perl - Practical Extraction and Report Language

  • NAME
  • SYNOPSIS
    • Overview
    • Tutorials
    • Reference Manual
    • Internals and C Language Interface
    • Miscellaneous
    • Language-Specific
    • Platform-Specific
  • DESCRIPTION
  • AVAILABILITY
  • ENVIRONMENT
  • AUTHOR
  • FILES
  • SEE ALSO
  • DIAGNOSTICS
  • BUGS
  • NOTES

NAME

perl - Practical Extraction and Report Language

SYNOPSIS

perl | [ -sTtuUWX ]
 | [ -hv ] [ -V[:configvar] ]
 | [ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
 | [ -pna ] [ -F pattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
 | [ -I dir ] [ -m[-]module ] [ -M[-]'module...' ] [ -f ]
 | [ -C [number/list] ]
 | [ -P ]
 | [ -S ]
 | [ -x[dir] ]
 | [ -i[extension] ]
 | [ -e 'command' ] [ -- ] [ programfile ] [ argument ]...

If you're new to Perl, you should start with the perlintro manpage, which is a general intro for beginners and provides some background to help you navigate the rest of Perl's extensive documentation.

For ease of access, the Perl manual has been split up into several sections.

Overview

    perl                Perl overview (this section)
    perlintro           Perl introduction for beginners
    perltoc             Perl documentation table of contents
    ActivePerl          ActivePerl overview

Tutorials

    perlreftut          Perl references short introduction
    perldsc             Perl data structures intro
    perllol             Perl data structures: arrays of arrays
    perlrequick         Perl regular expressions quick start
    perlretut           Perl regular expressions tutorial
    perlboot            Perl OO tutorial for beginners
    perltoot            Perl OO tutorial, part 1
    perltooc            Perl OO tutorial, part 2
    perlbot             Perl OO tricks and examples
    perlstyle           Perl style guide
    perlcheat           Perl cheat sheet
    perltrap            Perl traps for the unwary
    perldebtut          Perl debugging tutorial
    perlfaq             Perl frequently asked questions
      perlfaq1          General Questions About Perl
      perlfaq2          Obtaining and Learning about Perl
      perlfaq3          Programming Tools
      perlfaq4          Data Manipulation
      perlfaq5          Files and Formats
      perlfaq6          Regexes
      perlfaq7          Perl Language Issues
      perlfaq8          System Interaction
      perlfaq9          Networking

Reference Manual

    perlsyn             Perl syntax
    perldata            Perl data structures
    perlop              Perl operators and precedence
    perlsub             Perl subroutines
    perlfunc            Perl built-in functions
      perlopentut       Perl open() tutorial
      perlpacktut       Perl pack() and unpack() tutorial
    perlpod             Perl plain old documentation
    perlpodspec         Perl plain old documentation format specification
    perlrun             Perl execution and options
    perldiag            Perl diagnostic messages
    perllexwarn         Perl warnings and their control
    perldebug           Perl debugging
    perlvar             Perl predefined variables
    perlre              Perl regular expressions, the rest of the story
    perlreref           Perl regular expressions quick reference
    perlref             Perl references, the rest of the story
    perlform            Perl formats
    perlobj             Perl objects
    perltie             Perl objects hidden behind simple variables
      perldbmfilter     Perl DBM filters
    perlipc             Perl interprocess communication
    perlfork            Perl fork() information
    perlnumber          Perl number semantics
    perlthrtut          Perl threads tutorial
      perlothrtut       Old Perl threads tutorial
    perlport            Perl portability guide
    perllocale          Perl locale support
    perluniintro        Perl Unicode introduction
    perlunicode         Perl Unicode support
    perlebcdic          Considerations for running Perl on EBCDIC platforms
    perlsec             Perl security
    perlmod             Perl modules: how they work
    perlmodlib          Perl modules: how to write and use
    perlmodstyle        Perl modules: how to write modules with style
    perlmodinstall      Perl modules: how to install from CPAN
    perlnewmod          Perl modules: preparing a new module for distribution
    perlutil            utilities packaged with the Perl distribution
    perlcompile         Perl compiler suite intro
    perlfilter          Perl source filters
    perlglossary        Perl Glossary

Internals and C Language Interface

    perlembed           Perl ways to embed perl in your C or C++ application
    perldebguts         Perl debugging guts and tips
    perlxstut           Perl XS tutorial
    perlxs              Perl XS application programming interface
    perlclib            Internal replacements for standard C library functions
    perlguts            Perl internal functions for those doing extensions
    perlcall            Perl calling conventions from C
    perlapi             Perl API listing (autogenerated)
    perlintern          Perl internal functions (autogenerated)
    perliol             C API for Perl's implementation of IO in Layers
    perlapio            Perl internal IO abstraction interface
    perlhack            Perl hackers guide

Miscellaneous

    perlbook            Perl book information
    perltodo            Perl things to do
    perldoc             Look up Perl documentation in Pod format
    perlhist            Perl history records
    perldelta           Perl changes since previous version
    perl587delta        Perl changes in version 5.8.7
    perl586delta        Perl changes in version 5.8.6
    perl585delta        Perl changes in version 5.8.5
    perl584delta        Perl changes in version 5.8.4
    perl583delta        Perl changes in version 5.8.3
    perl582delta        Perl changes in version 5.8.2
    perl581delta        Perl changes in version 5.8.1
    perl58delta         Perl changes in version 5.8.0
    perl573delta        Perl changes in version 5.7.3
    perl572delta        Perl changes in version 5.7.2
    perl571delta        Perl changes in version 5.7.1
    perl570delta        Perl changes in version 5.7.0
    perl561delta        Perl changes in version 5.6.1
    perl56delta         Perl changes in version 5.6
    perl5005delta       Perl changes in version 5.005
    perl5004delta       Perl changes in version 5.004
    activeperl-release  Release notes for ActivePerl
    activeperl-changes  ActivePerl revision history
    perlartistic        Perl Artistic License
    perlgpl             GNU General Public License

Language-Specific

    perlcn              Perl for Simplified Chinese (in EUC-CN)
    perljp              Perl for Japanese (in EUC-JP)
    perlko              Perl for Korean (in EUC-KR)
    perltw              Perl for Traditional Chinese (in Big5)

Platform-Specific

    perlaix             Perl notes for AIX
    perlamiga           Perl notes for AmigaOS
    perlapollo          Perl notes for Apollo DomainOS
    perlbeos            Perl notes for BeOS
    perlbs2000          Perl notes for POSIX-BC BS2000
    perlce              Perl notes for WinCE
    perlcygwin          Perl notes for Cygwin
    perldgux            Perl notes for DG/UX
    perldos             Perl notes for DOS
    perlepoc            Perl notes for EPOC
    perlfreebsd         Perl notes for FreeBSD
    perlhpux            Perl notes for HP-UX
    perlhurd            Perl notes for Hurd
    perlirix            Perl notes for Irix
    perllinux           Perl notes for Linux
    perlmachten         Perl notes for Power MachTen
    perlmacos           Perl notes for Mac OS (Classic)
    perlmacosx          Perl notes for Mac OS X
    perlmint            Perl notes for MiNT
    perlmpeix           Perl notes for MPE/iX
    perlnetware         Perl notes for NetWare
    perlopenbsd         Perl notes for OpenBSD
    perlos2             Perl notes for OS/2
    perlos390           Perl notes for OS/390
    perlos400           Perl notes for OS/400
    perlplan9           Perl notes for Plan 9
    perlqnx             Perl notes for QNX
    perlsolaris         Perl notes for Solaris
    perltru64           Perl notes for Tru64
    perluts             Perl notes for UTS
    perlvmesa           Perl notes for VM/ESA
    perlvms             Perl notes for VMS
    perlvos             Perl notes for Stratus VOS
    perlwin32           Perl notes for Windows

By default, the manpages listed above are installed in the /usr/local/man/ directory.

Extensive additional documentation for Perl modules is available. The default configuration for perl will place this additional documentation in the /usr/local/lib/perl5/man directory (or else in the man subdirectory of the Perl library directory). Some of this additional documentation is distributed standard with Perl, but you'll also find documentation for third-party modules there.

You should be able to view Perl's documentation with your man(1) program by including the proper directories in the appropriate start-up files, or in the MANPATH environment variable. To find out where the configuration has installed the manpages, type:

    perl -V:man.dir

If the directories have a common stem, such as /usr/local/man/man1 and /usr/local/man/man3, you need only to add that stem (/usr/local/man) to your man(1) configuration files or your MANPATH environment variable. If they do not share a stem, you'll have to add both stems.

If that doesn't work for some reason, you can still use the supplied perldoc script to view module information. You might also look into getting a replacement man program.

If something strange has gone wrong with your program and you're not sure where you should look for help, try the -w switch first. It will often point out exactly where the trouble is.

DESCRIPTION

Perl is a language optimized for scanning arbitrary text files, extracting information from those text files, and printing reports based on that information. It's also a good language for many system management tasks. The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, elegant, minimal).

Perl combines (in the author's opinion, anyway) some of the best features of C, sed, awk, and sh, so people familiar with those languages should have little difficulty with it. (Language historians will also note some vestiges of csh, Pascal, and even BASIC-PLUS.) Expression syntax corresponds closely to C expression syntax. Unlike most Unix utilities, Perl does not arbitrarily limit the size of your data--if you've got the memory, Perl can slurp in your whole file as a single string. Recursion is of unlimited depth. And the tables used by hashes (sometimes called "associative arrays") grow as necessary to prevent degraded performance. Perl can use sophisticated pattern matching techniques to scan large amounts of data quickly. Although optimized for scanning text, Perl can also deal with binary data, and can make dbm files look like hashes. Setuid Perl scripts are safer than C programs through a dataflow tracing mechanism that prevents many stupid security holes.

If you have a problem that would ordinarily use sed or awk or sh, but it exceeds their capabilities or must run a little faster, and you don't want to write the silly thing in C, then Perl may be for you. There are also translators to turn your sed and awk scripts into Perl scripts.

But wait, there's more...

Begun in 1993 (see the perlhist manpage), Perl version 5 is nearly a complete rewrite that provides the following additional benefits:

  • modularity and reusability using innumerable modules

    Described in the perlmod manpage, the perlmodlib manpage, and the perlmodinstall manpage.

  • embeddable and extensible

    Described in the perlembed manpage, the perlxstut manpage, the perlxs manpage, the perlcall manpage, the perlguts manpage, and the xsubpp manpage.

  • roll-your-own magic variables (including multiple simultaneous DBM implementations)

    Described in the perltie manpage and the AnyDBM_File manpage.

  • subroutines can now be overridden, autoloaded, and prototyped

    Described in the perlsub manpage.

  • arbitrarily nested data structures and anonymous functions

    Described in the perlreftut manpage, the perlref manpage, the perldsc manpage, and the perllol manpage.

  • object-oriented programming

    Described in the perlobj manpage, the perlboot manpage, the perltoot manpage, the perltooc manpage, and the perlbot manpage.

  • support for light-weight processes (threads)

    Described in the perlthrtut manpage and the threads manpage.

  • support for Unicode, internationalization, and localization

    Described in the perluniintro manpage, the perllocale manpage and the Locale::Maketext manpage.

  • lexical scoping

    Described in the perlsub manpage.

  • regular expression enhancements

    Described in the perlre manpage, with additional examples in the perlop manpage.

  • enhanced debugger and interactive Perl environment, with integrated editor support

    Described in the perldebtut manpage, the perldebug manpage and the perldebguts manpage.

  • POSIX 1003.1 compliant library

    Described in the POSIX manpage.

Okay, that's definitely enough hype.

AVAILABILITY

Perl is available for most operating systems, including virtually all Unix-like platforms. See Supported Platforms in the perlport manpage for a listing.

ENVIRONMENT

See the perlrun manpage.

AUTHOR

Larry Wall <larry@wall.org>, with the help of oodles of other folks.

If your Perl success stories and testimonials may be of help to others who wish to advocate the use of Perl in their applications, or if you wish to simply express your gratitude to Larry and the Perl developers, please write to perl-thanks@perl.org .

FILES

 "@INC"                 locations of perl libraries

SEE ALSO

 a2p    awk to perl translator
 s2p    sed to perl translator
 http://www.perl.org/       the Perl homepage
 http://www.perl.com/       Perl articles (O'Reilly)
 http://www.cpan.org/       the Comprehensive Perl Archive
 http://www.pm.org/         the Perl Mongers

DIAGNOSTICS

The use warnings pragma (and the -w switch) produces some lovely diagnostics.

See the perldiag manpage for explanations of all Perl's diagnostics. The use diagnostics pragma automatically turns Perl's normally terse warnings and errors into these longer forms.

Compilation errors will tell you the line number of the error, with an indication of the next token or token type that was to be examined. (In a script passed to Perl via -e switches, each -e is counted as one line.)

Setuid scripts have additional constraints that can produce error messages such as "Insecure dependency". See the perlsec manpage.

Did we mention that you should definitely consider using the -w switch?

BUGS

The -w switch is not mandatory.

Perl is at the mercy of your machine's definitions of various operations such as type casting, atof(), and floating-point output with sprintf().

If your stdio requires a seek or eof between reads and writes on a particular stream, so does Perl. (This doesn't apply to sysread() and syswrite().)

While none of the built-in data types have any arbitrary size limits (apart from memory size), there are still a few arbitrary limits: a given variable name may not be longer than 251 characters. Line numbers displayed by diagnostics are internally stored as short integers, so they are limited to a maximum of 65535 (higher numbers usually being affected by wraparound).

You may mail your bug reports (be sure to include full configuration information as output by the myconfig program in the perl source tree, or by perl -V) to perlbug@perl.org . If you've succeeded in compiling perl, the perlbug script in the utils/ subdirectory can be used to help mail in a bug report.

Perl actually stands for Pathologically Eclectic Rubbish Lister, but don't tell anyone I said that.

NOTES

The Perl motto is "There's more than one way to do it." Divining how many more is left as an exercise to the reader.

The three principal virtues of a programmer are Laziness, Impatience, and Hubris. See the Camel Book for why.


perlintro -- a brief introduction and overview of Perl

  • DESCRIPTION
    • What is Perl?
    • Running Perl programs
    • Basic syntax overview
    • Perl variable types
    • Variable scoping
    • Conditional and looping constructs
    • Builtin operators and functions
    • Files and I/O
    • Regular expressions
    • Writing subroutines
    • OO Perl
    • Using Perl modules
  • AUTHOR

NAME

perlintro -- a brief introduction and overview of Perl

DESCRIPTION

This document is intended to give you a quick overview of the Perl programming language, along with pointers to further documentation. It is intended as a "bootstrap" guide for those who are new to the language, and provides just enough information for you to be able to read other peoples' Perl and understand roughly what it's doing, or write your own simple scripts.

This introductory document does not aim to be complete. It does not even aim to be entirely accurate. In some cases perfection has been sacrificed in the goal of getting the general idea across. You are strongly advised to follow this introduction with more information from the full Perl manual, the table of contents to which can be found in the perltoc manpage.

Throughout this document you'll see references to other parts of the Perl documentation. You can read that documentation using the perldoc command or whatever method you're using to read this document.

What is Perl?

Perl is a general-purpose programming language originally developed for text manipulation and now used for a wide range of tasks including system administration, web development, network programming, GUI development, and more.

The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, elegant, minimal). Its major features are that it's easy to use, supports both procedural and object-oriented (OO) programming, has powerful built-in support for text processing, and has one of the world's most impressive collections of third-party modules.

Different definitions of Perl are given in the perl manpage, the perlfaq1 manpage and no doubt other places. From this we can determine that Perl is different things to different people, but that lots of people think it's at least worth writing about.

Running Perl programs

To run a Perl program from the Unix command line:

    perl progname.pl

Alternatively, put this as the first line of your script:

    #!/usr/bin/env perl

... and run the script as /path/to/script.pl. Of course, it'll need to be executable first, so chmod 755 script.pl (under Unix).

For more information, including instructions for other platforms such as Windows and Mac OS, read the perlrun manpage.

Basic syntax overview

A Perl script or program consists of one or more statements. These statements are simply written in the script in a straightforward fashion. There is no need to have a main() function or anything of that kind.

Perl statements end in a semi-colon:

    print "Hello, world";

Comments start with a hash symbol and run to the end of the line

    # This is a comment

Whitespace is irrelevant:

    print
        "Hello, world"
        ;

... except inside quoted strings:

    # this would print with a linebreak in the middle
    print "Hello
    world";

Double quotes or single quotes may be used around literal strings:

    print "Hello, world";
    print 'Hello, world';

However, only double quotes "interpolate" variables and special characters such as newlines (\n):

    print "Hello, $name\n";     # works fine
    print 'Hello, $name\n';     # prints $name\n literally

Numbers don't need quotes around them:

    print 42;

You can use parentheses for functions' arguments or omit them according to your personal taste. They are only required occasionally to clarify issues of precedence.

    print("Hello, world\n");
    print "Hello, world\n";

More detailed information about Perl syntax can be found in the perlsyn manpage.

Perl variable types

Perl has three main variable types: scalars, arrays, and hashes.

Scalars

A scalar represents a single value:

    my $animal = "camel";
    my $answer = 42;

Scalar values can be strings, integers or floating point numbers, and Perl will automatically convert between them as required. There is no need to pre-declare your variable types.

Scalar values can be used in various ways:

    print $animal;
    print "The animal is $animal\n";
    print "The square of $answer is ", $answer * $answer, "\n";

There are a number of "magic" scalars with names that look like punctuation or line noise. These special variables are used for all kinds of purposes, and are documented in the perlvar manpage. The only one you need to know about for now is $_ which is the "default variable". It's used as the default argument to a number of functions in Perl, and it's set implicitly by certain looping constructs.

    print;          # prints contents of $_ by default
Arrays

An array represents a list of values:

    my @animals = ("camel", "llama", "owl");
    my @numbers = (23, 42, 69);
    my @mixed   = ("camel", 42, 1.23);

Arrays are zero-indexed. Here's how you get at elements in an array:

    print $animals[0];              # prints "camel"
    print $animals[1];              # prints "llama"

The special variable $#array tells you the index of the last element of an array:

    print $mixed[$#mixed];       # last element, prints 1.23

You might be tempted to use $#array + 1 to tell you how many items there are in an array. Don't bother. As it happens, using @array where Perl expects to find a scalar value ("in scalar context") will give you the number of elements in the array:

    if (@animals < 5) { ... }

The elements we're getting from the array start with a $ because we're getting just a single value out of the array -- you ask for a scalar, you get a scalar.

To get multiple values from an array:

    @animals[0,1];                  # gives ("camel", "llama");
    @animals[0..2];                 # gives ("camel", "llama", "owl");
    @animals[1..$#animals];         # gives all except the first element

This is called an "array slice".

You can do various useful things to lists:

    my @sorted    = sort @animals;
    my @backwards = reverse @numbers;

There are a couple of special arrays too, such as @ARGV (the command line arguments to your script) and @_ (the arguments passed to a subroutine). These are documented in the perlvar manpage.

Hashes

A hash represents a set of key/value pairs:

    my %fruit_color = ("apple", "red", "banana", "yellow");

You can use whitespace and the => operator to lay them out more nicely:

    my %fruit_color = (
        apple  => "red",
        banana => "yellow",
    );

To get at hash elements:

    $fruit_color{"apple"};           # gives "red"

You can get at lists of keys and values with keys() and values().

    my @fruits = keys %fruit_colors;
    my @colors = values %fruit_colors;

Hashes have no particular internal order, though you can sort the keys and loop through them.

Just like special scalars and arrays, there are also special hashes. The most well known of these is %ENV which contains environment variables. Read all about it (and other special variables) in the perlvar manpage.

Scalars, arrays and hashes are documented more fully in the perldata manpage.

More complex data types can be constructed using references, which allow you to build lists and hashes within lists and hashes.

A reference is a scalar value and can refer to any other Perl data type. So by storing a reference as the value of an array or hash element, you can easily create lists and hashes within lists and hashes. The following example shows a 2 level hash of hash structure using anonymous hash references.

    my $variables = {
        scalar  =>  {
                     description => "single item",
                     sigil => '$',
                    },
        array   =>  {
                     description => "ordered list of items",
                     sigil => '@',
                    },
        hash    =>  {
                     description => "key/value pairs",
                     sigil => '%',
                    },
    };

    print "Scalars begin with a $variables->{'scalar'}->{'sigil'}\n";

Exhaustive information on the topic of references can be found in the perlreftut manpage, the perllol manpage, the perlref manpage and the perldsc manpage.

Variable scoping

Throughout the previous section all the examples have used the syntax:

    my $var = "value";

The my is actually not required; you could just use:

    $var = "value";

However, the above usage will create global variables throughout your program, which is bad programming practice. my creates lexically scoped variables instead. The variables are scoped to the block (i.e. a bunch of statements surrounded by curly-braces) in which they are defined.

    my $a = "foo";
    if ($some_condition) {
        my $b = "bar";
        print $a;           # prints "foo"
        print $b;           # prints "bar"
    }
    print $a;               # prints "foo"
    print $b;               # prints nothing; $b has fallen out of scope

Using my in combination with a use strict; at the top of your Perl scripts means that the interpreter will pick up certain common programming errors. For instance, in the example above, the final print $b would cause a compile-time error and prevent you from running the program. Using strict is highly recommended.

Conditional and looping constructs

Perl has most of the usual conditional and looping constructs except for case/switch (but if you really want it, there is a Switch module in Perl 5.8 and newer, and on CPAN. See the section on modules, below, for more information about modules and CPAN).

The conditions can be any Perl expression. See the list of operators in the next section for information on comparison and boolean logic operators, which are commonly used in conditional statements.

if
    if ( condition ) {
        ...
    } elsif ( other condition ) {
        ...
    } else {
        ...
    }

There's also a negated version of it:

    unless ( condition ) {
        ...
    }

This is provided as a more readable version of if (!condition).

Note that the braces are required in Perl, even if you've only got one line in the block. However, there is a clever way of making your one-line conditional blocks more English like:

    # the traditional way
    if ($zippy) {
        print "Yow!";
    }

    # the Perlish post-condition way
    print "Yow!" if $zippy;
    print "We have no bananas" unless $bananas;
while
    while ( condition ) {
        ...
    }

There's also a negated version, for the same reason we have unless:

    until ( condition ) {
        ...
    }

You can also use while in a post-condition:

    print "LA LA LA\n" while 1;          # loops forever
for

Exactly like C:

    for ($i=0; $i <= $max; $i++) {
        ...
    }

The C style for loop is rarely needed in Perl since Perl provides the more friendly list scanning foreach loop.

foreach
    foreach (@array) {
        print "This element is $_\n";
    }

    # you don't have to use the default $_ either...
    foreach my $key (keys %hash) {
        print "The value of $key is $hash{$key}\n";
    }

For more detail on looping constructs (and some that weren't mentioned in this overview) see the perlsyn manpage.

Builtin operators and functions

Perl comes with a wide selection of builtin functions. Some of the ones we've already seen include print, sort and reverse. A list of them is given at the start of the perlfunc manpage and you can easily read about any given function by using perldoc -f functionname.

Perl operators are documented in full in the perlop manpage, but here are a few of the most common ones:

Arithmetic
    +   addition
    -   subtraction
    *   multiplication
    /   division
Numeric comparison
    ==  equality
    !=  inequality
    <   less than
    >   greater than
    <=  less than or equal
    >=  greater than or equal
String comparison
    eq  equality
    ne  inequality
    lt  less than
    gt  greater than
    le  less than or equal
    ge  greater than or equal

(Why do we have separate numeric and string comparisons? Because we don't have special variable types, and Perl needs to know whether to sort numerically (where 99 is less than 100) or alphabetically (where 100 comes before 99).

Boolean logic
    &&  and
    ||  or
    !   not

(and, or and not aren't just in the above table as descriptions of the operators -- they're also supported as operators in their own right. They're more readable than the C-style operators, but have different precedence to && and friends. Check the perlop manpage for more detail.)

Miscellaneous
    =   assignment
    .   string concatenation
    x   string multiplication
    ..  range operator (creates a list of numbers)

Many operators can be combined with a = as follows:

    $a += 1;        # same as $a = $a + 1
    $a -= 1;        # same as $a = $a - 1
    $a .= "\n";     # same as $a = $a . "\n";

Files and I/O

You can open a file for input or output using the open() function. It's documented in extravagant detail in the perlfunc manpage and the perlopentut manpage, but in short:

    open(INFILE,  "input.txt")   or die "Can't open input.txt: $!";
    open(OUTFILE, ">output.txt") or die "Can't open output.txt: $!";
    open(LOGFILE, ">>my.log")    or die "Can't open logfile: $!";

You can read from an open filehandle using the <> operator. In scalar context it reads a single line from the filehandle, and in list context it reads the whole file in, assigning each line to an element of the list:

    my $line  = <INFILE>;
    my @lines = <INFILE>;

Reading in the whole file at one time is called slurping. It can be useful but it may be a memory hog. Most text file processing can be done a line at a time with Perl's looping constructs.

The <> operator is most often seen in a while loop:

    while (<INFILE>) {     # assigns each line in turn to $_
        print "Just read in this line: $_";
    }

We've already seen how to print to standard output using print(). However, print() can also take an optional first argument specifying which filehandle to print to:

    print STDERR "This is your final warning.\n";
    print OUTFILE $record;
    print LOGFILE $logmessage;

When you're done with your filehandles, you should close() them (though to be honest, Perl will clean up after you if you forget):

    close INFILE;

Regular expressions

Perl's regular expression support is both broad and deep, and is the subject of lengthy documentation in the perlrequick manpage, the perlretut manpage, and elsewhere. However, in short:

Simple matching
    if (/foo/)       { ... }  # true if $_ contains "foo"
    if ($a =~ /foo/) { ... }  # true if $a contains "foo"

The // matching operator is documented in the perlop manpage. It operates on $_ by default, or can be bound to another variable using the =~ binding operator (also documented in the perlop manpage).

Simple substitution
    s/foo/bar/;               # replaces foo with bar in $_
    $a =~ s/foo/bar/;         # replaces foo with bar in $a
    $a =~ s/foo/bar/g;        # replaces ALL INSTANCES of foo with bar in $a

The s/// substitution operator is documented in the perlop manpage.

More complex regular expressions

You don't just have to match on fixed strings. In fact, you can match on just about anything you could dream of by using more complex regular expressions. These are documented at great length in the perlre manpage, but for the meantime, here's a quick cheat sheet:

    .                   a single character
    \s                  a whitespace character (space, tab, newline)
    \S                  non-whitespace character
    \d                  a digit (0-9)
    \D                  a non-digit
    \w                  a word character (a-z, A-Z, 0-9, _)
    \W                  a non-word character
    [aeiou]             matches a single character in the given set
    [^aeiou]            matches a single character outside the given set
    (foo|bar|baz)       matches any of the alternatives specified
    ^                   start of string
    $                   end of string

Quantifiers can be used to specify how many of the previous thing you want to match on, where "thing" means either a literal character, one of the metacharacters listed above, or a group of characters or metacharacters in parentheses.

    *                   zero or more of the previous thing
    +                   one or more of the previous thing
    ?                   zero or one of the previous thing
    {3}                 matches exactly 3 of the previous thing
    {3,6}               matches between 3 and 6 of the previous thing
    {3,}                matches 3 or more of the previous thing

Some brief examples:

    /^\d+/              string starts with one or more digits
    /^$/                nothing in the string (start and end are adjacent)
    /(\d\s){3}/         a three digits, each followed by a whitespace
                        character (eg "3 4 5 ")
    /(a.)+/             matches a string in which every odd-numbered letter
                        is a (eg "abacadaf")

    # This loop reads from STDIN, and prints non-blank lines:
    while (<>) {
        next if /^$/;
        print;
    }
Parentheses for capturing

As well as grouping, parentheses serve a second purpose. They can be used to capture the results of parts of the regexp match for later use. The results end up in $1, $2 and so on.

    # a cheap and nasty way to break an email address up into parts

    if ($email =~ /([^@]+)@(.+)/) {
        print "Username is $1\n";
        print "Hostname is $2\n";
    }
Other regexp features

Perl regexps also support backreferences, lookaheads, and all kinds of other complex details. Read all about them in the perlrequick manpage, the perlretut manpage, and the perlre manpage.

Writing subroutines

Writing subroutines is easy:

    sub log {
        my $logmessage = shift;
        print LOGFILE $logmessage;
    }

What's that shift? Well, the arguments to a subroutine are available to us as a special array called @_ (see the perlvar manpage for more on that). The default argument to the shift function just happens to be @_. So my $logmessage = shift; shifts the first item off the list of arguments and assigns it to $logmessage.

We can manipulate @_ in other ways too:

    my ($logmessage, $priority) = @_;       # common
    my $logmessage = $_[0];                 # uncommon, and ugly

Subroutines can also return values:

    sub square {
        my $num = shift;
        my $result = $num * $num;
        return $result;
    }

For more information on writing subroutines, see the perlsub manpage.

OO Perl

OO Perl is relatively simple and is implemented using references which know what sort of object they are based on Perl's concept of packages. However, OO Perl is largely beyond the scope of this document. Read the perlboot manpage, the perltoot manpage, the perltooc manpage and the perlobj manpage.

As a beginning Perl programmer, your most common use of OO Perl will be in using third-party modules, which are documented below.

Using Perl modules

Perl modules provide a range of features to help you avoid reinventing the wheel, and can be downloaded from CPAN ( http://www.cpan.org/ ). A number of popular modules are included with the Perl distribution itself.

Categories of modules range from text manipulation to network protocols to database integration to graphics. A categorized list of modules is also available from CPAN.

To learn how to install modules you download from CPAN, read the perlmodinstall manpage

To learn how to use a particular module, use perldoc Module::Name. Typically you will want to use Module::Name, which will then give you access to exported functions or an OO interface to the module.

the perlfaq manpage contains questions and answers related to many common tasks, and often provides suggestions for good CPAN modules to use.

the perlmod manpage describes Perl modules in general. the perlmodlib manpage lists the modules which came with your Perl installation.

If you feel the urge to write Perl modules, the perlnewmod manpage will give you good advice.

AUTHOR

Kirrily "Skud" Robert <skud@cpan.org>


perlglossary - Perl Glossary

    • A
    • B
    • C
    • D
    • E
    • F
    • G
    • H
    • I
    • J
    • K
    • L
    • M
    • N
    • O
    • P
    • Q
    • R
    • S
    • T
    • U
    • V
    • W
    • X
    • Y
    • Z
  • AUTHOR AND COPYRIGHT

NAME

perlglossary - Perl Glossary

DESCRIPTION

A glossary of terms (technical and otherwise) used in the Perl documentation. Other useful sources include the Free On-Line Dictionary of Computing http://foldoc.doc.ic.ac.uk/foldoc/index.html, the Jargon File http://catb.org/~esr/jargon/, and Wikipedia http://www.wikipedia.org/.

A

accessor methods

A method used to indirectly inspect or update an object's state (its instance variables).

actual arguments

The scalar values that you supply to a function or subroutine when you call it. For instance, when you call power("puff"), the string "puff" is the actual argument. See also argument and formal arguments.

address operator

Some languages work directly with the memory addresses of values, but this can be like playing with fire. Perl provides a set of asbestos gloves for handling all memory management. The closest to an address operator in Perl is the backslash operator, but it gives you a hard reference, which is much safer than a memory address.

algorithm

A well-defined sequence of steps, clearly enough explained that even a computer could do them.

alias

A nickname for something, which behaves in all ways as though you'd used the original name instead of the nickname. Temporary aliases are implicitly created in the loop variable for foreach loops, in the $_ variable for map or grep operators, in $a and $b during sort's comparison function, and in each element of @_ for the actual arguments of a subroutine call. Permanent aliases are explicitly created in packages by importing symbols or by assignment to typeglobs. Lexically scoped aliases for package variables are explicitly created by the our declaration.

alternatives

A list of possible choices from which you may select only one, as in "Would you like door A, B, or C?" Alternatives in regular expressions are separated with a single vertical bar: |. Alternatives in normal Perl expressions are separated with a double vertical bar: ||. Logical alternatives in Boolean expressions are separated with either || or or.

anonymous

Used to describe a referent that is not directly accessible through a named variable. Such a referent must be indirectly accessible through at least one hard reference. When the last hard reference goes away, the anonymous referent is destroyed without pity.

architecture

The kind of computer you're working on, where one "kind" of computer means all those computers sharing a compatible machine language. Since Perl programs are (typically) simple text files, not executable images, a Perl program is much less sensitive to the architecture it's running on than programs in other languages, such as C, that are compiled into machine code. See also platform and operating system.

argument

A piece of data supplied to a program, subroutine, function, or method to tell it what it's supposed to do. Also called a "parameter".

ARGV

The name of the array containing the argument vector from the command line. If you use the empty <> operator, ARGV is the name of both the filehandle used to traverse the arguments and the scalar containing the name of the current input file.

arithmetical operator

A symbol such as + or / that tells Perl to do the arithmetic you were supposed to learn in grade school.

array

An ordered sequence of values, stored such that you can easily access any of the values using an integer subscript that specifies the value's offset in the sequence.

array context

An archaic expression for what is more correctly referred to as list context.

ASCII

The American Standard Code for Information Interchange (a 7-bit character set adequate only for poorly representing English text). Often used loosely to describe the lowest 128 values of the various ISO-8859-X character sets, a bunch of mutually incompatible 8-bit codes best described as half ASCII. See also Unicode.

assertion

A component of a regular expression that must be true for the pattern to match but does not necessarily match any characters itself. Often used specifically to mean a zero width assertion.

assignment

An operator whose assigned mission in life is to change the value of a variable.

assignment operator

Either a regular assignment, or a compound operator composed of an ordinary assignment and some other operator, that changes the value of a variable in place, that is, relative to its old value. For example, $a += 2 adds 2 to $a.

associative array

See hash. Please.

associativity

Determines whether you do the left operator first or the right operator first when you have "A operator B operator C" and the two operators are of the same precedence. Operators like + are left associative, while operators like ** are right associative. See the perlop manpage for a list of operators and their associativity.

asynchronous

Said of events or activities whose relative temporal ordering is indeterminate because too many things are going on at once. Hence, an asynchronous event is one you didn't know when to expect.

atom

A regular expression component potentially matching a substring containing one or more characters and treated as an indivisible syntactic unit by any following quantifier. (Contrast with an assertion that matches something of zero width and may not be quantified.)

atomic operation

When Democritus gave the word "atom" to the indivisible bits of matter, he meant literally something that could not be cut: a- (not) + tomos (cuttable). An atomic operation is an action that can't be interrupted, not one forbidden in a nuclear-free zone.

attribute

A new feature that allows the declaration of variables and subroutines with modifiers as in sub foo : locked method. Also, another name for an instance variable of an object.

autogeneration

A feature of operator overloading of objects, whereby the behavior of certain operators can be reasonably deduced using more fundamental operators. This assumes that the overloaded operators will often have the same relationships as the regular operators. See the perlop manpage.

autoincrement

To add one to something automatically, hence the name of the ++ operator. To instead subtract one from something automatically is known as an "autodecrement".

autoload

To load on demand. (Also called "lazy" loading.) Specifically, to call an AUTOLOAD subroutine on behalf of an undefined subroutine.

autosplit

To split a string automatically, as the -a switch does when running under -p or -n in order to emulate awk. (See also the the AutoSplit manpage module, which has nothing to do with the -a switch, but a lot to do with autoloading.)

autovivification

A Greco-Roman word meaning "to bring oneself to life". In Perl, storage locations (lvalues) spontaneously generate themselves as needed, including the creation of any hard reference values to point to the next level of storage. The assignment $a[5][5][5][5][5] = "quintet" potentially creates five scalar storage locations, plus four references (in the first four scalar locations) pointing to four new anonymous arrays (to hold the last four scalar locations). But the point of autovivification is that you don't have to worry about it.

AV

Short for "array value", which refers to one of Perl's internal data types that holds an array. The AV type is a subclass of SV.

awk

Descriptive editing term--short for "awkward". Also coincidentally refers to a venerable text-processing language from which Perl derived some of its high-level ideas.

B

backreference

A substring captured by a subpattern within unadorned parentheses in a regex. Backslashed decimal numbers (\1, \2, etc.) later in the same pattern refer back to the corresponding subpattern in the current match. Outside the pattern, the numbered variables ($1, $2, etc.) continue to refer to these same values, as long as the pattern was the last successful match of the current dynamic scope.

backtracking

The practice of saying, "If I had to do it all over, I'd do it differently," and then actually going back and doing it all over differently. Mathematically speaking, it's returning from an unsuccessful recursion on a tree of possibilities. Perl backtracks when it attempts to match patterns with a regular expression, and its earlier attempts don't pan out. See Backtracking in the perlre manpage.

backward compatibility

Means you can still run your old program because we didn't break any of the features or bugs it was relying on.

bareword

A word sufficiently ambiguous to be deemed illegal under use strict 'subs'. In the absence of that stricture, a bareword is treated as if quotes were around it.

base class

A generic object type; that is, a class from which other, more specific classes are derived genetically by inheritance. Also called a "superclass" by people who respect their ancestors.

big-endian

From Swift: someone who eats eggs big end first. Also used of computers that store the most significant byte of a word at a lower byte address than the least significant byte. Often considered superior to little-endian machines. See also little-endian.

binary

Having to do with numbers represented in base 2. That means there's basically two numbers, 0 and 1. Also used to describe a "non-text file", presumably because such a file makes full use of all the binary bits in its bytes. With the advent of Unicode, this distinction, already suspect, loses even more of its meaning.

binary operator

An operator that takes two operands.

bind

To assign a specific network address to a socket.

bit

An integer in the range from 0 to 1, inclusive. The smallest possible unit of information storage. An eighth of a byte or of a dollar. (The term "Pieces of Eight" comes from being able to split the old Spanish dollar into 8 bits, each of which still counted for money. That's why a 25-cent piece today is still "two bits".)

bit shift

The movement of bits left or right in a computer word, which has the effect of multiplying or dividing by a power of 2.

bit string

A sequence of bits that is actually being thought of as a sequence of bits, for once.

bless

In corporate life, to grant official approval to a thing, as in, "The VP of Engineering has blessed our WebCruncher project." Similarly in Perl, to grant official approval to a referent so that it can function as an object, such as a WebCruncher object. See bless in the perlfunc manpage.

block

What a process does when it has to wait for something: "My process blocked waiting for the disk." As an unrelated noun, it refers to a large chunk of data, of a size that the operating system likes to deal with (normally a power of two such as 512 or 8192). Typically refers to a chunk of data that's coming from or going to a disk file.

BLOCK

A syntactic construct consisting of a sequence of Perl statements that is delimited by braces. The if and while statements are defined in terms of BLOCKs, for instance. Sometimes we also say "block" to mean a lexical scope; that is, a sequence of statements that act like a BLOCK, such as within an eval or a file, even though the statements aren't delimited by braces.

block buffering

A method of making input and output efficient by passing one block at a time. By default, Perl does block buffering to disk files. See buffer and command buffering.

Boolean

A value that is either true or false.

Boolean context

A special kind of scalar context used in conditionals to decide whether the scalar value returned by an expression is true or false. Does not evaluate as either a string or a number. See context.

breakpoint

A spot in your program where you've told the debugger to stop execution so you can poke around and see whether anything is wrong yet.

broadcast

To send a datagram to multiple destinations simultaneously.

BSD

A psychoactive drug, popular in the 80s, probably developed at U. C. Berkeley or thereabouts. Similar in many ways to the prescription-only medication called "System V", but infinitely more useful. (Or, at least, more fun.) The full chemical name is "Berkeley Standard Distribution".

bucket

A location in a hash table containing (potentially) multiple entries whose keys "hash" to the same hash value according to its hash function. (As internal policy, you don't have to worry about it, unless you're into internals, or policy.)

buffer

A temporary holding location for data. Block buffering means that the data is passed on to its destination whenever the buffer is full. Line buffering means that it's passed on whenever a complete line is received. Command buffering means that it's passed every time you do a print command (or equivalent). If your output is unbuffered, the system processes it one byte at a time without the use of a holding area. This can be rather inefficient.

built-in

A function that is predefined in the language. Even when hidden by overriding, you can always get at a built-in function by qualifying its name with the CORE:: pseudo-package.

bundle

A group of related modules on CPAN. (Also, sometimes refers to a group of command-line switches grouped into one switch cluster.)

byte

A piece of data worth eight bits in most places.

bytecode

A pidgin-like language spoken among 'droids when they don't wish to reveal their orientation (see endian). Named after some similar languages spoken (for similar reasons) between compilers and interpreters in the late 20th century. These languages are characterized by representing everything as a non-architecture-dependent sequence of bytes.

C

C

A language beloved by many for its inside-out type definitions, inscrutable precedence rules, and heavy overloading of the function-call mechanism. (Well, actually, people first switched to C because they found lowercase identifiers easier to read than upper.) Perl is written in C, so it's not surprising that Perl borrowed a few ideas from it.

C preprocessor

The typical C compiler's first pass, which processes lines beginning with # for conditional compilation and macro definition and does various manipulations of the program text based on the current definitions. Also known as cpp(1).

call by reference

An argument-passing mechanism in which the formal arguments refer directly to the actual arguments, and the subroutine can change the actual arguments by changing the formal arguments. That is, the formal argument is an alias for the actual argument. See also call by value.

call by value

An argument-passing mechanism in which the formal arguments refer to a copy of the actual arguments, and the subroutine cannot change the actual arguments by changing the formal arguments. See also call by reference.

callback

A handler that you register with some other part of your program in the hope that the other part of your program will trigger your handler when some event of interest transpires.

canonical

Reduced to a standard form to facilitate comparison.

capturing

The use of parentheses around a subpattern in a regular expression to store the matched substring as a backreference. (Captured strings are also returned as a list in list context.)

character

A small integer representative of a unit of orthography. Historically, characters were usually stored as fixed-width integers (typically in a byte, or maybe two, depending on the character set), but with the advent of UTF-8, characters are often stored in a variable number of bytes depending on the size of the integer that represents the character. Perl manages this transparently for you, for the most part.

character class

A square-bracketed list of characters used in a regular expression to indicate that any character of the set may occur at a given point. Loosely, any predefined set of characters so used.

character property

A predefined character class matchable by the \p metasymbol. Many standard properties are defined for Unicode.

circumfix operator

An operator that surrounds its operand, like the angle operator, or parentheses, or a hug.

class

A user-defined type, implemented in Perl via a package that provides (either directly or by inheritance) methods (that is, subroutines) to handle instances of the class (its objects). See also inheritance.

class method

A method whose invocant is a package name, not an object reference. A method associated with the class as a whole.

client

In networking, a process that initiates contact with a server process in order to exchange data and perhaps receive a service.

cloister

A cluster used to restrict the scope of a regular expression modifier.

closure

An anonymous subroutine that, when a reference to it is generated at run time, keeps track of the identities of externally visible lexical variables even after those lexical variables have supposedly gone out of scope. They're called "closures" because this sort of behavior gives mathematicians a sense of closure.

cluster

A parenthesized subpattern used to group parts of a regular expression into a single atom.

CODE

The word returned by the ref function when you apply it to a reference to a subroutine. See also CV.

code generator

A system that writes code for you in a low-level language, such as code to implement the backend of a compiler. See program generator.

code subpattern

A regular expression subpattern whose real purpose is to execute some Perl code, for example, the (?{...}) and (??{...}) subpatterns.

collating sequence

The order into which characters sort. This is used by string comparison routines to decide, for example, where in this glossary to put "collating sequence".

command

In shell programming, the syntactic combination of a program name and its arguments. More loosely, anything you type to a shell (a command interpreter) that starts it doing something. Even more loosely, a Perl statement, which might start with a label and typically ends with a semicolon.

command buffering

A mechanism in Perl that lets you store up the output of each Perl command and then flush it out as a single request to the operating system. It's enabled by setting the $| ($AUTOFLUSH) variable to a true value. It's used when you don't want data sitting around not going where it's supposed to, which may happen because the default on a file or pipe is to use block buffering.

command name

The name of the program currently executing, as typed on the command line. In C, the command name is passed to the program as the first command-line argument. In Perl, it comes in separately as $0.

command-line arguments

The values you supply along with a program name when you tell a shell to execute a command. These values are passed to a Perl program through @ARGV.

comment

A remark that doesn't affect the meaning of the program. In Perl, a comment is introduced by a # character and continues to the end of the line.

compilation unit

The file (or string, in the case of eval) that is currently being compiled.

compile phase

Any time before Perl starts running your main program. See also run phase. Compile phase is mostly spent in compile time, but may also be spent in run time when BEGIN blocks, use declarations, or constant subexpressions are being evaluated. The startup and import code of any use declaration is also run during compile phase.

compile time

The time when Perl is trying to make sense of your code, as opposed to when it thinks it knows what your code means and is merely trying to do what it thinks your code says to do, which is run time.

compiler

Strictly speaking, a program that munches up another program and spits out yet another file containing the program in a "more executable" form, typically containing native machine instructions. The perl program is not a compiler by this definition, but it does contain a kind of compiler that takes a program and turns it into a more executable form (syntax trees) within the perl process itself, which the interpreter then interprets. There are, however, extension modules to get Perl to act more like a "real" compiler. See the O manpage.

composer

A "constructor" for a referent that isn't really an object, like an anonymous array or a hash (or a sonata, for that matter). For example, a pair of braces acts as a composer for a hash, and a pair of brackets acts as a composer for an array. See Making References in the perlref manpage.

concatenation

The process of gluing one cat's nose to another cat's tail. Also, a similar operation on two strings.

conditional

Something "iffy". See Boolean context.

connection

In telephony, the temporary electrical circuit between the caller's and the callee's phone. In networking, the same kind of temporary circuit between a client and a server.

construct

As a noun, a piece of syntax made up of smaller pieces. As a transitive verb, to create an object using a constructor.

constructor

Any class method, instance method, or subroutine that composes, initializes, blesses, and returns an object. Sometimes we use the term loosely to mean a composer.

context

The surroundings, or environment. The context given by the surrounding code determines what kind of data a particular expression is expected to return. The three primary contexts are list context, scalar context, and void context. Scalar context is sometimes subdivided into Boolean context, numeric context, string context, and void context. There's also a "don't care" scalar context (which is dealt with in Programming Perl, Third Edition, Chapter 2, "Bits and Pieces" if you care).

continuation

The treatment of more than one physical line as a single logical line. Makefile lines are continued by putting a backslash before the newline. Mail headers as defined by RFC 822 are continued by putting a space or tab after the newline. In general, lines in Perl do not need any form of continuation mark, because whitespace (including newlines) is gleefully ignored. Usually.

core dump

The corpse of a process, in the form of a file left in the working directory of the process, usually as a result of certain kinds of fatal error.

CPAN

The Comprehensive Perl Archive Network. (See What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? in the perlfaq2 manpage).

cracker

Someone who breaks security on computer systems. A cracker may be a true hacker or only a script kiddie.

current package

The package in which the current statement is compiled. Scan backwards in the text of your program through the current lexical scope or any enclosing lexical scopes till you find a package declaration. That's your current package name.

current working directory

See working directory.

currently selected output channel

The last filehandle that was designated with select(FILEHANDLE); STDOUT, if no filehandle has been selected.

CV

An internal "code value" typedef, holding a subroutine. The CV type is a subclass of SV.

D

dangling statement

A bare, single statement, without any braces, hanging off an if or while conditional. C allows them. Perl doesn't.

data structure

How your various pieces of data relate to each other and what shape they make when you put them all together, as in a rectangular table or a triangular-shaped tree.

data type

A set of possible values, together with all the operations that know how to deal with those values. For example, a numeric data type has a certain set of numbers that you can work with and various mathematical operations that you can do on the numbers but would make little sense on, say, a string such as "Kilroy". Strings have their own operations, such as concatenation. Compound types made of a number of smaller pieces generally have operations to compose and decompose them, and perhaps to rearrange them. Objects that model things in the real world often have operations that correspond to real activities. For instance, if you model an elevator, your elevator object might have an open_door() method.

datagram

A packet of data, such as a UDP message, that (from the viewpoint of the programs involved) can be sent independently over the network. (In fact, all packets are sent independently at the IP level, but stream protocols such as TCP hide this from your program.)

DBM

Stands for "Data Base Management" routines, a set of routines that emulate an associative array using disk files. The routines use a dynamic hashing scheme to locate any entry with only two disk accesses. DBM files allow a Perl program to keep a persistent hash across multiple invocations. You can tie your hash variables to various DBM implementations--see the AnyDBM_File manpage and DB_File.

declaration

An assertion that states something exists and perhaps describes what it's like, without giving any commitment as to how or where you'll use it. A declaration is like the part of your recipe that says, "two cups flour, one large egg, four or five tadpoles..." See statement for its opposite. Note that some declarations also function as statements. Subroutine declarations also act as definitions if a body is supplied.

decrement

To subtract a value from a variable, as in "decrement $x" (meaning to remove 1 from its value) or "decrement $x by 3".

default

A value chosen for you if you don't supply a value of your own.

defined

Having a meaning. Perl thinks that some of the things people try to do are devoid of meaning, in particular, making use of variables that have never been given a value and performing certain operations on data that isn't there. For example, if you try to read data past the end of a file, Perl will hand you back an undefined value. See also false and defined in the perlfunc manpage.

delimiter

A character or string that sets bounds to an arbitrarily-sized textual object, not to be confused with a separator or terminator. "To delimit" really just means "to surround" or "to enclose" (like these parentheses are doing).

dereference

A fancy computer science term meaning "to follow a reference to what it points to". The "de" part of it refers to the fact that you're taking away one level of indirection.

derived class

A class that defines some of its methods in terms of a more generic class, called a base class. Note that classes aren't classified exclusively into base classes or derived classes: a class can function as both a derived class and a base class simultaneously, which is kind of classy.

descriptor

See file descriptor.

destroy

To deallocate the memory of a referent (first triggering its DESTROY method, if it has one).

destructor

A special method that is called when an object is thinking about destroying itself. A Perl program's DESTROY method doesn't do the actual destruction; Perl just triggers the method in case the class wants to do any associated cleanup.

device

A whiz-bang hardware gizmo (like a disk or tape drive or a modem or a joystick or a mouse) attached to your computer, that the operating system tries to make look like a file (or a bunch of files). Under Unix, these fake files tend to live in the /dev directory.

directive

A pod directive. See the perlpod manpage.

directory

A special file that contains other files. Some operating systems call these "folders", "drawers", or "catalogs".

directory handle

A name that represents a particular instance of opening a directory to read it, until you close it. See the opendir function.

dispatch

To send something to its correct destination. Often used metaphorically to indicate a transfer of programmatic control to a destination selected algorithmically, often by lookup in a table of function references or, in the case of object methods, by traversing the inheritance tree looking for the most specific definition for the method.

distribution

A standard, bundled release of a system of software. The default usage implies source code is included. If that is not the case, it will be called a "binary-only" distribution.

dweomer

An enchantment, illusion, phantasm, or jugglery. Said when Perl's magical dwimmer effects don't do what you expect, but rather seem to be the product of arcane dweomercraft, sorcery, or wonder working. [From Old English]

dwimmer

DWIM is an acronym for "Do What I Mean", the principle that something should just do what you want it to do without an undue amount of fuss. A bit of code that does "dwimming" is a "dwimmer". Dwimming can require a great deal of behind-the-scenes magic, which (if it doesn't stay properly behind the scenes) is called a dweomer instead.

dynamic scoping

Dynamic scoping works over a dynamic scope, making variables visible throughout the rest of the block in which they are first used and in any subroutines that are called by the rest of the block. Dynamically scoped variables can have their values temporarily changed (and implicitly restored later) by a local operator. (Compare lexical scoping.) Used more loosely to mean how a subroutine that is in the middle of calling another subroutine "contains" that subroutine at run time.

E

eclectic

Derived from many sources. Some would say too many.

element

A basic building block. When you're talking about an array, it's one of the items that make up the array.

embedding

When something is contained in something else, particularly when that might be considered surprising: "I've embedded a complete Perl interpreter in my editor!"

empty subclass test

The notion that an empty derived class should behave exactly like its base class.

en passant

When you change a value as it is being copied. [From French, "in passing", as in the exotic pawn-capturing maneuver in chess.]

encapsulation

The veil of abstraction separating the interface from the implementation (whether enforced or not), which mandates that all access to an object's state be through methods alone.

endian

See little-endian and big-endian.

environment

The collective set of environment variables your process inherits from its parent. Accessed via %ENV.

environment variable

A mechanism by which some high-level agent such as a user can pass its preferences down to its future offspring (child processes, grandchild processes, great-grandchild processes, and so on). Each environment variable is a key/value pair, like one entry in a hash.

EOF

End of File. Sometimes used metaphorically as the terminating string of a here document.

errno

The error number returned by a syscall when it fails. Perl refers to the error by the name $! (or $OS_ERROR if you use the English module).

error

See exception or fatal error.

escape sequence

See metasymbol.

exception

A fancy term for an error. See fatal error.

exception handling

The way a program responds to an error. The exception handling mechanism in Perl is the eval operator.

exec

To throw away the current process's program and replace it with another without exiting the process or relinquishing any resources held (apart from the old memory image).

executable file

A file that is specially marked to tell the operating system that it's okay to run this file as a program. Usually shortened to "executable".

execute

To run a program or subroutine. (Has nothing to do with the kill built-in, unless you're trying to run a signal handler.)

execute bit

The special mark that tells the operating system it can run this program. There are actually three execute bits under Unix, and which bit gets used depends on whether you own the file singularly, collectively, or not at all.

exit status

See status.

export

To make symbols from a module available for import by other modules.

expression

Anything you can legally say in a spot where a value is required. Typically composed of literals, variables, operators, functions, and subroutine calls, not necessarily in that order.

extension

A Perl module that also pulls in compiled C or C++ code. More generally, any experimental option that can be compiled into Perl, such as multithreading.

F

false

In Perl, any value that would look like "" or "0" if evaluated in a string context. Since undefined values evaluate to "", all undefined values are false, but not all false values are undefined.

FAQ

Frequently Asked Question (although not necessarily frequently answered, especially if the answer appears in the Perl FAQ shipped standard with Perl).

fatal error

An uncaught exception, which causes termination of the process after printing a message on your standard error stream. Errors that happen inside an eval are not fatal. Instead, the eval terminates after placing the exception message in the $@ ($EVAL_ERROR) variable. You can try to provoke a fatal error with the die operator (known as throwing or raising an exception), but this may be caught by a dynamically enclosing eval. If not caught, the die becomes a fatal error.

field

A single piece of numeric or string data that is part of a longer string, record, or line. Variable-width fields are usually split up by separators (so use split to extract the fields), while fixed-width fields are usually at fixed positions (so use unpack). Instance variables are also known as fields.

FIFO

First In, First Out. See also LIFO. Also, a nickname for a named pipe.

file

A named collection of data, usually stored on disk in a directory in a filesystem. Roughly like a document, if you're into office metaphors. In modern filesystems, you can actually give a file more than one name. Some files have special properties, like directories and devices.

file descriptor

The little number the operating system uses to keep track of which opened file you're talking about. Perl hides the file descriptor inside a standard I/O stream and then attaches the stream to a filehandle.

file test operator

A built-in unary operator that you use to determine whether something is true about a file, such as -o $filename to test whether you're the owner of the file.

fileglob

A "wildcard" match on filenames. See the glob function.

filehandle

An identifier (not necessarily related to the real name of a file) that represents a particular instance of opening a file until you close it. If you're going to open and close several different files in succession, it's fine to open each of them with the same filehandle, so you don't have to write out separate code to process each file.

filename

One name for a file. This name is listed in a directory, and you can use it in an open to tell the operating system exactly which file you want to open, and associate the file with a filehandle which will carry the subsequent identity of that file in your program, until you close it.

filesystem

A set of directories and files residing on a partition of the disk. Sometimes known as a "partition". You can change the file's name or even move a file around from directory to directory within a filesystem without actually moving the file itself, at least under Unix.

filter

A program designed to take a stream of input and transform it into a stream of output.

flag

We tend to avoid this term because it means so many things. It may mean a command-line switch that takes no argument itself (such as Perl's -n and -p flags) or, less frequently, a single-bit indicator (such as the O_CREAT and O_EXCL flags used in sysopen).

floating point

A method of storing numbers in "scientific notation", such that the precision of the number is independent of its magnitude (the decimal point "floats"). Perl does its numeric work with floating-point numbers (sometimes called "floats"), when it can't get away with using integers. Floating-point numbers are mere approximations of real numbers.

flush

The act of emptying a buffer, often before it's full.

FMTEYEWTK

Far More Than Everything You Ever Wanted To Know. An exhaustive treatise on one narrow topic, something of a super-FAQ. See Tom for far more.

fork

To create a child process identical to the parent process at its moment of conception, at least until it gets ideas of its own. A thread with protected memory.

formal arguments

The generic names by which a subroutine knows its arguments. In many languages, formal arguments are always given individual names, but in Perl, the formal arguments are just the elements of an array. The formal arguments to a Perl program are $ARGV[0], $ARGV[1], and so on. Similarly, the formal arguments to a Perl subroutine are $_[0], $_[1], and so on. You may give the arguments individual names by assigning the values to a my list. See also actual arguments.

format

A specification of how many spaces and digits and things to put somewhere so that whatever you're printing comes out nice and pretty.

freely available

Means you don't have to pay money to get it, but the copyright on it may still belong to someone else (like Larry).

freely redistributable

Means you're not in legal trouble if you give a bootleg copy of it to your friends and we find out about it. In fact, we'd rather you gave a copy to all your friends.

freeware

Historically, any software that you give away, particularly if you make the source code available as well. Now often called open source software. Recently there has been a trend to use the term in contradistinction to open source software, to refer only to free software released under the Free Software Foundation's GPL (General Public License), but this is difficult to justify etymologically.

function

Mathematically, a mapping of each of a set of input values to a particular output value. In computers, refers to a subroutine or operator that returns a value. It may or may not have input values (called arguments).

funny character

Someone like Larry, or one of his peculiar friends. Also refers to the strange prefixes that Perl requires as noun markers on its variables.

garbage collection

A misnamed feature--it should be called, "expecting your mother to pick up after you". Strictly speaking, Perl doesn't do this, but it relies on a reference-counting mechanism to keep things tidy. However, we rarely speak strictly and will often refer to the reference-counting scheme as a form of garbage collection. (If it's any comfort, when your interpreter exits, a "real" garbage collector runs to make sure everything is cleaned up if you've been messy with circular references and such.)

G

GID

Group ID--in Unix, the numeric group ID that the operating system uses to identify you and members of your group.

glob

Strictly, the shell's * character, which will match a "glob" of characters when you're trying to generate a list of filenames. Loosely, the act of using globs and similar symbols to do pattern matching. See also fileglob and typeglob.

global

Something you can see from anywhere, usually used of variables and subroutines that are visible everywhere in your program. In Perl, only certain special variables are truly global--most variables (and all subroutines) exist only in the current package. Global variables can be declared with our. See our in the perlfunc manpage.

global destruction

The garbage collection of globals (and the running of any associated object destructors) that takes place when a Perl interpreter is being shut down. Global destruction should not be confused with the Apocalypse, except perhaps when it should.

glue language

A language such as Perl that is good at hooking things together that weren't intended to be hooked together.

granularity

The size of the pieces you're dealing with, mentally speaking.

greedy

A subpattern whose quantifier wants to match as many things as possible.

grep

Originally from the old Unix editor command for "Globally search for a Regular Expression and Print it", now used in the general sense of any kind of search, especially text searches. Perl has a built-in grep function that searches a list for elements matching any given criterion, whereas the grep(1) program searches for lines matching a regular expression in one or more files.

group

A set of users of which you are a member. In some operating systems (like Unix), you can give certain file access permissions to other members of your group.

GV

An internal "glob value" typedef, holding a typeglob. The GV type is a subclass of SV.

H

hacker

Someone who is brilliantly persistent in solving technical problems, whether these involve golfing, fighting orcs, or programming. Hacker is a neutral term, morally speaking. Good hackers are not to be confused with evil crackers or clueless script kiddies. If you confuse them, we will presume that you are either evil or clueless.

handler

A subroutine or method that is called by Perl when your program needs to respond to some internal event, such as a signal, or an encounter with an operator subject to operator overloading. See also callback.

hard reference

A scalar value containing the actual address of a referent, such that the referent's reference count accounts for it. (Some hard references are held internally, such as the implicit reference from one of a typeglob's variable slots to its corresponding referent.) A hard reference is different from a symbolic reference.

hash

An unordered association of key/value pairs, stored such that you can easily use a string key to look up its associated data value. This glossary is like a hash, where the word to be defined is the key, and the definition is the value. A hash is also sometimes septisyllabically called an "associative array", which is a pretty good reason for simply calling it a "hash" instead.

hash table

A data structure used internally by Perl for implementing associative arrays (hashes) efficiently. See also bucket.

header file

A file containing certain required definitions that you must include "ahead" of the rest of your program to do certain obscure operations. A C header file has a .h extension. Perl doesn't really have header files, though historically Perl has sometimes used translated .h files with a .ph extension. See require in the perlfunc manpage. (Header files have been superseded by the module mechanism.)

here document

So called because of a similar construct in shells that pretends that the lines following the command are a separate file to be fed to the command, up to some terminating string. In Perl, however, it's just a fancy form of quoting.

hexadecimal

A number in base 16, "hex" for short. The digits for 10 through 16 are customarily represented by the letters a through f. Hexadecimal constants in Perl start with 0x. See also hex in the perlfunc manpage.

home directory

The directory you are put into when you log in. On a Unix system, the name is often placed into $ENV{HOME} or $ENV{LOGDIR} by login, but you can also find it with (getpwuid($<))[7]. (Some platforms do not have a concept of a home directory.)

host

The computer on which a program or other data resides.

hubris

Excessive pride, the sort of thing Zeus zaps you for. Also the quality that makes you write (and maintain) programs that other people won't want to say bad things about. Hence, the third great virtue of a programmer. See also laziness and impatience.

HV

Short for a "hash value" typedef, which holds Perl's internal representation of a hash. The HV type is a subclass of SV.

I

identifier

A legally formed name for most anything in which a computer program might be interested. Many languages (including Perl) allow identifiers that start with a letter and contain letters and digits. Perl also counts the underscore character as a valid letter. (Perl also has more complicated names, such as qualified names.)

impatience

The anger you feel when the computer is being lazy. This makes you write programs that don't just react to your needs, but actually anticipate them. Or at least that pretend to. Hence, the second great virtue of a programmer. See also laziness and hubris.

implementation

How a piece of code actually goes about doing its job. Users of the code should not count on implementation details staying the same unless they are part of the published interface.

import

To gain access to symbols that are exported from another module. See use in the perlfunc manpage.

increment

To increase the value of something by 1 (or by some other number, if so specified).

indexing

In olden days, the act of looking up a key in an actual index (such as a phone book), but now merely the act of using any kind of key or position to find the corresponding value, even if no index is involved. Things have degenerated to the point that Perl's index function merely locates the position (index) of one string in another.

indirect filehandle

An expression that evaluates to something that can be used as a filehandle: a string (filehandle name), a typeglob, a typeglob reference, or a low-level IO object.

indirect object

In English grammar, a short noun phrase between a verb and its direct object indicating the beneficiary or recipient of the action. In Perl, print STDOUT "$foo\n"; can be understood as "verb indirect-object object" where STDOUT is the recipient of the print action, and "$foo" is the object being printed. Similarly, when invoking a method, you might place the invocant between the method and its arguments:

  $gollum = new Pathetic::Creature "Smeagol";
  give $gollum "Fisssssh!";
  give $gollum "Precious!";
indirect object slot

The syntactic position falling between a method call and its arguments when using the indirect object invocation syntax. (The slot is distinguished by the absence of a comma between it and the next argument.) STDERR is in the indirect object slot here:

  print STDERR "Awake!  Awake!  Fear, Fire,
      Foes!  Awake!\n";
indirection

If something in a program isn't the value you're looking for but indicates where the value is, that's indirection. This can be done with either symbolic references or hard references.

infix

An operator that comes in between its operands, such as multiplication in 24 * 7.

inheritance

What you get from your ancestors, genetically or otherwise. If you happen to be a class, your ancestors are called base classes and your descendants are called derived classes. See single inheritance and multiple inheritance.

instance

Short for "an instance of a class", meaning an object of that class.

instance variable

An attribute of an object; data stored with the particular object rather than with the class as a whole.

integer

A number with no fractional (decimal) part. A counting number, like 1, 2, 3, and so on, but including 0 and the negatives.

interface

The services a piece of code promises to provide forever, in contrast to its implementation, which it should feel free to change whenever it likes.

interpolation

The insertion of a scalar or list value somewhere in the middle of another value, such that it appears to have been there all along. In Perl, variable interpolation happens in double-quoted strings and patterns, and list interpolation occurs when constructing the list of values to pass to a list operator or other such construct that takes a LIST.

interpreter

Strictly speaking, a program that reads a second program and does what the second program says directly without turning the program into a different form first, which is what compilers do. Perl is not an interpreter by this definition, because it contains a kind of compiler that takes a program and turns it into a more executable form (syntax trees) within the perl process itself, which the Perl run time system then interprets.

invocant

The agent on whose behalf a method is invoked. In a class method, the invocant is a package name. In an instance method, the invocant is an object reference.

invocation

The act of calling up a deity, daemon, program, method, subroutine, or function to get it do what you think it's supposed to do. We usually "call" subroutines but "invoke" methods, since it sounds cooler.

I/O

Input from, or output to, a file or device.

IO

An internal I/O object. Can also mean indirect object.

IP

Internet Protocol, or Intellectual Property.

IPC

Interprocess Communication.

is-a

A relationship between two objects in which one object is considered to be a more specific version of the other, generic object: "A camel is a mammal." Since the generic object really only exists in a Platonic sense, we usually add a little abstraction to the notion of objects and think of the relationship as being between a generic base class and a specific derived class. Oddly enough, Platonic classes don't always have Platonic relationships--see inheritance.

iteration

Doing something repeatedly.

iterator

A special programming gizmo that keeps track of where you are in something that you're trying to iterate over. The foreach loop in Perl contains an iterator; so does a hash, allowing you to each through it.

IV

The integer four, not to be confused with six, Tom's favorite editor. IV also means an internal Integer Value of the type a scalar can hold, not to be confused with an NV.

J

JAPH

"Just Another Perl Hacker," a clever but cryptic bit of Perl code that when executed, evaluates to that string. Often used to illustrate a particular Perl feature, and something of an ungoing Obfuscated Perl Contest seen in Usenix signatures.

K

key

The string index to a hash, used to look up the value associated with that key.

keyword

See reserved words.

L

label

A name you give to a statement so that you can talk about that statement elsewhere in the program.

laziness

The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful, and document what you wrote so you don't have to answer so many questions about it. Hence, the first great virtue of a programmer. Also hence, this book. See also impatience and hubris.

left shift

A bit shift that multiplies the number by some power of 2.

leftmost longest

The preference of the regular expression engine to match the leftmost occurrence of a pattern, then given a position at which a match will occur, the preference for the longest match (presuming the use of a greedy quantifier). See the perlre manpage for much more on this subject.

lexeme

Fancy term for a token.

lexer

Fancy term for a tokener.

lexical analysis

Fancy term for tokenizing.

lexical scoping

Looking at your Oxford English Dictionary through a microscope. (Also known as static scoping, because dictionaries don't change very fast.) Similarly, looking at variables stored in a private dictionary (namespace) for each scope, which are visible only from their point of declaration down to the end of the lexical scope in which they are declared. --Syn. static scoping. --Ant. dynamic scoping.

lexical variable

A variable subject to lexical scoping, declared by my. Often just called a "lexical". (The our declaration declares a lexically scoped name for a global variable, which is not itself a lexical variable.)

library

Generally, a collection of procedures. In ancient days, referred to a collection of subroutines in a .pl file. In modern times, refers more often to the entire collection of Perl modules on your system.

LIFO

Last In, First Out. See also FIFO. A LIFO is usually called a stack.

line

In Unix, a sequence of zero or more non-newline characters terminated with a newline character. On non-Unix machines, this is emulated by the C library even if the underlying operating system has different ideas.

line buffering

Used by a standard I/O output stream that flushes its buffer after every newline. Many standard I/O libraries automatically set up line buffering on output that is going to the terminal.

line number

The number of lines read previous to this one, plus 1. Perl keeps a separate line number for each source or input file it opens. The current source file's line number is represented by __LINE__. The current input line number (for the file that was most recently read via <FH>) is represented by the $. ($INPUT_LINE_NUMBER) variable. Many error messages report both values, if available.

link

Used as a noun, a name in a directory, representing a file. A given file can have multiple links to it. It's like having the same phone number listed in the phone directory under different names. As a verb, to resolve a partially compiled file's unresolved symbols into a (nearly) executable image. Linking can generally be static or dynamic, which has nothing to do with static or dynamic scoping.

LIST

A syntactic construct representing a comma-separated list of expressions, evaluated to produce a list value. Each expression in a LIST is evaluated in list context and interpolated into the list value.

list

An ordered set of scalar values.

list context

The situation in which an expression is expected by its surroundings (the code calling it) to return a list of values rather than a single value. Functions that want a LIST of arguments tell those arguments that they should produce a list value. See also context.

list operator

An operator that does something with a list of values, such as join or grep. Usually used for named built-in operators (such as print, unlink, and system) that do not require parentheses around their argument list.

list value

An unnamed list of temporary scalar values that may be passed around within a program from any list-generating function to any function or construct that provides a list context.

literal

A token in a programming language such as a number or string that gives you an actual value instead of merely representing possible values as a variable does.

little-endian

From Swift: someone who eats eggs little end first. Also used of computers that store the least significant byte of a word at a lower byte address than the most significant byte. Often considered superior to big-endian machines. See also big-endian.

local

Not meaning the same thing everywhere. A global variable in Perl can be localized inside a dynamic scope via the local operator.

logical operator

Symbols representing the concepts "and", "or", "xor", and "not".

lookahead

An assertion that peeks at the string to the right of the current match location.

lookbehind

An assertion that peeks at the string to the left of the current match location.

loop

A construct that performs something repeatedly, like a roller coaster.

loop control statement

Any statement within the body of a loop that can make a loop prematurely stop looping or skip an iteration. Generally you shouldn't try this on roller coasters.

loop label

A kind of key or name attached to a loop (or roller coaster) so that loop control statements can talk about which loop they want to control.

lvaluable

Able to serve as an lvalue.

lvalue

Term used by language lawyers for a storage location you can assign a new value to, such as a variable or an element of an array. The "l" is short for "left", as in the left side of an assignment, a typical place for lvalues. An lvaluable function or expression is one to which a value may be assigned, as in pos($x) = 10.

lvalue modifier

An adjectival pseudofunction that warps the meaning of an lvalue in some declarative fashion. Currently there are three lvalue modifiers: my, our, and local.

M

magic

Technically speaking, any extra semantics attached to a variable such as $!, $0, %ENV, or %SIG, or to any tied variable. Magical things happen when you diddle those variables.

magical increment

An increment operator that knows how to bump up alphabetics as well as numbers.

magical variables

Special variables that have side effects when you access them or assign to them. For example, in Perl, changing elements of the %ENV array also changes the corresponding environment variables that subprocesses will use. Reading the $! variable gives you the current system error number or message.

Makefile

A file that controls the compilation of a program. Perl programs don't usually need a Makefile because the Perl compiler has plenty of self-control.

man

The Unix program that displays online documentation (manual pages) for you.

manpage

A "page" from the manuals, typically accessed via the man(1) command. A manpage contains a SYNOPSIS, a DESCRIPTION, a list of BUGS, and so on, and is typically longer than a page. There are manpages documenting commands, syscalls, library functions, devices, protocols, files, and such. In this book, we call any piece of standard Perl documentation (like perlop or perldelta) a manpage, no matter what format it's installed in on your system.

matching

See pattern matching.

member data

See instance variable.

memory

This always means your main memory, not your disk. Clouding the issue is the fact that your machine may implement virtual memory; that is, it will pretend that it has more memory than it really does, and it'll use disk space to hold inactive bits. This can make it seem like you have a little more memory than you really do, but it's not a substitute for real memory. The best thing that can be said about virtual memory is that it lets your performance degrade gradually rather than suddenly when you run out of real memory. But your program can die when you run out of virtual memory too, if you haven't thrashed your disk to death first.

metacharacter

A character that is not supposed to be treated normally. Which characters are to be treated specially as metacharacters varies greatly from context to context. Your shell will have certain metacharacters, double-quoted Perl strings have other metacharacters, and regular expression patterns have all the double-quote metacharacters plus some extra ones of their own.

metasymbol

Something we'd call a metacharacter except that it's a sequence of more than one character. Generally, the first character in the sequence must be a true metacharacter to get the other characters in the metasymbol to misbehave along with it.

method

A kind of action that an object can take if you tell it to. See the perlobj manpage.

minimalism

The belief that "small is beautiful." Paradoxically, if you say something in a small language, it turns out big, and if you say it in a big language, it turns out small. Go figure.

mode

In the context of the the stat manpage syscall, refers to the field holding the permission bits and the type of the file.

modifier

See statement modifier, regular expression modifier, and lvalue modifier, not necessarily in that order.

module

A file that defines a package of (almost) the same name, which can either export symbols or function as an object class. (A module's main .pm file may also load in other files in support of the module.) See the use built-in.

modulus

An integer divisor when you're interested in the remainder instead of the quotient.

monger

Short for Perl Monger, a purveyor of Perl.

mortal

A temporary value scheduled to die when the current statement finishes.

multidimensional array

An array with multiple subscripts for finding a single element. Perl implements these using references--see the perllol manpage and the perldsc manpage.

multiple inheritance

The features you got from your mother and father, mixed together unpredictably. (See also inheritance, and single inheritance.) In computer languages (including Perl), the notion that a given class may have multiple direct ancestors or base classes.

N

named pipe

A pipe with a name embedded in the filesystem so that it can be accessed by two unrelated processes.

namespace

A domain of names. You needn't worry about whether the names in one such domain have been used in another. See package.

network address

The most important attribute of a socket, like your telephone's telephone number. Typically an IP address. See also port.

newline

A single character that represents the end of a line, with the ASCII value of 012 octal under Unix (but 015 on a Mac), and represented by \n in Perl strings. For Windows machines writing text files, and for certain physical devices like terminals, the single newline gets automatically translated by your C library into a line feed and a carriage return, but normally, no translation is done.

NFS

Network File System, which allows you to mount a remote filesystem as if it were local.

null character

A character with the ASCII value of zero. It's used by C to terminate strings, but Perl allows strings to contain a null.

null list

A list value with zero elements, represented in Perl by ().

null string

A string containing no characters, not to be confused with a string containing a null character, which has a positive length and is true.

numeric context

The situation in which an expression is expected by its surroundings (the code calling it) to return a number. See also context and string context.

NV

Short for Nevada, no part of which will ever be confused with civilization. NV also means an internal floating-point Numeric Value of the type a scalar can hold, not to be confused with an IV.

nybble

Half a byte, equivalent to one hexadecimal digit, and worth four bits.

O

object

An instance of a class. Something that "knows" what user-defined type (class) it is, and what it can do because of what class it is. Your program can request an object to do things, but the object gets to decide whether it wants to do them or not. Some objects are more accommodating than others.

octal

A number in base 8. Only the digits 0 through 7 are allowed. Octal constants in Perl start with 0, as in 013. See also the oct function.

offset

How many things you have to skip over when moving from the beginning of a string or array to a specific position within it. Thus, the minimum offset is zero, not one, because you don't skip anything to get to the first item.

one-liner

An entire computer program crammed into one line of text.

open source software

Programs for which the source code is freely available and freely redistributable, with no commercial strings attached. For a more detailed definition, see http://www.opensource.org/osd.html.

operand

An expression that yields a value that an operator operates on. See also precedence.

operating system

A special program that runs on the bare machine and hides the gory details of managing processes and devices. Usually used in a looser sense to indicate a particular culture of programming. The loose sense can be used at varying levels of specificity. At one extreme, you might say that all versions of Unix and Unix-lookalikes are the same operating system (upsetting many people, especially lawyers and other advocates). At the other extreme, you could say this particular version of this particular vendor's operating system is different from any other version of this or any other vendor's operating system. Perl is much more portable across operating systems than many other languages. See also architecture and platform.

operator

A gizmo that transforms some number of input values to some number of output values, often built into a language with a special syntax or symbol. A given operator may have specific expectations about what types of data you give as its arguments (operands) and what type of data you want back from it.

operator overloading

A kind of overloading that you can do on built-in operators to make them work on objects as if the objects were ordinary scalar values, but with the actual semantics supplied by the object class. This is set up with the the overload manpage pragma.

options

See either switches or regular expression modifier.

overloading

Giving additional meanings to a symbol or construct. Actually, all languages do overloading to one extent or another, since people are good at figuring out things from context.

overriding

Hiding or invalidating some other definition of the same name. (Not to be confused with overloading, which adds definitions that must be disambiguated some other way.) To confuse the issue further, we use the word with two overloaded definitions: to describe how you can define your own subroutine to hide a built-in function of the same name (see Overriding Built-in Functions in the perlsub manpage) and to describe how you can define a replacement method in a derived class to hide a base class's method of the same name (see the perlobj manpage).

owner

The one user (apart from the superuser) who has absolute control over a file. A file may also have a group of users who may exercise joint ownership if the real owner permits it. See permission bits.

P

package

A namespace for global variables, subroutines, and the like, such that they can be kept separate from like-named symbols in other namespaces. In a sense, only the package is global, since the symbols in the package's symbol table are only accessible from code compiled outside the package by naming the package. But in another sense, all package symbols are also globals--they're just well-organized globals.

pad

Short for scratchpad.

parameter

See argument.

parent class

See base class.

parse tree

See syntax tree.

parsing

The subtle but sometimes brutal art of attempting to turn your possibly malformed program into a valid syntax tree.

patch

To fix by applying one, as it were. In the realm of hackerdom, a listing of the differences between two versions of a program as might be applied by the patch(1) program when you want to fix a bug or upgrade your old version.

PATH

The list of directories the system searches to find a program you want to execute. The list is stored as one of your environment variables, accessible in Perl as $ENV{PATH}.

pathname

A fully qualified filename such as /usr/bin/perl. Sometimes confused with PATH.

pattern

A template used in pattern matching.

pattern matching

Taking a pattern, usually a regular expression, and trying the pattern various ways on a string to see whether there's any way to make it fit. Often used to pick interesting tidbits out of a file.

permission bits

Bits that the owner of a file sets or unsets to allow or disallow access to other people. These flag bits are part of the mode word returned by the stat built-in when you ask about a file. On Unix systems, you can check the ls(1) manpage for more information.

Pern

What you get when you do Perl++ twice. Doing it only once will curl your hair. You have to increment it eight times to shampoo your hair. Lather, rinse, iterate.

pipe

A direct connection that carries the output of one process to the input of another without an intermediate temporary file. Once the pipe is set up, the two processes in question can read and write as if they were talking to a normal file, with some caveats.

pipeline

A series of processes all in a row, linked by pipes, where each passes its output stream to the next.

platform

The entire hardware and software context in which a program runs. A program written in a platform-dependent language might break if you change any of: machine, operating system, libraries, compiler, or system configuration. The perl interpreter has to be compiled differently for each platform because it is implemented in C, but programs written in the Perl language are largely platform-independent.

pod

The markup used to embed documentation into your Perl code. See the perlpod manpage.

pointer

A variable in a language like C that contains the exact memory location of some other item. Perl handles pointers internally so you don't have to worry about them. Instead, you just use symbolic pointers in the form of keys and variable names, or hard references, which aren't pointers (but act like pointers and do in fact contain pointers).

polymorphism

The notion that you can tell an object to do something generic, and the object will interpret the command in different ways depending on its type. [<Gk many shapes]

port

The part of the address of a TCP or UDP socket that directs packets to the correct process after finding the right machine, something like the phone extension you give when you reach the company operator. Also, the result of converting code to run on a different platform than originally intended, or the verb denoting this conversion.

portable

Once upon a time, C code compilable under both BSD and SysV. In general, code that can be easily converted to run on another platform, where "easily" can be defined however you like, and usually is. Anything may be considered portable if you try hard enough. See mobile home or London Bridge.

porter

Someone who "carries" software from one platform to another. Porting programs written in platform-dependent languages such as C can be difficult work, but porting programs like Perl is very much worth the agony.

POSIX

The Portable Operating System Interface specification.

postfix

An operator that follows its operand, as in $x++.

pp

An internal shorthand for a "push-pop" code, that is, C code implementing Perl's stack machine.

pragma

A standard module whose practical hints and suggestions are received (and possibly ignored) at compile time. Pragmas are named in all lowercase.

precedence

The rules of conduct that, in the absence of other guidance, determine what should happen first. For example, in the absence of parentheses, you always do multiplication before addition.

prefix

An operator that precedes its operand, as in ++$x.

preprocessing

What some helper process did to transform the incoming data into a form more suitable for the current process. Often done with an incoming pipe. See also C preprocessor.

procedure

A subroutine.

process

An instance of a running program. Under multitasking systems like Unix, two or more separate processes could be running the same program independently at the same time--in fact, the fork function is designed to bring about this happy state of affairs. Under other operating systems, processes are sometimes called "threads", "tasks", or "jobs", often with slight nuances in meaning.

program generator

A system that algorithmically writes code for you in a high-level language. See also code generator.

progressive matching

Pattern matching that picks up where it left off before.

property

See either instance variable or character property.

protocol

In networking, an agreed-upon way of sending messages back and forth so that neither correspondent will get too confused.

prototype

An optional part of a subroutine declaration telling the Perl compiler how many and what flavor of arguments may be passed as actual arguments, so that you can write subroutine calls that parse much like built-in functions. (Or don't parse, as the case may be.)

pseudofunction

A construct that sometimes looks like a function but really isn't. Usually reserved for lvalue modifiers like my, for context modifiers like scalar, and for the pick-your-own-quotes constructs, q//, qq//, qx//, qw//, qr//, m//, s///, y///, and tr///.

pseudohash

A reference to an array whose initial element happens to hold a reference to a hash. You can treat a pseudohash reference as either an array reference or a hash reference.

pseudoliteral

An operator that looks something like a literal, such as the output-grabbing operator, `command`.

public domain

Something not owned by anybody. Perl is copyrighted and is thus not in the public domain--it's just freely available and freely redistributable.

pumpkin

A notional "baton" handed around the Perl community indicating who is the lead integrator in some arena of development.

pumpking

A pumpkin holder, the person in charge of pumping the pump, or at least priming it. Must be willing to play the part of the Great Pumpkin now and then.

PV

A "pointer value", which is Perl Internals Talk for a char*.

Q

qualified

Possessing a complete name. The symbol $Ent::moot is qualified; $moot is unqualified. A fully qualified filename is specified from the top-level directory.

quantifier

A component of a regular expression specifying how many times the foregoing atom may occur.

R

readable

With respect to files, one that has the proper permission bit set to let you access the file. With respect to computer programs, one that's written well enough that someone has a chance of figuring out what it's trying to do.

reaping

The last rites performed by a parent process on behalf of a deceased child process so that it doesn't remain a zombie. See the wait and waitpid function calls.

record

A set of related data values in a file or stream, often associated with a unique key field. In Unix, often commensurate with a line, or a blank-line-terminated set of lines (a "paragraph"). Each line of the /etc/passwd file is a record, keyed on login name, containing information about that user.

recursion

The art of defining something (at least partly) in terms of itself, which is a naughty no-no in dictionaries but often works out okay in computer programs if you're careful not to recurse forever, which is like an infinite loop with more spectacular failure modes.

reference

Where you look to find a pointer to information somewhere else. (See indirection.) References come in two flavors, symbolic references and hard references.

referent

Whatever a reference refers to, which may or may not have a name. Common types of referents include scalars, arrays, hashes, and subroutines.

regex

See regular expression.

regular expression

A single entity with various interpretations, like an elephant. To a computer scientist, it's a grammar for a little language in which some strings are legal and others aren't. To normal people, it's a pattern you can use to find what you're looking for when it varies from case to case. Perl's regular expressions are far from regular in the theoretical sense, but in regular use they work quite well. Here's a regular expression: /Oh s.*t./. This will match strings like "Oh say can you see by the dawn's early light" and "Oh sit!". See the perlre manpage.

regular expression modifier

An option on a pattern or substitution, such as /i to render the pattern case insensitive. See also cloister.

regular file

A file that's not a directory, a device, a named pipe or socket, or a symbolic link. Perl uses the -f file test operator to identify regular files. Sometimes called a "plain" file.

relational operator

An operator that says whether a particular ordering relationship is true about a pair of operands. Perl has both numeric and string relational operators. See collating sequence.

reserved words

A word with a specific, built-in meaning to a compiler, such as if or delete. In many languages (not Perl), it's illegal to use reserved words to name anything else. (Which is why they're reserved, after all.) In Perl, you just can't use them to name labels or filehandles. Also called "keywords".

return value

The value produced by a subroutine or expression when evaluated. In Perl, a return value may be either a list or a scalar.

RFC

Request For Comment, which despite the timid connotations is the name of a series of important standards documents.

right shift

A bit shift that divides a number by some power of 2.

root

The superuser (UID == 0). Also, the top-level directory of the filesystem.

RTFM

What you are told when someone thinks you should Read The Fine Manual.

run phase

Any time after Perl starts running your main program. See also compile phase. Run phase is mostly spent in run time but may also be spent in compile time when require, do FILE, or eval STRING operators are executed or when a substitution uses the /ee modifier.

run time

The time when Perl is actually doing what your code says to do, as opposed to the earlier period of time when it was trying to figure out whether what you said made any sense whatsoever, which is compile time.

run-time pattern

A pattern that contains one or more variables to be interpolated before parsing the pattern as a regular expression, and that therefore cannot be analyzed at compile time, but must be re-analyzed each time the pattern match operator is evaluated. Run-time patterns are useful but expensive.

RV

A recreational vehicle, not to be confused with vehicular recreation. RV also means an internal Reference Value of the type a scalar can hold. See also IV and NV if you're not confused yet.

rvalue

A value that you might find on the right side of an assignment. See also lvalue.

S

scalar

A simple, singular value; a number, string, or reference.

scalar context

The situation in which an expression is expected by its surroundings (the code calling it) to return a single value rather than a list of values. See also context and list context. A scalar context sometimes imposes additional constraints on the return value--see string context and numeric context. Sometimes we talk about a Boolean context inside conditionals, but this imposes no additional constraints, since any scalar value, whether numeric or string, is already true or false.

scalar literal

A number or quoted string--an actual value in the text of your program, as opposed to a variable.

scalar value

A value that happens to be a scalar as opposed to a list.

scalar variable

A variable prefixed with $ that holds a single value.

scope

How far away you can see a variable from, looking through one. Perl has two visibility mechanisms: it does dynamic scoping of local variables, meaning that the rest of the block, and any subroutines that are called by the rest of the block, can see the variables that are local to the block. Perl does lexical scoping of my variables, meaning that the rest of the block can see the variable, but other subroutines called by the block cannot see the variable.

scratchpad

The area in which a particular invocation of a particular file or subroutine keeps some of its temporary values, including any lexically scoped variables.

script

A text file that is a program intended to be executed directly rather than compiled to another form of file before execution. Also, in the context of Unicode, a writing system for a particular language or group of languages, such as Greek, Bengali, or Klingon.

script kiddie

A cracker who is not a hacker, but knows just enough to run canned scripts. A cargo-cult programmer.

sed

A venerable Stream EDitor from which Perl derives some of its ideas.

semaphore

A fancy kind of interlock that prevents multiple threads or processes from using up the same resources simultaneously.

separator

A character or string that keeps two surrounding strings from being confused with each other. The split function works on separators. Not to be confused with delimiters or terminators. The "or" in the previous sentence separated the two alternatives.

serialization

Putting a fancy data structure into linear order so that it can be stored as a string in a disk file or database or sent through a pipe. Also called marshalling.

server

In networking, a process that either advertises a service or just hangs around at a known location and waits for clients who need service to get in touch with it.

service

Something you do for someone else to make them happy, like giving them the time of day (or of their life). On some machines, well-known services are listed by the getservent function.

setgid

Same as setuid, only having to do with giving away group privileges.

setuid

Said of a program that runs with the privileges of its owner rather than (as is usually the case) the privileges of whoever is running it. Also describes the bit in the mode word (permission bits) that controls the feature. This bit must be explicitly set by the owner to enable this feature, and the program must be carefully written not to give away more privileges than it ought to.

shared memory

A piece of memory accessible by two different processes who otherwise would not see each other's memory.

shebang

Irish for the whole McGillicuddy. In Perl culture, a portmanteau of "sharp" and "bang", meaning the #! sequence that tells the system where to find the interpreter.

shell

A command-line interpreter. The program that interactively gives you a prompt, accepts one or more lines of input, and executes the programs you mentioned, feeding each of them their proper arguments and input data. Shells can also execute scripts containing such commands. Under Unix, typical shells include the Bourne shell (/bin/sh), the C shell (/bin/csh), and the Korn shell (/bin/ksh). Perl is not strictly a shell because it's not interactive (although Perl programs can be interactive).

side effects

Something extra that happens when you evaluate an expression. Nowadays it can refer to almost anything. For example, evaluating a simple assignment statement typically has the "side effect" of assigning a value to a variable. (And you thought assigning the value was your primary intent in the first place!) Likewise, assigning a value to the special variable $| ($AUTOFLUSH) has the side effect of forcing a flush after every write or print on the currently selected filehandle.

signal

A bolt out of the blue; that is, an event triggered by the operating system, probably when you're least expecting it.

signal handler

A subroutine that, instead of being content to be called in the normal fashion, sits around waiting for a bolt out of the blue before it will deign to execute. Under Perl, bolts out of the blue are called signals, and you send them with the kill built-in. See %SIG in the perlvar manpage and Signals in the perlipc manpage.

single inheritance

The features you got from your mother, if she told you that you don't have a father. (See also inheritance and multiple inheritance.) In computer languages, the notion that classes reproduce asexually so that a given class can only have one direct ancestor or base class. Perl supplies no such restriction, though you may certainly program Perl that way if you like.

slice

A selection of any number of elements from a list, array, or hash.

slurp

To read an entire file into a string in one operation.

socket

An endpoint for network communication among multiple processes that works much like a telephone or a post office box. The most important thing about a socket is its network address (like a phone number). Different kinds of sockets have different kinds of addresses--some look like filenames, and some don't.

soft reference

See symbolic reference.

source filter

A special kind of module that does preprocessing on your script just before it gets to the tokener.

stack

A device you can put things on the top of, and later take them back off in the opposite order in which you put them on. See LIFO.

standard

Included in the official Perl distribution, as in a standard module, a standard tool, or a standard Perl manpage.

standard error

The default output stream for nasty remarks that don't belong in standard output. Represented within a Perl program by the filehandle STDERR. You can use this stream explicitly, but the die and warn built-ins write to your standard error stream automatically.

standard I/O

A standard C library for doing buffered input and output to the operating system. (The "standard" of standard I/O is only marginally related to the "standard" of standard input and output.) In general, Perl relies on whatever implementation of standard I/O a given operating system supplies, so the buffering characteristics of a Perl program on one machine may not exactly match those on another machine. Normally this only influences efficiency, not semantics. If your standard I/O package is doing block buffering and you want it to flush the buffer more often, just set the $| variable to a true value.

standard input

The default input stream for your program, which if possible shouldn't care where its data is coming from. Represented within a Perl program by the filehandle STDIN.

standard output

The default output stream for your program, which if possible shouldn't care where its data is going. Represented within a Perl program by the filehandle STDOUT.

stat structure

A special internal spot in which Perl keeps the information about the last file on which you requested information.

statement

A command to the computer about what to do next, like a step in a recipe: "Add marmalade to batter and mix until mixed." A statement is distinguished from a declaration, which doesn't tell the computer to do anything, but just to learn something.

statement modifier

A conditional or loop that you put after the statement instead of before, if you know what we mean.

static

Varying slowly compared to something else. (Unfortunately, everything is relatively stable compared to something else, except for certain elementary particles, and we're not so sure about them.) In computers, where things are supposed to vary rapidly, "static" has a derogatory connotation, indicating a slightly dysfunctional variable, subroutine, or method. In Perl culture, the word is politely avoided.

static method

No such thing. See class method.

static scoping

No such thing. See lexical scoping.

static variable

No such thing. Just use a lexical variable in a scope larger than your subroutine.

status

The value returned to the parent process when one of its child processes dies. This value is placed in the special variable $?. Its upper eight bits are the exit status of the defunct process, and its lower eight bits identify the signal (if any) that the process died from. On Unix systems, this status value is the same as the status word returned by wait(2). See system in the perlfunc manpage.

STDERR

See standard error.

STDIN

See standard input.

STDIO

See standard I/O.

STDOUT

See standard output.

stream

A flow of data into or out of a process as a steady sequence of bytes or characters, without the appearance of being broken up into packets. This is a kind of interface--the underlying implementation may well break your data up into separate packets for delivery, but this is hidden from you.

string

A sequence of characters such as "He said !@#*&%@#*?!". A string does not have to be entirely printable.

string context

The situation in which an expression is expected by its surroundings (the code calling it) to return a string. See also context and numeric context.

stringification

The process of producing a string representation of an abstract object.

struct

C keyword introducing a structure definition or name.

structure

See data structure.

subclass

See derived class.

subpattern

A component of a regular expression pattern.

subroutine

A named or otherwise accessible piece of program that can be invoked from elsewhere in the program in order to accomplish some sub-goal of the program. A subroutine is often parameterized to accomplish different but related things depending on its input arguments. If the subroutine returns a meaningful value, it is also called a function.

subscript

A value that indicates the position of a particular array element in an array.

substitution

Changing parts of a string via the s/// operator. (We avoid use of this term to mean variable interpolation.)

substring

A portion of a string, starting at a certain character position (offset) and proceeding for a certain number of characters.

superclass

See base class.

superuser

The person whom the operating system will let do almost anything. Typically your system administrator or someone pretending to be your system administrator. On Unix systems, the root user. On Windows systems, usually the Administrator user.

SV

Short for "scalar value". But within the Perl interpreter every referent is treated as a member of a class derived from SV, in an object-oriented sort of way. Every value inside Perl is passed around as a C language SV* pointer. The SV struct knows its own "referent type", and the code is smart enough (we hope) not to try to call a hash function on a subroutine.

switch

An option you give on a command line to influence the way your program works, usually introduced with a minus sign. The word is also used as a nickname for a switch statement.

switch cluster

The combination of multiple command-line switches (e.g., -a -b -c) into one switch (e.g., -abc). Any switch with an additional argument must be the last switch in a cluster.

switch statement

A program technique that lets you evaluate an expression and then, based on the value of the expression, do a multiway branch to the appropriate piece of code for that value. Also called a "case structure", named after the similar Pascal construct. Most switch statements in Perl are spelled for. See Basic BLOCKs and Switch Statements in the perlsyn manpage.

symbol

Generally, any token or metasymbol. Often used more specifically to mean the sort of name you might find in a symbol table.

symbol table

Where a compiler remembers symbols. A program like Perl must somehow remember all the names of all the variables, filehandles, and subroutines you've used. It does this by placing the names in a symbol table, which is implemented in Perl using a hash table. There is a separate symbol table for each package to give each package its own namespace.

symbolic debugger

A program that lets you step through the execution of your program, stopping or printing things out here and there to see whether anything has gone wrong, and if so, what. The "symbolic" part just means that you can talk to the debugger using the same symbols with which your program is written.

symbolic link

An alternate filename that points to the real filename, which in turn points to the real file. Whenever the operating system is trying to parse a pathname containing a symbolic link, it merely substitutes the new name and continues parsing.

symbolic reference

A variable whose value is the name of another variable or subroutine. By dereferencing the first variable, you can get at the second one. Symbolic references are illegal under use strict 'refs'.

synchronous

Programming in which the orderly sequence of events can be determined; that is, when things happen one after the other, not at the same time.

syntactic sugar

An alternative way of writing something more easily; a shortcut.

syntax

From Greek, "with-arrangement". How things (particularly symbols) are put together with each other.

syntax tree

An internal representation of your program wherein lower-level constructs dangle off the higher-level constructs enclosing them.

syscall

A function call directly to the operating system. Many of the important subroutines and functions you use aren't direct system calls, but are built up in one or more layers above the system call level. In general, Perl programmers don't need to worry about the distinction. However, if you do happen to know which Perl functions are really syscalls, you can predict which of these will set the $! ($ERRNO) variable on failure. Unfortunately, beginning programmers often confusingly employ the term "system call" to mean what happens when you call the Perl system function, which actually involves many syscalls. To avoid any confusion, we nearly always use say "syscall" for something you could call indirectly via Perl's syscall function, and never for something you would call with Perl's system function.

T

tainted

Said of data derived from the grubby hands of a user and thus unsafe for a secure program to rely on. Perl does taint checks if you run a setuid (or setgid) program, or if you use the -T switch.

TCP

Short for Transmission Control Protocol. A protocol wrapped around the Internet Protocol to make an unreliable packet transmission mechanism appear to the application program to be a reliable stream of bytes. (Usually.)

term

Short for a "terminal", that is, a leaf node of a syntax tree. A thing that functions grammatically as an operand for the operators in an expression.

terminator

A character or string that marks the end of another string. The $/ variable contains the string that terminates a readline operation, which chomp deletes from the end. Not to be confused with delimiters or separators. The period at the end of this sentence is a terminator.

ternary

An operator taking three operands. Sometimes pronounced trinary.

text

A string or file containing primarily printable characters.

thread

Like a forked process, but without fork's inherent memory protection. A thread is lighter weight than a full process, in that a process could have multiple threads running around in it, all fighting over the same process's memory space unless steps are taken to protect threads from each other. See the threads manpage.

tie

The bond between a magical variable and its implementation class. See tie in the perlfunc manpage and the perltie manpage.

TMTOWTDI

There's More Than One Way To Do It, the Perl Motto. The notion that there can be more than one valid path to solving a programming problem in context. (This doesn't mean that more ways are always better or that all possible paths are equally desirable--just that there need not be One True Way.) Pronounced TimToady.

token

A morpheme in a programming language, the smallest unit of text with semantic significance.

tokener

A module that breaks a program text into a sequence of tokens for later analysis by a parser.

tokenizing

Splitting up a program text into tokens. Also known as "lexing", in which case you get "lexemes" instead of tokens.

toolbox approach

The notion that, with a complete set of simple tools that work well together, you can build almost anything you want. Which is fine if you're assembling a tricycle, but if you're building a defranishizing comboflux regurgalator, you really want your own machine shop in which to build special tools. Perl is sort of a machine shop.

transliterate

To turn one string representation into another by mapping each character of the source string to its corresponding character in the result string. See tr/SEARCHLIST/REPLACEMENTLIST/cds in the perlop manpage.

trigger

An event that causes a handler to be run.

trinary

Not a stellar system with three stars, but an operator taking three operands. Sometimes pronounced ternary.

troff

A venerable typesetting language from which Perl derives the name of its $% variable and which is secretly used in the production of Camel books.

true

Any scalar value that doesn't evaluate to 0 or "".

truncating

Emptying a file of existing contents, either automatically when opening a file for writing or explicitly via the truncate function.

type

See data type and class.

type casting

Converting data from one type to another. C permits this. Perl does not need it. Nor want it.

typed lexical

A lexical variable that is declared with a class type: my Pony $bill.

typedef

A type definition in the C language.

typeglob

Use of a single identifier, prefixed with *. For example, *name stands for any or all of $name, @name, %name, &name, or just name. How you use it determines whether it is interpreted as all or only one of them. See Typeglobs and Filehandles in the perldata manpage.

typemap

A description of how C types may be transformed to and from Perl types within an extension module written in XS.

U

UDP

User Datagram Protocol, the typical way to send datagrams over the Internet.

UID

A user ID. Often used in the context of file or process ownership.

umask

A mask of those permission bits that should be forced off when creating files or directories, in order to establish a policy of whom you'll ordinarily deny access to. See the umask function.

unary operator

An operator with only one operand, like ! or chdir. Unary operators are usually prefix operators; that is, they precede their operand. The ++ and -- operators can be either prefix or postfix. (Their position does change their meanings.)

Unicode

A character set comprising all the major character sets of the world, more or less. See http://www.unicode.org.

Unix

A very large and constantly evolving language with several alternative and largely incompatible syntaxes, in which anyone can define anything any way they choose, and usually do. Speakers of this language think it's easy to learn because it's so easily twisted to one's own ends, but dialectical differences make tribal intercommunication nearly impossible, and travelers are often reduced to a pidgin-like subset of the language. To be universally understood, a Unix shell programmer must spend years of study in the art. Many have abandoned this discipline and now communicate via an Esperanto-like language called Perl.

In ancient times, Unix was also used to refer to some code that a couple of people at Bell Labs wrote to make use of a PDP-7 computer that wasn't doing much of anything else at the time.

V

value

An actual piece of data, in contrast to all the variables, references, keys, indexes, operators, and whatnot that you need to access the value.

variable

A named storage location that can hold any of various kinds of value, as your program sees fit.

variable interpolation

The interpolation of a scalar or array variable into a string.

variadic

Said of a function that happily receives an indeterminate number of actual arguments.

vector

Mathematical jargon for a list of scalar values.

virtual

Providing the appearance of something without the reality, as in: virtual memory is not real memory. (See also memory.) The opposite of "virtual" is "transparent", which means providing the reality of something without the appearance, as in: Perl handles the variable-length UTF-8 character encoding transparently.

void context

A form of scalar context in which an expression is not expected to return any value at all and is evaluated for its side effects alone.

v-string

A "version" or "vector" string specified with a v followed by a series of decimal integers in dot notation, for instance, v1.20.300.4000. Each number turns into a character with the specified ordinal value. (The v is optional when there are at least three integers.)

W

warning

A message printed to the STDERR stream to the effect that something might be wrong but isn't worth blowing up over. See warn in the perlfunc manpage and the the warnings manpage pragma.

watch expression

An expression which, when its value changes, causes a breakpoint in the Perl debugger.

whitespace

A character that moves your cursor but doesn't otherwise put anything on your screen. Typically refers to any of: space, tab, line feed, carriage return, or form feed.

word

In normal "computerese", the piece of data of the size most efficiently handled by your computer, typically 32 bits or so, give or take a few powers of 2. In Perl culture, it more often refers to an alphanumeric identifier (including underscores), or to a string of nonwhitespace characters bounded by whitespace or string boundaries.

working directory

Your current directory, from which relative pathnames are interpreted by the operating system. The operating system knows your current directory because you told it with a chdir or because you started out in the place where your parent process was when you were born.

wrapper

A program or subroutine that runs some other program or subroutine for you, modifying some of its input or output to better suit your purposes.

WYSIWYG

What You See Is What You Get. Usually used when something that appears on the screen matches how it will eventually look, like Perl's format declarations. Also used to mean the opposite of magic because everything works exactly as it appears, as in the three-argument form of open.

X

XS

An extraordinarily exported, expeditiously excellent, expressly eXternal Subroutine, executed in existing C or C++ or in an exciting new extension language called (exasperatingly) XS. Examine the perlxs manpage for the exact explanation or the perlxstut manpage for an exemplary unexacting one.

XSUB

An external subroutine defined in XS.

Y

yacc

Yet Another Compiler Compiler. A parser generator without which Perl probably would not have existed. See the file perly.y in the Perl source distribution.

Z

zero width

A subpattern assertion matching the null string between characters.

zombie

A process that has died (exited) but whose parent has not yet received proper notification of its demise by virtue of having called wait or waitpid. If you fork, you must clean up after your child processes when they exit, or else the process table will fill up and your system administrator will Not Be Happy with you.

AUTHOR AND COPYRIGHT

Based on the Glossary of Programming Perl, Third Edition, by Larry Wall, Tom Christiansen & Jon Orwant. Copyright (c) 2000, 1996, 1991 O'Reilly Media, Inc. This document may be distributed under the same terms as Perl itself.


perlrun - how to execute the Perl interpreter

    • #! and quoting on non-Unix systems
    • Location of Perl
    • Command Switches
  • ENVIRONMENT

NAME

perlrun - how to execute the Perl interpreter

SYNOPSIS

perl | [ -sTtuUWX ]
 | [ -hv ] [ -V[:configvar] ]
 | [ -cw ] [ -d[t][:debugger] ] [ -D[number/list] ]
 | [ -pna ] [ -F pattern ] [ -l[octal] ] [ -0[octal/hexadecimal] ]
 | [ -I dir ] [ -m[-]module ] [ -M[-]'module...' ] [ -f ]
 | [ -C [number/list] ]
 | [ -P ]
 | [ -S ]
 | [ -x[dir] ]
 | [ -i[extension] ]
 | [ -e 'command' ] [ -- ] [ programfile ] [ argument ]...

DESCRIPTION

The normal way to run a Perl program is by making it directly executable, or else by passing the name of the source file as an argument on the command line. (An interactive Perl environment is also possible--see the perldebug manpage for details on how to do that.) Upon startup, Perl looks for your program in one of the following places:

  1. Specified line by line via -e switches on the command line.

  2. Contained in the file specified by the first filename on the command line. (Note that systems supporting the #! notation invoke interpreters this way. See Location of Perl.)

  3. Passed in implicitly via standard input. This works only if there are no filename arguments--to pass arguments to a STDIN-read program you must explicitly specify a "-" for the program name.

With methods 2 and 3, Perl starts parsing the input file from the beginning, unless you've specified a -x switch, in which case it scans for the first line starting with #! and containing the word "perl", and starts there instead. This is useful for running a program embedded in a larger message. (In this case you would indicate the end of the program using the __END__ token.)

The #! line is always examined for switches as the line is being parsed. Thus, if you're on a machine that allows only one argument with the #! line, or worse, doesn't even recognize the #! line, you still can get consistent switch behavior regardless of how Perl was invoked, even if -x was used to find the beginning of the program.

Because historically some operating systems silently chopped off kernel interpretation of the #! line after 32 characters, some switches may be passed in on the command line, and some may not; you could even get a "-" without its letter, if you're not careful. You probably want to make sure that all your switches fall either before or after that 32-character boundary. Most switches don't actually care if they're processed redundantly, but getting a "-" instead of a complete switch could cause Perl to try to execute standard input instead of your program. And a partial -I switch could also cause odd results.

Some switches do care if they are processed twice, for instance combinations of -l and -0. Either put all the switches after the 32-character boundary (if applicable), or replace the use of -0 digits by BEGIN{ $/ = "\0digits"; }.

Parsing of the #! switches starts wherever "perl" is mentioned in the line. The sequences "-*" and "- " are specifically ignored so that you could, if you were so inclined, say

    #!/bin/sh -- # -*- perl -*- -p
    eval 'exec perl -wS $0 ${1+"$@"}'
        if $running_under_some_shell;

to let Perl see the -p switch.

A similar trick involves the env program, if you have it.

    #!/usr/bin/env perl

The examples above use a relative path to the perl interpreter, getting whatever version is first in the user's path. If you want a specific version of Perl, say, perl5.005_57, you should place that directly in the #! line's path.

If the #! line does not contain the word "perl", the program named after the #! is executed instead of the Perl interpreter. This is slightly bizarre, but it helps people on machines that don't do #!, because they can tell a program that their SHELL is /usr/bin/perl, and Perl will then dispatch the program to the correct interpreter for them.

After locating your program, Perl compiles the entire program to an internal form. If there are any compilation errors, execution of the program is not attempted. (This is unlike the typical shell script, which might run part-way through before finding a syntax error.)

If the program is syntactically correct, it is executed. If the program runs off the end without hitting an exit() or die() operator, an implicit exit(0) is provided to indicate successful completion.

#! and quoting on non-Unix systems

Unix's #! technique can be simulated on other systems:

OS/2

Put

    extproc perl -S -your_switches

as the first line in *.cmd file (-S due to a bug in cmd.exe's `extproc' handling).

MS-DOS

Create a batch file to run your program, and codify it in ALTERNATE_SHEBANG (see the dosish.h file in the source distribution for more information).

Win95/NT

The Win95/NT installation, when using the ActiveState installer for Perl, will modify the Registry to associate the .pl extension with the perl interpreter. If you install Perl by other means (including building from the sources), you may have to modify the Registry yourself. Note that this means you can no longer tell the difference between an executable Perl program and a Perl library file.

Macintosh

Under "Classic" MacOS, a perl program will have the appropriate Creator and Type, so that double-clicking them will invoke the MacPerl application. Under Mac OS X, clickable apps can be made from any #! script using Wil Sanchez' DropScript utility: http://www.wsanchez.net/software/ .

VMS

Put

    $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
    $ exit++ + ++$status != 0 and $exit = $status = undef;

at the top of your program, where -mysw are any command line switches you want to pass to Perl. You can now invoke the program directly, by saying perl program, or as a DCL procedure, by saying @program (or implicitly via DCL$PATH by just using the name of the program).

This incantation is a bit much to remember, but Perl will display it for you if you say perl "-V:startperl".

Command-interpreters on non-Unix systems have rather different ideas on quoting than Unix shells. You'll need to learn the special characters in your command-interpreter (*, \ and " are common) and how to protect whitespace and these characters to run one-liners (see -e below).

On some systems, you may have to change single-quotes to double ones, which you must not do on Unix or Plan 9 systems. You might also have to change a single % to a %%.

For example:

    # Unix
    perl -e 'print "Hello world\n"'
    # MS-DOS, etc.
    perl -e "print \"Hello world\n\""
    # Macintosh
    print "Hello world\n"
     (then Run "Myscript" or Shift-Command-R)
    # VMS
    perl -e "print ""Hello world\n"""

The problem is that none of this is reliable: it depends on the command and it is entirely possible neither works. If 4DOS were the command shell, this would probably work better:

    perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""

CMD.EXE in Windows NT slipped a lot of standard Unix functionality in when nobody was looking, but just try to find documentation for its quoting rules.

Under the Macintosh, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several quoting variants, except that it makes free use of the Macintosh's non-ASCII characters as control characters.

There is no general solution to all of this. It's just a mess.

Location of Perl

It may seem obvious to say, but Perl is useful only when users can easily find it. When possible, it's good for both /usr/bin/perl and /usr/local/bin/perl to be symlinks to the actual binary. If that can't be done, system administrators are strongly encouraged to put (symlinks to) perl and its accompanying utilities into a directory typically found along a user's PATH, or in some other obvious and convenient place.

In this documentation, #!/usr/bin/perl on the first line of the program will stand in for whatever method works on your system. You are advised to use a specific path if you care about a specific version.

    #!/usr/local/bin/perl5.00554

or if you just want to be running at least version, place a statement like this at the top of your program:

    use 5.005_54;

Command Switches

As with all standard commands, a single-character switch may be clustered with the following switch, if any.

    #!/usr/bin/perl -spi.orig   # same as -s -p -i.orig

Switches include:

-0[octal/hexadecimal]

specifies the input record separator ($/) as an octal or hexadecimal number. If there are no digits, the null character is the separator. Other switches may precede or follow the digits. For example, if you have a version of find which can print filenames terminated by the null character, you can say this:

    find . -name '*.orig' -print0 | perl -n0e unlink

The special value 00 will cause Perl to slurp files in paragraph mode. The value 0777 will cause Perl to slurp files whole because there is no legal byte with that value.

If you want to specify any Unicode character, use the hexadecimal format: -0xHHH..., where the H are valid hexadecimal digits. (This means that you cannot use the -x with a directory name that consists of hexadecimal digits.)

-a

turns on autosplit mode when used with a -n or -p. An implicit split command to the @F array is done as the first thing inside the implicit while loop produced by the -n or -p.

    perl -ane 'print pop(@F), "\n";'

is equivalent to

    while (<>) {
        @F = split(' ');
        print pop(@F), "\n";
    }

An alternate delimiter may be specified using -F.

-C [number/list]

The -C flag controls some Unicode of the Perl Unicode features.

As of 5.8.1, the -C can be followed either by a number or a list of option letters. The letters, their numeric values, and effects are as follows; listing the letters is equal to summing the numbers.

    I     1    STDIN is assumed to be in UTF-8
    O     2    STDOUT will be in UTF-8
    E     4    STDERR will be in UTF-8
    S     7    I + O + E
    i     8    UTF-8 is the default PerlIO layer for input streams
    o    16    UTF-8 is the default PerlIO layer for output streams
    D    24    i + o
    A    32    the @ARGV elements are expected to be strings encoded in UTF-8
    L    64    normally the "IOEioA" are unconditional,
               the L makes them conditional on the locale environment
               variables (the LC_ALL, LC_TYPE, and LANG, in the order
               of decreasing precedence) -- if the variables indicate
               UTF-8, then the selected "IOEioA" are in effect

For example, -COE and -C6 will both turn on UTF-8-ness on both STDOUT and STDERR. Repeating letters is just redundant, not cumulative nor toggling.

The io options mean that any subsequent open() (or similar I/O operations) will have the :utf8 PerlIO layer implicitly applied to them, in other words, UTF-8 is expected from any input stream, and UTF-8 is produced to any output stream. This is just the default, with explicit layers in open() and with binmode() one can manipulate streams as usual.

-C on its own (not followed by any number or option list), or the empty string "" for the PERL_UNICODE environment variable, has the same effect as -CSDL. In other words, the standard I/O handles and the default open() layer are UTF-8-fied but only if the locale environment variables indicate a UTF-8 locale. This behaviour follows the implicit (and problematic) UTF-8 behaviour of Perl 5.8.0.

You can use -C0 (or "0" for PERL_UNICODE) to explicitly disable all the above Unicode features.

The read-only magic variable ${^UNICODE} reflects the numeric value of this setting. This is variable is set during Perl startup and is thereafter read-only. If you want runtime effects, use the three-arg open() (see open in the perlfunc manpage), the two-arg binmode() (see binmode in the perlfunc manpage), and the open pragma (see the open manpage).

(In Perls earlier than 5.8.1 the -C switch was a Win32-only switch that enabled the use of Unicode-aware "wide system call" Win32 APIs. This feature was practically unused, however, and the command line switch was therefore "recycled".)

-c

causes Perl to check the syntax of the program and then exit without executing it. Actually, it will execute BEGIN, CHECK, and use blocks, because these are considered as occurring outside the execution of your program. INIT and END blocks, however, will be skipped.

-d
-dt

runs the program under the Perl debugger. See the perldebug manpage. If t is specified, it indicates to the debugger that threads will be used in the code being debugged.

-d:foo[=bar,baz]
-dt:foo[=bar,baz]

runs the program under the control of a debugging, profiling, or tracing module installed as Devel::foo. E.g., -d:DProf executes the program using the Devel::DProf profiler. As with the -M flag, options may be passed to the Devel::foo package where they will be received and interpreted by the Devel::foo::import routine. The comma-separated list of options must follow a = character. If t is specified, it indicates to the debugger that threads will be used in the code being debugged. See the perldebug manpage.

-D letters
-D number

sets debugging flags. To watch how it executes your program, use -Dtls. (This works only if debugging is compiled into your Perl.) Another nice value is -Dx, which lists your compiled syntax tree. And -Dr displays compiled regular expressions; the format of the output is explained in the perldebguts manpage.

As an alternative, specify a number instead of list of letters (e.g., -D14 is equivalent to -Dtls):

        1  p  Tokenizing and parsing
        2  s  Stack snapshots (with v, displays all stacks)
        4  l  Context (loop) stack processing
        8  t  Trace execution
       16  o  Method and overloading resolution
       32  c  String/numeric conversions
       64  P  Print profiling info, preprocessor command for -P, source file input state
      128  m  Memory allocation
      256  f  Format processing
      512  r  Regular expression parsing and execution
     1024  x  Syntax tree dump
     2048  u  Tainting checks
     4096     (Obsolete, previously used for LEAKTEST)
     8192  H  Hash dump -- usurps values()
    16384  X  Scratchpad allocation
    32768  D  Cleaning up
    65536  S  Thread synchronization
   131072  T  Tokenising
   262144  R  Include reference counts of dumped variables (eg when using -Ds)
   524288  J  Do not s,t,P-debug (Jump over) opcodes within package DB
  1048576  v  Verbose: use in conjunction with other flags
  8388608  q  quiet - currently only suppresses the "EXECUTING" message

All these flags require -DDEBUGGING when you compile the Perl executable (but see the Devel::Peek manpage, the re manpage which may change this). See the INSTALL file in the Perl source distribution for how to do this. This flag is automatically set if you include -g option when Configure asks you about optimizer/debugger flags.

If you're just trying to get a print out of each line of Perl code as it executes, the way that sh -x provides for shell scripts, you can't use Perl's -D switch. Instead do this

  # If you have "env" utility
  env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
  # Bourne shell syntax
  $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
  # csh syntax
  % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)

See the perldebug manpage for details and variations.

-e commandline

may be used to enter one line of program. If -e is given, Perl will not look for a filename in the argument list. Multiple -e commands may be given to build up a multi-line script. Make sure to use semicolons where you would in a normal program.

-f

Disable executing $Config{sitelib}/sitecustomize.pl at startup.

Perl can be built so that it by default will try to execute $Config{sitelib}/sitecustomize.pl at startup. This is a hook that allows the sysadmin to customize how perl behaves. It can for instance be used to add entries to the @INC array to make perl find modules in non-standard locations.

-F pattern

specifies the pattern to split on if -a is also in effect. The pattern may be surrounded by //, "", or '', otherwise it will be put in single quotes. You can't use literal whitespace in the pattern.

-h

prints a summary of the options.

-i[extension]

specifies that files processed by the <> construct are to be edited in-place. It does this by renaming the input file, opening the output file by the original name, and selecting that output file as the default for print() statements. The extension, if supplied, is used to modify the name of the old file to make a backup copy, following these rules:

If no extension is supplied, no backup is made and the current file is overwritten.

If the extension doesn't contain a *, then it is appended to the end of the current filename as a suffix. If the extension does contain one or more * characters, then each * is replaced with the current filename. In Perl terms, you could think of this as:

    ($backup = $extension) =~ s/\*/$file_name/g;

This allows you to add a prefix to the backup file, instead of (or in addition to) a suffix:

    $ perl -pi'orig_*' -e 's/bar/baz/' fileA    # backup to 'orig_fileA'

Or even to place backup copies of the original files into another directory (provided the directory already exists):

    $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'

These sets of one-liners are equivalent:

    $ perl -pi -e 's/bar/baz/' fileA            # overwrite current file
    $ perl -pi'*' -e 's/bar/baz/' fileA         # overwrite current file
    $ perl -pi'.orig' -e 's/bar/baz/' fileA     # backup to 'fileA.orig'
    $ perl -pi'*.orig' -e 's/bar/baz/' fileA    # backup to 'fileA.orig'

From the shell, saying

    $ perl -p -i.orig -e "s/foo/bar/; ... "

is the same as using the program:

    #!/usr/bin/perl -pi.orig
    s/foo/bar/;

which is equivalent to

    #!/usr/bin/perl
    $extension = '.orig';
    LINE: while (<>) {
        if ($ARGV ne $oldargv) {
            if ($extension !~ /\*/) {
                $backup = $ARGV . $extension;
            }
            else {
                ($backup = $extension) =~ s/\*/$ARGV/g;
            }
            rename($ARGV, $backup);
            open(ARGVOUT, ">$ARGV");
            select(ARGVOUT);
            $oldargv = $ARGV;
        }
        s/foo/bar/;
    }
    continue {
        print;  # this prints to original filename
    }
    select(STDOUT);

except that the -i form doesn't need to compare $ARGV to $oldargv to know when the filename has changed. It does, however, use ARGVOUT for the selected filehandle. Note that STDOUT is restored as the default output filehandle after the loop.

As shown above, Perl creates the backup file whether or not any output is actually changed. So this is just a fancy way to copy files:

    $ perl -p -i'/some/file/path/*' -e 1 file1 file2 file3...
or
    $ perl -p -i'.orig' -e 1 file1 file2 file3...

You can use eof without parentheses to locate the end of each input file, in case you want to append to each file, or reset line numbering (see example in eof in the perlfunc manpage).

If, for a given file, Perl is unable to create the backup file as specified in the extension then it will skip that file and continue on with the next one (if it exists).

For a discussion of issues surrounding file permissions and -i, see Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl? in the perlfaq5 manpage.

You cannot use -i to create directories or to strip extensions from files.

Perl does not expand ~ in filenames, which is good, since some folks use it for their backup files:

    $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...

Note that because -i renames or deletes the original file before creating a new file of the same name, UNIX-style soft and hard links will not be preserved.

Finally, the -i switch does not impede execution when no files are given on the command line. In this case, no backup is made (the original file cannot, of course, be determined) and processing proceeds from STDIN to STDOUT as might be expected.

-I directory

Directories specified by -I are prepended to the search path for modules (@INC), and also tells the C preprocessor where to search for include files. The C preprocessor is invoked with -P; by default it searches /usr/include and /usr/lib/perl.

-l[octnum]

enables automatic line-ending processing. It has two separate effects. First, it automatically chomps $/ (the input record separator) when used with -n or -p. Second, it assigns $\ (the output record separator) to have the value of octnum so that any print statements will have that separator added back on. If octnum is omitted, sets $\ to the current value of $/. For instance, to trim lines to 80 columns:

    perl -lpe 'substr($_, 80) = ""'

Note that the assignment $\ = $/ is done when the switch is processed, so the input record separator can be different than the output record separator if the -l switch is followed by a -0 switch:

    gnufind / -print0 | perl -ln0e 'print "found $_" if -p'

This sets $\ to newline and then sets $/ to the null character.

-m[-]module
-M[-]module
-M[-]'module ...'
-[mM][-]module=arg[,arg]...

-m module executes use module (); before executing your program.

-M module executes use module ; before executing your program. You can use quotes to add extra code after the module name, e.g., '-Mmodule qw(foo bar)'.

If the first character after the -M or -m is a dash (-) then the 'use' is replaced with 'no'.

A little builtin syntactic sugar means you can also say -mmodule=foo,bar or -Mmodule=foo,bar as a shortcut for '-Mmodule qw(foo bar)'. This avoids the need to use quotes when importing symbols. The actual code generated by -Mmodule=foo,bar is use module split(/,/,q{foo,bar}). Note that the = form removes the distinction between -m and -M.

A consequence of this is that -MFoo=number never does a version check (unless Foo::import() itself is set up to do a version check, which could happen for example if Foo inherits from Exporter.)

-n

causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like sed -n or awk:

  LINE:
    while (<>) {
        ...             # your program goes here
    }

Note that the lines are not printed by default. See -p to have lines printed. If a file named by an argument cannot be opened for some reason, Perl warns you about it and moves on to the next file.

Here is an efficient way to delete all files that haven't been modified for at least a week:

    find . -mtime +7 -print | perl -nle unlink

This is faster than using the -exec switch of find because you don't have to start a process on every filename found. It does suffer from the bug of mishandling newlines in pathnames, which you can fix if you follow the example under -0.

BEGIN and END blocks may be used to capture control before or after the implicit program loop, just as in awk.

-p

causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like sed:

  LINE:
    while (<>) {
        ...             # your program goes here
    } continue {
        print or die "-p destination: $!\n";
    }

If a file named by an argument cannot be opened for some reason, Perl warns you about it, and moves on to the next file. Note that the lines are printed automatically. An error occurring during printing is treated as fatal. To suppress printing use the -n switch. A -p overrides a -n switch.

BEGIN and END blocks may be used to capture control before or after the implicit loop, just as in awk.

-P

NOTE: Use of -P is strongly discouraged because of its inherent problems, including poor portability.

This option causes your program to be run through the C preprocessor before compilation by Perl. Because both comments and cpp directives begin with the # character, you should avoid starting comments with any words recognized by the C preprocessor such as "if", "else", or "define".

If you're considering using -P, you might also want to look at the Filter::cpp module from CPAN.

The problems of -P include, but are not limited to:

  • The #! line is stripped, so any switches there don't apply.

  • A -P on a #! line doesn't work.

  • All lines that begin with (whitespace and) a # but do not look like cpp commands, are stripped, including anything inside Perl strings, regular expressions, and here-docs .

  • In some platforms the C preprocessor knows too much: it knows about the C++ -style until-end-of-line comments starting with "//". This will cause problems with common Perl constructs like

        s/foo//;

    because after -P this will became illegal code

        s/foo

    The workaround is to use some other quoting separator than "/", like for example "!":

        s!foo!!;

  • It requires not only a working C preprocessor but also a working sed. If not on UNIX, you are probably out of luck on this.

  • Script line numbers are not preserved.

  • The -x does not work with -P.

-s

enables rudimentary switch parsing for switches on the command line after the program name but before any filename arguments (or before an argument of --). Any switch found there is removed from @ARGV and sets the corresponding variable in the Perl program. The following program prints "1" if the program is invoked with a -xyz switch, and "abc" if it is invoked with -xyz=abc.

    #!/usr/bin/perl -s
    if ($xyz) { print "$xyz\n" }

Do note that a switch like --help creates the variable ${-help}, which is not compliant with strict refs. Also, when using this option on a script with warnings enabled you may get a lot of spurious "used only once" warnings.

-S

makes Perl use the PATH environment variable to search for the program (unless the name of the program contains directory separators).

On some platforms, this also makes Perl append suffixes to the filename while searching for it. For example, on Win32 platforms, the ".bat" and ".cmd" suffixes are appended if a lookup for the original name fails, and if the name does not already end in one of those suffixes. If your Perl was compiled with DEBUGGING turned on, using the -Dp switch to Perl shows how the search progresses.

Typically this is used to emulate #! startup on platforms that don't support #!. Its also convenient when debugging a script that uses #!, and is thus normally found by the shell's $PATH search mechanism.

This example works on many platforms that have a shell compatible with Bourne shell:

    #!/usr/bin/perl
    eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
            if $running_under_some_shell;

The system ignores the first line and feeds the program to /bin/sh, which proceeds to try to execute the Perl program as a shell script. The shell executes the second line as a normal shell command, and thus starts up the Perl interpreter. On some systems $0 doesn't always contain the full pathname, so the -S tells Perl to search for the program if necessary. After Perl locates the program, it parses the lines and ignores them because the variable $running_under_some_shell is never true. If the program will be interpreted by csh, you will need to replace ${1+"$@"} with $*, even though that doesn't understand embedded spaces (and such) in the argument list. To start up sh rather than csh, some systems may have to replace the #! line with a line containing just a colon, which will be politely ignored by Perl. Other systems can't control that, and need a totally devious construct that will work under any of csh, sh, or Perl, such as the following:

        eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
        & eval 'exec /usr/bin/perl -wS $0 $argv:q'
                if $running_under_some_shell;

If the filename supplied contains directory separators (i.e., is an absolute or relative pathname), and if that file is not found, platforms that append file extensions will do so and try to look for the file with those extensions added, one by one.

On DOS-like platforms, if the program does not contain directory separators, it will first be searched for in the current directory before being searched for on the PATH. On Unix platforms, the program will be searched for strictly on the PATH.

-t

Like -T, but taint checks will issue warnings rather than fatal errors. These warnings can be controlled normally with no warnings qw(taint).

NOTE: this is not a substitute for -T. This is meant only to be used as a temporary development aid while securing legacy code: for real production code and for new secure code written from scratch always use the real -T.

-T

forces "taint" checks to be turned on so you can test them. Ordinarily these checks are done only when running setuid or setgid. It's a good idea to turn them on explicitly for programs that run on behalf of someone else whom you might not necessarily trust, such as CGI programs or any internet servers you might write in Perl. See the perlsec manpage for details. For security reasons, this option must be seen by Perl quite early; usually this means it must appear early on the command line or in the #! line for systems which support that construct.

-u

This obsolete switch causes Perl to dump core after compiling your program. You can then in theory take this core dump and turn it into an executable file by using the undump program (not supplied). This speeds startup at the expense of some disk space (which you can minimize by stripping the executable). (Still, a "hello world" executable comes out to about 200K on my machine.) If you want to execute a portion of your program before dumping, use the dump() operator instead. Note: availability of undump is platform specific and may not be available for a specific port of Perl.

This switch has been superseded in favor of the new Perl code generator backends to the compiler. See the B manpage and the B::Bytecode manpage for details.

-U

allows Perl to do unsafe operations. Currently the only "unsafe" operations are attempting to unlink directories while running as superuser, and running setuid programs with fatal taint checks turned into warnings. Note that the -w switch (or the $^W variable) must be used along with this option to actually generate the taint-check warnings.

-v

prints the version and patchlevel of your perl executable.

-V

prints summary of the major perl configuration values and the current values of @INC.

-V:configvar

Prints to STDOUT the value of the named configuration variable(s), with multiples when your configvar argument looks like a regex (has non-letters). For example:

    $ perl -V:libc
        libc='/lib/libc-2.2.4.so';
    $ perl -V:lib.
        libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
        libc='/lib/libc-2.2.4.so';
    $ perl -V:lib.*
        libpth='/usr/local/lib /lib /usr/lib';
        libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
        lib_ext='.a';
        libc='/lib/libc-2.2.4.so';
        libperl='libperl.a';
        ....

Additionally, extra colons can be used to control formatting. A trailing colon suppresses the linefeed and terminator ';', allowing you to embed queries into shell commands. (mnemonic: PATH separator ':'.)

    $ echo "compression-vars: " `perl -V:z.*: ` " are here !"
    compression-vars:  zcat='' zip='zip'  are here !

A leading colon removes the 'name=' part of the response, this allows you to map to the name you need. (mnemonic: empty label)

    $ echo "goodvfork="`./perl -Ilib -V::usevfork`
    goodvfork=false;

Leading and trailing colons can be used together if you need positional parameter values without the names. Note that in the case below, the PERL_API params are returned in alphabetical order.

    $ echo building_on `perl -V::osname: -V::PERL_API_.*:` now
    building_on 'linux' '5' '1' '9' now
-w

prints warnings about dubious constructs, such as variable names that are mentioned only once and scalar variables that are used before being set, redefined subroutines, references to undefined filehandles or filehandles opened read-only that you are attempting to write on, values used as a number that don't look like numbers, using an array as though it were a scalar, if your subroutines recurse more than 100 deep, and innumerable other things.

This switch really just enables the internal $^W variable. You can disable or promote into fatal errors specific warnings using __WARN__ hooks, as described in the perlvar manpage and warn in the perlfunc manpage. See also the perldiag manpage and the perltrap manpage. A new, fine-grained warning facility is also available if you want to manipulate entire classes of warnings; see the warnings manpage or the perllexwarn manpage.

-W

Enables all warnings regardless of no warnings or $^W. See the perllexwarn manpage.

-X

Disables all warnings regardless of use warnings or $^W. See the perllexwarn manpage.

-x
-x directory

tells Perl that the program is embedded in a larger chunk of unrelated ASCII text, such as in a mail message. Leading garbage will be discarded until the first line that starts with #! and contains the string "perl". Any meaningful switches on that line will be applied. If a directory name is specified, Perl will switch to that directory before running the program. The -x switch controls only the disposal of leading garbage. The program must be terminated with __END__ if there is trailing garbage to be ignored (the program can process any or all of the trailing garbage via the DATA filehandle if desired).

ENVIRONMENT

HOME

Used if chdir has no argument.

LOGDIR

Used if chdir has no argument and HOME is not set.

PATH

Used in executing subprocesses, and in finding the program if -S is used.

PERL5LIB

A list of directories in which to look for Perl library files before looking in the standard library and the current directory. Any architecture-specific directories under the specified locations are automatically included if they exist. If PERL5LIB is not defined, PERLLIB is used. Directories are separated (like in PATH) by a colon on unixish platforms and by a semicolon on Windows (the proper path separator being given by the command perl -V:path_sep).

When running taint checks (either because the program was running setuid or setgid, or the -T switch was used), neither variable is used. The program should instead say:

    use lib "/my/directory";
PERL5OPT

Command-line options (switches). Switches in this variable are taken as if they were on every Perl command line. Only the -[DIMUdmtw] switches are allowed. When running taint checks (because the program was running setuid or setgid, or the -T switch was used), this variable is ignored. If PERL5OPT begins with -T, tainting will be enabled, and any subsequent options ignored.

PERLIO

A space (or colon) separated list of PerlIO layers. If perl is built to use PerlIO system for IO (the default) these layers effect perl's IO.

It is conventional to start layer names with a colon e.g. :perlio to emphasise their similarity to variable "attributes". But the code that parses layer specification strings (which is also used to decode the PERLIO environment variable) treats the colon as a separator.

An unset or empty PERLIO is equivalent to :stdio.

The list becomes the default for all perl's IO. Consequently only built-in layers can appear in this list, as external layers (such as :encoding()) need IO in order to load them!. See "open pragma" for how to add external encodings as defaults.

The layers that it makes sense to include in the PERLIO environment variable are briefly summarised below. For more details see the PerlIO manpage.

:bytes

A pseudolayer that turns off the :utf8 flag for the layer below. Unlikely to be useful on its own in the global PERLIO environment variable. You perhaps were thinking of :crlf:bytes or :perlio:bytes.

:crlf

A layer which does CRLF to "\n" translation distinguishing "text" and "binary" files in the manner of MS-DOS and similar operating systems. (It currently does not mimic MS-DOS as far as treating of Control-Z as being an end-of-file marker.)

:mmap

A layer which implements "reading" of files by using mmap() to make (whole) file appear in the process's address space, and then using that as PerlIO's "buffer".

:perlio

This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer". As such it will call whatever layer is below it for its operations (typically :unix).

:pop

An experimental pseudolayer that removes the topmost layer. Use with the same care as is reserved for nitroglycerin.

:raw

A pseudolayer that manipulates other layers. Applying the :raw layer is equivalent to calling binmode($fh). It makes the stream pass each byte as-is without any translation. In particular CRLF translation, and/or :utf8 intuited from locale are disabled.

Unlike in the earlier versions of Perl :raw is not just the inverse of :crlf - other layers which would affect the binary nature of the stream are also removed or disabled.

:stdio

This layer provides PerlIO interface by wrapping system's ANSI C "stdio" library calls. The layer provides both buffering and IO. Note that :stdio layer does not do CRLF translation even if that is platforms normal behaviour. You will need a :crlf layer above it to do that.

:unix

Low level layer which calls read, write and lseek etc.

:utf8

A pseudolayer that turns on a flag on the layer below to tell perl that output should be in utf8 and that input should be regarded as already in utf8 form. May be useful in PERLIO environment variable to make UTF-8 the default. (To turn off that behaviour use :bytes layer.)

:win32

On Win32 platforms this experimental layer uses native "handle" IO rather than unix-like numeric file descriptor layer. Known to be buggy in this release.

On all platforms the default set of layers should give acceptable results.

For UNIX platforms that will equivalent of "unix perlio" or "stdio". Configure is setup to prefer "stdio" implementation if system's library provides for fast access to the buffer, otherwise it uses the "unix perlio" implementation.

On Win32 the default in this release is "unix crlf". Win32's "stdio" has a number of bugs/mis-features for perl IO which are somewhat C compiler vendor/version dependent. Using our own crlf layer as the buffer avoids those issues and makes things more uniform. The crlf layer provides CRLF to/from "\n" conversion as well as buffering.

This release uses unix as the bottom layer on Win32 and so still uses C compiler's numeric file descriptor routines. There is an experimental native win32 layer which is expected to be enhanced and should eventually be the default under Win32.

PERLIO_DEBUG

If set to the name of a file or device then certain operations of PerlIO sub-system will be logged to that file (opened as append). Typical uses are UNIX:

   PERLIO_DEBUG=/dev/tty perl script ...

and Win32 approximate equivalent:

   set PERLIO_DEBUG=CON
   perl script ...

This functionality is disabled for setuid scripts and for scripts run with -T.

PERLLIB

A list of directories in which to look for Perl library files before looking in the standard library and the current directory. If PERL5LIB is defined, PERLLIB is not used.

PERL5DB

The command used to load the debugger code. The default is:

        BEGIN { require 'perl5db.pl' }
PERL5DB_THREADED

If set to a true value, indicates to the debugger that the code being debugged uses threads.

PERL5SHELL (specific to the Win32 port)

May be set to an alternative shell that perl must use internally for executing "backtick" commands or system(). Default is cmd.exe /x/d/c on WindowsNT and command.com /c on Windows95. The value is considered to be space-separated. Precede any character that needs to be protected (like a space or backslash) with a backslash.

Note that Perl doesn't use COMSPEC for this purpose because COMSPEC has a high degree of variability among users, leading to portability concerns. Besides, perl can use a shell that may not be fit for interactive use, and setting COMSPEC to such a shell may interfere with the proper functioning of other programs (which usually look in COMSPEC to find a shell fit for interactive use).

PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)

Set to 1 to allow the use of non-IFS compatible LSP's. Perl normally searches for an IFS-compatible LSP because this is required for its emulation of Windows sockets as real filehandles. However, this may cause problems if you have a firewall such as McAfee Guardian which requires all applications to use its LSP which is not IFS-compatible, because clearly Perl will normally avoid using such an LSP. Setting this environment variable to 1 means that Perl will simply use the first suitable LSP enumerated in the catalog, which keeps McAfee Guardian happy (and in that particular case Perl still works too because McAfee Guardian's LSP actually plays some other games which allow applications requiring IFS compatibility to work).

PERL_DEBUG_MSTATS

Relevant only if perl is compiled with the malloc included with the perl distribution (that is, if perl -V:d_mymalloc is 'define'). If set, this causes memory statistics to be dumped after execution. If set to an integer greater than one, also causes memory statistics to be dumped after compilation.

PERL_DESTRUCT_LEVEL

Relevant only if your perl executable was built with -DDEBUGGING, this controls the behavior of global destruction of objects and other references. See PERL_DESTRUCT_LEVEL in the perlhack manpage for more information.

PERL_DL_NONLAZY

Set to one to have perl resolve all undefined symbols when it loads a dynamic library. The default behaviour is to resolve symbols when they are used. Setting this variable is useful during testing of extensions as it ensures that you get an error on misspelled function names even if the test suite doesn't call it.

PERL_ENCODING

If using the encoding pragma without an explicit encoding name, the PERL_ENCODING environment variable is consulted for an encoding name.

PERL_HASH_SEED

(Since Perl 5.8.1.) Used to randomise Perl's internal hash function. To emulate the pre-5.8.1 behaviour, set to an integer (zero means exactly the same order as 5.8.0). "Pre-5.8.1" means, among other things, that hash keys will be ordered the same between different runs of Perl.

The default behaviour is to randomise unless the PERL_HASH_SEED is set. If Perl has been compiled with -DUSE_HASH_SEED_EXPLICIT, the default behaviour is not to randomise unless the PERL_HASH_SEED is set.

If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses the pseudorandom seed supplied by the operating system and libraries. This means that each different run of Perl will have a different ordering of the results of keys(), values(), and each().

Please note that the hash seed is sensitive information. Hashes are randomized to protect against local and remote attacks against Perl code. By manually setting a seed this protection may be partially or completely lost.

See Algorithmic Complexity Attacks in the perlsec manpage and PERL_HASH_SEED_DEBUG for more information.

PERL_HASH_SEED_DEBUG

(Since Perl 5.8.1.) Set to one to display (to STDERR) the value of the hash seed at the beginning of execution. This, combined with PERL_HASH_SEED is intended to aid in debugging nondeterministic behavior caused by hash randomization.

Note that the hash seed is sensitive information: by knowing it one can craft a denial-of-service attack against Perl code, even remotely, see Algorithmic Complexity Attacks in the perlsec manpage for more information. Do not disclose the hash seed to people who don't need to know it. See also hash_seed() of the Hash::Util manpage.

PERL_ROOT (specific to the VMS port)

A translation concealed rooted logical name that contains perl and the logical device for the @INC path on VMS only. Other logical names that affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in the perlvms manpage and in README.vms in the Perl source distribution.

PERL_SIGNALS

In Perls 5.8.1 and later. If set to unsafe the pre-Perl-5.8.0 signals behaviour (immediate but unsafe) is restored. If set to safe the safe (or deferred) signals are used. See Deferred Signals (Safe Signals) in the perlipc manpage.

PERL_UNICODE

Equivalent to the -C command-line switch. Note that this is not a boolean variable-- setting this to "1" is not the right way to "enable Unicode" (whatever that would mean). You can use "0" to "disable Unicode", though (or alternatively unset PERL_UNICODE in your shell before starting Perl). See the description of the -C switch for more information.

SYS$LOGIN (specific to the VMS port)

Used if chdir has no argument and HOME and LOGDIR are not set.

Perl also has environment variables that control how Perl handles data specific to particular natural languages. See the perllocale manpage.

Apart from these, Perl uses no other environment variables, except to make them available to the program being executed, and to child processes. However, programs running setuid would do well to execute the following lines before doing anything else, just to keep people honest:

    $ENV{PATH}  = '/bin:/usr/bin';    # or whatever you need
    $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
    delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};


perlapi - autogenerated documentation for the perl public API

  • "Gimme" Values
  • Array Manipulation Functions
  • Callback Functions
  • Character classes
  • Cloning an interpreter
  • CV Manipulation Functions
  • Embedding Functions
  • Functions in file pp_pack.c
  • Global Variables
  • GV Functions
  • Handy Values
  • Hash Manipulation Functions
  • Magical Functions
  • Memory Management
  • Miscellaneous Functions
  • Numeric functions
  • Optree Manipulation Functions
  • Pad Data Structures
  • Stack Manipulation Macros
  • SV Flags
  • SV Manipulation Functions
  • Unicode Support
  • Variables created by xsubpp and xsubpp internal functions
  • Warning and Dieing
  • AUTHORS
  • SEE ALSO

NAME

perlapi - autogenerated documentation for the perl public API

DESCRIPTION

This file contains the documentation of the perl public API generated by embed.pl, specifically a listing of functions, macros, flags, and variables that may be used by extension writers. The interfaces of any functions that are not listed here are subject to change without notice. For this reason, blindly using functions listed in proto.h is to be avoided when writing extensions.

Note that all Perl API global variables must be referenced with the PL_ prefix. Some macros are provided for compatibility with the older, unadorned names, but this support may be disabled in a future release.

The listing is alphabetical, case insensitive.

"Gimme" Values

GIMME

A backward-compatible version of GIMME_V which can only return G_SCALAR or G_ARRAY; in a void context, it returns G_SCALAR. Deprecated. Use GIMME_V instead.

        U32     GIMME
GIMME_V

The XSUB-writer's equivalent to Perl's wantarray. Returns G_VOID, G_SCALAR or G_ARRAY for void, scalar or list context, respectively.

        U32     GIMME_V
G_ARRAY

Used to indicate list context. See GIMME_V, GIMME and the perlcall manpage.

G_DISCARD

Indicates that arguments returned from a callback should be discarded. See the perlcall manpage.

G_EVAL

Used to force a Perl eval wrapper around a callback. See the perlcall manpage.

G_NOARGS

Indicates that no arguments are being sent to a callback. See the perlcall manpage.

G_SCALAR

Used to indicate scalar context. See GIMME_V, GIMME, and the perlcall manpage.

G_VOID

Used to indicate void context. See GIMME_V and the perlcall manpage.

Array Manipulation Functions

AvFILL

Same as av_len(). Deprecated, use av_len() instead.

        int     AvFILL(AV* av)
av_clear

Clears an array, making it empty. Does not free the memory used by the array itself.

        void    av_clear(AV* ar)
av_delete

Deletes the element indexed by key from the array. Returns the deleted element. If flags equals G_DISCARD, the element is freed and null is returned.

        SV*     av_delete(AV* ar, I32 key, I32 flags)
av_exists

Returns true if the element indexed by key has been initialized.

This relies on the fact that uninitialized array elements are set to &PL_sv_undef.

        bool    av_exists(AV* ar, I32 key)
av_extend

Pre-extend an array. The key is the index to which the array should be extended.

        void    av_extend(AV* ar, I32 key)
av_fetch

Returns the SV at the specified index in the array. The key is the index. If lval is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to a SV*.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied arrays.

        SV**    av_fetch(AV* ar, I32 key, I32 lval)
av_fill

Ensure than an array has a given number of elements, equivalent to Perl's $#array = $fill;.

        void    av_fill(AV* ar, I32 fill)
av_len

Returns the highest index in the array. Returns -1 if the array is empty.

        I32     av_len(AV* ar)
av_make

Creates a new AV and populates it with a list of SVs. The SVs are copied into the array, so they may be freed after the call to av_make. The new AV will have a reference count of 1.

        AV*     av_make(I32 size, SV** svp)
av_pop

Pops an SV off the end of the array. Returns &PL_sv_undef if the array is empty.

        SV*     av_pop(AV* ar)
av_push

Pushes an SV onto the end of the array. The array will grow automatically to accommodate the addition.

        void    av_push(AV* ar, SV* val)
av_shift

Shifts an SV off the beginning of the array.

        SV*     av_shift(AV* ar)
av_store

Stores an SV in an array. The array index is specified as key. The return value will be NULL if the operation failed or if the value did not need to be actually stored within the array (as in the case of tied arrays). Otherwise it can be dereferenced to get the original SV*. Note that the caller is responsible for suitably incrementing the reference count of val before the call, and decrementing it if the function returned NULL.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied arrays.

        SV**    av_store(AV* ar, I32 key, SV* val)
av_undef

Undefines the array. Frees the memory used by the array itself.

        void    av_undef(AV* ar)
av_unshift

Unshift the given number of undef values onto the beginning of the array. The array will grow automatically to accommodate the addition. You must then use av_store to assign values to these new elements.

        void    av_unshift(AV* ar, I32 num)
get_av

Returns the AV of the specified Perl array. If create is set and the Perl variable does not exist then it will be created. If create is not set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

        AV*     get_av(const char* name, I32 create)
newAV

Creates a new AV. The reference count is set to 1.

        AV*     newAV()
sortsv

Sort an array. Here is an example:

    sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);

See lib/sort.pm for details about controlling the sorting algorithm.

        void    sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)

Callback Functions

call_argv

Performs a callback to the specified Perl sub. See the perlcall manpage.

NOTE: the perl_ form of this function is deprecated.

        I32     call_argv(const char* sub_name, I32 flags, char** argv)
call_method

Performs a callback to the specified Perl method. The blessed object must be on the stack. See the perlcall manpage.

NOTE: the perl_ form of this function is deprecated.

        I32     call_method(const char* methname, I32 flags)
call_pv

Performs a callback to the specified Perl sub. See the perlcall manpage.

NOTE: the perl_ form of this function is deprecated.

        I32     call_pv(const char* sub_name, I32 flags)
call_sv

Performs a callback to the Perl sub whose name is in the SV. See the perlcall manpage.

NOTE: the perl_ form of this function is deprecated.

        I32     call_sv(SV* sv, I32 flags)
ENTER

Opening bracket on a callback. See LEAVE and the perlcall manpage.

                ENTER;
eval_pv

Tells Perl to eval the given string and return an SV* result.

NOTE: the perl_ form of this function is deprecated.

        SV*     eval_pv(const char* p, I32 croak_on_error)
eval_sv

Tells Perl to eval the string in the SV.

NOTE: the perl_ form of this function is deprecated.

        I32     eval_sv(SV* sv, I32 flags)
FREETMPS

Closing bracket for temporaries on a callback. See SAVETMPS and the perlcall manpage.

                FREETMPS;
LEAVE

Closing bracket on a callback. See ENTER and the perlcall manpage.

                LEAVE;
SAVETMPS

Opening bracket for temporaries on a callback. See FREETMPS and the perlcall manpage.

                SAVETMPS;

Character classes

isALNUM

Returns a boolean indicating whether the C char is an ASCII alphanumeric character (including underscore) or digit.

        bool    isALNUM(char ch)
isALPHA

Returns a boolean indicating whether the C char is an ASCII alphabetic character.

        bool    isALPHA(char ch)
isDIGIT

Returns a boolean indicating whether the C char is an ASCII digit.

        bool    isDIGIT(char ch)
isLOWER

Returns a boolean indicating whether the C char is a lowercase character.

        bool    isLOWER(char ch)
isSPACE

Returns a boolean indicating whether the C char is whitespace.

        bool    isSPACE(char ch)
isUPPER

Returns a boolean indicating whether the C char is an uppercase character.

        bool    isUPPER(char ch)
toLOWER

Converts the specified character to lowercase.

        char    toLOWER(char ch)
toUPPER

Converts the specified character to uppercase.

        char    toUPPER(char ch)

Cloning an interpreter

perl_clone

Create and return a new interpreter by cloning the current one.

perl_clone takes these flags as parameters:

CLONEf_COPY_STACKS - is used to, well, copy the stacks also, without it we only clone the data and zero the stacks, with it we copy the stacks and the new perl interpreter is ready to run at the exact same point as the previous one. The pseudo-fork code uses COPY_STACKS while the threads->new doesn't.

CLONEf_KEEP_PTR_TABLE perl_clone keeps a ptr_table with the pointer of the old variable as a key and the new variable as a value, this allows it to check if something has been cloned and not clone it again but rather just use the value and increase the refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill the ptr_table using the function ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;, reason to keep it around is if you want to dup some of your own variable who are outside the graph perl scans, example of this code is in threads.xs create

CLONEf_CLONE_HOST This is a win32 thing, it is ignored on unix, it tells perls win32host code (which is c++) to clone itself, this is needed on win32 if you want to run two threads at the same time, if you just want to do some stuff in a separate perl interpreter and then throw it away and return to the original one, you don't need to do anything.

        PerlInterpreter*        perl_clone(PerlInterpreter* interp, UV flags)

CV Manipulation Functions

CvSTASH

Returns the stash of the CV.

        HV*     CvSTASH(CV* cv)
get_cv

Returns the CV of the specified Perl subroutine. If create is set and the Perl subroutine does not exist then it will be declared (which has the same effect as saying sub name;). If create is not set and the subroutine does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

        CV*     get_cv(const char* name, I32 create)

Embedding Functions

cv_undef

Clear out all the active components of a CV. This can happen either by an explicit undef &foo, or by the reference count going to zero. In the former case, we keep the CvOUTSIDE pointer, so that any anonymous children can still follow the full lexical scope chain.

        void    cv_undef(CV* cv)
load_module

Loads the module whose name is pointed to by the string part of name. Note that the actual module name, not its filename, should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if specified, provides version semantics similar to use Foo::Bar VERSION. The optional trailing SV* arguments can be used to specify arguments to the module's import() method, similar to use Foo::Bar VERSION LIST.

        void    load_module(U32 flags, SV* name, SV* ver, ...)
nothreadhook

Stub that provides thread hook for perl_destruct when there are no threads.

        int     nothreadhook()
perl_alloc

Allocates a new Perl interpreter. See the perlembed manpage.

        PerlInterpreter*        perl_alloc()
perl_construct

Initializes a new Perl interpreter. See the perlembed manpage.

        void    perl_construct(PerlInterpreter* interp)
perl_destruct

Shuts down a Perl interpreter. See the perlembed manpage.

        int     perl_destruct(PerlInterpreter* interp)
perl_free

Releases a Perl interpreter. See the perlembed manpage.

        void    perl_free(PerlInterpreter* interp)
perl_parse

Tells a Perl interpreter to parse a Perl script. See the perlembed manpage.

        int     perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
perl_run

Tells a Perl interpreter to run. See the perlembed manpage.

        int     perl_run(PerlInterpreter* interp)
require_pv

Tells Perl to require the file named by the string argument. It is analogous to the Perl code eval "require '$file'". It's even implemented that way; consider using load_module instead.

NOTE: the perl_ form of this function is deprecated.

        void    require_pv(const char* pv)

Functions in file pp_pack.c

packlist

The engine implementing pack() Perl function.

        void    packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist)
pack_cat

The engine implementing pack() Perl function. Note: parameters next_in_list and flags are not used. This call should not be used; use packlist instead.

        void    pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
unpackstring

The engine implementing unpack() Perl function. unpackstring puts the extracted list items on the stack and returns the number of elements. Issue PUTBACK before and SPAGAIN after the call to this function.

        I32     unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)
unpack_str

The engine implementing unpack() Perl function. Note: parameters strbeg, new_s and ocnt are not used. This call should not be used, use unpackstring instead.

        I32     unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)

Global Variables

PL_modglobal

PL_modglobal is a general purpose, interpreter global HV for use by extensions that need to keep information on a per-interpreter basis. In a pinch, it can also be used as a symbol table for extensions to share data among each other. It is a good idea to use keys prefixed by the package name of the extension that owns the data.

        HV*     PL_modglobal
PL_na

A convenience variable which is typically used with SvPV when one doesn't care about the length of the string. It is usually more efficient to either declare a local variable and use that instead or to use the SvPV_nolen macro.

        STRLEN  PL_na
PL_sv_no

This is the false SV. See PL_sv_yes. Always refer to this as &PL_sv_no.

        SV      PL_sv_no
PL_sv_undef

This is the undef SV. Always refer to this as &PL_sv_undef.

        SV      PL_sv_undef
PL_sv_yes

This is the true SV. See PL_sv_no. Always refer to this as &PL_sv_yes.

        SV      PL_sv_yes

GV Functions

GvSV

Return the SV from the GV.

        SV*     GvSV(GV* gv)
gv_fetchmeth

Returns the glob with the given name and a defined subroutine or NULL. The glob lives in the given stash, or in the stashes accessible via @ISA and UNIVERSAL::.

The argument level should be either 0 or -1. If level==0, as a side-effect creates a glob with the given name in the given stash which in the case of success contains an alias for the subroutine, and sets up caching info for this glob. Similarly for all the searched stashes.

This function grants "SUPER" token as a postfix of the stash name. The GV returned from gv_fetchmeth may be a method cache entry, which is not visible to Perl code. So when calling call_sv, you should not use the GV directly; instead, you should use the method's CV, which can be obtained from the GV with the GvCV macro.

        GV*     gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
gv_fetchmethod

See gv_fetchmethod_autoload.

        GV*     gv_fetchmethod(HV* stash, const char* name)
gv_fetchmethod_autoload

Returns the glob which contains the subroutine to call to invoke the method on the stash. In fact in the presence of autoloading this may be the glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is already setup.

The third parameter of gv_fetchmethod_autoload determines whether AUTOLOAD lookup is performed if the given method is not present: non-zero means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling gv_fetchmethod is equivalent to calling gv_fetchmethod_autoload with a non-zero autoload parameter.

These functions grant "SUPER" token as a prefix of the method name. Note that if you want to keep the returned glob for a long time, you need to check for it being "AUTOLOAD", since at the later time the call may load a different subroutine due to $AUTOLOAD changing its value. Use the glob created via a side effect to do this.

These functions have the same side-effects and as gv_fetchmeth with level==0. name should be writable if contains ':' or ' ''. The warning against passing the GV returned by gv_fetchmeth to call_sv apply equally to these functions.

        GV*     gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
gv_fetchmeth_autoload

Same as gv_fetchmeth(), but looks for autoloaded subroutines too. Returns a glob for the subroutine.

For an autoloaded subroutine without a GV, will create a GV even if level < 0. For an autoloaded subroutine without a stub, GvCV() of the result may be zero.

        GV*     gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
gv_stashpv

Returns a pointer to the stash for a specified package. name should be a valid UTF-8 string and must be null-terminated. If create is set then the package will be created if it does not already exist. If create is not set and the package does not exist then NULL is returned.

        HV*     gv_stashpv(const char* name, I32 create)
gv_stashpvn

Returns a pointer to the stash for a specified package. name should be a valid UTF-8 string. The namelen parameter indicates the length of the name, in bytes. If create is set then the package will be created if it does not already exist. If create is not set and the package does not exist then NULL is returned.

        HV*     gv_stashpvn(const char* name, U32 namelen, I32 create)
gv_stashsv

Returns a pointer to the stash for a specified package, which must be a valid UTF-8 string. See gv_stashpv.

        HV*     gv_stashsv(SV* sv, I32 create)

Handy Values

Nullav

Null AV pointer.

Nullch

Null character pointer.

Nullcv

Null CV pointer.

Nullhv

Null HV pointer.

Nullsv

Null SV pointer.

Hash Manipulation Functions

get_hv

Returns the HV of the specified Perl hash. If create is set and the Perl variable does not exist then it will be created. If create is not set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

        HV*     get_hv(const char* name, I32 create)
HEf_SVKEY

This flag, used in the length slot of hash entries and magic structures, specifies the structure contains an SV* pointer where a char* pointer is to be expected. (For information only--not to be used).

HeHASH

Returns the computed hash stored in the hash entry.

        U32     HeHASH(HE* he)
HeKEY

Returns the actual pointer stored in the key slot of the hash entry. The pointer may be either char* or SV*, depending on the value of HeKLEN(). Can be assigned to. The HePV() or HeSVKEY() macros are usually preferable for finding the value of a key.

        void*   HeKEY(HE* he)
HeKLEN

If this is negative, and amounts to HEf_SVKEY, it indicates the entry holds an SV* key. Otherwise, holds the actual length of the key. Can be assigned to. The HePV() macro is usually preferable for finding key lengths.

        STRLEN  HeKLEN(HE* he)
HePV

Returns the key slot of the hash entry as a char* value, doing any necessary dereferencing of possibly SV* keys. The length of the string is placed in len (this is a macro, so do not use &len). If you do not care about what the length of the key is, you may use the global variable PL_na, though this is rather less efficient than using a local variable. Remember though, that hash keys in perl are free to contain embedded nulls, so using strlen() or similar is not a good way to find the length of hash keys. This is very similar to the SvPV() macro described elsewhere in this document.

        char*   HePV(HE* he, STRLEN len)
HeSVKEY

Returns the key as an SV*, or Nullsv if the hash entry does not contain an SV* key.

        SV*     HeSVKEY(HE* he)
HeSVKEY_force

Returns the key as an SV*. Will create and return a temporary mortal SV* if the hash entry contains only a char* key.

        SV*     HeSVKEY_force(HE* he)
HeSVKEY_set

Sets the key to a given SV*, taking care to set the appropriate flags to indicate the presence of an SV* key, and returns the same SV*.

        SV*     HeSVKEY_set(HE* he, SV* sv)
HeVAL

Returns the value slot (type SV*) stored in the hash entry.

        SV*     HeVAL(HE* he)
HvNAME

Returns the package name of a stash, or NULL if stash isn't a stash. See SvSTASH, CvSTASH.

        char*   HvNAME(HV* stash)
hv_clear

Clears a hash, making it empty.

        void    hv_clear(HV* tb)
hv_clear_placeholders

Clears any placeholders from a hash. If a restricted hash has any of its keys marked as readonly and the key is subsequently deleted, the key is not actually deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags it so it will be ignored by future operations such as iterating over the hash, but will still allow the hash to have a value reassigned to the key at some future point. This function clears any such placeholder keys from the hash. See Hash::Util::lock_keys() for an example of its use.

        void    hv_clear_placeholders(HV* hb)
hv_delete

Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The klen is the length of the key. The flags value will normally be zero; if set to G_DISCARD then NULL will be returned.

        SV*     hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
hv_delete_ent

Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The flags value will normally be zero; if set to G_DISCARD then NULL will be returned. hash can be a valid precomputed hash value, or 0 to ask for it to be computed.

        SV*     hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
hv_exists

Returns a boolean indicating whether the specified hash key exists. The klen is the length of the key.

        bool    hv_exists(HV* tb, const char* key, I32 klen)
hv_exists_ent

Returns a boolean indicating whether the specified hash key exists. hash can be a valid precomputed hash value, or 0 to ask for it to be computed.

        bool    hv_exists_ent(HV* tb, SV* key, U32 hash)
hv_fetch

Returns the SV which corresponds to the specified key in the hash. The klen is the length of the key. If lval is set then the fetch will be part of a store. Check that the return value is non-null before dereferencing it to an SV*.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied hashes.

        SV**    hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
hv_fetch_ent

Returns the hash entry which corresponds to the specified key in the hash. hash must be a valid precomputed hash number for the given key, or 0 if you want the function to compute it. IF lval is set then the fetch will be part of a store. Make sure the return value is non-null before accessing it. The return value when tb is a tied hash is a pointer to a static location, so be sure to make a copy of the structure if you need to store it somewhere.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied hashes.

        HE*     hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
hv_iterinit

Prepares a starting point to traverse a hash table. Returns the number of keys in the hash (i.e. the same as HvKEYS(tb)). The return value is currently only meaningful for hashes without tie magic.

NOTE: Before version 5.004_65, hv_iterinit used to return the number of hash buckets that happen to be in use. If you still need that esoteric value, you can get it through the macro HvFILL(tb).

        I32     hv_iterinit(HV* tb)
hv_iterkey

Returns the key from the current position of the hash iterator. See hv_iterinit.

        char*   hv_iterkey(HE* entry, I32* retlen)
hv_iterkeysv

Returns the key as an SV* from the current position of the hash iterator. The return value will always be a mortal copy of the key. Also see hv_iterinit.

        SV*     hv_iterkeysv(HE* entry)
hv_iternext

Returns entries from a hash iterator. See hv_iterinit.

You may call hv_delete or hv_delete_ent on the hash entry that the iterator currently points to, without losing your place or invalidating your iterator. Note that in this case the current entry is deleted from the hash with your iterator holding the last reference to it. Your iterator is flagged to free the entry on the next call to hv_iternext, so you must not discard your iterator immediately else the entry will leak - call hv_iternext to trigger the resource deallocation.

        HE*     hv_iternext(HV* tb)
hv_iternextsv

Performs an hv_iternext, hv_iterkey, and hv_iterval in one operation.

        SV*     hv_iternextsv(HV* hv, char** key, I32* retlen)
hv_iternext_flags

Returns entries from a hash iterator. See hv_iterinit and hv_iternext. The flags value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is set the placeholders keys (for restricted hashes) will be returned in addition to normal keys. By default placeholders are automatically skipped over. Currently a placeholder is implemented with a value that is &Perl_sv_placeholder. Note that the implementation of placeholders and restricted hashes may change, and the implementation currently is insufficiently abstracted for any change to be tidy.

NOTE: this function is experimental and may change or be removed without notice.

        HE*     hv_iternext_flags(HV* tb, I32 flags)
hv_iterval

Returns the value from the current position of the hash iterator. See hv_iterkey.

        SV*     hv_iterval(HV* tb, HE* entry)
hv_magic

Adds magic to a hash. See sv_magic.

        void    hv_magic(HV* hv, GV* gv, int how)
hv_scalar

Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.

        SV*     hv_scalar(HV* hv)
hv_store

Stores an SV in a hash. The hash key is specified as key and klen is the length of the key. The hash parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value will be NULL if the operation failed or if the value did not need to be actually stored within the hash (as in the case of tied hashes). Otherwise it can be dereferenced to get the original SV*. Note that the caller is responsible for suitably incrementing the reference count of val before the call, and decrementing it if the function returned NULL. Effectively a successful hv_store takes ownership of one reference to val. This is usually what you want; a newly created SV has a reference count of one, so if all your code does is create SVs then store them in a hash, hv_store will own the only reference to the new SV, and your code doesn't need to do anything further to tidy up. hv_store is not implemented as a call to hv_store_ent, and does not create a temporary SV for the key, so if your key data is not already in SV form then use hv_store in preference to hv_store_ent.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied hashes.

        SV**    hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
hv_store_ent

Stores val in a hash. The hash key is specified as key. The hash parameter is the precomputed hash value; if it is zero then Perl will compute it. The return value is the new hash entry so created. It will be NULL if the operation failed or if the value did not need to be actually stored within the hash (as in the case of tied hashes). Otherwise the contents of the return value can be accessed using the He? macros described here. Note that the caller is responsible for suitably incrementing the reference count of val before the call, and decrementing it if the function returned NULL. Effectively a successful hv_store_ent takes ownership of one reference to val. This is usually what you want; a newly created SV has a reference count of one, so if all your code does is create SVs then store them in a hash, hv_store will own the only reference to the new SV, and your code doesn't need to do anything further to tidy up. Note that hv_store_ent only reads the key; unlike val it does not take ownership of it, so maintaining the correct reference count on key is entirely the caller's responsibility. hv_store is not implemented as a call to hv_store_ent, and does not create a temporary SV for the key, so if your key data is not already in SV form then use hv_store in preference to hv_store_ent.

See Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage for more information on how to use this function on tied hashes.

        HE*     hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
hv_undef

Undefines the hash.

        void    hv_undef(HV* tb)
newHV

Creates a new HV. The reference count is set to 1.

        HV*     newHV()

Magical Functions

mg_clear

Clear something magical that the SV represents. See sv_magic.

        int     mg_clear(SV* sv)
mg_copy

Copies the magic from one SV to another. See sv_magic.

        int     mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
mg_find

Finds the magic pointer for type matching the SV. See sv_magic.

        MAGIC*  mg_find(SV* sv, int type)
mg_free

Free any magic storage used by the SV. See sv_magic.

        int     mg_free(SV* sv)
mg_get

Do magic after a value is retrieved from the SV. See sv_magic.

        int     mg_get(SV* sv)
mg_length

Report on the SV's length. See sv_magic.

        U32     mg_length(SV* sv)
mg_magical

Turns on the magical status of an SV. See sv_magic.

        void    mg_magical(SV* sv)
mg_set

Do magic after a value is assigned to the SV. See sv_magic.

        int     mg_set(SV* sv)
SvGETMAGIC

Invokes mg_get on an SV if it has 'get' magic. This macro evaluates its argument more than once.

        void    SvGETMAGIC(SV* sv)
SvLOCK

Arranges for a mutual exclusion lock to be obtained on sv if a suitable module has been loaded.

        void    SvLOCK(SV* sv)
SvSETMAGIC

Invokes mg_set on an SV if it has 'set' magic. This macro evaluates its argument more than once.

        void    SvSETMAGIC(SV* sv)
SvSetMagicSV

Like SvSetSV, but does any set magic required afterwards.

        void    SvSetMagicSV(SV* dsb, SV* ssv)
SvSetMagicSV_nosteal

Like SvSetSV_nosteal, but does any set magic required afterwards.

        void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
SvSetSV

Calls sv_setsv if dsv is not the same as ssv. May evaluate arguments more than once.

        void    SvSetSV(SV* dsb, SV* ssv)
SvSetSV_nosteal

Calls a non-destructive version of sv_setsv if dsv is not the same as ssv. May evaluate arguments more than once.

        void    SvSetSV_nosteal(SV* dsv, SV* ssv)
SvSHARE

Arranges for sv to be shared between threads if a suitable module has been loaded.

        void    SvSHARE(SV* sv)
SvUNLOCK

Releases a mutual exclusion lock on sv if a suitable module has been loaded.

        void    SvUNLOCK(SV* sv)

Memory Management

Copy

The XSUB-writer's interface to the C memcpy function. The src is the source, dest is the destination, nitems is the number of items, and type is the type. May fail on overlapping copies. See also Move.

        void    Copy(void* src, void* dest, int nitems, type)
CopyD

Like Copy but returns dest. Useful for encouraging compilers to tail-call optimise.

        void *  CopyD(void* src, void* dest, int nitems, type)
Move

The XSUB-writer's interface to the C memmove function. The src is the source, dest is the destination, nitems is the number of items, and type is the type. Can do overlapping moves. See also Copy.

        void    Move(void* src, void* dest, int nitems, type)
MoveD

Like Move but returns dest. Useful for encouraging compilers to tail-call optimise.

        void *  MoveD(void* src, void* dest, int nitems, type)
Newx

The XSUB-writer's interface to the C malloc function.

        void    Newx(void* ptr, int nitems, type)
Newxc

The XSUB-writer's interface to the C malloc function, with cast.

        void    Newxc(void* ptr, int nitems, type, cast)
Newxz

The XSUB-writer's interface to the C malloc function. The allocated memory is zeroed with memzero.

In 5.9.3, we removed the 1st parameter, a debug aid, from the api. It was used to uniquely identify each usage of these allocation functions, but was deemed unnecessary with the availability of better memory tracking tools, valgrind for example.

        void    Newxz(void* ptr, int nitems, type)
Poison

Fill up memory with a pattern (byte 0xAB over and over again) that hopefully catches attempts to access uninitialized memory.

        void    Poison(void* dest, int nitems, type)
Renew

The XSUB-writer's interface to the C realloc function.

        void    Renew(void* ptr, int nitems, type)
Renewc

The XSUB-writer's interface to the C realloc function, with cast.

        void    Renewc(void* ptr, int nitems, type, cast)
Safefree

The XSUB-writer's interface to the C free function.

        void    Safefree(void* ptr)
savepv

Perl's version of strdup(). Returns a pointer to a newly allocated string which is a duplicate of pv. The size of the string is determined by strlen(). The memory allocated for the new string can be freed with the Safefree() function.

        char*   savepv(const char* pv)
savepvn

Perl's version of what strndup() would be if it existed. Returns a pointer to a newly allocated string which is a duplicate of the first len bytes from pv. The memory allocated for the new string can be freed with the Safefree() function.

        char*   savepvn(const char* pv, I32 len)
savesharedpv

A version of savepv() which allocates the duplicate string in memory which is shared between threads.

        char*   savesharedpv(const char* pv)
savesvpv

A version of savepv()/savepvn() which gets the string to duplicate from the passed in SV using SvPV()

        char*   savesvpv(SV* sv)
StructCopy

This is an architecture-independent macro to copy one structure to another.

        void    StructCopy(type src, type dest, type)
Zero

The XSUB-writer's interface to the C memzero function. The dest is the destination, nitems is the number of items, and type is the type.

        void    Zero(void* dest, int nitems, type)
ZeroD

Like Zero but returns dest. Useful for encouraging compilers to tail-call optimise.

        void *  ZeroD(void* dest, int nitems, type)

Miscellaneous Functions

fbm_compile

Analyses the string in order to make fast searches on it using fbm_instr() -- the Boyer-Moore algorithm.

        void    fbm_compile(SV* sv, U32 flags)
fbm_instr

Returns the location of the SV in the string delimited by str and strend. It returns Nullch if the string can't be found. The sv does not have to be fbm_compiled, but the search will not be as fast then.

        char*   fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
form

Takes a sprintf-style format pattern and conventional (non-SV) arguments and returns the formatted string.

    (char *) Perl_form(pTHX_ const char* pat, ...)

can be used any place a string (char *) is required:

    char * s = Perl_form("%d.%d",major,minor);

Uses a single private buffer so if you want to format several strings you must explicitly copy the earlier strings away (and free the copies when you are done).

        char*   form(const char* pat, ...)
getcwd_sv

Fill the sv with current working directory

        int     getcwd_sv(SV* sv)
strEQ

Test two strings to see if they are equal. Returns true or false.

        bool    strEQ(char* s1, char* s2)
strGE

Test two strings to see if the first, s1, is greater than or equal to the second, s2. Returns true or false.

        bool    strGE(char* s1, char* s2)
strGT

Test two strings to see if the first, s1, is greater than the second, s2. Returns true or false.

        bool    strGT(char* s1, char* s2)
strLE

Test two strings to see if the first, s1, is less than or equal to the second, s2. Returns true or false.

        bool    strLE(char* s1, char* s2)
strLT

Test two strings to see if the first, s1, is less than the second, s2. Returns true or false.

        bool    strLT(char* s1, char* s2)
strNE

Test two strings to see if they are different. Returns true or false.

        bool    strNE(char* s1, char* s2)
strnEQ

Test two strings to see if they are equal. The len parameter indicates the number of bytes to compare. Returns true or false. (A wrapper for strncmp).

        bool    strnEQ(char* s1, char* s2, STRLEN len)
strnNE

Test two strings to see if they are different. The len parameter indicates the number of bytes to compare. Returns true or false. (A wrapper for strncmp).

        bool    strnNE(char* s1, char* s2, STRLEN len)
sv_nolocking

Dummy routine which "locks" an SV when there is no locking module present. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness.

        void    sv_nolocking(SV *)
sv_nosharing

Dummy routine which "shares" an SV when there is no sharing module present. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness.

        void    sv_nosharing(SV *)
sv_nounlocking

Dummy routine which "unlocks" an SV when there is no locking module present. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness.

        void    sv_nounlocking(SV *)

Numeric functions

grok_bin

converts a string representing a binary number to numeric form.

On entry start and *len give the string to scan, *flags gives conversion flags, and result should be NULL or a pointer to an NV. The scan stops at the end of the string, or the first invalid character. Unless PERL_SCAN_SILENT_ILLDIGIT is set in *flags, encountering an invalid character will also trigger a warning. On return *len is set to the length of the scanned string, and *flags gives output flags.

If the value is <= UV_MAX it is returned as a UV, the output flags are clear, and nothing is written to *result. If the value is > UV_MAX grok_bin returns UV_MAX, sets PERL_SCAN_GREATER_THAN_UV_MAX in the output flags, and writes the value to *result (or the value is discarded if result is NULL).

The binary number may optionally be prefixed with "0b" or "b" unless PERL_SCAN_DISALLOW_PREFIX is set in *flags on entry. If PERL_SCAN_ALLOW_UNDERSCORES is set in *flags then the binary number may use '_' characters to separate digits.

        UV      grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
grok_hex

converts a string representing a hex number to numeric form.

On entry start and *len give the string to scan, *flags gives conversion flags, and result should be NULL or a pointer to an NV. The scan stops at the end of the string, or the first invalid character. Unless PERL_SCAN_SILENT_ILLDIGIT is set in *flags, encountering an invalid character will also trigger a warning. On return *len is set to the length of the scanned string, and *flags gives output flags.

If the value is <= UV_MAX it is returned as a UV, the output flags are clear, and nothing is written to *result. If the value is > UV_MAX grok_hex returns UV_MAX, sets PERL_SCAN_GREATER_THAN_UV_MAX in the output flags, and writes the value to *result (or the value is discarded if result is NULL).

The hex number may optionally be prefixed with "0x" or "x" unless PERL_SCAN_DISALLOW_PREFIX is set in *flags on entry. If PERL_SCAN_ALLOW_UNDERSCORES is set in *flags then the hex number may use '_' characters to separate digits.

        UV      grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
grok_number

Recognise (or not) a number. The type of the number is returned (0 if unrecognised), otherwise it is a bit-ORed combination of IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).

If the value of the number can fit an in UV, it is returned in the *valuep IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV will never be set unless *valuep is valid, but *valuep may have been assigned to during processing even though IS_NUMBER_IN_UV is not set on return. If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when valuep is non-NULL, but no actual assignment (or SEGV) will occur.

IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were seen (in which case *valuep gives the true value truncated to an integer), and IS_NUMBER_NEG if the number is negative (in which case *valuep holds the absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the number is larger than a UV.

        int     grok_number(const char *pv, STRLEN len, UV *valuep)
grok_numeric_radix

Scan and skip for a numeric decimal separator (radix).

        bool    grok_numeric_radix(const char **sp, const char *send)
grok_oct

converts a string representing an octal number to numeric form.

On entry start and *len give the string to scan, *flags gives conversion flags, and result should be NULL or a pointer to an NV. The scan stops at the end of the string, or the first invalid character. Unless PERL_SCAN_SILENT_ILLDIGIT is set in *flags, encountering an invalid character will also trigger a warning. On return *len is set to the length of the scanned string, and *flags gives output flags.

If the value is <= UV_MAX it is returned as a UV, the output flags are clear, and nothing is written to *result. If the value is > UV_MAX grok_oct returns UV_MAX, sets PERL_SCAN_GREATER_THAN_UV_MAX in the output flags, and writes the value to *result (or the value is discarded if result is NULL).

If PERL_SCAN_ALLOW_UNDERSCORES is set in *flags then the octal number may use '_' characters to separate digits.

        UV      grok_oct(char* start, STRLEN* len_p, I32* flags, NV *result)
scan_bin

For backwards compatibility. Use grok_bin instead.

        NV      scan_bin(char* start, STRLEN len, STRLEN* retlen)
scan_hex

For backwards compatibility. Use grok_hex instead.

        NV      scan_hex(char* start, STRLEN len, STRLEN* retlen)
scan_oct

For backwards compatibility. Use grok_oct instead.

        NV      scan_oct(char* start, STRLEN len, STRLEN* retlen)

Optree Manipulation Functions

cv_const_sv

If cv is a constant sub eligible for inlining. returns the constant value returned by the sub. Otherwise, returns NULL.

Constant subs can be created with newCONSTSUB or as described in Constant Functions in the perlsub manpage.

        SV*     cv_const_sv(CV* cv)
newCONSTSUB

Creates a constant sub equivalent to Perl sub FOO () { 123 } which is eligible for inlining at compile-time.

        CV*     newCONSTSUB(HV* stash, char* name, SV* sv)
newXS

Used by xsubpp to hook up XSUBs as Perl subs.

Pad Data Structures

pad_sv

Get the value at offset po in the current pad. Use macro PAD_SV instead of calling this function directly.

        SV*     pad_sv(PADOFFSET po)

Stack Manipulation Macros

dMARK

Declare a stack marker variable, mark, for the XSUB. See MARK and dORIGMARK.

                dMARK;
dORIGMARK

Saves the original stack mark for the XSUB. See ORIGMARK.

                dORIGMARK;
dSP

Declares a local copy of perl's stack pointer for the XSUB, available via the SP macro. See SP.

                dSP;
EXTEND

Used to extend the argument stack for an XSUB's return values. Once used, guarantees that there is room for at least nitems to be pushed onto the stack.

        void    EXTEND(SP, int nitems)
MARK

Stack marker variable for the XSUB. See dMARK.

mPUSHi

Push an integer onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use TARG. See also PUSHi, mXPUSHi and XPUSHi.

        void    mPUSHi(IV iv)
mPUSHn

Push a double onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use TARG. See also PUSHn, mXPUSHn and XPUSHn.

        void    mPUSHn(NV nv)
mPUSHp

Push a string onto the stack. The stack must have room for this element. The len indicates the length of the string. Handles 'set' magic. Does not use TARG. See also PUSHp, mXPUSHp and XPUSHp.

        void    mPUSHp(char* str, STRLEN len)
mPUSHu

Push an unsigned integer onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use TARG. See also PUSHu, mXPUSHu and XPUSHu.

        void    mPUSHu(UV uv)
mXPUSHi

Push an integer onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use TARG. See also XPUSHi, mPUSHi and PUSHi.

        void    mXPUSHi(IV iv)
mXPUSHn

Push a double onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use TARG. See also XPUSHn, mPUSHn and PUSHn.

        void    mXPUSHn(NV nv)
mXPUSHp

Push a string onto the stack, extending the stack if necessary. The len indicates the length of the string. Handles 'set' magic. Does not use TARG. See also XPUSHp, mPUSHp and PUSHp.

        void    mXPUSHp(char* str, STRLEN len)
mXPUSHu

Push an unsigned integer onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use TARG. See also XPUSHu, mPUSHu and PUSHu.

        void    mXPUSHu(UV uv)
ORIGMARK

The original stack mark for the XSUB. See dORIGMARK.

POPi

Pops an integer off the stack.

        IV      POPi
POPl

Pops a long off the stack.

        long    POPl
POPn

Pops a double off the stack.

        NV      POPn
POPp

Pops a string off the stack. Deprecated. New code should use POPpx.

        char*   POPp
POPpbytex

Pops a string off the stack which must consist of bytes i.e. characters < 256.

        char*   POPpbytex
POPpx

Pops a string off the stack.

        char*   POPpx
POPs

Pops an SV off the stack.

        SV*     POPs
PUSHi

Push an integer onto the stack. The stack must have room for this element. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mPUSHi instead. See also XPUSHi and mXPUSHi.

        void    PUSHi(IV iv)
PUSHMARK

Opening bracket for arguments on a callback. See PUTBACK and the perlcall manpage.

        void    PUSHMARK(SP)
PUSHmortal

Push a new mortal SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. Does not use TARG. See also PUSHs, XPUSHmortal and XPUSHs.

        void    PUSHmortal()
PUSHn

Push a double onto the stack. The stack must have room for this element. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mPUSHn instead. See also XPUSHn and mXPUSHn.

        void    PUSHn(NV nv)
PUSHp

Push a string onto the stack. The stack must have room for this element. The len indicates the length of the string. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mPUSHp instead. See also XPUSHp and mXPUSHp.

        void    PUSHp(char* str, STRLEN len)
PUSHs

Push an SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. Does not use TARG. See also PUSHmortal, XPUSHs and XPUSHmortal.

        void    PUSHs(SV* sv)
PUSHu

Push an unsigned integer onto the stack. The stack must have room for this element. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mPUSHu instead. See also XPUSHu and mXPUSHu.

        void    PUSHu(UV uv)
PUTBACK

Closing bracket for XSUB arguments. This is usually handled by xsubpp. See PUSHMARK and the perlcall manpage for other uses.

                PUTBACK;
SP

Stack pointer. This is usually handled by xsubpp. See dSP and SPAGAIN.

SPAGAIN

Refetch the stack pointer. Used after a callback. See the perlcall manpage.

                SPAGAIN;
XPUSHi

Push an integer onto the stack, extending the stack if necessary. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mXPUSHi instead. See also PUSHi and mPUSHi.

        void    XPUSHi(IV iv)
XPUSHmortal

Push a new mortal SV onto the stack, extending the stack if necessary. Does not handle 'set' magic. Does not use TARG. See also XPUSHs, PUSHmortal and PUSHs.

        void    XPUSHmortal()
XPUSHn

Push a double onto the stack, extending the stack if necessary. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mXPUSHn instead. See also PUSHn and mPUSHn.

        void    XPUSHn(NV nv)
XPUSHp

Push a string onto the stack, extending the stack if necessary. The len indicates the length of the string. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mXPUSHp instead. See also PUSHp and mPUSHp.

        void    XPUSHp(char* str, STRLEN len)
XPUSHs

Push an SV onto the stack, extending the stack if necessary. Does not handle 'set' magic. Does not use TARG. See also XPUSHmortal, PUSHs and PUSHmortal.

        void    XPUSHs(SV* sv)
XPUSHu

Push an unsigned integer onto the stack, extending the stack if necessary. Handles 'set' magic. Uses TARG, so dTARGET or dXSTARG should be called to declare it. Do not call multiple TARG-oriented macros to return lists from XSUB's - see mXPUSHu instead. See also PUSHu and mPUSHu.

        void    XPUSHu(UV uv)
XSRETURN

Return from XSUB, indicating number of items on the stack. This is usually handled by xsubpp.

        void    XSRETURN(int nitems)
XSRETURN_EMPTY

Return an empty list from an XSUB immediately.

                XSRETURN_EMPTY;
XSRETURN_IV

Return an integer from an XSUB immediately. Uses XST_mIV.

        void    XSRETURN_IV(IV iv)
XSRETURN_NO

Return &PL_sv_no from an XSUB immediately. Uses XST_mNO.

                XSRETURN_NO;
XSRETURN_NV

Return a double from an XSUB immediately. Uses XST_mNV.

        void    XSRETURN_NV(NV nv)
XSRETURN_PV

Return a copy of a string from an XSUB immediately. Uses XST_mPV.

        void    XSRETURN_PV(char* str)
XSRETURN_UNDEF

Return &PL_sv_undef from an XSUB immediately. Uses XST_mUNDEF.

                XSRETURN_UNDEF;
XSRETURN_UV

Return an integer from an XSUB immediately. Uses XST_mUV.

        void    XSRETURN_UV(IV uv)
XSRETURN_YES

Return &PL_sv_yes from an XSUB immediately. Uses XST_mYES.

                XSRETURN_YES;
XST_mIV

Place an integer into the specified position pos on the stack. The value is stored in a new mortal SV.

        void    XST_mIV(int pos, IV iv)
XST_mNO

Place &PL_sv_no into the specified position pos on the stack.

        void    XST_mNO(int pos)
XST_mNV

Place a double into the specified position pos on the stack. The value is stored in a new mortal SV.

        void    XST_mNV(int pos, NV nv)
XST_mPV

Place a copy of a string into the specified position pos on the stack. The value is stored in a new mortal SV.

        void    XST_mPV(int pos, char* str)
XST_mUNDEF

Place &PL_sv_undef into the specified position pos on the stack.

        void    XST_mUNDEF(int pos)
XST_mYES

Place &PL_sv_yes into the specified position pos on the stack.

        void    XST_mYES(int pos)

SV Flags

svtype

An enum of flags for Perl types. These are found in the file sv.h in the svtype enum. Test these flags with the SvTYPE macro.

SVt_IV

Integer type flag for scalars. See svtype.

SVt_NV

Double type flag for scalars. See svtype.

SVt_PV

Pointer type flag for scalars. See svtype.

SVt_PVAV

Type flag for arrays. See svtype.

SVt_PVCV

Type flag for code refs. See svtype.

SVt_PVHV

Type flag for hashes. See svtype.

SVt_PVMG

Type flag for blessed scalars. See svtype.

SV Manipulation Functions

get_sv

Returns the SV of the specified Perl scalar. If create is set and the Perl variable does not exist then it will be created. If create is not set and the variable does not exist then NULL is returned.

NOTE: the perl_ form of this function is deprecated.

        SV*     get_sv(const char* name, I32 create)
looks_like_number

Test if the content of an SV looks like a number (or is a number). Inf and Infinity are treated as numbers (so will not issue a non-numeric warning), even if your atof() doesn't grok them.

        I32     looks_like_number(SV* sv)
newRV_inc

Creates an RV wrapper for an SV. The reference count for the original SV is incremented.

        SV*     newRV_inc(SV* sv)
newRV_noinc

Creates an RV wrapper for an SV. The reference count for the original SV is not incremented.

        SV*     newRV_noinc(SV *sv)
NEWSV

Creates a new SV. A non-zero len parameter indicates the number of bytes of preallocated string space the SV should have. An extra byte for a tailing NUL is also reserved. (SvPOK is not set for the SV even if string space is allocated.) The reference count for the new SV is set to 1. id is an integer id between 0 and 1299 (used to identify leaks).

        SV*     NEWSV(int id, STRLEN len)
newSV

Create a new null SV, or if len > 0, create a new empty SVt_PV type SV with an initial PV allocation of len+1. Normally accessed via the NEWSV macro.

        SV*     newSV(STRLEN len)
newSVhek

Creates a new SV from the hash key structure. It will generate scalars that point to the shared string table where possible. Returns a new (undefined) SV if the hek is NULL.

        SV*     newSVhek(const HEK *hek)
newSViv

Creates a new SV and copies an integer into it. The reference count for the SV is set to 1.

        SV*     newSViv(IV i)
newSVnv

Creates a new SV and copies a floating point value into it. The reference count for the SV is set to 1.

        SV*     newSVnv(NV n)
newSVpv

Creates a new SV and copies a string into it. The reference count for the SV is set to 1. If len is zero, Perl will compute the length using strlen(). For efficiency, consider using newSVpvn instead.

        SV*     newSVpv(const char* s, STRLEN len)
newSVpvf

Creates a new SV and initializes it with the string formatted like sprintf.

        SV*     newSVpvf(const char* pat, ...)
newSVpvn

Creates a new SV and copies a string into it. The reference count for the SV is set to 1. Note that if len is zero, Perl will create a zero length string. You are responsible for ensuring that the source string is at least len bytes long. If the s argument is NULL the new SV will be undefined.

        SV*     newSVpvn(const char* s, STRLEN len)
newSVpvn_share

Creates a new SV with its SvPVX_const pointing to a shared string in the string table. If the string does not already exist in the table, it is created first. Turns on READONLY and FAKE. The string's hash is stored in the UV slot of the SV; if the hash parameter is non-zero, that value is used; otherwise the hash is computed. The idea here is that as the string table is used for shared hash keys these strings will have SvPVX_const == HeKEY and hash lookup will avoid string compare.

        SV*     newSVpvn_share(const char* s, I32 len, U32 hash)
newSVrv

Creates a new SV for the RV, rv, to point to. If rv is not an RV then it will be upgraded to one. If classname is non-null then the new SV will be blessed in the specified package. The new SV is returned and its reference count is 1.

        SV*     newSVrv(SV* rv, const char* classname)
newSVsv

Creates a new SV which is an exact duplicate of the original SV. (Uses sv_setsv).

        SV*     newSVsv(SV* old)
newSVuv

Creates a new SV and copies an unsigned integer into it. The reference count for the SV is set to 1.

        SV*     newSVuv(UV u)
SvCUR

Returns the length of the string which is in the SV. See SvLEN.

        STRLEN  SvCUR(SV* sv)
SvCUR_set

Set the current length of the string which is in the SV. See SvCUR and SvIV_set.

        void    SvCUR_set(SV* sv, STRLEN len)
SvEND

Returns a pointer to the last character in the string which is in the SV. See SvCUR. Access the character as *(SvEND(sv)).

        char*   SvEND(SV* sv)
SvGROW

Expands the character buffer in the SV so that it has room for the indicated number of bytes (remember to reserve space for an extra trailing NUL character). Calls sv_grow to perform the expansion if necessary. Returns a pointer to the character buffer.

        char *  SvGROW(SV* sv, STRLEN len)
SvIOK

Returns a boolean indicating whether the SV contains an integer.

        bool    SvIOK(SV* sv)
SvIOKp

Returns a boolean indicating whether the SV contains an integer. Checks the private setting. Use SvIOK.

        bool    SvIOKp(SV* sv)
SvIOK_notUV

Returns a boolean indicating whether the SV contains a signed integer.

        bool    SvIOK_notUV(SV* sv)
SvIOK_off

Unsets the IV status of an SV.

        void    SvIOK_off(SV* sv)
SvIOK_on

Tells an SV that it is an integer.

        void    SvIOK_on(SV* sv)
SvIOK_only

Tells an SV that it is an integer and disables all other OK bits.

        void    SvIOK_only(SV* sv)
SvIOK_only_UV

Tells and SV that it is an unsigned integer and disables all other OK bits.

        void    SvIOK_only_UV(SV* sv)
SvIOK_UV

Returns a boolean indicating whether the SV contains an unsigned integer.

        bool    SvIOK_UV(SV* sv)
SvIsCOW

Returns a boolean indicating whether the SV is Copy-On-Write. (either shared hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for COW)

        bool    SvIsCOW(SV* sv)
SvIsCOW_shared_hash

Returns a boolean indicating whether the SV is Copy-On-Write shared hash key scalar.

        bool    SvIsCOW_shared_hash(SV* sv)
SvIV

Coerces the given SV to an integer and returns it. See SvIVx for a version which guarantees to evaluate sv only once.

        IV      SvIV(SV* sv)
SvIVX

Returns the raw value in the SV's IV slot, without checks or conversions. Only use when you are sure SvIOK is true. See also SvIV().

        IV      SvIVX(SV* sv)
SvIVx

Coerces the given SV to an integer and returns it. Guarantees to evaluate sv only once. Use the more efficient SvIV otherwise.

        IV      SvIVx(SV* sv)
SvIV_set

Set the value of the IV pointer in sv to val. It is possible to perform the same function of this macro with an lvalue assignment to SvIVX. With future Perls, however, it will be more efficient to use SvIV_set instead of the lvalue assignment to SvIVX.

        void    SvIV_set(SV* sv, IV val)
SvLEN

Returns the size of the string buffer in the SV, not including any part attributable to SvOOK. See SvCUR.

        STRLEN  SvLEN(SV* sv)
SvLEN_set

Set the actual length of the string which is in the SV. See SvIV_set.

        void    SvLEN_set(SV* sv, STRLEN len)
SvMAGIC_set

Set the value of the MAGIC pointer in sv to val. See SvIV_set.

        void    SvMAGIC_set(SV* sv, MAGIC* val)
SvNIOK

Returns a boolean indicating whether the SV contains a number, integer or double.

        bool    SvNIOK(SV* sv)
SvNIOKp

Returns a boolean indicating whether the SV contains a number, integer or double. Checks the private setting. Use SvNIOK.

        bool    SvNIOKp(SV* sv)
SvNIOK_off

Unsets the NV/IV status of an SV.

        void    SvNIOK_off(SV* sv)
SvNOK

Returns a boolean indicating whether the SV contains a double.

        bool    SvNOK(SV* sv)
SvNOKp

Returns a boolean indicating whether the SV contains a double. Checks the private setting. Use SvNOK.

        bool    SvNOKp(SV* sv)
SvNOK_off

Unsets the NV status of an SV.

        void    SvNOK_off(SV* sv)
SvNOK_on

Tells an SV that it is a double.

        void    SvNOK_on(SV* sv)
SvNOK_only

Tells an SV that it is a double and disables all other OK bits.

        void    SvNOK_only(SV* sv)
SvNV

Coerce the given SV to a double and return it. See SvNVx for a version which guarantees to evaluate sv only once.

        NV      SvNV(SV* sv)
SvNVX

Returns the raw value in the SV's NV slot, without checks or conversions. Only use when you are sure SvNOK is true. See also SvNV().

        NV      SvNVX(SV* sv)
SvNVx

Coerces the given SV to a double and returns it. Guarantees to evaluate sv only once. Use the more efficient SvNV otherwise.

        NV      SvNVx(SV* sv)
SvNV_set

Set the value of the NV pointer in sv to val. See SvIV_set.

        void    SvNV_set(SV* sv, NV val)
SvOK

Returns a boolean indicating whether the value is an SV. It also tells whether the value is defined or not.

        bool    SvOK(SV* sv)
SvOOK

Returns a boolean indicating whether the SvIVX is a valid offset value for the SvPVX. This hack is used internally to speed up removal of characters from the beginning of a SvPV. When SvOOK is true, then the start of the allocated string buffer is really (SvPVX - SvIVX).

        bool    SvOOK(SV* sv)
SvPOK

Returns a boolean indicating whether the SV contains a character string.

        bool    SvPOK(SV* sv)
SvPOKp

Returns a boolean indicating whether the SV contains a character string. Checks the private setting. Use SvPOK.

        bool    SvPOKp(SV* sv)
SvPOK_off

Unsets the PV status of an SV.

        void    SvPOK_off(SV* sv)
SvPOK_on

Tells an SV that it is a string.

        void    SvPOK_on(SV* sv)
SvPOK_only

Tells an SV that it is a string and disables all other OK bits. Will also turn off the UTF-8 status.

        void    SvPOK_only(SV* sv)
SvPOK_only_UTF8

Tells an SV that it is a string and disables all other OK bits, and leaves the UTF-8 status as it was.

        void    SvPOK_only_UTF8(SV* sv)
SvPV

Returns a pointer to the string in the SV, or a stringified form of the SV if the SV does not contain a string. The SV may cache the stringified version becoming SvPOK. Handles 'get' magic. See also SvPVx for a version which guarantees to evaluate sv only once.

        char*   SvPV(SV* sv, STRLEN len)
SvPVbyte

Like SvPV, but converts sv to byte representation first if necessary.

        char*   SvPVbyte(SV* sv, STRLEN len)
SvPVbytex

Like SvPV, but converts sv to byte representation first if necessary. Guarantees to evaluate sv only once; use the more efficient SvPVbyte otherwise.

        char*   SvPVbytex(SV* sv, STRLEN len)
SvPVbytex_force

Like SvPV_force, but converts sv to byte representation first if necessary. Guarantees to evaluate sv only once; use the more efficient SvPVbyte_force otherwise.

        char*   SvPVbytex_force(SV* sv, STRLEN len)
SvPVbyte_force

Like SvPV_force, but converts sv to byte representation first if necessary.

        char*   SvPVbyte_force(SV* sv, STRLEN len)
SvPVbyte_nolen

Like SvPV_nolen, but converts sv to byte representation first if necessary.

        char*   SvPVbyte_nolen(SV* sv)
SvPVutf8

Like SvPV, but converts sv to utf8 first if necessary.

        char*   SvPVutf8(SV* sv, STRLEN len)
SvPVutf8x

Like SvPV, but converts sv to utf8 first if necessary. Guarantees to evaluate sv only once; use the more efficient SvPVutf8 otherwise.

        char*   SvPVutf8x(SV* sv, STRLEN len)
SvPVutf8x_force

Like SvPV_force, but converts sv to utf8 first if necessary. Guarantees to evaluate sv only once; use the more efficient SvPVutf8_force otherwise.

        char*   SvPVutf8x_force(SV* sv, STRLEN len)
SvPVutf8_force

Like SvPV_force, but converts sv to utf8 first if necessary.

        char*   SvPVutf8_force(SV* sv, STRLEN len)
SvPVutf8_nolen

Like SvPV_nolen, but converts sv to utf8 first if necessary.

        char*   SvPVutf8_nolen(SV* sv)
SvPVX

Returns a pointer to the physical string in the SV. The SV must contain a string.

        char*   SvPVX(SV* sv)
SvPVx

A version of SvPV which guarantees to evaluate sv only once.

        char*   SvPVx(SV* sv, STRLEN len)
SvPV_force

Like SvPV but will force the SV into containing just a string (SvPOK_only). You want force if you are going to update the SvPVX directly.

        char*   SvPV_force(SV* sv, STRLEN len)
SvPV_force_nomg

Like SvPV but will force the SV into containing just a string (SvPOK_only). You want force if you are going to update the SvPVX directly. Doesn't process magic.

        char*   SvPV_force_nomg(SV* sv, STRLEN len)
SvPV_nolen

Returns a pointer to the string in the SV, or a stringified form of the SV if the SV does not contain a string. The SV may cache the stringified form becoming SvPOK. Handles 'get' magic.

        char*   SvPV_nolen(SV* sv)
SvPV_set

Set the value of the PV pointer in sv to val. See SvIV_set.

        void    SvPV_set(SV* sv, char* val)
SvREFCNT

Returns the value of the object's reference count.

        U32     SvREFCNT(SV* sv)
SvREFCNT_dec

Decrements the reference count of the given SV.

        void    SvREFCNT_dec(SV* sv)
SvREFCNT_inc

Increments the reference count of the given SV.

        SV*     SvREFCNT_inc(SV* sv)
SvROK

Tests if the SV is an RV.

        bool    SvROK(SV* sv)
SvROK_off

Unsets the RV status of an SV.

        void    SvROK_off(SV* sv)
SvROK_on

Tells an SV that it is an RV.

        void    SvROK_on(SV* sv)
SvRV

Dereferences an RV to return the SV.

        SV*     SvRV(SV* sv)
SvRV_set

Set the value of the RV pointer in sv to val. See SvIV_set.

        void    SvRV_set(SV* sv, SV* val)
SvSTASH

Returns the stash of the SV.

        HV*     SvSTASH(SV* sv)
SvSTASH_set

Set the value of the STASH pointer in sv to val. See SvIV_set.

        void    SvSTASH_set(SV* sv, STASH* val)
SvTAINT

Taints an SV if tainting is enabled.

        void    SvTAINT(SV* sv)
SvTAINTED

Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.

        bool    SvTAINTED(SV* sv)
SvTAINTED_off

Untaints an SV. Be very careful with this routine, as it short-circuits some of Perl's fundamental security features. XS module authors should not use this function unless they fully understand all the implications of unconditionally untainting the value. Untainting should be done in the standard perl fashion, via a carefully crafted regexp, rather than directly untainting variables.

        void    SvTAINTED_off(SV* sv)
SvTAINTED_on

Marks an SV as tainted if tainting is enabled.

        void    SvTAINTED_on(SV* sv)
SvTRUE

Returns a boolean indicating whether Perl would evaluate the SV as true or false, defined or undefined. Does not handle 'get' magic.

        bool    SvTRUE(SV* sv)
SvTYPE

Returns the type of the SV. See svtype.

        svtype  SvTYPE(SV* sv)
SvUOK

Returns a boolean indicating whether the SV contains an unsigned integer.

        void    SvUOK(SV* sv)
SvUPGRADE

Used to upgrade an SV to a more complex form. Uses sv_upgrade to perform the upgrade if necessary. See svtype.

        void    SvUPGRADE(SV* sv, svtype type)
SvUTF8

Returns a boolean indicating whether the SV contains UTF-8 encoded data.

        bool    SvUTF8(SV* sv)
SvUTF8_off

Unsets the UTF-8 status of an SV.

        void    SvUTF8_off(SV *sv)
SvUTF8_on

Turn on the UTF-8 status of an SV (the data is not changed, just the flag). Do not use frivolously.

        void    SvUTF8_on(SV *sv)
SvUV

Coerces the given SV to an unsigned integer and returns it. See SvUVx for a version which guarantees to evaluate sv only once.

        UV      SvUV(SV* sv)
SvUVX

Returns the raw value in the SV's UV slot, without checks or conversions. Only use when you are sure SvIOK is true. See also SvUV().

        UV      SvUVX(SV* sv)
SvUVx

Coerces the given SV to an unsigned integer and returns it. Guarantees to evaluate sv only once. Use the more efficient SvUV otherwise.

        UV      SvUVx(SV* sv)
SvUV_set

Set the value of the UV pointer in sv to val. See SvIV_set.

        void    SvUV_set(SV* sv, UV val)
sv_2bool

This function is only called on magical items, and is only used by sv_true() or its macro equivalent.

        bool    sv_2bool(SV* sv)
sv_2cv

Using various gambits, try to get a CV from an SV; in addition, try if possible to set *st and *gvp to the stash and GV associated with it.

        CV*     sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
sv_2io

Using various gambits, try to get an IO from an SV: the IO slot if its a GV; or the recursive result if we're an RV; or the IO slot of the symbol named after the PV if we're a string.

        IO*     sv_2io(SV* sv)
sv_2iv

Return the integer value of an SV, doing any necessary string conversion, magic etc. Normally used via the SvIV(sv) and SvIVx(sv) macros.

        IV      sv_2iv(SV* sv)
sv_2mortal

Marks an existing SV as mortal. The SV will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. SvTEMP() is turned on which means that the SV's string buffer can be "stolen" if this SV is copied. See also sv_newmortal and sv_mortalcopy.

        SV*     sv_2mortal(SV* sv)
sv_2nv

Return the num value of an SV, doing any necessary string or integer conversion, magic etc. Normally used via the SvNV(sv) and SvNVx(sv) macros.

        NV      sv_2nv(SV* sv)
sv_2pvbyte

Return a pointer to the byte-encoded representation of the SV, and set *lp to its length. May cause the SV to be downgraded from UTF-8 as a side-effect.

Usually accessed via the SvPVbyte macro.

        char*   sv_2pvbyte(SV* sv, STRLEN* lp)
sv_2pvbyte_nolen

Return a pointer to the byte-encoded representation of the SV. May cause the SV to be downgraded from UTF-8 as a side-effect.

Usually accessed via the SvPVbyte_nolen macro.

        char*   sv_2pvbyte_nolen(SV* sv)
sv_2pvutf8

Return a pointer to the UTF-8-encoded representation of the SV, and set *lp to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.

Usually accessed via the SvPVutf8 macro.

        char*   sv_2pvutf8(SV* sv, STRLEN* lp)
sv_2pvutf8_nolen

Return a pointer to the UTF-8-encoded representation of the SV. May cause the SV to be upgraded to UTF-8 as a side-effect.

Usually accessed via the SvPVutf8_nolen macro.

        char*   sv_2pvutf8_nolen(SV* sv)
sv_2pv_flags

Returns a pointer to the string value of an SV, and sets *lp to its length. If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string if necessary. Normally invoked via the SvPV_flags macro. sv_2pv() and sv_2pv_nomg usually end up here too.

        char*   sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
sv_2pv_nolen

Like sv_2pv(), but doesn't return the length too. You should usually use the macro wrapper SvPV_nolen(sv) instead. char* sv_2pv_nolen(SV* sv)

sv_2uv

Return the unsigned integer value of an SV, doing any necessary string conversion, magic etc. Normally used via the SvUV(sv) and SvUVx(sv) macros.

        UV      sv_2uv(SV* sv)
sv_backoff

Remove any string offset. You should normally use the SvOOK_off macro wrapper instead.

        int     sv_backoff(SV* sv)
sv_bless

Blesses an SV into a specified package. The SV must be an RV. The package must be designated by its stash (see gv_stashpv()). The reference count of the SV is unaffected.

        SV*     sv_bless(SV* sv, HV* stash)
sv_catpv

Concatenates the string onto the end of the string which is in the SV. If the SV has the UTF-8 status set, then the bytes appended should be valid UTF-8. Handles 'get' magic, but not 'set' magic. See sv_catpv_mg.

        void    sv_catpv(SV* sv, const char* ptr)
sv_catpvf

Processes its arguments like sprintf and appends the formatted output to an SV. If the appended data contains "wide" characters (including, but not limited to, SVs with a UTF-8 PV formatted with %s, and characters >255 formatted with %c), the original SV might get upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See sv_catpvf_mg. If the original SV was UTF-8, the pattern should be valid UTF-8; if the original SV was bytes, the pattern should be too.

        void    sv_catpvf(SV* sv, const char* pat, ...)
sv_catpvf_mg

Like sv_catpvf, but also handles 'set' magic.

        void    sv_catpvf_mg(SV *sv, const char* pat, ...)
sv_catpvn

Concatenates the string onto the end of the string which is in the SV. The len indicates number of bytes to copy. If the SV has the UTF-8 status set, then the bytes appended should be valid UTF-8. Handles 'get' magic, but not 'set' magic. See sv_catpvn_mg.

        void    sv_catpvn(SV* sv, const char* ptr, STRLEN len)
sv_catpvn_flags

Concatenates the string onto the end of the string which is in the SV. The len indicates number of bytes to copy. If the SV has the UTF-8 status set, then the bytes appended should be valid UTF-8. If flags has SV_GMAGIC bit set, will mg_get on dsv if appropriate, else not. sv_catpvn and sv_catpvn_nomg are implemented in terms of this function.

        void    sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
sv_catpvn_mg

Like sv_catpvn, but also handles 'set' magic.

        void    sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
sv_catpvn_nomg

Like sv_catpvn but doesn't process magic.

        void    sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
sv_catpv_mg

Like sv_catpv, but also handles 'set' magic.

        void    sv_catpv_mg(SV *sv, const char *ptr)
sv_catsv

Concatenates the string from SV ssv onto the end of the string in SV dsv. Modifies dsv but not ssv. Handles 'get' magic, but not 'set' magic. See sv_catsv_mg.

        void    sv_catsv(SV* dsv, SV* ssv)
sv_catsv_flags

Concatenates the string from SV ssv onto the end of the string in SV dsv. Modifies dsv but not ssv. If flags has SV_GMAGIC bit set, will mg_get on the SVs if appropriate, else not. sv_catsv and sv_catsv_nomg are implemented in terms of this function.

        void    sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
sv_catsv_mg

Like sv_catsv, but also handles 'set' magic.

        void    sv_catsv_mg(SV *dstr, SV *sstr)
sv_catsv_nomg

Like sv_catsv but doesn't process magic.

        void    sv_catsv_nomg(SV* dsv, SV* ssv)
sv_chop

Efficient removal of characters from the beginning of the string buffer. SvPOK(sv) must be true and the ptr must be a pointer to somewhere inside the string buffer. The ptr becomes the first character of the adjusted string. Uses the "OOK hack". Beware: after this function returns, ptr and SvPVX_const(sv) may no longer refer to the same chunk of data.

        void    sv_chop(SV* sv, char* ptr)
sv_clear

Clear an SV: call any destructors, free up any memory used by the body, and free the body itself. The SV's head is not freed, although its type is set to all 1's so that it won't inadvertently be assumed to be live during global destruction etc. This function should only be called when REFCNT is zero. Most of the time you'll want to call sv_free() (or its macro wrapper SvREFCNT_dec) instead.

        void    sv_clear(SV* sv)
sv_cmp

Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in sv1 is less than, equal to, or greater than the string in sv2. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary. See also sv_cmp_locale.

        I32     sv_cmp(SV* sv1, SV* sv2)
sv_cmp_locale

Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary. See also sv_cmp_locale. See also sv_cmp.

        I32     sv_cmp_locale(SV* sv1, SV* sv2)
sv_collxfrm

Add Collate Transform magic to an SV if it doesn't already have it.

Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the scalar data of the variable, but transformed to such a format that a normal memory comparison can be used to compare the data according to the locale settings.

        char*   sv_collxfrm(SV* sv, STRLEN* nxp)
sv_copypv

Copies a stringified representation of the source SV into the destination SV. Automatically performs any necessary mg_get and coercion of numeric values into strings. Guaranteed to preserve UTF-8 flag even from overloaded objects. Similar in nature to sv_2pv[_flags] but operates directly on an SV instead of just the string. Mostly uses sv_2pv_flags to do its work, except when that would lose the UTF-8'ness of the PV.

        void    sv_copypv(SV* dsv, SV* ssv)
sv_dec

Auto-decrement of the value in the SV, doing string to numeric conversion if necessary. Handles 'get' magic.

        void    sv_dec(SV* sv)
sv_derived_from

Returns a boolean indicating whether the SV is derived from the specified class. This is the function that implements UNIVERSAL::isa. It works for class names as well as for objects.

        bool    sv_derived_from(SV* sv, const char* name)
sv_eq

Returns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings if necessary.

        I32     sv_eq(SV* sv1, SV* sv2)
sv_force_normal

Undo various types of fakery on an SV: if the PV is a shared string, make a private copy; if we're a ref, stop refing; if we're a glob, downgrade to an xpvmg. See also sv_force_normal_flags.

        void    sv_force_normal(SV *sv)
sv_force_normal_flags

Undo various types of fakery on an SV: if the PV is a shared string, make a private copy; if we're a ref, stop refing; if we're a glob, downgrade to an xpvmg. The flags parameter gets passed to sv_unref_flags() when unrefing. sv_force_normal calls this function with flags set to 0.

        void    sv_force_normal_flags(SV *sv, U32 flags)
sv_free

Decrement an SV's reference count, and if it drops to zero, call sv_clear to invoke destructors and free up any memory used by the body; finally, deallocate the SV's head itself. Normally called via a wrapper macro SvREFCNT_dec.

        void    sv_free(SV* sv)
sv_gets

Get a line from the filehandle and store it into the SV, optionally appending to the currently-stored string.

        char*   sv_gets(SV* sv, PerlIO* fp, I32 append)
sv_grow

Expands the character buffer in the SV. If necessary, uses sv_unref and upgrades the SV to SVt_PV. Returns a pointer to the character buffer. Use the SvGROW wrapper instead.

        char*   sv_grow(SV* sv, STRLEN newlen)
sv_inc

Auto-increment of the value in the SV, doing string to numeric conversion if necessary. Handles 'get' magic.

        void    sv_inc(SV* sv)
sv_insert

Inserts a string at the specified offset/length within the SV. Similar to the Perl substr() function.

        void    sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
sv_isa

Returns a boolean indicating whether the SV is blessed into the specified class. This does not check for subtypes; use sv_derived_from to verify an inheritance relationship.

        int     sv_isa(SV* sv, const char* name)
sv_isobject

Returns a boolean indicating whether the SV is an RV pointing to a blessed object. If the SV is not an RV, or if the object is not blessed, then this will return false.

        int     sv_isobject(SV* sv)
sv_iv

A private implementation of the SvIVx macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        IV      sv_iv(SV* sv)
sv_len

Returns the length of the string in the SV. Handles magic and type coercion. See also SvCUR, which gives raw access to the xpv_cur slot.

        STRLEN  sv_len(SV* sv)
sv_len_utf8

Returns the number of characters in the string in an SV, counting wide UTF-8 bytes as a single character. Handles magic and type coercion.

        STRLEN  sv_len_utf8(SV* sv)
sv_magic

Adds magic to an SV. First upgrades sv to type SVt_PVMG if necessary, then adds a new magic item of type how to the head of the magic list.

See sv_magicext (which sv_magic now calls) for a description of the handling of the name and namlen arguments.

You need to use sv_magicext to add magic to SvREADONLY SVs and also to add more than one instance of the same 'how'.

        void    sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
sv_magicext

Adds magic to an SV, upgrading it if necessary. Applies the supplied vtable and returns a pointer to the magic added.

Note that sv_magicext will allow things that sv_magic will not. In particular, you can add magic to SvREADONLY SVs, and add more than one instance of the same 'how'.

If namlen is greater than zero then a savepvn copy of name is stored, if namlen is zero then name is stored as-is and - as another special case - if (name && namlen == HEf_SVKEY) then name is assumed to contain an SV* and is stored as-is with its REFCNT incremented.

(This is now used as a subroutine by sv_magic.)

        MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen)
sv_mortalcopy

Creates a new SV which is a copy of the original SV (using sv_setsv). The new SV is marked as mortal. It will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. See also sv_newmortal and sv_2mortal.

        SV*     sv_mortalcopy(SV* oldsv)
sv_newmortal

Creates a new null SV which is mortal. The reference count of the SV is set to 1. It will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as statement boundaries. See also sv_mortalcopy and sv_2mortal.

        SV*     sv_newmortal()
sv_newref

Increment an SV's reference count. Use the SvREFCNT_inc() wrapper instead.

        SV*     sv_newref(SV* sv)
sv_nv

A private implementation of the SvNVx macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        NV      sv_nv(SV* sv)
sv_pos_b2u

Converts the value pointed to by offsetp from a count of bytes from the start of the string, to a count of the equivalent number of UTF-8 chars. Handles magic and type coercion.

        void    sv_pos_b2u(SV* sv, I32* offsetp)
sv_pos_u2b

Converts the value pointed to by offsetp from a count of UTF-8 chars from the start of the string, to a count of the equivalent number of bytes; if lenp is non-zero, it does the same to lenp, but this time starting from the offset, rather than from the start of the string. Handles magic and type coercion.

        void    sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
sv_pv

Use the SvPV_nolen macro instead

        char*   sv_pv(SV *sv)
sv_pvbyte

Use SvPVbyte_nolen instead.

        char*   sv_pvbyte(SV *sv)
sv_pvbyten

A private implementation of the SvPVbyte macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvbyten(SV *sv, STRLEN *len)
sv_pvbyten_force

A private implementation of the SvPVbytex_force macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvbyten_force(SV* sv, STRLEN* lp)
sv_pvn

A private implementation of the SvPV macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvn(SV *sv, STRLEN *len)
sv_pvn_force

Get a sensible string out of the SV somehow. A private implementation of the SvPV_force macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvn_force(SV* sv, STRLEN* lp)
sv_pvn_force_flags

Get a sensible string out of the SV somehow. If flags has SV_GMAGIC bit set, will mg_get on sv if appropriate, else not. sv_pvn_force and sv_pvn_force_nomg are implemented in terms of this function. You normally want to use the various wrapper macros instead: see SvPV_force and SvPV_force_nomg

        char*   sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
sv_pvutf8

Use the SvPVutf8_nolen macro instead

        char*   sv_pvutf8(SV *sv)
sv_pvutf8n

A private implementation of the SvPVutf8 macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvutf8n(SV *sv, STRLEN *len)
sv_pvutf8n_force

A private implementation of the SvPVutf8_force macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        char*   sv_pvutf8n_force(SV* sv, STRLEN* lp)
sv_reftype

Returns a string describing what the SV is a reference to.

        char*   sv_reftype(SV* sv, int ob)
sv_replace

Make the first argument a copy of the second, then delete the original. The target SV physically takes over ownership of the body of the source SV and inherits its flags; however, the target keeps any magic it owns, and any magic in the source is discarded. Note that this is a rather specialist SV copying operation; most of the time you'll want to use sv_setsv or one of its many macro front-ends.

        void    sv_replace(SV* sv, SV* nsv)
sv_report_used

Dump the contents of all SVs not yet freed. (Debugging aid).

        void    sv_report_used()
sv_reset

Underlying implementation for the reset Perl function. Note that the perl-level function is vaguely deprecated.

        void    sv_reset(char* s, HV* stash)
sv_rvweaken

Weaken a reference: set the SvWEAKREF flag on this RV; give the referred-to SV PERL_MAGIC_backref magic if it hasn't already; and push a back-reference to this RV onto the array of backreferences associated with that magic.

        SV*     sv_rvweaken(SV *sv)
sv_setiv

Copies an integer into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also sv_setiv_mg.

        void    sv_setiv(SV* sv, IV num)
sv_setiv_mg

Like sv_setiv, but also handles 'set' magic.

        void    sv_setiv_mg(SV *sv, IV i)
sv_setnv

Copies a double into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also sv_setnv_mg.

        void    sv_setnv(SV* sv, NV num)
sv_setnv_mg

Like sv_setnv, but also handles 'set' magic.

        void    sv_setnv_mg(SV *sv, NV num)
sv_setpv

Copies a string into an SV. The string must be null-terminated. Does not handle 'set' magic. See sv_setpv_mg.

        void    sv_setpv(SV* sv, const char* ptr)
sv_setpvf

Works like sv_catpvf but copies the text into the SV instead of appending it. Does not handle 'set' magic. See sv_setpvf_mg.

        void    sv_setpvf(SV* sv, const char* pat, ...)
sv_setpvf_mg

Like sv_setpvf, but also handles 'set' magic.

        void    sv_setpvf_mg(SV *sv, const char* pat, ...)
sv_setpviv

Copies an integer into the given SV, also updating its string value. Does not handle 'set' magic. See sv_setpviv_mg.

        void    sv_setpviv(SV* sv, IV num)
sv_setpviv_mg

Like sv_setpviv, but also handles 'set' magic.

        void    sv_setpviv_mg(SV *sv, IV iv)
sv_setpvn

Copies a string into an SV. The len parameter indicates the number of bytes to be copied. If the ptr argument is NULL the SV will become undefined. Does not handle 'set' magic. See sv_setpvn_mg.

        void    sv_setpvn(SV* sv, const char* ptr, STRLEN len)
sv_setpvn_mg

Like sv_setpvn, but also handles 'set' magic.

        void    sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
sv_setpv_mg

Like sv_setpv, but also handles 'set' magic.

        void    sv_setpv_mg(SV *sv, const char *ptr)
sv_setref_iv

Copies an integer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to Nullch to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

        SV*     sv_setref_iv(SV* rv, const char* classname, IV iv)
sv_setref_nv

Copies a double into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to Nullch to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

        SV*     sv_setref_nv(SV* rv, const char* classname, NV nv)
sv_setref_pv

Copies a pointer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. If the pv argument is NULL then PL_sv_undef will be placed into the SV. The classname argument indicates the package for the blessing. Set classname to Nullch to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Do not use with other Perl types such as HV, AV, SV, CV, because those objects will become corrupted by the pointer copy process.

Note that sv_setref_pvn copies the string while this copies the pointer.

        SV*     sv_setref_pv(SV* rv, const char* classname, void* pv)
sv_setref_pvn

Copies a string into a new SV, optionally blessing the SV. The length of the string must be specified with n. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to Nullch to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

Note that sv_setref_pv copies the pointer while this copies the string.

        SV*     sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
sv_setref_uv

Copies an unsigned integer into a new SV, optionally blessing the SV. The rv argument will be upgraded to an RV. That RV will be modified to point to the new SV. The classname argument indicates the package for the blessing. Set classname to Nullch to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned.

        SV*     sv_setref_uv(SV* rv, const char* classname, UV uv)
sv_setsv

Copies the contents of the source SV ssv into the destination SV dsv. The source SV may be destroyed if it is mortal, so don't use this function if the source SV needs to be reused. Does not handle 'set' magic. Loosely speaking, it performs a copy-by-value, obliterating any previous content of the destination.

You probably want to use one of the assortment of wrappers, such as SvSetSV, SvSetSV_nosteal, SvSetMagicSV and SvSetMagicSV_nosteal.

        void    sv_setsv(SV* dsv, SV* ssv)
sv_setsv_flags

Copies the contents of the source SV ssv into the destination SV dsv. The source SV may be destroyed if it is mortal, so don't use this function if the source SV needs to be reused. Does not handle 'set' magic. Loosely speaking, it performs a copy-by-value, obliterating any previous content of the destination. If the flags parameter has the SV_GMAGIC bit set, will mg_get on ssv if appropriate, else not. If the flags parameter has the NOSTEAL bit set then the buffers of temps will not be stolen. <sv_setsv> and sv_setsv_nomg are implemented in terms of this function.

You probably want to use one of the assortment of wrappers, such as SvSetSV, SvSetSV_nosteal, SvSetMagicSV and SvSetMagicSV_nosteal.

This is the primary function for copying scalars, and most other copy-ish functions and macros use this underneath.

        void    sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
sv_setsv_mg

Like sv_setsv, but also handles 'set' magic.

        void    sv_setsv_mg(SV *dstr, SV *sstr)
sv_setsv_nomg

Like sv_setsv but doesn't process magic.

        void    sv_setsv_nomg(SV* dsv, SV* ssv)
sv_setuv

Copies an unsigned integer into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also sv_setuv_mg.

        void    sv_setuv(SV* sv, UV num)
sv_setuv_mg

Like sv_setuv, but also handles 'set' magic.

        void    sv_setuv_mg(SV *sv, UV u)
sv_taint

Taint an SV. Use SvTAINTED_on instead.
void sv_taint(SV* sv)

sv_tainted

Test an SV for taintedness. Use SvTAINTED instead.
bool sv_tainted(SV* sv)

sv_true

Returns true if the SV has a true value by Perl's rules. Use the SvTRUE macro instead, which may call sv_true() or may instead use an in-line version.

        I32     sv_true(SV *sv)
sv_unmagic

Removes all magic of type type from an SV.

        int     sv_unmagic(SV* sv, int type)
sv_unref

Unsets the RV status of the SV, and decrements the reference count of whatever was being referenced by the RV. This can almost be thought of as a reversal of newSVrv. This is sv_unref_flags with the flag being zero. See SvROK_off.

        void    sv_unref(SV* sv)
sv_unref_flags

Unsets the RV status of the SV, and decrements the reference count of whatever was being referenced by the RV. This can almost be thought of as a reversal of newSVrv. The cflags argument can contain SV_IMMEDIATE_UNREF to force the reference count to be decremented (otherwise the decrementing is conditional on the reference count being different from one or the reference being a readonly SV). See SvROK_off.

        void    sv_unref_flags(SV* sv, U32 flags)
sv_untaint

Untaint an SV. Use SvTAINTED_off instead.
void sv_untaint(SV* sv)

sv_upgrade

Upgrade an SV to a more complex form. Generally adds a new body type to the SV, then copies across as much information as possible from the old body. You generally want to use the SvUPGRADE macro wrapper. See also svtype.

        bool    sv_upgrade(SV* sv, U32 mt)
sv_usepvn

Tells an SV to use ptr to find its string value. Normally the string is stored inside the SV but sv_usepvn allows the SV to use an outside string. The ptr should point to memory that was allocated by malloc. The string length, len, must be supplied. This function will realloc the memory pointed to by ptr, so that pointer should not be freed or used by the programmer after giving it to sv_usepvn. Does not handle 'set' magic. See sv_usepvn_mg.

        void    sv_usepvn(SV* sv, char* ptr, STRLEN len)
sv_usepvn_mg

Like sv_usepvn, but also handles 'set' magic.

        void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
sv_utf8_decode

If the PV of the SV is an octet sequence in UTF-8 and contains a multiple-byte character, the SvUTF8 flag is turned on so that it looks like a character. If the PV contains only single-byte characters, the SvUTF8 flag stays being off. Scans PV for validity and returns false if the PV is invalid UTF-8.

NOTE: this function is experimental and may change or be removed without notice.

        bool    sv_utf8_decode(SV *sv)
sv_utf8_downgrade

Attempts to convert the PV of an SV from characters to bytes. If the PV contains a character beyond byte, this conversion will fail; in this case, either returns false or, if fail_ok is not true, croaks.

This is not as a general purpose Unicode to byte encoding interface: use the Encode extension for that.

NOTE: this function is experimental and may change or be removed without notice.

        bool    sv_utf8_downgrade(SV *sv, bool fail_ok)
sv_utf8_encode

Converts the PV of an SV to UTF-8, but then turns the SvUTF8 flag off so that it looks like octets again.

        void    sv_utf8_encode(SV *sv)
sv_utf8_upgrade

Converts the PV of an SV to its UTF-8-encoded form. Forces the SV to string form if it is not already. Always sets the SvUTF8 flag to avoid future validity checks even if all the bytes have hibit clear.

This is not as a general purpose byte encoding to Unicode interface: use the Encode extension for that.

        STRLEN  sv_utf8_upgrade(SV *sv)
sv_utf8_upgrade_flags

Converts the PV of an SV to its UTF-8-encoded form. Forces the SV to string form if it is not already. Always sets the SvUTF8 flag to avoid future validity checks even if all the bytes have hibit clear. If flags has SV_GMAGIC bit set, will mg_get on sv if appropriate, else not. sv_utf8_upgrade and sv_utf8_upgrade_nomg are implemented in terms of this function.

This is not as a general purpose byte encoding to Unicode interface: use the Encode extension for that.

        STRLEN  sv_utf8_upgrade_flags(SV *sv, I32 flags)
sv_uv

A private implementation of the SvUVx macro for compilers which can't cope with complex macro expressions. Always use the macro instead.

        UV      sv_uv(SV* sv)
sv_vcatpvf

Processes its arguments like vsprintf and appends the formatted output to an SV. Does not handle 'set' magic. See sv_vcatpvf_mg.

Usually used via its frontend sv_catpvf.

        void    sv_vcatpvf(SV* sv, const char* pat, va_list* args)
sv_vcatpvfn

Processes its arguments like vsprintf and appends the formatted output to an SV. Uses an array of SVs if the C style variable argument list is missing (NULL). When running with taint checks enabled, indicates via maybe_tainted if results are untrustworthy (often due to the use of locales).

XXX Except that it maybe_tainted is never assigned to.

Usually used via one of its frontends sv_vcatpvf and sv_vcatpvf_mg.

        void    sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
sv_vcatpvf_mg

Like sv_vcatpvf, but also handles 'set' magic.

Usually used via its frontend sv_catpvf_mg.

        void    sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
sv_vsetpvf

Works like sv_vcatpvf but copies the text into the SV instead of appending it. Does not handle 'set' magic. See sv_vsetpvf_mg.

Usually used via its frontend sv_setpvf.

        void    sv_vsetpvf(SV* sv, const char* pat, va_list* args)
sv_vsetpvfn

Works like sv_vcatpvfn but copies the text into the SV instead of appending it.

Usually used via one of its frontends sv_vsetpvf and sv_vsetpvf_mg.

        void    sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
sv_vsetpvf_mg

Like sv_vsetpvf, but also handles 'set' magic.

Usually used via its frontend sv_setpvf_mg.

        void    sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)

Unicode Support

bytes_from_utf8

Converts a string s of length len from UTF-8 into byte encoding. Unlike utf8_to_bytes but like bytes_to_utf8, returns a pointer to the newly-created string, and updates len to contain the new length. Returns the original string if no conversion occurs, len is unchanged. Do nothing if is_utf8 points to 0. Sets is_utf8 to 0 if s is converted or contains all 7bit characters.

NOTE: this function is experimental and may change or be removed without notice.

        U8*     bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
bytes_to_utf8

Converts a string s of length len from ASCII into UTF-8 encoding. Returns a pointer to the newly-created string, and sets len to reflect the new length.

If you want to convert to UTF-8 from other encodings than ASCII, see sv_recode_to_utf8().

NOTE: this function is experimental and may change or be removed without notice.

        U8*     bytes_to_utf8(U8 *s, STRLEN *len)
ibcmp_utf8

Return true if the strings s1 and s2 differ case-insensitively, false if not (if they are equal case-insensitively). If u1 is true, the string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 are false, the respective string is assumed to be in native 8-bit encoding.

If the pe1 and pe2 are non-NULL, the scanning pointers will be copied in there (they will point at the beginning of the next character). If the pointers behind pe1 or pe2 are non-NULL, they are the end pointers beyond which scanning will not continue under any circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and s2+l2 will be used as goal end pointers that will also stop the scan, and which qualify towards defining a successful match: all the scans that define an explicit length must reach their goal pointers for a match to succeed).

For case-insensitiveness, the "casefolding" of Unicode is used instead of upper/lowercasing both the characters, see http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).

        I32     ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
is_utf8_char

Tests if some arbitrary number of bytes begins in a valid UTF-8 character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character. The actual number of bytes in the UTF-8 character will be returned if it is valid, otherwise 0.

        STRLEN  is_utf8_char(U8 *p)
is_utf8_string

Returns true if first len bytes of the given string form a valid UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does not mean 'a string that contains code points above 0x7F encoded in UTF-8' because a valid ASCII string is a valid UTF-8 string.

See also is_utf8_string_loclen() and is_utf8_string_loc().

        bool    is_utf8_string(U8 *s, STRLEN len)
is_utf8_string_loc

Like is_utf8_string() but stores the location of the failure (in the case of "utf8ness failure") or the location s+len (in the case of "utf8ness success") in the ep.

See also is_utf8_string_loclen() and is_utf8_string().

        bool    is_utf8_string_loc(U8 *s, STRLEN len, U8 **p)
is_utf8_string_loclen

Like is_utf8_string() but stores the location of the failure (in the case of "utf8ness failure") or the location s+len (in the case of "utf8ness success") in the ep, and the number of UTF-8 encoded characters in the el.

See also is_utf8_string_loc() and is_utf8_string().

        bool    is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
pv_uni_display

Build to the scalar dsv a displayable version of the string spv, length len, the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended).

The flags argument can have UNI_DISPLAY_ISPRINT set to display isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH to display the \\[nrfta\\] as the backslashed versions (like '\n') (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.

The pointer to the PV of the dsv is returned.

        char*   pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
sv_cat_decode

The encoding is assumed to be an Encode object, the PV of the ssv is assumed to be octets in that encoding and decoding the input starts from the position which (PV + *offset) pointed to. The dsv will be concatenated the decoded UTF-8 string from ssv. Decoding will terminate when the string tstr appears in decoding output or the input ends on the PV of the ssv. The value which the offset points will be modified to the last input position on the ssv.

Returns TRUE if the terminator was found, else returns FALSE.

        bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
sv_recode_to_utf8

The encoding is assumed to be an Encode object, on entry the PV of the sv is assumed to be octets in that encoding, and the sv will be converted into Unicode (and UTF-8).

If the sv already is UTF-8 (or if it is not POK), or if the encoding is not a reference, nothing is done to the sv. If the encoding is not an Encode::XS Encoding object, bad things will happen. (See lib/encoding.pm and the Encode manpage).

The PV of the sv is returned.

        char*   sv_recode_to_utf8(SV* sv, SV *encoding)
sv_uni_display

Build to the scalar dsv a displayable version of the scalar sv, the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended).

The flags argument is as in pv_uni_display().

The pointer to the PV of the dsv is returned.

        char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
to_utf8_case

The "p" contains the pointer to the UTF-8 string encoding the character that is being converted.

The "ustrp" is a pointer to the character buffer to put the conversion result to. The "lenp" is a pointer to the length of the result.

The "swashp" is a pointer to the swash to use.

Both the special and normal mappings are stored lib/unicore/To/Foo.pl, and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, but not always, a multicharacter mapping), is tried first.

The "special" is a string like "utf8::ToSpecLower", which means the hash %utf8::ToSpecLower. The access to the hash is through Perl_to_utf8_case().

The "normal" is a string like "ToLower" which means the swash %utf8::ToLower.

        UV      to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, char *normal, char *special)
to_utf8_fold

Convert the UTF-8 encoded character at p to its foldcase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be longer than the original character (up to three characters).

The first character of the foldcased version is returned (but note, as explained above, that there may be more.)

        UV      to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_lower

Convert the UTF-8 encoded character at p to its lowercase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the lowercase version may be longer than the original character.

The first character of the lowercased version is returned (but note, as explained above, that there may be more.)

        UV      to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_title

Convert the UTF-8 encoded character at p to its titlecase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the titlecase version may be longer than the original character.

The first character of the titlecased version is returned (but note, as explained above, that there may be more.)

        UV      to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
to_utf8_upper

Convert the UTF-8 encoded character at p to its uppercase version and store that in UTF-8 in ustrp and its length in bytes in lenp. Note that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the uppercase version may be longer than the original character.

The first character of the uppercased version is returned (but note, as explained above, that there may be more.)

        UV      to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
utf8n_to_uvchr

Returns the native character value of the first character in the string s which is assumed to be in UTF-8 encoding; retlen will be set to the length, in bytes, of that character.

Allows length and flags to be passed to low level routine.

        UV      utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
utf8n_to_uvuni

Bottom level UTF-8 decode routine. Returns the unicode code point value of the first character in the string s which is assumed to be in UTF-8 encoding and no longer than curlen; retlen will be set to the length, in bytes, of that character.

If s does not point to a well-formed UTF-8 character, the behaviour is dependent on the value of flags: if it contains UTF8_CHECK_ONLY, it is assumed that the caller will raise a warning, and this function will silently just set retlen to -1 and return zero. If the flags does not contain UTF8_CHECK_ONLY, warnings about malformations will be given, retlen will be set to the expected length of the UTF-8 character in bytes, and zero will be returned.

The flags can also contain various flags to allow deviations from the strict UTF-8 encoding (see utf8.h).

Most code should use utf8_to_uvchr() rather than call this directly.

        UV      utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
utf8_distance

Returns the number of UTF-8 characters between the UTF-8 pointers a and b.

WARNING: use only if you *know* that the pointers point inside the same UTF-8 buffer.

        IV      utf8_distance(U8 *a, U8 *b)
utf8_hop

Return the UTF-8 pointer s displaced by off characters, either forward or backward.

WARNING: do not use the following unless you *know* off is within the UTF-8 data pointed to by s *and* that on entry s is aligned on the first byte of character or just after the last byte of a character.

        U8*     utf8_hop(U8 *s, I32 off)
utf8_length

Return the length of the UTF-8 char encoded string s in characters. Stops at e (inclusive). If e < s or if the scan would end up past e, croaks.

        STRLEN  utf8_length(U8* s, U8 *e)
utf8_to_bytes

Converts a string s of length len from UTF-8 into byte encoding. Unlike bytes_to_utf8, this over-writes the original string, and updates len to contain the new length. Returns zero on failure, setting len to -1.

NOTE: this function is experimental and may change or be removed without notice.

        U8*     utf8_to_bytes(U8 *s, STRLEN *len)
utf8_to_uvchr

Returns the native character value of the first character in the string s which is assumed to be in UTF-8 encoding; retlen will be set to the length, in bytes, of that character.

If s does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1.

        UV      utf8_to_uvchr(U8 *s, STRLEN *retlen)
utf8_to_uvuni

Returns the Unicode code point of the first character in the string s which is assumed to be in UTF-8 encoding; retlen will be set to the length, in bytes, of that character.

This function should only be used when returned UV is considered an index into the Unicode semantic tables (e.g. swashes).

If s does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1.

        UV      utf8_to_uvuni(U8 *s, STRLEN *retlen)
uvchr_to_utf8

Adds the UTF-8 representation of the Native codepoint uv to the end of the string d; d should be have at least UTF8_MAXBYTES+1 free bytes available. The return value is the pointer to the byte after the end of the new character. In other words,

    d = uvchr_to_utf8(d, uv);

is the recommended wide native character-aware way of saying

    *(d++) = uv;

        U8*     uvchr_to_utf8(U8 *d, UV uv)
uvuni_to_utf8_flags

Adds the UTF-8 representation of the Unicode codepoint uv to the end of the string d; d should be have at least UTF8_MAXBYTES+1 free bytes available. The return value is the pointer to the byte after the end of the new character. In other words,

    d = uvuni_to_utf8_flags(d, uv, flags);

or, in most cases,

    d = uvuni_to_utf8(d, uv);

(which is equivalent to)

    d = uvuni_to_utf8_flags(d, uv, 0);

is the recommended Unicode-aware way of saying

    *(d++) = uv;

        U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)

Variables created by xsubpp and xsubpp internal functions

ax

Variable which is setup by xsubpp to indicate the stack base offset, used by the ST, XSprePUSH and XSRETURN macros. The dMARK macro must be called prior to setup the MARK variable.

        I32     ax
CLASS

Variable which is setup by xsubpp to indicate the class name for a C++ XS constructor. This is always a char*. See THIS.

        char*   CLASS
dAX

Sets up the ax variable. This is usually handled automatically by xsubpp by calling dXSARGS.

                dAX;
dAXMARK

Sets up the ax variable and stack marker variable mark. This is usually handled automatically by xsubpp by calling dXSARGS.

                dAXMARK;
dITEMS

Sets up the items variable. This is usually handled automatically by xsubpp by calling dXSARGS.

                dITEMS;
dXSARGS

Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. Sets up the ax and items variables by calling dAX and dITEMS. This is usually handled automatically by xsubpp.

                dXSARGS;
dXSI32

Sets up the ix variable for an XSUB which has aliases. This is usually handled automatically by xsubpp.

                dXSI32;
items

Variable which is setup by xsubpp to indicate the number of items on the stack. See Variable-length Parameter Lists in the perlxs manpage.

        I32     items
ix

Variable which is setup by xsubpp to indicate which of an XSUB's aliases was used to invoke it. See The ALIAS: Keyword in the perlxs manpage.

        I32     ix
newXSproto

Used by xsubpp to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs.

RETVAL

Variable which is setup by xsubpp to hold the return value for an XSUB. This is always the proper type for the XSUB. See The RETVAL Variable in the perlxs manpage.

        (whatever)      RETVAL
ST

Used to access elements on the XSUB's stack.

        SV*     ST(int ix)
THIS

Variable which is setup by xsubpp to designate the object in a C++ XSUB. This is always the proper type for the C++ object. See CLASS and Using XS With C++ in the perlxs manpage.

        (whatever)      THIS
XS

Macro to declare an XSUB and its C parameter list. This is handled by xsubpp.

XS_VERSION

The version identifier for an XS module. This is usually handled automatically by ExtUtils::MakeMaker. See XS_VERSION_BOOTCHECK.

XS_VERSION_BOOTCHECK

Macro to verify that a PM module's $VERSION variable matches the XS module's XS_VERSION variable. This is usually handled automatically by xsubpp. See The VERSIONCHECK: Keyword in the perlxs manpage.

                XS_VERSION_BOOTCHECK;

Warning and Dieing

croak

This is the XSUB-writer's interface to Perl's die function. Normally call this function the same way you call the C printf function. Calling croak returns control directly to Perl, sidestepping the normal C order of execution. See warn.

If you want to throw an exception object, assign the object to $@ and then pass Nullch to croak():

   errsv = get_sv("@", TRUE);
   sv_setsv(errsv, exception_object);
   croak(Nullch);

        void    croak(const char* pat, ...)
warn

This is the XSUB-writer's interface to Perl's warn function. Call this function the same way you call the C printf function. See croak.

        void    warn(const char* pat, ...)

AUTHORS

Until May 1997, this document was maintained by Jeff Okamoto <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.

With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, and Gurusamy Sarathy.

API Listing originally by Dean Roehrich <roehrich@cray.com>.

Updated to be autogenerated from comments in the source by Benjamin Stuhl.

SEE ALSO

perlguts(1), perlxs(1), perlxstut(1), perlintern(1)


perlapio - perl's IO abstraction interface.

    • Co-existence with stdio
    • "Fast gets" Functions
    • Other Functions

NAME

perlapio - perl's IO abstraction interface.

SYNOPSIS

    #define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */
    #include <perlio.h>           /* Usually via #include <perl.h> */

    PerlIO *PerlIO_stdin(void);
    PerlIO *PerlIO_stdout(void);
    PerlIO *PerlIO_stderr(void);

    PerlIO *PerlIO_open(const char *path,const char *mode);
    PerlIO *PerlIO_fdopen(int fd, const char *mode);
    PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old);  /* deprecated */
    int     PerlIO_close(PerlIO *f);

    int     PerlIO_stdoutf(const char *fmt,...)
    int     PerlIO_puts(PerlIO *f,const char *string);
    int     PerlIO_putc(PerlIO *f,int ch);
    int     PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
    int     PerlIO_printf(PerlIO *f, const char *fmt,...);
    int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
    int     PerlIO_flush(PerlIO *f);

    int     PerlIO_eof(PerlIO *f);
    int     PerlIO_error(PerlIO *f);
    void    PerlIO_clearerr(PerlIO *f);

    int     PerlIO_getc(PerlIO *d);
    int     PerlIO_ungetc(PerlIO *f,int ch);
    int     PerlIO_read(PerlIO *f, void *buf, size_t numbytes);

    int     PerlIO_fileno(PerlIO *f);

    void    PerlIO_setlinebuf(PerlIO *f);

    Off_t   PerlIO_tell(PerlIO *f);
    int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
    void    PerlIO_rewind(PerlIO *f);

    int     PerlIO_getpos(PerlIO *f, SV *save);        /* prototype changed */
    int     PerlIO_setpos(PerlIO *f, SV *saved);       /* prototype changed */

    int     PerlIO_fast_gets(PerlIO *f);
    int     PerlIO_has_cntptr(PerlIO *f);
    int     PerlIO_get_cnt(PerlIO *f);
    char   *PerlIO_get_ptr(PerlIO *f);
    void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count);

    int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
    void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */

    int     PerlIO_has_base(PerlIO *f);
    char   *PerlIO_get_base(PerlIO *f);
    int     PerlIO_get_bufsiz(PerlIO *f);

    PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
    FILE   *PerlIO_exportFILE(PerlIO *f, int flags);
    FILE   *PerlIO_findFILE(PerlIO *f);
    void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);

    int     PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
    int     PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
    void    PerlIO_debug(const char *fmt,...)

DESCRIPTION

Perl's source code, and extensions that want maximum portability, should use the above functions instead of those defined in ANSI C's stdio.h. The perl headers (in particular "perlio.h") will #define them to the I/O mechanism selected at Configure time.

The functions are modeled on those in stdio.h, but parameter order has been "tidied up a little".

PerlIO * takes the place of FILE *. Like FILE * it should be treated as opaque (it is probably safe to assume it is a pointer to something).

There are currently three implementations:

  1. USE_STDIO

    All above are #define'd to stdio functions or are trivial wrapper functions which call stdio. In this case only PerlIO * is a FILE *. This has been the default implementation since the abstraction was introduced in perl5.003_02.

  2. USE_SFIO

    A "legacy" implementation in terms of the "sfio" library. Used for some specialist applications on Unix machines ("sfio" is not widely ported away from Unix). Most of above are #define'd to the sfio functions. PerlIO * is in this case Sfio_t *.

  3. USE_PERLIO

    Introduced just after perl5.7.0, this is a re-implementation of the above abstraction which allows perl more control over how IO is done as it decouples IO from the way the operating system and C library choose to do things. For USE_PERLIO PerlIO * has an extra layer of indirection - it is a pointer-to-a-pointer. This allows the PerlIO * to remain with a known value while swapping the implementation around underneath at run time. In this case all the above are true (but very simple) functions which call the underlying implementation.

    This is the only implementation for which PerlIO_apply_layers() does anything "interesting".

    The USE_PERLIO implementation is described in the perliol manpage.

Because "perlio.h" is a thin layer (for efficiency) the semantics of these functions are somewhat dependent on the underlying implementation. Where these variations are understood they are noted below.

Unless otherwise noted, functions return 0 on success, or a negative value (usually EOF which is usually -1) and set errno on error.

PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()

Use these rather than stdin, stdout, stderr. They are written to look like "function calls" rather than variables because this makes it easier to make them function calls if platform cannot export data to loaded modules, or if (say) different "threads" might have different values.

PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)

These correspond to fopen()/fdopen() and the arguments are the same. Return NULL and set errno if there is an error. There may be an implementation limit on the number of open handles, which may be lower than the limit on the number of open files - errno may not be set when NULL is returned if this limit is exceeded.

PerlIO_reopen(path,mode,f)

While this currently exists in all three implementations perl itself does not use it. As perl does not use it, it is not well tested.

Perl prefers to dup the new low-level descriptor to the descriptor used by the existing PerlIO. This may become the behaviour of this function in the future.

PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)

These are fprintf()/vfprintf() equivalents.

PerlIO_stdoutf(fmt,...)

This is printf() equivalent. printf is #defined to this function, so it is (currently) legal to use printf(fmt,...) in perl sources.

PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)

These correspond functionally to fread() and fwrite() but the arguments and return values are different. The PerlIO_read() and PerlIO_write() signatures have been modeled on the more sane low level read() and write() functions instead: The "file" argument is passed first, there is only one "count", and the return value can distinguish between error and EOF.

Returns a byte count if successful (which may be zero or positive), returns negative value and sets errno on error. Depending on implementation errno may be EINTR if operation was interrupted by a signal.

PerlIO_close(f)

Depending on implementation errno may be EINTR if operation was interrupted by a signal.

PerlIO_puts(f,s), PerlIO_putc(f,c)

These correspond to fputs() and fputc(). Note that arguments have been revised to have "file" first.

PerlIO_ungetc(f,c)

This corresponds to ungetc(). Note that arguments have been revised to have "file" first. Arranges that next read operation will return the byte c. Despite the implied "character" in the name only values in the range 0..0xFF are defined. Returns the byte c on success or -1 (EOF) on error. The number of bytes that can be "pushed back" may vary, only 1 character is certain, and then only if it is the last character that was read from the handle.

PerlIO_getc(f)

This corresponds to getc(). Despite the c in the name only byte range 0..0xFF is supported. Returns the character read or -1 (EOF) on error.

PerlIO_eof(f)

This corresponds to feof(). Returns a true/false indication of whether the handle is at end of file. For terminal devices this may or may not be "sticky" depending on the implementation. The flag is cleared by PerlIO_seek(), or PerlIO_rewind().

PerlIO_error(f)

This corresponds to ferror(). Returns a true/false indication of whether there has been an IO error on the handle.

PerlIO_fileno(f)

This corresponds to fileno(), note that on some platforms, the meaning of "fileno" may not match Unix. Returns -1 if the handle has no open descriptor associated with it.

PerlIO_clearerr(f)

This corresponds to clearerr(), i.e., clears 'error' and (usually) 'eof' flags for the "stream". Does not return a value.

PerlIO_flush(f)

This corresponds to fflush(). Sends any buffered write data to the underlying file. If called with NULL this may flush all open streams (or core dump with some USE_STDIO implementations). Calling on a handle open for read only, or on which last operation was a read of some kind may lead to undefined behaviour on some USE_STDIO implementations. The USE_PERLIO (layers) implementation tries to behave better: it flushes all open streams when passed NULL, and attempts to retain data on read streams either in the buffer or by seeking the handle to the current logical position.

PerlIO_seek(f,offset,whence)

This corresponds to fseek(). Sends buffered write data to the underlying file, or discards any buffered read data, then positions the file descriptor as specified by offset and whence (sic). This is the correct thing to do when switching between read and write on the same handle (see issues with PerlIO_flush() above). Offset is of type Off_t which is a perl Configure value which may not be same as stdio's off_t.

PerlIO_tell(f)

This corresponds to ftell(). Returns the current file position, or (Off_t) -1 on error. May just return value system "knows" without making a system call or checking the underlying file descriptor (so use on shared file descriptors is not safe without a PerlIO_seek()). Return value is of type Off_t which is a perl Configure value which may not be same as stdio's off_t.

PerlIO_getpos(f,p), PerlIO_setpos(f,p)

These correspond (loosely) to fgetpos() and fsetpos(). Rather than stdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is stored there should be considered opaque. The layout of the data may vary from handle to handle. When not using stdio or if platform does not have the stdio calls then they are implemented in terms of PerlIO_tell() and PerlIO_seek().

PerlIO_rewind(f)

This corresponds to rewind(). It is usually defined as being

    PerlIO_seek(f,(Off_t)0L, SEEK_SET);
    PerlIO_clearerr(f);
PerlIO_tmpfile()

This corresponds to tmpfile(), i.e., returns an anonymous PerlIO or NULL on error. The system will attempt to automatically delete the file when closed. On Unix the file is usually unlink-ed just after it is created so it does not matter how it gets closed. On other systems the file may only be deleted if closed via PerlIO_close() and/or the program exits via exit. Depending on the implementation there may be "race conditions" which allow other processes access to the file, though in general it will be safer in this regard than ad. hoc. schemes.

PerlIO_setlinebuf(f)

This corresponds to setlinebuf(). Does not return a value. What constitutes a "line" is implementation dependent but usually means that writing "\n" flushes the buffer. What happens with things like "this\nthat" is uncertain. (Perl core uses it only when "dumping"; it has nothing to do with $| auto-flush.)

Co-existence with stdio

There is outline support for co-existence of PerlIO with stdio. Obviously if PerlIO is implemented in terms of stdio there is no problem. However in other cases then mechanisms must exist to create a FILE * which can be passed to library code which is going to use stdio calls.

The first step is to add this line:

   #define PERLIO_NOT_STDIO 0

before including any perl header files. (This will probably become the default at some point). That prevents "perlio.h" from attempting to #define stdio functions onto PerlIO functions.

XS code is probably better using "typemap" if it expects FILE * arguments. The standard typemap will be adjusted to comprehend any changes in this area.

PerlIO_importFILE(f,mode)

Used to get a PerlIO * from a FILE *.

The mode argument should be a string as would be passed to fopen/PerlIO_open. If it is NULL then - for legacy support - the code will (depending upon the platform and the implementation) either attempt to empirically determine the mode in which f is open, or use "r+" to indicate a read/write stream.

Once called the FILE * should ONLY be closed by calling PerlIO_close() on the returned PerlIO *.

The PerlIO is set to textmode. Use PerlIO_binmode if this is not the desired mode.

This is not the reverse of PerlIO_exportFILE().

PerlIO_exportFILE(f,mode)

Given a PerlIO * create a 'native' FILE * suitable for passing to code expecting to be compiled and linked with ANSI C stdio.h. The mode argument should be a string as would be passed to fopen/PerlIO_open. If it is NULL then - for legacy support - the FILE * is opened in same mode as the PerlIO *.

The fact that such a FILE * has been 'exported' is recorded, (normally by pushing a new :stdio "layer" onto the PerlIO *), which may affect future PerlIO operations on the original PerlIO *. You should not call fclose() on the file unless you call PerlIO_releaseFILE() to disassociate it from the PerlIO *. (Do not use PerlIO_importFILE() for doing the disassociation.)

Calling this function repeatedly will create a FILE * on each call (and will push an :stdio layer each time as well).

PerlIO_releaseFILE(p,f)

Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is complete. It is removed from the list of 'exported' FILE *s, and the associated PerlIO * should revert to its original behaviour.

Use this to disassociate a file from a PerlIO * that was associated using PerlIO_exportFILE().

PerlIO_findFILE(f)

Returns a native FILE * used by a stdio layer. If there is none, it will create one with PerlIO_exportFILE. In either case the FILE * should be considered as belonging to PerlIO subsystem and should only be closed by calling PerlIO_close().

"Fast gets" Functions

In addition to standard-like API defined so far above there is an "implementation" interface which allows perl to get at internals of PerlIO. The following calls correspond to the various FILE_xxx macros determined by Configure - or their equivalent in other implementations. This section is really of interest to only those concerned with detailed perl-core behaviour, implementing a PerlIO mapping or writing code which can make use of the "read ahead" that has been done by the IO system in the same way perl does. Note that any code that uses these interfaces must be prepared to do things the traditional way if a handle does not support them.

PerlIO_fast_gets(f)

Returns true if implementation has all the interfaces required to allow perl's sv_gets to "bypass" normal IO mechanism. This can vary from handle to handle.

  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                        PerlIO_canset_cnt(f) && \
                        `Can set pointer into buffer'
PerlIO_has_cntptr(f)

Implementation can return pointer to current position in the "buffer" and a count of bytes available in the buffer. Do not use this - use PerlIO_fast_gets.

PerlIO_get_cnt(f)

Return count of readable bytes in the buffer. Zero or negative return means no more bytes available.

PerlIO_get_ptr(f)

Return pointer to next readable byte in buffer, accessing via the pointer (dereferencing) is only safe if PerlIO_get_cnt() has returned a positive value. Only positive offsets up to value returned by PerlIO_get_cnt() are allowed.

PerlIO_set_ptrcnt(f,p,c)

Set pointer into buffer, and a count of bytes still in the buffer. Should be used only to set pointer to within range implied by previous calls to PerlIO_get_ptr and PerlIO_get_cnt. The two values must be consistent with each other (implementation may only use one or the other or may require both).

PerlIO_canset_cnt(f)

Implementation can adjust its idea of number of bytes in the buffer. Do not use this - use PerlIO_fast_gets.

PerlIO_set_cnt(f,c)

Obscure - set count of bytes in the buffer. Deprecated. Only usable if PerlIO_canset_cnt() returns true. Currently used in only doio.c to force count less than -1 to -1. Perhaps should be PerlIO_set_empty or similar. This call may actually do nothing if "count" is deduced from pointer and a "limit". Do not use this - use PerlIO_set_ptrcnt().

PerlIO_has_base(f)

Returns true if implementation has a buffer, and can return pointer to whole buffer and its size. Used by perl for -T / -B tests. Other uses would be very obscure...

PerlIO_get_base(f)

Return start of buffer. Access only positive offsets in the buffer up to the value returned by PerlIO_get_bufsiz().

PerlIO_get_bufsiz(f)

Return the total number of bytes in the buffer, this is neither the number that can be read, nor the amount of memory allocated to the buffer. Rather it is what the operating system and/or implementation happened to read() (or whatever) last time IO was requested.

Other Functions

PerlIO_apply_layers(f,mode,layers)

The new interface to the USE_PERLIO implementation. The layers ":crlf" and ":raw" are only ones allowed for other implementations and those are silently ignored. (As of perl5.8 ":raw" is deprecated.) Use PerlIO_binmode() below for the portable case.

PerlIO_binmode(f,ptype,imode,layers)

The hook used by perl's binmode operator. ptype is perl's character for the kind of IO:

'<' read
'>' write
'+' read/write

imode is O_BINARY or O_TEXT.

layers is a string of layers to apply, only ":crlf" makes sense in the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour of passing NULL.)

Portable cases are:

    PerlIO_binmode(f,ptype,O_BINARY,Nullch);
    and
    PerlIO_binmode(f,ptype,O_TEXT,":crlf");

On Unix these calls probably have no effect whatsoever. Elsewhere they alter "\n" to CR,LF translation and possibly cause a special text "end of file" indicator to be written or honoured on read. The effect of making the call after doing any IO to the handle depends on the implementation. (It may be ignored, affect any data which is already buffered as well, or only apply to subsequent data.)

PerlIO_debug(fmt,...)

PerlIO_debug is a printf()-like function which can be used for debugging. No return value. Its main use is inside PerlIO where using real printf, warn() etc. would recursively call PerlIO and be a problem.

PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical use might be

  Bourne shells (sh, ksh, bash, zsh, ash, ...):
   PERLIO_DEBUG=/dev/tty ./perl somescript some args
  Csh/Tcsh:
   setenv PERLIO_DEBUG /dev/tty
   ./perl somescript some args
  If you have the "env" utility:
   env PERLIO_DEBUG=/dev/tty ./perl somescript some args
  Win32:
   set PERLIO_DEBUG=CON
   perl somescript some args

If $ENV{'PERLIO_DEBUG'} is not set PerlIO_debug() is a no-op.


perlcall - Perl calling conventions from C

  • THE CALL_ FUNCTIONS
  • FLAG VALUES
    • G_VOID
    • G_SCALAR
    • G_ARRAY
    • G_DISCARD
    • G_NOARGS
    • G_EVAL
    • G_KEEPERR
    • Determining the Context
  • EXAMPLES
    • No Parameters, Nothing returned
    • Passing Parameters
    • Returning a Scalar
    • Returning a list of values
    • Returning a list in a scalar context
    • Returning Data from Perl via the parameter list
    • Using G_EVAL
    • Using G_KEEPERR
    • Using call_sv
    • Using call_argv
    • Using call_method
    • Using GIMME_V
    • Using Perl to dispose of temporaries
    • Strategies for storing Callback Context Information
    • Alternate Stack Manipulation
    • Creating and calling an anonymous subroutine in C
  • SEE ALSO
  • AUTHOR
  • DATE

NAME

perlcall - Perl calling conventions from C

DESCRIPTION

The purpose of this document is to show you how to call Perl subroutines directly from C, i.e., how to write callbacks.

Apart from discussing the C interface provided by Perl for writing callbacks the document uses a series of examples to show how the interface actually works in practice. In addition some techniques for coding callbacks are covered.

Examples where callbacks are necessary include

  • An Error Handler

    You have created an XSUB interface to an application's C API.

    A fairly common feature in applications is to allow you to define a C function that will be called whenever something nasty occurs. What we would like is to be able to specify a Perl subroutine that will be called instead.

  • An Event Driven Program

    The classic example of where callbacks are used is when writing an event driven program like for an X windows application. In this case you register functions to be called whenever specific events occur, e.g., a mouse button is pressed, the cursor moves into a window or a menu item is selected.

Although the techniques described here are applicable when embedding Perl in a C program, this is not the primary goal of this document. There are other details that must be considered and are specific to embedding Perl. For details on embedding Perl in C refer to the perlembed manpage.

Before you launch yourself head first into the rest of this document, it would be a good idea to have read the following two documents - the perlxs manpage and the perlguts manpage.

THE CALL_ FUNCTIONS

Although this stuff is easier to explain using examples, you first need be aware of a few important definitions.

Perl has a number of C functions that allow you to call Perl subroutines. They are

    I32 call_sv(SV* sv, I32 flags);
    I32 call_pv(char *subname, I32 flags);
    I32 call_method(char *methname, I32 flags);
    I32 call_argv(char *subname, I32 flags, register char **argv);

The key function is call_sv. All the other functions are fairly simple wrappers which make it easier to call Perl subroutines in special cases. At the end of the day they will all call call_sv to invoke the Perl subroutine.

All the call_* functions have a flags parameter which is used to pass a bit mask of options to Perl. This bit mask operates identically for each of the functions. The settings available in the bit mask are discussed in FLAG VALUES.

Each of the functions will now be discussed in turn.

call_sv

call_sv takes two parameters, the first, sv, is an SV*. This allows you to specify the Perl subroutine to be called either as a C string (which has first been converted to an SV) or a reference to a subroutine. The section, Using call_sv, shows how you can make use of call_sv.

call_pv

The function, call_pv, is similar to call_sv except it expects its first parameter to be a C char* which identifies the Perl subroutine you want to call, e.g., call_pv("fred", 0). If the subroutine you want to call is in another package, just include the package name in the string, e.g., "pkg::fred".

call_method

The function call_method is used to call a method from a Perl class. The parameter methname corresponds to the name of the method to be called. Note that the class that the method belongs to is passed on the Perl stack rather than in the parameter list. This class can be either the name of the class (for a static method) or a reference to an object (for a virtual method). See the perlobj manpage for more information on static and virtual methods and Using call_method for an example of using call_method.

call_argv

call_argv calls the Perl subroutine specified by the C string stored in the subname parameter. It also takes the usual flags parameter. The final parameter, argv, consists of a NULL terminated list of C strings to be passed as parameters to the Perl subroutine. See Using call_argv.

All the functions return an integer. This is a count of the number of items returned by the Perl subroutine. The actual items returned by the subroutine are stored on the Perl stack.

As a general rule you should always check the return value from these functions. Even if you are expecting only a particular number of values to be returned from the Perl subroutine, there is nothing to stop someone from doing something unexpected--don't say you haven't been warned.

FLAG VALUES

The flags parameter in all the call_* functions is a bit mask which can consist of any combination of the symbols defined below, OR'ed together.

G_VOID

Calls the Perl subroutine in a void context.

This flag has 2 effects:

  1. It indicates to the subroutine being called that it is executing in a void context (if it executes wantarray the result will be the undefined value).

  2. It ensures that nothing is actually returned from the subroutine.

The value returned by the call_* function indicates how many items have been returned by the Perl subroutine - in this case it will be 0.

G_SCALAR

Calls the Perl subroutine in a scalar context. This is the default context flag setting for all the call_* functions.

This flag has 2 effects:

  1. It indicates to the subroutine being called that it is executing in a scalar context (if it executes wantarray the result will be false).

  2. It ensures that only a scalar is actually returned from the subroutine. The subroutine can, of course, ignore the wantarray and return a list anyway. If so, then only the last element of the list will be returned.

The value returned by the call_* function indicates how many items have been returned by the Perl subroutine - in this case it will be either 0 or 1.

If 0, then you have specified the G_DISCARD flag.

If 1, then the item actually returned by the Perl subroutine will be stored on the Perl stack - the section Returning a Scalar shows how to access this value on the stack. Remember that regardless of how many items the Perl subroutine returns, only the last one will be accessible from the stack - think of the case where only one value is returned as being a list with only one element. Any other items that were returned will not exist by the time control returns from the call_* function. The section Returning a list in a scalar context shows an example of this behavior.

G_ARRAY

Calls the Perl subroutine in a list context.

As with G_SCALAR, this flag has 2 effects:

  1. It indicates to the subroutine being called that it is executing in a list context (if it executes wantarray the result will be true).

  2. It ensures that all items returned from the subroutine will be accessible when control returns from the call_* function.

The value returned by the call_* function indicates how many items have been returned by the Perl subroutine.

If 0, then you have specified the G_DISCARD flag.

If not 0, then it will be a count of the number of items returned by the subroutine. These items will be stored on the Perl stack. The section Returning a list of values gives an example of using the G_ARRAY flag and the mechanics of accessing the returned items from the Perl stack.

G_DISCARD

By default, the call_* functions place the items returned from by the Perl subroutine on the stack. If you are not interested in these items, then setting this flag will make Perl get rid of them automatically for you. Note that it is still possible to indicate a context to the Perl subroutine by using either G_SCALAR or G_ARRAY.

If you do not set this flag then it is very important that you make sure that any temporaries (i.e., parameters passed to the Perl subroutine and values returned from the subroutine) are disposed of yourself. The section Returning a Scalar gives details of how to dispose of these temporaries explicitly and the section Using Perl to dispose of temporaries discusses the specific circumstances where you can ignore the problem and let Perl deal with it for you.

G_NOARGS

Whenever a Perl subroutine is called using one of the call_* functions, it is assumed by default that parameters are to be passed to the subroutine. If you are not passing any parameters to the Perl subroutine, you can save a bit of time by setting this flag. It has the effect of not creating the @_ array for the Perl subroutine.

Although the functionality provided by this flag may seem straightforward, it should be used only if there is a good reason to do so. The reason for being cautious is that even if you have specified the G_NOARGS flag, it is still possible for the Perl subroutine that has been called to think that you have passed it parameters.

In fact, what can happen is that the Perl subroutine you have called can access the @_ array from a previous Perl subroutine. This will occur when the code that is executing the call_* function has itself been called from another Perl subroutine. The code below illustrates this

    sub fred
      { print "@_\n"  }

    sub joe
      { &fred }

    &joe(1,2,3);

This will print

    1 2 3

What has happened is that fred accesses the @_ array which belongs to joe.

G_EVAL

It is possible for the Perl subroutine you are calling to terminate abnormally, e.g., by calling die explicitly or by not actually existing. By default, when either of these events occurs, the process will terminate immediately. If you want to trap this type of event, specify the G_EVAL flag. It will put an eval { } around the subroutine call.

Whenever control returns from the call_* function you need to check the $@ variable as you would in a normal Perl script.

The value returned from the call_* function is dependent on what other flags have been specified and whether an error has occurred. Here are all the different cases that can occur:

  • If the call_* function returns normally, then the value returned is as specified in the previous sections.

  • If G_DISCARD is specified, the return value will always be 0.

  • If G_ARRAY is specified and an error has occurred, the return value will always be 0.

  • If G_SCALAR is specified and an error has occurred, the return value will be 1 and the value on the top of the stack will be undef. This means that if you have already detected the error by checking $@ and you want the program to continue, you must remember to pop the undef from the stack.

See Using G_EVAL for details on using G_EVAL.

G_KEEPERR

You may have noticed that using the G_EVAL flag described above will always clear the $@ variable and set it to a string describing the error iff there was an error in the called code. This unqualified resetting of $@ can be problematic in the reliable identification of errors using the eval {} mechanism, because the possibility exists that perl will call other code (end of block processing code, for example) between the time the error causes $@ to be set within eval {}, and the subsequent statement which checks for the value of $@ gets executed in the user's script.

This scenario will mostly be applicable to code that is meant to be called from within destructors, asynchronous callbacks, signal handlers, __DIE__ or __WARN__ hooks, and tie functions. In such situations, you will not want to clear $@ at all, but simply to append any new errors to any existing value of $@.

The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in call_* functions that are used to implement such code. This flag has no effect when G_EVAL is not used.

When G_KEEPERR is used, any errors in the called code will be prefixed with the string "\t(in cleanup)", and appended to the current value of $@. an error will not be appended if that same error string is already at the end of $@.

In addition, a warning is generated using the appended string. This can be disabled using no warnings 'misc'.

The G_KEEPERR flag was introduced in Perl version 5.002.

See Using G_KEEPERR for an example of a situation that warrants the use of this flag.

Determining the Context

As mentioned above, you can determine the context of the currently executing subroutine in Perl with wantarray. The equivalent test can be made in C by using the GIMME_V macro, which returns G_ARRAY if you have been called in a list context, G_SCALAR if in a scalar context, or G_VOID if in a void context (i.e. the return value will not be used). An older version of this macro is called GIMME; in a void context it returns G_SCALAR instead of G_VOID. An example of using the GIMME_V macro is shown in section Using GIMME_V.

EXAMPLES

Enough of the definition talk, let's have a few examples.

Perl provides many macros to assist in accessing the Perl stack. Wherever possible, these macros should always be used when interfacing to Perl internals. We hope this should make the code less vulnerable to any changes made to Perl in the future.

Another point worth noting is that in the first series of examples I have made use of only the call_pv function. This has been done to keep the code simpler and ease you into the topic. Wherever possible, if the choice is between using call_pv and call_sv, you should always try to use call_sv. See Using call_sv for details.

No Parameters, Nothing returned

This first trivial example will call a Perl subroutine, PrintUID, to print out the UID of the process.

    sub PrintUID
    {
        print "UID is $<\n";
    }

and here is a C function to call it

    static void
    call_PrintUID()
    {
        dSP;

        PUSHMARK(SP);
        call_pv("PrintUID", G_DISCARD|G_NOARGS);
            }

Simple, eh.

A few points to note about this example.

  1. Ignore dSP and PUSHMARK(SP) for now. They will be discussed in the next example.

  2. We aren't passing any parameters to PrintUID so G_NOARGS can be specified.

  3. We aren't interested in anything returned from PrintUID, so G_DISCARD is specified. Even if PrintUID was changed to return some value(s), having specified G_DISCARD will mean that they will be wiped by the time control returns from call_pv.

  4. As call_pv is being used, the Perl subroutine is specified as a C string. In this case the subroutine name has been 'hard-wired' into the code.

  5. Because we specified G_DISCARD, it is not necessary to check the value returned from call_pv. It will always be 0.

Passing Parameters

Now let's make a slightly more complex example. This time we want to call a Perl subroutine, LeftString, which will take 2 parameters--a string ($s) and an integer ($n). The subroutine will simply print the first $n characters of the string.

So the Perl subroutine would look like this

    sub LeftString
    {
        my($s, $n) = @_;
        print substr($s, 0, $n), "\n";
    }

The C function required to call LeftString would look like this.

    static void
    call_LeftString(a, b)
    char * a;
    int b;
    {
        dSP;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(a, 0)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        call_pv("LeftString", G_DISCARD);

        FREETMPS;
        LEAVE;
            }

Here are a few notes on the C function call_LeftString.

  1. Parameters are passed to the Perl subroutine using the Perl stack. This is the purpose of the code beginning with the line dSP and ending with the line PUTBACK. The dSP declares a local copy of the stack pointer. This local copy should always be accessed as SP.

  2. If you are going to put something onto the Perl stack, you need to know where to put it. This is the purpose of the macro dSP--it declares and initializes a local copy of the Perl stack pointer.

    All the other macros which will be used in this example require you to have used this macro.

    The exception to this rule is if you are calling a Perl subroutine directly from an XSUB function. In this case it is not necessary to use the dSP macro explicitly--it will be declared for you automatically.

  3. Any parameters to be pushed onto the stack should be bracketed by the PUSHMARK and PUTBACK macros. The purpose of these two macros, in this context, is to count the number of parameters you are pushing automatically. Then whenever Perl is creating the @_ array for the subroutine, it knows how big to make it.

    The PUSHMARK macro tells Perl to make a mental note of the current stack pointer. Even if you aren't passing any parameters (like the example shown in the section No Parameters, Nothing returned) you must still call the PUSHMARK macro before you can call any of the call_* functions--Perl still needs to know that there are no parameters.

    The PUTBACK macro sets the global copy of the stack pointer to be the same as our local copy. If we didn't do this call_pv wouldn't know where the two parameters we pushed were--remember that up to now all the stack pointer manipulation we have done is with our local copy, not the global copy.

  4. Next, we come to XPUSHs. This is where the parameters actually get pushed onto the stack. In this case we are pushing a string and an integer.

    See XSUBs and the Argument Stack in the perlguts manpage for details on how the XPUSH macros work.

  5. Because we created temporary values (by means of sv_2mortal() calls) we will have to tidy up the Perl stack and dispose of mortal SVs.

    This is the purpose of

        ENTER;
    SAVETMPS;

    at the start of the function, and

        FREETMPS;
    LEAVE;

    at the end. The ENTER/SAVETMPS pair creates a boundary for any temporaries we create. This means that the temporaries we get rid of will be limited to those which were created after these calls.

    The FREETMPS/LEAVE pair will get rid of any values returned by the Perl subroutine (see next example), plus it will also dump the mortal SVs we have created. Having ENTER/SAVETMPS at the beginning of the code makes sure that no other mortals are destroyed.

    Think of these macros as working a bit like using { and } in Perl to limit the scope of local variables.

    See the section Using Perl to dispose of temporaries for details of an alternative to using these macros.

  6. Finally, LeftString can now be called via the call_pv function. The only flag specified this time is G_DISCARD. Because we are passing 2 parameters to the Perl subroutine this time, we have not specified G_NOARGS.

Returning a Scalar

Now for an example of dealing with the items returned from a Perl subroutine.

Here is a Perl subroutine, Adder, that takes 2 integer parameters and simply returns their sum.

    sub Adder
    {
        my($a, $b) = @_;
        $a + $b;
    }

Because we are now concerned with the return value from Adder, the C function required to call it is now a bit more complex.

    static void
    call_Adder(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("Adder", G_SCALAR);

        SPAGAIN;

        if (count != 1)
            croak("Big trouble\n");

        printf ("The sum of %d and %d is %d\n", a, b, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
            }

Points to note this time are

  1. The only flag specified this time was G_SCALAR. That means the @_ array will be created and that the value returned by Adder will still exist after the call to call_pv.

  2. The purpose of the macro SPAGAIN is to refresh the local copy of the stack pointer. This is necessary because it is possible that the memory allocated to the Perl stack has been reallocated whilst in the call_pv call.

    If you are making use of the Perl stack pointer in your code you must always refresh the local copy using SPAGAIN whenever you make use of the call_* functions or any other Perl internal function.

  3. Although only a single value was expected to be returned from Adder, it is still good practice to check the return code from call_pv anyway.

    Expecting a single value is not quite the same as knowing that there will be one. If someone modified Adder to return a list and we didn't check for that possibility and take appropriate action the Perl stack would end up in an inconsistent state. That is something you really don't want to happen ever.

  4. The POPi macro is used here to pop the return value from the stack. In this case we wanted an integer, so POPi was used.

    Here is the complete list of POP macros available, along with the types they return.

        POPs        SV
    POPp        pointer
    POPn        double
    POPi        integer
    POPl        long

  5. The final PUTBACK is used to leave the Perl stack in a consistent state before exiting the function. This is necessary because when we popped the return value from the stack with POPi it updated only our local copy of the stack pointer. Remember, PUTBACK sets the global stack pointer to be the same as our local copy.

Returning a list of values

Now, let's extend the previous example to return both the sum of the parameters and the difference.

Here is the Perl subroutine

    sub AddSubtract
    {
       my($a, $b) = @_;
       ($a+$b, $a-$b);
    }

and this is the C function

    static void
    call_AddSubtract(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_ARRAY);

        SPAGAIN;

        if (count != 2)
            croak("Big trouble\n");

        printf ("%d - %d = %d\n", a, b, POPi);
        printf ("%d + %d = %d\n", a, b, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
            }

If call_AddSubtract is called like this

    call_AddSubtract(7, 4);

then here is the output

    7 - 4 = 3
    7 + 4 = 11

Notes

  1. We wanted list context, so G_ARRAY was used.

  2. Not surprisingly POPi is used twice this time because we were retrieving 2 values from the stack. The important thing to note is that when using the POP* macros they come off the stack in reverse order.

Returning a list in a scalar context

Say the Perl subroutine in the previous section was called in a scalar context, like this

    static void
    call_AddSubScalar(a, b)
    int a;
    int b;
    {
        dSP;
        int count;
        int i;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_SCALAR);

        SPAGAIN;

        printf ("Items Returned = %d\n", count);

        for (i = 1; i <= count; ++i)
            printf ("Value %d = %d\n", i, POPi);

        PUTBACK;
        FREETMPS;
        LEAVE;
            }

The other modification made is that call_AddSubScalar will print the number of items returned from the Perl subroutine and their value (for simplicity it assumes that they are integer). So if call_AddSubScalar is called

    call_AddSubScalar(7, 4);

then the output will be

    Items Returned = 1
    Value 1 = 3

In this case the main point to note is that only the last item in the list is returned from the subroutine, AddSubtract actually made it back to call_AddSubScalar.

Returning Data from Perl via the parameter list

It is also possible to return values directly via the parameter list - whether it is actually desirable to do it is another matter entirely.

The Perl subroutine, Inc, below takes 2 parameters and increments each directly.

    sub Inc
    {
        ++ $_[0];
        ++ $_[1];
    }

and here is a C function to call it.

    static void
    call_Inc(a, b)
    int a;
    int b;
    {
        dSP;
        int count;
        SV * sva;
        SV * svb;

        ENTER;
        SAVETMPS;

        sva = sv_2mortal(newSViv(a));
        svb = sv_2mortal(newSViv(b));

        PUSHMARK(SP);
        XPUSHs(sva);
        XPUSHs(svb);
        PUTBACK;

        count = call_pv("Inc", G_DISCARD);

        if (count != 0)
            croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
                   count);

        printf ("%d + 1 = %d\n", a, SvIV(sva));
        printf ("%d + 1 = %d\n", b, SvIV(svb));

        FREETMPS;
        LEAVE;
            }

To be able to access the two parameters that were pushed onto the stack after they return from call_pv it is necessary to make a note of their addresses--thus the two variables sva and svb.

The reason this is necessary is that the area of the Perl stack which held them will very likely have been overwritten by something else by the time control returns from call_pv.

Using G_EVAL

Now an example using G_EVAL. Below is a Perl subroutine which computes the difference of its 2 parameters. If this would result in a negative result, the subroutine calls die.

    sub Subtract
    {
        my ($a, $b) = @_;

        die "death can be fatal\n" if $a < $b;

        $a - $b;
            }

and some C to call it

    static void
    call_Subtract(a, b)
    int a;
    int b;
    {
        dSP;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("Subtract", G_EVAL|G_SCALAR);

        SPAGAIN;

        /* Check the eval first */
        if (SvTRUE(ERRSV))
        {
            STRLEN n_a;
            printf ("Uh oh - %s\n", SvPV(ERRSV, n_a));
            POPs;
        }
        else
        {
            if (count != 1)
               croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
                        count);

            printf ("%d - %d = %d\n", a, b, POPi);
                    }

        PUTBACK;
        FREETMPS;
        LEAVE;
            }

If call_Subtract is called thus

    call_Subtract(4, 5)

the following will be printed

    Uh oh - death can be fatal

Notes

  1. We want to be able to catch the die so we have used the G_EVAL flag. Not specifying this flag would mean that the program would terminate immediately at the die statement in the subroutine Subtract.

  2. The code

        if (SvTRUE(ERRSV))
    {
        STRLEN n_a;
        printf ("Uh oh - %s\n", SvPV(ERRSV, n_a));
        POPs;
    }

    is the direct equivalent of this bit of Perl

        print "Uh oh - $@\n" if $@;

    PL_errgv is a perl global of type GV * that points to the symbol table entry containing the error. ERRSV therefore refers to the C equivalent of $@.

  3. Note that the stack is popped using POPs in the block where SvTRUE(ERRSV) is true. This is necessary because whenever a call_* function invoked with G_EVAL|G_SCALAR returns an error, the top of the stack holds the value undef. Because we want the program to continue after detecting this error, it is essential that the stack is tidied up by removing the undef.

Using G_KEEPERR

Consider this rather facetious example, where we have used an XS version of the call_Subtract example above inside a destructor:

    package Foo;
    sub new { bless {}, $_[0] }
    sub Subtract {
        my($a,$b) = @_;
        die "death can be fatal" if $a < $b;
        $a - $b;
    }
    sub DESTROY { call_Subtract(5, 4); }
    sub foo { die "foo dies"; }

    package main;
    eval { Foo->new->foo };
    print "Saw: $@" if $@;             # should be, but isn't

This example will fail to recognize that an error occurred inside the eval {}. Here's why: the call_Subtract code got executed while perl was cleaning up temporaries when exiting the eval block, and because call_Subtract is implemented with call_pv using the G_EVAL flag, it promptly reset $@. This results in the failure of the outermost test for $@, and thereby the failure of the error trap.

Appending the G_KEEPERR flag, so that the call_pv call in call_Subtract reads:

        count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);

will preserve the error and restore reliable error handling.

Using call_sv

In all the previous examples I have 'hard-wired' the name of the Perl subroutine to be called from C. Most of the time though, it is more convenient to be able to specify the name of the Perl subroutine from within the Perl script.

Consider the Perl code below

    sub fred
    {
        print "Hello there\n";
    }

    CallSubPV("fred");

Here is a snippet of XSUB which defines CallSubPV.

    void
    CallSubPV(name)
        char *  name
        CODE:
        PUSHMARK(SP);
        call_pv(name, G_DISCARD|G_NOARGS);

That is fine as far as it goes. The thing is, the Perl subroutine can be specified as only a string. For Perl 4 this was adequate, but Perl 5 allows references to subroutines and anonymous subroutines. This is where call_sv is useful.

The code below for CallSubSV is identical to CallSubPV except that the name parameter is now defined as an SV* and we use call_sv instead of call_pv.

    void
    CallSubSV(name)
        SV *    name
        CODE:
        PUSHMARK(SP);
        call_sv(name, G_DISCARD|G_NOARGS);

Because we are using an SV to call fred the following can all be used

    CallSubSV("fred");
    CallSubSV(\&fred);
    $ref = \&fred;
    CallSubSV($ref);
    CallSubSV( sub { print "Hello there\n" } );

As you can see, call_sv gives you much greater flexibility in how you can specify the Perl subroutine.

You should note that if it is necessary to store the SV (name in the example above) which corresponds to the Perl subroutine so that it can be used later in the program, it not enough just to store a copy of the pointer to the SV. Say the code above had been like this

    static SV * rememberSub;

    void
    SaveSub1(name)
        SV *    name
        CODE:
        rememberSub = name;

    void
    CallSavedSub1()
        CODE:
        PUSHMARK(SP);
        call_sv(rememberSub, G_DISCARD|G_NOARGS);

The reason this is wrong is that by the time you come to use the pointer rememberSub in CallSavedSub1, it may or may not still refer to the Perl subroutine that was recorded in SaveSub1. This is particularly true for these cases

    SaveSub1(\&fred);
    CallSavedSub1();

    SaveSub1( sub { print "Hello there\n" } );
    CallSavedSub1();

By the time each of the SaveSub1 statements above have been executed, the SV*s which corresponded to the parameters will no longer exist. Expect an error message from Perl of the form

    Can't use an undefined value as a subroutine reference at ...

for each of the CallSavedSub1 lines.

Similarly, with this code

    $ref = \&fred;
    SaveSub1($ref);
    $ref = 47;
    CallSavedSub1();

you can expect one of these messages (which you actually get is dependent on the version of Perl you are using)

    Not a CODE reference at ...
    Undefined subroutine &main::47 called ...

The variable $ref may have referred to the subroutine fred whenever the call to SaveSub1 was made but by the time CallSavedSub1 gets called it now holds the number 47. Because we saved only a pointer to the original SV in SaveSub1, any changes to $ref will be tracked by the pointer rememberSub. This means that whenever CallSavedSub1 gets called, it will attempt to execute the code which is referenced by the SV* rememberSub. In this case though, it now refers to the integer 47, so expect Perl to complain loudly.

A similar but more subtle problem is illustrated with this code

    $ref = \&fred;
    SaveSub1($ref);
    $ref = \&joe;
    CallSavedSub1();

This time whenever CallSavedSub1 get called it will execute the Perl subroutine joe (assuming it exists) rather than fred as was originally requested in the call to SaveSub1.

To get around these problems it is necessary to take a full copy of the SV. The code below shows SaveSub2 modified to do that

    static SV * keepSub = (SV*)NULL;

    void
    SaveSub2(name)
        SV *    name
        CODE:
        /* Take a copy of the callback */
        if (keepSub == (SV*)NULL)
            /* First time, so create a new SV */
            keepSub = newSVsv(name);
        else
            /* Been here before, so overwrite */
            SvSetSV(keepSub, name);

    void
    CallSavedSub2()
        CODE:
        PUSHMARK(SP);
        call_sv(keepSub, G_DISCARD|G_NOARGS);

To avoid creating a new SV every time SaveSub2 is called, the function first checks to see if it has been called before. If not, then space for a new SV is allocated and the reference to the Perl subroutine, name is copied to the variable keepSub in one operation using newSVsv. Thereafter, whenever SaveSub2 is called the existing SV, keepSub, is overwritten with the new value using SvSetSV.

Using call_argv

Here is a Perl subroutine which prints whatever parameters are passed to it.

    sub PrintList
    {
        my(@list) = @_;

        foreach (@list) { print "$_\n" }
            }

and here is an example of call_argv which will call PrintList.

    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};

    static void
    call_PrintList()
    {
        dSP;

        call_argv("PrintList", G_DISCARD, words);
            }

Note that it is not necessary to call PUSHMARK in this instance. This is because call_argv will do it for you.

Using call_method

Consider the following Perl code

    {
        package Mine;

        sub new
        {
            my($type) = shift;
            bless [@_]
        }

        sub Display
        {
            my ($self, $index) = @_;
            print "$index: $$self[$index]\n";
        }

        sub PrintID
        {
            my($class) = @_;
            print "This is Class $class version 1.0\n";
        }
            }

It implements just a very simple class to manage an array. Apart from the constructor, new, it declares methods, one static and one virtual. The static method, PrintID, prints out simply the class name and a version number. The virtual method, Display, prints out a single element of the array. Here is an all Perl example of using it.

    $a = new Mine ('red', 'green', 'blue');
    $a->Display(1);
    PrintID Mine;

will print

    1: green
    This is Class Mine version 1.0

Calling a Perl method from C is fairly straightforward. The following things are required

  • a reference to the object for a virtual method or the name of the class for a static method.

  • the name of the method.

  • any other parameters specific to the method.

Here is a simple XSUB which illustrates the mechanics of calling both the PrintID and Display methods from C.

    void
    call_Method(ref, method, index)
        SV *    ref
        char *  method
        int             index
        CODE:
        PUSHMARK(SP);
        XPUSHs(ref);
        XPUSHs(sv_2mortal(newSViv(index)));
        PUTBACK;

        call_method(method, G_DISCARD);

    void
    call_PrintID(class, method)
        char *  class
        char *  method
        CODE:
        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(class, 0)));
        PUTBACK;

        call_method(method, G_DISCARD);

So the methods PrintID and Display can be invoked like this

    $a = new Mine ('red', 'green', 'blue');
    call_Method($a, 'Display', 1);
    call_PrintID('Mine', 'PrintID');

The only thing to note is that in both the static and virtual methods, the method name is not passed via the stack--it is used as the first parameter to call_method.

Using GIMME_V

Here is a trivial XSUB which prints the context in which it is currently executing.

    void
    PrintContext()
        CODE:
        I32 gimme = GIMME_V;
        if (gimme == G_VOID)
            printf ("Context is Void\n");
        else if (gimme == G_SCALAR)
            printf ("Context is Scalar\n");
        else
            printf ("Context is Array\n");

and here is some Perl to test it

    PrintContext;
    $a = PrintContext;
    @a = PrintContext;

The output from that will be

    Context is Void
    Context is Scalar
    Context is Array

Using Perl to dispose of temporaries

In the examples given to date, any temporaries created in the callback (i.e., parameters passed on the stack to the call_* function or values returned via the stack) have been freed by one of these methods

  • specifying the G_DISCARD flag with call_*.

  • explicitly disposed of using the ENTER/SAVETMPS - FREETMPS/LEAVE pairing.

There is another method which can be used, namely letting Perl do it for you automatically whenever it regains control after the callback has terminated. This is done by simply not using the

    ENTER;
    SAVETMPS;
    ...
    FREETMPS;
    LEAVE;

sequence in the callback (and not, of course, specifying the G_DISCARD flag).

If you are going to use this method you have to be aware of a possible memory leak which can arise under very specific circumstances. To explain these circumstances you need to know a bit about the flow of control between Perl and the callback routine.

The examples given at the start of the document (an error handler and an event driven program) are typical of the two main sorts of flow control that you are likely to encounter with callbacks. There is a very important distinction between them, so pay attention.

In the first example, an error handler, the flow of control could be as follows. You have created an interface to an external library. Control can reach the external library like this

    perl --> XSUB --> external library

Whilst control is in the library, an error condition occurs. You have previously set up a Perl callback to handle this situation, so it will get executed. Once the callback has finished, control will drop back to Perl again. Here is what the flow of control will be like in that situation

    perl --> XSUB --> external library
                      ...
                      error occurs
                      ...
                      external library --> call_* --> perl
                                                          |
    perl <-- XSUB <-- external library <-- call_* <----+

After processing of the error using call_* is completed, control reverts back to Perl more or less immediately.

In the diagram, the further right you go the more deeply nested the scope is. It is only when control is back with perl on the extreme left of the diagram that you will have dropped back to the enclosing scope and any temporaries you have left hanging around will be freed.

In the second example, an event driven program, the flow of control will be more like this

    perl --> XSUB --> event handler
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+
                      ...
                      event handler --> call_* --> perl
                                                       |
                      event handler <-- call_* <----+

In this case the flow of control can consist of only the repeated sequence

    event handler --> call_* --> perl

for practically the complete duration of the program. This means that control may never drop back to the surrounding scope in Perl at the extreme left.

So what is the big problem? Well, if you are expecting Perl to tidy up those temporaries for you, you might be in for a long wait. For Perl to dispose of your temporaries, control must drop back to the enclosing scope at some stage. In the event driven scenario that may never happen. This means that as time goes on, your program will create more and more temporaries, none of which will ever be freed. As each of these temporaries consumes some memory your program will eventually consume all the available memory in your system--kapow!

So here is the bottom line--if you are sure that control will revert back to the enclosing Perl scope fairly quickly after the end of your callback, then it isn't absolutely necessary to dispose explicitly of any temporaries you may have created. Mind you, if you are at all uncertain about what to do, it doesn't do any harm to tidy up anyway.

Strategies for storing Callback Context Information

Potentially one of the trickiest problems to overcome when designing a callback interface can be figuring out how to store the mapping between the C callback function and the Perl equivalent.

To help understand why this can be a real problem first consider how a callback is set up in an all C environment. Typically a C API will provide a function to register a callback. This will expect a pointer to a function as one of its parameters. Below is a call to a hypothetical function register_fatal which registers the C function to get called when a fatal error occurs.

    register_fatal(cb1);

The single parameter cb1 is a pointer to a function, so you must have defined cb1 in your code, say something like this

    static void
    cb1()
    {
        printf ("Fatal Error\n");
        exit(1);
    }

Now change that to call a Perl subroutine instead

    static SV * callback = (SV*)NULL;

    static void
    cb1()
    {
        dSP;

        PUSHMARK(SP);

        /* Call the Perl sub to process the callback */
        call_sv(callback, G_DISCARD);
            }

    void
    register_fatal(fn)
        SV *    fn
        CODE:
        /* Remember the Perl sub */
        if (callback == (SV*)NULL)
            callback = newSVsv(fn);
        else
            SvSetSV(callback, fn);

        /* register the callback with the external library */
        register_fatal(cb1);

where the Perl equivalent of register_fatal and the callback it registers, pcb1, might look like this

    # Register the sub pcb1
    register_fatal(\&pcb1);

    sub pcb1
    {
        die "I'm dying...\n";
    }

The mapping between the C callback and the Perl equivalent is stored in the global variable callback.

This will be adequate if you ever need to have only one callback registered at any time. An example could be an error handler like the code sketched out above. Remember though, repeated calls to register_fatal will replace the previously registered callback function with the new one.

Say for example you want to interface to a library which allows asynchronous file i/o. In this case you may be able to register a callback whenever a read operation has completed. To be of any use we want to be able to call separate Perl subroutines for each file that is opened. As it stands, the error handler example above would not be adequate as it allows only a single callback to be defined at any time. What we require is a means of storing the mapping between the opened file and the Perl subroutine we want to be called for that file.

Say the i/o library has a function asynch_read which associates a C function ProcessRead with a file handle fh--this assumes that it has also provided some routine to open the file and so obtain the file handle.

    asynch_read(fh, ProcessRead)

This may expect the C ProcessRead function of this form

    void
    ProcessRead(fh, buffer)
    int fh;
    char *      buffer;
    {
         ...
    }

To provide a Perl interface to this library we need to be able to map between the fh parameter and the Perl subroutine we want called. A hash is a convenient mechanism for storing this mapping. The code below shows a possible implementation

    static HV * Mapping = (HV*)NULL;

    void
    asynch_read(fh, callback)
        int     fh
        SV *    callback
        CODE:
        /* If the hash doesn't already exist, create it */
        if (Mapping == (HV*)NULL)
            Mapping = newHV();

        /* Save the fh -> callback mapping */
        hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);

        /* Register with the C Library */
        asynch_read(fh, asynch_read_if);

and asynch_read_if could look like this

    static void
    asynch_read_if(fh, buffer)
    int fh;
    char *      buffer;
    {
        dSP;
        SV ** sv;

        /* Get the callback associated with fh */
        sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
        if (sv == (SV**)NULL)
            croak("Internal error...\n");

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(fh)));
        XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
        PUTBACK;

        /* Call the Perl sub */
        call_sv(*sv, G_DISCARD);
            }

For completeness, here is asynch_close. This shows how to remove the entry from the hash Mapping.

    void
    asynch_close(fh)
        int     fh
        CODE:
        /* Remove the entry from the hash */
        (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);

        /* Now call the real asynch_close */
        asynch_close(fh);

So the Perl interface would look like this

    sub callback1
    {
        my($handle, $buffer) = @_;
    }

    # Register the Perl callback
    asynch_read($fh, \&callback1);

    asynch_close($fh);

The mapping between the C callback and Perl is stored in the global hash Mapping this time. Using a hash has the distinct advantage that it allows an unlimited number of callbacks to be registered.

What if the interface provided by the C callback doesn't contain a parameter which allows the file handle to Perl subroutine mapping? Say in the asynchronous i/o package, the callback function gets passed only the buffer parameter like this

    void
    ProcessRead(buffer)
    char *      buffer;
    {
        ...
    }

Without the file handle there is no straightforward way to map from the C callback to the Perl subroutine.

In this case a possible way around this problem is to predefine a series of C functions to act as the interface to Perl, thus

    #define MAX_CB              3
    #define NULL_HANDLE -1
    typedef void (*FnMap)();

    struct MapStruct {
        FnMap    Function;
        SV *     PerlSub;
        int      Handle;
      };

    static void  fn1();
    static void  fn2();
    static void  fn3();

    static struct MapStruct Map [MAX_CB] =
        {
            { fn1, NULL, NULL_HANDLE },
            { fn2, NULL, NULL_HANDLE },
            { fn3, NULL, NULL_HANDLE }
        };

    static void
    Pcb(index, buffer)
    int index;
    char * buffer;
    {
        dSP;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
        PUTBACK;

        /* Call the Perl sub */
        call_sv(Map[index].PerlSub, G_DISCARD);
            }

    static void
    fn1(buffer)
    char * buffer;
    {
        Pcb(0, buffer);
    }

    static void
    fn2(buffer)
    char * buffer;
    {
        Pcb(1, buffer);
    }

    static void
    fn3(buffer)
    char * buffer;
    {
        Pcb(2, buffer);
    }

    void
    array_asynch_read(fh, callback)
        int             fh
        SV *    callback
        CODE:
        int index;
        int null_index = MAX_CB;

        /* Find the same handle or an empty entry */
        for (index = 0; index < MAX_CB; ++index)
        {
            if (Map[index].Handle == fh)
                break;

            if (Map[index].Handle == NULL_HANDLE)
                null_index = index;
                    }

        if (index == MAX_CB && null_index == MAX_CB)
            croak ("Too many callback functions registered\n");

        if (index == MAX_CB)
            index = null_index;

        /* Save the file handle */
        Map[index].Handle = fh;

        /* Remember the Perl sub */
        if (Map[index].PerlSub == (SV*)NULL)
            Map[index].PerlSub = newSVsv(callback);
        else
            SvSetSV(Map[index].PerlSub, callback);

        asynch_read(fh, Map[index].Function);

    void
    array_asynch_close(fh)
        int     fh
        CODE:
        int index;

        /* Find the file handle */
        for (index = 0; index < MAX_CB; ++ index)
            if (Map[index].Handle == fh)
                break;

        if (index == MAX_CB)
            croak ("could not close fh %d\n", fh);

        Map[index].Handle = NULL_HANDLE;
        SvREFCNT_dec(Map[index].PerlSub);
        Map[index].PerlSub = (SV*)NULL;

        asynch_close(fh);

In this case the functions fn1, fn2, and fn3 are used to remember the Perl subroutine to be called. Each of the functions holds a separate hard-wired index which is used in the function Pcb to access the Map array and actually call the Perl subroutine.

There are some obvious disadvantages with this technique.

Firstly, the code is considerably more complex than with the previous example.

Secondly, there is a hard-wired limit (in this case 3) to the number of callbacks that can exist simultaneously. The only way to increase the limit is by modifying the code to add more functions and then recompiling. None the less, as long as the number of functions is chosen with some care, it is still a workable solution and in some cases is the only one available.

To summarize, here are a number of possible methods for you to consider for storing the mapping between C and the Perl callback

  1. Ignore the problem - Allow only 1 callback

    For a lot of situations, like interfacing to an error handler, this may be a perfectly adequate solution.

  2. Create a sequence of callbacks - hard wired limit

    If it is impossible to tell from the parameters passed back from the C callback what the context is, then you may need to create a sequence of C callback interface functions, and store pointers to each in an array.

  3. Use a parameter to map to the Perl callback

    A hash is an ideal mechanism to store the mapping between C and Perl.

Alternate Stack Manipulation

Although I have made use of only the POP* macros to access values returned from Perl subroutines, it is also possible to bypass these macros and read the stack using the ST macro (See the perlxs manpage for a full description of the ST macro).

Most of the time the POP* macros should be adequate, the main problem with them is that they force you to process the returned values in sequence. This may not be the most suitable way to process the values in some cases. What we want is to be able to access the stack in a random order. The ST macro as used when coding an XSUB is ideal for this purpose.

The code below is the example given in the section Returning a list of values recoded to use ST instead of POP*.

    static void
    call_AddSubtract2(a, b)
    int a;
    int b;
    {
        dSP;
        I32 ax;
        int count;

        ENTER;
        SAVETMPS;

        PUSHMARK(SP);
        XPUSHs(sv_2mortal(newSViv(a)));
        XPUSHs(sv_2mortal(newSViv(b)));
        PUTBACK;

        count = call_pv("AddSubtract", G_ARRAY);

        SPAGAIN;
        SP -= count;
        ax = (SP - PL_stack_base) + 1;

        if (count != 2)
            croak("Big trouble\n");

        printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
        printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));

        PUTBACK;
        FREETMPS;
        LEAVE;
            }

Notes

  1. Notice that it was necessary to define the variable ax. This is because the ST macro expects it to exist. If we were in an XSUB it would not be necessary to define ax as it is already defined for you.

  2. The code

            SPAGAIN;
        SP -= count;
        ax = (SP - PL_stack_base) + 1;

    sets the stack up so that we can use the ST macro.

  3. Unlike the original coding of this example, the returned values are not accessed in reverse order. So ST(0) refers to the first value returned by the Perl subroutine and ST(count-1) refers to the last.

Creating and calling an anonymous subroutine in C

As we've already shown, call_sv can be used to invoke an anonymous subroutine. However, our example showed a Perl script invoking an XSUB to perform this operation. Let's see how it can be done inside our C code:

 ...
 SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);

 ...
 call_sv(cvrv, G_VOID|G_NOARGS);

eval_pv is used to compile the anonymous subroutine, which will be the return value as well (read more about eval_pv in eval_pv in the perlapi manpage). Once this code reference is in hand, it can be mixed in with all the previous examples we've shown.

SEE ALSO

the perlxs manpage, the perlguts manpage, the perlembed manpage

AUTHOR

Paul Marquess

Special thanks to the following people who assisted in the creation of the document.

Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy and Larry Wall.

DATE

Version 1.3, 14th Apr 1997


perlclib - Internal replacements for standard C library functions

    • Conventions
    • File Operations
    • File Input and Output
    • File Positioning
    • Memory Management and String Handling
    • Character Class Tests
    • stdlib.h functions
    • Miscellaneous functions
  • SEE ALSO

NAME

perlclib - Internal replacements for standard C library functions

DESCRIPTION

One thing Perl porters should note is that perl doesn't tend to use that much of the C standard library internally; you'll see very little use of, for example, the ctype.h functions in there. This is because Perl tends to reimplement or abstract standard library functions, so that we know exactly how they're going to operate.

This is a reference card for people who are familiar with the C library and who want to do things the Perl way; to tell them which functions they ought to use instead of the more normal C functions.

Conventions

In the following tables:

t

is a type.

p

is a pointer.

n

is a number.

s

is a string.

sv, av, hv, etc. represent variables of their respective types.

File Operations

Instead of the stdio.h functions, you should use the Perl abstraction layer. Instead of FILE* types, you need to be handling PerlIO* types. Don't forget that with the new PerlIO layered I/O abstraction FILE* types may not even be available. See also the perlapio documentation for more information about the following functions:

    Instead Of:                 Use:
    stdin                       PerlIO_stdin()
    stdout                      PerlIO_stdout()
    stderr                      PerlIO_stderr()
    fopen(fn, mode)             PerlIO_open(fn, mode)
    freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Deprecated)
    fflush(stream)              PerlIO_flush(perlio)
    fclose(stream)              PerlIO_close(perlio)

File Input and Output

    Instead Of:                 Use:
    fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)
    [f]getc(stream)             PerlIO_getc(perlio)
    [f]putc(stream, n)          PerlIO_putc(perlio, n)
    ungetc(n, stream)           PerlIO_ungetc(perlio, n)

Note that the PerlIO equivalents of fread and fwrite are slightly different from their C library counterparts:

    fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
    fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)
    fputs(s, stream)            PerlIO_puts(perlio, s)

There is no equivalent to fgets; one should use sv_gets instead:

    fgets(s, n, stream)         sv_gets(sv, perlio, append)

File Positioning

    Instead Of:                 Use:
    feof(stream)                PerlIO_eof(perlio)
    fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
    rewind(stream)              PerlIO_rewind(perlio)
    fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
    fsetpos(stream, p)          PerlIO_setpos(perlio, sv)
    ferror(stream)              PerlIO_error(perlio)
    clearerr(stream)            PerlIO_clearerr(perlio)

Memory Management and String Handling

    Instead Of:                         Use:
    t* p = malloc(n)                    Newx(id, p, n, t)
    t* p = calloc(n, s)                 Newxz(id, p, n, t)
    p = realloc(p, n)                   Renew(p, n, t)
    memcpy(dst, src, n)                 Copy(src, dst, n, t)
    memmove(dst, src, n)                Move(src, dst, n, t)
    memcpy/*(struct foo *)              StructCopy(src, dst, t)
    memset(dst, 0, n * sizeof(t))       Zero(dst, n, t)
    memzero(dst, 0)                     Zero(dst, n, char)
    free(p)                             Safefree(p)
    strdup(p)                   savepv(p)
    strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
    strstr(big, little)         instr(big, little)
    strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
    strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)

Notice the different order of arguments to Copy and Move than used in memcpy and memmove.

Most of the time, though, you'll want to be dealing with SVs internally instead of raw char * strings:

    strlen(s)                   sv_len(sv)
    strcpy(dt, src)             sv_setpv(sv, s)
    strncpy(dt, src, n)         sv_setpvn(sv, s, n)
    strcat(dt, src)             sv_catpv(sv, s)
    strncat(dt, src)            sv_catpvn(sv, s)
    sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)

Note also the existence of sv_catpvf and sv_vcatpvfn, combining concatenation with formatting.

Sometimes instead of zeroing the allocated heap by using Newxz() you should consider "poisoning" the data. This means writing a bit pattern into it that should be illegal as pointers (and floating point numbers), and also hopefully surprising enough as integers, so that any code attempting to use the data without forethought will break sooner rather than later. Poisoning can be done using the Poison() macro, which has similar arguments as Zero():

    Poison(dst, n, t)

Character Class Tests

There are two types of character class tests that Perl implements: one type deals in chars and are thus not Unicode aware (and hence deprecated unless you know you should use them) and the other type deal in UVs and know about Unicode properties. In the following table, c is a char, and u is a Unicode codepoint.

    Instead Of:                 Use:            But better use:
    isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
    isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
    iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
    isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
    isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
    islower(c)                  isLOWER(c)      isLOWER_uni(u)
    isprint(c)                  isPRINT(c)      isPRINT_uni(u)
    ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
    isspace(c)                  isSPACE(c)      isSPACE_uni(u)
    isupper(c)                  isUPPER(c)      isUPPER_uni(u)
    isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)
    tolower(c)                  toLOWER(c)      toLOWER_uni(u)
    toupper(c)                  toUPPER(c)      toUPPER_uni(u)

stdlib.h functions

    Instead Of:                 Use:
    atof(s)                     Atof(s)
    atol(s)                     Atol(s)
    strtod(s, *p)               Nothing.  Just don't use it.
    strtol(s, *p, n)            Strtol(s, *p, n)
    strtoul(s, *p, n)           Strtoul(s, *p, n)

Notice also the grok_bin, grok_hex, and grok_oct functions in numeric.c for converting strings representing numbers in the respective bases into NVs.

In theory Strtol and Strtoul may not be defined if the machine perl is built on doesn't actually have strtol and strtoul. But as those 2 functions are part of the 1989 ANSI C spec we suspect you'll find them everywhere by now.

    int rand()                  double Drand01()
    srand(n)                    { seedDrand01((Rand_seed_t)n);
                                  PL_srand_called = TRUE; }

    exit(n)                     my_exit(n)
    system(s)                   Don't. Look at pp_system or use my_popen
    getenv(s)                   PerlEnv_getenv(s)
    setenv(s, val)              my_putenv(s, val)

Miscellaneous functions

You should not even want to use setjmp.h functions, but if you think you do, use the JMPENV stack in scope.h instead.

For signal/sigaction, use rsignal(signo, handler).

SEE ALSO

perlapi, perlapio, perlguts


perldebguts - Guts of Perl debugging

  • Debugger Internals
    • Writing Your Own Debugger
      • Environment Variables
      • Debugger internal variables
      • Debugger customization functions
  • Frame Listing Output Examples
  • Debugging regular expressions
    • Compile-time output
    • Types of nodes
    • Run-time output
  • Debugging Perl memory usage
    • Using $ENV{PERL_DEBUG_MSTATS}
  • SEE ALSO

NAME

perldebguts - Guts of Perl debugging

DESCRIPTION

This is not the perldebug(1) manpage, which tells you how to use the debugger. This manpage describes low-level details concerning the debugger's internals, which range from difficult to impossible to understand for anyone who isn't incredibly intimate with Perl's guts. Caveat lector.

Debugger Internals

Perl has special debugging hooks at compile-time and run-time used to create debugging environments. These hooks are not to be confused with the perl -Dxxx command described in the perlrun manpage, which is usable only if a special Perl is built per the instructions in the INSTALL podpage in the Perl source tree.

For example, whenever you call Perl's built-in caller function from the package DB, the arguments that the corresponding stack frame was called with are copied to the @DB::args array. These mechanisms are enabled by calling Perl with the -d switch. Specifically, the following additional features are enabled (cf. $^P in the perlvar manpage):

  • Perl inserts the contents of $ENV{PERL5DB} (or BEGIN {require 'perl5db.pl'} if not present) before the first line of your program.

  • Each array @{"_<$filename"} holds the lines of $filename for a file compiled by Perl. The same is also true for evaled strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34). Code assertions in regexes look like (re_eval 19).

    Values in this array are magical in numeric context: they compare equal to zero only if the line is not breakable.

  • Each hash %{"_<$filename"} contains breakpoints and actions keyed by line number. Individual entries (as opposed to the whole hash) are settable. Perl only cares about Boolean true here, although the values used by perl5db.pl have the form "$break_condition\0$action".

    The same holds for evaluated strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34) or (re_eval 19).

  • Each scalar ${"_<$filename"} contains "_<$filename". This is also the case for evaluated strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34) or (re_eval 19).

  • After each required file is compiled, but before it is executed, DB::postponed(*{"_<$filename"}) is called if the subroutine DB::postponed exists. Here, the $filename is the expanded name of the required file, as found in the values of %INC.

  • After each subroutine subname is compiled, the existence of $DB::postponed{subname} is checked. If this key exists, DB::postponed(subname) is called if the DB::postponed subroutine also exists.

  • A hash %DB::sub is maintained, whose keys are subroutine names and whose values have the form filename:startline-endline. filename has the form (eval 34) for subroutines defined inside evals, or (re_eval 19) for those within regex code assertions.

  • When the execution of your program reaches a point that can hold a breakpoint, the DB::DB() subroutine is called if any of the variables $DB::trace, $DB::single, or $DB::signal is true. These variables are not localizable. This feature is disabled when executing inside DB::DB(), including functions called from it unless $^D & (1<<30) is true.

  • When execution of the program reaches a subroutine call, a call to &DB::sub(args) is made instead, with $DB::sub holding the name of the called subroutine. (This doesn't happen if the subroutine was compiled in the DB package.)

Note that if &DB::sub needs external data for it to work, no subroutine call is possible without it. As an example, the standard debugger's &DB::sub depends on the $DB::deep variable (it defines how many levels of recursion deep into the debugger you can go before a mandatory break). If $DB::deep is not defined, subroutine calls are not possible, even though &DB::sub exists.

Writing Your Own Debugger

Environment Variables

The PERL5DB environment variable can be used to define a debugger. For example, the minimal "working" debugger (it actually doesn't do anything) consists of one line:

  sub DB::DB {}

It can easily be defined like this:

  $ PERL5DB="sub DB::DB {}" perl -d your-script

Another brief debugger, slightly more useful, can be created with only the line:

  sub DB::DB {print ++$i; scalar <STDIN>}

This debugger prints a number which increments for each statement encountered and waits for you to hit a newline before continuing to the next statement.

The following debugger is actually useful:

  {
    package DB;
    sub DB  {}
    sub sub {print ++$i, " $sub\n"; &$sub}
  }

It prints the sequence number of each subroutine call and the name of the called subroutine. Note that &DB::sub is being compiled into the package DB through the use of the package directive.

When it starts, the debugger reads your rc file (./.perldb or ~/.perldb under Unix), which can set important options. (A subroutine (&afterinit) can be defined here as well; it is executed after the debugger completes its own initialization.)

After the rc file is read, the debugger reads the PERLDB_OPTS environment variable and uses it to set debugger options. The contents of this variable are treated as if they were the argument of an o ... debugger command (q.v. in Options in the perldebug manpage).

Debugger internal variables In addition to the file and subroutine-related variables mentioned above, the debugger also maintains various magical internal variables.

  • @DB::dbline is an alias for @{"::_<current_file"}, which holds the lines of the currently-selected file (compiled by Perl), either explicitly chosen with the debugger's f command, or implicitly by flow of execution.

    Values in this array are magical in numeric context: they compare equal to zero only if the line is not breakable.

  • %DB::dbline, is an alias for %{"::_<current_file"}, which contains breakpoints and actions keyed by line number in the currently-selected file, either explicitly chosen with the debugger's f command, or implicitly by flow of execution.

    As previously noted, individual entries (as opposed to the whole hash) are settable. Perl only cares about Boolean true here, although the values used by perl5db.pl have the form "$break_condition\0$action".

Debugger customization functions

Some functions are provided to simplify customization.

  • See Options in the perldebug manpage for description of options parsed by DB::parse_options(string) parses debugger options; see pperldebug/Options for a description of options recognized.

  • DB::dump_trace(skip[,count]) skips the specified number of frames and returns a list containing information about the calling frames (all of them, if count is missing). Each entry is reference to a hash with keys context (either ., $, or @), sub (subroutine name, or info about eval), args (undef or a reference to an array), file, and line.

  • DB::print_trace(FH, skip[, count[, short]]) prints formatted info about caller frames. The last two functions may be convenient as arguments to <, << commands.

Note that any variables and functions that are not documented in this manpages (or in the perldebug manpage) are considered for internal use only, and as such are subject to change without notice.

Frame Listing Output Examples

The frame option can be used to control the output of frame information. For example, contrast this expression trace:

 $ perl -de 42
 Stack dump during die enabled outside of evals.
 Loading DB routines from perl5db.pl patch level 0.94
 Emacs support available.
 Enter h or `h h' for help.
 main::(-e:1):   0
   DB<1> sub foo { 14 }

   DB<2> sub bar { 3 }

   DB<3> t print foo() * bar()
    main::((eval 172):3):   print foo() + bar();
    main::foo((eval 168):2):
    main::bar((eval 170):2):
    42

with this one, once the option frame=2 has been set:

   DB<4> o f=2
                frame = '2'
   DB<5> t print foo() * bar()
    3:      foo() * bar()
    entering main::foo
     2:     sub foo { 14 };
    exited main::foo
    entering main::bar
     2:     sub bar { 3 };
    exited main::bar
    42

By way of demonstration, we present below a laborious listing resulting from setting your PERLDB_OPTS environment variable to the value f=n N, and running perl -d -V from the command line. Examples use various values of n are shown to give you a feel for the difference between settings. Long those it may be, this is not a complete listing, but only excerpts.

  1.   entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   entering Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
  entering Config::myconfig
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH
   entering Config::FETCH
  2.   entering main::BEGIN
   entering Config::BEGIN
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   exited Config::BEGIN
   Package lib/Config.pm.
   entering Config::TIEHASH
   exited Config::TIEHASH
   entering Exporter::import
    entering Exporter::export
    exited Exporter::export
   exited Exporter::import
  exited main::BEGIN
  entering Config::myconfig
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH
   exited Config::FETCH
   entering Config::FETCH
  3.   in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
  4.   in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  out $=main::BEGIN() from /dev/null:0
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
   in  $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
  5.   in  $=main::BEGIN() from /dev/null:0
   in  $=Config::BEGIN() from lib/Config.pm:2
    Package lib/Exporter.pm.
    Package lib/Carp.pm.
   out $=Config::BEGIN() from lib/Config.pm:0
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
   out $=Config::TIEHASH('Config') from lib/Config.pm:644
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
  out $=main::BEGIN() from /dev/null:0
  in  @=Config::myconfig() from /dev/null:0
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
   out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
  6.   in  $=CODE(0x15eca4)() from /dev/null:0
   in  $=CODE(0x182528)() from lib/Config.pm:2
    Package lib/Exporter.pm.
   out $=CODE(0x182528)() from lib/Config.pm:0
   scalar context return from CODE(0x182528): undef
   Package lib/Config.pm.
   in  $=Config::TIEHASH('Config') from lib/Config.pm:628
   out $=Config::TIEHASH('Config') from lib/Config.pm:628
   scalar context return from Config::TIEHASH:   empty hash
   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/Exporter.pm:171
    scalar context return from Exporter::export: ''
   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
   scalar context return from Exporter::import: ''

In all cases shown above, the line indentation shows the call tree. If bit 2 of frame is set, a line is printed on exit from a subroutine as well. If bit 4 is set, the arguments are printed along with the caller info. If bit 8 is set, the arguments are printed even if they are tied or references. If bit 16 is set, the return value is printed, too.

When a package is compiled, a line like this

    Package lib/Carp.pm.

is printed with proper indentation.

Debugging regular expressions

There are two ways to enable debugging output for regular expressions.

If your perl is compiled with -DDEBUGGING, you may use the -Dr flag on the command line.

Otherwise, one can use re 'debug', which has effects at compile time and run time. It is not lexically scoped.

Compile-time output

The debugging output at compile time looks like this:

  Compiling REx `[bc]d(ef*g)+h[ij]k$'
  size 45 Got 364 bytes for offset annotations.
  first at 1
  rarest char g at 0
  rarest char d at 0
     1: ANYOF[bc](12)
    12: EXACT <d>(14)
    14: CURLYX[0] {1,32767}(28)
    16:   OPEN1(18)
    18:     EXACT <e>(20)
    20:     STAR(23)
    21:       EXACT <f>(0)
    23:     EXACT <g>(25)
    25:   CLOSE1(27)
    27:   WHILEM[1/1](0)
    28: NOTHING(29)
    29: EXACT <h>(31)
    31: ANYOF[ij](42)
    42: EXACT <k>(44)
    44: EOL(45)
    45: END(0)
  anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
        stclass `ANYOF[bc]' minlen 7
  Offsets: [45]
        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
  Omitting $` $& $' support.

The first line shows the pre-compiled form of the regex. The second shows the size of the compiled form (in arbitrary units, usually 4-byte words) and the total number of bytes allocated for the offset/length table, usually 4+size*8. The next line shows the label id of the first node that does a match.

The

  anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
        stclass `ANYOF[bc]' minlen 7

line (split into two lines above) contains optimizer information. In the example shown, the optimizer found that the match should contain a substring de at offset 1, plus substring gh at some offset between 3 and infinity. Moreover, when checking for these substrings (to abandon impossible matches quickly), Perl will check for the substring gh before checking for the substring de. The optimizer may also use the knowledge that the match starts (at the first id) with a character class, and no string shorter than 7 characters can possibly match.

The fields of interest which may appear in this line are

anchored STRING at POS
floating STRING at POS1..POS2

See above.

matching floating/anchored

Which substring to check first.

minlen

The minimal length of the match.

stclass TYPE

Type of first matching node.

noscan

Don't scan for the found substrings.

isall

Means that the optimizer information is all that the regular expression contains, and thus one does not need to enter the regex engine at all.

GPOS

Set if the pattern contains \G.

plus

Set if the pattern starts with a repeated char (as in x+y).

implicit

Set if the pattern starts with .*.

with eval

Set if the pattern contain eval-groups, such as (?{ code }) and (??{ code }).

anchored(TYPE)

If the pattern may match only at a handful of places, (with TYPE being BOL, MBOL, or GPOS. See the table below.

If a substring is known to match at end-of-line only, it may be followed by $, as in floating `k'$.

The optimizer-specific information is used to avoid entering (a slow) regex engine on strings that will not definitely match. If the isall flag is set, a call to the regex engine may be avoided even when the optimizer found an appropriate place for the match.

Above the optimizer section is the list of nodes of the compiled form of the regex. Each line has format

id: TYPE OPTIONAL-INFO (next-id)

Types of nodes

Here are the possible types, with short descriptions:

    # TYPE arg-description [num-args] [longjump-len] DESCRIPTION

    # Exit points
    END         no      End of program.
    SUCCEED     no      Return from a subroutine, basically.
    # Anchors:
    BOL         no      Match "" at beginning of line.
    MBOL        no      Same, assuming multiline.
    SBOL        no      Same, assuming singleline.
    EOS         no      Match "" at end of string.
    EOL         no      Match "" at end of line.
    MEOL        no      Same, assuming multiline.
    SEOL        no      Same, assuming singleline.
    BOUND       no      Match "" at any word boundary
    BOUNDL      no      Match "" at any word boundary
    NBOUND      no      Match "" at any word non-boundary
    NBOUNDL     no      Match "" at any word non-boundary
    GPOS        no      Matches where last m//g left off.
    # [Special] alternatives
    ANY         no      Match any one character (except newline).
    SANY        no      Match any one character.
    ANYOF       sv      Match character in (or not in) this class.
    ALNUM       no      Match any alphanumeric character
    ALNUML      no      Match any alphanumeric char in locale
    NALNUM      no      Match any non-alphanumeric character
    NALNUML     no      Match any non-alphanumeric char in locale
    SPACE       no      Match any whitespace character
    SPACEL      no      Match any whitespace char in locale
    NSPACE      no      Match any non-whitespace character
    NSPACEL     no      Match any non-whitespace char in locale
    DIGIT       no      Match any numeric character
    NDIGIT      no      Match any non-numeric character
    # BRANCH    The set of branches constituting a single choice are hooked
    #           together with their "next" pointers, since precedence prevents
    #           anything being concatenated to any individual branch.  The
    #           "next" pointer of the last BRANCH in a choice points to the
    #           thing following the whole choice.  This is also where the
    #           final "next" pointer of each individual branch points; each
    #           branch starts with the operand node of a BRANCH node.
    #
    BRANCH      node    Match this alternative, or the next...

    # BACK      Normal "next" pointers all implicitly point forward; BACK
    #           exists to make loop structures possible.
    # not used
    BACK        no      Match "", "next" ptr points backward.

    # Literals
    EXACT       sv      Match this string (preceded by length).
    EXACTF      sv      Match this string, folded (prec. by length).
    EXACTFL     sv      Match this string, folded in locale (w/len).
    # Do nothing
    NOTHING     no      Match empty string.
    # A variant of above which delimits a group, thus stops optimizations
    TAIL        no      Match empty string. Can jump here from outside.
    # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
    #           BRANCH structures using BACK.  Simple cases (one character
    #           per match) are implemented with STAR and PLUS for speed
    #           and to minimize recursive plunges.
    #
    STAR        node    Match this (simple) thing 0 or more times.
    PLUS        node    Match this (simple) thing 1 or more times.
    CURLY       sv 2    Match this simple thing {n,m} times.
    CURLYN      no 2    Match next-after-this simple thing
    #                   {n,m} times, set parens.
    CURLYM      no 2    Match this medium-complex thing {n,m} times.
    CURLYX      sv 2    Match this complex thing {n,m} times.

    # This terminator creates a loop structure for CURLYX
    WHILEM      no      Do curly processing and see if rest matches.
    # OPEN,CLOSE,GROUPP ...are numbered at compile time.
    OPEN        num 1   Mark this point in input as start of #n.
    CLOSE       num 1   Analogous to OPEN.
    REF         num 1   Match some already matched string
    REFF        num 1   Match already matched string, folded
    REFFL       num 1   Match already matched string, folded in loc.
    # grouping assertions
    IFMATCH     off 1 2 Succeeds if the following matches.
    UNLESSM     off 1 2 Fails if the following matches.
    SUSPEND     off 1 1 "Independent" sub-regex.
    IFTHEN      off 1 1 Switch, should be preceded by switcher .
    GROUPP      num 1   Whether the group matched.
    # Support for long regex
    LONGJMP     off 1 1 Jump far away.
    BRANCHJ     off 1 1 BRANCH with long offset.
    # The heavy worker
    EVAL        evl 1   Execute some Perl code.
    # Modifiers
    MINMOD      no      Next operator is not greedy.
    LOGICAL     no      Next opcode should set the flag only.
    # This is not used yet
    RENUM       off 1 1 Group with independently numbered parens.
    # This is not really a node, but an optimized away piece of a "long" node.
    # To simplify debugging output, we mark it as if it were a node
    OPTIMIZED   off     Placeholder for dump.

Following the optimizer information is a dump of the offset/length table, here split across several lines:

  Offsets: [45]
        1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
        0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
        11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
        0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]

The first line here indicates that the offset/length table contains 45 entries. Each entry is a pair of integers, denoted by offset[length]. Entries are numbered starting with 1, so entry #1 here is 1[4] and entry #12 is 5[1]. 1[4] indicates that the node labeled 1: (the 1: ANYOF[bc]) begins at character position 1 in the pre-compiled form of the regex, and has a length of 4 characters. 5[1] in position 12 indicates that the node labeled 12: (the 12: EXACT <d>) begins at character position 5 in the pre-compiled form of the regex, and has a length of 1 character. 12[1] in position 14 indicates that the node labeled 14: (the 14: CURLYX[0] {1,32767}) begins at character position 12 in the pre-compiled form of the regex, and has a length of 1 character---that is, it corresponds to the + symbol in the precompiled regex.

0[0] items indicate that there is no corresponding node.

Run-time output

First of all, when doing a match, one may get no run-time output even if debugging is enabled. This means that the regex engine was never entered and that all of the job was therefore done by the optimizer.

If the regex engine was entered, the output may look like this:

  Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
    Setting an EVAL scope, savestack=3
     2 <ab> <cdefg__gh_>    |  1: ANYOF
     3 <abc> <defg__gh_>    | 11: EXACT <d>
     4 <abcd> <efg__gh_>    | 13: CURLYX {1,32767}
     4 <abcd> <efg__gh_>    | 26:   WHILEM
                                0 out of 1..32767  cc=effff31c
     4 <abcd> <efg__gh_>    | 15:     OPEN1
     4 <abcd> <efg__gh_>    | 17:     EXACT <e>
     5 <abcde> <fg__gh_>    | 19:     STAR
                             EXACT <f> can match 1 times out of 32767...
    Setting an EVAL scope, savestack=3
     6 <bcdef> <g__gh__>    | 22:       EXACT <g>
     7 <bcdefg> <__gh__>    | 24:       CLOSE1
     7 <bcdefg> <__gh__>    | 26:       WHILEM
                                    1 out of 1..32767  cc=effff31c
    Setting an EVAL scope, savestack=12
     7 <bcdefg> <__gh__>    | 15:         OPEN1
     7 <bcdefg> <__gh__>    | 17:         EXACT <e>
       restoring \1 to 4(4)..7
                                    failed, try continuation...
     7 <bcdefg> <__gh__>    | 27:         NOTHING
     7 <bcdefg> <__gh__>    | 28:         EXACT <h>
                                    failed...
                                failed...

The most significant information in the output is about the particular node of the compiled regex that is currently being tested against the target string. The format of these lines is

STRING-OFFSET <PRE-STRING> <POST-STRING> |ID: TYPE

The TYPE info is indented with respect to the backtracking level. Other incidental information appears interspersed within.

Debugging Perl memory usage

Perl is a profligate wastrel when it comes to memory use. There is a saying that to estimate memory usage of Perl, assume a reasonable algorithm for memory allocation, multiply that estimate by 10, and while you still may miss the mark, at least you won't be quite so astonished. This is not absolutely true, but may provide a good grasp of what happens.

Assume that an integer cannot take less than 20 bytes of memory, a float cannot take less than 24 bytes, a string cannot take less than 32 bytes (all these examples assume 32-bit architectures, the result are quite a bit worse on 64-bit architectures). If a variable is accessed in two of three different ways (which require an integer, a float, or a string), the memory footprint may increase yet another 20 bytes. A sloppy malloc(3) implementation can inflate these numbers dramatically.

On the opposite end of the scale, a declaration like

  sub foo;

may take up to 500 bytes of memory, depending on which release of Perl you're running.

Anecdotal estimates of source-to-compiled code bloat suggest an eightfold increase. This means that the compiled form of reasonable (normally commented, properly indented etc.) code will take about eight times more space in memory than the code took on disk.

The -DL command-line switch is obsolete since circa Perl 5.6.0 (it was available only if Perl was built with -DDEBUGGING). The switch was used to track Perl's memory allocations and possible memory leaks. These days the use of malloc debugging tools like Purify or valgrind is suggested instead.

One way to find out how much memory is being used by Perl data structures is to install the Devel::Size module from CPAN: it gives you the minimum number of bytes required to store a particular data structure. Please be mindful of the difference between the size() and total_size().

If Perl has been compiled using Perl's malloc you can analyze Perl memory usage by setting the $ENV{PERL_DEBUG_MSTATS}.

Using $ENV{PERL_DEBUG_MSTATS}

If your perl is using Perl's malloc() and was compiled with the necessary switches (this is the default), then it will print memory usage statistics after compiling your code when $ENV{PERL_DEBUG_MSTATS} > 1, and before termination of the program when < $ENV{PERL_DEBUG_MSTATS} = 1 >>. The report format is similar to the following example:

  $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
  Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
     14216 free:   130   117    28     7     9   0   2     2   1 0 0
                437    61    36     0     5
     60924 used:   125   137   161    55     7   8   6    16   2 0 1
                 74   109   304    84    20
  Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
  Memory allocation statistics after execution:   (buckets 4(4)..8188(8192)
     30888 free:   245    78    85    13     6   2   1     3   2 0 1
                315   162    39    42    11
    175816 used:   265   176  1112   111    26  22  11    27   2 1 1
                196   178  1066   798    39
  Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.

It is possible to ask for such a statistic at arbitrary points in your execution using the mstat() function out of the standard Devel::Peek module.

Here is some explanation of that format:

buckets SMALLEST(APPROX)..GREATEST(APPROX)

Perl's malloc() uses bucketed allocations. Every request is rounded up to the closest bucket size available, and a bucket is taken from the pool of buckets of that size.

The line above describes the limits of buckets currently in use. Each bucket has two sizes: memory footprint and the maximal size of user data that can fit into this bucket. Suppose in the above example that the smallest bucket were size 4. The biggest bucket would have usable size 8188, and the memory footprint would be 8192.

In a Perl built for debugging, some buckets may have negative usable size. This means that these buckets cannot (and will not) be used. For larger buckets, the memory footprint may be one page greater than a power of 2. If so, case the corresponding power of two is printed in the APPROX field above.

Free/Used

The 1 or 2 rows of numbers following that correspond to the number of buckets of each size between SMALLEST and GREATEST. In the first row, the sizes (memory footprints) of buckets are powers of two--or possibly one page greater. In the second row, if present, the memory footprints of the buckets are between the memory footprints of two buckets "above".

For example, suppose under the previous example, the memory footprints were

     free:    8     16    32    64    128  256 512 1024 2048 4096 8192
           4     12    24    48    80

With non-DEBUGGING perl, the buckets starting from 128 have a 4-byte overhead, and thus an 8192-long bucket may take up to 8188-byte allocations.

Total sbrk(): SBRKed/SBRKs:CONTINUOUS

The first two fields give the total amount of memory perl sbrk(2)ed (ess-broken? :-) and number of sbrk(2)s used. The third number is what perl thinks about continuity of returned chunks. So long as this number is positive, malloc() will assume that it is probable that sbrk(2) will provide continuous memory.

Memory allocated by external libraries is not counted.

pad: 0

The amount of sbrk(2)ed memory needed to keep buckets aligned.

heads: 2192

Although memory overhead of bigger buckets is kept inside the bucket, for smaller buckets, it is kept in separate areas. This field gives the total size of these areas.

chain: 0

malloc() may want to subdivide a bigger bucket into smaller buckets. If only a part of the deceased bucket is left unsubdivided, the rest is kept as an element of a linked list. This field gives the total size of these chunks.

tail: 6144

To minimize the number of sbrk(2)s, malloc() asks for more memory. This field gives the size of the yet unused part, which is sbrk(2)ed, but never touched.

SEE ALSO

the perldebug manpage, the perlguts manpage, the perlrun manpage the re manpage, and the Devel::DProf manpage.


perlembed - how to embed perl in your C program

    • PREAMBLE
    • ROADMAP
    • Compiling your C program
    • Adding a Perl interpreter to your C program
    • Calling a Perl subroutine from your C program
    • Evaluating a Perl statement from your C program
    • Performing Perl pattern matches and substitutions from your C program
    • Fiddling with the Perl stack from your C program
    • Maintaining a persistent interpreter
    • Execution of END blocks
    • Maintaining multiple interpreter instances
    • Using Perl modules, which themselves use C libraries, from your C program
  • Embedding Perl under Win32
  • Hiding Perl_
  • MORAL
  • AUTHOR
  • COPYRIGHT

NAME

perlembed - how to embed perl in your C program

DESCRIPTION

PREAMBLE

Do you want to:

Use C from Perl?

Read the perlxstut manpage, the perlxs manpage, h2xs, the perlguts manpage, and the perlapi manpage.

Use a Unix program from Perl?

Read about back-quotes and about system and exec in the perlfunc manpage.

Use Perl from Perl?

Read about do in the perlfunc manpage and eval in the perlfunc manpage and require in the perlfunc manpage and use in the perlfunc manpage.

Use C from C?

Rethink your design.

Use Perl from C?

Read on...

ROADMAP

  • Compiling your C program

  • Adding a Perl interpreter to your C program

  • Calling a Perl subroutine from your C program

  • Evaluating a Perl statement from your C program

  • Performing Perl pattern matches and substitutions from your C program

  • Fiddling with the Perl stack from your C program

  • Maintaining a persistent interpreter

  • Maintaining multiple interpreter instances

  • Using Perl modules, which themselves use C libraries, from your C program

  • Embedding Perl under Win32

Compiling your C program

If you have trouble compiling the scripts in this documentation, you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)

Also, every C program that uses Perl must link in the perl library. What's that, you ask? Perl is itself written in C; the perl library is the collection of compiled C programs that were used to create your perl executable (/usr/bin/perl or equivalent). (Corollary: you can't use Perl from your C program unless Perl has been compiled on your machine, or installed properly--that's why you shouldn't blithely copy Perl executables from machine to machine without also copying the lib directory.)

When you use Perl from C, your C program will--usually--allocate, "run", and deallocate a PerlInterpreter object, which is defined by the perl library.

If your copy of Perl is recent enough to contain this documentation (version 5.002 or later), then the perl library (and EXTERN.h and perl.h, which you'll also need) will reside in a directory that looks like this:

    /usr/local/lib/perl5/your_architecture_here/CORE

or perhaps just

    /usr/local/lib/perl5/CORE

or maybe something like

    /usr/opt/perl5/CORE

Execute this statement for a hint about where to find CORE:

    perl -MConfig -e 'print $Config{archlib}'

Here's how you'd compile the example in the next section, Adding a Perl interpreter to your C program, on my Linux box:

    % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
    -I/usr/local/lib/perl5/i586-linux/5.003/CORE
    -L/usr/local/lib/perl5/i586-linux/5.003/CORE
    -o interp interp.c -lperl -lm

(That's all one line.) On my DEC Alpha running old 5.003_05, the incantation is a bit different:

    % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
    -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
    -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
    -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm

How can you figure out what to add? Assuming your Perl is post-5.001, execute a perl -V command and pay special attention to the "cc" and "ccflags" information.

You'll have to choose the appropriate compiler (cc, gcc, et al.) for your machine: perl -MConfig -e 'print $Config{cc}' will tell you what to use.

You'll also have to choose the appropriate library directory (/usr/local/lib/...) for your machine. If your compiler complains that certain functions are undefined, or that it can't locate -lperl, then you need to change the path following the -L. If it complains that it can't find EXTERN.h and perl.h, you need to change the path following the -I.

You may have to add extra libraries as well. Which ones? Perhaps those printed by

   perl -MConfig -e 'print $Config{libs}'

Provided your perl binary was properly configured and installed the ExtUtils::Embed module will determine all of this information for you:

   % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

If the ExtUtils::Embed module isn't part of your Perl distribution, you can retrieve it from http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/ (If this documentation came from your Perl distribution, then you're running 5.004 or better and you already have it.)

The ExtUtils::Embed kit on CPAN also contains all source code for the examples in this document, tests, additional examples and other information you may find useful.

Adding a Perl interpreter to your C program

In a sense, perl (the C program) is a good example of embedding Perl (the language), so I'll demonstrate embedding with miniperlmain.c, included in the source distribution. Here's a bastardized, nonportable version of miniperlmain.c containing the essentials of embedding:

    #include <EXTERN.h>               /* from the Perl distribution     */
    #include <perl.h>                 /* from the Perl distribution     */

    static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/

    int main(int argc, char **argv, char **env)
    {
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
        perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
        perl_run(my_perl);
        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
    }

Notice that we don't use the env pointer. Normally handed to perl_parse as its final argument, env here is replaced by NULL, which means that the current environment will be used. The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up of the C runtime environment necessary to run Perl interpreters; since PERL_SYS_INIT3() may change env, it may be more appropriate to provide env as an argument to perl_parse().

Now compile this program (I'll call it interp.c) into an executable:

    % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

After a successful compilation, you'll be able to use interp just like perl itself:

    % interp
    print "Pretty Good Perl \n";
    print "10890 - 9801 is ", 10890 - 9801;
    <CTRL-D>
    Pretty Good Perl
    10890 - 9801 is 1089

or

    % interp -e 'printf("%x", 3735928559)'
    deadbeef

You can also read and execute Perl statements from a file while in the midst of your C program, by placing the filename in argv[1] before calling perl_run.

Calling a Perl subroutine from your C program

To call individual Perl subroutines, you can use any of the call_* functions documented in the perlcall manpage. In this example we'll use call_argv.

That's shown below, in a program I'll call showtime.c.

    #include <EXTERN.h>
    #include <perl.h>

    static PerlInterpreter *my_perl;

    int main(int argc, char **argv, char **env)
    {
        char *args[] = { NULL };
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);

        perl_parse(my_perl, NULL, argc, argv, NULL);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;

        /*** skipping perl_run() ***/
        call_argv("showtime", G_DISCARD | G_NOARGS, args);

        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
            }

where showtime is a Perl subroutine that takes no arguments (that's the G_NOARGS) and for which I'll ignore the return value (that's the G_DISCARD). Those flags, and others, are discussed in the perlcall manpage.

I'll define the showtime subroutine in a file called showtime.pl:

    print "I shan't be printed.";

    sub showtime {
        print time;
    }

Simple enough. Now compile and run:

    % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
    % showtime showtime.pl
    818284590

yielding the number of seconds that elapsed between January 1, 1970 (the beginning of the Unix epoch), and the moment I began writing this sentence.

In this particular case we don't have to call perl_run, as we set the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in perl_destruct.

If you want to pass arguments to the Perl subroutine, you can add strings to the NULL-terminated args list passed to call_argv. For other data types, or to examine return values, you'll need to manipulate the Perl stack. That's demonstrated in Fiddling with the Perl stack from your C program.

Evaluating a Perl statement from your C program

Perl provides two API functions to evaluate pieces of Perl code. These are eval_sv in the perlapi manpage and eval_pv in the perlapi manpage.

Arguably, these are the only routines you'll ever need to execute snippets of Perl code from within your C program. Your code can be as long as you wish; it can contain multiple statements; it can employ use in the perlfunc manpage, require in the perlfunc manpage, and do in the perlfunc manpage to include external Perl files.

eval_pv lets us evaluate individual Perl strings, and then extract variables for coercion into C types. The following program, string.c, executes three Perl strings, extracting an int from the first, a float from the second, and a char * from the third.

   #include <EXTERN.h>
   #include <perl.h>

   static PerlInterpreter *my_perl;

   main (int argc, char **argv, char **env)
   {
       STRLEN n_a;
       char *embedding[] = { "", "-e", "0" };

       PERL_SYS_INIT3(&argc,&argv,&env);
       my_perl = perl_alloc();
       perl_construct( my_perl );

       perl_parse(my_perl, NULL, 3, embedding, NULL);
       PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
       perl_run(my_perl);

       /** Treat $a as an integer **/
       eval_pv("$a = 3; $a **= 2", TRUE);
       printf("a = %d\n", SvIV(get_sv("a", FALSE)));

       /** Treat $a as a float **/
       eval_pv("$a = 3.14; $a **= 2", TRUE);
       printf("a = %f\n", SvNV(get_sv("a", FALSE)));

       /** Treat $a as a string **/
       eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
       printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));

       perl_destruct(my_perl);
       perl_free(my_perl);
       PERL_SYS_TERM();
          }

All of those strange functions with sv in their names help convert Perl scalars to C types. They're described in the perlguts manpage and the perlapi manpage.

If you compile and run string.c, you'll see the results of using SvIV() to create an int, SvNV() to create a float, and SvPV() to create a string:

   a = 9
   a = 9.859600
   a = Just Another Perl Hacker

In the example above, we've created a global variable to temporarily store the computed value of our eval'd expression. It is also possible and in most cases a better strategy to fetch the return value from eval_pv() instead. Example:

   ...
   STRLEN n_a;
   SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
   printf("%s\n", SvPV(val,n_a));
   ...

This way, we avoid namespace pollution by not creating global variables and we've simplified our code as well.

Performing Perl pattern matches and substitutions from your C program

The eval_sv() function lets us evaluate strings of Perl code, so we can define some functions that use it to "specialize" in matches and substitutions: match(), substitute(), and matches().

   I32 match(SV *string, char *pattern);

Given a string and a pattern (e.g., m/clasp/ or /\b\w*\b/, which in your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if the string matches the pattern and 0 otherwise.

   int substitute(SV **string, char *pattern);

Given a pointer to an SV and an =~ operation (e.g., s/bob/robert/g or tr[A-Z][a-z]), substitute() modifies the string within the SV as according to the operation, returning the number of substitutions made.

   int matches(SV *string, char *pattern, AV **matches);

Given an SV, a pattern, and a pointer to an empty AV, matches() evaluates $string =~ $pattern in a list context, and fills in matches with the array elements, returning the number of matches found.

Here's a sample program, match.c, that uses all three (long lines have been wrapped here):

 #include <EXTERN.h>
 #include <perl.h>

 static PerlInterpreter *my_perl;

 /** my_eval_sv(code, error_check)
 ** kinda like eval_sv(),
 ** but we pop the return value off the stack
 **/
 SV* my_eval_sv(SV *sv, I32 croak_on_error)
 {
     dSP;
     SV* retval;
     STRLEN n_a;

     PUSHMARK(SP);
     eval_sv(sv, G_SCALAR);

     SPAGAIN;
     retval = POPs;
     PUTBACK;

     if (croak_on_error && SvTRUE(ERRSV))
        croak(SvPVx(ERRSV, n_a));

     return retval;
      }

 /** match(string, pattern)
 **
 ** Used for matches in a scalar context.
 **
 ** Returns 1 if the match was successful; 0 otherwise.
 **/

 I32 match(SV *string, char *pattern)
 {
     SV *command = NEWSV(1099, 0), *retval;
     STRLEN n_a;

     sv_setpvf(command, "my $string = '%s'; $string =~ %s",
              SvPV(string,n_a), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     return SvIV(retval);
      }

 /** substitute(string, pattern)
 **
 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
 **
 ** Returns the number of successful matches, and
 ** modifies the input string if there were any.
 **/
 I32 substitute(SV **string, char *pattern)
 {
     SV *command = NEWSV(1099, 0), *retval;
     STRLEN n_a;

     sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
              SvPV(*string,n_a), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     *string = get_sv("string", FALSE);
     return SvIV(retval);
      }

 /** matches(string, pattern, matches)
 **
 ** Used for matches in a list context.
 **
 ** Returns the number of matches,
 ** and fills in **matches with the matching substrings
 **/
 I32 matches(SV *string, char *pattern, AV **match_list)
 {
     SV *command = NEWSV(1099, 0);
     I32 num_matches;
     STRLEN n_a;

     sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
              SvPV(string,n_a), pattern);

     my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     *match_list = get_av("array", FALSE);
     num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/

     return num_matches;
      }

 main (int argc, char **argv, char **env)
 {
     char *embedding[] = { "", "-e", "0" };
     AV *match_list;
     I32 num_matches, i;
     SV *text;
     STRLEN n_a;

     PERL_SYS_INIT3(&argc,&argv,&env);
     my_perl = perl_alloc();
     perl_construct(my_perl);
     perl_parse(my_perl, NULL, 3, embedding, NULL);
     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;

     text = NEWSV(1099,0);
     sv_setpv(text, "When he is at a convenience store and the "
        "bill comes to some amount like 76 cents, Maynard is "
        "aware that there is something he *should* do, something "
        "that will enable him to get back a quarter, but he has "
        "no idea *what*.  He fumbles through his red squeezey "
        "changepurse and gives the boy three extra pennies with "
        "his dollar, hoping that he might luck into the correct "
        "amount.  The boy gives him back two of his own pennies "
        "and then the big shiny quarter that is his prize. "
        "-RICHH");

     if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
        printf("match: Text contains the word 'quarter'.\n\n");
     else
        printf("match: Text doesn't contain the word 'quarter'.\n\n");
     if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
        printf("match: Text contains the word 'eighth'.\n\n");
     else
        printf("match: Text doesn't contain the word 'eighth'.\n\n");
     /** Match all occurrences of /wi../ **/
     num_matches = matches(text, "m/(wi..)/g", &match_list);
     printf("matches: m/(wi..)/g found %d matches...\n", num_matches);

     for (i = 0; i < num_matches; i++)
        printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
     printf("\n");

     /** Remove all vowels from text **/
     num_matches = substitute(&text, "s/[aeiou]//gi");
     if (num_matches) {
        printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
               num_matches);
        printf("Now text is: %s\n\n", SvPV(text,n_a));
     }

     /** Attempt a substitution **/
     if (!substitute(&text, "s/Perl/C/")) {
        printf("substitute: s/Perl/C...No substitution made.\n\n");
     }

     SvREFCNT_dec(text);
     PL_perl_destruct_level = 1;
     perl_destruct(my_perl);
     perl_free(my_perl);
     PERL_SYS_TERM();
      }

which produces the output (again, long lines have been wrapped here)

   match: Text contains the word 'quarter'.
   match: Text doesn't contain the word 'eighth'.
   matches: m/(wi..)/g found 2 matches...
   match: will
   match: with
   substitute: s/[aeiou]//gi...139 substitutions made.
   Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
   Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
   qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd gvs th by
   thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt.  Th by gvs
   hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
   substitute: s/Perl/C...No substitution made.

Fiddling with the Perl stack from your C program

When trying to explain stacks, most computer science textbooks mumble something about spring-loaded columns of cafeteria plates: the last thing you pushed on the stack is the first thing you pop off. That'll do for our purposes: your C program will push some arguments onto "the Perl stack", shut its eyes while some magic happens, and then pop the results--the return value of your Perl subroutine--off the stack.

First you'll need to know how to convert between C types and Perl types, with newSViv() and sv_setnv() and newAV() and all their friends. They're described in the perlguts manpage and the perlapi manpage.

Then you'll need to know how to manipulate the Perl stack. That's described in the perlcall manpage.

Once you've understood those, embedding Perl in C is easy.

Because C has no builtin function for integer exponentiation, let's make Perl's ** operator available to it (this is less useful than it sounds, because Perl implements ** with C's pow() function). First I'll create a stub exponentiation function in power.pl:

    sub expo {
        my ($a, $b) = @_;
        return $a ** $b;
    }

Now I'll create a C program, power.c, with a function PerlPower() that contains all the perlguts necessary to push the two arguments into expo() and to pop the return value out. Take a deep breath...

    #include <EXTERN.h>
    #include <perl.h>

    static PerlInterpreter *my_perl;

    static void
    PerlPower(int a, int b)
    {
      dSP;                            /* initialize stack pointer      */
      ENTER;                          /* everything created after here */
      SAVETMPS;                       /* ...is a temporary variable.   */
      PUSHMARK(SP);                   /* remember the stack pointer    */
      XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
      XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
      PUTBACK;                      /* make local stack pointer global */
      call_pv("expo", G_SCALAR);      /* call the function             */
      SPAGAIN;                        /* refresh stack pointer         */
                                    /* pop the return value from stack */
      printf ("%d to the %dth power is %d.\n", a, b, POPi);
      PUTBACK;
      FREETMPS;                       /* free that return value        */
      LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
    }

    int main (int argc, char **argv, char **env)
    {
      char *my_argv[] = { "", "power.pl" };

      PERL_SYS_INIT3(&argc,&argv,&env);
      my_perl = perl_alloc();
      perl_construct( my_perl );

      perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
      PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
      perl_run(my_perl);

      PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/

      perl_destruct(my_perl);
      perl_free(my_perl);
      PERL_SYS_TERM();
          }

Compile and run:

    % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
    % power
    3 to the 4th power is 81.

Maintaining a persistent interpreter

When developing interactive and/or potentially long-running applications, it's a good idea to maintain a persistent interpreter rather than allocating and constructing a new interpreter multiple times. The major reason is speed: since Perl will only be loaded into memory once.

However, you have to be more cautious with namespace and variable scoping when using a persistent interpreter. In previous examples we've been using global variables in the default package main. We knew exactly what code would be run, and assumed we could avoid variable collisions and outrageous symbol table growth.

Let's say your application is a server that will occasionally run Perl code from some arbitrary file. Your server has no way of knowing what code it's going to run. Very dangerous.

If the file is pulled in by perl_parse(), compiled into a newly constructed interpreter, and subsequently cleaned out with perl_destruct() afterwards, you're shielded from most namespace troubles.

One way to avoid namespace collisions in this scenario is to translate the filename into a guaranteed-unique package name, and then compile the code into that package using eval in the perlfunc manpage. In the example below, each file will only be compiled once. Or, the application might choose to clean out the symbol table associated with the file after it's no longer needed. Using call_argv in the perlapi manpage, We'll call the subroutine Embed::Persistent::eval_file which lives in the file persistent.pl and pass the filename and boolean cleanup/cache flag as arguments.

Note that the process will continue to grow for each file that it uses. In addition, there might be AUTOLOADed subroutines and other conditions that cause Perl's symbol table to grow. You might want to add some logic that keeps track of the process size, or restarts itself after a certain number of requests, to ensure that memory consumption is minimized. You'll also want to scope your variables with my in the perlfunc manpage whenever possible.

 package Embed::Persistent;
 #persistent.pl

 use strict;
 our %Cache;
 use Symbol qw(delete_package);

 sub valid_package_name {
     my($string) = @_;
     $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
     # second pass only for words starting with a digit
     $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;

     # Dress it up as a real package name
     $string =~ s|/|::|g;
     return "Embed" . $string;
      }

 sub eval_file {
     my($filename, $delete) = @_;
     my $package = valid_package_name($filename);
     my $mtime = -M $filename;
     if(defined $Cache{$package}{mtime}
        &&
        $Cache{$package}{mtime} <= $mtime)
     {
        # we have compiled this subroutine already,
        # it has not been updated on disk, nothing left to do
        print STDERR "already compiled $package->handler\n";
     }
     else {
        local *FH;
        open FH, $filename or die "open '$filename' $!";
        local($/) = undef;
        my $sub = <FH>;
        close FH;

        #wrap the code into a subroutine inside our unique package
        my $eval = qq{package $package; sub handler { $sub; }};
        {
            # hide our variables within this block
            my($filename,$mtime,$package,$sub);
            eval $eval;
        }
        die $@ if $@;

        #cache it unless we're cleaning out each time
        $Cache{$package}{mtime} = $mtime unless $delete;
             }

     eval {$package->handler;};
     die $@ if $@;

     delete_package($package) if $delete;

     #take a look if you want
     #print Devel::Symdump->rnew($package)->as_string, $/;
      }

 1;

 __END__
 /* persistent.c */
 #include <EXTERN.h>
 #include <perl.h>
 /* 1 = clean out filename's symbol table after each request, 0 = don't */
 #ifndef DO_CLEAN
 #define DO_CLEAN 0
 #endif
 #define BUFFER_SIZE 1024

 static PerlInterpreter *my_perl = NULL;

 int
 main(int argc, char **argv, char **env)
 {
     char *embedding[] = { "", "persistent.pl" };
     char *args[] = { "", DO_CLEAN, NULL };
     char filename[BUFFER_SIZE];
     int exitstatus = 0;
     STRLEN n_a;

     PERL_SYS_INIT3(&argc,&argv,&env);
     if((my_perl = perl_alloc()) == NULL) {
        fprintf(stderr, "no memory!");
        exit(1);
     }
     perl_construct(my_perl);

     exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
     if(!exitstatus) {
        exitstatus = perl_run(my_perl);

        while(printf("Enter file name: ") &&
              fgets(filename, BUFFER_SIZE, stdin)) {

            filename[strlen(filename)-1] = '\0'; /* strip \n */
            /* call the subroutine, passing it the filename as an argument */
            args[0] = filename;
            call_argv("Embed::Persistent::eval_file",
                           G_DISCARD | G_EVAL, args);

            /* check $@ */
            if(SvTRUE(ERRSV))
                fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
                    }
                 }

     PL_perl_destruct_level = 0;
     perl_destruct(my_perl);
     perl_free(my_perl);
     PERL_SYS_TERM();
     exit(exitstatus);
      }

Now compile:

 % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

Here's an example script file:

 #test.pl
 my $string = "hello";
 foo($string);

 sub foo {
     print "foo says: @_\n";
 }

Now run:

 % persistent
 Enter file name: test.pl
 foo says: hello
 Enter file name: test.pl
 already compiled Embed::test_2epl->handler
 foo says: hello
 Enter file name: ^C

Execution of END blocks

Traditionally END blocks have been executed at the end of the perl_run. This causes problems for applications that never call perl_run. Since perl 5.7.2 you can specify PL_exit_flags |= PERL_EXIT_DESTRUCT_END to get the new behaviour. This also enables the running of END blocks if the perl_parse fails and perl_destruct will return the exit value.

Maintaining multiple interpreter instances

Some rare applications will need to create more than one interpreter during a session. Such an application might sporadically decide to release any resources associated with the interpreter.

The program must take care to ensure that this takes place before the next interpreter is constructed. By default, when perl is not built with any special options, the global variable PL_perl_destruct_level is set to 0, since extra cleaning isn't usually needed when a program only ever creates a single interpreter in its entire lifetime.

Setting PL_perl_destruct_level to 1 makes everything squeaky clean:

 while(1) {
     ...
     /* reset global variables here with PL_perl_destruct_level = 1 */
     PL_perl_destruct_level = 1;
     perl_construct(my_perl);
     ...
     /* clean and reset _everything_ during perl_destruct */
     PL_perl_destruct_level = 1;
     perl_destruct(my_perl);
     perl_free(my_perl);
     ...
     /* let's go do it again! */
 }

When perl_destruct() is called, the interpreter's syntax parse tree and symbol tables are cleaned up, and global variables are reset. The second assignment to PL_perl_destruct_level is needed because perl_construct resets it to 0.

Now suppose we have more than one interpreter instance running at the same time. This is feasible, but only if you used the Configure option -Dusemultiplicity or the options -Dusethreads -Duseithreads when building perl. By default, enabling one of these Configure options sets the per-interpreter global variable PL_perl_destruct_level to 1, so that thorough cleaning is automatic and interpreter variables are initialized correctly. Even if you don't intend to run two or more interpreters at the same time, but to run them sequentially, like in the above example, it is recommended to build perl with the -Dusemultiplicity option otherwise some interpreter variables may not be initialized correctly between consecutive runs and your application may crash.

Using -Dusethreads -Duseithreads rather than -Dusemultiplicity is more appropriate if you intend to run multiple interpreters concurrently in different threads, because it enables support for linking in the thread libraries of your system with the interpreter.

Let's give it a try:

 #include <EXTERN.h>
 #include <perl.h>

 /* we're going to embed two interpreters */
 /* we're going to embed two interpreters */
 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"

 int main(int argc, char **argv, char **env)
 {
     PerlInterpreter *one_perl, *two_perl;
     char *one_args[] = { "one_perl", SAY_HELLO };
     char *two_args[] = { "two_perl", SAY_HELLO };

     PERL_SYS_INIT3(&argc,&argv,&env);
     one_perl = perl_alloc();
     two_perl = perl_alloc();

     PERL_SET_CONTEXT(one_perl);
     perl_construct(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_construct(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
     PERL_SET_CONTEXT(two_perl);
     perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);

     PERL_SET_CONTEXT(one_perl);
     perl_run(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_run(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_destruct(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_destruct(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_free(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_free(two_perl);
     PERL_SYS_TERM();
      }

Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize the global state that tracks which interpreter is the "current" one on the particular process or thread that may be running it. It should always be used if you have more than one interpreter and are making perl API calls on both interpreters in an interleaved fashion.

PERL_SET_CONTEXT(interp) should also be called whenever interp is used by a thread that did not create it (using either perl_alloc(), or the more esoteric perl_clone()).

Compile as usual:

 % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

Run it, Run it:

 % multiplicity
 Hi, I'm one_perl
 Hi, I'm two_perl

Using Perl modules, which themselves use C libraries, from your C program

If you've played with the examples above and tried to embed a script that use()s a Perl module (such as Socket) which itself uses a C or C++ library, this probably happened:

 Can't load module Socket, dynamic loading not available in this perl.
  (You may need to build a new perl executable which either supports
  dynamic loading or has the Socket module statically linked into it.)

What's wrong?

Your interpreter doesn't know how to communicate with these extensions on its own. A little glue will help. Up until now you've been calling perl_parse(), handing it NULL for the second argument:

 perl_parse(my_perl, NULL, argc, my_argv, NULL);

That's where the glue code can be inserted to create the initial contact between Perl and linked C/C++ routines. Let's take a look some pieces of perlmain.c to see how Perl does this:

 static void xs_init (pTHX);

 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
 EXTERN_C void boot_Socket (pTHX_ CV* cv);

 EXTERN_C void
 xs_init(pTHX)
 {
        char *file = __FILE__;
        /* DynaLoader is a special case */
        newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
        newXS("Socket::bootstrap", boot_Socket, file);
 }

Simply put: for each extension linked with your Perl executable (determined during its initial configuration on your computer or when adding a new extension), a Perl subroutine is created to incorporate the extension's routines. Normally, that subroutine is named Module::bootstrap() and is invoked when you say use Module. In turn, this hooks into an XSUB, boot_Module, which creates a Perl counterpart for each of the extension's XSUBs. Don't worry about this part; leave that to the xsubpp and extension authors. If your extension is dynamically loaded, DynaLoader creates Module::bootstrap() for you on the fly. In fact, if you have a working DynaLoader then there is rarely any need to link in any other extensions statically.

Once you have this code, slap it into the second argument of perl_parse():

 perl_parse(my_perl, xs_init, argc, my_argv, NULL);

Then compile:

 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
 % interp
   use Socket;
   use SomeDynamicallyLoadedModule;

   print "Now I can use extensions!\n"'

ExtUtils::Embed can also automate writing the xs_init glue code.

 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
 % cc -c interp.c  `perl -MExtUtils::Embed -e ccopts`
 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`

Consult the perlxs manpage, the perlguts manpage, and the perlapi manpage for more details.

Embedding Perl under Win32

In general, all of the source code shown here should work unmodified under Windows.

However, there are some caveats about the command-line examples shown. For starters, backticks won't work under the Win32 native command shell. The ExtUtils::Embed kit on CPAN ships with a script called genmake, which generates a simple makefile to build a program from a single C source file. It can be used like this:

 C:\ExtUtils-Embed\eg> perl genmake interp.c
 C:\ExtUtils-Embed\eg> nmake
 C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"

You may wish to use a more robust environment such as the Microsoft Developer Studio. In this case, run this to generate perlxsi.c:

 perl -MExtUtils::Embed -e xsinit

Create a new project and Insert -> Files into Project: perlxsi.c, perl.lib, and your own source files, e.g. interp.c. Typically you'll find perl.lib in C:\perl\lib\CORE, if not, you should see the CORE directory relative to perl -V:archlib. The studio will also need this path so it knows where to find Perl include files. This path can be added via the Tools -> Options -> Directories menu. Finally, select Build -> Build interp.exe and you're ready to go.

Hiding Perl_

If you completely hide the short forms forms of the Perl public API, add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that for example instead of writing

    warn("%d bottles of beer on the wall", bottlecount);

you will have to write the explicit full form

    Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);

(See Background and PERL_IMPLICIT_CONTEXT for the explanation of the aTHX_. in the perlguts manpage ) Hiding the short forms is very useful for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts with other software packages (Perl defines about 2400 APIs with these short names, take or leave few hundred, so there certainly is room for conflict.)

MORAL

You can sometimes write faster code in C, but you can always write code faster in Perl. Because you can use each from the other, combine them as you wish.

AUTHOR

Jon Orwant <orwant@media.mit.edu> and Doug MacEachern <dougm@covalent.net>, with small contributions from Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya Zakharevich.

Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the most widely-used Perl embedding: the mod_perl system (perl.apache.org), which embeds Perl in the Apache web server. Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used this model for Oracle, Netscape and Internet Information Server Perl plugins.

COPYRIGHT

Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All Rights Reserved.

Permission is granted to make and distribute verbatim copies of this documentation provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this documentation under the conditions for verbatim copying, provided also that they are marked clearly as modified versions, that the authors' names and title are unchanged (though subtitles and additional authors' names may be added), and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this documentation into another language, under the above conditions for modified versions.


perlguts - Introduction to the Perl API

  • Variables
    • Datatypes
    • What is an "IV"?
    • Working with SVs
    • Offsets
    • What's Really Stored in an SV?
    • Working with AVs
    • Working with HVs
    • Hash API Extensions
    • AVs, HVs and undefined values
    • References
    • Blessed References and Class Objects
    • Creating New Variables
    • Reference Counts and Mortality
    • Stashes and Globs
    • Double-Typed SVs
    • Magic Variables
    • Assigning Magic
    • Magic Virtual Tables
    • Finding Magic
    • Understanding the Magic of Tied Hashes and Arrays
    • Localizing changes
  • Subroutines
    • XSUBs and the Argument Stack
    • Calling Perl Routines from within C Programs
    • Memory Allocation
      • Allocation
      • Reallocation
      • Moving
    • PerlIO
    • Putting a C value on Perl stack
    • Scratchpads
    • Scratchpads and recursion
  • Compiled code
    • Code tree
    • Examining the tree
    • Compile pass 1: check routines
    • Compile pass 1a: constant folding
    • Compile pass 2: context propagation
    • Compile pass 3: peephole optimization
    • Pluggable runops
  • Examining internal data structures with the dump functions
  • How multiple interpreters and concurrency are supported
    • Background and PERL_IMPLICIT_CONTEXT
    • So what happened to dTHR?
    • How do I use all this in extensions?
    • Should I do anything special if I call perl from multiple threads?
    • Future Plans and PERL_IMPLICIT_SYS
  • Internal Functions
    • Formatted Printing of IVs, UVs, and NVs
    • Pointer-To-Integer and Integer-To-Pointer
    • Source Documentation
    • Backwards compatibility
  • Unicode Support
    • What is Unicode, anyway?
    • How can I recognise a UTF-8 string?
    • How does UTF-8 represent Unicode characters?
    • How does Perl store UTF-8 strings?
    • How do I convert a string to UTF-8?
    • Is there anything else I need to know?
  • Custom Operators
  • AUTHORS
  • SEE ALSO

NAME

perlguts - Introduction to the Perl API

DESCRIPTION

This document attempts to describe how to use the Perl API, as well as to provide some info on the basic workings of the Perl core. It is far from complete and probably contains many errors. Please refer any questions or comments to the author below.

Variables

Datatypes

Perl has three typedefs that handle Perl's three main data types:

    SV  Scalar Value
    AV  Array Value
    HV  Hash Value

Each typedef has specific routines that manipulate the various data types.

What is an "IV"?

Perl uses a special typedef IV which is a simple signed integer type that is guaranteed to be large enough to hold a pointer (as well as an integer). Additionally, there is the UV, which is simply an unsigned IV.

Perl also uses two special typedefs, I32 and I16, which will always be at least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16, as well.) They will usually be exactly 32 and 16 bits long, but on Crays they will both be 64 bits.

Working with SVs

An SV can be created and loaded with one command. There are five types of values that can be loaded: an integer value (IV), an unsigned integer value (UV), a double (NV), a string (PV), and another scalar (SV).

The seven routines are:

    SV*  newSViv(IV);
    SV*  newSVuv(UV);
    SV*  newSVnv(double);
    SV*  newSVpv(const char*, STRLEN);
    SV*  newSVpvn(const char*, STRLEN);
    SV*  newSVpvf(const char*, ...);
    SV*  newSVsv(SV*);

STRLEN is an integer type (Size_t, usually defined as size_t in config.h) guaranteed to be large enough to represent the size of any string that perl can handle.

In the unlikely case of a SV requiring more complex initialisation, you can create an empty SV with newSV(len). If len is 0 an empty SV of type NULL is returned, else an SV of type PV is returned with len + 1 (for the NUL) bytes of storage allocated, accessible via SvPVX. In both cases the SV has value undef.

    SV *sv = newSV(0);   /* no storage allocated  */
    SV *sv = newSV(10);  /* 10 (+1) bytes of uninitialised storage allocated  */

To change the value of an already-existing SV, there are eight routines:

    void  sv_setiv(SV*, IV);
    void  sv_setuv(SV*, UV);
    void  sv_setnv(SV*, double);
    void  sv_setpv(SV*, const char*);
    void  sv_setpvn(SV*, const char*, STRLEN)
    void  sv_setpvf(SV*, const char*, ...);
    void  sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *);
    void  sv_setsv(SV*, SV*);

Notice that you can choose to specify the length of the string to be assigned by using sv_setpvn, newSVpvn, or newSVpv, or you may allow Perl to calculate the length by using sv_setpv or by specifying 0 as the second argument to newSVpv. Be warned, though, that Perl will determine the string's length by using strlen, which depends on the string terminating with a NUL character.

The arguments of sv_setpvf are processed like sprintf, and the formatted output becomes the value.

sv_vsetpvfn is an analogue of vsprintf, but it allows you to specify either a pointer to a variable argument list or the address and length of an array of SVs. The last argument points to a boolean; on return, if that boolean is true, then locale-specific information has been used to format the string, and the string's contents are therefore untrustworthy (see the perlsec manpage). This pointer may be NULL if that information is not important. Note that this function requires you to specify the length of the format.

The sv_set*() functions are not generic enough to operate on values that have "magic". See Magic Virtual Tables later in this document.

All SVs that contain strings should be terminated with a NUL character. If it is not NUL-terminated there is a risk of core dumps and corruptions from code which passes the string to C functions or system calls which expect a NUL-terminated string. Perl's own functions typically add a trailing NUL for this reason. Nevertheless, you should be very careful when you pass a string stored in an SV to a C function or system call.

To access the actual value that an SV points to, you can use the macros:

    SvIV(SV*)
    SvUV(SV*)
    SvNV(SV*)
    SvPV(SV*, STRLEN len)
    SvPV_nolen(SV*)

which will automatically coerce the actual scalar type into an IV, UV, double, or string.

In the SvPV macro, the length of the string returned is placed into the variable len (this is a macro, so you do not use &len). If you do not care what the length of the data is, use the SvPV_nolen macro. Historically the SvPV macro with the global variable PL_na has been used in this case. But that can be quite inefficient because PL_na must be accessed in thread-local storage in threaded Perl. In any case, remember that Perl allows arbitrary strings of data that may both contain NULs and might not be terminated by a NUL.

Also remember that C doesn't allow you to safely say foo(SvPV(s, len), len);. It might work with your compiler, but it won't work for everyone. Break this sort of statement up into separate assignments:

    SV *s;
    STRLEN len;
    char * ptr;
    ptr = SvPV(s, len);
    foo(ptr, len);

If you want to know if the scalar value is TRUE, you can use:

    SvTRUE(SV*)

Although Perl will automatically grow strings for you, if you need to force Perl to allocate more memory for your SV, you can use the macro

    SvGROW(SV*, STRLEN newlen)

which will determine if more memory needs to be allocated. If so, it will call the function sv_grow. Note that SvGROW can only increase, not decrease, the allocated memory of an SV and that it does not automatically add a byte for the a trailing NUL (perl's own string functions typically do SvGROW(sv, len + 1)).

If you have an SV and want to know what kind of data Perl thinks is stored in it, you can use the following macros to check the type of SV you have.

    SvIOK(SV*)
    SvNOK(SV*)
    SvPOK(SV*)

You can get and set the current length of the string stored in an SV with the following macros:

    SvCUR(SV*)
    SvCUR_set(SV*, I32 val)

You can also get a pointer to the end of the string stored in the SV with the macro:

    SvEND(SV*)

But note that these last three macros are valid only if SvPOK() is true.

If you want to append something to the end of string stored in an SV*, you can use the following functions:

    void  sv_catpv(SV*, const char*);
    void  sv_catpvn(SV*, const char*, STRLEN);
    void  sv_catpvf(SV*, const char*, ...);
    void  sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
    void  sv_catsv(SV*, SV*);

The first function calculates the length of the string to be appended by using strlen. In the second, you specify the length of the string yourself. The third function processes its arguments like sprintf and appends the formatted output. The fourth function works like vsprintf. You can specify the address and length of an array of SVs instead of the va_list argument. The fifth function extends the string stored in the first SV with the string stored in the second SV. It also forces the second SV to be interpreted as a string.

The sv_cat*() functions are not generic enough to operate on values that have "magic". See Magic Virtual Tables later in this document.

If you know the name of a scalar variable, you can get a pointer to its SV by using the following:

    SV*  get_sv("package::varname", FALSE);

This returns NULL if the variable does not exist.

If you want to know if this variable (or any other SV) is actually defined, you can call:

    SvOK(SV*)

The scalar undef value is stored in an SV instance called PL_sv_undef.

Its address can be used whenever an SV* is needed. Make sure that you don't try to compare a random sv with &PL_sv_undef. For example when interfacing Perl code, it'll work correctly for:

  foo(undef);

But won't work when called as:

  $x = undef;
  foo($x);

So to repeat always use SvOK() to check whether an sv is defined.

Also you have to be careful when using &PL_sv_undef as a value in AVs or HVs (see AVs, HVs and undefined values).

There are also the two values PL_sv_yes and PL_sv_no, which contain boolean TRUE and FALSE values, respectively. Like PL_sv_undef, their addresses can be used whenever an SV* is needed.

Do not be fooled into thinking that (SV *) 0 is the same as &PL_sv_undef. Take this code:

    SV* sv = (SV*) 0;
    if (I-am-to-return-a-real-value) {
            sv = sv_2mortal(newSViv(42));
    }
    sv_setsv(ST(0), sv);

This code tries to return a new SV (which contains the value 42) if it should return a real value, or undef otherwise. Instead it has returned a NULL pointer which, somewhere down the line, will cause a segmentation violation, bus error, or just weird results. Change the zero to &PL_sv_undef in the first line and all will be well.

To free an SV that you've created, call SvREFCNT_dec(SV*). Normally this call is not necessary (see Reference Counts and Mortality).

Offsets

Perl provides the function sv_chop to efficiently remove characters from the beginning of a string; you give it an SV and a pointer to somewhere inside the PV, and it discards everything before the pointer. The efficiency comes by means of a little hack: instead of actually removing the characters, sv_chop sets the flag OOK (offset OK) to signal to other functions that the offset hack is in effect, and it puts the number of bytes chopped off into the IV field of the SV. It then moves the PV pointer (called SvPVX) forward that many bytes, and adjusts SvCUR and SvLEN.

Hence, at this point, the start of the buffer that we allocated lives at SvPVX(sv) - SvIV(sv) in memory and the PV pointer is pointing into the middle of this allocated storage.

This is best demonstrated by example:

  % ./perl -Ilib -MDevel::Peek -le '$a="12345"; $a=~s/.//; Dump($a)'
  SV = PVIV(0x8128450) at 0x81340f0
    REFCNT = 1
    FLAGS = (POK,OOK,pPOK)
    IV = 1  (OFFSET)
    PV = 0x8135781 ( "1" . ) "2345"\0
    CUR = 4
    LEN = 5

Here the number of bytes chopped off (1) is put into IV, and Devel::Peek::Dump helpfully reminds us that this is an offset. The portion of the string between the "real" and the "fake" beginnings is shown in parentheses, and the values of SvCUR and SvLEN reflect the fake beginning, not the real one.

Something similar to the offset hack is performed on AVs to enable efficient shifting and splicing off the beginning of the array; while AvARRAY points to the first element in the array that is visible from Perl, AvALLOC points to the real start of the C array. These are usually the same, but a shift operation can be carried out by increasing AvARRAY by one and decreasing AvFILL and AvLEN. Again, the location of the real start of the C array only comes into play when freeing the array. See av_shift in av.c.

What's Really Stored in an SV?

Recall that the usual method of determining the type of scalar you have is to use Sv*OK macros. Because a scalar can be both a number and a string, usually these macros will always return TRUE and calling the Sv*V macros will do the appropriate conversion of string to integer/double or integer/double to string.

If you really need to know if you have an integer, double, or string pointer in an SV, you can use the following three macros instead:

    SvIOKp(SV*)
    SvNOKp(SV*)
    SvPOKp(SV*)

These will tell you if you truly have an integer, double, or string pointer stored in your SV. The "p" stands for private.

The are various ways in which the private and public flags may differ. For example, a tied SV may have a valid underlying value in the IV slot (so SvIOKp is true), but the data should be accessed via the FETCH routine rather than directly, so SvIOK is false. Another is when numeric conversion has occurred and precision has been lost: only the private flag is set on 'lossy' values. So when an NV is converted to an IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.

In general, though, it's best to use the Sv*V macros.

Working with AVs

There are two ways to create and load an AV. The first method creates an empty AV:

    AV*  newAV();

The second method both creates the AV and initially populates it with SVs:

    AV*  av_make(I32 num, SV **ptr);

The second argument points to an array containing num SV*'s. Once the AV has been created, the SVs can be destroyed, if so desired.

Once the AV has been created, the following operations are possible on AVs:

    void  av_push(AV*, SV*);
    SV*   av_pop(AV*);
    SV*   av_shift(AV*);
    void  av_unshift(AV*, I32 num);

These should be familiar operations, with the exception of av_unshift. This routine adds num elements at the front of the array with the undef value. You must then use av_store (described below) to assign values to these new elements.

Here are some other functions:

    I32   av_len(AV*);
    SV**  av_fetch(AV*, I32 key, I32 lval);
    SV**  av_store(AV*, I32 key, SV* val);

The av_len function returns the highest index value in array (just like $#array in Perl). If the array is empty, -1 is returned. The av_fetch function returns the value at index key, but if lval is non-zero, then av_fetch will store an undef value at that index. The av_store function stores the value val at index key, and does not increment the reference count of val. Thus the caller is responsible for taking care of that, and if av_store returns NULL, the caller will have to decrement the reference count to avoid a memory leak. Note that av_fetch and av_store both return SV**'s, not SV*'s as their return value.

    void  av_clear(AV*);
    void  av_undef(AV*);
    void  av_extend(AV*, I32 key);

The av_clear function deletes all the elements in the AV* array, but does not actually delete the array itself. The av_undef function will delete all the elements in the array plus the array itself. The av_extend function extends the array so that it contains at least key+1 elements. If key+1 is less than the currently allocated length of the array, then nothing is done.

If you know the name of an array variable, you can get a pointer to its AV by using the following:

    AV*  get_av("package::varname", FALSE);

This returns NULL if the variable does not exist.

See Understanding the Magic of Tied Hashes and Arrays for more information on how to use the array access functions on tied arrays.

Working with HVs

To create an HV, you use the following routine:

    HV*  newHV();

Once the HV has been created, the following operations are possible on HVs:

    SV**  hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
    SV**  hv_fetch(HV*, const char* key, U32 klen, I32 lval);

The klen parameter is the length of the key being passed in (Note that you cannot pass 0 in as a value of klen to tell Perl to measure the length of the key). The val argument contains the SV pointer to the scalar being stored, and hash is the precomputed hash value (zero if you want hv_store to calculate it for you). The lval parameter indicates whether this fetch is actually a part of a store operation, in which case a new undefined value will be added to the HV with the supplied key and hv_fetch will return as if the value had already existed.

Remember that hv_store and hv_fetch return SV**'s and not just SV*. To access the scalar value, you must first dereference the return value. However, you should check to make sure that the return value is not NULL before dereferencing it.

These two functions check if a hash table entry exists, and deletes it.

    bool  hv_exists(HV*, const char* key, U32 klen);
    SV*   hv_delete(HV*, const char* key, U32 klen, I32 flags);

If flags does not include the G_DISCARD flag then hv_delete will create and return a mortal copy of the deleted value.

And more miscellaneous functions:

    void   hv_clear(HV*);
    void   hv_undef(HV*);

Like their AV counterparts, hv_clear deletes all the entries in the hash table but does not actually delete the hash table. The hv_undef deletes both the entries and the hash table itself.

Perl keeps the actual data in linked list of structures with a typedef of HE. These contain the actual key and value pointers (plus extra administrative overhead). The key is a string pointer; the value is an SV*. However, once you have an HE*, to get the actual key and value, use the routines specified below.

    I32    hv_iterinit(HV*);
            /* Prepares starting point to traverse hash table */
    HE*    hv_iternext(HV*);
            /* Get the next entry, and return a pointer to a
               structure that has both the key and value */
    char*  hv_iterkey(HE* entry, I32* retlen);
            /* Get the key from an HE structure and also return
               the length of the key string */
    SV*    hv_iterval(HV*, HE* entry);
            /* Return an SV pointer to the value of the HE
               structure */
    SV*    hv_iternextsv(HV*, char** key, I32* retlen);
            /* This convenience routine combines hv_iternext,
               hv_iterkey, and hv_iterval.  The key and retlen
               arguments are return values for the key and its
               length.  The value is returned in the SV* argument */

If you know the name of a hash variable, you can get a pointer to its HV by using the following:

    HV*  get_hv("package::varname", FALSE);

This returns NULL if the variable does not exist.

The hash algorithm is defined in the PERL_HASH(hash, key, klen) macro:

    hash = 0;
    while (klen--)
        hash = (hash * 33) + *key++;
    hash = hash + (hash >> 5);                  /* after 5.6 */

The last step was added in version 5.6 to improve distribution of lower bits in the resulting hash value.

See Understanding the Magic of Tied Hashes and Arrays for more information on how to use the hash access functions on tied hashes.

Hash API Extensions

Beginning with version 5.004, the following functions are also supported:

    HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
    HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);

    bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
    SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);

    SV*     hv_iterkeysv  (HE* entry);

Note that these functions take SV* keys, which simplifies writing of extension code that deals with hash structures. These functions also allow passing of SV* keys to tie functions without forcing you to stringify the keys (unlike the previous set of functions).

They also return and accept whole hash entries (HE*), making their use more efficient (since the hash number for a particular string doesn't have to be recomputed every time). See the perlapi manpage for detailed descriptions.

The following macros must always be used to access the contents of hash entries. Note that the arguments to these macros must be simple variables, since they may get evaluated more than once. See the perlapi manpage for detailed descriptions of these macros.

    HePV(HE* he, STRLEN len)
    HeVAL(HE* he)
    HeHASH(HE* he)
    HeSVKEY(HE* he)
    HeSVKEY_force(HE* he)
    HeSVKEY_set(HE* he, SV* sv)

These two lower level macros are defined, but must only be used when dealing with keys that are not SV*s:

    HeKEY(HE* he)
    HeKLEN(HE* he)

Note that both hv_store and hv_store_ent do not increment the reference count of the stored val, which is the caller's responsibility. If these functions return a NULL value, the caller will usually have to decrement the reference count of val to avoid a memory leak.

AVs, HVs and undefined values

Sometimes you have to store undefined values in AVs or HVs. Although this may be a rare case, it can be tricky. That's because you're used to using &PL_sv_undef if you need an undefined SV.

For example, intuition tells you that this XS code:

    AV *av = newAV();
    av_store( av, 0, &PL_sv_undef );

is equivalent to this Perl code:

    my @av;
    $av[0] = undef;

Unfortunately, this isn't true. AVs use &PL_sv_undef as a marker for indicating that an array element has not yet been initialized. Thus, exists $av[0] would be true for the above Perl code, but false for the array generated by the XS code.

Other problems can occur when storing &PL_sv_undef in HVs:

    hv_store( hv, "key", 3, &PL_sv_undef, 0 );

This will indeed make the value undef, but if you try to modify the value of key, you'll get the following error:

    Modification of non-creatable hash value attempted

In perl 5.8.0, &PL_sv_undef was also used to mark placeholders in restricted hashes. This caused such hash entries not to appear when iterating over the hash or when checking for the keys with the hv_exists function.

You can run into similar problems when you store &PL_sv_true or &PL_sv_false into AVs or HVs. Trying to modify such elements will give you the following error:

    Modification of a read-only value attempted

To make a long story short, you can use the special variables &PL_sv_undef, &PL_sv_true and &PL_sv_false with AVs and HVs, but you have to make sure you know what you're doing.

Generally, if you want to store an undefined value in an AV or HV, you should not use &PL_sv_undef, but rather create a new undefined value using the newSV function, for example:

    av_store( av, 42, newSV(0) );
    hv_store( hv, "foo", 3, newSV(0), 0 );

References

References are a special type of scalar that point to other data types (including references).

To create a reference, use either of the following functions:

    SV* newRV_inc((SV*) thing);
    SV* newRV_noinc((SV*) thing);

The thing argument can be any of an SV*, AV*, or HV*. The functions are identical except that newRV_inc increments the reference count of the thing, while newRV_noinc does not. For historical reasons, newRV is a synonym for newRV_inc.

Once you have a reference, you can use the following macro to dereference the reference:

    SvRV(SV*)

then call the appropriate routines, casting the returned SV* to either an AV* or HV*, if required.

To determine if an SV is a reference, you can use the following macro:

    SvROK(SV*)

To discover what type of value the reference refers to, use the following macro and then check the return value.

    SvTYPE(SvRV(SV*))

The most useful types that will be returned are:

    SVt_IV    Scalar
    SVt_NV    Scalar
    SVt_PV    Scalar
    SVt_RV    Scalar
    SVt_PVAV  Array
    SVt_PVHV  Hash
    SVt_PVCV  Code
    SVt_PVGV  Glob (possible a file handle)
    SVt_PVMG  Blessed or Magical Scalar
    See the sv.h header file for more details.

Blessed References and Class Objects

References are also used to support object-oriented programming. In perl's OO lexicon, an object is simply a reference that has been blessed into a package (or class). Once blessed, the programmer may now use the reference to access the various methods in the class.

A reference can be blessed into a package with the following function:

    SV* sv_bless(SV* sv, HV* stash);

The sv argument must be a reference value. The stash argument specifies which class the reference will belong to. See Stashes and Globs for information on converting class names into stashes.

/* Still under construction */

Upgrades rv to reference if not already one. Creates new SV for rv to point to. If classname is non-null, the SV is blessed into the specified class. SV is returned.

        SV* newSVrv(SV* rv, const char* classname);

Copies integer, unsigned integer or double into an SV whose reference is rv. SV is blessed if classname is non-null.

        SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
        SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
        SV* sv_setref_nv(SV* rv, const char* classname, NV iv);

Copies the pointer value (the address, not the string!) into an SV whose reference is rv. SV is blessed if classname is non-null.

        SV* sv_setref_pv(SV* rv, const char* classname, PV iv);

Copies string into an SV whose reference is rv. Set length to 0 to let Perl calculate the string length. SV is blessed if classname is non-null.

        SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);

Tests whether the SV is blessed into the specified class. It does not check inheritance relationships.

        int  sv_isa(SV* sv, const char* name);

Tests whether the SV is a reference to a blessed object.

        int  sv_isobject(SV* sv);

Tests whether the SV is derived from the specified class. SV can be either a reference to a blessed object or a string containing a class name. This is the function implementing the UNIVERSAL::isa functionality.

        bool sv_derived_from(SV* sv, const char* name);

To check if you've got an object derived from a specific class you have to write:

        if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }

Creating New Variables

To create a new Perl variable with an undef value which can be accessed from your Perl script, use the following routines, depending on the variable type.

    SV*  get_sv("package::varname", TRUE);
    AV*  get_av("package::varname", TRUE);
    HV*  get_hv("package::varname", TRUE);

Notice the use of TRUE as the second parameter. The new variable can now be set, using the routines appropriate to the data type.

There are additional macros whose values may be bitwise OR'ed with the TRUE argument to enable certain extra features. Those bits are:

GV_ADDMULTI

Marks the variable as multiply defined, thus preventing the:

  Name <varname> used only once: possible typo

warning.

GV_ADDWARN

Issues the warning:

  Had to create <varname> unexpectedly

if the variable did not exist before the function was called.

If you do not specify a package name, the variable is created in the current package.

Reference Counts and Mortality

Perl uses a reference count-driven garbage collection mechanism. SVs, AVs, or HVs (xV for short in the following) start their life with a reference count of 1. If the reference count of an xV ever drops to 0, then it will be destroyed and its memory made available for reuse.

This normally doesn't happen at the Perl level unless a variable is undef'ed or the last variable holding a reference to it is changed or overwritten. At the internal level, however, reference counts can be manipulated with the following macros:

    int SvREFCNT(SV* sv);
    SV* SvREFCNT_inc(SV* sv);
    void SvREFCNT_dec(SV* sv);

However, there is one other function which manipulates the reference count of its argument. The newRV_inc function, you will recall, creates a reference to the specified argument. As a side effect, it increments the argument's reference count. If this is not what you want, use newRV_noinc instead.

For example, imagine you want to return a reference from an XSUB function. Inside the XSUB routine, you create an SV which initially has a reference count of one. Then you call newRV_inc, passing it the just-created SV. This returns the reference as a new SV, but the reference count of the SV you passed to newRV_inc has been incremented to two. Now you return the reference from the XSUB routine and forget about the SV. But Perl hasn't! Whenever the returned reference is destroyed, the reference count of the original SV is decreased to one and nothing happens. The SV will hang around without any way to access it until Perl itself terminates. This is a memory leak.

The correct procedure, then, is to use newRV_noinc instead of newRV_inc. Then, if and when the last reference is destroyed, the reference count of the SV will go to zero and it will be destroyed, stopping any memory leak.

There are some convenience functions available that can help with the destruction of xVs. These functions introduce the concept of "mortality". An xV that is mortal has had its reference count marked to be decremented, but not actually decremented, until "a short time later". Generally the term "short time later" means a single Perl statement, such as a call to an XSUB function. The actual determinant for when mortal xVs have their reference count decremented depends on two macros, SAVETMPS and FREETMPS. See the perlcall manpage and the perlxs manpage for more details on these macros.

"Mortalization" then is at its simplest a deferred SvREFCNT_dec. However, if you mortalize a variable twice, the reference count will later be decremented twice.

"Mortal" SVs are mainly used for SVs that are placed on perl's stack. For example an SV which is created just to pass a number to a called sub is made mortal to have it cleaned up automatically when it's popped off the stack. Similarly, results returned by XSUBs (which are pushed on the stack) are often made mortal.

To create a mortal variable, use the functions:

    SV*  sv_newmortal()
    SV*  sv_2mortal(SV*)
    SV*  sv_mortalcopy(SV*)

The first call creates a mortal SV (with no value), the second converts an existing SV to a mortal SV (and thus defers a call to SvREFCNT_dec), and the third creates a mortal copy of an existing SV. Because sv_newmortal gives the new SV no value,it must normally be given one via sv_setpv, sv_setiv, etc. :

    SV *tmp = sv_newmortal();
    sv_setiv(tmp, an_integer);

As that is multiple C statements it is quite common so see this idiom instead:

    SV *tmp = sv_2mortal(newSViv(an_integer));

You should be careful about creating mortal variables. Strange things can happen if you make the same value mortal within multiple contexts, or if you make a variable mortal multiple times. Thinking of "Mortalization" as deferred SvREFCNT_dec should help to minimize such problems. For example if you are passing an SV which you know has high enough REFCNT to survive its use on the stack you need not do any mortalization. If you are not sure then doing an SvREFCNT_inc and sv_2mortal, or making a sv_mortalcopy is safer.

The mortal routines are not just for SVs -- AVs and HVs can be made mortal by passing their address (type-casted to SV*) to the sv_2mortal or sv_mortalcopy routines.

Stashes and Globs

A stash is a hash that contains all variables that are defined within a package. Each key of the stash is a symbol name (shared by all the different types of objects that have the same name), and each value in the hash table is a GV (Glob Value). This GV in turn contains references to the various objects of that name, including (but not limited to) the following:

    Scalar Value
    Array Value
    Hash Value
    I/O Handle
    Format
    Subroutine

There is a single stash called PL_defstash that holds the items that exist in the main package. To get at the items in other packages, append the string "::" to the package name. The items in the Foo package are in the stash Foo:: in PL_defstash. The items in the Bar::Baz package are in the stash Baz:: in Bar::'s stash.

To get the stash pointer for a particular package, use the function:

    HV*  gv_stashpv(const char* name, I32 create)
    HV*  gv_stashsv(SV*, I32 create)

The first function takes a literal string, the second uses the string stored in the SV. Remember that a stash is just a hash table, so you get back an HV*. The create flag will create a new package if it is set.

The name that gv_stash*v wants is the name of the package whose symbol table you want. The default package is called main. If you have multiply nested packages, pass their names to gv_stash*v, separated by :: as in the Perl language itself.

Alternately, if you have an SV that is a blessed reference, you can find out the stash pointer by using:

    HV*  SvSTASH(SvRV(SV*));

then use the following to get the package name itself:

    char*  HvNAME(HV* stash);

If you need to bless or re-bless an object you can use the following function:

    SV*  sv_bless(SV*, HV* stash)

where the first argument, an SV*, must be a reference, and the second argument is a stash. The returned SV* can now be used in the same way as any other SV.

For more information on references and blessings, consult the perlref manpage.

Double-Typed SVs

Scalar variables normally contain only one type of value, an integer, double, pointer, or reference. Perl will automatically convert the actual scalar data from the stored type into the requested type.

Some scalar variables contain more than one type of scalar data. For example, the variable $! contains either the numeric value of errno or its string equivalent from either strerror or sys_errlist[].

To force multiple data values into an SV, you must do two things: use the sv_set*v routines to add the additional scalar type, then set a flag so that Perl will believe it contains more than one type of data. The four macros to set the flags are:

        SvIOK_on
        SvNOK_on
        SvPOK_on
        SvROK_on

The particular macro you must use depends on which sv_set*v routine you called first. This is because every sv_set*v routine turns on only the bit for the particular type of data being set, and turns off all the rest.

For example, to create a new Perl variable called "dberror" that contains both the numeric and descriptive string error values, you could use the following code:

    extern int  dberror;
    extern char *dberror_list;

    SV* sv = get_sv("dberror", TRUE);
    sv_setiv(sv, (IV) dberror);
    sv_setpv(sv, dberror_list[dberror]);
    SvIOK_on(sv);

If the order of sv_setiv and sv_setpv had been reversed, then the macro SvPOK_on would need to be called instead of SvIOK_on.

Magic Variables

[This section still under construction. Ignore everything here. Post no bills. Everything not permitted is forbidden.]

Any SV may be magical, that is, it has special features that a normal SV does not have. These features are stored in the SV structure in a linked list of struct magic's, typedef'ed to MAGIC.

    struct magic {
        MAGIC*      mg_moremagic;
        MGVTBL*     mg_virtual;
        U16         mg_private;
        char        mg_type;
        U8          mg_flags;
        SV*         mg_obj;
        char*       mg_ptr;
        I32         mg_len;
    };

Note this is current as of patchlevel 0, and could change at any time.

Assigning Magic

Perl adds magic to an SV using the sv_magic function:

    void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);

The sv argument is a pointer to the SV that is to acquire a new magical feature.

If sv is not already magical, Perl uses the SvUPGRADE macro to convert sv to type SVt_PVMG. Perl then continues by adding new magic to the beginning of the linked list of magical features. Any prior entry of the same type of magic is deleted. Note that this can be overridden, and multiple instances of the same type of magic can be associated with an SV.

The name and namlen arguments are used to associate a string with the magic, typically the name of a variable. namlen is stored in the mg_len field and if name is non-null then either a savepvn copy of name or name itself is stored in the mg_ptr field, depending on whether namlen is greater than zero or equal to zero respectively. As a special case, if (name && namlen == HEf_SVKEY) then name is assumed to contain an SV* and is stored as-is with its REFCNT incremented.

The sv_magic function uses how to determine which, if any, predefined "Magic Virtual Table" should be assigned to the mg_virtual field. See the Magic Virtual Tables section below. The how argument is also stored in the mg_type field. The value of how should be chosen from the set of macros PERL_MAGIC_foo found in perl.h. Note that before these macros were added, Perl internals used to directly use character literals, so you may occasionally come across old code or documentation referring to 'U' magic rather than PERL_MAGIC_uvar for example.

The obj argument is stored in the mg_obj field of the MAGIC structure. If it is not the same as the sv argument, the reference count of the obj object is incremented. If it is the same, or if the how argument is PERL_MAGIC_arylen, or if it is a NULL pointer, then obj is merely stored, without the reference count being incremented.

See also sv_magicext in the perlapi manpage for a more flexible way to add magic to an SV.

There is also a function to add magic to an HV:

    void hv_magic(HV *hv, GV *gv, int how);

This simply calls sv_magic and coerces the gv argument into an SV.

To remove the magic from an SV, call the function sv_unmagic:

    void sv_unmagic(SV *sv, int type);

The type argument should be equal to the how value when the SV was initially made magical.

Magic Virtual Tables

The mg_virtual field in the MAGIC structure is a pointer to an MGVTBL, which is a structure of function pointers and stands for "Magic Virtual Table" to handle the various operations that might be applied to that variable.

The MGVTBL has five pointers to the following routine types:

    int  (*svt_get)(SV* sv, MAGIC* mg);
    int  (*svt_set)(SV* sv, MAGIC* mg);
    U32  (*svt_len)(SV* sv, MAGIC* mg);
    int  (*svt_clear)(SV* sv, MAGIC* mg);
    int  (*svt_free)(SV* sv, MAGIC* mg);

This MGVTBL structure is set at compile-time in perl.h and there are currently 19 types (or 21 with overloading turned on). These different structures contain pointers to various routines that perform additional actions depending on which function is being called.

    Function pointer    Action taken
    ----------------    ------------
    svt_get             Do something before the value of the SV is retrieved.
    svt_set             Do something after the SV is assigned a value.
    svt_len             Report on the SV's length.
    svt_clear           Clear something the SV represents.
    svt_free            Free any extra storage associated with the SV.

For instance, the MGVTBL structure called vtbl_sv (which corresponds to an mg_type of PERL_MAGIC_sv) contains:

    { magic_get, magic_set, magic_len, 0, 0 }

Thus, when an SV is determined to be magical and of type PERL_MAGIC_sv, if a get operation is being performed, the routine magic_get is called. All the various routines for the various magical types begin with magic_. NOTE: the magic routines are not considered part of the Perl API, and may not be exported by the Perl library.

The current kinds of Magic Virtual Tables are:

    mg_type
    (old-style char and macro)   MGVTBL         Type of magic
    --------------------------   ------         ----------------------------
    \0 PERL_MAGIC_sv             vtbl_sv        Special scalar variable
    A  PERL_MAGIC_overload       vtbl_amagic    %OVERLOAD hash
    a  PERL_MAGIC_overload_elem  vtbl_amagicelem %OVERLOAD hash element
    c  PERL_MAGIC_overload_table (none)         Holds overload table (AMT)
                                                on stash
    B  PERL_MAGIC_bm             vtbl_bm        Boyer-Moore (fast string search)
    D  PERL_MAGIC_regdata        vtbl_regdata   Regex match position data
                                                (@+ and @- vars)
    d  PERL_MAGIC_regdatum       vtbl_regdatum  Regex match position data
                                                element
    E  PERL_MAGIC_env            vtbl_env       %ENV hash
    e  PERL_MAGIC_envelem        vtbl_envelem   %ENV hash element
    f  PERL_MAGIC_fm             vtbl_fm        Formline ('compiled' format)
    g  PERL_MAGIC_regex_global   vtbl_mglob     m//g target / study()ed string
    I  PERL_MAGIC_isa            vtbl_isa       @ISA array
    i  PERL_MAGIC_isaelem        vtbl_isaelem   @ISA array element
    k  PERL_MAGIC_nkeys          vtbl_nkeys     scalar(keys()) lvalue
    L  PERL_MAGIC_dbfile         (none)         Debugger %_<filename
    l  PERL_MAGIC_dbline         vtbl_dbline    Debugger %_<filename element
    m  PERL_MAGIC_mutex          vtbl_mutex     ???
    o  PERL_MAGIC_collxfrm       vtbl_collxfrm  Locale collate transformation
    P  PERL_MAGIC_tied           vtbl_pack      Tied array or hash
    p  PERL_MAGIC_tiedelem       vtbl_packelem  Tied array or hash element
    q  PERL_MAGIC_tiedscalar     vtbl_packelem  Tied scalar or handle
    r  PERL_MAGIC_qr             vtbl_qr        precompiled qr// regex
    S  PERL_MAGIC_sig            vtbl_sig       %SIG hash
    s  PERL_MAGIC_sigelem        vtbl_sigelem   %SIG hash element
    t  PERL_MAGIC_taint          vtbl_taint     Taintedness
    U  PERL_MAGIC_uvar           vtbl_uvar      Available for use by extensions
    v  PERL_MAGIC_vec            vtbl_vec       vec() lvalue
    V  PERL_MAGIC_vstring        (none)         v-string scalars
    w  PERL_MAGIC_utf8           vtbl_utf8      UTF-8 length+offset cache
    x  PERL_MAGIC_substr         vtbl_substr    substr() lvalue
    y  PERL_MAGIC_defelem        vtbl_defelem   Shadow "foreach" iterator
                                                variable / smart parameter
                                                vivification
    *  PERL_MAGIC_glob           vtbl_glob      GV (typeglob)
    #  PERL_MAGIC_arylen         vtbl_arylen    Array length ($#ary)
    .  PERL_MAGIC_pos            vtbl_pos       pos() lvalue
    <  PERL_MAGIC_backref        vtbl_backref   ???
    ~  PERL_MAGIC_ext            (none)         Available for use by extensions

When an uppercase and lowercase letter both exist in the table, then the uppercase letter is typically used to represent some kind of composite type (a list or a hash), and the lowercase letter is used to represent an element of that composite type. Some internals code makes use of this case relationship. However, 'v' and 'V' (vec and v-string) are in no way related.

The PERL_MAGIC_ext and PERL_MAGIC_uvar magic types are defined specifically for use by extensions and will not be used by perl itself. Extensions can use PERL_MAGIC_ext magic to 'attach' private information to variables (typically objects). This is especially useful because there is no way for normal perl code to corrupt this private information (unlike using extra elements of a hash object).

Similarly, PERL_MAGIC_uvar magic can be used much like tie() to call a C function any time a scalar's value is used or changed. The MAGIC's mg_ptr field points to a ufuncs structure:

    struct ufuncs {
        I32 (*uf_val)(pTHX_ IV, SV*);
        I32 (*uf_set)(pTHX_ IV, SV*);
        IV uf_index;
    };

When the SV is read from or written to, the uf_val or uf_set function will be called with uf_index as the first arg and a pointer to the SV as the second. A simple example of how to add PERL_MAGIC_uvar magic is shown below. Note that the ufuncs structure is copied by sv_magic, so you can safely allocate it on the stack.

    void
    Umagic(sv)
        SV *sv;
    PREINIT:
        struct ufuncs uf;
    CODE:
        uf.uf_val   = &my_get_fn;
        uf.uf_set   = &my_set_fn;
        uf.uf_index = 0;
        sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));

Note that because multiple extensions may be using PERL_MAGIC_ext or PERL_MAGIC_uvar magic, it is important for extensions to take extra care to avoid conflict. Typically only using the magic on objects blessed into the same class as the extension is sufficient. For PERL_MAGIC_ext magic, it may also be appropriate to add an I32 'signature' at the top of the private data area and check that.

Also note that the sv_set*() and sv_cat*() functions described earlier do not invoke 'set' magic on their targets. This must be done by the user either by calling the SvSETMAGIC() macro after calling these functions, or by using one of the sv_set*_mg() or sv_cat*_mg() functions. Similarly, generic C code must call the SvGETMAGIC() macro to invoke any 'get' magic if they use an SV obtained from external sources in functions that don't handle magic. See the perlapi manpage for a description of these functions. For example, calls to the sv_cat*() functions typically need to be followed by SvSETMAGIC(), but they don't need a prior SvGETMAGIC() since their implementation handles 'get' magic.

Finding Magic

    MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */

This routine returns a pointer to the MAGIC structure stored in the SV. If the SV does not have that magical feature, NULL is returned. Also, if the SV is not of type SVt_PVMG, Perl may core dump.

    int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);

This routine checks to see what types of magic sv has. If the mg_type field is an uppercase letter, then the mg_obj is copied to nsv, but the mg_type field is changed to be the lowercase letter.

Understanding the Magic of Tied Hashes and Arrays

Tied hashes and arrays are magical beasts of the PERL_MAGIC_tied magic type.

WARNING: As of the 5.004 release, proper usage of the array and hash access functions requires understanding a few caveats. Some of these caveats are actually considered bugs in the API, to be fixed in later releases, and are bracketed with [MAYCHANGE] below. If you find yourself actually applying such information in this section, be aware that the behavior may change in the future, umm, without warning.

The perl tie function associates a variable with an object that implements the various GET, SET, etc methods. To perform the equivalent of the perl tie function from an XSUB, you must mimic this behaviour. The code below carries out the necessary steps - firstly it creates a new hash, and then creates a second hash which it blesses into the class which will implement the tie methods. Lastly it ties the two hashes together, and returns a reference to the new tied hash. Note that the code below does NOT call the TIEHASH method in the MyTie class - see Calling Perl Routines from within C Programs for details on how to do this.

    SV*
    mytie()
    PREINIT:
        HV *hash;
        HV *stash;
        SV *tie;
    CODE:
        hash = newHV();
        tie = newRV_noinc((SV*)newHV());
        stash = gv_stashpv("MyTie", TRUE);
        sv_bless(tie, stash);
        hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
        RETVAL = newRV_noinc(hash);
    OUTPUT:
        RETVAL

The av_store function, when given a tied array argument, merely copies the magic of the array onto the value to be "stored", using mg_copy. It may also return NULL, indicating that the value did not actually need to be stored in the array. [MAYCHANGE] After a call to av_store on a tied array, the caller will usually need to call mg_set(val) to actually invoke the perl level "STORE" method on the TIEARRAY object. If av_store did return NULL, a call to SvREFCNT_dec(val) will also be usually necessary to avoid a memory leak. [/MAYCHANGE]

The previous paragraph is applicable verbatim to tied hash access using the hv_store and hv_store_ent functions as well.

av_fetch and the corresponding hash functions hv_fetch and hv_fetch_ent actually return an undefined mortal value whose magic has been initialized using mg_copy. Note the value so returned does not need to be deallocated, as it is already mortal. [MAYCHANGE] But you will need to call mg_get() on the returned value in order to actually invoke the perl level "FETCH" method on the underlying TIE object. Similarly, you may also call mg_set() on the return value after possibly assigning a suitable value to it using sv_setsv, which will invoke the "STORE" method on the TIE object. [/MAYCHANGE]

[MAYCHANGE] In other words, the array or hash fetch/store functions don't really fetch and store actual values in the case of tied arrays and hashes. They merely call mg_copy to attach magic to the values that were meant to be "stored" or "fetched". Later calls to mg_get and mg_set actually do the job of invoking the TIE methods on the underlying objects. Thus the magic mechanism currently implements a kind of lazy access to arrays and hashes.

Currently (as of perl version 5.004), use of the hash and array access functions requires the user to be aware of whether they are operating on "normal" hashes and arrays, or on their tied variants. The API may be changed to provide more transparent access to both tied and normal data types in future versions. [/MAYCHANGE]

You would do well to understand that the TIEARRAY and TIEHASH interfaces are mere sugar to invoke some perl method calls while using the uniform hash and array syntax. The use of this sugar imposes some overhead (typically about two to four extra opcodes per FETCH/STORE operation, in addition to the creation of all the mortal variables required to invoke the methods). This overhead will be comparatively small if the TIE methods are themselves substantial, but if they are only a few statements long, the overhead will not be insignificant.

Localizing changes

Perl has a very handy construction

  {
    local $var = 2;
    ...
  }

This construction is approximately equivalent to

  {
    my $oldvar = $var;
    $var = 2;
    ...
    $var = $oldvar;
  }

The biggest difference is that the first construction would reinstate the initial value of $var, irrespective of how control exits the block: goto, return, die/eval, etc. It is a little bit more efficient as well.

There is a way to achieve a similar task from C via Perl API: create a pseudo-block, and arrange for some changes to be automatically undone at the end of it, either explicit, or via a non-local exit (via die()). A block-like construct is created by a pair of ENTER/LEAVE macros (see Returning a Scalar in the perlcall manpage). Such a construct may be created specially for some important localized task, or an existing one (like boundaries of enclosing Perl subroutine/block, or an existing pair for freeing TMPs) may be used. (In the second case the overhead of additional localization must be almost negligible.) Note that any XSUB is automatically enclosed in an ENTER/LEAVE pair.

Inside such a pseudo-block the following service is available:

SAVEINT(int i)
SAVEIV(IV i)
SAVEI32(I32 i)
SAVELONG(long i)

These macros arrange things to restore the value of integer variable i at the end of enclosing pseudo-block.

SAVESPTR(s)
SAVEPPTR(p)

These macros arrange things to restore the value of pointers s and p. s must be a pointer of a type which survives conversion to SV* and back, p should be able to survive conversion to char* and back.

SAVEFREESV(SV *sv)

The refcount of sv would be decremented at the end of pseudo-block. This is similar to sv_2mortal in that it is also a mechanism for doing a delayed SvREFCNT_dec. However, while sv_2mortal extends the lifetime of sv until the beginning of the next statement, SAVEFREESV extends it until the end of the enclosing scope. These lifetimes can be wildly different.

Also compare SAVEMORTALIZESV.

SAVEMORTALIZESV(SV *sv)

Just like SAVEFREESV, but mortalizes sv at the end of the current scope instead of decrementing its reference count. This usually has the effect of keeping sv alive until the statement that called the currently live scope has finished executing.

SAVEFREEOP(OP *op)

The OP * is op_free()ed at the end of pseudo-block.

SAVEFREEPV(p)

The chunk of memory which is pointed to by p is Safefree()ed at the end of pseudo-block.

SAVECLEARSV(SV *sv)

Clears a slot in the current scratchpad which corresponds to sv at the end of pseudo-block.

SAVEDELETE(HV *hv, char *key, I32 length)

The key key of hv is deleted at the end of pseudo-block. The string pointed to by key is Safefree()ed. If one has a key in short-lived storage, the corresponding string may be reallocated like this:

  SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)

At the end of pseudo-block the function f is called with the only argument p.

SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)

At the end of pseudo-block the function f is called with the implicit context argument (if any), and p.

SAVESTACK_POS()

The current offset on the Perl internal stack (cf. SP) is restored at the end of pseudo-block.

The following API list contains functions, thus one needs to provide pointers to the modifiable data explicitly (either C pointers, or Perlish GV *s). Where the above macros take int, a similar function takes int *.

SV* save_scalar(GV *gv)

Equivalent to Perl code local $gv.

AV* save_ary(GV *gv)
HV* save_hash(GV *gv)

Similar to save_scalar, but localize @gv and %gv.

void save_item(SV *item)

Duplicates the current value of SV, on the exit from the current ENTER/LEAVE pseudo-block will restore the value of SV using the stored value.

void save_list(SV **sarg, I32 maxsarg)

A variant of save_item which takes multiple arguments via an array sarg of SV* of length maxsarg.

SV* save_svref(SV **sptr)

Similar to save_scalar, but will reinstate an SV *.

void save_aptr(AV **aptr)
void save_hptr(HV **hptr)

Similar to save_svref, but localize AV * and HV *.

The Alias module implements localization of the basic types within the caller's scope. People who are interested in how to localize things in the containing scope should take a look there too.

Subroutines

XSUBs and the Argument Stack

The XSUB mechanism is a simple way for Perl programs to access C subroutines. An XSUB routine will have a stack that contains the arguments from the Perl program, and a way to map from the Perl data structures to a C equivalent.

The stack arguments are accessible through the ST(n) macro, which returns the n'th stack argument. Argument 0 is the first argument passed in the Perl subroutine call. These arguments are SV*, and can be used anywhere an SV* is used.

Most of the time, output from the C routine can be handled through use of the RETVAL and OUTPUT directives. However, there are some cases where the argument stack is not already long enough to handle all the return values. An example is the POSIX tzname() call, which takes no arguments, but returns two, the local time zone's standard and summer time abbreviations.

To handle this situation, the PPCODE directive is used and the stack is extended using the macro:

    EXTEND(SP, num);

where SP is the macro that represents the local copy of the stack pointer, and num is the number of elements the stack should be extended by.

Now that there is room on the stack, values can be pushed on it using PUSHs macro. The pushed values will often need to be "mortal" (See Reference Counts and Mortality):

    PUSHs(sv_2mortal(newSViv(an_integer)))
    PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
    PUSHs(sv_2mortal(newSVnv(a_double)))
    PUSHs(sv_2mortal(newSVpv("Some String",0)))

And now the Perl program calling tzname, the two values will be assigned as in:

    ($standard_abbrev, $summer_abbrev) = POSIX::tzname;

An alternate (and possibly simpler) method to pushing values on the stack is to use the macro:

    XPUSHs(SV*)

This macro automatically adjust the stack for you, if needed. Thus, you do not need to call EXTEND to extend the stack.

Despite their suggestions in earlier versions of this document the macros (X)PUSH[iunp] are not suited to XSUBs which return multiple results. For that, either stick to the (X)PUSHs macros shown above, or use the new m(X)PUSH[iunp] macros instead; see Putting a C value on Perl stack.

For more information, consult the perlxs manpage and the perlxstut manpage.

Calling Perl Routines from within C Programs

There are four routines that can be used to call a Perl subroutine from within a C program. These four are:

    I32  call_sv(SV*, I32);
    I32  call_pv(const char*, I32);
    I32  call_method(const char*, I32);
    I32  call_argv(const char*, I32, register char**);

The routine most often used is call_sv. The SV* argument contains either the name of the Perl subroutine to be called, or a reference to the subroutine. The second argument consists of flags that control the context in which the subroutine is called, whether or not the subroutine is being passed arguments, how errors should be trapped, and how to treat return values.

All four routines return the number of arguments that the subroutine returned on the Perl stack.

These routines used to be called perl_call_sv, etc., before Perl v5.6.0, but those names are now deprecated; macros of the same name are provided for compatibility.

When using any of these routines (except call_argv), the programmer must manipulate the Perl stack. These include the following macros and functions:

    dSP
    SP
    PUSHMARK()
    PUTBACK
    SPAGAIN
    ENTER
    SAVETMPS
    FREETMPS
    LEAVE
    XPUSH*()
    POP*()

For a detailed description of calling conventions from C to Perl, consult the perlcall manpage.

Memory Allocation

Allocation

All memory meant to be used with the Perl API functions should be manipulated using the macros described in this section. The macros provide the necessary transparency between differences in the actual malloc implementation that is used within perl.

It is suggested that you enable the version of malloc that is distributed with Perl. It keeps pools of various sizes of unallocated memory in order to satisfy allocation requests more quickly. However, on some platforms, it may cause spurious malloc or free errors.

The following three macros are used to initially allocate memory :

    Newx(pointer, number, type);
    Newxc(pointer, number, type, cast);
    Newxz(pointer, number, type);

The first argument pointer should be the name of a variable that will point to the newly allocated memory.

The second and third arguments number and type specify how many of the specified type of data structure should be allocated. The argument type is passed to sizeof. The final argument to Newxc, cast, should be used if the pointer argument is different from the type argument.

Unlike the Newx and Newxc macros, the Newxz macro calls memzero to zero out all the newly allocated memory.

Reallocation

    Renew(pointer, number, type);
    Renewc(pointer, number, type, cast);
    Safefree(pointer)

These three macros are used to change a memory buffer size or to free a piece of memory no longer needed. The arguments to Renew and Renewc match those of New and Newc with the exception of not needing the "magic cookie" argument.

Moving

    Move(source, dest, number, type);
    Copy(source, dest, number, type);
    Zero(dest, number, type);

These three macros are used to move, copy, or zero out previously allocated memory. The source and dest arguments point to the source and destination starting points. Perl will move, copy, or zero out number instances of the size of the type data structure (using the sizeof function).

PerlIO

The most recent development releases of Perl has been experimenting with removing Perl's dependency on the "normal" standard I/O suite and allowing other stdio implementations to be used. This involves creating a new abstraction layer that then calls whichever implementation of stdio Perl was compiled with. All XSUBs should now use the functions in the PerlIO abstraction layer and not make any assumptions about what kind of stdio is being used.

For a complete description of the PerlIO abstraction, consult the perlapio manpage.

Putting a C value on Perl stack

A lot of opcodes (this is an elementary operation in the internal perl stack machine) put an SV* on the stack. However, as an optimization the corresponding SV is (usually) not recreated each time. The opcodes reuse specially assigned SVs (targets) which are (as a corollary) not constantly freed/created.

Each of the targets is created only once (but see Scratchpads and recursion below), and when an opcode needs to put an integer, a double, or a string on stack, it just sets the corresponding parts of its target and puts the target on stack.

The macro to put this target on stack is PUSHTARG, and it is directly used in some opcodes, as well as indirectly in zillions of others, which use it via (X)PUSH[iunp].

Because the target is reused, you must be careful when pushing multiple values on the stack. The following code will not do what you think:

    XPUSHi(10);
    XPUSHi(20);

This translates as "set TARG to 10, push a pointer to TARG onto the stack; set TARG to 20, push a pointer to TARG onto the stack". At the end of the operation, the stack does not contain the values 10 and 20, but actually contains two pointers to TARG, which we have set to 20.

If you need to push multiple different values then you should either use the (X)PUSHs macros, or else use the new m(X)PUSH[iunp] macros, none of which make use of TARG. The (X)PUSHs macros simply push an SV* on the stack, which, as noted under XSUBs and the Argument Stack, will often need to be "mortal". The new m(X)PUSH[iunp] macros make this a little easier to achieve by creating a new mortal for you (via (X)PUSHmortal), pushing that onto the stack (extending it if necessary in the case of the mXPUSH[iunp] macros), and then setting its value. Thus, instead of writing this to "fix" the example above:

    XPUSHs(sv_2mortal(newSViv(10)))
    XPUSHs(sv_2mortal(newSViv(20)))

you can simply write:

    mXPUSHi(10)
    mXPUSHi(20)

On a related note, if you do use (X)PUSH[iunp], then you're going to need a dTARG in your variable declarations so that the *PUSH* macros can make use of the local variable TARG. See also dTARGET and dXSTARG.

Scratchpads

The question remains on when the SVs which are targets for opcodes are created. The answer is that they are created when the current unit -- a subroutine or a file (for opcodes for statements outside of subroutines) -- is compiled. During this time a special anonymous Perl array is created, which is called a scratchpad for the current unit.

A scratchpad keeps SVs which are lexicals for the current unit and are targets for opcodes. One can deduce that an SV lives on a scratchpad by looking on its flags: lexicals have SVs_PADMY set, and targets have SVs_PADTMP set.

The correspondence between OPs and targets is not 1-to-1. Different OPs in the compile tree of the unit can use the same target, if this would not conflict with the expected life of the temporary.

Scratchpads and recursion

In fact it is not 100% true that a compiled unit contains a pointer to the scratchpad AV. In fact it contains a pointer to an AV of (initially) one element, and this element is the scratchpad AV. Why do we need an extra level of indirection?

The answer is recursion, and maybe threads. Both these can create several execution pointers going into the same subroutine. For the subroutine-child not write over the temporaries for the subroutine-parent (lifespan of which covers the call to the child), the parent and the child should have different scratchpads. (And the lexicals should be separate anyway!)

So each subroutine is born with an array of scratchpads (of length 1). On each entry to the subroutine it is checked that the current depth of the recursion is not more than the length of this array, and if it is, new scratchpad is created and pushed into the array.

The targets on this scratchpad are undefs, but they are already marked with correct flags.

Compiled code

Code tree

Here we describe the internal form your code is converted to by Perl. Start with a simple example:

  $a = $b + $c;

This is converted to a tree similar to this one:

             assign-to
           /           \
          +             $a
        /   \
      $b     $c

(but slightly more complicated). This tree reflects the way Perl parsed your code, but has nothing to do with the execution order. There is an additional "thread" going through the nodes of the tree which shows the order of execution of the nodes. In our simplified example above it looks like:

     $b ---> $c ---> + ---> $a ---> assign-to

But with the actual compile tree for $a = $b + $c it is different: some nodes optimized away. As a corollary, though the actual tree contains more nodes than our simplified example, the execution order is the same as in our example.

Examining the tree

If you have your perl compiled for debugging (usually done with -DDEBUGGING on the Configure command line), you may examine the compiled tree by specifying -Dx on the Perl command line. The output takes several lines per node, and for $b+$c it looks like this:

    5           TYPE = add  ===> 6
                TARG = 1
                FLAGS = (SCALAR,KIDS)
                {
                    TYPE = null  ===> (4)
                      (was rv2sv)
                    FLAGS = (SCALAR,KIDS)
                    {
    3                   TYPE = gvsv  ===> 4
                        FLAGS = (SCALAR)
                        GV = main::b
                    }
                }
                {
                    TYPE = null  ===> (5)
                      (was rv2sv)
                    FLAGS = (SCALAR,KIDS)
                    {
    4                   TYPE = gvsv  ===> 5
                        FLAGS = (SCALAR)
                        GV = main::c
                    }
                }

This tree has 5 nodes (one per TYPE specifier), only 3 of them are not optimized away (one per number in the left column). The immediate children of the given node correspond to {} pairs on the same level of indentation, thus this listing corresponds to the tree:

                   add
                 /     \
               null    null
                |       |
               gvsv    gvsv

The execution order is indicated by ===> marks, thus it is 3 4 5 6 (node 6 is not included into above listing), i.e., gvsv gvsv add whatever.

Each of these nodes represents an op, a fundamental operation inside the Perl core. The code which implements each operation can be found in the pp*.c files; the function which implements the op with type gvsv is pp_gvsv, and so on. As the tree above shows, different ops have different numbers of children: add is a binary operator, as one would expect, and so has two children. To accommodate the various different numbers of children, there are various types of op data structure, and they link together in different ways.

The simplest type of op structure is OP: this has no children. Unary operators, UNOPs, have one child, and this is pointed to by the op_first field. Binary operators (BINOPs) have not only an op_first field but also an op_last field. The most complex type of op is a LISTOP, which has any number of children. In this case, the first child is pointed to by op_first and the last child by op_last. The children in between can be found by iteratively following the op_sibling pointer from the first child to the last.

There are also two other op types: a PMOP holds a regular expression, and has no children, and a LOOP may or may not have children. If the op_children field is non-zero, it behaves like a LISTOP. To complicate matters, if a UNOP is actually a null op after optimization (see Compile pass 2: context propagation) it will still have children in accordance with its former type.

Another way to examine the tree is to use a compiler back-end module, such as the B::Concise manpage.

Compile pass 1: check routines

The tree is created by the compiler while yacc code feeds it the constructions it recognizes. Since yacc works bottom-up, so does the first pass of perl compilation.

What makes this pass interesting for perl developers is that some optimization may be performed on this pass. This is optimization by so-called "check routines". The correspondence between node names and corresponding check routines is described in opcode.pl (do not forget to run make regen_headers if you modify this file).

A check routine is called when the node is fully constructed except for the execution-order thread. Since at this time there are no back-links to the currently constructed node, one can do most any operation to the top-level node, including freeing it and/or creating new nodes above/below it.

The check routine returns the node which should be inserted into the tree (if the top-level node was not modified, check routine returns its argument).

By convention, check routines have names ck_*. They are usually called from new*OP subroutines (or convert) (which in turn are called from perly.y).

Compile pass 1a: constant folding

Immediately after the check routine is called the returned node is checked for being compile-time executable. If it is (the value is judged to be constant) it is immediately executed, and a constant node with the "return value" of the corresponding subtree is substituted instead. The subtree is deleted.

If constant folding was not performed, the execution-order thread is created.

Compile pass 2: context propagation

When a context for a part of compile tree is known, it is propagated down through the tree. At this time the context can have 5 values (instead of 2 for runtime context): void, boolean, scalar, list, and lvalue. In contrast with the pass 1 this pass is processed from top to bottom: a node's context determines the context for its children.

Additional context-dependent optimizations are performed at this time. Since at this moment the compile tree contains back-references (via "thread" pointers), nodes cannot be free()d now. To allow optimized-away nodes at this stage, such nodes are null()ified instead of free()ing (i.e. their type is changed to OP_NULL).

Compile pass 3: peephole optimization

After the compile tree for a subroutine (or for an eval or a file) is created, an additional pass over the code is performed. This pass is neither top-down or bottom-up, but in the execution order (with additional complications for conditionals). These optimizations are done in the subroutine peep(). Optimizations performed at this stage are subject to the same restrictions as in the pass 2.

Pluggable runops

The compile tree is executed in a runops function. There are two runops functions, in run.c and in dump.c. Perl_runops_debug is used with DEBUGGING and Perl_runops_standard is used otherwise. For fine control over the execution of the compile tree it is possible to provide your own runops function.

It's probably best to copy one of the existing runops functions and change it to suit your needs. Then, in the BOOT section of your XS file, add the line:

  PL_runops = my_runops;

This function should be as efficient as possible to keep your programs running as fast as possible.

Examining internal data structures with the dump functions

To aid debugging, the source file dump.c contains a number of functions which produce formatted output of internal data structures.

The most commonly used of these functions is Perl_sv_dump; it's used for dumping SVs, AVs, HVs, and CVs. The Devel::Peek module calls sv_dump to produce debugging output from Perl-space, so users of that module should already be familiar with its format.

Perl_op_dump can be used to dump an OP structure or any of its derivatives, and produces output similar to perl -Dx; in fact, Perl_dump_eval will dump the main root of the code being evaluated, exactly like -Dx.

Other useful functions are Perl_dump_sub, which turns a GV into an op tree, Perl_dump_packsubs which calls Perl_dump_sub on all the subroutines in a package like so: (Thankfully, these are all xsubs, so there is no op tree)

    (gdb) print Perl_dump_packsubs(PL_defstash)
    SUB attributes::bootstrap = (xsub 0x811fedc 0)
    SUB UNIVERSAL::can = (xsub 0x811f50c 0)
    SUB UNIVERSAL::isa = (xsub 0x811f304 0)
    SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0)
    SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0)

and Perl_dump_all, which dumps all the subroutines in the stash and the op tree of the main root.

How multiple interpreters and concurrency are supported

Background and PERL_IMPLICIT_CONTEXT

The Perl interpreter can be regarded as a closed box: it has an API for feeding it code or otherwise making it do things, but it also has functions for its own use. This smells a lot like an object, and there are ways for you to build Perl so that you can have multiple interpreters, with one interpreter represented either as a C structure, or inside a thread-specific structure. These structures contain all the context, the state of that interpreter.

Two macros control the major Perl build flavors: MULTIPLICITY and USE_5005THREADS. The MULTIPLICITY build has a C structure that packages all the interpreter state, and there is a similar thread-specific data structure under USE_5005THREADS. In both cases, PERL_IMPLICIT_CONTEXT is also normally defined, and enables the support for passing in a "hidden" first argument that represents all three data structures.

All this obviously requires a way for the Perl internal functions to be either subroutines taking some kind of structure as the first argument, or subroutines taking nothing as the first argument. To enable these two very different ways of building the interpreter, the Perl source (as it does in so many other situations) makes heavy use of macros and subroutine naming conventions.

First problem: deciding which functions will be public API functions and which will be private. All functions whose names begin S_ are private (think "S" for "secret" or "static"). All other functions begin with "Perl_", but just because a function begins with "Perl_" does not mean it is part of the API. (See Internal Functions.) The easiest way to be sure a function is part of the API is to find its entry in the perlapi manpage. If it exists in the perlapi manpage, it's part of the API. If it doesn't, and you think it should be (i.e., you need it for your extension), send mail via perlbug explaining why you think it should be.

Second problem: there must be a syntax so that the same subroutine declarations and calls can pass a structure as their first argument, or pass nothing. To solve this, the subroutines are named and declared in a particular way. Here's a typical start of a static function used within the Perl guts:

  STATIC void
  S_incline(pTHX_ char *s)

STATIC becomes "static" in C, and may be #define'd to nothing in some configurations in future.

A public function (i.e. part of the internal API, but not necessarily sanctioned for use in extensions) begins like this:

  void
  Perl_sv_setiv(pTHX_ SV* dsv, IV num)

pTHX_ is one of a number of macros (in perl.h) that hide the details of the interpreter's context. THX stands for "thread", "this", or "thingy", as the case may be. (And no, George Lucas is not involved. :-) The first character could be 'p' for a prototype, 'a' for argument, or 'd' for declaration, so we have pTHX, aTHX and dTHX, and their variants.

When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is no first argument containing the interpreter's context. The trailing underscore in the pTHX_ macro indicates that the macro expansion needs a comma after the context argument because other arguments follow it. If PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the subroutine is not prototyped to take the extra argument. The form of the macro without the trailing underscore is used when there are no additional explicit arguments.

When a core function calls another, it must pass the context. This is normally hidden via macros. Consider sv_setiv. It expands into something like this:

    #ifdef PERL_IMPLICIT_CONTEXT
      #define sv_setiv(a,b)      Perl_sv_setiv(aTHX_ a, b)
      /* can't do this for vararg functions, see below */
    #else
      #define sv_setiv           Perl_sv_setiv
    #endif

This works well, and means that XS authors can gleefully write:

    sv_setiv(foo, bar);

and still have it work under all the modes Perl could have been compiled with.

This doesn't work so cleanly for varargs functions, though, as macros imply that the number of arguments is known in advance. Instead we either need to spell them out fully, passing aTHX_ as the first argument (the Perl core tends to do this with functions like Perl_warner), or use a context-free version.

The context-free version of Perl_warner is called Perl_warner_nocontext, and does not take the extra argument. Instead it does dTHX; to get the context from thread-local storage. We #define warner Perl_warner_nocontext so that extensions get source compatibility at the expense of performance. (Passing an arg is cheaper than grabbing it from thread-local storage.)

You can ignore [pad]THXx when browsing the Perl headers/sources. Those are strictly for use within the core. Extensions and embedders need only be aware of [pad]THX.

So what happened to dTHR?

dTHR was introduced in perl 5.005 to support the older thread model. The older thread model now uses the THX mechanism to pass context pointers around, so dTHR is not useful any more. Perl 5.6.0 and later still have it for backward source compatibility, but it is defined to be a no-op.

How do I use all this in extensions?

When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call any functions in the Perl API will need to pass the initial context argument somehow. The kicker is that you will need to write it in such a way that the extension still compiles when Perl hasn't been built with PERL_IMPLICIT_CONTEXT enabled.

There are three ways to do this. First, the easy but inefficient way, which is also the default, in order to maintain source compatibility with extensions: whenever XSUB.h is #included, it redefines the aTHX and aTHX_ macros to call a function that will return the context. Thus, something like:

        sv_setiv(sv, num);

in your extension will translate to this when PERL_IMPLICIT_CONTEXT is in effect:

        Perl_sv_setiv(Perl_get_context(), sv, num);

or to this otherwise:

        Perl_sv_setiv(sv, num);

You have to do nothing new in your extension to get this; since the Perl library provides Perl_get_context(), it will all just work.

The second, more efficient way is to use the following template for your Foo.xs:

        #define PERL_NO_GET_CONTEXT     /* we want efficiency */
        #include "EXTERN.h"
        #include "perl.h"
        #include "XSUB.h"

        static my_private_function(int arg1, int arg2);

        static SV *
        my_private_function(int arg1, int arg2)
        {
            dTHX;       /* fetch context */
            ... call many Perl API functions ...
        }

        [... etc ...]
        MODULE = Foo            PACKAGE = Foo
        /* typical XSUB */
        void
        my_xsub(arg)
                int arg
            CODE:
                my_private_function(arg, 10);

Note that the only two changes from the normal way of writing an extension is the addition of a #define PERL_NO_GET_CONTEXT before including the Perl headers, followed by a dTHX; declaration at the start of every function that will call the Perl API. (You'll know which functions need this, because the C compiler will complain that there's an undeclared identifier in those functions.) No changes are needed for the XSUBs themselves, because the XS() macro is correctly defined to pass in the implicit context if needed.

The third, even more efficient way is to ape how it is done within the Perl guts:

        #define PERL_NO_GET_CONTEXT     /* we want efficiency */
        #include "EXTERN.h"
        #include "perl.h"
        #include "XSUB.h"

        /* pTHX_ only needed for functions that call Perl API */
        static my_private_function(pTHX_ int arg1, int arg2);

        static SV *
        my_private_function(pTHX_ int arg1, int arg2)
        {
            /* dTHX; not needed here, because THX is an argument */
            ... call Perl API functions ...
        }

        [... etc ...]
        MODULE = Foo            PACKAGE = Foo
        /* typical XSUB */
        void
        my_xsub(arg)
                int arg
            CODE:
                my_private_function(aTHX_ arg, 10);

This implementation never has to fetch the context using a function call, since it is always passed as an extra argument. Depending on your needs for simplicity or efficiency, you may mix the previous two approaches freely.

Never add a comma after pTHX yourself--always use the form of the macro with the underscore for functions that take explicit arguments, or the form without the argument for functions with no explicit arguments.

Should I do anything special if I call perl from multiple threads?

If you create interpreters in one thread and then proceed to call them in another, you need to make sure perl's own Thread Local Storage (TLS) slot is initialized correctly in each of those threads.

The perl_alloc and perl_clone API functions will automatically set the TLS slot to the interpreter they created, so that there is no need to do anything special if the interpreter is always accessed in the same thread that created it, and that thread did not create or call any other interpreters afterwards. If that is not the case, you have to set the TLS slot of the thread before calling any functions in the Perl API on that particular interpreter. This is done by calling the PERL_SET_CONTEXT macro in that thread as the first thing you do:

        /* do this before doing anything else with some_perl */
        PERL_SET_CONTEXT(some_perl);

        ... other Perl API calls on some_perl go here ...

Future Plans and PERL_IMPLICIT_SYS

Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything that the interpreter knows about itself and pass it around, so too are there plans to allow the interpreter to bundle up everything it knows about the environment it's running on. This is enabled with the PERL_IMPLICIT_SYS macro. Currently it only works with USE_ITHREADS and USE_5005THREADS on Windows (see inside iperlsys.h).

This allows the ability to provide an extra pointer (called the "host" environment) for all the system calls. This makes it possible for all the system stuff to maintain their own state, broken down into seven C structures. These are thin wrappers around the usual system calls (see win32/perllib.c) for the default perl executable, but for a more ambitious host (like the one that would do fork() emulation) all the extra work needed to pretend that different interpreters are actually different "processes", would be done here.

The Perl engine/interpreter and the host are orthogonal entities. There could be one or more interpreters in a process, and one or more "hosts", with free association between them.

Internal Functions

All of Perl's internal functions which will be exposed to the outside world are prefixed by Perl_ so that they will not conflict with XS functions or functions used in a program in which Perl is embedded. Similarly, all global variables begin with PL_. (By convention, static functions start with S_.)

Inside the Perl core, you can get at the functions either with or without the Perl_ prefix, thanks to a bunch of defines that live in embed.h. This header file is generated automatically from embed.pl and embed.fnc. embed.pl also creates the prototyping header files for the internal functions, generates the documentation and a lot of other bits and pieces. It's important that when you add a new function to the core or change an existing one, you change the data in the table in embed.fnc as well. Here's a sample entry from that table:

    Apd |SV**   |av_fetch   |AV* ar|I32 key|I32 lval

The second column is the return type, the third column the name. Columns after that are the arguments. The first column is a set of flags:

A

This function is a part of the public API. All such functions should also have 'd', very few do not.

p

This function has a Perl_ prefix; i.e. it is defined as Perl_av_fetch.

d

This function has documentation using the apidoc feature which we'll look at in a second. Some functions have 'd' but not 'A'; docs are good.

Other available flags are:

s

This is a static function and is defined as STATIC S_whatever, and usually called within the sources as whatever(...).

n

This does not need a interpreter context, so the definition has no pTHX, and it follows that callers don't use aTHX. (See Background and PERL_IMPLICIT_CONTEXT in the perlguts manpage.)

r

This function never returns; croak, exit and friends.

f

This function takes a variable number of arguments, printf style. The argument list should end with ..., like this:

    Afprd   |void   |croak          |const char* pat|...
M

This function is part of the experimental development API, and may change or disappear without notice.

o

This function should not have a compatibility macro to define, say, Perl_parse to parse. It must be called as Perl_parse.

x

This function isn't exported out of the Perl core.

m

This is implemented as a macro.

X

This function is explicitly exported.

E

This function is visible to extensions included in the Perl core.

b

Binary backward compatibility; this function is a macro but also has a Perl_ implementation (which is exported).

others

See the comments at the top of embed.fnc for others.

If you edit embed.pl or embed.fnc, you will need to run make regen_headers to force a rebuild of embed.h and other auto-generated files.

Formatted Printing of IVs, UVs, and NVs

If you are printing IVs, UVs, or NVS instead of the stdio(3) style formatting codes like %d, %ld, %f, you should use the following macros for portability

        IVdf            IV in decimal
        UVuf            UV in decimal
        UVof            UV in octal
        UVxf            UV in hexadecimal
        NVef            NV %e-like
        NVff            NV %f-like
        NVgf            NV %g-like

These will take care of 64-bit integers and long doubles. For example:

        printf("IV is %"IVdf"\n", iv);

The IVdf will expand to whatever is the correct format for the IVs.

If you are printing addresses of pointers, use UVxf combined with PTR2UV(), do not use %lx or %p.

Pointer-To-Integer and Integer-To-Pointer

Because pointer size does not necessarily equal integer size, use the follow macros to do it right.

        PTR2UV(pointer)
        PTR2IV(pointer)
        PTR2NV(pointer)
        INT2PTR(pointertotype, integer)

For example:

        IV  iv = ...;
        SV *sv = INT2PTR(SV*, iv);

and

        AV *av = ...;
        UV  uv = PTR2UV(av);

Source Documentation

There's an effort going on to document the internal functions and automatically produce reference manuals from them - the perlapi manpage is one such manual which details all the functions which are available to XS writers. the perlintern manpage is the autogenerated manual for the functions which are not part of the API and are supposedly for internal use only.

Source documentation is created by putting POD comments into the C source, like this:

 /*
 =for apidoc sv_setiv
 Copies an integer into the given SV.  Does not handle 'set' magic.  See
 C<sv_setiv_mg>.
 =cut
 */

Please try and supply some documentation if you add functions to the Perl core.

Backwards compatibility

The Perl API changes over time. New functions are added or the interfaces of existing functions are changed. The Devel::PPPort module tries to provide compatibility code for some of these changes, so XS writers don't have to code it themselves when supporting multiple versions of Perl.

Devel::PPPort generates a C header file ppport.h that can also be run as a Perl script. To generate ppport.h, run:

    perl -MDevel::PPPort -eDevel::PPPort::WriteFile

Besides checking existing XS code, the script can also be used to retrieve compatibility information for various API calls using the --api-info command line switch. For example:

  % perl ppport.h --api-info=sv_magicext

For details, see perldoc ppport.h.

Unicode Support

Perl 5.6.0 introduced Unicode support. It's important for porters and XS writers to understand this support and make sure that the code they write does not corrupt Unicode data.

What is Unicode, anyway?

In the olden, less enlightened times, we all used to use ASCII. Most of us did, anyway. The big problem with ASCII is that it's American. Well, no, that's not actually the problem; the problem is that it's not particularly useful for people who don't use the Roman alphabet. What used to happen was that particular languages would stick their own alphabet in the upper range of the sequence, between 128 and 255. Of course, we then ended up with plenty of variants that weren't quite ASCII, and the whole point of it being a standard was lost.

Worse still, if you've got a language like Chinese or Japanese that has hundreds or thousands of characters, then you really can't fit them into a mere 256, so they had to forget about ASCII altogether, and build their own systems using pairs of numbers to refer to one character.

To fix this, some people formed Unicode, Inc. and produced a new character set containing all the characters you can possibly think of and more. There are several ways of representing these characters, and the one Perl uses is called UTF-8. UTF-8 uses a variable number of bytes to represent a character, instead of just one. You can learn more about Unicode at http://www.unicode.org/

How can I recognise a UTF-8 string?

You can't. This is because UTF-8 data is stored in bytes just like non-UTF-8 data. The Unicode character 200, (0xC8 for you hex types) capital E with a grave accent, is represented by the two bytes v196.172. Unfortunately, the non-Unicode string chr(196).chr(172) has that byte sequence as well. So you can't tell just by looking - this is what makes Unicode input an interesting problem.

The API function is_utf8_string can help; it'll tell you if a string contains only valid UTF-8 characters. However, it can't do the work for you. On a character-by-character basis, is_utf8_char will tell you whether the current character in a string is valid UTF-8.

How does UTF-8 represent Unicode characters?

As mentioned above, UTF-8 uses a variable number of bytes to store a character. Characters with values 1...128 are stored in one byte, just like good ol' ASCII. Character 129 is stored as v194.129; this continues up to character 191, which is v194.191. Now we've run out of bits (191 is binary 10111111) so we move on; 192 is v195.128. And so it goes on, moving to three bytes at character 2048.

Assuming you know you're dealing with a UTF-8 string, you can find out how long the first character in it is with the UTF8SKIP macro:

    char *utf = "\305\233\340\240\201";
    I32 len;

    len = UTF8SKIP(utf); /* len is 2 here */
    utf += len;
    len = UTF8SKIP(utf); /* len is 3 here */

Another way to skip over characters in a UTF-8 string is to use utf8_hop, which takes a string and a number of characters to skip over. You're on your own about bounds checking, though, so don't use it lightly.

All bytes in a multi-byte UTF-8 character will have the high bit set, so you can test if you need to do something special with this character like this (the UTF8_IS_INVARIANT() is a macro that tests whether the byte can be encoded as a single byte even in UTF-8):

    U8 *utf;
    UV uv;      /* Note: a UV, not a U8, not a char */

    if (!UTF8_IS_INVARIANT(*utf))
        /* Must treat this as UTF-8 */
        uv = utf8_to_uv(utf);
    else
        /* OK to treat this character as a byte */
        uv = *utf;

You can also see in that example that we use utf8_to_uv to get the value of the character; the inverse function uv_to_utf8 is available for putting a UV into UTF-8:

    if (!UTF8_IS_INVARIANT(uv))
        /* Must treat this as UTF8 */
        utf8 = uv_to_utf8(utf8, uv);
    else
        /* OK to treat this character as a byte */
        *utf8++ = uv;

You must convert characters to UVs using the above functions if you're ever in a situation where you have to match UTF-8 and non-UTF-8 characters. You may not skip over UTF-8 characters in this case. If you do this, you'll lose the ability to match hi-bit non-UTF-8 characters; for instance, if your UTF-8 string contains v196.172, and you skip that character, you can never match a chr(200) in a non-UTF-8 string. So don't do that!

How does Perl store UTF-8 strings?

Currently, Perl deals with Unicode strings and non-Unicode strings slightly differently. If a string has been identified as being UTF-8 encoded, Perl will set a flag in the SV, SVf_UTF8. You can check and manipulate this flag with the following macros:

    SvUTF8(sv)
    SvUTF8_on(sv)
    SvUTF8_off(sv)

This flag has an important effect on Perl's treatment of the string: if Unicode data is not properly distinguished, regular expressions, length, substr and other string handling operations will have undesirable results.

The problem comes when you have, for instance, a string that isn't flagged is UTF-8, and contains a byte sequence that could be UTF-8 - especially when combining non-UTF-8 and UTF-8 strings.

Never forget that the SVf_UTF8 flag is separate to the PV value; you need be sure you don't accidentally knock it off while you're manipulating SVs. More specifically, you cannot expect to do this:

    SV *sv;
    SV *nsv;
    STRLEN len;
    char *p;

    p = SvPV(sv, len);
    frobnicate(p);
    nsv = newSVpvn(p, len);

The char* string does not tell you the whole story, and you can't copy or reconstruct an SV just by copying the string value. Check if the old SV has the UTF-8 flag set, and act accordingly:

    p = SvPV(sv, len);
    frobnicate(p);
    nsv = newSVpvn(p, len);
    if (SvUTF8(sv))
        SvUTF8_on(nsv);

In fact, your frobnicate function should be made aware of whether or not it's dealing with UTF-8 data, so that it can handle the string appropriately.

Since just passing an SV to an XS function and copying the data of the SV is not enough to copy the UTF-8 flags, even less right is just passing a char * to an XS function.

How do I convert a string to UTF-8?

If you're mixing UTF-8 and non-UTF-8 strings, you might find it necessary to upgrade one of the strings to UTF-8. If you've got an SV, the easiest way to do this is:

    sv_utf8_upgrade(sv);

However, you must not do this, for example:

    if (!SvUTF8(left))
        sv_utf8_upgrade(left);

If you do this in a binary operator, you will actually change one of the strings that came into the operator, and, while it shouldn't be noticeable by the end user, it can cause problems.

Instead, bytes_to_utf8 will give you a UTF-8-encoded copy of its string argument. This is useful for having the data available for comparisons and so on, without harming the original SV. There's also utf8_to_bytes to go the other way, but naturally, this will fail if the string contains any characters above 255 that can't be represented in a single byte.

Is there anything else I need to know?

Not really. Just remember these things:

  • There's no way to tell if a string is UTF-8 or not. You can tell if an SV is UTF-8 by looking at is SvUTF8 flag. Don't forget to set the flag if something should be UTF-8. Treat the flag as part of the PV, even though it's not - if you pass on the PV to somewhere, pass on the flag too.

  • If a string is UTF-8, always use utf8_to_uv to get at the value, unless UTF8_IS_INVARIANT(*s) in which case you can use *s.

  • When writing a character uv to a UTF-8 string, always use uv_to_utf8, unless UTF8_IS_INVARIANT(uv)) in which case you can use *s = uv.

  • Mixing UTF-8 and non-UTF-8 strings is tricky. Use bytes_to_utf8 to get a new string which is UTF-8 encoded. There are tricks you can use to delay deciding whether you need to use a UTF-8 string until you get to a high character - HALF_UPGRADE is one of those.

Custom Operators

Custom operator support is a new experimental feature that allows you to define your own ops. This is primarily to allow the building of interpreters for other languages in the Perl core, but it also allows optimizations through the creation of "macro-ops" (ops which perform the functions of multiple ops which are usually executed together, such as gvsv, gvsv, add.)

This feature is implemented as a new op type, OP_CUSTOM. The Perl core does not "know" anything special about this op type, and so it will not be involved in any optimizations. This also means that you can define your custom ops to be any op structure - unary, binary, list and so on - you like.

It's important to know what custom operators won't do for you. They won't let you add new syntax to Perl, directly. They won't even let you add new keywords, directly. In fact, they won't change the way Perl compiles a program at all. You have to do those changes yourself, after Perl has compiled the program. You do this either by manipulating the op tree using a CHECK block and the B::Generate module, or by adding a custom peephole optimizer with the optimize module.

When you do this, you replace ordinary Perl ops with custom ops by creating ops with the type OP_CUSTOM and the pp_addr of your own PP function. This should be defined in XS code, and should look like the PP ops in pp_*.c. You are responsible for ensuring that your op takes the appropriate number of values from the stack, and you are responsible for adding stack marks if necessary.

You should also "register" your op with the Perl interpreter so that it can produce sensible error and warning messages. Since it is possible to have multiple custom ops within the one "logical" op type OP_CUSTOM, Perl uses the value of o->op_ppaddr as a key into the PL_custom_op_descs and PL_custom_op_names hashes. This means you need to enter a name and description for your op at the appropriate place in the PL_custom_op_names and PL_custom_op_descs hashes.

Forthcoming versions of B::Generate (version 1.0 and above) should directly support the creation of custom ops by name.

AUTHORS

Until May 1997, this document was maintained by Jeff Okamoto <okamoto@corp.hp.com>. It is now maintained as part of Perl itself by the Perl 5 Porters <perl5-porters@perl.org>.

With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen McCamant, and Gurusamy Sarathy.

SEE ALSO

perlapi(1), perlintern(1), perlxs(1), perlembed(1)


perlhack - How to hack at the Perl internals

    • Keeping in sync
    • Why rsync the source tree
    • Why rsync the patches
    • Working with the source
    • Perlbug administration
    • Submitting patches
    • Finding Your Way Around
    • Elements of the interpreter
    • Internal Variable Types
    • Op Trees
    • Stacks
    • Millions of Macros
    • The .i Targets
    • Poking at Perl
    • Using a source-level debugger
    • gdb macro support
    • Dumping Perl Data Structures
    • Patching
    • Patching a core module
    • Adding a new function to the core
    • Writing a test
    • Special Make Test Targets
    • Running tests by hand
      • Using t/harness for testing
  • EXTERNAL TOOLS FOR DEBUGGING PERL
    • Rational Software's Purify
    • Purify on Unix
    • Purify on NT
    • valgrind
    • Compaq's/Digital's/HP's Third Degree
    • PERL_DESTRUCT_LEVEL
    • Profiling
    • Gprof Profiling
    • GCC gcov Profiling
    • Pixie Profiling
    • Miscellaneous tricks
    • CONCLUSION
  • AUTHOR

NAME

perlhack - How to hack at the Perl internals

DESCRIPTION

This document attempts to explain how Perl development takes place, and ends with some suggestions for people wanting to become bona fide porters.

The perl5-porters mailing list is where the Perl standard distribution is maintained and developed. The list can get anywhere from 10 to 150 messages a day, depending on the heatedness of the debate. Most days there are two or three patches, extensions, features, or bugs being discussed at a time.

A searchable archive of the list is at either:

    http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/

or

    http://archive.develooper.com/perl5-porters@perl.org/

List subscribers (the porters themselves) come in several flavours. Some are quiet curious lurkers, who rarely pitch in and instead watch the ongoing development to ensure they're forewarned of new changes or features in Perl. Some are representatives of vendors, who are there to make sure that Perl continues to compile and work on their platforms. Some patch any reported bug that they know how to fix, some are actively patching their pet area (threads, Win32, the regexp engine), while others seem to do nothing but complain. In other words, it's your usual mix of technical people.

Over this group of porters presides Larry Wall. He has the final word in what does and does not change in the Perl language. Various releases of Perl are shepherded by a "pumpking", a porter responsible for gathering patches, deciding on a patch-by-patch, feature-by-feature basis what will and will not go into the release. For instance, Gurusamy Sarathy was the pumpking for the 5.6 release of Perl, and Jarkko Hietaniemi was the pumpking for the 5.8 release, and Rafael Garcia-Suarez holds the pumpking crown for the 5.10 release.

In addition, various people are pumpkings for different things. For instance, Andy Dougherty and Jarkko Hietaniemi did a grand job as the Configure pumpkin up till the 5.8 release. For the 5.10 release H.Merijn Brand took over.

Larry sees Perl development along the lines of the US government: there's the Legislature (the porters), the Executive branch (the pumpkings), and the Supreme Court (Larry). The legislature can discuss and submit patches to the executive branch all they like, but the executive branch is free to veto them. Rarely, the Supreme Court will side with the executive branch over the legislature, or the legislature over the executive branch. Mostly, however, the legislature and the executive branch are supposed to get along and work out their differences without impeachment or court cases.

You might sometimes see reference to Rule 1 and Rule 2. Larry's power as Supreme Court is expressed in The Rules:

  1. Larry is always by definition right about how Perl should behave. This means he has final veto power on the core functionality.

  2. Larry is allowed to change his mind about any matter at a later date, regardless of whether he previously invoked Rule 1.

Got that? Larry is always right, even when he was wrong. It's rare to see either Rule exercised, but they are often alluded to.

New features and extensions to the language are contentious, because the criteria used by the pumpkings, Larry, and other porters to decide which features should be implemented and incorporated are not codified in a few small design goals as with some other languages. Instead, the heuristics are flexible and often difficult to fathom. Here is one person's list, roughly in decreasing order of importance, of heuristics that new features have to be weighed against:

Does concept match the general goals of Perl?

These haven't been written anywhere in stone, but one approximation is:

 1. Keep it fast, simple, and useful.
 2. Keep features/concepts as orthogonal as possible.
 3. No arbitrary limits (platforms, data sizes, cultures).
 4. Keep it open and exciting to use/patch/advocate Perl everywhere.
 5. Either assimilate new technologies, or build bridges to them.
Where is the implementation?

All the talk in the world is useless without an implementation. In almost every case, the person or people who argue for a new feature will be expected to be the ones who implement it. Porters capable of coding new features have their own agendas, and are not available to implement your (possibly good) idea.

Backwards compatibility

It's a cardinal sin to break existing Perl programs. New warnings are contentious--some say that a program that emits warnings is not broken, while others say it is. Adding keywords has the potential to break programs, changing the meaning of existing token sequences or functions might break programs.

Could it be a module instead?

Perl 5 has extension mechanisms, modules and XS, specifically to avoid the need to keep changing the Perl interpreter. You can write modules that export functions, you can give those functions prototypes so they can be called like built-in functions, you can even write XS code to mess with the runtime data structures of the Perl interpreter if you want to implement really complicated things. If it can be done in a module instead of in the core, it's highly unlikely to be added.

Is the feature generic enough?

Is this something that only the submitter wants added to the language, or would it be broadly useful? Sometimes, instead of adding a feature with a tight focus, the porters might decide to wait until someone implements the more generalized feature. For instance, instead of implementing a "delayed evaluation" feature, the porters are waiting for a macro system that would permit delayed evaluation and much more.

Does it potentially introduce new bugs?

Radical rewrites of large chunks of the Perl interpreter have the potential to introduce new bugs. The smaller and more localized the change, the better.

Does it preclude other desirable features?

A patch is likely to be rejected if it closes off future avenues of development. For instance, a patch that placed a true and final interpretation on prototypes is likely to be rejected because there are still options for the future of prototypes that haven't been addressed.

Is the implementation robust?

Good patches (tight code, complete, correct) stand more chance of going in. Sloppy or incorrect patches might be placed on the back burner until the pumpking has time to fix, or might be discarded altogether without further notice.

Is the implementation generic enough to be portable?

The worst patches make use of a system-specific features. It's highly unlikely that nonportable additions to the Perl language will be accepted.

Is the implementation tested?

Patches which change behaviour (fixing bugs or introducing new features) must include regression tests to verify that everything works as expected. Without tests provided by the original author, how can anyone else changing perl in the future be sure that they haven't unwittingly broken the behaviour the patch implements? And without tests, how can the patch's author be confident that his/her hard work put into the patch won't be accidentally thrown away by someone in the future?

Is there enough documentation?

Patches without documentation are probably ill-thought out or incomplete. Nothing can be added without documentation, so submitting a patch for the appropriate manpages as well as the source code is always a good idea.

Is there another way to do it?

Larry said "Although the Perl Slogan is There's More Than One Way to Do It, I hesitate to make 10 ways to do something". This is a tricky heuristic to navigate, though--one man's essential addition is another man's pointless cruft.

Does it create too much work?

Work for the pumpking, work for Perl programmers, work for module authors, ... Perl is supposed to be easy.

Patches speak louder than words

Working code is always preferred to pie-in-the-sky ideas. A patch to add a feature stands a much higher chance of making it to the language than does a random feature request, no matter how fervently argued the request might be. This ties into "Will it be useful?", as the fact that someone took the time to make the patch demonstrates a strong desire for the feature.

If you're on the list, you might hear the word "core" bandied around. It refers to the standard distribution. "Hacking on the core" means you're changing the C source code to the Perl interpreter. "A core module" is one that ships with Perl.

Keeping in sync

The source code to the Perl interpreter, in its different versions, is kept in a repository managed by a revision control system ( which is currently the Perforce program, see http://perforce.com/ ). The pumpkings and a few others have access to the repository to check in changes. Periodically the pumpking for the development version of Perl will release a new version, so the rest of the porters can see what's changed. The current state of the main trunk of repository, and patches that describe the individual changes that have happened since the last public release are available at this location:

    http://public.activestate.com/pub/apc/
    ftp://public.activestate.com/pub/apc/

If you're looking for a particular change, or a change that affected a particular set of files, you may find the Perl Repository Browser useful:

    http://public.activestate.com/cgi-bin/perlbrowse

You may also want to subscribe to the perl5-changes mailing list to receive a copy of each patch that gets submitted to the maintenance and development "branches" of the perl repository. See http://lists.perl.org/ for subscription information.

If you are a member of the perl5-porters mailing list, it is a good thing to keep in touch with the most recent changes. If not only to verify if what you would have posted as a bug report isn't already solved in the most recent available perl development branch, also known as perl-current, bleading edge perl, bleedperl or bleadperl.

Needless to say, the source code in perl-current is usually in a perpetual state of evolution. You should expect it to be very buggy. Do not use it for any purpose other than testing and development.

Keeping in sync with the most recent branch can be done in several ways, but the most convenient and reliable way is using rsync, available at ftp://rsync.samba.org/pub/rsync/ . (You can also get the most recent branch by FTP.)

If you choose to keep in sync using rsync, there are two approaches to doing so:

rsync'ing the source tree

Presuming you are in the directory where your perl source resides and you have rsync installed and available, you can "upgrade" to the bleadperl using:

 # rsync -avz rsync://public.activestate.com/perl-current/ .

This takes care of updating every single item in the source tree to the latest applied patch level, creating files that are new (to your distribution) and setting date/time stamps of existing files to reflect the bleadperl status.

Note that this will not delete any files that were in '.' before the rsync. Once you are sure that the rsync is running correctly, run it with the --delete and the --dry-run options like this:

 # rsync -avz --delete --dry-run rsync://public.activestate.com/perl-current/ .

This will simulate an rsync run that also deletes files not present in the bleadperl master copy. Observe the results from this run closely. If you are sure that the actual run would delete no files precious to you, you could remove the '--dry-run' option.

You can than check what patch was the latest that was applied by looking in the file .patch, which will show the number of the latest patch.

If you have more than one machine to keep in sync, and not all of them have access to the WAN (so you are not able to rsync all the source trees to the real source), there are some ways to get around this problem.

Using rsync over the LAN

Set up a local rsync server which makes the rsynced source tree available to the LAN and sync the other machines against this directory.

From http://rsync.samba.org/README.html :

   "Rsync uses rsh or ssh for communication. It does not need to be
    setuid and requires no special privileges for installation.  It
    does not require an inetd entry or a daemon.  You must, however,
    have a working rsh or ssh system.  Using ssh is recommended for
    its security features."
Using pushing over the NFS

Having the other systems mounted over the NFS, you can take an active pushing approach by checking the just updated tree against the other not-yet synced trees. An example would be

  #!/usr/bin/perl -w

  use strict;
  use File::Copy;

  my %MF = map {
      m/(\S+)/;
      $1 => [ (stat $1)[2, 7, 9] ];     # mode, size, mtime
      } `cat MANIFEST`;

  my %remote = map { $_ => "/$_/pro/3gl/CPAN/perl-5.7.1" } qw(host1 host2);

  foreach my $host (keys %remote) {
      unless (-d $remote{$host}) {
          print STDERR "Cannot Xsync for host $host\n";
          next;
          }
      foreach my $file (keys %MF) {
          my $rfile = "$remote{$host}/$file";
          my ($mode, $size, $mtime) = (stat $rfile)[2, 7, 9];
          defined $size or ($mode, $size, $mtime) = (0, 0, 0);
          $size == $MF{$file}[1] && $mtime == $MF{$file}[2] and next;
          printf "%4s %-34s %8d %9d  %8d %9d\n",
              $host, $file, $MF{$file}[1], $MF{$file}[2], $size, $mtime;
          unlink $rfile;
          copy ($file, $rfile);
          utime time, $MF{$file}[2], $rfile;
          chmod $MF{$file}[0], $rfile;
          }
      }

though this is not perfect. It could be improved with checking file checksums before updating. Not all NFS systems support reliable utime support (when used over the NFS).

rsync'ing the patches

The source tree is maintained by the pumpking who applies patches to the files in the tree. These patches are either created by the pumpking himself using diff -c after updating the file manually or by applying patches sent in by posters on the perl5-porters list. These patches are also saved and rsync'able, so you can apply them yourself to the source files.

Presuming you are in a directory where your patches reside, you can get them in sync with

 # rsync -avz rsync://public.activestate.com/perl-current-diffs/ .

This makes sure the latest available patch is downloaded to your patch directory.

It's then up to you to apply these patches, using something like

 # last=`ls -t *.gz | sed q`
 # rsync -avz rsync://public.activestate.com/perl-current-diffs/ .
 # find . -name '*.gz' -newer $last -exec gzcat {} \; >blead.patch
 # cd ../perl-current
 # patch -p1 -N <../perl-current-diffs/blead.patch

or, since this is only a hint towards how it works, use CPAN-patchaperl from Andreas König to have better control over the patching process.

Why rsync the source tree

It's easier to rsync the source tree

Since you don't have to apply the patches yourself, you are sure all files in the source tree are in the right state.

It's more reliable

While both the rsync-able source and patch areas are automatically updated every few minutes, keep in mind that applying patches may sometimes mean careful hand-holding, especially if your version of the patch program does not understand how to deal with new files, files with 8-bit characters, or files without trailing newlines.

Why rsync the patches

It's easier to rsync the patches

If you have more than one machine that you want to keep in track with bleadperl, it's easier to rsync the patches only once and then apply them to all the source trees on the different machines.

In case you try to keep in pace on 5 different machines, for which only one of them has access to the WAN, rsync'ing all the source trees should than be done 5 times over the NFS. Having rsync'ed the patches only once, I can apply them to all the source trees automatically. Need you say more ;-)

It's a good reference

If you do not only like to have the most recent development branch, but also like to fix bugs, or extend features, you want to dive into the sources. If you are a seasoned perl core diver, you don't need no manuals, tips, roadmaps, perlguts.pod or other aids to find your way around. But if you are a starter, the patches may help you in finding where you should start and how to change the bits that bug you.

The file Changes is updated on occasions the pumpking sees as his own little sync points. On those occasions, he releases a tar-ball of the current source tree (i.e. perl@7582.tar.gz), which will be an excellent point to start with when choosing to use the 'rsync the patches' scheme. Starting with perl@7582, which means a set of source files on which the latest applied patch is number 7582, you apply all succeeding patches available from then on (7583, 7584, ...).

You can use the patches later as a kind of search archive.

Finding a start point

If you want to fix/change the behaviour of function/feature Foo, just scan the patches for patches that mention Foo either in the subject, the comments, or the body of the fix. A good chance the patch shows you the files that are affected by that patch which are very likely to be the starting point of your journey into the guts of perl.

Finding how to fix a bug

If you've found where the function/feature Foo misbehaves, but you don't know how to fix it (but you do know the change you want to make), you can, again, peruse the patches for similar changes and look how others apply the fix.

Finding the source of misbehaviour

When you keep in sync with bleadperl, the pumpking would love to see that the community efforts really work. So after each of his sync points, you are to 'make test' to check if everything is still in working order. If it is, you do 'make ok', which will send an OK report to perlbug@perl.org. (If you do not have access to a mailer from the system you just finished successfully 'make test', you can do 'make okfile', which creates the file perl.ok, which you can than take to your favourite mailer and mail yourself).

But of course, as always, things will not always lead to a success path, and one or more test do not pass the 'make test'. Before sending in a bug report (using 'make nok' or 'make nokfile'), check the mailing list if someone else has reported the bug already and if so, confirm it by replying to that message. If not, you might want to trace the source of that misbehaviour before sending in the bug, which will help all the other porters in finding the solution.

Here the saved patches come in very handy. You can check the list of patches to see which patch changed what file and what change caused the misbehaviour. If you note that in the bug report, it saves the one trying to solve it, looking for that point.

If searching the patches is too bothersome, you might consider using perl's bugtron to find more information about discussions and ramblings on posted bugs.

If you want to get the best of both worlds, rsync both the source tree for convenience, reliability and ease and rsync the patches for reference.

Working with the source

Because you cannot use the Perforce client, you cannot easily generate diffs against the repository, nor will merges occur when you update via rsync. If you edit a file locally and then rsync against the latest source, changes made in the remote copy will overwrite your local versions!

The best way to deal with this is to maintain a tree of symlinks to the rsync'd source. Then, when you want to edit a file, you remove the symlink, copy the real file into the other tree, and edit it. You can then diff your edited file against the original to generate a patch, and you can safely update the original tree.

Perl's Configure script can generate this tree of symlinks for you. The following example assumes that you have used rsync to pull a copy of the Perl source into the perl-rsync directory. In the directory above that one, you can execute the following commands:

  mkdir perl-dev
  cd perl-dev
  ../perl-rsync/Configure -Dmksymlinks -Dusedevel -D"optimize=-g"

This will start the Perl configuration process. After a few prompts, you should see something like this:

  Symbolic links are supported.
  Checking how to test for symbolic links...
  Your builtin 'test -h' may be broken.
  Trying external '/usr/bin/test -h'.
  You can test for symbolic links with '/usr/bin/test -h'.
  Creating the symbolic links...
  (First creating the subdirectories...)
  (Then creating the symlinks...)

The specifics may vary based on your operating system, of course. After you see this, you can abort the Configure script, and you will see that the directory you are in has a tree of symlinks to the perl-rsync directories and files.

If you plan to do a lot of work with the Perl source, here are some Bourne shell script functions that can make your life easier:

    function edit {
        if [ -L $1 ]; then
            mv $1 $1.orig
                cp $1.orig $1
                vi $1
        else
            /bin/vi $1
                fi
    }

    function unedit {
        if [ -L $1.orig ]; then
            rm $1
                mv $1.orig $1
                fi
    }

Replace "vi" with your favorite flavor of editor.

Here is another function which will quickly generate a patch for the files which have been edited in your symlink tree:

    mkpatchorig() {
        local diffopts
            for f in `find . -name '*.orig' | sed s,^\./,,`
                do
                    case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in
                        c)   diffopts=-p ;;
                pod) diffopts='-F^=' ;;
                *)   diffopts= ;;
                esac
                    diff -du $diffopts $f `echo $f | sed 's,.orig$,,'`
                    done
    }

This function produces patches which include enough context to make your changes obvious. This makes it easier for the Perl pumpking(s) to review them when you send them to the perl5-porters list, and that means they're more likely to get applied.

This function assumed a GNU diff, and may require some tweaking for other diff variants.

Perlbug administration

There is a single remote administrative interface for modifying bug status, category, open issues etc. using the RT bugtracker system, maintained by Robert Spier. Become an administrator, and close any bugs you can get your sticky mitts on:

        http://rt.perl.org

The bugtracker mechanism for perl5 bugs in particular is at:

        http://bugs6.perl.org/perlbug

To email the bug system administrators:

        "perlbug-admin" <perlbug-admin@perl.org>

Submitting patches

Always submit patches to perl5-porters@perl.org. If you're patching a core module and there's an author listed, send the author a copy (see Patching a core module). This lets other porters review your patch, which catches a surprising number of errors in patches. Either use the diff program (available in source code form from ftp://ftp.gnu.org/pub/gnu/ , or use Johan Vromans' makepatch (available from CPAN/authors/id/JV/). Unified diffs are preferred, but context diffs are accepted. Do not send RCS-style diffs or diffs without context lines. More information is given in the Porting/patching.pod file in the Perl source distribution. Please patch against the latest development version (e.g., if you're fixing a bug in the 5.005 track, patch against the latest 5.005_5x version). Only patches that survive the heat of the development branch get applied to maintenance versions.

Your patch should update the documentation and test suite. See Writing a test.

To report a bug in Perl, use the program perlbug which comes with Perl (if you can't get Perl to work, send mail to the address perlbug@perl.org or perlbug@perl.com). Reporting bugs through perlbug feeds into the automated bug-tracking system, access to which is provided through the web at http://bugs.perl.org/ . It often pays to check the archives of the perl5-porters mailing list to see whether the bug you're reporting has been reported before, and if so whether it was considered a bug. See above for the location of the searchable archives.

The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers who test CPAN modules on a variety of platforms. Perl Smokers ( http://archives.develooper.com/daily-build@perl.org/ ) automatically tests Perl source releases on platforms with various configurations. Both efforts welcome volunteers.

It's a good idea to read and lurk for a while before chipping in. That way you'll get to see the dynamic of the conversations, learn the personalities of the players, and hopefully be better prepared to make a useful contribution when do you speak up.

If after all this you still think you want to join the perl5-porters mailing list, send mail to perl5-porters-subscribe@perl.org. To unsubscribe, send mail to perl5-porters-unsubscribe@perl.org.

To hack on the Perl guts, you'll need to read the following things:

the perlguts manpage

This is of paramount importance, since it's the documentation of what goes where in the Perl source. Read it over a couple of times and it might start to make sense - don't worry if it doesn't yet, because the best way to study it is to read it in conjunction with poking at Perl source, and we'll do that later on.

You might also want to look at Gisle Aas's illustrated perlguts - there's no guarantee that this will be absolutely up-to-date with the latest documentation in the Perl core, but the fundamentals will be right. ( http://gisle.aas.no/perl/illguts/ )

the perlxstut manpage and the perlxs manpage

A working knowledge of XSUB programming is incredibly useful for core hacking; XSUBs use techniques drawn from the PP code, the portion of the guts that actually executes a Perl program. It's a lot gentler to learn those techniques from simple examples and explanation than from the core itself.

the perlapi manpage

The documentation for the Perl API explains what some of the internal functions do, as well as the many macros used in the source.

Porting/pumpkin.pod

This is a collection of words of wisdom for a Perl porter; some of it is only useful to the pumpkin holder, but most of it applies to anyone wanting to go about Perl development.

The perl5-porters FAQ

This should be available from http://simon-cozens.org/writings/p5p-faq ; alternatively, you can get the FAQ emailed to you by sending mail to perl5-porters-faq@perl.org. It contains hints on reading perl5-porters, information on how perl5-porters works and how Perl development in general works.

Finding Your Way Around

Perl maintenance can be split into a number of areas, and certain people (pumpkins) will have responsibility for each area. These areas sometimes correspond to files or directories in the source kit. Among the areas are:

Core modules

Modules shipped as part of the Perl core live in the lib/ and ext/ subdirectories: lib/ is for the pure-Perl modules, and ext/ contains the core XS modules.

Tests

There are tests for nearly all the modules, built-ins and major bits of functionality. Test files all have a .t suffix. Module tests live in the lib/ and ext/ directories next to the module being tested. Others live in t/. See Writing a test

Documentation

Documentation maintenance includes looking after everything in the pod/ directory, (as well as contributing new documentation) and the documentation to the modules in core.

Configure

The configure process is the way we make Perl portable across the myriad of operating systems it supports. Responsibility for the configure, build and installation process, as well as the overall portability of the core code rests with the configure pumpkin - others help out with individual operating systems.

The files involved are the operating system directories, (win32/, os2/, vms/ and so on) the shell scripts which generate config.h and Makefile, as well as the metaconfig files which generate Configure. (metaconfig isn't included in the core distribution.)

Interpreter

And of course, there's the core of the Perl interpreter itself. Let's have a look at that in a little more detail.

Before we leave looking at the layout, though, don't forget that MANIFEST contains not only the file names in the Perl distribution, but short descriptions of what's in them, too. For an overview of the important files, try this:

    perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST

Elements of the interpreter

The work of the interpreter has two main stages: compiling the code into the internal representation, or bytecode, and then executing it. Compiled code in the perlguts manpage explains exactly how the compilation stage happens.

Here is a short breakdown of perl's operation:

Startup

The action begins in perlmain.c. (or miniperlmain.c for miniperl) This is very high-level code, enough to fit on a single screen, and it resembles the code found in the perlembed manpage; most of the real action takes place in perl.c

First, perlmain.c allocates some memory and constructs a Perl interpreter:

    1 PERL_SYS_INIT3(&argc,&argv,&env);
    2
    3 if (!PL_do_undump) {
    4     my_perl = perl_alloc();
    5     if (!my_perl)
    6         exit(1);
    7     perl_construct(my_perl);
    8     PL_perl_destruct_level = 0;
    9 }

Line 1 is a macro, and its definition is dependent on your operating system. Line 3 references PL_do_undump, a global variable - all global variables in Perl start with PL_. This tells you whether the current running program was created with the -u flag to perl and then undump, which means it's going to be false in any sane context.

Line 4 calls a function in perl.c to allocate memory for a Perl interpreter. It's quite a simple function, and the guts of it looks like this:

    my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));

Here you see an example of Perl's system abstraction, which we'll see later: PerlMem_malloc is either your system's malloc, or Perl's own malloc as defined in malloc.c if you selected that option at configure time.

Next, in line 7, we construct the interpreter; this sets up all the special variables that Perl needs, the stacks, and so on.

Now we pass Perl the command line options, and tell it to go:

    exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL);
    if (!exitstatus) {
        exitstatus = perl_run(my_perl);
    }

perl_parse is actually a wrapper around S_parse_body, as defined in perl.c, which processes the command line options, sets up any statically linked XS modules, opens the program and calls yyparse to parse it.

Parsing

The aim of this stage is to take the Perl source, and turn it into an op tree. We'll see what one of those looks like later. Strictly speaking, there's three things going on here.

yyparse, the parser, lives in perly.c, although you're better off reading the original YACC input in perly.y. (Yes, Virginia, there is a YACC grammar for Perl!) The job of the parser is to take your code and "understand" it, splitting it into sentences, deciding which operands go with which operators and so on.

The parser is nobly assisted by the lexer, which chunks up your input into tokens, and decides what type of thing each token is: a variable name, an operator, a bareword, a subroutine, a core function, and so on. The main point of entry to the lexer is yylex, and that and its associated routines can be found in toke.c. Perl isn't much like other computer languages; it's highly context sensitive at times, it can be tricky to work out what sort of token something is, or where a token ends. As such, there's a lot of interplay between the tokeniser and the parser, which can get pretty frightening if you're not used to it.

As the parser understands a Perl program, it builds up a tree of operations for the interpreter to perform during execution. The routines which construct and link together the various operations are to be found in op.c, and will be examined later.

Optimization

Now the parsing stage is complete, and the finished tree represents the operations that the Perl interpreter needs to perform to execute our program. Next, Perl does a dry run over the tree looking for optimisations: constant expressions such as 3 + 4 will be computed now, and the optimizer will also see if any multiple operations can be replaced with a single one. For instance, to fetch the variable $foo, instead of grabbing the glob *foo and looking at the scalar component, the optimizer fiddles the op tree to use a function which directly looks up the scalar in question. The main optimizer is peep in op.c, and many ops have their own optimizing functions.

Running

Now we're finally ready to go: we have compiled Perl byte code, and all that's left to do is run it. The actual execution is done by the runops_standard function in run.c; more specifically, it's done by these three innocent looking lines:

    while ((PL_op = CALL_FPTR(PL_op->op_ppaddr)(aTHX))) {
        PERL_ASYNC_CHECK();
    }

You may be more comfortable with the Perl version of that:

    PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op->{function}};

Well, maybe not. Anyway, each op contains a function pointer, which stipulates the function which will actually carry out the operation. This function will return the next op in the sequence - this allows for things like if which choose the next op dynamically at run time. The PERL_ASYNC_CHECK makes sure that things like signals interrupt execution if required.

The actual functions called are known as PP code, and they're spread between four files: pp_hot.c contains the "hot" code, which is most often used and highly optimized, pp_sys.c contains all the system-specific functions, pp_ctl.c contains the functions which implement control structures (if, while and the like) and pp.c contains everything else. These are, if you like, the C code for Perl's built-in functions and operators.

Note that each pp_ function is expected to return a pointer to the next op. Calls to perl subs (and eval blocks) are handled within the same runops loop, and do not consume extra space on the C stack. For example, pp_entersub and pp_entertry just push a CxSUB or CxEVAL block struct onto the context stack which contain the address of the op following the sub call or eval. They then return the first op of that sub or eval block, and so execution continues of that sub or block. Later, a pp_leavesub or pp_leavetry op pops the CxSUB or CxEVAL, retrieves the return op from it, and returns it.

Exception handing

Perl's exception handing (i.e. die etc) is built on top of the low-level setjmp()/longjmp() C-library functions. These basically provide a way to capture the current PC and SP registers and later restore them; i.e. a longjmp() continues at the point in code where a previous setjmp() was done, with anything further up on the C stack being lost. This is why code should always save values using SAVE_FOO rather than in auto variables.

The perl core wraps setjmp() etc in the macros JMPENV_PUSH and JMPENV_JUMP. The basic rule of perl exceptions is that exit, and die (in the absence of eval) perform a JMPENV_JUMP(2), while die within eval does a JMPENV_JUMP(3).

At entry points to perl, such as perl_parse(), perl_run() and call_sv(cv, G_EVAL) each does a JMPENV_PUSH, then enter a runops loop or whatever, and handle possible exception returns. For a 2 return, final cleanup is performed, such as popping stacks and calling CHECK or END blocks. Amongst other things, this is how scope cleanup still occurs during an exit.

If a die can find a CxEVAL block on the context stack, then the stack is popped to that level and the return op in that block is assigned to PL_restartop; then a JMPENV_JUMP(3) is performed. This normally passes control back to the guard. In the case of perl_run and call_sv, a non-null PL_restartop triggers re-entry to the runops loop. The is the normal way that die or croak is handled within an eval.

Sometimes ops are executed within an inner runops loop, such as tie, sort or overload code. In this case, something like

    sub FETCH { eval { die } }

would cause a longjmp right back to the guard in perl_run, popping both runops loops, which is clearly incorrect. One way to avoid this is for the tie code to do a JMPENV_PUSH before executing FETCH in the inner runops loop, but for efficiency reasons, perl in fact just sets a flag, using CATCH_SET(TRUE). The pp_require, pp_entereval and pp_entertry ops check this flag, and if true, they call docatch, which does a JMPENV_PUSH and starts a new runops level to execute the code, rather than doing it on the current loop.

As a further optimisation, on exit from the eval block in the FETCH, execution of the code following the block is still carried on in the inner loop. When an exception is raised, docatch compares the JMPENV level of the CxEVAL with PL_top_env and if they differ, just re-throws the exception. In this way any inner loops get popped.

Here's an example.

    1: eval { tie @a, 'A' };
    2: sub A::TIEARRAY {
    3:     eval { die };
    4:     die;
    5: }

To run this code, perl_run is called, which does a JMPENV_PUSH then enters a runops loop. This loop executes the eval and tie ops on line 1, with the eval pushing a CxEVAL onto the context stack.

The pp_tie does a CATCH_SET(TRUE), then starts a second runops loop to execute the body of TIEARRAY. When it executes the entertry op on line 3, CATCH_GET is true, so pp_entertry calls docatch which does a JMPENV_PUSH and starts a third runops loop, which then executes the die op. At this point the C call stack looks like this:

    Perl_pp_die
    Perl_runops      # third loop
    S_docatch_body
    S_docatch
    Perl_pp_entertry
    Perl_runops      # second loop
    S_call_body
    Perl_call_sv
    Perl_pp_tie
    Perl_runops      # first loop
    S_run_body
    perl_run
    main

and the context and data stacks, as shown by -Dstv, look like:

    STACK 0: MAIN
      CX 0: BLOCK  =>
      CX 1: EVAL   => AV()  PV("A"\0)
      retop=leave
    STACK 1: MAGIC
      CX 0: SUB    =>
      retop=(null)
      CX 1: EVAL   => *
    retop=nextstate

The die pops the first CxEVAL off the context stack, sets PL_restartop from it, does a JMPENV_JUMP(3), and control returns to the top docatch. This then starts another third-level runops level, which executes the nextstate, pushmark and die ops on line 4. At the point that the second pp_die is called, the C call stack looks exactly like that above, even though we are no longer within an inner eval; this is because of the optimization mentioned earlier. However, the context stack now looks like this, ie with the top CxEVAL popped:

    STACK 0: MAIN
      CX 0: BLOCK  =>
      CX 1: EVAL   => AV()  PV("A"\0)
      retop=leave
    STACK 1: MAGIC
      CX 0: SUB    =>
      retop=(null)

The die on line 4 pops the context stack back down to the CxEVAL, leaving it as:

    STACK 0: MAIN
      CX 0: BLOCK  =>

As usual, PL_restartop is extracted from the CxEVAL, and a JMPENV_JUMP(3) done, which pops the C stack back to the docatch:

    S_docatch
    Perl_pp_entertry
    Perl_runops      # second loop
    S_call_body
    Perl_call_sv
    Perl_pp_tie
    Perl_runops      # first loop
    S_run_body
    perl_run
    main

In this case, because the JMPENV level recorded in the CxEVAL differs from the current one, docatch just does a JMPENV_JUMP(3) and the C stack unwinds to:

    perl_run
    main

Because PL_restartop is non-null, run_body starts a new runops loop and execution continues.

Internal Variable Types

You should by now have had a look at the perlguts manpage, which tells you about Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do that now.

These variables are used not only to represent Perl-space variables, but also any constants in the code, as well as some structures completely internal to Perl. The symbol table, for instance, is an ordinary Perl hash. Your code is represented by an SV as it's read into the parser; any program files you call are opened via ordinary Perl filehandles, and so on.

The core Devel::Peek module lets us examine SVs from a Perl program. Let's see, for instance, how Perl treats the constant "hello".

      % perl -MDevel::Peek -e 'Dump("hello")'
    1 SV = PV(0xa041450) at 0xa04ecbc
    2   REFCNT = 1
    3   FLAGS = (POK,READONLY,pPOK)
    4   PV = 0xa0484e0 "hello"\0
    5   CUR = 5
    6   LEN = 6

Reading Devel::Peek output takes a bit of practise, so let's go through it line by line.

Line 1 tells us we're looking at an SV which lives at 0xa04ecbc in memory. SVs themselves are very simple structures, but they contain a pointer to a more complex structure. In this case, it's a PV, a structure which holds a string value, at location 0xa041450. Line 2 is the reference count; there are no other references to this data, so it's 1.

Line 3 are the flags for this SV - it's OK to use it as a PV, it's a read-only SV (because it's a constant) and the data is a PV internally. Next we've got the contents of the string, starting at location 0xa0484e0.

Line 5 gives us the current length of the string - note that this does not include the null terminator. Line 6 is not the length of the string, but the length of the currently allocated buffer; as the string grows, Perl automatically extends the available storage via a routine called SvGROW.

You can get at any of these quantities from C very easily; just add Sv to the name of the field shown in the snippet, and you've got a macro which will return the value: SvCUR(sv) returns the current length of the string, SvREFCOUNT(sv) returns the reference count, SvPV(sv, len) returns the string itself with its length, and so on. More macros to manipulate these properties can be found in the perlguts manpage.

Let's take an example of manipulating a PV, from sv_catpvn, in sv.c

     1  void
     2  Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len)
     3  {
     4      STRLEN tlen;
     5      char *junk;

     6      junk = SvPV_force(sv, tlen);
     7      SvGROW(sv, tlen + len + 1);
     8      if (ptr == junk)
     9          ptr = SvPVX(sv);
         10      Move(ptr,SvPVX(sv)+tlen,len,char);
         11      SvCUR(sv) += len;
         12      *SvEND(sv) = '\0';
         13      (void)SvPOK_only_UTF8(sv);          /* validate pointer */
         14      SvTAINT(sv);
         15  }

This is a function which adds a string, ptr, of length len onto the end of the PV stored in sv. The first thing we do in line 6 is make sure that the SV has a valid PV, by calling the SvPV_force macro to force a PV. As a side effect, tlen gets set to the current value of the PV, and the PV itself is returned to junk.

In line 7, we make sure that the SV will have enough room to accommodate the old string, the new string and the null terminator. If LEN isn't big enough, SvGROW will reallocate space for us.

Now, if junk is the same as the string we're trying to add, we can grab the string directly from the SV; SvPVX is the address of the PV in the SV.

Line 10 does the actual catenation: the Move macro moves a chunk of memory around: we move the string ptr to the end of the PV - that's the start of the PV plus its current length. We're moving len bytes of type char. After doing so, we need to tell Perl we've extended the string, by altering CUR to reflect the new length. SvEND is a macro which gives us the end of the string, so that needs to be a "\0".

Line 13 manipulates the flags; since we've changed the PV, any IV or NV values will no longer be valid: if we have $a=10; $a.="6"; we don't want to use the old IV of 10. SvPOK_only_utf8 is a special UTF-8-aware version of SvPOK_only, a macro which turns off the IOK and NOK flags and turns on POK. The final SvTAINT is a macro which launders tainted data if taint mode is turned on.

AVs and HVs are more complicated, but SVs are by far the most common variable type being thrown around. Having seen something of how we manipulate these, let's go on and look at how the op tree is constructed.

Op Trees

First, what is the op tree, anyway? The op tree is the parsed representation of your program, as we saw in our section on parsing, and it's the sequence of operations that Perl goes through to execute your program, as we saw in Running.

An op is a fundamental operation that Perl can perform: all the built-in functions and operators are ops, and there are a series of ops which deal with concepts the interpreter needs internally - entering and leaving a block, ending a statement, fetching a variable, and so on.

The op tree is connected in two ways: you can imagine that there are two "routes" through it, two orders in which you can traverse the tree. First, parse order reflects how the parser understood the code, and secondly, execution order tells perl what order to perform the operations in.

The easiest way to examine the op tree is to stop Perl after it has finished parsing, and get it to dump out the tree. This is exactly what the compiler backends B::Terse, B::Concise and B::Debug do.

Let's have a look at how Perl sees $a = $b + $c:

     % perl -MO=Terse -e '$a=$b+$c'
     1  LISTOP (0x8179888) leave
     2      OP (0x81798b0) enter
     3      COP (0x8179850) nextstate
     4      BINOP (0x8179828) sassign
     5          BINOP (0x8179800) add [1]
     6              UNOP (0x81796e0) null [15]
     7                  SVOP (0x80fafe0) gvsv  GV (0x80fa4cc) *b
     8              UNOP (0x81797e0) null [15]
     9                  SVOP (0x8179700) gvsv  GV (0x80efeb0) *c
    10          UNOP (0x816b4f0) null [15]
    11              SVOP (0x816dcf0) gvsv  GV (0x80fa460) *a

Let's start in the middle, at line 4. This is a BINOP, a binary operator, which is at location 0x8179828. The specific operator in question is sassign - scalar assignment - and you can find the code which implements it in the function pp_sassign in pp_hot.c. As a binary operator, it has two children: the add operator, providing the result of $b+$c, is uppermost on line 5, and the left hand side is on line 10.

Line 10 is the null op: this does exactly nothing. What is that doing there? If you see the null op, it's a sign that something has been optimized away after parsing. As we mentioned in Optimization, the optimization stage sometimes converts two operations into one, for example when fetching a scalar variable. When this happens, instead of rewriting the op tree and cleaning up the dangling pointers, it's easier just to replace the redundant operation with the null op. Originally, the tree would have looked like this:

    10          SVOP (0x816b4f0) rv2sv [15]
    11              SVOP (0x816dcf0) gv  GV (0x80fa460) *a

That is, fetch the a entry from the main symbol table, and then look at the scalar component of it: gvsv (pp_gvsv into pp_hot.c) happens to do both these things.

The right hand side, starting at line 5 is similar to what we've just seen: we have the add op (pp_add also in pp_hot.c) add together two gvsvs.

Now, what's this about?

     1  LISTOP (0x8179888) leave
     2      OP (0x81798b0) enter
     3      COP (0x8179850) nextstate

enter and leave are scoping ops, and their job is to perform any housekeeping every time you enter and leave a block: lexical variables are tidied up, unreferenced variables are destroyed, and so on. Every program will have those first three lines: leave is a list, and its children are all the statements in the block. Statements are delimited by nextstate, so a block is a collection of nextstate ops, with the ops to be performed for each statement being the children of nextstate. enter is a single op which functions as a marker.

That's how Perl parsed the program, from top to bottom:

                        Program
                           |
                       Statement
                           |
                           =
                          / \
                         /   \
                        $a   +
                            / \
                          $b   $c

However, it's impossible to perform the operations in this order: you have to find the values of $b and $c before you add them together, for instance. So, the other thread that runs through the op tree is the execution order: each op has a field op_next which points to the next op to be run, so following these pointers tells us how perl executes the code. We can traverse the tree in this order using the exec option to B::Terse:

     % perl -MO=Terse,exec -e '$a=$b+$c'
     1  OP (0x8179928) enter
     2  COP (0x81798c8) nextstate
     3  SVOP (0x81796c8) gvsv  GV (0x80fa4d4) *b
     4  SVOP (0x8179798) gvsv  GV (0x80efeb0) *c
     5  BINOP (0x8179878) add [1]
     6  SVOP (0x816dd38) gvsv  GV (0x80fa468) *a
     7  BINOP (0x81798a0) sassign
     8  LISTOP (0x8179900) leave

This probably makes more sense for a human: enter a block, start a statement. Get the values of $b and $c, and add them together. Find $a, and assign one to the other. Then leave.

The way Perl builds up these op trees in the parsing process can be unravelled by examining perly.y, the YACC grammar. Let's take the piece we need to construct the tree for $a = $b + $c

    1 term    :   term ASSIGNOP term
    2                { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); }
    3         |   term ADDOP term
    4                { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }

If you're not used to reading BNF grammars, this is how it works: You're fed certain things by the tokeniser, which generally end up in upper case. Here, ADDOP, is provided when the tokeniser sees + in your code. ASSIGNOP is provided when = is used for assigning. These are "terminal symbols", because you can't get any simpler than them.

The grammar, lines one and three of the snippet above, tells you how to build up more complex forms. These complex forms, "non-terminal symbols" are generally placed in lower case. term here is a non-terminal symbol, representing a single expression.

The grammar gives you the following rule: you can make the thing on the left of the colon if you see all the things on the right in sequence. This is called a "reduction", and the aim of parsing is to completely reduce the input. There are several different ways you can perform a reduction, separated by vertical bars: so, term followed by = followed by term makes a term, and term followed by + followed by term can also make a term.

So, if you see two terms with an = or +, between them, you can turn them into a single expression. When you do this, you execute the code in the block on the next line: if you see =, you'll do the code in line 2. If you see +, you'll do the code in line 4. It's this code which contributes to the op tree.

            |   term ADDOP term
            { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }

What this does is creates a new binary op, and feeds it a number of variables. The variables refer to the tokens: $1 is the first token in the input, $2 the second, and so on - think regular expression backreferences. $$ is the op returned from this reduction. So, we call newBINOP to create a new binary operator. The first parameter to newBINOP, a function in op.c, is the op type. It's an addition operator, so we want the type to be ADDOP. We could specify this directly, but it's right there as the second token in the input, so we use $2. The second parameter is the op's flags: 0 means "nothing special". Then the things to add: the left and right hand side of our expression, in scalar context.

Stacks

When perl executes something like addop, how does it pass on its results to the next op? The answer is, through the use of stacks. Perl has a number of stacks to store things it's currently working on, and we'll look at the three most important ones here.

Argument stack

Arguments are passed to PP code and returned from PP code using the argument stack, ST. The typical way to handle arguments is to pop them off the stack, deal with them how you wish, and then push the result back onto the stack. This is how, for instance, the cosine operator works:

      NV value;
      value = POPn;
      value = Perl_cos(value);
      XPUSHn(value);

We'll see a more tricky example of this when we consider Perl's macros below. POPn gives you the NV (floating point value) of the top SV on the stack: the $x in cos($x). Then we compute the cosine, and push the result back as an NV. The X in XPUSHn means that the stack should be extended if necessary - it can't be necessary here, because we know there's room for one more item on the stack, since we've just removed one! The XPUSH* macros at least guarantee safety.

Alternatively, you can fiddle with the stack directly: SP gives you the first element in your portion of the stack, and TOP* gives you the top SV/IV/NV/etc. on the stack. So, for instance, to do unary negation of an integer:

     SETi(-TOPi);

Just set the integer value of the top stack entry to its negation.

Argument stack manipulation in the core is exactly the same as it is in XSUBs - see the perlxstut manpage, the perlxs manpage and the perlguts manpage for a longer description of the macros used in stack manipulation.

Mark stack

I say "your portion of the stack" above because PP code doesn't necessarily get the whole stack to itself: if your function calls another function, you'll only want to expose the arguments aimed for the called function, and not (necessarily) let it get at your own data. The way we do this is to have a "virtual" bottom-of-stack, exposed to each function. The mark stack keeps bookmarks to locations in the argument stack usable by each function. For instance, when dealing with a tied variable, (internally, something with "P" magic) Perl has to call methods for accesses to the tied variables. However, we need to separate the arguments exposed to the method to the argument exposed to the original function - the store or fetch or whatever it may be. Here's how the tied push is implemented; see av_push in av.c:

     1  PUSHMARK(SP);
     2  EXTEND(SP,2);
     3  PUSHs(SvTIED_obj((SV*)av, mg));
     4  PUSHs(val);
     5  PUTBACK;
     6  ENTER;
     7  call_method("PUSH", G_SCALAR|G_DISCARD);
     8  LEAVE;
     9  POPSTACK;

The lines which concern the mark stack are the first, fifth and last lines: they save away, restore and remove the current position of the argument stack.

Let's examine the whole implementation, for practice:

     1  PUSHMARK(SP);

Push the current state of the stack pointer onto the mark stack. This is so that when we've finished adding items to the argument stack, Perl knows how many things we've added recently.

     2  EXTEND(SP,2);
     3  PUSHs(SvTIED_obj((SV*)av, mg));
     4  PUSHs(val);

We're going to add two more items onto the argument stack: when you have a tied array, the PUSH subroutine receives the object and the value to be pushed, and that's exactly what we have here - the tied object, retrieved with SvTIED_obj, and the value, the SV val.

     5  PUTBACK;

Next we tell Perl to make the change to the global stack pointer: dSP only gave us a local copy, not a reference to the global.

     6  ENTER;
     7  call_method("PUSH", G_SCALAR|G_DISCARD);
     8  LEAVE;

ENTER and LEAVE localise a block of code - they make sure that all variables are tidied up, everything that has been localised gets its previous value returned, and so on. Think of them as the { and } of a Perl block.

To actually do the magic method call, we have to call a subroutine in Perl space: call_method takes care of that, and it's described in the perlcall manpage. We call the PUSH method in scalar context, and we're going to discard its return value.

     9  POPSTACK;

Finally, we remove the value we placed on the mark stack, since we don't need it any more.

Save stack

C doesn't have a concept of local scope, so perl provides one. We've seen that ENTER and LEAVE are used as scoping braces; the save stack implements the C equivalent of, for example:

    {
        local $foo = 42;
        ...
    }

See Localising Changes in the perlguts manpage for how to use the save stack.

Millions of Macros

One thing you'll notice about the Perl source is that it's full of macros. Some have called the pervasive use of macros the hardest thing to understand, others find it adds to clarity. Let's take an example, the code which implements the addition operator:

   1  PP(pp_add)
   2  {
   3      dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
   4      {
   5        dPOPTOPnnrl_ul;
   6        SETn( left + right );
   7        RETURN;
   8      }
   9  }

Every line here (apart from the braces, of course) contains a macro. The first line sets up the function declaration as Perl expects for PP code; line 3 sets up variable declarations for the argument stack and the target, the return value of the operation. Finally, it tries to see if the addition operation is overloaded; if so, the appropriate subroutine is called.

Line 5 is another variable declaration - all variable declarations start with d - which pops from the top of the argument stack two NVs (hence nn) and puts them into the variables right and left, hence the rl. These are the two operands to the addition operator. Next, we call SETn to set the NV of the return value to the result of adding the two values. This done, we return - the RETURN macro makes sure that our return value is properly handled, and we pass the next operator to run back to the main run loop.

Most of these macros are explained in the perlapi manpage, and some of the more important ones are explained in the perlxs manpage as well. Pay special attention to Background and PERL_IMPLICIT_CONTEXT in the perlguts manpage for information on the [pad]THX_? macros.

The .i Targets

You can expand the macros in a foo.c file by saying

    make foo.i

which will expand the macros using cpp. Don't be scared by the results.

Poking at Perl

To really poke around with Perl, you'll probably want to build Perl for debugging, like this:

    ./Configure -d -D optimize=-g
    make

-g is a flag to the C compiler to have it produce debugging information which will allow us to step through a running program. Configure will also turn on the DEBUGGING compilation symbol which enables all the internal debugging code in Perl. There are a whole bunch of things you can debug with this: the perlrun manpage lists them all, and the best way to find out about them is to play about with them. The most useful options are probably

    l  Context (loop) stack processing
    t  Trace execution
    o  Method and overloading resolution
    c  String/numeric conversions

Some of the functionality of the debugging code can be achieved using XS modules.

    -Dr => use re 'debug'
    -Dx => use O 'Debug'

Using a source-level debugger

If the debugging output of -D doesn't help you, it's time to step through perl's execution with a source-level debugger.

  • We'll use gdb for our examples here; the principles will apply to any debugger, but check the manual of the one you're using.

To fire up the debugger, type

    gdb ./perl

You'll want to do that in your Perl source tree so the debugger can read the source code. You should see the copyright message, followed by the prompt.

    (gdb)

help will get you into the documentation, but here are the most useful commands:

run [args]

Run the program with the given arguments.

break function_name
break source.c:xxx

Tells the debugger that we'll want to pause execution when we reach either the named function (but see Internal Functions in the perlguts manpage!) or the given line in the named source file.

step

Steps through the program a line at a time.

next

Steps through the program a line at a time, without descending into functions.

continue

Run until the next breakpoint.

finish

Run until the end of the current function, then stop again.

'enter'

Just pressing Enter will do the most recent operation again - it's a blessing when stepping through miles of source code.

print

Execute the given C code and print its results. WARNING: Perl makes heavy use of macros, and gdb does not necessarily support macros (see later gdb macro support). You'll have to substitute them yourself, or to invoke cpp on the source code files (see The .i Targets) So, for instance, you can't say

    print SvPV_nolen(sv)

but you have to say

    print Perl_sv_2pv_nolen(sv)

You may find it helpful to have a "macro dictionary", which you can produce by saying cpp -dM perl.c | sort. Even then, cpp won't recursively apply those macros for you.

gdb macro support

Recent versions of gdb have fairly good macro support, but in order to use it you'll need to compile perl with macro definitions included in the debugging information. Using gcc version 3.1, this means configuring with -Doptimize=-g3. Other compilers might use a different switch (if they support debugging macros at all).

Dumping Perl Data Structures

One way to get around this macro hell is to use the dumping functions in dump.c; these work a little like an internal Devel::Peek, but they also cover OPs and other structures that you can't get at from Perl. Let's take an example. We'll use the $a = $b + $c we used before, but give it a bit of context: $b = "6XXXX"; $c = 2.3;. Where's a good place to stop and poke around?

What about pp_add, the function we examined earlier to implement the + operator:

    (gdb) break Perl_pp_add
    Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.

Notice we use Perl_pp_add and not pp_add - see Internal Functions in the perlguts manpage. With the breakpoint in place, we can run our program:

    (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c'

Lots of junk will go past as gdb reads in the relevant source files and libraries, and then:

    Breakpoint 1, Perl_pp_add () at pp_hot.c:309
    309         dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
    (gdb) step
    311           dPOPTOPnnrl_ul;
    (gdb)

We looked at this bit of code before, and we said that dPOPTOPnnrl_ul arranges for two NVs to be placed into left and right - let's slightly expand it:

    #define dPOPTOPnnrl_ul  NV right = POPn; \
                            SV *leftsv = TOPs; \
                            NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0

POPn takes the SV from the top of the stack and obtains its NV either directly (if SvNOK is set) or by calling the sv_2nv function. TOPs takes the next SV from the top of the stack - yes, POPn uses TOPs - but doesn't remove it. We then use SvNV to get the NV from leftsv in the same way as before - yes, POPn uses SvNV.

Since we don't have an NV for $b, we'll have to use sv_2nv to convert it. If we step again, we'll find ourselves there:

    Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
    1669        if (!sv)
    (gdb)

We can now use Perl_sv_dump to investigate the SV:

    SV = PV(0xa057cc0) at 0xa0675d0
    REFCNT = 1
    FLAGS = (POK,pPOK)
    PV = 0xa06a510 "6XXXX"\0
    CUR = 5
    LEN = 6
    $1 = void

We know we're going to get 6 from this, so let's finish the subroutine:

    (gdb) finish
    Run till exit from #0  Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
    0x462669 in Perl_pp_add () at pp_hot.c:311
    311           dPOPTOPnnrl_ul;

We can also dump out this op: the current op is always stored in PL_op, and we can dump it with Perl_op_dump. This'll give us similar output to B::Debug.

    {
    13  TYPE = add  ===> 14
        TARG = 1
        FLAGS = (SCALAR,KIDS)
        {
            TYPE = null  ===> (12)
              (was rv2sv)
            FLAGS = (SCALAR,KIDS)
            {
    11          TYPE = gvsv  ===> 12
                FLAGS = (SCALAR)
                GV = main::b
            }
        }

# finish this later #

Patching

All right, we've now had a look at how to navigate the Perl sources and some things you'll need to know when fiddling with them. Let's now get on and create a simple patch. Here's something Larry suggested: if a U is the first active format during a pack, (for example, pack "U3C8", @stuff) then the resulting string should be treated as UTF-8 encoded.

How do we prepare to fix this up? First we locate the code in question - the pack happens at runtime, so it's going to be in one of the pp files. Sure enough, pp_pack is in pp.c. Since we're going to be altering this file, let's copy it to pp.c~.

[Well, it was in pp.c when this tutorial was written. It has now been split off with pp_unpack to its own file, pp_pack.c]

Now let's look over pp_pack: we take a pattern into pat, and then loop over the pattern, taking each format character in turn into datum_type. Then for each possible format character, we swallow up the other arguments in the pattern (a field width, an asterisk, and so on) and convert the next chunk input into the specified format, adding it onto the output SV cat.

How do we know if the U is the first format in the pat? Well, if we have a pointer to the start of pat then, if we see a U we can test whether we're still at the start of the string. So, here's where pat is set up:

    STRLEN fromlen;
    register char *pat = SvPVx(*++MARK, fromlen);
    register char *patend = pat + fromlen;
    register I32 len;
    I32 datumtype;
    SV *fromstr;

We'll have another string pointer in there:

    STRLEN fromlen;
    register char *pat = SvPVx(*++MARK, fromlen);
    register char *patend = pat + fromlen;
     +  char *patcopy;
    register I32 len;
    I32 datumtype;
    SV *fromstr;

And just before we start the loop, we'll set patcopy to be the start of pat:

    items = SP - MARK;
    MARK++;
    sv_setpvn(cat, "", 0);
     +  patcopy = pat;
    while (pat < patend) {

Now if we see a U which was at the start of the string, we turn on the UTF8 flag for the output SV, cat:

 +  if (datumtype == 'U' && pat==patcopy+1)
 +      SvUTF8_on(cat);
    if (datumtype == '#') {
        while (pat < patend && *pat != '\n')
            pat++;

Remember that it has to be patcopy+1 because the first character of the string is the U which has been swallowed into datumtype!

Oops, we forgot one thing: what if there are spaces at the start of the pattern? pack(" U*", @stuff) will have U as the first active character, even though it's not the first thing in the pattern. In this case, we have to advance patcopy along with pat when we see spaces:

    if (isSPACE(datumtype))
        continue;

needs to become

    if (isSPACE(datumtype)) {
        patcopy++;
        continue;
    }

OK. That's the C part done. Now we must do two additional things before this patch is ready to go: we've changed the behaviour of Perl, and so we must document that change. We must also provide some more regression tests to make sure our patch works and doesn't create a bug somewhere else along the line.

The regression tests for each operator live in t/op/, and so we make a copy of t/op/pack.t to t/op/pack.t~. Now we can add our tests to the end. First, we'll test that the U does indeed create Unicode strings.

t/op/pack.t has a sensible ok() function, but if it didn't we could use the one from t/test.pl.

 require './test.pl';
 plan( tests => 159 );

so instead of this:

 print 'not ' unless "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000);
 print "ok $test\n"; $test++;

we can write the more sensible (see the Test::More manpage for a full explanation of is() and other testing functions).

 is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000),
                                       "U* produces unicode" );

Now we'll test that we got that space-at-the-beginning business right:

 is( "1.20.300.4000", sprintf "%vd", pack("  U*",1,20,300,4000),
                                       "  with spaces at the beginning" );

And finally we'll test that we don't make Unicode strings if U is not the first active format:

 isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000),
                                       "U* not first isn't unicode" );

Mustn't forget to change the number of tests which appears at the top, or else the automated tester will get confused. This will either look like this:

 print "1..156\n";

or this:

 plan( tests => 156 );

We now compile up Perl, and run it through the test suite. Our new tests pass, hooray!

Finally, the documentation. The job is never done until the paperwork is over, so let's describe the change we've just made. The relevant place is pod/perlfunc.pod; again, we make a copy, and then we'll insert this text in the description of pack:

 =item *
 If the pattern begins with a C<U>, the resulting string will be treated
 as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string
 with an initial C<U0>, and the bytes that follow will be interpreted as
 Unicode characters. If you don't want this to happen, you can begin your
 pattern with C<C0> (or anything else) to force Perl not to UTF-8 encode your
 string, and then follow this with a C<U*> somewhere in your pattern.

All done. Now let's create the patch. Porting/patching.pod tells us that if we're making major changes, we should copy the entire directory to somewhere safe before we begin fiddling, and then do

    diff -ruN old new > patch

However, we know which files we've changed, and we can simply do this:

    diff -u pp.c~             pp.c             >  patch
    diff -u t/op/pack.t~      t/op/pack.t      >> patch
    diff -u pod/perlfunc.pod~ pod/perlfunc.pod >> patch

We end up with a patch looking a little like this:

    --- pp.c~       Fri Jun 02 04:34:10 2000
    +++ pp.c        Fri Jun 16 11:37:25 2000
    @@ -4375,6 +4375,7 @@
         register I32 items;
         STRLEN fromlen;
         register char *pat = SvPVx(*++MARK, fromlen);
    +    char *patcopy;
         register char *patend = pat + fromlen;
         register I32 len;
         I32 datumtype;
    @@ -4405,6 +4406,7 @@
    ...

And finally, we submit it, with our rationale, to perl5-porters. Job done!

Patching a core module

This works just like patching anything else, with an extra consideration. Many core modules also live on CPAN. If this is so, patch the CPAN version instead of the core and send the patch off to the module maintainer (with a copy to p5p). This will help the module maintainer keep the CPAN version in sync with the core version without constantly scanning p5p.

The list of maintainers of core modules is usefully documented in Porting/Maintainers.pl.

Adding a new function to the core

If, as part of a patch to fix a bug, or just because you have an especially good idea, you decide to add a new function to the core, discuss your ideas on p5p well before you start work. It may be that someone else has already attempted to do what you are considering and can give lots of good advice or even provide you with bits of code that they already started (but never finished).

You have to follow all of the advice given above for patching. It is extremely important to test any addition thoroughly and add new tests to explore all boundary conditions that your new function is expected to handle. If your new function is used only by one module (e.g. toke), then it should probably be named S_your_function (for static); on the other hand, if you expect it to accessible from other functions in Perl, you should name it Perl_your_function. See Internal Functions in the perlguts manpage for more details.

The location of any new code is also an important consideration. Don't just create a new top level .c file and put your code there; you would have to make changes to Configure (so the Makefile is created properly), as well as possibly lots of include files. This is strictly pumpking business.

It is better to add your function to one of the existing top level source code files, but your choice is complicated by the nature of the Perl distribution. Only the files that are marked as compiled static are located in the perl executable. Everything else is located in the shared library (or DLL if you are running under WIN32). So, for example, if a function was only used by functions located in toke.c, then your code can go in toke.c. If, however, you want to call the function from universal.c, then you should put your code in another location, for example util.c.

In addition to writing your c-code, you will need to create an appropriate entry in embed.pl describing your function, then run 'make regen_headers' to create the entries in the numerous header files that perl needs to compile correctly. See Internal Functions in the perlguts manpage for information on the various options that you can set in embed.pl. You will forget to do this a few (or many) times and you will get warnings during the compilation phase. Make sure that you mention this when you post your patch to P5P; the pumpking needs to know this.

When you write your new code, please be conscious of existing code conventions used in the perl source files. See the perlstyle manpage for details. Although most of the guidelines discussed seem to focus on Perl code, rather than c, they all apply (except when they don't ;). See also Porting/patching.pod file in the Perl source distribution for lots of details about both formatting and submitting patches of your changes.

Lastly, TEST TEST TEST TEST TEST any code before posting to p5p. Test on as many platforms as you can find. Test as many perl Configure options as you can (e.g. MULTIPLICITY). If you have profiling or memory tools, see EXTERNAL TOOLS FOR DEBUGGING PERL below for how to use them to further test your code. Remember that most of the people on P5P are doing this on their own time and don't have the time to debug your code.

Writing a test

Every module and built-in function has an associated test file (or should...). If you add or change functionality, you have to write a test. If you fix a bug, you have to write a test so that bug never comes back. If you alter the docs, it would be nice to test what the new documentation says.

In short, if you submit a patch you probably also have to patch the tests.

For modules, the test file is right next to the module itself. lib/strict.t tests lib/strict.pm. This is a recent innovation, so there are some snags (and it would be wonderful for you to brush them out), but it basically works that way. Everything else lives in t/.

t/base/

Testing of the absolute basic functionality of Perl. Things like if, basic file reads and writes, simple regexes, etc. These are run first in the test suite and if any of them fail, something is really broken.

t/cmd/

These test the basic control structures, if/else, while, subroutines, etc.

t/comp/

Tests basic issues of how Perl parses and compiles itself.

t/io/

Tests for built-in IO functions, including command line arguments.

t/lib/

The old home for the module tests, you shouldn't put anything new in here. There are still some bits and pieces hanging around in here that need to be moved. Perhaps you could move them? Thanks!

t/op/

Tests for perl's built in functions that don't fit into any of the other directories.

t/pod/

Tests for POD directives. There are still some tests for the Pod modules hanging around in here that need to be moved out into lib/.

t/run/

Testing features of how perl actually runs, including exit codes and handling of PERL* environment variables.

t/uni/

Tests for the core support of Unicode.

t/win32/

Windows-specific tests.

t/x2p

A test suite for the s2p converter.

The core uses the same testing style as the rest of Perl, a simple "ok/not ok" run through Test::Harness, but there are a few special considerations.

There are three ways to write a test in the core. Test::More, t/test.pl and ad hoc print $test ? "ok 42\n" : "not ok 42\n". The decision of which to use depends on what part of the test suite you're working on. This is a measure to prevent a high-level failure (such as Config.pm breaking) from causing basic functionality tests to fail.

t/base t/comp

Since we don't know if require works, or even subroutines, use ad hoc tests for these two. Step carefully to avoid using the feature being tested.

t/cmd t/run t/io t/op

Now that basic require() and subroutines are tested, you can use the t/test.pl library which emulates the important features of Test::More while using a minimum of core features.

You can also conditionally use certain libraries like Config, but be sure to skip the test gracefully if it's not there.

t/lib ext lib

Now that the core of Perl is tested, Test::More can be used. You can also use the full suite of core modules in the tests.

When you say "make test" Perl uses the t/TEST program to run the test suite (except under Win32 where it uses t/harness instead.) All tests are run from the t/ directory, not the directory which contains the test. This causes some problems with the tests in lib/, so here's some opportunity for some patching.

You must be triply conscious of cross-platform concerns. This usually boils down to using File::Spec and avoiding things like fork() and system() unless absolutely necessary.

Special Make Test Targets

There are various special make targets that can be used to test Perl slightly differently than the standard "test" target. Not all them are expected to give a 100% success rate. Many of them have several aliases, and many of them are not available on certain operating systems.

coretest

Run perl on all core tests (t/* and lib/[a-z]* pragma tests).

(Not available on Win32)

test.deparse

Run all the tests through B::Deparse. Not all tests will succeed.

(Not available on Win32)

test.taintwarn

Run all tests with the -t command-line switch. Not all tests are expected to succeed (until they're specifically fixed, of course).

(Not available on Win32)

minitest

Run miniperl on t/base, t/comp, t/cmd, t/run, t/io, t/op, and t/uni tests.

test.valgrind check.valgrind utest.valgrind ucheck.valgrind

(Only in Linux) Run all the tests using the memory leak + naughty memory access tool "valgrind". The log files will be named testname.valgrind.

test.third check.third utest.third ucheck.third

(Only in Tru64) Run all the tests using the memory leak + naughty memory access tool "Third Degree". The log files will be named perl.3log.testname.

test.torture torturetest

Run all the usual tests and some extra tests. As of Perl 5.8.0 the only extra tests are Abigail's JAPHs, t/japh/abigail.t.

You can also run the torture test with t/harness by giving -torture argument to t/harness.

utest ucheck test.utf8 check.utf8

Run all the tests with -Mutf8. Not all tests will succeed.

(Not available on Win32)

minitest.utf16 test.utf16

Runs the tests with UTF-16 encoded scripts, encoded with different versions of this encoding.

make utest.utf16 runs the test suite with a combination of -utf8 and -utf16 arguments to t/TEST.

(Not available on Win32)

test_harness

Run the test suite with the t/harness controlling program, instead of t/TEST. t/harness is more sophisticated, and uses the the Test::Harness manpage module, thus using this test target supposes that perl mostly works. The main advantage for our purposes is that it prints a detailed summary of failed tests at the end. Also, unlike t/TEST, it doesn't redirect stderr to stdout.

Note that under Win32 t/harness is always used instead of t/TEST, so there is no special "test_harness" target.

Under Win32's "test" target you may use the TEST_SWITCHES and TEST_FILES environment variables to control the behaviour of t/harness. This means you can say

    nmake test TEST_FILES="op/*.t"
    nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
test-notty test_notty

Sets PERL_SKIP_TTY_TEST to true before running normal test.

Running tests by hand

You can run part of the test suite by hand by using one the following commands from the t/ directory :

    ./perl -I../lib TEST list-of-.t-files

or

    ./perl -I../lib harness list-of-.t-files

(if you don't specify test scripts, the whole test suite will be run.)

Using t/harness for testing

If you use harness for testing you have several command line options available to you. The arguments are as follows, and are in the order that they must appear if used together.

    harness -v -torture -re=pattern LIST OF FILES TO TEST
    harness -v -torture -re LIST OF PATTERNS TO MATCH

If LIST OF FILES TO TEST is omitted the file list is obtained from the manifest. The file list may include shell wildcards which will be expanded out.

-v

Run the tests under verbose mode so you can see what tests were run, and debug outbut.

-torture

Run the torture tests as well as the normal set.

-re=PATTERN

Filter the file list so that all the test files run match PATTERN. Note that this form is distinct from the -re LIST OF PATTERNS form below in that it allows the file list to be provided as well.

-re LIST OF PATTERNS

Filter the file list so that all the test files run match /(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined by '|' and you cannot supply a list of files, instead the test files are obtained from the MANIFEST.

You can run an individual test by a command similar to

    ./perl -I../lib patho/to/foo.t

except that the harnesses set up some environment variables that may affect the execution of the test :

PERL_CORE=1

indicates that we're running this test part of the perl core test suite. This is useful for modules that have a dual life on CPAN.

PERL_DESTRUCT_LEVEL=2

is set to 2 if it isn't set already (see PERL_DESTRUCT_LEVEL)

PERL

(used only by t/TEST) if set, overrides the path to the perl executable that should be used to run the tests (the default being ./perl).

PERL_SKIP_TTY_TEST

if set, tells to skip the tests that need a terminal. It's actually set automatically by the Makefile, but can also be forced artificially by running 'make test_notty'.

EXTERNAL TOOLS FOR DEBUGGING PERL

Sometimes it helps to use external tools while debugging and testing Perl. This section tries to guide you through using some common testing and debugging tools with Perl. This is meant as a guide to interfacing these tools with Perl, not as any kind of guide to the use of the tools themselves.

NOTE 1: Running under memory debuggers such as Purify, valgrind, or Third Degree greatly slows down the execution: seconds become minutes, minutes become hours. For example as of Perl 5.8.1, the ext/Encode/t/Unicode.t takes extraordinarily long to complete under e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more than six hours, even on a snappy computer-- the said test must be doing something that is quite unfriendly for memory debuggers. If you don't feel like waiting, that you can simply kill away the perl process.

NOTE 2: To minimize the number of memory leak false alarms (see PERL_DESTRUCT_LEVEL for more information), you have to have environment variable PERL_DESTRUCT_LEVEL set to 2. The TEST and harness scripts do that automatically. But if you are running some of the tests manually-- for csh-like shells:

    setenv PERL_DESTRUCT_LEVEL 2

and for Bourne-type shells:

    PERL_DESTRUCT_LEVEL=2
    export PERL_DESTRUCT_LEVEL

or in UNIXy environments you can also use the env command:

    env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...

NOTE 3: There are known memory leaks when there are compile-time errors within eval or require, seeing S_doeval in the call stack is a good sign of these. Fixing these leaks is non-trivial, unfortunately, but they must be fixed eventually.

Rational Software's Purify

Purify is a commercial tool that is helpful in identifying memory overruns, wild pointers, memory leaks and other such badness. Perl must be compiled in a specific way for optimal testing with Purify. Purify is available under Windows NT, Solaris, HP-UX, SGI, and Siemens Unix.

Purify on Unix

On Unix, Purify creates a new Perl binary. To get the most benefit out of Purify, you should create the perl to Purify using:

    sh Configure -Accflags=-DPURIFY -Doptimize='-g' \
     -Uusemymalloc -Dusemultiplicity

where these arguments mean:

-Accflags=-DPURIFY

Disables Perl's arena memory allocation functions, as well as forcing use of memory allocation functions derived from the system malloc.

-Doptimize='-g'

Adds debugging information so that you see the exact source statements where the problem occurs. Without this flag, all you will see is the source filename of where the error occurred.

-Uusemymalloc

Disable Perl's malloc so that Purify can more closely monitor allocations and leaks. Using Perl's malloc will make Purify report most leaks in the "potential" leaks category.

-Dusemultiplicity

Enabling the multiplicity option allows perl to clean up thoroughly when the interpreter shuts down, which reduces the number of bogus leak reports from Purify.

Once you've compiled a perl suitable for Purify'ing, then you can just:

    make pureperl

which creates a binary named 'pureperl' that has been Purify'ed. This binary is used in place of the standard 'perl' binary when you want to debug Perl memory problems.

As an example, to show any memory leaks produced during the standard Perl testset you would create and run the Purify'ed perl as:

    make pureperl
    cd t
    ../pureperl -I../lib harness

which would run Perl on test.pl and report any memory problems.

Purify outputs messages in "Viewer" windows by default. If you don't have a windowing environment or if you simply want the Purify output to unobtrusively go to a log file instead of to the interactive window, use these following options to output to the log file "perl.log":

    setenv PURIFYOPTIONS "-chain-length=25 -windows=no \
     -log-file=perl.log -append-logfile=yes"

If you plan to use the "Viewer" windows, then you only need this option:

    setenv PURIFYOPTIONS "-chain-length=25"

In Bourne-type shells:

    PURIFYOPTIONS="..."
    export PURIFYOPTIONS

or if you have the "env" utility:

    env PURIFYOPTIONS="..." ../pureperl ...

Purify on NT

Purify on Windows NT instruments the Perl binary 'perl.exe' on the fly. There are several options in the makefile you should change to get the most use out of Purify:

DEFINES

You should add -DPURIFY to the DEFINES line so the DEFINES line looks something like:

    DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1

to disable Perl's arena memory allocation functions, as well as to force use of memory allocation functions derived from the system malloc.

USE_MULTI = define

Enabling the multiplicity option allows perl to clean up thoroughly when the interpreter shuts down, which reduces the number of bogus leak reports from Purify.

#PERL_MALLOC = define

Disable Perl's malloc so that Purify can more closely monitor allocations and leaks. Using Perl's malloc will make Purify report most leaks in the "potential" leaks category.

CFG = Debug

Adds debugging information so that you see the exact source statements where the problem occurs. Without this flag, all you will see is the source filename of where the error occurred.

As an example, to show any memory leaks produced during the standard Perl testset you would create and run Purify as:

    cd win32
    make
    cd ../t
    purify ../perl -I../lib harness

which would instrument Perl in memory, run Perl on test.pl, then finally report any memory problems.

valgrind

The excellent valgrind tool can be used to find out both memory leaks and illegal memory accesses. As of August 2003 it unfortunately works only on x86 (ELF) Linux. The special "test.valgrind" target can be used to run the tests under valgrind. Found errors and memory leaks are logged in files named test.valgrind.

As system libraries (most notably glibc) are also triggering errors, valgrind allows to suppress such errors using suppression files. The default suppression file that comes with valgrind already catches a lot of them. Some additional suppressions are defined in t/perl.supp.

To get valgrind and for more information see

    http://developer.kde.org/~sewardj/

Compaq's/Digital's/HP's Third Degree

Third Degree is a tool for memory leak detection and memory access checks. It is one of the many tools in the ATOM toolkit. The toolkit is only available on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1).

When building Perl, you must first run Configure with -Doptimize=-g and -Uusemymalloc flags, after that you can use the make targets "perl.third" and "test.third". (What is required is that Perl must be compiled using the -g flag, you may need to re-Configure.)

The short story is that with "atom" you can instrument the Perl executable to create a new executable called perl.third. When the instrumented executable is run, it creates a log of dubious memory traffic in file called perl.3log. See the manual pages of atom and third for more information. The most extensive Third Degree documentation is available in the Compaq "Tru64 UNIX Programmer's Guide", chapter "Debugging Programs with Third Degree".

The "test.third" leaves a lot of files named foo_bar.3log in the t/ subdirectory. There is a problem with these files: Third Degree is so effective that it finds problems also in the system libraries. Therefore you should used the Porting/thirdclean script to cleanup the *.3log files.

There are also leaks that for given certain definition of a leak, aren't. See PERL_DESTRUCT_LEVEL for more information.

PERL_DESTRUCT_LEVEL

If you want to run any of the tests yourself manually using e.g. valgrind, or the pureperl or perl.third executables, please note that by default perl does not explicitly cleanup all the memory it has allocated (such as global memory arenas) but instead lets the exit() of the whole program "take care" of such allocations, also known as "global destruction of objects".

There is a way to tell perl to do complete cleanup: set the environment variable PERL_DESTRUCT_LEVEL to a non-zero value. The t/TEST wrapper does set this to 2, and this is what you need to do too, if you don't want to see the "global leaks": For example, for "third-degreed" Perl:

        env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t

(Note: the mod_perl apache module uses also this environment variable for its own purposes and extended its semantics. Refer to the mod_perl documentation for more information. Also, spawned threads do the equivalent of setting this variable to the value 1.)

If, at the end of a run you get the message N scalars leaked, you can recompile with -DDEBUG_LEAKING_SCALARS, which will cause the addresses of all those leaked SVs to be dumped; it also converts new_SV() from a macro into a real function, so you can use your favourite debugger to discover where those pesky SVs were allocated.

Profiling

Depending on your platform there are various of profiling Perl.

There are two commonly used techniques of profiling executables: statistical time-sampling and basic-block counting.

The first method takes periodically samples of the CPU program counter, and since the program counter can be correlated with the code generated for functions, we get a statistical view of in which functions the program is spending its time. The caveats are that very small/fast functions have lower probability of showing up in the profile, and that periodically interrupting the program (this is usually done rather frequently, in the scale of milliseconds) imposes an additional overhead that may skew the results. The first problem can be alleviated by running the code for longer (in general this is a good idea for profiling), the second problem is usually kept in guard by the profiling tools themselves.

The second method divides up the generated code into basic blocks. Basic blocks are sections of code that are entered only in the beginning and exited only at the end. For example, a conditional jump starts a basic block. Basic block profiling usually works by instrumenting the code by adding enter basic block #nnnn book-keeping code to the generated code. During the execution of the code the basic block counters are then updated appropriately. The caveat is that the added extra code can skew the results: again, the profiling tools usually try to factor their own effects out of the results.

Gprof Profiling

gprof is a profiling tool available in many UNIX platforms, it uses statistical time-sampling.

You can build a profiled version of perl called "perl.gprof" by invoking the make target "perl.gprof" (What is required is that Perl must be compiled using the -pg flag, you may need to re-Configure). Running the profiled version of Perl will create an output file called gmon.out is created which contains the profiling data collected during the execution.

The gprof tool can then display the collected data in various ways. Usually gprof understands the following options:

-a

Suppress statically defined functions from the profile.

-b

Suppress the verbose descriptions in the profile.

-e routine

Exclude the given routine and its descendants from the profile.

-f routine

Display only the given routine and its descendants in the profile.

-s

Generate a summary file called gmon.sum which then may be given to subsequent gprof runs to accumulate data over several runs.

-z

Display routines that have zero usage.

For more detailed explanation of the available commands and output formats, see your own local documentation of gprof.

GCC gcov Profiling

Starting from GCC 3.0 basic block profiling is officially available for the GNU CC.

You can build a profiled version of perl called perl.gcov by invoking the make target "perl.gcov" (what is required that Perl must be compiled using gcc with the flags -fprofile-arcs -ftest-coverage, you may need to re-Configure).

Running the profiled version of Perl will cause profile output to be generated. For each source file an accompanying ".da" file will be created.

To display the results you use the "gcov" utility (which should be installed if you have gcc 3.0 or newer installed). gcov is run on source code files, like this

    gcov sv.c

which will cause sv.c.gcov to be created. The .gcov files contain the source code annotated with relative frequencies of execution indicated by "#" markers.

Useful options of gcov include -b which will summarise the basic block, branch, and function call coverage, and -c which instead of relative frequencies will use the actual counts. For more information on the use of gcov and basic block profiling with gcc, see the latest GNU CC manual, as of GCC 3.0 see

    http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html

and its section titled "8. gcov: a Test Coverage Program"

    http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132

Pixie Profiling

Pixie is a profiling tool available on IRIX and Tru64 (aka Digital UNIX aka DEC OSF/1) platforms. Pixie does its profiling using basic-block counting.

You can build a profiled version of perl called perl.pixie by invoking the make target "perl.pixie" (what is required is that Perl must be compiled using the -g flag, you may need to re-Configure).

In Tru64 a file called perl.Addrs will also be silently created, this file contains the addresses of the basic blocks. Running the profiled version of Perl will create a new file called "perl.Counts" which contains the counts for the basic block for that particular program execution.

To display the results you use the prof utility. The exact incantation depends on your operating system, "prof perl.Counts" in IRIX, and "prof -pixie -all -L. perl" in Tru64.

In IRIX the following prof options are available:

-h

Reports the most heavily used lines in descending order of use. Useful for finding the hotspot lines.

-l

Groups lines by procedure, with procedures sorted in descending order of use. Within a procedure, lines are listed in source order. Useful for finding the hotspots of procedures.

In Tru64 the following options are available:

-p[rocedures]

Procedures sorted in descending order by the number of cycles executed in each procedure. Useful for finding the hotspot procedures. (This is the default option.)

-h[eavy]

Lines sorted in descending order by the number of cycles executed in each line. Useful for finding the hotspot lines.

-i[nvocations]

The called procedures are sorted in descending order by number of calls made to the procedures. Useful for finding the most used procedures.

-l[ines]

Grouped by procedure, sorted by cycles executed per procedure. Useful for finding the hotspots of procedures.

-testcoverage

The compiler emitted code for these lines, but the code was unexecuted.

-z[ero]

Unexecuted procedures.

For further information, see your system's manual pages for pixie and prof.

Miscellaneous tricks

  • Those debugging perl with the DDD frontend over gdb may find the following useful:

    You can extend the data conversion shortcuts menu, so for example you can display an SV's IV value with one click, without doing any typing. To do that simply edit ~/.ddd/init file and add after:

      ! Display shortcuts.
  Ddd*gdbDisplayShortcuts: \
  /t ()   // Convert to Bin\n\
  /d ()   // Convert to Dec\n\
  /x ()   // Convert to Hex\n\
  /o ()   // Convert to Oct(\n\

    the following two lines:

      ((XPV*) (())->sv_any )->xpv_pv  // 2pvx\n\
  ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx

    so now you can do ivx and pvx lookups or you can plug there the sv_peek "conversion":

      Perl_sv_peek(my_perl, (SV*)()) // sv_peek

    (The my_perl is for threaded builds.) Just remember that every line, but the last one, should end with \n\

    Alternatively edit the init file interactively via: 3rd mouse button -> New Display -> Edit Menu

    Note: you can define up to 20 conversion shortcuts in the gdb section.

  • If you see in a debugger a memory area mysteriously full of 0xabababab, you may be seeing the effect of the Poison() macro, see the perlclib manpage.

CONCLUSION

We've had a brief look around the Perl source, an overview of the stages perl goes through when it's running your code, and how to use a debugger to poke at the Perl guts. We took a very simple problem and demonstrated how to solve it fully - with documentation, regression tests, and finally a patch for submission to p5p. Finally, we talked about how to use external tools to debug and test Perl.

I'd now suggest you read over those references again, and then, as soon as possible, get your hands dirty. The best way to learn is by doing, so:

  • Subscribe to perl5-porters, follow the patches and try and understand them; don't be afraid to ask if there's a portion you're not clear on - who knows, you may unearth a bug in the patch...

  • Keep up to date with the bleeding edge Perl distributions and get familiar with the changes. Try and get an idea of what areas people are working on and the changes they're making.

  • Do read the README associated with your operating system, e.g. README.aix on the IBM AIX OS. Don't hesitate to supply patches to that README if you find anything missing or changed over a new OS release.

  • Find an area of Perl that seems interesting to you, and see if you can work out how it works. Scan through the source, and step over it in the debugger. Play, poke, investigate, fiddle! You'll probably get to understand not just your chosen area but a much wider range of perl's activity as well, and probably sooner than you'd think.

The Road goes ever on and on, down from the door where it began.

If you can do these things, you've started on the long road to Perl porting. Thanks for wanting to help make Perl better - and happy hacking!

AUTHOR

This document was written by Nathan Torkington, and is maintained by the perl5-porters mailing list.


perlintern - autogenerated documentation of purely B<internal> Perl functions

  • CV reference counts and CvOUTSIDE
  • Functions in file pad.h
  • Functions in file pp_ctl.c
  • Global Variables
  • GV Functions
  • IO Functions
  • Pad Data Structures
  • Stack Manipulation Macros
  • SV Manipulation Functions
  • AUTHORS
  • SEE ALSO

NAME

perlintern - autogenerated documentation of purely internal
Perl functions

DESCRIPTION

This file is the autogenerated documentation of functions in the Perl interpreter that are documented using Perl's internal documentation format but are not marked as part of the Perl API. In other words, they are not for use in extensions!

CV reference counts and CvOUTSIDE

CvWEAKOUTSIDE

Each CV has a pointer, CvOUTSIDE(), to its lexically enclosing CV (if any). Because pointers to anonymous sub prototypes are stored in & pad slots, it is a possible to get a circular reference, with the parent pointing to the child and vice-versa. To avoid the ensuing memory leak, we do not increment the reference count of the CV pointed to by CvOUTSIDE in the one specific instance that the parent has a & pad slot pointing back to us. In this case, we set the CvWEAKOUTSIDE flag in the child. This allows us to determine under what circumstances we should decrement the refcount of the parent when freeing the child.

There is a further complication with non-closure anonymous subs (i.e. those that do not refer to any lexicals outside that sub). In this case, the anonymous prototype is shared rather than being cloned. This has the consequence that the parent may be freed while there are still active children, eg

    BEGIN { $a = sub { eval '$x' } }

In this case, the BEGIN is freed immediately after execution since there are no active references to it: the anon sub prototype has CvWEAKOUTSIDE set since it's not a closure, and $a points to the same CV, so it doesn't contribute to BEGIN's refcount either. When $a is executed, the eval '$x' causes the chain of CvOUTSIDEs to be followed, and the freed BEGIN is accessed.

To avoid this, whenever a CV and its associated pad is freed, any & entries in the pad are explicitly removed from the pad, and if the refcount of the pointed-to anon sub is still positive, then that child's CvOUTSIDE is set to point to its grandparent. This will only occur in the single specific case of a non-closure anon prototype having one or more active references (such as $a above).

One other thing to consider is that a CV may be merely undefined rather than freed, eg undef &foo. In this case, its refcount may not have reached zero, but we still delete its pad and its CvROOT etc. Since various children may still have their CvOUTSIDE pointing at this undefined CV, we keep its own CvOUTSIDE for the time being, so that the chain of lexical scopes is unbroken. For example, the following should print 123:

    my $x = 123;
    sub tmp { sub { eval '$x' } }
    my $a = tmp();
    undef &tmp;
    print  $a->();

        bool    CvWEAKOUTSIDE(CV *cv)

Functions in file pad.h

CX_CURPAD_SAVE

Save the current pad in the given context block structure.

        void    CX_CURPAD_SAVE(struct context)
CX_CURPAD_SV

Access the SV at offset po in the saved current pad in the given context block structure (can be used as an lvalue).

        SV *    CX_CURPAD_SV(struct context, PADOFFSET po)
PAD_BASE_SV

Get the value from slot po in the base (DEPTH=1) pad of a padlist

        SV *    PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
PAD_CLONE_VARS

|CLONE_PARAMS* param Clone the state variables associated with running and compiling pads.

        void    PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
PAD_COMPNAME_FLAGS

Return the flags for the current compiling pad name at offset po. Assumes a valid slot entry.

        U32     PAD_COMPNAME_FLAGS(PADOFFSET po)
PAD_COMPNAME_GEN

The generation number of the name at offset po in the current compiling pad (lvalue). Note that SvCUR is hijacked for this purpose.

        STRLEN  PAD_COMPNAME_GEN(PADOFFSET po)
PAD_COMPNAME_GEN_set

Sets the generation number of the name at offset po in the current ling pad (lvalue) to gen. Note that SvCUR_set is hijacked for this purpose.

        STRLEN  PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
PAD_COMPNAME_OURSTASH

Return the stash associated with an our variable. Assumes the slot entry is a valid our lexical.

        HV *    PAD_COMPNAME_OURSTASH(PADOFFSET po)
PAD_COMPNAME_PV

Return the name of the current compiling pad name at offset po. Assumes a valid slot entry.

        char *  PAD_COMPNAME_PV(PADOFFSET po)
PAD_COMPNAME_TYPE

Return the type (stash) of the current compiling pad name at offset po. Must be a valid name. Returns null if not typed.

        HV *    PAD_COMPNAME_TYPE(PADOFFSET po)
PAD_DUP

Clone a padlist.

        void    PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
PAD_RESTORE_LOCAL

Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()

        void    PAD_RESTORE_LOCAL(PAD *opad)
PAD_SAVE_LOCAL

Save the current pad to the local variable opad, then make the current pad equal to npad

        void    PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
PAD_SAVE_SETNULLPAD

Save the current pad then set it to null.

        void    PAD_SAVE_SETNULLPAD()
PAD_SETSV

Set the slot at offset po in the current pad to sv

        SV *    PAD_SETSV(PADOFFSET po, SV* sv)
PAD_SET_CUR

Set the current pad to be pad n in the padlist, saving the previous current pad. NB currently this macro expands to a string too long for some compilers, so it's best to replace it with

    SAVECOMPPAD();
    PAD_SET_CUR_NOSAVE(padlist,n);

        void    PAD_SET_CUR(PADLIST padlist, I32 n)
PAD_SET_CUR_NOSAVE

like PAD_SET_CUR, but without the save

        void    PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
PAD_SV

Get the value at offset po in the current pad

        void    PAD_SV(PADOFFSET po)
PAD_SVl

Lightweight and lvalue version of PAD_SV. Get or set the value at offset po in the current pad. Unlike PAD_SV, does not print diagnostics with -DX. For internal use only.

        SV *    PAD_SVl(PADOFFSET po)
SAVECLEARSV

Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')

        void    SAVECLEARSV(SV **svp)
SAVECOMPPAD

save PL_comppad and PL_curpad

        void    SAVECOMPPAD()
SAVEPADSV

Save a pad slot (used to restore after an iteration)

XXX DAPM it would make more sense to make the arg a PADOFFSET
void SAVEPADSV(PADOFFSET po)

Functions in file pp_ctl.c

find_runcv

Locate the CV corresponding to the currently executing sub or eval. If db_seqp is non_null, skip CVs that are in the DB package and populate *db_seqp with the cop sequence number at the point that the DB:: code was entered. (allows debuggers to eval in the scope of the breakpoint rather than in the scope of the debugger itself).

        CV*     find_runcv(U32 *db_seqp)

Global Variables

PL_DBsingle

When Perl is run in debugging mode, with the -d switch, this SV is a boolean which indicates whether subs are being single-stepped. Single-stepping is automatically turned on after every step. This is the C variable which corresponds to Perl's $DB::single variable. See PL_DBsub.

        SV *    PL_DBsingle
PL_DBsub

When Perl is run in debugging mode, with the -d switch, this GV contains the SV which holds the name of the sub being debugged. This is the C variable which corresponds to Perl's $DB::sub variable. See PL_DBsingle.

        GV *    PL_DBsub
PL_DBtrace

Trace variable used when Perl is run in debugging mode, with the -d switch. This is the C variable which corresponds to Perl's $DB::trace variable. See PL_DBsingle.

        SV *    PL_DBtrace
PL_dowarn

The C variable which corresponds to Perl's $^W warning variable.

        bool    PL_dowarn
PL_last_in_gv

The GV which was last used for a filehandle input operation. (<FH>)

        GV*     PL_last_in_gv
PL_ofs_sv

The output field separator - $, in Perl space.

        SV*     PL_ofs_sv
PL_rs

The input record separator - $/ in Perl space.

        SV*     PL_rs

GV Functions

is_gv_magical

Returns TRUE if given the name of a magical GV.

Currently only useful internally when determining if a GV should be created even in rvalue contexts.

flags is not used at present but available for future extension to allow selecting particular classes of magical variable.

Currently assumes that name is NUL terminated (as well as len being valid). This assumption is met by all callers within the perl core, which all pass pointers returned by SvPV.

        bool    is_gv_magical(char *name, STRLEN len, U32 flags)

IO Functions

start_glob

Function called by do_readline to spawn a glob (or do the glob inside perl on VMS). This code used to be inline, but now perl uses File::Glob this glob starter is only used by miniperl during the build process. Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.

        PerlIO* start_glob(SV* pattern, IO *io)

Pad Data Structures

CvPADLIST

CV's can have CvPADLIST(cv) set to point to an AV.

For these purposes "forms" are a kind-of CV, eval""s are too (except they're not callable at will and are always thrown away after the eval"" is done executing).

XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, but that is really the callers pad (a slot of which is allocated by every entersub).

The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items is managed "manual" (mostly in pad.c) rather than normal av.c rules. The items in the AV are not SVs as for a normal AV, but other AVs:

0'th Entry of the CvPADLIST is an AV which represents the "names" or rather the "static type information" for lexicals.

The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that depth of recursion into the CV. The 0'th slot of a frame AV is an AV which is @_. other entries are storage for variables and op targets.

During compilation: PL_comppad_name is set to the names AV. PL_comppad is set to the frame AV for the frame CvDEPTH == 1. PL_curpad is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).

During execution, PL_comppad and PL_curpad refer to the live frame of the currently executing sub.

Iterating over the names AV iterates over all possible pad items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having &PL_sv_undef "names" (see pad_alloc()).

Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. The rest are op targets/GVs/constants which are statically allocated or resolved at compile time. These don't have names by which they can be looked up from Perl code at run time through eval"" like my/our variables can be. Since they can't be looked up by "name" but only by their index allocated at compile time (which is usually in PL_op->op_targ), wasting a name SV for them doesn't make sense.

The SVs in the names AV have their PV being the name of the variable. NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type. For our lexicals, the type is SVt_PVGV, and GvSTASH points at the stash of the associated global (so that duplicate our declarations in the same package can be detected). SvCUR is sometimes hijacked to store the generation number during compilation.

If SvFAKE is set on the name SV then slot in the frame AVs are a REFCNT'ed references to a lexical from "outside". In this case, the name SV does not have a cop_seq range, since it is in scope throughout.

If the 'name' is '&' the corresponding entry in frame AV is a CV representing a possible closure. (SvFAKE and name of '&' is not a meaningful combination currently but could become so if my sub foo {} is implemented.)

The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, and set on scope exit. This allows the 'Variable $x is not available' warning to be generated in evals, such as

    { my $x = 1; sub f { eval '$x'} } f();

        AV *    CvPADLIST(CV *cv)
cv_clone

Clone a CV: make a new CV which points to the same code etc, but which has a newly-created pad built by copying the prototype pad and capturing any outer lexicals.

        CV*     cv_clone(CV* proto)
cv_dump

dump the contents of a CV

        void    cv_dump(const CV *cv, const char *title)
do_dump_pad

Dump the contents of a padlist

        void    do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
intro_my

"Introduce" my variables to visible status.

        U32     intro_my()
pad_add_anon

Add an anon code entry to the current compiling pad

        PADOFFSET       pad_add_anon(SV* sv, OPCODE op_type)
pad_add_name

Create a new name in the current pad at the specified offset. If typestash is valid, the name is for a typed lexical; set the name's stash to that value. If ourstash is valid, it's an our lexical, set the name's GvSTASH to that value

Also, if the name is @.. or %.., create a new array or hash for that slot

If fake, it means we're cloning an existing entry

        PADOFFSET       pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
pad_alloc

Allocate a new my or tmp pad entry. For a my, simply push a null SV onto the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards for a slot which has no name and no active value.

        PADOFFSET       pad_alloc(I32 optype, U32 tmptype)
pad_block_start

Update the pad compilation state variables on entry to a new block

        void    pad_block_start(int full)
pad_check_dup

Check for duplicate declarations: report any of: * a my in the current scope with the same name; * an our (anywhere in the pad) with the same name and the same stash as ourstash is_our indicates that the name to check is an 'our' declaration

        void    pad_check_dup(char* name, bool is_our, HV* ourstash)
pad_findlex

Find a named lexical anywhere in a chain of nested pads. Add fake entries in the inner pads if it's found in an outer one. innercv is the CV *inside* the chain of outer CVs to be searched. If newoff is non-null, this is a run-time cloning: don't add fake entries, just find the lexical and add a ref to it at newoff in the current pad.

        PADOFFSET       pad_findlex(const char* name, PADOFFSET newoff, const CV* innercv)
pad_findmy

Given a lexical name, try to find its offset, first in the current pad, or failing that, in the pads of any lexically enclosing subs (including the complications introduced by eval). If the name is found in an outer pad, then a fake entry is added to the current pad. Returns the offset in the current pad, or NOT_IN_PAD on failure.

        PADOFFSET       pad_findmy(char* name)
pad_fixup_inner_anons

For any anon CVs in the pad, change CvOUTSIDE of that CV from old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be moved to a pre-existing CV struct.

        void    pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
pad_free

Free the SV at offset po in the current pad.

        void    pad_free(PADOFFSET po)
pad_leavemy

Cleanup at end of scope during compilation: set the max seq number for lexicals in this scope and warn of any lexicals that never got introduced.

        void    pad_leavemy()
pad_new

Create a new compiling padlist, saving and updating the various global vars at the same time as creating the pad itself. The following flags can be OR'ed together:

    padnew_CLONE        this pad is for a cloned CV
    padnew_SAVE         save old globals
    padnew_SAVESUB      also save extra stuff for start of sub
        PADLIST*        pad_new(int flags)
pad_push

Push a new pad frame onto the padlist, unless there's already a pad at this depth, in which case don't bother creating a new one. If has_args is true, give the new pad an @_ in slot zero.

        void    pad_push(PADLIST *padlist, int depth, int has_args)
pad_reset

Mark all the current temporaries for reuse

        void    pad_reset()
pad_setsv

Set the entry at offset po in the current pad to sv. Use the macro PAD_SETSV() rather than calling this function directly.

        void    pad_setsv(PADOFFSET po, SV* sv)
pad_swipe

Abandon the tmp in the current pad at offset po and replace with a new one.

        void    pad_swipe(PADOFFSET po, bool refadjust)
pad_tidy

Tidy up a pad after we've finished compiling it: * remove most stuff from the pads of anonsub prototypes; * give it a @_; * mark tmps as such.

        void    pad_tidy(padtidy_type type)
pad_undef

Free the padlist associated with a CV. If parts of it happen to be current, we null the relevant PL_*pad* global vars so that we don't have any dangling references left. We also repoint the CvOUTSIDE of any about-to-be-orphaned inner subs to the outer of this cv.

(This function should really be called pad_free, but the name was already taken)

        void    pad_undef(CV* cv)

Stack Manipulation Macros

djSP

Declare Just SP. This is actually identical to dSP, and declares a local copy of perl's stack pointer, available via the SP macro. See SP. (Available for backward source code compatibility with the old (Perl 5.005) thread model.)

                djSP;
LVRET

True if this op will be the return value of an lvalue subroutine

SV Manipulation Functions

report_uninit

Print appropriate "Use of uninitialized variable" warning

        void    report_uninit()
sv_add_arena

Given a chunk of memory, link it to the head of the list of arenas, and split it into a list of free SVs.

        void    sv_add_arena(char* ptr, U32 size, U32 flags)
sv_clean_all

Decrement the refcnt of each remaining SV, possibly triggering a cleanup. This function may have to be called multiple times to free SVs which are in complex self-referential hierarchies.

        I32     sv_clean_all()
sv_clean_objs

Attempt to destroy all objects not yet freed

        void    sv_clean_objs()
sv_free_arenas

Deallocate the memory used by all arenas. Note that all the individual SV heads and bodies within the arenas must already have been freed.

        void    sv_free_arenas()

AUTHORS

The autodocumentation system was originally added to the Perl core by Benjamin Stuhl. Documentation is by whoever was kind enough to document their functions.

SEE ALSO

perlguts(1), perlapi(1)


perliol - C API for Perl's implementation of IO in Layers.

    • History and Background
    • Basic Structure
    • Layers vs Disciplines
    • Data Structures
    • Functions and Attributes
    • Per-instance Data
    • Layers in action.
    • Per-instance flag bits
    • Methods in Detail
    • Utilities
    • Implementing PerlIO Layers
    • Core Layers
    • Extension Layers
  • TODO

NAME

perliol - C API for Perl's implementation of IO in Layers.

SYNOPSIS

    /* Defining a layer ... */
    #include <perliol.h>

DESCRIPTION

This document describes the behavior and implementation of the PerlIO abstraction described in the perlapio manpage when USE_PERLIO is defined (and USE_SFIO is not).

History and Background

The PerlIO abstraction was introduced in perl5.003_02 but languished as just an abstraction until perl5.7.0. However during that time a number of perl extensions switched to using it, so the API is mostly fixed to maintain (source) compatibility.

The aim of the implementation is to provide the PerlIO API in a flexible and platform neutral manner. It is also a trial of an "Object Oriented C, with vtables" approach which may be applied to perl6.

Basic Structure

PerlIO is a stack of layers.

The low levels of the stack work with the low-level operating system calls (file descriptors in C) getting bytes in and out, the higher layers of the stack buffer, filter, and otherwise manipulate the I/O, and return characters (or bytes) to Perl. Terms above and below are used to refer to the relative positioning of the stack layers.

A layer contains a "vtable", the table of I/O operations (at C level a table of function pointers), and status flags. The functions in the vtable implement operations like "open", "read", and "write".

When I/O, for example "read", is requested, the request goes from Perl first down the stack using "read" functions of each layer, then at the bottom the input is requested from the operating system services, then the result is returned up the stack, finally being interpreted as Perl data.

The requests do not necessarily go always all the way down to the operating system: that's where PerlIO buffering comes into play.

When you do an open() and specify extra PerlIO layers to be deployed, the layers you specify are "pushed" on top of the already existing default stack. One way to see it is that "operating system is on the left" and "Perl is on the right".

What exact layers are in this default stack depends on a lot of things: your operating system, Perl version, Perl compile time configuration, and Perl runtime configuration. See the PerlIO manpage, PERLIO in the perlrun manpage, and the open manpage for more information.

binmode() operates similarly to open(): by default the specified layers are pushed on top of the existing stack.

However, note that even as the specified layers are "pushed on top" for open() and binmode(), this doesn't mean that the effects are limited to the "top": PerlIO layers can be very 'active' and inspect and affect layers also deeper in the stack. As an example there is a layer called "raw" which repeatedly "pops" layers until it reaches the first layer that has declared itself capable of handling binary data. The "pushed" layers are processed in left-to-right order.

sysopen() operates (unsurprisingly) at a lower level in the stack than open(). For example in UNIX or UNIX-like systems sysopen() operates directly at the level of file descriptors: in the terms of PerlIO layers, it uses only the "unix" layer, which is a rather thin wrapper on top of the UNIX file descriptors.

Layers vs Disciplines

Initial discussion of the ability to modify IO streams behaviour used the term "discipline" for the entities which were added. This came (I believe) from the use of the term in "sfio", which in turn borrowed it from "line disciplines" on Unix terminals. However, this document (and the C code) uses the term "layer".

This is, I hope, a natural term given the implementation, and should avoid connotations that are inherent in earlier uses of "discipline" for things which are rather different.

Data Structures

The basic data structure is a PerlIOl:

        typedef struct _PerlIO PerlIOl;
        typedef struct _PerlIO_funcs PerlIO_funcs;
        typedef PerlIOl *PerlIO;

        struct _PerlIO
        {
         PerlIOl *      next;       /* Lower layer */
         PerlIO_funcs * tab;        /* Functions for this layer */
         IV             flags;      /* Various flags for state */
        };

A PerlIOl * is a pointer to the struct, and the application level PerlIO * is a pointer to a PerlIOl * - i.e. a pointer to a pointer to the struct. This allows the application level PerlIO * to remain constant while the actual PerlIOl * underneath changes. (Compare perl's SV * which remains constant while its sv_any field changes as the scalar's type changes.) An IO stream is then in general represented as a pointer to this linked-list of "layers".

It should be noted that because of the double indirection in a PerlIO *, a &(perlio->next) "is" a PerlIO *, and so to some degree at least one layer can use the "standard" API on the next layer down.

A "layer" is composed of two parts:

  1. The functions and attributes of the "layer class".

  2. The per-instance data for a particular handle.

Functions and Attributes

The functions and attributes are accessed via the "tab" (for table) member of PerlIOl. The functions (methods of the layer "class") are fixed, and are defined by the PerlIO_funcs type. They are broadly the same as the public PerlIO_xxxxx functions:

  struct _PerlIO_funcs
  {
   Size_t               fsize;
   char *               name;
   Size_t               size;
   IV           kind;
   IV           (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab);
   IV           (*Popped)(pTHX_ PerlIO *f);
   PerlIO *     (*Open)(pTHX_ PerlIO_funcs *tab,
                        AV *layers, IV n,
                        const char *mode,
                        int fd, int imode, int perm,
                        PerlIO *old,
                        int narg, SV **args);
   IV           (*Binmode)(pTHX_ PerlIO *f);
   SV *         (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
   IV           (*Fileno)(pTHX_ PerlIO *f);
   PerlIO *     (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
   /* Unix-like functions - cf sfio line disciplines */
   SSize_t      (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
   SSize_t      (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
   SSize_t      (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
   IV           (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
   Off_t        (*Tell)(pTHX_ PerlIO *f);
   IV           (*Close)(pTHX_ PerlIO *f);
   /* Stdio-like buffered IO functions */
   IV           (*Flush)(pTHX_ PerlIO *f);
   IV           (*Fill)(pTHX_ PerlIO *f);
   IV           (*Eof)(pTHX_ PerlIO *f);
   IV           (*Error)(pTHX_ PerlIO *f);
   void         (*Clearerr)(pTHX_ PerlIO *f);
   void         (*Setlinebuf)(pTHX_ PerlIO *f);
   /* Perl's snooping functions */
   STDCHAR *    (*Get_base)(pTHX_ PerlIO *f);
   Size_t       (*Get_bufsiz)(pTHX_ PerlIO *f);
   STDCHAR *    (*Get_ptr)(pTHX_ PerlIO *f);
   SSize_t      (*Get_cnt)(pTHX_ PerlIO *f);
   void         (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
  };

The first few members of the struct give a function table size for compatibility check "name" for the layer, the size to malloc for the per-instance data, and some flags which are attributes of the class as whole (such as whether it is a buffering layer), then follow the functions which fall into four basic groups:

  1. Opening and setup functions

  2. Basic IO operations

  3. Stdio class buffering options.

  4. Functions to support Perl's traditional "fast" access to the buffer.

A layer does not have to implement all the functions, but the whole table has to be present. Unimplemented slots can be NULL (which will result in an error when called) or can be filled in with stubs to "inherit" behaviour from a "base class". This "inheritance" is fixed for all instances of the layer, but as the layer chooses which stubs to populate the table, limited "multiple inheritance" is possible.

Per-instance Data

The per-instance data are held in memory beyond the basic PerlIOl struct, by making a PerlIOl the first member of the layer's struct thus:

        typedef struct
        {
         struct _PerlIO base;       /* Base "class" info */
         STDCHAR *      buf;        /* Start of buffer */
         STDCHAR *      end;        /* End of valid part of buffer */
         STDCHAR *      ptr;        /* Current position in buffer */
         Off_t          posn;       /* Offset of buf into the file */
         Size_t         bufsiz;     /* Real size of buffer */
         IV             oneword;    /* Emergency buffer */
        } PerlIOBuf;

In this way (as for perl's scalars) a pointer to a PerlIOBuf can be treated as a pointer to a PerlIOl.

Layers in action.

                table           perlio          unix
            |           |
            +-----------+    +----------+    +--------+
   PerlIO ->|           |--->|  next    |--->|  NULL  |
            +-----------+    +----------+    +--------+
            |           |    |  buffer  |    |   fd   |
            +-----------+    |          |    +--------+
            |           |    +----------+

The above attempts to show how the layer scheme works in a simple case. The application's PerlIO * points to an entry in the table(s) representing open (allocated) handles. For example the first three slots in the table correspond to stdin,stdout and stderr. The table in turn points to the current "top" layer for the handle - in this case an instance of the generic buffering layer "perlio". That layer in turn points to the next layer down - in this case the lowlevel "unix" layer.

The above is roughly equivalent to a "stdio" buffered stream, but with much more flexibility:

  • If Unix level read/write/lseek is not appropriate for (say) sockets then the "unix" layer can be replaced (at open time or even dynamically) with a "socket" layer.

  • Different handles can have different buffering schemes. The "top" layer could be the "mmap" layer if reading disk files was quicker using mmap than read. An "unbuffered" stream can be implemented simply by not having a buffer layer.

  • Extra layers can be inserted to process the data as it flows through. This was the driving need for including the scheme in perl 5.7.0+ - we needed a mechanism to allow data to be translated between perl's internal encoding (conceptually at least Unicode as UTF-8), and the "native" format used by the system. This is provided by the ":encoding(xxxx)" layer which typically sits above the buffering layer.

  • A layer can be added that does "\n" to CRLF translation. This layer can be used on any platform, not just those that normally do such things.

Per-instance flag bits

The generic flag bits are a hybrid of O_XXXXX style flags deduced from the mode string passed to PerlIO_open(), and state bits for typical buffer layers.

PERLIO_F_EOF

End of file.

PERLIO_F_CANWRITE

Writes are permitted, i.e. opened as "w" or "r+" or "a", etc.

PERLIO_F_CANREAD

Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick).

PERLIO_F_ERROR

An error has occurred (for PerlIO_error()).

PERLIO_F_TRUNCATE

Truncate file suggested by open mode.

PERLIO_F_APPEND

All writes should be appends.

PERLIO_F_CRLF

Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF mapped to "\n" for input. Normally the provided "crlf" layer is the only layer that need bother about this. PerlIO_binmode() will mess with this flag rather than add/remove layers if the PERLIO_K_CANCRLF bit is set for the layers class.

PERLIO_F_UTF8

Data written to this layer should be UTF-8 encoded; data provided by this layer should be considered UTF-8 encoded. Can be set on any layer by ":utf8" dummy layer. Also set on ":encoding" layer.

PERLIO_F_UNBUF

Layer is unbuffered - i.e. write to next layer down should occur for each write to this layer.

PERLIO_F_WRBUF

The buffer for this layer currently holds data written to it but not sent to next layer.

PERLIO_F_RDBUF

The buffer for this layer currently holds unconsumed data read from layer below.

PERLIO_F_LINEBUF

Layer is line buffered. Write data should be passed to next layer down whenever a "\n" is seen. Any data beyond the "\n" should then be processed.

PERLIO_F_TEMP

File has been unlink()ed, or should be deleted on close().

PERLIO_F_OPEN

Handle is open.

PERLIO_F_FASTGETS

This instance of this layer supports the "fast gets" interface. Normally set based on PERLIO_K_FASTGETS for the class and by the existence of the function(s) in the table. However a class that normally provides that interface may need to avoid it on a particular instance. The "pending" layer needs to do this when it is pushed above a layer which does not support the interface. (Perl's sv_gets() does not expect the streams fast gets behaviour to change during one "get".)

Methods in Detail

fsize
        Size_t fsize;

Size of the function table. This is compared against the value PerlIO code "knows" as a compatibility check. Future versions may be able to tolerate layers compiled against an old version of the headers.

name
        char * name;

The name of the layer whose open() method Perl should invoke on open(). For example if the layer is called APR, you will call:

  open $fh, ">:APR", ...

and Perl knows that it has to invoke the PerlIOAPR_open() method implemented by the APR layer.

size
        Size_t size;

The size of the per-instance data structure, e.g.:

  sizeof(PerlIOAPR)

If this field is zero then PerlIO_pushed does not malloc anything and assumes layer's Pushed function will do any required layer stack manipulation - used to avoid malloc/free overhead for dummy layers. If the field is non-zero it must be at least the size of PerlIOl, PerlIO_pushed will allocate memory for the layer's data structures and link new layer onto the stream's stack. (If the layer's Pushed method returns an error indication the layer is popped again.)

kind
        IV kind;
  • PERLIO_K_BUFFERED

    The layer is buffered.

  • PERLIO_K_RAW

    The layer is acceptable to have in a binmode(FH) stack - i.e. it does not (or will configure itself not to) transform bytes passing through it.

  • PERLIO_K_CANCRLF

    Layer can translate between "\n" and CRLF line ends.

  • PERLIO_K_FASTGETS

    Layer allows buffer snooping.

  • PERLIO_K_MULTIARG

    Used when the layer's open() accepts more arguments than usual. The extra arguments should come not before the MODE argument. When this flag is used it's up to the layer to validate the args.

Pushed
        IV      (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);

The only absolutely mandatory method. Called when the layer is pushed onto the stack. The mode argument may be NULL if this occurs post-open. The arg will be non-NULL if an argument string was passed. In most cases this should call PerlIOBase_pushed() to convert mode into the appropriate PERLIO_F_XXXXX flags in addition to any actions the layer itself takes. If a layer is not expecting an argument it need neither save the one passed to it, nor provide Getarg() (it could perhaps Perl_warn that the argument was un-expected).

Returns 0 on success. On failure returns -1 and should set errno.

Popped
        IV      (*Popped)(pTHX_ PerlIO *f);

Called when the layer is popped from the stack. A layer will normally be popped after Close() is called. But a layer can be popped without being closed if the program is dynamically managing layers on the stream. In such cases Popped() should free any resources (buffers, translation tables, ...) not held directly in the layer's struct. It should also Unread() any unconsumed data that has been read and buffered from the layer below back to that layer, so that it can be re-provided to what ever is now above.

Returns 0 on success and failure. If Popped() returns true then perlio.c assumes that either the layer has popped itself, or the layer is super special and needs to be retained for other reasons. In most cases it should return false.

Open
        PerlIO *        (*Open)(...);

The Open() method has lots of arguments because it combines the functions of perl's open, PerlIO_open, perl's sysopen, PerlIO_fdopen and PerlIO_reopen. The full prototype is as follows:

 PerlIO *       (*Open)(pTHX_ PerlIO_funcs *tab,
                        AV *layers, IV n,
                        const char *mode,
                        int fd, int imode, int perm,
                        PerlIO *old,
                        int narg, SV **args);

Open should (perhaps indirectly) call PerlIO_allocate() to allocate a slot in the table and associate it with the layers information for the opened file, by calling PerlIO_push. The layers AV is an array of all the layers destined for the PerlIO *, and any arguments passed to them, n is the index into that array of the layer being called. The macro PerlIOArg will return a (possibly NULL) SV * for the argument passed to the layer.

The mode string is an "fopen()-like" string which would match the regular expression /^[I#]?[rwa]\+?[bt]?$/.

The 'I' prefix is used during creation of stdin..stderr via special PerlIO_fdopen calls; the '#' prefix means that this is sysopen and that imode and perm should be passed to PerlLIO_open3; 'r' means read, 'w' means write and 'a' means append. The '+' suffix means that both reading and writing/appending are permitted. The 'b' suffix means file should be binary, and 't' means it is text. (Almost all layers should do the IO in binary mode, and ignore the b/t bits. The :crlf layer should be pushed to handle the distinction.)

If old is not NULL then this is a PerlIO_reopen. Perl itself does not use this (yet?) and semantics are a little vague.

If fd not negative then it is the numeric file descriptor fd, which will be open in a manner compatible with the supplied mode string, the call is thus equivalent to PerlIO_fdopen. In this case nargs will be zero.

If nargs is greater than zero then it gives the number of arguments passed to open, otherwise it will be 1 if for example PerlIO_open was called. In simple cases SvPV_nolen(*args) is the pathname to open.

Having said all that translation-only layers do not need to provide Open() at all, but rather leave the opening to a lower level layer and wait to be "pushed". If a layer does provide Open() it should normally call the Open() method of next layer down (if any) and then push itself on top if that succeeds.

If PerlIO_push was performed and open has failed, it must PerlIO_pop itself, since if it's not, the layer won't be removed and may cause bad problems.

Returns NULL on failure.

Binmode
        IV        (*Binmode)(pTHX_ PerlIO *f);

Optional. Used when :raw layer is pushed (explicitly or as a result of binmode(FH)). If not present layer will be popped. If present should configure layer as binary (or pop itself) and return 0. If it returns -1 for error binmode will fail with layer still on the stack.

Getarg
        SV *      (*Getarg)(pTHX_ PerlIO *f,
                            CLONE_PARAMS *param, int flags);

Optional. If present should return an SV * representing the string argument passed to the layer when it was pushed. e.g. ":encoding(ascii)" would return an SvPV with value "ascii". (param and flags arguments can be ignored in most cases)

Dup uses Getarg to retrieve the argument originally passed to Pushed, so you must implement this function if your layer has an extra argument to Pushed and will ever be Duped.

Fileno
        IV        (*Fileno)(pTHX_ PerlIO *f);

Returns the Unix/Posix numeric file descriptor for the handle. Normally PerlIOBase_fileno() (which just asks next layer down) will suffice for this.

Returns -1 on error, which is considered to include the case where the layer cannot provide such a file descriptor.

Dup
        PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
                        CLONE_PARAMS *param, int flags);

XXX: Needs more docs.

Used as part of the "clone" process when a thread is spawned (in which case param will be non-NULL) and when a stream is being duplicated via '&' in the open.

Similar to Open, returns PerlIO* on success, NULL on failure.

Read
        SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);

Basic read operation.

Typically will call Fill and manipulate pointers (possibly via the API). PerlIOBuf_read() may be suitable for derived classes which provide "fast gets" methods.

Returns actual bytes read, or -1 on an error.

Unread
        SSize_t (*Unread)(pTHX_ PerlIO *f,
                          const void *vbuf, Size_t count);

A superset of stdio's ungetc(). Should arrange for future reads to see the bytes in vbuf. If there is no obviously better implementation then PerlIOBase_unread() provides the function by pushing a "fake" "pending" layer above the calling layer.

Returns the number of unread chars.

Write
        SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);

Basic write operation.

Returns bytes written or -1 on an error.

Seek
        IV      (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);

Position the file pointer. Should normally call its own Flush method and then the Seek method of next layer down.

Returns 0 on success, -1 on failure.

Tell
        Off_t   (*Tell)(pTHX_ PerlIO *f);

Return the file pointer. May be based on layers cached concept of position to avoid overhead.

Returns -1 on failure to get the file pointer.

Close
        IV      (*Close)(pTHX_ PerlIO *f);

Close the stream. Should normally call PerlIOBase_close() to flush itself and close layers below, and then deallocate any data structures (buffers, translation tables, ...) not held directly in the data structure.

Returns 0 on success, -1 on failure.

Flush
        IV      (*Flush)(pTHX_ PerlIO *f);

Should make stream's state consistent with layers below. That is, any buffered write data should be written, and file position of lower layers adjusted for data read from below but not actually consumed. (Should perhaps Unread() such data to the lower layer.)

Returns 0 on success, -1 on failure.

Fill
        IV      (*Fill)(pTHX_ PerlIO *f);

The buffer for this layer should be filled (for read) from layer below. When you "subclass" PerlIOBuf layer, you want to use its _read method and to supply your own fill method, which fills the PerlIOBuf's buffer.

Returns 0 on success, -1 on failure.

Eof
        IV      (*Eof)(pTHX_ PerlIO *f);

Return end-of-file indicator. PerlIOBase_eof() is normally sufficient.

Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.

Error
        IV      (*Error)(pTHX_ PerlIO *f);

Return error indicator. PerlIOBase_error() is normally sufficient.

Returns 1 if there is an error (usually when PERLIO_F_ERROR is set, 0 otherwise.

Clearerr
        void    (*Clearerr)(pTHX_ PerlIO *f);

Clear end-of-file and error indicators. Should call PerlIOBase_clearerr() to set the PERLIO_F_XXXXX flags, which may suffice.

Setlinebuf
        void    (*Setlinebuf)(pTHX_ PerlIO *f);

Mark the stream as line buffered. PerlIOBase_setlinebuf() sets the PERLIO_F_LINEBUF flag and is normally sufficient.

Get_base
        STDCHAR *       (*Get_base)(pTHX_ PerlIO *f);

Allocate (if not already done so) the read buffer for this layer and return pointer to it. Return NULL on failure.

Get_bufsiz
        Size_t  (*Get_bufsiz)(pTHX_ PerlIO *f);

Return the number of bytes that last Fill() put in the buffer.

Get_ptr
        STDCHAR *       (*Get_ptr)(pTHX_ PerlIO *f);

Return the current read pointer relative to this layer's buffer.

Get_cnt
        SSize_t (*Get_cnt)(pTHX_ PerlIO *f);

Return the number of bytes left to be read in the current buffer.

Set_ptrcnt
        void    (*Set_ptrcnt)(pTHX_ PerlIO *f,
                              STDCHAR *ptr, SSize_t cnt);

Adjust the read pointer and count of bytes to match ptr and/or cnt. The application (or layer above) must ensure they are consistent. (Checking is allowed by the paranoid.)

Utilities

To ask for the next layer down use PerlIONext(PerlIO *f).

To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All this does is really just to check that the pointer is non-NULL and that the pointer behind that is non-NULL.)

PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words, the PerlIOl* pointer.

PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.

Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either calls the callback from the functions of the layer f (just by the name of the IO function, like "Read") with the args, or if there is no such callback, calls the base version of the callback with the same args, or if the f is invalid, set errno to EBADF and return failure.

Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls the callback of the functions of the layer f with the args, or if there is no such callback, set errno to EINVAL. Or if the f is invalid, set errno to EBADF and return failure.

Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls the callback of the functions of the layer f with the args, or if there is no such callback, calls the base version of the callback with the same args, or if the f is invalid, set errno to EBADF.

Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the callback of the functions of the layer f with the args, or if there is no such callback, set errno to EINVAL. Or if the f is invalid, set errno to EBADF.

Implementing PerlIO Layers

If you find the implementation document unclear or not sufficient, look at the existing PerlIO layer implementations, which include:

  • C implementations

    The perlio.c and perliol.h in the Perl core implement the "unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending" layers, and also the "mmap" and "win32" layers if applicable. (The "win32" is currently unfinished and unused, to see what is used instead in Win32, see Querying the layers of filehandles in the PerlIO manpage .)

    PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.

    PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.

  • Perl implementations

    PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.

If you are creating a PerlIO layer, you may want to be lazy, in other words, implement only the methods that interest you. The other methods you can either replace with the "blank" methods

    PerlIOBase_noop_ok
    PerlIOBase_noop_fail

(which do nothing, and return zero and -1, respectively) or for certain methods you may assume a default behaviour by using a NULL method. The Open method looks for help in the 'parent' layer. The following table summarizes the behaviour:

    method      behaviour with NULL
    Clearerr    PerlIOBase_clearerr
    Close       PerlIOBase_close
    Dup         PerlIOBase_dup
    Eof         PerlIOBase_eof
    Error       PerlIOBase_error
    Fileno      PerlIOBase_fileno
    Fill        FAILURE
    Flush       SUCCESS
    Getarg      SUCCESS
    Get_base    FAILURE
    Get_bufsiz  FAILURE
    Get_cnt     FAILURE
    Get_ptr     FAILURE
    Open        INHERITED
    Popped      SUCCESS
    Pushed      SUCCESS
    Read        PerlIOBase_read
    Seek        FAILURE
    Set_cnt     FAILURE
    Set_ptrcnt  FAILURE
    Setlinebuf  PerlIOBase_setlinebuf
    Tell        FAILURE
    Unread      PerlIOBase_unread
    Write       FAILURE
 FAILURE        Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and
                return -1 (for numeric return values) or NULL (for pointers)
 INHERITED      Inherited from the layer below
 SUCCESS        Return 0 (for numeric return values) or a pointer

Core Layers

The file perlio.c provides the following layers:

"unix"

A basic non-buffered layer which calls Unix/POSIX read(), write(), lseek(), close(). No buffering. Even on platforms that distinguish between O_TEXT and O_BINARY this layer is always O_BINARY.

"perlio"

A very complete generic buffering layer which provides the whole of PerlIO API. It is also intended to be used as a "base class" for other layers. (For example its Read() method is implemented in terms of the Get_cnt()/Get_ptr()/Set_ptrcnt() methods).

"perlio" over "unix" provides a complete replacement for stdio as seen via PerlIO API. This is the default for USE_PERLIO when system's stdio does not permit perl's "fast gets" access, and which do not distinguish between O_TEXT and O_BINARY.

"stdio"

A layer which provides the PerlIO API via the layer scheme, but implements it by calling system's stdio. This is (currently) the default if system's stdio provides sufficient access to allow perl's "fast gets" access and which do not distinguish between O_TEXT and O_BINARY.

"crlf"

A layer derived using "perlio" as a base class. It provides Win32-like "\n" to CR,LF translation. Can either be applied above "perlio" or serve as the buffer layer itself. "crlf" over "unix" is the default if system distinguishes between O_TEXT and O_BINARY opens. (At some point "unix" will be replaced by a "native" Win32 IO layer on that platform, as Win32's read/write layer has various drawbacks.) The "crlf" layer is a reasonable model for a layer which transforms data in some way.

"mmap"

If Configure detects mmap() functions this layer is provided (with "perlio" as a "base") which does "read" operations by mmap()ing the file. Performance improvement is marginal on modern systems, so it is mainly there as a proof of concept. It is likely to be unbundled from the core at some point. The "mmap" layer is a reasonable model for a minimalist "derived" layer.

"pending"

An "internal" derivative of "perlio" which can be used to provide Unread() function for layers which have no buffer or cannot be bothered. (Basically this layer's Fill() pops itself off the stack and so resumes reading from layer below.)

"raw"

A dummy layer which never exists on the layer stack. Instead when "pushed" it actually pops the stack removing itself, it then calls Binmode function table entry on all the layers in the stack - normally this (via PerlIOBase_binmode) removes any layers which do not have PERLIO_K_RAW bit set. Layers can modify that behaviour by defining their own Binmode entry.

"utf8"

Another dummy layer. When pushed it pops itself and sets the PERLIO_F_UTF8 flag on the layer which was (and now is once more) the top of the stack.

In addition perlio.c also provides a number of PerlIOBase_xxxx() functions which are intended to be used in the table slots of classes which do not need to do anything special for a particular method.

Extension Layers

Layers can made available by extension modules. When an unknown layer is encountered the PerlIO code will perform the equivalent of :

   use PerlIO 'layer';

Where layer is the unknown layer. PerlIO.pm will then attempt to:

   require PerlIO::layer;

If after that process the layer is still not defined then the open will fail.

The following extension layers are bundled with perl:

":encoding"
   use Encoding;

makes this layer available, although PerlIO.pm "knows" where to find it. It is an example of a layer which takes an argument as it is called thus:

   open( $fh, "<:encoding(iso-8859-7)", $pathname );
":scalar"

Provides support for reading data from and writing data to a scalar.

   open( $fh, "+<:scalar", \$scalar );

When a handle is so opened, then reads get bytes from the string value of $scalar, and writes change the value. In both cases the position in $scalar starts as zero but can be altered via seek, and determined via tell.

Please note that this layer is implied when calling open() thus:

   open( $fh, "+<", \$scalar );
":via"

Provided to allow layers to be implemented as Perl code. For instance:

   use PerlIO::via::StripHTML;
   open( my $fh, "<:via(StripHTML)", "index.html" );

See the PerlIO::via manpage for details.

TODO

Things that need to be done to improve this document.

  • Explain how to make a valid fh without going through open()(i.e. apply a layer). For example if the file is not opened through perl, but we want to get back a fh, like it was opened by Perl.

    How PerlIO_apply_layera fits in, where its docs, was it made public?

    Currently the example could be something like this:

      PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
  {
      char *mode; /* "w", "r", etc */
      const char *layers = ":APR"; /* the layer name */
      PerlIO *f = PerlIO_allocate(aTHX);
      if (!f) {
          return NULL;
      }

          PerlIO_apply_layers(aTHX_ f, mode, layers);

          if (f) {
          PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
          /* fill in the st struct, as in _open() */
          st->file = file;
          PerlIOBase(f)->flags |= PERLIO_F_OPEN;

              return f;
                }
                return NULL;
            }

  • fix/add the documentation in places marked as XXX.

  • The handling of errors by the layer is not specified. e.g. when $! should be set explicitly, when the error handling should be just delegated to the top layer.

    Probably give some hints on using SETERRNO() or pointers to where they can be found.

  • I think it would help to give some concrete examples to make it easier to understand the API. Of course I agree that the API has to be concise, but since there is no second document that is more of a guide, I think that it'd make it easier to start with the doc which is an API, but has examples in it in places where things are unclear, to a person who is not a PerlIO guru (yet).


perlxs - XS language reference manual

    • Introduction
    • On The Road
    • The Anatomy of an XSUB
    • The Argument Stack
    • The RETVAL Variable
    • Returning SVs, AVs and HVs through RETVAL
    • The MODULE Keyword
    • The PACKAGE Keyword
    • The PREFIX Keyword
    • The OUTPUT: Keyword
    • The NO_OUTPUT Keyword
    • The CODE: Keyword
    • The INIT: Keyword
    • The NO_INIT Keyword
    • Initializing Function Parameters
    • Default Parameter Values
    • The PREINIT: Keyword
    • The SCOPE: Keyword
    • The INPUT: Keyword
    • The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
    • The length(NAME) Keyword
    • Variable-length Parameter Lists
    • The C_ARGS: Keyword
    • The PPCODE: Keyword
    • Returning Undef And Empty Lists
    • The REQUIRE: Keyword
    • The CLEANUP: Keyword
    • The POSTCALL: Keyword
    • The BOOT: Keyword
    • The VERSIONCHECK: Keyword
    • The PROTOTYPES: Keyword
    • The PROTOTYPE: Keyword
    • The ALIAS: Keyword
    • The OVERLOAD: Keyword
    • The FALLBACK: Keyword
    • The INTERFACE: Keyword
    • The INTERFACE_MACRO: Keyword
    • The INCLUDE: Keyword
    • The CASE: Keyword
    • The & Unary Operator
    • Inserting POD, Comments and C Preprocessor Directives
    • Using XS With C++
    • Interface Strategy
    • Perl Objects And C Structures
    • The Typemap
    • Safely Storing Static Data in XS
  • EXAMPLES
  • XS VERSION
  • AUTHOR

NAME

perlxs - XS language reference manual

DESCRIPTION

Introduction

XS is an interface description file format used to create an extension interface between Perl and C code (or a C library) which one wishes to use with Perl. The XS interface is combined with the library to create a new library which can then be either dynamically loaded or statically linked into perl. The XS interface description is written in the XS language and is the core component of the Perl extension interface.

An XSUB forms the basic unit of the XS interface. After compilation by the xsubpp compiler, each XSUB amounts to a C function definition which will provide the glue between Perl calling conventions and C calling conventions.

The glue code pulls the arguments from the Perl stack, converts these Perl values to the formats expected by a C function, call this C function, transfers the return values of the C function back to Perl. Return values here may be a conventional C return value or any C function arguments that may serve as output parameters. These return values may be passed back to Perl either by putting them on the Perl stack, or by modifying the arguments supplied from the Perl side.

The above is a somewhat simplified view of what really happens. Since Perl allows more flexible calling conventions than C, XSUBs may do much more in practice, such as checking input parameters for validity, throwing exceptions (or returning undef/empty list) if the return value from the C function indicates failure, calling different C functions based on numbers and types of the arguments, providing an object-oriented interface, etc.

Of course, one could write such glue code directly in C. However, this would be a tedious task, especially if one needs to write glue for multiple C functions, and/or one is not familiar enough with the Perl stack discipline and other such arcana. XS comes to the rescue here: instead of writing this glue C code in long-hand, one can write a more concise short-hand description of what should be done by the glue, and let the XS compiler xsubpp handle the rest.

The XS language allows one to describe the mapping between how the C routine is used, and how the corresponding Perl routine is used. It also allows creation of Perl routines which are directly translated to C code and which are not related to a pre-existing C function. In cases when the C interface coincides with the Perl interface, the XSUB declaration is almost identical to a declaration of a C function (in K&R style). In such circumstances, there is another tool called h2xs that is able to translate an entire C header file into a corresponding XS file that will provide glue to the functions/macros described in the header file.

The XS compiler is called xsubpp. This compiler creates the constructs necessary to let an XSUB manipulate Perl values, and creates the glue necessary to let Perl call the XSUB. The compiler uses typemaps to determine how to map C function parameters and output values to Perl values and back. The default typemap (which comes with Perl) handles many common C types. A supplementary typemap may also be needed to handle any special structures and types for the library being linked.

A file in XS format starts with a C language section which goes until the first MODULE = directive. Other XS directives and XSUB definitions may follow this line. The "language" used in this part of the file is usually referred to as the XS language. xsubpp recognizes and skips POD (see the perlpod manpage) in both the C and XS language sections, which allows the XS file to contain embedded documentation.

See the perlxstut manpage for a tutorial on the whole extension creation process.

Note: For some extensions, Dave Beazley's SWIG system may provide a significantly more convenient mechanism for creating the extension glue code. See http://www.swig.org/ for more information.

On The Road

Many of the examples which follow will concentrate on creating an interface between Perl and the ONC+ RPC bind library functions. The rpcb_gettime() function is used to demonstrate many features of the XS language. This function has two parameters; the first is an input parameter and the second is an output parameter. The function also returns a status value.

        bool_t rpcb_gettime(const char *host, time_t *timep);

From C this function will be called with the following statements.

     #include <rpc/rpc.h>
     bool_t status;
     time_t timep;
     status = rpcb_gettime( "localhost", &timep );

If an XSUB is created to offer a direct translation between this function and Perl, then this XSUB will be used from Perl with the following code. The $status and $timep variables will contain the output of the function.

     use RPC;
     $status = rpcb_gettime( "localhost", $timep );

The following XS file shows an XS subroutine, or XSUB, which demonstrates one possible interface to the rpcb_gettime() function. This XSUB represents a direct translation between C and Perl and so preserves the interface even from Perl. This XSUB will be invoked from Perl with the usage shown above. Note that the first three #include statements, for EXTERN.h, perl.h, and XSUB.h, will always be present at the beginning of an XS file. This approach and others will be expanded later in this document.

     #include "EXTERN.h"
     #include "perl.h"
     #include "XSUB.h"
     #include <rpc/rpc.h>

     MODULE = RPC  PACKAGE = RPC
     bool_t
     rpcb_gettime(host,timep)
          char *host
          time_t &timep
        OUTPUT:
          timep

Any extension to Perl, including those containing XSUBs, should have a Perl module to serve as the bootstrap which pulls the extension into Perl. This module will export the extension's functions and variables to the Perl program and will cause the extension's XSUBs to be linked into Perl. The following module will be used for most of the examples in this document and should be used from Perl with the use command as shown earlier. Perl modules are explained in more detail later in this document.

     package RPC;

     require Exporter;
     require DynaLoader;
     @ISA = qw(Exporter DynaLoader);
     @EXPORT = qw( rpcb_gettime );

     bootstrap RPC;
     1;

Throughout this document a variety of interfaces to the rpcb_gettime() XSUB will be explored. The XSUBs will take their parameters in different orders or will take different numbers of parameters. In each case the XSUB is an abstraction between Perl and the real C rpcb_gettime() function, and the XSUB must always ensure that the real rpcb_gettime() function is called with the correct parameters. This abstraction will allow the programmer to create a more Perl-like interface to the C function.

The Anatomy of an XSUB

The simplest XSUBs consist of 3 parts: a description of the return value, the name of the XSUB routine and the names of its arguments, and a description of types or formats of the arguments.

The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C function which takes a single argument and returns a single value.

     double
     sin(x)
       double x

Optionally, one can merge the description of types and the list of argument names, rewriting this as

     double
     sin(double x)

This makes this XSUB look similar to an ANSI C declaration. An optional semicolon is allowed after the argument list, as in

     double
     sin(double x);

Parameters with C pointer types can have different semantic: C functions with similar declarations

     bool string_looks_as_a_number(char *s);
     bool make_char_uppercase(char *c);

are used in absolutely incompatible manner. Parameters to these functions could be described xsubpp like this:

     char *  s
     char    &c

Both these XS declarations correspond to the char* C type, but they have different semantics, see The & Unary Operator.

It is convenient to think that the indirection operator * should be considered as a part of the type and the address operator & should be considered part of the variable. See The Typemap for more info about handling qualifiers and unary operators in C types.

The function name and the return type must be placed on separate lines and should be flush left-adjusted.

  INCORRECT                        CORRECT
  double sin(x)                    double
    double x                       sin(x)
                                     double x

The rest of the function description may be indented or left-adjusted. The following example shows a function with its body left-adjusted. Most examples in this document will indent the body for better readability.

  CORRECT
  double
  sin(x)
  double x

More complicated XSUBs may contain many other sections. Each section of an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:. However, the first two lines of an XSUB always contain the same data: descriptions of the return type and the names of the function and its parameters. Whatever immediately follows these is considered to be an INPUT: section unless explicitly marked with another keyword. (See The INPUT: Keyword.)

An XSUB section continues until another section-start keyword is found.

The Argument Stack

The Perl argument stack is used to store the values which are sent as parameters to the XSUB and to store the XSUB's return value(s). In reality all Perl functions (including non-XSUB ones) keep their values on this stack all the same time, each limited to its own range of positions on the stack. In this document the first position on that stack which belongs to the active function will be referred to as position 0 for that function.

XSUBs refer to their stack arguments with the macro ST(x), where x refers to a position in this XSUB's part of the stack. Position 0 for that function would be known to the XSUB as ST(0). The XSUB's incoming parameters and outgoing return values always begin at ST(0). For many simple cases the xsubpp compiler will generate the code necessary to handle the argument stack by embedding code fragments found in the typemaps. In more complex cases the programmer must supply the code.

The RETVAL Variable

The RETVAL variable is a special C variable that is declared automatically for you. The C type of RETVAL matches the return type of the C library function. The xsubpp compiler will declare this variable in each XSUB with non-void return type. By default the generated C function will use RETVAL to hold the return value of the C library function being called. In simple cases the value of RETVAL will be placed in ST(0) of the argument stack where it can be received by Perl as the return value of the XSUB.

If the XSUB has a return type of void then the compiler will not declare a RETVAL variable for that function. When using a PPCODE: section no manipulation of the RETVAL variable is required, the section may use direct stack manipulation to place output values on the stack.

If PPCODE: directive is not used, void return value should be used only for subroutines which do not return a value, even if CODE: directive is used which sets ST(0) explicitly.

Older versions of this document recommended to use void return value in such cases. It was discovered that this could lead to segfaults in cases when XSUB was truly void. This practice is now deprecated, and may be not supported at some future version. Use the return value SV * in such cases. (Currently xsubpp contains some heuristic code which tries to disambiguate between "truly-void" and "old-practice-declared-as-void" functions. Hence your code is at mercy of this heuristics unless you use SV * as return value.)

Returning SVs, AVs and HVs through RETVAL

When you're using RETVAL to return an SV *, there's some magic going on behind the scenes that should be mentioned. When you're manipulating the argument stack using the ST(x) macro, for example, you usually have to pay special attention to reference counts. (For more about reference counts, see the perlguts manpage.) To make your life easier, the typemap file automatically makes RETVAL mortal when you're returning an SV *. Thus, the following two XSUBs are more or less equivalent:

  void
  alpha()
      PPCODE:
          ST(0) = newSVpv("Hello World",0);
          sv_2mortal(ST(0));
          XSRETURN(1);

  SV *
  beta()
      CODE:
          RETVAL = newSVpv("Hello World",0);
      OUTPUT:
          RETVAL

This is quite useful as it usually improves readability. While this works fine for an SV *, it's unfortunately not as easy to have AV * or HV * as a return value. You should be able to write:

  AV *
  array()
      CODE:
          RETVAL = newAV();
          /* do something with RETVAL */
      OUTPUT:
          RETVAL

But due to an unfixable bug (fixing it would break lots of existing CPAN modules) in the typemap file, the reference count of the AV * is not properly decremented. Thus, the above XSUB would leak memory whenever it is being called. The same problem exists for HV *.

When you're returning an AV * or a HV *, you have make sure their reference count is decremented by making the AV or HV mortal:

  AV *
  array()
      CODE:
          RETVAL = newAV();
          sv_2mortal((SV*)RETVAL);
          /* do something with RETVAL */
      OUTPUT:
          RETVAL

And also remember that you don't have to do this for an SV *.

The MODULE Keyword

The MODULE keyword is used to start the XS code and to specify the package of the functions which are being defined. All text preceding the first MODULE keyword is considered C code and is passed through to the output with POD stripped, but otherwise untouched. Every XS module will have a bootstrap function which is used to hook the XSUBs into Perl. The package name of this bootstrap function will match the value of the last MODULE statement in the XS source files. The value of MODULE should always remain constant within the same XS file, though this is not required.

The following example will start the XS code and will place all functions in a package named RPC.

     MODULE = RPC

The PACKAGE Keyword

When functions within an XS source file must be separated into packages the PACKAGE keyword should be used. This keyword is used with the MODULE keyword and must follow immediately after it when used.

     MODULE = RPC  PACKAGE = RPC
     [ XS code in package RPC ]
     MODULE = RPC  PACKAGE = RPCB
     [ XS code in package RPCB ]
     MODULE = RPC  PACKAGE = RPC
     [ XS code in package RPC ]

The same package name can be used more than once, allowing for non-contiguous code. This is useful if you have a stronger ordering principle than package names.

Although this keyword is optional and in some cases provides redundant information it should always be used. This keyword will ensure that the XSUBs appear in the desired package.

The PREFIX Keyword

The PREFIX keyword designates prefixes which should be removed from the Perl function names. If the C function is rpcb_gettime() and the PREFIX value is rpcb_ then Perl will see this function as gettime().

This keyword should follow the PACKAGE keyword when used. If PACKAGE is not used then PREFIX should follow the MODULE keyword.

     MODULE = RPC  PREFIX = rpc_
     MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_

The OUTPUT: Keyword

The OUTPUT: keyword indicates that certain function parameters should be updated (new values made visible to Perl) when the XSUB terminates or that certain values should be returned to the calling Perl function. For simple functions which have no CODE: or PPCODE: section, such as the sin() function above, the RETVAL variable is automatically designated as an output value. For more complex functions the xsubpp compiler will need help to determine which variables are output variables.

This keyword will normally be used to complement the CODE: keyword. The RETVAL variable is not recognized as an output variable when the CODE: keyword is present. The OUTPUT: keyword is used in this situation to tell the compiler that RETVAL really is an output variable.

The OUTPUT: keyword can also be used to indicate that function parameters are output variables. This may be necessary when a parameter has been modified within the function and the programmer would like the update to be seen by Perl.

     bool_t
     rpcb_gettime(host,timep)
          char *host
          time_t &timep
        OUTPUT:
          timep

The OUTPUT: keyword will also allow an output parameter to be mapped to a matching piece of code rather than to a typemap.

     bool_t
     rpcb_gettime(host,timep)
          char *host
          time_t &timep
        OUTPUT:
          timep sv_setnv(ST(1), (double)timep);

xsubpp emits an automatic SvSETMAGIC() for all parameters in the OUTPUT section of the XSUB, except RETVAL. This is the usually desired behavior, as it takes care of properly invoking 'set' magic on output parameters (needed for hash or array element parameters that must be created if they didn't exist). If for some reason, this behavior is not desired, the OUTPUT section may contain a SETMAGIC: DISABLE line to disable it for the remainder of the parameters in the OUTPUT section. Likewise, SETMAGIC: ENABLE can be used to reenable it for the remainder of the OUTPUT section. See the perlguts manpage for more details about 'set' magic.

The NO_OUTPUT Keyword

The NO_OUTPUT can be placed as the first token of the XSUB. This keyword indicates that while the C subroutine we provide an interface to has a non-void return type, the return value of this C subroutine should not be returned from the generated Perl subroutine.

With this keyword present The RETVAL Variable is created, and in the generated call to the subroutine this variable is assigned to, but the value of this variable is not going to be used in the auto-generated code.

This keyword makes sense only if RETVAL is going to be accessed by the user-supplied code. It is especially useful to make a function interface more Perl-like, especially when the C return value is just an error condition indicator. For example,

  NO_OUTPUT int
  delete_file(char *name)
    POSTCALL:
      if (RETVAL != 0)
          croak("Error %d while deleting file '%s'", RETVAL, name);

Here the generated XS function returns nothing on success, and will die() with a meaningful error message on error.

The CODE: Keyword

This keyword is used in more complicated XSUBs which require special handling for the C function. The RETVAL variable is still declared, but it will not be returned unless it is specified in the OUTPUT: section.

The following XSUB is for a C function which requires special handling of its parameters. The Perl usage is given first.

     $status = rpcb_gettime( "localhost", $timep );

The XSUB follows.

     bool_t
     rpcb_gettime(host,timep)
          char *host
          time_t timep
        CODE:
               RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

The INIT: Keyword

The INIT: keyword allows initialization to be inserted into the XSUB before the compiler generates the call to the C function. Unlike the CODE: keyword above, this keyword does not affect the way the compiler handles RETVAL.

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t &timep
        INIT:
          printf("# Host is %s\n", host );
        OUTPUT:
          timep

Another use for the INIT: section is to check for preconditions before making a call to the C function:

    long long
    lldiv(a,b)
        long long a
        long long b
      INIT:
        if (a == 0 && b == 0)
            XSRETURN_UNDEF;
        if (b == 0)
            croak("lldiv: cannot divide by 0");

The NO_INIT Keyword

The NO_INIT keyword is used to indicate that a function parameter is being used only as an output value. The xsubpp compiler will normally generate code to read the values of all function parameters from the argument stack and assign them to C variables upon entry to the function. NO_INIT will tell the compiler that some parameters will be used for output rather than for input and that they will be handled before the function terminates.

The following example shows a variation of the rpcb_gettime() function. This function uses the timep variable only as an output variable and does not care about its initial contents.

     bool_t
     rpcb_gettime(host,timep)
          char *host
          time_t &timep = NO_INIT
        OUTPUT:
          timep

Initializing Function Parameters

C function parameters are normally initialized with their values from the argument stack (which in turn contains the parameters that were passed to the XSUB from Perl). The typemaps contain the code segments which are used to translate the Perl values to the C parameters. The programmer, however, is allowed to override the typemaps and supply alternate (or additional) initialization code. Initialization code starts with the first =, ; or + on a line in the INPUT: section. The only exception happens if this ; terminates the line, then this ; is quietly ignored.

The following code demonstrates how to supply initialization code for function parameters. The initialization code is eval'd within double quotes by the compiler before it is added to the output so anything which should be interpreted literally [mainly $, @, or \\] must be protected with backslashes. The variables $var, $arg, and $type can be used as in typemaps.

     bool_t
     rpcb_gettime(host,timep)
          char *host = (char *)SvPV($arg,PL_na);
          time_t &timep = 0;
        OUTPUT:
          timep

This should not be used to supply default values for parameters. One would normally use this when a function parameter must be processed by another library function before it can be used. Default parameters are covered in the next section.

If the initialization begins with =, then it is output in the declaration for the input variable, replacing the initialization supplied by the typemap. If the initialization begins with ; or +, then it is performed after all of the input variables have been declared. In the ; case the initialization normally supplied by the typemap is not performed. For the + case, the declaration for the variable will include the initialization from the typemap. A global variable, %v, is available for the truly rare case where information from one initialization is needed in another initialization.

Here's a truly obscure example:

     bool_t
     rpcb_gettime(host,timep)
          time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
          char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
        OUTPUT:
          timep

The construct \$v{timep}=@{[$v{timep}=$arg]} used in the above example has a two-fold purpose: first, when this line is processed by xsubpp, the Perl snippet $v{timep}=$arg is evaluated. Second, the text of the evaluated snippet is output into the generated C file (inside a C comment)! During the processing of char *host line, $arg will evaluate to ST(0), and $v{timep} will evaluate to ST(1).

Default Parameter Values

Default values for XSUB arguments can be specified by placing an assignment statement in the parameter list. The default value may be a number, a string or the special string NO_INIT. Defaults should always be used on the right-most parameters only.

To allow the XSUB for rpcb_gettime() to have a default host value the parameters to the XSUB could be rearranged. The XSUB will then call the real rpcb_gettime() function with the parameters in the correct order. This XSUB can be called from Perl with either of the following statements:

     $status = rpcb_gettime( $timep, $host );

     $status = rpcb_gettime( $timep );

The XSUB will look like the code which follows. A CODE: block is used to call the real rpcb_gettime() function with the parameters in the correct order for that function.

     bool_t
     rpcb_gettime(timep,host="localhost")
          char *host
          time_t timep = NO_INIT
        CODE:
               RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

The PREINIT: Keyword

The PREINIT: keyword allows extra variables to be declared immediately before or after the declarations of the parameters from the INPUT: section are emitted.

If a variable is declared inside a CODE: section it will follow any typemap code that is emitted for the input parameters. This may result in the declaration ending up after C code, which is C syntax error. Similar errors may happen with an explicit ;-type or +-type initialization of parameters is used (see Initializing Function Parameters). Declaring these variables in an INIT: section will not help.

In such cases, to force an additional variable to be declared together with declarations of other variables, place the declaration into a PREINIT: section. The PREINIT: keyword may be used one or more times within an XSUB.

The following examples are equivalent, but if the code is using complex typemaps then the first example is safer.

     bool_t
     rpcb_gettime(timep)
          time_t timep = NO_INIT
        PREINIT:
          char *host = "localhost";
        CODE:
          RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

For this particular case an INIT: keyword would generate the same C code as the PREINIT: keyword. Another correct, but error-prone example:

     bool_t
     rpcb_gettime(timep)
          time_t timep = NO_INIT
        CODE:
          char *host = "localhost";
          RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

Another way to declare host is to use a C block in the CODE: section:

     bool_t
     rpcb_gettime(timep)
          time_t timep = NO_INIT
        CODE:
          {
            char *host = "localhost";
            RETVAL = rpcb_gettime( host, &timep );
          }
        OUTPUT:
          timep
          RETVAL

The ability to put additional declarations before the typemap entries are processed is very handy in the cases when typemap conversions manipulate some global state:

    MyObject
    mutate(o)
        PREINIT:
            MyState st = global_state;
        INPUT:
            MyObject o;
        CLEANUP:
            reset_to(global_state, st);

Here we suppose that conversion to MyObject in the INPUT: section and from MyObject when processing RETVAL will modify a global variable global_state. After these conversions are performed, we restore the old value of global_state (to avoid memory leaks, for example).

There is another way to trade clarity for compactness: INPUT sections allow declaration of C variables which do not appear in the parameter list of a subroutine. Thus the above code for mutate() can be rewritten as

    MyObject
    mutate(o)
          MyState st = global_state;
          MyObject o;
        CLEANUP:
          reset_to(global_state, st);

and the code for rpcb_gettime() can be rewritten as

     bool_t
     rpcb_gettime(timep)
          time_t timep = NO_INIT
          char *host = "localhost";
        C_ARGS:
          host, &timep
        OUTPUT:
          timep
          RETVAL

The SCOPE: Keyword

The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If enabled, the XSUB will invoke ENTER and LEAVE automatically.

To support potentially complex type mappings, if a typemap entry used by an XSUB contains a comment like /*scope*/ then scoping will be automatically enabled for that XSUB.

To enable scoping:

    SCOPE: ENABLE

To disable scoping:

    SCOPE: DISABLE

The INPUT: Keyword

The XSUB's parameters are usually evaluated immediately after entering the XSUB. The INPUT: keyword can be used to force those parameters to be evaluated a little later. The INPUT: keyword can be used multiple times within an XSUB and can be used to list one or more input variables. This keyword is used with the PREINIT: keyword.

The following example shows how the input parameter timep can be evaluated late, after a PREINIT.

    bool_t
    rpcb_gettime(host,timep)
          char *host
        PREINIT:
          time_t tt;
        INPUT:
          time_t timep
        CODE:
               RETVAL = rpcb_gettime( host, &tt );
               timep = tt;
        OUTPUT:
          timep
          RETVAL

The next example shows each input parameter evaluated late.

    bool_t
    rpcb_gettime(host,timep)
        PREINIT:
          time_t tt;
        INPUT:
          char *host
        PREINIT:
          char *h;
        INPUT:
          time_t timep
        CODE:
               h = host;
               RETVAL = rpcb_gettime( h, &tt );
               timep = tt;
        OUTPUT:
          timep
          RETVAL

Since INPUT sections allow declaration of C variables which do not appear in the parameter list of a subroutine, this may be shortened to:

    bool_t
    rpcb_gettime(host,timep)
          time_t tt;
          char *host;
          char *h = host;
          time_t timep;
        CODE:
          RETVAL = rpcb_gettime( h, &tt );
          timep = tt;
        OUTPUT:
          timep
          RETVAL

(We used our knowledge that input conversion for char * is a "simple" one, thus host is initialized on the declaration line, and our assignment h = host is not performed too early. Otherwise one would need to have the assignment h = host in a CODE: or INIT: section.)

The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords

In the list of parameters for an XSUB, one can precede parameter names by the IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT keywords. IN keyword is the default, the other keywords indicate how the Perl interface should differ from the C interface.

Parameters preceded by OUTLIST/IN_OUTLIST/OUT/IN_OUT keywords are considered to be used by the C subroutine via pointers. OUTLIST/OUT keywords indicate that the C subroutine does not inspect the memory pointed by this parameter, but will write through this pointer to provide additional return values.

Parameters preceded by OUTLIST keyword do not appear in the usage signature of the generated Perl function.

Parameters preceded by IN_OUTLIST/IN_OUT/OUT do appear as parameters to the Perl function. With the exception of OUT-parameters, these parameters are converted to the corresponding C type, then pointers to these data are given as arguments to the C function. It is expected that the C function will write through these pointers.

The return list of the generated Perl function consists of the C return value from the function (unless the XSUB is of void return type or The NO_OUTPUT Keyword was used) followed by all the OUTLIST and IN_OUTLIST parameters (in the order of appearance). On the return from the XSUB the IN_OUT/OUT Perl parameter will be modified to have the values written by the C function.

For example, an XSUB

  void
  day_month(OUTLIST day, IN unix_time, OUTLIST month)
    int day
    int unix_time
    int month

should be used from Perl as

  my ($day, $month) = day_month(time);

The C signature of the corresponding function should be

  void day_month(int *day, int unix_time, int *month);

The IN/OUTLIST/IN_OUTLIST/IN_OUT/OUT keywords can be mixed with ANSI-style declarations, as in

  void
  day_month(OUTLIST int day, int unix_time, OUTLIST int month)

(here the optional IN keyword is omitted).

The IN_OUT parameters are identical with parameters introduced with The & Unary Operator and put into the OUTPUT: section (see The OUTPUT: Keyword). The IN_OUTLIST parameters are very similar, the only difference being that the value C function writes through the pointer would not modify the Perl parameter, but is put in the output list.

The OUTLIST/OUT parameter differ from IN_OUTLIST/IN_OUT parameters only by the initial value of the Perl parameter not being read (and not being given to the C function - which gets some garbage instead). For example, the same C function as above can be interfaced with as

  void day_month(OUT int day, int unix_time, OUT int month);

or

  void
  day_month(day, unix_time, month)
      int &day = NO_INIT
      int  unix_time
      int &month = NO_INIT
    OUTPUT:
      day
      month

However, the generated Perl function is called in very C-ish style:

  my ($day, $month);
  day_month($day, time, $month);

The length(NAME) Keyword

If one of the input arguments to the C function is the length of a string argument NAME, one can substitute the name of the length-argument by length(NAME) in the XSUB declaration. This argument must be omitted when the generated Perl function is called. E.g.,

  void
  dump_chars(char *s, short l)
  {
    short n = 0;
    while (n < l) {
        printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
        n++;
    }
  }

  MODULE = x            PACKAGE = x
  void dump_chars(char *s, short length(s))

should be called as dump_chars($string).

This directive is supported with ANSI-type function declarations only.

Variable-length Parameter Lists

XSUBs can have variable-length parameter lists by specifying an ellipsis (...) in the parameter list. This use of the ellipsis is similar to that found in ANSI C. The programmer is able to determine the number of arguments passed to the XSUB by examining the items variable which the xsubpp compiler supplies for all XSUBs. By using this mechanism one can create an XSUB which accepts a list of parameters of unknown length.

The host parameter for the rpcb_gettime() XSUB can be optional so the ellipsis can be used to indicate that the XSUB will take a variable number of parameters. Perl should be able to call this XSUB with either of the following statements.

     $status = rpcb_gettime( $timep, $host );

     $status = rpcb_gettime( $timep );

The XS code, with ellipsis, follows.

     bool_t
     rpcb_gettime(timep, ...)
          time_t timep = NO_INIT
        PREINIT:
          char *host = "localhost";
          STRLEN n_a;
        CODE:
          if( items > 1 )
               host = (char *)SvPV(ST(1), n_a);
          RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

The C_ARGS: Keyword

The C_ARGS: keyword allows creating of XSUBS which have different calling sequence from Perl than from C, without a need to write CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is put as the argument to the called C function without any change.

For example, suppose that a C function is declared as

    symbolic nth_derivative(int n, symbolic function, int flags);

and that the default flags are kept in a global C variable default_flags. Suppose that you want to create an interface which is called as

    $second_deriv = $function->nth_derivative(2);

To do this, declare the XSUB as

    symbolic
    nth_derivative(function, n)
        symbolic        function
        int             n
      C_ARGS:
        n, function, default_flags

The PPCODE: Keyword

The PPCODE: keyword is an alternate form of the CODE: keyword and is used to tell the xsubpp compiler that the programmer is supplying the code to control the argument stack for the XSUBs return values. Occasionally one will want an XSUB to return a list of values rather than a single value. In these cases one must use PPCODE: and then explicitly push the list of values on the stack. The PPCODE: and CODE: keywords should not be used together within the same XSUB.

The actual difference between PPCODE: and CODE: sections is in the initialization of SP macro (which stands for the current Perl stack pointer), and in the handling of data on the stack when returning from an XSUB. In CODE: sections SP preserves the value which was on entry to the XSUB: SP is on the function pointer (which follows the last parameter). In PPCODE: sections SP is moved backward to the beginning of the parameter list, which allows PUSH*() macros to place output values in the place Perl expects them to be when the XSUB returns back to Perl.

The generated trailer for a CODE: section ensures that the number of return values Perl will see is either 0 or 1 (depending on the voidness of the return value of the C function, and heuristics mentioned in The RETVAL Variable). The trailer generated for a PPCODE: section is based on the number of return values and on the number of times SP was updated by [X]PUSH*() macros.

Note that macros ST(i), XST_m*() and XSRETURN*() work equally well in CODE: sections and PPCODE: sections.

The following XSUB will call the C rpcb_gettime() function and will return its two output values, timep and status, to Perl as a single list.

     void
     rpcb_gettime(host)
          char *host
        PREINIT:
          time_t  timep;
          bool_t  status;
        PPCODE:
          status = rpcb_gettime( host, &timep );
          EXTEND(SP, 2);
          PUSHs(sv_2mortal(newSViv(status)));
          PUSHs(sv_2mortal(newSViv(timep)));

Notice that the programmer must supply the C code necessary to have the real rpcb_gettime() function called and to have the return values properly placed on the argument stack.

The void return type for this function tells the xsubpp compiler that the RETVAL variable is not needed or used and that it should not be created. In most scenarios the void return type should be used with the PPCODE: directive.

The EXTEND() macro is used to make room on the argument stack for 2 return values. The PPCODE: directive causes the xsubpp compiler to create a stack pointer available as SP, and it is this pointer which is being used in the EXTEND() macro. The values are then pushed onto the stack with the PUSHs() macro.

Now the rpcb_gettime() function can be used from Perl with the following statement.

     ($status, $timep) = rpcb_gettime("localhost");

When handling output parameters with a PPCODE section, be sure to handle 'set' magic properly. See the perlguts manpage for details about 'set' magic.

Returning Undef And Empty Lists

Occasionally the programmer will want to return simply undef or an empty list if a function fails rather than a separate status value. The rpcb_gettime() function offers just this situation. If the function succeeds we would like to have it return the time and if it fails we would like to have undef returned. In the following Perl code the value of $timep will either be undef or it will be a valid time.

     $timep = rpcb_gettime( "localhost" );

The following XSUB uses the SV * return type as a mnemonic only, and uses a CODE: block to indicate to the compiler that the programmer has supplied all the necessary code. The sv_newmortal() call will initialize the return value to undef, making that the default return value.

     SV *
     rpcb_gettime(host)
          char *  host
        PREINIT:
          time_t  timep;
          bool_t x;
        CODE:
          ST(0) = sv_newmortal();
          if( rpcb_gettime( host, &timep ) )
               sv_setnv( ST(0), (double)timep);

The next example demonstrates how one would place an explicit undef in the return value, should the need arise.

     SV *
     rpcb_gettime(host)
          char *  host
        PREINIT:
          time_t  timep;
          bool_t x;
        CODE:
          ST(0) = sv_newmortal();
          if( rpcb_gettime( host, &timep ) ){
               sv_setnv( ST(0), (double)timep);
          }
          else{
               ST(0) = &PL_sv_undef;
          }

To return an empty list one must use a PPCODE: block and then not push return values on the stack.

     void
     rpcb_gettime(host)
          char *host
        PREINIT:
          time_t  timep;
        PPCODE:
          if( rpcb_gettime( host, &timep ) )
               PUSHs(sv_2mortal(newSViv(timep)));
          else{
              /* Nothing pushed on stack, so an empty
               * list is implicitly returned. */
          }

Some people may be inclined to include an explicit return in the above XSUB, rather than letting control fall through to the end. In those situations XSRETURN_EMPTY should be used, instead. This will ensure that the XSUB stack is properly adjusted. Consult the perlapi manpage for other XSRETURN macros.

Since XSRETURN_* macros can be used with CODE blocks as well, one can rewrite this example as:

     int
     rpcb_gettime(host)
          char *host
        PREINIT:
          time_t  timep;
        CODE:
          RETVAL = rpcb_gettime( host, &timep );
          if (RETVAL == 0)
                XSRETURN_UNDEF;
        OUTPUT:
          RETVAL

In fact, one can put this check into a POSTCALL: section as well. Together with PREINIT: simplifications, this leads to:

     int
     rpcb_gettime(host)
          char *host
          time_t  timep;
        POSTCALL:
          if (RETVAL == 0)
                XSRETURN_UNDEF;

The REQUIRE: Keyword

The REQUIRE: keyword is used to indicate the minimum version of the xsubpp compiler needed to compile the XS module. An XS module which contains the following statement will compile with only xsubpp version 1.922 or greater:

        REQUIRE: 1.922

The CLEANUP: Keyword

This keyword can be used when an XSUB requires special cleanup procedures before it terminates. When the CLEANUP: keyword is used it must follow any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The code specified for the cleanup block will be added as the last statements in the XSUB.

The POSTCALL: Keyword

This keyword can be used when an XSUB requires special procedures executed after the C subroutine call is performed. When the POSTCALL: keyword is used it must precede OUTPUT: and CLEANUP: blocks which are present in the XSUB.

See examples in The NO_OUTPUT Keyword and Returning Undef And Empty Lists.

The POSTCALL: block does not make a lot of sense when the C subroutine call is supplied by user by providing either CODE: or PPCODE: section.

The BOOT: Keyword

The BOOT: keyword is used to add code to the extension's bootstrap function. The bootstrap function is generated by the xsubpp compiler and normally holds the statements necessary to register any XSUBs with Perl. With the BOOT: keyword the programmer can tell the compiler to add extra statements to the bootstrap function.

This keyword may be used any time after the first MODULE keyword and should appear on a line by itself. The first blank line after the keyword will terminate the code block.

     BOOT:
     # The following message will be printed when the
     # bootstrap function executes.
     printf("Hello from the bootstrap!\n");

The VERSIONCHECK: Keyword

The VERSIONCHECK: keyword corresponds to xsubpp's -versioncheck and -noversioncheck options. This keyword overrides the command line options. Version checking is enabled by default. When version checking is enabled the XS module will attempt to verify that its version matches the version of the PM module.

To enable version checking:

    VERSIONCHECK: ENABLE

To disable version checking:

    VERSIONCHECK: DISABLE

The PROTOTYPES: Keyword

The PROTOTYPES: keyword corresponds to xsubpp's -prototypes and -noprototypes options. This keyword overrides the command line options. Prototypes are enabled by default. When prototypes are enabled XSUBs will be given Perl prototypes. This keyword may be used multiple times in an XS module to enable and disable prototypes for different parts of the module.

To enable prototypes:

    PROTOTYPES: ENABLE

To disable prototypes:

    PROTOTYPES: DISABLE

The PROTOTYPE: Keyword

This keyword is similar to the PROTOTYPES: keyword above but can be used to force xsubpp to use a specific prototype for the XSUB. This keyword overrides all other prototype options and keywords but affects only the current XSUB. Consult Prototypes in the perlsub manpage for information about Perl prototypes.

    bool_t
    rpcb_gettime(timep, ...)
          time_t timep = NO_INIT
        PROTOTYPE: $;$
        PREINIT:
          char *host = "localhost";
          STRLEN n_a;
        CODE:
                  if( items > 1 )
                       host = (char *)SvPV(ST(1), n_a);
                  RETVAL = rpcb_gettime( host, &timep );
        OUTPUT:
          timep
          RETVAL

If the prototypes are enabled, you can disable it locally for a given XSUB as in the following example:

    void
    rpcb_gettime_noproto()
        PROTOTYPE: DISABLE
    ...

The ALIAS: Keyword

The ALIAS: keyword allows an XSUB to have two or more unique Perl names and to know which of those names was used when it was invoked. The Perl names may be fully-qualified with package names. Each alias is given an index. The compiler will setup a variable called ix which contain the index of the alias which was used. When the XSUB is called with its declared name ix will be 0.

The following example will create aliases FOO::gettime() and BAR::getit() for this function.

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t &timep
        ALIAS:
            FOO::gettime = 1
            BAR::getit = 2
        INIT:
          printf("# ix = %d\n", ix );
        OUTPUT:
          timep

The OVERLOAD: Keyword

Instead of writing an overloaded interface using pure Perl, you can also use the OVERLOAD keyword to define additional Perl names for your functions (like the ALIAS: keyword above). However, the overloaded functions must be defined with three parameters (except for the nomethod() function which needs four parameters). If any function has the OVERLOAD: keyword, several additional lines will be defined in the c file generated by xsubpp in order to register with the overload magic.

Since blessed objects are actually stored as RV's, it is useful to use the typemap features to preprocess parameters and extract the actual SV stored within the blessed RV. See the sample for T_PTROBJ_SPECIAL below.

To use the OVERLOAD: keyword, create an XS function which takes three input parameters ( or use the c style '...' definition) like this:

    SV *
    cmp (lobj, robj, swap)
    My_Module_obj    lobj
    My_Module_obj    robj
    IV               swap
    OVERLOAD: cmp <=>
    { /* function defined here */}

In this case, the function will overload both of the three way comparison operators. For all overload operations using non-alpha characters, you must type the parameter without quoting, seperating multiple overloads with whitespace. Note that "" (the stringify overload) should be entered as \"\" (i.e. escaped).

The FALLBACK: Keyword

In addition to the OVERLOAD keyword, if you need to control how Perl autogenerates missing overloaded operators, you can set the FALLBACK keyword in the module header section, like this:

    MODULE = RPC  PACKAGE = RPC
    FALLBACK: TRUE
    ...

where FALLBACK can take any of the three values TRUE, FALSE, or UNDEF. If you do not set any FALLBACK value when using OVERLOAD, it defaults to UNDEF. FALLBACK is not used except when one or more functions using OVERLOAD have been defined. Please see Fallback in the overload manpage for more details.

The INTERFACE: Keyword

This keyword declares the current XSUB as a keeper of the given calling signature. If some text follows this keyword, it is considered as a list of functions which have this signature, and should be attached to the current XSUB.

For example, if you have 4 C functions multiply(), divide(), add(), subtract() all having the signature:

    symbolic f(symbolic, symbolic);

you can make them all to use the same XSUB using this:

    symbolic
    interface_s_ss(arg1, arg2)
        symbolic        arg1
        symbolic        arg2
    INTERFACE:
        multiply divide
        add subtract

(This is the complete XSUB code for 4 Perl functions!) Four generated Perl function share names with corresponding C functions.

The advantage of this approach comparing to ALIAS: keyword is that there is no need to code a switch statement, each Perl function (which shares the same XSUB) knows which C function it should call. Additionally, one can attach an extra function remainder() at runtime by using

    CV *mycv = newXSproto("Symbolic::remainder",
                          XS_Symbolic_interface_s_ss, __FILE__, "$$");
    XSINTERFACE_FUNC_SET(mycv, remainder);

say, from another XSUB. (This example supposes that there was no INTERFACE_MACRO: section, otherwise one needs to use something else instead of XSINTERFACE_FUNC_SET, see the next section.)

The INTERFACE_MACRO: Keyword

This keyword allows one to define an INTERFACE using a different way to extract a function pointer from an XSUB. The text which follows this keyword should give the name of macros which would extract/set a function pointer. The extractor macro is given return type, CV*, and XSANY.any_dptr for this CV*. The setter macro is given cv, and the function pointer.

The default value is XSINTERFACE_FUNC and XSINTERFACE_FUNC_SET. An INTERFACE keyword with an empty list of functions can be omitted if INTERFACE_MACRO keyword is used.

Suppose that in the previous example functions pointers for multiply(), divide(), add(), subtract() are kept in a global C array fp[] with offsets being multiply_off, divide_off, add_off, subtract_off. Then one can use

    #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
        ((XSINTERFACE_CVT(ret,))fp[CvXSUBANY(cv).any_i32])
    #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
        CvXSUBANY(cv).any_i32 = CAT2( f, _off )

in C section,

    symbolic
    interface_s_ss(arg1, arg2)
        symbolic        arg1
        symbolic        arg2
      INTERFACE_MACRO:
        XSINTERFACE_FUNC_BYOFFSET
        XSINTERFACE_FUNC_BYOFFSET_set
      INTERFACE:
        multiply divide
        add subtract

in XSUB section.

The INCLUDE: Keyword

This keyword can be used to pull other files into the XS module. The other files may have XS code. INCLUDE: can also be used to run a command to generate the XS code to be pulled into the module.

The file Rpcb1.xsh contains our rpcb_gettime() function:

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t &timep
        OUTPUT:
          timep

The XS module can use INCLUDE: to pull that file into it.

    INCLUDE: Rpcb1.xsh

If the parameters to the INCLUDE: keyword are followed by a pipe (|) then the compiler will interpret the parameters as a command.

    INCLUDE: cat Rpcb1.xsh |

The CASE: Keyword

The CASE: keyword allows an XSUB to have multiple distinct parts with each part acting as a virtual XSUB. CASE: is greedy and if it is used then all other XS keywords must be contained within a CASE:. This means nothing may precede the first CASE: in the XSUB and anything following the last CASE: is included in that case.

A CASE: might switch via a parameter of the XSUB, via the ix ALIAS: variable (see The ALIAS: Keyword), or maybe via the items variable (see Variable-length Parameter Lists). The last CASE: becomes the default case if it is not associated with a conditional. The following example shows CASE switched via ix with a function rpcb_gettime() having an alias x_gettime(). When the function is called as rpcb_gettime() its parameters are the usual (char *host, time_t *timep), but when the function is called as x_gettime() its parameters are reversed, (time_t *timep, char *host).

    long
    rpcb_gettime(a,b)
      CASE: ix == 1
        ALIAS:
          x_gettime = 1
        INPUT:
          # 'a' is timep, 'b' is host
          char *b
          time_t a = NO_INIT
        CODE:
               RETVAL = rpcb_gettime( b, &a );
        OUTPUT:
          a
          RETVAL
      CASE:
          # 'a' is host, 'b' is timep
          char *a
          time_t &b = NO_INIT
        OUTPUT:
          b
          RETVAL

That function can be called with either of the following statements. Note the different argument lists.

        $status = rpcb_gettime( $host, $timep );

        $status = x_gettime( $timep, $host );

The & Unary Operator

The & unary operator in the INPUT: section is used to tell xsubpp that it should convert a Perl value to/from C using the C type to the left of &, but provide a pointer to this value when the C function is called.

This is useful to avoid a CODE: block for a C function which takes a parameter by reference. Typically, the parameter should be not a pointer type (an int or long but not an int* or long*).

The following XSUB will generate incorrect C code. The xsubpp compiler will turn this into code which calls rpcb_gettime() with parameters (char *host, time_t timep), but the real rpcb_gettime() wants the timep parameter to be of type time_t* rather than time_t.

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t timep
        OUTPUT:
          timep

That problem is corrected by using the & operator. The xsubpp compiler will now turn this into code which calls rpcb_gettime() correctly with parameters (char *host, time_t *timep). It does this by carrying the & through, so the function call looks like rpcb_gettime(host, &timep).

    bool_t
    rpcb_gettime(host,timep)
          char *host
          time_t &timep
        OUTPUT:
          timep

Inserting POD, Comments and C Preprocessor Directives

C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions. Comments are allowed anywhere after the MODULE keyword. The compiler will pass the preprocessor directives through untouched and will remove the commented lines. POD documentation is allowed at any point, both in the C and XS language sections. POD must be terminated with a =cut command; xsubpp will exit with an error if it does not. It is very unlikely that human generated C code will be mistaken for POD, as most indenting styles result in whitespace in front of any line starting with =. Machine generated XS files may fall into this trap unless care is taken to ensure that a space breaks the sequence "\n=".

Comments can be added to XSUBs by placing a # as the first non-whitespace of a line. Care should be taken to avoid making the comment look like a C preprocessor directive, lest it be interpreted as such. The simplest way to prevent this is to put whitespace in front of the #.

If you use preprocessor directives to choose one of two versions of a function, use

    #if ... version1
    #else /* ... version2  */
    #endif

and not

    #if ... version1
    #endif
    #if ... version2
    #endif

because otherwise xsubpp will believe that you made a duplicate definition of the function. Also, put a blank line before the #else/#endif so it will not be seen as part of the function body.

Using XS With C++

If an XSUB name contains ::, it is considered to be a C++ method. The generated Perl function will assume that its first argument is an object pointer. The object pointer will be stored in a variable called THIS. The object should have been created by C++ with the new() function and should be blessed by Perl with the sv_setref_pv() macro. The blessing of the object by Perl can be handled by a typemap. An example typemap is shown at the end of this section.

If the return type of the XSUB includes static, the method is considered to be a static method. It will call the C++ function using the class::method() syntax. If the method is not static the function will be called using the THIS->method() syntax.

The next examples will use the following C++ class.

     class color {
          public:
          color();
          ~color();
          int blue();
          void set_blue( int );

          private:
          int c_blue;
               };

The XSUBs for the blue() and set_blue() methods are defined with the class name but the parameter for the object (THIS, or "self") is implicit and is not listed.

     int
     color::blue()
     void
     color::set_blue( val )
          int val

Both Perl functions will expect an object as the first parameter. In the generated C++ code the object is called THIS, and the method call will be performed on this object. So in the C++ code the blue() and set_blue() methods will be called as this:

     RETVAL = THIS->blue();

     THIS->set_blue( val );

You could also write a single get/set method using an optional argument:

     int
     color::blue( val = NO_INIT )
         int val
         PROTOTYPE $;$
         CODE:
             if (items > 1)
                 THIS->set_blue( val );
             RETVAL = THIS->blue();
         OUTPUT:
             RETVAL

If the function's name is DESTROY then the C++ delete function will be called and THIS will be given as its parameter. The generated C++ code for

     void
     color::DESTROY()

will look like this:

     color *THIS = ...; // Initialized as in typemap

     delete THIS;

If the function's name is new then the C++ new function will be called to create a dynamic C++ object. The XSUB will expect the class name, which will be kept in a variable called CLASS, to be given as the first argument.

     color *
     color::new()

The generated C++ code will call new.

     RETVAL = new color();

The following is an example of a typemap that could be used for this C++ example.

    TYPEMAP
    color *             O_OBJECT
    OUTPUT
    # The Perl object is blessed into 'CLASS', which should be a
    # char* having the name of the package for the blessing.
    O_OBJECT
        sv_setref_pv( $arg, CLASS, (void*)$var );

    INPUT
    O_OBJECT
        if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
                $var = ($type)SvIV((SV*)SvRV( $arg ));
        else{
                warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
                XSRETURN_UNDEF;
        }

Interface Strategy

When designing an interface between Perl and a C library a straight translation from C to XS (such as created by h2xs -x) is often sufficient. However, sometimes the interface will look very C-like and occasionally nonintuitive, especially when the C function modifies one of its parameters, or returns failure inband (as in "negative return values mean failure"). In cases where the programmer wishes to create a more Perl-like interface the following strategy may help to identify the more critical parts of the interface.

Identify the C functions with input/output or output parameters. The XSUBs for these functions may be able to return lists to Perl.

Identify the C functions which use some inband info as an indication of failure. They may be candidates to return undef or an empty list in case of failure. If the failure may be detected without a call to the C function, you may want to use an INIT: section to report the failure. For failures detectable after the C function returns one may want to use a POSTCALL: section to process the failure. In more complicated cases use CODE: or PPCODE: sections.

If many functions use the same failure indication based on the return value, you may want to create a special typedef to handle this situation. Put

  typedef int negative_is_failure;

near the beginning of XS file, and create an OUTPUT typemap entry for negative_is_failure which converts negative values to undef, or maybe croak()s. After this the return value of type negative_is_failure will create more Perl-like interface.

Identify which values are used by only the C and XSUB functions themselves, say, when a parameter to a function should be a contents of a global variable. If Perl does not need to access the contents of the value then it may not be necessary to provide a translation for that value from C to Perl.

Identify the pointers in the C function parameter lists and return values. Some pointers may be used to implement input/output or output parameters, they can be handled in XS with the & unary operator, and, possibly, using the NO_INIT keyword. Some others will require handling of types like int *, and one needs to decide what a useful Perl translation will do in such a case. When the semantic is clear, it is advisable to put the translation into a typemap file.

Identify the structures used by the C functions. In many cases it may be helpful to use the T_PTROBJ typemap for these structures so they can be manipulated by Perl as blessed objects. (This is handled automatically by h2xs -x.)

If the same C type is used in several different contexts which require different translations, typedef several new types mapped to this C type, and create separate typemap entries for these new types. Use these types in declarations of return type and parameters to XSUBs.

Perl Objects And C Structures

When dealing with C structures one should select either T_PTROBJ or T_PTRREF for the XS type. Both types are designed to handle pointers to complex objects. The T_PTRREF type will allow the Perl object to be unblessed while the T_PTROBJ type requires that the object be blessed. By using T_PTROBJ one can achieve a form of type-checking because the XSUB will attempt to verify that the Perl object is of the expected type.

The following XS code shows the getnetconfigent() function which is used with ONC+ TIRPC. The getnetconfigent() function will return a pointer to a C structure and has the C prototype shown below. The example will demonstrate how the C pointer will become a Perl reference. Perl will consider this reference to be a pointer to a blessed object and will attempt to call a destructor for the object. A destructor will be provided in the XS source to free the memory used by getnetconfigent(). Destructors in XS can be created by specifying an XSUB function whose name ends with the word DESTROY. XS destructors can be used to free memory which may have been malloc'd by another XSUB.

     struct netconfig *getnetconfigent(const char *netid);

A typedef will be created for struct netconfig. The Perl object will be blessed in a class matching the name of the C type, with the tag Ptr appended, and the name should not have embedded spaces if it will be a Perl package name. The destructor will be placed in a class corresponding to the class of the object and the PREFIX keyword will be used to trim the name to the word DESTROY as Perl will expect.

     typedef struct netconfig Netconfig;

     MODULE = RPC  PACKAGE = RPC
     Netconfig *
     getnetconfigent(netid)
          char *netid
     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
     void
     rpcb_DESTROY(netconf)
          Netconfig *netconf
        CODE:
          printf("Now in NetconfigPtr::DESTROY\n");
          free( netconf );

This example requires the following typemap entry. Consult the typemap section for more information about adding new typemaps for an extension.

     TYPEMAP
     Netconfig *  T_PTROBJ

This example will be used with the following Perl statements.

     use RPC;
     $netconf = getnetconfigent("udp");

When Perl destroys the object referenced by $netconf it will send the object to the supplied XSUB DESTROY function. Perl cannot determine, and does not care, that this object is a C struct and not a Perl object. In this sense, there is no difference between the object created by the getnetconfigent() XSUB and an object created by a normal Perl subroutine.

The Typemap

The typemap is a collection of code fragments which are used by the xsubpp compiler to map C function parameters and values to Perl values. The typemap file may consist of three sections labelled TYPEMAP, INPUT, and OUTPUT. An unlabelled initial section is assumed to be a TYPEMAP section. The INPUT section tells the compiler how to translate Perl values into variables of certain C types. The OUTPUT section tells the compiler how to translate the values from certain C types into values Perl can understand. The TYPEMAP section tells the compiler which of the INPUT and OUTPUT code fragments should be used to map a given C type to a Perl value. The section labels TYPEMAP, INPUT, or OUTPUT must begin in the first column on a line by themselves, and must be in uppercase.

The default typemap in the lib/ExtUtils directory of the Perl source contains many useful types which can be used by Perl extensions. Some extensions define additional typemaps which they keep in their own directory. These additional typemaps may reference INPUT and OUTPUT maps in the main typemap. The xsubpp compiler will allow the extension's own typemap to override any mappings which are in the default typemap.

Most extensions which require a custom typemap will need only the TYPEMAP section of the typemap file. The custom typemap used in the getnetconfigent() example shown earlier demonstrates what may be the typical use of extension typemaps. That typemap is used to equate a C structure with the T_PTROBJ typemap. The typemap used by getnetconfigent() is shown here. Note that the C type is separated from the XS type with a tab and that the C unary operator * is considered to be a part of the C type name.

        TYPEMAP
        Netconfig *<tab>T_PTROBJ

Here's a more complicated example: suppose that you wanted struct netconfig to be blessed into the class Net::Config. One way to do this is to use underscores (_) to separate package names, as follows:

        typedef struct netconfig * Net_Config;

And then provide a typemap entry T_PTROBJ_SPECIAL that maps underscores to double-colons (::), and declare Net_Config to be of that type:

        TYPEMAP
        Net_Config      T_PTROBJ_SPECIAL
        INPUT
        T_PTROBJ_SPECIAL
                if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
                        IV tmp = SvIV((SV*)SvRV($arg));
                        $var = INT2PTR($type, tmp);
                }
                else
                        croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")

        OUTPUT
        T_PTROBJ_SPECIAL
                sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
                (void*)$var);

The INPUT and OUTPUT sections substitute underscores for double-colons on the fly, giving the desired effect. This example demonstrates some of the power and versatility of the typemap facility.

The INT2PTR macro (defined in perl.h) casts an integer to a pointer, of a given type, taking care of the possible different size of integers and pointers. There are also PTR2IV, PTR2UV, PTR2NV macros, to map the other way, which may be useful in OUTPUT sections.

Safely Storing Static Data in XS

Starting with Perl 5.8, a macro framework has been defined to allow static data to be safely stored in XS modules that will be accessed from a multi-threaded Perl.

Although primarily designed for use with multi-threaded Perl, the macros have been designed so that they will work with non-threaded Perl as well.

It is therefore strongly recommended that these macros be used by all XS modules that make use of static data.

The easiest way to get a template set of macros to use is by specifying the -g (--global) option with h2xs (see h2xs).

Below is an example module that makes use of the macros.

    #include "EXTERN.h"
    #include "perl.h"
    #include "XSUB.h"

    /* Global Data */
    #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION

    typedef struct {
        int count;
        char name[3][100];
    } my_cxt_t;

    START_MY_CXT
    MODULE = BlindMice           PACKAGE = BlindMice
    BOOT:
    {
        MY_CXT_INIT;
        MY_CXT.count = 0;
        strcpy(MY_CXT.name[0], "None");
        strcpy(MY_CXT.name[1], "None");
        strcpy(MY_CXT.name[2], "None");
    }

    int
    newMouse(char * name)
        char * name;
        PREINIT:
          dMY_CXT;
        CODE:
          if (MY_CXT.count >= 3) {
              warn("Already have 3 blind mice");
              RETVAL = 0;
          }
          else {
              RETVAL = ++ MY_CXT.count;
              strcpy(MY_CXT.name[MY_CXT.count - 1], name);
          }

    char *
    get_mouse_name(index)
      int index
      CODE:
        dMY_CXT;
        RETVAL = MY_CXT.lives ++;
        if (index > MY_CXT.count)
          croak("There are only 3 blind mice.");
        else
          RETVAL = newSVpv(MY_CXT.name[index - 1]);

REFERENCE

MY_CXT_KEY

This macro is used to define a unique key to refer to the static data for an XS module. The suggested naming scheme, as used by h2xs, is to use a string that consists of the module name, the string "::_guts" and the module version number.

    #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
typedef my_cxt_t

This struct typedef must always be called my_cxt_t -- the other CXT* macros assume the existence of the my_cxt_t typedef name.

Declare a typedef named my_cxt_t that is a structure that contains all the data that needs to be interpreter-local.

    typedef struct {
        int some_value;
    } my_cxt_t;
START_MY_CXT

Always place the START_MY_CXT macro directly after the declaration of my_cxt_t.

MY_CXT_INIT

The MY_CXT_INIT macro initialises storage for the my_cxt_t struct.

It must be called exactly once -- typically in a BOOT: section.

dMY_CXT

Use the dMY_CXT macro (a declaration) in all the functions that access MY_CXT.

MY_CXT

Use the MY_CXT macro to access members of the my_cxt_t struct. For example, if my_cxt_t is

    typedef struct {
        int index;
    } my_cxt_t;

then use this to access the index member

    dMY_CXT;
    MY_CXT.index = 2;

EXAMPLES

File RPC.xs: Interface to some ONC+ RPC bind library functions.

     #include "EXTERN.h"
     #include "perl.h"
     #include "XSUB.h"

     #include <rpc/rpc.h>

     typedef struct netconfig Netconfig;

     MODULE = RPC  PACKAGE = RPC
     SV *
     rpcb_gettime(host="localhost")
          char *host
        PREINIT:
          time_t  timep;
        CODE:
          ST(0) = sv_newmortal();
          if( rpcb_gettime( host, &timep ) )
               sv_setnv( ST(0), (double)timep );

     Netconfig *
     getnetconfigent(netid="udp")
          char *netid
     MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_
     void
     rpcb_DESTROY(netconf)
          Netconfig *netconf
        CODE:
          printf("NetconfigPtr::DESTROY\n");
          free( netconf );

File typemap: Custom typemap for RPC.xs.

     TYPEMAP
     Netconfig *  T_PTROBJ

File RPC.pm: Perl module for the RPC extension.

     package RPC;

     require Exporter;
     require DynaLoader;
     @ISA = qw(Exporter DynaLoader);
     @EXPORT = qw(rpcb_gettime getnetconfigent);

     bootstrap RPC;
     1;

File rpctest.pl: Perl test program for the RPC extension.

     use RPC;

     $netconf = getnetconfigent();
     $a = rpcb_gettime();
     print "time = $a\n";
     print "netconf = $netconf\n";

     $netconf = getnetconfigent("tcp");
     $a = rpcb_gettime("poplar");
     print "time = $a\n";
     print "netconf = $netconf\n";

XS VERSION

This document covers features supported by xsubpp 1.935.

AUTHOR

Originally written by Dean Roehrich <roehrich@cray.com>.

Maintained since 1996 by The Perl Porters <perlbug@perl.org>.


perlXStut - Tutorial for writing XSUBs

  • SPECIAL NOTES
    • make
    • Version caveat
    • Dynamic Loading versus Static Loading
  • TUTORIAL
    • EXAMPLE 1
    • EXAMPLE 2
    • What has gone on?
    • Writing good test scripts
    • EXAMPLE 3
    • What's new here?
    • Input and Output Parameters
    • The XSUBPP Program
    • The TYPEMAP file
    • Warning about Output Arguments
    • EXAMPLE 4
    • What has happened here?
    • Anatomy of .xs file
    • Getting the fat out of XSUBs
    • More about XSUB arguments
    • The Argument Stack
    • Extending your Extension
    • Documenting your Extension
    • Installing your Extension
    • EXAMPLE 5
    • New Things in this Example
    • EXAMPLE 6
    • New Things in this Example
    • EXAMPLE 7 (Coming Soon)
    • EXAMPLE 8 (Coming Soon)
    • EXAMPLE 9 Passing open files to XSes
    • Troubleshooting these Examples
  • See also
  • Author
    • Last Changed

NAME

perlXStut - Tutorial for writing XSUBs

DESCRIPTION

This tutorial will educate the reader on the steps involved in creating a Perl extension. The reader is assumed to have access to the perlguts manpage, the perlapi manpage and the perlxs manpage.

This tutorial starts with very simple examples and becomes more complex, with each new example adding new features. Certain concepts may not be completely explained until later in the tutorial in order to slowly ease the reader into building extensions.

This tutorial was written from a Unix point of view. Where I know them to be otherwise different for other platforms (e.g. Win32), I will list them. If you find something that was missed, please let me know.

SPECIAL NOTES

make

This tutorial assumes that the make program that Perl is configured to use is called make. Instead of running "make" in the examples that follow, you may have to substitute whatever make program Perl has been configured to use. Running perl -V:make should tell you what it is.

Version caveat

When writing a Perl extension for general consumption, one should expect that the extension will be used with versions of Perl different from the version available on your machine. Since you are reading this document, the version of Perl on your machine is probably 5.005 or later, but the users of your extension may have more ancient versions.

To understand what kinds of incompatibilities one may expect, and in the rare case that the version of Perl on your machine is older than this document, see the section on "Troubleshooting these Examples" for more information.

If your extension uses some features of Perl which are not available on older releases of Perl, your users would appreciate an early meaningful warning. You would probably put this information into the README file, but nowadays installation of extensions may be performed automatically, guided by CPAN.pm module or other tools.

In MakeMaker-based installations, Makefile.PL provides the earliest opportunity to perform version checks. One can put something like this in Makefile.PL for this purpose:

    eval { require 5.007 }
        or die <<EOD;
    ############
    ### This module uses frobnication framework which is not available before
    ### version 5.007 of Perl.  Upgrade your Perl before installing Kara::Mba.
    ############
    EOD

Dynamic Loading versus Static Loading

It is commonly thought that if a system does not have the capability to dynamically load a library, you cannot build XSUBs. This is incorrect. You can build them, but you must link the XSUBs subroutines with the rest of Perl, creating a new executable. This situation is similar to Perl 4.

This tutorial can still be used on such a system. The XSUB build mechanism will check the system and build a dynamically-loadable library if possible, or else a static library and then, optionally, a new statically-linked executable with that static library linked in.

Should you wish to build a statically-linked executable on a system which can dynamically load libraries, you may, in all the following examples, where the command "make" with no arguments is executed, run the command "make perl" instead.

If you have generated such a statically-linked executable by choice, then instead of saying "make test", you should say "make test_static". On systems that cannot build dynamically-loadable libraries at all, simply saying "make test" is sufficient.

TUTORIAL

Now let's go on with the show!

EXAMPLE 1

Our first extension will be very simple. When we call the routine in the extension, it will print out a well-known message and return.

Run "h2xs -A -n Mytest". This creates a directory named Mytest, possibly under ext/ if that directory exists in the current working directory. Several files will be created in the Mytest dir, including MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, test.pl, and Changes.

The MANIFEST file contains the names of all the files just created in the Mytest directory.

The file Makefile.PL should look something like this:

        use ExtUtils::MakeMaker;
        # See lib/ExtUtils/MakeMaker.pm for details of how to influence
        # the contents of the Makefile that is written.
        WriteMakefile(
            NAME         => 'Mytest',
            VERSION_FROM => 'Mytest.pm', # finds $VERSION
            LIBS         => [''],   # e.g., '-lm'
            DEFINE       => '',     # e.g., '-DHAVE_SOMETHING'
            INC          => '',     # e.g., '-I/usr/include/other'
        );

The file Mytest.pm should start with something like this:

        package Mytest;

        use strict;
        use warnings;

        require Exporter;
        require DynaLoader;

        our @ISA = qw(Exporter DynaLoader);
        # Items to export into callers namespace by default. Note: do not export
        # names by default without a very good reason. Use EXPORT_OK instead.
        # Do not simply export all your public functions/methods/constants.
        our @EXPORT = qw(

        );
        our $VERSION = '0.01';

        bootstrap Mytest $VERSION;

        # Preloaded methods go here.

        # Autoload methods go after __END__, and are processed by the autosplit program.

        1;
        __END__
        # Below is the stub of documentation for your module. You better edit it!

The rest of the .pm file contains sample code for providing documentation for the extension.

Finally, the Mytest.xs file should look something like this:

        #include "EXTERN.h"
        #include "perl.h"
        #include "XSUB.h"

        MODULE = Mytest         PACKAGE = Mytest

Let's edit the .xs file by adding this to the end of the file:

        void
        hello()
            CODE:
                printf("Hello, world!\n");

It is okay for the lines starting at the "CODE:" line to not be indented. However, for readability purposes, it is suggested that you indent CODE: one level and the lines following one more level.

Now we'll run "perl Makefile.PL". This will create a real Makefile, which make needs. Its output looks something like:

        % perl Makefile.PL
        Checking if your kit is complete...
        Looks good
        Writing Makefile for Mytest
        %

Now, running make will produce output that looks something like this (some long lines have been shortened for clarity and some extraneous lines have been deleted):

        % make
        umask 0 && cp Mytest.pm ./blib/Mytest.pm
        perl xsubpp -typemap typemap Mytest.xs >Mytest.tc && mv Mytest.tc Mytest.c
        Please specify prototyping behavior for Mytest.xs (see perlxs manual)
        cc -c Mytest.c
        Running Mkbootstrap for Mytest ()
        chmod 644 Mytest.bs
        LD_RUN_PATH="" ld -o ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl -b Mytest.o
        chmod 755 ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl
        cp Mytest.bs ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
        chmod 644 ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
        Manifying ./blib/man3/Mytest.3
        %

You can safely ignore the line about "prototyping behavior" - it is explained in the section "The PROTOTYPES: Keyword" in the perlxs manpage.

If you are on a Win32 system, and the build process fails with linker errors for functions in the C library, check if your Perl is configured to use PerlCRT (running perl -V:libc should show you if this is the case). If Perl is configured to use PerlCRT, you have to make sure PerlCRT.lib is copied to the same location that msvcrt.lib lives in, so that the compiler can find it on its own. msvcrt.lib is usually found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib).

Perl has its own special way of easily writing test scripts, but for this example only, we'll create our own test script. Create a file called hello that looks like this:

        #! /opt/perl5/bin/perl

        use ExtUtils::testlib;

        use Mytest;

        Mytest::hello();

Now we make the script executable (chmod +x hello), run the script and we should see the following output:

        % ./hello
        Hello, world!
        %

EXAMPLE 2

Now let's add to our extension a subroutine that will take a single numeric argument as input and return 0 if the number is even or 1 if the number is odd.

Add the following to the end of Mytest.xs:

        int
        is_even(input)
                int     input
            CODE:
                RETVAL = (input % 2 == 0);
            OUTPUT:
                RETVAL

There does not need to be whitespace at the start of the "int input" line, but it is useful for improving readability. Placing a semi-colon at the end of that line is also optional. Any amount and kind of whitespace may be placed between the "int" and "input".

Now re-run make to rebuild our new shared library.

Now perform the same steps as before, generating a Makefile from the Makefile.PL file, and running make.

In order to test that our extension works, we now need to look at the file test.pl. This file is set up to imitate the same kind of testing structure that Perl itself has. Within the test script, you perform a number of tests to confirm the behavior of the extension, printing "ok" when the test is correct, "not ok" when it is not. Change the print statement in the BEGIN block to print "1..4", and add the following code to the end of the file:

        print &Mytest::is_even(0) == 1 ? "ok 2" : "not ok 2", "\n";
        print &Mytest::is_even(1) == 0 ? "ok 3" : "not ok 3", "\n";
        print &Mytest::is_even(2) == 1 ? "ok 4" : "not ok 4", "\n";

We will be calling the test script through the command "make test". You should see output that looks something like this:

        % make test
        PERL_DL_NONLAZY=1 /opt/perl5.004/bin/perl (lots of -I arguments) test.pl
        1..4
        ok 1
        ok 2
        ok 3
        ok 4
        %

What has gone on?

The program h2xs is the starting point for creating extensions. In later examples we'll see how we can use h2xs to read header files and generate templates to connect to C routines.

h2xs creates a number of files in the extension directory. The file Makefile.PL is a perl script which will generate a true Makefile to build the extension. We'll take a closer look at it later.

The .pm and .xs files contain the meat of the extension. The .xs file holds the C routines that make up the extension. The .pm file contains routines that tell Perl how to load your extension.

Generating the Makefile and running make created a directory called blib (which stands for "build library") in the current working directory. This directory will contain the shared library that we will build. Once we have tested it, we can install it into its final location.

Invoking the test script via "make test" did something very important. It invoked perl with all those -I arguments so that it could find the various files that are part of the extension. It is very important that while you are still testing extensions that you use "make test". If you try to run the test script all by itself, you will get a fatal error. Another reason it is important to use "make test" to run your test script is that if you are testing an upgrade to an already-existing version, using "make test" insures that you will test your new extension, not the already-existing version.

When Perl sees a use extension;, it searches for a file with the same name as the use'd extension that has a .pm suffix. If that file cannot be found, Perl dies with a fatal error. The default search path is contained in the @INC array.

In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic Loader extensions. It then sets the @ISA and @EXPORT arrays and the $VERSION scalar; finally it tells perl to bootstrap the module. Perl will call its dynamic loader routine (if there is one) and load the shared library.

The two arrays @ISA and @EXPORT are very important. The @ISA array contains a list of other packages in which to search for methods (or subroutines) that do not exist in the current package. This is usually only important for object-oriented extensions (which we will talk about much later), and so usually doesn't need to be modified.

The @EXPORT array tells Perl which of the extension's variables and subroutines should be placed into the calling package's namespace. Because you don't know if the user has already used your variable and subroutine names, it's vitally important to carefully select what to export. Do not export method or variable names by default without a good reason.

As a general rule, if the module is trying to be object-oriented then don't export anything. If it's just a collection of functions and variables, then you can export them via another array, called @EXPORT_OK. This array does not automatically place its subroutine and variable names into the namespace unless the user specifically requests that this be done.

See the perlmod manpage for more information.

The $VERSION variable is used to ensure that the .pm file and the shared library are "in sync" with each other. Any time you make changes to the .pm or .xs files, you should increment the value of this variable.

Writing good test scripts

The importance of writing good test scripts cannot be overemphasized. You should closely follow the "ok/not ok" style that Perl itself uses, so that it is very easy and unambiguous to determine the outcome of each test case. When you find and fix a bug, make sure you add a test case for it.

By running "make test", you ensure that your test.pl script runs and uses the correct version of your extension. If you have many test cases, you might want to copy Perl's test style. Create a directory named "t" in the extension's directory and append the suffix ".t" to the names of your test files. When you run "make test", all of these test files will be executed.

EXAMPLE 3

Our third extension will take one argument as its input, round off that value, and set the argument to the rounded value.

Add the following to the end of Mytest.xs:

        void
        round(arg)
                double  arg
            CODE:
                if (arg > 0.0) {
                        arg = floor(arg + 0.5);
                } else if (arg < 0.0) {
                        arg = ceil(arg - 0.5);
                } else {
                        arg = 0.0;
                }
            OUTPUT:
                arg

Edit the Makefile.PL file so that the corresponding line looks like this:

        'LIBS'      => ['-lm'],   # e.g., '-lm'

Generate the Makefile and run make. Change the BEGIN block to print "1..9" and add the following to test.pl:

        $i = -1.5; &Mytest::round($i); print $i == -2.0 ? "ok 5" : "not ok 5", "\n";
        $i = -1.1; &Mytest::round($i); print $i == -1.0 ? "ok 6" : "not ok 6", "\n";
        $i = 0.0; &Mytest::round($i); print $i == 0.0 ? "ok 7" : "not ok 7", "\n";
        $i = 0.5; &Mytest::round($i); print $i == 1.0 ? "ok 8" : "not ok 8", "\n";
        $i = 1.2; &Mytest::round($i); print $i == 1.0 ? "ok 9" : "not ok 9", "\n";

Running "make test" should now print out that all nine tests are okay.

Notice that in these new test cases, the argument passed to round was a scalar variable. You might be wondering if you can round a constant or literal. To see what happens, temporarily add the following line to test.pl:

        &Mytest::round(3);

Run "make test" and notice that Perl dies with a fatal error. Perl won't let you change the value of constants!

What's new here?

  • We've made some changes to Makefile.PL. In this case, we've specified an extra library to be linked into the extension's shared library, the math library libm in this case. We'll talk later about how to write XSUBs that can call every routine in a library.

  • The value of the function is not being passed back as the function's return value, but by changing the value of the variable that was passed into the function. You might have guessed that when you saw that the return value of round is of type "void".

Input and Output Parameters

You specify the parameters that will be passed into the XSUB on the line(s) after you declare the function's return value and name. Each input parameter line starts with optional whitespace, and may have an optional terminating semicolon.

The list of output parameters occurs at the very end of the function, just before after the OUTPUT: directive. The use of RETVAL tells Perl that you wish to send this value back as the return value of the XSUB function. In Example 3, we wanted the "return value" placed in the original variable which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section.

The XSUBPP Program

The xsubpp program takes the XS code in the .xs file and translates it into C code, placing it in a file whose suffix is .c. The C code created makes heavy use of the C functions within Perl.

The TYPEMAP file

The xsubpp program uses rules to convert from Perl's data types (scalar, array, etc.) to C's data types (int, char, etc.). These rules are stored in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into three parts.

The first section maps various C data types to a name, which corresponds somewhat with the various Perl types. The second section contains C code which xsubpp uses to handle input parameters. The third section contains C code which xsubpp uses to handle output parameters.

Let's take a look at a portion of the .c file created for our extension. The file name is Mytest.c:

        XS(XS_Mytest_round)
        {
            dXSARGS;
            if (items != 1)
                croak("Usage: Mytest::round(arg)");
            {
                double  arg = (double)SvNV(ST(0));      /* XXXXX */
                if (arg > 0.0) {
                        arg = floor(arg + 0.5);
                } else if (arg < 0.0) {
                        arg = ceil(arg - 0.5);
                } else {
                        arg = 0.0;
                }
                sv_setnv(ST(0), (double)arg);   /* XXXXX */
            }
            XSRETURN(1);
        }

Notice the two lines commented with "XXXXX". If you check the first section of the typemap file, you'll see that doubles are of type T_DOUBLE. In the INPUT section, an argument that is T_DOUBLE is assigned to the variable arg by calling the routine SvNV on something, then casting it to double, then assigned to the variable arg. Similarly, in the OUTPUT section, once arg has its final value, it is passed to the sv_setnv function to be passed back to the calling subroutine. These two functions are explained in the perlguts manpage; we'll talk more later about what that "ST(0)" means in the section on the argument stack.

Warning about Output Arguments

In general, it's not a good idea to write extensions that modify their input parameters, as in Example 3. Instead, you should probably return multiple values in an array and let the caller handle them (we'll do this in a later example). However, in order to better accommodate calling pre-existing C routines, which often do modify their input parameters, this behavior is tolerated.

EXAMPLE 4

In this example, we'll now begin to write XSUBs that will interact with pre-defined C libraries. To begin with, we will build a small library of our own, then let h2xs write our .pm and .xs files for us.

Create a new directory called Mytest2 at the same level as the directory Mytest. In the Mytest2 directory, create another directory called mylib, and cd into that directory.

Here we'll create some files that will generate a test library. These will include a C source file and a header file. We'll also create a Makefile.PL in this directory. Then we'll make sure that running make at the Mytest2 level will automatically run this Makefile.PL file and the resulting Makefile.

In the mylib directory, create a file mylib.h that looks like this:

        #define TESTVAL 4

        extern double   foo(int, long, const char*);

Also create a file mylib.c that looks like this:

        #include <stdlib.h>
        #include "./mylib.h"

        double
        foo(int a, long b, const char *c)
        {
                return (a + b + atof(c) + TESTVAL);
        }

And finally create a file Makefile.PL that looks like this:

        use ExtUtils::MakeMaker;
        $Verbose = 1;
        WriteMakefile(
            NAME   => 'Mytest2::mylib',
            SKIP   => [qw(all static static_lib dynamic dynamic_lib)],
            clean  => {'FILES' => 'libmylib$(LIB_EXT)'},
        );

        sub MY::top_targets {
                '
        all :: static
        pure_all :: static
        static ::       libmylib$(LIB_EXT)
        libmylib$(LIB_EXT): $(O_FILES)
                $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
                $(RANLIB) libmylib$(LIB_EXT)
        ';
        }

Make sure you use a tab and not spaces on the lines beginning with "$(AR)" and "$(RANLIB)". Make will not function properly if you use spaces. It has also been reported that the "cr" argument to $(AR) is unnecessary on Win32 systems.

We will now create the main top-level Mytest2 files. Change to the directory above Mytest2 and run the following command:

        % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h

This will print out a warning about overwriting Mytest2, but that's okay. Our files are stored in Mytest2/mylib, and will be untouched.

The normal Makefile.PL that h2xs generates doesn't know about the mylib directory. We need to tell it that there is a subdirectory and that we will be generating a library in it. Let's add the argument MYEXTLIB to the WriteMakefile call so that it looks like this:

        WriteMakefile(
            'NAME'      => 'Mytest2',
            'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
            'LIBS'      => [''],   # e.g., '-lm'
            'DEFINE'    => '',     # e.g., '-DHAVE_SOMETHING'
            'INC'       => '',     # e.g., '-I/usr/include/other'
            'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
        );

and then at the end add a subroutine (which will override the pre-existing subroutine). Remember to use a tab character to indent the line beginning with "cd"!

        sub MY::postamble {
        '
        $(MYEXTLIB): mylib/Makefile
                cd mylib && $(MAKE) $(PASSTHRU)
        ';
        }

Let's also fix the MANIFEST file so that it accurately reflects the contents of our extension. The single line that says "mylib" should be replaced by the following three lines:

        mylib/Makefile.PL
        mylib/mylib.c
        mylib/mylib.h

To keep our namespace nice and unpolluted, edit the .pm file and change the variable @EXPORT to @EXPORT_OK. Finally, in the .xs file, edit the #include line to read:

        #include "mylib/mylib.h"

And also add the following function definition to the end of the .xs file:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            OUTPUT:
                RETVAL

Now we also need to create a typemap file because the default Perl doesn't currently support the const char * type. Create a file called typemap in the Mytest2 directory and place the following in it:

        const char *    T_PV

Now run perl on the top-level Makefile.PL. Notice that it also created a Makefile in the mylib directory. Run make and watch that it does cd into the mylib directory and run make in there as well.

Now edit the test.pl script and change the BEGIN block to print "1..4", and add the following lines to the end of the script:

        print &Mytest2::foo(1, 2, "Hello, world!") == 7 ? "ok 2\n" : "not ok 2\n";
        print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n";
        print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n";

(When dealing with floating-point comparisons, it is best to not check for equality, but rather that the difference between the expected and actual result is below a certain amount (called epsilon) which is 0.01 in this case)

Run "make test" and all should be well.

What has happened here?

Unlike previous examples, we've now run h2xs on a real include file. This has caused some extra goodies to appear in both the .pm and .xs files.

  • In the .xs file, there's now a #include directive with the absolute path to the mylib.h header file. We changed this to a relative path so that we could move the extension directory if we wanted to.

  • There's now some new C code that's been added to the .xs file. The purpose of the constant routine is to make the values that are #define'd in the header file accessible by the Perl script (by calling either TESTVAL or &Mytest2::TESTVAL). There's also some XS code to allow calls to the constant routine.

  • The .pm file originally exported the name TESTVAL in the @EXPORT array. This could lead to name clashes. A good rule of thumb is that if the #define is only going to be used by the C routines themselves, and not by the user, they should be removed from the @EXPORT array. Alternately, if you don't mind using the "fully qualified name" of a variable, you could move most or all of the items from the @EXPORT array into the @EXPORT_OK array.

  • If our include file had contained #include directives, these would not have been processed by h2xs. There is no good solution to this right now.

  • We've also told Perl about the library that we built in the mylib subdirectory. That required only the addition of the MYEXTLIB variable to the WriteMakefile call and the replacement of the postamble subroutine to cd into the subdirectory and run make. The Makefile.PL for the library is a bit more complicated, but not excessively so. Again we replaced the postamble subroutine to insert our own code. This code simply specified that the library to be created here was a static archive library (as opposed to a dynamically loadable library) and provided the commands to build it.

Anatomy of .xs file

The .xs file of EXAMPLE 4 contained some new elements. To understand the meaning of these elements, pay attention to the line which reads

        MODULE = Mytest2                PACKAGE = Mytest2

Anything before this line is plain C code which describes which headers to include, and defines some convenience functions. No translations are performed on this part, apart from having embedded POD documentation skipped over (see the perlpod manpage) it goes into the generated output C file as is.

Anything after this line is the description of XSUB functions. These descriptions are translated by xsubpp into C code which implements these functions using Perl calling conventions, and which makes these functions visible from Perl interpreter.

Pay a special attention to the function constant. This name appears twice in the generated .xs file: once in the first part, as a static C function, then another time in the second part, when an XSUB interface to this static C function is defined.

This is quite typical for .xs files: usually the .xs file provides an interface to an existing C function. Then this C function is defined somewhere (either in an external library, or in the first part of .xs file), and a Perl interface to this function (i.e. "Perl glue") is described in the second part of .xs file. The situation in EXAMPLE 1, EXAMPLE 2, and EXAMPLE 3, when all the work is done inside the "Perl glue", is somewhat of an exception rather than the rule.

Getting the fat out of XSUBs

In EXAMPLE 4 the second part of .xs file contained the following description of an XSUB:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            OUTPUT:
                RETVAL

Note that in contrast with EXAMPLE 1, EXAMPLE 2 and EXAMPLE 3, this description does not contain the actual code for what is done is done during a call to Perl function foo(). To understand what is going on here, one can add a CODE section to this XSUB:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            CODE:
                RETVAL = foo(a,b,c);
            OUTPUT:
                RETVAL

However, these two XSUBs provide almost identical generated C code: xsubpp compiler is smart enough to figure out the CODE: section from the first two lines of the description of XSUB. What about OUTPUT: section? In fact, that is absolutely the same! The OUTPUT: section can be removed as well, as far as CODE: section or PPCODE: section is not specified: xsubpp can see that it needs to generate a function call section, and will autogenerate the OUTPUT section too. Thus one can shortcut the XSUB to become:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c

Can we do the same with an XSUB

        int
        is_even(input)
                int     input
            CODE:
                RETVAL = (input % 2 == 0);
            OUTPUT:
                RETVAL

of EXAMPLE 2? To do this, one needs to define a C function int is_even(int input). As we saw in Anatomy of .xs file, a proper place for this definition is in the first part of .xs file. In fact a C function

        int
        is_even(int arg)
        {
                return (arg % 2 == 0);
        }

is probably overkill for this. Something as simple as a #define will do too:

        #define is_even(arg)    ((arg) % 2 == 0)

After having this in the first part of .xs file, the "Perl glue" part becomes as simple as

        int
        is_even(input)
                int     input

This technique of separation of the glue part from the workhorse part has obvious tradeoffs: if you want to change a Perl interface, you need to change two places in your code. However, it removes a lot of clutter, and makes the workhorse part independent from idiosyncrasies of Perl calling convention. (In fact, there is nothing Perl-specific in the above description, a different version of xsubpp might have translated this to TCL glue or Python glue as well.)

More about XSUB arguments

With the completion of Example 4, we now have an easy way to simulate some real-life libraries whose interfaces may not be the cleanest in the world. We shall now continue with a discussion of the arguments passed to the xsubpp compiler.

When you specify arguments to routines in the .xs file, you are really passing three pieces of information for each argument listed. The first piece is the order of that argument relative to the others (first, second, etc). The second is the type of argument, and consists of the type declaration of the argument (e.g., int, char*, etc). The third piece is the calling convention for the argument in the call to the library function.

While Perl passes arguments to functions by reference, C passes arguments by value; to implement a C function which modifies data of one of the "arguments", the actual argument of this C function would be a pointer to the data. Thus two C functions with declarations

        int string_length(char *s);
        int upper_case_char(char *cp);

may have completely different semantics: the first one may inspect an array of chars pointed by s, and the second one may immediately dereference cp and manipulate *cp only (using the return value as, say, a success indicator). From Perl one would use these functions in a completely different manner.

One conveys this info to xsubpp by replacing * before the argument by &. & means that the argument should be passed to a library function by its address. The above two function may be XSUB-ified as

        int
        string_length(s)
                char *  s
        int
        upper_case_char(cp)
                char    &cp

For example, consider:

        int
        foo(a,b)
                char    &a
                char *  b

The first Perl argument to this function would be treated as a char and assigned to the variable a, and its address would be passed into the function foo. The second Perl argument would be treated as a string pointer and assigned to the variable b. The value of b would be passed into the function foo. The actual call to the function foo that xsubpp generates would look like this:

        foo(&a, b);

xsubpp will parse the following function argument lists identically:

        char    &a
        char&a
        char    & a

However, to help ease understanding, it is suggested that you place a "&" next to the variable name and away from the variable type), and place a "*" near the variable type, but away from the variable name (as in the call to foo above). By doing so, it is easy to understand exactly what will be passed to the C function -- it will be whatever is in the "last column".

You should take great pains to try to pass the function the type of variable it wants, when possible. It will save you a lot of trouble in the long run.

The Argument Stack

If we look at any of the C code generated by any of the examples except example 1, you will notice a number of references to ST(n), where n is usually 0. "ST" is actually a macro that points to the n'th argument on the argument stack. ST(0) is thus the first argument on the stack and therefore the first argument passed to the XSUB, ST(1) is the second argument, and so on.

When you list the arguments to the XSUB in the .xs file, that tells xsubpp which argument corresponds to which of the argument stack (i.e., the first one listed is the first argument, and so on). You invite disaster if you do not list them in the same order as the function expects them.

The actual values on the argument stack are pointers to the values passed in. When an argument is listed as being an OUTPUT value, its corresponding value on the stack (i.e., ST(0) if it was the first argument) is changed. You can verify this by looking at the C code generated for Example 3. The code for the round() XSUB routine contains lines that look like this:

        double  arg = (double)SvNV(ST(0));
        /* Round the contents of the variable arg */
        sv_setnv(ST(0), (double)arg);

The arg variable is initially set by taking the value from ST(0), then is stored back into ST(0) at the end of the routine.

XSUBs are also allowed to return lists, not just scalars. This must be done by manipulating stack values ST(0), ST(1), etc, in a subtly different way. See the perlxs manpage for details.

XSUBs are also allowed to avoid automatic conversion of Perl function arguments to C function arguments. See the perlxs manpage for details. Some people prefer manual conversion by inspecting ST(i) even in the cases when automatic conversion will do, arguing that this makes the logic of an XSUB call clearer. Compare with Getting the fat out of XSUBs for a similar tradeoff of a complete separation of "Perl glue" and "workhorse" parts of an XSUB.

While experts may argue about these idioms, a novice to Perl guts may prefer a way which is as little Perl-guts-specific as possible, meaning automatic conversion and automatic call generation, as in Getting the fat out of XSUBs. This approach has the additional benefit of protecting the XSUB writer from future changes to the Perl API.

Extending your Extension

Sometimes you might want to provide some extra methods or subroutines to assist in making the interface between Perl and your extension simpler or easier to understand. These routines should live in the .pm file. Whether they are automatically loaded when the extension itself is loaded or only loaded when called depends on where in the .pm file the subroutine definition is placed. You can also consult the AutoLoader manpage for an alternate way to store and load your extra subroutines.

Documenting your Extension

There is absolutely no excuse for not documenting your extension. Documentation belongs in the .pm file. This file will be fed to pod2man, and the embedded documentation will be converted to the manpage format, then placed in the blib directory. It will be copied to Perl's manpage directory when the extension is installed.

You may intersperse documentation and Perl code within the .pm file. In fact, if you want to use method autoloading, you must do this, as the comment inside the .pm file explains.

See the perlpod manpage for more information about the pod format.

Installing your Extension

Once your extension is complete and passes all its tests, installing it is quite simple: you simply run "make install". You will either need to have write permission into the directories where Perl is installed, or ask your system administrator to run the make for you.

Alternately, you can specify the exact directory to place the extension's files by placing a "PREFIX=/destination/directory" after the make install. (or in between the make and install if you have a brain-dead version of make). This can be very useful if you are building an extension that will eventually be distributed to multiple systems. You can then just archive the files in the destination directory and distribute them to your destination systems.

EXAMPLE 5

In this example, we'll do some more work with the argument stack. The previous examples have all returned only a single value. We'll now create an extension that returns an array.

This extension is very Unix-oriented (struct statfs and the statfs system call). If you are not running on a Unix system, you can substitute for statfs any other function that returns multiple values, you can hard-code values to be returned to the caller (although this will be a bit harder to test the error case), or you can simply not do this example. If you change the XSUB, be sure to fix the test cases to match the changes.

Return to the Mytest directory and add the following code to the end of Mytest.xs:

        void
        statfs(path)
                char *  path
            INIT:
                int i;
                struct statfs buf;

            PPCODE:
                i = statfs(path, &buf);
                if (i == 0) {
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[0])));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[1])));
                } else {
                        XPUSHs(sv_2mortal(newSVnv(errno)));
                }

You'll also need to add the following code to the top of the .xs file, just after the include of "XSUB.h":

        #include <sys/vfs.h>

Also add the following code segment to test.pl while incrementing the "1..9" string in the BEGIN block to "1..11":

        @a = &Mytest::statfs("/blech");
        print ((scalar(@a) == 1 && $a[0] == 2) ? "ok 10\n" : "not ok 10\n");
        @a = &Mytest::statfs("/");
        print scalar(@a) == 9 ? "ok 11\n" : "not ok 11\n";

New Things in this Example

This example added quite a few new concepts. We'll take them one at a time.

  • The INIT: directive contains code that will be placed immediately after the argument stack is decoded. C does not allow variable declarations at arbitrary locations inside a function, so this is usually the best way to declare local variables needed by the XSUB. (Alternatively, one could put the whole PPCODE: section into braces, and put these declarations on top.)

  • This routine also returns a different number of arguments depending on the success or failure of the call to statfs. If there is an error, the error number is returned as a single-element array. If the call is successful, then a 9-element array is returned. Since only one argument is passed into this function, we need room on the stack to hold the 9 values which may be returned.

    We do this by using the PPCODE: directive, rather than the CODE: directive. This tells xsubpp that we will be managing the return values that will be put on the argument stack by ourselves.

  • When we want to place values to be returned to the caller onto the stack, we use the series of macros that begin with "XPUSH". There are five different versions, for placing integers, unsigned integers, doubles, strings, and Perl scalars on the stack. In our example, we placed a Perl scalar onto the stack. (In fact this is the only macro which can be used to return multiple values.)

    The XPUSH* macros will automatically extend the return stack to prevent it from being overrun. You push values onto the stack in the order you want them seen by the calling program.

  • The values pushed onto the return stack of the XSUB are actually mortal SV's. They are made mortal so that once the values are copied by the calling program, the SV's that held the returned values can be deallocated. If they were not mortal, then they would continue to exist after the XSUB routine returned, but would not be accessible. This is a memory leak.

  • If we were interested in performance, not in code compactness, in the success branch we would not use XPUSHs macros, but PUSHs macros, and would pre-extend the stack before pushing the return values:

            EXTEND(SP, 9);

    The tradeoff is that one needs to calculate the number of return values in advance (though overextending the stack will not typically hurt anything but memory consumption).

    Similarly, in the failure branch we could use PUSHs without extending the stack: the Perl function reference comes to an XSUB on the stack, thus the stack is always large enough to take one return value.

EXAMPLE 6

In this example, we will accept a reference to an array as an input parameter, and return a reference to an array of hashes. This will demonstrate manipulation of complex Perl data types from an XSUB.

This extension is somewhat contrived. It is based on the code in the previous example. It calls the statfs function multiple times, accepting a reference to an array of filenames as input, and returning a reference to an array of hashes containing the data for each of the filesystems.

Return to the Mytest directory and add the following code to the end of Mytest.xs:

        SV *
        multi_statfs(paths)
                SV * paths
            INIT:
                AV * results;
                I32 numpaths = 0;
                int i, n;
                struct statfs buf;

                if ((!SvROK(paths))
                    || (SvTYPE(SvRV(paths)) != SVt_PVAV)
                    || ((numpaths = av_len((AV *)SvRV(paths))) < 0))
                {
                    XSRETURN_UNDEF;
                }
                results = (AV *)sv_2mortal((SV *)newAV());
                            CODE:
                for (n = 0; n <= numpaths; n++) {
                    HV * rh;
                    STRLEN l;
                    char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);

                    i = statfs(fn, &buf);
                    if (i != 0) {
                        av_push(results, newSVnv(errno));
                        continue;
                    }

                    rh = (HV *)sv_2mortal((SV *)newHV());

                    hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
                    hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
                    hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
                    hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
                    hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
                    hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
                    hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);

                    av_push(results, newRV((SV *)rh));
                                    }
                                    RETVAL = newRV((SV *)results);
                                OUTPUT:
                                    RETVAL

And add the following code to test.pl, while incrementing the "1..11" string in the BEGIN block to "1..13":

        $results = Mytest::multi_statfs([ '/', '/blech' ]);
        print ((ref $results->[0]) ? "ok 12\n" : "not ok 12\n");
        print ((! ref $results->[1]) ? "ok 13\n" : "not ok 13\n");

New Things in this Example

There are a number of new concepts introduced here, described below:

  • This function does not use a typemap. Instead, we declare it as accepting one SV* (scalar) parameter, and returning an SV* value, and we take care of populating these scalars within the code. Because we are only returning one value, we don't need a PPCODE: directive - instead, we use CODE: and OUTPUT: directives.

  • When dealing with references, it is important to handle them with caution. The INIT: block first checks that SvROK returns true, which indicates that paths is a valid reference. It then verifies that the object referenced by paths is an array, using SvRV to dereference paths, and SvTYPE to discover its type. As an added test, it checks that the array referenced by paths is non-empty, using the av_len function (which returns -1 if the array is empty). The XSRETURN_UNDEF macro is used to abort the XSUB and return the undefined value whenever all three of these conditions are not met.

  • We manipulate several arrays in this XSUB. Note that an array is represented internally by an AV* pointer. The functions and macros for manipulating arrays are similar to the functions in Perl: av_len returns the highest index in an AV*, much like $#array; av_fetch fetches a single scalar value from an array, given its index; av_push pushes a scalar value onto the end of the array, automatically extending the array as necessary.

    Specifically, we read pathnames one at a time from the input array, and store the results in an output array (results) in the same order. If statfs fails, the element pushed onto the return array is the value of errno after the failure. If statfs succeeds, though, the value pushed onto the return array is a reference to a hash containing some of the information in the statfs structure.

    As with the return stack, it would be possible (and a small performance win) to pre-extend the return array before pushing data into it, since we know how many elements we will return:

            av_extend(results, numpaths);

  • We are performing only one hash operation in this function, which is storing a new scalar under a key using hv_store. A hash is represented by an HV* pointer. Like arrays, the functions for manipulating hashes from an XSUB mirror the functionality available from Perl. See the perlguts manpage and the perlapi manpage for details.

  • To create a reference, we use the newRV function. Note that you can cast an AV* or an HV* to type SV* in this case (and many others). This allows you to take references to arrays, hashes and scalars with the same function. Conversely, the SvRV function always returns an SV*, which may need to be cast to the appropriate type if it is something other than a scalar (check with SvTYPE).

  • At this point, xsubpp is doing very little work - the differences between Mytest.xs and Mytest.c are minimal.

EXAMPLE 7 (Coming Soon)

XPUSH args AND set RETVAL AND assign return value to array

EXAMPLE 8 (Coming Soon)

Setting $!

EXAMPLE 9 Passing open files to XSes

You would think passing files to an XS is difficult, with all the typeglobs and stuff. Well, it isn't.

Suppose that for some strange reason we need a wrapper around the standard C library function fputs(). This is all we need:

        #define PERLIO_NOT_STDIO 0
        #include "EXTERN.h"
        #include "perl.h"
        #include "XSUB.h"

        #include <stdio.h>

        int
        fputs(s, stream)
                char *          s
                FILE *          stream

The real work is done in the standard typemap.

But you loose all the fine stuff done by the perlio layers. This calls the stdio function fputs(), which knows nothing about them.

The standard typemap offers three variants of PerlIO *: InputStream (T_IN), InOutStream (T_INOUT) and OutputStream (T_OUT). A bare PerlIO * is considered a T_INOUT. If it matters in your code (see below for why it might) #define or typedef one of the specific names and use that as the argument or result type in your XS file.

The standard typemap does not contain PerlIO * before perl 5.7, but it has the three stream variants. Using a PerlIO * directly is not backwards compatible unless you provide your own typemap.

For streams coming from perl the main difference is that OutputStream will get the output PerlIO * - which may make a difference on a socket. Like in our example...

For streams being handed to perl a new file handle is created (i.e. a reference to a new glob) and associated with the PerlIO * provided. If the read/write state of the PerlIO * is not correct then you may get errors or warnings from when the file handle is used. So if you opened the PerlIO * as "w" it should really be an OutputStream if open as "r" it should be an InputStream.

Now, suppose you want to use perlio layers in your XS. We'll use the perlio PerlIO_puts() function as an example.

In the C part of the XS file (above the first MODULE line) you have

        #define OutputStream    PerlIO *
            or
        typedef PerlIO *        OutputStream;

And this is the XS code:

        int
        perlioputs(s, stream)
                char *          s
                OutputStream    stream
        CODE:
                RETVAL = PerlIO_puts(stream, s);
        OUTPUT:
                RETVAL

We have to use a CODE section because PerlIO_puts() has the arguments reversed compared to fputs(), and we want to keep the arguments the same.

Wanting to explore this thoroughly, we want to use the stdio fputs() on a PerlIO *. This means we have to ask the perlio system for a stdio FILE *:

        int
        perliofputs(s, stream)
                char *          s
                OutputStream    stream
        PREINIT:
                FILE *fp = PerlIO_findFILE(stream);
        CODE:
                if (fp != (FILE*) 0) {
                        RETVAL = fputs(s, fp);
                } else {
                        RETVAL = -1;
                }
        OUTPUT:
                RETVAL

Note: PerlIO_findFILE() will search the layers for a stdio layer. If it can't find one, it will call PerlIO_exportFILE() to generate a new stdio FILE. Please only call PerlIO_exportFILE() if you want a new FILE. It will generate one on each call and push a new stdio layer. So don't call it repeatedly on the same file. PerlIO()_findFILE will retrieve the stdio layer once it has been generated by PerlIO_exportFILE().

This applies to the perlio system only. For versions before 5.7, PerlIO_exportFILE() is equivalent to PerlIO_findFILE().

Troubleshooting these Examples

As mentioned at the top of this document, if you are having problems with these example extensions, you might see if any of these help you.

  • In versions of 5.002 prior to the gamma version, the test script in Example 1 will not function properly. You need to change the "use lib" line to read:

            use lib './blib';

  • In versions of 5.002 prior to version 5.002b1h, the test.pl file was not automatically created by h2xs. This means that you cannot say "make test" to run the test script. You will need to add the following line before the "use extension" statement:

            use lib './blib';

  • In versions 5.000 and 5.001, instead of using the above line, you will need to use the following line:

            BEGIN { unshift(@INC, "./blib") }

  • This document assumes that the executable named "perl" is Perl version 5. Some systems may have installed Perl version 5 as "perl5".

See also

For more information, consult the perlguts manpage, the perlapi manpage, the perlxs manpage, the perlmod manpage, and the perlpod manpage.

Author

Jeff Okamoto <okamoto@corp.hp.com>

Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, and Tim Bunce.

PerlIO material contributed by Lupe Christoph, with some clarification by Nick Ing-Simmons.

Last Changed

2002/05/08


perlebcdic - Considerations for running Perl on EBCDIC platforms

  • COMMON CHARACTER CODE SETS
    • ASCII
    • ISO 8859
    • Latin 1 (ISO 8859-1)
    • EBCDIC
    • 13 variant characters
    • 0037
    • 1047
    • POSIX-BC
    • Unicode code points versus EBCDIC code points
    • Remaining Perl Unicode problems in EBCDIC
    • Unicode and UTF
    • Using Encode
  • SINGLE OCTET TABLES
  • IDENTIFYING CHARACTER CODE SETS
  • CONVERSIONS
    • tr///
    • iconv
    • C RTL
  • OPERATOR DIFFERENCES
  • FUNCTION DIFFERENCES
  • REGULAR EXPRESSION DIFFERENCES
  • SOCKETS
  • SORTING
    • Ignore ASCII vs. EBCDIC sort differences.
    • MONO CASE then sort data.
    • Convert, sort data, then re convert.
    • Perform sorting on one type of machine only.
  • TRANSFORMATION FORMATS
    • URL decoding and encoding
    • uu encoding and decoding
    • Quoted-Printable encoding and decoding
    • Caesarian ciphers
  • Hashing order and checksums
  • I18N AND L10N
  • MULTI OCTET CHARACTER SETS
  • OS ISSUES
    • OS/400
    • OS/390, z/OS
    • VM/ESA?
    • POSIX-BC?
  • BUGS
  • SEE ALSO
  • REFERENCES
  • HISTORY
  • AUTHOR

NAME

perlebcdic - Considerations for running Perl on EBCDIC platforms

DESCRIPTION

An exploration of some of the issues facing Perl programmers on EBCDIC based computers. We do not cover localization, internationalization, or multi byte character set issues other than some discussion of UTF-8 and UTF-EBCDIC.

Portions that are still incomplete are marked with XXX.

COMMON CHARACTER CODE SETS

ASCII

The American Standard Code for Information Interchange is a set of integers running from 0 to 127 (decimal) that imply character interpretation by the display and other system(s) of computers. The range 0..127 can be covered by setting the bits in a 7-bit binary digit, hence the set is sometimes referred to as a "7-bit ASCII". ASCII was described by the American National Standards Institute document ANSI X3.4-1986. It was also described by ISO 646:1991 (with localization for currency symbols). The full ASCII set is given in the table below as the first 128 elements. Languages that can be written adequately with the characters in ASCII include English, Hawaiian, Indonesian, Swahili and some Native American languages.

There are many character sets that extend the range of integers from 0..2**7-1 up to 2**8-1, or 8 bit bytes (octets if you prefer). One common one is the ISO 8859-1 character set.

ISO 8859

The ISO 8859-$n are a collection of character code sets from the International Organization for Standardization (ISO) each of which adds characters to the ASCII set that are typically found in European languages many of which are based on the Roman, or Latin, alphabet.

Latin 1 (ISO 8859-1)

A particular 8-bit extension to ASCII that includes grave and acute accented Latin characters. Languages that can employ ISO 8859-1 include all the languages covered by ASCII as well as Afrikaans, Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian, Portuguese, Spanish, and Swedish. Dutch is covered albeit without the ij ligature. French is covered too but without the oe ligature. German can use ISO 8859-1 but must do so without German-style quotation marks. This set is based on Western European extensions to ASCII and is commonly encountered in world wide web work. In IBM character code set identification terminology ISO 8859-1 is also known as CCSID 819 (or sometimes 0819 or even 00819).

EBCDIC

The Extended Binary Coded Decimal Interchange Code refers to a large collection of slightly different single and multi byte coded character sets that are different from ASCII or ISO 8859-1 and typically run on host computers. The EBCDIC encodings derive from 8 bit byte extensions of Hollerith punched card encodings. The layout on the cards was such that high bits were set for the upper and lower case alphabet characters [a-z] and [A-Z], but there were gaps within each latin alphabet range.

Some IBM EBCDIC character sets may be known by character code set identification numbers (CCSID numbers) or code page numbers. Leading zero digits in CCSID numbers within this document are insignificant. E.g. CCSID 0037 may be referred to as 37 in places.

13 variant characters

Among IBM EBCDIC character code sets there are 13 characters that are often mapped to different integer values. Those characters are known as the 13 "variant" characters and are:

    \ [ ] { } ^ ~ ! # | $ @ `

0037

Character code set ID 0037 is a mapping of the ASCII plus Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 0037 is used in North American English locales on the OS/400 operating system that runs on AS/400 computers. CCSID 37 differs from ISO 8859-1 in 237 places, in other words they agree on only 19 code point values.

1047

Character code set ID 1047 is also a mapping of the ASCII plus Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 1047 is used under Unix System Services for OS/390 or z/OS, and OpenEdition for VM/ESA. CCSID 1047 differs from CCSID 0037 in eight places.

POSIX-BC

The EBCDIC code page in use on Siemens' BS2000 system is distinct from 1047 and 0037. It is identified below as the POSIX-BC set.

Unicode code points versus EBCDIC code points

In Unicode terminology a code point is the number assigned to a character: for example, in EBCDIC the character "A" is usually assigned the number 193. In Unicode the character "A" is assigned the number 65. This causes a problem with the semantics of the pack/unpack "U", which are supposed to pack Unicode code points to characters and back to numbers. The problem is: which code points to use for code points less than 256? (for 256 and over there's no problem: Unicode code points are used) In EBCDIC, for the low 256 the EBCDIC code points are used. This means that the equivalences

        pack("U", ord($character)) eq $character
        unpack("U", $character) == ord $character

will hold. (If Unicode code points were applied consistently over all the possible code points, pack("U",ord("A")) would in EBCDIC equal A with acute or chr(101), and unpack("U", "A") would equal 65, or non-breaking space, not 193, or ord "A".)

Remaining Perl Unicode problems in EBCDIC

  • Many of the remaining seem to be related to case-insensitive matching: for example, /[\x{131}]/ (LATIN SMALL LETTER DOTLESS I) does not match "I" case-insensitively, as it should under Unicode. (The match succeeds in ASCII-derived platforms.)

  • The extensions Unicode::Collate and Unicode::Normalized are not supported under EBCDIC, likewise for the encoding pragma.

Unicode and UTF

UTF is a Unicode Transformation Format. UTF-8 is a Unicode conforming representation of the Unicode standard that looks very much like ASCII. UTF-EBCDIC is an attempt to represent Unicode characters in an EBCDIC transparent manner.

Using Encode

Starting from Perl 5.8 you can use the standard new module Encode to translate from EBCDIC to Latin-1 code points

        use Encode 'from_to';

        my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' );

        # $a is in EBCDIC code points
        from_to($a, $ebcdic{ord '^'}, 'latin1');
        # $a is ISO 8859-1 code points

and from Latin-1 code points to EBCDIC code points

        use Encode 'from_to';

        my %ebcdic = ( 176 => 'cp37', 95 => 'cp1047', 106 => 'posix-bc' );

        # $a is ISO 8859-1 code points
        from_to($a, 'latin1', $ebcdic{ord '^'});
        # $a is in EBCDIC code points

For doing I/O it is suggested that you use the autotranslating features of PerlIO, see the perluniintro manpage.

Since version 5.8 Perl uses the new PerlIO I/O library. This enables you to use different encodings per IO channel. For example you may use

    use Encode;
    open($f, ">:encoding(ascii)", "test.ascii");
    print $f "Hello World!\n";
    open($f, ">:encoding(cp37)", "test.ebcdic");
    print $f "Hello World!\n";
    open($f, ">:encoding(latin1)", "test.latin1");
    print $f "Hello World!\n";
    open($f, ">:encoding(utf8)", "test.utf8");
    print $f "Hello World!\n";

to get two files containing "Hello World!\n" in ASCII, CP 37 EBCDIC, ISO 8859-1 (Latin-1) (in this example identical to ASCII) respective UTF-EBCDIC (in this example identical to normal EBCDIC). See the documentation of Encode::PerlIO for details.

As the PerlIO layer uses raw IO (bytes) internally, all this totally ignores things like the type of your filesystem (ASCII or EBCDIC).

SINGLE OCTET TABLES

The following tables list the ASCII and Latin 1 ordered sets including the subsets: C0 controls (0..31), ASCII graphics (32..7e), delete (7f), C1 controls (80..9f), and Latin-1 (a.k.a. ISO 8859-1) (a0..ff). In the table non-printing control character names as well as the Latin 1 extensions to ASCII have been labelled with character names roughly corresponding to The Unicode Standard, Version 3.0 albeit with substitutions such as s/LATIN// and s/VULGAR// in all cases, s/CAPITAL LETTER// in some cases, and s/SMALL LETTER ([A-Z])/\l$1/ in some other cases (the charnames pragma names unfortunately do not list explicit names for the C0 or C1 control characters). The "names" of the C1 control set (128..159 in ISO 8859-1) listed here are somewhat arbitrary. The differences between the 0037 and 1047 sets are flagged with ***. The differences between the 1047 and POSIX-BC sets are flagged with ###. All ord() numbers listed are decimal. If you would rather see this table listing octal values then run the table (that is, the pod version of this document since this recipe may not work with a pod2_other_format translation) through:

recipe 0
    perl -ne 'if(/(.{33})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
     -e '{printf("%s%-9o%-9o%-9o%o\n",$1,$2,$3,$4,$5)}' perlebcdic.pod

If you want to retain the UTF-x code points then in script form you might want to write:

recipe 1
    open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
    while (<FH>) {
        if (/(.{33})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)  {
            if ($7 ne '' && $9 ne '') {
                printf("%s%-9o%-9o%-9o%-9o%-3o.%-5o%-3o.%o\n",$1,$2,$3,$4,$5,$6,$7,$8,$9);
            }
            elsif ($7 ne '') {
                printf("%s%-9o%-9o%-9o%-9o%-3o.%-5o%o\n",$1,$2,$3,$4,$5,$6,$7,$8);
            }
            else {
                printf("%s%-9o%-9o%-9o%-9o%-9o%o\n",$1,$2,$3,$4,$5,$6,$8);
            }
        }
    }

If you would rather see this table listing hexadecimal values then run the table through:

recipe 2
    perl -ne 'if(/(.{33})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
     -e '{printf("%s%-9X%-9X%-9X%X\n",$1,$2,$3,$4,$5)}' perlebcdic.pod

Or, in order to retain the UTF-x code points in hexadecimal:

recipe 3
    open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
    while (<FH>) {
        if (/(.{33})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)  {
            if ($7 ne '' && $9 ne '') {
                printf("%s%-9X%-9X%-9X%-9X%-2X.%-6X%-2X.%X\n",$1,$2,$3,$4,$5,$6,$7,$8,$9);
            }
            elsif ($7 ne '') {
                printf("%s%-9X%-9X%-9X%-9X%-2X.%-6X%X\n",$1,$2,$3,$4,$5,$6,$7,$8);
            }
            else {
                printf("%s%-9X%-9X%-9X%-9X%-9X%X\n",$1,$2,$3,$4,$5,$6,$8);
            }
        }
    }

                                                                     incomp-  incomp-
                                 8859-1                              lete     lete
    chr                          0819     0037     1047     POSIX-BC UTF-8    UTF-EBCDIC
    ------------------------------------------------------------------------------------
    <NULL>                       0        0        0        0        0        0
    <START OF HEADING>           1        1        1        1        1        1
    <START OF TEXT>              2        2        2        2        2        2
    <END OF TEXT>                3        3        3        3        3        3
    <END OF TRANSMISSION>        4        55       55       55       4        55
    <ENQUIRY>                    5        45       45       45       5        45
    <ACKNOWLEDGE>                6        46       46       46       6        46
    <BELL>                       7        47       47       47       7        47
    <BACKSPACE>                  8        22       22       22       8        22
    <HORIZONTAL TABULATION>      9        5        5        5        9        5
    <LINE FEED>                  10       37       21       21       10       21       ***
    <VERTICAL TABULATION>        11       11       11       11       11       11
    <FORM FEED>                  12       12       12       12       12       12
    <CARRIAGE RETURN>            13       13       13       13       13       13
    <SHIFT OUT>                  14       14       14       14       14       14
    <SHIFT IN>                   15       15       15       15       15       15
    <DATA LINK ESCAPE>           16       16       16       16       16       16
    <DEVICE CONTROL ONE>         17       17       17       17       17       17
    <DEVICE CONTROL TWO>         18       18       18       18       18       18
    <DEVICE CONTROL THREE>       19       19       19       19       19       19
    <DEVICE CONTROL FOUR>        20       60       60       60       20       60
    <NEGATIVE ACKNOWLEDGE>       21       61       61       61       21       61
    <SYNCHRONOUS IDLE>           22       50       50       50       22       50
    <END OF TRANSMISSION BLOCK>  23       38       38       38       23       38
    <CANCEL>                     24       24       24       24       24       24
    <END OF MEDIUM>              25       25       25       25       25       25
    <SUBSTITUTE>                 26       63       63       63       26       63
    <ESCAPE>                     27       39       39       39       27       39
    <FILE SEPARATOR>             28       28       28       28       28       28
    <GROUP SEPARATOR>            29       29       29       29       29       29
    <RECORD SEPARATOR>           30       30       30       30       30       30
    <UNIT SEPARATOR>             31       31       31       31       31       31
    <SPACE>                      32       64       64       64       32       64
    !                            33       90       90       90       33       90
    "                            34       127      127      127      34       127
    #                            35       123      123      123      35       123
    $                            36       91       91       91       36       91
    %                            37       108      108      108      37       108
    &                            38       80       80       80       38       80
    '                            39       125      125      125      39       125
    (                            40       77       77       77       40       77
    )                            41       93       93       93       41       93
    *                            42       92       92       92       42       92
    +                            43       78       78       78       43       78
    ,                            44       107      107      107      44       107
    -                            45       96       96       96       45       96
    .                            46       75       75       75       46       75
    /                            47       97       97       97       47       97
    0                            48       240      240      240      48       240
    1                            49       241      241      241      49       241
    2                            50       242      242      242      50       242
    3                            51       243      243      243      51       243
    4                            52       244      244      244      52       244
    5                            53       245      245      245      53       245
    6                            54       246      246      246      54       246
    7                            55       247      247      247      55       247
    8                            56       248      248      248      56       248
    9                            57       249      249      249      57       249
    :                            58       122      122      122      58       122
    ;                            59       94       94       94       59       94
    <                            60       76       76       76       60       76
    =                            61       126      126      126      61       126
    >                            62       110      110      110      62       110
    ?                            63       111      111      111      63       111
    @                            64       124      124      124      64       124
    A                            65       193      193      193      65       193
    B                            66       194      194      194      66       194
    C                            67       195      195      195      67       195
    D                            68       196      196      196      68       196
    E                            69       197      197      197      69       197
    F                            70       198      198      198      70       198
    G                            71       199      199      199      71       199
    H                            72       200      200      200      72       200
    I                            73       201      201      201      73       201
    J                            74       209      209      209      74       209
    K                            75       210      210      210      75       210
    L                            76       211      211      211      76       211
    M                            77       212      212      212      77       212
    N                            78       213      213      213      78       213
    O                            79       214      214      214      79       214
    P                            80       215      215      215      80       215
    Q                            81       216      216      216      81       216
    R                            82       217      217      217      82       217
    S                            83       226      226      226      83       226
    T                            84       227      227      227      84       227
    U                            85       228      228      228      85       228
    V                            86       229      229      229      86       229
    W                            87       230      230      230      87       230
    X                            88       231      231      231      88       231
    Y                            89       232      232      232      89       232
    Z                            90       233      233      233      90       233
    [                            91       186      173      187      91       173      *** ###
    \                            92       224      224      188      92       224      ###
    ]                            93       187      189      189      93       189      ***
    ^                            94       176      95       106      94       95       *** ###
    _                            95       109      109      109      95       109
    `                            96       121      121      74       96       121      ###
    a                            97       129      129      129      97       129
    b                            98       130      130      130      98       130
    c                            99       131      131      131      99       131
    d                            100      132      132      132      100      132
    e                            101      133      133      133      101      133
    f                            102      134      134      134      102      134
    g                            103      135      135      135      103      135
    h                            104      136      136      136      104      136
    i                            105      137      137      137      105      137
    j                            106      145      145      145      106      145
    k                            107      146      146      146      107      146
    l                            108      147      147      147      108      147
    m                            109      148      148      148      109      148
    n                            110      149      149      149      110      149
    o                            111      150      150      150      111      150
    p                            112      151      151      151      112      151
    q                            113      152      152      152      113      152
    r                            114      153      153      153      114      153
    s                            115      162      162      162      115      162
    t                            116      163      163      163      116      163
    u                            117      164      164      164      117      164
    v                            118      165      165      165      118      165
    w                            119      166      166      166      119      166
    x                            120      167      167      167      120      167
    y                            121      168      168      168      121      168
    z                            122      169      169      169      122      169
    {                            123      192      192      251      123      192      ###
    |                            124      79       79       79       124      79
    }                            125      208      208      253      125      208      ###
    ~                            126      161      161      255      126      161      ###
    <DELETE>                     127      7        7        7        127      7
    <C1 0>                       128      32       32       32       194.128  32
    <C1 1>                       129      33       33       33       194.129  33
    <C1 2>                       130      34       34       34       194.130  34
    <C1 3>                       131      35       35       35       194.131  35
    <C1 4>                       132      36       36       36       194.132  36
    <C1 5>                       133      21       37       37       194.133  37       ***
    <C1 6>                       134      6        6        6        194.134  6
    <C1 7>                       135      23       23       23       194.135  23
    <C1 8>                       136      40       40       40       194.136  40
    <C1 9>                       137      41       41       41       194.137  41
    <C1 10>                      138      42       42       42       194.138  42
    <C1 11>                      139      43       43       43       194.139  43
    <C1 12>                      140      44       44       44       194.140  44
    <C1 13>                      141      9        9        9        194.141  9
    <C1 14>                      142      10       10       10       194.142  10
    <C1 15>                      143      27       27       27       194.143  27
    <C1 16>                      144      48       48       48       194.144  48
    <C1 17>                      145      49       49       49       194.145  49
    <C1 18>                      146      26       26       26       194.146  26
    <C1 19>                      147      51       51       51       194.147  51
    <C1 20>                      148      52       52       52       194.148  52
    <C1 21>                      149      53       53       53       194.149  53
    <C1 22>                      150      54       54       54       194.150  54
    <C1 23>                      151      8        8        8        194.151  8
    <C1 24>                      152      56       56       56       194.152  56
    <C1 25>                      153      57       57       57       194.153  57
    <C1 26>                      154      58       58       58       194.154  58
    <C1 27>                      155      59       59       59       194.155  59
    <C1 28>                      156      4        4        4        194.156  4
    <C1 29>                      157      20       20       20       194.157  20
    <C1 30>                      158      62       62       62       194.158  62
    <C1 31>                      159      255      255      95       194.159  255      ###
    <NON-BREAKING SPACE>         160      65       65       65       194.160  128.65
    <INVERTED EXCLAMATION MARK>  161      170      170      170      194.161  128.66
    <CENT SIGN>                  162      74       74       176      194.162  128.67   ###
    <POUND SIGN>                 163      177      177      177      194.163  128.68
    <CURRENCY SIGN>              164      159      159      159      194.164  128.69
    <YEN SIGN>                   165      178      178      178      194.165  128.70
    <BROKEN BAR>                 166      106      106      208      194.166  128.71   ###
    <SECTION SIGN>               167      181      181      181      194.167  128.72
    <DIAERESIS>                  168      189      187      121      194.168  128.73   *** ###
    <COPYRIGHT SIGN>             169      180      180      180      194.169  128.74
    <FEMININE ORDINAL INDICATOR> 170      154      154      154      194.170  128.81
    <LEFT POINTING GUILLEMET>    171      138      138      138      194.171  128.82
    <NOT SIGN>                   172      95       176      186      194.172  128.83   *** ###
    <SOFT HYPHEN>                173      202      202      202      194.173  128.84
    <REGISTERED TRADE MARK SIGN> 174      175      175      175      194.174  128.85
    <MACRON>                     175      188      188      161      194.175  128.86   ###
    <DEGREE SIGN>                176      144      144      144      194.176  128.87
    <PLUS-OR-MINUS SIGN>         177      143      143      143      194.177  128.88
    <SUPERSCRIPT TWO>            178      234      234      234      194.178  128.89
    <SUPERSCRIPT THREE>          179      250      250      250      194.179  128.98
    <ACUTE ACCENT>               180      190      190      190      194.180  128.99
    <MICRO SIGN>                 181      160      160      160      194.181  128.100
    <PARAGRAPH SIGN>             182      182      182      182      194.182  128.101
    <MIDDLE DOT>                 183      179      179      179      194.183  128.102
    <CEDILLA>                    184      157      157      157      194.184  128.103
    <SUPERSCRIPT ONE>            185      218      218      218      194.185  128.104
    <MASC. ORDINAL INDICATOR>    186      155      155      155      194.186  128.105
    <RIGHT POINTING GUILLEMET>   187      139      139      139      194.187  128.106
    <FRACTION ONE QUARTER>       188      183      183      183      194.188  128.112
    <FRACTION ONE HALF>          189      184      184      184      194.189  128.113
    <FRACTION THREE QUARTERS>    190      185      185      185      194.190  128.114
    <INVERTED QUESTION MARK>     191      171      171      171      194.191  128.115
    <A WITH GRAVE>               192      100      100      100      195.128  138.65
    <A WITH ACUTE>               193      101      101      101      195.129  138.66
    <A WITH CIRCUMFLEX>          194      98       98       98       195.130  138.67
    <A WITH TILDE>               195      102      102      102      195.131  138.68
    <A WITH DIAERESIS>           196      99       99       99       195.132  138.69
    <A WITH RING ABOVE>          197      103      103      103      195.133  138.70
    <CAPITAL LIGATURE AE>        198      158      158      158      195.134  138.71
    <C WITH CEDILLA>             199      104      104      104      195.135  138.72
    <E WITH GRAVE>               200      116      116      116      195.136  138.73
    <E WITH ACUTE>               201      113      113      113      195.137  138.74
    <E WITH CIRCUMFLEX>          202      114      114      114      195.138  138.81
    <E WITH DIAERESIS>           203      115      115      115      195.139  138.82
    <I WITH GRAVE>               204      120      120      120      195.140  138.83
    <I WITH ACUTE>               205      117      117      117      195.141  138.84
    <I WITH CIRCUMFLEX>          206      118      118      118      195.142  138.85
    <I WITH DIAERESIS>           207      119      119      119      195.143  138.86
    <CAPITAL LETTER ETH>         208      172      172      172      195.144  138.87
    <N WITH TILDE>               209      105      105      105      195.145  138.88
    <O WITH GRAVE>               210      237      237      237      195.146  138.89
    <O WITH ACUTE>               211      238      238      238      195.147  138.98
    <O WITH CIRCUMFLEX>          212      235      235      235      195.148  138.99
    <O WITH TILDE>               213      239      239      239      195.149  138.100
    <O WITH DIAERESIS>           214      236      236      236      195.150  138.101
    <MULTIPLICATION SIGN>        215      191      191      191      195.151  138.102
    <O WITH STROKE>              216      128      128      128      195.152  138.103
    <U WITH GRAVE>               217      253      253      224      195.153  138.104  ###
    <U WITH ACUTE>               218      254      254      254      195.154  138.105
    <U WITH CIRCUMFLEX>          219      251      251      221      195.155  138.106  ###
    <U WITH DIAERESIS>           220      252      252      252      195.156  138.112
    <Y WITH ACUTE>               221      173      186      173      195.157  138.113  *** ###
    <CAPITAL LETTER THORN>       222      174      174      174      195.158  138.114
    <SMALL LETTER SHARP S>       223      89       89       89       195.159  138.115
    <a WITH GRAVE>               224      68       68       68       195.160  139.65
    <a WITH ACUTE>               225      69       69       69       195.161  139.66
    <a WITH CIRCUMFLEX>          226      66       66       66       195.162  139.67
    <a WITH TILDE>               227      70       70       70       195.163  139.68
    <a WITH DIAERESIS>           228      67       67       67       195.164  139.69
    <a WITH RING ABOVE>          229      71       71       71       195.165  139.70
    <SMALL LIGATURE ae>          230      156      156      156      195.166  139.71
    <c WITH CEDILLA>             231      72       72       72       195.167  139.72
    <e WITH GRAVE>               232      84       84       84       195.168  139.73
    <e WITH ACUTE>               233      81       81       81       195.169  139.74
    <e WITH CIRCUMFLEX>          234      82       82       82       195.170  139.81
    <e WITH DIAERESIS>           235      83       83       83       195.171  139.82
    <i WITH GRAVE>               236      88       88       88       195.172  139.83
    <i WITH ACUTE>               237      85       85       85       195.173  139.84
    <i WITH CIRCUMFLEX>          238      86       86       86       195.174  139.85
    <i WITH DIAERESIS>           239      87       87       87       195.175  139.86
    <SMALL LETTER eth>           240      140      140      140      195.176  139.87
    <n WITH TILDE>               241      73       73       73       195.177  139.88
    <o WITH GRAVE>               242      205      205      205      195.178  139.89
    <o WITH ACUTE>               243      206      206      206      195.179  139.98
    <o WITH CIRCUMFLEX>          244      203      203      203      195.180  139.99
    <o WITH TILDE>               245      207      207      207      195.181  139.100
    <o WITH DIAERESIS>           246      204      204      204      195.182  139.101
    <DIVISION SIGN>              247      225      225      225      195.183  139.102
    <o WITH STROKE>              248      112      112      112      195.184  139.103
    <u WITH GRAVE>               249      221      221      192      195.185  139.104  ###
    <u WITH ACUTE>               250      222      222      222      195.186  139.105
    <u WITH CIRCUMFLEX>          251      219      219      219      195.187  139.106
    <u WITH DIAERESIS>           252      220      220      220      195.188  139.112
    <y WITH ACUTE>               253      141      141      141      195.189  139.113
    <SMALL LETTER thorn>         254      142      142      142      195.190  139.114
    <y WITH DIAERESIS>           255      223      223      223      195.191  139.115

If you would rather see the above table in CCSID 0037 order rather than ASCII + Latin-1 order then run the table through:

recipe 4
    perl -ne 'if(/.{33}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
     -e '{push(@l,$_)}' \
     -e 'END{print map{$_->[0]}' \
     -e '          sort{$a->[1] <=> $b->[1]}' \
     -e '          map{[$_,substr($_,42,3)]}@l;}' perlebcdic.pod

If you would rather see it in CCSID 1047 order then change the digit 42 in the last line to 51, like this:

recipe 5
    perl -ne 'if(/.{33}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
     -e '{push(@l,$_)}' \
     -e 'END{print map{$_->[0]}' \
     -e '          sort{$a->[1] <=> $b->[1]}' \
     -e '          map{[$_,substr($_,51,3)]}@l;}' perlebcdic.pod

If you would rather see it in POSIX-BC order then change the digit 51 in the last line to 60, like this:

recipe 6
    perl -ne 'if(/.{33}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
     -e '{push(@l,$_)}' \
     -e 'END{print map{$_->[0]}' \
     -e '          sort{$a->[1] <=> $b->[1]}' \
     -e '          map{[$_,substr($_,60,3)]}@l;}' perlebcdic.pod

IDENTIFYING CHARACTER CODE SETS

To determine the character set you are running under from perl one could use the return value of ord() or chr() to test one or more character values. For example:

    $is_ascii  = "A" eq chr(65);
    $is_ebcdic = "A" eq chr(193);

Also, "\t" is a HORIZONTAL TABULATION character so that:

    $is_ascii  = ord("\t") == 9;
    $is_ebcdic = ord("\t") == 5;

To distinguish EBCDIC code pages try looking at one or more of the characters that differ between them. For example:

    $is_ebcdic_37   = "\n" eq chr(37);
    $is_ebcdic_1047 = "\n" eq chr(21);

Or better still choose a character that is uniquely encoded in any of the code sets, e.g.:

    $is_ascii           = ord('[') == 91;
    $is_ebcdic_37       = ord('[') == 186;
    $is_ebcdic_1047     = ord('[') == 173;
    $is_ebcdic_POSIX_BC = ord('[') == 187;

However, it would be unwise to write tests such as:

    $is_ascii = "\r" ne chr(13);  #  WRONG
    $is_ascii = "\n" ne chr(10);  #  ILL ADVISED

Obviously the first of these will fail to distinguish most ASCII machines from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC machine since "\r" eq chr(13) under all of those coded character sets. But note too that because "\n" is chr(13) and "\r" is chr(10) on the MacIntosh (which is an ASCII machine) the second $is_ascii test will lead to trouble there.

To determine whether or not perl was built under an EBCDIC code page you can use the Config module like so:

    use Config;
    $is_ebcdic = $Config{'ebcdic'} eq 'define';

CONVERSIONS

tr///

In order to convert a string of characters from one character set to another a simple list of numbers, such as in the right columns in the above table, along with perl's tr/// operator is all that is needed. The data in the table are in ASCII order hence the EBCDIC columns provide easy to use ASCII to EBCDIC operations that are also easily reversed.

For example, to convert ASCII to code page 037 take the output of the second column from the output of recipe 0 (modified to add \\ characters) and use it in tr/// like so:

    $cp_037 =
    '\000\001\002\003\234\011\206\177\227\215\216\013\014\015\016\017' .
    '\020\021\022\023\235\205\010\207\030\031\222\217\034\035\036\037' .
    '\200\201\202\203\204\012\027\033\210\211\212\213\214\005\006\007' .
    '\220\221\026\223\224\225\226\004\230\231\232\233\024\025\236\032' .
    '\040\240\342\344\340\341\343\345\347\361\242\056\074\050\053\174' .
    '\046\351\352\353\350\355\356\357\354\337\041\044\052\051\073\254' .
    '\055\057\302\304\300\301\303\305\307\321\246\054\045\137\076\077' .
    '\370\311\312\313\310\315\316\317\314\140\072\043\100\047\075\042' .
    '\330\141\142\143\144\145\146\147\150\151\253\273\360\375\376\261' .
    '\260\152\153\154\155\156\157\160\161\162\252\272\346\270\306\244' .
    '\265\176\163\164\165\166\167\170\171\172\241\277\320\335\336\256' .
    '\136\243\245\267\251\247\266\274\275\276\133\135\257\250\264\327' .
    '\173\101\102\103\104\105\106\107\110\111\255\364\366\362\363\365' .
    '\175\112\113\114\115\116\117\120\121\122\271\373\374\371\372\377' .
    '\134\367\123\124\125\126\127\130\131\132\262\324\326\322\323\325' .
    '\060\061\062\063\064\065\066\067\070\071\263\333\334\331\332\237' ;

    my $ebcdic_string = $ascii_string;
    eval '$ebcdic_string =~ tr/' . $cp_037 . '/\000-\377/';

To convert from EBCDIC 037 to ASCII just reverse the order of the tr/// arguments like so:

    my $ascii_string = $ebcdic_string;
    eval '$ascii_string =~ tr/\000-\377/' . $cp_037 . '/';

Similarly one could take the output of the third column from recipe 0 to obtain a $cp_1047 table. The fourth column of the output from recipe 0 could provide a $cp_posix_bc table suitable for transcoding as well.

iconv

XPG operability often implies the presence of an iconv utility available from the shell or from the C library. Consult your system's documentation for information on iconv.

On OS/390 or z/OS see the iconv(1) manpage. One way to invoke the iconv shell utility from within perl would be to:

    # OS/390 or z/OS example
    $ascii_data = `echo '$ebcdic_data'| iconv -f IBM-1047 -t ISO8859-1`

or the inverse map:

    # OS/390 or z/OS example
    $ebcdic_data = `echo '$ascii_data'| iconv -f ISO8859-1 -t IBM-1047`

For other perl based conversion options see the Convert::* modules on CPAN.

C RTL

The OS/390 and z/OS C run time libraries provide _atoe() and _etoa() functions.

OPERATOR DIFFERENCES

The .. range operator treats certain character ranges with care on EBCDIC machines. For example the following array will have twenty six elements on either an EBCDIC machine or an ASCII machine:

    @alphabet = ('A'..'Z');   #  $#alphabet == 25

The bitwise operators such as & ^ | may return different results when operating on string or character data in a perl program running on an EBCDIC machine than when run on an ASCII machine. Here is an example adapted from the one in the perlop manpage:

    # EBCDIC-based examples
    print "j p \n" ^ " a h";                      # prints "JAPH\n"
    print "JA" | "  ph\n";                        # prints "japh\n"
    print "JAPH\nJunk" & "\277\277\277\277\277";  # prints "japh\n";
    print 'p N$' ^ " E<H\n";                      # prints "Perl\n";

An interesting property of the 32 C0 control characters in the ASCII table is that they can "literally" be constructed as control characters in perl, e.g. (chr(0) eq "\c@") (chr(1) eq "\cA"), and so on. Perl on EBCDIC machines has been ported to take "\c@" to chr(0) and "\cA" to chr(1) as well, but the thirty three characters that result depend on which code page you are using. The table below uses the character names from the previous table but with substitutions such as s/START OF/S.O./; s/END OF /E.O./; s/TRANSMISSION/TRANS./; s/TABULATION/TAB./; s/VERTICAL/VERT./; s/HORIZONTAL/HORIZ./; s/DEVICE CONTROL/D.C./; s/SEPARATOR/SEP./; s/NEGATIVE ACKNOWLEDGE/NEG. ACK./;. The POSIX-BC and 1047 sets are identical throughout this range and differ from the 0037 set at only one spot (21 decimal). Note that the LINE FEED character may be generated by "\cJ" on ASCII machines but by "\cU" on 1047 or POSIX-BC machines and cannot be generated as a "\c.letter." control character on 0037 machines. Note also that "\c\\" maps to two characters not one.

    chr   ord  8859-1               0037                1047 && POSIX-BC
    ------------------------------------------------------------------------
    "\c?" 127  <DELETE>             "                   "              ***><
    "\c@"   0  <NULL>               <NULL>              <NULL>         ***><
    "\cA"   1  <S.O. HEADING>       <S.O. HEADING>      <S.O. HEADING>
    "\cB"   2  <S.O. TEXT>          <S.O. TEXT>         <S.O. TEXT>
    "\cC"   3  <E.O. TEXT>          <E.O. TEXT>         <E.O. TEXT>
    "\cD"   4  <E.O. TRANS.>        <C1 28>             <C1 28>
    "\cE"   5  <ENQUIRY>            <HORIZ. TAB.>       <HORIZ. TAB.>
    "\cF"   6  <ACKNOWLEDGE>        <C1 6>              <C1 6>
    "\cG"   7  <BELL>               <DELETE>            <DELETE>
    "\cH"   8  <BACKSPACE>          <C1 23>             <C1 23>
    "\cI"   9  <HORIZ. TAB.>        <C1 13>             <C1 13>
    "\cJ"  10  <LINE FEED>          <C1 14>             <C1 14>
    "\cK"  11  <VERT. TAB.>         <VERT. TAB.>        <VERT. TAB.>
    "\cL"  12  <FORM FEED>          <FORM FEED>         <FORM FEED>
    "\cM"  13  <CARRIAGE RETURN>    <CARRIAGE RETURN>   <CARRIAGE RETURN>
    "\cN"  14  <SHIFT OUT>          <SHIFT OUT>         <SHIFT OUT>
    "\cO"  15  <SHIFT IN>           <SHIFT IN>          <SHIFT IN>
    "\cP"  16  <DATA LINK ESCAPE>   <DATA LINK ESCAPE>  <DATA LINK ESCAPE>
    "\cQ"  17  <D.C. ONE>           <D.C. ONE>          <D.C. ONE>
    "\cR"  18  <D.C. TWO>           <D.C. TWO>          <D.C. TWO>
    "\cS"  19  <D.C. THREE>         <D.C. THREE>        <D.C. THREE>
    "\cT"  20  <D.C. FOUR>          <C1 29>             <C1 29>
    "\cU"  21  <NEG. ACK.>          <C1 5>              <LINE FEED>    ***
    "\cV"  22  <SYNCHRONOUS IDLE>   <BACKSPACE>         <BACKSPACE>
    "\cW"  23  <E.O. TRANS. BLOCK>  <C1 7>              <C1 7>
    "\cX"  24  <CANCEL>             <CANCEL>            <CANCEL>
    "\cY"  25  <E.O. MEDIUM>        <E.O. MEDIUM>       <E.O. MEDIUM>
    "\cZ"  26  <SUBSTITUTE>         <C1 18>             <C1 18>
    "\c["  27  <ESCAPE>             <C1 15>             <C1 15>
    "\c\\" 28  <FILE SEP.>\         <FILE SEP.>\        <FILE SEP.>\
    "\c]"  29  <GROUP SEP.>         <GROUP SEP.>        <GROUP SEP.>
    "\c^"  30  <RECORD SEP.>        <RECORD SEP.>       <RECORD SEP.>  ***><
    "\c_"  31  <UNIT SEP.>          <UNIT SEP.>         <UNIT SEP.>    ***><

FUNCTION DIFFERENCES

chr()

chr() must be given an EBCDIC code number argument to yield a desired character return value on an EBCDIC machine. For example:

    $CAPITAL_LETTER_A = chr(193);
ord()

ord() will return EBCDIC code number values on an EBCDIC machine. For example:

    $the_number_193 = ord("A");
pack()

The c and C templates for pack() are dependent upon character set encoding. Examples of usage on EBCDIC include:

    $foo = pack("CCCC",193,194,195,196);
    # $foo eq "ABCD"
    $foo = pack("C4",193,194,195,196);
    # same thing

    $foo = pack("ccxxcc",193,194,195,196);
    # $foo eq "AB\0\0CD"
print()

One must be careful with scalars and strings that are passed to print that contain ASCII encodings. One common place for this to occur is in the output of the MIME type header for CGI script writing. For example, many perl programming guides recommend something similar to:

    print "Content-type:\ttext/html\015\012\015\012";
    # this may be wrong on EBCDIC

Under the IBM OS/390 USS Web Server or WebSphere on z/OS for example you should instead write that as:

    print "Content-type:\ttext/html\r\n\r\n"; # OK for DGW et alia

That is because the translation from EBCDIC to ASCII is done by the web server in this case (such code will not be appropriate for the Macintosh however). Consult your web server's documentation for further details.

printf()

The formats that can convert characters to numbers and vice versa will be different from their ASCII counterparts when executed on an EBCDIC machine. Examples include:

    printf("%c%c%c",193,194,195);  # prints ABC
sort()

EBCDIC sort results may differ from ASCII sort results especially for mixed case strings. This is discussed in more detail below.

sprintf()

See the discussion of printf() above. An example of the use of sprintf would be:

    $CAPITAL_LETTER_A = sprintf("%c",193);
unpack()

See the discussion of pack() above.

REGULAR EXPRESSION DIFFERENCES

As of perl 5.005_03 the letter range regular expression such as [A-Z] and [a-z] have been especially coded to not pick up gap characters. For example, characters such as ô o WITH CIRCUMFLEX that lie between I and J would not be matched by the regular expression range /[H-K]/. This works in the other direction, too, if either of the range end points is explicitly numeric: [\x89-\x91] will match \x8e, even though \x89 is i and \x91 is j, and \x8e is a gap character from the alphabetic viewpoint.

If you do want to match the alphabet gap characters in a single octet regular expression try matching the hex or octal code such as /\313/ on EBCDIC or /\364/ on ASCII machines to have your regular expression match o WITH CIRCUMFLEX.

Another construct to be wary of is the inappropriate use of hex or octal constants in regular expressions. Consider the following set of subs:

    sub is_c0 {
        my $char = substr(shift,0,1);
        $char =~ /[\000-\037]/;
    }

    sub is_print_ascii {
        my $char = substr(shift,0,1);
        $char =~ /[\040-\176]/;
    }

    sub is_delete {
        my $char = substr(shift,0,1);
        $char eq "\177";
    }

    sub is_c1 {
        my $char = substr(shift,0,1);
        $char =~ /[\200-\237]/;
    }

    sub is_latin_1 {
        my $char = substr(shift,0,1);
        $char =~ /[\240-\377]/;
    }

The above would be adequate if the concern was only with numeric code points. However, the concern may be with characters rather than code points and on an EBCDIC machine it may be desirable for constructs such as if (is_print_ascii("A")) {print "A is a printable character\n";} to print out the expected message. One way to represent the above collection of character classification subs that is capable of working across the four coded character sets discussed in this document is as follows:

    sub Is_c0 {
        my $char = substr(shift,0,1);
        if (ord('^')==94)  { # ascii
            return $char =~ /[\000-\037]/;
        }
        if (ord('^')==176) { # 37
            return $char =~ /[\000-\003\067\055-\057\026\005\045\013-\023\074\075\062\046\030\031\077\047\034-\037]/;
        }
        if (ord('^')==95 || ord('^')==106) { # 1047 || posix-bc
            return $char =~ /[\000-\003\067\055-\057\026\005\025\013-\023\074\075\062\046\030\031\077\047\034-\037]/;
        }
    }

    sub Is_print_ascii {
        my $char = substr(shift,0,1);
        $char =~ /[ !"\#\$%&'()*+,\-.\/0-9:;<=>?\@A-Z[\\\]^_`a-z{|}~]/;
    }

    sub Is_delete {
        my $char = substr(shift,0,1);
        if (ord('^')==94)  { # ascii
            return $char eq "\177";
        }
        else  {              # ebcdic
            return $char eq "\007";
        }
    }

    sub Is_c1 {
        my $char = substr(shift,0,1);
        if (ord('^')==94)  { # ascii
            return $char =~ /[\200-\237]/;
        }
        if (ord('^')==176) { # 37
            return $char =~ /[\040-\044\025\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\377]/;
        }
        if (ord('^')==95)  { # 1047
            return $char =~ /[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\377]/;
        }
        if (ord('^')==106) { # posix-bc
            return $char =~
              /[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\137]/;
        }
    }

    sub Is_latin_1 {
        my $char = substr(shift,0,1);
        if (ord('^')==94)  { # ascii
            return $char =~ /[\240-\377]/;
        }
        if (ord('^')==176) { # 37
            return $char =~
              /[\101\252\112\261\237\262\152\265\275\264\232\212\137\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
        }
        if (ord('^')==95)  { # 1047
            return $char =~
              /[\101\252\112\261\237\262\152\265\273\264\232\212\260\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\272\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
        }
        if (ord('^')==106) { # posix-bc
            return $char =~
              /[\101\252\260\261\237\262\320\265\171\264\232\212\272\312\257\241\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\340\376\335\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\300\336\333\334\215\216\337]/;
        }
    }

Note however that only the Is_ascii_print() sub is really independent of coded character set. Another way to write Is_latin_1() would be to use the characters in the range explicitly:

    sub Is_latin_1 {
        my $char = substr(shift,0,1);
        $char =~ /[ ¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ]/;
    }

Although that form may run into trouble in network transit (due to the presence of 8 bit characters) or on non ISO-Latin character sets.

SOCKETS

Most socket programming assumes ASCII character encodings in network byte order. Exceptions can include CGI script writing under a host web server where the server may take care of translation for you. Most host web servers convert EBCDIC data to ISO-8859-1 or Unicode on output.

SORTING

One big difference between ASCII based character sets and EBCDIC ones are the relative positions of upper and lower case letters and the letters compared to the digits. If sorted on an ASCII based machine the two letter abbreviation for a physician comes before the two letter for drive, that is:

    @sorted = sort(qw(Dr. dr.));  # @sorted holds ('Dr.','dr.') on ASCII,
                                  # but ('dr.','Dr.') on EBCDIC

The property of lower case before uppercase letters in EBCDIC is even carried to the Latin 1 EBCDIC pages such as 0037 and 1047. An example would be that Ë E WITH DIAERESIS (203) comes before ë e WITH DIAERESIS (235) on an ASCII machine, but the latter (83) comes before the former (115) on an EBCDIC machine. (Astute readers will note that the upper case version of ß SMALL LETTER SHARP S is simply "SS" and that the upper case version of ÿ y WITH DIAERESIS is not in the 0..255 range but it is at U+x0178 in Unicode, or "\x{178}" in a Unicode enabled Perl).

The sort order will cause differences between results obtained on ASCII machines versus EBCDIC machines. What follows are some suggestions on how to deal with these differences.

Ignore ASCII vs. EBCDIC sort differences.

This is the least computationally expensive strategy. It may require some user education.

MONO CASE then sort data.

In order to minimize the expense of mono casing mixed test try to tr/// towards the character set case most employed within the data. If the data are primarily UPPERCASE non Latin 1 then apply tr/[a-z]/[A-Z]/ then sort(). If the data are primarily lowercase non Latin 1 then apply tr/[A-Z]/[a-z]/ before sorting. If the data are primarily UPPERCASE and include Latin-1 characters then apply:

    tr/[a-z]/[A-Z]/;
    tr/[àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ]/[ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ]/;
    s/ß/SS/g;

then sort(). Do note however that such Latin-1 manipulation does not address the ÿ y WITH DIAERESIS character that will remain at code point 255 on ASCII machines, but 223 on most EBCDIC machines where it will sort to a place less than the EBCDIC numerals. With a Unicode enabled Perl you might try:

    tr/^?/\x{178}/;

The strategy of mono casing data before sorting does not preserve the case of the data and may not be acceptable for that reason.

Convert, sort data, then re convert.

This is the most expensive proposition that does not employ a network connection.

Perform sorting on one type of machine only.

This strategy can employ a network connection. As such it would be computationally expensive.

TRANSFORMATION FORMATS

There are a variety of ways of transforming data with an intra character set mapping that serve a variety of purposes. Sorting was discussed in the previous section and a few of the other more popular mapping techniques are discussed next.

URL decoding and encoding

Note that some URLs have hexadecimal ASCII code points in them in an attempt to overcome character or protocol limitation issues. For example the tilde character is not on every keyboard hence a URL of the form:

    http://www.pvhp.com/~pvhp/

may also be expressed as either of:

    http://www.pvhp.com/%7Epvhp/
    http://www.pvhp.com/%7epvhp/

where 7E is the hexadecimal ASCII code point for '~'. Here is an example of decoding such a URL under CCSID 1047:

    $url = 'http://www.pvhp.com/%7Epvhp/';
    # this array assumes code page 1047
    my @a2e_1047 = (
          0,  1,  2,  3, 55, 45, 46, 47, 22,  5, 21, 11, 12, 13, 14, 15,
         16, 17, 18, 19, 60, 61, 50, 38, 24, 25, 63, 39, 28, 29, 30, 31,
         64, 90,127,123, 91,108, 80,125, 77, 93, 92, 78,107, 96, 75, 97,
        240,241,242,243,244,245,246,247,248,249,122, 94, 76,126,110,111,
        124,193,194,195,196,197,198,199,200,201,209,210,211,212,213,214,
        215,216,217,226,227,228,229,230,231,232,233,173,224,189, 95,109,
        121,129,130,131,132,133,134,135,136,137,145,146,147,148,149,150,
        151,152,153,162,163,164,165,166,167,168,169,192, 79,208,161,  7,
         32, 33, 34, 35, 36, 37,  6, 23, 40, 41, 42, 43, 44,  9, 10, 27,
         48, 49, 26, 51, 52, 53, 54,  8, 56, 57, 58, 59,  4, 20, 62,255,
         65,170, 74,177,159,178,106,181,187,180,154,138,176,202,175,188,
        144,143,234,250,190,160,182,179,157,218,155,139,183,184,185,171,
        100,101, 98,102, 99,103,158,104,116,113,114,115,120,117,118,119,
        172,105,237,238,235,239,236,191,128,253,254,251,252,186,174, 89,
         68, 69, 66, 70, 67, 71,156, 72, 84, 81, 82, 83, 88, 85, 86, 87,
        140, 73,205,206,203,207,204,225,112,221,222,219,220,141,142,223
    );
    $url =~ s/%([0-9a-fA-F]{2})/pack("c",$a2e_1047[hex($1)])/ge;

Conversely, here is a partial solution for the task of encoding such a URL under the 1047 code page:

    $url = 'http://www.pvhp.com/~pvhp/';
    # this array assumes code page 1047
    my @e2a_1047 = (
          0,  1,  2,  3,156,  9,134,127,151,141,142, 11, 12, 13, 14, 15,
         16, 17, 18, 19,157, 10,  8,135, 24, 25,146,143, 28, 29, 30, 31,
        128,129,130,131,132,133, 23, 27,136,137,138,139,140,  5,  6,  7,
        144,145, 22,147,148,149,150,  4,152,153,154,155, 20, 21,158, 26,
         32,160,226,228,224,225,227,229,231,241,162, 46, 60, 40, 43,124,
         38,233,234,235,232,237,238,239,236,223, 33, 36, 42, 41, 59, 94,
         45, 47,194,196,192,193,195,197,199,209,166, 44, 37, 95, 62, 63,
        248,201,202,203,200,205,206,207,204, 96, 58, 35, 64, 39, 61, 34,
        216, 97, 98, 99,100,101,102,103,104,105,171,187,240,253,254,177,
        176,106,107,108,109,110,111,112,113,114,170,186,230,184,198,164,
        181,126,115,116,117,118,119,120,121,122,161,191,208, 91,222,174,
        172,163,165,183,169,167,182,188,189,190,221,168,175, 93,180,215,
        123, 65, 66, 67, 68, 69, 70, 71, 72, 73,173,244,246,242,243,245,
        125, 74, 75, 76, 77, 78, 79, 80, 81, 82,185,251,252,249,250,255,
         92,247, 83, 84, 85, 86, 87, 88, 89, 90,178,212,214,210,211,213,
         48, 49, 50, 51, 52, 53, 54, 55, 56, 57,179,219,220,217,218,159
    );
    # The following regular expression does not address the
    # mappings for: ('.' => '%2E', '/' => '%2F', ':' => '%3A')
    $url =~ s/([\t "#%&\(\),;<=>\?\@\[\\\]^`{|}~])/sprintf("%%%02X",$e2a_1047[ord($1)])/ge;

where a more complete solution would split the URL into components and apply a full s/// substitution only to the appropriate parts.

In the remaining examples a @e2a or @a2e array may be employed but the assignment will not be shown explicitly. For code page 1047 you could use the @a2e_1047 or @e2a_1047 arrays just shown.

uu encoding and decoding

The u template to pack() or unpack() will render EBCDIC data in EBCDIC characters equivalent to their ASCII counterparts. For example, the following will print "Yes indeed\n" on either an ASCII or EBCDIC computer:

    $all_byte_chrs = '';
    for (0..255) { $all_byte_chrs .= chr($_); }
    $uuencode_byte_chrs = pack('u', $all_byte_chrs);
    ($uu = <<'ENDOFHEREDOC') =~ s/^\s*//gm;
    M``$"`P0%!@<("0H+#`T.#Q`1$A,4%187&!D:&QP='A\@(2(C)"4F)R@I*BLL
    M+2XO,#$R,S0U-C<X.3H[/#T^/T!!0D-$149'2$E*2TQ-3D]045)35%565UA9
    M6EM<75Y?8&%B8V1E9F=H:6IK;&UN;W!Q<G-T=79W>'EZ>WQ]?G^`@8*#A(6&
    MAXB)BHN,C8Z/D)&2DY25EI>8F9J;G)V>GZ"AHJ.DI::GJ*FJJZRMKJ^PL;*S
    MM+6VM[BYNKN\O;Z_P,'"P\3%QL?(R<K+S,W.S]#1TM/4U=;7V-G:V]S=WM_@
    ?X>+CY.7FY^CIZNOL[>[O\/'R\_3U]O?X^?K[_/W^_P``
    ENDOFHEREDOC
    if ($uuencode_byte_chrs eq $uu) {
        print "Yes ";
    }
    $uudecode_byte_chrs = unpack('u', $uuencode_byte_chrs);
    if ($uudecode_byte_chrs eq $all_byte_chrs) {
        print "indeed\n";
    }

Here is a very spartan uudecoder that will work on EBCDIC provided that the @e2a array is filled in appropriately:

    #!/usr/local/bin/perl
    @e2a = ( # this must be filled in
           );
    $_ = <> until ($mode,$file) = /^begin\s*(\d*)\s*(\S*)/;
    open(OUT, "> $file") if $file ne "";
    while(<>) {
        last if /^end/;
        next if /[a-z]/;
        next unless int(((($e2a[ord()] - 32 ) & 077) + 2) / 3) ==
            int(length() / 4);
        print OUT unpack("u", $_);
    }
    close(OUT);
    chmod oct($mode), $file;

Quoted-Printable encoding and decoding

On ASCII encoded machines it is possible to strip characters outside of the printable set using:

    # This QP encoder works on ASCII only
    $qp_string =~ s/([=\x00-\x1F\x80-\xFF])/sprintf("=%02X",ord($1))/ge;

Whereas a QP encoder that works on both ASCII and EBCDIC machines would look somewhat like the following (where the EBCDIC branch @e2a array is omitted for brevity):

    if (ord('A') == 65) {    # ASCII
        $delete = "\x7F";    # ASCII
        @e2a = (0 .. 255)    # ASCII to ASCII identity map
    }
    else {                   # EBCDIC
        $delete = "\x07";    # EBCDIC
        @e2a =               # EBCDIC to ASCII map (as shown above)
    }
    $qp_string =~
      s/([^ !"\#\$%&'()*+,\-.\/0-9:;<>?\@A-Z[\\\]^_`a-z{|}~$delete])/sprintf("=%02X",$e2a[ord($1)])/ge;

(although in production code the substitutions might be done in the EBCDIC branch with the @e2a array and separately in the ASCII branch without the expense of the identity map).

Such QP strings can be decoded with:

    # This QP decoder is limited to ASCII only
    $string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr hex $1/ge;
    $string =~ s/=[\n\r]+$//;

Whereas a QP decoder that works on both ASCII and EBCDIC machines would look somewhat like the following (where the @a2e array is omitted for brevity):

    $string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr $a2e[hex $1]/ge;
    $string =~ s/=[\n\r]+$//;

Caesarian ciphers

The practice of shifting an alphabet one or more characters for encipherment dates back thousands of years and was explicitly detailed by Gaius Julius Caesar in his Gallic Wars text. A single alphabet shift is sometimes referred to as a rotation and the shift amount is given as a number $n after the string 'rot' or "rot$n". Rot0 and rot26 would designate identity maps on the 26 letter English version of the Latin alphabet. Rot13 has the interesting property that alternate subsequent invocations are identity maps (thus rot13 is its own non-trivial inverse in the group of 26 alphabet rotations). Hence the following is a rot13 encoder and decoder that will work on ASCII and EBCDIC machines:

    #!/usr/local/bin/perl

    while(<>){
        tr/n-za-mN-ZA-M/a-zA-Z/;
        print;
    }

In one-liner form:

    perl -ne 'tr/n-za-mN-ZA-M/a-zA-Z/;print'

Hashing order and checksums

To the extent that it is possible to write code that depends on hashing order there may be differences between hashes as stored on an ASCII based machine and hashes stored on an EBCDIC based machine. XXX

I18N AND L10N

Internationalization(I18N) and localization(L10N) are supported at least in principle even on EBCDIC machines. The details are system dependent and discussed under the OS ISSUES in the perlebcdic manpage section below.

MULTI OCTET CHARACTER SETS

Perl may work with an internal UTF-EBCDIC encoding form for wide characters on EBCDIC platforms in a manner analogous to the way that it works with the UTF-8 internal encoding form on ASCII based platforms.

Legacy multi byte EBCDIC code pages XXX.

OS ISSUES

There may be a few system dependent issues of concern to EBCDIC Perl programmers.

OS/400

PASE

The PASE environment is runtime environment for OS/400 that can run executables built for PowerPC AIX in OS/400, see the perlos400 manpage. PASE is ASCII-based, not EBCDIC-based as the ILE.

IFS access

XXX.

OS/390, z/OS

Perl runs under Unix Systems Services or USS.

chcp

chcp is supported as a shell utility for displaying and changing one's code page. See also chcp.

dataset access

For sequential data set access try:

    my @ds_records = `cat //DSNAME`;

or:

    my @ds_records = `cat //'HLQ.DSNAME'`;

See also the OS390::Stdio module on CPAN.

OS/390, z/OS iconv

iconv is supported as both a shell utility and a C RTL routine. See also the iconv(1) and iconv(3) manual pages.

locales

On OS/390 or z/OS see the locale manpage for information on locales. The L10N files are in /usr/nls/locale. $Config{d_setlocale} is 'define' on OS/390 or z/OS.

VM/ESA?

XXX.

POSIX-BC?

XXX.

BUGS

This pod document contains literal Latin 1 characters and may encounter translation difficulties. In particular one popular nroff implementation was known to strip accented characters to their unaccented counterparts while attempting to view this document through the pod2man program (for example, you may see a plain y rather than one with a diaeresis as in ÿ). Another nroff truncated the resultant manpage at the first occurrence of 8 bit characters.

Not all shells will allow multiple -e string arguments to perl to be concatenated together properly as recipes 0, 2, 4, 5, and 6 might seem to imply.

SEE ALSO

the perllocale manpage, the perlfunc manpage, the perlunicode manpage, the utf8 manpage.

REFERENCES

http://anubis.dkuug.dk/i18n/charmaps

http://www.unicode.org/

http://www.unicode.org/unicode/reports/tr16/

http://www.wps.com/texts/codes/ ASCII: American Standard Code for Information Infiltration Tom Jennings, September 1999.

The Unicode Standard, Version 3.0 The Unicode Consortium, Lisa Moore ed., ISBN 0-201-61633-5, Addison Wesley Developers Press, February 2000.

CDRA: IBM - Character Data Representation Architecture - Reference and Registry, IBM SC09-2190-00, December 1996.

"Demystifying Character Sets", Andrea Vine, Multilingual Computing & Technology, #26 Vol. 10 Issue 4, August/September 1999; ISSN 1523-0309; Multilingual Computing Inc. Sandpoint ID, USA.

Codes, Ciphers, and Other Cryptic and Clandestine Communication Fred B. Wrixon, ISBN 1-57912-040-7, Black Dog & Leventhal Publishers, 1998.

http://www.bobbemer.com/P-BIT.HTM IBM - EBCDIC and the P-bit; The biggest Computer Goof Ever Robert Bemer.

HISTORY

15 April 2001: added UTF-8 and UTF-EBCDIC to main table, pvhp.

AUTHOR

Peter Prymmer pvhp@best.com wrote this in 1999 and 2000 with CCSID 0819 and 0037 help from Chris Leach and André Pirard A.Pirard@ulg.ac.be as well as POSIX-BC help from Thomas Dorner Thomas.Dorner@start.de. Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and Joe Smith. Trademarks, registered trademarks, service marks and registered service marks used in this document are the property of their respective owners.


perlunicode - Unicode support in Perl

    • Important Caveats
    • Byte and Character Semantics
    • Effects of Character Semantics
    • Scripts
    • Blocks
    • User-Defined Character Properties
    • Character Encodings for Input and Output
    • Unicode Regular Expression Support Level
    • Unicode Encodings
    • Security Implications of Unicode
    • Unicode in Perl on EBCDIC
    • Locales
    • When Unicode Does Not Happen
    • Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
    • Using Unicode in XS
  • BUGS
    • Interaction with Locales
    • Interaction with Extensions
    • Speed
    • Porting code from perl-5.6.X
  • SEE ALSO

NAME

perlunicode - Unicode support in Perl

DESCRIPTION

Important Caveats

Unicode support is an extensive requirement. While Perl does not implement the Unicode standard or the accompanying technical reports from cover to cover, Perl does support many Unicode features.

Input and Output Layers

Perl knows when a filehandle uses Perl's internal Unicode encodings (UTF-8, or UTF-EBCDIC if in EBCDIC) if the filehandle is opened with the ":utf8" layer. Other encodings can be converted to Perl's encoding on input or from Perl's encoding on output by use of the ":encoding(...)" layer. See the open manpage.

To indicate that Perl source itself is using a particular encoding, see the encoding manpage.

Regular Expressions

The regular expression compiler produces polymorphic opcodes. That is, the pattern adapts to the data and automatically switches to the Unicode character scheme when presented with Unicode data--or instead uses a traditional byte scheme when presented with byte data.

use utf8 still needed to enable UTF-8/UTF-EBCDIC in scripts

As a compatibility measure, the use utf8 pragma must be explicitly included to enable recognition of UTF-8 in the Perl scripts themselves (in string or regular expression literals, or in identifier names) on ASCII-based machines or to recognize UTF-EBCDIC on EBCDIC-based machines. These are the only times when an explicit use utf8 is needed. See the utf8 manpage.

You can also use the encoding pragma to change the default encoding of the data in your script; see the encoding manpage.

BOM-marked scripts and UTF-16 scripts autodetected

If a Perl script begins marked with the Unicode BOM (UTF-16LE, UTF16-BE, or UTF-8), or if the script looks like non-BOM-marked UTF-16 of either endianness, Perl will correctly read in the script as Unicode. (BOMless UTF-8 cannot be effectively recognized or differentiated from ISO 8859-1 or other eight-bit encodings.)

use encoding needed to upgrade non-Latin-1 byte strings

By default, there is a fundamental asymmetry in Perl's unicode model: implicit upgrading from byte strings to Unicode strings assumes that they were encoded in ISO 8859-1 (Latin-1), but Unicode strings are downgraded with UTF-8 encoding. This happens because the first 256 codepoints in Unicode happens to agree with Latin-1.

If you wish to interpret byte strings as UTF-8 instead, use the encoding pragma:

    use encoding 'utf8';

See Byte and Character Semantics for more details.

Byte and Character Semantics

Beginning with version 5.6, Perl uses logically-wide characters to represent strings internally.

In future, Perl-level operations will be expected to work with characters rather than bytes.

However, as an interim compatibility measure, Perl aims to provide a safe migration path from byte semantics to character semantics for programs. For operations where Perl can unambiguously decide that the input data are characters, Perl switches to character semantics. For operations where this determination cannot be made without additional information from the user, Perl decides in favor of compatibility and chooses to use byte semantics.

This behavior preserves compatibility with earlier versions of Perl, which allowed byte semantics in Perl operations only if none of the program's inputs were marked as being as source of Unicode character data. Such data may come from filehandles, from calls to external programs, from information provided by the system (such as %ENV), or from literals and constants in the source text.

The bytes pragma will always, regardless of platform, force byte semantics in a particular lexical scope. See the bytes manpage.

The utf8 pragma is primarily a compatibility device that enables recognition of UTF-(8|EBCDIC) in literals encountered by the parser. Note that this pragma is only required while Perl defaults to byte semantics; when character semantics become the default, this pragma may become a no-op. See the utf8 manpage.

Unless explicitly stated, Perl operators use character semantics for Unicode data and byte semantics for non-Unicode data. The decision to use character semantics is made transparently. If input data comes from a Unicode source--for example, if a character encoding layer is added to a filehandle or a literal Unicode string constant appears in a program--character semantics apply. Otherwise, byte semantics are in effect. The bytes pragma should be used to force byte semantics on Unicode data.

If strings operating under byte semantics and strings with Unicode character data are concatenated, the new string will be created by decoding the byte strings as ISO 8859-1 (Latin-1), even if the old Unicode string used EBCDIC. This translation is done without regard to the system's native 8-bit encoding. To change this for systems with non-Latin-1 and non-EBCDIC native encodings, use the encoding pragma. See the encoding manpage.

Under character semantics, many operations that formerly operated on bytes now operate on characters. A character in Perl is logically just a number ranging from 0 to 2**31 or so. Larger characters may encode into longer sequences of bytes internally, but this internal detail is mostly hidden for Perl code. See the perluniintro manpage for more.

Effects of Character Semantics

Character semantics have the following effects:

  • Strings--including hash keys--and regular expression patterns may contain characters that have an ordinal value larger than 255.

    If you use a Unicode editor to edit your program, Unicode characters may occur directly within the literal strings in one of the various Unicode encodings (UTF-8, UTF-EBCDIC, UCS-2, etc.), but will be recognized as such and converted to Perl's internal representation only if the appropriate the encoding manpage is specified.

    Unicode characters can also be added to a string by using the \x{...} notation. The Unicode code for the desired character, in hexadecimal, should be placed in the braces. For instance, a smiley face is \x{263A}. This encoding scheme only works for characters with a code of 0x100 or above.

    Additionally, if you

       use charnames ':full';

    you can use the \N{...} notation and put the official Unicode character name within the braces, such as \N{WHITE SMILING FACE}.

  • If an appropriate the encoding manpage is specified, identifiers within the Perl script may contain Unicode alphanumeric characters, including ideographs. Perl does not currently attempt to canonicalize variable names.

  • Regular expressions match characters instead of bytes. "." matches a character instead of a byte. The \C pattern is provided to force a match a single byte--a char in C, hence \C.

  • Character classes in regular expressions match characters instead of bytes and match against the character properties specified in the Unicode properties database. \w can be used to match a Japanese ideograph, for instance.

    (However, and as a limitation of the current implementation, using \w or \W inside a [...] character class will still match with byte semantics.)

  • Named Unicode properties, scripts, and block ranges may be used like character classes via the \p{} "matches property" construct and the \P{} negation, "doesn't match property".

    For instance, \p{Lu} matches any character with the Unicode "Lu" (Letter, uppercase) property, while \p{M} matches any character with an "M" (mark--accents and such) property. Brackets are not required for single letter properties, so \p{M} is equivalent to \pM. Many predefined properties are available, such as \p{Mirrored} and \p{Tibetan}.

    The official Unicode script and block names have spaces and dashes as separators, but for convenience you can use dashes, spaces, or underbars, and case is unimportant. It is recommended, however, that for consistency you use the following naming: the official Unicode script, property, or block name (see below for the additional rules that apply to block names) with whitespace and dashes removed, and the words "uppercase-first-lowercase-rest". Latin-1 Supplement thus becomes Latin1Supplement.

    You can also use negation in both \p{} and \P{} by introducing a caret (^) between the first brace and the property name: \p{^Tamil} is equal to \P{Tamil}.

    NOTE: the properties, scripts, and blocks listed here are as of Unicode 3.2.0, March 2002, or Perl 5.8.0, July 2002. Unicode 4.0.0 came out in April 2003, and Perl 5.8.1 in September 2003.

    Here are the basic Unicode General Category properties, followed by their long form. You can use either; \p{Lu} and \p{UppercaseLetter}, for instance, are identical.

        Short       Long
        L           Letter
    LC          CasedLetter
    Lu          UppercaseLetter
    Ll          LowercaseLetter
    Lt          TitlecaseLetter
    Lm          ModifierLetter
    Lo          OtherLetter
        M           Mark
    Mn          NonspacingMark
    Mc          SpacingMark
    Me          EnclosingMark
        N           Number
    Nd          DecimalNumber
    Nl          LetterNumber
    No          OtherNumber
        P           Punctuation
    Pc          ConnectorPunctuation
    Pd          DashPunctuation
    Ps          OpenPunctuation
    Pe          ClosePunctuation
    Pi          InitialPunctuation
                (may behave like Ps or Pe depending on usage)
    Pf          FinalPunctuation
                (may behave like Ps or Pe depending on usage)
    Po          OtherPunctuation
        S           Symbol
    Sm          MathSymbol
    Sc          CurrencySymbol
    Sk          ModifierSymbol
    So          OtherSymbol
        Z           Separator
    Zs          SpaceSeparator
    Zl          LineSeparator
    Zp          ParagraphSeparator
        C           Other
    Cc          Control
    Cf          Format
    Cs          Surrogate   (not usable)
    Co          PrivateUse
    Cn          Unassigned

    Single-letter properties match all characters in any of the two-letter sub-properties starting with the same letter. LC and L& are special cases, which are aliases for the set of Ll, Lu, and Lt.

    Because Perl hides the need for the user to understand the internal representation of Unicode characters, there is no need to implement the somewhat messy concept of surrogates. Cs is therefore not supported.

    Because scripts differ in their directionality--Hebrew is written right to left, for example--Unicode supplies these properties in the BidiClass class:

        Property    Meaning
        L           Left-to-Right
    LRE         Left-to-Right Embedding
    LRO         Left-to-Right Override
    R           Right-to-Left
    AL          Right-to-Left Arabic
    RLE         Right-to-Left Embedding
    RLO         Right-to-Left Override
    PDF         Pop Directional Format
    EN          European Number
    ES          European Number Separator
    ET          European Number Terminator
    AN          Arabic Number
    CS          Common Number Separator
    NSM         Non-Spacing Mark
    BN          Boundary Neutral
    B           Paragraph Separator
    S           Segment Separator
    WS          Whitespace
    ON          Other Neutrals

    For example, \p{BidiClass:R} matches characters that are normally written right to left.

Scripts

The script names which can be used by \p{...} and \P{...}, such as in \p{Latin} or \p{Cyrillic}, are as follows:

    Arabic
    Armenian
    Bengali
    Bopomofo
    Buhid
    CanadianAboriginal
    Cherokee
    Cyrillic
    Deseret
    Devanagari
    Ethiopic
    Georgian
    Gothic
    Greek
    Gujarati
    Gurmukhi
    Han
    Hangul
    Hanunoo
    Hebrew
    Hiragana
    Inherited
    Kannada
    Katakana
    Khmer
    Lao
    Latin
    Malayalam
    Mongolian
    Myanmar
    Ogham
    OldItalic
    Oriya
    Runic
    Sinhala
    Syriac
    Tagalog
    Tagbanwa
    Tamil
    Telugu
    Thaana
    Thai
    Tibetan
    Yi

Extended property classes can supplement the basic properties, defined by the PropList Unicode database:

    ASCIIHexDigit
    BidiControl
    Dash
    Deprecated
    Diacritic
    Extender
    GraphemeLink
    HexDigit
    Hyphen
    Ideographic
    IDSBinaryOperator
    IDSTrinaryOperator
    JoinControl
    LogicalOrderException
    NoncharacterCodePoint
    OtherAlphabetic
    OtherDefaultIgnorableCodePoint
    OtherGraphemeExtend
    OtherLowercase
    OtherMath
    OtherUppercase
    QuotationMark
    Radical
    SoftDotted
    TerminalPunctuation
    UnifiedIdeograph
    WhiteSpace

and there are further derived properties:

    Alphabetic      Lu + Ll + Lt + Lm + Lo + OtherAlphabetic
    Lowercase       Ll + OtherLowercase
    Uppercase       Lu + OtherUppercase
    Math            Sm + OtherMath
    ID_Start        Lu + Ll + Lt + Lm + Lo + Nl
    ID_Continue     ID_Start + Mn + Mc + Nd + Pc
    Any             Any character
    Assigned        Any non-Cn character (i.e. synonym for \P{Cn})
    Unassigned      Synonym for \p{Cn}
    Common          Any character (or unassigned code point)
                    not explicitly assigned to a script

For backward compatibility (with Perl 5.6), all properties mentioned so far may have Is prepended to their name, so \P{IsLu}, for example, is equal to \P{Lu}.

Blocks

In addition to scripts, Unicode also defines blocks of characters. The difference between scripts and blocks is that the concept of scripts is closer to natural languages, while the concept of blocks is more of an artificial grouping based on groups of 256 Unicode characters. For example, the Latin script contains letters from many blocks but does not contain all the characters from those blocks. It does not, for example, contain digits, because digits are shared across many scripts. Digits and similar groups, like punctuation, are in a category called Common.

For more about scripts, see the UTR #24:

   http://www.unicode.org/unicode/reports/tr24/

For more about blocks, see:

   http://www.unicode.org/Public/UNIDATA/Blocks.txt

Block names are given with the In prefix. For example, the Katakana block is referenced via \p{InKatakana}. The In prefix may be omitted if there is no naming conflict with a script or any other property, but it is recommended that In always be used for block tests to avoid confusion.

These block names are supported:

    InAlphabeticPresentationForms
    InArabic
    InArabicPresentationFormsA
    InArabicPresentationFormsB
    InArmenian
    InArrows
    InBasicLatin
    InBengali
    InBlockElements
    InBopomofo
    InBopomofoExtended
    InBoxDrawing
    InBraillePatterns
    InBuhid
    InByzantineMusicalSymbols
    InCJKCompatibility
    InCJKCompatibilityForms
    InCJKCompatibilityIdeographs
    InCJKCompatibilityIdeographsSupplement
    InCJKRadicalsSupplement
    InCJKSymbolsAndPunctuation
    InCJKUnifiedIdeographs
    InCJKUnifiedIdeographsExtensionA
    InCJKUnifiedIdeographsExtensionB
    InCherokee
    InCombiningDiacriticalMarks
    InCombiningDiacriticalMarksforSymbols
    InCombiningHalfMarks
    InControlPictures
    InCurrencySymbols
    InCyrillic
    InCyrillicSupplementary
    InDeseret
    InDevanagari
    InDingbats
    InEnclosedAlphanumerics
    InEnclosedCJKLettersAndMonths
    InEthiopic
    InGeneralPunctuation
    InGeometricShapes
    InGeorgian
    InGothic
    InGreekExtended
    InGreekAndCoptic
    InGujarati
    InGurmukhi
    InHalfwidthAndFullwidthForms
    InHangulCompatibilityJamo
    InHangulJamo
    InHangulSyllables
    InHanunoo
    InHebrew
    InHighPrivateUseSurrogates
    InHighSurrogates
    InHiragana
    InIPAExtensions
    InIdeographicDescriptionCharacters
    InKanbun
    InKangxiRadicals
    InKannada
    InKatakana
    InKatakanaPhoneticExtensions
    InKhmer
    InLao
    InLatin1Supplement
    InLatinExtendedA
    InLatinExtendedAdditional
    InLatinExtendedB
    InLetterlikeSymbols
    InLowSurrogates
    InMalayalam
    InMathematicalAlphanumericSymbols
    InMathematicalOperators
    InMiscellaneousMathematicalSymbolsA
    InMiscellaneousMathematicalSymbolsB
    InMiscellaneousSymbols
    InMiscellaneousTechnical
    InMongolian
    InMusicalSymbols
    InMyanmar
    InNumberForms
    InOgham
    InOldItalic
    InOpticalCharacterRecognition
    InOriya
    InPrivateUseArea
    InRunic
    InSinhala
    InSmallFormVariants
    InSpacingModifierLetters
    InSpecials
    InSuperscriptsAndSubscripts
    InSupplementalArrowsA
    InSupplementalArrowsB
    InSupplementalMathematicalOperators
    InSupplementaryPrivateUseAreaA
    InSupplementaryPrivateUseAreaB
    InSyriac
    InTagalog
    InTagbanwa
    InTags
    InTamil
    InTelugu
    InThaana
    InThai
    InTibetan
    InUnifiedCanadianAboriginalSyllabics
    InVariationSelectors
    InYiRadicals
    InYiSyllables

  • The special pattern \X matches any extended Unicode sequence--"a combining character sequence" in Standardese--where the first character is a base character and subsequent characters are mark characters that apply to the base character. \X is equivalent to (?:\PM\pM*).

  • The tr/// operator translates characters instead of bytes. Note that the tr///CU functionality has been removed. For similar functionality see pack('U0', ...) and pack('C0', ...).

  • Case translation operators use the Unicode case translation tables when character input is provided. Note that uc(), or \U in interpolated strings, translates to uppercase, while ucfirst, or \u in interpolated strings, translates to titlecase in languages that make the distinction.

  • Most operators that deal with positions or lengths in a string will automatically switch to using character positions, including chop(), chomp(), substr(), pos(), index(), rindex(), sprintf(), write(), and length(). Operators that specifically do not switch include vec(), pack(), and unpack(). Operators that really don't care include operators that treats strings as a bucket of bits such as sort(), and operators dealing with filenames.

  • The pack()/unpack() letters c and C do not change, since they are often used for byte-oriented formats. Again, think char in the C language.

    There is a new U specifier that converts between Unicode characters and code points.

  • The chr() and ord() functions work on characters, similar to pack("U") and unpack("U"), not pack("C") and unpack("C"). pack("C") and unpack("C") are methods for emulating byte-oriented chr() and ord() on Unicode strings. While these methods reveal the internal encoding of Unicode strings, that is not something one normally needs to care about at all.

  • The bit string operators, & | ^ ~, can operate on character data. However, for backward compatibility, such as when using bit string operations when characters are all less than 256 in ordinal value, one should not use ~ (the bit complement) with characters of both values less than 256 and values greater than 256. Most importantly, DeMorgan's laws (~($x|$y) eq ~$x&~$y and ~($x&$y) eq ~$x|~$y) will not hold. The reason for this mathematical faux pas is that the complement cannot return both the 8-bit (byte-wide) bit complement and the full character-wide bit complement.

  • lc(), uc(), lcfirst(), and ucfirst() work for the following cases:

    • the case mapping is from a single Unicode character to another single Unicode character, or

    • the case mapping is from a single Unicode character to more than one Unicode character.

    Things to do with locales (Lithuanian, Turkish, Azeri) do not work since Perl does not understand the concept of Unicode locales.

    See the Unicode Technical Report #21, Case Mappings, for more details.

  • And finally, scalar reverse() reverses by character rather than by byte.

User-Defined Character Properties

You can define your own character properties by defining subroutines whose names begin with "In" or "Is". The subroutines can be defined in any package. The user-defined properties can be used in the regular expression \p and \P constructs; if you are using a user-defined property from a package other than the one you are in, you must specify its package in the \p or \P construct.

    # assuming property IsForeign defined in Lang::
    package main;  # property package name required
    if ($txt =~ /\p{Lang::IsForeign}+/) { ... }

    package Lang;  # property package name not required
    if ($txt =~ /\p{IsForeign}+/) { ... }

Note that the effect is compile-time and immutable once defined.

The subroutines must return a specially-formatted string, with one or more newline-separated lines. Each line must be one of the following:

  • Two hexadecimal numbers separated by horizontal whitespace (space or tabular characters) denoting a range of Unicode code points to include.

  • Something to include, prefixed by "+": a built-in character property (prefixed by "utf8::") or a user-defined character property, to represent all the characters in that property; two hexadecimal code points for a range; or a single hexadecimal code point.

  • Something to exclude, prefixed by "-": an existing character property (prefixed by "utf8::") or a user-defined character property, to represent all the characters in that property; two hexadecimal code points for a range; or a single hexadecimal code point.

  • Something to negate, prefixed "!": an existing character property (prefixed by "utf8::") or a user-defined character property, to represent all the characters in that property; two hexadecimal code points for a range; or a single hexadecimal code point.

  • Something to intersect with, prefixed by "&": an existing character property (prefixed by "utf8::") or a user-defined character property, for all the characters except the characters in the property; two hexadecimal code points for a range; or a single hexadecimal code point.

For example, to define a property that covers both the Japanese syllabaries (hiragana and katakana), you can define

    sub InKana {
        return <<END;
    3040\t309F
    30A0\t30FF
    END
    }

Imagine that the here-doc end marker is at the beginning of the line. Now you can use \p{InKana} and \P{InKana}.

You could also have used the existing block property names:

    sub InKana {
        return <<'END';
    +utf8::InHiragana
    +utf8::InKatakana
    END
    }

Suppose you wanted to match only the allocated characters, not the raw block ranges: in other words, you want to remove the non-characters:

    sub InKana {
        return <<'END';
    +utf8::InHiragana
    +utf8::InKatakana
    -utf8::IsCn
    END
    }

The negation is useful for defining (surprise!) negated classes.

    sub InNotKana {
        return <<'END';
    !utf8::InHiragana
    -utf8::InKatakana
    +utf8::IsCn
    END
    }

Intersection is useful for getting the common characters matched by two (or more) classes.

    sub InFooAndBar {
        return <<'END';
    +main::Foo
    &main::Bar
    END
    }

It's important to remember not to use "&" for the first set -- that would be intersecting with nothing (resulting in an empty set).

You can also define your own mappings to be used in the lc(), lcfirst(), uc(), and ucfirst() (or their string-inlined versions). The principle is the same: define subroutines in the main package with names like ToLower (for lc() and lcfirst()), ToTitle (for the first character in ucfirst()), and ToUpper (for uc(), and the rest of the characters in ucfirst()).

The string returned by the subroutines needs now to be three hexadecimal numbers separated by tabulators: start of the source range, end of the source range, and start of the destination range. For example:

    sub ToUpper {
        return <<END;
    0061\t0063\t0041
    END
    }

defines an uc() mapping that causes only the characters "a", "b", and "c" to be mapped to "A", "B", "C", all other characters will remain unchanged.

If there is no source range to speak of, that is, the mapping is from a single character to another single character, leave the end of the source range empty, but the two tabulator characters are still needed. For example:

    sub ToLower {
        return <<END;
    0041\t\t0061
    END
    }

defines a lc() mapping that causes only "A" to be mapped to "a", all other characters will remain unchanged.

(For serious hackers only) If you want to introspect the default mappings, you can find the data in the directory $Config{privlib}/unicore/To/. The mapping data is returned as the here-document, and the utf8::ToSpecFoo are special exception mappings derived from <$Config{privlib}>/unicore/SpecialCasing.txt. The Digit and Fold mappings that one can see in the directory are not directly user-accessible, one can use either the Unicode::UCD module, or just match case-insensitively (that's when the Fold mapping is used).

A final note on the user-defined property tests and mappings: they will be used only if the scalar has been marked as having Unicode characters. Old byte-style strings will not be affected.

Character Encodings for Input and Output

See the Encode manpage.

Unicode Regular Expression Support Level

The following list of Unicode support for regular expressions describes all the features currently supported. The references to "Level N" and the section numbers refer to the Unicode Technical Report 18, "Unicode Regular Expression Guidelines", version 6 (Unicode 3.2.0, Perl 5.8.0).

  • Level 1 - Basic Unicode Support

            2.1 Hex Notation                        - done          [1]
            Named Notation                      - done          [2]
        2.2 Categories                          - done          [3][4]
        2.3 Subtraction                         - MISSING       [5][6]
        2.4 Simple Word Boundaries              - done          [7]
        2.5 Simple Loose Matches                - done          [8]
        2.6 End of Line                         - MISSING       [9][10]
            [ 1] \x{...}
        [ 2] \N{...}
        [ 3] . \p{...} \P{...}
        [ 4] support for scripts (see UTR#24 Script Names), blocks,
             binary properties, enumerated non-binary properties, and
             numeric properties (as listed in UTR#18 Other Properties)
        [ 5] have negation
        [ 6] can use regular expression look-ahead [a]
             or user-defined character properties [b] to emulate subtraction
        [ 7] include Letters in word characters
        [ 8] note that Perl does Full case-folding in matching, not Simple:
             for example U+1F88 is equivalent with U+1F00 U+03B9,
             not with 1F80.  This difference matters for certain Greek
             capital letters with certain modifiers: the Full case-folding
             decomposes the letter, while the Simple case-folding would map
             it to a single character.
        [ 9] see UTR #13 Unicode Newline Guidelines
        [10] should do ^ and $ also on \x{85}, \x{2028} and \x{2029}
             (should also affect <>, $., and script line numbers)
             (the \x{85}, \x{2028} and \x{2029} do match \s)

    [a] You can mimic class subtraction using lookahead. For example, what UTR #18 might write as

        [{Greek}-[{UNASSIGNED}]]

    in Perl can be written as:

        (?!\p{Unassigned})\p{InGreekAndCoptic}
    (?=\p{Assigned})\p{InGreekAndCoptic}

    But in this particular example, you probably really want

        \p{GreekAndCoptic}

    which will match assigned characters known to be part of the Greek script.

    Also see the Unicode::Regex::Set module, it does implement the full UTR #18 grouping, intersection, union, and removal (subtraction) syntax.

    [b] See User-Defined Character Properties.

  • Level 2 - Extended Unicode Support

            3.1 Surrogates                          - MISSING       [11]
        3.2 Canonical Equivalents               - MISSING       [12][13]
        3.3 Locale-Independent Graphemes        - MISSING       [14]
        3.4 Locale-Independent Words            - MISSING       [15]
        3.5 Locale-Independent Loose Matches    - MISSING       [16]
            [11] Surrogates are solely a UTF-16 concept and Perl's internal
             representation is UTF-8.  The Encode module does UTF-16, though.
        [12] see UTR#15 Unicode Normalization
        [13] have Unicode::Normalize but not integrated to regexes
        [14] have \X but at this level . should equal that
        [15] need three classes, not just \w and \W
        [16] see UTR#21 Case Mappings

  • Level 3 - Locale-Sensitive Support

            4.1 Locale-Dependent Categories         - MISSING
        4.2 Locale-Dependent Graphemes          - MISSING       [16][17]
        4.3 Locale-Dependent Words              - MISSING
        4.4 Locale-Dependent Loose Matches      - MISSING
        4.5 Locale-Dependent Ranges             - MISSING
            [16] see UTR#10 Unicode Collation Algorithms
        [17] have Unicode::Collate but not integrated to regexes

Unicode Encodings

Unicode characters are assigned to code points, which are abstract numbers. To use these numbers, various encodings are needed.

  • UTF-8

    UTF-8 is a variable-length (1 to 6 bytes, current character allocations require 4 bytes), byte-order independent encoding. For ASCII (and we really do mean 7-bit ASCII, not another 8-bit encoding), UTF-8 is transparent.

    The following table is from Unicode 3.2.

     Code Points            1st Byte  2nd Byte  3rd Byte  4th Byte
       U+0000..U+007F       00..7F
   U+0080..U+07FF       C2..DF    80..BF
   U+0800..U+0FFF       E0        A0..BF    80..BF
   U+1000..U+CFFF       E1..EC    80..BF    80..BF
   U+D000..U+D7FF       ED        80..9F    80..BF
   U+D800..U+DFFF       ******* ill-formed *******
   U+E000..U+FFFF       EE..EF    80..BF    80..BF
  U+10000..U+3FFFF      F0        90..BF    80..BF    80..BF
  U+40000..U+FFFFF      F1..F3    80..BF    80..BF    80..BF
 U+100000..U+10FFFF     F4        80..8F    80..BF    80..BF

    Note the A0..BF in U+0800..U+0FFF, the 80..9F in U+D000...U+D7FF, the 90..BF in U+10000..U+3FFFF, and the 80...8F in U+100000..U+10FFFF. The "gaps" are caused by legal UTF-8 avoiding non-shortest encodings: it is technically possible to UTF-8-encode a single code point in different ways, but that is explicitly forbidden, and the shortest possible encoding should always be used. So that's what Perl does.

    Another way to look at it is via bits:

     Code Points                    1st Byte   2nd Byte  3rd Byte  4th Byte
                        0aaaaaaa     0aaaaaaa
            00000bbbbbaaaaaa     110bbbbb  10aaaaaa
            ccccbbbbbbaaaaaa     1110cccc  10bbbbbb  10aaaaaa
  00000dddccccccbbbbbbaaaaaa     11110ddd  10cccccc  10bbbbbb  10aaaaaa

    As you can see, the continuation bytes all begin with 10, and the leading bits of the start byte tell how many bytes the are in the encoded character.

  • UTF-EBCDIC

    Like UTF-8 but EBCDIC-safe, in the way that UTF-8 is ASCII-safe.

  • UTF-16, UTF-16BE, UTF-16LE, Surrogates, and BOMs (Byte Order Marks)

    The followings items are mostly for reference and general Unicode knowledge, Perl doesn't use these constructs internally.

    UTF-16 is a 2 or 4 byte encoding. The Unicode code points U+0000..U+FFFF are stored in a single 16-bit unit, and the code points U+10000..U+10FFFF in two 16-bit units. The latter case is using surrogates, the first 16-bit unit being the high surrogate, and the second being the low surrogate.

    Surrogates are code points set aside to encode the U+10000..U+10FFFF range of Unicode code points in pairs of 16-bit units. The high surrogates are the range U+D800..U+DBFF, and the low surrogates are the range U+DC00..U+DFFF. The surrogate encoding is

            $hi = ($uni - 0x10000) / 0x400 + 0xD800;
        $lo = ($uni - 0x10000) % 0x400 + 0xDC00;

    and the decoding is

            $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00);

    If you try to generate surrogates (for example by using chr()), you will get a warning if warnings are turned on, because those code points are not valid for a Unicode character.

    Because of the 16-bitness, UTF-16 is byte-order dependent. UTF-16 itself can be used for in-memory computations, but if storage or transfer is required either UTF-16BE (big-endian) or UTF-16LE (little-endian) encodings must be chosen.

    This introduces another problem: what if you just know that your data is UTF-16, but you don't know which endianness? Byte Order Marks, or BOMs, are a solution to this. A special character has been reserved in Unicode to function as a byte order marker: the character with the code point U+FEFF is the BOM.

    The trick is that if you read a BOM, you will know the byte order, since if it was written on a big-endian platform, you will read the bytes 0xFE 0xFF, but if it was written on a little-endian platform, you will read the bytes 0xFF 0xFE. (And if the originating platform was writing in UTF-8, you will read the bytes 0xEF 0xBB 0xBF.)

    The way this trick works is that the character with the code point U+FFFE is guaranteed not to be a valid Unicode character, so the sequence of bytes 0xFF 0xFE is unambiguously "BOM, represented in little-endian format" and cannot be U+FFFE, represented in big-endian format".

  • UTF-32, UTF-32BE, UTF-32LE

    The UTF-32 family is pretty much like the UTF-16 family, expect that the units are 32-bit, and therefore the surrogate scheme is not needed. The BOM signatures will be 0x00 0x00 0xFE 0xFF for BE and 0xFF 0xFE 0x00 0x00 for LE.

  • UCS-2, UCS-4

    Encodings defined by the ISO 10646 standard. UCS-2 is a 16-bit encoding. Unlike UTF-16, UCS-2 is not extensible beyond U+FFFF, because it does not use surrogates. UCS-4 is a 32-bit encoding, functionally identical to UTF-32.

  • UTF-7

    A seven-bit safe (non-eight-bit) encoding, which is useful if the transport or storage is not eight-bit safe. Defined by RFC 2152.

Security Implications of Unicode

  • Malformed UTF-8

    Unfortunately, the specification of UTF-8 leaves some room for interpretation of how many bytes of encoded output one should generate from one input Unicode character. Strictly speaking, the shortest possible sequence of UTF-8 bytes should be generated, because otherwise there is potential for an input buffer overflow at the receiving end of a UTF-8 connection. Perl always generates the shortest length UTF-8, and with warnings on Perl will warn about non-shortest length UTF-8 along with other malformations, such as the surrogates, which are not real Unicode code points.

  • Regular expressions behave slightly differently between byte data and character (Unicode) data. For example, the "word character" character class \w will work differently depending on if data is eight-bit bytes or Unicode.

    In the first case, the set of \w characters is either small--the default set of alphabetic characters, digits, and the "_"--or, if you are using a locale (see the perllocale manpage), the \w might contain a few more letters according to your language and country.

    In the second case, the \w set of characters is much, much larger. Most importantly, even in the set of the first 256 characters, it will probably match different characters: unlike most locales, which are specific to a language and country pair, Unicode classifies all the characters that are letters somewhere as \w. For example, your locale might not think that LATIN SMALL LETTER ETH is a letter (unless you happen to speak Icelandic), but Unicode does.

    As discussed elsewhere, Perl has one foot (two hooves?) planted in each of two worlds: the old world of bytes and the new world of characters, upgrading from bytes to characters when necessary. If your legacy code does not explicitly use Unicode, no automatic switch-over to characters should happen. Characters shouldn't get downgraded to bytes, either. It is possible to accidentally mix bytes and characters, however (see the perluniintro manpage), in which case \w in regular expressions might start behaving differently. Review your code. Use warnings and the strict pragma.

Unicode in Perl on EBCDIC

The way Unicode is handled on EBCDIC platforms is still experimental. On such platforms, references to UTF-8 encoding in this document and elsewhere should be read as meaning the UTF-EBCDIC specified in Unicode Technical Report 16, unless ASCII vs. EBCDIC issues are specifically discussed. There is no utfebcdic pragma or ":utfebcdic" layer; rather, "utf8" and ":utf8" are reused to mean the platform's "natural" 8-bit encoding of Unicode. See the perlebcdic manpage for more discussion of the issues.

Locales

Usually locale settings and Unicode do not affect each other, but there are a couple of exceptions:

  • You can enable automatic UTF-8-ification of your standard file handles, default open() layer, and @ARGV by using either the -C command line switch or the PERL_UNICODE environment variable, see the perlrun manpage for the documentation of the -C switch.

  • Perl tries really hard to work both with Unicode and the old byte-oriented world. Most often this is nice, but sometimes Perl's straddling of the proverbial fence causes problems.

When Unicode Does Not Happen

While Perl does have extensive ways to input and output in Unicode, and few other 'entry points' like the @ARGV which can be interpreted as Unicode (UTF-8), there still are many places where Unicode (in some encoding or another) could be given as arguments or received as results, or both, but it is not.

The following are such interfaces. For all of these interfaces Perl currently (as of 5.8.3) simply assumes byte strings both as arguments and results, or UTF-8 strings if the encoding pragma has been used.

One reason why Perl does not attempt to resolve the role of Unicode in this cases is that the answers are highly dependent on the operating system and the file system(s). For example, whether filenames can be in Unicode, and in exactly what kind of encoding, is not exactly a portable concept. Similarly for the qx and system: how well will the 'command line interface' (and which of them?) handle Unicode?

  • chdir, chmod, chown, chroot, exec, link, lstat, mkdir, rename, rmdir, stat, symlink, truncate, unlink, utime, -X

  • %ENV

  • glob (aka the <*>)

  • open, opendir, sysopen

  • qx (aka the backtick operator), system

  • readdir, readlink

Forcing Unicode in Perl (Or Unforcing Unicode in Perl)

Sometimes (see When Unicode Does Not Happen) there are situations where you simply need to force Perl to believe that a byte string is UTF-8, or vice versa. The low-level calls utf8::upgrade($bytestring) and utf8::downgrade($utf8string) are the answers.

Do not use them without careful thought, though: Perl may easily get very confused, angry, or even crash, if you suddenly change the 'nature' of scalar like that. Especially careful you have to be if you use the utf8::upgrade(): any random byte string is not valid UTF-8.

Using Unicode in XS

If you want to handle Perl Unicode in XS extensions, you may find the following C APIs useful. See also Unicode Support in the perlguts manpage for an explanation about Unicode at the XS level, and the perlapi manpage for the API details.

  • DO_UTF8(sv) returns true if the UTF8 flag is on and the bytes pragma is not in effect. SvUTF8(sv) returns true is the UTF8 flag is on; the bytes pragma is ignored. The UTF8 flag being on does not mean that there are any characters of code points greater than 255 (or 127) in the scalar or that there are even any characters in the scalar. What the UTF8 flag means is that the sequence of octets in the representation of the scalar is the sequence of UTF-8 encoded code points of the characters of a string. The UTF8 flag being off means that each octet in this representation encodes a single character with code point 0..255 within the string. Perl's Unicode model is not to use UTF-8 until it is absolutely necessary.

  • uvuni_to_utf8(buf, chr) writes a Unicode character code point into a buffer encoding the code point as UTF-8, and returns a pointer pointing after the UTF-8 bytes.

  • utf8_to_uvuni(buf, lenp) reads UTF-8 encoded bytes from a buffer and returns the Unicode character code point and, optionally, the length of the UTF-8 byte sequence.

  • utf8_length(start, end) returns the length of the UTF-8 encoded buffer in characters. sv_len_utf8(sv) returns the length of the UTF-8 encoded scalar.

  • sv_utf8_upgrade(sv) converts the string of the scalar to its UTF-8 encoded form. sv_utf8_downgrade(sv) does the opposite, if possible. sv_utf8_encode(sv) is like sv_utf8_upgrade except that it does not set the UTF8 flag. sv_utf8_decode() does the opposite of sv_utf8_encode(). Note that none of these are to be used as general-purpose encoding or decoding interfaces: use Encode for that. sv_utf8_upgrade() is affected by the encoding pragma but sv_utf8_downgrade() is not (since the encoding pragma is designed to be a one-way street).

  • is_utf8_char(s) returns true if the pointer points to a valid UTF-8 character.

  • is_utf8_string(buf, len) returns true if len bytes of the buffer are valid UTF-8.

  • UTF8SKIP(buf) will return the number of bytes in the UTF-8 encoded character in the buffer. UNISKIP(chr) will return the number of bytes required to UTF-8-encode the Unicode character code point. UTF8SKIP() is useful for example for iterating over the characters of a UTF-8 encoded buffer; UNISKIP() is useful, for example, in computing the size required for a UTF-8 encoded buffer.

  • utf8_distance(a, b) will tell the distance in characters between the two pointers pointing to the same UTF-8 encoded buffer.

  • utf8_hop(s, off) will return a pointer to an UTF-8 encoded buffer that is off (positive or negative) Unicode characters displaced from the UTF-8 buffer s. Be careful not to overstep the buffer: utf8_hop() will merrily run off the end or the beginning of the buffer if told to do so.

  • pv_uni_display(dsv, spv, len, pvlim, flags) and sv_uni_display(dsv, ssv, pvlim, flags) are useful for debugging the output of Unicode strings and scalars. By default they are useful only for debugging--they display all characters as hexadecimal code points--but with the flags UNI_DISPLAY_ISPRINT, UNI_DISPLAY_BACKSLASH, and UNI_DISPLAY_QQ you can make the output more readable.

  • ibcmp_utf8(s1, pe1, u1, l1, u1, s2, pe2, l2, u2) can be used to compare two strings case-insensitively in Unicode. For case-sensitive comparisons you can just use memEQ() and memNE() as usual.

For more information, see the perlapi manpage, and utf8.c and utf8.h in the Perl source code distribution.

BUGS

Interaction with Locales

Use of locales with Unicode data may lead to odd results. Currently, Perl attempts to attach 8-bit locale info to characters in the range 0..255, but this technique is demonstrably incorrect for locales that use characters above that range when mapped into Unicode. Perl's Unicode support will also tend to run slower. Use of locales with Unicode is discouraged.

Interaction with Extensions

When Perl exchanges data with an extension, the extension should be able to understand the UTF-8 flag and act accordingly. If the extension doesn't know about the flag, it's likely that the extension will return incorrectly-flagged data.

So if you're working with Unicode data, consult the documentation of every module you're using if there are any issues with Unicode data exchange. If the documentation does not talk about Unicode at all, suspect the worst and probably look at the source to learn how the module is implemented. Modules written completely in Perl shouldn't cause problems. Modules that directly or indirectly access code written in other programming languages are at risk.

For affected functions, the simple strategy to avoid data corruption is to always make the encoding of the exchanged data explicit. Choose an encoding that you know the extension can handle. Convert arguments passed to the extensions to that encoding and convert results back from that encoding. Write wrapper functions that do the conversions for you, so you can later change the functions when the extension catches up.

To provide an example, let's say the popular Foo::Bar::escape_html function doesn't deal with Unicode data yet. The wrapper function would convert the argument to raw UTF-8 and convert the result back to Perl's internal representation like so:

    sub my_escape_html ($) {
      my($what) = shift;
      return unless defined $what;
      Encode::decode_utf8(Foo::Bar::escape_html(Encode::encode_utf8($what)));
    }

Sometimes, when the extension does not convert data but just stores and retrieves them, you will be in a position to use the otherwise dangerous Encode::_utf8_on() function. Let's say the popular Foo::Bar extension, written in C, provides a param method that lets you store and retrieve data according to these prototypes:

    $self->param($name, $value);            # set a scalar
    $value = $self->param($name);           # retrieve a scalar

If it does not yet provide support for any encoding, one could write a derived class with such a param method:

    sub param {
      my($self,$name,$value) = @_;
      utf8::upgrade($name);     # make sure it is UTF-8 encoded
      if (defined $value)
        utf8::upgrade($value);  # make sure it is UTF-8 encoded
        return $self->SUPER::param($name,$value);
      } else {
        my $ret = $self->SUPER::param($name);
        Encode::_utf8_on($ret); # we know, it is UTF-8 encoded
        return $ret;
      }
    }

Some extensions provide filters on data entry/exit points, such as DB_File::filter_store_key and family. Look out for such filters in the documentation of your extensions, they can make the transition to Unicode data much easier.

Speed

Some functions are slower when working on UTF-8 encoded strings than on byte encoded strings. All functions that need to hop over characters such as length(), substr() or index(), or matching regular expressions can work much faster when the underlying data are byte-encoded.

In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1 a caching scheme was introduced which will hopefully make the slowness somewhat less spectacular, at least for some operations. In general, operations with UTF-8 encoded strings are still slower. As an example, the Unicode properties (character classes) like \p{Nd} are known to be quite a bit slower (5-20 times) than their simpler counterparts like \d (then again, there 268 Unicode characters matching Nd compared with the 10 ASCII characters matching d).

Porting code from perl-5.6.X

Perl 5.8 has a different Unicode model from 5.6. In 5.6 the programmer was required to use the utf8 pragma to declare that a given scope expected to deal with Unicode data and had to make sure that only Unicode data were reaching that scope. If you have code that is working with 5.6, you will need some of the following adjustments to your code. The examples are written such that the code will continue to work under 5.6, so you should be safe to try them out.

  • A filehandle that should read or write UTF-8

      if ($] > 5.007) {
    binmode $fh, ":utf8";
  }

  • A scalar that is going to be passed to some extension

    Be it Compress::Zlib, Apache::Request or any extension that has no mention of Unicode in the manpage, you need to make sure that the UTF-8 flag is stripped off. Note that at the time of this writing (October 2002) the mentioned modules are not UTF-8-aware. Please check the documentation to verify if this is still true.

      if ($] > 5.007) {
    require Encode;
    $val = Encode::encode_utf8($val); # make octets
  }

  • A scalar we got back from an extension

    If you believe the scalar comes back as UTF-8, you will most likely want the UTF-8 flag restored:

      if ($] > 5.007) {
    require Encode;
    $val = Encode::decode_utf8($val);
  }

  • Same thing, if you are really sure it is UTF-8

      if ($] > 5.007) {
    require Encode;
    Encode::_utf8_on($val);
  }

  • A wrapper for fetchrow_array and fetchrow_hashref

    When the database contains only UTF-8, a wrapper function or method is a convenient way to replace all your fetchrow_array and fetchrow_hashref calls. A wrapper function will also make it easier to adapt to future enhancements in your database driver. Note that at the time of this writing (October 2002), the DBI has no standardized way to deal with UTF-8 data. Please check the documentation to verify if that is still true.

      sub fetchrow {
    my($self, $sth, $what) = @_; # $what is one of fetchrow_{array,hashref}
    if ($] < 5.007) {
      return $sth->$what;
    } else {
      require Encode;
      if (wantarray) {
        my @arr = $sth->$what;
        for (@arr) {
          defined && /[^\000-\177]/ && Encode::_utf8_on($_);
        }
        return @arr;
      } else {
        my $ret = $sth->$what;
        if (ref $ret) {
          for my $k (keys %$ret) {
            defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret->{$k};
          }
          return $ret;
        } else {
          defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret;
          return $ret;
        }
      }
    }
  }

  • A large scalar that you know can only contain ASCII

    Scalars that contain only ASCII and are marked as UTF-8 are sometimes a drag to your program. If you recognize such a situation, just remove the UTF-8 flag:

      utf8::downgrade($val) if $] > 5.007;

SEE ALSO

the perluniintro manpage, the encoding manpage, the Encode manpage, the open manpage, the utf8 manpage, the bytes manpage, the perlretut manpage, ${^UNICODE} in the perlvar manpage


perluniintro - Perl Unicode introduction

    • Unicode
    • Perl's Unicode Support
    • Perl's Unicode Model
    • Unicode and EBCDIC
    • Creating Unicode
    • Handling Unicode
    • Legacy Encodings
    • Unicode I/O
    • Displaying Unicode As Text
    • Special Cases
    • Advanced Topics
    • Miscellaneous
    • Questions With Answers
    • Hexadecimal Notation
    • Further Resources
  • UNICODE IN OLDER PERLS
  • SEE ALSO
  • ACKNOWLEDGMENTS
  • AUTHOR, COPYRIGHT, AND LICENSE

NAME

perluniintro - Perl Unicode introduction

DESCRIPTION

This document gives a general idea of Unicode and how to use Unicode in Perl.

Unicode

Unicode is a character set standard which plans to codify all of the writing systems of the world, plus many other symbols.

Unicode and ISO/IEC 10646 are coordinated standards that provide code points for characters in almost all modern character set standards, covering more than 30 writing systems and hundreds of languages, including all commercially-important modern languages. All characters in the largest Chinese, Japanese, and Korean dictionaries are also encoded. The standards will eventually cover almost all characters in more than 250 writing systems and thousands of languages. Unicode 1.0 was released in October 1991, and 4.0 in April 2003.

A Unicode character is an abstract entity. It is not bound to any particular integer width, especially not to the C language char. Unicode is language-neutral and display-neutral: it does not encode the language of the text and it does not define fonts or other graphical layout details. Unicode operates on characters and on text built from those characters.

Unicode defines characters like LATIN CAPITAL LETTER A or GREEK SMALL LETTER ALPHA and unique numbers for the characters, in this case 0x0041 and 0x03B1, respectively. These unique numbers are called code points.

The Unicode standard prefers using hexadecimal notation for the code points. If numbers like 0x0041 are unfamiliar to you, take a peek at a later section, Hexadecimal Notation. The Unicode standard uses the notation U+0041 LATIN CAPITAL LETTER A, to give the hexadecimal code point and the normative name of the character.

Unicode also defines various properties for the characters, like "uppercase" or "lowercase", "decimal digit", or "punctuation"; these properties are independent of the names of the characters. Furthermore, various operations on the characters like uppercasing, lowercasing, and collating (sorting) are defined.

A Unicode character consists either of a single code point, or a base character (like LATIN CAPITAL LETTER A), followed by one or more modifiers (like COMBINING ACUTE ACCENT). This sequence of base character and modifiers is called a combining character sequence.

Whether to call these combining character sequences "characters" depends on your point of view. If you are a programmer, you probably would tend towards seeing each element in the sequences as one unit, or "character". The whole sequence could be seen as one "character", however, from the user's point of view, since that's probably what it looks like in the context of the user's language.

With this "whole sequence" view of characters, the total number of characters is open-ended. But in the programmer's "one unit is one character" point of view, the concept of "characters" is more deterministic. In this document, we take that second point of view: one "character" is one Unicode code point, be it a base character or a combining character.

For some combinations, there are precomposed characters. LATIN CAPITAL LETTER A WITH ACUTE, for example, is defined as a single code point. These precomposed characters are, however, only available for some combinations, and are mainly meant to support round-trip conversions between Unicode and legacy standards (like the ISO 8859). In the general case, the composing method is more extensible. To support conversion between different compositions of the characters, various normalization forms to standardize representations are also defined.

Because of backward compatibility with legacy encodings, the "a unique number for every character" idea breaks down a bit: instead, there is "at least one number for every character". The same character could be represented differently in several legacy encodings. The converse is also not true: some code points do not have an assigned character. Firstly, there are unallocated code points within otherwise used blocks. Secondly, there are special Unicode control characters that do not represent true characters.

A common myth about Unicode is that it would be "16-bit", that is, Unicode is only represented as 0x10000 (or 65536) characters from 0x0000 to 0xFFFF. This is untrue. Since Unicode 2.0 (July 1996), Unicode has been defined all the way up to 21 bits (0x10FFFF), and since Unicode 3.1 (March 2001), characters have been defined beyond 0xFFFF. The first 0x10000 characters are called the Plane 0, or the Basic Multilingual Plane (BMP). With Unicode 3.1, 17 (yes, seventeen) planes in all were defined--but they are nowhere near full of defined characters, yet.

Another myth is that the 256-character blocks have something to do with languages--that each block would define the characters used by a language or a set of languages. This is also untrue. The division into blocks exists, but it is almost completely accidental--an artifact of how the characters have been and still are allocated. Instead, there is a concept called scripts, which is more useful: there is Latin script, Greek script, and so on. Scripts usually span varied parts of several blocks. For further information see the Unicode::UCD manpage.

The Unicode code points are just abstract numbers. To input and output these abstract numbers, the numbers must be encoded or serialised somehow. Unicode defines several character encoding forms, of which UTF-8 is perhaps the most popular. UTF-8 is a variable length encoding that encodes Unicode characters as 1 to 6 bytes (only 4 with the currently defined characters). Other encodings include UTF-16 and UTF-32 and their big- and little-endian variants (UTF-8 is byte-order independent) The ISO/IEC 10646 defines the UCS-2 and UCS-4 encoding forms.

For more information about encodings--for instance, to learn what surrogates and byte order marks (BOMs) are--see the perlunicode manpage.

Perl's Unicode Support

Starting from Perl 5.6.0, Perl has had the capacity to handle Unicode natively. Perl 5.8.0, however, is the first recommended release for serious Unicode work. The maintenance release 5.6.1 fixed many of the problems of the initial Unicode implementation, but for example regular expressions still do not work with Unicode in 5.6.1.

Starting from Perl 5.8.0, the use of use utf8 is no longer necessary. In earlier releases the utf8 pragma was used to declare that operations in the current block or file would be Unicode-aware. This model was found to be wrong, or at least clumsy: the "Unicodeness" is now carried with the data, instead of being attached to the operations. Only one case remains where an explicit use utf8 is needed: if your Perl script itself is encoded in UTF-8, you can use UTF-8 in your identifier names, and in string and regular expression literals, by saying use utf8. This is not the default because scripts with legacy 8-bit data in them would break. See the utf8 manpage.

Perl's Unicode Model

Perl supports both pre-5.6 strings of eight-bit native bytes, and strings of Unicode characters. The principle is that Perl tries to keep its data as eight-bit bytes for as long as possible, but as soon as Unicodeness cannot be avoided, the data is transparently upgraded to Unicode.

Internally, Perl currently uses either whatever the native eight-bit character set of the platform (for example Latin-1) is, defaulting to UTF-8, to encode Unicode strings. Specifically, if all code points in the string are 0xFF or less, Perl uses the native eight-bit character set. Otherwise, it uses UTF-8.

A user of Perl does not normally need to know nor care how Perl happens to encode its internal strings, but it becomes relevant when outputting Unicode strings to a stream without a PerlIO layer -- one with the "default" encoding. In such a case, the raw bytes used internally (the native character set or UTF-8, as appropriate for each string) will be used, and a "Wide character" warning will be issued if those strings contain a character beyond 0x00FF.

For example,

      perl -e 'print "\x{DF}\n", "\x{0100}\x{DF}\n"'

produces a fairly useless mixture of native bytes and UTF-8, as well as a warning:

     Wide character in print at ...

To output UTF-8, use the :utf8 output layer. Prepending

      binmode(STDOUT, ":utf8");

to this sample program ensures that the output is completely UTF-8, and removes the program's warning.

You can enable automatic UTF-8-ification of your standard file handles, default open() layer, and @ARGV by using either the -C command line switch or the PERL_UNICODE environment variable, see the perlrun manpage for the documentation of the -C switch.

Note that this means that Perl expects other software to work, too: if Perl has been led to believe that STDIN should be UTF-8, but then STDIN coming in from another command is not UTF-8, Perl will complain about the malformed UTF-8.

All features that combine Unicode and I/O also require using the new PerlIO feature. Almost all Perl 5.8 platforms do use PerlIO, though: you can see whether yours is by running "perl -V" and looking for useperlio=define.

Unicode and EBCDIC

Perl 5.8.0 also supports Unicode on EBCDIC platforms. There, Unicode support is somewhat more complex to implement since additional conversions are needed at every step. Some problems remain, see the perlebcdic manpage for details.

In any case, the Unicode support on EBCDIC platforms is better than in the 5.6 series, which didn't work much at all for EBCDIC platform. On EBCDIC platforms, the internal Unicode encoding form is UTF-EBCDIC instead of UTF-8. The difference is that as UTF-8 is "ASCII-safe" in that ASCII characters encode to UTF-8 as-is, while UTF-EBCDIC is "EBCDIC-safe".

Creating Unicode

To create Unicode characters in literals for code points above 0xFF, use the \x{...} notation in double-quoted strings:

    my $smiley = "\x{263a}";

Similarly, it can be used in regular expression literals

    $smiley =~ /\x{263a}/;

At run-time you can use chr():

    my $hebrew_alef = chr(0x05d0);

See Further Resources for how to find all these numeric codes.

Naturally, ord() will do the reverse: it turns a character into a code point.

Note that \x.. (no {} and only two hexadecimal digits), \x{...}, and chr(...) for arguments less than 0x100 (decimal 256) generate an eight-bit character for backward compatibility with older Perls. For arguments of 0x100 or more, Unicode characters are always produced. If you want to force the production of Unicode characters regardless of the numeric value, use pack("U", ...) instead of \x.., \x{...}, or chr().

You can also use the charnames pragma to invoke characters by name in double-quoted strings:

    use charnames ':full';
    my $arabic_alef = "\N{ARABIC LETTER ALEF}";

And, as mentioned above, you can also pack() numbers into Unicode characters:

   my $georgian_an  = pack("U", 0x10a0);

Note that both \x{...} and \N{...} are compile-time string constants: you cannot use variables in them. if you want similar run-time functionality, use chr() and charnames::vianame().

If you want to force the result to Unicode characters, use the special "U0" prefix. It consumes no arguments but forces the result to be in Unicode characters, instead of bytes.

   my $chars = pack("U0C*", 0x80, 0x42);

Likewise, you can force the result to be bytes by using the special "C0" prefix.

Handling Unicode

Handling Unicode is for the most part transparent: just use the strings as usual. Functions like index(), length(), and substr() will work on the Unicode characters; regular expressions will work on the Unicode characters (see the perlunicode manpage and the perlretut manpage).

Note that Perl considers combining character sequences to be separate characters, so for example

    use charnames ':full';
    print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"), "\n";

will print 2, not 1. The only exception is that regular expressions have \X for matching a combining character sequence.

Life is not quite so transparent, however, when working with legacy encodings, I/O, and certain special cases:

Legacy Encodings

When you combine legacy data and Unicode the legacy data needs to be upgraded to Unicode. Normally ISO 8859-1 (or EBCDIC, if applicable) is assumed. You can override this assumption by using the encoding pragma, for example

    use encoding 'latin2'; # ISO 8859-2

in which case literals (string or regular expressions), chr(), and ord() in your whole script are assumed to produce Unicode characters from ISO 8859-2 code points. Note that the matching for encoding names is forgiving: instead of latin2 you could have said Latin 2, or iso8859-2, or other variations. With just

    use encoding;

the environment variable PERL_ENCODING will be consulted. If that variable isn't set, the encoding pragma will fail.

The Encode module knows about many encodings and has interfaces for doing conversions between those encodings:

    use Encode 'decode';
    $data = decode("iso-8859-3", $data); # convert from legacy to utf-8

Unicode I/O

Normally, writing out Unicode data

    print FH $some_string_with_unicode, "\n";

produces raw bytes that Perl happens to use to internally encode the Unicode string. Perl's internal encoding depends on the system as well as what characters happen to be in the string at the time. If any of the characters are at code points 0x100 or above, you will get a warning. To ensure that the output is explicitly rendered in the encoding you desire--and to avoid the warning--open the stream with the desired encoding. Some examples:

    open FH, ">:utf8", "file";

    open FH, ">:encoding(ucs2)",      "file";
    open FH, ">:encoding(UTF-8)",     "file";
    open FH, ">:encoding(shift_jis)", "file";

and on already open streams, use binmode():

    binmode(STDOUT, ":utf8");

    binmode(STDOUT, ":encoding(ucs2)");
    binmode(STDOUT, ":encoding(UTF-8)");
    binmode(STDOUT, ":encoding(shift_jis)");

The matching of encoding names is loose: case does not matter, and many encodings have several aliases. Note that the :utf8 layer must always be specified exactly like that; it is not subject to the loose matching of encoding names.

See the PerlIO manpage for the :utf8 layer, the PerlIO::encoding manpage and the Encode::PerlIO manpage for the :encoding() layer, and the Encode::Supported manpage for many encodings supported by the Encode module.

Reading in a file that you know happens to be encoded in one of the Unicode or legacy encodings does not magically turn the data into Unicode in Perl's eyes. To do that, specify the appropriate layer when opening files

    open(my $fh,'<:utf8', 'anything');
    my $line_of_unicode = <$fh>;

    open(my $fh,'<:encoding(Big5)', 'anything');
    my $line_of_unicode = <$fh>;

The I/O layers can also be specified more flexibly with the open pragma. See the open manpage, or look at the following example.

    use open ':utf8'; # input and output default layer will be UTF-8
    open X, ">file";
    print X chr(0x100), "\n";
    close X;
    open Y, "<file";
    printf "%#x\n", ord(<Y>); # this should print 0x100
    close Y;

With the open pragma you can use the :locale layer

    BEGIN { $ENV{LC_ALL} = $ENV{LANG} = 'ru_RU.KOI8-R' }
    # the :locale will probe the locale environment variables like LC_ALL
    use open OUT => ':locale'; # russki parusski
    open(O, ">koi8");
    print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
    close O;
    open(I, "<koi8");
    printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
    close I;

or you can also use the ':encoding(...)' layer

    open(my $epic,'<:encoding(iso-8859-7)','iliad.greek');
    my $line_of_unicode = <$epic>;

These methods install a transparent filter on the I/O stream that converts data from the specified encoding when it is read in from the stream. The result is always Unicode.

The the open manpage pragma affects all the open() calls after the pragma by setting default layers. If you want to affect only certain streams, use explicit layers directly in the open() call.

You can switch encodings on an already opened stream by using binmode(); see binmode in the perlfunc manpage.

The :locale does not currently (as of Perl 5.8.0) work with open() and binmode(), only with the open pragma. The :utf8 and :encoding(...) methods do work with all of open(), binmode(), and the open pragma.

Similarly, you may use these I/O layers on output streams to automatically convert Unicode to the specified encoding when it is written to the stream. For example, the following snippet copies the contents of the file "text.jis" (encoded as ISO-2022-JP, aka JIS) to the file "text.utf8", encoded as UTF-8:

    open(my $nihongo, '<:encoding(iso-2022-jp)', 'text.jis');
    open(my $unicode, '>:utf8',                  'text.utf8');
    while (<$nihongo>) { print $unicode $_ }

The naming of encodings, both by the open() and by the open pragma, is similar to the encoding pragma in that it allows for flexible names: koi8-r and KOI8R will both be understood.

Common encodings recognized by ISO, MIME, IANA, and various other standardisation organisations are recognised; for a more detailed list see the Encode::Supported manpage.

read() reads characters and returns the number of characters. seek() and tell() operate on byte counts, as do sysread() and sysseek().

Notice that because of the default behaviour of not doing any conversion upon input if there is no default layer, it is easy to mistakenly write code that keeps on expanding a file by repeatedly encoding the data:

    # BAD CODE WARNING
    open F, "file";
    local $/; ## read in the whole file of 8-bit characters
    $t = <F>;
    close F;
    open F, ">:utf8", "file";
    print F $t; ## convert to UTF-8 on output
    close F;

If you run this code twice, the contents of the file will be twice UTF-8 encoded. A use open ':utf8' would have avoided the bug, or explicitly opening also the file for input as UTF-8.

NOTE: the :utf8 and :encoding features work only if your Perl has been built with the new PerlIO feature (which is the default on most systems).

Displaying Unicode As Text

Sometimes you might want to display Perl scalars containing Unicode as simple ASCII (or EBCDIC) text. The following subroutine converts its argument so that Unicode characters with code points greater than 255 are displayed as \x{...}, control characters (like \n) are displayed as \x.., and the rest of the characters as themselves:

   sub nice_string {
       join("",
         map { $_ > 255 ?                  # if wide character...
               sprintf("\\x{%04X}", $_) :  # \x{...}
               chr($_) =~ /[[:cntrl:]]/ ?  # else if control character ...
               sprintf("\\x%02X", $_) :    # \x..
               quotemeta(chr($_))          # else quoted or as themselves
         } unpack("U*", $_[0]));           # unpack Unicode characters
   }

For example,

   nice_string("foo\x{100}bar\n")

returns the string

   'foo\x{0100}bar\x0A'

which is ready to be printed.

Special Cases

  • Bit Complement Operator ~ And vec()

    The bit complement operator ~ may produce surprising results if used on strings containing characters with ordinal values above 255. In such a case, the results are consistent with the internal encoding of the characters, but not with much else. So don't do that. Similarly for vec(): you will be operating on the internally-encoded bit patterns of the Unicode characters, not on the code point values, which is very probably not what you want.

  • Peeking At Perl's Internal Encoding

    Normal users of Perl should never care how Perl encodes any particular Unicode string (because the normal ways to get at the contents of a string with Unicode--via input and output--should always be via explicitly-defined I/O layers). But if you must, there are two ways of looking behind the scenes.

    One way of peeking inside the internal encoding of Unicode characters is to use unpack("C*", ... to get the bytes or unpack("H*", ...) to display the bytes:

        # this prints  c4 80  for the UTF-8 bytes 0xc4 0x80
    print join(" ", unpack("H*", pack("U", 0x100))), "\n";

    Yet another way would be to use the Devel::Peek module:

        perl -MDevel::Peek -e 'Dump(chr(0x100))'

    That shows the UTF8 flag in FLAGS and both the UTF-8 bytes and Unicode characters in PV. See also later in this document the discussion about the utf8::is_utf8() function.

Advanced Topics

  • String Equivalence

    The question of string equivalence turns somewhat complicated in Unicode: what do you mean by "equal"?

    (Is LATIN CAPITAL LETTER A WITH ACUTE equal to LATIN CAPITAL LETTER A?)

    The short answer is that by default Perl compares equivalence (eq, ne) based only on code points of the characters. In the above case, the answer is no (because 0x00C1 != 0x0041). But sometimes, any CAPITAL LETTER As should be considered equal, or even As of any case.

    The long answer is that you need to consider character normalization and casing issues: see the Unicode::Normalize manpage, Unicode Technical Reports #15 and #21, Unicode Normalization Forms and Case Mappings, http://www.unicode.org/unicode/reports/tr15/ and http://www.unicode.org/unicode/reports/tr21/

    As of Perl 5.8.0, the "Full" case-folding of Case Mappings/SpecialCasing is implemented.

  • String Collation

    People like to see their strings nicely sorted--or as Unicode parlance goes, collated. But again, what do you mean by collate?

    (Does LATIN CAPITAL LETTER A WITH ACUTE come before or after LATIN CAPITAL LETTER A WITH GRAVE?)

    The short answer is that by default, Perl compares strings (lt, le, cmp, ge, gt) based only on the code points of the characters. In the above case, the answer is "after", since 0x00C1 > 0x00C0.

    The long answer is that "it depends", and a good answer cannot be given without knowing (at the very least) the language context. See the Unicode::Collate manpage, and Unicode Collation Algorithm http://www.unicode.org/unicode/reports/tr10/

Miscellaneous

  • Character Ranges and Classes

    Character ranges in regular expression character classes (/[a-z]/) and in the tr/// (also known as y///) operator are not magically Unicode-aware. What this means that [A-Za-z] will not magically start to mean "all alphabetic letters"; not that it does mean that even for 8-bit characters, you should be using /[[:alpha:]]/ in that case.

    For specifying character classes like that in regular expressions, you can use the various Unicode properties--\pL, or perhaps \p{Alphabetic}, in this particular case. You can use Unicode code points as the end points of character ranges, but there is no magic associated with specifying a certain range. For further information--there are dozens of Unicode character classes--see the perlunicode manpage.

  • String-To-Number Conversions

    Unicode does define several other decimal--and numeric--characters besides the familiar 0 to 9, such as the Arabic and Indic digits. Perl does not support string-to-number conversion for digits other than ASCII 0 to 9 (and ASCII a to f for hexadecimal).

Questions With Answers

  • Will My Old Scripts Break?

    Very probably not. Unless you are generating Unicode characters somehow, old behaviour should be preserved. About the only behaviour that has changed and which could start generating Unicode is the old behaviour of chr() where supplying an argument more than 255 produced a character modulo 255. chr(300), for example, was equal to chr(45) or "-" (in ASCII), now it is LATIN CAPITAL LETTER I WITH BREVE.

  • How Do I Make My Scripts Work With Unicode?

    Very little work should be needed since nothing changes until you generate Unicode data. The most important thing is getting input as Unicode; for that, see the earlier I/O discussion.

  • How Do I Know Whether My String Is In Unicode?

    You shouldn't care. No, you really shouldn't. No, really. If you have to care--beyond the cases described above--it means that we didn't get the transparency of Unicode quite right.

    Okay, if you insist:

        print utf8::is_utf8($string) ? 1 : 0, "\n";

    But note that this doesn't mean that any of the characters in the string are necessary UTF-8 encoded, or that any of the characters have code points greater than 0xFF (255) or even 0x80 (128), or that the string has any characters at all. All the is_utf8() does is to return the value of the internal "utf8ness" flag attached to the $string. If the flag is off, the bytes in the scalar are interpreted as a single byte encoding. If the flag is on, the bytes in the scalar are interpreted as the (multi-byte, variable-length) UTF-8 encoded code points of the characters. Bytes added to an UTF-8 encoded string are automatically upgraded to UTF-8. If mixed non-UTF-8 and UTF-8 scalars are merged (double-quoted interpolation, explicit concatenation, and printf/sprintf parameter substitution), the result will be UTF-8 encoded as if copies of the byte strings were upgraded to UTF-8: for example,

        $a = "ab\x80c";
    $b = "\x{100}";
    print "$a = $b\n";

    the output string will be UTF-8-encoded ab\x80c = \x{100}\n, but $a will stay byte-encoded.

    Sometimes you might really need to know the byte length of a string instead of the character length. For that use either the Encode::encode_utf8() function or the bytes pragma and its only defined function length():

        my $unicode = chr(0x100);
    print length($unicode), "\n"; # will print 1
    require Encode;
    print length(Encode::encode_utf8($unicode)), "\n"; # will print 2
    use bytes;
    print length($unicode), "\n"; # will also print 2
                                  # (the 0xC4 0x80 of the UTF-8)

  • How Do I Detect Data That's Not Valid In a Particular Encoding?

    Use the Encode package to try converting it. For example,

        use Encode 'decode_utf8';
    if (decode_utf8($string_of_bytes_that_I_think_is_utf8)) {
        # valid
    } else {
        # invalid
    }

    For UTF-8 only, you can use:

        use warnings;
    @chars = unpack("U0U*", $string_of_bytes_that_I_think_is_utf8);

    If invalid, a Malformed UTF-8 character (byte 0x##) in unpack warning is produced. The "U0" means "expect strictly UTF-8 encoded Unicode". Without that the unpack("U*", ...) would accept also data like chr(0xFF), similarly to the pack as we saw earlier.

  • How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?

    This probably isn't as useful as you might think. Normally, you shouldn't need to.

    In one sense, what you are asking doesn't make much sense: encodings are for characters, and binary data are not "characters", so converting "data" into some encoding isn't meaningful unless you know in what character set and encoding the binary data is in, in which case it's not just binary data, now is it?

    If you have a raw sequence of bytes that you know should be interpreted via a particular encoding, you can use Encode:

        use Encode 'from_to';
    from_to($data, "iso-8859-1", "utf-8"); # from latin-1 to utf-8

    The call to from_to() changes the bytes in $data, but nothing material about the nature of the string has changed as far as Perl is concerned. Both before and after the call, the string $data contains just a bunch of 8-bit bytes. As far as Perl is concerned, the encoding of the string remains as "system-native 8-bit bytes".

    You might relate this to a fictional 'Translate' module:

       use Translate;
   my $phrase = "Yes";
   Translate::from_to($phrase, 'english', 'deutsch');
   ## phrase now contains "Ja"

    The contents of the string changes, but not the nature of the string. Perl doesn't know any more after the call than before that the contents of the string indicates the affirmative.

    Back to converting data. If you have (or want) data in your system's native 8-bit encoding (e.g. Latin-1, EBCDIC, etc.), you can use pack/unpack to convert to/from Unicode.

        $native_string  = pack("C*", unpack("U*", $Unicode_string));
    $Unicode_string = pack("U*", unpack("C*", $native_string));

    If you have a sequence of bytes you know is valid UTF-8, but Perl doesn't know it yet, you can make Perl a believer, too:

        use Encode 'decode_utf8';
    $Unicode = decode_utf8($bytes);

    You can convert well-formed UTF-8 to a sequence of bytes, but if you just want to convert random binary data into UTF-8, you can't. Any random collection of bytes isn't well-formed UTF-8. You can use unpack("C*", $string) for the former, and you can create well-formed Unicode data by pack("U*", 0xff, ...).

  • How Do I Display Unicode? How Do I Input Unicode?

    See http://www.alanwood.net/unicode/ and http://www.cl.cam.ac.uk/~mgk25/unicode.html

  • How Does Unicode Work With Traditional Locales?

    In Perl, not very well. Avoid using locales through the locale pragma. Use only one or the other. But see the perlrun manpage for the description of the -C switch and its environment counterpart, $ENV{PERL_UNICODE} to see how to enable various Unicode features, for example by using locale settings.

Hexadecimal Notation

The Unicode standard prefers using hexadecimal notation because that more clearly shows the division of Unicode into blocks of 256 characters. Hexadecimal is also simply shorter than decimal. You can use decimal notation, too, but learning to use hexadecimal just makes life easier with the Unicode standard. The U+HHHH notation uses hexadecimal, for example.

The 0x prefix means a hexadecimal number, the digits are 0-9 and a-f (or A-F, case doesn't matter). Each hexadecimal digit represents four bits, or half a byte. print 0x..., "\n" will show a hexadecimal number in decimal, and printf "%x\n", $decimal will show a decimal number in hexadecimal. If you have just the "hex digits" of a hexadecimal number, you can use the hex() function.

    print 0x0009, "\n";    # 9
    print 0x000a, "\n";    # 10
    print 0x000f, "\n";    # 15
    print 0x0010, "\n";    # 16
    print 0x0011, "\n";    # 17
    print 0x0100, "\n";    # 256

    print 0x0041, "\n";    # 65

    printf "%x\n",  65;    # 41
    printf "%#x\n", 65;    # 0x41

    print hex("41"), "\n"; # 65

Further Resources

  • Unicode Consortium

        http://www.unicode.org/

  • Unicode FAQ

        http://www.unicode.org/unicode/faq/

  • Unicode Glossary

        http://www.unicode.org/glossary/

  • Unicode Useful Resources

        http://www.unicode.org/unicode/onlinedat/resources.html

  • Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications

        http://www.alanwood.net/unicode/

  • UTF-8 and Unicode FAQ for Unix/Linux

        http://www.cl.cam.ac.uk/~mgk25/unicode.html

  • Legacy Character Sets

        http://www.czyborra.com/
    http://www.eki.ee/letter/

  • The Unicode support files live within the Perl installation in the directory

        $Config{installprivlib}/unicore

    in Perl 5.8.0 or newer, and

        $Config{installprivlib}/unicode

    in the Perl 5.6 series. (The renaming to lib/unicore was done to avoid naming conflicts with lib/Unicode in case-insensitive filesystems.) The main Unicode data file is UnicodeData.txt (or Unicode.301 in Perl 5.6.1.) You can find the $Config{installprivlib} by

        perl "-V:installprivlib"

    You can explore various information from the Unicode data files using the Unicode::UCD module.

UNICODE IN OLDER PERLS

If you cannot upgrade your Perl to 5.8.0 or later, you can still do some Unicode processing by using the modules Unicode::String, Unicode::Map8, and Unicode::Map, available from CPAN. If you have the GNU recode installed, you can also use the Perl front-end Convert::Recode for character conversions.

The following are fast conversions from ISO 8859-1 (Latin-1) bytes to UTF-8 bytes and back, the code works even with older Perl 5 versions.

    # ISO 8859-1 to UTF-8
    s/([\x80-\xFF])/chr(0xC0|ord($1)>>6).chr(0x80|ord($1)&0x3F)/eg;

    # UTF-8 to ISO 8859-1
    s/([\xC2\xC3])([\x80-\xBF])/chr(ord($1)<<6&0xC0|ord($2)&0x3F)/eg;

SEE ALSO

the perlunicode manpage, the Encode manpage, the encoding manpage, the open manpage, the utf8 manpage, the bytes manpage, the perlretut manpage, the perlrun manpage, the Unicode::Collate manpage, the Unicode::Normalize manpage, the Unicode::UCD manpage

ACKNOWLEDGMENTS

Thanks to the kind readers of the perl5-porters@perl.org, perl-unicode@perl.org, linux-utf8@nl.linux.org, and unicore@unicode.org mailing lists for their valuable feedback.

AUTHOR, COPYRIGHT, AND LICENSE

Copyright 2001-2002 Jarkko Hietaniemi <jhi@iki.fi>

This document may be distributed under the same terms as Perl itself.


perlref - Perl references and nested data structures

  • NOTE
  • DESCRIPTION
    • Making References
    • Using References
    • Symbolic references
    • Not-so-symbolic references
    • Pseudo-hashes: Using an array as a hash
    • Function Templates
  • WARNING
  • SEE ALSO

NAME

perlref - Perl references and nested data structures

NOTE

This is complete documentation about all aspects of references. For a shorter, tutorial introduction to just the essential features, see the perlreftut manpage.

DESCRIPTION

Before release 5 of Perl it was difficult to represent complex data structures, because all references had to be symbolic--and even then it was difficult to refer to a variable instead of a symbol table entry. Perl now not only makes it easier to use symbolic references to variables, but also lets you have "hard" references to any piece of data or code. Any scalar may hold a hard reference. Because arrays and hashes contain scalars, you can now easily build arrays of arrays, arrays of hashes, hashes of arrays, arrays of hashes of functions, and so on.

Hard references are smart--they keep track of reference counts for you, automatically freeing the thing referred to when its reference count goes to zero. (Reference counts for values in self-referential or cyclic data structures may not go to zero without a little help; see Two-Phased Garbage Collection in the perlobj manpage for a detailed explanation.) If that thing happens to be an object, the object is destructed. See the perlobj manpage for more about objects. (In a sense, everything in Perl is an object, but we usually reserve the word for references to objects that have been officially "blessed" into a class package.)

Symbolic references are names of variables or other objects, just as a symbolic link in a Unix filesystem contains merely the name of a file. The *glob notation is something of a symbolic reference. (Symbolic references are sometimes called "soft references", but please don't call them that; references are confusing enough without useless synonyms.)

In contrast, hard references are more like hard links in a Unix file system: They are used to access an underlying object without concern for what its (other) name is. When the word "reference" is used without an adjective, as in the following paragraph, it is usually talking about a hard reference.

References are easy to use in Perl. There is just one overriding principle: Perl does no implicit referencing or dereferencing. When a scalar is holding a reference, it always behaves as a simple scalar. It doesn't magically start being an array or hash or subroutine; you have to tell it explicitly to do so, by dereferencing it.

Making References

References can be created in several ways.

  1. By using the backslash operator on a variable, subroutine, or value. (This works much like the & (address-of) operator in C.) This typically creates another reference to a variable, because there's already a reference to the variable in the symbol table. But the symbol table reference might go away, and you'll still have the reference that the backslash returned. Here are some examples:

        $scalarref = \$foo;
    $arrayref  = \@ARGV;
    $hashref   = \%ENV;
    $coderef   = \&handler;
    $globref   = \*foo;

    It isn't possible to create a true reference to an IO handle (filehandle or dirhandle) using the backslash operator. The most you can get is a reference to a typeglob, which is actually a complete symbol table entry. But see the explanation of the *foo{THING} syntax below. However, you can still use type globs and globrefs as though they were IO handles.

  2. A reference to an anonymous array can be created using square brackets:

        $arrayref = [1, 2, ['a', 'b', 'c']];

    Here we've created a reference to an anonymous array of three elements whose final element is itself a reference to another anonymous array of three elements. (The multidimensional syntax described later can be used to access this. For example, after the above, $arrayref->[2][1] would have the value "b".)

    Taking a reference to an enumerated list is not the same as using square brackets--instead it's the same as creating a list of references!

        @list = (\$a, \@b, \%c);
    @list = \($a, @b, %c);      # same thing!

    As a special case, \(@foo) returns a list of references to the contents of @foo, not a reference to @foo itself. Likewise for %foo, except that the key references are to copies (since the keys are just strings rather than full-fledged scalars).

  3. A reference to an anonymous hash can be created using curly brackets:

        $hashref = {
        'Adam'  => 'Eve',
        'Clyde' => 'Bonnie',
    };

    Anonymous hash and array composers like these can be intermixed freely to produce as complicated a structure as you want. The multidimensional syntax described below works for these too. The values above are literals, but variables and expressions would work just as well, because assignment operators in Perl (even within local() or my()) are executable statements, not compile-time declarations.

    Because curly brackets (braces) are used for several other things including BLOCKs, you may occasionally have to disambiguate braces at the beginning of a statement by putting a + or a return in front so that Perl realizes the opening brace isn't starting a BLOCK. The economy and mnemonic value of using curlies is deemed worth this occasional extra hassle.

    For example, if you wanted a function to make a new hash and return a reference to it, you have these options:

        sub hashem {        { @_ } }   # silently wrong
    sub hashem {       +{ @_ } }   # ok
    sub hashem { return { @_ } }   # ok

    On the other hand, if you want the other meaning, you can do this:

        sub showem {        { @_ } }   # ambiguous (currently ok, but may change)
    sub showem {       {; @_ } }   # ok
    sub showem { { return @_ } }   # ok

    The leading +{ and {; always serve to disambiguate the expression to mean either the HASH reference, or the BLOCK.

  4. A reference to an anonymous subroutine can be created by using sub without a subname:

        $coderef = sub { print "Boink!\n" };

    Note the semicolon. Except for the code inside not being immediately executed, a sub {} is not so much a declaration as it is an operator, like do{} or eval{}. (However, no matter how many times you execute that particular line (unless you're in an eval("...")), $coderef will still have a reference to the same anonymous subroutine.)

    Anonymous subroutines act as closures with respect to my() variables, that is, variables lexically visible within the current scope. Closure is a notion out of the Lisp world that says if you define an anonymous function in a particular lexical context, it pretends to run in that context even when it's called outside the context.

    In human terms, it's a funny way of passing arguments to a subroutine when you define it as well as when you call it. It's useful for setting up little bits of code to run later, such as callbacks. You can even do object-oriented stuff with it, though Perl already provides a different mechanism to do that--see the perlobj manpage.

    You might also think of closure as a way to write a subroutine template without using eval(). Here's a small example of how closures work:

        sub newprint {
        my $x = shift;
        return sub { my $y = shift; print "$x, $y!\n"; };
    }
    $h = newprint("Howdy");
    $g = newprint("Greetings");

        # Time passes...

        &$h("world");
    &$g("earthlings");

    This prints

        Howdy, world!
    Greetings, earthlings!

    Note particularly that $x continues to refer to the value passed into newprint() despite "my $x" having gone out of scope by the time the anonymous subroutine runs. That's what a closure is all about.

    This applies only to lexical variables, by the way. Dynamic variables continue to work as they have always worked. Closure is not something that most Perl programmers need trouble themselves about to begin with.

  5. References are often returned by special subroutines called constructors. Perl objects are just references to a special type of object that happens to know which package it's associated with. Constructors are just special subroutines that know how to create that association. They do so by starting with an ordinary reference, and it remains an ordinary reference even while it's also being an object. Constructors are often named new() and called indirectly:

        $objref = new Doggie (Tail => 'short', Ears => 'long');

    But don't have to be:

        $objref   = Doggie->new(Tail => 'short', Ears => 'long');

        use Term::Cap;
    $terminal = Term::Cap->Tgetent( { OSPEED => 9600 });

        use Tk;
    $main    = MainWindow->new();
    $menubar = $main->Frame(-relief              => "raised",
                            -borderwidth         => 2)

  6. References of the appropriate type can spring into existence if you dereference them in a context that assumes they exist. Because we haven't talked about dereferencing yet, we can't show you any examples yet.

  7. A reference can be created by using a special syntax, lovingly known as the *foo{THING} syntax. *foo{THING} returns a reference to the THING slot in *foo (which is the symbol table entry which holds everything known as foo).

        $scalarref = *foo{SCALAR};
    $arrayref  = *ARGV{ARRAY};
    $hashref   = *ENV{HASH};
    $coderef   = *handler{CODE};
    $ioref     = *STDIN{IO};
    $globref   = *foo{GLOB};
    $formatref = *foo{FORMAT};

    All of these are self-explanatory except for *foo{IO}. It returns the IO handle, used for file handles (open in the perlfunc manpage), sockets (socket in the perlfunc manpage and socketpair in the perlfunc manpage), and directory handles (opendir in the perlfunc manpage). For compatibility with previous versions of Perl, *foo{FILEHANDLE} is a synonym for *foo{IO}, though it is deprecated as of 5.8.0. If deprecation warnings are in effect, it will warn of its use.

    *foo{THING} returns undef if that particular THING hasn't been used yet, except in the case of scalars. *foo{SCALAR} returns a reference to an anonymous scalar if $foo hasn't been used yet. This might change in a future release.

    *foo{IO} is an alternative to the *HANDLE mechanism given in Typeglobs and Filehandles in the perldata manpage for passing filehandles into or out of subroutines, or storing into larger data structures. Its disadvantage is that it won't create a new filehandle for you. Its advantage is that you have less risk of clobbering more than you want to with a typeglob assignment. (It still conflates file and directory handles, though.) However, if you assign the incoming value to a scalar instead of a typeglob as we do in the examples below, there's no risk of that happening.

        splutter(*STDOUT);          # pass the whole glob
    splutter(*STDOUT{IO});      # pass both file and dir handles

        sub splutter {
        my $fh = shift;
        print $fh "her um well a hmmm\n";
    }

        $rec = get_rec(*STDIN);     # pass the whole glob
    $rec = get_rec(*STDIN{IO}); # pass both file and dir handles

        sub get_rec {
        my $fh = shift;
        return scalar <$fh>;
    }

Using References

That's it for creating references. By now you're probably dying to know how to use references to get back to your long-lost data. There are several basic methods.

  1. Anywhere you'd put an identifier (or chain of identifiers) as part of a variable or subroutine name, you can replace the identifier with a simple scalar variable containing a reference of the correct type:

        $bar = $$scalarref;
    push(@$arrayref, $filename);
    $$arrayref[0] = "January";
    $$hashref{"KEY"} = "VALUE";
    &$coderef(1,2,3);
    print $globref "output\n";

    It's important to understand that we are specifically not dereferencing $arrayref[0] or $hashref{"KEY"} there. The dereference of the scalar variable happens before it does any key lookups. Anything more complicated than a simple scalar variable must use methods 2 or 3 below. However, a "simple scalar" includes an identifier that itself uses method 1 recursively. Therefore, the following prints "howdy".

        $refrefref = \\\"howdy";
    print $$$$refrefref;

  2. Anywhere you'd put an identifier (or chain of identifiers) as part of a variable or subroutine name, you can replace the identifier with a BLOCK returning a reference of the correct type. In other words, the previous examples could be written like this:

        $bar = ${$scalarref};
    push(@{$arrayref}, $filename);
    ${$arrayref}[0] = "January";
    ${$hashref}{"KEY"} = "VALUE";
    &{$coderef}(1,2,3);
    $globref->print("output\n");  # iff IO::Handle is loaded

    Admittedly, it's a little silly to use the curlies in this case, but the BLOCK can contain any arbitrary expression, in particular, subscripted expressions:

        &{ $dispatch{$index} }(1,2,3);      # call correct routine

    Because of being able to omit the curlies for the simple case of $$x, people often make the mistake of viewing the dereferencing symbols as proper operators, and wonder about their precedence. If they were, though, you could use parentheses instead of braces. That's not the case. Consider the difference below; case 0 is a short-hand version of case 1, not case 2:

        $$hashref{"KEY"}   = "VALUE";       # CASE 0
    ${$hashref}{"KEY"} = "VALUE";       # CASE 1
    ${$hashref{"KEY"}} = "VALUE";       # CASE 2
    ${$hashref->{"KEY"}} = "VALUE";     # CASE 3

    Case 2 is also deceptive in that you're accessing a variable called %hashref, not dereferencing through $hashref to the hash it's presumably referencing. That would be case 3.

  3. >>

    Subroutine calls and lookups of individual array elements arise often enough that it gets cumbersome to use method 2. As a form of syntactic sugar, the examples for method 2 may be written:

        $arrayref->[0] = "January";   # Array element
    $hashref->{"KEY"} = "VALUE";  # Hash element
    $coderef->(1,2,3);            # Subroutine call

    The left side of the arrow can be any expression returning a reference, including a previous dereference. Note that $array[$x] is not the same thing as $array->[$x] here:

        $array[$x]->{"foo"}->[0] = "January";

    This is one of the cases we mentioned earlier in which references could spring into existence when in an lvalue context. Before this statement, $array[$x] may have been undefined. If so, it's automatically defined with a hash reference so that we can look up {"foo"} in it. Likewise $array[$x]->{"foo"} will automatically get defined with an array reference so that we can look up [0] in it. This process is called autovivification.

    One more thing here. The arrow is optional between brackets subscripts, so you can shrink the above down to

        $array[$x]{"foo"}[0] = "January";

    Which, in the degenerate case of using only ordinary arrays, gives you multidimensional arrays just like C's:

        $score[$x][$y][$z] += 42;

    Well, okay, not entirely like C's arrays, actually. C doesn't know how to grow its arrays on demand. Perl does.

  4. If a reference happens to be a reference to an object, then there are probably methods to access the things referred to, and you should probably stick to those methods unless you're in the class package that defines the object's methods. In other words, be nice, and don't violate the object's encapsulation without a very good reason. Perl does not enforce encapsulation. We are not totalitarians here. We do expect some basic civility though.

Using a string or number as a reference produces a symbolic reference, as explained above. Using a reference as a number produces an integer representing its storage location in memory. The only useful thing to be done with this is to compare two references numerically to see whether they refer to the same location.

    if ($ref1 == $ref2) {  # cheap numeric compare of references
        print "refs 1 and 2 refer to the same thing\n";
    }

Using a reference as a string produces both its referent's type, including any package blessing as described in the perlobj manpage, as well as the numeric address expressed in hex. The ref() operator returns just the type of thing the reference is pointing to, without the address. See ref in the perlfunc manpage for details and examples of its use.

The bless() operator may be used to associate the object a reference points to with a package functioning as an object class. See the perlobj manpage.

A typeglob may be dereferenced the same way a reference can, because the dereference syntax always indicates the type of reference desired. So ${*foo} and ${\$foo} both indicate the same scalar variable.

Here's a trick for interpolating a subroutine call into a string:

    print "My sub returned @{[mysub(1,2,3)]} that time.\n";

The way it works is that when the @{...} is seen in the double-quoted string, it's evaluated as a block. The block creates a reference to an anonymous array containing the results of the call to mysub(1,2,3). So the whole block returns a reference to an array, which is then dereferenced by @{...} and stuck into the double-quoted string. This chicanery is also useful for arbitrary expressions:

    print "That yields @{[$n + 5]} widgets\n";

Symbolic references

We said that references spring into existence as necessary if they are undefined, but we didn't say what happens if a value used as a reference is already defined, but isn't a hard reference. If you use it as a reference, it'll be treated as a symbolic reference. That is, the value of the scalar is taken to be the name of a variable, rather than a direct link to a (possibly) anonymous value.

People frequently expect it to work like this. So it does.

    $name = "foo";
    $$name = 1;                 # Sets $foo
    ${$name} = 2;               # Sets $foo
    ${$name x 2} = 3;           # Sets $foofoo
    $name->[0] = 4;             # Sets $foo[0]
    @$name = ();                # Clears @foo
    &$name();                   # Calls &foo() (as in Perl 4)
    $pack = "THAT";
    ${"${pack}::$name"} = 5;    # Sets $THAT::foo without eval

This is powerful, and slightly dangerous, in that it's possible to intend (with the utmost sincerity) to use a hard reference, and accidentally use a symbolic reference instead. To protect against that, you can say

    use strict 'refs';

and then only hard references will be allowed for the rest of the enclosing block. An inner block may countermand that with

    no strict 'refs';

Only package variables (globals, even if localized) are visible to symbolic references. Lexical variables (declared with my()) aren't in a symbol table, and thus are invisible to this mechanism. For example:

    local $value = 10;
    $ref = "value";
    {
        my $value = 20;
        print $$ref;
    }

This will still print 10, not 20. Remember that local() affects package variables, which are all "global" to the package.

Not-so-symbolic references

A new feature contributing to readability in perl version 5.001 is that the brackets around a symbolic reference behave more like quotes, just as they always have within a string. That is,

    $push = "pop on ";
    print "${push}over";

has always meant to print "pop on over", even though push is a reserved word. This has been generalized to work the same outside of quotes, so that

    print ${push} . "over";

and even

    print ${ push } . "over";

will have the same effect. (This would have been a syntax error in Perl 5.000, though Perl 4 allowed it in the spaceless form.) This construct is not considered to be a symbolic reference when you're using strict refs:

    use strict 'refs';
    ${ bareword };      # Okay, means $bareword.
    ${ "bareword" };    # Error, symbolic reference.

Similarly, because of all the subscripting that is done using single words, we've applied the same rule to any bareword that is used for subscripting a hash. So now, instead of writing

    $array{ "aaa" }{ "bbb" }{ "ccc" }

you can write just

    $array{ aaa }{ bbb }{ ccc }

and not worry about whether the subscripts are reserved words. In the rare event that you do wish to do something like

    $array{ shift }

you can force interpretation as a reserved word by adding anything that makes it more than a bareword:

    $array{ shift() }
    $array{ +shift }
    $array{ shift @_ }

The use warnings pragma or the -w switch will warn you if it interprets a reserved word as a string. But it will no longer warn you about using lowercase words, because the string is effectively quoted.

Pseudo-hashes: Using an array as a hash

WARNING: This section describes an experimental feature. Details may change without notice in future versions.

NOTE: The current user-visible implementation of pseudo-hashes (the weird use of the first array element) is deprecated starting from Perl 5.8.0 and will be removed in Perl 5.10.0, and the feature will be implemented differently. Not only is the current interface rather ugly, but the current implementation slows down normal array and hash use quite noticeably. The 'fields' pragma interface will remain available.

Beginning with release 5.005 of Perl, you may use an array reference in some contexts that would normally require a hash reference. This allows you to access array elements using symbolic names, as if they were fields in a structure.

For this to work, the array must contain extra information. The first element of the array has to be a hash reference that maps field names to array indices. Here is an example:

    $struct = [{foo => 1, bar => 2}, "FOO", "BAR"];

    $struct->{foo};  # same as $struct->[1], i.e. "FOO"
    $struct->{bar};  # same as $struct->[2], i.e. "BAR"

    keys %$struct;   # will return ("foo", "bar") in some order
    values %$struct; # will return ("FOO", "BAR") in same some order

    while (my($k,$v) = each %$struct) {
       print "$k => $v\n";
    }

Perl will raise an exception if you try to access nonexistent fields. To avoid inconsistencies, always use the fields::phash() function provided by the fields pragma.

    use fields;
    $pseudohash = fields::phash(foo => "FOO", bar => "BAR");

For better performance, Perl can also do the translation from field names to array indices at compile time for typed object references. See the fields manpage.

There are two ways to check for the existence of a key in a pseudo-hash. The first is to use exists(). This checks to see if the given field has ever been set. It acts this way to match the behavior of a regular hash. For instance:

    use fields;
    $phash = fields::phash([qw(foo bar pants)], ['FOO']);
    $phash->{pants} = undef;

    print exists $phash->{foo};    # true, 'foo' was set in the declaration
    print exists $phash->{bar};    # false, 'bar' has not been used.
    print exists $phash->{pants};  # true, your 'pants' have been touched

The second is to use exists() on the hash reference sitting in the first array element. This checks to see if the given key is a valid field in the pseudo-hash.

    print exists $phash->[0]{bar};      # true, 'bar' is a valid field
    print exists $phash->[0]{shoes};# false, 'shoes' can't be used

delete() on a pseudo-hash element only deletes the value corresponding to the key, not the key itself. To delete the key, you'll have to explicitly delete it from the first hash element.

    print delete $phash->{foo};     # prints $phash->[1], "FOO"
    print exists $phash->{foo};     # false
    print exists $phash->[0]{foo};  # true, key still exists
    print delete $phash->[0]{foo};  # now key is gone
    print $phash->{foo};            # runtime exception

Function Templates

As explained above, an anonymous function with access to the lexical variables visible when that function was compiled, creates a closure. It retains access to those variables even though it doesn't get run until later, such as in a signal handler or a Tk callback.

Using a closure as a function template allows us to generate many functions that act similarly. Suppose you wanted functions named after the colors that generated HTML font changes for the various colors:

    print "Be ", red("careful"), "with that ", green("light");

The red() and green() functions would be similar. To create these, we'll assign a closure to a typeglob of the name of the function we're trying to build.

    @colors = qw(red blue green yellow orange purple violet);
    for my $name (@colors) {
        no strict 'refs';       # allow symbol table manipulation
        *$name = *{uc $name} = sub { "<FONT COLOR='$name'>@_</FONT>" };
    }

Now all those different functions appear to exist independently. You can call red(), RED(), blue(), BLUE(), green(), etc. This technique saves on both compile time and memory use, and is less error-prone as well, since syntax checks happen at compile time. It's critical that any variables in the anonymous subroutine be lexicals in order to create a proper closure. That's the reasons for the my on the loop iteration variable.

This is one of the only places where giving a prototype to a closure makes much sense. If you wanted to impose scalar context on the arguments of these functions (probably not a wise idea for this particular example), you could have written it this way instead:

    *$name = sub ($) { "<FONT COLOR='$name'>$_[0]</FONT>" };

However, since prototype checking happens at compile time, the assignment above happens too late to be of much use. You could address this by putting the whole loop of assignments within a BEGIN block, forcing it to occur during compilation.

Access to lexicals that change over type--like those in the for loop above--only works with closures, not general subroutines. In the general case, then, named subroutines do not nest properly, although anonymous ones do. Thus is because named subroutines are created (and capture any outer lexicals) only once at compile time, whereas anonymous subroutines get to capture each time you execute the 'sub' operator. If you are accustomed to using nested subroutines in other programming languages with their own private variables, you'll have to work at it a bit in Perl. The intuitive coding of this type of thing incurs mysterious warnings about "will not stay shared". For example, this won't work:

    sub outer {
        my $x = $_[0] + 35;
        sub inner { return $x * 19 }   # WRONG
        return $x + inner();
    }

A work-around is the following:

    sub outer {
        my $x = $_[0] + 35;
        local *inner = sub { return $x * 19 };
        return $x + inner();
    }

Now inner() can only be called from within outer(), because of the temporary assignments of the closure (anonymous subroutine). But when it does, it has normal access to the lexical variable $x from the scope of outer().

This has the interesting effect of creating a function local to another function, something not normally supported in Perl.

WARNING

You may not (usefully) use a reference as the key to a hash. It will be converted into a string:

    $x{ \$a } = $a;

If you try to dereference the key, it won't do a hard dereference, and you won't accomplish what you're attempting. You might want to do something more like

    $r = \@a;
    $x{ $r } = $r;

And then at least you can use the values(), which will be real refs, instead of the keys(), which won't.

The standard Tie::RefHash module provides a convenient workaround to this.

SEE ALSO

Besides the obvious documents, source code can be instructive. Some pathological examples of the use of references can be found in the t/op/ref.t regression test in the Perl source directory.

See also the perldsc manpage and the perllol manpage for how to use references to create complex data structures, and the perltoot manpage, the perlobj manpage, and the perlbot manpage for how to use them to create objects.


perlreftut - Mark's very short tutorial about references

  • Who Needs Complicated Data Structures?
  • The Solution
  • Syntax
    • Making References
      • Make Rule 1
    • Using References
      • Use Rule 1
      • Use Rule 2
    • An Example
    • Arrow Rule
  • Solution
  • The Rest
  • Summary
  • Credits
    • Distribution Conditions

NAME

perlreftut - Mark's very short tutorial about references

DESCRIPTION

One of the most important new features in Perl 5 was the capability to manage complicated data structures like multidimensional arrays and nested hashes. To enable these, Perl 5 introduced a feature called `references', and using references is the key to managing complicated, structured data in Perl. Unfortunately, there's a lot of funny syntax to learn, and the main manual page can be hard to follow. The manual is quite complete, and sometimes people find that a problem, because it can be hard to tell what is important and what isn't.

Fortunately, you only need to know 10% of what's in the main page to get 90% of the benefit. This page will show you that 10%.

Who Needs Complicated Data Structures?

One problem that came up all the time in Perl 4 was how to represent a hash whose values were lists. Perl 4 had hashes, of course, but the values had to be scalars; they couldn't be lists.

Why would you want a hash of lists? Let's take a simple example: You have a file of city and country names, like this:

        Chicago, USA
        Frankfurt, Germany
        Berlin, Germany
        Washington, USA
        Helsinki, Finland
        New York, USA

and you want to produce an output like this, with each country mentioned once, and then an alphabetical list of the cities in that country:

        Finland: Helsinki.
        Germany: Berlin, Frankfurt.
        USA:  Chicago, New York, Washington.

The natural way to do this is to have a hash whose keys are country names. Associated with each country name key is a list of the cities in that country. Each time you read a line of input, split it into a country and a city, look up the list of cities already known to be in that country, and append the new city to the list. When you're done reading the input, iterate over the hash as usual, sorting each list of cities before you print it out.

If hash values can't be lists, you lose. In Perl 4, hash values can't be lists; they can only be strings. You lose. You'd probably have to combine all the cities into a single string somehow, and then when time came to write the output, you'd have to break the string into a list, sort the list, and turn it back into a string. This is messy and error-prone. And it's frustrating, because Perl already has perfectly good lists that would solve the problem if only you could use them.

The Solution

By the time Perl 5 rolled around, we were already stuck with this design: Hash values must be scalars. The solution to this is references.

A reference is a scalar value that refers to an entire array or an entire hash (or to just about anything else). Names are one kind of reference that you're already familiar with. Think of the President of the United States: a messy, inconvenient bag of blood and bones. But to talk about him, or to represent him in a computer program, all you need is the easy, convenient scalar string "George Bush".

References in Perl are like names for arrays and hashes. They're Perl's private, internal names, so you can be sure they're unambiguous. Unlike "George Bush", a reference only refers to one thing, and you always know what it refers to. If you have a reference to an array, you can recover the entire array from it. If you have a reference to a hash, you can recover the entire hash. But the reference is still an easy, compact scalar value.

You can't have a hash whose values are arrays; hash values can only be scalars. We're stuck with that. But a single reference can refer to an entire array, and references are scalars, so you can have a hash of references to arrays, and it'll act a lot like a hash of arrays, and it'll be just as useful as a hash of arrays.

We'll come back to this city-country problem later, after we've seen some syntax for managing references.

Syntax

There are just two ways to make a reference, and just two ways to use it once you have it.

Making References

Make Rule 1

If you put a \ in front of a variable, you get a reference to that variable.

    $aref = \@array;         # $aref now holds a reference to @array
    $href = \%hash;          # $href now holds a reference to %hash
    $sref = \$scalar;        # $sref now holds a reference to $scalar

Once the reference is stored in a variable like $aref or $href, you can copy it or store it just the same as any other scalar value:

    $xy = $aref;             # $xy now holds a reference to @array
    $p[3] = $href;           # $p[3] now holds a reference to %hash
    $z = $p[3];              # $z now holds a reference to %hash

These examples show how to make references to variables with names. Sometimes you want to make an array or a hash that doesn't have a name. This is analogous to the way you like to be able to use the string "\n" or the number 80 without having to store it in a named variable first.

Make Rule 2

[ ITEMS ] makes a new, anonymous array, and returns a reference to that array. { ITEMS } makes a new, anonymous hash, and returns a reference to that hash.

    $aref = [ 1, "foo", undef, 13 ];
    # $aref now holds a reference to an array

    $href = { APR => 4, AUG => 8 };
    # $href now holds a reference to a hash

The references you get from rule 2 are the same kind of references that you get from rule 1:

        # This:
        $aref = [ 1, 2, 3 ];

        # Does the same as this:
        @array = (1, 2, 3);
        $aref = \@array;

The first line is an abbreviation for the following two lines, except that it doesn't create the superfluous array variable @array.

If you write just [], you get a new, empty anonymous array. If you write just {}, you get a new, empty anonymous hash.

Using References

What can you do with a reference once you have it? It's a scalar value, and we've seen that you can store it as a scalar and get it back again just like any scalar. There are just two more ways to use it:

Use Rule 1

You can always use an array reference, in curly braces, in place of the name of an array. For example, @{$aref} instead of @array.

Here are some examples of that:

Arrays:

        @a              @{$aref}                An array
        reverse @a      reverse @{$aref}        Reverse the array
        $a[3]           ${$aref}[3]             An element of the array
        $a[3] = 17;     ${$aref}[3] = 17        Assigning an element

On each line are two expressions that do the same thing. The left-hand versions operate on the array @a. The right-hand versions operate on the array that is referred to by $aref. Once they find the array they're operating on, both versions do the same things to the arrays.

Using a hash reference is exactly the same:

        %h              %{$href}              A hash
        keys %h         keys %{$href}         Get the keys from the hash
        $h{'red'}       ${$href}{'red'}       An element of the hash
        $h{'red'} = 17  ${$href}{'red'} = 17  Assigning an element

Whatever you want to do with a reference, Use Rule 1 tells you how to do it. You just write the Perl code that you would have written for doing the same thing to a regular array or hash, and then replace the array or hash name with {$reference}. "How do I loop over an array when all I have is a reference?" Well, to loop over an array, you would write

        for my $element (@array) {
           ...
        }

so replace the array name, @array, with the reference:

        for my $element (@{$aref}) {
           ...
        }

"How do I print out the contents of a hash when all I have is a reference?" First write the code for printing out a hash:

        for my $key (keys %hash) {
          print "$key => $hash{$key}\n";
        }

And then replace the hash name with the reference:

        for my $key (keys %{$href}) {
          print "$key => ${$href}{$key}\n";
        }

Use Rule 2

Use Rule 1 is all you really need, because it tells you how to do absolutely everything you ever need to do with references. But the most common thing to do with an array or a hash is to extract a single element, and the Use Rule 1 notation is cumbersome. So there is an abbreviation.

${$aref}[3] is too hard to read, so you can write $aref->[3] instead.

${$href}{red} is too hard to read, so you can write $href->{red} instead.

If $aref holds a reference to an array, then $aref->[3] is the fourth element of the array. Don't confuse this with $aref[3], which is the fourth element of a totally different array, one deceptively named @aref. $aref and @aref are unrelated the same way that $item and @item are.

Similarly, $href->{'red'} is part of the hash referred to by the scalar variable $href, perhaps even one with no name. $href{'red'} is part of the deceptively named %href hash. It's easy to forget to leave out the ->, and if you do, you'll get bizarre results when your program gets array and hash elements out of totally unexpected hashes and arrays that weren't the ones you wanted to use.

An Example

Let's see a quick example of how all this is useful.

First, remember that [1, 2, 3] makes an anonymous array containing (1, 2, 3), and gives you a reference to that array.

Now think about

        @a = ( [1, 2, 3],
               [4, 5, 6],
               [7, 8, 9]
             );

@a is an array with three elements, and each one is a reference to another array.

$a[1] is one of these references. It refers to an array, the array containing (4, 5, 6), and because it is a reference to an array, Use Rule 2 says that we can write $a[1]->[2] to get the third element from that array. $a[1]->[2] is the 6. Similarly, $a[0]->[1] is the 2. What we have here is like a two-dimensional array; you can write $a[ROW]->[COLUMN] to get or set the element in any row and any column of the array.

The notation still looks a little cumbersome, so there's one more abbreviation:

Arrow Rule

In between two subscripts, the arrow is optional.

Instead of $a[1]->[2], we can write $a[1][2]; it means the same thing. Instead of $a[0]->[1] = 23, we can write $a[0][1] = 23; it means the same thing.

Now it really looks like two-dimensional arrays!

You can see why the arrows are important. Without them, we would have had to write ${$a[1]}[2] instead of $a[1][2]. For three-dimensional arrays, they let us write $x[2][3][5] instead of the unreadable ${${$x[2]}[3]}[5].

Solution

Here's the answer to the problem I posed earlier, of reformatting a file of city and country names.

    1   my %table;

    2   while (<>) {
    3    chomp;
    4     my ($city, $country) = split /, /;
    5     $table{$country} = [] unless exists $table{$country};
    6     push @{$table{$country}}, $city;
    7   }

    8   foreach $country (sort keys %table) {
    9     print "$country: ";
       10     my @cities = @{$table{$country}};
       11     print join ', ', sort @cities;
       12     print ".\n";
       13   }

The program has two pieces: Lines 2--7 read the input and build a data structure, and lines 8-13 analyze the data and print out the report. We're going to have a hash, %table, whose keys are country names, and whose values are references to arrays of city names. The data structure will look like this:

           %table
        +-------+---+
        |       |   |   +-----------+--------+
        |Germany| *---->| Frankfurt | Berlin |
        |       |   |   +-----------+--------+
        +-------+---+
        |       |   |   +----------+
        |Finland| *---->| Helsinki |
        |       |   |   +----------+
        +-------+---+
        |       |   |   +---------+------------+----------+
        |  USA  | *---->| Chicago | Washington | New York |
        |       |   |   +---------+------------+----------+
        +-------+---+

We'll look at output first. Supposing we already have this structure, how do we print it out?

    8   foreach $country (sort keys %table) {
    9     print "$country: ";
       10     my @cities = @{$table{$country}};
       11     print join ', ', sort @cities;
       12     print ".\n";
       13   }

%table is an ordinary hash, and we get a list of keys from it, sort the keys, and loop over the keys as usual. The only use of references is in line 10. $table{$country} looks up the key $country in the hash and gets the value, which is a reference to an array of cities in that country. Use Rule 1 says that we can recover the array by saying @{$table{$country}}. Line 10 is just like

        @cities = @array;

except that the name array has been replaced by the reference {$table{$country}}. The @ tells Perl to get the entire array. Having gotten the list of cities, we sort it, join it, and print it out as usual.

Lines 2-7 are responsible for building the structure in the first place. Here they are again:

    2   while (<>) {
    3    chomp;
    4     my ($city, $country) = split /, /;
    5     $table{$country} = [] unless exists $table{$country};
    6     push @{$table{$country}}, $city;
    7   }

Lines 2-4 acquire a city and country name. Line 5 looks to see if the country is already present as a key in the hash. If it's not, the program uses the [] notation (Make Rule 2) to manufacture a new, empty anonymous array of cities, and installs a reference to it into the hash under the appropriate key.

Line 6 installs the city name into the appropriate array. $table{$country} now holds a reference to the array of cities seen in that country so far. Line 6 is exactly like

        push @array, $city;

except that the name array has been replaced by the reference {$table{$country}}. The push adds a city name to the end of the referred-to array.

There's one fine point I skipped. Line 5 is unnecessary, and we can get rid of it.

    2   while (<>) {
    3    chomp;
    4     my ($city, $country) = split /, /;
    5   ####  $table{$country} = [] unless exists $table{$country};
    6     push @{$table{$country}}, $city;
    7   }

If there's already an entry in %table for the current $country, then nothing is different. Line 6 will locate the value in $table{$country}, which is a reference to an array, and push $city into the array. But what does it do when $country holds a key, say Greece, that is not yet in %table?

This is Perl, so it does the exact right thing. It sees that you want to push Athens onto an array that doesn't exist, so it helpfully makes a new, empty, anonymous array for you, installs it into %table, and then pushes Athens onto it. This is called `autovivification'--bringing things to life automatically. Perl saw that they key wasn't in the hash, so it created a new hash entry automatically. Perl saw that you wanted to use the hash value as an array, so it created a new empty array and installed a reference to it in the hash automatically. And as usual, Perl made the array one element longer to hold the new city name.

The Rest

I promised to give you 90% of the benefit with 10% of the details, and that means I left out 90% of the details. Now that you have an overview of the important parts, it should be easier to read the the perlref manpage manual page, which discusses 100% of the details.

Some of the highlights of the perlref manpage:

  • You can make references to anything, including scalars, functions, and other references.

  • In Use Rule 1, you can omit the curly brackets whenever the thing inside them is an atomic scalar variable like $aref. For example, @$aref is the same as @{$aref}, and $$aref[1] is the same as ${$aref}[1]. If you're just starting out, you may want to adopt the habit of always including the curly brackets.

  • This doesn't copy the underlying array:

            $aref2 = $aref1;

    You get two references to the same array. If you modify $aref1->[23] and then look at $aref2->[23] you'll see the change.

    To copy the array, use

            $aref2 = [@{$aref1}];

    This uses [...] notation to create a new anonymous array, and $aref2 is assigned a reference to the new array. The new array is initialized with the contents of the array referred to by $aref1.

    Similarly, to copy an anonymous hash, you can use

            $href2 = {%{$href1}};

  • To see if a variable contains a reference, use the ref function. It returns true if its argument is a reference. Actually it's a little better than that: It returns HASH for hash references and ARRAY for array references.

  • If you try to use a reference like a string, you get strings like

            ARRAY(0x80f5dec)   or    HASH(0x826afc0)

    If you ever see a string that looks like this, you'll know you printed out a reference by mistake.

    A side effect of this representation is that you can use eq to see if two references refer to the same thing. (But you should usually use == instead because it's much faster.)

  • You can use a string as if it were a reference. If you use the string "foo" as an array reference, it's taken to be a reference to the array @foo. This is called a soft reference or symbolic reference. The declaration use strict 'refs' disables this feature, which can cause all sorts of trouble if you use it by accident.

You might prefer to go on to the perllol manpage instead of the perlref manpage; it discusses lists of lists and multidimensional arrays in detail. After that, you should move on to the perldsc manpage; it's a Data Structure Cookbook that shows recipes for using and printing out arrays of hashes, hashes of arrays, and other kinds of data.

Summary

Everyone needs compound data structures, and in Perl the way you get them is with references. There are four important rules for managing references: Two for making references and two for using them. Once you know these rules you can do most of the important things you need to do with references.

Credits

Author: Mark Jason Dominus, Plover Systems (mjd-perl-ref+@plover.com)

This article originally appeared in The Perl Journal ( http://www.tpj.com/ ) volume 3, #2. Reprinted with permission.

The original title was Understand References Today.

Distribution Conditions

Copyright 1998 The Perl Journal.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in these files are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perlothrtut - old tutorial on threads in Perl

  • What Is A Thread Anyway?
  • Threaded Program Models
    • Boss/Worker
    • Work Crew
    • Pipeline
  • Native threads
  • What kind of threads are perl threads?
  • Threadsafe Modules
  • Thread Basics
    • Basic Thread Support
    • Creating Threads
    • Giving up control
    • Waiting For A Thread To Exit
    • Errors In Threads
    • Ignoring A Thread
  • Threads And Data
    • Shared And Unshared Data
    • Thread Pitfall: Races
    • Controlling access: lock()
    • Thread Pitfall: Deadlocks
    • Queues: Passing Data Around
  • Threads And Code
    • Semaphores: Synchronizing Data Access
    • Attributes: Restricting Access To Subroutines
    • Subroutine Locks
    • Methods
    • Locking A Subroutine
  • General Thread Utility Routines
    • What Thread Am I In?
    • Thread IDs
    • Are These Threads The Same?
    • What Threads Are Running?
  • A Complete Example
  • Conclusion
  • Bibliography
    • Introductory Texts
    • OS-Related References
    • Other References
  • Acknowledgements
  • AUTHOR
  • Copyrights

NAME

perlothrtut - old tutorial on threads in Perl

DESCRIPTION

WARNING: This tutorial describes the old-style thread model that was introduced in release 5.005. This model is now deprecated, and will be removed, probably in version 5.10. The interfaces described here were considered experimental, and are likely to be buggy.

For information about the new interpreter threads ("ithreads") model, see the perlthrtut tutorial, and the the threads manpage and the threads::shared manpage modules.

You are strongly encouraged to migrate any existing threads code to the new model as soon as possible.

What Is A Thread Anyway?

A thread is a flow of control through a program with a single execution point.

Sounds an awful lot like a process, doesn't it? Well, it should. Threads are one of the pieces of a process. Every process has at least one thread and, up until now, every process running Perl had only one thread. With 5.005, though, you can create extra threads. We're going to show you how, when, and why.

Threaded Program Models

There are three basic ways that you can structure a threaded program. Which model you choose depends on what you need your program to do. For many non-trivial threaded programs you'll need to choose different models for different pieces of your program.

Boss/Worker

The boss/worker model usually has one `boss' thread and one or more `worker' threads. The boss thread gathers or generates tasks that need to be done, then parcels those tasks out to the appropriate worker thread.

This model is common in GUI and server programs, where a main thread waits for some event and then passes that event to the appropriate worker threads for processing. Once the event has been passed on, the boss thread goes back to waiting for another event.

The boss thread does relatively little work. While tasks aren't necessarily performed faster than with any other method, it tends to have the best user-response times.

Work Crew

In the work crew model, several threads are created that do essentially the same thing to different pieces of data. It closely mirrors classical parallel processing and vector processors, where a large array of processors do the exact same thing to many pieces of data.

This model is particularly useful if the system running the program will distribute multiple threads across different processors. It can also be useful in ray tracing or rendering engines, where the individual threads can pass on interim results to give the user visual feedback.

Pipeline

The pipeline model divides up a task into a series of steps, and passes the results of one step on to the thread processing the next. Each thread does one thing to each piece of data and passes the results to the next thread in line.

This model makes the most sense if you have multiple processors so two or more threads will be executing in parallel, though it can often make sense in other contexts as well. It tends to keep the individual tasks small and simple, as well as allowing some parts of the pipeline to block (on I/O or system calls, for example) while other parts keep going. If you're running different parts of the pipeline on different processors you may also take advantage of the caches on each processor.

This model is also handy for a form of recursive programming where, rather than having a subroutine call itself, it instead creates another thread. Prime and Fibonacci generators both map well to this form of the pipeline model. (A version of a prime number generator is presented later on.)

Native threads

There are several different ways to implement threads on a system. How threads are implemented depends both on the vendor and, in some cases, the version of the operating system. Often the first implementation will be relatively simple, but later versions of the OS will be more sophisticated.

While the information in this section is useful, it's not necessary, so you can skip it if you don't feel up to it.

There are three basic categories of threads-user-mode threads, kernel threads, and multiprocessor kernel threads.

User-mode threads are threads that live entirely within a program and its libraries. In this model, the OS knows nothing about threads. As far as it's concerned, your process is just a process.

This is the easiest way to implement threads, and the way most OSes start. The big disadvantage is that, since the OS knows nothing about threads, if one thread blocks they all do. Typical blocking activities include most system calls, most I/O, and things like sleep().

Kernel threads are the next step in thread evolution. The OS knows about kernel threads, and makes allowances for them. The main difference between a kernel thread and a user-mode thread is blocking. With kernel threads, things that block a single thread don't block other threads. This is not the case with user-mode threads, where the kernel blocks at the process level and not the thread level.

This is a big step forward, and can give a threaded program quite a performance boost over non-threaded programs. Threads that block performing I/O, for example, won't block threads that are doing other things. Each process still has only one thread running at once, though, regardless of how many CPUs a system might have.

Since kernel threading can interrupt a thread at any time, they will uncover some of the implicit locking assumptions you may make in your program. For example, something as simple as $a = $a + 2 can behave unpredictably with kernel threads if $a is visible to other threads, as another thread may have changed $a between the time it was fetched on the right hand side and the time the new value is stored.

Multiprocessor Kernel Threads are the final step in thread support. With multiprocessor kernel threads on a machine with multiple CPUs, the OS may schedule two or more threads to run simultaneously on different CPUs.

This can give a serious performance boost to your threaded program, since more than one thread will be executing at the same time. As a tradeoff, though, any of those nagging synchronization issues that might not have shown with basic kernel threads will appear with a vengeance.

In addition to the different levels of OS involvement in threads, different OSes (and different thread implementations for a particular OS) allocate CPU cycles to threads in different ways.

Cooperative multitasking systems have running threads give up control if one of two things happen. If a thread calls a yield function, it gives up control. It also gives up control if the thread does something that would cause it to block, such as perform I/O. In a cooperative multitasking implementation, one thread can starve all the others for CPU time if it so chooses.

Preemptive multitasking systems interrupt threads at regular intervals while the system decides which thread should run next. In a preemptive multitasking system, one thread usually won't monopolize the CPU.

On some systems, there can be cooperative and preemptive threads running simultaneously. (Threads running with realtime priorities often behave cooperatively, for example, while threads running at normal priorities behave preemptively.)

What kind of threads are perl threads?

If you have experience with other thread implementations, you might find that things aren't quite what you expect. It's very important to remember when dealing with Perl threads that Perl Threads Are Not X Threads, for all values of X. They aren't POSIX threads, or DecThreads, or Java's Green threads, or Win32 threads. There are similarities, and the broad concepts are the same, but if you start looking for implementation details you're going to be either disappointed or confused. Possibly both.

This is not to say that Perl threads are completely different from everything that's ever come before--they're not. Perl's threading model owes a lot to other thread models, especially POSIX. Just as Perl is not C, though, Perl threads are not POSIX threads. So if you find yourself looking for mutexes, or thread priorities, it's time to step back a bit and think about what you want to do and how Perl can do it.

Threadsafe Modules

The addition of threads has changed Perl's internals substantially. There are implications for people who write modules--especially modules with XS code or external libraries. While most modules won't encounter any problems, modules that aren't explicitly tagged as thread-safe should be tested before being used in production code.

Not all modules that you might use are thread-safe, and you should always assume a module is unsafe unless the documentation says otherwise. This includes modules that are distributed as part of the core. Threads are a beta feature, and even some of the standard modules aren't thread-safe.

If you're using a module that's not thread-safe for some reason, you can protect yourself by using semaphores and lots of programming discipline to control access to the module. Semaphores are covered later in the article. Perl Threads Are Different

Thread Basics

The core Thread module provides the basic functions you need to write threaded programs. In the following sections we'll cover the basics, showing you what you need to do to create a threaded program. After that, we'll go over some of the features of the Thread module that make threaded programming easier.

Basic Thread Support

Thread support is a Perl compile-time option-it's something that's turned on or off when Perl is built at your site, rather than when your programs are compiled. If your Perl wasn't compiled with thread support enabled, then any attempt to use threads will fail.

Remember that the threading support in 5.005 is in beta release, and should be treated as such. You should expect that it may not function entirely properly, and the thread interface may well change some before it is a fully supported, production release. The beta version shouldn't be used for mission-critical projects. Having said that, threaded Perl is pretty nifty, and worth a look.

Your programs can use the Config module to check whether threads are enabled. If your program can't run without them, you can say something like:

  $Config{usethreads} or die "Recompile Perl with threads to run this program.";

A possibly-threaded program using a possibly-threaded module might have code like this:

    use Config;
    use MyMod;

    if ($Config{usethreads}) {
        # We have threads
        require MyMod_threaded;
        import MyMod_threaded;
    } else {
        require MyMod_unthreaded;
        import MyMod_unthreaded;
    }

Since code that runs both with and without threads is usually pretty messy, it's best to isolate the thread-specific code in its own module. In our example above, that's what MyMod_threaded is, and it's only imported if we're running on a threaded Perl.

Creating Threads

The Thread package provides the tools you need to create new threads. Like any other module, you need to tell Perl you want to use it; use Thread imports all the pieces you need to create basic threads.

The simplest, straightforward way to create a thread is with new():

    use Thread;

    $thr = new Thread \&sub1;

    sub sub1 {
        print "In the thread\n";
    }

The new() method takes a reference to a subroutine and creates a new thread, which starts executing in the referenced subroutine. Control then passes both to the subroutine and the caller.

If you need to, your program can pass parameters to the subroutine as part of the thread startup. Just include the list of parameters as part of the Thread::new call, like this:

    use Thread;
    $Param3 = "foo";
    $thr = new Thread \&sub1, "Param 1", "Param 2", $Param3;
    $thr = new Thread \&sub1, @ParamList;
    $thr = new Thread \&sub1, qw(Param1 Param2 $Param3);

    sub sub1 {
        my @InboundParameters = @_;
        print "In the thread\n";
        print "got parameters >", join("<>", @InboundParameters), "<\n";
    }

The subroutine runs like a normal Perl subroutine, and the call to new Thread returns whatever the subroutine returns.

The last example illustrates another feature of threads. You can spawn off several threads using the same subroutine. Each thread executes the same subroutine, but in a separate thread with a separate environment and potentially separate arguments.

The other way to spawn a new thread is with async(), which is a way to spin off a chunk of code like eval(), but into its own thread:

    use Thread qw(async);

    $LineCount = 0;

    $thr = async {
        while(<>) {$LineCount++}
        print "Got $LineCount lines\n";
    };

    print "Waiting for the linecount to end\n";
    $thr->join;
    print "All done\n";

You'll notice we did a use Thread qw(async) in that example. async is not exported by default, so if you want it, you'll either need to import it before you use it or fully qualify it as Thread::async. You'll also note that there's a semicolon after the closing brace. That's because async() treats the following block as an anonymous subroutine, so the semicolon is necessary.

Like eval(), the code executes in the same context as it would if it weren't spun off. Since both the code inside and after the async start executing, you need to be careful with any shared resources. Locking and other synchronization techniques are covered later.

Giving up control

There are times when you may find it useful to have a thread explicitly give up the CPU to another thread. Your threading package might not support preemptive multitasking for threads, for example, or you may be doing something compute-intensive and want to make sure that the user-interface thread gets called frequently. Regardless, there are times that you might want a thread to give up the processor.

Perl's threading package provides the yield() function that does this. yield() is pretty straightforward, and works like this:

    use Thread qw(yield async);
    async {
        my $foo = 50;
        while ($foo--) { print "first async\n" }
        yield;
        $foo = 50;
        while ($foo--) { print "first async\n" }
    };
    async {
        my $foo = 50;
        while ($foo--) { print "second async\n" }
        yield;
        $foo = 50;
        while ($foo--) { print "second async\n" }
    };

Waiting For A Thread To Exit

Since threads are also subroutines, they can return values. To wait for a thread to exit and extract any scalars it might return, you can use the join() method.

    use Thread;
    $thr = new Thread \&sub1;

    @ReturnData = $thr->join;
    print "Thread returned @ReturnData";

    sub sub1 { return "Fifty-six", "foo", 2; }

In the example above, the join() method returns as soon as the thread ends. In addition to waiting for a thread to finish and gathering up any values that the thread might have returned, join() also performs any OS cleanup necessary for the thread. That cleanup might be important, especially for long-running programs that spawn lots of threads. If you don't want the return values and don't want to wait for the thread to finish, you should call the detach() method instead. detach() is covered later in the article.

Errors In Threads

So what happens when an error occurs in a thread? Any errors that could be caught with eval() are postponed until the thread is joined. If your program never joins, the errors appear when your program exits.

Errors deferred until a join() can be caught with eval():

    use Thread qw(async);
    $thr = async {$b = 3/0};   # Divide by zero error
    $foo = eval {$thr->join};
    if ($@) {
        print "died with error $@\n";
    } else {
        print "Hey, why aren't you dead?\n";
    }

eval() passes any results from the joined thread back unmodified, so if you want the return value of the thread, this is your only chance to get them.

Ignoring A Thread

join() does three things: it waits for a thread to exit, cleans up after it, and returns any data the thread may have produced. But what if you're not interested in the thread's return values, and you don't really care when the thread finishes? All you want is for the thread to get cleaned up after when it's done.

In this case, you use the detach() method. Once a thread is detached, it'll run until it's finished, then Perl will clean up after it automatically.

    use Thread;
    $thr = new Thread \&sub1; # Spawn the thread

    $thr->detach; # Now we officially don't care any more

    sub sub1 {
        $a = 0;
        while (1) {
            $a++;
            print "\$a is $a\n";
            sleep 1;
        }
    }

Once a thread is detached, it may not be joined, and any output that it might have produced (if it was done and waiting for a join) is lost.

Threads And Data

Now that we've covered the basics of threads, it's time for our next topic: data. Threading introduces a couple of complications to data access that non-threaded programs never need to worry about.

Shared And Unshared Data

The single most important thing to remember when using threads is that all threads potentially have access to all the data anywhere in your program. While this is true with a nonthreaded Perl program as well, it's especially important to remember with a threaded program, since more than one thread can be accessing this data at once.

Perl's scoping rules don't change because you're using threads. If a subroutine (or block, in the case of async()) could see a variable if you weren't running with threads, it can see it if you are. This is especially important for the subroutines that create, and makes my variables even more important. Remember--if your variables aren't lexically scoped (declared with my) you're probably sharing them between threads.

Thread Pitfall: Races

While threads bring a new set of useful tools, they also bring a number of pitfalls. One pitfall is the race condition:

    use Thread;
    $a = 1;
    $thr1 = Thread->new(\&sub1);
    $thr2 = Thread->new(\&sub2);

    sleep 10;
    print "$a\n";

    sub sub1 { $foo = $a; $a = $foo + 1; }
    sub sub2 { $bar = $a; $a = $bar + 1; }

What do you think $a will be? The answer, unfortunately, is "it depends." Both sub1() and sub2() access the global variable $a, once to read and once to write. Depending on factors ranging from your thread implementation's scheduling algorithm to the phase of the moon, $a can be 2 or 3.

Race conditions are caused by unsynchronized access to shared data. Without explicit synchronization, there's no way to be sure that nothing has happened to the shared data between the time you access it and the time you update it. Even this simple code fragment has the possibility of error:

    use Thread qw(async);
    $a = 2;
    async{ $b = $a; $a = $b + 1; };
    async{ $c = $a; $a = $c + 1; };

Two threads both access $a. Each thread can potentially be interrupted at any point, or be executed in any order. At the end, $a could be 3 or 4, and both $b and $c could be 2 or 3.

Whenever your program accesses data or resources that can be accessed by other threads, you must take steps to coordinate access or risk data corruption and race conditions.

Controlling access: lock()

The lock() function takes a variable (or subroutine, but we'll get to that later) and puts a lock on it. No other thread may lock the variable until the locking thread exits the innermost block containing the lock. Using lock() is straightforward:

    use Thread qw(async);
    $a = 4;
    $thr1 = async {
        $foo = 12;
        {
            lock ($a); # Block until we get access to $a
            $b = $a;
            $a = $b * $foo;
        }
        print "\$foo was $foo\n";
    };
    $thr2 = async {
        $bar = 7;
        {
            lock ($a); # Block until we can get access to $a
            $c = $a;
            $a = $c * $bar;
        }
        print "\$bar was $bar\n";
    };
    $thr1->join;
    $thr2->join;
    print "\$a is $a\n";

lock() blocks the thread until the variable being locked is available. When lock() returns, your thread can be sure that no other thread can lock that variable until the innermost block containing the lock exits.

It's important to note that locks don't prevent access to the variable in question, only lock attempts. This is in keeping with Perl's longstanding tradition of courteous programming, and the advisory file locking that flock() gives you. Locked subroutines behave differently, however. We'll cover that later in the article.

You may lock arrays and hashes as well as scalars. Locking an array, though, will not block subsequent locks on array elements, just lock attempts on the array itself.

Finally, locks are recursive, which means it's okay for a thread to lock a variable more than once. The lock will last until the outermost lock() on the variable goes out of scope.

Thread Pitfall: Deadlocks

Locks are a handy tool to synchronize access to data. Using them properly is the key to safe shared data. Unfortunately, locks aren't without their dangers. Consider the following code:

    use Thread qw(async yield);
    $a = 4;
    $b = "foo";
    async {
        lock($a);
        yield;
        sleep 20;
        lock ($b);
    };
    async {
        lock($b);
        yield;
        sleep 20;
        lock ($a);
    };

This program will probably hang until you kill it. The only way it won't hang is if one of the two async() routines acquires both locks first. A guaranteed-to-hang version is more complicated, but the principle is the same.

The first thread spawned by async() will grab a lock on $a then, a second or two later, try to grab a lock on $b. Meanwhile, the second thread grabs a lock on $b, then later tries to grab a lock on $a. The second lock attempt for both threads will block, each waiting for the other to release its lock.

This condition is called a deadlock, and it occurs whenever two or more threads are trying to get locks on resources that the others own. Each thread will block, waiting for the other to release a lock on a resource. That never happens, though, since the thread with the resource is itself waiting for a lock to be released.

There are a number of ways to handle this sort of problem. The best way is to always have all threads acquire locks in the exact same order. If, for example, you lock variables $a, $b, and $c, always lock $a before $b, and $b before $c. It's also best to hold on to locks for as short a period of time to minimize the risks of deadlock.

Queues: Passing Data Around

A queue is a special thread-safe object that lets you put data in one end and take it out the other without having to worry about synchronization issues. They're pretty straightforward, and look like this:

    use Thread qw(async);
    use Thread::Queue;

    my $DataQueue = new Thread::Queue;
    $thr = async {
        while ($DataElement = $DataQueue->dequeue) {
            print "Popped $DataElement off the queue\n";
        }
    };

    $DataQueue->enqueue(12);
    $DataQueue->enqueue("A", "B", "C");
    $DataQueue->enqueue(\$thr);
    sleep 10;
    $DataQueue->enqueue(undef);

You create the queue with new Thread::Queue. Then you can add lists of scalars onto the end with enqueue(), and pop scalars off the front of it with dequeue(). A queue has no fixed size, and can grow as needed to hold everything pushed on to it.

If a queue is empty, dequeue() blocks until another thread enqueues something. This makes queues ideal for event loops and other communications between threads.

Threads And Code

In addition to providing thread-safe access to data via locks and queues, threaded Perl also provides general-purpose semaphores for coarser synchronization than locks provide and thread-safe access to entire subroutines.

Semaphores: Synchronizing Data Access

Semaphores are a kind of generic locking mechanism. Unlike lock, which gets a lock on a particular scalar, Perl doesn't associate any particular thing with a semaphore so you can use them to control access to anything you like. In addition, semaphores can allow more than one thread to access a resource at once, though by default semaphores only allow one thread access at a time.

Basic semaphores

Semaphores have two methods, down and up. down decrements the resource count, while up increments it. down calls will block if the semaphore's current count would decrement below zero. This program gives a quick demonstration:

    use Thread qw(yield);
    use Thread::Semaphore;
    my $semaphore = new Thread::Semaphore;
    $GlobalVariable = 0;

    $thr1 = new Thread \&sample_sub, 1;
    $thr2 = new Thread \&sample_sub, 2;
    $thr3 = new Thread \&sample_sub, 3;

    sub sample_sub {
        my $SubNumber = shift @_;
        my $TryCount = 10;
        my $LocalCopy;
        sleep 1;
        while ($TryCount--) {
            $semaphore->down;
            $LocalCopy = $GlobalVariable;
            print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n";
            yield;
            sleep 2;
            $LocalCopy++;
            $GlobalVariable = $LocalCopy;
            $semaphore->up;
        }
    }

The three invocations of the subroutine all operate in sync. The semaphore, though, makes sure that only one thread is accessing the global variable at once.

Advanced Semaphores

By default, semaphores behave like locks, letting only one thread down() them at a time. However, there are other uses for semaphores.

Each semaphore has a counter attached to it. down() decrements the counter and up() increments the counter. By default, semaphores are created with the counter set to one, down() decrements by one, and up() increments by one. If down() attempts to decrement the counter below zero, it blocks until the counter is large enough. Note that while a semaphore can be created with a starting count of zero, any up() or down() always changes the counter by at least one. $semaphore->down(0) is the same as $semaphore->down(1).

The question, of course, is why would you do something like this? Why create a semaphore with a starting count that's not one, or why decrement/increment it by more than one? The answer is resource availability. Many resources that you want to manage access for can be safely used by more than one thread at once.

For example, let's take a GUI driven program. It has a semaphore that it uses to synchronize access to the display, so only one thread is ever drawing at once. Handy, but of course you don't want any thread to start drawing until things are properly set up. In this case, you can create a semaphore with a counter set to zero, and up it when things are ready for drawing.

Semaphores with counters greater than one are also useful for establishing quotas. Say, for example, that you have a number of threads that can do I/O at once. You don't want all the threads reading or writing at once though, since that can potentially swamp your I/O channels, or deplete your process' quota of filehandles. You can use a semaphore initialized to the number of concurrent I/O requests (or open files) that you want at any one time, and have your threads quietly block and unblock themselves.

Larger increments or decrements are handy in those cases where a thread needs to check out or return a number of resources at once.

Attributes: Restricting Access To Subroutines

In addition to synchronizing access to data or resources, you might find it useful to synchronize access to subroutines. You may be accessing a singular machine resource (perhaps a vector processor), or find it easier to serialize calls to a particular subroutine than to have a set of locks and semaphores.

One of the additions to Perl 5.005 is subroutine attributes. The Thread package uses these to provide several flavors of serialization. It's important to remember that these attributes are used in the compilation phase of your program so you can't change a subroutine's behavior while your program is actually running.

Subroutine Locks

The basic subroutine lock looks like this:

    sub test_sub :locked {
    }

This ensures that only one thread will be executing this subroutine at any one time. Once a thread calls this subroutine, any other thread that calls it will block until the thread in the subroutine exits it. A more elaborate example looks like this:

    use Thread qw(yield);

    new Thread \&thread_sub, 1;
    new Thread \&thread_sub, 2;
    new Thread \&thread_sub, 3;
    new Thread \&thread_sub, 4;

    sub sync_sub :locked {
        my $CallingThread = shift @_;
        print "In sync_sub for thread $CallingThread\n";
        yield;
        sleep 3;
        print "Leaving sync_sub for thread $CallingThread\n";
    }

    sub thread_sub {
        my $ThreadID = shift @_;
        print "Thread $ThreadID calling sync_sub\n";
        sync_sub($ThreadID);
        print "$ThreadID is done with sync_sub\n";
    }

The locked attribute tells perl to lock sync_sub(), and if you run this, you can see that only one thread is in it at any one time.

Methods

Locking an entire subroutine can sometimes be overkill, especially when dealing with Perl objects. When calling a method for an object, for example, you want to serialize calls to a method, so that only one thread will be in the subroutine for a particular object, but threads calling that subroutine for a different object aren't blocked. The method attribute indicates whether the subroutine is really a method.

    use Thread;

    sub tester {
        my $thrnum = shift @_;
        my $bar = new Foo;
        foreach (1..10) {
            print "$thrnum calling per_object\n";
            $bar->per_object($thrnum);
            print "$thrnum out of per_object\n";
            yield;
            print "$thrnum calling one_at_a_time\n";
            $bar->one_at_a_time($thrnum);
            print "$thrnum out of one_at_a_time\n";
            yield;
        }
    }

    foreach my $thrnum (1..10) {
        new Thread \&tester, $thrnum;
    }

    package Foo;
    sub new {
        my $class = shift @_;
        return bless [@_], $class;
    }

    sub per_object :locked :method {
        my ($class, $thrnum) = @_;
        print "In per_object for thread $thrnum\n";
        yield;
        sleep 2;
        print "Exiting per_object for thread $thrnum\n";
    }

    sub one_at_a_time :locked {
        my ($class, $thrnum) = @_;
        print "In one_at_a_time for thread $thrnum\n";
        yield;
        sleep 2;
        print "Exiting one_at_a_time for thread $thrnum\n";
    }

As you can see from the output (omitted for brevity; it's 800 lines) all the threads can be in per_object() simultaneously, but only one thread is ever in one_at_a_time() at once.

Locking A Subroutine

You can lock a subroutine as you would lock a variable. Subroutine locks work the same as specifying a locked attribute for the subroutine, and block all access to the subroutine for other threads until the lock goes out of scope. When the subroutine isn't locked, any number of threads can be in it at once, and getting a lock on a subroutine doesn't affect threads already in the subroutine. Getting a lock on a subroutine looks like this:

    lock(\&sub_to_lock);

Simple enough. Unlike the locked attribute, which is a compile time option, locking and unlocking a subroutine can be done at runtime at your discretion. There is some runtime penalty to using lock(\&sub) instead of the locked attribute, so make sure you're choosing the proper method to do the locking.

You'd choose lock(\&sub) when writing modules and code to run on both threaded and unthreaded Perl, especially for code that will run on 5.004 or earlier Perls. In that case, it's useful to have subroutines that should be serialized lock themselves if they're running threaded, like so:

    package Foo;
    use Config;
    $Running_Threaded = 0;

    BEGIN { $Running_Threaded = $Config{'usethreads'} }

    sub sub1 { lock(\&sub1) if $Running_Threaded }

This way you can ensure single-threadedness regardless of which version of Perl you're running.

General Thread Utility Routines

We've covered the workhorse parts of Perl's threading package, and with these tools you should be well on your way to writing threaded code and packages. There are a few useful little pieces that didn't really fit in anyplace else.

What Thread Am I In?

The Thread->self method provides your program with a way to get an object representing the thread it's currently in. You can use this object in the same way as the ones returned from the thread creation.

Thread IDs

tid() is a thread object method that returns the thread ID of the thread the object represents. Thread IDs are integers, with the main thread in a program being 0. Currently Perl assigns a unique tid to every thread ever created in your program, assigning the first thread to be created a tid of 1, and increasing the tid by 1 for each new thread that's created.

Are These Threads The Same?

The equal() method takes two thread objects and returns true if the objects represent the same thread, and false if they don't.

What Threads Are Running?

Thread->list returns a list of thread objects, one for each thread that's currently running. Handy for a number of things, including cleaning up at the end of your program:

    # Loop through all the threads
    foreach $thr (Thread->list) {
        # Don't join the main thread or ourselves
        if ($thr->tid && !Thread::equal($thr, Thread->self)) {
            $thr->join;
        }
    }

The example above is just for illustration. It isn't strictly necessary to join all the threads you create, since Perl detaches all the threads before it exits.

A Complete Example

Confused yet? It's time for an example program to show some of the things we've covered. This program finds prime numbers using threads.

    1  #!/usr/bin/perl -w
    2  # prime-pthread, courtesy of Tom Christiansen
    3
    4  use strict;
    5
    6  use Thread;
    7  use Thread::Queue;
    8
    9  my $stream = new Thread::Queue;
    10 my $kid    = new Thread(\&check_num, $stream, 2);
    11
    12 for my $i ( 3 .. 1000 ) {
    13     $stream->enqueue($i);
    14 }
    15
    16 $stream->enqueue(undef);
    17 $kid->join();
    18
    19 sub check_num {
    20     my ($upstream, $cur_prime) = @_;
    21     my $kid;
    22     my $downstream = new Thread::Queue;
    23     while (my $num = $upstream->dequeue) {
    24         next unless $num % $cur_prime;
    25         if ($kid) {
    26            $downstream->enqueue($num);
    27                  } else {
    28            print "Found prime $num\n";
    29                $kid = new Thread(\&check_num, $downstream, $num);
    30         }
    31     }
    32     $downstream->enqueue(undef) if $kid;
    33     $kid->join()         if $kid;
    34 }

This program uses the pipeline model to generate prime numbers. Each thread in the pipeline has an input queue that feeds numbers to be checked, a prime number that it's responsible for, and an output queue that it funnels numbers that have failed the check into. If the thread has a number that's failed its check and there's no child thread, then the thread must have found a new prime number. In that case, a new child thread is created for that prime and stuck on the end of the pipeline.

This probably sounds a bit more confusing than it really is, so lets go through this program piece by piece and see what it does. (For those of you who might be trying to remember exactly what a prime number is, it's a number that's only evenly divisible by itself and 1)

The bulk of the work is done by the check_num() subroutine, which takes a reference to its input queue and a prime number that it's responsible for. After pulling in the input queue and the prime that the subroutine's checking (line 20), we create a new queue (line 22) and reserve a scalar for the thread that we're likely to create later (line 21).

The while loop from lines 23 to line 31 grabs a scalar off the input queue and checks against the prime this thread is responsible for. Line 24 checks to see if there's a remainder when we modulo the number to be checked against our prime. If there is one, the number must not be evenly divisible by our prime, so we need to either pass it on to the next thread if we've created one (line 26) or create a new thread if we haven't.

The new thread creation is line 29. We pass on to it a reference to the queue we've created, and the prime number we've found.

Finally, once the loop terminates (because we got a 0 or undef in the queue, which serves as a note to die), we pass on the notice to our child and wait for it to exit if we've created a child (Lines 32 and 37).

Meanwhile, back in the main thread, we create a queue (line 9) and the initial child thread (line 10), and pre-seed it with the first prime: 2. Then we queue all the numbers from 3 to 1000 for checking (lines 12-14), then queue a die notice (line 16) and wait for the first child thread to terminate (line 17). Because a child won't die until its child has died, we know that we're done once we return from the join.

That's how it works. It's pretty simple; as with many Perl programs, the explanation is much longer than the program.

Conclusion

A complete thread tutorial could fill a book (and has, many times), but this should get you well on your way. The final authority on how Perl's threads behave is the documentation bundled with the Perl distribution, but with what we've covered in this article, you should be well on your way to becoming a threaded Perl expert.

Bibliography

Here's a short bibliography courtesy of Jürgen Christoffel:

Introductory Texts

Birrell, Andrew D. An Introduction to Programming with Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report #35 online as http://www.research.digital.com/SRC/staff/birrell/bib.html (highly recommended)

Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A Guide to Concurrency, Communication, and Multithreading. Prentice-Hall, 1996.

Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written introduction to threads).

Nelson, Greg (editor). Systems Programming with Modula-3. Prentice Hall, 1991, ISBN 0-13-590464-1.

Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell. Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1 (covers POSIX threads).

OS-Related References

Boykin, Joseph, David Kirschen, Alan Langerman, and Susan LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1.

Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, 1995, ISBN 0-13-219908-4 (great textbook).

Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4

Other References

Arnold, Ken and James Gosling. The Java Programming Language, 2nd ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.

Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage Collection on Virtually Shared Memory Architectures" in Memory Management: Proc. of the International Workshop IWMM 92, St. Malo, France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer, 1992, ISBN 3540-55940-X (real-life thread applications).

Acknowledgements

Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua Pritikin, and Alan Burlison, for their help in reality-checking and polishing this article. Big thanks to Tom Christiansen for his rewrite of the prime number generator.

AUTHOR

Dan Sugalski <sugalskd@ous.edu>

Copyrights

This article originally appeared in The Perl Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.


perlthrtut - tutorial on threads in Perl

  • Status
  • What Is A Thread Anyway?
  • Threaded Program Models
    • Boss/Worker
    • Work Crew
    • Pipeline
  • What kind of threads are Perl threads?
  • Thread-Safe Modules
  • Thread Basics
    • Basic Thread Support
    • A Note about the Examples
    • Creating Threads
    • Waiting For A Thread To Exit
    • Ignoring A Thread
  • Threads And Data
    • Shared And Unshared Data
    • Thread Pitfalls: Races
  • Synchronization and control
    • Controlling access: lock()
    • A Thread Pitfall: Deadlocks
    • Queues: Passing Data Around
    • Semaphores: Synchronizing Data Access
    • Basic semaphores
    • Advanced Semaphores
    • cond_wait() and cond_signal()
    • Giving up control
  • General Thread Utility Routines
    • What Thread Am I In?
    • Thread IDs
    • Are These Threads The Same?
    • What Threads Are Running?
  • A Complete Example
  • Different implementations of threads
  • Performance considerations
  • Process-scope Changes
  • Thread-Safety of System Libraries
  • Conclusion
  • Bibliography
    • Introductory Texts
    • OS-Related References
    • Other References
  • Acknowledgements
  • AUTHOR
  • Copyrights

NAME

perlthrtut - tutorial on threads in Perl

DESCRIPTION

NOTE: this tutorial describes the new Perl threading flavour introduced in Perl 5.6.0 called interpreter threads, or ithreads for short. In this model each thread runs in its own Perl interpreter, and any data sharing between threads must be explicit.

There is another older Perl threading flavour called the 5.005 model, unsurprisingly for 5.005 versions of Perl. The old model is known to have problems, deprecated, and will probably be removed around release 5.10. You are strongly encouraged to migrate any existing 5.005 threads code to the new model as soon as possible.

You can see which (or neither) threading flavour you have by running perl -V and looking at the Platform section. If you have useithreads=define you have ithreads, if you have use5005threads=define you have 5.005 threads. If you have neither, you don't have any thread support built in. If you have both, you are in trouble.

The user-level interface to the 5.005 threads was via the Threads class, while ithreads uses the the threads manpage class. Note the change in case.

Status

The ithreads code has been available since Perl 5.6.0, and is considered stable. The user-level interface to ithreads (the the threads manpage classes) appeared in the 5.8.0 release, and as of this time is considered stable although it should be treated with caution as with all new features.

What Is A Thread Anyway?

A thread is a flow of control through a program with a single execution point.

Sounds an awful lot like a process, doesn't it? Well, it should. Threads are one of the pieces of a process. Every process has at least one thread and, up until now, every process running Perl had only one thread. With 5.8, though, you can create extra threads. We're going to show you how, when, and why.

Threaded Program Models

There are three basic ways that you can structure a threaded program. Which model you choose depends on what you need your program to do. For many non-trivial threaded programs you'll need to choose different models for different pieces of your program.

Boss/Worker

The boss/worker model usually has one "boss" thread and one or more "worker" threads. The boss thread gathers or generates tasks that need to be done, then parcels those tasks out to the appropriate worker thread.

This model is common in GUI and server programs, where a main thread waits for some event and then passes that event to the appropriate worker threads for processing. Once the event has been passed on, the boss thread goes back to waiting for another event.

The boss thread does relatively little work. While tasks aren't necessarily performed faster than with any other method, it tends to have the best user-response times.

Work Crew

In the work crew model, several threads are created that do essentially the same thing to different pieces of data. It closely mirrors classical parallel processing and vector processors, where a large array of processors do the exact same thing to many pieces of data.

This model is particularly useful if the system running the program will distribute multiple threads across different processors. It can also be useful in ray tracing or rendering engines, where the individual threads can pass on interim results to give the user visual feedback.

Pipeline

The pipeline model divides up a task into a series of steps, and passes the results of one step on to the thread processing the next. Each thread does one thing to each piece of data and passes the results to the next thread in line.

This model makes the most sense if you have multiple processors so two or more threads will be executing in parallel, though it can often make sense in other contexts as well. It tends to keep the individual tasks small and simple, as well as allowing some parts of the pipeline to block (on I/O or system calls, for example) while other parts keep going. If you're running different parts of the pipeline on different processors you may also take advantage of the caches on each processor.

This model is also handy for a form of recursive programming where, rather than having a subroutine call itself, it instead creates another thread. Prime and Fibonacci generators both map well to this form of the pipeline model. (A version of a prime number generator is presented later on.)

What kind of threads are Perl threads?

If you have experience with other thread implementations, you might find that things aren't quite what you expect. It's very important to remember when dealing with Perl threads that Perl Threads Are Not X Threads, for all values of X. They aren't POSIX threads, or DecThreads, or Java's Green threads, or Win32 threads. There are similarities, and the broad concepts are the same, but if you start looking for implementation details you're going to be either disappointed or confused. Possibly both.

This is not to say that Perl threads are completely different from everything that's ever come before--they're not. Perl's threading model owes a lot to other thread models, especially POSIX. Just as Perl is not C, though, Perl threads are not POSIX threads. So if you find yourself looking for mutexes, or thread priorities, it's time to step back a bit and think about what you want to do and how Perl can do it.

However it is important to remember that Perl threads cannot magically do things unless your operating systems threads allows it. So if your system blocks the entire process on sleep(), Perl usually will as well.

Perl Threads Are Different.

Thread-Safe Modules

The addition of threads has changed Perl's internals substantially. There are implications for people who write modules with XS code or external libraries. However, since perl data is not shared among threads by default, Perl modules stand a high chance of being thread-safe or can be made thread-safe easily. Modules that are not tagged as thread-safe should be tested or code reviewed before being used in production code.

Not all modules that you might use are thread-safe, and you should always assume a module is unsafe unless the documentation says otherwise. This includes modules that are distributed as part of the core. Threads are a new feature, and even some of the standard modules aren't thread-safe.

Even if a module is thread-safe, it doesn't mean that the module is optimized to work well with threads. A module could possibly be rewritten to utilize the new features in threaded Perl to increase performance in a threaded environment.

If you're using a module that's not thread-safe for some reason, you can protect yourself by using it from one, and only one thread at all. If you need multiple threads to access such a module, you can use semaphores and lots of programming discipline to control access to it. Semaphores are covered in Basic semaphores.

See also Thread-Safety of System Libraries.

Thread Basics

The core the threads manpage module provides the basic functions you need to write threaded programs. In the following sections we'll cover the basics, showing you what you need to do to create a threaded program. After that, we'll go over some of the features of the the threads manpage module that make threaded programming easier.

Basic Thread Support

Thread support is a Perl compile-time option - it's something that's turned on or off when Perl is built at your site, rather than when your programs are compiled. If your Perl wasn't compiled with thread support enabled, then any attempt to use threads will fail.

Your programs can use the Config module to check whether threads are enabled. If your program can't run without them, you can say something like:

    $Config{useithreads} or die "Recompile Perl with threads to run this program.";

A possibly-threaded program using a possibly-threaded module might have code like this:

    use Config;
    use MyMod;

    BEGIN {
        if ($Config{useithreads}) {
            # We have threads
            require MyMod_threaded;
           import MyMod_threaded;
        } else {
           require MyMod_unthreaded;
           import MyMod_unthreaded;
        }
    }

Since code that runs both with and without threads is usually pretty messy, it's best to isolate the thread-specific code in its own module. In our example above, that's what MyMod_threaded is, and it's only imported if we're running on a threaded Perl.

A Note about the Examples

Although thread support is considered to be stable, there are still a number of quirks that may startle you when you try out any of the examples below. In a real situation, care should be taken that all threads are finished executing before the program exits. That care has not been taken in these examples in the interest of simplicity. Running these examples "as is" will produce error messages, usually caused by the fact that there are still threads running when the program exits. You should not be alarmed by this. Future versions of Perl may fix this problem.

Creating Threads

The the threads manpage package provides the tools you need to create new threads. Like any other module, you need to tell Perl that you want to use it; use threads imports all the pieces you need to create basic threads.

The simplest, most straightforward way to create a thread is with new():

    use threads;

    $thr = threads->new(\&sub1);

    sub sub1 {
        print "In the thread\n";
    }

The new() method takes a reference to a subroutine and creates a new thread, which starts executing in the referenced subroutine. Control then passes both to the subroutine and the caller.

If you need to, your program can pass parameters to the subroutine as part of the thread startup. Just include the list of parameters as part of the threads::new call, like this:

    use threads;

    $Param3 = "foo";
    $thr = threads->new(\&sub1, "Param 1", "Param 2", $Param3);
    $thr = threads->new(\&sub1, @ParamList);
    $thr = threads->new(\&sub1, qw(Param1 Param2 Param3));

    sub sub1 {
        my @InboundParameters = @_;
        print "In the thread\n";
        print "got parameters >", join("<>", @InboundParameters), "<\n";
    }

The last example illustrates another feature of threads. You can spawn off several threads using the same subroutine. Each thread executes the same subroutine, but in a separate thread with a separate environment and potentially separate arguments.

create() is a synonym for new().

Waiting For A Thread To Exit

Since threads are also subroutines, they can return values. To wait for a thread to exit and extract any values it might return, you can use the join() method:

    use threads;

    $thr = threads->new(\&sub1);

    @ReturnData = $thr->join;
    print "Thread returned @ReturnData";

    sub sub1 { return "Fifty-six", "foo", 2; }

In the example above, the join() method returns as soon as the thread ends. In addition to waiting for a thread to finish and gathering up any values that the thread might have returned, join() also performs any OS cleanup necessary for the thread. That cleanup might be important, especially for long-running programs that spawn lots of threads. If you don't want the return values and don't want to wait for the thread to finish, you should call the detach() method instead, as described next.

Ignoring A Thread

join() does three things: it waits for a thread to exit, cleans up after it, and returns any data the thread may have produced. But what if you're not interested in the thread's return values, and you don't really care when the thread finishes? All you want is for the thread to get cleaned up after when it's done.

In this case, you use the detach() method. Once a thread is detached, it'll run until it's finished, then Perl will clean up after it automatically.

    use threads;

    $thr = threads->new(\&sub1); # Spawn the thread

    $thr->detach; # Now we officially don't care any more

    sub sub1 {
        $a = 0;
        while (1) {
            $a++;
            print "\$a is $a\n";
            sleep 1;
        }
    }

Once a thread is detached, it may not be joined, and any return data that it might have produced (if it was done and waiting for a join) is lost.

Threads And Data

Now that we've covered the basics of threads, it's time for our next topic: data. Threading introduces a couple of complications to data access that non-threaded programs never need to worry about.

Shared And Unshared Data

The biggest difference between Perl ithreads and the old 5.005 style threading, or for that matter, to most other threading systems out there, is that by default, no data is shared. When a new perl thread is created, all the data associated with the current thread is copied to the new thread, and is subsequently private to that new thread! This is similar in feel to what happens when a UNIX process forks, except that in this case, the data is just copied to a different part of memory within the same process rather than a real fork taking place.

To make use of threading however, one usually wants the threads to share at least some data between themselves. This is done with the the threads::shared manpage module and the : shared attribute:

    use threads;
    use threads::shared;

    my $foo : shared = 1;
    my $bar = 1;
    threads->new(sub { $foo++; $bar++ })->join;

    print "$foo\n";  #prints 2 since $foo is shared
    print "$bar\n";  #prints 1 since $bar is not shared

In the case of a shared array, all the array's elements are shared, and for a shared hash, all the keys and values are shared. This places restrictions on what may be assigned to shared array and hash elements: only simple values or references to shared variables are allowed - this is so that a private variable can't accidentally become shared. A bad assignment will cause the thread to die. For example:

    use threads;
    use threads::shared;

    my $var           = 1;
    my $svar : shared = 2;
    my %hash : shared;

    ... create some threads ...
    $hash{a} = 1;       # all threads see exists($hash{a}) and $hash{a} == 1
    $hash{a} = $var     # okay - copy-by-value: same effect as previous
    $hash{a} = $svar    # okay - copy-by-value: same effect as previous
    $hash{a} = \$svar   # okay - a reference to a shared variable
    $hash{a} = \$var    # This will die
    delete $hash{a}     # okay - all threads will see !exists($hash{a})

Note that a shared variable guarantees that if two or more threads try to modify it at the same time, the internal state of the variable will not become corrupted. However, there are no guarantees beyond this, as explained in the next section.

Thread Pitfalls: Races

While threads bring a new set of useful tools, they also bring a number of pitfalls. One pitfall is the race condition:

    use threads;
    use threads::shared;

    my $a : shared = 1;
    $thr1 = threads->new(\&sub1);
    $thr2 = threads->new(\&sub2);

    $thr1->join;
    $thr2->join;
    print "$a\n";

    sub sub1 { my $foo = $a; $a = $foo + 1; }
    sub sub2 { my $bar = $a; $a = $bar + 1; }

What do you think $a will be? The answer, unfortunately, is "it depends." Both sub1() and sub2() access the global variable $a, once to read and once to write. Depending on factors ranging from your thread implementation's scheduling algorithm to the phase of the moon, $a can be 2 or 3.

Race conditions are caused by unsynchronized access to shared data. Without explicit synchronization, there's no way to be sure that nothing has happened to the shared data between the time you access it and the time you update it. Even this simple code fragment has the possibility of error:

    use threads;
    my $a : shared = 2;
    my $b : shared;
    my $c : shared;
    my $thr1 = threads->create(sub { $b = $a; $a = $b + 1; });
    my $thr2 = threads->create(sub { $c = $a; $a = $c + 1; });
    $thr1->join;
    $thr2->join;

Two threads both access $a. Each thread can potentially be interrupted at any point, or be executed in any order. At the end, $a could be 3 or 4, and both $b and $c could be 2 or 3.

Even $a += 5 or $a++ are not guaranteed to be atomic.

Whenever your program accesses data or resources that can be accessed by other threads, you must take steps to coordinate access or risk data inconsistency and race conditions. Note that Perl will protect its internals from your race conditions, but it won't protect you from you.

Synchronization and control

Perl provides a number of mechanisms to coordinate the interactions between themselves and their data, to avoid race conditions and the like. Some of these are designed to resemble the common techniques used in thread libraries such as pthreads; others are Perl-specific. Often, the standard techniques are clumsy and difficult to get right (such as condition waits). Where possible, it is usually easier to use Perlish techniques such as queues, which remove some of the hard work involved.

Controlling access: lock()

The lock() function takes a shared variable and puts a lock on it. No other thread may lock the variable until the variable is unlocked by the thread holding the lock. Unlocking happens automatically when the locking thread exits the outermost block that contains lock() function. Using lock() is straightforward: this example has several threads doing some calculations in parallel, and occasionally updating a running total:

    use threads;
    use threads::shared;

    my $total : shared = 0;

    sub calc {
        for (;;) {
            my $result;
            # (... do some calculations and set $result ...)
            {
                lock($total); # block until we obtain the lock
                $total += $result;
            } # lock implicitly released at end of scope
            last if $result == 0;
        }
    }

    my $thr1 = threads->new(\&calc);
    my $thr2 = threads->new(\&calc);
    my $thr3 = threads->new(\&calc);
    $thr1->join;
    $thr2->join;
    $thr3->join;
    print "total=$total\n";

lock() blocks the thread until the variable being locked is available. When lock() returns, your thread can be sure that no other thread can lock that variable until the outermost block containing the lock exits.

It's important to note that locks don't prevent access to the variable in question, only lock attempts. This is in keeping with Perl's longstanding tradition of courteous programming, and the advisory file locking that flock() gives you.

You may lock arrays and hashes as well as scalars. Locking an array, though, will not block subsequent locks on array elements, just lock attempts on the array itself.

Locks are recursive, which means it's okay for a thread to lock a variable more than once. The lock will last until the outermost lock() on the variable goes out of scope. For example:

    my $x : shared;
    doit();

    sub doit {
        {
            {
                lock($x); # wait for lock
                lock($x); # NOOP - we already have the lock
                {
                    lock($x); # NOOP
                    {
                        lock($x); # NOOP
                        lockit_some_more();
                    }
                }
            } # *** implicit unlock here ***
        }
    }

    sub lockit_some_more {
        lock($x); # NOOP
    } # nothing happens here

Note that there is no unlock() function - the only way to unlock a variable is to allow it to go out of scope.

A lock can either be used to guard the data contained within the variable being locked, or it can be used to guard something else, like a section of code. In this latter case, the variable in question does not hold any useful data, and exists only for the purpose of being locked. In this respect, the variable behaves like the mutexes and basic semaphores of traditional thread libraries.

A Thread Pitfall: Deadlocks

Locks are a handy tool to synchronize access to data, and using them properly is the key to safe shared data. Unfortunately, locks aren't without their dangers, especially when multiple locks are involved. Consider the following code:

    use threads;

    my $a : shared = 4;
    my $b : shared = "foo";
    my $thr1 = threads->new(sub {
        lock($a);
        sleep 20;
        lock($b);
    });
    my $thr2 = threads->new(sub {
        lock($b);
        sleep 20;
        lock($a);
    });

This program will probably hang until you kill it. The only way it won't hang is if one of the two threads acquires both locks first. A guaranteed-to-hang version is more complicated, but the principle is the same.

The first thread will grab a lock on $a, then, after a pause during which the second thread has probably had time to do some work, try to grab a lock on $b. Meanwhile, the second thread grabs a lock on $b, then later tries to grab a lock on $a. The second lock attempt for both threads will block, each waiting for the other to release its lock.

This condition is called a deadlock, and it occurs whenever two or more threads are trying to get locks on resources that the others own. Each thread will block, waiting for the other to release a lock on a resource. That never happens, though, since the thread with the resource is itself waiting for a lock to be released.

There are a number of ways to handle this sort of problem. The best way is to always have all threads acquire locks in the exact same order. If, for example, you lock variables $a, $b, and $c, always lock $a before $b, and $b before $c. It's also best to hold on to locks for as short a period of time to minimize the risks of deadlock.

The other synchronization primitives described below can suffer from similar problems.

Queues: Passing Data Around

A queue is a special thread-safe object that lets you put data in one end and take it out the other without having to worry about synchronization issues. They're pretty straightforward, and look like this:

    use threads;
    use Thread::Queue;

    my $DataQueue = Thread::Queue->new;
    $thr = threads->new(sub {
        while ($DataElement = $DataQueue->dequeue) {
            print "Popped $DataElement off the queue\n";
        }
    });

    $DataQueue->enqueue(12);
    $DataQueue->enqueue("A", "B", "C");
    $DataQueue->enqueue(\$thr);
    sleep 10;
    $DataQueue->enqueue(undef);
    $thr->join;

You create the queue with new Thread::Queue. Then you can add lists of scalars onto the end with enqueue(), and pop scalars off the front of it with dequeue(). A queue has no fixed size, and can grow as needed to hold everything pushed on to it.

If a queue is empty, dequeue() blocks until another thread enqueues something. This makes queues ideal for event loops and other communications between threads.

Semaphores: Synchronizing Data Access

Semaphores are a kind of generic locking mechanism. In their most basic form, they behave very much like lockable scalars, except that they can't hold data, and that they must be explicitly unlocked. In their advanced form, they act like a kind of counter, and can allow multiple threads to have the 'lock' at any one time.

Basic semaphores

Semaphores have two methods, down() and up(): down() decrements the resource count, while up increments it. Calls to down() will block if the semaphore's current count would decrement below zero. This program gives a quick demonstration:

    use threads;
    use Thread::Semaphore;

    my $semaphore = new Thread::Semaphore;
    my $GlobalVariable : shared = 0;

    $thr1 = new threads \&sample_sub, 1;
    $thr2 = new threads \&sample_sub, 2;
    $thr3 = new threads \&sample_sub, 3;

    sub sample_sub {
        my $SubNumber = shift @_;
        my $TryCount = 10;
        my $LocalCopy;
        sleep 1;
        while ($TryCount--) {
            $semaphore->down;
            $LocalCopy = $GlobalVariable;
            print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n";
            sleep 2;
            $LocalCopy++;
            $GlobalVariable = $LocalCopy;
            $semaphore->up;
        }
    }

    $thr1->join;
    $thr2->join;
    $thr3->join;

The three invocations of the subroutine all operate in sync. The semaphore, though, makes sure that only one thread is accessing the global variable at once.

Advanced Semaphores

By default, semaphores behave like locks, letting only one thread down() them at a time. However, there are other uses for semaphores.

Each semaphore has a counter attached to it. By default, semaphores are created with the counter set to one, down() decrements the counter by one, and up() increments by one. However, we can override any or all of these defaults simply by passing in different values:

    use threads;
    use Thread::Semaphore;
    my $semaphore = Thread::Semaphore->new(5);
                    # Creates a semaphore with the counter set to five

    $thr1 = threads->new(\&sub1);
    $thr2 = threads->new(\&sub1);

    sub sub1 {
        $semaphore->down(5); # Decrements the counter by five
        # Do stuff here
        $semaphore->up(5); # Increment the counter by five
    }

    $thr1->detach;
    $thr2->detach;

If down() attempts to decrement the counter below zero, it blocks until the counter is large enough. Note that while a semaphore can be created with a starting count of zero, any up() or down() always changes the counter by at least one, and so $semaphore->down(0) is the same as $semaphore->down(1).

The question, of course, is why would you do something like this? Why create a semaphore with a starting count that's not one, or why decrement/increment it by more than one? The answer is resource availability. Many resources that you want to manage access for can be safely used by more than one thread at once.

For example, let's take a GUI driven program. It has a semaphore that it uses to synchronize access to the display, so only one thread is ever drawing at once. Handy, but of course you don't want any thread to start drawing until things are properly set up. In this case, you can create a semaphore with a counter set to zero, and up it when things are ready for drawing.

Semaphores with counters greater than one are also useful for establishing quotas. Say, for example, that you have a number of threads that can do I/O at once. You don't want all the threads reading or writing at once though, since that can potentially swamp your I/O channels, or deplete your process' quota of filehandles. You can use a semaphore initialized to the number of concurrent I/O requests (or open files) that you want at any one time, and have your threads quietly block and unblock themselves.

Larger increments or decrements are handy in those cases where a thread needs to check out or return a number of resources at once.

cond_wait() and cond_signal()

These two functions can be used in conjunction with locks to notify co-operating threads that a resource has become available. They are very similar in use to the functions found in pthreads. However for most purposes, queues are simpler to use and more intuitive. See the threads::shared manpage for more details.

Giving up control

There are times when you may find it useful to have a thread explicitly give up the CPU to another thread. You may be doing something processor-intensive and want to make sure that the user-interface thread gets called frequently. Regardless, there are times that you might want a thread to give up the processor.

Perl's threading package provides the yield() function that does this. yield() is pretty straightforward, and works like this:

    use threads;

    sub loop {
            my $thread = shift;
            my $foo = 50;
            while($foo--) { print "in thread $thread\n" }
            threads->yield;
            $foo = 50;
            while($foo--) { print "in thread $thread\n" }
    }

    my $thread1 = threads->new(\&loop, 'first');
    my $thread2 = threads->new(\&loop, 'second');
    my $thread3 = threads->new(\&loop, 'third');

It is important to remember that yield() is only a hint to give up the CPU, it depends on your hardware, OS and threading libraries what actually happens. On many operating systems, yield() is a no-op. Therefore it is important to note that one should not build the scheduling of the threads around yield() calls. It might work on your platform but it won't work on another platform.

General Thread Utility Routines

We've covered the workhorse parts of Perl's threading package, and with these tools you should be well on your way to writing threaded code and packages. There are a few useful little pieces that didn't really fit in anyplace else.

What Thread Am I In?

The threads->self class method provides your program with a way to get an object representing the thread it's currently in. You can use this object in the same way as the ones returned from thread creation.

Thread IDs

tid() is a thread object method that returns the thread ID of the thread the object represents. Thread IDs are integers, with the main thread in a program being 0. Currently Perl assigns a unique tid to every thread ever created in your program, assigning the first thread to be created a tid of 1, and increasing the tid by 1 for each new thread that's created.

Are These Threads The Same?

The equal() method takes two thread objects and returns true if the objects represent the same thread, and false if they don't.

Thread objects also have an overloaded == comparison so that you can do comparison on them as you would with normal objects.

What Threads Are Running?

threads->list returns a list of thread objects, one for each thread that's currently running and not detached. Handy for a number of things, including cleaning up at the end of your program:

    # Loop through all the threads
    foreach $thr (threads->list) {
        # Don't join the main thread or ourselves
        if ($thr->tid && !threads::equal($thr, threads->self)) {
            $thr->join;
        }
    }

If some threads have not finished running when the main Perl thread ends, Perl will warn you about it and die, since it is impossible for Perl to clean up itself while other threads are running

A Complete Example

Confused yet? It's time for an example program to show some of the things we've covered. This program finds prime numbers using threads.

    1  #!/usr/bin/perl -w
    2  # prime-pthread, courtesy of Tom Christiansen
    3
    4  use strict;
    5
    6  use threads;
    7  use Thread::Queue;
    8
    9  my $stream = new Thread::Queue;
    10 my $kid    = new threads(\&check_num, $stream, 2);
    11
    12 for my $i ( 3 .. 1000 ) {
    13     $stream->enqueue($i);
    14 }
    15
    16 $stream->enqueue(undef);
    17 $kid->join;
    18
    19 sub check_num {
    20     my ($upstream, $cur_prime) = @_;
    21     my $kid;
    22     my $downstream = new Thread::Queue;
    23     while (my $num = $upstream->dequeue) {
    24         next unless $num % $cur_prime;
    25         if ($kid) {
    26            $downstream->enqueue($num);
    27                  } else {
    28            print "Found prime $num\n";
    29                $kid = new threads(\&check_num, $downstream, $num);
    30         }
    31     }
    32     $downstream->enqueue(undef) if $kid;
    33     $kid->join           if $kid;
    34 }

This program uses the pipeline model to generate prime numbers. Each thread in the pipeline has an input queue that feeds numbers to be checked, a prime number that it's responsible for, and an output queue into which it funnels numbers that have failed the check. If the thread has a number that's failed its check and there's no child thread, then the thread must have found a new prime number. In that case, a new child thread is created for that prime and stuck on the end of the pipeline.

This probably sounds a bit more confusing than it really is, so let's go through this program piece by piece and see what it does. (For those of you who might be trying to remember exactly what a prime number is, it's a number that's only evenly divisible by itself and 1)

The bulk of the work is done by the check_num() subroutine, which takes a reference to its input queue and a prime number that it's responsible for. After pulling in the input queue and the prime that the subroutine's checking (line 20), we create a new queue (line 22) and reserve a scalar for the thread that we're likely to create later (line 21).

The while loop from lines 23 to line 31 grabs a scalar off the input queue and checks against the prime this thread is responsible for. Line 24 checks to see if there's a remainder when we modulo the number to be checked against our prime. If there is one, the number must not be evenly divisible by our prime, so we need to either pass it on to the next thread if we've created one (line 26) or create a new thread if we haven't.

The new thread creation is line 29. We pass on to it a reference to the queue we've created, and the prime number we've found.

Finally, once the loop terminates (because we got a 0 or undef in the queue, which serves as a note to die), we pass on the notice to our child and wait for it to exit if we've created a child (lines 32 and 37).

Meanwhile, back in the main thread, we create a queue (line 9) and the initial child thread (line 10), and pre-seed it with the first prime: 2. Then we queue all the numbers from 3 to 1000 for checking (lines 12-14), then queue a die notice (line 16) and wait for the first child thread to terminate (line 17). Because a child won't die until its child has died, we know that we're done once we return from the join.

That's how it works. It's pretty simple; as with many Perl programs, the explanation is much longer than the program.

Different implementations of threads

Some background on thread implementations from the operating system viewpoint. There are three basic categories of threads: user-mode threads, kernel threads, and multiprocessor kernel threads.

User-mode threads are threads that live entirely within a program and its libraries. In this model, the OS knows nothing about threads. As far as it's concerned, your process is just a process.

This is the easiest way to implement threads, and the way most OSes start. The big disadvantage is that, since the OS knows nothing about threads, if one thread blocks they all do. Typical blocking activities include most system calls, most I/O, and things like sleep().

Kernel threads are the next step in thread evolution. The OS knows about kernel threads, and makes allowances for them. The main difference between a kernel thread and a user-mode thread is blocking. With kernel threads, things that block a single thread don't block other threads. This is not the case with user-mode threads, where the kernel blocks at the process level and not the thread level.

This is a big step forward, and can give a threaded program quite a performance boost over non-threaded programs. Threads that block performing I/O, for example, won't block threads that are doing other things. Each process still has only one thread running at once, though, regardless of how many CPUs a system might have.

Since kernel threading can interrupt a thread at any time, they will uncover some of the implicit locking assumptions you may make in your program. For example, something as simple as $a = $a + 2 can behave unpredictably with kernel threads if $a is visible to other threads, as another thread may have changed $a between the time it was fetched on the right hand side and the time the new value is stored.

Multiprocessor kernel threads are the final step in thread support. With multiprocessor kernel threads on a machine with multiple CPUs, the OS may schedule two or more threads to run simultaneously on different CPUs.

This can give a serious performance boost to your threaded program, since more than one thread will be executing at the same time. As a tradeoff, though, any of those nagging synchronization issues that might not have shown with basic kernel threads will appear with a vengeance.

In addition to the different levels of OS involvement in threads, different OSes (and different thread implementations for a particular OS) allocate CPU cycles to threads in different ways.

Cooperative multitasking systems have running threads give up control if one of two things happen. If a thread calls a yield function, it gives up control. It also gives up control if the thread does something that would cause it to block, such as perform I/O. In a cooperative multitasking implementation, one thread can starve all the others for CPU time if it so chooses.

Preemptive multitasking systems interrupt threads at regular intervals while the system decides which thread should run next. In a preemptive multitasking system, one thread usually won't monopolize the CPU.

On some systems, there can be cooperative and preemptive threads running simultaneously. (Threads running with realtime priorities often behave cooperatively, for example, while threads running at normal priorities behave preemptively.)

Most modern operating systems support preemptive multitasking nowadays.

Performance considerations

The main thing to bear in mind when comparing ithreads to other threading models is the fact that for each new thread created, a complete copy of all the variables and data of the parent thread has to be taken. Thus thread creation can be quite expensive, both in terms of memory usage and time spent in creation. The ideal way to reduce these costs is to have a relatively short number of long-lived threads, all created fairly early on - before the base thread has accumulated too much data. Of course, this may not always be possible, so compromises have to be made. However, after a thread has been created, its performance and extra memory usage should be little different than ordinary code.

Also note that under the current implementation, shared variables use a little more memory and are a little slower than ordinary variables.

Process-scope Changes

Note that while threads themselves are separate execution threads and Perl data is thread-private unless explicitly shared, the threads can affect process-scope state, affecting all the threads.

The most common example of this is changing the current working directory using chdir(). One thread calls chdir(), and the working directory of all the threads changes.

Even more drastic example of a process-scope change is chroot(): the root directory of all the threads changes, and no thread can undo it (as opposed to chdir()).

Further examples of process-scope changes include umask() and changing uids/gids.

Thinking of mixing fork() and threads? Please lie down and wait until the feeling passes. Be aware that the semantics of fork() vary between platforms. For example, some UNIX systems copy all the current threads into the child process, while others only copy the thread that called fork(). You have been warned!

Similarly, mixing signals and threads should not be attempted. Implementations are platform-dependent, and even the POSIX semantics may not be what you expect (and Perl doesn't even give you the full POSIX API).

Thread-Safety of System Libraries

Whether various library calls are thread-safe is outside the control of Perl. Calls often suffering from not being thread-safe include: localtime(), gmtime(), get{gr,host,net,proto,serv,pw}*(), readdir(), rand(), and srand() -- in general, calls that depend on some global external state.

If the system Perl is compiled in has thread-safe variants of such calls, they will be used. Beyond that, Perl is at the mercy of the thread-safety or -unsafety of the calls. Please consult your C library call documentation.

On some platforms the thread-safe library interfaces may fail if the result buffer is too small (for example the user group databases may be rather large, and the reentrant interfaces may have to carry around a full snapshot of those databases). Perl will start with a small buffer, but keep retrying and growing the result buffer until the result fits. If this limitless growing sounds bad for security or memory consumption reasons you can recompile Perl with PERL_REENTRANT_MAXSIZE defined to the maximum number of bytes you will allow.

Conclusion

A complete thread tutorial could fill a book (and has, many times), but with what we've covered in this introduction, you should be well on your way to becoming a threaded Perl expert.

Bibliography

Here's a short bibliography courtesy of Jürgen Christoffel:

Introductory Texts

Birrell, Andrew D. An Introduction to Programming with Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report #35 online as http://gatekeeper.dec.com/pub/DEC/SRC/research-reports/abstracts/src-rr-035.html (highly recommended)

Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A Guide to Concurrency, Communication, and Multithreading. Prentice-Hall, 1996.

Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written introduction to threads).

Nelson, Greg (editor). Systems Programming with Modula-3. Prentice Hall, 1991, ISBN 0-13-590464-1.

Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell. Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1 (covers POSIX threads).

OS-Related References

Boykin, Joseph, David Kirschen, Alan Langerman, and Susan LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1.

Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, 1995, ISBN 0-13-219908-4 (great textbook).

Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4

Other References

Arnold, Ken and James Gosling. The Java Programming Language, 2nd ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.

comp.programming.threads FAQ, http://www.serpentine.com/~bos/threads-faq/

Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage Collection on Virtually Shared Memory Architectures" in Memory Management: Proc. of the International Workshop IWMM 92, St. Malo, France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer, 1992, ISBN 3540-55940-X (real-life thread applications).

Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002, http://www.perl.com/pub/a/2002/06/11/threads.html

Acknowledgements

Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua Pritikin, and Alan Burlison, for their help in reality-checking and polishing this article. Big thanks to Tom Christiansen for his rewrite of the prime number generator.

AUTHOR

Dan Sugalski <dan@sidhe.org

Slightly modified by Arthur Bergman to fit the new thread model/module.

Reworked slightly by Jörg Walter <jwalt@cpan.org to be more concise about thread-safety of perl code.

Rearranged slightly by Elizabeth Mattijsen <liz@dijkmat.nl to put less emphasis on yield().

Copyrights

The original version of this article originally appeared in The Perl Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.

For more information please see the threads manpage and the threads::shared manpage.


perlcompile - Introduction to the Perl Compiler-Translator

    • Layout
  • Using The Back Ends
    • The Cross Referencing Back End
    • The Decompiling Back End
    • The Lint Back End
    • The Simple C Back End
    • The Bytecode Back End
    • The Optimized C Back End
  • Module List for the Compiler Suite
  • KNOWN PROBLEMS
  • AUTHOR

NAME

perlcompile - Introduction to the Perl Compiler-Translator

DESCRIPTION

Perl has always had a compiler: your source is compiled into an internal form (a parse tree) which is then optimized before being run. Since version 5.005, Perl has shipped with a module capable of inspecting the optimized parse tree (B), and this has been used to write many useful utilities, including a module that lets you turn your Perl into C source code that can be compiled into a native executable.

The B module provides access to the parse tree, and other modules ("back ends") do things with the tree. Some write it out as bytecode, C source code, or a semi-human-readable text. Another traverses the parse tree to build a cross-reference of which subroutines, formats, and variables are used where. Another checks your code for dubious constructs. Yet another back end dumps the parse tree back out as Perl source, acting as a source code beautifier or deobfuscator.

Because its original purpose was to be a way to produce C code corresponding to a Perl program, and in turn a native executable, the B module and its associated back ends are known as "the compiler", even though they don't really compile anything. Different parts of the compiler are more accurately a "translator", or an "inspector", but people want Perl to have a "compiler option" not an "inspector gadget". What can you do?

This document covers the use of the Perl compiler: which modules it comprises, how to use the most important of the back end modules, what problems there are, and how to work around them.

Layout

The compiler back ends are in the B:: hierarchy, and the front-end (the module that you, the user of the compiler, will sometimes interact with) is the O module. Some back ends (e.g., B::C) have programs (e.g., perlcc) to hide the modules' complexity.

Here are the important back ends to know about, with their status expressed as a number from 0 (outline for later implementation) to 10 (if there's a bug in it, we're very surprised):

B::Bytecode

Stores the parse tree in a machine-independent format, suitable for later reloading through the ByteLoader module. Status: 5 (some things work, some things don't, some things are untested).

B::C

Creates a C source file containing code to rebuild the parse tree and resume the interpreter. Status: 6 (many things work adequately, including programs using Tk).

B::CC

Creates a C source file corresponding to the run time code path in the parse tree. This is the closest to a Perl-to-C translator there is, but the code it generates is almost incomprehensible because it translates the parse tree into a giant switch structure that manipulates Perl structures. Eventual goal is to reduce (given sufficient type information in the Perl program) some of the Perl data structure manipulations into manipulations of C-level ints, floats, etc. Status: 5 (some things work, including uncomplicated Tk examples).

B::Lint

Complains if it finds dubious constructs in your source code. Status: 6 (it works adequately, but only has a very limited number of areas that it checks).

B::Deparse

Recreates the Perl source, making an attempt to format it coherently. Status: 8 (it works nicely, but a few obscure things are missing).

B::Xref

Reports on the declaration and use of subroutines and variables. Status: 8 (it works nicely, but still has a few lingering bugs).

Using The Back Ends

The following sections describe how to use the various compiler back ends. They're presented roughly in order of maturity, so that the most stable and proven back ends are described first, and the most experimental and incomplete back ends are described last.

The O module automatically enabled the -c flag to Perl, which prevents Perl from executing your code once it has been compiled. This is why all the back ends print:

  myperlprogram syntax OK

before producing any other output.

The Cross Referencing Back End

The cross referencing back end (B::Xref) produces a report on your program, breaking down declarations and uses of subroutines and variables (and formats) by file and subroutine. For instance, here's part of the report from the pod2man program that comes with Perl:

  Subroutine clear_noremap
    Package (lexical)
      $ready_to_print   i1069, 1079
    Package main
      $&                1086
      $.                1086
      $0                1086
      $1                1087
      $2                1085, 1085
      $3                1085, 1085
      $ARGV             1086
      %HTML_Escapes     1085, 1085

This shows the variables used in the subroutine clear_noremap. The variable $ready_to_print is a my() (lexical) variable, introduced (first declared with my()) on line 1069, and used on line 1079. The variable $& from the main package is used on 1086, and so on.

A line number may be prefixed by a single letter:

i

Lexical variable introduced (declared with my()) for the first time.

&

Subroutine or method call.

s

Subroutine defined.

r

Format defined.

The most useful option the cross referencer has is to save the report to a separate file. For instance, to save the report on myperlprogram to the file report:

  $ perl -MO=Xref,-oreport myperlprogram

The Decompiling Back End

The Deparse back end turns your Perl source back into Perl source. It can reformat along the way, making it useful as a de-obfuscator. The most basic way to use it is:

  $ perl -MO=Deparse myperlprogram

You'll notice immediately that Perl has no idea of how to paragraph your code. You'll have to separate chunks of code from each other with newlines by hand. However, watch what it will do with one-liners:

  $ perl -MO=Deparse -e '$op=shift||die "usage: $0
  code [...]";chomp(@ARGV=<>)unless@ARGV; for(@ARGV){$was=$_;eval$op;
  die$@ if$@; rename$was,$_ unless$was eq $_}'
  -e syntax OK
  $op = shift @ARGV || die("usage: $0 code [...]");
  chomp(@ARGV = <ARGV>) unless @ARGV;
  foreach $_ (@ARGV) {
      $was = $_;
      eval $op;
      die $@ if $@;
      rename $was, $_ unless $was eq $_;
  }

The decompiler has several options for the code it generates. For instance, you can set the size of each indent from 4 (as above) to 2 with:

  $ perl -MO=Deparse,-si2 myperlprogram

The -p option adds parentheses where normally they are omitted:

  $ perl -MO=Deparse -e 'print "Hello, world\n"'
  -e syntax OK
  print "Hello, world\n";
  $ perl -MO=Deparse,-p -e 'print "Hello, world\n"'
  -e syntax OK
  print("Hello, world\n");

See the B::Deparse manpage for more information on the formatting options.

The Lint Back End

The lint back end (B::Lint) inspects programs for poor style. One programmer's bad style is another programmer's useful tool, so options let you select what is complained about.

To run the style checker across your source code:

  $ perl -MO=Lint myperlprogram

To disable context checks and undefined subroutines:

  $ perl -MO=Lint,-context,-undefined-subs myperlprogram

See the B::Lint manpage for information on the options.

The Simple C Back End

This module saves the internal compiled state of your Perl program to a C source file, which can be turned into a native executable for that particular platform using a C compiler. The resulting program links against the Perl interpreter library, so it will not save you disk space (unless you build Perl with a shared library) or program size. It may, however, save you startup time.

The perlcc tool generates such executables by default.

  perlcc myperlprogram.pl

The Bytecode Back End

This back end is only useful if you also have a way to load and execute the bytecode that it produces. The ByteLoader module provides this functionality.

To turn a Perl program into executable byte code, you can use perlcc with the -B switch:

  perlcc -B myperlprogram.pl

The byte code is machine independent, so once you have a compiled module or program, it is as portable as Perl source (assuming that the user of the module or program has a modern-enough Perl interpreter to decode the byte code).

See B::Bytecode for information on options to control the optimization and nature of the code generated by the Bytecode module.

The Optimized C Back End

The optimized C back end will turn your Perl program's run time code-path into an equivalent (but optimized) C program that manipulates the Perl data structures directly. The program will still link against the Perl interpreter library, to allow for eval(), s///e, require, etc.

The perlcc tool generates such executables when using the -O switch. To compile a Perl program (ending in .pl or .p):

  perlcc -O myperlprogram.pl

To produce a shared library from a Perl module (ending in .pm):

  perlcc -O Myperlmodule.pm

For more information, see perlcc and the B::CC manpage.

Module List for the Compiler Suite

B

This module is the introspective ("reflective" in Java terms) module, which allows a Perl program to inspect its innards. The back end modules all use this module to gain access to the compiled parse tree. You, the user of a back end module, will not need to interact with B.

O

This module is the front-end to the compiler's back ends. Normally called something like this:

  $ perl -MO=Deparse myperlprogram

This is like saying use O 'Deparse' in your Perl program.

B::Asmdata

This module is used by the B::Assembler module, which is in turn used by the B::Bytecode module, which stores a parse-tree as bytecode for later loading. It's not a back end itself, but rather a component of a back end.

B::Assembler

This module turns a parse-tree into data suitable for storing and later decoding back into a parse-tree. It's not a back end itself, but rather a component of a back end. It's used by the assemble program that produces bytecode.

B::Bblock

This module is used by the B::CC back end. It walks "basic blocks". A basic block is a series of operations which is known to execute from start to finish, with no possibility of branching or halting.

B::Bytecode

This module is a back end that generates bytecode from a program's parse tree. This bytecode is written to a file, from where it can later be reconstructed back into a parse tree. The goal is to do the expensive program compilation once, save the interpreter's state into a file, and then restore the state from the file when the program is to be executed. See The Bytecode Back End for details about usage.

B::C

This module writes out C code corresponding to the parse tree and other interpreter internal structures. You compile the corresponding C file, and get an executable file that will restore the internal structures and the Perl interpreter will begin running the program. See The Simple C Back End for details about usage.

B::CC

This module writes out C code corresponding to your program's operations. Unlike the B::C module, which merely stores the interpreter and its state in a C program, the B::CC module makes a C program that does not involve the interpreter. As a consequence, programs translated into C by B::CC can execute faster than normal interpreted programs. See The Optimized C Back End for details about usage.

B::Concise

This module prints a concise (but complete) version of the Perl parse tree. Its output is more customizable than the one of B::Terse or B::Debug (and it can emulate them). This module useful for people who are writing their own back end, or who are learning about the Perl internals. It's not useful to the average programmer.

B::Debug

This module dumps the Perl parse tree in verbose detail to STDOUT. It's useful for people who are writing their own back end, or who are learning about the Perl internals. It's not useful to the average programmer.

B::Deparse

This module produces Perl source code from the compiled parse tree. It is useful in debugging and deconstructing other people's code, also as a pretty-printer for your own source. See The Decompiling Back End for details about usage.

B::Disassembler

This module turns bytecode back into a parse tree. It's not a back end itself, but rather a component of a back end. It's used by the disassemble program that comes with the bytecode.

B::Lint

This module inspects the compiled form of your source code for things which, while some people frown on them, aren't necessarily bad enough to justify a warning. For instance, use of an array in scalar context without explicitly saying scalar(@array) is something that Lint can identify. See The Lint Back End for details about usage.

B::Showlex

This module prints out the my() variables used in a function or a file. To get a list of the my() variables used in the subroutine mysub() defined in the file myperlprogram:

  $ perl -MO=Showlex,mysub myperlprogram

To get a list of the my() variables used in the file myperlprogram:

  $ perl -MO=Showlex myperlprogram

[BROKEN]

B::Stackobj

This module is used by the B::CC module. It's not a back end itself, but rather a component of a back end.

B::Stash

This module is used by the perlcc program, which compiles a module into an executable. B::Stash prints the symbol tables in use by a program, and is used to prevent B::CC from producing C code for the B::* and O modules. It's not a back end itself, but rather a component of a back end.

B::Terse

This module prints the contents of the parse tree, but without as much information as B::Debug. For comparison, print "Hello, world." produced 96 lines of output from B::Debug, but only 6 from B::Terse.

This module is useful for people who are writing their own back end, or who are learning about the Perl internals. It's not useful to the average programmer.

B::Xref

This module prints a report on where the variables, subroutines, and formats are defined and used within a program and the modules it loads. See The Cross Referencing Back End for details about usage.

KNOWN PROBLEMS

The simple C backend currently only saves typeglobs with alphanumeric names.

The optimized C backend outputs code for more modules than it should (e.g., DirHandle). It also has little hope of properly handling goto LABEL outside the running subroutine (goto &sub is okay). goto LABEL currently does not work at all in this backend. It also creates a huge initialization function that gives C compilers headaches. Splitting the initialization function gives better results. Other problems include: unsigned math does not work correctly; some opcodes are handled incorrectly by default opcode handling mechanism.

BEGIN{} blocks are executed while compiling your code. Any external state that is initialized in BEGIN{}, such as opening files, initiating database connections etc., do not behave properly. To work around this, Perl has an INIT{} block that corresponds to code being executed before your program begins running but after your program has finished being compiled. Execution order: BEGIN{}, (possible save of state through compiler back-end), INIT{}, program runs, END{}.

AUTHOR

This document was originally written by Nathan Torkington, and is now maintained by the perl5-porters mailing list perl5-porters@perl.org.


perldbmfilter - Perl DBM Filters

    • The Filter
    • An Example - the NULL termination problem.
    • Another Example - Key is a C int.
  • SEE ALSO
  • AUTHOR

NAME

perldbmfilter - Perl DBM Filters

SYNOPSIS

    $db = tie %hash, 'DBM', ...
    $old_filter = $db->filter_store_key  ( sub { ... } );
    $old_filter = $db->filter_store_value( sub { ... } );
    $old_filter = $db->filter_fetch_key  ( sub { ... } );
    $old_filter = $db->filter_fetch_value( sub { ... } );

DESCRIPTION

The four filter_* methods shown above are available in all the DBM modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File, ODBM_File and SDBM_File.

Each of the methods work identically, and are used to install (or uninstall) a single DBM Filter. The only difference between them is the place that the filter is installed.

To summarise:

filter_store_key

If a filter has been installed with this method, it will be invoked every time you write a key to a DBM database.

filter_store_value

If a filter has been installed with this method, it will be invoked every time you write a value to a DBM database.

filter_fetch_key

If a filter has been installed with this method, it will be invoked every time you read a key from a DBM database.

filter_fetch_value

If a filter has been installed with this method, it will be invoked every time you read a value from a DBM database.

You can use any combination of the methods from none to all four.

All filter methods return the existing filter, if present, or undef in not.

To delete a filter pass undef to it.

The Filter

When each filter is called by Perl, a local copy of $_ will contain the key or value to be filtered. Filtering is achieved by modifying the contents of $_. The return code from the filter is ignored.

An Example -- the NULL termination problem.

DBM Filters are useful for a class of problems where you always want to make the same transformation to all keys, all values or both.

For example, consider the following scenario. You have a DBM database that you need to share with a third-party C application. The C application assumes that all keys and values are NULL terminated. Unfortunately when Perl writes to DBM databases it doesn't use NULL termination, so your Perl application will have to manage NULL termination itself. When you write to the database you will have to use something like this:

    $hash{"$key\0"} = "$value\0";

Similarly the NULL needs to be taken into account when you are considering the length of existing keys/values.

It would be much better if you could ignore the NULL terminations issue in the main application code and have a mechanism that automatically added the terminating NULL to all keys and values whenever you write to the database and have them removed when you read from the database. As I'm sure you have already guessed, this is a problem that DBM Filters can fix very easily.

    use strict;
    use warnings;
    use SDBM_File;
    use Fcntl;

    my %hash;
    my $filename = "filt";
    unlink $filename;

    my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
      or die "Cannot open $filename: $!\n";

    # Install DBM Filters
    $db->filter_fetch_key  ( sub { s/\0$//    } );
    $db->filter_store_key  ( sub { $_ .= "\0" } );
    $db->filter_fetch_value(
        sub { no warnings 'uninitialized'; s/\0$// } );
    $db->filter_store_value( sub { $_ .= "\0" } );

    $hash{"abc"} = "def";
    my $a = $hash{"ABC"};
    # ...
    undef $db;
    untie %hash;

The code above uses SDBM_File, but it will work with any of the DBM modules.

Hopefully the contents of each of the filters should be self-explanatory. Both "fetch" filters remove the terminating NULL, and both "store" filters add a terminating NULL.

Another Example -- Key is a C int.

Here is another real-life example. By default, whenever Perl writes to a DBM database it always writes the key and value as strings. So when you use this:

    $hash{12345} = "something";

the key 12345 will get stored in the DBM database as the 5 byte string "12345". If you actually want the key to be stored in the DBM database as a C int, you will have to use pack when writing, and unpack when reading.

Here is a DBM Filter that does it:

    use strict;
    use warnings;
    use DB_File;
    my %hash;
    my $filename = "filt";
    unlink $filename;

    my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
      or die "Cannot open $filename: $!\n";

    $db->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
    $db->filter_store_key  ( sub { $_ = pack ("i", $_) } );
    $hash{123} = "def";
    # ...
    undef $db;
    untie %hash;

The code above uses DB_File, but again it will work with any of the DBM modules.

This time only two filters have been used -- we only need to manipulate the contents of the key, so it wasn't necessary to install any value filters.

SEE ALSO

DB_File, GDBM_File, the NDBM_File manpage, ODBM_File and the SDBM_File manpage.

AUTHOR

Paul Marquess


perlfilter - Source Filters

  • CONCEPTS
  • USING FILTERS
  • WRITING A SOURCE FILTER
  • WRITING A SOURCE FILTER IN C
  • CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
  • WRITING A SOURCE FILTER IN PERL
  • USING CONTEXT: THE DEBUG FILTER
  • CONCLUSION
  • THINGS TO LOOK OUT FOR
  • REQUIREMENTS
  • AUTHOR
  • Copyrights

NAME

perlfilter - Source Filters

DESCRIPTION

This article is about a little-known feature of Perl called source filters. Source filters alter the program text of a module before Perl sees it, much as a C preprocessor alters the source text of a C program before the compiler sees it. This article tells you more about what source filters are, how they work, and how to write your own.

The original purpose of source filters was to let you encrypt your program source to prevent casual piracy. This isn't all they can do, as you'll soon learn. But first, the basics.

CONCEPTS

Before the Perl interpreter can execute a Perl script, it must first read it from a file into memory for parsing and compilation. If that script itself includes other scripts with a use or require statement, then each of those scripts will have to be read from their respective files as well.

Now think of each logical connection between the Perl parser and an individual file as a source stream. A source stream is created when the Perl parser opens a file, it continues to exist as the source code is read into memory, and it is destroyed when Perl is finished parsing the file. If the parser encounters a require or use statement in a source stream, a new and distinct stream is created just for that file.

The diagram below represents a single source stream, with the flow of source from a Perl script file on the left into the Perl parser on the right. This is how Perl normally operates.

    file -------> parser

There are two important points to remember:

  1. Although there can be any number of source streams in existence at any given time, only one will be active.

  2. Every source stream is associated with only one file.

A source filter is a special kind of Perl module that intercepts and modifies a source stream before it reaches the parser. A source filter changes our diagram like this:

    file ----> filter ----> parser

If that doesn't make much sense, consider the analogy of a command pipeline. Say you have a shell script stored in the compressed file trial.gz. The simple pipeline command below runs the script without needing to create a temporary file to hold the uncompressed file.

    gunzip -c trial.gz | sh

In this case, the data flow from the pipeline can be represented as follows:

    trial.gz ----> gunzip ----> sh

With source filters, you can store the text of your script compressed and use a source filter to uncompress it for Perl's parser:

     compressed           gunzip
    Perl program ---> source filter ---> parser

USING FILTERS

So how do you use a source filter in a Perl script? Above, I said that a source filter is just a special kind of module. Like all Perl modules, a source filter is invoked with a use statement.

Say you want to pass your Perl source through the C preprocessor before execution. You could use the existing -P command line option to do this, but as it happens, the source filters distribution comes with a C preprocessor filter module called Filter::cpp. Let's use that instead.

Below is an example program, cpp_test, which makes use of this filter. Line numbers have been added to allow specific lines to be referenced easily.

    1: use Filter::cpp;
    2: #define TRUE 1
    3: $a = TRUE;
    4: print "a = $a\n";

When you execute this script, Perl creates a source stream for the file. Before the parser processes any of the lines from the file, the source stream looks like this:

    cpp_test ---------> parser

Line 1, use Filter::cpp, includes and installs the cpp filter module. All source filters work this way. The use statement is compiled and executed at compile time, before any more of the file is read, and it attaches the cpp filter to the source stream behind the scenes. Now the data flow looks like this:

    cpp_test ----> cpp filter ----> parser

As the parser reads the second and subsequent lines from the source stream, it feeds those lines through the cpp source filter before processing them. The cpp filter simply passes each line through the real C preprocessor. The output from the C preprocessor is then inserted back into the source stream by the filter.

                  .-> cpp --.
                  |         |
                  |         |
                  |       <-'
   cpp_test ----> cpp filter ----> parser

The parser then sees the following code:

    use Filter::cpp;
    $a = 1;
    print "a = $a\n";

Let's consider what happens when the filtered code includes another module with use:

    1: use Filter::cpp;
    2: #define TRUE 1
    3: use Fred;
    4: $a = TRUE;
    5: print "a = $a\n";

The cpp filter does not apply to the text of the Fred module, only to the text of the file that used it (cpp_test). Although the use statement on line 3 will pass through the cpp filter, the module that gets included (Fred) will not. The source streams look like this after line 3 has been parsed and before line 4 is parsed:

    cpp_test ---> cpp filter ---> parser (INACTIVE)
    Fred.pm ----> parser

As you can see, a new stream has been created for reading the source from Fred.pm. This stream will remain active until all of Fred.pm has been parsed. The source stream for cpp_test will still exist, but is inactive. Once the parser has finished reading Fred.pm, the source stream associated with it will be destroyed. The source stream for cpp_test then becomes active again and the parser reads line 4 and subsequent lines from cpp_test.

You can use more than one source filter on a single file. Similarly, you can reuse the same filter in as many files as you like.

For example, if you have a uuencoded and compressed source file, it is possible to stack a uudecode filter and an uncompression filter like this:

    use Filter::uudecode; use Filter::uncompress;
    M'XL(".H<US4''V9I;F%L')Q;>7/;1I;_>_I3=&E=%:F*I"T?22Q/
    M6]9*<IQCO*XFT"0[PL%%'Y+IG?WN^ZYN-$'J.[.JE$,20/?K=_[>
    ...

Once the first line has been processed, the flow will look like this:

    file ---> uudecode ---> uncompress ---> parser
               filter         filter

Data flows through filters in the same order they appear in the source file. The uudecode filter appeared before the uncompress filter, so the source file will be uudecoded before it's uncompressed.

WRITING A SOURCE FILTER

There are three ways to write your own source filter. You can write it in C, use an external program as a filter, or write the filter in Perl. I won't cover the first two in any great detail, so I'll get them out of the way first. Writing the filter in Perl is most convenient, so I'll devote the most space to it.

WRITING A SOURCE FILTER IN C

The first of the three available techniques is to write the filter completely in C. The external module you create interfaces directly with the source filter hooks provided by Perl.

The advantage of this technique is that you have complete control over the implementation of your filter. The big disadvantage is the increased complexity required to write the filter - not only do you need to understand the source filter hooks, but you also need a reasonable knowledge of Perl guts. One of the few times it is worth going to this trouble is when writing a source scrambler. The decrypt filter (which unscrambles the source before Perl parses it) included with the source filter distribution is an example of a C source filter (see Decryption Filters, below).

Decryption Filters

All decryption filters work on the principle of "security through obscurity." Regardless of how well you write a decryption filter and how strong your encryption algorithm, anyone determined enough can retrieve the original source code. The reason is quite simple - once the decryption filter has decrypted the source back to its original form, fragments of it will be stored in the computer's memory as Perl parses it. The source might only be in memory for a short period of time, but anyone possessing a debugger, skill, and lots of patience can eventually reconstruct your program.

That said, there are a number of steps that can be taken to make life difficult for the potential cracker. The most important: Write your decryption filter in C and statically link the decryption module into the Perl binary. For further tips to make life difficult for the potential cracker, see the file decrypt.pm in the source filters module.

CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE

An alternative to writing the filter in C is to create a separate executable in the language of your choice. The separate executable reads from standard input, does whatever processing is necessary, and writes the filtered data to standard output. Filter:cpp is an example of a source filter implemented as a separate executable - the executable is the C preprocessor bundled with your C compiler.

The source filter distribution includes two modules that simplify this task: Filter::exec and Filter::sh. Both allow you to run any external executable. Both use a coprocess to control the flow of data into and out of the external executable. (For details on coprocesses, see Stephens, W.R. "Advanced Programming in the UNIX Environment." Addison-Wesley, ISBN 0-210-56317-7, pages 441-445.) The difference between them is that Filter::exec spawns the external command directly, while Filter::sh spawns a shell to execute the external command. (Unix uses the Bourne shell; NT uses the cmd shell.) Spawning a shell allows you to make use of the shell metacharacters and redirection facilities.

Here is an example script that uses Filter::sh:

    use Filter::sh 'tr XYZ PQR';
    $a = 1;
    print "XYZ a = $a\n";

The output you'll get when the script is executed:

    PQR a = 1

Writing a source filter as a separate executable works fine, but a small performance penalty is incurred. For example, if you execute the small example above, a separate subprocess will be created to run the Unix tr command. Each use of the filter requires its own subprocess. If creating subprocesses is expensive on your system, you might want to consider one of the other options for creating source filters.

WRITING A SOURCE FILTER IN PERL

The easiest and most portable option available for creating your own source filter is to write it completely in Perl. To distinguish this from the previous two techniques, I'll call it a Perl source filter.

To help understand how to write a Perl source filter we need an example to study. Here is a complete source filter that performs rot13 decoding. (Rot13 is a very simple encryption scheme used in Usenet postings to hide the contents of offensive posts. It moves every letter forward thirteen places, so that A becomes N, B becomes O, and Z becomes M.)

   package Rot13;

   use Filter::Util::Call;

   sub import {
      my ($type) = @_;
      my ($ref) = [];
      filter_add(bless $ref);
   }

   sub filter {
      my ($self) = @_;
      my ($status);

      tr/n-za-mN-ZA-M/a-zA-Z/
         if ($status = filter_read()) > 0;
      $status;
         }

   1;

All Perl source filters are implemented as Perl classes and have the same basic structure as the example above.

First, we include the Filter::Util::Call module, which exports a number of functions into your filter's namespace. The filter shown above uses two of these functions, filter_add() and filter_read().

Next, we create the filter object and associate it with the source stream by defining the import function. If you know Perl well enough, you know that import is called automatically every time a module is included with a use statement. This makes import the ideal place to both create and install a filter object.

In the example filter, the object ($ref) is blessed just like any other Perl object. Our example uses an anonymous array, but this isn't a requirement. Because this example doesn't need to store any context information, we could have used a scalar or hash reference just as well. The next section demonstrates context data.

The association between the filter object and the source stream is made with the filter_add() function. This takes a filter object as a parameter ($ref in this case) and installs it in the source stream.

Finally, there is the code that actually does the filtering. For this type of Perl source filter, all the filtering is done in a method called filter(). (It is also possible to write a Perl source filter using a closure. See the Filter::Util::Call manual page for more details.) It's called every time the Perl parser needs another line of source to process. The filter() method, in turn, reads lines from the source stream using the filter_read() function.

If a line was available from the source stream, filter_read() returns a status value greater than zero and appends the line to $_. A status value of zero indicates end-of-file, less than zero means an error. The filter function itself is expected to return its status in the same way, and put the filtered line it wants written to the source stream in $_. The use of $_ accounts for the brevity of most Perl source filters.

In order to make use of the rot13 filter we need some way of encoding the source file in rot13 format. The script below, mkrot13, does just that.

    die "usage mkrot13 filename\n" unless @ARGV;
    my $in = $ARGV[0];
    my $out = "$in.tmp";
    open(IN, "<$in") or die "Cannot open file $in: $!\n";
    open(OUT, ">$out") or die "Cannot open file $out: $!\n";

    print OUT "use Rot13;\n";
    while (<IN>) {
       tr/a-zA-Z/n-za-mN-ZA-M/;
       print OUT;
    }

    close IN;
    close OUT;
    unlink $in;
    rename $out, $in;

If we encrypt this with mkrot13:

    print " hello fred \n";

the result will be this:

    use Rot13;
    cevag "uryyb serq\a";

Running it produces this output:

    hello fred

USING CONTEXT: THE DEBUG FILTER

The rot13 example was a trivial example. Here's another demonstration that shows off a few more features.

Say you wanted to include a lot of debugging code in your Perl script during development, but you didn't want it available in the released product. Source filters offer a solution. In order to keep the example simple, let's say you wanted the debugging output to be controlled by an environment variable, DEBUG. Debugging code is enabled if the variable exists, otherwise it is disabled.

Two special marker lines will bracket debugging code, like this:

    ## DEBUG_BEGIN
    if ($year > 1999) {
       warn "Debug: millennium bug in year $year\n";
    }
    ## DEBUG_END

When the DEBUG environment variable exists, the filter ensures that Perl parses only the code between the DEBUG_BEGIN and DEBUG_END markers. That means that when DEBUG does exist, the code above should be passed through the filter unchanged. The marker lines can also be passed through as-is, because the Perl parser will see them as comment lines. When DEBUG isn't set, we need a way to disable the debug code. A simple way to achieve that is to convert the lines between the two markers into comments:

    ## DEBUG_BEGIN
    #if ($year > 1999) {
    #     warn "Debug: millennium bug in year $year\n";
    #}
    ## DEBUG_END

Here is the complete Debug filter:

    package Debug;

    use strict;
    use warnings;
    use Filter::Util::Call;

    use constant TRUE => 1;
    use constant FALSE => 0;

    sub import {
       my ($type) = @_;
       my (%context) = (
         Enabled => defined $ENV{DEBUG},
         InTraceBlock => FALSE,
         Filename => (caller)[1],
         LineNo => 0,
         LastBegin => 0,
       );
       filter_add(bless \%context);
    }

    sub Die {
       my ($self) = shift;
       my ($message) = shift;
       my ($line_no) = shift || $self->{LastBegin};
       die "$message at $self->{Filename} line $line_no.\n"
    }

    sub filter {
       my ($self) = @_;
       my ($status);
       $status = filter_read();
       ++ $self->{LineNo};

       # deal with EOF/error first
       if ($status <= 0) {
           $self->Die("DEBUG_BEGIN has no DEBUG_END")
               if $self->{InTraceBlock};
           return $status;
       }

       if ($self->{InTraceBlock}) {
          if (/^\s*##\s*DEBUG_BEGIN/ ) {
              $self->Die("Nested DEBUG_BEGIN", $self->{LineNo})
          } elsif (/^\s*##\s*DEBUG_END/) {
              $self->{InTraceBlock} = FALSE;
          }

          # comment out the debug lines when the filter is disabled
          s/^/#/ if ! $self->{Enabled};
                 } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
          $self->{InTraceBlock} = TRUE;
          $self->{LastBegin} = $self->{LineNo};
                 } elsif ( /^\s*##\s*DEBUG_END/ ) {
          $self->Die("DEBUG_END has no DEBUG_BEGIN", $self->{LineNo});
                 }
                 return $status;
              }

    1;

The big difference between this filter and the previous example is the use of context data in the filter object. The filter object is based on a hash reference, and is used to keep various pieces of context information between calls to the filter function. All but two of the hash fields are used for error reporting. The first of those two, Enabled, is used by the filter to determine whether the debugging code should be given to the Perl parser. The second, InTraceBlock, is true when the filter has encountered a DEBUG_BEGIN line, but has not yet encountered the following DEBUG_END line.

If you ignore all the error checking that most of the code does, the essence of the filter is as follows:

    sub filter {
       my ($self) = @_;
       my ($status);
       $status = filter_read();

       # deal with EOF/error first
       return $status if $status <= 0;
       if ($self->{InTraceBlock}) {
          if (/^\s*##\s*DEBUG_END/) {
             $self->{InTraceBlock} = FALSE
          }

          # comment out debug lines when the filter is disabled
          s/^/#/ if ! $self->{Enabled};
                 } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
          $self->{InTraceBlock} = TRUE;
                 }
                 return $status;
              }

Be warned: just as the C-preprocessor doesn't know C, the Debug filter doesn't know Perl. It can be fooled quite easily:

    print <<EOM;
    ##DEBUG_BEGIN
    EOM

Such things aside, you can see that a lot can be achieved with a modest amount of code.

CONCLUSION

You now have better understanding of what a source filter is, and you might even have a possible use for them. If you feel like playing with source filters but need a bit of inspiration, here are some extra features you could add to the Debug filter.

First, an easy one. Rather than having debugging code that is all-or-nothing, it would be much more useful to be able to control which specific blocks of debugging code get included. Try extending the syntax for debug blocks to allow each to be identified. The contents of the DEBUG environment variable can then be used to control which blocks get included.

Once you can identify individual blocks, try allowing them to be nested. That isn't difficult either.

Here is an interesting idea that doesn't involve the Debug filter. Currently Perl subroutines have fairly limited support for formal parameter lists. You can specify the number of parameters and their type, but you still have to manually take them out of the @_ array yourself. Write a source filter that allows you to have a named parameter list. Such a filter would turn this:

    sub MySub ($first, $second, @rest) { ... }

into this:

    sub MySub($$@) {
       my ($first) = shift;
       my ($second) = shift;
       my (@rest) = @_;
       ...
    }

Finally, if you feel like a real challenge, have a go at writing a full-blown Perl macro preprocessor as a source filter. Borrow the useful features from the C preprocessor and any other macro processors you know. The tricky bit will be choosing how much knowledge of Perl's syntax you want your filter to have.

THINGS TO LOOK OUT FOR

Some Filters Clobber the DATA Handle

Some source filters use the DATA handle to read the calling program. When using these source filters you cannot rely on this handle, nor expect any particular kind of behavior when operating on it. Filters based on Filter::Util::Call (and therefore Filter::Simple) do not alter the DATA filehandle.

REQUIREMENTS

The Source Filters distribution is available on CPAN, in

    CPAN/modules/by-module/Filter

Starting from Perl 5.8 Filter::Util::Call (the core part of the Source Filters distribution) is part of the standard Perl distribution. Also included is a friendlier interface called Filter::Simple, by Damian Conway.

AUTHOR

Paul Marquess <Paul.Marquess@btinternet.com>

Copyrights

This article originally appeared in The Perl Journal #11, and is copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.


perlfork - Perl's fork emulation

    • Behavior of other Perl features in forked pseudo-processes
    • Resource limits
    • Killing the parent process
    • Lifetime of the parent process and pseudo-processes
    • CAVEATS AND LIMITATIONS
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

perlfork - Perl's fork() emulation

SYNOPSIS

    NOTE:  As of the 5.8.0 release, fork() emulation has considerably
    matured.  However, there are still a few known bugs and differences
    from real fork() that might affect you.  See the "BUGS" and
    "CAVEATS AND LIMITATIONS" sections below.

Perl provides a fork() keyword that corresponds to the Unix system call of the same name. On most Unix-like platforms where the fork() system call is available, Perl's fork() simply calls it.

On some platforms such as Windows where the fork() system call is not available, Perl can be built to emulate fork() at the interpreter level. While the emulation is designed to be as compatible as possible with the real fork() at the level of the Perl program, there are certain important differences that stem from the fact that all the pseudo child "processes" created this way live in the same real process as far as the operating system is concerned.

This document provides a general overview of the capabilities and limitations of the fork() emulation. Note that the issues discussed here are not applicable to platforms where a real fork() is available and Perl has been configured to use it.

DESCRIPTION

The fork() emulation is implemented at the level of the Perl interpreter. What this means in general is that running fork() will actually clone the running interpreter and all its state, and run the cloned interpreter in a separate thread, beginning execution in the new thread just after the point where the fork() was called in the parent. We will refer to the thread that implements this child "process" as the pseudo-process.

To the Perl program that called fork(), all this is designed to be transparent. The parent returns from the fork() with a pseudo-process ID that can be subsequently used in any process manipulation functions; the child returns from the fork() with a value of 0 to signify that it is the child pseudo-process.

Behavior of other Perl features in forked pseudo-processes

Most Perl features behave in a natural way within pseudo-processes.

$$ or $PROCESS_ID

This special variable is correctly set to the pseudo-process ID. It can be used to identify pseudo-processes within a particular session. Note that this value is subject to recycling if any pseudo-processes are launched after others have been wait()-ed on.

%ENV

Each pseudo-process maintains its own virtual environment. Modifications to %ENV affect the virtual environment, and are only visible within that pseudo-process, and in any processes (or pseudo-processes) launched from it.

chdir() and all other builtins that accept filenames

Each pseudo-process maintains its own virtual idea of the current directory. Modifications to the current directory using chdir() are only visible within that pseudo-process, and in any processes (or pseudo-processes) launched from it. All file and directory accesses from the pseudo-process will correctly map the virtual working directory to the real working directory appropriately.

wait() and waitpid()

wait() and waitpid() can be passed a pseudo-process ID returned by fork(). These calls will properly wait for the termination of the pseudo-process and return its status.

kill()

kill() can be used to terminate a pseudo-process by passing it the ID returned by fork(). This should not be used except under dire circumstances, because the operating system may not guarantee integrity of the process resources when a running thread is terminated. Note that using kill() on a pseudo-process() may typically cause memory leaks, because the thread that implements the pseudo-process does not get a chance to clean up its resources.

exec()

Calling exec() within a pseudo-process actually spawns the requested executable in a separate process and waits for it to complete before exiting with the same exit status as that process. This means that the process ID reported within the running executable will be different from what the earlier Perl fork() might have returned. Similarly, any process manipulation functions applied to the ID returned by fork() will affect the waiting pseudo-process that called exec(), not the real process it is waiting for after the exec().

exit()

exit() always exits just the executing pseudo-process, after automatically wait()-ing for any outstanding child pseudo-processes. Note that this means that the process as a whole will not exit unless all running pseudo-processes have exited.

Open handles to files, directories and network sockets

All open handles are dup()-ed in pseudo-processes, so that closing any handles in one process does not affect the others. See below for some limitations.

Resource limits

In the eyes of the operating system, pseudo-processes created via the fork() emulation are simply threads in the same process. This means that any process-level limits imposed by the operating system apply to all pseudo-processes taken together. This includes any limits imposed by the operating system on the number of open file, directory and socket handles, limits on disk space usage, limits on memory size, limits on CPU utilization etc.

Killing the parent process

If the parent process is killed (either using Perl's kill() builtin, or using some external means) all the pseudo-processes are killed as well, and the whole process exits.

Lifetime of the parent process and pseudo-processes

During the normal course of events, the parent process and every pseudo-process started by it will wait for their respective pseudo-children to complete before they exit. This means that the parent and every pseudo-child created by it that is also a pseudo-parent will only exit after their pseudo-children have exited.

A way to mark a pseudo-processes as running detached from their parent (so that the parent would not have to wait() for them if it doesn't want to) will be provided in future.

CAVEATS AND LIMITATIONS

BEGIN blocks

The fork() emulation will not work entirely correctly when called from within a BEGIN block. The forked copy will run the contents of the BEGIN block, but will not continue parsing the source stream after the BEGIN block. For example, consider the following code:

    BEGIN {
        fork and exit;          # fork child and exit the parent
        print "inner\n";
    }
    print "outer\n";

This will print:

    inner

rather than the expected:

    inner
    outer

This limitation arises from fundamental technical difficulties in cloning and restarting the stacks used by the Perl parser in the middle of a parse.

Open filehandles

Any filehandles open at the time of the fork() will be dup()-ed. Thus, the files can be closed independently in the parent and child, but beware that the dup()-ed handles will still share the same seek pointer. Changing the seek position in the parent will change it in the child and vice-versa. One can avoid this by opening files that need distinct seek pointers separately in the child.

Forking pipe open() not yet implemented

The open(FOO, "|-") and open(BAR, "-|") constructs are not yet implemented. This limitation can be easily worked around in new code by creating a pipe explicitly. The following example shows how to write to a forked child:

    # simulate open(FOO, "|-")
    sub pipe_to_fork ($) {
        my $parent = shift;
        pipe my $child, $parent or die;
        my $pid = fork();
        die "fork() failed: $!" unless defined $pid;
        if ($pid) {
            close $child;
        }
        else {
            close $parent;
            open(STDIN, "<&=" . fileno($child)) or die;
        }
        $pid;
    }

    if (pipe_to_fork('FOO')) {
        # parent
        print FOO "pipe_to_fork\n";
        close FOO;
    }
    else {
        # child
        while (<STDIN>) { print; }
        exit(0);
    }

And this one reads from the child:

    # simulate open(FOO, "-|")
    sub pipe_from_fork ($) {
        my $parent = shift;
        pipe $parent, my $child or die;
        my $pid = fork();
        die "fork() failed: $!" unless defined $pid;
        if ($pid) {
            close $child;
        }
        else {
            close $parent;
            open(STDOUT, ">&=" . fileno($child)) or die;
        }
        $pid;
    }

    if (pipe_from_fork('BAR')) {
        # parent
        while (<BAR>) { print; }
        close BAR;
    }
    else {
        # child
        print "pipe_from_fork\n";
        exit(0);
    }

Forking pipe open() constructs will be supported in future.

Global state maintained by XSUBs

External subroutines (XSUBs) that maintain their own global state may not work correctly. Such XSUBs will either need to maintain locks to protect simultaneous access to global data from different pseudo-processes, or maintain all their state on the Perl symbol table, which is copied naturally when fork() is called. A callback mechanism that provides extensions an opportunity to clone their state will be provided in the near future.

Interpreter embedded in larger application

The fork() emulation may not behave as expected when it is executed in an application which embeds a Perl interpreter and calls Perl APIs that can evaluate bits of Perl code. This stems from the fact that the emulation only has knowledge about the Perl interpreter's own data structures and knows nothing about the containing application's state. For example, any state carried on the application's own call stack is out of reach.

Thread-safety of extensions

Since the fork() emulation runs code in multiple threads, extensions calling into non-thread-safe libraries may not work reliably when calling fork(). As Perl's threading support gradually becomes more widely adopted even on platforms with a native fork(), such extensions are expected to be fixed for thread-safety.

BUGS

  • Having pseudo-process IDs be negative integers breaks down for the integer -1 because the wait() and waitpid() functions treat this number as being special. The tacit assumption in the current implementation is that the system never allocates a thread ID of 1 for user threads. A better representation for pseudo-process IDs will be implemented in future.

  • In certain cases, the OS-level handles created by the pipe(), socket(), and accept() operators are apparently not duplicated accurately in pseudo-processes. This only happens in some situations, but where it does happen, it may result in deadlocks between the read and write ends of pipe handles, or inability to send or receive data across socket handles.

  • This document may be incomplete in some respects.

AUTHOR

Support for concurrent interpreters and the fork() emulation was implemented by ActiveState, with funding from Microsoft Corporation.

This document is authored and maintained by Gurusamy Sarathy <gsar@activestate.com>.

SEE ALSO

fork in the perlfunc manpage, the perlipc manpage


perlform - Perl formats

    • Text Fields
    • Numeric Fields
    • The Field @* for Variable Width Multi-Line Text
    • The Field ^* for Variable Width One-line-at-a-time Text
    • Specifying Values
    • Using Fill Mode
    • Suppressing Lines Where All Fields Are Void
    • Repeating Format Lines
    • Top of Form Processing
    • Format Variables
  • NOTES
    • Footers
    • Accessing Formatting Internals
  • WARNINGS

NAME

perlform - Perl formats

DESCRIPTION

Perl has a mechanism to help you generate simple reports and charts. To facilitate this, Perl helps you code up your output page close to how it will look when it's printed. It can keep track of things like how many lines are on a page, what page you're on, when to print page headers, etc. Keywords are borrowed from FORTRAN: format() to declare and write() to execute; see their entries in the perlfunc manpage. Fortunately, the layout is much more legible, more like BASIC's PRINT USING statement. Think of it as a poor man's nroff(1).

Formats, like packages and subroutines, are declared rather than executed, so they may occur at any point in your program. (Usually it's best to keep them all together though.) They have their own namespace apart from all the other "types" in Perl. This means that if you have a function named "Foo", it is not the same thing as having a format named "Foo". However, the default name for the format associated with a given filehandle is the same as the name of the filehandle. Thus, the default format for STDOUT is named "STDOUT", and the default format for filehandle TEMP is named "TEMP". They just look the same. They aren't.

Output record formats are declared as follows:

    format NAME =
    FORMLIST
    .

If the name is omitted, format "STDOUT" is defined. A single "." in column 1 is used to terminate a format. FORMLIST consists of a sequence of lines, each of which may be one of three types:

  1. A comment, indicated by putting a '#' in the first column.

  2. A "picture" line giving the format for one output line.

  3. An argument line supplying values to plug into the previous picture line.

Picture lines contain output field definitions, intermingled with literal text. These lines do not undergo any kind of variable interpolation. Field definitions are made up from a set of characters, for starting and extending a field to its desired width. This is the complete set of characters for field definitions: > > >>

   @    start of regular field
   ^    start of special field
   <    pad character for left adjustification
   |    pad character for centering
   >    pad character for right adjustificat
   #    pad character for a right justified numeric field
   0    instead of first #: pad number with leading zeroes
   .    decimal point within a numeric field
   ...  terminate a text field, show "..." as truncation evidence
   @*   variable width field for a multi-line value
   ^*   variable width field for next line of a multi-line value
   ~    suppress line with all fields empty
   ~~   repeat line until all fields are exhausted

Each field in a picture line starts with either "@" (at) or "^" (caret), indicating what we'll call, respectively, a "regular" or "special" field. The choice of pad characters determines whether a field is textual or numeric. The tilde operators are not part of a field. Let's look at the various possibilities in detail.

Text Fields

The length of the field is supplied by padding out the field with multiple "<", ">", or "|" characters to specify a non-numeric field with, respectively, left justification, right justification, or centering. For a regular field, the value (up to the first newline) is taken and printed according to the selected justification, truncating excess characters. If you terminate a text field with "...", three dots will be shown if the value is truncated. A special text field may be used to do rudimentary multi-line text block filling; see Using Fill Mode for details.

   Example:
      format STDOUT =
      @<<<<<<   @||||||   @>>>>>>
      "left",   "middle", "right"
      .
   Output:
      left      middle    right

Numeric Fields

Using "#" as a padding character specifies a numeric field, with right justification. An optional "." defines the position of the decimal point. With a "0" (zero) instead of the first "#", the formatted number will be padded with leading zeroes if necessary. A special numeric field is blanked out if the value is undefined. If the resulting value would exceed the width specified the field is filled with "#" as overflow evidence.

   Example:
      format STDOUT =
      @###   @.###   @##.###  @###   @###   ^####
       42,   3.1415,  undef,    0, 10000,   undef
      .
   Output:
        42   3.142     0.000     0   ####

The Field @* for Variable Width Multi-Line Text

The field "@*" can be used for printing multi-line, nontruncated values; it should (but need not) appear by itself on a line. A final line feed is chomped off, but all other characters are emitted verbatim.

The Field ^* for Variable Width One-line-at-a-time Text

Like "@*", this is a variable width field. The value supplied must be a scalar variable. Perl puts the first line (up to the first "\n") of the text into the field, and then chops off the front of the string so that the next time the variable is referenced, more of the text can be printed. The variable will not be restored.

   Example:
      $text = "line 1\nline 2\nline 3";
      format STDOUT =
      Text: ^*
            $text
      ~~    ^*
            $text
      .
   Output:
      Text: line 1
            line 2
            line 3

Specifying Values

The values are specified on the following format line in the same order as the picture fields. The expressions providing the values must be separated by commas. They are all evaluated in a list context before the line is processed, so a single list expression could produce multiple list elements. The expressions may be spread out to more than one line if enclosed in braces. If so, the opening brace must be the first token on the first line. If an expression evaluates to a number with a decimal part, and if the corresponding picture specifies that the decimal part should appear in the output (that is, any picture except multiple "#" characters without an embedded "."), the character used for the decimal point is always determined by the current LC_NUMERIC locale. This means that, if, for example, the run-time environment happens to specify a German locale, "," will be used instead of the default ".". See the perllocale manpage and WARNINGS for more information.

Using Fill Mode

On text fields the caret enables a kind of fill mode. Instead of an arbitrary expression, the value supplied must be a scalar variable that contains a text string. Perl puts the next portion of the text into the field, and then chops off the front of the string so that the next time the variable is referenced, more of the text can be printed. (Yes, this means that the variable itself is altered during execution of the write() call, and is not restored.) The next portion of text is determined by a crude line breaking algorithm. You may use the carriage return character (\r) to force a line break. You can change which characters are legal to break on by changing the variable $: (that's $FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a list of the desired characters.

Normally you would use a sequence of fields in a vertical stack associated with the same scalar variable to print out a block of text. You might wish to end the final field with the text "...", which will appear in the output if the text was too long to appear in its entirety.

Suppressing Lines Where All Fields Are Void

Using caret fields can produce lines where all fields are blank. You can suppress such lines by putting a "~" (tilde) character anywhere in the line. The tilde will be translated to a space upon output.

Repeating Format Lines

If you put two contiguous tilde characters "~~" anywhere into a line, the line will be repeated until all the fields on the line are exhausted, i.e. undefined. For special (caret) text fields this will occur sooner or later, but if you use a text field of the at variety, the expression you supply had better not give the same value every time forever! (shift(@f) is a simple example that would work.) Don't use a regular (at) numeric field in such lines, because it will never go blank.

Top of Form Processing

Top-of-form processing is by default handled by a format with the same name as the current filehandle with "_TOP" concatenated to it. It's triggered at the top of each page. See write in the perlfunc manpage.

Examples:

 # a report on the /etc/passwd file
 format STDOUT_TOP =
                         Passwd File
 Name                Login    Office   Uid   Gid Home
 ------------------------------------------------------------------
 .
 format STDOUT =
 @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
 $name,              $login,  $office,$uid,$gid, $home
 .
 # a report from a bug report form
 format STDOUT_TOP =
                         Bug Reports
 @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
 $system,                      $%,         $date
 ------------------------------------------------------------------
 .
 format STDOUT =
 Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
          $subject
 Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
        $index,                       $description
 Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
           $priority,        $date,   $description
 From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
       $from,                         $description
 Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
              $programmer,            $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                      $description
 ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
                                      $description
 .

It is possible to intermix print()s with write()s on the same output channel, but you'll have to handle $- ($FORMAT_LINES_LEFT) yourself.

Format Variables

The current format name is stored in the variable $~ ($FORMAT_NAME), and the current top of form format name is in $^ ($FORMAT_TOP_NAME). The current output page number is stored in $% ($FORMAT_PAGE_NUMBER), and the number of lines on the page is in $= ($FORMAT_LINES_PER_PAGE). Whether to autoflush output on this handle is stored in $| ($OUTPUT_AUTOFLUSH). The string output before each top of page (except the first) is stored in $^L ($FORMAT_FORMFEED). These variables are set on a per-filehandle basis, so you'll need to select() into a different one to affect them:

    select((select(OUTF),
            $~ = "My_Other_Format",
            $^ = "My_Top_Format"
           )[0]);

Pretty ugly, eh? It's a common idiom though, so don't be too surprised when you see it. You can at least use a temporary variable to hold the previous filehandle: (this is a much better approach in general, because not only does legibility improve, you now have intermediary stage in the expression to single-step the debugger through):

    $ofh = select(OUTF);
    $~ = "My_Other_Format";
    $^ = "My_Top_Format";
    select($ofh);

If you use the English module, you can even read the variable names:

    use English '-no_match_vars';
    $ofh = select(OUTF);
    $FORMAT_NAME     = "My_Other_Format";
    $FORMAT_TOP_NAME = "My_Top_Format";
    select($ofh);

But you still have those funny select()s. So just use the FileHandle module. Now, you can access these special variables using lowercase method names instead:

    use FileHandle;
    format_name     OUTF "My_Other_Format";
    format_top_name OUTF "My_Top_Format";

Much better!

NOTES

Because the values line may contain arbitrary expressions (for at fields, not caret fields), you can farm out more sophisticated processing to other functions, like sprintf() or one of your own. For example:

    format Ident =
        @<<<<<<<<<<<<<<<
        &commify($n)
    .

To get a real at or caret into the field, do this:

    format Ident =
    I have an @ here.
            "@"
    .

To center a whole line of text, do something like this:

    format Ident =
    @|||||||||||||||||||||||||||||||||||||||||||||||
            "Some text line"
    .

There is no builtin way to say "float this to the right hand side of the page, however wide it is." You have to specify where it goes. The truly desperate can generate their own format on the fly, based on the current number of columns, and then eval() it:

    $format  = "format STDOUT = \n"
             . '^' . '<' x $cols . "\n"
             . '$entry' . "\n"
             . "\t^" . "<" x ($cols-8) . "~~\n"
             . '$entry' . "\n"
             . ".\n";
    print $format if $Debugging;
    eval $format;
    die $@ if $@;

Which would generate a format looking something like this:

 format STDOUT =
 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 $entry
         ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
 $entry
 .

Here's a little program that's somewhat like fmt(1):

 format =
 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
 $_
 .
 $/ = '';
 while (<>) {
     s/\s*\n\s*/ /g;
     write;
 }

Footers

While $FORMAT_TOP_NAME contains the name of the current header format, there is no corresponding mechanism to automatically do the same thing for a footer. Not knowing how big a format is going to be until you evaluate it is one of the major problems. It's on the TODO list.

Here's one strategy: If you have a fixed-size footer, you can get footers by checking $FORMAT_LINES_LEFT before each write() and print the footer yourself if necessary.

Here's another strategy: Open a pipe to yourself, using open(MYSELF, "|-") (see open() in the perlfunc manpage) and always write() to MYSELF instead of STDOUT. Have your child process massage its STDIN to rearrange headers and footers however you like. Not very convenient, but doable.

Accessing Formatting Internals

For low-level access to the formatting mechanism. you may use formline() and access $^A (the $ACCUMULATOR variable) directly.

For example:

    $str = formline <<'END', 1,2,3;
    @<<<  @|||  @>>>
    END

    print "Wow, I just stored `$^A' in the accumulator!\n";

Or to make an swrite() subroutine, which is to write() what sprintf() is to printf(), do this:

    use Carp;
    sub swrite {
        croak "usage: swrite PICTURE ARGS" unless @_;
        my $format = shift;
        $^A = "";
        formline($format,@_);
        return $^A;
    }

    $string = swrite(<<'END', 1, 2, 3);
     Check me out
     @<<<  @|||  @>>>
     END
    print $string;

WARNINGS

The lone dot that ends a format can also prematurely end a mail message passing through a misconfigured Internet mailer (and based on experience, such misconfiguration is the rule, not the exception). So when sending format code through mail, you should indent it so that the format-ending dot is not on the left margin; this will prevent SMTP cutoff.

Lexical variables (declared with "my") are not visible within a format unless the format is declared within the scope of the lexical variable. (They weren't visible at all before version 5.001.)

Formats are the only part of Perl that unconditionally use information from a program's locale; if a program's environment specifies an LC_NUMERIC locale, it is always used to specify the decimal point character in formatted output. Perl ignores all other aspects of locale handling unless the use locale pragma is in effect. Formatted output cannot be controlled by use locale because the pragma is tied to the block structure of the program, and, for historical reasons, formats exist outside that block structure. See the perllocale manpage for further discussion of locale handling.

Within strings that are to be displayed in a fixed length text field, each control character is substituted by a space. (But remember the special meaning of \r when using fill mode.) This is done to avoid misalignment when control characters "disappear" on some output media.


perlipc - Perl interprocess communication

  • Signals
    • Handling the SIGHUP Signal in Daemons
  • Named Pipes
    • Deferred Signals (Safe Signals)
  • Using open() for IPC
    • Filehandles
    • Background Processes
    • Complete Dissociation of Child from Parent
    • Safe Pipe Opens
    • Bidirectional Communication with Another Process
    • Bidirectional Communication with Yourself
  • Sockets: Client/Server Communication
    • Internet Line Terminators
    • Internet TCP Clients and Servers
    • Unix-Domain TCP Clients and Servers
  • TCP Clients with IO::Socket
    • A Simple Client
    • A Webget Client
    • Interactive Client with IO::Socket
  • TCP Servers with IO::Socket
  • UDP: Message Passing
  • SysV IPC
  • NOTES
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)

DESCRIPTION

The basic IPC facilities of Perl are built out of the good old Unix signals, named pipes, pipe opens, the Berkeley socket routines, and SysV IPC calls. Each is used in slightly different situations.

Signals

Perl uses a simple signal handling model: the %SIG hash contains names or references of user-installed signal handlers. These handlers will be called with an argument which is the name of the signal that triggered it. A signal may be generated intentionally from a particular keyboard sequence like control-C or control-Z, sent to you from another process, or triggered automatically by the kernel when special events transpire, like a child process exiting, your process running out of stack space, or hitting file size limit.

For example, to trap an interrupt signal, set up a handler like this:

    sub catch_zap {
        my $signame = shift;
        $shucks++;
        die "Somebody sent me a SIG$signame";
    }
    $SIG{INT} = 'catch_zap';  # could fail in modules
    $SIG{INT} = \&catch_zap;  # best strategy

Prior to Perl 5.7.3 it was necessary to do as little as you possibly could in your handler; notice how all we do is set a global variable and then raise an exception. That's because on most systems, libraries are not re-entrant; particularly, memory allocation and I/O routines are not. That meant that doing nearly anything in your handler could in theory trigger a memory fault and subsequent core dump - see Deferred Signals (Safe Signals) below.

The names of the signals are the ones listed out by kill -l on your system, or you can retrieve them from the Config module. Set up an @signame list indexed by number to get the name and a %signo table indexed by name to get the number:

    use Config;
    defined $Config{sig_name} || die "No sigs?";
    foreach $name (split(' ', $Config{sig_name})) {
        $signo{$name} = $i;
        $signame[$i] = $name;
        $i++;
    }

So to check whether signal 17 and SIGALRM were the same, do just this:

    print "signal #17 = $signame[17]\n";
    if ($signo{ALRM}) {
        print "SIGALRM is $signo{ALRM}\n";
    }

You may also choose to assign the strings 'IGNORE' or 'DEFAULT' as the handler, in which case Perl will try to discard the signal or do the default thing.

On most Unix platforms, the CHLD (sometimes also known as CLD) signal has special behavior with respect to a value of 'IGNORE'. Setting $SIG{CHLD} to 'IGNORE' on such a platform has the effect of not creating zombie processes when the parent process fails to wait() on its child processes (i.e. child processes are automatically reaped). Calling wait() with $SIG{CHLD} set to 'IGNORE' usually returns -1 on such platforms.

Some signals can be neither trapped nor ignored, such as the KILL and STOP (but not the TSTP) signals. One strategy for temporarily ignoring signals is to use a local() statement, which will be automatically restored once your block is exited. (Remember that local() values are "inherited" by functions called from within that block.)

    sub precious {
        local $SIG{INT} = 'IGNORE';
        &more_functions;
    }
    sub more_functions {
        # interrupts still ignored, for now...
    }

Sending a signal to a negative process ID means that you send the signal to the entire Unix process-group. This code sends a hang-up signal to all processes in the current process group (and sets $SIG{HUP} to IGNORE so it doesn't kill itself):

    {
        local $SIG{HUP} = 'IGNORE';
        kill HUP => -$$;
        # snazzy writing of: kill('HUP', -$$)
    }

Another interesting signal to send is signal number zero. This doesn't actually affect a child process, but instead checks whether it's alive or has changed its UID.

    unless (kill 0 => $kid_pid) {
        warn "something wicked happened to $kid_pid";
    }

When directed at a process whose UID is not identical to that of the sending process, signal number zero may fail because you lack permission to send the signal, even though the process is alive. You may be able to determine the cause of failure using %!.

    unless (kill 0 => $pid or $!{EPERM}) {
        warn "$pid looks dead";
    }

You might also want to employ anonymous functions for simple signal handlers:

    $SIG{INT} = sub { die "\nOutta here!\n" };

But that will be problematic for the more complicated handlers that need to reinstall themselves. Because Perl's signal mechanism is currently based on the signal(3) function from the C library, you may sometimes be so misfortunate as to run on systems where that function is "broken", that is, it behaves in the old unreliable SysV way rather than the newer, more reasonable BSD and POSIX fashion. So you'll see defensive people writing signal handlers like this:

    sub REAPER {
        $waitedpid = wait;
        # loathe sysV: it makes us not only reinstate
        # the handler, but place it after the wait
        $SIG{CHLD} = \&REAPER;
    }
    $SIG{CHLD} = \&REAPER;
    # now do something that forks...

or better still:

    use POSIX ":sys_wait_h";
    sub REAPER {
        my $child;
        # If a second child dies while in the signal handler caused by the
        # first death, we won't get another signal. So must loop here else
        # we will leave the unreaped child as a zombie. And the next time
        # two children die we get another zombie. And so on.
        while (($child = waitpid(-1,WNOHANG)) > 0) {
            $Kid_Status{$child} = $?;
        }
        $SIG{CHLD} = \&REAPER;  # still loathe sysV
    }
    $SIG{CHLD} = \&REAPER;
    # do something that forks...

Signal handling is also used for timeouts in Unix, While safely protected within an eval{} block, you set a signal handler to trap alarm signals and then schedule to have one delivered to you in some number of seconds. Then try your blocking operation, clearing the alarm when it's done but not before you've exited your eval{} block. If it goes off, you'll use die() to jump out of the block, much as you might using longjmp() or throw() in other languages.

Here's an example:

    eval {
        local $SIG{ALRM} = sub { die "alarm clock restart" };
        alarm 10;
        flock(FH, 2);   # blocking write lock
        alarm 0;
    };
    if ($@ and $@ !~ /alarm clock restart/) { die }

If the operation being timed out is system() or qx(), this technique is liable to generate zombies. If this matters to you, you'll need to do your own fork() and exec(), and kill the errant child process.

For more complex signal handling, you might see the standard POSIX module. Lamentably, this is almost entirely undocumented, but the t/lib/posix.t file from the Perl source distribution has some examples in it.

Handling the SIGHUP Signal in Daemons

A process that usually starts when the system boots and shuts down when the system is shut down is called a daemon (Disk And Execution MONitor). If a daemon process has a configuration file which is modified after the process has been started, there should be a way to tell that process to re-read its configuration file, without stopping the process. Many daemons provide this mechanism using the SIGHUP signal handler. When you want to tell the daemon to re-read the file you simply send it the SIGHUP signal.

Not all platforms automatically reinstall their (native) signal handlers after a signal delivery. This means that the handler works only the first time the signal is sent. The solution to this problem is to use POSIX signal handlers if available, their behaviour is well-defined.

The following example implements a simple daemon, which restarts itself every time the SIGHUP signal is received. The actual code is located in the subroutine code(), which simply prints some debug info to show that it works and should be replaced with the real code.

  #!/usr/bin/perl -w

  use POSIX ();
  use FindBin ();
  use File::Basename ();
  use File::Spec::Functions;

  $|=1;

  # make the daemon cross-platform, so exec always calls the script
  # itself with the right path, no matter how the script was invoked.
  my $script = File::Basename::basename($0);
  my $SELF = catfile $FindBin::Bin, $script;

  # POSIX unmasks the sigprocmask properly
  my $sigset = POSIX::SigSet->new();
  my $action = POSIX::SigAction->new('sigHUP_handler',
                                     $sigset,
                                     &POSIX::SA_NODEFER);
  POSIX::sigaction(&POSIX::SIGHUP, $action);

  sub sigHUP_handler {
      print "got SIGHUP\n";
      exec($SELF, @ARGV) or die "Couldn't restart: $!\n";
  }

  code();

  sub code {
      print "PID: $$\n";
      print "ARGV: @ARGV\n";
      my $c = 0;
      while (++$c) {
          sleep 2;
          print "$c\n";
      }
  }
  __END__

Named Pipes

A named pipe (often referred to as a FIFO) is an old Unix IPC mechanism for processes communicating on the same machine. It works just like a regular, connected anonymous pipes, except that the processes rendezvous using a filename and don't have to be related.

To create a named pipe, use the POSIX::mkfifo() function.

    use POSIX qw(mkfifo);
    mkfifo($path, 0700) or die "mkfifo $path failed: $!";

You can also use the Unix command mknod(1) or on some systems, mkfifo(1). These may not be in your normal path.

    # system return val is backwards, so && not ||
    #
    $ENV{PATH} .= ":/etc:/usr/etc";
    if  (      system('mknod',  $path, 'p')
            && system('mkfifo', $path) )
    {
        die "mk{nod,fifo} $path failed";
    }

A fifo is convenient when you want to connect a process to an unrelated one. When you open a fifo, the program will block until there's something on the other end.

For example, let's say you'd like to have your .signature file be a named pipe that has a Perl program on the other end. Now every time any program (like a mailer, news reader, finger program, etc.) tries to read from that file, the reading program will block and your program will supply the new signature. We'll use the pipe-checking file test -p to find out whether anyone (or anything) has accidentally removed our fifo.

    chdir; # go home
    $FIFO = '.signature';

    while (1) {
        unless (-p $FIFO) {
            unlink $FIFO;
            require POSIX;
            POSIX::mkfifo($FIFO, 0700)
                or die "can't mkfifo $FIFO: $!";
        }

        # next line blocks until there's a reader
        open (FIFO, "> $FIFO") || die "can't write $FIFO: $!";
        print FIFO "John Smith (smith\@host.org)\n", `fortune -s`;
        close FIFO;
        sleep 2;    # to avoid dup signals
            }

Deferred Signals (Safe Signals)

In Perls before Perl 5.7.3 by installing Perl code to deal with signals, you were exposing yourself to danger from two things. First, few system library functions are re-entrant. If the signal interrupts while Perl is executing one function (like malloc(3) or printf(3)), and your signal handler then calls the same function again, you could get unpredictable behavior--often, a core dump. Second, Perl isn't itself re-entrant at the lowest levels. If the signal interrupts Perl while Perl is changing its own internal data structures, similarly unpredictable behaviour may result.

There were two things you could do, knowing this: be paranoid or be pragmatic. The paranoid approach was to do as little as possible in your signal handler. Set an existing integer variable that already has a value, and return. This doesn't help you if you're in a slow system call, which will just restart. That means you have to die to longjump(3) out of the handler. Even this is a little cavalier for the true paranoiac, who avoids die in a handler because the system is out to get you. The pragmatic approach was to say "I know the risks, but prefer the convenience", and to do anything you wanted in your signal handler, and be prepared to clean up core dumps now and again.

In Perl 5.7.3 and later to avoid these problems signals are "deferred"-- that is when the signal is delivered to the process by the system (to the C code that implements Perl) a flag is set, and the handler returns immediately. Then at strategic "safe" points in the Perl interpreter (e.g. when it is about to execute a new opcode) the flags are checked and the Perl level handler from %SIG is executed. The "deferred" scheme allows much more flexibility in the coding of signal handler as we know Perl interpreter is in a safe state, and that we are not in a system library function when the handler is called. However the implementation does differ from previous Perls in the following ways:

Long running opcodes

As Perl interpreter only looks at the signal flags when it about to execute a new opcode if a signal arrives during a long running opcode (e.g. a regular expression operation on a very large string) then signal will not be seen until operation completes.

Interrupting IO

When a signal is delivered (e.g. INT control-C) the operating system breaks into IO operations like read (used to implement Perls <> operator). On older Perls the handler was called immediately (and as read is not "unsafe" this worked well). With the "deferred" scheme the handler is not called immediately, and if Perl is using system's stdio library that library may re-start the read without returning to Perl and giving it a chance to call the %SIG handler. If this happens on your system the solution is to use :perlio layer to do IO - at least on those handles which you want to be able to break into with signals. (The :perlio layer checks the signal flags and calls %SIG handlers before resuming IO operation.)

Note that the default in Perl 5.7.3 and later is to automatically use the :perlio layer.

Note that some networking library functions like gethostbyname() are known to have their own implementations of timeouts which may conflict with your timeouts. If you are having problems with such functions, you can try using the POSIX sigaction() function, which bypasses the Perl safe signals (note that this means subjecting yourself to possible memory corruption, as described above). Instead of setting $SIG{ALRM}:

   local $SIG{ALRM} = sub { die "alarm" };

try something like the following:

    use POSIX qw(SIGALRM);
    POSIX::sigaction(SIGALRM,
                     POSIX::SigAction->new(sub { die "alarm" }))
          or die "Error setting SIGALRM handler: $!\n";
Restartable system calls

On systems that supported it, older versions of Perl used the SA_RESTART flag when installing %SIG handlers. This meant that restartable system calls would continue rather than returning when a signal arrived. In order to deliver deferred signals promptly, Perl 5.7.3 and later do not use SA_RESTART. Consequently, restartable system calls can fail (with $! set to EINTR) in places where they previously would have succeeded.

Note that the default :perlio layer will retry read, write and close as described above and that interrupted wait and waitpid calls will always be retried.

Signals as "faults"

Certain signals e.g. SEGV, ILL, BUS are generated as a result of virtual memory or other "faults". These are normally fatal and there is little a Perl-level handler can do with them. (In particular the old signal scheme was particularly unsafe in such cases.) However if a %SIG handler is set the new scheme simply sets a flag and returns as described above. This may cause the operating system to try the offending machine instruction again and - as nothing has changed - it will generate the signal again. The result of this is a rather odd "loop". In future Perl's signal mechanism may be changed to avoid this - perhaps by simply disallowing %SIG handlers on signals of that type. Until then the work-round is not to set a %SIG handler on those signals. (Which signals they are is operating system dependent.)

Signals triggered by operating system state

On some operating systems certain signal handlers are supposed to "do something" before returning. One example can be CHLD or CLD which indicates a child process has completed. On some operating systems the signal handler is expected to wait for the completed child process. On such systems the deferred signal scheme will not work for those signals (it does not do the wait). Again the failure will look like a loop as the operating system will re-issue the signal as there are un-waited-for completed child processes.

If you want the old signal behaviour back regardless of possible memory corruption, set the environment variable PERL_SIGNALS to "unsafe" (a new feature since Perl 5.8.1).

Using open() for IPC

Perl's basic open() statement can also be used for unidirectional interprocess communication by either appending or prepending a pipe symbol to the second argument to open(). Here's how to start something up in a child process you intend to write to:

    open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
                    || die "can't fork: $!";
    local $SIG{PIPE} = sub { die "spooler pipe broke" };
    print SPOOLER "stuff\n";
    close SPOOLER || die "bad spool: $! $?";

And here's how to start up a child process you intend to read from:

    open(STATUS, "netstat -an 2>&1 |")
                    || die "can't fork: $!";
    while (<STATUS>) {
        next if /^(tcp|udp)/;
        print;
    }
    close STATUS || die "bad netstat: $! $?";

If one can be sure that a particular program is a Perl script that is expecting filenames in @ARGV, the clever programmer can write something like this:

    % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile

and irrespective of which shell it's called from, the Perl program will read from the file f1, the process cmd1, standard input (tmpfile in this case), the f2 file, the cmd2 command, and finally the f3 file. Pretty nifty, eh?

You might notice that you could use backticks for much the same effect as opening a pipe for reading:

    print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
    die "bad netstat" if $?;

While this is true on the surface, it's much more efficient to process the file one line or record at a time because then you don't have to read the whole thing into memory at once. It also gives you finer control of the whole process, letting you to kill off the child process early if you'd like.

Be careful to check both the open() and the close() return values. If you're writing to a pipe, you should also trap SIGPIPE. Otherwise, think of what happens when you start up a pipe to a command that doesn't exist: the open() will in all likelihood succeed (it only reflects the fork()'s success), but then your output will fail--spectacularly. Perl can't know whether the command worked because your command is actually running in a separate process whose exec() might have failed. Therefore, while readers of bogus commands return just a quick end of file, writers to bogus command will trigger a signal they'd better be prepared to handle. Consider:

    open(FH, "|bogus")  or die "can't fork: $!";
    print FH "bang\n"   or die "can't write: $!";
    close FH            or die "can't close: $!";

That won't blow up until the close, and it will blow up with a SIGPIPE. To catch it, you could use this:

    $SIG{PIPE} = 'IGNORE';
    open(FH, "|bogus")  or die "can't fork: $!";
    print FH "bang\n"   or die "can't write: $!";
    close FH            or die "can't close: status=$?";

Filehandles

Both the main process and any child processes it forks share the same STDIN, STDOUT, and STDERR filehandles. If both processes try to access them at once, strange things can happen. You may also want to close or reopen the filehandles for the child. You can get around this by opening your pipe with open(), but on some systems this means that the child process cannot outlive the parent.

Background Processes

You can run a command in the background with:

    system("cmd &");

The command's STDOUT and STDERR (and possibly STDIN, depending on your shell) will be the same as the parent's. You won't need to catch SIGCHLD because of the double-fork taking place (see below for more details).

Complete Dissociation of Child from Parent

In some cases (starting server processes, for instance) you'll want to completely dissociate the child process from the parent. This is often called daemonization. A well behaved daemon will also chdir() to the root directory (so it doesn't prevent unmounting the filesystem containing the directory from which it was launched) and redirect its standard file descriptors from and to /dev/null (so that random output doesn't wind up on the user's terminal).

    use POSIX 'setsid';

    sub daemonize {
        chdir '/'               or die "Can't chdir to /: $!";
        open STDIN, '/dev/null' or die "Can't read /dev/null: $!";
        open STDOUT, '>/dev/null'
                                or die "Can't write to /dev/null: $!";
        defined(my $pid = fork) or die "Can't fork: $!";
        exit if $pid;
        setsid                  or die "Can't start a new session: $!";
        open STDERR, '>&STDOUT' or die "Can't dup stdout: $!";
    }

The fork() has to come before the setsid() to ensure that you aren't a process group leader (the setsid() will fail if you are). If your system doesn't have the setsid() function, open /dev/tty and use the TIOCNOTTY ioctl() on it instead. See tty(4) for details.

Non-Unix users should check their Your_OS::Process module for other solutions.

Safe Pipe Opens

Another interesting approach to IPC is making your single program go multiprocess and communicate between (or even amongst) yourselves. The open() function will accept a file argument of either "-|" or "|-" to do a very interesting thing: it forks a child connected to the filehandle you've opened. The child is running the same program as the parent. This is useful for safely opening a file when running under an assumed UID or GID, for example. If you open a pipe to minus, you can write to the filehandle you opened and your kid will find it in his STDIN. If you open a pipe from minus, you can read from the filehandle you opened whatever your kid writes to his STDOUT.

    use English '-no_match_vars';
    my $sleep_count = 0;

    do {
        $pid = open(KID_TO_WRITE, "|-");
        unless (defined $pid) {
            warn "cannot fork: $!";
            die "bailing out" if $sleep_count++ > 6;
            sleep 10;
        }
    } until defined $pid;

    if ($pid) {  # parent
        print KID_TO_WRITE @some_data;
        close(KID_TO_WRITE) || warn "kid exited $?";
    } else {     # child
        ($EUID, $EGID) = ($UID, $GID); # suid progs only
        open (FILE, "> /safe/file")
            || die "can't open /safe/file: $!";
        while (<STDIN>) {
            print FILE; # child's STDIN is parent's KID
        }
        exit;  # don't forget this
    }

Another common use for this construct is when you need to execute something without the shell's interference. With system(), it's straightforward, but you can't use a pipe open or backticks safely. That's because there's no way to stop the shell from getting its hands on your arguments. Instead, use lower-level control to call exec() directly.

Here's a safe backtick or pipe open for read:

    # add error processing as above
    $pid = open(KID_TO_READ, "-|");

    if ($pid) {   # parent
        while (<KID_TO_READ>) {
            # do something interesting
        }
        close(KID_TO_READ) || warn "kid exited $?";

    } else {      # child
        ($EUID, $EGID) = ($UID, $GID); # suid only
        exec($program, @options, @args)
            || die "can't exec program: $!";
        # NOTREACHED
    }

And here's a safe pipe open for writing:

    # add error processing as above
    $pid = open(KID_TO_WRITE, "|-");
    $SIG{PIPE} = sub { die "whoops, $program pipe broke" };

    if ($pid) {  # parent
        for (@data) {
            print KID_TO_WRITE;
        }
        close(KID_TO_WRITE) || warn "kid exited $?";

    } else {     # child
        ($EUID, $EGID) = ($UID, $GID);
        exec($program, @options, @args)
            || die "can't exec program: $!";
        # NOTREACHED
    }

Since Perl 5.8.0, you can also use the list form of open for pipes : the syntax

    open KID_PS, "-|", "ps", "aux" or die $!;

forks the ps(1) command (without spawning a shell, as there are more than three arguments to open()), and reads its standard output via the KID_PS filehandle. The corresponding syntax to write to command pipes (with "|-" in place of "-|") is also implemented.

Note that these operations are full Unix forks, which means they may not be correctly implemented on alien systems. Additionally, these are not true multithreading. If you'd like to learn more about threading, see the modules file mentioned below in the SEE ALSO section.

Bidirectional Communication with Another Process

While this works reasonably well for unidirectional communication, what about bidirectional communication? The obvious thing you'd like to do doesn't actually work:

    open(PROG_FOR_READING_AND_WRITING, "| some program |")

and if you forget to use the use warnings pragma or the -w flag, then you'll miss out entirely on the diagnostic message:

    Can't do bidirectional pipe at -e line 1.

If you really want to, you can use the standard open2() library function to catch both ends. There's also an open3() for tridirectional I/O so you can also catch your child's STDERR, but doing so would then require an awkward select() loop and wouldn't allow you to use normal Perl input operations.

If you look at its source, you'll see that open2() uses low-level primitives like Unix pipe() and exec() calls to create all the connections. While it might have been slightly more efficient by using socketpair(), it would have then been even less portable than it already is. The open2() and open3() functions are unlikely to work anywhere except on a Unix system or some other one purporting to be POSIX compliant.

Here's an example of using open2():

    use FileHandle;
    use IPC::Open2;
    $pid = open2(*Reader, *Writer, "cat -u -n" );
    print Writer "stuff\n";
    $got = <Reader>;

The problem with this is that Unix buffering is really going to ruin your day. Even though your Writer filehandle is auto-flushed, and the process on the other end will get your data in a timely manner, you can't usually do anything to force it to give it back to you in a similarly quick fashion. In this case, we could, because we gave cat a -u flag to make it unbuffered. But very few Unix commands are designed to operate over pipes, so this seldom works unless you yourself wrote the program on the other end of the double-ended pipe.

A solution to this is the nonstandard Comm.pl library. It uses pseudo-ttys to make your program behave more reasonably:

    require 'Comm.pl';
    $ph = open_proc('cat -n');
    for (1..10) {
        print $ph "a line\n";
        print "got back ", scalar <$ph>;
    }

This way you don't have to have control over the source code of the program you're using. The Comm library also has expect() and interact() functions. Find the library (and we hope its successor IPC::Chat) at your nearest CPAN archive as detailed in the SEE ALSO section below.

The newer Expect.pm module from CPAN also addresses this kind of thing. This module requires two other modules from CPAN: IO::Pty and IO::Stty. It sets up a pseudo-terminal to interact with programs that insist on using talking to the terminal device driver. If your system is amongst those supported, this may be your best bet.

Bidirectional Communication with Yourself

If you want, you may make low-level pipe() and fork() to stitch this together by hand. This example only talks to itself, but you could reopen the appropriate handles to STDIN and STDOUT and call other processes.

    #!/usr/bin/perl -w
    # pipe1 - bidirectional communication using two pipe pairs
    #         designed for the socketpair-challenged
    use IO::Handle;     # thousands of lines just for autoflush :-(
    pipe(PARENT_RDR, CHILD_WTR);                # XXX: failure?
    pipe(CHILD_RDR,  PARENT_WTR);               # XXX: failure?
    CHILD_WTR->autoflush(1);
    PARENT_WTR->autoflush(1);

    if ($pid = fork) {
        close PARENT_RDR; close PARENT_WTR;
        print CHILD_WTR "Parent Pid $$ is sending this\n";
        chomp($line = <CHILD_RDR>);
        print "Parent Pid $$ just read this: `$line'\n";
        close CHILD_RDR; close CHILD_WTR;
        waitpid($pid,0);
    } else {
        die "cannot fork: $!" unless defined $pid;
        close CHILD_RDR; close CHILD_WTR;
        chomp($line = <PARENT_RDR>);
        print "Child Pid $$ just read this: `$line'\n";
        print PARENT_WTR "Child Pid $$ is sending this\n";
        close PARENT_RDR; close PARENT_WTR;
        exit;
    }

But you don't actually have to make two pipe calls. If you have the socketpair() system call, it will do this all for you.

    #!/usr/bin/perl -w
    # pipe2 - bidirectional communication using socketpair
    #   "the best ones always go both ways"

    use Socket;
    use IO::Handle;     # thousands of lines just for autoflush :-(
    # We say AF_UNIX because although *_LOCAL is the
    # POSIX 1003.1g form of the constant, many machines
    # still don't have it.
    socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
                                or  die "socketpair: $!";

    CHILD->autoflush(1);
    PARENT->autoflush(1);

    if ($pid = fork) {
        close PARENT;
        print CHILD "Parent Pid $$ is sending this\n";
        chomp($line = <CHILD>);
        print "Parent Pid $$ just read this: `$line'\n";
        close CHILD;
        waitpid($pid,0);
    } else {
        die "cannot fork: $!" unless defined $pid;
        close CHILD;
        chomp($line = <PARENT>);
        print "Child Pid $$ just read this: `$line'\n";
        print PARENT "Child Pid $$ is sending this\n";
        close PARENT;
        exit;
    }

Sockets: Client/Server Communication

While not limited to Unix-derived operating systems (e.g., WinSock on PCs provides socket support, as do some VMS libraries), you may not have sockets on your system, in which case this section probably isn't going to do you much good. With sockets, you can do both virtual circuits (i.e., TCP streams) and datagrams (i.e., UDP packets). You may be able to do even more depending on your system.

The Perl function calls for dealing with sockets have the same names as the corresponding system calls in C, but their arguments tend to differ for two reasons: first, Perl filehandles work differently than C file descriptors. Second, Perl already knows the length of its strings, so you don't need to pass that information.

One of the major problems with old socket code in Perl was that it used hard-coded values for some of the constants, which severely hurt portability. If you ever see code that does anything like explicitly setting $AF_INET = 2, you know you're in for big trouble: An immeasurably superior approach is to use the Socket module, which more reliably grants access to various constants and functions you'll need.

If you're not writing a server/client for an existing protocol like NNTP or SMTP, you should give some thought to how your server will know when the client has finished talking, and vice-versa. Most protocols are based on one-line messages and responses (so one party knows the other has finished when a "\n" is received) or multi-line messages and responses that end with a period on an empty line ("\n.\n" terminates a message/response).

Internet Line Terminators

The Internet line terminator is "\015\012". Under ASCII variants of Unix, that could usually be written as "\r\n", but under other systems, "\r\n" might at times be "\015\015\012", "\012\012\015", or something completely different. The standards specify writing "\015\012" to be conformant (be strict in what you provide), but they also recommend accepting a lone "\012" on input (but be lenient in what you require). We haven't always been very good about that in the code in this manpage, but unless you're on a Mac, you'll probably be ok.

Internet TCP Clients and Servers

Use Internet-domain sockets when you want to do client-server communication that might extend to machines outside of your own system.

Here's a sample TCP client using Internet-domain sockets:

    #!/usr/bin/perl -w
    use strict;
    use Socket;
    my ($remote,$port, $iaddr, $paddr, $proto, $line);

    $remote  = shift || 'localhost';
    $port    = shift || 2345;  # random port
    if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') }
    die "No port" unless $port;
    $iaddr   = inet_aton($remote)               || die "no host: $remote";
    $paddr   = sockaddr_in($port, $iaddr);

    $proto   = getprotobyname('tcp');
    socket(SOCK, PF_INET, SOCK_STREAM, $proto)  || die "socket: $!";
    connect(SOCK, $paddr)    || die "connect: $!";
    while (defined($line = <SOCK>)) {
        print $line;
    }

    close (SOCK)            || die "close: $!";
    exit;

And here's a corresponding server to go along with it. We'll leave the address as INADDR_ANY so that the kernel can choose the appropriate interface on multihomed hosts. If you want sit on a particular interface (like the external side of a gateway or firewall machine), you should fill this in with your real address instead.

    #!/usr/bin/perl -Tw
    use strict;
    BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
    use Socket;
    use Carp;
    my $EOL = "\015\012";

    sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }

    my $port = shift || 2345;
    my $proto = getprotobyname('tcp');

    ($port) = $port =~ /^(\d+)$/                        or die "invalid port";

    socket(Server, PF_INET, SOCK_STREAM, $proto)        || die "socket: $!";
    setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
                                        pack("l", 1))   || die "setsockopt: $!";
    bind(Server, sockaddr_in($port, INADDR_ANY))        || die "bind: $!";
    listen(Server,SOMAXCONN)                            || die "listen: $!";

    logmsg "server started on port $port";

    my $paddr;

    $SIG{CHLD} = \&REAPER;

    for ( ; $paddr = accept(Client,Server); close Client) {
        my($port,$iaddr) = sockaddr_in($paddr);
        my $name = gethostbyaddr($iaddr,AF_INET);

        logmsg "connection from $name [",
                inet_ntoa($iaddr), "]
                at port $port";

        print Client "Hello there, $name, it's now ",
                        scalar localtime, $EOL;
            }

And here's a multithreaded version. It's multithreaded in that like most typical servers, it spawns (forks) a slave server to handle the client request so that the master server can quickly go back to service a new client.

    #!/usr/bin/perl -Tw
    use strict;
    BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
    use Socket;
    use Carp;
    my $EOL = "\015\012";

    sub spawn;  # forward declaration
    sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }

    my $port = shift || 2345;
    my $proto = getprotobyname('tcp');

    ($port) = $port =~ /^(\d+)$/                        or die "invalid port";

    socket(Server, PF_INET, SOCK_STREAM, $proto)        || die "socket: $!";
    setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
                                        pack("l", 1))   || die "setsockopt: $!";
    bind(Server, sockaddr_in($port, INADDR_ANY))        || die "bind: $!";
    listen(Server,SOMAXCONN)                            || die "listen: $!";

    logmsg "server started on port $port";

    my $waitedpid = 0;
    my $paddr;

    use POSIX ":sys_wait_h";
    sub REAPER {
        my $child;
        while (($waitedpid = waitpid(-1,WNOHANG)) > 0) {
            logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
        }
        $SIG{CHLD} = \&REAPER;  # loathe sysV
    }

    $SIG{CHLD} = \&REAPER;

    for ( $waitedpid = 0;
          ($paddr = accept(Client,Server)) || $waitedpid;
          $waitedpid = 0, close Client)
    {
        next if $waitedpid and not $paddr;
        my($port,$iaddr) = sockaddr_in($paddr);
        my $name = gethostbyaddr($iaddr,AF_INET);

        logmsg "connection from $name [",
                inet_ntoa($iaddr), "]
                at port $port";

        spawn sub {
            $|=1;
            print "Hello there, $name, it's now ", scalar localtime, $EOL;
            exec '/usr/games/fortune'           # XXX: `wrong' line terminators
                or confess "can't exec fortune: $!";
        };

    }
    sub spawn {
        my $coderef = shift;

        unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
            confess "usage: spawn CODEREF";
        }

        my $pid;
        if (!defined($pid = fork)) {
            logmsg "cannot fork: $!";
            return;
        } elsif ($pid) {
            logmsg "begat $pid";
            return; # I'm the parent
        }
        # else I'm the child -- go spawn

        open(STDIN,  "<&Client")   || die "can't dup client to stdin";
        open(STDOUT, ">&Client")   || die "can't dup client to stdout";
        ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
        exit &$coderef();
            }

This server takes the trouble to clone off a child version via fork() for each incoming request. That way it can handle many requests at once, which you might not always want. Even if you don't fork(), the listen() will allow that many pending connections. Forking servers have to be particularly careful about cleaning up their dead children (called "zombies" in Unix parlance), because otherwise you'll quickly fill up your process table.

We suggest that you use the -T flag to use taint checking (see the perlsec manpage) even if we aren't running setuid or setgid. This is always a good idea for servers and other programs run on behalf of someone else (like CGI scripts), because it lessens the chances that people from the outside will be able to compromise your system.

Let's look at another TCP client. This one connects to the TCP "time" service on a number of different machines and shows how far their clocks differ from the system on which it's being run:

    #!/usr/bin/perl  -w
    use strict;
    use Socket;

    my $SECS_of_70_YEARS = 2208988800;
    sub ctime { scalar localtime(shift) }

    my $iaddr = gethostbyname('localhost');
    my $proto = getprotobyname('tcp');
    my $port = getservbyname('time', 'tcp');
    my $paddr = sockaddr_in(0, $iaddr);
    my($host);

    $| = 1;
    printf "%-24s %8s %s\n",  "localhost", 0, ctime(time());

    foreach $host (@ARGV) {
        printf "%-24s ", $host;
        my $hisiaddr = inet_aton($host)     || die "unknown host";
        my $hispaddr = sockaddr_in($port, $hisiaddr);
        socket(SOCKET, PF_INET, SOCK_STREAM, $proto)   || die "socket: $!";
        connect(SOCKET, $hispaddr)          || die "bind: $!";
        my $rtime = '    ';
        read(SOCKET, $rtime, 4);
        close(SOCKET);
        my $histime = unpack("N", $rtime) - $SECS_of_70_YEARS;
        printf "%8d %s\n", $histime - time, ctime($histime);
    }

Unix-Domain TCP Clients and Servers

That's fine for Internet-domain clients and servers, but what about local communications? While you can use the same setup, sometimes you don't want to. Unix-domain sockets are local to the current host, and are often used internally to implement pipes. Unlike Internet domain sockets, Unix domain sockets can show up in the file system with an ls(1) listing.

    % ls -l /dev/log
    srw-rw-rw-  1 root            0 Oct 31 07:23 /dev/log

You can test for these with Perl's -S file test:

    unless ( -S '/dev/log' ) {
        die "something's wicked with the log system";
    }

Here's a sample Unix-domain client:

    #!/usr/bin/perl -w
    use Socket;
    use strict;
    my ($rendezvous, $line);

    $rendezvous = shift || 'catsock';
    socket(SOCK, PF_UNIX, SOCK_STREAM, 0)       || die "socket: $!";
    connect(SOCK, sockaddr_un($rendezvous))     || die "connect: $!";
    while (defined($line = <SOCK>)) {
        print $line;
    }
    exit;

And here's a corresponding server. You don't have to worry about silly network terminators here because Unix domain sockets are guaranteed to be on the localhost, and thus everything works right.

    #!/usr/bin/perl -Tw
    use strict;
    use Socket;
    use Carp;

    BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
    sub spawn;  # forward declaration
    sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }

    my $NAME = 'catsock';
    my $uaddr = sockaddr_un($NAME);
    my $proto = getprotobyname('tcp');

    socket(Server,PF_UNIX,SOCK_STREAM,0)        || die "socket: $!";
    unlink($NAME);
    bind  (Server, $uaddr)                      || die "bind: $!";
    listen(Server,SOMAXCONN)                    || die "listen: $!";

    logmsg "server started on $NAME";

    my $waitedpid;

    use POSIX ":sys_wait_h";
    sub REAPER {
        my $child;
        while (($waitedpid = waitpid(-1,WNOHANG)) > 0) {
            logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
        }
        $SIG{CHLD} = \&REAPER;  # loathe sysV
    }

    $SIG{CHLD} = \&REAPER;

    for ( $waitedpid = 0;
          accept(Client,Server) || $waitedpid;
          $waitedpid = 0, close Client)
    {
        next if $waitedpid;
        logmsg "connection on $NAME";
        spawn sub {
            print "Hello there, it's now ", scalar localtime, "\n";
            exec '/usr/games/fortune' or die "can't exec fortune: $!";
        };
    }

    sub spawn {
        my $coderef = shift;

        unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
            confess "usage: spawn CODEREF";
        }

        my $pid;
        if (!defined($pid = fork)) {
            logmsg "cannot fork: $!";
            return;
        } elsif ($pid) {
            logmsg "begat $pid";
            return; # I'm the parent
        }
        # else I'm the child -- go spawn

        open(STDIN,  "<&Client")   || die "can't dup client to stdin";
        open(STDOUT, ">&Client")   || die "can't dup client to stdout";
        ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
        exit &$coderef();
            }

As you see, it's remarkably similar to the Internet domain TCP server, so much so, in fact, that we've omitted several duplicate functions--spawn(), logmsg(), ctime(), and REAPER()--which are exactly the same as in the other server.

So why would you ever want to use a Unix domain socket instead of a simpler named pipe? Because a named pipe doesn't give you sessions. You can't tell one process's data from another's. With socket programming, you get a separate session for each client: that's why accept() takes two arguments.

For example, let's say that you have a long running database server daemon that you want folks from the World Wide Web to be able to access, but only if they go through a CGI interface. You'd have a small, simple CGI program that does whatever checks and logging you feel like, and then acts as a Unix-domain client and connects to your private server.

TCP Clients with IO::Socket

For those preferring a higher-level interface to socket programming, the IO::Socket module provides an object-oriented approach. IO::Socket is included as part of the standard Perl distribution as of the 5.004 release. If you're running an earlier version of Perl, just fetch IO::Socket from CPAN, where you'll also find modules providing easy interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just to name a few.

A Simple Client

Here's a client that creates a TCP connection to the "daytime" service at port 13 of the host name "localhost" and prints out everything that the server there cares to provide.

    #!/usr/bin/perl -w
    use IO::Socket;
    $remote = IO::Socket::INET->new(
                        Proto    => "tcp",
                        PeerAddr => "localhost",
                        PeerPort => "daytime(13)",
                    )
                  or die "cannot connect to daytime port at localhost";
    while ( <$remote> ) { print }

When you run this program, you should get something back that looks like this:

    Wed May 14 08:40:46 MDT 1997

Here are what those parameters to the new constructor mean:

Proto

This is which protocol to use. In this case, the socket handle returned will be connected to a TCP socket, because we want a stream-oriented connection, that is, one that acts pretty much like a plain old file. Not all sockets are this of this type. For example, the UDP protocol can be used to make a datagram socket, used for message-passing.

PeerAddr

This is the name or Internet address of the remote host the server is running on. We could have specified a longer name like "www.perl.com", or an address like "204.148.40.9". For demonstration purposes, we've used the special hostname "localhost", which should always mean the current machine you're running on. The corresponding Internet address for localhost is "127.1", if you'd rather use that.

PeerPort

This is the service name or port number we'd like to connect to. We could have gotten away with using just "daytime" on systems with a well-configured system services file,[FOOTNOTE: The system services file is in /etc/services under Unix] but just in case, we've specified the port number (13) in parentheses. Using just the number would also have worked, but constant numbers make careful programmers nervous.

Notice how the return value from the new constructor is used as a filehandle in the while loop? That's what's called an indirect filehandle, a scalar variable containing a filehandle. You can use it the same way you would a normal filehandle. For example, you can read one line from it this way:

    $line = <$handle>;

all remaining lines from is this way:

    @lines = <$handle>;

and send a line of data to it this way:

    print $handle "some data\n";

A Webget Client

Here's a simple client that takes a remote host to fetch a document from, and then a list of documents to get from that host. This is a more interesting client than the previous one because it first sends something to the server before fetching the server's response.

    #!/usr/bin/perl -w
    use IO::Socket;
    unless (@ARGV > 1) { die "usage: $0 host document ..." }
    $host = shift(@ARGV);
    $EOL = "\015\012";
    $BLANK = $EOL x 2;
    foreach $document ( @ARGV ) {
        $remote = IO::Socket::INET->new( Proto     => "tcp",
                                         PeerAddr  => $host,
                                         PeerPort  => "http(80)",
                                        );
        unless ($remote) { die "cannot connect to http daemon on $host" }
        $remote->autoflush(1);
        print $remote "GET $document HTTP/1.0" . $BLANK;
        while ( <$remote> ) { print }
        close $remote;
    }

The web server handing the "http" service, which is assumed to be at its standard port, number 80. If the web server you're trying to connect to is at a different port (like 1080 or 8080), you should specify as the named-parameter pair, PeerPort => 8080. The autoflush method is used on the socket because otherwise the system would buffer up the output we sent it. (If you're on a Mac, you'll also need to change every "\n" in your code that sends data over the network to be a "\015\012" instead.)

Connecting to the server is only the first part of the process: once you have the connection, you have to use the server's language. Each server on the network has its own little command language that it expects as input. The string that we send to the server starting with "GET" is in HTTP syntax. In this case, we simply request each specified document. Yes, we really are making a new connection for each document, even though it's the same host. That's the way you always used to have to speak HTTP. Recent versions of web browsers may request that the remote server leave the connection open a little while, but the server doesn't have to honor such a request.

Here's an example of running that program, which we'll call webget:

    % webget www.perl.com /guanaco.html
    HTTP/1.1 404 File Not Found
    Date: Thu, 08 May 1997 18:02:32 GMT
    Server: Apache/1.2b6
    Connection: close
    Content-type: text/html
    <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
    <BODY><H1>File Not Found</H1>
    The requested URL /guanaco.html was not found on this server.<P>
    </BODY>

Ok, so that's not very interesting, because it didn't find that particular document. But a long response wouldn't have fit on this page.

For a more fully-featured version of this program, you should look to the lwp-request program included with the LWP modules from CPAN.

Interactive Client with IO::Socket

Well, that's all fine if you want to send one command and get one answer, but what about setting up something fully interactive, somewhat like the way telnet works? That way you can type a line, get the answer, type a line, get the answer, etc.

This client is more complicated than the two we've done so far, but if you're on a system that supports the powerful fork call, the solution isn't that rough. Once you've made the connection to whatever service you'd like to chat with, call fork to clone your process. Each of these two identical process has a very simple job to do: the parent copies everything from the socket to standard output, while the child simultaneously copies everything from standard input to the socket. To accomplish the same thing using just one process would be much harder, because it's easier to code two processes to do one thing than it is to code one process to do two things. (This keep-it-simple principle a cornerstones of the Unix philosophy, and good software engineering as well, which is probably why it's spread to other systems.)

Here's the code:

    #!/usr/bin/perl -w
    use strict;
    use IO::Socket;
    my ($host, $port, $kidpid, $handle, $line);

    unless (@ARGV == 2) { die "usage: $0 host port" }
    ($host, $port) = @ARGV;

    # create a tcp connection to the specified host and port
    $handle = IO::Socket::INET->new(Proto     => "tcp",
                                    PeerAddr  => $host,
                                    PeerPort  => $port)
           or die "can't connect to port $port on $host: $!";

    $handle->autoflush(1);              # so output gets there right away
    print STDERR "[Connected to $host:$port]\n";

    # split the program into two processes, identical twins
    die "can't fork: $!" unless defined($kidpid = fork());

    # the if{} block runs only in the parent process
    if ($kidpid) {
        # copy the socket to standard output
        while (defined ($line = <$handle>)) {
            print STDOUT $line;
        }
        kill("TERM", $kidpid);                  # send SIGTERM to child
    }
    # the else{} block runs only in the child process
    else {
        # copy standard input to the socket
        while (defined ($line = <STDIN>)) {
            print $handle $line;
        }
    }

The kill function in the parent's if block is there to send a signal to our child process (current running in the else block) as soon as the remote server has closed its end of the connection.

If the remote server sends data a byte at time, and you need that data immediately without waiting for a newline (which might not happen), you may wish to replace the while loop in the parent with the following:

    my $byte;
    while (sysread($handle, $byte, 1) == 1) {
        print STDOUT $byte;
    }

Making a system call for each byte you want to read is not very efficient (to put it mildly) but is the simplest to explain and works reasonably well.

TCP Servers with IO::Socket

As always, setting up a server is little bit more involved than running a client. The model is that the server creates a special kind of socket that does nothing but listen on a particular port for incoming connections. It does this by calling the IO::Socket::INET->new() method with slightly different arguments than the client did.

Proto

This is which protocol to use. Like our clients, we'll still specify "tcp" here.

LocalPort

We specify a local port in the LocalPort argument, which we didn't do for the client. This is service name or port number for which you want to be the server. (Under Unix, ports under 1024 are restricted to the superuser.) In our sample, we'll use port 9000, but you can use any port that's not currently in use on your system. If you try to use one already in used, you'll get an "Address already in use" message. Under Unix, the netstat -a command will show which services current have servers.

Listen

The Listen parameter is set to the maximum number of pending connections we can accept until we turn away incoming clients. Think of it as a call-waiting queue for your telephone. The low-level Socket module has a special symbol for the system maximum, which is SOMAXCONN.

Reuse

The Reuse parameter is needed so that we restart our server manually without waiting a few minutes to allow system buffers to clear out.

Once the generic server socket has been created using the parameters listed above, the server then waits for a new client to connect to it. The server blocks in the accept method, which eventually accepts a bidirectional connection from the remote client. (Make sure to autoflush this handle to circumvent buffering.)

To add to user-friendliness, our server prompts the user for commands. Most servers don't do this. Because of the prompt without a newline, you'll have to use the sysread variant of the interactive client above.

This server accepts one of five different commands, sending output back to the client. Note that unlike most network servers, this one only handles one incoming client at a time. Multithreaded servers are covered in Chapter 6 of the Camel.

Here's the code. We'll

 #!/usr/bin/perl -w
 use IO::Socket;
 use Net::hostent;              # for OO version of gethostbyaddr

 $PORT = 9000;                  # pick something not in use

 $server = IO::Socket::INET->new( Proto     => 'tcp',
                                  LocalPort => $PORT,
                                  Listen    => SOMAXCONN,
                                  Reuse     => 1);

 die "can't setup server" unless $server;
 print "[Server $0 accepting clients]\n";

 while ($client = $server->accept()) {
   $client->autoflush(1);
   print $client "Welcome to $0; type help for command list.\n";
   $hostinfo = gethostbyaddr($client->peeraddr);
   printf "[Connect from %s]\n", $hostinfo ? $hostinfo->name : $client->peerhost;
   print $client "Command? ";
   while ( <$client>) {
     next unless /\S/;       # blank line
     if    (/quit|exit/i)    { last;                                     }
     elsif (/date|time/i)    { printf $client "%s\n", scalar localtime;  }
     elsif (/who/i )         { print  $client `who 2>&1`;                }
     elsif (/cookie/i )      { print  $client `/usr/games/fortune 2>&1`; }
     elsif (/motd/i )        { print  $client `cat /etc/motd 2>&1`;      }
     else {
       print $client "Commands: quit date who cookie motd\n";
     }
   } continue {
      print $client "Command? ";
   }
   close $client;
 }

UDP: Message Passing

Another kind of client-server setup is one that uses not connections, but messages. UDP communications involve much lower overhead but also provide less reliability, as there are no promises that messages will arrive at all, let alone in order and unmangled. Still, UDP offers some advantages over TCP, including being able to "broadcast" or "multicast" to a whole bunch of destination hosts at once (usually on your local subnet). If you find yourself overly concerned about reliability and start building checks into your message system, then you probably should use just TCP to start with.

Note that UDP datagrams are not a bytestream and should not be treated as such. This makes using I/O mechanisms with internal buffering like stdio (i.e. print() and friends) especially cumbersome. Use syswrite(), or better send(), like in the example below.

Here's a UDP program similar to the sample Internet TCP client given earlier. However, instead of checking one host at a time, the UDP version will check many of them asynchronously by simulating a multicast and then using select() to do a timed-out wait for I/O. To do something similar with TCP, you'd have to use a different socket handle for each host.

    #!/usr/bin/perl -w
    use strict;
    use Socket;
    use Sys::Hostname;

    my ( $count, $hisiaddr, $hispaddr, $histime,
         $host, $iaddr, $paddr, $port, $proto,
         $rin, $rout, $rtime, $SECS_of_70_YEARS);

    $SECS_of_70_YEARS      = 2208988800;

    $iaddr = gethostbyname(hostname());
    $proto = getprotobyname('udp');
    $port = getservbyname('time', 'udp');
    $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick

    socket(SOCKET, PF_INET, SOCK_DGRAM, $proto)   || die "socket: $!";
    bind(SOCKET, $paddr)                          || die "bind: $!";

    $| = 1;
    printf "%-12s %8s %s\n",  "localhost", 0, scalar localtime time;
    $count = 0;
    for $host (@ARGV) {
        $count++;
        $hisiaddr = inet_aton($host)    || die "unknown host";
        $hispaddr = sockaddr_in($port, $hisiaddr);
        defined(send(SOCKET, 0, 0, $hispaddr))    || die "send $host: $!";
    }

    $rin = '';
    vec($rin, fileno(SOCKET), 1) = 1;

    # timeout after 10.0 seconds
    while ($count && select($rout = $rin, undef, undef, 10.0)) {
        $rtime = '';
        ($hispaddr = recv(SOCKET, $rtime, 4, 0))        || die "recv: $!";
        ($port, $hisiaddr) = sockaddr_in($hispaddr);
        $host = gethostbyaddr($hisiaddr, AF_INET);
        $histime = unpack("N", $rtime) - $SECS_of_70_YEARS;
        printf "%-12s ", $host;
        printf "%8d %s\n", $histime - time, scalar localtime($histime);
        $count--;
    }

Note that this example does not include any retries and may consequently fail to contact a reachable host. The most prominent reason for this is congestion of the queues on the sending host if the number of list of hosts to contact is sufficiently large.

SysV IPC

While System V IPC isn't so widely used as sockets, it still has some interesting uses. You can't, however, effectively use SysV IPC or Berkeley mmap() to have shared memory so as to share a variable amongst several processes. That's because Perl would reallocate your string when you weren't wanting it to.

Here's a small example showing shared memory usage.

    use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU);

    $size = 2000;
    $id = shmget(IPC_PRIVATE, $size, S_IRWXU) || die "$!";
    print "shm key $id\n";

    $message = "Message #1";
    shmwrite($id, $message, 0, 60) || die "$!";
    print "wrote: '$message'\n";
    shmread($id, $buff, 0, 60) || die "$!";
    print "read : '$buff'\n";

    # the buffer of shmread is zero-character end-padded.
    substr($buff, index($buff, "\0")) = '';
    print "un" unless $buff eq $message;
    print "swell\n";

    print "deleting shm $id\n";
    shmctl($id, IPC_RMID, 0) || die "$!";

Here's an example of a semaphore:

    use IPC::SysV qw(IPC_CREAT);

    $IPC_KEY = 1234;
    $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!";
    print "shm key $id\n";

Put this code in a separate file to be run in more than one process. Call the file take:

    # create a semaphore

    $IPC_KEY = 1234;
    $id = semget($IPC_KEY,  0 , 0 );
    die if !defined($id);

    $semnum = 0;
    $semflag = 0;

    # 'take' semaphore
    # wait for semaphore to be zero
    $semop = 0;
    $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);

    # Increment the semaphore count
    $semop = 1;
    $opstring2 = pack("s!s!s!", $semnum, $semop,  $semflag);
    $opstring = $opstring1 . $opstring2;

    semop($id,$opstring) || die "$!";

Put this code in a separate file to be run in more than one process. Call this file give:

    # 'give' the semaphore
    # run this in the original process and you will see
    # that the second process continues

    $IPC_KEY = 1234;
    $id = semget($IPC_KEY, 0, 0);
    die if !defined($id);

    $semnum = 0;
    $semflag = 0;

    # Decrement the semaphore count
    $semop = -1;
    $opstring = pack("s!s!s!", $semnum, $semop, $semflag);

    semop($id,$opstring) || die "$!";

The SysV IPC code above was written long ago, and it's definitely clunky looking. For a more modern look, see the IPC::SysV module which is included with Perl starting from Perl 5.005.

A small example demonstrating SysV message queues:

    use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU);

    my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRWXU);

    my $sent = "message";
    my $type_sent = 1234;
    my $rcvd;
    my $type_rcvd;

    if (defined $id) {
        if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) {
            if (msgrcv($id, $rcvd, 60, 0, 0)) {
                ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd);
                if ($rcvd eq $sent) {
                    print "okay\n";
                } else {
                    print "not okay\n";
                }
            } else {
                die "# msgrcv failed\n";
            }
        } else {
            die "# msgsnd failed\n";
        }
        msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n";
    } else {
        die "# msgget failed\n";
    }

NOTES

Most of these routines quietly but politely return undef when they fail instead of causing your program to die right then and there due to an uncaught exception. (Actually, some of the new Socket conversion functions croak() on bad arguments.) It is therefore essential to check return values from these functions. Always begin your socket programs this way for optimal success, and don't forget to add -T taint checking flag to the #! line for servers:

    #!/usr/bin/perl -Tw
    use strict;
    use sigtrap;
    use Socket;

BUGS

All these routines create system-specific portability problems. As noted elsewhere, Perl is at the mercy of your C libraries for much of its system behaviour. It's probably safest to assume broken SysV semantics for signals and to stick with simple TCP and UDP socket operations; e.g., don't try to pass open file descriptors over a local UDP datagram socket if you want your code to stand a chance of being portable.

AUTHOR

Tom Christiansen, with occasional vestiges of Larry Wall's original version and suggestions from the Perl Porters.

SEE ALSO

There's a lot more to networking than this, but this should get you started.

For intrepid programmers, the indispensable textbook is Unix Network Programming, 2nd Edition, Volume 1 by W. Richard Stevens (published by Prentice-Hall). Note that most books on networking address the subject from the perspective of a C programmer; translation to Perl is left as an exercise for the reader.

The IO::Socket(3) manpage describes the object library, and the Socket(3) manpage describes the low-level interface to sockets. Besides the obvious functions in the perlfunc manpage, you should also check out the modules file at your nearest CPAN site. (See the perlmodlib manpage or best yet, the Perl FAQ for a description of what CPAN is and where to get it.)

Section 5 of the modules file is devoted to "Networking, Device Control (modems), and Interprocess Communication", and contains numerous unbundled modules numerous networking modules, Chat and Expect operations, CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet, Threads, and ToolTalk--just to name a few.


perllocale - Perl locale handling

  • PREPARING TO USE LOCALES
  • USING LOCALES
    • The use locale pragma
    • The setlocale function
    • Finding locales
    • LOCALE PROBLEMS
    • Temporarily fixing locale problems
    • Permanently fixing locale problems
    • Permanently fixing your system's locale configuration
    • Fixing system locale configuration
    • The localeconv function
    • I18N::Langinfo
  • LOCALE CATEGORIES
    • Category LC_COLLATE: Collation
    • Category LC_CTYPE: Character Types
    • Category LC_NUMERIC: Numeric Formatting
    • Category LC_MONETARY: Formatting of monetary amounts
    • LC_TIME
    • Other categories
  • SECURITY
  • ENVIRONMENT
  • NOTES
    • Backward compatibility
    • I18N:Collate obsolete
    • Sort speed and memory use impacts
    • write() and LC_NUMERIC
    • Freely available locale definitions
    • I18n and l10n
    • An imperfect standard
  • Unicode and UTF-8
  • BUGS
    • Broken systems
  • SEE ALSO
  • HISTORY

NAME

perllocale - Perl locale handling (internationalization and localization)

DESCRIPTION

Perl supports language-specific notions of data such as "is this a letter", "what is the uppercase equivalent of this letter", and "which of these letters comes first". These are important issues, especially for languages other than English--but also for English: it would be naïve to imagine that A-Za-z defines all the "letters" needed to write in English. Perl is also aware that some character other than '.' may be preferred as a decimal point, and that output date representations may be language-specific. The process of making an application take account of its users' preferences in such matters is called internationalization (often abbreviated as i18n); telling such an application about a particular set of preferences is known as localization (l10n).

Perl can understand language-specific data via the standardized (ISO C, XPG4, POSIX 1.c) method called "the locale system". The locale system is controlled per application using one pragma, one function call, and several environment variables.

NOTE: This feature is new in Perl 5.004, and does not apply unless an application specifically requests it--see Backward compatibility. The one exception is that write() now always uses the current locale - see NOTES.

PREPARING TO USE LOCALES

If Perl applications are to understand and present your data correctly according a locale of your choice, all of the following must be true:

  • Your operating system must support the locale system. If it does, you should find that the setlocale() function is a documented part of its C library.

  • Definitions for locales that you use must be installed. You, or your system administrator, must make sure that this is the case. The available locales, the location in which they are kept, and the manner in which they are installed all vary from system to system. Some systems provide only a few, hard-wired locales and do not allow more to be added. Others allow you to add "canned" locales provided by the system supplier. Still others allow you or the system administrator to define and add arbitrary locales. (You may have to ask your supplier to provide canned locales that are not delivered with your operating system.) Read your system documentation for further illumination.

  • Perl must believe that the locale system is supported. If it does, perl -V:d_setlocale will say that the value for d_setlocale is define.

If you want a Perl application to process and present your data according to a particular locale, the application code should include the use locale pragma (see The use locale pragma) where appropriate, and at least one of the following must be true:

  • The locale-determining environment variables (see ENVIRONMENT) must be correctly set up at the time the application is started, either by yourself or by whoever set up your system account.

  • The application must set its own locale using the method described in The setlocale function.

USING LOCALES

The use locale pragma

By default, Perl ignores the current locale. The use locale pragma tells Perl to use the current locale for some operations:

  • The comparison operators (lt, le, cmp, ge, and gt) and the POSIX string collation functions strcoll() and strxfrm() use LC_COLLATE. sort() is also affected if used without an explicit comparison function, because it uses cmp by default.

    Note: eq and ne are unaffected by locale: they always perform a char-by-char comparison of their scalar operands. What's more, if cmp finds that its operands are equal according to the collation sequence specified by the current locale, it goes on to perform a char-by-char comparison, and only returns 0 (equal) if the operands are char-for-char identical. If you really want to know whether two strings--which eq and cmp may consider different--are equal as far as collation in the locale is concerned, see the discussion in Category LC_COLLATE: Collation.

  • Regular expressions and case-modification functions (uc(), lc(), ucfirst(), and lcfirst()) use LC_CTYPE

  • The formatting functions (printf(), sprintf() and write()) use LC_NUMERIC

  • The POSIX date formatting function (strftime()) uses LC_TIME.

LC_COLLATE, LC_CTYPE, and so on, are discussed further in LOCALE CATEGORIES.

The default behavior is restored with the no locale pragma, or upon reaching the end of block enclosing use locale.

The string result of any operation that uses locale information is tainted, as it is possible for a locale to be untrustworthy. See SECURITY.

The setlocale function

You can switch locales as often as you wish at run time with the POSIX::setlocale() function:

        # This functionality not usable prior to Perl 5.004
        require 5.004;

        # Import locale-handling tool set from POSIX module.
        # This example uses: setlocale -- the function call
        #                    LC_CTYPE -- explained below
        use POSIX qw(locale_h);

        # query and save the old locale
        $old_locale = setlocale(LC_CTYPE);

        setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
        # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"

        setlocale(LC_CTYPE, "");
        # LC_CTYPE now reset to default defined by LC_ALL/LC_CTYPE/LANG
        # environment variables.  See below for documentation.

        # restore the old locale
        setlocale(LC_CTYPE, $old_locale);

The first argument of setlocale() gives the category, the second the locale. The category tells in what aspect of data processing you want to apply locale-specific rules. Category names are discussed in LOCALE CATEGORIES and ENVIRONMENT. The locale is the name of a collection of customization information corresponding to a particular combination of language, country or territory, and codeset. Read on for hints on the naming of locales: not all systems name locales as in the example.

If no second argument is provided and the category is something else than LC_ALL, the function returns a string naming the current locale for the category. You can use this value as the second argument in a subsequent call to setlocale().

If no second argument is provided and the category is LC_ALL, the result is implementation-dependent. It may be a string of concatenated locales names (separator also implementation-dependent) or a single locale name. Please consult your setlocale(3) for details.

If a second argument is given and it corresponds to a valid locale, the locale for the category is set to that value, and the function returns the now-current locale value. You can then use this in yet another call to setlocale(). (In some implementations, the return value may sometimes differ from the value you gave as the second argument--think of it as an alias for the value you gave.)

As the example shows, if the second argument is an empty string, the category's locale is returned to the default specified by the corresponding environment variables. Generally, this results in a return to the default that was in force when Perl started up: changes to the environment made by the application after startup may or may not be noticed, depending on your system's C library.

If the second argument does not correspond to a valid locale, the locale for the category is not changed, and the function returns undef.

For further information about the categories, consult setlocale(3).

Finding locales

For locales available in your system, consult also setlocale(3) to see whether it leads to the list of available locales (search for the SEE ALSO section). If that fails, try the following command lines:

        locale -a
        nlsinfo
        ls /usr/lib/nls/loc
        ls /usr/lib/locale
        ls /usr/lib/nls
        ls /usr/share/locale

and see whether they list something resembling these

        en_US.ISO8859-1     de_DE.ISO8859-1     ru_RU.ISO8859-5
        en_US.iso88591      de_DE.iso88591      ru_RU.iso88595
        en_US               de_DE               ru_RU
        en                  de                  ru
        english             german              russian
        english.iso88591    german.iso88591     russian.iso88595
        english.roman8                          russian.koi8r

Sadly, even though the calling interface for setlocale() has been standardized, names of locales and the directories where the configuration resides have not been. The basic form of the name is language_territory.codeset, but the latter parts after language are not always present. The language and country are usually from the standards ISO 3166 and ISO 639, the two-letter abbreviations for the countries and the languages of the world, respectively. The codeset part often mentions some ISO 8859 character set, the Latin codesets. For example, ISO 8859-1 is the so-called "Western European codeset" that can be used to encode most Western European languages adequately. Again, there are several ways to write even the name of that one standard. Lamentably.

Two special locales are worth particular mention: "C" and "POSIX". Currently these are effectively the same locale: the difference is mainly that the first one is defined by the C standard, the second by the POSIX standard. They define the default locale in which every program starts in the absence of locale information in its environment. (The default default locale, if you will.) Its language is (American) English and its character codeset ASCII.

NOTE: Not all systems have the "POSIX" locale (not all systems are POSIX-conformant), so use "C" when you need explicitly to specify this default locale.

LOCALE PROBLEMS

You may encounter the following warning message at Perl startup:

        perl: warning: Setting locale failed.
        perl: warning: Please check that your locale settings:
                LC_ALL = "En_US",
                LANG = (unset)
            are supported and installed on your system.
        perl: warning: Falling back to the standard locale ("C").

This means that your locale settings had LC_ALL set to "En_US" and LANG exists but has no value. Perl tried to believe you but could not. Instead, Perl gave up and fell back to the "C" locale, the default locale that is supposed to work no matter what. This usually means your locale settings were wrong, they mention locales your system has never heard of, or the locale installation in your system has problems (for example, some system files are broken or missing). There are quick and temporary fixes to these problems, as well as more thorough and lasting fixes.

Temporarily fixing locale problems

The two quickest fixes are either to render Perl silent about any locale inconsistencies or to run Perl under the default locale "C".

Perl's moaning about locale problems can be silenced by setting the environment variable PERL_BADLANG to a zero value, for example "0". This method really just sweeps the problem under the carpet: you tell Perl to shut up even when Perl sees that something is wrong. Do not be surprised if later something locale-dependent misbehaves.

Perl can be run under the "C" locale by setting the environment variable LC_ALL to "C". This method is perhaps a bit more civilized than the PERL_BADLANG approach, but setting LC_ALL (or other locale variables) may affect other programs as well, not just Perl. In particular, external programs run from within Perl will see these changes. If you make the new settings permanent (read on), all programs you run see the changes. See ENVIRONMENT for the full list of relevant environment variables and USING LOCALES for their effects in Perl. Effects in other programs are easily deducible. For example, the variable LC_COLLATE may well affect your sort program (or whatever the program that arranges "records" alphabetically in your system is called).

You can test out changing these variables temporarily, and if the new settings seem to help, put those settings into your shell startup files. Consult your local documentation for the exact details. For in Bourne-like shells (sh, ksh, bash, zsh):

        LC_ALL=en_US.ISO8859-1
        export LC_ALL

This assumes that we saw the locale "en_US.ISO8859-1" using the commands discussed above. We decided to try that instead of the above faulty locale "En_US"--and in Cshish shells (csh, tcsh)

        setenv LC_ALL en_US.ISO8859-1

or if you have the "env" application you can do in any shell

        env LC_ALL=en_US.ISO8859-1 perl ...

If you do not know what shell you have, consult your local helpdesk or the equivalent.

Permanently fixing locale problems

The slower but superior fixes are when you may be able to yourself fix the misconfiguration of your own environment variables. The mis(sing)configuration of the whole system's locales usually requires the help of your friendly system administrator.

First, see earlier in this document about Finding locales. That tells how to find which locales are really supported--and more importantly, installed--on your system. In our example error message, environment variables affecting the locale are listed in the order of decreasing importance (and unset variables do not matter). Therefore, having LC_ALL set to "En_US" must have been the bad choice, as shown by the error message. First try fixing locale settings listed first.

Second, if using the listed commands you see something exactly (prefix matches do not count and case usually counts) like "En_US" without the quotes, then you should be okay because you are using a locale name that should be installed and available in your system. In this case, see Permanently fixing your system's locale configuration.

Permanently fixing your system's locale configuration

This is when you see something like:

        perl: warning: Please check that your locale settings:
                LC_ALL = "En_US",
                LANG = (unset)
            are supported and installed on your system.

but then cannot see that "En_US" listed by the above-mentioned commands. You may see things like "en_US.ISO8859-1", but that isn't the same. In this case, try running under a locale that you can list and which somehow matches what you tried. The rules for matching locale names are a bit vague because standardization is weak in this area. See again the Finding locales about general rules.

Fixing system locale configuration

Contact a system administrator (preferably your own) and report the exact error message you get, and ask them to read this same documentation you are now reading. They should be able to check whether there is something wrong with the locale configuration of the system. The Finding locales section is unfortunately a bit vague about the exact commands and places because these things are not that standardized.

The localeconv function

The POSIX::localeconv() function allows you to get particulars of the locale-dependent numeric formatting information specified by the current LC_NUMERIC and LC_MONETARY locales. (If you just want the name of the current locale for a particular category, use POSIX::setlocale() with a single parameter--see The setlocale function.)

        use POSIX qw(locale_h);

        # Get a reference to a hash of locale-dependent info
        $locale_values = localeconv();

        # Output sorted list of the values
        for (sort keys %$locale_values) {
            printf "%-20s = %s\n", $_, $locale_values->{$_}
        }

localeconv() takes no arguments, and returns a reference to a hash. The keys of this hash are variable names for formatting, such as decimal_point and thousands_sep. The values are the corresponding, er, values. See localeconv in the POSIX manpage for a longer example listing the categories an implementation might be expected to provide; some provide more and others fewer. You don't need an explicit use locale, because localeconv() always observes the current locale.

Here's a simple-minded example program that rewrites its command-line parameters as integers correctly formatted in the current locale:

        # See comments in previous example
        require 5.004;
        use POSIX qw(locale_h);

        # Get some of locale's numeric formatting parameters
        my ($thousands_sep, $grouping) =
             @{localeconv()}{'thousands_sep', 'grouping'};

        # Apply defaults if values are missing
        $thousands_sep = ',' unless $thousands_sep;

        # grouping and mon_grouping are packed lists
        # of small integers (characters) telling the
        # grouping (thousand_seps and mon_thousand_seps
        # being the group dividers) of numbers and
        # monetary quantities.  The integers' meanings:
        # 255 means no more grouping, 0 means repeat
        # the previous grouping, 1-254 means use that
        # as the current grouping.  Grouping goes from
        # right to left (low to high digits).  In the
        # below we cheat slightly by never using anything
        # else than the first grouping (whatever that is).
        if ($grouping) {
            @grouping = unpack("C*", $grouping);
        } else {
            @grouping = (3);
        }

        # Format command line params for current locale
        for (@ARGV) {
            $_ = int;    # Chop non-integer part
            1 while
            s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
            print "$_";
        }
        print "\n";

I18N::Langinfo

Another interface for querying locale-dependent information is the I18N::Langinfo::langinfo() function, available at least in UNIX-like systems and VMS.

The following example will import the langinfo() function itself and three constants to be used as arguments to langinfo(): a constant for the abbreviated first day of the week (the numbering starts from Sunday = 1) and two more constants for the affirmative and negative answers for a yes/no question in the current locale.

    use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);

    my ($abday_1, $yesstr, $nostr) = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);

    print "$abday_1? [$yesstr/$nostr] ";

In other words, in the "C" (or English) locale the above will probably print something like:

    Sun? [yes/no]

See the I18N::Langinfo manpage for more information.

LOCALE CATEGORIES

The following subsections describe basic locale categories. Beyond these, some combination categories allow manipulation of more than one basic category at a time. See ENVIRONMENT for a discussion of these.

Category LC_COLLATE: Collation

In the scope of use locale, Perl looks to the LC_COLLATE environment variable to determine the application's notions on collation (ordering) of characters. For example, 'b' follows 'a' in Latin alphabets, but where do 'á' and 'å' belong? And while 'color' follows 'chocolate' in English, what about in Spanish?

The following collations all make sense and you may meet any of them if you "use locale".

        A B C D E a b c d e
        A a B b C c D d E e
        a A b B c C d D e E
        a b c d e A B C D E

Here is a code snippet to tell what "word" characters are in the current locale, in that locale's order:

        use locale;
        print +(sort grep /\w/, map { chr } 0..255), "\n";

Compare this with the characters that you see and their order if you state explicitly that the locale should be ignored:

        no locale;
        print +(sort grep /\w/, map { chr } 0..255), "\n";

This machine-native collation (which is what you get unless use locale has appeared earlier in the same block) must be used for sorting raw binary data, whereas the locale-dependent collation of the first example is useful for natural text.

As noted in USING LOCALES, cmp compares according to the current collation locale when use locale is in effect, but falls back to a char-by-char comparison for strings that the locale says are equal. You can use POSIX::strcoll() if you don't want this fall-back:

        use POSIX qw(strcoll);
        $equal_in_locale =
            !strcoll("space and case ignored", "SpaceAndCaseIgnored");

$equal_in_locale will be true if the collation locale specifies a dictionary-like ordering that ignores space characters completely and which folds case.

If you have a single string that you want to check for "equality in locale" against several others, you might think you could gain a little efficiency by using POSIX::strxfrm() in conjunction with eq:

        use POSIX qw(strxfrm);
        $xfrm_string = strxfrm("Mixed-case string");
        print "locale collation ignores spaces\n"
            if $xfrm_string eq strxfrm("Mixed-casestring");
        print "locale collation ignores hyphens\n"
            if $xfrm_string eq strxfrm("Mixedcase string");
        print "locale collation ignores case\n"
            if $xfrm_string eq strxfrm("mixed-case string");

strxfrm() takes a string and maps it into a transformed string for use in char-by-char comparisons against other transformed strings during collation. "Under the hood", locale-affected Perl comparison operators call strxfrm() for both operands, then do a char-by-char comparison of the transformed strings. By calling strxfrm() explicitly and using a non locale-affected comparison, the example attempts to save a couple of transformations. But in fact, it doesn't save anything: Perl magic (see Magic Variables in the perlguts manpage) creates the transformed version of a string the first time it's needed in a comparison, then keeps this version around in case it's needed again. An example rewritten the easy way with cmp runs just about as fast. It also copes with null characters embedded in strings; if you call strxfrm() directly, it treats the first null it finds as a terminator. don't expect the transformed strings it produces to be portable across systems--or even from one revision of your operating system to the next. In short, don't call strxfrm() directly: let Perl do it for you.

Note: use locale isn't shown in some of these examples because it isn't needed: strcoll() and strxfrm() exist only to generate locale-dependent results, and so always obey the current LC_COLLATE locale.

Category LC_CTYPE: Character Types

In the scope of use locale, Perl obeys the LC_CTYPE locale setting. This controls the application's notion of which characters are alphabetic. This affects Perl's \w regular expression metanotation, which stands for alphanumeric characters--that is, alphabetic, numeric, and including other special characters such as the underscore or hyphen. (Consult the perlre manpage for more information about regular expressions.) Thanks to LC_CTYPE, depending on your locale setting, characters like 'æ', 'ð', 'ß', and 'ø' may be understood as \w characters.

The LC_CTYPE locale also provides the map used in transliterating characters between lower and uppercase. This affects the case-mapping functions--lc(), lcfirst, uc(), and ucfirst(); case-mapping interpolation with \l, \L, \u, or \U in double-quoted strings and s/// substitutions; and case-independent regular expression pattern matching using the i modifier.

Finally, LC_CTYPE affects the POSIX character-class test functions--isalpha(), islower(), and so on. For example, if you move from the "C" locale to a 7-bit Scandinavian one, you may find--possibly to your surprise--that "|" moves from the ispunct() class to isalpha().

Note: A broken or malicious LC_CTYPE locale definition may result in clearly ineligible characters being considered to be alphanumeric by your application. For strict matching of (mundane) letters and digits--for example, in command strings--locale-aware applications should use \w inside a no locale block. See SECURITY.

Category LC_NUMERIC: Numeric Formatting

In the scope of use locale, Perl obeys the LC_NUMERIC locale information, which controls an application's idea of how numbers should be formatted for human readability by the printf(), sprintf(), and write() functions. String-to-numeric conversion by the POSIX::strtod() function is also affected. In most implementations the only effect is to change the character used for the decimal point--perhaps from '.' to ','. These functions aren't aware of such niceties as thousands separation and so on. (See The localeconv function if you care about these things.)

Output produced by print() is also affected by the current locale: it depends on whether use locale or no locale is in effect, and corresponds to what you'd get from printf() in the "C" locale. The same is true for Perl's internal conversions between numeric and string formats:

        use POSIX qw(strtod);
        use locale;

        $n = 5/2;   # Assign numeric 2.5 to $n

        $a = " $n"; # Locale-dependent conversion to string

        print "half five is $n\n";       # Locale-dependent output

        printf "half five is %g\n", $n;  # Locale-dependent output

        print "DECIMAL POINT IS COMMA\n"
            if $n == (strtod("2,5"))[0]; # Locale-dependent conversion

See also the I18N::Langinfo manpage and RADIXCHAR.

Category LC_MONETARY: Formatting of monetary amounts

The C standard defines the LC_MONETARY category, but no function that is affected by its contents. (Those with experience of standards committees will recognize that the working group decided to punt on the issue.) Consequently, Perl takes no notice of it. If you really want to use LC_MONETARY, you can query its contents--see The localeconv function--and use the information that it returns in your application's own formatting of currency amounts. However, you may well find that the information, voluminous and complex though it may be, still does not quite meet your requirements: currency formatting is a hard nut to crack.

See also the I18N::Langinfo manpage and CRNCYSTR.

LC_TIME

Output produced by POSIX::strftime(), which builds a formatted human-readable date/time string, is affected by the current LC_TIME locale. Thus, in a French locale, the output produced by the %B format element (full month name) for the first month of the year would be "janvier". Here's how to get a list of long month names in the current locale:

        use POSIX qw(strftime);
        for (0..11) {
            $long_month_name[$_] =
                strftime("%B", 0, 0, 0, 1, $_, 96);
        }

Note: use locale isn't needed in this example: as a function that exists only to generate locale-dependent results, strftime() always obeys the current LC_TIME locale.

See also the I18N::Langinfo manpage and ABDAY_1..ABDAY_7, DAY_1..DAY_7, ABMON_1..ABMON_12, and ABMON_1..ABMON_12.

Other categories

The remaining locale category, LC_MESSAGES (possibly supplemented by others in particular implementations) is not currently used by Perl--except possibly to affect the behavior of library functions called by extensions outside the standard Perl distribution and by the operating system and its utilities. Note especially that the string value of $! and the error messages given by external utilities may be changed by LC_MESSAGES. If you want to have portable error codes, use %!. See the Errno manpage.

SECURITY

Although the main discussion of Perl security issues can be found in the perlsec manpage, a discussion of Perl's locale handling would be incomplete if it did not draw your attention to locale-dependent security issues. Locales--particularly on systems that allow unprivileged users to build their own locales--are untrustworthy. A malicious (or just plain broken) locale can make a locale-aware application give unexpected results. Here are a few possibilities:

  • Regular expression checks for safe file names or mail addresses using \w may be spoofed by an LC_CTYPE locale that claims that characters such as ">" and "|" are alphanumeric.

  • String interpolation with case-mapping, as in, say, $dest = "C:\U$name.$ext", may produce dangerous results if a bogus LC_CTYPE case-mapping table is in effect.

  • A sneaky LC_COLLATE locale could result in the names of students with "D" grades appearing ahead of those with "A"s.

  • An application that takes the trouble to use information in LC_MONETARY may format debits as if they were credits and vice versa if that locale has been subverted. Or it might make payments in US dollars instead of Hong Kong dollars.

  • The date and day names in dates formatted by strftime() could be manipulated to advantage by a malicious user able to subvert the LC_DATE locale. ("Look--it says I wasn't in the building on Sunday.")

Such dangers are not peculiar to the locale system: any aspect of an application's environment which may be modified maliciously presents similar challenges. Similarly, they are not specific to Perl: any programming language that allows you to write programs that take account of their environment exposes you to these issues.

Perl cannot protect you from all possibilities shown in the examples--there is no substitute for your own vigilance--but, when use locale is in effect, Perl uses the tainting mechanism (see the perlsec manpage) to mark string results that become locale-dependent, and which may be untrustworthy in consequence. Here is a summary of the tainting behavior of operators and functions that may be affected by the locale:

  • Comparison operators (lt, le, ge, gt and cmp):

    Scalar true/false (or less/equal/greater) result is never tainted.

  • Case-mapping interpolation (with \l, \L, \u or \U)

    Result string containing interpolated material is tainted if use locale is in effect.

  • Matching operator (m//):

    Scalar true/false result never tainted.

    Subpatterns, either delivered as a list-context result or as $1 etc. are tainted if use locale is in effect, and the subpattern regular expression contains \w (to match an alphanumeric character), \W (non-alphanumeric character), \s (whitespace character), or \S (non whitespace character). The matched-pattern variable, $&, $` (pre-match), $' (post-match), and $+ (last match) are also tainted if use locale is in effect and the regular expression contains \w, \W, \s, or \S.

  • Substitution operator (s///):

    Has the same behavior as the match operator. Also, the left operand of =~ becomes tainted when use locale in effect if modified as a result of a substitution based on a regular expression match involving \w, \W, \s, or \S; or of case-mapping with \l, \L,\u or \U.

  • Output formatting functions (printf() and write()):

    Results are never tainted because otherwise even output from print, for example print(1/7), should be tainted if use locale is in effect.

  • Case-mapping functions (lc(), lcfirst(), uc(), ucfirst()):

    Results are tainted if use locale is in effect.

  • POSIX locale-dependent functions (localeconv(), strcoll(), strftime(), strxfrm()):

    Results are never tainted.

  • POSIX character class tests (isalnum(), isalpha(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()):

    True/false results are never tainted.

Three examples illustrate locale-dependent tainting. The first program, which ignores its locale, won't run: a value taken directly from the command line may not be used to name an output file when taint checks are enabled.

        #/usr/local/bin/perl -T
        # Run with taint checking

        # Command line sanity check omitted...
        $tainted_output_file = shift;

        open(F, ">$tainted_output_file")
            or warn "Open of $untainted_output_file failed: $!\n";

The program can be made to run by "laundering" the tainted value through a regular expression: the second example--which still ignores locale information--runs, creating the file named on its command line if it can.

        #/usr/local/bin/perl -T

        $tainted_output_file = shift;
        $tainted_output_file =~ m%[\w/]+%;
        $untainted_output_file = $&;

        open(F, ">$untainted_output_file")
            or warn "Open of $untainted_output_file failed: $!\n";

Compare this with a similar but locale-aware program:

        #/usr/local/bin/perl -T

        $tainted_output_file = shift;
        use locale;
        $tainted_output_file =~ m%[\w/]+%;
        $localized_output_file = $&;

        open(F, ">$localized_output_file")
            or warn "Open of $localized_output_file failed: $!\n";

This third program fails to run because $& is tainted: it is the result of a match involving \w while use locale is in effect.

ENVIRONMENT

PERL_BADLANG

A string that can suppress Perl's warning about failed locale settings at startup. Failure can occur if the locale support in the operating system is lacking (broken) in some way--or if you mistyped the name of a locale when you set up your environment. If this environment variable is absent, or has a value that does not evaluate to integer zero--that is, "0" or ""-- Perl will complain about locale setting failures.

NOTE: PERL_BADLANG only gives you a way to hide the warning message. The message tells about some problem in your system's locale support, and you should investigate what the problem is.

The following environment variables are not specific to Perl: They are part of the standardized (ISO C, XPG4, POSIX 1.c) setlocale() method for controlling an application's opinion on data.

LC_ALL

LC_ALL is the "override-all" locale environment variable. If set, it overrides all the rest of the locale environment variables.

LANGUAGE

NOTE: LANGUAGE is a GNU extension, it affects you only if you are using the GNU libc. This is the case if you are using e.g. Linux. If you are using "commercial" UNIXes you are most probably not using GNU libc and you can ignore LANGUAGE.

However, in the case you are using LANGUAGE: it affects the language of informational, warning, and error messages output by commands (in other words, it's like LC_MESSAGES) but it has higher priority than LC_ALL. Moreover, it's not a single value but instead a "path" (":"-separated list) of languages (not locales). See the GNU gettext library documentation for more information.

LC_CTYPE

In the absence of LC_ALL, LC_CTYPE chooses the character type locale. In the absence of both LC_ALL and LC_CTYPE, LANG chooses the character type locale.

LC_COLLATE

In the absence of LC_ALL, LC_COLLATE chooses the collation (sorting) locale. In the absence of both LC_ALL and LC_COLLATE, LANG chooses the collation locale.

LC_MONETARY

In the absence of LC_ALL, LC_MONETARY chooses the monetary formatting locale. In the absence of both LC_ALL and LC_MONETARY, LANG chooses the monetary formatting locale.

LC_NUMERIC

In the absence of LC_ALL, LC_NUMERIC chooses the numeric format locale. In the absence of both LC_ALL and LC_NUMERIC, LANG chooses the numeric format.

LC_TIME

In the absence of LC_ALL, LC_TIME chooses the date and time formatting locale. In the absence of both LC_ALL and LC_TIME, LANG chooses the date and time formatting locale.

LANG

LANG is the "catch-all" locale environment variable. If it is set, it is used as the last resort after the overall LC_ALL and the category-specific LC_....

NOTES

Backward compatibility

Versions of Perl prior to 5.004 mostly ignored locale information, generally behaving as if something similar to the "C" locale were always in force, even if the program environment suggested otherwise (see The setlocale function). By default, Perl still behaves this way for backward compatibility. If you want a Perl application to pay attention to locale information, you must use the use locale pragma (see The use locale pragma) to instruct it to do so.

Versions of Perl from 5.002 to 5.003 did use the LC_CTYPE information if available; that is, \w did understand what were the letters according to the locale environment variables. The problem was that the user had no control over the feature: if the C library supported locales, Perl used them.

I18N:Collate obsolete

In versions of Perl prior to 5.004, per-locale collation was possible using the I18N::Collate library module. This module is now mildly obsolete and should be avoided in new applications. The LC_COLLATE functionality is now integrated into the Perl core language: One can use locale-specific scalar data completely normally with use locale, so there is no longer any need to juggle with the scalar references of I18N::Collate.

Sort speed and memory use impacts

Comparing and sorting by locale is usually slower than the default sorting; slow-downs of two to four times have been observed. It will also consume more memory: once a Perl scalar variable has participated in any string comparison or sorting operation obeying the locale collation rules, it will take 3-15 times more memory than before. (The exact multiplier depends on the string's contents, the operating system and the locale.) These downsides are dictated more by the operating system's implementation of the locale system than by Perl.

write() and LC_NUMERIC

Formats are the only part of Perl that unconditionally use information from a program's locale; if a program's environment specifies an LC_NUMERIC locale, it is always used to specify the decimal point character in formatted output. Formatted output cannot be controlled by use locale because the pragma is tied to the block structure of the program, and, for historical reasons, formats exist outside that block structure.

Freely available locale definitions

There is a large collection of locale definitions at ftp://dkuug.dk/i18n/WG15-collection . You should be aware that it is unsupported, and is not claimed to be fit for any purpose. If your system allows installation of arbitrary locales, you may find the definitions useful as they are, or as a basis for the development of your own locales.

I18n and l10n

"Internationalization" is often abbreviated as i18n because its first and last letters are separated by eighteen others. (You may guess why the internalin ... internaliti ... i18n tends to get abbreviated.) In the same way, "localization" is often abbreviated to l10n.

An imperfect standard

Internationalization, as defined in the C and POSIX standards, can be criticized as incomplete, ungainly, and having too large a granularity. (Locales apply to a whole process, when it would arguably be more useful to have them apply to a single thread, window group, or whatever.) They also have a tendency, like standards groups, to divide the world into nations, when we all know that the world can equally well be divided into bankers, bikers, gamers, and so on. But, for now, it's the only standard we've got. This may be construed as a bug.

Unicode and UTF-8

The support of Unicode is new starting from Perl version 5.6, and more fully implemented in the version 5.8. See the perluniintro manpage and the perlunicode manpage for more details.

Usually locale settings and Unicode do not affect each other, but there are exceptions, see Locales in the perlunicode manpage for examples.

BUGS

Broken systems

In certain systems, the operating system's locale support is broken and cannot be fixed or used by Perl. Such deficiencies can and will result in mysterious hangs and/or Perl core dumps when the use locale is in effect. When confronted with such a system, please report in excruciating detail to <perlbug@perl.org>, and complain to your vendor: bug fixes may exist for these problems in your operating system. Sometimes such bug fixes are called an operating system upgrade.

SEE ALSO

the I18N::Langinfo manpage, the perluniintro manpage, the perlunicode manpage, the open manpage, isalnum in the POSIX manpage, isalpha in the POSIX manpage, isdigit in the POSIX manpage, isgraph in the POSIX manpage, islower in the POSIX manpage, isprint in the POSIX manpage, ispunct in the POSIX manpage, isspace in the POSIX manpage, isupper in the POSIX manpage, isxdigit in the POSIX manpage, localeconv in the POSIX manpage, setlocale in the POSIX manpage, strcoll in the POSIX manpage, strftime in the POSIX manpage, strtod in the POSIX manpage, strxfrm in the POSIX manpage.

HISTORY

Jarkko Hietaniemi's original perli18n.pod heavily hacked by Dominic Dunlop, assisted by the perl5-porters. Prose worked over a bit by Tom Christiansen.

Last update: Thu Jun 11 08:44:13 MDT 1998


perlpacktut - tutorial on C<pack> and C<unpack>

  • The Basic Principle
  • Packing Text
  • Packing Numbers
    • Integers
    • Unpacking a Stack Frame
    • How to Eat an Egg on a Net
    • Floating point Numbers
  • Exotic Templates
    • Bit Strings
    • Uuencoding
    • Doing Sums
    • Unicode
    • Another Portable Binary Encoding
  • Template Grouping
  • Lengths and Widths
    • String Lengths
    • Dynamic Templates
    • Counting Repetitions
  • Packing and Unpacking C Structures
    • The Alignment Pit
    • Alignment, Take 2
    • Alignment, Take 3
    • Pointers for How to Use Them
  • Pack Recipes
  • Funnies Section
  • Authors

NAME

perlpacktut - tutorial on pack and unpack

DESCRIPTION

pack and unpack are two functions for transforming data according to a user-defined template, between the guarded way Perl stores values and some well-defined representation as might be required in the environment of a Perl program. Unfortunately, they're also two of the most misunderstood and most often overlooked functions that Perl provides. This tutorial will demystify them for you.

The Basic Principle

Most programming languages don't shelter the memory where variables are stored. In C, for instance, you can take the address of some variable, and the sizeof operator tells you how many bytes are allocated to the variable. Using the address and the size, you may access the storage to your heart's content.

In Perl, you just can't access memory at random, but the structural and representational conversion provided by pack and unpack is an excellent alternative. The pack function converts values to a byte sequence containing representations according to a given specification, the so-called "template" argument. unpack is the reverse process, deriving some values from the contents of a string of bytes. (Be cautioned, however, that not all that has been packed together can be neatly unpacked - a very common experience as seasoned travellers are likely to confirm.)

Why, you may ask, would you need a chunk of memory containing some values in binary representation? One good reason is input and output accessing some file, a device, or a network connection, whereby this binary representation is either forced on you or will give you some benefit in processing. Another cause is passing data to some system call that is not available as a Perl function: syscall requires you to provide parameters stored in the way it happens in a C program. Even text processing (as shown in the next section) may be simplified with judicious usage of these two functions.

To see how (un)packing works, we'll start with a simple template code where the conversion is in low gear: between the contents of a byte sequence and a string of hexadecimal digits. Let's use unpack, since this is likely to remind you of a dump program, or some desperate last message unfortunate programs are wont to throw at you before they expire into the wild blue yonder. Assuming that the variable $mem holds a sequence of bytes that we'd like to inspect without assuming anything about its meaning, we can write

   my( $hex ) = unpack( 'H*', $mem );
   print "$hex\n";

whereupon we might see something like this, with each pair of hex digits corresponding to a byte:

   41204d414e204120504c414e20412043414e414c2050414e414d41

What was in this chunk of memory? Numbers, characters, or a mixture of both? Assuming that we're on a computer where ASCII (or some similar) encoding is used: hexadecimal values in the range 0x40 - 0x5A indicate an uppercase letter, and 0x20 encodes a space. So we might assume it is a piece of text, which some are able to read like a tabloid; but others will have to get hold of an ASCII table and relive that firstgrader feeling. Not caring too much about which way to read this, we note that unpack with the template code H converts the contents of a sequence of bytes into the customary hexadecimal notation. Since "a sequence of" is a pretty vague indication of quantity, H has been defined to convert just a single hexadecimal digit unless it is followed by a repeat count. An asterisk for the repeat count means to use whatever remains.

The inverse operation - packing byte contents from a string of hexadecimal digits - is just as easily written. For instance:

   my $s = pack( 'H2' x 10, map { "3$_" } ( 0..9 ) );
   print "$s\n";

Since we feed a list of ten 2-digit hexadecimal strings to pack, the pack template should contain ten pack codes. If this is run on a computer with ASCII character coding, it will print 0123456789.

Packing Text

Let's suppose you've got to read in a data file like this:

    Date      |Description                | Income|Expenditure
    01/24/2001 Ahmed's Camel Emporium                  1147.99
    01/28/2001 Flea spray                                24.99
    01/29/2001 Camel rides to tourists      235.00

How do we do it? You might think first to use split; however, since split collapses blank fields, you'll never know whether a record was income or expenditure. Oops. Well, you could always use substr:

    while (<>) {
        my $date   = substr($_,  0, 11);
        my $desc   = substr($_, 12, 27);
        my $income = substr($_, 40,  7);
        my $expend = substr($_, 52,  7);
        ...
    }

It's not really a barrel of laughs, is it? In fact, it's worse than it may seem; the eagle-eyed may notice that the first field should only be 10 characters wide, and the error has propagated right through the other numbers - which we've had to count by hand. So it's error-prone as well as horribly unfriendly.

Or maybe we could use regular expressions:

    while (<>) {
        my($date, $desc, $income, $expend) =
            m|(\d\d/\d\d/\d{4}) (.{27}) (.{7})(.*)|;
        ...
    }

Urgh. Well, it's a bit better, but - well, would you want to maintain that?

Hey, isn't Perl supposed to make this sort of thing easy? Well, it does, if you use the right tools. pack and unpack are designed to help you out when dealing with fixed-width data like the above. Let's have a look at a solution with unpack:

    while (<>) {
        my($date, $desc, $income, $expend) = unpack("A10xA27xA7A*", $_);
        ...
    }

That looks a bit nicer; but we've got to take apart that weird template. Where did I pull that out of?

OK, let's have a look at some of our data again; in fact, we'll include the headers, and a handy ruler so we can keep track of where we are.

             1         2         3         4         5
    1234567890123456789012345678901234567890123456789012345678
    Date      |Description                | Income|Expenditure
    01/28/2001 Flea spray                                24.99
    01/29/2001 Camel rides to tourists      235.00

From this, we can see that the date column stretches from column 1 to column 10 - ten characters wide. The pack-ese for "character" is A, and ten of them are A10. So if we just wanted to extract the dates, we could say this:

    my($date) = unpack("A10", $_);

OK, what's next? Between the date and the description is a blank column; we want to skip over that. The x template means "skip forward", so we want one of those. Next, we have another batch of characters, from 12 to 38. That's 27 more characters, hence A27. (Don't make the fencepost error - there are 27 characters between 12 and 38, not 26. Count 'em!)

Now we skip another character and pick up the next 7 characters:

    my($date,$description,$income) = unpack("A10xA27xA7", $_);

Now comes the clever bit. Lines in our ledger which are just income and not expenditure might end at column 46. Hence, we don't want to tell our unpack pattern that we need to find another 12 characters; we'll just say "if there's anything left, take it". As you might guess from regular expressions, that's what the * means: "use everything remaining".

  • Be warned, though, that unlike regular expressions, if the unpack template doesn't match the incoming data, Perl will scream and die.

Hence, putting it all together:

    my($date,$description,$income,$expend) = unpack("A10xA27xA7xA*", $_);

Now, that's our data parsed. I suppose what we might want to do now is total up our income and expenditure, and add another line to the end of our ledger - in the same format - saying how much we've brought in and how much we've spent:

    while (<>) {
        my($date, $desc, $income, $expend) = unpack("A10xA27xA7xA*", $_);
        $tot_income += $income;
        $tot_expend += $expend;
    }

    $tot_income = sprintf("%.2f", $tot_income); # Get them into
    $tot_expend = sprintf("%.2f", $tot_expend); # "financial" format

    $date = POSIX::strftime("%m/%d/%Y", localtime);

    # OK, let's go:

    print pack("A10xA27xA7xA*", $date, "Totals", $tot_income, $tot_expend);

Oh, hmm. That didn't quite work. Let's see what happened:

    01/24/2001 Ahmed's Camel Emporium                   1147.99
    01/28/2001 Flea spray                                 24.99
    01/29/2001 Camel rides to tourists     1235.00
    03/23/2001Totals                     1235.001172.98

OK, it's a start, but what happened to the spaces? We put x, didn't we? Shouldn't it skip forward? Let's look at what pack in the perlfunc manpage says:

    x   A null byte.

Urgh. No wonder. There's a big difference between "a null byte", character zero, and "a space", character 32. Perl's put something between the date and the description - but unfortunately, we can't see it!

What we actually need to do is expand the width of the fields. The A format pads any non-existent characters with spaces, so we can use the additional spaces to line up our fields, like this:

    print pack("A11 A28 A8 A*", $date, "Totals", $tot_income, $tot_expend);

(Note that you can put spaces in the template to make it more readable, but they don't translate to spaces in the output.) Here's what we got this time:

    01/24/2001 Ahmed's Camel Emporium                   1147.99
    01/28/2001 Flea spray                                 24.99
    01/29/2001 Camel rides to tourists     1235.00
    03/23/2001 Totals                      1235.00 1172.98

That's a bit better, but we still have that last column which needs to be moved further over. There's an easy way to fix this up: unfortunately, we can't get pack to right-justify our fields, but we can get sprintf to do it:

    $tot_income = sprintf("%.2f", $tot_income);
    $tot_expend = sprintf("%12.2f", $tot_expend);
    $date = POSIX::strftime("%m/%d/%Y", localtime);
    print pack("A11 A28 A8 A*", $date, "Totals", $tot_income, $tot_expend);

This time we get the right answer:

    01/28/2001 Flea spray                                 24.99
    01/29/2001 Camel rides to tourists     1235.00
    03/23/2001 Totals                      1235.00      1172.98

So that's how we consume and produce fixed-width data. Let's recap what we've seen of pack and unpack so far:

  • Use pack to go from several pieces of data to one fixed-width version; use unpack to turn a fixed-width-format string into several pieces of data.

  • The pack format A means "any character"; if you're packing and you've run out of things to pack, pack will fill the rest up with spaces.

  • x means "skip a byte" when unpacking; when packing, it means "introduce a null byte" - that's probably not what you mean if you're dealing with plain text.

  • You can follow the formats with numbers to say how many characters should be affected by that format: A12 means "take 12 characters"; x6 means "skip 6 bytes" or "character 0, 6 times".

  • Instead of a number, you can use * to mean "consume everything else left".

    Warning: when packing multiple pieces of data, * only means "consume all of the current piece of data". That's to say

        pack("A*A*", $one, $two)

    packs all of $one into the first A* and then all of $two into the second. This is a general principle: each format character corresponds to one piece of data to be packed.

Packing Numbers

So much for textual data. Let's get onto the meaty stuff that pack and unpack are best at: handling binary formats for numbers. There is, of course, not just one binary format - life would be too simple - but Perl will do all the finicky labor for you.

Integers

Packing and unpacking numbers implies conversion to and from some specific binary representation. Leaving floating point numbers aside for the moment, the salient properties of any such representation are:

  • the number of bytes used for storing the integer,

  • whether the contents are interpreted as a signed or unsigned number,

  • the byte ordering: whether the first byte is the least or most significant byte (or: little-endian or big-endian, respectively).

So, for instance, to pack 20302 to a signed 16 bit integer in your computer's representation you write

   my $ps = pack( 's', 20302 );

Again, the result is a string, now containing 2 bytes. If you print this string (which is, generally, not recommended) you might see ON or NO (depending on your system's byte ordering) - or something entirely different if your computer doesn't use ASCII character encoding. Unpacking $ps with the same template returns the original integer value:

   my( $s ) = unpack( 's', $ps );

This is true for all numeric template codes. But don't expect miracles: if the packed value exceeds the allotted byte capacity, high order bits are silently discarded, and unpack certainly won't be able to pull them back out of some magic hat. And, when you pack using a signed template code such as s, an excess value may result in the sign bit getting set, and unpacking this will smartly return a negative value.

16 bits won't get you too far with integers, but there is l and L for signed and unsigned 32-bit integers. And if this is not enough and your system supports 64 bit integers you can push the limits much closer to infinity with pack codes q and Q. A notable exception is provided by pack codes i and I for signed and unsigned integers of the "local custom" variety: Such an integer will take up as many bytes as a local C compiler returns for sizeof(int), but it'll use at least 32 bits.

Each of the integer pack codes sSlLqQ results in a fixed number of bytes, no matter where you execute your program. This may be useful for some applications, but it does not provide for a portable way to pass data structures between Perl and C programs (bound to happen when you call XS extensions or the Perl function syscall), or when you read or write binary files. What you'll need in this case are template codes that depend on what your local C compiler compiles when you code short or unsigned long, for instance. These codes and their corresponding byte lengths are shown in the table below. Since the C standard leaves much leeway with respect to the relative sizes of these data types, actual values may vary, and that's why the values are given as expressions in C and Perl. (If you'd like to use values from %Config in your program you have to import it with use Config.)

   signed unsigned  byte length in C   byte length in Perl
     s!     S!      sizeof(short)      $Config{shortsize}
     i!     I!      sizeof(int)        $Config{intsize}
     l!     L!      sizeof(long)       $Config{longsize}
     q!     Q!      sizeof(long long)  $Config{longlongsize}

The i! and I! codes aren't different from i and I; they are tolerated for completeness' sake.

Unpacking a Stack Frame

Requesting a particular byte ordering may be necessary when you work with binary data coming from some specific architecture whereas your program could run on a totally different system. As an example, assume you have 24 bytes containing a stack frame as it happens on an Intel 8086:

      +---------+        +----+----+               +---------+
 TOS: |   IP    |  TOS+4:| FL | FH | FLAGS  TOS+14:|   SI    |
      +---------+        +----+----+               +---------+
      |   CS    |        | AL | AH | AX            |   DI    |
      +---------+        +----+----+               +---------+
                         | BL | BH | BX            |   BP    |
                         +----+----+               +---------+
                         | CL | CH | CX            |   DS    |
                         +----+----+               +---------+
                         | DL | DH | DX            |   ES    |
                         +----+----+               +---------+

First, we note that this time-honored 16-bit CPU uses little-endian order, and that's why the low order byte is stored at the lower address. To unpack such a (signed) short we'll have to use code v. A repeat count unpacks all 12 shorts:

   my( $ip, $cs, $flags, $ax, $bx, $cd, $dx, $si, $di, $bp, $ds, $es ) =
     unpack( 'v12', $frame );

Alternatively, we could have used C to unpack the individually accessible byte registers FL, FH, AL, AH, etc.:

   my( $fl, $fh, $al, $ah, $bl, $bh, $cl, $ch, $dl, $dh ) =
     unpack( 'C10', substr( $frame, 4, 10 ) );

It would be nice if we could do this in one fell swoop: unpack a short, back up a little, and then unpack 2 bytes. Since Perl is nice, it proffers the template code X to back up one byte. Putting this all together, we may now write:

   my( $ip, $cs,
       $flags,$fl,$fh,
       $ax,$al,$ah, $bx,$bl,$bh, $cx,$cl,$ch, $dx,$dl,$dh,
       $si, $di, $bp, $ds, $es ) =
   unpack( 'v2' . ('vXXCC' x 5) . 'v5', $frame );

(The clumsy construction of the template can be avoided - just read on!)

We've taken some pains to construct the template so that it matches the contents of our frame buffer. Otherwise we'd either get undefined values, or unpack could not unpack all. If pack runs out of items, it will supply null strings (which are coerced into zeroes whenever the pack code says so).

How to Eat an Egg on a Net

The pack code for big-endian (high order byte at the lowest address) is n for 16 bit and N for 32 bit integers. You use these codes if you know that your data comes from a compliant architecture, but, surprisingly enough, you should also use these pack codes if you exchange binary data, across the network, with some system that you know next to nothing about. The simple reason is that this order has been chosen as the network order, and all standard-fearing programs ought to follow this convention. (This is, of course, a stern backing for one of the Lilliputian parties and may well influence the political development there.) So, if the protocol expects you to send a message by sending the length first, followed by just so many bytes, you could write:

   my $buf = pack( 'N', length( $msg ) ) . $msg;

or even:

   my $buf = pack( 'NA*', length( $msg ), $msg );

and pass $buf to your send routine. Some protocols demand that the count should include the length of the count itself: then just add 4 to the data length. (But make sure to read Lengths and Widths before you really code this!)

Floating point Numbers

For packing floating point numbers you have the choice between the pack codes f and d which pack into (or unpack from) single-precision or double-precision representation as it is provided by your system. (There is no such thing as a network representation for reals, so if you want to send your real numbers across computer boundaries, you'd better stick to ASCII representation, unless you're absolutely sure what's on the other end of the line.)

Exotic Templates

Bit Strings

Bits are the atoms in the memory world. Access to individual bits may have to be used either as a last resort or because it is the most convenient way to handle your data. Bit string (un)packing converts between strings containing a series of 0 and 1 characters and a sequence of bytes each containing a group of 8 bits. This is almost as simple as it sounds, except that there are two ways the contents of a byte may be written as a bit string. Let's have a look at an annotated byte:

     7 6 5 4 3 2 1 0
   +-----------------+
   | 1 0 0 0 1 1 0 0 |
   +-----------------+
    MSB           LSB

It's egg-eating all over again: Some think that as a bit string this should be written "10001100" i.e. beginning with the most significant bit, others insist on "00110001". Well, Perl isn't biased, so that's why we have two bit string codes:

   $byte = pack( 'B8', '10001100' ); # start with MSB
   $byte = pack( 'b8', '00110001' ); # start with LSB

It is not possible to pack or unpack bit fields - just integral bytes. pack always starts at the next byte boundary and "rounds up" to the next multiple of 8 by adding zero bits as required. (If you do want bit fields, there is vec in the perlfunc manpage. Or you could implement bit field handling at the character string level, using split, substr, and concatenation on unpacked bit strings.)

To illustrate unpacking for bit strings, we'll decompose a simple status register (a "-" stands for a "reserved" bit):

   +-----------------+-----------------+
   | S Z - A - P - C | - - - - O D I T |
   +-----------------+-----------------+
    MSB           LSB MSB           LSB

Converting these two bytes to a string can be done with the unpack template 'b16'. To obtain the individual bit values from the bit string we use split with the "empty" separator pattern which dissects into individual characters. Bit values from the "reserved" positions are simply assigned to undef, a convenient notation for "I don't care where this goes".

   ($carry, undef, $parity, undef, $auxcarry, undef, $zero, $sign,
    $trace, $interrupt, $direction, $overflow) =
      split( //, unpack( 'b16', $status ) );

We could have used an unpack template 'b12' just as well, since the last 4 bits can be ignored anyway.

Uuencoding

Another odd-man-out in the template alphabet is u, which packs an "uuencoded string". ("uu" is short for Unix-to-Unix.) Chances are that you won't ever need this encoding technique which was invented to overcome the shortcomings of old-fashioned transmission mediums that do not support other than simple ASCII data. The essential recipe is simple: Take three bytes, or 24 bits. Split them into 4 six-packs, adding a space (0x20) to each. Repeat until all of the data is blended. Fold groups of 4 bytes into lines no longer than 60 and garnish them in front with the original byte count (incremented by 0x20) and a "\n" at the end. - The pack chef will prepare this for you, a la minute, when you select pack code u on the menu:

   my $uubuf = pack( 'u', $bindat );

A repeat count after u sets the number of bytes to put into an uuencoded line, which is the maximum of 45 by default, but could be set to some (smaller) integer multiple of three. unpack simply ignores the repeat count.

Doing Sums

An even stranger template code is %<number>. First, because it's used as a prefix to some other template code. Second, because it cannot be used in pack at all, and third, in unpack, doesn't return the data as defined by the template code it precedes. Instead it'll give you an integer of number bits that is computed from the data value by doing sums. For numeric unpack codes, no big feat is achieved:

    my $buf = pack( 'iii', 100, 20, 3 );
    print unpack( '%32i3', $buf ), "\n";  # prints 123

For string values, % returns the sum of the byte values saving you the trouble of a sum loop with substr and ord:

    print unpack( '%32A*', "\x01\x10" ), "\n";  # prints 17

Although the % code is documented as returning a "checksum": don't put your trust in such values! Even when applied to a small number of bytes, they won't guarantee a noticeable Hamming distance.

In connection with b or B, % simply adds bits, and this can be put to good use to count set bits efficiently:

    my $bitcount = unpack( '%32b*', $mask );

And an even parity bit can be determined like this:

    my $evenparity = unpack( '%1b*', $mask );

Unicode

Unicode is a character set that can represent most characters in most of the world's languages, providing room for over one million different characters. Unicode 3.1 specifies 94,140 characters: The Basic Latin characters are assigned to the numbers 0 - 127. The Latin-1 Supplement with characters that are used in several European languages is in the next range, up to 255. After some more Latin extensions we find the character sets from languages using non-Roman alphabets, interspersed with a variety of symbol sets such as currency symbols, Zapf Dingbats or Braille. (You might want to visit www.unicode.org for a look at some of them - my personal favourites are Telugu and Kannada.)

The Unicode character sets associates characters with integers. Encoding these numbers in an equal number of bytes would more than double the requirements for storing texts written in Latin alphabets. The UTF-8 encoding avoids this by storing the most common (from a western point of view) characters in a single byte while encoding the rarer ones in three or more bytes.

So what has this got to do with pack? Well, if you want to convert between a Unicode number and its UTF-8 representation you can do so by using template code U. As an example, let's produce the UTF-8 representation of the Euro currency symbol (code number 0x20AC):

   $UTF8{Euro} = pack( 'U', 0x20AC );

Inspecting $UTF8{Euro} shows that it contains 3 bytes: "\xe2\x82\xac". The round trip can be completed with unpack:

   $Unicode{Euro} = unpack( 'U', $UTF8{Euro} );

Usually you'll want to pack or unpack UTF-8 strings:

   # pack and unpack the Hebrew alphabet
   my $alefbet = pack( 'U*', 0x05d0..0x05ea );
   my @hebrew = unpack( 'U*', $utf );

Another Portable Binary Encoding

The pack code w has been added to support a portable binary data encoding scheme that goes way beyond simple integers. (Details can be found at Casbah.org, the Scarab project.) A BER (Binary Encoded Representation) compressed unsigned integer stores base 128 digits, most significant digit first, with as few digits as possible. Bit eight (the high bit) is set on each byte except the last. There is no size limit to BER encoding, but Perl won't go to extremes.

   my $berbuf = pack( 'w*', 1, 128, 128+1, 128*128+127 );

A hex dump of $berbuf, with spaces inserted at the right places, shows 01 8100 8101 81807F. Since the last byte is always less than 128, unpack knows where to stop.

Template Grouping

Prior to Perl 5.8, repetitions of templates had to be made by x-multiplication of template strings. Now there is a better way as we may use the pack codes ( and ) combined with a repeat count. The unpack template from the Stack Frame example can simply be written like this:

   unpack( 'v2 (vXXCC)5 v5', $frame )

Let's explore this feature a little more. We'll begin with the equivalent of

   join( '', map( substr( $_, 0, 1 ), @str ) )

which returns a string consisting of the first character from each string. Using pack, we can write

   pack( '(A)'.@str, @str )

or, because a repeat count * means "repeat as often as required", simply

   pack( '(A)*', @str )

(Note that the template A* would only have packed $str[0] in full length.)

To pack dates stored as triplets ( day, month, year ) in an array @dates into a sequence of byte, byte, short integer we can write

   $pd = pack( '(CCS)*', map( @$_, @dates ) );

To swap pairs of characters in a string (with even length) one could use several techniques. First, let's use x and X to skip forward and back:

   $s = pack( '(A)*', unpack( '(xAXXAx)*', $s ) );

We can also use @ to jump to an offset, with 0 being the position where we were when the last ( was encountered:

   $s = pack( '(A)*', unpack( '(@1A @0A @2)*', $s ) );

Finally, there is also an entirely different approach by unpacking big endian shorts and packing them in the reverse byte order:

   $s = pack( '(v)*', unpack( '(n)*', $s );

Lengths and Widths

String Lengths

In the previous section we've seen a network message that was constructed by prefixing the binary message length to the actual message. You'll find that packing a length followed by so many bytes of data is a frequently used recipe since appending a null byte won't work if a null byte may be part of the data. Here is an example where both techniques are used: after two null terminated strings with source and destination address, a Short Message (to a mobile phone) is sent after a length byte:

   my $msg = pack( 'Z*Z*CA*', $src, $dst, length( $sm ), $sm );

Unpacking this message can be done with the same template:

   ( $src, $dst, $len, $sm ) = unpack( 'Z*Z*CA*', $msg );

There's a subtle trap lurking in the offing: Adding another field after the Short Message (in variable $sm) is all right when packing, but this cannot be unpacked naively:

   # pack a message
   my $msg = pack( 'Z*Z*CA*C', $src, $dst, length( $sm ), $sm, $prio );

   # unpack fails - $prio remains undefined!
   ( $src, $dst, $len, $sm, $prio ) = unpack( 'Z*Z*CA*C', $msg );

The pack code A* gobbles up all remaining bytes, and $prio remains undefined! Before we let disappointment dampen the morale: Perl's got the trump card to make this trick too, just a little further up the sleeve. Watch this:

   # pack a message: ASCIIZ, ASCIIZ, length/string, byte
   my $msg = pack( 'Z* Z* C/A* C', $src, $dst, $sm, $prio );

   # unpack
   ( $src, $dst, $sm, $prio ) = unpack( 'Z* Z* C/A* C', $msg );

Combining two pack codes with a slash (/) associates them with a single value from the argument list. In pack, the length of the argument is taken and packed according to the first code while the argument itself is added after being converted with the template code after the slash. This saves us the trouble of inserting the length call, but it is in unpack where we really score: The value of the length byte marks the end of the string to be taken from the buffer. Since this combination doesn't make sense except when the second pack code isn't a*, A* or Z*, Perl won't let you.

The pack code preceding / may be anything that's fit to represent a number: All the numeric binary pack codes, and even text codes such as A4 or Z*:

   # pack/unpack a string preceded by its length in ASCII
   my $buf = pack( 'A4/A*', "Humpty-Dumpty" );
   # unpack $buf: '13  Humpty-Dumpty'
   my $txt = unpack( 'A4/A*', $buf );

/ is not implemented in Perls before 5.6, so if your code is required to work on older Perls you'll need to unpack( 'Z* Z* C') to get the length, then use it to make a new unpack string. For example

   # pack a message: ASCIIZ, ASCIIZ, length, string, byte (5.005 compatible)
   my $msg = pack( 'Z* Z* C A* C', $src, $dst, length $sm, $sm, $prio );

   # unpack
   ( undef, undef, $len) = unpack( 'Z* Z* C', $msg );
   ($src, $dst, $sm, $prio) = unpack ( "Z* Z* x A$len C", $msg );

But that second unpack is rushing ahead. It isn't using a simple literal string for the template. So maybe we should introduce...

Dynamic Templates

So far, we've seen literals used as templates. If the list of pack items doesn't have fixed length, an expression constructing the template is required (whenever, for some reason, ()* cannot be used). Here's an example: To store named string values in a way that can be conveniently parsed by a C program, we create a sequence of names and null terminated ASCII strings, with = between the name and the value, followed by an additional delimiting null byte. Here's how:

   my $env = pack( '(A*A*Z*)' . keys( %Env ) . 'C',
                   map( { ( $_, '=', $Env{$_} ) } keys( %Env ) ), 0 );

Let's examine the cogs of this byte mill, one by one. There's the map call, creating the items we intend to stuff into the $env buffer: to each key (in $_) it adds the = separator and the hash entry value. Each triplet is packed with the template code sequence A*A*Z* that is repeated according to the number of keys. (Yes, that's what the keys function returns in scalar context.) To get the very last null byte, we add a 0 at the end of the pack list, to be packed with C. (Attentive readers may have noticed that we could have omitted the 0.)

For the reverse operation, we'll have to determine the number of items in the buffer before we can let unpack rip it apart:

   my $n = $env =~ tr/\0// - 1;
   my %env = map( split( /=/, $_ ), unpack( "(Z*)$n", $env ) );

The tr counts the null bytes. The unpack call returns a list of name-value pairs each of which is taken apart in the map block.

Counting Repetitions

Rather than storing a sentinel at the end of a data item (or a list of items), we could precede the data with a count. Again, we pack keys and values of a hash, preceding each with an unsigned short length count, and up front we store the number of pairs:

   my $env = pack( 'S(S/A* S/A*)*', scalar keys( %Env ), %Env );

This simplifies the reverse operation as the number of repetitions can be unpacked with the / code:

   my %env = unpack( 'S/(S/A* S/A*)', $env );

Note that this is one of the rare cases where you cannot use the same template for pack and unpack because pack can't determine a repeat count for a ()-group.

Packing and Unpacking C Structures

In previous sections we have seen how to pack numbers and character strings. If it were not for a couple of snags we could conclude this section right away with the terse remark that C structures don't contain anything else, and therefore you already know all there is to it. Sorry, no: read on, please.

The Alignment Pit

In the consideration of speed against memory requirements the balance has been tilted in favor of faster execution. This has influenced the way C compilers allocate memory for structures: On architectures where a 16-bit or 32-bit operand can be moved faster between places in memory, or to or from a CPU register, if it is aligned at an even or multiple-of-four or even at a multiple-of eight address, a C compiler will give you this speed benefit by stuffing extra bytes into structures. If you don't cross the C shoreline this is not likely to cause you any grief (although you should care when you design large data structures, or you want your code to be portable between architectures (you do want that, don't you?)).

To see how this affects pack and unpack, we'll compare these two C structures:

   typedef struct {
     char     c1;
     short    s;
     char     c2;
     long     l;
   } gappy_t;

   typedef struct {
     long     l;
     short    s;
     char     c1;
     char     c2;
   } dense_t;

Typically, a C compiler allocates 12 bytes to a gappy_t variable, but requires only 8 bytes for a dense_t. After investigating this further, we can draw memory maps, showing where the extra 4 bytes are hidden:

   0           +4          +8          +12
   +--+--+--+--+--+--+--+--+--+--+--+--+
   |c1|xx|  s  |c2|xx|xx|xx|     l     |    xx = fill byte
   +--+--+--+--+--+--+--+--+--+--+--+--+
   gappy_t
   0           +4          +8
   +--+--+--+--+--+--+--+--+
   |     l     |  h  |c1|c2|
   +--+--+--+--+--+--+--+--+
   dense_t

And that's where the first quirk strikes: pack and unpack templates have to be stuffed with x codes to get those extra fill bytes.

The natural question: "Why can't Perl compensate for the gaps?" warrants an answer. One good reason is that C compilers might provide (non-ANSI) extensions permitting all sorts of fancy control over the way structures are aligned, even at the level of an individual structure field. And, if this were not enough, there is an insidious thing called union where the amount of fill bytes cannot be derived from the alignment of the next item alone.

OK, so let's bite the bullet. Here's one way to get the alignment right by inserting template codes x, which don't take a corresponding item from the list:

  my $gappy = pack( 'cxs cxxx l!', $c1, $s, $c2, $l );

Note the ! after l: We want to make sure that we pack a long integer as it is compiled by our C compiler. And even now, it will only work for the platforms where the compiler aligns things as above. And somebody somewhere has a platform where it doesn't. [Probably a Cray, where shorts, ints and longs are all 8 bytes. :-)]

Counting bytes and watching alignments in lengthy structures is bound to be a drag. Isn't there a way we can create the template with a simple program? Here's a C program that does the trick:

   #include <stdio.h>
   #include <stddef.h>

   typedef struct {
     char     fc1;
     short    fs;
     char     fc2;
     long     fl;
   } gappy_t;

   #define Pt(struct,field,tchar) \
     printf( "@%d%s ", offsetof(struct,field), # tchar );

   int main() {
     Pt( gappy_t, fc1, c  );
     Pt( gappy_t, fs,  s! );
     Pt( gappy_t, fc2, c  );
     Pt( gappy_t, fl,  l! );
     printf( "\n" );
   }

The output line can be used as a template in a pack or unpack call:

  my $gappy = pack( '@0c @2s! @4c @8l!', $c1, $s, $c2, $l );

Gee, yet another template code - as if we hadn't plenty. But @ saves our day by enabling us to specify the offset from the beginning of the pack buffer to the next item: This is just the value the offsetof macro (defined in <stddef.h>) returns when given a struct type and one of its field names ("member-designator" in C standardese).

Neither using offsets nor adding x's to bridge the gaps is satisfactory. (Just imagine what happens if the structure changes.) What we really need is a way of saying "skip as many bytes as required to the next multiple of N". In fluent Templatese, you say this with x!N where N is replaced by the appropriate value. Here's the next version of our struct packaging:

  my $gappy = pack( 'c x!2 s c x!4 l!', $c1, $s, $c2, $l );

That's certainly better, but we still have to know how long all the integers are, and portability is far away. Rather than 2, for instance, we want to say "however long a short is". But this can be done by enclosing the appropriate pack code in brackets: [s]. So, here's the very best we can do:

  my $gappy = pack( 'c x![s] s c x![l!] l!', $c1, $s, $c2, $l );

Alignment, Take 2

I'm afraid that we're not quite through with the alignment catch yet. The hydra raises another ugly head when you pack arrays of structures:

   typedef struct {
     short    count;
     char     glyph;
   } cell_t;

   typedef cell_t buffer_t[BUFLEN];

Where's the catch? Padding is neither required before the first field count, nor between this and the next field glyph, so why can't we simply pack like this:

   # something goes wrong here:
   pack( 's!a' x @buffer,
         map{ ( $_->{count}, $_->{glyph} ) } @buffer );

This packs 3*@buffer bytes, but it turns out that the size of buffer_t is four times BUFLEN! The moral of the story is that the required alignment of a structure or array is propagated to the next higher level where we have to consider padding at the end of each component as well. Thus the correct template is:

   pack( 's!ax' x @buffer,
         map{ ( $_->{count}, $_->{glyph} ) } @buffer );

Alignment, Take 3

And even if you take all the above into account, ANSI still lets this:

   typedef struct {
     char     foo[2];
   } foo_t;

vary in size. The alignment constraint of the structure can be greater than any of its elements. [And if you think that this doesn't affect anything common, dismember the next cellphone that you see. Many have ARM cores, and the ARM structure rules make sizeof (foo_t) == 4]

Pointers for How to Use Them

The title of this section indicates the second problem you may run into sooner or later when you pack C structures. If the function you intend to call expects a, say, void * value, you cannot simply take a reference to a Perl variable. (Although that value certainly is a memory address, it's not the address where the variable's contents are stored.)

Template code P promises to pack a "pointer to a fixed length string". Isn't this what we want? Let's try:

    # allocate some storage and pack a pointer to it
    my $memory = "\x00" x $size;
    my $memptr = pack( 'P', $memory );

But wait: doesn't pack just return a sequence of bytes? How can we pass this string of bytes to some C code expecting a pointer which is, after all, nothing but a number? The answer is simple: We have to obtain the numeric address from the bytes returned by pack.

    my $ptr = unpack( 'L!', $memptr );

Obviously this assumes that it is possible to typecast a pointer to an unsigned long and vice versa, which frequently works but should not be taken as a universal law. - Now that we have this pointer the next question is: How can we put it to good use? We need a call to some C function where a pointer is expected. The read(2) system call comes to mind:

    ssize_t read(int fd, void *buf, size_t count);

After reading the perlfunc manpage explaining how to use syscall we can write this Perl function copying a file to standard output:

    require 'syscall.ph';
    sub cat($){
        my $path = shift();
        my $size = -s $path;
        my $memory = "\x00" x $size;  # allocate some memory
        my $ptr = unpack( 'L', pack( 'P', $memory ) );
        open( F, $path ) || die( "$path: cannot open ($!)\n" );
        my $fd = fileno(F);
        my $res = syscall( &SYS_read, fileno(F), $ptr, $size );
        print $memory;
        close( F );
    }

This is neither a specimen of simplicity nor a paragon of portability but it illustrates the point: We are able to sneak behind the scenes and access Perl's otherwise well-guarded memory! (Important note: Perl's syscall does not require you to construct pointers in this roundabout way. You simply pass a string variable, and Perl forwards the address.)

How does unpack with P work? Imagine some pointer in the buffer about to be unpacked: If it isn't the null pointer (which will smartly produce the undef value) we have a start address - but then what? Perl has no way of knowing how long this "fixed length string" is, so it's up to you to specify the actual size as an explicit length after P.

   my $mem = "abcdefghijklmn";
   print unpack( 'P5', pack( 'P', $mem ) ); # prints "abcde"

As a consequence, pack ignores any number or * after P.

Now that we have seen P at work, we might as well give p a whirl. Why do we need a second template code for packing pointers at all? The answer lies behind the simple fact that an unpack with p promises a null-terminated string starting at the address taken from the buffer, and that implies a length for the data item to be returned:

   my $buf = pack( 'p', "abc\x00efhijklmn" );
   print unpack( 'p', $buf );    # prints "abc"

Albeit this is apt to be confusing: As a consequence of the length being implied by the string's length, a number after pack code p is a repeat count, not a length as after P.

Using pack(..., $x) with P or p to get the address where $x is actually stored must be used with circumspection. Perl's internal machinery considers the relation between a variable and that address as its very own private matter and doesn't really care that we have obtained a copy. Therefore:

  • Do not use pack with p or P to obtain the address of variable that's bound to go out of scope (and thereby freeing its memory) before you are done with using the memory at that address.

  • Be very careful with Perl operations that change the value of the variable. Appending something to the variable, for instance, might require reallocation of its storage, leaving you with a pointer into no-man's land.

  • Don't think that you can get the address of a Perl variable when it is stored as an integer or double number! pack('P', $x) will force the variable's internal representation to string, just as if you had written something like $x .= ''.

It's safe, however, to P- or p-pack a string literal, because Perl simply allocates an anonymous variable.

Pack Recipes

Here are a collection of (possibly) useful canned recipes for pack and unpack:

    # Convert IP address for socket functions
    pack( "C4", split /\./, "123.4.5.6" );

    # Count the bits in a chunk of memory (e.g. a select vector)
    unpack( '%32b*', $mask );

    # Determine the endianness of your system
    $is_little_endian = unpack( 'c', pack( 's', 1 ) );
    $is_big_endian = unpack( 'xc', pack( 's', 1 ) );

    # Determine the number of bits in a native integer
    $bits = unpack( '%32I!', ~0 );

    # Prepare argument for the nanosleep system call
    my $timespec = pack( 'L!L!', $secs, $nanosecs );

For a simple memory dump we unpack some bytes into just as many pairs of hex digits, and use map to handle the traditional spacing - 16 bytes to a line:

    my $i;
    print map( ++$i % 16 ? "$_ " : "$_\n",
               unpack( 'H2' x length( $mem ), $mem ) ),
          length( $mem ) % 16 ? "\n" : '';

Funnies Section

    # Pulling digits out of nowhere...
    print unpack( 'C', pack( 'x' ) ),
          unpack( '%B*', pack( 'A' ) ),
          unpack( 'H', pack( 'A' ) ),
          unpack( 'A', unpack( 'C', pack( 'A' ) ) ), "\n";

    # One for the road ;-)
    my $advice = pack( 'all u can in a van' );

Authors

Simon Cozens and Wolfgang Laun.


perltie - how to hide an object class in a simple variable

    • Tying Scalars
    • Tying Arrays
    • Tying Hashes
    • Tying FileHandles
    • UNTIE this
    • The untie Gotcha
  • SEE ALSO
  • BUGS
  • AUTHOR

NAME

perltie - how to hide an object class in a simple variable

SYNOPSIS

 tie VARIABLE, CLASSNAME, LIST
 $object = tied VARIABLE
 untie VARIABLE

DESCRIPTION

Prior to release 5.0 of Perl, a programmer could use dbmopen() to connect an on-disk database in the standard Unix dbm(3x) format magically to a %HASH in their program. However, their Perl was either built with one particular dbm library or another, but not both, and you couldn't extend this mechanism to other packages or types of variables.

Now you can.

The tie() function binds a variable to a class (package) that will provide the implementation for access methods for that variable. Once this magic has been performed, accessing a tied variable automatically triggers method calls in the proper class. The complexity of the class is hidden behind magic methods calls. The method names are in ALL CAPS, which is a convention that Perl uses to indicate that they're called implicitly rather than explicitly--just like the BEGIN() and END() functions.

In the tie() call, VARIABLE is the name of the variable to be enchanted. CLASSNAME is the name of a class implementing objects of the correct type. Any additional arguments in the LIST are passed to the appropriate constructor method for that class--meaning TIESCALAR(), TIEARRAY(), TIEHASH(), or TIEHANDLE(). (Typically these are arguments such as might be passed to the dbminit() function of C.) The object returned by the "new" method is also returned by the tie() function, which would be useful if you wanted to access other methods in CLASSNAME. (You don't actually have to return a reference to a right "type" (e.g., HASH or CLASSNAME) so long as it's a properly blessed object.) You can also retrieve a reference to the underlying object using the tied() function.

Unlike dbmopen(), the tie() function will not use or require a module for you--you need to do that explicitly yourself.

Tying Scalars

A class implementing a tied scalar should define the following methods: TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.

Let's look at each in turn, using as an example a tie class for scalars that allows the user to do something like:

    tie $his_speed, 'Nice', getppid();
    tie $my_speed,  'Nice', $$;

And now whenever either of those variables is accessed, its current system priority is retrieved and returned. If those variables are set, then the process's priority is changed!

We'll use Jarkko Hietaniemi <jhi@iki.fi>'s BSD::Resource class (not included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants from your system, as well as the getpriority() and setpriority() system calls. Here's the preamble of the class.

    package Nice;
    use Carp;
    use BSD::Resource;
    use strict;
    $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
TIESCALAR classname, LIST

This is the constructor for the class. That means it is expected to return a blessed reference to a new scalar (probably anonymous) that it's creating. For example:

    sub TIESCALAR {
        my $class = shift;
        my $pid = shift || $$; # 0 means me

        if ($pid !~ /^\d+$/) {
            carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
            return undef;
        }

        unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
            carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
            return undef;
        }

        return bless \$pid, $class;
            }

This tie class has chosen to return an error rather than raising an exception if its constructor should fail. While this is how dbmopen() works, other classes may well not wish to be so forgiving. It checks the global variable $^W to see whether to emit a bit of noise anyway.

FETCH this

This method will be triggered every time the tied variable is accessed (read). It takes no arguments beyond its self reference, which is the object representing the scalar we're dealing with. Because in this case we're using just a SCALAR ref for the tied scalar object, a simple $$self allows the method to get at the real value stored there. In our example below, that real value is the process ID to which we've tied our variable.

    sub FETCH {
        my $self = shift;
        confess "wrong type" unless ref $self;
        croak "usage error" if @_;
        my $nicety;
        local($!) = 0;
        $nicety = getpriority(PRIO_PROCESS, $$self);
        if ($!) { croak "getpriority failed: $!" }
        return $nicety;
    }

This time we've decided to blow up (raise an exception) if the renice fails--there's no place for us to return an error otherwise, and it's probably the right thing to do.

STORE this, value

This method will be triggered every time the tied variable is set (assigned). Beyond its self reference, it also expects one (and only one) argument--the new value the user is trying to assign. Don't worry about returning a value from STORE -- the semantic of assignment returning the assigned value is implemented with FETCH.

    sub STORE {
        my $self = shift;
        confess "wrong type" unless ref $self;
        my $new_nicety = shift;
        croak "usage error" if @_;

        if ($new_nicety < PRIO_MIN) {
            carp sprintf
              "WARNING: priority %d less than minimum system priority %d",
                  $new_nicety, PRIO_MIN if $^W;
            $new_nicety = PRIO_MIN;
        }

        if ($new_nicety > PRIO_MAX) {
            carp sprintf
              "WARNING: priority %d greater than maximum system priority %d",
                  $new_nicety, PRIO_MAX if $^W;
            $new_nicety = PRIO_MAX;
        }

        unless (defined setpriority(PRIO_PROCESS, $$self, $new_nicety)) {
            confess "setpriority failed: $!";
        }
            }
UNTIE this

This method will be triggered when the untie occurs. This can be useful if the class needs to know when no further calls will be made. (Except DESTROY of course.) See The untie Gotcha below for more details.

DESTROY this

This method will be triggered when the tied variable needs to be destructed. As with other object classes, such a method is seldom necessary, because Perl deallocates its moribund object's memory for you automatically--this isn't C++, you know. We'll use a DESTROY method here for debugging purposes only.

    sub DESTROY {
        my $self = shift;
        confess "wrong type" unless ref $self;
        carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
    }

That's about all there is to it. Actually, it's more than all there is to it, because we've done a few nice things here for the sake of completeness, robustness, and general aesthetics. Simpler TIESCALAR classes are certainly possible.

Tying Arrays

A class implementing a tied ordinary array should define the following methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.

FETCHSIZE and STORESIZE are used to provide $#array and equivalent scalar(@array) access.

The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are required if the perl operator with the corresponding (but lowercase) name is to operate on the tied array. The Tie::Array class can be used as a base class to implement the first five of these in terms of the basic methods above. The default implementations of DELETE and EXISTS in Tie::Array simply croak.

In addition EXTEND will be called when perl would have pre-extended allocation in a real array.

For this discussion, we'll implement an array whose elements are a fixed size at creation. If you try to create an element larger than the fixed size, you'll take an exception. For example:

    use FixedElem_Array;
    tie @array, 'FixedElem_Array', 3;
    $array[0] = 'cat';  # ok.
    $array[1] = 'dogs'; # exception, length('dogs') > 3.

The preamble code for the class is as follows:

    package FixedElem_Array;
    use Carp;
    use strict;
TIEARRAY classname, LIST

This is the constructor for the class. That means it is expected to return a blessed reference through which the new array (probably an anonymous ARRAY ref) will be accessed.

In our example, just to show you that you don't really have to return an ARRAY reference, we'll choose a HASH reference to represent our object. A HASH works out well as a generic record type: the {ELEMSIZE} field will store the maximum element size allowed, and the {ARRAY} field will hold the true ARRAY ref. If someone outside the class tries to dereference the object returned (doubtless thinking it an ARRAY ref), they'll blow up. This just goes to show you that you should respect an object's privacy.

    sub TIEARRAY {
      my $class    = shift;
      my $elemsize = shift;
      if ( @_ || $elemsize =~ /\D/ ) {
        croak "usage: tie ARRAY, '" . __PACKAGE__ . "', elem_size";
      }
      return bless {
        ELEMSIZE => $elemsize,
        ARRAY    => [],
      }, $class;
    }
FETCH this, index

This method will be triggered every time an individual element the tied array is accessed (read). It takes one argument beyond its self reference: the index whose value we're trying to fetch.

    sub FETCH {
      my $self  = shift;
      my $index = shift;
      return $self->{ARRAY}->[$index];
    }

If a negative array index is used to read from an array, the index will be translated to a positive one internally by calling FETCHSIZE before being passed to FETCH. You may disable this feature by assigning a true value to the variable $NEGATIVE_INDICES in the tied array class.

As you may have noticed, the name of the FETCH method (et al.) is the same for all accesses, even though the constructors differ in names (TIESCALAR vs TIEARRAY). While in theory you could have the same class servicing several tied types, in practice this becomes cumbersome, and it's easiest to keep them at simply one tie type per class.

STORE this, index, value

This method will be triggered every time an element in the tied array is set (written). It takes two arguments beyond its self reference: the index at which we're trying to store something and the value we're trying to put there.

In our example, undef is really $self->{ELEMSIZE} number of spaces so we have a little more work to do here:

    sub STORE {
      my $self = shift;
      my( $index, $value ) = @_;
      if ( length $value > $self->{ELEMSIZE} ) {
        croak "length of $value is greater than $self->{ELEMSIZE}";
      }
      # fill in the blanks
      $self->EXTEND( $index ) if $index > $self->FETCHSIZE();
      # right justify to keep element size for smaller elements
      $self->{ARRAY}->[$index] = sprintf "%$self->{ELEMSIZE}s", $value;
    }

Negative indexes are treated the same as with FETCH.

FETCHSIZE this

Returns the total number of items in the tied array associated with object this. (Equivalent to scalar(@array)). For example:

    sub FETCHSIZE {
      my $self = shift;
      return scalar @{$self->{ARRAY}};
    }
STORESIZE this, count

Sets the total number of items in the tied array associated with object this to be count. If this makes the array larger then class's mapping of undef should be returned for new positions. If the array becomes smaller then entries beyond count should be deleted.

In our example, 'undef' is really an element containing $self->{ELEMSIZE} number of spaces. Observe:

    sub STORESIZE {
      my $self  = shift;
      my $count = shift;
      if ( $count > $self->FETCHSIZE() ) {
        foreach ( $count - $self->FETCHSIZE() .. $count ) {
          $self->STORE( $_, '' );
        }
      } elsif ( $count < $self->FETCHSIZE() ) {
        foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) {
          $self->POP();
        }
      }
    }
EXTEND this, count

Informative call that array is likely to grow to have count entries. Can be used to optimize allocation. This method need do nothing.

In our example, we want to make sure there are no blank (undef) entries, so EXTEND will make use of STORESIZE to fill elements as needed:

    sub EXTEND {
      my $self  = shift;
      my $count = shift;
      $self->STORESIZE( $count );
    }
EXISTS this, key

Verify that the element at index key exists in the tied array this.

In our example, we will determine that if an element consists of $self->{ELEMSIZE} spaces only, it does not exist:

    sub EXISTS {
      my $self  = shift;
      my $index = shift;
      return 0 if ! defined $self->{ARRAY}->[$index] ||
                  $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
      return 1;
    }
DELETE this, key

Delete the element at index key from the tied array this.

In our example, a deleted item is $self->{ELEMSIZE} spaces:

    sub DELETE {
      my $self  = shift;
      my $index = shift;
      return $self->STORE( $index, '' );
    }
CLEAR this

Clear (remove, delete, ...) all values from the tied array associated with object this. For example:

    sub CLEAR {
      my $self = shift;
      return $self->{ARRAY} = [];
    }
PUSH this, LIST

Append elements of LIST to the array. For example:

    sub PUSH {
      my $self = shift;
      my @list = @_;
      my $last = $self->FETCHSIZE();
      $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
      return $self->FETCHSIZE();
    }
POP this

Remove last element of the array and return it. For example:

    sub POP {
      my $self = shift;
      return pop @{$self->{ARRAY}};
    }
SHIFT this

Remove the first element of the array (shifting other elements down) and return it. For example:

    sub SHIFT {
      my $self = shift;
      return shift @{$self->{ARRAY}};
    }
UNSHIFT this, LIST

Insert LIST elements at the beginning of the array, moving existing elements up to make room. For example:

    sub UNSHIFT {
      my $self = shift;
      my @list = @_;
      my $size = scalar( @list );
      # make room for our list
      @{$self->{ARRAY}}[ $size .. $#{$self->{ARRAY}} + $size ]
       = @{$self->{ARRAY}};
      $self->STORE( $_, $list[$_] ) foreach 0 .. $#list;
    }
SPLICE this, offset, length, LIST

Perform the equivalent of splice on the array.

offset is optional and defaults to zero, negative values count back from the end of the array.

length is optional and defaults to rest of the array.

LIST may be empty.

Returns a list of the original length elements at offset.

In our example, we'll use a little shortcut if there is a LIST:

    sub SPLICE {
      my $self   = shift;
      my $offset = shift || 0;
      my $length = shift || $self->FETCHSIZE() - $offset;
      my @list   = ();
      if ( @_ ) {
        tie @list, __PACKAGE__, $self->{ELEMSIZE};
        @list   = @_;
      }
      return splice @{$self->{ARRAY}}, $offset, $length, @list;
    }
UNTIE this

Will be called when untie happens. (See The untie Gotcha below.)

DESTROY this

This method will be triggered when the tied variable needs to be destructed. As with the scalar tie class, this is almost never needed in a language that does its own garbage collection, so this time we'll just leave it out.

Tying Hashes

Hashes were the first Perl data type to be tied (see dbmopen()). A class implementing a tied hash should define the following methods: TIEHASH is the constructor. FETCH and STORE access the key and value pairs. EXISTS reports whether a key is present in the hash, and DELETE deletes one. CLEAR empties the hash by deleting all the key and value pairs. FIRSTKEY and NEXTKEY implement the keys() and each() functions to iterate over all the keys. SCALAR is triggered when the tied hash is evaluated in scalar context. UNTIE is called when untie happens, and DESTROY is called when the tied variable is garbage collected.

If this seems like a lot, then feel free to inherit from merely the standard Tie::StdHash module for most of your methods, redefining only the interesting ones. See the Tie::Hash manpage for details.

Remember that Perl distinguishes between a key not existing in the hash, and the key existing in the hash but having a corresponding value of undef. The two possibilities can be tested with the exists() and defined() functions.

Here's an example of a somewhat interesting tied hash class: it gives you a hash representing a particular user's dot files. You index into the hash with the name of the file (minus the dot) and you get back that dot file's contents. For example:

    use DotFiles;
    tie %dot, 'DotFiles';
    if ( $dot{profile} =~ /MANPATH/ ||
         $dot{login}   =~ /MANPATH/ ||
         $dot{cshrc}   =~ /MANPATH/    )
    {
        print "you seem to set your MANPATH\n";
    }

Or here's another sample of using our tied class:

    tie %him, 'DotFiles', 'daemon';
    foreach $f ( keys %him ) {
        printf "daemon dot file %s is size %d\n",
            $f, length $him{$f};
    }

In our tied hash DotFiles example, we use a regular hash for the object containing several important fields, of which only the {LIST} field will be what the user thinks of as the real hash.

USER

whose dot files this object represents

HOME

where those dot files live

CLOBBER

whether we should try to change or remove those dot files

LIST

the hash of dot file names and content mappings

Here's the start of Dotfiles.pm:

    package DotFiles;
    use Carp;
    sub whowasi { (caller(1))[3] . '()' }
    my $DEBUG = 0;
    sub debug { $DEBUG = @_ ? shift : 1 }

For our example, we want to be able to emit debugging info to help in tracing during development. We keep also one convenience function around internally to help print out warnings; whowasi() returns the function name that calls it.

Here are the methods for the DotFiles tied hash.

TIEHASH classname, LIST

This is the constructor for the class. That means it is expected to return a blessed reference through which the new object (probably but not necessarily an anonymous hash) will be accessed.

Here's the constructor:

    sub TIEHASH {
        my $self = shift;
        my $user = shift || $>;
        my $dotdir = shift || '';
        croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
        $user = getpwuid($user) if $user =~ /^\d+$/;
        my $dir = (getpwnam($user))[7]
                || croak "@{[&whowasi]}: no user $user";
        $dir .= "/$dotdir" if $dotdir;

        my $node = {
            USER    => $user,
            HOME    => $dir,
            LIST    => {},
            CLOBBER => 0,
        };

        opendir(DIR, $dir)
                || croak "@{[&whowasi]}: can't opendir $dir: $!";
        foreach $dot ( grep /^\./ && -f "$dir/$_", readdir(DIR)) {
            $dot =~ s/^\.//;
            $node->{LIST}{$dot} = undef;
        }
        closedir DIR;
        return bless $node, $self;
            }

It's probably worth mentioning that if you're going to filetest the return values out of a readdir, you'd better prepend the directory in question. Otherwise, because we didn't chdir() there, it would have been testing the wrong file.

FETCH this, key

This method will be triggered every time an element in the tied hash is accessed (read). It takes one argument beyond its self reference: the key whose value we're trying to fetch.

Here's the fetch for our DotFiles example.

    sub FETCH {
        carp &whowasi if $DEBUG;
        my $self = shift;
        my $dot = shift;
        my $dir = $self->{HOME};
        my $file = "$dir/.$dot";

        unless (exists $self->{LIST}->{$dot} || -f $file) {
            carp "@{[&whowasi]}: no $dot file" if $DEBUG;
            return undef;
        }

        if (defined $self->{LIST}->{$dot}) {
            return $self->{LIST}->{$dot};
        } else {
            return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
        }
            }

It was easy to write by having it call the Unix cat(1) command, but it would probably be more portable to open the file manually (and somewhat more efficient). Of course, because dot files are a Unixy concept, we're not that concerned.

STORE this, key, value

This method will be triggered every time an element in the tied hash is set (written). It takes two arguments beyond its self reference: the index at which we're trying to store something, and the value we're trying to put there.

Here in our DotFiles example, we'll be careful not to let them try to overwrite the file unless they've called the clobber() method on the original object reference returned by tie().

    sub STORE {
        carp &whowasi if $DEBUG;
        my $self = shift;
        my $dot = shift;
        my $value = shift;
        my $file = $self->{HOME} . "/.$dot";
        my $user = $self->{USER};

        croak "@{[&whowasi]}: $file not clobberable"
            unless $self->{CLOBBER};

        open(F, "> $file") || croak "can't open $file: $!";
        print F $value;
        close(F);
            }

If they wanted to clobber something, they might say:

    $ob = tie %daemon_dots, 'daemon';
    $ob->clobber(1);
    $daemon_dots{signature} = "A true daemon\n";

Another way to lay hands on a reference to the underlying object is to use the tied() function, so they might alternately have set clobber using:

    tie %daemon_dots, 'daemon';
    tied(%daemon_dots)->clobber(1);

The clobber method is simply:

    sub clobber {
        my $self = shift;
        $self->{CLOBBER} = @_ ? shift : 1;
    }
DELETE this, key

This method is triggered when we remove an element from the hash, typically by using the delete() function. Again, we'll be careful to check whether they really want to clobber files.

    sub DELETE   {
        carp &whowasi if $DEBUG;

        my $self = shift;
        my $dot = shift;
        my $file = $self->{HOME} . "/.$dot";
        croak "@{[&whowasi]}: won't remove file $file"
            unless $self->{CLOBBER};
        delete $self->{LIST}->{$dot};
        my $success = unlink($file);
        carp "@{[&whowasi]}: can't unlink $file: $!" unless $success;
        $success;
            }

The value returned by DELETE becomes the return value of the call to delete(). If you want to emulate the normal behavior of delete(), you should return whatever FETCH would have returned for this key. In this example, we have chosen instead to return a value which tells the caller whether the file was successfully deleted.

CLEAR this

This method is triggered when the whole hash is to be cleared, usually by assigning the empty list to it.

In our example, that would remove all the user's dot files! It's such a dangerous thing that they'll have to set CLOBBER to something higher than 1 to make it happen.

    sub CLEAR    {
        carp &whowasi if $DEBUG;
        my $self = shift;
        croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
            unless $self->{CLOBBER} > 1;
        my $dot;
        foreach $dot ( keys %{$self->{LIST}}) {
            $self->DELETE($dot);
        }
    }
EXISTS this, key

This method is triggered when the user uses the exists() function on a particular hash. In our example, we'll look at the {LIST} hash element for this:

    sub EXISTS   {
        carp &whowasi if $DEBUG;
        my $self = shift;
        my $dot = shift;
        return exists $self->{LIST}->{$dot};
    }
FIRSTKEY this

This method will be triggered when the user is going to iterate through the hash, such as via a keys() or each() call.

    sub FIRSTKEY {
        carp &whowasi if $DEBUG;
        my $self = shift;
        my $a = keys %{$self->{LIST}};          # reset each() iterator
        each %{$self->{LIST}}
    }
NEXTKEY this, lastkey

This method gets triggered during a keys() or each() iteration. It has a second argument which is the last key that had been accessed. This is useful if you're carrying about ordering or calling the iterator from more than one sequence, or not really storing things in a hash anywhere.

For our example, we're using a real hash so we'll do just the simple thing, but we'll have to go through the LIST field indirectly.

    sub NEXTKEY  {
        carp &whowasi if $DEBUG;
        my $self = shift;
        return each %{ $self->{LIST} }
    }
SCALAR this

This is called when the hash is evaluated in scalar context. In order to mimic the behaviour of untied hashes, this method should return a false value when the tied hash is considered empty. If this method does not exist, perl will make some educated guesses and return true when the hash is inside an iteration. If this isn't the case, FIRSTKEY is called, and the result will be a false value if FIRSTKEY returns the empty list, true otherwise.

However, you should not blindly rely on perl always doing the right thing. Particularly, perl will mistakenly return true when you clear the hash by repeatedly calling DELETE until it is empty. You are therefore advised to supply your own SCALAR method when you want to be absolutely sure that your hash behaves nicely in scalar context.

In our example we can just call scalar on the underlying hash referenced by $self->{LIST}:

    sub SCALAR {
        carp &whowasi if $DEBUG;
        my $self = shift;
        return scalar %{ $self->{LIST} }
    }
UNTIE this

This is called when untie occurs. See The untie Gotcha below.

DESTROY this

This method is triggered when a tied hash is about to go out of scope. You don't really need it unless you're trying to add debugging or have auxiliary state to clean up. Here's a very simple function:

    sub DESTROY  {
        carp &whowasi if $DEBUG;
    }

Note that functions such as keys() and values() may return huge lists when used on large objects, like DBM files. You may prefer to use the each() function to iterate over such. Example:

    # print out history file offsets
    use NDBM_File;
    tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
    while (($key,$val) = each %HIST) {
        print $key, ' = ', unpack('L',$val), "\n";
    }
    untie(%HIST);

Tying FileHandles

This is partially implemented now.

A class implementing a tied filehandle should define the following methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC, READ, and possibly CLOSE, UNTIE and DESTROY. The class can also provide: BINMODE, OPEN, EOF, FILENO, SEEK, TELL - if the corresponding perl operators are used on the handle.

When STDERR is tied, its PRINT method will be called to issue warnings and error messages. This feature is temporarily disabled during the call, which means you can use warn() inside PRINT without starting a recursive loop. And just like __WARN__ and __DIE__ handlers, STDERR's PRINT method may be called to report parser errors, so the caveats mentioned under %SIG in the perlvar manpage apply.

All of this is especially useful when perl is embedded in some other program, where output to STDOUT and STDERR may have to be redirected in some special way. See nvi and the Apache module for examples.

In our example we're going to create a shouting handle.

    package Shout;
TIEHANDLE classname, LIST

This is the constructor for the class. That means it is expected to return a blessed reference of some sort. The reference can be used to hold some internal information.

    sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
WRITE this, LIST

This method will be called when the handle is written to via the syswrite function.

    sub WRITE {
        $r = shift;
        my($buf,$len,$offset) = @_;
        print "WRITE called, \$buf=$buf, \$len=$len, \$offset=$offset";
    }
PRINT this, LIST

This method will be triggered every time the tied handle is printed to with the print() function. Beyond its self reference it also expects the list that was passed to the print function.

    sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
PRINTF this, LIST

This method will be triggered every time the tied handle is printed to with the printf() function. Beyond its self reference it also expects the format and list that was passed to the printf function.

    sub PRINTF {
        shift;
        my $fmt = shift;
        print sprintf($fmt, @_);
    }
READ this, LIST

This method will be called when the handle is read from via the read or sysread functions.

    sub READ {
        my $self = shift;
        my $bufref = \$_[0];
        my(undef,$len,$offset) = @_;
        print "READ called, \$buf=$bufref, \$len=$len, \$offset=$offset";
        # add to $$bufref, set $len to number of characters read
        $len;
    }
READLINE this

This method will be called when the handle is read from via <HANDLE>. The method should return undef when there is no more data.

    sub READLINE { $r = shift; "READLINE called $$r times\n"; }
GETC this

This method will be called when the getc function is called.

    sub GETC { print "Don't GETC, Get Perl"; return "a"; }
CLOSE this

This method will be called when the handle is closed via the close function.

    sub CLOSE { print "CLOSE called.\n" }
UNTIE this

As with the other types of ties, this method will be called when untie happens. It may be appropriate to "auto CLOSE" when this occurs. See The untie Gotcha below.

DESTROY this

As with the other types of ties, this method will be called when the tied handle is about to be destroyed. This is useful for debugging and possibly cleaning up.

    sub DESTROY { print "</shout>\n" }

Here's how to use our little example:

    tie(*FOO,'Shout');
    print FOO "hello\n";
    $a = 4; $b = 6;
    print FOO $a, " plus ", $b, " equals ", $a + $b, "\n";
    print <FOO>;

UNTIE this

You can define for all tie types an UNTIE method that will be called at untie(). See The untie Gotcha below.

The untie Gotcha

If you intend making use of the object returned from either tie() or tied(), and if the tie's target class defines a destructor, there is a subtle gotcha you must guard against.

As setup, consider this (admittedly rather contrived) example of a tie; all it does is use a file to keep a log of the values assigned to a scalar.

    package Remember;

    use strict;
    use warnings;
    use IO::File;

    sub TIESCALAR {
        my $class = shift;
        my $filename = shift;
        my $handle = new IO::File "> $filename"
                         or die "Cannot open $filename: $!\n";

        print $handle "The Start\n";
        bless {FH => $handle, Value => 0}, $class;
            }

    sub FETCH {
        my $self = shift;
        return $self->{Value};
    }

    sub STORE {
        my $self = shift;
        my $value = shift;
        my $handle = $self->{FH};
        print $handle "$value\n";
        $self->{Value} = $value;
    }

    sub DESTROY {
        my $self = shift;
        my $handle = $self->{FH};
        print $handle "The End\n";
        close $handle;
    }

    1;

Here is an example that makes use of this tie:

    use strict;
    use Remember;

    my $fred;
    tie $fred, 'Remember', 'myfile.txt';
    $fred = 1;
    $fred = 4;
    $fred = 5;
    untie $fred;
    system "cat myfile.txt";

This is the output when it is executed:

    The Start
    1
    4
    5
    The End

So far so good. Those of you who have been paying attention will have spotted that the tied object hasn't been used so far. So lets add an extra method to the Remember class to allow comments to be included in the file -- say, something like this:

    sub comment {
        my $self = shift;
        my $text = shift;
        my $handle = $self->{FH};
        print $handle $text, "\n";
    }

And here is the previous example modified to use the comment method (which requires the tied object):

    use strict;
    use Remember;

    my ($fred, $x);
    $x = tie $fred, 'Remember', 'myfile.txt';
    $fred = 1;
    $fred = 4;
    comment $x "changing...";
    $fred = 5;
    untie $fred;
    system "cat myfile.txt";

When this code is executed there is no output. Here's why:

When a variable is tied, it is associated with the object which is the return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This object normally has only one reference, namely, the implicit reference from the tied variable. When untie() is called, that reference is destroyed. Then, as in the first example above, the object's destructor (DESTROY) is called, which is normal for objects that have no more valid references; and thus the file is closed.

In the second example, however, we have stored another reference to the tied object in $x. That means that when untie() gets called there will still be a valid reference to the object in existence, so the destructor is not called at that time, and thus the file is not closed. The reason there is no output is because the file buffers have not been flushed to disk.

Now that you know what the problem is, what can you do to avoid it? Prior to the introduction of the optional UNTIE method the only way was the good old -w flag. Which will spot any instances where you call untie() and there are still valid references to the tied object. If the second script above this near the top use warnings 'untie' or was run with the -w flag, Perl prints this warning message:

    untie attempted while 1 inner references still exist

To get the script to work properly and silence the warning make sure there are no valid references to the tied object before untie() is called:

    undef $x;
    untie $fred;

Now that UNTIE exists the class designer can decide which parts of the class functionality are really associated with untie and which with the object being destroyed. What makes sense for a given class depends on whether the inner references are being kept so that non-tie-related methods can be called on the object. But in most cases it probably makes sense to move the functionality that would have been in DESTROY to the UNTIE method.

If the UNTIE method exists then the warning above does not occur. Instead the UNTIE method is passed the count of "extra" references and can issue its own warning if appropriate. e.g. to replicate the no UNTIE case this method can be used:

    sub UNTIE
    {
     my ($obj,$count) = @_;
     carp "untie attempted while $count inner references still exist" if $count;
    }

SEE ALSO

See DB_File or the Config manpage for some interesting tie() implementations. A good starting point for many tie() implementations is with one of the modules the Tie::Scalar manpage, the Tie::Array manpage, the Tie::Hash manpage, or the Tie::Handle manpage.

BUGS

The bucket usage information provided by scalar(%hash) is not available. What this means is that using %tied_hash in boolean context doesn't work right (currently this always tests false, regardless of whether the hash is empty or hash elements).

Localizing tied arrays or hashes does not work. After exiting the scope the arrays or the hashes are not restored.

Counting the number of entries in a hash via scalar(keys(%hash)) or scalar(values(%hash)) is inefficient since it needs to iterate through all the entries with FIRSTKEY/NEXTKEY.

Tied hash/array slices cause multiple FETCH/STORE pairs, there are no tie methods for slice operations.

You cannot easily tie a multilevel data structure (such as a hash of hashes) to a dbm file. The first problem is that all but GDBM and Berkeley DB have size limitations, but beyond that, you also have problems with how references are to be represented on disk. One experimental module that does attempt to address this need is DBM::Deep. Check your nearest CPAN site as described in the perlmodlib manpage for source code. Note that despite its name, DBM::Deep does not use dbm. Another earlier attempt at solving the problem is MLDBM, which is also available on the CPAN, but which has some fairly serious limitations.

Tied filehandles are still incomplete. sysopen(), truncate(), flock(), fcntl(), stat() and -X can't currently be trapped.

AUTHOR

Tom Christiansen

TIEHANDLE by Sven Verdoolaege <skimo@dns.ufsia.ac.be> and Doug MacEachern <dougm@osf.org>

UNTIE by Nick Ing-Simmons <nick@ing-simmons.net>

SCALAR by Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>

Tying Arrays by Casey West <casey@geeknest.com>


perldata - Perl data types

    • Variable names
    • Context
    • Scalar values
    • Scalar value constructors
      • Version Strings
      • Special Literals
      • Barewords
      • Array Joining Delimiter
    • List value constructors
    • Subscripts
    • Slices
    • Typeglobs and Filehandles
  • SEE ALSO

NAME

perldata - Perl data types

DESCRIPTION

Variable names

Perl has three built-in data types: scalars, arrays of scalars, and associative arrays of scalars, known as "hashes". A scalar is a single string (of any size, limited only by the available memory), number, or a reference to something (which will be discussed in the perlref manpage). Normal arrays are ordered lists of scalars indexed by number, starting with 0. Hashes are unordered collections of scalar values indexed by their associated string key.

Values are usually referred to by name, or through a named reference. The first character of the name tells you to what sort of data structure it refers. The rest of the name tells you the particular value to which it refers. Usually this name is a single identifier, that is, a string beginning with a letter or underscore, and containing letters, underscores, and digits. In some cases, it may be a chain of identifiers, separated by :: (or by the slightly archaic '); all but the last are interpreted as names of packages, to locate the namespace in which to look up the final identifier (see Packages in the perlmod manpage for details). It's possible to substitute for a simple identifier, an expression that produces a reference to the value at runtime. This is described in more detail below and in the perlref manpage.

Perl also has its own built-in variables whose names don't follow these rules. They have strange names so they don't accidentally collide with one of your normal variables. Strings that match parenthesized parts of a regular expression are saved under names containing only digits after the $ (see the perlop manpage and the perlre manpage). In addition, several special variables that provide windows into the inner working of Perl have names containing punctuation characters and control characters. These are documented in the perlvar manpage.

Scalar values are always named with '$', even when referring to a scalar that is part of an array or a hash. The '$' symbol works semantically like the English word "the" in that it indicates a single value is expected.

    $days               # the simple scalar value "days"
    $days[28]           # the 29th element of array @days
    $days{'Feb'}        # the 'Feb' value from hash %days
    $#days              # the last index of array @days

Entire arrays (and slices of arrays and hashes) are denoted by '@', which works much like the word "these" or "those" does in English, in that it indicates multiple values are expected.

    @days               # ($days[0], $days[1],... $days[n])
    @days[3,4,5]        # same as ($days[3],$days[4],$days[5])
    @days{'a','c'}      # same as ($days{'a'},$days{'c'})

Entire hashes are denoted by '%':

    %days               # (key1, val1, key2, val2 ...)

In addition, subroutines are named with an initial '&', though this is optional when unambiguous, just as the word "do" is often redundant in English. Symbol table entries can be named with an initial '*', but you don't really care about that yet (if ever :-).

Every variable type has its own namespace, as do several non-variable identifiers. This means that you can, without fear of conflict, use the same name for a scalar variable, an array, or a hash--or, for that matter, for a filehandle, a directory handle, a subroutine name, a format name, or a label. This means that $foo and @foo are two different variables. It also means that $foo[1] is a part of @foo, not a part of $foo. This may seem a bit weird, but that's okay, because it is weird.

Because variable references always start with '$', '@', or '%', the "reserved" words aren't in fact reserved with respect to variable names. They are reserved with respect to labels and filehandles, however, which don't have an initial special character. You can't have a filehandle named "log", for instance. Hint: you could say open(LOG,'logfile') rather than open(log,'logfile'). Using uppercase filehandles also improves readability and protects you from conflict with future reserved words. Case is significant--"FOO", "Foo", and "foo" are all different names. Names that start with a letter or underscore may also contain digits and underscores.

It is possible to replace such an alphanumeric name with an expression that returns a reference to the appropriate type. For a description of this, see the perlref manpage.

Names that start with a digit may contain only more digits. Names that do not start with a letter, underscore, digit or a caret (i.e. a control character) are limited to one character, e.g., $% or $$. (Most of these one character names have a predefined significance to Perl. For instance, $$ is the current process id.)

Context

The interpretation of operations and values in Perl sometimes depends on the requirements of the context around the operation or value. There are two major contexts: list and scalar. Certain operations return list values in contexts wanting a list, and scalar values otherwise. If this is true of an operation it will be mentioned in the documentation for that operation. In other words, Perl overloads certain operations based on whether the expected return value is singular or plural. Some words in English work this way, like "fish" and "sheep".

In a reciprocal fashion, an operation provides either a scalar or a list context to each of its arguments. For example, if you say

    int( <STDIN> )

the integer operation provides scalar context for the <> operator, which responds by reading one line from STDIN and passing it back to the integer operation, which will then find the integer value of that line and return that. If, on the other hand, you say

    sort( <STDIN> )

then the sort operation provides list context for <>, which will proceed to read every line available up to the end of file, and pass that list of lines back to the sort routine, which will then sort those lines and return them as a list to whatever the context of the sort was.

Assignment is a little bit special in that it uses its left argument to determine the context for the right argument. Assignment to a scalar evaluates the right-hand side in scalar context, while assignment to an array or hash evaluates the righthand side in list context. Assignment to a list (or slice, which is just a list anyway) also evaluates the righthand side in list context.

When you use the use warnings pragma or Perl's -w command-line option, you may see warnings about useless uses of constants or functions in "void context". Void context just means the value has been discarded, such as a statement containing only "fred"; or getpwuid(0);. It still counts as scalar context for functions that care whether or not they're being called in list context.

User-defined subroutines may choose to care whether they are being called in a void, scalar, or list context. Most subroutines do not need to bother, though. That's because both scalars and lists are automatically interpolated into lists. See wantarray in the perlfunc manpage for how you would dynamically discern your function's calling context.

Scalar values

All data in Perl is a scalar, an array of scalars, or a hash of scalars. A scalar may contain one single value in any of three different flavors: a number, a string, or a reference. In general, conversion from one form to another is transparent. Although a scalar may not directly hold multiple values, it may contain a reference to an array or hash which in turn contains multiple values.

Scalars aren't necessarily one thing or another. There's no place to declare a scalar variable to be of type "string", type "number", type "reference", or anything else. Because of the automatic conversion of scalars, operations that return scalars don't need to care (and in fact, cannot care) whether their caller is looking for a string, a number, or a reference. Perl is a contextually polymorphic language whose scalars can be strings, numbers, or references (which includes objects). Although strings and numbers are considered pretty much the same thing for nearly all purposes, references are strongly-typed, uncastable pointers with builtin reference-counting and destructor invocation.

A scalar value is interpreted as TRUE in the Boolean sense if it is not the null string or the number 0 (or its string equivalent, "0"). The Boolean context is just a special kind of scalar context where no conversion to a string or a number is ever performed.

There are actually two varieties of null strings (sometimes referred to as "empty" strings), a defined one and an undefined one. The defined version is just a string of length zero, such as "". The undefined version is the value that indicates that there is no real value for something, such as when there was an error, or at end of file, or when you refer to an uninitialized variable or element of an array or hash. Although in early versions of Perl, an undefined scalar could become defined when first used in a place expecting a defined value, this no longer happens except for rare cases of autovivification as explained in the perlref manpage. You can use the defined() operator to determine whether a scalar value is defined (this has no meaning on arrays or hashes), and the undef() operator to produce an undefined value.

To find out whether a given string is a valid non-zero number, it's sometimes enough to test it against both numeric 0 and also lexical "0" (although this will cause noises if warnings are on). That's because strings that aren't numbers count as 0, just as they do in awk:

    if ($str == 0 && $str ne "0")  {
        warn "That doesn't look like a number";
    }

That method may be best because otherwise you won't treat IEEE notations like NaN or Infinity properly. At other times, you might prefer to determine whether string data can be used numerically by calling the POSIX::strtod() function or by inspecting your string with a regular expression (as documented in the perlre manpage).

    warn "has nondigits"        if     /\D/;
    warn "not a natural number" unless /^\d+$/;             # rejects -3
    warn "not an integer"       unless /^-?\d+$/;           # rejects +3
    warn "not an integer"       unless /^[+-]?\d+$/;
    warn "not a decimal number" unless /^-?\d+\.?\d*$/;     # rejects .2
    warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
    warn "not a C float"
        unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;

The length of an array is a scalar value. You may find the length of array @days by evaluating $#days, as in csh. However, this isn't the length of the array; it's the subscript of the last element, which is a different value since there is ordinarily a 0th element. Assigning to $#days actually changes the length of the array. Shortening an array this way destroys intervening values. Lengthening an array that was previously shortened does not recover values that were in those elements. (It used to do so in Perl 4, but we had to break this to make sure destructors were called when expected.)

You can also gain some minuscule measure of efficiency by pre-extending an array that is going to get big. You can also extend an array by assigning to an element that is off the end of the array. You can truncate an array down to nothing by assigning the null list () to it. The following are equivalent:

    @whatever = ();
    $#whatever = -1;

If you evaluate an array in scalar context, it returns the length of the array. (Note that this is not true of lists, which return the last value, like the C comma operator, nor of built-in functions, which return whatever they feel like returning.) The following is always true:

    scalar(@whatever) == $#whatever - $[ + 1;

Version 5 of Perl changed the semantics of $[: files that don't set the value of $[ no longer need to worry about whether another file changed its value. (In other words, use of $[ is deprecated.) So in general you can assume that

    scalar(@whatever) == $#whatever + 1;

Some programmers choose to use an explicit conversion so as to leave nothing to doubt:

    $element_count = scalar(@whatever);

If you evaluate a hash in scalar context, it returns false if the hash is empty. If there are any key/value pairs, it returns true; more precisely, the value returned is a string consisting of the number of used buckets and the number of allocated buckets, separated by a slash. This is pretty much useful only to find out whether Perl's internal hashing algorithm is performing poorly on your data set. For example, you stick 10,000 things in a hash, but evaluating %HASH in scalar context reveals "1/16", which means only one out of sixteen buckets has been touched, and presumably contains all 10,000 of your items. This isn't supposed to happen.

You can preallocate space for a hash by assigning to the keys() function. This rounds up the allocated buckets to the next power of two:

    keys(%users) = 1000;                # allocate 1024 buckets

Scalar value constructors

Numeric literals are specified in any of the following floating point or integer formats:

    12345
    12345.67
    .23E-10             # a very small number
    3.14_15_92          # a very important number
    4_294_967_296       # underscore for legibility
    0xff                # hex
    0xdead_beef         # more hex
    0377                # octal (only numbers, begins with 0)
    0b011011            # binary

You are allowed to use underscores (underbars) in numeric literals between digits for legibility. You could, for example, group binary digits by threes (as for a Unix-style mode argument such as 0b110_100_100) or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.

String literals are usually delimited by either single or double quotes. They work much like quotes in the standard Unix shells: double-quoted string literals are subject to backslash and variable substitution; single-quoted strings are not (except for \' and \\). The usual C-style backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic forms. See Quote and Quote-like Operators in the perlop manpage for a list.

Hexadecimal, octal, or binary, representations in string literals (e.g. '0xff') are not automatically converted to their integer representation. The hex() and oct() functions make these conversions for you. See hex in the perlfunc manpage and oct in the perlfunc manpage for more details.

You can also embed newlines directly in your strings, i.e., they can end on a different line than they begin. This is nice, but if you forget your trailing quote, the error will not be reported until Perl finds another line containing the quote character, which may be much further on in the script. Variable substitution inside strings is limited to scalar variables, arrays, and array or hash slices. (In other words, names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The price is $100."

    $Price = '$100';    # not interpolated
    print "The price is $Price.\n";     # interpolated

There is no double interpolation in Perl, so the $100 is left as is.

As in some shells, you can enclose the variable name in braces to disambiguate it from following alphanumerics (and underscores). You must also do this when interpolating a variable into a string to separate the variable name from a following double-colon or an apostrophe, since these would be otherwise treated as a package separator:

    $who = "Larry";
    print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
    print "We use ${who}speak when ${who}'s here.\n";

Without the braces, Perl would have looked for a $whospeak, a $who::0, and a $who's variable. The last two would be the $0 and the $s variables in the (presumably) non-existent package who.

In fact, an identifier within such curlies is forced to be a string, as is any simple identifier within a hash subscript. Neither need quoting. Our earlier example, $days{'Feb'} can be written as $days{Feb} and the quotes will be assumed automatically. But anything more complicated in the subscript will be interpreted as an expression. This means for example that $version{2.0}++ is equivalent to $version{2}++, not to $version{'2.0'}++.

Version Strings

Note: Version Strings (v-strings) have been deprecated. They will not be available after Perl 5.8. The marginal benefits of v-strings were greatly outweighed by the potential for Surprise and Confusion.

A literal of the form v1.20.300.4000 is parsed as a string composed of characters with the specified ordinals. This form, known as v-strings, provides an alternative, more readable way to construct strings, rather than use the somewhat less readable interpolation form "\x{1}\x{14}\x{12c}\x{fa0}". This is useful for representing Unicode strings, and for comparing version "numbers" using the string comparison operators, cmp, gt, lt etc. If there are two or more dots in the literal, the leading v may be omitted.

    print v9786;              # prints UTF-8 encoded SMILEY, "\x{263a}"
    print v102.111.111;       # prints "foo"
    print 102.111.111;        # same

Such literals are accepted by both require and use for doing a version check. The $^V special variable also contains the running Perl interpreter's version in this form. See $^V in the perlvar manpage. Note that using the v-strings for IPv4 addresses is not portable unless you also use the inet_aton()/inet_ntoa() routines of the Socket package.

Note that since Perl 5.8.1 the single-number v-strings (like v65) are not v-strings before the => operator (which is usually used to separate a hash key from a hash value), instead they are interpreted as literal strings ('v65'). They were v-strings from Perl 5.6.0 to Perl 5.8.0, but that caused more confusion and breakage than good. Multi-number v-strings like v65.66 and 65.66.67 continue to be v-strings always.

Special Literals

The special literals __FILE__, __LINE__, and __PACKAGE__ represent the current filename, line number, and package name at that point in your program. They may be used only as separate tokens; they will not be interpolated into strings. If there is no current package (due to an empty package; directive), __PACKAGE__ is the undefined value.

The two control characters ^D and ^Z, and the tokens __END__ and __DATA__ may be used to indicate the logical end of the script before the actual end of file. Any following text is ignored.

Text after __DATA__ but may be read via the filehandle PACKNAME::DATA, where PACKNAME is the package that was current when the __DATA__ token was encountered. The filehandle is left open pointing to the contents after __DATA__. It is the program's responsibility to close DATA when it is done reading from it. For compatibility with older scripts written before __DATA__ was introduced, __END__ behaves like __DATA__ in the toplevel script (but not in files loaded with require or do) and leaves the remaining contents of the file accessible via main::DATA.

See the SelfLoader manpage for more description of __DATA__, and an example of its use. Note that you cannot read from the DATA filehandle in a BEGIN block: the BEGIN block is executed as soon as it is seen (during compilation), at which point the corresponding __DATA__ (or __END__) token has not yet been seen.

Barewords

A word that has no other interpretation in the grammar will be treated as if it were a quoted string. These are known as "barewords". As with filehandles and labels, a bareword that consists entirely of lowercase letters risks conflict with future reserved words, and if you use the use warnings pragma or the -w switch, Perl will warn you about any such words. Some people may wish to outlaw barewords entirely. If you say

    use strict 'subs';

then any bareword that would NOT be interpreted as a subroutine call produces a compile-time error instead. The restriction lasts to the end of the enclosing block. An inner block may countermand this by saying no strict 'subs'.

Array Joining Delimiter

Arrays and slices are interpolated into double-quoted strings by joining the elements with the delimiter specified in the $" variable ($LIST_SEPARATOR if "use English;" is specified), space by default. The following are equivalent:

    $temp = join($", @ARGV);
    system "echo $temp";

    system "echo @ARGV";

Within search patterns (which also undergo double-quotish substitution) there is an unfortunate ambiguity: Is /$foo[bar]/ to be interpreted as /${foo}[bar]/ (where [bar] is a character class for the regular expression) or as /${foo[bar]}/ (where [bar] is the subscript to array @foo)? If @foo doesn't otherwise exist, then it's obviously a character class. If @foo exists, Perl takes a good guess about [bar], and is almost always right. If it does guess wrong, or if you're just plain paranoid, you can force the correct interpretation with curly braces as above.

If you're looking for the information on how to use here-documents, which used to be here, that's been moved to Quote and Quote-like Operators in the perlop manpage.

List value constructors

List values are denoted by separating individual values by commas (and enclosing the list in parentheses where precedence requires it):

    (LIST)

In a context not requiring a list value, the value of what appears to be a list literal is simply the value of the final element, as with the C comma operator. For example,

    @foo = ('cc', '-E', $bar);

assigns the entire list value to array @foo, but

    $foo = ('cc', '-E', $bar);

assigns the value of variable $bar to the scalar variable $foo. Note that the value of an actual array in scalar context is the length of the array; the following assigns the value 3 to $foo:

    @foo = ('cc', '-E', $bar);
    $foo = @foo;                # $foo gets 3

You may have an optional comma before the closing parenthesis of a list literal, so that you can say:

    @foo = (
        1,
        2,
        3,
    );

To use a here-document to assign an array, one line per element, you might use an approach like this:

    @sauces = <<End_Lines =~ m/(\S.*\S)/g;
        normal tomato
        spicy tomato
        green chile
        pesto
        white wine
    End_Lines

LISTs do automatic interpolation of sublists. That is, when a LIST is evaluated, each element of the list is evaluated in list context, and the resulting list value is interpolated into LIST just as if each individual element were a member of LIST. Thus arrays and hashes lose their identity in a LIST--the list

    (@foo,@bar,&SomeSub,%glarch)

contains all the elements of @foo followed by all the elements of @bar, followed by all the elements returned by the subroutine named SomeSub called in list context, followed by the key/value pairs of %glarch. To make a list reference that does NOT interpolate, see the perlref manpage.

The null list is represented by (). Interpolating it in a list has no effect. Thus ((),(),()) is equivalent to (). Similarly, interpolating an array with no elements is the same as if no array had been interpolated at that point.

This interpolation combines with the facts that the opening and closing parentheses are optional (except when necessary for precedence) and lists may end with an optional comma to mean that multiple commas within lists are legal syntax. The list 1,,3 is a concatenation of two lists, 1, and 3, the first of which ends with that optional comma. 1,,3 is (1,),(3) is 1,3 (And similarly for 1,,,3 is (1,),(,),3 is 1,3 and so on.) Not that we'd advise you to use this obfuscation.

A list value may also be subscripted like a normal array. You must put the list in parentheses to avoid ambiguity. For example:

    # Stat returns list value.
    $time = (stat($file))[8];

    # SYNTAX ERROR HERE.
    $time = stat($file)[8];  # OOPS, FORGOT PARENTHESES

    # Find a hex digit.
    $hexdigit = ('a','b','c','d','e','f')[$digit-10];

    # A "reverse comma operator".
    return (pop(@foo),pop(@foo))[0];

Lists may be assigned to only when each element of the list is itself legal to assign to:

    ($a, $b, $c) = (1, 2, 3);

    ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);

An exception to this is that you may assign to undef in a list. This is useful for throwing away some of the return values of a function:

    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);

List assignment in scalar context returns the number of elements produced by the expression on the right side of the assignment:

    $x = (($foo,$bar) = (3,2,1));       # set $x to 3, not 2
    $x = (($foo,$bar) = f());           # set $x to f()'s return count

This is handy when you want to do a list assignment in a Boolean context, because most list functions return a null list when finished, which when assigned produces a 0, which is interpreted as FALSE.

It's also the source of a useful idiom for executing a function or performing an operation in list context and then counting the number of return values, by assigning to an empty list and then using that assignment in scalar context. For example, this code:

    $count = () = $string =~ /\d+/g;

will place into $count the number of digit groups found in $string. This happens because the pattern match is in list context (since it is being assigned to the empty list), and will therefore return a list of all matching parts of the string. The list assignment in scalar context will translate that into the number of elements (here, the number of times the pattern matched) and assign that to $count. Note that simply using

    $count = $string =~ /\d+/g;

would not have worked, since a pattern match in scalar context will only return true or false, rather than a count of matches.

The final element of a list assignment may be an array or a hash:

    ($a, $b, @rest) = split;
    my($a, $b, %rest) = @_;

You can actually put an array or hash anywhere in the list, but the first one in the list will soak up all the values, and anything after it will become undefined. This may be useful in a my() or local().

A hash can be initialized using a literal list holding pairs of items to be interpreted as a key and a value:

    # same as map assignment above
    %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);

While literal lists and named arrays are often interchangeable, that's not the case for hashes. Just because you can subscript a list value like a normal array does not mean that you can subscript a list value as a hash. Likewise, hashes included as parts of other lists (including parameters lists and return lists from functions) always flatten out into key/value pairs. That's why it's good to use references sometimes.

It is often more readable to use the => operator between key/value pairs. The => operator is mostly just a more visually distinctive synonym for a comma, but it also arranges for its left-hand operand to be interpreted as a string -- if it's a bareword that would be a legal simple identifier (=> doesn't quote compound identifiers, that contain double colons). This makes it nice for initializing hashes:

    %map = (
                 red   => 0x00f,
                 blue  => 0x0f0,
                 green => 0xf00,
       );

or for initializing hash references to be used as records:

    $rec = {
                witch => 'Mable the Merciless',
                cat   => 'Fluffy the Ferocious',
                date  => '10/31/1776',
    };

or for using call-by-named-parameter to complicated functions:

   $field = $query->radio_group(
               name      => 'group_name',
               values    => ['eenie','meenie','minie'],
               default   => 'meenie',
               linebreak => 'true',
               labels    => \%labels
   );

Note that just because a hash is initialized in that order doesn't mean that it comes out in that order. See sort in the perlfunc manpage for examples of how to arrange for an output ordering.

Subscripts

An array is subscripted by specifying a dollar sign ($), then the name of the array (without the leading @), then the subscript inside square brackets. For example:

    @myarray = (5, 50, 500, 5000);
    print "Element Number 2 is", $myarray[2], "\n";

The array indices start with 0. A negative subscript retrieves its value from the end. In our example, $myarray[-1] would have been 5000, and $myarray[-2] would have been 500.

Hash subscripts are similar, only instead of square brackets curly brackets are used. For example:

    %scientists =
    (
        "Newton" => "Isaac",
        "Einstein" => "Albert",
        "Darwin" => "Charles",
        "Feynman" => "Richard",
    );

    print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";

Slices

A common way to access an array or a hash is one scalar element at a time. You can also subscript a list to get a single element from it.

    $whoami = $ENV{"USER"};             # one element from the hash
    $parent = $ISA[0];                  # one element from the array
    $dir    = (getpwnam("daemon"))[7];  # likewise, but with list

A slice accesses several elements of a list, an array, or a hash simultaneously using a list of subscripts. It's more convenient than writing out the individual elements as a list of separate scalar values.

    ($him, $her)   = @folks[0,-1];              # array slice
    @them          = @folks[0 .. 3];            # array slice
    ($who, $home)  = @ENV{"USER", "HOME"};      # hash slice
    ($uid, $dir)   = (getpwnam("daemon"))[2,7]; # list slice

Since you can assign to a list of variables, you can also assign to an array or hash slice.

    @days[3..5]    = qw/Wed Thu Fri/;
    @colors{'red','blue','green'}
                   = (0xff0000, 0x0000ff, 0x00ff00);
    @folks[0, -1]  = @folks[-1, 0];

The previous assignments are exactly equivalent to

    ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
    ($colors{'red'}, $colors{'blue'}, $colors{'green'})
                   = (0xff0000, 0x0000ff, 0x00ff00);
    ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);

Since changing a slice changes the original array or hash that it's slicing, a foreach construct will alter some--or even all--of the values of the array or hash.

    foreach (@array[ 4 .. 10 ]) { s/peter/paul/ }

    foreach (@hash{qw[key1 key2]}) {
        s/^\s+//;           # trim leading whitespace
        s/\s+$//;           # trim trailing whitespace
        s/(\w+)/\u\L$1/g;   # "titlecase" words
    }

A slice of an empty list is still an empty list. Thus:

    @a = ()[1,0];           # @a has no elements
    @b = (@a)[0,1];         # @b has no elements
    @c = (0,1)[2,3];        # @c has no elements

But:

    @a = (1)[1,0];          # @a has two elements
    @b = (1,undef)[1,0,2];  # @b has three elements

This makes it easy to write loops that terminate when a null list is returned:

    while ( ($home, $user) = (getpwent)[7,0]) {
        printf "%-8s %s\n", $user, $home;
    }

As noted earlier in this document, the scalar sense of list assignment is the number of elements on the right-hand side of the assignment. The null list contains no elements, so when the password file is exhausted, the result is 0, not 2.

If you're confused about why you use an '@' there on a hash slice instead of a '%', think of it like this. The type of bracket (square or curly) governs whether it's an array or a hash being looked at. On the other hand, the leading symbol ('$' or '@') on the array or hash indicates whether you are getting back a singular value (a scalar) or a plural one (a list).

Typeglobs and Filehandles

Perl uses an internal type called a typeglob to hold an entire symbol table entry. The type prefix of a typeglob is a *, because it represents all types. This used to be the preferred way to pass arrays and hashes by reference into a function, but now that we have real references, this is seldom needed.

The main use of typeglobs in modern Perl is create symbol table aliases. This assignment:

    *this = *that;

makes $this an alias for $that, @this an alias for @that, %this an alias for %that, &this an alias for &that, etc. Much safer is to use a reference. This:

    local *Here::blue = \$There::green;

temporarily makes $Here::blue an alias for $There::green, but doesn't make @Here::blue an alias for @There::green, or %Here::blue an alias for %There::green, etc. See Symbol Tables in the perlmod manpage for more examples of this. Strange though this may seem, this is the basis for the whole module import/export system.

Another use for typeglobs is to pass filehandles into a function or to create new filehandles. If you need to use a typeglob to save away a filehandle, do it this way:

    $fh = *STDOUT;

or perhaps as a real reference, like this:

    $fh = \*STDOUT;

See the perlsub manpage for examples of using these as indirect filehandles in functions.

Typeglobs are also a way to create a local filehandle using the local() operator. These last until their block is exited, but may be passed back. For example:

    sub newopen {
        my $path = shift;
        local  *FH;  # not my!
        open   (FH, $path)          or  return undef;
        return *FH;
    }
    $fh = newopen('/etc/passwd');

Now that we have the *foo{THING} notation, typeglobs aren't used as much for filehandle manipulations, although they're still needed to pass brand new file and directory handles into or out of functions. That's because *HANDLE{IO} only works if HANDLE has already been used as a handle. In other words, *FH must be used to create new symbol table entries; *foo{THING} cannot. When in doubt, use *FH.

All functions that are capable of creating filehandles (open(), opendir(), pipe(), socketpair(), sysopen(), socket(), and accept()) automatically create an anonymous filehandle if the handle passed to them is an uninitialized scalar variable. This allows the constructs such as open(my $fh, ...) and open(local $fh,...) to be used to create filehandles that will conveniently be closed automatically when the scope ends, provided there are no other references to them. This largely eliminates the need for typeglobs when opening filehandles that must be passed around, as in the following example:

    sub myopen {
        open my $fh, "@_"
             or die "Can't open '@_': $!";
        return $fh;
    }

    {
        my $f = myopen("</etc/motd");
        print <$f>;
        # $f implicitly closed here
    }

Note that if an initialized scalar variable is used instead the result is different: my $fh='zzz'; open($fh, ...) is equivalent to open( *{'zzz'}, ...). use strict 'refs' forbids such practice.

Another way to create anonymous filehandles is with the Symbol module or with the IO::Handle module and its ilk. These modules have the advantage of not hiding different types of the same name during the local(). See the bottom of open() in the perlfunc manpage for an example.

SEE ALSO

See the perlvar manpage for a description of Perl's built-in variables and a discussion of legal variable names. See the perlref manpage, the perlsub manpage, and Symbol Tables in the perlmod manpage for more discussion on typeglobs and the *foo{THING} syntax.


perldsc - Perl Data Structures Cookbook

  • REFERENCES
  • COMMON MISTAKES
  • CAVEAT ON PRECEDENCE
  • WHY YOU SHOULD ALWAYS use strict
  • DEBUGGING
  • CODE EXAMPLES
  • ARRAYS OF ARRAYS
    • Declaration of an ARRAY OF ARRAYS
    • Generation of an ARRAY OF ARRAYS
    • Access and Printing of an ARRAY OF ARRAYS
  • HASHES OF ARRAYS
    • Declaration of a HASH OF ARRAYS
    • Generation of a HASH OF ARRAYS
    • Access and Printing of a HASH OF ARRAYS
  • ARRAYS OF HASHES
    • Declaration of an ARRAY OF HASHES
    • Generation of an ARRAY OF HASHES
    • Access and Printing of an ARRAY OF HASHES
  • HASHES OF HASHES
    • Declaration of a HASH OF HASHES
    • Generation of a HASH OF HASHES
    • Access and Printing of a HASH OF HASHES
  • MORE ELABORATE RECORDS
    • Declaration of MORE ELABORATE RECORDS
    • Declaration of a HASH OF COMPLEX RECORDS
    • Generation of a HASH OF COMPLEX RECORDS
  • Database Ties
  • SEE ALSO
  • AUTHOR

NAME

perldsc - Perl Data Structures Cookbook

DESCRIPTION

The single feature most sorely lacking in the Perl programming language prior to its 5.0 release was complex data structures. Even without direct language support, some valiant programmers did manage to emulate them, but it was hard work and not for the faint of heart. You could occasionally get away with the $m{$AoA,$b} notation borrowed from awk in which the keys are actually more like a single concatenated string "$AoA$b", but traversal and sorting were difficult. More desperate programmers even hacked Perl's internal symbol table directly, a strategy that proved hard to develop and maintain--to put it mildly.

The 5.0 release of Perl let us have complex data structures. You may now write something like this and all of a sudden, you'd have an array with three dimensions!

    for $x (1 .. 10) {
        for $y (1 .. 10) {
            for $z (1 .. 10) {
                $AoA[$x][$y][$z] =
                    $x ** $y + $z;
            }
        }
    }

Alas, however simple this may appear, underneath it's a much more elaborate construct than meets the eye!

How do you print it out? Why can't you say just print @AoA? How do you sort it? How can you pass it to a function or get one of these back from a function? Is it an object? Can you save it to disk to read back later? How do you access whole rows or columns of that matrix? Do all the values have to be numeric?

As you see, it's quite easy to become confused. While some small portion of the blame for this can be attributed to the reference-based implementation, it's really more due to a lack of existing documentation with examples designed for the beginner.

This document is meant to be a detailed but understandable treatment of the many different sorts of data structures you might want to develop. It should also serve as a cookbook of examples. That way, when you need to create one of these complex data structures, you can just pinch, pilfer, or purloin a drop-in example from here.

Let's look at each of these possible constructs in detail. There are separate sections on each of the following:

  • arrays of arrays
  • hashes of arrays
  • arrays of hashes
  • hashes of hashes
  • more elaborate constructs

But for now, let's look at general issues common to all these types of data structures.

REFERENCES

The most important thing to understand about all data structures in Perl -- including multidimensional arrays--is that even though they might appear otherwise, Perl @ARRAYs and %HASHes are all internally one-dimensional. They can hold only scalar values (meaning a string, number, or a reference). They cannot directly contain other arrays or hashes, but instead contain references to other arrays or hashes.

You can't use a reference to an array or hash in quite the same way that you would a real array or hash. For C or C++ programmers unused to distinguishing between arrays and pointers to the same, this can be confusing. If so, just think of it as the difference between a structure and a pointer to a structure.

You can (and should) read more about references in the perlref(1) man page. Briefly, references are rather like pointers that know what they point to. (Objects are also a kind of reference, but we won't be needing them right away--if ever.) This means that when you have something which looks to you like an access to a two-or-more-dimensional array and/or hash, what's really going on is that the base type is merely a one-dimensional entity that contains references to the next level. It's just that you can use it as though it were a two-dimensional one. This is actually the way almost all C multidimensional arrays work as well.

    $array[7][12]                       # array of arrays
    $array[7]{string}                   # array of hashes
    $hash{string}[7]                    # hash of arrays
    $hash{string}{'another string'}     # hash of hashes

Now, because the top level contains only references, if you try to print out your array in with a simple print() function, you'll get something that doesn't look very nice, like this:

    @AoA = ( [2, 3], [4, 5, 7], [0] );
    print $AoA[1][2];
      7
    print @AoA;
      ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)

That's because Perl doesn't (ever) implicitly dereference your variables. If you want to get at the thing a reference is referring to, then you have to do this yourself using either prefix typing indicators, like ${$blah}, @{$blah}, @{$blah[$i]}, or else postfix pointer arrows, like $a->[3], $h->{fred}, or even $ob->method()->[3].

COMMON MISTAKES

The two most common mistakes made in constructing something like an array of arrays is either accidentally counting the number of elements or else taking a reference to the same memory location repeatedly. Here's the case where you just get the count instead of a nested array:

    for $i (1..10) {
        @array = somefunc($i);
        $AoA[$i] = @array;      # WRONG!
    }

That's just the simple case of assigning an array to a scalar and getting its element count. If that's what you really and truly want, then you might do well to consider being a tad more explicit about it, like this:

    for $i (1..10) {
        @array = somefunc($i);
        $counts[$i] = scalar @array;
    }

Here's the case of taking a reference to the same memory location again and again:

    for $i (1..10) {
        @array = somefunc($i);
        $AoA[$i] = \@array;     # WRONG!
    }

So, what's the big problem with that? It looks right, doesn't it? After all, I just told you that you need an array of references, so by golly, you've made me one!

Unfortunately, while this is true, it's still broken. All the references in @AoA refer to the very same place, and they will therefore all hold whatever was last in @array! It's similar to the problem demonstrated in the following C program:

    #include <pwd.h>
    main() {
        struct passwd *getpwnam(), *rp, *dp;
        rp = getpwnam("root");
        dp = getpwnam("daemon");

        printf("daemon name is %s\nroot name is %s\n",
                dp->pw_name, rp->pw_name);
            }

Which will print

    daemon name is daemon
    root name is daemon

The problem is that both rp and dp are pointers to the same location in memory! In C, you'd have to remember to malloc() yourself some new memory. In Perl, you'll want to use the array constructor [] or the hash constructor {} instead. Here's the right way to do the preceding broken code fragments:

    for $i (1..10) {
        @array = somefunc($i);
        $AoA[$i] = [ @array ];
    }

The square brackets make a reference to a new array with a copy of what's in @array at the time of the assignment. This is what you want.

Note that this will produce something similar, but it's much harder to read:

    for $i (1..10) {
        @array = 0 .. $i;
        @{$AoA[$i]} = @array;
    }

Is it the same? Well, maybe so--and maybe not. The subtle difference is that when you assign something in square brackets, you know for sure it's always a brand new reference with a new copy of the data. Something else could be going on in this new case with the @{$AoA[$i]}} dereference on the left-hand-side of the assignment. It all depends on whether $AoA[$i] had been undefined to start with, or whether it already contained a reference. If you had already populated @AoA with references, as in

    $AoA[3] = \@another_array;

Then the assignment with the indirection on the left-hand-side would use the existing reference that was already there:

    @{$AoA[3]} = @array;

Of course, this would have the "interesting" effect of clobbering @another_array. (Have you ever noticed how when a programmer says something is "interesting", that rather than meaning "intriguing", they're disturbingly more apt to mean that it's "annoying", "difficult", or both? :-)

So just remember always to use the array or hash constructors with [] or {}, and you'll be fine, although it's not always optimally efficient.

Surprisingly, the following dangerous-looking construct will actually work out fine:

    for $i (1..10) {
        my @array = somefunc($i);
        $AoA[$i] = \@array;
    }

That's because my() is more of a run-time statement than it is a compile-time declaration per se. This means that the my() variable is remade afresh each time through the loop. So even though it looks as though you stored the same variable reference each time, you actually did not! This is a subtle distinction that can produce more efficient code at the risk of misleading all but the most experienced of programmers. So I usually advise against teaching it to beginners. In fact, except for passing arguments to functions, I seldom like to see the gimme-a-reference operator (backslash) used much at all in code. Instead, I advise beginners that they (and most of the rest of us) should try to use the much more easily understood constructors [] and {} instead of relying upon lexical (or dynamic) scoping and hidden reference-counting to do the right thing behind the scenes.

In summary:

    $AoA[$i] = [ @array ];      # usually best
    $AoA[$i] = \@array;         # perilous; just how my() was that array?
    @{ $AoA[$i] } = @array;     # way too tricky for most programmers

CAVEAT ON PRECEDENCE

Speaking of things like @{$AoA[$i]}, the following are actually the same thing: >>

    $aref->[2][2]       # clear
    $$aref[2][2]        # confusing

That's because Perl's precedence rules on its five prefix dereferencers (which look like someone swearing: $ @ * % &) make them bind more tightly than the postfix subscripting brackets or braces! This will no doubt come as a great shock to the C or C++ programmer, who is quite accustomed to using *a[i] to mean what's pointed to by the i'th element of a. That is, they first take the subscript, and only then dereference the thing at that subscript. That's fine in C, but this isn't C.

The seemingly equivalent construct in Perl, $$aref[$i] first does the deref of $aref, making it take $aref as a reference to an array, and then dereference that, and finally tell you the i'th value of the array pointed to by $AoA. If you wanted the C notion, you'd have to write ${$AoA[$i]} to force the $AoA[$i] to get evaluated first before the leading $ dereferencer.

WHY YOU SHOULD ALWAYS use strict

If this is starting to sound scarier than it's worth, relax. Perl has some features to help you avoid its most common pitfalls. The best way to avoid getting confused is to start every program like this:

    #!/usr/bin/perl -w
    use strict;

This way, you'll be forced to declare all your variables with my() and also disallow accidental "symbolic dereferencing". Therefore if you'd done this:

    my $aref = [
        [ "fred", "barney", "pebbles", "bambam", "dino", ],
        [ "homer", "bart", "marge", "maggie", ],
        [ "george", "jane", "elroy", "judy", ],
    ];

    print $aref[2][2];

The compiler would immediately flag that as an error at compile time, because you were accidentally accessing @aref, an undeclared variable, and it would thereby remind you to write instead:

    print $aref->[2][2]

DEBUGGING

Before version 5.002, the standard Perl debugger didn't do a very nice job of printing out complex data structures. With 5.002 or above, the debugger includes several new features, including command line editing as well as the x command to dump out complex data structures. For example, given the assignment to $AoA above, here's the debugger output:

    DB<1> x $AoA
    $AoA = ARRAY(0x13b5a0)
       0  ARRAY(0x1f0a24)
          0  'fred'
          1  'barney'
          2  'pebbles'
          3  'bambam'
          4  'dino'
       1  ARRAY(0x13b558)
          0  'homer'
          1  'bart'
          2  'marge'
          3  'maggie'
       2  ARRAY(0x13b540)
          0  'george'
          1  'jane'
          2  'elroy'
          3  'judy'

CODE EXAMPLES

Presented with little comment (these will get their own manpages someday) here are short code examples illustrating access of various types of data structures.

ARRAYS OF ARRAYS

Declaration of an ARRAY OF ARRAYS

 @AoA = (
        [ "fred", "barney" ],
        [ "george", "jane", "elroy" ],
        [ "homer", "marge", "bart" ],
      );

Generation of an ARRAY OF ARRAYS

 # reading from file
 while ( <> ) {
     push @AoA, [ split ];
 }

 # calling a function
 for $i ( 1 .. 10 ) {
     $AoA[$i] = [ somefunc($i) ];
 }

 # using temp vars
 for $i ( 1 .. 10 ) {
     @tmp = somefunc($i);
     $AoA[$i] = [ @tmp ];
 }

 # add to an existing row
 push @{ $AoA[0] }, "wilma", "betty";

Access and Printing of an ARRAY OF ARRAYS

 # one element
 $AoA[0][0] = "Fred";

 # another element
 $AoA[1][1] =~ s/(\w)/\u$1/;

 # print the whole thing with refs
 for $aref ( @AoA ) {
     print "\t [ @$aref ],\n";
 }

 # print the whole thing with indices
 for $i ( 0 .. $#AoA ) {
     print "\t [ @{$AoA[$i]} ],\n";
 }

 # print the whole thing one at a time
 for $i ( 0 .. $#AoA ) {
     for $j ( 0 .. $#{ $AoA[$i] } ) {
         print "elt $i $j is $AoA[$i][$j]\n";
     }
 }

HASHES OF ARRAYS

Declaration of a HASH OF ARRAYS

 %HoA = (
        flintstones        => [ "fred", "barney" ],
        jetsons            => [ "george", "jane", "elroy" ],
        simpsons           => [ "homer", "marge", "bart" ],
      );

Generation of a HASH OF ARRAYS

 # reading from file
 # flintstones: fred barney wilma dino
 while ( <> ) {
     next unless s/^(.*?):\s*//;
     $HoA{$1} = [ split ];
 }

 # reading from file; more temps
 # flintstones: fred barney wilma dino
 while ( $line = <> ) {
     ($who, $rest) = split /:\s*/, $line, 2;
     @fields = split ' ', $rest;
     $HoA{$who} = [ @fields ];
 }

 # calling a function that returns a list
 for $group ( "simpsons", "jetsons", "flintstones" ) {
     $HoA{$group} = [ get_family($group) ];
 }

 # likewise, but using temps
 for $group ( "simpsons", "jetsons", "flintstones" ) {
     @members = get_family($group);
     $HoA{$group} = [ @members ];
 }

 # append new members to an existing family
 push @{ $HoA{"flintstones"} }, "wilma", "betty";

Access and Printing of a HASH OF ARRAYS

 # one element
 $HoA{flintstones}[0] = "Fred";

 # another element
 $HoA{simpsons}[1] =~ s/(\w)/\u$1/;

 # print the whole thing
 foreach $family ( keys %HoA ) {
     print "$family: @{ $HoA{$family} }\n"
 }

 # print the whole thing with indices
 foreach $family ( keys %HoA ) {
     print "family: ";
     foreach $i ( 0 .. $#{ $HoA{$family} } ) {
         print " $i = $HoA{$family}[$i]";
     }
     print "\n";
 }

 # print the whole thing sorted by number of members
 foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} } keys %HoA ) {
     print "$family: @{ $HoA{$family} }\n"
 }

 # print the whole thing sorted by number of members and name
 foreach $family ( sort {
                            @{$HoA{$b}} <=> @{$HoA{$a}}
                                        ||
                                    $a cmp $b
            } keys %HoA )
 {
     print "$family: ", join(", ", sort @{ $HoA{$family} }), "\n";
 }

ARRAYS OF HASHES

Declaration of an ARRAY OF HASHES

 @AoH = (
        {
            Lead     => "fred",
            Friend   => "barney",
        },
        {
            Lead     => "george",
            Wife     => "jane",
            Son      => "elroy",
        },
        {
            Lead     => "homer",
            Wife     => "marge",
            Son      => "bart",
        }
  );

Generation of an ARRAY OF HASHES

 # reading from file
 # format: LEAD=fred FRIEND=barney
 while ( <> ) {
     $rec = {};
     for $field ( split ) {
         ($key, $value) = split /=/, $field;
         $rec->{$key} = $value;
     }
     push @AoH, $rec;
 }

 # reading from file
 # format: LEAD=fred FRIEND=barney
 # no temp
 while ( <> ) {
     push @AoH, { split /[\s+=]/ };
 }

 # calling a function  that returns a key/value pair list, like
 # "lead","fred","daughter","pebbles"
 while ( %fields = getnextpairset() ) {
     push @AoH, { %fields };
 }

 # likewise, but using no temp vars
 while (<>) {
     push @AoH, { parsepairs($_) };
 }

 # add key/value to an element
 $AoH[0]{pet} = "dino";
 $AoH[2]{pet} = "santa's little helper";

Access and Printing of an ARRAY OF HASHES

 # one element
 $AoH[0]{lead} = "fred";

 # another element
 $AoH[1]{lead} =~ s/(\w)/\u$1/;

 # print the whole thing with refs
 for $href ( @AoH ) {
     print "{ ";
     for $role ( keys %$href ) {
         print "$role=$href->{$role} ";
     }
     print "}\n";
 }

 # print the whole thing with indices
 for $i ( 0 .. $#AoH ) {
     print "$i is { ";
     for $role ( keys %{ $AoH[$i] } ) {
         print "$role=$AoH[$i]{$role} ";
     }
     print "}\n";
 }

 # print the whole thing one at a time
 for $i ( 0 .. $#AoH ) {
     for $role ( keys %{ $AoH[$i] } ) {
         print "elt $i $role is $AoH[$i]{$role}\n";
     }
 }

HASHES OF HASHES

Declaration of a HASH OF HASHES

 %HoH = (
        flintstones => {
                lead      => "fred",
                pal       => "barney",
        },
        jetsons     => {
                lead      => "george",
                wife      => "jane",
                "his boy" => "elroy",
        },
        simpsons    => {
                lead      => "homer",
                wife      => "marge",
                kid       => "bart",
        },
 );

Generation of a HASH OF HASHES

 # reading from file
 # flintstones: lead=fred pal=barney wife=wilma pet=dino
 while ( <> ) {
     next unless s/^(.*?):\s*//;
     $who = $1;
     for $field ( split ) {
         ($key, $value) = split /=/, $field;
         $HoH{$who}{$key} = $value;
     }

 # reading from file; more temps
 while ( <> ) {
     next unless s/^(.*?):\s*//;
     $who = $1;
     $rec = {};
     $HoH{$who} = $rec;
     for $field ( split ) {
         ($key, $value) = split /=/, $field;
         $rec->{$key} = $value;
     }
 }

 # calling a function  that returns a key,value hash
 for $group ( "simpsons", "jetsons", "flintstones" ) {
     $HoH{$group} = { get_family($group) };
 }

 # likewise, but using temps
 for $group ( "simpsons", "jetsons", "flintstones" ) {
     %members = get_family($group);
     $HoH{$group} = { %members };
 }

 # append new members to an existing family
 %new_folks = (
     wife => "wilma",
     pet  => "dino",
 );

 for $what (keys %new_folks) {
     $HoH{flintstones}{$what} = $new_folks{$what};
 }

Access and Printing of a HASH OF HASHES

 # one element
 $HoH{flintstones}{wife} = "wilma";

 # another element
 $HoH{simpsons}{lead} =~ s/(\w)/\u$1/;

 # print the whole thing
 foreach $family ( keys %HoH ) {
     print "$family: { ";
     for $role ( keys %{ $HoH{$family} } ) {
         print "$role=$HoH{$family}{$role} ";
     }
     print "}\n";
 }

 # print the whole thing  somewhat sorted
 foreach $family ( sort keys %HoH ) {
     print "$family: { ";
     for $role ( sort keys %{ $HoH{$family} } ) {
         print "$role=$HoH{$family}{$role} ";
     }
     print "}\n";
 }

 # print the whole thing sorted by number of members
 foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$a}} } keys %HoH ) {
     print "$family: { ";
     for $role ( sort keys %{ $HoH{$family} } ) {
         print "$role=$HoH{$family}{$role} ";
     }
     print "}\n";
 }

 # establish a sort order (rank) for each role
 $i = 0;
 for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i }

 # now print the whole thing sorted by number of members
 foreach $family ( sort { keys %{ $HoH{$b} } <=> keys %{ $HoH{$a} } } keys %HoH ) {
     print "$family: { ";
     # and print these according to rank order
     for $role ( sort { $rank{$a} <=> $rank{$b} }  keys %{ $HoH{$family} } ) {
         print "$role=$HoH{$family}{$role} ";
     }
     print "}\n";
 }

MORE ELABORATE RECORDS

Declaration of MORE ELABORATE RECORDS

Here's a sample showing how to create and use a record whose fields are of many different sorts:

     $rec = {
         TEXT      => $string,
         SEQUENCE  => [ @old_values ],
         LOOKUP    => { %some_table },
         THATCODE  => \&some_function,
         THISCODE  => sub { $_[0] ** $_[1] },
         HANDLE    => \*STDOUT,
     };

     print $rec->{TEXT};

     print $rec->{SEQUENCE}[0];
     $last = pop @ { $rec->{SEQUENCE} };

     print $rec->{LOOKUP}{"key"};
     ($first_k, $first_v) = each %{ $rec->{LOOKUP} };

     $answer = $rec->{THATCODE}->($arg);
     $answer = $rec->{THISCODE}->($arg1, $arg2);

     # careful of extra block braces on fh ref
     print { $rec->{HANDLE} } "a string\n";

     use FileHandle;
     $rec->{HANDLE}->autoflush(1);
     $rec->{HANDLE}->print(" a string\n");

Declaration of a HASH OF COMPLEX RECORDS

     %TV = (
        flintstones => {
            series   => "flintstones",
            nights   => [ qw(monday thursday friday) ],
            members  => [
                { name => "fred",    role => "lead", age  => 36, },
                { name => "wilma",   role => "wife", age  => 31, },
                { name => "pebbles", role => "kid",  age  =>  4, },
            ],
        },

        jetsons     => {
            series   => "jetsons",
            nights   => [ qw(wednesday saturday) ],
            members  => [
                { name => "george",  role => "lead", age  => 41, },
                { name => "jane",    role => "wife", age  => 39, },
                { name => "elroy",   role => "kid",  age  =>  9, },
            ],
         },

        simpsons    => {
            series   => "simpsons",
            nights   => [ qw(monday) ],
            members  => [
                { name => "homer", role => "lead", age  => 34, },
                { name => "marge", role => "wife", age => 37, },
                { name => "bart",  role => "kid",  age  =>  11, },
            ],
         },
              );

Generation of a HASH OF COMPLEX RECORDS

     # reading from file
     # this is most easily done by having the file itself be
     # in the raw data format as shown above.  perl is happy
     # to parse complex data structures if declared as data, so
     # sometimes it's easiest to do that

     # here's a piece by piece build up
     $rec = {};
     $rec->{series} = "flintstones";
     $rec->{nights} = [ find_days() ];

     @members = ();
     # assume this file in field=value syntax
     while (<>) {
         %fields = split /[\s=]+/;
         push @members, { %fields };
     }
     $rec->{members} = [ @members ];

     # now remember the whole thing
     $TV{ $rec->{series} } = $rec;

     ###########################################################
     # now, you might want to make interesting extra fields that
     # include pointers back into the same data structure so if
     # change one piece, it changes everywhere, like for example
     # if you wanted a {kids} field that was a reference
     # to an array of the kids' records without having duplicate
     # records and thus update problems.
     ###########################################################
     foreach $family (keys %TV) {
         $rec = $TV{$family}; # temp pointer
         @kids = ();
         for $person ( @{ $rec->{members} } ) {
             if ($person->{role} =~ /kid|son|daughter/) {
                 push @kids, $person;
             }
         }
         # REMEMBER: $rec and $TV{$family} point to same data!!
         $rec->{kids} = [ @kids ];
     }

     # you copied the array, but the array itself contains pointers
     # to uncopied objects. this means that if you make bart get
     # older via

     $TV{simpsons}{kids}[0]{age}++;

     # then this would also change in
     print $TV{simpsons}{members}[2]{age};

     # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2]
     # both point to the same underlying anonymous hash table

     # print the whole thing
     foreach $family ( keys %TV ) {
         print "the $family";
         print " is on during @{ $TV{$family}{nights} }\n";
         print "its members are:\n";
         for $who ( @{ $TV{$family}{members} } ) {
             print " $who->{name} ($who->{role}), age $who->{age}\n";
         }
         print "it turns out that $TV{$family}{lead} has ";
         print scalar ( @{ $TV{$family}{kids} } ), " kids named ";
         print join (", ", map { $_->{name} } @{ $TV{$family}{kids} } );
         print "\n";
     }

Database Ties

You cannot easily tie a multilevel data structure (such as a hash of hashes) to a dbm file. The first problem is that all but GDBM and Berkeley DB have size limitations, but beyond that, you also have problems with how references are to be represented on disk. One experimental module that does partially attempt to address this need is the MLDBM module. Check your nearest CPAN site as described in the perlmodlib manpage for source code to MLDBM.

SEE ALSO

perlref(1), perllol(1), perldata(1), perlobj(1)

AUTHOR

Tom Christiansen <tchrist@perl.com>

Last update: Wed Oct 23 04:57:50 MET DST 1996


perllol - Manipulating Arrays of Arrays in Perl

    • Declaration and Access of Arrays of Arrays
    • Growing Your Own
    • Access and Printing
    • Slices
  • SEE ALSO
  • AUTHOR

NAME

perllol - Manipulating Arrays of Arrays in Perl

DESCRIPTION

Declaration and Access of Arrays of Arrays

The simplest thing to build is an array of arrays (sometimes imprecisely called a list of lists). It's reasonably easy to understand, and almost everything that applies here will also be applicable later on with the fancier data structures.

An array of an array is just a regular old array @AoA that you can get at with two subscripts, like $AoA[3][2]. Here's a declaration of the array:

    # assign to our array, an array of array references
    @AoA = (
           [ "fred", "barney" ],
           [ "george", "jane", "elroy" ],
           [ "homer", "marge", "bart" ],
    );

    print $AoA[2][2];
      bart

Now you should be very careful that the outer bracket type is a round one, that is, a parenthesis. That's because you're assigning to an @array, so you need parentheses. If you wanted there not to be an @AoA, but rather just a reference to it, you could do something more like this:

    # assign a reference to array of array references
    $ref_to_AoA = [
        [ "fred", "barney", "pebbles", "bambam", "dino", ],
        [ "homer", "bart", "marge", "maggie", ],
        [ "george", "jane", "elroy", "judy", ],
    ];

    print $ref_to_AoA->[2][2];

Notice that the outer bracket type has changed, and so our access syntax has also changed. That's because unlike C, in perl you can't freely interchange arrays and references thereto. $ref_to_AoA is a reference to an array, whereas @AoA is an array proper. Likewise, $AoA[2] is not an array, but an array ref. So how come you can write these:

    $AoA[2][2]
    $ref_to_AoA->[2][2]

instead of having to write these:

    $AoA[2]->[2]
    $ref_to_AoA->[2]->[2]

Well, that's because the rule is that on adjacent brackets only (whether square or curly), you are free to omit the pointer dereferencing arrow. But you cannot do so for the very first one if it's a scalar containing a reference, which means that $ref_to_AoA always needs it.

Growing Your Own

That's all well and good for declaration of a fixed data structure, but what if you wanted to add new elements on the fly, or build it up entirely from scratch?

First, let's look at reading it in from a file. This is something like adding a row at a time. We'll assume that there's a flat file in which each line is a row and each word an element. If you're trying to develop an @AoA array containing all these, here's the right way to do that:

    while (<>) {
        @tmp = split;
        push @AoA, [ @tmp ];
    }

You might also have loaded that from a function:

    for $i ( 1 .. 10 ) {
        $AoA[$i] = [ somefunc($i) ];
    }

Or you might have had a temporary variable sitting around with the array in it.

    for $i ( 1 .. 10 ) {
        @tmp = somefunc($i);
        $AoA[$i] = [ @tmp ];
    }

It's very important that you make sure to use the [] array reference constructor. That's because this will be very wrong:

    $AoA[$i] = @tmp;

You see, assigning a named array like that to a scalar just counts the number of elements in @tmp, which probably isn't what you want.

If you are running under use strict, you'll have to add some declarations to make it happy:

    use strict;
    my(@AoA, @tmp);
    while (<>) {
        @tmp = split;
        push @AoA, [ @tmp ];
    }

Of course, you don't need the temporary array to have a name at all:

    while (<>) {
        push @AoA, [ split ];
    }

You also don't have to use push(). You could just make a direct assignment if you knew where you wanted to put it:

    my (@AoA, $i, $line);
    for $i ( 0 .. 10 ) {
        $line = <>;
        $AoA[$i] = [ split ' ', $line ];
    }

or even just

    my (@AoA, $i);
    for $i ( 0 .. 10 ) {
        $AoA[$i] = [ split ' ', <> ];
    }

You should in general be leery of using functions that could potentially return lists in scalar context without explicitly stating such. This would be clearer to the casual reader:

    my (@AoA, $i);
    for $i ( 0 .. 10 ) {
        $AoA[$i] = [ split ' ', scalar(<>) ];
    }

If you wanted to have a $ref_to_AoA variable as a reference to an array, you'd have to do something like this:

    while (<>) {
        push @$ref_to_AoA, [ split ];
    }

Now you can add new rows. What about adding new columns? If you're dealing with just matrices, it's often easiest to use simple assignment:

    for $x (1 .. 10) {
        for $y (1 .. 10) {
            $AoA[$x][$y] = func($x, $y);
        }
    }

    for $x ( 3, 7, 9 ) {
        $AoA[$x][20] += func2($x);
    }

It doesn't matter whether those elements are already there or not: it'll gladly create them for you, setting intervening elements to undef as need be.

If you wanted just to append to a row, you'd have to do something a bit funnier looking:

    # add new columns to an existing row
    push @{ $AoA[0] }, "wilma", "betty";

Notice that I couldn't say just:

    push $AoA[0], "wilma", "betty";  # WRONG!

In fact, that wouldn't even compile. How come? Because the argument to push() must be a real array, not just a reference to such.

Access and Printing

Now it's time to print your data structure out. How are you going to do that? Well, if you want only one of the elements, it's trivial:

    print $AoA[0][0];

If you want to print the whole thing, though, you can't say

    print @AoA;         # WRONG

because you'll get just references listed, and perl will never automatically dereference things for you. Instead, you have to roll yourself a loop or two. This prints the whole structure, using the shell-style for() construct to loop across the outer set of subscripts.

    for $aref ( @AoA ) {
        print "\t [ @$aref ],\n";
    }

If you wanted to keep track of subscripts, you might do this:

    for $i ( 0 .. $#AoA ) {
        print "\t elt $i is [ @{$AoA[$i]} ],\n";
    }

or maybe even this. Notice the inner loop.

    for $i ( 0 .. $#AoA ) {
        for $j ( 0 .. $#{$AoA[$i]} ) {
            print "elt $i $j is $AoA[$i][$j]\n";
        }
    }

As you can see, it's getting a bit complicated. That's why sometimes is easier to take a temporary on your way through:

    for $i ( 0 .. $#AoA ) {
        $aref = $AoA[$i];
        for $j ( 0 .. $#{$aref} ) {
            print "elt $i $j is $AoA[$i][$j]\n";
        }
    }

Hmm... that's still a bit ugly. How about this:

    for $i ( 0 .. $#AoA ) {
        $aref = $AoA[$i];
        $n = @$aref - 1;
        for $j ( 0 .. $n ) {
            print "elt $i $j is $AoA[$i][$j]\n";
        }
    }

Slices

If you want to get at a slice (part of a row) in a multidimensional array, you're going to have to do some fancy subscripting. That's because while we have a nice synonym for single elements via the pointer arrow for dereferencing, no such convenience exists for slices. (Remember, of course, that you can always write a loop to do a slice operation.)

Here's how to do one operation using a loop. We'll assume an @AoA variable as before.

    @part = ();
    $x = 4;
    for ($y = 7; $y < 13; $y++) {
        push @part, $AoA[$x][$y];
    }

That same loop could be replaced with a slice operation:

    @part = @{ $AoA[4] } [ 7..12 ];

but as you might well imagine, this is pretty rough on the reader.

Ah, but what if you wanted a two-dimensional slice, such as having $x run from 4..8 and $y run from 7 to 12? Hmm... here's the simple way:

    @newAoA = ();
    for ($startx = $x = 4; $x <= 8; $x++) {
        for ($starty = $y = 7; $y <= 12; $y++) {
            $newAoA[$x - $startx][$y - $starty] = $AoA[$x][$y];
        }
    }

We can reduce some of the looping through slices

    for ($x = 4; $x <= 8; $x++) {
        push @newAoA, [ @{ $AoA[$x] } [ 7..12 ] ];
    }

If you were into Schwartzian Transforms, you would probably have selected map for that

    @newAoA = map { [ @{ $AoA[$_] } [ 7..12 ] ] } 4 .. 8;

Although if your manager accused of seeking job security (or rapid insecurity) through inscrutable code, it would be hard to argue. :-) If I were you, I'd put that in a function:

    @newAoA = splice_2D( \@AoA, 4 => 8, 7 => 12 );
    sub splice_2D {
        my $lrr = shift;        # ref to array of array refs!
        my ($x_lo, $x_hi,
            $y_lo, $y_hi) = @_;

        return map {
            [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ]
        } $x_lo .. $x_hi;
            }

SEE ALSO

perldata(1), perlref(1), perldsc(1)

AUTHOR

Tom Christiansen <tchrist@perl.com>

Last update: Thu Jun 4 16:16:23 MDT 1998


perlnumber - semantics of numbers and numeric operations in Perl

  • Storing numbers
  • Numeric operators and numeric conversions
  • Flavors of Perl numeric operations
  • AUTHOR
  • SEE ALSO

NAME

perlnumber - semantics of numbers and numeric operations in Perl

SYNOPSIS

    $n = 1234;              # decimal integer
    $n = 0b1110011;         # binary integer
    $n = 01234;             # octal integer
    $n = 0x1234;            # hexadecimal integer
    $n = 12.34e-56;         # exponential notation
    $n = "-12.34e56";       # number specified as a string
    $n = "1234";            # number specified as a string

DESCRIPTION

This document describes how Perl internally handles numeric values.

Perl's operator overloading facility is completely ignored here. Operator overloading allows user-defined behaviors for numbers, such as operations over arbitrarily large integers, floating points numbers with arbitrary precision, operations over "exotic" numbers such as modular arithmetic or p-adic arithmetic, and so on. See the overload manpage for details.

Storing numbers

Perl can internally represent numbers in 3 different ways: as native integers, as native floating point numbers, and as decimal strings. Decimal strings may have an exponential notation part, as in "12.34e-56". Native here means "a format supported by the C compiler which was used to build perl".

The term "native" does not mean quite as much when we talk about native integers, as it does when native floating point numbers are involved. The only implication of the term "native" on integers is that the limits for the maximal and the minimal supported true integral quantities are close to powers of 2. However, "native" floats have a most fundamental restriction: they may represent only those numbers which have a relatively "short" representation when converted to a binary fraction. For example, 0.9 cannot be represented by a native float, since the binary fraction for 0.9 is infinite:

  binary0.1110011001100...

with the sequence 1100 repeating again and again. In addition to this limitation, the exponent of the binary number is also restricted when it is represented as a floating point number. On typical hardware, floating point values can store numbers with up to 53 binary digits, and with binary exponents between -1024 and 1024. In decimal representation this is close to 16 decimal digits and decimal exponents in the range of -304..304. The upshot of all this is that Perl cannot store a number like 12345678901234567 as a floating point number on such architectures without loss of information.

Similarly, decimal strings can represent only those numbers which have a finite decimal expansion. Being strings, and thus of arbitrary length, there is no practical limit for the exponent or number of decimal digits for these numbers. (But realize that what we are discussing the rules for just the storage of these numbers. The fact that you can store such "large" numbers does not mean that the operations over these numbers will use all of the significant digits. See Numeric operators and numeric conversions for details.)

In fact numbers stored in the native integer format may be stored either in the signed native form, or in the unsigned native form. Thus the limits for Perl numbers stored as native integers would typically be -2**31..2**32-1, with appropriate modifications in the case of 64-bit integers. Again, this does not mean that Perl can do operations only over integers in this range: it is possible to store many more integers in floating point format.

Summing up, Perl numeric values can store only those numbers which have a finite decimal expansion or a "short" binary expansion.

Numeric operators and numeric conversions

As mentioned earlier, Perl can store a number in any one of three formats, but most operators typically understand only one of those formats. When a numeric value is passed as an argument to such an operator, it will be converted to the format understood by the operator.

Six such conversions are possible:

  native integer        --> native floating point       (*)
  native integer        --> decimal string
  native floating_point --> native integer              (*)
  native floating_point --> decimal string              (*)
  decimal string        --> native integer
  decimal string        --> native floating point       (*)

These conversions are governed by the following general rules:

  • If the source number can be represented in the target form, that representation is used.

  • If the source number is outside of the limits representable in the target form, a representation of the closest limit is used. (Loss of information)

  • If the source number is between two numbers representable in the target form, a representation of one of these numbers is used. (Loss of information)

  • In native floating point --> native integer conversions the magnitude of the result is less than or equal to the magnitude of the source. ("Rounding to zero".)

  • If the decimal string --> native integer conversion cannot be done without loss of information, the result is compatible with the conversion sequence decimal_string --> native_floating_point --> native_integer. In particular, rounding is strongly biased to 0, though a number like "0.99999999999999999999" has a chance of being rounded to 1.

RESTRICTION: The conversions marked with (*) above involve steps performed by the C compiler. In particular, bugs/features of the compiler used may lead to breakage of some of the above rules.

Flavors of Perl numeric operations

Perl operations which take a numeric argument treat that argument in one of four different ways: they may force it to one of the integer/floating/ string formats, or they may behave differently depending on the format of the operand. Forcing a numeric value to a particular format does not change the number stored in the value.

All the operators which need an argument in the integer format treat the argument as in modular arithmetic, e.g., mod 2**32 on a 32-bit architecture. sprintf "%u", -1 therefore provides the same result as sprintf "%u", ~0.

Arithmetic operators

The binary operators + - * / % == != > < >= <= and the unary operators - abs and -- will attempt to convert arguments to integers. If both conversions are possible without loss of precision, and the operation can be performed without loss of precision then the integer result is used. Otherwise arguments are converted to floating point format and the floating point result is used. The caching of conversions (as described above) means that the integer conversion does not throw away fractional parts on floating point numbers.

++

++ behaves as the other operators above, except that if it is a string matching the format /^[a-zA-Z]*[0-9]*\z/ the string increment described in the perlop manpage is used.

Arithmetic operators during use integer

In scopes where use integer; is in force, nearly all the operators listed above will force their argument(s) into integer format, and return an integer result. The exceptions, abs, ++ and --, do not change their behavior with use integer;

Other mathematical operators

Operators such as **, sin and exp force arguments to floating point format.

Bitwise operators

Arguments are forced into the integer format if not strings.

Bitwise operators during use integer

forces arguments to integer format. Also shift operations internally use signed integers rather than the default unsigned.

Operators which expect an integer

force the argument into the integer format. This is applicable to the third and fourth arguments of sysread, for example.

Operators which expect a string

force the argument into the string format. For example, this is applicable to printf "%s", $value.

Though forcing an argument into a particular form does not change the stored number, Perl remembers the result of such conversions. In particular, though the first such conversion may be time-consuming, repeated operations will not need to redo the conversion.

AUTHOR

Ilya Zakharevich ilya@math.ohio-state.edu

Editorial adjustments by Gurusamy Sarathy <gsar@ActiveState.com>

Updates for 5.8.0 by Nicholas Clark <nick@ccl4.org>

SEE ALSO

the overload manpage, the perlop manpage


perldebtut - Perl debugging tutorial

  • use strict
  • Looking at data and -w and v
  • help
  • Stepping through code
  • Placeholder for a, w, t, T
  • REGULAR EXPRESSIONS
  • OUTPUT TIPS
  • CGI
  • GUIs
  • SUMMARY
  • SEE ALSO
  • AUTHOR
  • CONTRIBUTORS

NAME

perldebtut - Perl debugging tutorial

DESCRIPTION

A (very) lightweight introduction in the use of the perl debugger, and a pointer to existing, deeper sources of information on the subject of debugging perl programs.

There's an extraordinary number of people out there who don't appear to know anything about using the perl debugger, though they use the language every day. This is for them.

use strict

First of all, there's a few things you can do to make your life a lot more straightforward when it comes to debugging perl programs, without using the debugger at all. To demonstrate, here's a simple script, named "hello", with a problem:

        #!/usr/bin/perl

        $var1 = 'Hello World'; # always wanted to do that :-)
        $var2 = "$varl\n";

        print $var2;
        exit;

While this compiles and runs happily, it probably won't do what's expected, namely it doesn't print "Hello World\n" at all; It will on the other hand do exactly what it was told to do, computers being a bit that way inclined. That is, it will print out a newline character, and you'll get what looks like a blank line. It looks like there's 2 variables when (because of the typo) there's really 3:

        $var1 = 'Hello World';
        $varl = undef;
        $var2 = "\n";

To catch this kind of problem, we can force each variable to be declared before use by pulling in the strict module, by putting 'use strict;' after the first line of the script.

Now when you run it, perl complains about the 3 undeclared variables and we get four error messages because one variable is referenced twice:

 Global symbol "$var1" requires explicit package name at ./t1 line 4.
 Global symbol "$var2" requires explicit package name at ./t1 line 5.
 Global symbol "$varl" requires explicit package name at ./t1 line 5.
 Global symbol "$var2" requires explicit package name at ./t1 line 7.
 Execution of ./hello aborted due to compilation errors.

Luvverly! and to fix this we declare all variables explicitly and now our script looks like this:

        #!/usr/bin/perl
        use strict;

        my $var1 = 'Hello World';
        my $varl = undef;
        my $var2 = "$varl\n";

        print $var2;
        exit;

We then do (always a good idea) a syntax check before we try to run it again:

        > perl -c hello
        hello syntax OK

And now when we run it, we get "\n" still, but at least we know why. Just getting this script to compile has exposed the '$varl' (with the letter 'l') variable, and simply changing $varl to $var1 solves the problem.

Looking at data and -w and v

Ok, but how about when you want to really see your data, what's in that dynamic variable, just before using it?

        #!/usr/bin/perl
        use strict;

        my $key = 'welcome';
        my %data = (
                'this' => qw(that),
                'tom' => qw(and jerry),
                'welcome' => q(Hello World),
                'zip' => q(welcome),
        );
        my @data = keys %data;

        print "$data{$key}\n";
        exit;

Looks OK, after it's been through the syntax check (perl -c scriptname), we run it and all we get is a blank line again! Hmmmm.

One common debugging approach here, would be to liberally sprinkle a few print statements, to add a check just before we print out our data, and another just after:

        print "All OK\n" if grep($key, keys %data);
        print "$data{$key}\n";
        print "done: '$data{$key}'\n";

And try again:

        > perl data
        All OK
        done: ''

After much staring at the same piece of code and not seeing the wood for the trees for some time, we get a cup of coffee and try another approach. That is, we bring in the cavalry by giving perl the '-d' switch on the command line:

        > perl -d data
        Default die handler restored.
        Loading DB routines from perl5db.pl version 1.07
        Editor support available.
        Enter h or `h h' for help, or `man perldebug' for more help.
        main::(./data:4):     my $key = 'welcome';

Now, what we've done here is to launch the built-in perl debugger on our script. It's stopped at the first line of executable code and is waiting for input.

Before we go any further, you'll want to know how to quit the debugger: use just the letter 'q', not the words 'quit' or 'exit':

        DB<1> q
        >

That's it, you're back on home turf again.

help

Fire the debugger up again on your script and we'll look at the help menu. There's a couple of ways of calling help: a simple 'h' will get the summary help list, '|h' (pipe-h) will pipe the help through your pager (which is (probably 'more' or 'less'), and finally, 'h h' (h-space-h) will give you the entire help screen. Here is the summary page:

D1h

 List/search source lines:               Control script execution:
  l [ln|sub]  List source code            T           Stack trace
  - or .      List previous/current line  s [expr]    Single step [in expr]
  v [line]    View around line            n [expr]    Next, steps over subs
  f filename  View source in file         <CR/Enter>  Repeat last n or s
  /pattern/ ?patt?   Search forw/backw    r           Return from subroutine
  M           Show module versions        c [ln|sub]  Continue until position
 Debugger controls:                       L           List break/watch/actions
  o [...]     Set debugger options        t [expr]    Toggle trace [trace expr]
  <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
  ! [N|pat]   Redo a previous command     B ln|*      Delete a/all breakpoints
  H [-num]    Display last num commands   a [ln] cmd  Do cmd before line
  = [a val]   Define/list an alias        A ln|*      Delete a/all actions
  h [db_cmd]  Get help on command         w expr      Add a watch expression
  h h         Complete help page          W expr|*    Delete a/all watch exprs
  |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a subprocess
  q or ^D     Quit                        R           Attempt a restart
 Data Examination:     expr     Execute perl code, also see: s,n,t expr
  x|m expr       Evals expr in list context, dumps the result or lists methods.
  p expr         Print expression (uses script's current package).
  S [[!]pat]     List subroutine names [not] matching pattern
  V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or !pattern.
  X [Vars]       Same as "V current_package [Vars]".
  y [n [Vars]]   List lexicals in higher scope <n>.  Vars same as V.
 For more help, type h cmd_letter, or run man perldebug for all docs.

More confusing options than you can shake a big stick at! It's not as bad as it looks and it's very useful to know more about all of it, and fun too!

There's a couple of useful ones to know about straight away. You wouldn't think we're using any libraries at all at the moment, but 'M' will show which modules are currently loaded, and their version number, while 'm' will show the methods, and 'S' shows all subroutines (by pattern) as shown below. 'V' and 'X' show variables in the program by package scope and can be constrained by pattern.

        DB<2>S str
        dumpvar::stringify
        strict::bits
        strict::import
        strict::unimport

Using 'X' and cousins requires you not to use the type identifiers ($@%), just the 'name':

        DM<3>X ~err
        FileHandle(stderr) => fileno(2)

Remember we're in our tiny program with a problem, we should have a look at where we are, and what our data looks like. First of all let's view some code at our present position (the first line of code in this case), via 'v':

        DB<4> v
        1       #!/usr/bin/perl
        2:      use strict;
        3
        4==>    my $key = 'welcome';
        5:      my %data = (
        6               'this' => qw(that),
        7               'tom' => qw(and jerry),
        8               'welcome' => q(Hello World),
        9               'zip' => q(welcome),
        10      );

At line number 4 is a helpful pointer, that tells you where you are now. To see more code, type 'v' again:

        DB<4> v
        8               'welcome' => q(Hello World),
        9               'zip' => q(welcome),
        10      );
        11:     my @data = keys %data;
        12:     print "All OK\n" if grep($key, keys %data);
        13:     print "$data{$key}\n";
        14:     print "done: '$data{$key}'\n";
        15:     exit;

And if you wanted to list line 5 again, type 'l 5', (note the space):

        DB<4> l 5
        5:      my %data = (

In this case, there's not much to see, but of course normally there's pages of stuff to wade through, and 'l' can be very useful. To reset your view to the line we're about to execute, type a lone period '.':

        DB<5> .
        main::(./data_a:4):     my $key = 'welcome';

The line shown is the one that is about to be executed next, it hasn't happened yet. So while we can print a variable with the letter 'p', at this point all we'd get is an empty (undefined) value back. What we need to do is to step through the next executable statement with an 's':

        DB<6> s
        main::(./data_a:5):     my %data = (
        main::(./data_a:6):             'this' => qw(that),
        main::(./data_a:7):             'tom' => qw(and jerry),
        main::(./data_a:8):             'welcome' => q(Hello World),
        main::(./data_a:9):             'zip' => q(welcome),
        main::(./data_a:10):    );

Now we can have a look at that first ($key) variable:

        DB<7> p $key
        welcome

line 13 is where the action is, so let's continue down to there via the letter 'c', which by the way, inserts a 'one-time-only' breakpoint at the given line or sub routine:

        DB<8> c 13
        All OK
        main::(./data_a:13):    print "$data{$key}\n";

We've gone past our check (where 'All OK' was printed) and have stopped just before the meat of our task. We could try to print out a couple of variables to see what is happening:

        DB<9> p $data{$key}

Not much in there, lets have a look at our hash:

        DB<10> p %data
        Hello Worldziptomandwelcomejerrywelcomethisthat
        DB<11> p keys %data
        Hello Worldtomwelcomejerrythis

Well, this isn't very easy to read, and using the helpful manual (h h), the 'x' command looks promising:

        DB<12> x %data
        0  'Hello World'
        1  'zip'
        2  'tom'
        3  'and'
        4  'welcome'
        5  undef
        6  'jerry'
        7  'welcome'
        8  'this'
        9  'that'

That's not much help, a couple of welcomes in there, but no indication of which are keys, and which are values, it's just a listed array dump and, in this case, not particularly helpful. The trick here, is to use a reference to the data structure:

        DB<13> x \%data
        0  HASH(0x8194bc4)
           'Hello World' => 'zip'
           'jerry' => 'welcome'
           'this' => 'that'
           'tom' => 'and'
           'welcome' => undef

The reference is truly dumped and we can finally see what we're dealing with. Our quoting was perfectly valid but wrong for our purposes, with 'and jerry' being treated as 2 separate words rather than a phrase, thus throwing the evenly paired hash structure out of alignment.

The '-w' switch would have told us about this, had we used it at the start, and saved us a lot of trouble:

        > perl -w data
        Odd number of elements in hash assignment at ./data line 5.

We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get our expected output:

        > perl -w data
        Hello World

While we're here, take a closer look at the 'x' command, it's really useful and will merrily dump out nested references, complete objects, partial objects - just about whatever you throw at it:

Let's make a quick object and x-plode it, first we'll start the debugger: it wants some form of input from STDIN, so we give it something non-committal, a zero:

        > perl -de 0
        Default die handler restored.
        Loading DB routines from perl5db.pl version 1.07
        Editor support available.
        Enter h or `h h' for help, or `man perldebug' for more help.
        main::(-e:1):   0

Now build an on-the-fly object over a couple of lines (note the backslash):

        DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
        cont:   {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')

And let's have a look at it:

        DB<2> x $obj
        0  MY_class=HASH(0x828ad98)
                'attr' => HASH(0x828ad68)
        'col' => 'black'
        'things' => ARRAY(0x828abb8)
                0  'this'
                1  'that'
                2  'etc'
                'unique_id' => 123
        DB<3>

Useful, huh? You can eval nearly anything in there, and experiment with bits of code or regexes until the cows come home:

        DB<3> @data = qw(this that the other atheism leather theory scythe)
        DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
        atheism
        leather
        other
        scythe
        the
        theory
        saw -> 6

If you want to see the command History, type an 'H':

        DB<5> H
        4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
        3: @data = qw(this that the other atheism leather theory scythe)
        2: x $obj
        1: $obj = bless({'unique_id'=>'123', 'attr'=>
        {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
        DB<5>

And if you want to repeat any previous command, use the exclamation: '!':

        DB<5> !4
        p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
        atheism
        leather
        other
        scythe
        the
        theory
        saw -> 12

For more on references see the perlref manpage and the perlreftut manpage

Stepping through code

Here's a simple program which converts between Celsius and Fahrenheit, it too has a problem:

        #!/usr/bin/perl -w
        use strict;

        my $arg = $ARGV[0] || '-c20';

        if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
                my ($deg, $num) = ($1, $2);
                my ($in, $out) = ($num, $num);
                if ($deg eq 'c') {
                        $deg = 'f';
                        $out = &c2f($num);
                } else {
                        $deg = 'c';
                        $out = &f2c($num);
                }
                $out = sprintf('%0.2f', $out);
                $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
                print "$out $deg\n";
        } else {
                print "Usage: $0 -[c|f] num\n";
        }
        exit;

        sub f2c {
                my $f = shift;
                my $c = 5 * $f - 32 / 9;
                return $c;
        }

        sub c2f {
                my $c = shift;
                my $f = 9 * $c / 5 + 32;
                return $f;
        }

For some reason, the Fahrenheit to Celsius conversion fails to return the expected output. This is what it does:

        > temp -c0.72
        33.30 f
        > temp -f33.3
        162.94 c

Not very consistent! We'll set a breakpoint in the code manually and run it under the debugger to see what's going on. A breakpoint is a flag, to which the debugger will run without interruption, when it reaches the breakpoint, it will stop execution and offer a prompt for further interaction. In normal use, these debugger commands are completely ignored, and they are safe - if a little messy, to leave in production code.

        my ($in, $out) = ($num, $num);
        $DB::single=2; # insert at line 9!
        if ($deg eq 'c')
                ...

        > perl -d temp -f33.3
        Default die handler restored.
        Loading DB routines from perl5db.pl version 1.07
        Editor support available.
        Enter h or `h h' for help, or `man perldebug' for more help.
        main::(temp:4): my $arg = $ARGV[0] || '-c100';

We'll simply continue down to our pre-set breakpoint with a 'c':

        DB<1> c
        main::(temp:10):                if ($deg eq 'c') {

Followed by a view command to see where we are:

        DB<1> v
        7:              my ($deg, $num) = ($1, $2);
        8:              my ($in, $out) = ($num, $num);
        9:              $DB::single=2;
        10==>           if ($deg eq 'c') {
        11:                     $deg = 'f';
        12:                     $out = &c2f($num);
        13              } else {
        14:                     $deg = 'c';
        15:                     $out = &f2c($num);
        16              }

And a print to show what values we're currently using:

        DB<1> p $deg, $num
        f33.3

We can put another break point on any line beginning with a colon, we'll use line 17 as that's just as we come out of the subroutine, and we'd like to pause there later on:

        DB<2> b 17

There's no feedback from this, but you can see what breakpoints are set by using the list 'L' command:

        DB<3> L
        temp:
                17:            print "$out $deg\n";
                break if (1)

Note that to delete a breakpoint you use 'd' or 'D'.

Now we'll continue down into our subroutine, this time rather than by line number, we'll use the subroutine name, followed by the now familiar 'v':

        DB<3> c f2c
        main::f2c(temp:30):             my $f = shift;

        DB<4> v
        24:     exit;
        25
        26      sub f2c {
        27==>           my $f = shift;
        28:             my $c = 5 * $f - 32 / 9;
        29:             return $c;
        30      }
        31
        32      sub c2f {
        33:             my $c = shift;

Note that if there was a subroutine call between us and line 29, and we wanted to single-step through it, we could use the 's' command, and to step over it we would use 'n' which would execute the sub, but not descend into it for inspection. In this case though, we simply continue down to line 29:

        DB<4> c 29
        main::f2c(temp:29):             return $c;

And have a look at the return value:

        DB<5> p $c
        162.944444444444

This is not the right answer at all, but the sum looks correct. I wonder if it's anything to do with operator precedence? We'll try a couple of other possibilities with our sum:

        DB<6> p (5 * $f - 32 / 9)
        162.944444444444
        DB<7> p 5 * $f - (32 / 9)
        162.944444444444
        DB<8> p (5 * $f) - 32 / 9
        162.944444444444
        DB<9> p 5 * ($f - 32) / 9
        0.722222222222221

:-) that's more like it! Ok, now we can set our return variable and we'll return out of the sub with an 'r':

        DB<10> $c = 5 * ($f - 32) / 9
        DB<11> r
        scalar context return from main::f2c: 0.722222222222221

Looks good, let's just continue off the end of the script:

        DB<12> c
        0.72 c
        Debugged program terminated.  Use q to quit or R to restart,
        use O inhibit_exit to avoid stopping after program termination,
        h q, h R or h O to get additional info.

A quick fix to the offending line (insert the missing parentheses) in the actual program and we're finished.

Placeholder for a, w, t, T

Actions, watch variables, stack traces etc.: on the TODO list.

        a
        w
        t
        T

REGULAR EXPRESSIONS

Ever wanted to know what a regex looked like? You'll need perl compiled with the DEBUGGING flag for this one:

        > perl -Dr -e '/^pe(a)*rl$/i'
        Compiling REx `^pe(a)*rl$'
        size 17 first at 2
        rarest char
         at 0
           1: BOL(2)
           2: EXACTF <pe>(4)
           4: CURLYN[1] {0,32767}(14)
           6:   NOTHING(8)
           8:   EXACTF <a>(0)
          12:   WHILEM(0)
          13: NOTHING(14)
          14: EXACTF <rl>(16)
          16: EOL(17)
          17: END(0)
        floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
        anchored(BOL) minlen 4
        Omitting $` $& $' support.

        EXECUTING...
        Freeing REx: `^pe(a)*rl$'

Did you really want to know? :-) For more gory details on getting regular expressions to work, have a look at the perlre manpage, the perlretut manpage, and to decode the mysterious labels (BOL and CURLYN, etc. above), see the perldebguts manpage.

OUTPUT TIPS

To get all the output from your error log, and not miss any messages via helpful operating system buffering, insert a line like this, at the start of your script:

        $|=1;

To watch the tail of a dynamically growing logfile, (from the command line):

        tail -f $error_log

Wrapping all die calls in a handler routine can be useful to see how, and from where, they're being called, the perlvar manpage has more information:

        BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }

Various useful techniques for the redirection of STDOUT and STDERR filehandles are explained in the perlopentut manpage and the perlfaq8 manpage.

CGI

Just a quick hint here for all those CGI programmers who can't figure out how on earth to get past that 'waiting for input' prompt, when running their CGI script from the command-line, try something like this:

        > perl -d my_cgi.pl -nodebug

Of course the CGI manpage and the perlfaq9 manpage will tell you more.

GUIs

The command line interface is tightly integrated with an emacs extension and there's a vi interface too.

You don't have to do this all on the command line, though, there are a few GUI options out there. The nice thing about these is you can wave a mouse over a variable and a dump of its data will appear in an appropriate window, or in a popup balloon, no more tiresome typing of 'x $varname' :-)

In particular have a hunt around for the following:

ptkdb perlTK based wrapper for the built-in debugger

ddd data display debugger

PerlDevKit and PerlBuilder are NT specific

NB. (more info on these and others would be appreciated).

SUMMARY

We've seen how to encourage good coding practices with use strict and -w. We can run the perl debugger perl -d scriptname to inspect your data from within the perl debugger with the p and x commands. You can walk through your code, set breakpoints with b and step through that code with s or n, continue with c and return from a sub with r. Fairly intuitive stuff when you get down to it.

There is of course lots more to find out about, this has just scratched the surface. The best way to learn more is to use perldoc to find out more about the language, to read the on-line help (the perldebug manpage is probably the next place to go), and of course, experiment.

SEE ALSO

the perldebug manpage, the perldebguts manpage, the perldiag manpage, dprofpp, the perlrun manpage

AUTHOR

Richard Foley <richard@rfi.net> Copyright (c) 2000

CONTRIBUTORS

Various people have made helpful suggestions and contributions, in particular:

Ronald J Kimball <rjk@linguist.dartmouth.edu>

Hugo van der Sanden <hv@crypt0.demon.co.uk>

Peter Scott <Peter@PSDT.com>


perldebug - Perl debugging

  • The Perl Debugger
    • Debugger Commands
    • Configurable Options
    • Debugger input/output
    • Debugging compile-time statements
    • Debugger Customization
    • Readline Support
    • Editor Support for Debugging
    • The Perl Profiler
  • Debugging regular expressions
  • Debugging memory usage
  • SEE ALSO
  • BUGS

NAME

perldebug - Perl debugging

DESCRIPTION

First of all, have you tried using the -w switch?

If you're new to the Perl debugger, you may prefer to read the perldebtut manpage, which is a tutorial introduction to the debugger .

The Perl Debugger

If you invoke Perl with the -d switch, your script runs under the Perl source debugger. This works like an interactive Perl environment, prompting for debugger commands that let you examine source code, set breakpoints, get stack backtraces, change the values of variables, etc. This is so convenient that you often fire up the debugger all by itself just to test out Perl constructs interactively to see what they do. For example:

    $ perl -d -e 42

In Perl, the debugger is not a separate program the way it usually is in the typical compiled environment. Instead, the -d flag tells the compiler to insert source information into the parse trees it's about to hand off to the interpreter. That means your code must first compile correctly for the debugger to work on it. Then when the interpreter starts up, it preloads a special Perl library file containing the debugger.

The program will halt right before the first run-time executable statement (but see below regarding compile-time statements) and ask you to enter a debugger command. Contrary to popular expectations, whenever the debugger halts and shows you a line of code, it always displays the line it's about to execute, rather than the one it has just executed.

Any command not recognized by the debugger is directly executed (eval'd) as Perl code in the current package. (The debugger uses the DB package for keeping its own state information.)

Note that the said eval is bound by an implicit scope. As a result any newly introduced lexical variable or any modified capture buffer content is lost after the eval. The debugger is a nice environment to learn Perl, but if you interactively experiment using material which should be in the same scope, stuff it in one line.

For any text entered at the debugger prompt, leading and trailing whitespace is first stripped before further processing. If a debugger command coincides with some function in your own program, merely precede the function with something that doesn't look like a debugger command, such as a leading ; or perhaps a +, or by wrapping it with parentheses or braces.

Debugger Commands

The debugger understands the following commands:

h

Prints out a summary help message

h [command]

Prints out a help message for the given debugger command.

h h

The special argument of h h produces the entire help page, which is quite long.

If the output of the h h command (or any command, for that matter) scrolls past your screen, precede the command with a leading pipe symbol so that it's run through your pager, as in

    DB> |h h

You may change the pager which is used via o pager=... command.

p expr

Same as print {$DB::OUT} expr in the current package. In particular, because this is just Perl's own print function, this means that nested data structures and objects are not dumped, unlike with the x command.

The DB::OUT filehandle is opened to /dev/tty, regardless of where STDOUT may be redirected to.

x [maxdepth] expr

Evaluates its expression in list context and dumps out the result in a pretty-printed fashion. Nested data structures are printed out recursively, unlike the real print function in Perl. When dumping hashes, you'll probably prefer 'x \%h' rather than 'x %h'. See the Dumpvalue manpage if you'd like to do this yourself.

The output format is governed by multiple options described under Configurable Options.

If the maxdepth is included, it must be a numeral N; the value is dumped only N levels deep, as if the dumpDepth option had been temporarily set to N.

V [pkg [vars]]

Display all (or some) variables in package (defaulting to main) using a data pretty-printer (hashes show their keys and values so you see what's what, control characters are made printable, etc.). Make sure you don't put the type specifier (like $) there, just the symbol names, like this:

    V DB filename line

Use ~pattern and !pattern for positive and negative regexes.

This is similar to calling the x command on each applicable var.

X [vars]

Same as V currentpackage [vars].

y [level [vars]]

Display all (or some) lexical variables (mnemonic: mY variables) in the current scope or level scopes higher. You can limit the variables that you see with vars which works exactly as it does for the V and X commands. Requires the PadWalker module version 0.08 or higher; will warn if this isn't installed. Output is pretty-printed in the same style as for V and the format is controlled by the same options.

T

Produce a stack backtrace. See below for details on its output.

s [expr]

Single step. Executes until the beginning of another statement, descending into subroutine calls. If an expression is supplied that includes function calls, it too will be single-stepped.

n [expr]

Next. Executes over subroutine calls, until the beginning of the next statement. If an expression is supplied that includes function calls, those functions will be executed with stops before each statement.

r

Continue until the return from the current subroutine. Dump the return value if the PrintRet option is set (default).

<CR>

Repeat last n or s command.

c [line|sub]

Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine.

l

List next window of lines.

l min+incr

List incr+1 lines starting at min.

l min-max

List lines min through max. l - is synonymous to -.

l line

List a single line.

l subname

List first window of lines from subroutine. subname may be a variable that contains a code reference.

-

List previous window of lines.

v [line]

View a few lines of code around the current line.

.

Return the internal debugger pointer to the line last executed, and print out that line.

f filename

Switch to viewing a different file or eval statement. If filename is not a full pathname found in the values of %INC, it is considered a regex.

evaled strings (when accessible) are considered to be filenames: f (eval 7) and f eval 7\b access the body of the 7th evaled string (in the order of execution). The bodies of the currently executed eval and of evaled strings that define subroutines are saved and thus accessible.

/pattern/

Search forwards for pattern (a Perl regex); final / is optional. The search is case-insensitive by default.

?pattern?

Search backwards for pattern; final ? is optional. The search is case-insensitive by default.

L [abw]

List (default all) actions, breakpoints and watch expressions

S [[!]regex]

List subroutine names [not] matching the regex.

t

Toggle trace mode (see also the AutoTrace option).

t expr

Trace through execution of expr. See Frame Listing Output Examples in the perldebguts manpage for examples.

b

Sets breakpoint on current line

b [line] [condition]

Set a breakpoint before the given line. If a condition is specified, it's evaluated each time the statement is reached: a breakpoint is taken only if the condition is true. Breakpoints may only be set on lines that begin an executable statement. Conditions don't use if:

    b 237 $x > 30
    b 237 ++$count237 < 11
    b 33 /pattern/i
b subname [condition]

Set a breakpoint before the first line of the named subroutine. subname may be a variable containing a code reference (in this case condition is not supported).

b postpone subname [condition]

Set a breakpoint at first line of subroutine after it is compiled.

b load filename

Set a breakpoint before the first executed line of the filename, which should be a full pathname found amongst the %INC values.

b compile subname

Sets a breakpoint before the first statement executed after the specified subroutine is compiled.

B line

Delete a breakpoint from the specified line.

B *

Delete all installed breakpoints.

a [line] command

Set an action to be done before the line is executed. If line is omitted, set an action on the line about to be executed. The sequence of steps taken by the debugger is

  1. check for a breakpoint at this line
  2. print the line if necessary (tracing)
  3. do any actions associated with that line
  4. prompt user if at a breakpoint or in single-step
  5. evaluate line

For example, this will print out $foo every time line 53 is passed:

    a 53 print "DB FOUND $foo\n"
A line

Delete an action from the specified line.

A *

Delete all installed actions.

w expr

Add a global watch-expression. We hope you know what one of these is, because they're supposed to be obvious.

W expr

Delete watch-expression

W *

Delete all watch-expressions.

o

Display all options

o booloption ...

Set each listed Boolean option to the value 1.

o anyoption? ...

Print out the value of one or more options.

o option=value ...

Set the value of one or more options. If the value has internal whitespace, it should be quoted. For example, you could set o pager="less -MQeicsNfr" to call less with those specific options. You may use either single or double quotes, but if you do, you must escape any embedded instances of same sort of quote you began with, as well as any escaping any escapes that immediately precede that quote but which are not meant to escape the quote itself. In other words, you follow single-quoting rules irrespective of the quote; eg: o option='this isn\'t bad' or o option="She said, \"Isn't it?\"".

For historical reasons, the =value is optional, but defaults to 1 only where it is safe to do so--that is, mostly for Boolean options. It is always better to assign a specific value using =. The option can be abbreviated, but for clarity probably should not be. Several options can be set together. See Configurable Options for a list of these.

< ? >

List out all pre-prompt Perl command actions.

< [ command ] >

Set an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines.

< * >

Delete all pre-prompt Perl command actions.

<< command >

Add an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backwhacking the newlines.

> ? >>

List out post-prompt Perl command actions.

> command >>

Set an action (Perl command) to happen after the prompt when you've just given a command to return to executing the script. A multi-line command may be entered by backslashing the newlines (we bet you couldn't've guessed this by now).

> * >>

Delete all post-prompt Perl command actions.

>> command > >>>

Adds an action (Perl command) to happen after the prompt when you've just given a command to return to executing the script. A multi-line command may be entered by backslashing the newlines.

{ ?

List out pre-prompt debugger commands.

{ [ command ]

Set an action (debugger command) to happen before every debugger prompt. A multi-line command may be entered in the customary fashion.

Because this command is in some senses new, a warning is issued if you appear to have accidentally entered a block instead. If that's what you mean to do, write it as with ;{ ... } or even do { ... }.

{ *

Delete all pre-prompt debugger commands.

{{ command

Add an action (debugger command) to happen before every debugger prompt. A multi-line command may be entered, if you can guess how: see above.

! number

Redo a previous command (defaults to the previous command).

! -number

Redo number'th previous command.

! pattern

Redo last command that started with pattern. See o recallCommand, too.

!! cmd

Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See o shellBang, also. Note that the user's current shell (well, their $ENV{SHELL} variable) will be used, which can interfere with proper interpretation of exit status or signal and coredump information.

source file

Read and execute debugger commands from file. file may itself contain source commands.

H -number

Display last n commands. Only commands longer than one character are listed. If number is omitted, list them all.

q or ^D

Quit. ("quit" doesn't work for this, unless you've made an alias) This is the only supported way to exit the debugger, though typing exit twice might work.

Set the inhibit_exit option to 0 if you want to be able to step off the end the script. You may also need to set $finished to 0 if you want to step through global destruction.

R

Restart the debugger by exec()ing a new session. We try to maintain your history across this, but internal settings and command-line options may be lost.

The following setting are currently preserved: history, breakpoints, actions, debugger options, and the Perl command-line options -w, -I, and -e.

|dbcmd

Run the debugger command, piping DB::OUT into your current pager.

||dbcmd

Same as |dbcmd but DB::OUT is temporarily selected as well.

= [alias value]

Define a command alias, like

    = quit q

or list current aliases.

command

Execute command as a Perl statement. A trailing semicolon will be supplied. If the Perl statement would otherwise be confused for a Perl debugger, use a leading semicolon, too.

m expr

List which methods may be called on the result of the evaluated expression. The expression may evaluated to a reference to a blessed object, or to a package name.

M

Displays all loaded modules and their versions

man [manpage]

Despite its name, this calls your system's default documentation viewer on the given page, or on the viewer itself if manpage is omitted. If that viewer is man, the current Config information is used to invoke man using the proper MANPATH or -M manpath option. Failed lookups of the form XXX that match known manpages of the form perlXXX will be retried. This lets you type man debug or man op from the debugger.

On systems traditionally bereft of a usable man command, the debugger invokes perldoc. Occasionally this determination is incorrect due to recalcitrant vendors or rather more felicitously, to enterprising users. If you fall into either category, just manually set the $DB::doccmd variable to whatever viewer to view the Perl documentation on your system. This may be set in an rc file, or through direct assignment. We're still waiting for a working example of something along the lines of:

    $DB::doccmd = 'netscape -remote http://something.here/';

Configurable Options

The debugger has numerous options settable using the o command, either interactively or from the environment or an rc file. (./.perldb or ~/.perldb under Unix.)

recallCommand, ShellBang

The characters used to recall command or spawn shell. By default, both are set to !, which is unfortunate.

pager

Program to use for output of pager-piped commands (those beginning with a | character.) By default, $ENV{PAGER} will be used. Because the debugger uses your current terminal characteristics for bold and underlining, if the chosen pager does not pass escape sequences through unchanged, the output of some debugger commands will not be readable when sent through the pager.

tkRunning

Run Tk while prompting (with ReadLine).

signalLevel, warnLevel, dieLevel

Level of verbosity. By default, the debugger leaves your exceptions and warnings alone, because altering them can break correctly running programs. It will attempt to print a message when uncaught INT, BUS, or SEGV signals arrive. (But see the mention of signals in BUGS below.)

To disable this default safe mode, set these values to something higher than 0. At a level of 1, you get backtraces upon receiving any kind of warning (this is often annoying) or exception (this is often valuable). Unfortunately, the debugger cannot discern fatal exceptions from non-fatal ones. If dieLevel is even 1, then your non-fatal exceptions are also traced and unceremoniously altered if they came from eval'd strings or from any kind of eval within modules you're attempting to load. If dieLevel is 2, the debugger doesn't care where they came from: It usurps your exception handler and prints out a trace, then modifies all exceptions with its own embellishments. This may perhaps be useful for some tracing purposes, but tends to hopelessly destroy any program that takes its exception handling seriously.

AutoTrace

Trace mode (similar to t command, but can be put into PERLDB_OPTS).

LineInfo

File or pipe to print line number info to. If it is a pipe (say, |visual_perl_db), then a short message is used. This is the mechanism used to interact with a slave editor or visual debugger, such as the special vi or emacs hooks, or the ddd graphical debugger.

inhibit_exit

If 0, allows stepping off the end of the script.

PrintRet

Print return value after r command if set (default).

ornaments

Affects screen appearance of the command line (see the Term::ReadLine manpage). There is currently no way to disable these, which can render some output illegible on some displays, or with some pagers. This is considered a bug.

frame

Affects the printing of messages upon entry and exit from subroutines. If frame & 2 is false, messages are printed on entry only. (Printing on exit might be useful if interspersed with other messages.)

If frame & 4, arguments to functions are printed, plus context and caller info. If frame & 8, overloaded stringify and tied FETCH is enabled on the printed arguments. If frame & 16, the return value from the subroutine is printed.

The length at which the argument list is truncated is governed by the next option:

maxTraceLen

Length to truncate the argument list when the frame option's bit 4 is set.

windowSize

Change the size of code list window (default is 10 lines).

The following options affect what happens with V, X, and x commands:

arrayDepth, hashDepth

Print only first N elements ('' for all).

dumpDepth

Limit recursion depth to N levels when dumping structures. Negative values are interpreted as infinity. Default: infinity.

compactDump, veryCompact

Change the style of array and hash output. If compactDump, short array may be printed on one line.

globPrint

Whether to print contents of globs.

DumpDBFiles

Dump arrays holding debugged files.

DumpPackages

Dump symbol tables of packages.

DumpReused

Dump contents of "reused" addresses.

quote, HighBit, undefPrint

Change the style of string dump. The default value for quote is auto; one can enable double-quotish or single-quotish format by setting it to " or ', respectively. By default, characters with their high bit set are printed verbatim.

UsageOnly

Rudimentary per-package memory usage dump. Calculates total size of strings found in variables in the package. This does not include lexicals in a module's file scope, or lost in closures.

After the rc file is read, the debugger reads the $ENV{PERLDB_OPTS} environment variable and parses this as the remainder of a "O ..." line as one might enter at the debugger prompt. You may place the initialization options TTY, noTTY, ReadLine, and NonStop there.

If your rc file contains:

  parse_options("NonStop=1 LineInfo=db.out AutoTrace");

then your script will run without human intervention, putting trace information into the file db.out. (If you interrupt it, you'd better reset LineInfo to /dev/tty if you expect to see anything.)

TTY

The TTY to use for debugging I/O.

noTTY

If set, the debugger goes into NonStop mode and will not connect to a TTY. If interrupted (or if control goes to the debugger via explicit setting of $DB::signal or $DB::single from the Perl script), it connects to a TTY specified in the TTY option at startup, or to a tty found at runtime using the Term::Rendezvous module of your choice.

This module should implement a method named new that returns an object with two methods: IN and OUT. These should return filehandles to use for debugging input and output correspondingly. The new method should inspect an argument containing the value of $ENV{PERLDB_NOTTY} at startup, or "$ENV{HOME}/.perldbtty$$" otherwise. This file is not inspected for proper ownership, so security hazards are theoretically possible.

ReadLine

If false, readline support in the debugger is disabled in order to debug applications that themselves use ReadLine.

NonStop

If set, the debugger goes into non-interactive mode until interrupted, or programmatically by setting $DB::signal or $DB::single.

Here's an example of using the $ENV{PERLDB_OPTS} variable:

    $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram

That will run the script myprogram without human intervention, printing out the call tree with entry and exit points. Note that NonStop=1 frame=2 is equivalent to N f=2, and that originally, options could be uniquely abbreviated by the first letter (modulo the Dump* options). It is nevertheless recommended that you always spell them out in full for legibility and future compatibility.

Other examples include

    $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram

which runs script non-interactively, printing info on each entry into a subroutine and each executed line into the file named listing. (If you interrupt it, you would better reset LineInfo to something "interactive"!)

Other examples include (using standard shell syntax to show environment variable settings):

  $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
      perl -d myprogram )

which may be useful for debugging a program that uses Term::ReadLine itself. Do not forget to detach your shell from the TTY in the window that corresponds to /dev/ttyXX, say, by issuing a command like

  $ sleep 1000000

See Debugger Internals in the perldebguts manpage for details.

Debugger input/output

Prompt

The debugger prompt is something like

    DB<8>

or even

    DB<<17>>

where that number is the command number, and which you'd use to access with the built-in csh-like history mechanism. For example, !17 would repeat command number 17. The depth of the angle brackets indicates the nesting depth of the debugger. You could get more than one set of brackets, for example, if you'd already at a breakpoint and then printed the result of a function call that itself has a breakpoint, or you step into an expression via s/n/t expression command.

Multiline commands

If you want to enter a multi-line command, such as a subroutine definition with several statements or a format, escape the newline that would normally end the debugger command with a backslash. Here's an example:

      DB<1> for (1..4) {         \
      cont:     print "ok\n";   \
      cont: }
      ok
      ok
      ok
      ok

Note that this business of escaping a newline is specific to interactive commands typed into the debugger.

Stack backtrace

Here's an example of what a stack backtrace via T command might look like:

    $ = main::infested called from file `Ambulation.pm' line 10
    @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
    $ = main::pests('bactrian', 4) called from file `camel_flea' line 4

The left-hand character up there indicates the context in which the function was called, with $ and @ meaning scalar or list contexts respectively, and . meaning void context (which is actually a sort of scalar context). The display above says that you were in the function main::infested when you ran the stack dump, and that it was called in scalar context from line 10 of the file Ambulation.pm, but without any arguments at all, meaning it was called as &infested. The next stack frame shows that the function Ambulation::legs was called in list context from the camel_flea file with four arguments. The last stack frame shows that main::pests was called in scalar context, also from camel_flea, but from line 4.

If you execute the T command from inside an active use statement, the backtrace will contain both a require frame and an eval) frame.

Line Listing Format

This shows the sorts of output the l command can produce:

    DB<<13>> l
      101:                @i{@i} = ();
      102:b               @isa{@i,$pack} = ()
      103                     if(exists $i{$prevpack} || exists $isa{$pack});
      104             }
      105
      106             next
      107==>              if(exists $isa{$pack});
      108
      109:a           if ($extra-- > 0) {
      110:                %isa = ($pack,1);

Breakable lines are marked with :. Lines with breakpoints are marked by b and those with actions by a. The line that's about to be executed is marked by ==>.

Please be aware that code in debugger listings may not look the same as your original source code. Line directives and external source filters can alter the code before Perl sees it, causing code to move from its original positions or take on entirely different forms.

Frame listing

When the frame option is set, the debugger would print entered (and optionally exited) subroutines in different styles. See the perldebguts manpage for incredibly long examples of these.

Debugging compile-time statements

If you have compile-time executable statements (such as code within BEGIN and CHECK blocks or use statements), these will not be stopped by debugger, although requires and INIT blocks will, and compile-time statements can be traced with AutoTrace option set in PERLDB_OPTS). From your own Perl code, however, you can transfer control back to the debugger using the following statement, which is harmless if the debugger is not running:

    $DB::single = 1;

If you set $DB::single to 2, it's equivalent to having just typed the n command, whereas a value of 1 means the s command. The $DB::trace variable should be set to 1 to simulate having typed the t command.

Another way to debug compile-time code is to start the debugger, set a breakpoint on the load of some module:

    DB<7> b load f:/perllib/lib/Carp.pm
  Will stop on load of `f:/perllib/lib/Carp.pm'.

and then restart the debugger using the R command (if possible). One can use b compile subname for the same purpose.

Debugger Customization

The debugger probably contains enough configuration hooks that you won't ever have to modify it yourself. You may change the behaviour of debugger from within the debugger using its o command, from the command line via the PERLDB_OPTS environment variable, and from customization files.

You can do some customization by setting up a .perldb file, which contains initialization code. For instance, you could make aliases like these (the last one is one people expect to be there):

    $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
    $DB::alias{'stop'} = 's/^stop (at|in)/b/';
    $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
    $DB::alias{'quit'} = 's/^quit(\s*)/exit/';

You can change options from .perldb by using calls like this one;

    parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");

The code is executed in the package DB. Note that .perldb is processed before processing PERLDB_OPTS. If .perldb defines the subroutine afterinit, that function is called after debugger initialization ends. .perldb may be contained in the current directory, or in the home directory. Because this file is sourced in by Perl and may contain arbitrary commands, for security reasons, it must be owned by the superuser or the current user, and writable by no one but its owner.

You can mock TTY input to debugger by adding arbitrary commands to @DB::typeahead. For example, your .perldb file might contain:

    sub afterinit { push @DB::typeahead, "b 4", "b 6"; }

Which would attempt to set breakpoints on lines 4 and 6 immediately after debugger initialization. Note that @DB::typeahead is not a supported interface and is subject to change in future releases.

If you want to modify the debugger, copy perl5db.pl from the Perl library to another name and hack it to your heart's content. You'll then want to set your PERL5DB environment variable to say something like this:

    BEGIN { require "myperl5db.pl" }

As a last resort, you could also use PERL5DB to customize the debugger by directly setting internal variables or calling debugger functions.

Note that any variables and functions that are not documented in this document (or in the perldebguts manpage) are considered for internal use only, and as such are subject to change without notice.

Readline Support

As shipped, the only command-line history supplied is a simplistic one that checks for leading exclamation points. However, if you install the Term::ReadKey and Term::ReadLine modules from CPAN, you will have full editing capabilities much like GNU readline(3) provides. Look for these in the modules/by-module/Term directory on CPAN. These do not support normal vi command-line editing, however.

A rudimentary command-line completion is also available. Unfortunately, the names of lexical variables are not available for completion.

Editor Support for Debugging

If you have the FSF's version of emacs installed on your system, it can interact with the Perl debugger to provide an integrated software development environment reminiscent of its interactions with C debuggers.

Perl comes with a start file for making emacs act like a syntax-directed editor that understands (some of) Perl's syntax. Look in the emacs directory of the Perl source distribution.

A similar setup by Tom Christiansen for interacting with any vendor-shipped vi and the X11 window system is also available. This works similarly to the integrated multiwindow support that emacs provides, where the debugger drives the editor. At the time of this writing, however, that tool's eventual location in the Perl distribution was uncertain.

Users of vi should also look into vim and gvim, the mousey and windy version, for coloring of Perl keywords.

Note that only perl can truly parse Perl, so all such CASE tools fall somewhat short of the mark, especially if you don't program your Perl as a C programmer might.

The Perl Profiler

If you wish to supply an alternative debugger for Perl to run, just invoke your script with a colon and a package argument given to the -d flag. The most popular alternative debuggers for Perl is the Perl profiler. Devel::DProf is now included with the standard Perl distribution. To profile your Perl program in the file mycode.pl, just type:

    $ perl -d:DProf mycode.pl

When the script terminates the profiler will dump the profile information to a file called tmon.out. A tool like dprofpp, also supplied with the standard Perl distribution, can be used to interpret the information in that profile.

Debugging regular expressions

use re 'debug' enables you to see the gory details of how the Perl regular expression engine works. In order to understand this typically voluminous output, one must not only have some idea about how regular expression matching works in general, but also know how Perl's regular expressions are internally compiled into an automaton. These matters are explored in some detail in Debugging regular expressions in the perldebguts manpage.

Debugging memory usage

Perl contains internal support for reporting its own memory usage, but this is a fairly advanced concept that requires some understanding of how memory allocation works. See Debugging Perl memory usage in the perldebguts manpage for the details.

SEE ALSO

You did try the -w switch, didn't you?

the perldebtut manpage, the perldebguts manpage, the re manpage, the DB manpage, the Devel::DProf manpage, dprofpp, the Dumpvalue manpage, and the perlrun manpage.

When debugging a script that uses #! and is thus normally found in $PATH, the -S option causes perl to search $PATH for it, so you don't have to type the path or which $scriptname.

  $ perl -Sd foo.pl

BUGS

You cannot get stack frame information or in any fashion debug functions that were not compiled by Perl, such as those from C or C++ extensions.

If you alter your @_ arguments in a subroutine (such as with shift or pop), the stack backtrace will not show the original values.

The debugger does not currently work in conjunction with the -W command-line switch, because it itself is not free of warnings.

If you're in a slow syscall (like waiting, accepting, or reading from your keyboard or a socket) and haven't set up your own $SIG{INT} handler, then you won't be able to CTRL-C your way back to the debugger, because the debugger's own $SIG{INT} handler doesn't understand that it needs to raise an exception to longjmp(3) out of slow syscalls.


perldiag - various Perl diagnostics

NAME

perldiag - various Perl diagnostics

DESCRIPTION

These messages are classified as follows (listed in increasing order of desperation):

    (W) A warning (optional).
    (D) A deprecation (optional).
    (S) A severe warning (default).
    (F) A fatal error (trappable).
    (P) An internal error you should never see (trappable).
    (X) A very fatal error (nontrappable).
    (A) An alien error message (not generated by Perl).

The majority of messages from the first three classifications above (W, D & S) can be controlled using the warnings pragma.

If a message can be controlled by the warnings pragma, its warning category is included with the classification letter in the description below.

Optional warnings are enabled by using the warnings pragma or the -w and -W switches. Warnings may be captured by setting $SIG{__WARN__} to a reference to a routine that will be called on each warning instead of printing it. See the perlvar manpage.

Default warnings are always enabled unless they are explicitly disabled with the warnings pragma or the -X switch.

Trappable errors may be trapped using the eval operator. See eval in the perlfunc manpage. In almost all cases, warnings may be selectively disabled or promoted to fatal errors using the warnings pragma. See the warnings manpage.

The messages are in alphabetical order, without regard to upper or lower-case. Some of these messages are generic. Spots that vary are denoted with a %s or other printf-style escape. These escapes are ignored by the alphabetical order, as are all characters other than letters. To look up your message, just ignore anything that is not a letter.

accept() on closed socket %s

(W closed) You tried to do an accept on a closed socket. Did you forget to check the return value of your socket() call? See accept in the perlfunc manpage.

Allocation too large: %lx

(X) You can't allocate more than 64K on an MS-DOS machine.

'!' allowed only after types %s

(F) The '!' is allowed in pack() or unpack() only after certain types. See pack in the perlfunc manpage.

Ambiguous call resolved as CORE::%s(), qualify as such or use &

(W ambiguous) A subroutine you have declared has the same name as a Perl keyword, and you have used the name without qualification for calling one or the other. Perl decided to call the builtin because the subroutine is not imported.

To force interpretation as a subroutine call, either put an ampersand before the subroutine name, or qualify the name with its package. Alternatively, you can import the subroutine (or pretend that it's imported with the use subs pragma).

To silently interpret it as the Perl operator, use the CORE:: prefix on the operator (e.g. CORE::log($x)) or declare the subroutine to be an object method (see Subroutine Attributes in the perlsub manpage or the attributes manpage).

Ambiguous range in transliteration operator

(F) You wrote something like tr/a-z-0// which doesn't mean anything at all. To include a - character in a transliteration, put it either first or last. (In the past, tr/a-z-0// was synonymous with tr/a-y//, which was probably not what you would have expected.)

Ambiguous use of %s resolved as %s

(W ambiguous)(S) You said something that may not be interpreted the way you thought. Normally it's pretty easy to disambiguate it by supplying a missing quote, operator, parenthesis pair or declaration.

'|' and '<' may not both be specified on command line

(F) An error peculiar to VMS. Perl does its own command line redirection, and found that STDIN was a pipe, and that you also tried to redirect STDIN using '<'. Only one STDIN stream to a customer, please.

'|' and '>' may not both be specified on command line

(F) An error peculiar to VMS. Perl does its own command line redirection, and thinks you tried to redirect stdout both to a file and into a pipe to another command. You need to choose one or the other, though nothing's stopping you from piping into a program or Perl script which 'splits' output into two streams, such as

    open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!";
    while (<STDIN>) {
        print;
        print OUT;
    }
    close OUT;
Applying %s to %s will act on scalar(%s)

(W misc) The pattern match (//), substitution (s///), and transliteration (tr///) operators work on scalar values. If you apply one of them to an array or a hash, it will convert the array or hash to a scalar value -- the length of an array, or the population info of a hash -- and then work on that scalar value. This is probably not what you meant to do. See grep in the perlfunc manpage and map in the perlfunc manpage for alternatives.

Args must match #! line

(F) The setuid emulator requires that the arguments Perl was invoked with match the arguments specified on the #! line. Since some systems impose a one-argument limit on the #! line, try combining switches; for example, turn -w -U into -wU.

Arg too short for msgsnd

(F) msgsnd() requires a string at least as long as sizeof(long).

%s argument is not a HASH or ARRAY element

(F) The argument to exists() must be a hash or array element, such as:

    $foo{$bar}
    $ref->{"susie"}[12]
%s argument is not a HASH or ARRAY element or slice

(F) The argument to delete() must be either a hash or array element, such as:

    $foo{$bar}
    $ref->{"susie"}[12]

or a hash or array slice, such as:

    @foo[$bar, $baz, $xyzzy]
    @{$ref->[12]}{"susie", "queue"}
%s argument is not a subroutine name

(F) The argument to exists() for exists &sub must be a subroutine name, and not a subroutine call. exists &sub() will generate this error.

Argument "%s" isn't numeric%s

(W numeric) The indicated string was fed as an argument to an operator that expected a numeric value instead. If you're fortunate the message will identify which operator was so unfortunate.

Argument list not closed for PerlIO layer "%s"

(W layer) When pushing a layer with arguments onto the Perl I/O system you forgot the ) that closes the argument list. (Layers take care of transforming data between external and internal representations.) Perl stopped parsing the layer list at this point and did not attempt to push this layer. If your program didn't explicitly request the failing operation, it may be the result of the value of the environment variable PERLIO.

Array @%s missing the @ in argument %d of %s()

(D deprecated) Really old Perl let you omit the @ on array names in some spots. This is now heavily deprecated.

assertion botched: %s

(P) The malloc package that comes with Perl had an internal failure.

Assertion failed: file "%s"

(P) A general assertion failed. The file in question must be examined.

Assignment to both a list and a scalar

(F) If you assign to a conditional operator, the 2nd and 3rd arguments must either both be scalars or both be lists. Otherwise Perl won't know which context to supply to the right side.

A thread exited while %d threads were running

(W threads)(S) When using threaded Perl, a thread (not necessarily the main thread) exited while there were still other threads running. Usually it's a good idea to first collect the return values of the created threads by joining them, and only then exit from the main thread. See the threads manpage.

Attempt to access disallowed key '%s' in a restricted hash

(F) The failing code has attempted to get or set a key which is not in the current set of allowed keys of a restricted hash.

Attempt to bless into a reference

(F) The CLASSNAME argument to the bless() operator is expected to be the name of the package to bless the resulting object into. You've supplied instead a reference to something: perhaps you wrote

    bless $self, $proto;

when you intended

    bless $self, ref($proto) || $proto;

If you actually want to bless into the stringified version of the reference supplied, you need to stringify it yourself, for example by:

    bless $self, "$proto";
Attempt to delete disallowed key '%s' from a restricted hash

(F) The failing code attempted to delete from a restricted hash a key which is not in its key set.

Attempt to delete readonly key '%s' from a restricted hash

(F) The failing code attempted to delete a key whose value has been declared readonly from a restricted hash.

Attempt to free non-arena SV: 0x%lx

(P internal) All SV objects are supposed to be allocated from arenas that will be garbage collected on exit. An SV was discovered to be outside any of those arenas.

Attempt to free nonexistent shared string

(P internal) Perl maintains a reference counted internal table of strings to optimize the storage and access of hash keys and other strings. This indicates someone tried to decrement the reference count of a string that can no longer be found in the table.

Attempt to free temp prematurely

(W debugging) Mortalized values are supposed to be freed by the free_tmps() routine. This indicates that something else is freeing the SV before the free_tmps() routine gets a chance, which means that the free_tmps() routine will be freeing an unreferenced scalar when it does try to free it.

Attempt to free unreferenced glob pointers

(P internal) The reference counts got screwed up on symbol aliases.

Attempt to free unreferenced scalar

(W internal) Perl went to decrement the reference count of a scalar to see if it would go to 0, and discovered that it had already gone to 0 earlier, and should have been freed, and in fact, probably was freed. This could indicate that SvREFCNT_dec() was called too many times, or that SvREFCNT_inc() was called too few times, or that the SV was mortalized when it shouldn't have been, or that memory has been corrupted.

Attempt to join self

(F) You tried to join a thread from within itself, which is an impossible task. You may be joining the wrong thread, or you may need to move the join() to some other thread.

Attempt to pack pointer to temporary value

(W pack) You tried to pass a temporary value (like the result of a function, or a computed expression) to the "p" pack() template. This means the result contains a pointer to a location that could become invalid anytime, even before the end of the current statement. Use literals or global values as arguments to the "p" pack() template to avoid this warning.

Attempt to set length of freed array

(W) You tried to set the length of an array which has been freed. You can do this by storing a reference to the scalar representing the last index of an array and later assigning through that reference. For example

    $r = do {my @a; \$#a};
    $$r = 503
Attempt to use reference as lvalue in substr

(W substr) You supplied a reference as the first argument to substr() used as an lvalue, which is pretty strange. Perhaps you forgot to dereference it first. See substr in the perlfunc manpage.

Bad arg length for %s, is %d, should be %s

(F) You passed a buffer of the wrong size to one of msgctl(), semctl() or shmctl(). In C parlance, the correct sizes are, respectively, sizeof(struct msqid_ds *), sizeof(struct semid_ds *), and sizeof(struct shmid_ds *).

Bad evalled substitution pattern

(F) You've used the /e switch to evaluate the replacement for a substitution, but perl found a syntax error in the code to evaluate, most likely an unexpected right brace '}'.

Bad filehandle: %s

(F) A symbol was passed to something wanting a filehandle, but the symbol has no filehandle associated with it. Perhaps you didn't do an open(), or did it in another package.

Bad free() ignored

(S malloc) An internal routine called free() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by setting environment variable PERL_BADFREE to 0.

This message can be seen quite often with DB_File on systems with "hard" dynamic linking, like AIX and OS/2. It is a bug of Berkeley DB which is left unnoticed if DB uses forgiving system malloc().

Bad hash

(P) One of the internal hash routines was passed a null HV pointer.

Bad index while coercing array into hash

(F) The index looked up in the hash found as the 0'th element of a pseudo-hash is not legal. Index values must be at 1 or greater. See the perlref manpage.

Badly placed ()'s

(A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

Bad name after %s::

(F) You started to name a symbol by using a package prefix, and then didn't finish the symbol. In particular, you can't interpolate outside of quotes, so

    $var = 'myvar';
    $sym = mypack::$var;

is not the same as

    $var = 'myvar';
    $sym = "mypack::$var";
Bad realloc() ignored

(S malloc) An internal routine called realloc() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by setting environment variable PERL_BADFREE to 1.

Bad symbol for array

(P) An internal request asked to add an array entry to something that wasn't a symbol table entry.

Bad symbol for filehandle

(P) An internal request asked to add a filehandle entry to something that wasn't a symbol table entry.

Bad symbol for hash

(P) An internal request asked to add a hash entry to something that wasn't a symbol table entry.

Bareword found in conditional

(W bareword) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

    open FOO || die;

It may also indicate a misspelled constant that has been interpreted as a bareword:

    use constant TYPO => 1;
    if (TYOP) { print "foo" }

The strict pragma is useful in avoiding such errors.

Bareword "%s" not allowed while "strict subs" in use

(F) With "strict subs" in use, a bareword is only allowed as a subroutine identifier, in curly brackets or to the left of the "=>" symbol. Perhaps you need to predeclare a subroutine?

Bareword "%s" refers to nonexistent package

(W bareword) You used a qualified bareword of the form Foo::, but the compiler saw no other uses of that namespace before that point. Perhaps you need to predeclare a package?

BEGIN failed--compilation aborted

(F) An untrapped exception was raised while executing a BEGIN subroutine. Compilation stops immediately and the interpreter is exited.

BEGIN not safe after errors--compilation aborted

(F) Perl found a BEGIN {} subroutine (or a use directive, which implies a BEGIN {}) after one or more compilation errors had already occurred. Since the intended environment for the BEGIN {} could not be guaranteed (due to the errors), and since subsequent code likely depends on its correct operation, Perl just gave up.

\1 better written as $1

(W syntax) Outside of patterns, backreferences live on as variables. The use of backslashes is grandfathered on the right-hand side of a substitution, but stylistically it's better to use the variable form because other Perl programmers will expect it, and it works better if there are more than 9 backreferences.

Binary number > 0b11111111111111111111111111111111 non-portable

(W portable) The binary number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

bind() on closed socket %s

(W closed) You tried to do a bind on a closed socket. Did you forget to check the return value of your socket() call? See bind in the perlfunc manpage.

binmode() on closed filehandle %s

(W unopened) You tried binmode() on a filehandle that was never opened. Check you control flow and number of arguments.

Bit vector size > 32 non-portable

(W portable) Using bit vector sizes larger than 32 is non-portable.

Bizarre copy of %s in %s

(P) Perl detected an attempt to copy an internal value that is not copyable.

Buffer overflow in prime_env_iter: %s

(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over %ENV, it encountered a logical name or symbol definition which was too long, so it was truncated to the string shown.

Callback called exit

(F) A subroutine invoked from an external package via call_sv() exited by calling exit.

%s() called too early to check prototype

(W prototype) You've called a function that has a prototype before the parser saw a definition or declaration for it, and Perl could not check that the call conforms to the prototype. You need to either add an early prototype declaration for the subroutine in question, or move the subroutine definition ahead of the call to get proper prototype checking. Alternatively, if you are certain that you're calling the function correctly, you may put an ampersand before the name to avoid the warning. See the perlsub manpage.

Cannot compress integer in pack

(F) An argument to pack("w",...) was too large to compress. The BER compressed integer format can only be used with positive integers, and you attempted to compress Infinity or a very large number (> 1e308). See pack in the perlfunc manpage.

Cannot compress negative numbers in pack

(F) An argument to pack("w",...) was negative. The BER compressed integer format can only be used with positive integers. See pack in the perlfunc manpage.

Can only compress unsigned integers in pack

(F) An argument to pack("w",...) was not an integer. The BER compressed integer format can only be used with positive integers, and you attempted to compress something else. See pack in the perlfunc manpage.

Can't bless non-reference value

(F) Only hard references may be blessed. This is how Perl "enforces" encapsulation of objects. See the perlobj manpage.

Can't call method "%s" in empty package "%s"

(F) You called a method correctly, and it correctly indicated a package functioning as a class, but that package doesn't have ANYTHING defined in it, let alone methods. See the perlobj manpage.

Can't call method "%s" on an undefined value

(F) You used the syntax of a method call, but the slot filled by the object reference or package name contains an undefined value. Something like this will reproduce the error:

    $BADREF = undef;
    process $BADREF 1,2,3;
    $BADREF->process(1,2,3);
Can't call method "%s" on unblessed reference

(F) A method call must know in what package it's supposed to run. It ordinarily finds this out from the object reference you supply, but you didn't supply an object reference in this case. A reference isn't an object reference until it has been blessed. See the perlobj manpage.

Can't call method "%s" without a package or object reference

(F) You used the syntax of a method call, but the slot filled by the object reference or package name contains an expression that returns a defined value which is neither an object reference nor a package name. Something like this will reproduce the error:

    $BADREF = 42;
    process $BADREF 1,2,3;
    $BADREF->process(1,2,3);
Can't chdir to %s

(F) You called perl -x/foo/bar, but /foo/bar is not a directory that you can chdir to, possibly because it doesn't exist.

Can't check filesystem of script "%s" for nosuid

(P) For some reason you can't check the filesystem of the script for nosuid.

Can't coerce array into hash

(F) You used an array where a hash was expected, but the array has no information on how to map from keys to array indices. You can do that only with arrays that have a hash reference at index 0.

Can't coerce %s to integer in %s

(F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are. So you can't say things like:

    *foo += 1;

You CAN say

    $foo = *foo;
    $foo += 1;

but then $foo no longer contains a glob.

Can't coerce %s to number in %s

(F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are.

Can't coerce %s to string in %s

(F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are.

Can't create pipe mailbox

(P) An error peculiar to VMS. The process is suffering from exhausted quotas or other plumbing problems.

Can't declare class for non-scalar %s in "%s"

(F) Currently, only scalar variables can be declared with a specific class qualifier in a "my" or "our" declaration. The semantics may be extended for other types of variables in future.

Can't declare %s in "%s"

(F) Only scalar, array, and hash variables may be declared as "my" or "our" variables. They must have ordinary identifiers as names.

Can't do inplace edit: %s is not a regular file

(S inplace) You tried to use the -i switch on a special file, such as a file in /dev, or a FIFO. The file was ignored.

Can't do inplace edit on %s: %s

(S inplace) The creation of the new file failed for the indicated reason.

Can't do inplace edit without backup

(F) You're on a system such as MS-DOS that gets confused if you try reading from a deleted (but still opened) file. You have to say -i.bak, or some such.

Can't do inplace edit: %s would not be unique

(S inplace) Your filesystem does not support filenames longer than 14 characters and Perl was unable to create a unique filename during inplace editing with the -i switch. The file was ignored.

Can't do {n,m} with n > m in regex; marked by <-- HERE in m/%s/

(F) Minima must be less than or equal to maxima. If you really want your regexp to match something 0 times, just put {0}. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Can't do setegid!

(P) The setegid() call failed for some reason in the setuid emulator of suidperl.

Can't do seteuid!

(P) The setuid emulator of suidperl failed for some reason.

Can't do setuid

(F) This typically means that ordinary perl tried to exec suidperl to do setuid emulation, but couldn't exec it. It looks for a name of the form sperl5.000 in the same directory that the perl executable resides under the name perl5.000, typically /usr/local/bin on Unix machines. If the file is there, check the execute permissions. If it isn't, ask your sysadmin why he and/or she removed it.

Can't do waitpid with flags

(F) This machine doesn't have either waitpid() or wait4(), so only waitpid() without flags is emulated.

Can't emulate -%s on #! line

(F) The #! line specifies a switch that doesn't make sense at this point. For example, it'd be kind of silly to put a -x on the #! line.

Can't exec "%s": %s

(W exec) A system(), exec(), or piped open call could not execute the named program for the indicated reason. Typical reasons include: the permissions were wrong on the file, the file wasn't found in $ENV{PATH}, the executable in question was compiled for another architecture, or the #! line in a script points to an interpreter that can't be run for similar reasons. (Or maybe your system doesn't support #! at all.)

Can't exec %s

(F) Perl was trying to execute the indicated program for you because that's what the #! line said. If that's not what you wanted, you may need to mention "perl" on the #! line somewhere.

Can't execute %s

(F) You used the -S switch, but the copies of the script to execute found in the PATH did not have correct permissions.

Can't find an opnumber for "%s"

(F) A string of a form CORE::word was given to prototype(), but there is no builtin with the name word.

Can't find %s character property "%s"

(F) You used \p{} or \P{} but the character property by that name could not be found. Maybe you misspelled the name of the property (remember that the names of character properties consist only of alphanumeric characters), or maybe you forgot the Is or In prefix?

Can't find label %s

(F) You said to goto a label that isn't mentioned anywhere that it's possible for us to go to. See goto in the perlfunc manpage.

Can't find %s on PATH

(F) You used the -S switch, but the script to execute could not be found in the PATH.

Can't find %s on PATH, '.' not in PATH

(F) You used the -S switch, but the script to execute could not be found in the PATH, or at least not with the correct permissions. The script exists in the current directory, but PATH prohibits running it.

Can't find %s property definition %s

(F) You may have tried to use \p which means a Unicode property (for example \p{Lu} is all uppercase letters). If you did mean to use a Unicode property, see the perlunicode manpage for the list of known properties. If you didn't mean to use a Unicode property, escape the \p, either by \\p (just the \p) or by \Q\p (the rest of the string, until possible \E).

Can't find string terminator %s anywhere before EOF

(F) Perl strings can stretch over multiple lines. This message means that the closing delimiter was omitted. Because bracketed quotes count nesting levels, the following is missing its final parenthesis:

    print q(The character '(' starts a side comment.);

If you're getting this error from a here-document, you may have included unseen whitespace before or after your closing tag. A good programmer's editor will have a way to help you find these characters.

Can't fork

(F) A fatal error occurred while trying to fork while opening a pipeline.

Can't get filespec - stale stat buffer?

(S) A warning peculiar to VMS. This arises because of the difference between access checks under VMS and under the Unix model Perl assumes. Under VMS, access checks are done by filename, rather than by bits in the stat buffer, so that ACLs and other protections can be taken into account. Unfortunately, Perl assumes that the stat buffer contains all the necessary information, and passes it, instead of the filespec, to the access checking routine. It will try to retrieve the filespec using the device name and FID present in the stat buffer, but this works only if you haven't made a subsequent call to the CRTL stat() routine, because the device name is overwritten with each call. If this warning appears, the name lookup failed, and the access checking routine gave up and returned FALSE, just to be conservative. (Note: The access checking routine knows about the Perl stat operator and file tests, so you shouldn't ever see this warning in response to a Perl command; it arises only if some internal code takes stat buffers lightly.)

Can't get pipe mailbox device name

(P) An error peculiar to VMS. After creating a mailbox to act as a pipe, Perl can't retrieve its name for later use.

Can't get SYSGEN parameter value for MAXBUF

(P) An error peculiar to VMS. Perl asked $GETSYI how big you want your mailbox buffers to be, and didn't get an answer.

Can't "goto" into the middle of a foreach loop

(F) A "goto" statement was executed to jump into the middle of a foreach loop. You can't get there from here. See goto in the perlfunc manpage.

Can't "goto" out of a pseudo block

(F) A "goto" statement was executed to jump out of what might look like a block, except that it isn't a proper block. This usually occurs if you tried to jump out of a sort() block or subroutine, which is a no-no. See goto in the perlfunc manpage.

Can't goto subroutine from an eval-%s

(F) The "goto subroutine" call can't be used to jump out of an eval "string" or block.

Can't goto subroutine outside a subroutine

(F) The deeply magical "goto subroutine" call can only replace one subroutine call for another. It can't manufacture one out of whole cloth. In general you should be calling it out of only an AUTOLOAD routine anyway. See goto in the perlfunc manpage.

Can't ignore signal CHLD, forcing to default

(W signal) Perl has detected that it is being run with the SIGCHLD signal (sometimes known as SIGCLD) disabled. Since disabling this signal will interfere with proper determination of exit status of child processes, Perl has reset the signal to its default value. This situation typically indicates that the parent program under which Perl may be running (e.g. cron) is being very careless.

Can't "last" outside a loop block

(F) A "last" statement was executed to break out of the current block, except that there's this itty bitty problem called there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(), map() or grep(). You can usually double the curlies to get the same effect though, because the inner curlies will be considered a block that loops once. See last in the perlfunc manpage.

Can't load '%s' for module %s

(F) The module you tried to load failed to load a dynamic extension. This may either mean that you upgraded your version of perl to one that is incompatible with your old dynamic extensions (which is known to happen between major versions of perl), or (more likely) that your dynamic extension was built against an older version of the library that is installed on your system. You may need to rebuild your old dynamic extensions.

Can't localize lexical variable %s

(F) You used local on a variable name that was previously declared as a lexical variable using "my". This is not allowed. If you want to localize a package variable of the same name, qualify it with the package name.

Can't localize pseudo-hash element

(F) You said something like local $ar->{'key'}, where $ar is a reference to a pseudo-hash. That hasn't been implemented yet, but you can get a similar effect by localizing the corresponding array element directly -- local $ar->[$ar->[0]{'key'}].

Can't localize through a reference

(F) You said something like local $$ref, which Perl can't currently handle, because when it goes to restore the old value of whatever $ref pointed to after the scope of the local() is finished, it can't be sure that $ref will still be a reference.

Can't locate %s

(F) You said to do (or require, or use) a file that couldn't be found. Perl looks for the file in all the locations mentioned in @INC, unless the file name included the full path to the file. Perhaps you need to set the PERL5LIB or PERL5OPT environment variable to say where the extra library is, or maybe the script needs to add the library name to @INC. Or maybe you just misspelled the name of the file. See require in the perlfunc manpage and the lib manpage.

Can't locate auto/%s.al in @INC

(F) A function (or method) was called in a package which allows autoload, but there is no function to autoload. Most probable causes are a misprint in a function/method name or a failure to AutoSplit the file, say, by doing make install.

Can't locate loadable object for module %s in @INC

(F) The module you loaded is trying to load an external library, like for example, foo.so or bar.dll, but the the DynaLoader manpage module was unable to locate this library. See the DynaLoader manpage.

Can't locate object method "%s" via package "%s"

(F) You called a method correctly, and it correctly indicated a package functioning as a class, but that package doesn't define that particular method, nor does any of its base classes. See the perlobj manpage.

Can't locate package %s for @%s::ISA

(W syntax) The @ISA array contained the name of another package that doesn't seem to exist.

Can't locate PerlIO%s

(F) You tried to use in open() a PerlIO layer that does not exist, e.g. open(FH, ">:nosuchlayer", "somefile").

Can't make list assignment to \%ENV on this system

(F) List assignment to %ENV is not supported on some systems, notably VMS.

Can't modify %s in %s

(F) You aren't allowed to assign to the item indicated, or otherwise try to change it, such as with an auto-increment.

Can't modify nonexistent substring

(P) The internal routine that does assignment to a substr() was handed a NULL.

Can't modify non-lvalue subroutine call

(F) Subroutines meant to be used in lvalue context should be declared as such, see Lvalue subroutines in the perlsub manpage.

Can't msgrcv to read-only var

(F) The target of a msgrcv must be modifiable to be used as a receive buffer.

Can't "next" outside a loop block

(F) A "next" statement was executed to reiterate the current block, but there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(), map() or grep(). You can usually double the curlies to get the same effect though, because the inner curlies will be considered a block that loops once. See next in the perlfunc manpage.

Can't open %s: %s

(S inplace) The implicit opening of a file through use of the <> filehandle, either implicitly under the -n or -p command-line switches, or explicitly, failed for the indicated reason. Usually this is because you don't have read permission for a file which you named on the command line.

Can't open a reference

(W io) You tried to open a scalar reference for reading or writing, using the 3-arg open() syntax :

    open FH, '>', $ref;

but your version of perl is compiled without perlio, and this form of open is not supported.

Can't open bidirectional pipe

(W pipe) You tried to say open(CMD, "|cmd|"), which is not supported. You can try any of several modules in the Perl library to do this, such as IPC::Open2. Alternately, direct the pipe's output to a file using ">", and then read it in under a different file handle.

Can't open error file %s as stderr

(F) An error peculiar to VMS. Perl does its own command line redirection, and couldn't open the file specified after '2>' or '2>>' on the command line for writing.

Can't open input file %s as stdin

(F) An error peculiar to VMS. Perl does its own command line redirection, and couldn't open the file specified after '<' on the command line for reading.

Can't open output file %s as stdout

(F) An error peculiar to VMS. Perl does its own command line redirection, and couldn't open the file specified after '>' or '>>' on the command line for writing.

Can't open output pipe (name: %s)

(P) An error peculiar to VMS. Perl does its own command line redirection, and couldn't open the pipe into which to send data destined for stdout.

Can't open perl script%s

(F) The script you specified can't be opened for the indicated reason.

If you're debugging a script that uses #!, and normally relies on the shell's $PATH search, the -S option causes perl to do that search, so you don't have to type the path or `which $scriptname`.

Can't read CRTL environ

(S) A warning peculiar to VMS. Perl tried to read an element of %ENV from the CRTL's internal environment array and discovered the array was missing. You need to figure out where your CRTL misplaced its environ or define PERL_ENV_TABLES (see the perlvms manpage) so that environ is not searched.

Can't redefine active sort subroutine %s

(F) Perl optimizes the internal handling of sort subroutines and keeps pointers into them. You tried to redefine one such sort subroutine when it was currently active, which is not allowed. If you really want to do this, you should write sort { &func } @x instead of sort func @x.

Can't "redo" outside a loop block

(F) A "redo" statement was executed to restart the current block, but there isn't a current block. Note that an "if" or "else" block doesn't count as a "loopish" block, as doesn't a block given to sort(), map() or grep(). You can usually double the curlies to get the same effect though, because the inner curlies will be considered a block that loops once. See redo in the perlfunc manpage.

Can't remove %s: %s, skipping file

(S inplace) You requested an inplace edit without creating a backup file. Perl was unable to remove the original file to replace it with the modified file. The file was left unmodified.

Can't rename %s to %s: %s, skipping file

(S inplace) The rename done by the -i switch failed for some reason, probably because you don't have write permission to the directory.

Can't reopen input pipe (name: %s) in binary mode

(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried to reopen it to accept binary data. Alas, it failed.

Can't resolve method `%s' overloading `%s' in package `%s'

(F|P) Error resolving overloading specified by a method name (as opposed to a subroutine reference): no such method callable via the package. If method name is ???, this is an internal error.

Can't reswap uid and euid

(P) The setreuid() call failed for some reason in the setuid emulator of suidperl.

Can't return %s from lvalue subroutine

(F) Perl detected an attempt to return illegal lvalues (such as temporary or readonly values) from a subroutine used as an lvalue. This is not allowed.

Can't return outside a subroutine

(F) The return statement was executed in mainline code, that is, where there was no subroutine call to return out of. See the perlsub manpage.

Can't return %s to lvalue scalar context

(F) You tried to return a complete array or hash from an lvalue subroutine, but you called the subroutine in a way that made Perl think you meant to return only one value. You probably meant to write parentheses around the call to the subroutine, which tell Perl that the call should be in list context.

Can't stat script "%s"

(P) For some reason you can't fstat() the script even though you have it open already. Bizarre.

Can't swap uid and euid

(P) The setreuid() call failed for some reason in the setuid emulator of suidperl.

Can't take log of %g

(F) For ordinary real numbers, you can't take the logarithm of a negative number or zero. There's a Math::Complex package that comes standard with Perl, though, if you really want to do that for the negative numbers.

Can't take sqrt of %g

(F) For ordinary real numbers, you can't take the square root of a negative number. There's a Math::Complex package that comes standard with Perl, though, if you really want to do that.

Can't undef active subroutine

(F) You can't undefine a routine that's currently running. You can, however, redefine it while it's running, and you can even undef the redefined subroutine while the old routine is running. Go figure.

Can't unshift

(F) You tried to unshift an "unreal" array that can't be unshifted, such as the main Perl stack.

Can't upgrade that kind of scalar

(P) The internal sv_upgrade routine adds "members" to an SV, making it into a more specialized kind of SV. The top several SV types are so specialized, however, that they cannot be interconverted. This message indicates that such a conversion was attempted.

Can't upgrade to undef

(P) The undefined SV is the bottom of the totem pole, in the scheme of upgradability. Upgrading to undef indicates an error in the code calling sv_upgrade.

Can't use anonymous symbol table for method lookup

(F) The internal routine that does method lookup was handed a symbol table that doesn't have a name. Symbol tables can become anonymous for example by undefining stashes: undef %Some::Package::.

Can't use an undefined value as %s reference

(F) A value used as either a hard reference or a symbolic reference must be a defined value. This helps to delurk some insidious errors.

Can't use bareword ("%s") as %s ref while "strict refs" in use

(F) Only hard references are allowed by "strict refs". Symbolic references are disallowed. See the perlref manpage.

Can't use %! because Errno.pm is not available

(F) The first time the %! hash is used, perl automatically loads the Errno.pm module. The Errno module is expected to tie the %! hash to provide symbolic names for $! errno values.

Can't use %s for loop variable

(F) Only a simple scalar variable may be used as a loop variable on a foreach.

Can't use global %s in "my"

(F) You tried to declare a magical variable as a lexical variable. This is not allowed, because the magic can be tied to only one location (namely the global variable) and it would be incredibly confusing to have variables in your program that looked like magical variables but weren't.

Can't use "my %s" in sort comparison

(F) The global variables $a and $b are reserved for sort comparisons. You mentioned $a or $b in the same line as the <=> or cmp operator, and the variable had earlier been declared as a lexical variable. Either qualify the sort variable with the package name, or rename the lexical variable.

Can't use %s ref as %s ref

(F) You've mixed up your reference types. You have to dereference a reference of the type needed. You can use the ref() function to test the type of the reference, if need be.

Can't use string ("%s") as %s ref while "strict refs" in use

(F) Only hard references are allowed by "strict refs". Symbolic references are disallowed. See the perlref manpage.

Can't use subscript on %s

(F) The compiler tried to interpret a bracketed expression as a subscript. But to the left of the brackets was an expression that didn't look like a hash or array reference, or anything else subscriptable.

Can't use \%c to mean $%c in expression

(W syntax) In an ordinary expression, backslash is a unary operator that creates a reference to its argument. The use of backslash to indicate a backreference to a matched substring is valid only as part of a regular expression pattern. Trying to do this in ordinary Perl code produces a value that prints out looking like SCALAR(0xdecaf). Use the $1 form instead.

Can't weaken a nonreference

(F) You attempted to weaken something that was not a reference. Only references can be weakened.

Can't x= to read-only value

(F) You tried to repeat a constant value (often the undefined value) with an assignment operator, which implies modifying the value itself. Perhaps you need to copy the value to a temporary, and repeat that.

Character in "C" format wrapped in pack

(W pack) You said

    pack("C", $x)

where $x is either less than 0 or more than 255; the "C" format is only for encoding native operating system characters (ASCII, EBCDIC, and so on) and not for Unicode characters, so Perl behaved as if you meant

    pack("C", $x & 255)

If you actually want to pack Unicode codepoints, use the "U" format instead.

Character in "c" format wrapped in pack

(W pack) You said

    pack("c", $x)

where $x is either less than -128 or more than 127; the "c" format is only for encoding native operating system characters (ASCII, EBCDIC, and so on) and not for Unicode characters, so Perl behaved as if you meant

    pack("c", $x & 255);

If you actually want to pack Unicode codepoints, use the "U" format instead.

close() on unopened filehandle %s

(W unopened) You tried to close a filehandle that was never opened.

Code missing after '/'

(F) You had a (sub-)template that ends with a '/'. There must be another template code following the slash. See pack in the perlfunc manpage.

%s: Command not found

(A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

Compilation failed in require

(F) Perl could not compile a file specified in a require statement. Perl uses this generic message when none of the errors that it encountered were severe enough to halt compilation immediately.

Complex regular subexpression recursion limit (%d) exceeded

(W regexp) The regular expression engine uses recursion in complex situations where back-tracking is required. Recursion depth is limited to 32766, or perhaps less in architectures where the stack cannot grow arbitrarily. ("Simple" and "medium" situations are handled without recursion and are not subject to a limit.) Try shortening the string under examination; looping in Perl code (e.g. with while) rather than in the regular expression engine; or rewriting the regular expression so that it is simpler or backtracks less. (See the perlfaq2 manpage for information on Mastering Regular Expressions.)

cond_broadcast() called on unlocked variable

(W threads) Within a thread-enabled program, you tried to call cond_broadcast() on a variable which wasn't locked. The cond_broadcast() function is used to wake up another thread that is waiting in a cond_wait(). To ensure that the signal isn't sent before the other thread has a chance to enter the wait, it is usual for the signaling thread to first wait for a lock on variable. This lock attempt will only succeed after the other thread has entered cond_wait() and thus relinquished the lock.

cond_signal() called on unlocked variable

(W threads) Within a thread-enabled program, you tried to call cond_signal() on a variable which wasn't locked. The cond_signal() function is used to wake up another thread that is waiting in a cond_wait(). To ensure that the signal isn't sent before the other thread has a chance to enter the wait, it is usual for the signaling thread to first wait for a lock on variable. This lock attempt will only succeed after the other thread has entered cond_wait() and thus relinquished the lock.

connect() on closed socket %s

(W closed) You tried to do a connect on a closed socket. Did you forget to check the return value of your socket() call? See connect in the perlfunc manpage.

Constant(%s)%s: %s

(F) The parser found inconsistencies either while attempting to define an overloaded constant, or when trying to find the character name specified in the \N{...} escape. Perhaps you forgot to load the corresponding overload or charnames pragma? See the charnames manpage and the overload manpage.

Constant is not %s reference

(F) A constant value (perhaps declared using the use constant pragma) is being dereferenced, but it amounts to the wrong type of reference. The message indicates the type of reference that was expected. This usually indicates a syntax error in dereferencing the constant value. See Constant Functions in the perlsub manpage and the constant manpage.

Constant subroutine %s redefined

(S) You redefined a subroutine which had previously been eligible for inlining. See Constant Functions in the perlsub manpage for commentary and workarounds.

Constant subroutine %s undefined

(W misc) You undefined a subroutine which had previously been eligible for inlining. See Constant Functions in the perlsub manpage for commentary and workarounds.

Copy method did not return a reference

(F) The method which overloads "=" is buggy. See Copy Constructor in the overload manpage.

CORE::%s is not a keyword

(F) The CORE:: namespace is reserved for Perl keywords.

corrupted regexp pointers

(P) The regular expression engine got confused by what the regular expression compiler gave it.

corrupted regexp program

(P) The regular expression engine got passed a regexp program without a valid magic number.

Corrupt malloc ptr 0x%lx at 0x%lx

(P) The malloc package that comes with Perl had an internal failure.

Count after length/code in unpack

(F) You had an unpack template indicating a counted-length string, but you have also specified an explicit size for the string. See pack in the perlfunc manpage.

Deep recursion on subroutine "%s"

(W recursion) This subroutine has called itself (directly or indirectly) 100 times more than it has returned. This probably indicates an infinite recursion, unless you're writing strange benchmark programs, in which case it indicates something else.

defined(@array) is deprecated

(D deprecated) defined() is not usually useful on arrays because it checks for an undefined scalar value. If you want to see if the array is empty, just use if (@array) { # not empty } for example.

defined(%hash) is deprecated

(D deprecated) defined() is not usually useful on hashes because it checks for an undefined scalar value. If you want to see if the hash is empty, just use if (%hash) { # not empty } for example.

%s defines neither package nor VERSION--version check failed

(F) You said something like "use Module 42" but in the Module file there are neither package declarations nor a $VERSION.

Delimiter for here document is too long

(F) In a here document construct like <<FOO, the label FOO is too long for Perl to handle. You have to be seriously twisted to write code that triggers this error.

DESTROY created new reference to dead object '%s'

(F) A DESTROY() method created a new reference to the object which is just being DESTROYed. Perl is confused, and prefers to abort rather than to create a dangling reference.

Did not produce a valid header

See Server error.

%s did not return a true value

(F) A required (or used) file must return a true value to indicate that it compiled correctly and ran its initialization code correctly. It's traditional to end such a file with a "1;", though any true value would do. See require in the perlfunc manpage.

(Did you mean &%s instead?)

(W) You probably referred to an imported subroutine &FOO as $FOO or some such.

(Did you mean "local" instead of "our"?)

(W misc) Remember that "our" does not localize the declared global variable. You have declared it again in the same lexical scope, which seems superfluous.

(Did you mean $ or @ instead of %?)

(W) You probably said %hash{$key} when you meant $hash{$key} or @hash{@keys}. On the other hand, maybe you just meant %hash and got carried away.

Died

(F) You passed die() an empty string (the equivalent of die "") or you called it with no args and both $@ and $_ were empty.

Document contains no data

See Server error.

%s does not define %s::VERSION--version check failed

(F) You said something like "use Module 42" but the Module did not define a $VERSION.

'/' does not take a repeat count

(F) You cannot put a repeat count of any kind right after the '/' code. See pack in the perlfunc manpage.

Don't know how to handle magic of type '%s'

(P) The internal handling of magical variables has been cursed.

do_study: out of memory

(P) This should have been caught by safemalloc() instead.

(Do you need to predeclare %s?)

(S syntax) This is an educated guess made in conjunction with the message "%s found where operator expected". It often means a subroutine or module name is being referenced that hasn't been declared yet. This may be because of ordering problems in your file, or because of a missing "sub", "package", "require", or "use" statement. If you're referencing something that isn't defined yet, you don't actually have to define the subroutine or package before the current location. You can use an empty "sub foo;" or "package FOO;" to enter a "forward" declaration.

dump() better written as CORE::dump()

(W misc) You used the obsolescent dump() built-in function, without fully qualifying it as CORE::dump(). Maybe it's a typo. See dump in the perlfunc manpage.

Duplicate free() ignored

(S malloc) An internal routine called free() on something that had already been freed.

Duplicate modifier '%c' after '%c' in %s

(W) You have applied the same modifier more than once after a type in a pack template. See pack in the perlfunc manpage.

elseif should be elsif

(S syntax) There is no keyword "elseif" in Perl because Larry thinks it's ugly. Your code will be interpreted as an attempt to call a method named "elseif" for the class returned by the following block. This is unlikely to be what you want.

Empty %s

(F) \p and \P are used to introduce a named Unicode property, as described in the perlunicode manpage and the perlre manpage. You used \p or \P in a regular expression without specifying the property name.

entering effective %s failed

(F) While under the use filetest pragma, switching the real and effective uids or gids failed.

%ENV is aliased to %s

(F) You're running under taint mode, and the %ENV variable has been aliased to another hash, so it doesn't reflect anymore the state of the program's environment. This is potentially insecure.

Error converting file specification %s

(F) An error peculiar to VMS. Because Perl may have to deal with file specifications in either VMS or Unix syntax, it converts them to a single form when it must operate on them directly. Either you've passed an invalid file specification to Perl, or you've found a case the conversion routines don't handle. Drat.

%s: Eval-group in insecure regular expression

(F) Perl detected tainted data when trying to compile a regular expression that contains the (?{ ... }) zero-width assertion, which is unsafe. See (?{ code }) in the perlre manpage, and the perlsec manpage.

%s: Eval-group not allowed at run time

(F) Perl tried to compile a regular expression containing the (?{ ... }) zero-width assertion at run time, as it would when the pattern contains interpolated values. Since that is a security risk, it is not allowed. If you insist, you may still do this by explicitly building the pattern from an interpolated string at run time and using that in an eval(). See (?{ code }) in the perlre manpage.

%s: Eval-group not allowed, use re 'eval'

(F) A regular expression contained the (?{ ... }) zero-width assertion, but that construct is only allowed when the use re 'eval' pragma is in effect. See (?{ code }) in the perlre manpage.

Excessively long <> operator

(F) The contents of a <> operator may not exceed the maximum size of a Perl identifier. If you're just trying to glob a long list of filenames, try using the glob() operator, or put the filenames into a variable and glob that.

exec? I'm not *that* kind of operating system

(F) The exec function is not implemented in MacPerl. See the perlport manpage.

Execution of %s aborted due to compilation errors

(F) The final summary message when a Perl compilation fails.

Exiting eval via %s

(W exiting) You are exiting an eval by unconventional means, such as a goto, or a loop control statement.

Exiting format via %s

(W exiting) You are exiting a format by unconventional means, such as a goto, or a loop control statement.

Exiting pseudo-block via %s

(W exiting) You are exiting a rather special block construct (like a sort block or subroutine) by unconventional means, such as a goto, or a loop control statement. See sort in the perlfunc manpage.

Exiting subroutine via %s

(W exiting) You are exiting a subroutine by unconventional means, such as a goto, or a loop control statement.

Exiting substitution via %s

(W exiting) You are exiting a substitution by unconventional means, such as a return, a goto, or a loop control statement.

Explicit blessing to '' (assuming package main)

(W misc) You are blessing a reference to a zero length string. This has the effect of blessing the reference into the package main. This is usually not what you want. Consider providing a default target package, e.g. bless($ref, $p || 'MyPackage');

%s: Expression syntax

(A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

%s failed--call queue aborted

(F) An untrapped exception was raised while executing a CHECK, INIT, or END subroutine. Processing of the remainder of the queue of such routines has been prematurely ended.

False [] range "%s" in regex; marked by <-- HERE in m/%s/

(W regexp) A character class range must start and end at a literal character, not another character class like \d or [:alpha:]. The "-" in your false range is interpreted as a literal "-". Consider quoting the "-", "\-". The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Fatal VMS error at %s, line %d

(P) An error peculiar to VMS. Something untoward happened in a VMS system service or RTL routine; Perl's exit status should provide more details. The filename in "at %s" and the line number in "line %d" tell you which section of the Perl source code is distressed.

fcntl is not implemented

(F) Your machine apparently doesn't implement fcntl(). What is this, a PDP-11 or something?

Filehandle %s opened only for input

(W io) You tried to write on a read-only filehandle. If you intended it to be a read-write filehandle, you needed to open it with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you intended only to write the file, use ">" or ">>". See open in the perlfunc manpage.

Filehandle %s opened only for output

(W io) You tried to read from a filehandle opened only for writing, If you intended it to be a read/write filehandle, you needed to open it with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you intended only to read from the file, use "<". See open in the perlfunc manpage. Another possibility is that you attempted to open filedescriptor 0 (also known as STDIN) for output (maybe you closed STDIN earlier?).

Filehandle %s reopened as %s only for input

(W io) You opened for reading a filehandle that got the same filehandle id as STDOUT or STDERR. This occurred because you closed STDOUT or STDERR previously.

Filehandle STDIN reopened as %s only for output

(W io) You opened for writing a filehandle that got the same filehandle id as STDIN. This occurred because you closed STDIN previously.

Final $ should be \$ or $name

(F) You must now decide whether the final $ in a string was meant to be a literal dollar sign, or was meant to introduce a variable name that happens to be missing. So you have to put either the backslash or the name.

flock() on closed filehandle %s

(W closed) The filehandle you're attempting to flock() got itself closed some time before now. Check your control flow. flock() operates on filehandles. Are you attempting to call flock() on a dirhandle by the same name?

Format not terminated

(F) A format must be terminated by a line with a solitary dot. Perl got to the end of your file without finding such a line.

Format %s redefined

(W redefine) You redefined a format. To suppress this warning, say

    {
        no warnings 'redefine';
        eval "format NAME =...";
    }
Found = in conditional, should be ==

(W syntax) You said

    if ($foo = 123)

when you meant

    if ($foo == 123)

(or something like that).

%s found where operator expected

(S syntax) The Perl lexer knows whether to expect a term or an operator. If it sees what it knows to be a term when it was expecting to see an operator, it gives you this warning. Usually it indicates that an operator or delimiter was omitted, such as a semicolon.

gdbm store returned %d, errno %d, key "%s"

(S) A warning from the GDBM_File extension that a store failed.

gethostent not implemented

(F) Your C library apparently doesn't implement gethostent(), probably because if it did, it'd feel morally obligated to return every hostname on the Internet.

get%sname() on closed socket %s

(W closed) You tried to get a socket or peer socket name on a closed socket. Did you forget to check the return value of your socket() call?

getpwnam returned invalid UIC %#o for user "%s"

(S) A warning peculiar to VMS. The call to sys$getuai underlying the getpwnam operator returned an invalid UIC.

getsockopt() on closed socket %s

(W closed) You tried to get a socket option on a closed socket. Did you forget to check the return value of your socket() call? See getsockopt in the perlfunc manpage.

Global symbol "%s" requires explicit package name

(F) You've said "use strict vars", which indicates that all variables must either be lexically scoped (using "my"), declared beforehand using "our", or explicitly qualified to say which package the global variable is in (using "::").

glob failed (%s)

(W glob) Something went wrong with the external program(s) used for glob and <*.c>. Usually, this means that you supplied a glob pattern that caused the external program to fail and exit with a nonzero status. If the message indicates that the abnormal exit resulted in a coredump, this may also mean that your csh (C shell) is broken. If so, you should change all of the csh-related variables in config.sh: If you have tcsh, make the variables refer to it as if it were csh (e.g. full_csh='/usr/bin/tcsh'); otherwise, make them all empty (except that d_csh should be 'undef') so that Perl will think csh is missing. In either case, after editing config.sh, run ./Configure -S and rebuild Perl.

Glob not terminated

(F) The lexer saw a left angle bracket in a place where it was expecting a term, so it's looking for the corresponding right angle bracket, and not finding it. Chances are you left some needed parentheses out earlier in the line, and you really meant a "less than".

Got an error from DosAllocMem

(P) An error peculiar to OS/2. Most probably you're using an obsolete version of Perl, and this should not happen anyway.

goto must have label

(F) Unlike with "next" or "last", you're not allowed to goto an unspecified destination. See goto in the perlfunc manpage.

()-group starts with a count

(F) A ()-group started with a count. A count is supposed to follow something: a template character or a ()-group. See pack in the perlfunc manpage.

%s had compilation errors

(F) The final summary message when a perl -c fails.

Had to create %s unexpectedly

(S internal) A routine asked for a symbol from a symbol table that ought to have existed already, but for some reason it didn't, and had to be created on an emergency basis to prevent a core dump.

Hash %%s missing the % in argument %d of %s()

(D deprecated) Really old Perl let you omit the % on hash names in some spots. This is now heavily deprecated.

%s has too many errors

(F) The parser has given up trying to parse the program after 10 errors. Further error messages would likely be uninformative.

Hexadecimal number > 0xffffffff non-portable

(W portable) The hexadecimal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

Identifier too long

(F) Perl limits identifiers (names for variables, functions, etc.) to about 250 characters for simple names, and somewhat more for compound names (like $A::B). You've exceeded Perl's limits. Future versions of Perl are likely to eliminate these arbitrary limitations.

Illegal binary digit %s

(F) You used a digit other than 0 or 1 in a binary number.

Illegal binary digit %s ignored

(W digit) You may have tried to use a digit other than 0 or 1 in a binary number. Interpretation of the binary number stopped before the offending digit.

Illegal character %s (carriage return)

(F) Perl normally treats carriage returns in the program text as it would any other whitespace, which means you should never see this error when Perl was built using standard options. For some reason, your version of Perl appears to have been built without this support. Talk to your Perl administrator.

Illegal character in prototype for %s : %s

(W syntax) An illegal character was found in a prototype declaration. Legal characters in prototypes are $, @, %, *, ;, [, ], &, and \.

Illegal declaration of anonymous subroutine

(F) When using the sub keyword to construct an anonymous subroutine, you must always specify a block of code. See the perlsub manpage.

Illegal declaration of subroutine %s

(F) A subroutine was not declared correctly. See the perlsub manpage.

Illegal division by zero

(F) You tried to divide a number by 0. Either something was wrong in your logic, or you need to put a conditional in to guard against meaningless input.

Illegal hexadecimal digit %s ignored

(W digit) You may have tried to use a character other than 0 - 9 or A - F, a - f in a hexadecimal number. Interpretation of the hexadecimal number stopped before the illegal character.

Illegal modulus zero

(F) You tried to divide a number by 0 to get the remainder. Most numbers don't take to this kindly.

Illegal number of bits in vec

(F) The number of bits in vec() (the third argument) must be a power of two from 1 to 32 (or 64, if your platform supports that).

Illegal octal digit %s

(F) You used an 8 or 9 in an octal number.

Illegal octal digit %s ignored

(W digit) You may have tried to use an 8 or 9 in an octal number. Interpretation of the octal number stopped before the 8 or 9.

Illegal switch in PERL5OPT: %s

(X) The PERL5OPT environment variable may only be used to set the following switches: -[DIMUdmtw].

Ill-formed CRTL environ value "%s"

(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal environ array, and encountered an element without the = delimiter used to separate keys from values. The element is ignored.

Ill-formed message in prime_env_iter: |%s|

(W internal) A warning peculiar to VMS. Perl tried to read a logical name or CLI symbol definition when preparing to iterate over %ENV, and didn't see the expected delimiter between key and value, so the line was ignored.

(in cleanup) %s

(W misc) This prefix usually indicates that a DESTROY() method raised the indicated exception. Since destructors are usually called by the system at arbitrary points during execution, and often a vast number of times, the warning is issued only once for any number of failures that would otherwise result in the same message being repeated.

Failure of user callbacks dispatched using the G_KEEPERR flag could also result in this warning. See G_KEEPERR in the perlcall manpage.

In EBCDIC the v-string components cannot exceed 2147483647

(F) An error peculiar to EBCDIC. Internally, v-strings are stored as Unicode code points, and encoded in EBCDIC as UTF-EBCDIC. The UTF-EBCDIC encoding is limited to code points no larger than 2147483647 (0x7FFFFFFF).

Insecure dependency in %s

(F) You tried to do something that the tainting mechanism didn't like. The tainting mechanism is turned on when you're running setuid or setgid, or when you specify -T to turn it on explicitly. The tainting mechanism labels all data that's derived directly or indirectly from the user, who is considered to be unworthy of your trust. If any such data is used in a "dangerous" operation, you get this error. See the perlsec manpage for more information.

Insecure directory in %s

(F) You can't use system(), exec(), or a piped open in a setuid or setgid script if $ENV{PATH} contains a directory that is writable by the world. Also, the PATH must not contain any relative directory. See the perlsec manpage.

Insecure $ENV{%s} while running %s

(F) You can't use system(), exec(), or a piped open in a setuid or setgid script if any of $ENV{PATH}, $ENV{IFS}, $ENV{CDPATH}, $ENV{ENV}, $ENV{BASH_ENV} or $ENV{TERM} are derived from data supplied (or potentially supplied) by the user. The script must set the path to a known value, using trustworthy data. See the perlsec manpage.

Integer overflow in %s number

(W overflow) The hexadecimal, octal or binary number you have specified either as a literal or as an argument to hex() or oct() is too big for your architecture, and has been converted to a floating point number. On a 32-bit architecture the largest hexadecimal, octal or binary number representable without overflow is 0xFFFFFFFF, 037777777777, or 0b11111111111111111111111111111111 respectively. Note that Perl transparently promotes all numbers to a floating point representation internally--subject to loss of precision errors in subsequent operations.

Internal disaster in regex; marked by <-- HERE in m/%s/

(P) Something went badly wrong in the regular expression parser. The <-- HERE shows in the regular expression about where the problem was discovered.

Internal inconsistency in tracking vforks

(S) A warning peculiar to VMS. Perl keeps track of the number of times you've called fork and exec, to determine whether the current call to exec should affect the current script or a subprocess (see exec LIST in the perlvms manpage). Somehow, this count has become scrambled, so Perl is making a guess and treating this exec as a request to terminate the Perl script and execute the specified command.

Internal urp in regex; marked by <-- HERE in m/%s/

(P) Something went badly awry in the regular expression parser. The <-- HERE shows in the regular expression about where the problem was discovered.

%s (...) interpreted as function

(W syntax) You've run afoul of the rule that says that any list operator followed by parentheses turns into a function, with all the list operators arguments found inside the parentheses. See Terms and List Operators (Leftward) in the perlop manpage.

Invalid %s attribute: %s

The indicated attribute for a subroutine or variable was not recognized by Perl or by a user-supplied handler. See the attributes manpage.

Invalid %s attributes: %s

The indicated attributes for a subroutine or variable were not recognized by Perl or by a user-supplied handler. See the attributes manpage.

Invalid conversion in %s: "%s"

(W printf) Perl does not understand the given format conversion. See sprintf in the perlfunc manpage.

Invalid [] range "%s" in regex; marked by <-- HERE in m/%s/

(F) The range specified in a character class had a minimum character greater than the maximum character. One possibility is that you forgot the {} from your ending \x{} - \x without the curly braces can go only up to ff. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Invalid range "%s" in transliteration operator

(F) The range specified in the tr/// or y/// operator had a minimum character greater than the maximum character. See the perlop manpage.

Invalid separator character %s in attribute list

(F) Something other than a colon or whitespace was seen between the elements of an attribute list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon. See the attributes manpage.

Invalid separator character %s in PerlIO layer specification %s

(W layer) When pushing layers onto the Perl I/O system, something other than a colon or whitespace was seen between the elements of a layer list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon.

Invalid type '%s' in %s

(F) The given character is not a valid pack or unpack type. See pack in the perlfunc manpage. (W) The given character is not a valid pack or unpack type but used to be silently ignored.

ioctl is not implemented

(F) Your machine apparently doesn't implement ioctl(), which is pretty strange for a machine that supports C.

ioctl() on unopened %s

(W unopened) You tried ioctl() on a filehandle that was never opened. Check you control flow and number of arguments.

IO layers (like "%s") unavailable

(F) Your Perl has not been configured to have PerlIO, and therefore you cannot use IO layers. To have PerlIO Perl must be configured with 'useperlio'.

IO::Socket::atmark not implemented on this architecture

(F) Your machine doesn't implement the sockatmark() functionality, neither as a system call or an ioctl call (SIOCATMARK).

`%s' is not a code reference

(W overload) The second (fourth, sixth, ...) argument of overload::constant needs to be a code reference. Either an anonymous subroutine, or a reference to a subroutine.

`%s' is not an overloadable type

(W overload) You tried to overload a constant type the overload package is unaware of.

junk on end of regexp

(P) The regular expression parser is confused.

Label not found for "last %s"

(F) You named a loop to break out of, but you're not currently in a loop of that name, not even if you count where you were called from. See last in the perlfunc manpage.

Label not found for "next %s"

(F) You named a loop to continue, but you're not currently in a loop of that name, not even if you count where you were called from. See last in the perlfunc manpage.

Label not found for "redo %s"

(F) You named a loop to restart, but you're not currently in a loop of that name, not even if you count where you were called from. See last in the perlfunc manpage.

leaving effective %s failed

(F) While under the use filetest pragma, switching the real and effective uids or gids failed.

length/code after end of string in unpack

(F) While unpacking, the string buffer was already used up when an unpack length/code combination tried to obtain more data. This results in an undefined value for the length. See pack in the perlfunc manpage.

listen() on closed socket %s

(W closed) You tried to do a listen on a closed socket. Did you forget to check the return value of your socket() call? See listen in the perlfunc manpage.

Lookbehind longer than %d not implemented in regex; marked by <-- HERE in m/%s/

(F) There is currently a limit on the length of string which lookbehind can handle. This restriction may be eased in a future release. The <-- HERE shows in the regular expression about where the problem was discovered.

lstat() on filehandle %s

(W io) You tried to do an lstat on a filehandle. What did you mean by that? lstat() makes sense only on filenames. (Perl did a fstat() instead on the filehandle.)

Lvalue subs returning %s not implemented yet

(F) Due to limitations in the current implementation, array and hash values cannot be returned in subroutines used in lvalue context. See Lvalue subroutines in the perlsub manpage.

Malformed integer in [] in pack

(F) Between the brackets enclosing a numeric repeat count only digits are permitted. See pack in the perlfunc manpage.

Malformed integer in [] in unpack

(F) Between the brackets enclosing a numeric repeat count only digits are permitted. See pack in the perlfunc manpage.

Malformed PERLLIB_PREFIX

(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form

    prefix1;prefix2

or prefix1 prefix2

with nonempty prefix1 and prefix2. If prefix1 is indeed a prefix of a builtin library search path, prefix2 is substituted. The error may appear if components are not found, or are too long. See "PERLLIB_PREFIX" in the perlos2 manpage.

Malformed prototype for %s: %s

(F) You tried to use a function with a malformed prototype. The syntax of function prototypes is given a brief compile-time check for obvious errors like invalid characters. A more rigorous check is run when the function is called.

Malformed UTF-8 character (%s)

(S utf8) (F) Perl detected something that didn't comply with UTF-8 encoding rules.

One possible cause is that you read in data that you thought to be in UTF-8 but it wasn't (it was for example legacy 8-bit data). Another possibility is careless use of utf8::upgrade().

Malformed UTF-16 surrogate

Perl thought it was reading UTF-16 encoded character data but while doing it Perl met a malformed Unicode surrogate.

%s matches null string many times in regex; marked by <-- HERE in m/%s/

(W regexp) The pattern you've specified would be an infinite loop if the regular expression engine didn't specifically check for that. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

"%s" may clash with future reserved word

(W) This warning may be due to running a perl5 script through a perl4 interpreter, especially if the word that is being warned about is "use" or "my".

% may not be used in pack

(F) You can't pack a string by supplying a checksum, because the checksumming process loses information, and you can't go the other way. See unpack in the perlfunc manpage.

Method for operation %s not found in package %s during blessing

(F) An attempt was made to specify an entry in an overloading table that doesn't resolve to a valid subroutine. See the overload manpage.

Method %s not permitted

See Server error.

Might be a runaway multi-line %s string starting on line %d

(S) An advisory indicating that the previous error may have been caused by a missing delimiter on a string or pattern, because it eventually ended earlier on the current line.

Misplaced _ in number

(W syntax) An underscore (underbar) in a numeric constant did not separate two digits.

Missing argument to -%c

(F) The argument to the indicated command line switch must follow immediately after the switch, without intervening spaces.

Missing %sbrace%s on \N{}

(F) Wrong syntax of character name literal \N{charname} within double-quotish context.

Missing comma after first argument to %s function

(F) While certain functions allow you to specify a filehandle or an "indirect object" before the argument list, this ain't one of them.

Missing command in piped open

(W pipe) You used the open(FH, "| command") or open(FH, "command |") construction, but the command was missing or blank.

Missing control char name in \c

(F) A double-quoted string ended with "\c", without the required control character name.

Missing name in "my sub"

(F) The reserved syntax for lexically scoped subroutines requires that they have a name with which they can be found.

Missing $ on loop variable

(F) Apparently you've been programming in csh too much. Variables are always mentioned with the $ in Perl, unlike in the shells, where it can vary from one line to the next.

(Missing operator before %s?)

(S syntax) This is an educated guess made in conjunction with the message "%s found where operator expected". Often the missing operator is a comma.

Missing right brace on %s

(F) Missing right brace in \p{...} or \P{...}.

Missing right curly or square bracket

(F) The lexer counted more opening curly or square brackets than closing ones. As a general rule, you'll find it's missing near the place you were last editing.

(Missing semicolon on previous line?)

(S syntax) This is an educated guess made in conjunction with the message "%s found where operator expected". Don't automatically put a semicolon on the previous line just because you saw this message.

Modification of a read-only value attempted

(F) You tried, directly or indirectly, to change the value of a constant. You didn't, of course, try "2 = 1", because the compiler catches that. But an easy way to do the same thing is:

    sub mod { $_[0] = 1 }
    mod(2);

Another way is to assign to a substr() that's off the end of the string.

Yet another way is to assign to a foreach loop VAR when VAR is aliased to a constant in the look LIST:

        $x = 1;
        foreach my $n ($x, 2) {
            $n *= 2; # modifies the $x, but fails on attempt to modify the 2
        }
Modification of non-creatable array value attempted, %s

(F) You tried to make an array value spring into existence, and the subscript was probably negative, even counting from end of the array backwards.

Modification of non-creatable hash value attempted, %s

(P) You tried to make a hash value spring into existence, and it couldn't be created for some peculiar reason.

Module name must be constant

(F) Only a bare module name is allowed as the first argument to a "use".

Module name required with -%c option

(F) The -M or -m options say that Perl should load some module, but you omitted the name of the module. Consult the perlrun manpage for full details about -M and -m.

More than one argument to open

(F) The open function has been asked to open multiple files. This can happen if you are trying to open a pipe to a command that takes a list of arguments, but have forgotten to specify a piped open mode. See open in the perlfunc manpage for details.

msg%s not implemented

(F) You don't have System V message IPC on your system.

Multidimensional syntax %s not supported

(W syntax) Multidimensional arrays aren't written like $foo[1,2,3]. They're written like $foo[1][2][3], as in C.

'/' must be followed by 'a*', 'A*' or 'Z*'

(F) You had a pack template indicating a counted-length string, Currently the only things that can have their length counted are a*, A* or Z*. See pack in the perlfunc manpage.

'/' must follow a numeric type in unpack

(F) You had an unpack template that contained a '/', but this did not follow some unpack specification producing a numeric value. See pack in the perlfunc manpage.

"my sub" not yet implemented

(F) Lexically scoped subroutines are not yet implemented. Don't try that yet.

"my" variable %s can't be in a package

(F) Lexically scoped variables aren't in a package, so it doesn't make sense to try to declare one with a package qualifier on the front. Use local() if you want to localize a package variable.

Name "%s::%s" used only once: possible typo

(W once) Typographical errors often show up as unique variable names. If you had a good reason for having a unique name, then just mention it again somehow to suppress the message. The our declaration is provided for this purpose.

NOTE: This warning detects symbols that have been used only once so $c, @c, %c, *c, &c, sub c{}, c(), and c (the filehandle or format) are considered the same; if a program uses $c only once but also uses any of the others it will not trigger this warning.

Negative '/' count in unpack

(F) The length count obtained from a length/code unpack operation was negative. See pack in the perlfunc manpage.

Negative length

(F) You tried to do a read/write/send/recv operation with a buffer length that is less than 0. This is difficult to imagine.

Negative offset to vec in lvalue context

(F) When vec is called in an lvalue context, the second argument must be greater than or equal to zero.

Nested quantifiers in regex; marked by <-- HERE in m/%s/

(F) You can't quantify a quantifier without intervening parentheses. So things like ** or +* or ?* are illegal. The <-- HERE shows in the regular expression about where the problem was discovered.

Note that the minimal matching quantifiers, *?, +?, and ?? appear to be nested quantifiers, but aren't. See the perlre manpage.

%s never introduced

(S internal) The symbol in question was declared but somehow went out of scope before it could possibly have been used.

Newline in left-justified string for %s

(W printf) There is a newline in a string to be left justified by printf or sprintf.

The padding spaces will appear after the newline, which is probably not what you wanted. Usually you should remove the newline from the string and put formatting characters in the sprintf format.

No %s allowed while running setuid

(F) Certain operations are deemed to be too insecure for a setuid or setgid script to even be allowed to attempt. Generally speaking there will be another way to do what you want that is, if not secure, at least securable. See the perlsec manpage.

No comma allowed after %s

(F) A list operator that has a filehandle or "indirect object" is not allowed to have a comma between that and the following arguments. Otherwise it'd be just another one of the arguments.

One possible cause for this is that you expected to have imported a constant to your name space with use or import while no such importing took place, it may for example be that your operating system does not support that particular constant. Hopefully you did use an explicit import list for the constants you expect to see, please see use in the perlfunc manpage and import in the perlfunc manpage. While an explicit import list would probably have caught this error earlier it naturally does not remedy the fact that your operating system still does not support that constant. Maybe you have a typo in the constants of the symbol import list of use or import or in the constant name at the line where this error was triggered?

No command into which to pipe on command line

(F) An error peculiar to VMS. Perl handles its own command line redirection, and found a '|' at the end of the command line, so it doesn't know where you want to pipe the output from this command.

No DB::DB routine defined

(F) The currently executing code was compiled with the -d switch, but for some reason the current debugger (e.g. perl5db.pl or a Devel:: module) didn't define a routine to be called at the beginning of each statement.

No dbm on this machine

(P) This is counted as an internal error, because every machine should supply dbm nowadays, because Perl comes with SDBM. See the SDBM_File manpage.

No DB::sub routine defined

(F) The currently executing code was compiled with the -d switch, but for some reason the current debugger (e.g. perl5db.pl or a Devel:: module) didn't define a DB::sub routine to be called at the beginning of each ordinary subroutine call.

No -e allowed in setuid scripts

(F) A setuid script can't be specified by the user.

No error file after 2> or 2>> on command line

(F) An error peculiar to VMS. Perl handles its own command line redirection, and found a '2>' or a '2>>' on the command line, but can't find the name of the file to which to write data destined for stderr.

No group ending character '%c' found in template

(F) A pack or unpack template has an opening '(' or '[' without its matching counterpart. See pack in the perlfunc manpage.

No input file after < on command line

(F) An error peculiar to VMS. Perl handles its own command line redirection, and found a '<' on the command line, but can't find the name of the file from which to read data for stdin.

No #! line

(F) The setuid emulator requires that scripts have a well-formed #! line even on machines that don't support the #! construct.

"no" not allowed in expression

(F) The "no" keyword is recognized and executed at compile time, and returns no useful value. See the perlmod manpage.

No output file after > on command line

(F) An error peculiar to VMS. Perl handles its own command line redirection, and found a lone '>' at the end of the command line, so it doesn't know where you wanted to redirect stdout.

No output file after > or >> on command line

(F) An error peculiar to VMS. Perl handles its own command line redirection, and found a '>' or a '>>' on the command line, but can't find the name of the file to which to write data destined for stdout.

No package name allowed for variable %s in "our"

(F) Fully qualified variable names are not allowed in "our" declarations, because that doesn't make much sense under existing semantics. Such syntax is reserved for future extensions.

No Perl script found in input

(F) You called perl -x, but no line was found in the file beginning with #! and containing the word "perl".

No setregid available

(F) Configure didn't find anything resembling the setregid() call for your system.

No setreuid available

(F) Configure didn't find anything resembling the setreuid() call for your system.

No %s specified for -%c

(F) The indicated command line switch needs a mandatory argument, but you haven't specified one.

No such class %s

(F) You provided a class qualifier in a "my" or "our" declaration, but this class doesn't exist at this point in your program.

No such pipe open

(P) An error peculiar to VMS. The internal routine my_pclose() tried to close a pipe which hadn't been opened. This should have been caught earlier as an attempt to close an unopened filehandle.

No such pseudo-hash field "%s"

(F) You tried to access an array as a hash, but the field name used is not defined. The hash at index 0 should map all valid field names to array indices for that to work.

No such pseudo-hash field "%s" in variable %s of type %s

(F) You tried to access a field of a typed variable where the type does not know about the field name. The field names are looked up in the %FIELDS hash in the type package at compile time. The %FIELDS hash is %usually set up with the 'fields' pragma.

No such signal: SIG%s

(W signal) You specified a signal name as a subscript to %SIG that was not recognized. Say kill -l in your shell to see the valid signal names on your system.

Not a CODE reference

(F) Perl was trying to evaluate a reference to a code value (that is, a subroutine), but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See also the perlref manpage.

Not a format reference

(F) I'm not sure how you managed to generate a reference to an anonymous format, but this indicates you did, and that it didn't exist.

Not a GLOB reference

(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a symbol table entry that looks like *foo), but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See the perlref manpage.

Not a HASH reference

(F) Perl was trying to evaluate a reference to a hash value, but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See the perlref manpage.

Not an ARRAY reference

(F) Perl was trying to evaluate a reference to an array value, but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See the perlref manpage.

Not a perl script

(F) The setuid emulator requires that scripts have a well-formed #! line even on machines that don't support the #! construct. The line must mention perl.

Not a SCALAR reference

(F) Perl was trying to evaluate a reference to a scalar value, but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See the perlref manpage.

Not a subroutine reference

(F) Perl was trying to evaluate a reference to a code value (that is, a subroutine), but found a reference to something else instead. You can use the ref() function to find out what kind of ref it really was. See also the perlref manpage.

Not a subroutine reference in overload table

(F) An attempt was made to specify an entry in an overloading table that doesn't somehow point to a valid subroutine. See the overload manpage.

Not enough arguments for %s

(F) The function requires more arguments than you specified.

Not enough format arguments

(W syntax) A format specified more picture fields than the next line supplied. See the perlform manpage.

%s: not found

(A) You've accidentally run your script through the Bourne shell instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

no UTC offset information; assuming local time is UTC

(S) A warning peculiar to VMS. Perl was unable to find the local timezone offset, so it's assuming that local system time is equivalent to UTC. If it's not, define the logical name SYS$TIMEZONE_DIFFERENTIAL to translate to the number of seconds which need to be added to UTC to get local time.

Non-string passed as bitmask

(W misc) A number has been passed as a bitmask argument to select(). Use the vec() function to construct the file descriptor bitmasks for select. See select in the perlfunc manpage

Null filename used

(F) You can't require the null filename, especially because on many machines that means the current directory! See require in the perlfunc manpage.

NULL OP IN RUN

(P debugging) Some internal routine called run() with a null opcode pointer.

Null picture in formline

(F) The first argument to formline must be a valid format picture specification. It was found to be empty, which probably means you supplied it an uninitialized value. See the perlform manpage.

Null realloc

(P) An attempt was made to realloc NULL.

NULL regexp argument

(P) The internal pattern matching routines blew it big time.

NULL regexp parameter

(P) The internal pattern matching routines are out of their gourd.

Number too long

(F) Perl limits the representation of decimal numbers in programs to about 250 characters. You've exceeded that length. Future versions of Perl are likely to eliminate this arbitrary limitation. In the meantime, try using scientific notation (e.g. "1e6" instead of "1_000_000").

Octal number in vector unsupported

(F) Numbers with a leading 0 are not currently allowed in vectors. The octal number interpretation of such numbers may be supported in a future version.

Octal number > 037777777777 non-portable

(W portable) The octal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

See also the perlport manpage for writing portable code.

Odd number of arguments for overload::constant

(W overload) The call to overload::constant contained an odd number of arguments. The arguments should come in pairs.

Odd number of elements in anonymous hash

(W misc) You specified an odd number of elements to initialize a hash, which is odd, because hashes come in key/value pairs.

Odd number of elements in hash assignment

(W misc) You specified an odd number of elements to initialize a hash, which is odd, because hashes come in key/value pairs.

Offset outside string

(F) You tried to do a read/write/send/recv operation with an offset pointing outside the buffer. This is difficult to imagine. The sole exception to this is that sysread()ing past the buffer will extend the buffer and zero pad the new area.

%s() on unopened %s

(W unopened) An I/O operation was attempted on a filehandle that was never initialized. You need to do an open(), a sysopen(), or a socket() call, or call a constructor from the FileHandle package.

-%s on unopened filehandle %s

(W unopened) You tried to invoke a file test operator on a filehandle that isn't open. Check your control flow. See also -X in the perlfunc manpage.

oops: oopsAV

(S internal) An internal warning that the grammar is screwed up.

oops: oopsHV

(S internal) An internal warning that the grammar is screwed up.

Operation "%s": no method found, %s

(F) An attempt was made to perform an overloaded operation for which no handler was defined. While some handlers can be autogenerated in terms of other handlers, there is no default handler for any operation, unless fallback overloading key is specified to be true. See the overload manpage.

Operator or semicolon missing before %s

(S ambiguous) You used a variable or subroutine call where the parser was expecting an operator. The parser has assumed you really meant to use an operator, but this is highly likely to be incorrect. For example, if you say "*foo *foo" it will be interpreted as if you said "*foo * 'foo'".

"our" variable %s redeclared

(W misc) You seem to have already declared the same global once before in the current lexical scope.

Out of memory!

(X) The malloc() function returned 0, indicating there was insufficient remaining memory (or virtual memory) to satisfy the request. Perl has no option but to exit immediately.

At least in Unix you may be able to get past this by increasing your process datasize limits: in csh/tcsh use limit and limit datasize n (where n is the number of kilobytes) to check the current limits and change them, and in ksh/bash/zsh use ulimit -a and ulimit -d n, respectively.

Out of memory during %s extend

(X) An attempt was made to extend an array, a list, or a string beyond the largest possible memory allocation.

Out of memory during "large" request for %s

(F) The malloc() function returned 0, indicating there was insufficient remaining memory (or virtual memory) to satisfy the request. However, the request was judged large enough (compile-time default is 64K), so a possibility to shut down by trapping this error is granted.

Out of memory during request for %s

(X|F) The malloc() function returned 0, indicating there was insufficient remaining memory (or virtual memory) to satisfy the request.

The request was judged to be small, so the possibility to trap it depends on the way perl was compiled. By default it is not trappable. However, if compiled for this, Perl may use the contents of $^M as an emergency pool after die()ing with this message. In this case the error is trappable once, and the error message will include the line and file where the failed request happened.

Out of memory during ridiculously large request

(F) You can't allocate more than 2^31+"small amount" bytes. This error is most likely to be caused by a typo in the Perl program. e.g., $arr[time] instead of $arr[$time].

Out of memory for yacc stack

(F) The yacc parser wanted to grow its stack so it could continue parsing, but realloc() wouldn't give it more memory, virtual or otherwise.

'@' outside of string in unpack

(F) You had a template that specified an absolute position outside the string being unpacked. See pack in the perlfunc manpage.

%s package attribute may clash with future reserved word: %s

(W reserved) A lowercase attribute name was used that had a package-specific handler. That name might have a meaning to Perl itself some day, even though it doesn't yet. Perhaps you should use a mixed-case attribute name, instead. See the attributes manpage.

pack/unpack repeat count overflow

(F) You can't specify a repeat count so large that it overflows your signed integers. See pack in the perlfunc manpage.

page overflow

(W io) A single call to write() produced more lines than can fit on a page. See the perlform manpage.

panic: %s

(P) An internal error.

panic: ck_grep

(P) Failed an internal consistency check trying to compile a grep.

panic: ck_split

(P) Failed an internal consistency check trying to compile a split.

panic: corrupt saved stack index

(P) The savestack was requested to restore more localized values than there are in the savestack.

panic: del_backref

(P) Failed an internal consistency check while trying to reset a weak reference.

panic: Devel::DProf inconsistent subroutine return

(P) Devel::DProf called a subroutine that exited using goto(LABEL), last(LABEL) or next(LABEL). Leaving that way a subroutine called from an XSUB will lead very probably to a crash of the interpreter. This is a bug that will hopefully one day get fixed.

panic: die %s

(P) We popped the context stack to an eval context, and then discovered it wasn't an eval context.

panic: do_subst

(P) The internal pp_subst() routine was called with invalid operational data.

panic: do_trans_%s

(P) The internal do_trans routines were called with invalid operational data.

panic: frexp

(P) The library function frexp() failed, making printf("%f") impossible.

panic: goto

(P) We popped the context stack to a context with the specified label, and then discovered it wasn't a context we know how to do a goto in.

panic: INTERPCASEMOD

(P) The lexer got into a bad state at a case modifier.

panic: INTERPCONCAT

(P) The lexer got into a bad state parsing a string with brackets.

panic: kid popen errno read

(F) forked child returned an incomprehensible message about its errno.

panic: last

(P) We popped the context stack to a block context, and then discovered it wasn't a block context.

panic: leave_scope clearsv

(P) A writable lexical variable became read-only somehow within the scope.

panic: leave_scope inconsistency

(P) The savestack probably got out of sync. At least, there was an invalid enum on the top of it.

panic: magic_killbackrefs

(P) Failed an internal consistency check while trying to reset all weak references to an object.

panic: malloc

(P) Something requested a negative number of bytes of malloc.

panic: mapstart

(P) The compiler is screwed up with respect to the map() function.

panic: memory wrap

(P) Something tried to allocate more memory than possible.

panic: null array

(P) One of the internal array routines was passed a null AV pointer.

panic: pad_alloc

(P) The compiler got confused about which scratch pad it was allocating and freeing temporaries and lexicals from.

panic: pad_free curpad

(P) The compiler got confused about which scratch pad it was allocating and freeing temporaries and lexicals from.

panic: pad_free po

(P) An invalid scratch pad offset was detected internally.

panic: pad_reset curpad

(P) The compiler got confused about which scratch pad it was allocating and freeing temporaries and lexicals from.

panic: pad_sv po

(P) An invalid scratch pad offset was detected internally.

panic: pad_swipe curpad

(P) The compiler got confused about which scratch pad it was allocating and freeing temporaries and lexicals from.

panic: pad_swipe po

(P) An invalid scratch pad offset was detected internally.

panic: pp_iter

(P) The foreach iterator got called in a non-loop context frame.

panic: pp_match%s

(P) The internal pp_match() routine was called with invalid operational data.

panic: pp_split

(P) Something terrible went wrong in setting up for the split.

panic: realloc

(P) Something requested a negative number of bytes of realloc.

panic: restartop

(P) Some internal routine requested a goto (or something like it), and didn't supply the destination.

panic: return

(P) We popped the context stack to a subroutine or eval context, and then discovered it wasn't a subroutine or eval context.

panic: scan_num

(P) scan_num() got called on something that wasn't a number.

panic: sv_insert

(P) The sv_insert() routine was told to remove more string than there was string.

panic: top_env

(P) The compiler attempted to do a goto, or something weird like that.

panic: utf16_to_utf8: odd bytelen

(P) Something tried to call utf16_to_utf8 with an odd (as opposed to even) byte length.

panic: yylex

(P) The lexer got into a bad state while processing a case modifier.

Parentheses missing around "%s" list

(W parenthesis) You said something like

    my $foo, $bar = @_;

when you meant

    my ($foo, $bar) = @_;

Remember that "my", "our", and "local" bind tighter than comma.

-p destination: %s

(F) An error occurred during the implicit output invoked by the -p command-line switch. (This output goes to STDOUT unless you've redirected it with select().)

(perhaps you forgot to load "%s"?)

(F) This is an educated guess made in conjunction with the message "Can't locate object method \"%s\" via package \"%s\"". It often means that a method requires a package that has not been loaded.

Perl %s required--this is only version %s, stopped

(F) The module in question uses features of a version of Perl more recent than the currently running version. How long has it been since you upgraded, anyway? See require in the perlfunc manpage.

PERL_SH_DIR too long

(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the sh-shell in. See "PERL_SH_DIR" in the perlos2 manpage.

PERL_SIGNALS illegal: "%s"

See PERL_SIGNALS in the perlrun manpage for legal values.

perl: warning: Setting locale failed.

(S) The whole warning message will look something like:

        perl: warning: Setting locale failed.
        perl: warning: Please check that your locale settings:
                LC_ALL = "En_US",
                LANG = (unset)
            are supported and installed on your system.
        perl: warning: Falling back to the standard locale ("C").

Exactly what were the failed locale settings varies. In the above the settings were that the LC_ALL was "En_US" and the LANG had no value. This error means that Perl detected that you and/or your operating system supplier and/or system administrator have set up the so-called locale system but Perl could not use those settings. This was not dead serious, fortunately: there is a "default locale" called "C" that Perl can and will use, the script will be run. Before you really fix the problem, however, you will get the same error message each time you run Perl. How to really fix the problem can be found in the perllocale manpage section LOCALE PROBLEMS.

Permission denied

(F) The setuid emulator in suidperl decided you were up to no good.

pid %x not a child

(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a process which isn't a subprocess of the current process. While this is fine from VMS' perspective, it's probably not what you intended.

'P' must have an explicit size in unpack

(F) The unpack format P must have an explicit size, not "*".

-P not allowed for setuid/setgid script

(F) The script would have to be opened by the C preprocessor by name, which provides a race condition that breaks security.

POSIX class [:%s:] unknown in regex; marked by <-- HERE in m/%s/

(F) The class in the character class [: :] syntax is unknown. The <-- HERE shows in the regular expression about where the problem was discovered. Note that the POSIX character classes do not have the is prefix the corresponding C interfaces have: in other words, it's [[:print:]], not isprint. See the perlre manpage.

POSIX getpgrp can't take an argument

(F) Your system has POSIX getpgrp(), which takes no argument, unlike the BSD version, which takes a pid.

POSIX syntax [%s] belongs inside character classes in regex; marked by <-- HERE in m/%s/

(W regexp) The character class constructs [: :], [= =], and [. .] go inside character classes, the [] are part of the construct, for example: /[012[:alpha:]345]/. Note that [= =] and [. .] are not currently implemented; they are simply placeholders for future extensions and will cause fatal errors. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

POSIX syntax [. .] is reserved for future extensions in regex; marked by <-- HERE in m/%s/

(F regexp) Within regular expression character classes ([]) the syntax beginning with "[." and ending with ".]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[." and ".\]". The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

POSIX syntax [= =] is reserved for future extensions in regex; marked by <-- HERE in m/%s/

(F) Within regular expression character classes ([]) the syntax beginning with "[=" and ending with "=]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[=" and "=\]". The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Possible attempt to put comments in qw() list

(W qw) qw() lists contain items separated by whitespace; as with literal strings, comment characters are not ignored, but are instead treated as literal data. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.)

You probably wrote something like this:

    @list = qw(
        a # a comment
        b # another comment
    );

when you should have written this:

    @list = qw(
        a
        b
    );

If you really want comments, build your list the old-fashioned way, with quotes and commas:

    @list = (
        'a',    # a comment
        'b',    # another comment
    );
Possible attempt to separate words with commas

(W qw) qw() lists contain items separated by whitespace; therefore commas aren't needed to separate the items. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.)

You probably wrote something like this:

    qw! a, b, c !;

which puts literal commas into some of the list items. Write it without commas if you don't want them to appear in your data:

    qw! a b c !;
Possible memory corruption: %s overflowed 3rd argument

(F) An ioctl() or fcntl() returned more than Perl was bargaining for. Perl guesses a reasonable buffer size, but puts a sentinel byte at the end of the buffer just in case. This sentinel byte got clobbered, and Perl assumes that memory is now corrupted. See ioctl in the perlfunc manpage.

Possible precedence problem on bitwise %c operator

(W precedence) Your program uses a bitwise logical operator in conjunction with a numeric comparison operator, like this :

    if ($x & $y == 0) { ... }

This expression is actually equivalent to $x & ($y == 0), due to the higher precedence of ==. This is probably not what you want. (If you really meant to write this, disable the warning, or, better, put the parentheses explicitly and write $x & ($y == 0)).

Possible unintended interpolation of %s in string

(W ambiguous) You said something like `@foo' in a double-quoted string but there was no array @foo in scope at the time. If you wanted a literal @foo, then write it as \@foo; otherwise find out what happened to the array you apparently lost track of.

Possible Y2K bug: %s

(W y2k) You are concatenating the number 19 with another number, which could be a potential Year 2000 problem.

pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead

(D deprecated) You have written something like this:

    sub doit
    {
        use attrs qw(locked);
    }

You should use the new declaration syntax instead.

    sub doit : locked
    {
        ...

The use attrs pragma is now obsolete, and is only provided for backward-compatibility. See Subroutine Attributes in the perlsub manpage.

Precedence problem: open %s should be open(%s)

(S precedence) The old irregular construct

    open FOO || die;

is now misinterpreted as

    open(FOO || die);

because of the strict regularization of Perl 5's grammar into unary and list operators. (The old open was a little of both.) You must put parentheses around the filehandle, or use the new "or" operator instead of "||".

Premature end of script headers

See Server error.

printf() on closed filehandle %s

(W closed) The filehandle you're writing to got itself closed sometime before now. Check your control flow.

print() on closed filehandle %s

(W closed) The filehandle you're printing on got itself closed sometime before now. Check your control flow.

Process terminated by SIG%s

(W) This is a standard message issued by OS/2 applications, while *nix applications die in silence. It is considered a feature of the OS/2 port. One can easily disable this by appropriate sighandlers, see Signals in the perlipc manpage. See also "Process terminated by SIGTERM/SIGINT" in the perlos2 manpage.

Prototype mismatch: %s vs %s

(S prototype) The subroutine being declared or defined had previously been declared or defined with a different function prototype.

Prototype not terminated

(F) You've omitted the closing parenthesis in a function prototype definition.

Pseudo-hashes are deprecated

(D deprecated) Pseudo-hashes were deprecated in Perl 5.8.0 and they will be removed in Perl 5.10.0, see the perl58delta manpage for more details. You can continue to use the fields pragma.

Quantifier follows nothing in regex; marked by <-- HERE in m/%s/

(F) You started a regular expression with a quantifier. Backslash it if you meant it literally. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Quantifier in {,} bigger than %d in regex; marked by <-- HERE in m/%s/

(F) There is currently a limit to the size of the min and max values of the {min,max} construct. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Quantifier unexpected on zero-length expression; marked by <-- HERE in m/%s/

(W regexp) You applied a regular expression quantifier in a place where it makes no sense, such as on a zero-width assertion. Try putting the quantifier inside the assertion instead. For example, the way to match "abc" provided that it is followed by three repetitions of "xyz" is /abc(?=(?:xyz){3})/, not /abc(?=xyz){3}/.

The <-- HERE shows in the regular expression about where the problem was discovered.

Range iterator outside integer range

(F) One (or both) of the numeric arguments to the range operator ".." are outside the range which can be represented by integers internally. One possible workaround is to force Perl to use magical string increment by prepending "0" to your numbers.

readline() on closed filehandle %s

(W closed) The filehandle you're reading from got itself closed sometime before now. Check your control flow.

read() on closed filehandle %s

(W closed) You tried to read from a closed filehandle.

read() on unopened filehandle %s

(W unopened) You tried to read from a filehandle that was never opened.

Reallocation too large: %lx

(F) You can't allocate more than 64K on an MS-DOS machine.

realloc() of freed memory ignored

(S malloc) An internal routine called realloc() on something that had already been freed.

Recompile perl with -DDEBUGGING to use -D switch

(F debugging) You can't use the -D option unless the code to produce the desired output is compiled into Perl, which entails some overhead, which is why it's currently left out of your copy.

Recursive inheritance detected in package '%s'

(F) More than 100 levels of inheritance were used. Probably indicates an unintended loop in your inheritance hierarchy.

Recursive inheritance detected while looking for method %s

(F) More than 100 levels of inheritance were encountered while invoking a method. Probably indicates an unintended loop in your inheritance hierarchy.

Reference found where even-sized list expected

(W misc) You gave a single reference where Perl was expecting a list with an even number of elements (for assignment to a hash). This usually means that you used the anon hash constructor when you meant to use parens. In any case, a hash requires key/value pairs.

    %hash = { one => 1, two => 2, };    # WRONG
    %hash = [ qw/ an anon array / ];    # WRONG
    %hash = ( one => 1, two => 2, );    # right
    %hash = qw( one 1 two 2 );                  # also fine
Reference is already weak

(W misc) You have attempted to weaken a reference that is already weak. Doing so has no effect.

Reference miscount in sv_replace()

(W internal) The internal sv_replace() function was handed a new SV with a reference count of other than 1.

Reference to nonexistent group in regex; marked by <-- HERE in m/%s/

(F) You used something like \7 in your regular expression, but there are not at least seven sets of capturing parentheses in the expression. If you wanted to have the character with value 7 inserted into the regular expression, prepend a zero to make the number at least two digits: \07

The <-- HERE shows in the regular expression about where the problem was discovered.

regexp memory corruption

(P) The regular expression engine got confused by what the regular expression compiler gave it.

Regexp out of space

(P) A "can't happen" error, because safemalloc() should have caught it earlier.

Repeated format line will never terminate (~~ and @# incompatible)

(F) Your format contains the ~~ repeat-until-blank sequence and a numeric field that will never go blank so that the repetition never terminates. You might use ^# instead. See the perlform manpage.

Reversed %s= operator

(W syntax) You wrote your assignment operator backwards. The = must always comes last, to avoid ambiguity with subsequent unary operators.

Runaway format

(F) Your format contained the ~~ repeat-until-blank sequence, but it produced 200 lines at once, and the 200th line looked exactly like the 199th line. Apparently you didn't arrange for the arguments to exhaust themselves, either by using ^ instead of @ (for scalar variables), or by shifting or popping (for array variables). See the perlform manpage.

Scalars leaked: %d

(P) Something went wrong in Perl's internal bookkeeping of scalars: not all scalar variables were deallocated by the time Perl exited. What this usually indicates is a memory leak, which is of course bad, especially if the Perl program is intended to be long-running.

Scalar value @%s[%s] better written as $%s[%s]

(W syntax) You've used an array slice (indicated by @) to select a single element of an array. Generally it's better to ask for a scalar value (indicated by $). The difference is that $foo[&bar] always behaves like a scalar, both when assigning to it and when evaluating its argument, while @foo[&bar] behaves like a list when you assign to it, and provides a list context to its subscript, which can do weird things if you're expecting only one subscript.

On the other hand, if you were actually hoping to treat the array element as a list, you need to look into how references work, because Perl will not magically convert between scalars and lists for you. See the perlref manpage.

Scalar value @%s{%s} better written as $%s{%s}

(W syntax) You've used a hash slice (indicated by @) to select a single element of a hash. Generally it's better to ask for a scalar value (indicated by $). The difference is that $foo{&bar} always behaves like a scalar, both when assigning to it and when evaluating its argument, while @foo{&bar} behaves like a list when you assign to it, and provides a list context to its subscript, which can do weird things if you're expecting only one subscript.

On the other hand, if you were actually hoping to treat the hash element as a list, you need to look into how references work, because Perl will not magically convert between scalars and lists for you. See the perlref manpage.

Script is not setuid/setgid in suidperl

(F) Oddly, the suidperl program was invoked on a script without a setuid or setgid bit set. This doesn't make much sense.

Search pattern not terminated

(F) The lexer couldn't find the final delimiter of a // or m{} construct. Remember that bracketing delimiters count nesting level. Missing the leading $ from a variable $m may cause this error.

Note that since Perl 5.9.0 a // can also be the defined-or construct, not just the empty search pattern. Therefore code written in Perl 5.9.0 or later that uses the // as the defined-or can be misparsed by pre-5.9.0 Perls as a non-terminated search pattern.

Search pattern not terminated or ternary operator parsed as search pattern

(F) The lexer couldn't find the final delimiter of a ?PATTERN? construct.

The question mark is also used as part of the ternary operator (as in foo ? 0 : 1) leading to some ambiguous constructions being wrongly parsed. One way to disambiguate the parsing is to put parentheses around the conditional expression, i.e. (foo) ? 0 : 1.

%sseek() on unopened filehandle

(W unopened) You tried to use the seek() or sysseek() function on a filehandle that was either never opened or has since been closed.

select not implemented

(F) This machine doesn't implement the select() system call.

Self-ties of arrays and hashes are not supported

(F) Self-ties are of arrays and hashes are not supported in the current implementation.

Semicolon seems to be missing

(W semicolon) A nearby syntax error was probably caused by a missing semicolon, or possibly some other missing operator, such as a comma.

semi-panic: attempt to dup freed string

(S internal) The internal newSVsv() routine was called to duplicate a scalar that had previously been marked as free.

sem%s not implemented

(F) You don't have System V semaphore IPC on your system.

send() on closed socket %s

(W closed) The socket you're sending to got itself closed sometime before now. Check your control flow.

Sequence (? incomplete in regex; marked by <-- HERE in m/%s/

(F) A regular expression ended with an incomplete extension (?. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Sequence (?%s...) not implemented in regex; marked by <-- HERE in m/%s/

(F) A proposed regular expression extension has the character reserved but has not yet been written. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Sequence (?%s...) not recognized in regex; marked by <-- HERE in m/%s/

(F) You used a regular expression extension that doesn't make sense. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Sequence (?#... not terminated in regex; marked by <-- HERE in m/%s/

(F) A regular expression comment must be terminated by a closing parenthesis. Embedded parentheses aren't allowed. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

Sequence (?{...}) not terminated or not {}-balanced in regex; marked by <-- HERE in m/%s/

(F) If the contents of a (?{...}) clause contains braces, they must balance for Perl to properly detect the end of the clause. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

  • Server error

    See Server error.

    • Server error

    This is the error message generally seen in a browser window when trying to run a CGI program (including SSI) over the web. The actual error text varies widely from server to server. The most frequently-seen variants are "500 Server error", "Method (something) not permitted", "Document contains no data", "Premature end of script headers", and "Did not produce a valid header".

    This is a CGI error, not a Perl error.

    You need to make sure your script is executable, is accessible by the user CGI is running the script under (which is probably not the user account you tested it under), does not rely on any environment variables (like PATH) from the user it isn't running under, and isn't in a location where the CGI server can't find it, basically, more or less. Please see the following for more information:

            http://www.perl.org/CGI_MetaFAQ.html
        http://www.htmlhelp.org/faq/cgifaq.html
        http://www.w3.org/Security/Faq/

    You should also look at the perlfaq9 manpage.

    setegid() not implemented

    (F) You tried to assign to $), and your operating system doesn't support the setegid() system call (or equivalent), or at least Configure didn't think so.

    seteuid() not implemented

    (F) You tried to assign to $>, and your operating system doesn't support the seteuid() system call (or equivalent), or at least Configure didn't think so.

    setpgrp can't take arguments

    (F) Your system has the setpgrp() from BSD 4.2, which takes no arguments, unlike POSIX setpgid(), which takes a process ID and process group ID.

    setrgid() not implemented

    (F) You tried to assign to $(, and your operating system doesn't support the setrgid() system call (or equivalent), or at least Configure didn't think so.

    setruid() not implemented

    (F) You tried to assign to $<, and your operating system doesn't support the setruid() system call (or equivalent), or at least Configure didn't think so.

    setsockopt() on closed socket %s

    (W closed) You tried to set a socket option on a closed socket. Did you forget to check the return value of your socket() call? See setsockopt in the perlfunc manpage.

    Setuid/gid script is writable by world

    (F) The setuid emulator won't run a script that is writable by the world, because the world might have written on it already.

    Setuid script not plain file

    (F) The setuid emulator won't run a script that isn't read from a file, but from a socket, a pipe or another device.

    shm%s not implemented

    (F) You don't have System V shared memory IPC on your system.

    <> should be quotes

    (F) You wrote require <file> when you should have written require 'file'.

    /%s/ should probably be written as "%s"

    (W syntax) You have used a pattern where Perl expected to find a string, as in the first argument to join. Perl will treat the true or false result of matching the pattern against $_ as the string, which is probably not what you had in mind.

    shutdown() on closed socket %s

    (W closed) You tried to do a shutdown on a closed socket. Seems a bit superfluous.

    SIG%s handler "%s" not defined

    (W signal) The signal handler named in %SIG doesn't, in fact, exist. Perhaps you put it into the wrong package?

    sort is now a reserved word

    (F) An ancient error message that almost nobody ever runs into anymore. But before sort was a keyword, people sometimes used it as a filehandle.

    Sort subroutine didn't return a numeric value

    (F) A sort comparison routine must return a number. You probably blew it by not using <=> or cmp, or by not using them correctly. See sort in the perlfunc manpage.

    Sort subroutine didn't return single value

    (F) A sort comparison subroutine may not return a list value with more or less than one element. See sort in the perlfunc manpage.

    splice() offset past end of array

    (W misc) You attempted to specify an offset that was past the end of the array passed to splice(). Splicing will instead commence at the end of the array, rather than past it. If this isn't what you want, try explicitly pre-extending the array by assigning $#array = $offset. See splice in the perlfunc manpage.

    Split loop

    (P) The split was looping infinitely. (Obviously, a split shouldn't iterate more times than there are characters of input, which is what happened.) See split in the perlfunc manpage.

    Statement unlikely to be reached

    (W exec) You did an exec() with some statement after it other than a die(). This is almost always an error, because exec() never returns unless there was a failure. You probably wanted to use system() instead, which does return. To suppress this warning, put the exec() in a block by itself.

    stat() on unopened filehandle %s

    (W unopened) You tried to use the stat() function on a filehandle that was either never opened or has since been closed.

    Stub found while resolving method "%s" overloading "%s"

    (P) Overloading resolution over @ISA tree may be broken by importation stubs. Stubs should never be implicitly created, but explicit calls to can may break this.

    Subroutine %s redefined

    (W redefine) You redefined a subroutine. To suppress this warning, say

        {
        no warnings 'redefine';
        eval "sub name { ... }";
    }
    Substitution loop

    (P) The substitution was looping infinitely. (Obviously, a substitution shouldn't iterate more times than there are characters of input, which is what happened.) See the discussion of substitution in Quote and Quote-like Operators in the perlop manpage.

    Substitution pattern not terminated

    (F) The lexer couldn't find the interior delimiter of an s/// or s{}{} construct. Remember that bracketing delimiters count nesting level. Missing the leading $ from variable $s may cause this error.

    Substitution replacement not terminated

    (F) The lexer couldn't find the final delimiter of an s/// or s{}{} construct. Remember that bracketing delimiters count nesting level. Missing the leading $ from variable $s may cause this error.

    substr outside of string

    (W substr),(F) You tried to reference a substr() that pointed outside of a string. That is, the absolute value of the offset was larger than the length of the string. See substr in the perlfunc manpage. This warning is fatal if substr is used in an lvalue context (as the left hand side of an assignment or as a subroutine argument for example).

    suidperl is no longer needed since %s

    (F) Your Perl was compiled with -DSETUID_SCRIPTS_ARE_SECURE_NOW, but a version of the setuid emulator somehow got run anyway.

    Switch (?(condition)... contains too many branches in regex; marked by <-- HERE in m/%s/

    (F) A (?(condition)if-clause|else-clause) construct can have at most two branches (the if-clause and the else-clause). If you want one or both to contain alternation, such as using this|that|other, enclose it in clustering parentheses:

        (?(condition)(?:this|that|other)|else-clause)

    The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    Switch condition not recognized in regex; marked by <-- HERE in m/%s/

    (F) If the argument to the (?(...)if-clause|else-clause) construct is a number, it can be only a number. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    switching effective %s is not implemented

    (F) While under the use filetest pragma, we cannot switch the real and effective uids or gids.

    %s syntax

    (F) The final summary message when a perl -c succeeds.

    syntax error

    (F) Probably means you had a syntax error. Common reasons include:

        A keyword is misspelled.
    A semicolon is missing.
    A comma is missing.
    An opening or closing parenthesis is missing.
    An opening or closing brace is missing.
    A closing quote is missing.

    Often there will be another error message associated with the syntax error giving more information. (Sometimes it helps to turn on -w.) The error message itself often tells you where it was in the line when it decided to give up. Sometimes the actual error is several tokens before this, because Perl is good at understanding random input. Occasionally the line number may be misleading, and once in a blue moon the only way to figure out what's triggering the error is to call perl -c repeatedly, chopping away half the program each time to see if the error went away. Sort of the cybernetic version of 20 questions.

    syntax error at line %d: `%s' unexpected

    (A) You've accidentally run your script through the Bourne shell instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

    syntax error in file %s at line %d, next 2 tokens "%s"

    (F) This error is likely to occur if you run a perl5 script through a perl4 interpreter, especially if the next 2 tokens are "use strict" or "my $var" or "our $var".

    sysread() on closed filehandle %s

    (W closed) You tried to read from a closed filehandle.

    sysread() on unopened filehandle %s

    (W unopened) You tried to read from a filehandle that was never opened.

    System V %s is not implemented on this machine

    (F) You tried to do something with a function beginning with "sem", "shm", or "msg" but that System V IPC is not implemented in your machine. In some machines the functionality can exist but be unconfigured. Consult your system support.

    syswrite() on closed filehandle %s

    (W closed) The filehandle you're writing to got itself closed sometime before now. Check your control flow.

    -T and -B not implemented on filehandles

    (F) Perl can't peek at the stdio buffer of filehandles when it doesn't know about your kind of stdio. You'll have to use a filename instead.

    Target of goto is too deeply nested

    (F) You tried to use goto to reach a label that was too deeply nested for Perl to reach. Perl is doing you a favor by refusing.

    tell() on unopened filehandle

    (W unopened) You tried to use the tell() function on a filehandle that was either never opened or has since been closed.

    That use of $[ is unsupported

    (F) Assignment to $[ is now strictly circumscribed, and interpreted as a compiler directive. You may say only one of

        $[ = 0;
    $[ = 1;
    ...
    local $[ = 0;
    local $[ = 1;
    ...

    This is to prevent the problem of one module changing the array base out from under another module inadvertently. See $[ in the perlvar manpage.

    The crypt() function is unimplemented due to excessive paranoia

    (F) Configure couldn't find the crypt() function on your machine, probably because your vendor didn't supply it, probably because they think the U.S. Government thinks it's a secret, or at least that they will continue to pretend that it is. And if you quote me on that, I will deny it.

    The %s function is unimplemented

    The function indicated isn't implemented on this architecture, according to the probings of Configure.

    The stat preceding %s wasn't an lstat

    (F) It makes no sense to test the current stat buffer for symbolic linkhood if the last stat that wrote to the stat buffer already went past the symlink to get to the real file. Use an actual filename instead.

    The 'unique' attribute may only be applied to 'our' variables

    (F) Currently this attribute is not supported on my or sub declarations. See our in the perlfunc manpage.

    This Perl can't reset CRTL environ elements (%s)
    This Perl can't set CRTL environ elements (%s=%s)

    (W internal) Warnings peculiar to VMS. You tried to change or delete an element of the CRTL's internal environ array, but your copy of Perl wasn't built with a CRTL that contained the setenv() function. You'll need to rebuild Perl with a CRTL that does, or redefine PERL_ENV_TABLES (see the perlvms manpage) so that the environ array isn't the target of the change to %ENV which produced the warning.

    thread failed to start: %s

    (W threads)(S) The entry point function of threads->create() failed for some reason.

  • 005 threads are deprecated

    (D deprecated) The 5.005-style threads (activated by use Thread;) are deprecated and one should use the new ithreads instead, see the perl58delta manpage for more details.

    • times not implemented

    (F) Your version of the C library apparently doesn't do times(). I suspect you're not running on Unix.

    "-T" is on the #! line, it must also be used on the command line

    (X) The #! line (or local equivalent) in a Perl script contains the -T option, but Perl was not invoked with -T in its command line. This is an error because, by the time Perl discovers a -T in a script, it's too late to properly taint everything from the environment. So Perl gives up.

    If the Perl script is being executed as a command using the #! mechanism (or its local equivalent), this error can usually be fixed by editing the #! line so that the -T option is a part of Perl's first argument: e.g. change perl -n -T to perl -T -n.

    If the Perl script is being executed as perl scriptname, then the -T option must appear on the command line: perl -T scriptname.

    To%s: illegal mapping '%s'

    (F) You tried to define a customized To-mapping for lc(), lcfirst, uc(), or ucfirst() (or their string-inlined versions), but you specified an illegal mapping. See User-Defined Character Properties in the perlunicode manpage.

    Too deeply nested ()-groups

    (F) Your template contains ()-groups with a ridiculously deep nesting level.

    Too few args to syscall

    (F) There has to be at least one argument to syscall() to specify the system call to call, silly dilly.

    Too late for "-%s" option

    (X) The #! line (or local equivalent) in a Perl script contains the -M or -m option. This is an error because -M and -m options are not intended for use inside scripts. Use the use pragma instead.

    Too late to run %s block

    (W void) A CHECK or INIT block is being defined during run time proper, when the opportunity to run them has already passed. Perhaps you are loading a file with require or do when you should be using use instead. Or perhaps you should put the require or do inside a BEGIN block.

    Too many args to syscall

    (F) Perl supports a maximum of only 14 args to syscall().

    Too many arguments for %s

    (F) The function requires fewer arguments than you specified.

    Too many )'s

    (A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

    Too many ('s

    (A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

    Trailing \ in regex m/%s/

    (F) The regular expression ends with an unbackslashed backslash. Backslash it. See the perlre manpage.

    Transliteration pattern not terminated

    (F) The lexer couldn't find the interior delimiter of a tr/// or tr[][] or y/// or y[][] construct. Missing the leading $ from variables $tr or $y may cause this error.

    Transliteration replacement not terminated

    (F) The lexer couldn't find the final delimiter of a tr///, tr[][], y/// or y[][] construct.

    '%s' trapped by operation mask

    (F) You tried to use an operator from a Safe compartment in which it's disallowed. See the Safe manpage.

    truncate not implemented

    (F) Your machine doesn't implement a file truncation mechanism that Configure knows about.

    Type of arg %d to %s must be %s (not %s)

    (F) This function requires the argument in that position to be of a certain type. Arrays must be @NAME or @{EXPR}. Hashes must be %NAME or %{EXPR}. No implicit dereferencing is allowed--use the {EXPR} forms as an explicit dereference. See the perlref manpage.

    umask not implemented

    (F) Your machine doesn't implement the umask function and you tried to use it to restrict permissions for yourself (EXPR & 0700).

    Unable to create sub named "%s"

    (F) You attempted to create or access a subroutine with an illegal name.

    Unbalanced context: %d more PUSHes than POPs

    (W internal) The exit code detected an internal inconsistency in how many execution contexts were entered and left.

    Unbalanced saves: %d more saves than restores

    (W internal) The exit code detected an internal inconsistency in how many values were temporarily localized.

    Unbalanced scopes: %d more ENTERs than LEAVEs

    (W internal) The exit code detected an internal inconsistency in how many blocks were entered and left.

    Unbalanced tmps: %d more allocs than frees

    (W internal) The exit code detected an internal inconsistency in how many mortal scalars were allocated and freed.

    Undefined format "%s" called

    (F) The format indicated doesn't seem to exist. Perhaps it's really in another package? See the perlform manpage.

    Undefined sort subroutine "%s" called

    (F) The sort comparison routine specified doesn't seem to exist. Perhaps it's in a different package? See sort in the perlfunc manpage.

    Undefined subroutine &%s called

    (F) The subroutine indicated hasn't been defined, or if it was, it has since been undefined.

    Undefined subroutine called

    (F) The anonymous subroutine you're trying to call hasn't been defined, or if it was, it has since been undefined.

    Undefined subroutine in sort

    (F) The sort comparison routine specified is declared but doesn't seem to have been defined yet. See sort in the perlfunc manpage.

    Undefined top format "%s" called

    (F) The format indicated doesn't seem to exist. Perhaps it's really in another package? See the perlform manpage.

    Undefined value assigned to typeglob

    (W misc) An undefined value was assigned to a typeglob, a la *foo = undef. This does nothing. It's possible that you really mean undef *foo.

    %s: Undefined variable

    (A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

    unexec of %s into %s failed!

    (F) The unexec() routine failed for some reason. See your local FSF representative, who probably put it there in the first place.

    Unicode character %s is illegal

    (W utf8) Certain Unicode characters have been designated off-limits by the Unicode standard and should not be generated. If you really know what you are doing you can turn off this warning by no warnings 'utf8';.

    Unknown BYTEORDER

    (F) There are no byte-swapping functions for a machine with this byte order.

    Unknown open() mode '%s'

    (F) The second argument of 3-argument open() is not among the list of valid modes: <, >, >>, +<, +>, +>>, -|, |-, <&, >&.

    Unknown PerlIO layer "%s"

    (W layer) An attempt was made to push an unknown layer onto the Perl I/O system. (Layers take care of transforming data between external and internal representations.) Note that some layers, such as mmap, are not supported in all environments. If your program didn't explicitly request the failing operation, it may be the result of the value of the environment variable PERLIO.

    Unknown process %x sent message to prime_env_iter: %s

    (P) An error peculiar to VMS. Perl was reading values for %ENV before iterating over it, and someone else stuck a message in the stream of data Perl expected. Someone's very confused, or perhaps trying to subvert Perl's population of %ENV for nefarious purposes.

    Unknown "re" subpragma '%s' (known ones are: %s)

    You tried to use an unknown subpragma of the "re" pragma.

    Unknown switch condition (?(%.2s in regex; marked by <-- HERE in m/%s/

    (F) The condition part of a (?(condition)if-clause|else-clause) construct is not known. The condition may be lookahead or lookbehind (the condition is true if the lookahead or lookbehind is true), a (?{...}) construct (the condition is true if the code evaluates to a true value), or a number (the condition is true if the set of capturing parentheses named by the number matched).

    The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    Unknown Unicode option letter '%c'

    You specified an unknown Unicode option. See the perlrun manpage documentation of the -C switch for the list of known options.

    Unknown Unicode option value %x

    You specified an unknown Unicode option. See the perlrun manpage documentation of the -C switch for the list of known options.

    Unknown warnings category '%s'

    (F) An error issued by the warnings pragma. You specified a warnings category that is unknown to perl at this point.

    Note that if you want to enable a warnings category registered by a module (e.g. use warnings 'File::Find'), you must have imported this module first.

    unmatched [ in regex; marked by <-- HERE in m/%s/

    (F) The brackets around a character class must match. If you wish to include a closing bracket in a character class, backslash it or put it first. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    unmatched ( in regex; marked by <-- HERE in m/%s/

    (F) Unbackslashed parentheses must always be balanced in regular expressions. If you're a vi user, the % key is valuable for finding the matching parenthesis. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    Unmatched right %s bracket

    (F) The lexer counted more closing curly or square brackets than opening ones, so you're probably missing a matching opening bracket. As a general rule, you'll find the missing one (so to speak) near the place you were last editing.

    Unquoted string "%s" may clash with future reserved word

    (W reserved) You used a bareword that might someday be claimed as a reserved word. It's best to put such a word in quotes, or capitalize it somehow, or insert an underbar into it. You might also declare it as a subroutine.

    Unrecognized character %s

    (F) The Perl parser has no idea what to do with the specified character in your Perl script (or eval). Perhaps you tried to run a compressed script, a binary program, or a directory as a Perl program.

    /%s/: Unrecognized escape \\%c in character class passed through

    (W regexp) You used a backslash-character combination which is not recognized by Perl inside character classes. The character was understood literally.

    Unrecognized escape \\%c passed through

    (W misc) You used a backslash-character combination which is not recognized by Perl.

    Unrecognized escape \\%c passed through in regex; marked by <-- HERE in m/%s/

    (W regexp) You used a backslash-character combination which is not recognized by Perl. This combination appears in an interpolated variable or a '-delimited regular expression. The character was understood literally. The <-- HERE shows in the regular expression about where the escape was discovered.

    Unrecognized signal name "%s"

    (F) You specified a signal name to the kill() function that was not recognized. Say kill -l in your shell to see the valid signal names on your system.

    Unrecognized switch: -%s (-h will show valid options)

    (F) You specified an illegal option to Perl. Don't do that. (If you think you didn't do that, check the #! line to see if it's supplying the bad switch on your behalf.)

    Unsuccessful %s on filename containing newline

    (W newline) A file operation was attempted on a filename, and that operation failed, PROBABLY because the filename contained a newline, PROBABLY because you forgot to chomp() it off. See chomp in the perlfunc manpage.

    Unsupported directory function "%s" called

    (F) Your machine doesn't support opendir() and readdir().

    Unsupported function %s

    (F) This machine doesn't implement the indicated function, apparently. At least, Configure doesn't think so.

    Unsupported function fork

    (F) Your version of executable does not support forking.

    Note that under some systems, like OS/2, there may be different flavors of Perl executables, some of which may support fork, some not. Try changing the name you call Perl by to perl_, perl__, and so on.

    Unsupported script encoding %s

    (F) Your program file begins with a Unicode Byte Order Mark (BOM) which declares it to be in a Unicode encoding that Perl cannot read.

    Unsupported socket function "%s" called

    (F) Your machine doesn't support the Berkeley socket mechanism, or at least that's what Configure thought.

    Unterminated attribute list

    (F) The lexer found something other than a simple identifier at the start of an attribute, and it wasn't a semicolon or the start of a block. Perhaps you terminated the parameter list of the previous attribute too soon. See the attributes manpage.

    Unterminated attribute parameter in attribute list

    (F) The lexer saw an opening (left) parenthesis character while parsing an attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance. See the attributes manpage.

    Unterminated compressed integer

    (F) An argument to unpack("w",...) was incompatible with the BER compressed integer format and could not be converted to an integer. See pack in the perlfunc manpage.

    Unterminated <> operator

    (F) The lexer saw a left angle bracket in a place where it was expecting a term, so it's looking for the corresponding right angle bracket, and not finding it. Chances are you left some needed parentheses out earlier in the line, and you really meant a "less than".

    untie attempted while %d inner references still exist

    (W untie) A copy of the object returned from tie (or tied) was still valid when untie was called.

    Usage: POSIX::%s(%s)

    (F) You called a POSIX function with incorrect arguments. See FUNCTIONS in the POSIX manpage for more information.

    Usage: Win32::%s(%s)

    (F) You called a Win32 function with incorrect arguments. See the Win32 manpage for more information.

    Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in m/%s/

    (W regexp) You have used an internal modifier such as (?-o) that has no meaning unless removed from the entire regexp:

        if ($string =~ /(?-o)$pattern/o) { ... }

    must be written as

        if ($string =~ /$pattern/) { ... }

    The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    Useless (?%s) - use /%s modifier in regex; marked by <-- HERE in m/%s/

    (W regexp) You have used an internal modifier such as (?o) that has no meaning unless applied to the entire regexp:

        if ($string =~ /(?o)$pattern/) { ... }

    must be written as

        if ($string =~ /$pattern/o) { ... }

    The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    Useless use of %s in void context

    (W void) You did something without a side effect in a context that does nothing with the return value, such as a statement that doesn't return a value from a block, or the left side of a scalar comma operator. Very often this points not to stupidity on your part, but a failure of Perl to parse your program the way you thought it would. For example, you'd get this if you mixed up your C precedence with Python precedence and said

        $one, $two = 1, 2;

    when you meant to say

        ($one, $two) = (1, 2);

    Another common error is to use ordinary parentheses to construct a list reference when you should be using square or curly brackets, for example, if you say

        $array = (1,2);

    when you should have said

        $array = [1,2];

    The square brackets explicitly turn a list value into a scalar value, while parentheses do not. So when a parenthesized list is evaluated in a scalar context, the comma is treated like C's comma operator, which throws away the left argument, which is not what you want. See the perlref manpage for more on this.

    This warning will not be issued for numerical constants equal to 0 or 1 since they are often used in statements like

        1 while sub_with_side_effects();

    String constants that would normally evaluate to 0 or 1 are warned about.

    Useless use of "re" pragma

    (W) You did use re; without any arguments. That isn't very useful.

    Useless use of sort in scalar context

    (W void) You used sort in scalar context, as in :

        my $x = sort @y;

    This is not very useful, and perl currently optimizes this away.

    Useless use of %s with no values

    (W syntax) You used the push() or unshift() function with no arguments apart from the array, like push(@x) or unshift(@foo). That won't usually have any effect on the array, so is completely useless. It's possible in principle that push(@tied_array) could have some effect if the array is tied to a class which implements a PUSH method. If so, you can write it as push(@tied_array,()) to avoid this warning.

    "use" not allowed in expression

    (F) The "use" keyword is recognized and executed at compile time, and returns no useful value. See the perlmod manpage.

    Use of bare << to mean <<"" is deprecated

    (D deprecated) You are now encouraged to use the explicitly quoted form if you wish to use an empty line as the terminator of the here-document.

    Use of chdir('') or chdir(undef) as chdir() deprecated

    (D deprecated) chdir() with no arguments is documented to change to $ENV{HOME} or $ENV{LOGDIR}. chdir(undef) and chdir('') share this behavior, but that has been deprecated. In future versions they will simply fail.

    Be careful to check that what you pass to chdir() is defined and not blank, else you might find yourself in your home directory.

    Use of /c modifier is meaningless in s///

    (W regexp) You used the /c modifier in a substitution. The /c modifier is not presently meaningful in substitutions.

    Use of /c modifier is meaningless without /g

    (W regexp) You used the /c modifier with a regex operand, but didn't use the /g modifier. Currently, /c is meaningful only when /g is used. (This may change in the future.)

    Use of freed value in iteration

    (F) Perhaps you modified the iterated array within the loop? This error is typically caused by code like the following:

        @a = (3,4);
    @a = () for (1,2,@a);

    You are not supposed to modify arrays while they are being iterated over. For speed and efficiency reasons, Perl internally does not do full reference-counting of iterated items, hence deleting such an item in the middle of an iteration causes Perl to see a freed value.

    Use of *glob{FILEHANDLE} is deprecated

    (D deprecated) You are now encouraged to use the shorter *glob{IO} form to access the filehandle slot within a typeglob.

    Use of /g modifier is meaningless in split

    (W regexp) You used the /g modifier on the pattern for a split operator. Since split always tries to match the pattern repeatedly, the /g has no effect.

    Use of implicit split to @_ is deprecated

    (D deprecated) It makes a lot of work for the compiler when you clobber a subroutine's argument list, so it's better if you assign the results of a split() explicitly to an array (or list).

    Use of inherited AUTOLOAD for non-method %s() is deprecated

    (D deprecated) As an (ahem) accidental feature, AUTOLOAD subroutines are looked up as methods (using the @ISA hierarchy) even when the subroutines to be autoloaded were called as plain functions (e.g. Foo::bar()), not as methods (e.g. Foo->bar() or < $obj-bar() >>).

    This bug will be rectified in future by using method lookup only for methods' AUTOLOADs. However, there is a significant base of existing code that may be using the old behavior. So, as an interim step, Perl currently issues an optional warning when non-methods use inherited AUTOLOADs.

    The simple rule is: Inheritance will not work when autoloading non-methods. The simple fix for old code is: In any module that used to depend on inheriting AUTOLOAD for non-methods from a base class named BaseClass, execute *AUTOLOAD = \&BaseClass::AUTOLOAD during startup.

    In code that currently says use AutoLoader; @ISA = qw(AutoLoader); you should remove AutoLoader from @ISA and change use AutoLoader; to use AutoLoader 'AUTOLOAD';.

    Use of %s in printf format not supported

    (F) You attempted to use a feature of printf that is accessible from only C. This usually means there's a better way to do it in Perl.

    Use of $* is deprecated

    (D deprecated) This variable magically turned on multi-line pattern matching, both for you and for any luckless subroutine that you happen to call. You should use the new //m and //s modifiers now to do that without the dangerous action-at-a-distance effects of $*.

    Use of $# is deprecated

    (D deprecated) This was an ill-advised attempt to emulate a poorly defined awk feature. Use an explicit printf() or sprintf() instead.

    Use of %s is deprecated

    (D deprecated) The construct indicated is no longer recommended for use, generally because there's a better way to do it, and also because the old way has bad side effects.

    Use of -l on filehandle %s

    (W io) A filehandle represents an opened file, and when you opened the file it already went past any symlink you are presumably trying to look for. The operation returned undef. Use a filename instead.

    Use of "package" with no arguments is deprecated

    (D deprecated) You used the package keyword without specifying a package name. So no namespace is current at all. Using this can cause many otherwise reasonable constructs to fail in baffling ways. use strict; instead.

    Use of reference "%s" as array index

    (W misc) You tried to use a reference as an array index; this probably isn't what you mean, because references in numerical context tend to be huge numbers, and so usually indicates programmer error.

    If you really do mean it, explicitly numify your reference, like so: $array[0+$ref]. This warning is not given for overloaded objects, either, because you can overload the numification and stringification operators and then you assumedly know what you are doing.

    Use of reserved word "%s" is deprecated

    (D deprecated) The indicated bareword is a reserved word. Future versions of perl may use it as a keyword, so you're better off either explicitly quoting the word in a manner appropriate for its context of use, or using a different name altogether. The warning can be suppressed for subroutine names by either adding a & prefix, or using a package qualifier, e.g. &our(), or Foo::our().

    Use of tainted arguments in %s is deprecated

    (W taint, deprecated) You have supplied system() or exec() with multiple arguments and at least one of them is tainted. This used to be allowed but will become a fatal error in a future version of perl. Untaint your arguments. See the perlsec manpage.

    Use of uninitialized value%s

    (W uninitialized) An undefined value was used as if it were already defined. It was interpreted as a "" or a 0, but maybe it was a mistake. To suppress this warning assign a defined value to your variables.

    To help you figure out what was undefined, perl tells you what operation you used the undefined value in. Note, however, that perl optimizes your program and the operation displayed in the warning may not necessarily appear literally in your program. For example, "that $foo" is usually optimized into "that " . $foo, and the warning will refer to the concatenation (.) operator, even though there is no . in your program.

    Using a hash as a reference is deprecated

    (D deprecated) You tried to use a hash as a reference, as in %foo->{"bar"} or %$ref->{"hello"}. Versions of perl <= 5.6.1 used to allow this syntax, but shouldn't have. It is now deprecated, and will be removed in a future version.

    Using an array as a reference is deprecated

    (D deprecated) You tried to use an array as a reference, as in @foo->[23] or @$ref->[99]. Versions of perl <= 5.6.1 used to allow this syntax, but shouldn't have. It is now deprecated, and will be removed in a future version.

    UTF-16 surrogate %s

    (W utf8) You tried to generate half of an UTF-16 surrogate by requesting a Unicode character between the code points 0xD800 and 0xDFFF (inclusive). That range is reserved exclusively for the use of UTF-16 encoding (by having two 16-bit UCS-2 characters); but Perl encodes its characters in UTF-8, so what you got is a very illegal character. If you really know what you are doing you can turn off this warning by no warnings 'utf8';.

    Value of %s can be "0"; test with defined()

    (W misc) In a conditional expression, you used <HANDLE>, <*> (glob), each(), or readdir() as a boolean value. Each of these constructs can return a value of "0"; that would make the conditional expression false, which is probably not what you intended. When using these constructs in conditional expressions, test their values with the defined operator.

    Value of CLI symbol "%s" too long

    (W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV element from a CLI symbol table, and found a resultant string longer than 1024 characters. The return value has been truncated to 1024 characters.

    Variable "%s" is not imported%s

    (F) While "use strict" in effect, you referred to a global variable that you apparently thought was imported from another module, because something else of the same name (usually a subroutine) is exported by that module. It usually means you put the wrong funny character on the front of your variable.

    Variable length lookbehind not implemented in regex; marked by <-- HERE in m/%s/

    (F) Lookbehind is allowed only for subexpressions whose length is fixed and known at compile time. The <-- HERE shows in the regular expression about where the problem was discovered. See the perlre manpage.

    "%s" variable %s masks earlier declaration in same %s

    (W misc) A "my" or "our" variable has been redeclared in the current scope or statement, effectively eliminating all access to the previous instance. This is almost always a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed.

    Variable "%s" may be unavailable

    (W closure) An inner (nested) anonymous subroutine is inside a named subroutine, and outside that is another subroutine; and the anonymous (innermost) subroutine is referencing a lexical variable defined in the outermost subroutine. For example:

       sub outermost { my $a; sub middle { sub { $a } } }

    If the anonymous subroutine is called or referenced (directly or indirectly) from the outermost subroutine, it will share the variable as you would expect. But if the anonymous subroutine is called or referenced when the outermost subroutine is not active, it will see the value of the shared variable as it was before and during the *first* call to the outermost subroutine, which is probably not what you want.

    In these circumstances, it is usually best to make the middle subroutine anonymous, using the sub {} syntax. Perl has specific support for shared variables in nested anonymous subroutines; a named subroutine in between interferes with this feature.

    Variable syntax

    (A) You've accidentally run your script through csh instead of Perl. Check the #! line, or manually feed your script into Perl yourself.

    Variable "%s" will not stay shared

    (W closure) An inner (nested) named subroutine is referencing a lexical variable defined in an outer subroutine.

    When the inner subroutine is called, it will probably see the value of the outer subroutine's variable as it was before and during the *first* call to the outer subroutine; in this case, after the first call to the outer subroutine is complete, the inner and outer subroutines will no longer share a common value for the variable. In other words, the variable will no longer be shared.

    Furthermore, if the outer subroutine is anonymous and references a lexical variable outside itself, then the outer and inner subroutines will never share the given variable.

    This problem can usually be solved by making the inner subroutine anonymous, using the sub {} syntax. When inner anonymous subs that reference variables in outer subroutines are called or referenced, they are automatically rebound to the current values of such variables.

    Version number must be a constant number

    (P) The attempt to translate a use Module n.n LIST statement into its equivalent BEGIN block found an internal inconsistency with the version number.

    Warning: something's wrong

    (W) You passed warn() an empty string (the equivalent of warn "") or you called it with no args and $_ was empty.

    Warning: unable to close filehandle %s properly

    (S) The implicit close() done by an open() got an error indication on the close(). This usually indicates your file system ran out of disk space.

    Warning: Use of "%s" without parentheses is ambiguous

    (S ambiguous) You wrote a unary operator followed by something that looks like a binary operator that could also have been interpreted as a term or unary operator. For instance, if you know that the rand function has a default argument of 1.0, and you write

        rand + 5;

    you may THINK you wrote the same thing as

        rand() + 5;

    but in actual fact, you got

        rand(+5);

    So put in parentheses to say what you really mean.

    Wide character in %s

    (W utf8) Perl met a wide character (>255) when it wasn't expecting one. This warning is by default on for I/O (like print). The easiest way to quiet this warning is simply to add the :utf8 layer to the output, e.g. binmode STDOUT, ':utf8'. Another way to turn off the warning is to add no warnings 'utf8'; but that is often closer to cheating. In general, you are supposed to explicitly mark the filehandle with an encoding, see the open manpage and binmode in the perlfunc manpage.

    Within []-length '%c' not allowed

    (F) The count in the (un)pack template may be replaced by [TEMPLATE] only if TEMPLATE always matches the same amount of packed bytes that can be determined from the template alone. This is not possible if it contains an of the codes @, /, U, u, w or a *-length. Redesign the template.

    write() on closed filehandle %s

    (W closed) The filehandle you're writing to got itself closed sometime before now. Check your control flow.

    %s "\x%s" does not map to Unicode

    When reading in different encodings Perl tries to map everything into Unicode characters. The bytes you read in are not legal in this encoding, for example

        utf8 "\xE4" does not map to Unicode

    if you try to read in the a-diaereses Latin-1 as UTF-8.

    'X' outside of string

    (F) You had a (un)pack template that specified a relative position before the beginning of the string being (un)packed. See pack in the perlfunc manpage.

    'x' outside of string in unpack

    (F) You had a pack template that specified a relative position after the end of the string being unpacked. See pack in the perlfunc manpage.

    YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!

    (F) And you probably never will, because you probably don't have the sources to your kernel, and your vendor probably doesn't give a rip about what you want. Your best bet is to put a setuid C wrapper around your script.

    You need to quote "%s"

    (W syntax) You assigned a bareword as a signal handler name. Unfortunately, you already have a subroutine of that name declared, which means that Perl 5 will try to call the subroutine when the assignment is executed, which is probably not what you want. (If it IS what you want, put an & in front.)

    Your random numbers are not that random

    (F) When trying to initialise the random seed for hashes, Perl could not get any randomness out of your system. This usually indicates Something Very Wrong.


perllexwarn - Perl Lexical Warnings

    • Default Warnings and Optional Warnings
    • What's wrong with -w and $^W
    • Controlling Warnings from the Command Line
    • Backward Compatibility
    • Category Hierarchy
    • Fatal Warnings
    • Reporting Warnings from a Module
  • TODO
  • SEE ALSO
  • AUTHOR

NAME

perllexwarn - Perl Lexical Warnings

DESCRIPTION

The use warnings pragma is a replacement for both the command line flag -w and the equivalent Perl variable, $^W.

The pragma works just like the existing "strict" pragma. This means that the scope of the warning pragma is limited to the enclosing block. It also means that the pragma setting will not leak across files (via use, require or do). This allows authors to independently define the degree of warning checks that will be applied to their module.

By default, optional warnings are disabled, so any legacy code that doesn't attempt to control the warnings will work unchanged.

All warnings are enabled in a block by either of these:

    use warnings;
    use warnings 'all';

Similarly all warnings are disabled in a block by either of these:

    no warnings;
    no warnings 'all';

For example, consider the code below:

    use warnings;
    my @a;
    {
        no warnings;
        my $b = @a[0];
    }
    my $c = @a[0];

The code in the enclosing block has warnings enabled, but the inner block has them disabled. In this case that means the assignment to the scalar $c will trip the "Scalar value @a[0] better written as $a[0]" warning, but the assignment to the scalar $b will not.

Default Warnings and Optional Warnings

Before the introduction of lexical warnings, Perl had two classes of warnings: mandatory and optional.

As its name suggests, if your code tripped a mandatory warning, you would get a warning whether you wanted it or not. For example, the code below would always produce an "isn't numeric" warning about the "2:".

    my $a = "2:" + 3;

With the introduction of lexical warnings, mandatory warnings now become default warnings. The difference is that although the previously mandatory warnings are still enabled by default, they can then be subsequently enabled or disabled with the lexical warning pragma. For example, in the code below, an "isn't numeric" warning will only be reported for the $a variable.

    my $a = "2:" + 3;
    no warnings;
    my $b = "2:" + 3;

Note that neither the -w flag or the $^W can be used to disable/enable default warnings. They are still mandatory in this case.

What's wrong with -w and $^W

Although very useful, the big problem with using -w on the command line to enable warnings is that it is all or nothing. Take the typical scenario when you are writing a Perl program. Parts of the code you will write yourself, but it's very likely that you will make use of pre-written Perl modules. If you use the -w flag in this case, you end up enabling warnings in pieces of code that you haven't written.

Similarly, using $^W to either disable or enable blocks of code is fundamentally flawed. For a start, say you want to disable warnings in a block of code. You might expect this to be enough to do the trick:

     {
         local ($^W) = 0;
         my $a =+ 2;
         my $b; chop $b;
     }

When this code is run with the -w flag, a warning will be produced for the $a line -- "Reversed += operator".

The problem is that Perl has both compile-time and run-time warnings. To disable compile-time warnings you need to rewrite the code like this:

     {
         BEGIN { $^W = 0 }
         my $a =+ 2;
         my $b; chop $b;
     }

The other big problem with $^W is the way you can inadvertently change the warning setting in unexpected places in your code. For example, when the code below is run (without the -w flag), the second call to doit will trip a "Use of uninitialized value" warning, whereas the first will not.

    sub doit
    {
        my $b; chop $b;
    }

    doit();

    {
        local ($^W) = 1;
        doit()
    }

This is a side-effect of $^W being dynamically scoped.

Lexical warnings get around these limitations by allowing finer control over where warnings can or can't be tripped.

Controlling Warnings from the Command Line

There are three Command Line flags that can be used to control when warnings are (or aren't) produced:

-w

This is the existing flag. If the lexical warnings pragma is not used in any of you code, or any of the modules that you use, this flag will enable warnings everywhere. See Backward Compatibility for details of how this flag interacts with lexical warnings.

-W

If the -W flag is used on the command line, it will enable all warnings throughout the program regardless of whether warnings were disabled locally using no warnings or $^W =0. This includes all files that get included via use, require or do. Think of it as the Perl equivalent of the "lint" command.

-X

Does the exact opposite to the -W flag, i.e. it disables all warnings.

Backward Compatibility

If you are used with working with a version of Perl prior to the introduction of lexically scoped warnings, or have code that uses both lexical warnings and $^W, this section will describe how they interact.

How Lexical Warnings interact with -w/$^W:

  1. If none of the three command line flags (-w, -W or -X) that control warnings is used and neither $^W or the warnings pragma are used, then default warnings will be enabled and optional warnings disabled. This means that legacy code that doesn't attempt to control the warnings will work unchanged.

  2. The -w flag just sets the global $^W variable as in 5.005 -- this means that any legacy code that currently relies on manipulating $^W to control warning behavior will still work as is.

  3. Apart from now being a boolean, the $^W variable operates in exactly the same horrible uncontrolled global way, except that it cannot disable/enable default warnings.

  4. If a piece of code is under the control of the warnings pragma, both the $^W variable and the -w flag will be ignored for the scope of the lexical warning.

  5. The only way to override a lexical warnings setting is with the -W or -X command line flags.

The combined effect of 3 & 4 is that it will allow code which uses the warnings pragma to control the warning behavior of $^W-type code (using a local $^W=0) if it really wants to, but not vice-versa.

Category Hierarchy

A hierarchy of "categories" have been defined to allow groups of warnings to be enabled/disabled in isolation.

The current hierarchy is:

  all -+
       |
       +- closure
       |
       +- deprecated
       |
       +- exiting
       |
       +- glob
       |
       +- io -----------+
       |                |
       |                +- closed
       |                |
       |                +- exec
       |                |
       |                +- layer
       |                |
       |                +- newline
       |                |
       |                +- pipe
       |                |
       |                +- unopened
       |
       +- misc
       |
       +- numeric
       |
       +- once
       |
       +- overflow
       |
       +- pack
       |
       +- portable
       |
       +- recursion
       |
       +- redefine
       |
       +- regexp
       |
       +- severe -------+
       |                |
       |                +- debugging
       |                |
       |                +- inplace
       |                |
       |                +- internal
       |                |
       |                +- malloc
       |
       +- signal
       |
       +- substr
       |
       +- syntax -------+
       |                |
       |                +- ambiguous
       |                |
       |                +- bareword
       |                |
       |                +- digit
       |                |
       |                +- parenthesis
       |                |
       |                +- precedence
       |                |
       |                +- printf
       |                |
       |                +- prototype
       |                |
       |                +- qw
       |                |
       |                +- reserved
       |                |
       |                +- semicolon
       |
       +- taint
       |
       +- threads
       |
       +- uninitialized
       |
       +- unpack
       |
       +- untie
       |
       +- utf8
       |
       +- void
       |
       +- y2k

Just like the "strict" pragma any of these categories can be combined

    use warnings qw(void redefine);
    no warnings qw(io syntax untie);

Also like the "strict" pragma, if there is more than one instance of the warnings pragma in a given scope the cumulative effect is additive.

    use warnings qw(void); # only "void" warnings enabled
    ...
    use warnings qw(io);   # only "void" & "io" warnings enabled
    ...
    no warnings qw(void);  # only "io" warnings enabled

To determine which category a specific warning has been assigned to see the perldiag manpage.

Note: In Perl 5.6.1, the lexical warnings category "deprecated" was a sub-category of the "syntax" category. It is now a top-level category in its own right.

Fatal Warnings

The presence of the word "FATAL" in the category list will escalate any warnings detected from the categories specified in the lexical scope into fatal errors. In the code below, the use of time, length and join can all produce a "Useless use of xxx in void context" warning.

    use warnings;

    time;

    {
        use warnings FATAL => qw(void);
        length "abc";
    }

    join "", 1,2,3;

    print "done\n";

When run it produces this output

    Useless use of time in void context at fatal line 3.
    Useless use of length in void context at fatal line 7.

The scope where length is used has escalated the void warnings category into a fatal error, so the program terminates immediately it encounters the warning.

To explicitly turn off a "FATAL" warning you just disable the warning it is associated with. So, for example, to disable the "void" warning in the example above, either of these will do the trick:

    no warnings qw(void);
    no warnings FATAL => qw(void);

If you want to downgrade a warning that has been escalated into a fatal error back to a normal warning, you can use the "NONFATAL" keyword. For example, the code below will promote all warnings into fatal errors, except for those in the "syntax" category.

    use warnings FATAL => 'all', NONFATAL => 'syntax';

Reporting Warnings from a Module

The warnings pragma provides a number of functions that are useful for module authors. These are used when you want to report a module-specific warning to a calling module has enabled warnings via the warnings pragma.

Consider the module MyMod::Abc below.

    package MyMod::Abc;

    use warnings::register;

    sub open {
        my $path = shift;
        if ($path !~ m#^/#) {
            warnings::warn("changing relative path to /var/abc")
                if warnings::enabled();
            $path = "/var/abc/$path";
        }
    }

    1;

The call to warnings::register will create a new warnings category called "MyMod::abc", i.e. the new category name matches the current package name. The open function in the module will display a warning message if it gets given a relative path as a parameter. This warnings will only be displayed if the code that uses MyMod::Abc has actually enabled them with the warnings pragma like below.

    use MyMod::Abc;
    use warnings 'MyMod::Abc';
    ...
    abc::open("../fred.txt");

It is also possible to test whether the pre-defined warnings categories are set in the calling module with the warnings::enabled function. Consider this snippet of code:

    package MyMod::Abc;

    sub open {
        warnings::warnif("deprecated",
                         "open is deprecated, use new instead");
        new(@_);
    }

    sub new
    ...
    1;

The function open has been deprecated, so code has been included to display a warning message whenever the calling module has (at least) the "deprecated" warnings category enabled. Something like this, say.

    use warnings 'deprecated';
    use MyMod::Abc;
    ...
    MyMod::Abc::open($filename);

Either the warnings::warn or warnings::warnif function should be used to actually display the warnings message. This is because they can make use of the feature that allows warnings to be escalated into fatal errors. So in this case

    use MyMod::Abc;
    use warnings FATAL => 'MyMod::Abc';
    ...
    MyMod::Abc::open('../fred.txt');

the warnings::warnif function will detect this and die after displaying the warning message.

The three warnings functions, warnings::warn, warnings::warnif and warnings::enabled can optionally take an object reference in place of a category name. In this case the functions will use the class name of the object as the warnings category.

Consider this example:

    package Original;

    no warnings;
    use warnings::register;

    sub new
    {
        my $class = shift;
        bless [], $class;
    }

    sub check
    {
        my $self = shift;
        my $value = shift;

        if ($value % 2 && warnings::enabled($self))
          { warnings::warn($self, "Odd numbers are unsafe") }
            }

    sub doit
    {
        my $self = shift;
        my $value = shift;
        $self->check($value);
        # ...
    }

    1;

    package Derived;

    use warnings::register;
    use Original;
    our @ISA = qw( Original );
    sub new
    {
        my $class = shift;
        bless [], $class;
    }

    1;

The code below makes use of both modules, but it only enables warnings from Derived.

    use Original;
    use Derived;
    use warnings 'Derived';
    my $a = new Original;
    $a->doit(1);
    my $b = new Derived;
    $a->doit(1);

When this code is run only the Derived object, $b, will generate a warning.

    Odd numbers are unsafe at main.pl line 7

Notice also that the warning is reported at the line where the object is first used.

TODO

  perl5db.pl
    The debugger saves and restores C<$^W> at runtime. I haven't checked
    whether the debugger will still work with the lexical warnings
    patch applied.
  diagnostics.pm
    I *think* I've got diagnostics to work with the lexical warnings
    patch, but there were design decisions made in diagnostics to work
    around the limitations of C<$^W>. Now that those limitations are gone,
    the module should be revisited.
  document calling the warnings::* functions from XS

SEE ALSO

the warnings manpage, the perldiag manpage.

AUTHOR

Paul Marquess


perlcheat - Perl 5 Cheat Sheet

    • The sheet
  • ACKNOWLEDGEMENTS
  • AUTHOR
  • SEE ALSO

NAME

perlcheat - Perl 5 Cheat Sheet

DESCRIPTION

This 'cheat sheet' is a handy reference, meant for beginning Perl programmers. Not everything is mentioned, but 194 features may already be overwhelming.

The sheet

  CONTEXTS  SIGILS             ARRAYS        HASHES
  void      $scalar   whole:   @array        %hash
  scalar    @array    slice:   @array[0, 2]  @hash{'a', 'b'}
  list      %hash     element: $array[0]     $hash{'a'}
            &sub
            *glob    SCALAR VALUES
                     number, string, reference, glob, undef
  REFERENCES
  \     references      $$foo[1]       aka $foo->[1]
  $@%&* dereference     $$foo{bar}     aka $foo->{bar}
  []    anon. arrayref  ${$$foo[1]}[2] aka $foo->[1]->[2]
  {}    anon. hashref   ${$$foo[1]}[2] aka $foo->[1][2]
  \()   list of refs
                          NUMBERS vs STRINGS  LINKS
  OPERATOR PRECEDENCE     =          =        perl.plover.com
  ->                      +          .        search.cpan.org
  ++ --                   == !=      eq ne         cpan.org
  **                      < > <= >=  lt gt le ge   pm.org
  ! ~ \ u+ u-             <=>        cmp           tpj.com
  =~ !~                                            perldoc.com
  * / % x                 SYNTAX
  + - .                   for    (LIST) { }, for (a;b;c) { }
  << >>                   while  ( ) { }, until ( ) { }
  named uops              if     ( ) { } elsif ( ) { } else { }
  < > <= >= lt gt le ge   unless ( ) { } elsif ( ) { } else { }
  == != <=> eq ne cmp     for equals foreach (ALWAYS)
  &
  | ^              REGEX METACHARS            REGEX MODIFIERS
  &&               ^     string begin         /i case insens.
  ||               $     str. end (before \n) /m line based ^$
  .. ...           +     one or more          /s . includes \n
  ?:               *     zero or more         /x ign. wh.space
  = += -= *= etc.  ?     zero or one          /g global
  , =>             {3,7} repeat in range
  list ops         ()    capture          REGEX CHARCLASSES
  not              (?:)  no capture       .  == [^\n]
  and              []    character class  \s == [\x20\f\t\r\n]
  or xor           |     alternation      \w == [A-Za-z0-9_]
                   \b    word boundary    \d == [0-9]
                   \z    string end       \S, \W and \D negate
  DO
  use strict;        DON'T            LINKS
  use warnings;      "$foo"           perl.com
  my $var;           $$variable_name  perlmonks.org
  open() or die $!;  `$userinput`     use.perl.org
  use Modules;       /$userinput/     perl.apache.org
                                      parrotcode.org
  FUNCTION RETURN LISTS
  stat      localtime    caller         SPECIAL VARIABLES
   0 dev    0 second     0 package      $_    default variable
   1 ino    1 minute     1 filename     $0    program name
   2 mode   2 hour       2 line         $/    input separator
   3 nlink  3 day        3 subroutine   $\    output separator
   4 uid    4 month-1    4 hasargs      $|    autoflush
   5 gid    5 year-1900  5 wantarray    $!    sys/libcall error
   6 rdev   6 weekday    6 evaltext     $@    eval error
   7 size   7 yearday    7 is_require   $$    process ID
   8 atime  8 is_dst     8 hints        $.    line number
   9 mtime               9 bitmask      @ARGV command line args
  10 ctime  just use                    @INC  include paths
  11 blksz  POSIX::      3..9 only      @_    subroutine args
  12 blcks  strftime!    with EXPR      %ENV  environment

ACKNOWLEDGEMENTS

The first version of this document appeared on Perl Monks, where several people had useful suggestions. Thank you, Perl Monks.

A special thanks to Damian Conway, who didn't only suggest important changes, but also took the time to count the number of listed features and make a Perl 6 version to show that Perl will stay Perl.

AUTHOR

Juerd Waalboer <juerd@cpan.org>, with the help of many Perl Monks.

SEE ALSO

 http://perlmonks.org/?node_id=216602      the original PM post
 http://perlmonks.org/?node_id=238031      Damian Conway's Perl 6 version
 http://juerd.nl/site.plp/perlcheat        home of the Perl Cheat Sheet


perlfunc - Perl builtin functions

    • Perl Functions by Category
    • Portability
    • Alphabetical Listing of Perl Functions

NAME

perlfunc - Perl builtin functions

DESCRIPTION

The functions in this section can serve as terms in an expression. They fall into two major categories: list operators and named unary operators. These differ in their precedence relationship with a following comma. (See the precedence table in the perlop manpage.) List operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of a unary operator, but merely separates the arguments of a list operator. A unary operator generally provides a scalar context to its argument, while a list operator may provide either scalar or list contexts for its arguments. If it does both, the scalar arguments will be first, and the list argument will follow. (Note that there can ever be only one such list argument.) For instance, splice() has three scalar arguments followed by a list, whereas gethostbyname() has four scalar arguments.

In the syntax descriptions that follow, list operators that expect a list (and provide list context for the elements of the list) are shown with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. Commas should separate elements of the LIST.

Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the parentheses.) If you use the parentheses, the simple (but occasionally surprising) rule is this: It looks like a function, therefore it is a function, and precedence doesn't matter. Otherwise it's a list operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to be careful sometimes:

    print 1+2+4;        # Prints 7.
    print(1+2) + 4;     # Prints 3.
    print (1+2)+4;      # Also prints 3!
    print +(1+2)+4;     # Prints 7.
    print ((1+2)+4);    # Prints 7.

If you run Perl with the -w switch it can warn you about this. For example, the third line above produces:

    print (...) interpreted as function at - line 1.
    Useless use of integer addition in void context at - line 1.

A few functions take no arguments at all, and therefore work as neither unary nor list operators. These include such functions as time and endpwent. For example, time+86_400 always means time() + 86_400.

For functions that can be used in either a scalar or list context, nonabortive failure is generally indicated in a scalar context by returning the undefined value, and in a list context by returning the null list.

Remember the following important rule: There is no rule that relates the behavior of an expression in list context to its behavior in scalar context, or vice versa. It might do two totally different things. Each operator and function decides which sort of value it would be most appropriate to return in scalar context. Some operators return the length of the list that would have been returned in list context. Some operators return the first value in the list. Some operators return the last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency.

A named array in scalar context is quite different from what would at first glance appear to be a list in scalar context. You can't get a list like (1,2,3) into being in scalar context, because the compiler knows the context at compile time. It would generate the scalar comma operator there, not the list construction version of the comma. That means it was never a list to start with.

In general, functions in Perl that serve as wrappers for system calls of the same name (like chown(2), fork(2), closedir(2), etc.) all return true when they succeed and undef otherwise, as is usually mentioned in the descriptions below. This is different from the C interfaces, which return -1 on failure. Exceptions to this rule are wait, waitpid, and syscall. System calls also set the special $! variable on failure. Other functions do not, except accidentally.

Perl Functions by Category

Here are Perl's functions (including things that look like functions, like some keywords and named operators) arranged by category. Some functions appear in more than one place.

Functions for SCALARs or strings

chomp, chop, chr, crypt, hex, index, lc, lcfirst, length, oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex, sprintf, substr, tr///, uc, ucfirst, y///

Regular expressions and pattern matching

m//, pos, quotemeta, s///, split, study, qr//

Numeric functions

abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, srand

Functions for real @ARRAYs

pop, push, shift, splice, unshift

Functions for list data

grep, join, map, qw/STRING/, reverse, sort, unpack

Functions for real %HASHes

delete, each, exists, keys, values

Input and output functions

binmode, close, closedir, dbmclose, dbmopen, die, eof, fileno, flock, format, getc, print, printf, read, readdir, rewinddir, seek, seekdir, select, syscall, sysread, sysseek, syswrite, tell, telldir, truncate, warn, write

Functions for fixed length data or records

pack, read, syscall, sysread, syswrite, unpack, vec

Functions for filehandles, files, or directories

-X, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link, lstat, mkdir, open, opendir, readlink, rename, rmdir, stat, symlink, sysopen, umask, unlink, utime

Keywords related to the control flow of your Perl program

caller, continue, die, do, dump, eval, exit, goto, last, next, redo, return, sub, wantarray

Keywords related to scoping

caller, import, local, my, our, package, use

Miscellaneous functions

defined, dump, eval, formline, local, my, our, reset, scalar, undef, wantarray

Functions for processes and process groups

alarm, exec, fork, getpgrp, getppid, getpriority, kill, pipe, qx/STRING/, setpgrp, setpriority, sleep, system, times, wait, waitpid

Keywords related to perl modules

do, import, no, package, require, use

Keywords related to classes and object-orientedness

bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use

Low-level socket functions

accept, bind, connect, getpeername, getsockname, getsockopt, listen, recv, send, setsockopt, shutdown, socket, socketpair

System V interprocess communication functions

msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop, shmctl, shmget, shmread, shmwrite

Fetching user and group info

endgrent, endhostent, endnetent, endpwent, getgrent, getgrgid, getgrnam, getlogin, getpwent, getpwnam, getpwuid, setgrent, setpwent

Fetching network info

endprotoent, endservent, gethostbyaddr, gethostbyname, gethostent, getnetbyaddr, getnetbyname, getnetent, getprotobyname, getprotobynumber, getprotoent, getservbyname, getservbyport, getservent, sethostent, setnetent, setprotoent, setservent

Time-related functions

gmtime, localtime, time, times

Functions new in perl5

abs, bless, chomp, chr, exists, formline, glob, import, lc, lcfirst, map, my, no, our, prototype, qx/STRING/, qw/STRING/, readline, readpipe, ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use

* - sub was a keyword in perl4, but in perl5 it is an operator, which can be used in expressions.

Functions obsoleted in perl5

dbmclose, dbmopen

Portability

Perl was born in Unix and can therefore access all common Unix system calls. In non-Unix environments, the functionality of some Unix system calls may not be available, or details of the available functionality may differ slightly. The Perl functions affected by this are:

-X, binmode, chmod, chown, chroot, crypt, dbmclose, dbmopen, dump, endgrent, endhostent, endnetent, endprotoent, endpwent, endservent, exec, fcntl, flock, fork, getgrent, getgrgid, gethostbyname, gethostent, getlogin, getnetbyaddr, getnetbyname, getnetent, getppid, getpgrp, getpriority, getprotobynumber, getprotoent, getpwent, getpwnam, getpwuid, getservbyport, getservent, getsockopt, glob, ioctl, kill, link, lstat, msgctl, msgget, msgrcv, msgsnd, open, pipe, readlink, rename, select, semctl, semget, semop, setgrent, sethostent, setnetent, setpgrp, setpriority, setprotoent, setpwent, setservent, setsockopt, shmctl, shmget, shmread, shmwrite, socket, socketpair, stat, symlink, syscall, sysopen, system, times, truncate, umask, unlink, utime, wait, waitpid

For more information about the portability of these functions, see the perlport manpage and other available platform-specific documentation.

Alphabetical Listing of Perl Functions

-X FILEHANDLE
-X EXPR
-X

A file test, where X is one of the letters listed below. This unary operator takes one argument, either a filename or a filehandle, and tests the associated file to see if something is true about it. If the argument is omitted, tests $_, except for -t, which tests STDIN. Unless otherwise documented, it returns 1 for true and '' for false, or the undefined value if the file doesn't exist. Despite the funny names, precedence is the same as any other named unary operator, and the argument may be parenthesized like any other unary operator. The operator may be any of:

    -r  File is readable by effective uid/gid.
    -w  File is writable by effective uid/gid.
    -x  File is executable by effective uid/gid.
    -o  File is owned by effective uid.
    -R  File is readable by real uid/gid.
    -W  File is writable by real uid/gid.
    -X  File is executable by real uid/gid.
    -O  File is owned by real uid.
    -e  File exists.
    -z  File has zero size (is empty).
    -s  File has nonzero size (returns size in bytes).
    -f  File is a plain file.
    -d  File is a directory.
    -l  File is a symbolic link.
    -p  File is a named pipe (FIFO), or Filehandle is a pipe.
    -S  File is a socket.
    -b  File is a block special file.
    -c  File is a character special file.
    -t  Filehandle is opened to a tty.
    -u  File has setuid bit set.
    -g  File has setgid bit set.
    -k  File has sticky bit set.
    -T  File is an ASCII text file (heuristic guess).
    -B  File is a "binary" file (opposite of -T).
    -M  Script start time minus file modification time, in days.
    -A  Same for access time.
    -C  Same for inode change time (Unix, may differ for other platforms)

Example:

    while (<>) {
        chomp;
        next unless -f $_;      # ignore specials
        #...
    }

The interpretation of the file permission operators -r, -R, -w, -W, -x, and -X is by default based solely on the mode of the file and the uids and gids of the user. There may be other reasons you can't actually read, write, or execute the file. Such reasons may be for example network filesystem access controls, ACLs (access control lists), read-only filesystems, and unrecognized executable formats.

Also note that, for the superuser on the local filesystems, the -r, -R, -w, and -W tests always return 1, and -x and -X return 1 if any execute bit is set in the mode. Scripts run by the superuser may thus need to do a stat() to determine the actual mode of the file, or temporarily set their effective uid to something else.

If you are using ACLs, there is a pragma called filetest that may produce more accurate results than the bare stat() mode bits. When under the use filetest 'access' the above-mentioned filetests will test whether the permission can (not) be granted using the access() family of system calls. Also note that the -x and -X may under this pragma return true even if there are no execute permission bits set (nor any extra execute permission ACLs). This strangeness is due to the underlying system calls' definitions. Read the documentation for the filetest pragma for more information.

Note that -s/a/b/ does not do a negated substitution. Saying -exp($foo) still works as expected, however--only single letters following a minus are interpreted as file tests.

The -T and -B switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or characters with the high bit set. If too many strange characters (>30%) are found, it's a -B file; otherwise it's a -T file. Also, any file containing null in the first block is considered a binary file. If -T or -B is used on a filehandle, the current IO buffer is examined rather than the first block. Both -T and -B return true on a null file, or a file at EOF when testing a filehandle. Because you have to read a file to do the -T test, on most occasions you want to use a -f against the file first, as in next unless -f $file && -T $file.

If any of the file tests (or either the stat or lstat operators) are given the special filehandle consisting of a solitary underline, then the stat structure of the previous file test (or stat operator) is used, saving a system call. (This doesn't work with -t, and you need to remember that lstat() and -l will leave values in the stat structure for the symbolic link, not the real file.) (Also, if the stat buffer was filled by an lstat call, -T and -B will reset it with the results of stat _). Example:

    print "Can do.\n" if -r $a || -w _ || -x _;

    stat($filename);
    print "Readable\n" if -r _;
    print "Writable\n" if -w _;
    print "Executable\n" if -x _;
    print "Setuid\n" if -u _;
    print "Setgid\n" if -g _;
    print "Sticky\n" if -k _;
    print "Text\n" if -T _;
    print "Binary\n" if -B _;
abs VALUE
abs

Returns the absolute value of its argument. If VALUE is omitted, uses $_.

accept NEWSOCKET,GENERICSOCKET

Accepts an incoming socket connect, just as the accept(2) system call does. Returns the packed address if it succeeded, false otherwise. See the example in Sockets: Client/Server Communication in the perlipc manpage.

On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptor, as determined by the value of $^F. See $^F in the perlvar manpage.

alarm SECONDS
alarm

Arranges to have a SIGALRM delivered to this process after the specified number of wallclock seconds has elapsed. If SECONDS is not specified, the value stored in $_ is used. (On some machines, unfortunately, the elapsed time may be up to one second less or more than you specified because of how seconds are counted, and process scheduling may delay the delivery of the signal even further.)

Only one timer may be counting at once. Each call disables the previous timer, and an argument of 0 may be supplied to cancel the previous timer without starting a new one. The returned value is the amount of time remaining on the previous timer.

For delays of finer granularity than one second, you may use Perl's four-argument version of select() leaving the first three arguments undefined, or you might be able to use the syscall interface to access setitimer(2) if your system supports it. The Time::HiRes module (from CPAN, and starting from Perl 5.8 part of the standard distribution) may also prove useful.

It is usually a mistake to intermix alarm and sleep calls. (sleep may be internally implemented in your system with alarm)

If you want to use alarm to time out a system call you need to use an eval/die pair. You can't rely on the alarm causing the system call to fail with $! set to EINTR because Perl sets up signal handlers to restart system calls on some systems. Using eval/die always works, modulo the caveats given in Signals in the perlipc manpage.

    eval {
        local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
        alarm $timeout;
        $nread = sysread SOCKET, $buffer, $size;
        alarm 0;
    };
    if ($@) {
        die unless $@ eq "alarm\n";   # propagate unexpected errors
        # timed out
    }
    else {
        # didn't
    }

For more information see the perlipc manpage.

atan2 Y,X

Returns the arctangent of Y/X in the range -PI to PI.

For the tangent operation, you may use the Math::Trig::tan function, or use the familiar relation:

    sub tan { sin($_[0]) / cos($_[0])  }

Note that atan2(0, 0) is not well-defined.

bind SOCKET,NAME

Binds a network address to a socket, just as the bind system call does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in Sockets: Client/Server Communication in the perlipc manpage.

binmode FILEHANDLE, LAYER
binmode FILEHANDLE

Arranges for FILEHANDLE to be read or written in "binary" or "text" mode on systems where the run-time libraries distinguish between binary and text files. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. Returns true on success, otherwise it returns undef and sets $! (errno).

On some systems (in general, DOS and Windows-based systems) binmode() is necessary when you're not working with a text file. For the sake of portability it is a good idea to always use it when appropriate, and to never use it when it isn't appropriate. Also, people can set their I/O to be by default UTF-8 encoded Unicode, not bytes.

In other words: regardless of platform, use binmode() on binary data, like for example images.

If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the file handle. When LAYER is present using binmode on text file makes sense.

If LAYER is omitted or specified as :raw the filehandle is made suitable for passing binary data. This includes turning off possible CRLF translation and marking it as bytes (as opposed to Unicode characters). Note that, despite what may be implied in "Programming Perl" (the Camel) or elsewhere, :raw is not the simply inverse of :crlf -- other layers which would affect binary nature of the stream are also disabled. See the PerlIO manpage, the perlrun manpage and the discussion about the PERLIO environment variable.

The :bytes, :crlf, and :utf8, and any other directives of the form :..., are called I/O layers. The open pragma can be used to establish default I/O layers. See the open manpage.

The LAYER parameter of the binmode() function is described as "DISCIPLINE" in "Programming Perl, 3rd Edition". However, since the publishing of this book, by many known as "Camel III", the consensus of the naming of this functionality has moved from "discipline" to "layer". All documentation of this version of Perl therefore refers to "layers" rather than to "disciplines". Now back to the regularly scheduled documentation...

To mark FILEHANDLE as UTF-8, use :utf8.

In general, binmode() should be called after open() but before any I/O is done on the filehandle. Calling binmode() will normally flush any pending buffered output data (and perhaps pending input data) on the handle. An exception to this is the :encoding layer that changes the default character encoding of the handle, see the open manpage. The :encoding layer sometimes needs to be called in mid-stream, and it doesn't flush the stream. The :encoding also implicitly pushes on top of itself the :utf8 layer because internally Perl will operate on UTF-8 encoded Unicode characters.

The operating system, device drivers, C libraries, and Perl run-time system all work together to let the programmer treat a single character (\n) as the line terminator, irrespective of the external representation. On many operating systems, the native text file representation matches the internal representation, but on some platforms the external representation of \n is made up of more than one character.

Mac OS, all variants of Unix, and Stream_LF files on VMS use a single character to end each line in the external representation of text (even though that single character is CARRIAGE RETURN on Mac OS and LINE FEED on Unix and most VMS files). In other systems like OS/2, DOS and the various flavors of MS-Windows your program sees a \n as a simple \cJ, but what's stored in text files are the two characters \cM\cJ. That means that, if you don't use binmode() on these systems, \cM\cJ sequences on disk will be converted to \n on input, and any \n in your program will be converted back to \cM\cJ on output. This is what you want for text files, but it can be disastrous for binary files.

Another consequence of using binmode() (on some systems) is that special end-of-file markers will be seen as part of the data stream. For systems from the Microsoft family this means that if your binary data contains \cZ, the I/O subsystem will regard it as the end of the file, unless you use binmode().

binmode() is not only important for readline() and print() operations, but also when using read(), seek(), sysread(), syswrite() and tell() (see the perlport manpage for more details). See the $/ and $\ variables in the perlvar manpage for how to manually set your input and output line-termination sequences.

bless REF,CLASSNAME
bless REF

This function tells the thingy referenced by REF that it is now an object in the CLASSNAME package. If CLASSNAME is omitted, the current package is used. Because a bless is often the last thing in a constructor, it returns the reference for convenience. Always use the two-argument version if a derived class might inherit the function doing the blessing. See the perltoot manpage and the perlobj manpage for more about the blessing (and blessings) of objects.

Consider always blessing objects in CLASSNAMEs that are mixed case. Namespaces with all lowercase names are considered reserved for Perl pragmata. Builtin types have all uppercase names. To prevent confusion, you may wish to avoid such package names as well. Make sure that CLASSNAME is a true value.

See Perl Modules in the perlmod manpage.

caller EXPR
caller

Returns the context of the current subroutine call. In scalar context, returns the caller's package name if there is a caller, that is, if we're in a subroutine or eval or require, and the undefined value otherwise. In list context, returns

    ($package, $filename, $line) = caller;

With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one.

    ($package, $filename, $line, $subroutine, $hasargs,
    $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);

Here $subroutine may be (eval) if the frame is not a subroutine call, but an eval. In such a case additional elements $evaltext and $is_require are set: $is_require is true if the frame is created by a require or use statement, $evaltext contains the text of the eval EXPR statement. In particular, for an eval BLOCK statement, $filename is (eval), but $evaltext is undefined. (Note also that each use statement creates a require frame inside an eval EXPR frame.) $subroutine may also be (unknown) if this particular subroutine happens to have been deleted from the symbol table. $hasargs is true if a new instance of @_ was set up for the frame. $hints and $bitmask contain pragmatic hints that the caller was compiled with. The $hints and $bitmask values are subject to change between versions of Perl, and are not meant for external use.

Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the arguments with which the subroutine was invoked.

Be aware that the optimizer might have optimized call frames away before caller had a chance to get the information. That means that caller(N) might not return information about the call frame you expect it do, for N > 1. In particular, @DB::args might have information from the previous time caller was called.

chdir EXPR
chdir FILEHANDLE
chdir DIRHANDLE
chdir

Changes the working directory to EXPR, if possible. If EXPR is omitted, changes to the directory specified by $ENV{HOME}, if set; if not, changes to the directory specified by $ENV{LOGDIR}. (Under VMS, the variable $ENV{SYS$LOGIN} is also checked, and used if it is set.) If neither is set, chdir does nothing. It returns true upon success, false otherwise. See the example under die.

On systems that support fchdir, you might pass a file handle or directory handle as argument. On systems that don't support fchdir, passing handles produces a fatal error at run time.

chmod LIST

Changes the permissions of a list of files. The first element of the list must be the numerical mode, which should probably be an octal number, and which definitely should not be a string of octal digits: 0644 is okay, '0644' is not. Returns the number of files successfully changed. See also oct, if all you have is a string.

    $cnt = chmod 0755, 'foo', 'bar';
    chmod 0755, @executables;
    $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
                                             # --w----r-T
    $mode = '0644'; chmod oct($mode), 'foo'; # this is better
    $mode = 0644;   chmod $mode, 'foo';      # this is best

On systems that support fchmod, you might pass file handles among the files. On systems that don't support fchmod, passing file handles produces a fatal error at run time.

    open(my $fh, "<", "foo");
    my $perm = (stat $fh)[2] & 07777;
    chmod($perm | 0600, $fh);

You can also import the symbolic S_I* constants from the Fcntl module:

    use Fcntl ':mode';

    chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
    # This is identical to the chmod 0755 of the above example.
chomp VARIABLE
chomp( LIST )
chomp

This safer version of chop removes any trailing string that corresponds to the current value of $/ (also known as $INPUT_RECORD_SEPARATOR in the English module). It returns the total number of characters removed from all its arguments. It's often used to remove the newline from the end of an input record when you're worried that the final record may be missing its newline. When in paragraph mode ($/ = ""), it removes all trailing newlines from the string. When in slurp mode ($/ = undef) or fixed-length record mode ($/ is a reference to an integer or the like, see the perlvar manpage) chomp() won't remove anything. If VARIABLE is omitted, it chomps $_. Example:

    while (<>) {
        chomp;  # avoid \n on last field
        @array = split(/:/);
        # ...
    }

If VARIABLE is a hash, it chomps the hash's values, but not its keys.

You can actually chomp anything that's an lvalue, including an assignment:

    chomp($cwd = `pwd`);
    chomp($answer = <STDIN>);

If you chomp a list, each element is chomped, and the total number of characters removed is returned.

If the encoding pragma is in scope then the lengths returned are calculated from the length of $/ in Unicode characters, which is not always the same as the length of $/ in the native encoding.

Note that parentheses are necessary when you're chomping anything that is not a simple variable. This is because chomp $cwd = `pwd`; is interpreted as (chomp $cwd) = `pwd`;, rather than as chomp( $cwd = `pwd` ) which you might expect. Similarly, chomp $a, $b is interpreted as chomp($a), $b rather than as chomp($a, $b).

chop VARIABLE
chop( LIST )
chop

Chops off the last character of a string and returns the character chopped. It is much more efficient than s/.$//s because it neither scans nor copies the string. If VARIABLE is omitted, chops $_. If VARIABLE is a hash, it chops the hash's values, but not its keys.

You can actually chop anything that's an lvalue, including an assignment.

If you chop a list, each element is chopped. Only the value of the last chop is returned.

Note that chop returns the last character. To return all but the last character, use substr($string, 0, -1).

See also chomp.

chown LIST

Changes the owner (and group) of a list of files. The first two elements of the list must be the numeric uid and gid, in that order. A value of -1 in either position is interpreted by most systems to leave that value unchanged. Returns the number of files successfully changed.

    $cnt = chown $uid, $gid, 'foo', 'bar';
    chown $uid, $gid, @filenames;

On systems that support fchown, you might pass file handles among the files. On systems that don't support fchown, passing file handles produces a fatal error at run time.

Here's an example that looks up nonnumeric uids in the passwd file:

    print "User: ";
    chomp($user = <STDIN>);
    print "Files: ";
    chomp($pattern = <STDIN>);

    ($login,$pass,$uid,$gid) = getpwnam($user)
        or die "$user not in passwd file";

    @ary = glob($pattern);      # expand filenames
    chown $uid, $gid, @ary;

On most systems, you are not allowed to change the ownership of the file unless you're the superuser, although you should be able to change the group to any of your secondary groups. On insecure systems, these restrictions may be relaxed, but this is not a portable assumption. On POSIX systems, you can detect this condition this way:

    use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
    $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
chr NUMBER
chr

Returns the character represented by that NUMBER in the character set. For example, chr(65) is "A" in either ASCII or Unicode, and chr(0x263a) is a Unicode smiley face. Note that characters from 128 to 255 (inclusive) are by default not encoded in UTF-8 Unicode for backward compatibility reasons (but see the encoding manpage).

If NUMBER is omitted, uses $_.

For the reverse, use ord.

Note that under the bytes pragma the NUMBER is masked to the low eight bits.

See the perlunicode manpage and the encoding manpage for more about Unicode.

chroot FILENAME
chroot

This function works like the system call by the same name: it makes the named directory the new root directory for all further pathnames that begin with a / by your process and all its children. (It doesn't change your current working directory, which is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is omitted, does a chroot to $_.

close FILEHANDLE
close

Closes the file or pipe associated with the file handle, returning true only if IO buffers are successfully flushed and closes the system file descriptor. Closes the currently selected filehandle if the argument is omitted.

You don't have to close FILEHANDLE if you are immediately going to do another open on it, because open will close it for you. (See open.) However, an explicit close on an input file resets the line counter ($.), while the implicit close done by open does not.

If the file handle came from a piped open, close will additionally return false if one of the other system calls involved fails, or if the program exits with non-zero status. (If the only problem was that the program exited non-zero, $! will be set to 0.) Closing a pipe also waits for the process executing on the pipe to complete, in case you want to look at the output of the pipe afterwards, and implicitly puts the exit status value of that command into $?.

Prematurely closing the read end of a pipe (i.e. before the process writing to it at the other end has closed it) will result in a SIGPIPE being delivered to the writer. If the other end can't handle that, be sure to read all the data before closing the pipe.

Example:

    open(OUTPUT, '|sort >foo')  # pipe to sort
        or die "Can't start sort: $!";
    #...                        # print stuff to output
    close OUTPUT                # wait for sort to finish
        or warn $! ? "Error closing sort pipe: $!"
                   : "Exit status $? from sort";
    open(INPUT, 'foo')          # get sort's results
        or die "Can't open 'foo' for input: $!";

FILEHANDLE may be an expression whose value can be used as an indirect filehandle, usually the real filehandle name.

closedir DIRHANDLE

Closes a directory opened by opendir and returns the success of that system call.

connect SOCKET,NAME

Attempts to connect to a remote socket, just as the connect system call does. Returns true if it succeeded, false otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in Sockets: Client/Server Communication in the perlipc manpage.

continue BLOCK

continue is actually a flow control statement rather than a function. If there is a continue BLOCK attached to a BLOCK (typically in a while or foreach), it is always executed just before the conditional is about to be evaluated again, just like the third part of a for loop in C. Thus it can be used to increment a loop variable, even when the loop has been continued via the next statement (which is similar to the C continue statement).

last, next, or redo may appear within a continue block. last and redo will behave as if they had been executed within the main block. So will next, but since it will execute a continue block, it may be more entertaining.

    while (EXPR) {
        ### redo always comes here
        do_something;
    } continue {
        ### next always comes here
        do_something_else;
        # then back the top to re-check EXPR
    }
    ### last always comes here

Omitting the continue section is semantically equivalent to using an empty one, logically enough. In that case, next goes directly back to check the condition at the top of the loop.

cos EXPR
cos

Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, takes cosine of $_.

For the inverse cosine operation, you may use the Math::Trig::acos() function, or use this relation:

    sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
crypt PLAINTEXT,SALT

Creates a digest string exactly like the crypt(3) function in the C library (assuming that you actually have a version there that has not been extirpated as a potential munitions).

crypt() is a one-way hash function. The PLAINTEXT and SALT is turned into a short string, called a digest, which is returned. The same PLAINTEXT and SALT will always return the same string, but there is no (known) way to get the original PLAINTEXT from the hash. Small changes in the PLAINTEXT or SALT will result in large changes in the digest.

There is no decrypt function. This function isn't all that useful for cryptography (for that, look for Crypt modules on your nearby CPAN mirror) and the name "crypt" is a bit of a misnomer. Instead it is primarily used to check if two pieces of text are the same without having to transmit or store the text itself. An example is checking if a correct password is given. The digest of the password is stored, not the password itself. The user types in a password that is crypt()'d with the same salt as the stored digest. If the two digests match the password is correct.

When verifying an existing digest string you should use the digest as the salt (like crypt($plain, $digest) eq $digest). The SALT used to create the digest is visible as part of the digest. This ensures crypt() will hash the new string with the same salt as the digest. This allows your code to work with the standard crypt and with more exotic implementations. In other words, do not assume anything about the returned string itself, or how many bytes in the digest matter.

Traditionally the result is a string of 13 bytes: two first bytes of the salt, followed by 11 bytes from the set [./0-9A-Za-z], and only the first eight bytes of the digest string mattered, but alternative hashing schemes (like MD5), higher level security schemes (like C2), and implementations on non-UNIX platforms may produce different strings.

When choosing a new salt create a random two character string whose characters come from the set [./0-9A-Za-z] (like join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]). This set of characters is just a recommendation; the characters allowed in the salt depend solely on your system's crypt library, and Perl can't restrict what salts crypt() accepts.

Here's an example that makes sure that whoever runs this program knows their password:

    $pwd = (getpwuid($<))[1];

    system "stty -echo";
    print "Password: ";
    chomp($word = <STDIN>);
    print "\n";
    system "stty echo";

    if (crypt($word, $pwd) ne $pwd) {
        die "Sorry...\n";
    } else {
        print "ok\n";
    }

Of course, typing in your own password to whoever asks you for it is unwise.

The crypt function is unsuitable for hashing large quantities of data, not least of all because you can't get the information back. Look at the the Digest manpage module for more robust algorithms.

If using crypt() on a Unicode string (which potentially has characters with codepoints above 255), Perl tries to make sense of the situation by trying to downgrade (a copy of the string) the string back to an eight-bit byte string before calling crypt() (on that copy). If that works, good. If not, crypt() dies with Wide character in crypt.

dbmclose HASH

[This function has been largely superseded by the untie function.]

Breaks the binding between a DBM file and a hash.

dbmopen HASH,DBNAME,MASK

[This function has been largely superseded by the tie function.]

This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a hash. HASH is the name of the hash. (Unlike normal open, the first argument is not a filehandle, even though it looks like one). DBNAME is the name of the database (without the .dir or .pag extension if any). If the database does not exist, it is created with protection specified by MASK (as modified by the umask). If your system supports only the older DBM functions, you may perform only one dbmopen in your program. In older versions of Perl, if your system had neither DBM nor ndbm, calling dbmopen produced a fatal error; it now falls back to sdbm(3).

If you don't have write access to the DBM file, you can only read hash variables, not set them. If you want to test whether you can write, either use file tests or try setting a dummy hash entry inside an eval, which will trap the error.

Note that functions such as keys and values may return huge lists when used on large DBM files. You may prefer to use the each function to iterate over large DBM files. Example:

    # print out history file offsets
    dbmopen(%HIST,'/usr/lib/news/history',0666);
    while (($key,$val) = each %HIST) {
        print $key, ' = ', unpack('L',$val), "\n";
    }
    dbmclose(%HIST);

See also the AnyDBM_File manpage for a more general description of the pros and cons of the various dbm approaches, as well as DB_File for a particularly rich implementation.

You can control which DBM library you use by loading that library before you call dbmopen():

    use DB_File;
    dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
        or die "Can't open netscape history file: $!";
defined EXPR
defined

Returns a Boolean value telling whether EXPR has a value other than the undefined value undef. If EXPR is not present, $_ will be checked.

Many operations return undef to indicate failure, end of file, system error, uninitialized variable, and other exceptional conditions. This function allows you to distinguish undef from other values. (A simple Boolean test will not distinguish among undef, zero, the empty string, and "0", which are all equally false.) Note that since undef is a valid scalar, its presence doesn't necessarily indicate an exceptional condition: pop returns undef when its argument is an empty array, or when the element to return happens to be undef.

You may also use defined(&func) to check whether subroutine &func has ever been defined. The return value is unaffected by any forward declarations of &func. Note that a subroutine which is not defined may still be callable: its package may have an AUTOLOAD method that makes it spring into existence the first time that it is called -- see the perlsub manpage.

Use of defined on aggregates (hashes and arrays) is deprecated. It used to report whether memory for that aggregate has ever been allocated. This behavior may disappear in future versions of Perl. You should instead use a simple test for size:

    if (@an_array) { print "has array elements\n" }
    if (%a_hash)   { print "has hash members\n"   }

When used on a hash element, it tells you whether the value is defined, not whether the key exists in the hash. Use exists for the latter purpose.

Examples:

    print if defined $switch{'D'};
    print "$val\n" while defined($val = pop(@ary));
    die "Can't readlink $sym: $!"
        unless defined($value = readlink $sym);
    sub foo { defined &$bar ? &$bar(@_) : die "No bar"; }
    $debugging = 0 unless defined $debugging;

Note: Many folks tend to overuse defined, and then are surprised to discover that the number 0 and "" (the zero-length string) are, in fact, defined values. For example, if you say

    "ab" =~ /a(.*)b/;

The pattern match succeeds, and $1 is defined, despite the fact that it matched "nothing". It didn't really fail to match anything. Rather, it matched something that happened to be zero characters long. This is all very above-board and honest. When a function returns an undefined value, it's an admission that it couldn't give you an honest answer. So you should use defined only when you're questioning the integrity of what you're trying to do. At other times, a simple comparison to 0 or "" is what you want.

See also undef, exists, ref.

delete EXPR

Given an expression that specifies a hash element, array element, hash slice, or array slice, deletes the specified element(s) from the hash or array. In the case of an array, if the array elements happen to be at the end, the size of the array will shrink to the highest element that tests true for exists() (or 0 if no such element exists).

Returns a list with the same number of elements as the number of elements for which deletion was attempted. Each element of that list consists of either the value of the element deleted, or the undefined value. In scalar context, this means that you get the value of the last element deleted (or the undefined value if that element did not exist).

    %hash = (foo => 11, bar => 22, baz => 33);
    $scalar = delete $hash{foo};             # $scalar is 11
    $scalar = delete @hash{qw(foo bar)};     # $scalar is 22
    @array  = delete @hash{qw(foo bar baz)}; # @array  is (undef,undef,33)

Deleting from %ENV modifies the environment. Deleting from a hash tied to a DBM file deletes the entry from the DBM file. Deleting from a tied hash or array may not necessarily return anything.

Deleting an array element effectively returns that position of the array to its initial, uninitialized state. Subsequently testing for the same element with exists() will return false. Also, deleting array elements in the middle of an array will not shift the index of the elements after them down. Use splice() for that. See exists.

The following (inefficiently) deletes all the values of %HASH and @ARRAY:

    foreach $key (keys %HASH) {
        delete $HASH{$key};
    }

    foreach $index (0 .. $#ARRAY) {
        delete $ARRAY[$index];
    }

And so do these:

    delete @HASH{keys %HASH};

    delete @ARRAY[0 .. $#ARRAY];

But both of these are slower than just assigning the empty list or undefining %HASH or @ARRAY:

    %HASH = ();         # completely empty %HASH
    undef %HASH;        # forget %HASH ever existed

    @ARRAY = ();        # completely empty @ARRAY
    undef @ARRAY;       # forget @ARRAY ever existed

Note that the EXPR can be arbitrarily complicated as long as the final operation is a hash element, array element, hash slice, or array slice lookup:

    delete $ref->[$x][$y]{$key};
    delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};

    delete $ref->[$x][$y][$index];
    delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
die LIST

Outside an eval, prints the value of LIST to STDERR and exits with the current value of $! (errno). If $! is 0, exits with the value of ($? >> 8) (backtick `command` status). If ($? >> 8) is 0, exits with 255. Inside an eval(), the error message is stuffed into $@ and the eval is terminated with the undefined value. This makes die the way to raise an exception.

Equivalent examples:

    die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
    chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"

If the last element of LIST does not end in a newline, the current script line number and input line number (if any) are also printed, and a newline is supplied. Note that the "input line number" (also known as "chunk") is subject to whatever notion of "line" happens to be currently in effect, and is also available as the special variable $.. See $/ in the perlvar manpage and $. in the perlvar manpage.

Hint: sometimes appending ", stopped" to your message will cause it to make better sense when the string "at foo line 123" is appended. Suppose you are running script "canasta".

    die "/etc/games is no good";
    die "/etc/games is no good, stopped";

produce, respectively

    /etc/games is no good at canasta line 123.
    /etc/games is no good, stopped at canasta line 123.

See also exit(), warn(), and the Carp module.

If LIST is empty and $@ already contains a value (typically from a previous eval) that value is reused after appending "\t...propagated". This is useful for propagating exceptions:

    eval { ... };
    die unless $@ =~ /Expected exception/;

If LIST is empty and $@ contains an object reference that has a PROPAGATE method, that method will be called with additional file and line number parameters. The return value replaces the value in $@. i.e. as if $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; were called.

If $@ is empty then the string "Died" is used.

die() can also be called with a reference argument. If this happens to be trapped within an eval(), $@ contains the reference. This behavior permits a more elaborate exception handling implementation using objects that maintain arbitrary state about the nature of the exception. Such a scheme is sometimes preferable to matching particular string values of $@ using regular expressions. Here's an example:

    use Scalar::Util 'blessed';

    eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
    if ($@) {
        if (blessed($@) && $@->isa("Some::Module::Exception")) {
            # handle Some::Module::Exception
        }
        else {
            # handle all other possible exceptions
        }
    }

Because perl will stringify uncaught exception messages before displaying them, you may want to overload stringification operations on such custom exception objects. See the overload manpage for details about that.

You can arrange for a callback to be run just before the die does its deed, by setting the $SIG{__DIE__} hook. The associated handler will be called with the error text and can change the error message, if it sees fit, by calling die again. See $SIG{expr} in the perlvar manpage for details on setting %SIG entries, and eval BLOCK for some examples. Although this feature was to be run only right before your program was to exit, this is not currently the case--the $SIG{__DIE__} hook is currently called even inside eval()ed blocks/strings! If one wants the hook to do nothing in such situations, put

        die @_ if $^S;

as the first line of the handler (see $^S in the perlvar manpage). Because this promotes strange action at a distance, this counterintuitive behavior may be fixed in a future release.

do BLOCK

Not really a function. Returns the value of the last command in the sequence of commands indicated by BLOCK. When modified by the while or until loop modifier, executes the BLOCK once before testing the loop condition. (On other statements the loop modifiers test the conditional first.)

do BLOCK does not count as a loop, so the loop control statements next, last, or redo cannot be used to leave or restart the block. See the perlsyn manpage for alternative strategies.

do SUBROUTINE(LIST)

This form of subroutine call is deprecated. See the perlsub manpage.

do EXPR

Uses the value of EXPR as a filename and executes the contents of the file as a Perl script.

    do 'stat.pl';

is just like

    eval `cat stat.pl`;

except that it's more efficient and concise, keeps track of the current filename for error messages, searches the @INC directories, and updates %INC if the file is found. See Predefined Names in the perlvar manpage for these variables. It also differs in that code evaluated with do FILENAME cannot see lexicals in the enclosing scope; eval STRING does. It's the same, however, in that it does reparse the file every time you call it, so you probably don't want to do this inside a loop.

If do cannot read the file, it returns undef and sets $! to the error. If do can read the file but cannot compile it, it returns undef and sets an error message in $@. If the file is successfully compiled, do returns the value of the last expression evaluated.

Note that inclusion of library modules is better done with the use and require operators, which also do automatic error checking and raise an exception if there's a problem.

You might like to use do to read in a program configuration file. Manual error checking can be done this way:

    # read in config files: system first, then user
    for $file ("/share/prog/defaults.rc",
               "$ENV{HOME}/.someprogrc")
       {
        unless ($return = do $file) {
            warn "couldn't parse $file: $@" if $@;
            warn "couldn't do $file: $!"    unless defined $return;
            warn "couldn't run $file"       unless $return;
        }
    }
dump LABEL
dump

This function causes an immediate core dump. See also the -u command-line switch in the perlrun manpage, which does the same thing. Primarily this is so that you can use the undump program (not supplied) to turn your core dump into an executable binary after having initialized all your variables at the beginning of the program. When the new binary is executed it will begin by executing a goto LABEL (with all the restrictions that goto suffers). Think of it as a goto with an intervening core dump and reincarnation. If LABEL is omitted, restarts the program from the top.

WARNING: Any files opened at the time of the dump will not be open any more when the program is reincarnated, with possible resulting confusion on the part of Perl.

This function is now largely obsolete, partly because it's very hard to convert a core file into an executable, and because the real compiler backends for generating portable bytecode and compilable C code have superseded it. That's why you should now invoke it as CORE::dump(), if you don't want to be warned against a possible typo.

If you're looking to use dump to speed up your program, consider generating bytecode or native C code as described in perlcc. If you're just trying to accelerate a CGI script, consider using the mod_perl extension to Apache, or the CPAN module, CGI::Fast. You might also consider autoloading or selfloading, which at least make your program appear to run faster.

each HASH

When called in list context, returns a 2-element list consisting of the key and value for the next element of a hash, so that you can iterate over it. When called in scalar context, returns only the key for the next element in the hash.

Entries are returned in an apparently random order. The actual random order is subject to change in future versions of perl, but it is guaranteed to be in the same order as either the keys or values function would produce on the same (unmodified) hash. Since Perl 5.8.1 the ordering is different even between different runs of Perl for security reasons (see Algorithmic Complexity Attacks in the perlsec manpage).

When the hash is entirely read, a null array is returned in list context (which when assigned produces a false (0) value), and undef in scalar context. The next call to each after that will start iterating again. There is a single iterator for each hash, shared by all each, keys, and values function calls in the program; it can be reset by reading all the elements from the hash, or by evaluating keys HASH or values HASH. If you add or delete elements of a hash while you're iterating over it, you may get entries skipped or duplicated, so don't. Exception: It is always safe to delete the item most recently returned by each(), which means that the following code will work:

        while (($key, $value) = each %hash) {
          print $key, "\n";
          delete $hash{$key};   # This is safe
        }

The following prints out your environment like the printenv(1) program, only in a different order:

    while (($key,$value) = each %ENV) {
        print "$key=$value\n";
    }

See also keys, values and sort.

eof FILEHANDLE
eof ()
eof

Returns 1 if the next read on FILEHANDLE will return end of file, or if FILEHANDLE is not open. FILEHANDLE may be an expression whose value gives the real filehandle. (Note that this function actually reads a character and then ungetcs it, so isn't very useful in an interactive context.) Do not read from a terminal file (or call eof(FILEHANDLE) on it) after end-of-file is reached. File types such as terminals may lose the end-of-file condition if you do.

An eof without an argument uses the last file read. Using eof() with empty parentheses is very different. It refers to the pseudo file formed from the files listed on the command line and accessed via the <> operator. Since <> isn't explicitly opened, as a normal filehandle is, an eof() before <> has been used will cause @ARGV to be examined to determine if input is available. Similarly, an eof() after <> has returned end-of-file will assume you are processing another @ARGV list, and if you haven't set @ARGV, will read input from STDIN; see I/O Operators in the perlop manpage.

In a while (<>) loop, eof or eof(ARGV) can be used to detect the end of each file, eof() will only detect the end of the last file. Examples:

    # reset line numbering on each input file
    while (<>) {
        next if /^\s*#/;        # skip comments
        print "$.\t$_";
    } continue {
        close ARGV  if eof;     # Not eof()!
    }

    # insert dashes just before last line of last file
    while (<>) {
        if (eof()) {            # check for end of last file
            print "--------------\n";
        }
        print;
        last if eof();          # needed if we're reading from a terminal
    }

Practical hint: you almost never need to use eof in Perl, because the input operators typically return undef when they run out of data, or if there was an error.

eval EXPR
eval BLOCK
eval

In the first form, the return value of EXPR is parsed and executed as if it were a little Perl program. The value of the expression (which is itself determined within scalar context) is first parsed, and if there weren't any errors, executed in the lexical context of the current Perl program, so that any variable settings or subroutine and format definitions remain afterwards. Note that the value is parsed every time the eval executes. If EXPR is omitted, evaluates $_. This form is typically used to delay parsing and subsequent execution of the text of EXPR until run time.

In the second form, the code within the BLOCK is parsed only once--at the same time the code surrounding the eval itself was parsed--and executed within the context of the current Perl program. This form is typically used to trap exceptions more efficiently than the first (see below), while also providing the benefit of checking the code within BLOCK at compile time.

The final semicolon, if any, may be omitted from the value of EXPR or within the BLOCK.

In both forms, the value returned is the value of the last expression evaluated inside the mini-program; a return statement may be also used, just as with subroutines. The expression providing the return value is evaluated in void, scalar, or list context, depending on the context of the eval itself. See wantarray for more on how the evaluation context can be determined.

If there is a syntax error or runtime error, or a die statement is executed, an undefined value is returned by eval, and $@ is set to the error message. If there was no error, $@ is guaranteed to be a null string. Beware that using eval neither silences perl from printing warnings to STDERR, nor does it stuff the text of warning messages into $@. To do either of those, you have to use the $SIG{__WARN__} facility, or turn off warnings inside the BLOCK or EXPR using no warnings 'all'. See warn, the perlvar manpage, the warnings manpage and the perllexwarn manpage.

Note that, because eval traps otherwise-fatal errors, it is useful for determining whether a particular feature (such as socket or symlink) is implemented. It is also Perl's exception trapping mechanism, where the die operator is used to raise exceptions.

If the code to be executed doesn't vary, you may use the eval-BLOCK form to trap run-time errors without incurring the penalty of recompiling each time. The error, if any, is still returned in $@. Examples:

    # make divide-by-zero nonfatal
    eval { $answer = $a / $b; }; warn $@ if $@;

    # same thing, but less efficient
    eval '$answer = $a / $b'; warn $@ if $@;

    # a compile-time error
    eval { $answer = };                 # WRONG

    # a run-time error
    eval '$answer =';   # sets $@

Using the eval{} form as an exception trap in libraries does have some issues. Due to the current arguably broken state of __DIE__ hooks, you may wish not to trigger any __DIE__ hooks that user code may have installed. You can use the local $SIG{__DIE__} construct for this purpose, as shown in this example:

    # a very private exception trap for divide-by-zero
    eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
    warn $@ if $@;

This is especially significant, given that __DIE__ hooks can call die again, which has the effect of changing their error messages:

    # __DIE__ hooks may modify error messages
    {
       local $SIG{'__DIE__'} =
              sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
       eval { die "foo lives here" };
       print $@ if $@;                # prints "bar lives here"
    }

Because this promotes action at a distance, this counterintuitive behavior may be fixed in a future release.

With an eval, you should be especially careful to remember what's being looked at when:

    eval $x;            # CASE 1
    eval "$x";          # CASE 2

    eval '$x';          # CASE 3
    eval { $x };        # CASE 4

    eval "\$$x++";      # CASE 5
    $$x++;              # CASE 6

Cases 1 and 2 above behave identically: they run the code contained in the variable $x. (Although case 2 has misleading double quotes making the reader wonder what else might be happening (nothing is).) Cases 3 and 4 likewise behave in the same way: they run the code '$x', which does nothing but return the value of $x. (Case 4 is preferred for purely visual reasons, but it also has the advantage of compiling at compile-time instead of at run-time.) Case 5 is a place where normally you would like to use double quotes, except that in this particular situation, you can just use symbolic references instead, as in case 6.

eval BLOCK does not count as a loop, so the loop control statements next, last, or redo cannot be used to leave or restart the block.

Note that as a very special case, an eval '' executed within the DB package doesn't see the usual surrounding lexical scope, but rather the scope of the first non-DB piece of code that called it. You don't normally need to worry about this unless you are writing a Perl debugger.

exec LIST
exec PROGRAM LIST

The exec function executes a system command and never returns-- use system instead of exec if you want it to return. It fails and returns false only if the command does not exist and it is executed directly instead of via your system's command shell (see below).

Since it's a common mistake to use exec instead of system, Perl warns you if there is a following statement which isn't die, warn, or exit (if -w is set - but you always do that). If you really want to follow an exec with some other statement, you can use one of these styles to avoid the warning:

    exec ('foo')   or print STDERR "couldn't exec foo: $!";
    { exec ('foo') }; print STDERR "couldn't exec foo: $!";

If there is more than one argument in LIST, or if LIST is an array with more than one value, calls execvp(3) with the arguments in LIST. If there is only one scalar argument or an array with one element in it, the argument is checked for shell metacharacters, and if there are any, the entire argument is passed to the system's command shell for parsing (this is /bin/sh -c on Unix platforms, but varies on other platforms). If there are no shell metacharacters in the argument, it is split into words and passed directly to execvp, which is more efficient. Examples:

    exec '/bin/echo', 'Your arguments are: ', @ARGV;
    exec "sort $outfile | uniq";

If you don't really want to execute the first argument, but want to lie to the program you are executing about its own name, you can specify the program you actually want to run as an "indirect object" (without a comma) in front of the LIST. (This always forces interpretation of the LIST as a multivalued list, even if there is only a single scalar in the list.) Example:

    $shell = '/bin/csh';
    exec $shell '-sh';          # pretend it's a login shell

or, more directly,

    exec {'/bin/csh'} '-sh';    # pretend it's a login shell

When the arguments get executed via the system shell, results will be subject to its quirks and capabilities. See `STRING` in the perlop manpage for details.

Using an indirect object with exec or system is also more secure. This usage (which also works fine with system()) forces interpretation of the arguments as a multivalued list, even if the list had just one argument. That way you're safe from the shell expanding wildcards or splitting up words with whitespace in them.

    @args = ( "echo surprise" );

    exec @args;               # subject to shell escapes
                                # if @args == 1
    exec { $args[0] } @args;  # safe even with one-arg list

The first version, the one without the indirect object, ran the echo program, passing it "surprise" an argument. The second version didn't--it tried to run a program literally called "echo surprise", didn't find it, and set $? to a non-zero value indicating failure.

Beginning with v5.6.0, Perl will attempt to flush all files opened for output before the exec, but this may not be supported on some platforms (see the perlport manpage). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles in order to avoid lost output.

Note that exec will not call your END blocks, nor will it call any DESTROY methods in your objects.

exists EXPR

Given an expression that specifies a hash element or array element, returns true if the specified element in the hash or array has ever been initialized, even if the corresponding value is undefined. The element is not autovivified if it doesn't exist.

    print "Exists\n"    if exists $hash{$key};
    print "Defined\n"   if defined $hash{$key};
    print "True\n"      if $hash{$key};

    print "Exists\n"    if exists $array[$index];
    print "Defined\n"   if defined $array[$index];
    print "True\n"      if $array[$index];

A hash or array element can be true only if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true.

Given an expression that specifies the name of a subroutine, returns true if the specified subroutine has ever been declared, even if it is undefined. Mentioning a subroutine name for exists or defined does not count as declaring it. Note that a subroutine which does not exist may still be callable: its package may have an AUTOLOAD method that makes it spring into existence the first time that it is called -- see the perlsub manpage.

    print "Exists\n"    if exists &subroutine;
    print "Defined\n"   if defined &subroutine;

Note that the EXPR can be arbitrarily complicated as long as the final operation is a hash or array key lookup or subroutine name:

    if (exists $ref->{A}->{B}->{$key})  { }
    if (exists $hash{A}{B}{$key})       { }

    if (exists $ref->{A}->{B}->[$ix])   { }
    if (exists $hash{A}{B}[$ix])        { }

    if (exists &{$ref->{A}{B}{$key}})   { }

Although the deepest nested array or hash will not spring into existence just because its existence was tested, any intervening ones will. Thus $ref->{"A"} and $ref->{"A"}->{"B"} will spring into existence due to the existence test for the $key element above. This happens anywhere the arrow operator is used, including even:

    undef $ref;
    if (exists $ref->{"Some key"})      { }
    print $ref;             # prints HASH(0x80d3d5c)

This surprising autovivification in what does not at first--or even second--glance appear to be an lvalue context may be fixed in a future release.

See Pseudo-hashes: Using an array as a hash in the perlref manpage for specifics on how exists() acts when used on a pseudo-hash.

Use of a subroutine call, rather than a subroutine name, as an argument to exists() is an error.

    exists &sub;        # OK
    exists &sub();      # Error
exit EXPR
exit

Evaluates EXPR and exits immediately with that value. Example:

    $ans = <STDIN>;
    exit 0 if $ans =~ /^[Xx]/;

See also die. If EXPR is omitted, exits with 0 status. The only universally recognized values for EXPR are 0 for success and 1 for error; other values are subject to interpretation depending on the environment in which the Perl program is running. For example, exiting 69 (EX_UNAVAILABLE) from a sendmail incoming-mail filter will cause the mailer to return the item undelivered, but that's not true everywhere.

Don't use exit to abort a subroutine if there's any chance that someone might want to trap whatever error happened. Use die instead, which can be trapped by an eval.

The exit() function does not always exit immediately. It calls any defined END routines first, but these END routines may not themselves abort the exit. Likewise any object destructors that need to be called are called before the real exit. If this is a problem, you can call POSIX:_exit($status) to avoid END and destructor processing. See the perlmod manpage for details.

exp EXPR
exp

Returns e (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives exp($_).

fcntl FILEHANDLE,FUNCTION,SCALAR

Implements the fcntl(2) function. You'll probably have to say

    use Fcntl;

first to get the correct constant definitions. Argument processing and value return works just like ioctl below. For example:

    use Fcntl;
    fcntl($filehandle, F_GETFL, $packed_return_buffer)
        or die "can't fcntl F_GETFL: $!";

You don't have to check for defined on the return from fcntl. Like ioctl, it maps a 0 return from the system call into "0 but true" in Perl. This string is true in boolean context and 0 in numeric context. It is also exempt from the normal -w warnings on improper numeric conversions.

Note that fcntl will produce a fatal error if used on a machine that doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) manpage to learn what functions are available on your system.

Here's an example of setting a filehandle named REMOTE to be non-blocking at the system level. You'll have to negotiate $| on your own, though.

    use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);

    $flags = fcntl(REMOTE, F_GETFL, 0)
                or die "Can't get flags for the socket: $!\n";

    $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
                or die "Can't set flags for the socket: $!\n";
fileno FILEHANDLE

Returns the file descriptor for a filehandle, or undefined if the filehandle is not open. This is mainly useful for constructing bitmaps for select and low-level POSIX tty-handling operations. If FILEHANDLE is an expression, the value is taken as an indirect filehandle, generally its name.

You can use this to find out whether two handles refer to the same underlying descriptor:

    if (fileno(THIS) == fileno(THAT)) {
        print "THIS and THAT are dups\n";
    }

(Filehandles connected to memory objects via new features of open may return undefined even though they are open.)

flock FILEHANDLE,OPERATION

Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true for success, false on failure. Produces a fatal error if used on a machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). flock is Perl's portable file locking interface, although it locks only entire files, not records.

Two potentially non-obvious but traditional flock semantics are that it waits indefinitely until the lock is granted, and that its locks merely advisory. Such discretionary locks are more flexible, but offer fewer guarantees. This means that programs that do not also use flock may modify files locked with flock. See the perlport manpage, your port's specific documentation, or your system-specific local manpages for details. It's best to assume traditional behavior if you're writing portable programs. (But if you're not, you should as always feel perfectly free to write for your own system's idiosyncrasies (sometimes called "features"). Slavish adherence to portability concerns shouldn't get in the way of your getting your job done.)

OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but you can use the symbolic names if you import them from the Fcntl module, either individually, or as a group using the ':flock' tag. LOCK_SH requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN releases a previously requested lock. If LOCK_NB is bitwise-or'ed with LOCK_SH or LOCK_EX then flock will return immediately rather than blocking waiting for the lock (check the return status to see if you got it).

To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE before locking or unlocking it.

Note that the emulation built with lockf(3) doesn't provide shared locks, and it requires that FILEHANDLE be open with write intent. These are the semantics that lockf(3) implements. Most if not all systems implement lockf(3) in terms of fcntl(2) locking, though, so the differing semantics shouldn't bite too many people.

Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE be open with read intent to use LOCK_SH and requires that it be open with write intent to use LOCK_EX.

Note also that some versions of flock cannot lock things over the network; you would need to use the more system-specific fcntl for that. If you like you can force Perl to ignore your system's flock(2) function, and so provide its own fcntl(2)-based emulation, by passing the switch -Ud_flock to the Configure program when you configure perl.

Here's a mailbox appender for BSD systems.

    use Fcntl ':flock'; # import LOCK_* constants

    sub lock {
        flock(MBOX,LOCK_EX);
        # and, in case someone appended
        # while we were waiting...
        seek(MBOX, 0, 2);
    }

    sub unlock {
        flock(MBOX,LOCK_UN);
    }

    open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
            or die "Can't open mailbox: $!";

    lock();
    print MBOX $msg,"\n\n";
    unlock();

On systems that support a real flock(), locks are inherited across fork() calls, whereas those that must resort to the more capricious fcntl() function lose the locks, making it harder to write servers.

See also DB_File for other flock() examples.

fork

Does a fork(2) system call to create a new process running the same program at the same point. It returns the child pid to the parent process, 0 to the child process, or undef if the fork is unsuccessful. File descriptors (and sometimes locks on those descriptors) are shared, while everything else is copied. On most systems supporting fork(), great care has gone into making it extremely efficient (for example, using copy-on-write technology on data pages), making it the dominant paradigm for multitasking over the last few decades.

Beginning with v5.6.0, Perl will attempt to flush all files opened for output before forking the child process, but this may not be supported on some platforms (see the perlport manpage). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles in order to avoid duplicate output.

If you fork without ever waiting on your children, you will accumulate zombies. On some systems, you can avoid this by setting $SIG{CHLD} to "IGNORE". See also the perlipc manpage for more examples of forking and reaping moribund children.

Note that if your forked child inherits system file descriptors like STDIN and STDOUT that are actually connected by a pipe or socket, even if you exit, then the remote server (such as, say, a CGI script or a backgrounded job launched from a remote shell) won't think you're done. You should reopen those to /dev/null if it's any issue.

format

Declare a picture format for use by the write function. For example:

    format Something =
        Test: @<<<<<<<< @||||| @>>>>>
              $str,     $%,    '$' . int($num)
    .
    $str = "widget";
    $num = $cost/$quantity;
    $~ = 'Something';
    write;

See the perlform manpage for many details and examples.

formline PICTURE,LIST

This is an internal function used by formats, though you may call it, too. It formats (see the perlform manpage) a list of values according to the contents of PICTURE, placing the output into the format output accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a write is done, the contents of $^A are written to some filehandle. You could also read $^A and then set $^A back to "". Note that a format typically does one formline per line of form, but the formline function itself doesn't care how many newlines are embedded in the PICTURE. This means that the ~ and ~~ tokens will treat the entire PICTURE as a single line. You may therefore need to use multiple formlines to implement a single record format, just like the format compiler.

Be careful if you put double quotes around the picture, because an @ character may be taken to mean the beginning of an array name. formline always returns true. See the perlform manpage for other examples.

getc FILEHANDLE
getc

Returns the next character from the input file attached to FILEHANDLE, or the undefined value at end of file, or if there was an error (in the latter case $! is set). If FILEHANDLE is omitted, reads from STDIN. This is not particularly efficient. However, it cannot be used by itself to fetch single characters without waiting for the user to hit enter. For that, try something more like:

    if ($BSD_STYLE) {
        system "stty cbreak </dev/tty >/dev/tty 2>&1";
    }
    else {
        system "stty", '-icanon', 'eol', "\001";
    }

    $key = getc(STDIN);

    if ($BSD_STYLE) {
        system "stty -cbreak </dev/tty >/dev/tty 2>&1";
    }
    else {
        system "stty", 'icanon', 'eol', '^@'; # ASCII null
    }
    print "\n";

Determination of whether $BSD_STYLE should be set is left as an exercise to the reader.

The POSIX::getattr function can do this more portably on systems purporting POSIX compliance. See also the Term::ReadKey module from your nearest CPAN site; details on CPAN can be found on CPAN in the perlmodlib manpage.

getlogin

This implements the C library function of the same name, which on most systems returns the current login from /etc/utmp, if any. If null, use getpwuid.

    $login = getlogin || getpwuid($<) || "Kilroy";

Do not consider getlogin for authentication: it is not as secure as getpwuid.

getpeername SOCKET

Returns the packed sockaddr address of other end of the SOCKET connection.

    use Socket;
    $hersockaddr    = getpeername(SOCK);
    ($port, $iaddr) = sockaddr_in($hersockaddr);
    $herhostname    = gethostbyaddr($iaddr, AF_INET);
    $herstraddr     = inet_ntoa($iaddr);
getpgrp PID

Returns the current process group for the specified PID. Use a PID of 0 to get the current process group for the current process. Will raise an exception if used on a machine that doesn't implement getpgrp(2). If PID is omitted, returns process group of current process. Note that the POSIX version of getpgrp does not accept a PID argument, so only PID==0 is truly portable.

getppid

Returns the process id of the parent process.

Note for Linux users: on Linux, the C functions getpid() and getppid() return different values from different threads. In order to be portable, this behavior is not reflected by the perl-level function getppid(), that returns a consistent value across threads. If you want to call the underlying getppid(), you may use the CPAN module Linux::Pid.

getpriority WHICH,WHO

Returns the current priority for a process, a process group, or a user. (See getpriority(2).) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2).

getpwnam NAME
getgrnam NAME
gethostbyname NAME
getnetbyname NAME
getprotobyname NAME
getpwuid UID
getgrgid GID
getservbyname NAME,PROTO
gethostbyaddr ADDR,ADDRTYPE
getnetbyaddr ADDR,ADDRTYPE
getprotobynumber NUMBER
getservbyport PORT,PROTO
getpwent
getgrent
gethostent
getnetent
getprotoent
getservent
setpwent
setgrent
sethostent STAYOPEN
setnetent STAYOPEN
setprotoent STAYOPEN
setservent STAYOPEN
endpwent
endgrent
endhostent
endnetent
endprotoent
endservent

These routines perform the same functions as their counterparts in the system library. In list context, the return values from the various get routines are as follows:

    ($name,$passwd,$uid,$gid,
       $quota,$comment,$gcos,$dir,$shell,$expire) = getpw*
    ($name,$passwd,$gid,$members) = getgr*
    ($name,$aliases,$addrtype,$length,@addrs) = gethost*
    ($name,$aliases,$addrtype,$net) = getnet*
    ($name,$aliases,$proto) = getproto*
    ($name,$aliases,$port,$proto) = getserv*

(If the entry doesn't exist you get a null list.)

The exact meaning of the $gcos field varies but it usually contains the real name of the user (as opposed to the login name) and other information pertaining to the user. Beware, however, that in many system users are able to change this information and therefore it cannot be trusted and therefore the $gcos is tainted (see the perlsec manpage). The $passwd and $shell, user's encrypted password and login shell, are also tainted, because of the same reason.

In scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. (If the entry doesn't exist you get the undefined value.) For example:

    $uid   = getpwnam($name);
    $name  = getpwuid($num);
    $name  = getpwent();
    $gid   = getgrnam($name);
    $name  = getgrgid($num);
    $name  = getgrent();
    #etc.

In getpw*() the fields $quota, $comment, and $expire are special cases in the sense that in many systems they are unsupported. If the $quota is unsupported, it is an empty scalar. If it is supported, it usually encodes the disk quota. If the $comment field is unsupported, it is an empty scalar. If it is supported it usually encodes some administrative comment about the user. In some systems the $quota field may be $change or $age, fields that have to do with password aging. In some systems the $comment field may be $class. The $expire field, if present, encodes the expiration period of the account or the password. For the availability and the exact meaning of these fields in your system, please consult your getpwnam(3) documentation and your pwd.h file. You can also find out from within Perl what your $quota and $comment fields mean and whether you have the $expire field by using the Config module and the values d_pwquota, d_pwage, d_pwchange, d_pwcomment, and d_pwexpire. Shadow password files are only supported if your vendor has implemented them in the intuitive fashion that calling the regular C library routines gets the shadow versions if you're running under privilege or if there exists the shadow(3) functions as found in System V (this includes Solaris and Linux.) Those systems that implement a proprietary shadow password facility are unlikely to be supported.

The $members value returned by getgr*() is a space separated list of the login names of the members of the group.

For the gethost*() functions, if the h_errno variable is supported in C, it will be returned to you via $? if the function call fails. The @addrs value returned by a successful call is a list of the raw addresses returned by the corresponding system library call. In the Internet domain, each address is four bytes long and you can unpack it by saying something like:

    ($a,$b,$c,$d) = unpack('C4',$addr[0]);

The Socket library makes this slightly easier:

    use Socket;
    $iaddr = inet_aton("127.1"); # or whatever address
    $name  = gethostbyaddr($iaddr, AF_INET);

    # or going the other way
    $straddr = inet_ntoa($iaddr);

If you get tired of remembering which element of the return list contains which return value, by-name interfaces are provided in standard modules: File::stat, Net::hostent, Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime, and User::grent. These override the normal built-ins, supplying versions that return objects with the appropriate names for each field. For example:

   use File::stat;
   use User::pwent;
   $is_his = (stat($filename)->uid == pwent($whoever)->uid);

Even though it looks like they're the same method calls (uid), they aren't, because a File::stat object is different from a User::pwent object.

getsockname SOCKET

Returns the packed sockaddr address of this end of the SOCKET connection, in case you don't know the address because you have several different IPs that the connection might have come in on.

    use Socket;
    $mysockaddr = getsockname(SOCK);
    ($port, $myaddr) = sockaddr_in($mysockaddr);
    printf "Connect to %s [%s]\n",
       scalar gethostbyaddr($myaddr, AF_INET),
       inet_ntoa($myaddr);
getsockopt SOCKET,LEVEL,OPTNAME

Queries the option named OPTNAME associated with SOCKET at a given LEVEL. Options may exist at multiple protocol levels depending on the socket type, but at least the uppermost socket level SOL_SOCKET (defined in the Socket module) will exist. To query options at another level the protocol number of the appropriate protocol controlling the option should be supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, LEVEL should be set to the protocol number of TCP, which you can get using getprotobyname.

The call returns a packed string representing the requested socket option, or undef if there is an error (the error reason will be in $!). What exactly is in the packed string depends in the LEVEL and OPTNAME, consult your system documentation for details. A very common case however is that the option is an integer, in which case the result will be a packed integer which you can decode using unpack with the i (or I) format.

An example testing if Nagle's algorithm is turned on on a socket:

    use Socket qw(:all);

    defined(my $tcp = getprotobyname("tcp"))
        or die "Could not determine the protocol number for tcp";
    # my $tcp = IPPROTO_TCP; # Alternative
    my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
        or die "Could not query TCP_NODELAY socket option: $!";
    my $nodelay = unpack("I", $packed);
    print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
glob EXPR
glob

In list context, returns a (possibly empty) list of filename expansions on the value of EXPR such as the standard Unix shell /bin/csh would do. In scalar context, glob iterates through such filename expansions, returning undef when the list is exhausted. This is the internal function implementing the <*.c> operator, but you can use it directly. If EXPR is omitted, $_ is used. The <*.c> operator is discussed in more detail in I/O Operators in the perlop manpage.

Beginning with v5.6.0, this operator is implemented using the standard File::Glob extension. See the File::Glob manpage for details.

gmtime EXPR
gmtime

Converts a time as returned by the time function to an 9-element list with the time localized for the standard Greenwich time zone. Typically used as follows:

    #  0    1    2     3     4    5     6     7     8
    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                            gmtime(time);

All list elements are numeric, and come straight out of the C `struct tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the specified time. $mday is the day of the month, and $mon is the month itself, in the range 0..11 with 0 indicating January and 11 indicating December. $year is the number of years since 1900. That is, $year is 123 in year 2023. $wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of the year, in the range 0..364 (or 0..365 in leap years). $isdst is always 0.

Note that the $year element is not simply the last two digits of the year. If you assume it is then you create non-Y2K-compliant programs--and you wouldn't want to do that, would you?

The proper way to get a complete 4-digit year is simply:

        $year += 1900;

And to get the last two digits of the year (e.g., '01' in 2001) do:

        $year = sprintf("%02d", $year % 100);

If EXPR is omitted, gmtime() uses the current time (gmtime(time)).

In scalar context, gmtime() returns the ctime(3) value:

    $now_string = gmtime;  # e.g., "Thu Oct 13 04:54:34 1994"

If you need local time instead of GMT use the localtime builtin. See also the timegm function provided by the Time::Local module, and the strftime(3) and mktime(3) functions available via the the POSIX manpage module.

This scalar value is not locale dependent (see the perllocale manpage), but is instead a Perl builtin. To get somewhat similar but locale dependent date strings, see the example in localtime.

See gmtime in the perlport manpage for portability concerns.

goto LABEL
goto EXPR
goto &NAME

The goto-LABEL form finds the statement labeled with LABEL and resumes execution there. It may not be used to go into any construct that requires initialization, such as a subroutine or a foreach loop. It also can't be used to go into a construct that is optimized away, or to get out of a block or subroutine given to sort. It can be used to go almost anywhere else within the dynamic scope, including out of subroutines, but it's usually better to use some other construct such as last or die. The author of Perl has never felt the need to use this form of goto (in Perl, that is--C is another matter). (The difference being that C does not offer named loops combined with loop control. Perl does, and this replaces most structured uses of goto in other languages.)

The goto-EXPR form expects a label name, whose scope will be resolved dynamically. This allows for computed gotos per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability:

    goto ("FOO", "BAR", "GLARCH")[$i];

The goto-&NAME form is quite different from the other forms of goto. In fact, it isn't a goto in the normal sense at all, and doesn't have the stigma associated with other gotos. Instead, it exits the current subroutine (losing any changes set by local()) and immediately calls in its place the named subroutine using the current value of @_. This is used by AUTOLOAD subroutines that wish to load another subroutine and then pretend that the other subroutine had been called in the first place (except that any modifications to @_ in the current subroutine are propagated to the other subroutine.) After the goto, not even caller will be able to tell that this routine was called first.

NAME needn't be the name of a subroutine; it can be a scalar variable containing a code reference, or a block that evaluates to a code reference.

grep BLOCK LIST
grep EXPR,LIST

This is similar in spirit to, but not the same as, grep(1) and its relatives. In particular, it is not limited to using regular expressions.

Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each element) and returns the list value consisting of those elements for which the expression evaluated to true. In scalar context, returns the number of times the expression was true.

    @foo = grep(!/^#/, @bar);    # weed out comments

or equivalently,

    @foo = grep {!/^#/} @bar;    # weed out comments

Note that $_ is an alias to the list value, so it can be used to modify the elements of the LIST. While this is useful and supported, it can cause bizarre results if the elements of LIST are not variables. Similarly, grep returns aliases into the original list, much as a for loop's index variable aliases the list elements. That is, modifying an element of a list returned by grep (for example, in a foreach, map or another grep) actually modifies the element in the original list. This is usually something to be avoided when writing clear code.

See also map for a list composed of the results of the BLOCK or EXPR.

hex EXPR
hex

Interprets EXPR as a hex string and returns the corresponding value. (To convert strings that might start with either 0, 0x, or 0b, see oct.) If EXPR is omitted, uses $_.

    print hex '0xAf'; # prints '175'
    print hex 'aF';   # same

Hex strings may only represent integers. Strings that would cause integer overflow trigger a warning. Leading whitespace is not stripped, unlike oct(). To present something as hex, look into printf, sprintf, or unpack.

import LIST

There is no builtin import function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The use function calls the import method for the package used. See also use, the perlmod manpage, and the Exporter manpage.

index STR,SUBSTR,POSITION
index STR,SUBSTR

The index function searches for one string within another, but without the wildcard-like behavior of a full regular-expression pattern match. It returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. POSITION before the beginning of the string or after its end is treated as if it were the beginning or the end, respectively. POSITION and the return value are based at 0 (or whatever you've set the $[ variable to--but don't do that). If the substring is not found, index returns one less than the base, ordinarily -1.

int EXPR
int

Returns the integer portion of EXPR. If EXPR is omitted, uses $_. You should not use this function for rounding: one because it truncates towards 0, and two because machine representations of floating point numbers can sometimes produce counterintuitive results. For example, int(-6.725/0.025) produces -268 rather than the correct -269; that's because it's really more like -268.99999999999994315658 instead. Usually, the sprintf, printf, or the POSIX::floor and POSIX::ceil functions will serve you better than will int().

ioctl FILEHANDLE,FUNCTION,SCALAR

Implements the ioctl(2) function. You'll probably first have to say

    require "sys/ioctl.ph";     # probably in $Config{archlib}/sys/ioctl.ph

to get the correct function definitions. If sys/ioctl.ph doesn't exist or doesn't have the correct definitions you'll have to roll your own, based on your C header files such as <sys/ioctl.h >>. (There is a Perl script called h2ph that comes with the Perl kit that may help you in this, but it's nontrivial.) SCALAR will be read and/or written depending on the FUNCTION--a pointer to the string value of SCALAR will be passed as the third argument of the actual ioctl call. (If SCALAR has no string value but does have a numeric value, that value will be passed rather than a pointer to the string value. To guarantee this to be true, add a 0 to the scalar before using it.) The pack and unpack functions may be needed to manipulate the values of structures used by ioctl.

The return value of ioctl (and fcntl) is as follows:

        if OS returns:          then Perl returns:
            -1                    undefined value
             0                  string "0 but true"
        anything else               that number

Thus Perl returns true on success and false on failure, yet you can still easily determine the actual value returned by the operating system:

    $retval = ioctl(...) || -1;
    printf "System returned %d\n", $retval;

The special string "0 but true" is exempt from -w complaints about improper numeric conversions.

join EXPR,LIST

Joins the separate strings of LIST into a single string with fields separated by the value of EXPR, and returns that new string. Example:

    $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);

Beware that unlike split, join doesn't take a pattern as its first argument. Compare split.

keys HASH

Returns a list consisting of all the keys of the named hash. (In scalar context, returns the number of keys.)

The keys are returned in an apparently random order. The actual random order is subject to change in future versions of perl, but it is guaranteed to be the same order as either the values or each function produces (given that the hash has not been modified). Since Perl 5.8.1 the ordering is different even between different runs of Perl for security reasons (see Algorithmic Complexity Attacks in the perlsec manpage).

As a side effect, calling keys() resets the HASH's internal iterator (see each). In particular, calling keys() in void context resets the iterator with no other overhead.

Here is yet another way to print your environment:

    @keys = keys %ENV;
    @values = values %ENV;
    while (@keys) {
        print pop(@keys), '=', pop(@values), "\n";
    }

or how about sorted by key:

    foreach $key (sort(keys %ENV)) {
        print $key, '=', $ENV{$key}, "\n";
    }

The returned values are copies of the original keys in the hash, so modifying them will not affect the original hash. Compare values.

To sort a hash by value, you'll need to use a sort function. Here's a descending numeric sort of a hash by its values:

    foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
        printf "%4d %s\n", $hash{$key}, $key;
    }

As an lvalue keys allows you to increase the number of hash buckets allocated for the given hash. This can gain you a measure of efficiency if you know the hash is going to get big. (This is similar to pre-extending an array by assigning a larger number to $#array.) If you say

    keys %hash = 200;

then %hash will have at least 200 buckets allocated for it--256 of them, in fact, since it rounds up to the next power of two. These buckets will be retained even if you do %hash = (), use undef %hash if you want to free the storage while %hash is still in scope. You can't shrink the number of buckets allocated for the hash using keys in this way (but you needn't worry about doing this by accident, as trying has no effect).

See also each, values and sort.

kill SIGNAL, LIST

Sends a signal to a list of processes. Returns the number of processes successfully signaled (which is not necessarily the same as the number actually killed).

    $cnt = kill 1, $child1, $child2;
    kill 9, @goners;

If SIGNAL is zero, no signal is sent to the process. This is a useful way to check that a child process is alive and hasn't changed its UID. See the perlport manpage for notes on the portability of this construct.

Unlike in the shell, if SIGNAL is negative, it kills process groups instead of processes. (On System V, a negative PROCESS number will also kill process groups, but that's not portable.) That means you usually want to use positive not negative signals. You may also use a signal name in quotes.

See Signals in the perlipc manpage for more details.

last LABEL
last

The last command is like the break statement in C (as used in loops); it immediately exits the loop in question. If the LABEL is omitted, the command refers to the innermost enclosing loop. The continue block, if any, is not executed:

    LINE: while (<STDIN>) {
        last LINE if /^$/;      # exit when done with header
        #...
    }

last cannot be used to exit a block which returns a value such as eval {}, sub {} or do {}, and should not be used to exit a grep() or map() operation.

Note that a block by itself is semantically identical to a loop that executes once. Thus last can be used to effect an early exit out of such a block.

See also continue for an illustration of how last, next, and redo work.

lc EXPR
lc

Returns a lowercased version of EXPR. This is the internal function implementing the \L escape in double-quoted strings. Respects current LC_CTYPE locale if use locale in force. See the perllocale manpage and the perlunicode manpage for more details about locale and Unicode support.

If EXPR is omitted, uses $_.

lcfirst EXPR
lcfirst

Returns the value of EXPR with the first character lowercased. This is the internal function implementing the \l escape in double-quoted strings. Respects current LC_CTYPE locale if use locale in force. See the perllocale manpage and the perlunicode manpage for more details about locale and Unicode support.

If EXPR is omitted, uses $_.

length EXPR
length

Returns the length in characters of the value of EXPR. If EXPR is omitted, returns length of $_. Note that this cannot be used on an entire array or hash to find out how many elements these have. For that, use scalar @array and scalar keys %hash respectively.

Note the characters: if the EXPR is in Unicode, you will get the number of characters, not the number of bytes. To get the length in bytes, use do { use bytes; length(EXPR) }, see the bytes manpage.

link OLDFILE,NEWFILE

Creates a new filename linked to the old filename. Returns true for success, false otherwise.

listen SOCKET,QUEUESIZE

Does the same thing that the listen system call does. Returns true if it succeeded, false otherwise. See the example in Sockets: Client/Server Communication in the perlipc manpage.

local EXPR

You really probably want to be using my instead, because local isn't what most people think of as "local". See Private Variables via my() in the perlsub manpage for details.

A local modifies the listed variables to be local to the enclosing block, file, or eval. If more than one value is listed, the list must be placed in parentheses. See Temporary Values via local() in the perlsub manpage for details, including issues with tied arrays and hashes.

localtime EXPR
localtime

Converts a time as returned by the time function to a 9-element list with the time analyzed for the local time zone. Typically used as follows:

    #  0    1    2     3     4    5     6     7     8
    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
                                                localtime(time);

All list elements are numeric, and come straight out of the C `struct tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the specified time.

$mday is the day of the month, and $mon is the month itself, in the range 0..11 with 0 indicating January and 11 indicating December. This makes it easy to get a month name from a list:

    my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
    print "$abbr[$mon] $mday";
    # $mon=9, $mday=18 gives "Oct 18"

$year is the number of years since 1900, not just the last two digits of the year. That is, $year is 123 in year 2023. The proper way to get a complete 4-digit year is simply:

    $year += 1900;

To get the last two digits of the year (e.g., '01' in 2001) do:

    $year = sprintf("%02d", $year % 100);

$wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of the year, in the range 0..364 (or 0..365 in leap years.)

$isdst is true if the specified time occurs during Daylight Saving Time, false otherwise.

If EXPR is omitted, localtime() uses the current time (localtime(time)).

In scalar context, localtime() returns the ctime(3) value:

    $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"

This scalar value is not locale dependent but is a Perl builtin. For GMT instead of local time use the gmtime builtin. See also the Time::Local module (to convert the second, minutes, hours, ... back to the integer value returned by time()), and the the POSIX manpage module's strftime(3) and mktime(3) functions.

To get somewhat similar but locale dependent date strings, set up your locale environment variables appropriately (please see the perllocale manpage) and try for example:

    use POSIX qw(strftime);
    $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
    # or for GMT formatted appropriately for your locale:
    $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;

Note that the %a and %b, the short forms of the day of the week and the month of the year, may not necessarily be three characters wide.

See localtime in the perlport manpage for portability concerns.

lock THING

This function places an advisory lock on a shared variable, or referenced object contained in THING until the lock goes out of scope.

lock() is a "weak keyword" : this means that if you've defined a function by this name (before any calls to it), that function will be called instead. (However, if you've said use threads, lock() is always a keyword.) See the threads manpage.

log EXPR
log

Returns the natural logarithm (base e) of EXPR. If EXPR is omitted, returns log of $_. To get the log of another base, use basic algebra: The base-N log of a number is equal to the natural log of that number divided by the natural log of N. For example:

    sub log10 {
        my $n = shift;
        return log($n)/log(10);
    }

See also exp for the inverse operation.

lstat EXPR
lstat

Does the same thing as the stat function (including setting the special _ filehandle) but stats a symbolic link instead of the file the symbolic link points to. If symbolic links are unimplemented on your system, a normal stat is done. For much more detailed information, please see the documentation for stat.

If EXPR is omitted, stats $_.

m//

The match operator. See the perlop manpage.

map BLOCK LIST
map EXPR,LIST

Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each element) and returns the list value composed of the results of each such evaluation. In scalar context, returns the total number of elements so generated. Evaluates BLOCK or EXPR in list context, so each element of LIST may produce zero, one, or more elements in the returned value.

    @chars = map(chr, @nums);

translates a list of numbers to the corresponding characters. And

    %hash = map { getkey($_) => $_ } @array;

is just a funny way to write

    %hash = ();
    foreach $_ (@array) {
        $hash{getkey($_)} = $_;
    }

Note that $_ is an alias to the list value, so it can be used to modify the elements of the LIST. While this is useful and supported, it can cause bizarre results if the elements of LIST are not variables. Using a regular foreach loop for this purpose would be clearer in most cases. See also grep for an array composed of those items of the original list for which the BLOCK or EXPR evaluates to true.

{ starts both hash references and blocks, so map { ... could be either the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look ahead for the closing } it has to take a guess at which its dealing with based what it finds just after the {. Usually it gets it right, but if it doesn't it won't realize something is wrong until it gets to the } and encounters the missing (or unexpected) comma. The syntax error will be reported close to the } but you'll need to change something near the { such as using a unary + to give perl some help:

    %hash = map {  "\L$_", 1  } @array  # perl guesses EXPR.  wrong
    %hash = map { +"\L$_", 1  } @array  # perl guesses BLOCK. right
    %hash = map { ("\L$_", 1) } @array  # this also works
    %hash = map {  lc($_), 1  } @array  # as does this.
    %hash = map +( lc($_), 1 ), @array  # this is EXPR and works!

    %hash = map  ( lc($_), 1 ), @array  # evaluates to (1, @array)

or to force an anon hash constructor use +{

   @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end

and you get list of anonymous hashes each with only 1 entry.

mkdir FILENAME,MASK
mkdir FILENAME

Creates the directory specified by FILENAME, with permissions specified by MASK (as modified by umask). If it succeeds it returns true, otherwise it returns false and sets $! (errno). If omitted, MASK defaults to 0777.

In general, it is better to create directories with permissive MASK, and let the user modify that with their umask, than it is to supply a restrictive MASK and give the user no way to be more permissive. The exceptions to this rule are when the file or directory should be kept private (mail files, for instance). The perlfunc(1) entry on umask discusses the choice of MASK in more detail.

Note that according to the POSIX 1003.1-1996 the FILENAME may have any number of trailing slashes. Some operating and filesystems do not get this right, so Perl automatically removes all trailing slashes to keep everyone happy.

msgctl ID,CMD,ARG

Calls the System V IPC function msgctl(2). You'll probably have to say

    use IPC::SysV;

first to get the correct constant definitions. If CMD is IPC_STAT, then ARG must be a variable that will hold the returned msqid_ds structure. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. See also SysV IPC in the perlipc manpage, IPC::SysV, and IPC::Semaphore documentation.

msgget KEY,FLAGS

Calls the System V IPC function msgget(2). Returns the message queue id, or the undefined value if there is an error. See also SysV IPC in the perlipc manpage and IPC::SysV and IPC::Msg documentation.

msgrcv ID,VAR,SIZE,TYPE,FLAGS

Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with unpack("l! a*"). Taints the variable. Returns true if successful, or false if there is an error. See also SysV IPC in the perlipc manpage, IPC::SysV, and IPC::SysV::Msg documentation.

msgsnd ID,MSG,FLAGS

Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the native long integer message type, and be followed by the length of the actual message, and finally the message itself. This kind of packing can be achieved with pack("l! a*", $type, $message). Returns true if successful, or false if there is an error. See also IPC::SysV and IPC::SysV::Msg documentation.

my EXPR
my TYPE EXPR
my EXPR : ATTRS
my TYPE EXPR : ATTRS

A my declares the listed variables to be local (lexically) to the enclosing block, file, or eval. If more than one value is listed, the list must be placed in parentheses.

The exact semantics and interface of TYPE and ATTRS are still evolving. TYPE is currently bound to the use of fields pragma, and attributes are handled using the attributes pragma, or starting from Perl 5.8.0 also via the Attribute::Handlers module. See Private Variables via my() in the perlsub manpage for details, and the fields manpage, the attributes manpage, and the Attribute::Handlers manpage.

next LABEL
next

The next command is like the continue statement in C; it starts the next iteration of the loop:

    LINE: while (<STDIN>) {
        next LINE if /^#/;      # discard comments
        #...
    }

Note that if there were a continue block on the above, it would get executed even on discarded lines. If the LABEL is omitted, the command refers to the innermost enclosing loop.

next cannot be used to exit a block which returns a value such as eval {}, sub {} or do {}, and should not be used to exit a grep() or map() operation.

Note that a block by itself is semantically identical to a loop that executes once. Thus next will exit such a block early.

See also continue for an illustration of how last, next, and redo work.

no Module VERSION LIST
no Module VERSION
no Module LIST
no Module

See the use function, which no is the opposite of.

oct EXPR
oct

Interprets EXPR as an octal string and returns the corresponding value. (If EXPR happens to start off with 0x, interprets it as a hex string. If EXPR starts off with 0b, it is interpreted as a binary string. Leading whitespace is ignored in all three cases.) The following will handle decimal, binary, octal, and hex in the standard Perl or C notation:

    $val = oct($val) if $val =~ /^0/;

If EXPR is omitted, uses $_. To go the other way (produce a number in octal), use sprintf() or printf():

    $perms = (stat("filename"))[2] & 07777;
    $oct_perms = sprintf "%lo", $perms;

The oct() function is commonly used when a string such as 644 needs to be converted into a file mode, for example. (Although perl will automatically convert strings into numbers as needed, this automatic conversion assumes base 10.)

open FILEHANDLE,EXPR
open FILEHANDLE,MODE,EXPR
open FILEHANDLE,MODE,EXPR,LIST
open FILEHANDLE,MODE,REFERENCE
open FILEHANDLE

Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE.

(The following is a comprehensive reference to open(): for a gentler introduction you may consider the perlopentut manpage.)

If FILEHANDLE is an undefined scalar variable (or array or hash element) the variable is assigned a reference to a new anonymous filehandle, otherwise if FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. (This is considered a symbolic reference, so use strict 'refs' should not be in effect.)

If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. (Note that lexical variables--those declared with my--will not work for this purpose; so if you're using my, specify EXPR in your call to open.)

If three or more arguments are specified then the mode of opening and the file name are separate. If MODE is '<' or nothing, the file is opened for input. If MODE is '>', the file is truncated and opened for output, being created if necessary. If MODE is '>>', the file is opened for appending, again being created if necessary.

You can put a '+' in front of the '>' or '<' to indicate that you want both read and write access to the file; thus '+<' is almost always preferred for read/write updates--the < '+' >> mode would clobber the file first. You can't usually use either read-write mode for updating textfiles, since they have variable length records. See the -i switch in the perlrun manpage for a better approach. The file is created with permissions of 0666 modified by the process' umask value.

These various prefixes correspond to the fopen(3) modes of 'r', 'r+', 'w', 'w+', 'a', and 'a+'.

In the 2-arguments (and 1-argument) form of the call the mode and filename should be concatenated (in this order), possibly separated by spaces. It is possible to omit the mode in these forms if the mode is '<'.

If the filename begins with '|', the filename is interpreted as a command to which output is to be piped, and if the filename ends with a '|', the filename is interpreted as a command which pipes output to us. See Using open() for IPC in the perlipc manpage for more examples of this. (You are not allowed to open to a command that pipes both in and out, but see the IPC::Open2 manpage, the IPC::Open3 manpage, and Bidirectional Communication with Another Process in the perlipc manpage for alternatives.)

For three or more arguments if MODE is '|-', the filename is interpreted as a command to which output is to be piped, and if MODE is '-|', the filename is interpreted as a command which pipes output to us. In the 2-arguments (and 1-argument) form one should replace dash ('-') with the command. See Using open() for IPC in the perlipc manpage for more examples of this. (You are not allowed to open to a command that pipes both in and out, but see the IPC::Open2 manpage, the IPC::Open3 manpage, and Bidirectional Communication in the perlipc manpage for alternatives.)

In the three-or-more argument form of pipe opens, if LIST is specified (extra arguments after the command name) then LIST becomes arguments to the command invoked if the platform supports it. The meaning of open with more than three arguments for non-pipe modes is not yet specified. Experimental "layers" may give extra LIST arguments meaning.

In the 2-arguments (and 1-argument) form opening '-' opens STDIN and opening '>-' opens STDOUT.

You may use the three-argument form of open to specify IO "layers" (sometimes also referred to as "disciplines") to be applied to the handle that affect how the input and output are processed (see the open manpage and the PerlIO manpage for more details). For example

  open(FH, "<:utf8", "file")

will open the UTF-8 encoded file containing Unicode characters, see the perluniintro manpage. Note that if layers are specified in the three-arg form then default layers stored in ${^OPEN} (see the perlvar manpage; usually set by the open pragma or the switch -CioD) are ignored.

Open returns nonzero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the pid of the subprocess.

If you're running Perl on a system that distinguishes between text files and binary files, then you should check out binmode for tips for dealing with this. The key distinction between systems that need binmode and those that don't is their text file formats. Systems like Unix, Mac OS, and Plan 9, which delimit lines with a single character, and which encode that character in C as "\n", do not need binmode. The rest need it.

When opening a file, it's usually a bad idea to continue normal execution if the request failed, so open is frequently used in connection with die. Even if die won't do what you want (say, in a CGI script, where you want to make a nicely formatted error message (but there are modules that can help with that problem)) you should always check the return value from opening a file. The infrequent exception is when working with an unopened filehandle is actually what you want to do.

As a special case the 3-arg form with a read/write mode and the third argument being undef:

    open(TMP, "+>", undef) or die ...

opens a filehandle to an anonymous temporary file. Also using "+<" works for symmetry, but you really should consider writing something to the temporary file first. You will need to seek() to do the reading.

Since v5.8.0, perl has built using PerlIO by default. Unless you've changed this (i.e. Configure -Uuseperlio), you can open file handles to "in memory" files held in Perl scalars via:

    open($fh, '>', \$variable) || ..

Though if you try to re-open STDOUT or STDERR as an "in memory" file, you have to close it first:

    close STDOUT;
    open STDOUT, '>', \$variable or die "Can't open STDOUT: $!";

Examples:

    $ARTICLE = 100;
    open ARTICLE or die "Can't find article $ARTICLE: $!\n";
    while (<ARTICLE>) {...

    open(LOG, '>>/usr/spool/news/twitlog');     # (log is reserved)
    # if the open fails, output is discarded

    open(DBASE, '+<', 'dbase.mine')             # open for update
        or die "Can't open 'dbase.mine' for update: $!";

    open(DBASE, '+<dbase.mine')                 # ditto
        or die "Can't open 'dbase.mine' for update: $!";

    open(ARTICLE, '-|', "caesar <$article")     # decrypt article
        or die "Can't start caesar: $!";

    open(ARTICLE, "caesar <$article |")         # ditto
        or die "Can't start caesar: $!";

    open(EXTRACT, "|sort >Tmp$$")               # $$ is our process id
        or die "Can't start sort: $!";

    # in memory files
    open(MEMORY,'>', \$var)
        or die "Can't open memory file: $!";
    print MEMORY "foo!\n";                      # output will end up in $var

    # process argument list of files along with any includes

    foreach $file (@ARGV) {
        process($file, 'fh00');
    }

    sub process {
        my($filename, $input) = @_;
        $input++;               # this is a string increment
        unless (open($input, $filename)) {
            print STDERR "Can't open $filename: $!\n";
            return;
        }

        local $_;
        while (<$input>) {              # note use of indirection
            if (/^#include "(.*)"/) {
                process($1, $input);
                next;
            }
            #...                # whatever
        }
            }

See the perliol manpage for detailed info on PerlIO.

You may also, in the Bourne shell tradition, specify an EXPR beginning with '>&', in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be duped (as dup(2)) and opened. You may use & after >, >>, <, +>, +>>, and +<. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents of IO buffers.) If you use the 3-arg form then you can pass either a number, the name of a filehandle or the normal "reference to a glob".

Here is a script that saves, redirects, and restores STDOUT and STDERR using various methods:

    #!/usr/bin/perl
    open my $oldout, ">&STDOUT"     or die "Can't dup STDOUT: $!";
    open OLDERR,     ">&", \*STDERR or die "Can't dup STDERR: $!";

    open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!";
    open STDERR, ">&STDOUT"     or die "Can't dup STDOUT: $!";

    select STDERR; $| = 1;      # make unbuffered
    select STDOUT; $| = 1;      # make unbuffered

    print STDOUT "stdout 1\n";  # this works for
    print STDERR "stderr 1\n";  # subprocesses too

    open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!";
    open STDERR, ">&OLDERR"    or die "Can't dup OLDERR: $!";

    print STDOUT "stdout 2\n";
    print STDERR "stderr 2\n";

If you specify '<&=X', where X is a file descriptor number or a filehandle, then Perl will do an equivalent of C's fdopen of that file descriptor (and not call dup(2)); this is more parsimonious of file descriptors. For example:

    # open for input, reusing the fileno of $fd
    open(FILEHANDLE, "<&=$fd")

or

    open(FILEHANDLE, "<&=", $fd)

or

    # open for append, using the fileno of OLDFH
    open(FH, ">>&=", OLDFH)

or

    open(FH, ">>&=OLDFH")

Being parsimonious on filehandles is also useful (besides being parsimonious) for example when something is dependent on file descriptors, like for example locking using flock(). If you do just open(A, '>>&B'), the filehandle A will not have the same file descriptor as B, and therefore flock(A) will not flock(B), and vice versa. But with open(A, '>>&=B') the filehandles will share the same file descriptor.

Note that if you are using Perls older than 5.8.0, Perl will be using the standard C libraries' fdopen() to implement the "=" functionality. On many UNIX systems fdopen() fails when file descriptors exceed a certain value, typically 255. For Perls 5.8.0 and later, PerlIO is most often the default.

You can see whether Perl has been compiled with PerlIO or not by running perl -V and looking for useperlio= line. If useperlio is define, you have PerlIO, otherwise you don't.

If you open a pipe on the command '-', i.e., either '|-' or '-|' with 2-arguments (or 1-argument) form of open(), then there is an implicit fork done, and the return value of open is the pid of the child within the parent process, and 0 within the child process. (Use defined($pid) to determine whether the open was successful.) The filehandle behaves normally for the parent, but i/o to that filehandle is piped from/to the STDOUT/STDIN of the child process. In the child process the filehandle isn't opened--i/o happens from/to the new STDOUT or STDIN. Typically this is used like the normal piped open when you want to exercise more control over just how the pipe command gets executed, such as when you are running setuid, and don't want to have to scan shell commands for metacharacters. The following triples are more or less equivalent:

    open(FOO, "|tr '[a-z]' '[A-Z]'");
    open(FOO, '|-', "tr '[a-z]' '[A-Z]'");
    open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]';
    open(FOO, '|-', "tr", '[a-z]', '[A-Z]');

    open(FOO, "cat -n '$file'|");
    open(FOO, '-|', "cat -n '$file'");
    open(FOO, '-|') || exec 'cat', '-n', $file;
    open(FOO, '-|', "cat", '-n', $file);

The last example in each block shows the pipe as "list form", which is not yet supported on all platforms. A good rule of thumb is that if your platform has true fork() (in other words, if your platform is UNIX) you can use the list form.

See Safe Pipe Opens in the perlipc manpage for more examples of this.

Beginning with v5.6.0, Perl will attempt to flush all files opened for output before any operation that may do a fork, but this may not be supported on some platforms (see the perlport manpage). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles.

On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptor as determined by the value of $^F. See $^F in the perlvar manpage.

Closing any piped filehandle causes the parent process to wait for the child to finish, and returns the status value in $?.

The filename passed to 2-argument (or 1-argument) form of open() will have leading and trailing whitespace deleted, and the normal redirection characters honored. This property, known as "magic open", can often be used to good effect. A user could specify a filename of "rsh cat file |", or you could change certain filenames as needed:

    $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
    open(FH, $filename) or die "Can't open $filename: $!";

Use 3-argument form to open a file with arbitrary weird characters in it,

    open(FOO, '<', $file);

otherwise it's necessary to protect any leading and trailing whitespace:

    $file =~ s#^(\s)#./$1#;
    open(FOO, "< $file\0");

(this may not work on some bizarre filesystems). One should conscientiously choose between the magic and 3-arguments form of open():

    open IN, $ARGV[0];

will allow the user to specify an argument of the form "rsh cat file |", but will not work on a filename which happens to have a trailing space, while

    open IN, '<', $ARGV[0];

will have exactly the opposite restrictions.

If you want a "real" C open (see open(2) on your system), then you should use the sysopen function, which involves no such magic (but may use subtly different filemodes than Perl open(), which is mapped to C fopen()). This is another way to protect your filenames from interpretation. For example:

    use IO::Handle;
    sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
        or die "sysopen $path: $!";
    $oldfh = select(HANDLE); $| = 1; select($oldfh);
    print HANDLE "stuff $$\n";
    seek(HANDLE, 0, 0);
    print "File contains: ", <HANDLE>;

Using the constructor from the IO::Handle package (or one of its subclasses, such as IO::File or IO::Socket), you can generate anonymous filehandles that have the scope of whatever variables hold references to them, and automatically close whenever and however you leave that scope:

    use IO::File;
    #...
    sub read_myfile_munged {
        my $ALL = shift;
        my $handle = new IO::File;
        open($handle, "myfile") or die "myfile: $!";
        $first = <$handle>
            or return ();     # Automatically closed here.
        mung $first or die "mung failed";       # Or here.
        return $first, <$handle> if $ALL;       # Or here.
        $first;                                 # Or here.
    }

See seek for some details about mixing reading and writing.

opendir DIRHANDLE,EXPR

Opens a directory named EXPR for processing by readdir, telldir, seekdir, rewinddir, and closedir. Returns true if successful. DIRHANDLE may be an expression whose value can be used as an indirect dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined scalar variable (or array or hash element), the variable is assigned a reference to a new anonymous dirhandle. DIRHANDLEs have their own namespace separate from FILEHANDLEs.

ord EXPR
ord

Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC, or Unicode) value of the first character of EXPR. If EXPR is omitted, uses $_.

For the reverse, see chr. See the perlunicode manpage and the encoding manpage for more about Unicode.

our EXPR
our EXPR TYPE
our EXPR : ATTRS
our TYPE EXPR : ATTRS

our associates a simple name with a package variable in the current package for use within the current scope. When use strict 'vars' is in effect, our lets you use declared global variables without qualifying them with package names, within the lexical scope of the our declaration. In this way our differs from use vars, which is package scoped.

Unlike my, which both allocates storage for a variable and associates a simple name with that storage for use within the current scope, our associates a simple name with a package variable in the current package, for use within the current scope. In other words, our has the same scoping rules as my, but does not necessarily create a variable.

If more than one value is listed, the list must be placed in parentheses.

    our $foo;
    our($bar, $baz);

An our declaration declares a global variable that will be visible across its entire lexical scope, even across package boundaries. The package in which the variable is entered is determined at the point of the declaration, not at the point of use. This means the following behavior holds:

    package Foo;
    our $bar;           # declares $Foo::bar for rest of lexical scope
    $bar = 20;

    package Bar;
    print $bar;         # prints 20, as it refers to $Foo::bar

Multiple our declarations with the same name in the same lexical scope are allowed if they are in different packages. If they happen to be in the same package, Perl will emit warnings if you have asked for them, just like multiple my declarations. Unlike a second my declaration, which will bind the name to a fresh variable, a second our declaration in the same package, in the same scope, is merely redundant.

    use warnings;
    package Foo;
    our $bar;           # declares $Foo::bar for rest of lexical scope
    $bar = 20;

    package Bar;
    our $bar = 30;      # declares $Bar::bar for rest of lexical scope
    print $bar;         # prints 30

    our $bar;           # emits warning but has no other effect
    print $bar;         # still prints 30

An our declaration may also have a list of attributes associated with it.

The exact semantics and interface of TYPE and ATTRS are still evolving. TYPE is currently bound to the use of fields pragma, and attributes are handled using the attributes pragma, or starting from Perl 5.8.0 also via the Attribute::Handlers module. See Private Variables via my() in the perlsub manpage for details, and the fields manpage, the attributes manpage, and the Attribute::Handlers manpage.

The only currently recognized our() attribute is unique which indicates that a single copy of the global is to be used by all interpreters should the program happen to be running in a multi-interpreter environment. (The default behaviour would be for each interpreter to have its own copy of the global.) Examples:

    our @EXPORT : unique = qw(foo);
    our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]);
    our $VERSION : unique = "1.00";

Note that this attribute also has the effect of making the global readonly when the first new interpreter is cloned (for example, when the first new thread is created).

Multi-interpreter environments can come to being either through the fork() emulation on Windows platforms, or by embedding perl in a multi-threaded application. The unique attribute does nothing in all other environments.

Warning: the current implementation of this attribute operates on the typeglob associated with the variable; this means that our $x : unique also has the effect of our @x : unique; our %x : unique. This may be subject to change.

pack TEMPLATE,LIST

Takes a LIST of values and converts it into a string using the rules given by the TEMPLATE. The resulting string is the concatenation of the converted values. Typically, each converted value looks like its machine-level representation. For example, on 32-bit machines a converted integer may be represented by a sequence of 4 bytes.

The TEMPLATE is a sequence of characters that give the order and type of values, as follows:

    a   A string with arbitrary binary data, will be null padded.
    A   A text (ASCII) string, will be space padded.
    Z   A null terminated (ASCIZ) string, will be null padded.
    b   A bit string (ascending bit order inside each byte, like vec()).
    B   A bit string (descending bit order inside each byte).
    h   A hex string (low nybble first).
    H   A hex string (high nybble first).
    c   A signed char value.
    C   An unsigned char value.  Only does bytes.  See U for Unicode.
    s   A signed short value.
    S   An unsigned short value.
          (This 'short' is _exactly_ 16 bits, which may differ from
           what a local C compiler calls 'short'.  If you want
           native-length shorts, use the '!' suffix.)
    i   A signed integer value.
    I   An unsigned integer value.
          (This 'integer' is _at_least_ 32 bits wide.  Its exact
           size depends on what a local C compiler calls 'int',
           and may even be larger than the 'long' described in
           the next item.)
    l   A signed long value.
    L   An unsigned long value.
          (This 'long' is _exactly_ 32 bits, which may differ from
           what a local C compiler calls 'long'.  If you want
           native-length longs, use the '!' suffix.)
    n   An unsigned short in "network" (big-endian) order.
    N   An unsigned long in "network" (big-endian) order.
    v   An unsigned short in "VAX" (little-endian) order.
    V   An unsigned long in "VAX" (little-endian) order.
          (These 'shorts' and 'longs' are _exactly_ 16 bits and
           _exactly_ 32 bits, respectively.)
    q   A signed quad (64-bit) value.
    Q   An unsigned quad value.
          (Quads are available only if your system supports 64-bit
           integer values _and_ if Perl has been compiled to support those.
           Causes a fatal error otherwise.)
    j   A signed integer value (a Perl internal integer, IV).
    J   An unsigned integer value (a Perl internal unsigned integer, UV).
    f   A single-precision float in the native format.
    d   A double-precision float in the native format.
    F   A floating point value in the native native format
           (a Perl internal floating point value, NV).
    D   A long double-precision float in the native format.
          (Long doubles are available only if your system supports long
           double values _and_ if Perl has been compiled to support those.
           Causes a fatal error otherwise.)
    p   A pointer to a null-terminated string.
    P   A pointer to a structure (fixed-length string).
    u   A uuencoded string.
    U   A Unicode character number.  Encodes to UTF-8 internally
        (or UTF-EBCDIC in EBCDIC platforms).
    w   A BER compressed integer (not an ASN.1 BER, see perlpacktut for
        details).  Its bytes represent an unsigned integer in base 128,
        most significant digit first, with as few digits as possible.  Bit
        eight (the high bit) is set on each byte except the last.
    x   A null byte.
    X   Back up a byte.
    @   Null fill to absolute position, counted from the start of
        the innermost ()-group.
    (   Start of a ()-group.

The following rules apply:

  • Each letter may optionally be followed by a number giving a repeat count. With all types except a, A, Z, b, B, h, H, @, x, X and P the pack function will gobble up that many values from the LIST. A * for the repeat count means to use however many items are left, except for @, x, X, where it is equivalent to 0, and u, where it is equivalent to 1 (or 45, what is the same). A numeric repeat count may optionally be enclosed in brackets, as in pack 'C[80]', @arr.

    One can replace the numeric repeat count by a template enclosed in brackets; then the packed length of this template in bytes is used as a count. For example, x[L] skips a long (it skips the number of bytes in a long); the template $t X[$t] $t unpack()s twice what $t unpacks. If the template in brackets contains alignment commands (such as x![d]), its packed length is calculated as if the start of the template has the maximal possible alignment.

    When used with Z, * results in the addition of a trailing null byte (so the packed result will be one longer than the byte length of the item).

    The repeat count for u is interpreted as the maximal number of bytes to encode per line of output, with 0 and 1 replaced by 45.

  • The a, A, and Z types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as necessary. When unpacking, A strips trailing spaces and nulls, Z strips everything after the first null, and a returns data verbatim. When packing, a, and Z are equivalent.

    If the value-to-pack is too long, it is truncated. If too long and an explicit count is provided, Z packs only $count-1 bytes, followed by a null byte. Thus Z always packs a trailing null byte under all circumstances.

  • Likewise, the b and B fields pack a string that many bits long. Each byte of the input field of pack() generates 1 bit of the result. Each result bit is based on the least-significant bit of the corresponding input byte, i.e., on ord($byte)%2. In particular, bytes "0" and "1" generate bits 0 and 1, as do bytes "\0" and "\1".

    Starting from the beginning of the input string of pack(), each 8-tuple of bytes is converted to 1 byte of output. With format b the first byte of the 8-tuple determines the least-significant bit of a byte, and with format B it determines the most-significant bit of a byte.

    If the length of the input string is not exactly divisible by 8, the remainder is packed as if the input string were padded by null bytes at the end. Similarly, during unpack()ing the "extra" bits are ignored.

    If the input string of pack() is longer than needed, extra bytes are ignored. A * for the repeat count of pack() means to use all the bytes of the input field. On unpack()ing the bits are converted to a string of "0"s and "1"s.

  • The h and H fields pack a string that many nybbles (4-bit groups, representable as hexadecimal digits, 0-9a-f) long.

    Each byte of the input field of pack() generates 4 bits of the result. For non-alphabetical bytes the result is based on the 4 least-significant bits of the input byte, i.e., on ord($byte)%16. In particular, bytes "0" and "1" generate nybbles 0 and 1, as do bytes "\0" and "\1". For bytes "a".."f" and "A".."F" the result is compatible with the usual hexadecimal digits, so that "a" and "A" both generate the nybble 0xa==10. The result for bytes "g".."z" and "G".."Z" is not well-defined.

    Starting from the beginning of the input string of pack(), each pair of bytes is converted to 1 byte of output. With format h the first byte of the pair determines the least-significant nybble of the output byte, and with format H it determines the most-significant nybble.

    If the length of the input string is not even, it behaves as if padded by a null byte at the end. Similarly, during unpack()ing the "extra" nybbles are ignored.

    If the input string of pack() is longer than needed, extra bytes are ignored. A * for the repeat count of pack() means to use all the bytes of the input field. On unpack()ing the bits are converted to a string of hexadecimal digits.

  • The p type packs a pointer to a null-terminated string. You are responsible for ensuring the string is not a temporary value (which can potentially get deallocated before you get around to using the packed result). The P type packs a pointer to a structure of the size indicated by the length. A NULL pointer is created if the corresponding value for p or P is undef, similarly for unpack().

  • The / template character allows packing and unpacking of strings where the packed structure contains a byte count followed by the string itself. You write length-item/string-item.

    The length-item can be any pack template letter, and describes how the length value is packed. The ones likely to be of most use are integer-packing ones like n (for Java strings), w (for ASN.1 or SNMP) and N (for Sun XDR).

    For pack, the string-item must, at present, be "A*", "a*" or "Z*". For unpack the length of the string is obtained from the length-item, but if you put in the '*' it will be ignored. For all other codes, unpack applies the length value to the next item, which must not have a repeat count.

        unpack 'C/a', "\04Gurusamy";        gives 'Guru'
    unpack 'a3/A* A*', '007 Bond  J ';  gives (' Bond','J')
    pack 'n/a* w/a*','hello,','world';  gives "\000\006hello,\005world"

    The length-item is not returned explicitly from unpack.

    Adding a count to the length-item letter is unlikely to do anything useful, unless that letter is A, a or Z. Packing with a length-item of a or Z may introduce "\000" characters, which Perl does not regard as legal in numeric strings.

  • The integer types s, S, l, and L may be immediately followed by a ! suffix to signify native shorts or longs--as you can see from above for example a bare l does mean exactly 32 bits, the native long (as seen by the local C compiler) may be larger. This is an issue mainly in 64-bit platforms. You can see whether using ! makes any difference by

            print length(pack("s")), " ", length(pack("s!")), "\n";
        print length(pack("l")), " ", length(pack("l!")), "\n";

    i! and I! also work but only because of completeness; they are identical to i and I.

    The actual sizes (in bytes) of native shorts, ints, longs, and long longs on the platform where Perl was built are also available via the Config manpage:

           use Config;
       print $Config{shortsize},    "\n";
       print $Config{intsize},      "\n";
       print $Config{longsize},     "\n";
       print $Config{longlongsize}, "\n";

    (The $Config{longlongsize} will be undefined if your system does not support long longs.)

  • The integer formats s, S, i, I, l, L, j, and J are inherently non-portable between processors and operating systems because they obey the native byteorder and endianness. For example a 4-byte integer 0x12345678 (305419896 decimal) would be ordered natively (arranged in and handled by the CPU registers) into bytes as

            0x12 0x34 0x56 0x78     # big-endian
        0x78 0x56 0x34 0x12     # little-endian

    Basically, the Intel and VAX CPUs are little-endian, while everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode.

    The names `big-endian' and `little-endian' are comic references to the classic "Gulliver's Travels" (via the paper "On Holy Wars and a Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and the egg-eating habits of the Lilliputians.

    Some systems may have even weirder byte orders such as

            0x56 0x78 0x12 0x34
        0x34 0x12 0x78 0x56

    You can see your system's preference with

            print join(" ", map { sprintf "%#02x", $_ }
                            unpack("C*",pack("L",0x12345678))), "\n";

    The byteorder on the platform where Perl was built is also available via the Config manpage:

            use Config;
        print $Config{byteorder}, "\n";

    Byteorders '1234' and '12345678' are little-endian, '4321' and '87654321' are big-endian.

    If you want portable packed integers use the formats n, N, v, and V, their byte endianness and size are known. See also the perlport manpage.

  • Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats around, and the lack of a standard "network" representation, no facility for interchange has been made. This means that packed floating point data written on one machine may not be readable on another - even if both use IEEE floating point arithmetic (as the endian-ness of the memory representation is not part of the IEEE spec). See also the perlport manpage.

    Note that Perl uses doubles internally for all numeric calculation, and converting from double into float and thence back to double again will lose precision (i.e., unpack("f", pack("f", $foo)) will not in general equal $foo).

  • If the pattern begins with a U, the resulting string will be treated as UTF-8-encoded Unicode. You can force UTF-8 encoding on in a string with an initial U0, and the bytes that follow will be interpreted as Unicode characters. If you don't want this to happen, you can begin your pattern with C0 (or anything else) to force Perl not to UTF-8 encode your string, and then follow this with a U* somewhere in your pattern.

  • You must yourself do any alignment or padding by inserting for example enough 'x'es while packing. There is no way to pack() and unpack() could know where the bytes are going to or coming from. Therefore pack (and unpack) handle their output and input as flat sequences of bytes.

  • A ()-group is a sub-TEMPLATE enclosed in parentheses. A group may take a repeat count, both as postfix, and for unpack() also via the / template character. Within each repetition of a group, positioning with @ starts again at 0. Therefore, the result of

        pack( '@1A((@2A)@3A)', 'a', 'b', 'c' )

    is the string "\0a\0\0bc".

  • x and X accept ! modifier. In this case they act as alignment commands: they jump forward/back to the closest position aligned at a multiple of count bytes. For example, to pack() or unpack() C's struct {char c; double d; char cc[2]} one may need to use the template C x![d] d C[2]; this assumes that doubles must be aligned on the double's size.

    For alignment commands count of 0 is equivalent to count of 1; both result in no-ops.

  • A comment in a TEMPLATE starts with # and goes to the end of line. White space may be used to separate pack codes from each other, but a ! modifier and a repeat count must follow immediately.

  • If TEMPLATE requires more arguments to pack() than actually given, pack() assumes additional "" arguments. If TEMPLATE requires fewer arguments to pack() than actually given, extra arguments are ignored.

Examples:

    $foo = pack("CCCC",65,66,67,68);
    # foo eq "ABCD"
    $foo = pack("C4",65,66,67,68);
    # same thing
    $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
    # same thing with Unicode circled letters

    $foo = pack("ccxxcc",65,66,67,68);
    # foo eq "AB\0\0CD"

    # note: the above examples featuring "C" and "c" are true
    # only on ASCII and ASCII-derived systems such as ISO Latin 1
    # and UTF-8.  In EBCDIC the first example would be
    # $foo = pack("CCCC",193,194,195,196);

    $foo = pack("s2",1,2);
    # "\1\0\2\0" on little-endian
    # "\0\1\0\2" on big-endian

    $foo = pack("a4","abcd","x","y","z");
    # "abcd"

    $foo = pack("aaaa","abcd","x","y","z");
    # "axyz"

    $foo = pack("a14","abcdefg");
    # "abcdefg\0\0\0\0\0\0\0"

    $foo = pack("i9pl", gmtime);
    # a real struct tm (on my system anyway)

    $utmp_template = "Z8 Z8 Z16 L";
    $utmp = pack($utmp_template, @utmp1);
    # a struct utmp (BSDish)

    @utmp2 = unpack($utmp_template, $utmp);
    # "@utmp1" eq "@utmp2"

    sub bintodec {
        unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
    }

    $foo = pack('sx2l', 12, 34);
    # short 12, two zero bytes padding, long 34
    $bar = pack('s@4l', 12, 34);
    # short 12, zero fill to position 4, long 34
    # $foo eq $bar

The same template may generally also be used in unpack().

package NAMESPACE
package

Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block, file, or eval (the same as the my operator). All further unqualified dynamic identifiers will be in this namespace. A package statement affects only dynamic variables--including those you've used local on--but not lexical variables, which are created with my. Typically it would be the first declaration in a file to be included by the require or use operator. You can switch into a package in more than one place; it merely influences which symbol table is used by the compiler for the rest of that block. You can refer to variables and filehandles in other packages by prefixing the identifier with the package name and a double colon: $Package::Variable. If the package name is null, the main package as assumed. That is, $::sail is equivalent to $main::sail (as well as to $main'sail, still seen in older code).

If NAMESPACE is omitted, then there is no current package, and all identifiers must be fully qualified or lexicals. However, you are strongly advised not to make use of this feature. Its use can cause unexpected behaviour, even crashing some versions of Perl. It is deprecated, and will be removed from a future release.

See Packages in the perlmod manpage for more information about packages, modules, and classes. See the perlsub manpage for other scoping issues.

pipe READHANDLE,WRITEHANDLE

Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur unless you are very careful. In addition, note that Perl's pipes use IO buffering, so you may need to set $| to flush your WRITEHANDLE after each command, depending on the application.

See the IPC::Open2 manpage, the IPC::Open3 manpage, and Bidirectional Communication in the perlipc manpage for examples of such things.

On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptors as determined by the value of $^F. See $^F in the perlvar manpage.

pop ARRAY
pop

Pops and returns the last value of the array, shortening the array by one element. Has an effect similar to

    $ARRAY[$#ARRAY--]

If there are no elements in the array, returns the undefined value (although this may happen at other times as well). If ARRAY is omitted, pops the @ARGV array in the main program, and the @_ array in subroutines, just like shift.

pos SCALAR
pos

Returns the offset of where the last m//g search left off for the variable in question ($_ is used when the variable is not specified). Note that 0 is a valid match offset. undef indicates that the search position is reset (usually due to match failure, but can also be because no match has yet been performed on the scalar). pos directly accesses the location used by the regexp engine to store the offset, so assigning to pos will change that offset, and so will also influence the \G zero-width assertion in regular expressions. Because a failed m//gc match doesn't reset the offset, the return from pos won't change either in this case. See the perlre manpage and the perlop manpage.

print FILEHANDLE LIST
print LIST
print

Prints a string or a list of strings. Returns true if successful. FILEHANDLE may be a scalar variable name, in which case the variable contains the name of or a reference to the filehandle, thus introducing one level of indirection. (NOTE: If FILEHANDLE is a variable and the next token is a term, it may be misinterpreted as an operator unless you interpose a + or put parentheses around the arguments.) If FILEHANDLE is omitted, prints by default to standard output (or to the last selected output channel--see select). If LIST is also omitted, prints $_ to the currently selected output channel. To set the default output channel to something other than STDOUT use the select operation. The current value of $, (if any) is printed between each LIST item. The current value of $\ (if any) is printed after the entire LIST has been printed. Because print takes a LIST, anything in the LIST is evaluated in list context, and any subroutine that you call will have one or more of its expressions evaluated in list context. Also be careful not to follow the print keyword with a left parenthesis unless you want the corresponding right parenthesis to terminate the arguments to the print--interpose a + or put parentheses around all the arguments.

Note that if you're storing FILEHANDLEs in an array, or if you're using any other expression more complex than a scalar variable to retrieve it, you will have to use a block returning the filehandle value instead:

    print { $files[$i] } "stuff\n";
    print { $OK ? STDOUT : STDERR } "stuff\n";
printf FILEHANDLE FORMAT, LIST
printf FORMAT, LIST

Equivalent to print FILEHANDLE sprintf(FORMAT, LIST), except that $\ (the output record separator) is not appended. The first argument of the list will be interpreted as the printf format. See sprintf for an explanation of the format argument. If use locale is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See the perllocale manpage.

Don't fall into the trap of using a printf when a simple print would do. The print is more efficient and less error prone.

prototype FUNCTION

Returns the prototype of a function as a string (or undef if the function has no prototype). FUNCTION is a reference to, or the name of, the function whose prototype you want to retrieve.

If FUNCTION is a string starting with CORE::, the rest is taken as a name for Perl builtin. If the builtin is not overridable (such as qw//) or its arguments cannot be expressed by a prototype (such as system) returns undef because the builtin does not really behave like a Perl function. Otherwise, the string describing the equivalent prototype is returned.

push ARRAY,LIST

Treats ARRAY as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of LIST. Has the same effect as

    for $value (LIST) {
        $ARRAY[++$#ARRAY] = $value;
    }

but is more efficient. Returns the number of elements in the array following the completed push.

q/STRING/
qq/STRING/
qr/STRING/
qx/STRING/
qw/STRING/

Generalized quotes. See Regexp Quote-Like Operators in the perlop manpage.

quotemeta EXPR
quotemeta

Returns the value of EXPR with all non-"word" characters backslashed. (That is, all characters not matching /[A-Za-z_0-9]/ will be preceded by a backslash in the returned string, regardless of any locale settings.) This is the internal function implementing the \Q escape in double-quoted strings.

If EXPR is omitted, uses $_.

rand EXPR
rand

Returns a random fractional number greater than or equal to 0 and less than the value of EXPR. (EXPR should be positive.) If EXPR is omitted, the value 1 is used. Currently EXPR with the value 0 is also special-cased as 1 - this has not been documented before perl 5.8.0 and is subject to change in future versions of perl. Automatically calls srand unless srand has already been called. See also srand.

Apply int() to the value returned by rand() if you want random integers instead of random fractional numbers. For example,

    int(rand(10))

returns a random integer between 0 and 9, inclusive.

(Note: If your rand function consistently returns numbers that are too large or too small, then your version of Perl was probably compiled with the wrong number of RANDBITS.)

read FILEHANDLE,SCALAR,LENGTH,OFFSET
read FILEHANDLE,SCALAR,LENGTH

Attempts to read LENGTH characters of data into variable SCALAR from the specified FILEHANDLE. Returns the number of characters actually read, 0 at end of file, or undef if there was an error (in the latter case $! is also set). SCALAR will be grown or shrunk so that the last character actually read is the last character of the scalar after the read.

An OFFSET may be specified to place the read data at some place in the string other than the beginning. A negative OFFSET specifies placement at that many characters counting backwards from the end of the string. A positive OFFSET greater than the length of SCALAR results in the string being padded to the required size with "\0" bytes before the result of the read is appended.

The call is actually implemented in terms of either Perl's or system's fread() call. To get a true read(2) system call, see sysread.

Note the characters: depending on the status of the filehandle, either (8-bit) bytes or characters are read. By default all filehandles operate on bytes, but for example if the filehandle has been opened with the :utf8 I/O layer (see open, and the open pragma, the open manpage), the I/O will operate on UTF-8 encoded Unicode characters, not bytes. Similarly for the :encoding pragma: in that case pretty much any characters can be read.

readdir DIRHANDLE

Returns the next directory entry for a directory opened by opendir. If used in list context, returns all the rest of the entries in the directory. If there are no more entries, returns an undefined value in scalar context or a null list in list context.

If you're planning to filetest the return values out of a readdir, you'd better prepend the directory in question. Otherwise, because we didn't chdir there, it would have been testing the wrong file.

    opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
    @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
    closedir DIR;
readline EXPR

Reads from the filehandle whose typeglob is contained in EXPR. In scalar context, each call reads and returns the next line, until end-of-file is reached, whereupon the subsequent call returns undef. In list context, reads until end-of-file is reached and returns a list of lines. Note that the notion of "line" used here is however you may have defined it with $/ or $INPUT_RECORD_SEPARATOR). See $/ in the perlvar manpage.

When $/ is set to undef, when readline() is in scalar context (i.e. file slurp mode), and when an empty file is read, it returns '' the first time, followed by undef subsequently.

This is the internal function implementing the <EXPR> operator, but you can use it directly. The <EXPR> operator is discussed in more detail in I/O Operators in the perlop manpage.

    $line = <STDIN>;
    $line = readline(*STDIN);           # same thing

If readline encounters an operating system error, $! will be set with the corresponding error message. It can be helpful to check $! when you are reading from filehandles you don't trust, such as a tty or a socket. The following example uses the operator form of readline, and takes the necessary steps to ensure that readline was successful.

    for (;;) {
        undef $!;
        unless (defined( $line = <> )) {
            die $! if $!;
            last; # reached EOF
        }
        # ...
    }
readlink EXPR
readlink

Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets $! (errno). If EXPR is omitted, uses $_.

readpipe EXPR

EXPR is executed as a system command. The collected standard output of the command is returned. In scalar context, it comes back as a single (potentially multi-line) string. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). This is the internal function implementing the qx/EXPR/ operator, but you can use it directly. The qx/EXPR/ operator is discussed in more detail in I/O Operators in the perlop manpage.

recv SOCKET,SCALAR,LENGTH,FLAGS

Receives a message on a socket. Attempts to receive LENGTH characters of data into variable SCALAR from the specified SOCKET filehandle. SCALAR will be grown or shrunk to the length actually read. Takes the same flags as the system call of the same name. Returns the address of the sender if SOCKET's protocol supports this; returns an empty string otherwise. If there's an error, returns the undefined value. This call is actually implemented in terms of recvfrom(2) system call. See UDP: Message Passing in the perlipc manpage for examples.

Note the characters: depending on the status of the socket, either (8-bit) bytes or characters are received. By default all sockets operate on bytes, but for example if the socket has been changed using binmode() to operate with the :utf8 I/O layer (see the open pragma, the open manpage), the I/O will operate on UTF-8 encoded Unicode characters, not bytes. Similarly for the :encoding pragma: in that case pretty much any characters can be read.

redo LABEL
redo

The redo command restarts the loop block without evaluating the conditional again. The continue block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing loop. Programs that want to lie to themselves about what was just input normally use this command:

    # a simpleminded Pascal comment stripper
    # (warning: assumes no { or } in strings)
    LINE: while (<STDIN>) {
        while (s|({.*}.*){.*}|$1 |) {}
        s|{.*}| |;
        if (s|{.*| |) {
            $front = $_;
            while (<STDIN>) {
                if (/}/) {      # end of comment?
                    s|^|$front\{|;
                    redo LINE;
                }
            }
        }
        print;
    }

redo cannot be used to retry a block which returns a value such as eval {}, sub {} or do {}, and should not be used to exit a grep() or map() operation.

Note that a block by itself is semantically identical to a loop that executes once. Thus redo inside such a block will effectively turn it into a looping construct.

See also continue for an illustration of how last, next, and redo work.

ref EXPR
ref

Returns a non-empty string if EXPR is a reference, the empty string otherwise. If EXPR is not specified, $_ will be used. The value returned depends on the type of thing the reference is a reference to. Builtin types include:

    SCALAR
    ARRAY
    HASH
    CODE
    REF
    GLOB
    LVALUE

If the referenced object has been blessed into a package, then that package name is returned instead. You can think of ref as a typeof operator.

    if (ref($r) eq "HASH") {
        print "r is a reference to a hash.\n";
    }
    unless (ref($r)) {
        print "r is not a reference at all.\n";
    }

See also the perlref manpage.

rename OLDNAME,NEWNAME

Changes the name of a file; an existing file NEWNAME will be clobbered. Returns true for success, false otherwise.

Behavior of this function varies wildly depending on your system implementation. For example, it will usually not work across file system boundaries, even though the system mv command sometimes compensates for this. Other restrictions include whether it works on directories, open files, or pre-existing files. Check the perlport manpage and either the rename(2) manpage or equivalent system documentation for details.

require VERSION
require EXPR
require

Demands a version of Perl specified by VERSION, or demands some semantics specified by EXPR or by $_ if EXPR is not supplied.

VERSION may be either a numeric argument such as 5.006, which will be compared to $], or a literal of the form v5.6.1, which will be compared to $^V (aka $PERL_VERSION). A fatal error is produced at run time if VERSION is greater than the version of the current Perl interpreter. Compare with use, which can do a similar check at compile time.

Specifying VERSION as a literal of the form v5.6.1 should generally be avoided, because it leads to misleading error messages under earlier versions of Perl that do not support this syntax. The equivalent numeric version should be used instead.

    require v5.6.1;     # run time version check
    require 5.6.1;      # ditto
    require 5.006_001;  # ditto; preferred for backwards compatibility

Otherwise, require demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is essentially just a variety of eval. Has semantics similar to the following subroutine:

    sub require {
       my ($filename) = @_;
       if (exists $INC{$filename}) {
           return 1 if $INC{$filename};
           die "Compilation failed in require";
       }
       my ($realfilename,$result);
       ITER: {
           foreach $prefix (@INC) {
               $realfilename = "$prefix/$filename";
               if (-f $realfilename) {
                   $INC{$filename} = $realfilename;
                   $result = do $realfilename;
                   last ITER;
               }
           }
           die "Can't find $filename in \@INC";
       }
       if ($@) {
           $INC{$filename} = undef;
           die $@;
       } elsif (!$result) {
           delete $INC{$filename};
           die "$filename did not return true value";
       } else {
           return $result;
       }
    }

Note that the file will not be included twice under the same specified name.

The file must return true as the last statement to indicate successful execution of any initialization code, so it's customary to end such a file with 1; unless you're sure it'll return true otherwise. But it's better just to put the 1;, in case you add more statements.

If EXPR is a bareword, the require assumes a ".pm" extension and replaces "::" with "/" in the filename for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace.

In other words, if you try this:

        require Foo::Bar;    # a splendid bareword

The require function will actually look for the "Foo/Bar.pm" file in the directories specified in the @INC array.

But if you try this:

        $class = 'Foo::Bar';
        require $class;      # $class is not a bareword
            #or
        require "Foo::Bar";  # not a bareword because of the ""

The require function will look for the "Foo::Bar" file in the @INC array and will complain about not finding "Foo::Bar" there. In this case you can do:

        eval "require $class";

Now that you understand how require looks for files in the case of a bareword argument, there is a little extra functionality going on behind the scenes. Before require looks for a ".pm" extension, it will first look for a filename with a ".pmc" extension. A file with this extension is assumed to be Perl bytecode generated by B::Bytecode. If this file is found, and its modification time is newer than a coinciding ".pm" non-compiled file, it will be loaded in place of that non-compiled file ending in a ".pm" extension.

You can also insert hooks into the import facility, by putting directly Perl code into the @INC array. There are three forms of hooks: subroutine references, array references and blessed objects.

Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets called with two parameters, the first being a reference to itself, and the second the name of the file to be included (e.g. "Foo/Bar.pm"). The subroutine should return undef or a filehandle, from which the file to include will be read. If undef is returned, require will look at the remaining elements of @INC.

If the hook is an array reference, its first element must be a subroutine reference. This subroutine is called as above, but the first parameter is the array reference. This enables to pass indirectly some arguments to the subroutine.

In other words, you can write:

    push @INC, \&my_sub;
    sub my_sub {
        my ($coderef, $filename) = @_;  # $coderef is \&my_sub
        ...
    }

or:

    push @INC, [ \&my_sub, $x, $y, ... ];
    sub my_sub {
        my ($arrayref, $filename) = @_;
        # Retrieve $x, $y, ...
        my @parameters = @$arrayref[1..$#$arrayref];
        ...
    }

If the hook is an object, it must provide an INC method that will be called as above, the first parameter being the object itself. (Note that you must fully qualify the sub's name, as it is always forced into package main.) Here is a typical code layout:

    # In Foo.pm
    package Foo;
    sub new { ... }
    sub Foo::INC {
        my ($self, $filename) = @_;
        ...
    }

    # In the main program
    push @INC, new Foo(...);

Note that these hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See %INC in the perlvar manpage.

For a yet-more-powerful import facility, see use and the perlmod manpage.

reset EXPR
reset

Generally used in a continue block at the end of a loop to clear variables and reset ?? searches so that they work again. The expression is interpreted as a list of single characters (hyphens allowed for ranges). All variables and arrays beginning with one of those letters are reset to their pristine state. If the expression is omitted, one-match searches (?pattern?) are reset to match again. Resets only variables or searches in the current package. Always returns 1. Examples:

    reset 'X';          # reset all X variables
    reset 'a-z';        # reset lower case variables
    reset;              # just reset ?one-time? searches

Resetting "A-Z" is not recommended because you'll wipe out your @ARGV and @INC arrays and your %ENV hash. Resets only package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, so you'll probably want to use them instead. See my.

return EXPR
return

Returns from a subroutine, eval, or do FILE with the value given in EXPR. Evaluation of EXPR may be in list, scalar, or void context, depending on how the return value will be used, and the context may vary from one execution to the next (see wantarray). If no EXPR is given, returns an empty list in list context, the undefined value in scalar context, and (of course) nothing at all in a void context.

(Note that in the absence of an explicit return, a subroutine, eval, or do FILE will automatically return the value of the last expression evaluated.)

reverse LIST

In list context, returns a list value consisting of the elements of LIST in the opposite order. In scalar context, concatenates the elements of LIST and returns a string value with all characters in the opposite order.

    print reverse <>;           # line tac, last line first

    undef $/;                   # for efficiency of <>
    print scalar reverse <>;    # character tac, last line tsrif

Used without arguments in scalar context, reverse() reverses $_.

This operator is also handy for inverting a hash, although there are some caveats. If a value is duplicated in the original hash, only one of those can be represented as a key in the inverted hash. Also, this has to unwind one hash and build a whole new one, which may take some time on a large hash, such as from a DBM file.

    %by_name = reverse %by_address;     # Invert the hash
rewinddir DIRHANDLE

Sets the current position to the beginning of the directory for the readdir routine on DIRHANDLE.

rindex STR,SUBSTR,POSITION
rindex STR,SUBSTR

Works just like index() except that it returns the position of the last occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence beginning at or before that position.

rmdir FILENAME
rmdir

Deletes the directory specified by FILENAME if that directory is empty. If it succeeds it returns true, otherwise it returns false and sets $! (errno). If FILENAME is omitted, uses $_.

s///

The substitution operator. See the perlop manpage.

scalar EXPR

Forces EXPR to be interpreted in scalar context and returns the value of EXPR.

    @counts = ( scalar @a, scalar @b, scalar @c );

There is no equivalent operator to force an expression to be interpolated in list context because in practice, this is never needed. If you really wanted to do so, however, you could use the construction @{[ (some expression) ]}, but usually a simple (some expression) suffices.

Because scalar is unary operator, if you accidentally use for EXPR a parenthesized list, this behaves as a scalar comma expression, evaluating all but the last element in void context and returning the final element evaluated in scalar context. This is seldom what you want.

The following single statement:

        print uc(scalar(&foo,$bar)),$baz;

is the moral equivalent of these two:

        &foo;
        print(uc($bar),$baz);

See the perlop manpage for more details on unary operators and the comma operator.

seek FILEHANDLE,POSITION,WHENCE

Sets FILEHANDLE's position, just like the fseek call of stdio. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are 0 to set the new position in bytes to POSITION, 1 to set it to the current position plus POSITION, and 2 to set it to EOF plus POSITION (typically negative). For WHENCE you may use the constants SEEK_SET, SEEK_CUR, and SEEK_END (start of the file, current position, end of the file) from the Fcntl module. Returns 1 upon success, 0 otherwise.

Note the in bytes: even if the filehandle has been set to operate on characters (for example by using the :utf8 open layer), tell() will return byte offsets, not character offsets (because implementing that would render seek() and tell() rather slow).

If you want to position file for sysread or syswrite, don't use seek--buffering makes its effect on the file's system position unpredictable and non-portable. Use sysseek instead.

Due to the rules and rigors of ANSI C, on some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling stdio's clearerr(3). A WHENCE of 1 (SEEK_CUR) is useful for not moving the file position:

    seek(TEST,0,1);

This is also useful for applications emulating tail -f. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a seek() to reset things. The seek doesn't change the current position, but it does clear the end-of-file condition on the handle, so that the next <FILE> makes Perl try again to read something. We hope.

If that doesn't work (some IO implementations are particularly cantankerous), then you may need something more like this:

    for (;;) {
        for ($curpos = tell(FILE); $_ = <FILE>;
             $curpos = tell(FILE)) {
            # search for some stuff and put it into files
        }
        sleep($for_a_while);
        seek(FILE, $curpos, 0);
    }
seekdir DIRHANDLE,POS

Sets the current position for the readdir routine on DIRHANDLE. POS must be a value returned by telldir. seekdir also has the same caveats about possible directory compaction as the corresponding system library routine.

select FILEHANDLE
select

Returns the currently selected filehandle. Sets the current default filehandle for output, if FILEHANDLE is supplied. This has two effects: first, a write or a print without a filehandle will default to this FILEHANDLE. Second, references to variables related to output will refer to this output channel. For example, if you have to set the top of form format for more than one output channel, you might do the following:

    select(REPORT1);
    $^ = 'report1_top';
    select(REPORT2);
    $^ = 'report2_top';

FILEHANDLE may be an expression whose value gives the name of the actual filehandle. Thus:

    $oldfh = select(STDERR); $| = 1; select($oldfh);

Some programmers may prefer to think of filehandles as objects with methods, preferring to write the last example as:

    use IO::Handle;
    STDERR->autoflush(1);
select RBITS,WBITS,EBITS,TIMEOUT

This calls the select(2) system call with the bit masks specified, which can be constructed using fileno and vec, along these lines:

    $rin = $win = $ein = '';
    vec($rin,fileno(STDIN),1) = 1;
    vec($win,fileno(STDOUT),1) = 1;
    $ein = $rin | $win;

If you want to select on many filehandles you might wish to write a subroutine:

    sub fhbits {
        my(@fhlist) = split(' ',$_[0]);
        my($bits);
        for (@fhlist) {
            vec($bits,fileno($_),1) = 1;
        }
        $bits;
    }
    $rin = fhbits('STDIN TTY SOCK');

The usual idiom is:

    ($nfound,$timeleft) =
      select($rout=$rin, $wout=$win, $eout=$ein, $timeout);

or to block until something becomes ready just do this

    $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef);

Most systems do not bother to return anything useful in $timeleft, so calling select() in scalar context just returns $nfound.

Any of the bit masks can also be undef. The timeout, if specified, is in seconds, which may be fractional. Note: not all implementations are capable of returning the $timeleft. If not, they always return $timeleft equal to the supplied $timeout.

You can effect a sleep of 250 milliseconds this way:

    select(undef, undef, undef, 0.25);

Note that whether select gets restarted after signals (say, SIGALRM) is implementation-dependent. See also the perlport manpage for notes on the portability of select.

On error, select behaves like the select(2) system call : it returns -1 and sets $!.

Note: on some Unixes, the select(2) system call may report a socket file descriptor as "ready for reading", when actually no data is available, thus a subsequent read blocks. It can be avoided using always the O_NONBLOCK flag on the socket. See select(2) and fcntl(2) for further details.

WARNING: One should not attempt to mix buffered I/O (like read or <FH>) with select, except as permitted by POSIX, and even then only on POSIX systems. You have to use sysread instead.

semctl ID,SEMNUM,CMD,ARG

Calls the System V IPC function semctl. You'll probably have to say

    use IPC::SysV;

first to get the correct constant definitions. If CMD is IPC_STAT or GETALL, then ARG must be a variable that will hold the returned semid_ds structure or semaphore value array. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. The ARG must consist of a vector of native short integers, which may be created with pack("s!",(0)x$nsem). See also SysV IPC in the perlipc manpage, IPC::SysV, IPC::Semaphore documentation.

semget KEY,NSEMS,FLAGS

Calls the System V IPC function semget. Returns the semaphore id, or the undefined value if there is an error. See also SysV IPC in the perlipc manpage, IPC::SysV, IPC::SysV::Semaphore documentation.

semop KEY,OPSTRING

Calls the System V IPC function semop to perform semaphore operations such as signalling and waiting. OPSTRING must be a packed array of semop structures. Each semop structure can be generated with pack("s!3", $semnum, $semop, $semflag). The length of OPSTRING implies the number of semaphore operations. Returns true if successful, or false if there is an error. As an example, the following code waits on semaphore $semnum of semaphore id $semid:

    $semop = pack("s!3", $semnum, -1, 0);
    die "Semaphore trouble: $!\n" unless semop($semid, $semop);

To signal the semaphore, replace -1 with 1. See also SysV IPC in the perlipc manpage, IPC::SysV, and IPC::SysV::Semaphore documentation.

send SOCKET,MSG,FLAGS,TO
send SOCKET,MSG,FLAGS

Sends a message on a socket. Attempts to send the scalar MSG to the SOCKET filehandle. Takes the same flags as the system call of the same name. On unconnected sockets you must specify a destination to send TO, in which case it does a C sendto. Returns the number of characters sent, or the undefined value if there is an error. The C system call sendmsg(2) is currently unimplemented. See UDP: Message Passing in the perlipc manpage for examples.

Note the characters: depending on the status of the socket, either (8-bit) bytes or characters are sent. By default all sockets operate on bytes, but for example if the socket has been changed using binmode() to operate with the :utf8 I/O layer (see open, or the open pragma, the open manpage), the I/O will operate on UTF-8 encoded Unicode characters, not bytes. Similarly for the :encoding pragma: in that case pretty much any characters can be sent.

setpgrp PID,PGRP

Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted, it defaults to 0,0. Note that the BSD 4.2 version of setpgrp does not accept any arguments, so only setpgrp(0,0) is portable. See also POSIX::setsid().

setpriority WHICH,WHO,PRIORITY

Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2).

setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL

Sets the socket option requested. Returns undefined if there is an error. Use integer constants provided by the Socket module for LEVEL and OPNAME. Values for LEVEL can also be obtained from getprotobyname. OPTVAL might either be a packed string or an integer. An integer OPTVAL is shorthand for pack("i", OPTVAL).

An example disabling the Nagle's algorithm for a socket:

    use Socket qw(IPPROTO_TCP TCP_NODELAY);
    setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
shift ARRAY
shift

Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the @_ array within the lexical scope of subroutines and formats, and the @ARGV array at file scopes or within the lexical scopes established by the eval '', BEGIN {}, INIT {}, CHECK {}, and END {} constructs.

See also unshift, push, and pop. shift and unshift do the same thing to the left end of an array that pop and push do to the right end.

shmctl ID,CMD,ARG

Calls the System V IPC function shmctl. You'll probably have to say

    use IPC::SysV;

first to get the correct constant definitions. If CMD is IPC_STAT, then ARG must be a variable that will hold the returned shmid_ds structure. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. See also SysV IPC in the perlipc manpage and IPC::SysV documentation.

shmget KEY,SIZE,FLAGS

Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. See also SysV IPC in the perlipc manpage and IPC::SysV documentation.

shmread ID,VAR,POS,SIZE
shmwrite ID,STRING,POS,SIZE

Reads or writes the System V shared memory segment ID starting at position POS for size SIZE by attaching to it, copying in/out, and detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, or false if there is an error. shmread() taints the variable. See also SysV IPC in the perlipc manpage, IPC::SysV documentation, and the IPC::Shareable module from CPAN.

shutdown SOCKET,HOW

Shuts down a socket connection in the manner indicated by HOW, which has the same interpretation as in the system call of the same name.

    shutdown(SOCKET, 0);    # I/we have stopped reading data
    shutdown(SOCKET, 1);    # I/we have stopped writing data
    shutdown(SOCKET, 2);    # I/we have stopped using this socket

This is useful with sockets when you want to tell the other side you're done writing but not done reading, or vice versa. It's also a more insistent form of close because it also disables the file descriptor in any forked copies in other processes.

sin EXPR
sin

Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of $_.

For the inverse sine operation, you may use the Math::Trig::asin function, or use this relation:

    sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
sleep EXPR
sleep

Causes the script to sleep for EXPR seconds, or forever if no EXPR. May be interrupted if the process receives a signal such as SIGALRM. Returns the number of seconds actually slept. You probably cannot mix alarm and sleep calls, because sleep is often implemented using alarm.

On some older systems, it may sleep up to a full second less than what you requested, depending on how it counts seconds. Most modern systems always sleep the full amount. They may appear to sleep longer than that, however, because your process might not be scheduled right away in a busy multitasking system.

For delays of finer granularity than one second, you may use Perl's syscall interface to access setitimer(2) if your system supports it, or else see select above. The Time::HiRes module (from CPAN, and starting from Perl 5.8 part of the standard distribution) may also help.

See also the POSIX module's pause function.

socket SOCKET,DOMAIN,TYPE,PROTOCOL

Opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. You should use Socket first to get the proper definitions imported. See the examples in Sockets: Client/Server Communication in the perlipc manpage.

On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptor, as determined by the value of $^F. See $^F in the perlvar manpage.

socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL

Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal error. Returns true if successful.

On systems that support a close-on-exec flag on files, the flag will be set for the newly opened file descriptors, as determined by the value of $^F. See $^F in the perlvar manpage.

Some systems defined pipe in terms of socketpair, in which a call to pipe(Rdr, Wtr) is essentially:

    use Socket;
    socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
    shutdown(Rdr, 1);        # no more writing for reader
    shutdown(Wtr, 0);        # no more reading for writer

See the perlipc manpage for an example of socketpair use. Perl 5.8 and later will emulate socketpair using IP sockets to localhost if your system implements sockets but not socketpair.

sort SUBNAME LIST
sort BLOCK LIST
sort LIST

In list context, this sorts the LIST and returns the sorted list value. In scalar context, the behaviour of sort() is undefined.

If SUBNAME or BLOCK is omitted, sorts in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the list are to be ordered. (The < <= >> and cmp operators are extremely useful in such routines.) SUBNAME may be a scalar variable name (unsubscripted), in which case the value provides the name of (or a reference to) the actual subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine.

If the subroutine's prototype is ($$), the elements to be compared are passed by reference in @_, as for a normal subroutine. This is slower than unprototyped subroutines, where the elements to be compared are passed into the subroutine as the package global variables $a and $b (see example below). Note that in the latter case, it is usually counter-productive to declare $a and $b as lexicals.

In either case, the subroutine may not be recursive. The values to be compared are always passed by reference and should not be modified.

You also cannot exit out of the sort block or subroutine using any of the loop control operators described in the perlsyn manpage or with goto.

When use locale is in effect, sort LIST sorts LIST according to the current collation locale. See the perllocale manpage.

sort() returns aliases into the original list, much as a for loop's index variable aliases the list elements. That is, modifying an element of a list returned by sort() (for example, in a foreach, map or grep) actually modifies the element in the original list. This is usually something to be avoided when writing clear code.

Perl 5.6 and earlier used a quicksort algorithm to implement sort. That algorithm was not stable, and could go quadratic. (A stable sort preserves the input order of elements that compare equal. Although quicksort's run time is O(NlogN) when averaged over all arrays of length N, the time can be O(N**2), quadratic behavior, for some inputs.) In 5.7, the quicksort implementation was replaced with a stable mergesort algorithm whose worst-case behavior is O(NlogN). But benchmarks indicated that for some inputs, on some platforms, the original quicksort was faster. 5.8 has a sort pragma for limited control of the sort. Its rather blunt control of the underlying algorithm may not persist into future Perls, but the ability to characterize the input or output in implementation independent ways quite probably will. See the sort manpage.

Examples:

    # sort lexically
    @articles = sort @files;

    # same thing, but with explicit sort routine
    @articles = sort {$a cmp $b} @files;

    # now case-insensitively
    @articles = sort {uc($a) cmp uc($b)} @files;

    # same thing in reversed order
    @articles = sort {$b cmp $a} @files;

    # sort numerically ascending
    @articles = sort {$a <=> $b} @files;

    # sort numerically descending
    @articles = sort {$b <=> $a} @files;

    # this sorts the %age hash by value instead of key
    # using an in-line function
    @eldest = sort { $age{$b} <=> $age{$a} } keys %age;

    # sort using explicit subroutine name
    sub byage {
        $age{$a} <=> $age{$b};  # presuming numeric
    }
    @sortedclass = sort byage @class;

    sub backwards { $b cmp $a }
    @harry  = qw(dog cat x Cain Abel);
    @george = qw(gone chased yz Punished Axed);
    print sort @harry;
            # prints AbelCaincatdogx
    print sort backwards @harry;
            # prints xdogcatCainAbel
    print sort @george, 'to', @harry;
            # prints AbelAxedCainPunishedcatchaseddoggonetoxyz

    # inefficiently sort by descending numeric compare using
    # the first integer after the first = sign, or the
    # whole record case-insensitively otherwise

    @new = sort {
        ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
                            ||
                    uc($a)  cmp  uc($b)
    } @old;

    # same thing, but much more efficiently;
    # we'll build auxiliary indices instead
    # for speed
    @nums = @caps = ();
    for (@old) {
        push @nums, /=(\d+)/;
        push @caps, uc($_);
    }

    @new = @old[ sort {
                        $nums[$b] <=> $nums[$a]
                                 ||
                        $caps[$a] cmp $caps[$b]
                       } 0..$#old
               ];

    # same thing, but without any temps
    @new = map { $_->[0] }
           sort { $b->[1] <=> $a->[1]
                           ||
                  $a->[2] cmp $b->[2]
           } map { [$_, /=(\d+)/, uc($_)] } @old;

    # using a prototype allows you to use any comparison subroutine
    # as a sort subroutine (including other package's subroutines)
    package other;
    sub backwards ($$) { $_[1] cmp $_[0]; }     # $a and $b are not set here

    package main;
    @new = sort other::backwards @old;

    # guarantee stability, regardless of algorithm
    use sort 'stable';
    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;

    # force use of mergesort (not portable outside Perl 5.8)
    use sort '_mergesort';  # note discouraging _
    @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;

If you're using strict, you must not declare $a and $b as lexicals. They are package globals. That means if you're in the main package and type

    @articles = sort {$b <=> $a} @files;

then $a and $b are $main::a and $main::b (or $::a and $::b), but if you're in the FooPack package, it's the same as typing

    @articles = sort {$FooPack::b <=> $FooPack::a} @files;

The comparison function is required to behave. If it returns inconsistent results (sometimes saying $x[1] is less than $x[2] and sometimes saying the opposite, for example) the results are not well-defined.

Because <=> returns undef when either operand is NaN (not-a-number), and because sort will trigger a fatal error unless the result of a comparison is defined, when sorting with a comparison function like $a <=> $b, be careful about lists that might contain a NaN. The following example takes advantage of the fact that NaN != NaN to eliminate any NaNs from the input.

    @result = sort { $a <=> $b } grep { $_ == $_ } @input;
splice ARRAY,OFFSET,LENGTH,LIST
splice ARRAY,OFFSET,LENGTH
splice ARRAY,OFFSET
splice ARRAY

Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. In list context, returns the elements removed from the array. In scalar context, returns the last element removed, or undef if no elements are removed. The array grows or shrinks as necessary. If OFFSET is negative then it starts that far from the end of the array. If LENGTH is omitted, removes everything from OFFSET onward. If LENGTH is negative, removes the elements from OFFSET onward except for -LENGTH elements at the end of the array. If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is past the end of the array, perl issues a warning, and splices at the end of the array.

The following equivalences hold (assuming $[ == 0 and $#a >= $i )

    push(@a,$x,$y)      splice(@a,@a,0,$x,$y)
    pop(@a)             splice(@a,-1)
    shift(@a)           splice(@a,0,1)
    unshift(@a,$x,$y)   splice(@a,0,0,$x,$y)
    $a[$i] = $y         splice(@a,$i,1,$y)

Example, assuming array lengths are passed before arrays:

    sub aeq {   # compare two list values
        my(@a) = splice(@_,0,shift);
        my(@b) = splice(@_,0,shift);
        return 0 unless @a == @b;       # same len?
        while (@a) {
            return 0 if pop(@a) ne pop(@b);
        }
        return 1;
    }
    if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
split /PATTERN/,EXPR,LIMIT
split /PATTERN/,EXPR
split /PATTERN/
split

Splits the string EXPR into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. (If all fields are empty, they are considered to be trailing.)

In scalar context, returns the number of fields found and splits into the @_ array. Use of split in scalar context is deprecated, however, because it clobbers your subroutine arguments.

If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything matching PATTERN is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.)

If LIMIT is specified and positive, it represents the maximum number of fields the EXPR will be split into, though the actual number of fields returned depends on the number of times PATTERN matches within EXPR. If LIMIT is unspecified or zero, trailing null fields are stripped (which potential users of pop would do well to remember). If LIMIT is negative, it is treated as if an arbitrarily large LIMIT had been specified. Note that splitting an EXPR that evaluates to the empty string always returns the empty list, regardless of the LIMIT specified.

A pattern matching the null string (not to be confused with a null pattern //, which is just one member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example:

    print join(':', split(/ */, 'hi there'));

produces the output 'h:i:t:h:e:r:e'.

As a special case for split, using the empty pattern // specifically matches only the null string, and is not be confused with the regular use of // to mean "the last successful pattern match". So, for split, the following:

    print join(':', split(//, 'hi there'));

produces the output 'h:i: :t:h:e:r:e'.

Empty leading (or trailing) fields are produced when there are positive width matches at the beginning (or end) of the string; a zero-width match at the beginning (or end) of the string does not produce an empty field. For example:

   print join(':', split(/(?=\w)/, 'hi there!'));

produces the output 'h:i :t:h:e:r:e!'.

The LIMIT parameter can be used to split a line partially

    ($login, $passwd, $remainder) = split(/:/, $_, 3);

When assigning to a list, if LIMIT is omitted, or zero, Perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need.

If the PATTERN contains parentheses, additional list elements are created from each matching substring in the delimiter.

    split(/([,-])/, "1-10,20", 3);

produces the list value

    (1, '-', 10, ',', 20)

If you had the entire header of a normal Unix email message in $header, you could split it up into fields and their values this way:

    $header =~ s/\n\s+/ /g;  # fix continuation lines
    %hdrs   =  (UNIX_FROM => split /^(\S*?):\s*/m, $header);

The pattern /PATTERN/ may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, use /$variable/o.)

As a special case, specifying a PATTERN of space (' ') will split on white space just as split with no arguments does. Thus, split(' ') can be used to emulate awk's default behavior, whereas split(/ /) will give you as many null initial fields as there are leading spaces. A split on /\s+/ is like a split(' ') except that any leading whitespace produces a null first field. A split with no arguments really does a split(' ', $_) internally.

A PATTERN of /^/ is treated as if it were /^/m, since it isn't much use otherwise.

Example:

    open(PASSWD, '/etc/passwd');
    while (<PASSWD>) {
        chomp;
        ($login, $passwd, $uid, $gid,
         $gcos, $home, $shell) = split(/:/);
        #...
    }

As with regular pattern matching, any capturing parentheses that are not matched in a split() will be set to undef when returned:

    @fields = split /(A)|B/, "1A2B3";
    # @fields is (1, 'A', 2, undef, 3)
sprintf FORMAT, LIST

Returns a string formatted by the usual printf conventions of the C library function sprintf. See below for more details and see sprintf(3) or printf(3) on your system for an explanation of the general principles.

For example:

        # Format number with up to 8 leading zeroes
        $result = sprintf("%08d", $number);

        # Round number to 3 digits after decimal point
        $rounded = sprintf("%.3f", $number);

Perl does its own sprintf formatting--it emulates the C function sprintf, but it doesn't use it (except for floating-point numbers, and even then only the standard modifiers are allowed). As a result, any non-standard extensions in your local sprintf are not available from Perl.

Unlike printf, sprintf does not do what you probably mean when you pass it an array as your first argument. The array is given scalar context, and instead of using the 0th element of the array as the format, Perl will use the count of elements in the array as the format, which is almost never useful.

Perl's sprintf permits the following universally-known conversions:

   %%   a percent sign
   %c   a character with the given number
   %s   a string
   %d   a signed integer, in decimal
   %u   an unsigned integer, in decimal
   %o   an unsigned integer, in octal
   %x   an unsigned integer, in hexadecimal
   %e   a floating-point number, in scientific notation
   %f   a floating-point number, in fixed decimal notation
   %g   a floating-point number, in %e or %f notation

In addition, Perl permits the following widely-supported conversions:

   %X   like %x, but using upper-case letters
   %E   like %e, but using an upper-case "E"
   %G   like %g, but with an upper-case "E" (if applicable)
   %b   an unsigned integer, in binary
   %p   a pointer (outputs the Perl value's address in hexadecimal)
   %n   special: *stores* the number of characters output so far
        into the next variable in the parameter list

Finally, for backward (and we do mean "backward") compatibility, Perl permits these unnecessary but widely-supported conversions:

   %i   a synonym for %d
   %D   a synonym for %ld
   %U   a synonym for %lu
   %O   a synonym for %lo
   %F   a synonym for %f

Note that the number of exponent digits in the scientific notation produced by %e, %E, %g and %G for numbers with the modulus of the exponent less than 100 is system-dependent: it may be three or less (zero-padded as necessary). In other words, 1.23 times ten to the 99th may be either "1.23e99" or "1.23e099".

Between the % and the format letter, you may specify a number of additional attributes controlling the interpretation of the format. In order, these are:

format parameter index

An explicit format parameter index, such as 2$. By default sprintf will format the next unused argument in the list, but this allows you to take the arguments out of order, e.g.:

  printf '%2$d %1$d', 12, 34;      # prints "34 12"
  printf '%3$d %d %1$d', 1, 2, 3;  # prints "3 1 1"
flags

one or more of: space prefix positive number with a space + prefix positive number with a plus sign - left-justify within the field 0 use zeros, not spaces, to right-justify # prefix non-zero octal with "0", non-zero hex with "0x", non-zero binary with "0b"

For example:

  printf '<% d>', 12;   # prints "< 12>"
  printf '<%+d>', 12;   # prints "<+12>"
  printf '<%6s>', 12;   # prints "<    12>"
  printf '<%-6s>', 12;  # prints "<12    >"
  printf '<%06s>', 12;  # prints "<000012>"
  printf '<%#x>', 12;   # prints "<0xc>"
vector flag

This flag tells perl to interpret the supplied string as a vector of integers, one for each character in the string. Perl applies the format to each integer in turn, then joins the resulting strings with a separator (a dot . by default). This can be useful for displaying ordinal values of characters in arbitrary strings:

  printf "%vd", "AB\x{100}";           # prints "65.66.256"
  printf "version is v%vd\n", $^V;     # Perl's version

Put an asterisk * before the v to override the string to use to separate the numbers:

  printf "address is %*vX\n", ":", $addr;   # IPv6 address
  printf "bits are %0*v8b\n", " ", $bits;   # random bitstring

You can also explicitly specify the argument number to use for the join string using e.g. *2$v:

  printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":";   # 3 IPv6 addresses
(minimum) width

Arguments are usually formatted to be only as wide as required to display the given value. You can override the width by putting a number here, or get the width from the next argument (with *) or from a specified argument (with e.g. *2$):

  printf '<%s>', "a";       # prints "<a>"
  printf '<%6s>', "a";      # prints "<     a>"
  printf '<%*s>', 6, "a";   # prints "<     a>"
  printf '<%*2$s>', "a", 6; # prints "<     a>"
  printf '<%2s>', "long";   # prints "<long>" (does not truncate)

If a field width obtained through * is negative, it has the same effect as the - flag: left-justification.

precision, or maximum width

You can specify a precision (for numeric conversions) or a maximum width (for string conversions) by specifying a . followed by a number. For floating point formats, with the exception of 'g' and 'G', this specifies the number of decimal places to show (the default being 6), e.g.:

  # these examples are subject to system-specific variation
  printf '<%f>', 1;    # prints "<1.000000>"
  printf '<%.1f>', 1;  # prints "<1.0>"
  printf '<%.0f>', 1;  # prints "<1>"
  printf '<%e>', 10;   # prints "<1.000000e+01>"
  printf '<%.1e>', 10; # prints "<1.0e+01>"

For 'g' and 'G', this specifies the maximum number of digits to show, including prior to the decimal point as well as after it, e.g.:

  # these examples are subject to system-specific variation
  printf '<%g>', 1;        # prints "<1>"
  printf '<%.10g>', 1;     # prints "<1>"
  printf '<%g>', 100;      # prints "<100>"
  printf '<%.1g>', 100;    # prints "<1e+02>"
  printf '<%.2g>', 100.01; # prints "<1e+02>"
  printf '<%.5g>', 100.01; # prints "<100.01>"
  printf '<%.4g>', 100.01; # prints "<100>"

For integer conversions, specifying a precision implies that the output of the number itself should be zero-padded to this width:

  printf '<%.6x>', 1;      # prints "<000001>"
  printf '<%#.6x>', 1;     # prints "<0x000001>"
  printf '<%-10.6x>', 1;   # prints "<000001    >"

For string conversions, specifying a precision truncates the string to fit in the specified width:

  printf '<%.5s>', "truncated";   # prints "<trunc>"
  printf '<%10.5s>', "truncated"; # prints "<     trunc>"

You can also get the precision from the next argument using .*:

  printf '<%.6x>', 1;       # prints "<000001>"
  printf '<%.*x>', 6, 1;    # prints "<000001>"

You cannot currently get the precision from a specified number, but it is intended that this will be possible in the future using e.g. .*2$:

  printf '<%.*2$x>', 1, 6;   # INVALID, but in future will print "<000001>"
size

For numeric conversions, you can specify the size to interpret the number as using l, h, V, q, L, or ll. For integer conversions (d u o x X b i D U O), numbers are usually assumed to be whatever the default integer size is on your platform (usually 32 or 64 bits), but you can override this to use instead one of the standard C types, as supported by the compiler used to build Perl:

   l           interpret integer as C type "long" or "unsigned long"
   h           interpret integer as C type "short" or "unsigned short"
   q, L or ll  interpret integer as C type "long long", "unsigned long long".
               or "quads" (typically 64-bit integers)

The last will produce errors if Perl does not understand "quads" in your installation. (This requires that either the platform natively supports quads or Perl was specifically compiled to support quads.) You can find out whether your Perl supports quads via the Config manpage:

        use Config;
        ($Config{use64bitint} eq 'define' || $Config{longsize} >= 8) &&
                print "quads\n";

For floating point conversions (e f g E F G), numbers are usually assumed to be the default floating point size on your platform (double or long double), but you can force 'long double' with q, L, or ll if your platform supports them. You can find out whether your Perl supports long doubles via the Config manpage:

        use Config;
        $Config{d_longdbl} eq 'define' && print "long doubles\n";

You can find out whether Perl considers 'long double' to be the default floating point size to use on your platform via the Config manpage:

        use Config;
        ($Config{uselongdouble} eq 'define') &&
                print "long doubles by default\n";

It can also be the case that long doubles and doubles are the same thing:

        use Config;
        ($Config{doublesize} == $Config{longdblsize}) &&
                print "doubles are long doubles\n";

The size specifier V has no effect for Perl code, but it is supported for compatibility with XS code; it means 'use the standard size for a Perl integer (or floating-point number)', which is already the default for Perl code.

order of arguments

Normally, sprintf takes the next unused argument as the value to format for each format specification. If the format specification uses * to require additional arguments, these are consumed from the argument list in the order in which they appear in the format specification before the value to format. Where an argument is specified using an explicit index, this does not affect the normal order for the arguments (even when the explicitly specified index would have been the next argument in any case).

So:

  printf '<%*.*s>', $a, $b, $c;

would use $a for the width, $b for the precision and $c as the value to format, while:

  print '<%*1$.*s>', $a, $b;

would use $a for the width and the precision, and $b as the value to format.

Here are some more examples - beware that when using an explicit index, the $ may need to be escaped:

  printf "%2\$d %d\n",    12, 34;               # will print "34 12\n"
  printf "%2\$d %d %d\n", 12, 34;               # will print "34 12 34\n"
  printf "%3\$d %d %d\n", 12, 34, 56;           # will print "56 12 34\n"
  printf "%2\$*3\$d %d\n", 12, 34, 3;           # will print " 34 12\n"

If use locale is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See the perllocale manpage.

sqrt EXPR
sqrt

Return the square root of EXPR. If EXPR is omitted, returns square root of $_. Only works on non-negative operands, unless you've loaded the standard Math::Complex module.

    use Math::Complex;
    print sqrt(-2);    # prints 1.4142135623731i
srand EXPR
srand

Sets the random number seed for the rand operator.

The point of the function is to "seed" the rand function so that rand can produce a different sequence each time you run your program.

If srand() is not called explicitly, it is called implicitly at the first use of the rand operator. However, this was not the case in versions of Perl before 5.004, so if your script will run under older Perl versions, it should call srand.

Most programs won't even call srand() at all, except those that need a cryptographically-strong starting point rather than the generally acceptable default, which is based on time of day, process ID, and memory allocation, or the /dev/urandom device, if available.

You can call srand($seed) with the same $seed to reproduce the same sequence from rand(), but this is usually reserved for generating predictable results for testing or debugging. Otherwise, don't call srand() more than once in your program.

Do not call srand() (i.e. without an argument) more than once in a script. The internal state of the random number generator should contain more entropy than can be provided by any seed, so calling srand() again actually loses randomness.

Most implementations of srand take an integer and will silently truncate decimal numbers. This means srand(42) will usually produce the same results as srand(42.1). To be safe, always pass srand an integer.

In versions of Perl prior to 5.004 the default seed was just the current time. This isn't a particularly good seed, so many old programs supply their own seed value (often time ^ $$ or time ^ ($$ + ($$ << 15))), but that isn't necessary any more.

For cryptographic purposes, however, you need something much more random than the default seed. Checksumming the compressed output of one or more rapidly changing operating system status programs is the usual method. For example:

    srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip`);

If you're particularly concerned with this, see the Math::TrulyRandom module in CPAN.

Frequently called programs (like CGI scripts) that simply use

    time ^ $$

for a seed can fall prey to the mathematical property that

    a^b == (a+1)^(b+1)

one-third of the time. So don't do that.

stat FILEHANDLE
stat EXPR
stat

Returns a 13-element list giving the status info for a file, either the file opened via FILEHANDLE, or named by EXPR. If EXPR is omitted, it stats $_. Returns a null list if the stat fails. Typically used as follows:

    ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
       $atime,$mtime,$ctime,$blksize,$blocks)
           = stat($filename);

Not all fields are supported on all filesystem types. Here are the meanings of the fields:

  0 dev      device number of filesystem
  1 ino      inode number
  2 mode     file mode  (type and permissions)
  3 nlink    number of (hard) links to the file
  4 uid      numeric user ID of file's owner
  5 gid      numeric group ID of file's owner
  6 rdev     the device identifier (special files only)
  7 size     total size of file, in bytes
  8 atime    last access time in seconds since the epoch
  9 mtime    last modify time in seconds since the epoch
 10 ctime    inode change time in seconds since the epoch (*)
 11 blksize  preferred block size for file system I/O
 12 blocks   actual number of blocks allocated

(The epoch was at 00:00 January 1, 1970 GMT.)

(*) Not all fields are supported on all filesystem types. Notably, the ctime field is non-portable. In particular, you cannot expect it to be a "creation time", see Files and Filesystems in the perlport manpage for details.

If stat is passed the special filehandle consisting of an underline, no stat is done, but the current contents of the stat structure from the last stat, lstat, or filetest are returned. Example:

    if (-x $file && (($d) = stat(_)) && $d < 0) {
        print "$file is executable NFS file\n";
    }

(This works on machines only for which the device number is negative under NFS.)

Because the mode contains both the file type and its permissions, you should mask off the file type portion and (s)printf using a "%o" if you want to see the real permissions.

    $mode = (stat($filename))[2];
    printf "Permissions are %04o\n", $mode & 07777;

In scalar context, stat returns a boolean value indicating success or failure, and, if successful, sets the information associated with the special filehandle _.

The File::stat module provides a convenient, by-name access mechanism:

    use File::stat;
    $sb = stat($filename);
    printf "File is %s, size is %s, perm %04o, mtime %s\n",
        $filename, $sb->size, $sb->mode & 07777,
        scalar localtime $sb->mtime;

You can import symbolic mode constants (S_IF*) and functions (S_IS*) from the Fcntl module:

    use Fcntl ':mode';

    $mode = (stat($filename))[2];

    $user_rwx      = ($mode & S_IRWXU) >> 6;
    $group_read    = ($mode & S_IRGRP) >> 3;
    $other_execute =  $mode & S_IXOTH;

    printf "Permissions are %04o\n", S_IMODE($mode), "\n";

    $is_setuid     =  $mode & S_ISUID;
    $is_setgid     =  S_ISDIR($mode);

You could write the last two using the -u and -d operators. The commonly available S_IF* constants are

    # Permissions: read, write, execute, for user, group, others.

    S_IRWXU S_IRUSR S_IWUSR S_IXUSR
    S_IRWXG S_IRGRP S_IWGRP S_IXGRP
    S_IRWXO S_IROTH S_IWOTH S_IXOTH
    # Setuid/Setgid/Stickiness/SaveText.
    # Note that the exact meaning of these is system dependent.

    S_ISUID S_ISGID S_ISVTX S_ISTXT
    # File types.  Not necessarily all are available on your system.

    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
    # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.

    S_IREAD S_IWRITE S_IEXEC

and the S_IF* functions are

    S_IMODE($mode)      the part of $mode containing the permission bits
                        and the setuid/setgid/sticky bits
    S_IFMT($mode)       the part of $mode containing the file type
                        which can be bit-anded with e.g. S_IFREG
                        or with the following functions
    # The operators -f, -d, -l, -b, -c, -p, and -S.

    S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
    S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
    # No direct -X operator counterpart, but for the first one
    # the -g operator is often equivalent.  The ENFMT stands for
    # record flocking enforcement, a platform-dependent feature.

    S_ISENFMT($mode) S_ISWHT($mode)

See your native chmod(2) and stat(2) documentation for more details about the S_* constants. To get status info for a symbolic link instead of the target file behind the link, use the lstat function.

study SCALAR
study

Takes extra time to study SCALAR ($_ if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching on, and on the distribution of character frequencies in the string to be searched--you probably want to compare run times with and without it to see which runs faster. Those loops that scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. You may have only one study active at a time--if you study a different scalar the first is "unstudied". (The way study works is this: a linked list of every character in the string to be searched is made, so we know, for example, where all the 'k' characters are. From each search string, the rarest character is selected, based on some static frequency tables constructed from some C programs and English text. Only those places that contain this "rarest" character are examined.)

For example, here is a loop that inserts index producing entries before any line containing a certain pattern:

    while (<>) {
        study;
        print ".IX foo\n"       if /\bfoo\b/;
        print ".IX bar\n"       if /\bbar\b/;
        print ".IX blurfl\n"    if /\bblurfl\b/;
        # ...
        print;
    }

In searching for /\bfoo\b/, only those locations in $_ that contain f will be looked at, because f is rarer than o. In general, this is a big win except in pathological cases. The only question is whether it saves you more time than it took to build the linked list in the first place.

Note that if you have to look for strings that you don't know till runtime, you can build an entire loop as a string and eval that to avoid recompiling all your patterns all the time. Together with undefining $/ to input entire files as one record, this can be very fast, often faster than specialized programs like fgrep(1). The following scans a list of files (@files) for a list of words (@words), and prints out the names of those files that contain a match:

    $search = 'while (<>) { study;';
    foreach $word (@words) {
        $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
    }
    $search .= "}";
    @ARGV = @files;
    undef $/;
    eval $search;               # this screams
    $/ = "\n";          # put back to normal input delimiter
    foreach $file (sort keys(%seen)) {
        print $file, "\n";
    }
sub NAME BLOCK
sub NAME (PROTO) BLOCK
sub NAME : ATTRS BLOCK
sub NAME (PROTO) : ATTRS BLOCK

This is subroutine definition, not a real function per se. Without a BLOCK it's just a forward declaration. Without a NAME, it's an anonymous function declaration, and does actually return a value: the CODE ref of the closure you just created.

See the perlsub manpage and the perlref manpage for details about subroutines and references, and the attributes manpage and the Attribute::Handlers manpage for more information about attributes.

substr EXPR,OFFSET,LENGTH,REPLACEMENT
substr EXPR,OFFSET,LENGTH
substr EXPR,OFFSET

Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set $[ to (but don't do that). If OFFSET is negative (or more precisely, less than $[), starts that far from the end of the string. If LENGTH is omitted, returns everything to the end of the string. If LENGTH is negative, leaves that many characters off the end of the string.

You can use the substr() function as an lvalue, in which case EXPR must itself be an lvalue. If you assign something shorter than LENGTH, the string will shrink, and if you assign something longer than LENGTH, the string will grow to accommodate it. To keep the string the same length you may need to pad or chop your value using sprintf.

If OFFSET and LENGTH specify a substring that is partly outside the string, only the part within the string is returned. If the substring is beyond either end of the string, substr() returns the undefined value and produces a warning. When used as an lvalue, specifying a substring that is entirely outside the string is a fatal error. Here's an example showing the behavior for boundary cases:

    my $name = 'fred';
    substr($name, 4) = 'dy';            # $name is now 'freddy'
    my $null = substr $name, 6, 2;      # returns '' (no warning)
    my $oops = substr $name, 7;         # returns undef, with warning
    substr($name, 7) = 'gap';           # fatal error

An alternative to using substr() as an lvalue is to specify the replacement string as the 4th argument. This allows you to replace parts of the EXPR and return what was there before in one operation, just as you can with splice().

symlink OLDFILE,NEWFILE

Creates a new filename symbolically linked to the old filename. Returns 1 for success, 0 otherwise. On systems that don't support symbolic links, produces a fatal error at run time. To check for that, use eval:

    $symlink_exists = eval { symlink("",""); 1 };
syscall NUMBER, LIST

Calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. If unimplemented, produces a fatal error. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to receive any result that might be written into a string. You can't use a string literal (or other read-only string) as an argument to syscall because Perl has to assume that any string pointer might be written through. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add 0 to them to force them to look like numbers. This emulates the syswrite function (or vice versa):

    require 'syscall.ph';               # may need to run h2ph
    $s = "hi there\n";
    syscall(&SYS_write, fileno(STDOUT), $s, length $s);

Note that Perl supports passing of up to only 14 arguments to your system call, which in practice should usually suffice.

Syscall returns whatever value returned by the system call it calls. If the system call fails, syscall returns -1 and sets $! (errno). Note that some system calls can legitimately return -1. The proper way to handle such calls is to assign $!=0; before the call and check the value of $! if syscall returns -1.

There's a problem with syscall(&SYS_pipe): it returns the file number of the read end of the pipe it creates. There is no way to retrieve the file number of the other end. You can avoid this problem by using pipe instead.

sysopen FILEHANDLE,FILENAME,MODE
sysopen FILEHANDLE,FILENAME,MODE,PERMS

Opens the file whose filename is given by FILENAME, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. This function calls the underlying operating system's open function with the parameters FILENAME, MODE, PERMS.

The possible values and flag bits of the MODE parameter are system-dependent; they are available via the standard module Fcntl. See the documentation of your operating system's open to see which values and flag bits are available. You may combine several flags using the |-operator.

Some of the most common values are O_RDONLY for opening the file in read-only mode, O_WRONLY for opening the file in write-only mode, and O_RDWR for opening the file in read-write mode.

For historical reasons, some values work on almost every system supported by perl: zero means read-only, one means write-only, and two means read/write. We know that these values do not work under OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to use them in new code.

If the file named by FILENAME does not exist and the open call creates it (typically because MODE includes the O_CREAT flag), then the value of PERMS specifies the permissions of the newly created file. If you omit the PERMS argument to sysopen, Perl uses the octal value 0666. These permission values need to be in octal, and are modified by your process's current umask.

In many systems the O_EXCL flag is available for opening files in exclusive mode. This is not locking: exclusiveness means here that if the file already exists, sysopen() fails. O_EXCL may not work on network filesystems, and has no effect unless the O_CREAT flag is set as well. Setting O_CREAT|O_EXCL prevents the file from being opened if it is a symbolic link. It does not protect against symbolic links in the file's path.

Sometimes you may want to truncate an already-existing file. This can be done using the O_TRUNC flag. The behavior of O_TRUNC with O_RDONLY is undefined.

You should seldom if ever use 0644 as argument to sysopen, because that takes away the user's option to have a more permissive umask. Better to omit it. See the perlfunc(1) entry on umask for more on this.

Note that sysopen depends on the fdopen() C library function. On many UNIX systems, fdopen() is known to fail when file descriptors exceed a certain value, typically 255. If you need more file descriptors than that, consider rebuilding Perl to use the sfio library, or perhaps using the POSIX::open() function.

See the perlopentut manpage for a kinder, gentler explanation of opening files.

sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
sysread FILEHANDLE,SCALAR,LENGTH

Attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE, using the system call read(2). It bypasses buffered IO, so mixing this with other kinds of reads, print, write, seek, tell, or eof can cause confusion because the perlio or stdio layers usually buffers data. Returns the number of bytes actually read, 0 at end of file, or undef if there was an error (in the latter case $! is also set). SCALAR will be grown or shrunk so that the last byte actually read is the last byte of the scalar after the read.

An OFFSET may be specified to place the read data at some place in the string other than the beginning. A negative OFFSET specifies placement at that many characters counting backwards from the end of the string. A positive OFFSET greater than the length of SCALAR results in the string being padded to the required size with "\0" bytes before the result of the read is appended.

There is no syseof() function, which is ok, since eof() doesn't work very well on device files (like ttys) anyway. Use sysread() and check for a return value for 0 to decide whether you're done.

Note that if the filehandle has been marked as :utf8 Unicode characters are read instead of bytes (the LENGTH, OFFSET, and the return value of sysread() are in Unicode characters). The :encoding(...) layer implicitly introduces the :utf8 layer. See binmode, open, and the open pragma, the open manpage.

sysseek FILEHANDLE,POSITION,WHENCE

Sets FILEHANDLE's system position in bytes using the system call lseek(2). FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are 0 to set the new position to POSITION, 1 to set the it to the current position plus POSITION, and 2 to set it to EOF plus POSITION (typically negative).

Note the in bytes: even if the filehandle has been set to operate on characters (for example by using the :utf8 I/O layer), tell() will return byte offsets, not character offsets (because implementing that would render sysseek() very slow).

sysseek() bypasses normal buffered IO, so mixing this with reads (other than sysread, for example <> or read()) print, write, seek, tell, or eof may cause confusion.

For WHENCE, you may also use the constants SEEK_SET, SEEK_CUR, and SEEK_END (start of the file, current position, end of the file) from the Fcntl module. Use of the constants is also more portable than relying on 0, 1, and 2. For example to define a "systell" function:

        use Fcntl 'SEEK_CUR';
        sub systell { sysseek($_[0], 0, SEEK_CUR) }

Returns the new position, or the undefined value on failure. A position of zero is returned as the string "0 but true"; thus sysseek returns true on success and false on failure, yet you can still easily determine the new position.

system LIST
system PROGRAM LIST

Does exactly the same thing as exec LIST, except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. If there is more than one argument in LIST, or if LIST is an array with more than one value, starts the program given by the first element of the list with arguments given by the rest of the list. If there is only one scalar argument, the argument is checked for shell metacharacters, and if there are any, the entire argument is passed to the system's command shell for parsing (this is /bin/sh -c on Unix platforms, but varies on other platforms). If there are no shell metacharacters in the argument, it is split into words and passed directly to execvp, which is more efficient.

Beginning with v5.6.0, Perl will attempt to flush all files opened for output before any operation that may do a fork, but this may not be supported on some platforms (see the perlport manpage). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles.

The return value is the exit status of the program as returned by the wait call. To get the actual exit value, shift right by eight (see below). See also exec. This is not what you want to use to capture the output from a command, for that you should use merely backticks or qx//, as described in `STRING` in the perlop manpage. Return value of -1 indicates a failure to start the program or an error of the wait(2) system call (inspect $! for the reason).

Like exec, system allows you to lie to a program about its name if you use the system PROGRAM LIST syntax. Again, see exec.

Since SIGINT and SIGQUIT are ignored during the execution of system, if you expect your program to terminate on receipt of these signals you will need to arrange to do so yourself based on the return value.

    @args = ("command", "arg1", "arg2");
    system(@args) == 0
         or die "system @args failed: $?"

You can check all the failure possibilities by inspecting $? like this:

    if ($? == -1) {
        print "failed to execute: $!\n";
    }
    elsif ($? & 127) {
        printf "child died with signal %d, %s coredump\n",
            ($? & 127),  ($? & 128) ? 'with' : 'without';
    }
    else {
        printf "child exited with value %d\n", $? >> 8;
    }

or more portably by using the W*() calls of the POSIX extension; see the perlport manpage for more information.

When the arguments get executed via the system shell, results and return codes will be subject to its quirks and capabilities. See `STRING` in the perlop manpage and exec for details.

syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
syswrite FILEHANDLE,SCALAR,LENGTH
syswrite FILEHANDLE,SCALAR

Attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE, using the system call write(2). If LENGTH is not specified, writes whole SCALAR. It bypasses buffered IO, so mixing this with reads (other than sysread()), print, write, seek, tell, or eof may cause confusion because the perlio and stdio layers usually buffers data. Returns the number of bytes actually written, or undef if there was an error (in this case the errno variable $! is also set). If the LENGTH is greater than the available data in the SCALAR after the OFFSET, only as much data as is available will be written.

An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing that many characters counting backwards from the end of the string. In the case the SCALAR is empty you can use OFFSET but only zero offset.

Note that if the filehandle has been marked as :utf8, Unicode characters are written instead of bytes (the LENGTH, OFFSET, and the return value of syswrite() are in UTF-8 encoded Unicode characters). The :encoding(...) layer implicitly introduces the :utf8 layer. See binmode, open, and the open pragma, the open manpage.

tell FILEHANDLE
tell

Returns the current position in bytes for FILEHANDLE, or -1 on error. FILEHANDLE may be an expression whose value gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes the file last read.

Note the in bytes: even if the filehandle has been set to operate on characters (for example by using the :utf8 open layer), tell() will return byte offsets, not character offsets (because that would render seek() and tell() rather slow).

The return value of tell() for the standard streams like the STDIN depends on the operating system: it may return -1 or something else. tell() on pipes, fifos, and sockets usually returns -1.

There is no systell function. Use sysseek(FH, 0, 1) for that.

Do not use tell() (or other buffered I/O operations) on a file handle that has been manipulated by sysread(), syswrite() or sysseek(). Those functions ignore the buffering, while tell() does not.

telldir DIRHANDLE

Returns the current position of the readdir routines on DIRHANDLE. Value may be given to seekdir to access a particular location in a directory. telldir has the same caveats about possible directory compaction as the corresponding system library routine.

tie VARIABLE,CLASSNAME,LIST

This function binds a variable to a package class that will provide the implementation for the variable. VARIABLE is the name of the variable to be enchanted. CLASSNAME is the name of a class implementing objects of correct type. Any additional arguments are passed to the new method of the class (meaning TIESCALAR, TIEHANDLE, TIEARRAY, or TIEHASH). Typically these are arguments such as might be passed to the dbm_open() function of C. The object returned by the new method is also returned by the tie function, which would be useful if you want to access other methods in CLASSNAME.

Note that functions such as keys and values may return huge lists when used on large objects, like DBM files. You may prefer to use the each function to iterate over such. Example:

    # print out history file offsets
    use NDBM_File;
    tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
    while (($key,$val) = each %HIST) {
        print $key, ' = ', unpack('L',$val), "\n";
    }
    untie(%HIST);

A class implementing a hash should have the following methods:

    TIEHASH classname, LIST
    FETCH this, key
    STORE this, key, value
    DELETE this, key
    CLEAR this
    EXISTS this, key
    FIRSTKEY this
    NEXTKEY this, lastkey
    SCALAR this
    DESTROY this
    UNTIE this

A class implementing an ordinary array should have the following methods:

    TIEARRAY classname, LIST
    FETCH this, key
    STORE this, key, value
    FETCHSIZE this
    STORESIZE this, count
    CLEAR this
    PUSH this, LIST
    POP this
    SHIFT this
    UNSHIFT this, LIST
    SPLICE this, offset, length, LIST
    EXTEND this, count
    DESTROY this
    UNTIE this

A class implementing a file handle should have the following methods:

    TIEHANDLE classname, LIST
    READ this, scalar, length, offset
    READLINE this
    GETC this
    WRITE this, scalar, length, offset
    PRINT this, LIST
    PRINTF this, format, LIST
    BINMODE this
    EOF this
    FILENO this
    SEEK this, position, whence
    TELL this
    OPEN this, mode, LIST
    CLOSE this
    DESTROY this
    UNTIE this

A class implementing a scalar should have the following methods:

    TIESCALAR classname, LIST
    FETCH this,
    STORE this, value
    DESTROY this
    UNTIE this

Not all methods indicated above need be implemented. See the perltie manpage, the Tie::Hash manpage, the Tie::Array manpage, the Tie::Scalar manpage, and the Tie::Handle manpage.

Unlike dbmopen, the tie function will not use or require a module for you--you need to do that explicitly yourself. See DB_File or the Config module for interesting tie implementations.

For further details see the perltie manpage, tied VARIABLE.

tied VARIABLE

Returns a reference to the object underlying VARIABLE (the same value that was originally returned by the tie call that bound the variable to a package.) Returns the undefined value if VARIABLE isn't tied to a package.

time

Returns the number of non-leap seconds since whatever time the system considers to be the epoch, suitable for feeding to gmtime and localtime. On most systems the epoch is 00:00:00 UTC, January 1, 1970; a prominent exception being Mac OS Classic which uses 00:00:00, January 1, 1904 in the current local time zone for its epoch.

For measuring time in better granularity than one second, you may use either the Time::HiRes module (from CPAN, and starting from Perl 5.8 part of the standard distribution), or if you have gettimeofday(2), you may be able to use the syscall interface of Perl. See the perlfaq8 manpage for details.

times

Returns a four-element list giving the user and system times, in seconds, for this process and the children of this process.

    ($user,$system,$cuser,$csystem) = times;

In scalar context, times returns $user.

tr///

The transliteration operator. Same as y///. See the perlop manpage.

truncate FILEHANDLE,LENGTH
truncate EXPR,LENGTH

Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified length. Produces a fatal error if truncate isn't implemented on your system. Returns true if successful, the undefined value otherwise.

The behavior is undefined if LENGTH is greater than the length of the file.

uc EXPR
uc

Returns an uppercased version of EXPR. This is the internal function implementing the \U escape in double-quoted strings. Respects current LC_CTYPE locale if use locale in force. See the perllocale manpage and the perlunicode manpage for more details about locale and Unicode support. It does not attempt to do titlecase mapping on initial letters. See ucfirst for that.

If EXPR is omitted, uses $_.

ucfirst EXPR
ucfirst

Returns the value of EXPR with the first character in uppercase (titlecase in Unicode). This is the internal function implementing the \u escape in double-quoted strings. Respects current LC_CTYPE locale if use locale in force. See the perllocale manpage and the perlunicode manpage for more details about locale and Unicode support.

If EXPR is omitted, uses $_.

umask EXPR
umask

Sets the umask for the process to EXPR and returns the previous value. If EXPR is omitted, merely returns the current umask.

The Unix permission rwxr-x--- is represented as three sets of three bits, or three octal digits: 0750 (the leading 0 indicates octal and isn't one of the digits). The umask value is such a number representing disabled permissions bits. The permission (or "mode") values you pass mkdir or sysopen are modified by your umask, so even if you tell sysopen to create a file with permissions 0777, if your umask is 0022 then the file will actually be created with permissions 0755. If your umask were 0027 (group can't write; others can't read, write, or execute), then passing sysopen 0666 would create a file with mode 0640 (0666 &~ 027 is 0640).

Here's some advice: supply a creation mode of 0666 for regular files (in sysopen) and one of 0777 for directories (in mkdir) and executable files. This gives users the freedom of choice: if they want protected files, they might choose process umasks of 022, 027, or even the particularly antisocial mask of 077. Programs should rarely if ever make policy decisions better left to the user. The exception to this is when writing files that should be kept private: mail files, web browser cookies, .rhosts files, and so on.

If umask(2) is not implemented on your system and you are trying to restrict access for yourself (i.e., (EXPR & 0700) > 0), produces a fatal error at run time. If umask(2) is not implemented and you are not trying to restrict access for yourself, returns undef.

Remember that a umask is a number, usually given in octal; it is not a string of octal digits. See also oct, if all you have is a string.

undef EXPR
undef

Undefines the value of EXPR, which must be an lvalue. Use only on a scalar value, an array (using @), a hash (using %), a subroutine (using &), or a typeglob (using *). (Saying undef $hash{$key} will probably not do what you expect on most predefined variables or DBM list values, so don't do that; see delete.) Always returns the undefined value. You can omit the EXPR, in which case nothing is undefined, but you still get an undefined value that you could, for instance, return from a subroutine, assign to a variable or pass as a parameter. Examples:

    undef $foo;
    undef $bar{'blurfl'};      # Compare to: delete $bar{'blurfl'};
    undef @ary;
    undef %hash;
    undef &mysub;
    undef *xyz;       # destroys $xyz, @xyz, %xyz, &xyz, etc.
    return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
    select undef, undef, undef, 0.25;
    ($a, $b, undef, $c) = &foo;       # Ignore third value returned

Note that this is a unary operator, not a list operator.

unlink LIST
unlink

Deletes a list of files. Returns the number of files successfully deleted.

    $cnt = unlink 'a', 'b', 'c';
    unlink @goners;
    unlink <*.bak>;

Note: unlink will not attempt to delete directories unless you are superuser and the -U flag is supplied to Perl. Even if these conditions are met, be warned that unlinking a directory can inflict damage on your filesystem. Finally, using unlink on directories is not supported on many operating systems. Use rmdir instead.

If LIST is omitted, uses $_.

unpack TEMPLATE,EXPR

unpack does the reverse of pack: it takes a string and expands it out into a list of values. (In scalar context, it returns merely the first value produced.)

The string is broken into chunks described by the TEMPLATE. Each chunk is converted separately to a value. Typically, either the string is a result of pack, or the bytes of the string represent a C structure of some kind.

The TEMPLATE has the same format as in the pack function. Here's a subroutine that does substring:

    sub substr {
        my($what,$where,$howmuch) = @_;
        unpack("x$where a$howmuch", $what);
    }

and then there's

    sub ordinal { unpack("c",$_[0]); } # same as ord()

In addition to fields allowed in pack(), you may prefix a field with a %<number> to indicate that you want a <number>-bit checksum of the items instead of the items themselves. Default is a 16-bit checksum. Checksum is calculated by summing numeric values of expanded values (for string fields the sum of ord($char) is taken, for bit fields the sum of zeroes and ones).

For example, the following computes the same number as the System V sum program:

    $checksum = do {
        local $/;  # slurp!
        unpack("%32C*",<>) % 65535;
    };

The following efficiently counts the number of set bits in a bit vector:

    $setbits = unpack("%32b*", $selectmask);

The p and P formats should be used with care. Since Perl has no way of checking whether the value passed to unpack() corresponds to a valid memory location, passing a pointer value that's not known to be valid is likely to have disastrous consequences.

If there are more pack codes or if the repeat count of a field or a group is larger than what the remainder of the input string allows, the result is not well defined: in some cases, the repeat count is decreased, or unpack() will produce null strings or zeroes, or terminate with an error. If the input string is longer than one described by the TEMPLATE, the rest is ignored.

See pack for more examples and notes.

untie VARIABLE

Breaks the binding between a variable and a package. (See tie.) Has no effect if the variable is not tied.

unshift ARRAY,LIST

Does the opposite of a shift. Or the opposite of a push, depending on how you look at it. Prepends list to the front of the array, and returns the new number of elements in the array.

    unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;

Note the LIST is prepended whole, not one element at a time, so the prepended elements stay in the same order. Use reverse to do the reverse.

use Module VERSION LIST
use Module VERSION
use Module LIST
use Module
use VERSION

Imports some semantics into the current package from the named module, generally by aliasing certain subroutine or variable names into your package. It is exactly equivalent to

    BEGIN { require Module; import Module LIST; }

except that Module must be a bareword.

VERSION may be either a numeric argument such as 5.006, which will be compared to $], or a literal of the form v5.6.1, which will be compared to $^V (aka $PERL_VERSION. A fatal error is produced if VERSION is greater than the version of the current Perl interpreter; Perl will not attempt to parse the rest of the file. Compare with require, which can do a similar check at run time.

Specifying VERSION as a literal of the form v5.6.1 should generally be avoided, because it leads to misleading error messages under earlier versions of Perl that do not support this syntax. The equivalent numeric version should be used instead.

    use v5.6.1;         # compile time version check
    use 5.6.1;          # ditto
    use 5.006_001;      # ditto; preferred for backwards compatibility

This is often useful if you need to check the current Perl version before useing library modules that have changed in incompatible ways from older versions of Perl. (We try not to do this more than we have to.)

The BEGIN forces the require and import to happen at compile time. The require makes sure the module is loaded into memory if it hasn't been yet. The import is not a builtin--it's just an ordinary static method call into the Module package to tell the module to import the list of features back into the current package. The module can implement its import method any way it likes, though most modules just choose to derive their import method via inheritance from the Exporter class that is defined in the Exporter module. See the Exporter manpage. If no import method can be found then the call is skipped.

If you do not want to call the package's import method (for instance, to stop your namespace from being altered), explicitly supply the empty list:

    use Module ();

That is exactly equivalent to

    BEGIN { require Module }

If the VERSION argument is present between Module and LIST, then the use will call the VERSION method in class Module with the given version as an argument. The default VERSION method, inherited from the UNIVERSAL class, croaks if the given version is larger than the value of the variable $Module::VERSION.

Again, there is a distinction between omitting LIST (import called with no arguments) and an explicit empty LIST () (import not called). Note that there is no comma after VERSION!

Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are:

    use constant;
    use diagnostics;
    use integer;
    use sigtrap  qw(SEGV BUS);
    use strict   qw(subs vars refs);
    use subs     qw(afunc blurfl);
    use warnings qw(all);
    use sort     qw(stable _quicksort _mergesort);

Some of these pseudo-modules import semantics into the current block scope (like strict or integer, unlike ordinary modules, which import symbols into the current package (which are effective through the end of the file).

There's a corresponding no command that unimports meanings imported by use, i.e., it calls unimport Module LIST instead of import.

    no integer;
    no strict 'refs';
    no warnings;

See the perlmodlib manpage for a list of standard modules and pragmas. See the perlrun manpage for the -M and -m command-line options to perl that give use functionality from the command-line.

utime LIST

Changes the access and modification times on each file of a list of files. The first two elements of the list must be the NUMERICAL access and modification times, in that order. Returns the number of files successfully changed. The inode change time of each file is set to the current time. For example, this code has the same effect as the Unix touch(1) command when the files already exist and belong to the user running the program:

    #!/usr/bin/perl
    $atime = $mtime = time;
    utime $atime, $mtime, @ARGV;

Since perl 5.7.2, if the first two elements of the list are undef, then the utime(2) function in the C library will be called with a null second argument. On most systems, this will set the file's access and modification times to the current time (i.e. equivalent to the example above) and will even work on other users' files where you have write permission:

    utime undef, undef, @ARGV;

Under NFS this will use the time of the NFS server, not the time of the local machine. If there is a time synchronization problem, the NFS server and local machine will have different times. The Unix touch(1) command will in fact normally use this form instead of the one shown in the first example.

Note that only passing one of the first two elements as undef will be equivalent of passing it as 0 and will not have the same effect as described when they are both undef. This case will also trigger an uninitialized warning.

values HASH

Returns a list consisting of all the values of the named hash. (In a scalar context, returns the number of values.)

The values are returned in an apparently random order. The actual random order is subject to change in future versions of perl, but it is guaranteed to be the same order as either the keys or each function would produce on the same (unmodified) hash. Since Perl 5.8.1 the ordering is different even between different runs of Perl for security reasons (see Algorithmic Complexity Attacks in the perlsec manpage).

As a side effect, calling values() resets the HASH's internal iterator, see each. (In particular, calling values() in void context resets the iterator with no other overhead.)

Note that the values are not copied, which means modifying them will modify the contents of the hash:

    for (values %hash)      { s/foo/bar/g }   # modifies %hash values
    for (@hash{keys %hash}) { s/foo/bar/g }   # same

See also keys, each, and sort.

vec EXPR,OFFSET,BITS

Treats the string in EXPR as a bit vector made up of elements of width BITS, and returns the value of the element specified by OFFSET as an unsigned integer. BITS therefore specifies the number of bits that are reserved for each element in the bit vector. This must be a power of two from 1 to 32 (or 64, if your platform supports that).

If BITS is 8, "elements" coincide with bytes of the input string.

If BITS is 16 or more, bytes of the input string are grouped into chunks of size BITS/8, and each group is converted to a number as with pack()/unpack() with big-endian formats n/N (and analogously for BITS==64). See pack for details.

If bits is 4 or less, the string is broken into bytes, then the bits of each byte are broken into 8/BITS groups. Bits of a byte are numbered in a little-endian-ish way, as in 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80. For example, breaking the single input byte chr(0x36) into two groups gives a list (0x6, 0x3); breaking it into 4 groups gives (0x2, 0x1, 0x3, 0x0).

vec may also be assigned to, in which case parentheses are needed to give the expression the correct precedence as in

    vec($image, $max_x * $x + $y, 8) = 3;

If the selected element is outside the string, the value 0 is returned. If an element off the end of the string is written to, Perl will first extend the string with sufficiently many zero bytes. It is an error to try to write off the beginning of the string (i.e. negative OFFSET).

The string should not contain any character with the value > 255 (which can only happen if you're using UTF-8 encoding). If it does, it will be treated as something that is not UTF-8 encoded. When the vec was assigned to, other parts of your program will also no longer consider the string to be UTF-8 encoded. In other words, if you do have such characters in your string, vec() will operate on the actual byte string, and not the conceptual character string.

Strings created with vec can also be manipulated with the logical operators |, &, ^, and ~. These operators will assume a bit vector operation is desired when both operands are strings. See Bitwise String Operators in the perlop manpage.

The following code will build up an ASCII string saying 'PerlPerlPerl'. The comments show the string after each step. Note that this code works in the same way on big-endian or little-endian machines.

    my $foo = '';
    vec($foo,  0, 32) = 0x5065726C;     # 'Perl'

    # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
    print vec($foo, 0, 8);              # prints 80 == 0x50 == ord('P')

    vec($foo,  2, 16) = 0x5065;         # 'PerlPe'
    vec($foo,  3, 16) = 0x726C;         # 'PerlPerl'
    vec($foo,  8,  8) = 0x50;           # 'PerlPerlP'
    vec($foo,  9,  8) = 0x65;           # 'PerlPerlPe'
    vec($foo, 20,  4) = 2;              # 'PerlPerlPe'   . "\x02"
    vec($foo, 21,  4) = 7;              # 'PerlPerlPer'
                                        # 'r' is "\x72"
    vec($foo, 45,  2) = 3;              # 'PerlPerlPer'  . "\x0c"
    vec($foo, 93,  1) = 1;              # 'PerlPerlPer'  . "\x2c"
    vec($foo, 94,  1) = 1;              # 'PerlPerlPerl'
                                        # 'l' is "\x6c"

To transform a bit vector into a string or list of 0's and 1's, use these:

    $bits = unpack("b*", $vector);
    @bits = split(//, unpack("b*", $vector));

If you know the exact length in bits, it can be used in place of the *.

Here is an example to illustrate how the bits actually fall in place:

    #!/usr/bin/perl -wl

    print <<'EOT';
                                      0         1         2         3
                       unpack("V",$_) 01234567890123456789012345678901
    ------------------------------------------------------------------
    EOT

    for $w (0..3) {
        $width = 2**$w;
        for ($shift=0; $shift < $width; ++$shift) {
            for ($off=0; $off < 32/$width; ++$off) {
                $str = pack("B*", "0"x32);
                $bits = (1<<$shift);
                vec($str, $off, $width) = $bits;
                $res = unpack("b*",$str);
                $val = unpack("V", $str);
                write;
            }
        }
    }

    format STDOUT =
    vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    $off, $width, $bits, $val, $res
    .
    __END__

Regardless of the machine architecture on which it is run, the above example should print the following table:

                                      0         1         2         3
                       unpack("V",$_) 01234567890123456789012345678901
    ------------------------------------------------------------------
    vec($_, 0, 1) = 1   ==          1 10000000000000000000000000000000
    vec($_, 1, 1) = 1   ==          2 01000000000000000000000000000000
    vec($_, 2, 1) = 1   ==          4 00100000000000000000000000000000
    vec($_, 3, 1) = 1   ==          8 00010000000000000000000000000000
    vec($_, 4, 1) = 1   ==         16 00001000000000000000000000000000
    vec($_, 5, 1) = 1   ==         32 00000100000000000000000000000000
    vec($_, 6, 1) = 1   ==         64 00000010000000000000000000000000
    vec($_, 7, 1) = 1   ==        128 00000001000000000000000000000000
    vec($_, 8, 1) = 1   ==        256 00000000100000000000000000000000
    vec($_, 9, 1) = 1   ==        512 00000000010000000000000000000000
    vec($_,10, 1) = 1   ==       1024 00000000001000000000000000000000
    vec($_,11, 1) = 1   ==       2048 00000000000100000000000000000000
    vec($_,12, 1) = 1   ==       4096 00000000000010000000000000000000
    vec($_,13, 1) = 1   ==       8192 00000000000001000000000000000000
    vec($_,14, 1) = 1   ==      16384 00000000000000100000000000000000
    vec($_,15, 1) = 1   ==      32768 00000000000000010000000000000000
    vec($_,16, 1) = 1   ==      65536 00000000000000001000000000000000
    vec($_,17, 1) = 1   ==     131072 00000000000000000100000000000000
    vec($_,18, 1) = 1   ==     262144 00000000000000000010000000000000
    vec($_,19, 1) = 1   ==     524288 00000000000000000001000000000000
    vec($_,20, 1) = 1   ==    1048576 00000000000000000000100000000000
    vec($_,21, 1) = 1   ==    2097152 00000000000000000000010000000000
    vec($_,22, 1) = 1   ==    4194304 00000000000000000000001000000000
    vec($_,23, 1) = 1   ==    8388608 00000000000000000000000100000000
    vec($_,24, 1) = 1   ==   16777216 00000000000000000000000010000000
    vec($_,25, 1) = 1   ==   33554432 00000000000000000000000001000000
    vec($_,26, 1) = 1   ==   67108864 00000000000000000000000000100000
    vec($_,27, 1) = 1   ==  134217728 00000000000000000000000000010000
    vec($_,28, 1) = 1   ==  268435456 00000000000000000000000000001000
    vec($_,29, 1) = 1   ==  536870912 00000000000000000000000000000100
    vec($_,30, 1) = 1   == 1073741824 00000000000000000000000000000010
    vec($_,31, 1) = 1   == 2147483648 00000000000000000000000000000001
    vec($_, 0, 2) = 1   ==          1 10000000000000000000000000000000
    vec($_, 1, 2) = 1   ==          4 00100000000000000000000000000000
    vec($_, 2, 2) = 1   ==         16 00001000000000000000000000000000
    vec($_, 3, 2) = 1   ==         64 00000010000000000000000000000000
    vec($_, 4, 2) = 1   ==        256 00000000100000000000000000000000
    vec($_, 5, 2) = 1   ==       1024 00000000001000000000000000000000
    vec($_, 6, 2) = 1   ==       4096 00000000000010000000000000000000
    vec($_, 7, 2) = 1   ==      16384 00000000000000100000000000000000
    vec($_, 8, 2) = 1   ==      65536 00000000000000001000000000000000
    vec($_, 9, 2) = 1   ==     262144 00000000000000000010000000000000
    vec($_,10, 2) = 1   ==    1048576 00000000000000000000100000000000
    vec($_,11, 2) = 1   ==    4194304 00000000000000000000001000000000
    vec($_,12, 2) = 1   ==   16777216 00000000000000000000000010000000
    vec($_,13, 2) = 1   ==   67108864 00000000000000000000000000100000
    vec($_,14, 2) = 1   ==  268435456 00000000000000000000000000001000
    vec($_,15, 2) = 1   == 1073741824 00000000000000000000000000000010
    vec($_, 0, 2) = 2   ==          2 01000000000000000000000000000000
    vec($_, 1, 2) = 2   ==          8 00010000000000000000000000000000
    vec($_, 2, 2) = 2   ==         32 00000100000000000000000000000000
    vec($_, 3, 2) = 2   ==        128 00000001000000000000000000000000
    vec($_, 4, 2) = 2   ==        512 00000000010000000000000000000000
    vec($_, 5, 2) = 2   ==       2048 00000000000100000000000000000000
    vec($_, 6, 2) = 2   ==       8192 00000000000001000000000000000000
    vec($_, 7, 2) = 2   ==      32768 00000000000000010000000000000000
    vec($_, 8, 2) = 2   ==     131072 00000000000000000100000000000000
    vec($_, 9, 2) = 2   ==     524288 00000000000000000001000000000000
    vec($_,10, 2) = 2   ==    2097152 00000000000000000000010000000000
    vec($_,11, 2) = 2   ==    8388608 00000000000000000000000100000000
    vec($_,12, 2) = 2   ==   33554432 00000000000000000000000001000000
    vec($_,13, 2) = 2   ==  134217728 00000000000000000000000000010000
    vec($_,14, 2) = 2   ==  536870912 00000000000000000000000000000100
    vec($_,15, 2) = 2   == 2147483648 00000000000000000000000000000001
    vec($_, 0, 4) = 1   ==          1 10000000000000000000000000000000
    vec($_, 1, 4) = 1   ==         16 00001000000000000000000000000000
    vec($_, 2, 4) = 1   ==        256 00000000100000000000000000000000
    vec($_, 3, 4) = 1   ==       4096 00000000000010000000000000000000
    vec($_, 4, 4) = 1   ==      65536 00000000000000001000000000000000
    vec($_, 5, 4) = 1   ==    1048576 00000000000000000000100000000000
    vec($_, 6, 4) = 1   ==   16777216 00000000000000000000000010000000
    vec($_, 7, 4) = 1   ==  268435456 00000000000000000000000000001000
    vec($_, 0, 4) = 2   ==          2 01000000000000000000000000000000
    vec($_, 1, 4) = 2   ==         32 00000100000000000000000000000000
    vec($_, 2, 4) = 2   ==        512 00000000010000000000000000000000
    vec($_, 3, 4) = 2   ==       8192 00000000000001000000000000000000
    vec($_, 4, 4) = 2   ==     131072 00000000000000000100000000000000
    vec($_, 5, 4) = 2   ==    2097152 00000000000000000000010000000000
    vec($_, 6, 4) = 2   ==   33554432 00000000000000000000000001000000
    vec($_, 7, 4) = 2   ==  536870912 00000000000000000000000000000100
    vec($_, 0, 4) = 4   ==          4 00100000000000000000000000000000
    vec($_, 1, 4) = 4   ==         64 00000010000000000000000000000000
    vec($_, 2, 4) = 4   ==       1024 00000000001000000000000000000000
    vec($_, 3, 4) = 4   ==      16384 00000000000000100000000000000000
    vec($_, 4, 4) = 4   ==     262144 00000000000000000010000000000000
    vec($_, 5, 4) = 4   ==    4194304 00000000000000000000001000000000
    vec($_, 6, 4) = 4   ==   67108864 00000000000000000000000000100000
    vec($_, 7, 4) = 4   == 1073741824 00000000000000000000000000000010
    vec($_, 0, 4) = 8   ==          8 00010000000000000000000000000000
    vec($_, 1, 4) = 8   ==        128 00000001000000000000000000000000
    vec($_, 2, 4) = 8   ==       2048 00000000000100000000000000000000
    vec($_, 3, 4) = 8   ==      32768 00000000000000010000000000000000
    vec($_, 4, 4) = 8   ==     524288 00000000000000000001000000000000
    vec($_, 5, 4) = 8   ==    8388608 00000000000000000000000100000000
    vec($_, 6, 4) = 8   ==  134217728 00000000000000000000000000010000
    vec($_, 7, 4) = 8   == 2147483648 00000000000000000000000000000001
    vec($_, 0, 8) = 1   ==          1 10000000000000000000000000000000
    vec($_, 1, 8) = 1   ==        256 00000000100000000000000000000000
    vec($_, 2, 8) = 1   ==      65536 00000000000000001000000000000000
    vec($_, 3, 8) = 1   ==   16777216 00000000000000000000000010000000
    vec($_, 0, 8) = 2   ==          2 01000000000000000000000000000000
    vec($_, 1, 8) = 2   ==        512 00000000010000000000000000000000
    vec($_, 2, 8) = 2   ==     131072 00000000000000000100000000000000
    vec($_, 3, 8) = 2   ==   33554432 00000000000000000000000001000000
    vec($_, 0, 8) = 4   ==          4 00100000000000000000000000000000
    vec($_, 1, 8) = 4   ==       1024 00000000001000000000000000000000
    vec($_, 2, 8) = 4   ==     262144 00000000000000000010000000000000
    vec($_, 3, 8) = 4   ==   67108864 00000000000000000000000000100000
    vec($_, 0, 8) = 8   ==          8 00010000000000000000000000000000
    vec($_, 1, 8) = 8   ==       2048 00000000000100000000000000000000
    vec($_, 2, 8) = 8   ==     524288 00000000000000000001000000000000
    vec($_, 3, 8) = 8   ==  134217728 00000000000000000000000000010000
    vec($_, 0, 8) = 16  ==         16 00001000000000000000000000000000
    vec($_, 1, 8) = 16  ==       4096 00000000000010000000000000000000
    vec($_, 2, 8) = 16  ==    1048576 00000000000000000000100000000000
    vec($_, 3, 8) = 16  ==  268435456 00000000000000000000000000001000
    vec($_, 0, 8) = 32  ==         32 00000100000000000000000000000000
    vec($_, 1, 8) = 32  ==       8192 00000000000001000000000000000000
    vec($_, 2, 8) = 32  ==    2097152 00000000000000000000010000000000
    vec($_, 3, 8) = 32  ==  536870912 00000000000000000000000000000100
    vec($_, 0, 8) = 64  ==         64 00000010000000000000000000000000
    vec($_, 1, 8) = 64  ==      16384 00000000000000100000000000000000
    vec($_, 2, 8) = 64  ==    4194304 00000000000000000000001000000000
    vec($_, 3, 8) = 64  == 1073741824 00000000000000000000000000000010
    vec($_, 0, 8) = 128 ==        128 00000001000000000000000000000000
    vec($_, 1, 8) = 128 ==      32768 00000000000000010000000000000000
    vec($_, 2, 8) = 128 ==    8388608 00000000000000000000000100000000
    vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
wait

Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in $?. Note that a return value of -1 could mean that child processes are being automatically reaped, as described in the perlipc manpage.

waitpid PID,FLAGS

Waits for a particular child process to terminate and returns the pid of the deceased process, or -1 if there is no such child process. On some systems, a value of 0 indicates that there are processes still running. The status is returned in $?. If you say

    use POSIX ":sys_wait_h";
    #...
    do {
        $kid = waitpid(-1, WNOHANG);
    } until $kid > 0;

then you can do a non-blocking wait for all pending zombie processes. Non-blocking wait is available on machines supporting either the waitpid(2) or wait4(2) system calls. However, waiting for a particular pid with FLAGS of 0 is implemented everywhere. (Perl emulates the system call by remembering the status values of processes that have exited but have not been harvested by the Perl script yet.)

Note that on some systems, a return value of -1 could mean that child processes are being automatically reaped. See the perlipc manpage for details, and for other examples.

wantarray

Returns true if the context of the currently executing subroutine or eval is looking for a list value. Returns false if the context is looking for a scalar. Returns the undefined value if the context is looking for no value (void context).

    return unless defined wantarray;    # don't bother doing more
    my @a = complex_calculation();
    return wantarray ? @a : "@a";

wantarray()'s result is unspecified in the top level of a file, in a BEGIN, CHECK, INIT or END block, or in a DESTROY method.

This function should have been named wantlist() instead.

warn LIST

Produces a message on STDERR just like die, but doesn't exit or throw an exception.

If LIST is empty and $@ already contains a value (typically from a previous eval) that value is used after appending "\t...caught" to $@. This is useful for staying almost, but not entirely similar to die.

If $@ is empty then the string "Warning: Something's wrong" is used.

No message is printed if there is a $SIG{__WARN__} handler installed. It is the handler's responsibility to deal with the message as it sees fit (like, for instance, converting it into a die). Most handlers must therefore make arrangements to actually display the warnings that they are not prepared to deal with, by calling warn again in the handler. Note that this is quite safe and will not produce an endless loop, since __WARN__ hooks are not called from inside one.

You will find this behavior is slightly different from that of $SIG{__DIE__} handlers (which don't suppress the error text, but can instead call die again to change it).

Using a __WARN__ handler provides a powerful way to silence all warnings (even the so-called mandatory ones). An example:

    # wipe out *all* compile-time warnings
    BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
    my $foo = 10;
    my $foo = 20;          # no warning about duplicate my $foo,
                           # but hey, you asked for it!
    # no compile-time or run-time warnings before here
    $DOWARN = 1;

    # run-time warnings enabled after here
    warn "\$foo is alive and $foo!";     # does show up

See the perlvar manpage for details on setting %SIG entries, and for more examples. See the Carp module for other kinds of warnings using its carp() and cluck() functions.

write FILEHANDLE
write EXPR
write

Writes a formatted record (possibly multi-line) to the specified FILEHANDLE, using the format associated with that file. By default the format for a file is the one having the same name as the filehandle, but the format for the current output channel (see the select function) may be set explicitly by assigning the name of the format to the $~ variable.

Top of form processing is handled automatically: if there is insufficient room on the current page for the formatted record, the page is advanced by writing a form feed, a special top-of-page format is used to format the new page header, and then the record is written. By default the top-of-page format is the name of the filehandle with "_TOP" appended, but it may be dynamically set to the format of your choice by assigning the name to the $^ variable while the filehandle is selected. The number of lines remaining on the current page is in variable $-, which can be set to 0 to force a new page.

If FILEHANDLE is unspecified, output goes to the current default output channel, which starts out as STDOUT but may be changed by the select operator. If the FILEHANDLE is an EXPR, then the expression is evaluated and the resulting string is used to look up the name of the FILEHANDLE at run time. For more on formats, see the perlform manpage.

Note that write is not the opposite of read. Unfortunately.

y///

The transliteration operator. Same as tr///. See the perlop manpage.


perlop - Perl operators and precedence

    • Operator Precedence and Associativity
    • Terms and List Operators (Leftward)
    • The Arrow Operator
    • Auto-increment and Auto-decrement
    • Exponentiation
    • Symbolic Unary Operators
    • Binding Operators
    • Multiplicative Operators
    • Additive Operators
    • Shift Operators
    • Named Unary Operators
    • Relational Operators
    • Equality Operators
    • Bitwise And
    • Bitwise Or and Exclusive Or
    • C-style Logical And
    • C-style Logical Or
    • Range Operators
    • Conditional Operator
    • Assignment Operators
    • Comma Operator
    • List Operators (Rightward)
    • Logical Not
    • Logical And
    • Logical or and Exclusive Or
    • C Operators Missing From Perl
    • Quote and Quote-like Operators
    • Regexp Quote-Like Operators
    • Gory details of parsing quoted constructs
    • I/O Operators
    • Constant Folding
    • No-ops
    • Bitwise String Operators
    • Integer Arithmetic
    • Floating-point Arithmetic
    • Bigger Numbers

NAME

perlop - Perl operators and precedence

DESCRIPTION

Operator Precedence and Associativity

Operator precedence and associativity work in Perl more or less like they do in mathematics.

Operator precedence means some operators are evaluated before others. For example, in 2 + 4 * 5, the multiplication has higher precedence so 4 * 5 is evaluated first yielding 2 + 20 == 22 and not 6 * 5 == 30.

Operator associativity defines what happens if a sequence of the same operators is used one after another: whether the evaluator will evaluate the left operations first or the right. For example, in 8 - 4 - 2, subtraction is left associative so Perl evaluates the expression left to right. 8 - 4 is evaluated first making the expression 4 - 2 == 2 and not 8 - 2 == 6.

Perl operators have the following associativity and precedence, listed from highest precedence to lowest. Operators borrowed from C keep the same precedence relationship with each other, even where C's precedence is slightly screwy. (This makes learning Perl easier for C folks.) With very few exceptions, these all operate on scalar values only, not array values.

    left        terms and list operators (leftward)
    left        ->
    nonassoc    ++ --
    right       **
    right       ! ~ \ and unary + and -
    left        =~ !~
    left        * / % x
    left        + - .
    left        << >>
    nonassoc    named unary operators
    nonassoc    < > <= >= lt gt le ge
    nonassoc    == != <=> eq ne cmp
    left        &
    left        | ^
    left        &&
    left        ||
    nonassoc    ..  ...
    right       ?:
    right       = += -= *= etc.
    left        , =>
    nonassoc    list operators (rightward)
    right       not
    left        and
    left        or xor

In the following sections, these operators are covered in precedence order.

Many operators can be overloaded for objects. See the overload manpage.

Terms and List Operators (Leftward)

A TERM has the highest precedence in Perl. They include variables, quote and quote-like operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary operators behaving as functions because you put parentheses around the arguments. These are all documented in the perlfunc manpage.

If any list operator (print(), etc.) or any unary operator (chdir(), etc.) is followed by a left parenthesis as the next token, the operator and arguments within parentheses are taken to be of highest precedence, just like a normal function call.

In the absence of parentheses, the precedence of list operators such as print, sort, or chmod is either very high or very low depending on whether you are looking at the left side or the right side of the operator. For example, in

    @ary = (1, 3, sort 4, 2);
    print @ary;         # prints 1324

the commas on the right of the sort are evaluated before the sort, but the commas on the left are evaluated after. In other words, list operators tend to gobble up all arguments that follow, and then act like a simple TERM with regard to the preceding expression. Be careful with parentheses:

    # These evaluate exit before doing the print:
    print($foo, exit);  # Obviously not what you want.
    print $foo, exit;   # Nor is this.

    # These do the print before evaluating exit:
    (print $foo), exit; # This is what you want.
    print($foo), exit;  # Or this.
    print ($foo), exit; # Or even this.

Also note that

    print ($foo & 255) + 1, "\n";

probably doesn't do what you expect at first glance. The parentheses enclose the argument list for print which is evaluated (printing the result of $foo & 255). Then one is added to the return value of print (usually 1). The result is something like this:

    1 + 1, "\n";    # Obviously not what you meant.

To do what you meant properly, you must write:

    print(($foo & 255) + 1, "\n");

See Named Unary Operators for more discussion of this.

Also parsed as terms are the do {} and eval {} constructs, as well as subroutine and method calls, and the anonymous constructors [] and {}.

See also Quote and Quote-like Operators toward the end of this section, as well as I/O Operators.

The Arrow Operator >>

"->" is an infix dereference operator, just as it is in C and C++. If the right side is either a [...], {...}, or a (...) subscript, then the left side must be either a hard or symbolic reference to an array, a hash, or a subroutine respectively. (Or technically speaking, a location capable of holding a hard reference, if it's an array or hash reference being used for assignment.) See the perlreftut manpage and the perlref manpage.

Otherwise, the right side is a method name or a simple scalar variable containing either the method name or a subroutine reference, and the left side must be either an object (a blessed reference) or a class name (that is, a package name). See the perlobj manpage.

Auto-increment and Auto-decrement

"++" and "--" work as in C. That is, if placed before a variable, they increment or decrement the variable by one before returning the value, and if placed after, increment or decrement after returning the value.

    $i = 0;  $j = 0;
    print $i++;  # prints 0
    print ++$j;  # prints 1

Note that just as in C, Perl doesn't define when the variable is incremented or decremented. You just know it will be done sometime before or after the value is returned. This also means that modifying a variable twice in the same statement will lead to undefined behaviour. Avoid statements like:

    $i = $i ++;
    print ++ $i + $i ++;

Perl will not guarantee what the result of the above statements is.

The auto-increment operator has a little extra builtin magic to it. If you increment a variable that is numeric, or that has ever been used in a numeric context, you get a normal increment. If, however, the variable has been used in only string contexts since it was set, and has a value that is not the empty string and matches the pattern /^[a-zA-Z]*[0-9]*\z/, the increment is done as a string, preserving each character within its range, with carry:

    print ++($foo = '99');      # prints '100'
    print ++($foo = 'a0');      # prints 'a1'
    print ++($foo = 'Az');      # prints 'Ba'
    print ++($foo = 'zz');      # prints 'aaa'

undef is always treated as numeric, and in particular is changed to 0 before incrementing (so that a post-increment of an undef value will return 0 rather than undef).

The auto-decrement operator is not magical.

Exponentiation

Binary "**" is the exponentiation operator. It binds even more tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is implemented using C's pow(3) function, which actually works on doubles internally.)

Symbolic Unary Operators

Unary "!" performs logical negation, i.e., "not". See also not for a lower precedence version of this.

Unary "-" performs arithmetic negation if the operand is numeric. If the operand is an identifier, a string consisting of a minus sign concatenated with the identifier is returned. Otherwise, if the string starts with a plus or minus, a string starting with the opposite sign is returned. One effect of these rules is that -bareword is equivalent to the string "-bareword". If, however, the string begins with a non-alphabetic character (exluding "+" or "-"), Perl will attempt to convert the string to a numeric and the arithmetic negation is performed. If the string cannot be cleanly converted to a numeric, Perl will give the warning Argument "the string" isn't numeric in negation (-) at ....

Unary "~" performs bitwise negation, i.e., 1's complement. For example, 0666 & ~027 is 0640. (See also Integer Arithmetic and Bitwise String Operators.) Note that the width of the result is platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64 bits wide on a 64-bit platform, so if you are expecting a certain bit width, remember to use the & operator to mask off the excess bits.

Unary "+" has no effect whatsoever, even on strings. It is useful syntactically for separating a function name from a parenthesized expression that would otherwise be interpreted as the complete list of function arguments. (See examples above under Terms and List Operators (Leftward).)

Unary "\" creates a reference to whatever follows it. See the perlreftut manpage and the perlref manpage. Do not confuse this behavior with the behavior of backslash within a string, although both forms do convey the notion of protecting the next thing from interpolation.

Binding Operators

Binary "=~" binds a scalar expression to a pattern match. Certain operations search or modify the string $_ by default. This operator makes that kind of operation work on some other string. The right argument is a search pattern, substitution, or transliteration. The left argument is what is supposed to be searched, substituted, or transliterated instead of the default $_. When used in scalar context, the return value generally indicates the success of the operation. Behavior in list context depends on the particular operator. See Regexp Quote-Like Operators for details and the perlretut manpage for examples using these operators.

If the right argument is an expression rather than a search pattern, substitution, or transliteration, it is interpreted as a search pattern at run time.

Binary "!~" is just like "=~" except the return value is negated in the logical sense.

Multiplicative Operators

Binary "*" multiplies two numbers.

Binary "/" divides two numbers.

Binary "%" computes the modulus of two numbers. Given integer operands $a and $b: If $b is positive, then $a % $b is $a minus the largest multiple of $b that is not greater than $a. If $b is negative, then $a % $b is $a minus the smallest multiple of $b that is not less than $a (i.e. the result will be less than or equal to zero). Note that when use integer is in scope, "%" gives you direct access to the modulus operator as implemented by your C compiler. This operator is not as well defined for negative operands, but it will execute faster.

Binary "x" is the repetition operator. In scalar context or if the left operand is not enclosed in parentheses, it returns a string consisting of the left operand repeated the number of times specified by the right operand. In list context, if the left operand is enclosed in parentheses or is a list formed by qw/STRING/, it repeats the list. If the right operand is zero or negative, it returns an empty string or an empty list, depending on the context.

    print '-' x 80;             # print row of dashes

    print "\t" x ($tab/8), ' ' x ($tab%8);      # tab over

    @ones = (1) x 80;           # a list of 80 1's
    @ones = (5) x @ones;        # set all elements to 5

Additive Operators

Binary "+" returns the sum of two numbers.

Binary "-" returns the difference of two numbers.

Binary "." concatenates two strings.

Shift Operators >> > >>>

Binary "<<" returns the value of its left argument shifted left by the number of bits specified by the right argument. Arguments should be integers. (See also Integer Arithmetic.)

Binary ">>" returns the value of its left argument shifted right by the number of bits specified by the right argument. Arguments should be integers. (See also Integer Arithmetic.)

Note that both "<<" and ">>" in Perl are implemented directly using "<<" and ">>" in C. If use integer (see Integer Arithmetic) is in force then signed C integers are used, else unsigned C integers are used. Either way, the implementation isn't going to generate results larger than the size of the integer type Perl was built with (32 bits or 64 bits).

The result of overflowing the range of the integers is undefined because it is undefined also in C. In other words, using 32-bit integers, 1 << 32 is undefined. Shifting by a negative number of bits is also undefined.

Named Unary Operators

The various named unary operators are treated as functions with one argument, with optional parentheses.

If any list operator (print(), etc.) or any unary operator (chdir(), etc.) is followed by a left parenthesis as the next token, the operator and arguments within parentheses are taken to be of highest precedence, just like a normal function call. For example, because named unary operators are higher precedence than ||:

    chdir $foo    || die;       # (chdir $foo) || die
    chdir($foo)   || die;       # (chdir $foo) || die
    chdir ($foo)  || die;       # (chdir $foo) || die
    chdir +($foo) || die;       # (chdir $foo) || die

but, because * is higher precedence than named operators:

    chdir $foo * 20;    # chdir ($foo * 20)
    chdir($foo) * 20;   # (chdir $foo) * 20
    chdir ($foo) * 20;  # (chdir $foo) * 20
    chdir +($foo) * 20; # chdir ($foo * 20)

    rand 10 * 20;       # rand (10 * 20)
    rand(10) * 20;      # (rand 10) * 20
    rand (10) * 20;     # (rand 10) * 20
    rand +(10) * 20;    # rand (10 * 20)

Regarding precedence, the filetest operators, like -f, -M, etc. are treated like named unary operators, but they don't follow this functional parenthesis rule. That means, for example, that -f($file).".bak" is equivalent to -f "$file.bak".

See also Terms and List Operators (Leftward).

Relational Operators

Binary "<" returns true if the left argument is numerically less than the right argument. >

Binary ">" returns true if the left argument is numerically greater than the right argument. >>

Binary "<=" returns true if the left argument is numerically less than or equal to the right argument. >

Binary ">=" returns true if the left argument is numerically greater than or equal to the right argument. = >>

Binary "lt" returns true if the left argument is stringwise less than the right argument. >

Binary "gt" returns true if the left argument is stringwise greater than the right argument. >

Binary "le" returns true if the left argument is stringwise less than or equal to the right argument. >

Binary "ge" returns true if the left argument is stringwise greater than or equal to the right argument. >

Equality Operators

Binary "==" returns true if the left argument is numerically equal to the right argument.

Binary "!=" returns true if the left argument is numerically not equal to the right argument.

Binary "<=>" returns -1, 0, or 1 depending on whether the left argument is numerically less than, equal to, or greater than the right argument. If your platform supports NaNs (not-a-numbers) as numeric values, using them with "<=>" returns undef. NaN is not "<", "==", ">", "<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN returns true, as does NaN != anything else. If your platform doesn't support NaNs then NaN is just a string with numeric value 0. >>

    perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
    perl -le '$a = "NaN"; print "NaN support here" if $a != $a'

Binary "eq" returns true if the left argument is stringwise equal to the right argument.

Binary "ne" returns true if the left argument is stringwise not equal to the right argument.

Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise less than, equal to, or greater than the right argument.

"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified by the current locale if use locale is in effect. See the perllocale manpage.

Bitwise And

Binary "&" returns its operands ANDed together bit by bit. (See also Integer Arithmetic and Bitwise String Operators.)

Note that "&" has lower priority than relational operators, so for example the brackets are essential in a test like

        print "Even\n" if ($x & 1) == 0;

Bitwise Or and Exclusive Or

Binary "|" returns its operands ORed together bit by bit. (See also Integer Arithmetic and Bitwise String Operators.)

Binary "^" returns its operands XORed together bit by bit. (See also Integer Arithmetic and Bitwise String Operators.)

Note that "|" and "^" have lower priority than relational operators, so for example the brackets are essential in a test like

        print "false\n" if (8 | 2) != 10;

C-style Logical And

Binary "&&" performs a short-circuit logical AND operation. That is, if the left operand is false, the right operand is not even evaluated. Scalar or list context propagates down to the right operand if it is evaluated.

C-style Logical Or

Binary "||" performs a short-circuit logical OR operation. That is, if the left operand is true, the right operand is not even evaluated. Scalar or list context propagates down to the right operand if it is evaluated.

The || and && operators return the last value evaluated (unlike C's || and &&, which return 0 or 1). Thus, a reasonably portable way to find out the home directory might be:

    $home = $ENV{'HOME'} || $ENV{'LOGDIR'} ||
        (getpwuid($<))[7] || die "You're homeless!\n";

In particular, this means that you shouldn't use this for selecting between two aggregates for assignment:

    @a = @b || @c;              # this is wrong
    @a = scalar(@b) || @c;      # really meant this
    @a = @b ? @b : @c;          # this works fine, though

As more readable alternatives to && and || when used for control flow, Perl provides and and or operators (see below). The short-circuit behavior is identical. The precedence of "and" and "or" is much lower, however, so that you can safely use them after a list operator without the need for parentheses:

    unlink "alpha", "beta", "gamma"
            or gripe(), next LINE;

With the C-style operators that would have been written like this:

    unlink("alpha", "beta", "gamma")
            || (gripe(), next LINE);

Using "or" for assignment is unlikely to do what you want; see below.

Range Operators

Binary ".." is the range operator, which is really two different operators depending on the context. In list context, it returns a list of values counting (up by ones) from the left value to the right value. If the left value is greater than the right value then it returns the empty list. The range operator is useful for writing foreach (1..10) loops and for doing slice operations on arrays. In the current implementation, no temporary array is created when the range operator is used as the expression in foreach loops, but older versions of Perl might burn a lot of memory when you write something like this:

    for (1 .. 1_000_000) {
        # code
    }

The range operator also works on strings, using the magical auto-increment, see below.

In scalar context, ".." returns a boolean value. The operator is bistable, like a flip-flop, and emulates the line-range (comma) operator of sed, awk, and various editors. Each ".." operator maintains its own boolean state. It is false as long as its left operand is false. Once the left operand is true, the range operator stays true until the right operand is true, AFTER which the range operator becomes false again. It doesn't become false till the next time the range operator is evaluated. It can test the right operand and become false on the same evaluation it became true (as in awk), but it still returns true once. If you don't want it to test the right operand till the next evaluation, as in sed, just use three dots ("...") instead of two. In all other regards, "..." behaves just like ".." does.

The right operand is not evaluated while the operator is in the "false" state, and the left operand is not evaluated while the operator is in the "true" state. The precedence is a little lower than || and &&. The value returned is either the empty string for false, or a sequence number (beginning with 1) for true. The sequence number is reset for each range encountered. The final sequence number in a range has the string "E0" appended to it, which doesn't affect its numeric value, but gives you something to search for if you want to exclude the endpoint. You can exclude the beginning point by waiting for the sequence number to be greater than 1.

If either operand of scalar ".." is a constant expression, that operand is considered true if it is equal (==) to the current input line number (the $. variable).

To be pedantic, the comparison is actually int(EXPR) == int(EXPR), but that is only an issue if you use a floating point expression; when implicitly using $. as described in the previous paragraph, the comparison is int(EXPR) == int($.) which is only an issue when $. is set to a floating point value and you are not reading from a file. Furthermore, "span" .. "spat" or 2.18 .. 3.14 will not do what you want in scalar context because each of the operands are evaluated using their integer representation.

Examples:

As a scalar operator:

    if (101 .. 200) { print; } # print 2nd hundred lines, short for
                               #   if ($. == 101 .. $. == 200) ...

    next LINE if (1 .. /^$/);  # skip header lines, short for
                               #   ... if ($. == 1 .. /^$/);
                               # (typically in a loop labeled LINE)

    s/^/> / if (/^$/ .. eof());  # quote body

    # parse mail messages
    while (<>) {
        $in_header =   1  .. /^$/;
        $in_body   = /^$/ .. eof;
        if ($in_header) {
            # ...
        } else { # in body
            # ...
        }
    } continue {
        close ARGV if eof;             # reset $. each file
    }

Here's a simple example to illustrate the difference between the two range operators:

    @lines = ("   - Foo",
              "01 - Bar",
              "1  - Baz",
              "   - Quux");

    foreach (@lines) {
        if (/0/ .. /1/) {
            print "$_\n";
        }
    }

This program will print only the line containing "Bar". If the range operator is changed to ..., it will also print the "Baz" line.

And now some examples as a list operator:

    for (101 .. 200) { print; } # print $_ 100 times
    @foo = @foo[0 .. $#foo];    # an expensive no-op
    @foo = @foo[$#foo-4 .. $#foo];      # slice last 5 items

The range operator (in list context) makes use of the magical auto-increment algorithm if the operands are strings. You can say

    @alphabet = ('A' .. 'Z');

to get all normal letters of the English alphabet, or

    $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];

to get a hexadecimal digit, or

    @z2 = ('01' .. '31');  print $z2[$mday];

to get dates with leading zeros. If the final value specified is not in the sequence that the magical increment would produce, the sequence goes until the next value would be longer than the final value specified.

Because each operand is evaluated in integer form, 2.18 .. 3.14 will return two elements in list context.

    @list = (2.18 .. 3.14); # same as @list = (2 .. 3);

Conditional Operator

Ternary "?:" is the conditional operator, just as in C. It works much like an if-then-else. If the argument before the ? is true, the argument before the : is returned, otherwise the argument after the : is returned. For example:

    printf "I have %d dog%s.\n", $n,
            ($n == 1) ? '' : "s";

Scalar or list context propagates downward into the 2nd or 3rd argument, whichever is selected.

    $a = $ok ? $b : $c;  # get a scalar
    @a = $ok ? @b : @c;  # get an array
    $a = $ok ? @b : @c;  # oops, that's just a count!

The operator may be assigned to if both the 2nd and 3rd arguments are legal lvalues (meaning that you can assign to them):

    ($a_or_b ? $a : $b) = $c;

Because this operator produces an assignable result, using assignments without parentheses will get you in trouble. For example, this:

    $a % 2 ? $a += 10 : $a += 2

Really means this:

    (($a % 2) ? ($a += 10) : $a) += 2

Rather than this:

    ($a % 2) ? ($a += 10) : ($a += 2)

That should probably be written more simply as:

    $a += ($a % 2) ? 10 : 2;

Assignment Operators >> >= >>>

"=" is the ordinary assignment operator.

Assignment operators work as in C. That is,

    $a += 2;

is equivalent to

    $a = $a + 2;

although without duplicating any side effects that dereferencing the lvalue might trigger, such as from tie(). Other assignment operators work similarly. The following are recognized:

    **=    +=    *=    &=    <<=    &&=
           -=    /=    |=    >>=    ||=
           .=    %=    ^=
                 x=

Although these are grouped by family, they all have the precedence of assignment.

Unlike in C, the scalar assignment operator produces a valid lvalue. Modifying an assignment is equivalent to doing the assignment and then modifying the variable that was assigned to. This is useful for modifying a copy of something, like this:

    ($tmp = $global) =~ tr [A-Z] [a-z];

Likewise,

    ($a += 2) *= 3;

is equivalent to

    $a += 2;
    $a *= 3;

Similarly, a list assignment in list context produces the list of lvalues assigned to, and a list assignment in scalar context returns the number of elements produced by the expression on the right hand side of the assignment.

Comma Operator

Binary "," is the comma operator. In scalar context it evaluates its left argument, throws that value away, then evaluates its right argument and returns that value. This is just like C's comma operator.

In list context, it's just the list argument separator, and inserts both its arguments into the list.

The => operator is a synonym for the comma, but forces any word (consisting entirely of word characters) to its left to be interpreted as a string (as of 5.001). This includes words that might otherwise be considered a constant or function call.

    use constant FOO => "something";

    my %h = ( FOO => 23 );

is equivalent to:

    my %h = ("FOO", 23);

It is NOT:

    my %h = ("something", 23);

If the argument on the left is not a word, it is first interpreted as an expression, and then the string value of that is used.

The => operator is helpful in documenting the correspondence between keys and values in hashes, and other paired elements in lists.

        %hash = ( $key => $value );
        login( $username => $password );

List Operators (Rightward)

On the right side of a list operator, it has very low precedence, such that it controls all comma-separated expressions found there. The only operators with lower precedence are the logical operators "and", "or", and "not", which may be used to evaluate calls to list operators without the need for extra parentheses:

    open HANDLE, "filename"
        or die "Can't open: $!\n";

See also discussion of list operators in Terms and List Operators (Leftward).

Logical Not

Unary "not" returns the logical negation of the expression to its right. It's the equivalent of "!" except for the very low precedence.

Logical And

Binary "and" returns the logical conjunction of the two surrounding expressions. It's equivalent to && except for the very low precedence. This means that it short-circuits: i.e., the right expression is evaluated only if the left expression is true.

Logical or and Exclusive Or

Binary "or" returns the logical disjunction of the two surrounding expressions. It's equivalent to || except for the very low precedence. This makes it useful for control flow

    print FH $data              or die "Can't write to FH: $!";

This means that it short-circuits: i.e., the right expression is evaluated only if the left expression is false. Due to its precedence, you should probably avoid using this for assignment, only for control flow.

    $a = $b or $c;              # bug: this is wrong
    ($a = $b) or $c;            # really means this
    $a = $b || $c;              # better written this way

However, when it's a list-context assignment and you're trying to use "||" for control flow, you probably need "or" so that the assignment takes higher precedence.

    @info = stat($file) || die;     # oops, scalar sense of stat!
    @info = stat($file) or die;     # better, now @info gets its due

Then again, you could always use parentheses.

Binary "xor" returns the exclusive-OR of the two surrounding expressions. It cannot short circuit, of course.

C Operators Missing From Perl

Here is what C has that Perl doesn't:

unary &

Address-of operator. (But see the "\" operator for taking a reference.)

unary *

Dereference-address operator. (Perl's prefix dereferencing operators are typed: $, @, %, and &.)

(TYPE)

Type-casting operator.

Quote and Quote-like Operators >>

While we usually think of quotes as literal values, in Perl they function as operators, providing various kinds of interpolating and pattern matching capabilities. Perl provides customary quote characters for these behaviors, but also provides a way for you to choose your quote character for any of them. In the following table, a {} represents any pair of delimiters you choose.

    Customary  Generic        Meaning        Interpolates
        ''       q{}          Literal             no
        ""      qq{}          Literal             yes
        ``      qx{}          Command             yes*
                qw{}         Word list            no
        //       m{}       Pattern match          yes*
                qr{}          Pattern             yes*
                 s{}{}      Substitution          yes*
                tr{}{}    Transliteration         no (but see below)
        <<EOF                 here-doc            yes*
        * unless the delimiter is ''.

Non-bracketing delimiters use the same character fore and aft, but the four sorts of brackets (round, angle, square, curly) will all nest, which means that

        q{foo{bar}baz}

is the same as

        'foo{bar}baz'

Note, however, that this does not always work for quoting Perl code:

        $s = q{ if($a eq "}") ... }; # WRONG

is a syntax error. The Text::Balanced module (from CPAN, and starting from Perl 5.8 part of the standard distribution) is able to do this properly.

There can be whitespace between the operator and the quoting characters, except when # is being used as the quoting character. q#foo# is parsed as the string foo, while q #foo# is the operator q followed by a comment. Its argument will be taken from the next line. This allows you to write:

    s {foo}  # Replace foo
      {bar}  # with bar.

The following escape sequences are available in constructs that interpolate and in transliterations.

    \t          tab             (HT, TAB)
    \n          newline         (NL)
    \r          return          (CR)
    \f          form feed       (FF)
    \b          backspace       (BS)
    \a          alarm (bell)    (BEL)
    \e          escape          (ESC)
    \033        octal char      (ESC)
    \x1b        hex char        (ESC)
    \x{263a}    wide hex char   (SMILEY)
    \c[         control char    (ESC)
    \N{name}    named Unicode character

NOTE: Unlike C and other languages, Perl has no \v escape sequence for the vertical tab (VT - ASCII 11).

The following escape sequences are available in constructs that interpolate but not in transliterations.

    \l          lowercase next char
    \u          uppercase next char
    \L          lowercase till \E
    \U          uppercase till \E
    \E          end case modification
    \Q          quote non-word characters till \E

If use locale is in effect, the case map used by \l, \L, \u and \U is taken from the current locale. See the perllocale manpage. If Unicode (for example, \N{} or wide hex characters of 0x100 or beyond) is being used, the case map used by \l, \L, \u and \U is as defined by Unicode. For documentation of \N{name}, see the charnames manpage.

All systems use the virtual "\n" to represent a line terminator, called a "newline". There is no such thing as an unvarying, physical newline character. It is only an illusion that the operating system, device drivers, C libraries, and Perl all conspire to preserve. Not all systems read "\r" as ASCII CR and "\n" as ASCII LF. For example, on a Mac, these are reversed, and on systems without line terminator, printing "\n" may emit no actual data. In general, use "\n" when you mean a "newline" for your system, but use the literal ASCII when you need an exact character. For example, most networking protocols expect and prefer a CR+LF ("\015\012" or "\cM\cJ") for line terminators, and although they often accept just "\012", they seldom tolerate just "\015". If you get in the habit of using "\n" for networking, you may be burned some day.

For constructs that do interpolate, variables beginning with "$" or "@" are interpolated. Subscripted variables such as $a[3] or $href->{key}[0] are also interpolated, as are array and hash slices. But method calls such as $obj->meth are not.

Interpolating an array or slice interpolates the elements in order, separated by the value of $", so is equivalent to interpolating join $", @array. "Punctuation" arrays such as @+ are only interpolated if the name is enclosed in braces @{+}.

You cannot include a literal $ or @ within a \Q sequence. An unescaped $ or @ interpolates the corresponding variable, while escaping will cause the literal string \$ to be inserted. You'll need to write something like m/\Quser\E\@\Qhost/.

Patterns are subject to an additional level of interpretation as a regular expression. This is done as a second pass, after variables are interpolated, so that regular expressions may be incorporated into the pattern from the variables. If this is not what you want, use \Q to interpolate a variable literally.

Apart from the behavior described above, Perl does not expand multiple levels of interpolation. In particular, contrary to the expectations of shell programmers, back-quotes do NOT interpolate within double quotes, nor do single quotes impede evaluation of variables when used within double quotes.

Regexp Quote-Like Operators

Here are the quote-like operators that apply to pattern matching and related activities.

?PATTERN?

This is just like the /pattern/ search, except that it matches only once between calls to the reset() operator. This is a useful optimization when you want to see only the first occurrence of something in each file of a set of files, for instance. Only ?? patterns local to the current package are reset.

    while (<>) {
        if (?^$?) {
                            # blank line between header and body
        }
    } continue {
        reset if eof;       # clear ?? status for next file
    }

This usage is vaguely deprecated, which means it just might possibly be removed in some distant future version of Perl, perhaps somewhere around the year 2168.

m/PATTERN/cgimosx
/PATTERN/cgimosx

Searches a string for a pattern match, and in scalar context returns true if it succeeds, false if it fails. If no string is specified via the =~ or !~ operator, the $_ string is searched. (The string specified with =~ need not be an lvalue--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.) See also the perlre manpage. See the perllocale manpage for discussion of additional considerations that apply when use locale is in effect.

Options are:

    c   Do not reset search position on a failed match when /g is in effect.
    g   Match globally, i.e., find all occurrences.
    i   Do case-insensitive pattern matching.
    m   Treat string as multiple lines.
    o   Compile pattern only once.
    s   Treat string as single line.
    x   Use extended regular expressions.

If "/" is the delimiter then the initial m is optional. With the m you can use any pair of non-alphanumeric, non-whitespace characters as delimiters. This is particularly useful for matching path names that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is the delimiter, then the match-only-once rule of ?PATTERN? applies. If "'" is the delimiter, no interpolation is performed on the PATTERN.

PATTERN may contain variables, which will be interpolated (and the pattern recompiled) every time the pattern search is evaluated, except for when the delimiter is a single quote. (Note that $(, $), and $| are not interpolated because they look like end-of-string tests.) If you want such a pattern to be compiled only once, add a /o after the trailing delimiter. This avoids expensive run-time recompilations, and is useful when the value you are interpolating won't change over the life of the script. However, mentioning /o constitutes a promise that you won't change the variables in the pattern. If you change them, Perl won't even notice. See also qr/STRING/imosx.

If the PATTERN evaluates to the empty string, the last successfully matched regular expression is used instead. In this case, only the g and c flags on the empty pattern is honoured - the other flags are taken from the original pattern. If no match has previously succeeded, this will (silently) act instead as a genuine empty pattern (which will always match).

If the /g option is not used, m// in list context returns a list consisting of the subexpressions matched by the parentheses in the pattern, i.e., ($1, $2, $3...). (Note that here $1 etc. are also set, and that this differs from Perl 4's behavior.) When there are no parentheses in the pattern, the return value is the list (1) for success. With or without parentheses, an empty list is returned upon failure.

Examples:

    open(TTY, '/dev/tty');
    <TTY> =~ /^y/i && foo();    # do foo if desired

    if (/Version: *([0-9.]*)/) { $version = $1; }

    next if m#^/usr/spool/uucp#;

    # poor man's grep
    $arg = shift;
    while (<>) {
        print if /$arg/o;       # compile only once
    }

    if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))

This last example splits $foo into the first two words and the remainder of the line, and assigns those three fields to $F1, $F2, and $Etc. The conditional is true if any variables were assigned, i.e., if the pattern matched.

The /g modifier specifies global pattern matching--that is, matching as many times as possible within the string. How it behaves depends on the context. In list context, it returns a list of the substrings matched by any capturing parentheses in the regular expression. If there are no parentheses, it returns a list of all the matched strings, as if there were parentheses around the whole pattern.

In scalar context, each execution of m//g finds the next match, returning true if it matches, and false if there is no further match. The position after the last match can be read or set using the pos() function; see pos in the perlfunc manpage. A failed match normally resets the search position to the beginning of the string, but you can avoid that by adding the /c modifier (e.g. m//gc). Modifying the target string also resets the search position.

You can intermix m//g matches with m/\G.../g, where \G is a zero-width assertion that matches the exact position where the previous m//g, if any, left off. Without the /g modifier, the \G assertion still anchors at pos(), but the match is of course only attempted once. Using \G without /g on a target string that has not previously had a /g match applied to it is the same as using the \A assertion to match the beginning of the string. Note also that, currently, \G is only properly supported when anchored at the very beginning of the pattern.

Examples:

    # list context
    ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);

    # scalar context
    $/ = "";
    while (defined($paragraph = <>)) {
        while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) {
            $sentences++;
        }
    }
    print "$sentences\n";

    # using m//gc with \G
    $_ = "ppooqppqq";
    while ($i++ < 2) {
        print "1: '";
        print $1 while /(o)/gc; print "', pos=", pos, "\n";
        print "2: '";
        print $1 if /\G(q)/gc;  print "', pos=", pos, "\n";
        print "3: '";
        print $1 while /(p)/gc; print "', pos=", pos, "\n";
    }
    print "Final: '$1', pos=",pos,"\n" if /\G(.)/;

The last example should print:

    1: 'oo', pos=4
    2: 'q', pos=5
    3: 'pp', pos=7
    1: '', pos=7
    2: 'q', pos=8
    3: '', pos=8
    Final: 'q', pos=8

Notice that the final match matched q instead of p, which a match without the \G anchor would have done. Also note that the final match did not update pos -- pos is only updated on a /g match. If the final match did indeed match p, it's a good bet that you're running an older (pre-5.6.0) Perl.

A useful idiom for lex-like scanners is /\G.../gc. You can combine several regexps like this to process a string part-by-part, doing different actions depending on which regexp matched. Each regexp tries to match where the previous one leaves off.

 $_ = <<'EOL';
      $url = new URI::URL "http://www/";   die if $url eq "xXx";
 EOL
 LOOP:
    {
      print(" digits"),         redo LOOP if /\G\d+\b[,.;]?\s*/gc;
      print(" lowercase"),      redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc;
      print(" UPPERCASE"),      redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc;
      print(" Capitalized"),    redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc;
      print(" MiXeD"),          redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc;
      print(" alphanumeric"),   redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc;
      print(" line-noise"),     redo LOOP if /\G[^A-Za-z0-9]+/gc;
      print ". That's all!\n";
    }

Here is the output (split into several lines):

 line-noise lowercase line-noise lowercase UPPERCASE line-noise
 UPPERCASE line-noise lowercase line-noise lowercase line-noise
 lowercase lowercase line-noise lowercase lowercase line-noise
 MiXeD line-noise. That's all!
q/STRING/
'STRING'

A single-quoted, literal string. A backslash represents a backslash unless followed by the delimiter or another backslash, in which case the delimiter or backslash is interpolated.

    $foo = q!I said, "You said, 'She said it.'"!;
    $bar = q('This is it.');
    $baz = '\n';                # a two-character string
qq/STRING/
"STRING"

A double-quoted, interpolated string.

    $_ .= qq
     (*** The previous line contains the naughty word "$1".\n)
                if /\b(tcl|java|python)\b/i;      # :-)
    $baz = "\n";                # a one-character string
qr/STRING/imosx

This operator quotes (and possibly compiles) its STRING as a regular expression. STRING is interpolated the same way as PATTERN in m/PATTERN/. If "'" is used as the delimiter, no interpolation is done. Returns a Perl value which may be used instead of the corresponding /STRING/imosx expression.

For example,

    $rex = qr/my.STRING/is;
    s/$rex/foo/;

is equivalent to

    s/my.STRING/foo/is;

The result may be used as a subpattern in a match:

    $re = qr/$pattern/;
    $string =~ /foo${re}bar/;   # can be interpolated in other patterns
    $string =~ $re;             # or used standalone
    $string =~ /$re/;           # or this way

Since Perl may compile the pattern at the moment of execution of qr() operator, using qr() may have speed advantages in some situations, notably if the result of qr() is used standalone:

    sub match {
        my $patterns = shift;
        my @compiled = map qr/$_/i, @$patterns;
        grep {
            my $success = 0;
            foreach my $pat (@compiled) {
                $success = 1, last if /$pat/;
            }
            $success;
        } @_;
    }

Precompilation of the pattern into an internal representation at the moment of qr() avoids a need to recompile the pattern every time a match /$pat/ is attempted. (Perl has many other internal optimizations, but none would be triggered in the above example if we did not use qr() operator.)

Options are:

    i   Do case-insensitive pattern matching.
    m   Treat string as multiple lines.
    o   Compile pattern only once.
    s   Treat string as single line.
    x   Use extended regular expressions.

See the perlre manpage for additional information on valid syntax for STRING, and for a detailed look at the semantics of regular expressions.

qx/STRING/
`STRING`

A string which is (possibly) interpolated and then executed as a system command with /bin/sh or its equivalent. Shell wildcards, pipes, and redirections will be honored. The collected standard output of the command is returned; standard error is unaffected. In scalar context, it comes back as a single (potentially multi-line) string, or undef if the command failed. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR), or an empty list if the command failed.

Because backticks do not affect standard error, use shell file descriptor syntax (assuming the shell supports this) if you care to address this. To capture a command's STDERR and STDOUT together:

    $output = `cmd 2>&1`;

To capture a command's STDOUT but discard its STDERR:

    $output = `cmd 2>/dev/null`;

To capture a command's STDERR but discard its STDOUT (ordering is important here):

    $output = `cmd 2>&1 1>/dev/null`;

To exchange a command's STDOUT and STDERR in order to capture the STDERR but leave its STDOUT to come out the old STDERR:

    $output = `cmd 3>&1 1>&2 2>&3 3>&-`;

To read both a command's STDOUT and its STDERR separately, it's easiest to redirect them separately to files, and then read from those files when the program is done:

    system("program args 1>program.stdout 2>program.stderr");

Using single-quote as a delimiter protects the command from Perl's double-quote interpolation, passing it on to the shell instead:

    $perl_info  = qx(ps $$);            # that's Perl's $$
    $shell_info = qx'ps $$';            # that's the new shell's $$

How that string gets evaluated is entirely subject to the command interpreter on your system. On most platforms, you will have to protect shell metacharacters if you want them treated literally. This is in practice difficult to do, as it's unclear how to escape which characters. See the perlsec manpage for a clean and safe example of a manual fork() and exec() to emulate backticks safely.

On some platforms (notably DOS-like ones), the shell may not be capable of dealing with multiline commands, so putting newlines in the string may not get you what you want. You may be able to evaluate multiple commands in a single line by separating them with the command separator character, if your shell supports that (e.g. ; on many Unix shells; & on the Windows NT cmd shell).

Beginning with v5.6.0, Perl will attempt to flush all files opened for output before starting the child process, but this may not be supported on some platforms (see the perlport manpage). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles.

Beware that some command shells may place restrictions on the length of the command line. You must ensure your strings don't exceed this limit after any necessary interpolations. See the platform-specific release notes for more details about your particular environment.

Using this operator can lead to programs that are difficult to port, because the shell commands called vary between systems, and may in fact not be present at all. As one example, the type command under the POSIX shell is very different from the type command under DOS. That doesn't mean you should go out of your way to avoid backticks when they're the right way to get something done. Perl was made to be a glue language, and one of the things it glues together is commands. Just understand what you're getting yourself into.

See I/O Operators for more discussion.

qw/STRING/

Evaluates to a list of the words extracted out of STRING, using embedded whitespace as the word delimiters. It can be understood as being roughly equivalent to:

    split(' ', q/STRING/);

the differences being that it generates a real list at compile time, and in scalar context it returns the last element in the list. So this expression:

    qw(foo bar baz)

is semantically equivalent to the list:

    'foo', 'bar', 'baz'

Some frequently seen examples:

    use POSIX qw( setlocale localeconv )
    @EXPORT = qw( foo bar baz );

A common mistake is to try to separate the words with comma or to put comments into a multi-line qw-string. For this reason, the use warnings pragma and the -w switch (that is, the $^W variable) produces warnings if the STRING contains the "," or the "#" character.

s/PATTERN/REPLACEMENT/egimosx

Searches a string for a pattern, and if found, replaces that pattern with the replacement text and returns the number of substitutions made. Otherwise it returns false (specifically, the empty string).

If no string is specified via the =~ or !~ operator, the $_ variable is searched and modified. (The string specified with =~ must be scalar variable, an array element, a hash element, or an assignment to one of those, i.e., an lvalue.)

If the delimiter chosen is a single quote, no interpolation is done on either the PATTERN or the REPLACEMENT. Otherwise, if the PATTERN contains a $ that looks like a variable rather than an end-of-string test, the variable will be interpolated into the pattern at run-time. If you want the pattern compiled only once the first time the variable is interpolated, use the /o option. If the pattern evaluates to the empty string, the last successfully executed regular expression is used instead. See the perlre manpage for further explanation on these. See the perllocale manpage for discussion of additional considerations that apply when use locale is in effect.

Options are:

    e   Evaluate the right side as an expression.
    g   Replace globally, i.e., all occurrences.
    i   Do case-insensitive pattern matching.
    m   Treat string as multiple lines.
    o   Compile pattern only once.
    s   Treat string as single line.
    x   Use extended regular expressions.

Any non-alphanumeric, non-whitespace delimiter may replace the slashes. If single quotes are used, no interpretation is done on the replacement string (the /e modifier overrides this, however). Unlike Perl 4, Perl 5 treats backticks as normal delimiters; the replacement text is not evaluated as a command. If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own pair of quotes, which may or may not be bracketing quotes, e.g., s(foo)(bar) or s<foo>/bar/. A /e will cause the replacement portion to be treated as a full-fledged Perl expression and evaluated right then and there. It is, however, syntax checked at compile-time. A second e modifier will cause the replacement portion to be evaled before being run as a Perl expression.

Examples:

    s/\bgreen\b/mauve/g;                # don't change wintergreen

    $path =~ s|/usr/bin|/usr/local/bin|;

    s/Login: $foo/Login: $bar/; # run-time pattern

    ($foo = $bar) =~ s/this/that/;      # copy first, then change

    $count = ($paragraph =~ s/Mister\b/Mr./g);  # get change-count

    $_ = 'abc123xyz';
    s/\d+/$&*2/e;               # yields 'abc246xyz'
    s/\d+/sprintf("%5d",$&)/e;  # yields 'abc  246xyz'
    s/\w/$& x 2/eg;             # yields 'aabbcc  224466xxyyzz'

    s/%(.)/$percent{$1}/g;      # change percent escapes; no /e
    s/%(.)/$percent{$1} || $&/ge;       # expr now, so /e
    s/^=(\w+)/&pod($1)/ge;      # use function call

    # expand variables in $_, but dynamics only, using
    # symbolic dereferencing
    s/\$(\w+)/${$1}/g;

    # Add one to the value of any numbers in the string
    s/(\d+)/1 + $1/eg;

    # This will expand any embedded scalar variable
    # (including lexicals) in $_ : First $1 is interpolated
    # to the variable name, and then evaluated
    s/(\$\w+)/$1/eeg;

    # Delete (most) C comments.
    $program =~ s {
        /\*     # Match the opening delimiter.
        .*?     # Match a minimal number of characters.
        \*/     # Match the closing delimiter.
    } []gsx;

    s/^\s*(.*?)\s*$/$1/;        # trim whitespace in $_, expensively

    for ($variable) {           # trim whitespace in $variable, cheap
        s/^\s+//;
        s/\s+$//;
    }

    s/([^ ]*) *([^ ]*)/$2 $1/;  # reverse 1st two fields

Note the use of $ instead of \ in the last example. Unlike sed, we use the \<digit> form in only the left hand side. Anywhere else it's $<digit>.

Occasionally, you can't use just a /g to get all the changes to occur that you might want. Here are two common cases:

    # put commas in the right places in an integer
    1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;

    # expand tabs to 8-column spacing
    1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
tr/SEARCHLIST/REPLACEMENTLIST/cds
y/SEARCHLIST/REPLACEMENTLIST/cds

Transliterates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is transliterated. (The string specified with =~ must be a scalar variable, an array element, a hash element, or an assignment to one of those, i.e., an lvalue.)

A character range may be specified with a hyphen, so tr/A-J/0-9/ does the same replacement as tr/ACEGIBDFHJ/0246813579/. For sed devotees, y is provided as a synonym for tr. If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes, e.g., tr[A-Z][a-z] or tr(+\-*/)/ABCD/.

Note that tr does not do regular expression character classes such as \d or [:lower:]. The <tr> operator is not equivalent to the tr(1) utility. If you want to map strings between lower/upper cases, see lc in the perlfunc manpage and uc in the perlfunc manpage, and in general consider using the s operator if you need regular expressions.

Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results you probably didn't expect. A sound principle is to use only ranges that begin from and end at either alphabets of equal case (a-e, A-E), or digits (0-4). Anything else is unsafe. If in doubt, spell out the character sets in full.

Options:

    c   Complement the SEARCHLIST.
    d   Delete found but unreplaced characters.
    s   Squash duplicate replaced characters.

If the /c modifier is specified, the SEARCHLIST character set is complemented. If the /d modifier is specified, any characters specified by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note that this is slightly more flexible than the behavior of some tr programs, which delete anything they find in the SEARCHLIST, period.) If the /s modifier is specified, sequences of characters that were transliterated to the same character are squashed down to a single instance of the character.

If the /d modifier is used, the REPLACEMENTLIST is always interpreted exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST, the final character is replicated till it is long enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated. This latter is useful for counting characters in a class or for squashing character sequences in a class.

Examples:

    $ARGV[1] =~ tr/A-Z/a-z/;    # canonicalize to lower case

    $cnt = tr/*/*/;             # count the stars in $_

    $cnt = $sky =~ tr/*/*/;     # count the stars in $sky

    $cnt = tr/0-9//;            # count the digits in $_

    tr/a-zA-Z//s;               # bookkeeper -> bokeper

    ($HOST = $host) =~ tr/a-z/A-Z/;

    tr/a-zA-Z/ /cs;             # change non-alphas to single space

    tr [\200-\377]
       [\000-\177];             # delete 8th bit

If multiple transliterations are given for a character, only the first one is used:

    tr/AAA/XYZ/

will transliterate any A to X.

Because the transliteration table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use an eval():

    eval "tr/$oldlist/$newlist/";
    die $@ if $@;

    eval "tr/$oldlist/$newlist/, 1" or die $@;
<<EOF >>

A line-oriented form of quoting is based on the shell "here-document" syntax. Following a << you specify a string to terminate the quoted material, and all lines following the current line down to the terminating string are the value of the item. The terminating string may be either an identifier (a word), or some quoted text. If quoted, the type of quotes you use determines the treatment of the text, just as in regular quoting. An unquoted identifier works like double quotes. There must be no space between the << and the identifier, unless the identifier is quoted. (If you put a space it will be treated as a null identifier, which is valid, and matches the first empty line.) The terminating string must appear by itself (unquoted and with no surrounding whitespace) on the terminating line.

       print <<EOF;
           The price is $Price.
           EOF

       print << "EOF"; # same as above
           The price is $Price.
           EOF

       print << `EOC`; # execute commands
           echo hi there
           echo lo there
           EOC

       print <<"foo", <<"bar"; # you can stack them
           I said foo.
           foo
           I said bar.
           bar

       myfunc(<< "THIS", 23, <<'THAT');
           Here's a line
           or two.
           THIS
           and here's another.
           THAT

Just don't forget that you have to put a semicolon on the end to finish the statement, as Perl doesn't know you're not going to try to do this:

       print <<ABC
           179231
           ABC
       + 20;

If you want your here-docs to be indented with the rest of the code, you'll need to remove leading whitespace from each line manually:

    ($quote = <<'FINIS') =~ s/^\s+//gm;
       The Road goes ever on and on,
       down from the door where it began.
    FINIS

If you use a here-doc within a delimited construct, such as in s///eg, the quoted material must come on the lines following the final delimiter. So instead of

    s/this/<<E . 'that'
    the other
    E
     . 'more '/eg;

you have to write

    s/this/<<E . 'that'
     . 'more '/eg;
    the other
    E

If the terminating identifier is on the last line of the program, you must be sure there is a newline after it; otherwise, Perl will give the warning Can't find string terminator "END" anywhere before EOF....

Additionally, the quoting rules for the identifier are not related to Perl's quoting rules -- q(), qq(), and the like are not supported in place of '' and "", and the only interpolation is for backslashing the quoting character:

    print << "abc\"def";
    testing...
    abc"def

Finally, quoted strings cannot span multiple lines. The general rule is that the identifier must be a string literal. Stick with that, and you should be safe.

Gory details of parsing quoted constructs

When presented with something that might have several different interpretations, Perl uses the DWIM (that's "Do What I Mean") principle to pick the most probable interpretation. This strategy is so successful that Perl programmers often do not suspect the ambivalence of what they write. But from time to time, Perl's notions differ substantially from what the author honestly meant.

This section hopes to clarify how Perl handles quoted constructs. Although the most common reason to learn this is to unravel labyrinthine regular expressions, because the initial steps of parsing are the same for all quoting operators, they are all discussed together.

The most important Perl parsing rule is the first one discussed below: when processing a quoted construct, Perl first finds the end of that construct, then interprets its contents. If you understand this rule, you may skip the rest of this section on the first reading. The other rules are likely to contradict the user's expectations much less frequently than this first one.

Some passes discussed below are performed concurrently, but because their results are the same, we consider them individually. For different quoting constructs, Perl performs different numbers of passes, from one to five, but these passes are always performed in the same order.

Finding the end

The first pass is finding the end of the quoted construct, whether it be a multicharacter delimiter "\nEOF\n" in the <<EOF construct, a / that terminates a qq// construct, a ] which terminates qq[] construct, or a > which terminates a fileglob started with <.

When searching for single-character non-pairing delimiters, such as /, combinations of \\ and \/ are skipped. However, when searching for single-character pairing delimiter like [, combinations of \\, \], and \[ are all skipped, and nested [, ] are skipped as well. When searching for multicharacter delimiters, nothing is skipped.

For constructs with three-part delimiters (s///, y///, and tr///), the search is repeated once more.

During this search no attention is paid to the semantics of the construct. Thus:

    "$hash{"$foo/$bar"}"

or:

    m/
      bar       # NOT a comment, this slash / terminated m//!
     /x

do not form legal quoted expressions. The quoted part ends on the first " and /, and the rest happens to be a syntax error. Because the slash that terminated m// was followed by a SPACE, the example above is not m//x, but rather m// with no /x modifier. So the embedded # is interpreted as a literal #.

Also no attention is paid to \c\ during this search. Thus the second \ in qq/\c\/ is interpreted as a part of \/, and the following / is not recognized as a delimiter. Instead, use \034 or \x1c at the end of quoted constructs.

Removal of backslashes before delimiters

During the second pass, text between the starting and ending delimiters is copied to a safe location, and the \ is removed from combinations consisting of \ and delimiter--or delimiters, meaning both starting and ending delimiters will should these differ. This removal does not happen for multi-character delimiters. Note that the combination \\ is left intact, just as it was.

Starting from this step no information about the delimiters is used in parsing.

Interpolation

The next step is interpolation in the text obtained, which is now delimiter-independent. There are four different cases.

<<'EOF', m'', s''', tr///, y///

No interpolation is performed.

'', q//

The only interpolation is removal of \ from pairs \\.

"", ``, qq//, qx//, <file*glob>

\Q, \U, \u, \L, \l (possibly paired with \E) are converted to corresponding Perl constructs. Thus, "$foo\Qbaz$bar" is converted to $foo . (quotemeta("baz" . $bar)) internally. The other combinations are replaced with appropriate expansions.

Let it be stressed that whatever falls between \Q and \E is interpolated in the usual way. Something like "\Q\\E" has no \E inside. instead, it has \Q, \\, and E, so the result is the same as for "\\\\E". As a general rule, backslashes between \Q and \E may lead to counterintuitive results. So, "\Q\t\E" is converted to quotemeta("\t"), which is the same as "\\\t" (since TAB is not alphanumeric). Note also that:

  $str = '\t';
  return "\Q$str";

may be closer to the conjectural intention of the writer of "\Q\t\E".

Interpolated scalars and arrays are converted internally to the join and . catenation operations. Thus, "$foo XXX '@arr'" becomes:

  $foo . " XXX '" . (join $", @arr) . "'";

All operations above are performed simultaneously, left to right.

Because the result of "\Q STRING \E" has all metacharacters quoted, there is no way to insert a literal $ or @ inside a \Q\E pair. If protected by \, $ will be quoted to became "\\\$"; if not, it is interpreted as the start of an interpolated scalar.

Note also that the interpolation code needs to make a decision on where the interpolated scalar ends. For instance, whether "a $b -> {c}" really means:

  "a " . $b . " -> {c}";

or:

  "a " . $b -> {c};

Most of the time, the longest possible text that does not include spaces between components and which contains matching braces or brackets. because the outcome may be determined by voting based on heuristic estimators, the result is not strictly predictable. Fortunately, it's usually correct for ambiguous cases.

?RE?, /RE/, m/RE/, s/RE/foo/,

Processing of \Q, \U, \u, \L, \l, and interpolation happens (almost) as with qq// constructs, but the substitution of \ followed by RE-special chars (including \) is not performed. Moreover, inside (?{BLOCK}), (?# comment ), and a #-comment in a //x-regular expression, no processing is performed whatsoever. This is the first step at which the presence of the //x modifier is relevant.

Interpolation has several quirks: $|, $(, and $) are not interpolated, and constructs $var[SOMETHING] are voted (by several different estimators) to be either an array element or $var followed by an RE alternative. This is where the notation ${arr[$bar]} comes handy: /${arr[0-9]}/ is interpreted as array element -9, not as a regular expression from the variable $arr followed by a digit, which would be the interpretation of /$arr[0-9]/. Since voting among different estimators may occur, the result is not predictable.

It is at this step that \1 is begrudgingly converted to $1 in the replacement text of s/// to correct the incorrigible sed hackers who haven't picked up the saner idiom yet. A warning is emitted if the use warnings pragma or the -w command-line flag (that is, the $^W variable) was set.

The lack of processing of \\ creates specific restrictions on the post-processed text. If the delimiter is /, one cannot get the combination \/ into the result of this step. / will finish the regular expression, \/ will be stripped to / on the previous step, and \\/ will be left as is. Because / is equivalent to \/ inside a regular expression, this does not matter unless the delimiter happens to be character special to the RE engine, such as in s*foo*bar*, m[foo], or ?foo?; or an alphanumeric char, as in:

  m m ^ a \s* b mmx;

In the RE above, which is intentionally obfuscated for illustration, the delimiter is m, the modifier is mx, and after backslash-removal the RE is the same as for m/ ^ a \s* b /mx. There's more than one reason you're encouraged to restrict your delimiters to non-alphanumeric, non-whitespace choices.

This step is the last one for all constructs except regular expressions, which are processed further.

Interpolation of regular expressions

Previous steps were performed during the compilation of Perl code, but this one happens at run time--although it may be optimized to be calculated at compile time if appropriate. After preprocessing described above, and possibly after evaluation if catenation, joining, casing translation, or metaquoting are involved, the resulting string is passed to the RE engine for compilation.

Whatever happens in the RE engine might be better discussed in the perlre manpage, but for the sake of continuity, we shall do so here.

This is another step where the presence of the //x modifier is relevant. The RE engine scans the string from left to right and converts it to a finite automaton.

Backslashed characters are either replaced with corresponding literal strings (as with \{), or else they generate special nodes in the finite automaton (as with \b). Characters special to the RE engine (such as |) generate corresponding nodes or groups of nodes. (?#...) comments are ignored. All the rest is either converted to literal strings to match, or else is ignored (as is whitespace and #-style comments if //x is present).

Parsing of the bracketed character class construct, [...], is rather different than the rule used for the rest of the pattern. The terminator of this construct is found using the same rules as for finding the terminator of a {}-delimited construct, the only exception being that ] immediately following [ is treated as though preceded by a backslash. Similarly, the terminator of (?{...}) is found using the same rules as for finding the terminator of a {}-delimited construct.

It is possible to inspect both the string given to RE engine and the resulting finite automaton. See the arguments debug/debugcolor in the use re pragma, as well as Perl's -Dr command-line switch documented in Command Switches in the perlrun manpage.

Optimization of regular expressions

This step is listed for completeness only. Since it does not change semantics, details of this step are not documented and are subject to change without notice. This step is performed over the finite automaton that was generated during the previous pass.

It is at this stage that split() silently optimizes /^/ to mean /^/m.

I/O Operators >>

There are several I/O operators you should know about.

A string enclosed by backticks (grave accents) first undergoes double-quote interpolation. It is then interpreted as an external command, and the output of that command is the value of the backtick string, like in a shell. In scalar context, a single string consisting of all output is returned. In list context, a list of values is returned, one per line of output. (You can set $/ to use a different line terminator.) The command is executed each time the pseudo-literal is evaluated. The status value of the command is returned in $? (see the perlvar manpage for the interpretation of $?). Unlike in csh, no translation is done on the return data--newlines remain newlines. Unlike in any of the shells, single quotes do not hide variable names in the command from interpretation. To pass a literal dollar-sign through to the shell you need to hide it with a backslash. The generalized form of backticks is qx//. (Because backticks always undergo shell expansion as well, see the perlsec manpage for security concerns.)

In scalar context, evaluating a filehandle in angle brackets yields the next line from that file (the newline, if any, included), or undef at end-of-file or on error. When $/ is set to undef (sometimes known as file-slurp mode) and the file is empty, it returns '' the first time, followed by undef subsequently.

Ordinarily you must assign the returned value to a variable, but there is one situation where an automatic assignment happens. If and only if the input symbol is the only thing inside the conditional of a while statement (even if disguised as a for(;;) loop), the value is automatically assigned to the global variable $_, destroying whatever was there previously. (This may seem like an odd thing to you, but you'll use the construct in almost every Perl script you write.) The $_ variable is not implicitly localized. You'll have to put a local $_; before the loop if you want that to happen.

The following lines are equivalent:

    while (defined($_ = <STDIN>)) { print; }
    while ($_ = <STDIN>) { print; }
    while (<STDIN>) { print; }
    for (;<STDIN>;) { print; }
    print while defined($_ = <STDIN>);
    print while ($_ = <STDIN>);
    print while <STDIN>;

This also behaves similarly, but avoids $_ :

    while (my $line = <STDIN>) { print $line }

In these loop constructs, the assigned value (whether assignment is automatic or explicit) is then tested to see whether it is defined. The defined test avoids problems where line has a string value that would be treated as false by Perl, for example a "" or a "0" with no trailing newline. If you really mean for such values to terminate the loop, they should be tested for explicitly:

    while (($_ = <STDIN>) ne '0') { ... }
    while (<STDIN>) { last unless $_; ... }

In other boolean contexts, <filehandle> without an explicit defined test or comparison elicit a warning if the use warnings pragma or the -w command-line switch (the $^W variable) is in effect.

The filehandles STDIN, STDOUT, and STDERR are predefined. (The filehandles stdin, stdout, and stderr will also work except in packages, where they would be interpreted as local identifiers rather than global.) Additional filehandles may be created with the open() function, amongst others. See the perlopentut manpage and open in the perlfunc manpage for details on this.

If a <FILEHANDLE> is used in a context that is looking for a list, a list comprising all input lines is returned, one line per list element. It's easy to grow to a rather large data space this way, so use with care.

<FILEHANDLE> may also be spelled readline(*FILEHANDLE). See readline in the perlfunc manpage.

The null filehandle <> is special: it can be used to emulate the behavior of sed and awk. Input from <> comes either from standard input, or from each file listed on the command line. Here's how it works: the first time <> is evaluated, the @ARGV array is checked, and if it is empty, $ARGV[0] is set to "-", which when opened gives you standard input. The @ARGV array is then processed as a list of filenames. The loop

    while (<>) {
        ...                     # code for each line
    }

is equivalent to the following Perl-like pseudo code:

    unshift(@ARGV, '-') unless @ARGV;
    while ($ARGV = shift) {
        open(ARGV, $ARGV);
        while (<ARGV>) {
            ...         # code for each line
        }
    }

except that it isn't so cumbersome to say, and will actually work. It really does shift the @ARGV array and put the current filename into the $ARGV variable. It also uses filehandle ARGV internally--<> is just a synonym for <ARGV>, which is magical. (The pseudo code above doesn't work because it treats <ARGV> as non-magical.)

You can modify @ARGV before the first <> as long as the array ends up containing the list of filenames you really want. Line numbers ($.) continue as though the input were one big happy file. See the example in eof in the perlfunc manpage for how to reset line numbers on each file.

If you want to set @ARGV to your own list of files, go right ahead. This sets @ARGV to all plain text files if no @ARGV was given:

    @ARGV = grep { -f && -T } glob('*') unless @ARGV;

You can even set them to pipe commands. For example, this automatically filters compressed arguments through gzip:

    @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_ |" : $_ } @ARGV;

If you want to pass switches into your script, you can use one of the Getopts modules or put a loop on the front like this:

    while ($_ = $ARGV[0], /^-/) {
        shift;
        last if /^--$/;
        if (/^-D(.*)/) { $debug = $1 }
        if (/^-v/)     { $verbose++  }
        # ...           # other switches
    }

    while (<>) {
        # ...           # code for each line
    }

The <> symbol will return undef for end-of-file only once. If you call it again after this, it will assume you are processing another @ARGV list, and if you haven't set @ARGV, will read input from STDIN.

If what the angle brackets contain is a simple scalar variable (e.g., <$foo>), then that variable contains the name of the filehandle to input from, or its typeglob, or a reference to the same. For example:

    $fh = \*STDIN;
    $line = <$fh>;

If what's within the angle brackets is neither a filehandle nor a simple scalar variable containing a filehandle name, typeglob, or typeglob reference, it is interpreted as a filename pattern to be globbed, and either a list of filenames or the next filename in the list is returned, depending on context. This distinction is determined on syntactic grounds alone. That means <$x> is always a readline() from an indirect handle, but <$hash{key}> is always a glob(). That's because $x is a simple scalar variable, but $hash{key} is not--it's a hash element. Even <$x > (note the extra space) is treated as glob("$x "), not readline($x).

One level of double-quote interpretation is done first, but you can't say <$foo> because that's an indirect filehandle as explained in the previous paragraph. (In older versions of Perl, programmers would insert curly brackets to force interpretation as a filename glob: <${foo}>. These days, it's considered cleaner to call the internal function directly as glob($foo), which is probably the right way to have done it in the first place.) For example:

    while (<*.c>) {
        chmod 0644, $_;
    }

is roughly equivalent to:

    open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
    while (<FOO>) {
        chomp;
        chmod 0644, $_;
    }

except that the globbing is actually done internally using the standard File::Glob extension. Of course, the shortest way to do the above is:

    chmod 0644, <*.c>;

A (file)glob evaluates its (embedded) argument only when it is starting a new list. All values must be read before it will start over. In list context, this isn't important because you automatically get them all anyway. However, in scalar context the operator returns the next value each time it's called, or undef when the list has run out. As with filehandle reads, an automatic defined is generated when the glob occurs in the test part of a while, because legal glob returns (e.g. a file called 0) would otherwise terminate the loop. Again, undef is returned only once. So if you're expecting a single value from a glob, it is much better to say

    ($file) = <blurch*>;

than

    $file = <blurch*>;

because the latter will alternate between returning a filename and returning false.

If you're trying to do variable interpolation, it's definitely better to use the glob() function, because the older notation can cause people to become confused with the indirect filehandle notation.

    @files = glob("$dir/*.[ch]");
    @files = glob($files[$i]);

Constant Folding

Like C, Perl does a certain amount of expression evaluation at compile time whenever it determines that all arguments to an operator are static and have no side effects. In particular, string concatenation happens at compile time between literals that don't do variable substitution. Backslash interpolation also happens at compile time. You can say

    'Now is the time for all' . "\n" .
        'good men to come to.'

and this all reduces to one string internally. Likewise, if you say

    foreach $file (@filenames) {
        if (-s $file > 5 + 100 * 2**16) {  }
    }

the compiler will precompute the number which that expression represents so that the interpreter won't have to.

No-ops

Perl doesn't officially have a no-op operator, but the bare constants 0 and 1 are special-cased to not produce a warning in a void context, so you can for example safely do

    1 while foo();

Bitwise String Operators

Bitstrings of any size may be manipulated by the bitwise operators (~ | & ^).

If the operands to a binary bitwise op are strings of different sizes, | and ^ ops act as though the shorter operand had additional zero bits on the right, while the & op acts as though the longer operand were truncated to the length of the shorter. The granularity for such extension or truncation is one or more bytes.

    # ASCII-based examples
    print "j p \n" ^ " a h";            # prints "JAPH\n"
    print "JA" | "  ph\n";              # prints "japh\n"
    print "japh\nJunk" & '_____';       # prints "JAPH\n";
    print 'p N$' ^ " E<H\n";            # prints "Perl\n";

If you are intending to manipulate bitstrings, be certain that you're supplying bitstrings: If an operand is a number, that will imply a numeric bitwise operation. You may explicitly show which type of operation you intend by using "" or 0+, as in the examples below.

    $foo =  150  |  105;        # yields 255  (0x96 | 0x69 is 0xFF)
    $foo = '150' |  105;        # yields 255
    $foo =  150  | '105';       # yields 255
    $foo = '150' | '105';       # yields string '155' (under ASCII)

    $baz = 0+$foo & 0+$bar;     # both ops explicitly numeric
    $biz = "$foo" ^ "$bar";     # both ops explicitly stringy

See vec in the perlfunc manpage for information on how to manipulate individual bits in a bit vector.

Integer Arithmetic

By default, Perl assumes that it must do most of its arithmetic in floating point. But by saying

    use integer;

you may tell the compiler that it's okay to use integer operations (if it feels like it) from here to the end of the enclosing BLOCK. An inner BLOCK may countermand this by saying

    no integer;

which lasts until the end of that BLOCK. Note that this doesn't mean everything is only an integer, merely that Perl may use integer operations if it is so inclined. For example, even under use integer, if you take the sqrt(2), you'll still get 1.4142135623731 or so.

Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<", and ">>") always produce integral results. (But see also Bitwise String Operators.) However, use integer still has meaning for them. By default, their results are interpreted as unsigned integers, but if use integer is in effect, their results are interpreted as signed integers. For example, ~0 usually evaluates to a large integral value. However, use integer; ~0 is -1 on twos-complement machines.

Floating-point Arithmetic

While use integer provides integer-only arithmetic, there is no analogous mechanism to provide automatic rounding or truncation to a certain number of decimal places. For rounding to a certain number of digits, sprintf() or printf() is usually the easiest route. See the perlfaq4 manpage.

Floating-point numbers are only approximations to what a mathematician would call real numbers. There are infinitely more reals than floats, so some corners must be cut. For example:

    printf "%.20g\n", 123456789123456789;
    #        produces 123456789123456784

Testing for exact equality of floating-point equality or inequality is not a good idea. Here's a (relatively expensive) work-around to compare whether two floating-point numbers are equal to a particular number of decimal places. See Knuth, volume II, for a more robust treatment of this topic.

    sub fp_equal {
        my ($X, $Y, $POINTS) = @_;
        my ($tX, $tY);
        $tX = sprintf("%.${POINTS}g", $X);
        $tY = sprintf("%.${POINTS}g", $Y);
        return $tX eq $tY;
    }

The POSIX module (part of the standard perl distribution) implements ceil(), floor(), and other mathematical and trigonometric functions. The Math::Complex module (part of the standard perl distribution) defines mathematical functions that work on both the reals and the imaginary numbers. Math::Complex not as efficient as POSIX, but POSIX can't work with complex numbers.

Rounding in financial applications can have serious implications, and the rounding method used should be specified precisely. In these cases, it probably pays not to trust whichever system rounding is being used by Perl, but to instead implement the rounding function you need yourself.

Bigger Numbers

The standard Math::BigInt and Math::BigFloat modules provide variable-precision arithmetic and overloaded operators, although they're currently pretty slow. At the cost of some space and considerable speed, they avoid the normal pitfalls associated with limited-precision representations.

    use Math::BigInt;
    $x = Math::BigInt->new('123456789123456789');
    print $x * $x;

    # prints +15241578780673678515622620750190521

There are several modules that let you calculate with (bound only by memory and cpu-time) unlimited or fixed precision. There are also some non-standard modules that provide faster implementations via external C libraries.

Here is a short, but incomplete summary:

        Math::Fraction          big, unlimited fractions like 9973 / 12967
        Math::String            treat string sequences like numbers
        Math::FixedPrecision    calculate with a fixed precision
        Math::Currency          for currency calculations
        Bit::Vector             manipulate bit vectors fast (uses C)
        Math::BigIntFast        Bit::Vector wrapper for big numbers
        Math::Pari              provides access to the Pari C library
        Math::BigInteger        uses an external C library
        Math::Cephes            uses external Cephes C library (no big numbers)
        Math::Cephes::Fraction  fractions via the Cephes library
        Math::GMP               another one using an external C library

Choose wisely.


perlopentut - tutorial on opening things in Perl

  • Open à la shell
    • Simple Opens
    • Indirect Filehandles
    • Pipe Opens
    • The Minus File
    • Mixing Reads and Writes
    • Filters
  • Open à la C
    • Permissions à la mode
  • Obscure Open Tricks
    • Re-Opening Files (dups)
    • Dispelling the Dweomer
    • Paths as Opens
    • Single Argument Open
    • Playing with STDIN and STDOUT
  • Other I/O Issues
    • Opening Non-File Files
    • Opening Named Pipes
    • Opening Sockets
    • Binary Files
    • File Locking
    • IO Layers
  • SEE ALSO
  • AUTHOR and COPYRIGHT
  • HISTORY

NAME

perlopentut - tutorial on opening things in Perl

DESCRIPTION

Perl has two simple, built-in ways to open files: the shell way for convenience, and the C way for precision. The shell way also has 2- and 3-argument forms, which have different semantics for handling the filename. The choice is yours.

Open à la shell

Perl's open function was designed to mimic the way command-line redirection in the shell works. Here are some basic examples from the shell:

    $ myprogram file1 file2 file3
    $ myprogram    <  inputfile
    $ myprogram    >  outputfile
    $ myprogram    >> outputfile
    $ myprogram    |  otherprogram
    $ otherprogram |  myprogram

And here are some more advanced examples:

    $ otherprogram      | myprogram f1 - f2
    $ otherprogram 2>&1 | myprogram -
    $ myprogram     <&3
    $ myprogram     >&4

Programmers accustomed to constructs like those above can take comfort in learning that Perl directly supports these familiar constructs using virtually the same syntax as the shell.

Simple Opens

The open function takes two arguments: the first is a filehandle, and the second is a single string comprising both what to open and how to open it. open returns true when it works, and when it fails, returns a false value and sets the special variable $! to reflect the system error. If the filehandle was previously opened, it will be implicitly closed first.

For example:

    open(INFO,      "datafile") || die("can't open datafile: $!");
    open(INFO,   "<  datafile") || die("can't open datafile: $!");
    open(RESULTS,">  runstats") || die("can't open runstats: $!");
    open(LOG,    ">> logfile ") || die("can't open logfile:  $!");

If you prefer the low-punctuation version, you could write that this way:

    open INFO,   "<  datafile"  or die "can't open datafile: $!";
    open RESULTS,">  runstats"  or die "can't open runstats: $!";
    open LOG,    ">> logfile "  or die "can't open logfile:  $!";

A few things to notice. First, the leading less-than is optional. If omitted, Perl assumes that you want to open the file for reading.

Note also that the first example uses the || logical operator, and the second uses or, which has lower precedence. Using || in the latter examples would effectively mean

    open INFO, ( "<  datafile"  || die "can't open datafile: $!" );

which is definitely not what you want.

The other important thing to notice is that, just as in the shell, any whitespace before or after the filename is ignored. This is good, because you wouldn't want these to do different things:

    open INFO,   "<datafile"
    open INFO,   "< datafile"
    open INFO,   "<  datafile"

Ignoring surrounding whitespace also helps for when you read a filename in from a different file, and forget to trim it before opening:

    $filename = <INFO>;         # oops, \n still there
    open(EXTRA, "< $filename") || die "can't open $filename: $!";

This is not a bug, but a feature. Because open mimics the shell in its style of using redirection arrows to specify how to open the file, it also does so with respect to extra whitespace around the filename itself as well. For accessing files with naughty names, see Dispelling the Dweomer.

There is also a 3-argument version of open, which lets you put the special redirection characters into their own argument:

    open( INFO, ">", $datafile ) || die "Can't create $datafile: $!";

In this case, the filename to open is the actual string in $datafile, so you don't have to worry about $datafile containing characters that might influence the open mode, or whitespace at the beginning of the filename that would be absorbed in the 2-argument version. Also, any reduction of unnecessary string interpolation is a good thing.

Indirect Filehandles

open's first argument can be a reference to a filehandle. As of perl 5.6.0, if the argument is uninitialized, Perl will automatically create a filehandle and put a reference to it in the first argument, like so:

    open( my $in, $infile )   or die "Couldn't read $infile: $!";
    while ( <$in> ) {
        # do something with $_
    }
    close $in;

Indirect filehandles make namespace management easier. Since filehandles are global to the current package, two subroutines trying to open INFILE will clash. With two functions opening indirect filehandles like my $infile, there's no clash and no need to worry about future conflicts.

Another convenient behavior is that an indirect filehandle automatically closes when it goes out of scope or when you undefine it:

    sub firstline {
        open( my $in, shift ) && return scalar <$in>;
        # no close() required
    }

Pipe Opens

In C, when you want to open a file using the standard I/O library, you use the fopen function, but when opening a pipe, you use the popen function. But in the shell, you just use a different redirection character. That's also the case for Perl. The open call remains the same--just its argument differs.

If the leading character is a pipe symbol, open starts up a new command and opens a write-only filehandle leading into that command. This lets you write into that handle and have what you write show up on that command's standard input. For example:

    open(PRINTER, "| lpr -Plp1")    || die "can't run lpr: $!";
    print PRINTER "stuff\n";
    close(PRINTER)                  || die "can't close lpr: $!";

If the trailing character is a pipe, you start up a new command and open a read-only filehandle leading out of that command. This lets whatever that command writes to its standard output show up on your handle for reading. For example:

    open(NET, "netstat -i -n |")    || die "can't fork netstat: $!";
    while (<NET>) { }               # do something with input
    close(NET)                      || die "can't close netstat: $!";

What happens if you try to open a pipe to or from a non-existent command? If possible, Perl will detect the failure and set $! as usual. But if the command contains special shell characters, such as > or *, called 'metacharacters', Perl does not execute the command directly. Instead, Perl runs the shell, which then tries to run the command. This means that it's the shell that gets the error indication. In such a case, the open call will only indicate failure if Perl can't even run the shell. See How can I capture STDERR from an external command? in the perlfaq8 manpage to see how to cope with this. There's also an explanation in the perlipc manpage.

If you would like to open a bidirectional pipe, the IPC::Open2 library will handle this for you. Check out Bidirectional Communication with Another Process in the perlipc manpage

The Minus File

Again following the lead of the standard shell utilities, Perl's open function treats a file whose name is a single minus, "-", in a special way. If you open minus for reading, it really means to access the standard input. If you open minus for writing, it really means to access the standard output.

If minus can be used as the default input or default output, what happens if you open a pipe into or out of minus? What's the default command it would run? The same script as you're currently running! This is actually a stealth fork hidden inside an open call. See Safe Pipe Opens in the perlipc manpage for details.

Mixing Reads and Writes

It is possible to specify both read and write access. All you do is add a "+" symbol in front of the redirection. But as in the shell, using a less-than on a file never creates a new file; it only opens an existing one. On the other hand, using a greater-than always clobbers (truncates to zero length) an existing file, or creates a brand-new one if there isn't an old one. Adding a "+" for read-write doesn't affect whether it only works on existing files or always clobbers existing ones.

    open(WTMP, "+< /usr/adm/wtmp")
        || die "can't open /usr/adm/wtmp: $!";

    open(SCREEN, "+> lkscreen")
        || die "can't open lkscreen: $!";

    open(LOGFILE, "+>> /var/log/applog"
        || die "can't open /var/log/applog: $!";

The first one won't create a new file, and the second one will always clobber an old one. The third one will create a new file if necessary and not clobber an old one, and it will allow you to read at any point in the file, but all writes will always go to the end. In short, the first case is substantially more common than the second and third cases, which are almost always wrong. (If you know C, the plus in Perl's open is historically derived from the one in C's fopen(3S), which it ultimately calls.)

In fact, when it comes to updating a file, unless you're working on a binary file as in the WTMP case above, you probably don't want to use this approach for updating. Instead, Perl's -i flag comes to the rescue. The following command takes all the C, C++, or yacc source or header files and changes all their foo's to bar's, leaving the old version in the original filename with a ".orig" tacked on the end:

    $ perl -i.orig -pe 's/\bfoo\b/bar/g' *.[Cchy]

This is a short cut for some renaming games that are really the best way to update textfiles. See the second question in the perlfaq5 manpage for more details.

Filters

One of the most common uses for open is one you never even notice. When you process the ARGV filehandle using <ARGV>, Perl actually does an implicit open on each file in @ARGV. Thus a program called like this:

    $ myprogram file1 file2 file3

Can have all its files opened and processed one at a time using a construct no more complex than:

    while (<>) {
        # do something with $_
    }

If @ARGV is empty when the loop first begins, Perl pretends you've opened up minus, that is, the standard input. In fact, $ARGV, the currently open file during <ARGV> processing, is even set to "-" in these circumstances.

You are welcome to pre-process your @ARGV before starting the loop to make sure it's to your liking. One reason to do this might be to remove command options beginning with a minus. While you can always roll the simple ones by hand, the Getopts modules are good for this:

    use Getopt::Std;

    # -v, -D, -o ARG, sets $opt_v, $opt_D, $opt_o
    getopts("vDo:");

    # -v, -D, -o ARG, sets $args{v}, $args{D}, $args{o}
    getopts("vDo:", \%args);

Or the standard Getopt::Long module to permit named arguments:

    use Getopt::Long;
    GetOptions( "verbose"  => \$verbose,        # --verbose
                "Debug"    => \$debug,          # --Debug
                "output=s" => \$output );
            # --output=somestring or --output somestring

Another reason for preprocessing arguments is to make an empty argument list default to all files:

    @ARGV = glob("*") unless @ARGV;

You could even filter out all but plain, text files. This is a bit silent, of course, and you might prefer to mention them on the way.

    @ARGV = grep { -f && -T } @ARGV;

If you're using the -n or -p command-line options, you should put changes to @ARGV in a BEGIN{} block.

Remember that a normal open has special properties, in that it might call fopen(3S) or it might called popen(3S), depending on what its argument looks like; that's why it's sometimes called "magic open". Here's an example:

    $pwdinfo = `domainname` =~ /^(\(none\))?$/
                    ? '< /etc/passwd'
                    : 'ypcat passwd |';

    open(PWD, $pwdinfo)
                or die "can't open $pwdinfo: $!";

This sort of thing also comes into play in filter processing. Because <ARGV> processing employs the normal, shell-style Perl open, it respects all the special things we've already seen:

    $ myprogram f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile

That program will read from the file f1, the process cmd1, standard input (tmpfile in this case), the f2 file, the cmd2 command, and finally the f3 file.

Yes, this also means that if you have files named "-" (and so on) in your directory, they won't be processed as literal files by open. You'll need to pass them as "./-", much as you would for the rm program, or you could use sysopen as described below.

One of the more interesting applications is to change files of a certain name into pipes. For example, to autoprocess gzipped or compressed files by decompressing them with gzip:

    @ARGV = map { /^\.(gz|Z)$/ ? "gzip -dc $_ |" : $_  } @ARGV;

Or, if you have the GET program installed from LWP, you can fetch URLs before processing them:

    @ARGV = map { m#^\w+://# ? "GET $_ |" : $_ } @ARGV;

It's not for nothing that this is called magic <ARGV>. Pretty nifty, eh?

Open à la C

If you want the convenience of the shell, then Perl's open is definitely the way to go. On the other hand, if you want finer precision than C's simplistic fopen(3S) provides you should look to Perl's sysopen, which is a direct hook into the open(2) system call. That does mean it's a bit more involved, but that's the price of precision.

sysopen takes 3 (or 4) arguments.

    sysopen HANDLE, PATH, FLAGS, [MASK]

The HANDLE argument is a filehandle just as with open. The PATH is a literal path, one that doesn't pay attention to any greater-thans or less-thans or pipes or minuses, nor ignore whitespace. If it's there, it's part of the path. The FLAGS argument contains one or more values derived from the Fcntl module that have been or'd together using the bitwise "|" operator. The final argument, the MASK, is optional; if present, it is combined with the user's current umask for the creation mode of the file. You should usually omit this.

Although the traditional values of read-only, write-only, and read-write are 0, 1, and 2 respectively, this is known not to hold true on some systems. Instead, it's best to load in the appropriate constants first from the Fcntl module, which supplies the following standard flags:

    O_RDONLY            Read only
    O_WRONLY            Write only
    O_RDWR              Read and write
    O_CREAT             Create the file if it doesn't exist
    O_EXCL              Fail if the file already exists
    O_APPEND            Append to the file
    O_TRUNC             Truncate the file
    O_NONBLOCK          Non-blocking access

Less common flags that are sometimes available on some operating systems include O_BINARY, O_TEXT, O_SHLOCK, O_EXLOCK, O_DEFER, O_SYNC, O_ASYNC, O_DSYNC, O_RSYNC, O_NOCTTY, O_NDELAY and O_LARGEFILE. Consult your open(2) manpage or its local equivalent for details. (Note: starting from Perl release 5.6 the O_LARGEFILE flag, if available, is automatically added to the sysopen() flags because large files are the default.)

Here's how to use sysopen to emulate the simple open calls we had before. We'll omit the || die $! checks for clarity, but make sure you always check the return values in real code. These aren't quite the same, since open will trim leading and trailing whitespace, but you'll get the idea.

To open a file for reading:

    open(FH, "< $path");
    sysopen(FH, $path, O_RDONLY);

To open a file for writing, creating a new file if needed or else truncating an old file:

    open(FH, "> $path");
    sysopen(FH, $path, O_WRONLY | O_TRUNC | O_CREAT);

To open a file for appending, creating one if necessary:

    open(FH, ">> $path");
    sysopen(FH, $path, O_WRONLY | O_APPEND | O_CREAT);

To open a file for update, where the file must already exist:

    open(FH, "+< $path");
    sysopen(FH, $path, O_RDWR);

And here are things you can do with sysopen that you cannot do with a regular open. As you'll see, it's just a matter of controlling the flags in the third argument.

To open a file for writing, creating a new file which must not previously exist:

    sysopen(FH, $path, O_WRONLY | O_EXCL | O_CREAT);

To open a file for appending, where that file must already exist:

    sysopen(FH, $path, O_WRONLY | O_APPEND);

To open a file for update, creating a new file if necessary:

    sysopen(FH, $path, O_RDWR | O_CREAT);

To open a file for update, where that file must not already exist:

    sysopen(FH, $path, O_RDWR | O_EXCL | O_CREAT);

To open a file without blocking, creating one if necessary:

    sysopen(FH, $path, O_WRONLY | O_NONBLOCK | O_CREAT);

Permissions à la mode

If you omit the MASK argument to sysopen, Perl uses the octal value 0666. The normal MASK to use for executables and directories should be 0777, and for anything else, 0666.

Why so permissive? Well, it isn't really. The MASK will be modified by your process's current umask. A umask is a number representing disabled permissions bits; that is, bits that will not be turned on in the created files' permissions field.

For example, if your umask were 027, then the 020 part would disable the group from writing, and the 007 part would disable others from reading, writing, or executing. Under these conditions, passing sysopen 0666 would create a file with mode 0640, since 0666 & ~027 is 0640.

You should seldom use the MASK argument to sysopen(). That takes away the user's freedom to choose what permission new files will have. Denying choice is almost always a bad thing. One exception would be for cases where sensitive or private data is being stored, such as with mail folders, cookie files, and internal temporary files.

Obscure Open Tricks

Re-Opening Files (dups)

Sometimes you already have a filehandle open, and want to make another handle that's a duplicate of the first one. In the shell, we place an ampersand in front of a file descriptor number when doing redirections. For example, 2>&1 makes descriptor 2 (that's STDERR in Perl) be redirected into descriptor 1 (which is usually Perl's STDOUT). The same is essentially true in Perl: a filename that begins with an ampersand is treated instead as a file descriptor if a number, or as a filehandle if a string.

    open(SAVEOUT, ">&SAVEERR") || die "couldn't dup SAVEERR: $!";
    open(MHCONTEXT, "<&4")     || die "couldn't dup fd4: $!";

That means that if a function is expecting a filename, but you don't want to give it a filename because you already have the file open, you can just pass the filehandle with a leading ampersand. It's best to use a fully qualified handle though, just in case the function happens to be in a different package:

    somefunction("&main::LOGFILE");

This way if somefunction() is planning on opening its argument, it can just use the already opened handle. This differs from passing a handle, because with a handle, you don't open the file. Here you have something you can pass to open.

If you have one of those tricky, newfangled I/O objects that the C++ folks are raving about, then this doesn't work because those aren't a proper filehandle in the native Perl sense. You'll have to use fileno() to pull out the proper descriptor number, assuming you can:

    use IO::Socket;
    $handle = IO::Socket::INET->new("www.perl.com:80");
    $fd = $handle->fileno;
    somefunction("&$fd");  # not an indirect function call

It can be easier (and certainly will be faster) just to use real filehandles though:

    use IO::Socket;
    local *REMOTE = IO::Socket::INET->new("www.perl.com:80");
    die "can't connect" unless defined(fileno(REMOTE));
    somefunction("&main::REMOTE");

If the filehandle or descriptor number is preceded not just with a simple "&" but rather with a "&=" combination, then Perl will not create a completely new descriptor opened to the same place using the dup(2) system call. Instead, it will just make something of an alias to the existing one using the fdopen(3S) library call This is slightly more parsimonious of systems resources, although this is less a concern these days. Here's an example of that:

    $fd = $ENV{"MHCONTEXTFD"};
    open(MHCONTEXT, "<&=$fd")   or die "couldn't fdopen $fd: $!";

If you're using magic <ARGV>, you could even pass in as a command line argument in @ARGV something like "<&=$MHCONTEXTFD", but we've never seen anyone actually do this.

Dispelling the Dweomer

Perl is more of a DWIMmer language than something like Java--where DWIM is an acronym for "do what I mean". But this principle sometimes leads to more hidden magic than one knows what to do with. In this way, Perl is also filled with dweomer, an obscure word meaning an enchantment. Sometimes, Perl's DWIMmer is just too much like dweomer for comfort.

If magic open is a bit too magical for you, you don't have to turn to sysopen. To open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace. Leading whitespace is protected by inserting a "./" in front of a filename that starts with whitespace. Trailing whitespace is protected by appending an ASCII NUL byte ("\0") at the end of the string.

    $file =~ s#^(\s)#./$1#;
    open(FH, "< $file\0")   || die "can't open $file: $!";

This assumes, of course, that your system considers dot the current working directory, slash the directory separator, and disallows ASCII NULs within a valid filename. Most systems follow these conventions, including all POSIX systems as well as proprietary Microsoft systems. The only vaguely popular system that doesn't work this way is the "Classic" Macintosh system, which uses a colon where the rest of us use a slash. Maybe sysopen isn't such a bad idea after all.

If you want to use <ARGV> processing in a totally boring and non-magical way, you could do this first:

    #   "Sam sat on the ground and put his head in his hands.
    #   'I wish I had never come here, and I don't want to see
    #   no more magic,' he said, and fell silent."
    for (@ARGV) {
        s#^([^./])#./$1#;
        $_ .= "\0";
    }
    while (<>) {
        # now process $_
    }

But be warned that users will not appreciate being unable to use "-" to mean standard input, per the standard convention.

Paths as Opens

You've probably noticed how Perl's warn and die functions can produce messages like:

    Some warning at scriptname line 29, <FH> line 7.

That's because you opened a filehandle FH, and had read in seven records from it. But what was the name of the file, rather than the handle?

If you aren't running with strict refs, or if you've turned them off temporarily, then all you have to do is this:

    open($path, "< $path") || die "can't open $path: $!";
    while (<$path>) {
        # whatever
    }

Since you're using the pathname of the file as its handle, you'll get warnings more like

    Some warning at scriptname line 29, </etc/motd> line 7.

Single Argument Open

Remember how we said that Perl's open took two arguments? That was a passive prevarication. You see, it can also take just one argument. If and only if the variable is a global variable, not a lexical, you can pass open just one argument, the filehandle, and it will get the path from the global scalar variable of the same name.

    $FILE = "/etc/motd";
    open FILE or die "can't open $FILE: $!";
    while (<FILE>) {
        # whatever
    }

Why is this here? Someone has to cater to the hysterical porpoises. It's something that's been in Perl since the very beginning, if not before.

Playing with STDIN and STDOUT

One clever move with STDOUT is to explicitly close it when you're done with the program.

    END { close(STDOUT) || die "can't close stdout: $!" }

If you don't do this, and your program fills up the disk partition due to a command line redirection, it won't report the error exit with a failure status.

You don't have to accept the STDIN and STDOUT you were given. You are welcome to reopen them if you'd like.

    open(STDIN, "< datafile")
        || die "can't open datafile: $!";

    open(STDOUT, "> output")
        || die "can't open output: $!";

And then these can be accessed directly or passed on to subprocesses. This makes it look as though the program were initially invoked with those redirections from the command line.

It's probably more interesting to connect these to pipes. For example:

    $pager = $ENV{PAGER} || "(less || more)";
    open(STDOUT, "| $pager")
        || die "can't fork a pager: $!";

This makes it appear as though your program were called with its stdout already piped into your pager. You can also use this kind of thing in conjunction with an implicit fork to yourself. You might do this if you would rather handle the post processing in your own program, just in a different process:

    head(100);
    while (<>) {
        print;
    }

    sub head {
        my $lines = shift || 20;
        return if $pid = open(STDOUT, "|-");       # return if parent
        die "cannot fork: $!" unless defined $pid;
        while (<STDIN>) {
            last if --$lines < 0;
            print;
        }
        exit;
    }

This technique can be applied to repeatedly push as many filters on your output stream as you wish.

Other I/O Issues

These topics aren't really arguments related to open or sysopen, but they do affect what you do with your open files.

Opening Non-File Files

When is a file not a file? Well, you could say when it exists but isn't a plain file. We'll check whether it's a symbolic link first, just in case.

    if (-l $file || ! -f _) {
        print "$file is not a plain file\n";
    }

What other kinds of files are there than, well, files? Directories, symbolic links, named pipes, Unix-domain sockets, and block and character devices. Those are all files, too--just not plain files. This isn't the same issue as being a text file. Not all text files are plain files. Not all plain files are text files. That's why there are separate -f and -T file tests.

To open a directory, you should use the opendir function, then process it with readdir, carefully restoring the directory name if necessary:

    opendir(DIR, $dirname) or die "can't opendir $dirname: $!";
    while (defined($file = readdir(DIR))) {
        # do something with "$dirname/$file"
    }
    closedir(DIR);

If you want to process directories recursively, it's better to use the File::Find module. For example, this prints out all files recursively and adds a slash to their names if the file is a directory.

    @ARGV = qw(.) unless @ARGV;
    use File::Find;
    find sub { print $File::Find::name, -d && '/', "\n" }, @ARGV;

This finds all bogus symbolic links beneath a particular directory:

    find sub { print "$File::Find::name\n" if -l && !-e }, $dir;

As you see, with symbolic links, you can just pretend that it is what it points to. Or, if you want to know what it points to, then readlink is called for:

    if (-l $file) {
        if (defined($whither = readlink($file))) {
            print "$file points to $whither\n";
        } else {
            print "$file points nowhere: $!\n";
        }
    }

Opening Named Pipes

Named pipes are a different matter. You pretend they're regular files, but their opens will normally block until there is both a reader and a writer. You can read more about them in Named Pipes in the perlipc manpage. Unix-domain sockets are rather different beasts as well; they're described in Unix-Domain TCP Clients and Servers in the perlipc manpage.

When it comes to opening devices, it can be easy and it can be tricky. We'll assume that if you're opening up a block device, you know what you're doing. The character devices are more interesting. These are typically used for modems, mice, and some kinds of printers. This is described in How do I read and write the serial port? in the perlfaq8 manpage It's often enough to open them carefully:

    sysopen(TTYIN, "/dev/ttyS1", O_RDWR | O_NDELAY | O_NOCTTY)
                # (O_NOCTTY no longer needed on POSIX systems)
        or die "can't open /dev/ttyS1: $!";
    open(TTYOUT, "+>&TTYIN")
        or die "can't dup TTYIN: $!";

    $ofh = select(TTYOUT); $| = 1; select($ofh);

    print TTYOUT "+++at\015";
    $answer = <TTYIN>;

With descriptors that you haven't opened using sysopen, such as sockets, you can set them to be non-blocking using fcntl:

    use Fcntl;
    my $old_flags = fcntl($handle, F_GETFL, 0)
        or die "can't get flags: $!";
    fcntl($handle, F_SETFL, $old_flags | O_NONBLOCK)
        or die "can't set non blocking: $!";

Rather than losing yourself in a morass of twisting, turning ioctls, all dissimilar, if you're going to manipulate ttys, it's best to make calls out to the stty(1) program if you have it, or else use the portable POSIX interface. To figure this all out, you'll need to read the termios(3) manpage, which describes the POSIX interface to tty devices, and then the POSIX manpage, which describes Perl's interface to POSIX. There are also some high-level modules on CPAN that can help you with these games. Check out Term::ReadKey and Term::ReadLine.

Opening Sockets

What else can you open? To open a connection using sockets, you won't use one of Perl's two open functions. See Sockets: Client/Server Communication in the perlipc manpage for that. Here's an example. Once you have it, you can use FH as a bidirectional filehandle.

    use IO::Socket;
    local *FH = IO::Socket::INET->new("www.perl.com:80");

For opening up a URL, the LWP modules from CPAN are just what the doctor ordered. There's no filehandle interface, but it's still easy to get the contents of a document:

    use LWP::Simple;
    $doc = get('http://www.linpro.no/lwp/');

Binary Files

On certain legacy systems with what could charitably be called terminally convoluted (some would say broken) I/O models, a file isn't a file--at least, not with respect to the C standard I/O library. On these old systems whose libraries (but not kernels) distinguish between text and binary streams, to get files to behave properly you'll have to bend over backwards to avoid nasty problems. On such infelicitous systems, sockets and pipes are already opened in binary mode, and there is currently no way to turn that off. With files, you have more options.

Another option is to use the binmode function on the appropriate handles before doing regular I/O on them:

    binmode(STDIN);
    binmode(STDOUT);
    while (<STDIN>) { print }

Passing sysopen a non-standard flag option will also open the file in binary mode on those systems that support it. This is the equivalent of opening the file normally, then calling binmode on the handle.

    sysopen(BINDAT, "records.data", O_RDWR | O_BINARY)
        || die "can't open records.data: $!";

Now you can use read and print on that handle without worrying about the non-standard system I/O library breaking your data. It's not a pretty picture, but then, legacy systems seldom are. CP/M will be with us until the end of days, and after.

On systems with exotic I/O systems, it turns out that, astonishingly enough, even unbuffered I/O using sysread and syswrite might do sneaky data mutilation behind your back.

    while (sysread(WHENCE, $buf, 1024)) {
        syswrite(WHITHER, $buf, length($buf));
    }

Depending on the vicissitudes of your runtime system, even these calls may need binmode or O_BINARY first. Systems known to be free of such difficulties include Unix, the Mac OS, Plan 9, and Inferno.

File Locking

In a multitasking environment, you may need to be careful not to collide with other processes who want to do I/O on the same files as you are working on. You'll often need shared or exclusive locks on files for reading and writing respectively. You might just pretend that only exclusive locks exist.

Never use the existence of a file -e $file as a locking indication, because there is a race condition between the test for the existence of the file and its creation. It's possible for another process to create a file in the slice of time between your existence check and your attempt to create the file. Atomicity is critical.

Perl's most portable locking interface is via the flock function, whose simplicity is emulated on systems that don't directly support it such as SysV or Windows. The underlying semantics may affect how it all works, so you should learn how flock is implemented on your system's port of Perl.

File locking does not lock out another process that would like to do I/O. A file lock only locks out others trying to get a lock, not processes trying to do I/O. Because locks are advisory, if one process uses locking and another doesn't, all bets are off.

By default, the flock call will block until a lock is granted. A request for a shared lock will be granted as soon as there is no exclusive locker. A request for an exclusive lock will be granted as soon as there is no locker of any kind. Locks are on file descriptors, not file names. You can't lock a file until you open it, and you can't hold on to a lock once the file has been closed.

Here's how to get a blocking shared lock on a file, typically used for reading:

    use 5.004;
    use Fcntl qw(:DEFAULT :flock);
    open(FH, "< filename")  or die "can't open filename: $!";
    flock(FH, LOCK_SH)      or die "can't lock filename: $!";
    # now read from FH

You can get a non-blocking lock by using LOCK_NB.

    flock(FH, LOCK_SH | LOCK_NB)
        or die "can't lock filename: $!";

This can be useful for producing more user-friendly behaviour by warning if you're going to be blocking:

    use 5.004;
    use Fcntl qw(:DEFAULT :flock);
    open(FH, "< filename")  or die "can't open filename: $!";
    unless (flock(FH, LOCK_SH | LOCK_NB)) {
        $| = 1;
        print "Waiting for lock...";
        flock(FH, LOCK_SH)  or die "can't lock filename: $!";
        print "got it.\n"
    }
    # now read from FH

To get an exclusive lock, typically used for writing, you have to be careful. We sysopen the file so it can be locked before it gets emptied. You can get a nonblocking version using LOCK_EX | LOCK_NB.

    use 5.004;
    use Fcntl qw(:DEFAULT :flock);
    sysopen(FH, "filename", O_WRONLY | O_CREAT)
        or die "can't open filename: $!";
    flock(FH, LOCK_EX)
        or die "can't lock filename: $!";
    truncate(FH, 0)
        or die "can't truncate filename: $!";
    # now write to FH

Finally, due to the uncounted millions who cannot be dissuaded from wasting cycles on useless vanity devices called hit counters, here's how to increment a number in a file safely:

    use Fcntl qw(:DEFAULT :flock);

    sysopen(FH, "numfile", O_RDWR | O_CREAT)
        or die "can't open numfile: $!";
    # autoflush FH
    $ofh = select(FH); $| = 1; select ($ofh);
    flock(FH, LOCK_EX)
        or die "can't write-lock numfile: $!";

    $num = <FH> || 0;
    seek(FH, 0, 0)
        or die "can't rewind numfile : $!";
    print FH $num+1, "\n"
        or die "can't write numfile: $!";

    truncate(FH, tell(FH))
        or die "can't truncate numfile: $!";
    close(FH)
        or die "can't close numfile: $!";

IO Layers

In Perl 5.8.0 a new I/O framework called "PerlIO" was introduced. This is a new "plumbing" for all the I/O happening in Perl; for the most part everything will work just as it did, but PerlIO also brought in some new features such as the ability to think of I/O as "layers". One I/O layer may in addition to just moving the data also do transformations on the data. Such transformations may include compression and decompression, encryption and decryption, and transforming between various character encodings.

Full discussion about the features of PerlIO is out of scope for this tutorial, but here is how to recognize the layers being used:

  • The three-(or more)-argument form of open is being used and the second argument contains something else in addition to the usual '<', '>', '>>', '|' and their variants, for example:

        open(my $fh, "<:utf8", $fn);

  • The two-argument form of binmode is being used, for example

        binmode($fh, ":encoding(utf16)");

For more detailed discussion about PerlIO see the PerlIO manpage; for more detailed discussion about Unicode and I/O see the perluniintro manpage.

SEE ALSO

The open and sysopen functions in perlfunc(1); the system open(2), dup(2), fopen(3), and fdopen(3) manpages; the POSIX documentation.

AUTHOR and COPYRIGHT

Copyright 1998 Tom Christiansen.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in these files are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

HISTORY

First release: Sat Jan 9 08:09:11 MST 1999


perlport - Writing portable Perl

  • ISSUES
    • Newlines
    • Numbers endianness and Width
    • Files and Filesystems
    • System Interaction
    • Command names versus file pathnames
    • Networking
    • Interprocess Communication (IPC)
    • External Subroutines (XS)
    • Standard Modules
    • Time and Date
    • Character sets and character encoding
    • Internationalisation
    • System Resources
    • Security
    • Style
  • CPAN Testers
  • PLATFORMS
    • Unix
    • DOS and Derivatives
    • Mac OS
    • VMS
    • VOS
    • EBCDIC Platforms
    • Acorn RISC OS
    • Other perls
  • FUNCTION IMPLEMENTATIONS
    • Alphabetical Listing of Perl Functions
  • Supported Platforms
  • SEE ALSO
  • AUTHORS / CONTRIBUTORS

NAME

perlport - Writing portable Perl

DESCRIPTION

Perl runs on numerous operating systems. While most of them share much in common, they also have their own unique features.

This document is meant to help you to find out what constitutes portable Perl code. That way once you make a decision to write portably, you know where the lines are drawn, and you can stay within them.

There is a tradeoff between taking full advantage of one particular type of computer and taking advantage of a full range of them. Naturally, as you broaden your range and become more diverse, the common factors drop, and you are left with an increasingly smaller area of common ground in which you can operate to accomplish a particular task. Thus, when you begin attacking a problem, it is important to consider under which part of the tradeoff curve you want to operate. Specifically, you must decide whether it is important that the task that you are coding have the full generality of being portable, or whether to just get the job done right now. This is the hardest choice to be made. The rest is easy, because Perl provides many choices, whichever way you want to approach your problem.

Looking at it another way, writing portable code is usually about willfully limiting your available choices. Naturally, it takes discipline and sacrifice to do that. The product of portability and convenience may be a constant. You have been warned.

Be aware of two important points:

Not all Perl programs have to be portable

There is no reason you should not use Perl as a language to glue Unix tools together, or to prototype a Macintosh application, or to manage the Windows registry. If it makes no sense to aim for portability for one reason or another in a given program, then don't bother.

Nearly all of Perl already is portable

Don't be fooled into thinking that it is hard to create portable Perl code. It isn't. Perl tries its level-best to bridge the gaps between what's available on different platforms, and all the means available to use those features. Thus almost all Perl code runs on any machine without modification. But there are some significant issues in writing portable code, and this document is entirely about those issues.

Here's the general rule: When you approach a task commonly done using a whole range of platforms, think about writing portable code. That way, you don't sacrifice much by way of the implementation choices you can avail yourself of, and at the same time you can give your users lots of platform choices. On the other hand, when you have to take advantage of some unique feature of a particular platform, as is often the case with systems programming (whether for Unix, Windows, Mac OS, VMS, etc.), consider writing platform-specific code.

When the code will run on only two or three operating systems, you may need to consider only the differences of those particular systems. The important thing is to decide where the code will run and to be deliberate in your decision.

The material below is separated into three main sections: main issues of portability (ISSUES), platform-specific issues (PLATFORMS), and built-in perl functions that behave differently on various ports (FUNCTION IMPLEMENTATIONS).

This information should not be considered complete; it includes possibly transient information about idiosyncrasies of some of the ports, almost all of which are in a state of constant evolution. Thus, this material should be considered a perpetual work in progress (<IMG SRC="yellow_sign.gif" ALT="Under Construction">).

ISSUES

Newlines

In most operating systems, lines in files are terminated by newlines. Just what is used as a newline may vary from OS to OS. Unix traditionally uses \012, one type of DOSish I/O uses \015\012, and Mac OS uses \015.

Perl uses \n to represent the "logical" newline, where what is logical may depend on the platform in use. In MacPerl, \n always means \015. In DOSish perls, \n usually means \012, but when accessing a file in "text" mode, STDIO translates it to (or from) \015\012, depending on whether you're reading or writing. Unix does the same thing on ttys in canonical mode. \015\012 is commonly referred to as CRLF.

A common cause of unportable programs is the misuse of chop() to trim newlines:

    # XXX UNPORTABLE!
    while(<FILE>) {
        chop;
        @array = split(/:/);
        #...
    }

You can get away with this on Unix and Mac OS (they have a single character end-of-line), but the same program will break under DOSish perls because you're only chop()ing half the end-of-line. Instead, chomp() should be used to trim newlines. The the Dunce::Files manpage module can help audit your code for misuses of chop().

When dealing with binary files (or text files in binary mode) be sure to explicitly set $/ to the appropriate value for your file format before using chomp().

Because of the "text" mode translation, DOSish perls have limitations in using seek and tell on a file accessed in "text" mode. Stick to seek-ing to locations you got from tell (and no others), and you are usually free to use seek and tell even in "text" mode. Using seek or tell or other file operations may be non-portable. If you use binmode on a file, however, you can usually seek and tell with arbitrary values in safety.

A common misconception in socket programming is that \n eq \012 everywhere. When using protocols such as common Internet protocols, \012 and \015 are called for specifically, and the values of the logical \n and \r (carriage return) are not reliable.

    print SOCKET "Hi there, client!\r\n";      # WRONG
    print SOCKET "Hi there, client!\015\012";  # RIGHT

However, using \015\012 (or \cM\cJ, or \x0D\x0A) can be tedious and unsightly, as well as confusing to those maintaining the code. As such, the Socket module supplies the Right Thing for those who want it.

    use Socket qw(:DEFAULT :crlf);
    print SOCKET "Hi there, client!$CRLF"      # RIGHT

When reading from a socket, remember that the default input record separator $/ is \n, but robust socket code will recognize as either \012 or \015\012 as end of line:

    while (<SOCKET>) {
        # ...
    }

Because both CRLF and LF end in LF, the input record separator can be set to LF and any CR stripped later. Better to write:

    use Socket qw(:DEFAULT :crlf);
    local($/) = LF;      # not needed if $/ is already \012

    while (<SOCKET>) {
        s/$CR?$LF/\n/;   # not sure if socket uses LF or CRLF, OK
    #   s/\015?\012/\n/; # same thing
    }

This example is preferred over the previous one--even for Unix platforms--because now any \015's (\cM's) are stripped out (and there was much rejoicing).

Similarly, functions that return text data--such as a function that fetches a web page--should sometimes translate newlines before returning the data, if they've not yet been translated to the local newline representation. A single line of code will often suffice:

    $data =~ s/\015?\012/\n/g;
    return $data;

Some of this may be confusing. Here's a handy reference to the ASCII CR and LF characters. You can print it out and stick it in your wallet.

    LF  eq  \012  eq  \x0A  eq  \cJ  eq  chr(10)  eq  ASCII 10
    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  ASCII 13
             | Unix | DOS  | Mac  |
        ---------------------------
        \n   |  LF  |  LF  |  CR  |
        \r   |  CR  |  CR  |  LF  |
        \n * |  LF  | CRLF |  CR  |
        \r * |  CR  |  CR  |  LF  |
        ---------------------------
        * text-mode STDIO

The Unix column assumes that you are not accessing a serial line (like a tty) in canonical mode. If you are, then CR on input becomes "\n", and "\n" on output becomes CRLF.

These are just the most common definitions of \n and \r in Perl. There may well be others. For example, on an EBCDIC implementation such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based) the above material is similar to "Unix" but the code numbers change:

    LF  eq  \025  eq  \x15  eq  \cU  eq  chr(21)  eq  CP-1047 21
    LF  eq  \045  eq  \x25  eq           chr(37)  eq  CP-0037 37
    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-1047 13
    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-0037 13
             | z/OS | OS/400 |
        ----------------------
        \n   |  LF  |  LF    |
        \r   |  CR  |  CR    |
        \n * |  LF  |  LF    |
        \r * |  CR  |  CR    |
        ----------------------
        * text-mode STDIO

Numbers endianness and Width

Different CPUs store integers and floating point numbers in different orders (called endianness) and widths (32-bit and 64-bit being the most common today). This affects your programs when they attempt to transfer numbers in binary format from one CPU architecture to another, usually either "live" via network connection, or by storing the numbers to secondary storage such as a disk file or tape.

Conflicting storage orders make utter mess out of the numbers. If a little-endian host (Intel, VAX) stores 0x12345678 (305419896 in decimal), a big-endian host (Motorola, Sparc, PA) reads it as 0x78563412 (2018915346 in decimal). Alpha and MIPS can be either: Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode. To avoid this problem in network (socket) connections use the pack and unpack formats n and N, the "network" orders. These are guaranteed to be portable.

As of perl 5.8.5, you can also use the > and < modifiers to force big- or little-endian byte-order. This is useful if you want to store signed integers or 64-bit integers, for example.

You can explore the endianness of your platform by unpacking a data structure packed in native format such as:

    print unpack("h*", pack("s2", 1, 2)), "\n";
    # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
    # '00100020' on e.g. Motorola 68040

If you need to distinguish between endian architectures you could use either of the variables set like so:

    $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
    $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;

Differing widths can cause truncation even between platforms of equal endianness. The platform of shorter width loses the upper parts of the number. There is no good solution for this problem except to avoid transferring or storing raw binary numbers.

One can circumnavigate both these problems in two ways. Either transfer and store numbers always in text format, instead of raw binary, or else consider using modules like Data::Dumper (included in the standard distribution as of Perl 5.005) and Storable (included as of perl 5.8). Keeping all data as text significantly simplifies matters.

The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's how far EBCDIC, or more precisely UTF-EBCDIC will go.

Files and Filesystems

Most platforms these days structure files in a hierarchical fashion. So, it is reasonably safe to assume that all platforms support the notion of a "path" to uniquely identify a file on the system. How that path is really written, though, differs considerably.

Although similar, file path specifications differ between Unix, Windows, Mac OS, OS/2, VMS, VOS, RISC OS, and probably others. Unix, for example, is one of the few OSes that has the elegant idea of a single root directory.

DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with / as path separator, or in their own idiosyncratic ways (such as having several root directories and various "unrooted" device files such NIL: and LPT:).

Mac OS uses : as a path separator instead of /.

The filesystem may support neither hard links (link) nor symbolic links (symlink, readlink, lstat).

The filesystem may support neither access timestamp nor change timestamp (meaning that about the only portable timestamp is the modification timestamp), or one second granularity of any timestamps (e.g. the FAT filesystem limits the time granularity to two seconds).

The "inode change timestamp" (the -C filetest) may really be the "creation timestamp" (which it is not in UNIX).

VOS perl can emulate Unix filenames with / as path separator. The native pathname characters greater-than, less-than, number-sign, and percent-sign are always accepted.

RISC OS perl can emulate Unix filenames with / as path separator, or go native and use . for path separator and : to signal filesystems and disk names.

Don't assume UNIX filesystem access semantics: that read, write, and execute are all the permissions there are, and even if they exist, that their semantics (for example what do r, w, and x mean on a directory) are the UNIX ones. The various UNIX/POSIX compatibility layers usually try to make interfaces like chmod() work, but sometimes there simply is no good mapping.

If all this is intimidating, have no (well, maybe only a little) fear. There are modules that can help. The File::Spec modules provide methods to do the Right Thing on whatever platform happens to be running the program.

    use File::Spec::Functions;
    chdir(updir());        # go up one directory
    $file = catfile(curdir(), 'temp', 'file.txt');
    # on Unix and Win32, './temp/file.txt'
    # on Mac OS, ':temp:file.txt'
    # on VMS, '[.temp]file.txt'

File::Spec is available in the standard distribution as of version 5.004_05. File::Spec::Functions is only in File::Spec 0.7 and later, and some versions of perl come with version 0.6. If File::Spec is not updated to 0.7 or later, you must use the object-oriented interface from File::Spec (or upgrade File::Spec).

In general, production code should not have file paths hardcoded. Making them user-supplied or read from a configuration file is better, keeping in mind that file path syntax varies on different machines.

This is especially noticeable in scripts like Makefiles and test suites, which often assume / as a path separator for subdirectories.

Also of use is File::Basename from the standard distribution, which splits a pathname into pieces (base filename, full path to directory, and file suffix).

Even when on a single platform (if you can call Unix a single platform), remember not to count on the existence or the contents of particular system-specific files or directories, like /etc/passwd, /etc/sendmail.conf, /etc/resolv.conf, or even /tmp/. For example, /etc/passwd may exist but not contain the encrypted passwords, because the system is using some form of enhanced security. Or it may not contain all the accounts, because the system is using NIS. If code does need to rely on such a file, include a description of the file and its format in the code's documentation, then make it easy for the user to override the default location of the file.

Don't assume a text file will end with a newline. They should, but people forget.

Do not have two files or directories of the same name with different case, like test.pl and Test.pl, as many platforms have case-insensitive (or at least case-forgiving) filenames. Also, try not to have non-word characters (except for .) in the names, and keep them to the 8.3 convention, for maximum portability, onerous a burden though this may appear.

Likewise, when using the AutoSplit module, try to keep your functions to 8.3 naming and case-insensitive conventions; or, at the least, make it so the resulting files have a unique (case-insensitively) first 8 characters.

Whitespace in filenames is tolerated on most systems, but not all, and even on systems where it might be tolerated, some utilities might become confused by such whitespace.

Many systems (DOS, VMS) cannot have more than one . in their filenames.

Don't assume > won't be the first character of a filename. Always use < explicitly to open a file for reading, or even better, use the three-arg version of open, unless you want the user to be able to specify a pipe open.

    open(FILE, '<', $existing_file) or die $!;

If filenames might use strange characters, it is safest to open it with sysopen instead of open. open is magic and can translate characters like >, <, and |, which may be the wrong thing to do. (Sometimes, though, it's the right thing.) Three-arg open can also help protect against this translation in cases where it is undesirable.

Don't use : as a part of a filename since many systems use that for their own semantics (Mac OS Classic for separating pathname components, many networking schemes and utilities for separating the nodename and the pathname, and so on). For the same reasons, avoid @, ; and |.

Don't assume that in pathnames you can collapse two leading slashes // into one: some networking and clustering filesystems have special semantics for that. Let the operating system to sort it out.

The portable filename characters as defined by ANSI C are

 a b c d e f g h i j k l m n o p q r t u v w x y z
 A B C D E F G H I J K L M N O P Q R T U V W X Y Z
 0 1 2 3 4 5 6 7 8 9
 . _ -

and the "-" shouldn't be the first character. If you want to be hypercorrect, stay case-insensitive and within the 8.3 naming convention (all the files and directories have to be unique within one directory if their names are lowercased and truncated to eight characters before the ., if any, and to three characters after the ., if any). (And do not use .s in directory names.)

System Interaction

Not all platforms provide a command line. These are usually platforms that rely primarily on a Graphical User Interface (GUI) for user interaction. A program requiring a command line interface might not work everywhere. This is probably for the user of the program to deal with, so don't stay up late worrying about it.

Some platforms can't delete or rename files held open by the system, this limitation may also apply to changing filesystem metainformation like file permissions or owners. Remember to close files when you are done with them. Don't unlink or rename an open file. Don't tie or open a file already tied or opened; untie or close it first.

Don't open the same file more than once at a time for writing, as some operating systems put mandatory locks on such files.

Don't assume that write/modify permission on a directory gives the right to add or delete files/directories in that directory. That is filesystem specific: in some filesystems you need write/modify permission also (or even just) in the file/directory itself. In some filesystems (AFS, DFS) the permission to add/delete directory entries is a completely separate permission.

Don't assume that a single unlink completely gets rid of the file: some filesystems (most notably the ones in VMS) have versioned filesystems, and unlink() removes only the most recent one (it doesn't remove all the versions because by default the native tools on those platforms remove just the most recent version, too). The portable idiom to remove all the versions of a file is

    1 while unlink "file";

This will terminate if the file is undeleteable for some reason (protected, not there, and so on).

Don't count on a specific environment variable existing in %ENV. Don't count on %ENV entries being case-sensitive, or even case-preserving. Don't try to clear %ENV by saying %ENV = ();, or, if you really have to, make it conditional on $^O ne 'VMS' since in VMS the %ENV table is much more than a per-process key-value string table.

Don't count on signals or %SIG for anything.

Don't count on filename globbing. Use opendir, readdir, and closedir instead.

Don't count on per-program environment variables, or per-program current directories.

Don't count on specific values of $!, neither numeric nor especially the strings values-- users may switch their locales causing error messages to be translated into their languages. If you can trust a POSIXish environment, you can portably use the symbols defined by the Errno module, like ENOENT. And don't trust on the values of $! at all except immediately after a failed system call.

Command names versus file pathnames

Don't assume that the name used to invoke a command or program with system or exec can also be used to test for the existence of the file that holds the executable code for that command or program. First, many systems have "internal" commands that are built-in to the shell or OS and while these commands can be invoked, there is no corresponding file. Second, some operating systems (e.g., Cygwin, DJGPP, OS/2, and VOS) have required suffixes for executable files; these suffixes are generally permitted on the command name but are not required. Thus, a command like "perl" might exist in a file named "perl", "perl.exe", or "perl.pm", depending on the operating system. The variable "_exe" in the Config module holds the executable suffix, if any. Third, the VMS port carefully sets up $^X and $Config{perlpath} so that no further processing is required. This is just as well, because the matching regular expression used below would then have to deal with a possible trailing version number in the VMS file name.

To convert $^X to a file pathname, taking account of the requirements of the various operating system possibilities, say:

  use Config;
  $thisperl = $^X;
  if ($^O ne 'VMS')
     {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}

To convert $Config{perlpath} to a file pathname, say:

  use Config;
  $thisperl = $Config{perlpath};
  if ($^O ne 'VMS')
     {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}

Networking

Don't assume that you can reach the public Internet.

Don't assume that there is only one way to get through firewalls to the public Internet.

Don't assume that you can reach outside world through any other port than 80, or some web proxy. ftp is blocked by many firewalls.

Don't assume that you can send email by connecting to the local SMTP port.

Don't assume that you can reach yourself or any node by the name 'localhost'. The same goes for '127.0.0.1'. You will have to try both.

Don't assume that the host has only one network card, or that it can't bind to many virtual IP addresses.

Don't assume a particular network device name.

Don't assume a particular set of ioctl()s will work.

Don't assume that you can ping hosts and get replies.

Don't assume that any particular port (service) will respond.

Don't assume that Sys::Hostname (or any other API or command) returns either a fully qualified hostname or a non-qualified hostname: it all depends on how the system had been configured. Also remember things like DHCP and NAT-- the hostname you get back might not be very useful.

All the above "don't":s may look daunting, and they are -- but the key is to degrade gracefully if one cannot reach the particular network service one wants. Croaking or hanging do not look very professional.

Interprocess Communication (IPC)

In general, don't directly access the system in code meant to be portable. That means, no system, exec, fork, pipe, ``, qx//, open with a |, nor any of the other things that makes being a perl hacker worth being.

Commands that launch external processes are generally supported on most platforms (though many of them do not support any type of forking). The problem with using them arises from what you invoke them on. External tools are often named differently on different platforms, may not be available in the same location, might accept different arguments, can behave differently, and often present their results in a platform-dependent way. Thus, you should seldom depend on them to produce consistent results. (Then again, if you're calling netstat -a, you probably don't expect it to run on both Unix and CP/M.)

One especially common bit of Perl code is opening a pipe to sendmail:

    open(MAIL, '|/usr/lib/sendmail -t')
        or die "cannot fork sendmail: $!";

This is fine for systems programming when sendmail is known to be available. But it is not fine for many non-Unix systems, and even some Unix systems that may not have sendmail installed. If a portable solution is needed, see the various distributions on CPAN that deal with it. Mail::Mailer and Mail::Send in the MailTools distribution are commonly used, and provide several mailing methods, including mail, sendmail, and direct SMTP (via Net::SMTP) if a mail transfer agent is not available. Mail::Sendmail is a standalone module that provides simple, platform-independent mailing.

The Unix System V IPC (msg*(), sem*(), shm*()) is not available even on all Unix platforms.

Do not use either the bare result of pack("N", 10, 20, 30, 40) or bare v-strings (such as v10.20.30.40) to represent IPv4 addresses: both forms just pack the four bytes into network order. That this would be equal to the C language in_addr struct (which is what the socket code internally uses) is not guaranteed. To be portable use the routines of the Socket extension, such as inet_aton(), inet_ntoa(), and sockaddr_in().

The rule of thumb for portable code is: Do it all in portable Perl, or use a module (that may internally implement it with platform-specific code, but expose a common interface).

External Subroutines (XS)

XS code can usually be made to work with any platform, but dependent libraries, header files, etc., might not be readily available or portable, or the XS code itself might be platform-specific, just as Perl code might be. If the libraries and headers are portable, then it is normally reasonable to make sure the XS code is portable, too.

A different type of portability issue arises when writing XS code: availability of a C compiler on the end-user's system. C brings with it its own portability issues, and writing XS code will expose you to some of those. Writing purely in Perl is an easier way to achieve portability.

Standard Modules

In general, the standard modules work across platforms. Notable exceptions are the CPAN module (which currently makes connections to external programs that may not be available), platform-specific modules (like ExtUtils::MM_VMS), and DBM modules.

There is no one DBM module available on all platforms. SDBM_File and the others are generally available on all Unix and DOSish ports, but not in MacPerl, where only NBDM_File and DB_File are available.

The good news is that at least some DBM module should be available, and AnyDBM_File will use whichever module it can find. Of course, then the code needs to be fairly strict, dropping to the greatest common factor (e.g., not exceeding 1K for each record), so that it will work with any DBM module. See the AnyDBM_File manpage for more details.

Time and Date

The system's notion of time of day and calendar date is controlled in widely different ways. Don't assume the timezone is stored in $ENV{TZ}, and even if it is, don't assume that you can control the timezone through that variable. Don't assume anything about the three-letter timezone abbreviations (for example that MST would be the Mountain Standard Time, it's been known to stand for Moscow Standard Time). If you need to use timezones, express them in some unambiguous format like the exact number of minutes offset from UTC, or the POSIX timezone format.

Don't assume that the epoch starts at 00:00:00, January 1, 1970, because that is OS- and implementation-specific. It is better to store a date in an unambiguous representation. The ISO 8601 standard defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH-MM-SS (that's a literal "T" separating the date from the time). Please do use the ISO 8601 instead of making us to guess what date 02/03/04 might be. ISO 8601 even sorts nicely as-is. A text representation (like "1987-12-18") can be easily converted into an OS-specific value using a module like Date::Parse. An array of values, such as those returned by localtime, can be converted to an OS-specific representation using Time::Local.

When calculating specific times, such as for tests in time or date modules, it may be appropriate to calculate an offset for the epoch.

    require Time::Local;
    $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);

The value for $offset in Unix will be 0, but in Mac OS will be some large number. $offset can then be added to a Unix time value to get what should be the proper value on any system.

On Windows (at least), you shouldn't pass a negative value to gmtime or localtime.

Character sets and character encoding

Assume very little about character sets.

Assume nothing about numerical values (ord, chr) of characters. Do not use explicit code point ranges (like \xHH-\xHH); use for example symbolic character classes like [:print:].

Do not assume that the alphabetic characters are encoded contiguously (in the numeric sense). There may be gaps.

Do not assume anything about the ordering of the characters. The lowercase letters may come before or after the uppercase letters; the lowercase and uppercase may be interlaced so that both "a" and "A" come before "b"; the accented and other international characters may be interlaced so that ä comes before "b".

Internationalisation

If you may assume POSIX (a rather large assumption), you may read more about the POSIX locale system from the perllocale manpage. The locale system at least attempts to make things a little bit more portable, or at least more convenient and native-friendly for non-English users. The system affects character sets and encoding, and date and time formatting--amongst other things.

If you really want to be international, you should consider Unicode. See the perluniintro manpage and the perlunicode manpage for more information.

If you want to use non-ASCII bytes (outside the bytes 0x00..0x7f) in the "source code" of your code, to be portable you have to be explicit about what bytes they are. Someone might for example be using your code under a UTF-8 locale, in which case random native bytes might be illegal ("Malformed UTF-8 ...") This means that for example embedding ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble later. If the bytes are native 8-bit bytes, you can use the bytes pragma. If the bytes are in a string (regular expression being a curious string), you can often also use the \xHH notation instead of embedding the bytes as-is. If they are in some particular legacy encoding (ether single-byte or something more complicated), you can use the encoding pragma. (If you want to write your code in UTF-8, you can use either the utf8 pragma, or the encoding pragma.) The bytes and utf8 pragmata are available since Perl 5.6.0, and the encoding pragma since Perl 5.8.0.

System Resources

If your code is destined for systems with severely constrained (or missing!) virtual memory systems then you want to be especially mindful of avoiding wasteful constructs such as:

    # NOTE: this is no longer "bad" in perl5.005
    for (0..10000000) {}                       # bad
    for (my $x = 0; $x <= 10000000; ++$x) {}   # good

    @lines = <VERY_LARGE_FILE>;                # bad

    while (<FILE>) {$file .= $_}               # sometimes bad
    $file = join('', <FILE>);                  # better

The last two constructs may appear unintuitive to most people. The first repeatedly grows a string, whereas the second allocates a large chunk of memory in one go. On some systems, the second is more efficient that the first.

Security

Most multi-user platforms provide basic levels of security, usually implemented at the filesystem level. Some, however, do not-- unfortunately. Thus the notion of user id, or "home" directory, or even the state of being logged-in, may be unrecognizable on many platforms. If you write programs that are security-conscious, it is usually best to know what type of system you will be running under so that you can write code explicitly for that platform (or class of platforms).

Don't assume the UNIX filesystem access semantics: the operating system or the filesystem may be using some ACL systems, which are richer languages than the usual rwx. Even if the rwx exist, their semantics might be different.

(From security viewpoint testing for permissions before attempting to do something is silly anyway: if one tries this, there is potential for race conditions-- someone or something might change the permissions between the permissions check and the actual operation. Just try the operation.)

Don't assume the UNIX user and group semantics: especially, don't expect the $< and $> (or the $( and $)) to work for switching identities (or memberships).

Don't assume set-uid and set-gid semantics. (And even if you do, think twice: set-uid and set-gid are a known can of security worms.)

Style

For those times when it is necessary to have platform-specific code, consider keeping the platform-specific code in one place, making porting to other platforms easier. Use the Config module and the special variable $^O to differentiate platforms, as described in PLATFORMS.

Be careful in the tests you supply with your module or programs. Module code may be fully portable, but its tests might not be. This often happens when tests spawn off other processes or call external programs to aid in the testing, or when (as noted above) the tests assume certain things about the filesystem and paths. Be careful not to depend on a specific output style for errors, such as when checking $! after a failed system call. Using $! for anything else than displaying it as output is doubtful (though see the Errno module for testing reasonably portably for error value). Some platforms expect a certain output format, and Perl on those platforms may have been adjusted accordingly. Most specifically, don't anchor a regex when testing an error value.

CPAN Testers

Modules uploaded to CPAN are tested by a variety of volunteers on different platforms. These CPAN testers are notified by mail of each new upload, and reply to the list with PASS, FAIL, NA (not applicable to this platform), or UNKNOWN (unknown), along with any relevant notations.

The purpose of the testing is twofold: one, to help developers fix any problems in their code that crop up because of lack of testing on other platforms; two, to provide users with information about whether a given module works on a given platform.

Also see:

  • Mailing list: cpan-testers@perl.org

  • Testing results: http://testers.cpan.org/

PLATFORMS

As of version 5.002, Perl is built with a $^O variable that indicates the operating system it was built on. This was implemented to help speed up code that would otherwise have to use Config and use the value of $Config{osname}. Of course, to get more detailed information about the system, looking into %Config is certainly recommended.

%Config cannot always be trusted, however, because it was built at compile time. If perl was built in one place, then transferred elsewhere, some values may be wrong. The values may even have been edited after the fact.

Unix

Perl works on a bewildering variety of Unix and Unix-like platforms (see e.g. most of the files in the hints/ directory in the source code kit). On most of these systems, the value of $^O (hence $Config{'osname'}, too) is determined either by lowercasing and stripping punctuation from the first field of the string returned by typing uname -a (or a similar command) at the shell prompt or by testing the file system for the presence of uniquely named files such as a kernel or header file. Here, for example, are a few of the more popular Unix flavors:

    uname         $^O        $Config{'archname'}
    --------------------------------------------
    AIX           aix        aix
    BSD/OS        bsdos      i386-bsdos
    Darwin        darwin     darwin
    dgux          dgux       AViiON-dgux
    DYNIX/ptx     dynixptx   i386-dynixptx
    FreeBSD       freebsd    freebsd-i386
    Linux         linux      arm-linux
    Linux         linux      i386-linux
    Linux         linux      i586-linux
    Linux         linux      ppc-linux
    HP-UX         hpux       PA-RISC1.1
    IRIX          irix       irix
    Mac OS X      darwin     darwin
    MachTen PPC   machten    powerpc-machten
    NeXT 3        next       next-fat
    NeXT 4        next       OPENSTEP-Mach
    openbsd       openbsd    i386-openbsd
    OSF1          dec_osf    alpha-dec_osf
    reliantunix-n svr4       RM400-svr4
    SCO_SV        sco_sv     i386-sco_sv
    SINIX-N       svr4       RM400-svr4
    sn4609        unicos     CRAY_C90-unicos
    sn6521        unicosmk   t3e-unicosmk
    sn9617        unicos     CRAY_J90-unicos
    SunOS         solaris    sun4-solaris
    SunOS         solaris    i86pc-solaris
    SunOS4        sunos      sun4-sunos

Because the value of $Config{archname} may depend on the hardware architecture, it can vary more than the value of $^O.

DOS and Derivatives

Perl has long been ported to Intel-style microcomputers running under systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can bring yourself to mention (except for Windows CE, if you count that). Users familiar with COMMAND.COM or CMD.EXE style shells should be aware that each of these file specifications may have subtle differences:

    $filespec0 = "c:/foo/bar/file.txt";
    $filespec1 = "c:\\foo\\bar\\file.txt";
    $filespec2 = 'c:\foo\bar\file.txt';
    $filespec3 = 'c:\\foo\\bar\\file.txt';

System calls accept either / or \ as the path separator. However, many command-line utilities of DOS vintage treat / as the option prefix, so may get confused by filenames containing /. Aside from calling any external programs, / will work just fine, and probably better, as it is more consistent with popular usage, and avoids the problem of remembering what to backwhack and what not to.

The DOS FAT filesystem can accommodate only "8.3" style filenames. Under the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT) filesystems you may have to be careful about case returned with functions like readdir or used with functions like open or opendir.

DOS also treats several filenames as special, such as AUX, PRN, NUL, CON, COM1, LPT1, LPT2, etc. Unfortunately, sometimes these filenames won't even work if you include an explicit directory prefix. It is best to avoid such filenames, if you want your code to be portable to DOS and its derivatives. It's hard to know what these all are, unfortunately.

Users of these operating systems may also wish to make use of scripts such as pl2bat.bat or pl2cmd to put wrappers around your scripts.

Newline (\n) is translated as \015\012 by STDIO when reading from and writing to files (see Newlines). binmode(FILEHANDLE) will keep \n translated as \012 for that filehandle. Since it is a no-op on other systems, binmode should be used for cross-platform code that deals with binary data. That's assuming you realize in advance that your data is in binary. General-purpose programs should often assume nothing about their data.

The $^O variable and the $Config{archname} values for various DOSish perls are as follows:

     OS            $^O      $Config{archname}   ID    Version
     --------------------------------------------------------
     MS-DOS        dos        ?
     PC-DOS        dos        ?
     OS/2          os2        ?
     Windows 3.1   ?          ?                 0      3 01
     Windows 95    MSWin32    MSWin32-x86       1      4 00
     Windows 98    MSWin32    MSWin32-x86       1      4 10
     Windows ME    MSWin32    MSWin32-x86       1      ?
     Windows NT    MSWin32    MSWin32-x86       2      4 xx
     Windows NT    MSWin32    MSWin32-ALPHA     2      4 xx
     Windows NT    MSWin32    MSWin32-ppc       2      4 xx
     Windows 2000  MSWin32    MSWin32-x86       2      5 00
     Windows XP    MSWin32    MSWin32-x86       2      5 01
     Windows 2003  MSWin32    MSWin32-x86       2      5 02
     Windows CE    MSWin32    ?                 3
     Cygwin        cygwin     cygwin

The various MSWin32 Perl's can distinguish the OS they are running on via the value of the fifth element of the list returned from Win32::GetOSVersion(). For example:

    if ($^O eq 'MSWin32') {
        my @os_version_info = Win32::GetOSVersion();
        print +('3.1','95','NT')[$os_version_info[4]],"\n";
    }

There are also Win32::IsWinNT() and Win32::IsWin95(), try perldoc Win32, and as of libwin32 0.19 (not part of the core Perl distribution) Win32::GetOSName(). The very portable POSIX::uname() will work too:

    c:\> perl -MPOSIX -we "print join '|', uname"
    Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86

Also see:

  • The djgpp environment for DOS, http://www.delorie.com/djgpp/ and the perldos manpage.

  • The EMX environment for DOS, OS/2, etc. emx@iaehv.nl, http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or ftp://hobbes.nmsu.edu/pub/os2/dev/emx/ Also the perlos2 manpage.

  • Build instructions for Win32 in the perlwin32 manpage, or under the Cygnus environment in the perlcygwin manpage.

  • The Win32::* modules in the Win32 manpage.

  • The ActiveState Pages, http://www.activestate.com/

  • The Cygwin environment for Win32; README.cygwin (installed as the perlcygwin manpage), http://www.cygwin.com/

  • The U/WIN environment for Win32, http://www.research.att.com/sw/tools/uwin/

  • Build instructions for OS/2, the perlos2 manpage

Mac OS

Any module requiring XS compilation is right out for most people, because MacPerl is built using non-free (and non-cheap!) compilers. Some XS modules that can work with MacPerl are built and distributed in binary form on CPAN.

Directories are specified as:

    volume:folder:file              for absolute pathnames
    volume:folder:                  for absolute pathnames
    :folder:file                    for relative pathnames
    :folder:                        for relative pathnames
    :file                           for relative pathnames
    file                            for relative pathnames

Files are stored in the directory in alphabetical order. Filenames are limited to 31 characters, and may include any character except for null and :, which is reserved as the path separator.

Instead of flock, see FSpSetFLock and FSpRstFLock in the Mac::Files module, or chmod(0444, ...) and chmod(0666, ...).

In the MacPerl application, you can't run a program from the command line; programs that expect @ARGV to be populated can be edited with something like the following, which brings up a dialog box asking for the command line arguments.

    if (!@ARGV) {
        @ARGV = split /\s+/, MacPerl::Ask('Arguments?');
    }

A MacPerl script saved as a "droplet" will populate @ARGV with the full pathnames of the files dropped onto the script.

Mac users can run programs under a type of command line interface under MPW (Macintosh Programmer's Workshop, a free development environment from Apple). MacPerl was first introduced as an MPW tool, and MPW can be used like a shell:

    perl myscript.plx some arguments

ToolServer is another app from Apple that provides access to MPW tools from MPW and the MacPerl app, which allows MacPerl programs to use system, backticks, and piped open.

"Mac OS" is the proper name for the operating system, but the value in $^O is "MacOS". To determine architecture, version, or whether the application or MPW tool version is running, check:

    $is_app    = $MacPerl::Version =~ /App/;
    $is_tool   = $MacPerl::Version =~ /MPW/;
    ($version) = $MacPerl::Version =~ /^(\S+)/;
    $is_ppc    = $MacPerl::Architecture eq 'MacPPC';
    $is_68k    = $MacPerl::Architecture eq 'Mac68K';

Mac OS X, based on NeXT's OpenStep OS, runs MacPerl natively, under the "Classic" environment. There is no "Carbon" version of MacPerl to run under the primary Mac OS X environment. Mac OS X and its Open Source version, Darwin, both run Unix perl natively.

Also see:

  • MacPerl Development, http://dev.macperl.org/ .

  • The MacPerl Pages, http://www.macperl.com/ .

  • The MacPerl mailing lists, http://lists.perl.org/ .

  • MPW, ftp://ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/

VMS

Perl on VMS is discussed in the perlvms manpage in the perl distribution. Perl on VMS can accept either VMS- or Unix-style file specifications as in either of the following:

    $ perl -ne "print if /perl_setup/i" SYS$LOGIN:LOGIN.COM
    $ perl -ne "print if /perl_setup/i" /sys$login/login.com

but not a mixture of both as in:

    $ perl -ne "print if /perl_setup/i" sys$login:/login.com
    Can't open sys$login:/login.com: file specification syntax error

Interacting with Perl from the Digital Command Language (DCL) shell often requires a different set of quotation marks than Unix shells do. For example:

    $ perl -e "print ""Hello, world.\n"""
    Hello, world.

There are several ways to wrap your perl scripts in DCL .COM files, if you are so inclined. For example:

    $ write sys$output "Hello from DCL!"
    $ if p1 .eqs. ""
    $ then perl -x 'f$environment("PROCEDURE")
    $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
    $ deck/dollars="__END__"
    #!/usr/bin/perl
    print "Hello from Perl!\n";

    __END__
    $ endif

Do take care with $ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT if your perl-in-DCL script expects to do things like $read = <STDIN>;.

Filenames are in the format "name.extension;version". The maximum length for filenames is 39 characters, and the maximum length for extensions is also 39 characters. Version is a number from 1 to 32767. Valid characters are /[A-Z0-9$_-]/.

VMS's RMS filesystem is case-insensitive and does not preserve case. readdir returns lowercased filenames, but specifying a file for opening remains case-insensitive. Files without extensions have a trailing period on them, so doing a readdir with a file named A.;5 will return a. (though that file could be opened with open(FH, 'A')).

RMS had an eight level limit on directory depths from any rooted logical (allowing 16 levels overall) prior to VMS 7.2. Hence PERL_ROOT:[LIB.2.3.4.5.6.7.8] is a valid directory specification but PERL_ROOT:[LIB.2.3.4.5.6.7.8.9] is not. Makefile.PL authors might have to take this into account, but at least they can refer to the former as /PERL_ROOT/lib/2/3/4/5/6/7/8/.

The VMS::Filespec module, which gets installed as part of the build process on VMS, is a pure Perl module that can easily be installed on non-VMS platforms and can be helpful for conversions to and from RMS native formats.

What \n represents depends on the type of file opened. It usually represents \012 but it could also be \015, \012, \015\012, \000, \040, or nothing depending on the file organization and record format. The VMS::Stdio module provides access to the special fopen() requirements of files with unusual attributes on VMS.

TCP/IP stacks are optional on VMS, so socket routines might not be implemented. UDP sockets may not be supported.

The value of $^O on OpenVMS is "VMS". To determine the architecture that you are running on without resorting to loading all of %Config you can examine the content of the @INC array like so:

    if (grep(/VMS_AXP/, @INC)) {
        print "I'm on Alpha!\n";

    } elsif (grep(/VMS_VAX/, @INC)) {
        print "I'm on VAX!\n";

    } else {
        print "I'm not so sure about where $^O is...\n";
    }

On VMS, perl determines the UTC offset from the SYS$TIMEZONE_DIFFERENTIAL logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00, calls to localtime are adjusted to count offsets from 01-JAN-1970 00:00:00.00, just like Unix.

Also see:

  • README.vms (installed as README_vms), the perlvms manpage

  • vmsperl list, majordomo@perl.org

    (Put the words subscribe vmsperl in message body.)

  • vmsperl on the web, http://www.sidhe.org/vmsperl/index.html

VOS

Perl on VOS is discussed in README.vos in the perl distribution (installed as the perlvos manpage). Perl on VOS can accept either VOS- or Unix-style file specifications as in either of the following:

    C<< $ perl -ne "print if /perl_setup/i" >system>notices >>
    C<< $ perl -ne "print if /perl_setup/i" /system/notices >>

or even a mixture of both as in:

    C<< $ perl -ne "print if /perl_setup/i" >system/notices >>

Even though VOS allows the slash character to appear in object names, because the VOS port of Perl interprets it as a pathname delimiting character, VOS files, directories, or links whose names contain a slash character cannot be processed. Such files must be renamed before they can be processed by Perl. Note that VOS limits file names to 32 or fewer characters.

Perl on VOS can be built using two different compilers and two different versions of the POSIX runtime. The recommended method for building full Perl is with the GNU C compiler and the generally-available version of VOS POSIX support. See README.vos (installed as the perlvos manpage) for restrictions that apply when Perl is built using the VOS Standard C compiler or the alpha version of VOS POSIX support.

The value of $^O on VOS is "VOS". To determine the architecture that you are running on without resorting to loading all of %Config you can examine the content of the @INC array like so:

    if ($^O =~ /VOS/) {
        print "I'm on a Stratus box!\n";
    } else {
        print "I'm not on a Stratus box!\n";
        die;
    }

    if (grep(/860/, @INC)) {
        print "This box is a Stratus XA/R!\n";

    } elsif (grep(/7100/, @INC)) {
        print "This box is a Stratus HP 7100 or 8xxx!\n";

    } elsif (grep(/8000/, @INC)) {
        print "This box is a Stratus HP 8xxx!\n";

    } else {
        print "This box is a Stratus 68K!\n";
    }

Also see:

  • README.vos (installed as the perlvos manpage)

  • The VOS mailing list.

    There is no specific mailing list for Perl on VOS. You can post comments to the comp.sys.stratus newsgroup, or subscribe to the general Stratus mailing list. Send a letter with "subscribe Info-Stratus" in the message body to majordomo@list.stratagy.com.

  • VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html

EBCDIC Platforms

Recent versions of Perl have been ported to platforms such as OS/400 on AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390 Mainframes. Such computers use EBCDIC character sets internally (usually Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390 systems). On the mainframe perl currently works under the "Unix system services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater). See the perlos390 manpage for details. Note that for OS/400 there is also a port of Perl 5.8.1/5.9.0 or later to the PASE which is ASCII-based (as opposed to ILE which is EBCDIC-based), see the perlos400 manpage.

As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix sub-systems do not support the #! shebang trick for script invocation. Hence, on OS/390 and VM/ESA perl scripts can be executed with a header similar to the following simple script:

    : # use perl
        eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
            if 0;
    #!/usr/local/bin/perl     # just a comment really

    print "Hello from perl!\n";

OS/390 will support the #! shebang trick in release 2.8 and beyond. Calls to system and backticks can use POSIX shell syntax on all S/390 systems.

On the AS/400, if PERL5 is in your library list, you may need to wrap your perl scripts in a CL procedure to invoke them like so:

    BEGIN
      CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
    ENDPGM

This will invoke the perl script hello.pl in the root of the QOpenSys file system. On the AS/400 calls to system or backticks must use CL syntax.

On these platforms, bear in mind that the EBCDIC character set may have an effect on what happens with some perl functions (such as chr, pack, print, printf, ord, sort, sprintf, unpack), as well as bit-fiddling with ASCII constants using operators like ^, & and |, not to mention dealing with socket interfaces to ASCII computers (see Newlines).

Fortunately, most web servers for the mainframe will correctly translate the \n in the following statement to its ASCII equivalent (\r is the same under both Unix and OS/390 & VM/ESA):

    print "Content-type: text/html\r\n\r\n";

The values of $^O on some of these platforms includes:

    uname         $^O        $Config{'archname'}
    --------------------------------------------
    OS/390        os390      os390
    OS400         os400      os400
    POSIX-BC      posix-bc   BS2000-posix-bc
    VM/ESA        vmesa      vmesa

Some simple tricks for determining if you are running on an EBCDIC platform could include any of the following (perhaps all):

    if ("\t" eq "\05")   { print "EBCDIC may be spoken here!\n"; }

    if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }

    if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }

One thing you may not want to rely on is the EBCDIC encoding of punctuation characters since these may differ from code page to code page (and once your module or script is rumoured to work with EBCDIC, folks will want it to work with all EBCDIC character sets).

Also see:

  • the perlos390 manpage, README.os390, perlbs2000, README.vmesa, the perlebcdic manpage.

  • The perl-mvs@perl.org list is for discussion of porting issues as well as general usage issues for all EBCDIC Perls. Send a message body of "subscribe perl-mvs" to majordomo@perl.org.

  • AS/400 Perl information at http://as400.rochester.ibm.com/ as well as on CPAN in the ports/ directory.

Acorn RISC OS

Because Acorns use ASCII with newlines (\n) in text files as \012 like Unix, and because Unix filename emulation is turned on by default, most simple scripts will probably work "out of the box". The native filesystem is modular, and individual filesystems are free to be case-sensitive or insensitive, and are usually case-preserving. Some native filesystems have name length limits, which file and directory names are silently truncated to fit. Scripts should be aware that the standard filesystem currently has a name length limit of 10 characters, with up to 77 items in a directory, but other filesystems may not impose such limitations.

Native filenames are of the form

    Filesystem#Special_Field::DiskName.$.Directory.Directory.File

where

    Special_Field is not usually present, but may contain . and $ .
    Filesystem =~ m|[A-Za-z0-9_]|
    DsicName   =~ m|[A-Za-z0-9_/]|
    $ represents the root directory
    . is the path separator
    @ is the current directory (per filesystem but machine global)
    ^ is the parent directory
    Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+|

The default filename translation is roughly tr|/.|./|;

Note that "ADFS::HardDisk.$.File" ne 'ADFS::HardDisk.$.File' and that the second stage of $ interpolation in regular expressions will fall foul of the $. if scripts are not careful.

Logical paths specified by system variables containing comma-separated search lists are also allowed; hence System:Modules is a valid filename, and the filesystem will prefix Modules with each section of System$Path until a name is made that points to an object on disk. Writing to a new file System:Modules would be allowed only if System$Path contains a single item list. The filesystem will also expand system variables in filenames if enclosed in angle brackets, so <System$Dir>.Modules would look for the file $ENV{'System$Dir'} . 'Modules'. The obvious implication of this is that fully qualified filenames can start with <> and should be protected when open is used for input.

Because . was in use as a directory separator and filenames could not be assumed to be unique after 10 characters, Acorn implemented the C compiler to strip the trailing .c .h .s and .o suffix from filenames specified in source code and store the respective files in subdirectories named after the suffix. Hence files are translated:

    foo.h           h.foo
    C:foo.h         C:h.foo        (logical path variable)
    sys/os.h        sys.h.os       (C compiler groks Unix-speak)
    10charname.c    c.10charname
    10charname.o    o.10charname
    11charname_.c   c.11charname   (assuming filesystem truncates at 10)

The Unix emulation library's translation of filenames to native assumes that this sort of translation is required, and it allows a user-defined list of known suffixes that it will transpose in this fashion. This may seem transparent, but consider that with these rules foo/bar/baz.h and foo/bar/h/baz both map to foo.bar.h.baz, and that readdir and glob cannot and do not attempt to emulate the reverse mapping. Other .'s in filenames are translated to /.

As implied above, the environment accessed through %ENV is global, and the convention is that program specific environment variables are of the form Program$Name. Each filesystem maintains a current directory, and the current filesystem's current directory is the global current directory. Consequently, sociable programs don't change the current directory but rely on full pathnames, and programs (and Makefiles) cannot assume that they can spawn a child process which can change the current directory without affecting its parent (and everyone else for that matter).

Because native operating system filehandles are global and are currently allocated down from 255, with 0 being a reserved value, the Unix emulation library emulates Unix filehandles. Consequently, you can't rely on passing STDIN, STDOUT, or STDERR to your children.

The desire of users to express filenames of the form <Foo$Dir>.Bar on the command line unquoted causes problems, too: `` command output capture has to perform a guessing game. It assumes that a string <[^<>]+\$[^<>]> is a reference to an environment variable, whereas anything else involving < or > is redirection, and generally manages to be 99% right. Of course, the problem remains that scripts cannot rely on any Unix tools being available, or that any tools found have Unix-like command line arguments.

Extensions and XS are, in theory, buildable by anyone using free tools. In practice, many don't, as users of the Acorn platform are used to binary distributions. MakeMaker does run, but no available make currently copes with MakeMaker's makefiles; even if and when this should be fixed, the lack of a Unix-like shell will cause problems with makefile rules, especially lines of the form cd sdbm && make all, and anything using quoting.

"RISC OS" is the proper name for the operating system, but the value in $^O is "riscos" (because we don't like shouting).

Other perls

Perl has been ported to many platforms that do not fit into any of the categories listed above. Some, such as AmigaOS, Atari MiNT, BeOS, HP MPE/iX, QNX, Plan 9, and VOS, have been well-integrated into the standard Perl source code kit. You may need to see the ports/ directory on CPAN for information, and possibly binaries, for the likes of: aos, Atari ST, lynxos, riscos, Novell Netware, Tandem Guardian, etc. (Yes, we know that some of these OSes may fall under the Unix category, but we are not a standards body.)

Some approximate operating system names and their $^O values in the "OTHER" category include:

    OS            $^O        $Config{'archname'}
    ------------------------------------------
    Amiga DOS     amigaos    m68k-amigos
    BeOS          beos
    MPE/iX        mpeix      PA-RISC1.1

See also:

  • Amiga, README.amiga (installed as the perlamiga manpage).

  • Atari, README.mint and Guido Flohr's web page http://stud.uni-sb.de/~gufl0000/

  • Be OS, README.beos

  • HP 300 MPE/iX, README.mpeix and Mark Bixby's web page http://www.bixby.org/mark/perlix.html

  • A free perl5-based PERL.NLM for Novell Netware is available in precompiled binary and source code form from http://www.novell.com/ as well as from CPAN.

  • Plan 9, README.plan9

FUNCTION IMPLEMENTATIONS

Listed below are functions that are either completely unimplemented or else have been implemented differently on various platforms. Following each description will be, in parentheses, a list of platforms that the description applies to.

The list may well be incomplete, or even wrong in some places. When in doubt, consult the platform-specific README files in the Perl source distribution, and any other documentation resources accompanying a given port.

Be aware, moreover, that even among Unix-ish systems there are variations.

For many functions, you can also query %Config, exported by default from the Config module. For example, to check whether the platform has the lstat call, check $Config{d_lstat}. See the Config manpage for a full description of available variables.

Alphabetical Listing of Perl Functions

-X

-r, -w, and -x have a limited meaning only; directories and applications are executable, and there are no uid/gid considerations. -o is not supported. (Mac OS)

-r, -w, -x, and -o tell whether the file is accessible, which may not reflect UIC-based file protections. (VMS)

-s returns the size of the data fork, not the total size of data fork plus resource fork. (Mac OS).

-s by name on an open file will return the space reserved on disk, rather than the current extent. -s on an open filehandle returns the current size. (RISC OS)

-R, -W, -X, -O are indistinguishable from -r, -w, -x, -o. (Mac OS, Win32, VMS, RISC OS)

-b, -c, -k, -g, -p, -u, -A are not implemented. (Mac OS)

-g, -k, -l, -p, -u, -A are not particularly meaningful. (Win32, VMS, RISC OS)

-d is true if passed a device spec without an explicit directory. (VMS)

-T and -B are implemented, but might misclassify Mac text files with foreign characters; this is the case will all platforms, but may affect Mac OS often. (Mac OS)

-x (or -X) determine if a file ends in one of the executable suffixes. -S is meaningless. (Win32)

-x (or -X) determine if a file has an executable file type. (RISC OS)

atan2 Y,X

Due to issues with various CPUs, math libraries, compilers, and standards, results for atan2() may vary depending on any combination of the above. Perl attempts to conform to the Open Group/IEEE standards for the results returned from atan2(), but cannot force the issue if the system Perl is run on does not allow it. (Tru64, HP-UX 10.20)

The current version of the standards for atan2() is available at http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html.

atan2

Due to issues with various CPUs, math libraries, compilers, and standards, results for atan2() may vary depending on any combination of the above. Perl attempts to conform to the Open Group/IEEE standards for the results returned from atan2(), but cannot force the issue if the system Perl is run on does not allow it. (Tru64, HP-UX 10.20)

The current version of the standards for atan2() is available at http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html.

binmode

Meaningless. (Mac OS, RISC OS)

Reopens file and restores pointer; if function fails, underlying filehandle may be closed, or pointer may be in a different position. (VMS)

The value returned by tell may be affected after the call, and the filehandle may be flushed. (Win32)

chmod

Only limited meaning. Disabling/enabling write permission is mapped to locking/unlocking the file. (Mac OS)

Only good for changing "owner" read-write access, "group", and "other" bits are meaningless. (Win32)

Only good for changing "owner" and "other" read-write access. (RISC OS)

Access permissions are mapped onto VOS access-control list changes. (VOS)

The actual permissions set depend on the value of the CYGWIN in the SYSTEM environment settings. (Cygwin)

chown

Not implemented. (Mac OS, Win32, Plan 9, RISC OS, VOS)

Does nothing, but won't fail. (Win32)

chroot

Not implemented. (Mac OS, Win32, VMS, Plan 9, RISC OS, VOS, VM/ESA)

crypt

May not be available if library or source was not provided when building perl. (Win32)

Not implemented. (VOS)

dbmclose

Not implemented. (VMS, Plan 9, VOS)

dbmopen

Not implemented. (VMS, Plan 9, VOS)

dump

Not useful. (Mac OS, RISC OS)

Not implemented. (Win32)

Invokes VMS debugger. (VMS)

exec

Not implemented. (Mac OS)

Implemented via Spawn. (VM/ESA)

Does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX)

exit

Emulates UNIX exit() (which considers exit 1 to indicate an error) by mapping the 1 to SS$_ABORT (44). This behavior may be overridden with the pragma use vmsish 'exit'. As with the CRTL's exit() function, exit 0 is also mapped to an exit status of SS$_NORMAL (1); this mapping cannot be overridden. Any other argument to exit() is used directly as Perl's exit status. (VMS)

fcntl

Not implemented. (Win32, VMS)

flock

Not implemented (Mac OS, VMS, RISC OS, VOS).

Available only on Windows NT (not on Windows 95). (Win32)

fork

Not implemented. (Mac OS, AmigaOS, RISC OS, VOS, VM/ESA, VMS)

Emulated using multiple interpreters. See the perlfork manpage. (Win32)

Does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX)

getlogin

Not implemented. (Mac OS, RISC OS)

getpgrp

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS)

getppid

Not implemented. (Mac OS, Win32, RISC OS)

getpriority

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS, VM/ESA)

getpwnam

Not implemented. (Mac OS, Win32)

Not useful. (RISC OS)

getgrnam

Not implemented. (Mac OS, Win32, VMS, RISC OS)

getnetbyname

Not implemented. (Mac OS, Win32, Plan 9)

getpwuid

Not implemented. (Mac OS, Win32)

Not useful. (RISC OS)

getgrgid

Not implemented. (Mac OS, Win32, VMS, RISC OS)

getnetbyaddr

Not implemented. (Mac OS, Win32, Plan 9)

getprotobynumber

Not implemented. (Mac OS)

getservbyport

Not implemented. (Mac OS)

getpwent

Not implemented. (Mac OS, Win32, VM/ESA)

getgrent

Not implemented. (Mac OS, Win32, VMS, VM/ESA)

gethostbyname

gethostbyname('localhost') does not work everywhere: you may have to use gethostbyname('127.0.0.1'). (Mac OS, Irix 5)

gethostent

Not implemented. (Mac OS, Win32)

getnetent

Not implemented. (Mac OS, Win32, Plan 9)

getprotoent

Not implemented. (Mac OS, Win32, Plan 9)

getservent

Not implemented. (Win32, Plan 9)

sethostent

Not implemented. (Mac OS, Win32, Plan 9, RISC OS)

setnetent

Not implemented. (Mac OS, Win32, Plan 9, RISC OS)

setprotoent

Not implemented. (Mac OS, Win32, Plan 9, RISC OS)

setservent

Not implemented. (Plan 9, Win32, RISC OS)

endpwent

Not implemented. (Mac OS, MPE/iX, VM/ESA, Win32)

endgrent

Not implemented. (Mac OS, MPE/iX, RISC OS, VM/ESA, VMS, Win32)

endhostent

Not implemented. (Mac OS, Win32)

endnetent

Not implemented. (Mac OS, Win32, Plan 9)

endprotoent

Not implemented. (Mac OS, Win32, Plan 9)

endservent

Not implemented. (Plan 9, Win32)

getsockopt SOCKET,LEVEL,OPTNAME

Not implemented. (Plan 9)

glob

This operator is implemented via the File::Glob extension on most platforms. See the File::Glob manpage for portability information.

gmtime

Same portability caveats as the localtime manpage.

ioctl FILEHANDLE,FUNCTION,SCALAR

Not implemented. (VMS)

Available only for socket handles, and it does what the ioctlsocket() call in the Winsock API does. (Win32)

Available only for socket handles. (RISC OS)

kill

kill(0, LIST) is implemented for the sake of taint checking; use with other signals is unimplemented. (Mac OS)

Not implemented, hence not useful for taint checking. (RISC OS)

kill() doesn't have the semantics of raise(), i.e. it doesn't send a signal to the identified process like it does on Unix platforms. Instead kill($sig, $pid) terminates the process identified by $pid, and makes it exit immediately with exit status $sig. As in Unix, if $sig is 0 and the specified process exists, it returns true without actually terminating it. (Win32)

link

Not implemented. (Mac OS, MPE/iX, VMS, RISC OS)

Link count not updated because hard links are not quite that hard (They are sort of half-way between hard and soft links). (AmigaOS)

Hard links are implemented on Win32 (Windows NT and Windows 2000) under NTFS only.

localtime

Because Perl currently relies on the native standard C localtime() function, it is only safe to use times between 0 and (2**31)-1. Times outside this range may result in unexpected behavior depending on your operating system's implementation of localtime().

lstat

Not implemented. (VMS, RISC OS)

Return values (especially for device and inode) may be bogus. (Win32)

msgctl
msgget
msgsnd
msgrcv

Not implemented. (Mac OS, Win32, VMS, Plan 9, RISC OS, VOS)

open

The | variants are supported only if ToolServer is installed. (Mac OS)

open to |- and -| are unsupported. (Mac OS, Win32, RISC OS)

Opening a process does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX)

pipe

Very limited functionality. (MiNT)

readlink

Not implemented. (Win32, VMS, RISC OS)

rename

Can't move directories between directories on different logical volumes. (Win32)

select

Only implemented on sockets. (Win32, VMS)

Only reliable on sockets. (RISC OS)

Note that the select FILEHANDLE form is generally portable.

semctl
semget
semop

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS)

setgrent

Not implemented. (Mac OS, MPE/iX, VMS, Win32, RISC OS)

setpgrp

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS)

setpriority

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS)

setpwent

Not implemented. (Mac OS, MPE/iX, Win32, RISC OS)

setsockopt

Not implemented. (Plan 9)

shmctl
shmget
shmread
shmwrite

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS)

sockatmark

A relatively recent addition to socket functions, may not be implemented even in UNIX platforms.

socketpair

Not implemented. (Win32, VMS, RISC OS, VOS, VM/ESA)

stat

Platforms that do not have rdev, blksize, or blocks will return these as '', so numeric comparison or manipulation of these fields may cause 'not numeric' warnings.

mtime and atime are the same thing, and ctime is creation time instead of inode change time. (Mac OS).

ctime not supported on UFS (Mac OS X).

ctime is creation time instead of inode change time (Win32).

device and inode are not meaningful. (Win32)

device and inode are not necessarily reliable. (VMS)

mtime, atime and ctime all return the last modification time. Device and inode are not necessarily reliable. (RISC OS)

dev, rdev, blksize, and blocks are not available. inode is not meaningful and will differ between stat calls on the same file. (os2)

some versions of cygwin when doing a stat("foo") and if not finding it may then attempt to stat("foo.exe") (Cygwin)

symlink

Not implemented. (Win32, VMS, RISC OS)

syscall

Not implemented. (Mac OS, Win32, VMS, RISC OS, VOS, VM/ESA)

sysopen

The traditional "0", "1", and "2" MODEs are implemented with different numeric values on some systems. The flags exported by Fcntl (O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (Mac OS, OS/390, VM/ESA)

system

In general, do not assume the UNIX/POSIX semantics that you can shift $? right by eight to get the exit value, or that $? & 127 would give you the number of the signal that terminated the program, or that $? & 128 would test true if the program was terminated by a coredump. Instead, use the POSIX W*() interfaces: for example, use WIFEXITED($?) and WEXITVALUE($?) to test for a normal exit and the exit value, WIFSIGNALED($?) and WTERMSIG($?) for a signal exit and the signal. Core dumping is not a portable concept, so there's no portable way to test for that.

Only implemented if ToolServer is installed. (Mac OS)

As an optimization, may not call the command shell specified in $ENV{PERL5SHELL}. system(1, @args) spawns an external process and immediately returns its process designator, without waiting for it to terminate. Return value may be used subsequently in wait or waitpid. Failure to spawn() a subprocess is indicated by setting $? to "255 << 8". $? is set in a way compatible with Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8", as described in the documentation). (Win32)

There is no shell to process metacharacters, and the native standard is to pass a command line terminated by "\n" "\r" or "\0" to the spawned program. Redirection such as > foo is performed (if at all) by the run time library of the spawned program. system list will call the Unix emulation library's exec emulation, which attempts to provide emulation of the stdin, stdout, stderr in force in the parent, providing the child program uses a compatible version of the emulation library. scalar will call the native command line direct and no such emulation of a child Unix program will exists. Mileage will vary. (RISC OS)

Far from being POSIX compliant. Because there may be no underlying /bin/sh tries to work around the problem by forking and execing the first token in its argument string. Handles basic redirection ("<" or ">") on its own behalf. (MiNT)

Does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX)

The return value is POSIX-like (shifted up by 8 bits), which only allows room for a made-up value derived from the severity bits of the native 32-bit condition code (unless overridden by use vmsish 'status'). For more details see $? in the perlvms manpage. (VMS)

times

Only the first entry returned is nonzero. (Mac OS)

"cumulative" times will be bogus. On anything other than Windows NT or Windows 2000, "system" time will be bogus, and "user" time is actually the time returned by the clock() function in the C runtime library. (Win32)

Not useful. (RISC OS)

truncate

Not implemented. (Older versions of VMS)

Truncation to zero-length only. (VOS)

If a FILEHANDLE is supplied, it must be writable and opened in append mode (i.e., use open(FH, '>>filename') or sysopen(FH,...,O_APPEND|O_RDWR). If a filename is supplied, it should not be held open elsewhere. (Win32)

umask

Returns undef where unavailable, as of version 5.005.

umask works but the correct permissions are set only when the file is finally closed. (AmigaOS)

utime

Only the modification time is updated. (BeOS, Mac OS, VMS, RISC OS)

May not behave as expected. Behavior depends on the C runtime library's implementation of utime(), and the filesystem being used. The FAT filesystem typically does not support an "access time" field, and it may limit timestamps to a granularity of two seconds. (Win32)

wait
waitpid

Not implemented. (Mac OS, VOS)

Can only be applied to process handles returned for processes spawned using system(1, ...) or pseudo processes created with fork(). (Win32)

Not useful. (RISC OS)

Supported Platforms

As of September 2003 (the Perl release 5.8.1), the following platforms are able to build Perl from the standard source code distribution available at http://www.cpan.org/src/index.html

        AIX
        BeOS
        BSD/OS          (BSDi)
        Cygwin
        DG/UX
        DOS DJGPP       1)
        DYNIX/ptx
        EPOC R5
        FreeBSD
        HI-UXMPP        (Hitachi) (5.8.0 worked but we didn't know it)
        HP-UX
        IRIX
        Linux
        LynxOS
        Mac OS Classic
        Mac OS X        (Darwin)
        MPE/iX
        NetBSD
        NetWare
        NonStop-UX
        ReliantUNIX     (formerly SINIX)
        OpenBSD
        OpenVMS         (formerly VMS)
        Open UNIX       (Unixware) (since Perl 5.8.1/5.9.0)
        OS/2
        OS/400          (using the PASE) (since Perl 5.8.1/5.9.0)
        PowerUX
        POSIX-BC        (formerly BS2000)
        QNX
        Solaris
        SunOS 4
        SUPER-UX        (NEC)
        SVR4
        Tru64 UNIX      (formerly DEC OSF/1, Digital UNIX)
        UNICOS
        UNICOS/mk
        UTS
        VOS
        Win95/98/ME/2K/XP 2)
        WinCE
        z/OS            (formerly OS/390)
        VM/ESA
        1) in DOS mode either the DOS or OS/2 ports can be used
        2) compilers: Borland, MinGW (GCC), VC6

The following platforms worked with the previous releases (5.6 and 5.7), but we did not manage either to fix or to test these in time for the 5.8.1 release. There is a very good chance that many of these will work fine with the 5.8.1.

        DomainOS
        Hurd
        MachTen
        PowerMAX
        SCO SV
        Unixware
        Windows 3.1

Known to be broken for 5.8.0 and 5.8.1 (but 5.6.1 and 5.7.2 can be used):

        AmigaOS

The following platforms have been known to build Perl from source in the past (5.005_03 and earlier), but we haven't been able to verify their status for the current release, either because the hardware/software platforms are rare or because we don't have an active champion on these platforms--or both. They used to work, though, so go ahead and try compiling them, and let perlbug@perl.org of any trouble.

        3b1
        A/UX
        ConvexOS
        CX/UX
        DC/OSx
        DDE SMES
        DOS EMX
        Dynix
        EP/IX
        ESIX
        FPS
        GENIX
        Greenhills
        ISC
        MachTen 68k
        MiNT
        MPC
        NEWS-OS
        NextSTEP
        OpenSTEP
        Opus
        Plan 9
        RISC/os
        SCO ODT/OSR
        Stellar
        SVR2
        TI1500
        TitanOS
        Ultrix
        Unisys Dynix

The following platforms have their own source code distributions and binaries available via http://www.cpan.org/ports/

                                Perl release
        OS/400 (ILE)            5.005_02
        Tandem Guardian         5.004

The following platforms have only binaries available via http://www.cpan.org/ports/index.html :

                                Perl release
        Acorn RISCOS            5.005_02
        AOS                     5.002
        LynxOS                  5.004_02

Although we do suggest that you always build your own Perl from the source code, both for maximal configurability and for security, in case you are in a hurry you can check http://www.cpan.org/ports/index.html for binary distributions.

SEE ALSO

the perlaix manpage, the perlamiga manpage, the perlapollo manpage, the perlbeos manpage, the perlbs2000 manpage, the perlce manpage, the perlcygwin manpage, the perldgux manpage, the perldos manpage, the perlepoc manpage, the perlebcdic manpage, the perlfreebsd manpage, the perlhurd manpage, the perlhpux manpage, the perlirix manpage, the perlmachten manpage, the perlmacos manpage, the perlmacosx manpage, the perlmint manpage, the perlmpeix manpage, the perlnetware manpage, the perlos2 manpage, the perlos390 manpage, the perlos400 manpage, the perlplan9 manpage, the perlqnx manpage, the perlsolaris manpage, the perltru64 manpage, the perlunicode manpage, the perlvmesa manpage, the perlvms manpage, the perlvos manpage, the perlwin32 manpage, and the Win32 manpage.

AUTHORS / CONTRIBUTORS

Abigail <abigail@foad.org>, Charles Bailey <bailey@newman.upenn.edu>, Graham Barr <gbarr@pobox.com>, Tom Christiansen <tchrist@perl.com>, Nicholas Clark <nick@ccl4.org>, Thomas Dorner <Thomas.Dorner@start.de>, Andy Dougherty <doughera@lafayette.edu>, Dominic Dunlop <domo@computer.org>, Neale Ferguson <neale@vma.tabnsw.com.au>, David J. Fiander <davidf@mks.com>, Paul Green <Paul_Green@stratus.com>, M.J.T. Guy <mjtg@cam.ac.uk>, Jarkko Hietaniemi <jhi@iki.fi>, Luther Huffman <lutherh@stratcom.com>, Nick Ing-Simmons <nick@ing-simmons.net>, Andreas J. König <a.koenig@mind.de>, Markus Laker <mlaker@contax.co.uk>, Andrew M. Langmead <aml@world.std.com>, Larry Moore <ljmoore@freespace.net>, Paul Moore <Paul.Moore@uk.origin-it.com>, Chris Nandor <pudge@pobox.com>, Matthias Neeracher <neeracher@mac.com>, Philip Newton <pne@cpan.org>, Gary Ng <71564.1743@CompuServe.COM>, Tom Phoenix <rootbeer@teleport.com>, André Pirard <A.Pirard@ulg.ac.be>, Peter Prymmer <pvhp@forte.com>, Hugo van der Sanden <hv@crypt0.demon.co.uk>, Gurusamy Sarathy <gsar@activestate.com>, Paul J. Schinder <schinder@pobox.com>, Michael G Schwern <schwern@pobox.com>, Dan Sugalski <dan@sidhe.org>, Nathan Torkington <gnat@frii.com>.


perlsec - Perl security

    • Laundering and Detecting Tainted Data
    • Switches On the "#!" Line
    • Taint mode and @INC
    • Cleaning Up Your Path
    • Security Bugs
    • Protecting Your Programs
    • Unicode
    • Algorithmic Complexity Attacks
  • SEE ALSO

NAME

perlsec - Perl security

DESCRIPTION

Perl is designed to make it easy to program securely even when running with extra privileges, like setuid or setgid programs. Unlike most command line shells, which are based on multiple substitution passes on each line of the script, Perl uses a more conventional evaluation scheme with fewer hidden snags. Additionally, because the language has more builtin functionality, it can rely less upon external (and possibly untrustworthy) programs to accomplish its purposes.

Perl automatically enables a set of special security checks, called taint mode, when it detects its program running with differing real and effective user or group IDs. The setuid bit in Unix permissions is mode 04000, the setgid bit mode 02000; either or both may be set. You can also enable taint mode explicitly by using the -T command line flag. This flag is strongly suggested for server programs and any program run on behalf of someone else, such as a CGI script. Once taint mode is on, it's on for the remainder of your script.

While in this mode, Perl takes special precautions called taint checks to prevent both obvious and subtle traps. Some of these checks are reasonably simple, such as verifying that path directories aren't writable by others; careful programmers have always used checks like these. Other checks, however, are best supported by the language itself, and it is these checks especially that contribute to making a set-id Perl program more secure than the corresponding C program.

You may not use data derived from outside your program to affect something else outside your program--at least, not by accident. All command line arguments, environment variables, locale information (see the perllocale manpage), results of certain system calls (readdir(), readlink(), the variable of shmread(), the messages returned by msgrcv(), the password, gcos and shell fields returned by the getpwxxx() calls), and all file input are marked as "tainted". Tainted data may not be used directly or indirectly in any command that invokes a sub-shell, nor in any command that modifies files, directories, or processes, with the following exceptions:

  • Arguments to print and syswrite are not checked for taintedness.

  • Symbolic methods

        $obj->$method(@args);

    and symbolic sub references

        &{$foo}(@args);
    $foo->(@args);

    are not checked for taintedness. This requires extra carefulness unless you want external data to affect your control flow. Unless you carefully limit what these symbolic values are, people are able to call functions outside your Perl code, such as POSIX::system, in which case they are able to run arbitrary external code.

For efficiency reasons, Perl takes a conservative view of whether data is tainted. If an expression contains tainted data, any subexpression may be considered tainted, even if the value of the subexpression is not itself affected by the tainted data.

Because taintedness is associated with each scalar value, some elements of an array or hash can be tainted and others not. The keys of a hash are never tainted.

For example:

    $arg = shift;               # $arg is tainted
    $hid = $arg, 'bar';         # $hid is also tainted
    $line = <>;                 # Tainted
    $line = <STDIN>;            # Also tainted
    open FOO, "/home/me/bar" or die $!;
    $line = <FOO>;              # Still tainted
    $path = $ENV{'PATH'};       # Tainted, but see below
    $data = 'abc';              # Not tainted

    system "echo $arg";         # Insecure
    system "/bin/echo", $arg;   # Considered insecure
                                # (Perl doesn't know about /bin/echo)
    system "echo $hid";         # Insecure
    system "echo $data";        # Insecure until PATH set

    $path = $ENV{'PATH'};       # $path now tainted

    $ENV{'PATH'} = '/bin:/usr/bin';
    delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};

    $path = $ENV{'PATH'};       # $path now NOT tainted
    system "echo $data";        # Is secure now!

    open(FOO, "< $arg");        # OK - read-only file
    open(FOO, "> $arg");        # Not OK - trying to write

    open(FOO,"echo $arg|");     # Not OK
    open(FOO,"-|")
        or exec 'echo', $arg;   # Also not OK

    $shout = `echo $arg`;       # Insecure, $shout now tainted

    unlink $data, $arg;         # Insecure
    umask $arg;                 # Insecure

    exec "echo $arg";           # Insecure
    exec "echo", $arg;          # Insecure
    exec "sh", '-c', $arg;      # Very insecure!

    @files = <*.c>;             # insecure (uses readdir() or similar)
    @files = glob('*.c');       # insecure (uses readdir() or similar)

    # In Perl releases older than 5.6.0 the <*.c> and glob('*.c') would
    # have used an external program to do the filename expansion; but in
    # either case the result is tainted since the list of filenames comes
    # from outside of the program.

    $bad = ($arg, 23);          # $bad will be tainted
    $arg, `true`;               # Insecure (although it isn't really)

If you try to do something insecure, you will get a fatal error saying something like "Insecure dependency" or "Insecure $ENV{PATH}".

The exception to the principle of "one tainted value taints the whole expression" is with the ternary conditional operator ?:. Since code with a ternary conditional

    $result = $tainted_value ? "Untainted" : "Also untainted";

is effectively

    if ( $tainted_value ) {
        $result = "Untainted";
    } else {
        $result = "Also untainted";
    }

it doesn't make sense for $result to be tainted.

Laundering and Detecting Tainted Data

To test whether a variable contains tainted data, and whose use would thus trigger an "Insecure dependency" message, you can use the tainted() function of the Scalar::Util module, available in your nearby CPAN mirror, and included in Perl starting from the release 5.8.0. Or you may be able to use the following is_tainted() function.

    sub is_tainted {
        return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
    }

This function makes use of the fact that the presence of tainted data anywhere within an expression renders the entire expression tainted. It would be inefficient for every operator to test every argument for taintedness. Instead, the slightly more efficient and conservative approach is used that if any tainted value has been accessed within the same expression, the whole expression is considered tainted.

But testing for taintedness gets you only so far. Sometimes you have just to clear your data's taintedness. Values may be untainted by using them as keys in a hash; otherwise the only way to bypass the tainting mechanism is by referencing subpatterns from a regular expression match. Perl presumes that if you reference a substring using $1, $2, etc., that you knew what you were doing when you wrote the pattern. That means using a bit of thought--don't just blindly untaint anything, or you defeat the entire mechanism. It's better to verify that the variable has only good characters (for certain values of "good") rather than checking whether it has any bad characters. That's because it's far too easy to miss bad characters that you never thought of.

Here's a test to make sure that the data contains nothing but "word" characters (alphabetics, numerics, and underscores), a hyphen, an at sign, or a dot.

    if ($data =~ /^([-\@\w.]+)$/) {
        $data = $1;                     # $data now untainted
    } else {
        die "Bad data in '$data'";      # log this somewhere
    }

This is fairly secure because /\w+/ doesn't normally match shell metacharacters, nor are dot, dash, or at going to mean something special to the shell. Use of /.+/ would have been insecure in theory because it lets everything through, but Perl doesn't check for that. The lesson is that when untainting, you must be exceedingly careful with your patterns. Laundering data using regular expression is the only mechanism for untainting dirty data, unless you use the strategy detailed below to fork a child of lesser privilege.

The example does not untaint $data if use locale is in effect, because the characters matched by \w are determined by the locale. Perl considers that locale definitions are untrustworthy because they contain data from outside the program. If you are writing a locale-aware program, and want to launder data with a regular expression containing \w, put no locale ahead of the expression in the same block. See SECURITY in the perllocale manpage for further discussion and examples.

Switches On the "#!" Line

When you make a script executable, in order to make it usable as a command, the system will pass switches to perl from the script's #! line. Perl checks that any command line switches given to a setuid (or setgid) script actually match the ones set on the #! line. Some Unix and Unix-like environments impose a one-switch limit on the #! line, so you may need to use something like -wU instead of -w -U under such systems. (This issue should arise only in Unix or Unix-like environments that support #! and setuid or setgid scripts.)

Taint mode and @INC

When the taint mode (-T) is in effect, the "." directory is removed from @INC, and the environment variables PERL5LIB and PERLLIB are ignored by Perl. You can still adjust @INC from outside the program by using the -I command line option as explained in the perlrun manpage. The two environment variables are ignored because they are obscured, and a user running a program could be unaware that they are set, whereas the -I option is clearly visible and therefore permitted.

Another way to modify @INC without modifying the program, is to use the lib pragma, e.g.:

  perl -Mlib=/foo program

The benefit of using -Mlib=/foo over -I/foo, is that the former will automagically remove any duplicated directories, while the later will not.

Note that if a tainted string is added to @INC, the following problem will be reported:

  Insecure dependency in require while running with -T switch

Cleaning Up Your Path

For "Insecure $ENV{PATH}" messages, you need to set $ENV{'PATH'} to a known value, and each directory in the path must be absolute and non-writable by others than its owner and group. You may be surprised to get this message even if the pathname to your executable is fully qualified. This is not generated because you didn't supply a full path to the program; instead, it's generated because you never set your PATH environment variable, or you didn't set it to something that was safe. Because Perl can't guarantee that the executable in question isn't itself going to turn around and execute some other program that is dependent on your PATH, it makes sure you set the PATH.

The PATH isn't the only environment variable which can cause problems. Because some shells may use the variables IFS, CDPATH, ENV, and BASH_ENV, Perl checks that those are either empty or untainted when starting subprocesses. You may wish to add something like this to your setid and taint-checking scripts.

    delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};   # Make %ENV safer

It's also possible to get into trouble with other operations that don't care whether they use tainted values. Make judicious use of the file tests in dealing with any user-supplied filenames. When possible, do opens and such after properly dropping any special user (or group!) privileges. Perl doesn't prevent you from opening tainted filenames for reading, so be careful what you print out. The tainting mechanism is intended to prevent stupid mistakes, not to remove the need for thought.

Perl does not call the shell to expand wild cards when you pass system and exec explicit parameter lists instead of strings with possible shell wildcards in them. Unfortunately, the open, glob, and backtick functions provide no such alternate calling convention, so more subterfuge will be required.

Perl provides a reasonably safe way to open a file or pipe from a setuid or setgid program: just create a child process with reduced privilege who does the dirty work for you. First, fork a child using the special open syntax that connects the parent and child by a pipe. Now the child resets its ID set and any other per-process attributes, like environment variables, umasks, current working directories, back to the originals or known safe values. Then the child process, which no longer has any special permissions, does the open or other system call. Finally, the child passes the data it managed to access back to the parent. Because the file or pipe was opened in the child while running under less privilege than the parent, it's not apt to be tricked into doing something it shouldn't.

Here's a way to do backticks reasonably safely. Notice how the exec is not called with a string that the shell could expand. This is by far the best way to call something that might be subjected to shell escapes: just never call the shell at all.

        use English '-no_match_vars';
        die "Can't fork: $!" unless defined($pid = open(KID, "-|"));
        if ($pid) {           # parent
            while (<KID>) {
                # do something
            }
            close KID;
        } else {
            my @temp     = ($EUID, $EGID);
            my $orig_uid = $UID;
            my $orig_gid = $GID;
            $EUID = $UID;
            $EGID = $GID;
            # Drop privileges
            $UID  = $orig_uid;
            $GID  = $orig_gid;
            # Make sure privs are really gone
            ($EUID, $EGID) = @temp;
            die "Can't drop privileges"
                unless $UID == $EUID  && $GID eq $EGID;
            $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
            # Consider sanitizing the environment even more.
            exec 'myprog', 'arg1', 'arg2'
                or die "can't exec myprog: $!";
        }

A similar strategy would work for wildcard expansion via glob, although you can use readdir instead.

Taint checking is most useful when although you trust yourself not to have written a program to give away the farm, you don't necessarily trust those who end up using it not to try to trick it into doing something bad. This is the kind of security checking that's useful for set-id programs and programs launched on someone else's behalf, like CGI programs.

This is quite different, however, from not even trusting the writer of the code not to try to do something evil. That's the kind of trust needed when someone hands you a program you've never seen before and says, "Here, run this." For that kind of safety, check out the Safe module, included standard in the Perl distribution. This module allows the programmer to set up special compartments in which all system operations are trapped and namespace access is carefully controlled.

Security Bugs

Beyond the obvious problems that stem from giving special privileges to systems as flexible as scripts, on many versions of Unix, set-id scripts are inherently insecure right from the start. The problem is a race condition in the kernel. Between the time the kernel opens the file to see which interpreter to run and when the (now-set-id) interpreter turns around and reopens the file to interpret it, the file in question may have changed, especially if you have symbolic links on your system.

Fortunately, sometimes this kernel "feature" can be disabled. Unfortunately, there are two ways to disable it. The system can simply outlaw scripts with any set-id bit set, which doesn't help much. Alternately, it can simply ignore the set-id bits on scripts. If the latter is true, Perl can emulate the setuid and setgid mechanism when it notices the otherwise useless setuid/gid bits on Perl scripts. It does this via a special executable called suidperl that is automatically invoked for you if it's needed.

However, if the kernel set-id script feature isn't disabled, Perl will complain loudly that your set-id script is insecure. You'll need to either disable the kernel set-id script feature, or put a C wrapper around the script. A C wrapper is just a compiled program that does nothing except call your Perl program. Compiled programs are not subject to the kernel bug that plagues set-id scripts. Here's a simple wrapper, written in C:

    #define REAL_PATH "/path/to/script"
    main(ac, av)
        char **av;
    {
        execv(REAL_PATH, av);
    }

Compile this wrapper into a binary executable and then make it rather than your script setuid or setgid.

In recent years, vendors have begun to supply systems free of this inherent security bug. On such systems, when the kernel passes the name of the set-id script to open to the interpreter, rather than using a pathname subject to meddling, it instead passes /dev/fd/3. This is a special file already opened on the script, so that there can be no race condition for evil scripts to exploit. On these systems, Perl should be compiled with -DSETUID_SCRIPTS_ARE_SECURE_NOW. The Configure program that builds Perl tries to figure this out for itself, so you should never have to specify this yourself. Most modern releases of SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.

Prior to release 5.6.1 of Perl, bugs in the code of suidperl could introduce a security hole.

Protecting Your Programs

There are a number of ways to hide the source to your Perl programs, with varying levels of "security".

First of all, however, you can't take away read permission, because the source code has to be readable in order to be compiled and interpreted. (That doesn't mean that a CGI script's source is readable by people on the web, though.) So you have to leave the permissions at the socially friendly 0755 level. This lets people on your local system only see your source.

Some people mistakenly regard this as a security problem. If your program does insecure things, and relies on people not knowing how to exploit those insecurities, it is not secure. It is often possible for someone to determine the insecure things and exploit them without viewing the source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed.

You can try using encryption via source filters (Filter::* from CPAN, or Filter::Util::Call and Filter::Simple since Perl 5.8). But crackers might be able to decrypt it. You can try using the byte code compiler and interpreter described below, but crackers might be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (this is true of every language, not just Perl).

If you're concerned about people profiting from your code, then the bottom line is that nothing but a restrictive licence will give you legal security. License your software and pepper it with threatening statements like "This is unpublished proprietary software of XYZ Corp. Your access to it does not give you permission to use it blah blah blah." You should see a lawyer to be sure your licence's wording will stand up in court.

Unicode

Unicode is a new and complex technology and one may easily overlook certain security pitfalls. See the perluniintro manpage for an overview and the perlunicode manpage for details, and Security Implications of Unicode in the perlunicode manpage for security implications in particular.

Algorithmic Complexity Attacks

Certain internal algorithms used in the implementation of Perl can be attacked by choosing the input carefully to consume large amounts of either time or space or both. This can lead into the so-called Denial of Service (DoS) attacks.

  • Hash Function - the algorithm used to "order" hash elements has been changed several times during the development of Perl, mainly to be reasonably fast. In Perl 5.8.1 also the security aspect was taken into account.

    In Perls before 5.8.1 one could rather easily generate data that as hash keys would cause Perl to consume large amounts of time because internal structure of hashes would badly degenerate. In Perl 5.8.1 the hash function is randomly perturbed by a pseudorandom seed which makes generating such naughty hash keys harder. See PERL_HASH_SEED in the perlrun manpage for more information.

    The random perturbation is done by default but if one wants for some reason emulate the old behaviour one can set the environment variable PERL_HASH_SEED to zero (or any other integer). One possible reason for wanting to emulate the old behaviour is that in the new behaviour consecutive runs of Perl will order hash keys differently, which may confuse some applications (like Data::Dumper: the outputs of two different runs are no more identical).

    Perl has never guaranteed any ordering of the hash keys, and the ordering has already changed several times during the lifetime of Perl 5. Also, the ordering of hash keys has always been, and continues to be, affected by the insertion order.

    Also note that while the order of the hash elements might be randomised, this "pseudoordering" should not be used for applications like shuffling a list randomly (use List::Util::shuffle() for that, see the List::Util manpage, a standard core module since Perl 5.8.0; or the CPAN module Algorithm::Numerical::Shuffle), or for generating permutations (use e.g. the CPAN modules Algorithm::Permute or Algorithm::FastPermute), or for any cryptographic applications.

  • Regular expressions - Perl's regular expression engine is so called NFA (Non-Finite Automaton), which among other things means that it can rather easily consume large amounts of both time and space if the regular expression may match in several ways. Careful crafting of the regular expressions can help but quite often there really isn't much one can do (the book "Mastering Regular Expressions" is required reading, see the perlfaq2 manpage). Running out of space manifests itself by Perl running out of memory.

  • Sorting - the quicksort algorithm used in Perls before 5.8.0 to implement the sort() function is very easy to trick into misbehaving so that it consumes a lot of time. Nothing more is required than resorting a list already sorted. Starting from Perl 5.8.0 a different sorting algorithm, mergesort, is used. Mergesort is insensitive to its input data, so it cannot be similarly fooled.

See http://www.cs.rice.edu/~scrosby/hash/ for more information, and any computer science text book on the algorithmic complexity.

SEE ALSO

the perlrun manpage for its description of cleaning up environment variables.


perlstyle - Perl style guide

NAME

perlstyle - Perl style guide

DESCRIPTION

Each programmer will, of course, have his or her own preferences in regards to formatting, but there are some general guidelines that will make your programs easier to read, understand, and maintain.

The most important thing is to run your programs under the -w flag at all times. You may turn it off explicitly for particular portions of code via the no warnings pragma or the $^W variable if you must. You should also always run under use strict or know the reason why not. The use sigtrap and even use diagnostics pragmas may also prove useful.

Regarding aesthetics of code lay out, about the only thing Larry cares strongly about is that the closing curly bracket of a multi-line BLOCK should line up with the keyword that started the construct. Beyond that, he has other preferences that aren't so strong:

  • 4-column indent.

  • Opening curly on same line as keyword, if possible, otherwise line up.

  • Space before the opening curly of a multi-line BLOCK.

  • One-line BLOCK may be put on one line, including curlies.

  • No space before the semicolon.

  • Semicolon omitted in "short" one-line BLOCK.

  • Space around most operators.

  • Space around a "complex" subscript (inside brackets).

  • Blank lines between chunks that do different things.

  • Uncuddled elses.

  • No space between function name and its opening parenthesis.

  • Space after each comma.

  • Long lines broken after an operator (except and and or).

  • Space after last parenthesis matching on current line.

  • Line up corresponding items vertically.

  • Omit redundant punctuation as long as clarity doesn't suffer.

Larry has his reasons for each of these things, but he doesn't claim that everyone else's mind works the same as his does.

Here are some other more substantive style issues to think about:

  • Just because you CAN do something a particular way doesn't mean that you SHOULD do it that way. Perl is designed to give you several ways to do anything, so consider picking the most readable one. For instance

        open(FOO,$foo) || die "Can't open $foo: $!";

    is better than

        die "Can't open $foo: $!" unless open(FOO,$foo);

    because the second way hides the main point of the statement in a modifier. On the other hand

        print "Starting analysis\n" if $verbose;

    is better than

        $verbose && print "Starting analysis\n";

    because the main point isn't whether the user typed -v or not.

    Similarly, just because an operator lets you assume default arguments doesn't mean that you have to make use of the defaults. The defaults are there for lazy systems programmers writing one-shot programs. If you want your program to be readable, consider supplying the argument.

    Along the same lines, just because you CAN omit parentheses in many places doesn't mean that you ought to:

        return print reverse sort num values %array;
    return print(reverse(sort num (values(%array))));

    When in doubt, parenthesize. At the very least it will let some poor schmuck bounce on the % key in vi.

    Even if you aren't in doubt, consider the mental welfare of the person who has to maintain the code after you, and who will probably put parentheses in the wrong place.

  • Don't go through silly contortions to exit a loop at the top or the bottom, when Perl provides the last operator so you can exit in the middle. Just "outdent" it a little to make it more visible:

        LINE:
        for (;;) {
            statements;
          last LINE if $foo;
            next LINE if /^#/;
            statements;
        }

  • Don't be afraid to use loop labels--they're there to enhance readability as well as to allow multilevel loop breaks. See the previous example.

  • Avoid using grep() (or map()) or `backticks` in a void context, that is, when you just throw away their return values. Those functions all have return values, so use them. Otherwise use a foreach() loop or the system() function instead.

  • For portability, when using features that may not be implemented on every machine, test the construct in an eval to see if it fails. If you know what version or patchlevel a particular feature was implemented, you can test $] ($PERL_VERSION in English) to see if it will be there. The Config module will also let you interrogate values determined by the Configure program when Perl was installed.

  • Choose mnemonic identifiers. If you can't remember what mnemonic means, you've got a problem.

  • While short identifiers like $gotit are probably ok, use underscores to separate words in longer identifiers. It is generally easier to read $var_names_like_this than $VarNamesLikeThis, especially for non-native speakers of English. It's also a simple rule that works consistently with VAR_NAMES_LIKE_THIS.

    Package names are sometimes an exception to this rule. Perl informally reserves lowercase module names for "pragma" modules like integer and strict. Other modules should begin with a capital letter and use mixed case, but probably without underscores due to limitations in primitive file systems' representations of module names as files that must fit into a few sparse bytes.

  • You may find it helpful to use letter case to indicate the scope or nature of a variable. For example:

        $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
    $Some_Caps_Here  package-wide global/static
    $no_caps_here    function scope my() or local() variables

    Function and method names seem to work best as all lowercase. E.g., $obj->as_string().

    You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it.

  • If you have a really hairy regular expression, use the /x modifier and put in some whitespace to make it look a little less like line noise. Don't use slash as a delimiter when your regexp has slashes or backslashes.

  • Use the new and and or operators to avoid having to parenthesize list operators so much, and to reduce the incidence of punctuation operators like && and ||. Call your subroutines as if they were functions or list operators to avoid excessive ampersands and parentheses.

  • Use here documents instead of repeated print() statements.

  • Line up corresponding things vertically, especially if it'd be too long to fit on one line anyway.

        $IDX = $ST_MTIME;
    $IDX = $ST_ATIME       if $opt_u;
    $IDX = $ST_CTIME       if $opt_c;
    $IDX = $ST_SIZE        if $opt_s;

        mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
    chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
    mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";

  • Always check the return codes of system calls. Good error messages should go to STDERR, include which program caused the problem, what the failed system call and arguments were, and (VERY IMPORTANT) should contain the standard system error message for what went wrong. Here's a simple but sufficient example:

        opendir(D, $dir)     or die "can't opendir $dir: $!";

  • Line up your transliterations when it makes sense:

        tr [abc]
       [xyz];

  • Think about reusability. Why waste brainpower on a one-shot when you might want to do something like it again? Consider generalizing your code. Consider writing a module or object class. Consider making your code run cleanly with use strict and use warnings (or -w) in effect. Consider giving away your code. Consider changing your whole world view. Consider... oh, never mind.

  • Try to document your code and use Pod formatting in a consistent way. Here are commonly expected conventions:

    • use C<> for function, variable and module names (and more generally anything that can be considered part of code, like filehandles or specific values). Note that function names are considered more readable with parentheses after their name, that is function().

    • use B<> for commands names like cat or grep.

    • use F<> or C<> for file names. F<> should be the only Pod code for file names, but as most Pod formatters render it as italic, Unix and Windows paths with their slashes and backslashes may be less readable, and better rendered with C<>.

  • Be consistent.

  • Be nice.


perlsub - Perl subroutines

    • Private Variables via my()
    • Persistent Private Variables
    • Temporary Values via local()
      • Grammatical note on local()
      • Localization of special variables
      • Localization of globs
      • Localization of elements of composite types
    • Lvalue subroutines
    • Passing Symbol Table Entries (typeglobs)
    • When to Still Use local()
    • Pass by Reference
    • Prototypes
    • Constant Functions
    • Overriding Built-in Functions
    • Autoloading
    • Subroutine Attributes
  • SEE ALSO

NAME

perlsub - Perl subroutines

SYNOPSIS

To declare subroutines:

    sub NAME;                     # A "forward" declaration.
    sub NAME(PROTO);              #  ditto, but with prototypes
    sub NAME : ATTRS;             #  with attributes
    sub NAME(PROTO) : ATTRS;      #  with attributes and prototypes

    sub NAME BLOCK                # A declaration and a definition.
    sub NAME(PROTO) BLOCK         #  ditto, but with prototypes
    sub NAME : ATTRS BLOCK        #  with attributes
    sub NAME(PROTO) : ATTRS BLOCK #  with prototypes and attributes

To define an anonymous subroutine at runtime:

    $subref = sub BLOCK;                 # no proto
    $subref = sub (PROTO) BLOCK;         # with proto
    $subref = sub : ATTRS BLOCK;         # with attributes
    $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes

To import subroutines:

    use MODULE qw(NAME1 NAME2 NAME3);

To call subroutines:

    NAME(LIST);    # & is optional with parentheses.
    NAME LIST;     # Parentheses optional if predeclared/imported.
    &NAME(LIST);   # Circumvent prototypes.
    &NAME;         # Makes current @_ visible to called subroutine.

DESCRIPTION

Like many languages, Perl provides for user-defined subroutines. These may be located anywhere in the main program, loaded in from other files via the do, require, or use keywords, or generated on the fly using eval or anonymous subroutines. You can even call a function indirectly using a variable containing its name or a CODE reference.

The Perl model for function call and return values is simple: all functions are passed as parameters one single flat list of scalars, and all functions likewise return to their caller one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities--but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.)

Any arguments passed in show up in the array @_. Therefore, if you called a function with two arguments, those would be stored in $_[0] and $_[1]. The array @_ is a local array, but its elements are aliases for the actual scalar parameters. In particular, if an element $_[0] is updated, the corresponding argument is updated (or an error occurs if it is not updatable). If an argument is an array or hash element which did not exist when the function was called, that element is created only when (and if) it is modified or a reference to it is taken. (Some earlier versions of Perl created the element whether or not the element was assigned to.) Assigning to the whole array @_ removes that aliasing, and does not update any arguments.

A return statement may be used to exit a subroutine, optionally specifying the returned value, which will be evaluated in the appropriate context (list, scalar, or void) depending on the context of the subroutine call. If you specify no return value, the subroutine returns an empty list in list context, the undefined value in scalar context, or nothing in void context. If you return one or more aggregates (arrays and hashes), these will be flattened together into one large indistinguishable list.

If no return is found and if the last statement is an expression, its value is returned. If the last statement is a loop control structure like a foreach or a while, the returned value is unspecified. The empty sub returns the empty list.

Perl does not have named formal parameters. In practice all you do is assign to a my() list of these. Variables that aren't declared to be private are global variables. For gory details on creating private variables, see Private Variables via my() and Temporary Values via local(). To create protected environments for a set of functions in a separate package (and probably a separate file), see Packages in the perlmod manpage.

Example:

    sub max {
        my $max = shift(@_);
        foreach $foo (@_) {
            $max = $foo if $max < $foo;
        }
        return $max;
    }
    $bestday = max($mon,$tue,$wed,$thu,$fri);

Example:

    # get a line, combining continuation lines
    #  that start with whitespace

    sub get_line {
        $thisline = $lookahead;  # global variables!
        LINE: while (defined($lookahead = <STDIN>)) {
            if ($lookahead =~ /^[ \t]/) {
                $thisline .= $lookahead;
            }
            else {
                last LINE;
            }
        }
        return $thisline;
    }

    $lookahead = <STDIN>;       # get first line
    while (defined($line = get_line())) {
        ...
    }

Assigning to a list of private variables to name your arguments:

    sub maybeset {
        my($key, $value) = @_;
        $Foo{$key} = $value unless $Foo{$key};
    }

Because the assignment copies the values, this also has the effect of turning call-by-reference into call-by-value. Otherwise a function is free to do in-place modifications of @_ and change its caller's values.

    upcase_in($v1, $v2);  # this changes $v1 and $v2
    sub upcase_in {
        for (@_) { tr/a-z/A-Z/ }
    }

You aren't allowed to modify constants in this way, of course. If an argument were actually literal and you tried to change it, you'd take a (presumably fatal) exception. For example, this won't work:

    upcase_in("frederick");

It would be much safer if the upcase_in() function were written to return a copy of its parameters instead of changing them in place:

    ($v3, $v4) = upcase($v1, $v2);  # this doesn't change $v1 and $v2
    sub upcase {
        return unless defined wantarray;  # void context, do nothing
        my @parms = @_;
        for (@parms) { tr/a-z/A-Z/ }
        return wantarray ? @parms : $parms[0];
    }

Notice how this (unprototyped) function doesn't care whether it was passed real scalars or arrays. Perl sees all arguments as one big, long, flat parameter list in @_. This is one area where Perl's simple argument-passing style shines. The upcase() function would work perfectly well without changing the upcase() definition even if we fed it things like this:

    @newlist   = upcase(@list1, @list2);
    @newlist   = upcase( split /:/, $var );

Do not, however, be tempted to do this:

    (@a, @b)   = upcase(@list1, @list2);

Like the flattened incoming parameter list, the return list is also flattened on return. So all you have managed to do here is stored everything in @a and made @b empty. See Pass by Reference for alternatives.

A subroutine may be called using an explicit & prefix. The & is optional in modern Perl, as are parentheses if the subroutine has been predeclared. The & is not optional when just naming the subroutine, such as when it's used as an argument to defined() or undef(). Nor is it optional when you want to do an indirect subroutine call with a subroutine name or reference using the &$subref() or &{$subref}() constructs, although the $subref->() notation solves that problem. See the perlref manpage for more about all that.

Subroutines may be called recursively. If a subroutine is called using the & form, the argument list is optional, and if omitted, no @_ array is set up for the subroutine: the @_ array at the time of the call is visible to subroutine instead. This is an efficiency mechanism that new users may wish to avoid.

    &foo(1,2,3);        # pass three arguments
    foo(1,2,3);         # the same

    foo();              # pass a null list
    &foo();             # the same

    &foo;               # foo() get current args, like foo(@_) !!
    foo;                # like foo() IFF sub foo predeclared, else "foo"

Not only does the & form make the argument list optional, it also disables any prototype checking on arguments you do provide. This is partly for historical reasons, and partly for having a convenient way to cheat if you know what you're doing. See Prototypes below.

Subroutines whose names are in all upper case are reserved to the Perl core, as are modules whose names are in all lower case. A subroutine in all capitals is a loosely-held convention meaning it will be called indirectly by the run-time system itself, usually due to a triggered event. Subroutines that do special, pre-defined things include AUTOLOAD, CLONE, DESTROY plus all functions mentioned in the perltie manpage and the PerlIO::via manpage.

The BEGIN, CHECK, INIT and END subroutines are not so much subroutines as named special code blocks, of which you can have more than one in a package, and which you can not call explicitly. See BEGIN, CHECK, INIT and END in the perlmod manpage

Private Variables via my()

Synopsis:

    my $foo;            # declare $foo lexically local
    my (@wid, %get);    # declare list of variables local
    my $foo = "flurp";  # declare $foo lexical, and init it
    my @oof = @bar;     # declare @oof lexical, and init it
    my $x : Foo = $y;   # similar, with an attribute applied

WARNING: The use of attribute lists on my declarations is still evolving. The current semantics and interface are subject to change. See the attributes manpage and the Attribute::Handlers manpage.

The my operator declares the listed variables to be lexically confined to the enclosing block, conditional (if/unless/elsif/else), loop (for/foreach/while/until/continue), subroutine, eval, or do/require/use'd file. If more than one value is listed, the list must be placed in parentheses. All listed elements must be legal lvalues. Only alphanumeric identifiers may be lexically scoped--magical built-ins like $/ must currently be localized with local instead.

Unlike dynamic variables created by the local operator, lexical variables declared with my are totally hidden from the outside world, including any called subroutines. This is true if it's the same subroutine called from itself or elsewhere--every call gets its own copy.

This doesn't mean that a my variable declared in a statically enclosing lexical scope would be invisible. Only dynamic scopes are cut off. For example, the bumpx() function below has access to the lexical $x variable because both the my and the sub occurred at the same scope, presumably file scope.

    my $x = 10;
    sub bumpx { $x++ }

An eval(), however, can see lexical variables of the scope it is being evaluated in, so long as the names aren't hidden by declarations within the eval() itself. See the perlref manpage.

The parameter list to my() may be assigned to if desired, which allows you to initialize your variables. (If no initializer is given for a particular variable, it is created with the undefined value.) Commonly this is used to name input parameters to a subroutine. Examples:

    $arg = "fred";        # "global" variable
    $n = cube_root(27);
    print "$arg thinks the root is $n\n";
     fred thinks the root is 3

    sub cube_root {
        my $arg = shift;  # name doesn't matter
        $arg **= 1/3;
        return $arg;
    }

The my is simply a modifier on something you might assign to. So when you do assign to variables in its argument list, my doesn't change whether those variables are viewed as a scalar or an array. So

    my ($foo) = <STDIN>;                # WRONG?
    my @FOO = <STDIN>;

both supply a list context to the right-hand side, while

    my $foo = <STDIN>;

supplies a scalar context. But the following declares only one variable:

    my $foo, $bar = 1;                  # WRONG

That has the same effect as

    my $foo;
    $bar = 1;

The declared variable is not introduced (is not visible) until after the current statement. Thus,

    my $x = $x;

can be used to initialize a new $x with the value of the old $x, and the expression

    my $x = 123 and $x == 123

is false unless the old $x happened to have the value 123.

Lexical scopes of control structures are not bounded precisely by the braces that delimit their controlled blocks; control expressions are part of that scope, too. Thus in the loop

    while (my $line = <>) {
        $line = lc $line;
    } continue {
        print $line;
    }

the scope of $line extends from its declaration throughout the rest of the loop construct (including the continue clause), but not beyond it. Similarly, in the conditional

    if ((my $answer = <STDIN>) =~ /^yes$/i) {
        user_agrees();
    } elsif ($answer =~ /^no$/i) {
        user_disagrees();
    } else {
        chomp $answer;
        die "'$answer' is neither 'yes' nor 'no'";
    }

the scope of $answer extends from its declaration through the rest of that conditional, including any elsif and else clauses, but not beyond it. See Simple statements in the perlsyn manpage for information on the scope of variables in statements with modifiers.

The foreach loop defaults to scoping its index variable dynamically in the manner of local. However, if the index variable is prefixed with the keyword my, or if there is already a lexical by that name in scope, then a new lexical is created instead. Thus in the loop

    for my $i (1, 2, 3) {
        some_function();
    }

the scope of $i extends to the end of the loop, but not beyond it, rendering the value of $i inaccessible within some_function().

Some users may wish to encourage the use of lexically scoped variables. As an aid to catching implicit uses to package variables, which are always global, if you say

    use strict 'vars';

then any variable mentioned from there to the end of the enclosing block must either refer to a lexical variable, be predeclared via our or use vars, or else must be fully qualified with the package name. A compilation error results otherwise. An inner block may countermand this with no strict 'vars'.

A my has both a compile-time and a run-time effect. At compile time, the compiler takes notice of it. The principal usefulness of this is to quiet use strict 'vars', but it is also essential for generation of closures as detailed in the perlref manpage. Actual initialization is delayed until run time, though, so it gets executed at the appropriate time, such as each time through a loop, for example.

Variables declared with my are not part of any package and are therefore never fully qualified with the package name. In particular, you're not allowed to try to make a package variable (or other global) lexical:

    my $pack::var;      # ERROR!  Illegal syntax
    my $_;              # also illegal (currently)

In fact, a dynamic variable (also known as package or global variables) are still accessible using the fully qualified :: notation even while a lexical of the same name is also visible:

    package main;
    local $x = 10;
    my    $x = 20;
    print "$x and $::x\n";

That will print out 20 and 10.

You may declare my variables at the outermost scope of a file to hide any such identifiers from the world outside that file. This is similar in spirit to C's static variables when they are used at the file level. To do this with a subroutine requires the use of a closure (an anonymous function that accesses enclosing lexicals). If you want to create a private subroutine that cannot be called from outside that block, it can declare a lexical variable containing an anonymous sub reference:

    my $secret_version = '1.001-beta';
    my $secret_sub = sub { print $secret_version };
    &$secret_sub();

As long as the reference is never returned by any function within the module, no outside module can see the subroutine, because its name is not in any package's symbol table. Remember that it's not REALLY called $some_pack::secret_version or anything; it's just $secret_version, unqualified and unqualifiable.

This does not work with object methods, however; all object methods have to be in the symbol table of some package to be found. See Function Templates in the perlref manpage for something of a work-around to this.

Persistent Private Variables

Just because a lexical variable is lexically (also called statically) scoped to its enclosing block, eval, or do FILE, this doesn't mean that within a function it works like a C static. It normally works more like a C auto, but with implicit garbage collection.

Unlike local variables in C or C++, Perl's lexical variables don't necessarily get recycled just because their scope has exited. If something more permanent is still aware of the lexical, it will stick around. So long as something else references a lexical, that lexical won't be freed--which is as it should be. You wouldn't want memory being free until you were done using it, or kept around once you were done. Automatic garbage collection takes care of this for you.

This means that you can pass back or save away references to lexical variables, whereas to return a pointer to a C auto is a grave error. It also gives us a way to simulate C's function statics. Here's a mechanism for giving a function private variables with both lexical scoping and a static lifetime. If you do want to create something like C's static variables, just enclose the whole function in an extra block, and put the static variable outside the function but in the block.

    {
        my $secret_val = 0;
        sub gimme_another {
            return ++$secret_val;
        }
    }
    # $secret_val now becomes unreachable by the outside
    # world, but retains its value between calls to gimme_another

If this function is being sourced in from a separate file via require or use, then this is probably just fine. If it's all in the main program, you'll need to arrange for the my to be executed early, either by putting the whole block above your main program, or more likely, placing merely a BEGIN code block around it to make sure it gets executed before your program starts to run:

    BEGIN {
        my $secret_val = 0;
        sub gimme_another {
            return ++$secret_val;
        }
    }

See BEGIN, CHECK, INIT and END in the perlmod manpage about the special triggered code blocks, BEGIN, CHECK, INIT and END.

If declared at the outermost scope (the file scope), then lexicals work somewhat like C's file statics. They are available to all functions in that same file declared below them, but are inaccessible from outside that file. This strategy is sometimes used in modules to create private variables that the whole module can see.

Temporary Values via local()

WARNING: In general, you should be using my instead of local, because it's faster and safer. Exceptions to this include the global punctuation variables, global filehandles and formats, and direct manipulation of the Perl symbol table itself. local is mostly used when the current value of a variable must be visible to called subroutines.

Synopsis:

    # localization of values

    local $foo;                 # make $foo dynamically local
    local (@wid, %get);         # make list of variables local
    local $foo = "flurp";       # make $foo dynamic, and init it
    local @oof = @bar;          # make @oof dynamic, and init it

    local $hash{key} = "val";   # sets a local value for this hash entry
    local ($cond ? $v1 : $v2);  # several types of lvalues support
                                # localization

    # localization of symbols

    local *FH;                  # localize $FH, @FH, %FH, &FH  ...
    local *merlyn = *randal;    # now $merlyn is really $randal, plus
                                #     @merlyn is really @randal, etc
    local *merlyn = 'randal';   # SAME THING: promote 'randal' to *randal
    local *merlyn = \$randal;   # just alias $merlyn, not @merlyn etc

A local modifies its listed variables to be "local" to the enclosing block, eval, or do FILE--and to any subroutine called from within that block. A local just gives temporary values to global (meaning package) variables. It does not create a local variable. This is known as dynamic scoping. Lexical scoping is done with my, which works more like C's auto declarations.

Some types of lvalues can be localized as well : hash and array elements and slices, conditionals (provided that their result is always localizable), and symbolic references. As for simple variables, this creates new, dynamically scoped values.

If more than one variable or expression is given to local, they must be placed in parentheses. This operator works by saving the current values of those variables in its argument list on a hidden stack and restoring them upon exiting the block, subroutine, or eval. This means that called subroutines can also reference the local variable, but not the global one. The argument list may be assigned to if desired, which allows you to initialize your local variables. (If no initializer is given for a particular variable, it is created with an undefined value.)

Because local is a run-time operator, it gets executed each time through a loop. Consequently, it's more efficient to localize your variables outside the loop.

Grammatical note on local()

A local is simply a modifier on an lvalue expression. When you assign to a localized variable, the local doesn't change whether its list is viewed as a scalar or an array. So

    local($foo) = <STDIN>;
    local @FOO = <STDIN>;

both supply a list context to the right-hand side, while

    local $foo = <STDIN>;

supplies a scalar context.

Localization of special variables

If you localize a special variable, you'll be giving a new value to it, but its magic won't go away. That means that all side-effects related to this magic still work with the localized value.

This feature allows code like this to work :

    # Read the whole contents of FILE in $slurp
    { local $/ = undef; $slurp = <FILE>; }

Note, however, that this restricts localization of some values ; for example, the following statement dies, as of perl 5.9.0, with an error Modification of a read-only value attempted, because the $1 variable is magical and read-only :

    local $1 = 2;

Similarly, but in a way more difficult to spot, the following snippet will die in perl 5.9.0 :

    sub f { local $_ = "foo"; print }
    for ($1) {
        # now $_ is aliased to $1, thus is magic and readonly
        f();
    }

See next section for an alternative to this situation.

WARNING: Localization of tied arrays and hashes does not currently work as described. This will be fixed in a future release of Perl; in the meantime, avoid code that relies on any particular behaviour of localising tied arrays or hashes (localising individual elements is still okay). See Localising Tied Arrays and Hashes Is Broken in the perl58delta manpage for more details.

Localization of globs

The construct

    local *name;

creates a whole new symbol table entry for the glob name in the current package. That means that all variables in its glob slot ($name, @name, %name, &name, and the name filehandle) are dynamically reset.

This implies, among other things, that any magic eventually carried by those variables is locally lost. In other words, saying local */ will not have any effect on the internal value of the input record separator.

Notably, if you want to work with a brand new value of the default scalar $_, and avoid the potential problem listed above about $_ previously carrying a magic value, you should use local *_ instead of local $_.

Localization of elements of composite types

It's also worth taking a moment to explain what happens when you localize a member of a composite type (i.e. an array or hash element). In this case, the element is localized by name. This means that when the scope of the local() ends, the saved value will be restored to the hash element whose key was named in the local(), or the array element whose index was named in the local(). If that element was deleted while the local() was in effect (e.g. by a delete() from a hash or a shift() of an array), it will spring back into existence, possibly extending an array and filling in the skipped elements with undef. For instance, if you say

    %hash = ( 'This' => 'is', 'a' => 'test' );
    @ary  = ( 0..5 );
    {
         local($ary[5]) = 6;
         local($hash{'a'}) = 'drill';
         while (my $e = pop(@ary)) {
             print "$e . . .\n";
             last unless $e > 3;
         }
         if (@ary) {
             $hash{'only a'} = 'test';
             delete $hash{'a'};
         }
    }
    print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
    print "The array has ",scalar(@ary)," elements: ",
          join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";

Perl will print

    6 . . .
    4 . . .
    3 . . .
    This is a test only a test.
    The array has 6 elements: 0, 1, 2, undef, undef, 5

The behavior of local() on non-existent members of composite types is subject to change in future.

Lvalue subroutines

WARNING: Lvalue subroutines are still experimental and the implementation may change in future versions of Perl.

It is possible to return a modifiable value from a subroutine. To do this, you have to declare the subroutine to return an lvalue.

    my $val;
    sub canmod : lvalue {
        # return $val; this doesn't work, don't say "return"
        $val;
    }
    sub nomod {
        $val;
    }

    canmod() = 5;   # assigns to $val
    nomod()  = 5;   # ERROR

The scalar/list context for the subroutine and for the right-hand side of assignment is determined as if the subroutine call is replaced by a scalar. For example, consider:

    data(2,3) = get_data(3,4);

Both subroutines here are called in a scalar context, while in:

    (data(2,3)) = get_data(3,4);

and in:

    (data(2),data(3)) = get_data(3,4);

all the subroutines are called in a list context.

Lvalue subroutines are EXPERIMENTAL

They appear to be convenient, but there are several reasons to be circumspect.

You can't use the return keyword, you must pass out the value before falling out of subroutine scope. (see comment in example above). This is usually not a problem, but it disallows an explicit return out of a deeply nested loop, which is sometimes a nice way out.

They violate encapsulation. A normal mutator can check the supplied argument before setting the attribute it is protecting, an lvalue subroutine never gets that chance. Consider;

    my $some_array_ref = [];    # protected by mutators ??

    sub set_arr {               # normal mutator
        my $val = shift;
        die("expected array, you supplied ", ref $val)
           unless ref $val eq 'ARRAY';
        $some_array_ref = $val;
    }
    sub set_arr_lv : lvalue {   # lvalue mutator
        $some_array_ref;
    }

    # set_arr_lv cannot stop this !
    set_arr_lv() = { a => 1 };

Passing Symbol Table Entries (typeglobs)

WARNING: The mechanism described in this section was originally the only way to simulate pass-by-reference in older versions of Perl. While it still works fine in modern versions, the new reference mechanism is generally easier to work with. See below.

Sometimes you don't want to pass the value of an array to a subroutine but rather the name of it, so that the subroutine can modify the global copy of it rather than working with a local copy. In perl you can refer to all objects of a particular name by prefixing the name with a star: *foo. This is often known as a "typeglob", because the star on the front can be thought of as a wildcard match for all the funny prefix characters on variables and subroutines and such.

When evaluated, the typeglob produces a scalar value that represents all the objects of that name, including any filehandle, format, or subroutine. When assigned to, it causes the name mentioned to refer to whatever * value was assigned to it. Example:

    sub doubleary {
        local(*someary) = @_;
        foreach $elem (@someary) {
            $elem *= 2;
        }
    }
    doubleary(*foo);
    doubleary(*bar);

Scalars are already passed by reference, so you can modify scalar arguments without using this mechanism by referring explicitly to $_[0] etc. You can modify all the elements of an array by passing all the elements as scalars, but you have to use the * mechanism (or the equivalent reference mechanism) to push, pop, or change the size of an array. It will certainly be faster to pass the typeglob (or reference).

Even if you don't want to modify an array, this mechanism is useful for passing multiple arrays in a single LIST, because normally the LIST mechanism will merge all the array values so that you can't extract out the individual arrays. For more on typeglobs, see Typeglobs and Filehandles in the perldata manpage.

When to Still Use local()

Despite the existence of my, there are still three places where the local operator still shines. In fact, in these three places, you must use local instead of my.

  1. You need to give a global variable a temporary value, especially $_.

    The global variables, like @ARGV or the punctuation variables, must be localized with local(). This block reads in /etc/motd, and splits it up into chunks separated by lines of equal signs, which are placed in @Fields.

        {
        local @ARGV = ("/etc/motd");
        local $/ = undef;
        local $_ = <>;
        @Fields = split /^\s*=+\s*$/;
    }

    It particular, it's important to localize $_ in any routine that assigns to it. Look out for implicit assignments in while conditionals.

  2. You need to create a local file or directory handle or a local function.

    A function that needs a filehandle of its own must use local() on a complete typeglob. This can be used to create new symbol table entries:

        sub ioqueue {
        local  (*READER, *WRITER);    # not my!
        pipe    (READER,  WRITER)     or die "pipe: $!";
        return (*READER, *WRITER);
    }
    ($head, $tail) = ioqueue();

    See the Symbol module for a way to create anonymous symbol table entries.

    Because assignment of a reference to a typeglob creates an alias, this can be used to create what is effectively a local function, or at least, a local alias.

        {
        local *grow = \&shrink; # only until this block exists
        grow();                 # really calls shrink()
        move();                 # if move() grow()s, it shrink()s too
    }
    grow();                     # get the real grow() again

    See Function Templates in the perlref manpage for more about manipulating functions by name in this way.

  3. You want to temporarily change just one element of an array or hash.

    You can localize just one element of an aggregate. Usually this is done on dynamics:

        {
        local $SIG{INT} = 'IGNORE';
        funct();                            # uninterruptible
    }
    # interruptibility automatically restored here

    But it also works on lexically declared aggregates. Prior to 5.005, this operation could on occasion misbehave.

Pass by Reference

If you want to pass more than one array or hash into a function--or return them from it--and have them maintain their integrity, then you're going to have to use an explicit pass-by-reference. Before you do that, you need to understand references as detailed in the perlref manpage. This section may not make much sense to you otherwise.

Here are a few simple examples. First, let's pass in several arrays to a function and have it pop all of then, returning a new list of all their former last elements:

    @tailings = popmany ( \@a, \@b, \@c, \@d );

    sub popmany {
        my $aref;
        my @retlist = ();
        foreach $aref ( @_ ) {
            push @retlist, pop @$aref;
        }
        return @retlist;
    }

Here's how you might write a function that returns a list of keys occurring in all the hashes passed to it:

    @common = inter( \%foo, \%bar, \%joe );
    sub inter {
        my ($k, $href, %seen); # locals
        foreach $href (@_) {
            while ( $k = each %$href ) {
                $seen{$k}++;
            }
        }
        return grep { $seen{$_} == @_ } keys %seen;
    }

So far, we're using just the normal list return mechanism. What happens if you want to pass or return a hash? Well, if you're using only one of them, or you don't mind them concatenating, then the normal calling convention is ok, although a little expensive.

Where people get into trouble is here:

    (@a, @b) = func(@c, @d);
    or
    (%a, %b) = func(%c, %d);

That syntax simply won't work. It sets just @a or %a and clears the @b or %b. Plus the function didn't get passed into two separate arrays or hashes: it got one long list in @_, as always.

If you can arrange for everyone to deal with this through references, it's cleaner code, although not so nice to look at. Here's a function that takes two array references as arguments, returning the two array elements in order of how many elements they have in them:

    ($aref, $bref) = func(\@c, \@d);
    print "@$aref has more than @$bref\n";
    sub func {
        my ($cref, $dref) = @_;
        if (@$cref > @$dref) {
            return ($cref, $dref);
        } else {
            return ($dref, $cref);
        }
    }

It turns out that you can actually do this also:

    (*a, *b) = func(\@c, \@d);
    print "@a has more than @b\n";
    sub func {
        local (*c, *d) = @_;
        if (@c > @d) {
            return (\@c, \@d);
        } else {
            return (\@d, \@c);
        }
    }

Here we're using the typeglobs to do symbol table aliasing. It's a tad subtle, though, and also won't work if you're using my variables, because only globals (even in disguise as locals) are in the symbol table.

If you're passing around filehandles, you could usually just use the bare typeglob, like *STDOUT, but typeglobs references work, too. For example:

    splutter(\*STDOUT);
    sub splutter {
        my $fh = shift;
        print $fh "her um well a hmmm\n";
    }

    $rec = get_rec(\*STDIN);
    sub get_rec {
        my $fh = shift;
        return scalar <$fh>;
    }

If you're planning on generating new filehandles, you could do this. Notice to pass back just the bare *FH, not its reference.

    sub openit {
        my $path = shift;
        local *FH;
        return open (FH, $path) ? *FH : undef;
    }

Prototypes

Perl supports a very limited kind of compile-time argument checking using function prototyping. If you declare

    sub mypush (\@@)

then mypush() takes arguments exactly like push() does. The function declaration must be visible at compile time. The prototype affects only interpretation of new-style calls to the function, where new-style is defined as not using the & character. In other words, if you call it like a built-in function, then it behaves like a built-in function. If you call it like an old-fashioned subroutine, then it behaves like an old-fashioned subroutine. It naturally falls out from this rule that prototypes have no influence on subroutine references like \&foo or on indirect subroutine calls like &{$subref} or $subref->().

Method calls are not influenced by prototypes either, because the function to be called is indeterminate at compile time, since the exact code called depends on inheritance.

Because the intent of this feature is primarily to let you define subroutines that work like built-in functions, here are prototypes for some other functions that parse almost exactly like the corresponding built-in.

    Declared as                 Called as
    sub mylink ($$)          mylink $old, $new
    sub myvec ($$$)          myvec $var, $offset, 1
    sub myindex ($$;$)       myindex &getstring, "substr"
    sub mysyswrite ($$$;$)   mysyswrite $buf, 0, length($buf) - $off, $off
    sub myreverse (@)        myreverse $a, $b, $c
    sub myjoin ($@)          myjoin ":", $a, $b, $c
    sub mypop (\@)           mypop @array
    sub mysplice (\@$$@)     mysplice @array, @array, 0, @pushme
    sub mykeys (\%)          mykeys %{$hashref}
    sub myopen (*;$)         myopen HANDLE, $name
    sub mypipe (**)          mypipe READHANDLE, WRITEHANDLE
    sub mygrep (&@)          mygrep { /foo/ } $a, $b, $c
    sub myrand ($)           myrand 42
    sub mytime ()            mytime

Any backslashed prototype character represents an actual argument that absolutely must start with that character. The value passed as part of @_ will be a reference to the actual argument given in the subroutine call, obtained by applying \ to that argument.

You can also backslash several argument types simultaneously by using the \[] notation:

    sub myref (\[$@%&*])

will allow calling myref() as

    myref $var
    myref @array
    myref %hash
    myref &sub
    myref *glob

and the first argument of myref() will be a reference to a scalar, an array, a hash, a code, or a glob.

Unbackslashed prototype characters have special meanings. Any unbackslashed @ or % eats all remaining arguments, and forces list context. An argument represented by $ forces scalar context. An & requires an anonymous subroutine, which, if passed as the first argument, does not require the sub keyword or a subsequent comma.

A * allows the subroutine to accept a bareword, constant, scalar expression, typeglob, or a reference to a typeglob in that slot. The value will be available to the subroutine either as a simple scalar, or (in the latter two cases) as a reference to the typeglob. If you wish to always convert such arguments to a typeglob reference, use Symbol::qualify_to_ref() as follows:

    use Symbol 'qualify_to_ref';

    sub foo (*) {
        my $fh = qualify_to_ref(shift, caller);
        ...
    }

A semicolon separates mandatory arguments from optional arguments. It is redundant before @ or %, which gobble up everything else.

Note how the last three examples in the table above are treated specially by the parser. mygrep() is parsed as a true list operator, myrand() is parsed as a true unary operator with unary precedence the same as rand(), and mytime() is truly without arguments, just like time(). That is, if you say

    mytime +2;

you'll get mytime() + 2, not mytime(2), which is how it would be parsed without a prototype.

The interesting thing about & is that you can generate new syntax with it, provided it's in the initial position:

    sub try (&@) {
        my($try,$catch) = @_;
        eval { &$try };
        if ($@) {
            local $_ = $@;
            &$catch;
        }
    }
    sub catch (&) { $_[0] }

    try {
        die "phooey";
    } catch {
        /phooey/ and print "unphooey\n";
    };

That prints "unphooey". (Yes, there are still unresolved issues having to do with visibility of @_. I'm ignoring that question for the moment. (But note that if we make @_ lexically scoped, those anonymous subroutines can act like closures... (Gee, is this sounding a little Lispish? (Never mind.))))

And here's a reimplementation of the Perl grep operator:

    sub mygrep (&@) {
        my $code = shift;
        my @result;
        foreach $_ (@_) {
            push(@result, $_) if &$code;
        }
        @result;
    }

Some folks would prefer full alphanumeric prototypes. Alphanumerics have been intentionally left out of prototypes for the express purpose of someday in the future adding named, formal parameters. The current mechanism's main goal is to let module writers provide better diagnostics for module users. Larry feels the notation quite understandable to Perl programmers, and that it will not intrude greatly upon the meat of the module, nor make it harder to read. The line noise is visually encapsulated into a small pill that's easy to swallow.

If you try to use an alphanumeric sequence in a prototype you will generate an optional warning - "Illegal character in prototype...". Unfortunately earlier versions of Perl allowed the prototype to be used as long as its prefix was a valid prototype. The warning may be upgraded to a fatal error in a future version of Perl once the majority of offending code is fixed.

It's probably best to prototype new functions, not retrofit prototyping into older ones. That's because you must be especially careful about silent impositions of differing list versus scalar contexts. For example, if you decide that a function should take just one parameter, like this:

    sub func ($) {
        my $n = shift;
        print "you gave me $n\n";
    }

and someone has been calling it with an array or expression returning a list:

    func(@foo);
    func( split /:/ );

Then you've just supplied an automatic scalar in front of their argument, which can be more than a bit surprising. The old @foo which used to hold one thing doesn't get passed in. Instead, func() now gets passed in a 1; that is, the number of elements in @foo. And the split gets called in scalar context so it starts scribbling on your @_ parameter list. Ouch!

This is all very powerful, of course, and should be used only in moderation to make the world a better place.

Constant Functions

Functions with a prototype of () are potential candidates for inlining. If the result after optimization and constant folding is either a constant or a lexically-scoped scalar which has no other references, then it will be used in place of function calls made without &. Calls made using & are never inlined. (See constant.pm for an easy way to declare most constants.)

The following functions would all be inlined:

    sub pi ()           { 3.14159 }             # Not exact, but close.
    sub PI ()           { 4 * atan2 1, 1 }      # As good as it gets,
                                                # and it's inlined, too!
    sub ST_DEV ()       { 0 }
    sub ST_INO ()       { 1 }

    sub FLAG_FOO ()     { 1 << 8 }
    sub FLAG_BAR ()     { 1 << 9 }
    sub FLAG_MASK ()    { FLAG_FOO | FLAG_BAR }

    sub OPT_BAZ ()      { not (0x1B58 & FLAG_MASK) }

    sub N () { int(OPT_BAZ) / 3 }

    sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }

Be aware that these will not be inlined; as they contain inner scopes, the constant folding doesn't reduce them to a single constant:

    sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } }

    sub baz_val () {
        if (OPT_BAZ) {
            return 23;
        }
        else {
            return 42;
        }
    }

If you redefine a subroutine that was eligible for inlining, you'll get a mandatory warning. (You can use this warning to tell whether or not a particular subroutine is considered constant.) The warning is considered severe enough not to be optional because previously compiled invocations of the function will still be using the old value of the function. If you need to be able to redefine the subroutine, you need to ensure that it isn't inlined, either by dropping the () prototype (which changes calling semantics, so beware) or by thwarting the inlining mechanism in some other way, such as

    sub not_inlined () {
        23 if $];
    }

Overriding Built-in Functions

Many built-in functions may be overridden, though this should be tried only occasionally and for good reason. Typically this might be done by a package attempting to emulate missing built-in functionality on a non-Unix system.

Overriding may be done only by importing the name from a module at compile time--ordinary predeclaration isn't good enough. However, the use subs pragma lets you, in effect, predeclare subs via the import syntax, and these names may then override built-in ones:

    use subs 'chdir', 'chroot', 'chmod', 'chown';
    chdir $somewhere;
    sub chdir { ... }

To unambiguously refer to the built-in form, precede the built-in name with the special package qualifier CORE::. For example, saying CORE::open() always refers to the built-in open(), even if the current package has imported some other subroutine called &open() from elsewhere. Even though it looks like a regular function call, it isn't: you can't take a reference to it, such as the incorrect \&CORE::open might appear to produce.

Library modules should not in general export built-in names like open or chdir as part of their default @EXPORT list, because these may sneak into someone else's namespace and change the semantics unexpectedly. Instead, if the module adds that name to @EXPORT_OK, then it's possible for a user to import the name explicitly, but not implicitly. That is, they could say

    use Module 'open';

and it would import the open override. But if they said

    use Module;

they would get the default imports without overrides.

The foregoing mechanism for overriding built-in is restricted, quite deliberately, to the package that requests the import. There is a second method that is sometimes applicable when you wish to override a built-in everywhere, without regard to namespace boundaries. This is achieved by importing a sub into the special namespace CORE::GLOBAL::. Here is an example that quite brazenly replaces the glob operator with something that understands regular expressions.

    package REGlob;
    require Exporter;
    @ISA = 'Exporter';
    @EXPORT_OK = 'glob';

    sub import {
        my $pkg = shift;
        return unless @_;
        my $sym = shift;
        my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
        $pkg->export($where, $sym, @_);
    }

    sub glob {
        my $pat = shift;
        my @got;
        local *D;
        if (opendir D, '.') {
            @got = grep /$pat/, readdir D;
            closedir D;
        }
        return @got;
    }
    1;

And here's how it could be (ab)used:

    #use REGlob 'GLOBAL_glob';      # override glob() in ALL namespaces
    package Foo;
    use REGlob 'glob';              # override glob() in Foo:: only
    print for <^[a-z_]+\.pm\$>;     # show all pragmatic modules

The initial comment shows a contrived, even dangerous example. By overriding glob globally, you would be forcing the new (and subversive) behavior for the glob operator for every namespace, without the complete cognizance or cooperation of the modules that own those namespaces. Naturally, this should be done with extreme caution--if it must be done at all.

The REGlob example above does not implement all the support needed to cleanly override perl's glob operator. The built-in glob has different behaviors depending on whether it appears in a scalar or list context, but our REGlob doesn't. Indeed, many perl built-in have such context sensitive behaviors, and these must be adequately supported by a properly written override. For a fully functional example of overriding glob, study the implementation of File::DosGlob in the standard library.

When you override a built-in, your replacement should be consistent (if possible) with the built-in native syntax. You can achieve this by using a suitable prototype. To get the prototype of an overridable built-in, use the prototype function with an argument of "CORE::builtin_name" (see prototype in the perlfunc manpage).

Note however that some built-ins can't have their syntax expressed by a prototype (such as system or chomp). If you override them you won't be able to fully mimic their original syntax.

The built-ins do, require and glob can also be overridden, but due to special magic, their original syntax is preserved, and you don't have to define a prototype for their replacements. (You can't override the do BLOCK syntax, though).

require has special additional dark magic: if you invoke your require replacement as require Foo::Bar, it will actually receive the argument "Foo/Bar.pm" in @_. See require in the perlfunc manpage.

And, as you'll have noticed from the previous example, if you override glob, the <*> glob operator is overridden as well.

In a similar fashion, overriding the readline function also overrides the equivalent I/O operator <FILEHANDLE>.

Finally, some built-ins (e.g. exists or grep) can't be overridden.

Autoloading

If you call a subroutine that is undefined, you would ordinarily get an immediate, fatal error complaining that the subroutine doesn't exist. (Likewise for subroutines being used as methods, when the method doesn't exist in any base class of the class's package.) However, if an AUTOLOAD subroutine is defined in the package or packages used to locate the original subroutine, then that AUTOLOAD subroutine is called with the arguments that would have been passed to the original subroutine. The fully qualified name of the original subroutine magically appears in the global $AUTOLOAD variable of the same package as the AUTOLOAD routine. The name is not passed as an ordinary argument because, er, well, just because, that's why...

Many AUTOLOAD routines load in a definition for the requested subroutine using eval(), then execute that subroutine using a special form of goto() that erases the stack frame of the AUTOLOAD routine without a trace. (See the source to the standard module documented in the AutoLoader manpage, for example.) But an AUTOLOAD routine can also just emulate the routine and never define it. For example, let's pretend that a function that wasn't defined should just invoke system with those arguments. All you'd do is:

    sub AUTOLOAD {
        my $program = $AUTOLOAD;
        $program =~ s/.*:://;
        system($program, @_);
    }
    date();
    who('am', 'i');
    ls('-l');

In fact, if you predeclare functions you want to call that way, you don't even need parentheses:

    use subs qw(date who ls);
    date;
    who "am", "i";
    ls -l;

A more complete example of this is the standard Shell module, which can treat undefined subroutine calls as calls to external programs.

Mechanisms are available to help modules writers split their modules into autoloadable files. See the standard AutoLoader module described in the AutoLoader manpage and in the AutoSplit manpage, the standard SelfLoader modules in the SelfLoader manpage, and the document on adding C functions to Perl code in the perlxs manpage.

Subroutine Attributes

A subroutine declaration or definition may have a list of attributes associated with it. If such an attribute list is present, it is broken up at space or colon boundaries and treated as though a use attributes had been seen. See the attributes manpage for details about what attributes are currently supported. Unlike the limitation with the obsolescent use attrs, the sub : ATTRLIST syntax works to associate the attributes with a pre-declaration, and not just with a subroutine definition.

The attributes must be valid as simple identifier names (without any punctuation other than the '_' character). They may have a parameter list appended, which is only checked for whether its parentheses ('(',')') nest properly.

Examples of valid syntax (even though the attributes are unknown):

    sub fnord (&\%) : switch(10,foo(7,3))  :  expensive;
    sub plugh () : Ugly('\(") :Bad;
    sub xyzzy : _5x5 { ... }

Examples of invalid syntax:

    sub fnord : switch(10,foo(); # ()-string not balanced
    sub snoid : Ugly('(');        # ()-string not balanced
    sub xyzzy : 5x5;              # "5x5" not a valid identifier
    sub plugh : Y2::north;        # "Y2::north" not a simple identifier
    sub snurt : foo + bar;        # "+" not a colon or space

The attribute list is passed as a list of constant strings to the code which associates them with the subroutine. In particular, the second example of valid syntax above currently looks like this in terms of how it's parsed and invoked:

    use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';

For further details on attribute lists and their manipulation, see the attributes manpage and the Attribute::Handlers manpage.

SEE ALSO

See Function Templates in the perlref manpage for more about references and closures. See the perlxs manpage if you'd like to learn about calling C subroutines from Perl. See the perlembed manpage if you'd like to learn about calling Perl subroutines from C. See the perlmod manpage to learn about bundling up your functions in separate files. See the perlmodlib manpage to learn what library modules come standard on your system. See the perltoot manpage to learn how to make object method calls.


perlsyn - Perl syntax

    • Declarations
    • Comments
    • Simple Statements
    • Truth and Falsehood
    • Statement Modifiers
    • Compound Statements
    • Loop Control
    • For Loops
    • Foreach Loops
    • Basic BLOCKs and Switch Statements
    • Goto
    • PODs: Embedded Documentation
    • Plain Old Comments (Not!)

NAME

perlsyn - Perl syntax

DESCRIPTION

A Perl program consists of a sequence of declarations and statements which run from the top to the bottom. Loops, subroutines and other control structures allow you to jump around within the code.

Perl is a free-form language, you can format and indent it however you like. Whitespace mostly serves to separate tokens, unlike languages like Python where it is an important part of the syntax.

Many of Perl's syntactic elements are optional. Rather than requiring you to put parentheses around every function call and declare every variable, you can often leave such explicit elements off and Perl will figure out what you meant. This is known as Do What I Mean, abbreviated DWIM. It allows programmers to be lazy and to code in a style with which they are comfortable.

Perl borrows syntax and concepts from many languages: awk, sed, C, Bourne Shell, Smalltalk, Lisp and even English. Other languages have borrowed syntax from Perl, particularly its regular expression extensions. So if you have programmed in another language you will see familiar pieces in Perl. They often work the same, but see the perltrap manpage for information about how they differ.

Declarations

The only things you need to declare in Perl are report formats and subroutines (and sometimes not even subroutines). A variable holds the undefined value (undef) until it has been assigned a defined value, which is anything other than undef. When used as a number, undef is treated as 0; when used as a string, it is treated as the empty string, ""; and when used as a reference that isn't being assigned to, it is treated as an error. If you enable warnings, you'll be notified of an uninitialized value whenever you treat undef as a string or a number. Well, usually. Boolean contexts, such as:

    my $a;
    if ($a) {}

are exempt from warnings (because they care about truth rather than definedness). Operators such as ++, --, +=, -=, and .=, that operate on undefined left values such as:

    my $a;
    $a++;

are also always exempt from such warnings.

A declaration can be put anywhere a statement can, but has no effect on the execution of the primary sequence of statements--declarations all take effect at compile time. Typically all the declarations are put at the beginning or the end of the script. However, if you're using lexically-scoped private variables created with my(), you'll have to make sure your format or subroutine definition is within the same block scope as the my if you expect to be able to access those private variables.

Declaring a subroutine allows a subroutine name to be used as if it were a list operator from that point forward in the program. You can declare a subroutine without defining it by saying sub name, thus:

    sub myname;
    $me = myname $0             or die "can't get myname";

Note that myname() functions as a list operator, not as a unary operator; so be careful to use or instead of || in this case. However, if you were to declare the subroutine as sub myname ($), then myname would function as a unary operator, so either or or || would work.

Subroutines declarations can also be loaded up with the require statement or both loaded and imported into your namespace with a use statement. See the perlmod manpage for details on this.

A statement sequence may contain declarations of lexically-scoped variables, but apart from declaring a variable name, the declaration acts like an ordinary statement, and is elaborated within the sequence of statements as if it were an ordinary statement. That means it actually has both compile-time and run-time effects.

Comments

Text from a "#" character until the end of the line is a comment, and is ignored. Exceptions include "#" inside a string or regular expression.

Simple Statements

The only kind of simple statement is an expression evaluated for its side effects. Every simple statement must be terminated with a semicolon, unless it is the final statement in a block, in which case the semicolon is optional. (A semicolon is still encouraged if the block takes up more than one line, because you may eventually add another line.) Note that there are some operators like eval {} and do {} that look like compound statements, but aren't (they're just TERMs in an expression), and thus need an explicit termination if used as the last item in a statement.

Truth and Falsehood

The number 0, the strings '0' and '', the empty list (), and undef are all false in a boolean context. All other values are true. Negation of a true value by ! or not returns a special false value. When evaluated as a string it is treated as '', but as a number, it is treated as 0.

Statement Modifiers

Any simple statement may optionally be followed by a SINGLE modifier, just before the terminating semicolon (or block ending). The possible modifiers are:

    if EXPR
    unless EXPR
    while EXPR
    until EXPR
    foreach LIST

The EXPR following the modifier is referred to as the "condition". Its truth or falsehood determines how the modifier will behave.

if executes the statement once if and only if the condition is true. unless is the opposite, it executes the statement unless the condition is true (i.e., if the condition is false).

    print "Basset hounds got long ears" if length $ear >= 10;
    go_outside() and play() unless $is_raining;

The foreach modifier is an iterator: it executes the statement once for each item in the LIST (with $_ aliased to each item in turn).

    print "Hello $_!\n" foreach qw(world Dolly nurse);

while repeats the statement while the condition is true. until does the opposite, it repeats the statement until the condition is true (or while the condition is false):

    # Both of these count from 0 to 10.
    print $i++ while $i <= 10;
    print $j++ until $j >  10;

The while and until modifiers have the usual "while loop" semantics (conditional evaluated first), except when applied to a do-BLOCK (or to the deprecated do-SUBROUTINE statement), in which case the block executes once before the conditional is evaluated. This is so that you can write loops like:

    do {
        $line = <STDIN>;
        ...
    } until $line  eq ".\n";

See do in the perlfunc manpage. Note also that the loop control statements described later will NOT work in this construct, because modifiers don't take loop labels. Sorry. You can always put another block inside of it (for next) or around it (for last) to do that sort of thing. For next, just double the braces:

    do {{
        next if $x == $y;
        # do something here
    }} until $x++ > $z;

For last, you have to be more elaborate:

    LOOP: {
            do {
                last if $x = $y**2;
                # do something here
            } while $x++ <= $z;
    }

NOTE: The behaviour of a my statement modified with a statement modifier conditional or loop construct (e.g. my $x if ...) is undefined. The value of the my variable may be undef, any previously assigned value, or possibly anything else. Don't rely on it. Future versions of perl might do something different from the version of perl you try it out on. Here be dragons.

Compound Statements

In Perl, a sequence of statements that defines a scope is called a block. Sometimes a block is delimited by the file containing it (in the case of a required file, or the program as a whole), and sometimes a block is delimited by the extent of a string (in the case of an eval).

But generally, a block is delimited by curly brackets, also known as braces. We will call this syntactic construct a BLOCK.

The following compound statements may be used to control flow:

    if (EXPR) BLOCK
    if (EXPR) BLOCK else BLOCK
    if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
    LABEL while (EXPR) BLOCK
    LABEL while (EXPR) BLOCK continue BLOCK
    LABEL until (EXPR) BLOCK
    LABEL until (EXPR) BLOCK continue BLOCK
    LABEL for (EXPR; EXPR; EXPR) BLOCK
    LABEL foreach VAR (LIST) BLOCK
    LABEL foreach VAR (LIST) BLOCK continue BLOCK
    LABEL BLOCK continue BLOCK

Note that, unlike C and Pascal, these are defined in terms of BLOCKs, not statements. This means that the curly brackets are required--no dangling statements allowed. If you want to write conditionals without curly brackets there are several other ways to do it. The following all do the same thing:

    if (!open(FOO)) { die "Can't open $FOO: $!"; }
    die "Can't open $FOO: $!" unless open(FOO);
    open(FOO) or die "Can't open $FOO: $!";     # FOO or bust!
    open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
                        # a bit exotic, that last one

The if statement is straightforward. Because BLOCKs are always bounded by curly brackets, there is never any ambiguity about which if an else goes with. If you use unless in place of if, the sense of the test is reversed.

The while statement executes the block as long as the expression is true (does not evaluate to the null string "" or 0 or "0"). The until statement executes the block as long as the expression is false. The LABEL is optional, and if present, consists of an identifier followed by a colon. The LABEL identifies the loop for the loop control statements next, last, and redo. If the LABEL is omitted, the loop control statement refers to the innermost enclosing loop. This may include dynamically looking back your call-stack at run time to find the LABEL. Such desperate behavior triggers a warning if you use the use warnings pragma or the -w flag.

If there is a continue BLOCK, it is always executed just before the conditional is about to be evaluated again. Thus it can be used to increment a loop variable, even when the loop has been continued via the next statement.

Loop Control

The next command starts the next iteration of the loop:

    LINE: while (<STDIN>) {
        next LINE if /^#/;      # discard comments
        ...
    }

The last command immediately exits the loop in question. The continue block, if any, is not executed:

    LINE: while (<STDIN>) {
        last LINE if /^$/;      # exit when done with header
        ...
    }

The redo command restarts the loop block without evaluating the conditional again. The continue block, if any, is not executed. This command is normally used by programs that want to lie to themselves about what was just input.

For example, when processing a file like /etc/termcap. If your input lines might end in backslashes to indicate continuation, you want to skip ahead and get the next record.

    while (<>) {
        chomp;
        if (s/\\$//) {
            $_ .= <>;
            redo unless eof();
        }
        # now process $_
    }

which is Perl short-hand for the more explicitly written version:

    LINE: while (defined($line = <ARGV>)) {
        chomp($line);
        if ($line =~ s/\\$//) {
            $line .= <ARGV>;
            redo LINE unless eof(); # not eof(ARGV)!
        }
        # now process $line
    }

Note that if there were a continue block on the above code, it would get executed only on lines discarded by the regex (since redo skips the continue block). A continue block is often used to reset line counters or ?pat? one-time matches:

    # inspired by :1,$g/fred/s//WILMA/
    while (<>) {
        ?(fred)?    && s//WILMA $1 WILMA/;
        ?(barney)?  && s//BETTY $1 BETTY/;
        ?(homer)?   && s//MARGE $1 MARGE/;
    } continue {
        print "$ARGV $.: $_";
        close ARGV  if eof();           # reset $.
        reset       if eof();           # reset ?pat?
    }

If the word while is replaced by the word until, the sense of the test is reversed, but the conditional is still tested before the first iteration.

The loop control statements don't work in an if or unless, since they aren't loops. You can double the braces to make them such, though.

    if (/pattern/) {{
        last if /fred/;
        next if /barney/; # same effect as "last", but doesn't document as well
        # do something here
    }}

This is caused by the fact that a block by itself acts as a loop that executes once, see Basic BLOCKs and Switch Statements.

The form while/if BLOCK BLOCK, available in Perl 4, is no longer available. Replace any occurrence of if BLOCK by if (do BLOCK).

For Loops

Perl's C-style for loop works like the corresponding while loop; that means that this:

    for ($i = 1; $i < 10; $i++) {
        ...
    }

is the same as this:

    $i = 1;
    while ($i < 10) {
        ...
    } continue {
        $i++;
    }

There is one minor difference: if variables are declared with my in the initialization section of the for, the lexical scope of those variables is exactly the for loop (the body of the loop and the control sections).

Besides the normal array index looping, for can lend itself to many other interesting applications. Here's one that avoids the problem you get into if you explicitly test for end-of-file on an interactive file descriptor causing your program to appear to hang.

    $on_a_tty = -t STDIN && -t STDOUT;
    sub prompt { print "yes? " if $on_a_tty }
    for ( prompt(); <STDIN>; prompt() ) {
        # do something
    }

Using readline (or the operator form, <EXPR>) as the conditional of a for loop is shorthand for the following. This behaviour is the same as a while loop conditional. >>

    for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
        # do something
    }

Foreach Loops

The foreach loop iterates over a normal list value and sets the variable VAR to be each element of the list in turn. If the variable is preceded with the keyword my, then it is lexically scoped, and is therefore visible only within the loop. Otherwise, the variable is implicitly local to the loop and regains its former value upon exiting the loop. If the variable was previously declared with my, it uses that variable instead of the global one, but it's still localized to the loop. This implicit localisation occurs only in a foreach loop.

The foreach keyword is actually a synonym for the for keyword, so you can use foreach for readability or for for brevity. (Or because the Bourne shell is more familiar to you than csh, so writing for comes more naturally.) If VAR is omitted, $_ is set to each value.

If any element of LIST is an lvalue, you can modify it by modifying VAR inside the loop. Conversely, if any element of LIST is NOT an lvalue, any attempt to modify that element will fail. In other words, the foreach loop index variable is an implicit alias for each item in the list that you're looping over.

If any part of LIST is an array, foreach will get very confused if you add or remove elements within the loop body, for example with splice. So don't do that.

foreach probably won't do what you expect if VAR is a tied or other special variable. Don't do that either.

Examples:

    for (@ary) { s/foo/bar/ }

    for my $elem (@elements) {
        $elem *= 2;
    }

    for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
        print $count, "\n"; sleep(1);
    }

    for (1..15) { print "Merry Christmas\n"; }

    foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
        print "Item: $item\n";
    }

Here's how a C programmer might code up a particular algorithm in Perl:

    for (my $i = 0; $i < @ary1; $i++) {
        for (my $j = 0; $j < @ary2; $j++) {
            if ($ary1[$i] > $ary2[$j]) {
                last; # can't go to outer :-(
            }
            $ary1[$i] += $ary2[$j];
        }
        # this is where that last takes me
    }

Whereas here's how a Perl programmer more comfortable with the idiom might do it:

    OUTER: for my $wid (@ary1) {
    INNER:   for my $jet (@ary2) {
                next OUTER if $wid > $jet;
                $wid += $jet;
             }
          }

See how much easier this is? It's cleaner, safer, and faster. It's cleaner because it's less noisy. It's safer because if code gets added between the inner and outer loops later on, the new code won't be accidentally executed. The next explicitly iterates the other loop rather than merely terminating the inner one. And it's faster because Perl executes a foreach statement more rapidly than it would the equivalent for loop.

Basic BLOCKs and Switch Statements

A BLOCK by itself (labeled or not) is semantically equivalent to a loop that executes once. Thus you can use any of the loop control statements in it to leave or restart the block. (Note that this is NOT true in eval{}, sub{}, or contrary to popular belief do{} blocks, which do NOT count as loops.) The continue block is optional.

The BLOCK construct is particularly nice for doing case structures.

    SWITCH: {
        if (/^abc/) { $abc = 1; last SWITCH; }
        if (/^def/) { $def = 1; last SWITCH; }
        if (/^xyz/) { $xyz = 1; last SWITCH; }
        $nothing = 1;
    }

There is no official switch statement in Perl, because there are already several ways to write the equivalent.

However, starting from Perl 5.8 to get switch and case one can use the Switch extension and say:

        use Switch;

after which one has switch and case. It is not as fast as it could be because it's not really part of the language (it's done using source filters) but it is available, and it's very flexible.

In addition to the above BLOCK construct, you could write

    SWITCH: {
        $abc = 1, last SWITCH  if /^abc/;
        $def = 1, last SWITCH  if /^def/;
        $xyz = 1, last SWITCH  if /^xyz/;
        $nothing = 1;
    }

(That's actually not as strange as it looks once you realize that you can use loop control "operators" within an expression. That's just the binary comma operator in scalar context. See Comma Operator in the perlop manpage.)

or

    SWITCH: {
        /^abc/ && do { $abc = 1; last SWITCH; };
        /^def/ && do { $def = 1; last SWITCH; };
        /^xyz/ && do { $xyz = 1; last SWITCH; };
        $nothing = 1;
    }

or formatted so it stands out more as a "proper" switch statement:

    SWITCH: {
        /^abc/      && do {
                            $abc = 1;
                            last SWITCH;
                       };

        /^def/      && do {
                            $def = 1;
                            last SWITCH;
                       };

        /^xyz/      && do {
                            $xyz = 1;
                            last SWITCH;
                        };
        $nothing = 1;
            }

or

    SWITCH: {
        /^abc/ and $abc = 1, last SWITCH;
        /^def/ and $def = 1, last SWITCH;
        /^xyz/ and $xyz = 1, last SWITCH;
        $nothing = 1;
    }

or even, horrors,

    if (/^abc/)
        { $abc = 1 }
    elsif (/^def/)
        { $def = 1 }
    elsif (/^xyz/)
        { $xyz = 1 }
    else
        { $nothing = 1 }

A common idiom for a switch statement is to use foreach's aliasing to make a temporary assignment to $_ for convenient matching:

    SWITCH: for ($where) {
                /In Card Names/     && do { push @flags, '-e'; last; };
                /Anywhere/          && do { push @flags, '-h'; last; };
                /In Rulings/        && do {                    last; };
                die "unknown value for form variable where: `$where'";
            }

Another interesting approach to a switch statement is arrange for a do block to return the proper value:

    $amode = do {
        if     ($flag & O_RDONLY) { "r" }       # XXX: isn't this 0?
        elsif  ($flag & O_WRONLY) { ($flag & O_APPEND) ? "a" : "w" }
        elsif  ($flag & O_RDWR)   {
            if ($flag & O_CREAT)  { "w+" }
            else                  { ($flag & O_APPEND) ? "a+" : "r+" }
        }
    };

Or

        print do {
            ($flags & O_WRONLY) ? "write-only"          :
            ($flags & O_RDWR)   ? "read-write"          :
                                  "read-only";
        };

Or if you are certain that all the && clauses are true, you can use something like this, which "switches" on the value of the HTTP_USER_AGENT environment variable.

    #!/usr/bin/perl
    # pick out jargon file page based on browser
    $dir = 'http://www.wins.uva.nl/~mes/jargon';
    for ($ENV{HTTP_USER_AGENT}) {
        $page  =    /Mac/            && 'm/Macintrash.html'
                 || /Win(dows )?NT/  && 'e/evilandrude.html'
                 || /Win|MSIE|WebTV/ && 'm/MicroslothWindows.html'
                 || /Linux/          && 'l/Linux.html'
                 || /HP-UX/          && 'h/HP-SUX.html'
                 || /SunOS/          && 's/ScumOS.html'
                 ||                     'a/AppendixB.html';
    }
    print "Location: $dir/$page\015\012\015\012";

That kind of switch statement only works when you know the && clauses will be true. If you don't, the previous ?: example should be used.

You might also consider writing a hash of subroutine references instead of synthesizing a switch statement.

Goto

Although not for the faint of heart, Perl does support a goto statement. There are three forms: goto-LABEL, goto-EXPR, and goto-&NAME. A loop's LABEL is not actually a valid target for a goto; it's just the name of the loop.

The goto-LABEL form finds the statement labeled with LABEL and resumes execution there. It may not be used to go into any construct that requires initialization, such as a subroutine or a foreach loop. It also can't be used to go into a construct that is optimized away. It can be used to go almost anywhere else within the dynamic scope, including out of subroutines, but it's usually better to use some other construct such as last or die. The author of Perl has never felt the need to use this form of goto (in Perl, that is--C is another matter).

The goto-EXPR form expects a label name, whose scope will be resolved dynamically. This allows for computed gotos per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability:

    goto(("FOO", "BAR", "GLARCH")[$i]);

The goto-&NAME form is highly magical, and substitutes a call to the named subroutine for the currently running subroutine. This is used by AUTOLOAD() subroutines that wish to load another subroutine and then pretend that the other subroutine had been called in the first place (except that any modifications to @_ in the current subroutine are propagated to the other subroutine.) After the goto, not even caller() will be able to tell that this routine was called first.

In almost all cases like this, it's usually a far, far better idea to use the structured control flow mechanisms of next, last, or redo instead of resorting to a goto. For certain applications, the catch and throw pair of eval{} and die() for exception processing can also be a prudent approach.

PODs: Embedded Documentation

Perl has a mechanism for intermixing documentation with source code. While it's expecting the beginning of a new statement, if the compiler encounters a line that begins with an equal sign and a word, like this

    =head1 Here There Be Pods!

Then that text and all remaining text up through and including a line beginning with =cut will be ignored. The format of the intervening text is described in the perlpod manpage.

This allows you to intermix your source code and your documentation text freely, as in

    =item snazzle($)
    The snazzle() function will behave in the most spectacular
    form that you can possibly imagine, not even excepting
    cybernetic pyrotechnics.
    =cut back to the compiler, nuff of this pod stuff!
    sub snazzle($) {
        my $thingie = shift;
        .........
    }

Note that pod translators should look at only paragraphs beginning with a pod directive (it makes parsing easier), whereas the compiler actually knows to look for pod escapes even in the middle of a paragraph. This means that the following secret stuff will be ignored by both the compiler and the translators.

    $a=3;
    =secret stuff
     warn "Neither POD nor CODE!?"
    =cut back
    print "got $a\n";

You probably shouldn't rely upon the warn() being podded out forever. Not all pod translators are well-behaved in this regard, and perhaps the compiler will become pickier.

One may also use pod directives to quickly comment out a section of code.

Plain Old Comments (Not!)

Perl can process line directives, much like the C preprocessor. Using this, one can control Perl's idea of filenames and line numbers in error or warning messages (especially for strings that are processed with eval()). The syntax for this mechanism is the same as for most C preprocessors: it matches the regular expression

    # example: '# line 42 "new_filename.plx"'
    /^\#   \s*
      line \s+ (\d+)   \s*
      (?:\s("?)([^"]+)\2)? \s*
     $/x

with $1 being the line number for the next line, and $3 being the optional filename (specified with or without quotes).

There is a fairly obvious gotcha included with the line directive: Debuggers and profilers will only show the last source line to appear at a particular line number in a given file. Care should be taken not to cause line number collisions in code you'd like to debug later.

Here are some examples that you should be able to type into your command shell:

    % perl
    # line 200 "bzzzt"
    # the `#' on the previous line must be the first char on line
    die 'foo';
    __END__
    foo at bzzzt line 201.

    % perl
    # line 200 "bzzzt"
    eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
    __END__
    foo at - line 2001.

    % perl
    eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
    __END__
    foo at foo bar line 200.

    % perl
    # line 345 "goop"
    eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
    print $@;
    __END__
    foo at goop line 345.


perltrap - Perl traps for the unwary

    • Awk Traps
    • C/C++ Traps
    • Sed Traps
    • Shell Traps
    • Perl Traps
    • Perl4 to Perl5 Traps
    • Discontinuance, Deprecation, and BugFix traps
    • Parsing Traps
    • Numerical Traps
    • General data type traps
    • Context Traps - scalar, list contexts
    • Precedence Traps
    • General Regular Expression Traps using s///, etc.
    • Subroutine, Signal, Sorting Traps
    • OS Traps
    • Interpolation Traps
    • DBM Traps
    • Unclassified Traps

NAME

perltrap - Perl traps for the unwary

DESCRIPTION

The biggest trap of all is forgetting to use warnings or use the -w switch; see the perllexwarn manpage and the perlrun manpage. The second biggest trap is not making your entire program runnable under use strict. The third biggest trap is not reading the list of changes in this version of Perl; see the perldelta manpage.

Awk Traps

Accustomed awk users should take special note of the following:

  • A Perl program executes only once, not once for each input line. You can do an implicit loop with -n or -p.

  • The English module, loaded via

        use English;

    allows you to refer to special variables (like $/) with names (like $RS), as though they were in awk; see the perlvar manpage for details.

  • Semicolons are required after all simple statements in Perl (except at the end of a block). Newline is not a statement delimiter.

  • Curly brackets are required on ifs and whiles.

  • Variables begin with "$", "@" or "%" in Perl.

  • Arrays index from 0. Likewise string positions in substr() and index().

  • You have to decide whether your array has numeric or string indices.

  • Hash values do not spring into existence upon mere reference.

  • You have to decide whether you want to use string or numeric comparisons.

  • Reading an input line does not split it for you. You get to split it to an array yourself. And the split() operator has different arguments than awk's.

  • The current input line is normally in $_, not $0. It generally does not have the newline stripped. ($0 is the name of the program executed.) See the perlvar manpage.

  • $<digit> does not refer to fields--it refers to substrings matched by the last match pattern.

  • The print() statement does not add field and record separators unless you set $, and $\. You can set $OFS and $ORS if you're using the English module.

  • You must open your files before you print to them.

  • The range operator is "..", not comma. The comma operator works as in C.

  • The match operator is "=~", not "~". ("~" is the one's complement operator, as in C.)

  • The exponentiation operator is "**", not "^". "^" is the XOR operator, as in C. (You know, one could get the feeling that awk is basically incompatible with C.)

  • The concatenation operator is ".", not the null string. (Using the null string would render /pat/ /pat/ unparsable, because the third slash would be interpreted as a division operator--the tokenizer is in fact slightly context sensitive for operators like "/", "?", and ">". And in fact, "." itself can be the beginning of a number.)

  • The next, exit, and continue keywords work differently.

  • The following variables work differently:

          Awk       Perl
      ARGC      scalar @ARGV (compare with $#ARGV)
      ARGV[0]   $0
      FILENAME  $ARGV
      FNR       $. - something
      FS        (whatever you like)
      NF        $#Fld, or some such
      NR        $.
      OFMT      $#
      OFS       $,
      ORS       $\
      RLENGTH   length($&)
      RS        $/
      RSTART    length($`)
      SUBSEP    $;

  • You cannot set $RS to a pattern, only a string.

  • When in doubt, run the awk construct through a2p and see what it gives you.

C/C++ Traps

Cerebral C and C++ programmers should take note of the following:

  • Curly brackets are required on if's and while's.

  • You must use elsif rather than else if.

  • The break and continue keywords from C become in Perl last and next, respectively. Unlike in C, these do not work within a do { } while construct. See Loop Control in the perlsyn manpage.

  • There's no switch statement. (But it's easy to build one on the fly, see Basic BLOCKs and Switch Statements in the perlsyn manpage)

  • Variables begin with "$", "@" or "%" in Perl.

  • Comments begin with "#", not "/*" or "//". Perl may interpret C/C++ comments as division operators, unterminated regular expressions or the defined-or operator.

  • You can't take the address of anything, although a similar operator in Perl is the backslash, which creates a reference.

  • ARGV must be capitalized. $ARGV[0] is C's argv[1], and argv[0] ends up in $0.

  • System calls such as link(), unlink(), rename(), etc. return nonzero for success, not 0. (system(), however, returns zero for success.)

  • Signal handlers deal with signal names, not numbers. Use kill -l to find their names on your system.

Sed Traps

Seasoned sed programmers should take note of the following:

  • A Perl program executes only once, not once for each input line. You can do an implicit loop with -n or -p.

  • Backreferences in substitutions use "$" rather than "\".

  • The pattern matching metacharacters "(", ")", and "|" do not have backslashes in front.

  • The range operator is ..., rather than comma.

Shell Traps

Sharp shell programmers should take note of the following:

  • The backtick operator does variable interpolation without regard to the presence of single quotes in the command.

  • The backtick operator does no translation of the return value, unlike csh.

  • Shells (especially csh) do several levels of substitution on each command line. Perl does substitution in only certain constructs such as double quotes, backticks, angle brackets, and search patterns.

  • Shells interpret scripts a little bit at a time. Perl compiles the entire program before executing it (except for BEGIN blocks, which execute at compile time).

  • The arguments are available via @ARGV, not $1, $2, etc.

  • The environment is not automatically made available as separate scalar variables.

  • The shell's test uses "=", "!=", "<" etc for string comparisons and "-eq", "-ne", "-lt" etc for numeric comparisons. This is the reverse of Perl, which uses eq, ne, lt for string comparisons, and ==, != < etc for numeric comparisons.

Perl Traps

Practicing Perl Programmers should take note of the following:

  • Remember that many operations behave differently in a list context than they do in a scalar one. See the perldata manpage for details.

  • Avoid barewords if you can, especially all lowercase ones. You can't tell by just looking at it whether a bareword is a function or a string. By using quotes on strings and parentheses on function calls, you won't ever get them confused.

  • You cannot discern from mere inspection which builtins are unary operators (like chop() and chdir()) and which are list operators (like print() and unlink()). (Unless prototyped, user-defined subroutines can only be list operators, never unary ones.) See the perlop manpage and the perlsub manpage.

  • People have a hard time remembering that some functions default to $_, or @ARGV, or whatever, but that others which you might expect to do not.

  • The <FH> construct is not the name of the filehandle, it is a readline operation on that handle. The data read is assigned to $_ only if the file read is the sole condition in a while loop:

        while (<FH>)      { }
    while (defined($_ = <FH>)) { }..
    <FH>;  # data discarded!

  • Remember not to use = when you need =~; these two constructs are quite different:

        $x =  /foo/;
    $x =~ /foo/;

  • The do {} construct isn't a real loop that you can use loop control on.

  • Use my() for local variables whenever you can get away with it (but see the perlform manpage for where you can't). Using local() actually gives a local value to a global variable, which leaves you open to unforeseen side-effects of dynamic scoping.

  • If you localize an exported variable in a module, its exported value will not change. The local name becomes an alias to a new value but the external name is still an alias for the original.

Perl4 to Perl5 Traps

Practicing Perl4 Programmers should take note of the following Perl4-to-Perl5 specific traps.

They're crudely ordered according to the following list:

Discontinuance, Deprecation, and BugFix traps

Anything that's been fixed as a perl4 bug, removed as a perl4 feature or deprecated as a perl4 feature with the intent to encourage usage of some other perl5 feature.

Parsing Traps

Traps that appear to stem from the new parser.

Numerical Traps

Traps having to do with numerical or mathematical operators.

General data type traps

Traps involving perl standard data types.

Context Traps - scalar, list contexts

Traps related to context within lists, scalar statements/declarations.

Precedence Traps

Traps related to the precedence of parsing, evaluation, and execution of code.

General Regular Expression Traps using s///, etc.

Traps related to the use of pattern matching.

Subroutine, Signal, Sorting Traps

Traps related to the use of signals and signal handlers, general subroutines, and sorting, along with sorting subroutines.

OS Traps

OS-specific traps.

DBM Traps

Traps specific to the use of dbmopen(), and specific dbm implementations.

Unclassified Traps

Everything else.

If you find an example of a conversion trap that is not listed here, please submit it to <perlbug@perl.org> for inclusion. Also note that at least some of these can be caught with the use warnings pragma or the -w switch.

Discontinuance, Deprecation, and BugFix traps

Anything that has been discontinued, deprecated, or fixed as a bug from perl4.

  • Symbols starting with "_" no longer forced into main

    Symbols starting with "_" are no longer forced into package main, except for $_ itself (and @_, etc.).

        package test;
    $_legacy = 1;

        package main;
    print "\$_legacy is ",$_legacy,"\n";

        # perl4 prints: $_legacy is 1
    # perl5 prints: $_legacy is
  • Double-colon valid package separator in variable name

    Double-colon is now a valid package separator in a variable name. Thus these behave differently in perl4 vs. perl5, because the packages don't exist.

        $a=1;$b=2;$c=3;$var=4;
    print "$a::$b::$c ";
    print "$var::abc::xyz\n";

        # perl4 prints: 1::2::3 4::abc::xyz
    # perl5 prints: 3

    Given that :: is now the preferred package delimiter, it is debatable whether this should be classed as a bug or not. (The older package delimiter, ' ,is used here)

        $x = 10;
    print "x=${'x}\n";

        # perl4 prints: x=10
    # perl5 prints: Can't find string terminator "'" anywhere before EOF

    You can avoid this problem, and remain compatible with perl4, if you always explicitly include the package name:

        $x = 10;
    print "x=${main'x}\n";

    Also see precedence traps, for parsing $:.

  • 2nd and 3rd args to splice() are now in scalar context

    The second and third arguments of splice() are now evaluated in scalar context (as the Camel says) rather than list context.

        sub sub1{return(0,2) }          # return a 2-element list
    sub sub2{ return(1,2,3)}        # return a 3-element list
    @a1 = ("a","b","c","d","e");
    @a2 = splice(@a1,&sub1,&sub2);
    print join(' ',@a2),"\n";

        # perl4 prints: a b
    # perl5 prints: c d e
  • Can't do goto into a block that is optimized away

    You can't do a goto into a block that is optimized away. Darn.

        goto marker1;

        for(1){
    marker1:
        print "Here I is!\n";
    }

        # perl4 prints: Here I is!
    # perl5 errors: Can't "goto" into the middle of a foreach loop
  • Can't use whitespace as variable name or quote delimiter

    It is no longer syntactically legal to use whitespace as the name of a variable, or as a delimiter for any kind of quote construct. Double darn.

        $a = ("foo bar");
    $b = q baz;
    print "a is $a, b is $b\n";

        # perl4 prints: a is foo bar, b is baz
    # perl5 errors: Bareword found where operator expected
  • while/if BLOCK BLOCK gone

    The archaic while/if BLOCK BLOCK syntax is no longer supported.

        if { 1 } {
        print "True!";
    }
    else {
        print "False!";
    }

        # perl4 prints: True!
    # perl5 errors: syntax error at test.pl line 1, near "if {"
  • ** binds tighter than unary minus

    The ** operator now binds more tightly than unary minus. It was documented to work this way before, but didn't.

        print -4**2,"\n";

        # perl4 prints: 16
    # perl5 prints: -16
  • foreach changed when iterating over a list

    The meaning of foreach{} has changed slightly when it is iterating over a list which is not an array. This used to assign the list to a temporary array, but no longer does so (for efficiency). This means that you'll now be iterating over the actual values, not over copies of the values. Modifications to the loop variable can change the original values.

        @list = ('ab','abc','bcd','def');
    foreach $var (grep(/ab/,@list)){
        $var = 1;
    }
    print (join(':',@list));

        # perl4 prints: ab:abc:bcd:def
    # perl5 prints: 1:1:bcd:def

    To retain Perl4 semantics you need to assign your list explicitly to a temporary array and then iterate over that. For example, you might need to change

        foreach $var (grep(/ab/,@list)){

    to

        foreach $var (@tmp = grep(/ab/,@list)){

    Otherwise changing $var will clobber the values of @list. (This most often happens when you use $_ for the loop variable, and call subroutines in the loop that don't properly localize $_.)

  • split with no args behavior changed

    split with no arguments now behaves like split ' ' (which doesn't return an initial null field if $_ starts with whitespace), it used to behave like split /\s+/ (which does).

        $_ = ' hi mom';
    print join(':', split);

        # perl4 prints: :hi:mom
    # perl5 prints: hi:mom
  • -e behavior fixed

    Perl 4 would ignore any text which was attached to an -e switch, always taking the code snippet from the following arg. Additionally, it would silently accept an -e switch without a following arg. Both of these behaviors have been fixed.

        perl -e'print "attached to -e"' 'print "separate arg"'
        # perl4 prints: separate arg
    # perl5 prints: attached to -e

        perl -e
        # perl4 prints:
    # perl5 dies: No code specified for -e.
  • push returns number of elements in resulting list

    In Perl 4 the return value of push was undocumented, but it was actually the last value being pushed onto the target list. In Perl 5 the return value of push is documented, but has changed, it is the number of elements in the resulting list.

        @x = ('existing');
    print push(@x, 'first new', 'second new');

        # perl4 prints: second new
    # perl5 prints: 3
  • Some error messages differ

    Some error messages will be different.

  • split() honors subroutine args

    In Perl 4, if in list context the delimiters to the first argument of split() were ??, the result would be placed in @_ as well as being returned. Perl 5 has more respect for your subroutine arguments.

  • Bugs removed

    Some bugs may have been inadvertently removed. :-)

Parsing Traps

Perl4-to-Perl5 traps from having to do with parsing.

  • Space between . and = triggers syntax error

    Note the space between . and =

        $string . = "more string";
    print $string;

        # perl4 prints: more string
    # perl5 prints: syntax error at - line 1, near ". ="
  • Better parsing in perl 5

    Better parsing in perl 5

        sub foo {}
    &foo
    print("hello, world\n");

        # perl4 prints: hello, world
    # perl5 prints: syntax error
  • Function parsing

    "if it looks like a function, it is a function" rule.

      print
    ($foo == 1) ? "is one\n" : "is zero\n";

        # perl4 prints: is zero
    # perl5 warns: "Useless use of a constant in void context" if using -w
  • String interpolation of $#array differs

    String interpolation of the $#array construct differs when braces are to used around the name.

        @a = (1..3);
    print "${#a}";

        # perl4 prints: 2
    # perl5 fails with syntax error

        @ = (1..3);
    print "$#{a}";

        # perl4 prints: {a}
    # perl5 prints: 2
  • Perl guesses on map, grep followed by { if it starts BLOCK or hash ref

    When perl sees map { (or grep {), it has to guess whether the { starts a BLOCK or a hash reference. If it guesses wrong, it will report a syntax error near the } and the missing (or unexpected) comma.

    Use unary + before { on a hash reference, and unary + applied to the first thing in a BLOCK (after {), for perl to guess right all the time. (See map in the perlfunc manpage.)

Numerical Traps

Perl4-to-Perl5 traps having to do with numerical operators, operands, or output from same.

  • Formatted output and significant digits

    Formatted output and significant digits. In general, Perl 5 tries to be more precise. For example, on a Solaris Sparc:

        print 7.373504 - 0, "\n";
    printf "%20.18f\n", 7.373504 - 0;

        # Perl4 prints:
    7.3750399999999996141
    7.375039999999999614
        # Perl5 prints:
    7.373504
    7.375039999999999614

    Notice how the first result looks better in Perl 5.

    Your results may vary, since your floating point formatting routines and even floating point format may be slightly different.

  • Auto-increment operator over signed int limit deleted

    This specific item has been deleted. It demonstrated how the auto-increment operator would not catch when a number went over the signed int limit. Fixed in version 5.003_04. But always be wary when using large integers. If in doubt:

       use Math::BigInt;
  • Assignment of return values from numeric equality tests doesn't work

    Assignment of return values from numeric equality tests does not work in perl5 when the test evaluates to false (0). Logical tests now return a null, instead of 0

        $p = ($test == 1);
    print $p,"\n";

        # perl4 prints: 0
    # perl5 prints:

    Also see General Regular Expression Traps using s///, etc. for another example of this new feature...

  • Bitwise string ops

    When bitwise operators which can operate upon either numbers or strings (& | ^ ~) are given only strings as arguments, perl4 would treat the operands as bitstrings so long as the program contained a call to the vec() function. perl5 treats the string operands as bitstrings. (See Bitwise String Operators in the perlop manpage for more details.)

        $fred = "10";
    $barney = "12";
    $betty = $fred & $barney;
    print "$betty\n";
    # Uncomment the next line to change perl4's behavior
    # ($dummy) = vec("dummy", 0, 0);

        # Perl4 prints:
    8
        # Perl5 prints:
    10
        # If vec() is used anywhere in the program, both print:
    10

General data type traps

Perl4-to-Perl5 traps involving most data-types, and their usage within certain expressions and/or context.

  • Negative array subscripts now count from the end of array

    Negative array subscripts now count from the end of the array.

        @a = (1, 2, 3, 4, 5);
    print "The third element of the array is $a[3] also expressed as $a[-2] \n";

        # perl4 prints: The third element of the array is 4 also expressed as
    # perl5 prints: The third element of the array is 4 also expressed as 4
  • Setting $#array lower now discards array elements

    Setting $#array lower now discards array elements, and makes them impossible to recover.

        @a = (a,b,c,d,e);
    print "Before: ",join('',@a);
    $#a =1;
    print ", After: ",join('',@a);
    $#a =3;
    print ", Recovered: ",join('',@a),"\n";

        # perl4 prints: Before: abcde, After: ab, Recovered: abcd
    # perl5 prints: Before: abcde, After: ab, Recovered: ab
  • Hashes get defined before use

    Hashes get defined before use

        local($s,@a,%h);
    die "scalar \$s defined" if defined($s);
    die "array \@a defined" if defined(@a);
    die "hash \%h defined" if defined(%h);

        # perl4 prints:
    # perl5 dies: hash %h defined

    Perl will now generate a warning when it sees defined(@a) and defined(%h).

  • Glob assignment from localized variable to variable

    glob assignment from variable to variable will fail if the assigned variable is localized subsequent to the assignment

        @a = ("This is Perl 4");
    *b = *a;
    local(@a);
    print @b,"\n";

        # perl4 prints: This is Perl 4
    # perl5 prints:
  • Assigning undef to glob

    Assigning undef to a glob has no effect in Perl 5. In Perl 4 it undefines the associated scalar (but may have other side effects including SEGVs). Perl 5 will also warn if undef is assigned to a typeglob. (Note that assigning undef to a typeglob is different than calling the undef function on a typeglob (undef *foo), which has quite a few effects.

        $foo = "bar";
    *foo = undef;
    print $foo;

        # perl4 prints:
    # perl4 warns: "Use of uninitialized variable" if using -w
    # perl5 prints: bar
    # perl5 warns: "Undefined value assigned to typeglob" if using -w
  • Changes in unary negation (of strings)

    Changes in unary negation (of strings) This change effects both the return value and what it does to auto(magic)increment.

        $x = "aaa";
    print ++$x," : ";
    print -$x," : ";
    print ++$x,"\n";

        # perl4 prints: aab : -0 : 1
    # perl5 prints: aab : -aab : aac
  • Modifying of constants prohibited

    perl 4 lets you modify constants:

        $foo = "x";
    &mod($foo);
    for ($x = 0; $x < 3; $x++) {
        &mod("a");
    }
    sub mod {
        print "before: $_[0]";
        $_[0] = "m";
        print "  after: $_[0]\n";
    }

        # perl4:
    # before: x  after: m
    # before: a  after: m
    # before: m  after: m
    # before: m  after: m

        # Perl5:
    # before: x  after: m
    # Modification of a read-only value attempted at foo.pl line 12.
    # before: a
  • defined $var behavior changed

    The behavior is slightly different for:

        print "$x", defined $x
        # perl 4: 1
    # perl 5: <no output, $x is not called into existence>
  • Variable Suicide

    Variable suicide behavior is more consistent under Perl 5. Perl5 exhibits the same behavior for hashes and scalars, that perl4 exhibits for only scalars.

        $aGlobal{ "aKey" } = "global value";
    print "MAIN:", $aGlobal{"aKey"}, "\n";
    $GlobalLevel = 0;
    &test( *aGlobal );

        sub test {
        local( *theArgument ) = @_;
        local( %aNewLocal ); # perl 4 != 5.001l,m
        $aNewLocal{"aKey"} = "this should never appear";
        print "SUB: ", $theArgument{"aKey"}, "\n";
        $aNewLocal{"aKey"} = "level $GlobalLevel";   # what should print
        $GlobalLevel++;
        if( $GlobalLevel<4 ) {
            &test( *aNewLocal );
        }
    }

        # Perl4:
    # MAIN:global value
    # SUB: global value
    # SUB: level 0
    # SUB: level 1
    # SUB: level 2

        # Perl5:
    # MAIN:global value
    # SUB: global value
    # SUB: this should never appear
    # SUB: this should never appear
    # SUB: this should never appear

Context Traps - scalar, list contexts

  • Elements of argument lists for formats evaluated in list context

    The elements of argument lists for formats are now evaluated in list context. This means you can interpolate list values now.

        @fmt = ("foo","bar","baz");
    format STDOUT=
    @<<<<< @||||| @>>>>>
    @fmt;
    .
    write;

        # perl4 errors:  Please use commas to separate fields in file
    # perl5 prints: foo     bar      baz
  • caller() returns false value in scalar context if no caller present

    The caller() function now returns a false value in a scalar context if there is no caller. This lets library files determine if they're being required.

        caller() ? (print "You rang?\n") : (print "Got a 0\n");

        # perl4 errors: There is no caller
    # perl5 prints: Got a 0
  • Comma operator in scalar context gives scalar context to args

    The comma operator in a scalar context is now guaranteed to give a scalar context to its arguments.

        @y= ('a','b','c');
    $x = (1, 2, @y);
    print "x = $x\n";

        # Perl4 prints:  x = c   # Thinks list context interpolates list
    # Perl5 prints:  x = 3   # Knows scalar uses length of list
  • sprintf() prototyped as ($;@)

    sprintf() is prototyped as ($;@), so its first argument is given scalar context. Thus, if passed an array, it will probably not do what you want, unlike Perl 4:

        @z = ('%s%s', 'foo', 'bar');
    $x = sprintf(@z);
    print $x;

        # perl4 prints: foobar
    # perl5 prints: 3

    printf() works the same as it did in Perl 4, though:

        @z = ('%s%s', 'foo', 'bar');
    printf STDOUT (@z);

        # perl4 prints: foobar
    # perl5 prints: foobar

Precedence Traps

Perl4-to-Perl5 traps involving precedence order.

Perl 4 has almost the same precedence rules as Perl 5 for the operators that they both have. Perl 4 however, seems to have had some inconsistencies that made the behavior differ from what was documented.

  • LHS vs. RHS of any assignment operator

    LHS vs. RHS of any assignment operator. LHS is evaluated first in perl4, second in perl5; this can affect the relationship between side-effects in sub-expressions.

        @arr = ( 'left', 'right' );
    $a{shift @arr} = shift @arr;
    print join( ' ', keys %a );

        # perl4 prints: left
    # perl5 prints: right
  • Semantic errors introduced due to precedence

    These are now semantic errors because of precedence:

        @list = (1,2,3,4,5);
    %map = ("a",1,"b",2,"c",3,"d",4);
    $n = shift @list + 2;   # first item in list plus 2
    print "n is $n, ";
    $m = keys %map + 2;     # number of items in hash plus 2
    print "m is $m\n";

        # perl4 prints: n is 3, m is 6
    # perl5 errors and fails to compile
  • Precedence of assignment operators same as the precedence of assignment

    The precedence of assignment operators is now the same as the precedence of assignment. Perl 4 mistakenly gave them the precedence of the associated operator. So you now must parenthesize them in expressions like

        /foo/ ? ($a += 2) : ($a -= 2);

    Otherwise

        /foo/ ? $a += 2 : $a -= 2

    would be erroneously parsed as

        (/foo/ ? $a += 2 : $a) -= 2;

    On the other hand,

        $a += /foo/ ? 1 : 2;

    now works as a C programmer would expect.

  • open requires parentheses around filehandle
        open FOO || die;

    is now incorrect. You need parentheses around the filehandle. Otherwise, perl5 leaves the statement as its default precedence:

        open(FOO || die);

        # perl4 opens or dies
    # perl5 opens FOO, dying only if 'FOO' is false, i.e. never
  • $: precedence over $:: gone

    perl4 gives the special variable, $: precedence, where perl5 treats $:: as main package

        $a = "x"; print "$::a";

        # perl 4 prints: -:a
    # perl 5 prints: x
  • Precedence of file test operators documented

    perl4 had buggy precedence for the file test operators vis-a-vis the assignment operators. Thus, although the precedence table for perl4 leads one to believe -e $foo .= "q" should parse as ((-e $foo) .= "q"), it actually parses as (-e ($foo .= "q")). In perl5, the precedence is as documented.

        -e $foo .= "q"
        # perl4 prints: no output
    # perl5 prints: Can't modify -e in concatenation
  • keys, each, values are regular named unary operators

    In perl4, keys(), each() and values() were special high-precedence operators that operated on a single hash, but in perl5, they are regular named unary operators. As documented, named unary operators have lower precedence than the arithmetic and concatenation operators + - ., but the perl4 variants of these operators actually bind tighter than + - .. Thus, for:

        %foo = 1..10;
    print keys %foo - 1

        # perl4 prints: 4
    # perl5 prints: Type of arg 1 to keys must be hash (not subtraction)

    The perl4 behavior was probably more useful, if less consistent.

General Regular Expression Traps using s///, etc.

All types of RE traps.

  • s'$lhs'$rhs' interpolates on either side

    s'$lhs'$rhs' now does no interpolation on either side. It used to interpolate $lhs but not $rhs. (And still does not match a literal '$' in string)

        $a=1;$b=2;
    $string = '1 2 $a $b';
    $string =~ s'$a'$b';
    print $string,"\n";

        # perl4 prints: $b 2 $a $b
    # perl5 prints: 1 2 $a $b
  • m//g attaches its state to the searched string

    m//g now attaches its state to the searched string rather than the regular expression. (Once the scope of a block is left for the sub, the state of the searched string is lost)

        $_ = "ababab";
    while(m/ab/g){
        &doit("blah");
    }
    sub doit{local($_) = shift; print "Got $_ "}

        # perl4 prints: Got blah Got blah Got blah Got blah
    # perl5 prints: infinite loop blah...
  • m//o used within an anonymous sub

    Currently, if you use the m//o qualifier on a regular expression within an anonymous sub, all closures generated from that anonymous sub will use the regular expression as it was compiled when it was used the very first time in any such closure. For instance, if you say

        sub build_match {
        my($left,$right) = @_;
        return sub { $_[0] =~ /$left stuff $right/o; };
    }
    $good = build_match('foo','bar');
    $bad = build_match('baz','blarch');
    print $good->('foo stuff bar') ? "ok\n" : "not ok\n";
    print $bad->('baz stuff blarch') ? "ok\n" : "not ok\n";
    print $bad->('foo stuff bar') ? "not ok\n" : "ok\n";

    For most builds of Perl5, this will print: ok not ok not ok

    build_match() will always return a sub which matches the contents of $left and $right as they were the first time that build_match() was called, not as they are in the current call.

  • $+ isn't set to whole match

    If no parentheses are used in a match, Perl4 sets $+ to the whole match, just like $&. Perl5 does not.

        "abcdef" =~ /b.*e/;
    print "\$+ = $+\n";

        # perl4 prints: bcde
    # perl5 prints:
  • Substitution now returns null string if it fails

    substitution now returns the null string if it fails

        $string = "test";
    $value = ($string =~ s/foo//);
    print $value, "\n";

        # perl4 prints: 0
    # perl5 prints:

    Also see Numerical Traps for another example of this new feature.

  • s`lhs`rhs` is now a normal substitution

    s`lhs`rhs` (using backticks) is now a normal substitution, with no backtick expansion

        $string = "";
    $string =~ s`^`hostname`;
    print $string, "\n";

        # perl4 prints: <the local hostname>
    # perl5 prints: hostname
  • Stricter parsing of variables in regular expressions

    Stricter parsing of variables used in regular expressions

        s/^([^$grpc]*$grpc[$opt$plus$rep]?)//o;

        # perl4: compiles w/o error
    # perl5: with Scalar found where operator expected ..., near "$opt$plus"

    an added component of this example, apparently from the same script, is the actual value of the s'd string after the substitution. [$opt] is a character class in perl4 and an array subscript in perl5

        $grpc = 'a';
    $opt  = 'r';
    $_ = 'bar';
    s/^([^$grpc]*$grpc[$opt]?)/foo/;
    print;

        # perl4 prints: foo
    # perl5 prints: foobar
  • m?x? matches only once

    Under perl5, m?x? matches only once, like ?x?. Under perl4, it matched repeatedly, like /x/ or m!x!.

        $test = "once";
    sub match { $test =~ m?once?; }
    &match();
    if( &match() ) {
        # m?x? matches more then once
        print "perl4\n";
    } else {
        # m?x? matches only once
        print "perl5\n";
    }

        # perl4 prints: perl4
    # perl5 prints: perl5
  • Failed matches don't reset the match variables

    Unlike in Ruby, failed matches in Perl do not reset the match variables ($1, $2, ..., $`, ...).

Subroutine, Signal, Sorting Traps

The general group of Perl4-to-Perl5 traps having to do with Signals, Sorting, and their related subroutines, as well as general subroutine traps. Includes some OS-Specific traps.

  • Barewords that used to look like strings look like subroutine calls

    Barewords that used to look like strings to Perl will now look like subroutine calls if a subroutine by that name is defined before the compiler sees them.

        sub SeeYa { warn"Hasta la vista, baby!" }
    $SIG{'TERM'} = SeeYa;
    print "SIGTERM is now $SIG{'TERM'}\n";

        # perl4 prints: SIGTERM is now main'SeeYa
    # perl5 prints: SIGTERM is now main::1 (and warns "Hasta la vista, baby!")

    Use -w to catch this one

  • Reverse is no longer allowed as the name of a sort subroutine

    reverse is no longer allowed as the name of a sort subroutine.

        sub reverse{ print "yup "; $a <=> $b }
    print sort reverse (2,1,3);

        # perl4 prints: yup yup 123
    # perl5 prints: 123
    # perl5 warns (if using -w): Ambiguous call resolved as CORE::reverse()
  • warn() won't let you specify a filehandle.

    Although it _always_ printed to STDERR, warn() would let you specify a filehandle in perl4. With perl5 it does not.

        warn STDERR "Foo!";

        # perl4 prints: Foo!
    # perl5 prints: String found where operator expected

OS Traps

  • SysV resets signal handler correctly

    Under HPUX, and some other SysV OSes, one had to reset any signal handler, within the signal handler function, each time a signal was handled with perl4. With perl5, the reset is now done correctly. Any code relying on the handler _not_ being reset will have to be reworked.

    Since version 5.002, Perl uses sigaction() under SysV.

        sub gotit {
        print "Got @_... ";
    }
    $SIG{'INT'} = 'gotit';

        $| = 1;
    $pid = fork;
    if ($pid) {
        kill('INT', $pid);
        sleep(1);
        kill('INT', $pid);
    } else {
        while (1) {sleep(10);}
    }

        # perl4 (HPUX) prints: Got INT...
    # perl5 (HPUX) prints: Got INT... Got INT...
  • SysV seek() appends correctly

    Under SysV OSes, seek() on a file opened to append >> now does the right thing w.r.t. the fopen() manpage. e.g., - When a file is opened for append, it is impossible to overwrite information already in the file.

        open(TEST,">>seek.test");
    $start = tell TEST;
    foreach(1 .. 9){
        print TEST "$_ ";
    }
    $end = tell TEST;
    seek(TEST,$start,0);
    print TEST "18 characters here";

        # perl4 (solaris) seek.test has: 18 characters here
    # perl5 (solaris) seek.test has: 1 2 3 4 5 6 7 8 9 18 characters here

Interpolation Traps

Perl4-to-Perl5 traps having to do with how things get interpolated within certain expressions, statements, contexts, or whatever.

  • @ always interpolates an array in double-quotish strings

    @ now always interpolates an array in double-quotish strings.

        print "To: someone@somewhere.com\n";

        # perl4 prints: To:someone@somewhere.com
    # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere
    # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string
  • Double-quoted strings may no longer end with an unescaped $

    Double-quoted strings may no longer end with an unescaped $.

        $foo = "foo$";
    print "foo is $foo\n";

        # perl4 prints: foo is foo$
    # perl5 errors: Final $ should be \$ or $name

    Note: perl5 DOES NOT error on the terminating @ in $bar

  • Arbitrary expressions are evaluated inside braces within double quotes

    Perl now sometimes evaluates arbitrary expressions inside braces that occur within double quotes (usually when the opening brace is preceded by $ or @).

        @www = "buz";
    $foo = "foo";
    $bar = "bar";
    sub foo { return "bar" };
    print "|@{w.w.w}|${main'foo}|";

        # perl4 prints: |@{w.w.w}|foo|
    # perl5 prints: |buz|bar|

    Note that you can use strict; to ward off such trappiness under perl5.

  • $$x now tries to dereference $x

    The construct "this is $$x" used to interpolate the pid at that point, but now tries to dereference $x. $$ by itself still works fine, however.

        $s = "a reference";
    $x = *s;
    print "this is $$x\n";

        # perl4 prints: this is XXXx   (XXX is the current pid)
    # perl5 prints: this is a reference
  • Creation of hashes on the fly with eval "EXPR" requires protection

    Creation of hashes on the fly with eval "EXPR" now requires either both $'s to be protected in the specification of the hash name, or both curlies to be protected. If both curlies are protected, the result will be compatible with perl4 and perl5. This is a very common practice, and should be changed to use the block form of eval{} if possible.

        $hashname = "foobar";
    $key = "baz";
    $value = 1234;
    eval "\$$hashname{'$key'} = q|$value|";
    (defined($foobar{'baz'})) ?  (print "Yup") : (print "Nope");

        # perl4 prints: Yup
    # perl5 prints: Nope

    Changing

        eval "\$$hashname{'$key'} = q|$value|";

    to

        eval "\$\$hashname{'$key'} = q|$value|";

    causes the following result:

        # perl4 prints: Nope
    # perl5 prints: Yup

    or, changing to

        eval "\$$hashname\{'$key'\} = q|$value|";

    causes the following result:

        # perl4 prints: Yup
    # perl5 prints: Yup
    # and is compatible for both versions
  • Bugs in earlier perl versions

    perl4 programs which unconsciously rely on the bugs in earlier perl versions.

        perl -e '$bar=q/not/; print "This is $foo{$bar} perl5"'

        # perl4 prints: This is not perl5
    # perl5 prints: This is perl5
  • Array and hash brackets during interpolation

    You also have to be careful about array and hash brackets during interpolation.

        print "$foo["
        perl 4 prints: [
    perl 5 prints: syntax error
        print "$foo{"

        perl 4 prints: {
    perl 5 prints: syntax error

    Perl 5 is expecting to find an index or key name following the respective brackets, as well as an ending bracket of the appropriate type. In order to mimic the behavior of Perl 4, you must escape the bracket like so.

        print "$foo\[";
    print "$foo\{";
  • Interpolation of \$$foo{bar}

    Similarly, watch out for: \$$foo{bar}

        $foo = "baz";
    print "\$$foo{bar}\n";

        # perl4 prints: $baz{bar}
    # perl5 prints: $

    Perl 5 is looking for $foo{bar} which doesn't exist, but perl 4 is happy just to expand $foo to "baz" by itself. Watch out for this especially in eval's.

  • qq() string passed to eval will not find string terminator

    qq() string passed to eval

        eval qq(
        foreach \$y (keys %\$x\) {
            \$count++;
        }
    );
        # perl4 runs this ok
    # perl5 prints: Can't find string terminator ")"

DBM Traps

General DBM traps.

  • Perl5 must have been linked with same dbm/ndbm as the default for dbmopen()

    Existing dbm databases created under perl4 (or any other dbm/ndbm tool) may cause the same script, run under perl5, to fail. The build of perl5 must have been linked with the same dbm/ndbm as the default for dbmopen() to function properly without tie'ing to an extension dbm implementation.

        dbmopen (%dbm, "file", undef);
    print "ok\n";

        # perl4 prints: ok
    # perl5 prints: ok (IFF linked with -ldbm or -lndbm)
  • DBM exceeding limit on the key/value size will cause perl5 to exit immediately

    Existing dbm databases created under perl4 (or any other dbm/ndbm tool) may cause the same script, run under perl5, to fail. The error generated when exceeding the limit on the key/value size will cause perl5 to exit immediately.

        dbmopen(DB, "testdb",0600) || die "couldn't open db! $!";
    $DB{'trap'} = "x" x 1024;  # value too large for most dbm/ndbm
    print "YUP\n";

        # perl4 prints:
    dbm store returned -1, errno 28, key "trap" at - line 3.
    YUP
        # perl5 prints:
    dbm store returned -1, errno 28, key "trap" at - line 3.

Unclassified Traps

Everything else.

  • require/do trap using returned value

    If the file doit.pl has:

        sub foo {
        $rc = do "./do.pl";
        return 8;
    }
    print &foo, "\n";

    And the do.pl file has the following single line:

        return 3;

    Running doit.pl gives the following:

        # perl 4 prints: 3 (aborts the subroutine early)
    # perl 5 prints: 8

    Same behavior if you replace do with require.

  • split on empty string with LIMIT specified
        $string = '';
    @list = split(/foo/, $string, 2)

    Perl4 returns a one element list containing the empty string but Perl5 returns an empty list.

As always, if any of these are ever officially declared as bugs, they'll be fixed and removed.


perlvar - Perl predefined variables

    • Predefined Names
    • Error Indicators
    • Technical Note on the Syntax of Variable Names
  • BUGS

NAME

perlvar - Perl predefined variables

DESCRIPTION

Predefined Names

The following names have special meaning to Perl. Most punctuation names have reasonable mnemonics, or analogs in the shells. Nevertheless, if you wish to use long variable names, you need only say

    use English;

at the top of your program. This aliases all the short names to the long names in the current package. Some even have medium names, generally borrowed from awk. In general, it's best to use the

    use English '-no_match_vars';

invocation if you don't need $PREMATCH, $MATCH, or $POSTMATCH, as it avoids a certain performance hit with the use of regular expressions. See the English manpage.

Variables that depend on the currently selected filehandle may be set by calling an appropriate object method on the IO::Handle object, although this is less efficient than using the regular built-in variables. (Summary lines below for this contain the word HANDLE.) First you must say

    use IO::Handle;

after which you may use either

    method HANDLE EXPR

or more safely,

    HANDLE->method(EXPR)

Each method returns the old value of the IO::Handle attribute. The methods each take an optional EXPR, which, if supplied, specifies the new value for the IO::Handle attribute in question. If not supplied, most methods do nothing to the current value--except for autoflush(), which will assume a 1 for you, just to be different.

Because loading in the IO::Handle class is an expensive operation, you should learn how to use the regular built-in variables.

A few of these variables are considered "read-only". This means that if you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception.

You should be very careful when modifying the default values of most special variables described in this document. In most cases you want to localize these variables before changing them, since if you don't, the change may affect other modules which rely on the default values of the special variables that you have changed. This is one of the correct ways to read the whole file at once:

    open my $fh, "foo" or die $!;
    local $/; # enable localized slurp mode
    my $content = <$fh>;
    close $fh;

But the following code is quite bad:

    open my $fh, "foo" or die $!;
    undef $/; # enable slurp mode
    my $content = <$fh>;
    close $fh;

since some other module, may want to read data from some file in the default "line mode", so if the code we have just presented has been executed, the global value of $/ is now changed for any other code running inside the same Perl interpreter.

Usually when a variable is localized you want to make sure that this change affects the shortest scope possible. So unless you are already inside some short {} block, you should create one yourself. For example:

    my $content = '';
    open my $fh, "foo" or die $!;
    {
        local $/;
        $content = <$fh>;
    }
    close $fh;

Here is an example of how your own code can go broken:

    for (1..5){
        nasty_break();
        print "$_ ";
    }
    sub nasty_break {
        $_ = 5;
        # do something with $_
    }

You probably expect this code to print:

    1 2 3 4 5

but instead you get:

    5 5 5 5 5

Why? Because nasty_break() modifies $_ without localizing it first. The fix is to add local():

        local $_ = 5;

It's easy to notice the problem in such a short example, but in more complicated code you are looking for trouble if you don't localize changes to the special variables.

The following list is ordered by scalar variables first, then the arrays, then the hashes.

$ARG
$_

The default input and pattern-searching space. The following pairs are equivalent:

    while (<>) {...}    # equivalent only in while!
    while (defined($_ = <>)) {...}

    /^Subject:/
    $_ =~ /^Subject:/
    tr/a-z/A-Z/
    $_ =~ tr/a-z/A-Z/
    chomp
    chomp($_)

Here are the places where Perl will assume $_ even if you don't use it:

  • Various unary functions, including functions like ord() and int(), as well as the all file tests (-f, -d) except for -t, which defaults to STDIN.

  • Various list functions like print() and unlink().

  • The pattern matching operations m//, s///, and tr/// when used without an =~ operator.

  • The default iterator variable in a foreach loop if no other variable is supplied.

  • The implicit iterator variable in the grep() and map() functions.

  • The default place to put an input record when a <FH> operation's result is tested by itself as the sole criterion of a while test. Outside a while test, this will not happen.

(Mnemonic: underline is understood in certain operations.)

$a
$b

Special package variables when using sort(), see sort in the perlfunc manpage. Because of this specialness $a and $b don't need to be declared (using use vars, or our()) even when using the strict 'vars' pragma. Don't lexicalize them with my $a or my $b if you want to be able to use them in the sort() comparison block or function.

$<digits>

Contains the subpattern from the corresponding set of capturing parentheses from the last pattern match, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digits.) These variables are all read-only and dynamically scoped to the current BLOCK.

$MATCH
$&

The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: like & in some editors.) This variable is read-only and dynamically scoped to the current BLOCK.

The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS.

$PREMATCH
$`

The string preceding whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted string.) This variable is read-only.

The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS.

$POSTMATCH
$'

The string following whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted string.) Example:

    local $_ = 'abcdefghi';
    /def/;
    print "$`:$&:$'\n";         # prints abc:def:ghi

This variable is read-only and dynamically scoped to the current BLOCK.

The use of this variable anywhere in a program imposes a considerable performance penalty on all regular expression matches. See BUGS.

$LAST_PAREN_MATCH
$+

The text matched by the last bracket of the last successful search pattern. This is useful if you don't know which one of a set of alternative patterns matched. For example:

    /Version: (.*)|Revision: (.*)/ && ($rev = $+);

(Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK.

$^N

The text matched by the used group most-recently closed (i.e. the group with the rightmost closing parenthesis) of the last successful search pattern. (Mnemonic: the (possibly) Nested parenthesis that most recently closed.)

This is primarily used inside (?{...}) blocks for examining text recently matched. For example, to effectively capture text to a variable (in addition to $1, $2, etc.), replace (...) with

     (?:(...)(?{ $var = $^N }))

By setting and then using $var in this way relieves you from having to worry about exactly which numbered set of parentheses they are.

This variable is dynamically scoped to the current BLOCK.

@LAST_MATCH_END
@+

This array holds the offsets of the ends of the last successful submatches in the currently active dynamic scope. $+[0] is the offset into the string of the end of the entire match. This is the same value as what the pos function returns when called on the variable that was matched against. The nth element of this array holds the offset of the nth submatch, so $+[1] is the offset past where $1 ends, $+[2] the offset past where $2 ends, and so on. You can use $#+ to determine how many subgroups were in the last successful match. See the examples given for the @- variable.

$*

Set to a non-zero integer value to do multi-line matching within a string, 0 (or undefined) to tell Perl that it can assume that strings contain a single line, for the purpose of optimizing pattern matches. Pattern matches on strings containing multiple newlines can produce confusing results when $* is 0 or undefined. Default is undefined. (Mnemonic: * matches multiple things.) This variable influences the interpretation of only ^ and $. A literal newline can be searched for even when $* == 0.

Use of $* is deprecated in modern Perl, supplanted by the /s and /m modifiers on pattern matching.

Assigning a non-numerical value to $* triggers a warning (and makes $* act if $* == 0), while assigning a numerical value to $* makes that an implicit int is applied on the value.

HANDLE->input_line_number(EXPR)
$INPUT_LINE_NUMBER
$NR
$.

Current line number for the last filehandle accessed.

Each filehandle in Perl counts the number of lines that have been read from it. (Depending on the value of $/, Perl's idea of what constitutes a line may not match yours.) When a line is read from a filehandle (via readline() or <>), or when tell() or seek() is called on it, $. becomes an alias to the line counter for that filehandle.

You can adjust the counter by assigning to $., but this will not actually move the seek pointer. Localizing $. will not localize the filehandle's line count. Instead, it will localize perl's notion of which filehandle $. is currently aliased to.

$. is reset when the filehandle is closed, but not when an open filehandle is reopened without an intervening close(). For more details, see I/O Operators in the perlop manpage. Because <> never does an explicit close, line numbers increase across ARGV files (but see examples in eof in the perlfunc manpage).

You can also use HANDLE->input_line_number(EXPR) to access the line counter for a given filehandle without having to worry about which handle you last accessed.

(Mnemonic: many programs use "." to mean the current line number.)

IO::Handle->input_record_separator(EXPR)
$INPUT_RECORD_SEPARATOR
$RS
$/

The input record separator, newline by default. This influences Perl's idea of what a "line" is. Works like awk's RS variable, including treating empty lines as a terminator if set to the null string. (An empty line cannot contain any spaces or tabs.) You may set it to a multi-character string to match a multi-character terminator, or to undef to read through the end of file. Setting it to "\n\n" means something slightly different than setting to "", if the file contains consecutive empty lines. Setting to "" will treat two or more consecutive empty lines as a single empty line. Setting to "\n\n" will blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / delimits line boundaries when quoting poetry.)

    local $/;           # enable "slurp" mode
    local $_ = <FH>;    # whole file now here
    s/\n[ \t]+/ /g;

Remember: the value of $/ is a string, not a regex. awk has to be better for something. :-)

Setting $/ to a reference to an integer, scalar containing an integer, or scalar that's convertible to an integer will attempt to read records instead of lines, with the maximum record size being the referenced integer. So this:

    local $/ = \32768; # or \"32768", or \$var_containing_32768
    open my $fh, $myfile or die $!;
    local $_ = <$fh>;

will read a record of no more than 32768 bytes from FILE. If you're not reading from a record-oriented file (or your OS doesn't have record-oriented files), then you'll likely get a full chunk of data with every read. If a record is larger than the record size you've set, you'll get the record back in pieces.

On VMS, record reads are done with the equivalent of sysread, so it's best not to mix record and non-record reads on the same file. (This is unlikely to be a problem, because any file you'd want to read in record mode is probably unusable in line mode.) Non-VMS systems do normal I/O, so it's safe to mix record and non-record reads of a file.

See also Newlines in the perlport manpage. Also see $..

HANDLE->autoflush(EXPR)
$OUTPUT_AUTOFLUSH
$|

If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 (regardless of whether the channel is really buffered by the system or not; $| tells you only whether you've asked Perl explicitly to flush after each write). STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe or socket, such as when you are running a Perl program under rsh and want to see the output as it's happening. This has no effect on input buffering. See getc in the perlfunc manpage for that. (Mnemonic: when you want your pipes to be piping hot.)

IO::Handle->output_field_separator EXPR
$OUTPUT_FIELD_SEPARATOR
$OFS
$,

The output field separator for the print operator. If defined, this value is printed between each of print's arguments. Default is undef. (Mnemonic: what is printed when there is a "," in your print statement.)

IO::Handle->output_record_separator EXPR
$OUTPUT_RECORD_SEPARATOR
$ORS
$\

The output record separator for the print operator. If defined, this value is printed after the last of print's arguments. Default is undef. (Mnemonic: you set $\ instead of adding "\n" at the end of the print. Also, it's just like $/, but it's what you get "back" from Perl.)

$LIST_SEPARATOR
$"

This is like $, except that it applies to array and slice values interpolated into a double-quoted string (or similar interpreted string). Default is a space. (Mnemonic: obvious, I think.)

$SUBSCRIPT_SEPARATOR
$SUBSEP
$;

The subscript separator for multidimensional array emulation. If you refer to a hash element as

    $foo{$a,$b,$c}

it really means

    $foo{join($;, $a, $b, $c)}

But don't put

    @foo{$a,$b,$c}      # a slice--note the @

which means

    ($foo{$a},$foo{$b},$foo{$c})

Default is "\034", the same as SUBSEP in awk. If your keys contain binary data there might not be any safe value for $;. (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. Yeah, I know, it's pretty lame, but $, is already taken for something more important.)

Consider using "real" multidimensional arrays as described in the perllol manpage.

$#

The output format for printed numbers. This variable is a half-hearted attempt to emulate awk's OFMT variable. There are times, however, when awk and Perl have differing notions of what counts as numeric. The initial value is "%.ng", where n is the value of the macro DBL_DIG from your system's float.h. This is different from awk's default OFMT setting of "%.6g", so you need to set $# explicitly to get awk's value. (Mnemonic: # is the number sign.)

Use of $# is deprecated.

HANDLE->format_page_number(EXPR)
$FORMAT_PAGE_NUMBER
$%

The current page number of the currently selected output channel. Used with formats. (Mnemonic: % is page number in nroff.)

HANDLE->format_lines_per_page(EXPR)
$FORMAT_LINES_PER_PAGE
$=

The current page length (printable lines) of the currently selected output channel. Default is 60. Used with formats. (Mnemonic: = has horizontal lines.)

HANDLE->format_lines_left(EXPR)
$FORMAT_LINES_LEFT
$-

The number of lines left on the page of the currently selected output channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.)

@LAST_MATCH_START
@-

$-[0] is the offset of the start of the last successful match. $-[n] is the offset of the start of the substring matched by n-th subpattern, or undef if the subpattern did not match.

Thus after a match against $_, $& coincides with substr $_, $-[0], $+[0] - $-[0]. Similarly, $n coincides with substr $_, $-[n], $+[n] - $-[n] if $-[n] is defined, and $+ coincides with substr $_, $-[$#-], $+[$#-] - $-[$#-]. One can use $#- to find the last matched subgroup in the last successful match. Contrast with $#+, the number of subgroups in the regular expression. Compare with @+.

This array holds the offsets of the beginnings of the last successful submatches in the currently active dynamic scope. $-[0] is the offset into the string of the beginning of the entire match. The nth element of this array holds the offset of the nth submatch, so $-[1] is the offset where $1 begins, $-[2] the offset where $2 begins, and so on.

After a match against some variable $var:

$` is the same as substr($var, 0, $-[0])
$& is the same as substr($var, $-[0], $+[0] - $-[0])
$' is the same as substr($var, $+[0])
$1 is the same as substr($var, $-[1], $+[1] - $-[1])
$2 is the same as substr($var, $-[2], $+[2] - $-[2])
$3 is the same as substr($var, $-[3], $+[3] - $-[3])
HANDLE->format_name(EXPR)
$FORMAT_NAME
$~

The name of the current report format for the currently selected output channel. Default is the name of the filehandle. (Mnemonic: brother to $^.)

HANDLE->format_top_name(EXPR)
$FORMAT_TOP_NAME
$^

The name of the current top-of-page format for the currently selected output channel. Default is the name of the filehandle with _TOP appended. (Mnemonic: points to top of page.)

IO::Handle->format_line_break_characters EXPR
$FORMAT_LINE_BREAK_CHARACTERS
$:

The current set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format. Default is " \n-", to break on whitespace or hyphens. (Mnemonic: a "colon" in poetry is a part of a line.)

IO::Handle->format_formfeed EXPR
$FORMAT_FORMFEED
$^L

What formats output as a form feed. Default is \f.

$ACCUMULATOR
$^A

The current value of the write() accumulator for format() lines. A format contains formline() calls that put their result into $^A. After calling its format, write() prints out the contents of $^A and empties. So you never really see the contents of $^A unless you call formline() yourself and then look at it. See the perlform manpage and formline() in the perlfunc manpage.

$CHILD_ERROR
$?

The status returned by the last pipe close, backtick (``) command, successful call to wait() or waitpid(), or from the system() operator. This is just the 16-bit status word returned by the wait() system call (or else is made up to look like it). Thus, the exit value of the subprocess is really ($? >> 8), and $? & 127 gives which signal, if any, the process died from, and $? & 128 reports whether there was a core dump. (Mnemonic: similar to sh and ksh.)

Additionally, if the h_errno variable is supported in C, its value is returned via $? if any gethost*() function fails.

If you have installed a signal handler for SIGCHLD, the value of $? will usually be wrong outside that handler.

Inside an END subroutine $? contains the value that is going to be given to exit(). You can modify $? in an END subroutine to change the exit status of your program. For example:

    END {
        $? = 1 if $? == 255;  # die would make it 255
    }

Under VMS, the pragma use vmsish 'status' makes $? reflect the actual VMS exit status, instead of the default emulation of POSIX status; see $? in the perlvms manpage for details.

Also see Error Indicators.

${^ENCODING}

The object reference to the Encode object that is used to convert the source code to Unicode. Thanks to this variable your perl script does not have to be written in UTF-8. Default is undef. The direct manipulation of this variable is highly discouraged. See the encoding manpage for more details.

$OS_ERROR
$ERRNO
$!

If used numerically, yields the current value of the C errno variable, or in other words, if a system or library call fails, it sets this variable. This means that the value of $! is meaningful only immediately after a failure:

    if (open(FH, $filename)) {
        # Here $! is meaningless.
        ...
    } else {
        # ONLY here is $! meaningful.
        ...
        # Already here $! might be meaningless.
    }
    # Since here we might have either success or failure,
    # here $! is meaningless.

In the above meaningless stands for anything: zero, non-zero, undef. A successful system or library call does not set the variable to zero.

If used as a string, yields the corresponding system error string. You can assign a number to $! to set errno if, for instance, you want "$!" to return the string for error n, or you want to set the exit value for the die() operator. (Mnemonic: What just went bang?)

Also see Error Indicators.

%!

Each element of %! has a true value only if $! is set to that value. For example, $!{ENOENT} is true if and only if the current value of $! is ENOENT; that is, if the most recent error was "No such file or directory" (or its moral equivalent: not all operating systems give that exact error, and certainly not all languages). To check if a particular key is meaningful on your system, use exists $!{the_key}; for a list of legal keys, use keys %!. See the Errno manpage for more information, and also see above for the validity of $!.

$EXTENDED_OS_ERROR
$^E

Error information specific to the current operating system. At the moment, this differs from $! under only VMS, OS/2, and Win32 (and for MacPerl). On all other platforms, $^E is always just the same as $!.

Under VMS, $^E provides the VMS status value from the last system error. This is more specific information about the last system error than that provided by $!. This is particularly important when $! is set to EVMSERR.

Under OS/2, $^E is set to the error code of the last call to OS/2 API either via CRT, or directly from perl.

Under Win32, $^E always returns the last error information reported by the Win32 call GetLastError() which describes the last error from within the Win32 API. Most Win32-specific code will report errors via $^E. ANSI C and Unix-like calls set errno and so most portable Perl code will report errors via $!.

Caveats mentioned in the description of $! generally apply to $^E, also. (Mnemonic: Extra error explanation.)

Also see Error Indicators.

$EVAL_ERROR
$@

The Perl syntax error message from the last eval() operator. If $@ is the null string, the last eval() parsed and executed correctly (although the operations you invoked may have failed in the normal fashion). (Mnemonic: Where was the syntax error "at"?)

Warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting $SIG{__WARN__} as described below.

Also see Error Indicators.

$PROCESS_ID
$PID
$$

The process number of the Perl running this script. You should consider this variable read-only, although it will be altered across fork() calls. (Mnemonic: same as shells.)

Note for Linux users: on Linux, the C functions getpid() and getppid() return different values from different threads. In order to be portable, this behavior is not reflected by $$, whose value remains consistent across threads. If you want to call the underlying getpid(), you may use the CPAN module Linux::Pid.

$REAL_USER_ID
$UID
$<

The real uid of this process. (Mnemonic: it's the uid you came from, if you're running setuid.) You can change both the real uid and the effective uid at the same time by using POSIX::setuid(). Since changes to $< require a system call, check $! after a change attempt to detect any possible errors.

$EFFECTIVE_USER_ID
$EUID
$>

The effective uid of this process. Example:

    $< = $>;            # set real to effective uid
    ($<,$>) = ($>,$<);  # swap real and effective uid

You can change both the effective uid and the real uid at the same time by using POSIX::setuid(). Changes to $> require a check to $! to detect any possible errors after an attempted change.

(Mnemonic: it's the uid you went to, if you're running setuid.) $< and $> can be swapped only on machines supporting setreuid().

$REAL_GROUP_ID
$GID
$(

The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getgid(), and the subsequent ones by getgroups(), one of which may be the same as the first number.

However, a value assigned to $( must be a single number used to set the real gid. So the value given by $( should not be assigned back to $( without being forced numeric, such as by adding zero.

You can change both the real gid and the effective gid at the same time by using POSIX::setgid(). Changes to $( require a check to $! to detect any possible errors after an attempted change.

(Mnemonic: parentheses are used to group things. The real gid is the group you left, if you're running setgid.)

$EFFECTIVE_GROUP_ID
$EGID
$)

The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getegid(), and the subsequent ones by getgroups(), one of which may be the same as the first number.

Similarly, a value assigned to $) must also be a space-separated list of numbers. The first number sets the effective gid, and the rest (if any) are passed to setgroups(). To get the effect of an empty list for setgroups(), just repeat the new effective gid; that is, to force an effective gid of 5 and an effectively empty setgroups() list, say $) = "5 5" .

You can change both the effective gid and the real gid at the same time by using POSIX::setgid() (use only a single numeric argument). Changes to $) require a check to $! to detect any possible errors after an attempted change.

(Mnemonic: parentheses are used to group things. The effective gid is the group that's right for you, if you're running setgid.)

$<, $>, $( and $) can be set only on machines that support the corresponding set[re][ug]id() routine. $( and $) can be swapped only on machines supporting setregid().

$PROGRAM_NAME
$0

Contains the name of the program being executed.

On some (read: not all) operating systems assigning to $0 modifies the argument area that the ps program sees. On some platforms you may have to use special ps options or a different ps to see the changes. Modifying the $0 is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as sh and ksh.)

Note that there are platform specific limitations on the maximum length of $0. In the most extreme case it may be limited to the space occupied by the original $0.

In some platforms there may be arbitrary amount of padding, for example space characters, after the modified name as shown by ps. In some platforms this padding may extend all the way to the original length of the argument area, no matter what you do (this is the case for example with Linux 2.2).

Note for BSD users: setting $0 does not completely remove "perl" from the ps(1) output. For example, setting $0 to "foobar" may result in "perl: foobar (perl)" (whether both the "perl: " prefix and the " (perl)" suffix are shown depends on your exact BSD variant and version). This is an operating system feature, Perl cannot help it.

In multithreaded scripts Perl coordinates the threads so that any thread may modify its copy of the $0 and the change becomes visible to ps(1) (assuming the operating system plays along). Note that the view of $0 the other threads have will not change since they have their own copies of it.

$[

The index of the first element in an array, and of the first character in a substring. Default is 0, but you could theoretically set it to 1 to make Perl behave more like awk (or Fortran) when subscripting and when evaluating the index() and substr() functions. (Mnemonic: [ begins subscripts.)

As of release 5 of Perl, assignment to $[ is treated as a compiler directive, and cannot influence the behavior of any other file. (That's why you can only assign compile-time constants to it.) Its use is highly discouraged.

Note that, unlike other compile-time directives (such as the strict manpage), assignment to $[ can be seen from outer lexical scopes in the same file. However, you can use local() on it to strictly bind its value to a lexical block.

$]

The version + patchlevel / 1000 of the Perl interpreter. This variable can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: Is this version of perl in the right bracket?) Example:

    warn "No checksumming!\n" if $] < 3.019;

See also the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.

When testing the variable, to steer clear of floating point inaccuracies you might want to prefer the inequality tests < and > to the tests containing equivalence: <=, ==, and >=.

The floating point representation can sometimes lead to inaccurate numeric comparisons. See $^V for a more modern representation of the Perl version that allows accurate string comparisons.

$COMPILING
$^C

The current value of the flag associated with the -c switch. Mainly of use with -MO=... to allow code to alter its behavior when being compiled, such as for example to AUTOLOAD at compile time rather than normal, deferred loading. See perlcc. Setting $^C = 1 is similar to calling B::minus_c.

$DEBUGGING
$^D

The current value of the debugging flags. (Mnemonic: value of -D switch.) May be read or set. Like its command-line equivalent, you can use numeric or symbolic values, eg $^D = 10 or $^D = "st".

$SYSTEM_FD_MAX
$^F

The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails. (Ordinary file descriptors are closed before the open() is attempted.) The close-on-exec status of a file descriptor will be decided according to the value of $^F when the corresponding file, pipe, or socket was opened, not the time of the exec().

$^H

WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice.

This variable contains compile-time hints for the Perl interpreter. At the end of compilation of a BLOCK the value of this variable is restored to the value when the interpreter started to compile the BLOCK.

When perl begins to parse any block construct that provides a lexical scope (e.g., eval body, required file, subroutine body, loop body, or conditional block), the existing value of $^H is saved, but its value is left unchanged. When the compilation of the block is completed, it regains the saved value. Between the points where its value is saved and restored, code that executes within BEGIN blocks is free to change the value of $^H.

This behavior provides the semantic of lexical scoping, and is used in, for instance, the use strict pragma.

The contents should be an integer; different bits of it are used for different pragmatic flags. Here's an example:

    sub add_100 { $^H |= 0x100 }

    sub foo {
        BEGIN { add_100() }
        bar->baz($boon);
    }

Consider what happens during execution of the BEGIN block. At this point the BEGIN block has already been compiled, but the body of foo() is still being compiled. The new value of $^H will therefore be visible only while the body of foo() is being compiled.

Substitution of the above BEGIN block with:

    BEGIN { require strict; strict->import('vars') }

demonstrates how use strict 'vars' is implemented. Here's a conditional version of the same lexical pragma:

    BEGIN { require strict; strict->import('vars') if $condition }
%^H

WARNING: This variable is strictly for internal use only. Its availability, behavior, and contents are subject to change without notice.

The %^H hash provides the same scoping semantic as $^H. This makes it useful for implementation of lexically scoped pragmas.

$INPLACE_EDIT
$^I

The current value of the inplace-edit extension. Use undef to disable inplace editing. (Mnemonic: value of -i switch.)

$^M

By default, running out of memory is an untrappable, fatal error. However, if suitably built, Perl can use the contents of $^M as an emergency memory pool after die()ing. Suppose that your Perl were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then

    $^M = 'a' x (1 << 16);

would allocate a 64K buffer for use in an emergency. See the INSTALL file in the Perl distribution for information on how to add custom C compilation flags when compiling perl. To discourage casual use of this advanced feature, there is no English long name for this variable.

$OSNAME
$^O

The name of the operating system under which this copy of Perl was built, as determined during the configuration process. The value is identical to $Config{'osname'}. See also the Config manpage and the -V command-line switch documented in the perlrun manpage.

In Windows platforms, $^O is not very helpful: since it is always MSWin32, it doesn't tell the difference between 95/98/ME/NT/2000/XP/CE/.NET. Use Win32::GetOSName() or Win32::GetOSVersion() (see the Win32 manpage and the perlport manpage) to distinguish between the variants.

${^OPEN}

An internal variable used by PerlIO. A string in two parts, separated by a \0 byte, the first part describes the input layers, the second part describes the output layers.

$PERLDB
$^P

The internal variable for debugging support. The meanings of the various bits are subject to change, but currently indicate:

  1. x01

    Debug subroutine enter/exit.

  2. x02

    Line-by-line debugging.

  3. x04

    Switch off optimizations.

  4. x08

    Preserve more data for future interactive inspections.

  5. x10

    Keep info about source lines on which a subroutine is defined.

  6. x20

    Start with single-step on.

  7. x40

    Use subroutine address instead of name when reporting.

  8. x80

    Report goto &subroutine as well.

  9. x100

    Provide informative "file" names for evals based on the place they were compiled.

  10. x200

    Provide informative names to anonymous subroutines based on the place they were compiled.

  11. x400

    Debug assertion subroutines enter/exit.

Some bits may be relevant at compile-time only, some at run-time only. This is a new mechanism and the details may change.

$LAST_REGEXP_CODE_RESULT
$^R

The result of evaluation of the last successful (?{ code }) regular expression assertion (see the perlre manpage). May be written to.

$EXCEPTIONS_BEING_CAUGHT
$^S

Current state of the interpreter.

    $^S         State
    ---------   -------------------
    undef       Parsing module/eval
    true (1)    Executing an eval
    false (0)   Otherwise

The first state may happen in $SIG{__DIE__} and $SIG{__WARN__} handlers.

$BASETIME
$^T

The time at which the program began running, in seconds since the epoch (beginning of 1970). The values returned by the -M, -A, and -C filetests are based on this value.

${^TAINT}

Reflects if taint mode is on or off. 1 for on (the program was run with -T), 0 for off, -1 when only taint warnings are enabled (i.e. with -t or -TU).

${^UNICODE}

Reflects certain Unicode settings of Perl. See the perlrun manpage documentation for the -C switch for more information about the possible values. This variable is set during Perl startup and is thereafter read-only.

${^UTF8LOCALE}

This variable indicates whether an UTF-8 locale was detected by perl at startup. This information is used by perl when it's in adjust-utf8ness-to-locale mode (as when run with the -CL command-line switch); see the perlrun manpage for more info on this.

$PERL_VERSION
$^V

The revision, version, and subversion of the Perl interpreter, represented as a string composed of characters with those ordinals. Thus in Perl v5.6.0 it equals chr(5) . chr(6) . chr(0) and will return true for $^V eq v5.6.0. Note that the characters in this string value can potentially be in Unicode range.

This can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: use ^V for Version Control.) Example:

    warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0;

To convert $^V into its string representation use sprintf()'s "%vd" conversion:

    printf "version is v%vd\n", $^V;  # Perl's version

See the documentation of use VERSION and require VERSION for a convenient way to fail if the running Perl interpreter is too old.

See also $] for an older representation of the Perl version.

$WARNING
$^W

The current value of the warning switch, initially true if -w was used, false otherwise, but directly modifiable. (Mnemonic: related to the -w switch.) See also the warnings manpage.

${^WARNING_BITS}

The current set of warning checks enabled by the use warnings pragma. See the documentation of warnings for more details.

$EXECUTABLE_NAME
$^X

The name used to execute the current copy of Perl, from C's argv[0] or (where supported) /proc/self/exe.

Depending on the host operating system, the value of $^X may be a relative or absolute pathname of the perl program file, or may be the string used to invoke perl but not the pathname of the perl program file. Also, most operating systems permit invoking programs that are not in the PATH environment variable, so there is no guarantee that the value of $^X is in PATH. For VMS, the value may or may not include a version number.

You usually can use the value of $^X to re-invoke an independent copy of the same perl that is currently running, e.g.,

  @first_run = `$^X -le "print int rand 100 for 1..100"`;

But recall that not all operating systems support forking or capturing of the output of commands, so this complex statement may not be portable.

It is not safe to use the value of $^X as a path name of a file, as some operating systems that have a mandatory suffix on executable files do not require use of the suffix when invoking a command. To convert the value of $^X to a path name, use the following statements:

  # Build up a set of file names (not command names).
  use Config;
  $this_perl = $^X;
  if ($^O ne 'VMS')
     {$this_perl .= $Config{_exe}
          unless $this_perl =~ m/$Config{_exe}$/i;}

Because many operating systems permit anyone with read access to the Perl program file to make a copy of it, patch the copy, and then execute the copy, the security-conscious Perl programmer should take care to invoke the installed copy of perl, not the copy referenced by $^X. The following statements accomplish this goal, and produce a pathname that can be invoked as a command or referenced as a file.

  use Config;
  $secure_perl_path = $Config{perlpath};
  if ($^O ne 'VMS')
     {$secure_perl_path .= $Config{_exe}
          unless $secure_perl_path =~ m/$Config{_exe}$/i;}
ARGV

The special filehandle that iterates over command-line filenames in @ARGV. Usually written as the null filehandle in the angle operator <>. Note that currently ARGV only has its magical effect within the <> operator; elsewhere it is just a plain filehandle corresponding to the last file opened by <>. In particular, passing \*ARGV as a parameter to a function that expects a filehandle may not cause your function to automatically read the contents of all the files in @ARGV.

$ARGV

contains the name of the current file when reading from <>.

@ARGV

The array @ARGV contains the command-line arguments intended for the script. $#ARGV is generally the number of arguments minus one, because $ARGV[0] is the first argument, not the program's command name itself. See $0 for the command name.

ARGVOUT

The special filehandle that points to the currently open output file when doing edit-in-place processing with -i. Useful when you have to do a lot of inserting and don't want to keep modifying $_. See the perlrun manpage for the -i switch.

@F

The array @F contains the fields of each line read in when autosplit mode is turned on. See the perlrun manpage for the -a switch. This array is package-specific, and must be declared or given a full package name if not in package main when running under strict 'vars'.

@INC

The array @INC contains the list of places that the do EXPR, require, or use constructs look for their library files. It initially consists of the arguments to any -I command-line switches, followed by the default Perl library, probably /usr/local/lib/perl, followed by ".", to represent the current directory. ("." will not be appended if taint checks are enabled, either by -T or by -t.) If you need to modify this at runtime, you should use the use lib pragma to get the machine-dependent library properly loaded also:

    use lib '/mypath/libdir/';
    use SomeMod;

You can also insert hooks into the file inclusion system by putting Perl code directly into @INC. Those hooks may be subroutine references, array references or blessed objects. See require in the perlfunc manpage for details.

@_

Within a subroutine the array @_ contains the parameters passed to that subroutine. See the perlsub manpage.

%INC

The hash %INC contains entries for each filename included via the do, require, or use operators. The key is the filename you specified (with module names converted to pathnames), and the value is the location of the file found. The require operator uses this hash to determine whether a particular file has already been included.

If the file was loaded via a hook (e.g. a subroutine reference, see require in the perlfunc manpage for a description of these hooks), this hook is by default inserted into %INC in place of a filename. Note, however, that the hook may have set the %INC entry by itself to provide some more specific info.

%ENV
$ENV{expr}

The hash %ENV contains your current environment. Setting a value in ENV changes the environment for any child processes you subsequently fork() off.

%SIG
$SIG{expr}

The hash %SIG contains signal handlers for signals. For example:

    sub handler {       # 1st argument is signal name
        my($sig) = @_;
        print "Caught a SIG$sig--shutting down\n";
        close(LOG);
        exit(0);
    }

    $SIG{'INT'}  = \&handler;
    $SIG{'QUIT'} = \&handler;
    ...
    $SIG{'INT'}  = 'DEFAULT';   # restore default action
    $SIG{'QUIT'} = 'IGNORE';    # ignore SIGQUIT

Using a value of 'IGNORE' usually has the effect of ignoring the signal, except for the CHLD signal. See the perlipc manpage for more about this special case.

Here are some other examples:

    $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not recommended)
    $SIG{"PIPE"} = \&Plumber;   # just fine; assume current Plumber
    $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
    $SIG{"PIPE"} = Plumber();   # oops, what did Plumber() return??

Be sure not to use a bareword as the name of a signal handler, lest you inadvertently call it.

If your system has the sigaction() function then signal handlers are installed using it. This means you get reliable signal handling.

The default delivery policy of signals changed in Perl 5.8.0 from immediate (also known as "unsafe") to deferred, also known as "safe signals". See the perlipc manpage for more information.

Certain internal hooks can be also set using the %SIG hash. The routine indicated by $SIG{__WARN__} is called when a warning message is about to be printed. The warning message is passed as the first argument. The presence of a __WARN__ hook causes the ordinary printing of warnings to STDERR to be suppressed. You can use this to save warnings in a variable, or turn warnings into fatal errors, like this:

    local $SIG{__WARN__} = sub { die $_[0] };
    eval $proggie;

The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __DIE__ hook routine returns, the exception processing continues as it would have in the absence of the hook, unless the hook routine itself exits via a goto, a loop exit, or a die(). The __DIE__ handler is explicitly disabled during the call, so that you can die from a __DIE__ handler. Similarly for __WARN__.

Due to an implementation glitch, the $SIG{__DIE__} hook is called even inside an eval(). Do not use this to rewrite a pending exception in $@, or as a bizarre substitute for overriding CORE::GLOBAL::die(). This strange action at a distance may be fixed in a future release so that $SIG{__DIE__} is only called if your program is about to exit, as was the original intent. Any other use is deprecated.

__DIE__/__WARN__ handlers are very special in one respect: they may be called to report (probable) errors found by the parser. In such a case the parser may be in inconsistent state, so any attempt to evaluate Perl code from such a handler will probably result in a segfault. This means that warnings or errors that result from parsing Perl should be used with extreme caution, like this:

    require Carp if defined $^S;
    Carp::confess("Something wrong") if defined &Carp::confess;
    die "Something wrong, but could not load Carp to give backtrace...
         To see backtrace try starting Perl with -MCarp switch";

Here the first line will load Carp unless it is the parser who called the handler. The second line will print backtrace and die if Carp was available. The third line will be executed only if Carp was not available.

See die in the perlfunc manpage, warn in the perlfunc manpage, eval in the perlfunc manpage, and the warnings manpage for additional information.

Error Indicators

The variables $@, $!, $^E, and $? contain information about different types of error conditions that may appear during execution of a Perl program. The variables are shown ordered by the "distance" between the subsystem which reported the error and the Perl process. They correspond to errors detected by the Perl interpreter, C library, operating system, or an external program, respectively.

To illustrate the differences between these variables, consider the following Perl expression, which uses a single-quoted string:

    eval q{
        open my $pipe, "/cdrom/install |" or die $!;
        my @res = <$pipe>;
        close $pipe or die "bad pipe: $?, $!";
    };

After execution of this statement all 4 variables may have been set.

$@ is set if the string to be eval-ed did not compile (this may happen if open or close were imported with bad prototypes), or if Perl code executed during evaluation die()d . In these cases the value of $@ is the compile error, or the argument to die (which will interpolate $! and $?). (See also the Fatal manpage, though.)

When the eval() expression above is executed, open(), <PIPE>, and close are translated to calls in the C run-time library and thence to the operating system kernel. $! is set to the C library's errno if one of these calls fails.

Under a few operating systems, $^E may contain a more verbose error indicator, such as in this case, "CDROM tray not closed." Systems that do not support extended error messages leave $^E the same as $!.

Finally, $? may be set to non-0 value if the external program /cdrom/install fails. The upper eight bits reflect specific error conditions encountered by the program (the program's exit() value). The lower eight bits reflect mode of failure, like signal death and core dump information See wait(2) for details. In contrast to $! and $^E, which are set only if error condition is detected, the variable $? is set on each wait or pipe close, overwriting the old value. This is more like $@, which on every eval() is always set on failure and cleared on success.

For more details, see the individual descriptions at $@, $!, $^E, and $?.

Technical Note on the Syntax of Variable Names

Variable names in Perl can have several formats. Usually, they must begin with a letter or underscore, in which case they can be arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence :: or '. In this case, the part before the last :: or ' is taken to be a package qualifier; see the perlmod manpage.

Perl variable names may also be a sequence of digits or a single punctuation or control character. These names are all reserved for special uses by Perl; for example, the all-digits names are used to hold data captured by backreferences after a regular expression match. Perl has a special syntax for the single-control-character names: It understands ^X (caret X) to mean the control-X character. For example, the notation $^W (dollar-sign caret W) is the scalar variable whose name is the single character control-W. This is better than typing a literal control-W into your program.

Finally, new in Perl 5.6, Perl variable names may be alphanumeric strings that begin with control characters (or better yet, a caret). These variables must be written in the form ${^Foo}; the braces are not optional. ${^Foo} denotes the scalar variable whose name is a control-F followed by two o's. These variables are reserved for future special uses by Perl, except for the ones that begin with ^_ (control-underscore or caret-underscore). No control-character name that begins with ^_ will acquire a special meaning in any future version of Perl; such names may therefore be used safely in programs. $^_ itself, however, is reserved.

Perl identifiers that begin with digits, control characters, or punctuation characters are exempt from the effects of the package declaration and are always forced to be in package main; they are also exempt from strict 'vars' errors. A few other names are also exempt in these ways:

        ENV             STDIN
        INC             STDOUT
        ARGV            STDERR
        ARGVOUT         _
        SIG

In particular, the new special ${^_XYZ} variables are always taken to be in package main, regardless of any package declarations presently in scope.

BUGS

Due to an unfortunate accident of Perl's implementation, use English imposes a considerable performance penalty on all regular expression matches in a program, regardless of whether they occur in the scope of use English. For that reason, saying use English in libraries is strongly discouraged. See the Devel::SawAmpersand module documentation from CPAN ( http://www.cpan.org/modules/by-module/Devel/ ) for more information.

Having to even think about the $^S variable in your exception handlers is simply wrong. $SIG{__DIE__} as currently implemented invites grievous and difficult to track down errors. Avoid it and use an END{} or CORE::GLOBAL::die override instead.


perlmod - Perl modules

    • Packages
    • Symbol Tables
    • BEGIN, CHECK, INIT and END
    • Perl Classes
    • Perl Modules
    • Making your module threadsafe
  • SEE ALSO

NAME

perlmod - Perl modules (packages and symbol tables)

DESCRIPTION

Packages

Perl provides a mechanism for alternative namespaces to protect packages from stomping on each other's variables. In fact, there's really no such thing as a global variable in Perl. The package statement declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block, eval, or file, whichever comes first (the same scope as the my() and local() operators). Unqualified dynamic identifiers will be in this namespace, except for those few identifiers that if unqualified, default to the main package instead of the current one as described below. A package statement affects only dynamic variables--including those you've used local() on--but not lexical variables created with my(). Typically it would be the first declaration in a file included by the do, require, or use operators. You can switch into a package in more than one place; it merely influences which symbol table is used by the compiler for the rest of that block. You can refer to variables and filehandles in other packages by prefixing the identifier with the package name and a double colon: $Package::Variable. If the package name is null, the main package is assumed. That is, $::sail is equivalent to $main::sail.

The old package delimiter was a single quote, but double colon is now the preferred delimiter, in part because it's more readable to humans, and in part because it's more readable to emacs macros. It also makes C++ programmers feel like they know what's going on--as opposed to using the single quote as separator, which was there to make Ada programmers feel like they knew what was going on. Because the old-fashioned syntax is still supported for backwards compatibility, if you try to use a string like "This is $owner's house", you'll be accessing $owner::s; that is, the $s variable in package owner, which is probably not what you meant. Use braces to disambiguate, as in "This is ${owner}'s house".

Packages may themselves contain package separators, as in $OUTER::INNER::var. This implies nothing about the order of name lookups, however. There are no relative packages: all symbols are either local to the current package, or must be fully qualified from the outer package name down. For instance, there is nowhere within package OUTER that $INNER::var refers to $OUTER::INNER::var. INNER refers to a totally separate global package.

Only identifiers starting with letters (or underscore) are stored in a package's symbol table. All other symbols are kept in package main, including all punctuation variables, like $_. In addition, when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are forced to be in package main, even when used for other purposes than their built-in ones. If you have a package called m, s, or y, then you can't use the qualified form of an identifier because it would be instead interpreted as a pattern match, a substitution, or a transliteration.

Variables beginning with underscore used to be forced into package main, but we decided it was more useful for package writers to be able to use leading underscore to indicate private variables and method names. However, variables and functions named with a single _, such as $_ and sub _, are still forced into the package main. See also Technical Note on the Syntax of Variable Names in the perlvar manpage.

evaled strings are compiled in the package in which the eval() was compiled. (Assignments to $SIG{}, however, assume the signal handler specified is in the main package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine perldb.pl in the Perl library. It initially switches to the DB package so that the debugger doesn't interfere with variables in the program you are trying to debug. At various points, however, it temporarily switches back to the main package to evaluate various expressions in the context of the main package (or wherever you came from). See the perldebug manpage.

The special symbol __PACKAGE__ contains the current package, but cannot (easily) be used to construct variable names.

See the perlsub manpage for other scoping issues related to my() and local(), and the perlref manpage regarding closures.

Symbol Tables

The symbol table for a package happens to be stored in the hash of that name with two colons appended. The main symbol table's name is thus %main::, or %:: for short. Likewise the symbol table for the nested package mentioned earlier is named %OUTER::INNER::.

The value in each entry of the hash is what you are referring to when you use the *name typeglob notation. In fact, the following have the same effect, though the first is more efficient because it does the symbol table lookups at compile time:

    local *main::foo    = *main::bar;
    local $main::{foo}  = $main::{bar};

(Be sure to note the vast difference between the second line above and local $main::foo = $main::bar. The former is accessing the hash %main::, which is the symbol table of package main. The latter is simply assigning scalar $bar in package main to scalar $foo of the same package.)

You can use this to print out all the variables in a package, for instance. The standard but antiquated dumpvar.pl library and the CPAN module Devel::Symdump make use of this.

Assignment to a typeglob performs an aliasing operation, i.e.,

    *dick = *richard;

causes variables, subroutines, formats, and file and directory handles accessible via the identifier richard also to be accessible via the identifier dick. If you want to alias only a particular variable or subroutine, assign a reference instead:

    *dick = \$richard;

Which makes $richard and $dick the same variable, but leaves @richard and @dick as separate arrays. Tricky, eh?

There is one subtle difference between the following statements:

    *foo = *bar;
    *foo = \$bar;

*foo = *bar makes the typeglobs themselves synonymous while *foo = \$bar makes the SCALAR portions of two distinct typeglobs refer to the same scalar value. This means that the following code:

    $bar = 1;
    *foo = \$bar;       # Make $foo an alias for $bar

    {
        local $bar = 2; # Restrict changes to block
        print $foo;     # Prints '1'!
    }

Would print '1', because $foo holds a reference to the original $bar -- the one that was stuffed away by local() and which will be restored when the block ends. Because variables are accessed through the typeglob, you can use *foo = *bar to create an alias which can be localized. (But be aware that this means you can't have a separate @foo and @bar, etc.)

What makes all of this important is that the Exporter module uses glob aliasing as the import/export mechanism. Whether or not you can properly localize a variable that has been exported from a module depends on how it was exported:

    @EXPORT = qw($FOO); # Usual form, can't be localized
    @EXPORT = qw(*FOO); # Can be localized

You can work around the first case by using the fully qualified name ($Package::FOO) where you need a local value, or by overriding it by saying *FOO = *Package::FOO in your script.

The *x = \$y mechanism may be used to pass and return cheap references into or from subroutines if you don't want to copy the whole thing. It only works when assigning to dynamic variables, not lexicals.

    %some_hash = ();                    # can't be my()
    *some_hash = fn( \%another_hash );
    sub fn {
        local *hashsym = shift;
        # now use %hashsym normally, and you
        # will affect the caller's %another_hash
        my %nhash = (); # do what you want
        return \%nhash;
    }

On return, the reference will overwrite the hash slot in the symbol table specified by the *some_hash typeglob. This is a somewhat tricky way of passing around references cheaply when you don't want to have to remember to dereference variables explicitly.

Another use of symbol tables is for making "constant" scalars.

    *PI = \3.14159265358979;

Now you cannot alter $PI, which is probably a good thing all in all. This isn't the same as a constant subroutine, which is subject to optimization at compile-time. A constant subroutine is one prototyped to take no arguments and to return a constant expression. See the perlsub manpage for details on these. The use constant pragma is a convenient shorthand for these.

You can say *foo{PACKAGE} and *foo{NAME} to find out what name and package the *foo symbol table entry comes from. This may be useful in a subroutine that gets passed typeglobs as arguments:

    sub identify_typeglob {
        my $glob = shift;
        print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
    }
    identify_typeglob *foo;
    identify_typeglob *bar::baz;

This prints

    You gave me main::foo
    You gave me bar::baz

The *foo{THING} notation can also be used to obtain references to the individual elements of *foo. See the perlref manpage.

Subroutine definitions (and declarations, for that matter) need not necessarily be situated in the package whose symbol table they occupy. You can define a subroutine outside its package by explicitly qualifying the name of the subroutine:

    package main;
    sub Some_package::foo { ... }   # &foo defined in Some_package

This is just a shorthand for a typeglob assignment at compile time:

    BEGIN { *Some_package::foo = sub { ... } }

and is not the same as writing:

    {
        package Some_package;
        sub foo { ... }
    }

In the first two versions, the body of the subroutine is lexically in the main package, not in Some_package. So something like this:

    package main;

    $Some_package::name = "fred";
    $main::name = "barney";

    sub Some_package::foo {
        print "in ", __PACKAGE__, ": \$name is '$name'\n";
    }

    Some_package::foo();

prints:

    in main: $name is 'barney'

rather than:

    in Some_package: $name is 'fred'

This also has implications for the use of the SUPER:: qualifier (see the perlobj manpage).

BEGIN, CHECK, INIT and END

Four specially named code blocks are executed at the beginning and at the end of a running Perl program. These are the BEGIN, CHECK, INIT, and END blocks.

These code blocks can be prefixed with sub to give the appearance of a subroutine (although this is not considered good style). One should note that these code blocks don't really exist as named subroutines (despite their appearance). The thing that gives this away is the fact that you can have more than one of these code blocks in a program, and they will get all executed at the appropriate moment. So you can't execute any of these code blocks by name.

A BEGIN code block is executed as soon as possible, that is, the moment it is completely defined, even before the rest of the containing file (or string) is parsed. You may have multiple BEGIN blocks within a file (or eval'ed string) -- they will execute in order of definition. Because a BEGIN code block executes immediately, it can pull in definitions of subroutines and such from other files in time to be visible to the rest of the compile and run time. Once a BEGIN has run, it is immediately undefined and any code it used is returned to Perl's memory pool.

It should be noted that BEGIN code blocks are executed inside string eval()'s. The CHECK and INIT code blocks are not executed inside a string eval, which e.g. can be a problem in a mod_perl environment.

An END code block is executed as late as possible, that is, after perl has finished running the program and just before the interpreter is being exited, even if it is exiting as a result of a die() function. (But not if it's morphing into another program via exec, or being blown out of the water by a signal--you have to trap that yourself (if you can).) You may have multiple END blocks within a file--they will execute in reverse order of definition; that is: last in, first out (LIFO). END blocks are not executed when you run perl with the -c switch, or if compilation fails.

Note that END code blocks are not executed at the end of a string eval(): if any END code blocks are created in a string eval(), they will be executed just as any other END code block of that package in LIFO order just before the interpreter is being exited.

Inside an END code block, $? contains the value that the program is going to pass to exit(). You can modify $? to change the exit value of the program. Beware of changing $? by accident (e.g. by running something via system).

CHECK and INIT code blocks are useful to catch the transition between the compilation phase and the execution phase of the main program.

CHECK code blocks are run just after the initial Perl compile phase ends and before the run time begins, in LIFO order. CHECK code blocks are used in the Perl compiler suite to save the compiled state of the program.

INIT blocks are run just before the Perl runtime begins execution, in "first in, first out" (FIFO) order. For example, the code generators documented in perlcc make use of INIT blocks to initialize and resolve pointers to XSUBs.

When you use the -n and -p switches to Perl, BEGIN and END work just as they do in awk, as a degenerate case. Both BEGIN and CHECK blocks are run when you use the -c switch for a compile-only syntax check, although your main code is not.

The begincheck program makes it all clear, eventually:

  #!/usr/bin/perl

  # begincheck

  print         " 8. Ordinary code runs at runtime.\n";

  END { print   "14.   So this is the end of the tale.\n" }
  INIT { print  " 5. INIT blocks run FIFO just before runtime.\n" }
  CHECK { print " 4.   So this is the fourth line.\n" }

  print         " 9.   It runs in order, of course.\n";

  BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
  END { print   "13.   Read perlmod for the rest of the story.\n" }
  CHECK { print " 3. CHECK blocks run LIFO at compilation's end.\n" }
  INIT { print  " 6.   Run this again, using Perl's -c switch.\n" }

  print         "10.   This is anti-obfuscated code.\n";

  END { print   "12. END blocks run LIFO at quitting time.\n" }
  BEGIN { print " 2.   So this line comes out second.\n" }
  INIT { print  " 7.   You'll see the difference right away.\n" }

  print         "11.   It merely _looks_ like it should be confusing.\n";

  __END__

Perl Classes

There is no special class syntax in Perl, but a package may act as a class if it provides subroutines to act as methods. Such a package may also derive some of its methods from another class (package) by listing the other package name(s) in its global @ISA array (which must be a package global, not a lexical).

For more on this, see the perltoot manpage and the perlobj manpage.

Perl Modules

A module is just a set of related functions in a library file, i.e., a Perl package with the same name as the file. It is specifically designed to be reusable by other modules or programs. It may do this by providing a mechanism for exporting some of its symbols into the symbol table of any package using it, or it may function as a class definition and make its semantics available implicitly through method calls on the class and its objects, without explicitly exporting anything. Or it can do a little of both.

For example, to start a traditional, non-OO module called Some::Module, create a file called Some/Module.pm and start with this template:

    package Some::Module;  # assumes Some/Module.pm

    use strict;
    use warnings;

    BEGIN {
        use Exporter   ();
        our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);

        # set the version for version checking
        $VERSION     = 1.00;
        # if using RCS/CVS, this may be preferred
        $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\d+)/g;

        @ISA         = qw(Exporter);
        @EXPORT      = qw(&func1 &func2 &func4);
        %EXPORT_TAGS = ( );     # eg: TAG => [ qw!name1 name2! ],

        # your exported package globals go here,
        # as well as any optionally exported functions
        @EXPORT_OK   = qw($Var1 %Hashit &func3);
            }
            our @EXPORT_OK;

    # exported package globals go here
    our $Var1;
    our %Hashit;

    # non-exported package globals go here
    our @more;
    our $stuff;

    # initialize package globals, first exported ones
    $Var1   = '';
    %Hashit = ();

    # then the others (which are still accessible as $Some::Module::stuff)
    $stuff  = '';
    @more   = ();

    # all file-scoped lexicals must be created before
    # the functions below that use them.

    # file-private lexicals go here
    my $priv_var    = '';
    my %secret_hash = ();

    # here's a file-private function as a closure,
    # callable as &$priv_func;  it cannot be prototyped.
    my $priv_func = sub {
        # stuff goes here.
    };

    # make all your functions, whether exported or not;
    # remember to put something interesting in the {} stubs
    sub func1      {}    # no prototype
    sub func2()    {}    # proto'd void
    sub func3($$)  {}    # proto'd to 2 scalars

    # this one isn't exported, but could be called!
    sub func4(\%)  {}    # proto'd to 1 hash ref

    END { }       # module clean-up code here (global destructor)

    ## YOUR CODE GOES HERE

    1;  # don't forget to return a true value from the file

Then go on to declare and use your variables in functions without any qualifications. See the Exporter manpage and the the perlmodlib manpage for details on mechanics and style issues in module creation.

Perl modules are included into your program by saying

    use Module;

or

    use Module LIST;

This is exactly equivalent to

    BEGIN { require Module; import Module; }

or

    BEGIN { require Module; import Module LIST; }

As a special case

    use Module ();

is exactly equivalent to

    BEGIN { require Module; }

All Perl module files have the extension .pm. The use operator assumes this so you don't have to spell out "Module.pm" in quotes. This also helps to differentiate new modules from old .pl and .ph files. Module names are also capitalized unless they're functioning as pragmas; pragmas are in effect compiler directives, and are sometimes called "pragmatic modules" (or even "pragmata" if you're a classicist).

The two statements:

    require SomeModule;
    require "SomeModule.pm";

differ from each other in two ways. In the first case, any double colons in the module name, such as Some::Module, are translated into your system's directory separator, usually "/". The second case does not, and would have to be specified literally. The other difference is that seeing the first require clues in the compiler that uses of indirect object notation involving "SomeModule", as in $ob = purge SomeModule, are method calls, not function calls. (Yes, this really can make a difference.)

Because the use statement implies a BEGIN block, the importing of semantics happens as soon as the use statement is compiled, before the rest of the file is compiled. This is how it is able to function as a pragma mechanism, and also how modules are able to declare subroutines that are then visible as list or unary operators for the rest of the current file. This will not work if you use require instead of use. With require you can get into this problem:

    require Cwd;                # make Cwd:: accessible
    $here = Cwd::getcwd();

    use Cwd;                    # import names from Cwd::
    $here = getcwd();

    require Cwd;                # make Cwd:: accessible
    $here = getcwd();           # oops! no main::getcwd()

In general, use Module () is recommended over require Module, because it determines module availability at compile time, not in the middle of your program's execution. An exception would be if two modules each tried to use each other, and each also called a function from that other module. In that case, it's easy to use require instead.

Perl packages may be nested inside other package names, so we can have package names containing ::. But if we used that package name directly as a filename it would make for unwieldy or impossible filenames on some systems. Therefore, if a module's name is, say, Text::Soundex, then its definition is actually found in the library file Text/Soundex.pm.

Perl modules always have a .pm file, but there may also be dynamically linked executables (often ending in .so) or autoloaded subroutine definitions (often ending in .al) associated with the module. If so, these will be entirely transparent to the user of the module. It is the responsibility of the .pm file to load (or arrange to autoload) any additional functionality. For example, although the POSIX module happens to do both dynamic loading and autoloading, the user can say just use POSIX to get it all.

Making your module threadsafe

Since 5.6.0, Perl has had support for a new type of threads called interpreter threads (ithreads). These threads can be used explicitly and implicitly.

Ithreads work by cloning the data tree so that no data is shared between different threads. These threads can be used by using the threads module or by doing fork() on win32 (fake fork() support). When a thread is cloned all Perl data is cloned, however non-Perl data cannot be cloned automatically. Perl after 5.7.2 has support for the CLONE special subroutine. In CLONE you can do whatever you need to do, like for example handle the cloning of non-Perl data, if necessary. CLONE will be called once as a class method for every package that has it defined (or inherits it). It will be called in the context of the new thread, so all modifications are made in the new area. Currently CLONE is called with no parameters other than the invocant package name, but code should not assume that this will remain unchanged, as it is likely that in future extra parameters will be passed in to give more information about the state of cloning.

If you want to CLONE all objects you will need to keep track of them per package. This is simply done using a hash and Scalar::Util::weaken().

Perl after 5.8.7 has support for the CLONE_SKIP special subroutine. Like CLONE, CLONE_SKIP is called once per package; however, it is called just before cloning starts, and in the context of the parent thread. If it returns a true value, then no objects of that class will be cloned; or rather, they will be copied as unblessed, undef values. This provides a simple mechanism for making a module threadsafe; just add sub CLONE_SKIP { 1 } at the top of the class, and DESTROY() will be now only be called once per object. Of course, if the child thread needs to make use of the objects, then a more sophisticated approach is needed.

Like CLONE, CLONE_SKIP is currently called with no parameters other than the invocant package name, although that may change. Similarly, to allow for future expansion, the return value should be a single 0 or 1 value.

SEE ALSO

See the perlmodlib manpage for general style issues related to building Perl modules and classes, as well as descriptions of the standard library and CPAN, the Exporter manpage for how Perl's standard import/export mechanism works, the perltoot manpage and the perltooc manpage for an in-depth tutorial on creating classes, the perlobj manpage for a hard-core reference document on objects, the perlsub manpage for an explanation of functions and scoping, and the perlxstut manpage and the perlguts manpage for more information on writing extension modules.


perlmodinstall - Installing CPAN Modules

    • PREAMBLE
  • PORTABILITY
  • HEY
  • AUTHOR
  • COPYRIGHT

NAME

perlmodinstall - Installing CPAN Modules

DESCRIPTION

You can think of a module as the fundamental unit of reusable Perl code; see the perlmod manpage for details. Whenever anyone creates a chunk of Perl code that they think will be useful to the world, they register as a Perl developer at http://www.cpan.org/modules/04pause.html so that they can then upload their code to the CPAN. The CPAN is the Comprehensive Perl Archive Network and can be accessed at http://www.cpan.org/ , and searched at http://search.cpan.org/ .

This documentation is for people who want to download CPAN modules and install them on their own computer.

PREAMBLE

First, are you sure that the module isn't already on your system? Try perl -MFoo -e 1. (Replace "Foo" with the name of the module; for instance, perl -MCGI::Carp -e 1.

If you don't see an error message, you have the module. (If you do see an error message, it's still possible you have the module, but that it's not in your path, which you can display with perl -e "print qq(@INC)".) For the remainder of this document, we'll assume that you really honestly truly lack an installed module, but have found it on the CPAN.

So now you have a file ending in .tar.gz (or, less often, .zip). You know there's a tasty module inside. There are four steps you must now take:

DECOMPRESS the file
UNPACK the file into a directory
BUILD the module (sometimes unnecessary)
INSTALL the module.

Here's how to perform each step for each operating system. This is <not> a substitute for reading the README and INSTALL files that might have come with your module!

Also note that these instructions are tailored for installing the module into your system's repository of Perl modules -- but you can install modules into any directory you wish. For instance, where I say perl Makefile.PL, you can substitute perl Makefile.PL PREFIX=/my/perl_directory to install the modules into /my/perl_directory. Then you can use the modules from your Perl programs with use lib "/my/perl_directory/lib/site_perl"; or sometimes just use "/my/perl_directory";. If you're on a system that requires superuser/root access to install modules into the directories you see when you type perl -e "print qq(@INC)", you'll want to install them into a local directory (such as your home directory) and use this approach.

  • If you're on a Unix or Unix-like system,

    You can use Andreas Koenig's CPAN module ( http://www.cpan.org/modules/by-module/CPAN ) to automate the following steps, from DECOMPRESS through INSTALL.

    A. DECOMPRESS

    Decompress the file with gzip -d yourmodule.tar.gz

    You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/

    Or, you can combine this step with the next to save disk space:

         gzip -dc yourmodule.tar.gz | tar -xof -

    B. UNPACK

    Unpack the result with tar -xof yourmodule.tar

    C. BUILD

    Go into the newly-created directory and type:

          perl Makefile.PL
      make test

    or

          perl Makefile.PL PREFIX=/my/perl_directory

    to install it locally. (Remember that if you do this, you'll have to put use lib "/my/perl_directory"; near the top of the program that is to use this module.

    D. INSTALL

    While still in that directory, type:

          make install

    Make sure you have the appropriate permissions to install the module in your Perl 5 library directory. Often, you'll need to be root.

    That's all you need to do on Unix systems with dynamic linking. Most Unix systems have dynamic linking -- if yours doesn't, or if for another reason you have a statically-linked perl, and the module requires compilation, you'll need to build a new Perl binary that includes the module. Again, you'll probably need to be root.

  • If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)

    First, type ppm from a shell and see whether ActiveState's PPM repository has your module. If so, you can install it with ppm and you won't have to bother with any of the other steps here. You might be able to use the CPAN instructions from the "Unix or Linux" section above as well; give it a try. Otherwise, you'll have to follow the steps below.

       A. DECOMPRESS

    You can use the shareware Winzip ( http://www.winzip.com ) to decompress and unpack modules.

       B. UNPACK

    If you used WinZip, this was already done for you.

       C. BUILD

    You'll need the nmake utility, available at http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe or dmake, available on CPAN. http://search.cpan.org/dist/dmake/

    Does the module require compilation (i.e. does it have files that end in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now officially tough for you, because you have to compile the module yourself -- no easy feat on Windows. You'll need a compiler such as Visual C++. Alternatively, you can download a pre-built PPM package from ActiveState. http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/

    Go into the newly-created directory and type:

          perl Makefile.PL
      nmake test
       D. INSTALL

    While still in that directory, type:

          nmake install

  • If you're using a Macintosh with "Classic" MacOS and MacPerl,

    A. DECOMPRESS

    First, make sure you have the latest cpan-mac distribution ( http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for doing all of the steps. Read the cpan-mac directions carefully and install it. If you choose not to use cpan-mac for some reason, there are alternatives listed here.

    After installing cpan-mac, drop the module archive on the untarzipme droplet, which will decompress and unpack for you.

    Or, you can either use the shareware StuffIt Expander program ( http://www.aladdinsys.com/expander/ ) in combination with DropStuff with Expander Enhancer ( http://www.aladdinsys.com/dropstuff/ ) or the freeware MacGzip program ( http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).

    B. UNPACK

    If you're using untarzipme or StuffIt, the archive should be extracted now. Or, you can use the freeware suntar or Tar ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).

    C. BUILD

    Check the contents of the distribution. Read the module's documentation, looking for reasons why you might have trouble using it with MacPerl. Look for .xs and .c files, which normally denote that the distribution must be compiled, and you cannot install it "out of the box." (See PORTABILITY.)

    If a module does not work on MacPerl but should, or needs to be compiled, see if the module exists already as a port on the MacPerl Module Porters site ( http://pudge.net/mmp/ ). For more information on doing XS with MacPerl yourself, see Arved Sandstrom's XS tutorial ( http://macperl.com/depts/Tutorials/ ), and then consider uploading your binary to the CPAN and registering it on the MMP site.

    D. INSTALL

    If you are using cpan-mac, just drop the folder on the installme droplet, and use the module.

    Or, if you aren't using cpan-mac, do some manual labor.

    Make sure the newlines for the modules are in Mac format, not Unix format. If they are not then you might have decompressed them incorrectly. Check your decompression and unpacking utilities settings to make sure they are translating text files properly.

    As a last resort, you can use the perl one-liner:

        perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames>

    on the source files.

    Then move the files (probably just the .pm files, though there may be some additional ones, too; check the module documentation) to their final destination: This will most likely be in $ENV{MACPERL}site_lib: (i.e., HD:MacPerl folder:site_lib:). You can add new paths to the default @INC in the Preferences menu item in the MacPerl application ($ENV{MACPERL}site_lib: is added automagically). Create whatever directory structures are required (i.e., for Some::Module, create $ENV{MACPERL}site_lib:Some: and put Module.pm in that directory).

    Then run the following script (or something like it):

         #!perl -w
     use AutoSplit;
     my $dir = "${MACPERL}site_perl";
     autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);

  • If you're on the DJGPP port of DOS,

       A. DECOMPRESS

    djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) will both uncompress and unpack.

       B. UNPACK

    See above.

       C. BUILD

    Go into the newly-created directory and type:

          perl Makefile.PL
      make test

    You will need the packages mentioned in README.dos in the Perl distribution.

       D. INSTALL

    While still in that directory, type:

         make install

    You will need the packages mentioned in README.dos in the Perl distribution.

  • If you're on OS/2,

    Get the EMX development suite and gzip/tar, from either Hobbes ( http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow the instructions for Unix.

  • If you're on VMS,

    When downloading from CPAN, save your file with a .tgz extension instead of .tar.gz. All other periods in the filename should be replaced with underscores. For example, Your-Module-1.33.tar.gz should be downloaded as Your-Module-1_33.tgz.

    A. DECOMPRESS

    Type

        gzip -d Your-Module.tgz

    or, for zipped modules, type

        unzip Your-Module.zip

    Executables for gzip, zip, and VMStar:

        http://www.openvms.digital.com/freeware/
    http://www.crinoid.com/utils/

    and their source code:

        http://www.fsf.org/order/ftp.html

    Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip package. The former is a simple compression tool; the latter permits creation of multi-file archives.

    B. UNPACK

    If you're using VMStar:

         VMStar xf Your-Module.tar

    Or, if you're fond of VMS command syntax:

         tar/extract/verbose Your_Module.tar

    C. BUILD

    Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at http://www.madgoat.com ). Then type this to create the DESCRIP.MMS for the module:

        perl Makefile.PL

    Now you're ready to build:

        mms test

    Substitute mmk for mms above if you're using MMK.

    D. INSTALL

    Type

        mms install

    Substitute mmk for mms above if you're using MMK.

  • If you're on MVS,

    Introduce the .tar.gz file into an HFS as binary; don't translate from ASCII to EBCDIC.

    A. DECOMPRESS

    Decompress the file with gzip -d yourmodule.tar.gz

    You can get gzip from http://www.s390.ibm.com/products/oe/bpxqp1.html

    B. UNPACK

    Unpack the result with

         pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar

    The BUILD and INSTALL steps are identical to those for Unix. Some modules generate Makefiles that work better with GNU make, which is available from http://www.mks.com/s390/gnu/

PORTABILITY

Note that not all modules will work with on all platforms. See the perlport manpage for more information on portability issues. Read the documentation to see if the module will work on your system. There are basically three categories of modules that will not work "out of the box" with all platforms (with some possibility of overlap):

  • Those that should, but don't. These need to be fixed; consider contacting the author and possibly writing a patch.

  • Those that need to be compiled, where the target platform doesn't have compilers readily available. (These modules contain .xs or .c files, usually.) You might be able to find existing binaries on the CPAN or elsewhere, or you might want to try getting compilers and building it yourself, and then release the binary for other poor souls to use.

  • Those that are targeted at a specific platform. (Such as the Win32:: modules.) If the module is targeted specifically at a platform other than yours, you're out of luck, most likely.

Check the CPAN Testers if a module should work with your platform but it doesn't behave as you'd expect, or you aren't sure whether or not a module will work under your platform. If the module you want isn't listed there, you can test it yourself and let CPAN Testers know, you can join CPAN Testers, or you can request it be tested.

    http://testers.cpan.org/

HEY

If you have any suggested changes for this page, let me know. Please don't send me mail asking for help on how to install your modules. There are too many modules, and too few Orwants, for me to be able to answer or even acknowledge all your questions. Contact the module author instead, or post to comp.lang.perl.modules, or ask someone familiar with Perl on your operating system.

AUTHOR

Jon Orwant

orwant@medita.mit.edu

with invaluable help from Chris Nandor, and valuable help from Brandon Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.

First version July 22, 1998; last revised November 21, 2001.

COPYRIGHT

Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.

Permission is granted to make and distribute verbatim copies of this documentation provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this documentation under the conditions for verbatim copying, provided also that they are marked clearly as modified versions, that the authors' names and title are unchanged (though subtitles and additional authors' names may be added), and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this documentation into another language, under the above conditions for modified versions.


perlmodlib - constructing new Perl modules and finding existing ones

  • THE PERL MODULE LIBRARY
    • Pragmatic Modules
    • Standard Modules
    • Extension Modules
  • CPAN
    • Africa
    • Asia
    • Central America
    • Europe
    • North America
    • Oceania
    • South America
    • RSYNC Mirrors
  • Modules: Creation, Use, and Abuse
    • Guidelines for Module Creation
    • Guidelines for Converting Perl 4 Library Scripts into Modules
    • Guidelines for Reusing Application Code
  • NOTE

NAME

perlmodlib - constructing new Perl modules and finding existing ones

THE PERL MODULE LIBRARY

Many modules are included in the Perl distribution. These are described below, and all end in .pm. You may discover compiled library files (usually ending in .so) or small pieces of modules to be autoloaded (ending in .al); these were automatically generated by the installation process. You may also discover files in the library directory that end in either .pl or .ph. These are old libraries supplied so that old programs that use them still run. The .pl files will all eventually be converted into standard modules, and the .ph files made by h2ph will probably end up as extension modules made by h2xs. (Some .ph values may already be available through the POSIX, Errno, or Fcntl modules.) The pl2pm file in the distribution may help in your conversion, but it's just a mechanical process and therefore far from bulletproof.

Pragmatic Modules

They work somewhat like compiler directives (pragmata) in that they tend to affect the compilation of your program, and thus will usually work well only when used within a use, or no. Most of these are lexically scoped, so an inner BLOCK may countermand them by saying:

    no integer;
    no strict 'refs';
    no warnings;

which lasts until the end of that BLOCK.

Some pragmas are lexically scoped--typically those that affect the $^H hints variable. Others affect the current package instead, like use vars and use subs, which allow you to predeclare a variables or subroutines within a particular file rather than just a block. Such declarations are effective for the entire file for which they were declared. You cannot rescind them with no vars or no subs.

The following pragmas are defined (and have their own documentation).

attributes

Get/set subroutine or variable attributes

attrs

Set/get attributes of a subroutine (deprecated)

autouse

Postpone load of modules until a function is used

base

Establish IS-A relationship with base classes at compile time

bigint

Transparent BigInteger support for Perl

bignum

Transparent BigNumber support for Perl

bigrat

Transparent BigNumber/BigRational support for Perl

blib

Use MakeMaker's uninstalled version of a package

bytes

Force byte semantics rather than character semantics

charnames

Define character names for \N{named} string literal escapes

constant

Declare constants

diagnostics

Produce verbose warning diagnostics

encoding

Allows you to write your script in non-ascii or non-utf8

fields

Compile-time class fields

filetest

Control the filetest permission operators

if

use a Perl module if a condition holds

integer

Use integer arithmetic instead of floating point

less

Request less of something from the compiler

lib

Manipulate @INC at compile time

locale

Use and avoid POSIX locales for built-in operations

open

Set default PerlIO layers for input and output

ops

Restrict unsafe operations when compiling

overload

Package for overloading Perl operations

re

Alter regular expression behaviour

sigtrap

Enable simple signal handling

sort

Control sort() behaviour

strict

Restrict unsafe constructs

subs

Predeclare sub names

threads

Perl extension allowing use of interpreter based threads from perl

threads::shared

Perl extension for sharing data structures between threads

utf8

Enable/disable UTF-8 (or UTF-EBCDIC) in source code

vars

Predeclare global variable names (obsolete)

vmsish

Control VMS-specific language features

warnings

Control optional warnings

warnings::register

Warnings import function

Standard Modules

Standard, bundled modules are all expected to behave in a well-defined manner with respect to namespace pollution because they use the Exporter module. See their own documentation for details.

It's possible that not all modules listed below are installed on your system. For example, the GDBM_File module will not be installed if you don't have the gdbm library.

AnyDBM_File

Provide framework for multiple DBMs

Attribute::Handlers

Simpler definition of attribute handlers

AutoLoader

Load subroutines only on demand

AutoSplit

Split a package for autoloading

B

The Perl Compiler

B::Asmdata

Autogenerated data about Perl ops, used to generate bytecode

B::Assembler

Assemble Perl bytecode

B::Bblock

Walk basic blocks

B::Bytecode

Perl compiler's bytecode backend

B::C

Perl compiler's C backend

B::CC

Perl compiler's optimized C translation backend

B::Concise

Walk Perl syntax tree, printing concise info about ops

B::Debug

Walk Perl syntax tree, printing debug info about ops

B::Deparse

Perl compiler backend to produce perl code

B::Disassembler

Disassemble Perl bytecode

B::Lint

Perl lint

B::Showlex

Show lexical variables used in functions or files

B::Stackobj

Helper module for CC backend

B::Stash

Show what stashes are loaded

B::Terse

Walk Perl syntax tree, printing terse info about ops

B::Xref

Generates cross reference reports for Perl programs

Benchmark

Benchmark running times of Perl code

ByteLoader

Load byte compiled perl code

CGI

Simple Common Gateway Interface Class

CGI::Apache

Backward compatibility module for CGI.pm

CGI::Carp

CGI routines for writing to the HTTPD (or other) error log

CGI::Cookie

Interface to Netscape Cookies

CGI::Fast

CGI Interface for Fast CGI

CGI::Pretty

Module to produce nicely formatted HTML code

CGI::Push

Simple Interface to Server Push

CGI::Switch

Backward compatibility module for defunct CGI::Switch

CGI::Util

Internal utilities used by CGI module

CPAN

Query, download and build perl modules from CPAN sites

CPAN::FirstTime

Utility for CPAN::Config file Initialization

CPAN::Nox

Wrapper around CPAN.pm without using any XS module

CPAN::Version

Utility functions to compare CPAN versions

Carp

Warn of errors (from perspective of caller)

Carp::Heavy

Heavy machinery, no user serviceable parts inside

Class::ISA

Report the search path for a class's ISA tree

Class::Struct

Declare struct-like datatypes as Perl classes

Config

Access Perl configuration information

Cwd

Get pathname of current working directory

DB

Programmatic interface to the Perl debugging API (draft, subject to

DBM_Filter

Filter DBM keys/values

DB_File

Perl5 access to Berkeley DB version 1.x

Data::Dumper

Stringified perl data structures, suitable for both printing and eval

Devel::DProf

A Perl code profiler

Devel::PPPort

Perl/Pollution/Portability

Devel::Peek

A data debugging tool for the XS programmer

Devel::SelfStubber

Generate stubs for a SelfLoading module

Digest

Modules that calculate message digests

Digest::MD5

Perl interface to the MD5 Algorithm

Digest::base

Digest base class

Digest::file

Calculate digests of files

DirHandle

Supply object methods for directory handles

Dumpvalue

Provides screen dump of Perl data.

DynaLoader

Dynamically load C libraries into Perl code

Encode

Character encodings

Encode::Alias

Alias definitions to encodings

Encode::Byte

Single Byte Encodings

Encode::CJKConstants

Internally used by Encode::??::ISO_2022_*

Encode::CN

China-based Chinese Encodings

Encode::CN::HZ

Internally used by Encode::CN

Encode::Config

Internally used by Encode

Encode::EBCDIC

EBCDIC Encodings

Encode::Encoder

Object Oriented Encoder

Encode::Encoding

Encode Implementation Base Class

Encode::Guess

Guesses encoding from data

Encode::JP

Japanese Encodings

Encode::JP::H2Z

Internally used by Encode::JP::2022_JP*

Encode::JP::JIS7

Internally used by Encode::JP

Encode::KR

Korean Encodings

Encode::KR::2022_KR

Internally used by Encode::KR

Encode::MIME::Header

MIME 'B' and 'Q' header encoding

Encode::PerlIO

A detailed document on Encode and PerlIO

Encode::Supported

Encodings supported by Encode

Encode::Symbol

Symbol Encodings

Encode::TW

Taiwan-based Chinese Encodings

Encode::Unicode

Various Unicode Transformation Formats

Encode::Unicode::UTF7

UTF-7 encoding

English

Use nice English (or awk) names for ugly punctuation variables

Env

Perl module that imports environment variables as scalars or arrays

Errno

System errno constants

Exporter

Implements default import method for modules

Exporter::Heavy

Exporter guts

ExtUtils::Command

Utilities to replace common UNIX commands in Makefiles etc.

ExtUtils::Command::MM

Commands for the MM's to use in Makefiles

ExtUtils::Constant

Generate XS code to import C header constants

ExtUtils::Constant::Base

Base class for ExtUtils::Constant objects

ExtUtils::Constant::Utils

Helper functions for ExtUtils::Constant

ExtUtils::Constant::XS

Base class for ExtUtils::Constant objects

ExtUtils::Embed

Utilities for embedding Perl in C/C++ applications

ExtUtils::Install

Install files from here to there

ExtUtils::Installed

Inventory management of installed modules

ExtUtils::Liblist

Determine libraries to use and how to use them

ExtUtils::MM

OS adjusted ExtUtils::MakeMaker subclass

ExtUtils::MM_AIX

AIX specific subclass of ExtUtils::MM_Unix

ExtUtils::MM_Any

Platform-agnostic MM methods

ExtUtils::MM_BeOS

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_Cygwin

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_DOS

DOS specific subclass of ExtUtils::MM_Unix

ExtUtils::MM_MacOS

Once produced Makefiles for MacOS Classic

ExtUtils::MM_NW5

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_OS2

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_QNX

QNX specific subclass of ExtUtils::MM_Unix

ExtUtils::MM_UWIN

U/WIN specific subclass of ExtUtils::MM_Unix

ExtUtils::MM_Unix

Methods used by ExtUtils::MakeMaker

ExtUtils::MM_VMS

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_VOS

VOS specific subclass of ExtUtils::MM_Unix

ExtUtils::MM_Win32

Methods to override UN*X behaviour in ExtUtils::MakeMaker

ExtUtils::MM_Win95

Method to customize MakeMaker for Win9X

ExtUtils::MY

ExtUtils::MakeMaker subclass for customization

ExtUtils::MakeMaker

Create a module Makefile

ExtUtils::MakeMaker::Config

Wrapper around Config.pm

ExtUtils::MakeMaker::FAQ

Frequently Asked Questions About MakeMaker

ExtUtils::MakeMaker::Tutorial

Writing a module with MakeMaker

ExtUtils::MakeMaker::bytes

Version-agnostic bytes.pm

ExtUtils::MakeMaker::vmsish

Platform-agnostic vmsish.pm

ExtUtils::Manifest

Utilities to write and check a MANIFEST file

ExtUtils::Mkbootstrap

Make a bootstrap file for use by DynaLoader

ExtUtils::Mksymlists

Write linker options files for dynamic extension

ExtUtils::Packlist

Manage .packlist files

ExtUtils::testlib

Add blib/* directories to @INC

Fatal

Replace functions with equivalents which succeed or die

Fcntl

Load the C Fcntl.h defines

File::Basename

Parse file paths into directory, filename and suffix.

File::CheckTree

Run many filetest checks on a tree

File::Compare

Compare files or filehandles

File::Copy

Copy files or filehandles

File::DosGlob

DOS like globbing and then some

File::Find

Traverse a directory tree.

File::Glob

Perl extension for BSD glob routine

File::Path

Create or remove directory trees

File::Spec

Portably perform operations on file names

File::Spec::Cygwin

Methods for Cygwin file specs

File::Spec::Epoc

Methods for Epoc file specs

File::Spec::Functions

Portably perform operations on file names

File::Spec::Mac

File::Spec for Mac OS (Classic)

File::Spec::OS2

Methods for OS/2 file specs

File::Spec::Unix

File::Spec for Unix, base for other File::Spec modules

File::Spec::VMS

Methods for VMS file specs

File::Spec::Win32

Methods for Win32 file specs

File::Temp

Return name and handle of a temporary file safely

File::stat

By-name interface to Perl's built-in stat() functions

FileCache

Keep more files open than the system permits

FileHandle

Supply object methods for filehandles

Filter::Simple

Simplified source filtering

Filter::Util::Call

Perl Source Filter Utility Module

FindBin

Locate directory of original perl script

GDBM_File

Perl5 access to the gdbm library.

Getopt::Long

Extended processing of command line options

Getopt::Std

Process single-character switches with switch clustering

Hash::Util

A selection of general-utility hash subroutines

I18N::Collate

Compare 8-bit scalar data according to the current locale

I18N::LangTags

Functions for dealing with RFC3066-style language tags

I18N::LangTags::Detect

Detect the user's language preferences

I18N::LangTags::List

Tags and names for human languages

I18N::Langinfo

Query locale information

IO

Load various IO modules

IO::Dir

Supply object methods for directory handles

IO::File

Supply object methods for filehandles

IO::Handle

Supply object methods for I/O handles

IO::Pipe

Supply object methods for pipes

IO::Poll

Object interface to system poll call

IO::Seekable

Supply seek based methods for I/O objects

IO::Select

OO interface to the select system call

IO::Socket

Object interface to socket communications

IO::Socket::INET

Object interface for AF_INET domain sockets

IO::Socket::UNIX

Object interface for AF_UNIX domain sockets

IPC::Open2

Open a process for both reading and writing

IPC::Open3

Open a process for reading, writing, and error handling

IPC::SysV

SysV IPC constants

IPC::SysV::Msg

SysV Msg IPC object class

IPC::SysV::Semaphore

SysV Semaphore IPC object class

List::Util

A selection of general-utility list subroutines

Locale::Constants

Constants for Locale codes

Locale::Country

ISO codes for country identification (ISO 3166)

Locale::Currency

ISO three letter codes for currency identification (ISO 4217)

Locale::Language

ISO two letter codes for language identification (ISO 639)

Locale::Maketext

Framework for localization

Locale::Maketext::TPJ13

Article about software localization

Locale::Script

ISO codes for script identification (ISO 15924)

MIME::Base64

Encoding and decoding of base64 strings

MIME::Base64::QuotedPrint

Encoding and decoding of quoted-printable strings

Math::BigFloat

Arbitrary size floating point math package

Math::BigInt

Arbitrary size integer/float math package

Math::BigInt::Calc

Pure Perl module to support Math::BigInt

Math::BigInt::CalcEmu

Emulate low-level math with BigInt code

Math::BigRat

Arbitrary big rational numbers

Math::Complex

Complex numbers and associated mathematical functions

Math::Trig

Trigonometric functions

Memoize

Make functions faster by trading space for time

Memoize::AnyDBM_File

Glue to provide EXISTS for AnyDBM_File for Storable use

Memoize::Expire

Plug-in module for automatic expiration of memoized values

Memoize::ExpireFile

Test for Memoize expiration semantics

Memoize::ExpireTest

Test for Memoize expiration semantics

Memoize::NDBM_File

Glue to provide EXISTS for NDBM_File for Storable use

Memoize::SDBM_File

Glue to provide EXISTS for SDBM_File for Storable use

Memoize::Storable

Store Memoized data in Storable database

NDBM_File

Tied access to ndbm files

NEXT

Provide a pseudo-class NEXT (et al) that allows method redispatch

Net::Cmd

Network Command class (as used by FTP, SMTP etc)

Net::Config

Local configuration data for libnet

Net::Domain

Attempt to evaluate the current host's internet name and domain

Net::FTP

FTP Client class

Net::NNTP

NNTP Client class

Net::Netrc

OO interface to users netrc file

Net::POP3

Post Office Protocol 3 Client class (RFC1939)

Net::Ping

Check a remote host for reachability

Net::SMTP

Simple Mail Transfer Protocol Client

Net::Time

Time and daytime network client interface

Net::hostent

By-name interface to Perl's built-in gethost*() functions

Net::libnetFAQ

Libnet Frequently Asked Questions

Net::netent

By-name interface to Perl's built-in getnet*() functions

Net::protoent

By-name interface to Perl's built-in getproto*() functions

Net::servent

By-name interface to Perl's built-in getserv*() functions

O

Generic interface to Perl Compiler backends

ODBM_File

Tied access to odbm files

Opcode

Disable named opcodes when compiling perl code

POSIX

Perl interface to IEEE Std 1003.1

PerlIO

On demand loader for PerlIO layers and root of PerlIO::* name space

PerlIO::encoding

Encoding layer

PerlIO::scalar

In-memory IO, scalar IO

PerlIO::via

Helper class for PerlIO layers implemented in perl

PerlIO::via::QuotedPrint

PerlIO layer for quoted-printable strings

Pod::Checker

Check pod documents for syntax errors

Pod::Find

Find POD documents in directory trees

Pod::Functions

Group Perl's functions a la perlfunc.pod

Pod::Html

Module to convert pod files to HTML

Pod::InputObjects

Objects representing POD input paragraphs, commands, etc.

Pod::LaTeX

Convert Pod data to formatted Latex

Pod::Man

Convert POD data to formatted *roff input

Pod::ParseLink

Parse an L<> formatting code in POD text

Pod::ParseUtils

Helpers for POD parsing and conversion

Pod::Parser

Base class for creating POD filters and translators

Pod::Perldoc::ToChecker

Let Perldoc check Pod for errors

Pod::Perldoc::ToMan

Let Perldoc render Pod as man pages

Pod::Perldoc::ToNroff

Let Perldoc convert Pod to nroff

Pod::Perldoc::ToPod

Let Perldoc render Pod as ... Pod!

Pod::Perldoc::ToRtf

Let Perldoc render Pod as RTF

Pod::Perldoc::ToText

Let Perldoc render Pod as plaintext

Pod::Perldoc::ToTk

Let Perldoc use Tk::Pod to render Pod

Pod::Perldoc::ToXml

Let Perldoc render Pod as XML

Pod::PlainText

Convert POD data to formatted ASCII text

Pod::Plainer

Perl extension for converting Pod to old style Pod.

Pod::Select

Extract selected sections of POD from input

Pod::Text

Convert POD data to formatted ASCII text

Pod::Text::Color

Convert POD data to formatted color ASCII text

Pod::Text::Overstrike

Convert POD data to formatted overstrike text

Pod::Text::Termcap

Convert POD data to ASCII text with format escapes

Pod::Usage

Print a usage message from embedded pod documentation

SDBM_File

Tied access to sdbm files

Safe

Compile and execute code in restricted compartments

Scalar::Util

A selection of general-utility scalar subroutines

Search::Dict

Search for key in dictionary file

SelectSaver

Save and restore selected file handle

SelfLoader

Load functions only on demand

Shell

Run shell commands transparently within perl

Socket

Load the C socket.h defines and structure manipulators

Storable

Persistence for Perl data structures

Switch

A switch statement for Perl

Symbol

Manipulate Perl symbols and their names

Sys::Hostname

Try every conceivable way to get hostname

Sys::Syslog

Perl interface to the UNIX syslog(3) calls

Term::ANSIColor

Color screen output using ANSI escape sequences

Term::Cap

Perl termcap interface

Term::Complete

Perl word completion module

Term::ReadLine

Perl interface to various readline packages.

Test

Provides a simple framework for writing test scripts

Test::Builder

Backend for building test libraries

Test::Builder::Module

Base class for test modules

Test::Builder::Tester

Test testsuites that have been built with

Test::Builder::Tester::Color

Turn on colour in Test::Builder::Tester

Test::Harness

Run Perl standard test scripts with statistics

Test::Harness::Assert

Simple assert

Test::Harness::Iterator

Internal Test::Harness Iterator

Test::Harness::Point

Object for tracking a single test point

Test::Harness::Straps

Detailed analysis of test results

Test::Harness::TAP

Documentation for the TAP format

Test::More

Yet another framework for writing test scripts

Test::Simple

Basic utilities for writing tests.

Test::Tutorial

A tutorial about writing really basic tests

Text::Abbrev

Create an abbreviation table from a list

Text::Balanced

Extract delimited text sequences from strings.

Text::ParseWords

Parse text into an array of tokens or array of arrays

Text::Soundex

Implementation of the Soundex Algorithm as Described by Knuth

Text::Tabs

Expand and unexpand tabs per the unix expand(1) and unexpand(1)

Text::Wrap

Line wrapping to form simple paragraphs

Thread

Manipulate threads in Perl (for old code only)

Thread::Queue

Thread-safe queues

Thread::Semaphore

Thread-safe semaphores

Thread::Signal

Start a thread which runs signal handlers reliably (for old code)

Thread::Specific

Thread-specific keys

Tie::Array

Base class for tied arrays

Tie::File

Access the lines of a disk file via a Perl array

Tie::Handle

Base class definitions for tied handles

Tie::Hash

Base class definitions for tied hashes

Tie::Memoize

Add data to hash when needed

Tie::RefHash

Use references as hash keys

Tie::Scalar

Base class definitions for tied scalars

Tie::SubstrHash

Fixed-table-size, fixed-key-length hashing

Time::HiRes

High resolution alarm, sleep, gettimeofday, interval timers

Time::Local

Efficiently compute time from local and GMT time

Time::gmtime

By-name interface to Perl's built-in gmtime() function

Time::localtime

By-name interface to Perl's built-in localtime() function

Time::tm

Internal object used by Time::gmtime and Time::localtime

UNIVERSAL

Base class for ALL classes (blessed references)

Unicode::Collate

Unicode Collation Algorithm

Unicode::Normalize

Unicode Normalization Forms

Unicode::UCD

Unicode character database

User::grent

By-name interface to Perl's built-in getgr*() functions

User::pwent

By-name interface to Perl's built-in getpw*() functions

XS::APItest

Test the perl C API

XS::Typemap

Module to test the XS typemaps distributed with perl

XSLoader

Dynamically load C libraries into Perl code

To find out all modules installed on your system, including those without documentation or outside the standard release, just use the following command (under the default win32 shell, double quotes should be used instead of single quotes).

    % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
      'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
      no_chdir => 1 }, @INC'

(The -T is here to prevent '.' from being listed in @INC.) They should all have their own documentation installed and accessible via your system man(1) command. If you do not have a find program, you can use the Perl find2perl program instead, which generates Perl code as output you can run through perl. If you have a man program but it doesn't find your modules, you'll have to fix your manpath. See the perl manpage for details. If you have no system man command, you might try the perldoc program.

Note also that the command perldoc perllocal gives you a (possibly incomplete) list of the modules that have been further installed on your system. (The perllocal.pod file is updated by the standard MakeMaker install process.)

Extension Modules

Extension modules are written in C (or a mix of Perl and C). They are usually dynamically loaded into Perl if and when you need them, but may also be linked in statically. Supported extension modules include Socket, Fcntl, and POSIX.

Many popular C extension modules do not come bundled (at least, not completely) due to their sizes, volatility, or simply lack of time for adequate testing and configuration across the multitude of platforms on which Perl was beta-tested. You are encouraged to look for them on CPAN (described below), or using web search engines like Alta Vista or Google.

CPAN

CPAN stands for Comprehensive Perl Archive Network; it's a globally replicated trove of Perl materials, including documentation, style guides, tricks and traps, alternate ports to non-Unix systems and occasional binary distributions for these. Search engines for CPAN can be found at http://www.cpan.org/

Most importantly, CPAN includes around a thousand unbundled modules, some of which require a C compiler to build. Major categories of modules are:

  • Language Extensions and Documentation Tools

  • Development Support

  • Operating System Interfaces

  • Networking, Device Control (modems) and InterProcess Communication

  • Data Types and Data Type Utilities

  • Database Interfaces

  • User Interfaces

  • Interfaces to / Emulations of Other Programming Languages

  • File Names, File Systems and File Locking (see also File Handles)

  • String Processing, Language Text Processing, Parsing, and Searching

  • Option, Argument, Parameter, and Configuration File Processing

  • Internationalization and Locale

  • Authentication, Security, and Encryption

  • World Wide Web, HTML, HTTP, CGI, MIME

  • Server and Daemon Utilities

  • Archiving and Compression

  • Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing

  • Mail and Usenet News

  • Control Flow Utilities (callbacks and exceptions etc)

  • File Handle and Input/Output Stream Utilities

  • Miscellaneous Modules

The list of the registered CPAN sites as of this writing follows. Please note that the sorting order is alphabetical on fields:

Continent | |-->Country | |-->[state/province] | |-->ftp | |-->[http]

and thus the North American servers happen to be listed between the European and the South American sites.

You should try to choose one close to you.

Africa

South Africa
                      http://ftp.rucus.ru.ac.za/pub/perl/CPAN/
                      ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/
                      ftp://ftp.is.co.za/programming/perl/CPAN/
                      ftp://ftp.saix.net/pub/CPAN/
                      ftp://ftp.sun.ac.za/CPAN/CPAN/

Asia

China
                      http://cpan.linuxforum.net/
                      http://cpan.shellhung.org/
                      ftp://ftp.shellhung.org/pub/CPAN
                      ftp://mirrors.hknet.com/CPAN
Indonesia
                      http://mirrors.tf.itb.ac.id/cpan/
                      http://cpan.cbn.net.id/
                      ftp://ftp.cbn.net.id/mirror/CPAN
Israel
                      ftp://ftp.iglu.org.il/pub/CPAN/
                      http://cpan.lerner.co.il/
                      http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
                      ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
Japan
                      ftp://ftp.u-aizu.ac.jp/pub/CPAN
                      ftp://ftp.kddlabs.co.jp/CPAN/
                      ftp://ftp.ayamura.org/pub/CPAN/
                      ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
                      http://ftp.cpan.jp/
                      ftp://ftp.cpan.jp/CPAN/
                      ftp://ftp.dti.ad.jp/pub/lang/CPAN/
                      ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
Malaysia
                      http://cpan.MyBSD.org.my
                      http://mirror.leafbug.org/pub/CPAN
                      http://ossig.mncc.com.my/mirror/pub/CPAN
Russian Federation
                      http://cpan.tomsk.ru
                      ftp://cpan.tomsk.ru/
Saudi Arabia
                      ftp://ftp.isu.net.sa/pub/CPAN/
Singapore
                      http://CPAN.en.com.sg/
                      ftp://cpan.en.com.sg/
                      http://mirror.averse.net/pub/CPAN
                      ftp://mirror.averse.net/pub/CPAN
                      http://cpan.oss.eznetsols.org
                      ftp://ftp.oss.eznetsols.org/cpan
South Korea
                      http://CPAN.bora.net/
                      ftp://ftp.bora.net/pub/CPAN/
                      http://mirror.kr.FreeBSD.org/CPAN
                      ftp://ftp.kr.FreeBSD.org/pub/CPAN
Taiwan
                      ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
                      http://cpan.cdpa.nsysu.edu.tw/
                      ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN
                      http://ftp.isu.edu.tw/pub/CPAN
                      ftp://ftp.isu.edu.tw/pub/CPAN
                      ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
                      http://ftp.tku.edu.tw/pub/CPAN/
                      ftp://ftp.tku.edu.tw/pub/CPAN/
Thailand
                      ftp://ftp.loxinfo.co.th/pub/cpan/
                      ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/

Central America

Costa Rica
                      http://ftp.ucr.ac.cr/Unix/CPAN/
                      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/

Europe

Austria
                      http://cpan.inode.at/
                      ftp://cpan.inode.at
                      ftp://ftp.tuwien.ac.at/pub/CPAN/
Belgium
                      http://ftp.easynet.be/pub/CPAN/
                      ftp://ftp.easynet.be/pub/CPAN/
                      http://cpan.skynet.be
                      ftp://ftp.cpan.skynet.be/pub/CPAN
                      ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
Bosnia and Herzegovina
                      http://cpan.blic.net/
Bulgaria
                      http://cpan.online.bg
                      ftp://cpan.online.bg/cpan
                      http://cpan.zadnik.org
                      ftp://ftp.zadnik.org/mirrors/CPAN/
                      http://cpan.lirex.net/
                      ftp://ftp.lirex.net/pub/mirrors/CPAN
Croatia
                      http://ftp.linux.hr/pub/CPAN/
                      ftp://ftp.linux.hr/pub/CPAN/
Czech Republic
                      ftp://ftp.fi.muni.cz/pub/CPAN/
                      ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
Denmark
                      http://mirrors.sunsite.dk/cpan/
                      ftp://sunsite.dk/mirrors/cpan/
                      http://cpan.cybercity.dk
                      http://www.cpan.dk/CPAN/
                      ftp://www.cpan.dk/ftp.cpan.org/CPAN/
Estonia
                      ftp://ftp.ut.ee/pub/languages/perl/CPAN/
Finland
                      ftp://ftp.funet.fi/pub/languages/perl/CPAN/
                      http://mirror.eunet.fi/CPAN
France
                      http://www.enstimac.fr/Perl/CPAN
                      http://ftp.u-paris10.fr/perl/CPAN
                      ftp://ftp.u-paris10.fr/perl/CPAN
                      http://cpan.mirrors.easynet.fr/
                      ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
                      ftp://ftp.club-internet.fr/pub/perl/CPAN/
                      http://fr.cpan.org/
                      ftp://ftp.lip6.fr/pub/perl/CPAN/
                      ftp://ftp.oleane.net/pub/mirrors/CPAN/
                      ftp://ftp.pasteur.fr/pub/computing/CPAN/
                      http://mir2.ovh.net/ftp.cpan.org
                      ftp://mir1.ovh.net/ftp.cpan.org
                      http://ftp.crihan.fr/mirrors/ftp.cpan.org/
                      ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
                      http://ftp.u-strasbg.fr/CPAN
                      ftp://ftp.u-strasbg.fr/CPAN
                      ftp://cpan.cict.fr/pub/CPAN/
                      ftp://ftp.uvsq.fr/pub/perl/CPAN/
Germany
                      ftp://ftp.rub.de/pub/CPAN/
                      ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
                      ftp://ftp.uni-erlangen.de/pub/source/CPAN/
                      ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
                      http://pandemonium.tiscali.de/pub/CPAN/
                      ftp://pandemonium.tiscali.de/pub/CPAN/
                      http://ftp.gwdg.de/pub/languages/perl/CPAN/
                      ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
                      ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
                      ftp://ftp.leo.org/pub/CPAN/
                      http://cpan.noris.de/
                      ftp://cpan.noris.de/pub/CPAN/
                      ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
                      ftp://ftp.gmd.de/mirrors/CPAN/
Greece
                      ftp://ftp.acn.gr/pub/lang/perl
                      ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
                      ftp://ftp.ntua.gr/pub/lang/perl/
Hungary
                      http://ftp.kfki.hu/packages/perl/CPAN/
                      ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
Iceland
                      http://ftp.rhnet.is/pub/CPAN/
                      ftp://ftp.rhnet.is/pub/CPAN/
Ireland
                      http://cpan.indigo.ie/
                      ftp://cpan.indigo.ie/pub/CPAN/
                      http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
                      ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
                      http://sunsite.compapp.dcu.ie/pub/perl/
                      ftp://sunsite.compapp.dcu.ie/pub/perl/
Italy
                      http://cpan.nettuno.it/
                      http://gusp.dyndns.org/CPAN/
                      ftp://gusp.dyndns.org/pub/CPAN
                      http://softcity.iol.it/cpan
                      ftp://softcity.iol.it/pub/cpan
                      ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
                      ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
                      ftp://cis.uniRoma2.it/CPAN/
                      ftp://ftp.edisontel.it/pub/CPAN_Mirror/
                      http://cpan.flashnet.it/
                      ftp://ftp.flashnet.it/pub/CPAN/
Latvia
                      http://kvin.lv/pub/CPAN/
Lithuania
                      ftp://ftp.unix.lt/pub/CPAN/
Netherlands
                      ftp://download.xs4all.nl/pub/mirror/CPAN/
                      ftp://ftp.nl.uu.net/pub/CPAN/
                      ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
                      http://cpan.cybercomm.nl/
                      ftp://mirror.cybercomm.nl/pub/CPAN
                      ftp://mirror.vuurwerk.nl/pub/CPAN/
                      ftp://ftp.cpan.nl/pub/CPAN/
                      http://ftp.easynet.nl/mirror/CPAN
                      ftp://ftp.easynet.nl/mirror/CPAN
                      http://archive.cs.uu.nl/mirror/CPAN/
                      ftp://ftp.cs.uu.nl/mirror/CPAN/
Norway
                      ftp://ftp.uninett.no/pub/languages/perl/CPAN
                      ftp://ftp.uit.no/pub/languages/perl/cpan/
Poland
                      ftp://ftp.mega.net.pl/CPAN
                      ftp://ftp.man.torun.pl/pub/doc/CPAN/
                      ftp://sunsite.icm.edu.pl/pub/CPAN/
Portugal
                      ftp://ftp.ua.pt/pub/CPAN/
                      ftp://perl.di.uminho.pt/pub/CPAN/
                      http://cpan.dei.uc.pt/
                      ftp://ftp.dei.uc.pt/pub/CPAN
                      ftp://ftp.nfsi.pt/pub/CPAN
                      http://ftp.linux.pt/pub/mirrors/CPAN
                      ftp://ftp.linux.pt/pub/mirrors/CPAN
                      http://cpan.ip.pt/
                      ftp://cpan.ip.pt/pub/cpan/
                      http://cpan.telepac.pt/
                      ftp://ftp.telepac.pt/pub/cpan/
Romania
                      ftp://ftp.bio-net.ro/pub/CPAN
                      ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
                      ftp://ftp.lug.ro/CPAN
                      ftp://ftp.roedu.net/pub/CPAN/
                      ftp://ftp.dntis.ro/pub/cpan/
                      ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
                      http://cpan.ambra.ro/
                      ftp://ftp.ambra.ro/pub/CPAN
                      ftp://ftp.dnttm.ro/pub/CPAN/
                      ftp://ftp.lasting.ro/pub/CPAN
                      ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
Russia
                      ftp://ftp.chg.ru/pub/lang/perl/CPAN/
                      http://cpan.rinet.ru/
                      ftp://cpan.rinet.ru/pub/mirror/CPAN/
                      ftp://ftp.aha.ru/pub/CPAN/
                      ftp://ftp.corbina.ru/pub/CPAN/
                      http://cpan.sai.msu.ru/
                      ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
Slovakia
                      ftp://ftp.cvt.stuba.sk/pub/CPAN/
Slovenia
                      ftp://ftp.arnes.si/software/perl/CPAN/
Spain
                      http://cpan.imasd.elmundo.es/
                      ftp://ftp.rediris.es/mirror/CPAN/
                      ftp://ftp.ri.telefonica-data.net/CPAN
                      ftp://ftp.etse.urv.es/pub/perl/
Sweden
                      http://ftp.du.se/CPAN/
                      ftp://ftp.du.se/pub/CPAN/
                      http://mirror.dataphone.se/CPAN
                      ftp://mirror.dataphone.se/pub/CPAN
                      ftp://ftp.sunet.se/pub/lang/perl/CPAN/
Switzerland
                      http://cpan.mirror.solnet.ch/
                      ftp://ftp.solnet.ch/mirror/CPAN/
                      ftp://ftp.danyk.ch/CPAN/
                      ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
Turkey
                      http://ftp.ulak.net.tr/perl/CPAN/
                      ftp://ftp.ulak.net.tr/perl/CPAN
                      ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
Ukraine
                      http://cpan.org.ua/
                      ftp://cpan.org.ua/
                      ftp://ftp.perl.org.ua/pub/CPAN/
                      http://no-more.kiev.ua/CPAN/
                      ftp://no-more.kiev.ua/pub/CPAN/
United Kingdom
                      http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
                      ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
                      http://cpan.teleglobe.net/
                      ftp://cpan.teleglobe.net/pub/CPAN
                      http://cpan.mirror.anlx.net/
                      ftp://ftp.mirror.anlx.net/CPAN/
                      http://cpan.etla.org/
                      ftp://cpan.etla.org/pub/CPAN
                      ftp://ftp.demon.co.uk/pub/CPAN/
                      http://cpan.m.flirble.org/
                      ftp://ftp.flirble.org/pub/languages/perl/CPAN/
                      ftp://ftp.plig.org/pub/CPAN/
                      http://cpan.hambule.co.uk/
                      http://cpan.mirrors.clockerz.net/
                      ftp://ftp.clockerz.net/pub/CPAN/
                      ftp://usit.shef.ac.uk/pub/packages/CPAN/

North America

Canada
Alberta
                      http://cpan.sunsite.ualberta.ca/
                      ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
Manitoba
                      http://theoryx5.uwinnipeg.ca/pub/CPAN/
                      ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
Nova Scotia
                      ftp://cpan.chebucto.ns.ca/pub/CPAN/
Ontario
                      ftp://ftp.nrc.ca/pub/CPAN/
Mexico
                      http://cpan.azc.uam.mx
                      ftp://cpan.azc.uam.mx/mirrors/CPAN
                      http://www.cpan.unam.mx/
                      ftp://ftp.unam.mx/pub/CPAN
                      http://www.msg.com.mx/CPAN/
                      ftp://ftp.msg.com.mx/pub/CPAN/
United States
Alabama
                      http://mirror.hiwaay.net/CPAN/
                      ftp://mirror.hiwaay.net/CPAN/
California
                      http://cpan.develooper.com/
                      http://www.cpan.org/
                      ftp://cpan.valueclick.com/pub/CPAN/
                      http://www.mednor.net/ftp/pub/mirrors/CPAN/
                      ftp://ftp.mednor.net/pub/mirrors/CPAN/
                      http://mirrors.gossamer-threads.com/CPAN
                      ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
                      http://mirrors.kernel.org/cpan/
                      ftp://mirrors.kernel.org/pub/CPAN
                      http://cpan-sj.viaverio.com/
                      ftp://cpan-sj.viaverio.com/pub/CPAN/
                      http://cpan.digisle.net/
                      ftp://cpan.digisle.net/pub/CPAN
                      http://www.perl.com/CPAN/
                      http://www.uberlan.net/CPAN
Colorado
                      ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
                      http://cpan.four10.com
Delaware
                      http://ftp.lug.udel.edu/pub/CPAN
                      ftp://ftp.lug.udel.edu/pub/CPAN
District of Columbia
                      ftp://ftp.dc.aleron.net/pub/CPAN/
Florida
                      ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
                      http://mirror.csit.fsu.edu/pub/CPAN/
                      ftp://mirror.csit.fsu.edu/pub/CPAN/
                      http://cpan.mirrors.nks.net/
Indiana
                      ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
                      http://cpan.netnitco.net/
                      ftp://cpan.netnitco.net/pub/mirrors/CPAN/
                      http://archive.progeny.com/CPAN/
                      ftp://archive.progeny.com/CPAN/
                      http://fx.saintjoe.edu/pub/CPAN
                      ftp://ftp.saintjoe.edu/pub/CPAN
                      http://csociety-ftp.ecn.purdue.edu/pub/CPAN
                      ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
Kentucky
                      http://cpan.uky.edu/
                      ftp://cpan.uky.edu/pub/CPAN/
                      http://slugsite.louisville.edu/cpan
                      ftp://slugsite.louisville.edu/CPAN
Massachusetts
                      http://mirrors.towardex.com/CPAN
                      ftp://mirrors.towardex.com/pub/CPAN
                      ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
Michigan
                      ftp://cpan.cse.msu.edu/
                      http://cpan.calvin.edu/pub/CPAN
                      ftp://cpan.calvin.edu/pub/CPAN
Nevada
                      http://www.oss.redundant.com/pub/CPAN
                      ftp://www.oss.redundant.com/pub/CPAN
New Jersey
                      http://ftp.cpanel.net/pub/CPAN/
                      ftp://ftp.cpanel.net/pub/CPAN/
                      http://cpan.teleglobe.net/
                      ftp://cpan.teleglobe.net/pub/CPAN
New York
                      http://cpan.belfry.net/
                      http://cpan.erlbaum.net/
                      ftp://cpan.erlbaum.net/
                      http://cpan.thepirtgroup.com/
                      ftp://cpan.thepirtgroup.com/
                      ftp://ftp.stealth.net/pub/CPAN/
                      http://www.rge.com/pub/languages/perl/
                      ftp://ftp.rge.com/pub/languages/perl/
North Carolina
                      http://www.ibiblio.org/pub/languages/perl/CPAN
                      ftp://ftp.ibiblio.org/pub/languages/perl/CPAN
                      ftp://ftp.duke.edu/pub/perl/
                      ftp://ftp.ncsu.edu/pub/mirror/CPAN/
Oklahoma
                      ftp://ftp.ou.edu/mirrors/CPAN/
Oregon
                      ftp://ftp.orst.edu/pub/CPAN
Pennsylvania
                      http://ftp.epix.net/CPAN/
                      ftp://ftp.epix.net/pub/languages/perl/
                      http://mirrors.phenominet.com/pub/CPAN/
                      ftp://mirrors.phenominet.com/pub/CPAN/
                      http://cpan.pair.com/
                      ftp://cpan.pair.com/pub/CPAN/
                      ftp://carroll.cac.psu.edu/pub/CPAN/
Tennessee
                      ftp://ftp.sunsite.utk.edu/pub/CPAN/
Texas
                      http://ftp.sedl.org/pub/mirrors/CPAN/
                      http://www.binarycode.org/cpan
                      ftp://mirror.telentente.com/pub/CPAN
                      http://mirrors.theonlinerecordstore.com/CPAN
Utah
                      ftp://mirror.xmission.com/CPAN/
Virginia
                      http://cpan-du.viaverio.com/
                      ftp://cpan-du.viaverio.com/pub/CPAN/
                      http://mirrors.rcn.net/pub/lang/CPAN/
                      ftp://mirrors.rcn.net/pub/lang/CPAN/
                      http://perl.secsup.org/
                      ftp://perl.secsup.org/pub/perl/
                      http://noc.cvaix.com/mirrors/CPAN/
Washington
                      http://cpan.llarian.net/
                      ftp://cpan.llarian.net/pub/CPAN/
                      http://cpan.mirrorcentral.com/
                      ftp://ftp.mirrorcentral.com/pub/CPAN/
                      ftp://ftp-mirror.internap.com/pub/CPAN/
Wisconsin
                      http://mirror.sit.wisc.edu/pub/CPAN/
                      ftp://mirror.sit.wisc.edu/pub/CPAN/
                      http://mirror.aphix.com/CPAN
                      ftp://mirror.aphix.com/pub/CPAN

Oceania

Australia
                      http://ftp.planetmirror.com/pub/CPAN/
                      ftp://ftp.planetmirror.com/pub/CPAN/
                      ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
                      ftp://cpan.topend.com.au/pub/CPAN/
                      http://cpan.mirrors.ilisys.com.au
New Zealand
                      ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
United States
                      http://aniani.ifa.hawaii.edu/CPAN/
                      ftp://aniani.ifa.hawaii.edu/CPAN/

South America

Argentina
                      ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
                      http://www.linux.org.ar/mirrors/cpan
                      ftp://ftp.linux.org.ar/mirrors/cpan
Brazil
                      ftp://cpan.pop-mg.com.br/pub/CPAN/
                      ftp://ftp.matrix.com.br/pub/perl/CPAN/
                      http://cpan.hostsul.com.br/
                      ftp://cpan.hostsul.com.br/
Chile
                      http://cpan.netglobalis.net/
                      ftp://cpan.netglobalis.net/pub/CPAN/

RSYNC Mirrors

                      www.linux.org.ar::cpan
                      theoryx5.uwinnipeg.ca::CPAN
                      ftp.shellhung.org::CPAN
                      rsync.nic.funet.fi::CPAN
                      ftp.u-paris10.fr::CPAN
                      mir1.ovh.net::CPAN
                      rsync://ftp.crihan.fr::CPAN
                      ftp.gwdg.de::FTP/languages/perl/CPAN/
                      ftp.leo.org::CPAN
                      ftp.cbn.net.id::CPAN
                      rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
                      ftp.iglu.org.il::CPAN
                      gusp.dyndns.org::cpan
                      ftp.kddlabs.co.jp::cpan
                      ftp.ayamura.org::pub/CPAN/
                      mirror.leafbug.org::CPAN
                      rsync.en.com.sg::CPAN
                      mirror.averse.net::cpan
                      rsync.oss.eznetsols.org
                      ftp.kr.FreeBSD.org::CPAN
                      ftp.solnet.ch::CPAN
                      cpan.cdpa.nsysu.edu.tw::CPAN
                      cpan.teleglobe.net::CPAN
                      rsync://rsync.mirror.anlx.net::CPAN
                      ftp.sedl.org::cpan
                      ibiblio.org::CPAN
                      cpan-du.viaverio.com::CPAN
                      aniani.ifa.hawaii.edu::CPAN
                      archive.progeny.com::CPAN
                      rsync://slugsite.louisville.edu::CPAN
                      mirror.aphix.com::CPAN
                      cpan.teleglobe.net::CPAN
                      ftp.lug.udel.edu::cpan
                      mirrors.kernel.org::mirrors/CPAN
                      mirrors.phenominet.com::CPAN
                      cpan.pair.com::CPAN
                      cpan-sj.viaverio.com::CPAN
                      mirror.csit.fsu.edu::CPAN
                      csociety-ftp.ecn.purdue.edu::CPAN

For an up-to-date listing of CPAN sites, see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .

Modules: Creation, Use, and Abuse

(The following section is borrowed directly from Tim Bunce's modules file, available at your nearest CPAN site.)

Perl implements a class using a package, but the presence of a package doesn't imply the presence of a class. A package is just a namespace. A class is a package that provides subroutines that can be used as methods. A method is just a subroutine that expects, as its first argument, either the name of a package (for "static" methods), or a reference to something (for "virtual" methods).

A module is a file that (by convention) provides a class of the same name (sans the .pm), plus an import method in that class that can be called to fetch exported symbols. This module may implement some of its methods by loading dynamic C or C++ objects, but that should be totally transparent to the user of the module. Likewise, the module might set up an AUTOLOAD function to slurp in subroutine definitions on demand, but this is also transparent. Only the .pm file is required to exist. See the perlsub manpage, the perltoot manpage, and the AutoLoader manpage for details about the AUTOLOAD mechanism.

Guidelines for Module Creation

  • Do similar modules already exist in some form?

    If so, please try to reuse the existing modules either in whole or by inheriting useful features into a new class. If this is not practical try to get together with the module authors to work on extending or enhancing the functionality of the existing modules. A perfect example is the plethora of packages in perl4 for dealing with command line options.

    If you are writing a module to expand an already existing set of modules, please coordinate with the author of the package. It helps if you follow the same naming scheme and module interaction scheme as the original author.

  • Try to design the new module to be easy to extend and reuse.

    Try to use warnings; (or use warnings qw(...);). Remember that you can add no warnings qw(...); to individual blocks of code that need less warnings.

    Use blessed references. Use the two argument form of bless to bless into the class name given as the first parameter of the constructor, e.g.,:

     sub new {
     my $class = shift;
     return bless {}, $class;
 }

    or even this if you'd like it to be used as either a static or a virtual method.

     sub new {
     my $self  = shift;
     my $class = ref($self) || $self;
     return bless {}, $class;
 }

    Pass arrays as references so more parameters can be added later (it's also faster). Convert functions into methods where appropriate. Split large methods into smaller more flexible ones. Inherit methods from other modules if appropriate.

    Avoid class name tests like: die "Invalid" unless ref $ref eq 'FOO'. Generally you can delete the eq 'FOO' part with no harm at all. Let the objects look after themselves! Generally, avoid hard-wired class names as far as possible.

    Avoid $r->Class::func() where using @ISA=qw(... Class ...) and $r->func() would work (see the perlbot manpage for more details).

    Use autosplit so little used or newly added functions won't be a burden to programs that don't use them. Add test functions to the module after __END__ either using AutoSplit or by saying:

     eval join('',<main::DATA>) || die $@ unless caller();

    Does your module pass the 'empty subclass' test? If you say @SUBCLASS::ISA = qw(YOURCLASS); your applications should be able to use SUBCLASS in exactly the same way as YOURCLASS. For example, does your application still work if you change: $obj = new YOURCLASS; into: $obj = new SUBCLASS; ?

    Avoid keeping any state information in your packages. It makes it difficult for multiple other packages to use yours. Keep state information in objects.

    Always use -w.

    Try to use strict; (or use strict qw(...);). Remember that you can add no strict qw(...); to individual blocks of code that need less strictness.

    Always use -w.

    Follow the guidelines in the perlstyle(1) manual.

    Always use -w.

  • Some simple style guidelines

    The perlstyle manual supplied with Perl has many helpful points.

    Coding style is a matter of personal taste. Many people evolve their style over several years as they learn what helps them write and maintain good code. Here's one set of assorted suggestions that seem to be widely used by experienced developers:

    Use underscores to separate words. It is generally easier to read $var_names_like_this than $VarNamesLikeThis, especially for non-native speakers of English. It's also a simple rule that works consistently with VAR_NAMES_LIKE_THIS.

    Package/Module names are an exception to this rule. Perl informally reserves lowercase module names for 'pragma' modules like integer and strict. Other modules normally begin with a capital letter and use mixed case with no underscores (need to be short and portable).

    You may find it helpful to use letter case to indicate the scope or nature of a variable. For example:

     $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
 $Some_Caps_Here  package-wide global/static
 $no_caps_here    function scope my() or local() variables

    Function and method names seem to work best as all lowercase. e.g., $obj->as_string().

    You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it.

  • Select what to export.

    Do NOT export method names!

    Do NOT export anything else by default without a good reason!

    Exports pollute the namespace of the module user. If you must export try to use @EXPORT_OK in preference to @EXPORT and avoid short or common names to reduce the risk of name clashes.

    Generally anything not exported is still accessible from outside the module using the ModuleName::item_name (or $blessed_ref->method) syntax. By convention you can use a leading underscore on names to indicate informally that they are 'internal' and not for public use.

    (It is actually possible to get private functions by saying: my $subref = sub { ... }; &$subref;. But there's no way to call that directly as a method, because a method must have a name in the symbol table.)

    As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then @EXPORT_OK anything but use @EXPORT with caution.

  • Select a name for the module.

    This name should be as descriptive, accurate, and complete as possible. Avoid any risk of ambiguity. Always try to use two or more whole words. Generally the name should reflect what is special about what the module does rather than how it does it. Please use nested module names to group informally or categorize a module. There should be a very good reason for a module not to have a nested name. Module names should begin with a capital letter.

    Having 57 modules all called Sort will not make life easy for anyone (though having 23 called Sort::Quick is only marginally better :-). Imagine someone trying to install your module alongside many others. If in any doubt ask for suggestions in comp.lang.perl.misc.

    If you are developing a suite of related modules/classes it's good practice to use nested classes with a common prefix as this will avoid namespace clashes. For example: Xyz::Control, Xyz::View, Xyz::Model etc. Use the modules in this list as a naming guide.

    If adding a new module to a set, follow the original author's standards for naming modules and the interface to methods in those modules.

    If developing modules for private internal or project specific use, that will never be released to the public, then you should ensure that their names will not clash with any future public module. You can do this either by using the reserved Local::* category or by using a category name that includes an underscore like Foo_Corp::*.

    To be portable each component of a module name should be limited to 11 characters. If it might be used on MS-DOS then try to ensure each is unique in the first 8 characters. Nested modules make this easier.

  • Have you got it right?

    How do you know that you've made the right decisions? Have you picked an interface design that will cause problems later? Have you picked the most appropriate name? Do you have any questions?

    The best way to know for sure, and pick up many helpful suggestions, is to ask someone who knows. Comp.lang.perl.misc is read by just about all the people who develop modules and it's the best place to ask.

    All you need to do is post a short summary of the module, its purpose and interfaces. A few lines on each of the main methods is probably enough. (If you post the whole module it might be ignored by busy people - generally the very people you want to read it!)

    Don't worry about posting if you can't say when the module will be ready - just say so in the message. It might be worth inviting others to help you, they may be able to complete it for you!

  • README and other Additional Files.

    It's well known that software developers usually fully document the software they write. If, however, the world is in urgent need of your software and there is not enough time to write the full documentation please at least provide a README file containing:

    • A description of the module/package/extension etc.

    • A copyright notice - see below.

    • Prerequisites - what else you may need to have.

    • How to build it - possible changes to Makefile.PL etc.

    • How to install it.

    • Recent changes in this release, especially incompatibilities

    • Changes / enhancements you plan to make in the future.

    If the README file seems to be getting too large you may wish to split out some of the sections into separate files: INSTALL, Copying, ToDo etc.

    • Adding a Copyright Notice.

      How you choose to license your work is a personal decision. The general mechanism is to assert your Copyright and then make a declaration of how others may copy/use/modify your work.

      Perl, for example, is supplied with two types of licence: The GNU GPL and The Artistic Licence (see the files README, Copying, and Artistic, or the perlgpl manpage and the perlartistic manpage). Larry has good reasons for NOT just using the GNU GPL.

      My personal recommendation, out of respect for Larry, Perl, and the Perl community at large is to state something simply like:

       Copyright (c) 1995 Your Name. All rights reserved.
 This program is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself.

      This statement should at least appear in the README file. You may also wish to include it in a Copying file and your source files. Remember to include the other words in addition to the Copyright.

    • Give the module a version/issue/release number.

      To be fully compatible with the Exporter and MakeMaker modules you should store your module's version number in a non-my package variable called $VERSION. This should be a floating point number with at least two digits after the decimal (i.e., hundredths, e.g, $VERSION = "0.01"). Don't use a "1.3.2" style version. See the Exporter manpage for details.

      It may be handy to add a function or method to retrieve the number. Use the number in announcements and archive file names when releasing the module (ModuleName-1.02.tar.Z). See perldoc ExtUtils::MakeMaker.pm for details.

    • How to release and distribute a module.

      It's good idea to post an announcement of the availability of your module (or the module itself if small) to the comp.lang.perl.announce Usenet newsgroup. This will at least ensure very wide once-off distribution.

      If possible, register the module with CPAN. You should include details of its location in your announcement.

      Some notes about ftp archives: Please use a long descriptive file name that includes the version number. Most incoming directories will not be readable/listable, i.e., you won't be able to see your file after uploading it. Remember to send your email notification message as soon as possible after uploading else your file may get deleted automatically. Allow time for the file to be processed and/or check the file has been processed before announcing its location.

      FTP Archives for Perl Modules:

      Follow the instructions and links on:

         http://www.cpan.org/modules/00modlist.long.html
   http://www.cpan.org/modules/04pause.html

      or upload to one of these sites:

         https://pause.kbx.de/pause/
   http://pause.perl.org/pause/

      and notify <modules@perl.org>.

      By using the WWW interface you can ask the Upload Server to mirror your modules from your ftp or WWW site into your own directory on CPAN!

      Please remember to send me an updated entry for the Module list!

    • Take care when changing a released module.

      Always strive to remain compatible with previous released versions. Otherwise try to add a mechanism to revert to the old behavior if people rely on it. Document incompatible changes.

Guidelines for Converting Perl 4 Library Scripts into Modules

  • There is no requirement to convert anything.

    If it ain't broke, don't fix it! Perl 4 library scripts should continue to work with no problems. You may need to make some minor changes (like escaping non-array @'s in double quoted strings) but there is no need to convert a .pl file into a Module for just that.

  • Consider the implications.

    All Perl applications that make use of the script will need to be changed (slightly) if the script is converted into a module. Is it worth it unless you plan to make other changes at the same time?

  • Make the most of the opportunity.

    If you are going to convert the script to a module you can use the opportunity to redesign the interface. The guidelines for module creation above include many of the issues you should consider.

  • The pl2pm utility will get you started.

    This utility will read *.pl files (given as parameters) and write corresponding *.pm files. The pl2pm utilities does the following:

    • Adds the standard Module prologue lines

    • Converts package specifiers from ' to ::

    • Converts die(...) to croak(...)

    • Several other minor changes

    Being a mechanical process pl2pm is not bullet proof. The converted code will need careful checking, especially any package statements. Don't delete the original .pl file till the new .pm one works!

Guidelines for Reusing Application Code

  • Complete applications rarely belong in the Perl Module Library.

  • Many applications contain some Perl code that could be reused.

    Help save the world! Share your code in a form that makes it easy to reuse.

  • Break-out the reusable code into one or more separate module files.

  • Take the opportunity to reconsider and redesign the interfaces.

  • In some cases the 'application' can then be reduced to a small

    fragment of code built on top of the reusable modules. In these cases the application could invoked as:

         % perl -e 'use Module::Name; method(@ARGV)' ...
     or
     % perl -mModule::Name ...    (in perl5.002 or higher)

NOTE

Perl does not enforce private and public parts of its modules as you may have been used to in other languages like C++, Ada, or Modula-17. Perl doesn't have an infatuation with enforced privacy. It would prefer that you stayed out of its living room because you weren't invited, not because it has a shotgun.

The module and its user have a contract, part of which is common law, and part of which is "written". Part of the common law contract is that a module doesn't pollute any namespace it wasn't asked to. The written contract for the module (A.K.A. documentation) may make other provisions. But then you know when you use RedefineTheWorld that you're redefining the world and willing to take the consequences.


perlmodstyle - Perl module style guide

  • INTRODUCTION
  • QUICK CHECKLIST
    • Before you start
    • The API
    • Stability
    • Documentation
    • Release considerations
  • BEFORE YOU START WRITING A MODULE
    • Has it been done before?
    • Do one thing and do it well
    • What's in a name?
  • DESIGNING AND WRITING YOUR MODULE
    • To OO or not to OO?
    • Designing your API
    • Strictness and warnings
    • Backwards compatibility
    • Error handling and messages
  • DOCUMENTING YOUR MODULE
    • POD
    • README, INSTALL, release notes, changelogs
  • RELEASE CONSIDERATIONS
    • Version numbering
    • Pre-requisites
    • Testing
    • Packaging
    • Licensing
  • COMMON PITFALLS
    • Reinventing the wheel
    • Trying to do too much
    • Inappropriate documentation
  • SEE ALSO
  • AUTHOR

NAME

perlmodstyle - Perl module style guide

INTRODUCTION

This document attempts to describe the Perl Community's "best practice" for writing Perl modules. It extends the recommendations found in the perlstyle manpage , which should be considered required reading before reading this document.

While this document is intended to be useful to all module authors, it is particularly aimed at authors who wish to publish their modules on CPAN.

The focus is on elements of style which are visible to the users of a module, rather than those parts which are only seen by the module's developers. However, many of the guidelines presented in this document can be extrapolated and applied successfully to a module's internals.

This document differs from the perlnewmod manpage in that it is a style guide rather than a tutorial on creating CPAN modules. It provides a checklist against which modules can be compared to determine whether they conform to best practice, without necessarily describing in detail how to achieve this.

All the advice contained in this document has been gleaned from extensive conversations with experienced CPAN authors and users. Every piece of advice given here is the result of previous mistakes. This information is here to help you avoid the same mistakes and the extra work that would inevitably be required to fix them.

The first section of this document provides an itemized checklist; subsequent sections provide a more detailed discussion of the items on the list. The final section, "Common Pitfalls", describes some of the most popular mistakes made by CPAN authors.

QUICK CHECKLIST

For more detail on each item in this checklist, see below.

Before you start

  • Don't re-invent the wheel

  • Patch, extend or subclass an existing module where possible

  • Do one thing and do it well

  • Choose an appropriate name

The API

  • API should be understandable by the average programmer

  • Simple methods for simple tasks

  • Separate functionality from output

  • Consistent naming of subroutines or methods

  • Use named parameters (a hash or hashref) when there are more than two parameters

Stability

  • Ensure your module works under use strict and -w

  • Stable modules should maintain backwards compatibility

Documentation

  • Write documentation in POD

  • Document purpose, scope and target applications

  • Document each publically accessible method or subroutine, including params and return values

  • Give examples of use in your documentation

  • Provide a README file and perhaps also release notes, changelog, etc

  • Provide links to further information (URL, email)

Release considerations

  • Specify pre-requisites in Makefile.PL or Build.PL

  • Specify Perl version requirements with use

  • Include tests with your module

  • Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)

  • Increment the version number for every change, no matter how small

  • Package the module using "make dist"

  • Choose an appropriate license (GPL/Artistic is a good default)

BEFORE YOU START WRITING A MODULE

Try not to launch headlong into developing your module without spending some time thinking first. A little forethought may save you a vast amount of effort later on.

Has it been done before?

You may not even need to write the module. Check whether it's already been done in Perl, and avoid re-inventing the wheel unless you have a good reason.

Good places to look for pre-existing modules include http://search.cpan.org/ and asking on modules@perl.org

If an existing module almost does what you want, consider writing a patch, writing a subclass, or otherwise extending the existing module rather than rewriting it.

Do one thing and do it well

At the risk of stating the obvious, modules are intended to be modular. A Perl developer should be able to use modules to put together the building blocks of their application. However, it's important that the blocks are the right shape, and that the developer shouldn't have to use a big block when all they need is a small one.

Your module should have a clearly defined scope which is no longer than a single sentence. Can your module be broken down into a family of related modules?

Bad example:

"FooBar.pm provides an implementation of the FOO protocol and the related BAR standard."

Good example:

"Foo.pm provides an implementation of the FOO protocol. Bar.pm implements the related BAR protocol."

This means that if a developer only needs a module for the BAR standard, they should not be forced to install libraries for FOO as well.

What's in a name?

Make sure you choose an appropriate name for your module early on. This will help people find and remember your module, and make programming with your module more intuitive.

When naming your module, consider the following:

  • Be descriptive (i.e. accurately describes the purpose of the module).

  • Be consistent with existing modules.

  • Reflect the functionality of the module, not the implementation.

  • Avoid starting a new top-level hierarchy, especially if a suitable hierarchy already exists under which you could place your module.

You should contact modules@perl.org to ask them about your module name before publishing your module. You should also try to ask people who are already familiar with the module's application domain and the CPAN naming system. Authors of similar modules, or modules with similar names, may be a good place to start.

DESIGNING AND WRITING YOUR MODULE

Considerations for module design and coding:

To OO or not to OO?

Your module may be object oriented (OO) or not, or it may have both kinds of interfaces available. There are pros and cons of each technique, which should be considered when you design your API.

According to Damian Conway, you should consider using OO:

  • When the system is large or likely to become so

  • When the data is aggregated in obvious structures that will become objects

  • When the types of data form a natural hierarchy that can make use of inheritance

  • When operations on data vary according to data type (making polymorphic invocation of methods feasible)

  • When it is likely that new data types may be later introduced into the system, and will need to be handled by existing code

  • When interactions between data are best represented by overloaded operators

  • When the implementation of system components is likely to change over time (and hence should be encapsulated)

  • When the system design is itself object-oriented

  • When large amounts of client code will use the software (and should be insulated from changes in its implementation)

  • When many separate operations will need to be applied to the same set of data

Think carefully about whether OO is appropriate for your module. Gratuitous object orientation results in complex APIs which are difficult for the average module user to understand or use.

Designing your API

Your interfaces should be understandable by an average Perl programmer. The following guidelines may help you judge whether your API is sufficiently straightforward:

Write simple routines to do simple things.

It's better to have numerous simple routines than a few monolithic ones. If your routine changes its behaviour significantly based on its arguments, it's a sign that you should have two (or more) separate routines.

Separate functionality from output.

Return your results in the most generic form possible and allow the user to choose how to use them. The most generic form possible is usually a Perl data structure which can then be used to generate a text report, HTML, XML, a database query, or whatever else your users require.

If your routine iterates through some kind of list (such as a list of files, or records in a database) you may consider providing a callback so that users can manipulate each element of the list in turn. File::Find provides an example of this with its find(\&wanted, $dir) syntax.

Provide sensible shortcuts and defaults.

Don't require every module user to jump through the same hoops to achieve a simple result. You can always include optional parameters or routines for more complex or non-standard behaviour. If most of your users have to type a few almost identical lines of code when they start using your module, it's a sign that you should have made that behaviour a default. Another good indicator that you should use defaults is if most of your users call your routines with the same arguments.

Naming conventions

Your naming should be consistent. For instance, it's better to have:

        display_day();
        display_week();
        display_year();

than

        display_day();
        week_display();
        show_year();

This applies equally to method names, parameter names, and anything else which is visible to the user (and most things that aren't!)

Parameter passing

Use named parameters. It's easier to use a hash like this:

    $obj->do_something(
            name => "wibble",
            type => "text",
            size => 1024,
    );

... than to have a long list of unnamed parameters like this:

    $obj->do_something("wibble", "text", 1024);

While the list of arguments might work fine for one, two or even three arguments, any more arguments become hard for the module user to remember, and hard for the module author to manage. If you want to add a new parameter you will have to add it to the end of the list for backward compatibility, and this will probably make your list order unintuitive. Also, if many elements may be undefined you may see the following unattractive method calls:

    $obj->do_something(undef, undef, undef, undef, undef, undef, 1024);

Provide sensible defaults for parameters which have them. Don't make your users specify parameters which will almost always be the same.

The issue of whether to pass the arguments in a hash or a hashref is largely a matter of personal style.

The use of hash keys starting with a hyphen (-name) or entirely in upper case (NAME) is a relic of older versions of Perl in which ordinary lower case strings were not handled correctly by the => operator. While some modules retain uppercase or hyphenated argument keys for historical reasons or as a matter of personal style, most new modules should use simple lower case keys. Whatever you choose, be consistent!

Strictness and warnings

Your module should run successfully under the strict pragma and should run without generating any warnings. Your module should also handle taint-checking where appropriate, though this can cause difficulties in many cases.

Backwards compatibility

Modules which are "stable" should not break backwards compatibility without at least a long transition phase and a major change in version number.

Error handling and messages

When your module encounters an error it should do one or more of:

  • Return an undefined value.

  • set $Module::errstr or similar (errstr is a common name used by DBI and other popular modules; if you choose something else, be sure to document it clearly).

  • warn() or carp() a message to STDERR.

  • croak() only when your module absolutely cannot figure out what to do. (croak() is a better version of die() for use within modules, which reports its errors from the perspective of the caller. See the Carp manpage for details of croak(), carp() and other useful routines.)

  • As an alternative to the above, you may prefer to throw exceptions using the Error module.

Configurable error handling can be very useful to your users. Consider offering a choice of levels for warning and debug messages, an option to send messages to a separate file, a way to specify an error-handling routine, or other such features. Be sure to default all these options to the commonest use.

DOCUMENTING YOUR MODULE

POD

Your module should include documentation aimed at Perl developers. You should use Perl's "plain old documentation" (POD) for your general technical documentation, though you may wish to write additional documentation (white papers, tutorials, etc) in some other format. You need to cover the following subjects:

  • A synopsis of the common uses of the module

  • The purpose, scope and target applications of your module

  • Use of each publically accessible method or subroutine, including parameters and return values

  • Examples of use

  • Sources of further information

  • A contact email address for the author/maintainer

The level of detail in Perl module documentation generally goes from less detailed to more detailed. Your SYNOPSIS section should contain a minimal example of use (perhaps as little as one line of code; skip the unusual use cases or anything not needed by most users); the DESCRIPTION should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections.

Ideally, someone who's slightly familiar with your module should be able to refresh their memory without hitting "page down". As your reader continues through the document, they should receive a progressively greater amount of knowledge.

The recommended order of sections in Perl module documentation is:

  • NAME

  • SYNOPSIS

  • DESCRIPTION

  • One or more sections or subsections giving greater detail of available methods and routines and any other relevant information.

  • BUGS/CAVEATS/etc

  • AUTHOR

  • SEE ALSO

  • COPYRIGHT and LICENSE

Keep your documentation near the code it documents ("inline" documentation). Include POD for a given method right above that method's subroutine. This makes it easier to keep the documentation up to date, and avoids having to document each piece of code twice (once in POD and once in comments).

README, INSTALL, release notes, changelogs

Your module should also include a README file describing the module and giving pointers to further information (website, author email).

An INSTALL file should be included, and should contain simple installation instructions. When using ExtUtils::MakeMaker this will usually be:

perl Makefile.PL
make
make test
make install

When using Module::Build, this will usually be:

perl Build.PL
perl Build
perl Build test
perl Build install

Release notes or changelogs should be produced for each release of your software describing user-visible changes to your module, in terms relevant to the user.

RELEASE CONSIDERATIONS

Version numbering

Version numbers should indicate at least major and minor releases, and possibly sub-minor releases. A major release is one in which most of the functionality has changed, or in which major new functionality is added. A minor release is one in which a small amount of functionality has been added or changed. Sub-minor version numbers are usually used for changes which do not affect functionality, such as documentation patches.

The most common CPAN version numbering scheme looks like this:

    1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32

A correct CPAN version number is a floating point number with at least 2 digits after the decimal. You can test whether it conforms to CPAN by using

    perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'

If you want to release a 'beta' or 'alpha' version of a module but don't want CPAN.pm to list it as most recent use an '_' after the regular version number followed by at least 2 digits, eg. 1.20_01. If you do this, the following idiom is recommended:

  $VERSION = "1.12_01";
  $XS_VERSION = $VERSION; # only needed if you have XS code
  $VERSION = eval $VERSION;

With that trick MakeMaker will only read the first line and thus read the underscore, while the perl interpreter will evaluate the $VERSION and convert the string into a number. Later operations that treat $VERSION as a number will then be able to do so without provoking a warning about $VERSION not being a number.

Never release anything (even a one-word documentation patch) without incrementing the number. Even a one-word documentation patch should result in a change in version at the sub-minor level.

Pre-requisites

Module authors should carefully consider whether to rely on other modules, and which modules to rely on.

Most importantly, choose modules which are as stable as possible. In order of preference:

  • Core Perl modules

  • Stable CPAN modules

  • Unstable CPAN modules

  • Modules not available from CPAN

Specify version requirements for other Perl modules in the pre-requisites in your Makefile.PL or Build.PL.

Be sure to specify Perl version requirements both in Makefile.PL or Build.PL and with require 5.6.1 or similar. See the section on use VERSION of require in the perlfunc manpage for details.

Testing

All modules should be tested before distribution (using "make disttest"), and the tests should also be available to people installing the modules (using "make test"). For Module::Build you would use the make test equivalent perl Build test.

The importance of these tests is proportional to the alleged stability of a module -- a module which purports to be stable or which hopes to achieve wide use should adhere to as strict a testing regime as possible.

Useful modules to help you write tests (with minimum impact on your development process or your time) include Test::Simple, Carp::Assert and Test::Inline. For more sophisticated test suites there are Test::More and Test::MockObject.

Packaging

Modules should be packaged using one of the standard packaging tools. Currently you have the choice between ExtUtils::MakeMaker and the more platform independent Module::Build, allowing modules to be installed in a consistent manner. When using ExtUtils::MakeMaker, you can use "make dist" to create your package. Tools exist to help you to build your module in a MakeMaker-friendly style. These include ExtUtils::ModuleMaker and h2xs. See also the perlnewmod manpage.

Licensing

Make sure that your module has a license, and that the full text of it is included in the distribution (unless it's a common one and the terms of the license don't require you to include it).

If you don't know what license to use, dual licensing under the GPL and Artistic licenses (the same as Perl itself) is a good idea. See the perlgpl manpage and the perlartistic manpage.

COMMON PITFALLS

Reinventing the wheel

There are certain application spaces which are already very, very well served by CPAN. One example is templating systems, another is date and time modules, and there are many more. While it is a rite of passage to write your own version of these things, please consider carefully whether the Perl world really needs you to publish it.

Trying to do too much

Your module will be part of a developer's toolkit. It will not, in itself, form the entire toolkit. It's tempting to add extra features until your code is a monolithic system rather than a set of modular building blocks.

Inappropriate documentation

Don't fall into the trap of writing for the wrong audience. Your primary audience is a reasonably experienced developer with at least a moderate understanding of your module's application domain, who's just downloaded your module and wants to start using it as quickly as possible.

Tutorials, end-user documentation, research papers, FAQs etc are not appropriate in a module's main documentation. If you really want to write these, include them as sub-documents such as My::Module::Tutorial or My::Module::FAQ and provide a link in the SEE ALSO section of the main documentation.

SEE ALSO

the perlstyle manpage

General Perl style guide

the perlnewmod manpage

How to create a new module

the perlpod manpage

POD documentation

podchecker

Verifies your POD's correctness

Packaging Tools

the ExtUtils::MakeMaker manpage, the Module::Build manpage

Testing tools

the Test::Simple manpage, the Test::Inline manpage, the Carp::Assert manpage, the Test::More manpage, the Test::MockObject manpage

http://pause.perl.org/

Perl Authors Upload Server. Contains links to information for module authors.

Any good book on software engineering

AUTHOR

Kirrily "Skud" Robert <skud@cpan.org>


perlnewmod - preparing a new module for distribution

    • Warning
    • What should I make into a module?
    • Step-by-step: Preparing the ground
    • Step-by-step: Making the module
    • Step-by-step: Distributing your module
  • AUTHOR
  • SEE ALSO

NAME

perlnewmod - preparing a new module for distribution

DESCRIPTION

This document gives you some suggestions about how to go about writing Perl modules, preparing them for distribution, and making them available via CPAN.

One of the things that makes Perl really powerful is the fact that Perl hackers tend to want to share the solutions to problems they've faced, so you and I don't have to battle with the same problem again.

The main way they do this is by abstracting the solution into a Perl module. If you don't know what one of these is, the rest of this document isn't going to be much use to you. You're also missing out on an awful lot of useful code; consider having a look at the perlmod manpage, the perlmodlib manpage and the perlmodinstall manpage before coming back here.

When you've found that there isn't a module available for what you're trying to do, and you've had to write the code yourself, consider packaging up the solution into a module and uploading it to CPAN so that others can benefit.

Warning

We're going to primarily concentrate on Perl-only modules here, rather than XS modules. XS modules serve a rather different purpose, and you should consider different things before distributing them - the popularity of the library you are gluing, the portability to other operating systems, and so on. However, the notes on preparing the Perl side of the module and packaging and distributing it will apply equally well to an XS module as a pure-Perl one.

What should I make into a module?

You should make a module out of any code that you think is going to be useful to others. Anything that's likely to fill a hole in the communal library and which someone else can slot directly into their program. Any part of your code which you can isolate and extract and plug into something else is a likely candidate.

Let's take an example. Suppose you're reading in data from a local format into a hash-of-hashes in Perl, turning that into a tree, walking the tree and then piping each node to an Acme Transmogrifier Server.

Now, quite a few people have the Acme Transmogrifier, and you've had to write something to talk the protocol from scratch - you'd almost certainly want to make that into a module. The level at which you pitch it is up to you: you might want protocol-level modules analogous to Net::SMTP which then talk to higher level modules analogous to Mail::Send. The choice is yours, but you do want to get a module out for that server protocol.

Nobody else on the planet is going to talk your local data format, so we can ignore that. But what about the thing in the middle? Building tree structures from Perl variables and then traversing them is a nice, general problem, and if nobody's already written a module that does that, you might want to modularise that code too.

So hopefully you've now got a few ideas about what's good to modularise. Let's now see how it's done.

Step-by-step: Preparing the ground

Before we even start scraping out the code, there are a few things we'll want to do in advance.

Look around

Dig into a bunch of modules to see how they're written. I'd suggest starting with Text::Tabs, since it's in the standard library and is nice and simple, and then looking at something a little more complex like File::Copy. For object oriented code, WWW::Mechanize or the Email::* modules provide some good examples.

These should give you an overall feel for how modules are laid out and written.

Check it's new

There are a lot of modules on CPAN, and it's easy to miss one that's similar to what you're planning on contributing. Have a good plough through the http://search.cpan.org and make sure you're not the one reinventing the wheel!

Discuss the need

You might love it. You might feel that everyone else needs it. But there might not actually be any real demand for it out there. If you're unsure about the demand your module will have, consider sending out feelers on the comp.lang.perl.modules newsgroup, or as a last resort, ask the modules list at modules@perl.org. Remember that this is a closed list with a very long turn-around time - be prepared to wait a good while for a response from them.

Choose a name

Perl modules included on CPAN have a naming hierarchy you should try to fit in with. See the perlmodlib manpage for more details on how this works, and browse around CPAN and the modules list to get a feel of it. At the very least, remember this: modules should be title capitalised, (This::Thing) fit in with a category, and explain their purpose succinctly.

Check again

While you're doing that, make really sure you haven't missed a module similar to the one you're about to write.

When you've got your name sorted out and you're sure that your module is wanted and not currently available, it's time to start coding.

Step-by-step: Making the module

Start with module-starter or h2xs

The module-starter utility is distributed as part of the Module::Starter CPAN package. It creates a directory with stubs of all the necessary files to start a new module, according to recent "best practice" for module development, and is invoked from the command line, thus:

    module-starter --module=Foo::Bar \
       --author="Your Name" --email=yourname@cpan.org

If you do not wish to install the Module::Starter package from CPAN, h2xs is an older tool, originally intended for the development of XS modules, which comes packaged with the Perl distribution.

A typical invocation of h2xs for a pure Perl module is:

    h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar

The -A omits the Autoloader code, -X omits XS elements, --skip-exporter omits the Exporter code, --use-new-tests sets up a modern testing environment, and -n specifies the name of the module.

Use strict and warnings

A module's code has to be warning and strict-clean, since you can't guarantee the conditions that it'll be used under. Besides, you wouldn't want to distribute code that wasn't warning or strict-clean anyway, right?

Use Carp

The Carp module allows you to present your error messages from the caller's perspective; this gives you a way to signal a problem with the caller and not your module. For instance, if you say this:

    warn "No hostname given";

the user will see something like this:

    No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
    line 123.

which looks like your module is doing something wrong. Instead, you want to put the blame on the user, and say this:

    No hostname given at bad_code, line 10.

You do this by using Carp and replacing your warns with carps. If you need to die, say croak instead. However, keep warn and die in place for your sanity checks - where it really is your module at fault.

Use Exporter - wisely!

Exporter gives you a standard way of exporting symbols and subroutines from your module into the caller's namespace. For instance, saying use Net::Acme qw(&frob) would import the frob subroutine.

The package variable @EXPORT will determine which symbols will get exported when the caller simply says use Net::Acme - you will hardly ever want to put anything in there. @EXPORT_OK, on the other hand, specifies which symbols you're willing to export. If you do want to export a bunch of symbols, use the %EXPORT_TAGS and define a standard export set - look at the Exporter manpage for more details.

Use plain old documentation

The work isn't over until the paperwork is done, and you're going to need to put in some time writing some documentation for your module. module-starter or h2xs will provide a stub for you to fill in; if you're not sure about the format, look at the perlpod manpage for an introduction. Provide a good synopsis of how your module is used in code, a description, and then notes on the syntax and function of the individual subroutines or methods. Use Perl comments for developer notes and POD for end-user notes.

Write tests

You're encouraged to create self-tests for your module to ensure it's working as intended on the myriad platforms Perl supports; if you upload your module to CPAN, a host of testers will build your module and send you the results of the tests. Again, module-starter and h2xs provide a test framework which you can extend - you should do something more than just checking your module will compile. Test::Simple and Test::More are good places to start when writing a test suite.

Write the README

If you're uploading to CPAN, the automated gremlins will extract the README file and place that in your CPAN directory. It'll also appear in the main by-module and by-category directories if you make it onto the modules list. It's a good idea to put here what the module actually does in detail, and the user-visible changes since the last release.

Step-by-step: Distributing your module

Get a CPAN user ID

Every developer publishing modules on CPAN needs a CPAN ID. Visit http://pause.perl.org/, select "Request PAUSE Account", and wait for your request to be approved by the PAUSE administrators.

perl Makefile.PL; make test; make dist

Once again, module-starter or h2xs has done all the work for you. They produce the standard Makefile.PL you see when you download and install modules, and this produces a Makefile with a dist target.

Once you've ensured that your module passes its own tests - always a good thing to make sure - you can make dist, and the Makefile will hopefully produce you a nice tarball of your module, ready for upload.

Upload the tarball

The email you got when you received your CPAN ID will tell you how to log in to PAUSE, the Perl Authors Upload SErver. From the menus there, you can upload your module to CPAN.

Announce to the modules list

Once uploaded, it'll sit unnoticed in your author directory. If you want it connected to the rest of the CPAN, you'll need to go to "Register Namespace" on PAUSE. Once registered, your module will appear in the by-module and by-category listings on CPAN.

Announce to clpa

If you have a burning desire to tell the world about your release, post an announcement to the moderated comp.lang.perl.announce newsgroup.

Fix bugs!

Once you start accumulating users, they'll send you bug reports. If you're lucky, they'll even send you patches. Welcome to the joys of maintaining a software project...

AUTHOR

Simon Cozens, simon@cpan.org

Updated by Kirrily "Skud" Robert, skud@cpan.org

SEE ALSO

the perlmod manpage, the perlmodlib manpage, the perlmodinstall manpage, h2xs, the strict manpage, the Carp manpage, the Exporter manpage, the perlpod manpage, the Test::Simple manpage, the Test::More manpage the ExtUtils::MakeMaker manpage, the Module::Build manpage, the Module::Starter manpage http://www.cpan.org/ , Ken Williams' tutorial on building your own module at http://mathforum.org/~ken/perl_modules.html


perlboot - Beginner's Object-Oriented Tutorial

    • If we could talk to the animals...
    • Introducing the method invocation arrow
    • Invoking a barnyard
    • The extra parameter of method invocation
    • Calling a second method to simplify things
    • Inheriting the windpipes
    • A few notes about @ISA
    • Overriding the methods
    • Starting the search from a different place
    • The SUPER way of doing things
    • Where we're at so far...
    • A horse is a horse, of course of course - or is it?
    • Invoking an instance method
    • Accessing the instance data
    • How to build a horse
    • Inheriting the constructor
    • Making a method work with either classes or instances
    • Adding parameters to a method
    • More interesting instances
    • A horse of a different color
    • Summary
  • SEE ALSO
  • COPYRIGHT

NAME

perlboot - Beginner's Object-Oriented Tutorial

DESCRIPTION

If you're not familiar with objects from other languages, some of the other Perl object documentation may be a little daunting, such as the perlobj manpage, a basic reference in using objects, and the perltoot manpage, which introduces readers to the peculiarities of Perl's object system in a tutorial way.

So, let's take a different approach, presuming no prior object experience. It helps if you know about subroutines (the perlsub manpage), references (the perlref manpage et. seq.), and packages (the perlmod manpage), so become familiar with those first if you haven't already.

If we could talk to the animals...

Let's let the animals talk for a moment:

    sub Cow::speak {
      print "a Cow goes moooo!\n";
    }
    sub Horse::speak {
      print "a Horse goes neigh!\n";
    }
    sub Sheep::speak {
      print "a Sheep goes baaaah!\n"
    }

    Cow::speak;
    Horse::speak;
    Sheep::speak;

This results in:

    a Cow goes moooo!
    a Horse goes neigh!
    a Sheep goes baaaah!

Nothing spectacular here. Simple subroutines, albeit from separate packages, and called using the full package name. So let's create an entire pasture:

    # Cow::speak, Horse::speak, Sheep::speak as before
    @pasture = qw(Cow Cow Horse Sheep Sheep);
    foreach $animal (@pasture) {
      &{$animal."::speak"};
    }

This results in:

    a Cow goes moooo!
    a Cow goes moooo!
    a Horse goes neigh!
    a Sheep goes baaaah!
    a Sheep goes baaaah!

Wow. That symbolic coderef de-referencing there is pretty nasty. We're counting on no strict subs mode, certainly not recommended for larger programs. And why was that necessary? Because the name of the package seems to be inseparable from the name of the subroutine we want to invoke within that package.

Or is it?

Introducing the method invocation arrow

For now, let's say that Class->method invokes subroutine method in package Class. (Here, "Class" is used in its "category" meaning, not its "scholastic" meaning.) That's not completely accurate, but we'll do this one step at a time. Now let's use it like so:

    # Cow::speak, Horse::speak, Sheep::speak as before
    Cow->speak;
    Horse->speak;
    Sheep->speak;

And once again, this results in:

    a Cow goes moooo!
    a Horse goes neigh!
    a Sheep goes baaaah!

That's not fun yet. Same number of characters, all constant, no variables. But yet, the parts are separable now. Watch:

    $a = "Cow";
    $a->speak; # invokes Cow->speak

Ahh! Now that the package name has been parted from the subroutine name, we can use a variable package name. And this time, we've got something that works even when use strict refs is enabled.

Invoking a barnyard

Let's take that new arrow invocation and put it back in the barnyard example:

    sub Cow::speak {
      print "a Cow goes moooo!\n";
    }
    sub Horse::speak {
      print "a Horse goes neigh!\n";
    }
    sub Sheep::speak {
      print "a Sheep goes baaaah!\n"
    }

    @pasture = qw(Cow Cow Horse Sheep Sheep);
    foreach $animal (@pasture) {
      $animal->speak;
    }

There! Now we have the animals all talking, and safely at that, without the use of symbolic coderefs.

But look at all that common code. Each of the speak routines has a similar structure: a print operator and a string that contains common text, except for two of the words. It'd be nice if we could factor out the commonality, in case we decide later to change it all to says instead of goes.

And we actually have a way of doing that without much fuss, but we have to hear a bit more about what the method invocation arrow is actually doing for us.

The extra parameter of method invocation

The invocation of:

    Class->method(@args)

attempts to invoke subroutine Class::method as:

    Class::method("Class", @args);

(If the subroutine can't be found, "inheritance" kicks in, but we'll get to that later.) This means that we get the class name as the first parameter (the only parameter, if no arguments are given). So we can rewrite the Sheep speaking subroutine as:

    sub Sheep::speak {
      my $class = shift;
      print "a $class goes baaaah!\n";
    }

And the other two animals come out similarly:

    sub Cow::speak {
      my $class = shift;
      print "a $class goes moooo!\n";
    }
    sub Horse::speak {
      my $class = shift;
      print "a $class goes neigh!\n";
    }

In each case, $class will get the value appropriate for that subroutine. But once again, we have a lot of similar structure. Can we factor that out even further? Yes, by calling another method in the same class.

Calling a second method to simplify things

Let's call out from speak to a helper method called sound. This method provides the constant text for the sound itself.

    { package Cow;
      sub sound { "moooo" }
      sub speak {
        my $class = shift;
        print "a $class goes ", $class->sound, "!\n"
      }
    }

Now, when we call Cow->speak, we get a $class of Cow in speak. This in turn selects the Cow->sound method, which returns moooo. But how different would this be for the Horse?

    { package Horse;
      sub sound { "neigh" }
      sub speak {
        my $class = shift;
        print "a $class goes ", $class->sound, "!\n"
      }
    }

Only the name of the package and the specific sound change. So can we somehow share the definition for speak between the Cow and the Horse? Yes, with inheritance!

Inheriting the windpipes

We'll define a common subroutine package called Animal, with the definition for speak:

    { package Animal;
      sub speak {
        my $class = shift;
        print "a $class goes ", $class->sound, "!\n"
      }
    }

Then, for each animal, we say it "inherits" from Animal, along with the animal-specific sound:

    { package Cow;
      @ISA = qw(Animal);
      sub sound { "moooo" }
    }

Note the added @ISA array. We'll get to that in a minute.

But what happens when we invoke Cow->speak now?

First, Perl constructs the argument list. In this case, it's just Cow. Then Perl looks for Cow::speak. But that's not there, so Perl checks for the inheritance array @Cow::ISA. It's there, and contains the single name Animal.

Perl next checks for speak inside Animal instead, as in Animal::speak. And that's found, so Perl invokes that subroutine with the already frozen argument list.

Inside the Animal::speak subroutine, $class becomes Cow (the first argument). So when we get to the step of invoking $class->sound, it'll be looking for Cow->sound, which gets it on the first try without looking at @ISA. Success!

A few notes about @ISA

This magical @ISA variable (pronounced "is a" not "ice-uh"), has declared that Cow "is a" Animal. Note that it's an array, not a simple single value, because on rare occasions, it makes sense to have more than one parent class searched for the missing methods.

If Animal also had an @ISA, then we'd check there too. The search is recursive, depth-first, left-to-right in each @ISA. Typically, each @ISA has only one element (multiple elements means multiple inheritance and multiple headaches), so we get a nice tree of inheritance.

When we turn on use strict, we'll get complaints on @ISA, since it's not a variable containing an explicit package name, nor is it a lexical ("my") variable. We can't make it a lexical variable though (it has to belong to the package to be found by the inheritance mechanism), so there's a couple of straightforward ways to handle that.

The easiest is to just spell the package name out:

    @Cow::ISA = qw(Animal);

Or allow it as an implicitly named package variable:

    package Cow;
    use vars qw(@ISA);
    @ISA = qw(Animal);

If you're bringing in the class from outside, via an object-oriented module, you change:

    package Cow;
    use Animal;
    use vars qw(@ISA);
    @ISA = qw(Animal);

into just:

    package Cow;
    use base qw(Animal);

And that's pretty darn compact.

Overriding the methods

Let's add a mouse, which can barely be heard:

    # Animal package from before
    { package Mouse;
      @ISA = qw(Animal);
      sub sound { "squeak" }
      sub speak {
        my $class = shift;
        print "a $class goes ", $class->sound, "!\n";
        print "[but you can barely hear it!]\n";
      }
    }

    Mouse->speak;

which results in:

    a Mouse goes squeak!
    [but you can barely hear it!]

Here, Mouse has its own speaking routine, so Mouse->speak doesn't immediately invoke Animal->speak. This is known as "overriding". In fact, we didn't even need to say that a Mouse was an Animal at all, since all of the methods needed for speak are completely defined with Mouse.

But we've now duplicated some of the code from Animal->speak, and this can once again be a maintenance headache. So, can we avoid that? Can we say somehow that a Mouse does everything any other Animal does, but add in the extra comment? Sure!

First, we can invoke the Animal::speak method directly:

    # Animal package from before
    { package Mouse;
      @ISA = qw(Animal);
      sub sound { "squeak" }
      sub speak {
        my $class = shift;
        Animal::speak($class);
        print "[but you can barely hear it!]\n";
      }
    }

Note that we have to include the $class parameter (almost surely the value of "Mouse") as the first parameter to Animal::speak, since we've stopped using the method arrow. Why did we stop? Well, if we invoke Animal->speak there, the first parameter to the method will be "Animal" not "Mouse", and when time comes for it to call for the sound, it won't have the right class to come back to this package.

Invoking Animal::speak directly is a mess, however. What if Animal::speak didn't exist before, and was being inherited from a class mentioned in @Animal::ISA? Because we are no longer using the method arrow, we get one and only one chance to hit the right subroutine.

Also note that the Animal classname is now hardwired into the subroutine selection. This is a mess if someone maintains the code, changing @ISA for <Mouse> and didn't notice Animal there in speak. So, this is probably not the right way to go.

Starting the search from a different place

A better solution is to tell Perl to search from a higher place in the inheritance chain:

    # same Animal as before
    { package Mouse;
      # same @ISA, &sound as before
      sub speak {
        my $class = shift;
        $class->Animal::speak;
        print "[but you can barely hear it!]\n";
      }
    }

Ahh. This works. Using this syntax, we start with Animal to find speak, and use all of Animal's inheritance chain if not found immediately. And yet the first parameter will be $class, so the found speak method will get Mouse as its first entry, and eventually work its way back to Mouse::sound for the details.

But this isn't the best solution. We still have to keep the @ISA and the initial search package coordinated. Worse, if Mouse had multiple entries in @ISA, we wouldn't necessarily know which one had actually defined speak. So, is there an even better way?

The SUPER way of doing things

By changing the Animal class to the SUPER class in that invocation, we get a search of all of our super classes (classes listed in @ISA) automatically:

    # same Animal as before
    { package Mouse;
      # same @ISA, &sound as before
      sub speak {
        my $class = shift;
        $class->SUPER::speak;
        print "[but you can barely hear it!]\n";
      }
    }

So, SUPER::speak means look in the current package's @ISA for speak, invoking the first one found. Note that it does not look in the @ISA of $class.

Where we're at so far...

So far, we've seen the method arrow syntax:

  Class->method(@args);

or the equivalent:

  $a = "Class";
  $a->method(@args);

which constructs an argument list of:

  ("Class", @args)

and attempts to invoke

  Class::method("Class", @Args);

However, if Class::method is not found, then @Class::ISA is examined (recursively) to locate a package that does indeed contain method, and that subroutine is invoked instead.

Using this simple syntax, we have class methods, (multiple) inheritance, overriding, and extending. Using just what we've seen so far, we've been able to factor out common code, and provide a nice way to reuse implementations with variations. This is at the core of what objects provide, but objects also provide instance data, which we haven't even begun to cover.

A horse is a horse, of course of course -- or is it?

Let's start with the code for the Animal class and the Horse class:

  { package Animal;
    sub speak {
      my $class = shift;
      print "a $class goes ", $class->sound, "!\n"
    }
  }
  { package Horse;
    @ISA = qw(Animal);
    sub sound { "neigh" }
  }

This lets us invoke Horse->speak to ripple upward to Animal::speak, calling back to Horse::sound to get the specific sound, and the output of:

  a Horse goes neigh!

But all of our Horse objects would have to be absolutely identical. If I add a subroutine, all horses automatically share it. That's great for making horses the same, but how do we capture the distinctions about an individual horse? For example, suppose I want to give my first horse a name. There's got to be a way to keep its name separate from the other horses.

We can do that by drawing a new distinction, called an "instance". An "instance" is generally created by a class. In Perl, any reference can be an instance, so let's start with the simplest reference that can hold a horse's name: a scalar reference.

  my $name = "Mr. Ed";
  my $talking = \$name;

So now $talking is a reference to what will be the instance-specific data (the name). The final step in turning this into a real instance is with a special operator called bless:

  bless $talking, Horse;

This operator stores information about the package named Horse into the thing pointed at by the reference. At this point, we say $talking is an instance of Horse. That is, it's a specific horse. The reference is otherwise unchanged, and can still be used with traditional dereferencing operators.

Invoking an instance method

The method arrow can be used on instances, as well as names of packages (classes). So, let's get the sound that $talking makes:

  my $noise = $talking->sound;

To invoke sound, Perl first notes that $talking is a blessed reference (and thus an instance). It then constructs an argument list, in this case from just ($talking). (Later we'll see that arguments will take their place following the instance variable, just like with classes.)

Now for the fun part: Perl takes the class in which the instance was blessed, in this case Horse, and uses that to locate the subroutine to invoke the method. In this case, Horse::sound is found directly (without using inheritance), yielding the final subroutine invocation:

  Horse::sound($talking)

Note that the first parameter here is still the instance, not the name of the class as before. We'll get neigh as the return value, and that'll end up as the $noise variable above.

If Horse::sound had not been found, we'd be wandering up the @Horse::ISA list to try to find the method in one of the superclasses, just as for a class method. The only difference between a class method and an instance method is whether the first parameter is an instance (a blessed reference) or a class name (a string).

Accessing the instance data

Because we get the instance as the first parameter, we can now access the instance-specific data. In this case, let's add a way to get at the name:

  { package Horse;
    @ISA = qw(Animal);
    sub sound { "neigh" }
    sub name {
      my $self = shift;
      $$self;
    }
  }

Now we call for the name:

  print $talking->name, " says ", $talking->sound, "\n";

Inside Horse::name, the @_ array contains just $talking, which the shift stores into $self. (It's traditional to shift the first parameter off into a variable named $self for instance methods, so stay with that unless you have strong reasons otherwise.) Then, $self gets de-referenced as a scalar ref, yielding Mr. Ed, and we're done with that. The result is:

  Mr. Ed says neigh.

How to build a horse

Of course, if we constructed all of our horses by hand, we'd most likely make mistakes from time to time. We're also violating one of the properties of object-oriented programming, in that the "inside guts" of a Horse are visible. That's good if you're a veterinarian, but not if you just like to own horses. So, let's let the Horse class build a new horse:

  { package Horse;
    @ISA = qw(Animal);
    sub sound { "neigh" }
    sub name {
      my $self = shift;
      $$self;
    }
    sub named {
      my $class = shift;
      my $name = shift;
      bless \$name, $class;
    }
  }

Now with the new named method, we can build a horse:

  my $talking = Horse->named("Mr. Ed");

Notice we're back to a class method, so the two arguments to Horse::named are Horse and Mr. Ed. The bless operator not only blesses $name, it also returns the reference to $name, so that's fine as a return value. And that's how to build a horse.

We've called the constructor named here, so that it quickly denotes the constructor's argument as the name for this particular Horse. You can use different constructors with different names for different ways of "giving birth" to the object (like maybe recording its pedigree or date of birth). However, you'll find that most people coming to Perl from more limited languages use a single constructor named new, with various ways of interpreting the arguments to new. Either style is fine, as long as you document your particular way of giving birth to an object. (And you were going to do that, right?)

Inheriting the constructor

But was there anything specific to Horse in that method? No. Therefore, it's also the same recipe for building anything else that inherited from Animal, so let's put it there:

  { package Animal;
    sub speak {
      my $class = shift;
      print "a $class goes ", $class->sound, "!\n"
    }
    sub name {
      my $self = shift;
      $$self;
    }
    sub named {
      my $class = shift;
      my $name = shift;
      bless \$name, $class;
    }
  }
  { package Horse;
    @ISA = qw(Animal);
    sub sound { "neigh" }
  }

Ahh, but what happens if we invoke speak on an instance?

  my $talking = Horse->named("Mr. Ed");
  $talking->speak;

We get a debugging value:

  a Horse=SCALAR(0xaca42ac) goes neigh!

Why? Because the Animal::speak routine is expecting a classname as its first parameter, not an instance. When the instance is passed in, we'll end up using a blessed scalar reference as a string, and that shows up as we saw it just now.

Making a method work with either classes or instances

All we need is for a method to detect if it is being called on a class or called on an instance. The most straightforward way is with the ref operator. This returns a string (the classname) when used on a blessed reference, and undef when used on a string (like a classname). Let's modify the name method first to notice the change:

  sub name {
    my $either = shift;
    ref $either
      ? $$either # it's an instance, return name
      : "an unnamed $either"; # it's a class, return generic
  }

Here, the ?: operator comes in handy to select either the dereference or a derived string. Now we can use this with either an instance or a class. Note that I've changed the first parameter holder to $either to show that this is intended:

  my $talking = Horse->named("Mr. Ed");
  print Horse->name, "\n"; # prints "an unnamed Horse\n"
  print $talking->name, "\n"; # prints "Mr Ed.\n"

and now we'll fix speak to use this:

  sub speak {
    my $either = shift;
    print $either->name, " goes ", $either->sound, "\n";
  }

And since sound already worked with either a class or an instance, we're done!

Adding parameters to a method

Let's train our animals to eat:

  { package Animal;
    sub named {
      my $class = shift;
      my $name = shift;
      bless \$name, $class;
    }
    sub name {
      my $either = shift;
      ref $either
        ? $$either # it's an instance, return name
        : "an unnamed $either"; # it's a class, return generic
    }
    sub speak {
      my $either = shift;
      print $either->name, " goes ", $either->sound, "\n";
    }
    sub eat {
      my $either = shift;
      my $food = shift;
      print $either->name, " eats $food.\n";
    }
  }
  { package Horse;
    @ISA = qw(Animal);
    sub sound { "neigh" }
  }
  { package Sheep;
    @ISA = qw(Animal);
    sub sound { "baaaah" }
  }

And now try it out:

  my $talking = Horse->named("Mr. Ed");
  $talking->eat("hay");
  Sheep->eat("grass");

which prints:

  Mr. Ed eats hay.
  an unnamed Sheep eats grass.

An instance method with parameters gets invoked with the instance, and then the list of parameters. So that first invocation is like:

  Animal::eat($talking, "hay");

More interesting instances

What if an instance needs more data? Most interesting instances are made of many items, each of which can in turn be a reference or even another object. The easiest way to store these is often in a hash. The keys of the hash serve as the names of parts of the object (often called "instance variables" or "member variables"), and the corresponding values are, well, the values.

But how do we turn the horse into a hash? Recall that an object was any blessed reference. We can just as easily make it a blessed hash reference as a blessed scalar reference, as long as everything that looks at the reference is changed accordingly.

Let's make a sheep that has a name and a color:

  my $bad = bless { Name => "Evil", Color => "black" }, Sheep;

so $bad->{Name} has Evil, and $bad->{Color} has black. But we want to make $bad->name access the name, and that's now messed up because it's expecting a scalar reference. Not to worry, because that's pretty easy to fix up:

  ## in Animal
  sub name {
    my $either = shift;
    ref $either ?
      $either->{Name} :
      "an unnamed $either";
  }

And of course named still builds a scalar sheep, so let's fix that as well:

  ## in Animal
  sub named {
    my $class = shift;
    my $name = shift;
    my $self = { Name => $name, Color => $class->default_color };
    bless $self, $class;
  }

What's this default_color? Well, if named has only the name, we still need to set a color, so we'll have a class-specific initial color. For a sheep, we might define it as white:

  ## in Sheep
  sub default_color { "white" }

And then to keep from having to define one for each additional class, we'll define a "backstop" method that serves as the "default default", directly in Animal:

  ## in Animal
  sub default_color { "brown" }

Now, because name and named were the only methods that referenced the "structure" of the object, the rest of the methods can remain the same, so speak still works as before.

A horse of a different color

But having all our horses be brown would be boring. So let's add a method or two to get and set the color.

  ## in Animal
  sub color {
    $_[0]->{Color}
  }
  sub set_color {
    $_[0]->{Color} = $_[1];
  }

Note the alternate way of accessing the arguments: $_[0] is used in-place, rather than with a shift. (This saves us a bit of time for something that may be invoked frequently.) And now we can fix that color for Mr. Ed:

  my $talking = Horse->named("Mr. Ed");
  $talking->set_color("black-and-white");
  print $talking->name, " is colored ", $talking->color, "\n";

which results in:

  Mr. Ed is colored black-and-white

Summary

So, now we have class methods, constructors, instance methods, instance data, and even accessors. But that's still just the beginning of what Perl has to offer. We haven't even begun to talk about accessors that double as getters and setters, destructors, indirect object notation, subclasses that add instance data, per-class data, overloading, "isa" and "can" tests, UNIVERSAL class, and so on. That's for the rest of the Perl documentation to cover. Hopefully, this gets you started, though.

SEE ALSO

For more information, see the perlobj manpage (for all the gritty details about Perl objects, now that you've seen the basics), the perltoot manpage (the tutorial for those who already know objects), the perltooc manpage (dealing with class data), the perlbot manpage (for some more tricks), and books such as Damian Conway's excellent Object Oriented Perl.

Some modules which might prove interesting are Class::Accessor, Class::Class, Class::Contract, Class::Data::Inheritable, Class::MethodMaker and Tie::SecureHash

COPYRIGHT

Copyright (c) 1999, 2000 by Randal L. Schwartz and Stonehenge Consulting Services, Inc. Permission is hereby granted to distribute this document intact with the Perl distribution, and in accordance with the licenses of the Perl distribution; derived documents must include this copyright notice intact.

Portions of this text have been derived from Perl Training materials originally appearing in the Packages, References, Objects, and Modules course taught by instructors for Stonehenge Consulting Services, Inc. and used with permission.

Portions of this text have been derived from materials originally appearing in Linux Magazine and used with permission.


perlbot - Bag'o Object Tricks

  • OO SCALING TIPS
  • INSTANCE VARIABLES
  • SCALAR INSTANCE VARIABLES
  • INSTANCE VARIABLE INHERITANCE
  • OBJECT RELATIONSHIPS
  • OVERRIDING SUPERCLASS METHODS
  • USING RELATIONSHIP WITH SDBM
  • THINKING OF CODE REUSE
  • CLASS CONTEXT AND THE OBJECT
  • INHERITING A CONSTRUCTOR
  • DELEGATION
  • SEE ALSO

NAME

perlbot - Bag'o Object Tricks (the BOT)

DESCRIPTION

The following collection of tricks and hints is intended to whet curious appetites about such things as the use of instance variables and the mechanics of object and class relationships. The reader is encouraged to consult relevant textbooks for discussion of Object Oriented definitions and methodology. This is not intended as a tutorial for object-oriented programming or as a comprehensive guide to Perl's object oriented features, nor should it be construed as a style guide. If you're looking for tutorials, be sure to read the perlboot manpage, the perltoot manpage, and the perltooc manpage.

The Perl motto still holds: There's more than one way to do it.

OO SCALING TIPS

  1. Do not attempt to verify the type of $self. That'll break if the class is inherited, when the type of $self is valid but its package isn't what you expect. See rule 5.

  2. If an object-oriented (OO) or indirect-object (IO) syntax was used, then the object is probably the correct type and there's no need to become paranoid about it. Perl isn't a paranoid language anyway. If people subvert the OO or IO syntax then they probably know what they're doing and you should let them do it. See rule 1.

  3. Use the two-argument form of bless(). Let a subclass use your constructor. See INHERITING A CONSTRUCTOR.

  4. The subclass is allowed to know things about its immediate superclass, the superclass is allowed to know nothing about a subclass.

  5. Don't be trigger happy with inheritance. A "using", "containing", or "delegation" relationship (some sort of aggregation, at least) is often more appropriate. See OBJECT RELATIONSHIPS, USING RELATIONSHIP WITH SDBM, and DELEGATION.

  6. The object is the namespace. Make package globals accessible via the object. This will remove the guess work about the symbol's home package. See CLASS CONTEXT AND THE OBJECT.

  7. IO syntax is certainly less noisy, but it is also prone to ambiguities that can cause difficult-to-find bugs. Allow people to use the sure-thing OO syntax, even if you don't like it.

  8. Do not use function-call syntax on a method. You're going to be bitten someday. Someone might move that method into a superclass and your code will be broken. On top of that you're feeding the paranoia in rule 2.

  9. Don't assume you know the home package of a method. You're making it difficult for someone to override that method. See THINKING OF CODE REUSE.

INSTANCE VARIABLES

An anonymous array or anonymous hash can be used to hold instance variables. Named parameters are also demonstrated.

        package Foo;

        sub new {
                my $type = shift;
                my %params = @_;
                my $self = {};
                $self->{'High'} = $params{'High'};
                $self->{'Low'}  = $params{'Low'};
                bless $self, $type;
        }

        package Bar;

        sub new {
                my $type = shift;
                my %params = @_;
                my $self = [];
                $self->[0] = $params{'Left'};
                $self->[1] = $params{'Right'};
                bless $self, $type;
        }

        package main;

        $a = Foo->new( 'High' => 42, 'Low' => 11 );
        print "High=$a->{'High'}\n";
        print "Low=$a->{'Low'}\n";

        $b = Bar->new( 'Left' => 78, 'Right' => 40 );
        print "Left=$b->[0]\n";
        print "Right=$b->[1]\n";

SCALAR INSTANCE VARIABLES

An anonymous scalar can be used when only one instance variable is needed.

        package Foo;

        sub new {
                my $type = shift;
                my $self;
                $self = shift;
                bless \$self, $type;
        }

        package main;

        $a = Foo->new( 42 );
        print "a=$$a\n";

INSTANCE VARIABLE INHERITANCE

This example demonstrates how one might inherit instance variables from a superclass for inclusion in the new class. This requires calling the superclass's constructor and adding one's own instance variables to the new object.

        package Bar;

        sub new {
                my $type = shift;
                my $self = {};
                $self->{'buz'} = 42;
                bless $self, $type;
        }

        package Foo;
        @ISA = qw( Bar );

        sub new {
                my $type = shift;
                my $self = Bar->new;
                $self->{'biz'} = 11;
                bless $self, $type;
        }

        package main;

        $a = Foo->new;
        print "buz = ", $a->{'buz'}, "\n";
        print "biz = ", $a->{'biz'}, "\n";

OBJECT RELATIONSHIPS

The following demonstrates how one might implement "containing" and "using" relationships between objects.

        package Bar;

        sub new {
                my $type = shift;
                my $self = {};
                $self->{'buz'} = 42;
                bless $self, $type;
        }

        package Foo;

        sub new {
                my $type = shift;
                my $self = {};
                $self->{'Bar'} = Bar->new;
                $self->{'biz'} = 11;
                bless $self, $type;
        }

        package main;

        $a = Foo->new;
        print "buz = ", $a->{'Bar'}->{'buz'}, "\n";
        print "biz = ", $a->{'biz'}, "\n";

OVERRIDING SUPERCLASS METHODS

The following example demonstrates how to override a superclass method and then call the overridden method. The SUPER pseudo-class allows the programmer to call an overridden superclass method without actually knowing where that method is defined.

        package Buz;
        sub goo { print "here's the goo\n" }

        package Bar; @ISA = qw( Buz );
        sub google { print "google here\n" }

        package Baz;
        sub mumble { print "mumbling\n" }

        package Foo;
        @ISA = qw( Bar Baz );

        sub new {
                my $type = shift;
                bless [], $type;
        }
        sub grr { print "grumble\n" }
        sub goo {
                my $self = shift;
                $self->SUPER::goo();
        }
        sub mumble {
                my $self = shift;
                $self->SUPER::mumble();
        }
        sub google {
                my $self = shift;
                $self->SUPER::google();
        }

        package main;

        $foo = Foo->new;
        $foo->mumble;
        $foo->grr;
        $foo->goo;
        $foo->google;

Note that SUPER refers to the superclasses of the current package (Foo), not to the superclasses of $self.

USING RELATIONSHIP WITH SDBM

This example demonstrates an interface for the SDBM class. This creates a "using" relationship between the SDBM class and the new class Mydbm.

        package Mydbm;

        require SDBM_File;
        require Tie::Hash;
        @ISA = qw( Tie::Hash );

        sub TIEHASH {
            my $type = shift;
            my $ref  = SDBM_File->new(@_);
            bless {'dbm' => $ref}, $type;
        }
        sub FETCH {
            my $self = shift;
            my $ref  = $self->{'dbm'};
            $ref->FETCH(@_);
        }
        sub STORE {
            my $self = shift;
            if (defined $_[0]){
                my $ref = $self->{'dbm'};
                $ref->STORE(@_);
            } else {
                die "Cannot STORE an undefined key in Mydbm\n";
            }
        }

        package main;
        use Fcntl qw( O_RDWR O_CREAT );

        tie %foo, "Mydbm", "Sdbm", O_RDWR|O_CREAT, 0640;
        $foo{'bar'} = 123;
        print "foo-bar = $foo{'bar'}\n";

        tie %bar, "Mydbm", "Sdbm2", O_RDWR|O_CREAT, 0640;
        $bar{'Cathy'} = 456;
        print "bar-Cathy = $bar{'Cathy'}\n";

THINKING OF CODE REUSE

One strength of Object-Oriented languages is the ease with which old code can use new code. The following examples will demonstrate first how one can hinder code reuse and then how one can promote code reuse.

This first example illustrates a class which uses a fully-qualified method call to access the "private" method BAZ(). The second example will show that it is impossible to override the BAZ() method.

        package FOO;

        sub new {
                my $type = shift;
                bless {}, $type;
        }
        sub bar {
                my $self = shift;
                $self->FOO::private::BAZ;
        }

        package FOO::private;

        sub BAZ {
                print "in BAZ\n";
        }

        package main;

        $a = FOO->new;
        $a->bar;

Now we try to override the BAZ() method. We would like FOO::bar() to call GOOP::BAZ(), but this cannot happen because FOO::bar() explicitly calls FOO::private::BAZ().

        package FOO;

        sub new {
                my $type = shift;
                bless {}, $type;
        }
        sub bar {
                my $self = shift;
                $self->FOO::private::BAZ;
        }

        package FOO::private;

        sub BAZ {
                print "in BAZ\n";
        }

        package GOOP;
        @ISA = qw( FOO );
        sub new {
                my $type = shift;
                bless {}, $type;
        }

        sub BAZ {
                print "in GOOP::BAZ\n";
        }

        package main;

        $a = GOOP->new;
        $a->bar;

To create reusable code we must modify class FOO, flattening class FOO::private. The next example shows a reusable class FOO which allows the method GOOP::BAZ() to be used in place of FOO::BAZ().

        package FOO;

        sub new {
                my $type = shift;
                bless {}, $type;
        }
        sub bar {
                my $self = shift;
                $self->BAZ;
        }

        sub BAZ {
                print "in BAZ\n";
        }

        package GOOP;
        @ISA = qw( FOO );

        sub new {
                my $type = shift;
                bless {}, $type;
        }
        sub BAZ {
                print "in GOOP::BAZ\n";
        }

        package main;

        $a = GOOP->new;
        $a->bar;

CLASS CONTEXT AND THE OBJECT

Use the object to solve package and class context problems. Everything a method needs should be available via the object or should be passed as a parameter to the method.

A class will sometimes have static or global data to be used by the methods. A subclass may want to override that data and replace it with new data. When this happens the superclass may not know how to find the new copy of the data.

This problem can be solved by using the object to define the context of the method. Let the method look in the object for a reference to the data. The alternative is to force the method to go hunting for the data ("Is it in my class, or in a subclass? Which subclass?"), and this can be inconvenient and will lead to hackery. It is better just to let the object tell the method where that data is located.

        package Bar;

        %fizzle = ( 'Password' => 'XYZZY' );

        sub new {
                my $type = shift;
                my $self = {};
                $self->{'fizzle'} = \%fizzle;
                bless $self, $type;
        }

        sub enter {
                my $self = shift;

                # Don't try to guess if we should use %Bar::fizzle
                # or %Foo::fizzle.  The object already knows which
                # we should use, so just ask it.
                #
                my $fizzle = $self->{'fizzle'};

                print "The word is ", $fizzle->{'Password'}, "\n";
                        }

        package Foo;
        @ISA = qw( Bar );

        %fizzle = ( 'Password' => 'Rumple' );

        sub new {
                my $type = shift;
                my $self = Bar->new;
                $self->{'fizzle'} = \%fizzle;
                bless $self, $type;
        }

        package main;

        $a = Bar->new;
        $b = Foo->new;
        $a->enter;
        $b->enter;

INHERITING A CONSTRUCTOR

An inheritable constructor should use the second form of bless() which allows blessing directly into a specified class. Notice in this example that the object will be a BAR not a FOO, even though the constructor is in class FOO.

        package FOO;

        sub new {
                my $type = shift;
                my $self = {};
                bless $self, $type;
        }

        sub baz {
                print "in FOO::baz()\n";
        }

        package BAR;
        @ISA = qw(FOO);

        sub baz {
                print "in BAR::baz()\n";
        }

        package main;

        $a = BAR->new;
        $a->baz;

DELEGATION

Some classes, such as SDBM_File, cannot be effectively subclassed because they create foreign objects. Such a class can be extended with some sort of aggregation technique such as the "using" relationship mentioned earlier or by delegation.

The following example demonstrates delegation using an AUTOLOAD() function to perform message-forwarding. This will allow the Mydbm object to behave exactly like an SDBM_File object. The Mydbm class could now extend the behavior by adding custom FETCH() and STORE() methods, if this is desired.

        package Mydbm;

        require SDBM_File;
        require Tie::Hash;
        @ISA = qw(Tie::Hash);

        sub TIEHASH {
                my $type = shift;
                my $ref = SDBM_File->new(@_);
                bless {'delegate' => $ref};
        }

        sub AUTOLOAD {
                my $self = shift;

                # The Perl interpreter places the name of the
                # message in a variable called $AUTOLOAD.

                # DESTROY messages should never be propagated.
                return if $AUTOLOAD =~ /::DESTROY$/;

                # Remove the package name.
                $AUTOLOAD =~ s/^Mydbm:://;

                # Pass the message to the delegate.
                $self->{'delegate'}->$AUTOLOAD(@_);
                        }

        package main;
        use Fcntl qw( O_RDWR O_CREAT );

        tie %foo, "Mydbm", "adbm", O_RDWR|O_CREAT, 0640;
        $foo{'bar'} = 123;
        print "foo-bar = $foo{'bar'}\n";

SEE ALSO

the perlboot manpage, the perltoot manpage, the perltooc manpage.


perlobj - Perl objects

    • An Object is Simply a Reference
    • A Class is Simply a Package
    • A Method is Simply a Subroutine
    • Method Invocation
    • Indirect Object Syntax
    • Default UNIVERSAL methods
    • Destructors
    • Summary
    • Two-Phased Garbage Collection
  • SEE ALSO

NAME

perlobj - Perl objects

DESCRIPTION

First you need to understand what references are in Perl. See the perlref manpage for that. Second, if you still find the following reference work too complicated, a tutorial on object-oriented programming in Perl can be found in the perltoot manpage and the perltooc manpage.

If you're still with us, then here are three very simple definitions that you should find reassuring.

  1. An object is simply a reference that happens to know which class it belongs to.

  2. A class is simply a package that happens to provide methods to deal with object references.

  3. A method is simply a subroutine that expects an object reference (or a package name, for class methods) as the first argument.

We'll cover these points now in more depth.

An Object is Simply a Reference

Unlike say C++, Perl doesn't provide any special syntax for constructors. A constructor is merely a subroutine that returns a reference to something "blessed" into a class, generally the class that the subroutine is defined in. Here is a typical constructor:

    package Critter;
    sub new { bless {} }

That word new isn't special. You could have written a construct this way, too:

    package Critter;
    sub spawn { bless {} }

This might even be preferable, because the C++ programmers won't be tricked into thinking that new works in Perl as it does in C++. It doesn't. We recommend that you name your constructors whatever makes sense in the context of the problem you're solving. For example, constructors in the Tk extension to Perl are named after the widgets they create.

One thing that's different about Perl constructors compared with those in C++ is that in Perl, they have to allocate their own memory. (The other things is that they don't automatically call overridden base-class constructors.) The {} allocates an anonymous hash containing no key/value pairs, and returns it The bless() takes that reference and tells the object it references that it's now a Critter, and returns the reference. This is for convenience, because the referenced object itself knows that it has been blessed, and the reference to it could have been returned directly, like this:

    sub new {
        my $self = {};
        bless $self;
        return $self;
    }

You often see such a thing in more complicated constructors that wish to call methods in the class as part of the construction:

    sub new {
        my $self = {};
        bless $self;
        $self->initialize();
        return $self;
    }

If you care about inheritance (and you should; see Modules: Creation, Use, and Abuse in the perlmodlib manpage), then you want to use the two-arg form of bless so that your constructors may be inherited:

    sub new {
        my $class = shift;
        my $self = {};
        bless $self, $class;
        $self->initialize();
        return $self;
    }

Or if you expect people to call not just CLASS->new() but also $obj->new(), then use something like the following. (Note that using this to call new() on an instance does not automatically perform any copying. If you want a shallow or deep copy of an object, you'll have to specifically allow for that.) The initialize() method used will be of whatever $class we blessed the object into:

    sub new {
        my $this = shift;
        my $class = ref($this) || $this;
        my $self = {};
        bless $self, $class;
        $self->initialize();
        return $self;
    }

Within the class package, the methods will typically deal with the reference as an ordinary reference. Outside the class package, the reference is generally treated as an opaque value that may be accessed only through the class's methods.

Although a constructor can in theory re-bless a referenced object currently belonging to another class, this is almost certainly going to get you into trouble. The new class is responsible for all cleanup later. The previous blessing is forgotten, as an object may belong to only one class at a time. (Although of course it's free to inherit methods from many classes.) If you find yourself having to do this, the parent class is probably misbehaving, though.

A clarification: Perl objects are blessed. References are not. Objects know which package they belong to. References do not. The bless() function uses the reference to find the object. Consider the following example:

    $a = {};
    $b = $a;
    bless $a, BLAH;
    print "\$b is a ", ref($b), "\n";

This reports $b as being a BLAH, so obviously bless() operated on the object and not on the reference.

A Class is Simply a Package

Unlike say C++, Perl doesn't provide any special syntax for class definitions. You use a package as a class by putting method definitions into the class.

There is a special array within each package called @ISA, which says where else to look for a method if you can't find it in the current package. This is how Perl implements inheritance. Each element of the @ISA array is just the name of another package that happens to be a class package. The classes are searched (depth first) for missing methods in the order that they occur in @ISA. The classes accessible through @ISA are known as base classes of the current class.

All classes implicitly inherit from class UNIVERSAL as their last base class. Several commonly used methods are automatically supplied in the UNIVERSAL class; see Default UNIVERSAL methods for more details.

If a missing method is found in a base class, it is cached in the current class for efficiency. Changing @ISA or defining new subroutines invalidates the cache and causes Perl to do the lookup again.

If neither the current class, its named base classes, nor the UNIVERSAL class contains the requested method, these three places are searched all over again, this time looking for a method named AUTOLOAD(). If an AUTOLOAD is found, this method is called on behalf of the missing method, setting the package global $AUTOLOAD to be the fully qualified name of the method that was intended to be called.

If none of that works, Perl finally gives up and complains.

If you want to stop the AUTOLOAD inheritance say simply

        sub AUTOLOAD;

and the call will die using the name of the sub being called.

Perl classes do method inheritance only. Data inheritance is left up to the class itself. By and large, this is not a problem in Perl, because most classes model the attributes of their object using an anonymous hash, which serves as its own little namespace to be carved up by the various classes that might want to do something with the object. The only problem with this is that you can't sure that you aren't using a piece of the hash that isn't already used. A reasonable workaround is to prepend your fieldname in the hash with the package name.

    sub bump {
        my $self = shift;
        $self->{ __PACKAGE__ . ".count"}++;
    }

A Method is Simply a Subroutine

Unlike say C++, Perl doesn't provide any special syntax for method definition. (It does provide a little syntax for method invocation though. More on that later.) A method expects its first argument to be the object (reference) or package (string) it is being invoked on. There are two ways of calling methods, which we'll call class methods and instance methods.

A class method expects a class name as the first argument. It provides functionality for the class as a whole, not for any individual object belonging to the class. Constructors are often class methods, but see the perltoot manpage and the perltooc manpage for alternatives. Many class methods simply ignore their first argument, because they already know what package they're in and don't care what package they were invoked via. (These aren't necessarily the same, because class methods follow the inheritance tree just like ordinary instance methods.) Another typical use for class methods is to look up an object by name:

    sub find {
        my ($class, $name) = @_;
        $objtable{$name};
    }

An instance method expects an object reference as its first argument. Typically it shifts the first argument into a "self" or "this" variable, and then uses that as an ordinary reference.

    sub display {
        my $self = shift;
        my @keys = @_ ? @_ : sort keys %$self;
        foreach $key (@keys) {
            print "\t$key => $self->{$key}\n";
        }
    }

Method Invocation >>

For various historical and other reasons, Perl offers two equivalent ways to write a method call. The simpler and more common way is to use the arrow notation:

    my $fred = Critter->find("Fred");
    $fred->display("Height", "Weight");

You should already be familiar with the use of the -> operator with references. In fact, since $fred above is a reference to an object, you could think of the method call as just another form of dereferencing.

Whatever is on the left side of the arrow, whether a reference or a class name, is passed to the method subroutine as its first argument. So the above code is mostly equivalent to:

    my $fred = Critter::find("Critter", "Fred");
    Critter::display($fred, "Height", "Weight");

How does Perl know which package the subroutine is in? By looking at the left side of the arrow, which must be either a package name or a reference to an object, i.e. something that has been blessed to a package. Either way, that's the package where Perl starts looking. If that package has no subroutine with that name, Perl starts looking for it in any base classes of that package, and so on.

If you need to, you can force Perl to start looking in some other package:

    my $barney = MyCritter->Critter::find("Barney");
    $barney->Critter::display("Height", "Weight");

Here MyCritter is presumably a subclass of Critter that defines its own versions of find() and display(). We haven't specified what those methods do, but that doesn't matter above since we've forced Perl to start looking for the subroutines in Critter.

As a special case of the above, you may use the SUPER pseudo-class to tell Perl to start looking for the method in the packages named in the current class's @ISA list.

    package MyCritter;
    use base 'Critter';    # sets @MyCritter::ISA = ('Critter');

    sub display {
        my ($self, @args) = @_;
        $self->SUPER::display("Name", @args);
    }

It is important to note that SUPER refers to the superclass(es) of the current package and not to the superclass(es) of the object. Also, the SUPER pseudo-class can only currently be used as a modifier to a method name, but not in any of the other ways that class names are normally used, eg:

    something->SUPER::method(...);      # OK
    SUPER::method(...);                 # WRONG
    SUPER->method(...);                 # WRONG

Instead of a class name or an object reference, you can also use any expression that returns either of those on the left side of the arrow. So the following statement is valid:

    Critter->find("Fred")->display("Height", "Weight");

and so is the following:

    my $fred = (reverse "rettirC")->find(reverse "derF");

The right side of the arrow typically is the method name, but a simple scalar variable containing either the method name or a subroutine reference can also be used.

Indirect Object Syntax

The other way to invoke a method is by using the so-called "indirect object" notation. This syntax was available in Perl 4 long before objects were introduced, and is still used with filehandles like this:

   print STDERR "help!!!\n";

The same syntax can be used to call either object or class methods.

   my $fred = find Critter "Fred";
   display $fred "Height", "Weight";

Notice that there is no comma between the object or class name and the parameters. This is how Perl can tell you want an indirect method call instead of an ordinary subroutine call.

But what if there are no arguments? In that case, Perl must guess what you want. Even worse, it must make that guess at compile time. Usually Perl gets it right, but when it doesn't you get a function call compiled as a method, or vice versa. This can introduce subtle bugs that are hard to detect.

For example, a call to a method new in indirect notation -- as C++ programmers are wont to make -- can be miscompiled into a subroutine call if there's already a new function in scope. You'd end up calling the current package's new as a subroutine, rather than the desired class's method. The compiler tries to cheat by remembering bareword requires, but the grief when it messes up just isn't worth the years of debugging it will take you to track down such subtle bugs.

There is another problem with this syntax: the indirect object is limited to a name, a scalar variable, or a block, because it would have to do too much lookahead otherwise, just like any other postfix dereference in the language. (These are the same quirky rules as are used for the filehandle slot in functions like print and printf.) This can lead to horribly confusing precedence problems, as in these next two lines:

    move $obj->{FIELD};                 # probably wrong!
    move $ary[$i];                      # probably wrong!

Those actually parse as the very surprising:

    $obj->move->{FIELD};                # Well, lookee here
    $ary->move([$i]);                   # Didn't expect this one, eh?

Rather than what you might have expected:

    $obj->{FIELD}->move();              # You should be so lucky.
    $ary[$i]->move;                     # Yeah, sure.

To get the correct behavior with indirect object syntax, you would have to use a block around the indirect object:

    move {$obj->{FIELD}};
    move {$ary[$i]};

Even then, you still have the same potential problem if there happens to be a function named move in the current package. The -> notation suffers from neither of these disturbing ambiguities, so we recommend you use it exclusively. However, you may still end up having to read code using the indirect object notation, so it's important to be familiar with it.

Default UNIVERSAL methods

The UNIVERSAL package automatically contains the following methods that are inherited by all other classes:

isa(CLASS)

isa returns true if its object is blessed into a subclass of CLASS

You can also call UNIVERSAL::isa as a subroutine with two arguments. Of course, this will do the wrong thing if someone has overridden isa in a class, so don't do it.

If you need to determine whether you've received a valid invocant, use the blessed function from the Scalar::Util manpage:

    if (blessed($ref) && $ref->isa( 'Some::Class')) {
        # ...
    }

blessed returns the name of the package the argument has been blessed into, or undef.

can(METHOD)

can checks to see if its object has a method called METHOD, if it does then a reference to the sub is returned, if it does not then undef is returned.

UNIVERSAL::can can also be called as a subroutine with two arguments. It'll always return undef if its first argument isn't an object or a class name. The same caveats for calling UNIVERSAL::isa directly apply here, too.

VERSION( [NEED] )

VERSION returns the version number of the class (package). If the NEED argument is given then it will check that the current version (as defined by the $VERSION variable in the given package) not less than NEED; it will die if this is not the case. This method is normally called as a class method. This method is called automatically by the VERSION form of use.

    use A 1.2 qw(some imported subs);
    # implies:
    A->VERSION(1.2);

NOTE: can directly uses Perl's internal code for method lookup, and isa uses a very similar method and cache-ing strategy. This may cause strange effects if the Perl code dynamically changes @ISA in any package.

You may add other methods to the UNIVERSAL class via Perl or XS code. You do not need to use UNIVERSAL to make these methods available to your program (and you should not do so).

Destructors

When the last reference to an object goes away, the object is automatically destroyed. (This may even be after you exit, if you've stored references in global variables.) If you want to capture control just before the object is freed, you may define a DESTROY method in your class. It will automatically be called at the appropriate moment, and you can do any extra cleanup you need to do. Perl passes a reference to the object under destruction as the first (and only) argument. Beware that the reference is a read-only value, and cannot be modified by manipulating $_[0] within the destructor. The object itself (i.e. the thingy the reference points to, namely ${$_[0]}, @{$_[0]}, %{$_[0]} etc.) is not similarly constrained.

Since DESTROY methods can be called at unpredictable times, it is important that you localise any global variables that the method may update. In particular, localise $@ if you use eval {} and localise $? if you use system or backticks.

If you arrange to re-bless the reference before the destructor returns, perl will again call the DESTROY method for the re-blessed object after the current one returns. This can be used for clean delegation of object destruction, or for ensuring that destructors in the base classes of your choosing get called. Explicitly calling DESTROY is also possible, but is usually never needed.

Do not confuse the previous discussion with how objects CONTAINED in the current one are destroyed. Such objects will be freed and destroyed automatically when the current object is freed, provided no other references to them exist elsewhere.

Summary

That's about all there is to it. Now you need just to go off and buy a book about object-oriented design methodology, and bang your forehead with it for the next six months or so.

Two-Phased Garbage Collection

For most purposes, Perl uses a fast and simple, reference-based garbage collection system. That means there's an extra dereference going on at some level, so if you haven't built your Perl executable using your C compiler's -O flag, performance will suffer. If you have built Perl with cc -O, then this probably won't matter.

A more serious concern is that unreachable memory with a non-zero reference count will not normally get freed. Therefore, this is a bad idea:

    {
        my $a;
        $a = \$a;
    }

Even thought $a should go away, it can't. When building recursive data structures, you'll have to break the self-reference yourself explicitly if you don't care to leak. For example, here's a self-referential node such as one might use in a sophisticated tree structure:

    sub new_node {
        my $class = shift;
        my $node  = {};
        $node->{LEFT} = $node->{RIGHT} = $node;
        $node->{DATA} = [ @_ ];
        return bless $node => $class;
    }

If you create nodes like that, they (currently) won't go away unless you break their self reference yourself. (In other words, this is not to be construed as a feature, and you shouldn't depend on it.)

Almost.

When an interpreter thread finally shuts down (usually when your program exits), then a rather costly but complete mark-and-sweep style of garbage collection is performed, and everything allocated by that thread gets destroyed. This is essential to support Perl as an embedded or a multithreadable language. For example, this program demonstrates Perl's two-phased garbage collection:

    #!/usr/bin/perl
    package Subtle;

    sub new {
        my $test;
        $test = \$test;
        warn "CREATING " . \$test;
        return bless \$test;
    }

    sub DESTROY {
        my $self = shift;
        warn "DESTROYING $self";
    }

    package main;

    warn "starting program";
    {
        my $a = Subtle->new;
        my $b = Subtle->new;
        $$a = 0;  # break selfref
        warn "leaving block";
    }

    warn "just exited block";
    warn "time to die...";
    exit;

When run as /foo/test, the following output is produced:

    starting program at /foo/test line 18.
    CREATING SCALAR(0x8e5b8) at /foo/test line 7.
    CREATING SCALAR(0x8e57c) at /foo/test line 7.
    leaving block at /foo/test line 23.
    DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
    just exited block at /foo/test line 26.
    time to die... at /foo/test line 27.
    DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.

Notice that "global destruction" bit there? That's the thread garbage collector reaching the unreachable.

Objects are always destructed, even when regular refs aren't. Objects are destructed in a separate pass before ordinary refs just to prevent object destructors from using refs that have been themselves destructed. Plain refs are only garbage-collected if the destruct level is greater than 0. You can test the higher levels of global destruction by setting the PERL_DESTRUCT_LEVEL environment variable, presuming -DDEBUGGING was enabled during perl build time. See PERL_DESTRUCT_LEVEL in the perlhack manpage for more information.

A more complete garbage collection strategy will be implemented at a future date.

In the meantime, the best solution is to create a non-recursive container class that holds a pointer to the self-referential data structure. Define a DESTROY method for the containing object's class that manually breaks the circularities in the self-referential structure.

SEE ALSO

A kinder, gentler tutorial on object-oriented programming in Perl can be found in the perltoot manpage, the perlboot manpage and the perltooc manpage. You should also check out the perlbot manpage for other object tricks, traps, and tips, as well as the perlmodlib manpage for some style guides on constructing both modules and classes.


perltooc - Tom's OO Tutorial for Class Data in Perl

  • Class Data in a Can
  • Class Data as Package Variables
    • Putting All Your Eggs in One Basket
    • Inheritance Concerns
    • The Eponymous Meta-Object
    • Indirect References to Class Data
    • Monadic Classes
    • Translucent Attributes
  • Class Data as Lexical Variables
    • Privacy and Responsibility
    • File-Scoped Lexicals
    • More Inheritance Concerns
    • Locking the Door and Throwing Away the Key
    • Translucency Revisited
  • NOTES
  • SEE ALSO
  • AUTHOR AND COPYRIGHT
  • ACKNOWLEDGEMENTS
  • HISTORY

NAME

perltooc - Tom's OO Tutorial for Class Data in Perl

DESCRIPTION

When designing an object class, you are sometimes faced with the situation of wanting common state shared by all objects of that class. Such class attributes act somewhat like global variables for the entire class, but unlike program-wide globals, class attributes have meaning only to the class itself.

Here are a few examples where class attributes might come in handy:

  • to keep a count of the objects you've created, or how many are still extant.

  • to extract the name or file descriptor for a logfile used by a debugging method.

  • to access collective data, like the total amount of cash dispensed by all ATMs in a network in a given day.

  • to access the last object created by a class, or the most accessed object, or to retrieve a list of all objects.

Unlike a true global, class attributes should not be accessed directly. Instead, their state should be inspected, and perhaps altered, only through the mediated access of class methods. These class attributes accessor methods are similar in spirit and function to accessors used to manipulate the state of instance attributes on an object. They provide a clear firewall between interface and implementation.

You should allow access to class attributes through either the class name or any object of that class. If we assume that $an_object is of type Some_Class, and the &Some_Class::population_count method accesses class attributes, then these two invocations should both be possible, and almost certainly equivalent.

    Some_Class->population_count()
    $an_object->population_count()

The question is, where do you store the state which that method accesses? Unlike more restrictive languages like C++, where these are called static data members, Perl provides no syntactic mechanism to declare class attributes, any more than it provides a syntactic mechanism to declare instance attributes. Perl provides the developer with a broad set of powerful but flexible features that can be uniquely crafted to the particular demands of the situation.

A class in Perl is typically implemented in a module. A module consists of two complementary feature sets: a package for interfacing with the outside world, and a lexical file scope for privacy. Either of these two mechanisms can be used to implement class attributes. That means you get to decide whether to put your class attributes in package variables or to put them in lexical variables.

And those aren't the only decisions to make. If you choose to use package variables, you can make your class attribute accessor methods either ignorant of inheritance or sensitive to it. If you choose lexical variables, you can elect to permit access to them from anywhere in the entire file scope, or you can limit direct data access exclusively to the methods implementing those attributes.

Class Data in a Can

One of the easiest ways to solve a hard problem is to let someone else do it for you! In this case, Class::Data::Inheritable (available on a CPAN near you) offers a canned solution to the class data problem using closures. So before you wade into this document, consider having a look at that module.

Class Data as Package Variables

Because a class in Perl is really just a package, using package variables to hold class attributes is the most natural choice. This makes it simple for each class to have its own class attributes. Let's say you have a class called Some_Class that needs a couple of different attributes that you'd like to be global to the entire class. The simplest thing to do is to use package variables like $Some_Class::CData1 and $Some_Class::CData2 to hold these attributes. But we certainly don't want to encourage outsiders to touch those data directly, so we provide methods to mediate access.

In the accessor methods below, we'll for now just ignore the first argument--that part to the left of the arrow on method invocation, which is either a class name or an object reference.

    package Some_Class;
    sub CData1 {
        shift;  # XXX: ignore calling class/object
        $Some_Class::CData1 = shift if @_;
        return $Some_Class::CData1;
    }
    sub CData2 {
        shift;  # XXX: ignore calling class/object
        $Some_Class::CData2 = shift if @_;
        return $Some_Class::CData2;
    }

This technique is highly legible and should be completely straightforward to even the novice Perl programmer. By fully qualifying the package variables, they stand out clearly when reading the code. Unfortunately, if you misspell one of these, you've introduced an error that's hard to catch. It's also somewhat disconcerting to see the class name itself hard-coded in so many places.

Both these problems can be easily fixed. Just add the use strict pragma, then pre-declare your package variables. (The our operator will be new in 5.6, and will work for package globals just like my works for scoped lexicals.)

    package Some_Class;
    use strict;
    our($CData1, $CData2);      # our() is new to perl5.6
    sub CData1 {
        shift;  # XXX: ignore calling class/object
        $CData1 = shift if @_;
        return $CData1;
    }
    sub CData2 {
        shift;  # XXX: ignore calling class/object
        $CData2 = shift if @_;
        return $CData2;
    }

As with any other global variable, some programmers prefer to start their package variables with capital letters. This helps clarity somewhat, but by no longer fully qualifying the package variables, their significance can be lost when reading the code. You can fix this easily enough by choosing better names than were used here.

Putting All Your Eggs in One Basket

Just as the mindless enumeration of accessor methods for instance attributes grows tedious after the first few (see the perltoot manpage), so too does the repetition begin to grate when listing out accessor methods for class data. Repetition runs counter to the primary virtue of a programmer: Laziness, here manifesting as that innate urge every programmer feels to factor out duplicate code whenever possible.

Here's what to do. First, make just one hash to hold all class attributes.

    package Some_Class;
    use strict;
    our %ClassData = (          # our() is new to perl5.6
        CData1 => "",
        CData2 => "",
    );

Using closures (see the perlref manpage) and direct access to the package symbol table (see the perlmod manpage), now clone an accessor method for each key in the %ClassData hash. Each of these methods is used to fetch or store values to the specific, named class attribute.

    for my $datum (keys %ClassData) {
        no strict "refs";       # to register new methods in package
        *$datum = sub {
            shift;      # XXX: ignore calling class/object
            $ClassData{$datum} = shift if @_;
            return $ClassData{$datum};
        }
    }

It's true that you could work out a solution employing an &AUTOLOAD method, but this approach is unlikely to prove satisfactory. Your function would have to distinguish between class attributes and object attributes; it could interfere with inheritance; and it would have to careful about DESTROY. Such complexity is uncalled for in most cases, and certainly in this one.

You may wonder why we're rescinding strict refs for the loop. We're manipulating the package's symbol table to introduce new function names using symbolic references (indirect naming), which the strict pragma would otherwise forbid. Normally, symbolic references are a dodgy notion at best. This isn't just because they can be used accidentally when you aren't meaning to. It's also because for most uses to which beginning Perl programmers attempt to put symbolic references, we have much better approaches, like nested hashes or hashes of arrays. But there's nothing wrong with using symbolic references to manipulate something that is meaningful only from the perspective of the package symbol table, like method names or package variables. In other words, when you want to refer to the symbol table, use symbol references.

Clustering all the class attributes in one place has several advantages. They're easy to spot, initialize, and change. The aggregation also makes them convenient to access externally, such as from a debugger or a persistence package. The only possible problem is that we don't automatically know the name of each class's class object, should it have one. This issue is addressed below in The Eponymous Meta-Object.

Inheritance Concerns

Suppose you have an instance of a derived class, and you access class data using an inherited method call. Should that end up referring to the base class's attributes, or to those in the derived class? How would it work in the earlier examples? The derived class inherits all the base class's methods, including those that access class attributes. But what package are the class attributes stored in?

The answer is that, as written, class attributes are stored in the package into which those methods were compiled. When you invoke the &CData1 method on the name of the derived class or on one of that class's objects, the version shown above is still run, so you'll access $Some_Class::CData1--or in the method cloning version, $Some_Class::ClassData{CData1}.

Think of these class methods as executing in the context of their base class, not in that of their derived class. Sometimes this is exactly what you want. If Feline subclasses Carnivore, then the population of Carnivores in the world should go up when a new Feline is born. But what if you wanted to figure out how many Felines you have apart from Carnivores? The current approach doesn't support that.

You'll have to decide on a case-by-case basis whether it makes any sense for class attributes to be package-relative. If you want it to be so, then stop ignoring the first argument to the function. Either it will be a package name if the method was invoked directly on a class name, or else it will be an object reference if the method was invoked on an object reference. In the latter case, the ref() function provides the class of that object.

    package Some_Class;
    sub CData1 {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        my $varname = $class . "::CData1";
        no strict "refs";       # to access package data symbolically
        $$varname = shift if @_;
        return $$varname;
    }

And then do likewise for all other class attributes (such as CData2, etc.) that you wish to access as package variables in the invoking package instead of the compiling package as we had previously.

Once again we temporarily disable the strict references ban, because otherwise we couldn't use the fully-qualified symbolic name for the package global. This is perfectly reasonable: since all package variables by definition live in a package, there's nothing wrong with accessing them via that package's symbol table. That's what it's there for (well, somewhat).

What about just using a single hash for everything and then cloning methods? What would that look like? The only difference would be the closure used to produce new method entries for the class's symbol table.

    no strict "refs";
    *$datum = sub {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        my $varname = $class . "::ClassData";
        $varname->{$datum} = shift if @_;
        return $varname->{$datum};
    }

The Eponymous Meta-Object

It could be argued that the %ClassData hash in the previous example is neither the most imaginative nor the most intuitive of names. Is there something else that might make more sense, be more useful, or both?

As it happens, yes, there is. For the "class meta-object", we'll use a package variable of the same name as the package itself. Within the scope of a package Some_Class declaration, we'll use the eponymously named hash %Some_Class as that class's meta-object. (Using an eponymously named hash is somewhat reminiscent of classes that name their constructors eponymously in the Python or C++ fashion. That is, class Some_Class would use &Some_Class::Some_Class as a constructor, probably even exporting that name as well. The StrNum class in Recipe 13.14 in The Perl Cookbook does this, if you're looking for an example.)

This predictable approach has many benefits, including having a well-known identifier to aid in debugging, transparent persistence, or checkpointing. It's also the obvious name for monadic classes and translucent attributes, discussed later.

Here's an example of such a class. Notice how the name of the hash storing the meta-object is the same as the name of the package used to implement the class.

    package Some_Class;
    use strict;

    # create class meta-object using that most perfect of names
    our %Some_Class = (         # our() is new to perl5.6
        CData1 => "",
        CData2 => "",
    );

    # this accessor is calling-package-relative
    sub CData1 {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        no strict "refs";       # to access eponymous meta-object
        $class->{CData1} = shift if @_;
        return $class->{CData1};
    }

    # but this accessor is not
    sub CData2 {
        shift;                  # XXX: ignore calling class/object
        no strict "refs";       # to access eponymous meta-object
        __PACKAGE__ -> {CData2} = shift if @_;
        return __PACKAGE__ -> {CData2};
    }

In the second accessor method, the __PACKAGE__ notation was used for two reasons. First, to avoid hardcoding the literal package name in the code in case we later want to change that name. Second, to clarify to the reader that what matters here is the package currently being compiled into, not the package of the invoking object or class. If the long sequence of non-alphabetic characters bothers you, you can always put the __PACKAGE__ in a variable first.

    sub CData2 {
        shift;                  # XXX: ignore calling class/object
        no strict "refs";       # to access eponymous meta-object
        my $class = __PACKAGE__;
        $class->{CData2} = shift if @_;
        return $class->{CData2};
    }

Even though we're using symbolic references for good not evil, some folks tend to become unnerved when they see so many places with strict ref checking disabled. Given a symbolic reference, you can always produce a real reference (the reverse is not true, though). So we'll create a subroutine that does this conversion for us. If invoked as a function of no arguments, it returns a reference to the compiling class's eponymous hash. Invoked as a class method, it returns a reference to the eponymous hash of its caller. And when invoked as an object method, this function returns a reference to the eponymous hash for whatever class the object belongs to.

    package Some_Class;
    use strict;

    our %Some_Class = (         # our() is new to perl5.6
        CData1 => "",
        CData2 => "",
    );

    # tri-natured: function, class method, or object method
    sub _classobj {
        my $obclass = shift || __PACKAGE__;
        my $class   = ref($obclass) || $obclass;
        no strict "refs";   # to convert sym ref to real one
        return \%$class;
    }

    for my $datum (keys %{ _classobj() } ) {
        # turn off strict refs so that we can
        # register a method in the symbol table
        no strict "refs";
        *$datum = sub {
            use strict "refs";
            my $self = shift->_classobj();
            $self->{$datum} = shift if @_;
            return $self->{$datum};
        }
    }

Indirect References to Class Data

A reasonably common strategy for handling class attributes is to store a reference to each package variable on the object itself. This is a strategy you've probably seen before, such as in the perltoot manpage and the perlbot manpage, but there may be variations in the example below that you haven't thought of before.

    package Some_Class;
    our($CData1, $CData2);              # our() is new to perl5.6

    sub new {
        my $obclass = shift;
        return bless my $self = {
            ObData1 => "",
            ObData2 => "",
            CData1  => \$CData1,
            CData2  => \$CData2,
        } => (ref $obclass || $obclass);
    }

    sub ObData1 {
        my $self = shift;
        $self->{ObData1} = shift if @_;
        return $self->{ObData1};
    }

    sub ObData2 {
        my $self = shift;
        $self->{ObData2} = shift if @_;
        return $self->{ObData2};
    }

    sub CData1 {
        my $self = shift;
        my $dataref = ref $self
                        ? $self->{CData1}
                        : \$CData1;
        $$dataref = shift if @_;
        return $$dataref;
    }

    sub CData2 {
        my $self = shift;
        my $dataref = ref $self
                        ? $self->{CData2}
                        : \$CData2;
        $$dataref = shift if @_;
        return $$dataref;
    }

As written above, a derived class will inherit these methods, which will consequently access package variables in the base class's package. This is not necessarily expected behavior in all circumstances. Here's an example that uses a variable meta-object, taking care to access the proper package's data.

        package Some_Class;
        use strict;

        our %Some_Class = (     # our() is new to perl5.6
            CData1 => "",
            CData2 => "",
        );

        sub _classobj {
            my $self  = shift;
            my $class = ref($self) || $self;
            no strict "refs";
            # get (hard) ref to eponymous meta-object
            return \%$class;
        }

        sub new {
            my $obclass  = shift;
            my $classobj = $obclass->_classobj();
            bless my $self = {
                ObData1 => "",
                ObData2 => "",
                CData1  => \$classobj->{CData1},
                CData2  => \$classobj->{CData2},
            } => (ref $obclass || $obclass);
            return $self;
        }

        sub ObData1 {
            my $self = shift;
            $self->{ObData1} = shift if @_;
            return $self->{ObData1};
        }

        sub ObData2 {
            my $self = shift;
            $self->{ObData2} = shift if @_;
            return $self->{ObData2};
        }

        sub CData1 {
            my $self = shift;
            $self = $self->_classobj() unless ref $self;
            my $dataref = $self->{CData1};
            $$dataref = shift if @_;
            return $$dataref;
        }

        sub CData2 {
            my $self = shift;
            $self = $self->_classobj() unless ref $self;
            my $dataref = $self->{CData2};
            $$dataref = shift if @_;
            return $$dataref;
        }

Not only are we now strict refs clean, using an eponymous meta-object seems to make the code cleaner. Unlike the previous version, this one does something interesting in the face of inheritance: it accesses the class meta-object in the invoking class instead of the one into which the method was initially compiled.

You can easily access data in the class meta-object, making it easy to dump the complete class state using an external mechanism such as when debugging or implementing a persistent class. This works because the class meta-object is a package variable, has a well-known name, and clusters all its data together. (Transparent persistence is not always feasible, but it's certainly an appealing idea.)

There's still no check that object accessor methods have not been invoked on a class name. If strict ref checking is enabled, you'd blow up. If not, then you get the eponymous meta-object. What you do with--or about--this is up to you. The next two sections demonstrate innovative uses for this powerful feature.

Monadic Classes

Some of the standard modules shipped with Perl provide class interfaces without any attribute methods whatsoever. The most commonly used module not numbered amongst the pragmata, the Exporter module, is a class with neither constructors nor attributes. Its job is simply to provide a standard interface for modules wishing to export part of their namespace into that of their caller. Modules use the Exporter's &import method by setting their inheritance list in their package's @ISA array to mention "Exporter". But class Exporter provides no constructor, so you can't have several instances of the class. In fact, you can't have any--it just doesn't make any sense. All you get is its methods. Its interface contains no statefulness, so state data is wholly superfluous.

Another sort of class that pops up from time to time is one that supports a unique instance. Such classes are called monadic classes, or less formally, singletons or highlander classes.

If a class is monadic, where do you store its state, that is, its attributes? How do you make sure that there's never more than one instance? While you could merely use a slew of package variables, it's a lot cleaner to use the eponymously named hash. Here's a complete example of a monadic class:

    package Cosmos;
    %Cosmos = ();

    # accessor method for "name" attribute
    sub name {
        my $self = shift;
        $self->{name} = shift if @_;
        return $self->{name};
    }

    # read-only accessor method for "birthday" attribute
    sub birthday {
        my $self = shift;
        die "can't reset birthday" if @_;  # XXX: croak() is better
        return $self->{birthday};
    }

    # accessor method for "stars" attribute
    sub stars {
        my $self = shift;
        $self->{stars} = shift if @_;
        return $self->{stars};
    }

    # oh my - one of our stars just went out!
    sub supernova {
        my $self = shift;
        my $count = $self->stars();
        $self->stars($count - 1) if $count > 0;
    }

    # constructor/initializer method - fix by reboot
    sub bigbang {
        my $self = shift;
        %$self = (
            name         => "the world according to tchrist",
            birthday     => time(),
            stars        => 0,
        );
        return $self;       # yes, it's probably a class.  SURPRISE!
    }

    # After the class is compiled, but before any use or require
    # returns, we start off the universe with a bang.
    __PACKAGE__ -> bigbang();

Hold on, that doesn't look like anything special. Those attribute accessors look no different than they would if this were a regular class instead of a monadic one. The crux of the matter is there's nothing that says that $self must hold a reference to a blessed object. It merely has to be something you can invoke methods on. Here the package name itself, Cosmos, works as an object. Look at the &supernova method. Is that a class method or an object method? The answer is that static analysis cannot reveal the answer. Perl doesn't care, and neither should you. In the three attribute methods, %$self is really accessing the %Cosmos package variable.

If like Stephen Hawking, you posit the existence of multiple, sequential, and unrelated universes, then you can invoke the &bigbang method yourself at any time to start everything all over again. You might think of &bigbang as more of an initializer than a constructor, since the function doesn't allocate new memory; it only initializes what's already there. But like any other constructor, it does return a scalar value to use for later method invocations.

Imagine that some day in the future, you decide that one universe just isn't enough. You could write a new class from scratch, but you already have an existing class that does what you want--except that it's monadic, and you want more than just one cosmos.

That's what code reuse via subclassing is all about. Look how short the new code is:

    package Multiverse;
    use Cosmos;
    @ISA = qw(Cosmos);

    sub new {
        my $protoverse = shift;
        my $class      = ref($protoverse) || $protoverse;
        my $self       = {};
        return bless($self, $class)->bigbang();
    }
    1;

Because we were careful to be good little creators when we designed our Cosmos class, we can now reuse it without touching a single line of code when it comes time to write our Multiverse class. The same code that worked when invoked as a class method continues to work perfectly well when invoked against separate instances of a derived class.

The astonishing thing about the Cosmos class above is that the value returned by the &bigbang "constructor" is not a reference to a blessed object at all. It's just the class's own name. A class name is, for virtually all intents and purposes, a perfectly acceptable object. It has state, behavior, and identity, the three crucial components of an object system. It even manifests inheritance, polymorphism, and encapsulation. And what more can you ask of an object?

To understand object orientation in Perl, it's important to recognize the unification of what other programming languages might think of as class methods and object methods into just plain methods. "Class methods" and "object methods" are distinct only in the compartmentalizing mind of the Perl programmer, not in the Perl language itself.

Along those same lines, a constructor is nothing special either, which is one reason why Perl has no pre-ordained name for them. "Constructor" is just an informal term loosely used to describe a method that returns a scalar value that you can make further method calls against. So long as it's either a class name or an object reference, that's good enough. It doesn't even have to be a reference to a brand new object.

You can have as many--or as few--constructors as you want, and you can name them whatever you care to. Blindly and obediently using new() for each and every constructor you ever write is to speak Perl with such a severe C++ accent that you do a disservice to both languages. There's no reason to insist that each class have but one constructor, or that a constructor be named new(), or that a constructor be used solely as a class method and not an object method.

The next section shows how useful it can be to further distance ourselves from any formal distinction between class method calls and object method calls, both in constructors and in accessor methods.

Translucent Attributes

A package's eponymous hash can be used for more than just containing per-class, global state data. It can also serve as a sort of template containing default settings for object attributes. These default settings can then be used in constructors for initialization of a particular object. The class's eponymous hash can also be used to implement translucent attributes. A translucent attribute is one that has a class-wide default. Each object can set its own value for the attribute, in which case $object->attribute() returns that value. But if no value has been set, then $object->attribute() returns the class-wide default.

We'll apply something of a copy-on-write approach to these translucent attributes. If you're just fetching values from them, you get translucency. But if you store a new value to them, that new value is set on the current object. On the other hand, if you use the class as an object and store the attribute value directly on the class, then the meta-object's value changes, and later fetch operations on objects with uninitialized values for those attributes will retrieve the meta-object's new values. Objects with their own initialized values, however, won't see any change.

Let's look at some concrete examples of using these properties before we show how to implement them. Suppose that a class named Some_Class had a translucent data attribute called "color". First you set the color in the meta-object, then you create three objects using a constructor that happens to be named &spawn.

    use Vermin;
    Vermin->color("vermilion");

    $ob1 = Vermin->spawn();     # so that's where Jedi come from
    $ob2 = Vermin->spawn();
    $ob3 = Vermin->spawn();

    print $obj3->color();       # prints "vermilion"

Each of these objects' colors is now "vermilion", because that's the meta-object's value for that attribute, and these objects do not have individual color values set.

Changing the attribute on one object has no effect on other objects previously created.

    $ob3->color("chartreuse");
    print $ob3->color();        # prints "chartreuse"
    print $ob1->color();        # prints "vermilion", translucently

If you now use $ob3 to spawn off another object, the new object will take the color its parent held, which now happens to be "chartreuse". That's because the constructor uses the invoking object as its template for initializing attributes. When that invoking object is the class name, the object used as a template is the eponymous meta-object. When the invoking object is a reference to an instantiated object, the &spawn constructor uses that existing object as a template.

    $ob4 = $ob3->spawn();       # $ob3 now template, not %Vermin
    print $ob4->color();        # prints "chartreuse"

Any actual values set on the template object will be copied to the new object. But attributes undefined in the template object, being translucent, will remain undefined and consequently translucent in the new one as well.

Now let's change the color attribute on the entire class:

    Vermin->color("azure");
    print $ob1->color();        # prints "azure"
    print $ob2->color();        # prints "azure"
    print $ob3->color();        # prints "chartreuse"
    print $ob4->color();        # prints "chartreuse"

That color change took effect only in the first pair of objects, which were still translucently accessing the meta-object's values. The second pair had per-object initialized colors, and so didn't change.

One important question remains. Changes to the meta-object are reflected in translucent attributes in the entire class, but what about changes to discrete objects? If you change the color of $ob3, does the value of $ob4 see that change? Or vice-versa. If you change the color of $ob4, does then the value of $ob3 shift?

    $ob3->color("amethyst");
    print $ob3->color();        # prints "amethyst"
    print $ob4->color();        # hmm: "chartreuse" or "amethyst"?

While one could argue that in certain rare cases it should, let's not do that. Good taste aside, we want the answer to the question posed in the comment above to be "chartreuse", not "amethyst". So we'll treat these attributes similar to the way process attributes like environment variables, user and group IDs, or the current working directory are treated across a fork(). You can change only yourself, but you will see those changes reflected in your unspawned children. Changes to one object will propagate neither up to the parent nor down to any existing child objects. Those objects made later, however, will see the changes.

If you have an object with an actual attribute value, and you want to make that object's attribute value translucent again, what do you do? Let's design the class so that when you invoke an accessor method with undef as its argument, that attribute returns to translucency.

    $ob4->color(undef);         # back to "azure"

Here's a complete implementation of Vermin as described above.

    package Vermin;

    # here's the class meta-object, eponymously named.
    # it holds all class attributes, and also all instance attributes
    # so the latter can be used for both initialization
    # and translucency.

    our %Vermin = (             # our() is new to perl5.6
        PopCount => 0,          # capital for class attributes
        color    => "beige",    # small for instance attributes
    );

    # constructor method
    # invoked as class method or object method
    sub spawn {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        my $self = {};
        bless($self, $class);
        $class->{PopCount}++;
        # init fields from invoking object, or omit if
        # invoking object is the class to provide translucency
        %$self = %$obclass if ref $obclass;
        return $self;
    }

    # translucent accessor for "color" attribute
    # invoked as class method or object method
    sub color {
        my $self  = shift;
        my $class = ref($self) || $self;

        # handle class invocation
        unless (ref $self) {
            $class->{color} = shift if @_;
            return $class->{color}
        }

        # handle object invocation
        $self->{color} = shift if @_;
        if (defined $self->{color}) {  # not exists!
            return $self->{color};
        } else {
            return $class->{color};
        }
            }

    # accessor for "PopCount" class attribute
    # invoked as class method or object method
    # but uses object solely to locate meta-object
    sub population {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        return $class->{PopCount};
    }

    # instance destructor
    # invoked only as object method
    sub DESTROY {
        my $self  = shift;
        my $class = ref $self;
        $class->{PopCount}--;
    }

Here are a couple of helper methods that might be convenient. They aren't accessor methods at all. They're used to detect accessibility of data attributes. The &is_translucent method determines whether a particular object attribute is coming from the meta-object. The &has_attribute method detects whether a class implements a particular property at all. It could also be used to distinguish undefined properties from non-existent ones.

    # detect whether an object attribute is translucent
    # (typically?) invoked only as object method
    sub is_translucent {
        my($self, $attr)  = @_;
        return !defined $self->{$attr};
    }

    # test for presence of attribute in class
    # invoked as class method or object method
    sub has_attribute {
        my($self, $attr)  = @_;
        my $class = ref($self) || $self;
        return exists $class->{$attr};
    }

If you prefer to install your accessors more generically, you can make use of the upper-case versus lower-case convention to register into the package appropriate methods cloned from generic closures.

    for my $datum (keys %{ +__PACKAGE__ }) {
        *$datum = ($datum =~ /^[A-Z]/)
            ? sub {  # install class accessor
                    my $obclass = shift;
                    my $class   = ref($obclass) || $obclass;
                    return $class->{$datum};
                  }
            : sub { # install translucent accessor
                    my $self  = shift;
                    my $class = ref($self) || $self;
                    unless (ref $self) {
                        $class->{$datum} = shift if @_;
                        return $class->{$datum}
                    }
                    $self->{$datum} = shift if @_;
                    return defined $self->{$datum}
                        ? $self  -> {$datum}
                        : $class -> {$datum}
                  }
    }

Translations of this closure-based approach into C++, Java, and Python have been left as exercises for the reader. Be sure to send us mail as soon as you're done.

Class Data as Lexical Variables

Privacy and Responsibility

Unlike conventions used by some Perl programmers, in the previous examples, we didn't prefix the package variables used for class attributes with an underscore, nor did we do so for the names of the hash keys used for instance attributes. You don't need little markers on data names to suggest nominal privacy on attribute variables or hash keys, because these are already notionally private! Outsiders have no business whatsoever playing with anything within a class save through the mediated access of its documented interface; in other words, through method invocations. And not even through just any method, either. Methods that begin with an underscore are traditionally considered off-limits outside the class. If outsiders skip the documented method interface to poke around the internals of your class and end up breaking something, that's not your fault--it's theirs.

Perl believes in individual responsibility rather than mandated control. Perl respects you enough to let you choose your own preferred level of pain, or of pleasure. Perl believes that you are creative, intelligent, and capable of making your own decisions--and fully expects you to take complete responsibility for your own actions. In a perfect world, these admonitions alone would suffice, and everyone would be intelligent, responsible, happy, and creative. And careful. One probably shouldn't forget careful, and that's a good bit harder to expect. Even Einstein would take wrong turns by accident and end up lost in the wrong part of town.

Some folks get the heebie-jeebies when they see package variables hanging out there for anyone to reach over and alter them. Some folks live in constant fear that someone somewhere might do something wicked. The solution to that problem is simply to fire the wicked, of course. But unfortunately, it's not as simple as all that. These cautious types are also afraid that they or others will do something not so much wicked as careless, whether by accident or out of desperation. If we fire everyone who ever gets careless, pretty soon there won't be anybody left to get any work done.

Whether it's needless paranoia or sensible caution, this uneasiness can be a problem for some people. We can take the edge off their discomfort by providing the option of storing class attributes as lexical variables instead of as package variables. The my() operator is the source of all privacy in Perl, and it is a powerful form of privacy indeed.

It is widely perceived, and indeed has often been written, that Perl provides no data hiding, that it affords the class designer no privacy nor isolation, merely a rag-tag assortment of weak and unenforceable social conventions instead. This perception is demonstrably false and easily disproven. In the next section, we show how to implement forms of privacy that are far stronger than those provided in nearly any other object-oriented language.

File-Scoped Lexicals

A lexical variable is visible only through the end of its static scope. That means that the only code able to access that variable is code residing textually below the my() operator through the end of its block if it has one, or through the end of the current file if it doesn't.

Starting again with our simplest example given at the start of this document, we replace our() variables with my() versions.

    package Some_Class;
    my($CData1, $CData2);   # file scope, not in any package
    sub CData1 {
        shift;  # XXX: ignore calling class/object
        $CData1 = shift if @_;
        return $CData1;
    }
    sub CData2 {
        shift;  # XXX: ignore calling class/object
        $CData2 = shift if @_;
        return $CData2;
    }

So much for that old $Some_Class::CData1 package variable and its brethren! Those are gone now, replaced with lexicals. No one outside the scope can reach in and alter the class state without resorting to the documented interface. Not even subclasses or superclasses of this one have unmediated access to $CData1. They have to invoke the &CData1 method against Some_Class or an instance thereof, just like anybody else.

To be scrupulously honest, that last statement assumes you haven't packed several classes together into the same file scope, nor strewn your class implementation across several different files. Accessibility of those variables is based uniquely on the static file scope. It has nothing to do with the package. That means that code in a different file but the same package (class) could not access those variables, yet code in the same file but a different package (class) could. There are sound reasons why we usually suggest a one-to-one mapping between files and packages and modules and classes. You don't have to stick to this suggestion if you really know what you're doing, but you're apt to confuse yourself otherwise, especially at first.

If you'd like to aggregate your class attributes into one lexically scoped, composite structure, you're perfectly free to do so.

    package Some_Class;
    my %ClassData = (
        CData1 => "",
        CData2 => "",
    );
    sub CData1 {
        shift;  # XXX: ignore calling class/object
        $ClassData{CData1} = shift if @_;
        return $ClassData{CData1};
    }
    sub CData2 {
        shift;  # XXX: ignore calling class/object
        $ClassData{CData2} = shift if @_;
        return $ClassData{CData2};
    }

To make this more scalable as other class attributes are added, we can again register closures into the package symbol table to create accessor methods for them.

    package Some_Class;
    my %ClassData = (
        CData1 => "",
        CData2 => "",
    );
    for my $datum (keys %ClassData) {
        no strict "refs";
        *$datum = sub {
            shift;      # XXX: ignore calling class/object
            $ClassData{$datum} = shift if @_;
            return $ClassData{$datum};
        };
    }

Requiring even your own class to use accessor methods like anybody else is probably a good thing. But demanding and expecting that everyone else, be they subclass or superclass, friend or foe, will all come to your object through mediation is more than just a good idea. It's absolutely critical to the model. Let there be in your mind no such thing as "public" data, nor even "protected" data, which is a seductive but ultimately destructive notion. Both will come back to bite at you. That's because as soon as you take that first step out of the solid position in which all state is considered completely private, save from the perspective of its own accessor methods, you have violated the envelope. And, having pierced that encapsulating envelope, you shall doubtless someday pay the price when future changes in the implementation break unrelated code. Considering that avoiding this infelicitous outcome was precisely why you consented to suffer the slings and arrows of obsequious abstraction by turning to object orientation in the first place, such breakage seems unfortunate in the extreme.

More Inheritance Concerns

Suppose that Some_Class were used as a base class from which to derive Another_Class. If you invoke a &CData method on the derived class or on an object of that class, what do you get? Would the derived class have its own state, or would it piggyback on its base class's versions of the class attributes?

The answer is that under the scheme outlined above, the derived class would not have its own state data. As before, whether you consider this a good thing or a bad one depends on the semantics of the classes involved.

The cleanest, sanest, simplest way to address per-class state in a lexical is for the derived class to override its base class's version of the method that accesses the class attributes. Since the actual method called is the one in the object's derived class if this exists, you automatically get per-class state this way. Any urge to provide an unadvertised method to sneak out a reference to the %ClassData hash should be strenuously resisted.

As with any other overridden method, the implementation in the derived class always has the option of invoking its base class's version of the method in addition to its own. Here's an example:

    package Another_Class;
    @ISA = qw(Some_Class);

    my %ClassData = (
        CData1 => "",
    );

    sub CData1 {
        my($self, $newvalue) = @_;
        if (@_ > 1) {
            # set locally first
            $ClassData{CData1} = $newvalue;

            # then pass the buck up to the first
            # overridden version, if there is one
            if ($self->can("SUPER::CData1")) {
                $self->SUPER::CData1($newvalue);
            }
                    }
                    return $ClassData{CData1};
                }

Those dabbling in multiple inheritance might be concerned about there being more than one override.

    for my $parent (@ISA) {
        my $methname = $parent . "::CData1";
        if ($self->can($methname)) {
            $self->$methname($newvalue);
        }
    }

Because the &UNIVERSAL::can method returns a reference to the function directly, you can use this directly for a significant performance improvement:

    for my $parent (@ISA) {
        if (my $coderef = $self->can($parent . "::CData1")) {
            $self->$coderef($newvalue);
        }
    }

If you override UNIVERSAL::can in your own classes, be sure to return the reference appropriately.

Locking the Door and Throwing Away the Key

As currently implemented, any code within the same scope as the file-scoped lexical %ClassData can alter that hash directly. Is that ok? Is it acceptable or even desirable to allow other parts of the implementation of this class to access class attributes directly?

That depends on how careful you want to be. Think back to the Cosmos class. If the &supernova method had directly altered $Cosmos::Stars or $Cosmos::Cosmos{stars}, then we wouldn't have been able to reuse the class when it came to inventing a Multiverse. So letting even the class itself access its own class attributes without the mediating intervention of properly designed accessor methods is probably not a good idea after all.

Restricting access to class attributes from the class itself is usually not enforceable even in strongly object-oriented languages. But in Perl, you can.

Here's one way:

    package Some_Class;

    {  # scope for hiding $CData1
        my $CData1;
        sub CData1 {
            shift;      # XXX: unused
            $CData1 = shift if @_;
            return $CData1;
        }
    }

    {  # scope for hiding $CData2
        my $CData2;
        sub CData2 {
            shift;      # XXX: unused
            $CData2 = shift if @_;
            return $CData2;
        }
    }

No one--absolutely no one--is allowed to read or write the class attributes without the mediation of the managing accessor method, since only that method has access to the lexical variable it's managing. This use of mediated access to class attributes is a form of privacy far stronger than most OO languages provide.

The repetition of code used to create per-datum accessor methods chafes at our Laziness, so we'll again use closures to create similar methods.

    package Some_Class;

    {  # scope for ultra-private meta-object for class attributes
        my %ClassData = (
            CData1 => "",
            CData2 => "",
        );

        for my $datum (keys %ClassData ) {
            no strict "refs";
            *$datum = sub {
                use strict "refs";
                my ($self, $newvalue) = @_;
                $ClassData{$datum} = $newvalue if @_ > 1;
                return $ClassData{$datum};
            }
        }

    }

The closure above can be modified to take inheritance into account using the &UNIVERSAL::can method and SUPER as shown previously.

Translucency Revisited

The Vermin class demonstrates translucency using a package variable, eponymously named %Vermin, as its meta-object. If you prefer to use absolutely no package variables beyond those necessary to appease inheritance or possibly the Exporter, this strategy is closed to you. That's too bad, because translucent attributes are an appealing technique, so it would be valuable to devise an implementation using only lexicals.

There's a second reason why you might wish to avoid the eponymous package hash. If you use class names with double-colons in them, you would end up poking around somewhere you might not have meant to poke.

    package Vermin;
    $class = "Vermin";
    $class->{PopCount}++;
    # accesses $Vermin::Vermin{PopCount}

    package Vermin::Noxious;
    $class = "Vermin::Noxious";
    $class->{PopCount}++;
    # accesses $Vermin::Noxious{PopCount}

In the first case, because the class name had no double-colons, we got the hash in the current package. But in the second case, instead of getting some hash in the current package, we got the hash %Noxious in the Vermin package. (The noxious vermin just invaded another package and sprayed their data around it. :-) Perl doesn't support relative packages in its naming conventions, so any double-colons trigger a fully-qualified lookup instead of just looking in the current package.

In practice, it is unlikely that the Vermin class had an existing package variable named %Noxious that you just blew away. If you're still mistrustful, you could always stake out your own territory where you know the rules, such as using Eponymous::Vermin::Noxious or Hieronymus::Vermin::Boschious or Leave_Me_Alone::Vermin::Noxious as class names instead. Sure, it's in theory possible that someone else has a class named Eponymous::Vermin with its own %Noxious hash, but this kind of thing is always true. There's no arbiter of package names. It's always the case that globals like @Cwd::ISA would collide if more than one class uses the same Cwd package.

If this still leaves you with an uncomfortable twinge of paranoia, we have another solution for you. There's nothing that says that you have to have a package variable to hold a class meta-object, either for monadic classes or for translucent attributes. Just code up the methods so that they access a lexical instead.

Here's another implementation of the Vermin class with semantics identical to those given previously, but this time using no package variables.

    package Vermin;

    # Here's the class meta-object, eponymously named.
    # It holds all class data, and also all instance data
    # so the latter can be used for both initialization
    # and translucency.  it's a template.
    my %ClassData = (
        PopCount => 0,          # capital for class attributes
        color    => "beige",    # small for instance attributes
    );

    # constructor method
    # invoked as class method or object method
    sub spawn {
        my $obclass = shift;
        my $class   = ref($obclass) || $obclass;
        my $self = {};
        bless($self, $class);
        $ClassData{PopCount}++;
        # init fields from invoking object, or omit if
        # invoking object is the class to provide translucency
        %$self = %$obclass if ref $obclass;
        return $self;
    }

    # translucent accessor for "color" attribute
    # invoked as class method or object method
    sub color {
        my $self  = shift;

        # handle class invocation
        unless (ref $self) {
            $ClassData{color} = shift if @_;
            return $ClassData{color}
        }

        # handle object invocation
        $self->{color} = shift if @_;
        if (defined $self->{color}) {  # not exists!
            return $self->{color};
        } else {
            return $ClassData{color};
        }
            }

    # class attribute accessor for "PopCount" attribute
    # invoked as class method or object method
    sub population {
        return $ClassData{PopCount};
    }

    # instance destructor; invoked only as object method
    sub DESTROY {
        $ClassData{PopCount}--;
    }

    # detect whether an object attribute is translucent
    # (typically?) invoked only as object method
    sub is_translucent {
        my($self, $attr)  = @_;
        $self = \%ClassData if !ref $self;
        return !defined $self->{$attr};
    }

    # test for presence of attribute in class
    # invoked as class method or object method
    sub has_attribute {
        my($self, $attr)  = @_;
        return exists $ClassData{$attr};
    }

NOTES

Inheritance is a powerful but subtle device, best used only after careful forethought and design. Aggregation instead of inheritance is often a better approach.

You can't use file-scoped lexicals in conjunction with the SelfLoader or the AutoLoader, because they alter the lexical scope in which the module's methods wind up getting compiled.

The usual mealy-mouthed package-munging doubtless applies to setting up names of object attributes. For example, $self->{ObData1} should probably be $self->{ __PACKAGE__ . "_ObData1" }, but that would just confuse the examples.

SEE ALSO

the perltoot manpage, the perlobj manpage, the perlmod manpage, and the perlbot manpage.

The Tie::SecureHash and Class::Data::Inheritable modules from CPAN are worth checking out.

AUTHOR AND COPYRIGHT

Copyright (c) 1999 Tom Christiansen. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

ACKNOWLEDGEMENTS

Russ Allbery, Jon Orwant, Randy Ray, Larry Rosler, Nat Torkington, and Stephen Warren all contributed suggestions and corrections to this piece. Thanks especially to Damian Conway for his ideas and feedback, and without whose indirect prodding I might never have taken the time to show others how much Perl has to offer in the way of objects once you start thinking outside the tiny little box that today's "popular" object-oriented languages enforce.

HISTORY

Last edit: Sun Feb 4 20:50:28 EST 2001


perltoot - Tom's object-oriented tutorial for perl

  • Creating a Class
    • Object Representation
    • Class Interface
    • Constructors and Instance Methods
    • Planning for the Future: Better Constructors
    • Destructors
    • Other Object Methods
  • Class Data
    • Accessing Class Data
    • Debugging Methods
    • Class Destructors
    • Documenting the Interface
  • Aggregation
  • Inheritance
    • Overridden Methods
    • Multiple Inheritance
    • UNIVERSAL: The Root of All Objects
  • Alternate Object Representations
    • Arrays as Objects
    • Closures as Objects
  • AUTOLOAD: Proxy Methods
    • Autoloaded Data Methods
    • Inherited Autoloaded Data Methods
  • Metaclassical Tools
    • Class::Struct
    • Data Members as Variables
  • NOTES
    • Object Terminology
  • SEE ALSO
  • AUTHOR AND COPYRIGHT
  • COPYRIGHT
    • Acknowledgments

NAME

perltoot - Tom's object-oriented tutorial for perl

DESCRIPTION

Object-oriented programming is a big seller these days. Some managers would rather have objects than sliced bread. Why is that? What's so special about an object? Just what is an object anyway?

An object is nothing but a way of tucking away complex behaviours into a neat little easy-to-use bundle. (This is what professors call abstraction.) Smart people who have nothing to do but sit around for weeks on end figuring out really hard problems make these nifty objects that even regular people can use. (This is what professors call software reuse.) Users (well, programmers) can play with this little bundle all they want, but they aren't to open it up and mess with the insides. Just like an expensive piece of hardware, the contract says that you void the warranty if you muck with the cover. So don't do that.

The heart of objects is the class, a protected little private namespace full of data and functions. A class is a set of related routines that addresses some problem area. You can think of it as a user-defined type. The Perl package mechanism, also used for more traditional modules, is used for class modules as well. Objects "live" in a class, meaning that they belong to some package.

More often than not, the class provides the user with little bundles. These bundles are objects. They know whose class they belong to, and how to behave. Users ask the class to do something, like "give me an object." Or they can ask one of these objects to do something. Asking a class to do something for you is calling a class method. Asking an object to do something for you is calling an object method. Asking either a class (usually) or an object (sometimes) to give you back an object is calling a constructor, which is just a kind of method.

That's all well and good, but how is an object different from any other Perl data type? Just what is an object really; that is, what's its fundamental type? The answer to the first question is easy. An object is different from any other data type in Perl in one and only one way: you may dereference it using not merely string or numeric subscripts as with simple arrays and hashes, but with named subroutine calls. In a word, with methods.

The answer to the second question is that it's a reference, and not just any reference, mind you, but one whose referent has been bless()ed into a particular class (read: package). What kind of reference? Well, the answer to that one is a bit less concrete. That's because in Perl the designer of the class can employ any sort of reference they'd like as the underlying intrinsic data type. It could be a scalar, an array, or a hash reference. It could even be a code reference. But because of its inherent flexibility, an object is usually a hash reference.

Creating a Class

Before you create a class, you need to decide what to name it. That's because the class (package) name governs the name of the file used to house it, just as with regular modules. Then, that class (package) should provide one or more ways to generate objects. Finally, it should provide mechanisms to allow users of its objects to indirectly manipulate these objects from a distance.

For example, let's make a simple Person class module. It gets stored in the file Person.pm. If it were called a Happy::Person class, it would be stored in the file Happy/Person.pm, and its package would become Happy::Person instead of just Person. (On a personal computer not running Unix or Plan 9, but something like Mac OS or VMS, the directory separator may be different, but the principle is the same.) Do not assume any formal relationship between modules based on their directory names. This is merely a grouping convenience, and has no effect on inheritance, variable accessibility, or anything else.

For this module we aren't going to use Exporter, because we're a well-behaved class module that doesn't export anything at all. In order to manufacture objects, a class needs to have a constructor method. A constructor gives you back not just a regular data type, but a brand-new object in that class. This magic is taken care of by the bless() function, whose sole purpose is to enable its referent to be used as an object. Remember: being an object really means nothing more than that methods may now be called against it.

While a constructor may be named anything you'd like, most Perl programmers seem to like to call theirs new(). However, new() is not a reserved word, and a class is under no obligation to supply such. Some programmers have also been known to use a function with the same name as the class as the constructor.

Object Representation

By far the most common mechanism used in Perl to represent a Pascal record, a C struct, or a C++ class is an anonymous hash. That's because a hash has an arbitrary number of data fields, each conveniently accessed by an arbitrary name of your own devising.

If you were just doing a simple struct-like emulation, you would likely go about it something like this:

    $rec = {
        name  => "Jason",
        age   => 23,
        peers => [ "Norbert", "Rhys", "Phineas"],
    };

If you felt like it, you could add a bit of visual distinction by up-casing the hash keys:

    $rec = {
        NAME  => "Jason",
        AGE   => 23,
        PEERS => [ "Norbert", "Rhys", "Phineas"],
    };

And so you could get at $rec->{NAME} to find "Jason", or @{ $rec->{PEERS} } to get at "Norbert", "Rhys", and "Phineas". (Have you ever noticed how many 23-year-old programmers seem to be named "Jason" these days? :-)

This same model is often used for classes, although it is not considered the pinnacle of programming propriety for folks from outside the class to come waltzing into an object, brazenly accessing its data members directly. Generally speaking, an object should be considered an opaque cookie that you use object methods to access. Visually, methods look like you're dereffing a reference using a function name instead of brackets or braces.

Class Interface

Some languages provide a formal syntactic interface to a class's methods, but Perl does not. It relies on you to read the documentation of each class. If you try to call an undefined method on an object, Perl won't complain, but the program will trigger an exception while it's running. Likewise, if you call a method expecting a prime number as its argument with a non-prime one instead, you can't expect the compiler to catch this. (Well, you can expect it all you like, but it's not going to happen.)

Let's suppose you have a well-educated user of your Person class, someone who has read the docs that explain the prescribed interface. Here's how they might use the Person class:

    use Person;

    $him = Person->new();
    $him->name("Jason");
    $him->age(23);
    $him->peers( "Norbert", "Rhys", "Phineas" );

    push @All_Recs, $him;  # save object in array for later

    printf "%s is %d years old.\n", $him->name, $him->age;
    print "His peers are: ", join(", ", $him->peers), "\n";

    printf "Last rec's name is %s\n", $All_Recs[-1]->name;

As you can see, the user of the class doesn't know (or at least, has no business paying attention to the fact) that the object has one particular implementation or another. The interface to the class and its objects is exclusively via methods, and that's all the user of the class should ever play with.

Constructors and Instance Methods

Still, someone has to know what's in the object. And that someone is the class. It implements methods that the programmer uses to access the object. Here's how to implement the Person class using the standard hash-ref-as-an-object idiom. We'll make a class method called new() to act as the constructor, and three object methods called name(), age(), and peers() to get at per-object data hidden away in our anonymous hash.

    package Person;
    use strict;

    ##################################################
    ## the object constructor (simplistic version)  ##
    ##################################################
    sub new {
        my $self  = {};
        $self->{NAME}   = undef;
        $self->{AGE}    = undef;
        $self->{PEERS}  = [];
        bless($self);           # but see below
        return $self;
    }

    ##############################################
    ## methods to access per-object data        ##
    ##                                          ##
    ## With args, they set the value.  Without  ##
    ## any, they only retrieve it/them.         ##
    ##############################################

    sub name {
        my $self = shift;
        if (@_) { $self->{NAME} = shift }
        return $self->{NAME};
    }

    sub age {
        my $self = shift;
        if (@_) { $self->{AGE} = shift }
        return $self->{AGE};
    }

    sub peers {
        my $self = shift;
        if (@_) { @{ $self->{PEERS} } = @_ }
        return @{ $self->{PEERS} };
    }

    1;  # so the require or use succeeds

We've created three methods to access an object's data, name(), age(), and peers(). These are all substantially similar. If called with an argument, they set the appropriate field; otherwise they return the value held by that field, meaning the value of that hash key.

Planning for the Future: Better Constructors

Even though at this point you may not even know what it means, someday you're going to worry about inheritance. (You can safely ignore this for now and worry about it later if you'd like.) To ensure that this all works out smoothly, you must use the double-argument form of bless(). The second argument is the class into which the referent will be blessed. By not assuming our own class as the default second argument and instead using the class passed into us, we make our constructor inheritable.

    sub new {
        my $class = shift;
        my $self  = {};
        $self->{NAME}   = undef;
        $self->{AGE}    = undef;
        $self->{PEERS}  = [];
        bless ($self, $class);
        return $self;
    }

That's about all there is for constructors. These methods bring objects to life, returning neat little opaque bundles to the user to be used in subsequent method calls.

Destructors

Every story has a beginning and an end. The beginning of the object's story is its constructor, explicitly called when the object comes into existence. But the ending of its story is the destructor, a method implicitly called when an object leaves this life. Any per-object clean-up code is placed in the destructor, which must (in Perl) be called DESTROY.

If constructors can have arbitrary names, then why not destructors? Because while a constructor is explicitly called, a destructor is not. Destruction happens automatically via Perl's garbage collection (GC) system, which is a quick but somewhat lazy reference-based GC system. To know what to call, Perl insists that the destructor be named DESTROY. Perl's notion of the right time to call a destructor is not well-defined currently, which is why your destructors should not rely on when they are called.

Why is DESTROY in all caps? Perl on occasion uses purely uppercase function names as a convention to indicate that the function will be automatically called by Perl in some way. Others that are called implicitly include BEGIN, END, AUTOLOAD, plus all methods used by tied objects, described in the perltie manpage.

In really good object-oriented programming languages, the user doesn't care when the destructor is called. It just happens when it's supposed to. In low-level languages without any GC at all, there's no way to depend on this happening at the right time, so the programmer must explicitly call the destructor to clean up memory and state, crossing their fingers that it's the right time to do so. Unlike C++, an object destructor is nearly never needed in Perl, and even when it is, explicit invocation is uncalled for. In the case of our Person class, we don't need a destructor because Perl takes care of simple matters like memory deallocation.

The only situation where Perl's reference-based GC won't work is when there's a circularity in the data structure, such as:

    $this->{WHATEVER} = $this;

In that case, you must delete the self-reference manually if you expect your program not to leak memory. While admittedly error-prone, this is the best we can do right now. Nonetheless, rest assured that when your program is finished, its objects' destructors are all duly called. So you are guaranteed that an object eventually gets properly destroyed, except in the unique case of a program that never exits. (If you're running Perl embedded in another application, this full GC pass happens a bit more frequently--whenever a thread shuts down.)

Other Object Methods

The methods we've talked about so far have either been constructors or else simple "data methods", interfaces to data stored in the object. These are a bit like an object's data members in the C++ world, except that strangers don't access them as data. Instead, they should only access the object's data indirectly via its methods. This is an important rule: in Perl, access to an object's data should only be made through methods.

Perl doesn't impose restrictions on who gets to use which methods. The public-versus-private distinction is by convention, not syntax. (Well, unless you use the Alias module described below in Data Members as Variables.) Occasionally you'll see method names beginning or ending with an underscore or two. This marking is a convention indicating that the methods are private to that class alone and sometimes to its closest acquaintances, its immediate subclasses. But this distinction is not enforced by Perl itself. It's up to the programmer to behave.

There's no reason to limit methods to those that simply access data. Methods can do anything at all. The key point is that they're invoked against an object or a class. Let's say we'd like object methods that do more than fetch or set one particular field.

    sub exclaim {
        my $self = shift;
        return sprintf "Hi, I'm %s, age %d, working with %s",
            $self->{NAME}, $self->{AGE}, join(", ", @{$self->{PEERS}});
    }

Or maybe even one like this:

    sub happy_birthday {
        my $self = shift;
        return ++$self->{AGE};
    }

Some might argue that one should go at these this way:

    sub exclaim {
        my $self = shift;
        return sprintf "Hi, I'm %s, age %d, working with %s",
            $self->name, $self->age, join(", ", $self->peers);
    }

    sub happy_birthday {
        my $self = shift;
        return $self->age( $self->age() + 1 );
    }

But since these methods are all executing in the class itself, this may not be critical. There are tradeoffs to be made. Using direct hash access is faster (about an order of magnitude faster, in fact), and it's more convenient when you want to interpolate in strings. But using methods (the external interface) internally shields not just the users of your class but even you yourself from changes in your data representation.

Class Data

What about "class data", data items common to each object in a class? What would you want that for? Well, in your Person class, you might like to keep track of the total people alive. How do you implement that?

You could make it a global variable called $Person::Census. But about only reason you'd do that would be if you wanted people to be able to get at your class data directly. They could just say $Person::Census and play around with it. Maybe this is ok in your design scheme. You might even conceivably want to make it an exported variable. To be exportable, a variable must be a (package) global. If this were a traditional module rather than an object-oriented one, you might do that.

While this approach is expected in most traditional modules, it's generally considered rather poor form in most object modules. In an object module, you should set up a protective veil to separate interface from implementation. So provide a class method to access class data just as you provide object methods to access object data.

So, you could still keep $Census as a package global and rely upon others to honor the contract of the module and therefore not play around with its implementation. You could even be supertricky and make $Census a tied object as described in the perltie manpage, thereby intercepting all accesses.

But more often than not, you just want to make your class data a file-scoped lexical. To do so, simply put this at the top of the file:

    my $Census = 0;

Even though the scope of a my() normally expires when the block in which it was declared is done (in this case the whole file being required or used), Perl's deep binding of lexical variables guarantees that the variable will not be deallocated, remaining accessible to functions declared within that scope. This doesn't work with global variables given temporary values via local(), though.

Irrespective of whether you leave $Census a package global or make it instead a file-scoped lexical, you should make these changes to your Person::new() constructor:

    sub new {
        my $class = shift;
        my $self  = {};
        $Census++;
        $self->{NAME}   = undef;
        $self->{AGE}    = undef;
        $self->{PEERS}  = [];
        bless ($self, $class);
        return $self;
    }

    sub population {
        return $Census;
    }

Now that we've done this, we certainly do need a destructor so that when Person is destroyed, the $Census goes down. Here's how this could be done:

    sub DESTROY { --$Census }

Notice how there's no memory to deallocate in the destructor? That's something that Perl takes care of for you all by itself.

Alternatively, you could use the Class::Data::Inheritable module from CPAN.

Accessing Class Data

It turns out that this is not really a good way to go about handling class data. A good scalable rule is that you must never reference class data directly from an object method. Otherwise you aren't building a scalable, inheritable class. The object must be the rendezvous point for all operations, especially from an object method. The globals (class data) would in some sense be in the "wrong" package in your derived classes. In Perl, methods execute in the context of the class they were defined in, not that of the object that triggered them. Therefore, namespace visibility of package globals in methods is unrelated to inheritance.

Got that? Maybe not. Ok, let's say that some other class "borrowed" (well, inherited) the DESTROY method as it was defined above. When those objects are destroyed, the original $Census variable will be altered, not the one in the new class's package namespace. Perhaps this is what you want, but probably it isn't.

Here's how to fix this. We'll store a reference to the data in the value accessed by the hash key "_CENSUS". Why the underscore? Well, mostly because an initial underscore already conveys strong feelings of magicalness to a C programmer. It's really just a mnemonic device to remind ourselves that this field is special and not to be used as a public data member in the same way that NAME, AGE, and PEERS are. (Because we've been developing this code under the strict pragma, prior to perl version 5.004 we'll have to quote the field name.)

    sub new {
        my $class = shift;
        my $self  = {};
        $self->{NAME}     = undef;
        $self->{AGE}      = undef;
        $self->{PEERS}    = [];
        # "private" data
        $self->{"_CENSUS"} = \$Census;
        bless ($self, $class);
        ++ ${ $self->{"_CENSUS"} };
        return $self;
    }

    sub population {
        my $self = shift;
        if (ref $self) {
            return ${ $self->{"_CENSUS"} };
        } else {
            return $Census;
        }
    }

    sub DESTROY {
        my $self = shift;
        -- ${ $self->{"_CENSUS"} };
    }

Debugging Methods

It's common for a class to have a debugging mechanism. For example, you might want to see when objects are created or destroyed. To do that, add a debugging variable as a file-scoped lexical. For this, we'll pull in the standard Carp module to emit our warnings and fatal messages. That way messages will come out with the caller's filename and line number instead of our own; if we wanted them to be from our own perspective, we'd just use die() and warn() directly instead of croak() and carp() respectively.

    use Carp;
    my $Debugging = 0;

Now add a new class method to access the variable.

    sub debug {
        my $class = shift;
        if (ref $class)  { confess "Class method called as object method" }
        unless (@_ == 1) { confess "usage: CLASSNAME->debug(level)" }
        $Debugging = shift;
    }

Now fix up DESTROY to murmur a bit as the moribund object expires:

    sub DESTROY {
        my $self = shift;
        if ($Debugging) { carp "Destroying $self " . $self->name }
        -- ${ $self->{"_CENSUS"} };
    }

One could conceivably make a per-object debug state. That way you could call both of these:

    Person->debug(1);   # entire class
    $him->debug(1);     # just this object

To do so, we need our debugging method to be a "bimodal" one, one that works on both classes and objects. Therefore, adjust the debug() and DESTROY methods as follows:

    sub debug {
        my $self = shift;
        confess "usage: thing->debug(level)"    unless @_ == 1;
        my $level = shift;
        if (ref($self))  {
            $self->{"_DEBUG"} = $level;         # just myself
        } else {
            $Debugging        = $level;         # whole class
        }
    }

    sub DESTROY {
        my $self = shift;
        if ($Debugging || $self->{"_DEBUG"}) {
            carp "Destroying $self " . $self->name;
        }
        -- ${ $self->{"_CENSUS"} };
    }

What happens if a derived class (which we'll call Employee) inherits methods from this Person base class? Then Employee->debug(), when called as a class method, manipulates $Person::Debugging not $Employee::Debugging.

Class Destructors

The object destructor handles the death of each distinct object. But sometimes you want a bit of cleanup when the entire class is shut down, which currently only happens when the program exits. To make such a class destructor, create a function in that class's package named END. This works just like the END function in traditional modules, meaning that it gets called whenever your program exits unless it execs or dies of an uncaught signal. For example,

    sub END {
        if ($Debugging) {
            print "All persons are going away now.\n";
        }
    }

When the program exits, all the class destructors (END functions) are be called in the opposite order that they were loaded in (LIFO order).

Documenting the Interface

And there you have it: we've just shown you the implementation of this Person class. Its interface would be its documentation. Usually this means putting it in pod ("plain old documentation") format right there in the same file. In our Person example, we would place the following docs anywhere in the Person.pm file. Even though it looks mostly like code, it's not. It's embedded documentation such as would be used by the pod2man, pod2html, or pod2text programs. The Perl compiler ignores pods entirely, just as the translators ignore code. Here's an example of some pods describing the informal interface:

    =head1 NAME
    Person - class to implement people
    =head1 SYNOPSIS
     use Person;

     #################
     # class methods #
     #################
     $ob    = Person->new;
     $count = Person->population;

     #######################
     # object data methods #
     #######################

     ### get versions ###
         $who   = $ob->name;
         $years = $ob->age;
         @pals  = $ob->peers;

     ### set versions ###
         $ob->name("Jason");
         $ob->age(23);
         $ob->peers( "Norbert", "Rhys", "Phineas" );

     ########################
     # other object methods #
     ########################

     $phrase = $ob->exclaim;
     $ob->happy_birthday;

    =head1 DESCRIPTION
    The Person class implements dah dee dah dee dah....

That's all there is to the matter of interface versus implementation. A programmer who opens up the module and plays around with all the private little shiny bits that were safely locked up behind the interface contract has voided the warranty, and you shouldn't worry about their fate.

Aggregation

Suppose you later want to change the class to implement better names. Perhaps you'd like to support both given names (called Christian names, irrespective of one's religion) and family names (called surnames), plus nicknames and titles. If users of your Person class have been properly accessing it through its documented interface, then you can easily change the underlying implementation. If they haven't, then they lose and it's their fault for breaking the contract and voiding their warranty.

To do this, we'll make another class, this one called Fullname. What's the Fullname class look like? To answer that question, you have to first figure out how you want to use it. How about we use it this way:

    $him = Person->new();
    $him->fullname->title("St");
    $him->fullname->christian("Thomas");
    $him->fullname->surname("Aquinas");
    $him->fullname->nickname("Tommy");
    printf "His normal name is %s\n", $him->name;
    printf "But his real name is %s\n", $him->fullname->as_string;

Ok. To do this, we'll change Person::new() so that it supports a full name field this way:

    sub new {
        my $class = shift;
        my $self  = {};
        $self->{FULLNAME} = Fullname->new();
        $self->{AGE}      = undef;
        $self->{PEERS}    = [];
        $self->{"_CENSUS"} = \$Census;
        bless ($self, $class);
        ++ ${ $self->{"_CENSUS"} };
        return $self;
    }

    sub fullname {
        my $self = shift;
        return $self->{FULLNAME};
    }

Then to support old code, define Person::name() this way:

    sub name {
        my $self = shift;
        return $self->{FULLNAME}->nickname(@_)
          ||   $self->{FULLNAME}->christian(@_);
    }

Here's the Fullname class. We'll use the same technique of using a hash reference to hold data fields, and methods by the appropriate name to access them:

    package Fullname;
    use strict;

    sub new {
        my $class = shift;
        my $self  = {
            TITLE       => undef,
            CHRISTIAN   => undef,
            SURNAME     => undef,
            NICK        => undef,
        };
        bless ($self, $class);
        return $self;
    }

    sub christian {
        my $self = shift;
        if (@_) { $self->{CHRISTIAN} = shift }
        return $self->{CHRISTIAN};
    }

    sub surname {
        my $self = shift;
        if (@_) { $self->{SURNAME} = shift }
        return $self->{SURNAME};
    }

    sub nickname {
        my $self = shift;
        if (@_) { $self->{NICK} = shift }
        return $self->{NICK};
    }

    sub title {
        my $self = shift;
        if (@_) { $self->{TITLE} = shift }
        return $self->{TITLE};
    }

    sub as_string {
        my $self = shift;
        my $name = join(" ", @$self{'CHRISTIAN', 'SURNAME'});
        if ($self->{TITLE}) {
            $name = $self->{TITLE} . " " . $name;
        }
        return $name;
    }

    1;

Finally, here's the test program:

    #!/usr/bin/perl -w
    use strict;
    use Person;
    sub END { show_census() }

    sub show_census ()  {
        printf "Current population: %d\n", Person->population;
    }

    Person->debug(1);

    show_census();

    my $him = Person->new();

    $him->fullname->christian("Thomas");
    $him->fullname->surname("Aquinas");
    $him->fullname->nickname("Tommy");
    $him->fullname->title("St");
    $him->age(1);

    printf "%s is really %s.\n", $him->name, $him->fullname->as_string;
    printf "%s's age: %d.\n", $him->name, $him->age;
    $him->happy_birthday;
    printf "%s's age: %d.\n", $him->name, $him->age;

    show_census();

Inheritance

Object-oriented programming systems all support some notion of inheritance. Inheritance means allowing one class to piggy-back on top of another one so you don't have to write the same code again and again. It's about software reuse, and therefore related to Laziness, the principal virtue of a programmer. (The import/export mechanisms in traditional modules are also a form of code reuse, but a simpler one than the true inheritance that you find in object modules.)

Sometimes the syntax of inheritance is built into the core of the language, and sometimes it's not. Perl has no special syntax for specifying the class (or classes) to inherit from. Instead, it's all strictly in the semantics. Each package can have a variable called @ISA, which governs (method) inheritance. If you try to call a method on an object or class, and that method is not found in that object's package, Perl then looks to @ISA for other packages to go looking through in search of the missing method.

Like the special per-package variables recognized by Exporter (such as @EXPORT, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, and $VERSION), the @ISA array must be a package-scoped global and not a file-scoped lexical created via my(). Most classes have just one item in their @ISA array. In this case, we have what's called "single inheritance", or SI for short.

Consider this class:

    package Employee;
    use Person;
    @ISA = ("Person");
    1;

Not a lot to it, eh? All it's doing so far is loading in another class and stating that this one will inherit methods from that other class if need be. We have given it none of its own methods. We rely upon an Employee to behave just like a Person.

Setting up an empty class like this is called the "empty subclass test"; that is, making a derived class that does nothing but inherit from a base class. If the original base class has been designed properly, then the new derived class can be used as a drop-in replacement for the old one. This means you should be able to write a program like this:

    use Employee;
    my $empl = Employee->new();
    $empl->name("Jason");
    $empl->age(23);
    printf "%s is age %d.\n", $empl->name, $empl->age;

By proper design, we mean always using the two-argument form of bless(), avoiding direct access of global data, and not exporting anything. If you look back at the Person::new() function we defined above, we were careful to do that. There's a bit of package data used in the constructor, but the reference to this is stored on the object itself and all other methods access package data via that reference, so we should be ok.

What do we mean by the Person::new() function -- isn't that actually a method? Well, in principle, yes. A method is just a function that expects as its first argument a class name (package) or object (blessed reference). Person::new() is the function that both the Person->new() method and the Employee->new() method end up calling. Understand that while a method call looks a lot like a function call, they aren't really quite the same, and if you treat them as the same, you'll very soon be left with nothing but broken programs. First, the actual underlying calling conventions are different: method calls get an extra argument. Second, function calls don't do inheritance, but methods do.

        Method Call             Resulting Function Call
        -----------             ------------------------
        Person->new()           Person::new("Person")
        Employee->new()         Person::new("Employee")

So don't use function calls when you mean to call a method.

If an employee is just a Person, that's not all too very interesting. So let's add some other methods. We'll give our employee data fields to access their salary, their employee ID, and their start date.

If you're getting a little tired of creating all these nearly identical methods just to get at the object's data, do not despair. Later, we'll describe several different convenience mechanisms for shortening this up. Meanwhile, here's the straight-forward way:

    sub salary {
        my $self = shift;
        if (@_) { $self->{SALARY} = shift }
        return $self->{SALARY};
    }

    sub id_number {
        my $self = shift;
        if (@_) { $self->{ID} = shift }
        return $self->{ID};
    }

    sub start_date {
        my $self = shift;
        if (@_) { $self->{START_DATE} = shift }
        return $self->{START_DATE};
    }

Overridden Methods

What happens when both a derived class and its base class have the same method defined? Well, then you get the derived class's version of that method. For example, let's say that we want the peers() method called on an employee to act a bit differently. Instead of just returning the list of peer names, let's return slightly different strings. So doing this:

    $empl->peers("Peter", "Paul", "Mary");
    printf "His peers are: %s\n", join(", ", $empl->peers);

will produce:

    His peers are: PEON=PETER, PEON=PAUL, PEON=MARY

To do this, merely add this definition into the Employee.pm file:

    sub peers {
        my $self = shift;
        if (@_) { @{ $self->{PEERS} } = @_ }
        return map { "PEON=\U$_" } @{ $self->{PEERS} };
    }

There, we've just demonstrated the high-falutin' concept known in certain circles as polymorphism. We've taken on the form and behaviour of an existing object, and then we've altered it to suit our own purposes. This is a form of Laziness. (Getting polymorphed is also what happens when the wizard decides you'd look better as a frog.)

Every now and then you'll want to have a method call trigger both its derived class (also known as "subclass") version as well as its base class (also known as "superclass") version. In practice, constructors and destructors are likely to want to do this, and it probably also makes sense in the debug() method we showed previously.

To do this, add this to Employee.pm:

    use Carp;
    my $Debugging = 0;

    sub debug {
        my $self = shift;
        confess "usage: thing->debug(level)"    unless @_ == 1;
        my $level = shift;
        if (ref($self))  {
            $self->{"_DEBUG"} = $level;
        } else {
            $Debugging = $level;            # whole class
        }
        Person::debug($self, $Debugging);   # don't really do this
    }

As you see, we turn around and call the Person package's debug() function. But this is far too fragile for good design. What if Person doesn't have a debug() function, but is inheriting its debug() method from elsewhere? It would have been slightly better to say

    Person->debug($Debugging);

But even that's got too much hard-coded. It's somewhat better to say

    $self->Person::debug($Debugging);

Which is a funny way to say to start looking for a debug() method up in Person. This strategy is more often seen on overridden object methods than on overridden class methods.

There is still something a bit off here. We've hard-coded our superclass's name. This in particular is bad if you change which classes you inherit from, or add others. Fortunately, the pseudoclass SUPER comes to the rescue here.

    $self->SUPER::debug($Debugging);

This way it starts looking in my class's @ISA. This only makes sense from within a method call, though. Don't try to access anything in SUPER:: from anywhere else, because it doesn't exist outside an overridden method call. Note that SUPER refers to the superclass of the current package, not to the superclass of $self.

Things are getting a bit complicated here. Have we done anything we shouldn't? As before, one way to test whether we're designing a decent class is via the empty subclass test. Since we already have an Employee class that we're trying to check, we'd better get a new empty subclass that can derive from Employee. Here's one:

    package Boss;
    use Employee;        # :-)
    @ISA = qw(Employee);

And here's the test program:

    #!/usr/bin/perl -w
    use strict;
    use Boss;
    Boss->debug(1);

    my $boss = Boss->new();

    $boss->fullname->title("Don");
    $boss->fullname->surname("Pichon Alvarez");
    $boss->fullname->christian("Federico Jesus");
    $boss->fullname->nickname("Fred");

    $boss->age(47);
    $boss->peers("Frank", "Felipe", "Faust");

    printf "%s is age %d.\n", $boss->fullname->as_string, $boss->age;
    printf "His peers are: %s\n", join(", ", $boss->peers);

Running it, we see that we're still ok. If you'd like to dump out your object in a nice format, somewhat like the way the 'x' command works in the debugger, you could use the Data::Dumper module from CPAN this way:

    use Data::Dumper;
    print "Here's the boss:\n";
    print Dumper($boss);

Which shows us something like this:

    Here's the boss:
    $VAR1 = bless( {
         _CENSUS => \1,
         FULLNAME => bless( {
                              TITLE => 'Don',
                              SURNAME => 'Pichon Alvarez',
                              NICK => 'Fred',
                              CHRISTIAN => 'Federico Jesus'
                            }, 'Fullname' ),
         AGE => 47,
         PEERS => [
                    'Frank',
                    'Felipe',
                    'Faust'
                  ]
       }, 'Boss' );

Hm.... something's missing there. What about the salary, start date, and ID fields? Well, we never set them to anything, even undef, so they don't show up in the hash's keys. The Employee class has no new() method of its own, and the new() method in Person doesn't know about Employees. (Nor should it: proper OO design dictates that a subclass be allowed to know about its immediate superclass, but never vice-versa.) So let's fix up Employee::new() this way:

    sub new {
        my $class = shift;
        my $self  = $class->SUPER::new();
        $self->{SALARY}        = undef;
        $self->{ID}            = undef;
        $self->{START_DATE}    = undef;
        bless ($self, $class);          # reconsecrate
        return $self;
    }

Now if you dump out an Employee or Boss object, you'll find that new fields show up there now.

Multiple Inheritance

Ok, at the risk of confusing beginners and annoying OO gurus, it's time to confess that Perl's object system includes that controversial notion known as multiple inheritance, or MI for short. All this means is that rather than having just one parent class who in turn might itself have a parent class, etc., that you can directly inherit from two or more parents. It's true that some uses of MI can get you into trouble, although hopefully not quite so much trouble with Perl as with dubiously-OO languages like C++.

The way it works is actually pretty simple: just put more than one package name in your @ISA array. When it comes time for Perl to go finding methods for your object, it looks at each of these packages in order. Well, kinda. It's actually a fully recursive, depth-first order. Consider a bunch of @ISA arrays like this:

    @First::ISA    = qw( Alpha );
    @Second::ISA   = qw( Beta );
    @Third::ISA    = qw( First Second );

If you have an object of class Third:

    my $ob = Third->new();
    $ob->spin();

How do we find a spin() method (or a new() method for that matter)? Because the search is depth-first, classes will be looked up in the following order: Third, First, Alpha, Second, and Beta.

In practice, few class modules have been seen that actually make use of MI. One nearly always chooses simple containership of one class within another over MI. That's why our Person object contained a Fullname object. That doesn't mean it was one.

However, there is one particular area where MI in Perl is rampant: borrowing another class's class methods. This is rather common, especially with some bundled "objectless" classes, like Exporter, DynaLoader, AutoLoader, and SelfLoader. These classes do not provide constructors; they exist only so you may inherit their class methods. (It's not entirely clear why inheritance was done here rather than traditional module importation.)

For example, here is the POSIX module's @ISA:

    package POSIX;
    @ISA = qw(Exporter DynaLoader);

The POSIX module isn't really an object module, but then, neither are Exporter or DynaLoader. They're just lending their classes' behaviours to POSIX.

Why don't people use MI for object methods much? One reason is that it can have complicated side-effects. For one thing, your inheritance graph (no longer a tree) might converge back to the same base class. Although Perl guards against recursive inheritance, merely having parents who are related to each other via a common ancestor, incestuous though it sounds, is not forbidden. What if in our Third class shown above we wanted its new() method to also call both overridden constructors in its two parent classes? The SUPER notation would only find the first one. Also, what about if the Alpha and Beta classes both had a common ancestor, like Nought? If you kept climbing up the inheritance tree calling overridden methods, you'd end up calling Nought::new() twice, which might well be a bad idea.

UNIVERSAL: The Root of All Objects

Wouldn't it be convenient if all objects were rooted at some ultimate base class? That way you could give every object common methods without having to go and add it to each and every @ISA. Well, it turns out that you can. You don't see it, but Perl tacitly and irrevocably assumes that there's an extra element at the end of @ISA: the class UNIVERSAL. In version 5.003, there were no predefined methods there, but you could put whatever you felt like into it.

However, as of version 5.004 (or some subversive releases, like 5.003_08), UNIVERSAL has some methods in it already. These are builtin to your Perl binary, so they don't take any extra time to load. Predefined methods include isa(), can(), and VERSION(). isa() tells you whether an object or class "is" another one without having to traverse the hierarchy yourself:

   $has_io = $fd->isa("IO::Handle");
   $itza_handle = IO::Socket->isa("IO::Handle");

The can() method, called against that object or class, reports back whether its string argument is a callable method name in that class. In fact, it gives you back a function reference to that method:

   $his_print_method = $obj->can('as_string');

Finally, the VERSION method checks whether the class (or the object's class) has a package global called $VERSION that's high enough, as in:

    Some_Module->VERSION(3.0);
    $his_vers = $ob->VERSION();

However, we don't usually call VERSION ourselves. (Remember that an all uppercase function name is a Perl convention that indicates that the function will be automatically used by Perl in some way.) In this case, it happens when you say

    use Some_Module 3.0;

If you wanted to add version checking to your Person class explained above, just add this to Person.pm:

    our $VERSION = '1.1';

and then in Employee.pm you can say

    use Person 1.1;

And it would make sure that you have at least that version number or higher available. This is not the same as loading in that exact version number. No mechanism currently exists for concurrent installation of multiple versions of a module. Lamentably.

Alternate Object Representations

Nothing requires objects to be implemented as hash references. An object can be any sort of reference so long as its referent has been suitably blessed. That means scalar, array, and code references are also fair game.

A scalar would work if the object has only one datum to hold. An array would work for most cases, but makes inheritance a bit dodgy because you have to invent new indices for the derived classes.

Arrays as Objects

If the user of your class honors the contract and sticks to the advertised interface, then you can change its underlying interface if you feel like it. Here's another implementation that conforms to the same interface specification. This time we'll use an array reference instead of a hash reference to represent the object.

    package Person;
    use strict;

    my($NAME, $AGE, $PEERS) = ( 0 .. 2 );

    ############################################
    ## the object constructor (array version) ##
    ############################################
    sub new {
        my $self = [];
        $self->[$NAME]   = undef;  # this is unnecessary
        $self->[$AGE]    = undef;  # as is this
        $self->[$PEERS]  = [];     # but this isn't, really
        bless($self);
        return $self;
    }

    sub name {
        my $self = shift;
        if (@_) { $self->[$NAME] = shift }
        return $self->[$NAME];
    }

    sub age {
        my $self = shift;
        if (@_) { $self->[$AGE] = shift }
        return $self->[$AGE];
    }

    sub peers {
        my $self = shift;
        if (@_) { @{ $self->[$PEERS] } = @_ }
        return @{ $self->[$PEERS] };
    }

    1;  # so the require or use succeeds

You might guess that the array access would be a lot faster than the hash access, but they're actually comparable. The array is a little bit faster, but not more than ten or fifteen percent, even when you replace the variables above like $AGE with literal numbers, like 1. A bigger difference between the two approaches can be found in memory use. A hash representation takes up more memory than an array representation because you have to allocate memory for the keys as well as for the values. However, it really isn't that bad, especially since as of version 5.004, memory is only allocated once for a given hash key, no matter how many hashes have that key. It's expected that sometime in the future, even these differences will fade into obscurity as more efficient underlying representations are devised.

Still, the tiny edge in speed (and somewhat larger one in memory) is enough to make some programmers choose an array representation for simple classes. There's still a little problem with scalability, though, because later in life when you feel like creating subclasses, you'll find that hashes just work out better.

Closures as Objects

Using a code reference to represent an object offers some fascinating possibilities. We can create a new anonymous function (closure) who alone in all the world can see the object's data. This is because we put the data into an anonymous hash that's lexically visible only to the closure we create, bless, and return as the object. This object's methods turn around and call the closure as a regular subroutine call, passing it the field we want to affect. (Yes, the double-function call is slow, but if you wanted fast, you wouldn't be using objects at all, eh? :-)

Use would be similar to before:

    use Person;
    $him = Person->new();
    $him->name("Jason");
    $him->age(23);
    $him->peers( [ "Norbert", "Rhys", "Phineas" ] );
    printf "%s is %d years old.\n", $him->name, $him->age;
    print "His peers are: ", join(", ", @{$him->peers}), "\n";

but the implementation would be radically, perhaps even sublimely different:

    package Person;

    sub new {
         my $class  = shift;
         my $self = {
            NAME  => undef,
            AGE   => undef,
            PEERS => [],
         };
         my $closure = sub {
            my $field = shift;
            if (@_) { $self->{$field} = shift }
            return    $self->{$field};
        };
        bless($closure, $class);
        return $closure;
    }

    sub name   { &{ $_[0] }("NAME",  @_[ 1 .. $#_ ] ) }
    sub age    { &{ $_[0] }("AGE",   @_[ 1 .. $#_ ] ) }
    sub peers  { &{ $_[0] }("PEERS", @_[ 1 .. $#_ ] ) }

    1;

Because this object is hidden behind a code reference, it's probably a bit mysterious to those whose background is more firmly rooted in standard procedural or object-based programming languages than in functional programming languages whence closures derive. The object created and returned by the new() method is itself not a data reference as we've seen before. It's an anonymous code reference that has within it access to a specific version (lexical binding and instantiation) of the object's data, which are stored in the private variable $self. Although this is the same function each time, it contains a different version of $self.

When a method like $him->name("Jason") is called, its implicit zeroth argument is the invoking object--just as it is with all method calls. But in this case, it's our code reference (something like a function pointer in C++, but with deep binding of lexical variables). There's not a lot to be done with a code reference beyond calling it, so that's just what we do when we say &{$_[0]}. This is just a regular function call, not a method call. The initial argument is the string "NAME", and any remaining arguments are whatever had been passed to the method itself.

Once we're executing inside the closure that had been created in new(), the $self hash reference suddenly becomes visible. The closure grabs its first argument ("NAME" in this case because that's what the name() method passed it), and uses that string to subscript into the private hash hidden in its unique version of $self.

Nothing under the sun will allow anyone outside the executing method to be able to get at this hidden data. Well, nearly nothing. You could single step through the program using the debugger and find out the pieces while you're in the method, but everyone else is out of luck.

There, if that doesn't excite the Scheme folks, then I just don't know what will. Translation of this technique into C++, Java, or any other braindead-static language is left as a futile exercise for aficionados of those camps.

You could even add a bit of nosiness via the caller() function and make the closure refuse to operate unless called via its own package. This would no doubt satisfy certain fastidious concerns of programming police and related puritans.

If you were wondering when Hubris, the third principle virtue of a programmer, would come into play, here you have it. (More seriously, Hubris is just the pride in craftsmanship that comes from having written a sound bit of well-designed code.)

AUTOLOAD: Proxy Methods

Autoloading is a way to intercept calls to undefined methods. An autoload routine may choose to create a new function on the fly, either loaded from disk or perhaps just eval()ed right there. This define-on-the-fly strategy is why it's called autoloading.

But that's only one possible approach. Another one is to just have the autoloaded method itself directly provide the requested service. When used in this way, you may think of autoloaded methods as "proxy" methods.

When Perl tries to call an undefined function in a particular package and that function is not defined, it looks for a function in that same package called AUTOLOAD. If one exists, it's called with the same arguments as the original function would have had. The fully-qualified name of the function is stored in that package's global variable $AUTOLOAD. Once called, the function can do anything it would like, including defining a new function by the right name, and then doing a really fancy kind of goto right to it, erasing itself from the call stack.

What does this have to do with objects? After all, we keep talking about functions, not methods. Well, since a method is just a function with an extra argument and some fancier semantics about where it's found, we can use autoloading for methods, too. Perl doesn't start looking for an AUTOLOAD method until it has exhausted the recursive hunt up through @ISA, though. Some programmers have even been known to define a UNIVERSAL::AUTOLOAD method to trap unresolved method calls to any kind of object.

Autoloaded Data Methods

You probably began to get a little suspicious about the duplicated code way back earlier when we first showed you the Person class, and then later the Employee class. Each method used to access the hash fields looked virtually identical. This should have tickled that great programming virtue, Impatience, but for the time, we let Laziness win out, and so did nothing. Proxy methods can cure this.

Instead of writing a new function every time we want a new data field, we'll use the autoload mechanism to generate (actually, mimic) methods on the fly. To verify that we're accessing a valid member, we will check against an _permitted (pronounced "under-permitted") field, which is a reference to a file-scoped lexical (like a C file static) hash of permitted fields in this record called %fields. Why the underscore? For the same reason as the _CENSUS field we once used: as a marker that means "for internal use only".

Here's what the module initialization code and class constructor will look like when taking this approach:

    package Person;
    use Carp;
    our $AUTOLOAD;  # it's a package global

    my %fields = (
        name        => undef,
        age         => undef,
        peers       => undef,
    );

    sub new {
        my $class = shift;
        my $self  = {
            _permitted => \%fields,
            %fields,
        };
        bless $self, $class;
        return $self;
    }

If we wanted our record to have default values, we could fill those in where current we have undef in the %fields hash.

Notice how we saved a reference to our class data on the object itself? Remember that it's important to access class data through the object itself instead of having any method reference %fields directly, or else you won't have a decent inheritance.

The real magic, though, is going to reside in our proxy method, which will handle all calls to undefined methods for objects of class Person (or subclasses of Person). It has to be called AUTOLOAD. Again, it's all caps because it's called for us implicitly by Perl itself, not by a user directly.

    sub AUTOLOAD {
        my $self = shift;
        my $type = ref($self)
                    or croak "$self is not an object";

        my $name = $AUTOLOAD;
        $name =~ s/.*://;   # strip fully-qualified portion

        unless (exists $self->{_permitted}->{$name} ) {
            croak "Can't access `$name' field in class $type";
        }

        if (@_) {
            return $self->{$name} = shift;
        } else {
            return $self->{$name};
        }
            }

Pretty nifty, eh? All we have to do to add new data fields is modify %fields. No new functions need be written.

I could have avoided the _permitted field entirely, but I wanted to demonstrate how to store a reference to class data on the object so you wouldn't have to access that class data directly from an object method.

Inherited Autoloaded Data Methods

But what about inheritance? Can we define our Employee class similarly? Yes, so long as we're careful enough.

Here's how to be careful:

    package Employee;
    use Person;
    use strict;
    our @ISA = qw(Person);

    my %fields = (
        id          => undef,
        salary      => undef,
    );

    sub new {
        my $class = shift;
        my $self  = $class->SUPER::new();
        my($element);
        foreach $element (keys %fields) {
            $self->{_permitted}->{$element} = $fields{$element};
        }
        @{$self}{keys %fields} = values %fields;
        return $self;
    }

Once we've done this, we don't even need to have an AUTOLOAD function in the Employee package, because we'll grab Person's version of that via inheritance, and it will all work out just fine.

Metaclassical Tools

Even though proxy methods can provide a more convenient approach to making more struct-like classes than tediously coding up data methods as functions, it still leaves a bit to be desired. For one thing, it means you have to handle bogus calls that you don't mean to trap via your proxy. It also means you have to be quite careful when dealing with inheritance, as detailed above.

Perl programmers have responded to this by creating several different class construction classes. These metaclasses are classes that create other classes. A couple worth looking at are Class::Struct and Alias. These and other related metaclasses can be found in the modules directory on CPAN.

Class::Struct

One of the older ones is Class::Struct. In fact, its syntax and interface were sketched out long before perl5 even solidified into a real thing. What it does is provide you a way to "declare" a class as having objects whose fields are of a specific type. The function that does this is called, not surprisingly enough, struct(). Because structures or records are not base types in Perl, each time you want to create a class to provide a record-like data object, you yourself have to define a new() method, plus separate data-access methods for each of that record's fields. You'll quickly become bored with this process. The Class::Struct::struct() function alleviates this tedium.

Here's a simple example of using it:

    use Class::Struct qw(struct);
    use Jobbie;  # user-defined; see below

    struct 'Fred' => {
        one        => '$',
        many       => '@',
        profession => 'Jobbie',  # does not call Jobbie->new()
    };

    $ob = Fred->new(profession => Jobbie->new());
    $ob->one("hmmmm");

    $ob->many(0, "here");
    $ob->many(1, "you");
    $ob->many(2, "go");
    print "Just set: ", $ob->many(2), "\n";

    $ob->profession->salary(10_000);

You can declare types in the struct to be basic Perl types, or user-defined types (classes). User types will be initialized by calling that class's new() method.

Take care that the Jobbie object is not created automatically by the Fred class's new() method, so you should specify a Jobbie object when you create an instance of Fred.

Here's a real-world example of using struct generation. Let's say you wanted to override Perl's idea of gethostbyname() and gethostbyaddr() so that they would return objects that acted like C structures. We don't care about high-falutin' OO gunk. All we want is for these objects to act like structs in the C sense.

    use Socket;
    use Net::hostent;
    $h = gethostbyname("perl.com");  # object return
    printf "perl.com's real name is %s, address %s\n",
        $h->name, inet_ntoa($h->addr);

Here's how to do this using the Class::Struct module. The crux is going to be this call:

    struct 'Net::hostent' => [          # note bracket
        name       => '$',
        aliases    => '@',
        addrtype   => '$',
        'length'   => '$',
        addr_list  => '@',
     ];

Which creates object methods of those names and types. It even creates a new() method for us.

We could also have implemented our object this way:

    struct 'Net::hostent' => {          # note brace
        name       => '$',
        aliases    => '@',
        addrtype   => '$',
        'length'   => '$',
        addr_list  => '@',
     };

and then Class::Struct would have used an anonymous hash as the object type, instead of an anonymous array. The array is faster and smaller, but the hash works out better if you eventually want to do inheritance. Since for this struct-like object we aren't planning on inheritance, this time we'll opt for better speed and size over better flexibility.

Here's the whole implementation:

    package Net::hostent;
    use strict;

    BEGIN {
        use Exporter   ();
        our @EXPORT      = qw(gethostbyname gethostbyaddr gethost);
        our @EXPORT_OK   = qw(
                               $h_name         @h_aliases
                               $h_addrtype     $h_length
                               @h_addr_list    $h_addr
                           );
        our %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
    }
    our @EXPORT_OK;

    # Class::Struct forbids use of @ISA
    sub import { goto &Exporter::import }

    use Class::Struct qw(struct);
    struct 'Net::hostent' => [
       name        => '$',
       aliases     => '@',
       addrtype    => '$',
       'length'    => '$',
       addr_list   => '@',
    ];

    sub addr { shift->addr_list->[0] }

    sub populate (@) {
        return unless @_;
        my $hob = new();  # Class::Struct made this!
        $h_name     =    $hob->[0]              = $_[0];
        @h_aliases  = @{ $hob->[1] } = split ' ', $_[1];
        $h_addrtype =    $hob->[2]              = $_[2];
        $h_length   =    $hob->[3]              = $_[3];
        $h_addr     =                             $_[4];
        @h_addr_list = @{ $hob->[4] } =         @_[ (4 .. $#_) ];
        return $hob;
    }

    sub gethostbyname ($)  { populate(CORE::gethostbyname(shift)) }

    sub gethostbyaddr ($;$) {
        my ($addr, $addrtype);
        $addr = shift;
        require Socket unless @_;
        $addrtype = @_ ? shift : Socket::AF_INET();
        populate(CORE::gethostbyaddr($addr, $addrtype))
    }

    sub gethost($) {
        if ($_[0] =~ /^\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?$/) {
           require Socket;
           &gethostbyaddr(Socket::inet_aton(shift));
        } else {
           &gethostbyname;
        }
    }

    1;

We've snuck in quite a fair bit of other concepts besides just dynamic class creation, like overriding core functions, import/export bits, function prototyping, short-cut function call via &whatever, and function replacement with goto &whatever. These all mostly make sense from the perspective of a traditional module, but as you can see, we can also use them in an object module.

You can look at other object-based, struct-like overrides of core functions in the 5.004 release of Perl in File::stat, Net::hostent, Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime, User::grent, and User::pwent. These modules have a final component that's all lowercase, by convention reserved for compiler pragmas, because they affect the compilation and change a builtin function. They also have the type names that a C programmer would most expect.

Data Members as Variables

If you're used to C++ objects, then you're accustomed to being able to get at an object's data members as simple variables from within a method. The Alias module provides for this, as well as a good bit more, such as the possibility of private methods that the object can call but folks outside the class cannot.

Here's an example of creating a Person using the Alias module. When you update these magical instance variables, you automatically update value fields in the hash. Convenient, eh?

    package Person;

    # this is the same as before...
    sub new {
         my $class = shift;
         my $self = {
            NAME  => undef,
            AGE   => undef,
            PEERS => [],
        };
        bless($self, $class);
        return $self;
    }

    use Alias qw(attr);
    our ($NAME, $AGE, $PEERS);

    sub name {
        my $self = attr shift;
        if (@_) { $NAME = shift; }
        return    $NAME;
    }

    sub age {
        my $self = attr shift;
        if (@_) { $AGE = shift; }
        return    $AGE;
    }

    sub peers {
        my $self = attr shift;
        if (@_) { @PEERS = @_; }
        return    @PEERS;
    }

    sub exclaim {
        my $self = attr shift;
        return sprintf "Hi, I'm %s, age %d, working with %s",
            $NAME, $AGE, join(", ", @PEERS);
    }

    sub happy_birthday {
        my $self = attr shift;
        return ++$AGE;
    }

The need for the our declaration is because what Alias does is play with package globals with the same name as the fields. To use globals while use strict is in effect, you have to predeclare them. These package variables are localized to the block enclosing the attr() call just as if you'd used a local() on them. However, that means that they're still considered global variables with temporary values, just as with any other local().

It would be nice to combine Alias with something like Class::Struct or Class::MethodMaker.

NOTES

Object Terminology

In the various OO literature, it seems that a lot of different words are used to describe only a few different concepts. If you're not already an object programmer, then you don't need to worry about all these fancy words. But if you are, then you might like to know how to get at the same concepts in Perl.

For example, it's common to call an object an instance of a class and to call those objects' methods instance methods. Data fields peculiar to each object are often called instance data or object attributes, and data fields common to all members of that class are class data, class attributes, or static data members.

Also, base class, generic class, and superclass all describe the same notion, whereas derived class, specific class, and subclass describe the other related one.

C++ programmers have static methods and virtual methods, but Perl only has class methods and object methods. Actually, Perl only has methods. Whether a method gets used as a class or object method is by usage only. You could accidentally call a class method (one expecting a string argument) on an object (one expecting a reference), or vice versa.

From the C++ perspective, all methods in Perl are virtual. This, by the way, is why they are never checked for function prototypes in the argument list as regular builtin and user-defined functions can be.

Because a class is itself something of an object, Perl's classes can be taken as describing both a "class as meta-object" (also called object factory) philosophy and the "class as type definition" (declaring behaviour, not defining mechanism) idea. C++ supports the latter notion, but not the former.

SEE ALSO

The following manpages will doubtless provide more background for this one: the perlmod manpage, the perlref manpage, the perlobj manpage, the perlbot manpage, the perltie manpage, and the overload manpage.

the perlboot manpage is a kinder, gentler introduction to object-oriented programming.

the perltooc manpage provides more detail on class data.

Some modules which might prove interesting are Class::Accessor, Class::Class, Class::Contract, Class::Data::Inheritable, Class::MethodMaker and Tie::SecureHash

AUTHOR AND COPYRIGHT

Copyright (c) 1997, 1998 Tom Christiansen All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

COPYRIGHT

Acknowledgments

Thanks to Larry Wall, Roderick Schertler, Gurusamy Sarathy, Dean Roehrich, Raphael Manfredi, Brent Halsey, Greg Bacon, Brad Appleton, and many others for their helpful comments.


perlre - Perl regular expressions

    • Regular Expressions
    • Extended Patterns
    • Backtracking
    • Version 8 Regular Expressions
    • Warning on \1 vs $1
    • Repeated patterns matching zero-length substring
    • Combining pieces together
    • Creating custom RE engines
  • BUGS
  • SEE ALSO

NAME

perlre - Perl regular expressions

DESCRIPTION

This page describes the syntax of regular expressions in Perl.

If you haven't used regular expressions before, a quick-start introduction is available in the perlrequick manpage, and a longer tutorial introduction is available in the perlretut manpage.

For reference on how regular expressions are used in matching operations, plus various examples of the same, see discussions of m//, s///, qr// and ?? in Regexp Quote-Like Operators in the perlop manpage.

Matching operations can have various modifiers. Modifiers that relate to the interpretation of the regular expression inside are listed below. Modifiers that alter the way a regular expression is used by Perl are detailed in Regexp Quote-Like Operators in the perlop manpage and Gory details of parsing quoted constructs in the perlop manpage.

i

Do case-insensitive pattern matching.

If use locale is in effect, the case map is taken from the current locale. See the perllocale manpage.

m

Treat string as multiple lines. That is, change "^" and "$" from matching the start or end of the string to matching the start or end of any line anywhere within the string.

s

Treat string as single line. That is, change "." to match any character whatsoever, even a newline, which normally it would not match.

The /s and /m modifiers both override the $* setting. That is, no matter what $* contains, /s without /m will force "^" to match only at the beginning of the string and "$" to match only at the end (or just before a newline at the end) of the string. Together, as /ms, they let the "." match any character whatsoever, while still allowing "^" and "$" to match, respectively, just after and just before newlines within the string.

x

Extend your pattern's legibility by permitting whitespace and comments.

These are usually written as "the /x modifier", even though the delimiter in question might not really be a slash. Any of these modifiers may also be embedded within the regular expression itself using the (?...) construct. See below.

The /x modifier itself needs a little more explanation. It tells the regular expression parser to ignore whitespace that is neither backslashed nor within a character class. You can use this to break up your regular expression into (slightly) more readable parts. The # character is also treated as a metacharacter introducing a comment, just as in ordinary Perl code. This also means that if you want real whitespace or # characters in the pattern (outside a character class, where they are unaffected by /x), that you'll either have to escape them or encode them using octal or hex escapes. Taken together, these features go a long way towards making Perl's regular expressions more readable. Note that you have to be careful not to include the pattern delimiter in the comment--perl has no way of knowing you did not intend to close the pattern early. See the C-comment deletion code in the perlop manpage.

Regular Expressions

The patterns used in Perl pattern matching derive from supplied in the Version 8 regex routines. (The routines are derived (distantly) from Henry Spencer's freely redistributable reimplementation of the V8 routines.) See Version 8 Regular Expressions for details.

In particular the following metacharacters have their standard egrep-ish meanings:

    \   Quote the next metacharacter
    ^   Match the beginning of the line
    .   Match any character (except newline)
    $   Match the end of the line (or before newline at the end)
    |   Alternation
    ()  Grouping
    []  Character class

By default, the "^" character is guaranteed to match only the beginning of the string, the "$" character only the end (or before the newline at the end), and Perl does certain optimizations with the assumption that the string contains only one line. Embedded newlines will not be matched by "^" or "$". You may, however, wish to treat a string as a multi-line buffer, such that the "^" will match after any newline within the string, and "$" will match before any newline. At the cost of a little more overhead, you can do this by using the /m modifier on the pattern match operator. (Older programs did this by setting $*, but this practice is now deprecated.)

To simplify multi-line substitutions, the "." character never matches a newline unless you use the /s modifier, which in effect tells Perl to pretend the string is a single line--even if it isn't. The /s modifier also overrides the setting of $*, in case you have some (badly behaved) older code that sets it in another module.

The following standard quantifiers are recognized:

    *      Match 0 or more times
    +      Match 1 or more times
    ?      Match 1 or 0 times
    {n}    Match exactly n times
    {n,}   Match at least n times
    {n,m}  Match at least n but not more than m times

(If a curly bracket occurs in any other context, it is treated as a regular character. In particular, the lower bound is not optional.) The "*" modifier is equivalent to {0,}, the "+" modifier to {1,}, and the "?" modifier to {0,1}. n and m are limited to integral values less than a preset limit defined when perl is built. This is usually 32766 on the most common platforms. The actual limit can be seen in the error message generated by code such as this:

    $_ **= $_ , / {$_} / for 2 .. 42;

By default, a quantified subpattern is "greedy", that is, it will match as many times as possible (given a particular starting location) while still allowing the rest of the pattern to match. If you want it to match the minimum number of times possible, follow the quantifier with a "?". Note that the meanings don't change, just the "greediness":

    *?     Match 0 or more times
    +?     Match 1 or more times
    ??     Match 0 or 1 time
    {n}?   Match exactly n times
    {n,}?  Match at least n times
    {n,m}? Match at least n but not more than m times

Because patterns are processed as double quoted strings, the following also work:

    \t          tab                   (HT, TAB)
    \n          newline               (LF, NL)
    \r          return                (CR)
    \f          form feed             (FF)
    \a          alarm (bell)          (BEL)
    \e          escape (think troff)  (ESC)
    \033        octal char (think of a PDP-11)
    \x1B        hex char
    \x{263a}    wide hex char         (Unicode SMILEY)
    \c[         control char
    \N{name}    named char
    \l          lowercase next char (think vi)
    \u          uppercase next char (think vi)
    \L          lowercase till \E (think vi)
    \U          uppercase till \E (think vi)
    \E          end case modification (think vi)
    \Q          quote (disable) pattern metacharacters till \E

If use locale is in effect, the case map used by \l, \L, \u and \U is taken from the current locale. See the perllocale manpage. For documentation of \N{name}, see the charnames manpage.

You cannot include a literal $ or @ within a \Q sequence. An unescaped $ or @ interpolates the corresponding variable, while escaping will cause the literal string \$ to be matched. You'll need to write something like m/\Quser\E\@\Qhost/.

In addition, Perl defines the following:

    \w  Match a "word" character (alphanumeric plus "_")
    \W  Match a non-"word" character
    \s  Match a whitespace character
    \S  Match a non-whitespace character
    \d  Match a digit character
    \D  Match a non-digit character
    \pP Match P, named property.  Use \p{Prop} for longer names.
    \PP Match non-P
    \X  Match eXtended Unicode "combining character sequence",
        equivalent to (?:\PM\pM*)
    \C  Match a single C char (octet) even under Unicode.
        NOTE: breaks up characters into their UTF-8 bytes,
        so you may end up with malformed pieces of UTF-8.
        Unsupported in lookbehind.

A \w matches a single alphanumeric character (an alphabetic character, or a decimal digit) or _, not a whole word. Use \w+ to match a string of Perl-identifier characters (which isn't the same as matching an English word). If use locale is in effect, the list of alphabetic characters generated by \w is taken from the current locale. See the perllocale manpage. You may use \w, \W, \s, \S, \d, and \D within character classes, but if you try to use them as endpoints of a range, that's not a range, the "-" is understood literally. If Unicode is in effect, \s matches also "\x{85}", "\x{2028}, and "\x{2029}", see the perlunicode manpage for more details about \pP, \PP, and \X, and the perluniintro manpage about Unicode in general. You can define your own \p and \P properties, see the perlunicode manpage.

The POSIX character class syntax

    [:class:]

is also available. The available classes and their backslash equivalents (if available) are as follows:

    alpha
    alnum
    ascii
    blank               [1]
    cntrl
    digit       \d
    graph
    lower
    print
    punct
    space       \s      [2]
    upper
    word        \w      [3]
    xdigit
[1]

A GNU extension equivalent to [ \t], "all horizontal whitespace".

[2]

Not exactly equivalent to \s since the [[:space:]] includes also the (very rare) "vertical tabulator", "\ck", chr(11).

[3]

A Perl extension, see above.

For example use [:upper:] to match all the uppercase characters. Note that the [] are part of the [::] construct, not part of the whole character class. For example:

    [01[:alpha:]%]

matches zero, one, any alphabetic character, and the percentage sign.

The following equivalences to Unicode \p{} constructs and equivalent backslash character classes (if available), will hold:

    [:...:]     \p{...}         backslash

    alpha       IsAlpha
    alnum       IsAlnum
    ascii       IsASCII
    blank       IsSpace
    cntrl       IsCntrl
    digit       IsDigit        \d
    graph       IsGraph
    lower       IsLower
    print       IsPrint
    punct       IsPunct
    space       IsSpace
                IsSpacePerl    \s
    upper       IsUpper
    word        IsWord
    xdigit      IsXDigit

For example [:lower:] and \p{IsLower} are equivalent.

If the utf8 pragma is not used but the locale pragma is, the classes correlate with the usual isalpha(3) interface (except for "word" and "blank").

The assumedly non-obviously named classes are:

cntrl

Any control character. Usually characters that don't produce output as such but instead control the terminal somehow: for example newline and backspace are control characters. All characters with ord() less than 32 are most often classified as control characters (assuming ASCII, the ISO Latin character sets, and Unicode), as is the character with the ord() value of 127 (DEL).

graph

Any alphanumeric or punctuation (special) character.

print

Any alphanumeric or punctuation (special) character or the space character.

punct

Any punctuation (special) character.

xdigit

Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would work just fine) it is included for completeness.

You can negate the [::] character classes by prefixing the class name with a '^'. This is a Perl extension. For example:

    POSIX       traditional Unicode
    [:^digit:]      \D      \P{IsDigit}
    [:^space:]      \S      \P{IsSpace}
    [:^word:]       \W      \P{IsWord}

Perl respects the POSIX standard in that POSIX character classes are only supported within a character class. The POSIX character classes [.cc.] and [=cc=] are recognized but not supported and trying to use them will cause an error.

Perl defines the following zero-width assertions:

    \b  Match a word boundary
    \B  Match a non-(word boundary)
    \A  Match only at beginning of string
    \Z  Match only at end of string, or before newline at the end
    \z  Match only at end of string
    \G  Match only at pos() (e.g. at the end-of-match position
        of prior m//g)

A word boundary (\b) is a spot between two characters that has a \w on one side of it and a \W on the other side of it (in either order), counting the imaginary characters off the beginning and end of the string as matching a \W. (Within character classes \b represents backspace rather than a word boundary, just as it normally does in any double-quoted string.) The \A and \Z are just like "^" and "$", except that they won't match multiple times when the /m modifier is used, while "^" and "$" will match at every internal line boundary. To match the actual end of the string and not ignore an optional trailing newline, use \z.

The \G assertion can be used to chain global matches (using m//g), as described in Regexp Quote-Like Operators in the perlop manpage. It is also useful when writing lex-like scanners, when you have several patterns that you want to match against consequent substrings of your string, see the previous reference. The actual location where \G will match can also be influenced by using pos() as an lvalue: see pos in the perlfunc manpage. Currently \G is only fully supported when anchored to the start of the pattern; while it is permitted to use it elsewhere, as in /(?<=\G..)./g, some such uses (/.\G/g, for example) currently cause problems, and it is recommended that you avoid such usage for now.

The bracketing construct ( ... ) creates capture buffers. To refer to the digit'th buffer use \<digit> within the match. Outside the match use "$" instead of "\". (The \<digit> notation works in certain circumstances outside the match. See the warning below about \1 vs $1 for details.) Referring back to another part of the match is called a backreference.

There is no limit to the number of captured substrings that you may use. However Perl also uses \10, \11, etc. as aliases for \010, \011, etc. (Recall that 0 means octal, so \011 is the character at number 9 in your coded character set; which would be the 10th character, a horizontal tab under ASCII.) Perl resolves this ambiguity by interpreting \10 as a backreference only if at least 10 left parentheses have opened before it. Likewise \11 is a backreference only if at least 11 left parentheses have opened before it. And so on. \1 through \9 are always interpreted as backreferences.

Examples:

    s/^([^ ]*) *([^ ]*)/$2 $1/;     # swap first two words

     if (/(.)\1/) {                 # find first doubled char
         print "'$1' is the first doubled character\n";
     }

    if (/Time: (..):(..):(..)/) {   # parse out values
        $hours = $1;
        $minutes = $2;
        $seconds = $3;
    }

Several special variables also refer back to portions of the previous match. $+ returns whatever the last bracket match matched. $& returns the entire matched string. (At one point $0 did also, but now it returns the name of the program.) $` returns everything before the matched string. $' returns everything after the matched string. And $^N contains whatever was matched by the most-recently closed group (submatch). $^N can be used in extended patterns (see below), for example to assign a submatch to a variable.

The numbered match variables ($1, $2, $3, etc.) and the related punctuation set ($+, $&, $`, $', and $^N) are all dynamically scoped until the end of the enclosing block or until the next successful match, whichever comes first. (See Compound Statements in the perlsyn manpage.)

NOTE: failed matches in Perl do not reset the match variables, which makes it easier to write code that tests for a series of more specific cases and remembers the best match.

WARNING: Once Perl sees that you need one of $&, $`, or $' anywhere in the program, it has to provide them for every pattern match. This may substantially slow your program. Perl uses the same mechanism to produce $1, $2, etc, so you also pay a price for each pattern that contains capturing parentheses. (To avoid this cost while retaining the grouping behaviour, use the extended regular expression (?: ... ) instead.) But if you never use $&, $` or $', then patterns without capturing parentheses will not be penalized. So avoid $&, $', and $` if you can, but if you can't (and some algorithms really appreciate them), once you've used them once, use them at will, because you've already paid the price. As of 5.005, $& is not so costly as the other two.

Backslashed metacharacters in Perl are alphanumeric, such as \b, \w, \n. Unlike some other regular expression languages, there are no backslashed symbols that aren't alphanumeric. So anything that looks like \\, \(, \), \<, \>, \{, or \} is always interpreted as a literal character, not a metacharacter. This was once used in a common idiom to disable or quote the special meanings of regular expression metacharacters in a string that you want to use for a pattern. Simply quote all non-"word" characters:

    $pattern =~ s/(\W)/\\$1/g;

(If use locale is set, then this depends on the current locale.) Today it is more common to use the quotemeta() function or the \Q metaquoting escape sequence to disable all metacharacters' special meanings like this:

    /$unquoted\Q$quoted\E$unquoted/

Beware that if you put literal backslashes (those not inside interpolated variables) between \Q and \E, double-quotish backslash interpolation may lead to confusing results. If you need to use literal backslashes within \Q...\E, consult Gory details of parsing quoted constructs in the perlop manpage.

Extended Patterns

Perl also defines a consistent extension syntax for features not found in standard tools like awk and lex. The syntax is a pair of parentheses with a question mark as the first thing within the parentheses. The character after the question mark indicates the extension.

The stability of these extensions varies widely. Some have been part of the core language for many years. Others are experimental and may change without warning or be completely removed. Check the documentation on an individual feature to verify its current status.

A question mark was chosen for this and for the minimal-matching construct because 1) question marks are rare in older regular expressions, and 2) whenever you see one, you should stop and "question" exactly what is going on. That's psychology...

(?#text)

A comment. The text is ignored. If the /x modifier enables whitespace formatting, a simple # will suffice. Note that Perl closes the comment as soon as it sees a ), so there is no way to put a literal ) in the comment.

(?imsx-imsx)

One or more embedded pattern-match modifiers, to be turned on (or turned off, if preceded by -) for the remainder of the pattern or the remainder of the enclosing pattern group (if any). This is particularly useful for dynamic patterns, such as those read in from a configuration file, read in as an argument, are specified in a table somewhere, etc. Consider the case that some of which want to be case sensitive and some do not. The case insensitive ones need to include merely (?i) at the front of the pattern. For example:

    $pattern = "foobar";
    if ( /$pattern/i ) { }

    # more flexible:

    $pattern = "(?i)foobar";
    if ( /$pattern/ ) { }

These modifiers are restored at the end of the enclosing group. For example,

    ( (?i) blah ) \s+ \1

will match a repeated (including the case!) word blah in any case, assuming x modifier, and no i modifier outside this group.

(?:pattern)
(?imsx-imsx:pattern)

This is for clustering, not capturing; it groups subexpressions like "()", but doesn't make backreferences as "()" does. So

    @fields = split(/\b(?:a|b|c)\b/)

is like

    @fields = split(/\b(a|b|c)\b/)

but doesn't spit out extra fields. It's also cheaper not to capture characters if you don't need to.

Any letters between ? and : act as flags modifiers as with (?imsx-imsx). For example,

    /(?s-i:more.*than).*million/i

is equivalent to the more verbose

    /(?:(?s-i)more.*than).*million/i
(?=pattern)

A zero-width positive look-ahead assertion. For example, /\w+(?=\t)/ matches a word followed by a tab, without including the tab in $&.

(?!pattern)

A zero-width negative look-ahead assertion. For example /foo(?!bar)/ matches any occurrence of "foo" that isn't followed by "bar". Note however that look-ahead and look-behind are NOT the same thing. You cannot use this for look-behind.

If you are looking for a "bar" that isn't preceded by a "foo", /(?!foo)bar/ will not do what you want. That's because the (?!foo) is just saying that the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will match. You would have to do something like /(?!foo)...bar/ for that. We say "like" because there's the case of your "bar" not having three characters before it. You could cover that this way: /(?:(?!foo)...|^.{0,2})bar/. Sometimes it's still easier just to say:

    if (/bar/ && $` !~ /foo$/)

For look-behind see below.

(?<=pattern)

A zero-width positive look-behind assertion. For example, /(?<=\t)\w+/ matches a word that follows a tab, without including the tab in $&. Works only for fixed-width look-behind.

(?<!pattern)

A zero-width negative look-behind assertion. For example /(?<!bar)foo/ matches any occurrence of "foo" that does not follow "bar". Works only for fixed-width look-behind.

(?{ code })

WARNING: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice.

This zero-width assertion evaluates any embedded Perl code. It always succeeds, and its code is not interpolated. Currently, the rules to determine where the code ends are somewhat convoluted.

This feature can be used together with the special variable $^N to capture the results of submatches in variables without having to keep track of the number of nested parentheses. For example:

  $_ = "The brown fox jumps over the lazy dog";
  /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
  print "color = $color, animal = $animal\n";

Inside the (?{...}) block, $_ refers to the string the regular expression is matching against. You can also use pos() to know what is the current position of matching within this string.

The code is properly scoped in the following sense: If the assertion is backtracked (compare Backtracking), all changes introduced after localization are undone, so that

  $_ = 'a' x 8;
  m<
     (?{ $cnt = 0 })                    # Initialize $cnt.
     (
       a
       (?{
           local $cnt = $cnt + 1;       # Update $cnt, backtracking-safe.
       })
     )*
     aaaa
     (?{ $res = $cnt })                 # On success copy to non-localized
                                        # location.
   >x;

will set $res = 4. Note that after the match, $cnt returns to the globally introduced value, because the scopes that restrict local operators are unwound.

This assertion may be used as a (?(condition)yes-pattern|no-pattern) switch. If not used in this way, the result of evaluation of code is put into the special variable $^R. This happens immediately, so $^R can be used from other (?{ code }) assertions inside the same regular expression.

The assignment to $^R above is properly localized, so the old value of $^R is restored if the assertion is backtracked; compare Backtracking.

For reasons of security, this construct is forbidden if the regular expression involves run-time interpolation of variables, unless the perilous use re 'eval' pragma has been used (see the re manpage), or the variables contain results of qr// operator (see qr/STRING/imosx in the perlop manpage).

This restriction is because of the wide-spread and remarkably convenient custom of using run-time determined strings as patterns. For example:

    $re = <>;
    chomp $re;
    $string =~ /$re/;

Before Perl knew how to execute interpolated code within a pattern, this operation was completely safe from a security point of view, although it could raise an exception from an illegal pattern. If you turn on the use re 'eval', though, it is no longer secure, so you should only do so if you are also using taint checking. Better yet, use the carefully constrained evaluation within a Safe compartment. See the perlsec manpage for details about both these mechanisms.

(??{ code })

WARNING: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice. A simplified version of the syntax may be introduced for commonly used idioms.

This is a "postponed" regular subexpression. The code is evaluated at run time, at the moment this subexpression may match. The result of evaluation is considered as a regular expression and matched as if it were inserted instead of this construct.

The code is not interpolated. As before, the rules to determine where the code ends are currently somewhat convoluted.

The following pattern matches a parenthesized group:

  $re = qr{
             \(
             (?:
                (?> [^()]+ )    # Non-parens without backtracking
              |
                (??{ $re })     # Group with matching parens
             )*
             \)
          }x;
(?>pattern)

WARNING: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice.

An "independent" subexpression, one which matches the substring that a standalone pattern would match if anchored at the given position, and it matches nothing other than this substring. This construct is useful for optimizations of what would otherwise be "eternal" matches, because it will not backtrack (see Backtracking). It may also be useful in places where the "grab all you can, and do not give anything back" semantic is desirable.

For example: ^(?>a*)ab will never match, since (?>a*) (anchored at the beginning of string, as above) will match all characters a at the beginning of string, leaving no a for ab to match. In contrast, a*ab will match the same as a+b, since the match of the subgroup a* is influenced by the following group ab (see Backtracking). In particular, a* inside a*ab will match fewer characters than a standalone a*, since this makes the tail match.

An effect similar to (?>pattern) may be achieved by writing (?=(pattern))\1. This matches the same substring as a standalone a+, and the following \1 eats the matched string; it therefore makes a zero-length assertion into an analogue of (?>...). (The difference between these two constructs is that the second one uses a capturing group, thus shifting ordinals of backreferences in the rest of a regular expression.)

Consider this pattern:

    m{ \(
          (
            [^()]+              # x+
          |
            \( [^()]* \)
          )+
       \)
     }x

That will efficiently match a nonempty group with matching parentheses two levels deep or less. However, if there is no such group, it will take virtually forever on a long string. That's because there are so many different ways to split a long string into several substrings. This is what (.+)+ is doing, and (.+)+ is similar to a subpattern of the above pattern. Consider how the pattern above detects no-match on ((()aaaaaaaaaaaaaaaaaa in several seconds, but that each extra letter doubles this time. This exponential performance will make it appear that your program has hung. However, a tiny change to this pattern

    m{ \(
          (
            (?> [^()]+ )        # change x+ above to (?> x+ )
          |
            \( [^()]* \)
          )+
       \)
     }x

which uses (?>...) matches exactly when the one above does (verifying this yourself would be a productive exercise), but finishes in a fourth the time when used on a similar string with 1000000 as. Be aware, however, that this pattern currently triggers a warning message under the use warnings pragma or -w switch saying it "matches null string many times in regex".

On simple groups, such as the pattern (?> [^()]+ ), a comparable effect may be achieved by negative look-ahead, as in [^()]+ (?! [^()] ). This was only 4 times slower on a string with 1000000 as.

The "grab all you can, and do not give anything back" semantic is desirable in many situations where on the first sight a simple ()* looks like the correct solution. Suppose we parse text with comments being delimited by # followed by some optional (horizontal) whitespace. Contrary to its appearance, #[ \t]* is not the correct subexpression to match the comment delimiter, because it may "give up" some whitespace if the remainder of the pattern can be made to match that way. The correct answer is either one of these:

    (?>#[ \t]*)
    #[ \t]*(?![ \t])

For example, to grab non-empty comments into $1, one should use either one of these:

    / (?> \# [ \t]* ) (        .+ ) /x;
    /     \# [ \t]*   ( [^ \t] .* ) /x;

Which one you pick depends on which of these expressions better reflects the above specification of comments.

(?(condition)yes-pattern|no-pattern)
(?(condition)yes-pattern)

WARNING: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice.

Conditional expression. (condition) should be either an integer in parentheses (which is valid if the corresponding pair of parentheses matched), or look-ahead/look-behind/evaluate zero-width assertion.

For example:

    m{ ( \( )?
       [^()]+
       (?(1) \) )
     }x

matches a chunk of non-parentheses, possibly included in parentheses themselves.

Backtracking

NOTE: This section presents an abstract approximation of regular expression behavior. For a more rigorous (and complicated) view of the rules involved in selecting a match among possible alternatives, see Combining pieces together.

A fundamental feature of regular expression matching involves the notion called backtracking, which is currently used (when needed) by all regular expression quantifiers, namely *, *?, +, +?, {n,m}, and {n,m}?. Backtracking is often optimized internally, but the general principle outlined here is valid.

For a regular expression to match, the entire regular expression must match, not just part of it. So if the beginning of a pattern containing a quantifier succeeds in a way that causes later parts in the pattern to fail, the matching engine backs up and recalculates the beginning part--that's why it's called backtracking.

Here is an example of backtracking: Let's say you want to find the word following "foo" in the string "Food is on the foo table.":

    $_ = "Food is on the foo table.";
    if ( /\b(foo)\s+(\w+)/i ) {
        print "$2 follows $1.\n";
    }

When the match runs, the first part of the regular expression (\b(foo)) finds a possible match right at the beginning of the string, and loads up $1 with "Foo". However, as soon as the matching engine sees that there's no whitespace following the "Foo" that it had saved in $1, it realizes its mistake and starts over again one character after where it had the tentative match. This time it goes all the way until the next occurrence of "foo". The complete regular expression matches this time, and you get the expected output of "table follows foo."

Sometimes minimal matching can help a lot. Imagine you'd like to match everything between "foo" and "bar". Initially, you write something like this:

    $_ =  "The food is under the bar in the barn.";
    if ( /foo(.*)bar/ ) {
        print "got <$1>\n";
    }

Which perhaps unexpectedly yields:

  got <d is under the bar in the >

That's because .* was greedy, so you get everything between the first "foo" and the last "bar". Here it's more effective to use minimal matching to make sure you get the text between a "foo" and the first "bar" thereafter.

    if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
      got <d is under the >

Here's another example: let's say you'd like to match a number at the end of a string, and you also want to keep the preceding part of the match. So you write this:

    $_ = "I have 2 numbers: 53147";
    if ( /(.*)(\d*)/ ) {                                # Wrong!
        print "Beginning is <$1>, number is <$2>.\n";
    }

That won't work at all, because .* was greedy and gobbled up the whole string. As \d* can match on an empty string the complete regular expression matched successfully.

    Beginning is <I have 2 numbers: 53147>, number is <>.

Here are some variants, most of which don't work:

    $_ = "I have 2 numbers: 53147";
    @pats = qw{
        (.*)(\d*)
        (.*)(\d+)
        (.*?)(\d*)
        (.*?)(\d+)
        (.*)(\d+)$
        (.*?)(\d+)$
        (.*)\b(\d+)$
        (.*\D)(\d+)$
    };

    for $pat (@pats) {
        printf "%-12s ", $pat;
        if ( /$pat/ ) {
            print "<$1> <$2>\n";
        } else {
            print "FAIL\n";
        }
    }

That will print out:

    (.*)(\d*)    <I have 2 numbers: 53147> <>
    (.*)(\d+)    <I have 2 numbers: 5314> <7>
    (.*?)(\d*)   <> <>
    (.*?)(\d+)   <I have > <2>
    (.*)(\d+)$   <I have 2 numbers: 5314> <7>
    (.*?)(\d+)$  <I have 2 numbers: > <53147>
    (.*)\b(\d+)$ <I have 2 numbers: > <53147>
    (.*\D)(\d+)$ <I have 2 numbers: > <53147>

As you see, this can be a bit tricky. It's important to realize that a regular expression is merely a set of assertions that gives a definition of success. There may be 0, 1, or several different ways that the definition might succeed against a particular string. And if there are multiple ways it might succeed, you need to understand backtracking to know which variety of success you will achieve.

When using look-ahead assertions and negations, this can all get even trickier. Imagine you'd like to find a sequence of non-digits not followed by "123". You might try to write that as

    $_ = "ABC123";
    if ( /^\D*(?!123)/ ) {              # Wrong!
        print "Yup, no 123 in $_\n";
    }

But that isn't going to match; at least, not the way you're hoping. It claims that there is no 123 in the string. Here's a clearer picture of why that pattern matches, contrary to popular expectations:

    $x = 'ABC123';
    $y = 'ABC445';

    print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
    print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;

    print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
    print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;

This prints

    2: got ABC
    3: got AB
    4: got ABC

You might have expected test 3 to fail because it seems to a more general purpose version of test 1. The important difference between them is that test 3 contains a quantifier (\D*) and so can use backtracking, whereas test 1 will not. What's happening is that you've asked "Is it true that at the start of $x, following 0 or more non-digits, you have something that's not 123?" If the pattern matcher had let \D* expand to "ABC", this would have caused the whole pattern to fail.

The search engine will initially match \D* with "ABC". Then it will try to match (?!123 with "123", which fails. But because a quantifier (\D*) has been used in the regular expression, the search engine can backtrack and retry the match differently in the hope of matching the complete regular expression.

The pattern really, really wants to succeed, so it uses the standard pattern back-off-and-retry and lets \D* expand to just "AB" this time. Now there's indeed something following "AB" that is not "123". It's "C123", which suffices.

We can deal with this by using both an assertion and a negation. We'll say that the first part in $1 must be followed both by a digit and by something that's not "123". Remember that the look-aheads are zero-width expressions--they only look, but don't consume any of the string in their match. So rewriting this way produces what you'd expect; that is, case 5 will fail, but case 6 succeeds:

    print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/;
    print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;

    6: got ABC

In other words, the two zero-width assertions next to each other work as though they're ANDed together, just as you'd use any built-in assertions: /^$/ matches only if you're at the beginning of the line AND the end of the line simultaneously. The deeper underlying truth is that juxtaposition in regular expressions always means AND, except when you write an explicit OR using the vertical bar. /ab/ means match "a" AND (then) match "b", although the attempted matches are made at different positions because "a" is not a zero-width assertion, but a one-width assertion.

WARNING: particularly complicated regular expressions can take exponential time to solve because of the immense number of possible ways they can use backtracking to try match. For example, without internal optimizations done by the regular expression engine, this will take a painfully long time to run:

    'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/

And if you used *'s in the internal groups instead of limiting them to 0 through 5 matches, then it would take forever--or until you ran out of stack space. Moreover, these internal optimizations are not always applicable. For example, if you put {0,5} instead of * on the external group, no current optimization is applicable, and the match takes a long time to finish.

A powerful tool for optimizing such beasts is what is known as an "independent group", which does not backtrack (see < (?>pattern) >). Note also that zero-length look-ahead/look-behind assertions will not backtrack to make the tail match, since they are in "logical" context: only whether they match is considered relevant. For an example where side-effects of look-ahead might have influenced the following match, see < (?>pattern) >.

Version 8 Regular Expressions

In case you're not familiar with the "regular" Version 8 regex routines, here are the pattern-matching rules not described above.

Any single character matches itself, unless it is a metacharacter with a special meaning described here or above. You can cause characters that normally function as metacharacters to be interpreted literally by prefixing them with a "\" (e.g., "\." matches a ".", not any character; "\\" matches a "\"). A series of characters matches that series of characters in the target string, so the pattern blurfl would match "blurfl" in the target string.

You can specify a character class, by enclosing a list of characters in [], which will match any one character from the list. If the first character after the "[" is "^", the class matches any character not in the list. Within a list, the "-" character specifies a range, so that a-z represents all characters between "a" and "z", inclusive. If you want either "-" or "]" itself to be a member of a class, put it at the start of the list (possibly after a "^"), or escape it with a backslash. "-" is also taken literally when it is at the end of the list, just before the closing "]". (The following all specify the same class of three characters: [-az], [az-], and [a\-z]. All are different from [a-z], which specifies a class containing twenty-six characters, even on EBCDIC based coded character sets.) Also, if you try to use the character classes \w, \W, \s, \S, \d, or \D as endpoints of a range, that's not a range, the "-" is understood literally.

Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results you probably didn't expect. A sound principle is to use only ranges that begin from and end at either alphabets of equal case ([a-e], [A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt, spell out the character sets in full.

Characters may be specified using a metacharacter syntax much like that used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return, "\f" a form feed, etc. More generally, \nnn, where nnn is a string of octal digits, matches the character whose coded character set value is nnn. Similarly, \xnn, where nn are hexadecimal digits, matches the character whose numeric value is nn. The expression \cx matches the character control-x. Finally, the "." metacharacter matches any character except "\n" (unless you use /s).

You can specify a series of alternatives for a pattern using "|" to separate them, so that fee|fie|foe will match any of "fee", "fie", or "foe" in the target string (as would f(e|i|o)e). The first alternative includes everything from the last pattern delimiter ("(", "[", or the beginning of the pattern) up to the first "|", and the last alternative contains everything from the last "|" to the next pattern delimiter. That's why it's common practice to include alternatives in parentheses: to minimize confusion about where they start and end.

Alternatives are tried from left to right, so the first alternative found for which the entire expression matches, is the one that is chosen. This means that alternatives are not necessarily greedy. For example: when matching foo|foot against "barefoot", only the "foo" part will match, as that is the first alternative tried, and it successfully matches the target string. (This might not seem important, but it is important when you are capturing matched text using parentheses.)

Also remember that "|" is interpreted as a literal within square brackets, so if you write [fee|fie|foe] you're really only matching [feio|].

Within a pattern, you may designate subpatterns for later reference by enclosing them in parentheses, and you may refer back to the nth subpattern later in the pattern using the metacharacter \n. Subpatterns are numbered based on the left to right order of their opening parenthesis. A backreference matches whatever actually matched the subpattern in the string being examined, not the rules for that subpattern. Therefore, (0|0x)\d*\s\1\d* will match "0x1234 0x4321", but not "0x1234 01234", because subpattern 1 matched "0x", even though the rule 0|0x could potentially match the leading 0 in the second number.

Warning on \1 vs $1

Some people get too used to writing things like:

    $pattern =~ s/(\W)/\\\1/g;

This is grandfathered for the RHS of a substitute to avoid shocking the sed addicts, but it's a dirty habit to get into. That's because in PerlThink, the righthand side of an s/// is a double-quoted string. \1 in the usual double-quoted string means a control-A. The customary Unix meaning of \1 is kludged in for s///. However, if you get into the habit of doing that, you get yourself into trouble if you then add an /e modifier.

    s/(\d+)/ \1 + 1 /eg;        # causes warning under -w

Or if you try to do

    s/(\d+)/\1000/;

You can't disambiguate that by saying \{1}000, whereas you can fix it with ${1}000. The operation of interpolation should not be confused with the operation of matching a backreference. Certainly they mean two different things on the left side of the s///.

Repeated patterns matching zero-length substring

WARNING: Difficult material (and prose) ahead. This section needs a rewrite.

Regular expressions provide a terse and powerful programming language. As with most other power tools, power comes together with the ability to wreak havoc.

A common abuse of this power stems from the ability to make infinite loops using regular expressions, with something as innocuous as:

    'foo' =~ m{ ( o? )* }x;

The o? can match at the beginning of 'foo', and since the position in the string is not moved by the match, o? would match again and again because of the * modifier. Another common way to create a similar cycle is with the looping modifier //g:

    @matches = ( 'foo' =~ m{ o? }xg );

or

    print "match: <$&>\n" while 'foo' =~ m{ o? }xg;

or the loop implied by split().

However, long experience has shown that many programming tasks may be significantly simplified by using repeated subexpressions that may match zero-length substrings. Here's a simple example being:

    @chars = split //, $string;           # // is not magic in split
    ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /

Thus Perl allows such constructs, by forcefully breaking the infinite loop. The rules for this are different for lower-level loops given by the greedy modifiers *+{}, and for higher-level ones like the /g modifier or split() operator.

The lower-level loops are interrupted (that is, the loop is broken) when Perl detects that a repeated expression matched a zero-length substring. Thus

   m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;

is made equivalent to

   m{   (?: NON_ZERO_LENGTH )*
      |
        (?: ZERO_LENGTH )?
    }x;

The higher level-loops preserve an additional state between iterations: whether the last match was zero-length. To break the loop, the following match after a zero-length match is prohibited to have a length of zero. This prohibition interacts with backtracking (see Backtracking), and so the second best match is chosen if the best match is of zero length.

For example:

    $_ = 'bar';
    s/\w??/<$&>/g;

results in <><b><><a><><r><>. At each position of the string the best match given by non-greedy ?? is the zero-length match, and the second best match is what is matched by \w. Thus zero-length matches alternate with one-character-long matches.

Similarly, for repeated m/()/g the second-best match is the match at the position one notch further in the string.

The additional state of being matched with zero-length is associated with the matched string, and is reset by each assignment to pos(). Zero-length matches at the end of the previous match are ignored during split.

Combining pieces together

Each of the elementary pieces of regular expressions which were described before (such as ab or \Z) could match at most one substring at the given position of the input string. However, in a typical regular expression these elementary pieces are combined into more complicated patterns using combining operators ST, S|T, S* etc (in these examples S and T are regular subexpressions).

Such combinations can include alternatives, leading to a problem of choice: if we match a regular expression a|ab against "abc", will it match substring "a" or "ab"? One way to describe which substring is actually matched is the concept of backtracking (see Backtracking). However, this description is too low-level and makes you think in terms of a particular implementation.

Another description starts with notions of "better"/"worse". All the substrings which may be matched by the given regular expression can be sorted from the "best" match to the "worst" match, and it is the "best" match which is chosen. This substitutes the question of "what is chosen?" by the question of "which matches are better, and which are worse?".

Again, for elementary pieces there is no such question, since at most one match at a given position is possible. This section describes the notion of better/worse for combining operators. In the description below S and T are regular subexpressions.

ST

Consider two possible matches, AB and A'B', A and A' are substrings which can be matched by S, B and B' are substrings which can be matched by T.

If A is better match for S than A', AB is a better match than A'B'.

If A and A' coincide: AB is a better match than AB' if B is better match for T than B'.

S|T

When S can match, it is a better match than when only T can match.

Ordering of two matches for S is the same as for S. Similar for two matches for T.

S{REPEAT_COUNT}

Matches as SSS...S (repeated as many times as necessary).

S{min,max}

Matches as S{max}|S{max-1}|...|S{min+1}|S{min}.

S{min,max}?

Matches as S{min}|S{min+1}|...|S{max-1}|S{max}.

S?, S*, S+

Same as S{0,1}, S{0,BIG_NUMBER}, S{1,BIG_NUMBER} respectively.

S??, S*?, S+?

Same as S{0,1}?, S{0,BIG_NUMBER}?, S{1,BIG_NUMBER}? respectively.

(?>S)

Matches the best match for S and only that.

(?=S), (?<=S)

Only the best match for S is considered. (This is important only if S has capturing parentheses, and backreferences are used somewhere else in the whole regular expression.)

(?!S), (?<!S)

For this grouping operator there is no need to describe the ordering, since only whether or not S can match is important.

(??{ EXPR })

The ordering is the same as for the regular expression which is the result of EXPR.

(?(condition)yes-pattern|no-pattern)

Recall that which of yes-pattern or no-pattern actually matches is already determined. The ordering of the matches is the same as for the chosen subexpression.

The above recipes describe the ordering of matches at a given position. One more rule is needed to understand how a match is determined for the whole regular expression: a match at an earlier position is always better than a match at a later position.

Creating custom RE engines

Overloaded constants (see the overload manpage) provide a simple way to extend the functionality of the RE engine.

Suppose that we want to enable a new RE escape-sequence \Y| which matches at boundary between whitespace characters and non-whitespace characters. Note that (?=\S)(?<!\S)|(?!\S)(?<=\S) matches exactly at these positions, so we want to have each \Y| in the place of the more complicated version. We can create a module customre to do this:

    package customre;
    use overload;

    sub import {
      shift;
      die "No argument to customre::import allowed" if @_;
      overload::constant 'qr' => \&convert;
    }

    sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}

    # We must also take care of not escaping the legitimate \\Y|
    # sequence, hence the presence of '\\' in the conversion rules.
    my %rules = ( '\\' => '\\\\',
                  'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
    sub convert {
      my $re = shift;
      $re =~ s{
                \\ ( \\ | Y . )
              }
              { $rules{$1} or invalid($re,$1) }sgex;
      return $re;
    }

Now use customre enables the new escape in constant regular expressions, i.e., those without any runtime variable interpolations. As documented in the overload manpage, this conversion will work only over literal parts of regular expressions. For \Y|$re\Y| the variable part of this regular expression needs to be converted explicitly (but only if the special meaning of \Y| should be enabled inside $re):

    use customre;
    $re = <>;
    chomp $re;
    $re = customre::convert $re;
    /\Y|$re\Y|/;

BUGS

This document varies from difficult to understand to completely and utterly opaque. The wandering prose riddled with jargon is hard to fathom in several places.

This document needs a rewrite that separates the tutorial content from the reference content.

SEE ALSO

the perlrequick manpage.

the perlretut manpage.

Regexp Quote-Like Operators in the perlop manpage.

Gory details of parsing quoted constructs in the perlop manpage.

the perlfaq6 manpage.

pos in the perlfunc manpage.

the perllocale manpage.

the perlebcdic manpage.

Mastering Regular Expressions by Jeffrey Friedl, published by O'Reilly and Associates.


perlrequick - Perl regular expressions quick start

  • The Guide
    • Simple word matching
    • Using character classes
    • Matching this or that
    • Grouping things and hierarchical matching
    • Extracting matches
    • Matching repetitions
    • More matching
    • Search and replace
    • The split operator
  • BUGS
  • SEE ALSO
  • AUTHOR AND COPYRIGHT
    • Acknowledgments

NAME

perlrequick - Perl regular expressions quick start

DESCRIPTION

This page covers the very basics of understanding, creating and using regular expressions ('regexes') in Perl.

The Guide

Simple word matching

The simplest regex is simply a word, or more generally, a string of characters. A regex consisting of a word matches any string that contains that word:

    "Hello World" =~ /World/;  # matches

In this statement, World is a regex and the // enclosing /World/ tells perl to search a string for a match. The operator =~ associates the string with the regex match and produces a true value if the regex matched, or false if the regex did not match. In our case, World matches the second word in "Hello World", so the expression is true. This idea has several variations.

Expressions like this are useful in conditionals:

    print "It matches\n" if "Hello World" =~ /World/;

The sense of the match can be reversed by using !~ operator:

    print "It doesn't match\n" if "Hello World" !~ /World/;

The literal string in the regex can be replaced by a variable:

    $greeting = "World";
    print "It matches\n" if "Hello World" =~ /$greeting/;

If you're matching against $_, the $_ =~ part can be omitted:

    $_ = "Hello World";
    print "It matches\n" if /World/;

Finally, the // default delimiters for a match can be changed to arbitrary delimiters by putting an 'm' out front:

    "Hello World" =~ m!World!;   # matches, delimited by '!'
    "Hello World" =~ m{World};   # matches, note the matching '{}'
    "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
                                 # '/' becomes an ordinary char

Regexes must match a part of the string exactly in order for the statement to be true:

    "Hello World" =~ /world/;  # doesn't match, case sensitive
    "Hello World" =~ /o W/;    # matches, ' ' is an ordinary char
    "Hello World" =~ /World /; # doesn't match, no ' ' at end

perl will always match at the earliest possible point in the string:

    "Hello World" =~ /o/;       # matches 'o' in 'Hello'
    "That hat is red" =~ /hat/; # matches 'hat' in 'That'

Not all characters can be used 'as is' in a match. Some characters, called metacharacters, are reserved for use in regex notation. The metacharacters are

    {}[]()^$.|*+?\

A metacharacter can be matched by putting a backslash before it:

    "2+2=4" =~ /2+2/;    # doesn't match, + is a metacharacter
    "2+2=4" =~ /2\+2/;   # matches, \+ is treated like an ordinary +
    'C:\WIN32' =~ /C:\\WIN/;                       # matches
    "/usr/bin/perl" =~ /\/usr\/bin\/perl/;  # matches

In the last regex, the forward slash '/' is also backslashed, because it is used to delimit the regex.

Non-printable ASCII characters are represented by escape sequences. Common examples are \t for a tab, \n for a newline, and \r for a carriage return. Arbitrary bytes are represented by octal escape sequences, e.g., \033, or hexadecimal escape sequences, e.g., \x1B:

    "1000\t2000" =~ m(0\t2)        # matches
    "cat"        =~ /\143\x61\x74/ # matches, but a weird way to spell cat

Regexes are treated mostly as double quoted strings, so variable substitution works:

    $foo = 'house';
    'cathouse' =~ /cat$foo/;   # matches
    'housecat' =~ /${foo}cat/; # matches

With all of the regexes above, if the regex matched anywhere in the string, it was considered a match. To specify where it should match, we would use the anchor metacharacters ^ and $. The anchor ^ means match at the beginning of the string and the anchor $ means match at the end of the string, or before a newline at the end of the string. Some examples:

    "housekeeper" =~ /keeper/;         # matches
    "housekeeper" =~ /^keeper/;        # doesn't match
    "housekeeper" =~ /keeper$/;        # matches
    "housekeeper\n" =~ /keeper$/;      # matches
    "housekeeper" =~ /^housekeeper$/;  # matches

Using character classes

A character class allows a set of possible characters, rather than just a single character, to match at a particular point in a regex. Character classes are denoted by brackets [...], with the set of characters to be possibly matched inside. Here are some examples:

    /cat/;            # matches 'cat'
    /[bcr]at/;        # matches 'bat', 'cat', or 'rat'
    "abc" =~ /[cab]/; # matches 'a'

In the last statement, even though 'c' is the first character in the class, the earliest point at which the regex can match is 'a'.

    /[yY][eE][sS]/; # match 'yes' in a case-insensitive way
                    # 'yes', 'Yes', 'YES', etc.
    /yes/i;         # also match 'yes' in a case-insensitive way

The last example shows a match with an 'i' modifier, which makes the match case-insensitive.

Character classes also have ordinary and special characters, but the sets of ordinary and special characters inside a character class are different than those outside a character class. The special characters for a character class are -]\^$ and are matched using an escape:

   /[\]c]def/; # matches ']def' or 'cdef'
   $x = 'bcr';
   /[$x]at/;   # matches 'bat, 'cat', or 'rat'
   /[\$x]at/;  # matches '$at' or 'xat'
   /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'

The special character '-' acts as a range operator within character classes, so that the unwieldy [0123456789] and [abc...xyz] become the svelte [0-9] and [a-z]:

    /item[0-9]/;  # matches 'item0' or ... or 'item9'
    /[0-9a-fA-F]/;  # matches a hexadecimal digit

If '-' is the first or last character in a character class, it is treated as an ordinary character.

The special character ^ in the first position of a character class denotes a negated character class, which matches any character but those in the brackets. Both [...] and [^...] must match a character, or the match fails. Then

    /[^a]at/;  # doesn't match 'aat' or 'at', but matches
               # all other 'bat', 'cat, '0at', '%at', etc.
    /[^0-9]/;  # matches a non-numeric character
    /[a^]at/;  # matches 'aat' or '^at'; here '^' is ordinary

Perl has several abbreviations for common character classes:

  • \d is a digit and represents

        [0-9]

  • \s is a whitespace character and represents

        [\ \t\r\n\f]

  • \w is a word character (alphanumeric or _) and represents

        [0-9a-zA-Z_]

  • \D is a negated \d; it represents any character but a digit

        [^0-9]

  • \S is a negated \s; it represents any non-whitespace character

        [^\s]

  • \W is a negated \w; it represents any non-word character

        [^\w]

  • The period '.' matches any character but "\n"

The \d\s\w\D\S\W abbreviations can be used both inside and outside of character classes. Here are some in use:

    /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
    /[\d\s]/;         # matches any digit or whitespace character
    /\w\W\w/;         # matches a word char, followed by a
                      # non-word char, followed by a word char
    /..rt/;           # matches any two chars, followed by 'rt'
    /end\./;          # matches 'end.'
    /end[.]/;         # same thing, matches 'end.'

The word anchor \b matches a boundary between a word character and a non-word character \w\W or \W\w:

    $x = "Housecat catenates house and cat";
    $x =~ /\bcat/;  # matches cat in 'catenates'
    $x =~ /cat\b/;  # matches cat in 'housecat'
    $x =~ /\bcat\b/;  # matches 'cat' at end of string

In the last example, the end of the string is considered a word boundary.

Matching this or that

We can match different character strings with the alternation metacharacter '|'. To match dog or cat, we form the regex dog|cat. As before, perl will try to match the regex at the earliest possible point in the string. At each character position, perl will first try to match the first alternative, dog. If dog doesn't match, perl will then try the next alternative, cat. If cat doesn't match either, then the match fails and perl moves to the next position in the string. Some examples:

    "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
    "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"

Even though dog is the first alternative in the second regex, cat is able to match earlier in the string.

    "cats"          =~ /c|ca|cat|cats/; # matches "c"
    "cats"          =~ /cats|cat|ca|c/; # matches "cats"

At a given character position, the first alternative that allows the regex match to succeed will be the one that matches. Here, all the alternatives match at the first string position, so the first matches.

Grouping things and hierarchical matching

The grouping metacharacters () allow a part of a regex to be treated as a single unit. Parts of a regex are grouped by enclosing them in parentheses. The regex house(cat|keeper) means match house followed by either cat or keeper. Some more examples are

    /(a|b)b/;    # matches 'ab' or 'bb'
    /(^a|b)c/;   # matches 'ac' at start of string or 'bc' anywhere

    /house(cat|)/;  # matches either 'housecat' or 'house'
    /house(cat(s|)|)/;  # matches either 'housecats' or 'housecat' or
                        # 'house'.  Note groups can be nested.

    "20" =~ /(19|20|)\d\d/;  # matches the null alternative '()\d\d',
                             # because '20\d\d' can't match

Extracting matches

The grouping metacharacters () also allow the extraction of the parts of a string that matched. For each grouping, the part that matched inside goes into the special variables $1, $2, etc. They can be used just as ordinary variables:

    # extract hours, minutes, seconds
    $time =~ /(\d\d):(\d\d):(\d\d)/;  # match hh:mm:ss format
    $hours = $1;
    $minutes = $2;
    $seconds = $3;

In list context, a match /regex/ with groupings will return the list of matched values ($1,$2,...). So we could rewrite it as

    ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);

If the groupings in a regex are nested, $1 gets the group with the leftmost opening parenthesis, $2 the next opening parenthesis, etc. For example, here is a complex regex and the matching variables indicated below it:

    /(ab(cd|ef)((gi)|j))/;
     1  2      34

Associated with the matching variables $1, $2, ... are the backreferences \1, \2, ... Backreferences are matching variables that can be used inside a regex:

    /(\w\w\w)\s\1/; # find sequences like 'the the' in string

$1, $2, ... should only be used outside of a regex, and \1, \2, ... only inside a regex.

Matching repetitions

The quantifier metacharacters ?, *, +, and {} allow us to determine the number of repeats of a portion of a regex we consider to be a match. Quantifiers are put immediately after the character, character class, or grouping that we want to specify. They have the following meanings:

  • a? = match 'a' 1 or 0 times

  • a* = match 'a' 0 or more times, i.e., any number of times

  • a+ = match 'a' 1 or more times, i.e., at least once

  • a{n,m} = match at least n times, but not more than m times.

  • a{n,} = match at least n or more times

  • a{n} = match exactly n times

Here are some examples:

    /[a-z]+\s+\d*/;  # match a lowercase word, at least some space, and
                     # any number of digits
    /(\w+)\s+\1/;    # match doubled words of arbitrary length
    $year =~ /\d{2,4}/;  # make sure year is at least 2 but not more
                         # than 4 digits
    $year =~ /\d{4}|\d{2}/;    # better match; throw out 3 digit dates

These quantifiers will try to match as much of the string as possible, while still allowing the regex to match. So we have

    $x = 'the cat in the hat';
    $x =~ /^(.*)(at)(.*)$/; # matches,
                            # $1 = 'the cat in the h'
                            # $2 = 'at'
                            # $3 = ''   (0 matches)

The first quantifier .* grabs as much of the string as possible while still having the regex match. The second quantifier .* has no string left to it, so it matches 0 times.

More matching

There are a few more things you might want to know about matching operators. In the code

    $pattern = 'Seuss';
    while (<>) {
        print if /$pattern/;
    }

perl has to re-evaluate $pattern each time through the loop. If $pattern won't be changing, use the //o modifier, to only perform variable substitutions once. If you don't want any substitutions at all, use the special delimiter m'':

    @pattern = ('Seuss');
    m/@pattern/; # matches 'Seuss'
    m'@pattern'; # matches the literal string '@pattern'

The global modifier //g allows the matching operator to match within a string as many times as possible. In scalar context, successive matches against a string will have //g jump from match to match, keeping track of position in the string as it goes along. You can get or set the position with the pos() function. For example,

    $x = "cat dog house"; # 3 words
    while ($x =~ /(\w+)/g) {
        print "Word is $1, ends at position ", pos $x, "\n";
    }

prints

    Word is cat, ends at position 3
    Word is dog, ends at position 7
    Word is house, ends at position 13

A failed match or changing the target string resets the position. If you don't want the position reset after failure to match, add the //c, as in /regex/gc.

In list context, //g returns a list of matched groupings, or if there are no groupings, a list of matches to the whole regex. So

    @words = ($x =~ /(\w+)/g);  # matches,
                                # $word[0] = 'cat'
                                # $word[1] = 'dog'
                                # $word[2] = 'house'

Search and replace

Search and replace is performed using s/regex/replacement/modifiers. The replacement is a Perl double quoted string that replaces in the string whatever is matched with the regex. The operator =~ is also used here to associate a string with s///. If matching against $_, the $_ =~ can be dropped. If there is a match, s/// returns the number of substitutions made, otherwise it returns false. Here are a few examples:

    $x = "Time to feed the cat!";
    $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
    $y = "'quoted words'";
    $y =~ s/^'(.*)'$/$1/;  # strip single quotes,
                           # $y contains "quoted words"

With the s/// operator, the matched variables $1, $2, etc. are immediately available for use in the replacement expression. With the global modifier, s///g will search and replace all occurrences of the regex in the string:

    $x = "I batted 4 for 4";
    $x =~ s/4/four/;   # $x contains "I batted four for 4"
    $x = "I batted 4 for 4";
    $x =~ s/4/four/g;  # $x contains "I batted four for four"

The evaluation modifier s///e wraps an eval{...} around the replacement string and the evaluated result is substituted for the matched substring. Some examples:

    # reverse all the words in a string
    $x = "the cat in the hat";
    $x =~ s/(\w+)/reverse $1/ge;   # $x contains "eht tac ni eht tah"

    # convert percentage to decimal
    $x = "A 39% hit rate";
    $x =~ s!(\d+)%!$1/100!e;       # $x contains "A 0.39 hit rate"

The last example shows that s/// can use other delimiters, such as s!!! and s{}{}, and even s{}//. If single quotes are used s''', then the regex and replacement are treated as single quoted strings.

The split operator

split /regex/, string splits string into a list of substrings and returns that list. The regex determines the character sequence that string is split with respect to. For example, to split a string into words, use

    $x = "Calvin and Hobbes";
    @word = split /\s+/, $x;  # $word[0] = 'Calvin'
                              # $word[1] = 'and'
                              # $word[2] = 'Hobbes'

To extract a comma-delimited list of numbers, use

    $x = "1.618,2.718,   3.142";
    @const = split /,\s*/, $x;  # $const[0] = '1.618'
                                # $const[1] = '2.718'
                                # $const[2] = '3.142'

If the empty regex // is used, the string is split into individual characters. If the regex has groupings, then the list produced contains the matched substrings from the groupings as well:

    $x = "/usr/bin";
    @parts = split m!(/)!, $x;  # $parts[0] = ''
                                # $parts[1] = '/'
                                # $parts[2] = 'usr'
                                # $parts[3] = '/'
                                # $parts[4] = 'bin'

Since the first character of $x matched the regex, split prepended an empty initial element to the list.

BUGS

None.

SEE ALSO

This is just a quick start guide. For a more in-depth tutorial on regexes, see the perlretut manpage and for the reference page, see the perlre manpage.

AUTHOR AND COPYRIGHT

Copyright (c) 2000 Mark Kvale All rights reserved.

This document may be distributed under the same terms as Perl itself.

Acknowledgments

The author would like to thank Mark-Jason Dominus, Tom Christiansen, Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful comments.


perlreref - Perl Regular Expressions Reference

    • OPERATORS
    • SYNTAX
    • ESCAPE SEQUENCES
    • CHARACTER CLASSES
    • ANCHORS
    • QUANTIFIERS
    • EXTENDED CONSTRUCTS
    • VARIABLES
    • FUNCTIONS
    • TERMINOLOGY
      • Titlecase
  • AUTHOR
  • SEE ALSO
  • THANKS

NAME

perlreref - Perl Regular Expressions Reference

DESCRIPTION

This is a quick reference to Perl's regular expressions. For full information see the perlre manpage and the perlop manpage, as well as the SEE ALSO section in this document.

OPERATORS

  =~ determines to which variable the regex is applied.
     In its absence, $_ is used.
        $var =~ /foo/;

  !~ determines to which variable the regex is applied,
     and negates the result of the match; it returns
     false if the match succeeds, and true if it fails.

       $var !~ /foo/;

  m/pattern/igmsoxc searches a string for a pattern match,
     applying the given options.
        i  case-Insensitive
        g  Global - all occurrences
        m  Multiline mode - ^ and $ match internal lines
        s  match as a Single line - . matches \n
        o  compile pattern Once
        x  eXtended legibility - free whitespace and comments
        c  don't reset pos on failed matches when using /g
     If 'pattern' is an empty string, the last I<successfully> matched
     regex is used. Delimiters other than '/' may be used for both this
     operator and the following ones.
  qr/pattern/imsox lets you store a regex in a variable,
     or pass one around. Modifiers as for m// and are stored
     within the regex.
  s/pattern/replacement/igmsoxe substitutes matches of
     'pattern' with 'replacement'. Modifiers as for m//
     with one addition:
        e  Evaluate replacement as an expression
     'e' may be specified multiple times. 'replacement' is interpreted
     as a double quoted string unless a single-quote (') is the delimiter.
  ?pattern? is like m/pattern/ but matches only once. No alternate
      delimiters can be used. Must be reset with L<reset|perlfunc/reset>.

SYNTAX

   \       Escapes the character immediately following it
   .       Matches any single character except a newline (unless /s is used)
   ^       Matches at the beginning of the string (or line, if /m is used)
   $       Matches at the end of the string (or line, if /m is used)
   *       Matches the preceding element 0 or more times
   +       Matches the preceding element 1 or more times
   ?       Matches the preceding element 0 or 1 times
   {...}   Specifies a range of occurrences for the element preceding it
   [...]   Matches any one of the characters contained within the brackets
   (...)   Groups subexpressions for capturing to $1, $2...
   (?:...) Groups subexpressions without capturing (cluster)
   |       Matches either the subexpression preceding or following it
   \1, \2 ...  The text from the Nth group

ESCAPE SEQUENCES

These work as in normal strings.

   \a       Alarm (beep)
   \e       Escape
   \f       Formfeed
   \n       Newline
   \r       Carriage return
   \t       Tab
   \037     Any octal ASCII value
   \x7f     Any hexadecimal ASCII value
   \x{263a} A wide hexadecimal value
   \cx      Control-x
   \N{name} A named character

   \l  Lowercase next character
   \u  Titlecase next character
   \L  Lowercase until \E
   \U  Uppercase until \E
   \Q  Disable pattern metacharacters until \E
   \E  End case modification

For Titlecase, see Titlecase.

This one works differently from normal strings:

   \b  An assertion, not backspace, except in a character class

CHARACTER CLASSES

   [amy]    Match 'a', 'm' or 'y'
   [f-j]    Dash specifies "range"
   [f-j-]   Dash escaped or at start or end means 'dash'
   [^f-j]   Caret indicates "match any character _except_ these"

The following sequences work within or without a character class. The first six are locale aware, all are Unicode aware. The default character class equivalent are given. See the perllocale manpage and the perlunicode manpage for details.

   \d      A digit                     [0-9]
   \D      A nondigit                  [^0-9]
   \w      A word character            [a-zA-Z0-9_]
   \W      A non-word character        [^a-zA-Z0-9_]
   \s      A whitespace character      [ \t\n\r\f]
   \S      A non-whitespace character  [^ \t\n\r\f]
   \C      Match a byte (with Unicode, '.' matches a character)
   \pP     Match P-named (Unicode) property
   \p{...} Match Unicode property with long name
   \PP     Match non-P
   \P{...} Match lack of Unicode property with long name
   \X      Match extended unicode sequence

POSIX character classes and their Unicode and Perl equivalents:

   alnum   IsAlnum              Alphanumeric
   alpha   IsAlpha              Alphabetic
   ascii   IsASCII              Any ASCII char
   blank   IsSpace  [ \t]       Horizontal whitespace (GNU extension)
   cntrl   IsCntrl              Control characters
   digit   IsDigit  \d          Digits
   graph   IsGraph              Alphanumeric and punctuation
   lower   IsLower              Lowercase chars (locale and Unicode aware)
   print   IsPrint              Alphanumeric, punct, and space
   punct   IsPunct              Punctuation
   space   IsSpace  [\s\ck]     Whitespace
           IsSpacePerl   \s     Perl's whitespace definition
   upper   IsUpper              Uppercase chars (locale and Unicode aware)
   word    IsWord   \w          Alphanumeric plus _ (Perl extension)
   xdigit  IsXDigit [0-9A-Fa-f] Hexadecimal digit

Within a character class:

    POSIX       traditional   Unicode
    [:digit:]       \d        \p{IsDigit}
    [:^digit:]      \D        \P{IsDigit}

ANCHORS

All are zero-width assertions.

   ^  Match string start (or line, if /m is used)
   $  Match string end (or line, if /m is used) or before newline
   \b Match word boundary (between \w and \W)
   \B Match except at word boundary (between \w and \w or \W and \W)
   \A Match string start (regardless of /m)
   \Z Match string end (before optional newline)
   \z Match absolute string end
   \G Match where previous m//g left off

QUANTIFIERS

Quantifiers are greedy by default -- match the longest leftmost.

   Maximal Minimal Allowed range
   ------- ------- -------------
   {n,m}   {n,m}?  Must occur at least n times but no more than m times
   {n,}    {n,}?   Must occur at least n times
   {n}     {n}?    Must occur exactly n times
   *       *?      0 or more times (same as {0,})
   +       +?      1 or more times (same as {1,})
   ?       ??      0 or 1 time (same as {0,1})

There is no quantifier {,n} -- that gets understood as a literal string.

EXTENDED CONSTRUCTS

   (?#text)         A comment
   (?imxs-imsx:...) Enable/disable option (as per m// modifiers)
   (?=...)          Zero-width positive lookahead assertion
   (?!...)          Zero-width negative lookahead assertion
   (?<=...)         Zero-width positive lookbehind assertion
   (?<!...)         Zero-width negative lookbehind assertion
   (?>...)          Grab what we can, prohibit backtracking
   (?{ code })      Embedded code, return value becomes $^R
   (??{ code })     Dynamic regex, return value used as regex
   (?(cond)yes|no)  cond being integer corresponding to capturing parens
   (?(cond)yes)        or a lookaround/eval zero-width assertion

VARIABLES

   $_    Default variable for operators to use
   $*    Enable multiline matching (deprecated; not in 5.9.0 or later)

   $&    Entire matched string
   $`    Everything prior to matched string
   $'    Everything after to matched string

The use of those last three will slow down all regex use within your program. Consult the perlvar manpage for @LAST_MATCH_START to see equivalent expressions that won't cause slow down. See also the Devel::SawAmpersand manpage.

   $1, $2 ...  hold the Xth captured expr
   $+    Last parenthesized pattern match
   $^N   Holds the most recently closed capture
   $^R   Holds the result of the last (?{...}) expr
   @-    Offsets of starts of groups. $-[0] holds start of whole match
   @+    Offsets of ends of groups. $+[0] holds end of whole match

Captured groups are numbered according to their opening paren.

FUNCTIONS

   lc          Lowercase a string
   lcfirst     Lowercase first char of a string
   uc          Uppercase a string
   ucfirst     Titlecase first char of a string
   pos         Return or set current match position
   quotemeta   Quote metacharacters
   reset       Reset ?pattern? status
   study       Analyze string for optimizing matching
   split       Use regex to split a string into parts

The first four of these are like the escape sequences \L, \l, \U, and \u. For Titlecase, see Titlecase.

TERMINOLOGY

Titlecase

Unicode concept which most often is equal to uppercase, but for certain characters like the German "sharp s" there is a difference.

AUTHOR

Iain Truskett.

This document may be distributed under the same terms as Perl itself.

SEE ALSO

  • the perlretut manpage for a tutorial on regular expressions.

  • the perlrequick manpage for a rapid tutorial.

  • the perlre manpage for more details.

  • the perlvar manpage for details on the variables.

  • the perlop manpage for details on the operators.

  • the perlfunc manpage for details on the functions.

  • the perlfaq6 manpage for FAQs on regular expressions.

  • The the re manpage module to alter behaviour and aid debugging.

  • Debugging regular expressions in the perldebug manpage

  • the perluniintro manpage, the perlunicode manpage, the charnames manpage and the locale manpage for details on regexes and internationalisation.

  • Mastering Regular Expressions by Jeffrey Friedl (http://regex.info/) for a thorough grounding and reference on the topic.

THANKS

David P.C. Wollmann, Richard Soderberg, Sean M. Burke, Tom Christiansen, Jim Cromie, and Jeffrey Goff for useful advice.


perlretut - Perl regular expressions tutorial

  • Part 1: The basics
    • Simple word matching
    • Using character classes
    • Matching this or that
    • Grouping things and hierarchical matching
    • Extracting matches
    • Matching repetitions
    • Building a regexp
    • Using regular expressions in Perl
  • Part 2: Power tools
    • More on characters, strings, and character classes
    • Compiling and saving regular expressions
    • Embedding comments and modifiers in a regular expression
    • Non-capturing groupings
    • Looking ahead and looking behind
    • Using independent subexpressions to prevent backtracking
    • Conditional expressions
    • A bit of magic: executing Perl code in a regular expression
    • Pragmas and debugging
  • BUGS
  • SEE ALSO
  • AUTHOR AND COPYRIGHT
    • Acknowledgments

NAME

perlretut - Perl regular expressions tutorial

DESCRIPTION

This page provides a basic tutorial on understanding, creating and using regular expressions in Perl. It serves as a complement to the reference page on regular expressions the perlre manpage. Regular expressions are an integral part of the m//, s///, qr// and split operators and so this tutorial also overlaps with Regexp Quote-Like Operators in the perlop manpage and split in the perlfunc manpage.

Perl is widely renowned for excellence in text processing, and regular expressions are one of the big factors behind this fame. Perl regular expressions display an efficiency and flexibility unknown in most other computer languages. Mastering even the basics of regular expressions will allow you to manipulate text with surprising ease.

What is a regular expression? A regular expression is simply a string that describes a pattern. Patterns are in common use these days; examples are the patterns typed into a search engine to find web pages and the patterns used to list files in a directory, e.g., ls *.txt or dir *.*. In Perl, the patterns described by regular expressions are used to search strings, extract desired parts of strings, and to do search and replace operations.

Regular expressions have the undeserved reputation of being abstract and difficult to understand. Regular expressions are constructed using simple concepts like conditionals and loops and are no more difficult to understand than the corresponding if conditionals and while loops in the Perl language itself. In fact, the main challenge in learning regular expressions is just getting used to the terse notation used to express these concepts.

This tutorial flattens the learning curve by discussing regular expression concepts, along with their notation, one at a time and with many examples. The first part of the tutorial will progress from the simplest word searches to the basic regular expression concepts. If you master the first part, you will have all the tools needed to solve about 98% of your needs. The second part of the tutorial is for those comfortable with the basics and hungry for more power tools. It discusses the more advanced regular expression operators and introduces the latest cutting edge innovations in 5.6.0.

A note: to save time, 'regular expression' is often abbreviated as regexp or regex. Regexp is a more natural abbreviation than regex, but is harder to pronounce. The Perl pod documentation is evenly split on regexp vs regex; in Perl, there is more than one way to abbreviate it. We'll use regexp in this tutorial.

Part 1: The basics

Simple word matching

The simplest regexp is simply a word, or more generally, a string of characters. A regexp consisting of a word matches any string that contains that word:

    "Hello World" =~ /World/;  # matches

What is this perl statement all about? "Hello World" is a simple double quoted string. World is the regular expression and the // enclosing /World/ tells perl to search a string for a match. The operator =~ associates the string with the regexp match and produces a true value if the regexp matched, or false if the regexp did not match. In our case, World matches the second word in "Hello World", so the expression is true. Expressions like this are useful in conditionals:

    if ("Hello World" =~ /World/) {
        print "It matches\n";
    }
    else {
        print "It doesn't match\n";
    }

There are useful variations on this theme. The sense of the match can be reversed by using !~ operator:

    if ("Hello World" !~ /World/) {
        print "It doesn't match\n";
    }
    else {
        print "It matches\n";
    }

The literal string in the regexp can be replaced by a variable:

    $greeting = "World";
    if ("Hello World" =~ /$greeting/) {
        print "It matches\n";
    }
    else {
        print "It doesn't match\n";
    }

If you're matching against the special default variable $_, the $_ =~ part can be omitted:

    $_ = "Hello World";
    if (/World/) {
        print "It matches\n";
    }
    else {
        print "It doesn't match\n";
    }

And finally, the // default delimiters for a match can be changed to arbitrary delimiters by putting an 'm' out front:

    "Hello World" =~ m!World!;   # matches, delimited by '!'
    "Hello World" =~ m{World};   # matches, note the matching '{}'
    "/usr/bin/perl" =~ m"/perl"; # matches after '/usr/bin',
                                 # '/' becomes an ordinary char

/World/, m!World!, and m{World} all represent the same thing. When, e.g., "" is used as a delimiter, the forward slash '/' becomes an ordinary character and can be used in a regexp without trouble.

Let's consider how different regexps would match "Hello World":

    "Hello World" =~ /world/;  # doesn't match
    "Hello World" =~ /o W/;    # matches
    "Hello World" =~ /oW/;     # doesn't match
    "Hello World" =~ /World /; # doesn't match

The first regexp world doesn't match because regexps are case-sensitive. The second regexp matches because the substring 'o W' occurs in the string "Hello World" . The space character ' ' is treated like any other character in a regexp and is needed to match in this case. The lack of a space character is the reason the third regexp 'oW' doesn't match. The fourth regexp 'World ' doesn't match because there is a space at the end of the regexp, but not at the end of the string. The lesson here is that regexps must match a part of the string exactly in order for the statement to be true.

If a regexp matches in more than one place in the string, perl will always match at the earliest possible point in the string:

    "Hello World" =~ /o/;       # matches 'o' in 'Hello'
    "That hat is red" =~ /hat/; # matches 'hat' in 'That'

With respect to character matching, there are a few more points you need to know about. First of all, not all characters can be used 'as is' in a match. Some characters, called metacharacters, are reserved for use in regexp notation. The metacharacters are

    {}[]()^$.|*+?\

The significance of each of these will be explained in the rest of the tutorial, but for now, it is important only to know that a metacharacter can be matched by putting a backslash before it:

    "2+2=4" =~ /2+2/;    # doesn't match, + is a metacharacter
    "2+2=4" =~ /2\+2/;   # matches, \+ is treated like an ordinary +
    "The interval is [0,1)." =~ /[0,1)./     # is a syntax error!
    "The interval is [0,1)." =~ /\[0,1\)\./  # matches
    "/usr/bin/perl" =~ /\/usr\/bin\/perl/;  # matches

In the last regexp, the forward slash '/' is also backslashed, because it is used to delimit the regexp. This can lead to LTS (leaning toothpick syndrome), however, and it is often more readable to change delimiters.

    "/usr/bin/perl" =~ m!/usr/bin/perl!;    # easier to read

The backslash character '\' is a metacharacter itself and needs to be backslashed:

    'C:\WIN32' =~ /C:\\WIN/;   # matches

In addition to the metacharacters, there are some ASCII characters which don't have printable character equivalents and are instead represented by escape sequences. Common examples are \t for a tab, \n for a newline, \r for a carriage return and \a for a bell. If your string is better thought of as a sequence of arbitrary bytes, the octal escape sequence, e.g., \033, or hexadecimal escape sequence, e.g., \x1B may be a more natural representation for your bytes. Here are some examples of escapes:

    "1000\t2000" =~ m(0\t2)   # matches
    "1000\n2000" =~ /0\n20/   # matches
    "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne "\000"
    "cat"        =~ /\143\x61\x74/ # matches, but a weird way to spell cat

If you've been around Perl a while, all this talk of escape sequences may seem familiar. Similar escape sequences are used in double-quoted strings and in fact the regexps in Perl are mostly treated as double-quoted strings. This means that variables can be used in regexps as well. Just like double-quoted strings, the values of the variables in the regexp will be substituted in before the regexp is evaluated for matching purposes. So we have:

    $foo = 'house';
    'housecat' =~ /$foo/;      # matches
    'cathouse' =~ /cat$foo/;   # matches
    'housecat' =~ /${foo}cat/; # matches

So far, so good. With the knowledge above you can already perform searches with just about any literal string regexp you can dream up. Here is a very simple emulation of the Unix grep program:

    % cat > simple_grep
    #!/usr/bin/perl
    $regexp = shift;
    while (<>) {
        print if /$regexp/;
    }
    ^D

    % chmod +x simple_grep
    % simple_grep abba /usr/dict/words
    Babbage
    cabbage
    cabbages
    sabbath
    Sabbathize
    Sabbathizes
    sabbatical
    scabbard
    scabbards

This program is easy to understand. #!/usr/bin/perl is the standard way to invoke a perl program from the shell. $regexp = shift; saves the first command line argument as the regexp to be used, leaving the rest of the command line arguments to be treated as files. while (<>) loops over all the lines in all the files. For each line, print if /$regexp/; prints the line if the regexp matches the line. In this line, both print and /$regexp/ use the default variable $_ implicitly.

With all of the regexps above, if the regexp matched anywhere in the string, it was considered a match. Sometimes, however, we'd like to specify where in the string the regexp should try to match. To do this, we would use the anchor metacharacters ^ and $. The anchor ^ means match at the beginning of the string and the anchor $ means match at the end of the string, or before a newline at the end of the string. Here is how they are used:

    "housekeeper" =~ /keeper/;    # matches
    "housekeeper" =~ /^keeper/;   # doesn't match
    "housekeeper" =~ /keeper$/;   # matches
    "housekeeper\n" =~ /keeper$/; # matches

The second regexp doesn't match because ^ constrains keeper to match only at the beginning of the string, but "housekeeper" has keeper starting in the middle. The third regexp does match, since the $ constrains keeper to match only at the end of the string.

When both ^ and $ are used at the same time, the regexp has to match both the beginning and the end of the string, i.e., the regexp matches the whole string. Consider

    "keeper" =~ /^keep$/;      # doesn't match
    "keeper" =~ /^keeper$/;    # matches
    ""       =~ /^$/;          # ^$ matches an empty string

The first regexp doesn't match because the string has more to it than keep. Since the second regexp is exactly the string, it matches. Using both ^ and $ in a regexp forces the complete string to match, so it gives you complete control over which strings match and which don't. Suppose you are looking for a fellow named bert, off in a string by himself:

    "dogbert" =~ /bert/;   # matches, but not what you want

    "dilbert" =~ /^bert/;  # doesn't match, but ..
    "bertram" =~ /^bert/;  # matches, so still not good enough

    "bertram" =~ /^bert$/; # doesn't match, good
    "dilbert" =~ /^bert$/; # doesn't match, good
    "bert"    =~ /^bert$/; # matches, perfect

Of course, in the case of a literal string, one could just as easily use the string equivalence $string eq 'bert' and it would be more efficient. The ^...$ regexp really becomes useful when we add in the more powerful regexp tools below.

Using character classes

Although one can already do quite a lot with the literal string regexps above, we've only scratched the surface of regular expression technology. In this and subsequent sections we will introduce regexp concepts (and associated metacharacter notations) that will allow a regexp to not just represent a single character sequence, but a whole class of them.

One such concept is that of a character class. A character class allows a set of possible characters, rather than just a single character, to match at a particular point in a regexp. Character classes are denoted by brackets [...], with the set of characters to be possibly matched inside. Here are some examples:

    /cat/;       # matches 'cat'
    /[bcr]at/;   # matches 'bat, 'cat', or 'rat'
    /item[0123456789]/;  # matches 'item0' or ... or 'item9'
    "abc" =~ /[cab]/;    # matches 'a'

In the last statement, even though 'c' is the first character in the class, 'a' matches because the first character position in the string is the earliest point at which the regexp can match.

    /[yY][eE][sS]/;      # match 'yes' in a case-insensitive way
                         # 'yes', 'Yes', 'YES', etc.

This regexp displays a common task: perform a case-insensitive match. Perl provides away of avoiding all those brackets by simply appending an 'i' to the end of the match. Then /[yY][eE][sS]/; can be rewritten as /yes/i;. The 'i' stands for case-insensitive and is an example of a modifier of the matching operation. We will meet other modifiers later in the tutorial.

We saw in the section above that there were ordinary characters, which represented themselves, and special characters, which needed a backslash \ to represent themselves. The same is true in a character class, but the sets of ordinary and special characters inside a character class are different than those outside a character class. The special characters for a character class are -]\^$. ] is special because it denotes the end of a character class. $ is special because it denotes a scalar variable. \ is special because it is used in escape sequences, just like above. Here is how the special characters ]$\ are handled:

   /[\]c]def/; # matches ']def' or 'cdef'
   $x = 'bcr';
   /[$x]at/;   # matches 'bat', 'cat', or 'rat'
   /[\$x]at/;  # matches '$at' or 'xat'
   /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'

The last two are a little tricky. in [\$x], the backslash protects the dollar sign, so the character class has two members $ and x. In [\\$x], the backslash is protected, so $x is treated as a variable and substituted in double quote fashion.

The special character '-' acts as a range operator within character classes, so that a contiguous set of characters can be written as a range. With ranges, the unwieldy [0123456789] and [abc...xyz] become the svelte [0-9] and [a-z]. Some examples are

    /item[0-9]/;  # matches 'item0' or ... or 'item9'
    /[0-9bx-z]aa/;  # matches '0aa', ..., '9aa',
                    # 'baa', 'xaa', 'yaa', or 'zaa'
    /[0-9a-fA-F]/;  # matches a hexadecimal digit
    /[0-9a-zA-Z_]/; # matches a "word" character,
                    # like those in a perl variable name

If '-' is the first or last character in a character class, it is treated as an ordinary character; [-ab], [ab-] and [a\-b] are all equivalent.

The special character ^ in the first position of a character class denotes a negated character class, which matches any character but those in the brackets. Both [...] and [^...] must match a character, or the match fails. Then

    /[^a]at/;  # doesn't match 'aat' or 'at', but matches
               # all other 'bat', 'cat, '0at', '%at', etc.
    /[^0-9]/;  # matches a non-numeric character
    /[a^]at/;  # matches 'aat' or '^at'; here '^' is ordinary

Now, even [0-9] can be a bother the write multiple times, so in the interest of saving keystrokes and making regexps more readable, Perl has several abbreviations for common character classes:

  • \d is a digit and represents [0-9]

  • \s is a whitespace character and represents [\ \t\r\n\f]

  • \w is a word character (alphanumeric or _) and represents [0-9a-zA-Z_]

  • \D is a negated \d; it represents any character but a digit [^0-9]

  • \S is a negated \s; it represents any non-whitespace character [^\s]

  • \W is a negated \w; it represents any non-word character [^\w]

  • The period '.' matches any character but "\n"

The \d\s\w\D\S\W abbreviations can be used both inside and outside of character classes. Here are some in use:

    /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
    /[\d\s]/;         # matches any digit or whitespace character
    /\w\W\w/;         # matches a word char, followed by a
                      # non-word char, followed by a word char
    /..rt/;           # matches any two chars, followed by 'rt'
    /end\./;          # matches 'end.'
    /end[.]/;         # same thing, matches 'end.'

Because a period is a metacharacter, it needs to be escaped to match as an ordinary period. Because, for example, \d and \w are sets of characters, it is incorrect to think of [^\d\w] as [\D\W]; in fact [^\d\w] is the same as [^\w], which is the same as [\W]. Think DeMorgan's laws.

An anchor useful in basic regexps is the word anchor \b. This matches a boundary between a word character and a non-word character \w\W or \W\w:

    $x = "Housecat catenates house and cat";
    $x =~ /cat/;    # matches cat in 'housecat'
    $x =~ /\bcat/;  # matches cat in 'catenates'
    $x =~ /cat\b/;  # matches cat in 'housecat'
    $x =~ /\bcat\b/;  # matches 'cat' at end of string

Note in the last example, the end of the string is considered a word boundary.

You might wonder why '.' matches everything but "\n" - why not every character? The reason is that often one is matching against lines and would like to ignore the newline characters. For instance, while the string "\n" represents one line, we would like to think of as empty. Then

    ""   =~ /^$/;    # matches
    "\n" =~ /^$/;    # matches, "\n" is ignored

    ""   =~ /./;      # doesn't match; it needs a char
    ""   =~ /^.$/;    # doesn't match; it needs a char
    "\n" =~ /^.$/;    # doesn't match; it needs a char other than "\n"
    "a"  =~ /^.$/;    # matches
    "a\n"  =~ /^.$/;  # matches, ignores the "\n"

This behavior is convenient, because we usually want to ignore newlines when we count and match characters in a line. Sometimes, however, we want to keep track of newlines. We might even want ^ and $ to anchor at the beginning and end of lines within the string, rather than just the beginning and end of the string. Perl allows us to choose between ignoring and paying attention to newlines by using the //s and //m modifiers. //s and //m stand for single line and multi-line and they determine whether a string is to be treated as one continuous string, or as a set of lines. The two modifiers affect two aspects of how the regexp is interpreted: 1) how the '.' character class is defined, and 2) where the anchors ^ and $ are able to match. Here are the four possible combinations:

  • no modifiers (//): Default behavior. '.' matches any character except "\n". ^ matches only at the beginning of the string and $ matches only at the end or before a newline at the end.

  • s modifier (//s): Treat string as a single long line. '.' matches any character, even "\n". ^ matches only at the beginning of the string and $ matches only at the end or before a newline at the end.

  • m modifier (//m): Treat string as a set of multiple lines. '.' matches any character except "\n". ^ and $ are able to match at the start or end of any line within the string.

  • both s and m modifiers (//sm): Treat string as a single long line, but detect multiple lines. '.' matches any character, even "\n". ^ and $, however, are able to match at the start or end of any line within the string.

Here are examples of //s and //m in action:

    $x = "There once was a girl\nWho programmed in Perl\n";

    $x =~ /^Who/;   # doesn't match, "Who" not at start of string
    $x =~ /^Who/s;  # doesn't match, "Who" not at start of string
    $x =~ /^Who/m;  # matches, "Who" at start of second line
    $x =~ /^Who/sm; # matches, "Who" at start of second line

    $x =~ /girl.Who/;   # doesn't match, "." doesn't match "\n"
    $x =~ /girl.Who/s;  # matches, "." matches "\n"
    $x =~ /girl.Who/m;  # doesn't match, "." doesn't match "\n"
    $x =~ /girl.Who/sm; # matches, "." matches "\n"

Most of the time, the default behavior is what is want, but //s and //m are occasionally very useful. If //m is being used, the start of the string can still be matched with \A and the end of string can still be matched with the anchors \Z (matches both the end and the newline before, like $), and \z (matches only the end):

    $x =~ /^Who/m;   # matches, "Who" at start of second line
    $x =~ /\AWho/m;  # doesn't match, "Who" is not at start of string

    $x =~ /girl$/m;  # matches, "girl" at end of first line
    $x =~ /girl\Z/m; # doesn't match, "girl" is not at end of string

    $x =~ /Perl\Z/m; # matches, "Perl" is at newline before end
    $x =~ /Perl\z/m; # doesn't match, "Perl" is not at end of string

We now know how to create choices among classes of characters in a regexp. What about choices among words or character strings? Such choices are described in the next section.

Matching this or that

Sometimes we would like to our regexp to be able to match different possible words or character strings. This is accomplished by using the alternation metacharacter |. To match dog or cat, we form the regexp dog|cat. As before, perl will try to match the regexp at the earliest possible point in the string. At each character position, perl will first try to match the first alternative, dog. If dog doesn't match, perl will then try the next alternative, cat. If cat doesn't match either, then the match fails and perl moves to the next position in the string. Some examples:

    "cats and dogs" =~ /cat|dog|bird/;  # matches "cat"
    "cats and dogs" =~ /dog|cat|bird/;  # matches "cat"

Even though dog is the first alternative in the second regexp, cat is able to match earlier in the string.

    "cats"          =~ /c|ca|cat|cats/; # matches "c"
    "cats"          =~ /cats|cat|ca|c/; # matches "cats"

Here, all the alternatives match at the first string position, so the first alternative is the one that matches. If some of the alternatives are truncations of the others, put the longest ones first to give them a chance to match.

    "cab" =~ /a|b|c/ # matches "c"
                     # /a|b|c/ == /[abc]/

The last example points out that character classes are like alternations of characters. At a given character position, the first alternative that allows the regexp match to succeed will be the one that matches.

Grouping things and hierarchical matching

Alternation allows a regexp to choose among alternatives, but by itself it unsatisfying. The reason is that each alternative is a whole regexp, but sometime we want alternatives for just part of a regexp. For instance, suppose we want to search for housecats or housekeepers. The regexp housecat|housekeeper fits the bill, but is inefficient because we had to type house twice. It would be nice to have parts of the regexp be constant, like house, and some parts have alternatives, like cat|keeper.

The grouping metacharacters () solve this problem. Grouping allows parts of a regexp to be treated as a single unit. Parts of a regexp are grouped by enclosing them in parentheses. Thus we could solve the housecat|housekeeper by forming the regexp as house(cat|keeper). The regexp house(cat|keeper) means match house followed by either cat or keeper. Some more examples are

    /(a|b)b/;    # matches 'ab' or 'bb'
    /(ac|b)b/;   # matches 'acb' or 'bb'
    /(^a|b)c/;   # matches 'ac' at start of string or 'bc' anywhere
    /(a|[bc])d/; # matches 'ad', 'bd', or 'cd'

    /house(cat|)/;  # matches either 'housecat' or 'house'
    /house(cat(s|)|)/;  # matches either 'housecats' or 'housecat' or
                        # 'house'.  Note groups can be nested.

    /(19|20|)\d\d/;  # match years 19xx, 20xx, or the Y2K problem, xx
    "20" =~ /(19|20|)\d\d/;  # matches the null alternative '()\d\d',
                             # because '20\d\d' can't match

Alternations behave the same way in groups as out of them: at a given string position, the leftmost alternative that allows the regexp to match is taken. So in the last example at the first string position, "20" matches the second alternative, but there is nothing left over to match the next two digits \d\d. So perl moves on to the next alternative, which is the null alternative and that works, since "20" is two digits.

The process of trying one alternative, seeing if it matches, and moving on to the next alternative if it doesn't, is called backtracking. The term 'backtracking' comes from the idea that matching a regexp is like a walk in the woods. Successfully matching a regexp is like arriving at a destination. There are many possible trailheads, one for each string position, and each one is tried in order, left to right. From each trailhead there may be many paths, some of which get you there, and some which are dead ends. When you walk along a trail and hit a dead end, you have to backtrack along the trail to an earlier point to try another trail. If you hit your destination, you stop immediately and forget about trying all the other trails. You are persistent, and only if you have tried all the trails from all the trailheads and not arrived at your destination, do you declare failure. To be concrete, here is a step-by-step analysis of what perl does when it tries to match the regexp

    "abcde" =~ /(abd|abc)(df|d|de)/;

  1. Start with the first letter in the string 'a'.

  2. Try the first alternative in the first group 'abd'.

  3. Match 'a' followed by 'b'. So far so good.

  4. 'd' in the regexp doesn't match 'c' in the string - a dead end. So backtrack two characters and pick the second alternative in the first group 'abc'.

  5. Match 'a' followed by 'b' followed by 'c'. We are on a roll and have satisfied the first group. Set $1 to 'abc'.

  6. Move on to the second group and pick the first alternative 'df'.

  7. Match the 'd'.

  8. 'f' in the regexp doesn't match 'e' in the string, so a dead end. Backtrack one character and pick the second alternative in the second group 'd'.

  9. 'd' matches. The second grouping is satisfied, so set $2 to 'd'.

  10. We are at the end of the regexp, so we are done! We have matched 'abcd' out of the string "abcde".

There are a couple of things to note about this analysis. First, the third alternative in the second group 'de' also allows a match, but we stopped before we got to it - at a given character position, leftmost wins. Second, we were able to get a match at the first character position of the string 'a'. If there were no matches at the first position, perl would move to the second character position 'b' and attempt the match all over again. Only when all possible paths at all possible character positions have been exhausted does perl give up and declare $string =~ /(abd|abc)(df|d|de)/; to be false.

Even with all this work, regexp matching happens remarkably fast. To speed things up, during compilation stage, perl compiles the regexp into a compact sequence of opcodes that can often fit inside a processor cache. When the code is executed, these opcodes can then run at full throttle and search very quickly.

Extracting matches

The grouping metacharacters () also serve another completely different function: they allow the extraction of the parts of a string that matched. This is very useful to find out what matched and for text processing in general. For each grouping, the part that matched inside goes into the special variables $1, $2, etc. They can be used just as ordinary variables:

    # extract hours, minutes, seconds
    if ($time =~ /(\d\d):(\d\d):(\d\d)/) {    # match hh:mm:ss format
        $hours = $1;
        $minutes = $2;
        $seconds = $3;
    }

Now, we know that in scalar context, $time =~ /(\d\d):(\d\d):(\d\d)/ returns a true or false value. In list context, however, it returns the list of matched values ($1,$2,$3). So we could write the code more compactly as

    # extract hours, minutes, seconds
    ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);

If the groupings in a regexp are nested, $1 gets the group with the leftmost opening parenthesis, $2 the next opening parenthesis, etc. For example, here is a complex regexp and the matching variables indicated below it:

    /(ab(cd|ef)((gi)|j))/;
     1  2      34

so that if the regexp matched, e.g., $2 would contain 'cd' or 'ef'. For convenience, perl sets $+ to the string held by the highest numbered $1, $2, ... that got assigned (and, somewhat related, $^N to the value of the $1, $2, ... most-recently assigned; i.e. the $1, $2, ... associated with the rightmost closing parenthesis used in the match).

Closely associated with the matching variables $1, $2, ... are the backreferences \1, \2, ... . Backreferences are simply matching variables that can be used inside a regexp. This is a really nice feature - what matches later in a regexp can depend on what matched earlier in the regexp. Suppose we wanted to look for doubled words in text, like 'the the'. The following regexp finds all 3-letter doubles with a space in between:

    /(\w\w\w)\s\1/;

The grouping assigns a value to \1, so that the same 3 letter sequence is used for both parts. Here are some words with repeated parts:

    % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\1$' /usr/dict/words
    beriberi
    booboo
    coco
    mama
    murmur
    papa

The regexp has a single grouping which considers 4-letter combinations, then 3-letter combinations, etc. and uses \1 to look for a repeat. Although $1 and \1 represent the same thing, care should be taken to use matched variables $1, $2, ... only outside a regexp and backreferences \1, \2, ... only inside a regexp; not doing so may lead to surprising and/or undefined results.

In addition to what was matched, Perl 5.6.0 also provides the positions of what was matched with the @- and @+ arrays. $-[0] is the position of the start of the entire match and $+[0] is the position of the end. Similarly, $-[n] is the position of the start of the $n match and $+[n] is the position of the end. If $n is undefined, so are $-[n] and $+[n]. Then this code

    $x = "Mmm...donut, thought Homer";
    $x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches
    foreach $expr (1..$#-) {
        print "Match $expr: '${$expr}' at position ($-[$expr],$+[$expr])\n";
    }

prints

    Match 1: 'Mmm' at position (0,3)
    Match 2: 'donut' at position (6,11)

Even if there are no groupings in a regexp, it is still possible to find out what exactly matched in a string. If you use them, perl will set $` to the part of the string before the match, will set $& to the part of the string that matched, and will set $' to the part of the string after the match. An example:

    $x = "the cat caught the mouse";
    $x =~ /cat/;  # $` = 'the ', $& = 'cat', $' = ' caught the mouse'
    $x =~ /the/;  # $` = '', $& = 'the', $' = ' cat caught the mouse'

In the second match, $` = '' because the regexp matched at the first character position in the string and stopped, it never saw the second 'the'. It is important to note that using $` and $' slows down regexp matching quite a bit, and $& slows it down to a lesser extent, because if they are used in one regexp in a program, they are generated for <all> regexps in the program. So if raw performance is a goal of your application, they should be avoided. If you need them, use @- and @+ instead:

    $` is the same as substr( $x, 0, $-[0] )
    $& is the same as substr( $x, $-[0], $+[0]-$-[0] )
    $' is the same as substr( $x, $+[0] )

Matching repetitions

The examples in the previous section display an annoying weakness. We were only matching 3-letter words, or syllables of 4 letters or less. We'd like to be able to match words or syllables of any length, without writing out tedious alternatives like \w\w\w\w|\w\w\w|\w\w|\w.

This is exactly the problem the quantifier metacharacters ?, *, +, and {} were created for. They allow us to determine the number of repeats of a portion of a regexp we consider to be a match. Quantifiers are put immediately after the character, character class, or grouping that we want to specify. They have the following meanings:

  • a? = match 'a' 1 or 0 times

  • a* = match 'a' 0 or more times, i.e., any number of times

  • a+ = match 'a' 1 or more times, i.e., at least once

  • a{n,m} = match at least n times, but not more than m times.

  • a{n,} = match at least n or more times

  • a{n} = match exactly n times

Here are some examples:

    /[a-z]+\s+\d*/;  # match a lowercase word, at least some space, and
                     # any number of digits
    /(\w+)\s+\1/;    # match doubled words of arbitrary length
    /y(es)?/i;       # matches 'y', 'Y', or a case-insensitive 'yes'
    $year =~ /\d{2,4}/;  # make sure year is at least 2 but not more
                         # than 4 digits
    $year =~ /\d{4}|\d{2}/;    # better match; throw out 3 digit dates
    $year =~ /\d{2}(\d{2})?/;  # same thing written differently. However,
                               # this produces $1 and the other does not.

    % simple_grep '^(\w+)\1$' /usr/dict/words   # isn't this easier?
    beriberi
    booboo
    coco
    mama
    murmur
    papa

For all of these quantifiers, perl will try to match as much of the string as possible, while still allowing the regexp to succeed. Thus with /a?.../, perl will first try to match the regexp with the a present; if that fails, perl will try to match the regexp without the a present. For the quantifier *, we get the following:

    $x = "the cat in the hat";
    $x =~ /^(.*)(cat)(.*)$/; # matches,
                             # $1 = 'the '
                             # $2 = 'cat'
                             # $3 = ' in the hat'

Which is what we might expect, the match finds the only cat in the string and locks onto it. Consider, however, this regexp:

    $x =~ /^(.*)(at)(.*)$/; # matches,
                            # $1 = 'the cat in the h'
                            # $2 = 'at'
                            # $3 = ''   (0 matches)

One might initially guess that perl would find the at in cat and stop there, but that wouldn't give the longest possible string to the first quantifier .*. Instead, the first quantifier .* grabs as much of the string as possible while still having the regexp match. In this example, that means having the at sequence with the final at in the string. The other important principle illustrated here is that when there are two or more elements in a regexp, the leftmost quantifier, if there is one, gets to grab as much the string as possible, leaving the rest of the regexp to fight over scraps. Thus in our example, the first quantifier .* grabs most of the string, while the second quantifier .* gets the empty string. Quantifiers that grab as much of the string as possible are called maximal match or greedy quantifiers.

When a regexp can match a string in several different ways, we can use the principles above to predict which way the regexp will match:

  • Principle 0: Taken as a whole, any regexp will be matched at the earliest possible position in the string.

  • Principle 1: In an alternation a|b|c..., the leftmost alternative that allows a match for the whole regexp will be the one used.

  • Principle 2: The maximal matching quantifiers ?, *, + and {n,m} will in general match as much of the string as possible while still allowing the whole regexp to match.

  • Principle 3: If there are two or more elements in a regexp, the leftmost greedy quantifier, if any, will match as much of the string as possible while still allowing the whole regexp to match. The next leftmost greedy quantifier, if any, will try to match as much of the string remaining available to it as possible, while still allowing the whole regexp to match. And so on, until all the regexp elements are satisfied.

As we have seen above, Principle 0 overrides the others - the regexp will be matched as early as possible, with the other principles determining how the regexp matches at that earliest character position.

Here is an example of these principles in action:

    $x = "The programming republic of Perl";
    $x =~ /^(.+)(e|r)(.*)$/;  # matches,
                              # $1 = 'The programming republic of Pe'
                              # $2 = 'r'
                              # $3 = 'l'

This regexp matches at the earliest string position, 'T'. One might think that e, being leftmost in the alternation, would be matched, but r produces the longest string in the first quantifier.

    $x =~ /(m{1,2})(.*)$/;  # matches,
                            # $1 = 'mm'
                            # $2 = 'ing republic of Perl'

Here, The earliest possible match is at the first 'm' in programming. m{1,2} is the first quantifier, so it gets to match a maximal mm.

    $x =~ /.*(m{1,2})(.*)$/;  # matches,
                              # $1 = 'm'
                              # $2 = 'ing republic of Perl'

Here, the regexp matches at the start of the string. The first quantifier .* grabs as much as possible, leaving just a single 'm' for the second quantifier m{1,2}.

    $x =~ /(.?)(m{1,2})(.*)$/;  # matches,
                                # $1 = 'a'
                                # $2 = 'mm'
                                # $3 = 'ing republic of Perl'

Here, .? eats its maximal one character at the earliest possible position in the string, 'a' in programming, leaving m{1,2} the opportunity to match both m's. Finally,

    "aXXXb" =~ /(X*)/; # matches with $1 = ''

because it can match zero copies of 'X' at the beginning of the string. If you definitely want to match at least one 'X', use X+, not X*.

Sometimes greed is not good. At times, we would like quantifiers to match a minimal piece of string, rather than a maximal piece. For this purpose, Larry Wall created the minimal match or non-greedy quantifiers ??,*?, +?, and {}?. These are the usual quantifiers with a ? appended to them. They have the following meanings:

  • a?? = match 'a' 0 or 1 times. Try 0 first, then 1.

  • a*? = match 'a' 0 or more times, i.e., any number of times, but as few times as possible

  • a+? = match 'a' 1 or more times, i.e., at least once, but as few times as possible

  • a{n,m}? = match at least n times, not more than m times, as few times as possible

  • a{n,}? = match at least n times, but as few times as possible

  • a{n}? = match exactly n times. Because we match exactly n times, a{n}? is equivalent to a{n} and is just there for notational consistency.

Let's look at the example above, but with minimal quantifiers:

    $x = "The programming republic of Perl";
    $x =~ /^(.+?)(e|r)(.*)$/; # matches,
                              # $1 = 'Th'
                              # $2 = 'e'
                              # $3 = ' programming republic of Perl'

The minimal string that will allow both the start of the string ^ and the alternation to match is Th, with the alternation e|r matching e. The second quantifier .* is free to gobble up the rest of the string.

    $x =~ /(m{1,2}?)(.*?)$/;  # matches,
                              # $1 = 'm'
                              # $2 = 'ming republic of Perl'

The first string position that this regexp can match is at the first 'm' in programming. At this position, the minimal m{1,2}? matches just one 'm'. Although the second quantifier .*? would prefer to match no characters, it is constrained by the end-of-string anchor $ to match the rest of the string.

    $x =~ /(.*?)(m{1,2}?)(.*)$/;  # matches,
                                  # $1 = 'The progra'
                                  # $2 = 'm'
                                  # $3 = 'ming republic of Perl'

In this regexp, you might expect the first minimal quantifier .*? to match the empty string, because it is not constrained by a ^ anchor to match the beginning of the word. Principle 0 applies here, however. Because it is possible for the whole regexp to match at the start of the string, it will match at the start of the string. Thus the first quantifier has to match everything up to the first m. The second minimal quantifier matches just one m and the third quantifier matches the rest of the string.

    $x =~ /(.??)(m{1,2})(.*)$/;  # matches,
                                 # $1 = 'a'
                                 # $2 = 'mm'
                                 # $3 = 'ing republic of Perl'

Just as in the previous regexp, the first quantifier .?? can match earliest at position 'a', so it does. The second quantifier is greedy, so it matches mm, and the third matches the rest of the string.

We can modify principle 3 above to take into account non-greedy quantifiers:

  • Principle 3: If there are two or more elements in a regexp, the leftmost greedy (non-greedy) quantifier, if any, will match as much (little) of the string as possible while still allowing the whole regexp to match. The next leftmost greedy (non-greedy) quantifier, if any, will try to match as much (little) of the string remaining available to it as possible, while still allowing the whole regexp to match. And so on, until all the regexp elements are satisfied.

Just like alternation, quantifiers are also susceptible to backtracking. Here is a step-by-step analysis of the example

    $x = "the cat in the hat";
    $x =~ /^(.*)(at)(.*)$/; # matches,
                            # $1 = 'the cat in the h'
                            # $2 = 'at'
                            # $3 = ''   (0 matches)

  1. Start with the first letter in the string 't'.

  2. The first quantifier '.*' starts out by matching the whole string 'the cat in the hat'.

  3. 'a' in the regexp element 'at' doesn't match the end of the string. Backtrack one character.

  4. 'a' in the regexp element 'at' still doesn't match the last letter of the string 't', so backtrack one more character.

  5. Now we can match the 'a' and the 't'.

  6. Move on to the third element '.*'. Since we are at the end of the string and '.*' can match 0 times, assign it the empty string.

  7. We are done!

Most of the time, all this moving forward and backtracking happens quickly and searching is fast. There are some pathological regexps, however, whose execution time exponentially grows with the size of the string. A typical structure that blows up in your face is of the form

    /(a|b+)*/;

The problem is the nested indeterminate quantifiers. There are many different ways of partitioning a string of length n between the + and *: one repetition with b+ of length n, two repetitions with the first b+ length k and the second with length n-k, m repetitions whose bits add up to length n, etc. In fact there are an exponential number of ways to partition a string as a function of length. A regexp may get lucky and match early in the process, but if there is no match, perl will try every possibility before giving up. So be careful with nested *'s, {n,m}'s, and +'s. The book Mastering regular expressions by Jeffrey Friedl gives a wonderful discussion of this and other efficiency issues.

Building a regexp

At this point, we have all the basic regexp concepts covered, so let's give a more involved example of a regular expression. We will build a regexp that matches numbers.

The first task in building a regexp is to decide what we want to match and what we want to exclude. In our case, we want to match both integers and floating point numbers and we want to reject any string that isn't a number.

The next task is to break the problem down into smaller problems that are easily converted into a regexp.

The simplest case is integers. These consist of a sequence of digits, with an optional sign in front. The digits we can represent with \d+ and the sign can be matched with [+-]. Thus the integer regexp is

    /[+-]?\d+/;  # matches integers

A floating point number potentially has a sign, an integral part, a decimal point, a fractional part, and an exponent. One or more of these parts is optional, so we need to check out the different possibilities. Floating point numbers which are in proper form include 123., 0.345, .34, -1e6, and 25.4E-72. As with integers, the sign out front is completely optional and can be matched by [+-]?. We can see that if there is no exponent, floating point numbers must have a decimal point, otherwise they are integers. We might be tempted to model these with \d*\.\d*, but this would also match just a single decimal point, which is not a number. So the three cases of floating point number sans exponent are

   /[+-]?\d+\./;  # 1., 321., etc.
   /[+-]?\.\d+/;  # .1, .234, etc.
   /[+-]?\d+\.\d+/;  # 1.0, 30.56, etc.

These can be combined into a single regexp with a three-way alternation:

   /[+-]?(\d+\.\d+|\d+\.|\.\d+)/;  # floating point, no exponent

In this alternation, it is important to put '\d+\.\d+' before '\d+\.'. If '\d+\.' were first, the regexp would happily match that and ignore the fractional part of the number.

Now consider floating point numbers with exponents. The key observation here is that both integers and numbers with decimal points are allowed in front of an exponent. Then exponents, like the overall sign, are independent of whether we are matching numbers with or without decimal points, and can be 'decoupled' from the mantissa. The overall form of the regexp now becomes clear:

    /^(optional sign)(integer | f.p. mantissa)(optional exponent)$/;

The exponent is an e or E, followed by an integer. So the exponent regexp is

   /[eE][+-]?\d+/;  # exponent

Putting all the parts together, we get a regexp that matches numbers:

   /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/;  # Ta da!

Long regexps like this may impress your friends, but can be hard to decipher. In complex situations like this, the //x modifier for a match is invaluable. It allows one to put nearly arbitrary whitespace and comments into a regexp without affecting their meaning. Using it, we can rewrite our 'extended' regexp in the more pleasing form

   /^
      [+-]?         # first, match an optional sign
      (             # then match integers or f.p. mantissas:
          \d+\.\d+  # mantissa of the form a.b
         |\d+\.     # mantissa of the form a.
         |\.\d+     # mantissa of the form .b
         |\d+       # integer of the form a
      )
      ([eE][+-]?\d+)?  # finally, optionally match an exponent
   $/x;

If whitespace is mostly irrelevant, how does one include space characters in an extended regexp? The answer is to backslash it '\ ' or put it in a character class [ ] . The same thing goes for pound signs, use \# or [#]. For instance, Perl allows a space between the sign and the mantissa/integer, and we could add this to our regexp as follows:

   /^
      [+-]?\ *      # first, match an optional sign *and space*
      (             # then match integers or f.p. mantissas:
          \d+\.\d+  # mantissa of the form a.b
         |\d+\.     # mantissa of the form a.
         |\.\d+     # mantissa of the form .b
         |\d+       # integer of the form a
      )
      ([eE][+-]?\d+)?  # finally, optionally match an exponent
   $/x;

In this form, it is easier to see a way to simplify the alternation. Alternatives 1, 2, and 4 all start with \d+, so it could be factored out:

   /^
      [+-]?\ *      # first, match an optional sign
      (             # then match integers or f.p. mantissas:
          \d+       # start out with a ...
          (
              \.\d* # mantissa of the form a.b or a.
          )?        # ? takes care of integers of the form a
         |\.\d+     # mantissa of the form .b
      )
      ([eE][+-]?\d+)?  # finally, optionally match an exponent
   $/x;

or written in the compact form,

    /^[+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;

This is our final regexp. To recap, we built a regexp by

  • specifying the task in detail,

  • breaking down the problem into smaller parts,

  • translating the small parts into regexps,

  • combining the regexps,

  • and optimizing the final combined regexp.

These are also the typical steps involved in writing a computer program. This makes perfect sense, because regular expressions are essentially programs written a little computer language that specifies patterns.

Using regular expressions in Perl

The last topic of Part 1 briefly covers how regexps are used in Perl programs. Where do they fit into Perl syntax?

We have already introduced the matching operator in its default /regexp/ and arbitrary delimiter m!regexp! forms. We have used the binding operator =~ and its negation !~ to test for string matches. Associated with the matching operator, we have discussed the single line //s, multi-line //m, case-insensitive //i and extended //x modifiers.

There are a few more things you might want to know about matching operators. First, we pointed out earlier that variables in regexps are substituted before the regexp is evaluated:

    $pattern = 'Seuss';
    while (<>) {
        print if /$pattern/;
    }

This will print any lines containing the word Seuss. It is not as efficient as it could be, however, because perl has to re-evaluate $pattern each time through the loop. If $pattern won't be changing over the lifetime of the script, we can add the //o modifier, which directs perl to only perform variable substitutions once:

    #!/usr/bin/perl
    #    Improved simple_grep
    $regexp = shift;
    while (<>) {
        print if /$regexp/o;  # a good deal faster
    }

If you change $pattern after the first substitution happens, perl will ignore it. If you don't want any substitutions at all, use the special delimiter m'':

    @pattern = ('Seuss');
    while (<>) {
        print if m'@pattern';  # matches literal '@pattern', not 'Seuss'
    }

m'' acts like single quotes on a regexp; all other m delimiters act like double quotes. If the regexp evaluates to the empty string, the regexp in the last successful match is used instead. So we have

    "dog" =~ /d/;  # 'd' matches
    "dogbert =~ //;  # this matches the 'd' regexp used before

The final two modifiers //g and //c concern multiple matches. The modifier //g stands for global matching and allows the matching operator to match within a string as many times as possible. In scalar context, successive invocations against a string will have `//g jump from match to match, keeping track of position in the string as it goes along. You can get or set the position with the pos() function.

The use of //g is shown in the following example. Suppose we have a string that consists of words separated by spaces. If we know how many words there are in advance, we could extract the words using groupings:

    $x = "cat dog house"; # 3 words
    $x =~ /^\s*(\w+)\s+(\w+)\s+(\w+)\s*$/; # matches,
                                           # $1 = 'cat'
                                           # $2 = 'dog'
                                           # $3 = 'house'

But what if we had an indeterminate number of words? This is the sort of task //g was made for. To extract all words, form the simple regexp (\w+) and loop over all matches with /(\w+)/g:

    while ($x =~ /(\w+)/g) {
        print "Word is $1, ends at position ", pos $x, "\n";
    }

prints

    Word is cat, ends at position 3
    Word is dog, ends at position 7
    Word is house, ends at position 13

A failed match or changing the target string resets the position. If you don't want the position reset after failure to match, add the //c, as in /regexp/gc. The current position in the string is associated with the string, not the regexp. This means that different strings have different positions and their respective positions can be set or read independently.

In list context, //g returns a list of matched groupings, or if there are no groupings, a list of matches to the whole regexp. So if we wanted just the words, we could use

    @words = ($x =~ /(\w+)/g);  # matches,
                                # $word[0] = 'cat'
                                # $word[1] = 'dog'
                                # $word[2] = 'house'

Closely associated with the //g modifier is the \G anchor. The \G anchor matches at the point where the previous //g match left off. \G allows us to easily do context-sensitive matching:

    $metric = 1;  # use metric units
    ...
    $x = <FILE>;  # read in measurement
    $x =~ /^([+-]?\d+)\s*/g;  # get magnitude
    $weight = $1;
    if ($metric) { # error checking
        print "Units error!" unless $x =~ /\Gkg\./g;
    }
    else {
        print "Units error!" unless $x =~ /\Glbs\./g;
    }
    $x =~ /\G\s+(widget|sprocket)/g;  # continue processing

The combination of //g and \G allows us to process the string a bit at a time and use arbitrary Perl logic to decide what to do next. Currently, the \G anchor is only fully supported when used to anchor to the start of the pattern.

\G is also invaluable in processing fixed length records with regexps. Suppose we have a snippet of coding region DNA, encoded as base pair letters ATCGTTGAAT... and we want to find all the stop codons TGA. In a coding region, codons are 3-letter sequences, so we can think of the DNA snippet as a sequence of 3-letter records. The naive regexp

    # expanded, this is "ATC GTT GAA TGC AAA TGA CAT GAC"
    $dna = "ATCGTTGAATGCAAATGACATGAC";
    $dna =~ /TGA/;

doesn't work; it may match a TGA, but there is no guarantee that the match is aligned with codon boundaries, e.g., the substring GTT GAA gives a match. A better solution is

    while ($dna =~ /(\w\w\w)*?TGA/g) {  # note the minimal *?
        print "Got a TGA stop codon at position ", pos $dna, "\n";
    }

which prints

    Got a TGA stop codon at position 18
    Got a TGA stop codon at position 23

Position 18 is good, but position 23 is bogus. What happened?

The answer is that our regexp works well until we get past the last real match. Then the regexp will fail to match a synchronized TGA and start stepping ahead one character position at a time, not what we want. The solution is to use \G to anchor the match to the codon alignment:

    while ($dna =~ /\G(\w\w\w)*?TGA/g) {
        print "Got a TGA stop codon at position ", pos $dna, "\n";
    }

This prints

    Got a TGA stop codon at position 18

which is the correct answer. This example illustrates that it is important not only to match what is desired, but to reject what is not desired.

search and replace

Regular expressions also play a big role in search and replace operations in Perl. Search and replace is accomplished with the s/// operator. The general form is s/regexp/replacement/modifiers, with everything we know about regexps and modifiers applying in this case as well. The replacement is a Perl double quoted string that replaces in the string whatever is matched with the regexp. The operator =~ is also used here to associate a string with s///. If matching against $_, the $_ =~ can be dropped. If there is a match, s/// returns the number of substitutions made, otherwise it returns false. Here are a few examples:

    $x = "Time to feed the cat!";
    $x =~ s/cat/hacker/;   # $x contains "Time to feed the hacker!"
    if ($x =~ s/^(Time.*hacker)!$/$1 now!/) {
        $more_insistent = 1;
    }
    $y = "'quoted words'";
    $y =~ s/^'(.*)'$/$1/;  # strip single quotes,
                           # $y contains "quoted words"

In the last example, the whole string was matched, but only the part inside the single quotes was grouped. With the s/// operator, the matched variables $1, $2, etc. are immediately available for use in the replacement expression, so we use $1 to replace the quoted string with just what was quoted. With the global modifier, s///g will search and replace all occurrences of the regexp in the string:

    $x = "I batted 4 for 4";
    $x =~ s/4/four/;   # doesn't do it all:
                       # $x contains "I batted four for 4"
    $x = "I batted 4 for 4";
    $x =~ s/4/four/g;  # does it all:
                       # $x contains "I batted four for four"

If you prefer 'regex' over 'regexp' in this tutorial, you could use the following program to replace it:

    % cat > simple_replace
    #!/usr/bin/perl
    $regexp = shift;
    $replacement = shift;
    while (<>) {
        s/$regexp/$replacement/go;
        print;
    }
    ^D

    % simple_replace regexp regex perlretut.pod

In simple_replace we used the s///g modifier to replace all occurrences of the regexp on each line and the s///o modifier to compile the regexp only once. As with simple_grep, both the print and the s/$regexp/$replacement/go use $_ implicitly.

A modifier available specifically to search and replace is the s///e evaluation modifier. s///e wraps an eval{...} around the replacement string and the evaluated result is substituted for the matched substring. s///e is useful if you need to do a bit of computation in the process of replacing text. This example counts character frequencies in a line:

    $x = "Bill the cat";
    $x =~ s/(.)/$chars{$1}++;$1/eg;  # final $1 replaces char with itself
    print "frequency of '$_' is $chars{$_}\n"
        foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars);

This prints

    frequency of ' ' is 2
    frequency of 't' is 2
    frequency of 'l' is 2
    frequency of 'B' is 1
    frequency of 'c' is 1
    frequency of 'e' is 1
    frequency of 'h' is 1
    frequency of 'i' is 1
    frequency of 'a' is 1

As with the match m// operator, s/// can use other delimiters, such as s!!! and s{}{}, and even s{}//. If single quotes are used s''', then the regexp and replacement are treated as single quoted strings and there are no substitutions. s/// in list context returns the same thing as in scalar context, i.e., the number of matches.

The split operator

The split function can also optionally use a matching operator m// to split a string. split /regexp/, string, limit splits string into a list of substrings and returns that list. The regexp is used to match the character sequence that the string is split with respect to. The limit, if present, constrains splitting into no more than limit number of strings. For example, to split a string into words, use

    $x = "Calvin and Hobbes";
    @words = split /\s+/, $x;  # $word[0] = 'Calvin'
                               # $word[1] = 'and'
                               # $word[2] = 'Hobbes'

If the empty regexp // is used, the regexp always matches and the string is split into individual characters. If the regexp has groupings, then list produced contains the matched substrings from the groupings as well. For instance,

    $x = "/usr/bin/perl";
    @dirs = split m!/!, $x;  # $dirs[0] = ''
                             # $dirs[1] = 'usr'
                             # $dirs[2] = 'bin'
                             # $dirs[3] = 'perl'
    @parts = split m!(/)!, $x;  # $parts[0] = ''
                                # $parts[1] = '/'
                                # $parts[2] = 'usr'
                                # $parts[3] = '/'
                                # $parts[4] = 'bin'
                                # $parts[5] = '/'
                                # $parts[6] = 'perl'

Since the first character of $x matched the regexp, split prepended an empty initial element to the list.

If you have read this far, congratulations! You now have all the basic tools needed to use regular expressions to solve a wide range of text processing problems. If this is your first time through the tutorial, why not stop here and play around with regexps a while... Part 2 concerns the more esoteric aspects of regular expressions and those concepts certainly aren't needed right at the start.

Part 2: Power tools

OK, you know the basics of regexps and you want to know more. If matching regular expressions is analogous to a walk in the woods, then the tools discussed in Part 1 are analogous to topo maps and a compass, basic tools we use all the time. Most of the tools in part 2 are analogous to flare guns and satellite phones. They aren't used too often on a hike, but when we are stuck, they can be invaluable.

What follows are the more advanced, less used, or sometimes esoteric capabilities of perl regexps. In Part 2, we will assume you are comfortable with the basics and concentrate on the new features.

More on characters, strings, and character classes

There are a number of escape sequences and character classes that we haven't covered yet.

There are several escape sequences that convert characters or strings between upper and lower case. \l and \u convert the next character to lower or upper case, respectively:

    $x = "perl";
    $string =~ /\u$x/;  # matches 'Perl' in $string
    $x = "M(rs?|s)\\."; # note the double backslash
    $string =~ /\l$x/;  # matches 'mr.', 'mrs.', and 'ms.',

\L and \U converts a whole substring, delimited by \L or \U and \E, to lower or upper case:

    $x = "This word is in lower case:\L SHOUT\E";
    $x =~ /shout/;       # matches
    $x = "I STILL KEYPUNCH CARDS FOR MY 360"
    $x =~ /\Ukeypunch/;  # matches punch card string

If there is no \E, case is converted until the end of the string. The regexps \L\u$word or \u\L$word convert the first character of $word to uppercase and the rest of the characters to lowercase.

Control characters can be escaped with \c, so that a control-Z character would be matched with \cZ. The escape sequence \Q...\E quotes, or protects most non-alphabetic characters. For instance,

    $x = "\QThat !^*&%~& cat!";
    $x =~ /\Q!^*&%~&\E/;  # check for rough language

It does not protect $ or @, so that variables can still be substituted.

With the advent of 5.6.0, perl regexps can handle more than just the standard ASCII character set. Perl now supports Unicode, a standard for encoding the character sets from many of the world's written languages. Unicode does this by allowing characters to be more than one byte wide. Perl uses the UTF-8 encoding, in which ASCII characters are still encoded as one byte, but characters greater than chr(127) may be stored as two or more bytes.

What does this mean for regexps? Well, regexp users don't need to know much about perl's internal representation of strings. But they do need to know 1) how to represent Unicode characters in a regexp and 2) when a matching operation will treat the string to be searched as a sequence of bytes (the old way) or as a sequence of Unicode characters (the new way). The answer to 1) is that Unicode characters greater than chr(127) may be represented using the \x{hex} notation, with hex a hexadecimal integer:

    /\x{263a}/;  # match a Unicode smiley face :)

Unicode characters in the range of 128-255 use two hexadecimal digits with braces: \x{ab}. Note that this is different than \xab, which is just a hexadecimal byte with no Unicode significance.

NOTE: in Perl 5.6.0 it used to be that one needed to say use utf8 to use any Unicode features. This is no more the case: for almost all Unicode processing, the explicit utf8 pragma is not needed. (The only case where it matters is if your Perl script is in Unicode and encoded in UTF-8, then an explicit use utf8 is needed.)

Figuring out the hexadecimal sequence of a Unicode character you want or deciphering someone else's hexadecimal Unicode regexp is about as much fun as programming in machine code. So another way to specify Unicode characters is to use the named character escape sequence \N{name}. name is a name for the Unicode character, as specified in the Unicode standard. For instance, if we wanted to represent or match the astrological sign for the planet Mercury, we could use

    use charnames ":full"; # use named chars with Unicode full names
    $x = "abc\N{MERCURY}def";
    $x =~ /\N{MERCURY}/;   # matches

One can also use short names or restrict names to a certain alphabet:

    use charnames ':full';
    print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";

    use charnames ":short";
    print "\N{greek:Sigma} is an upper-case sigma.\n";

    use charnames qw(greek);
    print "\N{sigma} is Greek sigma\n";

A list of full names is found in the file Names.txt in the lib/perl5/5.X.X/unicore directory.

The answer to requirement 2), as of 5.6.0, is that if a regexp contains Unicode characters, the string is searched as a sequence of Unicode characters. Otherwise, the string is searched as a sequence of bytes. If the string is being searched as a sequence of Unicode characters, but matching a single byte is required, we can use the \C escape sequence. \C is a character class akin to . except that it matches any byte 0-255. So

    use charnames ":full"; # use named chars with Unicode full names
    $x = "a";
    $x =~ /\C/;  # matches 'a', eats one byte
    $x = "";
    $x =~ /\C/;  # doesn't match, no bytes to match
    $x = "\N{MERCURY}";  # two-byte Unicode character
    $x =~ /\C/;  # matches, but dangerous!

The last regexp matches, but is dangerous because the string character position is no longer synchronized to the string byte position. This generates the warning 'Malformed UTF-8 character'. The \C is best used for matching the binary data in strings with binary data intermixed with Unicode characters.

Let us now discuss the rest of the character classes. Just as with Unicode characters, there are named Unicode character classes represented by the \p{name} escape sequence. Closely associated is the \P{name} character class, which is the negation of the \p{name} class. For example, to match lower and uppercase characters,

    use charnames ":full"; # use named chars with Unicode full names
    $x = "BOB";
    $x =~ /^\p{IsUpper}/;   # matches, uppercase char class
    $x =~ /^\P{IsUpper}/;   # doesn't match, char class sans uppercase
    $x =~ /^\p{IsLower}/;   # doesn't match, lowercase char class
    $x =~ /^\P{IsLower}/;   # matches, char class sans lowercase

Here is the association between some Perl named classes and the traditional Unicode classes:

    Perl class name  Unicode class name or regular expression
    IsAlpha          /^[LM]/
    IsAlnum          /^[LMN]/
    IsASCII          $code <= 127
    IsCntrl          /^C/
    IsBlank          $code =~ /^(0020|0009)$/ || /^Z[^lp]/
    IsDigit          Nd
    IsGraph          /^([LMNPS]|Co)/
    IsLower          Ll
    IsPrint          /^([LMNPS]|Co|Zs)/
    IsPunct          /^P/
    IsSpace          /^Z/ || ($code =~ /^(0009|000A|000B|000C|000D)$/
    IsSpacePerl      /^Z/ || ($code =~ /^(0009|000A|000C|000D|0085|2028|2029)$/
    IsUpper          /^L[ut]/
    IsWord           /^[LMN]/ || $code eq "005F"
    IsXDigit         $code =~ /^00(3[0-9]|[46][1-6])$/

You can also use the official Unicode class names with the \p and \P, like \p{L} for Unicode 'letters', or \p{Lu} for uppercase letters, or \P{Nd} for non-digits. If a name is just one letter, the braces can be dropped. For instance, \pM is the character class of Unicode 'marks', for example accent marks. For the full list see the perlunicode manpage.

The Unicode has also been separated into various sets of characters which you can test with \p{In...} (in) and \P{In...} (not in), for example \p{Latin}, \p{Greek}, or \P{Katakana}. For the full list see the perlunicode manpage.

\X is an abbreviation for a character class sequence that includes the Unicode 'combining character sequences'. A 'combining character sequence' is a base character followed by any number of combining characters. An example of a combining character is an accent. Using the Unicode full names, e.g., A + COMBINING RING is a combining character sequence with base character A and combining character COMBINING RING , which translates in Danish to A with the circle atop it, as in the word Angstrom. \X is equivalent to \PM\pM*}, i.e., a non-mark followed by one or more marks.

For the full and latest information about Unicode see the latest Unicode standard, or the Unicode Consortium's website http://www.unicode.org/

As if all those classes weren't enough, Perl also defines POSIX style character classes. These have the form [:name:], with name the name of the POSIX class. The POSIX classes are alpha, alnum, ascii, cntrl, digit, graph, lower, print, punct, space, upper, and xdigit, and two extensions, word (a Perl extension to match \w), and blank (a GNU extension). If utf8 is being used, then these classes are defined the same as their corresponding perl Unicode classes: [:upper:] is the same as \p{IsUpper}, etc. The POSIX character classes, however, don't require using utf8. The [:digit:], [:word:], and [:space:] correspond to the familiar \d, \w, and \s character classes. To negate a POSIX class, put a ^ in front of the name, so that, e.g., [:^digit:] corresponds to \D and under utf8, \P{IsDigit}. The Unicode and POSIX character classes can be used just like \d, with the exception that POSIX character classes can only be used inside of a character class:

    /\s+[abc[:digit:]xyz]\s*/;  # match a,b,c,x,y,z, or a digit
    /^=item\s[[:digit:]]/;      # match '=item',
                                # followed by a space and a digit
    use charnames ":full";
    /\s+[abc\p{IsDigit}xyz]\s+/;  # match a,b,c,x,y,z, or a digit
    /^=item\s\p{IsDigit}/;        # match '=item',
                                  # followed by a space and a digit

Whew! That is all the rest of the characters and character classes.

Compiling and saving regular expressions

In Part 1 we discussed the //o modifier, which compiles a regexp just once. This suggests that a compiled regexp is some data structure that can be stored once and used again and again. The regexp quote qr// does exactly that: qr/string/ compiles the string as a regexp and transforms the result into a form that can be assigned to a variable:

    $reg = qr/foo+bar?/;  # reg contains a compiled regexp

Then $reg can be used as a regexp:

    $x = "fooooba";
    $x =~ $reg;     # matches, just like /foo+bar?/
    $x =~ /$reg/;   # same thing, alternate form

$reg can also be interpolated into a larger regexp:

    $x =~ /(abc)?$reg/;  # still matches

As with the matching operator, the regexp quote can use different delimiters, e.g., qr!!, qr{} and qr~~. The single quote delimiters qr'' prevent any interpolation from taking place.

Pre-compiled regexps are useful for creating dynamic matches that don't need to be recompiled each time they are encountered. Using pre-compiled regexps, simple_grep program can be expanded into a program that matches multiple patterns:

    % cat > multi_grep
    #!/usr/bin/perl
    # multi_grep - match any of <number> regexps
    # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
    $number = shift;
    $regexp[$_] = shift foreach (0..$number-1);
    @compiled = map qr/$_/, @regexp;
    while ($line = <>) {
        foreach $pattern (@compiled) {
            if ($line =~ /$pattern/) {
                print $line;
                last;  # we matched, so move onto the next line
            }
        }
    }
    ^D

    % multi_grep 2 last for multi_grep
        $regexp[$_] = shift foreach (0..$number-1);
            foreach $pattern (@compiled) {
                    last;

Storing pre-compiled regexps in an array @compiled allows us to simply loop through the regexps without any recompilation, thus gaining flexibility without sacrificing speed.

Embedding comments and modifiers in a regular expression

Starting with this section, we will be discussing Perl's set of extended patterns. These are extensions to the traditional regular expression syntax that provide powerful new tools for pattern matching. We have already seen extensions in the form of the minimal matching constructs ??, *?, +?, {n,m}?, and {n,}?. The rest of the extensions below have the form (?char...), where the char is a character that determines the type of extension.

The first extension is an embedded comment (?#text). This embeds a comment into the regular expression without affecting its meaning. The comment should not have any closing parentheses in the text. An example is

    /(?# Match an integer:)[+-]?\d+/;

This style of commenting has been largely superseded by the raw, freeform commenting that is allowed with the //x modifier.

The modifiers //i, //m, //s, and //x can also embedded in a regexp using (?i), (?m), (?s), and (?x). For instance,

    /(?i)yes/;  # match 'yes' case insensitively
    /yes/i;     # same thing
    /(?x)(          # freeform version of an integer regexp
             [+-]?  # match an optional sign
             \d+    # match a sequence of digits
         )
    /x;

Embedded modifiers can have two important advantages over the usual modifiers. Embedded modifiers allow a custom set of modifiers to each regexp pattern. This is great for matching an array of regexps that must have different modifiers:

    $pattern[0] = '(?i)doctor';
    $pattern[1] = 'Johnson';
    ...
    while (<>) {
        foreach $patt (@pattern) {
            print if /$patt/;
        }
    }

The second advantage is that embedded modifiers only affect the regexp inside the group the embedded modifier is contained in. So grouping can be used to localize the modifier's effects:

    /Answer: ((?i)yes)/;  # matches 'Answer: yes', 'Answer: YES', etc.

Embedded modifiers can also turn off any modifiers already present by using, e.g., (?-i). Modifiers can also be combined into a single expression, e.g., (?s-i) turns on single line mode and turns off case insensitivity.

Non-capturing groupings

We noted in Part 1 that groupings () had two distinct functions: 1) group regexp elements together as a single unit, and 2) extract, or capture, substrings that matched the regexp in the grouping. Non-capturing groupings, denoted by (?:regexp), allow the regexp to be treated as a single unit, but don't extract substrings or set matching variables $1, etc. Both capturing and non-capturing groupings are allowed to co-exist in the same regexp. Because there is no extraction, non-capturing groupings are faster than capturing groupings. Non-capturing groupings are also handy for choosing exactly which parts of a regexp are to be extracted to matching variables:

    # match a number, $1-$4 are set, but we only want $1
    /([+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?)/;

    # match a number faster , only $1 is set
    /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/;

    # match a number, get $1 = whole number, $2 = exponent
    /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?)/;

Non-capturing groupings are also useful for removing nuisance elements gathered from a split operation:

    $x = '12a34b5';
    @num = split /(a|b)/, $x;    # @num = ('12','a','34','b','5')
    @num = split /(?:a|b)/, $x;  # @num = ('12','34','5')

Non-capturing groupings may also have embedded modifiers: (?i-m:regexp) is a non-capturing grouping that matches regexp case insensitively and turns off multi-line mode.

Looking ahead and looking behind

This section concerns the lookahead and lookbehind assertions. First, a little background.

In Perl regular expressions, most regexp elements 'eat up' a certain amount of string when they match. For instance, the regexp element [abc}] eats up one character of the string when it matches, in the sense that perl moves to the next character position in the string after the match. There are some elements, however, that don't eat up characters (advance the character position) if they match. The examples we have seen so far are the anchors. The anchor ^ matches the beginning of the line, but doesn't eat any characters. Similarly, the word boundary anchor \b matches, e.g., if the character to the left is a word character and the character to the right is a non-word character, but it doesn't eat up any characters itself. Anchors are examples of 'zero-width assertions'. Zero-width, because they consume no characters, and assertions, because they test some property of the string. In the context of our walk in the woods analogy to regexp matching, most regexp elements move us along a trail, but anchors have us stop a moment and check our surroundings. If the local environment checks out, we can proceed forward. But if the local environment doesn't satisfy us, we must backtrack.

Checking the environment entails either looking ahead on the trail, looking behind, or both. ^ looks behind, to see that there are no characters before. $ looks ahead, to see that there are no characters after. \b looks both ahead and behind, to see if the characters on either side differ in their 'word'-ness.

The lookahead and lookbehind assertions are generalizations of the anchor concept. Lookahead and lookbehind are zero-width assertions that let us specify which characters we want to test for. The lookahead assertion is denoted by (?=regexp) and the lookbehind assertion is denoted by (?<=fixed-regexp). Some examples are

    $x = "I catch the housecat 'Tom-cat' with catnip";
    $x =~ /cat(?=\s+)/;  # matches 'cat' in 'housecat'
    @catwords = ($x =~ /(?<=\s)cat\w+/g);  # matches,
                                           # $catwords[0] = 'catch'
                                           # $catwords[1] = 'catnip'
    $x =~ /\bcat\b/;  # matches 'cat' in 'Tom-cat'
    $x =~ /(?<=\s)cat(?=\s)/; # doesn't match; no isolated 'cat' in
                              # middle of $x

Note that the parentheses in (?=regexp) and (?<=regexp) are non-capturing, since these are zero-width assertions. Thus in the second regexp, the substrings captured are those of the whole regexp itself. Lookahead (?=regexp) can match arbitrary regexps, but lookbehind (?<=fixed-regexp) only works for regexps of fixed width, i.e., a fixed number of characters long. Thus (?<=(ab|bc)) is fine, but (?<=(ab)*) is not. The negated versions of the lookahead and lookbehind assertions are denoted by (?!regexp) and (?<!fixed-regexp) respectively. They evaluate true if the regexps do not match:

    $x = "foobar";
    $x =~ /foo(?!bar)/;  # doesn't match, 'bar' follows 'foo'
    $x =~ /foo(?!baz)/;  # matches, 'baz' doesn't follow 'foo'
    $x =~ /(?<!\s)foo/;  # matches, there is no \s before 'foo'

The \C is unsupported in lookbehind, because the already treacherous definition of \C would become even more so when going backwards.

Using independent subexpressions to prevent backtracking

The last few extended patterns in this tutorial are experimental as of 5.6.0. Play with them, use them in some code, but don't rely on them just yet for production code.

Independent subexpressions are regular expressions, in the context of a larger regular expression, that function independently of the larger regular expression. That is, they consume as much or as little of the string as they wish without regard for the ability of the larger regexp to match. Independent subexpressions are represented by (?>regexp). We can illustrate their behavior by first considering an ordinary regexp:

    $x = "ab";
    $x =~ /a*ab/;  # matches

This obviously matches, but in the process of matching, the subexpression a* first grabbed the a. Doing so, however, wouldn't allow the whole regexp to match, so after backtracking, a* eventually gave back the a and matched the empty string. Here, what a* matched was dependent on what the rest of the regexp matched.

Contrast that with an independent subexpression:

    $x =~ /(?>a*)ab/;  # doesn't match!

The independent subexpression (?>a*) doesn't care about the rest of the regexp, so it sees an a and grabs it. Then the rest of the regexp ab cannot match. Because (?>a*) is independent, there is no backtracking and the independent subexpression does not give up its a. Thus the match of the regexp as a whole fails. A similar behavior occurs with completely independent regexps:

    $x = "ab";
    $x =~ /a*/g;   # matches, eats an 'a'
    $x =~ /\Gab/g; # doesn't match, no 'a' available

Here //g and \G create a 'tag team' handoff of the string from one regexp to the other. Regexps with an independent subexpression are much like this, with a handoff of the string to the independent subexpression, and a handoff of the string back to the enclosing regexp.

The ability of an independent subexpression to prevent backtracking can be quite useful. Suppose we want to match a non-empty string enclosed in parentheses up to two levels deep. Then the following regexp matches:

    $x = "abc(de(fg)h";  # unbalanced parentheses
    $x =~ /\( ( [^()]+ | \([^()]*\) )+ \)/x;

The regexp matches an open parenthesis, one or more copies of an alternation, and a close parenthesis. The alternation is two-way, with the first alternative [^()]+ matching a substring with no parentheses and the second alternative \([^()]*\) matching a substring delimited by parentheses. The problem with this regexp is that it is pathological: it has nested indeterminate quantifiers of the form (a+|b)+. We discussed in Part 1 how nested quantifiers like this could take an exponentially long time to execute if there was no match possible. To prevent the exponential blowup, we need to prevent useless backtracking at some point. This can be done by enclosing the inner quantifier as an independent subexpression:

    $x =~ /\( ( (?>[^()]+) | \([^()]*\) )+ \)/x;

Here, (?>[^()]+) breaks the degeneracy of string partitioning by gobbling up as much of the string as possible and keeping it. Then match failures fail much more quickly.

Conditional expressions

A conditional expression is a form of if-then-else statement that allows one to choose which patterns are to be matched, based on some condition. There are two types of conditional expression: (?(condition)yes-regexp) and (?(condition)yes-regexp|no-regexp). (?(condition)yes-regexp) is like an 'if () {}' statement in Perl. If the condition is true, the yes-regexp will be matched. If the condition is false, the yes-regexp will be skipped and perl will move onto the next regexp element. The second form is like an 'if () {} else {}' statement in Perl. If the condition is true, the yes-regexp will be matched, otherwise the no-regexp will be matched.

The condition can have two forms. The first form is simply an integer in parentheses (integer). It is true if the corresponding backreference \integer matched earlier in the regexp. The second form is a bare zero width assertion (?...), either a lookahead, a lookbehind, or a code assertion (discussed in the next section).

The integer form of the condition allows us to choose, with more flexibility, what to match based on what matched earlier in the regexp. This searches for words of the form "$x$x" or "$x$y$y$x":

    % simple_grep '^(\w+)(\w+)?(?(2)\2\1|\1)$' /usr/dict/words
    beriberi
    coco
    couscous
    deed
    ...
    toot
    toto
    tutu

The lookbehind condition allows, along with backreferences, an earlier part of the match to influence a later part of the match. For instance,

    /[ATGC]+(?(?<=AA)G|C)$/;

matches a DNA sequence such that it either ends in AAG, or some other base pair combination and C. Note that the form is (?(?<=AA)G|C) and not (?((?<=AA))G|C); for the lookahead, lookbehind or code assertions, the parentheses around the conditional are not needed.

A bit of magic: executing Perl code in a regular expression

Normally, regexps are a part of Perl expressions. Code evaluation expressions turn that around by allowing arbitrary Perl code to be a part of a regexp. A code evaluation expression is denoted (?{code}), with code a string of Perl statements.

Code expressions are zero-width assertions, and the value they return depends on their environment. There are two possibilities: either the code expression is used as a conditional in a conditional expression (?(condition)...), or it is not. If the code expression is a conditional, the code is evaluated and the result (i.e., the result of the last statement) is used to determine truth or falsehood. If the code expression is not used as a conditional, the assertion always evaluates true and the result is put into the special variable $^R. The variable $^R can then be used in code expressions later in the regexp. Here are some silly examples:

    $x = "abcdef";
    $x =~ /abc(?{print "Hi Mom!";})def/; # matches,
                                         # prints 'Hi Mom!'
    $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn't match,
                                         # no 'Hi Mom!'

Pay careful attention to the next example:

    $x =~ /abc(?{print "Hi Mom!";})ddd/; # doesn't match,
                                         # no 'Hi Mom!'
                                         # but why not?

At first glance, you'd think that it shouldn't print, because obviously the ddd isn't going to match the target string. But look at this example:

    $x =~ /abc(?{print "Hi Mom!";})[d]dd/; # doesn't match,
                                           # but _does_ print

Hmm. What happened here? If you've been following along, you know that the above pattern should be effectively the same as the last one -- enclosing the d in a character class isn't going to change what it matches. So why does the first not print while the second one does?

The answer lies in the optimizations the REx engine makes. In the first case, all the engine sees are plain old characters (aside from the ?{} construct). It's smart enough to realize that the string 'ddd' doesn't occur in our target string before actually running the pattern through. But in the second case, we've tricked it into thinking that our pattern is more complicated than it is. It takes a look, sees our character class, and decides that it will have to actually run the pattern to determine whether or not it matches, and in the process of running it hits the print statement before it discovers that we don't have a match.

To take a closer look at how the engine does optimizations, see the section Pragmas and debugging below.

More fun with ?{}:

    $x =~ /(?{print "Hi Mom!";})/;       # matches,
                                         # prints 'Hi Mom!'
    $x =~ /(?{$c = 1;})(?{print "$c";})/;  # matches,
                                           # prints '1'
    $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches,
                                           # prints '1'

The bit of magic mentioned in the section title occurs when the regexp backtracks in the process of searching for a match. If the regexp backtracks over a code expression and if the variables used within are localized using local, the changes in the variables produced by the code expression are undone! Thus, if we wanted to count how many times a character got matched inside a group, we could use, e.g.,

    $x = "aaaa";
    $count = 0;  # initialize 'a' count
    $c = "bob";  # test if $c gets clobbered
    $x =~ /(?{local $c = 0;})         # initialize count
           ( a                        # match 'a'
             (?{local $c = $c + 1;})  # increment count
           )*                         # do this any number of times,
           aa                         # but match 'aa' at the end
           (?{$count = $c;})          # copy local $c var into $count
          /x;
    print "'a' count is $count, \$c variable is '$c'\n";

This prints

    'a' count is 2, $c variable is 'bob'

If we replace the  (?{local $c = $c + 1;}) with  (?{$c = $c + 1;}) , the variable changes are not undone during backtracking, and we get

    'a' count is 4, $c variable is 'bob'

Note that only localized variable changes are undone. Other side effects of code expression execution are permanent. Thus

    $x = "aaaa";
    $x =~ /(a(?{print "Yow\n";}))*aa/;

produces

   Yow
   Yow
   Yow
   Yow

The result $^R is automatically localized, so that it will behave properly in the presence of backtracking.

This example uses a code expression in a conditional to match the article 'the' in either English or German:

    $lang = 'DE';  # use German
    ...
    $text = "das";
    print "matched\n"
        if $text =~ /(?(?{
                          $lang eq 'EN'; # is the language English?
                         })
                       the |             # if so, then match 'the'
                       (die|das|der)     # else, match 'die|das|der'
                     )
                    /xi;

Note that the syntax here is (?(?{...})yes-regexp|no-regexp), not (?((?{...}))yes-regexp|no-regexp). In other words, in the case of a code expression, we don't need the extra parentheses around the conditional.

If you try to use code expressions with interpolating variables, perl may surprise you:

    $bar = 5;
    $pat = '(?{ 1 })';
    /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
    /foo(?{ 1 })$bar/;   # compile error!
    /foo${pat}bar/;      # compile error!

    $pat = qr/(?{ $foo = 1 })/;  # precompile code regexp
    /foo${pat}bar/;      # compiles ok

If a regexp has (1) code expressions and interpolating variables, or (2) a variable that interpolates a code expression, perl treats the regexp as an error. If the code expression is precompiled into a variable, however, interpolating is ok. The question is, why is this an error?

The reason is that variable interpolation and code expressions together pose a security risk. The combination is dangerous because many programmers who write search engines often take user input and plug it directly into a regexp:

    $regexp = <>;       # read user-supplied regexp
    $chomp $regexp;     # get rid of possible newline
    $text =~ /$regexp/; # search $text for the $regexp

If the $regexp variable contains a code expression, the user could then execute arbitrary Perl code. For instance, some joker could search for system('rm -rf *'); to erase your files. In this sense, the combination of interpolation and code expressions taints your regexp. So by default, using both interpolation and code expressions in the same regexp is not allowed. If you're not concerned about malicious users, it is possible to bypass this security check by invoking use re 'eval' :

    use re 'eval';       # throw caution out the door
    $bar = 5;
    $pat = '(?{ 1 })';
    /foo(?{ 1 })$bar/;   # compiles ok
    /foo${pat}bar/;      # compiles ok

Another form of code expression is the pattern code expression . The pattern code expression is like a regular code expression, except that the result of the code evaluation is treated as a regular expression and matched immediately. A simple example is

    $length = 5;
    $char = 'a';
    $x = 'aaaaabb';
    $x =~ /(??{$char x $length})/x; # matches, there are 5 of 'a'

This final example contains both ordinary and pattern code expressions. It detects if a binary string 1101010010001... has a Fibonacci spacing 0,1,1,2,3,5,... of the 1's:

    $s0 = 0; $s1 = 1; # initial conditions
    $x = "1101010010001000001";
    print "It is a Fibonacci sequence\n"
        if $x =~ /^1         # match an initial '1'
                    (
                       (??{'0' x $s0}) # match $s0 of '0'
                       1               # and then a '1'
                       (?{
                          $largest = $s0;   # largest seq so far
                          $s2 = $s1 + $s0;  # compute next term
                          $s0 = $s1;        # in Fibonacci sequence
                          $s1 = $s2;
                         })
                    )+   # repeat as needed
                  $      # that is all there is
                 /x;
    print "Largest sequence matched was $largest\n";

This prints

    It is a Fibonacci sequence
    Largest sequence matched was 5

Ha! Try that with your garden variety regexp package...

Note that the variables $s0 and $s1 are not substituted when the regexp is compiled, as happens for ordinary variables outside a code expression. Rather, the code expressions are evaluated when perl encounters them during the search for a match.

The regexp without the //x modifier is

    /^1((??{'0'x$s0})1(?{$largest=$s0;$s2=$s1+$s0$s0=$s1;$s1=$s2;}))+$/;

and is a great start on an Obfuscated Perl entry :-) When working with code and conditional expressions, the extended form of regexps is almost necessary in creating and debugging regexps.

Pragmas and debugging

Speaking of debugging, there are several pragmas available to control and debug regexps in Perl. We have already encountered one pragma in the previous section, use re 'eval'; , that allows variable interpolation and code expressions to coexist in a regexp. The other pragmas are

    use re 'taint';
    $tainted = <>;
    @parts = ($tainted =~ /(\w+)\s+(\w+)/; # @parts is now tainted

The taint pragma causes any substrings from a match with a tainted variable to be tainted as well. This is not normally the case, as regexps are often used to extract the safe bits from a tainted variable. Use taint when you are not extracting safe bits, but are performing some other processing. Both taint and eval pragmas are lexically scoped, which means they are in effect only until the end of the block enclosing the pragmas.

    use re 'debug';
    /^(.*)$/s;       # output debugging info

    use re 'debugcolor';
    /^(.*)$/s;       # output debugging info in living color

The global debug and debugcolor pragmas allow one to get detailed debugging info about regexp compilation and execution. debugcolor is the same as debug, except the debugging information is displayed in color on terminals that can display termcap color sequences. Here is example output:

    % perl -e 'use re "debug"; "abc" =~ /a*b+c/;'
    Compiling REx `a*b+c'
    size 9 first at 1
       1: STAR(4)
       2:   EXACT <a>(0)
       4: PLUS(7)
       5:   EXACT <b>(0)
       7: EXACT <c>(9)
       9: END(0)
    floating `bc' at 0..2147483647 (checking floating) minlen 2
    Guessing start of match, REx `a*b+c' against `abc'...
    Found floating substr `bc' at offset 1...
    Guessed: match at offset 0
    Matching REx `a*b+c' against `abc'
      Setting an EVAL scope, savestack=3
       0 <> <abc>             |  1:  STAR
                               EXACT <a> can match 1 times out of 32767...
      Setting an EVAL scope, savestack=3
       1 <a> <bc>             |  4:    PLUS
                               EXACT <b> can match 1 times out of 32767...
      Setting an EVAL scope, savestack=3
       2 <ab> <c>             |  7:      EXACT <c>
       3 <abc> <>             |  9:      END
    Match successful!
    Freeing REx: `a*b+c'

If you have gotten this far into the tutorial, you can probably guess what the different parts of the debugging output tell you. The first part

    Compiling REx `a*b+c'
    size 9 first at 1
       1: STAR(4)
       2:   EXACT <a>(0)
       4: PLUS(7)
       5:   EXACT <b>(0)
       7: EXACT <c>(9)
       9: END(0)

describes the compilation stage. STAR(4) means that there is a starred object, in this case 'a', and if it matches, goto line 4, i.e., PLUS(7). The middle lines describe some heuristics and optimizations performed before a match:

    floating `bc' at 0..2147483647 (checking floating) minlen 2
    Guessing start of match, REx `a*b+c' against `abc'...
    Found floating substr `bc' at offset 1...
    Guessed: match at offset 0

Then the match is executed and the remaining lines describe the process:

    Matching REx `a*b+c' against `abc'
      Setting an EVAL scope, savestack=3
       0 <> <abc>             |  1:  STAR
                               EXACT <a> can match 1 times out of 32767...
      Setting an EVAL scope, savestack=3
       1 <a> <bc>             |  4:    PLUS
                               EXACT <b> can match 1 times out of 32767...
      Setting an EVAL scope, savestack=3
       2 <ab> <c>             |  7:      EXACT <c>
       3 <abc> <>             |  9:      END
    Match successful!
    Freeing REx: `a*b+c'

Each step is of the form n <x> <y> , with <x> the part of the string matched and <y> the part not yet matched. The |  1:  STAR says that perl is at line number 1 n the compilation list above. See Debugging regular expressions in the perldebguts manpage for much more detail.

An alternative method of debugging regexps is to embed print statements within the regexp. This provides a blow-by-blow account of the backtracking in an alternation:

    "that this" =~ m@(?{print "Start at position ", pos, "\n";})
                     t(?{print "t1\n";})
                     h(?{print "h1\n";})
                     i(?{print "i1\n";})
                     s(?{print "s1\n";})
                         |
                     t(?{print "t2\n";})
                     h(?{print "h2\n";})
                     a(?{print "a2\n";})
                     t(?{print "t2\n";})
                     (?{print "Done at position ", pos, "\n";})
                    @x;

prints

    Start at position 0
    t1
    h1
    t2
    h2
    a2
    t2
    Done at position 4

BUGS

Code expressions, conditional expressions, and independent expressions are experimental. Don't use them in production code. Yet.

SEE ALSO

This is just a tutorial. For the full story on perl regular expressions, see the the perlre manpage regular expressions reference page.

For more information on the matching m// and substitution s/// operators, see Regexp Quote-Like Operators in the perlop manpage. For information on the split operation, see split in the perlfunc manpage.

For an excellent all-around resource on the care and feeding of regular expressions, see the book Mastering Regular Expressions by Jeffrey Friedl (published by O'Reilly, ISBN 1556592-257-3).

AUTHOR AND COPYRIGHT

Copyright (c) 2000 Mark Kvale All rights reserved.

This document may be distributed under the same terms as Perl itself.

Acknowledgments

The inspiration for the stop codon DNA example came from the ZIP code example in chapter 7 of Mastering Regular Expressions.

The author would like to thank Jeff Pinyan, Andrew Johnson, Peter Haworth, Ronald J Kimball, and Joe Smith for all their helpful comments.


perlfaq - frequently asked questions about Perl

    • Where to get the perlfaq
    • How to contribute to the perlfaq
    • What will happen if you mail your Perl programming problems to the authors?
  • CREDITS
  • AUTHOR AND COPYRIGHT
  • Table of Contents
  • The Questions
    • the perlfaq1 manpage: General Questions About Perl
    • the perlfaq2 manpage: Obtaining and Learning about Perl
    • the perlfaq3 manpage: Programming Tools
    • the perlfaq4 manpage: Data Manipulation
    • the perlfaq5 manpage: Files and Formats
    • the perlfaq6 manpage: Regular Expressions
    • the perlfaq7 manpage: General Perl Language Issues
    • the perlfaq8 manpage: System Interaction
    • the perlfaq9 manpage: Networking

NAME

perlfaq - frequently asked questions about Perl

DESCRIPTION

The perlfaq comprises several documents that answer the most commonly asked questions about Perl and Perl programming. It's divided by topic into nine major sections outlined in this document.

Where to get the perlfaq

The perlfaq comes with the standard Perl distribution, so if you have Perl you should have the perlfaq. You should also have the perldoc tool that let's you read the the perlfaq manpage:

        $ perldoc perlfaq

Besides your local system, you can find the perlfaq on the web, including at http://perldoc.perl.org/ .

The perlfaq is an evolving document and you can read the latest version at http://faq.perl.org/ . The perlfaq-workers periodically post extracts of the latest perlfaq to comp.lang.perl.misc.

You can view the source tree at http://cvs.perl.org/viewcvs/cvs-public/perlfaq/ (which is outside of the main Perl source tree). The CVS repository notes all changes to the FAQ and holds the latest version of the working documents and may vary significantly from the version distributed with the latest version of Perl. Check the repository before sending your corrections.

How to contribute to the perlfaq

You can mail corrections, additions, and suggestions to <perlfaq-workers AT perl DOT org>. The perlfaq volunteers use this address to coordinate their efforts and track the perlfaq development. They appreciate your contributions to the FAQ but do not have time to provide individual help, so don't use this address to ask FAQs.

The perlfaq server posts extracts of the perlfaq to that newsgroup every 6 hours (or so), and the community of volunteers reviews and updates the answers. If you'd like to help review and update the answers, check out comp.lang.perl.misc.

What will happen if you mail your Perl programming problems to the authors?

The perlfaq-workers like to keep all traffic on the perlfaq-workers list so that everyone can see the work being done (and the work that needs to be done). The mailing list serves as an official record. If you email the authors or maintainers directly, you'll probably get a reply asking you to post to the mailing list. If you don't get a reply, it probably means that the person never saw the message or didn't have time to deal with it. Posting to the list allows the volunteers with time to deal with it when others are busy.

If you have a question that isn't in the FAQ and you would like help with it, try the resources in the perlfaq2 manpage.

CREDITS

Tom Christiansen wrote the original perlfaq then expanded it with the help of Nat Torkington. The perlfaq-workers maintain current document and the dezinens of comp.lang.perl.misc regularly review and update the FAQ. Several people have contributed answers, corrections, and comments, and the perlfaq notes those contributions wherever appropriate.

AUTHOR AND COPYRIGHT

Tom Christainsen wrote the original version of this document. brian d foy <bdfoy@cpan.org> wrote this version. See the individual perlfaq documents for additional copyright information.

This document is available under the same terms as Perl itself. Code examples in all the perlfaq documents are in the public domain. Use them as you see fit (and at your own risk with no warranty from anyone).

Table of Contents

perlfaq - this document
perlfaq1 - General Questions About Perl
perlfaq2 - Obtaining and Learning about Perl
perlfaq3 - Programming Tools
perlfaq4 - Data Manipulation
perlfaq5 - Files and Formats
perlfaq6 - Regular Expressions
perlfaq7 - General Perl Language Issues
perlfaq8 - System Interaction
perlfaq9 - Networking

The Questions

the perlfaq1 manpage: General Questions About Perl

Very general, high-level questions about Perl.

  • What is Perl?

  • Who supports Perl? Who develops it? Why is it free?

  • Which version of Perl should I use?

  • What are perl4, perl5, or perl6?

  • What is Ponie?

  • What is perl6?

  • How stable is Perl?

  • Is Perl difficult to learn?

  • How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?

  • Can I do [task] in Perl?

  • When shouldn't I program in Perl?

  • What's the difference between "perl" and "Perl"?

  • Is it a Perl program or a Perl script?

  • What is a JAPH?

  • Where can I get a list of Larry Wall witticisms?

  • How can I convince my sysadmin/supervisor/employees to use version 5/5.6.1/Perl instead of some other language?

the perlfaq2 manpage: Obtaining and Learning about Perl

Where to find source and documentation for Perl, support, and related matters.

  • What machines support perl? Where do I get it?

  • How can I get a binary version of perl?

  • I don't have a C compiler. How can I build my own Perl interpreter?

  • I copied the perl binary from one machine to another, but scripts don't work.

  • I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?

  • What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean?

  • Is there an ISO or ANSI certified version of Perl?

  • Where can I get information on Perl?

  • What are the Perl newsgroups on Usenet? Where do I post questions?

  • Where should I post source code?

  • Perl Books

  • Which magazines have Perl content?

  • What mailing lists are there for Perl?

  • Where are the archives for comp.lang.perl.misc?

  • Where can I buy a commercial version of perl?

  • Where do I send bug reports?

  • What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?

the perlfaq3 manpage: Programming Tools

Programmer tools and programming support.

  • How do I do (anything)?

  • How can I use Perl interactively?

  • Is there a Perl shell?

  • How do I find which modules are installed on my system?

  • How do I debug my Perl programs?

  • How do I profile my Perl programs?

  • How do I cross-reference my Perl programs?

  • Is there a pretty-printer (formatter) for Perl?

  • Is there a ctags for Perl?

  • Is there an IDE or Windows Perl Editor?

  • Where can I get Perl macros for vi?

  • Where can I get perl-mode for emacs?

  • How can I use curses with Perl?

  • How can I use X or Tk with Perl?

  • How can I make my Perl program run faster?

  • How can I make my Perl program take less memory?

  • Is it safe to return a reference to local or lexical data?

  • How can I free an array or hash so my program shrinks?

  • How can I make my CGI script more efficient?

  • How can I hide the source for my Perl program?

  • How can I compile my Perl program into byte code or C?

  • How can I compile Perl into Java?

  • How can I get #!perl to work on [MS-DOS,NT,...]?

  • Can I write useful Perl programs on the command line?

  • Why don't Perl one-liners work on my DOS/Mac/VMS system?

  • Where can I learn about CGI or Web programming in Perl?

  • Where can I learn about object-oriented Perl programming?

  • Where can I learn about linking C with Perl?

  • I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?

  • When I tried to run my script, I got this message. What does it mean?

  • What's MakeMaker?

the perlfaq4 manpage: Data Manipulation

Manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.

  • Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?

  • Why is int() broken?

  • Why isn't my octal data interpreted correctly?

  • Does Perl have a round() function? What about ceil() and floor()? Trig functions?

  • How do I convert between numeric representations/bases/radixes?

  • Why doesn't & work the way I want it to?

  • How do I multiply matrices?

  • How do I perform an operation on a series of integers?

  • How can I output Roman numerals?

  • Why aren't my random numbers random?

  • How do I get a random number between X and Y?

  • How do I find the day or week of the year?

  • How do I find the current century or millennium?

  • How can I compare two dates and find the difference?

  • How can I take a string and turn it into epoch seconds?

  • How can I find the Julian Day?

  • How do I find yesterday's date?

  • Does Perl have a Year 2000 problem? Is Perl Y2K compliant?

  • How do I validate input?

  • How do I unescape a string?

  • How do I remove consecutive pairs of characters?

  • How do I expand function calls in a string?

  • How do I find matching/nesting anything?

  • How do I reverse a string?

  • How do I expand tabs in a string?

  • How do I reformat a paragraph?

  • How can I access or change N characters of a string?

  • How do I change the Nth occurrence of something?

  • How can I count the number of occurrences of a substring within a string?

  • How do I capitalize all the words on one line?

  • How can I split a [character] delimited string except when inside [character]?

  • How do I strip blank space from the beginning/end of a string?

  • How do I pad a string with blanks or pad a number with zeroes?

  • How do I extract selected columns from a string?

  • How do I find the soundex value of a string?

  • How can I expand variables in text strings?

  • What's wrong with always quoting "$vars"?

  • Why don't my <<HERE documents work?

  • What is the difference between a list and an array?

  • What is the difference between $array[1] and @array[1]?

  • How can I remove duplicate elements from a list or array?

  • How can I tell whether a certain element is contained in a list or array?

  • How do I compute the difference of two arrays? How do I compute the intersection of two arrays?

  • How do I test whether two arrays or hashes are equal?

  • How do I find the first array element for which a condition is true?

  • How do I handle linked lists?

  • How do I handle circular lists?

  • How do I shuffle an array randomly?

  • How do I process/modify each element of an array?

  • How do I select a random element from an array?

  • How do I permute N elements of a list?

  • How do I sort an array by (anything)?

  • How do I manipulate arrays of bits?

  • Why does defined() return true on empty arrays and hashes?

  • How do I process an entire hash?

  • What happens if I add or remove keys from a hash while iterating over it?

  • How do I look up a hash element by value?

  • How can I know how many entries are in a hash?

  • How do I sort a hash (optionally by value instead of key)?

  • How can I always keep my hash sorted?

  • What's the difference between "delete" and "undef" with hashes?

  • Why don't my tied hashes make the defined/exists distinction?

  • How do I reset an each() operation part-way through?

  • How can I get the unique keys from two hashes?

  • How can I store a multidimensional array in a DBM file?

  • How can I make my hash remember the order I put elements into it?

  • Why does passing a subroutine an undefined element in a hash create it?

  • How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?

  • How can I use a reference as a hash key?

  • How do I handle binary data correctly?

  • How do I determine whether a scalar is a number/whole/integer/float?

  • How do I keep persistent data across program calls?

  • How do I print out or copy a recursive data structure?

  • How do I define methods for every class/object?

  • How do I verify a credit card checksum?

  • How do I pack arrays of doubles or floats for XS code?

the perlfaq5 manpage: Files and Formats

I/O and the "f" issues: filehandles, flushing, formats, and footers.

  • How do I flush/unbuffer an output filehandle? Why must I do this?

  • How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?

  • How do I count the number of lines in a file?

  • How can I use Perl's -i option from within a program?

  • How can I copy a file?

  • How do I make a temporary file name?

  • How can I manipulate fixed-record-length files?

  • How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?

  • How can I use a filehandle indirectly?

  • How can I set up a footer format to be used with write()?

  • How can I write() into a string?

  • How can I output my numbers with commas added?

  • How can I translate tildes (~) in a filename?

  • How come when I open a file read-write it wipes it out?

  • Why do I sometimes get an "Argument list too long" when I use <*>?

  • Is there a leak/bug in glob()?

  • How can I open a file with a leading ">" or trailing blanks?

  • How can I reliably rename a file?

  • How can I lock a file?

  • Why can't I just open(FH, ">file.lock")?

  • I still don't get locking. I just want to increment the number in the file. How can I do this?

  • All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?

  • How do I randomly update a binary file?

  • How do I get a file's timestamp in perl?

  • How do I set a file's timestamp in perl?

  • How do I print to more than one file at once?

  • How can I read in an entire file all at once?

  • How can I read in a file by paragraphs?

  • How can I read a single character from a file? From the keyboard?

  • How can I tell whether there's a character waiting on a filehandle?

  • How do I do a tail -f in perl?

  • How do I dup() a filehandle in Perl?

  • How do I close a file descriptor by number?

  • Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?

  • Why doesn't glob("*.*") get all the files?

  • Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?

  • How do I select a random line from a file?

  • Why do I get weird spaces when I print an array of lines?

the perlfaq6 manpage: Regular Expressions

This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number are handled with regular expressions, but those answers are found elsewhere in this document (in the perlfaq9 manpage: "How do I decode or create those %-encodings on the web" and the perlfaq4 manpage: "How do I determine whether a scalar is a number/whole/integer/float", to be precise).

  • How can I hope to use regular expressions without creating illegible and unmaintainable code?

  • I'm having trouble matching over more than one line. What's wrong?

  • How can I pull out lines between two patterns that are themselves on different lines?

  • I put a regular expression into $/ but it didn't work. What's wrong?

  • How do I substitute case insensitively on the LHS while preserving case on the RHS?

  • How can I make \w match national character sets?

  • How can I match a locale-smart version of /[a-zA-Z]/?

  • How can I quote a variable to use in a regex?

  • What is /o really for?

  • How do I use a regular expression to strip C style comments from a file?

  • Can I use Perl regular expressions to match balanced text?

  • What does it mean that regexes are greedy? How can I get around it?

  • How do I process each word on each line?

  • How can I print out a word-frequency or line-frequency summary?

  • How can I do approximate matching?

  • How do I efficiently match many regular expressions at once?

  • Why don't word-boundary searches with \b work for me?

  • Why does using $&, $`, or $' slow my program down?

  • What good is \G in a regular expression?

  • Are Perl regexes DFAs or NFAs? Are they POSIX compliant?

  • What's wrong with using grep in a void context?

  • How can I match strings with multibyte characters?

  • How do I match a pattern that is supplied by the user?

the perlfaq7 manpage: General Perl Language Issues

General Perl language issues that don't clearly fit into any of the other sections.

  • Can I get a BNF/yacc/RE for the Perl language?

  • What are all these $@%&* punctuation signs, and how do I know when to use them?

  • Do I always/never have to quote my strings or use semicolons and commas?

  • How do I skip some return values?

  • How do I temporarily block warnings?

  • What's an extension?

  • Why do Perl operators have different precedence than C operators?

  • How do I declare/create a structure?

  • How do I create a module?

  • How do I create a class?

  • How can I tell if a variable is tainted?

  • What's a closure?

  • What is variable suicide and how can I prevent it?

  • How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?

  • How do I create a static variable?

  • What's the difference between dynamic and lexical (static) scoping? Between local() and my()?

  • How can I access a dynamic variable while a similarly named lexical is in scope?

  • What's the difference between deep and shallow binding?

  • Why doesn't "my($foo) = <FILE>;" work right?

  • How do I redefine a builtin function, operator, or method?

  • What's the difference between calling a function as &foo and foo()?

  • How do I create a switch or case statement?

  • How can I catch accesses to undefined variables, functions, or methods?

  • Why can't a method included in this same file be found?

  • How can I find out my current package?

  • How can I comment out a large block of perl code?

  • How do I clear a package?

  • How can I use a variable as a variable name?

  • What does "bad interpreter" mean?

the perlfaq8 manpage: System Interaction

This section of the Perl FAQ covers questions involving operating system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation. Read the FAQs and documentation specific to the port of perl to your operating system (eg, the perlvms manpage, the perlplan9 manpage, ...). These should contain more detailed information on the vagaries of your perl.

  • How do I find out which operating system I'm running under?

  • How come exec() doesn't return?

  • How do I do fancy stuff with the keyboard/screen/mouse?

  • How do I print something out in color?

  • How do I read just one key without waiting for a return key?

  • How do I check whether input is ready on the keyboard?

  • How do I clear the screen?

  • How do I get the screen size?

  • How do I ask the user for a password?

  • How do I read and write the serial port?

  • How do I decode encrypted password files?

  • How do I start a process in the background?

  • How do I trap control characters/signals?

  • How do I modify the shadow password file on a Unix system?

  • How do I set the time and date?

  • How can I sleep() or alarm() for under a second?

  • How can I measure time under a second?

  • How can I do an atexit() or setjmp()/longjmp()? (Exception handling)

  • Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?

  • How can I call my system's unique C functions from Perl?

  • Where do I get the include files to do ioctl() or syscall()?

  • Why do setuid perl scripts complain about kernel problems?

  • How can I open a pipe both to and from a command?

  • Why can't I get the output of a command with system()?

  • How can I capture STDERR from an external command?

  • Why doesn't open() return an error when a pipe open fails?

  • What's wrong with using backticks in a void context?

  • How can I call backticks without shell processing?

  • Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?

  • How can I convert my shell script to perl?

  • Can I use perl to run a telnet or ftp session?

  • How can I write expect in Perl?

  • Is there a way to hide perl's command line from programs such as "ps"?

  • I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?

  • How do I close a process's filehandle without waiting for it to complete?

  • How do I fork a daemon process?

  • How do I find out if I'm running interactively or not?

  • How do I timeout a slow event?

  • How do I set CPU limits?

  • How do I avoid zombies on a Unix system?

  • How do I use an SQL database?

  • How do I make a system() exit on control-C?

  • How do I open a file without blocking?

  • How do I tell the difference between errors from the shell and perl?

  • How do I install a module from CPAN?

  • What's the difference between require and use?

  • How do I keep my own module/library directory?

  • How do I add the directory my program lives in to the module/library search path?

  • How do I add a directory to my include path (@INC) at runtime?

  • What is socket.ph and where do I get it?

the perlfaq9 manpage: Networking

Networking, the internet, and a few on the web.

  • What is the correct form of response from a CGI script?

  • My CGI script runs from the command line but not the browser. (500 Server Error)

  • How can I get better error messages from a CGI program?

  • How do I remove HTML from a string?

  • How do I extract URLs?

  • How do I download a file from the user's machine? How do I open a file on another machine?

  • How do I make a pop-up menu in HTML?

  • How do I fetch an HTML file?

  • How do I automate an HTML form submission?

  • How do I decode or create those %-encodings on the web?

  • How do I redirect to another page?

  • How do I put a password on my web pages?

  • How do I edit my .htpasswd and .htgroup files with Perl?

  • How do I make sure users can't enter values into a form that cause my CGI script to do bad things?

  • How do I parse a mail header?

  • How do I decode a CGI form?

  • How do I check a valid mail address?

  • How do I decode a MIME/BASE64 string?

  • How do I return the user's mail address?

  • How do I send mail?

  • How do I use MIME to make an attachment to a mail message?

  • How do I read mail?

  • How do I find out my hostname, domainname, or IP address?

  • How do I fetch a news article or the active newsgroups?

  • How do I fetch/put an FTP file?

  • How can I do RPC in Perl?


perlfaq1 - General Questions About Perl

    • What is Perl?
    • Who supports Perl? Who develops it? Why is it free?
    • Which version of Perl should I use?
    • What are perl4, perl5, or perl6?
    • What is Ponie?
    • What is perl6?
    • How stable is Perl?
    • Is Perl difficult to learn?
    • How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
    • Can I do [task] in Perl?
    • When shouldn't I program in Perl?
    • What's the difference between "perl" and "Perl"?
    • Is it a Perl program or a Perl script?
    • What is a JAPH?
    • Where can I get a list of Larry Wall witticisms?
    • How can I convince my sysadmin/supervisor/employees to use version 5/5.6.1/Perl instead of some other language?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq1 - General Questions About Perl ($Revision: 1.19 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section of the FAQ answers very general, high-level questions about Perl.

What is Perl?

Perl is a high-level programming language with an eclectic heritage written by Larry Wall and a cast of thousands. It derives from the ubiquitous C programming language and to a lesser extent from sed, awk, the Unix shell, and at least a dozen other tools and languages. Perl's process, file, and text manipulation facilities make it particularly well-suited for tasks involving quick prototyping, system utilities, software tools, system management tasks, database access, graphical programming, networking, and world wide web programming. These strengths make it especially popular with system administrators and CGI script authors, but mathematicians, geneticists, journalists, and even managers also use Perl. Maybe you should, too.

Who supports Perl? Who develops it? Why is it free?

The original culture of the pre-populist Internet and the deeply-held beliefs of Perl's author, Larry Wall, gave rise to the free and open distribution policy of perl. Perl is supported by its users. The core, the standard Perl library, the optional modules, and the documentation you're reading now were all written by volunteers. See the personal note at the end of the README file in the perl source distribution for more details. See the perlhist manpage (new as of 5.005) for Perl's milestone releases.

In particular, the core development team (known as the Perl Porters) are a rag-tag band of highly altruistic individuals committed to producing better software for free than you could hope to purchase for money. You may snoop on pending developments via the archives at http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ and http://archive.develooper.com/perl5-porters@perl.org/ or the news gateway nntp://nntp.perl.org/perl.perl5.porters or its web interface at http://nntp.perl.org/group/perl.perl5.porters , or read the faq at http://simon-cozens.org/writings/p5p-faq , or you can subscribe to the mailing list by sending perl5-porters-request@perl.org a subscription request (an empty message with no subject is fine).

While the GNU project includes Perl in its distributions, there's no such thing as "GNU Perl". Perl is not produced nor maintained by the Free Software Foundation. Perl's licensing terms are also more open than GNU software's tend to be.

You can get commercial support of Perl if you wish, although for most users the informal support will more than suffice. See the answer to "Where can I buy a commercial version of perl?" for more information.

Which version of Perl should I use?

(contributed by brian d foy)

There is often a matter of opinion and taste, and there isn't any one answer that fits anyone. In general, you want to use either the current stable release, or the stable release immediately prior to that one. Currently, those are perl5.8.x and perl5.6.x, respectively.

Beyond that, you have to consider several things and decide which is best for you.

  • If things aren't broken, upgrading perl may break them (or at least issue new warnings).

  • The latest versions of perl have more bug fixes.

  • The Perl community is geared toward supporting the most recent releases, so you'll have an easier time finding help for those.

  • Versions prior to perl5.004 had serious security problems with buffer overflows, and in some cases have CERT advisories (for instance, http://www.cert.org/advisories/CA-1997-17.html ).

  • The latest versions are probably the least deployed and widely tested, so you may want to wait a few months after their release and see what problems others have if you are risk averse.

  • The immediate, previous releases (i.e. perl5.6.x ) are usually maintained for a while, although not at the same level as the current releases.

  • No one is actively supporting perl4.x. Five years ago it was a dead camel carcass (according to this document). Now it's barely a skeleton as its whitewashed bones have fractured or eroded.

  • There is no perl6.x for the next couple of years. Stay tuned, but don't worry that you'll have to change major versions of Perl soon (i.e. before 2006).

  • There are really two tracks of perl development: a maintenance version and an experimental version. The maintenance versions are stable, and have an even number as the minor release (i.e. perl5.8.x, where 8 is the minor release). The experimental versions may include features that don't make it into the stable versions, and have an odd number as the minor release (i.e. perl5.9.x, where 9 is the minor release).

What are perl4, perl5, or perl6?

(contributed by brian d foy)

In short, perl4 is the past, perl5 is the present, and perl6 is the future.

The number after perl (i.e. the 5 after perl5) is the major release of the perl interpreter as well as the version of the language. Each major version has significant differences that earlier versions cannot support.

The current major release of Perl is perl5, and was released in 1994. It can run scripts from the previous major release, perl4 (March 1991), but has significant differences. It introduced the concept of references, complex data structures, and modules. The perl5 interpreter was a complete re-write of the previous perl sources.

Perl6 is the next major version of Perl, but it's still in development in both its syntax and design. The work started in 2002 and is still ongoing. Many of the most interesting features have shown up in the latest versions of perl5, and some perl5 modules allow you to use some perl6 syntax in your programs. You can learn more about perl6 at http://dev.perl.org/perl6/ .

See the perlhist manpage for a history of Perl revisions.

What is Ponie?

At The O'Reilly Open Source Software Convention in 2003, Artur Bergman, Fotango, and The Perl Foundation announced a project to run perl5 on the Parrot virtual machine named Ponie. Ponie stands for Perl On New Internal Engine. The Perl 5.10 language implementation will be used for Ponie, and there will be no language level differences between perl5 and ponie. Ponie is not a complete rewrite of perl5.

For more details, see http://www.poniecode.org/

What is perl6?

At The Second O'Reilly Open Source Software Convention, Larry Wall announced Perl6 development would begin in earnest. Perl6 was an oft used term for Chip Salzenberg's project to rewrite Perl in C++ named Topaz. However, Topaz provided valuable insights to the next version of Perl and its implementation, but was ultimately abandoned.

If you want to learn more about Perl6, or have a desire to help in the crusade to make Perl a better place then peruse the Perl6 developers page at http://dev.perl.org/perl6/ and get involved.

Perl6 is not scheduled for release yet, and Perl5 will still be supported for quite awhile after its release. Do not wait for Perl6 to do whatever you need to do.

"We're really serious about reinventing everything that needs reinventing." --Larry Wall

How stable is Perl?

Production releases, which incorporate bug fixes and new functionality, are widely tested before release. Since the 5.000 release, we have averaged only about one production release per year.

Larry and the Perl development team occasionally make changes to the internal core of the language, but all possible efforts are made toward backward compatibility. While not quite all perl4 scripts run flawlessly under perl5, an update to perl should nearly never invalidate a program written for an earlier version of perl (barring accidental bug fixes and the rare new keyword).

Is Perl difficult to learn?

No, Perl is easy to start learning--and easy to keep learning. It looks like most programming languages you're likely to have experience with, so if you've ever written a C program, an awk script, a shell script, or even a BASIC program, you're already partway there.

Most tasks only require a small subset of the Perl language. One of the guiding mottos for Perl development is "there's more than one way to do it" (TMTOWTDI, sometimes pronounced "tim toady"). Perl's learning curve is therefore shallow (easy to learn) and long (there's a whole lot you can do if you really want).

Finally, because Perl is frequently (but not always, and certainly not by definition) an interpreted language, you can write your programs and test them without an intermediate compilation step, allowing you to experiment and test/debug quickly and easily. This ease of experimentation flattens the learning curve even more.

Things that make Perl easier to learn: Unix experience, almost any kind of programming experience, an understanding of regular expressions, and the ability to understand other people's code. If there's something you need to do, then it's probably already been done, and a working example is usually available for free. Don't forget the new perl modules, either. They're discussed in Part 3 of this FAQ, along with CPAN, which is discussed in Part 2.

How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?

Favorably in some areas, unfavorably in others. Precisely which areas are good and bad is often a personal choice, so asking this question on Usenet runs a strong risk of starting an unproductive Holy War.

Probably the best thing to do is try to write equivalent code to do a set of tasks. These languages have their own newsgroups in which you can learn about (but hopefully not argue about) them.

Some comparison documents can be found at http://www.perl.com/doc/FMTEYEWTK/versus/ if you really can't stop yourself.

Can I do [task] in Perl?

Perl is flexible and extensible enough for you to use on virtually any task, from one-line file-processing tasks to large, elaborate systems. For many people, Perl serves as a great replacement for shell scripting. For others, it serves as a convenient, high-level replacement for most of what they'd program in low-level languages like C or C++. It's ultimately up to you (and possibly your management) which tasks you'll use Perl for and which you won't.

If you have a library that provides an API, you can make any component of it available as just another Perl function or variable using a Perl extension written in C or C++ and dynamically linked into your main perl interpreter. You can also go the other direction, and write your main program in C or C++, and then link in some Perl code on the fly, to create a powerful application. See the perlembed manpage.

That said, there will always be small, focused, special-purpose languages dedicated to a specific problem domain that are simply more convenient for certain kinds of problems. Perl tries to be all things to all people, but nothing special to anyone. Examples of specialized languages that come to mind include prolog and matlab.

When shouldn't I program in Perl?

When your manager forbids it--but do consider replacing them :-).

Actually, one good reason is when you already have an existing application written in another language that's all done (and done well), or you have an application language specifically designed for a certain task (e.g. prolog, make).

For various reasons, Perl is probably not well-suited for real-time embedded systems, low-level operating systems development work like device drivers or context-switching code, complex multi-threaded shared-memory applications, or extremely large applications. You'll notice that perl is not itself written in Perl.

The new, native-code compiler for Perl may eventually reduce the limitations given in the previous statement to some degree, but understand that Perl remains fundamentally a dynamically typed language, not a statically typed one. You certainly won't be chastised if you don't trust nuclear-plant or brain-surgery monitoring code to it. And Larry will sleep easier, too--Wall Street programs not withstanding. :-)

What's the difference between "perl" and "Perl"?

One bit. Oh, you weren't talking ASCII? :-) Larry now uses "Perl" to signify the language proper and "perl" the implementation of it, i.e. the current interpreter. Hence Tom's quip that "Nothing but perl can parse Perl." You may or may not choose to follow this usage. For example, parallelism means "awk and perl" and "Python and Perl" look OK, while "awk and Perl" and "Python and perl" do not. But never write "PERL", because perl is not an acronym, apocryphal folklore and post-facto expansions notwithstanding.

Is it a Perl program or a Perl script?

Larry doesn't really care. He says (half in jest) that "a script is what you give the actors. A program is what you give the audience."

Originally, a script was a canned sequence of normally interactive commands--that is, a chat script. Something like a UUCP or PPP chat script or an expect script fits the bill nicely, as do configuration scripts run by a program at its start up, such .cshrc or .ircrc, for example. Chat scripts were just drivers for existing programs, not stand-alone programs in their own right.

A computer scientist will correctly explain that all programs are interpreted and that the only question is at what level. But if you ask this question of someone who isn't a computer scientist, they might tell you that a program has been compiled to physical machine code once and can then be run multiple times, whereas a script must be translated by a program each time it's used.

Perl programs are (usually) neither strictly compiled nor strictly interpreted. They can be compiled to a byte-code form (something of a Perl virtual machine) or to completely different languages, like C or assembly language. You can't tell just by looking at it whether the source is destined for a pure interpreter, a parse-tree interpreter, a byte-code interpreter, or a native-code compiler, so it's hard to give a definitive answer here.

Now that "script" and "scripting" are terms that have been seized by unscrupulous or unknowing marketeers for their own nefarious purposes, they have begun to take on strange and often pejorative meanings, like "non serious" or "not real programming". Consequently, some Perl programmers prefer to avoid them altogether.

What is a JAPH?

These are the "just another perl hacker" signatures that some people sign their postings with. Randal Schwartz made these famous. About 100 of the earlier ones are available from http://www.cpan.org/misc/japh .

Where can I get a list of Larry Wall witticisms?

Over a hundred quips by Larry, from postings of his or source code, can be found at http://www.cpan.org/misc/lwall-quotes.txt.gz .

How can I convince my sysadmin/supervisor/employees to use version 5/5.6.1/Perl instead of some other language?

If your manager or employees are wary of unsupported software, or software which doesn't officially ship with your operating system, you might try to appeal to their self-interest. If programmers can be more productive using and utilizing Perl constructs, functionality, simplicity, and power, then the typical manager/supervisor/employee may be persuaded. Regarding using Perl in general, it's also sometimes helpful to point out that delivery times may be reduced using Perl compared to other languages.

If you have a project which has a bottleneck, especially in terms of translation or testing, Perl almost certainly will provide a viable, quick solution. In conjunction with any persuasion effort, you should not fail to point out that Perl is used, quite extensively, and with extremely reliable and valuable results, at many large computer software and hardware companies throughout the world. In fact, many Unix vendors now ship Perl by default. Support is usually just a news-posting away, if you can't find the answer in the comprehensive documentation, including this FAQ.

See http://www.perl.org/advocacy/ for more information.

If you face reluctance to upgrading from an older version of perl, then point out that version 4 is utterly unmaintained and unsupported by the Perl Development Team. Another big sell for Perl5 is the large number of modules and extensions which greatly reduce development time for any given task. Also mention that the difference between version 4 and version 5 of Perl is like the difference between awk and C++. (Well, OK, maybe it's not quite that distinct, but you get the idea.) If you want support and a reasonable guarantee that what you're developing will continue to work in the future, then you have to run the supported version. As of December 2003 that means running either 5.8.2 (released in November 2003), or one of the older releases like 5.6.2 (also released in November 2003; a maintenance release to let perl 5.6 compile on newer systems as 5.6.1 was released in April 2001) or 5.005_03 (released in March 1999), although 5.004_05 isn't that bad if you absolutely need such an old version (released in April 1999) for stability reasons. Anything older than 5.004_05 shouldn't be used.

Of particular note is the massive bug hunt for buffer overflow problems that went into the 5.004 release. All releases prior to that, including perl4, are considered insecure and should be upgraded as soon as possible.

In August 2000 in all Linux distributions a new security problem was found in the optional 'suidperl' (not built or installed by default) in all the Perl branches 5.6, 5.005, and 5.004, see http://www.cpan.org/src/5.0/sperl-2000-08-05/ Perl maintenance releases 5.6.1 and 5.8.0 have this security hole closed. Most, if not all, Linux distribution have patches for this vulnerability available, see http://www.linuxsecurity.com/advisories/ , but the most recommendable way is to upgrade to at least Perl 5.6.1.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required.


perlfaq2 - Obtaining and Learning about Perl

    • What machines support perl? Where do I get it?
    • How can I get a binary version of perl?
    • I don't have a C compiler. How can I build my own Perl interpreter?
    • I copied the perl binary from one machine to another, but scripts don't work.
    • I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
    • What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean?
    • Is there an ISO or ANSI certified version of Perl?
    • Where can I get information on Perl?
    • What are the Perl newsgroups on Usenet? Where do I post questions?
    • Where should I post source code?
    • Perl Books
    • Which magazines have Perl content?
    • What mailing lists are there for Perl?
    • Where are the archives for comp.lang.perl.misc?
    • Where can I buy a commercial version of perl?
    • Where do I send bug reports?
    • What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.39 $, $Date: 2006/01/08 14:27:07 $)

DESCRIPTION

This section of the FAQ answers questions about where to find source and documentation for Perl, support, and related matters.

What machines support perl? Where do I get it?

The standard release of perl (the one maintained by the perl development team) is distributed only in source code form. You can find this at http://www.cpan.org/src/latest.tar.gz , which is in a standard Internet format (a gzipped archive in POSIX tar format).

Perl builds and runs on a bewildering number of platforms. Virtually all known and current Unix derivatives are supported (perl's native platform), as are other systems like VMS, DOS, OS/2, Windows, QNX, BeOS, OS X, MPE/iX and the Amiga.

Binary distributions for some proprietary platforms, including Apple systems, can be found http://www.cpan.org/ports/ directory. Because these are not part of the standard distribution, they may and in fact do differ from the base perl port in a variety of ways. You'll have to check their respective release notes to see just what the differences are. These differences can be either positive (e.g. extensions for the features of the particular platform that are not supported in the source release of perl) or negative (e.g. might be based upon a less current source release of perl).

How can I get a binary version of perl?

If you don't have a C compiler because your vendor for whatever reasons did not include one with your system, the best thing to do is grab a binary version of gcc from the net and use that to compile perl with. CPAN only has binaries for systems that are terribly hard to get free compilers for, not for Unix systems.

Some URLs that might help you are:

    http://www.cpan.org/ports/
    http://www.perl.com/pub/language/info/software.html

Someone looking for a perl for Win16 might look to Laszlo Molnar's djgpp port in http://www.cpan.org/ports/#msdos , which comes with clear installation instructions. A simple installation guide for MS-DOS using Ilya Zakharevich's OS/2 port is available at http://www.cs.ruu.nl/%7Epiet/perl5dos.html and similarly for Windows 3.1 at http://www.cs.ruu.nl/%7Epiet/perlwin3.html .

I don't have a C compiler. How can I build my own Perl interpreter?

Since you don't have a C compiler, you're doomed and your vendor should be sacrificed to the Sun gods. But that doesn't help you.

What you need to do is get a binary version of gcc for your system first. Consult the Usenet FAQs for your operating system for information on where to get such a binary version.

I copied the perl binary from one machine to another, but scripts don't work.

That's probably because you forgot libraries, or library paths differ. You really should build the whole distribution on the machine it will eventually live on, and then type make install. Most other approaches are doomed to failure.

One simple way to check that things are in the right place is to print out the hard-coded @INC that perl looks through for libraries:

    % perl -le 'print for @INC'

If this command lists any paths that don't exist on your system, then you may need to move the appropriate libraries to these locations, or create symbolic links, aliases, or shortcuts appropriately. @INC is also printed as part of the output of

    % perl -V

You might also want to check out How do I keep my own module/library directory? in the perlfaq8 manpage.

I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?

Read the INSTALL file, which is part of the source distribution. It describes in detail how to cope with most idiosyncrasies that the Configure script can't work around for any given system or architecture.

What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean?

CPAN stands for Comprehensive Perl Archive Network, a ~1.2Gb archive replicated on nearly 200 machines all over the world. CPAN contains source code, non-native ports, documentation, scripts, and many third-party modules and extensions, designed for everything from commercial database interfaces to keyboard/screen control to web walking and CGI scripts. The master web site for CPAN is http://www.cpan.org/ and there is the CPAN Multiplexer at http://www.cpan.org/CPAN.html which will choose a mirror near you via DNS. See http://www.perl.com/CPAN (without a slash at the end) for how this process works. Also, http://mirror.cpan.org/ has a nice interface to the http://www.cpan.org/MIRRORED.BY mirror directory.

See the CPAN FAQ at http://www.cpan.org/misc/cpan-faq.html for answers to the most frequently asked questions about CPAN including how to become a mirror.

CPAN/path/... is a naming convention for files available on CPAN sites. CPAN indicates the base directory of a CPAN mirror, and the rest of the path is the path from that directory to the file. For instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN as your CPAN site, the file CPAN/misc/japh is downloadable as ftp://ftp.funet.fi/pub/languages/perl/CPAN/misc/japh .

Considering that there are close to two thousand existing modules in the archive, one probably exists to do nearly anything you can think of. Current categories under CPAN/modules/by-category/ include Perl core modules; development support; operating system interfaces; networking, devices, and interprocess communication; data type utilities; database interfaces; user interfaces; interfaces to other languages; filenames, file systems, and file locking; internationalization and locale; world wide web support; server and daemon utilities; archiving and compression; image manipulation; mail and news; control flow utilities; filehandle and I/O; Microsoft Windows modules; and miscellaneous modules.

See http://www.cpan.org/modules/00modlist.long.html or http://search.cpan.org/ for a more complete list of modules by category.

CPAN is not affiliated with O'Reilly Media.

Is there an ISO or ANSI certified version of Perl?

Certainly not. Larry expects that he'll be certified before Perl is.

Where can I get information on Perl?

The complete Perl documentation is available with the Perl distribution. If you have Perl installed locally, you probably have the documentation installed as well: type man perl if you're on a system resembling Unix. This will lead you to other important man pages, including how to set your $MANPATH. If you're not on a Unix system, access to the documentation will be different; for example, documentation might only be in HTML format. All proper perl installations have fully-accessible documentation.

You might also try perldoc perl in case your system doesn't have a proper man command, or it's been misinstalled. If that doesn't work, try looking in /usr/local/lib/perl5/pod for documentation.

If all else fails, consult http://perldoc.perl.org/ which has the complete documentation in HTML and PDF format.

Many good books have been written about Perl--see the section below for more details.

Tutorial documents are included in current or upcoming Perl releases include the perltoot manpage for objects or the perlboot manpage for a beginner's approach to objects, the perlopentut manpage for file opening semantics, the perlreftut manpage for managing references, the perlretut manpage for regular expressions, the perlthrtut manpage for threads, the perldebtut manpage for debugging, and the perlxstut manpage for linking C and Perl together. There may be more by the time you read this. These URLs might also be useful:

    http://perldoc.perl.org/
    http://bookmarks.cpan.org/search.cgi?cat=Training%2FTutorials

What are the Perl newsgroups on Usenet? Where do I post questions?

Several groups devoted to the Perl language are on Usenet:

    comp.lang.perl.announce             Moderated announcement group
    comp.lang.perl.misc                 High traffic general Perl discussion
    comp.lang.perl.moderated        Moderated discussion group
    comp.lang.perl.modules              Use and development of Perl modules
    comp.lang.perl.tk                   Using Tk (and X) from Perl
    comp.infosystems.www.authoring.cgi  Writing CGI scripts for the Web.

Some years ago, comp.lang.perl was divided into those groups, and comp.lang.perl itself officially removed. While that group may still be found on some news servers, it is unwise to use it, because postings there will not appear on news servers which honour the official list of group names. Use comp.lang.perl.misc for topics which do not have a more-appropriate specific group.

There is also a Usenet gateway to Perl mailing lists sponsored by perl.org at nntp://nntp.perl.org , a web interface to the same lists at http://nntp.perl.org/group/ and these lists are also available under the perl.* hierarchy at http://groups.google.com . Other groups are listed at http://lists.perl.org/ ( also known as http://lists.cpan.org/ ).

A nice place to ask questions is the PerlMonks site, http://www.perlmonks.org/ , or the Perl Beginners mailing list http://lists.perl.org/showlist.cgi?name=beginners .

Note that none of the above are supposed to write your code for you: asking questions about particular problems or general advice is fine, but asking someone to write your code for free is not very cool.

Where should I post source code?

You should post source code to whichever group is most appropriate, but feel free to cross-post to comp.lang.perl.misc. If you want to cross-post to alt.sources, please make sure it follows their posting standards, including setting the Followup-To header line to NOT include alt.sources; see their FAQ ( http://www.faqs.org/faqs/alt-sources-intro/ ) for details.

If you're just looking for software, first use Google ( http://www.google.com ), Google's usenet search interface ( http://groups.google.com ), and CPAN Search ( http://search.cpan.org ). This is faster and more productive than just posting a request.

Perl Books

A number of books on Perl and/or CGI programming are available. A few of these are good, some are OK, but many aren't worth your money. There is a list of these books, some with extensive reviews, at http://books.perl.org/ . If you don't see your book listed here, you can write to perlfaq-workers@perl.org .

The incontestably definitive reference book on Perl, written by the creator of Perl, is Programming Perl:

        Programming Perl (the "Camel Book"):
        by Larry Wall, Tom Christiansen, and Jon Orwant
        ISBN 0-596-00027-8  [3rd edition July 2000]
        http://www.oreilly.com/catalog/pperl3/
        (English, translations to several languages are also available)

The companion volume to the Camel containing thousands of real-world examples, mini-tutorials, and complete programs is:

        The Perl Cookbook (the "Ram Book"):
        by Tom Christiansen and Nathan Torkington,
            with Foreword by Larry Wall
        ISBN 0-596-00313-7 [2nd Edition August 2003]
        http://www.oreilly.com/catalog/perlckbk2/

If you're already a seasoned programmer, then the Camel Book might suffice for you to learn Perl. If you're not, check out the Llama book:

        Learning Perl
        by Randal L. Schwartz, Tom Phoenix, and brian d foy
        ISBN 0-596-10105-8 [4th edition July 2005]
        http://www.oreilly.com/catalog/learnperl4/

And for more advanced information on writing larger programs, presented in the same style as the Llama book, continue your education with the Alpaca book:

        Learning Perl Objects, References, and Modules (the "Alpaca Book")
        by Randal L. Schwartz, with Tom Phoenix (foreword by Damian Conway)
        ISBN 0-596-00478-8 [1st edition June 2003]
        http://www.oreilly.com/catalog/lrnperlorm/

If you're not an accidental programmer, but a more serious and possibly even degreed computer scientist who doesn't need as much hand-holding as we try to provide in the Llama, please check out the delightful book

        Perl: The Programmer's Companion
        by Nigel Chapman
        ISBN 0-471-97563-X [1997, 3rd printing Spring 1998]
        http://www.wiley.com/compbooks/catalog/97563-X.htm
        http://www.wiley.com/compbooks/chapman/perl/perltpc.html (errata etc)

If you are more at home in Windows the following is available (though unfortunately rather dated).

        Learning Perl on Win32 Systems (the "Gecko Book")
        by Randal L. Schwartz, Erik Olson, and Tom Christiansen,
            with foreword by Larry Wall
        ISBN 1-56592-324-3 [1st edition August 1997]
        http://www.oreilly.com/catalog/lperlwin/

Addison-Wesley ( http://www.awlonline.com/ ) and Manning ( http://www.manning.com/ ) are also publishers of some fine Perl books such as Object Oriented Programming with Perl by Damian Conway and Network Programming with Perl by Lincoln Stein.

An excellent technical book discounter is Bookpool at http://www.bookpool.com/ where a 30% discount or more is not unusual.

What follows is a list of the books that the FAQ authors found personally useful. Your mileage may (but, we hope, probably won't) vary.

Recommended books on (or mostly on) Perl follow.

References
        Programming Perl
        by Larry Wall, Tom Christiansen, and Jon Orwant
        ISBN 0-596-00027-8 [3rd edition July 2000]
        http://www.oreilly.com/catalog/pperl3/
        Perl 5 Pocket Reference
        by Johan Vromans
        ISBN 0-596-00032-4 [3rd edition May 2000]
        http://www.oreilly.com/catalog/perlpr3/
Tutorials
        Beginning Perl
        by James Lee
        ISBN 1-59059-391-X [2nd edition August 2004]
        http://apress.com/book/bookDisplay.html?bID=344
        Elements of Programming with Perl
        by Andrew L. Johnson
        ISBN 1-884777-80-5 [1st edition October 1999]
        http://www.manning.com/Johnson/
        Learning Perl
        by Randal L. Schwartz, Tom Phoenix, and brian d foy
        ISBN 0-596-10105-8 [4th edition July 2005]
        http://www.oreilly.com/catalog/learnperl4/
        Learning Perl Objects, References, and Modules
        by Randal L. Schwartz, with Tom Phoenix (foreword by Damian Conway)
        ISBN 0-596-00478-8 [1st edition June 2003]
        http://www.oreilly.com/catalog/lrnperlorm/
Task-Oriented
        Writing Perl Modules for CPAN
        by Sam Tregar
        ISBN 1-59059-018-X [1st edition Aug 2002]
        http://apress.com/book/bookDisplay.html?bID=14
        The Perl Cookbook
        by Tom Christiansen and Nathan Torkington
            with foreword by Larry Wall
        ISBN 1-56592-243-3 [1st edition August 1998]
        http://www.oreilly.com/catalog/cookbook/
        Effective Perl Programming
        by Joseph Hall
        ISBN 0-201-41975-0 [1st edition 1998]
        http://www.awl.com/
        Real World SQL Server Administration with Perl
        by Linchi Shea
        ISBN 1-59059-097-X [1st edition July 2003]
        http://apress.com/book/bookDisplay.html?bID=171
Special Topics
        Perl Best Practices
        by Damian Conway
        ISBN: 0-596-00173-8 [1st edition July 2005]
        http://www.oreilly.com/catalog/perlbp/
        Higher Order Perl
        by Mark-Jason Dominus
        ISBN: 1558607013 [1st edition March 2005]
        http://hop.perl.plover.com/
        Perl 6 Now: The Core Ideas Illustrated with Perl 5
        by Scott Walters
        ISBN 1-59059-395-2 [1st edition December 2004]
        http://apress.com/book/bookDisplay.html?bID=355
        Mastering Regular Expressions
        by Jeffrey E. F. Friedl
        ISBN 0-596-00289-0 [2nd edition July 2002]
        http://www.oreilly.com/catalog/regex2/
        Network Programming with Perl
        by Lincoln Stein
        ISBN 0-201-61571-1 [1st edition 2001]
        http://www.awlonline.com/
        Object Oriented Perl
        Damian Conway
            with foreword by Randal L. Schwartz
        ISBN 1-884777-79-1 [1st edition August 1999]
        http://www.manning.com/Conway/
        Data Munging with Perl
        Dave Cross
        ISBN 1-930110-00-6 [1st edition 2001]
        http://www.manning.com/cross
        Mastering Perl/Tk
        by Steve Lidie and Nancy Walsh
        ISBN 1-56592-716-8 [1st edition January 2002]
        http://www.oreilly.com/catalog/mastperltk/
        Extending and Embedding Perl
        by Tim Jenness and Simon Cozens
        ISBN 1-930110-82-0 [1st edition August 2002]
        http://www.manning.com/jenness
        Perl Debugger Pocket Reference
        by Richard Foley
        ISBN 0-596-00503-2 [1st edition January 2004]
        http://www.oreilly.com/catalog/perldebugpr/

Which magazines have Perl content?

The first (and for a long time, only) periodical devoted to All Things Perl, The Perl Journal contains tutorials, demonstrations, case studies, announcements, contests, and much more. TPJ has columns on web development, databases, Win32 Perl, graphical programming, regular expressions, and networking, and sponsors the Obfuscated Perl Contest and the Perl Poetry Contests. Beginning in November 2002, TPJ moved to a reader-supported monthly e-zine format in which subscribers can download issues as PDF documents. For more details on TPJ, see http://www.tpj.com/

Beyond this, magazines that frequently carry quality articles on Perl are The Perl Review ( http://www.theperlreview.com ), Unix Review ( http://www.unixreview.com/ ), Linux Magazine ( http://www.linuxmagazine.com/ ), and Usenix's newsletter/magazine to its members, login: ( http://www.usenix.org/ )

The Perl columns of Randal L. Schwartz are available on the web at http://www.stonehenge.com/merlyn/WebTechniques/ , http://www.stonehenge.com/merlyn/UnixReview/ , and http://www.stonehenge.com/merlyn/LinuxMag/ .

What mailing lists are there for Perl?

Most of the major modules (Tk, CGI, libwww-perl) have their own mailing lists. Consult the documentation that came with the module for subscription information.

A comprehensive list of Perl related mailing lists can be found at:

        http://lists.perl.org/

Where are the archives for comp.lang.perl.misc?

The Google search engine now carries archived and searchable newsgroup content.

http://groups.google.com/groups?group=comp.lang.perl.misc

If you have a question, you can be sure someone has already asked the same question at some point on c.l.p.m. It requires some time and patience to sift through all the content but often you will find the answer you seek.

Where can I buy a commercial version of perl?

In a real sense, perl already is commercial software: it has a license that you can grab and carefully read to your manager. It is distributed in releases and comes in well-defined packages. There is a very large user community and an extensive literature. The comp.lang.perl.* newsgroups and several of the mailing lists provide free answers to your questions in near real-time. Perl has traditionally been supported by Larry, scores of software designers and developers, and myriad programmers, all working for free to create a useful thing to make life better for everyone.

However, these answers may not suffice for managers who require a purchase order from a company whom they can sue should anything go awry. Or maybe they need very serious hand-holding and contractual obligations. Shrink-wrapped CDs with perl on them are available from several sources if that will help. For example, many Perl books include a distribution of perl, as do the O'Reilly Perl Resource Kits (in both the Unix flavor and in the proprietary Microsoft flavor); the free Unix distributions also all come with perl.

Where do I send bug reports?

If you are reporting a bug in the perl interpreter or the modules shipped with Perl, use the perlbug program in the Perl distribution or mail your report to perlbug@perl.org or at http://rt.perl.org/perlbug/ .

For Perl modules, you can submit bug reports to the Request Tracker set up at http://rt.cpan.org .

If you are posting a bug with a non-standard port (see the answer to "What platforms is perl available for?"), a binary distribution, or a non-standard module (such as Tk, CGI, etc), then please see the documentation that came with it to determine the correct place to post bugs.

Read the perlbug(1) man page (perl5.004 or later) for more information.

What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?

Perl.com at http://www.perl.com/ is part of the O'Reilly Network, a subsidiary of O'Reilly Media.

The Perl Foundation is an advocacy organization for the Perl language which maintains the web site http://www.perl.org/ as a general advocacy site for the Perl language. It uses the domain to provide general support services to the Perl community, including the hosting of mailing lists, web sites, and other services. The web site http://www.perl.org/ is a general advocacy site for the Perl language, and there are many other sub-domains for special topics, such as

        http://learn.perl.org/
        http://use.perl.org/
        http://jobs.perl.org/
        http://lists.perl.org/

Perl Mongers uses the pm.org domain for services related to Perl user groups, including the hosting of mailing lists and web sites. See the Perl user group web site at http://www.pm.org/ for more information about joining, starting, or requesting services for a Perl user group.

http://www.cpan.org/ is the Comprehensive Perl Archive Network, a replicated worldwide repository of Perl software, see the What is CPAN? question earlier in this document.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required.


perlfaq3 - Programming Tools

    • How do I do (anything)?
    • How can I use Perl interactively?
    • Is there a Perl shell?
    • How do I find which modules are installed on my system?
    • How do I debug my Perl programs?
    • How do I profile my Perl programs?
    • How do I cross-reference my Perl programs?
    • Is there a pretty-printer (formatter) for Perl?
    • Is there a ctags for Perl?
    • Is there an IDE or Windows Perl Editor?
    • Where can I get Perl macros for vi?
    • Where can I get perl-mode for emacs?
    • How can I use curses with Perl?
    • How can I use X or Tk with Perl?
    • How can I make my Perl program run faster?
    • How can I make my Perl program take less memory?
    • Is it safe to return a reference to local or lexical data?
    • How can I free an array or hash so my program shrinks?
    • How can I make my CGI script more efficient?
    • How can I hide the source for my Perl program?
    • How can I compile my Perl program into byte code or C?
    • How can I compile Perl into Java?
    • How can I get #!perl to work on [MS-DOS,NT,...]?
    • Can I write useful Perl programs on the command line?
    • Why don't Perl one-liners work on my DOS/Mac/VMS system?
    • Where can I learn about CGI or Web programming in Perl?
    • Where can I learn about object-oriented Perl programming?
    • Where can I learn about linking C with Perl?
    • I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
    • When I tried to run my script, I got this message. What does it mean?
    • What's MakeMaker?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq3 - Programming Tools ($Revision: 1.56 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section of the FAQ answers questions related to programmer tools and programming support.

How do I do (anything)?

Have you looked at CPAN (see the perlfaq2 manpage)? The chances are that someone has already written a module that can solve your problem. Have you read the appropriate manpages? Here's a brief index:

        Basics          perldata, perlvar, perlsyn, perlop, perlsub
        Execution       perlrun, perldebug
        Functions       perlfunc
        Objects         perlref, perlmod, perlobj, perltie
        Data Structures perlref, perllol, perldsc
        Modules         perlmod, perlmodlib, perlsub
        Regexes         perlre, perlfunc, perlop, perllocale
        Moving to perl5 perltrap, perl
        Linking w/C     perlxstut, perlxs, perlcall, perlguts, perlembed
        Various         http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz
                        (not a man-page but still useful, a collection
                         of various essays on Perl techniques)

A crude table of contents for the Perl manpage set is found in the perltoc manpage.

How can I use Perl interactively?

The typical approach uses the Perl debugger, described in the perldebug(1) manpage, on an "empty" program, like this:

    perl -de 42

Now just type in any legal Perl code, and it will be immediately evaluated. You can also examine the symbol table, get stack backtraces, check variable values, set breakpoints, and other operations typically found in symbolic debuggers.

Is there a Perl shell?

The psh (Perl sh) is currently at version 1.8. The Perl Shell is a shell that combines the interactive nature of a Unix shell with the power of Perl. The goal is a full featured shell that behaves as expected for normal shell activity and uses Perl syntax and functionality for control-flow statements and other things. You can get psh at http://sourceforge.net/projects/psh/ .

Zoidberg is a similar project and provides a shell written in perl, configured in perl and operated in perl. It is intended as a login shell and development environment. It can be found at http://zoidberg.sf.net/ or your local CPAN mirror.

The Shell.pm module (distributed with Perl) makes Perl try commands which aren't part of the Perl language as shell commands. perlsh from the source distribution is simplistic and uninteresting, but may still be what you want.

How do I find which modules are installed on my system?

You can use the ExtUtils::Installed module to show all installed distributions, although it can take awhile to do its magic. The standard library which comes with Perl just shows up as "Perl" (although you can get those with Module::CoreList).

        use ExtUtils::Installed;

        my $inst    = ExtUtils::Installed->new();
        my @modules = $inst->modules();

If you want a list of all of the Perl module filenames, you can use File::Find::Rule.

        use File::Find::Rule;

        my @files = File::Find::Rule->file()->name( '*.pm' )->in( @INC );

If you do not have that module, you can do the same thing with File::Find which is part of the standard library.

    use File::Find;
    my @files;

    find(
      sub {
        push @files, $File::Find::name
                if -f $File::Find::name && /\.pm$/
        },

      @INC
      );

        print join "\n", @files;

If you simply need to quickly check to see if a module is available, you can check for its documentation. If you can read the documentation the module is most likely installed. If you cannot read the documentation, the module might not have any (in rare cases).

        prompt% perldoc Module::Name

You can also try to include the module in a one-liner to see if perl finds it.

        perl -MModule::Name -e1

How do I debug my Perl programs?

Have you tried use warnings or used -w? They enable warnings to detect dubious practices.

Have you tried use strict? It prevents you from using symbolic references, makes you predeclare any subroutines that you call as bare words, and (probably most importantly) forces you to predeclare your variables with my, our, or use vars.

Did you check the return values of each and every system call? The operating system (and thus Perl) tells you whether they worked, and if not why.

  open(FH, "> /etc/cantwrite")
    or die "Couldn't write to /etc/cantwrite: $!\n";

Did you read the perltrap manpage? It's full of gotchas for old and new Perl programmers and even has sections for those of you who are upgrading from languages like awk and C.

Have you tried the Perl debugger, described in the perldebug manpage? You can step through your program and see what it's doing and thus work out why what it's doing isn't what it should be doing.

How do I profile my Perl programs?

You should get the Devel::DProf module from the standard distribution (or separately on CPAN) and also use Benchmark.pm from the standard distribution. The Benchmark module lets you time specific portions of your code, while Devel::DProf gives detailed breakdowns of where your code spends its time.

Here's a sample use of Benchmark:

  use Benchmark;

  @junk = `cat /etc/motd`;
  $count = 10_000;

  timethese($count, {
            'map' => sub { my @a = @junk;
                           map { s/a/b/ } @a;
                           return @a },
            'for' => sub { my @a = @junk;
                           for (@a) { s/a/b/ };
                           return @a },
           });

This is what it prints (on one machine--your results will be dependent on your hardware, operating system, and the load on your machine):

  Benchmark: timing 10000 iterations of for, map...
         for:  4 secs ( 3.97 usr  0.01 sys =  3.98 cpu)
         map:  6 secs ( 4.97 usr  0.00 sys =  4.97 cpu)

Be aware that a good benchmark is very hard to write. It only tests the data you give it and proves little about the differing complexities of contrasting algorithms.

How do I cross-reference my Perl programs?

The B::Xref module can be used to generate cross-reference reports for Perl programs.

    perl -MO=Xref[,OPTIONS] scriptname.plx

Is there a pretty-printer (formatter) for Perl?

Perltidy is a Perl script which indents and reformats Perl scripts to make them easier to read by trying to follow the rules of the the perlstyle manpage. If you write Perl scripts, or spend much time reading them, you will probably find it useful. It is available at http://perltidy.sourceforge.net

Of course, if you simply follow the guidelines in the perlstyle manpage, you shouldn't need to reformat. The habit of formatting your code as you write it will help prevent bugs. Your editor can and should help you with this. The perl-mode or newer cperl-mode for emacs can provide remarkable amounts of help with most (but not all) code, and even less programmable editors can provide significant assistance. Tom Christiansen and many other VI users swear by the following settings in vi and its clones:

    set ai sw=4
    map! ^O {^M}^[O^T

Put that in your .exrc file (replacing the caret characters with control characters) and away you go. In insert mode, ^T is for indenting, ^D is for undenting, and ^O is for blockdenting-- as it were. A more complete example, with comments, can be found at http://www.cpan.org/authors/id/TOMC/scripts/toms.exrc.gz

The a2ps http://www-inf.enst.fr/%7Edemaille/a2ps/black+white.ps.gz does lots of things related to generating nicely printed output of documents, as does enscript at http://people.ssh.fi/mtr/genscript/ .

Is there a ctags for Perl?

(contributed by brian d foy)

Exuberent ctags supports Perl: http://ctags.sourceforge.net/

You might also try pltags: http://www.mscha.com/pltags.zip

Is there an IDE or Windows Perl Editor?

Perl programs are just plain text, so any editor will do.

If you're on Unix, you already have an IDE--Unix itself. The UNIX philosophy is the philosophy of several small tools that each do one thing and do it well. It's like a carpenter's toolbox.

If you want an IDE, check the following (in alphabetical order, not order of preference):

Eclipse

http://e-p-i-c.sf.net/

The Eclipse Perl Integration Project integrates Perl editing/debugging with Eclipse.

Enginsite

http://www.enginsite.com/

Perl Editor by EngInSite is a complete integrated development environment (IDE) for creating, testing, and debugging Perl scripts; the tool runs on Windows 9x/NT/2000/XP or later.

Komodo

http://www.ActiveState.com/Products/Komodo/

ActiveState's cross-platform (as of October 2004, that's Windows, Linux, and Solaris), multi-language IDE has Perl support, including a regular expression debugger and remote debugging.

Open Perl IDE

http://open-perl-ide.sourceforge.net/

Open Perl IDE is an integrated development environment for writing and debugging Perl scripts with ActiveState's ActivePerl distribution under Windows 95/98/NT/2000.

OptiPerl

http://www.optiperl.com/

OptiPerl is a Windows IDE with simulated CGI environment, including debugger and syntax highlighting editor.

PerlBuilder

http://www.solutionsoft.com/perl.htm

PerlBuidler is an integrated development environment for Windows that supports Perl development.

visiPerl+

http://helpconsulting.net/visiperl/

From Help Consulting, for Windows.

Visual Perl

http://www.activestate.com/Products/Visual_Perl/

Visual Perl is a Visual Studio.NET plug-in from ActiveState.

Zeus

http://www.zeusedit.com/lookmain.html

Zeus for Window is another Win32 multi-language editor/IDE that comes with support for Perl:

For editors: if you're on Unix you probably have vi or a vi clone already, and possibly an emacs too, so you may not need to download anything. In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the best available Perl editing mode in any editor.

If you are using Windows, you can use any editor that lets you work with plain text, such as NotePad or WordPad. Word processors, such as Microsoft Word or WordPerfect, typically do not work since they insert all sorts of behind-the-scenes information, although some allow you to save files as "Text Only". You can also download text editors designed specifically for programming, such as Textpad ( http://www.textpad.com/ ) and UltraEdit ( http://www.ultraedit.com/ ), among others.

If you are using MacOS, the same concerns apply. MacPerl (for Classic environments) comes with a simple editor. Popular external editors are BBEdit ( http://www.bbedit.com/ ) or Alpha ( http://www.his.com/~jguyer/Alpha/Alpha8.html ). MacOS X users can use Unix editors as well. Neil Bowers (the man behind Geekcruises) has a list of Mac editors that can handle Perl ( http://www.neilbowers.org/macperleditors.html ).

GNU Emacs

http://www.gnu.org/software/emacs/windows/ntemacs.html

MicroEMACS

http://www.microemacs.de/

XEmacs

http://www.xemacs.org/Download/index.html

Jed

http://space.mit.edu/~davis/jed/

or a vi clone such as

Elvis

ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/

Vile

http://dickey.his.com/vile/vile.html

Vim

http://www.vim.org/

For vi lovers in general, Windows or elsewhere:

        http://www.thomer.com/thomer/vi/vi.html

nvi ( http://www.bostic.com/vi/ , available from CPAN in src/misc/) is yet another vi clone, unfortunately not available for Windows, but in UNIX platforms you might be interested in trying it out, firstly because strictly speaking it is not a vi clone, it is the real vi, or the new incarnation of it, and secondly because you can embed Perl inside it to use Perl as the scripting language. nvi is not alone in this, though: at least also vim and vile offer an embedded Perl.

The following are Win32 multilanguage editor/IDESs that support Perl:

Codewright

http://www.borland.com/codewright/

MultiEdit

http://www.MultiEdit.com/

SlickEdit

http://www.slickedit.com/

There is also a toyedit Text widget based editor written in Perl that is distributed with the Tk module on CPAN. The ptkdb ( http://world.std.com/~aep/ptkdb/ ) is a Perl/tk based debugger that acts as a development environment of sorts. Perl Composer ( http://perlcomposer.sourceforge.net/ ) is an IDE for Perl/Tk GUI creation.

In addition to an editor/IDE you might be interested in a more powerful shell environment for Win32. Your options include

Bash

from the Cygwin package ( http://sources.redhat.com/cygwin/ )

Ksh

from the MKS Toolkit ( http://www.mks.com/ ), or the Bourne shell of the U/WIN environment ( http://www.research.att.com/sw/tools/uwin/ )

Tcsh

ftp://ftp.astron.com/pub/tcsh/ , see also http://www.primate.wisc.edu/software/csh-tcsh-book/

Zsh

ftp://ftp.blarg.net/users/amol/zsh/ , see also http://www.zsh.org/

MKS and U/WIN are commercial (U/WIN is free for educational and research purposes), Cygwin is covered by the GNU Public License (but that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all contain (in addition to the shells) a comprehensive set of standard UNIX toolkit utilities.

If you're transferring text files between Unix and Windows using FTP be sure to transfer them in ASCII mode so the ends of lines are appropriately converted.

On Mac OS the MacPerl Application comes with a simple 32k text editor that behaves like a rudimentary IDE. In contrast to the MacPerl Application the MPW Perl tool can make use of the MPW Shell itself as an editor (with no 32k limit).

Affrus

is a full Perl development environment with full debugger support ( http://www.latenightsw.com ).

Alpha

is an editor, written and extensible in Tcl, that nonetheless has built in support for several popular markup and programming languages including Perl and HTML ( http://www.his.com/~jguyer/Alpha/Alpha8.html ).

BBEdit and BBEdit Lite

are text editors for Mac OS that have a Perl sensitivity mode ( http://web.barebones.com/ ).

Pepper and Pe are programming language sensitive text editors for Mac OS X and BeOS respectively ( http://www.hekkelman.com/ ).

Where can I get Perl macros for vi?

For a complete version of Tom Christiansen's vi configuration file, see http://www.cpan.org/authors/Tom_Christiansen/scripts/toms.exrc.gz , the standard benchmark file for vi emulators. The file runs best with nvi, the current version of vi out of Berkeley, which incidentally can be built with an embedded Perl interpreter--see http://www.cpan.org/src/misc/ .

Where can I get perl-mode for emacs?

Since Emacs version 19 patchlevel 22 or so, there have been both a perl-mode.el and support for the Perl debugger built in. These should come with the standard Emacs 19 distribution.

In the Perl source directory, you'll find a directory called "emacs", which contains a cperl-mode that color-codes keywords, provides context-sensitive help, and other nifty things.

Note that the perl-mode of emacs will have fits with "main'foo" (single quote), and mess up the indentation and highlighting. You are probably using "main::foo" in new Perl code anyway, so this shouldn't be an issue.

How can I use curses with Perl?

The Curses module from CPAN provides a dynamically loadable object module interface to a curses library. A small demo can be found at the directory http://www.cpan.org/authors/Tom_Christiansen/scripts/rep.gz ; this program repeats a command and updates the screen as needed, rendering rep ps axu similar to top.

How can I use X or Tk with Perl?

Tk is a completely Perl-based, object-oriented interface to the Tk toolkit that doesn't force you to use Tcl just to get at Tk. Sx is an interface to the Athena Widget set. Both are available from CPAN. See the directory http://www.cpan.org/modules/by-category/08_User_Interfaces/

Invaluable for Perl/Tk programming are the Perl/Tk FAQ at http://phaseit.net/claird/comp.lang.perl.tk/ptkFAQ.html , the Perl/Tk Reference Guide available at http://www.cpan.org/authors/Stephen_O_Lidie/ , and the online manpages at http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html .

How can I make my Perl program run faster?

The best way to do this is to come up with a better algorithm. This can often make a dramatic difference. Jon Bentley's book Programming Pearls (that's not a misspelling!) has some good tips on optimization, too. Advice on benchmarking boils down to: benchmark and profile to make sure you're optimizing the right part, look for better algorithms instead of microtuning your code, and when all else fails consider just buying faster hardware. You will probably want to read the answer to the earlier question "How do I profile my Perl programs?" if you haven't done so already.

A different approach is to autoload seldom-used Perl code. See the AutoSplit and AutoLoader modules in the standard distribution for that. Or you could locate the bottleneck and think about writing just that part in C, the way we used to take bottlenecks in C code and write them in assembler. Similar to rewriting in C, modules that have critical sections can be written in C (for instance, the PDL module from CPAN).

If you're currently linking your perl executable to a shared libc.so, you can often gain a 10-25% performance benefit by rebuilding it to link with a static libc.a instead. This will make a bigger perl executable, but your Perl programs (and programmers) may thank you for it. See the INSTALL file in the source distribution for more information.

The undump program was an ancient attempt to speed up Perl program by storing the already-compiled form to disk. This is no longer a viable option, as it only worked on a few architectures, and wasn't a good solution anyway.

How can I make my Perl program take less memory?

When it comes to time-space tradeoffs, Perl nearly always prefers to throw memory at a problem. Scalars in Perl use more memory than strings in C, arrays take more than that, and hashes use even more. While there's still a lot to be done, recent releases have been addressing these issues. For example, as of 5.004, duplicate hash keys are shared amongst all hashes using them, so require no reallocation.

In some cases, using substr() or vec() to simulate arrays can be highly beneficial. For example, an array of a thousand booleans will take at least 20,000 bytes of space, but it can be turned into one 125-byte bit vector--a considerable memory savings. The standard Tie::SubstrHash module can also help for certain types of data structure. If you're working with specialist data structures (matrices, for instance) modules that implement these in C may use less memory than equivalent Perl modules.

Another thing to try is learning whether your Perl was compiled with the system malloc or with Perl's builtin malloc. Whichever one it is, try using the other one and see whether this makes a difference. Information about malloc is in the INSTALL file in the source distribution. You can find out whether you are using perl's malloc by typing perl -V:usemymalloc.

Of course, the best way to save memory is to not do anything to waste it in the first place. Good programming practices can go a long way toward this:

  • Don't slurp!

    Don't read an entire file into memory if you can process it line by line. Or more concretely, use a loop like this:

            #
        # Good Idea
        #
        while (<FILE>) {
           # ...
        }

    instead of this:

            #
        # Bad Idea
        #
        @data = <FILE>;
        foreach (@data) {
            # ...
        }

    When the files you're processing are small, it doesn't much matter which way you do it, but it makes a huge difference when they start getting larger.

  • Use map and grep selectively

    Remember that both map and grep expect a LIST argument, so doing this:

            @wanted = grep {/pattern/} <FILE>;

    will cause the entire file to be slurped. For large files, it's better to loop:

            while (<FILE>) {
                push(@wanted, $_) if /pattern/;
        }
  • Avoid unnecessary quotes and stringification

    Don't quote large strings unless absolutely necessary:

            my $copy = "$large_string";

    makes 2 copies of $large_string (one for $copy and another for the quotes), whereas

            my $copy = $large_string;

    only makes one copy.

    Ditto for stringifying large arrays:

            {
                local $, = "\n";
                print @big_array;
        }

    is much more memory-efficient than either

            print join "\n", @big_array;

    or

            {
                local $" = "\n";
                print "@big_array";
        }
  • Pass by reference

    Pass arrays and hashes by reference, not by value. For one thing, it's the only way to pass multiple lists or hashes (or both) in a single call/return. It also avoids creating a copy of all the contents. This requires some judgment, however, because any changes will be propagated back to the original data. If you really want to mangle (er, modify) a copy, you'll have to sacrifice the memory needed to make one.

  • Tie large variables to disk.

    For "big" data stores (i.e. ones that exceed available memory) consider using one of the DB modules to store it on disk instead of in RAM. This will incur a penalty in access time, but that's probably better than causing your hard disk to thrash due to massive swapping.

Is it safe to return a reference to local or lexical data?

Yes. Perl's garbage collection system takes care of this so everything works out right.

    sub makeone {
        my @a = ( 1 .. 10 );
        return \@a;
    }

    for ( 1 .. 10 ) {
        push @many, makeone();
    }

    print $many[4][5], "\n";

    print "@many\n";

How can I free an array or hash so my program shrinks?

(contributed by Michael Carman)

You usually can't. Memory allocated to lexicals (i.e. my() variables) cannot be reclaimed or reused even if they go out of scope. It is reserved in case the variables come back into scope. Memory allocated to global variables can be reused (within your program) by using undef()ing and/or delete().

On most operating systems, memory allocated to a program can never be returned to the system. That's why long-running programs sometimes re- exec themselves. Some operating systems (notably, systems that use mmap(2) for allocating large chunks of memory) can reclaim memory that is no longer used, but on such systems, perl must be configured and compiled to use the OS's malloc, not perl's.

In general, memory allocation and de-allocation isn't something you can or should be worrying about much in Perl.

See also "How can I make my Perl program take less memory?"

How can I make my CGI script more efficient?

Beyond the normal measures described to make general Perl programs faster or smaller, a CGI program has additional issues. It may be run several times per second. Given that each time it runs it will need to be re-compiled and will often allocate a megabyte or more of system memory, this can be a killer. Compiling into C isn't going to help you because the process start-up overhead is where the bottleneck is.

There are two popular ways to avoid this overhead. One solution involves running the Apache HTTP server (available from http://www.apache.org/ ) with either of the mod_perl or mod_fastcgi plugin modules.

With mod_perl and the Apache::Registry module (distributed with mod_perl), httpd will run with an embedded Perl interpreter which pre-compiles your script and then executes it within the same address space without forking. The Apache extension also gives Perl access to the internal server API, so modules written in Perl can do just about anything a module written in C can. For more on mod_perl, see http://perl.apache.org/

With the FCGI module (from CPAN) and the mod_fastcgi module (available from http://www.fastcgi.com/ ) each of your Perl programs becomes a permanent CGI daemon process.

Both of these solutions can have far-reaching effects on your system and on the way you write your CGI programs, so investigate them with care.

See http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ .

How can I hide the source for my Perl program?

Delete it. :-) Seriously, there are a number of (mostly unsatisfactory) solutions with varying levels of "security".

First of all, however, you can't take away read permission, because the source code has to be readable in order to be compiled and interpreted. (That doesn't mean that a CGI script's source is readable by people on the web, though--only by people with access to the filesystem.) So you have to leave the permissions at the socially friendly 0755 level.

Some people regard this as a security problem. If your program does insecure things and relies on people not knowing how to exploit those insecurities, it is not secure. It is often possible for someone to determine the insecure things and exploit them without viewing the source. Security through obscurity, the name for hiding your bugs instead of fixing them, is little security indeed.

You can try using encryption via source filters (Starting from Perl 5.8 the Filter::Simple and Filter::Util::Call modules are included in the standard distribution), but any decent programmer will be able to decrypt it. You can try using the byte code compiler and interpreter described below, but the curious might still be able to de-compile it. You can try using the native-code compiler described below, but crackers might be able to disassemble it. These pose varying degrees of difficulty to people wanting to get at your code, but none can definitively conceal it (true of every language, not just Perl).

It is very easy to recover the source of Perl programs. You simply feed the program to the perl interpreter and use the modules in the B:: hierarchy. The B::Deparse module should be able to defeat most attempts to hide source. Again, this is not unique to Perl.

If you're concerned about people profiting from your code, then the bottom line is that nothing but a restrictive license will give you legal security. License your software and pepper it with threatening statements like "This is unpublished proprietary software of XYZ Corp. Your access to it does not give you permission to use it blah blah blah." We are not lawyers, of course, so you should see a lawyer if you want to be sure your license's wording will stand up in court.

How can I compile my Perl program into byte code or C?

(contributed by brian d foy)

In general, you can't do this. There are some things that may work for your situation though. People usually ask this question because they want to distribute their works without giving away the source code, and most solutions trade disk space for convenience. You probably won't see much of a speed increase either, since most solutions simply bundle a Perl interpreter in the final product (but see How can I make my Perl program run faster?).

The Perl Archive Toolkit ( http://par.perl.org/index.cgi ) is Perl's analog to Java's JAR. It's freely available and on CPAN ( http://search.cpan.org/dist/PAR/ ).

The B::* namespace, often called "the Perl compiler", but is really a way for Perl programs to peek at its innards rather than create pre-compiled versions of your program. However. the B::Bytecode module can turn your script into a bytecode format that could be loaded later by the ByteLoader module and executed as a regular Perl script.

There are also some commercial products that may work for you, although you have to buy a license for them.

The Perl Dev Kit ( http://www.activestate.com/Products/Perl_Dev_Kit/ ) from ActiveState can "Turn your Perl programs into ready-to-run executables for HP-UX, Linux, Solaris and Windows."

Perl2Exe ( http://www.indigostar.com/perl2exe.htm ) is a command line program for converting perl scripts to executable files. It targets both Windows and unix platforms.

How can I compile Perl into Java?

You can also integrate Java and Perl with the Perl Resource Kit from O'Reilly Media. See http://www.oreilly.com/catalog/prkunix/ .

Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in development, allows Perl code to be called from Java. See jpl/README in the Perl source tree.

How can I get #!perl to work on [MS-DOS,NT,...]?

For OS/2 just use

    extproc perl -S -your_switches

as the first line in *.cmd file (-S due to a bug in cmd.exe's "extproc" handling). For DOS one should first invent a corresponding batch file and codify it in ALTERNATE_SHEBANG (see the dosish.h file in the source distribution for more information).

The Win95/NT installation, when using the ActiveState port of Perl, will modify the Registry to associate the .pl extension with the perl interpreter. If you install another port, perhaps even building your own Win95/NT Perl from the standard sources by using a Windows port of gcc (e.g., with cygwin or mingw32), then you'll have to modify the Registry yourself. In addition to associating .pl with the interpreter, NT people can use: SET PATHEXT=%PATHEXT%;.PL to let them run the program install-linux.pl merely by typing install-linux.

Under "Classic" MacOS, a perl program will have the appropriate Creator and Type, so that double-clicking them will invoke the MacPerl application. Under Mac OS X, clickable apps can be made from any #! script using Wil Sanchez' DropScript utility: http://www.wsanchez.net/software/ .

IMPORTANT!: Whatever you do, PLEASE don't get frustrated, and just throw the perl interpreter into your cgi-bin directory, in order to get your programs working for a web server. This is an EXTREMELY big security risk. Take the time to figure out how to do it correctly.

Can I write useful Perl programs on the command line?

Yes. Read the perlrun manpage for more information. Some examples follow. (These assume standard Unix shell quoting rules.)

    # sum first and last fields
    perl -lane 'print $F[0] + $F[-1]' *
    # identify text files
    perl -le 'for(@ARGV) {print if -f && -T _}' *

    # remove (most) comments from C program
    perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c

    # make file a month younger than today, defeating reaper daemons
    perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' *

    # find first unused uid
    perl -le '$i++ while getpwuid($i); print $i'

    # display reasonable manpath
    echo $PATH | perl -nl -072 -e '
        s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}'

OK, the last one was actually an Obfuscated Perl Contest entry. :-)

Why don't Perl one-liners work on my DOS/Mac/VMS system?

The problem is usually that the command interpreters on those systems have rather different ideas about quoting than the Unix shells under which the one-liners were created. On some systems, you may have to change single-quotes to double ones, which you must NOT do on Unix or Plan9 systems. You might also have to change a single % to a %%.

For example:

    # Unix
    perl -e 'print "Hello world\n"'
    # DOS, etc.
    perl -e "print \"Hello world\n\""
    # Mac
    print "Hello world\n"
     (then Run "Myscript" or Shift-Command-R)
    # MPW
    perl -e 'print "Hello world\n"'
    # VMS
    perl -e "print ""Hello world\n"""

The problem is that none of these examples are reliable: they depend on the command interpreter. Under Unix, the first two often work. Under DOS, it's entirely possible that neither works. If 4DOS was the command shell, you'd probably have better luck like this:

  perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""

Under the Mac, it depends which environment you are using. The MacPerl shell, or MPW, is much like Unix shells in its support for several quoting variants, except that it makes free use of the Mac's non-ASCII characters as control characters.

Using qq(), q(), and qx(), instead of "double quotes", 'single quotes', and `backticks`, may make one-liners easier to write.

There is no general solution to all of this. It is a mess.

[Some of this answer was contributed by Kenneth Albanowski.]

Where can I learn about CGI or Web programming in Perl?

For modules, get the CGI or LWP modules from CPAN. For textbooks, see the two especially dedicated to web stuff in the question on books. For problems and questions related to the web, like "Why do I get 500 Errors" or "Why doesn't it run from the browser right when it runs fine on the command line", see the troubleshooting guides and references in the perlfaq9 manpage or in the CGI MetaFAQ:

        http://www.perl.org/CGI_MetaFAQ.html

Where can I learn about object-oriented Perl programming?

A good place to start is the perltoot manpage, and you can use the perlobj manpage, the perlboot manpage, the perltoot manpage, the perltooc manpage, and the perlbot manpage for reference.

A good book on OO on Perl is the "Object-Oriented Perl" by Damian Conway from Manning Publications, or "Learning Perl References, Objects, & Modules" by Randal Schwartz and Tom Phoenix from O'Reilly Media.

Where can I learn about linking C with Perl?

If you want to call C from Perl, start with the perlxstut manpage, moving on to the perlxs manpage, the xsubpp manpage, and the perlguts manpage. If you want to call Perl from C, then read the perlembed manpage, the perlcall manpage, and the perlguts manpage. Don't forget that you can learn a lot from looking at how the authors of existing extension modules wrote their code and solved their problems.

You might not need all the power of XS. The Inline::C module lets you put C code directly in your Perl source. It handles all the magic to make it work. You still have to learn at least some of the perl API but you won't have to deal with the complexity of the XS support files.

I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?

Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they fail, see perlbug and send a bug report with the output of make test TEST_VERBOSE=1 along with perl -V.

When I tried to run my script, I got this message. What does it mean?

A complete list of Perl's error messages and warnings with explanatory text can be found in the perldiag manpage. You can also use the splain program (distributed with Perl) to explain the error messages:

    perl program 2>diag.out
    splain [-v] [-p] diag.out

or change your program to explain the messages for you:

    use diagnostics;

or

    use diagnostics -verbose;

What's MakeMaker?

This module (part of the standard Perl distribution) is designed to write a Makefile for an extension module from a Makefile.PL. For more information, see the ExtUtils::MakeMaker manpage.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required.


perlfaq4 - Data Manipulation

  • Data: Numbers
    • Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
    • Why is int() broken?
    • Why isn't my octal data interpreted correctly?
    • Does Perl have a round() function? What about ceil() and floor()? Trig functions?
    • How do I convert between numeric representations/bases/radixes?
    • Why doesn't & work the way I want it to?
    • How do I multiply matrices?
    • How do I perform an operation on a series of integers?
    • How can I output Roman numerals?
    • Why aren't my random numbers random?
    • How do I get a random number between X and Y?
  • Data: Dates
    • How do I find the day or week of the year?
    • How do I find the current century or millennium?
    • How can I compare two dates and find the difference?
    • How can I take a string and turn it into epoch seconds?
    • How can I find the Julian Day?
    • How do I find yesterday's date?
    • Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
  • Data: Strings
    • How do I validate input?
    • How do I unescape a string?
    • How do I remove consecutive pairs of characters?
    • How do I expand function calls in a string?
    • How do I find matching/nesting anything?
    • How do I reverse a string?
    • How do I expand tabs in a string?
    • How do I reformat a paragraph?
    • How can I access or change N characters of a string?
    • How do I change the Nth occurrence of something?
    • How can I count the number of occurrences of a substring within a string?
    • How do I capitalize all the words on one line?
    • How can I split a [character] delimited string except when inside [character]?
    • How do I strip blank space from the beginning/end of a string?
    • How do I pad a string with blanks or pad a number with zeroes?
    • How do I extract selected columns from a string?
    • How do I find the soundex value of a string?
    • How can I expand variables in text strings?
    • What's wrong with always quoting "$vars"?
    • Why don't my <<HERE documents work?
  • Data: Arrays
    • What is the difference between a list and an array?
    • What is the difference between $array[1] and @array[1]?
    • How can I remove duplicate elements from a list or array?
    • How can I tell whether a certain element is contained in a list or array?
    • How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
    • How do I test whether two arrays or hashes are equal?
    • How do I find the first array element for which a condition is true?
    • How do I handle linked lists?
    • How do I handle circular lists?
    • How do I shuffle an array randomly?
    • How do I process/modify each element of an array?
    • How do I select a random element from an array?
    • How do I permute N elements of a list?
    • How do I sort an array by (anything)?
    • How do I manipulate arrays of bits?
    • Why does defined() return true on empty arrays and hashes?
  • Data: Hashes (Associative Arrays)
    • How do I process an entire hash?
    • What happens if I add or remove keys from a hash while iterating over it?
    • How do I look up a hash element by value?
    • How can I know how many entries are in a hash?
    • How do I sort a hash (optionally by value instead of key)?
    • How can I always keep my hash sorted?
    • What's the difference between "delete" and "undef" with hashes?
    • Why don't my tied hashes make the defined/exists distinction?
    • How do I reset an each() operation part-way through?
    • How can I get the unique keys from two hashes?
    • How can I store a multidimensional array in a DBM file?
    • How can I make my hash remember the order I put elements into it?
    • Why does passing a subroutine an undefined element in a hash create it?
    • How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
    • How can I use a reference as a hash key?
  • Data: Misc
    • How do I handle binary data correctly?
    • How do I determine whether a scalar is a number/whole/integer/float?
    • How do I keep persistent data across program calls?
    • How do I print out or copy a recursive data structure?
    • How do I define methods for every class/object?
    • How do I verify a credit card checksum?
    • How do I pack arrays of doubles or floats for XS code?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq4 - Data Manipulation ($Revision: 1.73 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section of the FAQ answers questions related to manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues.

Data: Numbers

Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?

Internally, your computer represents floating-point numbers in binary. Digital (as in powers of two) computers cannot store all numbers exactly. Some real numbers lose precision in the process. This is a problem with how computers store numbers and affects all computer languages, not just Perl.

the perlnumber manpage show the gory details of number representations and conversions.

To limit the number of decimal places in your numbers, you can use the printf or sprintf function. See the "Floating Point Arithmetic" for more details.

        printf "%.2f", 10/3;

        my $number = sprintf "%.2f", 10/3;

Why is int() broken?

Your int() is most probably working just fine. It's the numbers that aren't quite what you think.

First, see the above item "Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?".

For example, this

    print int(0.6/0.2-2), "\n";

will in most computers print 0, not 1, because even such simple numbers as 0.6 and 0.2 cannot be presented exactly by floating-point numbers. What you think in the above as 'three' is really more like 2.9999999999999995559.

Why isn't my octal data interpreted correctly?

Perl only understands octal and hex numbers as such when they occur as literals in your program. Octal literals in perl must start with a leading "0" and hexadecimal literals must start with a leading "0x". If they are read in from somewhere and assigned, no automatic conversion takes place. You must explicitly use oct() or hex() if you want the values converted to decimal. oct() interprets hex ("0x350"), octal ("0350" or even without the leading "0", like "377") and binary ("0b1010") numbers, while hex() only converts hexadecimal ones, with or without a leading "0x", like "0x255", "3A", "ff", or "deadbeef". The inverse mapping from decimal to octal can be done with either the "%o" or "%O" sprintf() formats.

This problem shows up most often when people try using chmod(), mkdir(), umask(), or sysopen(), which by widespread tradition typically take permissions in octal.

    chmod(644,  $file); # WRONG
    chmod(0644, $file); # right

Note the mistake in the first line was specifying the decimal literal 644, rather than the intended octal literal 0644. The problem can be seen with:

    printf("%#o",644); # prints 01204

Surely you had not intended chmod(01204, $file); - did you? If you want to use numeric literals as arguments to chmod() et al. then please try to express them as octal constants, that is with a leading zero and with the following digits restricted to the set 0..7.

Does Perl have a round() function? What about ceil() and floor()? Trig functions?

Remember that int() merely truncates toward 0. For rounding to a certain number of digits, sprintf() or printf() is usually the easiest route.

    printf("%.3f", 3.1415926535);       # prints 3.142

The POSIX module (part of the standard Perl distribution) implements ceil(), floor(), and a number of other mathematical and trigonometric functions.

    use POSIX;
    $ceil   = ceil(3.5);                        # 4
    $floor  = floor(3.5);                       # 3

In 5.000 to 5.003 perls, trigonometry was done in the Math::Complex module. With 5.004, the Math::Trig module (part of the standard Perl distribution) implements the trigonometric functions. Internally it uses the Math::Complex module and some functions can break out from the real axis into the complex plane, for example the inverse sine of 2.

Rounding in financial applications can have serious implications, and the rounding method used should be specified precisely. In these cases, it probably pays not to trust whichever system rounding is being used by Perl, but to instead implement the rounding function you need yourself.

To see why, notice how you'll still have an issue on half-way-point alternation:

    for ($i = 0; $i < 1.01; $i += 0.05) { printf "%.1f ",$i}

    0.0 0.1 0.1 0.2 0.2 0.2 0.3 0.3 0.4 0.4 0.5 0.5 0.6 0.7 0.7
    0.8 0.8 0.9 0.9 1.0 1.0

Don't blame Perl. It's the same as in C. IEEE says we have to do this. Perl numbers whose absolute values are integers under 2**31 (on 32 bit machines) will work pretty much like mathematical integers. Other numbers are not guaranteed.

How do I convert between numeric representations/bases/radixes?

As always with Perl there is more than one way to do it. Below are a few examples of approaches to making common conversions between number representations. This is intended to be representational rather than exhaustive.

Some of the examples below use the Bit::Vector module from CPAN. The reason you might choose Bit::Vector over the perl built in functions is that it works with numbers of ANY size, that it is optimized for speed on some operations, and for at least some programmers the notation might be familiar.

How do I convert hexadecimal into decimal

Using perl's built in conversion of 0x notation:

    $dec = 0xDEADBEEF;

Using the hex function:

    $dec = hex("DEADBEEF");

Using pack:

    $dec = unpack("N", pack("H8", substr("0" x 8 . "DEADBEEF", -8)));

Using the CPAN module Bit::Vector:

    use Bit::Vector;
    $vec = Bit::Vector->new_Hex(32, "DEADBEEF");
    $dec = $vec->to_Dec();
How do I convert from decimal to hexadecimal

Using sprintf:

    $hex = sprintf("%X", 3735928559); # upper case A-F
    $hex = sprintf("%x", 3735928559); # lower case a-f

Using unpack:

    $hex = unpack("H*", pack("N", 3735928559));

Using Bit::Vector:

    use Bit::Vector;
    $vec = Bit::Vector->new_Dec(32, -559038737);
    $hex = $vec->to_Hex();

And Bit::Vector supports odd bit counts:

    use Bit::Vector;
    $vec = Bit::Vector->new_Dec(33, 3735928559);
    $vec->Resize(32); # suppress leading 0 if unwanted
    $hex = $vec->to_Hex();
How do I convert from octal to decimal

Using Perl's built in conversion of numbers with leading zeros:

    $dec = 033653337357; # note the leading 0!

Using the oct function:

    $dec = oct("33653337357");

Using Bit::Vector:

    use Bit::Vector;
    $vec = Bit::Vector->new(32);
    $vec->Chunk_List_Store(3, split(//, reverse "33653337357"));
    $dec = $vec->to_Dec();
How do I convert from decimal to octal

Using sprintf:

    $oct = sprintf("%o", 3735928559);

Using Bit::Vector:

    use Bit::Vector;
    $vec = Bit::Vector->new_Dec(32, -559038737);
    $oct = reverse join('', $vec->Chunk_List_Read(3));
How do I convert from binary to decimal

Perl 5.6 lets you write binary numbers directly with the 0b notation:

    $number = 0b10110110;

Using oct:

    my $input = "10110110";
    $decimal = oct( "0b$input" );

Using pack and ord:

    $decimal = ord(pack('B8', '10110110'));

Using pack and unpack for larger strings:

    $int = unpack("N", pack("B32",
        substr("0" x 32 . "11110101011011011111011101111", -32)));
    $dec = sprintf("%d", $int);

    # substr() is used to left pad a 32 character string with zeros.

Using Bit::Vector:

    $vec = Bit::Vector->new_Bin(32, "11011110101011011011111011101111");
    $dec = $vec->to_Dec();
How do I convert from decimal to binary

Using sprintf (perl 5.6+):

    $bin = sprintf("%b", 3735928559);

Using unpack:

    $bin = unpack("B*", pack("N", 3735928559));

Using Bit::Vector:

    use Bit::Vector;
    $vec = Bit::Vector->new_Dec(32, -559038737);
    $bin = $vec->to_Bin();

The remaining transformations (e.g. hex -> oct, bin -> hex, etc.) are left as an exercise to the inclined reader.

Why doesn't & work the way I want it to?

The behavior of binary arithmetic operators depends on whether they're used on numbers or strings. The operators treat a string as a series of bits and work with that (the string "3" is the bit pattern 00110011). The operators work with the binary form of a number (the number 3 is treated as the bit pattern 00000011).

So, saying 11 & 3 performs the "and" operation on numbers (yielding 3). Saying "11" & "3" performs the "and" operation on strings (yielding "1").

Most problems with & and | arise because the programmer thinks they have a number but really it's a string. The rest arise because the programmer says:

    if ("\020\020" & "\101\101") {
        # ...
    }

but a string consisting of two null bytes (the result of "\020\020" & "\101\101") is not a false value in Perl. You need:

    if ( ("\020\020" & "\101\101") !~ /[^\000]/) {
        # ...
    }

How do I multiply matrices?

Use the Math::Matrix or Math::MatrixReal modules (available from CPAN) or the PDL extension (also available from CPAN).

How do I perform an operation on a series of integers?

To call a function on each element in an array, and collect the results, use:

    @results = map { my_func($_) } @array;

For example:

    @triple = map { 3 * $_ } @single;

To call a function on each element of an array, but ignore the results:

    foreach $iterator (@array) {
        some_func($iterator);
    }

To call a function on each integer in a (small) range, you can use:

    @results = map { some_func($_) } (5 .. 25);

but you should be aware that the .. operator creates an array of all integers in the range. This can take a lot of memory for large ranges. Instead use:

    @results = ();
    for ($i=5; $i < 500_005; $i++) {
        push(@results, some_func($i));
    }

This situation has been fixed in Perl5.005. Use of .. in a for loop will iterate over the range, without creating the entire range.

    for my $i (5 .. 500_005) {
        push(@results, some_func($i));
    }

will not create a list of 500,000 integers.

How can I output Roman numerals?

Get the http://www.cpan.org/modules/by-module/Roman module.

Why aren't my random numbers random?

If you're using a version of Perl before 5.004, you must call srand once at the start of your program to seed the random number generator.

         BEGIN { srand() if $] < 5.004 }

5.004 and later automatically call srand at the beginning. Don't call srand more than once---you make your numbers less random, rather than more.

Computers are good at being predictable and bad at being random (despite appearances caused by bugs in your programs :-). see the random article in the "Far More Than You Ever Wanted To Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz , courtesy of Tom Phoenix, talks more about this. John von Neumann said, "Anyone who attempts to generate random numbers by deterministic means is, of course, living in a state of sin."

If you want numbers that are more random than rand with srand provides, you should also check out the Math::TrulyRandom module from CPAN. It uses the imperfections in your system's timer to generate random numbers, but this takes quite a while. If you want a better pseudorandom generator than comes with your operating system, look at "Numerical Recipes in C" at http://www.nr.com/ .

How do I get a random number between X and Y?

rand($x) returns a number such that 0 <= rand($x) < $x. Thus what you want to have perl figure out is a random number in the range from 0 to the difference between your X and Y.

That is, to get a number between 10 and 15, inclusive, you want a random number between 0 and 5 that you can then add to 10.

    my $number = 10 + int rand( 15-10+1 );

Hence you derive the following simple function to abstract that. It selects a random integer between the two given integers (inclusive), For example: random_int_in(50,120).

   sub random_int_in ($$) {
     my($min, $max) = @_;
      # Assumes that the two arguments are integers themselves!
     return $min if $min == $max;
     ($min, $max) = ($max, $min)  if  $min > $max;
     return $min + int rand(1 + $max - $min);
   }

Data: Dates

How do I find the day or week of the year?

The localtime function returns the day of the year. Without an argument localtime uses the current time.

        $day_of_year = (localtime)[7];

The POSIX module can also format a date as the day of the year or week of the year.

        use POSIX qw/strftime/;
        my $day_of_year  = strftime "%j", localtime;
        my $week_of_year = strftime "%W", localtime;

To get the day of year for any date, use the Time::Local module to get a time in epoch seconds for the argument to localtime.

        use POSIX qw/strftime/;
        use Time::Local;
        my $week_of_year = strftime "%W",
                localtime( timelocal( 0, 0, 0, 18, 11, 1987 ) );

The Date::Calc module provides two functions to calculate these.

        use Date::Calc;
        my $day_of_year  = Day_of_Year(  1987, 12, 18 );
        my $week_of_year = Week_of_Year( 1987, 12, 18 );

How do I find the current century or millennium?

Use the following simple functions:

    sub get_century    {
        return int((((localtime(shift || time))[5] + 1999))/100);
    }

    sub get_millennium {
        return 1+int((((localtime(shift || time))[5] + 1899))/1000);
    }

On some systems, the POSIX module's strftime() function has been extended in a non-standard way to use a %C format, which they sometimes claim is the "century". It isn't, because on most such systems, this is only the first two digits of the four-digit year, and thus cannot be used to reliably determine the current century or millennium.

How can I compare two dates and find the difference?

(contributed by brian d foy)

You could just store all your dates as a number and then subtract. Life isn't always that simple though. If you want to work with formatted dates, the Date::Manip, Date::Calc, or DateTime modules can help you.

How can I take a string and turn it into epoch seconds?

If it's a regular enough string that it always has the same format, you can split it up and pass the parts to timelocal in the standard Time::Local module. Otherwise, you should look into the Date::Calc and Date::Manip modules from CPAN.

How can I find the Julian Day?

(contributed by brian d foy and Dave Cross)

You can use the Time::JulianDay module available on CPAN. Ensure that you really want to find a Julian day, though, as many people have different ideas about Julian days. See http://www.hermetic.ch/cal_stud/jdn.htm for instance.

You can also try the DateTime module, which can convert a date/time to a Julian Day.

  $ perl -MDateTime -le'print DateTime->today->jd'
  2453401.5

Or the modified Julian Day

  $ perl -MDateTime -le'print DateTime->today->mjd'
  53401

Or even the day of the year (which is what some people think of as a Julian day)

  $ perl -MDateTime -le'print DateTime->today->doy'
  31

How do I find yesterday's date?

(contributed by brian d foy)

Use one of the Date modules. The DateTime module makes it simple, and give you the same time of day, only the day before.

        use DateTime;

        my $yesterday = DateTime->now->subtract( days => 1 );

        print "Yesterday was $yesterday\n";

You can also use the Date::Calc module using its Today_and_Now function.

        use Date::Calc qw( Today_and_Now Add_Delta_DHMS );

        my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 );

        print "@date\n";

Most people try to use the time rather than the calendar to figure out dates, but that assumes that days are twenty-four hours each. For most people, there are two days a year when they aren't: the switch to and from summer time throws this off. Let the modules do the work.

Does Perl have a Year 2000 problem? Is Perl Y2K compliant?

Short answer: No, Perl does not have a Year 2000 problem. Yes, Perl is Y2K compliant (whatever that means). The programmers you've hired to use it, however, probably are not.

Long answer: The question belies a true understanding of the issue. Perl is just as Y2K compliant as your pencil--no more, and no less. Can you use your pencil to write a non-Y2K-compliant memo? Of course you can. Is that the pencil's fault? Of course it isn't.

The date and time functions supplied with Perl (gmtime and localtime) supply adequate information to determine the year well beyond 2000 (2038 is when trouble strikes for 32-bit machines). The year returned by these functions when used in a list context is the year minus 1900. For years between 1910 and 1999 this happens to be a 2-digit decimal number. To avoid the year 2000 problem simply do not treat the year as a 2-digit number. It isn't.

When gmtime() and localtime() are used in scalar context they return a timestamp string that contains a fully-expanded year. For example, $timestamp = gmtime(1005613200) sets $timestamp to "Tue Nov 13 01:00:00 2001". There's no year 2000 problem here.

That doesn't mean that Perl can't be used to create non-Y2K compliant programs. It can. But so can your pencil. It's the fault of the user, not the language. At the risk of inflaming the NRA: "Perl doesn't break Y2K, people do." See http://www.perl.org/about/y2k.html for a longer exposition.

Data: Strings

How do I validate input?

(contributed by brian d foy)

There are many ways to ensure that values are what you expect or want to accept. Besides the specific examples that we cover in the perlfaq, you can also look at the modules with "Assert" and "Validate" in their names, along with other modules such as Regexp::Common.

Some modules have validation for particular types of input, such as Business::ISBN, Business::CreditCard, Email::Valid, and Data::Validate::IP.

How do I unescape a string?

It depends just what you mean by "escape". URL escapes are dealt with in the perlfaq9 manpage. Shell escapes with the backslash (\) character are removed with

    s/\\(.)/$1/g;

This won't expand "\n" or "\t" or any other special escapes.

How do I remove consecutive pairs of characters?

(contributed by brian d foy)

You can use the substitution operator to find pairs of characters (or runs of characters) and replace them with a single instance. In this substitution, we find a character in (.). The memory parentheses store the matched character in the back-reference \1 and we use that to require that the same thing immediately follow it. We replace that part of the string with the character in $1.

    s/(.)\1/$1/g;

We can also use the transliteration operator, tr///. In this example, the search list side of our tr/// contains nothing, but the c option complements that so it contains everything. The replacement list also contains nothing, so the transliteration is almost a no-op since it won't do any replacements (or more exactly, replace the character with itself). However, the s option squashes duplicated and consecutive characters in the string so a character does not show up next to itself

        my $str = 'Haarlem';   # in the Netherlands
            $str =~ tr///cs;       # Now Harlem, like in New York

How do I expand function calls in a string?

(contributed by brian d foy)

This is documented in the perlref manpage, and although it's not the easiest thing to read, it does work. In each of these examples, we call the function inside the braces used to dereference a reference. If we have a more than one return value, we can construct and dereference an anonymous array. In this case, we call the function in list context.

        print "The time values are @{ [localtime] }.\n";

If we want to call the function in scalar context, we have to do a bit more work. We can really have any code we like inside the braces, so we simply have to end with the scalar reference, although how you do that is up to you, and you can use code inside the braces.

        print "The time is ${\(scalar localtime)}.\n"

        print "The time is ${ my $x = localtime; \$x }.\n";

If your function already returns a reference, you don't need to create the reference yourself.

        sub timestamp { my $t = localtime; \$t }

        print "The time is ${ timestamp() }.\n";

The Interpolation module can also do a lot of magic for you. You can specify a variable name, in this case E, to set up a tied hash that does the interpolation for you. It has several other methods to do this as well.

        use Interpolation E => 'eval';
        print "The time values are $E{localtime()}.\n";

In most cases, it is probably easier to simply use string concatenation, which also forces scalar context.

        print "The time is " . localtime . ".\n";

How do I find matching/nesting anything?

This isn't something that can be done in one regular expression, no matter how complicated. To find something between two single characters, a pattern like /x([^x]*)x/ will get the intervening bits in $1. For multiple ones, then something more like /alpha(.*?)omega/ would be needed. But none of these deals with nested patterns. For balanced expressions using (, {, [ or < as delimiters, use the CPAN module Regexp::Common, or see (??{ code }) in the perlre manpage. For other cases, you'll have to write a parser.

If you are serious about writing a parser, there are a number of modules or oddities that will make your life a lot easier. There are the CPAN modules Parse::RecDescent, Parse::Yapp, and Text::Balanced; and the byacc program. Starting from perl 5.8 the Text::Balanced is part of the standard distribution.

One simple destructive, inside-out approach that you might try is to pull out the smallest nesting parts one at a time:

    while (s/BEGIN((?:(?!BEGIN)(?!END).)*)END//gs) {
        # do something with $1
    }

A more complicated and sneaky approach is to make Perl's regular expression engine do it for you. This is courtesy Dean Inada, and rather has the nature of an Obfuscated Perl Contest entry, but it really does work:

    # $_ contains the string to parse
    # BEGIN and END are the opening and closing markers for the
    # nested text.

    @( = ('(','');
    @) = (')','');
    ($re=$_)=~s/((BEGIN)|(END)|.)/$)[!$3]\Q$1\E$([!$2]/gs;
    @$ = (eval{/$re/},$@!~/unmatched/i);
    print join("\n",@$[0..$#$]) if( $$[-1] );

How do I reverse a string?

Use reverse() in scalar context, as documented in reverse in the perlfunc manpage.

    $reversed = reverse $string;

How do I expand tabs in a string?

You can do it yourself:

    1 while $string =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e;

Or you can just use the Text::Tabs module (part of the standard Perl distribution).

    use Text::Tabs;
    @expanded_lines = expand(@lines_with_tabs);

How do I reformat a paragraph?

Use Text::Wrap (part of the standard Perl distribution):

    use Text::Wrap;
    print wrap("\t", '  ', @paragraphs);

The paragraphs you give to Text::Wrap should not contain embedded newlines. Text::Wrap doesn't justify the lines (flush-right).

Or use the CPAN module Text::Autoformat. Formatting files can be easily done by making a shell alias, like so:

    alias fmt="perl -i -MText::Autoformat -n0777 \
        -e 'print autoformat $_, {all=>1}' $*"

See the documentation for Text::Autoformat to appreciate its many capabilities.

How can I access or change N characters of a string?

You can access the first characters of a string with substr(). To get the first character, for example, start at position 0 and grab the string of length 1.

        $string = "Just another Perl Hacker";
            $first_char = substr( $string, 0, 1 );  #  'J'

To change part of a string, you can use the optional fourth argument which is the replacement string.

    substr( $string, 13, 4, "Perl 5.8.0" );

You can also use substr() as an lvalue.

    substr( $string, 13, 4 ) =  "Perl 5.8.0";

How do I change the Nth occurrence of something?

You have to keep track of N yourself. For example, let's say you want to change the fifth occurrence of "whoever" or "whomever" into "whosoever" or "whomsoever", case insensitively. These all assume that $_ contains the string to be altered.

    $count = 0;
    s{((whom?)ever)}{
        ++$count == 5           # is it the 5th?
            ? "${2}soever"      # yes, swap
            : $1                # renege and leave it there
    }ige;

In the more general case, you can use the /g modifier in a while loop, keeping count of matches.

    $WANT = 3;
    $count = 0;
    $_ = "One fish two fish red fish blue fish";
    while (/(\w+)\s+fish\b/gi) {
        if (++$count == $WANT) {
            print "The third fish is a $1 one.\n";
        }
    }

That prints out: "The third fish is a red one." You can also use a repetition count and repeated pattern like this:

    /(?:\w+\s+fish\s+){2}(\w+)\s+fish/i;

How can I count the number of occurrences of a substring within a string?

There are a number of ways, with varying efficiency. If you want a count of a certain single character (X) within a string, you can use the tr/// function like so:

    $string = "ThisXlineXhasXsomeXx'sXinXit";
    $count = ($string =~ tr/X//);
    print "There are $count X characters in the string";

This is fine if you are just looking for a single character. However, if you are trying to count multiple character substrings within a larger string, tr/// won't work. What you can do is wrap a while() loop around a global pattern match. For example, let's count negative integers:

    $string = "-9 55 48 -2 23 -76 4 14 -44";
    while ($string =~ /-\d+/g) { $count++ }
    print "There are $count negative numbers in the string";

Another version uses a global match in list context, then assigns the result to a scalar, producing a count of the number of matches.

        $count = () = $string =~ /-\d+/g;

How do I capitalize all the words on one line?

To make the first letter of each word upper case:

        $line =~ s/\b(\w)/\U$1/g;

This has the strange effect of turning "don't do it" into "Don'T Do It". Sometimes you might want this. Other times you might need a more thorough solution (Suggested by brian d foy):

    $string =~ s/ (
                 (^\w)    #at the beginning of the line
                   |      # or
                 (\s\w)   #preceded by whitespace
                   )
                /\U$1/xg;
    $string =~ /([\w']+)/\u\L$1/g;

To make the whole line upper case:

        $line = uc($line);

To force each word to be lower case, with the first letter upper case:

        $line =~ s/(\w+)/\u\L$1/g;

You can (and probably should) enable locale awareness of those characters by placing a use locale pragma in your program. See the perllocale manpage for endless details on locales.

This is sometimes referred to as putting something into "title case", but that's not quite accurate. Consider the proper capitalization of the movie Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb, for example.

Damian Conway's the Text::Autoformat manpage module provides some smart case transformations:

    use Text::Autoformat;
    my $x = "Dr. Strangelove or: How I Learned to Stop ".
      "Worrying and Love the Bomb";

    print $x, "\n";
    for my $style (qw( sentence title highlight ))
    {
        print autoformat($x, { case => $style }), "\n";
    }

How can I split a [character] delimited string except when inside [character]?

Several modules can handle this sort of pasing---Text::Balanced, Text::CSV, Text::CSV_XS, and Text::ParseWords, among others.

Take the example case of trying to split a string that is comma-separated into its different fields. You can't use split(/,/) because you shouldn't split if the comma is inside quotes. For example, take a data line like this:

    SAR001,"","Cimetrix, Inc","Bob Smith","CAM",N,8,1,0,7,"Error, Core Dumped"

Due to the restriction of the quotes, this is a fairly complex problem. Thankfully, we have Jeffrey Friedl, author of Mastering Regular Expressions, to handle these for us. He suggests (assuming your string is contained in $text):

     @new = ();
     push(@new, $+) while $text =~ m{
         "([^\"\\]*(?:\\.[^\"\\]*)*)",?  # groups the phrase inside the quotes
       | ([^,]+),?
       | ,
     }gx;
     push(@new, undef) if substr($text,-1,1) eq ',';

If you want to represent quotation marks inside a quotation-mark-delimited field, escape them with backslashes (eg, "like \"this\"".

Alternatively, the Text::ParseWords module (part of the standard Perl distribution) lets you say:

    use Text::ParseWords;
    @new = quotewords(",", 0, $text);

There's also a Text::CSV (Comma-Separated Values) module on CPAN.

How do I strip blank space from the beginning/end of a string?

(contributed by brian d foy)

A substitution can do this for you. For a single line, you want to replace all the leading or trailing whitespace with nothing. You can do that with a pair of substitutions.

        s/^\s+//;
        s/\s+$//;

You can also write that as a single substitution, although it turns out the combined statement is slower than the separate ones. That might not matter to you, though.

        s/^\s+|\s+$//g;

In this regular expression, the alternation matches either at the beginning or the end of the string since the anchors have a lower precedence than the alternation. With the /g flag, the substitution makes all possible matches, so it gets both. Remember, the trailing newline matches the \s+, and the $ anchor can match to the physical end of the string, so the newline disappears too. Just add the newline to the output, which has the added benefit of preserving "blank" (consisting entirely of whitespace) lines which the ^\s+ would remove all by itself.

        while( <> )
                {
                s/^\s+|\s+$//g;
                print "$_\n";
                }

For a multi-line string, you can apply the regular expression to each logical line in the string by adding the /m flag (for "multi-line"). With the /m flag, the $ matches before an embedded newline, so it doesn't remove it. It still removes the newline at the end of the string.

    $string =~ s/^\s+|\s+$//gm;

Remember that lines consisting entirely of whitespace will disappear, since the first part of the alternation can match the entire string and replace it with nothing. If need to keep embedded blank lines, you have to do a little more work. Instead of matching any whitespace (since that includes a newline), just match the other whitespace.

        $string =~ s/^[\t\f ]+|[\t\f ]+$//mg;

How do I pad a string with blanks or pad a number with zeroes?

In the following examples, $pad_len is the length to which you wish to pad the string, $text or $num contains the string to be padded, and $pad_char contains the padding character. You can use a single character string constant instead of the $pad_char variable if you know what it is in advance. And in the same way you can use an integer in place of $pad_len if you know the pad length in advance.

The simplest method uses the sprintf function. It can pad on the left or right with blanks and on the left with zeroes and it will not truncate the result. The pack function can only pad strings on the right with blanks and it will truncate the result to a maximum length of $pad_len.

    # Left padding a string with blanks (no truncation):
        $padded = sprintf("%${pad_len}s", $text);
        $padded = sprintf("%*s", $pad_len, $text);  # same thing

    # Right padding a string with blanks (no truncation):
        $padded = sprintf("%-${pad_len}s", $text);
        $padded = sprintf("%-*s", $pad_len, $text); # same thing

    # Left padding a number with 0 (no truncation):
        $padded = sprintf("%0${pad_len}d", $num);
        $padded = sprintf("%0*d", $pad_len, $num); # same thing

    # Right padding a string with blanks using pack (will truncate):
    $padded = pack("A$pad_len",$text);

If you need to pad with a character other than blank or zero you can use one of the following methods. They all generate a pad string with the x operator and combine that with $text. These methods do not truncate $text.

Left and right padding with any character, creating a new string:

    $padded = $pad_char x ( $pad_len - length( $text ) ) . $text;
    $padded = $text . $pad_char x ( $pad_len - length( $text ) );

Left and right padding with any character, modifying $text directly:

    substr( $text, 0, 0 ) = $pad_char x ( $pad_len - length( $text ) );
    $text .= $pad_char x ( $pad_len - length( $text ) );

How do I extract selected columns from a string?

Use substr() or unpack(), both documented in the perlfunc manpage. If you prefer thinking in terms of columns instead of widths, you can use this kind of thing:

    # determine the unpack format needed to split Linux ps output
    # arguments are cut columns
    my $fmt = cut2fmt(8, 14, 20, 26, 30, 34, 41, 47, 59, 63, 67, 72);

    sub cut2fmt {
        my(@positions) = @_;
        my $template  = '';
        my $lastpos   = 1;
        for my $place (@positions) {
            $template .= "A" . ($place - $lastpos) . " ";
            $lastpos   = $place;
        }
        $template .= "A*";
        return $template;
    }

How do I find the soundex value of a string?

(contributed by brian d foy)

You can use the Text::Soundex module. If you want to do fuzzy or close matching, you might also try the String::Approx, and Text::Metaphone, and Text::DoubleMetaphone modules.

How can I expand variables in text strings?

Let's assume that you have a string that contains placeholder variables.

    $text = 'this has a $foo in it and a $bar';

You can use a substitution with a double evaluation. The first /e turns $1 into $foo, and the second /e turns $foo into its value. You may want to wrap this in an eval: if you try to get the value of an undeclared variable while running under use strict, you get a fatal error.

    eval { $text =~ s/(\$\w+)/$1/eeg };
    die if $@;

It's probably better in the general case to treat those variables as entries in some special hash. For example:

    %user_defs = (
        foo  => 23,
        bar  => 19,
    );
    $text =~ s/\$(\w+)/$user_defs{$1}/g;

What's wrong with always quoting "$vars"?

The problem is that those double-quotes force stringification-- coercing numbers and references into strings--even when you don't want them to be strings. Think of it this way: double-quote expansion is used to produce new strings. If you already have a string, why do you need more?

If you get used to writing odd things like these:

    print "$var";       # BAD
    $new = "$old";      # BAD
    somefunc("$var");   # BAD

You'll be in trouble. Those should (in 99.8% of the cases) be the simpler and more direct:

    print $var;
    $new = $old;
    somefunc($var);

Otherwise, besides slowing you down, you're going to break code when the thing in the scalar is actually neither a string nor a number, but a reference:

    func(\@array);
    sub func {
        my $aref = shift;
        my $oref = "$aref";  # WRONG
    }

You can also get into subtle problems on those few operations in Perl that actually do care about the difference between a string and a number, such as the magical ++ autoincrement operator or the syscall() function.

Stringification also destroys arrays.

    @lines = `command`;
    print "@lines";             # WRONG - extra blanks
    print @lines;               # right

Why don't my <<HERE documents work?

Check for these three things:

There must be no space after the << part.
There (probably) should be a semicolon at the end.
You can't (easily) have any space in front of the tag.

If you want to indent the text in the here document, you can do this:

    # all in one
    ($VAR = <<HERE_TARGET) =~ s/^\s+//gm;
        your text
        goes here
    HERE_TARGET

But the HERE_TARGET must still be flush against the margin. If you want that indented also, you'll have to quote in the indentation.

    ($quote = <<'    FINIS') =~ s/^\s+//gm;
            ...we will have peace, when you and all your works have
            perished--and the works of your dark master to whom you
            would deliver us. You are a liar, Saruman, and a corrupter
            of men's hearts.  --Theoden in /usr/src/perl/taint.c
        FINIS
    $quote =~ s/\s+--/\n--/;

A nice general-purpose fixer-upper function for indented here documents follows. It expects to be called with a here document as its argument. It looks to see whether each line begins with a common substring, and if so, strips that substring off. Otherwise, it takes the amount of leading whitespace found on the first line and removes that much off each subsequent line.

    sub fix {
        local $_ = shift;
        my ($white, $leader);  # common whitespace and common leading string
        if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\1\2?.*\n)+$/) {
            ($white, $leader) = ($2, quotemeta($1));
        } else {
            ($white, $leader) = (/^(\s+)/, '');
        }
        s/^\s*?$leader(?:$white)?//gm;
        return $_;
    }

This works with leading special strings, dynamically determined:

    $remember_the_main = fix<<'    MAIN_INTERPRETER_LOOP';
        @@@ int
        @@@ runops() {
        @@@     SAVEI32(runlevel);
        @@@     runlevel++;
        @@@     while ( op = (*op->op_ppaddr)() );
        @@@     TAINT_NOT;
        @@@     return 0;
        @@@ }
    MAIN_INTERPRETER_LOOP

Or with a fixed amount of leading whitespace, with remaining indentation correctly preserved:

    $poem = fix<<EVER_ON_AND_ON;
       Now far ahead the Road has gone,
          And I must follow, if I can,
       Pursuing it with eager feet,
          Until it joins some larger way
       Where many paths and errands meet.
          And whither then? I cannot say.
                --Bilbo in /usr/src/perl/pp_ctl.c
    EVER_ON_AND_ON

Data: Arrays

What is the difference between a list and an array?

An array has a changeable length. A list does not. An array is something you can push or pop, while a list is a set of values. Some people make the distinction that a list is a value while an array is a variable. Subroutines are passed and return lists, you put things into list context, you initialize arrays with lists, and you foreach() across a list. @ variables are arrays, anonymous arrays are arrays, arrays in scalar context behave like the number of elements in them, subroutines access their arguments through the array @_, and push/pop/shift only work on arrays.

As a side note, there's no such thing as a list in scalar context. When you say

    $scalar = (2, 5, 7, 9);

you're using the comma operator in scalar context, so it uses the scalar comma operator. There never was a list there at all! This causes the last value to be returned: 9.

What is the difference between $array[1] and @array[1]?

The former is a scalar value; the latter an array slice, making it a list with one (scalar) value. You should use $ when you want a scalar value (most of the time) and @ when you want a list with one scalar value in it (very, very rarely; nearly never, in fact).

Sometimes it doesn't make a difference, but sometimes it does. For example, compare:

    $good[0] = `some program that outputs several lines`;

with

    @bad[0]  = `same program that outputs several lines`;

The use warnings pragma and the -w flag will warn you about these matters.

How can I remove duplicate elements from a list or array?

(contributed by brian d foy)

Use a hash. When you think the words "unique" or "duplicated", think "hash keys".

If you don't care about the order of the elements, you could just create the hash then extract the keys. It's not important how you create that hash: just that you use keys to get the unique elements.

   my %hash   = map { $_, 1 } @array;
   # or a hash slice: @hash{ @array } = ();
   # or a foreach: $hash{$_} = 1 foreach ( @array );

   my @unique = keys %hash;

You can also go through each element and skip the ones you've seen before. Use a hash to keep track. The first time the loop sees an element, that element has no key in %Seen. The next statement creates the key and immediately uses its value, which is undef, so the loop continues to the push and increments the value for that key. The next time the loop sees that same element, its key exists in the hash and the value for that key is true (since it's not 0 or undef), so the next skips that iteration and the loop goes to the next element.

        my @unique = ();
        my %seen   = ();

        foreach my $elem ( @array )
                {
                next if $seen{ $elem }++;
                push @unique, $elem;
                }

You can write this more briefly using a grep, which does the same thing.

   my %seen = ();
   my @unique = grep { ! $seen{ $_ }++ } @array;

How can I tell whether a certain element is contained in a list or array?

(portions of this answer contributed by Anno Siegel)

Hearing the word "in" is an indication that you probably should have used a hash, not a list or array, to store your data. Hashes are designed to answer this question quickly and efficiently. Arrays aren't.

That being said, there are several ways to approach this. If you are going to make this query many times over arbitrary string values, the fastest way is probably to invert the original array and maintain a hash whose keys are the first array's values.

    @blues = qw/azure cerulean teal turquoise lapis-lazuli/;
    %is_blue = ();
    for (@blues) { $is_blue{$_} = 1 }

Now you can check whether $is_blue{$some_color}. It might have been a good idea to keep the blues all in a hash in the first place.

If the values are all small integers, you could use a simple indexed array. This kind of an array will take up less space:

    @primes = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31);
    @is_tiny_prime = ();
    for (@primes) { $is_tiny_prime[$_] = 1 }
    # or simply  @istiny_prime[@primes] = (1) x @primes;

Now you check whether $is_tiny_prime[$some_number].

If the values in question are integers instead of strings, you can save quite a lot of space by using bit strings instead:

    @articles = ( 1..10, 150..2000, 2017 );
    undef $read;
    for (@articles) { vec($read,$_,1) = 1 }

Now check whether vec($read,$n,1) is true for some $n.

These methods guarantee fast individual tests but require a re-organization of the original list or array. They only pay off if you have to test multiple values against the same array.

If you are testing only once, the standard module List::Util exports the function first for this purpose. It works by stopping once it finds the element. It's written in C for speed, and its Perl equivalant looks like this subroutine:

        sub first (&@) {
                my $code = shift;
                foreach (@_) {
                        return $_ if &{$code}();
                }
                undef;
        }

If speed is of little concern, the common idiom uses grep in scalar context (which returns the number of items that passed its condition) to traverse the entire list. This does have the benefit of telling you how many matches it found, though.

        my $is_there = grep $_ eq $whatever, @array;

If you want to actually extract the matching elements, simply use grep in list context.

        my @matches = grep $_ eq $whatever, @array;

How do I compute the difference of two arrays? How do I compute the intersection of two arrays?

Use a hash. Here's code to do both and more. It assumes that each element is unique in a given array:

    @union = @intersection = @difference = ();
    %count = ();
    foreach $element (@array1, @array2) { $count{$element}++ }
    foreach $element (keys %count) {
        push @union, $element;
        push @{ $count{$element} > 1 ? \@intersection : \@difference }, $element;
    }

Note that this is the symmetric difference, that is, all elements in either A or in B but not in both. Think of it as an xor operation.

How do I test whether two arrays or hashes are equal?

The following code works for single-level arrays. It uses a stringwise comparison, and does not distinguish defined versus undefined empty strings. Modify if you have other needs.

    $are_equal = compare_arrays(\@frogs, \@toads);

    sub compare_arrays {
        my ($first, $second) = @_;
        no warnings;  # silence spurious -w undef complaints
        return 0 unless @$first == @$second;
        for (my $i = 0; $i < @$first; $i++) {
            return 0 if $first->[$i] ne $second->[$i];
        }
        return 1;
    }

For multilevel structures, you may wish to use an approach more like this one. It uses the CPAN module FreezeThaw:

    use FreezeThaw qw(cmpStr);
    @a = @b = ( "this", "that", [ "more", "stuff" ] );

    printf "a and b contain %s arrays\n",
        cmpStr(\@a, \@b) == 0
            ? "the same"
            : "different";

This approach also works for comparing hashes. Here we'll demonstrate two different answers:

    use FreezeThaw qw(cmpStr cmpStrHard);

    %a = %b = ( "this" => "that", "extra" => [ "more", "stuff" ] );
    $a{EXTRA} = \%b;
    $b{EXTRA} = \%a;

    printf "a and b contain %s hashes\n",
        cmpStr(\%a, \%b) == 0 ? "the same" : "different";

    printf "a and b contain %s hashes\n",
        cmpStrHard(\%a, \%b) == 0 ? "the same" : "different";

The first reports that both those the hashes contain the same data, while the second reports that they do not. Which you prefer is left as an exercise to the reader.

How do I find the first array element for which a condition is true?

To find the first array element which satisfies a condition, you can use the first() function in the List::Util module, which comes with Perl 5.8. This example finds the first element that contains "Perl".

        use List::Util qw(first);

        my $element = first { /Perl/ } @array;

If you cannot use List::Util, you can make your own loop to do the same thing. Once you find the element, you stop the loop with last.

        my $found;
        foreach ( @array )
                {
                if( /Perl/ ) { $found = $_; last }
                }

If you want the array index, you can iterate through the indices and check the array element at each index until you find one that satisfies the condition.

        my( $found, $index ) = ( undef, -1 );
        for( $i = 0; $i < @array; $i++ )
                {
                if( $array[$i] =~ /Perl/ )
                        {
                        $found = $array[$i];
                        $index = $i;
                        last;
                        }
                }

How do I handle linked lists?

In general, you usually don't need a linked list in Perl, since with regular arrays, you can push and pop or shift and unshift at either end, or you can use splice to add and/or remove arbitrary number of elements at arbitrary points. Both pop and shift are both O(1) operations on Perl's dynamic arrays. In the absence of shifts and pops, push in general needs to reallocate on the order every log(N) times, and unshift will need to copy pointers each time.

If you really, really wanted, you could use structures as described in the perldsc manpage or the perltoot manpage and do just what the algorithm book tells you to do. For example, imagine a list node like this:

    $node = {
        VALUE => 42,
        LINK  => undef,
    };

You could walk the list this way:

    print "List: ";
    for ($node = $head;  $node; $node = $node->{LINK}) {
        print $node->{VALUE}, " ";
    }
    print "\n";

You could add to the list this way:

    my ($head, $tail);
    $tail = append($head, 1);       # grow a new head
    for $value ( 2 .. 10 ) {
        $tail = append($tail, $value);
    }

    sub append {
        my($list, $value) = @_;
        my $node = { VALUE => $value };
        if ($list) {
            $node->{LINK} = $list->{LINK};
            $list->{LINK} = $node;
        } else {
            $_[0] = $node;      # replace caller's version
        }
        return $node;
    }

But again, Perl's built-in are virtually always good enough.

How do I handle circular lists?

Circular lists could be handled in the traditional fashion with linked lists, or you could just do something like this with an array:

    unshift(@array, pop(@array));  # the last shall be first
    push(@array, shift(@array));   # and vice versa

How do I shuffle an array randomly?

If you either have Perl 5.8.0 or later installed, or if you have Scalar-List-Utils 1.03 or later installed, you can say:

    use List::Util 'shuffle';

        @shuffled = shuffle(@list);

If not, you can use a Fisher-Yates shuffle.

    sub fisher_yates_shuffle {
        my $deck = shift;  # $deck is a reference to an array
        my $i = @$deck;
        while (--$i) {
            my $j = int rand ($i+1);
            @$deck[$i,$j] = @$deck[$j,$i];
        }
    }

    # shuffle my mpeg collection
    #
    my @mpeg = <audio/*/*.mp3>;
    fisher_yates_shuffle( \@mpeg );    # randomize @mpeg in place
    print @mpeg;

Note that the above implementation shuffles an array in place, unlike the List::Util::shuffle() which takes a list and returns a new shuffled list.

You've probably seen shuffling algorithms that work using splice, randomly picking another element to swap the current element with

    srand;
    @new = ();
    @old = 1 .. 10;  # just a demo
    while (@old) {
        push(@new, splice(@old, rand @old, 1));
    }

This is bad because splice is already O(N), and since you do it N times, you just invented a quadratic algorithm; that is, O(N**2). This does not scale, although Perl is so efficient that you probably won't notice this until you have rather largish arrays.

How do I process/modify each element of an array?

Use for/foreach:

    for (@lines) {
                s/foo/bar/;     # change that word
                tr/XZ/ZX/;      # swap those letters
    }

Here's another; let's compute spherical volumes:

    for (@volumes = @radii) {   # @volumes has changed parts
                $_ **= 3;
                $_ *= (4/3) * 3.14159;  # this will be constant folded
    }

which can also be done with map() which is made to transform one list into another:

        @volumes = map {$_ ** 3 * (4/3) * 3.14159} @radii;

If you want to do the same thing to modify the values of the hash, you can use the values function. As of Perl 5.6 the values are not copied, so if you modify $orbit (in this case), you modify the value.

    for $orbit ( values %orbits ) {
                ($orbit **= 3) *= (4/3) * 3.14159;
    }

Prior to perl 5.6 values returned copies of the values, so older perl code often contains constructions such as @orbits{keys %orbits} instead of values %orbits where the hash is to be modified.

How do I select a random element from an array?

Use the rand() function (see rand in the perlfunc manpage):

    $index   = rand @array;
    $element = $array[$index];

Or, simply: my $element = $array[ rand @array ];

How do I permute N elements of a list?

Use the List::Permutor module on CPAN. If the list is actually an array, try the Algorithm::Permute module (also on CPAN). It's written in XS code and is very efficient.

        use Algorithm::Permute;
        my @array = 'a'..'d';
        my $p_iterator = Algorithm::Permute->new ( \@array );
        while (my @perm = $p_iterator->next) {
           print "next permutation: (@perm)\n";
        }

For even faster execution, you could do:

   use Algorithm::Permute;
   my @array = 'a'..'d';
   Algorithm::Permute::permute {
      print "next permutation: (@array)\n";
   } @array;

Here's a little program that generates all permutations of all the words on each line of input. The algorithm embodied in the permute() function is discussed in Volume 4 (still unpublished) of Knuth's The Art of Computer Programming and will work on any list:

        #!/usr/bin/perl -n
        # Fischer-Kause ordered permutation generator

        sub permute (&@) {
                my $code = shift;
                my @idx = 0..$#_;
                while ( $code->(@_[@idx]) ) {
                        my $p = $#idx;
                        --$p while $idx[$p-1] > $idx[$p];
                        my $q = $p or return;
                        push @idx, reverse splice @idx, $p;
                        ++$q while $idx[$p-1] > $idx[$q];
                        @idx[$p-1,$q]=@idx[$q,$p-1];
                }
        }

        permute {print"@_\n"} split;

How do I sort an array by (anything)?

Supply a comparison function to sort() (described in sort in the perlfunc manpage):

    @list = sort { $a <=> $b } @list;

The default sort function is cmp, string comparison, which would sort (1, 2, 10) into (1, 10, 2). <=>, used above, is the numerical comparison operator.

If you have a complicated function needed to pull out the part you want to sort on, then don't do it inside the sort function. Pull it out first, because the sort BLOCK can be called many times for the same element. Here's an example of how to pull out the first word after the first number on each item, and then sort those words case-insensitively.

    @idx = ();
    for (@data) {
        ($item) = /\d+\s*(\S+)/;
        push @idx, uc($item);
    }
    @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ];

which could also be written this way, using a trick that's come to be known as the Schwartzian Transform:

    @sorted = map  { $_->[0] }
              sort { $a->[1] cmp $b->[1] }
              map  { [ $_, uc( (/\d+\s*(\S+)/)[0]) ] } @data;

If you need to sort on several fields, the following paradigm is useful.

    @sorted = sort { field1($a) <=> field1($b) ||
                     field2($a) cmp field2($b) ||
                     field3($a) cmp field3($b)
                   }     @data;

This can be conveniently combined with precalculation of keys as given above.

See the sort article in the "Far More Than You Ever Wanted To Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz for more about this approach.

See also the question below on sorting hashes.

How do I manipulate arrays of bits?

Use pack() and unpack(), or else vec() and the bitwise operations.

For example, this sets $vec to have bit N set if $ints[N] was set:

    $vec = '';
    foreach(@ints) { vec($vec,$_,1) = 1 }

Here's how, given a vector in $vec, you can get those bits into your @ints array:

    sub bitvec_to_list {
        my $vec = shift;
        my @ints;
        # Find null-byte density then select best algorithm
        if ($vec =~ tr/\0// / length $vec > 0.95) {
            use integer;
            my $i;
            # This method is faster with mostly null-bytes
            while($vec =~ /[^\0]/g ) {
                $i = -9 + 8 * pos $vec;
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
                push @ints, $i if vec($vec, ++$i, 1);
            }
        } else {
            # This method is a fast general algorithm
            use integer;
            my $bits = unpack "b*", $vec;
            push @ints, 0 if $bits =~ s/^(\d)// && $1;
            push @ints, pos $bits while($bits =~ /1/g);
        }
        return \@ints;
    }

This method gets faster the more sparse the bit vector is. (Courtesy of Tim Bunce and Winfried Koenig.)

You can make the while loop a lot shorter with this suggestion from Benjamin Goldberg:

        while($vec =~ /[^\0]+/g ) {
           push @ints, grep vec($vec, $_, 1), $-[0] * 8 .. $+[0] * 8;
        }

Or use the CPAN module Bit::Vector:

    $vector = Bit::Vector->new($num_of_bits);
    $vector->Index_List_Store(@ints);
    @ints = $vector->Index_List_Read();

Bit::Vector provides efficient methods for bit vector, sets of small integers and "big int" math.

Here's a more extensive illustration using vec():

    # vec demo
    $vector = "\xff\x0f\xef\xfe";
    print "Ilya's string \\xff\\x0f\\xef\\xfe represents the number ",
        unpack("N", $vector), "\n";
    $is_set = vec($vector, 23, 1);
    print "Its 23rd bit is ", $is_set ? "set" : "clear", ".\n";
    pvec($vector);

    set_vec(1,1,1);
    set_vec(3,1,1);
    set_vec(23,1,1);

    set_vec(3,1,3);
    set_vec(3,2,3);
    set_vec(3,4,3);
    set_vec(3,4,7);
    set_vec(3,8,3);
    set_vec(3,8,7);

    set_vec(0,32,17);
    set_vec(1,32,17);

    sub set_vec {
        my ($offset, $width, $value) = @_;
        my $vector = '';
        vec($vector, $offset, $width) = $value;
        print "offset=$offset width=$width value=$value\n";
        pvec($vector);
    }

    sub pvec {
        my $vector = shift;
        my $bits = unpack("b*", $vector);
        my $i = 0;
        my $BASE = 8;

        print "vector length in bytes: ", length($vector), "\n";
        @bytes = unpack("A8" x length($vector), $bits);
        print "bits are: @bytes\n\n";
            }

Why does defined() return true on empty arrays and hashes?

The short story is that you should probably only use defined on scalars or functions, not on aggregates (arrays and hashes). See defined in the perlfunc manpage in the 5.004 release or later of Perl for more detail.

Data: Hashes (Associative Arrays)

How do I process an entire hash?

Use the each() function (see each in the perlfunc manpage) if you don't care whether it's sorted:

    while ( ($key, $value) = each %hash) {
        print "$key = $value\n";
    }

If you want it sorted, you'll have to use foreach() on the result of sorting the keys as shown in an earlier question.

What happens if I add or remove keys from a hash while iterating over it?

(contributed by brian d foy)

The easy answer is "Don't do that!"

If you iterate through the hash with each(), you can delete the key most recently returned without worrying about it. If you delete or add other keys, the iterator may skip or double up on them since perl may rearrange the hash table. See the entry for each() in the perlfunc manpage.

How do I look up a hash element by value?

Create a reverse hash:

    %by_value = reverse %by_key;
    $key = $by_value{$value};

That's not particularly efficient. It would be more space-efficient to use:

    while (($key, $value) = each %by_key) {
        $by_value{$value} = $key;
    }

If your hash could have repeated values, the methods above will only find one of the associated keys. This may or may not worry you. If it does worry you, you can always reverse the hash into a hash of arrays instead:

     while (($key, $value) = each %by_key) {
         push @{$key_list_by_value{$value}}, $key;
     }

How can I know how many entries are in a hash?

If you mean how many keys, then all you have to do is use the keys() function in a scalar context:

    $num_keys = keys %hash;

The keys() function also resets the iterator, which means that you may see strange results if you use this between uses of other hash operators such as each().

How do I sort a hash (optionally by value instead of key)?

(contributed by brian d foy)

To sort a hash, start with the keys. In this example, we give the list of keys to the sort function which then compares them ASCIIbetically (which might be affected by your locale settings). The output list has the keys in ASCIIbetical order. Once we have the keys, we can go through them to create a report which lists the keys in ASCIIbetical order.

        my @keys = sort { $a cmp $b } keys %hash;

        foreach my $key ( @keys )
                {
                printf "%-20s %6d\n", $key, $hash{$value};
                }

We could get more fancy in the sort() block though. Instead of comparing the keys, we can compute a value with them and use that value as the comparison.

For instance, to make our report order case-insensitive, we use the \L sequence in a double-quoted string to make everything lowercase. The sort() block then compares the lowercased values to determine in which order to put the keys.

        my @keys = sort { "\L$a" cmp "\L$b" } keys %hash;

Note: if the computation is expensive or the hash has many elements, you may want to look at the Schwartzian Transform to cache the computation results.

If we want to sort by the hash value instead, we use the hash key to look it up. We still get out a list of keys, but this time they are ordered by their value.

        my @keys = sort { $hash{$a} <=> $hash{$b} } keys %hash;

From there we can get more complex. If the hash values are the same, we can provide a secondary sort on the hash key.

        my @keys = sort {
                $hash{$a} <=> $hash{$b}
                        or
                "\L$a" cmp "\L$b"
                } keys %hash;

How can I always keep my hash sorted?

You can look into using the DB_File module and tie() using the $DB_BTREE hash bindings as documented in DB_File/"In Memory Databases". The Tie::IxHash module from CPAN might also be instructive.

What's the difference between "delete" and "undef" with hashes?

Hashes contain pairs of scalars: the first is the key, the second is the value. The key will be coerced to a string, although the value can be any kind of scalar: string, number, or reference. If a key $key is present in %hash, exists($hash{$key}) will return true. The value for a given key can be undef, in which case $hash{$key} will be undef while exists $hash{$key} will return true. This corresponds to ($key, undef) being in the hash.

Pictures help... here's the %hash table:

          keys  values
        +------+------+
        |  a   |  3   |
        |  x   |  7   |
        |  d   |  0   |
        |  e   |  2   |
        +------+------+

And these conditions hold

        $hash{'a'}                       is true
        $hash{'d'}                       is false
        defined $hash{'d'}               is true
        defined $hash{'a'}               is true
        exists $hash{'a'}                is true (Perl5 only)
        grep ($_ eq 'a', keys %hash)     is true

If you now say

        undef $hash{'a'}

your table now reads:

          keys  values
        +------+------+
        |  a   | undef|
        |  x   |  7   |
        |  d   |  0   |
        |  e   |  2   |
        +------+------+

and these conditions now hold; changes in caps:

        $hash{'a'}                       is FALSE
        $hash{'d'}                       is false
        defined $hash{'d'}               is true
        defined $hash{'a'}               is FALSE
        exists $hash{'a'}                is true (Perl5 only)
        grep ($_ eq 'a', keys %hash)     is true

Notice the last two: you have an undef value, but a defined key!

Now, consider this:

        delete $hash{'a'}

your table now reads:

          keys  values
        +------+------+
        |  x   |  7   |
        |  d   |  0   |
        |  e   |  2   |
        +------+------+

and these conditions now hold; changes in caps:

        $hash{'a'}                       is false
        $hash{'d'}                       is false
        defined $hash{'d'}               is true
        defined $hash{'a'}               is false
        exists $hash{'a'}                is FALSE (Perl5 only)
        grep ($_ eq 'a', keys %hash)     is FALSE

See, the whole entry is gone!

Why don't my tied hashes make the defined/exists distinction?

This depends on the tied hash's implementation of EXISTS(). For example, there isn't the concept of undef with hashes that are tied to DBM* files. It also means that exists() and defined() do the same thing with a DBM* file, and what they end up doing is not what they do with ordinary hashes.

How do I reset an each() operation part-way through?

Using keys %hash in scalar context returns the number of keys in the hash and resets the iterator associated with the hash. You may need to do this if you use last to exit a loop early so that when you re-enter it, the hash iterator has been reset.

How can I get the unique keys from two hashes?

First you extract the keys from the hashes into lists, then solve the "removing duplicates" problem described above. For example:

    %seen = ();
    for $element (keys(%foo), keys(%bar)) {
        $seen{$element}++;
    }
    @uniq = keys %seen;

Or more succinctly:

    @uniq = keys %{{%foo,%bar}};

Or if you really want to save space:

    %seen = ();
    while (defined ($key = each %foo)) {
        $seen{$key}++;
    }
    while (defined ($key = each %bar)) {
        $seen{$key}++;
    }
    @uniq = keys %seen;

How can I store a multidimensional array in a DBM file?

Either stringify the structure yourself (no fun), or else get the MLDBM (which uses Data::Dumper) module from CPAN and layer it on top of either DB_File or GDBM_File.

How can I make my hash remember the order I put elements into it?

Use the Tie::IxHash from CPAN.

    use Tie::IxHash;
    tie my %myhash, 'Tie::IxHash';
    for (my $i=0; $i<20; $i++) {
        $myhash{$i} = 2*$i;
    }
    my @keys = keys %myhash;
    # @keys = (0,1,2,3,...)

Why does passing a subroutine an undefined element in a hash create it?

If you say something like:

    somefunc($hash{"nonesuch key here"});

Then that element "autovivifies"; that is, it springs into existence whether you store something there or not. That's because functions get scalars passed in by reference. If somefunc() modifies $_[0], it has to be ready to write it back into the caller's version.

This has been fixed as of Perl5.004.

Normally, merely accessing a key's value for a nonexistent key does not cause that key to be forever there. This is different than awk's behavior.

How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?

Usually a hash ref, perhaps like this:

    $record = {
        NAME   => "Jason",
        EMPNO  => 132,
        TITLE  => "deputy peon",
        AGE    => 23,
        SALARY => 37_000,
        PALS   => [ "Norbert", "Rhys", "Phineas"],
    };

References are documented in the perlref manpage and the upcoming the perlreftut manpage. Examples of complex data structures are given in the perldsc manpage and the perllol manpage. Examples of structures and object-oriented classes are in the perltoot manpage.

How can I use a reference as a hash key?

(contributed by brian d foy)

Hash keys are strings, so you can't really use a reference as the key. When you try to do that, perl turns the reference into its stringified form (for instance, HASH(0xDEADBEEF)). From there you can't get back the reference from the stringified form, at least without doing some extra work on your own. Also remember that hash keys must be unique, but two different variables can store the same reference (and those variables can change later).

The Tie::RefHash module, which is distributed with perl, might be what you want. It handles that extra work.

Data: Misc

How do I handle binary data correctly?

Perl is binary clean, so this shouldn't be a problem. For example, this works fine (assuming the files are found):

    if (`cat /vmunix` =~ /gzip/) {
        print "Your kernel is GNU-zip enabled!\n";
    }

On less elegant (read: Byzantine) systems, however, you have to play tedious games with "text" versus "binary" files. See binmode in the perlfunc manpage or the perlopentut manpage.

If you're concerned about 8-bit ASCII data, then see the perllocale manpage.

If you want to deal with multibyte characters, however, there are some gotchas. See the section on Regular Expressions.

How do I determine whether a scalar is a number/whole/integer/float?

Assuming that you don't care about IEEE notations like "NaN" or "Infinity", you probably just want to use a regular expression.

   if (/\D/)            { print "has nondigits\n" }
   if (/^\d+$/)         { print "is a whole number\n" }
   if (/^-?\d+$/)       { print "is an integer\n" }
   if (/^[+-]?\d+$/)    { print "is a +/- integer\n" }
   if (/^-?\d+\.?\d*$/) { print "is a real number\n" }
   if (/^-?(?:\d+(?:\.\d*)?|\.\d+)$/) { print "is a decimal number\n" }
   if (/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/)
                        { print "a C float\n" }

There are also some commonly used modules for the task. the Scalar::Util manpage (distributed with 5.8) provides access to perl's internal function looks_like_number for determining whether a variable looks like a number. the Data::Types manpage exports functions that validate data types using both the above and other regular expressions. Thirdly, there is Regexp::Common which has regular expressions to match various types of numbers. Those three modules are available from the CPAN.

If you're on a POSIX system, Perl supports the POSIX::strtod function. Its semantics are somewhat cumbersome, so here's a getnum wrapper function for more convenient access. This function takes a string and returns the number it found, or undef for input that isn't a C float. The is_numeric function is a front end to getnum if you just want to say, "Is this a float?"

    sub getnum {
        use POSIX qw(strtod);
        my $str = shift;
        $str =~ s/^\s+//;
        $str =~ s/\s+$//;
        $! = 0;
        my($num, $unparsed) = strtod($str);
        if (($str eq '') || ($unparsed != 0) || $!) {
            return undef;
        } else {
            return $num;
        }
    }

    sub is_numeric { defined getnum($_[0]) }

Or you could check out the the String::Scanf manpage module on the CPAN instead. The POSIX module (part of the standard Perl distribution) provides the strtod and strtol for converting strings to double and longs, respectively.

How do I keep persistent data across program calls?

For some specific applications, you can use one of the DBM modules. See the AnyDBM_File manpage. More generically, you should consult the FreezeThaw or Storable modules from CPAN. Starting from Perl 5.8 Storable is part of the standard distribution. Here's one example using Storable's store and retrieve functions:

    use Storable;
    store(\%hash, "filename");

    # later on...
    $href = retrieve("filename");        # by ref
    %hash = %{ retrieve("filename") };   # direct to hash

How do I print out or copy a recursive data structure?

The Data::Dumper module on CPAN (or the 5.005 release of Perl) is great for printing out data structures. The Storable module on CPAN (or the 5.8 release of Perl), provides a function called dclone that recursively copies its argument.

    use Storable qw(dclone);
    $r2 = dclone($r1);

Where $r1 can be a reference to any kind of data structure you'd like. It will be deeply copied. Because dclone takes and returns references, you'd have to add extra punctuation if you had a hash of arrays that you wanted to copy.

    %newhash = %{ dclone(\%oldhash) };

How do I define methods for every class/object?

Use the UNIVERSAL class (see the UNIVERSAL manpage).

How do I verify a credit card checksum?

Get the Business::CreditCard module from CPAN.

How do I pack arrays of doubles or floats for XS code?

The kgbpack.c code in the PGPLOT module on CPAN does just this. If you're doing a lot of float or double processing, consider using the PDL module from CPAN instead--it makes number-crunching easy.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perlfaq5 - Files and Formats

    • How do I flush/unbuffer an output filehandle? Why must I do this?
    • How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
    • How do I count the number of lines in a file?
    • How can I use Perl's -i option from within a program?
    • How can I copy a file?
    • How do I make a temporary file name?
    • How can I manipulate fixed-record-length files?
    • How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
    • How can I use a filehandle indirectly?
    • How can I set up a footer format to be used with write()?
    • How can I write() into a string?
    • How can I output my numbers with commas added?
    • How can I translate tildes (~) in a filename?
    • How come when I open a file read-write it wipes it out?
    • Why do I sometimes get an "Argument list too long" when I use <*>?
    • Is there a leak/bug in glob()?
    • How can I open a file with a leading ">" or trailing blanks?
    • How can I reliably rename a file?
    • How can I lock a file?
    • Why can't I just open(FH, ">file.lock")?
    • I still don't get locking. I just want to increment the number in the file. How can I do this?
    • All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
    • How do I randomly update a binary file?
    • How do I get a file's timestamp in perl?
    • How do I set a file's timestamp in perl?
    • How do I print to more than one file at once?
    • How can I read in an entire file all at once?
    • How can I read in a file by paragraphs?
    • How can I read a single character from a file? From the keyboard?
    • How can I tell whether there's a character waiting on a filehandle?
    • How do I do a tail -f in perl?
    • How do I dup() a filehandle in Perl?
    • How do I close a file descriptor by number?
    • Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
    • Why doesn't glob("*.*") get all the files?
    • Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?
    • How do I select a random line from a file?
    • Why do I get weird spaces when I print an array of lines?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq5 - Files and Formats ($Revision: 1.42 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section deals with I/O and the "f" issues: filehandles, flushing, formats, and footers.

How do I flush/unbuffer an output filehandle? Why must I do this?

Perl does not support truly unbuffered output (except insofar as you can syswrite(OUT, $char, 1)), although it does support is "command buffering", in which a physical write is performed after every output command.

The C standard I/O library (stdio) normally buffers characters sent to devices so that there isn't a system call for each byte. In most stdio implementations, the type of output buffering and the size of the buffer varies according to the type of device. Perl's print() and write() functions normally buffer output, while syswrite() bypasses buffering all together.

If you want your output to be sent immediately when you execute print() or write() (for instance, for some network protocols), you must set the handle's autoflush flag. This flag is the Perl variable $| and when it is set to a true value, Perl will flush the handle's buffer after each print() or write(). Setting $| affects buffering only for the currently selected default file handle. You choose this handle with the one argument select() call (see $| in the perlvar manpage and select in the perlfunc manpage).

Use select() to choose the desired handle, then set its per-filehandle variables.

    $old_fh = select(OUTPUT_HANDLE);
    $| = 1;
    select($old_fh);

Some idioms can handle this in a single statement:

    select((select(OUTPUT_HANDLE), $| = 1)[0]);

    $| = 1, select $_ for select OUTPUT_HANDLE;

Some modules offer object-oriented access to handles and their variables, although they may be overkill if this is the only thing you do with them. You can use IO::Handle:

    use IO::Handle;
    open(DEV, ">/dev/printer");   # but is this?
    DEV->autoflush(1);

or IO::Socket:

    use IO::Socket;               # this one is kinda a pipe?
        my $sock = IO::Socket::INET->new( 'www.example.com:80' );

    $sock->autoflush();

How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?

Use the Tie::File module, which is included in the standard distribution since Perl 5.8.0.

How do I count the number of lines in a file?

One fairly efficient way is to count newlines in the file. The following program uses a feature of tr///, as documented in the perlop manpage. If your text file doesn't end with a newline, then it's not really a proper text file, so this may report one fewer line than you expect.

    $lines = 0;
    open(FILE, $filename) or die "Can't open `$filename': $!";
    while (sysread FILE, $buffer, 4096) {
        $lines += ($buffer =~ tr/\n//);
    }
    close FILE;

This assumes no funny games with newline translations.

How can I use Perl's -i option from within a program?

-i sets the value of Perl's $^I variable, which in turn affects the behavior of <>; see the perlrun manpage for more details. By modifying the appropriate variables directly, you can get the same behavior within a larger program. For example:

     # ...
     {
        local($^I, @ARGV) = ('.orig', glob("*.c"));
        while (<>) {
           if ($. == 1) {
               print "This line should appear at the top of each file\n";
           }
           s/\b(p)earl\b/${1}erl/i;        # Correct typos, preserving case
           print;
           close ARGV if eof;              # Reset $.
        }
     }
     # $^I and @ARGV return to their old values here

This block modifies all the .c files in the current directory, leaving a backup of the original data from each file in a new .c.orig file.

How can I copy a file?

(contributed by brian d foy)

Use the File::Copy module. It comes with Perl and can do a true copy across file systems, and it does its magic in a portable fashion.

        use File::Copy;

        copy( $original, $new_copy ) or die "Copy failed: $!";

If you can't use File::Copy, you'll have to do the work yourself: open the original file, open the destination file, then print to the destination file as you read the original.

How do I make a temporary file name?

If you don't need to know the name of the file, you can use open() with undef in place of the file name. The open() function creates an anonymous temporary file.

        open my $tmp, '+>', undef or die $!;

Otherwise, you can use the File::Temp module.

  use File::Temp qw/ tempfile tempdir /;

  $dir = tempdir( CLEANUP => 1 );
  ($fh, $filename) = tempfile( DIR => $dir );

  # or if you don't need to know the filename

  $fh = tempfile( DIR => $dir );

The File::Temp has been a standard module since Perl 5.6.1. If you don't have a modern enough Perl installed, use the new_tmpfile class method from the IO::File module to get a filehandle opened for reading and writing. Use it if you don't need to know the file's name:

    use IO::File;
    $fh = IO::File->new_tmpfile()
        or die "Unable to make new temporary file: $!";

If you're committed to creating a temporary file by hand, use the process ID and/or the current time-value. If you need to have many temporary files in one process, use a counter:

    BEGIN {
        use Fcntl;
        my $temp_dir = -d '/tmp' ? '/tmp' : $ENV{TMPDIR} || $ENV{TEMP};
        my $base_name = sprintf("%s/%d-%d-0000", $temp_dir, $$, time());
        sub temp_file {
            local *FH;
            my $count = 0;
            until (defined(fileno(FH)) || $count++ > 100) {
                $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
                # O_EXCL is required for security reasons.
                sysopen(FH, $base_name, O_WRONLY|O_EXCL|O_CREAT);
            }
            if (defined(fileno(FH))
                return (*FH, $base_name);
            } else {
                return ();
            }
        }
    }

How can I manipulate fixed-record-length files?

The most efficient way is using pack() and unpack(). This is faster than using substr() when taking many, many strings. It is slower for just a few.

Here is a sample chunk of code to break up and put back together again some fixed-format input lines, in this case from the output of a normal, Berkeley-style ps:

    # sample input line:
    #   15158 p5  T      0:00 perl /home/tchrist/scripts/now-what
    my $PS_T = 'A6 A4 A7 A5 A*';
    open my $ps, '-|', 'ps';
    print scalar <$ps>;
    my @fields = qw( pid tt stat time command );
    while (<$ps>) {
        my %process;
        @process{@fields} = unpack($PS_T, $_);
        for my $field ( @fields ) {
            print "$field: <$process{$field}>\n";
        }
        print 'line=', pack($PS_T, @process{@fields} ), "\n";
    }

We've used a hash slice in order to easily handle the fields of each row. Storing the keys in an array means it's easy to operate on them as a group or loop over them with for. It also avoids polluting the program with global variables and using symbolic references.

How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?

As of perl5.6, open() autovivifies file and directory handles as references if you pass it an uninitialized scalar variable. You can then pass these references just like any other scalar, and use them in the place of named handles.

        open my    $fh, $file_name;

        open local $fh, $file_name;

        print $fh "Hello World!\n";

        process_file( $fh );

Before perl5.6, you had to deal with various typeglob idioms which you may see in older code.

        open FILE, "> $filename";
        process_typeglob(   *FILE );
        process_reference( \*FILE );

        sub process_typeglob  { local *FH = shift; print FH  "Typeglob!" }
        sub process_reference { local $fh = shift; print $fh "Reference!" }

If you want to create many anonymous handles, you should check out the Symbol or IO::Handle modules.

How can I use a filehandle indirectly?

An indirect filehandle is using something other than a symbol in a place that a filehandle is expected. Here are ways to get indirect filehandles:

    $fh =   SOME_FH;       # bareword is strict-subs hostile
    $fh =  "SOME_FH";      # strict-refs hostile; same package only
    $fh =  *SOME_FH;       # typeglob
    $fh = \*SOME_FH;       # ref to typeglob (bless-able)
    $fh =  *SOME_FH{IO};   # blessed IO::Handle from *SOME_FH typeglob

Or, you can use the new method from one of the IO::* modules to create an anonymous filehandle, store that in a scalar variable, and use it as though it were a normal filehandle.

    use IO::Handle;                     # 5.004 or higher
    $fh = IO::Handle->new();

Then use any of those as you would a normal filehandle. Anywhere that Perl is expecting a filehandle, an indirect filehandle may be used instead. An indirect filehandle is just a scalar variable that contains a filehandle. Functions like print, open, seek, or the <FH> diamond operator will accept either a named filehandle or a scalar variable containing one:

    ($ifh, $ofh, $efh) = (*STDIN, *STDOUT, *STDERR);
    print $ofh "Type it: ";
    $got = <$ifh>
    print $efh "What was that: $got";

If you're passing a filehandle to a function, you can write the function in two ways:

    sub accept_fh {
        my $fh = shift;
        print $fh "Sending to indirect filehandle\n";
    }

Or it can localize a typeglob and use the filehandle directly:

    sub accept_fh {
        local *FH = shift;
        print  FH "Sending to localized filehandle\n";
    }

Both styles work with either objects or typeglobs of real filehandles. (They might also work with strings under some circumstances, but this is risky.)

    accept_fh(*STDOUT);
    accept_fh($handle);

In the examples above, we assigned the filehandle to a scalar variable before using it. That is because only simple scalar variables, not expressions or subscripts of hashes or arrays, can be used with built-ins like print, printf, or the diamond operator. Using something other than a simple scalar variable as a filehandle is illegal and won't even compile:

    @fd = (*STDIN, *STDOUT, *STDERR);
    print $fd[1] "Type it: ";                           # WRONG
    $got = <$fd[0]>                                     # WRONG
    print $fd[2] "What was that: $got";                 # WRONG

With print and printf, you get around this by using a block and an expression where you would place the filehandle:

    print  { $fd[1] } "funny stuff\n";
    printf { $fd[1] } "Pity the poor %x.\n", 3_735_928_559;
    # Pity the poor deadbeef.

That block is a proper block like any other, so you can put more complicated code there. This sends the message out to one of two places:

    $ok = -x "/bin/cat";
    print { $ok ? $fd[1] : $fd[2] } "cat stat $ok\n";
    print { $fd[ 1+ ($ok || 0) ]  } "cat stat $ok\n";

This approach of treating print and printf like object methods calls doesn't work for the diamond operator. That's because it's a real operator, not just a function with a comma-less argument. Assuming you've been storing typeglobs in your structure as we did above, you can use the built-in function named readline to read a record just as <> does. Given the initialization shown above for @fd, this would work, but only because readline() requires a typeglob. It doesn't work with objects or strings, which might be a bug we haven't fixed yet.

    $got = readline($fd[0]);

Let it be noted that the flakiness of indirect filehandles is not related to whether they're strings, typeglobs, objects, or anything else. It's the syntax of the fundamental operators. Playing the object game doesn't help you at all here.

How can I set up a footer format to be used with write()?

There's no builtin way to do this, but the perlform manpage has a couple of techniques to make it possible for the intrepid hacker.

How can I write() into a string?

See Accessing Formatting Internals in the perlform manpage for an swrite() function.

How can I output my numbers with commas added?

(contributed by brian d foy and Benjamin Goldberg)

You can use the Number::Format manpage to separate places in a number. It handles locale information for those of you who want to insert full stops instead (or anything else that they want to use, really).

This subroutine will add commas to your number:

        sub commify {
           local $_  = shift;
           1 while s/^([-+]?\d+)(\d{3})/$1,$2/;
           return $_;
           }

This regex from Benjamin Goldberg will add commas to numbers:

   s/(^[-+]?\d+?(?=(?>(?:\d{3})+)(?!\d))|\G\d{3}(?=\d))/$1,/g;

It is easier to see with comments:

   s/(
       ^[-+]?            # beginning of number.
       \d+?              # first digits before first comma
       (?=               # followed by, (but not included in the match) :
          (?>(?:\d{3})+) # some positive multiple of three digits.
          (?!\d)         # an *exact* multiple, not x * 3 + 1 or whatever.
       )
      |                  # or:
       \G\d{3}           # after the last group, get three digits
       (?=\d)            # but they have to have more digits after them.
   )/$1,/xg;

How can I translate tildes (~) in a filename?

Use the <> (glob()) operator, documented in the perlfunc manpage. Older versions of Perl require that you have a shell installed that groks tildes. Recent perl versions have this feature built in. The File::KGlob module (available from CPAN) gives more portable glob functionality.

Within Perl, you may use this directly:

        $filename =~ s{
          ^ ~             # find a leading tilde
          (               # save this in $1
              [^/]        # a non-slash character
                    *     # repeated 0 or more times (0 means me)
          )
        }{
          $1
              ? (getpwnam($1))[7]
              : ( $ENV{HOME} || $ENV{LOGDIR} )
        }ex;

How come when I open a file read-write it wipes it out?

Because you're using something like this, which truncates the file and then gives you read-write access:

    open(FH, "+> /path/name");          # WRONG (almost always)

Whoops. You should instead use this, which will fail if the file doesn't exist.

    open(FH, "+< /path/name");          # open for update

Using ">" always clobbers or creates. Using "<" never does either. The "+" doesn't change this.

Here are examples of many kinds of file opens. Those using sysopen() all assume

    use Fcntl;

To open file for reading:

    open(FH, "< $path")                                 || die $!;
    sysopen(FH, $path, O_RDONLY)                        || die $!;

To open file for writing, create new file if needed or else truncate old file:

    open(FH, "> $path") || die $!;
    sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT)        || die $!;
    sysopen(FH, $path, O_WRONLY|O_TRUNC|O_CREAT, 0666)  || die $!;

To open file for writing, create new file, file must not exist:

    sysopen(FH, $path, O_WRONLY|O_EXCL|O_CREAT)         || die $!;
    sysopen(FH, $path, O_WRONLY|O_EXCL|O_CREAT, 0666)   || die $!;

To open file for appending, create if necessary:

    open(FH, ">> $path") || die $!;
    sysopen(FH, $path, O_WRONLY|O_APPEND|O_CREAT)       || die $!;
    sysopen(FH, $path, O_WRONLY|O_APPEND|O_CREAT, 0666) || die $!;

To open file for appending, file must exist:

    sysopen(FH, $path, O_WRONLY|O_APPEND)               || die $!;

To open file for update, file must exist:

    open(FH, "+< $path")                                || die $!;
    sysopen(FH, $path, O_RDWR)                          || die $!;

To open file for update, create file if necessary:

    sysopen(FH, $path, O_RDWR|O_CREAT)                  || die $!;
    sysopen(FH, $path, O_RDWR|O_CREAT, 0666)            || die $!;

To open file for update, file must not exist:

    sysopen(FH, $path, O_RDWR|O_EXCL|O_CREAT)           || die $!;
    sysopen(FH, $path, O_RDWR|O_EXCL|O_CREAT, 0666)     || die $!;

To open a file without blocking, creating if necessary:

    sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT)
            or die "can't open /foo/somefile: $!":

Be warned that neither creation nor deletion of files is guaranteed to be an atomic operation over NFS. That is, two processes might both successfully create or unlink the same file! Therefore O_EXCL isn't as exclusive as you might wish.

See also the new the perlopentut manpage if you have it (new for 5.6).

Why do I sometimes get an "Argument list too long" when I use <*>?

The <> operator performs a globbing operation (see above). In Perl versions earlier than v5.6.0, the internal glob() operator forks csh(1) to do the actual glob expansion, but csh can't handle more than 127 items and so gives the error message Argument list too long. People who installed tcsh as csh won't have this problem, but their users may be surprised by it.

To get around this, either upgrade to Perl v5.6.0 or later, do the glob yourself with readdir() and patterns, or use a module like File::KGlob, one that doesn't use the shell to do globbing.

Is there a leak/bug in glob()?

Due to the current implementation on some operating systems, when you use the glob() function or its angle-bracket alias in a scalar context, you may cause a memory leak and/or unpredictable behavior. It's best therefore to use glob() only in list context.

How can I open a file with a leading ">" or trailing blanks?

(contributed by Brian McCauley)

The special two argument form of Perl's open() function ignores trailing blanks in filenames and infers the mode from certain leading characters (or a trailing "|"). In older versions of Perl this was the only version of open() and so it is prevalent in old code and books.

Unless you have a particular reason to use the two argument form you should use the three argument form of open() which does not treat any charcters in the filename as special.

        open FILE, "<", "  file  ";  # filename is "   file   "
        open FILE, ">", ">file";     # filename is ">file"

How can I reliably rename a file?

If your operating system supports a proper mv(1) utility or its functional equivalent, this works:

    rename($old, $new) or system("mv", $old, $new);

It may be more portable to use the File::Copy module instead. You just copy to the new file to the new name (checking return values), then delete the old one. This isn't really the same semantically as a rename(), which preserves meta-information like permissions, timestamps, inode info, etc.

Newer versions of File::Copy export a move() function.

How can I lock a file?

Perl's builtin flock() function (see the perlfunc manpage for details) will call flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and later), and lockf(3) if neither of the two previous system calls exists. On some systems, it may even use a different form of native locking. Here are some gotchas with Perl's flock():

  1. Produces a fatal error if none of the three system calls (or their close equivalent) exists.

  2. lockf(3) does not provide shared locking, and requires that the filehandle be open for writing (or appending, or read/writing).

  3. Some versions of flock() can't lock files over a network (e.g. on NFS file systems), so you'd need to force the use of fcntl(2) when you build Perl. But even this is dubious at best. See the flock entry of the perlfunc manpage and the INSTALL file in the source distribution for information on building Perl to do this.

    Two potentially non-obvious but traditional flock semantics are that it waits indefinitely until the lock is granted, and that its locks are merely advisory. Such discretionary locks are more flexible, but offer fewer guarantees. This means that files locked with flock() may be modified by programs that do not also use flock(). Cars that stop for red lights get on well with each other, but not with cars that don't stop for red lights. See the perlport manpage, your port's specific documentation, or your system-specific local manpages for details. It's best to assume traditional behavior if you're writing portable programs. (If you're not, you should as always feel perfectly free to write for your own system's idiosyncrasies (sometimes called "features"). Slavish adherence to portability concerns shouldn't get in the way of your getting your job done.)

    For more information on file locking, see also File Locking in the perlopentut manpage if you have it (new for 5.6).

Why can't I just open(FH, ">file.lock")?

A common bit of code NOT TO USE is this:

    sleep(3) while -e "file.lock";      # PLEASE DO NOT USE
    open(LCK, "> file.lock");           # THIS BROKEN CODE

This is a classic race condition: you take two steps to do something which must be done in one. That's why computer hardware provides an atomic test-and-set instruction. In theory, this "ought" to work:

    sysopen(FH, "file.lock", O_WRONLY|O_EXCL|O_CREAT)
                or die "can't open  file.lock: $!";

except that lamentably, file creation (and deletion) is not atomic over NFS, so this won't work (at least, not every time) over the net. Various schemes involving link() have been suggested, but these tend to involve busy-wait, which is also subdesirable.

I still don't get locking. I just want to increment the number in the file. How can I do this?

Didn't anyone ever tell you web-page hit counters were useless? They don't count number of hits, they're a waste of time, and they serve only to stroke the writer's vanity. It's better to pick a random number; they're more realistic.

Anyway, this is what you can do if you can't help yourself.

    use Fcntl qw(:DEFAULT :flock);
    sysopen(FH, "numfile", O_RDWR|O_CREAT)       or die "can't open numfile: $!";
    flock(FH, LOCK_EX)                           or die "can't flock numfile: $!";
    $num = <FH> || 0;
    seek(FH, 0, 0)                               or die "can't rewind numfile: $!";
    truncate(FH, 0)                              or die "can't truncate numfile: $!";
    (print FH $num+1, "\n")                      or die "can't write numfile: $!";
    close FH                                     or die "can't close numfile: $!";

Here's a much better web-page hit counter:

    $hits = int( (time() - 850_000_000) / rand(1_000) );

If the count doesn't impress your friends, then the code might. :-)

All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?

If you are on a system that correctly implements flock() and you use the example appending code from "perldoc -f flock" everything will be OK even if the OS you are on doesn't implement append mode correctly (if such a system exists.) So if you are happy to restrict yourself to OSs that implement flock() (and that's not really much of a restriction) then that is what you should do.

If you know you are only going to use a system that does correctly implement appending (i.e. not Win32) then you can omit the seek() from the above code.

If you know you are only writing code to run on an OS and filesystem that does implement append mode correctly (a local filesystem on a modern Unix for example), and you keep the file in block-buffered mode and you write less than one buffer-full of output between each manual flushing of the buffer then each bufferload is almost guaranteed to be written to the end of the file in one chunk without getting intermingled with anyone else's output. You can also use the syswrite() function which is simply a wrapper around your systems write(2) system call.

There is still a small theoretical chance that a signal will interrupt the system level write() operation before completion. There is also a possibility that some STDIO implementations may call multiple system level write()s even if the buffer was empty to start. There may be some systems where this probability is reduced to zero.

How do I randomly update a binary file?

If you're just trying to patch a binary, in many cases something as simple as this works:

    perl -i -pe 's{window manager}{window mangler}g' /usr/bin/emacs

However, if you have fixed sized records, then you might do something more like this:

    $RECSIZE = 220; # size of record, in bytes
    $recno   = 37;  # which record to update
    open(FH, "+<somewhere") || die "can't update somewhere: $!";
    seek(FH, $recno * $RECSIZE, 0);
    read(FH, $record, $RECSIZE) == $RECSIZE || die "can't read record $recno: $!";
    # munge the record
    seek(FH, -$RECSIZE, 1);
    print FH $record;
    close FH;

Locking and error checking are left as an exercise for the reader. Don't forget them or you'll be quite sorry.

How do I get a file's timestamp in perl?

If you want to retrieve the time at which the file was last read, written, or had its meta-data (owner, etc) changed, you use the -A, -M, or -C file test operations as documented in the perlfunc manpage. These retrieve the age of the file (measured against the start-time of your program) in days as a floating point number. Some platforms may not have all of these times. See the perlport manpage for details. To retrieve the "raw" time in seconds since the epoch, you would call the stat function, then use localtime(), gmtime(), or POSIX::strftime() to convert this into human-readable form.

Here's an example:

    $write_secs = (stat($file))[9];
    printf "file %s updated at %s\n", $file,
        scalar localtime($write_secs);

If you prefer something more legible, use the File::stat module (part of the standard distribution in version 5.004 and later):

    # error checking left as an exercise for reader.
    use File::stat;
    use Time::localtime;
    $date_string = ctime(stat($file)->mtime);
    print "file $file updated at $date_string\n";

The POSIX::strftime() approach has the benefit of being, in theory, independent of the current locale. See the perllocale manpage for details.

How do I set a file's timestamp in perl?

You use the utime() function documented in utime in the perlfunc manpage. By way of example, here's a little program that copies the read and write times from its first argument to all the rest of them.

    if (@ARGV < 2) {
        die "usage: cptimes timestamp_file other_files ...\n";
    }
    $timestamp = shift;
    ($atime, $mtime) = (stat($timestamp))[8,9];
    utime $atime, $mtime, @ARGV;

Error checking is, as usual, left as an exercise for the reader.

The perldoc for utime also has an example that has the same effect as touch(1) on files that already exist.

Certain file systems have a limited ability to store the times on a file at the expected level of precision. For example, the FAT and HPFS filesystem are unable to create dates on files with a finer granularity than two seconds. This is a limitation of the filesystems, not of utime().

How do I print to more than one file at once?

To connect one filehandle to several output filehandles, you can use the IO::Tee or Tie::FileHandle::Multiplex modules.

If you only have to do this once, you can print individually to each filehandle.

    for $fh (FH1, FH2, FH3) { print $fh "whatever\n" }

How can I read in an entire file all at once?

You can use the File::Slurp module to do it in one step.

        use File::Slurp;

        $all_of_it = read_file($filename); # entire file in scalar
            @all_lines = read_file($filename); # one line perl element

The customary Perl approach for processing all the lines in a file is to do so one line at a time:

    open (INPUT, $file)         || die "can't open $file: $!";
    while (<INPUT>) {
        chomp;
        # do something with $_
    }
    close(INPUT)                || die "can't close $file: $!";

This is tremendously more efficient than reading the entire file into memory as an array of lines and then processing it one element at a time, which is often--if not almost always--the wrong approach. Whenever you see someone do this:

    @lines = <INPUT>;

you should think long and hard about why you need everything loaded at once. It's just not a scalable solution. You might also find it more fun to use the standard Tie::File module, or the DB_File module's $DB_RECNO bindings, which allow you to tie an array to a file so that accessing an element the array actually accesses the corresponding line in the file.

You can read the entire filehandle contents into a scalar.

    {
        local(*INPUT, $/);
        open (INPUT, $file)     || die "can't open $file: $!";
        $var = <INPUT>;
    }

That temporarily undefs your record separator, and will automatically close the file at block exit. If the file is already open, just use this:

    $var = do { local $/; <INPUT> };

For ordinary files you can also use the read function.

        read( INPUT, $var, -s INPUT );

The third argument tests the byte size of the data on the INPUT filehandle and reads that many bytes into the buffer $var.

How can I read in a file by paragraphs?

Use the $/ variable (see the perlvar manpage for details). You can either set it to "" to eliminate empty paragraphs ("abc\n\n\n\ndef", for instance, gets treated as two paragraphs and not three), or "\n\n" to accept empty paragraphs.

Note that a blank line must have no blanks in it. Thus "fred\n \nstuff\n\n" is one paragraph, but "fred\n\nstuff\n\n" is two.

How can I read a single character from a file? From the keyboard?

You can use the builtin getc() function for most filehandles, but it won't (easily) work on a terminal device. For STDIN, either use the Term::ReadKey module from CPAN or use the sample code in getc in the perlfunc manpage.

If your system supports the portable operating system programming interface (POSIX), you can use the following code, which you'll note turns off echo processing as well.

    #!/usr/bin/perl -w
    use strict;
    $| = 1;
    for (1..4) {
        my $got;
        print "gimme: ";
        $got = getone();
        print "--> $got\n";
    }
    exit;

    BEGIN {
        use POSIX qw(:termios_h);

        my ($term, $oterm, $echo, $noecho, $fd_stdin);

        $fd_stdin = fileno(STDIN);

        $term     = POSIX::Termios->new();
        $term->getattr($fd_stdin);
        $oterm     = $term->getlflag();

        $echo     = ECHO | ECHOK | ICANON;
        $noecho   = $oterm & ~$echo;

        sub cbreak {
            $term->setlflag($noecho);
            $term->setcc(VTIME, 1);
            $term->setattr($fd_stdin, TCSANOW);
        }

        sub cooked {
            $term->setlflag($oterm);
            $term->setcc(VTIME, 0);
            $term->setattr($fd_stdin, TCSANOW);
        }

        sub getone {
            my $key = '';
            cbreak();
            sysread(STDIN, $key, 1);
            cooked();
            return $key;
        }

    }
    END { cooked() }

The Term::ReadKey module from CPAN may be easier to use. Recent versions include also support for non-portable systems as well.

    use Term::ReadKey;
    open(TTY, "</dev/tty");
    print "Gimme a char: ";
    ReadMode "raw";
    $key = ReadKey 0, *TTY;
    ReadMode "normal";
    printf "\nYou said %s, char number %03d\n",
        $key, ord $key;

How can I tell whether there's a character waiting on a filehandle?

The very first thing you should do is look into getting the Term::ReadKey extension from CPAN. As we mentioned earlier, it now even has limited support for non-portable (read: not open systems, closed, proprietary, not POSIX, not Unix, etc) systems.

You should also check out the Frequently Asked Questions list in comp.unix.* for things like this: the answer is essentially the same. It's very system dependent. Here's one solution that works on BSD systems:

    sub key_ready {
        my($rin, $nfd);
        vec($rin, fileno(STDIN), 1) = 1;
        return $nfd = select($rin,undef,undef,0);
    }

If you want to find out how many characters are waiting, there's also the FIONREAD ioctl call to be looked at. The h2ph tool that comes with Perl tries to convert C include files to Perl code, which can be required. FIONREAD ends up defined as a function in the sys/ioctl.ph file:

    require 'sys/ioctl.ph';

    $size = pack("L", 0);
    ioctl(FH, FIONREAD(), $size)    or die "Couldn't call ioctl: $!\n";
    $size = unpack("L", $size);

If h2ph wasn't installed or doesn't work for you, you can grep the include files by hand:

    % grep FIONREAD /usr/include/*/*
    /usr/include/asm/ioctls.h:#define FIONREAD      0x541B

Or write a small C program using the editor of champions:

    % cat > fionread.c
    #include <sys/ioctl.h>
    main() {
        printf("%#08x\n", FIONREAD);
    }
    ^D
    % cc -o fionread fionread.c
    % ./fionread
    0x4004667f

And then hard code it, leaving porting as an exercise to your successor.

    $FIONREAD = 0x4004667f;         # XXX: opsys dependent

    $size = pack("L", 0);
    ioctl(FH, $FIONREAD, $size)     or die "Couldn't call ioctl: $!\n";
    $size = unpack("L", $size);

FIONREAD requires a filehandle connected to a stream, meaning that sockets, pipes, and tty devices work, but not files.

How do I do a tail -f in perl?

First try

    seek(GWFILE, 0, 1);

The statement seek(GWFILE, 0, 1) doesn't change the current position, but it does clear the end-of-file condition on the handle, so that the next <GWFILE> makes Perl try again to read something.

If that doesn't work (it relies on features of your stdio implementation), then you need something more like this:

        for (;;) {
          for ($curpos = tell(GWFILE); <GWFILE>; $curpos = tell(GWFILE)) {
            # search for some stuff and put it into files
          }
          # sleep for a while
          seek(GWFILE, $curpos, 0);  # seek to where we had been
        }

If this still doesn't work, look into the POSIX module. POSIX defines the clearerr() method, which can remove the end of file condition on a filehandle. The method: read until end of file, clearerr(), read some more. Lather, rinse, repeat.

There's also a File::Tail module from CPAN.

How do I dup() a filehandle in Perl?

If you check open in the perlfunc manpage, you'll see that several of the ways to call open() should do the trick. For example:

    open(LOG, ">>/foo/logfile");
    open(STDERR, ">&LOG");

Or even with a literal numeric descriptor:

   $fd = $ENV{MHCONTEXTFD};
   open(MHCONTEXT, "<&=$fd");   # like fdopen(3S)

Note that "<&STDIN" makes a copy, but "<&=STDIN" make an alias. That means if you close an aliased handle, all aliases become inaccessible. This is not true with a copied one.

Error checking, as always, has been left as an exercise for the reader.

How do I close a file descriptor by number?

This should rarely be necessary, as the Perl close() function is to be used for things that Perl opened itself, even if it was a dup of a numeric descriptor as with MHCONTEXT above. But if you really have to, you may be able to do this:

    require 'sys/syscall.ph';
    $rc = syscall(&SYS_close, $fd + 0);  # must force numeric
    die "can't sysclose $fd: $!" unless $rc == -1;

Or, just use the fdopen(3S) feature of open():

    {
        local *F;
        open F, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
        close F;
    }

Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?

Whoops! You just put a tab and a formfeed into that filename! Remember that within double quoted strings ("like\this"), the backslash is an escape character. The full list of these is in Quote and Quote-like Operators in the perlop manpage. Unsurprisingly, you don't have a file called "c:(tab)emp(formfeed)oo" or "c:(tab)emp(formfeed)oo.exe" on your legacy DOS filesystem.

Either single-quote your strings, or (preferably) use forward slashes. Since all DOS and Windows versions since something like MS-DOS 2.0 or so have treated / and \ the same in a path, you might as well use the one that doesn't clash with Perl--or the POSIX shell, ANSI C and C++, awk, Tcl, Java, or Python, just to mention a few. POSIX paths are more portable, too.

Why doesn't glob("*.*") get all the files?

Because even on non-Unix ports, Perl's glob function follows standard Unix globbing semantics. You'll need glob("*") to get all (non-hidden) files. This makes glob() portable even to legacy systems. Your port may include proprietary globbing functions as well. Check its documentation for details.

Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?

This is elaborately and painstakingly described in the file-dir-perms article in the "Far More Than You Ever Wanted To Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz .

The executive summary: learn how your filesystem works. The permissions on a file say what can happen to the data in that file. The permissions on a directory say what can happen to the list of files in that directory. If you delete a file, you're removing its name from the directory (so the operation depends on the permissions of the directory, not of the file). If you try to write to the file, the permissions of the file govern whether you're allowed to.

How do I select a random line from a file?

Here's an algorithm from the Camel Book:

    srand;
    rand($.) < 1 && ($line = $_) while <>;

This has a significant advantage in space over reading the whole file in. You can find a proof of this method in The Art of Computer Programming, Volume 2, Section 3.4.2, by Donald E. Knuth.

You can use the File::Random module which provides a function for that algorithm:

        use File::Random qw/random_line/;
        my $line = random_line($filename);

Another way is to use the Tie::File module, which treats the entire file as an array. Simply access a random array element.

Why do I get weird spaces when I print an array of lines?

Saying

    print "@lines\n";

joins together the elements of @lines with a space between them. If @lines were ("little", "fluffy", "clouds") then the above statement would print

    little fluffy clouds

but if each element of @lines was a line of text, ending a newline character ("little\n", "fluffy\n", "clouds\n") then it would print:

    little
     fluffy
     clouds

If your array contains lines, just print them:

    print @lines;

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples here are in the public domain. You are permitted and encouraged to use this code and any derivatives thereof in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit to the FAQ would be courteous but is not required.


perlfaq6 - Regular Expressions

    • How can I hope to use regular expressions without creating illegible and unmaintainable code?
    • I'm having trouble matching over more than one line. What's wrong?
    • How can I pull out lines between two patterns that are themselves on different lines?
    • I put a regular expression into $/ but it didn't work. What's wrong?
    • How do I substitute case insensitively on the LHS while preserving case on the RHS?
    • How can I make \w match national character sets?
    • How can I match a locale-smart version of /[a-zA-Z]/?
    • How can I quote a variable to use in a regex?
    • What is /o really for?
    • How do I use a regular expression to strip C style comments from a file?
    • Can I use Perl regular expressions to match balanced text?
    • What does it mean that regexes are greedy? How can I get around it?
    • How do I process each word on each line?
    • How can I print out a word-frequency or line-frequency summary?
    • How can I do approximate matching?
    • How do I efficiently match many regular expressions at once?
    • Why don't word-boundary searches with \b work for me?
    • Why does using $&, $`, or $' slow my program down?
    • What good is \G in a regular expression?
    • Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
    • What's wrong with using grep in a void context?
    • How can I match strings with multibyte characters?
    • How do I match a pattern that is supplied by the user?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq6 - Regular Expressions ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number are handled with regular expressions, but those answers are found elsewhere in this document (in the perlfaq9 manpage: "How do I decode or create those %-encodings on the web" and the perlfaq4 manpage: "How do I determine whether a scalar is a number/whole/integer/float", to be precise).

How can I hope to use regular expressions without creating illegible and unmaintainable code?

Three techniques can make regular expressions maintainable and understandable.

Comments Outside the Regex

Describe what you're doing and how you're doing it, using normal Perl comments.

    # turn the line into the first word, a colon, and the
    # number of characters on the rest of the line
    s/^(\w+)(.*)/ lc($1) . ":" . length($2) /meg;
Comments Inside the Regex

The /x modifier causes whitespace to be ignored in a regex pattern (except in a character class), and also allows you to use normal comments there, too. As you can imagine, whitespace and comments help a lot.

/x lets you turn this:

    s{<(?:[^>'"]*|".*?"|'.*?')+>}{}gs;

into this:

    s{ <                    # opening angle bracket
        (?:                 # Non-backreffing grouping paren
             [^>'"] *       # 0 or more things that are neither > nor ' nor "
                |           #    or else
             ".*?"          # a section between double quotes (stingy match)
                |           #    or else
             '.*?'          # a section between single quotes (stingy match)
        ) +                 #   all occurring one or more times
       >                    # closing angle bracket
    }{}gsx;                 # replace with nothing, i.e. delete

It's still not quite so clear as prose, but it is very useful for describing the meaning of each part of the pattern.

Different Delimiters

While we normally think of patterns as being delimited with / characters, they can be delimited by almost any character. the perlre manpage describes this. For example, the s/// above uses braces as delimiters. Selecting another delimiter can avoid quoting the delimiter within the pattern:

    s/\/usr\/local/\/usr\/share/g;      # bad delimiter choice
    s#/usr/local#/usr/share#g;          # better

I'm having trouble matching over more than one line. What's wrong?

Either you don't have more than one line in the string you're looking at (probably), or else you aren't using the correct modifier(s) on your pattern (possibly).

There are many ways to get multiline data into a string. If you want it to happen automatically while reading input, you'll want to set $/ (probably to '' for paragraphs or undef for the whole file) to allow you to read more than one line at a time.

Read the perlre manpage to help you decide which of /s and /m (or both) you might want to use: /s allows dot to include newline, and /m allows caret and dollar to match next to a newline, not just at the end of the string. You do need to make sure that you've actually got a multiline string in there.

For example, this program detects duplicate words, even when they span line breaks (but not paragraph ones). For this example, we don't need /s because we aren't using dot in a regular expression that we want to cross line boundaries. Neither do we need /m because we aren't wanting caret or dollar to match at any point inside the record next to newlines. But it's imperative that $/ be set to something other than the default, or else we won't actually ever have a multiline record read in.

    $/ = '';            # read in more whole paragraph, not just one line
    while ( <> ) {
        while ( /\b([\w'-]+)(\s+\1)+\b/gi ) {   # word starts alpha
            print "Duplicate $1 at paragraph $.\n";
        }
    }

Here's code that finds sentences that begin with "From " (which would be mangled by many mailers):

    $/ = '';            # read in more whole paragraph, not just one line
    while ( <> ) {
        while ( /^From /gm ) { # /m makes ^ match next to \n
            print "leading from in paragraph $.\n";
        }
    }

Here's code that finds everything between START and END in a paragraph:

    undef $/;           # read in whole file, not just one line or paragraph
    while ( <> ) {
        while ( /START(.*?)END/sgm ) { # /s makes . cross line boundaries
            print "$1\n";
        }
    }

How can I pull out lines between two patterns that are themselves on different lines?

You can use Perl's somewhat exotic .. operator (documented in the perlop manpage):

    perl -ne 'print if /START/ .. /END/' file1 file2 ...

If you wanted text and not lines, you would use

    perl -0777 -ne 'print "$1\n" while /START(.*?)END/gs' file1 file2 ...

But if you want nested occurrences of START through END, you'll run up against the problem described in the question in this section on matching balanced text.

Here's another example of using ..:

    while (<>) {
        $in_header =   1  .. /^$/;
        $in_body   = /^$/ .. eof();
        # now choose between them
    } continue {
        reset if eof();         # fix $.
    }

I put a regular expression into $/ but it didn't work. What's wrong?

Up to Perl 5.8.0, $/ has to be a string. This may change in 5.10, but don't get your hopes up. Until then, you can use these examples if you really need to do this.

If you have File::Stream, this is easy.

                         use File::Stream;
                                      my $stream = File::Stream->new(
                                           $filehandle,
                                           separator => qr/\s*,\s*/,
                                           );

                         print "$_\n" while <$stream>;

If you don't have File::Stream, you have to do a little more work.

You can use the four argument form of sysread to continually add to a buffer. After you add to the buffer, you check if you have a complete line (using your regular expression).

       local $_ = "";
       while( sysread FH, $_, 8192, length ) {
          while( s/^((?s).*?)your_pattern/ ) {
             my $record = $1;
             # do stuff here.
          }
       }

 You can do the same thing with foreach and a match using the
 c flag and the \G anchor, if you do not mind your entire file
 being in memory at the end.
       local $_ = "";
       while( sysread FH, $_, 8192, length ) {
          foreach my $record ( m/\G((?s).*?)your_pattern/gc ) {
             # do stuff here.
          }
          substr( $_, 0, pos ) = "" if pos;
       }

How do I substitute case insensitively on the LHS while preserving case on the RHS?

Here's a lovely Perlish solution by Larry Rosler. It exploits properties of bitwise xor on ASCII strings.

    $_= "this is a TEsT case";

    $old = 'test';
    $new = 'success';

    s{(\Q$old\E)}
     { uc $new | (uc $1 ^ $1) .
        (uc(substr $1, -1) ^ substr $1, -1) x
            (length($new) - length $1)
     }egi;

    print;

And here it is as a subroutine, modeled after the above:

    sub preserve_case($$) {
        my ($old, $new) = @_;
        my $mask = uc $old ^ $old;

        uc $new | $mask .
            substr($mask, -1) x (length($new) - length($old))
    }
    $a = "this is a TEsT case";
    $a =~ s/(test)/preserve_case($1, "success")/egi;
    print "$a\n";

This prints:

    this is a SUcCESS case

As an alternative, to keep the case of the replacement word if it is longer than the original, you can use this code, by Jeff Pinyan:

  sub preserve_case {
    my ($from, $to) = @_;
    my ($lf, $lt) = map length, @_;

    if ($lt < $lf) { $from = substr $from, 0, $lt }
    else { $from .= substr $to, $lf }

    return uc $to | ($from ^ uc $from);
      }

This changes the sentence to "this is a SUcCess case."

Just to show that C programmers can write C in any programming language, if you prefer a more C-like solution, the following script makes the substitution have the same case, letter by letter, as the original. (It also happens to run about 240% slower than the Perlish solution runs.) If the substitution has more characters than the string being substituted, the case of the last character is used for the rest of the substitution.

    # Original by Nathan Torkington, massaged by Jeffrey Friedl
    #
    sub preserve_case($$)
    {
        my ($old, $new) = @_;
        my ($state) = 0; # 0 = no change; 1 = lc; 2 = uc
        my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new));
        my ($len) = $oldlen < $newlen ? $oldlen : $newlen;

        for ($i = 0; $i < $len; $i++) {
            if ($c = substr($old, $i, 1), $c =~ /[\W\d_]/) {
                $state = 0;
            } elsif (lc $c eq $c) {
                substr($new, $i, 1) = lc(substr($new, $i, 1));
                $state = 1;
            } else {
                substr($new, $i, 1) = uc(substr($new, $i, 1));
                $state = 2;
            }
        }
        # finish up with any remaining new (for when new is longer than old)
        if ($newlen > $oldlen) {
            if ($state == 1) {
                substr($new, $oldlen) = lc(substr($new, $oldlen));
            } elsif ($state == 2) {
                substr($new, $oldlen) = uc(substr($new, $oldlen));
            }
        }
        return $new;
            }

How can I make \w match national character sets?

Put use locale; in your script. The \w character class is taken from the current locale.

See the perllocale manpage for details.

How can I match a locale-smart version of /[a-zA-Z]/?

You can use the POSIX character class syntax /[[:alpha:]]/ documented in the perlre manpage.

No matter which locale you are in, the alphabetic characters are the characters in \w without the digits and the underscore. As a regex, that looks like /[^\W\d_]/. Its complement, the non-alphabetics, is then everything in \W along with the digits and the underscore, or /[\W\d_]/.

How can I quote a variable to use in a regex?

The Perl parser will expand $variable and @variable references in regular expressions unless the delimiter is a single quote. Remember, too, that the right-hand side of a s/// substitution is considered a double-quoted string (see the perlop manpage for more details). Remember also that any regex special characters will be acted on unless you precede the substitution with \Q. Here's an example:

    $string = "Placido P. Octopus";
    $regex  = "P.";

    $string =~ s/$regex/Polyp/;
    # $string is now "Polypacido P. Octopus"

Because . is special in regular expressions, and can match any single character, the regex P. here has matched the <Pl> in the original string.

To escape the special meaning of ., we use \Q:

    $string = "Placido P. Octopus";
    $regex  = "P.";

    $string =~ s/\Q$regex/Polyp/;
    # $string is now "Placido Polyp Octopus"

The use of \Q causes the <.> in the regex to be treated as a regular character, so that P. matches a P followed by a dot.

What is /o really for?

Using a variable in a regular expression match forces a re-evaluation (and perhaps recompilation) each time the regular expression is encountered. The /o modifier locks in the regex the first time it's used. This always happens in a constant regular expression, and in fact, the pattern was compiled into the internal format at the same time your entire program was.

Use of /o is irrelevant unless variable interpolation is used in the pattern, and if so, the regex engine will neither know nor care whether the variables change after the pattern is evaluated the very first time.

/o is often used to gain an extra measure of efficiency by not performing subsequent evaluations when you know it won't matter (because you know the variables won't change), or more rarely, when you don't want the regex to notice if they do.

For example, here's a "paragrep" program:

    $/ = '';  # paragraph mode
    $pat = shift;
    while (<>) {
        print if /$pat/o;
    }

How do I use a regular expression to strip C style comments from a file?

While this actually can be done, it's much harder than you'd think. For example, this one-liner

    perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c

will work in many but not all cases. You see, it's too simple-minded for certain kinds of C programs, in particular, those with what appear to be comments in quoted strings. For that, you'd need something like this, created by Jeffrey Friedl and later modified by Fred Curtis.

    $/ = undef;
    $_ = <>;
    s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
    print;

This could, of course, be more legibly written with the /x modifier, adding whitespace and comments. Here it is expanded, courtesy of Fred Curtis.

    s{
       /\*         ##  Start of /* ... */ comment
       [^*]*\*+    ##  Non-* followed by 1-or-more *'s
       (
         [^/*][^*]*\*+
       )*          ##  0-or-more things which don't start with /
                   ##    but do end with '*'
       /           ##  End of /* ... */ comment
     |         ##     OR  various things which aren't comments:
       (
         "           ##  Start of " ... " string
         (
           \\.           ##  Escaped char
         |               ##    OR
           [^"\\]        ##  Non "\
         )*
         "           ##  End of " ... " string
       |         ##     OR
         '           ##  Start of ' ... ' string
         (
           \\.           ##  Escaped char
         |               ##    OR
           [^'\\]        ##  Non '\
         )*
         '           ##  End of ' ... ' string
       |         ##     OR
         .           ##  Anything other char
         [^/"'\\]*   ##  Chars which doesn't start a comment, string or escape
       )
     }{defined $2 ? $2 : ""}gxse;

A slight modification also removes C++ comments:

    s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;

Can I use Perl regular expressions to match balanced text?

Historically, Perl regular expressions were not capable of matching balanced text. As of more recent versions of perl including 5.6.1 experimental features have been added that make it possible to do this. Look at the documentation for the (??{ }) construct in recent perlre manual pages to see an example of matching balanced parentheses. Be sure to take special notice of the warnings present in the manual before making use of this feature.

CPAN contains many modules that can be useful for matching text depending on the context. Damian Conway provides some useful patterns in Regexp::Common. The module Text::Balanced provides a general solution to this problem.

One of the common applications of balanced text matching is working with XML and HTML. There are many modules available that support these needs. Two examples are HTML::Parser and XML::Parser. There are many others.

An elaborate subroutine (for 7-bit ASCII only) to pull out balanced and possibly nested single chars, like ` and ', { and }, or ( and ) can be found in http://www.cpan.org/authors/id/TOMC/scripts/pull_quotes.gz .

The C::Scan module from CPAN also contains such subs for internal use, but they are undocumented.

What does it mean that regexes are greedy? How can I get around it?

Most people mean that greedy regexes match as much as they can. Technically speaking, it's actually the quantifiers (?, *, +, {}) that are greedy rather than the whole pattern; Perl prefers local greed and immediate gratification to overall greed. To get non-greedy versions of the same quantifiers, use (??, *?, +?, {}?).

An example:

        $s1 = $s2 = "I am very very cold";
        $s1 =~ s/ve.*y //;      # I am cold
        $s2 =~ s/ve.*?y //;     # I am very cold

Notice how the second substitution stopped matching as soon as it encountered "y ". The *? quantifier effectively tells the regular expression engine to find a match as quickly as possible and pass control on to whatever is next in line, like you would if you were playing hot potato.

How do I process each word on each line?

Use the split function:

    while (<>) {
        foreach $word ( split ) {
            # do something with $word here
        }
    }

Note that this isn't really a word in the English sense; it's just chunks of consecutive non-whitespace characters.

To work with only alphanumeric sequences (including underscores), you might consider

    while (<>) {
        foreach $word (m/(\w+)/g) {
            # do something with $word here
        }
    }

How can I print out a word-frequency or line-frequency summary?

To do this, you have to parse out each word in the input stream. We'll pretend that by word you mean chunk of alphabetics, hyphens, or apostrophes, rather than the non-whitespace chunk idea of a word given in the previous question:

    while (<>) {
        while ( /(\b[^\W_\d][\w'-]+\b)/g ) {   # misses "`sheep'"
            $seen{$1}++;
        }
    }
    while ( ($word, $count) = each %seen ) {
        print "$count $word\n";
    }

If you wanted to do the same thing for lines, you wouldn't need a regular expression:

    while (<>) {
        $seen{$_}++;
    }
    while ( ($line, $count) = each %seen ) {
        print "$count $line";
    }

If you want these output in a sorted order, see the perlfaq4 manpage: "How do I sort a hash (optionally by value instead of key)?".

How can I do approximate matching?

See the module String::Approx available from CPAN.

How do I efficiently match many regular expressions at once?

( contributed by brian d foy )

Avoid asking Perl to compile a regular expression every time you want to match it. In this example, perl must recompile the regular expression for every iteration of the foreach() loop since it has no way to know what $pattern will be.

    @patterns = qw( foo bar baz );

    LINE: while( <> )
        {
                foreach $pattern ( @patterns )
                        {
                print if /\b$pattern\b/i;
                next LINE;
                        }
                }

The qr// operator showed up in perl 5.005. It compiles a regular expression, but doesn't apply it. When you use the pre-compiled version of the regex, perl does less work. In this example, I inserted a map() to turn each pattern into its pre-compiled form. The rest of the script is the same, but faster.

    @patterns = map { qr/\b$_\b/i } qw( foo bar baz );

    LINE: while( <> )
        {
                foreach $pattern ( @patterns )
                        {
                print if /\b$pattern\b/i;
                next LINE;
                        }
                }

In some cases, you may be able to make several patterns into a single regular expression. Beware of situations that require backtracking though.

        $regex = join '|', qw( foo bar baz );

    LINE: while( <> )
        {
                print if /\b(?:$regex)\b/i;
                }

For more details on regular expression efficiency, see Mastering Regular Expressions by Jeffrey Freidl. He explains how regular expressions engine work and why some patterns are surprisingly inefficient. Once you understand how perl applies regular expressions, you can tune them for individual situations.

Why don't word-boundary searches with \b work for me?

(contributed by brian d foy)

Ensure that you know what \b really does: it's the boundary between a word character, \w, and something that isn't a word character. That thing that isn't a word character might be \W, but it can also be the start or end of the string.

It's not (not!) the boundary between whitespace and non-whitespace, and it's not the stuff between words we use to create sentences.

In regex speak, a word boundary (\b) is a "zero width assertion", meaning that it doesn't represent a character in the string, but a condition at a certain position.

For the regular expression, /\bPerl\b/, there has to be a word boundary before the "P" and after the "l". As long as something other than a word character precedes the "P" and succeeds the "l", the pattern will match. These strings match /\bPerl\b/.

        "Perl"    # no word char before P or after l
        "Perl "   # same as previous (space is not a word char)
        "'Perl'"  # the ' char is not a word char
        "Perl's"  # no word char before P, non-word char after "l"

These strings do not match /\bPerl\b/.

        "Perl_"   # _ is a word char!
        "Perler"  # no word char before P, but one after l

You don't have to use \b to match words though. You can look for non-word characters surrounded by word characters. These strings match the pattern /\b'\b/.

        "don't"   # the ' char is surrounded by "n" and "t"
        "qep'a'"  # the ' char is surrounded by "p" and "a"

These strings do not match /\b'\b/.

        "foo'"    # there is no word char after non-word '

You can also use the complement of \b, \B, to specify that there should not be a word boundary.

In the pattern /\Bam\B/, there must be a word character before the "a" and after the "m". These patterns match /\Bam\B/:

        "llama"   # "am" surrounded by word chars
        "Samuel"  # same

These strings do not match /\Bam\B/

        "Sam"      # no word boundary before "a", but one after "m"
        "I am Sam" # "am" surrounded by non-word chars

Why does using $&, $`, or $' slow my program down?

(contributed by Anno Siegel)

Once Perl sees that you need one of these variables anywhere in the program, it provides them on each and every pattern match. That means that on every pattern match the entire string will be copied, part of it to $`, part to $&, and part to $'. Thus the penalty is most severe with long strings and patterns that match often. Avoid $&, $', and $` if you can, but if you can't, once you've used them at all, use them at will because you've already paid the price. Remember that some algorithms really appreciate them. As of the 5.005 release, the $& variable is no longer "expensive" the way the other two are.

Since Perl 5.6.1 the special variables @- and @+ can functionally replace $`, $& and $'. These arrays contain pointers to the beginning and end of each match (see perlvar for the full story), so they give you essentially the same information, but without the risk of excessive string copying.

What good is \G in a regular expression?

You use the \G anchor to start the next match on the same string where the last match left off. The regular expression engine cannot skip over any characters to find the next match with this anchor, so \G is similar to the beginning of string anchor, ^. The \G anchor is typically used with the g flag. It uses the value of pos() as the position to start the next match. As the match operator makes successive matches, it updates pos() with the position of the next character past the last match (or the first character of the next match, depending on how you like to look at it). Each string has its own pos() value.

Suppose you want to match all of consective pairs of digits in a string like "1122a44" and stop matching when you encounter non-digits. You want to match 11 and 22 but the letter <a> shows up between 22 and 44 and you want to stop at a. Simply matching pairs of digits skips over the a and still matches 44.

        $_ = "1122a44";
        my @pairs = m/(\d\d)/g;   # qw( 11 22 44 )

If you use the \G anchor, you force the match after 22 to start with the a. The regular expression cannot match there since it does not find a digit, so the next match fails and the match operator returns the pairs it already found.

        $_ = "1122a44";
        my @pairs = m/\G(\d\d)/g; # qw( 11 22 )

You can also use the \G anchor in scalar context. You still need the g flag.

        $_ = "1122a44";
        while( m/\G(\d\d)/g )
                {
                print "Found $1\n";
                }

After the match fails at the letter a, perl resets pos() and the next match on the same string starts at the beginning.

        $_ = "1122a44";
        while( m/\G(\d\d)/g )
                {
                print "Found $1\n";
                }

        print "Found $1 after while" if m/(\d\d)/g; # finds "11"

You can disable pos() resets on fail with the c flag. Subsequent matches start where the last successful match ended (the value of pos()) even if a match on the same string as failed in the meantime. In this case, the match after the while() loop starts at the a (where the last match stopped), and since it does not use any anchor it can skip over the a to find "44".

        $_ = "1122a44";
        while( m/\G(\d\d)/gc )
                {
                print "Found $1\n";
                }

        print "Found $1 after while" if m/(\d\d)/g; # finds "44"

Typically you use the \G anchor with the c flag when you want to try a different match if one fails, such as in a tokenizer. Jeffrey Friedl offers this example which works in 5.004 or later.

    while (<>) {
      chomp;
      PARSER: {
           m/ \G( \d+\b    )/gcx   && do { print "number: $1\n";  redo; };
           m/ \G( \w+      )/gcx   && do { print "word:   $1\n";  redo; };
           m/ \G( \s+      )/gcx   && do { print "space:  $1\n";  redo; };
           m/ \G( [^\w\d]+ )/gcx   && do { print "other:  $1\n";  redo; };
      }
    }

For each line, the PARSER loop first tries to match a series of digits followed by a word boundary. This match has to start at the place the last match left off (or the beginning of the string on the first match). Since m/ \G( \d+\b )/gcx uses the c flag, if the string does not match that regular expression, perl does not reset pos() and the next match starts at the same position to try a different pattern.

Are Perl regexes DFAs or NFAs? Are they POSIX compliant?

While it's true that Perl's regular expressions resemble the DFAs (deterministic finite automata) of the egrep(1) program, they are in fact implemented as NFAs (non-deterministic finite automata) to allow backtracking and backreferencing. And they aren't POSIX-style either, because those guarantee worst-case behavior for all cases. (It seems that some people prefer guarantees of consistency, even when what's guaranteed is slowness.) See the book "Mastering Regular Expressions" (from O'Reilly) by Jeffrey Friedl for all the details you could ever hope to know on these matters (a full citation appears in the perlfaq2 manpage).

What's wrong with using grep in a void context?

The problem is that grep builds a return list, regardless of the context. This means you're making Perl go to the trouble of building a list that you then just throw away. If the list is large, you waste both time and space. If your intent is to iterate over the list, then use a for loop for this purpose.

In perls older than 5.8.1, map suffers from this problem as well. But since 5.8.1, this has been fixed, and map is context aware - in void context, no lists are constructed.

How can I match strings with multibyte characters?

Starting from Perl 5.6 Perl has had some level of multibyte character support. Perl 5.8 or later is recommended. Supported multibyte character repertoires include Unicode, and legacy encodings through the Encode module. See the perluniintro manpage, the perlunicode manpage, and the Encode manpage.

If you are stuck with older Perls, you can do Unicode with the Unicode::String module, and character conversions using the Unicode::Map8 and Unicode::Map modules. If you are using Japanese encodings, you might try using the jperl 5.005_03.

Finally, the following set of approaches was offered by Jeffrey Friedl, whose article in issue #5 of The Perl Journal talks about this very matter.

Let's suppose you have some weird Martian encoding where pairs of ASCII uppercase letters encode single Martian letters (i.e. the two bytes "CV" make a single Martian letter, as do the two bytes "SG", "VS", "XX", etc.). Other bytes represent single characters, just like ASCII.

So, the string of Martian "I am CVSGXX!" uses 12 bytes to encode the nine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.

Now, say you want to search for the single character /GX/. Perl doesn't know about Martian, so it'll find the two bytes "GX" in the "I am CVSGXX!" string, even though that character isn't there: it just looks like it is because "SG" is next to "XX", but there's no real "GX". This is a big problem.

Here are a few ways, all painful, to deal with it:

   $martian =~ s/([A-Z][A-Z])/ $1 /g; # Make sure adjacent "martian"
                                      # bytes are no longer adjacent.
   print "found GX!\n" if $martian =~ /GX/;

Or like this:

   @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
   # above is conceptually similar to:     @chars = $text =~ m/(.)/g;
   #
   foreach $char (@chars) {
       print "found GX!\n", last if $char eq 'GX';
   }

Or like this:

   while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) {  # \G probably unneeded
       print "found GX!\n", last if $1 eq 'GX';
   }

Here's another, slightly less painful, way to do it from Benjamin Goldberg, who uses a zero-width negative look-behind assertion.

        print "found GX!\n" if  $martian =~ m/
                   (?<![A-Z])
                   (?:[A-Z][A-Z])*?
                   GX
                /x;

This succeeds if the "martian" character GX is in the string, and fails otherwise. If you don't like using (?<!), a zero-width negative look-behind assertion, you can replace (?<![A-Z]) with (?:^|[^A-Z]).

It does have the drawback of putting the wrong thing in $-[0] and $+[0], but this usually can be worked around.

How do I match a pattern that is supplied by the user?

Well, if it's really a pattern, then just use

    chomp($pattern = <STDIN>);
    if ($line =~ /$pattern/) { }

Alternatively, since you have no guarantee that your user entered a valid regular expression, trap the exception this way:

    if (eval { $line =~ /$pattern/ }) { }

If all you really want is to search for a string, not a pattern, then you should either use the index() function, which is made for string searching, or, if you can't be disabused of using a pattern match on a non-pattern, then be sure to use \Q...\E, documented in the perlre manpage.

    $pattern = <STDIN>;

    open (FILE, $input) or die "Couldn't open input $input: $!; aborting";
    while (<FILE>) {
        print if /\Q$pattern\E/;
    }
    close FILE;

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perlfaq7 - General Perl Language Issues

    • Can I get a BNF/yacc/RE for the Perl language?
    • What are all these $@%&* punctuation signs, and how do I know when to use them?
    • Do I always/never have to quote my strings or use semicolons and commas?
    • How do I skip some return values?
    • How do I temporarily block warnings?
    • What's an extension?
    • Why do Perl operators have different precedence than C operators?
    • How do I declare/create a structure?
    • How do I create a module?
    • How do I create a class?
    • How can I tell if a variable is tainted?
    • What's a closure?
    • What is variable suicide and how can I prevent it?
    • How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?
    • How do I create a static variable?
    • What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
    • How can I access a dynamic variable while a similarly named lexical is in scope?
    • What's the difference between deep and shallow binding?
    • Why doesn't "my($foo) = <FILE>;" work right?
    • How do I redefine a builtin function, operator, or method?
    • What's the difference between calling a function as &foo and foo()?
    • How do I create a switch or case statement?
    • How can I catch accesses to undefined variables, functions, or methods?
    • Why can't a method included in this same file be found?
    • How can I find out my current package?
    • How can I comment out a large block of perl code?
    • How do I clear a package?
    • How can I use a variable as a variable name?
    • What does "bad interpreter" mean?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq7 - General Perl Language Issues ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section deals with general Perl language issues that don't clearly fit into any of the other sections.

Can I get a BNF/yacc/RE for the Perl language?

There is no BNF, but you can paw your way through the yacc grammar in perly.y in the source distribution if you're particularly brave. The grammar relies on very smart tokenizing code, so be prepared to venture into toke.c as well.

In the words of Chaim Frenkel: "Perl's grammar can not be reduced to BNF. The work of parsing perl is distributed between yacc, the lexer, smoke and mirrors."

What are all these $@%&* punctuation signs, and how do I know when to use them?

They are type specifiers, as detailed in the perldata manpage:

    $ for scalar values (number, string or reference)
    @ for arrays
    % for hashes (associative arrays)
    & for subroutines (aka functions, procedures, methods)
    * for all types of that symbol name.  In version 4 you used them like
      pointers, but in modern perls you can just use references.

There are couple of other symbols that you're likely to encounter that aren't really type specifiers:

    <> are used for inputting a record from a filehandle.
    \  takes a reference to something.

Note that <FILE> is neither the type specifier for files nor the name of the handle. It is the <> operator applied to the handle FILE. It reads one line (well, record--see $/ in the perlvar manpage) from the handle FILE in scalar context, or all lines in list context. When performing open, close, or any other operation besides <> on files, or even when talking about the handle, do not use the brackets. These are correct: eof(FH), seek(FH, 0, 2) and "copying from STDIN to FILE".

Do I always/never have to quote my strings or use semicolons and commas?

Normally, a bareword doesn't need to be quoted, but in most cases probably should be (and must be under use strict). But a hash key consisting of a simple word (that isn't the name of a defined subroutine) and the left-hand operand to the => operator both count as though they were quoted:

    This                    is like this
    ------------            ---------------
    $foo{line}              $foo{'line'}
    bar => stuff            'bar' => stuff

The final semicolon in a block is optional, as is the final comma in a list. Good style (see the perlstyle manpage) says to put them in except for one-liners:

    if ($whoops) { exit 1 }
    @nums = (1, 2, 3);

    if ($whoops) {
        exit 1;
    }
    @lines = (
        "There Beren came from mountains cold",
        "And lost he wandered under leaves",
    );

How do I skip some return values?

One way is to treat the return values as a list and index into it:

        $dir = (getpwnam($user))[7];

Another way is to use undef as an element on the left-hand-side:

    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);

You can also use a list slice to select only the elements that you need:

        ($dev, $ino, $uid, $gid) = ( stat($file) )[0,1,4,5];

How do I temporarily block warnings?

If you are running Perl 5.6.0 or better, the use warnings pragma allows fine control of what warning are produced. See the perllexwarn manpage for more details.

    {
        no warnings;          # temporarily turn off warnings
        $a = $b + $c;         # I know these might be undef
    }

Additionally, you can enable and disable categories of warnings. You turn off the categories you want to ignore and you can still get other categories of warnings. See the perllexwarn manpage for the complete details, including the category names and hierarchy.

        {
        no warnings 'uninitialized';
        $a = $b + $c;
        }

If you have an older version of Perl, the $^W variable (documented in the perlvar manpage) controls runtime warnings for a block:

    {
        local $^W = 0;        # temporarily turn off warnings
        $a = $b + $c;         # I know these might be undef
    }

Note that like all the punctuation variables, you cannot currently use my() on $^W, only local().

What's an extension?

An extension is a way of calling compiled C code from Perl. Reading the perlxstut manpage is a good place to learn more about extensions.

Why do Perl operators have different precedence than C operators?

Actually, they don't. All C operators that Perl copies have the same precedence in Perl as they do in C. The problem is with operators that C doesn't have, especially functions that give a list context to everything on their right, eg. print, chmod, exec, and so on. Such functions are called "list operators" and appear as such in the precedence table in the perlop manpage.

A common mistake is to write:

    unlink $file || die "snafu";

This gets interpreted as:

    unlink ($file || die "snafu");

To avoid this problem, either put in extra parentheses or use the super low precedence or operator:

    (unlink $file) || die "snafu";
    unlink $file or die "snafu";

The "English" operators (and, or, xor, and not) deliberately have precedence lower than that of list operators for just such situations as the one above.

Another operator with surprising precedence is exponentiation. It binds more tightly even than unary minus, making -2**2 product a negative not a positive four. It is also right-associating, meaning that 2**3**2 is two raised to the ninth power, not eight squared.

Although it has the same precedence as in C, Perl's ?: operator produces an lvalue. This assigns $x to either $a or $b, depending on the trueness of $maybe:

    ($maybe ? $a : $b) = $x;

How do I declare/create a structure?

In general, you don't "declare" a structure. Just use a (probably anonymous) hash reference. See the perlref manpage and the perldsc manpage for details. Here's an example:

    $person = {};                   # new anonymous hash
    $person->{AGE}  = 24;           # set field AGE to 24
    $person->{NAME} = "Nat";        # set field NAME to "Nat"

If you're looking for something a bit more rigorous, try the perltoot manpage.

How do I create a module?

(contributed by brian d foy)

the perlmod manpage, the perlmodlib manpage, the perlmodstyle manpage explain modules in all the gory details. the perlnewmod manpage gives a brief overview of the process along with a couple of suggestions about style.

If you need to include C code or C library interfaces in your module, you'll need h2xs. h2xs will create the module distribution structure and the initial interface files you'll need. the perlxs manpage and the perlxstut manpage explain the details.

If you don't need to use C code, other tools such as ExtUtils::ModuleMaker and Module::Starter, can help you create a skeleton module distribution.

You may also want to see Sam Tregar's "Writing Perl Modules for CPAN" ( http://apress.com/book/bookDisplay.html?bID=14 ) which is the best hands-on guide to creating module distributions.

How do I create a class?

See the perltoot manpage for an introduction to classes and objects, as well as the perlobj manpage and the perlbot manpage.

How can I tell if a variable is tainted?

You can use the tainted() function of the Scalar::Util module, available from CPAN (or included with Perl since release 5.8.0). See also Laundering and Detecting Tainted Data in the perlsec manpage.

What's a closure?

Closures are documented in the perlref manpage.

Closure is a computer science term with a precise but hard-to-explain meaning. Closures are implemented in Perl as anonymous subroutines with lasting references to lexical variables outside their own scopes. These lexicals magically refer to the variables that were around when the subroutine was defined (deep binding).

Closures make sense in any programming language where you can have the return value of a function be itself a function, as you can in Perl. Note that some languages provide anonymous functions but are not capable of providing proper closures: the Python language, for example. For more information on closures, check out any textbook on functional programming. Scheme is a language that not only supports but encourages closures.

Here's a classic function-generating function:

    sub add_function_generator {
      return sub { shift() + shift() };
    }

    $add_sub = add_function_generator();
    $sum = $add_sub->(4,5);                # $sum is 9 now.

The closure works as a function template with some customization slots left out to be filled later. The anonymous subroutine returned by add_function_generator() isn't technically a closure because it refers to no lexicals outside its own scope.

Contrast this with the following make_adder() function, in which the returned anonymous function contains a reference to a lexical variable outside the scope of that function itself. Such a reference requires that Perl return a proper closure, thus locking in for all time the value that the lexical had when the function was created.

    sub make_adder {
        my $addpiece = shift;
        return sub { shift() + $addpiece };
    }

    $f1 = make_adder(20);
    $f2 = make_adder(555);

Now &$f1($n) is always 20 plus whatever $n you pass in, whereas &$f2($n) is always 555 plus whatever $n you pass in. The $addpiece in the closure sticks around.

Closures are often used for less esoteric purposes. For example, when you want to pass in a bit of code into a function:

    my $line;
    timeout( 30, sub { $line = <STDIN> } );

If the code to execute had been passed in as a string, '$line = <STDIN>', there would have been no way for the hypothetical timeout() function to access the lexical variable $line back in its caller's scope.

What is variable suicide and how can I prevent it?

This problem was fixed in perl 5.004_05, so preventing it means upgrading your version of perl. ;)

Variable suicide is when you (temporarily or permanently) lose the value of a variable. It is caused by scoping through my() and local() interacting with either closures or aliased foreach() iterator variables and subroutine arguments. It used to be easy to inadvertently lose a variable's value this way, but now it's much harder. Take this code:

    my $f = 'foo';
    sub T {
      while ($i++ < 3) { my $f = $f; $f .= $i; print $f, "\n" }
    }
    T;
    print "Finally $f\n";

If you are experiencing variable suicide, that my $f in the subroutine doesn't pick up a fresh copy of the $f whose value is <foo>. The output shows that inside the subroutine the value of $f leaks through when it shouldn't, as in this output:

        foobar
        foobarbar
        foobarbarbar
        Finally foo

The $f that has "bar" added to it three times should be a new $f my $f should create a new lexical variable each time through the loop. The expected output is:

        foobar
        foobar
        foobar
        Finally foo

How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?

With the exception of regexes, you need to pass references to these objects. See Pass by Reference in the perlsub manpage for this particular question, and the perlref manpage for information on references.

See "Passing Regexes", below, for information on passing regular expressions.

Passing Variables and Functions

Regular variables and functions are quite easy to pass: just pass in a reference to an existing or anonymous variable or function:

    func( \$some_scalar );

    func( \@some_array  );
    func( [ 1 .. 10 ]   );

    func( \%some_hash   );
    func( { this => 10, that => 20 }   );

    func( \&some_func   );
    func( sub { $_[0] ** $_[1] }   );
Passing Filehandles

As of Perl 5.6, you can represent filehandles with scalar variables which you treat as any other scalar.

        open my $fh, $filename or die "Cannot open $filename! $!";
        func( $fh );

        sub func {
                my $passed_fh = shift;

                my $line = <$fh>;
                }

Before Perl 5.6, you had to use the *FH or \*FH notations. These are "typeglobs"--see Typeglobs and Filehandles in the perldata manpage and especially Pass by Reference in the perlsub manpage for more information.

Passing Regexes

To pass regexes around, you'll need to be using a release of Perl sufficiently recent as to support the qr// construct, pass around strings and use an exception-trapping eval, or else be very, very clever.

Here's an example of how to pass in a string to be regex compared using qr//:

    sub compare($$) {
        my ($val1, $regex) = @_;
        my $retval = $val1 =~ /$regex/;
        return $retval;
    }
    $match = compare("old McDonald", qr/d.*D/i);

Notice how qr// allows flags at the end. That pattern was compiled at compile time, although it was executed later. The nifty qr// notation wasn't introduced until the 5.005 release. Before that, you had to approach this problem much less intuitively. For example, here it is again if you don't have qr//:

    sub compare($$) {
        my ($val1, $regex) = @_;
        my $retval = eval { $val1 =~ /$regex/ };
        die if $@;
        return $retval;
    }

    $match = compare("old McDonald", q/($?i)d.*D/);

Make sure you never say something like this:

    return eval "\$val =~ /$regex/";   # WRONG

or someone can sneak shell escapes into the regex due to the double interpolation of the eval and the double-quoted string. For example:

    $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';

    eval "\$string =~ /$pattern_of_evil/";

Those preferring to be very, very clever might see the O'Reilly book, Mastering Regular Expressions, by Jeffrey Friedl. Page 273's Build_MatchMany_Function() is particularly interesting. A complete citation of this book is given in the perlfaq2 manpage.

Passing Methods

To pass an object method into a subroutine, you can do this:

    call_a_lot(10, $some_obj, "methname")
    sub call_a_lot {
        my ($count, $widget, $trick) = @_;
        for (my $i = 0; $i < $count; $i++) {
            $widget->$trick();
        }
    }

Or, you can use a closure to bundle up the object, its method call, and arguments:

    my $whatnot =  sub { $some_obj->obfuscate(@args) };
    func($whatnot);
    sub func {
        my $code = shift;
        &$code();
    }

You could also investigate the can() method in the UNIVERSAL class (part of the standard perl distribution).

How do I create a static variable?

(contributed by brian d foy)

Perl doesn't have "static" variables, which can only be accessed from the function in which they are declared. You can get the same effect with lexical variables, though.

You can fake a static variable by using a lexical variable which goes out of scope. In this example, you define the subroutine counter, and it uses the lexical variable $count. Since you wrap this in a BEGIN block, $count is defined at compile-time, but also goes out of scope at the end of the BEGIN block. The BEGIN block also ensures that the subroutine and the value it uses is defined at compile-time so the subroutine is ready to use just like any other subroutine, and you can put this code in the same place as other subroutines in the program text (i.e. at the end of the code, typically). The subroutine counter still has a reference to the data, and is the only way you can access the value (and each time you do, you increment the value). The data in chunk of memory defined by $count is private to counter.

    BEGIN {
        my $count = 1;
        sub counter { $count++ }
    }

    my $start = count();

    .... # code that calls count();

    my $end = count();

In the previous example, you created a function-private variable because only one function remembered its reference. You could define multiple functions while the variable is in scope, and each function can share the "private" variable. It's not really "static" because you can access it outside the function while the lexical variable is in scope, and even create references to it. In this example, increment_count and return_count share the variable. One function adds to the value and the other simply returns the value. They can both access $count, and since it has gone out of scope, there is no other way to access it.

    BEGIN {
        my $count = 1;
        sub increment_count { $count++ }
        sub return_count    { $count }
    }

To declare a file-private variable, you still use a lexical variable. A file is also a scope, so a lexical variable defined in the file cannot be seen from any other file.

See Persistent Private Variables in the perlsub manpage for more information. The discussion of closures in the perlref manpage may help you even though we did not use anonymous subroutines in this answer. See Persistent Private Variables in the perlsub manpage for details.

What's the difference between dynamic and lexical (static) scoping? Between local() and my()?

local($x) saves away the old value of the global variable $x and assigns a new value for the duration of the subroutine which is visible in other functions called from that subroutine. This is done at run-time, so is called dynamic scoping. local() always affects global variables, also called package variables or dynamic variables.

my($x) creates a new variable that is only visible in the current subroutine. This is done at compile-time, so it is called lexical or static scoping. my() always affects private variables, also called lexical variables or (improperly) static(ly scoped) variables.

For instance:

    sub visible {
        print "var has value $var\n";
    }

    sub dynamic {
        local $var = 'local';   # new temporary value for the still-global
        visible();              #   variable called $var
    }

    sub lexical {
        my $var = 'private';    # new private variable, $var
        visible();              # (invisible outside of sub scope)
    }

    $var = 'global';

    visible();                  # prints global
    dynamic();                  # prints local
    lexical();                  # prints global

Notice how at no point does the value "private" get printed. That's because $var only has that value within the block of the lexical() function, and it is hidden from called subroutine.

In summary, local() doesn't make what you think of as private, local variables. It gives a global variable a temporary value. my() is what you're looking for if you want private variables.

See Private Variables via my() in the perlsub manpage and Temporary Values via local() in the perlsub manpage for excruciating details.

How can I access a dynamic variable while a similarly named lexical is in scope?

If you know your package, you can just mention it explicitly, as in $Some_Pack::var. Note that the notation $::var is not the dynamic $var in the current package, but rather the one in the "main" package, as though you had written $main::var.

        use vars '$var';
        local $var = "global";
        my    $var = "lexical";

        print "lexical is $var\n";
        print "global  is $main::var\n";

Alternatively you can use the compiler directive our() to bring a dynamic variable into the current lexical scope.

        require 5.006; # our() did not exist before 5.6
        use vars '$var';

        local $var = "global";
        my $var    = "lexical";

        print "lexical is $var\n";

        {
          our $var;
          print "global  is $var\n";
        }

What's the difference between deep and shallow binding?

In deep binding, lexical variables mentioned in anonymous subroutines are the same ones that were in scope when the subroutine was created. In shallow binding, they are whichever variables with the same names happen to be in scope when the subroutine is called. Perl always uses deep binding of lexical variables (i.e., those created with my()). However, dynamic variables (aka global, local, or package variables) are effectively shallowly bound. Consider this just one more reason not to use them. See the answer to What's a closure?.

Why doesn't "my($foo) = <FILE>;" work right?

my() and local() give list context to the right hand side of =. The <FH> read operation, like so many of Perl's functions and operators, can tell which context it was called in and behaves appropriately. In general, the scalar() function can help. This function does nothing to the data itself (contrary to popular myth) but rather tells its argument to behave in whatever its scalar fashion is. If that function doesn't have a defined scalar behavior, this of course doesn't help you (such as with sort()).

To enforce scalar context in this particular case, however, you need merely omit the parentheses:

    local($foo) = <FILE>;           # WRONG
    local($foo) = scalar(<FILE>);   # ok
    local $foo  = <FILE>;           # right

You should probably be using lexical variables anyway, although the issue is the same here:

    my($foo) = <FILE>;  # WRONG
    my $foo  = <FILE>;  # right

How do I redefine a builtin function, operator, or method?

Why do you want to do that? :-)

If you want to override a predefined function, such as open(), then you'll have to import the new definition from a different module. See Overriding Built-in Functions in the perlsub manpage. There's also an example in Class::Template in the perltoot manpage.

If you want to overload a Perl operator, such as + or **, then you'll want to use the use overload pragma, documented in the overload manpage.

If you're talking about obscuring method calls in parent classes, see Overridden Methods in the perltoot manpage.

What's the difference between calling a function as &foo and foo()?

When you call a function as &foo, you allow that function access to your current @_ values, and you bypass prototypes. The function doesn't get an empty @_--it gets yours! While not strictly speaking a bug (it's documented that way in the perlsub manpage), it would be hard to consider this a feature in most cases.

When you call your function as &foo(), then you do get a new @_, but prototyping is still circumvented.

Normally, you want to call a function using foo(). You may only omit the parentheses if the function is already known to the compiler because it already saw the definition (use but not require), or via a forward reference or use subs declaration. Even in this case, you get a clean @_ without any of the old values leaking through where they don't belong.

How do I create a switch or case statement?

This is explained in more depth in the the perlsyn manpage. Briefly, there's no official case statement, because of the variety of tests possible in Perl (numeric comparison, string comparison, glob comparison, regex matching, overloaded comparisons, ...). Larry couldn't decide how best to do this, so he left it out, even though it's been on the wish list since perl1.

Starting from Perl 5.8 to get switch and case one can use the Switch extension and say:

        use Switch;

after which one has switch and case. It is not as fast as it could be because it's not really part of the language (it's done using source filters) but it is available, and it's very flexible.

But if one wants to use pure Perl, the general answer is to write a construct like this:

    for ($variable_to_test) {
        if    (/pat1/)  { }     # do something
        elsif (/pat2/)  { }     # do something else
        elsif (/pat3/)  { }     # do something else
        else            { }     # default
    }

Here's a simple example of a switch based on pattern matching, this time lined up in a way to make it look more like a switch statement. We'll do a multiway conditional based on the type of reference stored in $whatchamacallit:

    SWITCH: for (ref $whatchamacallit) {

        /^$/            && die "not a reference";

        /SCALAR/        && do {
                                print_scalar($$ref);
                                last SWITCH;
                        };

        /ARRAY/         && do {
                                print_array(@$ref);
                                last SWITCH;
                        };

        /HASH/          && do {
                                print_hash(%$ref);
                                last SWITCH;
                        };

        /CODE/          && do {
                                warn "can't print function ref";
                                last SWITCH;
                        };

        # DEFAULT

        warn "User defined type skipped";

    }

See perlsyn/"Basic BLOCKs and Switch Statements" for many other examples in this style.

Sometimes you should change the positions of the constant and the variable. For example, let's say you wanted to test which of many answers you were given, but in a case-insensitive way that also allows abbreviations. You can use the following technique if the strings all start with different characters or if you want to arrange the matches so that one takes precedence over another, as "SEND" has precedence over "STOP" here:

    chomp($answer = <>);
    if    ("SEND"  =~ /^\Q$answer/i) { print "Action is send\n"  }
    elsif ("STOP"  =~ /^\Q$answer/i) { print "Action is stop\n"  }
    elsif ("ABORT" =~ /^\Q$answer/i) { print "Action is abort\n" }
    elsif ("LIST"  =~ /^\Q$answer/i) { print "Action is list\n"  }
    elsif ("EDIT"  =~ /^\Q$answer/i) { print "Action is edit\n"  }

A totally different approach is to create a hash of function references.

    my %commands = (
        "happy" => \&joy,
        "sad",  => \&sullen,
        "done"  => sub { die "See ya!" },
        "mad"   => \&angry,
    );

    print "How are you? ";
    chomp($string = <STDIN>);
    if ($commands{$string}) {
        $commands{$string}->();
    } else {
        print "No such command: $string\n";
    }

How can I catch accesses to undefined variables, functions, or methods?

The AUTOLOAD method, discussed in Autoloading in the perlsub manpage and AUTOLOAD: Proxy Methods in the perltoot manpage, lets you capture calls to undefined functions and methods.

When it comes to undefined variables that would trigger a warning under use warnings, you can promote the warning to an error.

        use warnings FATAL => qw(uninitialized);

Why can't a method included in this same file be found?

Some possible reasons: your inheritance is getting confused, you've misspelled the method name, or the object is of the wrong type. Check out the perltoot manpage for details about any of the above cases. You may also use print ref($object) to find out the class $object was blessed into.

Another possible reason for problems is because you've used the indirect object syntax (eg, find Guru "Samy") on a class name before Perl has seen that such a package exists. It's wisest to make sure your packages are all defined before you start using them, which will be taken care of if you use the use statement instead of require. If not, make sure to use arrow notation (eg., Guru->find("Samy")) instead. Object notation is explained in the perlobj manpage.

Make sure to read about creating modules in the perlmod manpage and the perils of indirect objects in Method Invocation in the perlobj manpage.

How can I find out my current package?

If you're just a random program, you can do this to find out what the currently compiled package is:

    my $packname = __PACKAGE__;

But, if you're a method and you want to print an error message that includes the kind of object you were called on (which is not necessarily the same as the one in which you were compiled):

    sub amethod {
        my $self  = shift;
        my $class = ref($self) || $self;
        warn "called me from a $class object";
    }

How can I comment out a large block of perl code?

You can use embedded POD to discard it. Enclose the blocks you want to comment out in POD markers. The <=begin> directive marks a section for a specific formatter. Use the comment format, which no formatter should claim to understand (by policy). Mark the end of the block with <=end>.

    # program is here

    =begin comment
    all of this stuff
    here will be ignored
    by everyone
        =end comment
    =cut
    # program continues

The pod directives cannot go just anywhere. You must put a pod directive where the parser is expecting a new statement, not just in the middle of an expression or some other arbitrary grammar production.

See the perlpod manpage for more details.

How do I clear a package?

Use this code, provided by Mark-Jason Dominus:

    sub scrub_package {
        no strict 'refs';
        my $pack = shift;
        die "Shouldn't delete main package"
            if $pack eq "" || $pack eq "main";
        my $stash = *{$pack . '::'}{HASH};
        my $name;
        foreach $name (keys %$stash) {
            my $fullname = $pack . '::' . $name;
            # Get rid of everything with that name.
            undef $$fullname;
            undef @$fullname;
            undef %$fullname;
            undef &$fullname;
            undef *$fullname;
        }
    }

Or, if you're using a recent release of Perl, you can just use the Symbol::delete_package() function instead.

How can I use a variable as a variable name?

Beginners often think they want to have a variable contain the name of a variable.

    $fred    = 23;
    $varname = "fred";
    ++$$varname;         # $fred now 24

This works sometimes, but it is a very bad idea for two reasons.

The first reason is that this technique only works on global variables. That means that if $fred is a lexical variable created with my() in the above example, the code wouldn't work at all: you'd accidentally access the global and skip right over the private lexical altogether. Global variables are bad because they can easily collide accidentally and in general make for non-scalable and confusing code.

Symbolic references are forbidden under the use strict pragma. They are not true references and consequently are not reference counted or garbage collected.

The other reason why using a variable to hold the name of another variable is a bad idea is that the question often stems from a lack of understanding of Perl data structures, particularly hashes. By using symbolic references, you are just using the package's symbol-table hash (like %main::) instead of a user-defined hash. The solution is to use your own hash or a real reference instead.

    $USER_VARS{"fred"} = 23;
    $varname = "fred";
    $USER_VARS{$varname}++;  # not $$varname++

There we're using the %USER_VARS hash instead of symbolic references. Sometimes this comes up in reading strings from the user with variable references and wanting to expand them to the values of your perl program's variables. This is also a bad idea because it conflates the program-addressable namespace and the user-addressable one. Instead of reading a string and expanding it to the actual contents of your program's own variables:

    $str = 'this has a $fred and $barney in it';
    $str =~ s/(\$\w+)/$1/eeg;             # need double eval

it would be better to keep a hash around like %USER_VARS and have variable references actually refer to entries in that hash:

    $str =~ s/\$(\w+)/$USER_VARS{$1}/g;   # no /e here at all

That's faster, cleaner, and safer than the previous approach. Of course, you don't need to use a dollar sign. You could use your own scheme to make it less confusing, like bracketed percent symbols, etc.

    $str = 'this has a %fred% and %barney% in it';
    $str =~ s/%(\w+)%/$USER_VARS{$1}/g;   # no /e here at all

Another reason that folks sometimes think they want a variable to contain the name of a variable is because they don't know how to build proper data structures using hashes. For example, let's say they wanted two hashes in their program: %fred and %barney, and that they wanted to use another scalar variable to refer to those by name.

    $name = "fred";
    $$name{WIFE} = "wilma";     # set %fred

    $name = "barney";
    $$name{WIFE} = "betty";     # set %barney

This is still a symbolic reference, and is still saddled with the problems enumerated above. It would be far better to write:

    $folks{"fred"}{WIFE}   = "wilma";
    $folks{"barney"}{WIFE} = "betty";

And just use a multilevel hash to start with.

The only times that you absolutely must use symbolic references are when you really must refer to the symbol table. This may be because it's something that can't take a real reference to, such as a format name. Doing so may also be important for method calls, since these always go through the symbol table for resolution.

In those cases, you would turn off strict 'refs' temporarily so you can play around with the symbol table. For example:

    @colors = qw(red blue green yellow orange purple violet);
    for my $name (@colors) {
        no strict 'refs';  # renege for the block
        *$name = sub { "<FONT COLOR='$name'>@_</FONT>" };
    }

All those functions (red(), blue(), green(), etc.) appear to be separate, but the real code in the closure actually was compiled only once.

So, sometimes you might want to use symbolic references to directly manipulate the symbol table. This doesn't matter for formats, handles, and subroutines, because they are always global--you can't use my() on them. For scalars, arrays, and hashes, though--and usually for subroutines-- you probably only want to use hard references.

What does "bad interpreter" mean?

(contributed by brian d foy)

The "bad interpreter" message comes from the shell, not perl. The actual message may vary depending on your platform, shell, and locale settings.

If you see "bad interpreter - no such file or directory", the first line in your perl script (the "shebang" line) does not contain the right path to perl (or any other program capable of running scripts). Sometimes this happens when you move the script from one machine to another and each machine has a different path to perl---/usr/bin/perl versus /usr/local/bin/perl for instance. It may also indicate that the source machine has CRLF line terminators and the destination machine has LF only: the shell tries to find /usr/bin/perl<CR>, but can't.

If you see "bad interpreter: Permission denied", you need to make your script executable.

In either case, you should still be able to run the scripts with perl explicitly:

        % perl script.pl

If you get a message like "perl: command not found", perl is not in your PATH, which might also mean that the location of perl is not where you expect it so you need to adjust your shebang line.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perlfaq8 - System Interaction

    • How do I find out which operating system I'm running under?
    • How come exec() doesn't return?
    • How do I do fancy stuff with the keyboard/screen/mouse?
    • How do I print something out in color?
    • How do I read just one key without waiting for a return key?
    • How do I check whether input is ready on the keyboard?
    • How do I clear the screen?
    • How do I get the screen size?
    • How do I ask the user for a password?
    • How do I read and write the serial port?
    • How do I decode encrypted password files?
    • How do I start a process in the background?
    • How do I trap control characters/signals?
    • How do I modify the shadow password file on a Unix system?
    • How do I set the time and date?
    • How can I sleep() or alarm() for under a second?
    • How can I measure time under a second?
    • How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
    • Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
    • How can I call my system's unique C functions from Perl?
    • Where do I get the include files to do ioctl() or syscall()?
    • Why do setuid perl scripts complain about kernel problems?
    • How can I open a pipe both to and from a command?
    • Why can't I get the output of a command with system()?
    • How can I capture STDERR from an external command?
    • Why doesn't open() return an error when a pipe open fails?
    • What's wrong with using backticks in a void context?
    • How can I call backticks without shell processing?
    • Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
    • How can I convert my shell script to perl?
    • Can I use perl to run a telnet or ftp session?
    • How can I write expect in Perl?
    • Is there a way to hide perl's command line from programs such as "ps"?
    • I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?
    • How do I close a process's filehandle without waiting for it to complete?
    • How do I fork a daemon process?
    • How do I find out if I'm running interactively or not?
    • How do I timeout a slow event?
    • How do I set CPU limits?
    • How do I avoid zombies on a Unix system?
    • How do I use an SQL database?
    • How do I make a system() exit on control-C?
    • How do I open a file without blocking?
    • How do I tell the difference between errors from the shell and perl?
    • How do I install a module from CPAN?
    • What's the difference between require and use?
    • How do I keep my own module/library directory?
    • How do I add the directory my program lives in to the module/library search path?
    • How do I add a directory to my include path (@INC) at runtime?
    • What is socket.ph and where do I get it?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq8 - System Interaction ($Revision: 1.27 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section of the Perl FAQ covers questions involving operating system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation.

Read the FAQs and documentation specific to the port of perl to your operating system (eg, the perlvms manpage, the perlplan9 manpage, ...). These should contain more detailed information on the vagaries of your perl.

How do I find out which operating system I'm running under?

The $^O variable ($OSNAME if you use English) contains an indication of the name of the operating system (not its release number) that your perl binary was built for.

How come exec() doesn't return?

Because that's what it does: it replaces your currently running program with a different one. If you want to keep going (as is probably the case if you're asking this question) use system() instead.

How do I do fancy stuff with the keyboard/screen/mouse?

How you access/control keyboards, screens, and pointing devices ("mice") is system-dependent. Try the following modules:

Keyboard
        Term::Cap               Standard perl distribution
        Term::ReadKey           CPAN
        Term::ReadLine::Gnu     CPAN
        Term::ReadLine::Perl    CPAN
        Term::Screen            CPAN
Screen
        Term::Cap               Standard perl distribution
        Curses                  CPAN
        Term::ANSIColor         CPAN
Mouse
        Tk                      CPAN

Some of these specific cases are shown as examples in other answers in this section of the perlfaq.

How do I print something out in color?

In general, you don't, because you don't know whether the recipient has a color-aware display device. If you know that they have an ANSI terminal that understands color, you can use the Term::ANSIColor module from CPAN:

    use Term::ANSIColor;
    print color("red"), "Stop!\n", color("reset");
    print color("green"), "Go!\n", color("reset");

Or like this:

    use Term::ANSIColor qw(:constants);
    print RED, "Stop!\n", RESET;
    print GREEN, "Go!\n", RESET;

How do I read just one key without waiting for a return key?

Controlling input buffering is a remarkably system-dependent matter. On many systems, you can just use the stty command as shown in getc in the perlfunc manpage, but as you see, that's already getting you into portability snags.

    open(TTY, "+</dev/tty") or die "no tty: $!";
    system "stty  cbreak </dev/tty >/dev/tty 2>&1";
    $key = getc(TTY);           # perhaps this works
    # OR ELSE
    sysread(TTY, $key, 1);      # probably this does
    system "stty -cbreak </dev/tty >/dev/tty 2>&1";

The Term::ReadKey module from CPAN offers an easy-to-use interface that should be more efficient than shelling out to stty for each key. It even includes limited support for Windows.

    use Term::ReadKey;
    ReadMode('cbreak');
    $key = ReadKey(0);
    ReadMode('normal');

However, using the code requires that you have a working C compiler and can use it to build and install a CPAN module. Here's a solution using the standard POSIX module, which is already on your systems (assuming your system supports POSIX).

    use HotKey;
    $key = readkey();

And here's the HotKey module, which hides the somewhat mystifying calls to manipulate the POSIX termios structures.

    # HotKey.pm
    package HotKey;

    @ISA = qw(Exporter);
    @EXPORT = qw(cbreak cooked readkey);

    use strict;
    use POSIX qw(:termios_h);
    my ($term, $oterm, $echo, $noecho, $fd_stdin);

    $fd_stdin = fileno(STDIN);
    $term     = POSIX::Termios->new();
    $term->getattr($fd_stdin);
    $oterm     = $term->getlflag();

    $echo     = ECHO | ECHOK | ICANON;
    $noecho   = $oterm & ~$echo;

    sub cbreak {
        $term->setlflag($noecho);  # ok, so i don't want echo either
        $term->setcc(VTIME, 1);
        $term->setattr($fd_stdin, TCSANOW);
    }

    sub cooked {
        $term->setlflag($oterm);
        $term->setcc(VTIME, 0);
        $term->setattr($fd_stdin, TCSANOW);
    }

    sub readkey {
        my $key = '';
        cbreak();
        sysread(STDIN, $key, 1);
        cooked();
        return $key;
    }

    END { cooked() }

    1;

How do I check whether input is ready on the keyboard?

The easiest way to do this is to read a key in nonblocking mode with the Term::ReadKey module from CPAN, passing it an argument of -1 to indicate not to block:

    use Term::ReadKey;

    ReadMode('cbreak');

    if (defined ($char = ReadKey(-1)) ) {
        # input was waiting and it was $char
    } else {
        # no input was waiting
    }

    ReadMode('normal');                  # restore normal tty settings

How do I clear the screen?

If you only have do so infrequently, use system:

    system("clear");

If you have to do this a lot, save the clear string so you can print it 100 times without calling a program 100 times:

    $clear_string = `clear`;
    print $clear_string;

If you're planning on doing other screen manipulations, like cursor positions, etc, you might wish to use Term::Cap module:

    use Term::Cap;
    $terminal = Term::Cap->Tgetent( {OSPEED => 9600} );
    $clear_string = $terminal->Tputs('cl');

How do I get the screen size?

If you have Term::ReadKey module installed from CPAN, you can use it to fetch the width and height in characters and in pixels:

    use Term::ReadKey;
    ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();

This is more portable than the raw ioctl, but not as illustrative:

    require 'sys/ioctl.ph';
    die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
    open(TTY, "+</dev/tty")                     or die "No tty: $!";
    unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) {
        die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
    }
    ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
    print "(row,col) = ($row,$col)";
    print "  (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
    print "\n";

How do I ask the user for a password?

(This question has nothing to do with the web. See a different FAQ for that.)

There's an example of this in crypt in the perlfunc manpage). First, you put the terminal into "no echo" mode, then just read the password normally. You may do this with an old-style ioctl() function, POSIX terminal control (see the POSIX manpage or its documentation the Camel Book), or a call to the stty program, with varying degrees of portability.

You can also do this for most systems using the Term::ReadKey module from CPAN, which is easier to use and in theory more portable.

    use Term::ReadKey;

    ReadMode('noecho');
    $password = ReadLine(0);

How do I read and write the serial port?

This depends on which operating system your program is running on. In the case of Unix, the serial ports will be accessible through files in /dev; on other systems, device names will doubtless differ. Several problem areas common to all device interaction are the following:

lockfiles

Your system may use lockfiles to control multiple access. Make sure you follow the correct protocol. Unpredictable behavior can result from multiple processes reading from one device.

open mode

If you expect to use both read and write operations on the device, you'll have to open it for update (see open in the perlfunc manpage for details). You may wish to open it without running the risk of blocking by using sysopen() and O_RDWR|O_NDELAY|O_NOCTTY from the Fcntl module (part of the standard perl distribution). See sysopen in the perlfunc manpage for more on this approach.

end of line

Some devices will be expecting a "\r" at the end of each line rather than a "\n". In some ports of perl, "\r" and "\n" are different from their usual (Unix) ASCII values of "\012" and "\015". You may have to give the numeric values you want directly, using octal ("\015"), hex ("0x0D"), or as a control-character specification ("\cM").

    print DEV "atv1\012";       # wrong, for some devices
    print DEV "atv1\015";       # right, for some devices

Even though with normal text files a "\n" will do the trick, there is still no unified scheme for terminating a line that is portable between Unix, DOS/Win, and Macintosh, except to terminate ALL line ends with "\015\012", and strip what you don't need from the output. This applies especially to socket I/O and autoflushing, discussed next.

flushing output

If you expect characters to get to your device when you print() them, you'll want to autoflush that filehandle. You can use select() and the $| variable to control autoflushing (see $| in the perlvar manpage and select in the perlfunc manpage, or the perlfaq5 manpage, "How do I flush/unbuffer an output filehandle? Why must I do this?"):

    $oldh = select(DEV);
    $| = 1;
    select($oldh);

You'll also see code that does this without a temporary variable, as in

    select((select(DEV), $| = 1)[0]);

Or if you don't mind pulling in a few thousand lines of code just because you're afraid of a little $| variable:

    use IO::Handle;
    DEV->autoflush(1);

As mentioned in the previous item, this still doesn't work when using socket I/O between Unix and Macintosh. You'll need to hard code your line terminators, in that case.

non-blocking input

If you are doing a blocking read() or sysread(), you'll have to arrange for an alarm handler to provide a timeout (see alarm in the perlfunc manpage). If you have a non-blocking open, you'll likely have a non-blocking read, which means you may have to use a 4-arg select() to determine whether I/O is ready on that device (see select in the perlfunc manpage.

While trying to read from his caller-id box, the notorious Jamie Zawinski <jwz@netscape.com>, after much gnashing of teeth and fighting with sysread, sysopen, POSIX's tcgetattr business, and various other functions that go bump in the night, finally came up with this:

    sub open_modem {
        use IPC::Open2;
        my $stty = `/bin/stty -g`;
        open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1");
        # starting cu hoses /dev/tty's stty settings, even when it has
        # been opened on a pipe...
        system("/bin/stty $stty");
        $_ = <MODEM_IN>;
        chomp;
        if ( !m/^Connected/ ) {
            print STDERR "$0: cu printed `$_' instead of `Connected'\n";
        }
    }

How do I decode encrypted password files?

You spend lots and lots of money on dedicated hardware, but this is bound to get you talked about.

Seriously, you can't if they are Unix password files--the Unix password system employs one-way encryption. It's more like hashing than encryption. The best you can check is whether something else hashes to the same string. You can't turn a hash back into the original string. Programs like Crack can forcibly (and intelligently) try to guess passwords, but don't (can't) guarantee quick success.

If you're worried about users selecting bad passwords, you should proactively check when they try to change their password (by modifying passwd(1), for example).

How do I start a process in the background?

Several modules can start other processes that do not block your Perl program. You can use IPC::Open3, Parallel::Jobs, IPC::Run, and some of the POE modules. See CPAN for more details.

You could also use

    system("cmd &")

or you could use fork as documented in fork in the perlfunc manpage, with further examples in the perlipc manpage. Some things to be aware of, if you're on a Unix-like system:

STDIN, STDOUT, and STDERR are shared

Both the main process and the backgrounded one (the "child" process) share the same STDIN, STDOUT and STDERR filehandles. If both try to access them at once, strange things can happen. You may want to close or reopen these for the child. You can get around this with opening a pipe (see open in the perlfunc manpage) but on some systems this means that the child process cannot outlive the parent.

Signals

You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too. SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is sent when you write to a filehandle whose child process has closed (an untrapped SIGPIPE can cause your program to silently die). This is not an issue with system("cmd&").

Zombies

You have to be prepared to "reap" the child process when it finishes.

    $SIG{CHLD} = sub { wait };

    $SIG{CHLD} = 'IGNORE';

You can also use a double fork. You immediately wait() for your first child, and the init daemon will wait() for your grandchild once it exits.

        unless ($pid = fork) {
                unless (fork) {
            exec "what you really wanna do";
            die "exec failed!";
                }
        exit 0;
        }
            waitpid($pid,0);

See Signals in the perlipc manpage for other examples of code to do this. Zombies are not an issue with system("prog &").

How do I trap control characters/signals?

You don't actually "trap" a control character. Instead, that character generates a signal which is sent to your terminal's currently foregrounded process group, which you then trap in your process. Signals are documented in Signals in the perlipc manpage and the section on "Signals" in the Camel.

You can set the values of the %SIG hash to be the functions you want to handle the signal. After perl catches the signal, it looks in %SIG for a key with the same name as the signal, then calls the subroutine value for that key.

        # as an anonymous subroutine

        $SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) };

        # or a reference to a function

        $SIG{INT} = \&ouch;

        # or the name of the function as a string

        $SIG{INT} = "ouch";

Perl versions before 5.8 had in its C source code signal handlers which would catch the signal and possibly run a Perl function that you had set in %SIG. This violated the rules of signal handling at that level causing perl to dump core. Since version 5.8.0, perl looks at %SIG *after* the signal has been caught, rather than while it is being caught. Previous versions of this answer were incorrect.

How do I modify the shadow password file on a Unix system?

If perl was installed correctly and your shadow library was written properly, the getpw*() functions described in the perlfunc manpage should in theory provide (read-only) access to entries in the shadow password file. To change the file, make a new shadow password file (the format varies from system to system--see passwd for specifics) and use pwd_mkdb(8) to install it (see pwd_mkdb for more details).

How do I set the time and date?

Assuming you're running under sufficient permissions, you should be able to set the system-wide date and time by running the date(1) program. (There is no way to set the time and date on a per-process basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT; the VMS equivalent is set time.

However, if all you want to do is change your time zone, you can probably get away with setting an environment variable:

    $ENV{TZ} = "MST7MDT";                  # unixish
    $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
    system "trn comp.lang.perl.misc";

How can I sleep() or alarm() for under a second?

If you want finer granularity than the 1 second that the sleep() function provides, the easiest way is to use the select() function as documented in select in the perlfunc manpage. Try the Time::HiRes and the BSD::Itimer modules (available from CPAN, and starting from Perl 5.8 Time::HiRes is part of the standard distribution).

How can I measure time under a second?

In general, you may not be able to. The Time::HiRes module (available from CPAN, and starting from Perl 5.8 part of the standard distribution) provides this functionality for some systems.

If your system supports both the syscall() function in Perl as well as a system call like gettimeofday(2), then you may be able to do something like this:

    require 'sys/syscall.ph';

    $TIMEVAL_T = "LL";

    $done = $start = pack($TIMEVAL_T, ());

    syscall(&SYS_gettimeofday, $start, 0) != -1
               or die "gettimeofday: $!";

       ##########################
       # DO YOUR OPERATION HERE #
       ##########################

    syscall( &SYS_gettimeofday, $done, 0) != -1
           or die "gettimeofday: $!";

    @start = unpack($TIMEVAL_T, $start);
    @done  = unpack($TIMEVAL_T, $done);

    # fix microseconds
    for ($done[1], $start[1]) { $_ /= 1_000_000 }

    $delta_time = sprintf "%.4f", ($done[0]  + $done[1]  )
                                            -
                                 ($start[0] + $start[1] );

How can I do an atexit() or setjmp()/longjmp()? (Exception handling)

Release 5 of Perl added the END block, which can be used to simulate atexit(). Each package's END block is called when the program or thread ends (see the perlmod manpage manpage for more details).

For example, you can use this to make sure your filter program managed to finish its output without filling up the disk:

    END {
        close(STDOUT) || die "stdout close failed: $!";
    }

The END block isn't called when untrapped signals kill the program, though, so if you use END blocks you should also use

        use sigtrap qw(die normal-signals);

Perl's exception-handling mechanism is its eval() operator. You can use eval() as setjmp and die() as longjmp. For details of this, see the section on signals, especially the time-out handler for a blocking flock() in Signals in the perlipc manpage or the section on "Signals" in the Camel Book.

If exception handling is all you're interested in, try the exceptions.pl library (part of the standard perl distribution).

If you want the atexit() syntax (and an rmexit() as well), try the AtExit module available from CPAN.

Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?

Some Sys-V based systems, notably Solaris 2.X, redefined some of the standard socket constants. Since these were constant across all architectures, they were often hardwired into perl code. The proper way to deal with this is to "use Socket" to get the correct values.

Note that even though SunOS and Solaris are binary compatible, these values are different. Go figure.

How can I call my system's unique C functions from Perl?

In most cases, you write an external module to do it--see the answer to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". However, if the function is a system call, and your system supports syscall(), you can use the syscall function (documented in the perlfunc manpage).

Remember to check the modules that came with your distribution, and CPAN as well---someone may already have written a module to do it. On Windows, try Win32::API. On Macs, try Mac::Carbon. If no module has an interface to the C function, you can inline a bit of C in your Perl source with Inline::C.

Where do I get the include files to do ioctl() or syscall()?

Historically, these would be generated by the h2ph tool, part of the standard perl distribution. This program converts cpp(1) directives in C header files to files containing subroutine definitions, like &SYS_getitimer, which you can use as arguments to your functions. It doesn't work perfectly, but it usually gets most of the job done. Simple files like errno.h, syscall.h, and socket.h were fine, but the hard ones like ioctl.h nearly always need to hand-edited. Here's how to install the *.ph files:

    1.  become super-user
    2.  cd /usr/include
    3.  h2ph *.h */*.h

If your system supports dynamic loading, for reasons of portability and sanity you probably ought to use h2xs (also part of the standard perl distribution). This tool converts C header files to Perl extensions. See the perlxstut manpage for how to get started with h2xs.

If your system doesn't support dynamic loading, you still probably ought to use h2xs. See the perlxstut manpage and the ExtUtils::MakeMaker manpage for more information (in brief, just use make perl instead of a plain make to rebuild perl with a new static extension).

Why do setuid perl scripts complain about kernel problems?

Some operating systems have bugs in the kernel that make setuid scripts inherently insecure. Perl gives you a number of options (described in the perlsec manpage) to work around such systems.

How can I open a pipe both to and from a command?

The IPC::Open2 module (part of the standard perl distribution) is an easy-to-use approach that internally uses pipe(), fork(), and exec() to do the job. Make sure you read the deadlock warnings in its documentation, though (see the IPC::Open2 manpage). See Bidirectional Communication with Another Process in the perlipc manpage and Bidirectional Communication with Yourself in the perlipc manpage

You may also use the IPC::Open3 module (part of the standard perl distribution), but be warned that it has a different order of arguments from IPC::Open2 (see the IPC::Open3 manpage).

Why can't I get the output of a command with system()?

You're confusing the purpose of system() and backticks (``). system() runs a command and returns exit status information (as a 16 bit value: the low 7 bits are the signal the process died from, if any, and the high 8 bits are the actual exit value). Backticks (``) run a command and return what it sent to STDOUT.

    $exit_status   = system("mail-users");
    $output_string = `ls`;

How can I capture STDERR from an external command?

There are three basic ways of running external commands:

    system $cmd;                # using system()
    $output = `$cmd`;           # using backticks (``)
    open (PIPE, "cmd |");       # using open()

With system(), both STDOUT and STDERR will go the same place as the script's STDOUT and STDERR, unless the system() command redirects them. Backticks and open() read only the STDOUT of your command.

You can also use the open3() function from IPC::Open3. Benjamin Goldberg provides some sample code:

To capture a program's STDOUT, but discard its STDERR:

    use IPC::Open3;
    use File::Spec;
    use Symbol qw(gensym);
    open(NULL, ">", File::Spec->devnull);
    my $pid = open3(gensym, \*PH, ">&NULL", "cmd");
    while( <PH> ) { }
    waitpid($pid, 0);

To capture a program's STDERR, but discard its STDOUT:

    use IPC::Open3;
    use File::Spec;
    use Symbol qw(gensym);
    open(NULL, ">", File::Spec->devnull);
    my $pid = open3(gensym, ">&NULL", \*PH, "cmd");
    while( <PH> ) { }
    waitpid($pid, 0);

To capture a program's STDERR, and let its STDOUT go to our own STDERR:

    use IPC::Open3;
    use Symbol qw(gensym);
    my $pid = open3(gensym, ">&STDERR", \*PH, "cmd");
    while( <PH> ) { }
    waitpid($pid, 0);

To read both a command's STDOUT and its STDERR separately, you can redirect them to temp files, let the command run, then read the temp files:

    use IPC::Open3;
    use Symbol qw(gensym);
    use IO::File;
    local *CATCHOUT = IO::File->new_tmpfile;
    local *CATCHERR = IO::File->new_tmpfile;
    my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
    waitpid($pid, 0);
    seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
    while( <CATCHOUT> ) {}
    while( <CATCHERR> ) {}

But there's no real need for *both* to be tempfiles... the following should work just as well, without deadlocking:

    use IPC::Open3;
    use Symbol qw(gensym);
    use IO::File;
    local *CATCHERR = IO::File->new_tmpfile;
    my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
    while( <CATCHOUT> ) {}
    waitpid($pid, 0);
    seek CATCHERR, 0, 0;
    while( <CATCHERR> ) {}

And it'll be faster, too, since we can begin processing the program's stdout immediately, rather than waiting for the program to finish.

With any of these, you can change file descriptors before the call:

    open(STDOUT, ">logfile");
    system("ls");

or you can use Bourne shell file-descriptor redirection:

    $output = `$cmd 2>some_file`;
    open (PIPE, "cmd 2>some_file |");

You can also use file-descriptor redirection to make STDERR a duplicate of STDOUT:

    $output = `$cmd 2>&1`;
    open (PIPE, "cmd 2>&1 |");

Note that you cannot simply open STDERR to be a dup of STDOUT in your Perl program and avoid calling the shell to do the redirection. This doesn't work:

    open(STDERR, ">&STDOUT");
    $alloutput = `cmd args`;  # stderr still escapes

This fails because the open() makes STDERR go to where STDOUT was going at the time of the open(). The backticks then make STDOUT go to a string, but don't change STDERR (which still goes to the old STDOUT).

Note that you must use Bourne shell (sh(1)) redirection syntax in backticks, not csh(1)! Details on why Perl's system() and backtick and pipe opens all use the Bourne shell are in the versus/csh.whynot article in the "Far More Than You Ever Wanted To Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz . To capture a command's STDERR and STDOUT together:

    $output = `cmd 2>&1`;                       # either with backticks
    $pid = open(PH, "cmd 2>&1 |");              # or with an open pipe
    while (<PH>) { }                            #    plus a read

To capture a command's STDOUT but discard its STDERR:

    $output = `cmd 2>/dev/null`;                # either with backticks
    $pid = open(PH, "cmd 2>/dev/null |");       # or with an open pipe
    while (<PH>) { }                            #    plus a read

To capture a command's STDERR but discard its STDOUT:

    $output = `cmd 2>&1 1>/dev/null`;           # either with backticks
    $pid = open(PH, "cmd 2>&1 1>/dev/null |");  # or with an open pipe
    while (<PH>) { }                            #    plus a read

To exchange a command's STDOUT and STDERR in order to capture the STDERR but leave its STDOUT to come out our old STDERR:

    $output = `cmd 3>&1 1>&2 2>&3 3>&-`;        # either with backticks
    $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe
    while (<PH>) { }                            #    plus a read

To read both a command's STDOUT and its STDERR separately, it's easiest to redirect them separately to files, and then read from those files when the program is done:

    system("program args 1>program.stdout 2>program.stderr");

Ordering is important in all these examples. That's because the shell processes file descriptor redirections in strictly left to right order.

    system("prog args 1>tmpfile 2>&1");
    system("prog args 2>&1 1>tmpfile");

The first command sends both standard out and standard error to the temporary file. The second command sends only the old standard output there, and the old standard error shows up on the old standard out.

Why doesn't open() return an error when a pipe open fails?

If the second argument to a piped open() contains shell metacharacters, perl fork()s, then exec()s a shell to decode the metacharacters and eventually run the desired program. If the program couldn't be run, it's the shell that gets the message, not Perl. All your Perl program can find out is whether the shell itself could be successfully started. You can still capture the shell's STDERR and check it for error messages. See How can I capture STDERR from an external command? elsewhere in this document, or use the IPC::Open3 module.

If there are no shell metacharacters in the argument of open(), Perl runs the command directly, without using the shell, and can correctly report whether the command started.

What's wrong with using backticks in a void context?

Strictly speaking, nothing. Stylistically speaking, it's not a good way to write maintainable code. Perl has several operators for running external commands. Backticks are one; they collect the output from the command for use in your program. The system function is another; it doesn't do this.

Writing backticks in your program sends a clear message to the readers of your code that you wanted to collect the output of the command. Why send a clear message that isn't true?

Consider this line:

    `cat /etc/termcap`;

You forgot to check $? to see whether the program even ran correctly. Even if you wrote

    print `cat /etc/termcap`;

this code could and probably should be written as

    system("cat /etc/termcap") == 0
        or die "cat program failed!";

which will get the output quickly (as it is generated, instead of only at the end) and also check the return value.

system() also provides direct control over whether shell wildcard processing may take place, whereas backticks do not.

How can I call backticks without shell processing?

This is a bit tricky. You can't simply write the command like this:

    @ok = `grep @opts '$search_string' @filenames`;

As of Perl 5.8.0, you can use open() with multiple arguments. Just like the list forms of system() and exec(), no shell escapes happen.

   open( GREP, "-|", 'grep', @opts, $search_string, @filenames );
   chomp(@ok = <GREP>);
   close GREP;

You can also:

    my @ok = ();
    if (open(GREP, "-|")) {
        while (<GREP>) {
            chomp;
            push(@ok, $_);
        }
        close GREP;
    } else {
        exec 'grep', @opts, $search_string, @filenames;
    }

Just as with system(), no shell escapes happen when you exec() a list. Further examples of this can be found in Safe Pipe Opens in the perlipc manpage.

Note that if you're use Microsoft, no solution to this vexing issue is even possible. Even if Perl were to emulate fork(), you'd still be stuck, because Microsoft does not have a argc/argv-style API.

Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?

Some stdio's set error and eof flags that need clearing. The POSIX module defines clearerr() that you can use. That is the technically correct way to do it. Here are some less reliable workarounds:

  1. Try keeping around the seekpointer and go there, like this:

        $where = tell(LOG);
    seek(LOG, $where, 0);

  2. If that doesn't work, try seeking to a different part of the file and then back.

  3. If that doesn't work, try seeking to a different part of the file, reading something, and then seeking back.

  4. If that doesn't work, give up on your stdio package and use sysread.

How can I convert my shell script to perl?

Learn Perl and rewrite it. Seriously, there's no simple converter. Things that are awkward to do in the shell are easy to do in Perl, and this very awkwardness is what would make a shell->perl converter nigh-on impossible to write. By rewriting it, you'll think about what you're really trying to do, and hopefully will escape the shell's pipeline datastream paradigm, which while convenient for some matters, causes many inefficiencies.

Can I use perl to run a telnet or ftp session?

Try the Net::FTP, TCP::Client, and Net::Telnet modules (available from CPAN). http://www.cpan.org/scripts/netstuff/telnet.emul.shar will also help for emulating the telnet protocol, but Net::Telnet is quite probably easier to use..

If all you want to do is pretend to be telnet but don't need the initial telnet handshaking, then the standard dual-process approach will suffice:

    use IO::Socket;             # new in 5.004
    $handle = IO::Socket::INET->new('www.perl.com:80')
            || die "can't connect to port 80 on www.perl.com: $!";
    $handle->autoflush(1);
    if (fork()) {               # XXX: undef means failure
        select($handle);
        print while <STDIN>;    # everything from stdin to socket
    } else {
        print while <$handle>;  # everything from socket to stdout
    }
    close $handle;
    exit;

How can I write expect in Perl?

Once upon a time, there was a library called chat2.pl (part of the standard perl distribution), which never really got finished. If you find it somewhere, don't use it. These days, your best bet is to look at the Expect module available from CPAN, which also requires two other modules from CPAN, IO::Pty and IO::Stty.

Is there a way to hide perl's command line from programs such as "ps"?

First of all note that if you're doing this for security reasons (to avoid people seeing passwords, for example) then you should rewrite your program so that critical information is never given as an argument. Hiding the arguments won't make your program completely secure.

To actually alter the visible command line, you can assign to the variable $0 as documented in the perlvar manpage. This won't work on all operating systems, though. Daemon programs like sendmail place their state there, as in:

    $0 = "orcus [accepting connections]";

I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?

Unix

In the strictest sense, it can't be done--the script executes as a different process from the shell it was started from. Changes to a process are not reflected in its parent--only in any children created after the change. There is shell magic that may allow you to fake it by eval()ing the script's output in your shell; check out the comp.unix.questions FAQ for details.

How do I close a process's filehandle without waiting for it to complete?

Assuming your system supports such things, just send an appropriate signal to the process (see kill in the perlfunc manpage). It's common to first send a TERM signal, wait a little bit, and then send a KILL signal to finish it off.

How do I fork a daemon process?

If by daemon process you mean one that's detached (disassociated from its tty), then the following process is reported to work on most Unixish systems. Non-Unix users should check their Your_OS::Process module for other solutions.

  • Open /dev/tty and use the TIOCNOTTY ioctl on it. See tty for details. Or better yet, you can just use the POSIX::setsid() function, so you don't have to worry about process groups.

  • Change directory to /

  • Reopen STDIN, STDOUT, and STDERR so they're not connected to the old tty.

  • Background yourself like this:

        fork && exit;

The Proc::Daemon module, available from CPAN, provides a function to perform these actions for you.

How do I find out if I'm running interactively or not?

Good question. Sometimes -t STDIN and -t STDOUT can give clues, sometimes not.

    if (-t STDIN && -t STDOUT) {
        print "Now what? ";
    }

On POSIX systems, you can test whether your own process group matches the current process group of your controlling terminal as follows:

    use POSIX qw/getpgrp tcgetpgrp/;
    open(TTY, "/dev/tty") or die $!;
    $tpgrp = tcgetpgrp(fileno(*TTY));
    $pgrp = getpgrp();
    if ($tpgrp == $pgrp) {
        print "foreground\n";
    } else {
        print "background\n";
    }

How do I timeout a slow event?

Use the alarm() function, probably in conjunction with a signal handler, as documented in Signals in the perlipc manpage and the section on "Signals" in the Camel. You may instead use the more flexible Sys::AlarmCall module available from CPAN.

The alarm() function is not implemented on all versions of Windows. Check the documentation for your specific version of Perl.

How do I set CPU limits?

Use the BSD::Resource module from CPAN.

How do I avoid zombies on a Unix system?

Use the reaper code from Signals in the perlipc manpage to call wait() when a SIGCHLD is received, or else use the double-fork technique described in How do I start a process in the background? in the perlfaq8 manpage.

How do I use an SQL database?

The DBI module provides an abstract interface to most database servers and types, including Oracle, DB2, Sybase, mysql, Postgresql, ODBC, and flat files. The DBI module accesses each database type through a database driver, or DBD. You can see a complete list of available drivers on CPAN: http://www.cpan.org/modules/by-module/DBD/ . You can read more about DBI on http://dbi.perl.org .

Other modules provide more specific access: Win32::ODBC, Alzabo, iodbc, and others found on CPAN Search: http://search.cpan.org .

How do I make a system() exit on control-C?

You can't. You need to imitate the system() call (see the perlipc manpage for sample code) and then have a signal handler for the INT signal that passes the signal on to the subprocess. Or you can check for it:

    $rc = system($cmd);
    if ($rc & 127) { die "signal death" }

How do I open a file without blocking?

If you're lucky enough to be using a system that supports non-blocking reads (most Unixish systems do), you need only to use the O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with sysopen():

    use Fcntl;
    sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
        or die "can't open /foo/somefile: $!":

How do I tell the difference between errors from the shell and perl?

(answer contributed by brian d foy, <bdfoy@cpan.org>

When you run a Perl script, something else is running the script for you, and that something else may output error messages. The script might emit its own warnings and error messages. Most of the time you cannot tell who said what.

You probably cannot fix the thing that runs perl, but you can change how perl outputs its warnings by defining a custom warning and die functions.

Consider this script, which has an error you may not notice immediately.

        #!/usr/locl/bin/perl

        print "Hello World\n";

I get an error when I run this from my shell (which happens to be bash). That may look like perl forgot it has a print() function, but my shebang line is not the path to perl, so the shell runs the script, and I get the error.

        $ ./test
        ./test: line 3: print: command not found

A quick and dirty fix involves a little bit of code, but this may be all you need to figure out the problem.

        #!/usr/bin/perl -w

        BEGIN {
        $SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; };
        $SIG{__DIE__}  = sub{ print STDERR "Perl: ", @_; exit 1};
        }

        $a = 1 + undef;
        $x / 0;
        __END__

The perl message comes out with "Perl" in front. The BEGIN block works at compile time so all of the compilation errors and warnings get the "Perl:" prefix too.

        Perl: Useless use of division (/) in void context at ./test line 9.
        Perl: Name "main::a" used only once: possible typo at ./test line 8.
        Perl: Name "main::x" used only once: possible typo at ./test line 9.
        Perl: Use of uninitialized value in addition (+) at ./test line 8.
        Perl: Use of uninitialized value in division (/) at ./test line 9.
        Perl: Illegal division by zero at ./test line 9.
        Perl: Illegal division by zero at -e line 3.

If I don't see that "Perl:", it's not from perl.

You could also just know all the perl errors, and although there are some people who may know all of them, you probably don't. However, they all should be in the perldiag manpage. If you don't find the error in there, it probably isn't a perl error.

Looking up every message is not the easiest way, so let perl to do it for you. Use the diagnostics pragma with turns perl's normal messages into longer discussions on the topic.

        use diagnostics;

If you don't get a paragraph or two of expanded discussion, it might not be perl's message.

How do I install a module from CPAN?

The easiest way is to have a module also named CPAN do it for you. This module comes with perl version 5.004 and later.

    $ perl -MCPAN -e shell
    cpan shell -- CPAN exploration and modules installation (v1.59_54)
    ReadLine support enabled
    cpan> install Some::Module

To manually install the CPAN module, or any well-behaved CPAN module for that matter, follow these steps:

  1. Unpack the source into a temporary area.

  2.     perl Makefile.PL
  3.     make
  4.     make test
  5.     make install

If your version of perl is compiled without dynamic loading, then you just need to replace step 3 (make) with make perl and you will get a new perl binary with your extension linked in.

See the ExtUtils::MakeMaker manpage for more details on building extensions. See also the next question, "What's the difference between require and use?".

What's the difference between require and use?

Perl offers several different ways to include code from one file into another. Here are the deltas between the various inclusion constructs:

    1)  do $file is like eval `cat $file`, except the former
        1.1: searches @INC and updates %INC.
        1.2: bequeaths an *unrelated* lexical scope on the eval'ed code.
    2)  require $file is like do $file, except the former
        2.1: checks for redundant loading, skipping already loaded files.
        2.2: raises an exception on failure to find, compile, or execute $file.
    3)  require Module is like require "Module.pm", except the former
        3.1: translates each "::" into your system's directory separator.
        3.2: primes the parser to disambiguate class Module as an indirect object.
    4)  use Module is like require Module, except the former
        4.1: loads the module at compile time, not run-time.
        4.2: imports symbols and semantics from that package to the current one.

In general, you usually want use and a proper Perl module.

How do I keep my own module/library directory?

When you build modules, use the PREFIX and LIB options when generating Makefiles:

    perl Makefile.PL PREFIX=/mydir/perl LIB=/mydir/perl/lib

then either set the PERL5LIB environment variable before you run scripts that use the modules/libraries (see the perlrun manpage) or say

    use lib '/mydir/perl/lib';

This is almost the same as

    BEGIN {
        unshift(@INC, '/mydir/perl/lib');
    }

except that the lib module checks for machine-dependent subdirectories. See Perl's the lib manpage for more information.

How do I add the directory my program lives in to the module/library search path?

    use FindBin;
    use lib "$FindBin::Bin";
    use your_own_modules;

How do I add a directory to my include path (@INC) at runtime?

Here are the suggested ways of modifying your include path:

    the PERLLIB environment variable
    the PERL5LIB environment variable
    the perl -Idir command line flag
    the use lib pragma, as in
        use lib "$ENV{HOME}/myown_perllib";

The latter is particularly useful because it knows about machine dependent architectures. The lib.pm pragmatic module was first included with the 5.002 release of Perl.

What is socket.ph and where do I get it?

It's a perl4-style file defining values for system networking constants. Sometimes it is built using h2ph when Perl is installed, but other times it is not. Modern programs use Socket; instead.

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perlfaq9 - Networking

    • What is the correct form of response from a CGI script?
    • My CGI script runs from the command line but not the browser. (500 Server Error)
    • How can I get better error messages from a CGI program?
    • How do I remove HTML from a string?
    • How do I extract URLs?
    • How do I download a file from the user's machine? How do I open a file on another machine?
    • How do I make a pop-up menu in HTML?
    • How do I fetch an HTML file?
    • How do I automate an HTML form submission?
    • How do I decode or create those %-encodings on the web?
    • How do I redirect to another page?
    • How do I put a password on my web pages?
    • How do I edit my .htpasswd and .htgroup files with Perl?
    • How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
    • How do I parse a mail header?
    • How do I decode a CGI form?
    • How do I check a valid mail address?
    • How do I decode a MIME/BASE64 string?
    • How do I return the user's mail address?
    • How do I send mail?
    • How do I use MIME to make an attachment to a mail message?
    • How do I read mail?
    • How do I find out my hostname, domainname, or IP address?
    • How do I fetch a news article or the active newsgroups?
    • How do I fetch/put an FTP file?
    • How can I do RPC in Perl?
  • AUTHOR AND COPYRIGHT

NAME

perlfaq9 - Networking ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION

This section deals with questions related to networking, the internet, and a few on the web.

What is the correct form of response from a CGI script?

(Alan Flavell <flavell+www@a5.ph.gla.ac.uk> answers...)

The Common Gateway Interface (CGI) specifies a software interface between a program ("CGI script") and a web server (HTTPD). It is not specific to Perl, and has its own FAQs and tutorials, and usenet group, comp.infosystems.www.authoring.cgi

The CGI specification is outlined in an informational RFC: http://www.ietf.org/rfc/rfc3875

Other relevant documentation listed in: http://www.perl.org/CGI_MetaFAQ.html

These Perl FAQs very selectively cover some CGI issues. However, Perl programmers are strongly advised to use the CGI.pm module, to take care of the details for them.

The similarity between CGI response headers (defined in the CGI specification) and HTTP response headers (defined in the HTTP specification, RFC2616) is intentional, but can sometimes be confusing.

The CGI specification defines two kinds of script: the "Parsed Header" script, and the "Non Parsed Header" (NPH) script. Check your server documentation to see what it supports. "Parsed Header" scripts are simpler in various respects. The CGI specification allows any of the usual newline representations in the CGI response (it's the server's job to create an accurate HTTP response based on it). So "\n" written in text mode is technically correct, and recommended. NPH scripts are more tricky: they must put out a complete and accurate set of HTTP transaction response headers; the HTTP specification calls for records to be terminated with carriage-return and line-feed, i.e ASCII \015\012 written in binary mode.

Using CGI.pm gives excellent platform independence, including EBCDIC systems. CGI.pm selects an appropriate newline representation ($CGI::CRLF) and sets binmode as appropriate.

My CGI script runs from the command line but not the browser. (500 Server Error)

Several things could be wrong. You can go through the "Troubleshooting Perl CGI scripts" guide at

        http://www.perl.org/troubleshooting_CGI.html

If, after that, you can demonstrate that you've read the FAQs and that your problem isn't something simple that can be easily answered, you'll probably receive a courteous and useful reply to your question if you post it on comp.infosystems.www.authoring.cgi (if it's something to do with HTTP or the CGI protocols). Questions that appear to be Perl questions but are really CGI ones that are posted to comp.lang.perl.misc are not so well received.

The useful FAQs, related documents, and troubleshooting guides are listed in the CGI Meta FAQ:

        http://www.perl.org/CGI_MetaFAQ.html

How can I get better error messages from a CGI program?

Use the CGI::Carp module. It replaces warn and die, plus the normal Carp modules carp, croak, and confess functions with more verbose and safer versions. It still sends them to the normal server error log.

    use CGI::Carp;
    warn "This is a complaint";
    die "But this one is serious";

The following use of CGI::Carp also redirects errors to a file of your choice, placed in a BEGIN block to catch compile-time warnings as well:

    BEGIN {
        use CGI::Carp qw(carpout);
        open(LOG, ">>/var/local/cgi-logs/mycgi-log")
            or die "Unable to append to mycgi-log: $!\n";
        carpout(*LOG);
    }

You can even arrange for fatal errors to go back to the client browser, which is nice for your own debugging, but might confuse the end user.

    use CGI::Carp qw(fatalsToBrowser);
    die "Bad error here";

Even if the error happens before you get the HTTP header out, the module will try to take care of this to avoid the dreaded server 500 errors. Normal warnings still go out to the server error log (or wherever you've sent them with carpout) with the application name and date stamp prepended.

How do I remove HTML from a string?

The most correct way (albeit not the fastest) is to use HTML::Parser from CPAN. Another mostly correct way is to use HTML::FormatText which not only removes HTML but also attempts to do a little simple formatting of the resulting plain text.

Many folks attempt a simple-minded regular expression approach, like s/<.*?>//g, but that fails in many cases because the tags may continue over line breaks, they may contain quoted angle-brackets, or HTML comment may be present. Plus, folks forget to convert entities--like &lt; for example.

Here's one "simple-minded" approach, that works for most files:

    #!/usr/bin/perl -p0777
    s/<(?:[^>'"]*|(['"]).*?\1)*>//gs

If you want a more complete solution, see the 3-stage striphtml program in http://www.cpan.org/authors/Tom_Christiansen/scripts/striphtml.gz .

Here are some tricky cases that you should think about when picking a solution:

    <IMG SRC = "foo.gif" ALT = "A > B">
    <IMG SRC = "foo.gif"
         ALT = "A > B">
    <!-- <A comment> -->
    <script>if (a<b && a>c)</script>
    <# Just data #>
    <![INCLUDE CDATA [ >>>>>>>>>>>> ]]>

If HTML comments include other tags, those solutions would also break on text like this:

    <!-- This section commented out.
        <B>You can't see me!</B>
    -->

How do I extract URLs?

You can easily extract all sorts of URLs from HTML with HTML::SimpleLinkExtor which handles anchors, images, objects, frames, and many other tags that can contain a URL. If you need anything more complex, you can create your own subclass of HTML::LinkExtor or HTML::Parser. You might even use HTML::SimpleLinkExtor as an example for something specifically suited to your needs.

You can use URI::Find to extract URLs from an arbitrary text document.

Less complete solutions involving regular expressions can save you a lot of processing time if you know that the input is simple. One solution from Tom Christiansen runs 100 times faster than most module based approaches but only extracts URLs from anchors where the first attribute is HREF and there are no other attributes.

        #!/usr/bin/perl -n00
        # qxurl - tchrist@perl.com
        print "$2\n" while m{
            < \s*
              A \s+ HREF \s* = \s* (["']) (.*?) \1
            \s* >
        }gsix;

How do I download a file from the user's machine? How do I open a file on another machine?

In this case, download means to use the file upload feature of HTML forms. You allow the web surfer to specify a file to send to your web server. To you it looks like a download, and to the user it looks like an upload. No matter what you call it, you do it with what's known as multipart/form-data encoding. The CGI.pm module (which comes with Perl as part of the Standard Library) supports this in the start_multipart_form() method, which isn't the same as the startform() method.

See the section in the CGI.pm documentation on file uploads for code examples and details.

How do I make a pop-up menu in HTML?

Use the <SELECT >> and <OPTION >> tags. The CGI.pm module (available from CPAN) supports this widget, as well as many others, including some that it cleverly synthesizes on its own.

How do I fetch an HTML file?

One approach, if you have the lynx text-based HTML browser installed on your system, is this:

    $html_code = `lynx -source $url`;
    $text_data = `lynx -dump $url`;

The libwww-perl (LWP) modules from CPAN provide a more powerful way to do this. They don't require lynx, but like lynx, can still work through proxies:

    # simplest version
    use LWP::Simple;
    $content = get($URL);

    # or print HTML from a URL
    use LWP::Simple;
    getprint "http://www.linpro.no/lwp/";

    # or print ASCII from HTML from a URL
    # also need HTML-Tree package from CPAN
    use LWP::Simple;
    use HTML::Parser;
    use HTML::FormatText;
    my ($html, $ascii);
    $html = get("http://www.perl.com/");
    defined $html
        or die "Can't fetch HTML from http://www.perl.com/";
    $ascii = HTML::FormatText->new->format(parse_html($html));
    print $ascii;

How do I automate an HTML form submission?

If you are doing something complex, such as moving through many pages and forms or a web site, you can use WWW::Mechanize. See its documentation for all the details.

If you're submitting values using the GET method, create a URL and encode the form using the query_form method:

    use LWP::Simple;
    use URI::URL;

    my $url = url('http://www.perl.com/cgi-bin/cpan_mod');
    $url->query_form(module => 'DB_File', readme => 1);
    $content = get($url);

If you're using the POST method, create your own user agent and encode the content appropriately.

    use HTTP::Request::Common qw(POST);
    use LWP::UserAgent;

    $ua = LWP::UserAgent->new();
    my $req = POST 'http://www.perl.com/cgi-bin/cpan_mod',
                   [ module => 'DB_File', readme => 1 ];
    $content = $ua->request($req)->as_string;

How do I decode or create those %-encodings on the web?

If you are writing a CGI script, you should be using the CGI.pm module that comes with perl, or some other equivalent module. The CGI module automatically decodes queries for you, and provides an escape() function to handle encoding.

The best source of detailed information on URI encoding is RFC 2396. Basically, the following substitutions do it:

    s/([^\w()'*~!.-])/sprintf '%%%02x', ord $1/eg;   # encode

    s/%([A-Fa-f\d]{2})/chr hex $1/eg;                # decode
        s/%([[:xdigit:]]{2})/chr hex $1/eg;          # same thing

However, you should only apply them to individual URI components, not the entire URI, otherwise you'll lose information and generally mess things up. If that didn't explain it, don't worry. Just go read section 2 of the RFC, it's probably the best explanation there is.

RFC 2396 also contains a lot of other useful information, including a regexp for breaking any arbitrary URI into components (Appendix B).

How do I redirect to another page?

Specify the complete URL of the destination (even if it is on the same server). This is one of the two different kinds of CGI "Location:" responses which are defined in the CGI specification for a Parsed Headers script. The other kind (an absolute URLpath) is resolved internally to the server without any HTTP redirection. The CGI specifications do not allow relative URLs in either case.

Use of CGI.pm is strongly recommended. This example shows redirection with a complete URL. This redirection is handled by the web browser.

      use CGI qw/:standard/;

      my $url = 'http://www.cpan.org/';
      print redirect($url);

This example shows a redirection with an absolute URLpath. This redirection is handled by the local web server.

      my $url = '/CPAN/index.html';
      print redirect($url);

But if coded directly, it could be as follows (the final "\n" is shown separately, for clarity), using either a complete URL or an absolute URLpath.

      print "Location: $url\n";   # CGI response header
      print "\n";                 # end of headers

How do I put a password on my web pages?

To enable authentication for your web server, you need to configure your web server. The configuration is different for different sorts of web servers---apache does it differently from iPlanet which does it differently from IIS. Check your web server documentation for the details for your particular server.

How do I edit my .htpasswd and .htgroup files with Perl?

The HTTPD::UserAdmin and HTTPD::GroupAdmin modules provide a consistent OO interface to these files, regardless of how they're stored. Databases may be text, dbm, Berkeley DB or any database with a DBI compatible driver. HTTPD::UserAdmin supports files used by the "Basic" and "Digest" authentication schemes. Here's an example:

    use HTTPD::UserAdmin ();
    HTTPD::UserAdmin
          ->new(DB => "/foo/.htpasswd")
          ->add($username => $password);

How do I make sure users can't enter values into a form that cause my CGI script to do bad things?

See the security references listed in the CGI Meta FAQ

        http://www.perl.org/CGI_MetaFAQ.html

How do I parse a mail header?

For a quick-and-dirty solution, try this solution derived from split in the perlfunc manpage:

    $/ = '';
    $header = <MSG>;
    $header =~ s/\n\s+/ /g;      # merge continuation lines
    %head = ( UNIX_FROM_LINE, split /^([-\w]+):\s*/m, $header );

That solution doesn't do well if, for example, you're trying to maintain all the Received lines. A more complete approach is to use the Mail::Header module from CPAN (part of the MailTools package).

How do I decode a CGI form?

(contributed by brian d foy)

Use the CGI.pm module that comes with Perl. It's quick, it's easy, and it actually does quite a bit of work to ensure things happen correctly. It handles GET, POST, and HEAD requests, multipart forms, multivalued fields, query string and message body combinations, and many other things you probably don't want to think about.

It doesn't get much easier: the CGI module automatically parses the input and makes each value available through the param() function.

        use CGI qw(:standard);

        my $total = param( 'price' ) + param( 'shipping' );

        my @items = param( 'item' ); # multiple values, same field name

If you want an object-oriented approach, CGI.pm can do that too.

        use CGI;

        my $cgi = CGI->new();

        my $total = $cgi->param( 'price' ) + $cgi->param( 'shipping' );

        my @items = $cgi->param( 'item' );

You might also try CGI::Minimal which is a lightweight version of the same thing. Other CGI::* modules on CPAN might work better for you, too.

Many people try to write their own decoder (or copy one from another program) and then run into one of the many "gotchas" of the task. It's much easier and less hassle to use CGI.pm.

How do I check a valid mail address?

You can't, at least, not in real time. Bummer, eh?

Without sending mail to the address and seeing whether there's a human on the other end to answer you, you cannot determine whether a mail address is valid. Even if you apply the mail header standard, you can have problems, because there are deliverable addresses that aren't RFC-822 (the mail header standard) compliant, and addresses that aren't deliverable which are compliant.

You can use the Email::Valid or RFC::RFC822::Address which check the format of the address, although they cannot actually tell you if it is a deliverable address (i.e. that mail to the address will not bounce). Modules like Mail::CheckUser and Mail::EXPN try to interact with the domain name system or particular mail servers to learn even more, but their methods do not work everywhere---especially for security conscious administrators.

Many are tempted to try to eliminate many frequently-invalid mail addresses with a simple regex, such as /^[\w.-]+\@(?:[\w-]+\.)+\w+$/. It's a very bad idea. However, this also throws out many valid ones, and says nothing about potential deliverability, so it is not suggested. Instead, see http://www.cpan.org/authors/Tom_Christiansen/scripts/ckaddr.gz , which actually checks against the full RFC spec (except for nested comments), looks for addresses you may not wish to accept mail to (say, Bill Clinton or your postmaster), and then makes sure that the hostname given can be looked up in the DNS MX records. It's not fast, but it works for what it tries to do.

Our best advice for verifying a person's mail address is to have them enter their address twice, just as you normally do to change a password. This usually weeds out typos. If both versions match, send mail to that address with a personal message that looks somewhat like:

    Dear someuser@host.com,
    Please confirm the mail address you gave us Wed May  6 09:38:41
    MDT 1998 by replying to this message.  Include the string
    "Rumpelstiltskin" in that reply, but spelled in reverse; that is,
    start with "Nik...".  Once this is done, your confirmed address will
    be entered into our records.

If you get the message back and they've followed your directions, you can be reasonably assured that it's real.

A related strategy that's less open to forgery is to give them a PIN (personal ID number). Record the address and PIN (best that it be a random one) for later processing. In the mail you send, ask them to include the PIN in their reply. But if it bounces, or the message is included via a "vacation" script, it'll be there anyway. So it's best to ask them to mail back a slight alteration of the PIN, such as with the characters reversed, one added or subtracted to each digit, etc.

How do I decode a MIME/BASE64 string?

The MIME-Base64 package (available from CPAN) handles this as well as the MIME/QP encoding. Decoding BASE64 becomes as simple as:

    use MIME::Base64;
    $decoded = decode_base64($encoded);

The MIME-Tools package (available from CPAN) supports extraction with decoding of BASE64 encoded attachments and content directly from email messages.

If the string to decode is short (less than 84 bytes long) a more direct approach is to use the unpack() function's "u" format after minor transliterations:

    tr#A-Za-z0-9+/##cd;                   # remove non-base64 chars
    tr#A-Za-z0-9+/# -_#;                  # convert to uuencoded format
    $len = pack("c", 32 + 0.75*length);   # compute length byte
    print unpack("u", $len . $_);         # uudecode and print

How do I return the user's mail address?

On systems that support getpwuid, the $< variable, and the Sys::Hostname module (which is part of the standard perl distribution), you can probably try using something like this:

    use Sys::Hostname;
    $address = sprintf('%s@%s', scalar getpwuid($<), hostname);

Company policies on mail address can mean that this generates addresses that the company's mail system will not accept, so you should ask for users' mail addresses when this matters. Furthermore, not all systems on which Perl runs are so forthcoming with this information as is Unix.

The Mail::Util module from CPAN (part of the MailTools package) provides a mailaddress() function that tries to guess the mail address of the user. It makes a more intelligent guess than the code above, using information given when the module was installed, but it could still be incorrect. Again, the best way is often just to ask the user.

How do I send mail?

Use the sendmail program directly:

    open(SENDMAIL, "|/usr/lib/sendmail -oi -t -odq")
                        or die "Can't fork for sendmail: $!\n";
    print SENDMAIL <<"EOF";
    From: User Originating Mail <me\@host>
    To: Final Destination <you\@otherhost>
    Subject: A relevant subject line

    Body of the message goes here after the blank line
    in as many lines as you like.
    EOF
    close(SENDMAIL)     or warn "sendmail didn't close nicely";

The -oi option prevents sendmail from interpreting a line consisting of a single dot as "end of message". The -t option says to use the headers to decide who to send the message to, and -odq says to put the message into the queue. This last option means your message won't be immediately delivered, so leave it out if you want immediate delivery.

Alternate, less convenient approaches include calling mail (sometimes called mailx) directly or simply opening up port 25 have having an intimate conversation between just you and the remote SMTP daemon, probably sendmail.

Or you might be able use the CPAN module Mail::Mailer:

    use Mail::Mailer;

    $mailer = Mail::Mailer->new();
    $mailer->open({ From    => $from_address,
                    To      => $to_address,
                    Subject => $subject,
                  })
        or die "Can't open: $!\n";
    print $mailer $body;
    $mailer->close();

The Mail::Internet module uses Net::SMTP which is less Unix-centric than Mail::Mailer, but less reliable. Avoid raw SMTP commands. There are many reasons to use a mail transport agent like sendmail. These include queuing, MX records, and security.

How do I use MIME to make an attachment to a mail message?

This answer is extracted directly from the MIME::Lite documentation. Create a multipart message (i.e., one with attachments).

    use MIME::Lite;

    ### Create a new multipart message:
    $msg = MIME::Lite->new(
                 From    =>'me@myhost.com',
                 To      =>'you@yourhost.com',
                 Cc      =>'some@other.com, some@more.com',
                 Subject =>'A message with 2 parts...',
                 Type    =>'multipart/mixed'
                 );

    ### Add parts (each "attach" has same arguments as "new"):
    $msg->attach(Type     =>'TEXT',
                 Data     =>"Here's the GIF file you wanted"
                 );
    $msg->attach(Type     =>'image/gif',
                 Path     =>'aaa000123.gif',
                 Filename =>'logo.gif'
                 );

    $text = $msg->as_string;

MIME::Lite also includes a method for sending these things.

    $msg->send;

This defaults to using sendmail but can be customized to use SMTP via the Net::SMTP manpage.

How do I read mail?

While you could use the Mail::Folder module from CPAN (part of the MailFolder package) or the Mail::Internet module from CPAN (part of the MailTools package), often a module is overkill. Here's a mail sorter.

    #!/usr/bin/perl

    my(@msgs, @sub);
    my $msgno = -1;
    $/ = '';                    # paragraph reads
    while (<>) {
        if (/^From /m) {
            /^Subject:\s*(?:Re:\s*)*(.*)/mi;
            $sub[++$msgno] = lc($1) || '';
        }
        $msgs[$msgno] .= $_;
    }
    for my $i (sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msgs)) {
        print $msgs[$i];
    }

Or more succinctly,

    #!/usr/bin/perl -n00
    # bysub2 - awkish sort-by-subject
    BEGIN { $msgno = -1 }
    $sub[++$msgno] = (/^Subject:\s*(?:Re:\s*)*(.*)/mi)[0] if /^From/m;
    $msg[$msgno] .= $_;
    END { print @msg[ sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msg) ] }

How do I find out my hostname, domainname, or IP address?

(contributed by brian d foy)

The Net::Domain module, which is part of the standard distribution starting in perl5.7.3, can get you the fully qualified domain name (FQDN), the host name, or the domain name.

        use Net::Domain qw(hostname hostfqdn hostdomain);

        my $host = hostfqdn();

The Sys::Hostname module, included in the standard distribution since perl5.6, can also get the hostname.

        use Sys::Hostname;

        $host = hostname();

To get the IP address, you can use the gethostbyname built-in function to turn the name into a number. To turn that number into the dotted octet form (a.b.c.d) that most people expect, use the inet_ntoa function from the <Socket> module, which also comes with perl.

    use Socket;

    my $address = inet_ntoa(
        scalar gethostbyname( $host || 'localhost' )
        );

How do I fetch a news article or the active newsgroups?

Use the Net::NNTP or News::NNTPClient modules, both available from CPAN. This can make tasks like fetching the newsgroup list as simple as

    perl -MNews::NNTPClient
      -e 'print News::NNTPClient->new->list("newsgroups")'

How do I fetch/put an FTP file?

LWP::Simple (available from CPAN) can fetch but not put. Net::FTP (also available from CPAN) is more complex but can put as well as fetch.

How can I do RPC in Perl?

(Contributed by brian d foy)

Use one of the RPC modules you can find on CPAN ( http://search.cpan.org/search?query=RPC&mode=all ).

AUTHOR AND COPYRIGHT

Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


perldelta - what is new for perl v5.8.8

  • Incompatible Changes
  • Core Enhancements
  • Modules and Pragmata
  • Utility Changes
    • h2xs enhancements
    • perlivp enhancements
  • New Documentation
  • Performance Enhancements
  • Installation and Configuration Improvements
  • Selected Bug Fixes
    • no warnings 'category' works correctly with -w
    • Remove over-optimisation
    • sprintf() fixes
    • Debugger and Unicode slowdown
    • Smaller fixes
  • New or Changed Diagnostics
    • Attempt to set length of freed array
    • Non-string passed as bitmask
    • Search pattern not terminated or ternary operator parsed as search pattern
  • Changed Internals
  • Platform Specific Problems
  • Reporting Bugs
  • SEE ALSO

NAME

perldelta - what is new for perl v5.8.8

DESCRIPTION

This document describes differences between the 5.8.7 release and the 5.8.8 release.

Incompatible Changes

There are no changes intentionally incompatible with 5.8.7. If any exist, they are bugs and reports are welcome.

Core Enhancements

  • chdir, chmod and chown can now work on filehandles as well as filenames, if the system supports respectively fchdir, fchmod and fchown, thanks to a patch provided by Gisle Aas.

Modules and Pragmata

  • Attribute::Handlers upgraded to version 0.78_02

    • Documentation typo fix

  • attrs upgraded to version 1.02

    • Internal cleanup only

  • autouse upgraded to version 1.05

    • Simplified implementation

  • B upgraded to version 1.09_01

    • The inheritance hierarchy of the B:: modules has been corrected; B::NV now inherits from B::SV (instead of B::IV).

  • blib upgraded to version 1.03

    • Documentation typo fix

  • ByteLoader upgraded to version 0.06

    • Internal cleanup

  • CGI upgraded to version 3.15

    • Extraneous "?" from self_url() removed

    • scrolling_list() select attribute fixed

    • virtual_port now works properly with the https protocol

    • upload_hook() and append() now works in function-oriented mode

    • POST_MAX doesn't cause the client to hang any more

    • Automatic tab indexes are now disabled and new -tabindex pragma has been added to turn automatic indexes back on

    • end_form() doesn't emit empty (and non-validating) <div>

    • CGI::Carp works better in certain mod_perl configurations

    • Setting $CGI::TMPDIRECTORY is now effective

    • Enhanced documentation

  • charnames upgraded to version 1.05

    • viacode() now accept hex strings and has been optimized.

  • CPAN upgraded to version 1.76_02

    • 1 minor bug fix for Win32

  • Cwd upgraded to version 3.12

    • canonpath() on Win32 now collapses foo\.. sections correctly.

    • Improved behaviour on Symbian OS.

    • Enhanced documentation and typo fixes

    • Internal cleanup

  • Data::Dumper upgraded to version 2.121_08

    • A problem where Data::Dumper would sometimes update the iterator state of hashes has been fixed

    • Numeric labels now work

    • Internal cleanup

  • DB upgraded to version 1.01

    • A problem where the state of the regexp engine would sometimes get clobbered when running under the debugger has been fixed.

  • DB_File upgraded to version 1.814

    • Adds support for Berkeley DB 4.4.

  • Devel::DProf upgraded to version 20050603.00

    • Internal cleanup

  • Devel::Peek upgraded to version 1.03

    • Internal cleanup

  • Devel::PPPort upgraded to version 3.06_01

    • --compat-version argument checking has been improved

    • Files passed on the command line are filtered by default

    • --nofilter option to override the filtering has been added

    • Enhanced documentation

  • diagnostics upgraded to version 1.15

    • Documentation typo fix

  • Digest upgraded to version 1.14

    • The constructor now knows which module implements SHA-224

    • Documentation tweaks and typo fixes

  • Digest::MD5 upgraded to version 2.36

    • XSLoader is now used for faster loading

    • Enhanced documentation including MD5 weaknesses discovered lately

  • Dumpvalue upgraded to version 1.12

    • Documentation fix

  • DynaLoader upgraded but unfortunately we're not able to increment its version number :-(

    • Implements dl_unload_file on Win32

    • Internal cleanup

    • XSLoader 0.06 incorporated; small optimisation for calling bootstrap_inherit() and documentation enhancements.

  • Encode upgraded to version 2.12

    • A coderef is now acceptable for CHECK!

    • 3 new characters added to the ISO-8859-7 encoding

    • New encoding MIME-Header-ISO_2022_JP added

    • Problem with partial characters and encoding(utf-8-strict) fixed.

    • Documentation enhancements and typo fixes

  • English upgraded to version 1.02

    • the $COMPILING variable has been added

  • ExtUtils::Constant upgraded to version 0.17

    • Improved compatibility with older versions of perl

  • ExtUtils::MakeMaker upgraded to version 6.30 (was 6.17)

    • Too much to list here; see http://search.cpan.org/src/MSCHWERN/ExtUtils-MakeMaker-6.30/Changes

  • File::Basename upgraded to version 2.74, with changes contributed by Michael Schwern.

    • Documentation clarified and errors corrected.

    • basename now strips trailing path separators before processing the name.

    • basename now returns / for parameter /, to make basename consistent with the shell utility of the same name.

    • The suffix is no longer stripped if it is identical to the remaining characters in the name, again for consistency with the shell utility.

    • Some internal code cleanup.

  • File::Copy upgraded to version 2.09

    • Copying a file onto itself used to fail.

    • Moving a file between file systems now preserves the access and modification time stamps

  • File::Find upgraded to version 1.10

    • Win32 portability fixes

    • Enhanced documentation

  • File::Glob upgraded to version 1.05

    • Internal cleanup

  • File::Path upgraded to version 1.08

    • mkpath now preserves errno when mkdir fails

  • File::Spec upgraded to version 3.12

    • File::Spec-rootdir()> now returns \ on Win32, instead of /

    • $^O could sometimes become tainted. This has been fixed.

    • canonpath on Win32 now collapses foo/.. (or foo\..) sections correctly, rather than doing the "misguided" work it was previously doing. Note that canonpath on Unix still does not collapse these sections, as doing so would be incorrect.

    • Some documentation improvements

    • Some internal code cleanup

  • FileCache upgraded to version 1.06

    • POD formatting errors in the documentation fixed

  • Filter::Simple upgraded to version 0.82

  • FindBin upgraded to version 1.47

    • Now works better with directories where access rights are more restrictive than usual.

  • GDBM_File upgraded to version 1.08

    • Internal cleanup

  • Getopt::Long upgraded to version 2.35

    • prefix_pattern has now been complemented by a new configuration option long_prefix_pattern that allows the user to specify what prefix patterns should have long option style semantics applied.

    • Options can now take multiple values at once (experimental)

    • Various bug fixes

  • if upgraded to version 0.05

    • Give more meaningful error messages from if when invoked with a condition in list context.

    • Restore backwards compatibility with earlier versions of perl

  • IO upgraded to version 1.22

    • Enhanced documentation

    • Internal cleanup

  • IPC::Open2 upgraded to version 1.02

    • Enhanced documentation

  • IPC::Open3 upgraded to version 1.02

    • Enhanced documentation

  • List::Util upgraded to version 1.18 (was 1.14)

    • Fix pure-perl version of refaddr to avoid blessing an un-blessed reference

    • Use XSLoader for faster loading

    • Fixed various memory leaks

    • Internal cleanup and portability fixes

  • Math::Complex upgraded to version 1.35

    • atan2(0, i) now works, as do all the (computable) complex argument cases

    • Fixes for certain bugs in make and emake

    • Support returning the kth root directly

    • Support [2,-3pi/8] in emake

    • Support inf for make/emake

    • Document make/emake more visibly

  • Math::Trig upgraded to version 1.03

    • Add more great circle routines: great_circle_waypoint and great_circle_destination

  • MIME::Base64 upgraded to version 3.07

    • Use XSLoader for faster loading

    • Enhanced documentation

    • Internal cleanup

  • NDBM_File upgraded to version 1.06

    • Enhanced documentation

  • ODBM_File upgraded to version 1.06

    • Documentation typo fixed

    • Internal cleanup

  • Opcode upgraded to version 1.06

    • Enhanced documentation

    • Internal cleanup

  • open upgraded to version 1.05

    • Enhanced documentation

  • overload upgraded to version 1.04

    • Enhanced documentation

  • PerlIO upgraded to version 1.04

    • PerlIO::via iterate over layers properly now

    • PerlIO::scalar understands $/ = "" now

    • encoding(utf-8-strict) with partial characters now works

    • Enhanced documentation

    • Internal cleanup

  • Pod::Functions upgraded to version 1.03

    • Documentation typos fixed

  • Pod::Html upgraded to version 1.0504

    • HTML output will now correctly link to =items on the same page, and should be valid XHTML.

    • Variable names are recognized as intended

    • Documentation typos fixed

  • Pod::Parser upgraded to version 1.32

    • Allow files that start with =head on the first line

    • Win32 portability fix

    • Exit status of pod2usage fixed

    • New -noperldoc switch for pod2usage

    • Arbitrary URL schemes now allowed

    • Documentation typos fixed

  • POSIX upgraded to version 1.09

    • Documentation typos fixed

    • Internal cleanup

  • re upgraded to version 0.05

    • Documentation typo fixed

  • Safe upgraded to version 2.12

    • Minor documentation enhancement

  • SDBM_File upgraded to version 1.05

    • Documentation typo fixed

    • Internal cleanup

  • Socket upgraded to version 1.78

    • Internal cleanup

  • Storable upgraded to version 2.15

    • This includes the STORABLE_attach hook functionality added by Adam Kennedy, and more frugal memory requirements when storing under ithreads, by using the ithreads cloning tracking code.

  • Switch upgraded to version 2.10_01

    • Documentation typos fixed

  • Sys::Syslog upgraded to version 0.13

    • Now provides numeric macros and meaningful Exporter tags.

    • No longer uses Sys::Hostname as it may provide useless values in unconfigured network environments, so instead uses INADDR_LOOPBACK directly.

    • syslog() now uses local timestamp.

    • setlogmask() now behaves like its C counterpart.

    • setlogsock() will now croak() as documented.

    • Improved error and warnings messages.

    • Improved documentation.

  • Term::ANSIColor upgraded to version 1.10

    • Fixes a bug in colored when $EACHLINE is set that caused it to not color lines consisting solely of 0 (literal zero).

    • Improved tests.

  • Term::ReadLine upgraded to version 1.02

    • Documentation tweaks

  • Test::Harness upgraded to version 2.56 (was 2.48)

    • The Test::Harness timer is now off by default.

    • Now shows elapsed time in milliseconds.

    • Various bug fixes

  • Test::Simple upgraded to version 0.62 (was 0.54)

    • is_deeply() no longer fails to work for many cases

    • Various minor bug fixes

    • Documentation enhancements

  • Text::Tabs upgraded to version 2005.0824

    • Provides a faster implementation of expand

  • Text::Wrap upgraded to version 2005.082401

    • Adds $Text::Wrap::separator2, which allows you to preserve existing newlines but add line-breaks with some other string.

  • threads upgraded to version 1.07

    • threads will now honour no warnings 'threads'

    • A thread's interpreter is now freed after $t->join() rather than after undef $t, which should fix some ithreads memory leaks. (Fixed by Dave Mitchell)

    • Some documentation typo fixes.

  • threads::shared upgraded to version 0.94

    • Documentation changes only

    • Note: An improved implementation of threads::shared is available on CPAN - this will be merged into 5.8.9 if it proves stable.

  • Tie::Hash upgraded to version 1.02

    • Documentation typo fixed

  • Time::HiRes upgraded to version 1.86 (was 1.66)

    • clock_nanosleep() and clock() functions added

    • Support for the POSIX clock_gettime() and clock_getres() has been added

    • Return undef or an empty list if the C gettimeofday() function fails

    • Improved nanosleep detection

    • Internal cleanup

    • Enhanced documentation

  • Unicode::Collate upgraded to version 0.52

    • Now implements UCA Revision 14 (based on Unicode 4.1.0).

    • Unicode::Collate-new> method no longer overwrites user's $_

    • Enhanced documentation

  • Unicode::UCD upgraded to version 0.24

    • Documentation typos fixed

  • User::grent upgraded to version 1.01

    • Documentation typo fixed

  • utf8 upgraded to version 1.06

    • Documentation typos fixed

  • vmsish upgraded to version 1.02

    • Documentation typos fixed

  • warnings upgraded to version 1.05

    • Gentler messing with Carp:: internals

    • Internal cleanup

    • Documentation update

  • Win32 upgraded to version 0.2601

    • Provides Windows Vista support to Win32::GetOSName

    • Documentation enhancements

  • XS::Typemap upgraded to version 0.02

    • Internal cleanup

Utility Changes

h2xs enhancements

h2xs implements new option --use-xsloader to force use of XSLoader even in backwards compatible modules.

The handling of authors' names that had apostrophes has been fixed.

Any enums with negative values are now skipped.

perlivp enhancements

perlivp implements new option -a and will not check for *.ph files by default any more. Use the -a option to run all tests.

New Documentation

The the perlglossary manpage manpage is a glossary of terms used in the Perl documentation, technical and otherwise, kindly provided by O'Reilly Media, inc.

Performance Enhancements

  • Weak reference creation is now O(1) rather than O(n), courtesy of Nicholas Clark. Weak reference deletion remains O(n), but if deletion only happens at program exit, it may be skipped completely.

  • Salvador Fandiño provided improvements to reduce the memory usage of sort and to speed up some cases.

  • Jarkko Hietaniemi and Andy Lester worked to mark as much data as possible in the C source files as static, to increase the proportion of the executable file that the operating system can share between process, and thus reduce real memory usage on multi-user systems.

Installation and Configuration Improvements

Parallel makes should work properly now, although there may still be problems if make test is instructed to run in parallel.

Building with Borland's compilers on Win32 should work more smoothly. In particular Steve Hay has worked to side step many warnings emitted by their compilers and at least one C compiler internal error.

Configure will now detect clearenv and unsetenv, thanks to a patch from Alan Burlison. It will also probe for futimes and whether sprintf correctly returns the length of the formatted string, which will both be used in perl 5.8.9.

There are improved hints for next-3.0, vmesa, IX, Darwin, Solaris, Linux, DEC/OSF, HP-UX and MPE/iX

Perl extensions on Windows now can be statically built into the Perl DLL, thanks to a work by Vadim Konovalov. (This improvement was actually in 5.8.7, but was accidentally omitted from the perl587delta manpage).

Selected Bug Fixes

no warnings 'category' works correctly with -w

Previously when running with warnings enabled globally via -w, selective disabling of specific warning categories would actually turn off all warnings. This is now fixed; now no warnings 'io'; will only turn off warnings in the io class. Previously it would erroneously turn off all warnings.

This bug fix may cause some programs to start correctly issuing warnings.

Remove over-optimisation

Perl 5.8.4 introduced a change so that assignments of undef to a scalar, or of an empty list to an array or a hash, were optimised away. As this could cause problems when goto jumps were involved, this change has been backed out.

sprintf() fixes

Using the sprintf() function with some formats could lead to a buffer overflow in some specific cases. This has been fixed, along with several other bugs, notably in bounds checking.

In related fixes, it was possible for badly written code that did not follow the documentation of Sys::Syslog to have formatting vulnerabilities. Sys::Syslog has been changed to protect people from poor quality third party code.

Debugger and Unicode slowdown

It had been reported that running under perl's debugger when processing Unicode data could cause unexpectedly large slowdowns. The most likely cause of this was identified and fixed by Nicholas Clark.

Smaller fixes

  • FindBin now works better with directories where access rights are more restrictive than usual.

  • Several memory leaks in ithreads were closed. An improved implementation of threads::shared is available on CPAN - this will be merged into 5.8.9 if it proves stable.

  • Trailing spaces are now trimmed from $! and $^E.

  • Operations that require perl to read a process' list of groups, such as reads of $( and $), now dynamically allocate memory rather than using a fixed sized array. The fixed size array could cause C stack exhaustion on systems configured to use large numbers of groups.

  • PerlIO::scalar now works better with non-default $/ settings.

  • You can now use the x operator to repeat a qw// list. This used to raise a syntax error.

  • The debugger now traces correctly execution in eval("")uated code that contains #line directives.

  • The value of the open pragma is no longer ignored for three-argument opens.

  • The optimisation of for (reverse @a) introduced in perl 5.8.6 could misbehave when the array had undefined elements and was used in LVALUE context. Dave Mitchell provided a fix.

  • Some case insensitive matches between UTF-8 encoded data and 8 bit regexps, and vice versa, could give malformed character warnings. These have been fixed by Dave Mitchell and Yves Orton.

  • lcfirst and ucfirst could corrupt the string for certain cases where the length UTF-8 encoding of the string in lower case, upper case or title case differed. This was fixed by Nicholas Clark.

  • Perl will now use the C library calls unsetenv and clearenv if present to delete keys from %ENV and delete %ENV entirely, thanks to a patch from Alan Burlison.

New or Changed Diagnostics

Attempt to set length of freed array

This is a new warning, produced in situations such as this:

    $r = do {my @a; \$#a};
    $$r = 503;

Non-string passed as bitmask

This is a new warning, produced when number has been passed as a argument to select(), instead of a bitmask.

    # Wrong, will now warn
    $rin = fileno(STDIN);
    ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);

    # Should be
    $rin = '';
    vec($rin,fileno(STDIN),1) = 1;
    ($nfound,$timeleft) = select($rout=$rin, undef, undef, $timeout);

Search pattern not terminated or ternary operator parsed as search pattern

This syntax error indicates that the lexer couldn't find the final delimiter of a ?PATTERN? construct. Mentioning the ternary operator in this error message makes it easier to diagnose syntax errors.

Changed Internals

There has been a fair amount of refactoring of the C source code, partly to make it tidier and more maintainable. The resulting object code and the perl binary may well be smaller than 5.8.7, in particular due to a change contributed by Dave Mitchell which reworked the warnings code to be significantly smaller. Apart from being smaller and possibly faster, there should be no user-detectable changes.

Andy Lester supplied many improvements to determine which function parameters and local variables could actually be declared const to the C compiler. Steve Peters provided new *_set macros and reworked the core to use these rather than assigning to macros in LVALUE context.

Dave Mitchell improved the lexer debugging output under -DT

Nicholas Clark changed the string buffer allocation so that it is now rounded up to the next multiple of 4 (or 8 on platforms with 64 bit pointers). This should reduce the number of calls to realloc without actually using any extra memory.

The HV's array of HE*s is now allocated at the correct (minimal) size, thanks to another change by Nicholas Clark. Compile with -DPERL_USE_LARGE_HV_ALLOC to use the old, sloppier, default.

For XS or embedding debugging purposes, if perl is compiled with -DDEBUG_LEAKING_SCALARS_FORK_DUMP in addition to -DDEBUG_LEAKING_SCALARS then a child process is forked just before global destruction, which is used to display the values of any scalars found to have leaked at the end of global destruction. Without this, the scalars have already been freed sufficiently at the point of detection that it is impossible to produce any meaningful dump of their contents. This feature was implemented by the indefatigable Nicholas Clark, based on an idea by Mike Giroux.

Platform Specific Problems

The optimiser on HP-UX 11.23 (Itanium 2) is currently partly disabled (scaled down to +O1) when using HP C-ANSI-C; the cause of problems at higher optimisation levels is still unclear.

There are a handful of remaining test failures on VMS, mostly due to test fixes and minor module tweaks with too many dependencies to integrate into this release from the development stream, where they have all been corrected. The following is a list of expected failures with the patch number of the fix where that is known:

    ext/Devel/PPPort/t/ppphtest.t  #26913
    ext/List/Util/t/p_tainted.t    #26912
    lib/ExtUtils/t/PL_FILES.t      #26813
    lib/ExtUtils/t/basic.t         #26813
    t/io/fs.t
    t/op/cmp.t

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl5004delta - what's new for perl5.004

  • Supported Environments
  • Core Changes
    • List assignment to %ENV works
    • Change to "Can't locate Foo.pm in @INC" error
    • Compilation option: Binary compatibility with 5.003
    • $PERL5OPT environment variable
    • Limitations on -M, -m, and -T options
    • More precise warnings
    • Deprecated: Inherited AUTOLOAD for non-methods
    • Previously deprecated %OVERLOAD is no longer usable
    • Subroutine arguments created only when they're modified
    • Group vector changeable with $)
    • Fixed parsing of $$<digit>, &$<digit>, etc.
    • Fixed localization of $<digit>, $&, etc.
    • No resetting of $. on implicit close
    • wantarray may return undef
    • eval EXPR determines value of EXPR in scalar context
    • Changes to tainting checks
    • New Opcode module and revised Safe module
    • Embedding improvements
    • Internal change: FileHandle class based on IO::* classes
    • Internal change: PerlIO abstraction interface
    • New and changed syntax
    • New and changed builtin constants
    • New and changed builtin variables
    • New and changed builtin functions
    • New builtin methods
    • TIEHANDLE now supported
    • Malloc enhancements
    • Miscellaneous efficiency enhancements
  • Support for More Operating Systems
    • Win32
    • Plan 9
    • QNX
    • AmigaOS
  • Pragmata
  • Modules
    • Required Updates
    • Installation directories
    • Module information summary
    • Fcntl
    • IO
    • Math::Complex
    • Math::Trig
    • DB_File
    • Net::Ping
    • Object-oriented overrides for builtin operators
  • Utility Changes
    • pod2html
    • xsubpp
  • C Language API Changes
  • Documentation Changes
  • New Diagnostics
  • BUGS
  • SEE ALSO
  • HISTORY

NAME

perl5004delta - what's new for perl5.004

DESCRIPTION

This document describes differences between the 5.003 release (as documented in Programming Perl, second edition--the Camel Book) and this one.

Supported Environments

Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2, QNX, AmigaOS, and Windows NT. Perl runs on Windows 95 as well, but it cannot be built there, for lack of a reasonable command interpreter.

Core Changes

Most importantly, many bugs were fixed, including several security problems. See the Changes file in the distribution for details.

List assignment to %ENV works

%ENV = () and %ENV = @list now work as expected (except on VMS where it generates a fatal error).

Change to "Can't locate Foo.pm in @INC" error

The error "Can't locate Foo.pm in @INC" now lists the contents of @INC for easier debugging.

Compilation option: Binary compatibility with 5.003

There is a new Configure question that asks if you want to maintain binary compatibility with Perl 5.003. If you choose binary compatibility, you do not have to recompile your extensions, but you might have symbol conflicts if you embed Perl in another application, just as in the 5.003 release. By default, binary compatibility is preserved at the expense of symbol table pollution.

$PERL5OPT environment variable

You may now put Perl options in the $PERL5OPT environment variable. Unless Perl is running with taint checks, it will interpret this variable as if its contents had appeared on a "#!perl" line at the beginning of your script, except that hyphens are optional. PERL5OPT may only be used to set the following switches: -[DIMUdmw].

Limitations on -M, -m, and -T options

The -M and -m options are no longer allowed on the #! line of a script. If a script needs a module, it should invoke it with the use pragma.

The -T option is also forbidden on the #! line of a script, unless it was present on the Perl command line. Due to the way #! works, this usually means that -T must be in the first argument. Thus:

    #!/usr/bin/perl -T -w

will probably work for an executable script invoked as scriptname, while:

    #!/usr/bin/perl -w -T

will probably fail under the same conditions. (Non-Unix systems will probably not follow this rule.) But perl scriptname is guaranteed to fail, since then there is no chance of -T being found on the command line before it is found on the #! line.

More precise warnings

If you removed the -w option from your Perl 5.003 scripts because it made Perl too verbose, we recommend that you try putting it back when you upgrade to Perl 5.004. Each new perl version tends to remove some undesirable warnings, while adding new warnings that may catch bugs in your scripts.

Deprecated: Inherited AUTOLOAD for non-methods

Before Perl 5.004, AUTOLOAD functions were looked up as methods (using the @ISA hierarchy), even when the function to be autoloaded was called as a plain function (e.g. Foo::bar()), not a method (e.g. Foo->bar() or $obj->bar()).

Perl 5.005 will use method lookup only for methods' AUTOLOADs. However, there is a significant base of existing code that may be using the old behavior. So, as an interim step, Perl 5.004 issues an optional warning when a non-method uses an inherited AUTOLOAD.

The simple rule is: Inheritance will not work when autoloading non-methods. The simple fix for old code is: In any module that used to depend on inheriting AUTOLOAD for non-methods from a base class named BaseClass, execute *AUTOLOAD = \&BaseClass::AUTOLOAD during startup.

Previously deprecated %OVERLOAD is no longer usable

Using %OVERLOAD to define overloading was deprecated in 5.003. Overloading is now defined using the overload pragma. %OVERLOAD is still used internally but should not be used by Perl scripts. See the overload manpage for more details.

Subroutine arguments created only when they're modified

In Perl 5.004, nonexistent array and hash elements used as subroutine parameters are brought into existence only if they are actually assigned to (via @_).

Earlier versions of Perl vary in their handling of such arguments. Perl versions 5.002 and 5.003 always brought them into existence. Perl versions 5.000 and 5.001 brought them into existence only if they were not the first argument (which was almost certainly a bug). Earlier versions of Perl never brought them into existence.

For example, given this code:

     undef @a; undef %a;
     sub show { print $_[0] };
     sub change { $_[0]++ };
     show($a[2]);
     change($a{b});

After this code executes in Perl 5.004, $a{b} exists but $a[2] does not. In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed (but $a[2]'s value would have been undefined).

Group vector changeable with $)

The $) special variable has always (well, in Perl 5, at least) reflected not only the current effective group, but also the group list as returned by the getgroups() C function (if there is one). However, until this release, there has not been a way to call the setgroups() C function from Perl.

In Perl 5.004, assigning to $) is exactly symmetrical with examining it: The first number in its string value is used as the effective gid; if there are any numbers after the first one, they are passed to the setgroups() C function (if there is one).

Fixed parsing of $$<digit>, &$<digit>, etc.

Perl versions before 5.004 misinterpreted any type marker followed by "$" and a digit. For example, "$$0" was incorrectly taken to mean "${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.

However, the developers of Perl 5.004 could not fix this bug completely, because at least two widely-used modules depend on the old meaning of "$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the old (broken) way inside strings; but it generates this message as a warning. And in Perl 5.005, this special treatment will cease.

Fixed localization of $<digit>, $&, etc.

Perl versions before 5.004 did not always properly localize the regex-related special variables. Perl 5.004 does localize them, as the documentation has always said it should. This may result in $1, $2, etc. no longer being set where existing programs use them.

No resetting of $. on implicit close

The documentation for Perl 5.0 has always stated that $. is not reset when an already-open file handle is reopened with no intervening call to close. Due to a bug, perl versions 5.000 through 5.003 did reset $. under that circumstance; Perl 5.004 does not.

wantarray may return undef

The wantarray operator returns true if a subroutine is expected to return a list, and false otherwise. In Perl 5.004, wantarray can also return the undefined value if a subroutine's return value will not be used at all, which allows subroutines to avoid a time-consuming calculation of a return value if it isn't going to be used.

eval EXPR determines value of EXPR in scalar context

Perl (version 5) used to determine the value of EXPR inconsistently, sometimes incorrectly using the surrounding context for the determination. Now, the value of EXPR (before being parsed by eval) is always determined in a scalar context. Once parsed, it is executed as before, by providing the context that the scope surrounding the eval provided. This change makes the behavior Perl4 compatible, besides fixing bugs resulting from the inconsistent behavior. This program:

    @a = qw(time now is time);
    print eval @a;
    print '|', scalar eval @a;

used to print something like "timenowis881399109|4", but now (and in perl4) prints "4|4".

Changes to tainting checks

A bug in previous versions may have failed to detect some insecure conditions when taint checks are turned on. (Taint checks are used in setuid or setgid scripts, or when explicitly turned on with the -T invocation option.) Although it's unlikely, this may cause a previously-working script to now fail -- which should be construed as a blessing, since that indicates a potentially-serious security hole was just plugged.

The new restrictions when tainting include:

No glob() or <*>

These operators may spawn the C shell (csh), which cannot be made safe. This restriction will be lifted in a future version of Perl when globbing is implemented without the use of an external program.

No spawning if tainted $CDPATH, $ENV, $BASH_ENV

These environment variables may alter the behavior of spawned programs (especially shells) in ways that subvert security. So now they are treated as dangerous, in the manner of $IFS and $PATH.

No spawning if tainted $TERM doesn't look like a terminal name

Some termcap libraries do unsafe things with $TERM. However, it would be unnecessarily harsh to treat all $TERM values as unsafe, since only shell metacharacters can cause trouble in $TERM. So a tainted $TERM is considered to be safe if it contains only alphanumerics, underscores, dashes, and colons, and unsafe if it contains other characters (including whitespace).

New Opcode module and revised Safe module

A new Opcode module supports the creation, manipulation and application of opcode masks. The revised Safe module has a new API and is implemented using the new Opcode module. Please read the new Opcode and Safe documentation.

Embedding improvements

In older versions of Perl it was not possible to create more than one Perl interpreter instance inside a single process without leaking like a sieve and/or crashing. The bugs that caused this behavior have all been fixed. However, you still must take care when embedding Perl in a C program. See the updated perlembed manpage for tips on how to manage your interpreters.

Internal change: FileHandle class based on IO::* classes

File handles are now stored internally as type IO::Handle. The FileHandle module is still supported for backwards compatibility, but it is now merely a front end to the IO::* modules -- specifically, IO::Handle, IO::Seekable, and IO::File. We suggest, but do not require, that you use the IO::* modules in new code.

In harmony with this change, *GLOB{FILEHANDLE} is now just a backward-compatible synonym for *GLOB{IO}.

Internal change: PerlIO abstraction interface

It is now possible to build Perl with AT&T's sfio IO package instead of stdio. See the perlapio manpage for more details, and the INSTALL file for how to use it.

New and changed syntax

$coderef->(PARAMS)

A subroutine reference may now be suffixed with an arrow and a (possibly empty) parameter list. This syntax denotes a call of the referenced subroutine, with the given parameters (if any).

This new syntax follows the pattern of $hashref->{FOO} and $aryref->[$foo]: You may now write &$subref($foo) as $subref->($foo). All these arrow terms may be chained; thus, &{$table->{FOO}}($bar) may now be written $table->{FOO}->($bar).

New and changed builtin constants

__PACKAGE__

The current package name at compile time, or the undefined value if there is no current package (due to a package; directive). Like __FILE__ and __LINE__, __PACKAGE__ does not interpolate into strings.

New and changed builtin variables

$^E

Extended error message on some platforms. (Also known as $EXTENDED_OS_ERROR if you use English).

$^H

The current set of syntax checks enabled by use strict. See the documentation of strict for more details. Not actually new, but newly documented. Because it is intended for internal use by Perl core components, there is no use English long name for this variable.

$^M

By default, running out of memory it is not trappable. However, if compiled for this, Perl may use the contents of $^M as an emergency pool after die()ing with this message. Suppose that your Perl were compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then

    $^M = 'a' x (1<<16);

would allocate a 64K buffer for use when in emergency. See the INSTALL file for information on how to enable this option. As a disincentive to casual use of this advanced feature, there is no use English long name for this variable.

New and changed builtin functions

delete on slices

This now works. (e.g. delete @ENV{'PATH', 'MANPATH'})

flock

is now supported on more platforms, prefers fcntl to lockf when emulating, and always flushes before (un)locking.

printf and sprintf

Perl now implements these functions itself; it doesn't use the C library function sprintf() any more, except for floating-point numbers, and even then only known flags are allowed. As a result, it is now possible to know which conversions and flags will work, and what they will do.

The new conversions in Perl's sprintf() are:

   %i   a synonym for %d
   %p   a pointer (the address of the Perl value, in hexadecimal)
   %n   special: *stores* the number of characters output so far
        into the next variable in the parameter list

The new flags that go between the % and the conversion are:

   #    prefix octal with "0", hex with "0x"
   h    interpret integer as C type "short" or "unsigned short"
   V    interpret integer as Perl's standard integer type

Also, where a number would appear in the flags, an asterisk ("*") may be used instead, in which case Perl uses the next item in the parameter list as the given number (that is, as the field width or precision). If a field width obtained through "*" is negative, it has the same effect as the '-' flag: left-justification.

See sprintf in the perlfunc manpage for a complete list of conversion and flags.

keys as an lvalue

As an lvalue, keys allows you to increase the number of hash buckets allocated for the given hash. This can gain you a measure of efficiency if you know the hash is going to get big. (This is similar to pre-extending an array by assigning a larger number to $#array.) If you say

    keys %hash = 200;

then %hash will have at least 200 buckets allocated for it. These buckets will be retained even if you do %hash = (); use undef %hash if you want to free the storage while %hash is still in scope. You can't shrink the number of buckets allocated for the hash using keys in this way (but you needn't worry about doing this by accident, as trying has no effect).

my() in Control Structures

You can now use my() (with or without the parentheses) in the control expressions of control structures such as:

    while (defined(my $line = <>)) {
        $line = lc $line;
    } continue {
        print $line;
    }

    if ((my $answer = <STDIN>) =~ /^y(es)?$/i) {
        user_agrees();
    } elsif ($answer =~ /^n(o)?$/i) {
        user_disagrees();
    } else {
        chomp $answer;
        die "`$answer' is neither `yes' nor `no'";
    }

Also, you can declare a foreach loop control variable as lexical by preceding it with the word "my". For example, in:

    foreach my $i (1, 2, 3) {
        some_function();
    }

$i is a lexical variable, and the scope of $i extends to the end of the loop, but not beyond it.

Note that you still cannot use my() on global punctuation variables such as $_ and the like.

pack() and unpack()

A new format 'w' represents a BER compressed integer (as defined in ASN.1). Its format is a sequence of one or more bytes, each of which provides seven bits of the total value, with the most significant first. Bit eight of each byte is set, except for the last byte, in which bit eight is clear.

If 'p' or 'P' are given undef as values, they now generate a NULL pointer.

Both pack() and unpack() now fail when their templates contain invalid types. (Invalid types used to be ignored.)

sysseek()

The new sysseek() operator is a variant of seek() that sets and gets the file's system read/write position, using the lseek(2) system call. It is the only reliable way to seek before using sysread() or syswrite(). Its return value is the new position, or the undefined value on failure.

use VERSION

If the first argument to use is a number, it is treated as a version number instead of a module name. If the version of the Perl interpreter is less than VERSION, then an error message is printed and Perl exits immediately. Because use occurs at compile time, this check happens immediately during the compilation process, unlike require VERSION, which waits until runtime for the check. This is often useful if you need to check the current Perl version before useing library modules which have changed in incompatible ways from older versions of Perl. (We try not to do this more than we have to.)

use Module VERSION LIST

If the VERSION argument is present between Module and LIST, then the use will call the VERSION method in class Module with the given version as an argument. The default VERSION method, inherited from the UNIVERSAL class, croaks if the given version is larger than the value of the variable $Module::VERSION. (Note that there is not a comma after VERSION!)

This version-checking mechanism is similar to the one currently used in the Exporter module, but it is faster and can be used with modules that don't use the Exporter. It is the recommended method for new code.

prototype(FUNCTION)

Returns the prototype of a function as a string (or undef if the function has no prototype). FUNCTION is a reference to or the name of the function whose prototype you want to retrieve. (Not actually new; just never documented before.)

srand

The default seed for srand, which used to be time, has been changed. Now it's a heady mix of difficult-to-predict system-dependent values, which should be sufficient for most everyday purposes.

Previous to version 5.004, calling rand without first calling srand would yield the same sequence of random numbers on most or all machines. Now, when perl sees that you're calling rand and haven't yet called srand, it calls srand with the default seed. You should still call srand manually if your code might ever be run on a pre-5.004 system, of course, or if you want a seed other than the default.

$_ as Default

Functions documented in the Camel to default to $_ now in fact do, and all those that do are so documented in the perlfunc manpage.

m//gc does not reset search position on failure

The m//g match iteration construct has always reset its target string's search position (which is visible through the pos operator) when a match fails; as a result, the next m//g match after a failure starts again at the beginning of the string. With Perl 5.004, this reset may be disabled by adding the "c" (for "continue") modifier, i.e. m//gc. This feature, in conjunction with the \G zero-width assertion, makes it possible to chain matches together. See the perlop manpage and the perlre manpage.

m//x ignores whitespace before ?*+{}

The m//x construct has always been intended to ignore all unescaped whitespace. However, before Perl 5.004, whitespace had the effect of escaping repeat modifiers like "*" or "?"; for example, /a *b/x was (mis)interpreted as /a\*b/x. This bug has been fixed in 5.004.

nested sub{} closures work now

Prior to the 5.004 release, nested anonymous functions didn't work right. They do now.

formats work right on changing lexicals

Just like anonymous functions that contain lexical variables that change (like a lexical index variable for a foreach loop), formats now work properly. For example, this silently failed before (printed only zeros), but is fine now:

    my $i;
    foreach $i ( 1 .. 10 ) {
        write;
    }
    format =
        my i is @#
        $i
    .

However, it still fails (without a warning) if the foreach is within a subroutine:

    my $i;
    sub foo {
      foreach $i ( 1 .. 10 ) {
        write;
      }
    }
    foo;
    format =
        my i is @#
        $i
    .

New builtin methods

The UNIVERSAL package automatically contains the following methods that are inherited by all other classes:

isa(CLASS)

isa returns true if its object is blessed into a subclass of CLASS

isa is also exportable and can be called as a sub with two arguments. This allows the ability to check what a reference points to. Example:

    use UNIVERSAL qw(isa);

    if(isa($ref, 'ARRAY')) {
       ...
    }
can(METHOD)

can checks to see if its object has a method called METHOD, if it does then a reference to the sub is returned; if it does not then undef is returned.

VERSION( [NEED] )

VERSION returns the version number of the class (package). If the NEED argument is given then it will check that the current version (as defined by the $VERSION variable in the given package) not less than NEED; it will die if this is not the case. This method is normally called as a class method. This method is called automatically by the VERSION form of use.

    use A 1.2 qw(some imported subs);
    # implies:
    A->VERSION(1.2);

NOTE: can directly uses Perl's internal code for method lookup, and isa uses a very similar method and caching strategy. This may cause strange effects if the Perl code dynamically changes @ISA in any package.

You may add other methods to the UNIVERSAL class via Perl or XS code. You do not need to use UNIVERSAL in order to make these methods available to your program. This is necessary only if you wish to have isa available as a plain subroutine in the current package.

TIEHANDLE now supported

See the perltie manpage for other kinds of tie()s.

TIEHANDLE classname, LIST

This is the constructor for the class. That means it is expected to return an object of some sort. The reference can be used to hold some internal information.

    sub TIEHANDLE {
        print "<shout>\n";
        my $i;
        return bless \$i, shift;
    }
PRINT this, LIST

This method will be triggered every time the tied handle is printed to. Beyond its self reference it also expects the list that was passed to the print function.

    sub PRINT {
        $r = shift;
        $$r++;
        return print join( $, => map {uc} @_), $\;
    }
PRINTF this, LIST

This method will be triggered every time the tied handle is printed to with the printf() function. Beyond its self reference it also expects the format and list that was passed to the printf function.

    sub PRINTF {
        shift;
          my $fmt = shift;
        print sprintf($fmt, @_)."\n";
    }
READ this LIST

This method will be called when the handle is read from via the read or sysread functions.

    sub READ {
        $r = shift;
        my($buf,$len,$offset) = @_;
        print "READ called, \$buf=$buf, \$len=$len, \$offset=$offset";
    }
READLINE this

This method will be called when the handle is read from. The method should return undef when there is no more data.

    sub READLINE {
        $r = shift;
        return "PRINT called $$r times\n"
    }
GETC this

This method will be called when the getc function is called.

    sub GETC { print "Don't GETC, Get Perl"; return "a"; }
DESTROY this

As with the other types of ties, this method will be called when the tied handle is about to be destroyed. This is useful for debugging and possibly for cleaning up.

    sub DESTROY {
        print "</shout>\n";
    }

Malloc enhancements

If perl is compiled with the malloc included with the perl distribution (that is, if perl -V:d_mymalloc is 'define') then you can print memory statistics at runtime by running Perl thusly:

  env PERL_DEBUG_MSTATS=2 perl your_script_here

The value of 2 means to print statistics after compilation and on exit; with a value of 1, the statistics are printed only on exit. (If you want the statistics at an arbitrary time, you'll need to install the optional module Devel::Peek.)

Three new compilation flags are recognized by malloc.c. (They have no effect if perl is compiled with system malloc().)

-DPERL_EMERGENCY_SBRK

If this macro is defined, running out of memory need not be a fatal error: a memory pool can allocated by assigning to the special variable $^M. See $^M.

-DPACK_MALLOC

Perl memory allocation is by bucket with sizes close to powers of two. Because of these malloc overhead may be big, especially for data of size exactly a power of two. If PACK_MALLOC is defined, perl uses a slightly different algorithm for small allocations (up to 64 bytes long), which makes it possible to have overhead down to 1 byte for allocations which are powers of two (and appear quite often).

Expected memory savings (with 8-byte alignment in alignbytes) is about 20% for typical Perl usage. Expected slowdown due to additional malloc overhead is in fractions of a percent (hard to measure, because of the effect of saved memory on speed).

-DTWO_POT_OPTIMIZE

Similarly to PACK_MALLOC, this macro improves allocations of data with size close to a power of two; but this works for big allocations (starting with 16K by default). Such allocations are typical for big hashes and special-purpose scripts, especially image processing.

On recent systems, the fact that perl requires 2M from system for 1M allocation will not affect speed of execution, since the tail of such a chunk is not going to be touched (and thus will not require real memory). However, it may result in a premature out-of-memory error. So if you will be manipulating very large blocks with sizes close to powers of two, it would be wise to define this macro.

Expected saving of memory is 0-100% (100% in applications which require most memory in such 2**n chunks); expected slowdown is negligible.

Miscellaneous efficiency enhancements

Functions that have an empty prototype and that do nothing but return a fixed value are now inlined (e.g. sub PI () { 3.14159 }).

Each unique hash key is only allocated once, no matter how many hashes have an entry with that key. So even if you have 100 copies of the same hash, the hash keys never have to be reallocated.

Support for More Operating Systems

Support for the following operating systems is new in Perl 5.004.

Win32

Perl 5.004 now includes support for building a "native" perl under Windows NT, using the Microsoft Visual C++ compiler (versions 2.0 and above) or the Borland C++ compiler (versions 5.02 and above). The resulting perl can be used under Windows 95 (if it is installed in the same directory locations as it got installed in Windows NT). This port includes support for perl extension building tools like the MakeMaker manpage and h2xs, so that many extensions available on the Comprehensive Perl Archive Network (CPAN) can now be readily built under Windows NT. See http://www.perl.com/ for more information on CPAN and README.win32 in the perl distribution for more details on how to get started with building this port.

There is also support for building perl under the Cygwin32 environment. Cygwin32 is a set of GNU tools that make it possible to compile and run many Unix programs under Windows NT by providing a mostly Unix-like interface for compilation and execution. See README.cygwin32 in the perl distribution for more details on this port and how to obtain the Cygwin32 toolkit.

Plan 9

See README.plan9 in the perl distribution.

QNX

See README.qnx in the perl distribution.

AmigaOS

See README.amigaos in the perl distribution.

Pragmata

Six new pragmatic modules exist:

use autouse MODULE => qw(sub1 sub2 sub3)

Defers require MODULE until someone calls one of the specified subroutines (which must be exported by MODULE). This pragma should be used with caution, and only when necessary.

use blib
use blib 'dir'

Looks for MakeMaker-like 'blib' directory structure starting in dir (or current directory) and working back up to five levels of parent directories.

Intended for use on command line with -M option as a way of testing arbitrary scripts against an uninstalled version of a package.

use constant NAME => VALUE

Provides a convenient interface for creating compile-time constants, See Constant Functions in the perlsub manpage.

use locale

Tells the compiler to enable (or disable) the use of POSIX locales for builtin operations.

When use locale is in effect, the current LC_CTYPE locale is used for regular expressions and case mapping; LC_COLLATE for string ordering; and LC_NUMERIC for numeric formatting in printf and sprintf (but not in print). LC_NUMERIC is always used in write, since lexical scoping of formats is problematic at best.

Each use locale or no locale affects statements to the end of the enclosing BLOCK or, if not inside a BLOCK, to the end of the current file. Locales can be switched and queried with POSIX::setlocale().

See the perllocale manpage for more information.

use ops

Disable unsafe opcodes, or any named opcodes, when compiling Perl code.

use vmsish

Enable VMS-specific language features. Currently, there are three VMS-specific features available: 'status', which makes $? and system return genuine VMS status values instead of emulating POSIX; 'exit', which makes exit take a genuine VMS status value instead of assuming that exit 1 is an error; and 'time', which makes all times relative to the local time zone, in the VMS tradition.

Modules

Required Updates

Though Perl 5.004 is compatible with almost all modules that work with Perl 5.003, there are a few exceptions:

    Module   Required Version for Perl 5.004
    ------   -------------------------------
    Filter   Filter-1.12
    LWP      libwww-perl-5.08
    Tk       Tk400.202 (-w makes noise)

Also, the majordomo mailing list program, version 1.94.1, doesn't work with Perl 5.004 (nor with perl 4), because it executes an invalid regular expression. This bug is fixed in majordomo version 1.94.2.

Installation directories

The installperl script now places the Perl source files for extensions in the architecture-specific library directory, which is where the shared libraries for extensions have always been. This change is intended to allow administrators to keep the Perl 5.004 library directory unchanged from a previous version, without running the risk of binary incompatibility between extensions' Perl source and shared libraries.

Module information summary

Brand new modules, arranged by topic rather than strictly alphabetically:

    CGI.pm               Web server interface ("Common Gateway Interface")
    CGI/Apache.pm        Support for Apache's Perl module
    CGI/Carp.pm          Log server errors with helpful context
    CGI/Fast.pm          Support for FastCGI (persistent server process)
    CGI/Push.pm          Support for server push
    CGI/Switch.pm        Simple interface for multiple server types
    CPAN                 Interface to Comprehensive Perl Archive Network
    CPAN::FirstTime      Utility for creating CPAN configuration file
    CPAN::Nox            Runs CPAN while avoiding compiled extensions
    IO.pm                Top-level interface to IO::* classes
    IO/File.pm           IO::File extension Perl module
    IO/Handle.pm         IO::Handle extension Perl module
    IO/Pipe.pm           IO::Pipe extension Perl module
    IO/Seekable.pm       IO::Seekable extension Perl module
    IO/Select.pm         IO::Select extension Perl module
    IO/Socket.pm         IO::Socket extension Perl module
    Opcode.pm            Disable named opcodes when compiling Perl code
    ExtUtils/Embed.pm    Utilities for embedding Perl in C programs
    ExtUtils/testlib.pm  Fixes up @INC to use just-built extension
    FindBin.pm           Find path of currently executing program
    Class/Struct.pm      Declare struct-like datatypes as Perl classes
    File/stat.pm         By-name interface to Perl's builtin stat
    Net/hostent.pm       By-name interface to Perl's builtin gethost*
    Net/netent.pm        By-name interface to Perl's builtin getnet*
    Net/protoent.pm      By-name interface to Perl's builtin getproto*
    Net/servent.pm       By-name interface to Perl's builtin getserv*
    Time/gmtime.pm       By-name interface to Perl's builtin gmtime
    Time/localtime.pm    By-name interface to Perl's builtin localtime
    Time/tm.pm           Internal object for Time::{gm,local}time
    User/grent.pm        By-name interface to Perl's builtin getgr*
    User/pwent.pm        By-name interface to Perl's builtin getpw*

    Tie/RefHash.pm       Base class for tied hashes with references as keys
    UNIVERSAL.pm         Base class for *ALL* classes

Fcntl

New constants in the existing Fcntl modules are now supported, provided that your operating system happens to support them:

    F_GETOWN F_SETOWN
    O_ASYNC O_DEFER O_DSYNC O_FSYNC O_SYNC
    O_EXLOCK O_SHLOCK

These constants are intended for use with the Perl operators sysopen() and fcntl() and the basic database modules like SDBM_File. For the exact meaning of these and other Fcntl constants please refer to your operating system's documentation for fcntl() and open().

In addition, the Fcntl module now provides these constants for use with the Perl operator flock():

        LOCK_SH LOCK_EX LOCK_NB LOCK_UN

These constants are defined in all environments (because where there is no flock() system call, Perl emulates it). However, for historical reasons, these constants are not exported unless they are explicitly requested with the ":flock" tag (e.g. use Fcntl ':flock').

IO

The IO module provides a simple mechanism to load all the IO modules at one go. Currently this includes:

     IO::Handle
     IO::Seekable
     IO::File
     IO::Pipe
     IO::Socket

For more information on any of these modules, please see its respective documentation.

Math::Complex

The Math::Complex module has been totally rewritten, and now supports more operations. These are overloaded:

     + - * / ** <=> neg ~ abs sqrt exp log sin cos atan2 "" (stringify)

And these functions are now exported:

    pi i Re Im arg
    log10 logn ln cbrt root
    tan
    csc sec cot
    asin acos atan
    acsc asec acot
    sinh cosh tanh
    csch sech coth
    asinh acosh atanh
    acsch asech acoth
    cplx cplxe

Math::Trig

This new module provides a simpler interface to parts of Math::Complex for those who need trigonometric functions only for real numbers.

DB_File

There have been quite a few changes made to DB_File. Here are a few of the highlights:

  • Fixed a handful of bugs.

  • By public demand, added support for the standard hash function exists().

  • Made it compatible with Berkeley DB 1.86.

  • Made negative subscripts work with RECNO interface.

  • Changed the default flags from O_RDWR to O_CREAT|O_RDWR and the default mode from 0640 to 0666.

  • Made DB_File automatically import the open() constants (O_RDWR, O_CREAT etc.) from Fcntl, if available.

  • Updated documentation.

Refer to the HISTORY section in DB_File.pm for a complete list of changes. Everything after DB_File 1.01 has been added since 5.003.

Net::Ping

Major rewrite - support added for both udp echo and real icmp pings.

Object-oriented overrides for builtin operators

Many of the Perl builtins returning lists now have object-oriented overrides. These are:

    File::stat
    Net::hostent
    Net::netent
    Net::protoent
    Net::servent
    Time::gmtime
    Time::localtime
    User::grent
    User::pwent

For example, you can now say

    use File::stat;
    use User::pwent;
    $his = (stat($filename)->st_uid == pwent($whoever)->pw_uid);

Utility Changes

pod2html

Sends converted HTML to standard output

The pod2html utility included with Perl 5.004 is entirely new. By default, it sends the converted HTML to its standard output, instead of writing it to a file like Perl 5.003's pod2html did. Use the --outfile=FILENAME option to write to a file.

xsubpp

void XSUBs now default to returning nothing

Due to a documentation/implementation bug in previous versions of Perl, XSUBs with a return type of void have actually been returning one value. Usually that value was the GV for the XSUB, but sometimes it was some already freed or reused value, which would sometimes lead to program failure.

In Perl 5.004, if an XSUB is declared as returning void, it actually returns no value, i.e. an empty list (though there is a backward-compatibility exception; see below). If your XSUB really does return an SV, you should give it a return type of SV *.

For backward compatibility, xsubpp tries to guess whether a void XSUB is really void or if it wants to return an SV *. It does so by examining the text of the XSUB: if xsubpp finds what looks like an assignment to ST(0), it assumes that the XSUB's return type is really SV *.

C Language API Changes

gv_fetchmethod and perl_call_sv

The gv_fetchmethod function finds a method for an object, just like in Perl 5.003. The GV it returns may be a method cache entry. However, in Perl 5.004, method cache entries are not visible to users; therefore, they can no longer be passed directly to perl_call_sv. Instead, you should use the GvCV macro on the GV to extract its CV, and pass the CV to perl_call_sv.

The most likely symptom of passing the result of gv_fetchmethod to perl_call_sv is Perl's producing an "Undefined subroutine called" error on the second call to a given method (since there is no cache on the first call).

perl_eval_pv

A new function handy for eval'ing strings of Perl code inside C code. This function returns the value from the eval statement, which can be used instead of fetching globals from the symbol table. See the perlguts manpage, the perlembed manpage and the perlcall manpage for details and examples.

Extended API for manipulating hashes

Internal handling of hash keys has changed. The old hashtable API is still fully supported, and will likely remain so. The additions to the API allow passing keys as SV*s, so that tied hashes can be given real scalars as keys rather than plain strings (nontied hashes still can only use strings as keys). New extensions must use the new hash access functions and macros if they wish to use SV* keys. These additions also make it feasible to manipulate HE*s (hash entries), which can be more efficient. See the perlguts manpage for details.

Documentation Changes

Many of the base and library pods were updated. These new pods are included in section 1:

the perldelta manpage

This document.

the perlfaq manpage

Frequently asked questions.

the perllocale manpage

Locale support (internationalization and localization).

the perltoot manpage

Tutorial on Perl OO programming.

the perlapio manpage

Perl internal IO abstraction interface.

the perlmodlib manpage

Perl module library and recommended practice for module creation. Extracted from the perlmod manpage (which is much smaller as a result).

the perldebug manpage

Although not new, this has been massively updated.

the perlsec manpage

Although not new, this has been massively updated.

New Diagnostics

Several new conditions will trigger warnings that were silent before. Some only affect certain platforms. The following new warnings and errors outline these. These messages are classified as follows (listed in increasing order of desperation):

   (W) A warning (optional).
   (D) A deprecation (optional).
   (S) A severe warning (mandatory).
   (F) A fatal error (trappable).
   (P) An internal error you should never see (trappable).
   (X) A very fatal error (nontrappable).
   (A) An alien error message (not generated by Perl).
"my" variable %s masks earlier declaration in same scope

(W) A lexical variable has been redeclared in the same scope, effectively eliminating all access to the previous instance. This is almost always a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed.

%s argument is not a HASH element or slice

(F) The argument to delete() must be either a hash element, such as

    $foo{$bar}
    $ref->[12]->{"susie"}

or a hash slice, such as

    @foo{$bar, $baz, $xyzzy}
    @{$ref->[12]}{"susie", "queue"}
Allocation too large: %lx

(X) You can't allocate more than 64K on an MS-DOS machine.

Allocation too large

(F) You can't allocate more than 2^31+"small amount" bytes.

Applying %s to %s will act on scalar(%s)

(W) The pattern match (//), substitution (s///), and transliteration (tr///) operators work on scalar values. If you apply one of them to an array or a hash, it will convert the array or hash to a scalar value -- the length of an array, or the population info of a hash -- and then work on that scalar value. This is probably not what you meant to do. See grep in the perlfunc manpage and map in the perlfunc manpage for alternatives.

Attempt to free nonexistent shared string

(P) Perl maintains a reference counted internal table of strings to optimize the storage and access of hash keys and other strings. This indicates someone tried to decrement the reference count of a string that can no longer be found in the table.

Attempt to use reference as lvalue in substr

(W) You supplied a reference as the first argument to substr() used as an lvalue, which is pretty strange. Perhaps you forgot to dereference it first. See substr in the perlfunc manpage.

Bareword "%s" refers to nonexistent package

(W) You used a qualified bareword of the form Foo::, but the compiler saw no other uses of that namespace before that point. Perhaps you need to predeclare a package?

Can't redefine active sort subroutine %s

(F) Perl optimizes the internal handling of sort subroutines and keeps pointers into them. You tried to redefine one such sort subroutine when it was currently active, which is not allowed. If you really want to do this, you should write sort { &func } @x instead of sort func @x.

Can't use bareword ("%s") as %s ref while "strict refs" in use

(F) Only hard references are allowed by "strict refs". Symbolic references are disallowed. See the perlref manpage.

Cannot resolve method `%s' overloading `%s' in package `%s'

(P) Internal error trying to resolve overloading specified by a method name (as opposed to a subroutine reference).

Constant subroutine %s redefined

(S) You redefined a subroutine which had previously been eligible for inlining. See Constant Functions in the perlsub manpage for commentary and workarounds.

Constant subroutine %s undefined

(S) You undefined a subroutine which had previously been eligible for inlining. See Constant Functions in the perlsub manpage for commentary and workarounds.

Copy method did not return a reference

(F) The method which overloads "=" is buggy. See Copy Constructor in the overload manpage.

Died

(F) You passed die() an empty string (the equivalent of die "") or you called it with no args and both $@ and $_ were empty.

Exiting pseudo-block via %s

(W) You are exiting a rather special block construct (like a sort block or subroutine) by unconventional means, such as a goto, or a loop control statement. See sort in the perlfunc manpage.

Identifier too long

(F) Perl limits identifiers (names for variables, functions, etc.) to 252 characters for simple names, somewhat more for compound names (like $A::B). You've exceeded Perl's limits. Future versions of Perl are likely to eliminate these arbitrary limitations.

Illegal character %s (carriage return)

(F) A carriage return character was found in the input. This is an error, and not a warning, because carriage return characters can break multi-line strings, including here documents (e.g., print <<EOF;).

Illegal switch in PERL5OPT: %s

(X) The PERL5OPT environment variable may only be used to set the following switches: -[DIMUdmw].

Integer overflow in hex number

(S) The literal hex number you have specified is too big for your architecture. On a 32-bit architecture the largest hex literal is 0xFFFFFFFF.

Integer overflow in octal number

(S) The literal octal number you have specified is too big for your architecture. On a 32-bit architecture the largest octal literal is 037777777777.

internal error: glob failed

(P) Something went wrong with the external program(s) used for glob and <*.c>. This may mean that your csh (C shell) is broken. If so, you should change all of the csh-related variables in config.sh: If you have tcsh, make the variables refer to it as if it were csh (e.g. full_csh='/usr/bin/tcsh'); otherwise, make them all empty (except that d_csh should be 'undef') so that Perl will think csh is missing. In either case, after editing config.sh, run ./Configure -S and rebuild Perl.

Invalid conversion in %s: "%s"

(W) Perl does not understand the given format conversion. See sprintf in the perlfunc manpage.

Invalid type in pack: '%s'

(F) The given character is not a valid pack type. See pack in the perlfunc manpage.

Invalid type in unpack: '%s'

(F) The given character is not a valid unpack type. See unpack in the perlfunc manpage.

Name "%s::%s" used only once: possible typo

(W) Typographical errors often show up as unique variable names. If you had a good reason for having a unique name, then just mention it again somehow to suppress the message (the use vars pragma is provided for just this purpose).

Null picture in formline

(F) The first argument to formline must be a valid format picture specification. It was found to be empty, which probably means you supplied it an uninitialized value. See the perlform manpage.

Offset outside string

(F) You tried to do a read/write/send/recv operation with an offset pointing outside the buffer. This is difficult to imagine. The sole exception to this is that sysread()ing past the buffer will extend the buffer and zero pad the new area.

Out of memory!

(X|F) The malloc() function returned 0, indicating there was insufficient remaining memory (or virtual memory) to satisfy the request.

The request was judged to be small, so the possibility to trap it depends on the way Perl was compiled. By default it is not trappable. However, if compiled for this, Perl may use the contents of $^M as an emergency pool after die()ing with this message. In this case the error is trappable once.

Out of memory during request for %s

(F) The malloc() function returned 0, indicating there was insufficient remaining memory (or virtual memory) to satisfy the request. However, the request was judged large enough (compile-time default is 64K), so a possibility to shut down by trapping this error is granted.

panic: frexp

(P) The library function frexp() failed, making printf("%f") impossible.

Possible attempt to put comments in qw() list

(W) qw() lists contain items separated by whitespace; as with literal strings, comment characters are not ignored, but are instead treated as literal data. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.)

You probably wrote something like this:

    @list = qw(
        a # a comment
        b # another comment
    );

when you should have written this:

    @list = qw(
        a
        b
    );

If you really want comments, build your list the old-fashioned way, with quotes and commas:

    @list = (
        'a',    # a comment
        'b',    # another comment
    );
Possible attempt to separate words with commas

(W) qw() lists contain items separated by whitespace; therefore commas aren't needed to separate the items. (You may have used different delimiters than the parentheses shown here; braces are also frequently used.)

You probably wrote something like this:

    qw! a, b, c !;

which puts literal commas into some of the list items. Write it without commas if you don't want them to appear in your data:

    qw! a b c !;
Scalar value @%s{%s} better written as $%s{%s}

(W) You've used a hash slice (indicated by @) to select a single element of a hash. Generally it's better to ask for a scalar value (indicated by $). The difference is that $foo{&bar} always behaves like a scalar, both when assigning to it and when evaluating its argument, while @foo{&bar} behaves like a list when you assign to it, and provides a list context to its subscript, which can do weird things if you're expecting only one subscript.

Stub found while resolving method `%s' overloading `%s' in %s

(P) Overloading resolution over @ISA tree may be broken by importing stubs. Stubs should never be implicitly created, but explicit calls to can may break this.

Too late for "-T" option

(X) The #! line (or local equivalent) in a Perl script contains the -T option, but Perl was not invoked with -T in its argument list. This is an error because, by the time Perl discovers a -T in a script, it's too late to properly taint everything from the environment. So Perl gives up.

untie attempted while %d inner references still exist

(W) A copy of the object returned from tie (or tied) was still valid when untie was called.

Unrecognized character %s

(F) The Perl parser has no idea what to do with the specified character in your Perl script (or eval). Perhaps you tried to run a compressed script, a binary program, or a directory as a Perl program.

Unsupported function fork

(F) Your version of executable does not support forking.

Note that under some systems, like OS/2, there may be different flavors of Perl executables, some of which may support fork, some not. Try changing the name you call Perl by to perl_, perl__, and so on.

Use of "$$<digit>" to mean "${$}<digit>" is deprecated

(D) Perl versions before 5.004 misinterpreted any type marker followed by "$" and a digit. For example, "$$0" was incorrectly taken to mean "${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.

However, the developers of Perl 5.004 could not fix this bug completely, because at least two widely-used modules depend on the old meaning of "$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the old (broken) way inside strings; but it generates this message as a warning. And in Perl 5.005, this special treatment will cease.

Value of %s can be "0"; test with defined()

(W) In a conditional expression, you used <HANDLE>, <*> (glob), each(), or readdir() as a boolean value. Each of these constructs can return a value of "0"; that would make the conditional expression false, which is probably not what you intended. When using these constructs in conditional expressions, test their values with the defined operator.

Variable "%s" may be unavailable

(W) An inner (nested) anonymous subroutine is inside a named subroutine, and outside that is another subroutine; and the anonymous (innermost) subroutine is referencing a lexical variable defined in the outermost subroutine. For example:

   sub outermost { my $a; sub middle { sub { $a } } }

If the anonymous subroutine is called or referenced (directly or indirectly) from the outermost subroutine, it will share the variable as you would expect. But if the anonymous subroutine is called or referenced when the outermost subroutine is not active, it will see the value of the shared variable as it was before and during the *first* call to the outermost subroutine, which is probably not what you want.

In these circumstances, it is usually best to make the middle subroutine anonymous, using the sub {} syntax. Perl has specific support for shared variables in nested anonymous subroutines; a named subroutine in between interferes with this feature.

Variable "%s" will not stay shared

(W) An inner (nested) named subroutine is referencing a lexical variable defined in an outer subroutine.

When the inner subroutine is called, it will probably see the value of the outer subroutine's variable as it was before and during the *first* call to the outer subroutine; in this case, after the first call to the outer subroutine is complete, the inner and outer subroutines will no longer share a common value for the variable. In other words, the variable will no longer be shared.

Furthermore, if the outer subroutine is anonymous and references a lexical variable outside itself, then the outer and inner subroutines will never share the given variable.

This problem can usually be solved by making the inner subroutine anonymous, using the sub {} syntax. When inner anonymous subs that reference variables in outer subroutines are called or referenced, they are automatically rebound to the current values of such variables.

Warning: something's wrong

(W) You passed warn() an empty string (the equivalent of warn "") or you called it with no args and $_ was empty.

Ill-formed logical name |%s| in prime_env_iter

(W) A warning peculiar to VMS. A logical name was encountered when preparing to iterate over %ENV which violates the syntactic rules governing logical names. Since it cannot be translated normally, it is skipped, and will not appear in %ENV. This may be a benign occurrence, as some software packages might directly modify logical name tables and introduce nonstandard names, or it may indicate that a logical name table has been corrupted.

Got an error from DosAllocMem

(P) An error peculiar to OS/2. Most probably you're using an obsolete version of Perl, and this should not happen anyway.

Malformed PERLLIB_PREFIX

(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form

    prefix1;prefix2

or

    prefix1 prefix2

with nonempty prefix1 and prefix2. If prefix1 is indeed a prefix of a builtin library search path, prefix2 is substituted. The error may appear if components are not found, or are too long. See "PERLLIB_PREFIX" in README.os2.

PERL_SH_DIR too long

(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the sh-shell in. See "PERL_SH_DIR" in README.os2.

Process terminated by SIG%s

(W) This is a standard message issued by OS/2 applications, while *nix applications die in silence. It is considered a feature of the OS/2 port. One can easily disable this by appropriate sighandlers, see Signals in the perlipc manpage. See also "Process terminated by SIGTERM/SIGINT" in README.os2.

BUGS

If you find what you think is a bug, you might check the headers of recently posted articles in the comp.lang.perl.misc newsgroup. There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Make sure you trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to <perlbug@perl.com> to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl. This file has been significantly updated for 5.004, so even veteran users should look through it.

The README file for general stuff.

The Copying file for copyright information.

HISTORY

Constructed by Tom Christiansen, grabbing material with permission from innumerable contributors, with kibitzing by more than a few Perl porters.

Last update: Wed May 14 11:14:09 EDT 1997


perl5005delta - what's new for perl5.005

  • About the new versioning system
  • Incompatible Changes
    • WARNING: This version is not binary compatible with Perl 5.004.
    • Default installation structure has changed
    • Perl Source Compatibility
    • C Source Compatibility
    • Binary Compatibility
    • Security fixes may affect compatibility
    • Relaxed new mandatory warnings introduced in 5.004
    • Licensing
  • Core Changes
    • Threads
    • Compiler
    • Regular Expressions
    • Improved malloc()
    • Quicksort is internally implemented
    • Reliable signals
    • Reliable stack pointers
    • More generous treatment of carriage returns
    • Memory leaks
    • Better support for multiple interpreters
    • Behavior of local() on array and hash elements is now well-defined
    • %! is transparently tied to the the Errno manpage module
    • Pseudo-hashes are supported
    • EXPR foreach EXPR is supported
    • Keywords can be globally overridden
    • $^E is meaningful on Win32
    • foreach (1..1000000) optimized
    • Foo:: can be used as implicitly quoted package name
    • exists $Foo::{Bar::} tests existence of a package
    • Better locale support
    • Experimental support for 64-bit platforms
    • prototype() returns useful results on builtins
    • Extended support for exception handling
    • Re-blessing in DESTROY() supported for chaining DESTROY() methods
    • All printf format conversions are handled internally
    • New INIT keyword
    • New lock keyword
    • New qr// operator
    • our is now a reserved word
    • Tied arrays are now fully supported
    • Tied handles support is better
    • 4th argument to substr
    • Negative LENGTH argument to splice
    • Magic lvalues are now more magical
    • <> now reads in records
  • Supported Platforms
    • New Platforms
    • Changes in existing support
  • Modules and Pragmata
    • New Modules
    • Changes in existing modules
  • Utility Changes
  • Documentation Changes
  • New Diagnostics
  • Obsolete Diagnostics
  • Configuration Changes
  • BUGS
  • SEE ALSO
  • HISTORY

NAME

perl5005delta - what's new for perl5.005

DESCRIPTION

This document describes differences between the 5.004 release and this one.

About the new versioning system

Perl is now developed on two tracks: a maintenance track that makes small, safe updates to released production versions with emphasis on compatibility; and a development track that pursues more aggressive evolution. Maintenance releases (which should be considered production quality) have subversion numbers that run from 1 to 49, and development releases (which should be considered "alpha" quality) run from 50 to 99.

Perl 5.005 is the combined product of the new dual-track development scheme.

Incompatible Changes

WARNING: This version is not binary compatible with Perl 5.004.

Starting with Perl 5.004_50 there were many deep and far-reaching changes to the language internals. If you have dynamically loaded extensions that you built under perl 5.003 or 5.004, you can continue to use them with 5.004, but you will need to rebuild and reinstall those extensions to use them 5.005. See INSTALL for detailed instructions on how to upgrade.

Default installation structure has changed

The new Configure defaults are designed to allow a smooth upgrade from 5.004 to 5.005, but you should read INSTALL for a detailed discussion of the changes in order to adapt them to your system.

Perl Source Compatibility

When none of the experimental features are enabled, there should be very few user-visible Perl source compatibility issues.

If threads are enabled, then some caveats apply. @_ and $_ become lexical variables. The effect of this should be largely transparent to the user, but there are some boundary conditions under which user will need to be aware of the issues. For example, local(@_) results in a "Can't localize lexical variable @_ ..." message. This may be enabled in a future version.

Some new keywords have been introduced. These are generally expected to have very little impact on compatibility. See New INIT keyword, New lock keyword, and New qr// operator.

Certain barewords are now reserved. Use of these will provoke a warning if you have asked for them with the -w switch. See our is now a reserved word.

C Source Compatibility

There have been a large number of changes in the internals to support the new features in this release.

  • Core sources now require ANSI C compiler

    An ANSI C compiler is now required to build perl. See INSTALL.

  • All Perl global variables must now be referenced with an explicit prefix

    All Perl global variables that are visible for use by extensions now have a PL_ prefix. New extensions should not refer to perl globals by their unqualified names. To preserve sanity, we provide limited backward compatibility for globals that are being widely used like sv_undef and na (which should now be written as PL_sv_undef, PL_na etc.)

    If you find that your XS extension does not compile anymore because a perl global is not visible, try adding a PL_ prefix to the global and rebuild.

    It is strongly recommended that all functions in the Perl API that don't begin with perl be referenced with a Perl_ prefix. The bare function names without the Perl_ prefix are supported with macros, but this support may cease in a future release.

    See the perlapi manpage.

  • Enabling threads has source compatibility issues

    Perl built with threading enabled requires extensions to use the new dTHR macro to initialize the handle to access per-thread data. If you see a compiler error that talks about the variable thr not being declared (when building a module that has XS code), you need to add dTHR; at the beginning of the block that elicited the error.

    The API function perl_get_sv("@",FALSE) should be used instead of directly accessing perl globals as GvSV(errgv). The API call is backward compatible with existing perls and provides source compatibility with threading is enabled.

    See C Source Compatibility for more information.

Binary Compatibility

This version is NOT binary compatible with older versions. All extensions will need to be recompiled. Further binaries built with threads enabled are incompatible with binaries built without. This should largely be transparent to the user, as all binary incompatible configurations have their own unique architecture name, and extension binaries get installed at unique locations. This allows coexistence of several configurations in the same directory hierarchy. See INSTALL.

Security fixes may affect compatibility

A few taint leaks and taint omissions have been corrected. This may lead to "failure" of scripts that used to work with older versions. Compiling with -DINCOMPLETE_TAINTS provides a perl with minimal amounts of changes to the tainting behavior. But note that the resulting perl will have known insecurities.

Oneliners with the -e switch do not create temporary files anymore.

Relaxed new mandatory warnings introduced in 5.004

Many new warnings that were introduced in 5.004 have been made optional. Some of these warnings are still present, but perl's new features make them less often a problem. See New Diagnostics.

Licensing

Perl has a new Social Contract for contributors. See Porting/Contract.

The license included in much of the Perl documentation has changed. Most of the Perl documentation was previously under the implicit GNU General Public License or the Artistic License (at the user's choice). Now much of the documentation unambiguously states the terms under which it may be distributed. Those terms are in general much less restrictive than the GNU GPL. See the perl manpage and the individual perl manpages listed therein.

Core Changes

Threads

WARNING: Threading is considered an experimental feature. Details of the implementation may change without notice. There are known limitations and some bugs. These are expected to be fixed in future versions.

See README.threads.

Compiler

WARNING: The Compiler and related tools are considered experimental. Features may change without notice, and there are known limitations and bugs. Since the compiler is fully external to perl, the default configuration will build and install it.

The Compiler produces three different types of transformations of a perl program. The C backend generates C code that captures perl's state just before execution begins. It eliminates the compile-time overheads of the regular perl interpreter, but the run-time performance remains comparatively the same. The CC backend generates optimized C code equivalent to the code path at run-time. The CC backend has greater potential for big optimizations, but only a few optimizations are implemented currently. The Bytecode backend generates a platform independent bytecode representation of the interpreter's state just before execution. Thus, the Bytecode back end also eliminates much of the compilation overhead of the interpreter.

The compiler comes with several valuable utilities.

B::Lint is an experimental module to detect and warn about suspicious code, especially the cases that the -w switch does not detect.

B::Deparse can be used to demystify perl code, and understand how perl optimizes certain constructs.

B::Xref generates cross reference reports of all definition and use of variables, subroutines and formats in a program.

B::Showlex show the lexical variables used by a subroutine or file at a glance.

perlcc is a simple frontend for compiling perl.

See ext/B/README, the B manpage, and the respective compiler modules.

Regular Expressions

Perl's regular expression engine has been seriously overhauled, and many new constructs are supported. Several bugs have been fixed.

Here is an itemized summary:

Many new and improved optimizations

Changes in the RE engine:

        Unneeded nodes removed;
        Substrings merged together;
        New types of nodes to process (SUBEXPR)* and similar expressions
            quickly, used if the SUBEXPR has no side effects and matches
            strings of the same length;
        Better optimizations by lookup for constant substrings;
        Better search for constants substrings anchored by $ ;

Changes in Perl code using RE engine:

        More optimizations to s/longer/short/;
        study() was not working;
        /blah/ may be optimized to an analogue of index() if $& $` $' not seen;
        Unneeded copying of matched-against string removed;
        Only matched part of the string is copying if $` $' were not seen;
Many bug fixes

Note that only the major bug fixes are listed here. See Changes for others.

        Backtracking might not restore start of $3.
        No feedback if max count for * or + on "complex" subexpression
            was reached, similarly (but at compile time) for {3,34567}
        Primitive restrictions on max count introduced to decrease a
            possibility of a segfault;
        (ZERO-LENGTH)* could segfault;
        (ZERO-LENGTH)* was prohibited;
        Long REs were not allowed;
        /RE/g could skip matches at the same position after a
          zero-length match;
New regular expression constructs

The following new syntax elements are supported:

        (?<=RE)
        (?<!RE)
        (?{ CODE })
        (?i-x)
        (?i:RE)
        (?(COND)YES_RE|NO_RE)
        (?>RE)
        \z
New operator for precompiled regular expressions

See New qr// operator.

Other improvements
        Better debugging output (possibly with colors),
            even from non-debugging Perl;
        RE engine code now looks like C, not like assembler;
        Behaviour of RE modifiable by `use re' directive;
        Improved documentation;
        Test suite significantly extended;
        Syntax [:^upper:] etc., reserved inside character classes;
Incompatible changes
        (?i) localized inside enclosing group;
        $( is not interpolated into RE any more;
        /RE/g may match at the same position (with non-zero length)
            after a zero-length match (bug fix).

See the perlre manpage and the perlop manpage.

Improved malloc()

See banner at the beginning of malloc.c for details.

Quicksort is internally implemented

Perl now contains its own highly optimized qsort() routine. The new qsort() is resistant to inconsistent comparison functions, so Perl's sort() will not provoke coredumps any more when given poorly written sort subroutines. (Some C library qsort()s that were being used before used to have this problem.) In our testing, the new qsort() required the minimal number of pair-wise compares on average, among all known qsort() implementations.

See perlfunc/sort.

Reliable signals

Perl's signal handling is susceptible to random crashes, because signals arrive asynchronously, and the Perl runtime is not reentrant at arbitrary times.

However, one experimental implementation of reliable signals is available when threads are enabled. See Thread::Signal. Also see INSTALL for how to build a Perl capable of threads.

Reliable stack pointers

The internals now reallocate the perl stack only at predictable times. In particular, magic calls never trigger reallocations of the stack, because all reentrancy of the runtime is handled using a "stack of stacks". This should improve reliability of cached stack pointers in the internals and in XSUBs.

More generous treatment of carriage returns

Perl used to complain if it encountered literal carriage returns in scripts. Now they are mostly treated like whitespace within program text. Inside string literals and here documents, literal carriage returns are ignored if they occur paired with linefeeds, or get interpreted as whitespace if they stand alone. This behavior means that literal carriage returns in files should be avoided. You can get the older, more compatible (but less generous) behavior by defining the preprocessor symbol PERL_STRICT_CR when building perl. Of course, all this has nothing whatever to do with how escapes like \r are handled within strings.

Note that this doesn't somehow magically allow you to keep all text files in DOS format. The generous treatment only applies to files that perl itself parses. If your C compiler doesn't allow carriage returns in files, you may still be unable to build modules that need a C compiler.

Memory leaks

substr, pos and vec don't leak memory anymore when used in lvalue context. Many small leaks that impacted applications that embed multiple interpreters have been fixed.

Better support for multiple interpreters

The build-time option -DMULTIPLICITY has had many of the details reworked. Some previously global variables that should have been per-interpreter now are. With care, this allows interpreters to call each other. See the PerlInterp extension on CPAN.

Behavior of local() on array and hash elements is now well-defined

See Temporary Values via local() in the perlsub manpage.

%! is transparently tied to the the Errno manpage module

See the perlvar manpage, and the Errno manpage.

Pseudo-hashes are supported

See the perlref manpage.

EXPR foreach EXPR is supported

See the perlsyn manpage.

Keywords can be globally overridden

See the perlsub manpage.

$^E is meaningful on Win32

See the perlvar manpage.

foreach (1..1000000) optimized

foreach (1..1000000) is now optimized into a counting loop. It does not try to allocate a 1000000-size list anymore.

Foo:: can be used as implicitly quoted package name

Barewords caused unintuitive behavior when a subroutine with the same name as a package happened to be defined. Thus, new Foo @args, use the result of the call to Foo() instead of Foo being treated as a literal. The recommended way to write barewords in the indirect object slot is new Foo:: @args. Note that the method new() is called with a first argument of Foo, not Foo:: when you do that.

exists $Foo::{Bar::} tests existence of a package

It was impossible to test for the existence of a package without actually creating it before. Now exists $Foo::{Bar::} can be used to test if the Foo::Bar namespace has been created.

Better locale support

See the perllocale manpage.

Experimental support for 64-bit platforms

Perl5 has always had 64-bit support on systems with 64-bit longs. Starting with 5.005, the beginnings of experimental support for systems with 32-bit long and 64-bit 'long long' integers has been added. If you add -DUSE_LONG_LONG to your ccflags in config.sh (or manually define it in perl.h) then perl will be built with 'long long' support. There will be many compiler warnings, and the resultant perl may not work on all systems. There are many other issues related to third-party extensions and libraries. This option exists to allow people to work on those issues.

prototype() returns useful results on builtins

See prototype in the perlfunc manpage.

Extended support for exception handling

die() now accepts a reference value, and $@ gets set to that value in exception traps. This makes it possible to propagate exception objects. This is an undocumented experimental feature.

Re-blessing in DESTROY() supported for chaining DESTROY() methods

See Destructors in the perlobj manpage.

All printf format conversions are handled internally

See printf in the perlfunc manpage.

New INIT keyword

INIT subs are like BEGIN and END, but they get run just before the perl runtime begins execution. e.g., the Perl Compiler makes use of INIT blocks to initialize and resolve pointers to XSUBs.

New lock keyword

The lock keyword is the fundamental synchronization primitive in threaded perl. When threads are not enabled, it is currently a noop.

To minimize impact on source compatibility this keyword is "weak", i.e., any user-defined subroutine of the same name overrides it, unless a use Thread has been seen.

New qr// operator

The qr// operator, which is syntactically similar to the other quote-like operators, is used to create precompiled regular expressions. This compiled form can now be explicitly passed around in variables, and interpolated in other regular expressions. See the perlop manpage.

our is now a reserved word

Calling a subroutine with the name our will now provoke a warning when using the -w switch.

Tied arrays are now fully supported

See the Tie::Array manpage.

Tied handles support is better

Several missing hooks have been added. There is also a new base class for TIEARRAY implementations. See the Tie::Array manpage.

4th argument to substr

substr() can now both return and replace in one operation. The optional 4th argument is the replacement string. See substr in the perlfunc manpage.

Negative LENGTH argument to splice

splice() with a negative LENGTH argument now work similar to what the LENGTH did for substr(). Previously a negative LENGTH was treated as 0. See splice in the perlfunc manpage.

Magic lvalues are now more magical

When you say something like substr($x, 5) = "hi", the scalar returned by substr() is special, in that any modifications to it affect $x. (This is called a 'magic lvalue' because an 'lvalue' is something on the left side of an assignment.) Normally, this is exactly what you would expect to happen, but Perl uses the same magic if you use substr(), pos(), or vec() in a context where they might be modified, like taking a reference with \ or as an argument to a sub that modifies @_. In previous versions, this 'magic' only went one way, but now changes to the scalar the magic refers to ($x in the above example) affect the magic lvalue too. For instance, this code now acts differently:

    $x = "hello";
    sub printit {
        $x = "g'bye";
        print $_[0], "\n";
    }
    printit(substr($x, 0, 5));

In previous versions, this would print "hello", but it now prints "g'bye".

<> now reads in records

If $/ is a reference to an integer, or a scalar that holds an integer, <> will read in records instead of lines. For more info, see $/ in the perlvar manpage.

Supported Platforms

Configure has many incremental improvements. Site-wide policy for building perl can now be made persistent, via Policy.sh. Configure also records the command-line arguments used in config.sh.

New Platforms

BeOS is now supported. See README.beos.

DOS is now supported under the DJGPP tools. See README.dos (installed as the perldos manpage on some systems).

MiNT is now supported. See README.mint.

MPE/iX is now supported. See README.mpeix.

MVS (aka OS390, aka Open Edition) is now supported. See README.os390 (installed as the perlos390 manpage on some systems).

Stratus VOS is now supported. See README.vos.

Changes in existing support

Win32 support has been vastly enhanced. Support for Perl Object, a C++ encapsulation of Perl. GCC and EGCS are now supported on Win32. See README.win32, aka the perlwin32 manpage.

VMS configuration system has been rewritten. See README.vms (installed as README_vms on some systems).

The hints files for most Unix platforms have seen incremental improvements.

Modules and Pragmata

New Modules

B

Perl compiler and tools. See the B manpage.

Data::Dumper

A module to pretty print Perl data. See the Data::Dumper manpage.

Dumpvalue

A module to dump perl values to the screen. See the Dumpvalue manpage.

Errno

A module to look up errors more conveniently. See the Errno manpage.

File::Spec

A portable API for file operations.

ExtUtils::Installed

Query and manage installed modules.

ExtUtils::Packlist

Manipulate .packlist files.

Fatal

Make functions/builtins succeed or die.

IPC::SysV

Constants and other support infrastructure for System V IPC operations in perl.

Test

A framework for writing testsuites.

Tie::Array

Base class for tied arrays.

Tie::Handle

Base class for tied handles.

Thread

Perl thread creation, manipulation, and support.

attrs

Set subroutine attributes.

fields

Compile-time class fields.

re

Various pragmata to control behavior of regular expressions.

Changes in existing modules

Benchmark

You can now run tests for x seconds instead of guessing the right number of tests to run.

Keeps better time.

Carp

Carp has a new function cluck(). cluck() warns, like carp(), but also adds a stack backtrace to the error message, like confess().

CGI

CGI has been updated to version 2.42.

Fcntl

More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for large (more than 4G) file access (the 64-bit support is not yet working, though, so no need to get overly excited), Free/Net/OpenBSD locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the mask of O_RDONLY, O_WRONLY, and O_RDWR.

Math::Complex

The accessors methods Re, Im, arg, abs, rho, theta, methods can ($z->Re()) now also act as mutators ($z->Re(3)).

Math::Trig

A little bit of radial trigonometry (cylindrical and spherical) added, for example the great circle distance.

POSIX

POSIX now has its own platform-specific hints files.

DB_File

DB_File supports version 2.x of Berkeley DB. See ext/DB_File/Changes.

MakeMaker

MakeMaker now supports writing empty makefiles, provides a way to specify that site umask() policy should be honored. There is also better support for manipulation of .packlist files, and getting information about installed modules.

Extensions that have both architecture-dependent and architecture-independent files are now always installed completely in the architecture-dependent locations. Previously, the shareable parts were shared both across architectures and across perl versions and were therefore liable to be overwritten with newer versions that might have subtle incompatibilities.

CPAN

See the perlmodinstall manpage and the CPAN manpage.

Cwd

Cwd::cwd is faster on most platforms.

Utility Changes

h2ph and related utilities have been vastly overhauled.

perlcc, a new experimental front end for the compiler is available.

The crude GNU configure emulator is now called configure.gnu to avoid trampling on Configure under case-insensitive filesystems.

perldoc used to be rather slow. The slower features are now optional. In particular, case-insensitive searches need the -i switch, and recursive searches need -r. You can set these switches in the PERLDOC environment variable to get the old behavior.

Documentation Changes

Config.pm now has a glossary of variables.

Porting/patching.pod has detailed instructions on how to create and submit patches for perl.

the perlport manpage specifies guidelines on how to write portably.

the perlmodinstall manpage describes how to fetch and install modules from CPAN sites.

Some more Perl traps are documented now. See the perltrap manpage.

the perlopentut manpage gives a tutorial on using open().

the perlreftut manpage gives a tutorial on references.

the perlthrtut manpage gives a tutorial on threads.

New Diagnostics

Ambiguous call resolved as CORE::%s(), qualify as such or use &

(W) A subroutine you have declared has the same name as a Perl keyword, and you have used the name without qualification for calling one or the other. Perl decided to call the builtin because the subroutine is not imported.

To force interpretation as a subroutine call, either put an ampersand before the subroutine name, or qualify the name with its package. Alternatively, you can import the subroutine (or pretend that it's imported with the use subs pragma).

To silently interpret it as the Perl operator, use the CORE:: prefix on the operator (e.g. CORE::log($x)) or by declaring the subroutine to be an object method (see the attrs manpage).

Bad index while coercing array into hash

(F) The index looked up in the hash found as the 0'th element of a pseudo-hash is not legal. Index values must be at 1 or greater. See the perlref manpage.

Bareword "%s" refers to nonexistent package

(W) You used a qualified bareword of the form Foo::, but the compiler saw no other uses of that namespace before that point. Perhaps you need to predeclare a package?

Can't call method "%s" on an undefined value

(F) You used the syntax of a method call, but the slot filled by the object reference or package name contains an undefined value. Something like this will reproduce the error:

    $BADREF = 42;
    process $BADREF 1,2,3;
    $BADREF->process(1,2,3);
Can't check filesystem of script "%s" for nosuid

(P) For some reason you can't check the filesystem of the script for nosuid.

Can't coerce array into hash

(F) You used an array where a hash was expected, but the array has no information on how to map from keys to array indices. You can do that only with arrays that have a hash reference at index 0.

Can't goto subroutine from an eval-string

(F) The "goto subroutine" call can't be used to jump out of an eval "string". (You can use it to jump out of an eval {BLOCK}, but you probably don't want to.)

Can't localize pseudo-hash element

(F) You said something like local $ar->{'key'}, where $ar is a reference to a pseudo-hash. That hasn't been implemented yet, but you can get a similar effect by localizing the corresponding array element directly -- local $ar->[$ar->[0]{'key'}].

Can't use %%! because Errno.pm is not available

(F) The first time the %! hash is used, perl automatically loads the Errno.pm module. The Errno module is expected to tie the %! hash to provide symbolic names for $! errno values.

Cannot find an opnumber for "%s"

(F) A string of a form CORE::word was given to prototype(), but there is no builtin with the name word.

Character class syntax [. .] is reserved for future extensions

(W) Within regular expression character classes ([]) the syntax beginning with "[." and ending with ".]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[." and ".\]".

Character class syntax [: :] is reserved for future extensions

(W) Within regular expression character classes ([]) the syntax beginning with "[:" and ending with ":]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[:" and ":\]".

Character class syntax [= =] is reserved for future extensions

(W) Within regular expression character classes ([]) the syntax beginning with "[=" and ending with "=]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[=" and "=\]".

%s: Eval-group in insecure regular expression

(F) Perl detected tainted data when trying to compile a regular expression that contains the (?{ ... }) zero-width assertion, which is unsafe. See (?{ code }) in the perlre manpage, and the perlsec manpage.

%s: Eval-group not allowed, use re 'eval'

(F) A regular expression contained the (?{ ... }) zero-width assertion, but that construct is only allowed when the use re 'eval' pragma is in effect. See (?{ code }) in the perlre manpage.

%s: Eval-group not allowed at run time

(F) Perl tried to compile a regular expression containing the (?{ ... }) zero-width assertion at run time, as it would when the pattern contains interpolated values. Since that is a security risk, it is not allowed. If you insist, you may still do this by explicitly building the pattern from an interpolated string at run time and using that in an eval(). See (?{ code }) in the perlre manpage.

Explicit blessing to '' (assuming package main)

(W) You are blessing a reference to a zero length string. This has the effect of blessing the reference into the package main. This is usually not what you want. Consider providing a default target package, e.g. bless($ref, $p || 'MyPackage');

Illegal hex digit ignored

(W) You may have tried to use a character other than 0 - 9 or A - F in a hexadecimal number. Interpretation of the hexadecimal number stopped before the illegal character.

No such array field

(F) You tried to access an array as a hash, but the field name used is not defined. The hash at index 0 should map all valid field names to array indices for that to work.

No such field "%s" in variable %s of type %s

(F) You tried to access a field of a typed variable where the type does not know about the field name. The field names are looked up in the %FIELDS hash in the type package at compile time. The %FIELDS hash is usually set up with the 'fields' pragma.

Out of memory during ridiculously large request

(F) You can't allocate more than 2^31+"small amount" bytes. This error is most likely to be caused by a typo in the Perl program. e.g., $arr[time] instead of $arr[$time].

Range iterator outside integer range

(F) One (or both) of the numeric arguments to the range operator ".." are outside the range which can be represented by integers internally. One possible workaround is to force Perl to use magical string increment by prepending "0" to your numbers.

Recursive inheritance detected while looking for method '%s' %s

(F) More than 100 levels of inheritance were encountered while invoking a method. Probably indicates an unintended loop in your inheritance hierarchy.

Reference found where even-sized list expected

(W) You gave a single reference where Perl was expecting a list with an even number of elements (for assignment to a hash). This usually means that you used the anon hash constructor when you meant to use parens. In any case, a hash requires key/value pairs.

    %hash = { one => 1, two => 2, };   # WRONG
    %hash = [ qw/ an anon array / ];   # WRONG
    %hash = ( one => 1, two => 2, );   # right
    %hash = qw( one 1 two 2 );                 # also fine
Undefined value assigned to typeglob

(W) An undefined value was assigned to a typeglob, a la *foo = undef. This does nothing. It's possible that you really mean undef *foo.

Use of reserved word "%s" is deprecated

(D) The indicated bareword is a reserved word. Future versions of perl may use it as a keyword, so you're better off either explicitly quoting the word in a manner appropriate for its context of use, or using a different name altogether. The warning can be suppressed for subroutine names by either adding a & prefix, or using a package qualifier, e.g. &our(), or Foo::our().

perl: warning: Setting locale failed.

(S) The whole warning message will look something like:

       perl: warning: Setting locale failed.
       perl: warning: Please check that your locale settings:
               LC_ALL = "En_US",
               LANG = (unset)
           are supported and installed on your system.
       perl: warning: Falling back to the standard locale ("C").

Exactly what were the failed locale settings varies. In the above the settings were that the LC_ALL was "En_US" and the LANG had no value. This error means that Perl detected that you and/or your system administrator have set up the so-called variable system but Perl could not use those settings. This was not dead serious, fortunately: there is a "default locale" called "C" that Perl can and will use, the script will be run. Before you really fix the problem, however, you will get the same error message each time you run Perl. How to really fix the problem can be found in LOCALE PROBLEMS in the perllocale manpage.

Obsolete Diagnostics

Can't mktemp()

(F) The mktemp() routine failed for some reason while trying to process a -e switch. Maybe your /tmp partition is full, or clobbered.

Removed because -e doesn't use temporary files any more.

Can't write to temp file for -e: %s

(F) The write routine failed for some reason while trying to process a -e switch. Maybe your /tmp partition is full, or clobbered.

Removed because -e doesn't use temporary files any more.

Cannot open temporary file

(F) The create routine failed for some reason while trying to process a -e switch. Maybe your /tmp partition is full, or clobbered.

Removed because -e doesn't use temporary files any more.

regexp too big

(F) The current implementation of regular expressions uses shorts as address offsets within a string. Unfortunately this means that if the regular expression compiles to longer than 32767, it'll blow up. Usually when you want a regular expression this big, there is a better way to do it with multiple statements. See the perlre manpage.

Configuration Changes

You can use "Configure -Uinstallusrbinperl" which causes installperl to skip installing perl also as /usr/bin/perl. This is useful if you prefer not to modify /usr/bin for some reason or another but harmful because many scripts assume to find Perl in /usr/bin/perl.

BUGS

If you find what you think is a bug, you might check the headers of recently posted articles in the comp.lang.perl.misc newsgroup. There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Make sure you trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to <perlbug@perl.com> to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Gurusamy Sarathy <gsar@activestate.com>, with many contributions from The Perl Porters.

Send omissions or corrections to <perlbug@perl.com>.


perl561delta - what's new for perl v5.6.x

  • Summary of changes between 5.6.0 and 5.6.1
    • Security Issues
    • Core bug fixes
    • Core features
    • Configuration issues
    • Documentation
    • Bundled modules
    • Platform-specific improvements
  • Core Enhancements
    • Interpreter cloning, threads, and concurrency
    • Lexically scoped warning categories
    • Unicode and UTF-8 support
    • Support for interpolating named characters
    • "our" declarations
    • Support for strings represented as a vector of ordinals
    • Improved Perl version numbering system
    • New syntax for declaring subroutine attributes
    • File and directory handles can be autovivified
    • open() with more than two arguments
    • 64-bit support
    • Large file support
    • Long doubles
    • "more bits"
    • Enhanced support for sort() subroutines
    • sort $coderef @foo allowed
    • File globbing implemented internally
    • Support for CHECK blocks
    • POSIX character class syntax [: :] supported
    • Better pseudo-random number generator
    • Improved qw// operator
    • Better worst-case behavior of hashes
    • pack() format 'Z' supported
    • pack() format modifier '!' supported
    • pack() and unpack() support counted strings
    • Comments in pack() templates
    • Weak references
    • Binary numbers supported
    • Lvalue subroutines
    • Some arrows may be omitted in calls through references
    • Boolean assignment operators are legal lvalues
    • exists() is supported on subroutine names
    • exists() and delete() are supported on array elements
    • Pseudo-hashes work better
    • Automatic flushing of output buffers
    • Better diagnostics on meaningless filehandle operations
    • Where possible, buffered data discarded from duped input filehandle
    • eof() has the same old magic as <>
    • binmode() can be used to set :crlf and :raw modes
    • -T filetest recognizes UTF-8 encoded files as "text"
    • system(), backticks and pipe open now reflect exec() failure
    • Improved diagnostics
    • Diagnostics follow STDERR
    • More consistent close-on-exec behavior
    • syswrite() ease-of-use
    • Better syntax checks on parenthesized unary operators
    • Bit operators support full native integer width
    • Improved security features
    • More functional bareword prototype (*)
    • require and do may be overridden
    • $^X variables may now have names longer than one character
    • New variable $^C reflects -c switch
    • New variable $^V contains Perl version as a string
    • Optional Y2K warnings
    • Arrays now always interpolate into double-quoted strings
    • @- and @+ provide starting/ending offsets of regex submatches
  • Modules and Pragmata
    • Modules
    • Pragmata
  • Utility Changes
    • dprofpp
    • find2perl
    • h2xs
    • perlcc
    • perldoc
    • The Perl Debugger
  • Improved Documentation
  • Performance enhancements
    • Simple sort() using { $a <=> $b } and the like are optimized
    • Optimized assignments to lexical variables
    • Faster subroutine calls
    • delete(), each(), values() and hash iteration are faster
  • Installation and Configuration Improvements
    • -Dusethreads means something different
    • New Configure flags
    • Threadedness and 64-bitness now more daring
    • Long Doubles
    • -Dusemorebits
    • -Duselargefiles
    • installusrbinperl
    • SOCKS support
    • -A flag
    • Enhanced Installation Directories
    • gcc automatically tried if 'cc' does not seem to be working
  • Platform specific changes
    • Supported platforms
    • DOS
    • OS390 (OpenEdition MVS)
    • VMS
    • Win32
  • Significant bug fixes
    • <HANDLE> on empty files
    • eval '...' improvements
    • All compilation errors are true errors
    • Implicitly closed filehandles are safer
    • Behavior of list slices is more consistent
    • (\$) prototype and $foo{a}
    • goto &sub and AUTOLOAD
    • -bareword allowed under use integer
    • Failures in DESTROY()
    • Locale bugs fixed
    • Memory leaks
    • Spurious subroutine stubs after failed subroutine calls
    • Taint failures under -U
    • END blocks and the -c switch
    • Potential to leak DATA filehandles
  • New or Changed Diagnostics
  • New tests
  • Incompatible Changes
    • Perl Source Incompatibilities
    • C Source Incompatibilities
    • Compatible C Source API Changes
    • Binary Incompatibilities
  • Known Problems
    • Localizing a tied hash element may leak memory
    • Known test failures
    • EBCDIC platforms not fully supported
    • UNICOS/mk CC failures during Configure run
    • Arrow operator and arrays
    • Experimental features
  • Obsolete Diagnostics
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl561delta - what's new for perl v5.6.x

DESCRIPTION

This document describes differences between the 5.005 release and the 5.6.1 release.

Summary of changes between 5.6.0 and 5.6.1

This section contains a summary of the changes between the 5.6.0 release and the 5.6.1 release. More details about the changes mentioned here may be found in the Changes files that accompany the Perl source distribution. See the perlhack manpage for pointers to online resources where you can inspect the individual patches described by these changes.

Security Issues

suidperl will not run /bin/mail anymore, because some platforms have a /bin/mail that is vulnerable to buffer overflow attacks.

Note that suidperl is neither built nor installed by default in any recent version of perl. Use of suidperl is highly discouraged. If you think you need it, try alternatives such as sudo first. See http://www.courtesan.com/sudo/ .

Core bug fixes

This is not an exhaustive list. It is intended to cover only the significant user-visible changes.

UNIVERSAL::isa()

A bug in the caching mechanism used by UNIVERSAL::isa() that affected base.pm has been fixed. The bug has existed since the 5.005 releases, but wasn't tickled by base.pm in those releases.

Memory leaks

Various cases of memory leaks and attempts to access uninitialized memory have been cured. See Known Problems below for further issues.

Numeric conversions

Numeric conversions did not recognize changes in the string value properly in certain circumstances.

In other situations, large unsigned numbers (those above 2**31) could sometimes lose their unsignedness, causing bogus results in arithmetic operations.

Integer modulus on large unsigned integers sometimes returned incorrect values.

Perl 5.6.0 generated "not a number" warnings on certain conversions where previous versions didn't.

These problems have all been rectified.

Infinity is now recognized as a number.

qw(a\\b)

In Perl 5.6.0, qw(a\\b) produced a string with two backslashes instead of one, in a departure from the behavior in previous versions. The older behavior has been reinstated.

caller()

caller() could cause core dumps in certain situations. Carp was sometimes affected by this problem.

Bugs in regular expressions

Pattern matches on overloaded values are now handled correctly.

Perl 5.6.0 parsed m/\x{ab}/ incorrectly, leading to spurious warnings. This has been corrected.

The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds of simple pattern matches. These are now handled better.

Regular expression debug output (whether through use re 'debug' or via -Dr) now looks better.

Multi-line matches like "a\nxb\n" =~ /(?!\A)x/m were flawed. The bug has been fixed.

Use of $& could trigger a core dump under some situations. This is now avoided.

Match variables $1 et al., weren't being unset when a pattern match was backtracking, and the anomaly showed up inside /...(?{ ... }).../ etc. These variables are now tracked correctly.

pos() did not return the correct value within s///ge in earlier versions. This is now handled correctly.

"slurp" mode

readline() on files opened in "slurp" mode could return an extra "" at the end in certain situations. This has been corrected.

Autovivification of symbolic references to special variables

Autovivification of symbolic references of special variables described in the perlvar manpage (as in ${$num}) was accidentally disabled. This works again now.

Lexical warnings

Lexical warnings now propagate correctly into eval "...".

use warnings qw(FATAL all) did not work as intended. This has been corrected.

Lexical warnings could leak into other scopes in some situations. This is now fixed.

warnings::enabled() now reports the state of $^W correctly if the caller isn't using lexical warnings.

Spurious warnings and errors

Perl 5.6.0 could emit spurious warnings about redefinition of dl_error() when statically building extensions into perl. This has been corrected.

"our" variables could result in bogus "Variable will not stay shared" warnings. This is now fixed.

"our" variables of the same name declared in two sibling blocks resulted in bogus warnings about "redeclaration" of the variables. The problem has been corrected.

glob()

Compatibility of the builtin glob() with old csh-based glob has been improved with the addition of GLOB_ALPHASORT option. See File::Glob.

File::Glob::glob() has been renamed to File::Glob::bsd_glob() because the name clashes with the builtin glob(). The older name is still available for compatibility, but is deprecated.

Spurious syntax errors generated in certain situations, when glob() caused File::Glob to be loaded for the first time, have been fixed.

Tainting

Some cases of inconsistent taint propagation (such as within hash values) have been fixed.

The tainting behavior of sprintf() has been rationalized. It does not taint the result of floating point formats anymore, making the behavior consistent with that of string interpolation.

sort()

Arguments to sort() weren't being provided the right wantarray() context. The comparison block is now run in scalar context, and the arguments to be sorted are always provided list context.

sort() is also fully reentrant, in the sense that the sort function can itself call sort(). This did not work reliably in previous releases.

#line directives

#line directives now work correctly when they appear at the very beginning of eval "...".

Subroutine prototypes

The (\&) prototype now works properly.

map()

map() could get pathologically slow when the result list it generates is larger than the source list. The performance has been improved for common scenarios.

Debugger

Debugger exit code now reflects the script exit code.

Condition "0" in breakpoints is now treated correctly.

The d command now checks the line number.

$. is no longer corrupted by the debugger.

All debugger output now correctly goes to the socket if RemotePort is set.

PERL5OPT

PERL5OPT can be set to more than one switch group. Previously, it used to be limited to one group of options only.

chop()

chop(@list) in list context returned the characters chopped in reverse order. This has been reversed to be in the right order.

Unicode support

Unicode support has seen a large number of incremental improvements, but continues to be highly experimental. It is not expected to be fully supported in the 5.6.x maintenance releases.

substr(), join(), repeat(), reverse(), quotemeta() and string concatenation were all handling Unicode strings incorrectly in Perl 5.6.0. This has been corrected.

Support for tr///CU and tr///UC etc., have been removed since we realized the interface is broken. For similar functionality, see pack in the perlfunc manpage.

The Unicode Character Database has been updated to version 3.0.1 with additions made available to the public as of August 30, 2000.

The Unicode character classes \p{Blank} and \p{SpacePerl} have been added. "Blank" is like C isblank(), that is, it contains only "horizontal whitespace" (the space character is, the newline isn't), and the "SpacePerl" is the Unicode equivalent of \s (\p{Space} isn't, since that includes the vertical tabulator character, whereas \s doesn't.)

If you are experimenting with Unicode support in perl, the development versions of Perl may have more to offer. In particular, I/O layers are now available in the development track, but not in the maintenance track, primarily to do backward compatibility issues. Unicode support is also evolving rapidly on a daily basis in the development track--the maintenance track only reflects the most conservative of these changes.

  • -bit support

    Support for 64-bit platforms has been improved, but continues to be experimental. The level of support varies greatly among platforms.

    • Compiler

    The B Compiler and its various backends have had many incremental improvements, but they continue to remain highly experimental. Use in production environments is discouraged.

    The perlcc tool has been rewritten so that the user interface is much more like that of a C compiler.

    The perlbc tools has been removed. Use perlcc -B instead.

    Lvalue subroutines

    There have been various bugfixes to support lvalue subroutines better. However, the feature still remains experimental.

    IO::Socket

    IO::Socket::INET failed to open the specified port if the service name was not known. It now correctly uses the supplied port number as is.

    File::Find

    File::Find now chdir()s correctly when chasing symbolic links.

    xsubpp

    xsubpp now tolerates embedded POD sections.

    no Module;

    no Module; does not produce an error even if Module does not have an unimport() method. This parallels the behavior of use vis-a-vis import.

    Tests

    A large number of tests have been added.

    Core features

    untie() will now call an UNTIE() hook if it exists. See the perltie manpage for details.

    The -DT command line switch outputs copious tokenizing information. See the perlrun manpage.

    Arrays are now always interpolated in double-quotish strings. Previously, "foo@bar.com" used to be a fatal error at compile time, if an array @bar was not used or declared. This transitional behavior was intended to help migrate perl4 code, and is deemed to be no longer useful. See Arrays now always interpolate into double-quoted strings.

    keys(), each(), pop(), push(), shift(), splice() and unshift() can all be overridden now.

    my __PACKAGE__ $obj now does the expected thing.

    Configuration issues

    On some systems (IRIX and Solaris among them) the system malloc is demonstrably better. While the defaults haven't been changed in order to retain binary compatibility with earlier releases, you may be better off building perl with Configure -Uusemymalloc ... as discussed in the INSTALL file.

    Configure has been enhanced in various ways:

    • Minimizes use of temporary files.

    • By default, does not link perl with libraries not used by it, such as the various dbm libraries. SunOS 4.x hints preserve behavior on that platform.

    • Support for pdp11-style memory models has been removed due to obsolescence.

    • Building outside the source tree is supported on systems that have symbolic links. This is done by running

          sh /path/to/source/Configure -Dmksymlinks ...
    make all test install

      in a directory other than the perl source directory. See INSTALL.

    • Configure -S can be run non-interactively.

    Documentation

    README.aix, README.solaris and README.macos have been added. README.posix-bc has been renamed to README.bs2000. These are installed as the perlaix manpage, the perlsolaris manpage, the perlmacos manpage, and the perlbs2000 manpage respectively.

    The following pod documents are brand new:

        perlclib    Internal replacements for standard C library functions
    perldebtut  Perl debugging tutorial
    perlebcdic  Considerations for running Perl on EBCDIC platforms
    perlnewmod  Perl modules: preparing a new module for distribution
    perlrequick Perl regular expressions quick start
    perlretut   Perl regular expressions tutorial
    perlutil    utilities packaged with the Perl distribution

    The INSTALL file has been expanded to cover various issues, such as 64-bit support.

    A longer list of contributors has been added to the source distribution. See the file AUTHORS.

    Numerous other changes have been made to the included documentation and FAQs.

    Bundled modules

    The following modules have been added.

    B::Concise

    Walks Perl syntax tree, printing concise info about ops. See the B::Concise manpage.

    File::Temp

    Returns name and handle of a temporary file safely. See the File::Temp manpage.

    Pod::LaTeX

    Converts Pod data to formatted LaTeX. See the Pod::LaTeX manpage.

    Pod::Text::Overstrike

    Converts POD data to formatted overstrike text. See the Pod::Text::Overstrike manpage.

    The following modules have been upgraded.

    CGI

    CGI v2.752 is now included.

    CPAN

    CPAN v1.59_54 is now included.

    Class::Struct

    Various bugfixes have been added.

    DB_File

    DB_File v1.75 supports newer Berkeley DB versions, among other improvements.

    Devel::Peek

    Devel::Peek has been enhanced to support dumping of memory statistics, when perl is built with the included malloc().

    File::Find

    File::Find now supports pre and post-processing of the files in order to sort() them, etc.

    Getopt::Long

    Getopt::Long v2.25 is included.

    IO::Poll

    Various bug fixes have been included.

    IPC::Open3

    IPC::Open3 allows use of numeric file descriptors.

    Math::BigFloat

    The fmod() function supports modulus operations. Various bug fixes have also been included.

    Math::Complex

    Math::Complex handles inf, NaN etc., better.

    Net::Ping

    ping() could fail on odd number of data bytes, and when the echo service isn't running. This has been corrected.

    Opcode

    A memory leak has been fixed.

    Pod::Parser

    Version 1.13 of the Pod::Parser suite is included.

    Pod::Text

    Pod::Text and related modules have been upgraded to the versions in podlators suite v2.08.

    SDBM_File

    On dosish platforms, some keys went missing because of lack of support for files with "holes". A workaround for the problem has been added.

    Sys::Syslog

    Various bug fixes have been included.

    Tie::RefHash

    Now supports Tie::RefHash::Nestable to automagically tie hashref values.

    Tie::SubstrHash

    Various bug fixes have been included.

    Platform-specific improvements

    The following new ports are now available.

    NCR MP-RAS
    NonStop-UX

    Perl now builds under Amdahl UTS.

    Perl has also been verified to build under Amiga OS.

    Support for EPOC has been much improved. See README.epoc.

    Building perl with -Duseithreads or -Duse5005threads now works under HP-UX 10.20 (previously it only worked under 10.30 or later). You will need a thread library package installed. See README.hpux.

    Long doubles should now work under Linux.

    Mac OS Classic is now supported in the mainstream source package. See README.macos.

    Support for MPE/iX has been updated. See README.mpeix.

    Support for OS/2 has been improved. See os2/Changes and README.os2.

    Dynamic loading on z/OS (formerly OS/390) has been improved. See README.os390.

    Support for VMS has seen many incremental improvements, including better support for operators like backticks and system(), and better %ENV handling. See README.vms and the perlvms manpage.

    Support for Stratus VOS has been improved. See vos/Changes and README.vos.

    Support for Windows has been improved.

    • fork() emulation has been improved in various ways, but still continues to be experimental. See the perlfork manpage for known bugs and caveats.

    • %SIG has been enabled under USE_ITHREADS, but its use is completely unsupported under all configurations.

    • Borland C++ v5.5 is now a supported compiler that can build Perl. However, the generated binaries continue to be incompatible with those generated by the other supported compilers (GCC and Visual C++).

    • Non-blocking waits for child processes (or pseudo-processes) are supported via waitpid($pid, &POSIX::WNOHANG).

    • A memory leak in accept() has been fixed.

    • wait(), waitpid() and backticks now return the correct exit status under Windows 9x.

    • Trailing new %ENV entries weren't propagated to child processes. This is now fixed.

    • Current directory entries in %ENV are now correctly propagated to child processes.

    • Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.

    • The makefiles now provide a single switch to bulk-enable all the features enabled in ActiveState ActivePerl (a popular binary distribution).

    • Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root. Other bugs in chdir() and Cwd::cwd() have also been fixed.

    • fork() correctly returns undef and sets EAGAIN when it runs out of pseudo-process handles.

    • ExtUtils::MakeMaker now uses $ENV{LIB} to search for libraries.

    • UNC path handling is better when perl is built to support fork().

    • A handle leak in socket handling has been fixed.

    • send() works from within a pseudo-process.

    Unless specifically qualified otherwise, the remainder of this document covers changes between the 5.005 and 5.6.0 releases.

    Core Enhancements

    Interpreter cloning, threads, and concurrency

    Perl 5.6.0 introduces the beginnings of support for running multiple interpreters concurrently in different threads. In conjunction with the perl_clone() API call, which can be used to selectively duplicate the state of any given interpreter, it is possible to compile a piece of code once in an interpreter, clone that interpreter one or more times, and run all the resulting interpreters in distinct threads.

    On the Windows platform, this feature is used to emulate fork() at the interpreter level. See the perlfork manpage for details about that.

    This feature is still in evolution. It is eventually meant to be used to selectively clone a subroutine and data reachable from that subroutine in a separate interpreter and run the cloned subroutine in a separate thread. Since there is no shared data between the interpreters, little or no locking will be needed (unless parts of the symbol table are explicitly shared). This is obviously intended to be an easy-to-use replacement for the existing threads support.

    Support for cloning interpreters and interpreter concurrency can be enabled using the -Dusethreads Configure option (see win32/Makefile for how to enable it on Windows.) The resulting perl executable will be functionally identical to one that was built with -Dmultiplicity, but the perl_clone() API call will only be available in the former.

    -Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn enables Perl source code changes that provide a clear separation between the op tree and the data it operates with. The former is immutable, and can therefore be shared between an interpreter and all of its clones, while the latter is considered local to each interpreter, and is therefore copied for each clone.

    Note that building Perl with the -Dusemultiplicity Configure option is adequate if you wish to run multiple independent interpreters concurrently in different threads. -Dusethreads only provides the additional functionality of the perl_clone() API call and other support for running cloned interpreters concurrently.

        NOTE: This is an experimental feature.  Implementation details are
    subject to change.

    Lexically scoped warning categories

    You can now control the granularity of warnings emitted by perl at a finer level using the use warnings pragma. the warnings manpage and the perllexwarn manpage have copious documentation on this feature.

    Unicode and UTF-8 support

    Perl now uses UTF-8 as its internal representation for character strings. The utf8 and bytes pragmas are used to control this support in the current lexical scope. See the perlunicode manpage, the utf8 manpage and the bytes manpage for more information.

    This feature is expected to evolve quickly to support some form of I/O disciplines that can be used to specify the kind of input and output data (bytes or characters). Until that happens, additional modules from CPAN will be needed to complete the toolkit for dealing with Unicode.

        NOTE: This should be considered an experimental feature.  Implementation
    details are subject to change.

    Support for interpolating named characters

    The new \N escape interpolates named characters within strings. For example, "Hi! \N{WHITE SMILING FACE}" evaluates to a string with a Unicode smiley face at the end.

    "our" declarations

    An "our" declaration introduces a value that can be best understood as a lexically scoped symbolic alias to a global variable in the package that was current where the variable was declared. This is mostly useful as an alternative to the vars pragma, but also provides the opportunity to introduce typing and other attributes for such variables. See our in the perlfunc manpage.

    Support for strings represented as a vector of ordinals

    Literals of the form v1.2.3.4 are now parsed as a string composed of characters with the specified ordinals. This is an alternative, more readable way to construct (possibly Unicode) strings instead of interpolating characters, as in "\x{1}\x{2}\x{3}\x{4}". The leading v may be omitted if there are more than two ordinals, so 1.2.3 is parsed the same as v1.2.3.

    Strings written in this form are also useful to represent version "numbers". It is easy to compare such version "numbers" (which are really just plain strings) using any of the usual string comparison operators eq, ne, lt, gt, etc., or perform bitwise string operations on them using |, &, etc.

    In conjunction with the new $^V magic variable (which contains the perl version as a string), such literals can be used as a readable way to check if you're running a particular version of Perl:

        # this will parse in older versions of Perl also
    if ($^V and $^V gt v5.6.0) {
        # new features supported
    }

    require and use also have some special magic to support such literals. They will be interpreted as a version rather than as a module name:

        require v5.6.0;             # croak if $^V lt v5.6.0
    use v5.6.0;                 # same, but croaks at compile-time

    Alternatively, the v may be omitted if there is more than one dot:

        require 5.6.0;
    use 5.6.0;

    Also, sprintf and printf support the Perl-specific format flag %v to print ordinals of characters in arbitrary strings:

        printf "v%vd", $^V;         # prints current version, such as "v5.5.650"
    printf "%*vX", ":", $addr;  # formats IPv6 address
    printf "%*vb", " ", $bits;  # displays bitstring

    See Scalar value constructors in the perldata manpage for additional information.

    Improved Perl version numbering system

    Beginning with Perl version 5.6.0, the version number convention has been changed to a "dotted integer" scheme that is more commonly found in open source projects.

    Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc. The next development series following v5.6.0 will be numbered v5.7.x, beginning with v5.7.0, and the next major production release following v5.6.0 will be v5.8.0.

    The English module now sets $PERL_VERSION to $^V (a string value) rather than $] (a numeric value). (This is a potential incompatibility. Send us a report via perlbug if you are affected by this.)

    The v1.2.3 syntax is also now legal in Perl. See Support for strings represented as a vector of ordinals for more on that.

    To cope with the new versioning system's use of at least three significant digits for each version component, the method used for incrementing the subversion number has also changed slightly. We assume that versions older than v5.6.0 have been incrementing the subversion component in multiples of 10. Versions after v5.6.0 will increment them by 1. Thus, using the new notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance version following v5.6.0 will be v5.6.1 (which should be read as being equivalent to a floating point value of 5.006_001 in the older format, stored in $]).

    New syntax for declaring subroutine attributes

    Formerly, if you wanted to mark a subroutine as being a method call or as requiring an automatic lock() when it is entered, you had to declare that with a use attrs pragma in the body of the subroutine. That can now be accomplished with declaration syntax, like this:

        sub mymethod : locked method;
    ...
    sub mymethod : locked method {
        ...
    }

        sub othermethod :locked :method;
    ...
    sub othermethod :locked :method {
        ...
    }

    (Note how only the first : is mandatory, and whitespace surrounding the : is optional.)

    AutoSplit.pm and SelfLoader.pm have been updated to keep the attributes with the stubs they provide. See the attributes manpage.

    File and directory handles can be autovivified

    Similar to how constructs such as $x->[0] autovivify a reference, handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(), socket(), and accept()) now autovivify a file or directory handle if the handle passed to them is an uninitialized scalar variable. This allows the constructs such as open(my $fh, ...) and open(local $fh,...) to be used to create filehandles that will conveniently be closed automatically when the scope ends, provided there are no other references to them. This largely eliminates the need for typeglobs when opening filehandles that must be passed around, as in the following example:

        sub myopen {
        open my $fh, "@_"
             or die "Can't open '@_': $!";
        return $fh;
    }

        {
        my $f = myopen("</etc/motd");
        print <$f>;
        # $f implicitly closed here
    }

    open() with more than two arguments

    If open() is passed three arguments instead of two, the second argument is used as the mode and the third argument is taken to be the file name. This is primarily useful for protecting against unintended magic behavior of the traditional two-argument form. See open in the perlfunc manpage.

    64-bit support

    Any platform that has 64-bit integers either

            (1) natively as longs or ints
        (2) via special compiler flags
        (3) using long long or int64_t

    is able to use "quads" (64-bit integers) as follows:

    • constants (decimal, hexadecimal, octal, binary) in the code

    • arguments to oct() and hex()

    • arguments to print(), printf() and sprintf() (flag prefixes ll, L, q)

    • printed as such

    • pack() and unpack() "q" and "Q" formats

    • in basic arithmetics: + - * / % (NOTE: operating close to the limits of the integer values may produce surprising results)

    • in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced to be 32 bits wide but now operate on the full native width.)

    • vec()

    Note that unless you have the case (a) you will have to configure and compile Perl using the -Duse64bitint Configure flag.

        NOTE: The Configure flags -Duselonglong and -Duse64bits have been
    deprecated.  Use -Duse64bitint instead.

    There are actually two modes of 64-bitness: the first one is achieved using Configure -Duse64bitint and the second one using Configure -Duse64bitall. The difference is that the first one is minimal and the second one maximal. The first works in more places than the second.

    The use64bitint does only as much as is required to get 64-bit integers into Perl (this may mean, for example, using "long longs") while your memory may still be limited to 2 gigabytes (because your pointers could still be 32-bit). Note that the name 64bitint does not imply that your C compiler will be using 64-bit ints (it might, but it doesn't have to): the use64bitint means that you will be able to have 64 bits wide scalar values.

    The use64bitall goes all the way by attempting to switch also integers (if it can), longs (and pointers) to being 64-bit. This may create an even more binary incompatible Perl than -Duse64bitint: the resulting executable may not run at all in a 32-bit box, or you may have to reboot/reconfigure/rebuild your operating system to be 64-bit aware.

    Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint nor -Duse64bitall.

    Last but not least: note that due to Perl's habit of always using floating point numbers, the quads are still not true integers. When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned, -9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they are silently promoted to floating point numbers, after which they will start losing precision (in their lower digits).

        NOTE: 64-bit support is still experimental on most platforms.
    Existing support only covers the LP64 data model.  In particular, the
    LLP64 data model is not yet supported.  64-bit libraries and system
    APIs on many platforms have not stabilized--your mileage may vary.

    Large file support

    If you have filesystems that support "large files" (files larger than 2 gigabytes), you may now also be able to create and access them from Perl.

        NOTE: The default action is to enable large file support, if
    available on the platform.

    If the large file support is on, and you have a Fcntl constant O_LARGEFILE, the O_LARGEFILE is automatically added to the flags of sysopen().

    Beware that unless your filesystem also supports "sparse files" seeking to umpteen petabytes may be inadvisable.

    Note that in addition to requiring a proper file system to do large files you may also need to adjust your per-process (or your per-system, or per-process-group, or per-user-group) maximum filesize limits before running Perl scripts that try to handle large files, especially if you intend to write such files.

    Finally, in addition to your process/process group maximum filesize limits, you may have quota limits on your filesystems that stop you (your user id or your user group id) from using large files.

    Adjusting your process/user/group/file system/operating system limits is outside the scope of Perl core language. For process limits, you may try increasing the limits using your shell's limits/limit/ulimit command before running Perl. The BSD::Resource extension (not included with the standard Perl distribution) may also be of use, it offers the getrlimit/setrlimit interface that can be used to adjust process resource usage limits, including the maximum filesize limit.

    Long doubles

    In some systems you may be able to use long doubles to enhance the range and precision of your double precision floating point numbers (that is, Perl's numbers). Use Configure -Duselongdouble to enable this support (if it is available).

    "more bits"

    You can "Configure -Dusemorebits" to turn on both the 64-bit support and the long double support.

    Enhanced support for sort() subroutines

    Perl subroutines with a prototype of ($$), and XSUBs in general, can now be used as sort subroutines. In either case, the two elements to be compared are passed as normal parameters in @_. See sort in the perlfunc manpage.

    For unprototyped sort subroutines, the historical behavior of passing the elements to be compared as the global variables $a and $b remains unchanged.

    sort $coderef @foo allowed

    sort() did not accept a subroutine reference as the comparison function in earlier versions. This is now permitted.

    File globbing implemented internally

    Perl now uses the File::Glob implementation of the glob() operator automatically. This avoids using an external csh process and the problems associated with it.

        NOTE: This is currently an experimental feature.  Interfaces and
    implementation are subject to change.

    Support for CHECK blocks

    In addition to BEGIN, INIT, END, DESTROY and AUTOLOAD, subroutines named CHECK are now special. These are queued up during compilation and behave similar to END blocks, except they are called at the end of compilation rather than at the end of execution. They cannot be called directly.

    POSIX character class syntax [: :] supported

    For example to match alphabetic characters use /[[:alpha:]]/. See the perlre manpage for details.

    Better pseudo-random number generator

    In 5.005_0x and earlier, perl's rand() function used the C library rand(3) function. As of 5.005_52, Configure tests for drand48(), random(), and rand() (in that order) and picks the first one it finds.

    These changes should result in better random numbers from rand().

    Improved qw// operator

    The qw// operator is now evaluated at compile time into a true list instead of being replaced with a run time call to split(). This removes the confusing misbehaviour of qw// in scalar context, which had inherited that behaviour from split().

    Thus:

        $foo = ($bar) = qw(a b c); print "$foo|$bar\n";

    now correctly prints "3|a", instead of "2|a".

    Better worst-case behavior of hashes

    Small changes in the hashing algorithm have been implemented in order to improve the distribution of lower order bits in the hashed value. This is expected to yield better performance on keys that are repeated sequences.

    pack() format 'Z' supported

    The new format type 'Z' is useful for packing and unpacking null-terminated strings. See pack in the perlfunc manpage.

    pack() format modifier '!' supported

    The new format type modifier '!' is useful for packing and unpacking native shorts, ints, and longs. See pack in the perlfunc manpage.

    pack() and unpack() support counted strings

    The template character '/' can be used to specify a counted string type to be packed or unpacked. See pack in the perlfunc manpage.

    Comments in pack() templates

    The '#' character in a template introduces a comment up to end of the line. This facilitates documentation of pack() templates.

    Weak references

    In previous versions of Perl, you couldn't cache objects so as to allow them to be deleted if the last reference from outside the cache is deleted. The reference in the cache would hold a reference count on the object and the objects would never be destroyed.

    Another familiar problem is with circular references. When an object references itself, its reference count would never go down to zero, and it would not get destroyed until the program is about to exit.

    Weak references solve this by allowing you to "weaken" any reference, that is, make it not count towards the reference count. When the last non-weak reference to an object is deleted, the object is destroyed and all the weak references to the object are automatically undef-ed.

    To use this feature, you need the Devel::WeakRef package from CPAN, which contains additional documentation.

        NOTE: This is an experimental feature.  Details are subject to change.

    Binary numbers supported

    Binary numbers are now supported as literals, in s?printf formats, and oct():

        $answer = 0b101010;
    printf "The answer is: %b\n", oct("0b101010");

    Lvalue subroutines

    Subroutines can now return modifiable lvalues. See Lvalue subroutines in the perlsub manpage.

        NOTE: This is an experimental feature.  Details are subject to change.

    Some arrows may be omitted in calls through references

    Perl now allows the arrow to be omitted in many constructs involving subroutine calls through references. For example, $foo[10]->('foo') may now be written $foo[10]('foo'). This is rather similar to how the arrow may be omitted from $foo[10]->{'foo'}. Note however, that the arrow is still required for foo(10)->('bar').

    Boolean assignment operators are legal lvalues

    Constructs such as ($a ||= 2) += 1 are now allowed.

    exists() is supported on subroutine names

    The exists() builtin now works on subroutine names. A subroutine is considered to exist if it has been declared (even if implicitly). See exists in the perlfunc manpage for examples.

    exists() and delete() are supported on array elements

    The exists() and delete() builtins now work on simple arrays as well. The behavior is similar to that on hash elements.

    exists() can be used to check whether an array element has been initialized. This avoids autovivifying array elements that don't exist. If the array is tied, the EXISTS() method in the corresponding tied package will be invoked.

    delete() may be used to remove an element from the array and return it. The array element at that position returns to its uninitialized state, so that testing for the same element with exists() will return false. If the element happens to be the one at the end, the size of the array also shrinks up to the highest element that tests true for exists(), or 0 if none such is found. If the array is tied, the DELETE() method in the corresponding tied package will be invoked.

    See exists in the perlfunc manpage and delete in the perlfunc manpage for examples.

    Pseudo-hashes work better

    Dereferencing some types of reference values in a pseudo-hash, such as $ph->{foo}[1], was accidentally disallowed. This has been corrected.

    When applied to a pseudo-hash element, exists() now reports whether the specified value exists, not merely if the key is valid.

    delete() now works on pseudo-hashes. When given a pseudo-hash element or slice it deletes the values corresponding to the keys (but not the keys themselves). See Pseudo-hashes: Using an array as a hash in the perlref manpage.

    Pseudo-hash slices with constant keys are now optimized to array lookups at compile-time.

    List assignments to pseudo-hash slices are now supported.

    The fields pragma now provides ways to create pseudo-hashes, via fields::new() and fields::phash(). See the fields manpage.

        NOTE: The pseudo-hash data type continues to be experimental.
    Limiting oneself to the interface elements provided by the
    fields pragma will provide protection from any future changes.

    Automatic flushing of output buffers

    fork(), exec(), system(), qx//, and pipe open()s now flush buffers of all files opened for output when the operation was attempted. This mostly eliminates confusing buffering mishaps suffered by users unaware of how Perl internally handles I/O.

    This is not supported on some platforms like Solaris where a suitably correct implementation of fflush(NULL) isn't available.

    Better diagnostics on meaningless filehandle operations

    Constructs such as open(<FH>) and close(<FH>) are compile time errors. Attempting to read from filehandles that were opened only for writing will now produce warnings (just as writing to read-only filehandles does).

    Where possible, buffered data discarded from duped input filehandle

    open(NEW, "<&OLD") now attempts to discard any data that was previously read and buffered in OLD before duping the handle. On platforms where doing this is allowed, the next read operation on NEW will return the same data as the corresponding operation on OLD. Formerly, it would have returned the data from the start of the following disk block instead.

    eof() has the same old magic as <>

    eof() would return true if no attempt to read from <> had yet been made. eof() has been changed to have a little magic of its own, it now opens the <> files.

    binmode() can be used to set :crlf and :raw modes

    binmode() now accepts a second argument that specifies a discipline for the handle in question. The two pseudo-disciplines ":raw" and ":crlf" are currently supported on DOS-derivative platforms. See binmode in the perlfunc manpage and the open manpage.

    -T filetest recognizes UTF-8 encoded files as "text"

    The algorithm used for the -T filetest has been enhanced to correctly identify UTF-8 content as "text".

    system(), backticks and pipe open now reflect exec() failure

    On Unix and similar platforms, system(), qx() and open(FOO, "cmd |") etc., are implemented via fork() and exec(). When the underlying exec() fails, earlier versions did not report the error properly, since the exec() happened to be in a different process.

    The child process now communicates with the parent about the error in launching the external command, which allows these constructs to return with their usual error value and set $!.

    Improved diagnostics

    Line numbers are no longer suppressed (under most likely circumstances) during the global destruction phase.

    Diagnostics emitted from code running in threads other than the main thread are now accompanied by the thread ID.

    Embedded null characters in diagnostics now actually show up. They used to truncate the message in prior versions.

    $foo::a and $foo::b are now exempt from "possible typo" warnings only if sort() is encountered in package foo.

    Unrecognized alphabetic escapes encountered when parsing quote constructs now generate a warning, since they may take on new semantics in later versions of Perl.

    Many diagnostics now report the internal operation in which the warning was provoked, like so:

        Use of uninitialized value in concatenation (.) at (eval 1) line 1.
    Use of uninitialized value in print at (eval 1) line 1.

    Diagnostics that occur within eval may also report the file and line number where the eval is located, in addition to the eval sequence number and the line number within the evaluated text itself. For example:

        Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF

    Diagnostics follow STDERR

    Diagnostic output now goes to whichever file the STDERR handle is pointing at, instead of always going to the underlying C runtime library's stderr.

    More consistent close-on-exec behavior

    On systems that support a close-on-exec flag on filehandles, the flag is now set for any handles created by pipe(), socketpair(), socket(), and accept(), if that is warranted by the value of $^F that may be in effect. Earlier versions neglected to set the flag for handles created with these operators. See pipe in the perlfunc manpage, socketpair in the perlfunc manpage, socket in the perlfunc manpage, accept in the perlfunc manpage, and $^F in the perlvar manpage.

    syswrite() ease-of-use

    The length argument of syswrite() has become optional.

    Better syntax checks on parenthesized unary operators

    Expressions such as:

        print defined(&foo,&bar,&baz);
    print uc("foo","bar","baz");
    undef($foo,&bar);

    used to be accidentally allowed in earlier versions, and produced unpredictable behaviour. Some produced ancillary warnings when used in this way; others silently did the wrong thing.

    The parenthesized forms of most unary operators that expect a single argument now ensure that they are not called with more than one argument, making the cases shown above syntax errors. The usual behaviour of:

        print defined &foo, &bar, &baz;
    print uc "foo", "bar", "baz";
    undef $foo, &bar;

    remains unchanged. See the perlop manpage.

    Bit operators support full native integer width

    The bit operators (& | ^ ~ << >>) now operate on the full native integral width (the exact size of which is available in $Config{ivsize}). For example, if your platform is either natively 64-bit or if Perl has been configured to use 64-bit integers, these operations apply to 8 bytes (as opposed to 4 bytes on 32-bit platforms). For portability, be sure to mask off the excess bits in the result of unary ~, e.g., ~$x & 0xffffffff.

    Improved security features

    More potentially unsafe operations taint their results for improved security.

    The passwd and shell fields returned by the getpwent(), getpwnam(), and getpwuid() are now tainted, because the user can affect their own encrypted password and login shell.

    The variable modified by shmread(), and messages returned by msgrcv() (and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted, because other untrusted processes can modify messages and shared memory segments for their own nefarious purposes.

    More functional bareword prototype (*)

    Bareword prototypes have been rationalized to enable them to be used to override builtins that accept barewords and interpret them in a special way, such as require or do.

    Arguments prototyped as * will now be visible within the subroutine as either a simple scalar or as a reference to a typeglob. See Prototypes in the perlsub manpage.

    require and do may be overridden

    require and do 'file' operations may be overridden locally by importing subroutines of the same name into the current package (or globally by importing them into the CORE::GLOBAL:: namespace). Overriding require will also affect use, provided the override is visible at compile-time. See Overriding Built-in Functions in the perlsub manpage.

    $^X variables may now have names longer than one character

    Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax error. Now variable names that begin with a control character may be arbitrarily long. However, for compatibility reasons, these variables must be written with explicit braces, as ${^XY} for example. ${^XYZ} is synonymous with ${"\cXYZ"}. Variable names with more than one control character, such as ${^XY^Z}, are illegal.

    The old syntax has not changed. As before, `^X' may be either a literal control-X character or the two-character sequence `caret' plus `X'. When braces are omitted, the variable name stops after the control character. Thus "$^XYZ" continues to be synonymous with $^X . "YZ" as before.

    As before, lexical variables may not have names beginning with control characters. As before, variables whose names begin with a control character are always forced to be in package `main'. All such variables are reserved for future extensions, except those that begin with ^_, which may be used by user programs and are guaranteed not to acquire special meaning in any future version of Perl.

    New variable $^C reflects -c switch

    $^C has a boolean value that reflects whether perl is being run in compile-only mode (i.e. via the -c switch). Since BEGIN blocks are executed under such conditions, this variable enables perl code to determine whether actions that make sense only during normal running are warranted. See the perlvar manpage.

    New variable $^V contains Perl version as a string

    $^V contains the Perl version number as a string composed of characters whose ordinals match the version numbers, i.e. v5.6.0. This may be used in string comparisons.

    See Support for strings represented as a vector of ordinals for an example.

    Optional Y2K warnings

    If Perl is built with the cpp macro PERL_Y2KWARN defined, it emits optional warnings when concatenating the number 19 with another number.

    This behavior must be specifically enabled when running Configure. See INSTALL and README.Y2K.

    Arrays now always interpolate into double-quoted strings

    In double-quoted strings, arrays now interpolate, no matter what. The behavior in earlier versions of perl 5 was that arrays would interpolate into strings if the array had been mentioned before the string was compiled, and otherwise Perl would raise a fatal compile-time error. In versions 5.000 through 5.003, the error was

            Literal @example now requires backslash

    In versions 5.004_01 through 5.6.0, the error was

            In string, @example now must be written as \@example

    The idea here was to get people into the habit of writing "fred\@example.com" when they wanted a literal @ sign, just as they have always written "Give me back my \$5" when they wanted a literal $ sign.

    Starting with 5.6.1, when Perl now sees an @ sign in a double-quoted string, it always attempts to interpolate an array, regardless of whether or not the array has been used or declared already. The fatal error has been downgraded to an optional warning:

            Possible unintended interpolation of @example in string

    This warns you that "fred@example.com" is going to turn into fred.com if you don't backslash the @. See http://www.plover.com/~mjd/perl/at-error.html for more details about the history here.

    @- and @+ provide starting/ending offsets of regex submatches

    The new magic variables @- and @+ provide the starting and ending offsets, respectively, of $&, $1, $2, etc. See the perlvar manpage for details.

    Modules and Pragmata

    Modules

    attributes

    While used internally by Perl as a pragma, this module also provides a way to fetch subroutine and variable attributes. See the attributes manpage.

    B

    The Perl Compiler suite has been extensively reworked for this release. More of the standard Perl testsuite passes when run under the Compiler, but there is still a significant way to go to achieve production quality compiled executables.

        NOTE: The Compiler suite remains highly experimental.  The
    generated code may not be correct, even when it manages to execute
    without errors.
    Benchmark

    Overall, Benchmark results exhibit lower average error and better timing accuracy.

    You can now run tests for n seconds instead of guessing the right number of tests to run: e.g., timethese(-5, ...) will run each code for at least 5 CPU seconds. Zero as the "number of repetitions" means "for at least 3 CPU seconds". The output format has also changed. For example:

       use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})

    will now output something like this:

       Benchmark: running a, b, each for at least 5 CPU seconds...
            a:  5 wallclock secs ( 5.77 usr +  0.00 sys =  5.77 CPU) @ 200551.91/s (n=1156516)
            b:  4 wallclock secs ( 5.00 usr +  0.02 sys =  5.02 CPU) @ 159605.18/s (n=800686)

    New features: "each for at least N CPU seconds...", "wallclock secs", and the "@ operations/CPU second (n=operations)".

    timethese() now returns a reference to a hash of Benchmark objects containing the test results, keyed on the names of the tests.

    timethis() now returns the iterations field in the Benchmark result object instead of 0.

    timethese(), timethis(), and the new cmpthese() (see below) can also take a format specifier of 'none' to suppress output.

    A new function countit() is just like timeit() except that it takes a TIME instead of a COUNT.

    A new function cmpthese() prints a chart comparing the results of each test returned from a timethese() call. For each possible pair of tests, the percentage speed difference (iters/sec or seconds/iter) is shown.

    For other details, see the Benchmark manpage.

    ByteLoader

    The ByteLoader is a dedicated extension to generate and run Perl bytecode. See the ByteLoader manpage.

    constant

    References can now be used.

    The new version also allows a leading underscore in constant names, but disallows a double leading underscore (as in "__LINE__"). Some other names are disallowed or warned against, including BEGIN, END, etc. Some names which were forced into main:: used to fail silently in some cases; now they're fatal (outside of main::) and an optional warning (inside of main::). The ability to detect whether a constant had been set with a given name has been added.

    See the constant manpage.

    charnames

    This pragma implements the \N string escape. See the charnames manpage.

    Data::Dumper

    A Maxdepth setting can be specified to avoid venturing too deeply into deep data structures. See the Data::Dumper manpage.

    The XSUB implementation of Dump() is now automatically called if the Useqq setting is not in use.

    Dumping qr// objects works correctly.

    DB

    DB is an experimental module that exposes a clean abstraction to Perl's debugging API.

    DB_File

    DB_File can now be built with Berkeley DB versions 1, 2 or 3. See ext/DB_File/Changes.

    Devel::DProf

    Devel::DProf, a Perl source code profiler has been added. See the Devel::DProf manpage and the dprofpp manpage.

    Devel::Peek

    The Devel::Peek module provides access to the internal representation of Perl variables and data. It is a data debugging tool for the XS programmer.

    Dumpvalue

    The Dumpvalue module provides screen dumps of Perl data.

    DynaLoader

    DynaLoader now supports a dl_unload_file() function on platforms that support unloading shared objects using dlclose().

    Perl can also optionally arrange to unload all extension shared objects loaded by Perl. To enable this, build Perl with the Configure option -Accflags=-DDL_UNLOAD_ALL_AT_EXIT. (This maybe useful if you are using Apache with mod_perl.)

    English

    $PERL_VERSION now stands for $^V (a string value) rather than for $] (a numeric value).

    Env

    Env now supports accessing environment variables like PATH as array variables.

    Fcntl

    More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for large file (more than 4GB) access (NOTE: the O_LARGEFILE is automatically added to sysopen() flags if large file support has been configured, as is the default), Free/Net/OpenBSD locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined mask of O_RDONLY, O_WRONLY, and O_RDWR. The seek()/sysseek() constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the :seek tag. The chmod()/stat() S_IF* constants and S_IS* functions are available via the :mode tag.

    File::Compare

    A compare_text() function has been added, which allows custom comparison functions. See the File::Compare manpage.

    File::Find

    File::Find now works correctly when the wanted() function is either autoloaded or is a symbolic reference.

    A bug that caused File::Find to lose track of the working directory when pruning top-level directories has been fixed.

    File::Find now also supports several other options to control its behavior. It can follow symbolic links if the follow option is specified. Enabling the no_chdir option will make File::Find skip changing the current directory when walking directories. The untaint flag can be useful when running with taint checks enabled.

    See the File::Find manpage.

    File::Glob

    This extension implements BSD-style file globbing. By default, it will also be used for the internal implementation of the glob() operator. See the File::Glob manpage.

    File::Spec

    New methods have been added to the File::Spec module: devnull() returns the name of the null device (/dev/null on Unix) and tmpdir() the name of the temp directory (normally /tmp on Unix). There are now also methods to convert between absolute and relative filenames: abs2rel() and rel2abs(). For compatibility with operating systems that specify volume names in file paths, the splitpath(), splitdir(), and catdir() methods have been added.

    File::Spec::Functions

    The new File::Spec::Functions modules provides a function interface to the File::Spec module. Allows shorthand

        $fullname = catfile($dir1, $dir2, $file);

    instead of

        $fullname = File::Spec->catfile($dir1, $dir2, $file);
    Getopt::Long

    Getopt::Long licensing has changed to allow the Perl Artistic License as well as the GPL. It used to be GPL only, which got in the way of non-GPL applications that wanted to use Getopt::Long.

    Getopt::Long encourages the use of Pod::Usage to produce help messages. For example:

        use Getopt::Long;
    use Pod::Usage;
    my $man = 0;
    my $help = 0;
    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
    pod2usage(1) if $help;
    pod2usage(-exitstatus => 0, -verbose => 2) if $man;

        __END__
        =head1 NAME
        sample - Using Getopt::Long and Pod::Usage
        =head1 SYNOPSIS
        sample [options] [file ...]
         Options:
       -help            brief help message
       -man             full documentation
        =head1 OPTIONS
        =over 8
        =item B<-help>
        Print a brief help message and exits.
        =item B<-man>
        Prints the manual page and exits.
        =back
        =head1 DESCRIPTION
        B<This program> will read the given input file(s) and do something
    useful with the contents thereof.
        =cut

    See the Pod::Usage manpage for details.

    A bug that prevented the non-option call-back <> from being specified as the first argument has been fixed.

    To specify the characters < and > as option starters, use ><. Note, however, that changing option starters is strongly deprecated.

    IO

    write() and syswrite() will now accept a single-argument form of the call, for consistency with Perl's syswrite().

    You can now create a TCP-based IO::Socket::INET without forcing a connect attempt. This allows you to configure its options (like making it non-blocking) and then call connect() manually.

    A bug that prevented the IO::Socket::protocol() accessor from ever returning the correct value has been corrected.

    IO::Socket::connect now uses non-blocking IO instead of alarm() to do connect timeouts.

    IO::Socket::accept now uses select() instead of alarm() for doing timeouts.

    IO::Socket::INET->new now sets $! correctly on failure. $@ is still set for backwards compatibility.

    JPL

    Java Perl Lingo is now distributed with Perl. See jpl/README for more information.

    lib

    use lib now weeds out any trailing duplicate entries. no lib removes all named entries.

    Math::BigInt

    The bitwise operations <<, >>, &, |, and ~ are now supported on bigints.

    Math::Complex

    The accessor methods Re, Im, arg, abs, rho, and theta can now also act as mutators (accessor $z->Re(), mutator $z->Re(3)).

    The class method display_format and the corresponding object method display_format, in addition to accepting just one argument, now can also accept a parameter hash. Recognized keys of a parameter hash are "style", which corresponds to the old one parameter case, and two new parameters: "format", which is a printf()-style format string (defaults usually to "%.15g", you can revert to the default by setting the format string to undef) used for both parts of a complex number, and "polar_pretty_print" (defaults to true), which controls whether an attempt is made to try to recognize small multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a polar complex number.

    The potentially disruptive change is that in list context both methods now return the parameter hash, instead of only the value of the "style" parameter.

    Math::Trig

    A little bit of radial trigonometry (cylindrical and spherical), radial coordinate conversions, and the great circle distance were added.

    Pod::Parser, Pod::InputObjects

    Pod::Parser is a base class for parsing and selecting sections of pod documentation from an input stream. This module takes care of identifying pod paragraphs and commands in the input and hands off the parsed paragraphs and commands to user-defined methods which are free to interpret or translate them as they see fit.

    Pod::InputObjects defines some input objects needed by Pod::Parser, and for advanced users of Pod::Parser that need more about a command besides its name and text.

    As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned "base parser code" recommended for use by all pod2xxx translators. Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already underway. For any questions or comments about pod parsing and translating issues and utilities, please use the pod-people@perl.org mailing list.

    For further information, please see the Pod::Parser manpage and the Pod::InputObjects manpage.

    Pod::Checker, podchecker

    This utility checks pod files for correct syntax, according to the perlpod manpage. Obvious errors are flagged as such, while warnings are printed for mistakes that can be handled gracefully. The checklist is not complete yet. See the Pod::Checker manpage.

    Pod::ParseUtils, Pod::Find

    These modules provide a set of gizmos that are useful mainly for pod translators. Pod::Find traverses directory structures and returns found pod files, along with their canonical names (like File::Spec::Unix). Pod::ParseUtils contains Pod::List (useful for storing pod list information), Pod::Hyperlink (for parsing the contents of L<> sequences) and Pod::Cache (for caching information about pod files, e.g., link nodes).

    Pod::Select, podselect

    Pod::Select is a subclass of Pod::Parser which provides a function named "podselect()" to filter out user-specified sections of raw pod documentation from an input stream. podselect is a script that provides access to Pod::Select from other scripts to be used as a filter. See the Pod::Select manpage.

    Pod::Usage, pod2usage

    Pod::Usage provides the function "pod2usage()" to print usage messages for a Perl script based on its embedded pod documentation. The pod2usage() function is generally useful to all script authors since it lets them write and maintain a single source (the pods) for documentation, thus removing the need to create and maintain redundant usage message text consisting of information already in the pods.

    There is also a pod2usage script which can be used from other kinds of scripts to print usage messages from pods (even for non-Perl scripts with pods embedded in comments).

    For details and examples, please see the Pod::Usage manpage.

    Pod::Text and Pod::Man

    Pod::Text has been rewritten to use Pod::Parser. While pod2text() is still available for backwards compatibility, the module now has a new preferred interface. See the Pod::Text manpage for the details. The new Pod::Text module is easily subclassed for tweaks to the output, and two such subclasses (Pod::Text::Termcap for man-page-style bold and underlining using termcap information, and Pod::Text::Color for markup with ANSI color sequences) are now standard.

    pod2man has been turned into a module, Pod::Man, which also uses Pod::Parser. In the process, several outstanding bugs related to quotes in section headers, quoting of code escapes, and nested lists have been fixed. pod2man is now a wrapper script around this module.

    SDBM_File

    An EXISTS method has been added to this module (and sdbm_exists() has been added to the underlying sdbm library), so one can now call exists on an SDBM_File tied hash and get the correct result, rather than a runtime error.

    A bug that may have caused data loss when more than one disk block happens to be read from the database in a single FETCH() has been fixed.

    Sys::Syslog

    Sys::Syslog now uses XSUBs to access facilities from syslog.h so it no longer requires syslog.ph to exist.

    Sys::Hostname

    Sys::Hostname now uses XSUBs to call the C library's gethostname() or uname() if they exist.

    Term::ANSIColor

    Term::ANSIColor is a very simple module to provide easy and readable access to the ANSI color and highlighting escape sequences, supported by most ANSI terminal emulators. It is now included standard.

    Time::Local

    The timelocal() and timegm() functions used to silently return bogus results when the date fell outside the machine's integer range. They now consistently croak() if the date falls in an unsupported range.

    Win32

    The error return value in list context has been changed for all functions that return a list of values. Previously these functions returned a list with a single element undef if an error occurred. Now these functions return the empty list in these situations. This applies to the following functions:

        Win32::FsType
    Win32::GetOSVersion

    The remaining functions are unchanged and continue to return undef on error even in list context.

    The Win32::SetLastError(ERROR) function has been added as a complement to the Win32::GetLastError() function.

    The new Win32::GetFullPathName(FILENAME) returns the full absolute pathname for FILENAME in scalar context. In list context it returns a two-element list containing the fully qualified directory name and the filename. See the Win32 manpage.

    XSLoader

    The XSLoader extension is a simpler alternative to DynaLoader. See the XSLoader manpage.

    DBM Filters

    A new feature called "DBM Filters" has been added to all the DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File. DBM Filters add four new methods to each DBM module:

        filter_store_key
    filter_store_value
    filter_fetch_key
    filter_fetch_value

    These can be used to filter key-value pairs before the pairs are written to the database or just after they are read from the database. See the perldbmfilter manpage for further information.

    Pragmata

    use attrs is now obsolete, and is only provided for backward-compatibility. It's been replaced by the sub : attributes syntax. See Subroutine Attributes in the perlsub manpage and the attributes manpage.

    Lexical warnings pragma, use warnings;, to control optional warnings. See the perllexwarn manpage.

    use filetest to control the behaviour of filetests (-r -w ...). Currently only one subpragma implemented, "use filetest 'access';", that uses access(2) or equivalent to check permissions instead of using stat(2) as usual. This matters in filesystems where there are ACLs (access control lists): the stat(2) might lie, but access(2) knows better.

    The open pragma can be used to specify default disciplines for handle constructors (e.g. open()) and for qx//. The two pseudo-disciplines :raw and :crlf are currently supported on DOS-derivative platforms (i.e. where binmode is not a no-op). See also binmode() can be used to set :crlf and :raw modes.

    Utility Changes

    dprofpp

    dprofpp is used to display profile data generated using Devel::DProf. See the dprofpp manpage.

    find2perl

    The find2perl utility now uses the enhanced features of the File::Find module. The -depth and -follow options are supported. Pod documentation is also included in the script.

    h2xs

    The h2xs tool can now work in conjunction with C::Scan (available from CPAN) to automatically parse real-life header files. The -M, -a, -k, and -o options are new.

    perlcc

    perlcc now supports the C and Bytecode backends. By default, it generates output from the simple C backend rather than the optimized C backend.

    Support for non-Unix platforms has been improved.

    perldoc

    perldoc has been reworked to avoid possible security holes. It will not by default let itself be run as the superuser, but you may still use the -U switch to try to make it drop privileges first.

    The Perl Debugger

    Many bug fixes and enhancements were added to perl5db.pl, the Perl debugger. The help documentation was rearranged. New commands include < ?, > ?, and { ? to list out current actions, man docpage to run your doc viewer on some perl docset, and support for quoted options. The help information was rearranged, and should be viewable once again if you're using less as your pager. A serious security hole was plugged--you should immediately remove all older versions of the Perl debugger as installed in previous releases, all the way back to perl3, from your system to avoid being bitten by this.

    Improved Documentation

    Many of the platform-specific README files are now part of the perl installation. See the perl manpage for the complete list.

    perlapi.pod

    The official list of public Perl API functions.

    perlboot.pod

    A tutorial for beginners on object-oriented Perl.

    perlcompile.pod

    An introduction to using the Perl Compiler suite.

    perldbmfilter.pod

    A howto document on using the DBM filter facility.

    perldebug.pod

    All material unrelated to running the Perl debugger, plus all low-level guts-like details that risked crushing the casual user of the debugger, have been relocated from the old manpage to the next entry below.

    perldebguts.pod

    This new manpage contains excessively low-level material not related to the Perl debugger, but slightly related to debugging Perl itself. It also contains some arcane internal details of how the debugging process works that may only be of interest to developers of Perl debuggers.

    perlfork.pod

    Notes on the fork() emulation currently available for the Windows platform.

    perlfilter.pod

    An introduction to writing Perl source filters.

    perlhack.pod

    Some guidelines for hacking the Perl source code.

    perlintern.pod

    A list of internal functions in the Perl source code. (List is currently empty.)

    perllexwarn.pod

    Introduction and reference information about lexically scoped warning categories.

    perlnumber.pod

    Detailed information about numbers as they are represented in Perl.

    perlopentut.pod

    A tutorial on using open() effectively.

    perlreftut.pod

    A tutorial that introduces the essentials of references.

    perltootc.pod

    A tutorial on managing class data for object modules.

    perltodo.pod

    Discussion of the most often wanted features that may someday be supported in Perl.

    perlunicode.pod

    An introduction to Unicode support features in Perl.

    Performance enhancements

    Simple sort() using { $a <=> $b } and the like are optimized

    Many common sort() operations using a simple inlined block are now optimized for faster performance.

    Optimized assignments to lexical variables

    Certain operations in the RHS of assignment statements have been optimized to directly set the lexical variable on the LHS, eliminating redundant copying overheads.

    Faster subroutine calls

    Minor changes in how subroutine calls are handled internally provide marginal improvements in performance.

    delete(), each(), values() and hash iteration are faster

    The hash values returned by delete(), each(), values() and hashes in a list context are the actual values in the hash, instead of copies. This results in significantly better performance, because it eliminates needless copying in most situations.

    Installation and Configuration Improvements

    -Dusethreads means something different

    The -Dusethreads flag now enables the experimental interpreter-based thread support by default. To get the flavor of experimental threads that was in 5.005 instead, you need to run Configure with "-Dusethreads -Duse5005threads".

    As of v5.6.0, interpreter-threads support is still lacking a way to create new threads from Perl (i.e., use Thread; will not work with interpreter threads). use Thread; continues to be available when you specify the -Duse5005threads option to Configure, bugs and all.

        NOTE: Support for threads continues to be an experimental feature.
    Interfaces and implementation are subject to sudden and drastic changes.

    New Configure flags

    The following new flags may be enabled on the Configure command line by running Configure with -Dflag.

        usemultiplicity
    usethreads useithreads      (new interpreter threads: no Perl API yet)
    usethreads use5005threads   (threads as they were in 5.005)
        use64bitint                 (equal to now deprecated 'use64bits')
    use64bitall
        uselongdouble
    usemorebits
    uselargefiles
    usesocks                    (only SOCKS v5 supported)

    Threadedness and 64-bitness now more daring

    The Configure options enabling the use of threads and the use of 64-bitness are now more daring in the sense that they no more have an explicit list of operating systems of known threads/64-bit capabilities. In other words: if your operating system has the necessary APIs and datatypes, you should be able just to go ahead and use them, for threads by Configure -Dusethreads, and for 64 bits either explicitly by Configure -Duse64bitint or implicitly if your system has 64-bit wide datatypes. See also 64-bit support.

    Long Doubles

    Some platforms have "long doubles", floating point numbers of even larger range than ordinary "doubles". To enable using long doubles for Perl's scalars, use -Duselongdouble.

    -Dusemorebits

    You can enable both -Duse64bitint and -Duselongdouble with -Dusemorebits. See also 64-bit support.

    -Duselargefiles

    Some platforms support system APIs that are capable of handling large files (typically, files larger than two gigabytes). Perl will try to use these APIs if you ask for -Duselargefiles.

    See Large file support for more information.

    installusrbinperl

    You can use "Configure -Uinstallusrbinperl" which causes installperl to skip installing perl also as /usr/bin/perl. This is useful if you prefer not to modify /usr/bin for some reason or another but harmful because many scripts assume to find Perl in /usr/bin/perl.

    SOCKS support

    You can use "Configure -Dusesocks" which causes Perl to probe for the SOCKS proxy protocol library (v5, not v4). For more information on SOCKS, see:

        http://www.socks.nec.com/

    -A flag

    You can "post-edit" the Configure variables using the Configure -A switch. The editing happens immediately after the platform specific hints files have been processed but before the actual configuration process starts. Run Configure -h to find out the full -A syntax.

    Enhanced Installation Directories

    The installation structure has been enriched to improve the support for maintaining multiple versions of perl, to provide locations for vendor-supplied modules, scripts, and manpages, and to ease maintenance of locally-added modules, scripts, and manpages. See the section on Installation Directories in the INSTALL file for complete details. For most users building and installing from source, the defaults should be fine.

    If you previously used Configure -Dsitelib or -Dsitearch to set special values for library directories, you might wish to consider using the new -Dsiteprefix setting instead. Also, if you wish to re-use a config.sh file from an earlier version of perl, you should be sure to check that Configure makes sensible choices for the new directories. See INSTALL for complete details.

    gcc automatically tried if 'cc' does not seem to be working

    In many platforms the vendor-supplied 'cc' is too stripped-down to build Perl (basically, the 'cc' doesn't do ANSI C). If this seems to be the case and the 'cc' does not seem to be the GNU C compiler 'gcc', an automatic attempt is made to find and use 'gcc' instead.

    Platform specific changes

    Supported platforms

    • The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread extension.

    • GNU/Hurd is now supported.

    • Rhapsody/Darwin is now supported.

    • EPOC is now supported (on Psion 5).

    • The cygwin port (formerly cygwin32) has been greatly improved.

    DOS

    • Perl now works with djgpp 2.02 (and 2.03 alpha).

    • Environment variable names are not converted to uppercase any more.

    • Incorrect exit codes from backticks have been fixed.

    • This port continues to use its own builtin globbing (not File::Glob).

    OS390 (OpenEdition MVS)

    Support for this EBCDIC platform has not been renewed in this release. There are difficulties in reconciling Perl's standardization on UTF-8 as its internal representation for characters with the EBCDIC character set, because the two are incompatible.

    It is unclear whether future versions will renew support for this platform, but the possibility exists.

    VMS

    Numerous revisions and extensions to configuration, build, testing, and installation process to accommodate core changes and VMS-specific options.

    Expand %ENV-handling code to allow runtime mapping to logical names, CLI symbols, and CRTL environ array.

    Extension of subprocess invocation code to accept filespecs as command "verbs".

    Add to Perl command line processing the ability to use default file types and to recognize Unix-style 2>&1.

    Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.

    Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.

    Barewords at start of Unix-syntax paths may be treated as text rather than only as logical names.

    Optional secure translation of several logical names used internally by Perl.

    Miscellaneous bugfixing and porting of new core code to VMS.

    Thanks are gladly extended to the many people who have contributed VMS patches, testing, and ideas.

    Win32

    Perl can now emulate fork() internally, using multiple interpreters running in different concurrent threads. This support must be enabled at build time. See the perlfork manpage for detailed information.

    When given a pathname that consists only of a drivename, such as A:, opendir() and stat() now use the current working directory for the drive rather than the drive root.

    The builtin XSUB functions in the Win32:: namespace are documented. See the Win32 manpage.

    $^X now contains the full path name of the running executable.

    A Win32::GetLongPathName() function is provided to complement Win32::GetFullPathName() and Win32::GetShortPathName(). See the Win32 manpage.

    POSIX::uname() is supported.

    system(1,...) now returns true process IDs rather than process handles. kill() accepts any real process id, rather than strictly return values from system(1,...).

    For better compatibility with Unix, kill(0, $pid) can now be used to test whether a process exists.

    The Shell module is supported.

    Better support for building Perl under command.com in Windows 95 has been added.

    Scripts are read in binary mode by default to allow ByteLoader (and the filter mechanism in general) to work properly. For compatibility, the DATA filehandle will be set to text mode if a carriage return is detected at the end of the line containing the __END__ or __DATA__ token; if not, the DATA filehandle will be left open in binary mode. Earlier versions always opened the DATA filehandle in text mode.

    The glob() operator is implemented via the File::Glob extension, which supports glob syntax of the C shell. This increases the flexibility of the glob() operator, but there may be compatibility issues for programs that relied on the older globbing syntax. If you want to preserve compatibility with the older syntax, you might want to run perl with -MFile::DosGlob. For details and compatibility information, see the File::Glob manpage.

    Significant bug fixes

    <HANDLE> on empty files

    With $/ set to undef, "slurping" an empty file returns a string of zero length (instead of undef, as it used to) the first time the HANDLE is read after $/ is set to undef. Further reads yield undef.

    This means that the following will append "foo" to an empty file (it used to do nothing):

        perl -0777 -pi -e 's/^/foo/' empty_file

    The behaviour of:

        perl -pi -e 's/^/foo/' empty_file

    is unchanged (it continues to leave the file empty).

    eval '...' improvements

    Line numbers (as reflected by caller() and most diagnostics) within eval '...' were often incorrect where here documents were involved. This has been corrected.

    Lexical lookups for variables appearing in eval '...' within functions that were themselves called within an eval '...' were searching the wrong place for lexicals. The lexical search now correctly ends at the subroutine's block boundary.

    The use of return within eval {...} caused $@ not to be reset correctly when no exception occurred within the eval. This has been fixed.

    Parsing of here documents used to be flawed when they appeared as the replacement expression in eval 's/.../.../e'. This has been fixed.

    All compilation errors are true errors

    Some "errors" encountered at compile time were by necessity generated as warnings followed by eventual termination of the program. This enabled more such errors to be reported in a single run, rather than causing a hard stop at the first error that was encountered.

    The mechanism for reporting such errors has been reimplemented to queue compile-time errors and report them at the end of the compilation as true errors rather than as warnings. This fixes cases where error messages leaked through in the form of warnings when code was compiled at run time using eval STRING, and also allows such errors to be reliably trapped using eval "...".

    Implicitly closed filehandles are safer

    Sometimes implicitly closed filehandles (as when they are localized, and Perl automatically closes them on exiting the scope) could inadvertently set $? or $!. This has been corrected.

    Behavior of list slices is more consistent

    When taking a slice of a literal list (as opposed to a slice of an array or hash), Perl used to return an empty list if the result happened to be composed of all undef values.

    The new behavior is to produce an empty list if (and only if) the original list was empty. Consider the following example:

        @a = (1,undef,undef,2)[2,1,2];

    The old behavior would have resulted in @a having no elements. The new behavior ensures it has three undefined elements.

    Note in particular that the behavior of slices of the following cases remains unchanged:

        @a = ()[1,2];
    @a = (getpwent)[7,0];
    @a = (anything_returning_empty_list())[2,1,2];
    @a = @b[2,1,2];
    @a = @c{'a','b','c'};

    See the perldata manpage.

    (\$) prototype and $foo{a}

    A scalar reference prototype now correctly allows a hash or array element in that slot.

    goto &sub and AUTOLOAD

    The goto &sub construct works correctly when &sub happens to be autoloaded.

    -bareword allowed under use integer

    The autoquoting of barewords preceded by - did not work in prior versions when the integer pragma was enabled. This has been fixed.

    Failures in DESTROY()

    When code in a destructor threw an exception, it went unnoticed in earlier versions of Perl, unless someone happened to be looking in $@ just after the point the destructor happened to run. Such failures are now visible as warnings when warnings are enabled.

    Locale bugs fixed

    printf() and sprintf() previously reset the numeric locale back to the default "C" locale. This has been fixed.

    Numbers formatted according to the local numeric locale (such as using a decimal comma instead of a decimal dot) caused "isn't numeric" warnings, even while the operations accessing those numbers produced correct results. These warnings have been discontinued.

    Memory leaks

    The eval 'return sub {...}' construct could sometimes leak memory. This has been fixed.

    Operations that aren't filehandle constructors used to leak memory when used on invalid filehandles. This has been fixed.

    Constructs that modified @_ could fail to deallocate values in @_ and thus leak memory. This has been corrected.

    Spurious subroutine stubs after failed subroutine calls

    Perl could sometimes create empty subroutine stubs when a subroutine was not found in the package. Such cases stopped later method lookups from progressing into base packages. This has been corrected.

    Taint failures under -U

    When running in unsafe mode, taint violations could sometimes cause silent failures. This has been fixed.

    END blocks and the -c switch

    Prior versions used to run BEGIN and END blocks when Perl was run in compile-only mode. Since this is typically not the expected behavior, END blocks are not executed anymore when the -c switch is used, or if compilation fails.

    See Support for CHECK blocks for how to run things when the compile phase ends.

    Potential to leak DATA filehandles

    Using the __DATA__ token creates an implicit filehandle to the file that contains the token. It is the program's responsibility to close it when it is done reading from it.

    This caveat is now better explained in the documentation. See the perldata manpage.

    New or Changed Diagnostics

    "%s" variable %s masks earlier declaration in same %s

    (W misc) A "my" or "our" variable has been redeclared in the current scope or statement, effectively eliminating all access to the previous instance. This is almost always a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed.

    "my sub" not yet implemented

    (F) Lexically scoped subroutines are not yet implemented. Don't try that yet.

    "our" variable %s redeclared

    (W misc) You seem to have already declared the same global once before in the current lexical scope.

    '!' allowed only after types %s

    (F) The '!' is allowed in pack() and unpack() only after certain types. See pack in the perlfunc manpage.

    / cannot take a count

    (F) You had an unpack template indicating a counted-length string, but you have also specified an explicit size for the string. See pack in the perlfunc manpage.

    / must be followed by a, A or Z

    (F) You had an unpack template indicating a counted-length string, which must be followed by one of the letters a, A or Z to indicate what sort of string is to be unpacked. See pack in the perlfunc manpage.

    / must be followed by a*, A* or Z*

    (F) You had a pack template indicating a counted-length string, Currently the only things that can have their length counted are a*, A* or Z*. See pack in the perlfunc manpage.

    / must follow a numeric type

    (F) You had an unpack template that contained a '#', but this did not follow some numeric unpack specification. See pack in the perlfunc manpage.

    /%s/: Unrecognized escape \\%c passed through

    (W regexp) You used a backslash-character combination which is not recognized by Perl. This combination appears in an interpolated variable or a '-delimited regular expression. The character was understood literally.

    /%s/: Unrecognized escape \\%c in character class passed through

    (W regexp) You used a backslash-character combination which is not recognized by Perl inside character classes. The character was understood literally.

    /%s/ should probably be written as "%s"

    (W syntax) You have used a pattern where Perl expected to find a string, as in the first argument to join. Perl will treat the true or false result of matching the pattern against $_ as the string, which is probably not what you had in mind.

    %s() called too early to check prototype

    (W prototype) You've called a function that has a prototype before the parser saw a definition or declaration for it, and Perl could not check that the call conforms to the prototype. You need to either add an early prototype declaration for the subroutine in question, or move the subroutine definition ahead of the call to get proper prototype checking. Alternatively, if you are certain that you're calling the function correctly, you may put an ampersand before the name to avoid the warning. See the perlsub manpage.

    %s argument is not a HASH or ARRAY element

    (F) The argument to exists() must be a hash or array element, such as:

        $foo{$bar}
    $ref->{"susie"}[12]
    %s argument is not a HASH or ARRAY element or slice

    (F) The argument to delete() must be either a hash or array element, such as:

        $foo{$bar}
    $ref->{"susie"}[12]

    or a hash or array slice, such as:

        @foo[$bar, $baz, $xyzzy]
    @{$ref->[12]}{"susie", "queue"}
    %s argument is not a subroutine name

    (F) The argument to exists() for exists &sub must be a subroutine name, and not a subroutine call. exists &sub() will generate this error.

    %s package attribute may clash with future reserved word: %s

    (W reserved) A lowercase attribute name was used that had a package-specific handler. That name might have a meaning to Perl itself some day, even though it doesn't yet. Perhaps you should use a mixed-case attribute name, instead. See the attributes manpage.

    (in cleanup) %s

    (W misc) This prefix usually indicates that a DESTROY() method raised the indicated exception. Since destructors are usually called by the system at arbitrary points during execution, and often a vast number of times, the warning is issued only once for any number of failures that would otherwise result in the same message being repeated.

    Failure of user callbacks dispatched using the G_KEEPERR flag could also result in this warning. See G_KEEPERR in the perlcall manpage.

    <> should be quotes

    (F) You wrote require <file> when you should have written require 'file'.

    Attempt to join self

    (F) You tried to join a thread from within itself, which is an impossible task. You may be joining the wrong thread, or you may need to move the join() to some other thread.

    Bad evalled substitution pattern

    (F) You've used the /e switch to evaluate the replacement for a substitution, but perl found a syntax error in the code to evaluate, most likely an unexpected right brace '}'.

    Bad realloc() ignored

    (S) An internal routine called realloc() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by setting environment variable PERL_BADFREE to 1.

    Bareword found in conditional

    (W bareword) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

        open FOO || die;

    It may also indicate a misspelled constant that has been interpreted as a bareword:

        use constant TYPO => 1;
    if (TYOP) { print "foo" }

    The strict pragma is useful in avoiding such errors.

    Binary number > 0b11111111111111111111111111111111 non-portable

    (W portable) The binary number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

    Bit vector size > 32 non-portable

    (W portable) Using bit vector sizes larger than 32 is non-portable.

    Buffer overflow in prime_env_iter: %s

    (W internal) A warning peculiar to VMS. While Perl was preparing to iterate over %ENV, it encountered a logical name or symbol definition which was too long, so it was truncated to the string shown.

    Can't check filesystem of script "%s"

    (P) For some reason you can't check the filesystem of the script for nosuid.

    Can't declare class for non-scalar %s in "%s"

    (S) Currently, only scalar variables can declared with a specific class qualifier in a "my" or "our" declaration. The semantics may be extended for other types of variables in future.

    Can't declare %s in "%s"

    (F) Only scalar, array, and hash variables may be declared as "my" or "our" variables. They must have ordinary identifiers as names.

    Can't ignore signal CHLD, forcing to default

    (W signal) Perl has detected that it is being run with the SIGCHLD signal (sometimes known as SIGCLD) disabled. Since disabling this signal will interfere with proper determination of exit status of child processes, Perl has reset the signal to its default value. This situation typically indicates that the parent program under which Perl may be running (e.g., cron) is being very careless.

    Can't modify non-lvalue subroutine call

    (F) Subroutines meant to be used in lvalue context should be declared as such, see Lvalue subroutines in the perlsub manpage.

    Can't read CRTL environ

    (S) A warning peculiar to VMS. Perl tried to read an element of %ENV from the CRTL's internal environment array and discovered the array was missing. You need to figure out where your CRTL misplaced its environ or define PERL_ENV_TABLES (see the perlvms manpage) so that environ is not searched.

    Can't remove %s: %s, skipping file

    (S) You requested an inplace edit without creating a backup file. Perl was unable to remove the original file to replace it with the modified file. The file was left unmodified.

    Can't return %s from lvalue subroutine

    (F) Perl detected an attempt to return illegal lvalues (such as temporary or readonly values) from a subroutine used as an lvalue. This is not allowed.

    Can't weaken a nonreference

    (F) You attempted to weaken something that was not a reference. Only references can be weakened.

    Character class [:%s:] unknown

    (F) The class in the character class [: :] syntax is unknown. See the perlre manpage.

    Character class syntax [%s] belongs inside character classes

    (W unsafe) The character class constructs [: :], [= =], and [. .] go inside character classes, the [] are part of the construct, for example: /[012[:alpha:]345]/. Note that [= =] and [. .] are not currently implemented; they are simply placeholders for future extensions.

    Constant is not %s reference

    (F) A constant value (perhaps declared using the use constant pragma) is being dereferenced, but it amounts to the wrong type of reference. The message indicates the type of reference that was expected. This usually indicates a syntax error in dereferencing the constant value. See Constant Functions in the perlsub manpage and the constant manpage.

    constant(%s): %s

    (F) The parser found inconsistencies either while attempting to define an overloaded constant, or when trying to find the character name specified in the \N{...} escape. Perhaps you forgot to load the corresponding overload or charnames pragma? See the charnames manpage and the overload manpage.

    CORE::%s is not a keyword

    (F) The CORE:: namespace is reserved for Perl keywords.

    defined(@array) is deprecated

    (D) defined() is not usually useful on arrays because it checks for an undefined scalar value. If you want to see if the array is empty, just use if (@array) { # not empty } for example.

    defined(%hash) is deprecated

    (D) defined() is not usually useful on hashes because it checks for an undefined scalar value. If you want to see if the hash is empty, just use if (%hash) { # not empty } for example.

    Did not produce a valid header

    See Server error.

    (Did you mean "local" instead of "our"?)

    (W misc) Remember that "our" does not localize the declared global variable. You have declared it again in the same lexical scope, which seems superfluous.

    Document contains no data

    See Server error.

    entering effective %s failed

    (F) While under the use filetest pragma, switching the real and effective uids or gids failed.

    false [] range "%s" in regexp

    (W regexp) A character class range must start and end at a literal character, not another character class like \d or [:alpha:]. The "-" in your false range is interpreted as a literal "-". Consider quoting the "-", "\-". See the perlre manpage.

    Filehandle %s opened only for output

    (W io) You tried to read from a filehandle opened only for writing. If you intended it to be a read/write filehandle, you needed to open it with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you intended only to read from the file, use "<". See open in the perlfunc manpage.

    flock() on closed filehandle %s

    (W closed) The filehandle you're attempting to flock() got itself closed some time before now. Check your logic flow. flock() operates on filehandles. Are you attempting to call flock() on a dirhandle by the same name?

    Global symbol "%s" requires explicit package name

    (F) You've said "use strict vars", which indicates that all variables must either be lexically scoped (using "my"), declared beforehand using "our", or explicitly qualified to say which package the global variable is in (using "::").

    Hexadecimal number > 0xffffffff non-portable

    (W portable) The hexadecimal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

    Ill-formed CRTL environ value "%s"

    (W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal environ array, and encountered an element without the = delimiter used to separate keys from values. The element is ignored.

    Ill-formed message in prime_env_iter: |%s|

    (W internal) A warning peculiar to VMS. Perl tried to read a logical name or CLI symbol definition when preparing to iterate over %ENV, and didn't see the expected delimiter between key and value, so the line was ignored.

    Illegal binary digit %s

    (F) You used a digit other than 0 or 1 in a binary number.

    Illegal binary digit %s ignored

    (W digit) You may have tried to use a digit other than 0 or 1 in a binary number. Interpretation of the binary number stopped before the offending digit.

    Illegal number of bits in vec

    (F) The number of bits in vec() (the third argument) must be a power of two from 1 to 32 (or 64, if your platform supports that).

    Integer overflow in %s number

    (W overflow) The hexadecimal, octal or binary number you have specified either as a literal or as an argument to hex() or oct() is too big for your architecture, and has been converted to a floating point number. On a 32-bit architecture the largest hexadecimal, octal or binary number representable without overflow is 0xFFFFFFFF, 037777777777, or 0b11111111111111111111111111111111 respectively. Note that Perl transparently promotes all numbers to a floating point representation internally--subject to loss of precision errors in subsequent operations.

    Invalid %s attribute: %s

    The indicated attribute for a subroutine or variable was not recognized by Perl or by a user-supplied handler. See the attributes manpage.

    Invalid %s attributes: %s

    The indicated attributes for a subroutine or variable were not recognized by Perl or by a user-supplied handler. See the attributes manpage.

    invalid [] range "%s" in regexp

    The offending range is now explicitly displayed.

    Invalid separator character %s in attribute list

    (F) Something other than a colon or whitespace was seen between the elements of an attribute list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon. See the attributes manpage.

    Invalid separator character %s in subroutine attribute list

    (F) Something other than a colon or whitespace was seen between the elements of a subroutine attribute list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon.

    leaving effective %s failed

    (F) While under the use filetest pragma, switching the real and effective uids or gids failed.

    Lvalue subs returning %s not implemented yet

    (F) Due to limitations in the current implementation, array and hash values cannot be returned in subroutines used in lvalue context. See Lvalue subroutines in the perlsub manpage.

    Method %s not permitted

    See Server error.

    Missing %sbrace%s on \N{}

    (F) Wrong syntax of character name literal \N{charname} within double-quotish context.

    Missing command in piped open

    (W pipe) You used the open(FH, "| command") or open(FH, "command |") construction, but the command was missing or blank.

    Missing name in "my sub"

    (F) The reserved syntax for lexically scoped subroutines requires that they have a name with which they can be found.

    No %s specified for -%c

    (F) The indicated command line switch needs a mandatory argument, but you haven't specified one.

    No package name allowed for variable %s in "our"

    (F) Fully qualified variable names are not allowed in "our" declarations, because that doesn't make much sense under existing semantics. Such syntax is reserved for future extensions.

    No space allowed after -%c

    (F) The argument to the indicated command line switch must follow immediately after the switch, without intervening spaces.

    no UTC offset information; assuming local time is UTC

    (S) A warning peculiar to VMS. Perl was unable to find the local timezone offset, so it's assuming that local system time is equivalent to UTC. If it's not, define the logical name SYS$TIMEZONE_DIFFERENTIAL to translate to the number of seconds which need to be added to UTC to get local time.

    Octal number > 037777777777 non-portable

    (W portable) The octal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

    See also the perlport manpage for writing portable code.

    panic: del_backref

    (P) Failed an internal consistency check while trying to reset a weak reference.

    panic: kid popen errno read

    (F) forked child returned an incomprehensible message about its errno.

    panic: magic_killbackrefs

    (P) Failed an internal consistency check while trying to reset all weak references to an object.

    Parentheses missing around "%s" list

    (W parenthesis) You said something like

        my $foo, $bar = @_;

    when you meant

        my ($foo, $bar) = @_;

    Remember that "my", "our", and "local" bind tighter than comma.

    Possible unintended interpolation of %s in string

    (W ambiguous) It used to be that Perl would try to guess whether you wanted an array interpolated or a literal @. It no longer does this; arrays are now always interpolated into strings. This means that if you try something like:

            print "fred@example.com";

    and the array @example doesn't exist, Perl is going to print fred.com, which is probably not what you wanted. To get a literal @ sign in a string, put a backslash before it, just as you would to get a literal $ sign.

    Possible Y2K bug: %s

    (W y2k) You are concatenating the number 19 with another number, which could be a potential Year 2000 problem.

    pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead

    (W deprecated) You have written something like this:

        sub doit
    {
        use attrs qw(locked);
    }

    You should use the new declaration syntax instead.

        sub doit : locked
    {
        ...

    The use attrs pragma is now obsolete, and is only provided for backward-compatibility. See Subroutine Attributes in the perlsub manpage.

    Premature end of script headers

    See Server error.

    Repeat count in pack overflows

    (F) You can't specify a repeat count so large that it overflows your signed integers. See pack in the perlfunc manpage.

    Repeat count in unpack overflows

    (F) You can't specify a repeat count so large that it overflows your signed integers. See unpack in the perlfunc manpage.

    realloc() of freed memory ignored

    (S) An internal routine called realloc() on something that had already been freed.

    Reference is already weak

    (W misc) You have attempted to weaken a reference that is already weak. Doing so has no effect.

    setpgrp can't take arguments

    (F) Your system has the setpgrp() from BSD 4.2, which takes no arguments, unlike POSIX setpgid(), which takes a process ID and process group ID.

    Strange *+?{} on zero-length expression

    (W regexp) You applied a regular expression quantifier in a place where it makes no sense, such as on a zero-width assertion. Try putting the quantifier inside the assertion instead. For example, the way to match "abc" provided that it is followed by three repetitions of "xyz" is /abc(?=(?:xyz){3})/, not /abc(?=xyz){3}/.

    switching effective %s is not implemented

    (F) While under the use filetest pragma, we cannot switch the real and effective uids or gids.

    This Perl can't reset CRTL environ elements (%s)
    This Perl can't set CRTL environ elements (%s=%s)

    (W internal) Warnings peculiar to VMS. You tried to change or delete an element of the CRTL's internal environ array, but your copy of Perl wasn't built with a CRTL that contained the setenv() function. You'll need to rebuild Perl with a CRTL that does, or redefine PERL_ENV_TABLES (see the perlvms manpage) so that the environ array isn't the target of the change to %ENV which produced the warning.

    Too late to run %s block

    (W void) A CHECK or INIT block is being defined during run time proper, when the opportunity to run them has already passed. Perhaps you are loading a file with require or do when you should be using use instead. Or perhaps you should put the require or do inside a BEGIN block.

    Unknown open() mode '%s'

    (F) The second argument of 3-argument open() is not among the list of valid modes: <, >, >>, +<, +>, +>>, -|, |-.

    Unknown process %x sent message to prime_env_iter: %s

    (P) An error peculiar to VMS. Perl was reading values for %ENV before iterating over it, and someone else stuck a message in the stream of data Perl expected. Someone's very confused, or perhaps trying to subvert Perl's population of %ENV for nefarious purposes.

    Unrecognized escape \\%c passed through

    (W misc) You used a backslash-character combination which is not recognized by Perl. The character was understood literally.

    Unterminated attribute parameter in attribute list

    (F) The lexer saw an opening (left) parenthesis character while parsing an attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance. See the attributes manpage.

    Unterminated attribute list

    (F) The lexer found something other than a simple identifier at the start of an attribute, and it wasn't a semicolon or the start of a block. Perhaps you terminated the parameter list of the previous attribute too soon. See the attributes manpage.

    Unterminated attribute parameter in subroutine attribute list

    (F) The lexer saw an opening (left) parenthesis character while parsing a subroutine attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance.

    Unterminated subroutine attribute list

    (F) The lexer found something other than a simple identifier at the start of a subroutine attribute, and it wasn't a semicolon or the start of a block. Perhaps you terminated the parameter list of the previous attribute too soon.

    Value of CLI symbol "%s" too long

    (W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV element from a CLI symbol table, and found a resultant string longer than 1024 characters. The return value has been truncated to 1024 characters.

    Version number must be a constant number

    (P) The attempt to translate a use Module n.n LIST statement into its equivalent BEGIN block found an internal inconsistency with the version number.

    New tests

    lib/attrs

    Compatibility tests for sub : attrs vs the older use attrs.

    lib/env

    Tests for new environment scalar capability (e.g., use Env qw($BAR);).

    lib/env-array

    Tests for new environment array capability (e.g., use Env qw(@PATH);).

    lib/io_const

    IO constants (SEEK_*, _IO*).

    lib/io_dir

    Directory-related IO methods (new, read, close, rewind, tied delete).

    lib/io_multihomed

    INET sockets with multi-homed hosts.

    lib/io_poll

    IO poll().

    lib/io_unix

    UNIX sockets.

    op/attrs

    Regression tests for my ($x,@y,%z) : attrs and <sub : attrs>.

    op/filetest

    File test operators.

    op/lex_assign

    Verify operations that access pad objects (lexicals and temporaries).

    op/exists_sub

    Verify exists &sub operations.

    Incompatible Changes

    Perl Source Incompatibilities

    Beware that any new warnings that have been added or old ones that have been enhanced are not considered incompatible changes.

    Since all new warnings must be explicitly requested via the -w switch or the warnings pragma, it is ultimately the programmer's responsibility to ensure that warnings are enabled judiciously.

    CHECK is a new keyword

    All subroutine definitions named CHECK are now special. See /"Support for CHECK blocks" for more information.

    Treatment of list slices of undef has changed

    There is a potential incompatibility in the behavior of list slices that are comprised entirely of undefined values. See Behavior of list slices is more consistent.

    Format of $English::PERL_VERSION is different

    The English module now sets $PERL_VERSION to $^V (a string value) rather than $] (a numeric value). This is a potential incompatibility. Send us a report via perlbug if you are affected by this.

    See Improved Perl version numbering system for the reasons for this change.

    Literals of the form 1.2.3 parse differently

    Previously, numeric literals with more than one dot in them were interpreted as a floating point number concatenated with one or more numbers. Such "numbers" are now parsed as strings composed of the specified ordinals.

    For example, print 97.98.99 used to output 97.9899 in earlier versions, but now prints abc.

    See Support for strings represented as a vector of ordinals.

    Possibly changed pseudo-random number generator

    Perl programs that depend on reproducing a specific set of pseudo-random numbers may now produce different output due to improvements made to the rand() builtin. You can use sh Configure -Drandfunc=rand to obtain the old behavior.

    See Better pseudo-random number generator.

    Hashing function for hash keys has changed

    Even though Perl hashes are not order preserving, the apparently random order encountered when iterating on the contents of a hash is actually determined by the hashing algorithm used. Improvements in the algorithm may yield a random order that is different from that of previous versions, especially when iterating on hashes.

    See Better worst-case behavior of hashes for additional information.

    undef fails on read only values

    Using the undef operator on a readonly value (such as $1) has the same effect as assigning undef to the readonly value--it throws an exception.

    Close-on-exec bit may be set on pipe and socket handles

    Pipe and socket handles are also now subject to the close-on-exec behavior determined by the special variable $^F.

    See More consistent close-on-exec behavior.

    Writing "$$1" to mean "${$}1" is unsupported

    Perl 5.004 deprecated the interpretation of $$1 and similar within interpolated strings to mean $$ . "1", but still allowed it.

    In Perl 5.6.0 and later, "$$1" always means "${$1}".

    delete(), each(), values() and \(%h)

    operate on aliases to values, not copies

    delete(), each(), values() and hashes (e.g. \(%h)) in a list context return the actual values in the hash, instead of copies (as they used to in earlier versions). Typical idioms for using these constructs copy the returned values, but this can make a significant difference when creating references to the returned values. Keys in the hash are still returned as copies when iterating on a hash.

    See also delete(), each(), values() and hash iteration are faster.

    vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS

    vec() generates a run-time error if the BITS argument is not a valid power-of-two integer.

    Text of some diagnostic output has changed

    Most references to internal Perl operations in diagnostics have been changed to be more descriptive. This may be an issue for programs that may incorrectly rely on the exact text of diagnostics for proper functioning.

    %@ has been removed

    The undocumented special variable %@ that used to accumulate "background" errors (such as those that happen in DESTROY()) has been removed, because it could potentially result in memory leaks.

    Parenthesized not() behaves like a list operator

    The not operator now falls under the "if it looks like a function, it behaves like a function" rule.

    As a result, the parenthesized form can be used with grep and map. The following construct used to be a syntax error before, but it works as expected now:

        grep not($_), @things;

    On the other hand, using not with a literal list slice may not work. The following previously allowed construct:

        print not (1,2,3)[0];

    needs to be written with additional parentheses now:

        print not((1,2,3)[0]);

    The behavior remains unaffected when not is not followed by parentheses.

    Semantics of bareword prototype (*) have changed

    The semantics of the bareword prototype * have changed. Perl 5.005 always coerced simple scalar arguments to a typeglob, which wasn't useful in situations where the subroutine must distinguish between a simple scalar and a typeglob. The new behavior is to not coerce bareword arguments to a typeglob. The value will always be visible as either a simple scalar or as a reference to a typeglob.

    See More functional bareword prototype (*).

    Semantics of bit operators may have changed on 64-bit platforms

    If your platform is either natively 64-bit or if Perl has been configured to used 64-bit integers, i.e., $Config{ivsize} is 8, there may be a potential incompatibility in the behavior of bitwise numeric operators (& | ^ ~ << >>). These operators used to strictly operate on the lower 32 bits of integers in previous versions, but now operate over the entire native integral width. In particular, note that unary ~ will produce different results on platforms that have different $Config{ivsize}. For portability, be sure to mask off the excess bits in the result of unary ~, e.g., ~$x & 0xffffffff.

    See Bit operators support full native integer width.

    More builtins taint their results

    As described in Improved security features, there may be more sources of taint in a Perl program.

    To avoid these new tainting behaviors, you can build Perl with the Configure option -Accflags=-DINCOMPLETE_TAINTS. Beware that the ensuing perl binary may be insecure.

    C Source Incompatibilities

    PERL_POLLUTE

    Release 5.005 grandfathered old global symbol names by providing preprocessor macros for extension source compatibility. As of release 5.6.0, these preprocessor definitions are not available by default. You need to explicitly compile perl with -DPERL_POLLUTE to get these definitions. For extensions still using the old symbols, this option can be specified via MakeMaker:

        perl Makefile.PL POLLUTE=1
    PERL_IMPLICIT_CONTEXT

    This new build option provides a set of macros for all API functions such that an implicit interpreter/thread context argument is passed to every API function. As a result of this, something like sv_setsv(foo,bar) amounts to a macro invocation that actually translates to something like Perl_sv_setsv(my_perl,foo,bar). While this is generally expected to not have any significant source compatibility issues, the difference between a macro and a real function call will need to be considered.

    This means that there is a source compatibility issue as a result of this if your extensions attempt to use pointers to any of the Perl API functions.

    Note that the above issue is not relevant to the default build of Perl, whose interfaces continue to match those of prior versions (but subject to the other options described here).

    See The Perl API in the perlguts manpage for detailed information on the ramifications of building Perl with this option.

        NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
    with one of -Dusethreads, -Dusemultiplicity, or both.  It is not
    intended to be enabled by users at this time.
    PERL_POLLUTE_MALLOC

    Enabling Perl's malloc in release 5.005 and earlier caused the namespace of the system's malloc family of functions to be usurped by the Perl versions, since by default they used the same names. Besides causing problems on platforms that do not allow these functions to be cleanly replaced, this also meant that the system versions could not be called in programs that used Perl's malloc. Previous versions of Perl have allowed this behaviour to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor definitions.

    As of release 5.6.0, Perl's malloc family of functions have default names distinct from the system versions. You need to explicitly compile perl with -DPERL_POLLUTE_MALLOC to get the older behaviour. HIDEMYMALLOC and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now the default.

    Note that these functions do not constitute Perl's memory allocation API. See Memory Allocation in the perlguts manpage for further information about that.

    Compatible C Source API Changes

    PATCHLEVEL is now PERL_VERSION

    The cpp macros PERL_REVISION, PERL_VERSION, and PERL_SUBVERSION are now available by default from perl.h, and reflect the base revision, patchlevel, and subversion respectively. PERL_REVISION had no prior equivalent, while PERL_VERSION and PERL_SUBVERSION were previously available as PATCHLEVEL and SUBVERSION.

    The new names cause less pollution of the cpp namespace and reflect what the numbers have come to stand for in common practice. For compatibility, the old names are still supported when patchlevel.h is explicitly included (as required before), so there is no source incompatibility from the change.

    Binary Incompatibilities

    In general, the default build of this release is expected to be binary compatible for extensions built with the 5.005 release or its maintenance versions. However, specific platforms may have broken binary compatibility due to changes in the defaults used in hints files. Therefore, please be sure to always check the platform-specific README files for any notes to the contrary.

    The usethreads or usemultiplicity builds are not binary compatible with the corresponding builds in 5.005.

    On platforms that require an explicit list of exports (AIX, OS/2 and Windows, among others), purely internal symbols such as parser functions and the run time opcodes are not exported by default. Perl 5.005 used to export all functions irrespective of whether they were considered part of the public API or not.

    For the full list of public API functions, see the perlapi manpage.

    Known Problems

    Localizing a tied hash element may leak memory

    As of the 5.6.1 release, there is a known leak when code such as this is executed:

        use Tie::Hash;
    tie my %tie_hash => 'Tie::StdHash';

        ...
        local($tie_hash{Foo}) = 1; # leaks

    Known test failures

    • 64-bit builds

      Subtest #15 of lib/b.t may fail under 64-bit builds on platforms such as HP-UX PA64 and Linux IA64. The issue is still being investigated.

      The lib/io_multihomed test may hang in HP-UX if Perl has been configured to be 64-bit. Because other 64-bit platforms do not hang in this test, HP-UX is suspect. All other tests pass in 64-bit HP-UX. The test attempts to create and connect to "multihomed" sockets (sockets which have multiple IP addresses).

      Note that 64-bit support is still experimental.

    • Failure of Thread tests

      The subtests 19 and 20 of lib/thr5005.t test are known to fail due to fundamental problems in the 5.005 threading implementation. These are not new failures--Perl 5.005_0x has the same bugs, but didn't have these tests. (Note that support for 5.005-style threading remains experimental.)

    • NEXTSTEP 3.3 POSIX test failure

      In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the operating system libraries is buggy: the %j format numbers the days of a month starting from zero, which, while being logical to programmers, will cause the subtests 19 to 27 of the lib/posix test may fail.

    • Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc

      If compiled with gcc 2.95 the lib/sdbm test will fail (dump core). The cure is to use the vendor cc, it comes with the operating system and produces good code.

    EBCDIC platforms not fully supported

    In earlier releases of Perl, EBCDIC environments like OS390 (also known as Open Edition MVS) and VM-ESA were supported. Due to changes required by the UTF-8 (Unicode) support, the EBCDIC platforms are not supported in Perl 5.6.0.

    The 5.6.1 release improves support for EBCDIC platforms, but they are not fully supported yet.

    UNICOS/mk CC failures during Configure run

    In UNICOS/mk the following errors may appear during the Configure run:

            Guessing which symbols your C compiler and preprocessor define...
        CC-20 cc: ERROR File = try.c, Line = 3
        ...
          bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
        ...
        4 errors detected in the compilation of "try.c".

    The culprit is the broken awk of UNICOS/mk. The effect is fortunately rather mild: Perl itself is not adversely affected by the error, only the h2ph utility coming with Perl, and that is rather rarely needed these days.

    Arrow operator and arrays

    When the left argument to the arrow operator -> is an array, or the scalar operator operating on an array, the result of the operation must be considered erroneous. For example:

        @x->[2]
    scalar(@x)->[2]

    These expressions will get run-time errors in some future release of Perl.

    Experimental features

    As discussed above, many features are still experimental. Interfaces and implementation of these features are subject to change, and in extreme cases, even subject to removal in some future release of Perl. These features include the following:

    Threads
    Unicode
  • -bit support
    Lvalue subroutines
    Weak references
    The pseudo-hash data type
    The Compiler suite
    Internal implementation of file globbing
    The DB module
    The regular expression code constructs:

    (?{ code }) and (??{ code })

    • Obsolete Diagnostics

    Character class syntax [: :] is reserved for future extensions

    (W) Within regular expression character classes ([]) the syntax beginning with "[:" and ending with ":]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[:" and ":\]".

    Ill-formed logical name |%s| in prime_env_iter

    (W) A warning peculiar to VMS. A logical name was encountered when preparing to iterate over %ENV which violates the syntactic rules governing logical names. Because it cannot be translated normally, it is skipped, and will not appear in %ENV. This may be a benign occurrence, as some software packages might directly modify logical name tables and introduce nonstandard names, or it may indicate that a logical name table has been corrupted.

    In string, @%s now must be written as \@%s

    The description of this error used to say:

            (Someday it will simply assume that an unbackslashed @
         interpolates an array.)

    That day has come, and this fatal error has been removed. It has been replaced by a non-fatal warning instead. See Arrays now always interpolate into double-quoted strings for details.

    Probable precedence problem on %s

    (W) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

        open FOO || die;
    regexp too big

    (F) The current implementation of regular expressions uses shorts as address offsets within a string. Unfortunately this means that if the regular expression compiles to longer than 32767, it'll blow up. Usually when you want a regular expression this big, there is a better way to do it with multiple statements. See the perlre manpage.

    Use of "$$<digit>" to mean "${$}<digit>" is deprecated

    (D) Perl versions before 5.004 misinterpreted any type marker followed by "$" and a digit. For example, "$$0" was incorrectly taken to mean "${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.

    However, the developers of Perl 5.004 could not fix this bug completely, because at least two widely-used modules depend on the old meaning of "$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the old (broken) way inside strings; but it generates this message as a warning. And in Perl 5.005, this special treatment will cease.

    Reporting Bugs

    If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup. There may also be information at http://www.perl.com/ , the Perl Home Page.

    If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

    SEE ALSO

    The Changes file for exhaustive details on what changed.

    The INSTALL file for how to build Perl.

    The README file for general stuff.

    The Artistic and Copying files for copyright information.

    HISTORY

    Written by Gurusamy Sarathy <gsar@ActiveState.com>, with many contributions from The Perl Porters.

    Send omissions or corrections to <perlbug@perl.org>.


perl56delta - what's new for perl v5.6.0

  • Core Enhancements
    • Interpreter cloning, threads, and concurrency
    • Lexically scoped warning categories
    • Unicode and UTF-8 support
    • Support for interpolating named characters
    • "our" declarations
    • Support for strings represented as a vector of ordinals
    • Improved Perl version numbering system
    • New syntax for declaring subroutine attributes
    • File and directory handles can be autovivified
    • open() with more than two arguments
    • 64-bit support
    • Large file support
    • Long doubles
    • "more bits"
    • Enhanced support for sort() subroutines
    • sort $coderef @foo allowed
    • File globbing implemented internally
    • Support for CHECK blocks
    • POSIX character class syntax [: :] supported
    • Better pseudo-random number generator
    • Improved qw// operator
    • Better worst-case behavior of hashes
    • pack() format 'Z' supported
    • pack() format modifier '!' supported
    • pack() and unpack() support counted strings
    • Comments in pack() templates
    • Weak references
    • Binary numbers supported
    • Lvalue subroutines
    • Some arrows may be omitted in calls through references
    • Boolean assignment operators are legal lvalues
    • exists() is supported on subroutine names
    • exists() and delete() are supported on array elements
    • Pseudo-hashes work better
    • Automatic flushing of output buffers
    • Better diagnostics on meaningless filehandle operations
    • Where possible, buffered data discarded from duped input filehandle
    • eof() has the same old magic as <>
    • binmode() can be used to set :crlf and :raw modes
    • -T filetest recognizes UTF-8 encoded files as "text"
    • system(), backticks and pipe open now reflect exec() failure
    • Improved diagnostics
    • Diagnostics follow STDERR
    • More consistent close-on-exec behavior
    • syswrite() ease-of-use
    • Better syntax checks on parenthesized unary operators
    • Bit operators support full native integer width
    • Improved security features
    • More functional bareword prototype (*)
    • require and do may be overridden
    • $^X variables may now have names longer than one character
    • New variable $^C reflects -c switch
    • New variable $^V contains Perl version as a string
    • Optional Y2K warnings
    • Arrays now always interpolate into double-quoted strings
    • @- and @+ provide starting/ending offsets of regex matches
  • Modules and Pragmata
    • Modules
    • Pragmata
  • Utility Changes
    • dprofpp
    • find2perl
    • h2xs
    • perlcc
    • perldoc
    • The Perl Debugger
  • Improved Documentation
  • Performance enhancements
    • Simple sort() using { $a <=> $b } and the like are optimized
    • Optimized assignments to lexical variables
    • Faster subroutine calls
    • delete(), each(), values() and hash iteration are faster
  • Installation and Configuration Improvements
    • -Dusethreads means something different
    • New Configure flags
    • Threadedness and 64-bitness now more daring
    • Long Doubles
    • -Dusemorebits
    • -Duselargefiles
    • installusrbinperl
    • SOCKS support
    • -A flag
    • Enhanced Installation Directories
  • Platform specific changes
    • Supported platforms
    • DOS
    • OS390 (OpenEdition MVS)
    • VMS
    • Win32
  • Significant bug fixes
    • <HANDLE> on empty files
    • eval '...' improvements
    • All compilation errors are true errors
    • Implicitly closed filehandles are safer
    • Behavior of list slices is more consistent
    • (\$) prototype and $foo{a}
    • goto &sub and AUTOLOAD
    • -bareword allowed under use integer
    • Failures in DESTROY()
    • Locale bugs fixed
    • Memory leaks
    • Spurious subroutine stubs after failed subroutine calls
    • Taint failures under -U
    • END blocks and the -c switch
    • Potential to leak DATA filehandles
  • New or Changed Diagnostics
  • New tests
  • Incompatible Changes
    • Perl Source Incompatibilities
    • C Source Incompatibilities
    • Compatible C Source API Changes
    • Binary Incompatibilities
  • Known Problems
    • Thread test failures
    • EBCDIC platforms not supported
    • In 64-bit HP-UX the lib/io_multihomed test may hang
    • NEXTSTEP 3.3 POSIX test failure
    • Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
    • UNICOS/mk CC failures during Configure run
    • Arrow operator and arrays
    • Experimental features
  • Obsolete Diagnostics
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl56delta - what's new for perl v5.6.0

DESCRIPTION

This document describes differences between the 5.005 release and the 5.6.0 release.

Core Enhancements

Interpreter cloning, threads, and concurrency

Perl 5.6.0 introduces the beginnings of support for running multiple interpreters concurrently in different threads. In conjunction with the perl_clone() API call, which can be used to selectively duplicate the state of any given interpreter, it is possible to compile a piece of code once in an interpreter, clone that interpreter one or more times, and run all the resulting interpreters in distinct threads.

On the Windows platform, this feature is used to emulate fork() at the interpreter level. See the perlfork manpage for details about that.

This feature is still in evolution. It is eventually meant to be used to selectively clone a subroutine and data reachable from that subroutine in a separate interpreter and run the cloned subroutine in a separate thread. Since there is no shared data between the interpreters, little or no locking will be needed (unless parts of the symbol table are explicitly shared). This is obviously intended to be an easy-to-use replacement for the existing threads support.

Support for cloning interpreters and interpreter concurrency can be enabled using the -Dusethreads Configure option (see win32/Makefile for how to enable it on Windows.) The resulting perl executable will be functionally identical to one that was built with -Dmultiplicity, but the perl_clone() API call will only be available in the former.

-Dusethreads enables the cpp macro USE_ITHREADS by default, which in turn enables Perl source code changes that provide a clear separation between the op tree and the data it operates with. The former is immutable, and can therefore be shared between an interpreter and all of its clones, while the latter is considered local to each interpreter, and is therefore copied for each clone.

Note that building Perl with the -Dusemultiplicity Configure option is adequate if you wish to run multiple independent interpreters concurrently in different threads. -Dusethreads only provides the additional functionality of the perl_clone() API call and other support for running cloned interpreters concurrently.

    NOTE: This is an experimental feature.  Implementation details are
    subject to change.

Lexically scoped warning categories

You can now control the granularity of warnings emitted by perl at a finer level using the use warnings pragma. the warnings manpage and the perllexwarn manpage have copious documentation on this feature.

Unicode and UTF-8 support

Perl now uses UTF-8 as its internal representation for character strings. The utf8 and bytes pragmas are used to control this support in the current lexical scope. See the perlunicode manpage, the utf8 manpage and the bytes manpage for more information.

This feature is expected to evolve quickly to support some form of I/O disciplines that can be used to specify the kind of input and output data (bytes or characters). Until that happens, additional modules from CPAN will be needed to complete the toolkit for dealing with Unicode.

    NOTE: This should be considered an experimental feature.  Implementation
    details are subject to change.

Support for interpolating named characters

The new \N escape interpolates named characters within strings. For example, "Hi! \N{WHITE SMILING FACE}" evaluates to a string with a unicode smiley face at the end.

"our" declarations

An "our" declaration introduces a value that can be best understood as a lexically scoped symbolic alias to a global variable in the package that was current where the variable was declared. This is mostly useful as an alternative to the vars pragma, but also provides the opportunity to introduce typing and other attributes for such variables. See our in the perlfunc manpage.

Support for strings represented as a vector of ordinals

Literals of the form v1.2.3.4 are now parsed as a string composed of characters with the specified ordinals. This is an alternative, more readable way to construct (possibly unicode) strings instead of interpolating characters, as in "\x{1}\x{2}\x{3}\x{4}". The leading v may be omitted if there are more than two ordinals, so 1.2.3 is parsed the same as v1.2.3.

Strings written in this form are also useful to represent version "numbers". It is easy to compare such version "numbers" (which are really just plain strings) using any of the usual string comparison operators eq, ne, lt, gt, etc., or perform bitwise string operations on them using |, &, etc.

In conjunction with the new $^V magic variable (which contains the perl version as a string), such literals can be used as a readable way to check if you're running a particular version of Perl:

    # this will parse in older versions of Perl also
    if ($^V and $^V gt v5.6.0) {
        # new features supported
    }

require and use also have some special magic to support such literals, but this particular usage should be avoided because it leads to misleading error messages under versions of Perl which don't support vector strings. Using a true version number will ensure correct behavior in all versions of Perl:

    require 5.006;    # run time check for v5.6
    use 5.006_001;    # compile time check for v5.6.1

Also, sprintf and printf support the Perl-specific format flag %v to print ordinals of characters in arbitrary strings:

    printf "v%vd", $^V;         # prints current version, such as "v5.5.650"
    printf "%*vX", ":", $addr;  # formats IPv6 address
    printf "%*vb", " ", $bits;  # displays bitstring

See Scalar value constructors in the perldata manpage for additional information.

Improved Perl version numbering system

Beginning with Perl version 5.6.0, the version number convention has been changed to a "dotted integer" scheme that is more commonly found in open source projects.

Maintenance versions of v5.6.0 will be released as v5.6.1, v5.6.2 etc. The next development series following v5.6.0 will be numbered v5.7.x, beginning with v5.7.0, and the next major production release following v5.6.0 will be v5.8.0.

The English module now sets $PERL_VERSION to $^V (a string value) rather than $] (a numeric value). (This is a potential incompatibility. Send us a report via perlbug if you are affected by this.)

The v1.2.3 syntax is also now legal in Perl. See Support for strings represented as a vector of ordinals for more on that.

To cope with the new versioning system's use of at least three significant digits for each version component, the method used for incrementing the subversion number has also changed slightly. We assume that versions older than v5.6.0 have been incrementing the subversion component in multiples of 10. Versions after v5.6.0 will increment them by 1. Thus, using the new notation, 5.005_03 is the "same" as v5.5.30, and the first maintenance version following v5.6.0 will be v5.6.1 (which should be read as being equivalent to a floating point value of 5.006_001 in the older format, stored in $]).

New syntax for declaring subroutine attributes

Formerly, if you wanted to mark a subroutine as being a method call or as requiring an automatic lock() when it is entered, you had to declare that with a use attrs pragma in the body of the subroutine. That can now be accomplished with declaration syntax, like this:

    sub mymethod : locked method;
    ...
    sub mymethod : locked method {
        ...
    }

    sub othermethod :locked :method;
    ...
    sub othermethod :locked :method {
        ...
    }

(Note how only the first : is mandatory, and whitespace surrounding the : is optional.)

AutoSplit.pm and SelfLoader.pm have been updated to keep the attributes with the stubs they provide. See the attributes manpage.

File and directory handles can be autovivified

Similar to how constructs such as $x->[0] autovivify a reference, handle constructors (open(), opendir(), pipe(), socketpair(), sysopen(), socket(), and accept()) now autovivify a file or directory handle if the handle passed to them is an uninitialized scalar variable. This allows the constructs such as open(my $fh, ...) and open(local $fh,...) to be used to create filehandles that will conveniently be closed automatically when the scope ends, provided there are no other references to them. This largely eliminates the need for typeglobs when opening filehandles that must be passed around, as in the following example:

    sub myopen {
        open my $fh, "@_"
             or die "Can't open '@_': $!";
        return $fh;
    }

    {
        my $f = myopen("</etc/motd");
        print <$f>;
        # $f implicitly closed here
    }

open() with more than two arguments

If open() is passed three arguments instead of two, the second argument is used as the mode and the third argument is taken to be the file name. This is primarily useful for protecting against unintended magic behavior of the traditional two-argument form. See open in the perlfunc manpage.

64-bit support

Any platform that has 64-bit integers either

        (1) natively as longs or ints
        (2) via special compiler flags
        (3) using long long or int64_t

is able to use "quads" (64-bit integers) as follows:

  • constants (decimal, hexadecimal, octal, binary) in the code

  • arguments to oct() and hex()

  • arguments to print(), printf() and sprintf() (flag prefixes ll, L, q)

  • printed as such

  • pack() and unpack() "q" and "Q" formats

  • in basic arithmetics: + - * / % (NOTE: operating close to the limits of the integer values may produce surprising results)

  • in bit arithmetics: & | ^ ~ << >> (NOTE: these used to be forced to be 32 bits wide but now operate on the full native width.)

  • vec()

Note that unless you have the case (a) you will have to configure and compile Perl using the -Duse64bitint Configure flag.

    NOTE: The Configure flags -Duselonglong and -Duse64bits have been
    deprecated.  Use -Duse64bitint instead.

There are actually two modes of 64-bitness: the first one is achieved using Configure -Duse64bitint and the second one using Configure -Duse64bitall. The difference is that the first one is minimal and the second one maximal. The first works in more places than the second.

The use64bitint does only as much as is required to get 64-bit integers into Perl (this may mean, for example, using "long longs") while your memory may still be limited to 2 gigabytes (because your pointers could still be 32-bit). Note that the name 64bitint does not imply that your C compiler will be using 64-bit ints (it might, but it doesn't have to): the use64bitint means that you will be able to have 64 bits wide scalar values.

The use64bitall goes all the way by attempting to switch also integers (if it can), longs (and pointers) to being 64-bit. This may create an even more binary incompatible Perl than -Duse64bitint: the resulting executable may not run at all in a 32-bit box, or you may have to reboot/reconfigure/rebuild your operating system to be 64-bit aware.

Natively 64-bit systems like Alpha and Cray need neither -Duse64bitint nor -Duse64bitall.

Last but not least: note that due to Perl's habit of always using floating point numbers, the quads are still not true integers. When quads overflow their limits (0...18_446_744_073_709_551_615 unsigned, -9_223_372_036_854_775_808...9_223_372_036_854_775_807 signed), they are silently promoted to floating point numbers, after which they will start losing precision (in their lower digits).

    NOTE: 64-bit support is still experimental on most platforms.
    Existing support only covers the LP64 data model.  In particular, the
    LLP64 data model is not yet supported.  64-bit libraries and system
    APIs on many platforms have not stabilized--your mileage may vary.

Large file support

If you have filesystems that support "large files" (files larger than 2 gigabytes), you may now also be able to create and access them from Perl.

    NOTE: The default action is to enable large file support, if
    available on the platform.

If the large file support is on, and you have a Fcntl constant O_LARGEFILE, the O_LARGEFILE is automatically added to the flags of sysopen().

Beware that unless your filesystem also supports "sparse files" seeking to umpteen petabytes may be inadvisable.

Note that in addition to requiring a proper file system to do large files you may also need to adjust your per-process (or your per-system, or per-process-group, or per-user-group) maximum filesize limits before running Perl scripts that try to handle large files, especially if you intend to write such files.

Finally, in addition to your process/process group maximum filesize limits, you may have quota limits on your filesystems that stop you (your user id or your user group id) from using large files.

Adjusting your process/user/group/file system/operating system limits is outside the scope of Perl core language. For process limits, you may try increasing the limits using your shell's limits/limit/ulimit command before running Perl. The BSD::Resource extension (not included with the standard Perl distribution) may also be of use, it offers the getrlimit/setrlimit interface that can be used to adjust process resource usage limits, including the maximum filesize limit.

Long doubles

In some systems you may be able to use long doubles to enhance the range and precision of your double precision floating point numbers (that is, Perl's numbers). Use Configure -Duselongdouble to enable this support (if it is available).

"more bits"

You can "Configure -Dusemorebits" to turn on both the 64-bit support and the long double support.

Enhanced support for sort() subroutines

Perl subroutines with a prototype of ($$), and XSUBs in general, can now be used as sort subroutines. In either case, the two elements to be compared are passed as normal parameters in @_. See sort in the perlfunc manpage.

For unprototyped sort subroutines, the historical behavior of passing the elements to be compared as the global variables $a and $b remains unchanged.

sort $coderef @foo allowed

sort() did not accept a subroutine reference as the comparison function in earlier versions. This is now permitted.

File globbing implemented internally

Perl now uses the File::Glob implementation of the glob() operator automatically. This avoids using an external csh process and the problems associated with it.

    NOTE: This is currently an experimental feature.  Interfaces and
    implementation are subject to change.

Support for CHECK blocks

In addition to BEGIN, INIT, END, DESTROY and AUTOLOAD, subroutines named CHECK are now special. These are queued up during compilation and behave similar to END blocks, except they are called at the end of compilation rather than at the end of execution. They cannot be called directly.

POSIX character class syntax [: :] supported

For example to match alphabetic characters use /[[:alpha:]]/. See the perlre manpage for details.

Better pseudo-random number generator

In 5.005_0x and earlier, perl's rand() function used the C library rand(3) function. As of 5.005_52, Configure tests for drand48(), random(), and rand() (in that order) and picks the first one it finds.

These changes should result in better random numbers from rand().

Improved qw// operator

The qw// operator is now evaluated at compile time into a true list instead of being replaced with a run time call to split(). This removes the confusing misbehaviour of qw// in scalar context, which had inherited that behaviour from split().

Thus:

    $foo = ($bar) = qw(a b c); print "$foo|$bar\n";

now correctly prints "3|a", instead of "2|a".

Better worst-case behavior of hashes

Small changes in the hashing algorithm have been implemented in order to improve the distribution of lower order bits in the hashed value. This is expected to yield better performance on keys that are repeated sequences.

pack() format 'Z' supported

The new format type 'Z' is useful for packing and unpacking null-terminated strings. See pack in the perlfunc manpage.

pack() format modifier '!' supported

The new format type modifier '!' is useful for packing and unpacking native shorts, ints, and longs. See pack in the perlfunc manpage.

pack() and unpack() support counted strings

The template character '/' can be used to specify a counted string type to be packed or unpacked. See pack in the perlfunc manpage.

Comments in pack() templates

The '#' character in a template introduces a comment up to end of the line. This facilitates documentation of pack() templates.

Weak references

In previous versions of Perl, you couldn't cache objects so as to allow them to be deleted if the last reference from outside the cache is deleted. The reference in the cache would hold a reference count on the object and the objects would never be destroyed.

Another familiar problem is with circular references. When an object references itself, its reference count would never go down to zero, and it would not get destroyed until the program is about to exit.

Weak references solve this by allowing you to "weaken" any reference, that is, make it not count towards the reference count. When the last non-weak reference to an object is deleted, the object is destroyed and all the weak references to the object are automatically undef-ed.

To use this feature, you need the Devel::WeakRef package from CPAN, which contains additional documentation.

    NOTE: This is an experimental feature.  Details are subject to change.

Binary numbers supported

Binary numbers are now supported as literals, in s?printf formats, and oct():

    $answer = 0b101010;
    printf "The answer is: %b\n", oct("0b101010");

Lvalue subroutines

Subroutines can now return modifiable lvalues. See Lvalue subroutines in the perlsub manpage.

    NOTE: This is an experimental feature.  Details are subject to change.

Some arrows may be omitted in calls through references

Perl now allows the arrow to be omitted in many constructs involving subroutine calls through references. For example, $foo[10]->('foo') may now be written $foo[10]('foo'). This is rather similar to how the arrow may be omitted from $foo[10]->{'foo'}. Note however, that the arrow is still required for foo(10)->('bar').

Boolean assignment operators are legal lvalues

Constructs such as ($a ||= 2) += 1 are now allowed.

exists() is supported on subroutine names

The exists() builtin now works on subroutine names. A subroutine is considered to exist if it has been declared (even if implicitly). See exists in the perlfunc manpage for examples.

exists() and delete() are supported on array elements

The exists() and delete() builtins now work on simple arrays as well. The behavior is similar to that on hash elements.

exists() can be used to check whether an array element has been initialized. This avoids autovivifying array elements that don't exist. If the array is tied, the EXISTS() method in the corresponding tied package will be invoked.

delete() may be used to remove an element from the array and return it. The array element at that position returns to its uninitialized state, so that testing for the same element with exists() will return false. If the element happens to be the one at the end, the size of the array also shrinks up to the highest element that tests true for exists(), or 0 if none such is found. If the array is tied, the DELETE() method in the corresponding tied package will be invoked.

See exists in the perlfunc manpage and delete in the perlfunc manpage for examples.

Pseudo-hashes work better

Dereferencing some types of reference values in a pseudo-hash, such as $ph->{foo}[1], was accidentally disallowed. This has been corrected.

When applied to a pseudo-hash element, exists() now reports whether the specified value exists, not merely if the key is valid.

delete() now works on pseudo-hashes. When given a pseudo-hash element or slice it deletes the values corresponding to the keys (but not the keys themselves). See Pseudo-hashes: Using an array as a hash in the perlref manpage.

Pseudo-hash slices with constant keys are now optimized to array lookups at compile-time.

List assignments to pseudo-hash slices are now supported.

The fields pragma now provides ways to create pseudo-hashes, via fields::new() and fields::phash(). See the fields manpage.

    NOTE: The pseudo-hash data type continues to be experimental.
    Limiting oneself to the interface elements provided by the
    fields pragma will provide protection from any future changes.

Automatic flushing of output buffers

fork(), exec(), system(), qx//, and pipe open()s now flush buffers of all files opened for output when the operation was attempted. This mostly eliminates confusing buffering mishaps suffered by users unaware of how Perl internally handles I/O.

This is not supported on some platforms like Solaris where a suitably correct implementation of fflush(NULL) isn't available.

Better diagnostics on meaningless filehandle operations

Constructs such as open(<FH>) and close(<FH>) are compile time errors. Attempting to read from filehandles that were opened only for writing will now produce warnings (just as writing to read-only filehandles does).

Where possible, buffered data discarded from duped input filehandle

open(NEW, "<&OLD") now attempts to discard any data that was previously read and buffered in OLD before duping the handle. On platforms where doing this is allowed, the next read operation on NEW will return the same data as the corresponding operation on OLD. Formerly, it would have returned the data from the start of the following disk block instead.

eof() has the same old magic as <>

eof() would return true if no attempt to read from <> had yet been made. eof() has been changed to have a little magic of its own, it now opens the <> files.

binmode() can be used to set :crlf and :raw modes

binmode() now accepts a second argument that specifies a discipline for the handle in question. The two pseudo-disciplines ":raw" and ":crlf" are currently supported on DOS-derivative platforms. See binmode in the perlfunc manpage and the open manpage.

-T filetest recognizes UTF-8 encoded files as "text"

The algorithm used for the -T filetest has been enhanced to correctly identify UTF-8 content as "text".

system(), backticks and pipe open now reflect exec() failure

On Unix and similar platforms, system(), qx() and open(FOO, "cmd |") etc., are implemented via fork() and exec(). When the underlying exec() fails, earlier versions did not report the error properly, since the exec() happened to be in a different process.

The child process now communicates with the parent about the error in launching the external command, which allows these constructs to return with their usual error value and set $!.

Improved diagnostics

Line numbers are no longer suppressed (under most likely circumstances) during the global destruction phase.

Diagnostics emitted from code running in threads other than the main thread are now accompanied by the thread ID.

Embedded null characters in diagnostics now actually show up. They used to truncate the message in prior versions.

$foo::a and $foo::b are now exempt from "possible typo" warnings only if sort() is encountered in package foo.

Unrecognized alphabetic escapes encountered when parsing quote constructs now generate a warning, since they may take on new semantics in later versions of Perl.

Many diagnostics now report the internal operation in which the warning was provoked, like so:

    Use of uninitialized value in concatenation (.) at (eval 1) line 1.
    Use of uninitialized value in print at (eval 1) line 1.

Diagnostics that occur within eval may also report the file and line number where the eval is located, in addition to the eval sequence number and the line number within the evaluated text itself. For example:

    Not enough arguments for scalar at (eval 4)[newlib/perl5db.pl:1411] line 2, at EOF

Diagnostics follow STDERR

Diagnostic output now goes to whichever file the STDERR handle is pointing at, instead of always going to the underlying C runtime library's stderr.

More consistent close-on-exec behavior

On systems that support a close-on-exec flag on filehandles, the flag is now set for any handles created by pipe(), socketpair(), socket(), and accept(), if that is warranted by the value of $^F that may be in effect. Earlier versions neglected to set the flag for handles created with these operators. See pipe in the perlfunc manpage, socketpair in the perlfunc manpage, socket in the perlfunc manpage, accept in the perlfunc manpage, and $^F in the perlvar manpage.

syswrite() ease-of-use

The length argument of syswrite() has become optional.

Better syntax checks on parenthesized unary operators

Expressions such as:

    print defined(&foo,&bar,&baz);
    print uc("foo","bar","baz");
    undef($foo,&bar);

used to be accidentally allowed in earlier versions, and produced unpredictable behaviour. Some produced ancillary warnings when used in this way; others silently did the wrong thing.

The parenthesized forms of most unary operators that expect a single argument now ensure that they are not called with more than one argument, making the cases shown above syntax errors. The usual behaviour of:

    print defined &foo, &bar, &baz;
    print uc "foo", "bar", "baz";
    undef $foo, &bar;

remains unchanged. See the perlop manpage.

Bit operators support full native integer width

The bit operators (& | ^ ~ << >>) now operate on the full native integral width (the exact size of which is available in $Config{ivsize}). For example, if your platform is either natively 64-bit or if Perl has been configured to use 64-bit integers, these operations apply to 8 bytes (as opposed to 4 bytes on 32-bit platforms). For portability, be sure to mask off the excess bits in the result of unary ~, e.g., ~$x & 0xffffffff.

Improved security features

More potentially unsafe operations taint their results for improved security.

The passwd and shell fields returned by the getpwent(), getpwnam(), and getpwuid() are now tainted, because the user can affect their own encrypted password and login shell.

The variable modified by shmread(), and messages returned by msgrcv() (and its object-oriented interface IPC::SysV::Msg::rcv) are also tainted, because other untrusted processes can modify messages and shared memory segments for their own nefarious purposes.

More functional bareword prototype (*)

Bareword prototypes have been rationalized to enable them to be used to override builtins that accept barewords and interpret them in a special way, such as require or do.

Arguments prototyped as * will now be visible within the subroutine as either a simple scalar or as a reference to a typeglob. See Prototypes in the perlsub manpage.

require and do may be overridden

require and do 'file' operations may be overridden locally by importing subroutines of the same name into the current package (or globally by importing them into the CORE::GLOBAL:: namespace). Overriding require will also affect use, provided the override is visible at compile-time. See Overriding Built-in Functions in the perlsub manpage.

$^X variables may now have names longer than one character

Formerly, $^X was synonymous with ${"\cX"}, but $^XY was a syntax error. Now variable names that begin with a control character may be arbitrarily long. However, for compatibility reasons, these variables must be written with explicit braces, as ${^XY} for example. ${^XYZ} is synonymous with ${"\cXYZ"}. Variable names with more than one control character, such as ${^XY^Z}, are illegal.

The old syntax has not changed. As before, `^X' may be either a literal control-X character or the two-character sequence `caret' plus `X'. When braces are omitted, the variable name stops after the control character. Thus "$^XYZ" continues to be synonymous with $^X . "YZ" as before.

As before, lexical variables may not have names beginning with control characters. As before, variables whose names begin with a control character are always forced to be in package `main'. All such variables are reserved for future extensions, except those that begin with ^_, which may be used by user programs and are guaranteed not to acquire special meaning in any future version of Perl.

New variable $^C reflects -c switch

$^C has a boolean value that reflects whether perl is being run in compile-only mode (i.e. via the -c switch). Since BEGIN blocks are executed under such conditions, this variable enables perl code to determine whether actions that make sense only during normal running are warranted. See the perlvar manpage.

New variable $^V contains Perl version as a string

$^V contains the Perl version number as a string composed of characters whose ordinals match the version numbers, i.e. v5.6.0. This may be used in string comparisons.

See Support for strings represented as a vector of ordinals for an example.

Optional Y2K warnings

If Perl is built with the cpp macro PERL_Y2KWARN defined, it emits optional warnings when concatenating the number 19 with another number.

This behavior must be specifically enabled when running Configure. See INSTALL and README.Y2K.

Arrays now always interpolate into double-quoted strings

In double-quoted strings, arrays now interpolate, no matter what. The behavior in earlier versions of perl 5 was that arrays would interpolate into strings if the array had been mentioned before the string was compiled, and otherwise Perl would raise a fatal compile-time error. In versions 5.000 through 5.003, the error was

        Literal @example now requires backslash

In versions 5.004_01 through 5.6.0, the error was

        In string, @example now must be written as \@example

The idea here was to get people into the habit of writing "fred\@example.com" when they wanted a literal @ sign, just as they have always written "Give me back my \$5" when they wanted a literal $ sign.

Starting with 5.6.1, when Perl now sees an @ sign in a double-quoted string, it always attempts to interpolate an array, regardless of whether or not the array has been used or declared already. The fatal error has been downgraded to an optional warning:

        Possible unintended interpolation of @example in string

This warns you that "fred@example.com" is going to turn into fred.com if you don't backslash the @. See http://www.plover.com/~mjd/perl/at-error.html for more details about the history here.

@- and @+ provide starting/ending offsets of regex matches

The new magic variables @- and @+ provide the starting and ending offsets, respectively, of $&, $1, $2, etc. See the perlvar manpage for details.

Modules and Pragmata

Modules

attributes

While used internally by Perl as a pragma, this module also provides a way to fetch subroutine and variable attributes. See the attributes manpage.

B

The Perl Compiler suite has been extensively reworked for this release. More of the standard Perl testsuite passes when run under the Compiler, but there is still a significant way to go to achieve production quality compiled executables.

    NOTE: The Compiler suite remains highly experimental.  The
    generated code may not be correct, even when it manages to execute
    without errors.
Benchmark

Overall, Benchmark results exhibit lower average error and better timing accuracy.

You can now run tests for n seconds instead of guessing the right number of tests to run: e.g., timethese(-5, ...) will run each code for at least 5 CPU seconds. Zero as the "number of repetitions" means "for at least 3 CPU seconds". The output format has also changed. For example:

   use Benchmark;$x=3;timethese(-5,{a=>sub{$x*$x},b=>sub{$x**2}})

will now output something like this:

   Benchmark: running a, b, each for at least 5 CPU seconds...
            a:  5 wallclock secs ( 5.77 usr +  0.00 sys =  5.77 CPU) @ 200551.91/s (n=1156516)
            b:  4 wallclock secs ( 5.00 usr +  0.02 sys =  5.02 CPU) @ 159605.18/s (n=800686)

New features: "each for at least N CPU seconds...", "wallclock secs", and the "@ operations/CPU second (n=operations)".

timethese() now returns a reference to a hash of Benchmark objects containing the test results, keyed on the names of the tests.

timethis() now returns the iterations field in the Benchmark result object instead of 0.

timethese(), timethis(), and the new cmpthese() (see below) can also take a format specifier of 'none' to suppress output.

A new function countit() is just like timeit() except that it takes a TIME instead of a COUNT.

A new function cmpthese() prints a chart comparing the results of each test returned from a timethese() call. For each possible pair of tests, the percentage speed difference (iters/sec or seconds/iter) is shown.

For other details, see the Benchmark manpage.

ByteLoader

The ByteLoader is a dedicated extension to generate and run Perl bytecode. See the ByteLoader manpage.

constant

References can now be used.

The new version also allows a leading underscore in constant names, but disallows a double leading underscore (as in "__LINE__"). Some other names are disallowed or warned against, including BEGIN, END, etc. Some names which were forced into main:: used to fail silently in some cases; now they're fatal (outside of main::) and an optional warning (inside of main::). The ability to detect whether a constant had been set with a given name has been added.

See the constant manpage.

charnames

This pragma implements the \N string escape. See the charnames manpage.

Data::Dumper

A Maxdepth setting can be specified to avoid venturing too deeply into deep data structures. See the Data::Dumper manpage.

The XSUB implementation of Dump() is now automatically called if the Useqq setting is not in use.

Dumping qr// objects works correctly.

DB

DB is an experimental module that exposes a clean abstraction to Perl's debugging API.

DB_File

DB_File can now be built with Berkeley DB versions 1, 2 or 3. See ext/DB_File/Changes.

Devel::DProf

Devel::DProf, a Perl source code profiler has been added. See the Devel::DProf manpage and the dprofpp manpage.

Devel::Peek

The Devel::Peek module provides access to the internal representation of Perl variables and data. It is a data debugging tool for the XS programmer.

Dumpvalue

The Dumpvalue module provides screen dumps of Perl data.

DynaLoader

DynaLoader now supports a dl_unload_file() function on platforms that support unloading shared objects using dlclose().

Perl can also optionally arrange to unload all extension shared objects loaded by Perl. To enable this, build Perl with the Configure option -Accflags=-DDL_UNLOAD_ALL_AT_EXIT. (This maybe useful if you are using Apache with mod_perl.)

English

$PERL_VERSION now stands for $^V (a string value) rather than for $] (a numeric value).

Env

Env now supports accessing environment variables like PATH as array variables.

Fcntl

More Fcntl constants added: F_SETLK64, F_SETLKW64, O_LARGEFILE for large file (more than 4GB) access (NOTE: the O_LARGEFILE is automatically added to sysopen() flags if large file support has been configured, as is the default), Free/Net/OpenBSD locking behaviour flags F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined mask of O_RDONLY, O_WRONLY, and O_RDWR. The seek()/sysseek() constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the :seek tag. The chmod()/stat() S_IF* constants and S_IS* functions are available via the :mode tag.

File::Compare

A compare_text() function has been added, which allows custom comparison functions. See the File::Compare manpage.

File::Find

File::Find now works correctly when the wanted() function is either autoloaded or is a symbolic reference.

A bug that caused File::Find to lose track of the working directory when pruning top-level directories has been fixed.

File::Find now also supports several other options to control its behavior. It can follow symbolic links if the follow option is specified. Enabling the no_chdir option will make File::Find skip changing the current directory when walking directories. The untaint flag can be useful when running with taint checks enabled.

See the File::Find manpage.

File::Glob

This extension implements BSD-style file globbing. By default, it will also be used for the internal implementation of the glob() operator. See the File::Glob manpage.

File::Spec

New methods have been added to the File::Spec module: devnull() returns the name of the null device (/dev/null on Unix) and tmpdir() the name of the temp directory (normally /tmp on Unix). There are now also methods to convert between absolute and relative filenames: abs2rel() and rel2abs(). For compatibility with operating systems that specify volume names in file paths, the splitpath(), splitdir(), and catdir() methods have been added.

File::Spec::Functions

The new File::Spec::Functions modules provides a function interface to the File::Spec module. Allows shorthand

    $fullname = catfile($dir1, $dir2, $file);

instead of

    $fullname = File::Spec->catfile($dir1, $dir2, $file);
Getopt::Long

Getopt::Long licensing has changed to allow the Perl Artistic License as well as the GPL. It used to be GPL only, which got in the way of non-GPL applications that wanted to use Getopt::Long.

Getopt::Long encourages the use of Pod::Usage to produce help messages. For example:

    use Getopt::Long;
    use Pod::Usage;
    my $man = 0;
    my $help = 0;
    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
    pod2usage(1) if $help;
    pod2usage(-exitstatus => 0, -verbose => 2) if $man;

    __END__
    =head1 NAME
    sample - Using Getopt::Long and Pod::Usage
    =head1 SYNOPSIS
    sample [options] [file ...]
     Options:
       -help            brief help message
       -man             full documentation
    =head1 OPTIONS
    =over 8
    =item B<-help>
    Print a brief help message and exits.
    =item B<-man>
    Prints the manual page and exits.
    =back
    =head1 DESCRIPTION
    B<This program> will read the given input file(s) and do something
    useful with the contents thereof.
    =cut

See the Pod::Usage manpage for details.

A bug that prevented the non-option call-back <> from being specified as the first argument has been fixed.

To specify the characters < and > as option starters, use ><. Note, however, that changing option starters is strongly deprecated.

IO

write() and syswrite() will now accept a single-argument form of the call, for consistency with Perl's syswrite().

You can now create a TCP-based IO::Socket::INET without forcing a connect attempt. This allows you to configure its options (like making it non-blocking) and then call connect() manually.

A bug that prevented the IO::Socket::protocol() accessor from ever returning the correct value has been corrected.

IO::Socket::connect now uses non-blocking IO instead of alarm() to do connect timeouts.

IO::Socket::accept now uses select() instead of alarm() for doing timeouts.

IO::Socket::INET->new now sets $! correctly on failure. $@ is still set for backwards compatibility.

JPL

Java Perl Lingo is now distributed with Perl. See jpl/README for more information.

lib

use lib now weeds out any trailing duplicate entries. no lib removes all named entries.

Math::BigInt

The bitwise operations <<, >>, &, |, and ~ are now supported on bigints.

Math::Complex

The accessor methods Re, Im, arg, abs, rho, and theta can now also act as mutators (accessor $z->Re(), mutator $z->Re(3)).

The class method display_format and the corresponding object method display_format, in addition to accepting just one argument, now can also accept a parameter hash. Recognized keys of a parameter hash are "style", which corresponds to the old one parameter case, and two new parameters: "format", which is a printf()-style format string (defaults usually to "%.15g", you can revert to the default by setting the format string to undef) used for both parts of a complex number, and "polar_pretty_print" (defaults to true), which controls whether an attempt is made to try to recognize small multiples and rationals of pi (2pi, pi/2) at the argument (angle) of a polar complex number.

The potentially disruptive change is that in list context both methods now return the parameter hash, instead of only the value of the "style" parameter.

Math::Trig

A little bit of radial trigonometry (cylindrical and spherical), radial coordinate conversions, and the great circle distance were added.

Pod::Parser, Pod::InputObjects

Pod::Parser is a base class for parsing and selecting sections of pod documentation from an input stream. This module takes care of identifying pod paragraphs and commands in the input and hands off the parsed paragraphs and commands to user-defined methods which are free to interpret or translate them as they see fit.

Pod::InputObjects defines some input objects needed by Pod::Parser, and for advanced users of Pod::Parser that need more about a command besides its name and text.

As of release 5.6.0 of Perl, Pod::Parser is now the officially sanctioned "base parser code" recommended for use by all pod2xxx translators. Pod::Text (pod2text) and Pod::Man (pod2man) have already been converted to use Pod::Parser and efforts to convert Pod::HTML (pod2html) are already underway. For any questions or comments about pod parsing and translating issues and utilities, please use the pod-people@perl.org mailing list.

For further information, please see the Pod::Parser manpage and the Pod::InputObjects manpage.

Pod::Checker, podchecker

This utility checks pod files for correct syntax, according to the perlpod manpage. Obvious errors are flagged as such, while warnings are printed for mistakes that can be handled gracefully. The checklist is not complete yet. See the Pod::Checker manpage.

Pod::ParseUtils, Pod::Find

These modules provide a set of gizmos that are useful mainly for pod translators. Pod::Find traverses directory structures and returns found pod files, along with their canonical names (like File::Spec::Unix). Pod::ParseUtils contains Pod::List (useful for storing pod list information), Pod::Hyperlink (for parsing the contents of L<> sequences) and Pod::Cache (for caching information about pod files, e.g., link nodes).

Pod::Select, podselect

Pod::Select is a subclass of Pod::Parser which provides a function named "podselect()" to filter out user-specified sections of raw pod documentation from an input stream. podselect is a script that provides access to Pod::Select from other scripts to be used as a filter. See the Pod::Select manpage.

Pod::Usage, pod2usage

Pod::Usage provides the function "pod2usage()" to print usage messages for a Perl script based on its embedded pod documentation. The pod2usage() function is generally useful to all script authors since it lets them write and maintain a single source (the pods) for documentation, thus removing the need to create and maintain redundant usage message text consisting of information already in the pods.

There is also a pod2usage script which can be used from other kinds of scripts to print usage messages from pods (even for non-Perl scripts with pods embedded in comments).

For details and examples, please see the Pod::Usage manpage.

Pod::Text and Pod::Man

Pod::Text has been rewritten to use Pod::Parser. While pod2text() is still available for backwards compatibility, the module now has a new preferred interface. See the Pod::Text manpage for the details. The new Pod::Text module is easily subclassed for tweaks to the output, and two such subclasses (Pod::Text::Termcap for man-page-style bold and underlining using termcap information, and Pod::Text::Color for markup with ANSI color sequences) are now standard.

pod2man has been turned into a module, Pod::Man, which also uses Pod::Parser. In the process, several outstanding bugs related to quotes in section headers, quoting of code escapes, and nested lists have been fixed. pod2man is now a wrapper script around this module.

SDBM_File

An EXISTS method has been added to this module (and sdbm_exists() has been added to the underlying sdbm library), so one can now call exists on an SDBM_File tied hash and get the correct result, rather than a runtime error.

A bug that may have caused data loss when more than one disk block happens to be read from the database in a single FETCH() has been fixed.

Sys::Syslog

Sys::Syslog now uses XSUBs to access facilities from syslog.h so it no longer requires syslog.ph to exist.

Sys::Hostname

Sys::Hostname now uses XSUBs to call the C library's gethostname() or uname() if they exist.

Term::ANSIColor

Term::ANSIColor is a very simple module to provide easy and readable access to the ANSI color and highlighting escape sequences, supported by most ANSI terminal emulators. It is now included standard.

Time::Local

The timelocal() and timegm() functions used to silently return bogus results when the date fell outside the machine's integer range. They now consistently croak() if the date falls in an unsupported range.

Win32

The error return value in list context has been changed for all functions that return a list of values. Previously these functions returned a list with a single element undef if an error occurred. Now these functions return the empty list in these situations. This applies to the following functions:

    Win32::FsType
    Win32::GetOSVersion

The remaining functions are unchanged and continue to return undef on error even in list context.

The Win32::SetLastError(ERROR) function has been added as a complement to the Win32::GetLastError() function.

The new Win32::GetFullPathName(FILENAME) returns the full absolute pathname for FILENAME in scalar context. In list context it returns a two-element list containing the fully qualified directory name and the filename. See the Win32 manpage.

XSLoader

The XSLoader extension is a simpler alternative to DynaLoader. See the XSLoader manpage.

DBM Filters

A new feature called "DBM Filters" has been added to all the DBM modules--DB_File, GDBM_File, NDBM_File, ODBM_File, and SDBM_File. DBM Filters add four new methods to each DBM module:

    filter_store_key
    filter_store_value
    filter_fetch_key
    filter_fetch_value

These can be used to filter key-value pairs before the pairs are written to the database or just after they are read from the database. See the perldbmfilter manpage for further information.

Pragmata

use attrs is now obsolete, and is only provided for backward-compatibility. It's been replaced by the sub : attributes syntax. See Subroutine Attributes in the perlsub manpage and the attributes manpage.

Lexical warnings pragma, use warnings;, to control optional warnings. See the perllexwarn manpage.

use filetest to control the behaviour of filetests (-r -w ...). Currently only one subpragma implemented, "use filetest 'access';", that uses access(2) or equivalent to check permissions instead of using stat(2) as usual. This matters in filesystems where there are ACLs (access control lists): the stat(2) might lie, but access(2) knows better.

The open pragma can be used to specify default disciplines for handle constructors (e.g. open()) and for qx//. The two pseudo-disciplines :raw and :crlf are currently supported on DOS-derivative platforms (i.e. where binmode is not a no-op). See also binmode() can be used to set :crlf and :raw modes.

Utility Changes

dprofpp

dprofpp is used to display profile data generated using Devel::DProf. See the dprofpp manpage.

find2perl

The find2perl utility now uses the enhanced features of the File::Find module. The -depth and -follow options are supported. Pod documentation is also included in the script.

h2xs

The h2xs tool can now work in conjunction with C::Scan (available from CPAN) to automatically parse real-life header files. The -M, -a, -k, and -o options are new.

perlcc

perlcc now supports the C and Bytecode backends. By default, it generates output from the simple C backend rather than the optimized C backend.

Support for non-Unix platforms has been improved.

perldoc

perldoc has been reworked to avoid possible security holes. It will not by default let itself be run as the superuser, but you may still use the -U switch to try to make it drop privileges first.

The Perl Debugger

Many bug fixes and enhancements were added to perl5db.pl, the Perl debugger. The help documentation was rearranged. New commands include < ?, > ?, and { ? to list out current actions, man docpage to run your doc viewer on some perl docset, and support for quoted options. The help information was rearranged, and should be viewable once again if you're using less as your pager. A serious security hole was plugged--you should immediately remove all older versions of the Perl debugger as installed in previous releases, all the way back to perl3, from your system to avoid being bitten by this.

Improved Documentation

Many of the platform-specific README files are now part of the perl installation. See the perl manpage for the complete list.

perlapi.pod

The official list of public Perl API functions.

perlboot.pod

A tutorial for beginners on object-oriented Perl.

perlcompile.pod

An introduction to using the Perl Compiler suite.

perldbmfilter.pod

A howto document on using the DBM filter facility.

perldebug.pod

All material unrelated to running the Perl debugger, plus all low-level guts-like details that risked crushing the casual user of the debugger, have been relocated from the old manpage to the next entry below.

perldebguts.pod

This new manpage contains excessively low-level material not related to the Perl debugger, but slightly related to debugging Perl itself. It also contains some arcane internal details of how the debugging process works that may only be of interest to developers of Perl debuggers.

perlfork.pod

Notes on the fork() emulation currently available for the Windows platform.

perlfilter.pod

An introduction to writing Perl source filters.

perlhack.pod

Some guidelines for hacking the Perl source code.

perlintern.pod

A list of internal functions in the Perl source code. (List is currently empty.)

perllexwarn.pod

Introduction and reference information about lexically scoped warning categories.

perlnumber.pod

Detailed information about numbers as they are represented in Perl.

perlopentut.pod

A tutorial on using open() effectively.

perlreftut.pod

A tutorial that introduces the essentials of references.

perltootc.pod

A tutorial on managing class data for object modules.

perltodo.pod

Discussion of the most often wanted features that may someday be supported in Perl.

perlunicode.pod

An introduction to Unicode support features in Perl.

Performance enhancements

Simple sort() using { $a <=> $b } and the like are optimized

Many common sort() operations using a simple inlined block are now optimized for faster performance.

Optimized assignments to lexical variables

Certain operations in the RHS of assignment statements have been optimized to directly set the lexical variable on the LHS, eliminating redundant copying overheads.

Faster subroutine calls

Minor changes in how subroutine calls are handled internally provide marginal improvements in performance.

delete(), each(), values() and hash iteration are faster

The hash values returned by delete(), each(), values() and hashes in a list context are the actual values in the hash, instead of copies. This results in significantly better performance, because it eliminates needless copying in most situations.

Installation and Configuration Improvements

-Dusethreads means something different

The -Dusethreads flag now enables the experimental interpreter-based thread support by default. To get the flavor of experimental threads that was in 5.005 instead, you need to run Configure with "-Dusethreads -Duse5005threads".

As of v5.6.0, interpreter-threads support is still lacking a way to create new threads from Perl (i.e., use Thread; will not work with interpreter threads). use Thread; continues to be available when you specify the -Duse5005threads option to Configure, bugs and all.

    NOTE: Support for threads continues to be an experimental feature.
    Interfaces and implementation are subject to sudden and drastic changes.

New Configure flags

The following new flags may be enabled on the Configure command line by running Configure with -Dflag.

    usemultiplicity
    usethreads useithreads      (new interpreter threads: no Perl API yet)
    usethreads use5005threads   (threads as they were in 5.005)
    use64bitint                 (equal to now deprecated 'use64bits')
    use64bitall
    uselongdouble
    usemorebits
    uselargefiles
    usesocks                    (only SOCKS v5 supported)

Threadedness and 64-bitness now more daring

The Configure options enabling the use of threads and the use of 64-bitness are now more daring in the sense that they no more have an explicit list of operating systems of known threads/64-bit capabilities. In other words: if your operating system has the necessary APIs and datatypes, you should be able just to go ahead and use them, for threads by Configure -Dusethreads, and for 64 bits either explicitly by Configure -Duse64bitint or implicitly if your system has 64-bit wide datatypes. See also 64-bit support.

Long Doubles

Some platforms have "long doubles", floating point numbers of even larger range than ordinary "doubles". To enable using long doubles for Perl's scalars, use -Duselongdouble.

-Dusemorebits

You can enable both -Duse64bitint and -Duselongdouble with -Dusemorebits. See also 64-bit support.

-Duselargefiles

Some platforms support system APIs that are capable of handling large files (typically, files larger than two gigabytes). Perl will try to use these APIs if you ask for -Duselargefiles.

See Large file support for more information.

installusrbinperl

You can use "Configure -Uinstallusrbinperl" which causes installperl to skip installing perl also as /usr/bin/perl. This is useful if you prefer not to modify /usr/bin for some reason or another but harmful because many scripts assume to find Perl in /usr/bin/perl.

SOCKS support

You can use "Configure -Dusesocks" which causes Perl to probe for the SOCKS proxy protocol library (v5, not v4). For more information on SOCKS, see:

    http://www.socks.nec.com/

-A flag

You can "post-edit" the Configure variables using the Configure -A switch. The editing happens immediately after the platform specific hints files have been processed but before the actual configuration process starts. Run Configure -h to find out the full -A syntax.

Enhanced Installation Directories

The installation structure has been enriched to improve the support for maintaining multiple versions of perl, to provide locations for vendor-supplied modules, scripts, and manpages, and to ease maintenance of locally-added modules, scripts, and manpages. See the section on Installation Directories in the INSTALL file for complete details. For most users building and installing from source, the defaults should be fine.

If you previously used Configure -Dsitelib or -Dsitearch to set special values for library directories, you might wish to consider using the new -Dsiteprefix setting instead. Also, if you wish to re-use a config.sh file from an earlier version of perl, you should be sure to check that Configure makes sensible choices for the new directories. See INSTALL for complete details.

Platform specific changes

Supported platforms

  • The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread extension.

  • GNU/Hurd is now supported.

  • Rhapsody/Darwin is now supported.

  • EPOC is now supported (on Psion 5).

  • The cygwin port (formerly cygwin32) has been greatly improved.

DOS

  • Perl now works with djgpp 2.02 (and 2.03 alpha).

  • Environment variable names are not converted to uppercase any more.

  • Incorrect exit codes from backticks have been fixed.

  • This port continues to use its own builtin globbing (not File::Glob).

OS390 (OpenEdition MVS)

Support for this EBCDIC platform has not been renewed in this release. There are difficulties in reconciling Perl's standardization on UTF-8 as its internal representation for characters with the EBCDIC character set, because the two are incompatible.

It is unclear whether future versions will renew support for this platform, but the possibility exists.

VMS

Numerous revisions and extensions to configuration, build, testing, and installation process to accommodate core changes and VMS-specific options.

Expand %ENV-handling code to allow runtime mapping to logical names, CLI symbols, and CRTL environ array.

Extension of subprocess invocation code to accept filespecs as command "verbs".

Add to Perl command line processing the ability to use default file types and to recognize Unix-style 2>&1.

Expansion of File::Spec::VMS routines, and integration into ExtUtils::MM_VMS.

Extension of ExtUtils::MM_VMS to handle complex extensions more flexibly.

Barewords at start of Unix-syntax paths may be treated as text rather than only as logical names.

Optional secure translation of several logical names used internally by Perl.

Miscellaneous bugfixing and porting of new core code to VMS.

Thanks are gladly extended to the many people who have contributed VMS patches, testing, and ideas.

Win32

Perl can now emulate fork() internally, using multiple interpreters running in different concurrent threads. This support must be enabled at build time. See the perlfork manpage for detailed information.

When given a pathname that consists only of a drivename, such as A:, opendir() and stat() now use the current working directory for the drive rather than the drive root.

The builtin XSUB functions in the Win32:: namespace are documented. See the Win32 manpage.

$^X now contains the full path name of the running executable.

A Win32::GetLongPathName() function is provided to complement Win32::GetFullPathName() and Win32::GetShortPathName(). See the Win32 manpage.

POSIX::uname() is supported.

system(1,...) now returns true process IDs rather than process handles. kill() accepts any real process id, rather than strictly return values from system(1,...).

For better compatibility with Unix, kill(0, $pid) can now be used to test whether a process exists.

The Shell module is supported.

Better support for building Perl under command.com in Windows 95 has been added.

Scripts are read in binary mode by default to allow ByteLoader (and the filter mechanism in general) to work properly. For compatibility, the DATA filehandle will be set to text mode if a carriage return is detected at the end of the line containing the __END__ or __DATA__ token; if not, the DATA filehandle will be left open in binary mode. Earlier versions always opened the DATA filehandle in text mode.

The glob() operator is implemented via the File::Glob extension, which supports glob syntax of the C shell. This increases the flexibility of the glob() operator, but there may be compatibility issues for programs that relied on the older globbing syntax. If you want to preserve compatibility with the older syntax, you might want to run perl with -MFile::DosGlob. For details and compatibility information, see the File::Glob manpage.

Significant bug fixes

<HANDLE> on empty files

With $/ set to undef, "slurping" an empty file returns a string of zero length (instead of undef, as it used to) the first time the HANDLE is read after $/ is set to undef. Further reads yield undef.

This means that the following will append "foo" to an empty file (it used to do nothing):

    perl -0777 -pi -e 's/^/foo/' empty_file

The behaviour of:

    perl -pi -e 's/^/foo/' empty_file

is unchanged (it continues to leave the file empty).

eval '...' improvements

Line numbers (as reflected by caller() and most diagnostics) within eval '...' were often incorrect where here documents were involved. This has been corrected.

Lexical lookups for variables appearing in eval '...' within functions that were themselves called within an eval '...' were searching the wrong place for lexicals. The lexical search now correctly ends at the subroutine's block boundary.

The use of return within eval {...} caused $@ not to be reset correctly when no exception occurred within the eval. This has been fixed.

Parsing of here documents used to be flawed when they appeared as the replacement expression in eval 's/.../.../e'. This has been fixed.

All compilation errors are true errors

Some "errors" encountered at compile time were by necessity generated as warnings followed by eventual termination of the program. This enabled more such errors to be reported in a single run, rather than causing a hard stop at the first error that was encountered.

The mechanism for reporting such errors has been reimplemented to queue compile-time errors and report them at the end of the compilation as true errors rather than as warnings. This fixes cases where error messages leaked through in the form of warnings when code was compiled at run time using eval STRING, and also allows such errors to be reliably trapped using eval "...".

Implicitly closed filehandles are safer

Sometimes implicitly closed filehandles (as when they are localized, and Perl automatically closes them on exiting the scope) could inadvertently set $? or $!. This has been corrected.

Behavior of list slices is more consistent

When taking a slice of a literal list (as opposed to a slice of an array or hash), Perl used to return an empty list if the result happened to be composed of all undef values.

The new behavior is to produce an empty list if (and only if) the original list was empty. Consider the following example:

    @a = (1,undef,undef,2)[2,1,2];

The old behavior would have resulted in @a having no elements. The new behavior ensures it has three undefined elements.

Note in particular that the behavior of slices of the following cases remains unchanged:

    @a = ()[1,2];
    @a = (getpwent)[7,0];
    @a = (anything_returning_empty_list())[2,1,2];
    @a = @b[2,1,2];
    @a = @c{'a','b','c'};

See the perldata manpage.

(\$) prototype and $foo{a}

A scalar reference prototype now correctly allows a hash or array element in that slot.

goto &sub and AUTOLOAD

The goto &sub construct works correctly when &sub happens to be autoloaded.

-bareword allowed under use integer

The autoquoting of barewords preceded by - did not work in prior versions when the integer pragma was enabled. This has been fixed.

Failures in DESTROY()

When code in a destructor threw an exception, it went unnoticed in earlier versions of Perl, unless someone happened to be looking in $@ just after the point the destructor happened to run. Such failures are now visible as warnings when warnings are enabled.

Locale bugs fixed

printf() and sprintf() previously reset the numeric locale back to the default "C" locale. This has been fixed.

Numbers formatted according to the local numeric locale (such as using a decimal comma instead of a decimal dot) caused "isn't numeric" warnings, even while the operations accessing those numbers produced correct results. These warnings have been discontinued.

Memory leaks

The eval 'return sub {...}' construct could sometimes leak memory. This has been fixed.

Operations that aren't filehandle constructors used to leak memory when used on invalid filehandles. This has been fixed.

Constructs that modified @_ could fail to deallocate values in @_ and thus leak memory. This has been corrected.

Spurious subroutine stubs after failed subroutine calls

Perl could sometimes create empty subroutine stubs when a subroutine was not found in the package. Such cases stopped later method lookups from progressing into base packages. This has been corrected.

Taint failures under -U

When running in unsafe mode, taint violations could sometimes cause silent failures. This has been fixed.

END blocks and the -c switch

Prior versions used to run BEGIN and END blocks when Perl was run in compile-only mode. Since this is typically not the expected behavior, END blocks are not executed anymore when the -c switch is used, or if compilation fails.

See Support for CHECK blocks for how to run things when the compile phase ends.

Potential to leak DATA filehandles

Using the __DATA__ token creates an implicit filehandle to the file that contains the token. It is the program's responsibility to close it when it is done reading from it.

This caveat is now better explained in the documentation. See the perldata manpage.

New or Changed Diagnostics

"%s" variable %s masks earlier declaration in same %s

(W misc) A "my" or "our" variable has been redeclared in the current scope or statement, effectively eliminating all access to the previous instance. This is almost always a typographical error. Note that the earlier variable will still exist until the end of the scope or until all closure referents to it are destroyed.

"my sub" not yet implemented

(F) Lexically scoped subroutines are not yet implemented. Don't try that yet.

"our" variable %s redeclared

(W misc) You seem to have already declared the same global once before in the current lexical scope.

'!' allowed only after types %s

(F) The '!' is allowed in pack() and unpack() only after certain types. See pack in the perlfunc manpage.

/ cannot take a count

(F) You had an unpack template indicating a counted-length string, but you have also specified an explicit size for the string. See pack in the perlfunc manpage.

/ must be followed by a, A or Z

(F) You had an unpack template indicating a counted-length string, which must be followed by one of the letters a, A or Z to indicate what sort of string is to be unpacked. See pack in the perlfunc manpage.

/ must be followed by a*, A* or Z*

(F) You had a pack template indicating a counted-length string, Currently the only things that can have their length counted are a*, A* or Z*. See pack in the perlfunc manpage.

/ must follow a numeric type

(F) You had an unpack template that contained a '#', but this did not follow some numeric unpack specification. See pack in the perlfunc manpage.

/%s/: Unrecognized escape \\%c passed through

(W regexp) You used a backslash-character combination which is not recognized by Perl. This combination appears in an interpolated variable or a '-delimited regular expression. The character was understood literally.

/%s/: Unrecognized escape \\%c in character class passed through

(W regexp) You used a backslash-character combination which is not recognized by Perl inside character classes. The character was understood literally.

/%s/ should probably be written as "%s"

(W syntax) You have used a pattern where Perl expected to find a string, as in the first argument to join. Perl will treat the true or false result of matching the pattern against $_ as the string, which is probably not what you had in mind.

%s() called too early to check prototype

(W prototype) You've called a function that has a prototype before the parser saw a definition or declaration for it, and Perl could not check that the call conforms to the prototype. You need to either add an early prototype declaration for the subroutine in question, or move the subroutine definition ahead of the call to get proper prototype checking. Alternatively, if you are certain that you're calling the function correctly, you may put an ampersand before the name to avoid the warning. See the perlsub manpage.

%s argument is not a HASH or ARRAY element

(F) The argument to exists() must be a hash or array element, such as:

    $foo{$bar}
    $ref->{"susie"}[12]
%s argument is not a HASH or ARRAY element or slice

(F) The argument to delete() must be either a hash or array element, such as:

    $foo{$bar}
    $ref->{"susie"}[12]

or a hash or array slice, such as:

    @foo[$bar, $baz, $xyzzy]
    @{$ref->[12]}{"susie", "queue"}
%s argument is not a subroutine name

(F) The argument to exists() for exists &sub must be a subroutine name, and not a subroutine call. exists &sub() will generate this error.

%s package attribute may clash with future reserved word: %s

(W reserved) A lowercase attribute name was used that had a package-specific handler. That name might have a meaning to Perl itself some day, even though it doesn't yet. Perhaps you should use a mixed-case attribute name, instead. See the attributes manpage.

(in cleanup) %s

(W misc) This prefix usually indicates that a DESTROY() method raised the indicated exception. Since destructors are usually called by the system at arbitrary points during execution, and often a vast number of times, the warning is issued only once for any number of failures that would otherwise result in the same message being repeated.

Failure of user callbacks dispatched using the G_KEEPERR flag could also result in this warning. See G_KEEPERR in the perlcall manpage.

<> should be quotes

(F) You wrote require <file> when you should have written require 'file'.

Attempt to join self

(F) You tried to join a thread from within itself, which is an impossible task. You may be joining the wrong thread, or you may need to move the join() to some other thread.

Bad evalled substitution pattern

(F) You've used the /e switch to evaluate the replacement for a substitution, but perl found a syntax error in the code to evaluate, most likely an unexpected right brace '}'.

Bad realloc() ignored

(S) An internal routine called realloc() on something that had never been malloc()ed in the first place. Mandatory, but can be disabled by setting environment variable PERL_BADFREE to 1.

Bareword found in conditional

(W bareword) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

    open FOO || die;

It may also indicate a misspelled constant that has been interpreted as a bareword:

    use constant TYPO => 1;
    if (TYOP) { print "foo" }

The strict pragma is useful in avoiding such errors.

Binary number > 0b11111111111111111111111111111111 non-portable

(W portable) The binary number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

Bit vector size > 32 non-portable

(W portable) Using bit vector sizes larger than 32 is non-portable.

Buffer overflow in prime_env_iter: %s

(W internal) A warning peculiar to VMS. While Perl was preparing to iterate over %ENV, it encountered a logical name or symbol definition which was too long, so it was truncated to the string shown.

Can't check filesystem of script "%s"

(P) For some reason you can't check the filesystem of the script for nosuid.

Can't declare class for non-scalar %s in "%s"

(S) Currently, only scalar variables can declared with a specific class qualifier in a "my" or "our" declaration. The semantics may be extended for other types of variables in future.

Can't declare %s in "%s"

(F) Only scalar, array, and hash variables may be declared as "my" or "our" variables. They must have ordinary identifiers as names.

Can't ignore signal CHLD, forcing to default

(W signal) Perl has detected that it is being run with the SIGCHLD signal (sometimes known as SIGCLD) disabled. Since disabling this signal will interfere with proper determination of exit status of child processes, Perl has reset the signal to its default value. This situation typically indicates that the parent program under which Perl may be running (e.g., cron) is being very careless.

Can't modify non-lvalue subroutine call

(F) Subroutines meant to be used in lvalue context should be declared as such, see Lvalue subroutines in the perlsub manpage.

Can't read CRTL environ

(S) A warning peculiar to VMS. Perl tried to read an element of %ENV from the CRTL's internal environment array and discovered the array was missing. You need to figure out where your CRTL misplaced its environ or define PERL_ENV_TABLES (see the perlvms manpage) so that environ is not searched.

Can't remove %s: %s, skipping file

(S) You requested an inplace edit without creating a backup file. Perl was unable to remove the original file to replace it with the modified file. The file was left unmodified.

Can't return %s from lvalue subroutine

(F) Perl detected an attempt to return illegal lvalues (such as temporary or readonly values) from a subroutine used as an lvalue. This is not allowed.

Can't weaken a nonreference

(F) You attempted to weaken something that was not a reference. Only references can be weakened.

Character class [:%s:] unknown

(F) The class in the character class [: :] syntax is unknown. See the perlre manpage.

Character class syntax [%s] belongs inside character classes

(W unsafe) The character class constructs [: :], [= =], and [. .] go inside character classes, the [] are part of the construct, for example: /[012[:alpha:]345]/. Note that [= =] and [. .] are not currently implemented; they are simply placeholders for future extensions.

Constant is not %s reference

(F) A constant value (perhaps declared using the use constant pragma) is being dereferenced, but it amounts to the wrong type of reference. The message indicates the type of reference that was expected. This usually indicates a syntax error in dereferencing the constant value. See Constant Functions in the perlsub manpage and the constant manpage.

constant(%s): %s

(F) The parser found inconsistencies either while attempting to define an overloaded constant, or when trying to find the character name specified in the \N{...} escape. Perhaps you forgot to load the corresponding overload or charnames pragma? See the charnames manpage and the overload manpage.

CORE::%s is not a keyword

(F) The CORE:: namespace is reserved for Perl keywords.

defined(@array) is deprecated

(D) defined() is not usually useful on arrays because it checks for an undefined scalar value. If you want to see if the array is empty, just use if (@array) { # not empty } for example.

defined(%hash) is deprecated

(D) defined() is not usually useful on hashes because it checks for an undefined scalar value. If you want to see if the hash is empty, just use if (%hash) { # not empty } for example.

Did not produce a valid header

See Server error.

(Did you mean "local" instead of "our"?)

(W misc) Remember that "our" does not localize the declared global variable. You have declared it again in the same lexical scope, which seems superfluous.

Document contains no data

See Server error.

entering effective %s failed

(F) While under the use filetest pragma, switching the real and effective uids or gids failed.

false [] range "%s" in regexp

(W regexp) A character class range must start and end at a literal character, not another character class like \d or [:alpha:]. The "-" in your false range is interpreted as a literal "-". Consider quoting the "-", "\-". See the perlre manpage.

Filehandle %s opened only for output

(W io) You tried to read from a filehandle opened only for writing. If you intended it to be a read/write filehandle, you needed to open it with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you intended only to read from the file, use "<". See open in the perlfunc manpage.

flock() on closed filehandle %s

(W closed) The filehandle you're attempting to flock() got itself closed some time before now. Check your logic flow. flock() operates on filehandles. Are you attempting to call flock() on a dirhandle by the same name?

Global symbol "%s" requires explicit package name

(F) You've said "use strict vars", which indicates that all variables must either be lexically scoped (using "my"), declared beforehand using "our", or explicitly qualified to say which package the global variable is in (using "::").

Hexadecimal number > 0xffffffff non-portable

(W portable) The hexadecimal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

Ill-formed CRTL environ value "%s"

(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal environ array, and encountered an element without the = delimiter used to separate keys from values. The element is ignored.

Ill-formed message in prime_env_iter: |%s|

(W internal) A warning peculiar to VMS. Perl tried to read a logical name or CLI symbol definition when preparing to iterate over %ENV, and didn't see the expected delimiter between key and value, so the line was ignored.

Illegal binary digit %s

(F) You used a digit other than 0 or 1 in a binary number.

Illegal binary digit %s ignored

(W digit) You may have tried to use a digit other than 0 or 1 in a binary number. Interpretation of the binary number stopped before the offending digit.

Illegal number of bits in vec

(F) The number of bits in vec() (the third argument) must be a power of two from 1 to 32 (or 64, if your platform supports that).

Integer overflow in %s number

(W overflow) The hexadecimal, octal or binary number you have specified either as a literal or as an argument to hex() or oct() is too big for your architecture, and has been converted to a floating point number. On a 32-bit architecture the largest hexadecimal, octal or binary number representable without overflow is 0xFFFFFFFF, 037777777777, or 0b11111111111111111111111111111111 respectively. Note that Perl transparently promotes all numbers to a floating point representation internally--subject to loss of precision errors in subsequent operations.

Invalid %s attribute: %s

The indicated attribute for a subroutine or variable was not recognized by Perl or by a user-supplied handler. See the attributes manpage.

Invalid %s attributes: %s

The indicated attributes for a subroutine or variable were not recognized by Perl or by a user-supplied handler. See the attributes manpage.

invalid [] range "%s" in regexp

The offending range is now explicitly displayed.

Invalid separator character %s in attribute list

(F) Something other than a colon or whitespace was seen between the elements of an attribute list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon. See the attributes manpage.

Invalid separator character %s in subroutine attribute list

(F) Something other than a colon or whitespace was seen between the elements of a subroutine attribute list. If the previous attribute had a parenthesised parameter list, perhaps that list was terminated too soon.

leaving effective %s failed

(F) While under the use filetest pragma, switching the real and effective uids or gids failed.

Lvalue subs returning %s not implemented yet

(F) Due to limitations in the current implementation, array and hash values cannot be returned in subroutines used in lvalue context. See Lvalue subroutines in the perlsub manpage.

Method %s not permitted

See Server error.

Missing %sbrace%s on \N{}

(F) Wrong syntax of character name literal \N{charname} within double-quotish context.

Missing command in piped open

(W pipe) You used the open(FH, "| command") or open(FH, "command |") construction, but the command was missing or blank.

Missing name in "my sub"

(F) The reserved syntax for lexically scoped subroutines requires that they have a name with which they can be found.

No %s specified for -%c

(F) The indicated command line switch needs a mandatory argument, but you haven't specified one.

No package name allowed for variable %s in "our"

(F) Fully qualified variable names are not allowed in "our" declarations, because that doesn't make much sense under existing semantics. Such syntax is reserved for future extensions.

No space allowed after -%c

(F) The argument to the indicated command line switch must follow immediately after the switch, without intervening spaces.

no UTC offset information; assuming local time is UTC

(S) A warning peculiar to VMS. Perl was unable to find the local timezone offset, so it's assuming that local system time is equivalent to UTC. If it's not, define the logical name SYS$TIMEZONE_DIFFERENTIAL to translate to the number of seconds which need to be added to UTC to get local time.

Octal number > 037777777777 non-portable

(W portable) The octal number you specified is larger than 2**32-1 (4294967295) and therefore non-portable between systems. See the perlport manpage for more on portability concerns.

See also the perlport manpage for writing portable code.

panic: del_backref

(P) Failed an internal consistency check while trying to reset a weak reference.

panic: kid popen errno read

(F) forked child returned an incomprehensible message about its errno.

panic: magic_killbackrefs

(P) Failed an internal consistency check while trying to reset all weak references to an object.

Parentheses missing around "%s" list

(W parenthesis) You said something like

    my $foo, $bar = @_;

when you meant

    my ($foo, $bar) = @_;

Remember that "my", "our", and "local" bind tighter than comma.

Possible unintended interpolation of %s in string

(W ambiguous) It used to be that Perl would try to guess whether you wanted an array interpolated or a literal @. It no longer does this; arrays are now always interpolated into strings. This means that if you try something like:

        print "fred@example.com";

and the array @example doesn't exist, Perl is going to print fred.com, which is probably not what you wanted. To get a literal @ sign in a string, put a backslash before it, just as you would to get a literal $ sign.

Possible Y2K bug: %s

(W y2k) You are concatenating the number 19 with another number, which could be a potential Year 2000 problem.

pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead

(W deprecated) You have written something like this:

    sub doit
    {
        use attrs qw(locked);
    }

You should use the new declaration syntax instead.

    sub doit : locked
    {
        ...

The use attrs pragma is now obsolete, and is only provided for backward-compatibility. See Subroutine Attributes in the perlsub manpage.

Premature end of script headers

See Server error.

Repeat count in pack overflows

(F) You can't specify a repeat count so large that it overflows your signed integers. See pack in the perlfunc manpage.

Repeat count in unpack overflows

(F) You can't specify a repeat count so large that it overflows your signed integers. See unpack in the perlfunc manpage.

realloc() of freed memory ignored

(S) An internal routine called realloc() on something that had already been freed.

Reference is already weak

(W misc) You have attempted to weaken a reference that is already weak. Doing so has no effect.

setpgrp can't take arguments

(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments, unlike POSIX setpgid(), which takes a process ID and process group ID.

Strange *+?{} on zero-length expression

(W regexp) You applied a regular expression quantifier in a place where it makes no sense, such as on a zero-width assertion. Try putting the quantifier inside the assertion instead. For example, the way to match "abc" provided that it is followed by three repetitions of "xyz" is /abc(?=(?:xyz){3})/, not /abc(?=xyz){3}/.

switching effective %s is not implemented

(F) While under the use filetest pragma, we cannot switch the real and effective uids or gids.

This Perl can't reset CRTL environ elements (%s)
This Perl can't set CRTL environ elements (%s=%s)

(W internal) Warnings peculiar to VMS. You tried to change or delete an element of the CRTL's internal environ array, but your copy of Perl wasn't built with a CRTL that contained the setenv() function. You'll need to rebuild Perl with a CRTL that does, or redefine PERL_ENV_TABLES (see the perlvms manpage) so that the environ array isn't the target of the change to %ENV which produced the warning.

Too late to run %s block

(W void) A CHECK or INIT block is being defined during run time proper, when the opportunity to run them has already passed. Perhaps you are loading a file with require or do when you should be using use instead. Or perhaps you should put the require or do inside a BEGIN block.

Unknown open() mode '%s'

(F) The second argument of 3-argument open() is not among the list of valid modes: <, >, >>, +<, +>, +>>, -|, |-.

Unknown process %x sent message to prime_env_iter: %s

(P) An error peculiar to VMS. Perl was reading values for %ENV before iterating over it, and someone else stuck a message in the stream of data Perl expected. Someone's very confused, or perhaps trying to subvert Perl's population of %ENV for nefarious purposes.

Unrecognized escape \\%c passed through

(W misc) You used a backslash-character combination which is not recognized by Perl. The character was understood literally.

Unterminated attribute parameter in attribute list

(F) The lexer saw an opening (left) parenthesis character while parsing an attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance. See the attributes manpage.

Unterminated attribute list

(F) The lexer found something other than a simple identifier at the start of an attribute, and it wasn't a semicolon or the start of a block. Perhaps you terminated the parameter list of the previous attribute too soon. See the attributes manpage.

Unterminated attribute parameter in subroutine attribute list

(F) The lexer saw an opening (left) parenthesis character while parsing a subroutine attribute list, but the matching closing (right) parenthesis character was not found. You may need to add (or remove) a backslash character to get your parentheses to balance.

Unterminated subroutine attribute list

(F) The lexer found something other than a simple identifier at the start of a subroutine attribute, and it wasn't a semicolon or the start of a block. Perhaps you terminated the parameter list of the previous attribute too soon.

Value of CLI symbol "%s" too long

(W misc) A warning peculiar to VMS. Perl tried to read the value of an %ENV element from a CLI symbol table, and found a resultant string longer than 1024 characters. The return value has been truncated to 1024 characters.

Version number must be a constant number

(P) The attempt to translate a use Module n.n LIST statement into its equivalent BEGIN block found an internal inconsistency with the version number.

New tests

lib/attrs

Compatibility tests for sub : attrs vs the older use attrs.

lib/env

Tests for new environment scalar capability (e.g., use Env qw($BAR);).

lib/env-array

Tests for new environment array capability (e.g., use Env qw(@PATH);).

lib/io_const

IO constants (SEEK_*, _IO*).

lib/io_dir

Directory-related IO methods (new, read, close, rewind, tied delete).

lib/io_multihomed

INET sockets with multi-homed hosts.

lib/io_poll

IO poll().

lib/io_unix

UNIX sockets.

op/attrs

Regression tests for my ($x,@y,%z) : attrs and <sub : attrs>.

op/filetest

File test operators.

op/lex_assign

Verify operations that access pad objects (lexicals and temporaries).

op/exists_sub

Verify exists &sub operations.

Incompatible Changes

Perl Source Incompatibilities

Beware that any new warnings that have been added or old ones that have been enhanced are not considered incompatible changes.

Since all new warnings must be explicitly requested via the -w switch or the warnings pragma, it is ultimately the programmer's responsibility to ensure that warnings are enabled judiciously.

CHECK is a new keyword

All subroutine definitions named CHECK are now special. See /"Support for CHECK blocks" for more information.

Treatment of list slices of undef has changed

There is a potential incompatibility in the behavior of list slices that are comprised entirely of undefined values. See Behavior of list slices is more consistent.

Format of $English::PERL_VERSION is different

The English module now sets $PERL_VERSION to $^V (a string value) rather than $] (a numeric value). This is a potential incompatibility. Send us a report via perlbug if you are affected by this.

See Improved Perl version numbering system for the reasons for this change.

Literals of the form 1.2.3 parse differently

Previously, numeric literals with more than one dot in them were interpreted as a floating point number concatenated with one or more numbers. Such "numbers" are now parsed as strings composed of the specified ordinals.

For example, print 97.98.99 used to output 97.9899 in earlier versions, but now prints abc.

See Support for strings represented as a vector of ordinals.

Possibly changed pseudo-random number generator

Perl programs that depend on reproducing a specific set of pseudo-random numbers may now produce different output due to improvements made to the rand() builtin. You can use sh Configure -Drandfunc=rand to obtain the old behavior.

See Better pseudo-random number generator.

Hashing function for hash keys has changed

Even though Perl hashes are not order preserving, the apparently random order encountered when iterating on the contents of a hash is actually determined by the hashing algorithm used. Improvements in the algorithm may yield a random order that is different from that of previous versions, especially when iterating on hashes.

See Better worst-case behavior of hashes for additional information.

undef fails on read only values

Using the undef operator on a readonly value (such as $1) has the same effect as assigning undef to the readonly value--it throws an exception.

Close-on-exec bit may be set on pipe and socket handles

Pipe and socket handles are also now subject to the close-on-exec behavior determined by the special variable $^F.

See More consistent close-on-exec behavior.

Writing "$$1" to mean "${$}1" is unsupported

Perl 5.004 deprecated the interpretation of $$1 and similar within interpolated strings to mean $$ . "1", but still allowed it.

In Perl 5.6.0 and later, "$$1" always means "${$1}".

delete(), each(), values() and \(%h)

operate on aliases to values, not copies

delete(), each(), values() and hashes (e.g. \(%h)) in a list context return the actual values in the hash, instead of copies (as they used to in earlier versions). Typical idioms for using these constructs copy the returned values, but this can make a significant difference when creating references to the returned values. Keys in the hash are still returned as copies when iterating on a hash.

See also delete(), each(), values() and hash iteration are faster.

vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS

vec() generates a run-time error if the BITS argument is not a valid power-of-two integer.

Text of some diagnostic output has changed

Most references to internal Perl operations in diagnostics have been changed to be more descriptive. This may be an issue for programs that may incorrectly rely on the exact text of diagnostics for proper functioning.

%@ has been removed

The undocumented special variable %@ that used to accumulate "background" errors (such as those that happen in DESTROY()) has been removed, because it could potentially result in memory leaks.

Parenthesized not() behaves like a list operator

The not operator now falls under the "if it looks like a function, it behaves like a function" rule.

As a result, the parenthesized form can be used with grep and map. The following construct used to be a syntax error before, but it works as expected now:

    grep not($_), @things;

On the other hand, using not with a literal list slice may not work. The following previously allowed construct:

    print not (1,2,3)[0];

needs to be written with additional parentheses now:

    print not((1,2,3)[0]);

The behavior remains unaffected when not is not followed by parentheses.

Semantics of bareword prototype (*) have changed

The semantics of the bareword prototype * have changed. Perl 5.005 always coerced simple scalar arguments to a typeglob, which wasn't useful in situations where the subroutine must distinguish between a simple scalar and a typeglob. The new behavior is to not coerce bareword arguments to a typeglob. The value will always be visible as either a simple scalar or as a reference to a typeglob.

See More functional bareword prototype (*).

Semantics of bit operators may have changed on 64-bit platforms

If your platform is either natively 64-bit or if Perl has been configured to used 64-bit integers, i.e., $Config{ivsize} is 8, there may be a potential incompatibility in the behavior of bitwise numeric operators (& | ^ ~ << >>). These operators used to strictly operate on the lower 32 bits of integers in previous versions, but now operate over the entire native integral width. In particular, note that unary ~ will produce different results on platforms that have different $Config{ivsize}. For portability, be sure to mask off the excess bits in the result of unary ~, e.g., ~$x & 0xffffffff.

See Bit operators support full native integer width.

More builtins taint their results

As described in Improved security features, there may be more sources of taint in a Perl program.

To avoid these new tainting behaviors, you can build Perl with the Configure option -Accflags=-DINCOMPLETE_TAINTS. Beware that the ensuing perl binary may be insecure.

C Source Incompatibilities

PERL_POLLUTE

Release 5.005 grandfathered old global symbol names by providing preprocessor macros for extension source compatibility. As of release 5.6.0, these preprocessor definitions are not available by default. You need to explicitly compile perl with -DPERL_POLLUTE to get these definitions. For extensions still using the old symbols, this option can be specified via MakeMaker:

    perl Makefile.PL POLLUTE=1
PERL_IMPLICIT_CONTEXT

This new build option provides a set of macros for all API functions such that an implicit interpreter/thread context argument is passed to every API function. As a result of this, something like sv_setsv(foo,bar) amounts to a macro invocation that actually translates to something like Perl_sv_setsv(my_perl,foo,bar). While this is generally expected to not have any significant source compatibility issues, the difference between a macro and a real function call will need to be considered.

This means that there is a source compatibility issue as a result of this if your extensions attempt to use pointers to any of the Perl API functions.

Note that the above issue is not relevant to the default build of Perl, whose interfaces continue to match those of prior versions (but subject to the other options described here).

See The Perl API in the perlguts manpage for detailed information on the ramifications of building Perl with this option.

    NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
    with one of -Dusethreads, -Dusemultiplicity, or both.  It is not
    intended to be enabled by users at this time.
PERL_POLLUTE_MALLOC

Enabling Perl's malloc in release 5.005 and earlier caused the namespace of the system's malloc family of functions to be usurped by the Perl versions, since by default they used the same names. Besides causing problems on platforms that do not allow these functions to be cleanly replaced, this also meant that the system versions could not be called in programs that used Perl's malloc. Previous versions of Perl have allowed this behaviour to be suppressed with the HIDEMYMALLOC and EMBEDMYMALLOC preprocessor definitions.

As of release 5.6.0, Perl's malloc family of functions have default names distinct from the system versions. You need to explicitly compile perl with -DPERL_POLLUTE_MALLOC to get the older behaviour. HIDEMYMALLOC and EMBEDMYMALLOC have no effect, since the behaviour they enabled is now the default.

Note that these functions do not constitute Perl's memory allocation API. See Memory Allocation in the perlguts manpage for further information about that.

Compatible C Source API Changes

PATCHLEVEL is now PERL_VERSION

The cpp macros PERL_REVISION, PERL_VERSION, and PERL_SUBVERSION are now available by default from perl.h, and reflect the base revision, patchlevel, and subversion respectively. PERL_REVISION had no prior equivalent, while PERL_VERSION and PERL_SUBVERSION were previously available as PATCHLEVEL and SUBVERSION.

The new names cause less pollution of the cpp namespace and reflect what the numbers have come to stand for in common practice. For compatibility, the old names are still supported when patchlevel.h is explicitly included (as required before), so there is no source incompatibility from the change.

Binary Incompatibilities

In general, the default build of this release is expected to be binary compatible for extensions built with the 5.005 release or its maintenance versions. However, specific platforms may have broken binary compatibility due to changes in the defaults used in hints files. Therefore, please be sure to always check the platform-specific README files for any notes to the contrary.

The usethreads or usemultiplicity builds are not binary compatible with the corresponding builds in 5.005.

On platforms that require an explicit list of exports (AIX, OS/2 and Windows, among others), purely internal symbols such as parser functions and the run time opcodes are not exported by default. Perl 5.005 used to export all functions irrespective of whether they were considered part of the public API or not.

For the full list of public API functions, see the perlapi manpage.

Known Problems

Thread test failures

The subtests 19 and 20 of lib/thr5005.t test are known to fail due to fundamental problems in the 5.005 threading implementation. These are not new failures--Perl 5.005_0x has the same bugs, but didn't have these tests.

EBCDIC platforms not supported

In earlier releases of Perl, EBCDIC environments like OS390 (also known as Open Edition MVS) and VM-ESA were supported. Due to changes required by the UTF-8 (Unicode) support, the EBCDIC platforms are not supported in Perl 5.6.0.

In 64-bit HP-UX the lib/io_multihomed test may hang

The lib/io_multihomed test may hang in HP-UX if Perl has been configured to be 64-bit. Because other 64-bit platforms do not hang in this test, HP-UX is suspect. All other tests pass in 64-bit HP-UX. The test attempts to create and connect to "multihomed" sockets (sockets which have multiple IP addresses).

NEXTSTEP 3.3 POSIX test failure

In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the operating system libraries is buggy: the %j format numbers the days of a month starting from zero, which, while being logical to programmers, will cause the subtests 19 to 27 of the lib/posix test may fail.

Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc

If compiled with gcc 2.95 the lib/sdbm test will fail (dump core). The cure is to use the vendor cc, it comes with the operating system and produces good code.

UNICOS/mk CC failures during Configure run

In UNICOS/mk the following errors may appear during the Configure run:

        Guessing which symbols your C compiler and preprocessor define...
        CC-20 cc: ERROR File = try.c, Line = 3
        ...
          bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
        ...
        4 errors detected in the compilation of "try.c".

The culprit is the broken awk of UNICOS/mk. The effect is fortunately rather mild: Perl itself is not adversely affected by the error, only the h2ph utility coming with Perl, and that is rather rarely needed these days.

Arrow operator and arrays

When the left argument to the arrow operator -> is an array, or the scalar operator operating on an array, the result of the operation must be considered erroneous. For example:

    @x->[2]
    scalar(@x)->[2]

These expressions will get run-time errors in some future release of Perl.

Experimental features

As discussed above, many features are still experimental. Interfaces and implementation of these features are subject to change, and in extreme cases, even subject to removal in some future release of Perl. These features include the following:

Threads
Unicode
  • -bit support
    Lvalue subroutines
    Weak references
    The pseudo-hash data type
    The Compiler suite
    Internal implementation of file globbing
    The DB module
    The regular expression code constructs:

    (?{ code }) and (??{ code })

    • Obsolete Diagnostics

    Character class syntax [: :] is reserved for future extensions

    (W) Within regular expression character classes ([]) the syntax beginning with "[:" and ending with ":]" is reserved for future extensions. If you need to represent those character sequences inside a regular expression character class, just quote the square brackets with the backslash: "\[:" and ":\]".

    Ill-formed logical name |%s| in prime_env_iter

    (W) A warning peculiar to VMS. A logical name was encountered when preparing to iterate over %ENV which violates the syntactic rules governing logical names. Because it cannot be translated normally, it is skipped, and will not appear in %ENV. This may be a benign occurrence, as some software packages might directly modify logical name tables and introduce nonstandard names, or it may indicate that a logical name table has been corrupted.

    In string, @%s now must be written as \@%s

    The description of this error used to say:

            (Someday it will simply assume that an unbackslashed @
         interpolates an array.)

    That day has come, and this fatal error has been removed. It has been replaced by a non-fatal warning instead. See Arrays now always interpolate into double-quoted strings for details.

    Probable precedence problem on %s

    (W) The compiler found a bareword where it expected a conditional, which often indicates that an || or && was parsed as part of the last argument of the previous construct, for example:

        open FOO || die;
    regexp too big

    (F) The current implementation of regular expressions uses shorts as address offsets within a string. Unfortunately this means that if the regular expression compiles to longer than 32767, it'll blow up. Usually when you want a regular expression this big, there is a better way to do it with multiple statements. See the perlre manpage.

    Use of "$$<digit>" to mean "${$}<digit>" is deprecated

    (D) Perl versions before 5.004 misinterpreted any type marker followed by "$" and a digit. For example, "$$0" was incorrectly taken to mean "${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004.

    However, the developers of Perl 5.004 could not fix this bug completely, because at least two widely-used modules depend on the old meaning of "$$0" in a string. So Perl 5.004 still interprets "$$<digit>" in the old (broken) way inside strings; but it generates this message as a warning. And in Perl 5.005, this special treatment will cease.

    Reporting Bugs

    If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup. There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

    If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

    SEE ALSO

    The Changes file for exhaustive details on what changed.

    The INSTALL file for how to build Perl.

    The README file for general stuff.

    The Artistic and Copying files for copyright information.

    HISTORY

    Written by Gurusamy Sarathy <gsar@activestate.com>, with many contributions from The Perl Porters.

    Send omissions or corrections to <perlbug@perl.org>.


perl570delta - what's new for perl v5.7.0

  • Security Vulnerability Closed
  • Incompatible Changes
  • Core Enhancements
  • Modules and Pragmata
    • New Modules
    • Updated And Improved Modules and Pragmata
  • Utility Changes
  • New Documentation
  • Performance Enhancements
  • Installation and Configuration Improvements
    • Generic Improvements
  • Selected Bug Fixes
    • Platform Specific Changes and Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Known Problems
    • Unicode Support Still Far From Perfect
    • EBCDIC Still A Lost Platform
    • Building Extensions Can Fail Because Of Largefiles
    • ftmp-security tests warn 'system possibly insecure'
    • Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
    • Long Doubles Still Don't Work In Solaris
    • Linux With Sfio Fails op/misc Test 48
    • Storable tests fail in some platforms
    • Threads Are Still Experimental
    • The Compiler Suite Is Still Experimental
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl570delta - what's new for perl v5.7.0

DESCRIPTION

This document describes differences between the 5.6.0 release and the 5.7.0 release.

Security Vulnerability Closed

A potential security vulnerability in the optional suidperl component of Perl has been identified. suidperl is neither built nor installed by default. As of September the 2nd, 2000, the only known vulnerable platform is Linux, most likely all Linux distributions. CERT and various vendors have been alerted about the vulnerability.

The problem was caused by Perl trying to report a suspected security exploit attempt using an external program, /bin/mail. On Linux platforms the /bin/mail program had an undocumented feature which when combined with suidperl gave access to a root shell, resulting in a serious compromise instead of reporting the exploit attempt. If you don't have /bin/mail, or if you have 'safe setuid scripts', or if suidperl is not installed, you are safe.

The exploit attempt reporting feature has been completely removed from the Perl 5.7.0 release, so that particular vulnerability isn't there anymore. However, further security vulnerabilities are, unfortunately, always possible. The suidperl code is being reviewed and if deemed too risky to continue to be supported, it may be completely removed from future releases. In any case, suidperl should only be used by security experts who know exactly what they are doing and why they are using suidperl instead of some other solution such as sudo ( see http://www.courtesan.com/sudo/ ).

Incompatible Changes

  • Arrays now always interpolate into double-quoted strings: constructs like "foo@bar" now always assume @bar is an array, whether or not the compiler has seen use of @bar.

  • The semantics of bless(REF, REF) were unclear and until someone proves it to make some sense, it is forbidden.

  • A reference to a reference now stringify as "REF(0x81485ec)" instead of "SCALAR(0x81485ec)" in order to be more consistent with the return value of ref().

  • The very dusty examples in the eg/ directory have been removed. Suggestions for new shiny examples welcome but the main issue is that the examples need to be documented, tested and (most importantly) maintained.

  • The obsolete chat2 library that should never have been allowed to escape the laboratory has been decommissioned.

  • The unimplemented POSIX regex features [[.cc.]] and [[=c=]] are still recognised but now cause fatal errors. The previous behaviour of ignoring them by default and warning if requested was unacceptable since it, in a way, falsely promised that the features could be used.

  • The (bogus) escape sequences \8 and \9 now give an optional warning ("Unrecognized escape passed through"). There is no need to \-escape any \w character.

  • lstat(FILEHANDLE) now gives a warning because the operation makes no sense. In future releases this may become a fatal error.

  • The long deprecated uppercase aliases for the string comparison operators (EQ, NE, LT, LE, GE, GT) have now been removed.

  • The regular expression captured submatches ($1, $2, ...) are now more consistently unset if the match fails, instead of leaving false data lying around in them.

  • The tr///C and tr///U features have been removed and will not return; the interface was a mistake. Sorry about that. For similar functionality, see pack('U0', ...) and pack('C0', ...).

Core Enhancements

  • perl -d:Module=arg,arg,arg now works (previously one couldn't pass in multiple arguments.)

  • my __PACKAGE__ $obj now works.

  • no Module; now works even if there is no "sub unimport" in the Module.

  • The numerical comparison operators return undef if either operand is a NaN. Previously the behaviour was unspecified.

  • pack('U0a*', ...) can now be used to force a string to UTF-8.

  • prototype(\&) is now available.

  • There is now an UNTIE method.

Modules and Pragmata

New Modules

  • File::Temp allows one to create temporary files and directories in an easy, portable, and secure way.

  • Storable gives persistence to Perl data structures by allowing the storage and retrieval of Perl data to and from files in a fast and compact binary format.

Updated And Improved Modules and Pragmata

  • The following independently supported modules have been updated to newer versions from CPAN: CGI, CPAN, DB_File, File::Spec, Getopt::Long, the podlators bundle, Pod::LaTeX, Pod::Parser, Term::ANSIColor, Test.

  • Bug fixes and minor enhancements have been applied to B::Deparse, Data::Dumper, IO::Poll, IO::Socket::INET, Math::BigFloat, Math::Complex, Math::Trig, Net::protoent, the re pragma, SelfLoader, Sys::SysLog, Test::Harness, Text::Wrap, UNIVERSAL, and the warnings pragma.

  • The attributes::reftype() now works on tied arguments.

  • AutoLoader can now be disabled with no AutoLoader;,

  • The English module can now be used without the infamous performance hit by saying

            use English '-no_performance_hit';

    (Assuming, of course, that one doesn't need the troublesome variables $`, $&, or $'.) Also, introduced @LAST_MATCH_START and @LAST_MATCH_END English aliases for @- and @+.

  • File::Find now has pre- and post-processing callbacks. It also correctly changes directories when chasing symbolic links. Callbacks (naughtily) exiting with "next;" instead of "return;" now work.

  • File::Glob::glob() renamed to File::Glob::bsd_glob() to avoid prototype mismatch with CORE::glob().

  • IPC::Open3 now allows the use of numeric file descriptors.

  • use lib now works identically to @INC. Removing directories with 'no lib' now works.

  • %INC now localised in a Safe compartment so that use/require work.

  • The Shell module now has an OO interface.

Utility Changes

  • The Emacs perl mode (emacs/cperl-mode.el) has been updated to version 4.31.

  • Perlbug is now much more robust. It also sends the bug report to perl.org, not perl.com.

  • The perlcc utility has been rewritten and its user interface (that is, command line) is much more like that of the UNIX C compiler, cc.

  • The xsubpp utility for extension writers now understands POD documentation embedded in the *.xs files.

New Documentation

  • perl56delta details the changes between the 5.005 release and the 5.6.0 release.

  • perldebtut is a Perl debugging tutorial.

  • perlebcdic contains considerations for running Perl on EBCDIC platforms. Note that unfortunately EBCDIC platforms that used to supported back in Perl 5.005 are still unsupported by Perl 5.7.0; the plan, however, is to bring them back to the fold.

  • perlnewmod tells about writing and submitting a new module.

  • perlposix-bc explains using Perl on the POSIX-BC platform (an EBCDIC mainframe platform).

  • perlretut is a regular expression tutorial.

  • perlrequick is a regular expressions quick-start guide. Yes, much quicker than perlretut.

  • perlutil explains the command line utilities packaged with the Perl distribution.

Performance Enhancements

  • map() that changes the size of the list should now work faster.

  • sort() has been changed to use mergesort internally as opposed to the earlier quicksort. For very small lists this may result in slightly slower sorting times, but in general the speedup should be at least 20%. Additional bonuses are that the worst case behaviour of sort() is now better (in computer science terms it now runs in time O(N log N), as opposed to quicksort's Theta(N**2) worst-case run time behaviour), and that sort() is now stable (meaning that elements with identical keys will stay ordered as they were before the sort).

Installation and Configuration Improvements

Generic Improvements

  • INSTALL now explains how you can configure Perl to use 64-bit integers even on non-64-bit platforms.

  • Policy.sh policy change: if you are reusing a Policy.sh file (see INSTALL) and you use Configure -Dprefix=/foo/bar and in the old Policy $prefix eq $siteprefix and $prefix eq $vendorprefix, all of them will now be changed to the new prefix, /foo/bar. (Previously only $prefix changed.) If you do not like this new behaviour, specify prefix, siteprefix, and vendorprefix explicitly.

  • A new optional location for Perl libraries, otherlibdirs, is available. It can be used for example for vendor add-ons without disturbing Perl's own library directories.

  • In many platforms the vendor-supplied 'cc' is too stripped-down to build Perl (basically, 'cc' doesn't do ANSI C). If this seems to be the case and 'cc' does not seem to be the GNU C compiler 'gcc', an automatic attempt is made to find and use 'gcc' instead.

  • gcc needs to closely track the operating system release to avoid build problems. If Configure finds that gcc was built for a different operating system release than is running, it now gives a clearly visible warning that there may be trouble ahead.

  • If binary compatibility with the 5.005 release is not wanted, Configure no longer suggests including the 5.005 modules in @INC.

  • Configure -S can now run non-interactively.

  • configure.gnu now works with options with whitespace in them.

  • installperl now outputs everything to STDERR.

  • $Config{byteorder} is now computed dynamically (this is more robust with "fat binaries" where an executable image contains binaries for more than one binary platform.)

Selected Bug Fixes

  • Several debugger fixes: exit code now reflects the script exit code, condition "0" now treated correctly, the d command now checks line number, the $. no longer gets corrupted, all debugger output now goes correctly to the socket if RemotePort is set.

  • *foo{FORMAT} now works.

  • Lexical warnings now propagating correctly between scopes.

  • Line renumbering with eval and #line now works.

  • Fixed numerous memory leaks, especially in eval "".

  • Modulus of unsigned numbers now works (4063328477 % 65535 used to return 27406, instead of 27047).

  • Some "not a number" warnings introduced in 5.6.0 eliminated to be more compatible with 5.005. Infinity is now recognised as a number.

  • our() variables will not cause "will not stay shared" warnings.

  • pack "Z" now correctly terminates the string with "\0".

  • Fix password routines which in some shadow password platforms (e.g. HP-UX) caused getpwent() to return every other entry.

  • printf() no longer resets the numeric locale to "C".

  • q(a\\b) now parses correctly as 'a\\b'.

  • Printing quads (64-bit integers) with printf/sprintf now works without the q L ll prefixes (assuming you are on a quad-capable platform).

  • Regular expressions on references and overloaded scalars now work.

  • scalar() now forces scalar context even when used in void context.

  • sort() arguments are now compiled in the right wantarray context (they were accidentally using the context of the sort() itself).

  • Changed the POSIX character class [[:space:]] to include the (very rare) vertical tab character. Added a new POSIX-ish character class [[:blank:]] which stands for horizontal whitespace (currently, the space and the tab).

  • $AUTOLOAD, sort(), lock(), and spawning subprocesses in multiple threads simultaneously are now thread-safe.

  • Allow read-only string on left hand side of non-modifying tr///.

  • Several Unicode fixes (but still not perfect).

    • BOMs (byte order marks) in the beginning of Perl files (scripts, modules) should now be transparently skipped. UTF-16 (UCS-2) encoded Perl files should now be read correctly.

    • The character tables have been updated to Unicode 3.0.1.

    • chr() for values greater than 127 now create utf8 when under use utf8.

    • Comparing with utf8 data does not magically upgrade non-utf8 data into utf8.

    • IsAlnum, IsAlpha, and IsWord now match titlecase.

    • Concatenation with the . operator or via variable interpolation, eq, substr, reverse, quotemeta, the x operator, substitution with s///, single-quoted UTF-8, should now work--in theory.

    • The tr/// operator now works slightly better but is still rather broken. Note that the tr///CU functionality has been removed (but see pack('U0', ...)).

    • vec() now refuses to deal with characters >255.

    • Zero entries were missing from the Unicode classes like IsDigit.

  • UNIVERSAL::isa no longer caches methods incorrectly. (This broke the Tk extension with 5.6.0.)

Platform Specific Changes and Fixes

  • BSDI 4.*

    Perl now works on post-4.0 BSD/OSes.

  • All BSDs

    Setting $0 now works (as much as possible; see perlvar for details).

  • Cygwin

    Numerous updates; currently synchronised with Cygwin 1.1.4.

  • EPOC

    EPOC update after Perl 5.6.0. See README.epoc.

  • FreeBSD 3.*

    Perl now works on post-3.0 FreeBSDs.

  • HP-UX

    README.hpux updated; Configure -Duse64bitall now almost works.

  • IRIX

    Numerous compilation flag and hint enhancements; accidental mixing of 32-bit and 64-bit libraries (a doomed attempt) made much harder.

  • Linux

    Long doubles should now work (see INSTALL).

  • Mac OS Classic

    Compilation of the standard Perl distribution in Mac OS Classic should now work if you have the Metrowerks development environment and the missing Mac-specific toolkit bits. Contact the macperl mailing list for details.

  • MPE/iX

    MPE/iX update after Perl 5.6.0. See README.mpeix.

  • NetBSD/sparc

    Perl now works on NetBSD/sparc.

  • OS/2

    Now works with usethreads (see INSTALL).

  • Solaris

    64-bitness using the Sun Workshop compiler now works.

  • Tru64 (aka Digital UNIX, aka DEC OSF/1)

    The operating system version letter now recorded in $Config{osvers}. Allow compiling with gcc (previously explicitly forbidden). Compiling with gcc still not recommended because buggy code results, even with gcc 2.95.2.

  • Unicos

    Fixed various alignment problems that lead into core dumps either during build or later; no longer dies on math errors at runtime; now using full quad integers (64 bits), previously was using only 46 bit integers for speed.

  • VMS

    chdir() now works better despite a CRT bug; now works with MULTIPLICITY (see INSTALL); now works with Perl's malloc.

  • Windows

    • accept() no longer leaks memory.

    • Better chdir() return value for a non-existent directory.

    • New %ENV entries now propagate to subprocesses.

    • $ENV{LIB} now used to search for libs under Visual C.

    • A failed (pseudo)fork now returns undef and sets errno to EAGAIN.

    • Allow REG_EXPAND_SZ keys in the registry.

    • Can now send() from all threads, not just the first one.

    • Fake signal handling reenabled, bugs and all.

    • Less stack reserved per thread so that more threads can run concurrently. (Still 16M per thread.)

    • File::Spec->tmpdir() now prefers C:/temp over /tmp (works better when perl is running as service).

    • Better UNC path handling under ithreads.

    • wait() and waitpid() now work much better.

    • winsock handle leak fixed.

New or Changed Diagnostics

All regular expression compilation error messages are now hopefully easier to understand both because the error message now comes before the failed regex and because the point of failure is now clearly marked.

The various "opened only for", "on closed", "never opened" warnings drop the main:: prefix for filehandles in the main package, for example STDIN instead of <main::STDIN>.

The "Unrecognized escape" warning has been extended to include \8, \9, and \_. There is no need to escape any of the \w characters.

Changed Internals

  • perlapi.pod (a companion to perlguts) now attempts to document the internal API.

  • You can now build a really minimal perl called microperl. Building microperl does not require even running Configure; make -f Makefile.micro should be enough. Beware: microperl makes many assumptions, some of which may be too bold; the resulting executable may crash or otherwise misbehave in wondrous ways. For careful hackers only.

  • Added rsignal(), whichsig(), do_join() to the publicised API.

  • Made possible to propagate customised exceptions via croak()ing.

  • Added is_utf8_char(), is_utf8_string(), bytes_to_utf8(), and utf8_to_bytes().

  • Now xsubs can have attributes just like subs.

Known Problems

Unicode Support Still Far From Perfect

We're working on it. Stay tuned.

EBCDIC Still A Lost Platform

The plan is to bring them back.

Building Extensions Can Fail Because Of Largefiles

Certain extensions like mod_perl and BSD::Resource are known to have issues with `largefiles', a change brought by Perl 5.6.0 in which file offsets default to 64 bits wide, where supported. Modules may fail to compile at all or compile and work incorrectly. Currently there is no good solution for the problem, but Configure now provides appropriate non-largefile ccflags, ldflags, libswanted, and libs in the %Config hash (e.g., $Config{ccflags_nolargefiles}) so the extensions that are having problems can try configuring themselves without the largefileness. This is admittedly not a clean solution, and the solution may not even work at all. One potential failure is whether one can (or, if one can, whether it's a good idea) link together at all binaries with different ideas about file offsets, all this is platform-dependent.

ftmp-security tests warn 'system possibly insecure'

Don't panic. Read INSTALL 'make test' section instead.

Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX

If perl is configured with -Duse64bitall, the successful result of the subtest 10 of lib/posix may arrive before the successful result of the subtest 9, which confuses the test harness so much that it thinks the subtest 9 failed.

Long Doubles Still Don't Work In Solaris

The experimental long double support is still very much so in Solaris. (Other platforms like Linux and Tru64 are beginning to solidify in this area.)

Linux With Sfio Fails op/misc Test 48

No known fix.

Storable tests fail in some platforms

If any Storable tests fail the use of Storable is not advisable.

  • Many Storable tests fail on AIX configured with 64 bit integers.

    So far unidentified problems break Storable in AIX if Perl is configured to use 64 bit integers. AIX in 32-bit mode works and other 64-bit platforms work with Storable.

  • DOS DJGPP may hang when testing Storable.

  • st-06compat fails in UNICOS and UNICOS/mk.

    This means that you cannot read old (pre-Storable-0.7) Storable images made in other platforms.

  • st-store.t and st-retrieve may fail with Compaq C 6.2 on OpenVMS Alpha 7.2.

Threads Are Still Experimental

Multithreading is still an experimental feature. Some platforms emit the following message for lib/thr5005

    #
    # This is a KNOWN FAILURE, and one of the reasons why threading
    # is still an experimental feature.  It is here to stop people
    # from deploying threads in production. ;-)
    #

and another known thread-related warning is

   pragma/overload......Unbalanced saves: 3 more saves than restores
   panic: magic_mutexfree during global destruction.
   ok
   lib/selfloader.......Unbalanced saves: 3 more saves than restores
   panic: magic_mutexfree during global destruction.
   ok
   lib/st-dclone........Unbalanced saves: 3 more saves than restores
   panic: magic_mutexfree during global destruction.
   ok

The Compiler Suite Is Still Experimental

The compiler suite is slowly getting better but is nowhere near working order yet. The backend part that has seen perhaps the most progress is the bytecode compiler.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/ There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Jarkko Hietaniemi <jhi@iki.fi>, with many contributions from The Perl Porters and Perl Users submitting feedback and patches.

Send omissions or corrections to <perlbug@perl.org>.


perl571delta - what's new for perl v5.7.1

  • Security Vulnerability Closed
  • Incompatible Changes
  • Core Enhancements
    • AUTOLOAD Is Now Lvaluable
    • PerlIO is Now The Default
    • Signals Are Now Safe
  • Modules and Pragmata
    • New Modules
    • Updated And Improved Modules and Pragmata
  • Performance Enhancements
  • Utility Changes
  • New Documentation
    • perlclib
    • perliol
    • README.aix
    • README.bs2000
    • README.macos
    • README.mpeix
    • README.solaris
    • README.vos
    • Porting/repository.pod
  • Installation and Configuration Improvements
    • New Or Improved Platforms
    • Generic Improvements
  • Selected Bug Fixes
    • Platform Specific Changes and Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • New Tests
  • Known Problems
    • AIX vac 5.0.0.0 May Produce Buggy Code For Perl
    • lib/ftmp-security tests warn 'system possibly insecure'
    • lib/io_multihomed Fails In LP64-Configured HP-UX
    • Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
    • lib/b test 19
    • Linux With Sfio Fails op/misc Test 48
    • sigaction test 13 in VMS
    • sprintf tests 129 and 130
    • Failure of Thread tests
    • Localising a Tied Variable Leaks Memory
    • Self-tying of Arrays and Hashes Is Forbidden
    • Building Extensions Can Fail Because Of Largefiles
    • The Compiler Suite Is Still Experimental
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl571delta - what's new for perl v5.7.1

DESCRIPTION

This document describes differences between the 5.7.0 release and the 5.7.1 release.

(To view the differences between the 5.6.0 release and the 5.7.0 release, see the perl570delta manpage.)

Security Vulnerability Closed

(This change was already made in 5.7.0 but bears repeating here.)

A potential security vulnerability in the optional suidperl component of Perl was identified in August 2000. suidperl is neither built nor installed by default. As of April 2001 the only known vulnerable platform is Linux, most likely all Linux distributions. CERT and various vendors and distributors have been alerted about the vulnerability. See http://www.cpan.org/src/5.0/sperl-2000-08-05/sperl-2000-08-05.txt for more information.

The problem was caused by Perl trying to report a suspected security exploit attempt using an external program, /bin/mail. On Linux platforms the /bin/mail program had an undocumented feature which when combined with suidperl gave access to a root shell, resulting in a serious compromise instead of reporting the exploit attempt. If you don't have /bin/mail, or if you have 'safe setuid scripts', or if suidperl is not installed, you are safe.

The exploit attempt reporting feature has been completely removed from all the Perl 5.7 releases (and will be gone also from the maintenance release 5.6.1), so that particular vulnerability isn't there anymore. However, further security vulnerabilities are, unfortunately, always possible. The suidperl code is being reviewed and if deemed too risky to continue to be supported, it may be completely removed from future releases. In any case, suidperl should only be used by security experts who know exactly what they are doing and why they are using suidperl instead of some other solution such as sudo ( see http://www.courtesan.com/sudo/ ).

Incompatible Changes

  • Although "you shouldn't do that", it was possible to write code that depends on Perl's hashed key order (Data::Dumper does this). The new algorithm "One-at-a-Time" produces a different hashed key order. More details are in Performance Enhancements.

  • The list of filenames from glob() (or <...>) is now by default sorted alphabetically to be csh-compliant. (bsd_glob() does still sort platform natively, ASCII or EBCDIC, unless GLOB_ALPHASORT is specified.)

Core Enhancements

AUTOLOAD Is Now Lvaluable

AUTOLOAD is now lvaluable, meaning that you can add the :lvalue attribute to AUTOLOAD subroutines and you can assign to the AUTOLOAD return value.

PerlIO is Now The Default

  • IO is now by default done via PerlIO rather than system's "stdio". PerlIO allows "layers" to be "pushed" onto a file handle to alter the handle's behaviour. Layers can be specified at open time via 3-arg form of open:

       open($fh,'>:crlf :utf8', $path) || ...

    or on already opened handles via extended binmode:

       binmode($fh,':encoding(iso-8859-7)');

    The built-in layers are: unix (low level read/write), stdio (as in previous Perls), perlio (re-implementation of stdio buffering in a portable manner), crlf (does CRLF <=> "\n" translation as on Win32, but available on any platform). A mmap layer may be available if platform supports it (mostly UNIXes).

    Layers to be applied by default may be specified via the 'open' pragma.

    See Installation and Configuration Improvements for the effects of PerlIO on your architecture name.

  • File handles can be marked as accepting Perl's internal encoding of Unicode (UTF-8 or UTF-EBCDIC depending on platform) by a pseudo layer ":utf8" :

       open($fh,">:utf8","Uni.txt");

    Note for EBCDIC users: the pseudo layer ":utf8" is erroneously named for you since it's not UTF-8 what you will be getting but instead UTF-EBCDIC. See the perlunicode manpage, the utf8 manpage, and http://www.unicode.org/unicode/reports/tr16/ for more information. In future releases this naming may change.

  • File handles can translate character encodings from/to Perl's internal Unicode form on read/write via the ":encoding()" layer.

  • File handles can be opened to "in memory" files held in Perl scalars via:

       open($fh,'>', \$variable) || ...

  • Anonymous temporary files are available without need to 'use FileHandle' or other module via

       open($fh,"+>", undef) || ...

    That is a literal undef, not an undefined value.

  • The list form of open is now implemented for pipes (at least on UNIX):

       open($fh,"-|", 'cat', '/etc/motd')

    creates a pipe, and runs the equivalent of exec('cat', '/etc/motd') in the child process.

  • The following builtin functions are now overridable: chop(), chomp(), each(), keys(), pop(), push(), shift(), splice(), unshift().

  • Formats now support zero-padded decimal fields.

  • Perl now tries internally to use integer values in numeric conversions and basic arithmetics (+ - * /) if the arguments are integers, and tries also to keep the results stored internally as integers. This change leads into often slightly faster and always less lossy arithmetics. (Previously Perl always preferred floating point numbers in its math.)

  • The printf() and sprintf() now support parameter reordering using the %\d+\$ and *\d+\$ syntaxes. For example

        print "%2\$s %1\$s\n", "foo", "bar";

    will print "bar foo\n"; This feature helps in writing internationalised software.

  • Unicode in general should be now much more usable. Unicode can be used in hash keys, Unicode in regular expressions should work now, Unicode in tr/// should work now (though tr/// seems to be a particularly tricky to get right, so you have been warned)

  • The Unicode Character Database coming with Perl has been upgraded to Unicode 3.1. For more information, see http://www.unicode.org/ , and http://www.unicode.org/unicode/reports/tr27/

    For developers interested in enhancing Perl's Unicode capabilities: almost all the UCD files are included with the Perl distribution in the lib/unicode subdirectory. The most notable omission, for space considerations, is the Unihan database.

  • The Unicode character classes \p{Blank} and \p{SpacePerl} have been added. "Blank" is like C isblank(), that is, it contains only "horizontal whitespace" (the space character is, the newline isn't), and the "SpacePerl" is the Unicode equivalent of \s (\p{Space} isn't, since that includes the vertical tabulator character, whereas \s doesn't.)

Signals Are Now Safe

Perl used to be fragile in that signals arriving at inopportune moments could corrupt Perl's internal state.

Modules and Pragmata

New Modules

  • B::Concise, by Stephen McCamant, is a new compiler backend for walking the Perl syntax tree, printing concise info about ops. The output is highly customisable.

    See the B::Concise manpage for more information.

  • Class::ISA, by Sean Burke, for reporting the search path for a class's ISA tree, has been added.

    See the Class::ISA manpage for more information.

  • Cwd has now a split personality: if possible, an extension is used, (this will hopefully be both faster and more secure and robust) but if not possible, the familiar Perl library implementation is used.

  • Digest, a frontend module for calculating digests (checksums), from Gisle Aas, has been added.

    See the Digest manpage for more information.

  • Digest::MD5 for calculating MD5 digests (checksums), by Gisle Aas, has been added.

        use Digest::MD5 'md5_hex';

        $digest = md5_hex("Thirsty Camel");

        print $digest, "\n"; # 01d19d9d2045e005c3f1b80e8b164de1

    NOTE: the MD5 backward compatibility module is deliberately not included since its use is discouraged.

    See the Digest::MD5 manpage for more information.

  • Encode, by Nick Ing-Simmons, provides a mechanism to translate between different character encodings. Support for Unicode, ISO-8859-*, ASCII, CP*, KOI8-R, and three variants of EBCDIC are compiled in to the module. Several other encodings (like Japanese, Chinese, and MacIntosh encodings) are included and will be loaded at runtime.

    Any encoding supported by Encode module is also available to the ":encoding()" layer if PerlIO is used.

    See the Encode manpage for more information.

  • Filter::Simple is an easy-to-use frontend to Filter::Util::Call, from Damian Conway.

        # in MyFilter.pm:

        package MyFilter;

        use Filter::Simple sub {
        while (my ($from, $to) = splice @_, 0, 2) {
                s/$from/$to/g;
        }
    };

        1;

        # in user's code:

        use MyFilter qr/red/ => 'green';

        print "red\n";   # this code is filtered, will print "green\n"
    print "bored\n"; # this code is filtered, will print "bogreen\n"

        no MyFilter;

        print "red\n";   # this code is not filtered, will print "red\n"

    See the Filter::Simple manpage for more information.

  • Filter::Util::Call, by Paul Marquess, provides you with the framework to write Source Filters in Perl. For most uses the frontend Filter::Simple is to be preferred. See the Filter::Util::Call manpage for more information.

  • Locale::Constants, Locale::Country, Locale::Currency, and Locale::Language, from Neil Bowers, have been added. They provide the codes for various locale standards, such as "fr" for France, "usd" for US Dollar, and "jp" for Japanese.

        use Locale::Country;

        $country = code2country('jp');               # $country gets 'Japan'
    $code    = country2code('Norway');           # $code gets 'no'

    See the Locale::Constants manpage, the Locale::Country manpage, the Locale::Currency manpage, and the Locale::Language manpage for more information.

  • MIME::Base64, by Gisle Aas, allows you to encode data in base64.

        use MIME::Base64;

        $encoded = encode_base64('Aladdin:open sesame');
    $decoded = decode_base64($encoded);

        print $encoded, "\n"; # "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

    See the MIME::Base64 manpage for more information.

  • MIME::QuotedPrint, by Gisle Aas, allows you to encode data in quoted-printable encoding.

        use MIME::QuotedPrint;

        $encoded = encode_qp("Smiley in Unicode: \x{263a}");
    $decoded = decode_qp($encoded);

        print $encoded, "\n"; # "Smiley in Unicode: =263A"

    MIME::QuotedPrint has been enhanced to provide the basic methods necessary to use it with PerlIO::Via as in :

        use MIME::QuotedPrint;
    open($fh,">Via(MIME::QuotedPrint)",$path)

    See the MIME::QuotedPrint manpage for more information.

  • PerlIO::Scalar, by Nick Ing-Simmons, provides the implementation of IO to "in memory" Perl scalars as discussed above. It also serves as an example of a loadable layer. Other future possibilities include PerlIO::Array and PerlIO::Code. See the PerlIO::Scalar manpage for more information.

  • PerlIO::Via, by Nick Ing-Simmons, acts as a PerlIO layer and wraps PerlIO layer functionality provided by a class (typically implemented in perl code).

        use MIME::QuotedPrint;
    open($fh,">Via(MIME::QuotedPrint)",$path)

    This will automatically convert everything output to $fh to Quoted-Printable. See the PerlIO::Via manpage for more information.

  • Pod::Text::Overstrike, by Joe Smith, has been added. It converts POD data to formatted overstrike text. See the Pod::Text::Overstrike manpage for more information.

  • Switch from Damian Conway has been added. Just by saying

        use Switch;

    you have switch and case available in Perl.

        use Switch;

        switch ($val) {

                    case 1          { print "number 1" }
                case "a"        { print "string a" }
                case [1..10,42] { print "number in list" }
                case (@array)   { print "number in list" }
                case /\w+/      { print "pattern" }
                case qr/\w+/    { print "pattern" }
                case (%hash)    { print "entry in hash" }
                case (\%hash)   { print "entry in hash" }
                case (\&sub)    { print "arg to subroutine" }
                else            { print "previous case not true" }
                    }

    See the Switch manpage for more information.

  • Text::Balanced from Damian Conway has been added, for extracting delimited text sequences from strings.

        use Text::Balanced 'extract_delimited';

        ($a, $b) = extract_delimited("'never say never', he never said", "'", '');

    $a will be "'never say never'", $b will be ', he never said'.

    In addition to extract_delimited() there are also extract_bracketed(), extract_quotelike(), extract_codeblock(), extract_variable(), extract_tagged(), extract_multiple(), gen_delimited_pat(), and gen_extract_tagged(). With these you can implement rather advanced parsing algorithms. See the Text::Balanced manpage for more information.

  • Tie::RefHash::Nestable, by Edward Avis, allows storing hash references (unlike the standard Tie::RefHash) The module is contained within Tie::RefHash.

  • XS::Typemap, by Tim Jenness, is a test extension that exercises XS typemaps. Nothing gets installed but for extension writers the code is worth studying.

Updated And Improved Modules and Pragmata

  • B::Deparse should be now more robust. It still far from providing a full round trip for any random piece of Perl code, though, and is under active development: expect more robustness in 5.7.2.

  • Class::Struct can now define the classes in compile time.

  • Math::BigFloat has undergone much fixing, and in addition the fmod() function now supports modulus operations.

    ( The fixed Math::BigFloat module is also available in CPAN for those who can't upgrade their Perl: http://www.cpan.org/authors/id/J/JP/JPEACOCK/ )

  • Devel::Peek now has an interface for the Perl memory statistics (this works only if you are using perl's malloc, and if you have compiled with debugging).

  • IO::Socket has now atmark() method, which returns true if the socket is positioned at the out-of-band mark. The method is also exportable as a sockatmark() function.

  • IO::Socket::INET has support for ReusePort option (if your platform supports it). The Reuse option now has an alias, ReuseAddr. For clarity you may want to prefer ReuseAddr.

  • Net::Ping has been enhanced. There is now "external" protocol which uses Net::Ping::External module which runs external ping(1) and parses the output. An alpha version of Net::Ping::External is available in CPAN and in 5.7.2 the Net::Ping::External may be integrated to Perl.

  • The open pragma allows layers other than ":raw" and ":crlf" when using PerlIO.

  • POSIX::sigaction() is now much more flexible and robust. You can now install coderef handlers, 'DEFAULT', and 'IGNORE' handlers, installing new handlers was not atomic.

  • The Test module has been significantly enhanced. Its use is greatly recommended for module writers.

  • The utf8:: name space (as in the pragma) provides various Perl-callable functions to provide low level access to Perl's internal Unicode representation. At the moment only length() has been implemented.

The following modules have been upgraded from the versions at CPAN: CPAN, CGI, DB_File, File::Temp, Getopt::Long, Pod::Man, Pod::Text, Storable, Text-Tabs+Wrap.

Performance Enhancements

  • Hashes now use Bob Jenkins "One-at-a-Time" hashing key algorithm ( http://burtleburtle.net/bob/hash/doobs.html ). This algorithm is reasonably fast while producing a much better spread of values than the old hashing algorithm (originally by Chris Torek, later tweaked by Ilya Zakharevich). Hash values output from the algorithm on a hash of all 3-char printable ASCII keys comes much closer to passing the DIEHARD random number generation tests. According to perlbench, this change has not affected the overall speed of Perl.

  • unshift() should now be noticeably faster.

Utility Changes

  • h2xs now produces template README.

  • s2p has been completely rewritten in Perl. (It is in fact a full implementation of sed in Perl.)

  • xsubpp now supports OUT keyword.

New Documentation

perlclib

Internal replacements for standard C library functions. (Interesting only for extension writers and Perl core hackers.)

perliol

Internals of PerlIO with layers.

README.aix

Documentation on compiling Perl on AIX has been added. AIX has several different C compilers and getting the right patch level is essential. On install README.aix will be installed as the perlaix manpage.

README.bs2000

Documentation on compiling Perl on the POSIX-BC platform (an EBCDIC mainframe environment) has been added.

This was formerly known as README.posix-bc but the name was considered to be too confusing (it has nothing to do with the POSIX module or the POSIX standard). On install README.bs2000 will be installed as the perlbs2000 manpage.

README.macos

In perl 5.7.1 (and in the 5.6.1) the MacPerl sources have been synchronised with the standard Perl sources. To compile MacPerl some additional steps are required, and this file documents those steps. On install README.macos will be installed as the perlmacos manpage.

README.mpeix

The README.mpeix has been podified, which means that this information about compiling and using Perl on the MPE/iX miniframe platform will be installed as the perlmpeix manpage.

README.solaris

README.solaris has been created and Solaris wisdom from elsewhere in the Perl documentation has been collected there. On install README.solaris will be installed as the perlsolaris manpage.

README.vos

The README.vos has been podified, which means that this information about compiling and using Perl on the Stratus VOS miniframe platform will be installed as the perlvos manpage.

Porting/repository.pod

Documentation on how to use the Perl source repository has been added.

Installation and Configuration Improvements

  • Because PerlIO is now the default on most platforms, "-perlio" doesn't get appended to the $Config{archname} (also known as $^O) anymore. Instead, if you explicitly choose not to use perlio (Configure command line option -Uuseperlio), you will get "-stdio" appended.

  • Another change related to the architecture name is that "-64all" (-Duse64bitall, or "maximally 64-bit") is appended only if your pointers are 64 bits wide. (To be exact, the use64bitall is ignored.)

  • APPLLIB_EXP, a less-know configuration-time definition, has been documented. It can be used to prepend site-specific directories to Perl's default search path (@INC), see INSTALL for information.

  • Building Berkeley DB3 for compatibility modes for DB, NDBM, and ODBM has been documented in INSTALL.

  • If you are on IRIX or Tru64 platforms, new profiling/debugging options have been added, see the perlhack manpage for more information about pixie and Third Degree.

New Or Improved Platforms

For the list of platforms known to support Perl, see Supported Platforms in the perlport manpage.

  • AIX dynamic loading should be now better supported.

  • After a long pause, AmigaOS has been verified to be happy with Perl.

  • EBCDIC platforms (z/OS, also known as OS/390, POSIX-BC, and VM/ESA) have been regained. Many test suite tests still fail and the co-existence of Unicode and EBCDIC isn't quite settled, but the situation is much better than with Perl 5.6. See the perlos390 manpage, the perlbs2000 manpage (for POSIX-BC), and the perlvmesa manpage for more information.

  • Building perl with -Duseithreads or -Duse5005threads now works under HP-UX 10.20 (previously it only worked under 10.30 or later). You will need a thread library package installed. See README.hpux.

  • Mac OS Classic (MacPerl has of course been available since perl 5.004 but now the source code bases of standard Perl and MacPerl have been synchronised)

  • NCR MP-RAS is now supported.

  • NonStop-UX is now supported.

  • Amdahl UTS is now supported.

  • z/OS (formerly known as OS/390, formerly known as MVS OE) has now support for dynamic loading. This is not selected by default, however, you must specify -Dusedl in the arguments of Configure.

Generic Improvements

  • Configure no longer includes the DBM libraries (dbm, gdbm, db, ndbm) when building the Perl binary. The only exception to this is SunOS 4.x, which needs them.

  • Some new Configure symbols, useful for extension writers:

    d_cmsghdr

    For struct cmsghdr.

    • d_fcntl_can_lock

    Whether fcntl() can be used for file locking.

    d_fsync
    d_getitimer
    d_getpagsz

    For getpagesize(), though you should prefer POSIX::sysconf(_SC_PAGE_SIZE))

    d_msghdr_s

    For struct msghdr.

    need_va_copy

    Whether one needs to use Perl_va_copy() to copy varargs.

    d_readv
    d_recvmsg
    d_sendmsg
    sig_size

    The number of elements in an array needed to hold all the available signals.

    d_sockatmark
    d_strtoq
    d_u32align

    Whether one needs to access character data aligned by U32 sized pointers.

    d_ualarm
    d_usleep

  • Removed Configure symbols: the PDP-11 memory model settings: huge, large, medium, models.

  • SOCKS support is now much more robust.

  • If your file system supports symbolic links you can build Perl outside of the source directory by

            mkdir perl/build/directory
        cd perl/build/directory
        sh /path/to/perl/source/Configure -Dmksymlinks ...

    This will create in perl/build/directory a tree of symbolic links pointing to files in /path/to/perl/source. The original files are left unaffected. After Configure has finished you can just say

            make all test

    and Perl will be built and tested, all in perl/build/directory.

Selected Bug Fixes

Numerous memory leaks and uninitialized memory accesses have been hunted down. Most importantly anonymous subs used to leak quite a bit.

  • chop(@list) in list context returned the characters chopped in reverse order. This has been reversed to be in the right order.

  • The order of DESTROYs has been made more predictable.

  • mkdir() now ignores trailing slashes in the directory name, as mandated by POSIX.

  • Attributes (like :shared) didn't work with our().

  • The PERL5OPT environment variable (for passing command line arguments to Perl) didn't work for more than a single group of options.

  • The tainting behaviour of sprintf() has been rationalized. It does not taint the result of floating point formats anymore, making the behaviour consistent with that of string interpolation.

  • All but the first argument of the IO syswrite() method are now optional.

  • Tie::ARRAY SPLICE method was broken.

  • vec() now tries to work with characters <= 255 when possible, but it leaves higher character values in place. In that case, if vec() was used to modify the string, it is no longer considered to be utf8-encoded.

Platform Specific Changes and Fixes

  • Linux previously had problems related to sockaddrlen when using accept(), revcfrom() (in Perl: recv()), getpeername(), and getsockname().

  • Previously DYNIX/ptx had problems in its Configure probe for non-blocking I/O.

  • Windows

    • Borland C++ v5.5 is now a supported compiler that can build Perl. However, the generated binaries continue to be incompatible with those generated by the other supported compilers (GCC and Visual C++).

    • Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root. Other bugs in chdir() and Cwd::cwd() have also been fixed.

    • Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x.

    • HTML files will be installed in c:\perl\html instead of c:\perl\lib\pod\html

    • The makefiles now provide a single switch to bulk-enable all the features enabled in ActiveState ActivePerl (a popular binary distribution).

New or Changed Diagnostics

Two new debugging options have been added: if you have compiled your Perl with debugging, you can use the -DT and -DR options to trace tokenising and to add reference counts to displaying variables, respectively.

  • If an attempt to use a (non-blessed) reference as an array index is made, a warning is given.

  • push @a; and unshift @a; (with no values to push or unshift) now give a warning. This may be a problem for generated and evaled code.

Changed Internals

  • Some new APIs: ptr_table_clear(), ptr_table_free(), sv_setref_uv(). For the full list of the available APIs see the perlapi manpage.

  • dTHR and djSP have been obsoleted; the former removed (because it's a no-op) and the latter replaced with dSP.

  • Perl now uses system malloc instead of Perl malloc on all 64-bit platforms, and even in some not-always-64-bit platforms like AIX, IRIX, and Solaris. This change breaks backward compatibility but Perl's malloc has problems with large address spaces and also the speed of vendors' malloc is generally better in large address space machines (Perl's malloc is mostly tuned for space).

New Tests

Many new tests have been added. The most notable is probably the lib/1_compile: it is very notable because running it takes quite a long time -- it test compiles all the Perl modules in the distribution. Please be patient.

Known Problems

Note that unlike other sections in this document (which describe changes since 5.7.0) this section is cumulative containing known problems for all the 5.7 releases.

AIX vac 5.0.0.0 May Produce Buggy Code For Perl

The AIX C compiler vac version 5.0.0.0 may produce buggy code, resulting in few random tests failing, but when the failing tests are run by hand, they succeed. We suggest upgrading to at least vac version 5.0.1.0, that has been known to compile Perl correctly. "lslpp -L|grep vac.C" will tell you the vac version.

lib/ftmp-security tests warn 'system possibly insecure'

Don't panic. Read INSTALL 'make test' section instead.

lib/io_multihomed Fails In LP64-Configured HP-UX

The lib/io_multihomed test may hang in HP-UX if Perl has been configured to be 64-bit. Because other 64-bit platforms do not hang in this test, HP-UX is suspect. All other tests pass in 64-bit HP-UX. The test attempts to create and connect to "multihomed" sockets (sockets which have multiple IP addresses).

Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX

If perl is configured with -Duse64bitall, the successful result of the subtest 10 of lib/posix may arrive before the successful result of the subtest 9, which confuses the test harness so much that it thinks the subtest 9 failed.

lib/b test 19

The test fails on various platforms (PA64 and IA64 are known), but the exact cause is still being investigated.

Linux With Sfio Fails op/misc Test 48

No known fix.

sigaction test 13 in VMS

The test is known to fail; whether it's because of VMS of because of faulty test is not known.

sprintf tests 129 and 130

The op/sprintf tests 129 and 130 are known to fail on some platforms. Examples include any platform using sfio, and Compaq/Tandem's NonStop-UX. The failing platforms do not comply with the ANSI C Standard, line 19ff on page 134 of ANSI X3.159 1989 to be exact. (They produce something else than "1" and "-1" when formatting 0.6 and -0.6 using the printf format "%.0f", most often they produce "0" and "-0".)

Failure of Thread tests

The subtests 19 and 20 of lib/thr5005.t test are known to fail due to fundamental problems in the 5.005 threading implementation. These are not new failures--Perl 5.005_0x has the same bugs, but didn't have these tests. (Note that support for 5.005-style threading remains experimental.)

Localising a Tied Variable Leaks Memory

    use Tie::Hash;
    tie my %tie_hash => 'Tie::StdHash';

    ...
    local($tie_hash{Foo}) = 1; # leaks

Code like the above is known to leak memory every time the local() is executed.

Self-tying of Arrays and Hashes Is Forbidden

Self-tying of arrays and hashes is broken in rather deep and hard-to-fix ways. As a stop-gap measure to avoid people from getting frustrated at the mysterious results (core dumps, most often) it is for now forbidden (you will get a fatal error even from an attempt).

Building Extensions Can Fail Because Of Largefiles

Some extensions like mod_perl are known to have issues with `largefiles', a change brought by Perl 5.6.0 in which file offsets default to 64 bits wide, where supported. Modules may fail to compile at all or compile and work incorrectly. Currently there is no good solution for the problem, but Configure now provides appropriate non-largefile ccflags, ldflags, libswanted, and libs in the %Config hash (e.g., $Config{ccflags_nolargefiles}) so the extensions that are having problems can try configuring themselves without the largefileness. This is admittedly not a clean solution, and the solution may not even work at all. One potential failure is whether one can (or, if one can, whether it's a good idea) link together at all binaries with different ideas about file offsets, all this is platform-dependent.

The Compiler Suite Is Still Experimental

The compiler suite is slowly getting better but is nowhere near working order yet.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/ There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Jarkko Hietaniemi <jhi@iki.fi>, with many contributions from The Perl Porters and Perl Users submitting feedback and patches.

Send omissions or corrections to <perlbug@perl.org>.


perl572delta - what's new for perl v5.7.2

  • Security Vulnerability Closed
  • Incompatible Changes
    • 64-bit platforms and malloc
    • AIX Dynaloading
    • Socket Extension Dynamic in VMS
    • Different Definition of the Unicode Character Classes \p{In...}
    • Deprecations
  • Core Enhancements
  • Modules and Pragmata
    • New Modules and Distributions
    • Updated And Improved Modules and Pragmata
  • Utility Changes
  • New Documentation
  • Installation and Configuration Improvements
    • New Or Improved Platforms
    • Generic Improvements
  • Selected Bug Fixes
    • Platform Specific Changes and Fixes
  • New or Changed Diagnostics
  • Source Code Enhancements
    • MAGIC constants
    • Better commented code
    • Regex pre-/post-compilation items matched up
    • gcc -Wall
  • New Tests
  • Known Problems
    • AIX
    • Amiga Perl Invoking Mystery
    • lib/ftmp-security tests warn 'system possibly insecure'
    • Cygwin intermittent failures of lib/Memoize/t/expire_file 11 and 12
    • HP-UX lib/io_multihomed Fails When LP64-Configured
    • HP-UX lib/posix Subtest 9 Fails When LP64-Configured
    • Linux With Sfio Fails op/misc Test 48
    • OS/390
    • op/sprintf tests 129 and 130
    • Failure of Thread tests
    • UNICOS
    • UTS
    • VMS
    • Win32
    • Localising a Tied Variable Leaks Memory
    • Self-tying of Arrays and Hashes Is Forbidden
    • Variable Attributes are not Currently Usable for Tieing
    • Building Extensions Can Fail Because Of Largefiles
    • The Compiler Suite Is Still Experimental
    • The Long Double Support is Still Experimental
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl572delta - what's new for perl v5.7.2

DESCRIPTION

This document describes differences between the 5.7.1 release and the 5.7.2 release.

(To view the differences between the 5.6.0 release and the 5.7.0 release, see the perl570delta manpage. To view the differences between the 5.7.0 release and the 5.7.1 release, see the perl571delta manpage.)

Security Vulnerability Closed

(This change was already made in 5.7.0 but bears repeating here.)

A security vulnerability affecting all Perl versions prior to 5.6.1 was found in August 2000. The vulnerability does not affect default installations and as far as is known affects only the Linux platform.

You should upgrade your Perl to 5.6.1 as soon as possible. Patches for earlier releases exist but using the patches require full recompilation from the source code anyway, so 5.6.1 is your best choice.

See http://www.cpan.org/src/5.0/sperl-2000-08-05/sperl-2000-08-05.txt for more information.

Incompatible Changes

64-bit platforms and malloc

If your pointers are 64 bits wide, the Perl malloc is no more being used because it simply does not work with 8-byte pointers. Also, usually the system malloc on such platforms are much better optimized for such large memory models than the Perl malloc.

AIX Dynaloading

The AIX dynaloading now uses in AIX releases 4.3 and newer the native dlopen interface of AIX instead of the old emulated interface. This change will probably break backward compatibility with compiled modules. The change was made to make Perl more compliant with other applications like modperl which are using the AIX native interface.

Socket Extension Dynamic in VMS

The Socket extension is now dynamically loaded instead of being statically built in. This may or may not be a problem with ancient TCP/IP stacks of VMS: we do not know since we weren't able to test Perl in such configurations.

Different Definition of the Unicode Character Classes \p{In...}

As suggested by the Unicode consortium, the Unicode character classes now prefer scripts as opposed to blocks (as defined by Unicode); in Perl, when the \p{In....} and the \p{In....} regular expression constructs are used. This has changed the definition of some of those character classes.

The difference between scripts and blocks is that scripts are the glyphs used by a language or a group of languages, while the blocks are more artificial groupings of 256 characters based on the Unicode numbering.

In general this change results in more inclusive Unicode character classes, but changes to the other direction also do take place: for example while the script Latin includes all the Latin characters and their various diacritic-adorned versions, it does not include the various punctuation or digits (since they are not solely Latin).

Changes in the character class semantics may have happened if a script and a block happen to have the same name, for example Hebrew. In such cases the script wins and \p{InHebrew} now means the script definition of Hebrew. The block definition in still available, though, by appending Block to the name: \p{InHebrewBlock} means what \p{InHebrew} meant in perl 5.6.0. For the full list of affected character classes, see Blocks in the perlunicode manpage.

Deprecations

The current user-visible implementation of pseudo-hashes (the weird use of the first array element) is deprecated starting from Perl 5.8.0 and will be removed in Perl 5.10.0, and the feature will be implemented differently. Not only is the current interface rather ugly, but the current implementation slows down normal array and hash use quite noticeably. The fields pragma interface will remain available.

The syntaxes @a->[...] and @h->{...} have now been deprecated.

The suidperl is also considered to be too much a risk to continue maintaining and the suidperl code is likely to be removed in a future release.

The package; syntax (package without an argument has been deprecated. Its semantics were never that clear and its implementation even less so. If you have used that feature to disallow all but fully qualified variables, use strict; instead.

The chdir(undef) and chdir('') behaviors to match chdir() has been deprecated. In future versions, chdir(undef) and chdir('') will simply fail.

Core Enhancements

In general a lot of fixing has happened in the area of Perl's understanding of numbers, both integer and floating point. Since in many systems the standard number parsing functions like strtoul() and atof() seem to have bugs, Perl tries to work around their deficiencies. This results hopefully in more accurate numbers.

  • The rules for allowing underscores (underbars) in numeric constants have been relaxed and simplified: now you can have an underscore between digits.

  • GMAGIC (right-hand side magic) could in many cases such as string concatenation be invoked too many times.

  • Lexicals I: lexicals outside an eval "" weren't resolved correctly inside a subroutine definition inside the eval "" if they were not already referenced in the top level of the eval""ed code.

  • Lexicals II: lexicals leaked at file scope into subroutines that were declared before the lexicals.

  • Lvalue subroutines can now return undef in list context.

  • The op_clear and op_null are now exported.

  • A new special regular expression variable has been introduced: $^N, which contains the most-recently closed group (submatch).

  • utime now supports utime undef, undef, @files to change the file timestamps to the current time.

  • The Perl parser has been stress tested using both random input and Markov chain input.

  • eval "v200" now works.

  • VMS now works under PerlIO.

  • END blocks are now run even if you exit/die in a BEGIN block. The execution of END blocks is now controlled by PL_exit_flags & PERL_EXIT_DESTRUCT_END. This enables the new behaviour for perl embedders. This will default in 5.10. See the perlembed manpage.

Modules and Pragmata

New Modules and Distributions

  • the Attribute::Handlers manpage - Simpler definition of attribute handlers

  • the ExtUtils::Constant manpage - generate XS code to import C header constants

  • the I18N::Langinfo manpage - query locale information

  • the I18N::LangTags manpage - functions for dealing with RFC3066-style language tags

  • libnet - a collection of perl5 modules related to network programming

    Perl installation leaves libnet unconfigured, use libnetcfg to configure.

  • the List::Util manpage - selection of general-utility list subroutines

  • the Locale::Maketext manpage - framework for localization

  • the Memoize manpage - Make your functions faster by trading space for time

  • the NEXT manpage - pseudo-class for method redispatch

  • the Scalar::Util manpage - selection of general-utility scalar subroutines

  • the Test::More manpage - yet another framework for writing test scripts

  • the Test::Simple manpage - Basic utilities for writing tests

  • the Time::HiRes manpage - high resolution ualarm, usleep, and gettimeofday

  • the Time::Piece manpage - Object Oriented time objects

    (Previously known as the Time::Object manpage.)

  • the Time::Seconds manpage - a simple API to convert seconds to other date values

  • UnicodeCD - Unicode Character Database

Updated And Improved Modules and Pragmata

  • the B::Deparse manpage module has been significantly enhanced. It now can deparse almost all of the standard test suite (so that the tests still succeed). There is a make target "test.deparse" for trying this out.

  • the Class::Struct manpage now assigns the array/hash element if the accessor is called with an array/hash element as the sole argument.

  • the Cwd manpage extension is now (even) faster.

  • DB_File extension has been updated to version 1.77.

  • the Fcntl manpage, the Socket manpage, and the Sys::Syslog manpage have been rewritten to use the new-style constant dispatch section (see the ExtUtils::Constant manpage).

  • the File::Find manpage is now (again) reentrant. It also has been made more portable.

  • the File::Glob manpage now supports GLOB_LIMIT constant to limit the size of the returned list of filenames.

  • the IO::Socket::INET manpage now supports LocalPort of zero (usually meaning that the operating system will make one up.)

  • The the vars manpage pragma now supports declaring fully qualified variables. (Something that our() does not and will not support.)

Utility Changes

  • The emacs/e2ctags.pl is now much faster.

  • h2ph now supports C trigraphs.

  • h2xs uses the new the ExtUtils::Constant manpage module which will affect newly created extensions that define constants. Since the new code is more correct (if you have two constants where the first one is a prefix of the second one, the first constant never gets defined), less lossy (it uses integers for integer constant, as opposed to the old code that used floating point numbers even for integer constants), and slightly faster, you might want to consider regenerating your extension code (the new scheme makes regenerating easy). h2xs now also supports C trigraphs.

  • libnetcfg has been added to configure the libnet.

  • The Pod::Html (and thusly pod2html) now allows specifying a cache directory.

New Documentation

  • the Locale::Maketext::TPJ13 manpage is an article about software localization, originally published in The Perl Journal #13, republished here with kind permission.

  • More README.$PLATFORM files have been converted into pod, which also means that they also be installed as perl$PLATFORM documentation files. The new files are the perlapollo manpage, the perlbeos manpage, the perldgux manpage, the perlhurd manpage, the perlmint manpage, the perlnetware manpage, the perlplan9 manpage, the perlqnx manpage, and the perltru64 manpage.

  • The Todo and Todo-5.6 files have been merged into the perltodo manpage.

  • Use of the gprof tool to profile Perl has been documented in the perlhack manpage. There is a make target "perl.gprof" for generating a gprofiled Perl executable.

Installation and Configuration Improvements

New Or Improved Platforms

  • AIX should now work better with gcc, threads, and 64-bitness. Also the long doubles support in AIX should be better now. See the perlaix manpage.

  • AtheOS ( http://www.atheos.cx/ ) is a new platform.

  • DG/UX platform now supports the 5.005-style threads. See the perldgux manpage.

  • DYNIX/ptx platform (a.k.a. dynixptx) is supported at or near osvers 4.5.2.

  • Several Mac OS (Classic) portability patches have been applied. We hope to get a fully working port by 5.8.0. (The remaining problems relate to the changed IO model of Perl.) See the perlmacos manpage.

  • Mac OS X (or Darwin) should now be able to build Perl even on HFS+ filesystems. (The case-insensitivity confused the Perl build process.)

  • NetWare from Novell is now supported. See the perlnetware manpage.

  • The Amdahl UTS UNIX mainframe platform is now supported.

Generic Improvements

  • In AFS installations one can configure the root of the AFS to be somewhere else than the default /afs by using the Configure parameter -Dafsroot=/some/where/else.

  • The version of Berkeley DB used when the Perl (and, presumably, the DB_File extension) was built is now available as @Config{qw(db_version_major db_version_minor db_version_patch)} from Perl and as DB_VERSION_MAJOR_CFG DB_VERSION_MINOR_CFG DB_VERSION_PATCH_CFG from C.

  • The Thread extension is now not built at all under ithreads (Configure -Duseithreads) because it wouldn't work anyway (the Thread extension requires being Configured with -Duse5005threads).

  • The B::Deparse compiler backend has been so significantly improved that almost the whole Perl test suite passes after being deparsed. A make target has been added to help in further testing: make test.deparse.

Selected Bug Fixes

  • The autouse pragma didn't work for Multi::Part::Function::Names.

  • The behaviour of non-decimal but numeric string constants such as "0x23" was platform-dependent: in some platforms that was seen as 35, in some as 0, in some as a floating point number (don't ask). This was caused by Perl using the operating system libraries in a situation where the result of the string to number conversion is undefined: now Perl consistently handles such strings as zero in numeric contexts.

  • dprofpp -R didn't work.

  • PERL5OPT with embedded spaces didn't work.

  • the Sys::Syslog manpage ignored the LOG_AUTH constant.

Platform Specific Changes and Fixes

  • Some versions of glibc have a broken modfl(). This affects builds with -Duselongdouble. This version of Perl detects this brokenness and has a workaround for it. The glibc release 2.2.2 is known to have fixed the modfl() bug.

New or Changed Diagnostics

  • In the regular expression diagnostics the << HERE marker introduced in 5.7.0 has been changed to be <-- HERE since too many people found the << to be too similar to here-document starters.

  • If you try to pack in the perlfunc manpage a number less than 0 or larger than 255 using the "C" format you will get an optional warning. Similarly for the "c" format and a number less than -128 or more than 127.

  • Certain regex modifiers such as (?o) make sense only if applied to the entire regex. You will an optional warning if you try to do otherwise.

  • Using arrays or hashes as references (e.g. %foo->{bar} has been deprecated for a while. Now you will get an optional warning.

Source Code Enhancements

MAGIC constants

The MAGIC constants (e.g. 'P') have been macrofied (e.g. PERL_MAGIC_TIED) for better source code readability and maintainability.

Better commented code

perly.c, sv.c, and sv.h have now been extensively commented.

Regex pre-/post-compilation items matched up

The regex compiler now maintains a structure that identifies nodes in the compiled bytecode with the corresponding syntactic features of the original regex expression. The information is attached to the new offsets member of the struct regexp. See the perldebguts manpage for more complete information.

gcc -Wall

The C code has been made much more gcc -Wall clean. Some warning messages still remain, though, so if you are compiling with gcc you will see some warnings about dubious practices. The warnings are being worked on.

New Tests

Several new tests have been added, especially for the lib subsection.

The tests are now reported in a different order than in earlier Perls. (This happens because the test scripts from under t/lib have been moved to be closer to the library/extension they are testing.)

Known Problems

Note that unlike other sections in this document (which describe changes since 5.7.0) this section is cumulative containing known problems for all the 5.7 releases.

AIX

  • In AIX 4.2 Perl extensions that use C++ functions that use statics may have problems in that the statics are not getting initialized. In newer AIX releases this has been solved by linking Perl with the libC_r library, but unfortunately in AIX 4.2 the said library has an obscure bug where the various functions related to time (such as time() and gettimeofday()) return broken values, and therefore in AIX 4.2 Perl is not linked against the libC_r.

  • vac 5.0.0.0 May Produce Buggy Code For Perl

    The AIX C compiler vac version 5.0.0.0 may produce buggy code, resulting in few random tests failing, but when the failing tests are run by hand, they succeed. We suggest upgrading to at least vac version 5.0.1.0, that has been known to compile Perl correctly. "lslpp -L|grep vac.C" will tell you the vac version.

Amiga Perl Invoking Mystery

One cannot call Perl using the volume: syntax, that is, perl -v works, but for example bin:perl -v doesn't. The exact reason is known but the current suspect is the ixemul library.

lib/ftmp-security tests warn 'system possibly insecure'

Don't panic. Read INSTALL 'make test' section instead.

Cygwin intermittent failures of lib/Memoize/t/expire_file 11 and 12

The subtests 11 and 12 sometimes fail and sometimes work.

HP-UX lib/io_multihomed Fails When LP64-Configured

The lib/io_multihomed test may hang in HP-UX if Perl has been configured to be 64-bit. Because other 64-bit platforms do not hang in this test, HP-UX is suspect. All other tests pass in 64-bit HP-UX. The test attempts to create and connect to "multihomed" sockets (sockets which have multiple IP addresses).

HP-UX lib/posix Subtest 9 Fails When LP64-Configured

If perl is configured with -Duse64bitall, the successful result of the subtest 10 of lib/posix may arrive before the successful result of the subtest 9, which confuses the test harness so much that it thinks the subtest 9 failed.

Linux With Sfio Fails op/misc Test 48

No known fix.

OS/390

OS/390 has rather many test failures but the situation is actually better than it was in 5.6.0, it's just that so many new modules and tests have been added.

 Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
 -----------------------------------------------------------------------------
 ../ext/B/Deparse.t                            14    1   7.14%  14
 ../ext/B/Showlex.t                             1    1 100.00%  1
 ../ext/Encode/Encode/Tcl.t                   610   13   2.13%  592 594 596 598
                                                                600 602 604-610
 ../ext/IO/lib/IO/t/io_unix.t     113 28928     5    3  60.00%  3-5
 ../ext/POSIX/POSIX.t                          29    1   3.45%  14
 ../ext/Storable/t/lock.t         255 65280     5    3  60.00%  3-5
 ../lib/locale.t                  129 33024   117   19  16.24%  99-117
 ../lib/warnings.t                            434    1   0.23%  75
 ../lib/ExtUtils.t                             27    1   3.70%  25
 ../lib/Math/BigInt/t/bigintpm.t             1190    1   0.08%  1145
 ../lib/Unicode/UCD.t                          81   48  59.26%  1-16 49-64 66-81
 ../lib/User/pwent.t                            9    1  11.11%  4
 op/pat.t                                     660    6   0.91%  242-243 424-425
                                                                626-627
 op/split.t                         0     9    ??   ??       %  ??
 op/taint.t                                   174    3   1.72%  156 162 168
 op/tr.t                                       70    3   4.29%  50 58-59
 Failed 16/422 test scripts, 96.21% okay. 105/23251 subtests failed, 99.55% okay.

op/sprintf tests 129 and 130

The op/sprintf tests 129 and 130 are known to fail on some platforms. Examples include any platform using sfio, and Compaq/Tandem's NonStop-UX. The failing platforms do not comply with the ANSI C Standard, line 19ff on page 134 of ANSI X3.159 1989 to be exact. (They produce something other than "1" and "-1" when formatting 0.6 and -0.6 using the printf format "%.0f", most often they produce "0" and "-0".)

Failure of Thread tests

Note that support for 5.005-style threading remains experimental.

The following tests are known to fail due to fundamental problems in the 5.005 threading implementation. These are not new failures--Perl 5.005_0x has the same bugs, but didn't have these tests.

  lib/autouse.t                 4
  t/lib/thr5005.t               19-20

UNICOS

  • ext/POSIX/sigaction subtests 6 and 13 may fail.

  • lib/ExtUtils may spuriously claim that subtest 28 failed, which is interesting since the test only has 27 tests.

  • Numerous numerical test failures

      op/numconvert                 209,210,217,218
  op/override                   7
  ext/Time/HiRes/HiRes          9
  lib/Math/BigInt/t/bigintpm    1145
  lib/Math/Trig                 25

    These tests fail because of yet unresolved floating point inaccuracies.

UTS

There are a few known test failures, see the perluts manpage.

VMS

Rather many tests are failing in VMS but that actually more tests succeed in VMS than they used to, it's just that there are many, many more tests than there used to be.

Here are the known failures from some compiler/platform combinations.

DEC C V5.3-006 on OpenVMS VAX V6.2

  [-.ext.list.util.t]tainted..............FAILED on test 3
  [-.ext.posix]sigaction..................FAILED on test 7
  [-.ext.time.hires]hires.................FAILED on test 14
  [-.lib.file.find]taint..................FAILED on test 17
  [-.lib.math.bigint.t]bigintpm...........FAILED on test 1183
  [-.lib.test.simple.t]exit...............FAILED on test 1
  [.lib]vmsish............................FAILED on test 13
  [.op]sprintf............................FAILED on test 12
  Failed 8/399 tests, 91.23% okay.

DEC C V6.0-001 on OpenVMS Alpha V7.2-1 and Compaq C V6.2-008 on OpenVMS Alpha V7.1

  [-.ext.list.util.t]tainted..............FAILED on test 3
  [-.lib.file.find]taint..................FAILED on test 17
  [-.lib.test.simple.t]exit...............FAILED on test 1
  [.lib]vmsish............................FAILED on test 13
  Failed 4/399 tests, 92.48% okay.

Compaq C V6.4-005 on OpenVMS Alpha 7.2.1

  [-.ext.b]showlex........................FAILED on test 1
  [-.ext.list.util.t]tainted..............FAILED on test 3
  [-.lib.file.find]taint..................FAILED on test 17
  [-.lib.test.simple.t]exit...............FAILED on test 1
  [.lib]vmsish............................FAILED on test 13
  [.op]misc...............................FAILED on test 49
  Failed 6/401 tests, 92.77% okay.

Win32

In multi-CPU boxes there are some problems with the I/O buffering: some output may appear twice.

Localising a Tied Variable Leaks Memory

    use Tie::Hash;
    tie my %tie_hash => 'Tie::StdHash';

    ...
    local($tie_hash{Foo}) = 1; # leaks

Code like the above is known to leak memory every time the local() is executed.

Self-tying of Arrays and Hashes Is Forbidden

Self-tying of arrays and hashes is broken in rather deep and hard-to-fix ways. As a stop-gap measure to avoid people from getting frustrated at the mysterious results (core dumps, most often) it is for now forbidden (you will get a fatal error even from an attempt).

Variable Attributes are not Currently Usable for Tieing

This limitation will hopefully be fixed in future. (Subroutine attributes work fine for tieing, see the Attribute::Handlers manpage).

Building Extensions Can Fail Because Of Largefiles

Some extensions like mod_perl are known to have issues with `largefiles', a change brought by Perl 5.6.0 in which file offsets default to 64 bits wide, where supported. Modules may fail to compile at all or compile and work incorrectly. Currently there is no good solution for the problem, but Configure now provides appropriate non-largefile ccflags, ldflags, libswanted, and libs in the %Config hash (e.g., $Config{ccflags_nolargefiles}) so the extensions that are having problems can try configuring themselves without the largefileness. This is admittedly not a clean solution, and the solution may not even work at all. One potential failure is whether one can (or, if one can, whether it's a good idea) link together at all binaries with different ideas about file offsets, all this is platform-dependent.

The Compiler Suite Is Still Experimental

The compiler suite is slowly getting better but is nowhere near working order yet.

The Long Double Support is Still Experimental

The ability to configure Perl's numbers to use "long doubles", floating point numbers of hopefully better accuracy, is still experimental. The implementations of long doubles are not yet widespread and the existing implementations are not quite mature or standardised, therefore trying to support them is a rare and moving target. The gain of more precision may also be offset by slowdown in computations (more bits to move around, and the operations are more likely to be executed by less optimised libraries).

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/ There may also be information at http://www.perl.com/perl/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Jarkko Hietaniemi <jhi@iki.fi>, with many contributions from The Perl Porters and Perl Users submitting feedback and patches.

Send omissions or corrections to <perlbug@perl.org>.


perl573delta - what's new for perl v5.7.3

  • Changes
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl573delta - what's new for perl v5.7.3

DESCRIPTION

This document describes differences between the 5.7.2 release and the 5.7.3 release.

(To view the differences between the 5.6.0 release and the 5.7.0 release, see the perl570delta manpage. To view the differences between the 5.7.0 release and the 5.7.1 release, see the perl571delta manpage. To view the differences between the 5.7.1 release and the 5.7.2 release, see the perl572delta manpage.)

Changes

This is just a selected list of some of the more notable changes. The numbers refer to the Perl repository change numbers; see Changes58 (or the Changes manpage in Perl 5.8.1). In addition to these changes, lots of work took place in integrating threads, PerlIO, and Unicode; general code cleanup; and last but not least porting to non-UNIX lands such as Win32, VMS, Cygwin, DJGPP, VOS, MacOS Classic, and EBCDIC.

  1. add LC_MESSAGES to POSIX :locale_h export tag

  2. add DEL to [:cntrl:]

  3. make h2ph understand constants like 1234L and 5678LL

  4. Win32: fix bugs in handling of the virtualized environment

  5. fix a bug in the security taint checking of open()

  6. make perl fork() safe even on platforms that don't have pthread_atfork()

  7. make switching optimization and debugging levels during Perl builds easier via the OPTIMIZE environment variable

  8. make split()'s unused captures to be undef, not ''

  9. Search::Dict: allow transforming lines before comparing

  10. allow installing extra modules or bundles when building Perl

  11. add -Wall in cflags when compiling with gcc to weed out dubious C practices

  12. pluggable optimizer

  13. WinCE: integrate the port

  14. Win32: 4-arg select was broken

  15. introduce the perlivp utility for verifying the Perl installation (IVP = Installation Verification Procedure)

  16. rename lib/unicode to lib/unicore to avoid case-insensitivity problems with lib/Unicode

  17. remove Time::Piece

  18. document that use utf8 is not the right way most of the time

  19. allow building perl with -DUSE_UTF8_SCRIPTS which makes UTF-8 the default script encoding (not the default since that would break all scripts having legacy eight-bit data in them)

  20. division preserving 64-bit integers

  21. document the coderef-in-@INC feature

  22. modulo (%) preserving 64-bit integers

  23. update to Unicode 3.1.1

  24. add the \[$@%&*] prototype support

  25. oct() and hex() in glorious 64 bit

  26. Class::Struct: allow recursive classes

  27. fix unpack U to be the reverse of pack U

  28. VMS: waitpid enhancements

  29. unpack("Z*Z*", pack("Z*Z*", ..)) was broken

  30. Devel::Peek: display UTF-8 SVs also as \x{...}

  31. Data::Dumper: option to sort hashes

  32. add perlpodspec

  33. threadsafe DynaLoader, re, Opcode, File::Glob, and B

  34. support BeOS better

  35. read-only hashes (user-level interface is Hash::Util)

  36. add Devel::PPPort

  37. add the sort pragma

  38. VMS: fix perl -P

  39. add perlpacktut

  40. SUPER-UX: add hints file

  41. Win32: non-blocking waitpid(-1,WNOHANG)

  42. introduce the -t option for gentler taint checking

  43. add the if pragma

  44. implement IV/UV/NV/long double un/packing with j/J/F/D

  45. document the new taint behaviour of exec LIST and system LIST

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.com/, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Jarkko Hietaniemi <jhi@iki.fi>, with many contributions from The Perl Porters and Perl Users submitting feedback and patches.

Send omissions or corrections to <perlbug@perl.org>.


perl581delta - what is new for perl v5.8.1

  • Incompatible Changes
    • Hash Randomisation
    • UTF-8 On Filehandles No Longer Activated By Locale
    • Single-number v-strings are no longer v-strings before "=>"
    • (Win32) The -C Switch Has Been Repurposed
    • (Win32) The /d Switch Of cmd.exe
  • Core Enhancements
    • UTF-8 no longer default under UTF-8 locales
    • Unsafe signals again available
    • Tied Arrays with Negative Array Indices
    • local ${$x}
    • Unicode Character Database 4.0.0
    • Deprecation Warnings
      • (Reminder) Pseudo-hashes are deprecated (really)
      • (Reminder) 5.005-style threads are deprecated (really)
      • (Reminder) The $* variable is deprecated (really)
    • Miscellaneous Enhancements
  • Modules and Pragmata
    • Updated Modules And Pragmata
  • Utility Changes
  • New Documentation
  • Installation and Configuration Improvements
    • Platform-specific enhancements
  • Selected Bug Fixes
    • Closures, eval and lexicals
    • Generic fixes
    • Platform-specific fixes
  • New or Changed Diagnostics
    • Changed "A thread exited while %d threads were running"
    • Removed "Attempt to clear a restricted hash"
    • New "Illegal declaration of anonymous subroutine"
    • Changed "Invalid range "%s" in transliteration operator"
    • New "Missing control char name in \c"
    • New "Newline in left-justified string for %s"
    • New "Possible precedence problem on bitwise %c operator"
    • New "Pseudo-hashes are deprecated"
    • New "read() on %s filehandle %s"
    • New "5.005 threads are deprecated"
    • New "Tied variable freed while still in use"
    • New "To%s: illegal mapping '%s'"
    • New "Use of freed value in iteration"
  • Changed Internals
  • New Tests
  • Known Problems
    • Tied hashes in scalar context
    • Net::Ping 450_service and 510_ping_udp failures
    • B::C
  • Platform Specific Problems
    • EBCDIC Platforms
    • Cygwin 1.5 problems
    • HP-UX: HP cc warnings about sendfile and sendpath
    • IRIX: t/uni/tr_7jis.t falsely failing
    • Mac OS X: no usemymalloc
    • Tru64: No threaded builds with GNU cc (gcc)
    • Win32: sysopen, sysread, syswrite
  • Future Directions
  • Reporting Bugs
  • SEE ALSO

NAME

perl581delta - what is new for perl v5.8.1

DESCRIPTION

This document describes differences between the 5.8.0 release and the 5.8.1 release.

If you are upgrading from an earlier release such as 5.6.1, first read the the perl58delta manpage, which describes differences between 5.6.0 and 5.8.0.

In case you are wondering about 5.6.1, it was bug-fix-wise rather identical to the development release 5.7.1. Confused? This timeline hopefully helps a bit: it lists the new major releases, their maintenance releases, and the development releases.

          New     Maintenance  Development
          5.6.0                             2000-Mar-22
                               5.7.0        2000-Sep-02
                  5.6.1                     2001-Apr-08
                               5.7.1        2001-Apr-09
                               5.7.2        2001-Jul-13
                               5.7.3        2002-Mar-05
          5.8.0                             2002-Jul-18
                  5.8.1                     2003-Sep-25

Incompatible Changes

Hash Randomisation

Mainly due to security reasons, the "random ordering" of hashes has been made even more random. Previously while the order of hash elements from keys(), values(), and each() was essentially random, it was still repeatable. Now, however, the order varies between different runs of Perl.

Perl has never guaranteed any ordering of the hash keys, and the ordering has already changed several times during the lifetime of Perl 5. Also, the ordering of hash keys has always been, and continues to be, affected by the insertion order.

The added randomness may affect applications.

One possible scenario is when output of an application has included hash data. For example, if you have used the Data::Dumper module to dump data into different files, and then compared the files to see whether the data has changed, now you will have false positives since the order in which hashes are dumped will vary. In general the cure is to sort the keys (or the values); in particular for Data::Dumper to use the Sortkeys option. If some particular order is really important, use tied hashes: for example the Tie::IxHash module which by default preserves the order in which the hash elements were added.

More subtle problem is reliance on the order of "global destruction". That is what happens at the end of execution: Perl destroys all data structures, including user data. If your destructors (the DESTROY subroutines) have assumed any particular ordering to the global destruction, there might be problems ahead. For example, in a destructor of one object you cannot assume that objects of any other class are still available, unless you hold a reference to them. If the environment variable PERL_DESTRUCT_LEVEL is set to a non-zero value, or if Perl is exiting a spawned thread, it will also destruct the ordinary references and the symbol tables that are no longer in use. You can't call a class method or an ordinary function on a class that has been collected that way.

The hash randomisation is certain to reveal hidden assumptions about some particular ordering of hash elements, and outright bugs: it revealed a few bugs in the Perl core and core modules.

To disable the hash randomisation in runtime, set the environment variable PERL_HASH_SEED to 0 (zero) before running Perl (for more information see PERL_HASH_SEED in the perlrun manpage), or to disable the feature completely in compile time, compile with -DNO_HASH_SEED (see INSTALL).

See Algorithmic Complexity Attacks in the perlsec manpage for the original rationale behind this change.

UTF-8 On Filehandles No Longer Activated By Locale

In Perl 5.8.0 all filehandles, including the standard filehandles, were implicitly set to be in Unicode UTF-8 if the locale settings indicated the use of UTF-8. This feature caused too many problems, so the feature was turned off and redesigned: see Core Enhancements.

Single-number v-strings are no longer v-strings before "=>"

The version strings or v-strings (see Version Strings in the perldata manpage) feature introduced in Perl 5.6.0 has been a source of some confusion-- especially when the user did not want to use it, but Perl thought it knew better. Especially troublesome has been the feature that before a "=>" a version string (a "v" followed by digits) has been interpreted as a v-string instead of a string literal. In other words:

        %h = ( v65 => 42 );

has meant since Perl 5.6.0

        %h = ( 'A' => 42 );

(at least in platforms of ASCII progeny) Perl 5.8.1 restores the more natural interpretation

        %h = ( 'v65' => 42 );

The multi-number v-strings like v65.66 and 65.66.67 still continue to be v-strings in Perl 5.8.

(Win32) The -C Switch Has Been Repurposed

The -C switch has changed in an incompatible way. The old semantics of this switch only made sense in Win32 and only in the "use utf8" universe in 5.6.x releases, and do not make sense for the Unicode implementation in 5.8.0. Since this switch could not have been used by anyone, it has been repurposed. The behavior that this switch enabled in 5.6.x releases may be supported in a transparent, data-dependent fashion in a future release.

For the new life of this switch, see UTF-8 no longer default under UTF-8 locales, and -C in the perlrun manpage.

(Win32) The /d Switch Of cmd.exe

Perl 5.8.1 uses the /d switch when running the cmd.exe shell internally for system(), backticks, and when opening pipes to external programs. The extra switch disables the execution of AutoRun commands from the registry, which is generally considered undesirable when running external programs. If you wish to retain compatibility with the older behavior, set PERL5SHELL in your environment to cmd /x/c.

Core Enhancements

UTF-8 no longer default under UTF-8 locales

In Perl 5.8.0 many Unicode features were introduced. One of them was found to be of more nuisance than benefit: the automagic (and silent) "UTF-8-ification" of filehandles, including the standard filehandles, if the user's locale settings indicated use of UTF-8.

For example, if you had en_US.UTF-8 as your locale, your STDIN and STDOUT were automatically "UTF-8", in other words an implicit binmode(..., ":utf8") was made. This meant that trying to print, say, chr(0xff), ended up printing the bytes 0xc3 0xbf. Hardly what you had in mind unless you were aware of this feature of Perl 5.8.0. The problem is that the vast majority of people weren't: for example in RedHat releases 8 and 9 the default locale setting is UTF-8, so all RedHat users got UTF-8 filehandles, whether they wanted it or not. The pain was intensified by the Unicode implementation of Perl 5.8.0 (still) having nasty bugs, especially related to the use of s/// and tr///. (Bugs that have been fixed in 5.8.1)

Therefore a decision was made to backtrack the feature and change it from implicit silent default to explicit conscious option. The new Perl command line option -C and its counterpart environment variable PERL_UNICODE can now be used to control how Perl and Unicode interact at interfaces like I/O and for example the command line arguments. See -C in the perlrun manpage and PERL_UNICODE in the perlrun manpage for more information.

Unsafe signals again available

In Perl 5.8.0 the so-called "safe signals" were introduced. This means that Perl no longer handles signals immediately but instead "between opcodes", when it is safe to do so. The earlier immediate handling easily could corrupt the internal state of Perl, resulting in mysterious crashes.

However, the new safer model has its problems too. Because now an opcode, a basic unit of Perl execution, is never interrupted but instead let to run to completion, certain operations that can take a long time now really do take a long time. For example, certain network operations have their own blocking and timeout mechanisms, and being able to interrupt them immediately would be nice.

Therefore perl 5.8.1 introduces a "backdoor" to restore the pre-5.8.0 (pre-5.7.3, really) signal behaviour. Just set the environment variable PERL_SIGNALS to unsafe, and the old immediate (and unsafe) signal handling behaviour returns. See PERL_SIGNALS in the perlrun manpage and Deferred Signals (Safe Signals) in the perlipc manpage.

In completely unrelated news, you can now use safe signals with POSIX::SigAction. See POSIX::SigAction in the POSIX manpage.

Tied Arrays with Negative Array Indices

Formerly, the indices passed to FETCH, STORE, EXISTS, and DELETE methods in tied array class were always non-negative. If the actual argument was negative, Perl would call FETCHSIZE implicitly and add the result to the index before passing the result to the tied array method. This behaviour is now optional. If the tied array class contains a package variable named $NEGATIVE_INDICES which is set to a true value, negative values will be passed to FETCH, STORE, EXISTS, and DELETE unchanged.

local ${$x}

The syntaxes

        local ${$x}
        local @{$x}
        local %{$x}

now do localise variables, given that the $x is a valid variable name.

Unicode Character Database 4.0.0

The copy of the Unicode Character Database included in Perl 5.8 has been updated to 4.0.0 from 3.2.0. This means for example that the Unicode character properties are as in Unicode 4.0.0.

Deprecation Warnings

There is one new feature deprecation. Perl 5.8.0 forgot to add some deprecation warnings, these warnings have now been added. Finally, a reminder of an impending feature removal.

(Reminder) Pseudo-hashes are deprecated (really)

Pseudo-hashes were deprecated in Perl 5.8.0 and will be removed in Perl 5.10.0, see the perl58delta manpage for details. Each attempt to access pseudo-hashes will trigger the warning Pseudo-hashes are deprecated. If you really want to continue using pseudo-hashes but not to see the deprecation warnings, use:

    no warnings 'deprecated';

Or you can continue to use the the fields manpage pragma, but please don't expect the data structures to be pseudohashes any more.

(Reminder) 5.005-style threads are deprecated (really)

5.005-style threads (activated by use Thread;) were deprecated in Perl 5.8.0 and will be removed after Perl 5.8, see the perl58delta manpage for details. Each 5.005-style thread creation will trigger the warning 5.005 threads are deprecated. If you really want to continue using the 5.005 threads but not to see the deprecation warnings, use:

    no warnings 'deprecated';

(Reminder) The $* variable is deprecated (really)

The $* variable controlling multi-line matching has been deprecated and will be removed after 5.8. The variable has been deprecated for a long time, and a deprecation warning Use of $* is deprecated is given, now the variable will just finally be removed. The functionality has been supplanted by the /s and /m modifiers on pattern matching. If you really want to continue using the $*-variable but not to see the deprecation warnings, use:

    no warnings 'deprecated';

Miscellaneous Enhancements

map in void context is no longer expensive. map is now context aware, and will not construct a list if called in void context.

If a socket gets closed by the server while printing to it, the client now gets a SIGPIPE. While this new feature was not planned, it fell naturally out of PerlIO changes, and is to be considered an accidental feature.

PerlIO::get_layers(FH) returns the names of the PerlIO layers active on a filehandle.

PerlIO::via layers can now have an optional UTF8 method to indicate whether the layer wants to "auto-:utf8" the stream.

utf8::is_utf8() has been added as a quick way to test whether a scalar is encoded internally in UTF-8 (Unicode).

Modules and Pragmata

Updated Modules And Pragmata

The following modules and pragmata have been updated since Perl 5.8.0:

base
B::Bytecode

In much better shape than it used to be. Still far from perfect, but maybe worth a try.

B::Concise
B::Deparse
Benchmark

An optional feature, :hireswallclock, now allows for high resolution wall clock times (uses Time::HiRes).

ByteLoader

See B::Bytecode.

bytes

Now has bytes::substr.

CGI
charnames

One can now have custom character name aliases.

CPAN

There is now a simple command line frontend to the CPAN.pm module called cpan.

Data::Dumper

A new option, Pair, allows choosing the separator between hash keys and values.

DB_File
Devel::PPPort
Digest::MD5
Encode

Significant updates on the encoding pragma functionality (tr/// and the DATA filehandle, formats).

If a filehandle has been marked as to have an encoding, unmappable characters are detected already during input, not later (when the corrupted data is being used).

The ISO 8859-6 conversion table has been corrected (the 0x30..0x39 erroneously mapped to U+0660..U+0669, instead of U+0030..U+0039). The GSM 03.38 conversion did not handle escape sequences correctly. The UTF-7 encoding has been added (making Encode feature-complete with Unicode::String).

fields
libnet
Math::BigInt

A lot of bugs have been fixed since v1.60, the version included in Perl v5.8.0. Especially noteworthy are the bug in Calc that caused div and mod to fail for some large values, and the fixes to the handling of bad inputs.

Some new features were added, e.g. the broot() method, you can now pass parameters to config() to change some settings at runtime, and it is now possible to trap the creation of NaN and infinity.

As usual, some optimizations took place and made the math overall a tad faster. In some cases, quite a lot faster, actually. Especially alternative libraries like Math::BigInt::GMP benefit from this. In addition, a lot of the quite clunky routines like fsqrt() and flog() are now much much faster.

MIME::Base64
NEXT

Diamond inheritance now works.

Net::Ping
PerlIO::scalar

Reading from non-string scalars (like the special variables, see the perlvar manpage) now works.

podlators
Pod::LaTeX
PodParsers
Pod::Perldoc

Complete rewrite. As a side-effect, no longer refuses to startup when run by root.

Scalar::Util

New utilities: refaddr, isvstring, looks_like_number, set_prototype.

Storable

Can now store code references (via B::Deparse, so not foolproof).

strict

Earlier versions of the strict pragma did not check the parameters implicitly passed to its "import" (use) and "unimport" (no) routine. This caused the false idiom such as:

        use strict qw(@ISA);
        @ISA = qw(Foo);

This however (probably) raised the false expectation that the strict refs, vars and subs were being enforced (and that @ISA was somehow "declared"). But the strict refs, vars, and subs are not enforced when using this false idiom.

Starting from Perl 5.8.1, the above will cause an error to be raised. This may cause programs which used to execute seemingly correctly without warnings and errors to fail when run under 5.8.1. This happens because

        use strict qw(@ISA);

will now fail with the error:

        Unknown 'strict' tag(s) '@ISA'

The remedy to this problem is to replace this code with the correct idiom:

        use strict;
        use vars qw(@ISA);
        @ISA = qw(Foo);
Term::ANSIcolor
Test::Harness

Now much more picky about extra or missing output from test scripts.

Test::More
Test::Simple
Text::Balanced
Time::HiRes

Use of nanosleep(), if available, allows mixing subsecond sleeps with alarms.

threads

Several fixes, for example for join() problems and memory leaks. In some platforms (like Linux) that use glibc the minimum memory footprint of one ithread has been reduced by several hundred kilobytes.

threads::shared

Many memory leaks have been fixed.

Unicode::Collate
Unicode::Normalize
Win32::GetFolderPath
Win32::GetOSVersion

Now returns extra information.

Utility Changes

The h2xs utility now produces a more modern layout: Foo-Bar/lib/Foo/Bar.pm instead of Foo/Bar/Bar.pm. Also, the boilerplate test is now called t/Foo-Bar.t instead of t/1.t.

The Perl debugger (lib/perl5db.pl) has now been extensively documented and bugs found while documenting have been fixed.

perldoc has been rewritten from scratch to be more robust and featureful.

perlcc -B works now at least somewhat better, while perlcc -c is rather more broken. (The Perl compiler suite as a whole continues to be experimental.)

New Documentation

perl573delta has been added to list the differences between the (now quite obsolete) development releases 5.7.2 and 5.7.3.

perl58delta has been added: it is the perldelta of 5.8.0, detailing the differences between 5.6.0 and 5.8.0.

perlartistic has been added: it is the Artistic License in pod format, making it easier for modules to refer to it.

perlcheat has been added: it is a Perl cheat sheet.

perlgpl has been added: it is the GNU General Public License in pod format, making it easier for modules to refer to it.

perlmacosx has been added to tell about the installation and use of Perl in Mac OS X.

perlos400 has been added to tell about the installation and use of Perl in OS/400 PASE.

perlreref has been added: it is a regular expressions quick reference.

Installation and Configuration Improvements

The UNIX standard Perl location, /usr/bin/perl, is no longer overwritten by default if it exists. This change was very prudent because so many UNIX vendors already provide a /usr/bin/perl, but simultaneously many system utilities may depend on that exact version of Perl, so better not to overwrite it.

One can now specify installation directories for site and vendor man and HTML pages, and site and vendor scripts. See INSTALL.

One can now specify a destination directory for Perl installation by specifying the DESTDIR variable for make install. (This feature is slightly different from the previous Configure -Dinstallprefix=....) See INSTALL.

gcc versions 3.x introduced a new warning that caused a lot of noise during Perl compilation: gcc -Ialreadyknowndirectory (warning: changing search order). This warning has now been avoided by Configure weeding out such directories before the compilation.

One can now build subsets of Perl core modules by using the Configure flags -Dnoextensions=... and -Donlyextensions=..., see INSTALL.

Platform-specific enhancements

In Cygwin Perl can now be built with threads (Configure -Duseithreads). This works with both Cygwin 1.3.22 and Cygwin 1.5.3.

In newer FreeBSD releases Perl 5.8.0 compilation failed because of trying to use malloc.h, which in FreeBSD is just a dummy file, and a fatal error to even try to use. Now malloc.h is not used.

Perl is now known to build also in Hitachi HI-UXMPP.

Perl is now known to build again in LynxOS.

Mac OS X now installs with Perl version number embedded in installation directory names for easier upgrading of user-compiled Perl, and the installation directories in general are more standard. In other words, the default installation no longer breaks the Apple-provided Perl. On the other hand, with Configure -Dprefix=/usr you can now really replace the Apple-supplied Perl (please be careful).

Mac OS X now builds Perl statically by default. This change was done mainly for faster startup times. The Apple-provided Perl is still dynamically linked and shared, and you can enable the sharedness for your own Perl builds by Configure -Duseshrplib.

Perl has been ported to IBM's OS/400 PASE environment. The best way to build a Perl for PASE is to use an AIX host as a cross-compilation environment. See README.os400.

Yet another cross-compilation option has been added: now Perl builds on OpenZaurus, an Linux distribution based on Mandrake + Embedix for the Sharp Zaurus PDA. See the Cross/README file.

Tru64 when using gcc 3 drops the optimisation for toke.c to -O2 because of gigantic memory use with the default -O3.

Tru64 can now build Perl with the newer Berkeley DBs.

Building Perl on WinCE has been much enhanced, see README.ce and README.perlce.

Selected Bug Fixes

Closures, eval and lexicals

There have been many fixes in the area of anonymous subs, lexicals and closures. Although this means that Perl is now more "correct", it is possible that some existing code will break that happens to rely on the faulty behaviour. In practice this is unlikely unless your code contains a very complex nesting of anonymous subs, evals and lexicals.

Generic fixes

If an input filehandle is marked :utf8 and Perl sees illegal UTF-8 coming in when doing <FH>, if warnings are enabled a warning is immediately given - instead of being silent about it and Perl being unhappy about the broken data later. (The :encoding(utf8) layer also works the same way.)

binmode(SOCKET, ":utf8") only worked on the input side, not on the output side of the socket. Now it works both ways.

For threaded Perls certain system database functions like getpwent() and getgrent() now grow their result buffer dynamically, instead of failing. This means that at sites with lots of users and groups the functions no longer fail by returning only partial results.

Perl 5.8.0 had accidentally broken the capability for users to define their own uppercase<->lowercase Unicode mappings (as advertised by the Camel). This feature has been fixed and is also documented better.

In 5.8.0 this

        $some_unicode .= <FH>;

didn't work correctly but instead corrupted the data. This has now been fixed.

Tied methods like FETCH etc. may now safely access tied values, i.e. resulting in a recursive call to FETCH etc. Remember to break the recursion, though.

At startup Perl blocks the SIGFPE signal away since there isn't much Perl can do about it. Previously this blocking was in effect also for programs executed from within Perl. Now Perl restores the original SIGFPE handling routine, whatever it was, before running external programs.

Linenumbers in Perl scripts may now be greater than 65536, or 2**16. (Perl scripts have always been able to be larger than that, it's just that the linenumber for reported errors and warnings have "wrapped around".) While scripts that large usually indicate a need to rethink your code a bit, such Perl scripts do exist, for example as results from generated code. Now linenumbers can go all the way to 4294967296, or 2**32.

Platform-specific fixes

Linux

  • Setting $0 works again (with certain limitations that Perl cannot do much about: see $0 in the perlvar manpage)

HP-UX

  • Setting $0 now works.

VMS

  • Configuration now tests for the presence of poll(), and IO::Poll now uses the vendor-supplied function if detected.

  • A rare access violation at Perl start-up could occur if the Perl image was installed with privileges or if there was an identifier with the subsystem attribute set in the process's rightslist. Either of these circumstances triggered tainting code that contained a pointer bug. The faulty pointer arithmetic has been fixed.

  • The length limit on values (not keys) in the %ENV hash has been raised from 255 bytes to 32640 bytes (except when the PERL_ENV_TABLES setting overrides the default use of logical names for %ENV). If it is necessary to access these long values from outside Perl, be aware that they are implemented using search list logical names that store the value in pieces, each 255-byte piece (up to 128 of them) being an element in the search list. When doing a lookup in %ENV from within Perl, the elements are combined into a single value. The existing VMS-specific ability to access individual elements of a search list logical name via the $ENV{'foo;N'} syntax (where N is the search list index) is unimpaired.

  • The piping implementation now uses local rather than global DCL symbols for inter-process communication.

  • File::Find could become confused when navigating to a relative directory whose name collided with a logical name. This problem has been corrected by adding directory syntax to relative path names, thus preventing logical name translation.

Win32

  • A memory leak in the fork() emulation has been fixed.

  • The return value of the ioctl() built-in function was accidentally broken in 5.8.0. This has been corrected.

  • The internal message loop executed by perl during blocking operations sometimes interfered with messages that were external to Perl. This often resulted in blocking operations terminating prematurely or returning incorrect results, when Perl was executing under environments that could generate Windows messages. This has been corrected.

  • Pipes and sockets are now automatically in binary mode.

  • The four-argument form of select() did not preserve $! (errno) properly when there were errors in the underlying call. This is now fixed.

  • The "CR CR LF" problem of has been fixed, binmode(FH, ":crlf") is now effectively a no-op.

New or Changed Diagnostics

All the warnings related to pack() and unpack() were made more informative and consistent.

Changed "A thread exited while %d threads were running"

The old version

    A thread exited while %d other threads were still running

was misleading because the "other" included also the thread giving the warning.

Removed "Attempt to clear a restricted hash"

It is not illegal to clear a restricted hash, so the warning was removed.

New "Illegal declaration of anonymous subroutine"

You must specify the block of code for sub.

Changed "Invalid range "%s" in transliteration operator"

The old version

    Invalid [] range "%s" in transliteration operator

was simply wrong because there are no "[] ranges" in tr///.

New "Missing control char name in \c"

Self-explanatory.

New "Newline in left-justified string for %s"

The padding spaces would appear after the newline, which is probably not what you had in mind.

New "Possible precedence problem on bitwise %c operator"

If you think this

    $x & $y == 0

tests whether the bitwise AND of $x and $y is zero, you will like this warning.

New "Pseudo-hashes are deprecated"

This warning should have been already in 5.8.0, since they are.

New "read() on %s filehandle %s"

You cannot read() (or sysread()) from a closed or unopened filehandle.

New "5.005 threads are deprecated"

This warning should have been already in 5.8.0, since they are.

New "Tied variable freed while still in use"

Something pulled the plug on a live tied variable, Perl plays safe by bailing out.

New "To%s: illegal mapping '%s'"

An illegal user-defined Unicode casemapping was specified.

New "Use of freed value in iteration"

Something modified the values being iterated over. This is not good.

Changed Internals

These news matter to you only if you either write XS code or like to know about or hack Perl internals (using Devel::Peek or any of the B:: modules counts), or like to run Perl with the -D option.

The embedding examples of the perlembed manpage have been reviewed to be uptodate and consistent: for example, the correct use of PERL_SYS_INIT3() and PERL_SYS_TERM().

Extensive reworking of the pad code (the code responsible for lexical variables) has been conducted by Dave Mitchell.

Extensive work on the v-strings by John Peacock.

UTF-8 length and position cache: to speed up the handling of Unicode (UTF-8) scalars, a cache was introduced. Potential problems exist if an extension bypasses the official APIs and directly modifies the PV of an SV: the UTF-8 cache does not get cleared as it should.

APIs obsoleted in Perl 5.8.0, like sv_2pv, sv_catpvn, sv_catsv, sv_setsv, are again available.

Certain Perl core C APIs like cxinc and regatom are no longer available at all to code outside the Perl core of the Perl core extensions. This is intentional. They never should have been available with the shorter names, and if you application depends on them, you should (be ashamed and) contact perl5-porters to discuss what are the proper APIs.

Certain Perl core C APIs like Perl_list are no longer available without their Perl_ prefix. If your XS module stops working because some functions cannot be found, in many cases a simple fix is to add the Perl_ prefix to the function and the thread context aTHX_ as the first argument of the function call. This is also how it should always have been done: letting the Perl_-less forms to leak from the core was an accident. For cleaner embedding you can also force this for all APIs by defining at compile time the cpp define PERL_NO_SHORT_NAMES.

Perl_save_bool() has been added.

Regexp objects (those created with qr) now have S-magic rather than R-magic. This fixed regexps of the form /...(??{...;$x})/ to no longer ignore changes made to $x. The S-magic avoids dropping the caching optimization and making (??{...}) constructs obscenely slow (and consequently useless). See also Magic Variables in the perlguts manpage. Regexp::Copy was affected by this change.

The Perl internal debugging macros DEBUG() and DEB() have been renamed to PERL_DEBUG() and PERL_DEB() to avoid namespace conflicts.

-DL removed (the leaktest had been broken and unsupported for years, use alternative debugging mallocs or tools like valgrind and Purify).

Verbose modifier v added for -DXv and -Dsv, see the perlrun manpage.

New Tests

In Perl 5.8.0 there were about 69000 separate tests in about 700 test files, in Perl 5.8.1 there are about 77000 separate tests in about 780 test files. The exact numbers depend on the Perl configuration and on the operating system platform.

Known Problems

The hash randomisation mentioned in Incompatible Changes is definitely problematic: it will wake dormant bugs and shake out bad assumptions.

If you want to use mod_perl 2.x with Perl 5.8.1, you will need mod_perl-1.99_10 or higher. Earlier versions of mod_perl 2.x do not work with the randomised hashes. (mod_perl 1.x works fine.) You will also need Apache::Test 1.04 or higher.

Many of the rarer platforms that worked 100% or pretty close to it with perl 5.8.0 have been left a little bit untended since their maintainers have been otherwise busy lately, and therefore there will be more failures on those platforms. Such platforms include Mac OS Classic, IBM z/OS (and other EBCDIC platforms), and NetWare. The most common Perl platforms (Unix and Unix-like, Microsoft platforms, and VMS) have large enough testing and expert population that they are doing well.

Tied hashes in scalar context

Tied hashes do not currently return anything useful in scalar context, for example when used as boolean tests:

        if (%tied_hash) { ... }

The current nonsensical behaviour is always to return false, regardless of whether the hash is empty or has elements.

The root cause is that there is no interface for the implementors of tied hashes to implement the behaviour of a hash in scalar context.

Net::Ping 450_service and 510_ping_udp failures

The subtests 9 and 18 of lib/Net/Ping/t/450_service.t, and the subtest 2 of lib/Net/Ping/t/510_ping_udp.t might fail if you have an unusual networking setup. For example in the latter case the test is trying to send a UDP ping to the IP address 127.0.0.1.

B::C

The C-generating compiler backend B::C (the frontend being perlcc -c) is even more broken than it used to be because of the extensive lexical variable changes. (The good news is that B::Bytecode and ByteLoader are better than they used to be.)

Platform Specific Problems

EBCDIC Platforms

IBM z/OS and other EBCDIC platforms continue to be problematic regarding Unicode support. Many Unicode tests are skipped when they really should be fixed.

Cygwin 1.5 problems

In Cygwin 1.5 the io/tell and op/sysio tests have failures for some yet unknown reason. In 1.5.5 the threads tests stress_cv, stress_re, and stress_string are failing unless the environment variable PERLIO is set to "perlio" (which makes also the io/tell failure go away).

Perl 5.8.1 does build and work well with Cygwin 1.3: with (uname -a) CYGWIN_NT-5.0 ... 1.3.22(0.78/3/2) 2003-03-18 09:20 i686 ... a 100% "make test" was achieved with Configure -des -Duseithreads.

HP-UX: HP cc warnings about sendfile and sendpath

With certain HP C compiler releases (e.g. B.11.11.02) you will get many warnings like this (lines wrapped for easier reading):

  cc: "/usr/include/sys/socket.h", line 504: warning 562:
    Redeclaration of "sendfile" with a different storage class specifier:
      "sendfile" will have internal linkage.
  cc: "/usr/include/sys/socket.h", line 505: warning 562:
    Redeclaration of "sendpath" with a different storage class specifier:
      "sendpath" will have internal linkage.

The warnings show up both during the build of Perl and during certain lib/ExtUtils tests that invoke the C compiler. The warning, however, is not serious and can be ignored.

IRIX: t/uni/tr_7jis.t falsely failing

The test t/uni/tr_7jis.t is known to report failure under 'make test' or the test harness with certain releases of IRIX (at least IRIX 6.5 and MIPSpro Compilers Version 7.3.1.1m), but if run manually the test fully passes.

Mac OS X: no usemymalloc

The Perl malloc (-Dusemymalloc) does not work at all in Mac OS X. This is not that serious, though, since the native malloc works just fine.

Tru64: No threaded builds with GNU cc (gcc)

In the latest Tru64 releases (e.g. v5.1B or later) gcc cannot be used to compile a threaded Perl (-Duseithreads) because the system <pthread.h> file doesn't know about gcc.

Win32: sysopen, sysread, syswrite

As of the 5.8.0 release, sysopen()/sysread()/syswrite() do not behave like they used to in 5.6.1 and earlier with respect to "text" mode. These built-ins now always operate in "binary" mode (even if sysopen() was passed the O_TEXT flag, or if binmode() was used on the file handle). Note that this issue should only make a difference for disk files, as sockets and pipes have always been in "binary" mode in the Windows port. As this behavior is currently considered a bug, compatible behavior may be re-introduced in a future release. Until then, the use of sysopen(), sysread() and syswrite() is not supported for "text" mode operations.

Future Directions

The following things might happen in future. The first publicly available releases having these characteristics will be the developer releases Perl 5.9.x, culminating in the Perl 5.10.0 release. These are our best guesses at the moment: we reserve the right to rethink.

  • PerlIO will become The Default. Currently (in Perl 5.8.x) the stdio library is still used if Perl thinks it can use certain tricks to make stdio go really fast. For future releases our goal is to make PerlIO go even faster.

  • A new feature called assertions will be available. This means that one can have code called assertions sprinkled in the code: usually they are optimised away, but they can be enabled with the -A option.

  • A new operator // (defined-or) will be available. This means that one will be able to say

        $a // $b

    instead of

       defined $a ? $a : $b

    and

       $c //= $d;

    instead of

       $c = $d unless defined $c;

    The operator will have the same precedence and associativity as ||. A source code patch against the Perl 5.8.1 sources will be available in CPAN as authors/id/H/HM/HMBRAND/dor-5.8.1.diff.

  • unpack() will default to unpacking the $_.

  • Various Copy-On-Write techniques will be investigated in hopes of speeding up Perl.

  • CPANPLUS, Inline, and Module::Build will become core modules.

  • The ability to write true lexically scoped pragmas will be introduced.

  • Work will continue on the bytecompiler and byteloader.

  • v-strings as they currently exist are scheduled to be deprecated. The v-less form (1.2.3) will become a "version object" when used with use, require, and $VERSION. $^V will also be a "version object" so the printf("%vd",...) construct will no longer be needed. The v-ful version (v1.2.3) will become obsolete. The equivalence of strings and v-strings (e.g. that currently 5.8.0 is equal to "\5\8\0") will go away. There may be no deprecation warning for v-strings, though: it is quite hard to detect when v-strings are being used safely, and when they are not.

  • 5.005 Threads Will Be Removed

  • The $* Variable Will Be Removed (it was deprecated a long time ago)

  • Pseudohashes Will Be Removed

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/ . There may also be information at http://www.perl.com/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl582delta - what is new for perl v5.8.2

  • Incompatible Changes
  • Core Enhancements
    • Hash Randomisation
    • Threading
  • Modules and Pragmata
    • Updated Modules And Pragmata
  • Selected Bug Fixes
  • Changed Internals
  • Platform Specific Problems
  • Future Directions
  • Reporting Bugs
  • SEE ALSO

NAME

perl582delta - what is new for perl v5.8.2

DESCRIPTION

This document describes differences between the 5.8.1 release and the 5.8.2 release.

If you are upgrading from an earlier release such as 5.6.1, first read the the perl58delta manpage, which describes differences between 5.6.0 and 5.8.0, and the the perl581delta manpage, which describes differences between 5.8.0 and 5.8.1.

Incompatible Changes

For threaded builds for modules calling certain re-entrant system calls, binary compatibility was accidentally lost between 5.8.0 and 5.8.1. Binary compatibility with 5.8.0 has been restored in 5.8.2, which necessitates breaking compatibility with 5.8.1. We see this as the lesser of two evils.

This will only affect people who have a threaded perl 5.8.1, and compiled modules which use these calls, and now attempt to run the compiled modules with 5.8.2. The fix is to re-compile and re-install the modules using 5.8.2.

Core Enhancements

Hash Randomisation

The hash randomisation introduced with 5.8.1 has been amended. It transpired that although the implementation introduced in 5.8.1 was source compatible with 5.8.0, it was not binary compatible in certain cases. 5.8.2 contains an improved implementation which is both source and binary compatible with both 5.8.0 and 5.8.1, and remains robust against the form of attack which prompted the change for 5.8.1.

We are grateful to the Debian project for their input in this area. See Algorithmic Complexity Attacks in the perlsec manpage for the original rationale behind this change.

Threading

Several memory leaks associated with variables shared between threads have been fixed.

Modules and Pragmata

Updated Modules And Pragmata

The following modules and pragmata have been updated since Perl 5.8.1:

Devel::PPPort
Digest::MD5
I18N::LangTags
libnet
MIME::Base64
Pod::Perldoc
strict

Documentation improved

Tie::Hash

Documentation improved

Time::HiRes
Unicode::Collate
Unicode::Normalize
UNIVERSAL

Documentation improved

Selected Bug Fixes

Some syntax errors involving unrecognized filetest operators are now handled correctly by the parser.

Changed Internals

Interpreter initialization is more complete when -DMULTIPLICITY is off. This should resolve problems with initializing and destroying the Perl interpreter more than once in a single process.

Platform Specific Problems

Dynamic linker flags have been tweaked for Solaris and OS X, which should solve problems seen while building some XS modules.

Bugs in OS/2 sockets and tmpfile have been fixed.

In OS X setreuid and friends are troublesome - perl will now work around their problems as best possible.

Future Directions

Starting with 5.8.3 we intend to make more frequent maintenance releases, with a smaller number of changes in each. The intent is to propagate bug fixes out to stable releases more rapidly and make upgrading stable releases less of an upheaval. This should give end users more flexibility in their choice of upgrade timing, and allow them easier assessment of the impact of upgrades. The current plan is for code freezes as follows

  • 5.8.3 23:59:59 GMT, Wednesday December 31st 2003

  • 5.8.4 23:59:59 GMT, Wednesday March 31st 2004

  • 5.8.5 23:59:59 GMT, Wednesday June 30th 2004

with the release following soon after, when testing is complete.

See Future Directions in the perl581delta manpage for more soothsaying.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/. There may also be information at http://www.perl.com/, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl583delta - what is new for perl v5.8.3

  • Incompatible Changes
  • Core Enhancements
  • Modules and Pragmata
  • Utility Changes
  • New Documentation
  • Installation and Configuration Improvements
  • Selected Bug Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Configuration and Building
  • Platform Specific Problems
  • Known Problems
  • Future Directions
  • Obituary
  • Reporting Bugs
  • SEE ALSO

NAME

perl583delta - what is new for perl v5.8.3

DESCRIPTION

This document describes differences between the 5.8.2 release and the 5.8.3 release.

If you are upgrading from an earlier release such as 5.6.1, first read the the perl58delta manpage, which describes differences between 5.6.0 and 5.8.0, and the the perl581delta manpage and the perl582delta manpage, which describe differences between 5.8.0, 5.8.1 and 5.8.2

Incompatible Changes

There are no changes incompatible with 5.8.2.

Core Enhancements

A SCALAR method is now available for tied hashes. This is called when a tied hash is used in scalar context, such as

    if (%tied_hash) {
        ...
    }

The old behaviour was that %tied_hash would return whatever would have been returned for that hash before the hash was tied (so usually 0). The new behaviour in the absence of a SCALAR method is to return TRUE if in the middle of an each iteration, and otherwise call FIRSTKEY to check if the hash is empty (making sure that a subsequent each will also begin by calling FIRSTKEY). Please see SCALAR in the perltie manpage for the full details and caveats.

Modules and Pragmata

CGI
Cwd
Digest
Digest::MD5
Encode
File::Spec
FindBin

A function again is provided to resolve problems where modules in different directories wish to use FindBin.

List::Util

You can now weaken references to read only values.

Math::BigInt
PodParser
Pod::Perldoc
POSIX
Unicode::Collate
Unicode::Normalize
Test::Harness
threads::shared

cond_wait has a new two argument form. cond_timedwait has been added.

Utility Changes

find2perl now assumes -print as a default action. Previously, it needed to be specified explicitly.

A new utility, prove, makes it easy to run an individual regression test at the command line. prove is part of Test::Harness, which users of earlier Perl versions can install from CPAN.

New Documentation

The documentation has been revised in places to produce more standard manpages.

The documentation for the special code blocks (BEGIN, CHECK, INIT, END) has been improved.

Installation and Configuration Improvements

Perl now builds on OpenVMS I64

Selected Bug Fixes

Using substr() on a UTF8 string could cause subsequent accesses on that string to return garbage. This was due to incorrect UTF8 offsets being cached, and is now fixed.

join() could return garbage when the same join() statement was used to process 8 bit data having earlier processed UTF8 data, due to the flags on that statement's temporary workspace not being reset correctly. This is now fixed.

$a .. $b will now work as expected when either $a or $b is undef

Using Unicode keys with tied hashes should now work correctly.

Reading $^E now preserves $!. Previously, the C code implementing $^E did not preserve errno, so reading $^E could cause errno and therefore $! to change unexpectedly.

Reentrant functions will (once more) work with C++. 5.8.2 introduced a bugfix which accidentally broke the compilation of Perl extensions written in C++

New or Changed Diagnostics

The fatal error "DESTROY created new reference to dead object" is now documented in the perldiag manpage.

Changed Internals

The hash code has been refactored to reduce source duplication. The external interface is unchanged, and aside from the bug fixes described above, there should be no change in behaviour.

hv_clear_placeholders is now part of the perl API

Some C macros have been tidied. In particular macros which create temporary local variables now name these variables more defensively, which should avoid bugs where names clash.

<signal.h> is now always included.

Configuration and Building

Configure now invokes callbacks regardless of the value of the variable they are called for. Previously callbacks were only invoked in the case $variable $define) branch. This change should only affect platform maintainers writing configuration hints files.

Platform Specific Problems

The regression test ext/threads/shared/t/wait.t fails on early RedHat 9 and HP-UX 10.20 due to bugs in their threading implementations. RedHat users should see https://rhn.redhat.com/errata/RHBA-2003-136.html and consider upgrading their glibc.

Known Problems

Detached threads aren't supported on Windows yet, as they may lead to memory access violation problems.

There is a known race condition opening scripts in suidperl. suidperl is neither built nor installed by default, and has been deprecated since perl 5.8.0. You are advised to replace use of suidperl with tools such as sudo ( http://www.courtesan.com/sudo/ )

We have a backlog of unresolved bugs. Dealing with bugs and bug reports is unglamorous work; not something ideally suited to volunteer labour, but that is all that we have.

The perl5 development team are implementing changes to help address this problem, which should go live in early 2004.

Future Directions

Code freeze for the next maintenance release (5.8.4) is on March 31st 2004, with release expected by mid April. Similarly 5.8.5's freeze will be at the end of June, with release by mid July.

Obituary

Iain 'Spoon' Truskett, Perl hacker, author of the perlreref manpage and contributor to CPAN, died suddenly on 29th December 2003, aged 24. He will be missed.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl584delta - what is new for perl v5.8.4

  • Incompatible Changes
  • Core Enhancements
    • Malloc wrapping
    • Unicode Character Database 4.0.1
    • suidperl less insecure
    • format
  • Modules and Pragmata
    • Updated modules
  • Performance Enhancements
  • Utility Changes
  • Installation and Configuration Improvements
  • Selected Bug Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Future Directions
  • Platform Specific Problems
  • Reporting Bugs
  • SEE ALSO

NAME

perl584delta - what is new for perl v5.8.4

DESCRIPTION

This document describes differences between the 5.8.3 release and the 5.8.4 release.

Incompatible Changes

Many minor bugs have been fixed. Scripts which happen to rely on previously erroneous behaviour will consider these fixes as incompatible changes :-) You are advised to perform sufficient acceptance testing on this release to satisfy yourself that this does not affect you, before putting this release into production.

The diagnostic output of Carp has been changed slightly, to add a space after the comma between arguments. This makes it much easier for tools such as web browsers to wrap it, but might confuse any automatic tools which perform detailed parsing of Carp output.

The internal dump output has been improved, so that non-printable characters such as newline and backspace are output in \x notation, rather than octal. This might just confuse non-robust tools which parse the output of modules such as Devel::Peek.

Core Enhancements

Malloc wrapping

Perl can now be built to detect attempts to assign pathologically large chunks of memory. Previously such assignments would suffer from integer wrap-around during size calculations causing a misallocation, which would crash perl, and could theoretically be used for "stack smashing" attacks. The wrapping defaults to enabled on platforms where we know it works (most AIX configurations, BSDi, Darwin, DEC OSF/1, FreeBSD, HP/UX, GNU Linux, OpenBSD, Solaris, VMS and most Win32 compilers) and defaults to disabled on other platforms.

Unicode Character Database 4.0.1

The copy of the Unicode Character Database included in Perl 5.8 has been updated to 4.0.1 from 4.0.0.

suidperl less insecure

Paul Szabo has analysed and patched suidperl to remove existing known insecurities. Currently there are no known holes in suidperl, but previous experience shows that we cannot be confident that these were the last. You may no longer invoke the set uid perl directly, so to preserve backwards compatibility with scripts that invoke #!/usr/bin/suidperl the only set uid binary is now sperl5.8.n (sperl5.8.4 for this release). suidperl is installed as a hard link to perl; both suidperl and perl will invoke sperl5.8.4 automatically the set uid binary, so this change should be completely transparent.

For new projects the core perl team would strongly recommend that you use dedicated, single purpose security tools such as sudo in preference to suidperl.

format

In addition to bug fixes, format's features have been enhanced. See the perlform manpage

Modules and Pragmata

The (mis)use of /tmp in core modules and documentation has been tidied up. Some modules available both within the perl core and independently from CPAN ("dual-life modules") have not yet had these changes applied; the changes will be integrated into future stable perl releases as the modules are updated on CPAN.

Updated modules

Attribute::Handlers
B
Benchmark
CGI
Carp
Cwd
Exporter
File::Find
IO
IPC::Open3
Local::Maketext
Math::BigFloat
Math::BigInt
Math::BigRat
MIME::Base64
ODBM_File
POSIX
Shell
Socket

There is experimental support for Linux abstract Unix domain sockets.

Storable
Switch

Synced with its CPAN version 2.10

Sys::Syslog

syslog() can now use numeric constants for facility names and priorities, in addition to strings.

Term::ANSIColor
Time::HiRes
Unicode::UCD
Win32

Win32.pm/Win32.xs has moved from the libwin32 module to core Perl

base
open
threads

Detached threads are now also supported on Windows.

utf8

Performance Enhancements

  • Accelerated Unicode case mappings (/i, lc, uc, etc).

  • In place sort optimised (eg @a = sort @a)

  • Unnecessary assignment optimised away in

      my $s = undef;
  my @a = ();
  my %h = ();

  • Optimised map in scalar context

Utility Changes

The Perl debugger (lib/perl5db.pl) can now save all debugger commands for sourcing later, and can display the parent inheritance tree of a given class.

Installation and Configuration Improvements

The build process on both VMS and Windows has had several minor improvements made. On Windows Borland's C compiler can now compile perl with PerlIO and/or USE_LARGE_FILES enabled.

perl.exe on Windows now has a "Camel" logo icon. The use of a camel with the topic of Perl is a trademark of O'Reilly and Associates Inc., and is used with their permission (ie distribution of the source, compiling a Windows executable from it, and using that executable locally). Use of the supplied camel for anything other than a perl executable's icon is specifically not covered, and anyone wishing to redistribute perl binaries with the icon should check directly with O'Reilly beforehand.

Perl should build cleanly on Stratus VOS once more.

Selected Bug Fixes

More utf8 bugs fixed, notably in how chomp, chop, send, and syswrite and interact with utf8 data. Concatenation now works correctly when use bytes; is in scope.

Pragmata are now correctly propagated into (?{...}) constructions in regexps. Code such as

   my $x = qr{ ... (??{ $x }) ... };

will now (correctly) fail under use strict. (As the inner $x is and has always referred to $::x)

The "const in void context" warning has been suppressed for a constant in an optimised-away boolean expression such as 5 || print;

perl -i could fchmod(stdin) by mistake. This is serious if stdin is attached to a terminal, and perl is running as root. Now fixed.

New or Changed Diagnostics

Carp and the internal diagnostic routines used by Devel::Peek have been made clearer, as described in Incompatible Changes

Changed Internals

Some bugs have been fixed in the hash internals. Restricted hashes and their place holders are now allocated and deleted at slightly different times, but this should not be visible to user code.

Future Directions

Code freeze for the next maintenance release (5.8.5) will be on 30th June 2004, with release by mid July.

Platform Specific Problems

This release is known not to build on Windows 95.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl585delta - what is new for perl v5.8.5

  • Incompatible Changes
  • Core Enhancements
  • Modules and Pragmata
  • Utility Changes
    • Perl's debugger
    • h2ph
  • Installation and Configuration Improvements
  • Selected Bug Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Known Problems
  • Platform Specific Problems
  • Reporting Bugs
  • SEE ALSO

NAME

perl585delta - what is new for perl v5.8.5

DESCRIPTION

This document describes differences between the 5.8.4 release and the 5.8.5 release.

Incompatible Changes

There are no changes incompatible with 5.8.4.

Core Enhancements

Perl's regular expression engine now contains support for matching on the intersection of two Unicode character classes. You can also now refer to user-defined character classes from within other user defined character classes.

Modules and Pragmata

  • Carp improved to work nicely with Safe. Carp's message reporting should now be anomaly free - it will always print out line number information.

  • CGI upgraded to version 3.05

  • charnames now avoids clobbering $_

  • Digest upgraded to version 1.08

  • Encode upgraded to version 2.01

  • FileCache upgraded to version 1.04

  • libnet upgraded to version 1.19

  • Pod::Parser upgraded to version 1.28

  • Pod::Perldoc upgraded to version 3.13

  • Pod::LaTeX upgraded to version 0.57

  • Safe now works properly with Carp

  • Scalar-List-Utils upgraded to version 1.14

  • Shell's documentation has been re-written, and its historical partial auto-quoting of command arguments can now be disabled.

  • Test upgraded to version 1.25

  • Test::Harness upgraded to version 2.42

  • Time::Local upgraded to version 1.10

  • Unicode::Collate upgraded to version 0.40

  • Unicode::Normalize upgraded to version 0.30

Utility Changes

Perl's debugger

The debugger can now emulate stepping backwards, by restarting and rerunning all bar the last command from a saved command history.

h2ph

h2ph is now able to understand a very limited set of C inline functions -- basically, the inline functions that look like CPP macros. This has been introduced to deal with some of the headers of the newest versions of the glibc. The standard warning still applies; to quote h2ph's documentation, you may need to dicker with the files produced.

Installation and Configuration Improvements

Perl 5.8.5 should build cleanly from source on LynxOS.

Selected Bug Fixes

  • The in-place sort optimisation introduced in 5.8.4 had a bug. For example, in code such as

        @a = sort ($b, @a)

    the result would omit the value $b. This is now fixed.

  • The optimisation for unnecessary assignments introduced in 5.8.4 could give spurious warnings. This has been fixed.

  • Perl should now correctly detect and read BOM-marked and (BOMless) UTF-16 scripts of either endianness.

  • Creating a new thread when weak references exist was buggy, and would often cause warnings at interpreter destruction time. The known bug is now fixed.

  • Several obscure bugs involving manipulating Unicode strings with substr have been fixed.

  • Previously if Perl's file globbing function encountered a directory that it did not have permission to open it would return immediately, leading to unexpected truncation of the list of results. This has been fixed, to be consistent with Unix shells' globbing behaviour.

  • Thread creation time could vary wildly between identical runs. This was caused by a poor hashing algorithm in the thread cloning routines, which has now been fixed.

  • The internals of the ithreads implementation were not checking if OS-level thread creation had failed. threads->create() now returns undef in if thread creation fails instead of crashing perl.

New or Changed Diagnostics

  • Perl -V has several improvements

    • correctly outputs local patch names that contain embedded code snippets or other characters that used to confuse it.

    • arguments to -V that look like regexps will give multiple lines of output.

    • a trailing colon suppresses the linefeed and ';' terminator, allowing embedding of queries into shell commands.

    • a leading colon removes the 'name=' part of the response, allowing mapping to any name.

  • When perl fails to find the specified script, it now outputs a second line suggesting that the user use the -S flag:

        $ perl5.8.5 missing.pl
    Can't open perl script "missing.pl": No such file or directory.
    Use -S to search $PATH for it.

Changed Internals

The Unicode character class files used by the regular expression engine are now built at build time from the supplied Unicode consortium data files, instead of being shipped prebuilt. This makes the compressed Perl source tarball about 200K smaller. A side effect is that the layout of files inside lib/unicore has changed.

Known Problems

The regression test t/uni/class.t is now performing considerably more tests, and can take several minutes to run even on a fast machine.

Platform Specific Problems

This release is known not to build on Windows 95.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl586delta - what is new for perl v5.8.6

  • Incompatible Changes
  • Core Enhancements
  • Modules and Pragmata
  • Utility Changes
  • Performance Enhancements
  • Selected Bug Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • New Tests
  • Reporting Bugs
  • SEE ALSO

NAME

perl586delta - what is new for perl v5.8.6

DESCRIPTION

This document describes differences between the 5.8.5 release and the 5.8.6 release.

Incompatible Changes

There are no changes incompatible with 5.8.5.

Core Enhancements

The perl interpreter is now more tolerant of UTF-16-encoded scripts.

On Win32, Perl can now use non-IFS compatible LSPs, which allows Perl to work in conjunction with firewalls such as McAfee Guardian. For full details see the file README.win32, particularly if you're running Win95.

Modules and Pragmata

  • With the base pragma, an intermediate class with no fields used to messes up private fields in the base class. This has been fixed.

  • Cwd upgraded to version 3.01 (as part of the new PathTools distribution)

  • Devel::PPPort upgraded to version 3.03

  • File::Spec upgraded to version 3.01 (as part of the new PathTools distribution)

  • Encode upgraded to version 2.08

  • ExtUtils::MakeMaker remains at version 6.17, as later stable releases currently available on CPAN have some issues with core modules on some core platforms.

  • I18N::LangTags upgraded to version 0.35

  • Math::BigInt upgraded to version 1.73

  • Math::BigRat upgraded to version 0.13

  • MIME::Base64 upgraded to version 3.05

  • POSIX::sigprocmask function can now retrieve the current signal mask without also setting it.

  • Time::HiRes upgraded to version 1.65

Utility Changes

Perl has a new -dt command-line flag, which enables threads support in the debugger.

Performance Enhancements

reverse sort ... is now optimized to sort in reverse, avoiding the generation of a temporary intermediate list.

for (reverse @foo) now iterates in reverse, avoiding the generation of a temporary reversed list.

Selected Bug Fixes

The regexp engine is now more robust when given invalid utf8 input, as is sometimes generated by buggy XS modules.

foreach on threads::shared array used to be able to crash Perl. This bug has now been fixed.

A regexp in STDOUT's destructor used to coredump, because the regexp pad was already freed. This has been fixed.

goto & is now more robust - bugs in deep recursion and chained goto & have been fixed.

Using delete on an array no longer leaks memory. A pop of an item from a shared array reference no longer causes a leak.

eval_sv() failing a taint test could corrupt the stack - this has been fixed.

On platforms with 64 bit pointers numeric comparison operators used to erroneously compare the addresses of references that are overloaded, rather than using the overloaded values. This has been fixed.

read into a UTF8-encoded buffer with an offset off the end of the buffer no longer mis-calculates buffer lengths.

Although Perl has promised since version 5.8 that sort() would be stable, the two cases sort {$b cmp $a} and sort {$b <=> $a} could produce non-stable sorts. This is corrected in perl5.8.6.

Localising $^D no longer generates a diagnostic message about valid -D flags.

New or Changed Diagnostics

For -t and -T, Too late for "-T" option has been changed to the more informative "-T" is on the #! line, it must also be used on the command line

Changed Internals

From now on all applications embedding perl will behave as if perl were compiled with -DPERL_USE_SAFE_PUTENV. See "Environment access" in the INSTALL file for details.

Most C source files now have comments at the top explaining their purpose, which should help anyone wishing to get an overview of the implementation.

New Tests

There are significantly more tests for the B suite of modules.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perldelta - what is new for perl v5.8.7

  • Incompatible Changes
  • Core Enhancements
    • Unicode Character Database 4.1.0
    • suidperl less insecure
    • Optional site customization script
    • Config.pm is now much smaller.
  • Modules and Pragmata
  • Utility Changes
    • find2perl enhancements
  • Performance Enhancements
  • Installation and Configuration Improvements
  • Selected Bug Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Known Problems
  • Platform Specific Problems
  • Reporting Bugs
  • SEE ALSO

NAME

perldelta - what is new for perl v5.8.7

DESCRIPTION

This document describes differences between the 5.8.6 release and the 5.8.7 release.

Incompatible Changes

There are no changes incompatible with 5.8.6.

Core Enhancements

Unicode Character Database 4.1.0

The copy of the Unicode Character Database included in Perl 5.8 has been updated to 4.1.0 from 4.0.1. See http://www.unicode.org/versions/Unicode4.1.0/#NotableChanges for the notable changes.

suidperl less insecure

A pair of exploits in suidperl involving debugging code have been closed.

For new projects the core perl team strongly recommends that you use dedicated, single purpose security tools such as sudo in preference to suidperl.

Optional site customization script

The perl interpreter can be built to allow the use of a site customization script. By default this is not enabled, to be consistent with previous perl releases. To use this, add -Dusesitecustomize to the command line flags when running the Configure script. See also -f in the perlrun manpage.

Config.pm is now much smaller.

Config.pm is now about 3K rather than 32K, with the infrequently used code and %Config values loaded on demand. This is transparent to the programmer, but means that most code will save parsing and loading 29K of script (for example, code that uses File::Find).

Modules and Pragmata

  • B upgraded to version 1.09

  • base upgraded to version 2.07

  • bignum upgraded to version 0.17

  • bytes upgraded to version 1.02

  • Carp upgraded to version 1.04

  • CGI upgraded to version 3.10

  • Class::ISA upgraded to version 0.33

  • Data::Dumper upgraded to version 2.121_02

  • DB_File upgraded to version 1.811

  • Devel::PPPort upgraded to version 3.06

  • Digest upgraded to version 1.10

  • Encode upgraded to version 2.10

  • FileCache upgraded to version 1.05

  • File::Path upgraded to version 1.07

  • File::Temp upgraded to version 0.16

  • IO::File upgraded to version 1.11

  • IO::Socket upgraded to version 1.28

  • Math::BigInt upgraded to version 1.77

  • Math::BigRat upgraded to version 0.15

  • overload upgraded to version 1.03

  • PathTools upgraded to version 3.05

  • Pod::HTML upgraded to version 1.0503

  • Pod::Perldoc upgraded to version 3.14

  • Pod::LaTeX upgraded to version 0.58

  • Pod::Parser upgraded to version 1.30

  • Symbol upgraded to version 1.06

  • Term::ANSIColor upgraded to version 1.09

  • Test::Harness upgraded to version 2.48

  • Test::Simple upgraded to version 0.54

  • Text::Wrap upgraded to version 2001.09293, to fix a bug when wrap() was called with a non-space separator.

  • threads::shared upgraded to version 0.93

  • Time::HiRes upgraded to version 1.66

  • Time::Local upgraded to version 1.11

  • Unicode::Normalize upgraded to version 0.32

  • utf8 upgraded to version 1.05

  • Win32 upgraded to version 0.24, which provides Win32::GetFileVersion

Utility Changes

find2perl enhancements

find2perl has new options -iname, -path and -ipath.

Performance Enhancements

The internal pointer mapping hash used during ithreads cloning now uses an arena for memory allocation. In tests this reduced ithreads cloning time by about 10%.

Installation and Configuration Improvements

  • The Win32 "dmake" makefile.mk has been updated to make it compatible with the latest versions of dmake.

  • PERL_MALLOC, DEBUG_MSTATS, PERL_HASH_SEED_EXPLICIT and NO_HASH_SEED should now work in Win32 makefiles.

Selected Bug Fixes

  • The socket() function on Win32 has been fixed so that it is able to use transport providers which specify a protocol of 0 (meaning any protocol is allowed) once more. (This was broken in 5.8.6, and typically caused the use of ICMP sockets to fail.)

  • Another obscure bug involving substr and UTF-8 caused by bad internal offset caching has been identified and fixed.

  • A bug involving the loading of UTF-8 tables by the regexp engine has been fixed - code such as "\x{100}" =~ /[[:print:]]/ will no longer give corrupt results.

  • Case conversion operations such as uc on a long Unicode string could exhaust memory. This has been fixed.

  • index/rindex were buggy for some combinations of Unicode and non-Unicode data. This has been fixed.

  • read (and presumably sysread) would expose the UTF-8 internals when reading from a byte oriented file handle into a UTF-8 scalar. This has been fixed.

  • Several pack/unpack bug fixes:

    • Checksums with b or B formats were broken.

    • unpack checksums could overflow with the C format.

    • U0 and C0 are now scoped to () pack sub-templates.

    • Counted length prefixes now don't change C0/U0 mode.

    • pack Z0 used to destroy the preceding character.

    • P/p pack formats used to only recognise literal undef

  • Using closures with ithreads could cause perl to crash. This was due to failure to correctly lock internal OP structures, and has been fixed.

  • The return value of close now correctly reflects any file errors that occur while flushing the handle's data, instead of just giving failure if the actual underlying file close operation failed.

  • not() || 1 used to segfault. not() now behaves like not(0), which was the pre 5.6.0 behaviour.

  • h2ph has various enhancements to cope with constructs in header files that used to result in incorrect or invalid output.

New or Changed Diagnostics

There is a new taint error, "%ENV is aliased to %s". This error is thrown when taint checks are enabled and when *ENV has been aliased, so that %ENV has no env-magic anymore and hence the environment cannot be verified as taint-free.

The internals of pack and unpack have been updated. All legitimate templates should work as before, but there may be some changes in the error reported for complex failure cases. Any behaviour changes for non-error cases are bugs, and should be reported.

Changed Internals

There has been a fair amount of refactoring of the C source code, partly to make it tidier and more maintainable. The resulting object code and the perl binary may well be smaller than 5.8.6, and hopefully faster in some cases, but apart from this there should be no user-detectable changes.

${^UTF8LOCALE} has been added to give perl space access to PL_utf8locale.

The size of the arenas used to allocate SV heads and most SV bodies can now be changed at compile time. The old size was 1008 bytes, the new default size is 4080 bytes.

Known Problems

Unicode strings returned from overloaded operators can be buggy. This is a long standing bug reported since 5.8.6 was released, but we do not yet have a suitable fix for it.

Platform Specific Problems

On UNICOS, lib/Math/BigInt/t/bigintc.t hangs burning CPU. ext/B/t/bytecode.t and ext/Socket/t/socketpair.t both fail tests. These are unlikely to be resolved, as our valiant UNICOS porter's last Cray is being decommissioned.

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org. There may also be information at http://www.perl.org, the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. You can browse and search the Perl 5 bugs at http://bugs.perl.org/

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.


perl58delta - what is new for perl v5.8.0

  • Highlights In 5.8.0
  • Incompatible Changes
    • Binary Incompatibility
    • 64-bit platforms and malloc
    • AIX Dynaloading
    • Attributes for my variables now handled at run-time
    • Socket Extension Dynamic in VMS
    • IEEE-format Floating Point Default on OpenVMS Alpha
    • New Unicode Semantics (no more use utf8, almost)
    • New Unicode Properties
    • REF(...) Instead Of SCALAR(...)
    • pack/unpack D/F recycled
    • glob() now returns filenames in alphabetical order
    • Deprecations
  • Core Enhancements
    • Unicode Overhaul
    • PerlIO is Now The Default
    • ithreads
    • Restricted Hashes
    • Safe Signals
    • Understanding of Numbers
    • Arrays now always interpolate into double-quoted strings [561]
    • Miscellaneous Changes
  • Modules and Pragmata
    • New Modules and Pragmata
    • Updated And Improved Modules and Pragmata
  • Utility Changes
  • New Documentation
  • Performance Enhancements
  • Installation and Configuration Improvements
    • Generic Improvements
    • New Or Improved Platforms
  • Selected Bug Fixes
    • Platform Specific Changes and Fixes
  • New or Changed Diagnostics
  • Changed Internals
  • Security Vulnerability Closed [561]
  • New Tests
  • Known Problems
    • The Compiler Suite Is Still Very Experimental
    • Localising Tied Arrays and Hashes Is Broken
    • Building Extensions Can Fail Because Of Largefiles
    • Modifying $_ Inside for(..)
    • mod_perl 1.26 Doesn't Build With Threaded Perl
    • lib/ftmp-security tests warn 'system possibly insecure'
    • libwww-perl (LWP) fails base/date #51
    • PDL failing some tests
    • Perl_get_sv
    • Self-tying Problems
    • ext/threads/t/libc
    • Failure of Thread (5.005-style) tests
    • Timing problems
    • Tied/Magical Array/Hash Elements Do Not Autovivify
    • Unicode in package/class and subroutine names does not work
  • Platform Specific Problems
    • AIX
    • Alpha systems with old gccs fail several tests
    • AmigaOS
    • BeOS
    • Cygwin "unable to remap"
    • Cygwin ndbm tests fail on FAT
    • DJGPP Failures
    • FreeBSD built with ithreads coredumps reading large directories
    • FreeBSD Failing locale Test 117 For ISO 8859-15 Locales
    • IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5
    • HP-UX lib/posix Subtest 9 Fails When LP64-Configured
    • Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint
    • Linux With Sfio Fails op/misc Test 48
    • Mac OS X
    • Mac OS X dyld undefined symbols
    • OS/2 Test Failures
    • op/sprintf tests 91, 129, and 130
    • SCO
    • Solaris 2.5
    • Solaris x86 Fails Tests With -Duse64bitint
    • SUPER-UX (NEC SX)
    • Term::ReadKey not working on Win32
    • UNICOS/mk
    • UTS
    • VOS (Stratus)
    • VMS
    • Win32
    • XML::Parser not working
    • z/OS (OS/390)
    • Unicode Support on EBCDIC Still Spotty
    • Seen In Perl 5.7 But Gone Now
  • Reporting Bugs
  • SEE ALSO
  • HISTORY

NAME

perl58delta - what is new for perl v5.8.0

DESCRIPTION

This document describes differences between the 5.6.0 release and the 5.8.0 release.

Many of the bug fixes in 5.8.0 were already seen in the 5.6.1 maintenance release since the two releases were kept closely coordinated (while 5.8.0 was still called 5.7.something).

Changes that were integrated into the 5.6.1 release are marked [561]. Many of these changes have been further developed since 5.6.1 was released, those are marked [561+].

You can see the list of changes in the 5.6.1 release (both from the 5.005_03 release and the 5.6.0 release) by reading the perl561delta manpage.

Highlights In 5.8.0

  • Better Unicode support

  • New IO Implementation

  • New Thread Implementation

  • Better Numeric Accuracy

  • Safe Signals

  • Many New Modules

  • More Extensive Regression Testing

Incompatible Changes

Binary Incompatibility

Perl 5.8 is not binary compatible with earlier releases of Perl.

You have to recompile your XS modules.

(Pure Perl modules should continue to work.)

The major reason for the discontinuity is the new IO architecture called PerlIO. PerlIO is the default configuration because without it many new features of Perl 5.8 cannot be used. In other words: you just have to recompile your modules containing XS code, sorry about that.

In future releases of Perl, non-PerlIO aware XS modules may become completely unsupported. This shouldn't be too difficult for module authors, however: PerlIO has been designed as a drop-in replacement (at the source code level) for the stdio interface.

Depending on your platform, there are also other reasons why we decided to break binary compatibility, please read on.

64-bit platforms and malloc

If your pointers are 64 bits wide, the Perl malloc is no longer being used because it does not work well with 8-byte pointers. Also, usually the system mallocs on such platforms are much better optimized for such large memory models than the Perl malloc. Some memory-hungry Perl applications like the PDL don't work well with Perl's malloc. Finally, other applications than Perl (such as mod_perl) tend to prefer the system malloc. Such platforms include Alpha and 64-bit HPPA, MIPS, PPC, and Sparc.

AIX Dynaloading

The AIX dynaloading now uses in AIX releases 4.3 and newer the native dlopen interface of AIX instead of the old emulated interface. This change will probably break backward compatibility with compiled modules. The change was made to make Perl more compliant with other applications like mod_perl which are using the AIX native interface.

Attributes for my variables now handled at run-time

The my EXPR : ATTRS syntax now applies variable attributes at run-time. (Subroutine and our variables still get attributes applied at compile-time.) See the attributes manpage for additional details. In particular, however, this allows variable attributes to be useful for tie interfaces, which was a deficiency of earlier releases. Note that the new semantics doesn't work with the Attribute::Handlers module (as of version 0.76).

Socket Extension Dynamic in VMS

The Socket extension is now dynamically loaded instead of being statically built in. This may or may not be a problem with ancient TCP/IP stacks of VMS: we do not know since we weren't able to test Perl in such configurations.

IEEE-format Floating Point Default on OpenVMS Alpha

Perl now uses IEEE format (T_FLOAT) as the default internal floating point format on OpenVMS Alpha, potentially breaking binary compatibility with external libraries or existing data. G_FLOAT is still available as a configuration option. The default on VAX (D_FLOAT) has not changed.

New Unicode Semantics (no more use utf8, almost)

Previously in Perl 5.6 to use Unicode one would say "use utf8" and then the operations (like string concatenation) were Unicode-aware in that lexical scope.

This was found to be an inconvenient interface, and in Perl 5.8 the Unicode model has completely changed: now the "Unicodeness" is bound to the data itself, and for most of the time "use utf8" is not needed at all. The only remaining use of "use utf8" is when the Perl script itself has been written in the UTF-8 encoding of Unicode. (UTF-8 has not been made the default since there are many Perl scripts out there that are using various national eight-bit character sets, which would be illegal in UTF-8.)

See the perluniintro manpage for the explanation of the current model, and the utf8 manpage for the current use of the utf8 pragma.

New Unicode Properties

Unicode scripts are now supported. Scripts are similar to (and superior to) Unicode blocks. The difference between scripts and blocks is that scripts are the glyphs used by a language or a group of languages, while the blocks are more artificial groupings of (mostly) 256 characters based on the Unicode numbering.

In general, scripts are more inclusive, but not universally so. For example, while the script Latin includes all the Latin characters and their various diacritic-adorned versions, it does not include the various punctuation or digits (since they are not solely Latin).

A number of other properties are now supported, including \p{L&}, \p{Any} \p{Assigned}, \p{Unassigned}, \p{Blank} [561] and \p{SpacePerl} [561] (along with their \P{...} versions, of course). See the perlunicode manpage for details, and more additions.

The In or Is prefix to names used with the \p{...} and \P{...} are now almost always optional. The only exception is that a In prefix is required to signify a Unicode block when a block name conflicts with a script name. For example, \p{Tibetan} refers to the script, while \p{InTibetan} refers to the block. When there is no name conflict, you can omit the In from the block name (e.g. \p{BraillePatterns}), but to be safe, it's probably best to always use the In).

REF(...) Instead Of SCALAR(...)

A reference to a reference now stringifies as "REF(0x81485ec)" instead of "SCALAR(0x81485ec)" in order to be more consistent with the return value of ref().

pack/unpack D/F recycled

The undocumented pack/unpack template letters D/F have been recycled for better use: now they stand for long double (if supported by the platform) and NV (Perl internal floating point type). (They used to be aliases for d/f, but you never knew that.)

glob() now returns filenames in alphabetical order

The list of filenames from glob() (or <...>) is now by default sorted alphabetically to be csh-compliant (which is what happened before in most UNIX platforms). (bsd_glob() does still sort platform natively, ASCII or EBCDIC, unless GLOB_ALPHASORT is specified.) [561]

Deprecations

  • The semantics of bless(REF, REF) were unclear and until someone proves it to make some sense, it is forbidden.

  • The obsolete chat2 library that should never have been allowed to escape the laboratory has been decommissioned.

  • Using chdir("") or chdir(undef) instead of explicit chdir() is doubtful. A failure (think chdir(some_function()) can lead into unintended chdir() to the home directory, therefore this behaviour is deprecated.

  • The builtin dump() function has probably outlived most of its usefulness. The core-dumping functionality will remain in future available as an explicit call to CORE::dump(), but in future releases the behaviour of an unqualified dump() call may change.

  • The very dusty examples in the eg/ directory have been removed. Suggestions for new shiny examples welcome but the main issue is that the examples need to be documented, tested and (most importantly) maintained.

  • The (bogus) escape sequences \8 and \9 now give an optional warning ("Unrecognized escape passed through"). There is no need to \-escape any \w character.

  • The *glob{FILEHANDLE} is deprecated, use *glob{IO} instead.

  • The package; syntax (package without an argument) has been deprecated. Its semantics were never that clear and its implementation even less so. If you have used that feature to disallow all but fully qualified variables, use strict; instead.

  • The unimplemented POSIX regex features [[.cc.]] and [[=c=]] are still recognised but now cause fatal errors. The previous behaviour of ignoring them by default and warning if requested was unacceptable since it, in a way, falsely promised that the features could be used.

  • In future releases, non-PerlIO aware XS modules may become completely unsupported. Since PerlIO is a drop-in replacement for stdio at the source code level, this shouldn't be that drastic a change.

  • Previous versions of perl and some readings of some sections of Camel III implied that the :raw "discipline" was the inverse of :crlf. Turning off "clrfness" is no longer enough to make a stream truly binary. So the PerlIO :raw layer (or "discipline", to use the Camel book's older terminology) is now formally defined as being equivalent to binmode(FH) - which is in turn defined as doing whatever is necessary to pass each byte as-is without any translation. In particular binmode(FH) - and hence :raw - will now turn off both CRLF and UTF-8 translation and remove other layers (e.g. :encoding()) which would modify byte stream.

  • The current user-visible implementation of pseudo-hashes (the weird use of the first array element) is deprecated starting from Perl 5.8.0 and will be removed in Perl 5.10.0, and the feature will be implemented differently. Not only is the current interface rather ugly, but the current implementation slows down normal array and hash use quite noticeably. The fields pragma interface will remain available. The restricted hashes interface is expected to be the replacement interface (see the Hash::Util manpage). If your existing programs depends on the underlying implementation, consider using the Class::PseudoHash manpage from CPAN.

  • The syntaxes @a->[...] and %h->{...} have now been deprecated.

  • After years of trying, suidperl is considered to be too complex to ever be considered truly secure. The suidperl functionality is likely to be removed in a future release.

  • The 5.005 threads model (module Thread) is deprecated and expected to be removed in Perl 5.10. Multithreaded code should be migrated to the new ithreads model (see the threads manpage, the threads::shared manpage and the perlthrtut manpage).

  • The long deprecated uppercase aliases for the string comparison operators (EQ, NE, LT, LE, GE, GT) have now been removed.

  • The tr///C and tr///U features have been removed and will not return; the interface was a mistake. Sorry about that. For similar functionality, see pack('U0', ...) and pack('C0', ...). [561]

  • Earlier Perls treated "sub foo (@bar)" as equivalent to "sub foo (@)". The prototypes are now checked better at compile-time for invalid syntax. An optional warning is generated ("Illegal character in prototype...") but this may be upgraded to a fatal error in a future release.

  • The exec LIST and system LIST operations now produce warnings on tainted data and in some future release they will produce fatal errors.

  • The existing behaviour when localising tied arrays and hashes is wrong, and will be changed in a future release, so do not rely on the existing behaviour. See Localising Tied Arrays and Hashes Is Broken.

Core Enhancements

Unicode Overhaul

Unicode in general should be now much more usable than in Perl 5.6.0 (or even in 5.6.1). Unicode can be used in hash keys, Unicode in regular expressions should work now, Unicode in tr/// should work now, Unicode in I/O should work now. See the perluniintro manpage for introduction and the perlunicode manpage for details.

  • The Unicode Character Database coming with Perl has been upgraded to Unicode 3.2.0. For more information, see http://www.unicode.org/ . [561+] (5.6.1 has UCD 3.0.1.)

  • For developers interested in enhancing Perl's Unicode capabilities: almost all the UCD files are included with the Perl distribution in the lib/unicore subdirectory. The most notable omission, for space considerations, is the Unihan database.

  • The properties \p{Blank} and \p{SpacePerl} have been added. "Blank" is like C isblank(), that is, it contains only "horizontal whitespace" (the space character is, the newline isn't), and the "SpacePerl" is the Unicode equivalent of \s (\p{Space} isn't, since that includes the vertical tabulator character, whereas \s doesn't.)

    See "New Unicode Properties" earlier in this document for additional information on changes with Unicode properties.

PerlIO is Now The Default

  • IO is now by default done via PerlIO rather than system's "stdio". PerlIO allows "layers" to be "pushed" onto a file handle to alter the handle's behaviour. Layers can be specified at open time via 3-arg form of open:

       open($fh,'>:crlf :utf8', $path) || ...

    or on already opened handles via extended binmode:

       binmode($fh,':encoding(iso-8859-7)');

    The built-in layers are: unix (low level read/write), stdio (as in previous Perls), perlio (re-implementation of stdio buffering in a portable manner), crlf (does CRLF <=> "\n" translation as on Win32, but available on any platform). A mmap layer may be available if platform supports it (mostly UNIXes).

    Layers to be applied by default may be specified via the 'open' pragma.

    See Installation and Configuration Improvements for the effects of PerlIO on your architecture name.

  • If your platform supports fork(), you can use the list form of open for pipes. For example:

        open KID_PS, "-|", "ps", "aux" or die $!;

    forks the ps(1) command (without spawning a shell, as there are more than three arguments to open()), and reads its standard output via the KID_PS filehandle. See the perlipc manpage.

  • File handles can be marked as accepting Perl's internal encoding of Unicode (UTF-8 or UTF-EBCDIC depending on platform) by a pseudo layer ":utf8" :

       open($fh,">:utf8","Uni.txt");

    Note for EBCDIC users: the pseudo layer ":utf8" is erroneously named for you since it's not UTF-8 what you will be getting but instead UTF-EBCDIC. See the perlunicode manpage, the utf8 manpage, and http://www.unicode.org/unicode/reports/tr16/ for more information. In future releases this naming may change. See the perluniintro manpage for more information about UTF-8.

  • If your environment variables (LC_ALL, LC_CTYPE, LANG) look like you want to use UTF-8 (any of the variables match /utf-?8/i), your STDIN, STDOUT, STDERR handles and the default open layer (see the open manpage) are marked as UTF-8. (This feature, like other new features that combine Unicode and I/O, work only if you are using PerlIO, but that's the default.)

    Note that after this Perl really does assume that everything is UTF-8: for example if some input handle is not, Perl will probably very soon complain about the input data like this "Malformed UTF-8 ..." since any old eight-bit data is not legal UTF-8.

    Note for code authors: if you want to enable your users to use UTF-8 as their default encoding but in your code still have eight-bit I/O streams (such as images or zip files), you need to explicitly open() or binmode() with :bytes (see open in the perlfunc manpage and binmode in the perlfunc manpage), or you can just use binmode(FH) (nice for pre-5.8.0 backward compatibility).

  • File handles can translate character encodings from/to Perl's internal Unicode form on read/write via the ":encoding()" layer.

  • File handles can be opened to "in memory" files held in Perl scalars via:

       open($fh,'>', \$variable) || ...

  • Anonymous temporary files are available without need to 'use FileHandle' or other module via

       open($fh,"+>", undef) || ...

    That is a literal undef, not an undefined value.

ithreads

The new interpreter threads ("ithreads" for short) implementation of multithreading, by Arthur Bergman, replaces the old "5.005 threads" implementation. In the ithreads model any data sharing between threads must be explicit, as opposed to the model where data sharing was implicit. See the threads manpage and the threads::shared manpage, and the perlthrtut manpage.

As a part of the ithreads implementation Perl will also use any necessary and detectable reentrant libc interfaces.

Restricted Hashes

A restricted hash is restricted to a certain set of keys, no keys outside the set can be added. Also individual keys can be restricted so that the key cannot be deleted and the value cannot be changed. No new syntax is involved: the Hash::Util module is the interface.

Safe Signals

Perl used to be fragile in that signals arriving at inopportune moments could corrupt Perl's internal state. Now Perl postpones handling of signals until it's safe (between opcodes).

This change may have surprising side effects because signals no longer interrupt Perl instantly. Perl will now first finish whatever it was doing, like finishing an internal operation (like sort()) or an external operation (like an I/O operation), and only then look at any arrived signals (and before starting the next operation). No more corrupt internal state since the current operation is always finished first, but the signal may take more time to get heard. Note that breaking out from potentially blocking operations should still work, though.

Understanding of Numbers

In general a lot of fixing has happened in the area of Perl's understanding of numbers, both integer and floating point. Since in many systems the standard number parsing functions like strtoul() and atof() seem to have bugs, Perl tries to work around their deficiencies. This results hopefully in more accurate numbers.

Perl now tries internally to use integer values in numeric conversions and basic arithmetics (+ - * /) if the arguments are integers, and tries also to keep the results stored internally as integers. This change leads to often slightly faster and always less lossy arithmetics. (Previously Perl always preferred floating point numbers in its math.)

Arrays now always interpolate into double-quoted strings [561]

In double-quoted strings, arrays now interpolate, no matter what. The behavior in earlier versions of perl 5 was that arrays would interpolate into strings if the array had been mentioned before the string was compiled, and otherwise Perl would raise a fatal compile-time error. In versions 5.000 through 5.003, the error was

        Literal @example now requires backslash

In versions 5.004_01 through 5.6.0, the error was

        In string, @example now must be written as \@example

The idea here was to get people into the habit of writing "fred\@example.com" when they wanted a literal @ sign, just as they have always written "Give me back my \$5" when they wanted a literal $ sign.

Starting with 5.6.1, when Perl now sees an @ sign in a double-quoted string, it always attempts to interpolate an array, regardless of whether or not the array has been used or declared already. The fatal error has been downgraded to an optional warning:

        Possible unintended interpolation of @example in string

This warns you that "fred@example.com" is going to turn into fred.com if you don't backslash the @. See http://www.plover.com/~mjd/perl/at-error.html for more details about the history here.

Miscellaneous Changes

  • AUTOLOAD is now lvaluable, meaning that you can add the :lvalue attribute to AUTOLOAD subroutines and you can assign to the AUTOLOAD return value.

  • The $Config{byteorder} (and corresponding BYTEORDER in config.h) was previously wrong in platforms if sizeof(long) was 4, but sizeof(IV) was 8. The byteorder was only sizeof(long) bytes long (1234 or 4321), but now it is correctly sizeof(IV) bytes long, (12345678 or 87654321). (This problem didn't affect Windows platforms.)

    Also, $Config{byteorder} is now computed dynamically--this is more robust with "fat binaries" where an executable image contains binaries for more than one binary platform, and when cross-compiling.

  • perl -d:Module=arg,arg,arg now works (previously one couldn't pass in multiple arguments.)

  • do followed by a bareword now ensures that this bareword isn't a keyword (to avoid a bug where do q(foo.pl) tried to call a subroutine called q). This means that for example instead of do format() you must write do &format().

  • The builtin dump() now gives an optional warning dump() better written as CORE::dump(), meaning that by default dump(...) is resolved as the builtin dump() which dumps core and aborts, not as (possibly) user-defined sub dump. To call the latter, qualify the call as &dump(...). (The whole dump() feature is to considered deprecated, and possibly removed/changed in future releases.)

  • chomp() and chop() are now overridable. Note, however, that their prototype (as given by prototype("CORE::chomp") is undefined, because it cannot be expressed and therefore one cannot really write replacements to override these builtins.

  • END blocks are now run even if you exit/die in a BEGIN block. Internally, the execution of END blocks is now controlled by PL_exit_flags & PERL_EXIT_DESTRUCT_END. This enables the new behaviour for Perl embedders. This will default in 5.10. See the perlembed manpage.

  • Formats now support zero-padded decimal fields.

  • Although "you shouldn't do that", it was possible to write code that depends on Perl's hashed key order (Data::Dumper does this). The new algorithm "One-at-a-Time" produces a different hashed key order. More details are in Performance Enhancements.

  • lstat(FILEHANDLE) now gives a warning because the operation makes no sense. In future releases this may become a fatal error.

  • Spurious syntax errors generated in certain situations, when glob() caused File::Glob to be loaded for the first time, have been fixed. [561]

  • Lvalue subroutines can now return undef in list context. However, the lvalue subroutine feature still remains experimental. [561+]

  • A lost warning "Can't declare ... dereference in my" has been restored (Perl had it earlier but it became lost in later releases.)

  • A new special regular expression variable has been introduced: $^N, which contains the most-recently closed group (submatch).

  • no Module; does not produce an error even if Module does not have an unimport() method. This parallels the behavior of use vis-a-vis import. [561]

  • The numerical comparison operators return undef if either operand is a NaN. Previously the behaviour was unspecified.

  • our can now have an experimental optional attribute unique that affects how global variables are shared among multiple interpreters, see our in the perlfunc manpage.

  • The following builtin functions are now overridable: each(), keys(), pop(), push(), shift(), splice(), unshift(). [561]

  • pack() / unpack() can now group template letters with () and then apply repetition/count modifiers on the groups.

  • pack() / unpack() can now process the Perl internal numeric types: IVs, UVs, NVs-- and also long doubles, if supported by the platform. The template letters are j, J, F, and D.

  • pack('U0a*', ...) can now be used to force a string to UTF-8.

  • my __PACKAGE__ $obj now works. [561]

  • POSIX::sleep() now returns the number of unslept seconds (as the POSIX standard says), as opposed to CORE::sleep() which returns the number of slept seconds.

  • printf() and sprintf() now support parameter reordering using the %\d+\$ and *\d+\$ syntaxes. For example

        printf "%2\$s %1\$s\n", "foo", "bar";

    will print "bar foo\n". This feature helps in writing internationalised software, and in general when the order of the parameters can vary.

  • The (\&) prototype now works properly. [561]

  • prototype(\[$@%&]) is now available to implicitly create references (useful for example if you want to emulate the tie() interface).

  • A new command-line option, -t is available. It is the little brother of -T: instead of dying on taint violations, lexical warnings are given. This is only meant as a temporary debugging aid while securing the code of old legacy applications. This is not a substitute for -T.

  • In other taint news, the exec LIST and system LIST have now been considered too risky (think exec @ARGV: it can start any program with any arguments), and now the said forms cause a warning under lexical warnings. You should carefully launder the arguments to guarantee their validity. In future releases of Perl the forms will become fatal errors so consider starting laundering now.

  • Tied hash interfaces are now required to have the EXISTS and DELETE methods (either own or inherited).

  • If tr/// is just counting characters, it doesn't attempt to modify its target.

  • untie() will now call an UNTIE() hook if it exists. See the perltie manpage for details. [561]

  • utime now supports utime undef, undef, @files to change the file timestamps to the current time.

  • The rules for allowing underscores (underbars) in numeric constants have been relaxed and simplified: now you can have an underscore simply between digits.

  • Rather than relying on C's argv[0] (which may not contain a full pathname) where possible $^X is now set by asking the operating system. (eg by reading /proc/self/exe on Linux, /proc/curproc/file on FreeBSD)

  • A new variable, ${^TAINT}, indicates whether taint mode is enabled.

  • You can now override the readline() builtin, and this overrides also the <FILEHANDLE> angle bracket operator.

  • The command-line options -s and -F are now recognized on the shebang (#!) line.

  • Use of the /c match modifier without an accompanying /g modifier elicits a new warning: Use of /c modifier is meaningless without /g.

    Use of /c in substitutions, even with /g, elicits Use of /c modifier is meaningless in s///.

    Use of /g with split elicits Use of /g modifier is meaningless in split.

  • Support for the CLONE special subroutine had been added. With ithreads, when a new thread is created, all Perl data is cloned, however non-Perl data cannot be cloned automatically. In CLONE you can do whatever you need to do, like for example handle the cloning of non-Perl data, if necessary. CLONE will be executed once for every package that has it defined or inherited. It will be called in the context of the new thread, so all modifications are made in the new area.

    See the perlmod manpage

Modules and Pragmata

New Modules and Pragmata

  • Attribute::Handlers, originally by Damian Conway and now maintained by Arthur Bergman, allows a class to define attribute handlers.

        package MyPack;
    use Attribute::Handlers;
    sub Wolf :ATTR(SCALAR) { print "howl!\n" }

        # later, in some package using or inheriting from MyPack...

        my MyPack $Fluffy : Wolf; # the attribute handler Wolf will be called

    Both variables and routines can have attribute handlers. Handlers can be specific to type (SCALAR, ARRAY, HASH, or CODE), or specific to the exact compilation phase (BEGIN, CHECK, INIT, or END). See the Attribute::Handlers manpage.

  • B::Concise, by Stephen McCamant, is a new compiler backend for walking the Perl syntax tree, printing concise info about ops. The output is highly customisable. See the B::Concise manpage. [561+]

  • The new bignum, bigint, and bigrat pragmas, by Tels, implement transparent bignum support (using the Math::BigInt, Math::BigFloat, and Math::BigRat backends).

  • Class::ISA, by Sean Burke, is a module for reporting the search path for a class's ISA tree. See the Class::ISA manpage.

  • Cwd now has a split personality: if possible, an XS extension is used, (this will hopefully be faster, more secure, and more robust) but if not possible, the familiar Perl implementation is used.

  • Devel::PPPort, originally by Kenneth Albanowski and now maintained by Paul Marquess, has been added. It is primarily used by h2xs to enhance portability of XS modules between different versions of Perl. See the Devel::PPPort manpage.

  • Digest, frontend module for calculating digests (checksums), from Gisle Aas, has been added. See the Digest manpage.

  • Digest::MD5 for calculating MD5 digests (checksums) as defined in RFC 1321, from Gisle Aas, has been added. See the Digest::MD5 manpage.

        use Digest::MD5 'md5_hex';

        $digest = md5_hex("Thirsty Camel");

        print $digest, "\n"; # 01d19d9d2045e005c3f1b80e8b164de1

    NOTE: the MD5 backward compatibility module is deliberately not included since its further use is discouraged.

    See also the PerlIO::via::QuotedPrint manpage.

  • Encode, originally by Nick Ing-Simmons and now maintained by Dan Kogai, provides a mechanism to translate between different character encodings. Support for Unicode, ISO-8859-1, and ASCII are compiled in to the module. Several other encodings (like the rest of the ISO-8859, CP*/Win*, Mac, KOI8-R, three variants EBCDIC, Chinese, Japanese, and Korean encodings) are included and can be loaded at runtime. (For space considerations, the largest Chinese encodings have been separated into their own CPAN module, Encode::HanExtra, which Encode will use if available). See the Encode manpage.

    Any encoding supported by Encode module is also available to the ":encoding()" layer if PerlIO is used.

  • Hash::Util is the interface to the new restricted hashes feature. (Implemented by Jeffrey Friedl, Nick Ing-Simmons, and Michael Schwern.) See the Hash::Util manpage.

  • I18N::Langinfo can be used to query locale information. See the I18N::Langinfo manpage.

  • I18N::LangTags, by Sean Burke, has functions for dealing with RFC3066-style language tags. See the I18N::LangTags manpage.

  • ExtUtils::Constant, by Nicholas Clark, is a new tool for extension writers for generating XS code to import C header constants. See the ExtUtils::Constant manpage.

  • Filter::Simple, by Damian Conway, is an easy-to-use frontend to Filter::Util::Call. See the Filter::Simple manpage.

        # in MyFilter.pm:

        package MyFilter;

        use Filter::Simple sub {
        while (my ($from, $to) = splice @_, 0, 2) {
                s/$from/$to/g;
        }
    };

        1;

        # in user's code:

        use MyFilter qr/red/ => 'green';

        print "red\n";   # this code is filtered, will print "green\n"
    print "bored\n"; # this code is filtered, will print "bogreen\n"

        no MyFilter;

        print "red\n";   # this code is not filtered, will print "red\n"

  • File::Temp, by Tim Jenness, allows one to create temporary files and directories in an easy, portable, and secure way. See the File::Temp manpage. [561+]

  • Filter::Util::Call, by Paul Marquess, provides you with the framework to write source filters in Perl. For most uses, the frontend Filter::Simple is to be preferred. See the Filter::Util::Call manpage.

  • if, by Ilya Zakharevich, is a new pragma for conditional inclusion of modules.

  • libnet, by Graham Barr, is a collection of perl5 modules related to network programming. See the Net::FTP manpage, the Net::NNTP manpage, the Net::Ping manpage (not part of libnet, but related), the Net::POP3 manpage, the Net::SMTP manpage, and the Net::Time manpage.

    Perl installation leaves libnet unconfigured; use libnetcfg to configure it.

  • List::Util, by Graham Barr, is a selection of general-utility list subroutines, such as sum(), min(), first(), and shuffle(). See the List::Util manpage.

  • Locale::Constants, Locale::Country, Locale::Currency Locale::Language, and the Locale::Script manpage, by Neil Bowers, have been added. They provide the codes for various locale standards, such as "fr" for France, "usd" for US Dollar, and "ja" for Japanese.

        use Locale::Country;

        $country = code2country('jp');               # $country gets 'Japan'
    $code    = country2code('Norway');           # $code gets 'no'

    See the Locale::Constants manpage, the Locale::Country manpage, the Locale::Currency manpage, and the Locale::Language manpage.

  • Locale::Maketext, by Sean Burke, is a localization framework. See the Locale::Maketext manpage, and the Locale::Maketext::TPJ13 manpage. The latter is an article about software localization, originally published in The Perl Journal #13, and republished here with kind permission.

  • Math::BigRat for big rational numbers, to accompany Math::BigInt and Math::BigFloat, from Tels. See the Math::BigRat manpage.

  • Memoize can make your functions faster by trading space for time, from Mark-Jason Dominus. See the Memoize manpage.

  • MIME::Base64, by Gisle Aas, allows you to encode data in base64, as defined in RFC 2045 - MIME (Multipurpose Internet Mail Extensions).

        use MIME::Base64;

        $encoded = encode_base64('Aladdin:open sesame');
    $decoded = decode_base64($encoded);

        print $encoded, "\n"; # "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

    See the MIME::Base64 manpage.

  • MIME::QuotedPrint, by Gisle Aas, allows you to encode data in quoted-printable encoding, as defined in RFC 2045 - MIME (Multipurpose Internet Mail Extensions).

        use MIME::QuotedPrint;

        $encoded = encode_qp("\xDE\xAD\xBE\xEF");
    $decoded = decode_qp($encoded);

        print $encoded, "\n"; # "=DE=AD=BE=EF\n"
    print $decoded, "\n"; # "\xDE\xAD\xBE\xEF\n"

    See also the PerlIO::via::QuotedPrint manpage.

  • NEXT, by Damian Conway, is a pseudo-class for method redispatch. See the NEXT manpage.

  • open is a new pragma for setting the default I/O layers for open().

  • PerlIO::scalar, by Nick Ing-Simmons, provides the implementation of IO to "in memory" Perl scalars as discussed above. It also serves as an example of a loadable PerlIO layer. Other future possibilities include PerlIO::Array and PerlIO::Code. See the PerlIO::scalar manpage.

  • PerlIO::via, by Nick Ing-Simmons, acts as a PerlIO layer and wraps PerlIO layer functionality provided by a class (typically implemented in Perl code).

  • PerlIO::via::QuotedPrint, by Elizabeth Mattijsen, is an example of a PerlIO::via class:

        use PerlIO::via::QuotedPrint;
    open($fh,">:via(QuotedPrint)",$path);

    This will automatically convert everything output to $fh to Quoted-Printable. See the PerlIO::via manpage and the PerlIO::via::QuotedPrint manpage.

  • Pod::ParseLink, by Russ Allbery, has been added, to parse L<> links in pods as described in the new perlpodspec.

  • Pod::Text::Overstrike, by Joe Smith, has been added. It converts POD data to formatted overstrike text. See the Pod::Text::Overstrike manpage. [561+]

  • Scalar::Util is a selection of general-utility scalar subroutines, such as blessed(), reftype(), and tainted(). See the Scalar::Util manpage.

  • sort is a new pragma for controlling the behaviour of sort().

  • Storable gives persistence to Perl data structures by allowing the storage and retrieval of Perl data to and from files in a fast and compact binary format. Because in effect Storable does serialisation of Perl data structures, with it you can also clone deep, hierarchical datastructures. Storable was originally created by Raphael Manfredi, but it is now maintained by Abhijit Menon-Sen. Storable has been enhanced to understand the two new hash features, Unicode keys and restricted hashes. See the Storable manpage.

  • Switch, by Damian Conway, has been added. Just by saying

        use Switch;

    you have switch and case available in Perl.

        use Switch;

        switch ($val) {

                    case 1          { print "number 1" }
                case "a"        { print "string a" }
                case [1..10,42] { print "number in list" }
                case (@array)   { print "number in list" }
                case /\w+/      { print "pattern" }
                case qr/\w+/    { print "pattern" }
                case (%hash)    { print "entry in hash" }
                case (\%hash)   { print "entry in hash" }
                case (\&sub)    { print "arg to subroutine" }
                else            { print "previous case not true" }
                    }

    See the Switch manpage.

  • Test::More, by Michael Schwern, is yet another framework for writing test scripts, more extensive than Test::Simple. See the Test::More manpage.

  • Test::Simple, by Michael Schwern, has basic utilities for writing tests. See the Test::Simple manpage.

  • Text::Balanced, by Damian Conway, has been added, for extracting delimited text sequences from strings.

        use Text::Balanced 'extract_delimited';

        ($a, $b) = extract_delimited("'never say never', he never said", "'", '');

    $a will be "'never say never'", $b will be ', he never said'.

    In addition to extract_delimited(), there are also extract_bracketed(), extract_quotelike(), extract_codeblock(), extract_variable(), extract_tagged(), extract_multiple(), gen_delimited_pat(), and gen_extract_tagged(). With these, you can implement rather advanced parsing algorithms. See the Text::Balanced manpage.

  • threads, by Arthur Bergman, is an interface to interpreter threads. Interpreter threads (ithreads) is the new thread model introduced in Perl 5.6 but only available as an internal interface for extension writers (and for Win32 Perl for fork() emulation). See the threads manpage, the threads::shared manpage, and the perlthrtut manpage.

  • threads::shared, by Arthur Bergman, allows data sharing for interpreter threads. See the threads::shared manpage.

  • Tie::File, by Mark-Jason Dominus, associates a Perl array with the lines of a file. See the Tie::File manpage.

  • Tie::Memoize, by Ilya Zakharevich, provides on-demand loaded hashes. See the Tie::Memoize manpage.

  • Tie::RefHash::Nestable, by Edward Avis, allows storing hash references (unlike the standard Tie::RefHash) The module is contained within Tie::RefHash. See the Tie::RefHash manpage.

  • Time::HiRes, by Douglas E. Wegscheid, provides high resolution timing (ualarm, usleep, and gettimeofday). See the Time::HiRes manpage.

  • Unicode::UCD offers a querying interface to the Unicode Character Database. See the Unicode::UCD manpage.

  • Unicode::Collate, by SADAHIRO Tomoyuki, implements the UCA (Unicode Collation Algorithm) for sorting Unicode strings. See the Unicode::Collate manpage.

  • Unicode::Normalize, by SADAHIRO Tomoyuki, implements the various Unicode normalization forms. See the Unicode::Normalize manpage.

  • XS::APItest, by Tim Jenness, is a test extension that exercises XS APIs. Currently only printf() is tested: how to output various basic data types from XS.

  • XS::Typemap, by Tim Jenness, is a test extension that exercises XS typemaps. Nothing gets installed, but the code is worth studying for extension writers.

Updated And Improved Modules and Pragmata

  • The following independently supported modules have been updated to the
newest versions from CPAN: CGI, CPAN, DB_File, File::Spec, File::Temp,
Getopt::Long, Math::BigFloat, Math::BigInt, the podlators bundle
(Pod::Man, Pod::Text), Pod::LaTeX [561+], Pod::Parser, Storable,
Term::ANSIColor, Test, Text-Tabs+Wrap.

  • attributes::reftype() now works on tied arguments.

  • AutoLoader can now be disabled with no AutoLoader;.

  • B::Deparse has been significantly enhanced by Robin Houston. It can now deparse almost all of the standard test suite (so that the tests still succeed). There is a make target "test.deparse" for trying this out.

  • Carp now has better interface documentation, and the @CARP_NOT interface has been added to get optional control over where errors are reported independently of @ISA, by Ben Tilly.

  • Class::Struct can now define the classes in compile time.

  • Class::Struct now assigns the array/hash element if the accessor is called with an array/hash element as the sole argument.

  • The return value of Cwd::fastcwd() is now tainted.

  • Data::Dumper now has an option to sort hashes.

  • Data::Dumper now has an option to dump code references using B::Deparse.

  • DB_File now supports newer Berkeley DB versions, among other improvements.

  • Devel::Peek now has an interface for the Perl memory statistics (this works only if you are using perl's malloc, and if you have compiled with debugging).

  • The English module can now be used without the infamous performance hit by saying

            use English '-no_match_vars';

    (Assuming, of course, that you don't need the troublesome variables $`, $&, or $'.) Also, introduced @LAST_MATCH_START and @LAST_MATCH_END English aliases for @- and @+.

  • ExtUtils::MakeMaker has been significantly cleaned up and fixed. The enhanced version has also been backported to earlier releases of Perl and submitted to CPAN so that the earlier releases can enjoy the fixes.

  • The arguments of WriteMakefile() in Makefile.PL are now checked for sanity much more carefully than before. This may cause new warnings when modules are being installed. See the ExtUtils::MakeMaker manpage for more details.

  • ExtUtils::MakeMaker now uses File::Spec internally, which hopefully leads to better portability.

  • Fcntl, Socket, and Sys::Syslog have been rewritten by Nicholas Clark to use the new-style constant dispatch section (see the ExtUtils::Constant manpage). This means that they will be more robust and hopefully faster.

  • File::Find now chdir()s correctly when chasing symbolic links. [561]

  • File::Find now has pre- and post-processing callbacks. It also correctly changes directories when chasing symbolic links. Callbacks (naughtily) exiting with "next;" instead of "return;" now work.

  • File::Find is now (again) reentrant. It also has been made more portable.

  • The warnings issued by File::Find now belong to their own category. You can enable/disable them with use/no warnings 'File::Find';.

  • File::Glob::glob() has been renamed to File::Glob::bsd_glob() because the name clashes with the builtin glob(). The older name is still available for compatibility, but is deprecated. [561]

  • File::Glob now supports GLOB_LIMIT constant to limit the size of the returned list of filenames.

  • IPC::Open3 now allows the use of numeric file descriptors.

  • IO::Socket now has an atmark() method, which returns true if the socket is positioned at the out-of-band mark. The method is also exportable as a sockatmark() function.

  • IO::Socket::INET failed to open the specified port if the service name was not known. It now correctly uses the supplied port number as is. [561]

  • IO::Socket::INET has support for the ReusePort option (if your platform supports it). The Reuse option now has an alias, ReuseAddr. For clarity, you may want to prefer ReuseAddr.

  • IO::Socket::INET now supports a value of zero for LocalPort (usually meaning that the operating system will make one up.)

  • 'use lib' now works identically to @INC. Removing directories with 'no lib' now works.

  • Math::BigFloat and Math::BigInt have undergone a full rewrite by Tels. They are now magnitudes faster, and they support various bignum libraries such as GMP and PARI as their backends.

  • Math::Complex handles inf, NaN etc., better.

  • Net::Ping has been considerably enhanced by Rob Brown: multihoming is now supported, Win32 functionality is better, there is now time measuring functionality (optionally high-resolution using Time::HiRes), and there is now "external" protocol which uses Net::Ping::External module which runs your external ping utility and parses the output. A version of Net::Ping::External is available in CPAN.

    Note that some of the Net::Ping tests are disabled when running under the Perl distribution since one cannot assume one or more of the following: enabled echo port at localhost, full Internet connectivity, or sympathetic firewalls. You can set the environment variable PERL_TEST_Net_Ping to "1" (one) before running the Perl test suite to enable all the Net::Ping tests.

  • POSIX::sigaction() is now much more flexible and robust. You can now install coderef handlers, 'DEFAULT', and 'IGNORE' handlers, installing new handlers was not atomic.

  • In Safe, %INC is now localised in a Safe compartment so that use/require work.

  • In SDBM_File on dosish platforms, some keys went missing because of lack of support for files with "holes". A workaround for the problem has been added.

  • In Search::Dict one can now have a pre-processing hook for the lines being searched.

  • The Shell module now has an OO interface.

  • In Sys::Syslog there is now a failover mechanism that will go through alternative connection mechanisms until the message is successfully logged.

  • The Test module has been significantly enhanced.

  • Time::Local::timelocal() does not handle fractional seconds anymore. The rationale is that neither does localtime(), and timelocal() and localtime() are supposed to be inverses of each other.

  • The vars pragma now supports declaring fully qualified variables. (Something that our() does not and will not support.)

  • The utf8:: name space (as in the pragma) provides various Perl-callable functions to provide low level access to Perl's internal Unicode representation. At the moment only length() has been implemented.

Utility Changes

  • Emacs perl mode (emacs/cperl-mode.el) has been updated to version 4.31.

  • emacs/e2ctags.pl is now much faster.

  • enc2xs is a tool for people adding their own encodings to the Encode module.

  • h2ph now supports C trigraphs.

  • h2xs now produces a template README.

  • h2xs now uses Devel::PPPort for better portability between different versions of Perl.

  • h2xs uses the new ExtUtils::Constant module which will affect newly created extensions that define constants. Since the new code is more correct (if you have two constants where the first one is a prefix of the second one, the first constant never got defined), less lossy (it uses integers for integer constant, as opposed to the old code that used floating point numbers even for integer constants), and slightly faster, you might want to consider regenerating your extension code (the new scheme makes regenerating easy). h2xs now also supports C trigraphs.

  • libnetcfg has been added to configure libnet.

  • perlbug is now much more robust. It also sends the bug report to perl.org, not perl.com.

  • perlcc has been rewritten and its user interface (that is, command line) is much more like that of the UNIX C compiler, cc. (The perlbc tools has been removed. Use perlcc -B instead.) Note that perlcc is still considered very experimental and unsupported. [561]

  • perlivp is a new Installation Verification Procedure utility for running any time after installing Perl.

  • piconv is an implementation of the character conversion utility iconv, demonstrating the new Encode module.

  • pod2html now allows specifying a cache directory.

  • pod2html now produces XHTML 1.0.

  • pod2html now understands POD written using different line endings (PC-like CRLF versus UNIX-like LF versus MacClassic-like CR).

  • s2p has been completely rewritten in Perl. (It is in fact a full implementation of sed in Perl: you can use the sed functionality by using the psed utility.)

  • xsubpp now understands POD documentation embedded in the *.xs files. [561]

  • xsubpp now supports the OUT keyword.

New Documentation

  • perl56delta details the changes between the 5.005 release and the 5.6.0 release.

  • perlclib documents the internal replacements for standard C library functions. (Interesting only for extension writers and Perl core hackers.) [561+]

  • perldebtut is a Perl debugging tutorial. [561+]

  • perlebcdic contains considerations for running Perl on EBCDIC platforms. [561+]

  • perlintro is a gentle introduction to Perl.

  • perliol documents the internals of PerlIO with layers.

  • perlmodstyle is a style guide for writing modules.

  • perlnewmod tells about writing and submitting a new module. [561+]

  • perlpacktut is a pack() tutorial.

  • perlpod has been rewritten to be clearer and to record the best practices gathered over the years.

  • perlpodspec is a more formal specification of the pod format, mainly of interest for writers of pod applications, not to people writing in pod.

  • perlretut is a regular expression tutorial. [561+]

  • perlrequick is a regular expressions quick-start guide. Yes, much quicker than perlretut. [561]

  • perltodo has been updated.

  • perltootc has been renamed as perltooc (to not to conflict with perltoot in filesystems restricted to "8.3" names).

  • perluniintro is an introduction to using Unicode in Perl. (perlunicode is more of a detailed reference and background information)

  • perlutil explains the command line utilities packaged with the Perl distribution. [561+]

The following platform-specific documents are available before the installation as README.platform, and after the installation as perlplatform:

    perlaix perlamiga perlapollo perlbeos perlbs2000
    perlce perlcygwin perldgux perldos perlepoc perlfreebsd perlhpux
    perlhurd perlirix perlmachten perlmacos perlmint perlmpeix
    perlnetware perlos2 perlos390 perlplan9 perlqnx perlsolaris
    perltru64 perluts perlvmesa perlvms perlvos perlwin32

These documents usually detail one or more of the following subjects: configuring, building, testing, installing, and sometimes also using Perl on the said platform.

Eastern Asian Perl users are now welcomed in their own languages: README.jp (Japanese), README.ko (Korean), README.cn (simplified Chinese) and README.tw (traditional Chinese), which are written in normal pod but encoded in EUC-JP, EUC-KR, EUC-CN and Big5. These will get installed as

   perljp perlko perlcn perltw

  • The documentation for the POSIX-BC platform is called "BS2000", to avoid confusion with the Perl POSIX module.

  • The documentation for the WinCE platform is called perlce (README.ce in the source code kit), to avoid confusion with the perlwin32 documentation on 8.3-restricted filesystems.

Performance Enhancements

  • map() could get pathologically slow when the result list it generates is larger than the source list. The performance has been improved for common scenarios. [561]

  • sort() is also fully reentrant, in the sense that the sort function can itself call sort(). This did not work reliably in previous releases. [561]

  • sort() has been changed to use primarily mergesort internally as opposed to the earlier quicksort. For very small lists this may result in slightly slower sorting times, but in general the speedup should be at least 20%. Additional bonuses are that the worst case behaviour of sort() is now better (in computer science terms it now runs in time O(N log N), as opposed to quicksort's Theta(N**2) worst-case run time behaviour), and that sort() is now stable (meaning that elements with identical keys will stay ordered as they were before the sort). See the sort pragma for information.

    The story in more detail: suppose you want to serve yourself a little slice of Pi.

        @digits = ( 3,1,4,1,5,9 );

    A numerical sort of the digits will yield (1,1,3,4,5,9), as expected. Which 1 comes first is hard to know, since one 1 looks pretty much like any other. You can regard this as totally trivial, or somewhat profound. However, if you just want to sort the even digits ahead of the odd ones, then what will

        sort { ($a % 2) <=> ($b % 2) } @digits;

    yield? The only even digit, 4, will come first. But how about the odd numbers, which all compare equal? With the quicksort algorithm used to implement Perl 5.6 and earlier, the order of ties is left up to the sort. So, as you add more and more digits of Pi, the order in which the sorted even and odd digits appear will change. and, for sufficiently large slices of Pi, the quicksort algorithm in Perl 5.8 won't return the same results even if reinvoked with the same input. The justification for this rests with quicksort's worst case behavior. If you run

       sort { $a <=> $b } ( 1 .. $N , 1 .. $N );

    (something you might approximate if you wanted to merge two sorted arrays using sort), doubling $N doesn't just double the quicksort time, it quadruples it. Quicksort has a worst case run time that can grow like N**2, so-called quadratic behaviour, and it can happen on patterns that may well arise in normal use. You won't notice this for small arrays, but you will notice it with larger arrays, and you may not live long enough for the sort to complete on arrays of a million elements. So the 5.8 quicksort scrambles large arrays before sorting them, as a statistical defence against quadratic behaviour. But that means if you sort the same large array twice, ties may be broken in different ways.

    Because of the unpredictability of tie-breaking order, and the quadratic worst-case behaviour, quicksort was almost replaced completely with a stable mergesort. Stable means that ties are broken to preserve the original order of appearance in the input array. So

        sort { ($a % 2) <=> ($b % 2) } (3,1,4,1,5,9);

    will yield (4,3,1,1,5,9), guaranteed. The even and odd numbers appear in the output in the same order they appeared in the input. Mergesort has worst case O(N log N) behaviour, the best value attainable. And, ironically, this mergesort does particularly well where quicksort goes quadratic: mergesort sorts (1..$N, 1..$N) in O(N) time. But quicksort was rescued at the last moment because it is faster than mergesort on certain inputs and platforms. For example, if you really don't care about the order of even and odd digits, quicksort will run in O(N) time; it's very good at sorting many repetitions of a small number of distinct elements. The quicksort divide and conquer strategy works well on platforms with relatively small, very fast, caches. Eventually, the problem gets whittled down to one that fits in the cache, from which point it benefits from the increased memory speed.

    Quicksort was rescued by implementing a sort pragma to control aspects of the sort. The stable subpragma forces stable behaviour, regardless of algorithm. The _quicksort and _mergesort subpragmas are heavy-handed ways to select the underlying implementation. The leading _ is a reminder that these subpragmas may not survive beyond 5.8. More appropriate mechanisms for selecting the implementation exist, but they wouldn't have arrived in time to save quicksort.

  • Hashes now use Bob Jenkins "One-at-a-Time" hashing key algorithm ( http://burtleburtle.net/bob/hash/doobs.html ). This algorithm is reasonably fast while producing a much better spread of values than the old hashing algorithm (originally by Chris Torek, later tweaked by Ilya Zakharevich). Hash values output from the algorithm on a hash of all 3-char printable ASCII keys comes much closer to passing the DIEHARD random number generation tests. According to perlbench, this change has not affected the overall speed of Perl.

  • unshift() should now be noticeably faster.

Installation and Configuration Improvements

Generic Improvements

  • INSTALL now explains how you can configure Perl to use 64-bit integers even on non-64-bit platforms.

  • Policy.sh policy change: if you are reusing a Policy.sh file (see INSTALL) and you use Configure -Dprefix=/foo/bar and in the old Policy $prefix eq $siteprefix and $prefix eq $vendorprefix, all of them will now be changed to the new prefix, /foo/bar. (Previously only $prefix changed.) If you do not like this new behaviour, specify prefix, siteprefix, and vendorprefix explicitly.

  • A new optional location for Perl libraries, otherlibdirs, is available. It can be used for example for vendor add-ons without disturbing Perl's own library directories.

  • In many platforms, the vendor-supplied 'cc' is too stripped-down to build Perl (basically, 'cc' doesn't do ANSI C). If this seems to be the case and 'cc' does not seem to be the GNU C compiler 'gcc', an automatic attempt is made to find and use 'gcc' instead.

  • gcc needs to closely track the operating system release to avoid build problems. If Configure finds that gcc was built for a different operating system release than is running, it now gives a clearly visible warning that there may be trouble ahead.

  • Since Perl 5.8 is not binary-compatible with previous releases of Perl, Configure no longer suggests including the 5.005 modules in @INC.

  • Configure -S can now run non-interactively. [561]

  • Configure support for pdp11-style memory models has been removed due to obsolescence. [561]

  • configure.gnu now works with options with whitespace in them.

  • installperl now outputs everything to STDERR.

  • Because PerlIO is now the default on most platforms, "-perlio" doesn't get appended to the $Config{archname} (also known as $^O) anymore. Instead, if you explicitly choose not to use perlio (Configure command line option -Uuseperlio), you will get "-stdio" appended.

  • Another change related to the architecture name is that "-64all" (-Duse64bitall, or "maximally 64-bit") is appended only if your pointers are 64 bits wide. (To be exact, the use64bitall is ignored.)

  • In AFS installations, one can configure the root of the AFS to be somewhere else than the default /afs by using the Configure parameter -Dafsroot=/some/where/else.

  • APPLLIB_EXP, a lesser-known configuration-time definition, has been documented. It can be used to prepend site-specific directories to Perl's default search path (@INC); see INSTALL for information.

  • The version of Berkeley DB used when the Perl (and, presumably, the DB_File extension) was built is now available as @Config{qw(db_version_major db_version_minor db_version_patch)} from Perl and as DB_VERSION_MAJOR_CFG DB_VERSION_MINOR_CFG DB_VERSION_PATCH_CFG from C.

  • Building Berkeley DB3 for compatibility modes for DB, NDBM, and ODBM has been documented in INSTALL.

  • If you have CPAN access (either network or a local copy such as a CD-ROM) you can during specify extra modules to Configure to build and install with Perl using the -Dextras=... option. See INSTALL for more details.

  • In addition to config.over, a new override file, config.arch, is available. This file is supposed to be used by hints file writers for architecture-wide changes (as opposed to config.over which is for site-wide changes).

  • If your file system supports symbolic links, you can build Perl outside of the source directory by

            mkdir perl/build/directory
        cd perl/build/directory
        sh /path/to/perl/source/Configure -Dmksymlinks ...

    This will create in perl/build/directory a tree of symbolic links pointing to files in /path/to/perl/source. The original files are left unaffected. After Configure has finished, you can just say

            make all test

    and Perl will be built and tested, all in perl/build/directory. [561]

  • For Perl developers, several new make targets for profiling and debugging have been added; see the perlhack manpage.

    • Use of the gprof tool to profile Perl has been documented in the perlhack manpage. There is a make target called "perl.gprof" for generating a gprofiled Perl executable.

    • If you have GCC 3, there is a make target called "perl.gcov" for creating a gcoved Perl executable for coverage analysis. See the perlhack manpage.

    • If you are on IRIX or Tru64 platforms, new profiling/debugging options have been added; see the perlhack manpage for more information about pixie and Third Degree.

  • Guidelines of how to construct minimal Perl installations have been added to INSTALL.

  • The Thread extension is now not built at all under ithreads (Configure -Duseithreads) because it wouldn't work anyway (the Thread extension requires being Configured with -Duse5005threads).

    Note that the 5.005 threads are unsupported and deprecated: if you have code written for the old threads you should migrate it to the new ithreads model.

  • The Gconvert macro ($Config{d_Gconvert}) used by perl for stringifying floating-point numbers is now more picky about using sprintf %.*g rules for the conversion. Some platforms that used to use gcvt may now resort to the slower sprintf.

  • The obsolete method of making a special (e.g., debugging) flavor of perl by saying

            make LIBPERL=libperld.a

    has been removed. Use -DDEBUGGING instead.

New Or Improved Platforms

For the list of platforms known to support Perl, see Supported Platforms in the perlport manpage.

  • AIX dynamic loading should be now better supported.

  • AIX should now work better with gcc, threads, and 64-bitness. Also the long doubles support in AIX should be better now. See the perlaix manpage.

  • AtheOS ( http://www.atheos.cx/ ) is a new platform.

  • BeOS has been reclaimed.

  • The DG/UX platform now supports 5.005-style threads. See the perldgux manpage.

  • The DYNIX/ptx platform (also known as dynixptx) is supported at or near osvers 4.5.2.

  • EBCDIC platforms (z/OS (also known as OS/390), POSIX-BC, and VM/ESA) have been regained. Many test suite tests still fail and the co-existence of Unicode and EBCDIC isn't quite settled, but the situation is much better than with Perl 5.6. See the perlos390 manpage, the perlbs2000 manpage (for POSIX-BC), and the perlvmesa manpage for more information.

  • Building perl with -Duseithreads or -Duse5005threads now works under HP-UX 10.20 (previously it only worked under 10.30 or later). You will need a thread library package installed. See README.hpux. [561]

  • Mac OS Classic is now supported in the mainstream source package (MacPerl has of course been available since perl 5.004 but now the source code bases of standard Perl and MacPerl have been synchronised) [561]

  • Mac OS X (or Darwin) should now be able to build Perl even on HFS+ filesystems. (The case-insensitivity used to confuse the Perl build process.)

  • NCR MP-RAS is now supported. [561]

  • All the NetBSD specific patches (except for the installation specific ones) have been merged back to the main distribution.

  • NetWare from Novell is now supported. See the perlnetware manpage.

  • NonStop-UX is now supported. [561]

  • NEC SUPER-UX is now supported.

  • All the OpenBSD specific patches (except for the installation specific ones) have been merged back to the main distribution.

  • Perl has been tested with the GNU pth userlevel thread package ( http://www.gnu.org/software/pth/pth.html ). All thread tests of Perl now work, but not without adding some yield()s to the tests, so while pth (and other userlevel thread implementations) can be considered to be "working" with Perl ithreads, keep in mind the possible non-preemptability of the underlying thread implementation.

  • Stratus VOS is now supported using Perl's native build method (Configure). This is the recommended method to build Perl on VOS. The older methods, which build miniperl, are still available. See the perlvos manpage. [561+]

  • The Amdahl UTS UNIX mainframe platform is now supported. [561]

  • WinCE is now supported. See the perlce manpage.

  • z/OS (formerly known as OS/390, formerly known as MVS OE) now has support for dynamic loading. This is not selected by default, however, you must specify -Dusedl in the arguments of Configure. [561]

Selected Bug Fixes

Numerous memory leaks and uninitialized memory accesses have been hunted down. Most importantly, anonymous subs used to leak quite a bit. [561]

  • The autouse pragma didn't work for Multi::Part::Function::Names.

  • caller() could cause core dumps in certain situations. Carp was sometimes affected by this problem. In particular, caller() now returns a subroutine name of (unknown) for subroutines that have been removed from the symbol table.

  • chop(@list) in list context returned the characters chopped in reverse order. This has been reversed to be in the right order. [561]

  • Configure no longer includes the DBM libraries (dbm, gdbm, db, ndbm) when building the Perl binary. The only exception to this is SunOS 4.x, which needs them. [561]

  • The behaviour of non-decimal but numeric string constants such as "0x23" was platform-dependent: in some platforms that was seen as 35, in some as 0, in some as a floating point number (don't ask). This was caused by Perl's using the operating system libraries in a situation where the result of the string to number conversion is undefined: now Perl consistently handles such strings as zero in numeric contexts.

  • Several debugger fixes: exit code now reflects the script exit code, condition "0" now treated correctly, the d command now checks line number, $. no longer gets corrupted, and all debugger output now goes correctly to the socket if RemotePort is set. [561]

  • The debugger (perl5db.pl) has been modified to present a more consistent commands interface, via (CommandSet=580). perl5db.t was also added to test the changes, and as a placeholder for further tests.

    See the perldebug manpage.

  • The debugger has a new dumpDepth option to control the maximum depth to which nested structures are dumped. The x command has been extended so that x N EXPR dumps out the value of EXPR to a depth of at most N levels.

  • The debugger can now show lexical variables if you have the CPAN module PadWalker installed.

  • The order of DESTROYs has been made more predictable.

  • Perl 5.6.0 could emit spurious warnings about redefinition of dl_error() when statically building extensions into perl. This has been corrected. [561]

  • dprofpp -R didn't work.

  • *foo{FORMAT} now works.

  • Infinity is now recognized as a number.

  • UNIVERSAL::isa no longer caches methods incorrectly. (This broke the Tk extension with 5.6.0.) [561]

  • Lexicals I: lexicals outside an eval "" weren't resolved correctly inside a subroutine definition inside the eval "" if they were not already referenced in the top level of the eval""ed code.

  • Lexicals II: lexicals leaked at file scope into subroutines that were declared before the lexicals.

  • Lexical warnings now propagating correctly between scopes and into eval "...".

  • use warnings qw(FATAL all) did not work as intended. This has been corrected. [561]

  • warnings::enabled() now reports the state of $^W correctly if the caller isn't using lexical warnings. [561]

  • Line renumbering with eval and #line now works. [561]

  • Fixed numerous memory leaks, especially in eval "".

  • Localised tied variables no longer leak memory

        use Tie::Hash;
    tie my %tied_hash => 'Tie::StdHash';

        ...
        # Used to leak memory every time local() was called;
    # in a loop, this added up.
    local($tied_hash{Foo}) = 1;

  • Localised hash elements (and %ENV) are correctly unlocalised to not exist, if they didn't before they were localised.

        use Tie::Hash;
    tie my %tied_hash => 'Tie::StdHash';

        ...
        # Nothing has set the FOO element so far

        { local $tied_hash{FOO} = 'Bar' }

        # This used to print, but not now.
    print "exists!\n" if exists $tied_hash{FOO};

    As a side effect of this fix, tied hash interfaces must define the EXISTS and DELETE methods.

  • mkdir() now ignores trailing slashes in the directory name, as mandated by POSIX.

  • Some versions of glibc have a broken modfl(). This affects builds with -Duselongdouble. This version of Perl detects this brokenness and has a workaround for it. The glibc release 2.2.2 is known to have fixed the modfl() bug.

  • Modulus of unsigned numbers now works (4063328477 % 65535 used to return 27406, instead of 27047). [561]

  • Some "not a number" warnings introduced in 5.6.0 eliminated to be more compatible with 5.005. Infinity is now recognised as a number. [561]

  • Numeric conversions did not recognize changes in the string value properly in certain circumstances. [561]

  • Attributes (such as :shared) didn't work with our().

  • our() variables will not cause bogus "Variable will not stay shared" warnings. [561]

  • "our" variables of the same name declared in two sibling blocks resulted in bogus warnings about "redeclaration" of the variables. The problem has been corrected. [561]

  • pack "Z" now correctly terminates the string with "\0".

  • Fix password routines which in some shadow password platforms (e.g. HP-UX) caused getpwent() to return every other entry.

  • The PERL5OPT environment variable (for passing command line arguments to Perl) didn't work for more than a single group of options. [561]

  • PERL5OPT with embedded spaces didn't work.

  • printf() no longer resets the numeric locale to "C".

  • qw(a\\b) now parses correctly as 'a\\b': that is, as three characters, not four. [561]

  • pos() did not return the correct value within s///ge in earlier versions. This is now handled correctly. [561]

  • Printing quads (64-bit integers) with printf/sprintf now works without the q L ll prefixes (assuming you are on a quad-capable platform).

  • Regular expressions on references and overloaded scalars now work. [561+]

  • Right-hand side magic (GMAGIC) could in many cases such as string concatenation be invoked too many times.

  • scalar() now forces scalar context even when used in void context.

  • SOCKS support is now much more robust.

  • sort() arguments are now compiled in the right wantarray context (they were accidentally using the context of the sort() itself). The comparison block is now run in scalar context, and the arguments to be sorted are always provided list context. [561]

  • Changed the POSIX character class [[:space:]] to include the (very rarely used) vertical tab character. Added a new POSIX-ish character class [[:blank:]] which stands for horizontal whitespace (currently, the space and the tab).

  • The tainting behaviour of sprintf() has been rationalized. It does not taint the result of floating point formats anymore, making the behaviour consistent with that of string interpolation. [561]

  • Some cases of inconsistent taint propagation (such as within hash values) have been fixed.

  • The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds of simple pattern matches. These are now handled better. [561]

  • Regular expression debug output (whether through use re 'debug' or via -Dr) now looks better. [561]

  • Multi-line matches like "a\nxb\n" =~ /(?!\A)x/m were flawed. The bug has been fixed. [561]

  • Use of $& could trigger a core dump under some situations. This is now avoided. [561]

  • The regular expression captured submatches ($1, $2, ...) are now more consistently unset if the match fails, instead of leaving false data lying around in them. [561]

  • readline() on files opened in "slurp" mode could return an extra "" (blank line) at the end in certain situations. This has been corrected. [561]

  • Autovivification of symbolic references of special variables described in the perlvar manpage (as in ${$num}) was accidentally disabled. This works again now. [561]

  • Sys::Syslog ignored the LOG_AUTH constant.

  • $AUTOLOAD, sort(), lock(), and spawning subprocesses in multiple threads simultaneously are now thread-safe.

  • Tie::Array's SPLICE method was broken.

  • Allow a read-only string on the left-hand side of a non-modifying tr///.

  • If STDERR is tied, warnings caused by warn and die now correctly pass to it.

  • Several Unicode fixes.

    • BOMs (byte order marks) at the beginning of Perl files (scripts, modules) should now be transparently skipped. UTF-16 and UCS-2 encoded Perl files should now be read correctly.

    • The character tables have been updated to Unicode 3.2.0.

    • Comparing with utf8 data does not magically upgrade non-utf8 data into utf8. (This was a problem for example if you were mixing data from I/O and Unicode data: your output might have got magically encoded as UTF-8.)

    • Generating illegal Unicode code points such as U+FFFE, or the UTF-16 surrogates, now also generates an optional warning.

    • IsAlnum, IsAlpha, and IsWord now match titlecase.

    • Concatenation with the . operator or via variable interpolation, eq, substr, reverse, quotemeta, the x operator, substitution with s///, single-quoted UTF-8, should now work.

    • The tr/// operator now works. Note that the tr///CU functionality has been removed (but see pack('U0', ...)).

    • eval "v200" now works.

    • Perl 5.6.0 parsed m/\x{ab}/ incorrectly, leading to spurious warnings. This has been corrected. [561]

    • Zero entries were missing from the Unicode classes such as IsDigit.

  • Large unsigned numbers (those above 2**31) could sometimes lose their unsignedness, causing bogus results in arithmetic operations. [561]

  • The Perl parser has been stress tested using both random input and Markov chain input and the few found crashes and lockups have been fixed.

Platform Specific Changes and Fixes

  • BSDI 4.*

    Perl now works on post-4.0 BSD/OSes.

  • All BSDs

    Setting $0 now works (as much as possible; see the perlvar manpage for details).

  • Cygwin

    Numerous updates; currently synchronised with Cygwin 1.3.10.

  • Previously DYNIX/ptx had problems in its Configure probe for non-blocking I/O.

  • EPOC

    EPOC now better supported. See README.epoc. [561]

  • FreeBSD 3.*

    Perl now works on post-3.0 FreeBSDs.

  • HP-UX

    README.hpux updated; Configure -Duse64bitall now works; now uses HP-UX malloc instead of Perl malloc.

  • IRIX

    Numerous compilation flag and hint enhancements; accidental mixing of 32-bit and 64-bit libraries (a doomed attempt) made much harder.

  • Linux

    • Long doubles should now work (see INSTALL). [561]

    • Linux previously had problems related to sockaddrlen when using accept(), recvfrom() (in Perl: recv()), getpeername(), and getsockname().

  • Mac OS Classic

    Compilation of the standard Perl distribution in Mac OS Classic should now work if you have the Metrowerks development environment and the missing Mac-specific toolkit bits. Contact the macperl mailing list for details.

  • MPE/iX

    MPE/iX update after Perl 5.6.0. See README.mpeix. [561]

  • NetBSD/threads: try installing the GNU pth (should be in the packages collection, or http://www.gnu.org/software/pth/), and Configure with -Duseithreads.

  • NetBSD/sparc

    Perl now works on NetBSD/sparc.

  • OS/2

    Now works with usethreads (see INSTALL). [561]

  • Solaris

    64-bitness using the Sun Workshop compiler now works.

  • Stratus VOS

    The native build method requires at least VOS Release 14.5.0 and GNU C++/GNU Tools 2.0.1 or later. The Perl pack function now maps overflowed values to +infinity and underflowed values to -infinity.

  • Tru64 (aka Digital UNIX, aka DEC OSF/1)

    The operating system version letter now recorded in $Config{osvers}. Allow compiling with gcc (previously explicitly forbidden). Compiling with gcc still not recommended because buggy code results, even with gcc 2.95.2.

  • Unicos

    Fixed various alignment problems that lead into core dumps either during build or later; no longer dies on math errors at runtime; now using full quad integers (64 bits), previously was using only 46 bit integers for speed.

  • VMS

    See Socket Extension Dynamic in VMS and IEEE-format Floating Point Default on OpenVMS Alpha for important changes not otherwise listed here.

    chdir() now works better despite a CRT bug; now works with MULTIPLICITY (see INSTALL); now works with Perl's malloc.

    The tainting of %ENV elements via keys or values was previously unimplemented. It now works as documented.

    The waitpid emulation has been improved. The worst bug (now fixed) was that a pid of -1 would cause a wildcard search of all processes on the system.

    POSIX-style signals are now emulated much better on VMS versions prior to 7.0.

    The system function and backticks operator have improved functionality and better error handling. [561]

    File access tests now use current process privileges rather than the user's default privileges, which could sometimes result in a mismatch between reported access and actual access. This improvement is only available on VMS v6.0 and later.

    There is a new kill implementation based on sys$sigprc that allows older VMS systems (pre-7.0) to use kill to send signals rather than simply force exit. This implementation also allows later systems to call kill from within a signal handler.

    Iterative logical name translations are now limited to 10 iterations in imitation of SHOW LOGICAL and other OpenVMS facilities.

  • Windows

    • Signal handling now works better than it used to. It is now implemented using a Windows message loop, and is therefore less prone to random crashes.

    • fork() emulation is now more robust, but still continues to have a few esoteric bugs and caveats. See the perlfork manpage for details. [561+]

    • A failed (pseudo)fork now returns undef and sets errno to EAGAIN. [561]

    • The following modules now work on Windows:

          ExtUtils::Embed         [561]
    IO::Pipe
    IO::Poll
    Net::Ping

    • IO::File::new_tmpfile() is no longer limited to 32767 invocations per-process.

    • Better chdir() return value for a non-existent directory.

    • Compiling perl using the 64-bit Platform SDK tools is now supported.

    • The Win32::SetChildShowWindow() builtin can be used to control the visibility of windows created by child processes. See the Win32 manpage for details.

    • Non-blocking waits for child processes (or pseudo-processes) are supported via waitpid($pid, &POSIX::WNOHANG).

    • The behavior of system() with multiple arguments has been rationalized. Each unquoted argument will be automatically quoted to protect whitespace, and any existing whitespace in the arguments will be preserved. This improves the portability of system(@args) by avoiding the need for Windows cmd shell specific quoting in perl programs.

      Note that this means that some scripts that may have relied on earlier buggy behavior may no longer work correctly. For example, system("nmake /nologo", @args) will now attempt to run the file nmake /nologo and will fail when such a file isn't found. On the other hand, perl will now execute code such as system("c:/Program Files/MyApp/foo.exe", @args) correctly.

    • The perl header files no longer suppress common warnings from the Microsoft Visual C++ compiler. This means that additional warnings may now show up when compiling XS code.

    • Borland C++ v5.5 is now a supported compiler that can build Perl. However, the generated binaries continue to be incompatible with those generated by the other supported compilers (GCC and Visual C++). [561]

    • Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x. [561]

    • Current directory entries in %ENV are now correctly propagated to child processes. [561]

    • New %ENV entries now propagate to subprocesses. [561]

    • Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root. Other bugs in chdir() and Cwd::cwd() have also been fixed. [561]

    • The makefiles now default to the features enabled in ActiveState ActivePerl (a popular Win32 binary distribution). [561]

    • HTML files will now be installed in c:\perl\html instead of c:\perl\lib\pod\html

    • REG_EXPAND_SZ keys are now allowed in registry settings used by perl. [561]

    • Can now send() from all threads, not just the first one. [561]

    • ExtUtils::MakeMaker now uses $ENV{LIB} to search for libraries. [561]

    • Less stack reserved per thread so that more threads can run concurrently. (Still 16M per thread.) [561]

    • File::Spec->tmpdir() now prefers C:/temp over /tmp (works better when perl is running as service).

    • Better UNC path handling under ithreads. [561]

    • wait(), waitpid(), and backticks now return the correct exit status under Windows 9x. [561]

    • A socket handle leak in accept() has been fixed. [561]

New or Changed Diagnostics

Please see the perldiag manpage for more details.

  • Ambiguous range in the transliteration operator (like a-z-9) now gives a warning.

  • chdir("") and chdir(undef) now give a deprecation warning because they cause a possible unintentional chdir to the home directory. Say chdir() if you really mean that.

  • Two new debugging options have been added: if you have compiled your Perl with debugging, you can use the -DT [561] and -DR options to trace tokenising and to add reference counts to displaying variables, respectively.

  • The lexical warnings category "deprecated" is no longer a sub-category of the "syntax" category. It is now a top-level category in its own right.

  • Unadorned dump() will now give a warning suggesting to use explicit CORE::dump() if that's what really is meant.

  • The "Unrecognized escape" warning has been extended to include \8, \9, and \_. There is no need to escape any of the \w characters.

  • All regular expression compilation error messages are now hopefully easier to understand both because the error message now comes before the failed regex and because the point of failure is now clearly marked by a <-- HERE marker.

  • Various I/O (and socket) functions like binmode(), close(), and so forth now more consistently warn if they are used illogically either on a yet unopened or on an already closed filehandle (or socket).

  • Using lstat() on a filehandle now gives a warning. (It's a non-sensical thing to do.)

  • The -M and -m options now warn if you didn't supply the module name.

  • If you in use specify a required minimum version, modules matching the name and but not defining a $VERSION will cause a fatal failure.

  • Using negative offset for vec() in lvalue context is now a warnable offense.

  • Odd number of arguments to overload::constant now elicits a warning.

  • Odd number of elements in anonymous hash now elicits a warning.

  • The various "opened only for", "on closed", "never opened" warnings drop the main:: prefix for filehandles in the main package, for example STDIN instead of main::STDIN.

  • Subroutine prototypes are now checked more carefully, you may get warnings for example if you have used non-prototype characters.

  • If an attempt to use a (non-blessed) reference as an array index is made, a warning is given.

  • push @a; and unshift @a; (with no values to push or unshift) now give a warning. This may be a problem for generated and evaled code.

  • If you try to pack in the perlfunc manpage a number less than 0 or larger than 255 using the "C" format you will get an optional warning. Similarly for the "c" format and a number less than -128 or more than 127.

  • pack P format now demands an explicit size.

  • unpack w now warns of unterminated compressed integers.

  • Warnings relating to the use of PerlIO have been added.

  • Certain regex modifiers such as (?o) make sense only if applied to the entire regex. You will get an optional warning if you try to do otherwise.

  • Variable length lookbehind has not yet been implemented, trying to use it will tell that.

  • Using arrays or hashes as references (e.g. %foo->{bar} has been deprecated for a while. Now you will get an optional warning.

  • Warnings relating to the use of the new restricted hashes feature have been added.

  • Self-ties of arrays and hashes are not supported and fatal errors will happen even at an attempt to do so.

  • Using sort in scalar context now issues an optional warning. This didn't do anything useful, as the sort was not performed.

  • Using the /g modifier in split() is meaningless and will cause a warning.

  • Using splice() past the end of an array now causes a warning.

  • Malformed Unicode encodings (UTF-8 and UTF-16) cause a lot of warnings, as does trying to use UTF-16 surrogates (which are unimplemented).

  • Trying to use Unicode characters on an I/O stream without marking the stream's encoding (using open() or binmode()) will cause "Wide character" warnings.

  • Use of v-strings in use/require causes a (backward) portability warning.

  • Warnings relating to the use interpreter threads and their shared data have been added.

Changed Internals

  • PerlIO is now the default.

  • perlapi.pod (a companion to perlguts) now attempts to document the internal API.

  • You can now build a really minimal perl called microperl. Building microperl does not require even running Configure; make -f Makefile.micro should be enough. Beware: microperl makes many assumptions, some of which may be too bold; the resulting executable may crash or otherwise misbehave in wondrous ways. For careful hackers only.

  • Added rsignal(), whichsig(), do_join(), op_clear, op_null, ptr_table_clear(), ptr_table_free(), sv_setref_uv(), and several UTF-8 interfaces to the publicised API. For the full list of the available APIs see the perlapi manpage.

  • Made possible to propagate customised exceptions via croak()ing.

  • Now xsubs can have attributes just like subs. (Well, at least the built-in attributes.)

  • dTHR and djSP have been obsoleted; the former removed (because it's a no-op) and the latter replaced with dSP.

  • PERL_OBJECT has been completely removed.

  • The MAGIC constants (e.g. 'P') have been macrofied (e.g. PERL_MAGIC_TIED) for better source code readability and maintainability.

  • The regex compiler now maintains a structure that identifies nodes in the compiled bytecode with the corresponding syntactic features of the original regex expression. The information is attached to the new offsets member of the struct regexp. See the perldebguts manpage for more complete information.

  • The C code has been made much more gcc -Wall clean. Some warning messages still remain in some platforms, so if you are compiling with gcc you may see some warnings about dubious practices. The warnings are being worked on.

  • perly.c, sv.c, and sv.h have now been extensively commented.

  • Documentation on how to use the Perl source repository has been added to Porting/repository.pod.

  • There are now several profiling make targets.

Security Vulnerability Closed [561]

(This change was already made in 5.7.0 but bears repeating here.) (5.7.0 came out before 5.6.1: the development branch 5.7 released earlier than the maintenance branch 5.6)

A potential security vulnerability in the optional suidperl component of Perl was identified in August 2000. suidperl is neither built nor installed by default. As of November 2001 the only known vulnerable platform is Linux, most likely all Linux distributions. CERT and various vendors and distributors have been alerted about the vulnerability. See http://www.cpan.org/src/5.0/sperl-2000-08-05/sperl-2000-08-05.txt for more information.

The problem was caused by Perl trying to report a suspected security exploit attempt using an external program, /bin/mail. On Linux platforms the /bin/mail program had an undocumented feature which when combined with suidperl gave access to a root shell, resulting in a serious compromise instead of reporting the exploit attempt. If you don't have /bin/mail, or if you have 'safe setuid scripts', or if suidperl is not installed, you are safe.

The exploit attempt reporting feature has been completely removed from Perl 5.8.0 (and the maintenance release 5.6.1, and it was removed also from all the Perl 5.7 releases), so that particular vulnerability isn't there anymore. However, further security vulnerabilities are, unfortunately, always possible. The suidperl functionality is most probably going to be removed in Perl 5.10. In any case, suidperl should only be used by security experts who know exactly what they are doing and why they are using suidperl instead of some other solution such as sudo ( see http://www.courtesan.com/sudo/ ).

New Tests

Several new tests have been added, especially for the lib and ext subsections. There are now about 69 000 individual tests (spread over about 700 test scripts), in the regression suite (5.6.1 has about 11 700 tests, in 258 test scripts) The exact numbers depend on the platform and Perl configuration used. Many of the new tests are of course introduced by the new modules, but still in general Perl is now more thoroughly tested.

Because of the large number of tests, running the regression suite will take considerably longer time than it used to: expect the suite to take up to 4-5 times longer to run than in perl 5.6. On a really fast machine you can hope to finish the suite in about 6-8 minutes (wallclock time).

The tests are now reported in a different order than in earlier Perls. (This happens because the test scripts from under t/lib have been moved to be closer to the library/extension they are testing.)

Known Problems

The Compiler Suite Is Still Very Experimental

The compiler suite is slowly getting better but it continues to be highly experimental. Use in production environments is discouraged.

Localising Tied Arrays and Hashes Is Broken

    local %tied_array;

doesn't work as one would expect: the old value is restored incorrectly. This will be changed in a future release, but we don't know yet what the new semantics will exactly be. In any case, the change will break existing code that relies on the current (ill-defined) semantics, so just avoid doing this in general.

Building Extensions Can Fail Because Of Largefiles

Some extensions like mod_perl are known to have issues with `largefiles', a change brought by Perl 5.6.0 in which file offsets default to 64 bits wide, where supported. Modules may fail to compile at all, or they may compile and work incorrectly. Currently, there is no good solution for the problem, but Configure now provides appropriate non-largefile ccflags, ldflags, libswanted, and libs in the %Config hash (e.g., $Config{ccflags_nolargefiles}) so the extensions that are having problems can try configuring themselves without the largefileness. This is admittedly not a clean solution, and the solution may not even work at all. One potential failure is whether one can (or, if one can, whether it's a good idea to) link together at all binaries with different ideas about file offsets; all this is platform-dependent.

Modifying $_ Inside for(..)

   for (1..5) { $_++ }

works without complaint. It shouldn't. (You should be able to modify only lvalue elements inside the loops.) You can see the correct behaviour by replacing the 1..5 with 1, 2, 3, 4, 5.

mod_perl 1.26 Doesn't Build With Threaded Perl

Use mod_perl 1.27 or higher.

lib/ftmp-security tests warn 'system possibly insecure'

Don't panic. Read the 'make test' section of INSTALL instead.

libwww-perl (LWP) fails base/date #51

Use libwww-perl 5.65 or later.

PDL failing some tests

Use PDL 2.3.4 or later.

Perl_get_sv

You may get errors like 'Undefined symbol "Perl_get_sv"' or "can't resolve symbol 'Perl_get_sv'", or the symbol may be "Perl_sv_2pv". This probably means that you are trying to use an older shared Perl library (or extensions linked with such) with Perl 5.8.0 executable. Perl used to have such a subroutine, but that is no more the case. Check your shared library path, and any shared Perl libraries in those directories.

Sometimes this problem may also indicate a partial Perl 5.8.0 installation, see Mac OS X dyld undefined symbols for an example and how to deal with it.

Self-tying Problems

Self-tying of arrays and hashes is broken in rather deep and hard-to-fix ways. As a stop-gap measure to avoid people from getting frustrated at the mysterious results (core dumps, most often), it is forbidden for now (you will get a fatal error even from an attempt).

A change to self-tying of globs has caused them to be recursively referenced (see: Two-Phased Garbage Collection in the perlobj manpage). You will now need an explicit untie to destroy a self-tied glob. This behaviour may be fixed at a later date.

Self-tying of scalars and IO thingies works.

ext/threads/t/libc

If this test fails, it indicates that your libc (C library) is not threadsafe. This particular test stress tests the localtime() call to find out whether it is threadsafe. See the perlthrtut manpage for more information.

Failure of Thread (5.005-style) tests

Note that support for 5.005-style threading is deprecated, experimental and practically unsupported. In 5.10, it is expected to be removed. You should migrate your code to ithreads.

The following tests are known to fail due to fundamental problems in the 5.005 threading implementation. These are not new failures--Perl 5.005_0x has the same bugs, but didn't have these tests.

 ../ext/B/t/xref.t                    255 65280    14   12  85.71%  3-14
 ../ext/List/Util/t/first.t           255 65280     7    4  57.14%  2 5-7
 ../lib/English.t                       2   512    54    2   3.70%  2-3
 ../lib/FileCache.t                                 5    1  20.00%  5
 ../lib/Filter/Simple/t/data.t                      6    3  50.00%  1-3
 ../lib/Filter/Simple/t/filter_only.                9    3  33.33%  1-2 5
 ../lib/Math/BigInt/t/bare_mbf.t                 1627    4   0.25%  8 11 1626-1627
 ../lib/Math/BigInt/t/bigfltpm.t                 1629    4   0.25%  10 13 1628-
                                                                    1629
 ../lib/Math/BigInt/t/sub_mbf.t                  1633    4   0.24%  8 11 1632-1633
 ../lib/Math/BigInt/t/with_sub.t                 1628    4   0.25%  9 12 1627-1628
 ../lib/Tie/File/t/31_autodefer.t     255 65280    65   32  49.23%  34-65
 ../lib/autouse.t                                  10    1  10.00%  4
 op/flip.t                                         15    1   6.67%  15

These failures are unlikely to get fixed as 5.005-style threads are considered fundamentally broken. (Basically what happens is that competing threads can corrupt shared global state, one good example being regular expression engine's state.)

Timing problems

The following tests may fail intermittently because of timing problems, for example if the system is heavily loaded.

    t/op/alarm.t
    ext/Time/HiRes/HiRes.t
    lib/Benchmark.t
    lib/Memoize/t/expmod_t.t
    lib/Memoize/t/speed.t

In case of failure please try running them manually, for example

    ./perl -Ilib ext/Time/HiRes/HiRes.t

Tied/Magical Array/Hash Elements Do Not Autovivify

For normal arrays $foo = \$bar[1] will assign undef to $bar[1] (assuming that it didn't exist before), but for tied/magical arrays and hashes such autovivification does not happen because there is currently no way to catch the reference creation. The same problem affects slicing over non-existent indices/keys of a tied/magical array/hash.

Unicode in package/class and subroutine names does not work

One can have Unicode in identifier names, but not in package/class or subroutine names. While some limited functionality towards this does exist as of Perl 5.8.0, that is more accidental than designed; use of Unicode for the said purposes is unsupported.

One reason of this unfinishedness is its (currently) inherent unportability: since both package names and subroutine names may need to be mapped to file and directory names, the Unicode capability of the filesystem becomes important-- and there unfortunately aren't portable answers.

Platform Specific Problems

AIX

  • If using the AIX native make command, instead of just "make" issue "make all". In some setups the former has been known to spuriously also try to run "make install". Alternatively, you may want to use GNU make.

  • In AIX 4.2, Perl extensions that use C++ functions that use statics may have problems in that the statics are not getting initialized. In newer AIX releases, this has been solved by linking Perl with the libC_r library, but unfortunately in AIX 4.2 the said library has an obscure bug where the various functions related to time (such as time() and gettimeofday()) return broken values, and therefore in AIX 4.2 Perl is not linked against libC_r.

  • vac 5.0.0.0 May Produce Buggy Code For Perl

    The AIX C compiler vac version 5.0.0.0 may produce buggy code, resulting in a few random tests failing when run as part of "make test", but when the failing tests are run by hand, they succeed. We suggest upgrading to at least vac version 5.0.1.0, that has been known to compile Perl correctly. "lslpp -L|grep vac.C" will tell you the vac version. See README.aix.

  • If building threaded Perl, you may get compilation warning from pp_sys.c:

      "pp_sys.c", line 4651.39: 1506-280 (W) Function argument assignment between types "unsigned char*" and "const void*" is not allowed.

    This is harmless; it is caused by the getnetbyaddr() and getnetbyaddr_r() having slightly different types for their first argument.

Alpha systems with old gccs fail several tests

If you see op/pack, op/pat, op/regexp, or ext/Storable tests failing in a Linux/alpha or *BSD/Alpha, it's probably time to upgrade your gcc. gccs prior to 2.95.3 are definitely not good enough, and gcc 3.1 may be even better. (RedHat Linux/alpha with gcc 3.1 reported no problems, as did Linux 2.4.18 with gcc 2.95.4.) (In Tru64, it is preferable to use the bundled C compiler.)

AmigaOS

Perl 5.8.0 doesn't build in AmigaOS. It broke at some point during the ithreads work and we could not find Amiga experts to unbreak the problems. Perl 5.6.1 still works for AmigaOS (as does the 5.7.2 development release).

BeOS

The following tests fail on 5.8.0 Perl in BeOS Personal 5.03:

 t/op/lfs............................FAILED at test 17
 t/op/magic..........................FAILED at test 24
 ext/Fcntl/t/syslfs..................FAILED at test 17
 ext/File/Glob/t/basic...............FAILED at test 3
 ext/POSIX/t/sigaction...............FAILED at test 13
 ext/POSIX/t/waitpid.................FAILED at test 1

See the perlbeos manpage (README.beos) for more details.

Cygwin "unable to remap"

For example when building the Tk extension for Cygwin, you may get an error message saying "unable to remap". This is known problem with Cygwin, and a workaround is detailed in here: http://sources.redhat.com/ml/cygwin/2001-12/msg00894.html

Cygwin ndbm tests fail on FAT

One can build but not install (or test the build of) the NDBM_File on FAT filesystems. Installation (or build) on NTFS works fine. If one attempts the test on a FAT install (or build) the following failures are expected:

 ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1-2 4 16-71
 ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
 ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
 ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7-11
 ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1-4
 run/fresh_perl.t                          97    1   1.03%  91

NDBM_File fails and ODBM_File just coredumps.

If you intend to run only on FAT (or if using AnyDBM_File on FAT), run Configure with the -Ui_ndbm and -Ui_dbm options to prevent NDBM_File and ODBM_File being built.

DJGPP Failures

 t/op/stat............................FAILED at test 29
 lib/File/Find/t/find.................FAILED at test 1
 lib/File/Find/t/taint................FAILED at test 1
 lib/h2xs.............................FAILED at test 15
 lib/Pod/t/eol........................FAILED at test 1
 lib/Test/Harness/t/strap-analyze.....FAILED at test 8
 lib/Test/Harness/t/test-harness......FAILED at test 23
 lib/Test/Simple/t/exit...............FAILED at test 1

The above failures are known as of 5.8.0 with native builds with long filenames, but there are a few more if running under dosemu because of limitations (and maybe bugs) of dosemu:

 t/comp/cpp...........................FAILED at test 3
 t/op/inccode.........................(crash)

and a few lib/ExtUtils tests, and several hundred Encode/t/Aliases.t failures that work fine with long filenames. So you really might prefer native builds and long filenames.

FreeBSD built with ithreads coredumps reading large directories

This is a known bug in FreeBSD 4.5's readdir_r(), it has been fixed in FreeBSD 4.6 (see the perlfreebsd manpage (README.freebsd)).

FreeBSD Failing locale Test 117 For ISO 8859-15 Locales

The ISO 8859-15 locales may fail the locale test 117 in FreeBSD. This is caused by the characters \xFF (y with diaeresis) and \xBE (Y with diaeresis) not behaving correctly when being matched case-insensitively. Apparently this problem has been fixed in the latest FreeBSD releases. ( http://www.freebsd.org/cgi/query-pr.cgi?pr=34308 )

IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5

IRIX with MIPSpro 7.3.1.2m or 7.3.1.3m compiler may fail the List::Util test ext/List/Util/t/shuffle.t by dumping core. This seems to be a compiler error since if compiled with gcc no core dump ensues, and no failures have been seen on the said test on any other platform.

Similarly, building the Digest::MD5 extension has been known to fail with "*** Termination code 139 (bu21)".

The cure is to drop optimization level (Configure -Doptimize=-O2).

HP-UX lib/posix Subtest 9 Fails When LP64-Configured

If perl is configured with -Duse64bitall, the successful result of the subtest 10 of lib/posix may arrive before the successful result of the subtest 9, which confuses the test harness so much that it thinks the subtest 9 failed.

Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint

This is a known bug in the glibc 2.2.5 with long long integers. ( http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=65612 )

Linux With Sfio Fails op/misc Test 48

No known fix.

Mac OS X

Please remember to set your environment variable LC_ALL to "C" (setenv LC_ALL C) before running "make test" to avoid a lot of warnings about the broken locales of Mac OS X.

The following tests are known to fail in Mac OS X 10.1.5 because of buggy (old) implementations of Berkeley DB included in Mac OS X:

 Failed Test                 Stat Wstat Total Fail  Failed  List of Failed
 -------------------------------------------------------------------------
 ../ext/DB_File/t/db-btree.t    0    11    ??   ??       %  ??
 ../ext/DB_File/t/db-recno.t              149    3   2.01%  61 63 65

If you are building on a UFS partition, you will also probably see t/op/stat.t subtest #9 fail. This is caused by Darwin's UFS not supporting inode change time.

Also the ext/POSIX/t/posix.t subtest #10 fails but it is skipped for now because the failure is Apple's fault, not Perl's (blocked signals are lost).

If you Configure with ithreads, ext/threads/t/libc.t will fail. Again, this is not Perl's fault-- the libc of Mac OS X is not threadsafe (in this particular test, the localtime() call is found to be threadunsafe.)

Mac OS X dyld undefined symbols

If after installing Perl 5.8.0 you are getting warnings about missing symbols, for example

    dyld: perl Undefined symbols
    _perl_sv_2pv
    _perl_get_sv

you probably have an old pre-Perl-5.8.0 installation (or parts of one) in /Library/Perl (the undefined symbols used to exist in pre-5.8.0 Perls). It seems that for some reason "make install" doesn't always completely overwrite the files in /Library/Perl. You can move the old Perl shared library out of the way like this:

    cd /Library/Perl/darwin/CORE
    mv libperl.dylib libperlold.dylib

and then reissue "make install". Note that the above of course is extremely disruptive for anything using the /usr/local/bin/perl. If that doesn't help, you may have to try removing all the .bundle files from beneath /Library/Perl, and again "make install"-ing.

OS/2 Test Failures

The following tests are known to fail on OS/2 (for clarity only the failures are shown, not the full error messages):

 ../lib/ExtUtils/t/Mkbootstrap.t    1   256    18    1   5.56%  8
 ../lib/ExtUtils/t/Packlist.t       1   256    34    1   2.94%  17
 ../lib/ExtUtils/t/basic.t          1   256    17    1   5.88%  14
 lib/os2_process.t                  2   512   227    2   0.88%  174 209
 lib/os2_process_kid.t                        227    2   0.88%  174 209
 lib/rx_cmprt.t                   255 65280    18    3  16.67%  16-18

op/sprintf tests 91, 129, and 130

The op/sprintf tests 91, 129, and 130 are known to fail on some platforms. Examples include any platform using sfio, and Compaq/Tandem's NonStop-UX.

Test 91 is known to fail on QNX6 (nto), because sprintf '%e',0 incorrectly produces 0.000000e+0 instead of 0.000000e+00.

For tests 129 and 130, the failing platforms do not comply with the ANSI C Standard: lines 19ff on page 134 of ANSI X3.159 1989, to be exact. (They produce something other than "1" and "-1" when formatting 0.6 and -0.6 using the printf format "%.0f"; most often, they produce "0" and "-0".)

SCO

The socketpair tests are known to be unhappy in SCO 3.2v5.0.4:

 ext/Socket/socketpair.t...............FAILED tests 15-45

Solaris 2.5

In case you are still using Solaris 2.5 (aka SunOS 5.5), you may experience failures (the test core dumping) in lib/locale.t. The suggested cure is to upgrade your Solaris.

Solaris x86 Fails Tests With -Duse64bitint

The following tests are known to fail in Solaris x86 with Perl configured to use 64 bit integers:

 ext/Data/Dumper/t/dumper.............FAILED at test 268
 ext/Devel/Peek/Peek..................FAILED at test 7

SUPER-UX (NEC SX)

The following tests are known to fail on SUPER-UX:

 op/64bitint...........................FAILED tests 29-30, 32-33, 35-36
 op/arith..............................FAILED tests 128-130
 op/pack...............................FAILED tests 25-5625
 op/pow................................
 op/taint..............................# msgsnd failed
 ../ext/IO/lib/IO/t/io_poll............FAILED tests 3-4
 ../ext/IPC/SysV/ipcsysv...............FAILED tests 2, 5-6
 ../ext/IPC/SysV/t/msg.................FAILED tests 2, 4-6
 ../ext/Socket/socketpair..............FAILED tests 12
 ../lib/IPC/SysV.......................FAILED tests 2, 5-6
 ../lib/warnings.......................FAILED tests 115-116, 118-119

The op/pack failure ("Cannot compress negative numbers at op/pack.t line 126") is serious but as of yet unsolved. It points at some problems with the signedness handling of the C compiler, as do the 64bitint, arith, and pow failures. Most of the rest point at problems with SysV IPC.

Term::ReadKey not working on Win32

Use Term::ReadKey 2.20 or later.

UNICOS/mk

  • During Configure, the test

        Guessing which symbols your C compiler and preprocessor define...

    will probably fail with error messages like

        CC-20 cc: ERROR File = try.c, Line = 3
      The identifier "bad" is undefined.
          bad switch yylook 79bad switch yylook 79bad switch yylook 79bad switch yylook 79#ifdef A29K
      ^
        CC-65 cc: ERROR File = try.c, Line = 3
      A semicolon is expected at this point.

    This is caused by a bug in the awk utility of UNICOS/mk. You can ignore the error, but it does cause a slight problem: you cannot fully benefit from the h2ph utility (see h2ph) that can be used to convert C headers to Perl libraries, mainly used to be able to access from Perl the constants defined using C preprocessor, cpp. Because of the above error, parts of the converted headers will be invisible. Luckily, these days the need for h2ph is rare.

  • If building Perl with interpreter threads (ithreads), the getgrent(), getgrnam(), and getgrgid() functions cannot return the list of the group members due to a bug in the multithreaded support of UNICOS/mk. What this means is that in list context the functions will return only three values, not four.

UTS

There are a few known test failures, see the perluts manpage (README.uts).

VOS (Stratus)

When Perl is built using the native build process on VOS Release 14.5.0 and GNU C++/GNU Tools 2.0.1, all attempted tests either pass or result in TODO (ignored) failures.

VMS

There should be no reported test failures with a default configuration, though there are a number of tests marked TODO that point to areas needing further debugging and/or porting work.

Win32

In multi-CPU boxes, there are some problems with the I/O buffering: some output may appear twice.

XML::Parser not working

Use XML::Parser 2.31 or later.

z/OS (OS/390)

z/OS has rather many test failures but the situation is actually much better than it was in 5.6.0; it's just that so many new modules and tests have been added.

 Failed Test                   Stat Wstat Total Fail  Failed  List of Failed
 ---------------------------------------------------------------------------
 ../ext/Data/Dumper/t/dumper.t              357    8   2.24%  311 314 325 327
                                                              331 333 337 339
 ../ext/IO/lib/IO/t/io_unix.t                 5    4  80.00%  2-5
 ../ext/Storable/t/downgrade.t   12  3072   169   12   7.10%  14-15 46-47 78-79
                                                              110-111 150 161
 ../lib/ExtUtils/t/Constant.t   121 30976    48   48 100.00%  1-48
 ../lib/ExtUtils/t/Embed.t                    9    9 100.00%  1-9
 op/pat.t                                   922    7   0.76%  665 776 785 832-
                                                              834 845
 op/sprintf.t                               224    3   1.34%  98 100 136
 op/tr.t                                     97    5   5.15%  63 71-74
 uni/fold.t                                 780    6   0.77%  61 169 196 661
                                                              710-711

The failures in dumper.t and downgrade.t are problems in the tests, those in io_unix and sprintf are problems in the USS (UDP sockets and printf formats). The pat, tr, and fold failures are genuine Perl problems caused by EBCDIC (and in the pat and fold cases, combining that with Unicode). The Constant and Embed are probably problems in the tests (since they test Perl's ability to build extensions, and that seems to be working reasonably well.)

Unicode Support on EBCDIC Still Spotty

Though mostly working, Unicode support still has problem spots on EBCDIC platforms. One such known spot are the \p{} and \P{} regular expression constructs for code points less than 256: the pP are testing for Unicode code points, not knowing about EBCDIC.

Seen In Perl 5.7 But Gone Now

Time::Piece (previously known as Time::Object) was removed because it was felt that it didn't have enough value in it to be a core module. It is still a useful module, though, and is available from the CPAN.

Perl 5.8 unfortunately does not build anymore on AmigaOS; this broke accidentally at some point. Since there are not that many Amiga developers available, we could not get this fixed and tested in time for 5.8.0. Perl 5.6.1 still works for AmigaOS (as does the 5.7.2 development release).

The PerlIO::Scalar and PerlIO::Via (capitalised) were renamed as PerlIO::scalar and PerlIO::via (all lowercase) just before 5.8.0. The main rationale was to have all core PerlIO layers to have all lowercase names. The "plugins" are named as usual, for example PerlIO::via::QuotedPrint.

The threads::shared::queue and threads::shared::semaphore were renamed as Thread::Queue and Thread::Semaphore just before 5.8.0. The main rationale was to have thread modules to obey normal naming, Thread:: (the threads and threads::shared themselves are more pragma-like, they affect compile-time, so they stay lowercase).

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup and the perl bug database at http://bugs.perl.org/ . There may also be information at http://www.perl.com/ , the Perl Home Page.

If you believe you have an unreported bug, please run the perlbug program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the output of perl -V, will be sent off to perlbug@perl.org to be analysed by the Perl porting team.

SEE ALSO

The Changes file for exhaustive details on what changed.

The INSTALL file for how to build Perl.

The README file for general stuff.

The Artistic and Copying files for copyright information.

HISTORY

Written by Jarkko Hietaniemi <jhi@iki.fi>.


README.aix - Perl version 5 on IBM Unix systems

    • Compiling Perl 5 on AIX
    • OS level
    • Building Dynamic Extensions on AIX
    • The IBM ANSI C Compiler
    • The usenm option
    • Using GNU's gcc for building perl
    • Using Large Files with Perl
    • Threaded Perl
    • 64-bit Perl
    • AIX 4.2 and extensions using C++ with statics
  • AUTHOR
  • DATE

NAME

README.aix - Perl version 5 on IBM Unix (AIX) systems

DESCRIPTION

This document describes various features of IBM's Unix operating system (AIX) that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

Compiling Perl 5 on AIX

When compiling Perl, you must use an ANSI C compiler. AIX does not ship an ANSI compliant C-compiler with AIX by default, but binary builds of gcc for AIX are widely available.

At the moment of writing, AIX supports two different native C compilers, for which you have to pay: xlC and vac. If you decide to use either of these two (which is quite a lot easier than using gcc), be sure to upgrade to the latest available patch level. Currently:

    xlC.C     3.1.4.10 or 3.6.6.0 or 4.0.2.2 or 5.0.2.9 or 6.0.0.3
    vac.C     4.4.0.3  or 5.0.2.6 or 6.0.0.1

note that xlC has the OS version in the name as of version 4.0.2.0, so you will find xlC.C for AIX-5.0 as package

    xlC.aix50.rte   5.0.2.0 or 6.0.0.3

subversions are not the same "latest" on all OS versions. For example, the latest xlC-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.

Perl can be compiled with either IBM's ANSI C compiler or with gcc. The former is recommended, as not only can it compile Perl with no difficulty, but also can take advantage of features listed later that require the use of IBM compiler-specific command-line flags.

The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler optimization bugs that affect compiling perl.c and regcomp.c, respectively. If Perl's configuration detects those compiler patch levels, optimization is turned off for the said source code files. Upgrading to at least 5.0.2.0 is recommended.

If you decide to use gcc, make sure your installation is recent and complete, and be sure to read the Perl README file for more gcc-specific details. Please report any hoops you had to jump through to the development team.

OS level

Before installing the patches to the IBM C-compiler you need to know the level of patching for the Operating System. IBM's command 'oslevel' will show the base, but is not always complete (in this example oslevel shows 4.3.NULL, whereas the system might run most of 4.3.THREE):

    # oslevel
    4.3.0.0
    # lslpp -l | grep 'bos.rte '
    bos.rte           4.3.3.75  COMMITTED  Base Operating System Runtime
    bos.rte            4.3.2.0  COMMITTED  Base Operating System Runtime
    #

The same might happen to AIX 5.1 or other OS levels. As a side note, perl cannot be built without bos.adt.syscalls and bos.adt.libm installed

    # lslpp -l | egrep "syscalls|libm"
    bos.adt.libm      5.1.0.25  COMMITTED  Base Application Development
    bos.adt.syscalls  5.1.0.36  COMMITTED  System Calls Application
    #

Building Dynamic Extensions on AIX

AIX supports dynamically loadable objects as well as shared libraries. Shared libraries by convention end with the suffix .a, which is a bit misleading, as an archive can contain static as well as dynamic members. For perl dynamically loaded objects we use the .so suffix also used on many other platforms.

Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3 or newer Perl uses the AIX native dynamic loading interface in the so called runtime linking mode instead of the emulated interface that was used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and earlier. This change does break backward compatibility with compiled modules from earlier perl releases. The change was made to make Perl more compliant with other applications like Apache/mod_perl which are using the AIX native interface. This change also enables the use of C++ code with static constructors and destructors in perl extensions, which was not possible using the emulated interface.

The IBM ANSI C Compiler

All defaults for Configure can be used.

If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0, but vac 5.0.2.6 or up is highly recommended. Note that since IBM has removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these versions should be considered obsolete.

Here's a brief lead of how to upgrade the compiler to the latest level. Of course this is subject to changes. You can only upgrade versions from ftp-available updates if the first three digit groups are the same (in where you can skip intermediate unlike the patches in the developer snapshots of perl), or to one version up where the "base" is available. In other words, the AIX compiler patches are cumulative.

 vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
 xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not available)
 # ftp ftp.software.ibm.com
 Connected to service.boulder.ibm.com.
 : welcome message ...
 Name (ftp.software.ibm.com:merijn): anonymous
 331 Guest login ok, send your complete e-mail address as password.
 Password:
 ... accepted login stuff
 ftp> cd /aix/fixes/v4/
 ftp> dir other other.ll
 output to local-file: other.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> dir xlc xlc.ll
 output to local-file: xlc.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> bye
 ... goodbye messages
 # ls -l *.ll
 -rw-rw-rw-   1 merijn   system    1169432 Nov  2 17:29 other.ll
 -rw-rw-rw-   1 merijn   system      29170 Nov  2 17:29 xlc.ll

On AIX 4.2 using xlC, we continue:

 # lslpp -l | fgrep 'xlC.C '
   xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
   xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
 # grep 'xlC.C.3.1.4.*.bff' xlc.ll
 -rw-r--r--   1 45776101 1        6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
 -rw-rw-r--   1 45776101 1        6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
 -rw-r--r--   1 45776101 1        6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
 -rw-r--r--   1 45776101 1        6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
 -rw-r--r--   1 45776101 1        6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
 -rw-rw-r--   1 45776101 1        6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
 -rw-rw-r--   1 45776101 1        6188032 May 22 1997  xlC.C.3.1.4.6.bff
 -rw-rw-r--   1 45776101 1        6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
 -rw-rw-r--   1 45776101 1        6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
 -rw-rw-r--   1 45776101 1        6169600 May 27 1998  xlC.C.3.1.4.9.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
 #

On AIX 4.3 using vac, we continue:

 # lslpp -l | grep 'vac.C '
  vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
  vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
 # grep 'vac.C.5.0.2.*.bff' other.ll
 -rw-rw-r--   1 45776101 1        13592576 Apr 16 2001  vac.C.5.0.2.0.bff
 -rw-rw-r--   1 45776101 1        14133248 Apr  9 2002  vac.C.5.0.2.3.bff
 -rw-rw-r--   1 45776101 1        14173184 May 20 2002  vac.C.5.0.2.4.bff
 -rw-rw-r--   1 45776101 1        14192640 Nov 22 2002  vac.C.5.0.2.6.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
 #

Likewise on all other OS levels. Then execute the following command, and fill in its choices

 # smit install_update
  -> Install and Update from LATEST Available Software
  * INPUT device / directory for software [ vac.C.5.0.2.6.bff    ]
  [ OK ]
  [ OK ]

Follow the messages ... and you're done.

If you like a more web-like approach, a good start point can be http://www14.software.ibm.com/webapp/download/downloadaz.jsp and click "C for AIX", and follow the instructions.

The usenm option

If linking miniperl

 cc -o miniperl ... miniperlmain.o opmini.o perl.o ... -lm -lc ...

causes error like this

 ld: 0711-317 ERROR: Undefined symbol: .aintl
 ld: 0711-317 ERROR: Undefined symbol: .copysignl
 ld: 0711-317 ERROR: Undefined symbol: .syscall
 ld: 0711-317 ERROR: Undefined symbol: .eaccess
 ld: 0711-317 ERROR: Undefined symbol: .setresuid
 ld: 0711-317 ERROR: Undefined symbol: .setresgid
 ld: 0711-317 ERROR: Undefined symbol: .setproctitle
 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.

you could retry with

 make realclean
 rm config.sh
 ./Configure -Dusenm ...

which makes Configure to use the nm tool when scanning for library symbols, which usually is not done in AIX.

Related to this, you probably should not use the -r option of Configure in AIX, because that affects of how the nm tool is used.

Using GNU's gcc for building perl

Using gcc-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box, as do recent gcc-2.9 builds available directly from IBM as part of their Linux compatibility packages, available here:

  http://www.ibm.com/servers/aix/products/aixos/linux/

Using Large Files with Perl

Should yield no problems.

Threaded Perl

Threads seem to work OK, though at the moment not all tests pass when threads are used in combination with 64-bit configurations.

You may get a warning when doing a threaded build:

  "pp_sys.c", line 4640.39: 1506-280 (W) Function argument assignment between types "unsigned char*" and "const void*" is not allowed.

The exact line number may vary, but if the warning (W) comes from a line line this

  hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);

in the "pp_ghostent" function, you may ignore it safely. The warning is caused by the reentrant variant of gethostbyaddr() having a slightly different prototype than its non-reentrant variant, but the difference is not really significant here.

64-bit Perl

If your AIX is installed with 64-bit support, you can expect 64-bit configurations to work. In combination with threads some tests might still fail.

AIX 4.2 and extensions using C++ with statics

In AIX 4.2 Perl extensions that use C++ functions that use statics may have problems in that the statics are not getting initialized. In newer AIX releases this has been solved by linking Perl with the libC_r library, but unfortunately in AIX 4.2 the said library has an obscure bug where the various functions related to time (such as time() and gettimeofday()) return broken values, and therefore in AIX 4.2 Perl is not linked against the libC_r.

AUTHOR

H.Merijn Brand <h.m.brand@xs4all.nl>

DATE

Version 0.0.6: 23 Dec 2002


perlamiga - Perl under Amiga OS

  • NOTE
  • SYNOPSIS
  • DESCRIPTION
    • Prerequisites for Compiling Perl on AmigaOS
    • Starting Perl programs under AmigaOS
    • Shortcomings of Perl under AmigaOS
  • INSTALLATION
  • Accessing documentation
    • Manpages for Perl on AmigaOS
    • Perl HTML Documentation on AmigaOS
    • Perl GNU Info Files on AmigaOS
    • Perl LaTeX Documentation on AmigaOS
  • BUILDING PERL ON AMIGAOS
    • Build Prerequisites for Perl on AmigaOS
    • Getting the Perl Source for AmigaOS
    • Making Perl on AmigaOS
    • Testing Perl on AmigaOS
    • Installing the built Perl on AmigaOS
  • PERL 5.8.0 BROKEN IN AMIGAOS
  • AUTHORS
  • SEE ALSO

NAME

perlamiga - Perl under Amiga OS

NOTE

Perl 5.8.0 cannot be built in AmigaOS. You can use either the maintenance release Perl 5.6.1 or the development release Perl 5.7.2 in AmigaOS. See PERL 5.8.0 BROKEN IN AMIGAOS if you want to help fixing this problem.

SYNOPSIS

One can read this document in the following formats:

        man perlamiga
        multiview perlamiga.guide

to list some (not all may be available simultaneously), or it may be read as is: either as README.amiga, or pod/perlamiga.pod.

A recent version of perl for the Amiga can be found at the Geek Gadgets section of the Aminet:

      http://www.aminet.net/~aminet/dev/gg/index.html

DESCRIPTION

Prerequisites for Compiling Perl on AmigaOS

Unix emulation for AmigaOS: ixemul.library

You need the Unix emulation for AmigaOS, whose most important part is ixemul.library. For a minimum setup, get the latest versions of the following packages from the Aminet archives ( http://www.aminet.net/~aminet/ ):

        ixemul-bin
        ixemul-env-bin
        pdksh-bin

Note also that this is a minimum setup; you might want to add other packages of ADE (the Amiga Developers Environment).

Version of Amiga OS

You need at the very least AmigaOS version 2.0. Recommended is version 3.1.

Starting Perl programs under AmigaOS

Start your Perl program foo with arguments arg1 arg2 arg3 the same way as on any other platform, by

        perl foo arg1 arg2 arg3

If you want to specify perl options -my_opts to the perl itself (as opposed to your program), use

        perl -my_opts foo arg1 arg2 arg3

Alternately, you can try to get a replacement for the system's Execute command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit of your scripts. Then you can invoke your scripts like under UNIX with

        foo arg1 arg2 arg3

(Note that having *nixish full path to perl /usr/bin/perl is not necessary, perl would be enough, but having full path would make it easier to use your script under *nix.)

Shortcomings of Perl under AmigaOS

Perl under AmigaOS lacks some features of perl under UNIX because of deficiencies in the UNIX-emulation, most notably:

  • fork()

  • some features of the UNIX filesystem regarding link count and file dates

  • inplace operation (the -i switch) without backup file

  • umask() works, but the correct permissions are only set when the file is finally close()d

INSTALLATION

Change to the installation directory (most probably ADE:), and extract the binary distribution:

lha -mraxe x perl-$VERSION-bin.lha

or

tar xvzpf perl-$VERSION-bin.tgz

(Of course you need lha or tar and gunzip for this.)

For installation of the Unix emulation, read the appropriate docs.

Accessing documentation

Manpages for Perl on AmigaOS

If you have man installed on your system, and you installed perl manpages, use something like this:

        man perlfunc
        man less
        man ExtUtils.MakeMaker

to access documentation for different components of Perl. Start with

        man perl

Note: You have to modify your man.conf file to search for manpages in the /ade/lib/perl5/man/man3 directory, or the man pages for the perl library will not be found.

Note that dot (.) is used as a package separator for documentation for packages, and as usual, sometimes you need to give the section - 3 above - to avoid shadowing by the less(1) manpage.

Perl HTML Documentation on AmigaOS

If you have some WWW browser available, you can build HTML docs. Cd to directory with .pod files, and do like this

        cd /ade/lib/perl5/pod
        pod2html

After this you can direct your browser the file perl.html in this directory, and go ahead with reading docs.

Alternatively you may be able to get these docs prebuilt from CPAN.

Perl GNU Info Files on AmigaOS

Users of Emacs would appreciate it very much, especially with CPerl mode loaded. You need to get latest pod2info from CPAN, or, alternately, prebuilt info pages.

Perl LaTeX Documentation on AmigaOS

Can be constructed using pod2latex.

BUILDING PERL ON AMIGAOS

Here we discuss how to build Perl under AmigaOS.

Build Prerequisites for Perl on AmigaOS

You need to have the latest ixemul (Unix emulation for Amiga) from Aminet.

Getting the Perl Source for AmigaOS

You can either get the latest perl-for-amiga source from Ninemoons and extract it with:

  tar xvzpf perl-$VERSION-src.tgz

or get the official source from CPAN:

  http://www.cpan.org/src/5.0

Extract it like this

  tar xvzpf perl-$VERSION.tar.gz

You will see a message about errors while extracting Configure. This is normal and expected. (There is a conflict with a similarly-named file configure, but it causes no harm.)

Making Perl on AmigaOS

Remember to use a hefty wad of stack (I use 2000000)

  sh configure.gnu --prefix=/gg

Now type

  make depend

Now!

  make

Testing Perl on AmigaOS

Now run

  make test

Some tests will be skipped because they need the fork() function:

io/pipe.t, op/fork.t, lib/filehand.t, lib/open2.t, lib/open3.t, lib/io_pipe.t, lib/io_sock.t

Installing the built Perl on AmigaOS

Run

  make install

PERL 5.8.0 BROKEN IN AMIGAOS

As told above, Perl 5.6.1 was still good in AmigaOS, as was 5.7.2. After Perl 5.7.2 (change #11423, see the Changes file, and the file pod/perlhack.pod for how to get the individual changes) Perl dropped its internal support for vfork(), and that was very probably the step that broke AmigaOS (since the ixemul library has only vfork). The build finally fails when the ext/DynaLoader is being built, and PERL ends up as "0" in the produced Makefile, trying to run "0" does not quite work. Also, executing miniperl in backticks seems to generate nothing: very probably related to the (v)fork problems. Fixing the breakage requires someone quite familiar with the ixemul library, and how one is supposed to run external commands in AmigaOS without fork().

AUTHORS

Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de Jan-Erik Karlsson, trg@privat.utfors.se

SEE ALSO

perl(1).


README.apollo - Perl version 5 on Apollo DomainOS

  • AUTHOR

NAME

README.apollo - Perl version 5 on Apollo DomainOS

DESCRIPTION

The following tests are known to fail as of Perl 5.005_03:

comp/decl..........FAILED at test 0 op/write...........FAILED at test 0 lib/filefind.......FAILED at test 2 lib/io_udp.........FAILED at test 2 lib/findbin........stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 162 stat(/ressel/ABT/USER/vta/jk/proj.local/perl/perl5.005_03-MAINT_TRIAL_5/t/lib/): No such file or directory at ../lib/FindBin.pm line 163 FAILED at test 1

AUTHOR

Johann Klasek <jk@auto.tuwien.ac.at>


README.beos - Perl version 5.8+ on BeOS

  • BUILD AND INSTALL
    • Requirements
    • Configure
    • Build
    • Install
  • KNOWN PROBLEMS
  • CONTACT

NAME

README.beos - Perl version 5.8+ on BeOS

DESCRIPTION

This file contains instructions how to build Perl under BeOS and lists known problems.

BUILD AND INSTALL

Requirements

I have built and tested Perl 5.8.6 and 5.9.1 under BeOS R5 x86 net server. I can't say anything with regard to PPC. Since Perl 5.8.0 had been released for BeOS BONE, I suspect, there is a good chance, that it still compiles on a BONE system. The only change I've made, that affects BONE systems is the recognition of whether it is a BONE system or not in hints/beos.sh. Now network socket support should remain enabled on BONE systems. This might as well break the build, though.

As more recent versions of autoconf require flock() support, I wrote a flock() emulation (flock_server) and released it on BeBits:

        http://www.bebits.com/app/4030

If you want to build a Perl with flock() support, you have to install this package first.

Configure

With flock() support:

        CFLAGS=-I/path/to/flock/server/headers ./configure.gnu \
                --prefix=/boot/home/config

Replace /path/to/flock/server/headers with the path to the directory containing the flock.h header.

Without flock() support:

        ./configure.gnu --prefix=/boot/home/config

Build

With flock() support:

        make LDLOADLIBS="-lnet -lflock"

Without flock() support:

        make LDLOADLIBS="-lnet"

-lnet is needed on net server systems only and if the compiler doesn't add it automatically (Be's R5 gcc does, Oliver Tappe's gcc 2.95.3 does not).

Install

Install all perl files:

        make install

Create a symlink for libperl:

        cd ~/config/lib; ln -s perl5/5.8.6/BePC-beos/CORE/libperl.so .

Replace 5.8.6 with your respective version of Perl.

KNOWN PROBLEMS

  • Network socket support is disabled for BeOS R5 net server. I didn't dare yet to try enabling it and see what problems occur.

  • The LFS (large file support) tests (t/op/lfs and xt/Fcntl/t/syslfs) are disabled as seeking beyond 2 GB is broken according to jhi@iki.fi who was the last one checking the BeOS port and updating this file before me. Haven't checked this myself.

  • The t/io/fflush test fails at #6. As far as I can tell, this is caused by a bug in the BeOS pipes implementation that occurs when starting other child processes. In the particular test case a system("perl -e 0") flushes the stdout pipe of another child process.

  • The ext/POSIX/t/waitpid test fails at #1. After all child processes are gone BeOS' waitpid(-1,...) returns 0 instead of -1 (as it should). No idea how to fix this.

CONTACT

For BeOS specifics problems feel free to mail to: Ingo Weinhold <bonefish@cs.tu-berlin.de>

Last update: 2004-12-16


README.BS2000 - building and installing Perl for BS2000.

    • gzip on BS2000
    • bison on BS2000
    • Unpacking Perl Distribution on BS2000
    • Compiling Perl on BS2000
    • Testing Perl on BS2000
    • Installing Perl on BS2000
    • Using Perl in the Posix-Shell of BS2000
    • Using Perl in "native" BS2000
    • Floating point anomalies on BS2000
    • Using PerlIO and different encodings on ASCII and EBCDIC partitions
  • AUTHORS
  • SEE ALSO
    • Mailing list
  • HISTORY

NAME

README.BS2000 - building and installing Perl for BS2000.

SYNOPSIS

This document will help you Configure, build, test and install Perl on BS2000 in the POSIX subsystem.

DESCRIPTION

This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD V3.1A or later. It may work on other versions, but we started porting and testing it with 3.1A and are currently using Version V4.0A.

You may need the following GNU programs in order to install perl:

gzip on BS2000

We used version 1.2.4, which could be installed out of the box with one failure during 'make check'.

bison on BS2000

The yacc coming with BS2000 POSIX didn't work for us. So we had to use bison. We had to make a few changes to perl in order to use the pure (reentrant) parser of bison. We used version 1.25, but we had to add a few changes due to EBCDIC. See below for more details concerning yacc.

Unpacking Perl Distribution on BS2000

To extract an ASCII tar archive on BS2000 POSIX you need an ASCII filesystem (we used the mountpoint /usr/local/ascii for this). Now you extract the archive in the ASCII filesystem without I/O-conversion:

cd /usr/local/ascii export IO_CONVERSION=NO gunzip < /usr/local/src/perl.tar.gz | pax -r

You may ignore the error message for the first element of the archive (this doesn't look like a tar archive / skipping to next file...), it's only the directory which will be created automatically anyway.

After extracting the archive you copy the whole directory tree to your EBCDIC filesystem. This time you use I/O-conversion:

cd /usr/local/src IO_CONVERSION=YES cp -r /usr/local/ascii/perl5.005_02 ./

Compiling Perl on BS2000

There is a "hints" file for BS2000 called hints.posix-bc (because posix-bc is the OS name given by `uname`) that specifies the correct values for most things. The major problem is (of course) the EBCDIC character set. We have german EBCDIC version.

Because of our problems with the native yacc we used GNU bison to generate a pure (=reentrant) parser for perly.y. So our yacc is really the following script:

-----8<-----/usr/local/bin/yacc-----8<----- #! /usr/bin/sh

# Bison as a reentrant yacc:

# save parameters: params="" while [[ $# -gt 1 ]]; do params="$params $1" shift done

# add flag %pure_parser:

tmpfile=/tmp/bison.$$.y echo %pure_parser > $tmpfile cat $1 >> $tmpfile

# call bison:

echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)" /usr/local/bin/bison --yacc $params $tmpfile

# cleanup:

rm -f $tmpfile -----8<----------8<-----

We still use the normal yacc for a2p.y though!!! We made a softlink called byacc to distinguish between the two versions:

ln -s /usr/bin/yacc /usr/local/bin/byacc

We build perl using GNU make. We tried the native make once and it worked too.

Testing Perl on BS2000

We still got a few errors during make test. Some of them are the result of using bison. Bison prints parser error instead of syntax error, so we may ignore them. The following list shows our errors, your results may differ:

op/numconvert.......FAILED tests 1409-1440 op/regexp...........FAILED tests 483, 496 op/regexp_noamp.....FAILED tests 483, 496 pragma/overload.....FAILED tests 152-153, 170-171 pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207 lib/bigfloat........FAILED tests 351-352, 355 lib/bigfltpm........FAILED tests 354-355, 358 lib/complex.........FAILED tests 267, 487 lib/dumper..........FAILED tests 43, 45 Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.

Installing Perl on BS2000

We have no nroff on BS2000 POSIX (yet), so we ignored any errors while installing the documentation.

Using Perl in the Posix-Shell of BS2000

BS2000 POSIX doesn't support the shebang notation (#!/usr/local/bin/perl), so you have to use the following lines instead:

: # use perl eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}' if $running_under_some_shell;

Using Perl in "native" BS2000

We don't have much experience with this yet, but try the following:

Copy your Perl executable to a BS2000 LLM using bs2cp:

bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'

Now you can start it with the following (SDF) command:

/START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV

First you get the BS2000 commandline prompt ('*'). Here you may enter your parameters, e.g. -e 'print "Hello World!\\n";' (note the double backslash!) or -w and the name of your Perl script. Filenames starting with / are searched in the Posix filesystem, others are searched in the BS2000 filesystem. You may even use wildcards if you put a % in front of your filename (e.g. -w checkfiles.pl %*.c). Read your C/C++ manual for additional possibilities of the commandline prompt (look for PARAMETER-PROMPTING).

Floating point anomalies on BS2000

There appears to be a bug in the floating point implementation on BS2000 POSIX systems such that calling int() on the product of a number and a small magnitude number is not the same as calling int() on the quotient of that number and a large magnitude number. For example, in the following Perl code:

    my $x = 100000.0;
    my $y = int($x * 1e-5) * 1e5; # '0'
    my $z = int($x / 1e+5) * 1e5;  # '100000'
    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000

Although one would expect the quantities $y and $z to be the same and equal to 100000 they will differ and instead will be 0 and 100000 respectively.

Using PerlIO and different encodings on ASCII and EBCDIC partitions

Since version 5.8 Perl uses the new PerlIO on BS2000. This enables you using different encodings per IO channel. For example you may use

    use Encode;
    open($f, ">:encoding(ascii)", "test.ascii");
    print $f "Hello World!\n";
    open($f, ">:encoding(posix-bc)", "test.ebcdic");
    print $f "Hello World!\n";
    open($f, ">:encoding(latin1)", "test.latin1");
    print $f "Hello World!\n";
    open($f, ">:encoding(utf8)", "test.utf8");
    print $f "Hello World!\n";

to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in this example identical to normal EBCDIC). See the documentation of Encode::PerlIO for details.

As the PerlIO layer uses raw IO internally, all this totally ignores the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION environment variable. If you want to get the old behavior, that the BS2000 IO functions determine conversion depending on the filesystem PerlIO still is your friend. You use IO_CONVERSION as usual and tell Perl, that it should use the native IO layer:

    export IO_CONVERSION=YES
    export PERLIO=stdio

Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC partitions. See the documentation of PerlIO (without Encode::!) for further posibilities.

AUTHORS

Thomas Dorner

SEE ALSO

INSTALL, the perlport manpage.

Mailing list

If you are interested in the VM/ESA, z/OS (formerly known as OS/390) and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list. To subscribe, send an empty message to perl-mvs-subscribe@perl.org.

See also:

    http://lists.perl.org/showlist.cgi?name=perl-mvs

There are web archives of the mailing list at:

    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
    http://archive.develooper.com/perl-mvs@perl.org/

HISTORY

This document was originally written by Thomas Dorner for the 5.005 release of Perl.

This document was podified for the 5.6 release of perl 11 July 2000.


perlce - Perl for WinCE

  • BUILD
    • Tools & SDK
    • Make
  • ACKNOWLEDGEMENTS
  • AUTHORS

NAME

perlce - Perl for WinCE

DESCRIPTION

This file gives the instructions for building Perl5.8 and above for WinCE. Please read and understand the terms under which this software is distributed.

BUILD

This section describes the steps to be performed to build PerlCE. You may find additional and newer information about building perl for WinCE using following URL:

  http://perlce.sourceforge.net

There should also be pre-built binaries there.

Don't be confused by large size of downloaded distribution or constructed binaries: entire distribution could be large for WinCE ideology, but you may strip it at your wish and use only required parts.

Tools & SDK

For compiling, you need following:

  • Microsoft Embedded Visual Tools
  • Microsoft Visual C++
  • Rainer Keuchel's celib-sources
  • Rainer Keuchel's console-sources

Needed source files can be downloaded via: www.rainer-keuchel.de/wince/dirlist.html

Make

Please pay attention that starting from 5.8.0 miniperl *is* built and it facilitates in further building process. This means that in addition to compiler installation for mobile device you also need to have Microsoft Visual C++ installed as well.

On the bright side, you do not need to edit any files from ./win32 subdirectory. Normally you only need to edit ./wince/compile.bat to reflect your system and run it.

File ./wince/compile.bat is actually a wrapper to call nmake -f makefile.ce with appropriate parameters and it accepts extra parameters and forwards them to "nmake" command as additional arguments. You should pass target this way.

To prepare distribution you need to do following:

  • go to ./wince subdirectory
  • edit file compile.bat
  • run compile.bat
  • run compile.bat dist

makefile.ce has CROSS_NAME macro, and it is used further to refer to your cross-compilation scheme. You could assign a name to it, but this is not necessary, because by default it is assigned after your machine configuration name, such as "wince-sh3-hpc-wce211", and this is enough to distinguish different builds at the same time. This option could be handy for several different builds on same platform to perform, say, threaded build. In a following example we assume that all required environment variables are set properly for C cross-compiler (a special *.bat file could fit perfectly to this purpose) and your compile.bat has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300".

  compile.bat
  compile.bat dist
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define"
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist

If all goes okay and no errors during a build, you'll get two independent distributions: "wince-mips-pocket-wce300" and "mips-wce300-thr".

Target 'dist' prepares distribution file set. Target 'zipdist' performs same as 'dist' but additionally compresses distribution files into zip archive.

NOTE: during a build there could be created a number (or one) of Config.pm for cross-compilation ("foreign" Config.pm) and those are hidden inside ../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to note, there should be *no* Config.pm for host miniperl. If you'll get an error that perl could not find Config.pm somewhere in building process this means something went wrong. Most probably you forgot to specify a cross-compilation when invoking miniperl.exe to Makefile.PL When building an extension for cross-compilation your command line should look like

  ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL

or just

  ..\miniperl.exe -I..\lib -MCross Makefile.PL

to refer a cross-compilation that was created last time.

If you decided to build with fcrypt.c file, please refer to README.win32 file, as long as all legal considerations and steps to do are exactly same in this case.

All questions related to building for WinCE devices could be asked in perlce-users@lists.sourceforge.net mailing list.

ACKNOWLEDGEMENTS

The port for Win32 was used as a reference.

AUTHORS

Rainer Keuchel (keuchel@netwave.de) Vadim Konovalov (vkonovalov@spb.lucent.com)


README.cygwin - Perl for Cygwin

  • PREREQUISITES FOR COMPILING PERL ON CYGWIN
    • Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
    • Cygwin Configuration
  • CONFIGURE PERL ON CYGWIN
    • Stripping Perl Binaries on Cygwin
    • Optional Libraries for Perl on Cygwin
    • Configure-time Options for Perl on Cygwin
    • Suspicious Warnings on Cygwin
  • MAKE ON CYGWIN
    • Errors on Cygwin
    • ld2 on Cygwin
  • TEST ON CYGWIN
    • File Permissions on Cygwin
    • NDBM_File and ODBM_File do not work on FAT filesystems
    • fork() failures in io_* tests
  • Specific features of the Cygwin port
    • Script Portability on Cygwin
    • Prebuilt methods:
  • INSTALL PERL ON CYGWIN
  • MANIFEST ON CYGWIN
  • BUGS ON CYGWIN
  • AUTHORS
  • HISTORY

NAME

README.cygwin - Perl for Cygwin

SYNOPSIS

This document will help you configure, make, test and install Perl on Cygwin. This document also describes features of Cygwin that will affect how Perl behaves at runtime.

NOTE: There are pre-built Perl packages available for Cygwin and a version of Perl is provided in the normal Cygwin install. If you do not need to customize the configuration, consider using one of those packages.

PREREQUISITES FOR COMPILING PERL ON CYGWIN

Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)

The Cygwin tools are ports of the popular GNU development tools for Win32 platforms. They run thanks to the Cygwin library which provides the UNIX system calls and environment these programs expect. More information about this project can be found at:

  http://www.cygwin.com/

A recent net or commercial release of Cygwin is required.

At the time this document was last updated, Cygwin 1.5.2 was current.

Cygwin Configuration

While building Perl some changes may be necessary to your Cygwin setup so that Perl builds cleanly. These changes are not required for normal Perl usage.

NOTE: The binaries that are built will run on all Win32 versions. They do not depend on your host system (Win9x/WinME, WinNT/Win2K) or your Cygwin configuration (ntea, ntsec, binary/text mounts). The only dependencies come from hard-coded pathnames like /usr/local. However, your host system and Cygwin configuration will affect Perl's runtime behavior (see TEST).

  • PATH

    Set the PATH environment variable so that Configure finds the Cygwin versions of programs. Any Windows directories should be removed or moved to the end of your PATH.

  • nroff

    If you do not have nroff (which is part of the groff package), Configure will not prompt you to install man pages.

  • Permissions

    On WinNT with either the ntea or ntsec CYGWIN settings, directory and file permissions may not be set correctly. Since the build process creates directories and files, to be safe you may want to run a chmod -R +w * on the entire Perl source tree.

    Also, it is a well known WinNT "feature" that files created by a login that is a member of the Administrators group will be owned by the Administrators group. Depending on your umask, you may find that you can not write to files that you just created (because you are no longer the owner). When using the ntsec CYGWIN setting, this is not an issue because it "corrects" the ownership to what you would expect on a UNIX system.

CONFIGURE PERL ON CYGWIN

The default options gathered by Configure with the assistance of hints/cygwin.sh will build a Perl that supports dynamic loading (which requires a shared libperl.dll).

This will run Configure and keep a record:

  ./Configure 2>&1 | tee log.configure

If you are willing to accept all the defaults run Configure with -de. However, several useful customizations are available.

Stripping Perl Binaries on Cygwin

It is possible to strip the EXEs and DLLs created by the build process. The resulting binaries will be significantly smaller. If you want the binaries to be stripped, you can either add a -s option when Configure prompts you,

  Any additional ld flags (NOT including libraries)? [none] -s
  Any special flags to pass to gcc to use dynamic linking? [none] -s
  Any special flags to pass to ld2 to create a dynamically loaded library?
  [none] -s

or you can edit hints/cygwin.sh and uncomment the relevant variables near the end of the file.

Optional Libraries for Perl on Cygwin

Several Perl functions and modules depend on the existence of some optional libraries. Configure will find them if they are installed in one of the directories listed as being used for library searches. Pre-built packages for most of these are available from the Cygwin installer.

  • -lcrypt

    The crypt package distributed with Cygwin is a Linux compatible 56-bit DES crypt port by Corinna Vinschen.

    Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.

    The DES based Ultra Fast Crypt port was done by Alexey Truhan:

      ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz

    NOTE: There are various export restrictions on DES implementations, see the glibc README for more details.

    The MD5 port was done by Andy Piper:

      ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz
  • -lgdbm (use GDBM_File)

    GDBM is available for Cygwin.

    NOTE: The GDBM library only works on NTFS partitions.

  • -ldb (use DB_File)

    BerkeleyDB is available for Cygwin.

    NOTE: The BerkeleyDB library only completely works on NTFS partitions.

  • -lcygipc (use IPC::SysV)

    A port of SysV IPC is available for Cygwin.

    NOTE: This has not been extensively tested. In particular, d_semctl_semun is undefined because it fails a Configure test and on Win9x the shm*() functions seem to hang. It also creates a compile time dependency because perl.h includes <sys/ipc.h> and <sys/sem.h> (which will be required in the future when compiling CPAN modules). CURRENTLY NOT SUPPORTED!

  • -lutil

    Included with the standard Cygwin netrelease is the inetutils package which includes libutil.a.

Configure-time Options for Perl on Cygwin

The INSTALL document describes several Configure-time options. Some of these will work with Cygwin, others are not yet possible. Also, some of these are experimental. You can either select an option when Configure prompts you or you can define (undefine) symbols on the command line.

  • -Uusedl

    Undefining this symbol forces Perl to be compiled statically.

  • -Uusemymalloc

    By default Perl uses the malloc() included with the Perl source. If you want to force Perl to build with the system malloc() undefine this symbol.

  • -Uuseperlio

    Undefining this symbol disables the PerlIO abstraction. PerlIO is now the default; it is not recommended to disable PerlIO.

  • -Dusemultiplicity

    Multiplicity is required when embedding Perl in a C program and using more than one interpreter instance. This works with the Cygwin port.

  • -Duse64bitint

    By default Perl uses 32 bit integers. If you want to use larger 64 bit integers, define this symbol.

  • -Duselongdouble

    gcc supports long doubles (12 bytes). However, several additional long double math functions are necessary to use them within Perl ({atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l, strtold). These are not yet available with Cygwin.

  • -Dusethreads

    POSIX threads are implemented in Cygwin, define this symbol if you want a threaded perl.

  • -Duselargefiles

    Cygwin uses 64-bit integers for internal size and position calculations, this will be correctly detected and defined by Configure.

  • -Dmksymlinks

    Use this to build perl outside of the source tree. This works with Cygwin. Details can be found in the INSTALL document. This is the recommended way to build perl from sources.

Suspicious Warnings on Cygwin

You may see some messages during Configure that seem suspicious.

  • dlsym()

    ld2 is needed to build dynamic libraries, but it does not exist when dlsym() checking occurs (it is not created until make runs). You will see the following message:

      Checking whether your C<dlsym()> needs a leading underscore ...
  ld2: not found
  I can't compile and run the test program.
  I'm guessing that dlsym doesn't need a leading underscore.

    Since the guess is correct, this is not a problem.

  • Win9x and d_eofnblk

    Win9x does not correctly report EOF with a non-blocking read on a closed pipe. You will see the following messages:

      But it also returns -1 to signal EOF, so be careful!
  WARNING: you can't distinguish between EOF and no data!
      *** WHOA THERE!!! ***
      The recommended value for $d_eofnblk on this machine was "define"!
      Keep the recommended value? [y]

    At least for consistency with WinNT, you should keep the recommended value.

  • Compiler/Preprocessor defines

    The following error occurs because of the Cygwin #define of _LONG_DOUBLE:

      Guessing which symbols your C compiler and preprocessor define...
  try.c:<line#>: missing binary operator

    This failure does not seem to cause any problems. With older gcc versions, "parse error" is reported instead of "missing binary operator".

MAKE ON CYGWIN

Simply run make and wait:

  make 2>&1 | tee log.make

Errors on Cygwin

Errors like these are normal:

  ...
  make: [extra.pods] Error 1 (ignored)
  ...
  make: [extras.make] Error 1 (ignored)

ld2 on Cygwin

During make, ld2 will be created and installed in your $installbin directory (where you said to put public executables). It does not wait until the make install process to install the ld2 script, this is because the remainder of the make refers to ld2 without fully specifying its path and does this from multiple subdirectories. The assumption is that $installbin is in your current PATH. If this is not the case make will fail at some point. If this happens, just manually copy ld2 from the source directory to somewhere in your PATH.

TEST ON CYGWIN

There are two steps to running the test suite:

  make test 2>&1 | tee log.make-test
  cd t;./perl harness 2>&1 | tee ../log.harness

The same tests are run both times, but more information is provided when running as ./perl harness.

Test results vary depending on your host system and your Cygwin configuration. If a test can pass in some Cygwin setup, it is always attempted and explainable test failures are documented. It is possible for Perl to pass all the tests, but it is more likely that some tests will fail for one of the reasons listed below.

File Permissions on Cygwin

UNIX file permissions are based on sets of mode bits for {read,write,execute} for each {user,group,other}. By default Cygwin only tracks the Win32 read-only attribute represented as the UNIX file user write bit (files are always readable, files are executable if they have a .{com,bat,exe} extension or begin with #!, directories are always readable and executable). On WinNT with the ntea CYGWIN setting, the additional mode bits are stored as extended file attributes. On WinNT with the ntsec CYGWIN setting, permissions use the standard WinNT security descriptors and access control lists. Without one of these options, these tests will fail (listing not updated yet):

  Failed Test           List of failed
  ------------------------------------
  io/fs.t               5, 7, 9-10
  lib/anydbm.t          2
  lib/db-btree.t        20
  lib/db-hash.t         16
  lib/db-recno.t        18
  lib/gdbm.t            2
  lib/ndbm.t            2
  lib/odbm.t            2
  lib/sdbm.t            2
  op/stat.t             9, 20 (.tmp not an executable extension)

NDBM_File and ODBM_File do not work on FAT filesystems

Do not use NDBM_File or ODBM_File on FAT filesystem. They can be built on a FAT filesystem, but many tests will fail:

 ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1-2 4 16-71
 ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
 ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
 ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7-11
 ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1-4
 run/fresh_perl.t                          97    1   1.03%  91

If you intend to run only on FAT (or if using AnyDBM_File on FAT), run Configure with the -Ui_ndbm and -Ui_dbm options to prevent NDBM_File and ODBM_File being built.

With NTFS (and CYGWIN=ntsec), there should be no problems even if perl was built on FAT.

fork() failures in io_* tests

A fork() failure may result in the following tests failing:

  ext/IO/lib/IO/t/io_multihomed.t
  ext/IO/lib/IO/t/io_sock.t
  ext/IO/lib/IO/t/io_unix.t

See comment on fork in Miscellaneous below.

Specific features of the Cygwin port

Script Portability on Cygwin

Cygwin does an outstanding job of providing UNIX-like semantics on top of Win32 systems. However, in addition to the items noted above, there are some differences that you should know about. This is a very brief guide to portability, more information can be found in the Cygwin documentation.

  • Pathnames

    Cygwin pathnames can be separated by forward (/) or backward (\\) slashes. They may also begin with drive letters (C:) or Universal Naming Codes (//UNC). DOS device names (aux, con, prn, com*, lpt?, nul) are invalid as base filenames. However, they can be used in extensions (e.g., hello.aux). Names may contain all printable characters except these:

      : * ? " < > |

    File names are case insensitive, but case preserving. A pathname that contains a backslash or drive letter is a Win32 pathname (and not subject to the translations applied to POSIX style pathnames).

  • Text/Binary

    When a file is opened it is in either text or binary mode. In text mode a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default mode for an open() is determined by the mode of the mount that underlies the file. Perl provides a binmode() function to set binary mode on files that otherwise would be treated as text. sysopen() with the O_TEXT flag sets text mode on files that otherwise would be treated as binary:

        sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)

    lseek(), tell() and sysseek() only work with files opened in binary mode.

    The text/binary issue is covered at length in the Cygwin documentation.

  • PerlIO

    PerlIO overrides the default Cygwin Text/Binary behaviour. A file will always treated as binary, regardless which mode of the mount it lives on, just like it is in UNIX. So CR/LF translation needs to be requested in either the open() call like this:

      open(FH, ">:crlf", "out.txt");

    which will do conversion from LF to CR/LF on the output, or in the environment settings (add this to your .bashrc):

      export PERLIO=crlf

    which will pull in the crlf PerlIO layer which does LF -> CRLF conversion on every output generated by perl.

  • .exe

    The Cygwin stat(), lstat() and readlink() functions make the .exe extension transparent by looking for foo.exe when you ask for foo (unless a foo also exists). Cygwin does not require a .exe extension, but gcc adds it automatically when building a program. However, when accessing an executable as a normal file (e.g., cp in a makefile) the .exe is not transparent. The install included with Cygwin automatically appends a .exe when necessary.

  • cygwin vs. windows process ids

    Cygwin processes have their own pid, which is different from the underlying windows pid. Most posix compliant Proc functions expect the cygwin pid, but several Win32::Process functions expect the winpid. E.g. $$ is the cygwin pid of /usr/bin/perl, which is not the winpid. Use Cygwin::winpid_to_pid() and Cygwin::winpid_to_pid() to translate between them.

  • chown()

    On WinNT chown() can change a file's user and group IDs. On Win9x chown() is a no-op, although this is appropriate since there is no security model.

  • Miscellaneous

    File locking using the F_GETLK command to fcntl() is a stub that returns ENOSYS.

    Win9x can not rename() an open file (although WinNT can).

    The Cygwin chroot() implementation has holes (it can not restrict file access by native Win32 programs).

    Inplace editing perl -i of files doesn't work without doing a backup of the file being edited perl -i.bak because of windowish restrictions, therefore Perl adds the suffix .bak automatically if you use perl -i without specifying a backup extension.

    Using fork() after loading multiple dlls may fail with an internal cygwin error like the following:

      C:\CYGWIN\BIN\PERL.EXE: *** couldn't allocate memory 0x10000(4128768) for 'C:\CYGWIN\LIB\PERL5\5.6.1\CYGWIN-MULTI\AUTO\SOCKET\SOCKET.DLL' alignment, Win32 error 8
        200 [main] perl 377147 sync_with_child: child -395691(0xB8) died before initialization with status code 0x1
   1370 [main] perl 377147 sync_with_child: *** child state child loading dlls

    Use the rebase utility to resolve the conflicting dll addresses. The rebase package is included in the Cygwin netrelease. Use setup.exe from http://www.cygwin.com/setup.exe to install it and run rebaseall.

Prebuilt methods:

Cwd::cwd

Returns current working directory.

Cygwin::pid_to_winpid

Translates a cygwin pid to the corresponding Windows pid (which may or may not be the same).

Cygwin::winpid_to_pid

Translates a Windows pid to the corresponding cygwin pid (if any).

INSTALL PERL ON CYGWIN

This will install Perl, including man pages.

  make install 2>&1 | tee log.make-install

NOTE: If STDERR is redirected make install will not prompt you to install perl into /usr/bin.

You may need to be Administrator to run make install. If you are not, you must have write access to the directories in question.

Information on installing the Perl documentation in HTML format can be found in the INSTALL document.

MANIFEST ON CYGWIN

These are the files in the Perl release that contain references to Cygwin. These very brief notes attempt to explain the reason for all conditional code. Hopefully, keeping this up to date will allow the Cygwin port to be kept as clean as possible (listing not updated yet).

Documentation
  INSTALL README.cygwin README.win32 MANIFEST
  Changes Changes5.005 Changes5.004 Changes5.6
  pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
  pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
  pod/perlhist.pod pod/perlmodlib.pod perl/buildtoc pod/perltoc.pod
Build, Configure, Make, Install
  cygwin/Makefile.SHs
  cygwin/ld2.in
  cygwin/perlld.in
  ext/IPC/SysV/hints/cygwin.pl
  ext/NDBM_File/hints/cygwin.pl
  ext/ODBM_File/hints/cygwin.pl
  hints/cygwin.sh
  Configure             - help finding hints from uname,
                          shared libperl required for dynamic loading
  Makefile.SH           - linklibperl
  Porting/patchls       - cygwin in port list
  installman            - man pages with :: translated to .
  installperl           - install dll/ld2/perlld, install to pods
  makedepend.SH         - uwinfix
Tests
  t/io/tell.t           - binmode
  t/lib/b.t             - ignore Cwd from os_extras
  t/lib/glob-basic.t    - Win32 directory list access differs from read mode
  t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
  t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
                          (cache manager sometimes preserves ctime of file
                          previously created and deleted), no -u (setuid)
  t/lib/cygwin.t        - builtin cygwin function tests
Compiled Perl Source
  EXTERN.h              - __declspec(dllimport)
  XSUB.h                - __declspec(dllexport)
  cygwin/cygwin.c       - os_extras (getcwd, spawn, Cygwin::winpid_to_pid,
                          Cygwin::pid_to_winpid)
  perl.c                - os_extras
  perl.h                - binmode
  doio.c                - win9x can not rename a file when it is open
  pp_sys.c              - do not define h_errno, pp_system with spawn
  util.c                - use setenv
Compiled Module Source
  ext/POSIX/POSIX.xs    - tzname defined externally
  ext/SDBM_File/sdbm/pair.c
                        - EXTCONST needs to be redefined from EXTERN.h
  ext/SDBM_File/sdbm/sdbm.c
                        - binary open
Perl Modules/Scripts
  lib/Cwd.pm            - hook to internal Cwd::cwd
  lib/ExtUtils/MakeMaker.pm
                        - require MM_Cygwin.pm
  lib/ExtUtils/MM_Cygwin.pm
                        - canonpath, cflags, manifypods, perl_archive
  lib/File/Find.pm      - on remote drives stat() always sets st_nlink to 1
  lib/File/Spec/Unix.pm - preserve //unc
  lib/File/Temp.pm      - no directory sticky bit
  lib/perl5db.pl        - use stdin not /dev/tty
  utils/perldoc.PL      - version comment

BUGS ON CYGWIN

Support for swapping real and effective user and group IDs is incomplete. On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid(). However, additional Cygwin calls for manipulating WinNT access tokens and security contexts are required.

AUTHORS

Charles Wilson <cwilson@ece.gatech.edu>, Eric Fifer <egf7@columbia.edu>, alexander smishlajev <als@turnhere.com>, Steven Morlock <newspost@morlock.net>, Sebastien Barre <Sebastien.Barre@utc.fr>, Teun Burgers <burgers@ecn.nl>, Gerrit P. Haase <gp@familiehaase.de>.

HISTORY

Last updated: 2005-02-11


perldgux - Perl under DG/UX.

  • BUILDING PERL ON DG/UX
    • Non-threaded Perl on DG/UX
    • Threaded Perl on DG/UX
    • Testing Perl on DG/UX
    • Installing the built perl on DG/UX
  • AUTHOR
  • SEE ALSO

NAME

perldgux - Perl under DG/UX.

SYNOPSIS

One can read this document in the following formats:

        man perldgux
        view perl perldgux
        explorer perldgux.html
        info perldgux

to list some (not all may be available simultaneously), or it may be read as is: as README.dgux.

DESCRIPTION

Perl 5.7/8.x for DG/UX ix86 R4.20MU0x

BUILDING PERL ON DG/UX

Non-threaded Perl on DG/UX

Just run ./Configure script from the top directory. Then give "make" to compile.

Threaded Perl on DG/UX

If you are using as compiler GCC-2.95.x rev(DG/UX) an easy solution for configuring perl in your DG/UX machine is to run the command:

./Configure -Dusethreads -Duseithreads -Dusedevel -des

This will automatically accept all the defaults and in particular /usr/local/ as installation directory. Note that GCC-2.95.x rev(DG/UX) knows the switch -pthread which allows it to link correctly DG/UX's -lthread library.

If you want to change the installation directory or have a standard DG/UX with C compiler GCC-2.7.2.x then you have no choice than to do an interactive build by issuing the command:

./Configure -Dusethreads -Duseithreads

In particular with GCC-2.7.2.x accept all the defaults and *watch* out for the message:

    Any additional ld flags (NOT including libraries)? [ -pthread]

Instead of -pthread put here -lthread. CGCC-2.7.2.x that comes with the DG/UX OS does NOT know the -pthread switch. So your build will fail if you choose the defaults. After configuration is done correctly give "make" to compile.

Testing Perl on DG/UX

Issuing a "make test" will run all the tests. If the test lib/ftmp-security gives you as a result something like

    lib/ftmp-security....File::Temp::_gettemp:
    Parent directory (/tmp/) is not safe (sticky bit not set
    when world writable?) at lib/ftmp-security.t line 100

don't panic and just set the sticky bit in your /tmp directory by doing the following as root:

cd / chmod +t /tmp (=set the sticky bit to /tmp).

Then rerun the tests. This time all must be OK.

Installing the built perl on DG/UX

Run the command "make install"

AUTHOR

Takis Psarogiannakopoulos Universirty of Cambridge Centre for Mathematical Sciences Department of Pure Mathematics Wilberforce road Cambridge CB3 0WB , UK email <takis@XFree86.Org>

SEE ALSO

perl(1).


perldos - Perl under DOS, W31, W95.

    • Prerequisites for Compiling Perl on DOS
    • Shortcomings of Perl under DOS
    • Building Perl on DOS
    • Testing Perl on DOS
    • Installation of Perl on DOS
  • BUILDING AND INSTALLING MODULES ON DOS
    • Building Prerequisites for Perl on DOS
    • Unpacking CPAN Modules on DOS
    • Building Non-XS Modules on DOS
    • Building XS Modules on DOS
  • AUTHOR
  • SEE ALSO

NAME

perldos - Perl under DOS, W31, W95.

SYNOPSIS

These are instructions for building Perl under DOS (or w??), using DJGPP v2.03 or later. Under w95 long filenames are supported.

DESCRIPTION

Before you start, you should glance through the README file found in the top-level directory where the Perl distribution was extracted. Make sure you read and understand the terms under which this software is being distributed.

This port currently supports MakeMaker (the set of modules that is used to build extensions to perl). Therefore, you should be able to build and install most extensions found in the CPAN sites.

Detailed instructions on how to build and install perl extension modules, including XS-type modules, is included. See 'BUILDING AND INSTALLING MODULES'.

Prerequisites for Compiling Perl on DOS

DJGPP

DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit, protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible operating systems, by DJ Delorie <dj@delorie.com> and friends.

For more details (FAQ), check out the home of DJGPP at:

        http://www.delorie.com/djgpp/

If you have questions about DJGPP, try posting to the DJGPP newsgroup: comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.

You can find the full DJGPP distribution on any SimTel.Net mirror all over the world. Like:

        ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2*

You need the following files to build perl (or add new modules):

        v2/djdev203.zip
        v2gnu/bnu2112b.zip
        v2gnu/gcc2953b.zip
        v2gnu/bsh204b.zip
        v2gnu/mak3791b.zip
        v2gnu/fil40b.zip
        v2gnu/sed3028b.zip
        v2gnu/txt20b.zip
        v2gnu/dif272b.zip
        v2gnu/grep24b.zip
        v2gnu/shl20jb.zip
        v2gnu/gwk306b.zip
        v2misc/csdpmi5b.zip

or possibly any newer version.

Pthreads

Thread support is not tested in this version of the djgpp perl.

Shortcomings of Perl under DOS

Perl under DOS lacks some features of perl under UNIX because of deficiencies in the UNIX-emulation, most notably:

  • fork() and pipe()

  • some features of the UNIX filesystem regarding link count and file dates

  • in-place operation is a little bit broken with short filenames

  • sockets

Building Perl on DOS

  • Unpack the source package perl5.8*.tar.gz with djtarx. If you want to use long file names under w95 and also to get Perl to pass all its tests, don't forget to use

            set LFN=y
        set FNCASE=y

    before unpacking the archive.

  • Create a "symlink" or copy your bash.exe to sh.exe in your ($DJDIR)/bin directory.

            ln -s bash.exe sh.exe

    [If you have the recommended version of bash for DJGPP, this is already done for you.]

    And make the SHELL environment variable point to this sh.exe:

            set SHELL=c:/djgpp/bin/sh.exe (use full path name!)

    You can do this in djgpp.env too. Add this line BEFORE any section definition:

            +SHELL=%DJDIR%/bin/sh.exe

  • If you have split.exe and gsplit.exe in your path, then rename split.exe to djsplit.exe, and gsplit.exe to split.exe. Copy or link gecho.exe to echo.exe if you don't have echo.exe. Copy or link gawk.exe to awk.exe if you don't have awk.exe.

    [If you have the recommended versions of djdev, shell utilities and gawk, all these are already done for you, and you will not need to do anything.]

  • Chdir to the djgpp subdirectory of perl toplevel and type the following commands:

            set FNCASE=y
        configure.bat

    This will do some preprocessing then run the Configure script for you. The Configure script is interactive, but in most cases you just need to press ENTER. The "set" command ensures that DJGPP preserves the letter case of file names when reading directories. If you already issued this set command when unpacking the archive, and you are in the same DOS session as when you unpacked the archive, you don't have to issue the set command again. This command is necessary *before* you start to (re)configure or (re)build perl in order to ensure both that perl builds correctly and that building XS-type modules can succeed. See the DJGPP info entry for "_preserve_fncase" for more information:

            info libc alphabetical _preserve_fncase

    If the script says that your package is incomplete, and asks whether to continue, just answer with Y (this can only happen if you don't use long filenames or forget to issue "set FNCASE=y" first).

    When Configure asks about the extensions, I suggest IO and Fcntl, and if you want database handling then SDBM_File or GDBM_File (you need to install gdbm for this one). If you want to use the POSIX extension (this is the default), make sure that the stack size of your cc1.exe is at least 512kbyte (you can check this with: stubedit cc1.exe).

    You can use the Configure script in non-interactive mode too. When I built my perl.exe, I used something like this:

            configure.bat -des

    You can find more info about Configure's command line switches in the INSTALL file.

    When the script ends, and you want to change some values in the generated config.sh file, then run

            sh Configure -S

    after you made your modifications.

    IMPORTANT: if you use this -S switch, be sure to delete the CONFIG environment variable before running the script:

            set CONFIG=

  • Now you can compile Perl. Type:

            make

Testing Perl on DOS

Type:

        make test

If you're lucky you should see "All tests successful". But there can be a few failed subtests (less than 5 hopefully) depending on some external conditions (e.g. some subtests fail under linux/dosemu or plain dos with short filenames only).

Installation of Perl on DOS

Type:

        make install

This will copy the newly compiled perl and libraries into your DJGPP directory structure. Perl.exe and the utilities go into ($DJDIR)/bin, and the library goes under ($DJDIR)/lib/perl5. The pod documentation goes under ($DJDIR)/lib/perl5/pod.

BUILDING AND INSTALLING MODULES ON DOS

Building Prerequisites for Perl on DOS

For building and installing non-XS modules, all you need is a working perl under DJGPP. Non-XS modules do not require re-linking the perl binary, and so are simpler to build and install.

XS-type modules do require re-linking the perl binary, because part of an XS module is written in "C", and has to be linked together with the perl binary to be executed. This is required because perl under DJGPP is built with the "static link" option, due to the lack of "dynamic linking" in the DJGPP environment.

Because XS modules require re-linking of the perl binary, you need both the perl binary distribution and the perl source distribution to build an XS extension module. In addition, you will have to have built your perl binary from the source distribution so that all of the components of the perl binary are available for the required link step.

Unpacking CPAN Modules on DOS

First, download the module package from CPAN (e.g., the "Comma Separated Value" text package, Text-CSV-0.01.tar.gz). Then expand the contents of the package into some location on your disk. Most CPAN modules are built with an internal directory structure, so it is usually safe to expand it in the root of your DJGPP installation. Some people prefer to locate source trees under /usr/src (i.e., ($DJDIR)/usr/src), but you may put it wherever seems most logical to you, *EXCEPT* under the same directory as your perl source code. There are special rules that apply to modules which live in the perl source tree that do not apply to most of the modules in CPAN.

Unlike other DJGPP packages, which are normal "zip" files, most CPAN module packages are "gzipped tarballs". Recent versions of WinZip will safely unpack and expand them, *UNLESS* they have zero-length files. It is a known WinZip bug (as of v7.0) that it will not extract zero-length files.

From the command line, you can use the djtar utility provided with DJGPP to unpack and expand these files. For example:

        C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz

This will create the new directory ($DJDIR)/Text-CSV-0.01, filling it with the source for this module.

Building Non-XS Modules on DOS

To build a non-XS module, you can use the standard module-building instructions distributed with perl modules.

    perl Makefile.PL
    make
    make test
    make install

This is sufficient because non-XS modules install only ".pm" files and (sometimes) pod and/or man documentation. No re-linking of the perl binary is needed to build, install or use non-XS modules.

Building XS Modules on DOS

To build an XS module, you must use the standard module-building instructions distributed with perl modules *PLUS* three extra instructions specific to the DJGPP "static link" build environment.

    set FNCASE=y
    perl Makefile.PL
    make
    make perl
    make test
    make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe
    make install

The first extra instruction sets DJGPP's FNCASE environment variable so that the new perl binary which you must build for an XS-type module will build correctly. The second extra instruction re-builds the perl binary in your module directory before you run "make test", so that you are testing with the new module code you built with "make". The third extra instruction installs the perl binary from your module directory into the standard DJGPP binary directory, ($DJDIR)/bin, replacing your previous perl binary.

Note that the MAP_TARGET value *must* have the ".exe" extension or you will not create a "perl.exe" to replace the one in ($DJDIR)/bin.

When you are done, the XS-module install process will have added information to your "perllocal" information telling that the perl binary has been replaced, and what module was installed. You can view this information at any time by using the command:

        perl -S perldoc perllocal

AUTHOR

Laszlo Molnar, laszlo.molnar@eth.ericsson.se [Installing/building perl]

Peter J. Farley III pjfarley@banet.net [Building/installing modules]

SEE ALSO

perl(1).


README.epoc - Perl for EPOC

  • INTRODUCTION
  • INSTALLING PERL ON EPOC
  • STARTING PERL ON EPOC
    • Editors on Epoc
    • Features of Perl on Epoc
    • Restrictions of Perl on Epoc
    • Compiling Perl 5 on the EPOC cross compiling environment
  • SUPPORT STATUS OF PERL ON EPOC
  • AUTHOR
  • LAST UPDATE

NAME

README.epoc - Perl for EPOC

SYNOPSIS

Perl 5 README file for the EPOC Release 5 operating system.

INTRODUCTION

EPOC is an OS for palmtops and mobile phones. For more informations look at: http://www.symbian.com/

This is a port of perl to the epocemx SDK by Eberhard Mattes, which itself uses the SDK by symbian. Essentially epocemx it is a POSIX look alike environment for the EPOC OS. For more information look at: http://epocemx.sourceforge.net/

perl and epocemx runs on Epoc Release 5 machines: Psion 5mx, 5mx Pro, Psion Revo, Psion Netbook and on the Ericsson M128. It may run on Epoc Release 3 Hardware (Series 5 classic), too. For more information about this hardware please refer to http://www.psion.com/

Vendors which like to have support for their devices are free to send me a sample.

INSTALLING PERL ON EPOC

You can download a ready-to-install version from http://www.oflebbe.de/oflebbe/perl/

You will need at least ~6MB free space in order to install and run perl.

Please install the emxusr.sis package from http://epocemx.sourceforge.net/ first.

Install perl.sis on the EPOC machine. If you do not know how to do that, consult your PsiWin documentation.

Perl itself and its standard library is using 4 MB disk space. Unicode support and some other modules are left out. (For details, please look into epoc/createpkg.pl). If you like to use these modules, you are free to copy them from a current perl release.

STARTING PERL ON EPOC

Please use the epocemx shell to start perl. perl integrates with the conventions of epocemx.

Editors on Epoc

A suitable text editor can be downloaded from symbian http://www.symbian.com/developer/downloads/files/editor.zip

Features of Perl on Epoc

The built-in function EPOC::getcwd returns the current directory.

Restrictions of Perl on Epoc

Features are left out, because of restrictions of the POSIX support in EPOC:

  • socket IO is only implemented poorly. You can only use sysread and syswrite on them. The commands read, write, print, <> do not work for sockets. This may change iff epocemx supports sockets.

  • kill, alarm and signals. Do not try to use them. This may be impossible to implement on EPOC.

  • select is missing.

  • binmode does not exist. (No CR LF to LF translation for text files)

  • EPOC does not handle the notion of current drive and current directory very well (i.e. not at all, but it tries hard to emulate one). See PATH.

  • Heap is limited to 4MB.

  • Dynamic loading is not implemented.

Compiling Perl 5 on the EPOC cross compiling environment

Sorry, this is far too short.

  • You will need the epocemx SDK from Eberhard Mattes.

  • Get the Perl sources from your nearest CPAN site.

  • Unpack the sources.

  • Build a native perl from this sources... Make sure to save the miniperl executable as miniperl.native.

    Start again from scratch

          cp epoc/* .
      ./Configure -S
      make
      cp miniperl.native miniperl
      touch miniperl.exe
      make
      perl createpkg.pl
          emxsis perl.pkg perl.sis

SUPPORT STATUS OF PERL ON EPOC

I'm offering this port "as is". You can ask me questions, but I can't guarantee I'll be able to answer them. Since the port to epocemx is quite new, please check the web for updates first.

Very special thanks to Eberhard Mattes for epocemx.

AUTHOR

Olaf Flebbe <olaf@oflebbe.de> http://www.oflebbe.de/oflebbe/perl/

LAST UPDATE

2003-01-18


README.freebsd - Perl version 5 on FreeBSD systems

    • FreeBSD core dumps from readdir_r with ithreads
    • $^X doesn't always contain a full path in FreeBSD
    • Perl will no longer be part of "base FreeBSD"
  • AUTHOR

NAME

README.freebsd - Perl version 5 on FreeBSD systems

DESCRIPTION

This document describes various features of FreeBSD that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

FreeBSD core dumps from readdir_r with ithreads

When perl is configured to use ithreads, it will use re-entrant library calls in preference to non-re-entrant versions. There is a bug in FreeBSD's readdir_r function in versions 4.5 and earlier that can cause a SEGV when reading large directories. A patch for FreeBSD libc is available (see http://www.freebsd.org/cgi/query-pr.cgi?pr=misc/30631 ) which has been integrated into FreeBSD 4.6.

$^X doesn't always contain a full path in FreeBSD

perl 5.8.0 sets $^X where possible to a full path by asking the operating system. On FreeBSD the full path of the perl interpreter is found by reading the symlink /proc/curproc/file. There is a bug on FreeBSD, where the result of reading this symlink is can be wrong in certain circumstances (see http://www.freebsd.org/cgi/query-pr.cgi?pr=35703 ). In these cases perl will fall back to the old behaviour of using C's argv[0] value for $^X.

Perl will no longer be part of "base FreeBSD"

Not as bad as it sounds--what this means is that Perl will no longer be part of the kernel build system of FreeBSD. Perl will still very probably be part of the "default install", and in any case the latest version will be in the ports system. The first FreeBSD version this change will affect is 5.0, all 4.n versions will keep the status quo.

AUTHOR

Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic and Tim Bunce.

Please report any errors, updates, or suggestions to perlbug@perl.org.


README.hpux - Perl version 5 on Hewlett-Packard Unix systems

    • Using perl as shipped with HP-UX
    • Using perl from HP's porting centre
    • Compiling Perl 5 on HP-UX
    • PA-RISC
    • Portability Between PA-RISC Versions
    • PA-RISC 1.0
    • PA-RISC 1.1
    • PA-RISC 2.0
    • Itanium Processor Family and HP-UX
    • Itanium & Itanium 2
    • Building Dynamic Extensions on HP-UX
    • The HP ANSI C Compiler
    • The GNU C Compiler
    • Using Large Files with Perl on HP-UX
    • Threaded Perl on HP-UX
    • 64-bit Perl on HP-UX
    • Oracle on HP-UX
    • GDBM and Threads on HP-UX
    • NFS filesystems and utime(2) on HP-UX
    • perl -P and // and HP-UX
    • HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
  • nss_delete core dump from op/pwent or op/grent
  • AUTHOR
  • DATE

NAME

README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems

DESCRIPTION

This document describes various features of HP's Unix operating system (HP-UX) that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

Using perl as shipped with HP-UX

Application release September 2001, HP-UX 11.00 is the first to ship with Perl. By the time it was perl-5.6.1 in /opt/perl. The first occurrence is on CD 5012-7954 and can be installed using

  swinstall -s /cdrom perl

assuming you have mounted that CD on /cdrom. In this version the following modules were installed:

  ActivePerl::DocTools-0.04   HTML::Parser-3.19   XML::DOM-1.25
  Archive::Tar-0.072          HTML::Tagset-3.03   XML::Parser-2.27
  Compress::Zlib-1.08         MIME::Base64-2.11   XML::Simple-1.05
  Convert::ASN1-0.10          Net-1.07            XML::XPath-1.09
  Digest::MD5-2.11            PPM-2.1.5           XML::XSLT-0.32
  File::CounterFile-0.12      SOAP::Lite-0.46     libwww-perl-5.51
  Font::AFM-1.18              Storable-1.011      libxml-perl-0.07
  HTML-Tree-3.11              URI-1.11            perl-ldap-0.23

The build was a portable hppa-1.1 multithread build that supports large files compiled with gcc-2.9-hppa-991112

If you perform a new installation, then Perl will be installed automatically.

More recent (preinstalled) HP-UX systems have more recent versions of Perl and the updated modules.

Using perl from HP's porting centre

HP porting centre tries very hard to keep up with customer demand and release updates from the Open Source community. Having precompiled Perl binaries available is obvious.

The HP porting centres are limited in what systems they are allowed to port to and they usually choose the two most recent OS versions available. This means that at the moment of writing, there are only HP-UX 11.11 (pa-risc 2.0) and HP-UX 11.23 (Itanium 2) ports available on the porting centres.

HP has asked the porting centre to move Open Source binaries from /opt to /usr/local, so binaries produced since the start of July 2002 are located in /usr/local.

One of HP porting centres URL's is http://hpux.connect.org.uk/ The port currently available is built with GNU gcc.

Compiling Perl 5 on HP-UX

When compiling Perl, you must use an ANSI C compiler. The C compiler that ships with all HP-UX systems is a K&R compiler that should only be used to build new kernels.

Perl can be compiled with either HP's ANSI C compiler or with gcc. The former is recommended, as not only can it compile Perl with no difficulty, but also can take advantage of features listed later that require the use of HP compiler-specific command-line flags.

If you decide to use gcc, make sure your installation is recent and complete, and be sure to read the Perl INSTALL file for more gcc-specific details.

PA-RISC

HP's current Unix systems run on its own Precision Architecture (PA-RISC) chip. HP-UX used to run on the Motorola MC68000 family of chips, but any machine with this chip in it is quite obsolete and this document will not attempt to address issues for compiling Perl on the Motorola chipset.

The most recent version of PA-RISC at the time of this document's last update is 2.0. HP PA-RISC systems are usually refered to with model description "HP 9000".

A complete list of models at the time the OS was built is in the file /usr/sam/lib/mo/sched.models. The first column corresponds to the last part of the output of the "model" command. The second column is the PA-RISC version and the third column is the exact chip type used. (Start browsing at the bottom to prevent confusion ;-)

  # model
  9000/800/L1000-44
  # grep L1000-44 /usr/sam/lib/mo/sched.models
  L1000-44        2.0     PA8500

Portability Between PA-RISC Versions

An executable compiled on a PA-RISC 2.0 platform will not execute on a PA-RISC 1.1 platform, even if they are running the same version of HP-UX. If you are building Perl on a PA-RISC 2.0 platform and want that Perl to also run on a PA-RISC 1.1, the compiler flags +DAportable and +DS32 should be used.

It is no longer possible to compile PA-RISC 1.0 executables on either the PA-RISC 1.1 or 2.0 platforms. The command-line flags are accepted, but the resulting executable will not run when transferred to a PA-RISC 1.0 system.

PA-RISC 1.0

The original version of PA-RISC, HP no longer sells any system with this chip.

The following systems contained PA-RISC 1.0 chips:

  600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850,
  852, 855, 860, 865, 870, 890

PA-RISC 1.1

An upgrade to the PA-RISC design, it shipped for many years in many different system.

The following systems contain with PA-RISC 1.1 chips:

  705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 744, 745,
  747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
  813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
  851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
  B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
  C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
  D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
  G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
  I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
  K420, S700i, S715, S744, S760, T500, T520

PA-RISC 2.0

The most recent upgrade to the PA-RISC design, it added support for 64-bit integer data.

As of the date of this document's last update, the following systems contain PA-RISC 2.0 chips:

  700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
  893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
  C180, C180+, C180-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
  D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
  J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260-EG, K270, K360,
  K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000,
  L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
  T600, V2000, V2200, V2250, V2500, V2600

Just before HP took over Compaq, some systems were renamed. the link that contained the explanation is dead, so here's a short summary:

  HP 9000 A-Class servers, now renamed HP Server rp2400 series.
  HP 9000 L-Class servers, now renamed HP Server rp5400 series.
  HP 9000 N-Class servers, now renamed HP Server rp7400.
  rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
  rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
  rp7410, rp7420, rp8400, rp8420, Superdome

The current naming convention is:

  aadddd
  ||||`+- 00 - 99 relative capacity & newness (upgrades, etc.)
  |||`--- unique number for each architecture to ensure different
  |||     systems do not have the same numbering across
  |||     architectures
  ||`---- 1 - 9 identifies family and/or relative positioning
  ||
  |`----- c = ia32 (cisc)
  |       p = pa-risc
  |       x = ia-64 (Itanium & Itanium 2)
  |       h = housing
  `------ t = tower
          r = rack optimized
          s = super scalable
          b = blade
          sa = appliance

Itanium Processor Family and HP-UX

HP-UX also runs on the new Itanium processor. This requires the use of a different version of HP-UX (currently 11.23 or 11i v2), and with the exception of a few differences detailed below and in later sections, Perl should compile with no problems.

Although PA-RISC binaries can run on Itanium systems, you should not attempt to use a PA-RISC version of Perl on an Itanium system. This is because shared libraries created on an Itanium system cannot be loaded while running a PA-RISC executable.

HP Itanium 2 systems are usually refered to with model description "HP Integrity".

Itanium & Itanium 2

HP also ships servers with the 128-bit Itanium processor(s). As of the date of this document's last update, the following systems contain Itanium or Itanium 2 chips (this is very likely to be out of date):

  BL60p, rx1600, rx1620, rx2600, rx2600hptc, rx2620, rx4610, rx4640,
  rx5670, rx7620, rx8620, rx9610

To see all about your machine, type

  # model
  ia64 hp server rx2600
  # /usr/contrib/bin/machinfo

Building Dynamic Extensions on HP-UX

HP-UX supports dynamically loadable libraries (shared libraries). Shared libraries end with the suffix .sl. On Itanium systems, they end with the suffix .so.

Shared libraries created on a platform using a particular PA-RISC version are not usable on platforms using an earlier PA-RISC version by default. However, this backwards compatibility may be enabled using the same +DAportable compiler flag (with the same PA-RISC 1.0 caveat mentioned above).

Shared libraries created on an Itanium platform cannot be loaded on a PA-RISC platform. Shared libraries created on a PA-RISC platform can only be loaded on an Itanium platform if it is a PA-RISC executable that is attempting to load the PA-RISC library. A PA-RISC shared library cannot be loaded into an Itanium executable nor vice-versa.

To create a shared library, the following steps must be performed:

  1. Compile source modules with +z or +Z flag to create a .o module
     which contains Position-Independent Code (PIC).  The linker will
     tell you in the next step if +Z was needed.
     (For gcc, the appropriate flag is -fpic or -fPIC.)
  2. Link the shared library using the -b flag.  If the code calls
     any functions in other system libraries (e.g., libm), it must
     be included on this line.

(Note that these steps are usually handled automatically by the extension's Makefile).

If these dependent libraries are not listed at shared library creation time, you will get fatal "Unresolved symbol" errors at run time when the library is loaded.

You may create a shared library that refers to another library, which may be either an archive library or a shared library. If this second library is a shared library, this is called a "dependent library". The dependent library's name is recorded in the main shared library, but it is not linked into the shared library. Instead, it is loaded when the main shared library is loaded. This can cause problems if you build an extension on one system and move it to another system where the libraries may not be located in the same place as on the first system.

If the referred library is an archive library, then it is treated as a simple collection of .o modules (all of which must contain PIC). These modules are then linked into the shared library.

Note that it is okay to create a library which contains a dependent library that is already linked into perl.

Some extensions, like DB_File and Compress::Zlib use/require prebuilt libraries for the perl extensions/modules to work. If these libraries are built using the default configuration, it might happen that you run into an error like "invalid loader fixup" during load phase. HP is aware of this problem. Search the HP-UX cxx-dev forums for discussions about the subject. The short answer is that everything (all libraries, everything) must be compiled with +z or +Z to be PIC (position independent code). (For gcc, that would be -fpic or -fPIC). In HP-UX 11.00 or newer the linker error message should tell the name of the offending object file.

A more general approach is to intervene manually, as with an example for the DB_File module, which requires SleepyCat's libdb.sl:

  # cd .../db-3.2.9/build_unix
  # vi Makefile
  ... add +Z to all cflags to create shared objects
  CFLAGS=         -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
                  -I/usr/local/include -I/usr/include/X11R6
  CXXFLAGS=       -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
                  -I/usr/local/include -I/usr/include/X11R6
  # make clean
  # make
  # mkdir tmp
  # cd tmp
  # ar x ../libdb.a
  # ld -b -o libdb-3.2.sl *.o
  # mv libdb-3.2.sl /usr/local/lib
  # rm *.o
  # cd /usr/local/lib
  # rm -f libdb.sl
  # ln -s libdb-3.2.sl libdb.sl

  # cd .../DB_File-1.76
  # make distclean
  # perl Makefile.PL
  # make
  # make test
  # make install

As of db-4.2.x it is no longer needed to do this by hand. Sleepycat has changed the configuration process to add +z on HP-UX automatically.

  # cd .../db-4.2.25/build_unix
  # env CFLAGS=+DA2.0w LDFLAGS=+DA2.0w ../dist/configure

should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.

It is no longer possible to link PA-RISC 1.0 shared libraries (even though the command-line flags are still present).

PA-RISC and Itanium object files are not interchangeable. Although you may be able to use ar to create an archive library of PA-RISC object files on an Itanium system, you cannot link against it using an Itanium link editor.

The HP ANSI C Compiler

When using this compiler to build Perl, you should make sure that the flag -Aa is added to the cpprun and cppstdin variables in the config.sh file (though see the section on 64-bit perl below). If you are using a recent version of the Perl distribution, these flags are set automatically.

The GNU C Compiler

When you are going to use the GNU C compiler (gcc), and you don't have gcc yet, you can either build it yourself from the sources (available from e.g. http://www.gnu.ai.mit.edu/software/gcc/releases.html) or fetch a prebuilt binary from the HP porting center. There are two places where gcc prebuilds can be fetched; the first and best (for HP-UX 11 only) is http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,547,00.html the second is http://hpux.cs.utah.edu/hppd/hpux/Gnu/ where you can also find the GNU binutils package. (Browse through the list, because there are often multiple versions of the same package available).

Above mentioned distributions are depots. H.Merijn Brand has made prebuilt gcc binaries available on http://mirrors.develooper.com/hpux/ and/or http://www.cmve.net/~merijn/ for HP-UX 10.20, HP-UX 11.00, and HP-UX 11.11 (HP-UX 11i) in both 32- and 64-bit versions. These are bzipped tar archives that also include recent GNU binutils and GNU gdb. Read the instructions on that page to rebuild gcc using itself.

On PA-RISC you need a different compiler for 32-bit applications and for 64-bit applications. On PA-RISC, 32-bit objects and 64-bit objects do not mix. Period. There is no different behaviour for HP C-ANSI-C or GNU gcc. So if you require your perl binary to use 64-bit libraries, like Oracle-64bit, you MUST build a 64-bit perl.

Building a 64-bit capable gcc on PA-RISC from source is possible only when you have the HP C-ANSI C compiler or an already working 64-bit binary of gcc available. Best performance for perl is achieved with HP's native compiler.

Using Large Files with Perl on HP-UX

Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes) may be created and manipulated. Three separate methods of doing this are available. Of these methods, the best method for Perl is to compile using the -Duselargefiles flag to Configure. This causes Perl to be compiled using structures and functions in which these are 64 bits wide, rather than 32 bits wide. (Note that this will only work with HP's ANSI C compiler. If you want to compile Perl using gcc, you will have to get a version of the compiler that supports 64-bit operations. See above for where to find it.)

There are some drawbacks to this approach. One is that any extension which calls any file-manipulating C function will need to be recompiled (just follow the usual "perl Makefile.PL; make; make test; make install" procedure).

The list of functions that will need to recompiled is:
creat, | fgetpos, | fopen,
freopen, | fsetpos, | fstat,
fstatvfs, | fstatvfsdev, | ftruncate,
ftw, | lockf, | lseek,
lstat, | mmap, | nftw,
open, | prealloc, | stat,
statvfs, | statvfsdev, | tmpfile,
truncate, | getrlimit, | setrlimit

Another drawback is only valid for Perl versions before 5.6.0. This drawback is that the seek and tell functions (both the builtin version and POSIX module version) will not perform correctly.

It is strongly recommended that you use this flag when you run Configure. If you do not do this, but later answer the question about large files when Configure asks you, you may get a configuration that cannot be compiled, or that does not function as expected.

Threaded Perl on HP-UX

It is possible to compile a version of threaded Perl on any version of HP-UX before 10.30, but it is strongly suggested that you be running on HP-UX 11.00 at least.

To compile Perl with threads, add -Dusethreads to the arguments of Configure. Verify that the -D_POSIX_C_SOURCE=199506L compiler flag is automatically added to the list of flags. Also make sure that -lpthread is listed before -lc in the list of libraries to link Perl with. The hints provided for HP-UX during Configure will try very hard to get this right for you.

HP-UX versions before 10.30 require a separate installation of a POSIX threads library package. Two examples are the HP DCE package, available on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20, April 1999 (B3920-13941)" or the Freely available PTH package, available on H.Merijn's site (http://mirrors.develooper.com/hpux/).

If you are going to use the HP DCE package, the library used for threading is /usr/lib/libcma.sl, but there have been multiple updates of that library over time. Perl will build with the first version, but it will not pass the test suite. Older Oracle versions might be a compelling reason not to update that library, otherwise please find a newer version in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672

reformatted output:

  d3:/usr/lib 106 > what libcma-*.1
  libcma-00000.1:
     HP DCE/9000 1.5               Module: libcma.sl (Export)
                                   Date: Apr 29 1996 22:11:24
  libcma-19739.1:
     HP DCE/9000 1.5 PHSS_19739-40 Module: libcma.sl (Export)
                                   Date: Sep  4 1999 01:59:07
  libcma-20608.1:
     HP DCE/9000 1.5 PHSS_20608    Module: libcma.1 (Export)
                                   Date: Dec  8 1999 18:41:23
  libcma-23672.1:
     HP DCE/9000 1.5 PHSS_23672    Module: libcma.1 (Export)
                                   Date: Apr  9 2001 10:01:06
  d3:/usr/lib 107 >

If you choose for the PTH package, use swinstall to install pth in the default location (/opt/pth), and then make symbolic links to the libraries from /usr/lib

  # cd /usr/lib
  # ln -s /opt/pth/lib/libpth* .

For building perl to support Oracle, it needs to be linked with libcl and libpthread. So even if your perl is an unthreaded build, these libraries might be required. See "Oracle on HP-UX" below.

64-bit Perl on HP-UX

Beginning with HP-UX 11.00, programs compiled under HP-UX can take advantage of the LP64 programming environment (LP64 means Longs and Pointers are 64 bits wide), in which scalar variables will be able to hold numbers larger than 2^32 with complete precision. Perl has proven to be consistent and reliable in 64bit mode since 5.8.1 on all HP-UX 11.xx.

As of the date of this document, Perl is fully 64-bit compliant on HP-UX 11.00 and up for both cc- and gcc builds. If you are about to build a 64-bit perl with GNU gcc, please read the gcc section carefully.

Should a user have the need for compiling Perl in the LP64 environment, use the -Duse64bitall flag to Configure. This will force Perl to be compiled in a pure LP64 environment (with the +DD64 flag for HP C-ANSI-C, with no additional options for GNU gcc 64-bit on PA-RISC, and with -mlp64 for GNU gcc on Itanium). If you want to compile Perl using gcc, you will have to get a version of the compiler that supports 64-bit operations.)

You can also use the -Duse64bitint flag to Configure. Although there are some minor differences between compiling Perl with this flag versus the -Duse64bitall flag, they should not be noticeable from a Perl user's perspective. When configuring -Duse64bitint using a 64bit gcc on a pa-risc architecture, -Duse64bitint is silently promoted to -Duse64bitall.

In both cases, it is strongly recommended that you use these flags when you run Configure. If you do not use do this, but later answer the questions about 64-bit numbers when Configure asks you, you may get a configuration that cannot be compiled, or that does not function as expected.

Oracle on HP-UX

Using perl to connect to Oracle databases through DBI and DBD::Oracle has caused a lot of people many headaches. Read README.hpux in the DBD::Oracle for much more information. The reason to mention it here is that Oracle requires a perl built with libcl and libpthread, the latter even when perl is build without threads. Building perl using all defaults, but still enabling to build DBD::Oracle later on can be achieved using

  Configure -A prepend:libswanted='cl pthread ' ...

Do not forget the space before the trailing quote.

Also note that this does not (yet) work with all configurations, it is known to fail with 64-bit versions of GCC.

GDBM and Threads on HP-UX

If you attempt to compile Perl with threads on an 11.X system and also link in the GDBM library, then Perl will immediately core dump when it starts up. The only workaround at this point is to relink the GDBM library under 11.X, then relink it into Perl.

NFS filesystems and utime(2) on HP-UX

If you are compiling Perl on a remotely-mounted NFS filesystem, the test io/fs.t may fail on test #18. This appears to be a bug in HP-UX and no fix is currently available.

perl -P and // and HP-UX

If HP-UX Perl is compiled with flags that will cause problems if the -P flag of Perl (preprocess Perl code with the C preprocessor before perl sees it) is used. The problem is that //, being a C++-style until-end-of-line comment, will disappear along with the remainder of the line. This means that common Perl constructs like

  s/foo//;

will turn into illegal code

  s/foo

The workaround is to use some other quoting separator than "/", like for example "!":

  s!foo!!;

HP-UX Kernel Parameters (maxdsiz) for Compiling Perl

By default, HP-UX comes configured with a maximum data segment size of 64MB. This is too small to correctly compile Perl with the maximum optimization levels. You can increase the size of the maxdsiz kernel parameter through the use of SAM.

When using the GUI version of SAM, click on the Kernel Configuration icon, then the Configurable Parameters icon. Scroll down and select the maxdsiz line. From the Actions menu, select the Modify Configurable Parameter item. Insert the new formula into the Formula/Value box. Then follow the instructions to rebuild your kernel and reboot your system.

In general, a value of 256MB (or "256*1024*1024") is sufficient for Perl to compile at maximum optimization.

nss_delete core dump from op/pwent or op/grent

You may get a bus error core dump from the op/pwent or op/grent tests. If compiled with -g you will see a stack trace much like the following:

  #0  0xc004216c in  () from /usr/lib/libc.2
  #1  0xc00d7550 in __nss_src_state_destr () from /usr/lib/libc.2
  #2  0xc00d7768 in __nss_src_state_destr () from /usr/lib/libc.2
  #3  0xc00d78a8 in nss_delete () from /usr/lib/libc.2
  #4  0xc01126d8 in endpwent () from /usr/lib/libc.2
  #5  0xd1950 in Perl_pp_epwent () from ./perl
  #6  0x94d3c in Perl_runops_standard () from ./perl
  #7  0x23728 in S_run_body () from ./perl
  #8  0x23428 in perl_run () from ./perl
  #9  0x2005c in main () from ./perl

The key here is the nss_delete call. One workaround for this bug seems to be to create add to the file /etc/nsswitch.conf (at least) the following lines

  group: files
  passwd: files

Whether you are using NIS does not matter. Amazingly enough, the same bug also affects Solaris.

AUTHOR

Jeff Okamoto <okamoto@corp.hp.com> H.Merijn Brand <h.m.brand@xs4all.nl>

With much assistance regarding shared libraries from Marc Sabatella.

DATE

Version 0.7.6: 2005-12-20


README.hurd - Perl version 5 on Hurd

    • Known Problems with Perl on Hurd
  • AUTHOR

NAME

README.hurd - Perl version 5 on Hurd

DESCRIPTION

If you want to use Perl on the Hurd, I recommend using the Debian GNU/Hurd distribution ( see http://www.debian.org/ ), even if an official, stable release has not yet been made. The old "gnu-0.2" binary distribution will most certainly have additional problems.

Known Problems with Perl on Hurd

The Perl test suite may still report some errors on the Hurd. The "lib/anydbm" and "pragma/warnings" tests will almost certainly fail. Both failures are not really specific to the Hurd, as indicated by the test suite output.

The socket tests may fail if the network is not configured. You have to make "/hurd/pfinet" the translator for "/servers/socket/2", giving it the right arguments. Try "/hurd/pfinet --help" for more information.

Here are the statistics for Perl 5.005_62 on my system:

 Failed Test  Status Wstat Total Fail  Failed  List of failed
 -------------------------------------------------------------------------
 lib/anydbm.t                 12    1   8.33%  12
 pragma/warnings             333    1   0.30%  215
 8 tests and 24 subtests skipped.
 Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed, 99.98% okay.

There are quite a few systems out there that do worse!

However, since I am running a very recent Hurd snapshot, in which a lot of bugs that were exposed by the Perl test suite have been fixed, you may encounter more failures. Likely candidates are: "op/stat", "lib/io_pipe", "lib/io_sock", "lib/io_udp" and "lib/time".

In any way, if you're seeing failures beyond those mentioned in this document, please consider upgrading to the latest Hurd before reporting the failure as a bug.

AUTHOR

Mark Kettenis <kettenis@gnu.org>

Last Updated: Fri, 29 Oct 1999 22:50:30 +0200


README.irix - Perl version 5 on Irix systems

    • Building 32-bit Perl in Irix
    • Building 64-bit Perl in Irix
    • About Compiler Versions of Irix
    • Linker Problems in Irix
    • Malloc in Irix
    • Building with threads in Irix
    • Irix 5.3
  • AUTHOR

NAME

README.irix - Perl version 5 on Irix systems

DESCRIPTION

This document describes various features of Irix that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

Building 32-bit Perl in Irix

Use

        sh Configure -Dcc='cc -n32'

to compile Perl 32-bit. Don't bother with -n32 unless you have 7.1 or later compilers (use cc -version to check).

(Building 'cc -n32' is the default.)

Building 64-bit Perl in Irix

Use

        sh Configure -Dcc='cc -64' -Duse64bitint

This requires require a 64-bit MIPS CPU (R8000, R10000, ...)

You can also use

        sh Configure -Dcc='cc -64' -Duse64bitall

but that makes no difference compared with the -Duse64bitint because of the cc -64.

You can also do

        sh Configure -Dcc='cc -n32' -Duse64bitint

to use long longs for the 64-bit integer type, in case you don't have a 64-bit CPU.

If you are using gcc, just

        sh Configure -Dcc=gcc -Duse64bitint

should be enough, the Configure should automatically probe for the correct 64-bit settings.

About Compiler Versions of Irix

Some Irix cc versions, e.g. 7.3.1.1m (try cc -version) have been known to have issues (coredumps) when compiling perl.c. If you've used -OPT:fast_io=ON and this happens, try removing it. If that fails, or you didn't use that, then try adjusting other optimization options (-LNO, -INLINE, -O3 to -O2, etcetera). The compiler bug has been reported to SGI. (Allen Smith <easmith@beatrice.rutgers.edu>)

Linker Problems in Irix

If you get complaints about so_locations then search in the file hints/irix_6.sh for "lddflags" and do the suggested adjustments. (David Billinghurst <David.Billinghurst@riotinto.com.au>)

Malloc in Irix

Do not try to use Perl's malloc, this will lead into very mysterious errors (especially with -Duse64bitall).

Building with threads in Irix

Run Configure with -Duseithreads which will configure Perl with the new Perl 5.8.0 "interpreter threads", see the threads manpage.

The old Perl 5.005 threads is obsolete, unmaintained, and its use is discouraged. If you really want it, run Configure with the -Dusethreads -Duse5005threads options as described in INSTALL.

For either thread model and for Irix 6.2, you have to have the following patches installed:

        1404 Irix 6.2 Posix 1003.1b man pages
        1645 Irix 6.2 & 6.3 POSIX header file updates
        2000 Irix 6.2 Posix 1003.1b support modules
        2254 Pthread library fixes
        2401 6.2 all platform kernel rollup

IMPORTANT: Without patch 2401, a kernel bug in Irix 6.2 will cause your machine to panic and crash when running threaded perl. Irix 6.3 and later are okay.

    Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
    pthreads patches information.

Irix 5.3

While running Configure and when building, you are likely to get quite a few of these warnings:

  ld:
  The shared object /usr/lib/libm.so did not resolve any symbols.
        You may want to remove it from your link line.

Ignore them: in IRIX 5.3 there is no way to quieten ld about this.

During compilation you will see this warning from toke.c:

  uopt: Warning: Perl_yylex: this procedure not optimized because it
        exceeds size threshold; to optimize this procedure, use -Olimit option
        with value >= 4252.

Ignore the warning.

In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3) the following failures are known.

 Failed Test                  Stat Wstat Total Fail  Failed  List of Failed
 --------------------------------------------------------------------------
 ../ext/List/Util/t/shuffle.t    0   139    ??   ??       %  ??
 ../lib/Math/Trig.t            255 65280    29   12  41.38%  24-29
 ../lib/sort.t                   0   138   119   72  60.50%  48-119
 56 tests and 474 subtests skipped.
 Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed, 99.90% okay.

They are suspected to be compiler errors (at least the shuffle.t failure is known from some IRIX 6 setups) and math library errors (the Trig.t failure), but since IRIX 5 is long since end-of-lifed, further fixes for the IRIX are unlikely. If you can get gcc for 5.3, you could try that, too, since gcc in IRIX 6 is a known workaround for at least the shuffle.t and sort.t failures.

AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>

Please report any errors, updates, or suggestions to perlbug@perl.org.


README.linux - Perl version 5 on Linux systems

    • Experimental Support for Sun Studio Compilers for Linux OS
  • AUTHOR

NAME

README.linux - Perl version 5 on Linux systems

DESCRIPTION

This document describes various features of Linux that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

Experimental Support for Sun Studio Compilers for Linux OS

Sun Microsystems has released a port of their Sun Studio compiliers for Linux. As of November 2005, only an alpha version has been released. Until a release of these compilers is made, support for compiling Perl with these compiler experimental.

Also, some special instructions for building Perl with Sun Studio on Linux. Following the normal Configure, you have to run make as follows:

    LDLOADLIBS=-lc make

LDLOADLIBS is an environment variable used by the linker to link modules /ext modules to glibc. Currently, that environment variable is not getting populated by a combination of Config entries and ExtUtil::MakeMaker. While there may be a bug somewhere in Perl's configuration or ExtUtil::MakeMaker causing the problem, the most likely cause is an incomplete understanding of Sun Studio by this author. Further investigation is needed to get this working better.

AUTHOR

Steve Peters <steve@fisharerojo.org>

Please report any errors, updates, or suggestions to perlbug@perl.org.


README.machten - Perl version 5 on Power MachTen systems

    • Perl version 5.8.x and greater not supported
    • Compiling Perl 5.6.x on MachTen
    • Failures during make test on MachTen
    • Building external modules on MachTen
  • AUTHOR
  • DATE

NAME

README.machten - Perl version 5 on Power MachTen systems

DESCRIPTION

This document describes how to build Perl 5 on Power MachTen systems, and discusses a few wrinkles in the implementation.

Perl version 5.8.x and greater not supported

Power MachTen is not supported by versions of Perl later than 5.6.x. If you wish to build a version from the 5.6 track, please obtain a source distribution from the archive at http://cpan.org/src/5.0/ and follow the instructions in its README.machten file.

MachTen is no longer supported by its developers, Tenon Intersystems. A UNIX environment hosted on Mac OS Classic, MachTen has been superseded by Mac OS X and by BSD and Linux implementations for Macintosh hardware. The final version of Power MachTen, 4.1.4, lacks many features found in modern implementations of UNIX, and has a number of bugs. These shortcomings prevent recent versions of Perl from being able to use extensions on MachTen, and cause numerous test suite failures in the perl core.

In September 2003, a discussion on the MachTen mailing list determined that there was no interest in making a later version of Perl build successfully on MachTen. Consequently, support for building Perl under MachTen has been suppressed in Perl distributions published after February 2004. The hints file, hints/machten.sh, remains a part of the distributions for reference purposes.

Compiling Perl 5.6.x on MachTen

To compile perl 5.6.x under MachTen 4.1.4 (and probably earlier versions):

  ./Configure -de
  make
  make test
  make install

This builds and installs a statically-linked perl; MachTen's dynamic linking facilities are not adequate to support Perl's use of dynamically linked libraries. (See hints/machten.sh for more information.)

You should have at least 32 megabytes of free memory on your system before running the make command.

For much more information on building perl -- for example, on how to change the default installation directory -- see INSTALL.

Failures during make test on MachTen

op/lexassign.t

This test may fail when first run after building perl. It does not fail subsequently. The cause is unknown.

pragma/warnings.t

Test 257 fails due to a failure to warn about attempts to read from a filehandle which is a duplicate of stdout when stdout is attached to a pipe. The output of the test contains a block comment which discusses a different failure, not applicable to MachTen.

The root of the problem is that Machten does not assign a file type to either end of a pipe (see the stat manpage), resulting, among other things in Perl's -p test failing on file descriptors belonging to pipes. As a result, perl becomes confused, and the test for reading from a write-only file fails. I am reluctant to patch perl to get around this, as it's clearly an OS bug (about which Tenon has been informed), and limited in its effect on practical Perl programs.

Building external modules on MachTen

To add an external module to perl, build in the normal way, which is documented in the ExtUtils::MakeMaker manpage, or which can be driven automatically by the CPAN module (see the CPAN manpage), which is part of the standard distribution. If you want to install a module which contains XS code (C or C++ source which compiles to object code for linking with perl), you will have to replace your perl binary with a new version containing the new statically-linked object module. The build process tells you how to do this.

There is a gotcha, however, which users usually encounter immediately they respond to CPAN's invitation to install Bundle::CPAN. When installing a bundle -- a group of modules which together achieve some particular purpose, the installation process for later modules in the bundle tends to assume that earlier modules have been fully installed and are available for use. This is not true on a statically-linked system for earlier modules which contain XS code. As a result the installation of the bundle fails. The work-around is not to install the bundle as a one-shot operation, but instead to see what modules it contains, and install these one-at-a-time by hand in the order given.

AUTHOR

Dominic Dunlop <domo@computer.org>

DATE

Version 1.1.0 2004-02-13


README.macos - Perl under Mac OS

  • AUTHOR
  • DATE

NAME

README.macos - Perl under Mac OS (Classic)

SYNOPSIS

This document briefly describes perl under Mac OS (Classic). If you are running perl under Mac OS X, you don't want to be here (unless you are in the Classic environment under Mac OS X).

When we say "Mac OS" below, we mean Mac OS 7, 8, and 9, and not Mac OS X.

DESCRIPTION

The latest perl source itself builds on Mac OS, with some additional pieces. Support for Mac OS is now in the perl core, and MacPerl is kept in close sync with regular perl releases.

To build perl for Mac OS (as an MPW tool), you will need the addition of the macos subdirectory, distributed separately. It includes extra source files, config files, and make files. It also includes extra Mac-specific modules.

To build the MacPerl application, you will also need the macperl directory, which includes the source files for creating the application itself.

All of this is available from the development site, via HTTP (in the MacPerl Installer, which includes all the source and binaries) and anonymous CVS.

        http://dev.macperl.org/

The source is also in the main perl repository in the macperl branch (the 5.6 source is in the maint-5.6/macperl branch).

You will also need compilers and libraries, all of them freely available. These are linked to from the SourceForge site. Go that site for all things having to do with MacPerl development.

MacPerl 5.6.1 and later are supported on Mac OS 8.1 and later, for 68040 and PowerPC architectures. The MPW tool may be used on Mac OS 7.5.5 and 68030 computers.

MacPerl 5.2.0r4 is also available, on the CPAN and on SourceForge. It is based on perl 5.004, and works with Mac OS 7.5.5 and 68030 computers.

AUTHOR

perl was ported to Mac OS by Matthias Neeracher <neeracher@mac.com>. It is currently maintained by Chris Nandor <pudge@pobox.com>.

DATE

Last modified 2002.05.02.


README.macosx - Perl under Mac OS X

    • Installation Prefix
    • SDK support
    • Universal Binary support
    • libperl and Prebinding
    • Updating Apple's Perl
    • Known problems
    • MacPerl
    • Carbon
    • Cocoa
  • Starting From Scratch
  • AUTHOR
  • DATE

NAME

README.macosx - Perl under Mac OS X

SYNOPSIS

This document briefly describes perl under Mac OS X.

DESCRIPTION

The latest Perl release (5.8.8 as of this writing) builds without changes under Mac OS X. Under 10.3 "Panther" and newer OS versions, all self-tests pass, and all standard features are supported.

Earlier Mac OS X releases (10.2 "Jaguar" and older) did not include a completely thread-safe libc, so threading is not fully supported. Also, earlier releases included a buggy libdb, so some of the DB_File tests are known to fail on those releases.

Installation Prefix

The default installation location for this release uses the traditional UNIX directory layout under /usr/local. This is the recommended location for most users, and will leave the Apple-supplied Perl and its modules undisturbed.

Using an installation prefix of '/usr' will result in a directory layout that mirrors that of Apple's default Perl, with core modules stored in '/System/Library/Perl/${version}', CPAN modules stored in '/Library/Perl/${version}', and the addition of '/Network/Library/Perl/${version}' to @INC for modules that are stored on a file server and used by many Macs.

SDK support

First, export the path to the SDK into the build environment:

    export SDK=/Developer/SDKs/MacOSX10.3.9.sdk

Use an SDK by exporting some additions to Perl's 'ccflags' and '..flags' config variables:

    ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc \
                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
                           -F$SDK/System/Library/Frameworks" \
                -Aldflags="-Wl,-syslibroot,$SDK" \
                -de

Universal Binary support

To compile perl as a universal binary (built for both ppc and intel), export the SDK variable as above, selecting the 10.4u SDK:

    export SDK=/Developer/SDKs/MacOSX10.4u.sdk

In addition to the compiler flags used to select the SDK, also add the flags for creating a universal binary:

    ./Configure -Accflags="-arch i686 -arch ppc -nostdinc -B$SDK/usr/include/gcc \
                           -B$SDK/usr/lib/gcc -isystem$SDK/usr/include \
                           -F$SDK/System/Library/Frameworks" \
                -Aldflags="-arch i686 -arch ppc -Wl,-syslibroot,$SDK" \
                -de

Keep in mind that these compiler and linker settings will also be used when building CPAN modules. For XS modules to be compiled as a universal binary, any libraries it links to must also be universal binaries. The system libraries that Apple includes with the 10.4u SDK are all universal, but user-installed libraries may need to be re-installed as universal binaries.

libperl and Prebinding

Mac OS X ships with a dynamically-loaded libperl, but the default for this release is to compile a static libperl. The reason for this is pre-binding. Dynamic libraries can be pre-bound to a specific address in memory in order to decrease load time. To do this, one needs to be aware of the location and size of all previously-loaded libraries. Apple collects this information as part of their overall OS build process, and thus has easy access to it when building Perl, but ordinary users would need to go to a great deal of effort to obtain the information needed for pre-binding.

You can override the default and build a shared libperl if you wish (Configure ... -Duseshrlib), but the load time on pre-10.4 OS releases will be greater than either the static library, or Apple's pre-bound dynamic library.

With 10.4 "Tiger" and newer, Apple has all but eliminated the performance penalty for non-prebound libraries.

Updating Apple's Perl

In a word - don't, at least without a *very* good reason. Your scripts can just as easily begin with "#!/usr/local/bin/perl" as with "#!/usr/bin/perl". Scripts supplied by Apple and other third parties as part of installation packages and such have generally only been tested with the /usr/bin/perl that's installed by Apple.

If you find that you do need to update the system Perl, one issue worth keeping in mind is the question of static vs. dynamic libraries. If you upgrade using the default static libperl, you will find that the dynamic libperl supplied by Apple will not be deleted. If both libraries are present when an application that links against libperl is built, ld will link against the dynamic library by default. So, if you need to replace Apple's dynamic libperl with a static libperl, you need to be sure to delete the older dynamic library after you've installed the update.

Known problems

If you have installed extra libraries such as GDBM through Fink (in other words, you have libraries under /sw/lib), or libdlcompat to /usr/local/lib, you may need to be extra careful when running Configure to not to confuse Configure and Perl about which libraries to use. Being confused will show up for example as "dyld" errors about symbol problems, for example during "make test". The safest bet is to run Configure as

    Configure ... -Uloclibpth -Dlibpth=/usr/lib

to make Configure look only into the system libraries. If you have some extra library directories that you really want to use (such as newer Berkeley DB libraries in pre-Panther systems), add those to the libpth:

    Configure ... -Uloclibpth -Dlibpth='/usr/lib /opt/lib'

The default of building Perl statically may cause problems with complex applications like Tk: in that case consider building shared Perl

    Configure ... -Duseshrplib

but remember that there's a startup cost to pay in that case (see above "libperl and Prebinding").

Starting with Tiger (Mac OS X 10.4), Apple shipped broken locale files for the eu_ES locale (Basque-Spain). In previous releases of Perl, this resulted in failures in the lib/locale test. These failures have been supressed in the current release of Perl by making the test ignore the broken locale. If you need to use the eu_ES locale, you should contact Apple support.

MacPerl

Quite a bit has been written about MacPerl, the Perl distribution for "Classic MacOS" - that is, versions 9 and earlier of MacOS. Because it runs in environment that's very different from that of UNIX, many things are done differently in MacPerl. Modules are installed using a different procedure, Perl itself is built differently, path names are different, etc.

From the perspective of a Perl programmer, Mac OS X is more like a traditional UNIX than Classic MacOS. If you find documentation that refers to a special procedure that's needed for MacOS that's drastically different from the instructions provided for UNIX, the MacOS instructions are quite often intended for MacPerl on Classic MacOS. In that case, the correct procedure on Mac OS X is usually to follow the UNIX instructions, rather than the MacPerl instructions.

Carbon

MacPerl ships with a number of modules that are used to access the classic MacOS toolbox. Many of these modules have been updated to use Mac OS X's newer "Carbon" toolbox, and are available from CPAN in the "Mac::Carbon" module.

Cocoa

There are two ways to use Cocoa from Perl. Apple's PerlObjCBridge module, included with Mac OS X, can be used by standalone scripts to access Foundation (i.e. non-GUI) classes and objects.

An alternative is CamelBones, a framework that allows access to both Foundation and AppKit classes and objects, so that full GUI applications can be built in Perl. CamelBones can be found on SourceForge, at http://www.sourceforge.net/projects/camelbones/.

Starting From Scratch

Unfortunately it is not that difficult somehow manage to break one's Mac OS X Perl rather severely. If all else fails and you want to really, REALLY, start from scratch and remove even your Apple Perl installation (which has become corrupted somehow), the following instructions should do it. Please think twice before following these instructions: they are much like conducting brain surgery to yourself. Without anesthesia. We will not come to fix your system if you do this.

First, get rid of the libperl.dylib:

    # cd /System/Library/Perl/darwin/CORE
    # rm libperl.dylib

Then delete every .bundle file found anywhere in the folders:

    /System/Library/Perl
    /Library/Perl

You can find them for example by

    # find /System/Library/Perl /Library/Perl -name '*.bundle' -print

After this you can either copy Perl from your operating system media (you will need at least the /System/Library/Perl and /usr/bin/perl), or rebuild Perl from the source code with Configure -Dprefix=/usr -Dusershrplib NOTE: the -Dprefix=/usr to replace the system Perl works much better with Perl 5.8.1 and later, in Perl 5.8.0 the settings were not quite right.

"Pacifist" from CharlesSoft (http://www.charlessoft.com/) is a nice way to extract the Perl binaries from the OS media, without having to reinstall the entire OS.

AUTHOR

This README was written by Sherm Pendley <sherm@dot-app.org>, and subsequently updated by Dominic Dunlop <domo@computer.org>. The "Starting From Scratch" recipe was contributed by John Montbriand <montbriand@apple.com>.

DATE

Last modified 2005-11-07.


README.mint - Perl version 5 on Atari MiNT

  • Known problems with Perl on MiNT
  • AUTHOR

NAME

README.mint - Perl version 5 on Atari MiNT

DESCRIPTION

There is a binary version of perl available from the FreeMiNT project http://freemint.de/ You may wish to use this instead of trying to compile yourself.

The following advice is from perl 5.004_02 and is probably rather out of date.

If you want to build perl yourself on MiNT (or maybe on an Atari without MiNT) you may want to accept some advice from somebody who already did it...

There was a perl port for Atari ST done by ++jrb bammi@cadence.com. This port tried very hard to build on non-MiNT-systems. For the sake of efficiency I've left this way. Yet, I haven't removed bammi's patches but left them intact. Unfortunately some of the files that bammi contributed to the perl distribution seem to have vanished?

So, how can you distinguish my patches from bammi's patches? All of bammi's stuff is embedded in "#ifdef atarist" preprocessor macros. My MiNT port uses "#ifdef __MINT__" instead (and unconditionally undefines "atarist". If you want to continue on bammi's port, all you have to do is to swap the "-D" and "-U" switches for "__MINT__" and "atarist" in the variable ccflags.

However, I think that my version will still run on non-MiNT-systems provided that the user has a Eunuchs-like environment (i.e. the standard envariables like $PATH, $HOME, ... are set, there is a POSIX compliant shell in /bin/sh, and...)

Known problems with Perl on MiNT

The problems you may encounter when building perl on your machine are most probably due to deficiencies in MiNT resp. the Atari platform in general.

First of all, if you have less than 8 MB of RAM you shouldn't even try to build Perl yourself. Better grab a binary pre-compiled version somewhere. Even if you have more memory you should take some care. Try to run in a fresh environment (without memory fragmented too much) with as few daemons, accessories, xcontrol modules etc. as possible. If you run some AES you should consider to start a console based environment instead.

A problem has been reported with sed. Sed is used to create some configuration files based on the answers you have given to the Configure script. Unfortunately the Perl Configure script shows sed on MiNT its limits. I have sed 2.05 with a stacksize of 64k and I have encountered no problems. If sed crashes during your configuration process you should first try to augment sed's stacksize:

        fixstk 64k /usr/bin/sed

(or similar). If it still doesn't help you may have a look which other versions of sed are installed on your system. If you have a KGMD 1.0 installation you will find three in /usr/bin. Have a look there.

Perl has some "mammut" C files. If gcc reports "internal compiler error: program cc1 got fatal signal 10" this is very likely due to a stack overflow in program cc1. Find cc1 and fix its stack. I have made good experiences with

        fixstk 2 cc1

This doesn't establish a stack of 2 Bytes only as you might think. It really reserves one half of the available memory for cc1's stack. A setting of 1 would reserve the entire memory for cc1, 3 would reserve three fourths. You will have to find out the value that suits to your system yourself.

To find out the location of the program "cc1" simply type `gcc --print-prog-name cc1' at your shell prompt.

Now run make (maybe "make -k"). If you get a fatal signal 10 increase cc1's stacksize, if you run out of memory you should either decrease the stacksize or follow some more hints:

Perl's building process is very handy on machines with a lot of virtual memory but may result in a disaster if you are short of memory. If gcc fails to compile many source files you should reduce the optimization. Grep for "optimize" in the file config.sh and change the flags.

If only several huge files cause problems (actually it is not a matter of the file size resp. the amount of code but depends on the size of the individual functions) it is useful to bypass the make program and compile these files directly from the command line. For example if you got something like the following from make:

        CCCMD = gcc -DPERL_CORE ....
        ...
        ...: virtual memory exhausted

you should hack into the shell:

        gcc -DPERL_CORE ... toke.c

Please note that you have to add the name of the source file (here toke.c) at the end.

If none of this helps, you're helpless. Wait for a binary release. If you have succeeded you may encounter another problem at the linking process. If gcc complains that it can't find some libraries within the perl distribution you probably have an old linker. If it complains for example about "file not found for xxx.olb" you should cd into the directory in question and

        ln -s libxxx.a xxx.olb

This will fix the problem.

This version (5.00402) of perl has passed most of the tests on my system:

 Failed Test  Status Wstat Total Fail  Failed  List of failed
 ------------------------------------------------------------------------------
 io/pipe.t                    10    2  20.00%  7, 9
 io/tell.t                    13    1   7.69%  12
 lib/complex.t               762   13   1.71%  84-85, 248-251, 257, 272-273,
                                               371, 380, 419-420
 lib/io_pipe.t                10    1  10.00%  9
 lib/io_tell.t                13    1   7.69%  12
 op/magic.t                   30    2   6.67%  29-30
 Failed 6/152 test scripts, 96.05% okay. 20/4359 subtests failed, 99.54% okay.

Pipes always cause problems with MiNT, it's actually a surprise that most of the tests did work. I've got no idea why the "tell" test failed, this shouldn't mean too big a problem however.

Most of the failures of lib/complex seem to be harmless, actually errors far right to the decimal point... Two failures seem to be serious: The sign of the results is reversed. I would say that this is due to minor bugs in the portable math lib that I compiled perl with.

I haven't bothered very much to find the reason for the failures with op/magic.t and op/stat.t. Maybe you'll find it out.

##########################################################################

Another possible problem may arise from the implementation of the "pwd" command. It happened to add a carriage return and newline to its output no matter what the setting of $UNIXMODE is. This is quite annoying since many library modules for perl take the output of pwd, chop off the trailing newline character and then expect to see a valid path in that. But the carriage return (last but second character!) isn't chopped off. You can either try to patch all library modules (at the price of performance for the extra transformation) or you can use my version of pwd that doesn't suffer from this deficiency.

The fixed implementation is in the mint subdirectory. Running "Configure" will attempt to build and install it if necessary (hints/mint.sh will do this work) but you can build and install it explicitly by:

        cd mint
        make install

This is the fastest solution.

Just in case you want to go the hard way: perl won't even build with a broken pwd! You will have to fix the library modules (ext/POSIX/POSIX.pm, lib/Cwd.pm, lib/pwd.pl) at last after building miniperl.

A major nuisance of current MiNTLib versions is the implementation of system() which is far from being POSIX compliant. A real system() should fork and then exec /bin/sh with its argument as a command line to the shell. The MiNTLib system() however doesn't expect that every user has a POSIX shell in /bin/sh. It tries to work around the problem by forking and exec'ing the first token in its argument string. To get a little bit of compliance to POSIX system() it tries to handle at least redirection ("<" or ">") on its own behalf.

This isn't a good idea since many programs expect that they can pass a command line to system() that exploits all features of a POSIX shell. If you use the MiNTLib version of system() with perl the Perl function system() will suffer from the same deficiencies.

You will find a fixed version of system() in the mint subdirectory. You can easily insert this version into your system libc:

        cd mint
        make system.o
        ar r /usr/lib/libc.a
        ranlib /usr/lib/libc.a

If you are suspicious you should either back up your libc before or extract the original system.o from your libc with "ar x /usr/lib/libc.a system.o". You can then backup the system.o module somewhere before you succeed.

Anything missing? Yep, I've almost forgotten... No file in this distribution without a fine saying. Take this one:

        "From a thief you should learn: (1) to work at night;
        (2) if one cannot gain what one wants in one night to
        try again the next night; (3) to love one's coworkers
        just as thieves love each other; (4) to be willing to
        risk one's life even for a little thing; (5) not to
        attach too much value to things even though one has
        risked one's life for them - just as a thief will resell
        a stolen article for a fraction of its real value;
        (6) to withstand all kinds of beatings and tortures
        but to remain what you are; and (7) to believe your
        work is worthwhile and not be willing to change it."

                        -- Rabbi Dov Baer, Maggid of Mezeritch

OK, this was my motto while working on Perl for MiNT, especially rule (1)...

Have fun with Perl!

AUTHOR

Guido Flohr

        mailto:guido@FreeMiNT.de


README.mpeix - Perl/iX for HP e3000 MPE

  • NOTE
  • Binary distribution from HP
  • What's New in Perl for MPE/iX
  • Welcome to Perl/iX
  • System Requirements for Perl/iX
  • How to Obtain Perl/iX
  • Perl/iX Distribution Contents Highlights
  • How to Compile Perl/iX
  • Getting Started with Perl/iX
  • MPE/iX Implementation Considerations
  • Known Perl/iX Bugs Under Investigation
  • Perl/iX To-Do List
  • Perl/iX Change History
  • AUTHOR

NAME

README.mpeix - Perl/iX for HP e3000 MPE

SYNOPSIS

   http://www.bixby.org/mark/perlix.html
   http://jazz.external.hp.com/src/hp_freeware/perl/
   Perl language for MPE
   Last updated January 12, 2006 @ 2100 UTC

NOTE

This is a podified version of the above-mentioned web page, podified by Jarkko Hietaniemi 2001-Jan-01.

Binary distribution from HP

The simplest way to obtain Perl for the MPE/iX is to go either of these URLs and follow the instructions within.

http://jazz.external.hp.com/src/hp_freeware/perl/ http://www.bixby.org/mark/perlix.html

Use which ever one is more recent.

What's New in Perl for MPE/iX

January 12, 2006

  • Updated for perl-5.8.8 and perl-5.9.3 by Ken Hirsch.

    Simplified the build process by using the MPEAUTOCONF functionality in Mark Klein's ld.

    If you build this from scratch, make sure you have a version of ld which supports it. In the shell, type

      ld --help
    and look for AUTOCONF or MPEAUTOCONF near the bottom
      or do this:
  ld --help 2>&1 | grep AUTOCONF

    If you see don't see AUTOCONF or MPEAUTOCONF, make sure you get a new version.

    You also do not have to use mpeix/relink after building, so the recommend sequence is:

      ./Configure -de
          # or ./Configure -de -Dusedevel
      # if you're building a development version

      make
  make test
     # if you run this in a job, do "make test_notty"
      make install

    Be prepared for a wait. These take much longer on MPE/iX than on a Unix system, because of a slow forking, mostly. On a lightly-loaded HP3000 Series 979 running MPE/iX 7.5:

        Configure: 1 hour
    make:      1 hour 15 minutes
    make test  1 hour 45 minutes

    Various socket problems were fixed in mpeix.c.

    Mark Klein provided a fixed sigsetjmp (that works with dynamic libraries) in mpeix_setjmp.c

  • June 1, 2000

    • Rebuilt to be compatible with mod_perl. If you plan on using mod_perl, you MUST download and install this version of Perl/iX!

    • uselargefiles="undef": not available in MPE for POSIX files yet.

    • Now bundled with various add-on packages:

      • libnet (as seen on CPAN)

      • libwww-perl (LWP) which lets Perl programs behave like web browsers:

            1. #!/PERL/PUB/perl
    2. use LWP::Simple;
    3. $doc = get('http://www.bixby.org/mark/perlix.html');  # reads the
       web page into variable $doc

        (http://www.bixby.org/mark/perlix.html)

      • mod_perl (just the perl portion; the actual DSO will be released soon with Apache/iX 1.3.12 from bixby.org). This module allows you to write high performance persistent Perl CGI scripts and all sorts of cool things. (http://perl.apache.org/)

        and much much more hiding under /PERL/PUB/.cpan/

      • The CPAN module now works for automatic downloading and installing of add-on packages:

            1. export FTP_PASSIVE=1
    2. perl -MCPAN -e shell
    3. Ignore any terminal I/O related complaints!

        (http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html)

    May 20, 2000

    • Updated to version 5.6.0. Builds straight out of the box on MPE/iX.

    • Perl's getpwnam() function which had regressed to being unimplemented on MPE is now implemented once again.

    September 17, 1999

    • Migrated from cccd.edu to bixby.org.

Welcome to Perl/iX

This is the official home page for the HP e3000 MPE/iX ( http://www.hp.com/go/e3000 ) port of the Perl scripting language ( http://www.perl.com/ ) which gives you all of the power of C, awk, sed, and sh in a single language. Check here for the latest news, implemented functionality, known bugs, to-do list, etc. Status reports about major milestones will also be posted to the HP3000-L mailing list ( http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU ) and its associated gatewayed newsgroup comp.sys.hp.mpe.

I'm doing this port because I can't live without Perl on the Unix machines that I administer, and I want to have the same power available to me on MPE.

Please send your comments, questions, and bug reports directly to me, Mark Bixby ( http://www.bixby.org/mark/ ). Or just post them to HP3000-L.

The platform I'm using to do this port is an HP 3000 957RX running MPE/iX 6.0 and using the GNU gcc C compiler ( http://jazz.external.hp.com/src/gnu/gnuframe.html ).

The combined porting wisdom from all of my ports can be found in my MPE/iX Porting Guide (http://www.bixby.org/mark/porting.html).

IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of the software you download from bixby.org is my personal freeware that is NOT supported by HP.

System Requirements for Perl/iX

  • MPE/iX 5.5 or later. This version of Perl/iX does NOT run on MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines.

  • If you wish to recompile Perl, you must install both GNUCORE and GNUGCC from jazz (http://jazz.external.hp.com/src/gnu/gnuframe.html).

  • Perl/iX will be happier on MPE/iX 5.5 if you install the MPEKX40B extended POSIX filename characters patch, but this is optional.

  • Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent Perl/iX from dying with an unresolved external reference to _getenv_libc.

  • If you will be compiling Perl/iX yourself, you will also need Syslog/iX ( http://www.bixby.org/mark/syslogix.html ) and the /BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX ( http://www.bixby.org/mark/bindix.html ).

How to Obtain Perl/iX

  1. Download Perl using either FTP.ARPA.SYS or some other client

  2. Extract the installation script

  3. Edit the installation script

  4. Run the installation script

  5. Convert your *.a system archive libraries to *.sl shared libraries

Download Perl using FTP.ARPA.SYS from your HP 3000 (the preferred method).....

    :HELLO MANAGER.SYS
    :XEQ FTP.ARPA.SYS
    open ftp.bixby.org
    anonymous
    your@email.address
    bytestream
    cd /pub/mpe
    get perl-5.6.0-mpe.tar.Z /tmp/perl.tar.Z;disc=2147483647
    exit

.....Or download using some other generic web or ftp client (the alternate method)

Download the following files (make sure that you use "binary mode" or whatever client feature that is 8-bit clean):

  • Perl from

        http://www.bixby.org/ftp/pub/mpe/perl-5.6.0-mpe.tar.Z

    or

        ftp://ftp.bixby.org/pub/mpe/perl-5.6.0-mpe.tar.Z

  • Upload those files to your HP 3000 in an 8-bit clean bytestream manner to:

        /tmp/perl.tar.Z

  • Then extract the installation script (after both download methods)

        :CHDIR /tmp
    :XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL'

  • Edit the installation script

    Examine the accounting structure creation commands and modify if necessary (adding additional capabilities, choosing a non-system volume set, etc).

        :XEQ VI.HPBIN.SYS /tmp/INSTALL

  • Run the installation script.

    The accounting structure will be created and then all files will be extracted from the archive.

        :XEQ SH.HPBIN.SYS /tmp/INSTALL

  • Convert your *.a system archive libraries to *.sl shared libraries

    You only have to do this ONCE on your MPE/iX 5.5 machine in order to convert /lib/lib*.a and /usr/lib/lib*.a libraries to their *.sl equivalents. This step should not be necessary on MPE/iX 6.0 or later machines because the 6.0 or later update process does it for you.

        :XEQ SH.HPBIN.SYS /PERL/PUB/LIBSHP3K

Perl/iX Distribution Contents Highlights

README

The file you're reading now.

INSTALL

Perl/iX Installation script.

LIBSHP3K

Script to convert *.a system archive libraries to *.sl shared libraries.

PERL

Perl NMPRG executable. A version-numbered backup copy also exists. You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl".

.cpan/

Much add-on source code downloaded with the CPAN module.

lib/

Perl libraries, both core and add-on.

man/

Perl man page documentation.

public_html/feedback.cgi

Sample feedback CGI form written in Perl.

src/perl-5.6.0-mpe

Source code.

How to Compile Perl/iX

  1. cd src/perl-5.6.0-mpe

  2. Read the INSTALL file for the official instructions

  3. ./Configure -d

  4. make

  5. ./mpeix/relink

  6. make test (expect approximately 15 out of 11306 subtests to fail, mostly due to MPE not supporting hard links, UDP socket problems, and handling exit() return codes improperly)

  7. make install

  8. Optionally create symbolic links that point to the Perl executable, i.e. ln -s /PERL/PUB/PERL /usr/local/bin/perl

The summary test results from "cd t; ./perl -I../lib harness":

  Failed Test  Status Wstat Total Fail  Failed  List of failed
  ---------------------------------------------------------------------------
  io/fs.t                      29    8  27.59%  2-5, 7-9, 11
  io/openpid.t                 10    1  10.00%  7
  lib/io_sock.t                14    1   7.14%  13
  lib/io_udp.t                  7    2  28.57%  3, 5
  lib/posix.t                  27    1   3.70%  12
  op/lex_assign.t             187    1   0.53%  13
  op/stat.t                    58    1   1.72%  3
  15 tests and 94 subtests skipped.
  Failed 7/236 test scripts, 97.03% okay. 15/11306 subtests failed, 99.87% okay.

Getting Started with Perl/iX

Create your Perl script files with "#!/PERL/PUB/perl" (or an equivalent symbolic link) as the first line. Use the chmod command to make sure that your script has execute permission. Run your script!

Be sure to take a look at the CPAN module list ( http://www.cpan.org/CPAN.html ). A wide variety of free Perl software is available. You can automatically download these packages by using the CPAN module ( http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html ).

MPE/iX Implementation Considerations

There some minor functionality issues to be aware of when comparing Perl for Unix (Perl/UX) to Perl/iX:

  • MPE gcc/ld doesn't properly support linking NMPRG executables against NMXL dynamic libraries, so you must manually run mpeix/relink after each re-build of Perl.

  • Perl/iX File::Copy will use MPE's /bin/cp command to copy files by name in order to preserve file attributes like file code.

  • MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(), setpwent(), endpwent().

  • MPE (and thus Perl/iX) lacks support for hard links.

  • MPE requires GETPRIVMODE() in order to bind() to ports less than 1024. Perl/iX will call GETPRIVMODE() automatically on your behalf if you attempt to bind() to these low-numbered ports. Note that the Perl/iX executable and the PERL account do not normally have CAP=PM, so if you will be bind()-ing to these privileged ports, you will manually need to add PM capability as appropriate.

  • MPE requires that you bind() to an IP address of zero. Perl/iX automatically replaces the IP address that you pass to bind() with a zero.

  • MPE requires GETPRIVMODE() in order to setuid(). There are too many calls to setuid() within Perl/iX, so I have not attempted an automatic GETPRIVMODE() solution similar to bind().

Known Perl/iX Bugs Under Investigation

None.

Perl/iX To-Do List

  • Make setuid()/setgid() support work.

  • Make sure that fcntl() against a socket descriptor is redirected to sfcntl().

  • Add support for Berkeley DB once I've finished porting Berkeley DB.

  • Write an MPE XS extension library containing miscellaneous important MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl().

Perl/iX Change History

May 6, 1999

  • Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent Perl/iX from dying with an unresolved external reference to _getenv_libc.

April 7, 1999

  • Updated to version 5.005_03.

  • The official source distribution once again compiles "straight out of the box" for MPE.

  • The current incarnation of the 5.5 POSIX filename extended characters patch is now MPEKX40B.

  • The LIBSHP3K *.a -> *.sl library conversion script is now included as /PERL/PUB/LIBSHP3K.

November 20, 1998

  • Updated to version 5.005_02.

  • Fixed a DynaLoader bug that was unable to load symbols from relative path name libraries.

  • Fixed a .xs compilation bug where the mpeixish.sh include file wasn't being installed into the proper directory.

  • All bugfixes will be submitted back to the official Perl developers.

  • The current incarnation of the POSIX filename extended characters patch is now MPEKXJ3A.

August 14, 1998

  • The previous POSIX filename extended characters patch MPEKX44C has been superseded by MPEKXB5A.

August 7, 1998

  • The previous POSIX filename extended characters patch MPEKX76A has been superseded by MPEKX44C.

July 28, 1998

  • Updated to version 5.005_01.

July 23, 1998

  • Updated to version 5.005 (production release). The public freeware sources are now 100% MPE-ready "straight out of the box".

July 17, 1998

  • Updated to version 5.005b1 (public beta release). The public freeware sources are now 99.9% MPE-ready. By installing and testing this beta on your own HP3000, you will be helping to insure that the final release of 5.005 will be 100% MPE-ready and 100% bug free.

  • My MPE binary release is now extracted using my standard INSTALL script.

July 15, 1998

  • Changed startperl to #!/PERL/PUB/perl so that Perl will recognize scripts more easily and efficiently.

July 8, 1998

  • Updated to version 5.004_70 (internal developer release) which is now MPE-ready. The next public freeware release of Perl should compile "straight out of the box" on MPE. Note that this version of Perl/iX was strictly internal to me and never publicly released. Note that [21]BIND/iX is now required (well, the include files and libbind.a) if you wish to compile Perl/iX.

November 6, 1997

  • Updated to version 5.004_04. No changes in MPE-specific functionality.

October 16, 1997

  • Added Demos section to the Perl/iX home page so you can see some sample Perl applications running on my 3000.

October 3, 1997

  • Added System Requirements section to the Perl/iX home page just so the prerequisites stand out more. Various other home page tweaks.

October 2, 1997

  • Initial public release.

September 1997

  • Porting begins.

AUTHOR

Mark Bixby, http://www.bixby.org/mark/


perlnetware - Perl for NetWare

  • BUILD
    • Tools & SDK
    • Setup
    • Make
    • Interpreter
    • Extensions
  • INSTALL
  • BUILD NEW EXTENSIONS
  • ACKNOWLEDGEMENTS
  • AUTHORS
  • DATE

NAME

perlnetware - Perl for NetWare

DESCRIPTION

This file gives instructions for building Perl 5.7 and above, and also Perl modules for NetWare. Before you start, you may want to read the README file found in the top level directory into which the Perl source code distribution was extracted. Make sure you read and understand the terms under which the software is being distributed.

BUILD

This section describes the steps to be performed to build a Perl NLM and other associated NLMs.

Tools & SDK

The build requires CodeWarrior compiler and linker. In addition, the "NetWare SDK", "NLM & NetWare Libraries for C" and "NetWare Server Protocol Libraries for C", all available at http://developer.novell.com/ndk/, are also required. Microsoft Visual C++ version 4.2 or later is also required.

Setup

The build process is dependent on the location of the NetWare SDK. Once the Tools & SDK are installed, the build environment has to be setup. The following batch files setup the environment.

SetNWBld.bat

The Execution of this file takes 2 parameters as input. The first being the NetWare SDK path, second being the path for CodeWarrior Compiler & tools. Execution of this file sets these paths and also sets the build type to Release by default.

Buildtype.bat

This is used to set the build type to debug or release. Change the build type only after executing SetNWBld.bat

  • Example: 1. Typing "buildtype d on" at the command prompt causes the buildtype to be set to Debug type with D2 flag set. 2. Typing "buildtype d off" or "buildtype d" at the command prompt causes the buildtype to be set to Debug type with D1 flag set. 2. Typing "buildtype r" at the command prompt sets it to Release Build type.

    • Make

    The make process runs only under WinNT shell. The NetWare makefile is located under the NetWare folder. This makes use of miniperl.exe to run some of the Perl scripts. To create miniperl.exe, first set the required paths for Visual c++ compilier (specify vcvars32 location) at the command prompt. Then run nmake from win32 folder through WinNT command prompt. The build process can be stopped after miniperl.exe is created. Then run nmake from NetWare folder through WinNT command prompt.

    Currently the following two build types are tested on NetWare:

    • USE_MULTI, USE_ITHREADS & USE_IMP_SYS defined

    • USE_MULTI & USE_IMP_SYS defined and USE_ITHREADS not defined

    Interpreter

    Once miniperl.exe creation is over, run nmake from the NetWare folder. This will build the Perl interpreter for NetWare as perl.nlm. This is copied under the Release folder if you are doing a release build, else will be copied under Debug folder for debug builds.

    Extensions

    The make process also creates the Perl extensions as <Extension.nlm>

    INSTALL

    To install NetWare Perl onto a NetWare server, first map the Sys volume of a NetWare server to i:. This is because the makefile by default sets the drive letter to i:. Type nmake nwinstall from NetWare folder on a WinNT command prompt. This will copy the binaries and module files onto the NetWare server under sys:\Perl folder. The Perl interpreter, perl.nlm, is copied under sys:\perl\system folder. Copy this to sys:\system folder.

    Example: At the command prompt Type "nmake nwinstall". This will install NetWare Perl on the NetWare Server. Similiarly if you type "nmake install", This will cause the binaries to be installed on the local machine. (Typically under the c:\perl folder)

    BUILD NEW EXTENSIONS

    To build extensions other than standard extensions, NetWare Perl has to be installed on Windows along with Windows Perl. The Perl for Windows can be either downloaded from the CPAN site and built using the sources, or the binaries can be directly downloaded from the ActiveState site. Installation can be done by invoking nmake install from the NetWare folder on a WinNT command prompt after building NetWare Perl by following steps given above. This will copy all the *.pm files and other required files. Documentation files are not copied. Thus one must first install Windows Perl, Then install NetWare Perl.

    Once this is done, do the following to build any extension:

    • Change to the extension directory where its source files are present.

    • Run the following command at the command prompt:

          perl -II<path to NetWare lib dir> -II<path to lib> Makefile.pl

      Example:

          perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl

      or

          perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl

    • nmake

    • nmake install

      Install will copy the files into the Windows machine where NetWare Perl is installed and these files may have to be copied to the NetWare server manually. Alternatively, pass INSTALLSITELIB=i:\perl\lib as an input to makefile.pl above. Here i: is the mapped drive to the sys: volume of the server where Perl on NetWare is installed. Now typing nmake install, will copy the files onto the NetWare server.

      Example: You can execute the following on the command prompt.

                perl -Ic:/perl/5.6.1/lib/NetWare-x86-multi-thread -Ic:\perl\5.6.1\lib MakeFile.pl
          INSTALLSITELIB=i:\perl\lib

      or

                perl -Ic:/perl/5.8.0/lib/NetWare-x86-multi-thread -Ic:\perl\5.8.0\lib MakeFile.pl
          INSTALLSITELIB=i:\perl\lib

    • Note: Some modules downloaded from CPAN may require NetWare related API in order to build on NetWare. Other modules may however build smoothly with or without minor changes depending on the type of module.

    ACKNOWLEDGEMENTS

    The makefile for Win32 is used as a reference to create the makefile for NetWare. Also, the make process for NetWare port uses miniperl.exe to run scripts during the make and installation process.

    AUTHORS

    Anantha Kesari H Y (hyanantha@novell.com) Aditya C (caditya@novell.com)

    DATE

    • Created - 18 Jan 2001

    • Modified - 25 June 2001

    • Modified - 13 July 2001

    • Modified - 28 May 2002


README.openbsd - Perl version 5 on OpenBSD systems

    • OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads
  • AUTHOR

NAME

README.openbsd - Perl version 5 on OpenBSD systems

DESCRIPTION

This document describes various features of OpenBSD that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads

When Perl is configured to use ithreads, it will use re-entrant library calls in preference to non-re-entrant versions. There is an incompatability in OpenBSD's getprotobyname_r and getservbyname_r function in versions 3.7 and later that will cause a SEGV when called without doing a bzero on their return structs prior to calling these functions. Current Perl's should handle this problem correctly. Older threaded Perls (5.8.6 or earlier) will run into this problem. If you want to run a threaded Perl on OpenBSD 3.7 or higher, you will need to upgrade to at least Perl 5.8.7.

AUTHOR

Steve Peters <steve@fisharerojo.org>

Please report any errors, updates, or suggestions to perlbug@perl.org.


perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.

    • Target
    • Other OSes
    • Prerequisites
    • Starting Perl programs under OS/2 (and DOS and...)
    • Starting OS/2 (and DOS) programs under Perl
  • Frequently asked questions
    • "It does not work"
    • I cannot run external programs
    • I cannot embed perl into my program, or use perl.dll from my
    • `` and pipe- open do not work under DOS.
    • Cannot start find.exe "pattern" file
  • INSTALLATION
    • Automatic binary installation
    • Manual binary installation
    • Warning
  • Accessing documentation
    • OS/2 .INF file
    • Plain text
    • Manpages
    • HTML
    • GNU info files
    • PDF files
    • LaTeX docs
  • BUILD
    • The short story
    • Prerequisites
    • Getting perl source
    • Application of the patches
    • Hand-editing
    • Making
    • Testing
    • Installing the built perl
    • a.out-style build
  • Building a binary distribution
  • Building custom .EXE files
    • Making executables with a custom collection of statically loaded extensions
    • Making executables with a custom search-paths
  • Build FAQ
    • Some / became \ in pdksh.
    • 'errno' - unresolved external
    • Problems with tr or sed
    • Some problem (forget which ;-)
    • Library ... not found
    • Segfault in make
    • op/sprintf test failure
  • Specific (mis)features of OS/2 port
    • setpriority, getpriority
    • system()
    • extproc on the first line
    • Additional modules:
    • Prebuilt methods:
    • Prebuilt variables:
    • Misfeatures
    • Modifications
    • Identifying DLLs
    • Centralized management of resources
  • Perl flavors
    • perl.exe
    • perl_.exe
    • perl__.exe
    • perl___.exe
    • Why strange names?
    • Why dynamic linking?
    • Why chimera build?
  • ENVIRONMENT
    • PERLLIB_PREFIX
    • PERL_BADLANG
    • PERL_BADFREE
    • PERL_SH_DIR
    • USE_PERL_FLOCK
    • TMP or TEMP
  • Evolution
    • Text-mode filehandles
    • Priorities
    • DLL name mangling: pre 5.6.2
    • DLL name mangling: 5.6.2 and beyond
    • DLL forwarder generation
    • Threading
    • Calls to external programs
    • Memory allocation
    • Threads
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.

SYNOPSIS

One can read this document in the following formats:

        man perlos2
        view perl perlos2
        explorer perlos2.html
        info perlos2

to list some (not all may be available simultaneously), or it may be read as is: either as README.os2, or pod/perlos2.pod.

To read the .INF version of documentation (very recommended) outside of OS/2, one needs an IBM's reader (may be available on IBM ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's Visual Age C++ 3.5.

A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package

  ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip

in ?:\JUST_ADD\view.exe. This gives one an access to EMX's .INF docs as well (text form is available in /emx/doc in EMX's distribution). There is also a different viewer named xview.

Note that if you have lynx.exe or netscape.exe installed, you can follow WWW links from this document in .INF format. If you have EMX docs installed correctly, you can follow library links (you need to have view emxbook working by setting EMXBOOK environment variable as it is described in EMX docs).

DESCRIPTION

Target

The target is to make OS/2 one of the best supported platform for using/building/developing Perl and Perl applications, as well as make Perl the best language to use under OS/2. The secondary target is to try to make this work under DOS and Win* as well (but not too hard).

The current state is quite close to this target. Known limitations:

  • Some *nix programs use fork() a lot; with the mostly useful flavors of perl for OS/2 (there are several built simultaneously) this is supported; but some flavors do not support this (e.g., when Perl is called from inside REXX). Using fork() after useing dynamically loading extensions would not work with very old versions of EMX.

  • You need a separate perl executable perl__.exe (see perl__.exe) if you want to use PM code in your application (as Perl/Tk or OpenGL Perl modules do) without having a text-mode window present.

    While using the standard perl.exe from a text-mode window is possible too, I have seen cases when this causes degradation of the system stability. Using perl__.exe avoids such a degradation.

  • There is no simple way to access WPS objects. The only way I know is via OS2::REXX and SOM extensions (see the OS2::REXX manpage, Som). However, we do not have access to convenience methods of Object-REXX. (Is it possible at all? I know of no Object-REXX API.) The SOM extension (currently in alpha-text) may eventually remove this shortcoming; however, due to the fact that DII is not supported by the SOM module, using SOM is not as convenient as one would like it.

Please keep this list up-to-date by informing me about other items.

Other OSes

Since OS/2 port of perl uses a remarkable EMX environment, it can run (and build extensions, and - possibly - be built itself) under any environment which can run EMX. The current list is DOS, DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, only one works, see perl_.exe.

Note that not all features of Perl are available under these environments. This depends on the features the extender - most probably RSX - decided to implement.

Cf. Prerequisites.

Prerequisites

EMX

EMX runtime is required (may be substituted by RSX). Note that it is possible to make perl_.exe to run under DOS without any external support by binding emx.exe/rsx.exe to it, see emxbind. Note that under DOS for best results one should use RSX runtime, which has much more functions working (like fork, popen and so on). In fact RSX is required if there is no VCPI present. Note the RSX requires DPMI. Many implementations of DPMI are known to be very buggy, beware!

Only the latest runtime is supported, currently 0.9d fix 03. Perl may run under earlier versions of EMX, but this is not tested.

One can get different parts of EMX from, say

  http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
  http://powerusersbbs.com/pub/os2/dev/   [EMX+GCC Development]
  http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/

The runtime component should have the name emxrt.zip.

NOTE. When using emx.exe/rsx.exe, it is enough to have them on your path. One does not need to specify them explicitly (though this

  emx perl_.exe -de 0

will work as well.)

RSX

To run Perl on DPMI platforms one needs RSX runtime. This is needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see Other OSes). RSX would not work with VCPI only, as EMX would, it requires DMPI.

Having RSX and the latest sh.exe one gets a fully functional *nix-ish environment under DOS, say, fork, `` and pipe-open work. In fact, MakeMaker works (for static build), so one can have Perl development environment under DOS.

One can get RSX from, say

  ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
  ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
  ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib

Contact the author on rainer@mathematik.uni-bielefeld.de.

The latest sh.exe with DOS hooks is available in

  http://www.ilyaz.org/software/os2/

as sh_dos.zip or under similar names starting with sh, pdksh etc.

HPFS

Perl does not care about file systems, but the perl library contains many files with long names, so to install it intact one needs a file system which supports long file names.

Note that if you do not plan to build the perl itself, it may be possible to fool EMX to truncate file names. This is not supported, read EMX docs to see how to do it.

pdksh

To start external programs with complicated command lines (like with pipes in between, and/or quoting of arguments), Perl uses an external shell. With EMX port such shell should be named sh.exe, and located either in the wired-in-during-compile locations (usually F:/bin), or in configurable location (see PERL_SH_DIR).

For best results use EMX pdksh. The standard binary (5.2.14 or later) runs under DOS (with RSX) as well, see

  http://www.ilyaz.org/software/os2/

Starting Perl programs under OS/2 (and DOS and...)

Start your Perl program foo.pl with arguments arg1 arg2 arg3 the same way as on any other platform, by

        perl foo.pl arg1 arg2 arg3

If you want to specify perl options -my_opts to the perl itself (as opposed to your program), use

        perl -my_opts foo.pl arg1 arg2 arg3

Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the following at the start of your perl script:

        extproc perl -S -my_opts

rename your program to foo.cmd, and start it by typing

        foo arg1 arg2 arg3

Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use extproc, thus you are forced to use -S perl switch, and your script should be on the PATH. As a plus side, if you know a full path to your script, you may still start it with

        perl ../../blah/foo.cmd arg1 arg2 arg3

(note that the argument -my_opts is taken care of by the extproc line in your script, see extproc on the first line).

To understand what the above magic does, read perl docs about -S switch - see the perlrun manpage, and cmdref about extproc:

        view perl perlrun
        man perlrun
        view cmdref extproc
        help extproc

or whatever method you prefer.

There are also endless possibilities to use executable extensions of 4os2, associations of WPS and so on... However, if you use *nixish shell (like sh.exe supplied in the binary distribution), you need to follow the syntax specified in Switches in the perlrun manpage.

Note that -S switch supports scripts with additional extensions .cmd, .btm, .bat, .pl as well.

Starting OS/2 (and DOS) programs under Perl

This is what system() (see system in the perlfunc manpage), `` (see I/O Operators in the perlop manpage), and open pipe (see open in the perlfunc manpage) are for. (Avoid exec() (see exec in the perlfunc manpage) unless you know what you do).

Note however that to use some of these operators you need to have a sh-syntax shell installed (see Pdksh, Frequently asked questions), and perl should be able to find it (see PERL_SH_DIR).

The cases when the shell is used are:

  1. One-argument system() (see system in the perlfunc manpage), exec() (see exec in the perlfunc manpage) with redirection or shell meta-characters;

  2. Pipe-open (see open in the perlfunc manpage) with the command which contains redirection or shell meta-characters;

  3. Backticks `` (see I/O Operators in the perlop manpage) with the command which contains redirection or shell meta-characters;

  4. If the executable called by system()/exec()/pipe-open()/`` is a script with the "magic" #! line or extproc line which specifies shell;

  5. If the executable called by system()/exec()/pipe-open()/`` is a script without "magic" line, and $ENV{EXECSHELL} is set to shell;

  6. If the executable called by system()/exec()/pipe-open()/`` is not found (is not this remark obsolete?);

  7. For globbing (see glob in the perlfunc manpage, I/O Operators in the perlop manpage) (obsolete? Perl uses builtin globbing nowadays...).

For the sake of speed for a common case, in the above algorithms backslashes in the command name are not considered as shell metacharacters.

Perl starts scripts which begin with cookies extproc or #! directly, without an intervention of shell. Perl uses the same algorithm to find the executable as pdksh: if the path on #! line does not work, and contains /, then the directory part of the executable is ignored, and the executable is searched in . and on PATH. To find arguments for these scripts Perl uses a different algorithm than pdksh: up to 3 arguments are recognized, and trailing whitespace is stripped.

If a script does not contain such a cooky, then to avoid calling sh.exe, Perl uses the same algorithm as pdksh: if $ENV{EXECSHELL} is set, the script is given as the first argument to this command, if not set, then $ENV{COMSPEC} /c is used (or a hardwired guess if $ENV{COMSPEC} is not set).

When starting scripts directly, Perl uses exactly the same algorithm as for the search of script given by -S command-line option: it will look in the current directory, then on components of $ENV{PATH} using the following order of appended extensions: no extension, .cmd, .btm, .bat, .pl.

Note that Perl will start to look for scripts only if OS/2 cannot start the specified application, thus system 'blah' will not look for a script if there is an executable file blah.exe anywhere on PATH. In other words, PATH is essentially searched twice: once by the OS for an executable, then by Perl for scripts.

Note also that executable files on OS/2 can have an arbitrary extension, but .exe will be automatically appended if no dot is present in the name. The workaround is as simple as that: since blah. and blah denote the same file (at list on FAT and HPFS file systems), to start an executable residing in file n:/bin/blah (no extension) give an argument n:/bin/blah. (dot appended) to system().

Perl will start PM programs from VIO (=text-mode) Perl process in a separate PM session; the opposite is not true: when you start a non-PM program from a PM Perl process, Perl would not run it in a separate session. If a separate session is desired, either ensure that shell will be used, as in system 'cmd /c myprog', or start it using optional arguments to system() documented in OS2::Process module. This is considered to be a feature.

Frequently asked questions

"It does not work"

Perl binary distributions come with a testperl.cmd script which tries to detect common problems with misconfigured installations. There is a pretty large chance it will discover which step of the installation you managed to goof. ;-)

I cannot run external programs

  • Did you run your programs with -w switch? See Starting OS/2 (and DOS) programs under Perl.

  • Do you try to run internal shell commands, like `copy a b` (internal for cmd.exe), or `glob a*b` (internal for ksh)? You need to specify your shell explicitly, like `cmd /c copy a b`, since Perl cannot deduce which commands are internal to your shell.

I cannot embed perl into my program, or use perl.dll from my program.

Is your program EMX-compiled with -Zmt -Zcrtdll?

Well, nowadays Perl DLL should be usable from a differently compiled program too... If you can run Perl code from REXX scripts (see the OS2::REXX manpage), then there are some other aspect of interaction which are overlooked by the current hackish code to support differently-compiled principal programs.

If everything else fails, you need to build a stand-alone DLL for perl. Contact me, I did it once. Sockets would not work, as a lot of other stuff.

Did you use the ExtUtils::Embed manpage?

Some time ago I had reports it does not work. Nowadays it is checked in the Perl test suite, so grep ./t subdirectory of the build tree (as well as *.t files in the ./lib subdirectory) to find how it should be done "correctly".

`` and pipe-open do not work under DOS.

This may a variant of just I cannot run external programs, or a deeper problem. Basically: you need RSX (see Prerequisites) for these commands to work, and you may need a port of sh.exe which understands command arguments. One of such ports is listed in Prerequisites under RSX. Do not forget to set variable "PERL_SH_DIR" as well.

DPMI is required for RSX.

Cannot start find.exe "pattern" file

The whole idea of the "standard C API to start applications" is that the forms foo and "foo" of program arguments are completely interchangable. find breaks this paradigm;

  find "pattern" file
  find pattern file

are not equivalent; find cannot be started directly using the above API. One needs a way to surround the doublequotes in some other quoting construction, necessarily having an extra non-Unixish shell in between.

Use one of

  system 'cmd', '/c', 'find "pattern" file';
  `cmd /c 'find "pattern" file'`

This would start find.exe via cmd.exe via sh.exe via perl.exe, but this is a price to pay if you want to use non-conforming program.

INSTALLATION

Automatic binary installation

The most convenient way of installing a binary distribution of perl is via perl installer install.exe. Just follow the instructions, and 99% of the installation blues would go away.

Note however, that you need to have unzip.exe on your path, and EMX environment running. The latter means that if you just installed EMX, and made all the needed changes to Config.sys, you may need to reboot in between. Check EMX runtime by running

        emxrev

Binary installer also creates a folder on your desktop with some useful objects. If you need to change some aspects of the work of the binary installer, feel free to edit the file Perl.pkg. This may be useful e.g., if you need to run the installer many times and do not want to make many interactive changes in the GUI.

Things not taken care of by automatic binary installation:

PERL_BADLANG

may be needed if you change your codepage after perl installation, and the new value is not supported by EMX. See PERL_BADLANG.

PERL_BADFREE

see PERL_BADFREE.

Config.pm

This file resides somewhere deep in the location you installed your perl library, find it out by

  perl -MConfig -le "print $INC{'Config.pm'}"

While most important values in this file are updated by the binary installer, some of them may need to be hand-edited. I know no such data, please keep me informed if you find one. Moreover, manual changes to the installed version may need to be accompanied by an edit of this file.

NOTE. Because of a typo the binary installer of 5.00305 would install a variable PERL_SHPATH into Config.sys. Please remove this variable and put PERL_SH_DIR instead.

Manual binary installation

As of version 5.00305, OS/2 perl binary distribution comes split into 11 components. Unfortunately, to enable configurable binary installation, the file paths in the zip files are not absolute, but relative to some directory.

Note that the extraction with the stored paths is still necessary (default with unzip, specify -d to pkunzip). However, you need to know where to extract the files. You need also to manually change entries in Config.sys to reflect where did you put the files. Note that if you have some primitive unzipper (like pkunzip), you may get a lot of warnings/errors during unzipping. Upgrade to (w)unzip.

Below is the sample of what to do to reproduce the configuration on my machine. In VIEW.EXE you can press Ctrl-Insert now, and cut-and-paste from the resulting file - created in the directory you started VIEW.EXE from.

For each component, we mention environment variables related to each installation directory. Either choose directories to match your values of the variables, or create/append-to variables to take into account the directories.

Perl VIO and PM executables (dynamically linked)
  unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
  unzip perl_exc.zip *.dll -d f:/emx.add/dll

(have the directories with *.exe on PATH, and *.dll on LIBPATH);

Perl_ VIO executable (statically linked)
  unzip perl_aou.zip -d f:/emx.add/bin

(have the directory on PATH);

Executables for Perl utilities
  unzip perl_utl.zip -d f:/emx.add/bin

(have the directory on PATH);

Main Perl library
  unzip perl_mlb.zip -d f:/perllib/lib

If this directory is exactly the same as the prefix which was compiled into perl.exe, you do not need to change anything. However, for perl to find the library if you use a different path, you need to set PERLLIB_PREFIX in Config.sys, see PERLLIB_PREFIX.

Additional Perl modules
  unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.8/

Same remark as above applies. Additionally, if this directory is not one of directories on @INC (and @INC is influenced by PERLLIB_PREFIX), you need to put this directory and subdirectory ./os2 in PERLLIB or PERL5LIB variable. Do not use PERL5LIB unless you have it set already. See ENVIRONMENT in the perl manpage.

[Check whether this extraction directory is still applicable with the new directory structure layout!]

Tools to compile Perl modules
  unzip perl_blb.zip -d f:/perllib/lib

Same remark as for perl_ste.zip.

Manpages for Perl and utilities
  unzip perl_man.zip -d f:/perllib/man

This directory should better be on MANPATH. You need to have a working man to access these files.

Manpages for Perl modules
  unzip perl_mam.zip -d f:/perllib/man

This directory should better be on MANPATH. You need to have a working man to access these files.

Source for Perl documentation
  unzip perl_pod.zip -d f:/perllib/lib

This is used by the perldoc program (see the perldoc manpage), and may be used to generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: info, LaTeX, Acrobat, FrameMaker and so on. [Use programs such as pod2latex etc.]

Perl manual in .INF format
  unzip perl_inf.zip -d d:/os2/book

This directory should better be on BOOKSHELF.

Pdksh
  unzip perl_sh.zip -d f:/bin

This is used by perl to run external commands which explicitly require shell, like the commands using redirection and shell metacharacters. It is also used instead of explicit /bin/sh.

Set PERL_SH_DIR (see PERL_SH_DIR) if you move sh.exe from the above location.

Note. It may be possible to use some other sh-compatible shell (untested).

After you installed the components you needed and updated the Config.sys correspondingly, you need to hand-edit Config.pm. This file resides somewhere deep in the location you installed your perl library, find it out by

  perl -MConfig -le "print $INC{'Config.pm'}"

You need to correct all the entries which look like file paths (they currently start with f:/).

Warning

The automatic and manual perl installation leave precompiled paths inside perl executables. While these paths are overwriteable (see PERLLIB_PREFIX, PERL_SH_DIR), some people may prefer binary editing of paths inside the executables/DLLs.

Accessing documentation

Depending on how you built/installed perl you may have (otherwise identical) Perl documentation in the following formats:

OS/2 .INF file

Most probably the most convenient form. Under OS/2 view it as

  view perl
  view perl perlfunc
  view perl less
  view perl ExtUtils::MakeMaker

(currently the last two may hit a wrong location, but this may improve soon). Under Win* see SYNOPSIS.

If you want to build the docs yourself, and have OS/2 toolkit, run

        pod2ipf > perl.ipf

in /perllib/lib/pod directory, then

        ipfc /inf perl.ipf

(Expect a lot of errors during the both steps.) Now move it on your BOOKSHELF path.

Plain text

If you have perl documentation in the source form, perl utilities installed, and GNU groff installed, you may use

        perldoc perlfunc
        perldoc less
        perldoc ExtUtils::MakeMaker

to access the perl documentation in the text form (note that you may get better results using perl manpages).

Alternately, try running pod2text on .pod files.

Manpages

If you have man installed on your system, and you installed perl manpages, use something like this:

        man perlfunc
        man 3 less
        man ExtUtils.MakeMaker

to access documentation for different components of Perl. Start with

        man perl

Note that dot (.) is used as a package separator for documentation for packages, and as usual, sometimes you need to give the section - 3 above - to avoid shadowing by the less(1) manpage.

Make sure that the directory above the directory with manpages is on our MANPATH, like this

  set MANPATH=c:/man;f:/perllib/man

for Perl manpages in f:/perllib/man/man1/ etc.

HTML

If you have some WWW browser available, installed the Perl documentation in the source form, and Perl utilities, you can build HTML docs. Cd to directory with .pod files, and do like this

        cd f:/perllib/lib/pod
        pod2html

After this you can direct your browser the file perl.html in this directory, and go ahead with reading docs, like this:

        explore file:///f:/perllib/lib/pod/perl.html

Alternatively you may be able to get these docs prebuilt from CPAN.

GNU info files

Users of Emacs would appreciate it very much, especially with CPerl mode loaded. You need to get latest pod2texi from CPAN, or, alternately, the prebuilt info pages.

PDF files

for Acrobat are available on CPAN (may be for slightly older version of perl).

LaTeX docs

can be constructed using pod2latex.

BUILD

Here we discuss how to build Perl under OS/2. There is an alternative (but maybe older) view on http://www.shadow.net/~troc/os2perl.html.

The short story

Assume that you are a seasoned porter, so are sure that all the necessary tools are already present on your system, and you know how to get the Perl source distribution. Untar it, change to the extract directory, and

  gnupatch -p0 < os2\diff.configure
  sh Configure -des -D prefix=f:/perllib
  make
  make test
  make install
  make aout_test
  make aout_install

This puts the executables in f:/perllib/bin. Manually move them to the PATH, manually move the built perl*.dll to LIBPATH (here for Perl DLL * is a not-very-meaningful hex checksum), and run

  make installcmd INSTALLCMDDIR=d:/ir/on/path

Assuming that the man-files were put on an appropriate location, this completes the installation of minimal Perl system. (The binary distribution contains also a lot of additional modules, and the documentation in INF format.)

What follows is a detailed guide through these steps.

Prerequisites

You need to have the latest EMX development environment, the full GNU tool suite (gawk renamed to awk, and GNU find.exe earlier on path than the OS/2 find.exe, same with sort.exe, to check use

  find --version
  sort --version

). You need the latest version of pdksh installed as sh.exe.

Check that you have BSD libraries and headers installed, and - optionally - Berkeley DB headers and libraries, and crypt.

Possible locations to get the files:

  ftp://hobbes.nmsu.edu/os2/unix/
  ftp://ftp.cdrom.com/pub/os2/unix/
  ftp://ftp.cdrom.com/pub/os2/dev32/
  ftp://ftp.cdrom.com/pub/os2/emx09c/

It is reported that the following archives contain enough utils to build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip, gnupatch.zip, gnuawk.zip, gnumake.zip, gnugrep.zip, bsddev.zip and ksh527rt.zip (or a later version). Note that all these utilities are known to be available from LEO:

  ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu

Note also that the db.lib and db.a from the EMX distribution are not suitable for multi-threaded compile (even single-threaded flavor of Perl uses multi-threaded C RTL, for compatibility with XFree86-OS/2). Get a corrected one from

  http://www.ilyaz.org/software/os2/db_mt.zip

If you have exactly the same version of Perl installed already, make sure that no copies or perl are currently running. Later steps of the build may fail since an older version of perl.dll loaded into memory may be found. Running make test becomes meaningless, since the test are checking a previous build of perl (this situation is detected and reported by lib/os2_base.t test). Do not forget to unset PERL_EMXLOAD_SEC in environment.

Also make sure that you have /tmp directory on the current drive, and . directory in your LIBPATH. One may try to correct the latter condition by

  set BEGINLIBPATH .\.

if you use something like CMD.EXE or latest versions of 4os2.exe. (Setting BEGINLIBPATH to just . is ignored by the OS/2 kernel.)

Make sure your gcc is good for -Zomf linking: run omflibs script in /emx/lib directory.

Check that you have link386 installed. It comes standard with OS/2, but may be not installed due to customization. If typing

  link386

shows you do not have it, do Selective install, and choose Link object modules in Optional system utilities/More. If you get into link386 prompts, press Ctrl-C to exit.

Getting perl source

You need to fetch the latest perl source (including developers releases). With some probability it is located in

  http://www.cpan.org/src/5.0
  http://www.cpan.org/src/5.0/unsupported

If not, you may need to dig in the indices to find it in the directory of the current maintainer.

Quick cycle of developers release may break the OS/2 build time to time, looking into

  http://www.cpan.org/ports/os2/

may indicate the latest release which was publicly released by the maintainer. Note that the release may include some additional patches to apply to the current source of perl.

Extract it like this

  tar vzxf perl5.00409.tar.gz

You may see a message about errors while extracting Configure. This is because there is a conflict with a similarly-named file configure.

Change to the directory of extraction.

Application of the patches

You need to apply the patches in ./os2/diff.* like this:

  gnupatch -p0 < os2\diff.configure

You may also need to apply the patches supplied with the binary distribution of perl. It also makes sense to look on the perl5-porters mailing list for the latest OS/2-related patches (see http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/). Such patches usually contain strings /os2/ and patch, so it makes sense looking for these strings.

Hand-editing

You may look into the file ./hints/os2.sh and correct anything wrong you find there. I do not expect it is needed anywhere.

Making

  sh Configure -des -D prefix=f:/perllib

prefix means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify PERLLIB_PREFIX, see PERLLIB_PREFIX.

Ignore the message about missing ln, and about -c option to tr. The latter is most probably already fixed, if you see it and can trace where the latter spurious warning comes from, please inform me.

Now

  make

At some moment the built may die, reporting a version mismatch or unable to run perl. This means that you do not have . in your LIBPATH, so perl.exe cannot find the needed perl67B2.dll (treat these hex digits as line noise). After this is fixed the build should finish without a lot of fuss.

Testing

Now run

  make test

All tests should succeed (with some of them skipped). If you have the same version of Perl installed, it is crucial that you have . early in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most probably test the wrong version of Perl.

Some tests may generate extra messages similar to

A lot of bad free

in database tests related to Berkeley DB. This should be fixed already. If it persists, you may disable this warnings, see PERL_BADFREE.

Process terminated by SIGTERM/SIGINT

This is a standard message issued by OS/2 applications. *nix applications die in silence. It is considered to be a feature. One can easily disable this by appropriate sighandlers.

However the test engine bleeds these message to screen in unexpected moments. Two messages of this kind should be present during testing.

To get finer test reports, call

  perl t/harness

The report with io/pipe.t failing may look like this:

  Failed Test  Status Wstat Total Fail  Failed  List of failed
  ------------------------------------------------------------
  io/pipe.t                    12    1   8.33%  9
  7 tests skipped, plus 56 subtests skipped.
  Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.

The reasons for most important skipped tests are:

op/fs.t

  1. Checks atime and mtime of stat() - unfortunately, HPFS provides only 2sec time granularity (for compatibility with FAT?).

  2. Checks truncate() on a filehandle just opened for write - I do not know why this should or should not work.

op/stat.t

Checks stat(). Tests:

  1. Checks atime and mtime of stat() - unfortunately, HPFS provides only 2sec time granularity (for compatibility with FAT?).

Installing the built perl

If you haven't yet moved perl*.dll onto LIBPATH, do it now.

Run

  make install

It would put the generated files into needed locations. Manually put perl.exe, perl__.exe and perl___.exe to a location on your PATH, perl.dll to a location on your LIBPATH.

Run

  make installcmd INSTALLCMDDIR=d:/ir/on/path

to convert perl utilities to .cmd files and put them on PATH. You need to put .EXE-utilities on path manually. They are installed in $prefix/bin, here $prefix is what you gave to Configure, see Making.

If you use man, either move the installed */man/ directories to your MANPATH, or modify MANPATH to match the location. (One could have avoided this by providing a correct manpath option to ./Configure, or editing ./config.sh between configuring and making steps.)

a.out-style build

Proceed as above, but make perl_.exe (see perl_.exe) by

  make perl_

test and install by

  make aout_test
  make aout_install

Manually put perl_.exe to a location on your PATH.

Note. The build process for perl_ does not know about all the dependencies, so you should make sure that anything is up-to-date, say, by doing

  make perl_dll

first.

Building a binary distribution

[This section provides a short overview only...]

Building should proceed differently depending on whether the version of perl you install is already present and used on your system, or is a new version not yet used. The description below assumes that the version is new, so installing its DLLs and .pm files will not disrupt the operation of your system even if some intermediate steps are not yet fully working.

The other cases require a little bit more convoluted procedures. Below I suppose that the current version of Perl is 5.8.2, so the executables are named accordingly.

  1. Fully build and test the Perl distribution. Make sure that no tests are failing with test and aout_test targets; fix the bugs in Perl and the Perl test suite detected by these tests. Make sure that all_test make target runs as clean as possible. Check that os2/perlrexx.cmd runs fine.

  2. Fully install Perl, including installcmd target. Copy the generated DLLs to LIBPATH; copy the numbered Perl executables (as in perl5.8.2.exe) to PATH; copy perl_.exe to PATH as perl_5.8.2.exe. Think whether you need backward-compatibility DLLs. In most cases you do not need to install them yet; but sometime this may simplify the following steps.

  3. Make sure that CPAN.pm can download files from CPAN. If not, you may need to manually install Net::FTP.

  4. Install the bundle Bundle::OS2_default

      perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1

    This may take a couple of hours on 1GHz processor (when run the first time). And this should not be necessarily a smooth procedure. Some modules may not specify required dependencies, so one may need to repeat this procedure several times until the results stabilize.

      perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
  perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3

    Even after they stabilize, some tests may fail.

    Fix as many discovered bugs as possible. Document all the bugs which are not fixed, and all the failures with unknown reasons. Inspect the produced logs 00cpan_i_1 to find suspiciously skipped tests, and other fishy events.

    Keep in mind that installation of some modules may fail too: for example, the DLLs to update may be already loaded by CPAN.pm. Inspect the install logs (in the example above 00cpan_i_1 etc) for errors, and install things manually, as in

      cd $CPANHOME/.cpan/build/Digest-MD5-2.31
  make install

    Some distributions may fail some tests, but you may want to install them anyway (as above, or via force install command of CPAN.pm shell-mode).

    Since this procedure may take quite a long time to complete, it makes sense to "freeze" your CPAN configuration by disabling periodic updates of the local copy of CPAN index: set index_expire to some big value (I use 365), then save the settings

      CPAN> o conf index_expire 365
  CPAN> o conf commit

    Reset back to the default value 1 when you are finished.

  5. When satisfied with the results, rerun the installcmd target. Now you can copy perl5.8.2.exe to perl.exe, and install the other OMF-build executables: perl__.exe etc. They are ready to be used.

  6. Change to the ./pod directory of the build tree, download the Perl logo CamelGrayBig.BMP, and run

      ( perl2ipf > perl.ipf ) |& tee 00ipf
  ipfc /INF perl.ipf |& tee 00inf

    This produces the Perl docs online book perl.INF. Install in on BOOKSHELF path.

  7. Now is the time to build statically linked executable perl_.exe which includes newly-installed via Bundle::OS2_default modules. Doing testing via CPAN.pm is going to be painfully slow, since it statically links a new executable per XS extension.

    Here is a possible workaround: create a toplevel Makefile.PL in $CPANHOME/.cpan/build/ with contents being (compare with Making executables with a custom collection of statically loaded extensions)

      use ExtUtils::MakeMaker;
  WriteMakefile NAME => 'dummy';

    execute this as

      perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
  make -k all test <nul |& 00aout_t1

    Again, this procedure should not be absolutely smooth. Some Makefile.PL's in subdirectories may be buggy, and would not run as "child" scripts. The interdependency of modules can strike you; however, since non-XS modules are already installed, the prerequisites of most modules have a very good chance to be present.

    If you discover some glitches, move directories of problematic modules to a different location; if these modules are non-XS modules, you may just ignore them - they are already installed; the remaining, XS, modules you need to install manually one by one.

    After each such removal you need to rerun the Makefile.PL/make process; usually this procedure converges soon. (But be sure to convert all the necessary external C libraries from .lib format to .a format: run one of

      emxaout foo.lib
  emximp -o foo.a foo.lib

    whichever is appropriate.) Also, make sure that the DLLs for external libraries are usable with with executables compiled without -Zmtd options.

    When you are sure that only a few subdirectories lead to failures, you may want to add -j4 option to make to speed up skipping subdirectories with already finished build.

    When you are satisfied with the results of tests, install the build C libraries for extensions:

      make install |& tee 00aout_i

    Now you can rename the file ./perl.exe generated during the last phase to perl_5.8.2.exe; place it on PATH; if there is an inter-dependency between some XS modules, you may need to repeat the test/install loop with this new executable and some excluded modules - until the procedure converges.

    Now you have all the necessary .a libraries for these Perl modules in the places where Perl builder can find it. Use the perl builder: change to an empty directory, create a "dummy" Makefile.PL again, and run

      perl_5.8.2.exe Makefile.PL |& tee 00c
  make perl                  |& tee 00p

    This should create an executable ./perl.exe with all the statically loaded extensions built in. Compare the generated perlmain.c files to make sure that during the iterations the number of loaded extensions only increases. Rename ./perl.exe to perl_5.8.2.exe on PATH.

    When it converges, you got a functional variant of perl_5.8.2.exe; copy it to perl_.exe. You are done with generation of the local Perl installation.

  8. Make sure that the installed modules are actually installed in the location of the new Perl, and are not inherited from entries of @INC given for inheritance from the older versions of Perl: set PERLLIB_582_PREFIX to redirect the new version of Perl to a new location, and copy the installed files to this new location. Redo the tests to make sure that the versions of modules inherited from older versions of Perl are not needed.

    Actually, the log output of pod2ipf during the step 6 gives a very detailed info about which modules are loaded from which place; so you may use it as an additional verification tool.

    Check that some temporary files did not make into the perl install tree. Run something like this

      pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less

    in the install tree (both top one and sitelib one).

    Compress all the DLLs with lxlite. The tiny .exe can be compressed with /c:max (the bug only appears when there is a fixup in the last 6 bytes of a page (?); since the tiny executables are much smaller than a page, the bug will not hit). Do not compress perl_.exe - it would not work under DOS.

  9. Now you can generate the binary distribution. This is done by running the test of the CPAN distribution OS2::SoftInstaller. Tune up the file test.pl to suit the layout of current version of Perl first. Do not forget to pack the necessary external DLLs accordingly. Include the description of the bugs and test suite failures you could not fix. Include the small-stack versions of Perl executables from Perl build directory.

    Include perl5.def so that people can relink the perl DLL preserving the binary compatibility, or can create compatibility DLLs. Include the diff files (diff -pu old new) of fixes you did so that people can rebuild your version. Include perl5.map so that one can use remote debugging.

  10. Share what you did with the other people. Relax. Enjoy fruits of your work.

  11. Brace yourself for thanks, bug reports, hate mail and spam coming as result of the previous step. No good deed should remain unpunished!

Building custom .EXE files

The Perl executables can be easily rebuilt at any moment. Moreover, one can use the embedding interface (see the perlembed manpage) to make very customized executables.

Making executables with a custom collection of statically loaded extensions

It is a little bit easier to do so while decreasing the list of statically loaded extensions. We discuss this case only here.

  1. Change to an empty directory, and create a placeholder <Makefile.PL>:

      use ExtUtils::MakeMaker;
  WriteMakefile NAME => 'dummy';

  2. Run it with the flavor of Perl (perl.exe or perl_.exe) you want to rebuild.

      perl_ Makefile.PL

  3. Ask it to create new Perl executable:

      make perl

    (you may need to manually add PERLTYPE=-DPERL_CORE to this commandline on some versions of Perl; the symptom is that the command-line globbing does not work from OS/2 shells with the newly-compiled executable; check with

      .\perl.exe -wle "print for @ARGV" *

    ).

  4. The previous step created perlmain.c which contains a list of newXS() calls near the end. Removing unnecessary calls, and rerunning

      make perl

    will produce a customized executable.

Making executables with a custom search-paths

The default perl executable is flexible enough to support most usages. However, one may want something yet more flexible; for example, one may want to find Perl DLL relatively to the location of the EXE file; or one may want to ignore the environment when setting the Perl-library search patch, etc.

If you fill comfortable with embedding interface (see the perlembed manpage), such things are easy to do repeating the steps outlined in Making executables with a custom collection of statically loaded extensions, and doing more comprehensive edits to main() of perlmain.c. The people with little desire to understand Perl can just rename main(), and do necessary modification in a custom main() which calls the renamed function in appropriate time.

However, there is a third way: perl DLL exports the main() function and several callbacks to customize the search path. Below is a complete example of a "Perl loader" which

  1. Looks for Perl DLL in the directory $exedir/../dll;

  2. Prepends the above directory to BEGINLIBPATH;

  3. Fails if the Perl DLL found via BEGINLIBPATH is different from what was loaded on step 1; e.g., another process could have loaded it from LIBPATH or from a different value of BEGINLIBPATH. In these cases one needs to modify the setting of the system so that this other process either does not run, or loads the DLL from BEGINLIBPATH with LIBPATHSTRICT=T (available with kernels after September 2000).

  4. Loads Perl library from $exedir/../dll/lib/.

  5. Uses Bourne shell from $exedir/../dll/sh/ksh.exe.

For best results compile the C file below with the same options as the Perl DLL. However, a lot of functionality will work even if the executable is not an EMX applications, e.g., if compiled with

  gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO

Here is the sample C file:

  #define INCL_DOS
  #define INCL_NOPM
  /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
  #define INCL_DOSPROCESS
  #include <os2.h>
  #include "EXTERN.h"
  #define PERL_IN_MINIPERLMAIN_C
  #include "perl.h"

  static char *me;
  HMODULE handle;

  static void
  die_with(char *msg1, char *msg2, char *msg3, char *msg4)
  {
     ULONG c;
     char *s = " error: ";

     DosWrite(2, me, strlen(me), &c);
     DosWrite(2, s, strlen(s), &c);
     DosWrite(2, msg1, strlen(msg1), &c);
     DosWrite(2, msg2, strlen(msg2), &c);
     DosWrite(2, msg3, strlen(msg3), &c);
     DosWrite(2, msg4, strlen(msg4), &c);
     DosWrite(2, "\r\n", 2, &c);
     exit(255);
       }

  typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
  typedef int (*main_t)(int type, char *argv[], char *env[]);
  typedef int (*handler_t)(void* data, int which);

  #ifndef PERL_DLL_BASENAME
  #  define PERL_DLL_BASENAME "perl"
  #endif

  static HMODULE
  load_perl_dll(char *basename)
  {
      char buf[300], fail[260];
      STRLEN l, dirl;
      fill_extLibpath_t f;
      ULONG rc_fullname;
      HMODULE handle, handle1;

      if (_execname(buf, sizeof(buf) - 13) != 0)
          die_with("Can't find full path: ", strerror(errno), "", "");
      /* XXXX Fill `me' with new value */
      l = strlen(buf);
      while (l && buf[l-1] != '/' && buf[l-1] != '\\')
          l--;
      dirl = l - 1;
      strcpy(buf + l, basename);
      l += strlen(basename);
      strcpy(buf + l, ".dll");
      if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
           && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
          die_with("Can't load DLL ", buf, "", "");
      if (rc_fullname)
          return handle;                /* was loaded with short name; all is fine */
      if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
          die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
      buf[dirl] = 0;
      if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
            0 /* keep old value */, me))
          die_with(me, ": prepending BEGINLIBPATH", "", "");
      if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
          die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
      buf[dirl] = '\\';
      if (handle1 != handle) {
          if (DosQueryModuleName(handle1, sizeof(fail), fail))
              strcpy(fail, "???");
          die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
                   fail,
                   "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
                   "\n\tso that the other copy is loaded via BEGINLIBPATH.");
      }
      return handle;
        }

  int
  main(int argc, char **argv, char **env)
  {
      main_t f;
      handler_t h;

      me = argv[0];
      /**/
      handle = load_perl_dll(PERL_DLL_BASENAME);

      if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
          die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
      if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
           || !h((void *)"~dll", Perlos2_handler_perllib_to)
           || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
          die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");

      if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
          die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
      return f(argc, argv, env);
        }

Build FAQ

Some / became \ in pdksh.

You have a very old pdksh. See Prerequisites.

'errno' - unresolved external

You do not have MT-safe db.lib. See Prerequisites.

Problems with tr or sed

reported with very old version of tr and sed.

Some problem (forget which ;-)

You have an older version of perl.dll on your LIBPATH, which broke the build of extensions.

Library ... not found

You did not run omflibs. See Prerequisites.

Segfault in make

You use an old version of GNU make. See Prerequisites.

op/sprintf test failure

This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.

Specific (mis)features of OS/2 port

setpriority, getpriority

Note that these functions are compatible with *nix, not with the older ports of '94 - 95. The priorities are absolute, go from 32 to -95, lower is quicker. 0 is the default priority.

WARNING. Calling getpriority on a non-existing process could lock the system before Warp3 fixpak22. Starting with Warp3, Perl will use a workaround: it aborts getpriority() if the process is not present. This is not possible on older versions 2.*, and has a race condition anyway.

system()

Multi-argument form of system() allows an additional numeric argument. The meaning of this argument is described in the OS2::Process manpage.

When finding a program to run, Perl first asks the OS to look for executables on PATH (OS/2 adds extension .exe if no extension is present). If not found, it looks for a script with possible extensions added in this order: no extension, .cmd, .btm, .bat, .pl. If found, Perl checks the start of the file for magic strings "#!" and "extproc ". If found, Perl uses the rest of the first line as the beginning of the command line to run this script. The only mangling done to the first line is extraction of arguments (currently up to 3), and ignoring of the path-part of the "interpreter" name if it can't be found using the full path.

E.g., system 'foo', 'bar', 'baz' may lead Perl to finding C:/emx/bin/foo.cmd with the first line being

 extproc /bin/bash    -x   -c

If /bin/bash.exe is not found, then Perl looks for an executable bash.exe on PATH. If found in C:/emx.add/bin/bash.exe, then the above system() is translated to

  system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)

One additional translation is performed: instead of /bin/sh Perl uses the hardwired-or-customized shell (see "PERL_SH_DIR").

The above search for "interpreter" is recursive: if bash executable is not found, but bash.btm is found, Perl will investigate its first line etc. The only hardwired limit on the recursion depth is implicit: there is a limit 4 on the number of additional arguments inserted before the actual arguments given to system(). In particular, if no additional arguments are specified on the "magic" first lines, then the limit on the depth is 4.

If Perl finds that the found executable is of PM type when the current session is not, it will start the new process in a separate session of necessary type. Call via OS2::Process to disable this magic.

WARNING. Due to the described logic, you need to explicitly specify .com extension if needed. Moreover, if the executable perl5.6.1 is requested, Perl will not look for perl5.6.1.exe. [This may change in the future.]

extproc on the first line

If the first chars of a Perl script are "extproc ", this line is treated as #!-line, thus all the switches on this line are processed (twice if script was started via cmd.exe). See DESCRIPTION in the perlrun manpage.

Additional modules:

the OS2::Process manpage, the OS2::DLL manpage, the OS2::REXX manpage, the OS2::PrfDB manpage, the OS2::ExtAttr manpage. These modules provide access to additional numeric argument for system and to the information about the running process, to DLLs having functions with REXX signature and to the REXX runtime, to OS/2 databases in the .INI format, and to Extended Attributes.

Two additional extensions by Andreas Kaiser, OS2::UPM, and OS2::FTP, are included into ILYAZ directory, mirrored on CPAN. Other OS/2-related extensions are available too.

Prebuilt methods:

File::Copy::syscopy

used by File::Copy::copy, see the File::Copy manpage.

DynaLoader::mod2fname

used by DynaLoader for DLL name mangling.

Cwd::current_drive()

Self explanatory.

Cwd::sys_chdir(name)

leaves drive as it is.

Cwd::change_drive(name)

chanes the "current" drive.

Cwd::sys_is_absolute(name)

means has drive letter and is_rooted.

Cwd::sys_is_rooted(name)

means has leading [/\\] (maybe after a drive-letter:).

Cwd::sys_is_relative(name)

means changes with current dir.

Cwd::sys_cwd(name)

Interface to cwd from EMX. Used by Cwd::cwd.

Cwd::sys_abspath(name, dir)

Really really odious function to implement. Returns absolute name of file which would have name if CWD were dir. Dir defaults to the current dir.

Cwd::extLibpath([type])

Get current value of extended library search path. If type is present and positive, works with END_LIBPATH, if negative, works with LIBPATHSTRICT, otherwise with BEGIN_LIBPATH.

Cwd::extLibpath_set( path [, type ] )

Set current value of extended library search path. If type is present and positive, works with <END_LIBPATH>, if negative, works with LIBPATHSTRICT, otherwise with BEGIN_LIBPATH.

OS2::Error(do_harderror,do_exception)

Returns undef if it was not called yet, otherwise bit 1 is set if on the previous call do_harderror was enabled, bit 2 is set if on previous call do_exception was enabled.

This function enables/disables error popups associated with hardware errors (Disk not ready etc.) and software exceptions.

I know of no way to find out the state of popups before the first call to this function.

OS2::Errors2Drive(drive)

Returns undef if it was not called yet, otherwise return false if errors were not requested to be written to a hard drive, or the drive letter if this was requested.

This function may redirect error popups associated with hardware errors (Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at the root directory of the specified drive. Overrides OS2::Error() specified by individual programs. Given argument undef will disable redirection.

Has global effect, persists after the application exits.

I know of no way to find out the state of redirection of popups to the disk before the first call to this function.

OS2::SysInfo()

Returns a hash with system information. The keys of the hash are

        MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
        MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
        MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
        VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
        MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
        TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
        MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
        FOREGROUND_PROCESS
OS2::BootDrive()

Returns a letter without colon.

OS2::MorphPM(serve), OS2::UnMorphPM(serve)

Transforms the current application into a PM application and back. The argument true means that a real message loop is going to be served. OS2::MorphPM() returns the PM message queue handle as an integer.

See Centralized management of resources for additional details.

OS2::Serve_Messages(force)

Fake on-demand retrieval of outstanding PM messages. If force is false, will not dispatch messages if a real message loop is known to be present. Returns number of messages retrieved.

Dies with "QUITing..." if WM_QUIT message is obtained.

OS2::Process_Messages(force [, cnt])

Retrieval of PM messages until window creation/destruction. If force is false, will not dispatch messages if a real message loop is known to be present.

Returns change in number of windows. If cnt is given, it is incremented by the number of messages retrieved.

Dies with "QUITing..." if WM_QUIT message is obtained.

OS2::_control87(new,mask)

the same as _control87(3) of EMX. Takes integers as arguments, returns the previous coprocessor control word as an integer. Only bits in new which are present in mask are changed in the control word.

OS2::get_control87()

gets the coprocessor control word as an integer.

OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)

The variant of OS2::_control87() with default values good for handling exception mask: if no mask, uses exception mask part of new only. If no new, disables all the floating point exceptions.

See Misfeatures for details.

OS2::DLLname([how [, \&xsub]])

Gives the information about the Perl DLL or the DLL containing the C function bound to by &xsub. The meaning of how is: default (2): full name; 0: handle; 1: module name.

(Note that some of these may be moved to different libraries - eventually).

Prebuilt variables:

$OS2::emx_rev

numeric value is the same as _emx_rev of EMX, a string value the same as _emx_vprt (similar to 0.9c).

$OS2::emx_env

same as _emx_env of EMX, a number similar to 0x8001.

$OS2::os_ver

a number OS_MAJOR + 0.001 * OS_MINOR.

$OS2::is_aout

true if the Perl library was compiled in AOUT format.

$OS2::can_fork

true if the current executable is an AOUT EMX executable, so Perl can fork. Do not use this, use the portable check for $Config::Config{dfork}.

$OS2::nsyserror

This variable (default is 1) controls whether to enforce the contents of $^E to start with SYS0003-like id. If set to 0, then the string value of $^E is what is available from the OS/2 message file. (Some messages in this file have an SYS0003-like id prepended, some not.)

Misfeatures

  • Since flock(3) is present in EMX, but is not functional, it is emulated by perl. To disable the emulations, set environment variable USE_PERL_FLOCK=0.

  • Here is the list of things which may be "broken" on EMX (from EMX docs):

    • The functions recvmsg(3), sendmsg(3), and socketpair(3) are not implemented.

    • sock_init(3) is not required and not implemented.

    • flock(3) is not yet implemented (dummy function). (Perl has a workaround.)

    • kill(3): Special treatment of PID=0, PID=1 and PID=-1 is not implemented.

    • waitpid(3):

            WUNTRACED
              Not implemented.
      waitpid() is not implemented for negative values of PID.

    Note that kill -9 does not work with the current version of EMX.

  • See Text-mode filehandles.

  • Unix-domain sockets on OS/2 live in a pseudo-file-system /sockets/.... To avoid a failure to create a socket with a name of a different form, "/socket/" is prepended to the socket name (unless it starts with this already).

    This may lead to problems later in case the socket is accessed via the "usual" file-system calls using the "initial" name.

  • Apparently, IBM used a compiler (for some period of time around '95?) which changes FP mask right and left. This is not that bad for IBM's programs, but the same compiler was used for DLLs which are used with general-purpose applications. When these DLLs are used, the state of floating-point flags in the application is not predictable.

    What is much worse, some DLLs change the floating point flags when in _DLLInitTerm() (e.g., TCP32IP). This means that even if you do not call any function in the DLL, just the act of loading this DLL will reset your flags. What is worse, the same compiler was used to compile some HOOK DLLs. Given that HOOK dlls are executed in the context of all the applications in the system, this means a complete unpredictablity of floating point flags on systems using such HOOK DLLs. E.g., GAMESRVR.DLL of DIVE origin changes the floating point flags on each write to the TTY of a VIO (windowed text-mode) applications.

    Some other (not completely debugged) situations when FP flags change include some video drivers (?), and some operations related to creation of the windows. People who code OpenGL may have more experience on this.

    Perl is generally used in the situation when all the floating-point exceptions are ignored, as is the default under EMX. If they are not ignored, some benign Perl programs would get a SIGFPE and would die a horrible death.

    To circumvent this, Perl uses two hacks. They help against one type of damage only: FP flags changed when loading a DLL.

    One of the hacks is to disable floating point exceptions on Perl startup (as is the default with EMX). This helps only with compile-time-linked DLLs changing the flags before main() had a chance to be called.

    The other hack is to restore FP flags after a call to dlopen(). This helps against similar damage done by DLLs _DLLInitTerm() at runtime. Currently no way to switch these hacks off is provided.

Modifications

Perl modifies some standard C library calls in the following ways:

popen

my_popen uses sh.exe if shell is required, cf. PERL_SH_DIR.

tmpnam

is created using TMP or TEMP environment variable, via tempnam.

tmpfile

If the current directory is not writable, file is created using modified tmpnam, so there may be a race condition.

ctermid

a dummy implementation.

stat

os2_stat special-cases /dev/tty and /dev/con.

mkdir, rmdir

these EMX functions do not work if the path contains a trailing /. Perl contains a workaround for this.

flock

Since flock(3) is present in EMX, but is not functional, it is emulated by perl. To disable the emulations, set environment variable USE_PERL_FLOCK=0.

Identifying DLLs

All the DLLs built with the current versions of Perl have ID strings identifying the name of the extension, its version, and the version of Perl required for this DLL. Run bldlevel DLL-name to find this info.

Centralized management of resources

Since to call certain OS/2 API one needs to have a correctly initialized Win subsystem, OS/2-specific extensions may require getting HABs and HMQs. If an extension would do it on its own, another extension could fail to initialize.

Perl provides a centralized management of these resources:

HAB

To get the HAB, the extension should call hab = perl_hab_GET() in C. After this call is performed, hab may be accessed as Perl_hab. There is no need to release the HAB after it is used.

If by some reasons perl.h cannot be included, use

  extern int Perl_hab_GET(void);

instead.

HMQ

There are two cases:

  • the extension needs an HMQ only because some API will not work otherwise. Use serve = 0 below.

  • the extension needs an HMQ since it wants to engage in a PM event loop. Use serve = 1 below.

To get an HMQ, the extension should call hmq = perl_hmq_GET(serve) in C. After this call is performed, hmq may be accessed as Perl_hmq.

To signal to Perl that HMQ is not needed any more, call perl_hmq_UNSET(serve). Perl process will automatically morph/unmorph itself into/from a PM process if HMQ is needed/not-needed. Perl will automatically enable/disable WM_QUIT message during shutdown if the message queue is served/not-served.

NOTE. If during a shutdown there is a message queue which did not disable WM_QUIT, and which did not process the received WM_QUIT message, the shutdown will be automatically cancelled. Do not call perl_hmq_GET(1) unless you are going to process messages on an orderly basis.

  • Treating errors reported by OS/2 API

    There are two principal conventions (it is useful to call them Dos* and Win* - though this part of the function signature is not always determined by the name of the API) of reporting the error conditions of OS/2 API. Most of Dos* APIs report the error code as the result of the call (so 0 means success, and there are many types of errors). Most of Win* API report success/fail via the result being TRUE/FALSE; to find the reason for the failure one should call WinGetLastError() API.

    Some Win* entry points also overload a "meaningful" return value with the error indicator; having a 0 return value indicates an error. Yet some other Win* entry points overload things even more, and 0 return value may mean a successful call returning a valid value 0, as well as an error condition; in the case of a 0 return value one should call WinGetLastError() API to distinguish a successful call from a failing one.

    By convention, all the calls to OS/2 API should indicate their failures by resetting $^E. All the Perl-accessible functions which call OS/2 API may be broken into two classes: some die()s when an API error is encountered, the other report the error via a false return value (of course, this does not concern Perl-accessible functions which expect a failure of the OS/2 API call, having some workarounds coded).

    Obviously, in the situation of the last type of the signature of an OS/2 API, it is must more convenient for the users if the failure is indicated by die()ing: one does not need to check $^E to know that something went wrong. If, however, this solution is not desirable by some reason, the code in question should reset $^E to 0 before making this OS/2 API call, so that the caller of this Perl-accessible function has a chance to distinguish a success-but-0-return value from a failure. (One may return undef as an alternative way of reporting an error.)

    The macros to simplify this type of error propagation are

    CheckOSError(expr)

    Returns true on error, sets $^E. Expects expr() be a call of Dos*-style API.

    • CheckWinError(expr)

    Returns true on error, sets $^E. Expects expr() be a call of Win*-style API.

    SaveWinError(expr)

    Returns expr, sets $^E from WinGetLastError() if expr is false.

    SaveCroakWinError(expr,die,name1,name2)

    Returns expr, sets $^E from WinGetLastError() if expr is false, and die()s if die and $^E are true. The message to die is the concatenated strings name1 and name2, separated by ": " from the contents of $^E.

    WinError_2_Perl_rc

    Sets Perl_rc to the return value of WinGetLastError().

    FillWinError

    Sets Perl_rc to the return value of WinGetLastError(), and sets $^E to the corresponding value.

    FillOSError(rc)

    Sets Perl_rc to rc, and sets $^E to the corresponding value.

  • Loading DLLs and ordinals in DLLs

    Some DLLs are only present in some versions of OS/2, or in some configurations of OS/2. Some exported entry points are present only in DLLs shipped with some versions of OS/2. If these DLLs and entry points were linked directly for a Perl executable/DLL or from a Perl extensions, this binary would work only with the specified versions/setups. Even if these entry points were not needed, the load of the executable (or DLL) would fail.

    For example, many newer useful APIs are not present in OS/2 v2; many PM-related APIs require DLLs not available on floppy-boot setup.

    To make these calls fail only when the calls are executed, one should call these API via a dynamic linking API. There is a subsystem in Perl to simplify such type of calls. A large number of entry points available for such linking is provided (see entries_ordinals - and also PMWIN_entries - in os2ish.h). These ordinals can be accessed via the APIs:

      CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
  DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
  DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
  DeclWinFuncByORD_CACHE_resetError_survive(),
  DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
  DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()

    See the header files and the C code in the supplied OS/2-related modules for the details on usage of these functions.

    Some of these functions also combine dynaloading semantic with the error-propagation semantic discussed above.

    • Perl flavors

    Because of idiosyncrasies of OS/2 one cannot have all the eggs in the same basket (though EMX environment tries hard to overcome this limitations, so the situation may somehow improve). There are 4 executables for Perl provided by the distribution:

    perl.exe

    The main workhorse. This is a chimera executable: it is compiled as an a.out-style executable, but is linked with omf-style dynamic library perl.dll, and with dynamic CRT DLL. This executable is a VIO application.

    It can load perl dynamic extensions, and it can fork().

    Note. Keep in mind that fork() is needed to open a pipe to yourself.

    perl_.exe

    This is a statically linked a.out-style executable. It cannot load dynamic Perl extensions. The executable supplied in binary distributions has a lot of extensions prebuilt, thus the above restriction is important only if you use custom-built extensions. This executable is a VIO application.

    This is the only executable with does not require OS/2. The friends locked into M$ world would appreciate the fact that this executable runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate extender. See Other OSes.

    perl__.exe

    This is the same executable as perl___.exe, but it is a PM application.

    Note. Usually (unless explicitly redirected during the startup) STDIN, STDERR, and STDOUT of a PM application are redirected to nul. However, it is possible to see them if you start perl__.exe from a PM program which emulates a console window, like Shell mode of Emacs or EPM. Thus it is possible to use Perl debugger (see the perldebug manpage) to debug your PM application (but beware of the message loop lockups - this will not work if you have a message queue to serve, unless you hook the serving into the getc() function of the debugger).

    Another way to see the output of a PM program is to run it as

      pm_prog args 2>&1 | cat -

    with a shell different from cmd.exe, so that it does not create a link between a VIO session and the session of pm_porg. (Such a link closes the VIO window.) E.g., this works with sh.exe - or with Perl!

      open P, 'pm_prog args 2>&1 |' or die;
  print while <P>;

    The flavor perl__.exe is required if you want to start your program without a VIO window present, but not detached (run help detach for more info). Very useful for extensions which use PM, like Perl/Tk or OpenGL.

    Note also that the differences between PM and VIO executables are only in the default behaviour. One can start any executable in any kind of session by using the arguments /fs, /pm or /win switches of the command start (of CMD.EXE or a similar shell). Alternatively, one can use the numeric first argument of the system Perl function (see the OS2::Process manpage).

    perl___.exe

    This is an omf-style executable which is dynamically linked to perl.dll and CRT DLL. I know no advantages of this executable over perl.exe, but it cannot fork() at all. Well, one advantage is that the build process is not so convoluted as with perl.exe.

    It is a VIO application.

    Why strange names?

    Since Perl processes the #!-line (cf. DESCRIPTION in the perlrun manpage, Switches in the perlrun manpage, Not a perl script in the perldiag manpage, No Perl script found in input in the perldiag manpage), it should know when a program is a Perl. There is some naming convention which allows Perl to distinguish correct lines from wrong ones. The above names are almost the only names allowed by this convention which do not contain digits (which have absolutely different semantics).

    Why dynamic linking?

    Well, having several executables dynamically linked to the same huge library has its advantages, but this would not substantiate the additional work to make it compile. The reason is the complicated-to-developers but very quick and convenient-to-users "hard" dynamic linking used by OS/2.

    There are two distinctive features of the dyna-linking model of OS/2: first, all the references to external functions are resolved at the compile time; second, there is no runtime fixup of the DLLs after they are loaded into memory. The first feature is an enormous advantage over other models: it avoids conflicts when several DLLs used by an application export entries with the same name. In such cases "other" models of dyna-linking just choose between these two entry points using some random criterion - with predictable disasters as results. But it is the second feature which requires the build of perl.dll.

    The address tables of DLLs are patched only once, when they are loaded. The addresses of the entry points into DLLs are guaranteed to be the same for all the programs which use the same DLL. This removes the runtime fixup - once DLL is loaded, its code is read-only.

    While this allows some (significant?) performance advantages, this makes life much harder for developers, since the above scheme makes it impossible for a DLL to be "linked" to a symbol in the .EXE file. Indeed, this would need a DLL to have different relocations tables for the (different) executables which use this DLL.

    However, a dynamically loaded Perl extension is forced to use some symbols from the perl executable, e.g., to know how to find the arguments to the functions: the arguments live on the perl internal evaluation stack. The solution is to put the main code of the interpreter into a DLL, and make the .EXE file which just loads this DLL into memory and supplies command-arguments. The extension DLL cannot link to symbols in .EXE, but it has no problem linking to symbols in the .DLL.

    This greatly increases the load time for the application (as well as complexity of the compilation). Since interpreter is in a DLL, the C RTL is basically forced to reside in a DLL as well (otherwise extensions would not be able to use CRT). There are some advantages if you use different flavors of perl, such as running perl.exe and perl__.exe simultaneously: they share the memory of perl.dll.

    NOTE. There is one additional effect which makes DLLs more wasteful: DLLs are loaded in the shared memory region, which is a scarse resource given the 512M barrier of the "standard" OS/2 virtual memory. The code of .EXE files is also shared by all the processes which use the particular .EXE, but they are "shared in the private address space of the process"; this is possible because the address at which different sections of the .EXE file are loaded is decided at compile-time, thus all the processes have these sections loaded at same addresses, and no fixup of internal links inside the .EXE is needed.

    Since DLLs may be loaded at run time, to have the same mechanism for DLLs one needs to have the address range of any of the loaded DLLs in the system to be available in all the processes which did not load a particular DLL yet. This is why the DLLs are mapped to the shared memory region.

    Why chimera build?

    Current EMX environment does not allow DLLs compiled using Unixish a.out format to export symbols for data (or at least some types of data). This forces omf-style compile of perl.dll.

    Current EMX environment does not allow .EXE files compiled in omf format to fork(). fork() is needed for exactly three Perl operations:

    • explicit fork() in the script,

    • open FH, "|-"

    • open FH, "-|", in other words, opening pipes to itself.

    While these operations are not questions of life and death, they are needed for a lot of useful scripts. This forces a.out-style compile of perl.exe.

    ENVIRONMENT

    Here we list environment variables with are either OS/2- and DOS- and Win*-specific, or are more important under OS/2 than under other OSes.

    PERLLIB_PREFIX

    Specific for EMX port. Should have the form

      path1;path2

    or

      path1 path2

    If the beginning of some prebuilt path matches path1, it is substituted with path2.

    Should be used if the perl library is moved from the default location in preference to PERL(5)LIB, since this would not leave wrong entries in @INC. For example, if the compiled version of perl looks for @INC in f:/perllib/lib, and you want to install the library in h:/opt/gnu, do

      set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu

    This will cause Perl with the prebuilt @INC of

      f:/perllib/lib/5.00553/os2
  f:/perllib/lib/5.00553
  f:/perllib/lib/site_perl/5.00553/os2
  f:/perllib/lib/site_perl/5.00553
  .

    to use the following @INC:

      h:/opt/gnu/5.00553/os2
  h:/opt/gnu/5.00553
  h:/opt/gnu/site_perl/5.00553/os2
  h:/opt/gnu/site_perl/5.00553
  .

    PERL_BADLANG

    If 0, perl ignores setlocale() failing. May be useful with some strange locales.

    PERL_BADFREE

    If 0, perl would not warn of in case of unwarranted free(). With older perls this might be useful in conjunction with the module DB_File, which was buggy when dynamically linked and OMF-built.

    Should not be set with newer Perls, since this may hide some real problems.

    PERL_SH_DIR

    Specific for EMX port. Gives the directory part of the location for sh.exe.

    USE_PERL_FLOCK

    Specific for EMX port. Since flock(3) is present in EMX, but is not functional, it is emulated by perl. To disable the emulations, set environment variable USE_PERL_FLOCK=0.

    TMP or TEMP

    Specific for EMX port. Used as storage place for temporary files.

    Evolution

    Here we list major changes which could make you by surprise.

    Text-mode filehandles

    Starting from version 5.8, Perl uses a builtin translation layer for text-mode files. This replaces the efficient well-tested EMX layer by some code which should be best characterized as a "quick hack".

    In addition to possible bugs and an inability to follow changes to the translation policy with off/on switches of TERMIO translation, this introduces a serious incompatible change: before sysread() on text-mode filehandles would go through the translation layer, now it would not.

    Priorities

    setpriority and getpriority are not compatible with earlier ports by Andreas Kaiser. See "setpriority, getpriority".

    DLL name mangling: pre 5.6.2

    With the release 5.003_01 the dynamically loadable libraries should be rebuilt when a different version of Perl is compiled. In particular, DLLs (including perl.dll) are now created with the names which contain a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.

    It may be possible to code a simple workaround which would

    • find the old DLLs looking through the old @INC;

    • mangle the names according to the scheme of new perl and copy the DLLs to these names;

    • edit the internal LX tables of DLL to reflect the change of the name (probably not needed for Perl extension DLLs, since the internally coded names are not used for "specific" DLLs, they used only for "global" DLLs).

    • edit the internal IMPORT tables and change the name of the "old" perl????.dll to the "new" perl????.dll.

    DLL name mangling: 5.6.2 and beyond

    In fact mangling of extension DLLs was done due to misunderstanding of the OS/2 dynaloading model. OS/2 (effectively) maintains two different tables of loaded DLL:

    Global DLLs

    those loaded by the base name from LIBPATH; including those associated at link time;

    specific DLLs

    loaded by the full name.

    When resolving a request for a global DLL, the table of already-loaded specific DLLs is (effectively) ignored; moreover, specific DLLs are always loaded from the prescribed path.

    There is/was a minor twist which makes this scheme fragile: what to do with DLLs loaded from

    BEGINLIBPATH and ENDLIBPATH

    (which depend on the process)

    . from LIBPATH

    which effectively depends on the process (although LIBPATH is the same for all the processes).

    Unless LIBPATHSTRICT is set to T (and the kernel is after 2000/09/01), such DLLs are considered to be global. When loading a global DLL it is first looked in the table of already-loaded global DLLs. Because of this the fact that one executable loaded a DLL from BEGINLIBPATH and ENDLIBPATH, or . from LIBPATH may affect which DLL is loaded when another executable requests a DLL with the same name. This is the reason for version-specific mangling of the DLL name for perl DLL.

    Since the Perl extension DLLs are always loaded with the full path, there is no need to mangle their names in a version-specific ways: their directory already reflects the corresponding version of perl, and @INC takes into account binary compatibility with older version. Starting from 5.6.2 the name mangling scheme is fixed to be the same as for Perl 5.005_53 (same as in a popular binary release). Thus new Perls will be able to resolve the names of old extension DLLs if @INC allows finding their directories.

    However, this still does not guarantee that these DLL may be loaded. The reason is the mangling of the name of the Perl DLL. And since the extension DLLs link with the Perl DLL, extension DLLs for older versions would load an older Perl DLL, and would most probably segfault (since the data in this DLL is not properly initialized).

    There is a partial workaround (which can be made complete with newer OS/2 kernels): create a forwarder DLL with the same name as the DLL of the older version of Perl, which forwards the entry points to the newer Perl's DLL. Make this DLL accessible on (say) the BEGINLIBPATH of the new Perl executable. When the new executable accesses old Perl's extension DLLs, they would request the old Perl's DLL by name, get the forwarder instead, so effectively will link with the currently running (new) Perl DLL.

    This may break in two ways:

    • Old perl executable is started when a new executable is running has loaded an extension compiled for the old executable (ouph!). In this case the old executable will get a forwarder DLL instead of the old perl DLL, so would link with the new perl DLL. While not directly fatal, it will behave the same as new executable. This beats the whole purpose of explicitly starting an old executable.

    • A new executable loads an extension compiled for the old executable when an old perl executable is running. In this case the extension will not pick up the forwarder - with fatal results.

    With support for LIBPATHSTRICT this may be circumvented - unless one of DLLs is started from . from LIBPATH (I do not know whether LIBPATHSTRICT affects this case).

    REMARK. Unless newer kernels allow . in BEGINLIBPATH (older do not), this mess cannot be completely cleaned. (It turns out that as of the beginning of 2002, . is not allowed, but .\. is - and it has the same effect.)

    REMARK. LIBPATHSTRICT, BEGINLIBPATH and ENDLIBPATH are not environment variables, although cmd.exe emulates them on SET ... lines. From Perl they may be accessed by the Cwd::extLibpath manpage and the Cwd::extLibpath_set manpage.

    DLL forwarder generation

    Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53), and the new version is 5.6.1. Create a file perl5shim.def-leader with

      LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
  DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
  CODE LOADONCALL
  DATA LOADONCALL NONSHARED MULTIPLE
  EXPORTS

    modifying the versions/names as needed. Run

     perl -wnle "next if 0../EXPORTS/; print qq(  \"$1\") if /\"(\w+)\"/" perl5.def >lst

    in the Perl build directory (to make the DLL smaller replace perl5.def with the definition file for the older version of Perl if present).

     cat perl5shim.def-leader lst >perl5shim.def
 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl

    (ignore multiple warning L4085).

    Threading

    As of release 5.003_01 perl is linked to multithreaded C RTL DLL. If perl itself is not compiled multithread-enabled, so will not be perl's malloc(). However, extensions may use multiple thread on their own risk.

    This was needed to compile Perl/Tk for XFree86-OS/2 out-of-the-box, and link with DLLs for other useful libraries, which typically are compiled with -Zmt -Zcrtdll.

    Calls to external programs

    Due to a popular demand the perl external program calling has been changed wrt Andreas Kaiser's port. If perl needs to call an external program via shell, the f:/bin/sh.exe will be called, or whatever is the override, see PERL_SH_DIR.

    Thus means that you need to get some copy of a sh.exe as well (I use one from pdksh). The path F:/bin above is set up automatically during the build to a correct value on the builder machine, but is overridable at runtime,

    Reasons: a consensus on perl5-porters was that perl should use one non-overridable shell per platform. The obvious choices for OS/2 are cmd.exe and sh.exe. Having perl build itself would be impossible with cmd.exe as a shell, thus I picked up sh.exe. This assures almost 100% compatibility with the scripts coming from *nix. As an added benefit this works as well under DOS if you use DOS-enabled port of pdksh (see Prerequisites).

    Disadvantages: currently sh.exe of pdksh calls external programs via fork()/exec(), and there is no functioning exec() on OS/2. exec() is emulated by EMX by an asynchronous call while the caller waits for child completion (to pretend that the pid did not change). This means that 1 extra copy of sh.exe is made active via fork()/exec(), which may lead to some resources taken from the system (even if we do not count extra work needed for fork()ing).

    Note that this a lesser issue now when we do not spawn sh.exe unless needed (metachars found).

    One can always start cmd.exe explicitly via

      system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...

    If you need to use cmd.exe, and do not want to hand-edit thousands of your scripts, the long-term solution proposed on p5-p is to have a directive

      use OS2::Cmd;

    which will override system(), exec(), ``, and open(,'...|'). With current perl you may override only system(), readpipe() - the explicit version of ``, and maybe exec(). The code will substitute the one-argument call to system() by CORE::system('cmd.exe', '/c', shift).

    If you have some working code for OS2::Cmd, please send it to me, I will include it into distribution. I have no need for such a module, so cannot test it.

    For the details of the current situation with calling external programs, see Starting OS/2 (and DOS) programs under Perl. Set us mention a couple of features:

    • External scripts may be called by their basename. Perl will try the same extensions as when processing -S command-line switch.

    • External scripts starting with #! or extproc will be executed directly, without calling the shell, by calling the program specified on the rest of the first line.

    Memory allocation

    Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound for speed, but perl is not, since its malloc is lightning-fast. Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker than EMX one. I do not have convincing data about memory footprint, but a (pretty random) benchmark showed that Perl's one is 5% better.

    Combination of perl's malloc() and rigid DLL name resolution creates a special problem with library functions which expect their return value to be free()d by system's free(). To facilitate extensions which need to call such functions, system memory-allocation functions are still available with the prefix emx_ added. (Currently only DLL perl has this, it should propagate to perl_.exe shortly.)

    Threads

    One can build perl with thread support enabled by providing -D usethreads option to Configure. Currently OS/2 support of threads is very preliminary.

    Most notable problems:

    COND_WAIT

    may have a race condition (but probably does not due to edge-triggered nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining waiting threads, with the linked list stored in per-thread structure?)?)

    os2.c

    has a couple of static variables used in OS/2-specific functions. (Need to be moved to per-thread structure, or serialized?)

    Note that these problems should not discourage experimenting, since they have a low probability of affecting small programs.

    BUGS

    This description is not updated often (since 5.6.1?), see ./os2/Changes (perlos2delta) for more info.

    AUTHOR

    Ilya Zakharevich, cpan@ilyaz.org

    SEE ALSO

    perl(1).


README.os390 - building and installing Perl for OS/390 and z/OS

    • Tools
    • Unpacking Perl distribution on OS/390
    • Setup and utilities for Perl on OS/390
    • Configure Perl on OS/390
    • Build, Test, Install Perl on OS/390
    • Build Anomalies with Perl on OS/390
    • Testing Anomalies with Perl on OS/390
    • Installation Anomalies with Perl on OS/390
    • Usage Hints for Perl on OS/390
    • Floating Point Anomalies with Perl on OS/390
    • Modules and Extensions for Perl on OS/390
  • AUTHORS
  • SEE ALSO
    • Mailing list for Perl on OS/390
  • HISTORY

NAME

README.os390 - building and installing Perl for OS/390 and z/OS

SYNOPSIS

This document will help you Configure, build, test and install Perl on OS/390 (aka z/OS) Unix System Services.

DESCRIPTION

This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7, 8, and 9. It may work on other versions or releases, but those are the ones we've tested it on.

You may need to carry out some system configuration tasks before running the Configure script for Perl.

Tools

The z/OS Unix Tools and Toys list may prove helpful and contains links to ports of much of the software helpful for building Perl. http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html

Unpacking Perl distribution on OS/390

If using ftp remember to transfer the distribution in binary format.

Gunzip/gzip for OS/390 is discussed at:

  http://www-1.ibm.com/servers/eserver/zseries/zos/unix/faq/bpxqp1.html

to extract an ASCII tar archive on OS/390, try this:

   pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar

or

   zcat latest.tar.Z | pax -o to=IBM-1047,from=ISO8859-1 -r

If you get lots of errors of the form

  tar: FSUM7171 ...: cannot set uid/gid: EDC5139I Operation not permitted.

you didn't read the above and tried to use tar instead of pax, you'll first have to remove the (now corrupt) perl directory

   rm -rf perl-...

and then use pax.

Setup and utilities for Perl on OS/390

Be sure that your yacc installation is in place including any necessary parser template files. If you have not already done so then be sure to:

  cp /samples/yyparse.c /etc

This may also be a good time to ensure that your /etc/protocol file and either your /etc/resolv.conf or /etc/hosts files are in place. The IBM document that described such USS system setup issues was SC28-1890-07 "OS/390 UNIX System Services Planning", in particular Chapter 6 on customizing the OE shell.

GNU make for OS/390, which is recommended for the build of perl (as well as building CPAN modules and extensions), is available from the Tools.

Some people have reported encountering "Out of memory!" errors while trying to build Perl using GNU make binaries. If you encounter such trouble then try to download the source code kit and build GNU make from source to eliminate any such trouble. You might also find GNU make (as well as Perl and Apache) in the red-piece/book "Open Source Software for OS/390 UNIX", SG24-5944-00 from IBM.

If instead of the recommended GNU make you would like to use the system supplied make program then be sure to install the default rules file properly via the shell command:

    cp /samples/startup.mk /etc

and be sure to also set the environment variable _C89_CCMODE=1 (exporting _C89_CCMODE=1 is also a good idea for users of GNU make).

You might also want to have GNU groff for OS/390 installed before running the "make install" step for Perl.

There is a syntax error in the /usr/include/sys/socket.h header file that IBM supplies with USS V2R7, V2R8, and possibly V2R9. The problem with the header file is that near the definition of the SO_REUSEPORT constant there is a spurious extra '/' character outside of a comment like so:

 #define SO_REUSEPORT    0x0200    /* allow local address & port
                                      reuse */                    /

You could edit that header yourself to remove that last '/', or you might note that Language Environment (LE) APAR PQ39997 describes the problem and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and apply them. If left unattended that syntax error will turn up as an inability for Perl to build its "Socket" extension.

For successful testing you may need to turn on the sticky bit for your world readable /tmp directory if you have not already done so (see man chmod).

Configure Perl on OS/390

Once you've unpacked the distribution, run "sh Configure" (see INSTALL for a full discussion of the Configure options). There is a "hints" file for os390 that specifies the correct values for most things. Some things to watch out for include:

  • A message of the form:

     (I see you are using the Korn shell.  Some ksh's blow up on Configure,
 mainly on older exotic systems.  If yours does, try the Bourne shell instead.)

    is nothing to worry about at all.

  • Some of the parser default template files in /samples are needed in /etc. In particular be sure that you at least copy /samples/yyparse.c to /etc before running Perl's Configure. This step ensures successful extraction of EBCDIC versions of parser files such as perly.c, perly.h, and x2p/a2p.c. This has to be done before running Configure the first time. If you failed to do so then the easiest way to re-Configure Perl is to delete your misconfigured build root and re-extract the source from the tar ball. Then you must ensure that /etc/yyparse.c is properly in place before attempting to re-run Configure.

  • This port will support dynamic loading, but it is not selected by default. If you would like to experiment with dynamic loading then be sure to specify -Dusedl in the arguments to the Configure script. See the comments in hints/os390.sh for more information on dynamic loading. If you build with dynamic loading then you will need to add the $archlibexp/CORE directory to your LIBPATH environment variable in order for perl to work. See the config.sh file for the value of $archlibexp. If in trying to use Perl you see an error message similar to:

     CEE3501S The module libperl.dll was not found.
         From entry point __dllstaticinit at compile unit offset +00000194 at

    then your LIBPATH does not have the location of libperl.x and either libperl.dll or libperl.so in it. Add that directory to your LIBPATH and proceed.

  • Do not turn on the compiler optimization flag "-O". There is a bug in either the optimizer or perl that causes perl to not work correctly when the optimizer is on.

  • Some of the configuration files in /etc used by the networking APIs are either missing or have the wrong names. In particular, make sure that there's either an /etc/resolv.conf or an /etc/hosts, so that gethostbyname() works, and make sure that the file /etc/proto has been renamed to /etc/protocol (NOT /etc/protocols, as used by other Unix systems). You may have to look for things like HOSTNAME and DOMAINORIGIN in the "//'SYS1.TCPPARMS(TCPDATA)'" PDS member in order to properly set up your /etc networking files.

Build, Test, Install Perl on OS/390

Simply put:

    sh Configure
    make
    make test

if everything looks ok (see the next section for test/IVP diagnosis) then:

    make install

this last step may or may not require UID=0 privileges depending on how you answered the questions that Configure asked and whether or not you have write access to the directories you specified.

Build Anomalies with Perl on OS/390

"Out of memory!" messages during the build of Perl are most often fixed by re building the GNU make utility for OS/390 from a source code kit.

Another memory limiting item to check is your MAXASSIZE parameter in your 'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space limits can be set on a per user ID basis in the USS segment of a RACF profile). People have reported successful builds of Perl with MAXASSIZE parameters as small as 503316480 (and it may be possible to build Perl with a MAXASSIZE smaller than that).

Within USS your /etc/profile or $HOME/.profile may limit your ulimit settings. Check that the following command returns reasonable values:

    ulimit -a

To conserve memory you should have your compiler modules loaded into the Link Pack Area (LPA/ELPA) rather than in a link list or step lib.

If the c89 compiler complains of syntax errors during the build of the Socket extension then be sure to fix the syntax error in the system header /usr/include/sys/socket.h.

Testing Anomalies with Perl on OS/390

The "make test" step runs a Perl Verification Procedure, usually before installation. You might encounter STDERR messages even during a successful run of "make test". Here is a guide to some of the more commonly seen anomalies:

  • A message of the form:

     comp/cpp.............ERROR CBC3191 ./.301989890.c:1     The character $ is not a
  valid C source character.
 FSUM3065 The COMPILE step ended with return code 12.
 FSUM3017 Could not compile .301989890.c. Correct the errors and try again.
 ok

    indicates that the t/comp/cpp.t test of Perl's -P command line switch has passed but that the particular invocation of c89 -E in the cpp script does not suppress the C compiler check of source code validity.

  • A message of the form:

     io/openpid...........CEE5210S The signal SIGHUP was received.
 CEE5210S The signal SIGHUP was received.
 CEE5210S The signal SIGHUP was received.
 ok

    indicates that the t/io/openpid.t test of Perl has passed but done so with extraneous messages on stderr from CEE.

  • A message of the form:

     lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/) is not safe
 (sticky bit not set when world writable?) at lib/ftmp-security.t line 100
 File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky bit not
 set when world writable?) at lib/ftmp-security.t line 100
 ok

    indicates a problem with the permissions on your /tmp directory within the HFS. To correct that problem issue the command:

         chmod a+t /tmp

    from an account with write access to the directory entry for /tmp.

  • Out of Memory!

    Recent perl test suite is quite memory hunrgy. In addition to the comments above on memory limitations it is also worth checking for _CEE_RUNOPTS in your environment. Perl now has (in miniperlmain.c) a C #pragma to set CEE run options, but the environment variable wins.

    The C code asks for:

     #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))

    The important parts of that are the second argument (the increment) to HEAP, and allowing the stack to be "Above the (16M) line". If the heap increment is too small then when perl (for example loading unicode/Name.pl) tries to create a "big" (400K+) string it cannot fit in a single segment and you get "Out of Memory!" - even if there is still plenty of memory available.

    A related issue is use with perl's malloc. Perl's malloc uses sbrk() to get memory, and sbrk() is limited to the first allocation so in this case something like:

      HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)

    is needed to get through the test suite.

Installation Anomalies with Perl on OS/390

The installman script will try to run on OS/390. There will be fewer errors if you have a roff utility installed. You can obtain GNU groff from the Redbook SG24-5944-00 ftp site.

Usage Hints for Perl on OS/390

When using perl on OS/390 please keep in mind that the EBCDIC and ASCII character sets are different. See perlebcdic.pod for more on such character set issues. Perl builtin functions that may behave differently under EBCDIC are also mentioned in the perlport.pod document.

Open Edition (UNIX System Services) from V2R8 onward does support #!/path/to/perl script invocation. There is a PTF available from IBM for V2R7 that will allow shell/kernel support for #!. USS releases prior to V2R7 did not support the #! means of script invocation. If you are running V2R6 or earlier then see:

    head `whence perldoc`

for an example of how to use the "eval exec" trick to ask the shell to have Perl run your scripts on those older releases of Unix System Services.

If you are having trouble with square brackets then consider switching your rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for working with Perl on USS.

Floating Point Anomalies with Perl on OS/390

There appears to be a bug in the floating point implementation on S/390 systems such that calling int() on the product of a number and a small magnitude number is not the same as calling int() on the quotient of that number and a large magnitude number. For example, in the following Perl code:

    my $x = 100000.0;
    my $y = int($x * 1e-5) * 1e5; # '0'
    my $z = int($x / 1e+5) * 1e5;  # '100000'
    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000

Although one would expect the quantities $y and $z to be the same and equal to 100000 they will differ and instead will be 0 and 100000 respectively.

The problem can be further examined in a roughly equivalent C program:

    #include <stdio.h>
    #include <math.h>
    main()
    {
    double r1,r2;
    double x = 100000.0;
    double y = 0.0;
    double z = 0.0;
    x = 100000.0 * 1e-5;
    r1 = modf (x,&y);
    x = 100000.0 / 1e+5;
    r2 = modf (x,&z);
    printf("y is %e and z is %e\n",y*1e5,z*1e5);
    /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
    }

Modules and Extensions for Perl on OS/390

Pure pure (that is non xs) modules may be installed via the usual:

    perl Makefile.PL
    make
    make test
    make install

If you built perl with dynamic loading capability then that would also be the way to build xs based extensions. However, if you built perl with the default static linking you can still build xs based extensions for OS/390 but you will need to follow the instructions in ExtUtils::MakeMaker for building statically linked perl binaries. In the simplest configurations building a static perl + xs extension boils down to:

    perl Makefile.PL
    make
    make perl
    make test
    make install
    make -f Makefile.aperl inst_perl MAP_TARGET=perl

In most cases people have reported better results with GNU make rather than the system's /bin/make program, whether for plain modules or for xs based extensions.

If the make process encounters trouble with either compilation or linking then try setting the _C89_CCMODE to 1. Assuming sh is your login shell then run:

    export _C89_CCMODE=1

If tcsh is your login shell then use the setenv command.

AUTHORS

David Fiander and Peter Prymmer with thanks to Dennis Longnecker and William Raffloer for valuable reports, LPAR and PTF feedback. Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00. Thanks to Ignasi Roca for pointing out the floating point problems. Thanks to John Goodyear for dynamic loading help.

SEE ALSO

INSTALL, the perlport manpage, the perlebcdic manpage, the ExtUtils::MakeMaker manpage.

    http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html
    http://www.redbooks.ibm.com/abstracts/sg245944.html
    http://www-1.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc
    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
    http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/ceea3030/
    http://publibz.boulder.ibm.com:80/cgi-bin/bookmgr_OS390/BOOKS/CBCUG030/

Mailing list for Perl on OS/390

If you are interested in the VM/ESA, z/OS (formerly known as OS/390) and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list. To subscribe, send an empty message to perl-mvs-subscribe@perl.org.

See also:

    http://lists.perl.org/showlist.cgi?name=perl-mvs

There are web archives of the mailing list at:

    http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
    http://archive.develooper.com/perl-mvs@perl.org/

HISTORY

This document was originally written by David Fiander for the 5.005 release of Perl.

This document was podified for the 5.005_03 release of Perl 11 March 1999.

Updated 28 November 2001 for broken URLs.

Updated 12 November 2000 for the 5.7.1 release of Perl.

Updated 15 January 2001 for the 5.7.1 release of Perl.

Updated 24 January 2001 to mention dynamic loading.

Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.


README.os400 - Perl version 5 on OS/400

    • Compiling Perl for OS/400 PASE
    • Installing Perl in OS/400 PASE
    • Using Perl in OS/400 PASE
    • Known Problems
    • Perl on ILE
  • AUTHORS

NAME

README.os400 - Perl version 5 on OS/400

DESCRIPTION

This document describes various features of IBM's OS/400 operating system that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs.

By far the easiest way to build Perl for OS/400 is to use the PASE (Portable Application Solutions Environment), for more information see http://www.iseries.ibm.com/developer/factory/pase/index.html This environment allows one to use AIX APIs while programming, and it provides a runtime that allows AIX binaries to execute directly on the PowerPC iSeries.

Compiling Perl for OS/400 PASE

The recommended way to build Perl for the OS/400 PASE is to build the Perl 5 source code (release 5.8.1 or later) under AIX.

The trick is to give a special parameter to the Configure shell script when running it on AIX:

  sh Configure -DPASE ...

The default installation directory of Perl under PASE is /QOpenSys/perl. This can be modified if needed with Configure parameter -Dprefix=/some/dir.

Starting from OS/400 V5R2 the IBM Visual Age compiler is supported on OS/400 PASE, so it is possible to build Perl natively on OS/400. The easier way, however, is to compile in AIX, as just described.

If you don't want to install the compiled Perl in AIX into /QOpenSys (for packaging it before copying it to PASE), you can use a Configure parameter: -Dinstallprefix=/tmp/QOpenSys/perl. This will cause the "make install" to install everything into that directory, while the installed files still think they are (will be) in /QOpenSys/perl.

If building natively on PASE, please do the build under the /QOpenSys directory, since Perl is happier when built on a case sensitive filesystem.

Installing Perl in OS/400 PASE

If you are compiling on AIX, simply do a "make install" on the AIX box. Once the install finishes, tar up the /QOpenSys/perl directory. Transfer the tarball to the OS/400 using FTP with the following commands:

  > binary
  > site namefmt 1
  > put perl.tar /QOpenSys

Once you have it on, simply bring up a PASE shell and extract the tarball.

If you are compiling in PASE, then "make install" is the only thing you will need to do.

The default path for perl binary is /QOpenSys/perl/bin/perl. You'll want to symlink /QOpenSys/usr/bin/perl to this file so you don't have to modify your path.

Using Perl in OS/400 PASE

Perl in PASE may be used in the same manner as you would use Perl on AIX.

Scripts starting with #!/usr/bin/perl should work if you have /QOpenSys/usr/bin/perl symlinked to your perl binary. This will not work if you've done a setuid/setgid or have environment variable PASE_EXEC_QOPENSYS="N". If you have V5R1, you'll need to get the latest PTFs to have this feature. Scripts starting with #!/QOpenSys/perl/bin/perl should always work.

Known Problems

When compiling in PASE, there is no "oslevel" command. Therefore, you may want to create a script called "oslevel" that echoes the level of AIX that your version of PASE runtime supports. If you're unsure, consult your documentation or use "4.3.3.0".

If you have test cases that fail, check for the existence of spool files. The test case may be trying to use a syscall that is not implemented in PASE. To avoid the SIGILL, try setting the PASE_SYSCALL_NOSIGILL environment variable or have a handler for the SIGILL. If you can compile programs for PASE, run the config script and edit config.sh when it gives you the option. If you want to remove fchdir(), which isn't implement in V5R1, simply change the line that says:

d_fchdir='define'

to

d_fchdir='undef'

and then compile Perl. The places where fchdir() is used have alternatives for systems that do not have fchdir() available.

Perl on ILE

There exists a port of Perl to the ILE environment. This port, however, is based quite an old release of Perl, Perl 5.00502 (August 1998). (As of July 2002 the latest release of Perl is 5.8.0, and even 5.6.1 has been out since April 2001.) If you need to run Perl on ILE, though, you may need this older port: http://www.cpan.org/ports/#os400 Note that any Perl release later than 5.00502 has not been ported to ILE.

If you need to use Perl in the ILE environment, you may want to consider using Qp2RunPase() to call the PASE version of Perl.

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi> Bryan Logan <bryanlog@us.ibm.com> David Larson <larson1@us.ibm.com>


perlplan9 - Plan 9-specific documentation for Perl

    • Invoking Perl
    • What's in Plan 9 Perl
    • What's not in Plan 9 Perl
    • Perl5 Functions not currently supported in Plan 9 Perl
    • Signals in Plan 9 Perl
  • COMPILING AND INSTALLING PERL ON PLAN 9
    • Installing Perl Documentation on Plan 9
  • BUGS
  • Revision date
  • AUTHOR

NAME

perlplan9 - Plan 9-specific documentation for Perl

DESCRIPTION

These are a few notes describing features peculiar to Plan 9 Perl. As such, it is not intended to be a replacement for the rest of the Perl 5 documentation (which is both copious and excellent). If you have any questions to which you can't find answers in these man pages, contact Luther Huffman at lutherh@stratcom.com and we'll try to answer them.

Invoking Perl

Perl is invoked from the command line as described in the perl manpage. Most perl scripts, however, do have a first line such as "#!/usr/local/bin/perl". This is known as a shebang (shell-bang) statement and tells the OS shell where to find the perl interpreter. In Plan 9 Perl this statement should be "#!/bin/perl" if you wish to be able to directly invoke the script by its name. Alternatively, you may invoke perl with the command "Perl" instead of "perl". This will produce Acme-friendly error messages of the form "filename:18".

Some scripts, usually identified with a *.PL extension, are self-configuring and are able to correctly create their own shebang path from config information located in Plan 9 Perl. These you won't need to be worried about.

What's in Plan 9 Perl

Although Plan 9 Perl currently only provides static loading, it is built with a number of useful extensions. These include Opcode, FileHandle, Fcntl, and POSIX. Expect to see others (and DynaLoading!) in the future.

What's not in Plan 9 Perl

As mentioned previously, dynamic loading isn't currently available nor is MakeMaker. Both are high-priority items.

Perl5 Functions not currently supported in Plan 9 Perl

Some, such as chown and umask aren't provided because the concept does not exist within Plan 9. Others, such as some of the socket-related functions, simply haven't been written yet. Many in the latter category may be supported in the future.

The functions not currently implemented include:

    chown, chroot, dbmclose, dbmopen, getsockopt,
    setsockopt, recvmsg, sendmsg, getnetbyname,
    getnetbyaddr, getnetent, getprotoent, getservent,
    sethostent, setnetent, setprotoent, setservent,
    endservent, endnetent, endprotoent, umask

There may be several other functions that have undefined behavior so this list shouldn't be considered complete.

Signals in Plan 9 Perl

For compatibility with perl scripts written for the Unix environment, Plan 9 Perl uses the POSIX signal emulation provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking isn't supported. The signals provided are:

    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
    SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM,
    SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
    SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU

COMPILING AND INSTALLING PERL ON PLAN 9

WELCOME to Plan 9 Perl, brave soul!

   This is a preliminary alpha version of Plan 9 Perl. Still to be
implemented are MakeMaker and DynaLoader. Many perl commands are
missing or currently behave in an inscrutable manner. These gaps will,
with perseverance and a modicum of luck, be remedied in the near
future.To install this software:

1. Create the source directories and libraries for perl by running the plan9/setup.rc command (i.e., located in the plan9 subdirectory). Note: the setup routine assumes that you haven't dearchived these files into /sys/src/cmd/perl. After running setup.rc you may delete the copy of the source you originally detarred, as source code has now been installed in /sys/src/cmd/perl. If you plan on installing perl binaries for all architectures, run "setup.rc -a".

2. After making sure that you have adequate privileges to build system software, from /sys/src/cmd/perl/5.00301 (adjust version appropriately) run:

        mk install

If you wish to install perl versions for all architectures (68020, mips, sparc and 386) run:

        mk installall

3. Wait. The build process will take a *long* time because perl bootstraps itself. A 75MHz Pentium, 16MB RAM machine takes roughly 30 minutes to build the distribution from scratch.

Installing Perl Documentation on Plan 9

This perl distribution comes with a tremendous amount of documentation. To add these to the built-in manuals that come with Plan 9, from /sys/src/cmd/perl/5.00301 (adjust version appropriately) run:

        mk man

To begin your reading, start with:

        man perl

This is a good introduction and will direct you towards other man pages that may interest you.

(Note: "mk man" may produce some extraneous noise. Fear not.)

BUGS

"As many as there are grains of sand on all the beaches of the world . . ." - Carl Sagan

Revision date

This document was revised 09-October-1996 for Perl 5.003_7.

AUTHOR

Direct questions, comments, and the unlikely bug report (ahem) direct comments toward:

Luther Huffman, lutherh@stratcom.com, Strategic Computer Solutions, Inc.


README.qnx - Perl version 5 on QNX

    • Required Software for Compiling Perl on QNX4
    • Outstanding Issues with Perl on QNX4
    • QNX auxiliary files
    • Outstanding issues with perl under QNX6
  • AUTHOR

NAME

README.qnx - Perl version 5 on QNX

DESCRIPTION

As of perl5.7.2 all tests pass under:

  QNX 4.24G
  Watcom 10.6 with Beta/970211.wcc.update.tar.F
  socket3r.lib Nov21 1996.

As of perl5.8.1 there is at least one test still failing.

Some tests may complain under known circumstances.

See below and hints/qnx.sh for more information.

Under QNX 6.2.0 there are still a few tests which fail. See below and hints/qnx.sh for more information.

Required Software for Compiling Perl on QNX4

As with many unix ports, this one depends on a few "standard" unix utilities which are not necessarily standard for QNX4.

/bin/sh

This is used heavily by Configure and then by perl itself. QNX4's version is fine, but Configure will choke on the 16-bit version, so if you are running QNX 4.22, link /bin/sh to /bin32/ksh

ar

This is the standard unix library builder. We use wlib. With Watcom 10.6, when wlib is linked as "ar", it behaves like ar and all is fine. Under 9.5, a cover is required. One is included in ../qnx

nm

This is used (optionally) by configure to list the contents of libraries. I will generate a cover function on the fly in the UU directory.

cpp

Configure and perl need a way to invoke a C preprocessor. I have created a simple cover for cc which does the right thing. Without this, Configure will create its own wrapper which works, but it doesn't handle some of the command line arguments that perl will throw at it.

make

You really need GNU make to compile this. GNU make ships by default with QNX 4.23, but you can get it from quics for earlier versions.

Outstanding Issues with Perl on QNX4

There is no support for dynamically linked libraries in QNX4.

If you wish to compile with the Socket extension, you need to have the TCP/IP toolkit, and you need to make sure that -lsocket locates the correct copy of socket3r.lib. Beware that the Watcom compiler ships with a stub version of socket3r.lib which has very little functionality. Also beware the order in which wlink searches directories for libraries. You may have /usr/lib/socket3r.lib pointing to the correct library, but wlink may pick up /usr/watcom/10.6/usr/lib/socket3r.lib instead. Make sure they both point to the correct library, that is, /usr/tcptk/current/usr/lib/socket3r.lib.

The following tests may report errors under QNX4:

ext/Cwd/Cwd.t will complain if `pwd` and cwd don't give the same results. cwd calls `fullpath -t`, so if you cd `fullpath -t` before running the test, it will pass.

lib/File/Find/taint.t will complain if '.' is in your PATH. The PATH test is triggered because cwd calls `fullpath -t`.

ext/IO/lib/IO/t/io_sock.t: Subtests 14 and 22 are skipped due to the fact that the functionality to read back the non-blocking status of a socket is not implemented in QNX's TCP/IP. This has been reported to QNX and it may work with later versions of TCP/IP.

t/io/tell.t: Subtest 27 is failing. We are still investigating.

QNX auxiliary files

The files in the "qnx" directory are:

qnx/ar

A script that emulates the standard unix archive (aka library) utility. Under Watcom 10.6, ar is linked to wlib and provides the expected interface. With Watcom 9.5, a cover function is required. This one is fairly crude but has proved adequate for compiling perl.

qnx/cpp

A script that provides C preprocessing functionality. Configure can generate a similar cover, but it doesn't handle all the command-line options that perl throws at it. This might be reasonably placed in /usr/local/bin.

Outstanding issues with perl under QNX6

The following tests are still failing for Perl 5.8.1 under QNX 6.2.0:

  op/sprintf.........................FAILED at test 91
  lib/Benchmark......................FAILED at test 26

This is due to a bug in the C library's printf routine. printf("'%e'", 0. ) produces '0.000000e+0', but ANSI requires '0.000000e+00'. QNX has acknowledged the bug.

AUTHOR

Norton T. Allen (allen@huarp.harvard.edu)


README.solaris - Perl version 5 on Solaris systems

    • Solaris Version Numbers.
  • RESOURCES
  • SETTING UP
    • File Extraction Problems on Solaris.
    • Compiler and Related Tools on Solaris.
      • Include /usr/ccs/bin/ in your PATH.
      • Avoid /usr/ucb/cc.
      • Sun's C Compiler
      • GCC
      • GNU as and GNU ld
      • Sun and GNU make
      • Avoid libucb.
    • Environment for Compiling perl on Solaris
      • PATH
      • LD_LIBRARY_PATH
  • RUN CONFIGURE.
    • 64-bit perl on Solaris.
      • General 32-bit vs. 64-bit issues.
      • Large File Support
      • Building an LP64 perl
      • Long Doubles.
    • Threads in perl on Solaris.
    • Malloc Issues with perl on Solaris.
  • MAKE PROBLEMS.
  • MAKE TEST
    • op/stat.t test 4 in Solaris
    • nss_delete core dump from op/pwent or op/grent
  • PREBUILT BINARIES OF PERL FOR SOLARIS.
  • RUNTIME ISSUES FOR PERL ON SOLARIS.
    • Limits on Numbers of Open Files on Solaris.
  • SOLARIS-SPECIFIC MODULES.
  • SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
    • Proc::ProcessTable on Solaris
    • BSD::Resource on Solaris
    • Net::SSLeay on Solaris
  • SunOS 4.x
  • AUTHOR

NAME

README.solaris - Perl version 5 on Solaris systems

DESCRIPTION

This document describes various features of Sun's Solaris operating system that will affect how Perl version 5 (hereafter just perl) is compiled and/or runs. Some issues relating to the older SunOS 4.x are also discussed, though they may be out of date.

For the most part, everything should just work.

Starting with Solaris 8, perl5.00503 (or higher) is supplied with the operating system, so you might not even need to build a newer version of perl at all. The Sun-supplied version is installed in /usr/perl5 with /usr/bin/perl pointing to /usr/perl5/bin/perl. Do not disturb that installation unless you really know what you are doing. If you remove the perl supplied with the OS, you will render some bits of your system inoperable. If you wish to install a newer version of perl, install it under a different prefix from /usr/perl5. Common prefixes to use are /usr/local and /opt/perl.

You may wish to put your version of perl in the PATH of all users by changing the link /usr/bin/perl. This is probably OK, as most perl scripts shipped with Solaris use an explicit path. (There are a few exceptions, such as /usr/bin/rpm2cpio and /etc/rcm/scripts/README, but these are also sufficiently generic that the actual version of perl probably doesn't matter too much.)

Solaris ships with a range of Solaris-specific modules. If you choose to install your own version of perl you will find the source of many of these modules is available on CPAN under the Sun::Solaris:: namespace.

Solaris may include two versions of perl, e.g. Solaris 9 includes both 5.005_03 and 5.6.1. This is to provide stability across Solaris releases, in cases where a later perl version has incompatibilities with the version included in the preceeding Solaris release. The default perl version will always be the most recent, and in general the old version will only be retained for one Solaris release. Note also that the default perl will NOT be configured to search for modules in the older version, again due to compatibility/stability concerns. As a consequence if you upgrade Solaris, you will have to rebuild/reinstall any additional CPAN modules that you installed for the previous Solaris version. See the CPAN manpage under 'autobundle' for a quick way of doing this.

As an interim measure, you may either change the #! line of your scripts to specifically refer to the old perl version, e.g. on Solaris 9 use #!/usr/perl5/5.00503/bin/perl to use the perl version that was the default for Solaris 8, or if you have a large number of scripts it may be more convenient to make the old version of perl the default on your system. You can do this by changing the appropriate symlinks under /usr/perl5 as follows (example for Solaris 9):

 # cd /usr/perl5
 # rm bin man pod
 # ln -s ./5.00503/bin
 # ln -s ./5.00503/man
 # ln -s ./5.00503/lib/pod
 # rm /usr/bin/perl
 # ln -s ../perl5/5.00503/bin/perl /usr/bin/perl

In both cases this should only be considered to be a temporary measure - you should upgrade to the later version of perl as soon as is practicable.

Note also that the perl command-line utilities (e.g. perldoc) and any that are added by modules that you install will be under /usr/perl5/bin, so that directory should be added to your PATH.

Solaris Version Numbers.

For consistency with common usage, perl's Configure script performs some minor manipulations on the operating system name and version number as reported by uname. Here's a partial translation table:

          Sun:                      perl's Configure:
 uname    uname -r   Name           osname     osvers
 SunOS    4.1.3     Solaris 1.1     sunos      4.1.3
 SunOS    5.6       Solaris 2.6     solaris    2.6
 SunOS    5.8       Solaris 8       solaris    2.8
 SunOS    5.9       Solaris 9       solaris    2.9
 SunOS    5.10      Solaris 10      solaris    2.10

The complete table can be found in the Sun Managers' FAQ ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq under "9.1) Which Sun models run which versions of SunOS?".

RESOURCES

There are many, many sources for Solaris information. A few of the important ones for perl:

Solaris FAQ

The Solaris FAQ is available at http://www.science.uva.nl/pub/solaris/solaris2.html.

The Sun Managers' FAQ is available at ftp://ftp.cs.toronto.edu/pub/jdd/sunmanagers/faq

Precompiled Binaries

Precompiled binaries, links to many sites, and much, much more are available at http://www.sunfreeware.com/ and http://www.blastwave.org/.

Solaris Documentation

All Solaris documentation is available on-line at http://docs.sun.com/.

SETTING UP

File Extraction Problems on Solaris.

Be sure to use a tar program compiled under Solaris (not SunOS 4.x) to extract the perl-5.x.x.tar.gz file. Do not use GNU tar compiled for SunOS4 on Solaris. (GNU tar compiled for Solaris should be fine.) When you run SunOS4 binaries on Solaris, the run-time system magically alters pathnames matching m#lib/locale# so that when tar tries to create lib/locale.pm, a file named lib/oldlocale.pm gets created instead. If you found this advice too late and used a SunOS4-compiled tar anyway, you must find the incorrectly renamed file and move it back to lib/locale.pm.

Compiler and Related Tools on Solaris.

You must use an ANSI C compiler to build perl. Perl can be compiled with either Sun's add-on C compiler or with gcc. The C compiler that shipped with SunOS4 will not do.

Include /usr/ccs/bin/ in your PATH.

Several tools needed to build perl are located in /usr/ccs/bin/: ar, as, ld, and make. Make sure that /usr/ccs/bin/ is in your PATH.

You need to make sure the following packages are installed (this info is extracted from the Solaris FAQ):

for tools (sccs, lex, yacc, make, nm, truss, ld, as): SUNWbtool, SUNWsprot, SUNWtoo

for libraries & headers: SUNWhea, SUNWarc, SUNWlibm, SUNWlibms, SUNWdfbh, SUNWcg6h, SUNWxwinc, SUNWolinc

for 64 bit development: SUNWarcx, SUNWbtoox, SUNWdplx, SUNWscpux, SUNWsprox, SUNWtoox, SUNWlmsx, SUNWlmx, SUNWlibCx

If you are in doubt which package contains a file you are missing, try to find an installation that has that file. Then do a

 $ grep /my/missing/file /var/sadm/install/contents

This will display a line like this:

/usr/include/sys/errno.h f none 0644 root bin 7471 37605 956241356 SUNWhea

The last item listed (SUNWhea in this example) is the package you need.

Avoid /usr/ucb/cc.

You don't need to have /usr/ucb/ in your PATH to build perl. If you want /usr/ucb/ in your PATH anyway, make sure that /usr/ucb/ is NOT in your PATH before the directory containing the right C compiler.

Sun's C Compiler

If you use Sun's C compiler, make sure the correct directory (usually /opt/SUNWspro/bin/) is in your PATH (before /usr/ucb/).

GCC

If you use gcc, make sure your installation is recent and complete. perl versions since 5.6.0 build fine with gcc > 2.8.1 on Solaris >= 2.6.

You must Configure perl with

 $ sh Configure -Dcc=gcc

If you don't, you may experience strange build errors.

If you have updated your Solaris version, you may also have to update your gcc. For example, if you are running Solaris 2.6 and your gcc is installed under /usr/local, check in /usr/local/lib/gcc-lib and make sure you have the appropriate directory, sparc-sun-solaris2.6/ or i386-pc-solaris2.6/. If gcc's directory is for a different version of Solaris than you are running, then you will need to rebuild gcc for your new version of Solaris.

You can get a precompiled version of gcc from http://www.sunfreeware.com/ or http://www.blastwave.org/. Make sure you pick up the package for your Solaris release.

If you wish to use gcc to build add-on modules for use with the perl shipped with Solaris, you should use the Solaris::PerlGcc module which is available from CPAN. The perl shipped with Solaris is configured and built with the Sun compilers, and the compiler configuration information stored in Config.pm is therefore only relevant to the Sun compilers. The Solaris:PerlGcc module contains a replacement Config.pm that is correct for gcc - see the module for details.

GNU as and GNU ld

The following information applies to gcc version 2. Volunteers to update it as appropropriate for gcc version 3 would be appreciated.

The versions of as and ld supplied with Solaris work fine for building perl. There is normally no need to install the GNU versions to compile perl.

If you decide to ignore this advice and use the GNU versions anyway, then be sure that they are relatively recent. Versions newer than 2.7 are apparently new enough. Older versions may have trouble with dynamic loading.

If you wish to use GNU ld, then you need to pass it the -Wl,-E flag. The hints/solaris_2.sh file tries to do this automatically by setting the following Configure variables:

 ccdlflags="$ccdlflags -Wl,-E"
 lddlflags="$lddlflags -Wl,-E -G"

However, over the years, changes in gcc, GNU ld, and Solaris ld have made it difficult to automatically detect which ld ultimately gets called. You may have to manually edit config.sh and add the -Wl,-E flags yourself, or else run Configure interactively and add the flags at the appropriate prompts.

If your gcc is configured to use GNU as and ld but you want to use the Solaris ones instead to build perl, then you'll need to add -B/usr/ccs/bin/ to the gcc command line. One convenient way to do that is with

 $ sh Configure -Dcc='gcc -B/usr/ccs/bin/'

Note that the trailing slash is required. This will result in some harmless warnings as Configure is run:

 gcc: file path prefix `/usr/ccs/bin/' never used

These messages may safely be ignored. (Note that for a SunOS4 system, you must use -B/bin/ instead.)

Alternatively, you can use the GCC_EXEC_PREFIX environment variable to ensure that Sun's as and ld are used. Consult your gcc documentation for further information on the -B option and the GCC_EXEC_PREFIX variable.

Sun and GNU make

The make under /usr/ccs/bin works fine for building perl. If you have the Sun C compilers, you will also have a parallel version of make (dmake). This works fine to build perl, but can sometimes cause problems when running 'make test' due to underspecified dependencies between the different test harness files. The same problem can also affect the building of some add-on modules, so in those cases either specify '-m serial' on the dmake command line, or use /usr/ccs/bin/make instead. If you wish to use GNU make, be sure that the set-group-id bit is not set. If it is, then arrange your PATH so that /usr/ccs/bin/make is before GNU make or else have the system administrator disable the set-group-id bit on GNU make.

Avoid libucb.

Solaris provides some BSD-compatibility functions in /usr/ucblib/libucb.a. Perl will not build and run correctly if linked against -lucb since it contains routines that are incompatible with the standard Solaris libc. Normally this is not a problem since the solaris hints file prevents Configure from even looking in /usr/ucblib for libraries, and also explicitly omits -lucb.

Environment for Compiling perl on Solaris

PATH

Make sure your PATH includes the compiler (/opt/SUNWspro/bin/ if you're using Sun's compiler) as well as /usr/ccs/bin/ to pick up the other development tools (such as make, ar, as, and ld). Make sure your path either doesn't include /usr/ucb or that it includes it after the compiler and compiler tools and other standard Solaris directories. You definitely don't want /usr/ucb/cc.

LD_LIBRARY_PATH

If you have the LD_LIBRARY_PATH environment variable set, be sure that it does NOT include /lib or /usr/lib. If you will be building extensions that call third-party shared libraries (e.g. Berkeley DB) then make sure that your LD_LIBRARY_PATH environment variable includes the directory with that library (e.g. /usr/local/lib).

If you get an error message

 dlopen: stub interception failed

it is probably because your LD_LIBRARY_PATH environment variable includes a directory which is a symlink to /usr/lib (such as /lib). The reason this causes a problem is quite subtle. The file libdl.so.1.0 actually *only* contains functions which generate 'stub interception failed' errors! The runtime linker intercepts links to "/usr/lib/libdl.so.1.0" and links in internal implementations of those functions instead. [Thanks to Tim Bunce for this explanation.]

RUN CONFIGURE.

See the INSTALL file for general information regarding Configure. Only Solaris-specific issues are discussed here. Usually, the defaults should be fine.

64-bit perl on Solaris.

See the INSTALL file for general information regarding 64-bit compiles. In general, the defaults should be fine for most people.

By default, perl-5.6.0 (or later) is compiled as a 32-bit application with largefile and long-long support.

General 32-bit vs. 64-bit issues.

Solaris 7 and above will run in either 32 bit or 64 bit mode on SPARC CPUs, via a reboot. You can build 64 bit apps whilst running 32 bit mode and vice-versa. 32 bit apps will run under Solaris running in either 32 or 64 bit mode. 64 bit apps require Solaris to be running 64 bit mode.

Existing 32 bit apps are properly known as LP32, i.e. Longs and Pointers are 32 bit. 64-bit apps are more properly known as LP64. The discriminating feature of a LP64 bit app is its ability to utilise a 64-bit address space. It is perfectly possible to have a LP32 bit app that supports both 64-bit integers (long long) and largefiles (> 2GB), and this is the default for perl-5.6.0.

For a more complete explanation of 64-bit issues, see the "Solaris 64-bit Developer's Guide" at http://docs.sun.com/

You can detect the OS mode using "isainfo -v", e.g.

 $ isainfo -v   # Ultra 30 in 64 bit mode
 64-bit sparcv9 applications
 32-bit sparc applications

By default, perl will be compiled as a 32-bit application. Unless you want to allocate more than ~ 4GB of memory inside perl, or unless you need more than 255 open file descriptors, you probably don't need perl to be a 64-bit app.

Large File Support

For Solaris 2.6 and onwards, there are two different ways for 32-bit applications to manipulate large files (files whose size is > 2GByte). (A 64-bit application automatically has largefile support built in by default.)

First is the "transitional compilation environment", described in lfcompile64(5). According to the man page,

 The transitional compilation  environment  exports  all  the
 explicit 64-bit functions (xxx64()) and types in addition to
 all the regular functions (xxx()) and types. Both xxx()  and
 xxx64()  functions  are  available to the program source.  A
 32-bit application must use the xxx64() functions in  order
 to  access  large  files.  See the lf64(5) manual page for a
 complete listing of the 64-bit transitional interfaces.

The transitional compilation environment is obtained with the following compiler and linker flags:

 getconf LFS64_CFLAGS        -D_LARGEFILE64_SOURCE
 getconf LFS64_LDFLAG        # nothing special needed
 getconf LFS64_LIBS          # nothing special needed

Second is the "large file compilation environment", described in lfcompile(5). According to the man page,

 Each interface named xxx() that needs to access 64-bit entities
 to  access  large  files maps to a xxx64() call in the
 resulting binary. All relevant data types are defined to  be
 of correct size (for example, off_t has a typedef definition
 for a 64-bit entity).
 An application compiled in this environment is able  to  use
 the  xxx()  source interfaces to access both large and small
 files, rather than having to explicitly utilize the  transitional
 xxx64()  interface  calls to access large files.

Two exceptions are fseek() and ftell(). 32-bit applications should use fseeko(3C) and ftello(3C). These will get automatically mapped to fseeko64() and ftello64().

The large file compilation environment is obtained with

 getconf LFS_CFLAGS      -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
 getconf LFS_LDFLAGS     # nothing special needed
 getconf LFS_LIBS        # nothing special needed

By default, perl uses the large file compilation environment and relies on Solaris to do the underlying mapping of interfaces.

Building an LP64 perl

To compile a 64-bit application on an UltraSparc with a recent Sun Compiler, you need to use the flag "-xarch=v9". getconf(1) will tell you this, e.g.

 $ getconf -a | grep v9
 XBS5_LP64_OFF64_CFLAGS:         -xarch=v9
 XBS5_LP64_OFF64_LDFLAGS:        -xarch=v9
 XBS5_LP64_OFF64_LINTFLAGS:      -xarch=v9
 XBS5_LPBIG_OFFBIG_CFLAGS:       -xarch=v9
 XBS5_LPBIG_OFFBIG_LDFLAGS:      -xarch=v9
 XBS5_LPBIG_OFFBIG_LINTFLAGS:    -xarch=v9
 _XBS5_LP64_OFF64_CFLAGS:        -xarch=v9
 _XBS5_LP64_OFF64_LDFLAGS:       -xarch=v9
 _XBS5_LP64_OFF64_LINTFLAGS:     -xarch=v9
 _XBS5_LPBIG_OFFBIG_CFLAGS:      -xarch=v9
 _XBS5_LPBIG_OFFBIG_LDFLAGS:     -xarch=v9
 _XBS5_LPBIG_OFFBIG_LINTFLAGS:   -xarch=v9

This flag is supported in Sun WorkShop Compilers 5.0 and onwards (now marketed under the name Forte) when used on Solaris 7 or later on UltraSparc systems.

If you are using gcc, you would need to use -mcpu=v9 -m64 instead. This option is not yet supported as of gcc 2.95.2; from install/SPECIFIC in that release:

 GCC version 2.95 is not able to compile code correctly for sparc64
 targets. Users of the Linux kernel, at least, can use the sparc32
 program to start up a new shell invocation with an environment that
 causes configure to recognize (via uname -a) the system as sparc-*-*
 instead.

All this should be handled automatically by the hints file, if requested.

Long Doubles.

As of 5.8.1, long doubles are working if you use the Sun compilers (needed for additional math routines not included in libm).

Threads in perl on Solaris.

It is possible to build a threaded version of perl on Solaris. The entire perl thread implementation is still experimental, however, so beware.

Malloc Issues with perl on Solaris.

Starting from perl 5.7.1 perl uses the Solaris malloc, since the perl malloc breaks when dealing with more than 2GB of memory, and the Solaris malloc also seems to be faster.

If you for some reason (such as binary backward compatibility) really need to use perl's malloc, you can rebuild perl from the sources and Configure the build with

 $ sh Configure -Dusemymalloc

You should not use perl's malloc if you are building with gcc. There are reports of core dumps, especially in the PDL module. The problem appears to go away under -DDEBUGGING, so it has been difficult to track down. Sun's compiler appears to be okay with or without perl's malloc. [XXX further investigation is needed here.]

MAKE PROBLEMS.

Dynamic Loading Problems With GNU as and GNU ld

If you have problems with dynamic loading using gcc on SunOS or Solaris, and you are using GNU as and GNU ld, see the section GNU as and GNU ld above.

ld.so.1: ./perl: fatal: relocation error:

If you get this message on SunOS or Solaris, and you're using gcc, it's probably the GNU as or GNU ld problem in the previous item GNU as and GNU ld.

dlopen: stub interception failed

The primary cause of the 'dlopen: stub interception failed' message is that the LD_LIBRARY_PATH environment variable includes a directory which is a symlink to /usr/lib (such as /lib). See LD_LIBRARY_PATH above.

#error "No DATAMODEL_NATIVE specified"

This is a common error when trying to build perl on Solaris 2.6 with a gcc installation from Solaris 2.5 or 2.5.1. The Solaris header files changed, so you need to update your gcc installation. You can either rerun the fixincludes script from gcc or take the opportunity to update your gcc installation.

sh: ar: not found

This is a message from your shell telling you that the command 'ar' was not found. You need to check your PATH environment variable to make sure that it includes the directory with the 'ar' command. This is a common problem on Solaris, where 'ar' is in the /usr/ccs/bin/ directory.

MAKE TEST

op/stat.t test 4 in Solaris

op/stat.t test 4 may fail if you are on a tmpfs of some sort. Building in /tmp sometimes shows this behavior. The test suite detects if you are building in /tmp, but it may not be able to catch all tmpfs situations.

nss_delete core dump from op/pwent or op/grent

See nss_delete core dump from op/pwent or op/grent in the perlhpux manpage.

PREBUILT BINARIES OF PERL FOR SOLARIS.

You can pick up prebuilt binaries for Solaris from http://www.sunfreeware.com/, http://www.blastwave.org, ActiveState http://www.activestate.com/, and http://www.perl.com/ under the Binaries list at the top of the page. There are probably other sources as well. Please note that these sites are under the control of their respective owners, not the perl developers.

RUNTIME ISSUES FOR PERL ON SOLARIS.

Limits on Numbers of Open Files on Solaris.

The stdio(3C) manpage notes that for LP32 applications, only 255 files may be opened using fopen(), and only file descriptors 0 through 255 can be used in a stream. Since perl calls open() and then fdopen(3C) with the resulting file descriptor, perl is limited to 255 simultaneous open files, even if sysopen() is used. If this proves to be an insurmountable problem, you can compile perl as a LP64 application, see Building an LP64 perl for details. Note also that the default resource limit for open file descriptors on Solaris is 255, so you will have to modify your ulimit or rctl (Solaris 9 onwards) appropriately.

SOLARIS-SPECIFIC MODULES.

See the modules under the Solaris:: and Sun::Solaris namespaces on CPAN, see http://www.cpan.org/modules/by-module/Solaris/ and http://www.cpan.org/modules/by-module/Sun/.

SOLARIS-SPECIFIC PROBLEMS WITH MODULES.

Proc::ProcessTable on Solaris

Proc::ProcessTable does not compile on Solaris with perl5.6.0 and higher if you have LARGEFILES defined. Since largefile support is the default in 5.6.0 and later, you have to take special steps to use this module.

The problem is that various structures visible via procfs use off_t, and if you compile with largefile support these change from 32 bits to 64 bits. Thus what you get back from procfs doesn't match up with the structures in perl, resulting in garbage. See proc(4) for further discussion.

A fix for Proc::ProcessTable is to edit Makefile to explicitly remove the largefile flags from the ones MakeMaker picks up from Config.pm. This will result in Proc::ProcessTable being built under the correct environment. Everything should then be OK as long as Proc::ProcessTable doesn't try to share off_t's with the rest of perl, or if it does they should be explicitly specified as off64_t.

BSD::Resource on Solaris

BSD::Resource versions earlier than 1.09 do not compile on Solaris with perl 5.6.0 and higher, for the same reasons as Proc::ProcessTable. BSD::Resource versions starting from 1.09 have a workaround for the problem.

Net::SSLeay on Solaris

Net::SSLeay requires a /dev/urandom to be present. This device is available from Solaris 9 onwards. For earlier Solaris versions you can either get the package SUNWski (packaged with several Sun software products, for example the Sun WebServer, which is part of the Solaris Server Intranet Extension, or the Sun Directory Services, part of Solaris for ISPs) or download the ANDIrand package from http://www.cosy.sbg.ac.at/~andi/. If you use SUNWski, make a symbolic link /dev/urandom pointing to /dev/random. For more details, see Document ID27606 entitled "Differing /dev/random support requirements within Solaris[TM] Operating Environments", available at http://sunsolve.sun.com .

It may be possible to use the Entropy Gathering Daemon (written in Perl!), available from http://www.lothar.com/tech/crypto/.

SunOS 4.x

In SunOS 4.x you most probably want to use the SunOS ld, /usr/bin/ld, since the more recent versions of GNU ld (like 2.13) do not seem to work for building Perl anymore. When linking the extensions, the GNU ld gets very unhappy and spews a lot of errors like this

  ... relocation truncated to fit: BASE13 ...

and dies. Therefore the SunOS 4.1 hints file explicitly sets the ld to be /usr/bin/ld.

As of Perl 5.8.1 the dynamic loading of libraries (DynaLoader, XSLoader) also seems to have become broken in in SunOS 4.x. Therefore the default is to build Perl statically.

Running the test suite in SunOS 4.1 is a bit tricky since the lib/Tie/File/t/09_gen_rs test hangs (subtest #51, FWIW) for some unknown reason. Just stop the test and kill that particular Perl process.

There are various other failures, that as of SunOS 4.1.4 and gcc 3.2.2 look a lot like gcc bugs. Many of the failures happen in the Encode tests, where for example when the test expects "0" you get "&#48;" which should after a little squinting look very odd indeed. Another example is earlier in t/run/fresh_perl where chr(0xff) is expected but the test fails because the result is chr(0xff). Exactly.

This is the "make test" result from the said combination:

  Failed 27 test scripts out of 745, 96.38% okay.

Running the harness is painful because of the many failing Unicode-related tests will output megabytes of failure messages, but if one patiently waits, one gets these results:

 Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
 -----------------------------------------------------------------------------
 ...
 ../ext/Encode/t/at-cn.t            4  1024    29    4  13.79%  14-17
 ../ext/Encode/t/at-tw.t           10  2560    17   10  58.82%  2 4 6 8 10 12
                                                                14-17
 ../ext/Encode/t/enc_data.t        29  7424    ??   ??       %  ??
 ../ext/Encode/t/enc_eucjp.t       29  7424    ??   ??       %  ??
 ../ext/Encode/t/enc_module.t      29  7424    ??   ??       %  ??
 ../ext/Encode/t/encoding.t        29  7424    ??   ??       %  ??
 ../ext/Encode/t/grow.t            12  3072    24   12  50.00%  2 4 6 8 10 12 14
                                                                16 18 20 22 24
  Failed Test                     Stat Wstat Total Fail  Failed  List of Failed
 ------------------------------------------------------------------------------
 ../ext/Encode/t/guess.t          255 65280    29   40 137.93%  10-29
 ../ext/Encode/t/jperl.t           29  7424    15   30 200.00%  1-15
 ../ext/Encode/t/mime-header.t      2   512    10    2  20.00%  2-3
 ../ext/Encode/t/perlio.t          22  5632    38   22  57.89%  1-4 9-16 19-20
                                                                23-24 27-32
 ../ext/List/Util/t/shuffle.t       0   139    ??   ??       %  ??
 ../ext/PerlIO/t/encoding.t                    14    1   7.14%  11
 ../ext/PerlIO/t/fallback.t                     9    2  22.22%  3 5
 ../ext/Socket/t/socketpair.t       0     2    45   70 155.56%  11-45
 ../lib/CPAN/t/vcmp.t                          30    1   3.33%  25
 ../lib/Tie/File/t/09_gen_rs.t      0    15    ??   ??       %  ??
 ../lib/Unicode/Collate/t/test.t              199   30  15.08%  7 26-27 71-75
                                                                81-88 95 101
                                                                103-104 106 108-
                                                                109 122 124 161
                                                                169-172
 ../lib/sort.t                      0   139   119   26  21.85%  107-119
 op/alarm.t                                     4    1  25.00%  4
 op/utfhash.t                                  97    1   1.03%  31
 run/fresh_perl.t                              91    1   1.10%  32
 uni/tr_7jis.t                                 ??   ??       %  ??
 uni/tr_eucjp.t                    29  7424     6   12 200.00%  1-6
 uni/tr_sjis.t                     29  7424     6   12 200.00%  1-6
 56 tests and 467 subtests skipped.
 Failed 27/811 test scripts, 96.67% okay. 1383/75399 subtests failed, 98.17% okay.

The alarm() test failure is caused by system() apparently blocking alarm(). That is probably a libc bug, and given that SunOS 4.x has been end-of-lifed years ago, don't hold your breath for a fix. In addition to that, don't try anything too Unicode-y, especially with Encode, and you should be fine in SunOS 4.x.

AUTHOR

The original was written by Andy Dougherty doughera@lafayette.edu drawing heavily on advice from Alan Burlison, Nick Ing-Simmons, Tim Bunce, and many other Solaris users over the years.

Please report any errors, updates, or suggestions to perlbug@perl.org.


README.tru64 - Perl version 5 on Tru64 systems

    • Compiling Perl 5 on Tru64
    • Using Large Files with Perl on Tru64
    • Threaded Perl on Tru64
    • Long Doubles on Tru64
    • DB_File tests failing on Tru64
    • 64-bit Perl on Tru64
    • Warnings about floating-point overflow when compiling Perl on Tru64
  • Testing Perl on Tru64
  • ext/ODBM_File/odbm Test Failing With Static Builds
  • Perl Fails Because Of Unresolved Symbol sockatmark
  • AUTHOR

NAME

README.tru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems

DESCRIPTION

This document describes various features of HP's (formerly Compaq's, formerly Digital's) Unix operating system (Tru64) that will affect how Perl version 5 (hereafter just Perl) is configured, compiled and/or runs.

Compiling Perl 5 on Tru64

The recommended compiler to use in Tru64 is the native C compiler. The native compiler produces much faster code (the speed difference is noticeable: several dozen percentages) and also more correct code: if you are considering using the GNU C compiler you should use at the very least the release of 2.95.3 since all older gcc releases are known to produce broken code when compiling Perl. One manifestation of this brokenness is the lib/sdbm test dumping core; another is many of the op/regexp and op/pat, or ext/Storable tests dumping core (the exact pattern of failures depending on the GCC release and optimization flags).

gcc 3.2.1 is known to work okay with Perl 5.8.0. However, when optimizing the toke.c gcc likes to have a lot of memory, 256 megabytes seems to be enough. The default setting of the process data section in Tru64 should be one gigabyte, but some sites/setups might have lowered that. The configuration process of Perl checks for too low process limits, and lowers the optimization for the toke.c if necessary, and also gives advice on how to raise the process limits.

Using Large Files with Perl on Tru64

In Tru64 Perl is automatically able to use large files, that is, files larger than 2 gigabytes, there is no need to use the Configure -Duselargefiles option as described in INSTALL (though using the option is harmless).

Threaded Perl on Tru64

If you want to use threads, you should primarily use the new Perl 5.8.0 threads model by running Configure with -Duseithreads.

The old Perl 5.005 threads is obsolete, unmaintained, and its use is discouraged. If you really want it, run Configure with the -Dusethreads -Duse5005threads options as described in INSTALL.

Either thread model is going to work only in Tru64 4.0 and newer releases, older operating releases like 3.2 aren't probably going to work properly with threads.

In Tru64 V5 (at least V5.1A, V5.1B) you cannot build threaded Perl with gcc because the system header <pthread.h> explicitly checks for supported C compilers, gcc (at least 3.2.2) not being one of them. But the system C compiler should work just fine.

Long Doubles on Tru64

You cannot Configure Perl to use long doubles unless you have at least Tru64 V5.0, the long double support simply wasn't functional enough before that. Perl's Configure will override attempts to use the long doubles (you can notice this by Configure finding out that the modfl() function does not work as it should).

At the time of this writing (June 2002), there is a known bug in the Tru64 libc printing of long doubles when not using "e" notation. The values are correct and usable, but you only get a limited number of digits displayed unless you force the issue by using printf "%.33e",$num or the like. For Tru64 versions V5.0A through V5.1A, a patch is expected sometime after perl 5.8.0 is released. If your libc has not yet been patched, you'll get a warning from Configure when selecting long doubles.

DB_File tests failing on Tru64

The DB_File tests (db-btree.t, db-hash.t, db-recno.t) may fail you have installed a newer version of Berkeley DB into the system and the -I and -L compiler and linker flags introduce version conflicts with the DB 1.85 headers and libraries that came with the Tru64. For example, mixing a DB v2 library with the DB v1 headers is a bad idea. Watch out for Configure options -Dlocincpth and -Dloclibpth, and check your /usr/local/include and /usr/local/lib since they are included by default.

The second option is to explicitly instruct Configure to detect the newer Berkeley DB installation, by supplying the right directories with -Dlocincpth=/some/include and -Dloclibpth=/some/lib and before running "make test" setting your LD_LIBRARY_PATH to /some/lib.

The third option is to work around the problem by disabling the DB_File completely when build Perl by specifying -Ui_db to Configure, and then using the BerkeleyDB module from CPAN instead of DB_File. The BerkeleyDB works with Berkeley DB versions 2.* or greater.

The Berkeley DB 4.1.25 has been tested with Tru64 V5.1A and found to work. The latest Berkeley DB can be found from http://www.sleepycat.com.

64-bit Perl on Tru64

In Tru64 Perl's integers are automatically 64-bit wide, there is no need to use the Configure -Duse64bitint option as described in INSTALL. Similarly, there is no need for -Duse64bitall since pointers are automatically 64-bit wide.

Warnings about floating-point overflow when compiling Perl on Tru64

When compiling Perl in Tru64 you may (depending on the compiler release) see two warnings like this

    cc: Warning: numeric.c, line 104: In this statement, floating-point overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
        return HUGE_VAL;
    -----------^

and when compiling the POSIX extension

    cc: Warning: const-c.inc, line 2007: In this statement, floating-point overflow occurs in evaluating the expression "1.8e308". (floatoverfl)
                return HUGE_VAL;
    -------------------^

The exact line numbers may vary between Perl releases. The warnings are benign and can be ignored: in later C compiler releases the warnings should be gone.

When the file pp_sys.c is being compiled you may (depending on the operating system release) see an additional compiler flag being used: -DNO_EFF_ONLY_OK. This is normal and refers to a feature that is relevant only if you use the filetest pragma. In older releases of the operating system the feature was broken and the NO_EFF_ONLY_OK instructs Perl not to use the feature.

Testing Perl on Tru64

During "make test" the comp/cpp will be skipped because on Tru64 it cannot be tested before Perl has been installed. The test refers to the use of the -P option of Perl.

ext/ODBM_File/odbm Test Failing With Static Builds

The ext/ODBM_File/odbm is known to fail with static builds (Configure -Uusedl) due to a known bug in Tru64's static libdbm library. The good news is that you very probably don't need to ever use the ODBM_File extension since more advanced NDBM_File works fine, not to mention the even more advanced DB_File.

Perl Fails Because Of Unresolved Symbol sockatmark

If you get an error like

    Can't load '.../OSF1/lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so' for module IO: Unresolved symbol in .../lib/perl5/5.8.0/alpha-dec_osf/auto/IO/IO.so: sockatmark at .../lib/perl5/5.8.0/alpha-dec_osf/XSLoader.pm line 75.

you need to either recompile your Perl in Tru64 4.0D or upgrade your Tru64 4.0D to at least 4.0F: the sockatmark() system call was added in Tru64 4.0F, and the IO extension refers that symbol.

AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>


perluts - Perl under UTS

  • BUILDING PERL ON UTS
  • Installing the built perl on UTS
  • AUTHOR

NAME

perluts - Perl under UTS

SYNOPSIS

This document can be read as is: as README.uts, or you can read it after you build your package using "man perluts".

The purpose is to help you build Perl for UTS, which, if you follow these instructions, should be easy, and result in a solidly working installation.

DESCRIPTION

Perl 5.7.2 (Developmental) or Perl 5.8.x (forthcoming) for UTS

BUILDING PERL ON UTS

NOTE: Some sites have redefined the way uname works, and if yours does this, special steps must be taken so that Configure can recognize your system as a UTS system. To see if you are in this category, issue the command "uname -a". It should look something like:

  uts juno 4 4.4 9672 370

At any rate, the first field should be "uts". If this is not the case; supposing it is, say telcoUTS, create a script, uts/uname (i.e. uname, in the subdirectory "uts" of the main Perl source dir): # uname /usr/bin/uname "$@" | sed -e 's/^telcoUTS/uts/'

and when you execute Configure, do it as below, except for adding PATH=uts:$PATH as a prefix. I.e. do:

   PATH=uts:$PATH ./Configure ...

There is no need to do an interactive configure, just type

  ./Configure -de [-Dusedevel] [-Doptimize=-g ] 2>&1 | tee Conf.out

"-Dusedevel" may be required to configure Perl 5.7.2 non-interactively. Use -Doptimize=-g if you want to run Perl under sdb or gdb, OR if you want to be able to use the -D command line flags to perl, which are occasionally useful in debugging perl scripts.

In this and the following steps, the "2>&1 | tee XXX.out" records all output from the process, which will be useful if anything unexpected goes wrong.

Then do the compilation with

  make 2>&1 | tee make.out

Finally, test using

  make test 2>&1 | tee make-test.out

In the output, the only failures you should see should look like:

   lib/Math/BigInt/t/bigfltpm.........Use of uninitialized value ...
   FAILED at test 57
   lib/Math/BigInt/t/bigintc..........ok
   lib/Math/BigInt/t/bigintpm.........FAILED at test 204
   lib/Math/BigInt/t/mbimbf...........Use of uninitialized value ...
   Illegal division by zero at ../lib/Math/BigInt/Calc.pm line 314.
   FAILED at test 71
   lib/Math/Complex...................exp: OVERFLOW
   FAILED at test 250
   lib/Math/Trig......................exp: OVERFLOW
   ok
   lib/Memoize/t/array................ok
        ...
   lib/Net/protoent...................ok
   lib/Net/servent....................FAILED at test 0

This means that everything passes except for some problems in the packages "Math::BigInt", "Math::Complex", and "Math::Trig". The lib/Net/servent failure seems to be a bug in the test program. To confirm this, from the main Perl source dir, do:

   LD_LIBRARY_PATH=`pwd` ./perl -Ilib lib/Net/servent.t

and it should output

   1..3
   ok 1
   ok 2
   ok 3

Installing the built perl on UTS

Run the command "make install"

AUTHOR

   Hal Morris
   UTS Global LLC
   email: hom00@utsglobal.com


README.vmesa - building and installing Perl for VM/ESA.

    • Unpacking Perl Distribution on VM/ESA
    • Setup Perl and utilities on VM/ESA
    • Configure Perl on VM/ESA
    • Testing Anomalies of Perl on VM/ESA
    • Usage Hints for Perl on VM/ESA
  • AUTHORS
  • SEE ALSO
    • Mailing list for Perl on VM/ESA

NAME

README.vmesa - building and installing Perl for VM/ESA.

SYNOPSIS

This document will help you Configure, build, test and install Perl on VM/ESA.

DESCRIPTION

This is a fully ported perl for VM/ESA 2.3.0. It may work on other versions, but that's the one we've tested it on.

If you've downloaded the binary distribution, it needs to be installed below /usr/local. Source code distributions have an automated "make install" step that means you do not need to extract the source code below /usr/local (though that is where it will be installed by default). You may need to worry about the networking configuration files discussed in the last bullet below.

Unpacking Perl Distribution on VM/ESA

To extract an ASCII tar archive on VM/ESA, try this:

   pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar

Setup Perl and utilities on VM/ESA

GNU make for VM/ESA, which may be required for the build of perl, is available from:

  http://vm.marist.edu/~neale/vmoe.html

Configure Perl on VM/ESA

Once you've unpacked the distribution, run Configure (see INSTALL for full discussion of the Configure options), and then run make, then "make test" then "make install" (this last step may require UID=0 privileges).

There is a "hints" file for vmesa that specifies the correct values for most things. Some things to watch out for are:

  • this port does support dynamic loading but it's not had much testing

  • Don't turn on the compiler optimization flag "-O". There's a bug in the compiler (APAR PQ18812) that generates some bad code the optimizer is on.

  • As VM/ESA doesn't fully support the fork() API programs relying on this call will not work. I've replaced fork()/exec() with spawn() and the standalone exec() with spawn(). This has a side effect when opening unnamed pipes in a shell script: there is no child process generated under.

  • At the moment the hints file for VM/ESA basically bypasses all of the automatic configuration process. This is because Configure relies on: 1. The header files living in the Byte File System (you could put the there if you want); 2. The C preprocessor including the #include statements in the preprocessor output (.i) file.

Testing Anomalies of Perl on VM/ESA

The "make test" step runs a Perl Verification Procedure, usually before installation. As the 5.6.1 kit was being assembled the following "failures" were known to appear on some machines during "make test" (mostly due to ASCII vs. EBCDIC conflicts), your results may differ:

[the list of failures being compiled]

Usage Hints for Perl on VM/ESA

When using perl on VM/ESA please keep in mind that the EBCDIC and ASCII character sets are different. Perl builtin functions that may behave differently under EBCDIC are mentioned in the perlport.pod document.

OpenEdition (UNIX System Services) does not (yet) support the #! means of script invocation. See:

    head `whence perldoc`

for an example of how to use the "eval exec" trick to ask the shell to have perl run your scripts for you.

AUTHORS

Neale Ferguson.

SEE ALSO

INSTALL, the perlport manpage, the perlebcdic manpage.

Mailing list for Perl on VM/ESA

If you are interested in the VM/ESA, z/OS (formerly known as OS/390) and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list. To subscribe, send an empty message to perl-mvs-subscribe@perl.org.

See also:

    http://lists.perl.org/showlist.cgi?name=perl-mvs

There are web archives of the mailing list at:


README.vms - Configuring, building, testing, and installing perl on VMS

    • Important safety tip
    • Introduction to Perl on VMS
    • Other required software for Compiling Perl on VMS
    • Additional software that is optional for Perl on VMS
  • Unpacking the Perl source code
  • Configuring the Perl build
    • Changing compile-time options (optional) for Perl on VMS
    • Socket Support (optional) for Perl on VMS
  • Building Perl
  • Testing Perl
    • Cleaning up and starting fresh (optional) installing Perl on VMS
  • Installing Perl
    • Installing Perl into DCLTABLES (optional) on VMS
    • INSTALLing Perl images (optional) on VMS
    • Running h2ph to create perl header files (optional) on VMS
  • Reporting Bugs
  • CAVEATS
    • DEC C issues with Perl on VMS
    • GNU issues with Perl on VMS
    • Floating Point Considerations
    • Multinet issues with Perl on VMS
  • Mailing Lists
    • Web sites for Perl on VMS
  • SEE ALSO
  • AUTHORS
  • ACKNOWLEDGEMENTS

NAME

README.vms - Configuring, building, testing, and installing perl on VMS

SYNOPSIS

To configure, build, test, and install perl on VMS:

    @ Configure
    mms
    mms test
    mms install

mmk may be used in place of mms in the last three steps.

DESCRIPTION

Important safety tip

The build and install procedures have changed significantly from the 5.004 releases! Make sure you read the "Configuring the Perl Build", "Building Perl", and "Installing Perl" sections of this document before you build or install. Also please note other changes in the current release by having a look at VMS in the perldelta manpage.

Also note that, as of Perl version 5.005 and later, an ANSI C compliant compiler is required to build Perl. VAX C is *not* ANSI compliant, as it died a natural death some time before the standard was set. Therefore VAX C will not compile Perl 5.005 or later. We are sorry about that.

If you are stuck without Compaq (formerly DEC) C consider trying Gnu C instead, though there have been no recent reports of builds using Gnu C. There is minimal support for Compaq C++ but this support is not complete; if you get it working please write to the vmsperl list (for info see Mailing Lists).

Introduction to Perl on VMS

The VMS port of Perl is as functionally complete as any other Perl port (and as complete as the ports on some Unix systems). The Perl binaries provide all the Perl system calls that are either available under VMS or reasonably emulated. There are some incompatibilities in process handling (e.g. the fork/exec model for creating subprocesses doesn't do what you might expect under Unix), mainly because VMS and Unix handle processes and sub-processes very differently.

There are still some unimplemented system functions, and of course we could use modules implementing useful VMS system services, so if you'd like to lend a hand we'd love to have you. Join the Perl Porting Team Now!

The current sources and build procedures have been tested on a VAX using DEC C, and on an AXP using DEC C. If you run into problems with other compilers, please let us know. (Note: DEC C was renamed to Compaq C around version 6.2).

There are issues with various versions of DEC C, so if you're not running a relatively modern version, check the "DEC C issues" section later on in this document.

Other required software for Compiling Perl on VMS

In addition to VMS and DCL you will need two things:

  1. A C compiler.

    DEC (now Compaq) C or gcc for VMS (AXP or VAX).

  2. A make tool.

    DEC's MMS (v2.6 or later), or MadGoat's free MMS analog MMK (available from ftp.madgoat.com/madgoat) both work just fine. Gnu Make might work, but it's been so long since anyone's tested it that we're not sure. MMK is free though, so go ahead and use that.

Additional software that is optional for Perl on VMS

You may also want to have on hand:

  1. GUNZIP/GZIP.EXE for VMS

    A de-compressor for *.gz and *.tgz files available from a number of web/ftp sites and is distributed on the OpenVMS Freeware CD-ROM from Compaq.

        http://www.fsf.org/order/ftp.html
    http://www.openvms.compaq.com/freeware/
    http://www.crinoid.com/utils/
  2. VMS TAR

    For reading and writing unix tape archives (*.tar files). Vmstar is also available from a number of web/ftp sites and is distributed on the OpenVMS Freeware CD-ROM from Compaq.

        ftp://ftp.lp.se/vms/
    http://www.openvms.compaq.com/freeware/

    Recent versions of VMS tar on ODS-5 volumes may extract tape archive files with ^. escaped periods in them. See below for further workarounds.

  3. UNZIP.EXE for VMS

    A combination decompressor and archive reader/writer for *.zip files. Unzip is available from a number of web/ftp sites.

        http://www.info-zip.org/UnZip.html
    http://www.openvms.compaq.com/freeware/
    ftp://ftp.openvms.compaq.com/
    ftp://ftp.madgoat.com/madgoat/
    ftp://ftp.process.com/vms-freeware/
  4. MOST

    Most is an optional pager that is convenient to use with perldoc (unlike TYPE/PAGE, MOST can go forward and backwards in a document and supports regular expression searching). Most builds with the slang library on VMS. Most and slang are available from:

        ftp://space.mit.edu/pub/davis/
    ftp://ftp.process.com/vms-freeware/narnia/
  5. GNU PATCH and DIFFUTILS for VMS

    Patches to Perl are usually distributed as GNU unified or contextual diffs. Such patches are created by the GNU diff program (part of the diffutils distribution) and applied with GNU patch. VMS ports of these utilities are available here:

        http://www.crinoid.com/utils/
    http://www.openvms.compaq.com/freeware/

Please note that UNZIP and GUNZIP are not the same thing (they work with different formats). Many of the useful files from CPAN (the Comprehensive Perl Archive Network) are in *.tar.gz or *.tgz format (this includes copies of the source code for perl as well as modules and scripts that you may wish to add later) hence you probably want to have GUNZIP.EXE and VMSTAR.EXE on your VMS machine.

If you want to include socket support, you'll need a TCP/IP stack and either DEC C, or socket libraries. See the "Socket Support (optional)" topic for more details.

Unpacking the Perl source code

You may need to set up a foreign symbol for the unpacking utility of choice.

If you unpack a perl source kit with a name containing multiple periods on an ODS-5 volume using recent versions of vmstar (e.g. V3.4 or later) you may need to be especially careful in unpacking the tape archive file. Try to use the ODS-2 compatability qualifiers such as:

    vmstar /extract/verbose/ods2 perl-V^.VIII^.III.tar

or:

    vmstar -xvof perl-5^.8^.8.tar

If you neglected to use the /ODS2 qualifier or the -o switch then you could rename the source directory:

    set security/protection=(o:rwed) perl-5^.8^.8.dir
    rename perl-5^.8^.8.dir perl-5_8_8.dir

Perl on VMS as of 5.8.8 does not completely handle extended file parse styles such as are encountered on ODS-5. While it can be built, installed, and run on ODS-5 filesystems; it may encounter trouble with characters that are otherwise illegal on ODS-2 volumes (notably the ^. escaped period sequence).

Configuring the Perl build

To configure perl (a necessary first step), issue the command

   @ Configure

from the top of an unpacked perl source directory. You will be asked a series of questions, and the answers to them (along with the capabilities of your C compiler and network stack) will determine how perl is custom built for your machine.

If you have multiple C compilers installed, you'll have your choice of which one to use. Various older versions of DEC C had some caveats, so if you're using a version older than 5.2, check the "DEC C Issues" section.

If you have any symbols or logical names in your environment that may interfere with the build or regression testing of perl then configure.com will try to warn you about them. If a logical name is causing you trouble but is in an LNM table that you do not have write access to then try defining your own to a harmless equivalence string in a table such that it is resolved before the other (e.g. if TMP is defined in the SYSTEM table then try DEFINE TMP "NL:" or somesuch in your process table) otherwise simply deassign the dangerous logical names. The potentially troublesome logicals and symbols are:

    COMP    "LOGICAL"
    EXT     "LOGICAL"
    FOO     "LOGICAL"
    LIB     "LOGICAL"
    LIST    "LOGICAL"
    MIME    "LOGICAL"
    POSIX   "LOGICAL"
    SYS     "LOGICAL"
    T       "LOGICAL"
    THREAD  "LOGICAL"
    THREADS "LOGICAL"
    TIME    "LOGICAL"
    TMP     "LOGICAL"
    UNICODE "LOGICAL"
    UTIL    "LOGICAL"
    TEST    "SYMBOL"

As a handy shortcut, the command:

    @ Configure "-des"

(note the quotation marks and case) will choose reasonable defaults automatically (it takes DEC C over Gnu C, DEC C sockets over SOCKETSHR sockets, and either over no sockets). Some options can be given explicitly on the command line; the following example specifies a non-default location for where Perl will be installed:

    @ Configure "-d" "-Dprefix=dka100:[utils.perl5.]"

Note that the installation location would be by default where you unpacked the source with a "_ROOT." appended. For example if you unpacked the perl source into:

   DKA200:[PERL-5_10_2...]

Then the PERL_SETUP.COM that gets written out by CONFIGURE.COM will try to DEFINE your installation PERL_ROOT to be:

   DKA200:[PERL-5_10_2_ROOT.]

More help with configure.com is available from:

    @ Configure "-h"

See the "Changing compile-time options (optional)" section below to learn even more details about how to influence the outcome of the important configuration step. If you find yourself reconfiguring and rebuilding then be sure to also follow the advice in the "Cleaning up and starting fresh (optional)" and the checklist of items in the "CAVEATS" sections below.

Changing compile-time options (optional) for Perl on VMS

Most of the user definable features of Perl are enabled or disabled in configure.com, which processes the hints file config_h.SH. There is code in there to Do The Right Thing, but that may end up being the wrong thing for you. Make sure you understand what you are doing since inappropriate changes to configure.com or config_h.SH can render perl unbuildable; odds are that there's nothing in there you'll need to change.

The one exception is the various *DIR install locations. Changing those requires changes in genconfig.pl as well. Be really careful if you need to change these, as they can cause some fairly subtle problems.

Socket Support (optional) for Perl on VMS

Perl includes a number of functions for IP sockets, which are available if you choose to compile Perl with socket support. Since IP networking is an optional addition to VMS, there are several different IP stacks available. How well integrated they are into the system depends on the stack, your version of VMS, and the version of your C compiler.

The most portable solution uses the SOCKETSHR library. In combination with either UCX or NetLib, this supports all the major TCP stacks (Multinet, Pathways, TCPWare, UCX, and CMU) on all versions of VMS Perl runs on, with all the compilers on both VAX and Alpha. The socket interface is also consistent across versions of VMS and C compilers. It has a problem with UDP sockets when used with Multinet, though, so you should be aware of that.

The other solution available is to use the socket routines built into DEC C. Which routines are available depend on the version of VMS you're running, and require proper UCX emulation by your TCP/IP vendor. Relatively current versions of Multinet, TCPWare, Pathway, and UCX all provide the required libraries--check your manuals or release notes to see if your version is new enough.

Building Perl

The configuration script will print out, at the very end, the MMS or MMK command you need to compile perl. Issue it (exactly as printed) to start the build.

Once you issue your MMS or MMK command, sit back and wait. Perl should compile and link without a problem. If a problem does occur check the "CAVEATS" section of this document. If that does not help send some mail to the VMSPERL mailing list. Instructions are in the "Mailing Lists" section of this document.

Testing Perl

Once Perl has built cleanly you need to test it to make sure things work. This step is very important since there are always things that can go wrong somehow and yield a dysfunctional Perl for you.

Testing is very easy, though, as there's a full test suite in the perl distribution. To run the tests, enter the *exact* MMS line you used to compile Perl and add the word "test" to the end, like this:

If the compile command was:

    MMS

then the test command ought to be:

    MMS test

MMS (or MMK) will run all the tests. This may take some time, as there are a lot of tests. If any tests fail, there will be a note made on-screen. At the end of all the tests, a summary of the tests, the number passed and failed, and the time taken will be displayed.

The test driver invoked via MMS TEST has a DCL wrapper ([.VMS]TEST.COM) that downgrades privileges to NETMBX, TMPMBX for the duration of the test run, and then restores them to their prior state upon completion of testing. This is done to ensure that the tests run in a private sandbox and can do no harm to your system even in the unlikely event something goes badly wrong in one of the test scripts while running the tests from a privileged account. A side effect of this safety precaution is that the account used to run the test suite must be the owner of the directory tree in which Perl has been built; otherwise the manipulations of temporary files and directories attempted by some of the tests will fail.

If any tests fail, it means something is wrong with Perl. If the test suite hangs (some tests can take upwards of two or three minutes, or more if you're on an especially slow machine, depending on your machine speed, so don't be hasty), then the test *after* the last one displayed failed. Don't install Perl unless you're confident that you're OK. Regardless of how confident you are, make a bug report to the VMSPerl mailing list.

If one or more tests fail, you can get more information on the failure by issuing this command sequence:

    @ [.VMS]TEST .typ "" "-v" [.subdir]test.T

where ".typ" is the file type of the Perl images you just built (if you didn't do anything special, use .EXE), and "[.subdir]test.T" is the test that failed. For example, with a normal Perl build, if the test indicated that t/op/time failed, then you'd do this:

    @ [.VMS]TEST .EXE "" "-v" [.OP]TIME.T

Note that test names are reported in UNIX syntax and relative to the top-level build directory. When supplying them individually to the test driver, you can use either UNIX or VMS syntax, but you must give the path relative to the [.T] directory and you must also add the .T extension to the filename. So, for example if the test lib/Math/Trig fails, you would run:

    @ [.VMS]TEST .EXE "" -"v" [-.lib.math]trig.t

When you send in a bug report for failed tests, please include the output from this command, which is run from the main source directory:

    MCR []MINIPERL "-V"

Note that -"V" really is a capital V in double quotes. This will dump out a couple of screens worth of configuration information, and can help us diagnose the problem. If (and only if) that did not work then try enclosing the output of:

    MMS printconfig

If (and only if) that did not work then try enclosing the output of:

    @ [.vms]myconfig

You may also be asked to provide your C compiler version ("CC/VERSION NL:" with DEC C, "gcc --version" with GNU CC). To obtain the version of MMS or MMK you are running try "MMS/ident" or "MMK /ident". The GNU make version can be identified with "make --version".

Cleaning up and starting fresh (optional) installing Perl on VMS

If you need to recompile from scratch, you have to make sure you clean up first. There is a procedure to do it--enter the *exact* MMS line you used to compile and add "realclean" at the end, like this:

if the compile command was:

    MMS

then the cleanup command ought to be:

    MMS realclean

If you do not do this things may behave erratically during the subsequent rebuild attempt. They might not, too, so it is best to be sure and do it.

Installing Perl

There are several steps you need to take to get Perl installed and running.

  1. Check your default file protections with

         SHOW PROTECTION /DEFAULT

    and adjust if necessary with SET PROTECTION=(code)/DEFAULT.

  2. Decide where you want Perl to be installed (unless you have already done so by using the "prefix" configuration parameter -- see the example in the "Configuring the Perl build" section).

    The DCL script PERL_SETUP.COM that is written by CONFIGURE.COM will help you with the definition of the PERL_ROOT and PERLSHR logical names and the PERL foreign command symbol. Take a look at PERL_SETUP.COM and modify it if you want to. The installation process will execute PERL_SETUP.COM and copy files to the directory tree pointed to by the PERL_ROOT logical name defined there, so make sure that you have write access to the parent directory of what will become the root of your Perl installation.

  3. Run the install script via:

        MMS install

    or

        MMK install

    If for some reason it complains about target INSTALL being up to date, throw a /FORCE switch on the MMS or MMK command.

Copy PERL_SETUP.COM to a place accessible to your perl users.

For example:

    COPY PERL_SETUP.COM SYS$LIBRARY:

If you want to have everyone on the system have access to perl then add a line that reads

    $ @sys$library:perl_setup

to SYS$MANAGER:SYLOGIN.COM.

Two alternatives to the foreign symbol would be to install PERL into DCLTABLES.EXE (Check out the section "Installing Perl into DCLTABLES (optional)" for more information), or put the image in a directory that's in your DCL$PATH (if you're using VMS V6.2 or higher).

An alternative to having PERL_SETUP.COM define the PERLSHR logical name is to simply copy it into the system shareable library directory with:

    copy perl_root:[000000]perlshr.exe sys$share:

See also the "INSTALLing images (optional)" section.

Installing Perl into DCLTABLES (optional) on VMS

Execute the following command file to define PERL as a DCL command. You'll need CMKRNL privilege to install the new dcltables.exe.

    $ create perl.cld
    !
    ! modify to reflect location of your perl.exe
    !
    define verb perl
      image perl_root:[000000]perl.exe
      cliflags (foreign)
    $!
    $ set command perl /table=sys$common:[syslib]dcltables.exe -
     /output=sys$common:[syslib]dcltables.exe
    $ install replace sys$common:[syslib]dcltables.exe
    $ exit

INSTALLing Perl images (optional) on VMS

On systems that are using perl quite a bit, and particularly those with minimal RAM, you can boost the performance of perl by INSTALLing it as a known image. PERLSHR.EXE is typically larger than 3000 blocks and that is a reasonably large amount of IO to load each time perl is invoked.

   INSTALL ADD PERLSHR/SHARE
   INSTALL ADD PERL/HEADER

should be enough for PERLSHR.EXE (/share implies /header and /open), while /HEADER should do for PERL.EXE (perl.exe is not a shared image).

If your code 'use's modules, check to see if there is a shareable image for them, too. In the base perl build, POSIX, IO, Fcntl, Opcode, SDBM_File, DCLsym, and Stdio, and other extensions all have shared images that can be installed /SHARE.

How much of a win depends on your memory situation, but if you are firing off perl with any regularity (like more than once every 20 seconds or so) it is probably beneficial to INSTALL at least portions of perl.

While there is code in perl to remove privileges as it runs you are advised to NOT INSTALL PERL.EXE with PRIVs!

Running h2ph to create perl header files (optional) on VMS

If using DEC C or Compaq C ensure that you have extracted loose versions of your compiler's header or *.H files. Be sure to check the contents of:

    SYS$LIBRARY:DECC$RTLDEF.TLB
    SYS$LIBRARY:SYS$LIB_C.TLB
    SYS$LIBRARY:SYS$STARLET_C.TLB

etcetera.

If using GNU cc then also check your GNU_CC:[000000...] tree for the locations of the GNU cc headers.

Reporting Bugs

If you come across what you think might be a bug in Perl, please report it. There's a script in PERL_ROOT:[UTILS], perlbug, that walks you through the process of creating a bug report. This script includes details of your installation, and is very handy. Completed bug reports should go to perlbug@perl.com.

CAVEATS

Probably the single biggest gotcha in compiling Perl is giving the wrong switches to MMS/MMK when you build. Use *exactly* what the configure.com script prints!

The next big gotcha is directory depth. Perl can create directories four, five, or even six levels deep during the build, so you don't have to be too deep to start to hit the RMS 8 level limit (for ODS 2 volumes which were common on versions of VMS prior to V7.2 and even with V7.2 on the VAX). It is best to do:

    DEFINE/TRANS=(CONC,TERM) PERLSRC "disk:[dir.dir.dir.perldir.]"
    SET DEFAULT PERLSRC:[000000]

before building in cases where you have to unpack the distribution so deep (note the trailing period in the definition of PERLSRC). Perl modules from CPAN can be just as bad (or worse), so watch out for them, too. Perl's configuration script will warn if it thinks you are too deep (at least on a VAX or on Alpha versions of VMS prior to 7.2). But MakeMaker will not warn you if you start out building a module too deep in a directory.

As noted above ODS-5 escape sequences such as ^. can break the perl build. Solutions include renaming files and directories as needed or being careful to use the -o switch or /ODS2 qualifier with latter versions of the vmstar utility when unpacking perl or CPAN modules on ODS-5 volumes.

Be sure that the process that you use to build perl has a PGFLQ greater than 100000. Be sure to have a correct local time zone to UTC offset defined (in seconds) in the logical name SYS$TIMEZONE_DIFFERENTIAL before running the regression test suite. The SYS$MANAGER:UTC$CONFIGURE_TDF.COM procedure will help you set that logical for your system but may require system privileges. For example, a location 5 hours west of UTC (such as the US East coast while not on daylight savings time) would have:

    DEFINE SYS$TIMEZONE_DIFFERENTIAL "-18000"

A final thing that causes trouble is leftover pieces from a failed build. If things go wrong make sure you do a "(MMK|MMS|make) realclean" before you rebuild.

DEC C issues with Perl on VMS

Note to DEC C users: Some early versions (pre-5.2, some pre-4. If you're DEC C 5.x or higher, with current patches if any, you're fine) of the DECCRTL contained a few bugs which affect Perl performance:

- pipes

Newlines are lost on I/O through pipes, causing lines to run together. This shows up as RMS RTB errors when reading from a pipe. You can work around this by having one process write data to a file, and then having the other read the file, instead of the pipe. This is fixed in version 4 of DEC C.

- modf()

The modf() routine returns a non-integral value for some values above INT_MAX; the Perl "int" operator will return a non-integral value in these cases. This is fixed in version 4 of DEC C.

- ALPACRT ECO

On the AXP, if SYSNAM privilege is enabled, the CRTL chdir() routine changes the process default device and directory permanently, even though the call specified that the change should not persist after Perl exited. This is fixed by DEC CSC patch ALPACRT04_061 or later. See also:

    http://ftp.support.compaq.com/patches/.new/openvms.shtml

Please note that in later versions "DEC C" may also be known as "Compaq C".

GNU issues with Perl on VMS

It has been a while since the GNU utilities such as GCC or GNU make were used to build perl on VMS. Hence they may require a great deal of source code modification to work again.

    http://slacvx.slac.stanford.edu/HELP/GCC
    http://www.progis.de/
    http://www.lp.se/products/gnu.html

Floating Point Considerations

Prior to 5.8.0, Perl simply accepted the default floating point options of the C compiler, namely representing doubles with D_FLOAT on VAX and G_FLOAT on Alpha. Single precision floating point values are represented in F_FLOAT format when either D_FLOAT or G_FLOAT is in use for doubles. Beginning with 5.8.0, Alpha builds now use IEEE floating point formats by default, which in VMS parlance are S_FLOAT for singles and T_FLOAT for doubles. IEEE is not available on VAX, so F_FLOAT and D_FLOAT remain the defaults for singles and doubles respectively. The available non-default options are G_FLOAT on VAX and D_FLOAT or G_FLOAT on Alpha.

The use of IEEE on Alpha introduces NaN, infinity, and denormalization capabilities not available with D_FLOAT and G_FLOAT. When using one of those non-IEEE formats, silent underflow and overflow are emulated in the conversion of strings to numbers, but it is preferable to get the real thing by using IEEE where possible.

Regardless of what floating point format you consider preferable, be aware that the choice may have an impact on compatibility with external libraries, such as database interfaces, and with existing data, such as data created with the pack function and written to disk, or data stored via the Storable extension. For example, a pack("d", $foo)") will create a D_FLOAT, G_FLOAT, or T_FLOAT depending on what your Perl was configured with. When written to disk, the value can only be retrieved later by a Perl configured with the same floating point option that was in effect when it was created.

To obtain a non-IEEE build on Alpha, simply answer no to the "Use IEEE math?" question during the configuration. To obtain an option different from the C compiler default on either VAX or Alpha, put in the option that you want in answer to the "Any additional cc flags?" question. For example, to obtain a G_FLOAT build on VAX, put in /FLOAT=G_FLOAT.

Multinet issues with Perl on VMS

Prior to the release of Perl 5.8.0 it was noted that the regression test for lib/Net/hostent (in file [.lib.Net]hostent.t) will fail owing to problems with the hostent structure returned by C calls to either gethostbyname() or gethostbyaddr() using DEC or Compaq C with a Multinet TCP/IP stack. The problem was noted in Multinet 4.3A using either Compaq C 6.5 or DEC C 6.0, and with Multinet 4.2A using DEC C 5.2, but could easily affect other versions of Multinet. Process Software Inc. has acknowledged a bug in the Multinet version of UCX$IPC_SHR and has provided an ECO for it. The ECO is called UCX_LIBRARY_EMULATION-010_A044 and is available from:

    http://www.multinet.process.com/eco.html

As of this writing, the ECO is only available for Multinet versions 4.3A and later. You may determine the version of Multinet that you are running using the command:

    multinet show /version

from the DCL command prompt.

If the ECO is unavailable for your version of Multinet and you are unable to upgrade, you might try using Perl programming constructs such as:

    $address = substr($gethostbyname_addr,0,4);

to temporarily work around the problem, or if you are brave and do not mind the possibility of breaking IPv6 addresses, you might modify the pp_sys.c file to add an ad-hoc correction like so:

    --- pp_sys.c;1        Thu May 30 14:42:17 2002
    +++ pp_sys.c        Thu May 30 12:54:02 2002
    @@ -4684,6 +4684,10 @@
             }
     #endif

    +    if (hent) {
    +        hent->h_length = 4;
    +    }
    +
         if (GIMME != G_ARRAY) {
             PUSHs(sv = sv_newmortal());
             if (hent) {

then re-compile and re-test your perl. After the installation of the Multinet ECO you ought to back out any such changes though.

Mailing Lists

There are several mailing lists available to the Perl porter. For VMS specific issues (including both Perl questions and installation problems) there is the VMSPERL mailing list. It is usually a low-volume (10-12 messages a week) mailing list.

To subscribe, send a mail message to VMSPERL-SUBSCRIBE@PERL.ORG. The VMSPERL mailing list address is VMSPERL@PERL.ORG. Any mail sent there gets echoed to all subscribers of the list. There is a searchable archive of the list on the web at:

    http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/

To unsubscribe from VMSPERL send a message to VMSPERL-UNSUBSCRIBE@PERL.ORG. Be sure to do so from the subscribed account that you are canceling.

Web sites for Perl on VMS

Vmsperl pages on the web include:

    http://www.sidhe.org/vmsperl/index.html
    http://www.crinoid.com/
    http://duphy4.physics.drexel.edu/pub/cgi_info.htmlx
    http://www.cpan.org/modules/by-module/VMS/
    http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/
    http://www.best.com/~pvhp/vms/
    http://www-ang.kfunigraz.ac.at/~binder/perl.html
    http://lists.perl.org/showlist.cgi?name=vmsperl
    http://archive.develooper.com/vmsperl@perl.org/
    http://www.openvms.compaq.com/openvms/products/ips/apache/csws_modperl.html

SEE ALSO

Perl information for users and programmers about the port of perl to VMS is available from the [.VMS]PERLVMS.POD file that gets installed as the perlvms manpage. For administrators the perlvms document also includes a detailed discussion of extending vmsperl with CPAN modules after Perl has been installed.

AUTHORS

Revised 10-October-2001 by Craig Berry craigberry@mac.com. Revised 25-February-2000 by Peter Prymmer pvhp@best.com. Revised 27-October-1999 by Craig Berry craigberry@mac.com. Revised 01-March-1999 by Dan Sugalski dan@sidhe.org. Originally by Charles Bailey bailey@newman.upenn.edu.

ACKNOWLEDGEMENTS

A real big thanks needs to go to Charles Bailey bailey@newman.upenn.edu, who is ultimately responsible for Perl 5.004 running on VMS. Without him, nothing the rest of us have done would be at all important.

There are, of course, far too many people involved in the porting and testing of Perl to mention everyone who deserves it, so please forgive us if we've missed someone. That said, special thanks are due to the following:

  Tim Adye T.J.Adye@rl.ac.uk
     for the VMS emulations of getpw*()
  David Denholm denholm@conmat.phys.soton.ac.uk
     for extensive testing and provision of pipe and SocketShr code,
  Mark Pizzolato mark@infocomm.com
     for the getredirection() code
  Rich Salz rsalz@bbn.com
     for readdir() and related routines
  Peter Prymmer pvhp@best.com
     for extensive testing, as well as development work on
     configuration and documentation for VMS Perl,
  Dan Sugalski dan@sidhe.org
     for extensive contributions to recent version support,
     development of VMS-specific extensions, and dissemination
     of information about VMS Perl,
  the Stanford Synchrotron Radiation Laboratory and the
     Laboratory of Nuclear Studies at Cornell University for
     the opportunity to test and develop for the AXP,
  John Hasstedt John.Hasstedt@sunysb.edu
     for VAX VMS V7.2 support

and to the entire VMSperl group for useful advice and suggestions. In addition the perl5-porters deserve credit for their creativity and willingness to work with the VMS newcomers. Finally, the greatest debt of gratitude is due to Larry Wall larry@wall.org, for having the ideas which have made our sleepless nights possible.

Thanks, The VMSperl group


README.vos - Perl for Stratus VOS

    • Multiple methods to build perl for VOS
    • Stratus POSIX Support
  • INSTALLING PERL IN VOS
    • Compiling Perl 5 on VOS
    • Installing Perl 5 on VOS
  • USING PERL IN VOS
    • Unimplemented Features of Perl on VOS
    • Restrictions of Perl on VOS
    • Handling of underflow and overflow
  • TEST STATUS
  • SUPPORT STATUS
  • AUTHOR
  • LAST UPDATE

NAME

README.vos - Perl for Stratus VOS

SYNOPSIS

This file contains notes for building perl on the Stratus VOS operating system. Perl is a scripting or macro language that is popular on many systems. See the perlbook manpage for a number of good books on Perl.

These are instructions for building Perl from source. Most people can simply download a pre-compiled distribution from the VOS anonymous FTP site. If you are running VOS Release 14.2.0 or earlier, download Perl from ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html If you are running VOS Release 14.3.0 or later, download Perl from ftp://ftp.stratus.com/pub/vos/posix/ga/ga.html Instructions for unbundling the Perl distribution file are at ftp://ftp.stratus.com/pub/vos/utility/utility.html

If you are running VOS Release 14.4.1 or later, you can obtain a pre-compiled, supported copy of perl by purchasing Release 2.0.1 (or later) of the VOS GNU C++ and GNU Tools product from Stratus Technologies.

Multiple methods to build perl for VOS

If you elect to build perl from its source code, you have several different ways that you can build perl. The method that you use depends on the version of VOS that you are using and on the architecture of your Stratus hardware platform.

  1. If you have a Stratus XA2000 (Motorola 68k-based) platform, you must build perl using the alpha version of VOS POSIX support and using the VOS Standard C Cross-compiler. You must build perl on VOS Release 14.1.0 (or later) on an XA/R or Continuum platform.

    This version of perl is properly called "miniperl" because it does not contain the complete perl functionality.

    You must build perl with the compile_perl.cm command macro found in the vos subdirectory.

  2. If you have a Stratus XA/R (Intel i860-based) platform, you must build perl using the alpha version of VOS POSIX support and using the VOS Standard C compiler or cross-compiler. You must build perl on VOS Release 14.1.0 (or later) on an XA/R or Continuum platform.

    This version of perl is properly called "miniperl" because it does not contain the complete perl functionality.

    You must build perl with the compile_perl.cm command macro found in the vos subdirectory.

  3. If you have a Stratus Continuum (PA-RISC-based) platform that is running a version of VOS earlier than VOS 14.3.0, you must build perl using the alpha version of VOS POSIX support and using the VOS Standard C compiler or cross-compiler. You must build perl on VOS Release 14.1.0 (or later) on an XA/R or Continuum platform.

    This version of perl is properly called "miniperl" because it does not contain the complete perl functionality.

    You must build perl with the compile_perl.cm command macro found in the vos subdirectory.

  4. If you have a Stratus Continuum (PA-RISC-based) platform that is running VOS Release 14.3.0 through VOS Release 14.4.1, you must build perl using the generally-available version of VOS POSIX support, and using either the VOS Standard C compiler or the VOS GNU C compiler. You must build perl on VOS Release 14.3.0 (or later) on a Continuum platform.

    This version of perl is properly called "miniperl" because it does not contain the complete perl functionality.

    You must build perl with the compile_perl.cm command macro found in the vos subdirectory.

  5. If you have a Stratus Continuum (PA-RISC-based) platform that is running VOS Release 14.5.0 or later, you can either use the previous method to build "miniperl" or you can build "full perl", which contains the complete functionality of perl. I strongly recommend that you build full perl. To build full perl, you must use the generally-available version of VOS POSIX support. You must use the VOS GNU C compiler and the VOS GNU C/C++ and GNU Tools Release 2.0.1 (or later) product. You must build full perl on VOS Release 14.5.0 (or later) on a Continuum platform.

    You must build full perl with the compile_full_perl.cm command macro found in the vos subdirectory.

Stratus POSIX Support

Note that there are two different implementations of POSIX.1 support on VOS. There is an alpha version of POSIX that is available from the Stratus anonymous ftp site ( ftp://ftp.stratus.com/pub/vos/posix/alpha/alpha.html ). There is a generally-available version of POSIX that comes with VOS Release 14.3.0 or higher. This port of POSIX will compile and bind with either version of POSIX.

Most of the Perl features should work on VOS regardless of which version of POSIX that you are using. However, the alpha version of POSIX is missing a number of key functions, and therefore any attempt by perl.pm to call the following unimplemented POSIX functions will result in an error message and an immediate and fatal call to the VOS debugger. They are "dup", "fork", and "waitpid". The lack of these functions prevents you from starting VOS commands and grabbing their output in perl. The workaround is to run the commands outside of perl, then have perl process the output file. These functions are all available in the generally-available version of POSIX.

INSTALLING PERL IN VOS

Compiling Perl 5 on VOS

Before you can build Perl 5 on VOS, you need to have or acquire the following additional items.

  1. The VOS Standard C Compiler (or the VOS Standard C Cross-Compiler) and the VOS C Runtime. If you are using the generally-available version of POSIX support, you may instead use the VOS GNU C/C++ Compiler. These are standard Stratus products.

  2. Either the VOS OS TCP/IP or STCP product set. If you are building with the alpha version of POSIX you need the OS TCP/IP product set. If you are building with the generally-available version of POSIX you need the STCP product set. These are standard Stratus products.

  3. Either the alpha or generally-available version of the VOS POSIX.1 environment.

    The alpha version of POSIX.1 support is available on the Stratus FTP site. Login anonymously to ftp.stratus.com and get the file /pub/vos/posix/alpha/posix.save.evf.gz in binary file-transfer mode. Or use the Uniform Resource Locator (URL) ftp://ftp.stratus.com/pub/vos/posix/alpha/posix.save.evf.gz from your web browser. Instructions for unbundling this file are at ftp://ftp.stratus.com/pub/vos/utility/utility.html This is NOT a standard Stratus product.

    In VOS Release 14.3.0, the generally-available version of POSIX.1 support is bundled with the VOS Standard C compiler (or Standard C Cross-Compiler). In VOS Release 14.4.0 or higher, it is also bundled with the VOS C Runtime. These are standard Stratus products.

  4. You must compile this version of Perl 5 on VOS Release 14.1.0 or higher because some of the perl source files contain more than 32,767 source lines. Due to VOS release-compatibility rules, this port of perl may not execute on VOS Release 12 or earlier.

  5. If you are using the generally-available version of VOS POSIX support, then you should also acquire the VOS GNU C/C++ Compiler and GNU Tools product. When perl is built with this version of POSIX support, it assumes that it can find "bash", "sed" and other POSIX-compatible commands in the directory /system/gnu_library/bin.

To build perl using the supplied VOS command macros, change to the "vos" subdirectory and type the command "compile_perl -processor X", where X is the processor type (mc68020, i80860, pa7100, pa8000) that you wish to use. Note that the generally-available version of POSIX.1 support is not available for the mc68020 or i80860 processors.

Use the "-version alpha" control argument to build perl with the alpha version of POSIX support, and use the "-version ga" control argument to build it with the generally-available version of POSIX. The default is "ga".

Use the "-compiler cc" control argument to build perl with the VOS Standard C compiler. Use the "-compiler gcc" control argument to build it with the GNU GCC compiler. The default is "cc".

You must have purchased the VOS Standard C Cross Compiler in order to compile perl for a processor type that is different from the processor type of the module.

Note that code compiled for the pa7100 processor type can execute on the PA7100, PA8000, PA8500 and PA8600 processors, and that code compiled for the pa8000 processor type can execute on the PA8000, PA8500 and PA8600 processors.

To build full perl using the supplied Configure script and makefiles, change to the "vos" subdirectory and type the command "compile_full_perl" or "start_process compile_full_perl". This will configure, build, and test perl.

Installing Perl 5 on VOS

  1. If you have built perl using the Configure script, ensure that you have modify permission to >system>ported and type

         gmake install

  2. If you have built perl using any of the other methods, type

         install_perl -processor PROCESSOR -name NAME

    where PROCESSOR is mc68020, i80860, pa7100, or pa8000, as appropriate, and NAME is perl or perl5, according to which name you wish to use.

    This command macro will install perl and all of its related files in the proper directories.

  3. While there are currently no architecture-specific extensions or modules distributed with perl, the following directories can be used to hold such files:

         >system>ported>lib>perl5>5.8.0>68k
     >system>ported>lib>perl5>5.8.0>860
     >system>ported>lib>perl5>5.8.0>7100
     >system>ported>lib>perl5>5.8.0>8000

  4. Site-specific perl extensions and modules can be installed in one of two places. Put architecture-independent files into:

         >system>ported>lib>perl5>site_perl>5.8.0

    Put site-specific architecture-dependent files into one of the following directories:

         >system>ported>lib>perl5>site_perl>5.8.0>68k
     >system>ported>lib>perl5>site_perl>5.8.0>860
     >system>ported>lib>perl5>site_perl>5.8.0>7100
     >system>ported>lib>perl5>site_perl>5.8.0>8000

  5. You can examine the @INC variable from within a perl program to see the order in which Perl searches these directories.

USING PERL IN VOS

Unimplemented Features of Perl on VOS

If perl is built with the alpha version of VOS POSIX.1 support and if it attempts to call an unimplemented VOS POSIX.1 function, it will print a fatal error message and enter the VOS debugger. This error is not recoverable. See vos_dummies.c for a list of the unimplemented POSIX.1 functions. To see what functions are unimplemented and what the error message looks like, compile and execute "test_vos_dummies.c".

Restrictions of Perl on VOS

This port of Perl version 5 to VOS prefers Unix-style, slash-separated pathnames over VOS-style greater-than-separated pathnames. VOS-style pathnames should work in most contexts, but if you have trouble, replace all greater-than characters by slash characters. Because the slash character is used as a pathname delimiter, Perl cannot process VOS pathnames containing a slash character in a directory or file name; these must be renamed.

This port of Perl also uses Unix-epoch date values internally. As long as you are dealing with ASCII character string representations of dates, this should not be an issue. The supported epoch is January 1, 1980 to January 17, 2038.

See the file pod/perlport.pod for more information about the VOS port of Perl.

Handling of underflow and overflow

Prior to VOS Release 14.7.0, VOS does not support automatically mapping overflowed floating-point values to +infinity, nor automatically mapping underflowed floating-point values to zero, unlike many other platforms. The Perl pack function has been modified to perform such mapping in software on VOS. Performing other floating-point computations that underflow or overflow will probably result in SIGFPE. Don't push your luck.

As of VOS Release 14.7.0, the VOS POSIX runtime sets up the PA-RISC hardware floating-point status register so that the overflow and underflow exceptions do not trap, but instead automatically convert the result to infinity or zero, as appropriate. As of this writing, there are still floating-point operations that can trap, for example, subtracting two infinite values. This is recorded as suggestion posix-1022, which is not yet fixed.

TEST STATUS

When Perl 5.8.3 is built using the native build process on VOS Release 14.7.0 and GNU C++/GNU Tools 2.0.2a, all but three attempted tests either pass or result in TODO (ignored) failures. The tests that fail are:

t/io/tell.t, test 28 t/op/pack.t, test 39 lib/Net/ing/t/450_service.t, test 8

SUPPORT STATUS

I'm offering this port "as is". You can ask me questions, but I can't guarantee I'll be able to answer them. There are some excellent books available on the Perl language; consult a book seller.

If you want a supported version of perl for VOS, purchase the VOS GNU C++ and GNU Tools Release 2.0.1 (or later) product from Stratus Technologies, along with a support contract (or from anyone else who will sell you support).

AUTHOR

Paul Green (Paul.Green@stratus.com)

LAST UPDATE

January 15, 2004


perlwin32 - Perl under Windows

    • Setting Up Perl on Win32
    • Building
    • Testing Perl on Win32
    • Installation of Perl on Win32
    • Usage Hints for Perl on Win32
    • Running Perl Scripts
    • Miscellaneous Things
  • BUGS AND CAVEATS
  • ACKNOWLEDGEMENTS
  • AUTHORS
  • SEE ALSO
  • HISTORY

NAME

perlwin32 - Perl under Windows

SYNOPSIS

These are instructions for building Perl under Windows 9x/NT/2000/XP on the Intel x86 and Itanium architectures.

DESCRIPTION

Before you start, you should glance through the README file found in the top-level directory to which the Perl distribution was extracted. Make sure you read and understand the terms under which this software is being distributed.

Also make sure you read BUGS AND CAVEATS below for the known limitations of this port.

The INSTALL file in the perl top-level has much information that is only relevant to people building Perl on Unix-like systems. In particular, you can safely ignore any information that talks about "Configure".

You may also want to look at two other options for building a perl that will work on Windows NT: the README.cygwin and README.os2 files, each of which give a different set of rules to build a Perl that will work on Win32 platforms. Those two methods will probably enable you to build a more Unix-compatible perl, but you will also need to download and use various other build-time and run-time support software described in those files.

This set of instructions is meant to describe a so-called "native" port of Perl to Win32 platforms. This includes both 32-bit and 64-bit Windows operating systems. The resulting Perl requires no additional software to run (other than what came with your operating system). Currently, this port is capable of using one of the following compilers on the Intel x86 architecture:

      Borland C++           version 5.02 or later
      Microsoft Visual C++  version 2.0 or later
      MinGW with gcc        gcc version 2.95.2 or later

The last of these is a high quality freeware compiler. Use version 3.2.x or later for the best results with this compiler.

The Borland C++ and Microsoft Visual C++ compilers are also now being given away free. The Borland compiler is available as "Borland C++ Compiler Free Command Line Tools" and is the same compiler that ships with the full "Borland C++ Builder" product. The Microsoft compiler is available as "Visual C++ Toolkit 2003", and also as part of the ".NET Framework SDK", and is the same compiler that ships with "Visual Studio .NET 2003 Professional".

This port can also be built on the Intel IA64 using:

      Microsoft Platform SDK    Nov 2001 (64-bit compiler and tools)

The MS Platform SDK can be downloaded from http://www.microsoft.com/.

This port fully supports MakeMaker (the set of modules that is used to build extensions to perl). Therefore, you should be able to build and install most extensions found in the CPAN sites. See Usage Hints for Perl on Win32 below for general hints about this.

Setting Up Perl on Win32

Make

You need a "make" program to build the sources. If you are using Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake will work. All other builds need dmake.

dmake is a freely available make that has very nice macro features and parallelability.

A port of dmake for Windows is available from:

    http://search.cpan.org/dist/dmake/

Fetch and install dmake somewhere on your path.

There exists a minor coexistence problem with dmake and Borland C++ compilers. Namely, if a distribution has C files named with mixed case letters, they will be compiled into appropriate .obj-files named with all lowercase letters, and every time dmake is invoked to bring files up to date, it will try to recompile such files again. For example, Tk distribution has a lot of such files, resulting in needless recompiles every time dmake is invoked. To avoid this, you may use the script "sync_ext.pl" after a successful build. It is available in the win32 subdirectory of the Perl source distribution.

Command Shell

Use the default "cmd" shell that comes with NT. Some versions of the popular 4DOS/NT shell have incompatibilities that may cause you trouble. If the build fails under that shell, try building again with the cmd shell.

The nmake Makefile also has known incompatibilities with the "command.com" shell that comes with Windows 9x. You will need to use dmake and makefile.mk to build under Windows 9x.

The surest way to build it is on Windows NT/2000/XP, using the cmd shell.

Make sure the path to the build directory does not contain spaces. The build usually works in this circumstance, but some tests will fail.

Borland C++

If you are using the Borland compiler, you will need dmake. (The make that Borland supplies is seriously crippled and will not work for MakeMaker builds.)

See Make above.

Microsoft Visual C++

The nmake that comes with Visual C++ will suffice for building. You will need to run the VCVARS32.BAT file, usually found somewhere like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin. This will set your build environment.

You can also use dmake to build using Visual C++; provided, however, you set OSRELEASE to "microsft" (or whatever the directory name under which the Visual C dmake configuration lives) in your environment and edit win32/config.vc to change "make=nmake" into "make=dmake". The latter step is only essential if you want to use dmake as your default make for building extensions using MakeMaker.

Microsoft Visual C++ Toolkit 2003

This free toolkit contains the same compiler and linker that ship with Visual Studio .NET 2003 Professional, but doesn't contain everything necessary to build Perl.

You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC SDK" components are required) for header files, libraries and rc.exe, and ".NET Framework SDK" for more libraries and nmake.exe. Note that the latter (which also includes the free compiler and linker) requires the ".NET Framework Redistributable" to be installed first. This can be downloaded and installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.

These packages can all be downloaded by searching in the Download Center at http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact links to these packages has proven a pointless task because the links keep on changing so often.)

Try to obtain the latest version of the Platform SDK. Sometimes these packages contain a particular Windows OS version in their name, but actually work on other OS versions too. For example, the "Windows Server 2003 SP1 Platform SDK" also runs on Windows XP SP2 and Windows 2000.

According to the download pages the Toolkit and the .NET Framework SDK are only supported on Windows 2000/XP/2003, so trying to use these tools on Windows 95/98/ME and even Windows NT probably won't work.

Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK. Setup your environment as follows (assuming default installation locations were chosen):

        SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;C:\Program Files\Microsoft SDK\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
        SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;C:\Program Files\Microsoft SDK\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
        SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;C:\Program Files\Microsoft SDK\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib

Several required files will still be missing:

  • cvtres.exe is required by link.exe when using a .res file. It is actually installed by the .NET Framework SDK, but into a location such as the following:

            C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322

    Copy it from there to C:\Program Files\Microsoft SDK\Bin

  • lib.exe is normally used to build libraries, but link.exe with the /lib option also works, so change win32/config.vc to use it instead:

    Change the line reading:

            ar='lib'

    to:

            ar='link /lib'

    It may also be useful to create a batch file called lib.bat in C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:

            @echo off
        link /lib %*

    for the benefit of any naughty C extension modules that you might want to build later which explicitly reference "lib" rather than taking their value from $Config{ar}.

  • setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV option is enabled). The Platform SDK supplies this object file in source form in C:\Program Files\Microsoft SDK\src\crt. Copy setargv.c, cruntime.h and internal.h from there to some temporary location and build setargv.obj using

            cl.exe /c /I. /D_CRTBLD setargv.c

    Then copy setargv.obj to C:\Program Files\Microsoft SDK\lib

    Alternatively, if you don't need perlglob.exe and don't need to enable the USE_SETARGV option then you can safely just remove all mention of $(GLOBEXE) from win32/Makefile and setargv.obj won't be required anyway.

Perl should now build using the win32/Makefile. You will need to edit that file to set

        CCTYPE = MSVC70FREE

and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.

Microsoft Platform SDK 64-bit Compiler

The nmake that comes with the Platform SDK will suffice for building Perl. Make sure you are building within one of the "Build Environment" shells available after you install the Platform SDK from the Start Menu.

MinGW release 3 with gcc

The latest release of MinGW at the time of writing is 3.1.0, which contains gcc-3.2.3. It can be downloaded here:

    http://www.mingw.org/

Perl also compiles with earlier releases of gcc (2.95.2 and up). See below for notes about using earlier versions of MinGW/gcc.

You also need dmake. See Make above on how to get it.

MinGW release 1 with gcc

The MinGW-1.1 bundle contains gcc-2.95.3.

Make sure you install the binaries that work with MSVCRT.DLL as indicated in the README for the GCC bundle. You may need to set up a few environment variables (usually ran from a batch file).

There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe released 7 November 1999:

  • It left out a fix for certain command line quotes. To fix this, be sure to download and install the file fixes/quote-fix-msvcrt.exe from the above ftp location.

  • The definition of the fpos_t type in stdio.h may be wrong. If your stdio.h has this problem, you will see an exception when running the test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from "long" to "long long" in the file i386-mingw32msvc/include/stdio.h, and rebuild.

A potentially simpler to install (but probably soon-to-be-outdated) bundle of the above package with the mentioned fixes already applied is available here:

    http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
    ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip

Building

  • Make sure you are in the "win32" subdirectory under the perl toplevel. This directory contains a "Makefile" that will work with versions of nmake that come with Visual C++ or the Platform SDK, and a dmake "makefile.mk" that will work for all supported compilers. The defaults in the dmake makefile are setup to build using MinGW/gcc.

  • Edit the makefile.mk (or Makefile, if you're using nmake) and change the values of INST_DRV and INST_TOP. You can also enable various build flags. These are explained in the makefiles.

    Note that it is generally not a good idea to try to build a perl with INST_DRV and INST_TOP set to a path that already exists from a previous build. In particular, this may cause problems with the lib/ExtUtils/t/Embed.t test, which attempts to build a test program and may end up building against the installed perl's lib/CORE directory rather than the one being tested.

    You will have to make sure that CCTYPE is set correctly and that CCHOME points to wherever you installed your compiler.

    The default value for CCHOME in the makefiles for Visual C++ may not be correct for some versions. Make sure the default exists and is valid.

    You may also need to comment out the DELAYLOAD = ... line in the Makefile if you're using VC++ 6.0 without the latest service pack and the linker reports an internal error.

    If you have either the source or a library that contains des_fcrypt(), enable the appropriate option in the makefile. A ready-to-use version of fcrypt.c, based on the version originally written by Eric Young at ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the distribution and CRYPT_SRC is set to use it. Alternatively, if you have built a library that contains des_fcrypt(), you can set CRYPT_LIB to point to the library name. Perl will also build without des_fcrypt(), but the crypt() builtin will fail at run time.

    If you want build some core extensions statically into perl's dll, specify them in the STATIC_EXT macro.

    Be sure to read the instructions near the top of the makefiles carefully.

  • Type "dmake" (or "nmake" if you are using that make).

    This should build everything. Specifically, it will create perl.exe, perl58.dll at the perl toplevel, and various other extension dll's under the lib\auto directory. If the build fails for any reason, make sure you have done the previous steps correctly.

Testing Perl on Win32

Type "dmake test" (or "nmake test"). This will run most of the tests from the testsuite (many tests will be skipped).

There should be no test failures when running under Windows NT/2000/XP. Many tests will fail under Windows 9x due to the inferior command shell.

Some test failures may occur if you use a command shell other than the native "cmd.exe", or if you are building from a path that contains spaces. So don't do that.

If you are running the tests from a emacs shell window, you may see failures in op/stat.t. Run "dmake test-notty" in that case.

If you're using the Borland compiler, you may see a failure in op/taint.t arising from the inability to find the Borland Runtime DLLs on the system default path. You will need to copy the DLLs reported by the messages from where Borland chose to install it, into the Windows system directory (usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.

If you're using Borland compiler versions 5.2 and below, you may run into problems finding the correct header files when building extensions. For example, building the "Tk" extension may fail because both perl and Tk contain a header file called "patchlevel.h". The latest Borland compiler (v5.5) is free of this misbehaviour, and it even supports an option -VI- for backward (bugward) compatibility for using the old Borland search algorithm to locate header files.

If you run the tests on a FAT partition, you may see some failures for link() related tests:

    Failed Test                     Stat Wstat Total Fail  Failed  List
    ../ext/IO/lib/IO/t/io_dup.t                    6    4  66.67%  2-5
    ../lib/File/Temp/t/mktemp.t                    9    1  11.11%  2
    ../lib/File/Temp/t/posix.t                     7    1  14.29%  3
    ../lib/File/Temp/t/security.t                 13    1   7.69%  2
    ../lib/File/Temp/t/tempfile.t                 20    2  10.00%  2 4
    comp/multiline.t                               6    2  33.33%  5-6
    io/dup.t                                       8    6  75.00%  2-7
    op/write.t                                    47    7  14.89%  1-3 6 9-11

Testing on NTFS avoids these errors.

Furthermore, you should make sure that during make test you do not have any GNU tool packages in your path: some toolkits like Unixutils include some tools (type for instance) which override the Windows ones and makes tests fail. Remove them from your path while testing to avoid these errors.

Please report any other failures as described under BUGS AND CAVEATS.

Installation of Perl on Win32

Type "dmake install" (or "nmake install"). This will put the newly built perl and the libraries under whatever INST_TOP points to in the Makefile. It will also install the pod documentation under $INST_TOP\$INST_VER\lib\pod and HTML versions of the same under $INST_TOP\$INST_VER\lib\pod\html.

To use the Perl you just installed you will need to add a new entry to your PATH environment variable: $INST_TOP\bin, e.g.

    set PATH=c:\perl\bin;%PATH%

If you opted to uncomment INST_VER and INST_ARCH in the makefile then the installation structure is a little more complicated and you will need to add two new PATH components instead: $INST_TOP\$INST_VER\bin and $INST_TOP\$INST_VER\bin\$ARCHNAME, e.g.

    set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%

Usage Hints for Perl on Win32

Environment Variables

The installation paths that you set during the build get compiled into perl, so you don't have to do anything additional to start using that perl (except add its location to your PATH variable).

If you put extensions in unusual places, you can set PERL5LIB to a list of paths separated by semicolons where you want perl to look for libraries. Look for descriptions of other environment variables you can set in the perlrun manpage.

You can also control the shell that perl uses to run system() and backtick commands via PERL5SHELL. See the perlrun manpage.

Perl does not depend on the registry, but it can look up certain default values if you choose to put them there. Perl attempts to read entries from HKEY_CURRENT_USER\Software\Perl and HKEY_LOCAL_MACHINE\Software\Perl. Entries in the former override entries in the latter. One or more of the following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:

    lib-$]              version-specific standard library path to add to @INC
    lib                 standard library path to add to @INC
    sitelib-$]          version-specific site library path to add to @INC
    sitelib             site library path to add to @INC
    vendorlib-$]        version-specific vendor library path to add to @INC
    vendorlib           vendor library path to add to @INC
    PERL*               fallback for all %ENV lookups that begin with "PERL"

Note the $] in the above is not literal. Substitute whatever version of perl you want to honor that entry, e.g. 5.6.0. Paths must be separated with semicolons, as usual on win32.

File Globbing

By default, perl handles file globbing using the File::Glob extension, which provides portable globbing.

If you want perl to use globbing that emulates the quirks of DOS filename conventions, you might want to consider using File::DosGlob to override the internal glob() implementation. See the File::DosGlob manpage for details.

Using perl from the command line

If you are accustomed to using perl from various command-line shells found in UNIX environments, you will be less than pleased with what Windows offers by way of a command shell.

The crucial thing to understand about the Windows environment is that the command line you type in is processed twice before Perl sees it. First, your command shell (usually CMD.EXE on Windows NT, and COMMAND.COM on Windows 9x) preprocesses the command line, to handle redirection, environment variable expansion, and location of the executable to run. Then, the perl executable splits the remaining command line into individual arguments, using the C runtime library upon which Perl was built.

It is particularly important to note that neither the shell nor the C runtime do any wildcard expansions of command-line arguments (so wildcards need not be quoted). Also, the quoting behaviours of the shell and the C runtime are rudimentary at best (and may, if you are using a non-standard shell, be inconsistent). The only (useful) quote character is the double quote ("). It can be used to protect spaces and other special characters in arguments.

The Windows NT documentation has almost no description of how the quoting rules are implemented, but here are some general observations based on experiments: The C runtime breaks arguments at spaces and passes them to programs in argc/argv. Double quotes can be used to prevent arguments with spaces in them from being split up. You can put a double quote in an argument by escaping it with a backslash and enclosing the whole argument within double quotes. The backslash and the pair of double quotes surrounding the argument will be stripped by the C runtime.

The file redirection characters "<", ">", and "|" can be quoted by double quotes (although there are suggestions that this may not always be true). Single quotes are not treated as quotes by the shell or the C runtime, they don't get stripped by the shell (just to make this type of quoting completely useless). The caret "^" has also been observed to behave as a quoting character, but this appears to be a shell feature, and the caret is not stripped from the command line, so Perl still sees it (and the C runtime phase does not treat the caret as a quote character).

Here are some examples of usage of the "cmd" shell:

This prints two doublequotes:

    perl -e "print '\"\"' "

This does the same:

    perl -e "print \"\\\"\\\"\" "

This prints "bar" and writes "foo" to the file "blurch":

    perl -e "print 'foo'; print STDERR 'bar'" > blurch

This prints "foo" ("bar" disappears into nowhereland):

    perl -e "print 'foo'; print STDERR 'bar'" 2> nul

This prints "bar" and writes "foo" into the file "blurch":

    perl -e "print 'foo'; print STDERR 'bar'" 1> blurch

This pipes "foo" to the "less" pager and prints "bar" on the console:

    perl -e "print 'foo'; print STDERR 'bar'" | less

This pipes "foo\nbar\n" to the less pager:

    perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less

This pipes "foo" to the pager and writes "bar" in the file "blurch":

    perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less

Discovering the usefulness of the "command.com" shell on Windows 9x is left as an exercise to the reader :)

One particularly pernicious problem with the 4NT command shell for Windows NT is that it (nearly) always treats a % character as indicating that environment variable expansion is needed. Under this shell, it is therefore important to always double any % characters which you want Perl to see (for example, for hash variables), even when they are quoted.

Building Extensions

The Comprehensive Perl Archive Network (CPAN) offers a wealth of extensions, some of which require a C compiler to build. Look in http://www.cpan.org/ for more information on CPAN.

Note that not all of the extensions available from CPAN may work in the Win32 environment; you should check the information at http://testers.cpan.org/ before investing too much effort into porting modules that don't readily build.

Most extensions (whether they require a C compiler or not) can be built, tested and installed with the standard mantra:

    perl Makefile.PL
    $MAKE
    $MAKE test
    $MAKE install

where $MAKE is whatever 'make' program you have configured perl to use. Use "perl -V:make" to find out what this is. Some extensions may not provide a testsuite (so "$MAKE test" may not do anything or fail), but most serious ones do.

It is important that you use a supported 'make' program, and ensure Config.pm knows about it. If you don't have nmake, you can either get dmake from the location mentioned earlier or get an old version of nmake reportedly available from:

 http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe

Another option is to use the make written in Perl, available from CPAN.

    http://www.cpan.org/modules/by-module/Make/

You may also use dmake. See Make above on how to get it.

Note that MakeMaker actually emits makefiles with different syntax depending on what 'make' it thinks you are using. Therefore, it is important that one of the following values appears in Config.pm:

    make='nmake'        # MakeMaker emits nmake syntax
    make='dmake'        # MakeMaker emits dmake syntax
    any other value     # MakeMaker emits generic make syntax
                            (e.g GNU make, or Perl make)

If the value doesn't match the 'make' program you want to use, edit Config.pm to fix it.

If a module implements XSUBs, you will need one of the supported C compilers. You must make sure you have set up the environment for the compiler for command-line compilation.

If a module does not build for some reason, look carefully for why it failed, and report problems to the module author. If it looks like the extension building support is at fault, report that with full details of how the build failed using the perlbug utility.

Command-line Wildcard Expansion

The default command shells on DOS descendant operating systems (such as they are) usually do not expand wildcard arguments supplied to programs. They consider it the application's job to handle that. This is commonly achieved by linking the application (in our case, perl) with startup code that the C runtime libraries usually provide. However, doing that results in incompatible perl versions (since the behavior of the argv expansion code differs depending on the compiler, and it is even buggy on some compilers). Besides, it may be a source of frustration if you use such a perl binary with an alternate shell that *does* expand wildcards.

Instead, the following solution works rather well. The nice things about it are 1) you can start using it right away; 2) it is more powerful, because it will do the right thing with a pattern like */*/*.c; 3) you can decide whether you do/don't want to use it; and 4) you can extend the method to add any customizations (or even entirely different kinds of wildcard expansion).

        C:\> copy con c:\perl\lib\Wild.pm
        # Wild.pm - emulate shell @ARGV expansion on shells that don't
        use File::DosGlob;
        @ARGV = map {
                      my @g = File::DosGlob::glob($_) if /[*?]/;
                      @g ? @g : $_;
                    } @ARGV;
        1;
        ^Z
        C:\> set PERL5OPT=-MWild
        C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
        p4view/perl/perl.c
        p4view/perl/perlio.c
        p4view/perl/perly.c
        perl5.005/win32/perlglob.c
        perl5.005/win32/perllib.c
        perl5.005/win32/perlglob.c
        perl5.005/win32/perllib.c
        perl5.005/win32/perlglob.c
        perl5.005/win32/perllib.c

Note there are two distinct steps there: 1) You'll have to create Wild.pm and put it in your perl lib directory. 2) You'll need to set the PERL5OPT environment variable. If you want argv expansion to be the default, just set PERL5OPT in your default startup environment.

If you are using the Visual C compiler, you can get the C runtime's command line wildcard expansion built into perl binary. The resulting binary will always expand unquoted command lines, which may not be what you want if you use a shell that does that for you. The expansion done is also somewhat less powerful than the approach suggested above.

Win32 Specific Extensions

A number of extensions specific to the Win32 platform are available from CPAN. You may find that many of these extensions are meant to be used under the Activeware port of Perl, which used to be the only native port for the Win32 platform. Since the Activeware port does not have adequate support for Perl's extension building tools, these extensions typically do not support those tools either and, therefore, cannot be built using the generic steps shown in the previous section.

To ensure smooth transitioning of existing code that uses the ActiveState port, there is a bundle of Win32 extensions that contains all of the ActiveState extensions and several other Win32 extensions from CPAN in source form, along with many added bugfixes, and with MakeMaker support. The latest version of this bundle is available at:

    http://search.cpan.org/dist/libwin32/

See the README in that distribution for building and installation instructions.

Notes on 64-bit Windows

Windows .NET Server supports the LLP64 data model on the Intel Itanium architecture.

The LLP64 data model is different from the LP64 data model that is the norm on 64-bit Unix platforms. In the former, int and long are both 32-bit data types, while pointers are 64 bits wide. In addition, there is a separate 64-bit wide integral type, __int64. In contrast, the LP64 data model that is pervasive on Unix platforms provides int as the 32-bit type, while both the long type and pointers are of 64-bit precision. Note that both models provide for 64-bits of addressability.

64-bit Windows running on Itanium is capable of running 32-bit x86 binaries transparently. This means that you could use a 32-bit build of Perl on a 64-bit system. Given this, why would one want to build a 64-bit build of Perl? Here are some reasons why you would bother:

  • A 64-bit native application will run much more efficiently on Itanium hardware.

  • There is no 2GB limit on process size.

  • Perl automatically provides large file support when built under 64-bit Windows.

  • Embedding Perl inside a 64-bit application.

Running Perl Scripts

Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to indicate to the OS that it should execute the file using perl. Win32 has no comparable means to indicate arbitrary files are executables.

Instead, all available methods to execute plain text files on Win32 rely on the file "extension". There are three methods to use this to execute perl scripts:

  1. There is a facility called "file extension associations" that will work in Windows NT 4.0. This can be manipulated via the two commands "assoc" and "ftype" that come standard with Windows NT 4.0. Type "ftype /?" for a complete example of how to set this up for perl scripts (Say what? You thought Windows NT wasn't perl-ready? :).

  2. Since file associations don't work everywhere, and there are reportedly bugs with file associations where it does work, the old method of wrapping the perl script to make it look like a regular batch file to the OS, may be used. The install process makes available the "pl2bat.bat" script which can be used to wrap perl scripts into batch files. For example:

            pl2bat foo.pl

    will create the file "FOO.BAT". Note "pl2bat" strips any .pl suffix and adds a .bat suffix to the generated file.

    If you use the 4DOS/NT or similar command shell, note that "pl2bat" uses the "%*" variable in the generated batch file to refer to all the command line arguments, so you may need to make sure that construct works in batch files. As of this writing, 4DOS/NT users will need a "ParameterChar = *" statement in their 4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT startup file to enable this to work.

  3. Using "pl2bat" has a few problems: the file name gets changed, so scripts that rely on $0 to find what they must do may not run properly; running "pl2bat" replicates the contents of the original script, and so this process can be maintenance intensive if the originals get updated often. A different approach that avoids both problems is possible.

    A script called "runperl.bat" is available that can be copied to any filename (along with the .bat suffix). For example, if you call it "foo.bat", it will run the file "foo" when it is executed. Since you can run batch files on Win32 platforms simply by typing the name (without the extension), this effectively runs the file "foo", when you type either "foo" or "foo.bat". With this method, "foo.bat" can even be in a different location than the file "foo", as long as "foo" is available somewhere on the PATH. If your scripts are on a filesystem that allows symbolic links, you can even avoid copying "runperl.bat".

    Here's a diversion: copy "runperl.bat" to "runperl", and type "runperl". Explain the observed behavior, or lack thereof. :) Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH

Miscellaneous Things

A full set of HTML documentation is installed, so you should be able to use it if you have a web browser installed on your system.

perldoc is also a useful tool for browsing information contained in the documentation, especially in conjunction with a pager like less (recent versions of which have Win32 support). You may have to set the PAGER environment variable to use a specific pager. "perldoc -f foo" will print information about the perl operator "foo".

One common mistake when using this port with a GUI library like Tk is assuming that Perl's normal behavior of opening a command-line window will go away. This isn't the case. If you want to start a copy of perl without opening a command-line window, use the wperl executable built during the installation process. Usage is exactly the same as normal perl on Win32, except that options like -h don't work (since they need a command-line window to print to).

If you find bugs in perl, you can run perlbug to create a bug report (you may have to send it manually if perlbug cannot find a mailer on your system).

BUGS AND CAVEATS

Norton AntiVirus interferes with the build process, particularly if set to "AutoProtect, All Files, when Opened". Unlike large applications the perl build process opens and modifies a lot of files. Having the the AntiVirus scan each and every one slows build the process significantly. Worse, with PERLIO=stdio the build process fails with peculiar messages as the virus checker interacts badly with miniperl.exe writing configure files (it seems to either catch file part written and treat it as suspicious, or virus checker may have it "locked" in a way which inhibits miniperl updating it). The build does complete with

   set PERLIO=perlio

but that may be just luck. Other AntiVirus software may have similar issues.

Some of the built-in functions do not act exactly as documented in the perlfunc manpage, and a few are not implemented at all. To avoid surprises, particularly if you have had prior exposure to Perl in other operating environments or if you intend to write code that will be portable to other environments, see the perlport manpage for a reasonably definitive list of these differences.

Not all extensions available from CPAN may build or work properly in the Win32 environment. See Building Extensions.

Most socket() related calls are supported, but they may not behave as on Unix platforms. See the perlport manpage for the full list. Perl requires Winsock2 to be installed on the system. If you're running Win95, you can download Winsock upgrade from here:

http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp

Later OS versions already include Winsock2 support.

Signal handling may not behave as on Unix platforms (where it doesn't exactly "behave", either :). For instance, calling die() or exit() from signal handlers will cause an exception, since most implementations of signal() on Win32 are severely crippled. Thus, signals may work only for simple things like setting a flag variable in the handler. Using signals under this port should currently be considered unsupported.

Please send detailed descriptions of any problems and solutions that you may find to <perlbug@perl.org>, along with the output produced by perl -V.

ACKNOWLEDGEMENTS

The use of a camel with the topic of Perl is a trademark of O'Reilly and Associates, Inc. Used with permission.

AUTHORS

Gary Ng <71564.1743@CompuServe.COM>
Gurusamy Sarathy <gsar@activestate.com>
Nick Ing-Simmons <nick@ing-simmons.net>
Jan Dubois <jand@activestate.com>
Steve Hay <steve.hay@uk.radan.com>

This document is maintained by Jan Dubois.

SEE ALSO

the perl manpage

HISTORY

This port was originally contributed by Gary Ng around 5.003_24, and borrowed from the Hip Communications port that was available at the time. Various people have made numerous and sundry hacks since then.

Borland support was added in 5.004_01 (Gurusamy Sarathy).

GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).

Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).

Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).

Win9x support was added in 5.6 (Benjamin Stuhl).

Support for 64-bit Windows added in 5.8 (ActiveState Corp).

Last updated: 30 September 2005


perlpod - the Plain Old Documentation format

    • Ordinary Paragraph
    • Verbatim Paragraph
    • Command Paragraph
    • Formatting Codes
    • The Intent
    • Embedding Pods in Perl Modules
    • Hints for Writing Pod
  • SEE ALSO
  • AUTHOR

NAME

perlpod - the Plain Old Documentation format

DESCRIPTION

Pod is a simple-to-use markup language used for writing documentation for Perl, Perl programs, and Perl modules.

Translators are available for converting Pod to various formats like plain text, HTML, man pages, and more.

Pod markup consists of three basic kinds of paragraphs: ordinary, verbatim, and command.

Ordinary Paragraph

Most paragraphs in your documentation will be ordinary blocks of text, like this one. You can simply type in your text without any markup whatsoever, and with just a blank line before and after. When it gets formatted, it will undergo minimal formatting, like being rewrapped, probably put into a proportionally spaced font, and maybe even justified.

You can use formatting codes in ordinary paragraphs, for bold, italic, code-style, hyperlinks, and more. Such codes are explained in the "Formatting Codes" section, below.

Verbatim Paragraph

Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped.

A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.

Command Paragraph

A command paragraph is used for special treatment of whole chunks of text, usually as headings or parts of lists.

All command paragraphs (which are typically only one line long) start with "=", followed by an identifier, followed by arbitrary text that the command can use however it pleases. Currently recognized commands are

    =pod
    =head1 Heading Text
    =head2 Heading Text
    =head3 Heading Text
    =head4 Heading Text
    =over indentlevel
    =item stuff
    =back
    =begin format
    =end format
    =for format text...
    =encoding type
    =cut

To explain them each in detail:

=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text

Head1 through head4 produce headings, head1 being the highest level. The text in the rest of this paragraph is the content of the heading. For example:

  =head2 Object Attributes

The text "Object Attributes" comprises the heading there. (Note that head3 and head4 are recent additions, not supported in older Pod translators.) The text in these heading commands can use formatting codes, as seen here:

  =head2 Possible Values for C<$/>

Such commands are explained in the "Formatting Codes" section, below.

=over indentlevel
=item stuff...
=back

Item, over, and back require a little more explanation: "=over" starts a region specifically for the generation of a list using "=item" commands, or for indenting (groups of) normal paragraphs. At the end of your list, use "=back" to end it. The indentlevel option to "=over" indicates how far over to indent, generally in ems (where one em is the width of an "M" in the document's base font) or roughly comparable units; if there is no indentlevel option, it defaults to four. (And some formatters may just ignore whatever indentlevel you provide.) In the stuff in =item stuff..., you may use formatting codes, as seen here:

  =item Using C<$|> to Control Buffering

Such commands are explained in the "Formatting Codes" section, below.

Note also that there are some basic rules to using "=over" ... "=back" regions:

  • Don't use "=item"s outside of an "=over" ... "=back" region.

  • The first thing after the "=over" command should be an "=item", unless there aren't going to be any items at all in this "=over" ... "=back" region.

  • Don't put "=headn" commands inside an "=over" ... "=back" region.

  • And perhaps most importantly, keep the items consistent: either use "=item *" for all of them, to produce bullets; or use "=item 1.", "=item 2.", etc., to produce numbered lists; or use "=item foo", "=item bar", etc. -- namely, things that look nothing like bullets or numbers.

    If you start with bullets or numbers, stick with them, as formatters use the first "=item" type to decide how to format the list.

=cut

To end a Pod block, use a blank line, then a line beginning with "=cut", and a blank line after it. This lets Perl (and the Pod formatter) know that this is where Perl code is resuming. (The blank line before the "=cut" is not technically necessary, but many older Pod processors require it.)

=pod

The "=pod" command by itself doesn't do much of anything, but it signals to Perl (and Pod formatters) that a Pod block starts here. A Pod block starts with any command paragraph, so a "=pod" command is usually used just when you want to start a Pod block with an ordinary paragraph or a verbatim paragraph. For example:

  =item stuff()
  This function does stuff.
  =cut
  sub stuff {
    ...
  }

  =pod
  Remember to check its return value, as in:
    stuff() || die "Couldn't do stuff!";

  =cut
=begin formatname
=end formatname
=for formatname text...

For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.

A command "=begin formatname", some paragraphs, and a command "=end formatname", mean that the text/data inbetween is meant for formatters that understand the special format called formatname. For example,

  =begin html
  <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>
  =end html

The command "=for formatname text..." specifies that the remainder of just this paragraph (starting right after formatname) is in that special format.

  =for html <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>

This means the same thing as the above "=begin html" ... "=end html" region.

That is, with "=for", you can have only one paragraph's worth of text (i.e., the text in "=foo targetname text..."), but with "=begin targetname" ... "=end targetname", you can have any amount of stuff inbetween. (Note that there still must be a blank line after the "=begin" command and a blank line before the "=end" command.

Here are some examples of how to use these:

  =begin html
  <br>Figure 1.<br><IMG SRC="figure1.png"><br>
  =end html
  =begin text
    ---------------
    |  foo        |
    |        bar  |
    ---------------
  ^^^^ Figure 1. ^^^^
  =end text

Some format names that formatters currently are known to accept include "roff", "man", "latex", "tex", "text", and "html". (Some formatters will treat some of these as synonyms.)

A format name of "comment" is common for just making notes (presumably to yourself) that won't appear in any formatted version of the Pod document:

  =for comment
  Make sure that all the available options are documented!

Some formatnames will require a leading colon (as in "=for :formatname", or "=begin :formatname" ... "=end :formatname"), to signal that the text is not raw data, but instead is Pod text (i.e., possibly containing formatting codes) that's just not for normal formatting (e.g., may not be a normal-use paragraph, but might be for formatting as a footnote).

=encoding encodingname

This command is used for declaring the encoding of a document. Most users won't need this; but if your encoding isn't US-ASCII or Latin-1, then put a =encoding encodingname command early in the document so that pod formatters will know how to decode the document. For encodingname, use a name recognized by the the Encode::Supported manpage module. Examples:

  =encoding utf8
  =encoding koi8-r

  =encoding ShiftJIS

  =encoding big5

And don't forget, when using any command, that the command lasts up until the end of its paragraph, not its line. So in the examples below, you can see that every command needs the blank line after it, to end its paragraph.

Some examples of lists include:

  =over
  =item *
  First item
  =item *
  Second item
  =back
  =over
  =item Foo()
  Description of Foo function
  =item Bar()
  Description of Bar function
  =back

Formatting Codes

In ordinary paragraphs and in some command paragraphs, various formatting codes (a.k.a. "interior sequences") can be used:

I<text> -- italic text <> >>

Used for emphasis ("be I<careful!>") and parameters ("redo I<LABEL>")

B<text> -- bold text <> >>

Used for switches ("perl's B<-n> switch"), programs ("some systems provide a B<chfn> for that"), emphasis ("be B<careful!>"), and so on ("and that feature is known as B<autovivification>").

C<code> -- code text <> >>

Renders code in a typewriter font, or gives some other indication that this represents program text ("C<gmtime($^T)>") or some other form of computerese ("C<drwxr-xr-x>").

L<name> -- a hyperlink <> >>

There are various syntaxes, listed below. In the syntaxes given, text, name, and section cannot contain the characters '/' and '|'; and any '<' or '>' should be matched.

  • L<name>

    Link to a Perl manual page (e.g., L<Net::Ping>). Note that name should not contain spaces. This syntax is also occasionally used for references to UNIX man pages, as in L<crontab(5)>.

  • L<name/"sec"> or L<name/sec>

    Link to a section in other manual page. E.g., L<perlsyn/"For Loops">

  • L</"sec"> or L</sec> or L<"sec">

    Link to a section in this manual page. E.g., L</"Object Methods">

A section is started by the named heading or item. For example, L<perlvar/$.> or L<perlvar/"$."> both link to the section started by "=item $." in perlvar. And L<perlsyn/For Loops> or L<perlsyn/"For Loops"> both link to the section started by "=head2 For Loops" in perlsyn.

To control what text is used for display, you use "L<text|...>", as in:

  • L<text|name>

    Link this text to that manual page. E.g., L<Perl Error Messages|perldiag>

  • L<text|name/"sec"> or L<text|name/sec>

    Link this text to that section in that manual page. E.g., L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"E<gt>

  • L<text|/"sec"> or L<text|/sec> or L<text|"sec">

    Link this text to that section in this manual page. E.g., L<the various attributes|/"Member Data">

Or you can link to a web page:

  • L<scheme:...>

    Links to an absolute URL. For example, L<http://www.perl.org/>. But note that there is no corresponding L<text|scheme:...> syntax, for various reasons.

E<escape> -- a character escape <> >>

Very similar to HTML/XML &foo; "entity references":

  • E<lt> -- a literal < (less than)

  • E<gt> -- a literal > (greater than)

  • E<verbar> -- a literal | (vertical bar)

  • E<sol> = a literal / (solidus)

    The above four are optional except in other formatting codes, notably L<...>, and when preceded by a capital letter.

  • E<htmlname>

    Some non-numeric HTML entity name, such as E<eacute>, meaning the same thing as &eacute; in HTML -- i.e., a lowercase e with an acute (/-shaped) accent.

  • E<number>

    The ASCII/Latin-1/Unicode character with that number. A leading "0x" means that number is hex, as in E<0x201E>. A leading "0" means that number is octal, as in E<075>. Otherwise number is interpreted as being in decimal, as in E<181>.

    Note that older Pod formatters might not recognize octal or hex numeric escapes, and that many formatters cannot reliably render characters above 255. (Some formatters may even have to use compromised renderings of Latin-1 characters, like rendering E<eacute> as just a plain "e".)

F<filename> -- used for filenames <> >>

Typically displayed in italics. Example: "F<.cshrc>"

S<text> -- text contains non-breaking spaces <> >>

This means that the words in text should not be broken across lines. Example: S<$x ? $y : $z>.

X<topic name> -- an index entry <> >>

This is ignored by most formatters, but some may use it for building indexes. It always renders as empty-string. Example: X<absolutizing relative URLs>

Z<> -- a null (zero-effect) formatting code <> >>

This is rarely used. It's one way to get around using an E<...> code sometimes. For example, instead of "NE<lt>3" (for "N<3") you could write "NZ<><3" (the "Z<>" breaks up the "N" and the "<" so they can't be considered the part of a (fictitious) "N<...>" code.

Most of the time, you will need only a single set of angle brackets to delimit the beginning and end of formatting codes. However, sometimes you will want to put a real right angle bracket (a greater-than sign, '>') inside of a formatting code. This is particularly common when using a formatting code to provide a different font-type for a snippet of code. As with all things in Perl, there is more than one way to do it. One way is to simply escape the closing bracket using an E code:

    C<$a E<lt>=E<gt> $b>

This will produce: "$a <=> $b"

A more readable, and perhaps more "plain" way is to use an alternate set of delimiters that doesn't require a single ">" to be escaped. With the Pod formatters that are standard starting with perl5.5.660, doubled angle brackets ("<<" and ">>") may be used if and only if there is whitespace right after the opening delimiter and whitespace right before the closing delimiter! For example, the following will do the trick:

    C<< $a <=> $b >>

In fact, you can use as many repeated angle-brackets as you like so long as you have the same number of them in the opening and closing delimiters, and make sure that whitespace immediately follows the last '<' of the opening delimiter, and immediately precedes the first '>' of the closing delimiter. (The whitespace is ignored.) So the following will also work:

    C<<< $a <=> $b >>>
    C<<<<  $a <=> $b     >>>>

And they all mean exactly the same as this:

    C<$a E<lt>=E<gt> $b>

As a further example, this means that if you wanted to put these bits of code in C (code) style:

    open(X, ">>thing.dat") || die $!
    $foo->bar();

you could do it like so:

    C<<< open(X, ">>thing.dat") || die $! >>>
    C<< $foo->bar(); >>

which is presumably easier to read than the old way:

    C<open(X, "E<gt>E<gt>thing.dat") || die $!>
    C<$foo-E<gt>bar();>

This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), and any other pod2xxx or Pod::Xxxx translators that use Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.

The Intent

The intent is simplicity of use, not power of expression. Paragraphs 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, or Esc Q in my version of emacs). I wanted the translator to always leave the ' and ` and " quotes alone, 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 monospace font.

The Pod format is not necessarily sufficient for writing a book. Pod is just meant to be an idiot-proof common source for nroff, HTML, TeX, and other markup languages, as used for online documentation. Translators exist for pod2text, pod2html, pod2man (that's for nroff(1) and troff(1)), pod2latex, and pod2fm. Various others are available in CPAN.

Embedding Pods in Perl Modules

You can embed Pod documentation in your Perl modules and scripts. Start your documentation with an empty line, a "=head1" command at the beginning, and end it with a "=cut" command and an empty line. Perl will ignore the Pod text. See any of the supplied library modules for examples. If you're going to put your Pod 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 command.

  __END__
  =head1 NAME
  Time::Local - efficiently compute time from local and GMT time

Without that empty line before the "=head1", many translators wouldn't have recognized the "=head1" as starting a Pod block.

Hints for Writing Pod

  • The podchecker command is provided for checking Pod syntax for errors and warnings. For example, it checks for completely blank lines in Pod blocks and for unknown commands and formatting codes. You should still also pass your document through one or more translators and proofread the result, or print out the result and proofread that. Some of the problems found may be bugs in the translators, which you may or may not wish to work around.

  • If you're more familiar with writing in HTML than with writing in Pod, you can try your hand at writing documentation in simple HTML, and converting it to Pod with the experimental Pod::HTML2Pod module, (available in CPAN), and looking at the resulting code. The experimental Pod::PXML module in CPAN might also be useful.

  • Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line. Having something like this:

     # - - - - - - - - - - - -
 =item $firecracker->boom()
     This noisily detonates the firecracker object.
 =cut
 sub boom {
 ...

    ...will make such Pod translators completely fail to see the Pod block at all.

    Instead, have it like this:

     # - - - - - - - - - - - -

     =item $firecracker->boom()
     This noisily detonates the firecracker object.
     =cut
     sub boom {
 ...

  • Some older Pod translators require paragraphs (including command paragraphs like "=head2 Functions") to be separated by completely empty lines. If you have an apparently empty line with some spaces on it, this might not count as a separator for those translators, and that could cause odd formatting.

  • Older translators might add wording around an L<> link, so that L<Foo::Bar> may become "the Foo::Bar manpage", for example. So you shouldn't write things like the L<foo> documentation, if you want the translated document to read sensibly -- instead write the L<Foo::Bar|Foo::Bar> documentation or L<the Foo::Bar documentation|Foo::Bar>, to control how the link comes out.

  • Going past the 70th column in a verbatim block might be ungracefully wrapped by some formatters.

SEE ALSO

the perlpodspec manpage, PODs: Embedded Documentation in the perlsyn manpage, the perlnewmod manpage, the perldoc manpage, pod2html, pod2man, podchecker.

AUTHOR

Larry Wall, Sean M. Burke


perlpodspec - Plain Old Documentation: format specification and notes

  • Pod Definitions
  • Pod Commands
  • Pod Formatting Codes
  • Notes on Implementing Pod Processors
  • About L<...> Codes
  • About =over...=back Regions
  • About Data Paragraphs and "=begin/=end" Regions
  • SEE ALSO
  • AUTHOR

NAME

perlpodspec - Plain Old Documentation: format specification and notes

DESCRIPTION

This document is detailed notes on the Pod markup language. Most people will only have to read perlpod to know how to write in Pod, but this document may answer some incidental questions to do with parsing and rendering Pod.

In this document, "must" / "must not", "should" / "should not", and "may" have their conventional (cf. RFC 2119) meanings: "X must do Y" means that if X doesn't do Y, it's against this specification, and should really be fixed. "X should do Y" means that it's recommended, but X may fail to do Y, if there's a good reason. "X may do Y" is merely a note that X can do Y at will (although it is up to the reader to detect any connotation of "and I think it would be nice if X did Y" versus "it wouldn't really bother me if X did Y").

Notably, when I say "the parser should do Y", the parser may fail to do Y, if the calling application explicitly requests that the parser not do Y. I often phrase this as "the parser should, by default, do Y." This doesn't require the parser to provide an option for turning off whatever feature Y is (like expanding tabs in verbatim paragraphs), although it implicates that such an option may be provided.

Pod Definitions

Pod is embedded in files, typically Perl source files -- although you can write a file that's nothing but Pod.

A line in a file consists of zero or more non-newline characters, terminated by either a newline or the end of the file.

A newline sequence is usually a platform-dependent concept, but Pod parsers should understand it to mean any of CR (ASCII 13), LF (ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in addition to any other system-specific meaning. The first CR/CRLF/LF sequence in the file may be used as the basis for identifying the newline sequence for parsing the rest of the file.

A blank line is a line consisting entirely of zero or more spaces (ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file. A non-blank line is a line containing one or more characters other than space or tab (and terminated by a newline or end-of-file).

(Note: Many older Pod parsers did not accept a line consisting of spaces/tabs and then a newline as a blank line -- the only lines they considered blank were lines consisting of no characters at all, terminated by a newline.)

Whitespace is used in this document as a blanket term for spaces, tabs, and newline sequences. (By itself, this term usually refers to literal whitespace. That is, sequences of whitespace characters in Pod source, as opposed to "E<32>", which is a formatting code that denotes a whitespace character.)

A Pod parser is a module meant for parsing Pod (regardless of whether this involves calling callbacks or building a parse tree or directly formatting it). A Pod formatter (or Pod translator) is a module or program that converts Pod to some other format (HTML, plaintext, TeX, PostScript, RTF). A Pod processor might be a formatter or translator, or might be a program that does something else with the Pod (like wordcounting it, scanning for index points, etc.).

Pod content is contained in Pod blocks. A Pod block starts with a line that matches <m/\A=[a-zA-Z]/>, and continues up to the next line that matches m/\A=cut/ -- or up to the end of the file, if there is no m/\A=cut/ line.

Within a Pod block, there are Pod paragraphs. A Pod paragraph consists of non-blank lines of text, separated by one or more blank lines.

For purposes of Pod processing, there are four types of paragraphs in a Pod block:

  • A command paragraph (also called a "directive"). The first line of this paragraph must match m/\A=[a-zA-Z]/. Command paragraphs are typically one line, as in:

      =head1 NOTES
      =item *

    But they may span several (non-blank) lines:

      =for comment
  Hm, I wonder what it would look like if
  you tried to write a BNF for Pod from this.
      =head3 Dr. Strangelove, or: How I Learned to
  Stop Worrying and Love the Bomb

    Some command paragraphs allow formatting codes in their content (i.e., after the part that matches m/\A=[a-zA-Z]\S*\s*/), as in:

      =head1 Did You Remember to C<use strict;>?

    In other words, the Pod processing handler for "head1" will apply the same processing to "Did You Remember to C<use strict;>?" that it would to an ordinary paragraph -- i.e., formatting codes (like "C<...>") are parsed and presumably formatted appropriately, and whitespace in the form of literal spaces and/or tabs is not significant.

  • A verbatim paragraph. The first line of this paragraph must be a literal space or tab, and this paragraph must not be inside a "=begin identifier", ... "=end identifier" sequence unless "identifier" begins with a colon (":"). That is, if a paragraph starts with a literal space or tab, but is inside a "=begin identifier", ... "=end identifier" region, then it's a data paragraph, unless "identifier" begins with a colon.

    Whitespace is significant in verbatim paragraphs (although, in processing, tabs are probably expanded).

  • An ordinary paragraph. A paragraph is an ordinary paragraph if its first line matches neither m/\A=[a-zA-Z]/ nor m/\A[ \t]/, and if it's not inside a "=begin identifier", ... "=end identifier" sequence unless "identifier" begins with a colon (":").

  • A data paragraph. This is a paragraph that is inside a "=begin identifier" ... "=end identifier" sequence where "identifier" does not begin with a literal colon (":"). In some sense, a data paragraph is not part of Pod at all (i.e., effectively it's "out-of-band"), since it's not subject to most kinds of Pod parsing; but it is specified here, since Pod parsers need to be able to call an event for it, or store it in some form in a parse tree, or at least just parse around it.

For example: consider the following paragraphs:

  # <- that's the 0th column

  =head1 Foo
  Stuff
    $foo->bar
  =cut

Here, "=head1 Foo" and "=cut" are command paragraphs because the first line of each matches m/\A=[a-zA-Z]/. "[space][space]$foo->bar" is a verbatim paragraph, because its first line starts with a literal whitespace character (and there's no "=begin"..."=end" region around).

The "=begin identifier" ... "=end identifier" commands stop paragraphs that they surround from being parsed as data or verbatim paragraphs, if identifier doesn't begin with a colon. This is discussed in detail in the section About Data Paragraphs and "=begin/=end" Regions.

Pod Commands

This section is intended to supplement and clarify the discussion in Command Paragraph in the perlpod manpage. These are the currently recognized Pod commands:

"=head1", "=head2", "=head3", "=head4"

This command indicates that the text in the remainder of the paragraph is a heading. That text may contain formatting codes. Examples:

  =head1 Object Attributes
  =head3 What B<Not> to Do!
"=pod"

This command indicates that this paragraph begins a Pod block. (If we are already in the middle of a Pod block, this command has no effect at all.) If there is any text in this command paragraph after "=pod", it must be ignored. Examples:

  =pod
  This is a plain Pod paragraph.
  =pod This text is ignored.
"=cut"

This command indicates that this line is the end of this previously started Pod block. If there is any text after "=cut" on the line, it must be ignored. Examples:

  =cut
  =cut The documentation ends here.
  =cut
  # This is the first line of program text.
  sub foo { # This is the second.

It is an error to try to start a Pod block with a "=cut" command. In that case, the Pod processor must halt parsing of the input file, and must by default emit a warning.

"=over"

This command indicates that this is the start of a list/indent region. If there is any text following the "=over", it must consist of only a nonzero positive numeral. The semantics of this numeral is explained in the About =over...=back Regions section, further below. Formatting codes are not expanded. Examples:

  =over 3
  =over 3.5
  =over
"=item"

This command indicates that an item in a list begins here. Formatting codes are processed. The semantics of the (optional) text in the remainder of this paragraph are explained in the About =over...=back Regions section, further below. Examples:

  =item
  =item *
  =item      *
  =item 14
  =item   3.
  =item C<< $thing->stuff(I<dodad>) >>
  =item For transporting us beyond seas to be tried for pretended
  offenses
  =item He is at this time transporting large armies of foreign
  mercenaries to complete the works of death, desolation and
  tyranny, already begun with circumstances of cruelty and perfidy
  scarcely paralleled in the most barbarous ages, and totally
  unworthy the head of a civilized nation.
"=back"

This command indicates that this is the end of the region begun by the most recent "=over" command. It permits no text after the "=back" command.

"=begin formatname"

This marks the following paragraphs (until the matching "=end formatname") as being for some special kind of processing. Unless "formatname" begins with a colon, the contained non-command paragraphs are data paragraphs. But if "formatname" does begin with a colon, then non-command paragraphs are ordinary paragraphs or data paragraphs. This is discussed in detail in the section About Data Paragraphs and "=begin/=end" Regions.

It is advised that formatnames match the regexp m/\A:?[-a-zA-Z0-9_]+\z/. Implementors should anticipate future expansion in the semantics and syntax of the first parameter to "=begin"/"=end"/"=for".

"=end formatname"

This marks the end of the region opened by the matching "=begin formatname" region. If "formatname" is not the formatname of the most recent open "=begin formatname" region, then this is an error, and must generate an error message. This is discussed in detail in the section About Data Paragraphs and "=begin/=end" Regions.

"=for formatname text..."

This is synonymous with:

     =begin formatname
     text...
     =end formatname

That is, it creates a region consisting of a single paragraph; that paragraph is to be treated as a normal paragraph if "formatname" begins with a ":"; if "formatname" doesn't begin with a colon, then "text..." will constitute a data paragraph. There is no way to use "=for formatname text..." to express "text..." as a verbatim paragraph.

"=encoding encodingname"

This command, which should occur early in the document (at least before any non-US-ASCII data!), declares that this document is encoded in the encoding encodingname, which must be an encoding name that the Encoding manpage recognizes. (Encoding's list of supported encodings, in the Encoding::Supported manpage, is useful here.) If the Pod parser cannot decode the declared encoding, it should emit a warning and may abort parsing the document altogether.

A document having more than one "=encoding" line should be considered an error. Pod processors may silently tolerate this if the not-first "=encoding" lines are just duplicates of the first one (e.g., if there's a "=use utf8" line, and later on another "=use utf8" line). But Pod processors should complain if there are contradictory "=encoding" lines in the same document (e.g., if there is a "=encoding utf8" early in the document and "=encoding big5" later). Pod processors that recognize BOMs may also complain if they see an "=encoding" line that contradicts the BOM (e.g., if a document with a UTF-16LE BOM has an "=encoding shiftjis" line).

If a Pod processor sees any command other than the ones listed above (like "=head", or "=haed1", or "=stuff", or "=cuttlefish", or "=w123"), that processor must by default treat this as an error. It must not process the paragraph beginning with that command, must by default warn of this as an error, and may abort the parse. A Pod parser may allow a way for particular applications to add to the above list of known commands, and to stipulate, for each additional command, whether formatting codes should be processed.

Future versions of this specification may add additional commands.

Pod Formatting Codes

(Note that in previous drafts of this document and of perlpod, formatting codes were referred to as "interior sequences", and this term may still be found in the documentation for Pod parsers, and in error messages from Pod processors.)

There are two syntaxes for formatting codes:

  • A formatting code starts with a capital letter (just US-ASCII [A-Z]) followed by a "<", any number of characters, and ending with the first matching ">". Examples:

        That's what I<you> think!
        What's C<dump()> for?
        X<C<chmod> and C<unlink()> Under Different Operating Systems>

  • A formatting code starts with a capital letter (just US-ASCII [A-Z]) followed by two or more "<"'s, one or more whitespace characters, any number of characters, one or more whitespace characters, and ending with the first matching sequence of two or more ">"'s, where the number of ">"'s equals the number of "<"'s in the opening of this formatting code. Examples:

        That's what I<< you >> think!
        C<<< open(X, ">>thing.dat") || die $! >>>
        B<< $foo->bar(); >>

    With this syntax, the whitespace character(s) after the "C<<<" and before the ">>" (or whatever letter) are not renderable -- they do not signify whitespace, are merely part of the formatting codes themselves. That is, these are all synonymous:

        C<thing>
    C<< thing >>
    C<<           thing     >>
    C<<<   thing >>>
    C<<<<
    thing
               >>>>

    and so on.

In parsing Pod, a notably tricky part is the correct parsing of (potentially nested!) formatting codes. Implementors should consult the code in the parse_text routine in Pod::Parser as an example of a correct implementation.

I<text> -- italic text

See the brief discussion in Formatting Codes in the perlpod manpage.

B<text> -- bold text

See the brief discussion in Formatting Codes in the perlpod manpage.

C<code> -- code text

See the brief discussion in Formatting Codes in the perlpod manpage.

F<filename> -- style for filenames

See the brief discussion in Formatting Codes in the perlpod manpage.

X<topic name> -- an index entry

See the brief discussion in Formatting Codes in the perlpod manpage.

This code is unusual in that most formatters completely discard this code and its content. Other formatters will render it with invisible codes that can be used in building an index of the current document.

Z<> -- a null (zero-effect) formatting code

Discussed briefly in Formatting Codes in the perlpod manpage.

This code is unusual is that it should have no content. That is, a processor may complain if it sees Z<potatoes>. Whether or not it complains, the potatoes text should ignored.

L<name> -- a hyperlink

The complicated syntaxes of this code are discussed at length in Formatting Codes in the perlpod manpage, and implementation details are discussed below, in About L<...> Codes. Parsing the contents of L<content> is tricky. Notably, the content has to be checked for whether it looks like a URL, or whether it has to be split on literal "|" and/or "/" (in the right order!), and so on, before E<...> codes are resolved.

E<escape> -- a character escape

See Formatting Codes in the perlpod manpage, and several points in Notes on Implementing Pod Processors.

S<text> -- text contains non-breaking spaces

This formatting code is syntactically simple, but semantically complex. What it means is that each space in the printable content of this code signifies a non-breaking space.

Consider:

    C<$x ? $y    :  $z>
    S<C<$x ? $y     :  $z>>

Both signify the monospace (c[ode] style) text consisting of "$x", one space, "?", one space, ":", one space, "$z". The difference is that in the latter, with the S code, those spaces are not "normal" spaces, but instead are non-breaking spaces.

If a Pod processor sees any formatting code other than the ones listed above (as in "N<...>", or "Q<...>", etc.), that processor must by default treat this as an error. A Pod parser may allow a way for particular applications to add to the above list of known formatting codes; a Pod parser might even allow a way to stipulate, for each additional command, whether it requires some form of special processing, as L<...> does.

Future versions of this specification may add additional formatting codes.

Historical note: A few older Pod processors would not see a ">" as closing a "C<" code, if the ">" was immediately preceded by a "-". This was so that this:

    C<$foo->bar>

would parse as equivalent to this:

    C<$foo-E<gt>bar>

instead of as equivalent to a "C" formatting code containing only "$foo-", and then a "bar>" outside the "C" formatting code. This problem has since been solved by the addition of syntaxes like this:

    C<< $foo->bar >>

Compliant parsers must not treat "->" as special.

Formatting codes absolutely cannot span paragraphs. If a code is opened in one paragraph, and no closing code is found by the end of that paragraph, the Pod parser must close that formatting code, and should complain (as in "Unterminated I code in the paragraph starting at line 123: 'Time objects are not...'"). So these two paragraphs:

  I<I told you not to do this!
  Don't make me say it again!>

...must not be parsed as two paragraphs in italics (with the I code starting in one paragraph and starting in another.) Instead, the first paragraph should generate a warning, but that aside, the above code must parse as if it were:

  I<I told you not to do this!>
  Don't make me say it again!E<gt>

(In SGMLish jargon, all Pod commands are like block-level elements, whereas all Pod formatting codes are like inline-level elements.)

Notes on Implementing Pod Processors

The following is a long section of miscellaneous requirements and suggestions to do with Pod processing.

  • Pod formatters should tolerate lines in verbatim blocks that are of any length, even if that means having to break them (possibly several times, for very long lines) to avoid text running off the side of the page. Pod formatters may warn of such line-breaking. Such warnings are particularly appropriate for lines are over 100 characters long, which are usually not intentional.

  • Pod parsers must recognize all of the three well-known newline formats: CR, LF, and CRLF. See perlport.

  • Pod parsers should accept input lines that are of any length.

  • Since Perl recognizes a Unicode Byte Order Mark at the start of files as signaling that the file is Unicode encoded as in UTF-16 (whether big-endian or little-endian) or UTF-8, Pod parsers should do the same. Otherwise, the character encoding should be understood as being UTF-8 if the first highbit byte sequence in the file seems valid as a UTF-8 sequence, or otherwise as Latin-1.

    Future versions of this specification may specify how Pod can accept other encodings. Presumably treatment of other encodings in Pod parsing would be as in XML parsing: whatever the encoding declared by a particular Pod file, content is to be stored in memory as Unicode characters.

  • The well known Unicode Byte Order Marks are as follows: if the file begins with the two literal byte values 0xFE 0xFF, this is the BOM for big-endian UTF-16. If the file begins with the two literal byte value 0xFF 0xFE, this is the BOM for little-endian UTF-16. If the file begins with the three literal byte values 0xEF 0xBB 0xBF, this is the BOM for UTF-8.

  • A naive but sufficient heuristic for testing the first highbit byte-sequence in a BOM-less file (whether in code or in Pod!), to see whether that sequence is valid as UTF-8 (RFC 2279) is to check whether that the first byte in the sequence is in the range 0xC0 - 0xFD and whether the next byte is in the range 0x80 - 0xBF. If so, the parser may conclude that this file is in UTF-8, and all highbit sequences in the file should be assumed to be UTF-8. Otherwise the parser should treat the file as being in Latin-1. In the unlikely circumstance that the first highbit sequence in a truly non-UTF-8 file happens to appear to be UTF-8, one can cater to our heuristic (as well as any more intelligent heuristic) by prefacing that line with a comment line containing a highbit sequence that is clearly not valid as UTF-8. A line consisting of simply "#", an e-acute, and any non-highbit byte, is sufficient to establish this file's encoding.

  • This document's requirements and suggestions about encodings do not apply to Pod processors running on non-ASCII platforms, notably EBCDIC platforms.

  • Pod processors must treat a "=for [label] [content...]" paragraph as meaning the same thing as a "=begin [label]" paragraph, content, and an "=end [label]" paragraph. (The parser may conflate these two constructs, or may leave them distinct, in the expectation that the formatter will nevertheless treat them the same.)

  • When rendering Pod to a format that allows comments (i.e., to nearly any format other than plaintext), a Pod formatter must insert comment text identifying its name and version number, and the name and version numbers of any modules it might be using to process the Pod. Minimal examples:

      %% POD::Pod2PS v3.14159, using POD::Parser v1.92
      <!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
      {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}

      .\" Pod::Man version 3.14159, using POD::Parser version 1.92

    Formatters may also insert additional comments, including: the release date of the Pod formatter program, the contact address for the author(s) of the formatter, the current time, the name of input file, the formatting options in effect, version of Perl used, etc.

    Formatters may also choose to note errors/warnings as comments, besides or instead of emitting them otherwise (as in messages to STDERR, or dieing).

  • Pod parsers may emit warnings or error messages ("Unknown E code E<zslig>!") to STDERR (whether through printing to STDERR, or warning/carping, or dieing/croaking), but must allow suppressing all such STDERR output, and instead allow an option for reporting errors/warnings in some other way, whether by triggering a callback, or noting errors in some attribute of the document object, or some similarly unobtrusive mechanism -- or even by appending a "Pod Errors" section to the end of the parsed form of the document.

  • In cases of exceptionally aberrant documents, Pod parsers may abort the parse. Even then, using dieing/croaking is to be avoided; where possible, the parser library may simply close the input file and add text like "*** Formatting Aborted ***" to the end of the (partial) in-memory document.

  • In paragraphs where formatting codes (like E<...>, B<...>) are understood (i.e., not verbatim paragraphs, but including ordinary paragraphs, and command paragraphs that produce renderable text, like "=head1"), literal whitespace should generally be considered "insignificant", in that one literal space has the same meaning as any (nonzero) number of literal spaces, literal newlines, and literal tabs (as long as this produces no blank lines, since those would terminate the paragraph). Pod parsers should compact literal whitespace in each processed paragraph, but may provide an option for overriding this (since some processing tasks do not require it), or may follow additional special rules (for example, specially treating period-space-space or period-newline sequences).

  • Pod parsers should not, by default, try to coerce apostrophe (') and quote (") into smart quotes (little 9's, 66's, 99's, etc), nor try to turn backtick (`) into anything else but a single backtick character (distinct from an openquote character!), nor "--" into anything but two minus signs. They must never do any of those things to text in C<...> formatting codes, and never ever to text in verbatim paragraphs.

  • When rendering Pod to a format that has two kinds of hyphens (-), one that's a non-breaking hyphen, and another that's a breakable hyphen (as in "object-oriented", which can be split across lines as "object-", newline, "oriented"), formatters are encouraged to generally translate "-" to non-breaking hyphen, but may apply heuristics to convert some of these to breaking hyphens.

  • Pod formatters should make reasonable efforts to keep words of Perl code from being broken across lines. For example, "Foo::Bar" in some formatting systems is seen as eligible for being broken across lines as "Foo::" newline "Bar" or even "Foo::-" newline "Bar". This should be avoided where possible, either by disabling all line-breaking in mid-word, or by wrapping particular words with internal punctuation in "don't break this across lines" codes (which in some formats may not be a single code, but might be a matter of inserting non-breaking zero-width spaces between every pair of characters in a word.)

  • Pod parsers should, by default, expand tabs in verbatim paragraphs as they are processed, before passing them to the formatter or other processor. Parsers may also allow an option for overriding this.

  • Pod parsers should, by default, remove newlines from the end of ordinary and verbatim paragraphs before passing them to the formatter. For example, while the paragraph you're reading now could be considered, in Pod source, to end with (and contain) the newline(s) that end it, it should be processed as ending with (and containing) the period character that ends this sentence.

  • Pod parsers, when reporting errors, should make some effort to report an approximate line number ("Nested E<>'s in Paragraph #52, near line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph number ("Nested E<>'s in Paragraph #52 of Thing/Foo.pm!"). Where this is problematic, the paragraph number should at least be accompanied by an excerpt from the paragraph ("Nested E<>'s in Paragraph #52 of Thing/Foo.pm, which begins 'Read/write accessor for the C<interest rate> attribute...'").

  • Pod parsers, when processing a series of verbatim paragraphs one after another, should consider them to be one large verbatim paragraph that happens to contain blank lines. I.e., these two lines, which have a blank line between them:

            use Foo;

            print Foo->VERSION

    should be unified into one paragraph ("\tuse Foo;\n\n\tprint Foo->VERSION") before being passed to the formatter or other processor. Parsers may also allow an option for overriding this.

    While this might be too cumbersome to implement in event-based Pod parsers, it is straightforward for parsers that return parse trees.

  • Pod formatters, where feasible, are advised to avoid splitting short verbatim paragraphs (under twelve lines, say) across pages.

  • Pod parsers must treat a line with only spaces and/or tabs on it as a "blank line" such as separates paragraphs. (Some older parsers recognized only two adjacent newlines as a "blank line" but would not recognize a newline, a space, and a newline, as a blank line. This is noncompliant behavior.)

  • Authors of Pod formatters/processors should make every effort to avoid writing their own Pod parser. There are already several in CPAN, with a wide range of interface styles -- and one of them, Pod::Parser, comes with modern versions of Perl.

  • Characters in Pod documents may be conveyed either as literals, or by number in E<n> codes, or by an equivalent mnemonic, as in E<eacute> which is exactly equivalent to E<233>.

    Characters in the range 32-126 refer to those well known US-ASCII characters (also defined there by Unicode, with the same meaning), which all Pod formatters must render faithfully. Characters in the ranges 0-31 and 127-159 should not be used (neither as literals, nor as E<number> codes), except for the literal byte-sequences for newline (13, 13 10, or 10), and tab (9).

    Characters in the range 160-255 refer to Latin-1 characters (also defined there by Unicode, with the same meaning). Characters above 255 should be understood to refer to Unicode characters.

  • Be warned that some formatters cannot reliably render characters outside 32-126; and many are able to handle 32-126 and 160-255, but nothing above 255.

  • Besides the well-known "E<lt>" and "E<gt>" codes for less-than and greater-than, Pod parsers must understand "E<sol>" for "/" (solidus, slash), and "E<verbar>" for "|" (vertical bar, pipe). Pod parsers should also understand "E<lchevron>" and "E<rchevron>" as legacy codes for characters 171 and 187, i.e., "left-pointing double angle quotation mark" = "left pointing guillemet" and "right-pointing double angle quotation mark" = "right pointing guillemet". (These look like little "<<" and ">>", and they are now preferably expressed with the HTML/XHTML codes "E<laquo>" and "E<raquo>".)

  • Pod parsers should understand all "E<html>" codes as defined in the entity declarations in the most recent XHTML specification at www.W3.org. Pod parsers must understand at least the entities that define characters in the range 160-255 (Latin-1). Pod parsers, when faced with some unknown "E<identifier>" code, shouldn't simply replace it with nullstring (by default, at least), but may pass it through as a string consisting of the literal characters E, less-than, identifier, greater-than. Or Pod parsers may offer the alternative option of processing such unknown "E<identifier>" codes by firing an event especially for such codes, or by adding a special node-type to the in-memory document tree. Such "E<identifier>" may have special meaning to some processors, or some processors may choose to add them to a special error report.

  • Pod parsers must also support the XHTML codes "E<quot>" for character 34 (doublequote, "), "E<amp>" for character 38 (ampersand, &), and "E<apos>" for character 39 (apostrophe, ').

  • Note that in all cases of "E<whatever>", whatever (whether an htmlname, or a number in any base) must consist only of alphanumeric characters -- that is, whatever must watch m/\A\w+\z/. So "E< 0 1 2 3 >" is invalid, because it contains spaces, which aren't alphanumeric characters. This presumably does not need special treatment by a Pod processor; " 0 1 2 3 " doesn't look like a number in any base, so it would presumably be looked up in the table of HTML-like names. Since there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ", this will be treated as an error. However, Pod processors may treat "E< 0 1 2 3 >" or "E<e-acute>" as syntactically invalid, potentially earning a different error message than the error message (or warning, or event) generated by a merely unknown (but theoretically valid) htmlname, as in "E<qacute>" [sic]. However, Pod parsers are not required to make this distinction.

  • Note that E<number> must not be interpreted as simply "codepoint number in the current/native character set". It always means only "the character represented by codepoint number in Unicode." (This is identical to the semantics of &#number; in XML.)

    This will likely require many formatters to have tables mapping from treatable Unicode codepoints (such as the "\xE9" for the e-acute character) to the escape sequences or codes necessary for conveying such sequences in the target output format. A converter to *roff would, for example know that "\xE9" (whether conveyed literally, or via a E<...> sequence) is to be conveyed as "e\\*'". Similarly, a program rendering Pod in a Mac OS application window, would presumably need to know that "\xE9" maps to codepoint 142 in MacRoman encoding that (at time of writing) is native for Mac OS. Such Unicode2whatever mappings are presumably already widely available for common output formats. (Such mappings may be incomplete! Implementers are not expected to bend over backwards in an attempt to render Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any of the other weird things that Unicode can encode.) And if a Pod document uses a character not found in such a mapping, the formatter should consider it an unrenderable character.

  • If, surprisingly, the implementor of a Pod formatter can't find a satisfactory pre-existing table mapping from Unicode characters to escapes in the target format (e.g., a decent table of Unicode characters to *roff escapes), it will be necessary to build such a table. If you are in this circumstance, you should begin with the characters in the range 0x00A0 - 0x00FF, which is mostly the heavily used accented characters. Then proceed (as patience permits and fastidiousness compels) through the characters that the (X)HTML standards groups judged important enough to merit mnemonics for. These are declared in the (X)HTML specifications at the www.W3.org site. At time of writing (September 2001), the most recent entity declaration files are:

      http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
  http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
  http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

    Then you can progress through any remaining notable Unicode characters in the range 0x2000-0x204D (consult the character tables at www.unicode.org), and whatever else strikes your fancy. For example, in xhtml-symbol.ent, there is the entry:

      <!ENTITY infin    "&#8734;"> <!-- infinity, U+221E ISOtech -->

    While the mapping "infin" to the character "\x{221E}" will (hopefully) have been already handled by the Pod parser, the presence of the character in this file means that it's reasonably important enough to include in a formatter's table that maps from notable Unicode characters to the codes necessary for rendering them. So for a Unicode-to-*roff mapping, for example, this would merit the entry:

      "\x{221E}" => '\(in',

    It is eagerly hoped that in the future, increasing numbers of formats (and formatters) will support Unicode characters directly (as (X)HTML does with &infin;, &#8734;, or &#x221E;), reducing the need for idiosyncratic mappings of Unicode-to-my_escapes.

  • It is up to individual Pod formatter to display good judgment when confronted with an unrenderable character (which is distinct from an unknown E<thing> sequence that the parser couldn't resolve to anything, renderable or not). It is good practice to map Latin letters with diacritics (like "E<eacute>"/"E<233>") to the corresponding unaccented US-ASCII letters (like a simple character 101, "e"), but clearly this is often not feasible, and an unrenderable character may be represented as "?", or the like. In attempting a sane fallback (as from E<233> to "e"), Pod formatters may use the %Latin1Code_to_fallback table in Pod::Escapes, or Text::Unidecode, if available.

    For example, this Pod text:

      magic is enabled if you set C<$Currency> to 'E<euro>'.

    may be rendered as: "magic is enabled if you set $Currency to '?'" or as "magic is enabled if you set $Currency to '[euro]'", or as "magic is enabled if you set $Currency to '[x20AC]', etc.

    A Pod formatter may also note, in a comment or warning, a list of what unrenderable characters were encountered.

  • E<...> may freely appear in any formatting code (other than in another E<...> or in an Z<>). That is, "X<The E<euro>1,000,000 Solution>" is valid, as is "L<The E<euro>1,000,000 Solution|Million::Euros>".

  • Some Pod formatters output to formats that implement non-breaking spaces as an individual character (which I'll call "NBSP"), and others output to formats that implement non-breaking spaces just as spaces wrapped in a "don't break this across lines" code. Note that at the level of Pod, both sorts of codes can occur: Pod can contain a NBSP character (whether as a literal, or as a "E<160>" or "E<nbsp>" code); and Pod can contain "S<foo I<bar> baz>" codes, where "mere spaces" (character 32) in such codes are taken to represent non-breaking spaces. Pod parsers should consider supporting the optional parsing of "S<foo I<bar> baz>" as if it were "fooNBSPI<bar>NBSPbaz", and, going the other way, the optional parsing of groups of words joined by NBSP's as if each group were in a S<...> code, so that formatters may use the representation that maps best to what the output format demands.

  • Some processors may find that the S<...> code is easiest to implement by replacing each space in the parse tree under the content of the S, with an NBSP. But note: the replacement should apply not to spaces in all text, but only to spaces in printable text. (This distinction may or may not be evident in the particular tree/event model implemented by the Pod parser.) For example, consider this unusual case:

       S<L</Autoloaded Functions>>

    This means that the space in the middle of the visible link text must not be broken across lines. In other words, it's the same as this:

       L<"AutoloadedE<160>Functions"/Autoloaded Functions>

    However, a misapplied space-to-NBSP replacement could (wrongly) produce something equivalent to this:

       L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>

    ...which is almost definitely not going to work as a hyperlink (assuming this formatter outputs a format supporting hypertext).

    Formatters may choose to just not support the S format code, especially in cases where the output format simply has no NBSP character/code and no code for "don't break this stuff across lines".

  • Besides the NBSP character discussed above, implementors are reminded of the existence of the other "special" character in Latin-1, the "soft hyphen" character, also known as "discretionary hyphen", i.e. E<173> = E<0xAD> = E<shy>). This character expresses an optional hyphenation point. That is, it normally renders as nothing, but may render as a "-" if a formatter breaks the word at that point. Pod formatters should, as appropriate, do one of the following: 1) render this with a code with the same meaning (e.g., "\-" in RTF), 2) pass it through in the expectation that the formatter understands this character as such, or 3) delete it.

    For example:

      sigE<shy>action
  manuE<shy>script
  JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi

    These signal to a formatter that if it is to hyphenate "sigaction" or "manuscript", then it should be done as "sig-[linebreak]action" or "manu-[linebreak]script" (and if it doesn't hyphenate it, then the E<shy> doesn't show up at all). And if it is to hyphenate "Jarkko" and/or "Hietaniemi", it can do so only at the points where there is a E<shy> code.

    In practice, it is anticipated that this character will not be used often, but formatters should either support it, or delete it.

  • If you think that you want to add a new command to Pod (like, say, a "=biblio" command), consider whether you could get the same effect with a for or begin/end sequence: "=for biblio ..." or "=begin biblio" ... "=end biblio". Pod processors that don't understand "=for biblio", etc, will simply ignore it, whereas they may complain loudly if they see "=biblio".

  • Throughout this document, "Pod" has been the preferred spelling for the name of the documentation format. One may also use "POD" or "pod". For the documentation that is (typically) in the Pod format, you may use "pod", or "Pod", or "POD". Understanding these distinctions is useful; but obsessing over how to spell them, usually is not.

About L<...> Codes

As you can tell from a glance at perlpod, the L<...> code is the most complex of the Pod formatting codes. The points below will hopefully clarify what it means and how processors should deal with it.

  • In parsing an L<...> code, Pod parsers must distinguish at least four attributes:

    First:

    The link-text. If there is none, this must be undef. (E.g., in "L<Perl Functions|perlfunc>", the link-text is "Perl Functions". In "L<Time::HiRes>" and even "L<|Time::HiRes>", there is no link text. Note that link text may contain formatting.)

    • Second:

    The possibly inferred link-text -- i.e., if there was no real link text, then this is the text that we'll infer in its place. (E.g., for "L<Getopt::Std>", the inferred link text is "Getopt::Std".)

    Third:

    The name or URL, or undef if none. (E.g., in "L<Perl Functions|perlfunc>", the name -- also sometimes called the page -- is "perlfunc". In "L</CAVEATS>", the name is undef.)

    Fourth:

    The section (AKA "item" in older perlpods), or undef if none. E.g., in DESCRIPTION in the Getopt::Std manpage, "DESCRIPTION" is the section. (Note that this is not the same as a manpage section like the "5" in "man 5 crontab". "Section Foo" in the Pod sense means the part of the text that's introduced by the heading or item whose text is "Foo".)

    Pod parsers may also note additional attributes including:

    Fifth:

    A flag for whether item 3 (if present) is a URL (like "http://lists.perl.org" is), in which case there should be no section attribute; a Pod name (like "perldoc" and "Getopt::Std" are); or possibly a man page name (like "crontab(5)" is).

    Sixth:

    The raw original L<...> content, before text is split on "|", "/", etc, and before E<...> codes are expanded.

    (The above were numbered only for concise reference below. It is not a requirement that these be passed as an actual list or array.)

    For example:

      L<Foo::Bar>
    =>  undef,                          # link text
        "Foo::Bar",                     # possibly inferred link text
        "Foo::Bar",                     # name
        undef,                          # section
        'pod',                          # what sort of link
        "Foo::Bar"                      # original content
      L<Perlport's section on NL's|perlport/Newlines>
    =>  "Perlport's section on NL's",   # link text
        "Perlport's section on NL's",   # possibly inferred link text
        "perlport",                     # name
        "Newlines",                     # section
        'pod',                          # what sort of link
        "Perlport's section on NL's|perlport/Newlines" # orig. content
      L<perlport/Newlines>
    =>  undef,                          # link text
        '"Newlines" in perlport',       # possibly inferred link text
        "perlport",                     # name
        "Newlines",                     # section
        'pod',                          # what sort of link
        "perlport/Newlines"             # original content
      L<crontab(5)/"DESCRIPTION">
    =>  undef,                          # link text
        '"DESCRIPTION" in crontab(5)',  # possibly inferred link text
        "crontab(5)",                   # name
        "DESCRIPTION",                  # section
        'man',                          # what sort of link
        'crontab(5)/"DESCRIPTION"'      # original content
      L</Object Attributes>
    =>  undef,                          # link text
        '"Object Attributes"',          # possibly inferred link text
        undef,                          # name
        "Object Attributes",            # section
        'pod',                          # what sort of link
        "/Object Attributes"            # original content
      L<http://www.perl.org/>;
    =>  undef,                          # link text
        "http://www.perl.org/";,         # possibly inferred link text
        "http://www.perl.org/";,         # name
        undef,                          # section
        'url',                          # what sort of link
        "http://www.perl.org/";          # original content

    Note that you can distinguish URL-links from anything else by the fact that they match m/\A\w+:[^:\s]\S*\z/. So L<http://www.perl.com> is a URL, but L<HTTP::Response> isn't.

  • In case of L<...> codes with no "text|" part in them, older formatters have exhibited great variation in actually displaying the link or cross reference. For example, L<crontab(5)> would render as "the crontab(5) manpage", or "in the crontab(5) manpage" or just "crontab(5)".

    Pod processors must now treat "text|"-less links as follows:

      L<name>         =>  L<name|name>
  L</section>     =>  L<"section"|/section>
  L<name/section> =>  L<"section" in name|name/section>

  • Note that section names might contain markup. I.e., if a section starts with:

      =head2 About the C<-M> Operator

    or with:

      =item About the C<-M> Operator

    then a link to it would look like this:

      L<somedoc/About the C<-M> Operator>

    Formatters may choose to ignore the markup for purposes of resolving the link and use only the renderable characters in the section name, as in:

      <h1><a name="About_the_-M_Operator">About the <code>-M</code>
  Operator</h1>
      ...
      <a href="somedoc#About_the_-M_Operator">About the <code>-M</code>
  Operator" in somedoc</a>

  • Previous versions of perlpod distinguished L<name/"section"> links from L<name/item> links (and their targets). These have been merged syntactically and semantically in the current specification, and section can refer either to a "=headn Heading Content" command or to a "=item Item Content" command. This specification does not specify what behavior should be in the case of a given document having several things all seeming to produce the same section identifier (e.g., in HTML, several things all producing the same anchorname in <a name="anchorname">...</a> elements). Where Pod processors can control this behavior, they should use the first such anchor. That is, L<Foo/Bar> refers to the first "Bar" section in Foo.

    But for some processors/formats this cannot be easily controlled; as with the HTML example, the behavior of multiple ambiguous <a name="anchorname">...</a> is most easily just left up to browsers to decide.

  • Authors wanting to link to a particular (absolute) URL, must do so only with "L<scheme:...>" codes (like L<http://www.perl.org>), and must not attempt "L<Some Site Name|scheme:...>" codes. This restriction avoids many problems in parsing and rendering L<...> codes.

  • In a L<text|...> code, text may contain formatting codes for formatting or for E<...> escapes, as in:

      L<B<ummE<234>stuff>|...>

    For L<...> codes without a "name|" part, only E<...> and Z<> codes may occur -- no other formatting codes. That is, authors should not use "L<B<Foo::Bar>>".

    Note, however, that formatting codes and Z<>'s can occur in any and all parts of an L<...> (i.e., in name, section, text, and url).

    Authors must not nest L<...> codes. For example, "L<The L<Foo::Bar> man page>" should be treated as an error.

  • Note that Pod authors may use formatting codes inside the "text" part of "L<text|name>" (and so on for L<text|/"sec">).

    In other words, this is valid:

      Go read L<the docs on C<$.>|perlvar/"$.">

    Some output formats that do allow rendering "L<...>" codes as hypertext, might not allow the link-text to be formatted; in that case, formatters will have to just ignore that formatting.

  • At time of writing, L<name> values are of two types: either the name of a Pod page like L<Foo::Bar> (which might be a real Perl module or program in an @INC / PATH directory, or a .pod file in those places); or the name of a UNIX man page, like L<crontab(5)>. In theory, L<chmod> in ambiguous between a Pod page called "chmod", or the Unix man page "chmod" (in whatever man-section). However, the presence of a string in parens, as in "crontab(5)", is sufficient to signal that what is being discussed is not a Pod page, and so is presumably a UNIX man page. The distinction is of no importance to many Pod processors, but some processors that render to hypertext formats may need to distinguish them in order to know how to render a given L<foo> code.

  • Previous versions of perlpod allowed for a L<section> syntax (as in "L<Object Attributes>"), which was not easily distinguishable from L<name> syntax. This syntax is no longer in the specification, and has been replaced by the L<"section"> syntax (where the quotes were formerly optional). Pod parsers should tolerate the L<section> syntax, for a while at least. The suggested heuristic for distinguishing L<section> from L<name> is that if it contains any whitespace, it's a section. Pod processors may warn about this being deprecated syntax.

About =over...=back Regions

"=over"..."=back" regions are used for various kinds of list-like structures. (I use the term "region" here simply as a collective term for everything from the "=over" to the matching "=back".)

  • The non-zero numeric indentlevel in "=over indentlevel" ... "=back" is used for giving the formatter a clue as to how many "spaces" (ems, or roughly equivalent units) it should tab over, although many formatters will have to convert this to an absolute measurement that may not exactly match with the size of spaces (or M's) in the document's base font. Other formatters may have to completely ignore the number. The lack of any explicit indentlevel parameter is equivalent to an indentlevel value of 4. Pod processors may complain if indentlevel is present but is not a positive number matching m/\A(\d*\.)?\d+\z/.

  • Authors of Pod formatters are reminded that "=over" ... "=back" may map to several different constructs in your output format. For example, in converting Pod to (X)HTML, it can map to any of <ul>...</ul>, <ol>...</ol>, <dl>...</dl>, or <blockquote>...</blockquote>. Similarly, "=item" can map to <li> or <dt>.

  • Each "=over" ... "=back" region should be one of the following:

    • An "=over" ... "=back" region containing only "=item *" commands, each followed by some number of ordinary/verbatim paragraphs, other nested "=over" ... "=back" regions, "=for..." paragraphs, and "=begin"..."=end" regions.

      (Pod processors must tolerate a bare "=item" as if it were "=item *".) Whether "*" is rendered as a literal asterisk, an "o", or as some kind of real bullet character, is left up to the Pod formatter, and may depend on the level of nesting.

    • An "=over" ... "=back" region containing only m/\A=item\s+\d+\.?\s*\z/ paragraphs, each one (or each group of them) followed by some number of ordinary/verbatim paragraphs, other nested "=over" ... "=back" regions, "=for..." paragraphs, and/or "=begin"..."=end" codes. Note that the numbers must start at 1 in each section, and must proceed in order and without skipping numbers.

      (Pod processors must tolerate lines like "=item 1" as if they were "=item 1.", with the period.)

    • An "=over" ... "=back" region containing only "=item [text]" commands, each one (or each group of them) followed by some number of ordinary/verbatim paragraphs, other nested "=over" ... "=back" regions, or "=for..." paragraphs, and "=begin"..."=end" regions.

      The "=item [text]" paragraph should not match m/\A=item\s+\d+\.?\s*\z/ or m/\A=item\s+\*\s*\z/, nor should it match just m/\A=item\s*\z/.

    • An "=over" ... "=back" region containing no "=item" paragraphs at all, and containing only some number of ordinary/verbatim paragraphs, and possibly also some nested "=over" ... "=back" regions, "=for..." paragraphs, and "=begin"..."=end" regions. Such an itemless "=over" ... "=back" region in Pod is equivalent in meaning to a "<blockquote>...</blockquote>" element in HTML.

    Note that with all the above cases, you can determine which type of "=over" ... "=back" you have, by examining the first (non-"=cut", non-"=pod") Pod paragraph after the "=over" command.

  • Pod formatters must tolerate arbitrarily large amounts of text in the "=item text..." paragraph. In practice, most such paragraphs are short, as in:

      =item For cutting off our trade with all parts of the world

    But they may be arbitrarily long:

      =item For transporting us beyond seas to be tried for pretended
  offenses
      =item He is at this time transporting large armies of foreign
  mercenaries to complete the works of death, desolation and
  tyranny, already begun with circumstances of cruelty and perfidy
  scarcely paralleled in the most barbarous ages, and totally
  unworthy the head of a civilized nation.

  • Pod processors should tolerate "=item *" / "=item number" commands with no accompanying paragraph. The middle item is an example:

      =over
      =item 1
      Pick up dry cleaning.
      =item 2
      =item 3
      Stop by the store.  Get Abba Zabas, Stoli, and cheap lawn chairs.
      =back

  • No "=over" ... "=back" region can contain headings. Processors may treat such a heading as an error.

  • Note that an "=over" ... "=back" region should have some content. That is, authors should not have an empty region like this:

      =over
      =back

    Pod processors seeing such a contentless "=over" ... "=back" region, may ignore it, or may report it as an error.

  • Processors must tolerate an "=over" list that goes off the end of the document (i.e., which has no matching "=back"), but they may warn about such a list.

  • Authors of Pod formatters should note that this construct:

      =item Neque
      =item Porro
      =item Quisquam Est
      Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
  velit, sed quia non numquam eius modi tempora incidunt ut
  labore et dolore magnam aliquam quaerat voluptatem.
      =item Ut Enim

    is semantically ambiguous, in a way that makes formatting decisions a bit difficult. On the one hand, it could be mention of an item "Neque", mention of another item "Porro", and mention of another item "Quisquam Est", with just the last one requiring the explanatory paragraph "Qui dolorem ipsum quia dolor..."; and then an item "Ut Enim". In that case, you'd want to format it like so:

      Neque
      Porro
      Quisquam Est
    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.
      Ut Enim

    But it could equally well be a discussion of three (related or equivalent) items, "Neque", "Porro", and "Quisquam Est", followed by a paragraph explaining them all, and then a new item "Ut Enim". In that case, you'd probably want to format it like so:

      Neque
  Porro
  Quisquam Est
    Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.
      Ut Enim

    But (for the forseeable future), Pod does not provide any way for Pod authors to distinguish which grouping is meant by the above "=item"-cluster structure. So formatters should format it like so:

      Neque
      Porro
      Quisquam Est
        Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
    velit, sed quia non numquam eius modi tempora incidunt ut
    labore et dolore magnam aliquam quaerat voluptatem.
      Ut Enim

    That is, there should be (at least roughly) equal spacing between items as between paragraphs (although that spacing may well be less than the full height of a line of text). This leaves it to the reader to use (con)textual cues to figure out whether the "Qui dolorem ipsum..." paragraph applies to the "Quisquam Est" item or to all three items "Neque", "Porro", and "Quisquam Est". While not an ideal situation, this is preferable to providing formatting cues that may be actually contrary to the author's intent.

About Data Paragraphs and "=begin/=end" Regions

Data paragraphs are typically used for inlining non-Pod data that is to be used (typically passed through) when rendering the document to a specific format:

  =begin rtf
  \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

  =end rtf

The exact same effect could, incidentally, be achieved with a single "=for" paragraph:

  =for rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

(Although that is not formally a data paragraph, it has the same meaning as one, and Pod parsers may parse it as one.)

Another example of a data paragraph:

  =begin html
  I like <em>PIE</em>!
  <hr>Especially pecan pie!
  =end html

If these were ordinary paragraphs, the Pod parser would try to expand the "E</em>" (in the first paragraph) as a formatting code, just like "E<lt>" or "E<eacute>". But since this is in a "=begin identifier"..."=end identifier" region and the identifier "html" doesn't begin have a ":" prefix, the contents of this region are stored as data paragraphs, instead of being processed as ordinary paragraphs (or if they began with a spaces and/or tabs, as verbatim paragraphs).

As a further example: At time of writing, no "biblio" identifier is supported, but suppose some processor were written to recognize it as a way of (say) denoting a bibliographic reference (necessarily containing formatting codes in ordinary paragraphs). The fact that "biblio" paragraphs were meant for ordinary processing would be indicated by prefacing each "biblio" identifier with a colon:

  =begin :biblio
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.
  =end :biblio

This would signal to the parser that paragraphs in this begin...end region are subject to normal handling as ordinary/verbatim paragraphs (while still tagged as meant only for processors that understand the "biblio" identifier). The same effect could be had with:

  =for :biblio
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.

The ":" on these identifiers means simply "process this stuff normally, even though the result will be for some special target". I suggest that parser APIs report "biblio" as the target identifier, but also report that it had a ":" prefix. (And similarly, with the above "html", report "html" as the target identifier, and note the lack of a ":" prefix.)

Note that a "=begin identifier"..."=end identifier" region where identifier begins with a colon, can contain commands. For example:

  =begin :biblio
  Wirth's classic is available in several editions, including:
  =for comment
   hm, check abebooks.com for how much used copies cost.
  =over
  =item
  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]
  =item
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.
  =back
  =end :biblio

Note, however, a "=begin identifier"..."=end identifier" region where identifier does not begin with a colon, should not directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back", nor "=item". For example, this may be considered invalid:

  =begin somedata
  This is a data paragraph.
  =head1 Don't do this!
  This is a data paragraph too.
  =end somedata

A Pod processor may signal that the above (specifically the "=head1" paragraph) is an error. Note, however, that the following should not be treated as an error:

  =begin somedata
  This is a data paragraph.
  =cut
  # Yup, this isn't Pod anymore.
  sub excl { (rand() > .5) ? "hoo!" : "hah!" }

  =pod
  This is a data paragraph too.
  =end somedata

And this too is valid:

  =begin someformat
  This is a data paragraph.
    And this is a data paragraph.
  =begin someotherformat
  This is a data paragraph too.
    And this is a data paragraph too.
  =begin :yetanotherformat
  =head2 This is a command paragraph!
  This is an ordinary paragraph!
    And this is a verbatim paragraph!
  =end :yetanotherformat
  =end someotherformat
  Another data paragraph!
  =end someformat

The contents of the above "=begin :yetanotherformat" ... "=end :yetanotherformat" region aren't data paragraphs, because the immediately containing region's identifier (":yetanotherformat") begins with a colon. In practice, most regions that contain data paragraphs will contain only data paragraphs; however, the above nesting is syntactically valid as Pod, even if it is rare. However, the handlers for some formats, like "html", will accept only data paragraphs, not nested regions; and they may complain if they see (targeted for them) nested regions, or commands, other than "=end", "=pod", and "=cut".

Also consider this valid structure:

  =begin :biblio
  Wirth's classic is available in several editions, including:
  =over
  =item
  Wirth, Niklaus.  1975.  I<Algorithmen und Datenstrukturen.>
  Teubner, Stuttgart.  [Yes, it's in German.]
  =item
  Wirth, Niklaus.  1976.  I<Algorithms + Data Structures =
  Programs.>  Prentice-Hall, Englewood Cliffs, NJ.
  =back
  Buy buy buy!
  =begin html
  <img src='wirth_spokesmodeling_book.png'>
  <hr>
  =end html
  Now now now!
  =end :biblio

There, the "=begin html"..."=end html" region is nested inside the larger "=begin :biblio"..."=end :biblio" region. Note that the content of the "=begin html"..."=end html" region is data paragraph(s), because the immediately containing region's identifier ("html") doesn't begin with a colon.

Pod parsers, when processing a series of data paragraphs one after another (within a single region), should consider them to be one large data paragraph that happens to contain blank lines. So the content of the above "=begin html"..."=end html" may be stored as two data paragraphs (one consisting of "<img src='wirth_spokesmodeling_book.png'>\n" and another consisting of "<hr>\n"), but should be stored as a single data paragraph (consisting of "<img src='wirth_spokesmodeling_book.png'>\n\n<hr>\n").

Pod processors should tolerate empty "=begin something"..."=end something" regions, empty "=begin :something"..."=end :something" regions, and contentless "=for something" and "=for :something" paragraphs. I.e., these should be tolerated:

  =for html
  =begin html
  =end html
  =begin :biblio
  =end :biblio

Incidentally, note that there's no easy way to express a data paragraph starting with something that looks like a command. Consider:

  =begin stuff
  =shazbot
  =end stuff

There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data paragraph "=shazbot\n". However, you can express a data paragraph consisting of "=shazbot\n" using this code:

  =for stuff =shazbot

The situation where this is necessary, is presumably quite rare.

Note that =end commands must match the currently open =begin command. That is, they must properly nest. For example, this is valid:

  =begin outer
  X
  =begin inner
  Y
  =end inner
  Z
  =end outer

while this is invalid:

  =begin outer
  X
  =begin inner
  Y
  =end outer
  Z
  =end inner

This latter is improper because when the "=end outer" command is seen, the currently open region has the formatname "inner", not "outer". (It just happens that "outer" is the format name of a higher-up region.) This is an error. Processors must by default report this as an error, and may halt processing the document containing that error. A corollary of this is that regions cannot "overlap" -- i.e., the latter block above does not represent a region called "outer" which contains X and Y, overlapping a region called "inner" which contains Y and Z. But because it is invalid (as all apparently overlapping regions would be), it doesn't represent that, or anything at all.

Similarly, this is invalid:

  =begin thing
  =end hting

This is an error because the region is opened by "thing", and the "=end" tries to close "hting" [sic].

This is also invalid:

  =begin thing
  =end

This is invalid because every "=end" command must have a formatname parameter.

SEE ALSO

the perlpod manpage, PODs: Embedded Documentation in the perlsyn manpage, podchecker

AUTHOR

Sean M. Burke


perldoc - Look up Perl documentation in Pod format.

  • OPTIONS
  • SECURITY
  • ENVIRONMENT
  • AUTHOR

NAME

perldoc - Look up Perl documentation in Pod format.

SYNOPSIS

perldoc [-h] [-v] [-t] [-u] [-m] [-l] [-F]
[-i] [-V] [-T] [-r]
[-ddestination_file]
[-oformatname]
[-MFormatterClassName]
[-wformatteroption:value]
[-n nroff-replacement]
[-X]
PageName|ModuleName|ProgramName

perldoc -f BuiltinFunction

perldoc -q FAQ Keyword

See below for more description of the switches.

DESCRIPTION

perldoc looks up a piece of documentation in .pod format that is embedded in the perl installation tree or in a perl script, and displays it via pod2man | nroff -man | $PAGER. (In addition, if running under HP-UX, col -x will be used.) This is primarily used for the documentation for the perl library modules.

Your system may also have man pages installed for those modules, in which case you can probably just use the man(1) command.

If you are looking for a table of contents to the Perl library modules documentation, see the the perltoc manpage page.

OPTIONS

-h

Prints out a brief help message.

-v

Describes search for the item in detail (verbosely).

-t

Display docs using plain text converter, instead of nroff. This may be faster, but it probably won't look as nice.

-u

Skip the real Pod formatting, and just show the raw Pod source (Unformatted)

-m module

Display the entire module: both code and unformatted pod documentation. This may be useful if the docs don't explain a function in the detail you need, and you'd like to inspect the code directly; perldoc will find the file for you and simply hand it off for display.

-l

Display only the file name of the module found.

-F

Consider arguments as file names; no search in directories will be performed.

-f perlfunc

The -f option followed by the name of a perl built in function will extract the documentation of this function from the perlfunc manpage.

Example:

      perldoc -f sprintf
-q perlfaq-search-regexp

The -q option takes a regular expression as an argument. It will search the question headings in perlfaq[1-9] and print the entries matching the regular expression. Example: perldoc -q shuffle

-T

This specifies that the output is not to be sent to a pager, but is to be sent right to STDOUT.

-d destination-filename

This specifies that the output is to be sent neither to a pager nor to STDOUT, but is to be saved to the specified filename. Example: perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap

-o output-formatname

This specifies that you want Perldoc to try using a Pod-formatting class for the output format that you specify. For example: -oman. This is actually just a wrapper around the -M switch; using -oformatname just looks for a loadable class by adding that format name (with different capitalizations) to the end of different classname prefixes.

For example, -oLaTeX currently tries all of the following classes:
Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
Pod::LATEX.

-M module-name

This specifies the module that you want to try using for formatting the pod. The class must at least provide a parse_from_file method. For example: perldoc -MPod::Perldoc::ToChecker.

You can specify several classes to try by joining them with commas or semicolons, as in -MTk::SuperPod;Tk::Pod.

-w option:value or -w option

This specifies an option to call the formatter with. For example, -w textsize:15 will call $formatter->textsize(15) on the formatter object before it is used to format the object. For this to be valid, the formatter class must provide such a method, and the value you pass should be valid. (So if textsize expects an integer, and you do -w textsize:big, expect trouble.)

You can use -w optionname (without a value) as shorthand for -w optionname:TRUE. This is presumably useful in cases of on/off features like: -w page_numbering.

You can use a "=" instead of the ":", as in: -w textsize=15. This might be more (or less) convenient, depending on what shell you use.

-X

Use an index if it is present -- the -X option looks for an entry whose basename matches the name given on the command line in the file $Config{archlib}/pod.idx. The pod.idx file should contain fully qualified filenames, one per line.

PageName|ModuleName|ProgramName

The item you want to look up. Nested modules (such as File::Basename) are specified either as File::Basename or File/Basename. You may also give a descriptive name of a page, such as perlfunc.

-n some-formatter

Specify replacement for nroff

-r

Recursive search.

-i

Ignore case.

-V

Displays the version of perldoc you're running.

SECURITY

Because perldoc does not run properly tainted, and is known to have security issues, when run as the superuser it will attempt to drop privileges by setting the effective and real IDs to nobody's or nouser's account, or -2 if unavailable. If it cannot relinquish its privileges, it will not run.

ENVIRONMENT

Any switches in the PERLDOC environment variable will be used before the command line arguments.

Useful values for PERLDOC include -oman, -otext, -otk, -ortf, -oxml, and so on, depending on what modules you have on hand; or exactly specify the formatter class with -MPod::Perldoc::ToMan or the like.

perldoc also searches directories specified by the PERL5LIB (or PERLLIB if PERL5LIB is not defined) and PATH environment variables. (The latter is so that embedded pods for executables, such as perldoc itself, are available.)

perldoc will use, in order of preference, the pager defined in PERLDOC_PAGER, MANPAGER, or PAGER before trying to find a pager on its own. (MANPAGER is not used if perldoc was told to display plain text or unformatted pod.)

One useful value for PERLDOC_PAGER is less -+C -E.

Having PERLDOCDEBUG set to a positive integer will make perldoc emit even more descriptive output than the -v switch does -- the higher the number, the more it emits.

AUTHOR

Current maintainer: Sean M. Burke, <sburke@cpan.org>

Past contributors are: Kenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty <doughera@lafcol.lafayette.edu>, and many others.


perlutil - utilities packaged with the Perl distribution

    • DOCUMENTATION
    • CONVERTORS
    • Administration
    • Development
    • SEE ALSO

NAME

perlutil - utilities packaged with the Perl distribution

DESCRIPTION

Along with the Perl interpreter itself, the Perl distribution installs a range of utilities on your system. There are also several utilities which are used by the Perl distribution itself as part of the install process. This document exists to list all of these utilities, explain what they are for and provide pointers to each module's documentation, if appropriate.

DOCUMENTATION

perldoc

The main interface to Perl's documentation is perldoc, although if you're reading this, it's more than likely that you've already found it. perldoc will extract and format the documentation from any file in the current directory, any Perl module installed on the system, or any of the standard documentation pages, such as this one. Use perldoc <name> to get information on any of the utilities described in this document.

pod2man and pod2text

If it's run from a terminal, perldoc will usually call pod2man to translate POD (Plain Old Documentation - see the perlpod manpage for an explanation) into a manpage, and then run man to display it; if man isn't available, pod2text will be used instead and the output piped through your favourite pager.

pod2html and pod2latex

As well as these two, there are two other converters: pod2html will produce HTML pages from POD, and pod2latex, which produces LaTeX files.

pod2usage

If you just want to know how to use the utilities described here, pod2usage will just extract the "USAGE" section; some of the utilities will automatically call pod2usage on themselves when you call them with -help.

podselect

pod2usage is a special case of podselect, a utility to extract named sections from documents written in POD. For instance, while utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS" sections: podselect -s "SYNOPSIS" ... will extract this section for a given file.

podchecker

If you're writing your own documentation in POD, the podchecker utility will look for errors in your markup.

splain

splain is an interface to the perldiag manpage - paste in your error message to it, and it'll explain it for you.

roffitall

The roffitall utility is not installed on your system but lives in the pod/ directory of your Perl source kit; it converts all the documentation from the distribution to *roff format, and produces a typeset PostScript or text file of the whole lot.

CONVERTORS

To help you convert legacy programs to Perl, we've included three conversion filters:

a2p

a2p converts awk scripts to Perl programs; for example, a2p -F: on the simple awk script {print $2} will produce a Perl program based around this code:

    while (<>) {
        ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999);
        print $Fld2;
    }
s2p

Similarly, s2p converts sed scripts to Perl programs. s2p run on s/foo/bar will produce a Perl program based around this:

    while (<>) {
        chomp;
        s/foo/bar/g;
        print if $printit;
    }
find2perl

Finally, find2perl translates find commands to Perl equivalents which use the File::Find module. As an example, find2perl . -user root -perm 4000 -print produces the following callback subroutine for File::Find:

    sub wanted {
        my ($dev,$ino,$mode,$nlink,$uid,$gid);
        (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
        $uid == $uid{'root'}) &&
        (($mode & 0777) == 04000);
        print("$name\n");
    }

As well as these filters for converting other languages, the pl2pm utility will help you convert old-style Perl 4 libraries to new-style Perl5 modules.

Administration

libnetcfg

To display and change the libnet configuration run the libnetcfg command.

Development

There are a set of utilities which help you in developing Perl programs, and in particular, extending Perl with C.

perlbug

perlbug is the recommended way to report bugs in the perl interpreter itself or any of the standard library modules back to the developers; please read through the documentation for perlbug thoroughly before using it to submit a bug report.

h2ph

Back before Perl had the XS system for connecting with C libraries, programmers used to get library constants by reading through the C header files. You may still see require 'syscall.ph' or similar around - the .ph file should be created by running h2ph on the corresponding .h file. See the h2ph documentation for more on how to convert a whole bunch of header files at once.

c2ph and pstruct

c2ph and pstruct, which are actually the same program but behave differently depending on how they are called, provide another way of getting at C with Perl - they'll convert C structures and union declarations to Perl code. This is deprecated in favour of h2xs these days.

h2xs

h2xs converts C header files into XS modules, and will try and write as much glue between C libraries and Perl modules as it can. It's also very useful for creating skeletons of pure Perl modules.

dprofpp

Perl comes with a profiler, the Devel::DProf module. The dprofpp utility analyzes the output of this profiler and tells you which subroutines are taking up the most run time. See the Devel::DProf manpage for more information.

perlcc

perlcc is the interface to the experimental Perl compiler suite.

SEE ALSO

perldoc, pod2man, the perlpod manpage, pod2html, pod2usage, podselect, podchecker, splain, the perldiag manpage, roffitall, a2p, s2p, find2perl, File::Find, pl2pm, perlbug, h2ph, c2ph, h2xs, dprofpp, the Devel::DProf manpage, perlcc


perl5db.pl - the perl debugger

  • GENERAL NOTES
    • Why not use more lexicals?
    • Automated variable stacking via local()
    • The ^ trick
    • FLAGS, FLAGS, FLAGS
    • What are those XXX comments for?
  • DATA STRUCTURES MAINTAINED BY CORE
  • DEBUGGER STARTUP
    • STARTUP-ONLY OPTIONS
      • SAMPLE RCFILE
  • INTERNALS DESCRIPTION
    • DEBUGGER INTERFACE VARIABLES
      • IMPORTANT INTERNAL VARIABLES
        • $CreateTTY
        • $doret
        • $evalarg
        • $frame
        • $level
        • $onetimeDump
        • $onetimeDumpDepth
        • $signal
        • $single
        • $trace
        • $slave_editor
        • @cmdfhs
        • @dbline
        • @old_watch
        • @saved
        • @stack
        • @to_watch
        • @typeahead
        • %alias
        • %break_on_load
        • %dbline
        • %had_breakpoints
        • %option
        • %postponed
        • %postponed_file
  • DEBUGGER INITIALIZATION
  • DEBUGGER ROUTINES
    • DB::eval()
      • Parameters and variables influencing execution of DB::eval()
      • The problem of lexicals
  • DEBUGGER INITIALIZATION
    • BASIC SETUP
    • THREADS SUPPORT
  • OPTION PROCESSING
    • SETTING UP THE DEBUGGER GREETING
    • READING THE RC FILE
    • RESTART PROCESSING
    • SETTING UP THE TERMINAL
    • SOCKET HANDLING
  • SUBROUTINES
    • DB
    • watchfunction()
    • GETTING READY TO EXECUTE COMMANDS
    • WHERE ARE WE?
    • THE COMMAND LOOP
        • The null command
      • COMMAND ALIASES
      • MAIN-LINE COMMANDS
        • q - quit
        • t - trace
        • S - list subroutines matching/not matching a pattern
        • X - list variables in current package
        • V - list variables
        • x - evaluate and print an expression
        • m - print methods
        • f - switch files
        • . - return to last-executed line.
        • - - back one window
      • PRE-580 COMMANDS VS. NEW COMMANDS: a, A, b, B, h, l, L, M, o, O, P, v, w, W, <, <<, {, {{
        • y - List lexicals in higher scope
      • COMMANDS NOT WORKING AFTER PROGRAM ENDS
        • n - single step, but don't trace down into subs
        • s - single-step, entering subs
        • c - run continuously, setting an optional breakpoint
        • r - return from a subroutine
        • T - stack trace
        • w - List window around current line.
        • W - watch-expression processing.
        • / - search forward for a string in the source
        • ? - search backward for a string in the source
        • $rc - Recall command
        • $sh$sh - system() command
        • $rc pattern $rc - Search command history
        • $sh - Invoke a shell
        • $sh command - Force execution of a command in a shell
        • H - display commands in history
        • man, doc, perldoc - look up documentation
        • p - print
        • = - define command alias
        • source - read commands from a file.
        • save - send current history to a file
        • R - restart
        • rerun - rerun the current session
        • |, || - pipe output through the pager.
      • END OF COMMAND PARSING
      • POST-COMMAND PROCESSING
      • COMMAND LOOP TERMINATION
    • sub
      • caller() support
  • EXTENDED COMMAND HANDLING AND THE COMMAND API
    • %set
    • cmd_wrapper() (API)
      • cmd_a (command)
      • cmd_A (command)
      • delete_action (API)
      • cmd_b (command)
      • break_on_load (API)
      • report_break_on_load (API)
      • cmd_b_load (command)
      • $filename_error (API package global)
      • breakable_line(from, to) (API)
      • breakable_line_in_filename(file, from, to) (API)
      • break_on_line(lineno, [condition]) (API)
      • cmd_b_line(line, [condition]) (command)
      • break_on_filename_line(file, line, [condition]) (API)
      • break_on_filename_line_range(file, from, to, [condition]) (API)
      • subroutine_filename_lines(subname, [condition]) (API)
      • break_subroutine(subname) (API)
      • cmd_b_sub(subname, [condition]) (command)
      • cmd_B - delete breakpoint(s) (command)
      • delete_breakpoint([line]) (API)
      • cmd_stop (command)
      • cmd_e - threads
      • cmd_E - list of thread ids
      • cmd_h - help command (command)
      • cmd_i - inheritance display
      • cmd_l - list lines (command)
      • cmd_L - list breakpoints, actions, and watch expressions (command)
      • cmd_M - list modules (command)
      • cmd_o - options (command)
      • cmd_O - nonexistent in 5.8.x (command)
      • cmd_v - view window (command)
      • cmd_w - add a watch expression (command)
      • cmd_W - delete watch expressions (command)
  • SUPPORT ROUTINES
    • save
    • print_lineinfo - show where we are now
    • postponed_sub
    • postponed
    • dumpit
    • print_trace
    • dump_trace(skip[,count])
    • action()
    • unbalanced
    • gets()
    • DB::system() - handle calls to<system()> without messing up the debugger
  • TTY MANAGEMENT
    • setterm
  • GET_FORK_TTY EXAMPLE FUNCTIONS
      • xterm_get_fork_TTY
      • os2_get_fork_TTY
    • create_IN_OUT($flags)
    • resetterm
    • readline
  • OPTIONS SUPPORT ROUTINES
    • dump_option - list the current value of an option setting
    • option_val - find the current value of an option
    • parse_options
  • RESTART SUPPORT
    • set_list
    • get_list
  • MISCELLANEOUS SIGNAL AND I/O MANAGEMENT
    • catch()
    • warn()
  • INITIALIZATION TTY SUPPORT
    • reset_IN_OUT
  • OPTION SUPPORT ROUTINES
    • TTY
    • noTTY
    • ReadLine
    • RemotePort
    • tkRunning
    • NonStop
    • pager
    • shellBang
    • ornaments
    • recallCommand
    • LineInfo - where the line number information goes
  • COMMAND SUPPORT ROUTINES
    • list_modules
    • sethelp()
      • HELP MESSAGE FORMAT
    • print_help()
    • fix_less
  • DIE AND WARN MANAGEMENT
    • diesignal
    • dbwarn
    • dbdie
    • warnlevel()
    • dielevel
    • signalLevel
  • SUBROUTINE DECODING SUPPORT
    • CvGV_name()
    • CvGV_name_or_bust coderef
    • find_sub
    • methods
    • methods_via($class, $prefix, $crawl_upward)
    • setman - figure out which command to use to show documentation
    • runman - run the appropriate command to show documentation
  • DEBUGGER INITIALIZATION - THE SECOND BEGIN BLOCK
  • READLINE SUPPORT - COMPLETION FUNCTION
    • db_complete
      • b postpone|compile
      • b load
      • V (list variable) and m (list modules)
        • Unqualified package names
        • Qualified package names
      • f - switch files
      • Subroutine name completion
      • Scalar, array, and hash completion: partially qualified package
      • Symbol completion: current package or package main.
      • Options
      • Filename completion
  • MISCELLANEOUS SUPPORT FUNCTIONS
    • end_report
    • clean_ENV
  • END PROCESSING - THE END BLOCK
  • PRE-5.8 COMMANDS
    • Null command
    • Old a command.
    • Old b command
    • Old D command.
    • Old h command
    • Old W command
  • PRE-AND-POST-PROMPT COMMANDS AND ACTIONS
    • cmd_pre590_prepost
    • cmd_prepost
  • DB::fake

NAME

perl5db.pl - the perl debugger

SYNOPSIS

    perl -d  your_Perl_script

DESCRIPTION

perl5db.pl is the perl debugger. It is loaded automatically by Perl when you invoke a script with perl -d. This documentation tries to outline the structure and services provided by perl5db.pl, and to describe how you can use them.

GENERAL NOTES

The debugger can look pretty forbidding to many Perl programmers. There are a number of reasons for this, many stemming out of the debugger's history.

When the debugger was first written, Perl didn't have a lot of its nicer features - no references, no lexical variables, no closures, no object-oriented programming. So a lot of the things one would normally have done using such features was done using global variables, globs and the local() operator in creative ways.

Some of these have survived into the current debugger; a few of the more interesting and still-useful idioms are noted in this section, along with notes on the comments themselves.

Why not use more lexicals?

Experienced Perl programmers will note that the debugger code tends to use mostly package globals rather than lexically-scoped variables. This is done to allow a significant amount of control of the debugger from outside the debugger itself.

Unfortunately, though the variables are accessible, they're not well documented, so it's generally been a decision that hasn't made a lot of difference to most users. Where appropriate, comments have been added to make variables more accessible and usable, with the understanding that these are debugger internals, and are therefore subject to change. Future development should probably attempt to replace the globals with a well-defined API, but for now, the variables are what we've got.

Automated variable stacking via local()

As you may recall from reading perlfunc, the local() operator makes a temporary copy of a variable in the current scope. When the scope ends, the old copy is restored. This is often used in the debugger to handle the automatic stacking of variables during recursive calls:

     sub foo {
        local $some_global++;

        # Do some stuff, then ...
        return;
             }

What happens is that on entry to the subroutine, $some_global is localized, then altered. When the subroutine returns, Perl automatically undoes the localization, restoring the previous value. Voila, automatic stack management.

The debugger uses this trick a lot. Of particular note is DB::eval, which lets the debugger get control inside of eval'ed code. The debugger localizes a saved copy of $@ inside the subroutine, which allows it to keep $@ safe until it DB::eval returns, at which point the previous value of $@ is restored. This makes it simple (well, simpler) to keep track of $@ inside evals which eval other eval's.

In any case, watch for this pattern. It occurs fairly often.

The ^ trick

This is used to cleverly reverse the sense of a logical test depending on the value of an auxiliary variable. For instance, the debugger's S (search for subroutines by pattern) allows you to negate the pattern like this:

   # Find all non-'foo' subs:
   S !/foo/

Boolean algebra states that the truth table for XOR looks like this:

  • 0 ^ 0 = 0

    (! not present and no match) --> false, don't print

  • 0 ^ 1 = 1

    (! not present and matches) --> true, print

  • 1 ^ 0 = 1

    (! present and no match) --> true, print

  • 1 ^ 1 = 0

    (! present and matches) --> false, don't print

As you can see, the first pair applies when ! isn't supplied, and the second pair applies when it is. The XOR simply allows us to compact a more complicated if-then-elseif-else into a more elegant (but perhaps overly clever) single test. After all, it needed this explanation...

FLAGS, FLAGS, FLAGS

There is a certain C programming legacy in the debugger. Some variables, such as $single, $trace, and $frame, have magical values composed of 1, 2, 4, etc. (powers of 2) OR'ed together. This allows several pieces of state to be stored independently in a single scalar.

A test like

    if ($scalar & 4) ...

is checking to see if the appropriate bit is on. Since each bit can be "addressed" independently in this way, $scalar is acting sort of like an array of bits. Obviously, since the contents of $scalar are just a bit-pattern, we can save and restore it easily (it will just look like a number).

The problem, is of course, that this tends to leave magic numbers scattered all over your program whenever a bit is set, cleared, or checked. So why do it?

  • First, doing an arithmetical or bitwise operation on a scalar is just about the fastest thing you can do in Perl: use constant actually creates a subroutine call, and array and hash lookups are much slower. Is this over-optimization at the expense of readability? Possibly, but the debugger accesses these variables a lot. Any rewrite of the code will probably have to benchmark alternate implementations and see which is the best balance of readability and speed, and then document how it actually works.

  • Second, it's very easy to serialize a scalar number. This is done in the restart code; the debugger state variables are saved in %ENV and then restored when the debugger is restarted. Having them be just numbers makes this trivial.

  • Third, some of these variables are being shared with the Perl core smack in the middle of the interpreter's execution loop. It's much faster for a C program (like the interpreter) to check a bit in a scalar than to access several different variables (or a Perl array).

What are those XXX comments for?

Any comment containing XXX means that the comment is either somewhat speculative - it's not exactly clear what a given variable or chunk of code is doing, or that it is incomplete - the basics may be clear, but the subtleties are not completely documented.

Send in a patch if you can clear up, fill out, or clarify an XXX.

DATA STRUCTURES MAINTAINED BY CORE

There are a number of special data structures provided to the debugger by the Perl interpreter.

The array @{$main::{'_<'.$filename}} (aliased locally to @dbline via glob assignment) contains the text from $filename, with each element corresponding to a single line of $filename.

The hash %{'_<'.$filename} (aliased locally to %dbline via glob assignment) contains breakpoints and actions. The keys are line numbers; you can set individual values, but not the whole hash. The Perl interpreter uses this hash to determine where breakpoints have been set. Any true value is considered to be a breakpoint; perl5db.pl uses $break_condition\0$action. Values are magical in numeric context: 1 if the line is breakable, 0 if not.

The scalar ${"_<$filename"} simply contains the string _<$filename. This is also the case for evaluated strings that contain subroutines, or which are currently being executed. The $filename for evaled strings looks like (eval 34) or (re_eval 19).

DEBUGGER STARTUP

When perl5db.pl starts, it reads an rcfile (perl5db.ini for non-interactive sessions, .perldb for interactive ones) that can set a number of options. In addition, this file may define a subroutine &afterinit that will be executed (in the debugger's context) after the debugger has initialized itself.

Next, it checks the PERLDB_OPTS environment variable and treats its contents as the argument of a o command in the debugger.

STARTUP-ONLY OPTIONS

The following options can only be specified at startup. To set them in your rcfile, add a call to &parse_options("optionName=new_value").

  • TTY

    the TTY to use for debugging i/o.

  • noTTY

    if set, goes in NonStop mode. On interrupt, if TTY is not set, uses the value of noTTY or $HOME/.perldbtty$$ to find TTY using Term::Rendezvous. Current variant is to have the name of TTY in this file.

  • ReadLine

    If false, a dummy ReadLine is used, so you can debug ReadLine applications.

  • NonStop

    if true, no i/o is performed until interrupt.

  • LineInfo

    file or pipe to print line number info to. If it is a pipe, a short "emacs like" message is used.

  • RemotePort

    host:port to connect to on remote host for remote debugging.

SAMPLE RCFILE

 &parse_options("NonStop=1 LineInfo=db.out");
  sub afterinit { $trace = 1; }

The script will run without human intervention, putting trace information into db.out. (If you interrupt it, you had better reset LineInfo to something interactive!)

INTERNALS DESCRIPTION

DEBUGGER INTERFACE VARIABLES

Perl supplies the values for %sub. It effectively inserts a &DB::DB(); in front of each place that can have a breakpoint. At each subroutine call, it calls &DB::sub with $DB::sub set to the called subroutine. It also inserts a BEGIN {require 'perl5db.pl'} before the first line.

After each required file is compiled, but before it is executed, a call to &DB::postponed($main::{'_<'.$filename}) is done. $filename is the expanded name of the required file (as found via %INC).

IMPORTANT INTERNAL VARIABLES

$CreateTTY

Used to control when the debugger will attempt to acquire another TTY to be used for input.

  • 1 - on fork()
  • 2 - debugger is started inside debugger
  • 4 - on startup

$doret

The value -2 indicates that no return value should be printed. Any other positive value causes DB::sub to print return values.

$evalarg

The item to be eval'ed by DB::eval. Used to prevent messing with the current contents of @_ when DB::eval is called.

$frame

Determines what messages (if any) will get printed when a subroutine (or eval) is entered or exited.

  • 0 - No enter/exit messages
  • 1 - Print entering messages on subroutine entry
  • 2 - Adds exit messages on subroutine exit. If no other flag is on, acts like 1+2.
  • 4 - Extended messages: <in|out> context=fully-qualified sub name from file:line. If no other flag is on, acts like 1+4.
  • 8 - Adds parameter information to messages, and overloaded stringify and tied FETCH is enabled on the printed arguments. Ignored if 4 is not on.
  • 16 - Adds context return from subname: value messages on subroutine/eval exit. Ignored if 4 is is not on.

To get everything, use $frame=30 (or o f=30 as a debugger command). The debugger internally juggles the value of $frame during execution to protect external modules that the debugger uses from getting traced.

$level

Tracks current debugger nesting level. Used to figure out how many <> pairs to surround the line number with when the debugger outputs a prompt. Also used to help determine if the program has finished during command parsing.

$onetimeDump

Controls what (if anything) DB::eval() will print after evaluating an expression.

  • undef - don't print anything
  • dump - use dumpvar.pl to display the value returned
  • methods - print the methods callable on the first item returned

$onetimeDumpDepth

Controls how far down dumpvar.pl will go before printing ... while dumping a structure. Numeric. If undef, print all levels.

$signal

Used to track whether or not an INT signal has been detected. DB::DB(), which is called before every statement, checks this and puts the user into command mode if it finds $signal set to a true value.

$single

Controls behavior during single-stepping. Stacked in @stack on entry to each subroutine; popped again at the end of each subroutine.

  • 0 - run continuously.
  • 1 - single-step, go into subs. The s command.
  • 2 - single-step, don't go into subs. The n command.
  • 4 - print current sub depth (turned on to force this when too much recursion occurs.

$trace

Controls the output of trace information.

  • 1 - The t command was entered to turn on tracing (every line executed is printed)
  • 2 - watch expressions are active
  • 4 - user defined a watchfunction() in afterinit()

$slave_editor

1 if LINEINFO was directed to a pipe; 0 otherwise.

@cmdfhs

Stack of filehandles that DB::readline() will read commands from. Manipulated by the debugger's source command and DB::readline() itself.

@dbline

Local alias to the magical line array, @{$main::{'_<'.$filename}} , supplied by the Perl interpreter to the debugger. Contains the source.

@old_watch

Previous values of watch expressions. First set when the expression is entered; reset whenever the watch expression changes.

@saved

Saves important globals ($@, $!, $^E, $,, $/, $\, $^W) so that the debugger can substitute safe values while it's running, and restore them when it returns control.

@stack

Saves the current value of $single on entry to a subroutine. Manipulated by the c command to turn off tracing in all subs above the current one.

@to_watch

The 'watch' expressions: to be evaluated before each line is executed.

@typeahead

The typeahead buffer, used by DB::readline.

%alias

Command aliases. Stored as character strings to be substituted for a command entered.

%break_on_load

Keys are file names, values are 1 (break when this file is loaded) or undef (don't break when it is loaded).

%dbline

Keys are line numbers, values are condition\0action. If used in numeric context, values are 0 if not breakable, 1 if breakable, no matter what is in the actual hash entry.

%had_breakpoints

Keys are file names; values are bitfields:

  • 1 - file has a breakpoint in it.
  • 2 - file has an action in it.

A zero or undefined value means this file has neither.

%option

Stores the debugger options. These are character string values.

%postponed

Saves breakpoints for code that hasn't been compiled yet. Keys are subroutine names, values are:

  • compile - break when this sub is compiled
  • break +0 if <condition> - break (conditionally) at the start of this routine. The condition will be '1' if no condition was specified.

%postponed_file

This hash keeps track of breakpoints that need to be set for files that have not yet been compiled. Keys are filenames; values are references to hashes. Each of these hashes is keyed by line number, and its values are breakpoint definitions (condition\0action).

DEBUGGER INITIALIZATION

The debugger's initialization actually jumps all over the place inside this package. This is because there are several BEGIN blocks (which of course execute immediately) spread through the code. Why is that?

The debugger needs to be able to change some things and set some things up before the debugger code is compiled; most notably, the $deep variable that DB::sub uses to tell when a program has recursed deeply. In addition, the debugger has to turn off warnings while the debugger code is compiled, but then restore them to their original setting before the program being debugged begins executing.

The first BEGIN block simply turns off warnings by saving the current setting of $^W and then setting it to zero. The second one initializes the debugger variables that are needed before the debugger begins executing. The third one puts $^X back to its former value.

We'll detail the second BEGIN block later; just remember that if you need to initialize something before the debugger starts really executing, that's where it has to go.

DEBUGGER ROUTINES

DB::eval()

This function replaces straight eval() inside the debugger; it simplifies the process of evaluating code in the user's context.

The code to be evaluated is passed via the package global variable $DB::evalarg; this is done to avoid fiddling with the contents of @_.

Before we do the eval(), we preserve the current settings of $trace, $single, $^D and $usercontext. The latter contains the preserved values of $@, $!, $^E, $,, $/, $\, $^W and the user's current package, grabbed when DB::DB got control. This causes the proper context to be used when the eval is actually done. Afterward, we restore $trace, $single, and $^D.

Next we need to handle $@ without getting confused. We save $@ in a local lexical, localize $saved[0] (which is where save() will put $@), and then call save() to capture $@, $!, $^E, $,, $/, $\, and $^W) and set $,, $/, $\, and $^W to values considered sane by the debugger. If there was an eval() error, we print it on the debugger's output. If $onetimedump is defined, we call dumpit if it's set to 'dump', or methods if it's set to 'methods'. Setting it to something else causes the debugger to do the eval but not print the result - handy if you want to do something else with it (the "watch expressions" code does this to get the value of the watch expression but not show it unless it matters).

In any case, we then return the list of output from eval to the caller, and unwinding restores the former version of $@ in @saved as well (the localization of $saved[0] goes away at the end of this scope).

Parameters and variables influencing execution of DB::eval()

DB::eval isn't parameterized in the standard way; this is to keep the debugger's calls to DB::eval() from mucking with @_, among other things. The variables listed below influence DB::eval()'s execution directly.

$evalarg - the thing to actually be eval'ed
$trace - Current state of execution tracing
$single - Current state of single-stepping
$onetimeDump - what is to be displayed after the evaluation
$onetimeDumpDepth - how deep dumpit() should go when dumping results

The following variables are altered by DB::eval() during its execution. They are "stacked" via local(), enabling recursive calls to DB::eval().

@res - used to capture output from actual eval.
$otrace - saved value of $trace.
$osingle - saved value of $single.
$od - saved value of $^D.
$saved[0] - saved value of $@.
$\ - for output of $@ if there is an evaluation error.

The problem of lexicals

The context of DB::eval() presents us with some problems. Obviously, we want to be 'sandboxed' away from the debugger's internals when we do the eval, but we need some way to control how punctuation variables and debugger globals are used.

We can't use local, because the code inside DB::eval can see localized variables; and we can't use my either for the same reason. The code in this routine compromises and uses my.

After this routine is over, we don't have user code executing in the debugger's context, so we can use my freely.

DEBUGGER INITIALIZATION

The debugger starts up in phases.

BASIC SETUP

First, it initializes the environment it wants to run in: turning off warnings during its own compilation, defining variables which it will need to avoid warnings later, setting itself up to not exit when the program terminates, and defaulting to printing return values for the r command.

THREADS SUPPORT

If we are running under a threaded Perl, we require threads and threads::shared if the environment variable PERL5DB_THREADED is set, to enable proper threaded debugger control. -dt can also be used to set this.

Each new thread will be announced and the debugger prompt will always inform you of each new thread created. It will also indicate the thread id in which we are currently running within the prompt like this:

        [tid] DB<$i>

Where [tid] is an integer thread id and $i is the familiar debugger command prompt. The prompt will show: [0] when running under threads, but not actually in a thread. [tid] is consistent with gdb usage.

While running under threads, when you set or delete a breakpoint (etc.), this will apply to all threads, not just the currently running one. When you are in a currently executing thread, you will stay there until it completes. With the current implementation it is not currently possible to hop from one thread to another.

The e and E commands are currently fairly minimal - see h e and h E.

Note that threading support was built into the debugger as of Perl version 5.8.6 and debugger version 1.2.8.

OPTION PROCESSING

The debugger's options are actually spread out over the debugger itself and dumpvar.pl; some of these are variables to be set, while others are subs to be called with a value. To try to make this a little easier to manage, the debugger uses a few data structures to define what options are legal and how they are to be processed.

First, the @options array defines the names of all the options that are to be accepted.

Second, optionVars lists the variables that each option uses to save its state.

Third, %optionAction defines the subroutine to be called to process each option.

Last, the %optionRequire notes modules that must be required if an option is used.

There are a number of initialization-related variables which can be set by putting code to set them in a BEGIN block in the PERL5DB environment variable. These are:

$rl - readline control XXX needs more explanation
$warnLevel - whether or not debugger takes over warning handling
$dieLevel - whether or not debugger takes over die handling
$signalLevel - whether or not debugger takes over signal handling
$pre - preprompt actions (array reference)
$post - postprompt actions (array reference)
$pretype
$CreateTTY - whether or not to create a new TTY for this debugger
$CommandSet - which command set to use (defaults to new, documented set)

The default die, warn, and signal handlers are set up.

The pager to be used is needed next. We try to get it from the environment first. if it's not defined there, we try to find it in the Perl Config.pm. If it's not there, we default to more. We then call the pager() function to save the pager name.

We set up the command to be used to access the man pages, the command recall character (! unless otherwise defined) and the shell escape character (! unless otherwise defined). Yes, these do conflict, and neither works in the debugger at the moment.

We then set up the gigantic string containing the debugger help. We also set the limit on the number of arguments we'll display during a trace.

SETTING UP THE DEBUGGER GREETING

The debugger greeting helps to inform the user how many debuggers are running, and whether the current debugger is the primary or a child.

If we are the primary, we just hang onto our pid so we'll have it when or if we start a child debugger. If we are a child, we'll set things up so we'll have a unique greeting and so the parent will give us our own TTY later.

We save the current contents of the PERLDB_PIDS environment variable because we mess around with it. We'll also need to hang onto it because we'll need it if we restart.

Child debuggers make a label out of the current PID structure recorded in PERLDB_PIDS plus the new PID. They also mark themselves as not having a TTY yet so the parent will give them one later via resetterm().

READING THE RC FILE

The debugger will read a file of initialization options if supplied. If running interactively, this is .perldb; if not, it's perldb.ini.

The debugger does a safety test of the file to be read. It must be owned either by the current user or root, and must only be writable by the owner.

The last thing we do during initialization is determine which subroutine is to be used to obtain a new terminal when a new debugger is started. Right now, the debugger only handles X Windows and OS/2.

RESTART PROCESSING

This section handles the restart command. When the R command is invoked, it tries to capture all of the state it can into environment variables, and then sets PERLDB_RESTART. When we start executing again, we check to see if PERLDB_RESTART is there; if so, we reload all the information that the R command stuffed into the environment variables.

  PERLDB_RESTART   - flag only, contains no restart data itself.
  PERLDB_HIST      - command history, if it's available
  PERLDB_ON_LOAD   - breakpoints set by the rc file
  PERLDB_POSTPONE  - subs that have been loaded/not executed, and have actions
  PERLDB_VISITED   - files that had breakpoints
  PERLDB_FILE_...  - breakpoints for a file
  PERLDB_OPT       - active options
  PERLDB_INC       - the original @INC
  PERLDB_PRETYPE   - preprompt debugger actions
  PERLDB_PRE       - preprompt Perl code
  PERLDB_POST      - post-prompt Perl code
  PERLDB_TYPEAHEAD - typeahead captured by readline()

We chug through all these variables and plug the values saved in them back into the appropriate spots in the debugger.

SETTING UP THE TERMINAL

Now, we'll decide how the debugger is going to interact with the user. If there's no TTY, we set the debugger to run non-stop; there's not going to be anyone there to enter commands.

If there is a TTY, we have to determine who it belongs to before we can proceed. If this is a slave editor or graphical debugger (denoted by the first command-line switch being '-emacs'), we shift this off and set $rl to 0 (XXX ostensibly to do straight reads).

We then determine what the console should be on various systems:

  • Cygwin - We use stdin instead of a separate device.
  • Unix - use /dev/tty.
  • Windows or MSDOS - use con.
  • MacOS - use Dev:Console:Perl Debug if this is the MPW version; Dev: Console if not.

    Note that Mac OS X returns darwin, not MacOS. Also note that the debugger doesn't do anything special for darwin. Maybe it should.

  • VMS - use sys$command.

Several other systems don't use a specific console. We undef $console for those (Windows using a slave editor/graphical debugger, NetWare, OS/2 with a slave editor, Epoc).

If there is a TTY hanging around from a parent, we use that as the console.

SOCKET HANDLING

The debugger is capable of opening a socket and carrying out a debugging session over the socket.

If RemotePort was defined in the options, the debugger assumes that it should try to start a debugging session on that port. It builds the socket and then tries to connect the input and output filehandles to it.

If no RemotePort was defined, and we want to create a TTY on startup, this is probably a situation where multiple debuggers are running (for example, a backticked command that starts up another debugger). We create a new IN and OUT filehandle, and do the necessary mojo to create a new TTY if we know how and if we can.

To finish initialization, we show the debugger greeting, and then call the afterinit() subroutine if there is one.

SUBROUTINES

DB

This gigantic subroutine is the heart of the debugger. Called before every statement, its job is to determine if a breakpoint has been reached, and stop if so; read commands from the user, parse them, and execute them, and hen send execution off to the next statement.

Note that the order in which the commands are processed is very important; some commands earlier in the loop will actually alter the $cmd variable to create other commands to be executed later. This is all highly optimized but can be confusing. Check the comments for each $cmd ... && do {} to see what's happening in any given command.

watchfunction()

watchfunction() is a function that can be defined by the user; it is a function which will be run on each entry to DB::DB; it gets the current package, filename, and line as its parameters.

The watchfunction can do anything it likes; it is executing in the debugger's context, so it has access to all of the debugger's internal data structures and functions.

watchfunction() can control the debugger's actions. Any of the following will cause the debugger to return control to the user's program after watchfunction() executes:

  • Returning a false value from the watchfunction() itself.

  • Altering $single to a false value.

  • Altering $signal to a false value.

  • Turning off the 4 bit in $trace (this also disables the check for watchfunction(). This can be done with

        $trace &= ~4;

GETTING READY TO EXECUTE COMMANDS

The debugger decides to take control if single-step mode is on, the t command was entered, or the user generated a signal. If the program has fallen off the end, we set things up so that entering further commands won't cause trouble, and we say that the program is over.

Special check: if we're in package DB::fake, we've gone through the END block at least once. We set up everything so that we can continue to enter commands and have a valid context to be in.

If the program hasn't finished executing, we scan forward to the next executable line, print that out, build the prompt from the file and line number information, and print that.

If there's an action to be executed for the line we stopped at, execute it. If there are any preprompt actions, execute those as well.

WHERE ARE WE?

XXX Relocate this section?

The debugger normally shows the line corresponding to the current line of execution. Sometimes, though, we want to see the next line, or to move elsewhere in the file. This is done via the $incr, $start, and $max variables.

$incr controls by how many lines the current line should move forward after a command is executed. If set to -1, this indicates that the current line shouldn't change.

$start is the current line. It is used for things like knowing where to move forwards or backwards from when doing an L or - command.

$max tells the debugger where the last line of the current file is. It's used to terminate loops most often.

THE COMMAND LOOP

Most of DB::DB is actually a command parsing and dispatch loop. It comes in two parts:

  • The outer part of the loop, starting at the CMD label. This loop reads a command and then executes it.

  • The inner part of the loop, starting at the PIPE label. This part is wholly contained inside the CMD block and only executes a command. Used to handle commands running inside a pager.

So why have two labels to restart the loop? Because sometimes, it's easier to have a command generate another command and then re-execute the loop to do the new command. This is faster, but perhaps a bit more convoluted.

The null command

A newline entered by itself means re-execute the last command. We grab the command out of $laststep (where it was recorded previously), and copy it back into $cmd to be executed below. If there wasn't any previous command, we'll do nothing below (no command will match). If there was, we also save it in the command history and fall through to allow the command parsing to pick it up.

COMMAND ALIASES

The debugger can create aliases for commands (these are stored in the %alias hash). Before a command is executed, the command loop looks it up in the alias hash and substitutes the contents of the alias for the command, completely replacing it.

MAIN-LINE COMMANDS

All of these commands work up to and after the program being debugged has terminated.

q - quit

Quit the debugger. This entails setting the $fall_off_end flag, so we don't try to execute further, cleaning any restart-related stuff out of the environment, and executing with the last value of $?.

t - trace

Turn tracing on or off. Inverts the appropriate bit in $trace (q.v.).

S - list subroutines matching/not matching a pattern

Walks through %sub, checking to see whether or not to print the name.

X - list variables in current package

Since the V command actually processes this, just change this to the appropriate V command and fall through.

V - list variables

Uses dumpvar.pl to dump out the current values for selected variables.

x - evaluate and print an expression

Hands the expression off to DB::eval, setting it up to print the value via dumpvar.pl instead of just printing it directly.

m - print methods

Just uses DB::methods to determine what methods are available.

f - switch files

. - return to last-executed line.

We set $incr to -1 to indicate that the debugger shouldn't move ahead, and then we look up the line in the magical %dbline hash.

- - back one window

We change $start to be one window back; if we go back past the first line, we set it to be the first line. We ser $incr to put us back at the currently-executing line, and then put a l $start + (list one window from $start) in $cmd to be executed later.

PRE-580 COMMANDS VS. NEW COMMANDS: a, A, b, B, h, l, L, M, o, O, P, v, w, W, <, <<, {, {{

In Perl 5.8.0, a realignment of the commands was done to fix up a number of problems, most notably that the default case of several commands destroying the user's work in setting watchpoints, actions, etc. We wanted, however, to retain the old commands for those who were used to using them or who preferred them. At this point, we check for the new commands and call cmd_wrapper to deal with them instead of processing them in-line.

y - List lexicals in higher scope

Uses PadWalker to find the lexicals supplied as arguments in a scope above the current one and then displays then using dumpvar.pl.

COMMANDS NOT WORKING AFTER PROGRAM ENDS

All of the commands below this point don't work after the program being debugged has ended. All of them check to see if the program has ended; this allows the commands to be relocated without worrying about a 'line of demarcation' above which commands can be entered anytime, and below which they can't.

n - single step, but don't trace down into subs

Done by setting $single to 2, which forces subs to execute straight through when entered (see DB::sub). We also save the n command in $laststep, so a null command knows what to re-execute.

s - single-step, entering subs

Sets $single to 1, which causes DB::sub to continue tracing inside subs. Also saves s as $lastcmd.

c - run continuously, setting an optional breakpoint

Most of the code for this command is taken up with locating the optional breakpoint, which is either a subroutine name or a line number. We set the appropriate one-time-break in @dbline and then turn off single-stepping in this and all call levels above this one.

r - return from a subroutine

For r to work properly, the debugger has to stop execution again immediately after the return is executed. This is done by forcing single-stepping to be on in the call level above the current one. If we are printing return values when a r is executed, set $doret appropriately, and force us out of the command loop.

T - stack trace

Just calls DB::print_trace.

w - List window around current line.

Just calls DB::cmd_w.

W - watch-expression processing.

Just calls DB::cmd_W.

/ - search forward for a string in the source

We take the argument and treat it as a pattern. If it turns out to be a bad one, we return the error we got from trying to eval it and exit. If not, we create some code to do the search and eval it so it can't mess us up.

? - search backward for a string in the source

Same as for /, except the loop runs backwards.

$rc - Recall command

Manages the commands in @hist (which is created if Term::ReadLine reports that the terminal supports history). It find the the command required, puts it into $cmd, and redoes the loop to execute it.

$sh$sh - system() command

Calls the DB::system() to handle the command. This keeps the STDIN and STDOUT from getting messed up.

$rc pattern $rc - Search command history

Another command to manipulate @hist: this one searches it with a pattern. If a command is found, it is placed in $cmd and executed via redo.

$sh - Invoke a shell

Uses DB::system to invoke a shell.

$sh command - Force execution of a command in a shell

Like the above, but the command is passed to the shell. Again, we use DB::system to avoid problems with STDIN and STDOUT.

H - display commands in history

Prints the contents of @hist (if any).

man, doc, perldoc - look up documentation

Just calls runman() to print the appropriate document.

p - print

Builds a print EXPR expression in the $cmd; this will get executed at the bottom of the loop.

= - define command alias

Manipulates %alias to add or list command aliases.

source - read commands from a file.

Opens a lexical filehandle and stacks it on @cmdfhs; DB::readline will pick it up.

save - send current history to a file

Takes the complete history, (not the shrunken version you see with H), and saves it to the given filename, so it can be replayed using source.

Note that all ^(save|source)'s are commented out with a view to minimise recursion.

R - restart

Restart the debugger session.

rerun - rerun the current session

Return to any given position in the true-history list

|, || - pipe output through the pager.

For |, we save OUT (the debugger's output filehandle) and STDOUT (the program's standard output). For ||, we only save OUT. We open a pipe to the pager (restoring the output filehandles if this fails). If this is the | command, we also set up a SIGPIPE handler which will simply set $signal, sending us back into the debugger.

We then trim off the pipe symbols and redo the command loop at the PIPE label, causing us to evaluate the command in $cmd without reading another.

END OF COMMAND PARSING

Anything left in $cmd at this point is a Perl expression that we want to evaluate. We'll always evaluate in the user's context, and fully qualify any variables we might want to address in the DB package.

POST-COMMAND PROCESSING

After each command, we check to see if the command output was piped anywhere. If so, we go through the necessary code to unhook the pipe and go back to our standard filehandles for input and output.

COMMAND LOOP TERMINATION

When commands have finished executing, we come here. If the user closed the input filehandle, we turn on $fall_off_end to emulate a q command. We evaluate any post-prompt items. We restore $@, $!, $^E, $,, $/, $\, and $^W, and return a null list as expected by the Perl interpreter. The interpreter will then execute the next line and then return control to us again.

sub

sub is called whenever a subroutine call happens in the program being debugged. The variable $DB::sub contains the name of the subroutine being called.

The core function of this subroutine is to actually call the sub in the proper context, capturing its output. This of course causes DB::DB to get called again, repeating until the subroutine ends and returns control to DB::sub again. Once control returns, DB::sub figures out whether or not to dump the return value, and returns its captured copy of the return value as its own return value. The value then feeds back into the program being debugged as if DB::sub hadn't been there at all.

sub does all the work of printing the subroutine entry and exit messages enabled by setting $frame. It notes what sub the autoloader got called for, and also prints the return value if needed (for the r command and if the 16 bit is set in $frame).

It also tracks the subroutine call depth by saving the current setting of $single in the @stack package global; if this exceeds the value in $deep, sub automatically turns on printing of the current depth by setting the 4 bit in $single. In any case, it keeps the current setting of stop/don't stop on entry to subs set as it currently is set.

caller() support

If caller() is called from the package DB, it provides some additional data, in the following order:

  • $package

    The package name the sub was in

  • $filename

    The filename it was defined in

  • $line

    The line number it was defined on

  • $subroutine

    The subroutine name; (eval) if an eval().

  • $hasargs

    1 if it has arguments, 0 if not

  • $wantarray

    1 if array context, 0 if scalar context

  • $evaltext

    The eval() text, if any (undefined for eval BLOCK)

  • $is_require

    frame was created by a use or require statement

  • $hints

    pragma information; subject to change between versions

  • $bitmask

    pragma information; subject to change between versions

  • @DB::args

    arguments with which the subroutine was invoked

EXTENDED COMMAND HANDLING AND THE COMMAND API

In Perl 5.8.0, there was a major realignment of the commands and what they did, Most of the changes were to systematize the command structure and to eliminate commands that threw away user input without checking.

The following sections describe the code added to make it easy to support multiple command sets with conflicting command names. This section is a start at unifying all command processing to make it simpler to develop commands.

Note that all the cmd_[a-zA-Z] subroutines require the command name, a line number, and $dbline (the current line) as arguments.

Support functions in this section which have multiple modes of failure die on error; the rest simply return a false value.

The user-interface functions (all of the cmd_* functions) just output error messages.

%set

The %set hash defines the mapping from command letter to subroutine name suffix.

%set is a two-level hash, indexed by set name and then by command name. Note that trying to set the CommandSet to foobar simply results in the 5.8.0 command set being used, since there's no top-level entry for foobar.

cmd_wrapper() (API)

cmd_wrapper() allows the debugger to switch command sets depending on the value of the CommandSet option.

It tries to look up the command in the %set package-level lexical (which means external entities can't fiddle with it) and create the name of the sub to call based on the value found in the hash (if it's there). All of the commands to be handled in a set have to be added to %set; if they aren't found, the 5.8.0 equivalent is called (if there is one).

This code uses symbolic references.

cmd_a (command)

The a command handles pre-execution actions. These are associated with a particular line, so they're stored in %dbline. We default to the current line if none is specified.

cmd_A (command)

Delete actions. Similar to above, except the delete code is in a separate subroutine, delete_action.

delete_action (API)

delete_action accepts either a line number or undef. If a line number is specified, we check for the line being executable (if it's not, it couldn't have had an action). If it is, we just take the action off (this will get any kind of an action, including breakpoints).

cmd_b (command)

Set breakpoints. Since breakpoints can be set in so many places, in so many ways, conditionally or not, the breakpoint code is kind of complex. Mostly, we try to parse the command type, and then shuttle it off to an appropriate subroutine to actually do the work of setting the breakpoint in the right place.

break_on_load (API)

We want to break when this file is loaded. Mark this file in the %break_on_load hash, and note that it has a breakpoint in %had_breakpoints.

report_break_on_load (API)

Gives us an array of filenames that are set to break on load. Note that only files with break-on-load are in here, so simply showing the keys suffices.

cmd_b_load (command)

We take the file passed in and try to find it in %INC (which maps modules to files they came from). We mark those files for break-on-load via break_on_load and then report that it was done.

$filename_error (API package global)

Several of the functions we need to implement in the API need to work both on the current file and on other files. We don't want to duplicate code, so $filename_error is used to contain the name of the file that's being worked on (if it's not the current one).

We can now build functions in pairs: the basic function works on the current file, and uses $filename_error as part of its error message. Since this is initialized to "", no filename will appear when we are working on the current file.

The second function is a wrapper which does the following:

  • Localizes $filename_error and sets it to the name of the file to be processed.

  • Localizes the *dbline glob and reassigns it to point to the file we want to process.

  • Calls the first function.

    The first function works on the current file (i.e., the one we changed to), and prints $filename_error in the error message (the name of the other file) if it needs to. When the functions return, *dbline is restored to point to the actual current file (the one we're executing in) and $filename_error is restored to "". This restores everything to the way it was before the second function was called at all.

    See the comments in breakable_line and breakable_line_in_file for more details.

breakable_line(from, to) (API)

The subroutine decides whether or not a line in the current file is breakable. It walks through @dbline within the range of lines specified, looking for the first line that is breakable.

If $to is greater than $from, the search moves forwards, finding the first line after $to that's breakable, if there is one.

If $from is greater than $to, the search goes backwards, finding the first line before $to that's breakable, if there is one.

breakable_line_in_filename(file, from, to) (API)

Like breakable_line, but look in another file.

break_on_line(lineno, [condition]) (API)

Adds a breakpoint with the specified condition (or 1 if no condition was specified) to the specified line. Dies if it can't.

cmd_b_line(line, [condition]) (command)

Wrapper for break_on_line. Prints the failure message if it doesn't work.

break_on_filename_line(file, line, [condition]) (API)

Switches to the file specified and then calls break_on_line to set the breakpoint.

break_on_filename_line_range(file, from, to, [condition]) (API)

Switch to another file, search the range of lines specified for an executable one, and put a breakpoint on the first one you find.

subroutine_filename_lines(subname, [condition]) (API)

Search for a subroutine within a given file. The condition is ignored. Uses find_sub to locate the desired subroutine.

break_subroutine(subname) (API)

Places a break on the first line possible in the specified subroutine. Uses subroutine_filename_lines to find the subroutine, and break_on_filename_line_range to place the break.

cmd_b_sub(subname, [condition]) (command)

We take the incoming subroutine name and fully-qualify it as best we can.

  1. If it's already fully-qualified, leave it alone.
  2. Try putting it in the current package.
  3. If it's not there, try putting it in CORE::GLOBAL if it exists there.
  4. If it starts with '::', put it in 'main::'.

After all this cleanup, we call break_subroutine to try to set the breakpoint.

cmd_B - delete breakpoint(s) (command)

The command mostly parses the command line and tries to turn the argument into a line spec. If it can't, it uses the current line. It then calls delete_breakpoint to actually do the work.

If * is specified, cmd_B calls delete_breakpoint with no arguments, thereby deleting all the breakpoints.

delete_breakpoint([line]) (API)

This actually does the work of deleting either a single breakpoint, or all of them.

For a single line, we look for it in @dbline. If it's nonbreakable, we just drop out with a message saying so. If it is, we remove the condition part of the 'condition\0action' that says there's a breakpoint here. If, after we've done that, there's nothing left, we delete the corresponding line in %dbline to signal that no action needs to be taken for this line.

For all breakpoints, we iterate through the keys of %had_breakpoints, which lists all currently-loaded files which have breakpoints. We then look at each line in each of these files, temporarily switching the %dbline and @dbline structures to point to the files in question, and do what we did in the single line case: delete the condition in @dbline, and delete the key in %dbline if nothing's left.

We then wholesale delete %postponed, %postponed_file, and %break_on_load, because these structures contain breakpoints for files and code that haven't been loaded yet. We can just kill these off because there are no magical debugger structures associated with them.

cmd_stop (command)

This is meant to be part of the new command API, but it isn't called or used anywhere else in the debugger. XXX It is probably meant for use in development of new commands.

cmd_e - threads

Display the current thread id:

        e

This could be how (when implemented) to send commands to this thread id (e cmd) or that thread id (e tid cmd).

cmd_E - list of thread ids

Display the list of available thread ids:

        E

This could be used (when implemented) to send commands to all threads (E cmd).

cmd_h - help command (command)

Does the work of either

  • Showing all the debugger help

  • Showing help for a specific command

cmd_i - inheritance display

Display the (nested) parentage of the module or object given.

cmd_l - list lines (command)

Most of the command is taken up with transforming all the different line specification syntaxes into 'start-stop'. After that is done, the command runs a loop over @dbline for the specified range of lines. It handles the printing of each line and any markers (==> for current line, b for break on this line, a for action on this line, : for this line breakable).

We save the last line listed in the $start global for further listing later.

cmd_L - list breakpoints, actions, and watch expressions (command)

To list breakpoints, the command has to look determine where all of them are first. It starts a %had_breakpoints, which tells us what all files have breakpoints and/or actions. For each file, we switch the *dbline glob (the magic source and breakpoint data structures) to the file, and then look through %dbline for lines with breakpoints and/or actions, listing them out. We look through %postponed not-yet-compiled subroutines that have breakpoints, and through %postponed_file for not-yet-require'd files that have breakpoints.

Watchpoints are simpler: we just list the entries in @to_watch.

cmd_M - list modules (command)

Just call list_modules.

cmd_o - options (command)

If this is just o by itself, we list the current settings via dump_option. If there's a nonblank value following it, we pass that on to parse_options for processing.

cmd_O - nonexistent in 5.8.x (command)

Advises the user that the O command has been renamed.

cmd_v - view window (command)

Uses the $preview variable set in the second BEGIN block (q.v.) to move back a few lines to list the selected line in context. Uses cmd_l to do the actual listing after figuring out the range of line to request.

cmd_w - add a watch expression (command)

The 5.8 version of this command adds a watch expression if one is specified; it does nothing if entered with no operands.

We extract the expression, save it, evaluate it in the user's context, and save the value. We'll re-evaluate it each time the debugger passes a line, and will stop (see the code at the top of the command loop) if the value of any of the expressions changes.

cmd_W - delete watch expressions (command)

This command accepts either a watch expression to be removed from the list of watch expressions, or * to delete them all.

If * is specified, we simply empty the watch expression list and the watch expression value list. We also turn off the bit that says we've got watch expressions.

If an expression (or partial expression) is specified, we pattern-match through the expressions and remove the ones that match. We also discard the corresponding values. If no watch expressions are left, we turn off the watching expressions bit.

SUPPORT ROUTINES

These are general support routines that are used in a number of places throughout the debugger.

cmd_P

Something to do with assertions

save

save() saves the user's versions of globals that would mess us up in @saved, and installs the versions we like better.

print_lineinfo - show where we are now

print_lineinfo prints whatever it is that it is handed; it prints it to the $LINEINFO filehandle instead of just printing it to STDOUT. This allows us to feed line information to a slave editor without messing up the debugger output.

postponed_sub

Handles setting postponed breakpoints in subroutines once they're compiled. For breakpoints, we use DB::find_sub to locate the source file and line range for the subroutine, then mark the file as having a breakpoint, temporarily switch the *dbline glob over to the source file, and then search the given range of lines to find a breakable line. If we find one, we set the breakpoint on it, deleting the breakpoint from %postponed.

postponed

Called after each required file is compiled, but before it is executed; also called if the name of a just-compiled subroutine is a key of %postponed. Propagates saved breakpoints (from b compile, b load, etc.) into the just-compiled code.

If this is a require'd file, the incoming parameter is the glob *{"_<$filename"}, with $filename the name of the require'd file.

If it's a subroutine, the incoming parameter is the subroutine name.

dumpit

dumpit is the debugger's wrapper around dumpvar.pl.

It gets a filehandle (to which dumpvar.pl's output will be directed) and a reference to a variable (the thing to be dumped) as its input.

The incoming filehandle is selected for output (dumpvar.pl is printing to the currently-selected filehandle, thank you very much). The current values of the package globals $single and $trace are backed up in lexicals, and they are turned off (this keeps the debugger from trying to single-step through dumpvar.pl (I think.)). $frame is localized to preserve its current value and it is set to zero to prevent entry/exit messages from printing, and $doret is localized as well and set to -2 to prevent return values from being shown.

dumpit() then checks to see if it needs to load dumpvar.pl and tries to load it (note: if you have a dumpvar.pl ahead of the installed version in @INC, yours will be used instead. Possible security problem?).

It then checks to see if the subroutine main::dumpValue is now defined (it should have been defined by dumpvar.pl). If it has, dumpit() localizes the globals necessary for things to be sane when main::dumpValue() is called, and picks up the variable to be dumped from the parameter list.

It checks the package global %options to see if there's a dumpDepth specified. If not, -1 is assumed; if so, the supplied value gets passed on to dumpvar.pl. This tells dumpvar.pl where to leave off when dumping a structure: -1 means dump everything.

dumpValue() is then called if possible; if not, dumpit()just prints a warning.

In either case, $single, $trace, $frame, and $doret are restored and we then return to the caller.

print_trace

print_trace's job is to print a stack trace. It does this via the dump_trace routine, which actually does all the ferreting-out of the stack trace data. print_trace takes care of formatting it nicely and printing it to the proper filehandle.

Parameters:

  • The filehandle to print to.

  • How many frames to skip before starting trace.

  • How many frames to print.

  • A flag: if true, print a short trace without filenames, line numbers, or arguments

The original comment below seems to be noting that the traceback may not be correct if this routine is called in a tied method.

dump_trace(skip[,count])

Actually collect the traceback information available via caller(). It does some filtering and cleanup of the data, but mostly it just collects it to make print_trace()'s job easier.

skip defines the number of stack frames to be skipped, working backwards from the most current. count determines the total number of frames to be returned; all of them (well, the first 10^9) are returned if count is omitted.

This routine returns a list of hashes, from most-recent to least-recent stack frame. Each has the following keys and values:

  • context - . (null), $ (scalar), or @ (array)
  • sub - subroutine name, or eval information
  • args - undef, or a reference to an array of arguments
  • file - the file in which this item was defined (if any)
  • line - the line on which it was defined

action()

action() takes input provided as the argument to an add-action command, either pre- or post-, and makes sure it's a complete command. It doesn't do any fancy parsing; it just keeps reading input until it gets a string without a trailing backslash.

unbalanced

This routine mostly just packages up a regular expression to be used to check that the thing it's being matched against has properly-matched curly braces.

Of note is the definition of the $balanced_brace_re global via ||=, which speeds things up by only creating the qr//'ed expression once; if it's already defined, we don't try to define it again. A speed hack.

gets()

gets() is a primitive (very primitive) routine to read continuations. It was devised for reading continuations for actions. it just reads more input with readline() and returns it.

DB::system() - handle calls to<system()> without messing up the debugger

The system() function assumes that it can just go ahead and use STDIN and STDOUT, but under the debugger, we want it to use the debugger's input and outout filehandles.

DB::system() socks away the program's STDIN and STDOUT, and then substitutes the debugger's IN and OUT filehandles for them. It does the system() call, and then puts everything back again.

TTY MANAGEMENT

The subs here do some of the terminal management for multiple debuggers.

setterm

Top-level function called when we want to set up a new terminal for use by the debugger.

If the noTTY debugger option was set, we'll either use the terminal supplied (the value of the noTTY option), or we'll use Term::Rendezvous to find one. If we're a forked debugger, we call resetterm to try to get a whole new terminal if we can.

In either case, we set up the terminal next. If the ReadLine option was true, we'll get a Term::ReadLine object for the current terminal and save the appropriate attributes. We then

GET_FORK_TTY EXAMPLE FUNCTIONS

When the process being debugged forks, or the process invokes a command via system() which starts a new debugger, we need to be able to get a new IN and OUT filehandle for the new debugger. Otherwise, the two processes fight over the terminal, and you can never quite be sure who's going to get the input you're typing.

get_fork_TTY is a glob-aliased function which calls the real function that is tasked with doing all the necessary operating system mojo to get a new TTY (and probably another window) and to direct the new debugger to read and write there.

The debugger provides get_fork_TTY functions which work for X Windows and OS/2. Other systems are not supported. You are encouraged to write get_fork_TTY functions which work for your platform and contribute them.

xterm_get_fork_TTY

This function provides the get_fork_TTY function for X windows. If a program running under the debugger forks, a new <xterm> window is opened and the subsidiary debugger is directed there.

The open() call is of particular note here. We have the new xterm we're spawning route file number 3 to STDOUT, and then execute the tty command (which prints the device name of the TTY we'll want to use for input and output to STDOUT, then sleep for a very long time, routing this output to file number 3. This way we can simply read from the <XT> filehandle (which is STDOUT from the commands we ran) to get the TTY we want to use.

Only works if xterm is in your path and $ENV{DISPLAY}, etc. are properly set up.

os2_get_fork_TTY

XXX It behooves an OS/2 expert to write the necessary documentation for this!

create_IN_OUT($flags)

Create a new pair of filehandles, pointing to a new TTY. If impossible, try to diagnose why.

Flags are:

  • 1 - Don't know how to create a new TTY.
  • 2 - Debugger has forked, but we can't get a new TTY.
  • 4 - standard debugger startup is happening.

resetterm

Handles rejiggering the prompt when we've forked off a new debugger.

If the new debugger happened because of a system() that invoked a program under the debugger, the arrow between the old pid and the new in the prompt has two dashes instead of one.

We take the current list of pids and add this one to the end. If there isn't any list yet, we make one up out of the initial pid associated with the terminal and our new pid, sticking an arrow (either one-dashed or two dashed) in between them.

If CreateTTY is off, or resetterm was called with no arguments, we don't try to create a new IN and OUT filehandle. Otherwise, we go ahead and try to do that.

readline

First, we handle stuff in the typeahead buffer. If there is any, we shift off the next line, print a message saying we got it, add it to the terminal history (if possible), and return it.

If there's nothing in the typeahead buffer, check the command filehandle stack. If there are any filehandles there, read from the last one, and return the line if we got one. If not, we pop the filehandle off and close it, and try the next one up the stack.

If we've emptied the filehandle stack, we check to see if we've got a socket open, and we read that and return it if we do. If we don't, we just call the core readline() and return its value.

OPTIONS SUPPORT ROUTINES

These routines handle listing and setting option values.

dump_option - list the current value of an option setting

This routine uses option_val to look up the value for an option. It cleans up escaped single-quotes and then displays the option and its value.

option_val - find the current value of an option

This can't just be a simple hash lookup because of the indirect way that the option values are stored. Some are retrieved by calling a subroutine, some are just variables.

You must supply a default value to be used in case the option isn't set.

parse_options

Handles the parsing and execution of option setting/displaying commands.

An option entered by itself is assumed to be set me to 1 (the default value) if the option is a boolean one. If not, the user is prompted to enter a valid value or to query the current value (via option? ).

If option=value is entered, we try to extract a quoted string from the value (if it is quoted). If it's not, we just use the whole value as-is.

We load any modules required to service this option, and then we set it: if it just gets stuck in a variable, we do that; if there's a subroutine to handle setting the option, we call that.

Finally, if we're running in interactive mode, we display the effect of the user's command back to the terminal, skipping this if we're setting things during initialization.

RESTART SUPPORT

These routines are used to store (and restore) lists of items in environment variables during a restart.

set_list

Set_list packages up items to be stored in a set of environment variables (VAR_n, containing the number of items, and VAR_0, VAR_1, etc., containing the values). Values outside the standard ASCII charset are stored by encoding then as hexadecimal values.

get_list

Reverse the set_list operation: grab VAR_n to see how many we should be getting back, and then pull VAR_0, VAR_1. etc. back out.

MISCELLANEOUS SIGNAL AND I/O MANAGEMENT

catch()

The catch() subroutine is the essence of fast and low-impact. We simply set an already-existing global scalar variable to a constant value. This avoids allocating any memory possibly in the middle of something that will get all confused if we do, particularly under unsafe signals.

warn()

warn emits a warning, by joining together its arguments and printing them, with couple of fillips.

If the composited message doesn't end with a newline, we automatically add $! and a newline to the end of the message. The subroutine expects $OUT to be set to the filehandle to be used to output warnings; it makes no assumptions about what filehandles are available.

INITIALIZATION TTY SUPPORT

reset_IN_OUT

This routine handles restoring the debugger's input and output filehandles after we've tried and failed to move them elsewhere. In addition, it assigns the debugger's output filehandle to $LINEINFO if it was already open there.

OPTION SUPPORT ROUTINES

The following routines are used to process some of the more complicated debugger options.

TTY

Sets the input and output filehandles to the specified files or pipes. If the terminal supports switching, we go ahead and do it. If not, and there's already a terminal in place, we save the information to take effect on restart.

If there's no terminal yet (for instance, during debugger initialization), we go ahead and set $console and $tty to the file indicated.

noTTY

Sets the $notty global, controlling whether or not the debugger tries to get a terminal to read from. If called after a terminal is already in place, we save the value to use it if we're restarted.

ReadLine

Sets the $rl option variable. If 0, we use Term::ReadLine::Stub (essentially, no readline processing on this terminal). Otherwise, we use Term::ReadLine. Can't be changed after a terminal's in place; we save the value in case a restart is done so we can change it then.

RemotePort

Sets the port that the debugger will try to connect to when starting up. If the terminal's already been set up, we can't do it, but we remember the setting in case the user does a restart.

tkRunning

Checks with the terminal to see if Tk is running, and returns true or false. Returns false if the current terminal doesn't support readline.

NonStop

Sets nonstop mode. If a terminal's already been set up, it's too late; the debugger remembers the setting in case you restart, though.

pager

Set up the $pager variable. Adds a pipe to the front unless there's one there already.

shellBang

Sets the shell escape command, and generates a printable copy to be used in the help.

ornaments

If the terminal has its own ornaments, fetch them. Otherwise accept whatever was passed as the argument. (This means you can't override the terminal's ornaments.)

recallCommand

Sets the recall command, and builds a printable version which will appear in the help text.

LineInfo - where the line number information goes

Called with no arguments, returns the file or pipe that line info should go to.

Called with an argument (a file or a pipe), it opens that onto the LINEINFO filehandle, unbuffers the filehandle, and then returns the file or pipe again to the caller.

COMMAND SUPPORT ROUTINES

These subroutines provide functionality for various commands.

list_modules

For the M command: list modules loaded and their versions. Essentially just runs through the keys in %INC, picks each package's $VERSION variable, gets the file name, and formats the information for output.

sethelp()

Sets up the monster string used to format and print the help.

HELP MESSAGE FORMAT

The help message is a peculiar format unto itself; it mixes pod ornaments ( ) with tabs to come up with a format that's fairly easy to parse and portable, but which still allows the help to be a little nicer than just plain text.

Essentially, you define the command name (usually marked up with and ), followed by a tab, and then the descriptive text, ending in a newline. The descriptive text can also be marked up in the same way. If you need to continue the descriptive text to another line, start that line with just tabs and then enter the marked-up text.

If you are modifying the help text, be careful. The help-string parser is not very sophisticated, and if you don't follow these rules it will mangle the help beyond hope until you fix the string.

print_help()

Most of what print_help does is just text formatting. It finds the B and I ornaments, cleans them off, and substitutes the proper terminal control characters to simulate them (courtesy of Term::ReadLine::TermCap).

fix_less

This routine does a lot of gyrations to be sure that the pager is less. It checks for less masquerading as more and records the result in $ENV{LESS} so we don't have to go through doing the stats again.

DIE AND WARN MANAGEMENT

diesignal

diesignal is a just-drop-dead die handler. It's most useful when trying to debug a debugger problem.

It does its best to report the error that occurred, and then forces the program, debugger, and everything to die.

dbwarn

The debugger's own default $SIG{__WARN__} handler. We load Carp to be able to get a stack trace, and output the warning message vi DB::dbwarn().

dbdie

The debugger's own $SIG{__DIE__} handler. Handles providing a stack trace by loading Carp and calling Carp::longmess() to get it. We turn off single stepping and tracing during the call to Carp::longmess to avoid debugging it - we just want to use it.

If dieLevel is zero, we let the program being debugged handle the exceptions. If it's 1, you get backtraces for any exception. If it's 2, the debugger takes over all exception handling, printing a backtrace and displaying the exception via its dbwarn() routine.

warnlevel()

Set the $DB::warnLevel variable that stores the value of the warnLevel option. Calling warnLevel() with a positive value results in the debugger taking over all warning handlers. Setting warnLevel to zero leaves any warning handlers set up by the program being debugged in place.

dielevel

Similar to warnLevel. Non-zero values for dieLevel result in the DB::dbdie() function overriding any other die() handler. Setting it to zero lets you use your own die() handler.

signalLevel

Number three in a series: set signalLevel to zero to keep your own signal handler for SIGSEGV and/or SIGBUS. Otherwise, the debugger takes over and handles them with DB::diesignal().

SUBROUTINE DECODING SUPPORT

These subroutines are used during the x and X commands to try to produce as much information as possible about a code reference. They use the Devel::Peek manpage to try to find the glob in which this code reference lives (if it does) - this allows us to actually code references which correspond to named subroutines (including those aliased via glob assignment).

CvGV_name()

Wrapper for CvGV_name_or_bust; tries to get the name of a reference via that routine. If this fails, return the reference again (when the reference is stringified, it'll come out as SOMETHING(0x...)).

CvGV_name_or_bust coderef

Calls the Devel::Peek manpage to try to find the glob the ref lives in; returns undef if the Devel::Peek manpage can't be loaded, or if Devel::Peek::CvGV can't find a glob for this ref.

Returns package::glob name if the code ref is found in a glob.

find_sub

A utility routine used in various places; finds the file where a subroutine was defined, and returns that filename and a line-number range.

Tries to use @sub first; if it can't find it there, it tries building a reference to the subroutine and uses CvGV_name_or_bust to locate it, loading it into @sub as a side effect (XXX I think). If it can't find it this way, it brute-force searches %sub, checking for identical references.

methods

A subroutine that uses the utility function methods_via to find all the methods in the class corresponding to the current reference and in UNIVERSAL.

methods_via($class, $prefix, $crawl_upward)

methods_via does the work of crawling up the @ISA tree and reporting all the parent class methods. $class is the name of the next class to try; $prefix is the message prefix, which gets built up as we go up the @ISA tree to show parentage; $crawl_upward is 1 if we should try to go higher in the @ISA tree, 0 if we should stop.

setman - figure out which command to use to show documentation

Just checks the contents of $^O and sets the $doccmd global accordingly.

runman - run the appropriate command to show documentation

Accepts a man page name; runs the appropriate command to display it (set up during debugger initialization). Uses DB::system to avoid mucking up the program's STDIN and STDOUT.

DEBUGGER INITIALIZATION - THE SECOND BEGIN BLOCK

Because of the way the debugger interface to the Perl core is designed, any debugger package globals that DB::sub() requires have to be defined before any subroutines can be called. These are defined in the second BEGIN block.

This block sets things up so that (basically) the world is sane before the debugger starts executing. We set up various variables that the debugger has to have set up before the Perl core starts running:

  • The debugger's own filehandles (copies of STD and STDOUT for now).

  • Characters for shell escapes, the recall command, and the history command.

  • The maximum recursion depth.

  • The size of a w command's window.

  • The before-this-line context to be printed in a v (view a window around this line) command.

  • The fact that we're not in a sub at all right now.

  • The default SIGINT handler for the debugger.

  • The appropriate value of the flag in $^D that says the debugger is running

  • The current debugger recursion level

  • The list of postponed items and the $single stack (XXX define this)

  • That we want no return values and no subroutine entry/exit trace.

READLINE SUPPORT - COMPLETION FUNCTION

db_complete

readline support - adds command completion to basic readline.

Returns a list of possible completions to readline when invoked. readline will print the longest common substring following the text already entered.

If there is only a single possible completion, readline will use it in full.

This code uses map and grep heavily to create lists of possible completion. Think LISP in this section.

b postpone|compile

  • Find all the subroutines that might match in this package

  • Add postpone, load, and compile as possibles (we may be completing the keyword itself)

  • Include all the rest of the subs that are known

  • grep out the ones that match the text we have so far

  • Return this as the list of possible completions

b load

Get all the possible files from @INC as it currently stands and select the ones that match the text so far.

V (list variable) and m (list modules)

There are two entry points for these commands:

Unqualified package names

Get the top-level packages and grab everything that matches the text so far. For each match, recursively complete the partial packages to get all possible matching packages. Return this sorted list.

Qualified package names

Take a partially-qualified package and find all subpackages for it by getting all the subpackages for the package so far, matching all the subpackages against the text, and discarding all of them which start with 'main::'. Return this list.

f - switch files

Here, we want to get a fully-qualified filename for the f command. Possibilities are:

  1. The original source file itself
  2. A file from @INC
  3. An eval (the debugger gets a (eval N) fake file for each eval).

Under the debugger, source files are represented as _</fullpath/to/file (evals are _<(eval NNN)) keys in %main::. We pull all of these out of %main::, add the initial source file, and extract the ones that match the completion text so far.

Subroutine name completion

We look through all of the defined subs (the keys of %sub) and return both all the possible matches to the subroutine name plus all the matches qualified to the current package.

Scalar, array, and hash completion: partially qualified package

Much like the above, except we have to do a little more cleanup:

  • Determine the package that the symbol is in. Put it in :: (effectively main::) if no package is specified.

  • Figure out the prefix vs. what needs completing.

  • Look through all the symbols in the package. grep out all the possible hashes/arrays/scalars, and then grep the possible matches out of those. map the prefix onto all the possibilities.

  • If there's only one hit, and it's a package qualifier, and it's not equal to the initial text, re-complete it using the symbol we actually found.

Symbol completion: current package or package main.

  • If it's main, delete main to just get :: leading.

  • We set the prefix to the item's sigil, and trim off the sigil to get the text to be completed.

  • If the package is :: (main), create an empty list; if it's something else, create a list of all the packages known. Append whichever list to a list of all the possible symbols in the current package. grep out the matches to the text entered so far, then map the prefix back onto the symbols.

  • If there's only one hit, it's a package qualifier, and it's not equal to the initial text, recomplete using this symbol.

Options

We use option_val() to look up the current value of the option. If there's only a single value, we complete the command in such a way that it is a complete command for setting the option in question. If there are multiple possible values, we generate a command consisting of the option plus a trailing question mark, which, if executed, will list the current value of the option.

Filename completion

For entering filenames. We simply call readline's filename_list() method with the completion text to get the possible completions.

MISCELLANEOUS SUPPORT FUNCTIONS

Functions that possibly ought to be somewhere else.

end_report

Say we're done.

clean_ENV

If we have $ini_pids, save it in the environment; else remove it from the environment. Used by the R (restart) command.

rerun

Rerun the current session to:

    rerun        current position
    rerun 4      command number 4
    rerun -4     current command minus 4 (go back 4 steps)

Whether this always makes sense, in the current context is unknowable, and is in part left as a useful exersize for the reader. This sub returns the appropriate arguments to rerun the current session.

restart

Restarting the debugger is a complex operation that occurs in several phases. First, we try to reconstruct the command line that was used to invoke Perl and the debugger.

After the command line has been reconstructed, the next step is to save the debugger's status in environment variables. The DB::set_list routine is used to save aggregate variables (both hashes and arrays); scalars are just popped into environment variables directly.

The most complex part of this is the saving of all of the breakpoints. They can live in an awful lot of places, and we have to go through all of them, find the breakpoints, and then save them in the appropriate environment variable via DB::set_list.

After all the debugger status has been saved, we take the command we built up and then return it, so we can exec() it. The debugger will spot the PERLDB_RESTART environment variable and realize it needs to reload its state from the environment.

END PROCESSING - THE END BLOCK

Come here at the very end of processing. We want to go into a loop where we allow the user to enter commands and interact with the debugger, but we don't want anything else to execute.

First we set the $finished variable, so that some commands that shouldn't be run after the end of program quit working.

We then figure out whether we're truly done (as in the user entered a q command, or we finished execution while running nonstop). If we aren't, we set $single to 1 (causing the debugger to get control again).

We then call DB::fake::at_exit(), which returns the Use 'q' to quit ... message and returns control to the debugger. Repeat.

When the user finally enters a q command, $fall_off_end is set to 1 and the END block simply exits with $single set to 0 (don't break, run to completion.).

PRE-5.8 COMMANDS

Some of the commands changed function quite a bit in the 5.8 command realignment, so much so that the old code had to be replaced completely. Because we wanted to retain the option of being able to go back to the former command set, we moved the old code off to this section.

There's an awful lot of duplicated code here. We've duplicated the comments to keep things clear.

Null command

Does nothing. Used to turn off commands.

Old a command.

This version added actions if you supplied them, and deleted them if you didn't.

Old b command

Add breakpoints.

Old D command.

Delete all breakpoints unconditionally.

Old h command

Print help. Defaults to printing the long-form help; the 5.8 version prints the summary by default.

Old W command

W <expr> adds a watch expression, W deletes them all.

PRE-AND-POST-PROMPT COMMANDS AND ACTIONS

The debugger used to have a bunch of nearly-identical code to handle the pre-and-post-prompt action commands. cmd_pre590_prepost and cmd_prepost unify all this into one set of code to handle the appropriate actions.

cmd_pre590_prepost

A small wrapper around cmd_prepost; it makes sure that the default doesn't do something destructive. In pre 5.8 debuggers, the default action was to delete all the actions.

cmd_prepost

Actually does all the handling for <, >, {{, {, etc. Since the lists of actions are all held in arrays that are pointed to by references anyway, all we have to do is pick the right array reference and then use generic code to all, delete, or list actions.

DB::fake

Contains the at_exit routine that the debugger uses to issue the Debugged program terminated ... message after the program completes. See the END block documentation for more details.


perlartistic - the Perl Artistic License

  • The "Artistic License"
    • Preamble
    • Definitions
    • Conditions

NAME

perlartistic - the Perl Artistic License

SYNOPSIS

 You can refer to this document in Pod via "L<perlartistic>"
 Or you can see this document by entering "perldoc perlartistic"

DESCRIPTION

This is "The Artistic License". It's here so that modules, programs, etc., that want to declare this as their distribution license, can link to it.

It is also one of the two licenses Perl allows itself to be redistributed and/or modified; for the other one, the GNU General Public License, see the the perlgpl manpage.

The "Artistic License"

Preamble

The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications.

Definitions

"Package"

refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification.

"Standard Version"

refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder as specified below.

"Copyright Holder"

is whoever is named in the copyright or copyrights for the package.

"You"

is you, if you're thinking about copying or distributing this Package.

"Reasonable copying fee"

is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.)

"Freely Available"

means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it.

Conditions

  1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers.

  2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version.

  3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following:

    a)

    place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as uunet.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package.

    4. b)

    use the modified Package only within your corporation or organization.

    c)

    rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version.

    d)

    make other distribution arrangements with the Copyright Holder.

  4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following:

    a)

    distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version.

    5. b)

    accompany the distribution with the machine-readable source of the Package with your modifications.

    c)

    give non-standard executables non-standard names, and clearly document the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version.

    d)

    make other distribution arrangements with the Copyright Holder.

  5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. You may embed this Package's interpreter within an executable of yours (by linking); this shall be construed as a mere form of aggregation, provided that the complete Standard Version of the interpreter is so embedded.

  6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whoever generated them, and may be sold commercially, and may be aggregated with this Package. If such scripts or library files are aggregated with this Package via the so-called "undump" or "unexec" methods of producing a binary executable image, then distribution of such an image shall neither be construed as a distribution of this Package nor shall it fall under the restrictions of Paragraphs 3 and 4, provided that you do not represent such an executable image as a Standard Version of this Package.

  7. C subroutines (or comparably compiled subroutines in other languages) supplied by you and linked into this Package in order to emulate subroutines and variables of the language defined by this Package shall not be considered part of this Package, but are the equivalent of input as in Paragraph 6, provided these subroutines do not change the language in any way that would cause it to fail the regression tests for the language.

  8. Aggregation of this Package with a commercial distribution is always permitted provided that the use of this Package is embedded; that is, when no overt attempt is made to make this Package's interfaces visible to the end user of the commercial distribution. Such use shall not be construed as a distribution of this Package.

  9. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission.

  10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The End


perlbook - Perl book information

NAME

perlbook - Perl book information

DESCRIPTION

The Camel Book, officially known as Programming Perl, Third Edition, by Larry Wall et al, is the definitive reference work covering nearly all of Perl. You can order it and other Perl books from O'Reilly & Associates, 1-800-998-9938. Local/overseas is +1 707 829 0515. If you can locate an O'Reilly order form, you can also fax to +1 707 829 0104. If you're web-connected, you can even mosey on over to http://www.oreilly.com/ for an online order form.

Other Perl books from various publishers and authors can be found listed in the perlfaq2 manpage or on the web at http://books.perl.org/.


perlgpl - the GNU General Public License, version 2

  • GNU GENERAL PUBLIC LICENSE

NAME

perlgpl - the GNU General Public License, version 2

SYNOPSIS

 You can refer to this document in Pod via "L<perlgpl>"
 Or you can see this document by entering "perldoc perlgpl"

DESCRIPTION

This is "The GNU General Public License, version 2". It's here so that modules, programs, etc., that want to declare this as their distribution license, can link to it.

It is also one of the two licenses Perl allows itself to be redistributed and/or modified; for the other one, the Perl Artistic License, see the the perlartistic manpage.

GNU GENERAL PUBLIC LICENSE

                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991
 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          59 Temple Place - Suite 330, Boston, MA
                          02111-1307, USA.
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
                            Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

--

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.
    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.
    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

--

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

--

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

--

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

                            NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

--

        Appendix: How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) 19yy  <name of author>
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

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

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type "show w".
    This is free software, and you are welcome to redistribute it
    under certain conditions; type "show c" for details.

The hypothetical commands "show w" and "show c" should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than "show w" and "show c"; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  "Gnomovision" (which makes passes at compilers) written by James Hacker.
  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

[End.]


perlhist - the Perl history records

  • INTRODUCTION
  • THE KEEPERS OF THE PUMPKIN
    • PUMPKIN?
  • THE RECORDS
    • SELECTED RELEASE SIZES
    • SELECTED PATCH SIZES
  • THE KEEPERS OF THE RECORDS

NAME

perlhist - the Perl history records

DESCRIPTION

This document aims to record the Perl source code releases.

INTRODUCTION

Perl history in brief, by Larry Wall:

    Perl 0 introduced Perl to my officemates.
    Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
        /(...|...)/.  \(Dan Faigin still hasn't forgiven me. :-\)
    Perl 2 introduced Henry Spencer's regular expression package.
    Perl 3 introduced the ability to handle binary data (embedded nulls).
    Perl 4 introduced the first Camel book.  Really.  We mostly just
        switched version numbers so the book could refer to 4.000.
    Perl 5 introduced everything else, including the ability to
        introduce everything else.

THE KEEPERS OF THE PUMPKIN

Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie, Gurusamy Sarathy, Graham Barr, Jarkko Hietaniemi, Hugo van der Sanden, Michael Schwern, Rafael Garcia-Suarez, Nicholas Clark, Richard Clamp, Leon Brocard.

PUMPKIN?

[from Porting/pumpkin.pod in the Perl source code distribution]

Chip Salzenberg gets credit for that, with a nod to his cow orker, David Croy. We had passed around various names (baton, token, hot potato) but none caught on. Then, Chip asked:

[begin quote]

   Who has the patch pumpkin?

To explain: David Croy once told me once that at a previous job, there was one tape drive and multiple systems that used it for backups. But instead of some high-tech exclusion software, they used a low-tech method to prevent multiple simultaneous backups: a stuffed pumpkin. No one was allowed to make backups unless they had the "backup pumpkin".

[end quote]

The name has stuck. The holder of the pumpkin is sometimes called the pumpking (keeping the source afloat?) or the pumpkineer (pulling the strings?).

THE RECORDS

 Pump-  Release         Date            Notes
 king                                   (by no means
                                         comprehensive,
                                         see Changes*
                                         for details)
 ===========================================================================
 Larry   0              Classified.     Don't ask.
 Larry   1.000          1987-Dec-18
          1.001..10     1988-Jan-30
          1.011..14     1988-Feb-02
 Schwern  1.0.15        2002-Dec-18     Modernization
 Richard  1.0.16        2003-Dec-18
 Larry   2.000          1988-Jun-05
          2.001         1988-Jun-28
 Larry   3.000          1989-Oct-18
          3.001         1989-Oct-26
          3.002..4      1989-Nov-11
          3.005         1989-Nov-18
          3.006..8      1989-Dec-22
          3.009..13     1990-Mar-02
          3.014         1990-Mar-13
          3.015         1990-Mar-14
          3.016..18     1990-Mar-28
          3.019..27     1990-Aug-10     User subs.
          3.028         1990-Aug-14
          3.029..36     1990-Oct-17
          3.037         1990-Oct-20
          3.040         1990-Nov-10
          3.041         1990-Nov-13
          3.042..43     1991-Jan-??
          3.044         1991-Jan-12
 Larry   4.000          1991-Mar-21
          4.001..3      1991-Apr-12
          4.004..9      1991-Jun-07
          4.010         1991-Jun-10
          4.011..18     1991-Nov-05
          4.019         1991-Nov-11     Stable.
          4.020..33     1992-Jun-08
          4.034         1992-Jun-11
          4.035         1992-Jun-23
 Larry    4.036         1993-Feb-05     Very stable.
          5.000alpha1   1993-Jul-31
          5.000alpha2   1993-Aug-16
          5.000alpha3   1993-Oct-10
          5.000alpha4   1993-???-??
          5.000alpha5   1993-???-??
          5.000alpha6   1994-Mar-18
          5.000alpha7   1994-Mar-25
 Andy     5.000alpha8   1994-Apr-04
 Larry    5.000alpha9   1994-May-05     ext appears.
          5.000alpha10  1994-Jun-11
          5.000alpha11  1994-Jul-01
 Andy     5.000a11a     1994-Jul-07     To fit 14.
          5.000a11b     1994-Jul-14
          5.000a11c     1994-Jul-19
          5.000a11d     1994-Jul-22
 Larry    5.000alpha12  1994-Aug-04
 Andy     5.000a12a     1994-Aug-08
          5.000a12b     1994-Aug-15
          5.000a12c     1994-Aug-22
          5.000a12d     1994-Aug-22
          5.000a12e     1994-Aug-22
          5.000a12f     1994-Aug-24
          5.000a12g     1994-Aug-24
          5.000a12h     1994-Aug-24
 Larry    5.000beta1    1994-Aug-30
 Andy     5.000b1a      1994-Sep-06
 Larry    5.000beta2    1994-Sep-14     Core slushified.
 Andy     5.000b2a      1994-Sep-14
          5.000b2b      1994-Sep-17
          5.000b2c      1994-Sep-17
 Larry    5.000beta3    1994-Sep-??
 Andy     5.000b3a      1994-Sep-18
          5.000b3b      1994-Sep-22
          5.000b3c      1994-Sep-23
          5.000b3d      1994-Sep-27
          5.000b3e      1994-Sep-28
          5.000b3f      1994-Sep-30
          5.000b3g      1994-Oct-04
 Andy     5.000b3h      1994-Oct-07
 Larry?   5.000gamma    1994-Oct-13?
 Larry   5.000          1994-Oct-17
 Andy     5.000a        1994-Dec-19
          5.000b        1995-Jan-18
          5.000c        1995-Jan-18
          5.000d        1995-Jan-18
          5.000e        1995-Jan-18
          5.000f        1995-Jan-18
          5.000g        1995-Jan-18
          5.000h        1995-Jan-18
          5.000i        1995-Jan-26
          5.000j        1995-Feb-07
          5.000k        1995-Feb-11
          5.000l        1995-Feb-21
          5.000m        1995-Feb-28
          5.000n        1995-Mar-07
          5.000o        1995-Mar-13?
 Larry   5.001          1995-Mar-13
 Andy     5.001a        1995-Mar-15
          5.001b        1995-Mar-31
          5.001c        1995-Apr-07
          5.001d        1995-Apr-14
          5.001e        1995-Apr-18     Stable.
          5.001f        1995-May-31
          5.001g        1995-May-25
          5.001h        1995-May-25
          5.001i        1995-May-30
          5.001j        1995-Jun-05
          5.001k        1995-Jun-06
          5.001l        1995-Jun-06     Stable.
          5.001m        1995-Jul-02     Very stable.
          5.001n        1995-Oct-31     Very unstable.
          5.002beta1    1995-Nov-21
          5.002b1a      1995-Dec-04
          5.002b1b      1995-Dec-04
          5.002b1c      1995-Dec-04
          5.002b1d      1995-Dec-04
          5.002b1e      1995-Dec-08
          5.002b1f      1995-Dec-08
 Tom      5.002b1g      1995-Dec-21     Doc release.
 Andy     5.002b1h      1996-Jan-05
          5.002b2       1996-Jan-14
 Larry    5.002b3       1996-Feb-02
 Andy     5.002gamma    1996-Feb-11
 Larry    5.002delta    1996-Feb-27
 Larry   5.002          1996-Feb-29     Prototypes.
 Charles  5.002_01      1996-Mar-25
         5.003          1996-Jun-25     Security release.
          5.003_01      1996-Jul-31
 Nick     5.003_02      1996-Aug-10
 Andy     5.003_03      1996-Aug-28
          5.003_04      1996-Sep-02
          5.003_05      1996-Sep-12
          5.003_06      1996-Oct-07
          5.003_07      1996-Oct-10
 Chip     5.003_08      1996-Nov-19
          5.003_09      1996-Nov-26
          5.003_10      1996-Nov-29
          5.003_11      1996-Dec-06
          5.003_12      1996-Dec-19
          5.003_13      1996-Dec-20
          5.003_14      1996-Dec-23
          5.003_15      1996-Dec-23
          5.003_16      1996-Dec-24
          5.003_17      1996-Dec-27
          5.003_18      1996-Dec-31
          5.003_19      1997-Jan-04
          5.003_20      1997-Jan-07
          5.003_21      1997-Jan-15
          5.003_22      1997-Jan-16
          5.003_23      1997-Jan-25
          5.003_24      1997-Jan-29
          5.003_25      1997-Feb-04
          5.003_26      1997-Feb-10
          5.003_27      1997-Feb-18
          5.003_28      1997-Feb-21
          5.003_90      1997-Feb-25     Ramping up to the 5.004 release.
          5.003_91      1997-Mar-01
          5.003_92      1997-Mar-06
          5.003_93      1997-Mar-10
          5.003_94      1997-Mar-22
          5.003_95      1997-Mar-25
          5.003_96      1997-Apr-01
          5.003_97      1997-Apr-03     Fairly widely used.
          5.003_97a     1997-Apr-05
          5.003_97b     1997-Apr-08
          5.003_97c     1997-Apr-10
          5.003_97d     1997-Apr-13
          5.003_97e     1997-Apr-15
          5.003_97f     1997-Apr-17
          5.003_97g     1997-Apr-18
          5.003_97h     1997-Apr-24
          5.003_97i     1997-Apr-25
          5.003_97j     1997-Apr-28
          5.003_98      1997-Apr-30
          5.003_99      1997-May-01
          5.003_99a     1997-May-09
          p54rc1        1997-May-12     Release Candidates.
          p54rc2        1997-May-14
 Chip    5.004          1997-May-15     A major maintenance release.
 Tim      5.004_01-t1   1997-???-??     The 5.004 maintenance track.
          5.004_01-t2   1997-Jun-11     aka perl5.004m1t2
          5.004_01      1997-Jun-13
          5.004_01_01   1997-Jul-29     aka perl5.004m2t1
          5.004_01_02   1997-Aug-01     aka perl5.004m2t2
          5.004_01_03   1997-Aug-05     aka perl5.004m2t3
          5.004_02      1997-Aug-07
          5.004_02_01   1997-Aug-12     aka perl5.004m3t1
          5.004_03-t2   1997-Aug-13     aka perl5.004m3t2
          5.004_03      1997-Sep-05
          5.004_04-t1   1997-Sep-19     aka perl5.004m4t1
          5.004_04-t2   1997-Sep-23     aka perl5.004m4t2
          5.004_04-t3   1997-Oct-10     aka perl5.004m4t3
          5.004_04-t4   1997-Oct-14     aka perl5.004m4t4
          5.004_04      1997-Oct-15
          5.004_04-m1   1998-Mar-04     (5.004m5t1) Maint. trials for 5.004_05.
          5.004_04-m2   1998-May-01
          5.004_04-m3   1998-May-15
          5.004_04-m4   1998-May-19
          5.004_05-MT5  1998-Jul-21
          5.004_05-MT6  1998-Oct-09
          5.004_05-MT7  1998-Nov-22
          5.004_05-MT8  1998-Dec-03
 Chip     5.004_05-MT9  1999-Apr-26
          5.004_05      1999-Apr-29
 Malcolm  5.004_50      1997-Sep-09     The 5.005 development track.
          5.004_51      1997-Oct-02
          5.004_52      1997-Oct-15
          5.004_53      1997-Oct-16
          5.004_54      1997-Nov-14
          5.004_55      1997-Nov-25
          5.004_56      1997-Dec-18
          5.004_57      1998-Feb-03
          5.004_58      1998-Feb-06
          5.004_59      1998-Feb-13
          5.004_60      1998-Feb-20
          5.004_61      1998-Feb-27
          5.004_62      1998-Mar-06
          5.004_63      1998-Mar-17
          5.004_64      1998-Apr-03
          5.004_65      1998-May-15
          5.004_66      1998-May-29
 Sarathy  5.004_67      1998-Jun-15
          5.004_68      1998-Jun-23
          5.004_69      1998-Jun-29
          5.004_70      1998-Jul-06
          5.004_71      1998-Jul-09
          5.004_72      1998-Jul-12
          5.004_73      1998-Jul-13
          5.004_74      1998-Jul-14     5.005 beta candidate.
          5.004_75      1998-Jul-15     5.005 beta1.
          5.004_76      1998-Jul-21     5.005 beta2.
          5.005         1998-Jul-22     Oneperl.
 Sarathy  5.005_01      1998-Jul-27     The 5.005 maintenance track.
          5.005_02-T1   1998-Aug-02
          5.005_02-T2   1998-Aug-05
          5.005_02      1998-Aug-08
 Graham   5.005_03-MT1  1998-Nov-30
          5.005_03-MT2  1999-Jan-04
          5.005_03-MT3  1999-Jan-17
          5.005_03-MT4  1999-Jan-26
          5.005_03-MT5  1999-Jan-28
          5.005_03-MT6  1999-Mar-05
          5.005_03      1999-Mar-28
 Leon     5.005_04-RC1  2004-Feb-05
          5.005_04-RC2  2004-Feb-18
          5.005_04      2004-Feb-23
 Sarathy  5.005_50      1998-Jul-26     The 5.6 development track.
          5.005_51      1998-Aug-10
          5.005_52      1998-Sep-25
          5.005_53      1998-Oct-31
          5.005_54      1998-Nov-30
          5.005_55      1999-Feb-16
          5.005_56      1999-Mar-01
          5.005_57      1999-May-25
          5.005_58      1999-Jul-27
          5.005_59      1999-Aug-02
          5.005_60      1999-Aug-02
          5.005_61      1999-Aug-20
          5.005_62      1999-Oct-15
          5.005_63      1999-Dec-09
          5.5.640       2000-Feb-02
          5.5.650       2000-Feb-08     beta1
          5.5.660       2000-Feb-22     beta2
          5.5.670       2000-Feb-29     beta3
          5.6.0-RC1     2000-Mar-09     Release candidate 1.
          5.6.0-RC2     2000-Mar-14     Release candidate 2.
          5.6.0-RC3     2000-Mar-21     Release candidate 3.
          5.6.0         2000-Mar-22
 Sarathy  5.6.1-TRIAL1  2000-Dec-18     The 5.6 maintenance track.
          5.6.1-TRIAL2  2001-Jan-31
          5.6.1-TRIAL3  2001-Mar-19
          5.6.1-foolish 2001-Apr-01     The "fools-gold" release.
          5.6.1         2001-Apr-08
 Rafael   5.6.2-RC1     2003-Nov-08
          5.6.2         2003-Nov-15     Fix new build issues
 Jarkko   5.7.0         2000-Sep-02     The 5.7 track: Development.
          5.7.1         2001-Apr-09
          5.7.2         2001-Jul-13     Virtual release candidate 0.
          5.7.3         2002-Mar-05
          5.8.0-RC1     2002-Jun-01
          5.8.0-RC2     2002-Jun-21
          5.8.0-RC3     2002-Jul-13
          5.8.0         2002-Jul-18
          5.8.1-RC1     2003-Jul-10
          5.8.1-RC2     2003-Jul-11
          5.8.1-RC3     2003-Jul-30
          5.8.1-RC4     2003-Aug-01
          5.8.1-RC5     2003-Sep-22
          5.8.1         2003-Sep-25
 Nicholas 5.8.2-RC1     2003-Oct-27
          5.8.2-RC2     2003-Nov-03
          5.8.2         2003-Nov-05
          5.8.3-RC1     2004-Jan-07
          5.8.3         2004-Jan-14
          5.8.4-RC1     2004-Apr-05
          5.8.4-RC2     2004-Apr-15
          5.8.4         2004-Apr-21
          5.8.5-RC1     2004-Jul-06
          5.8.5-RC2     2004-Jul-08
          5.8.5         2004-Jul-19
          5.8.6-RC1     2004-Nov-11
          5.8.6         2004-Nov-27
          5.8.7-RC1     2005-May-18
          5.8.7         2005-May-30
          5.8.8-RC1     2006-Jan-20
          5.8.8         2006-Jan-31
 Hugo     5.9.0         2003-Oct-27
 Rafael   5.9.1         2004-Mar-16
          5.9.2         2005-Apr-01
          5.9.3         2006-Jan-28

SELECTED RELEASE SIZES

For example the notation "core: 212 29" in the release 1.000 means that it had in the core 212 kilobytes, in 29 files. The "core".."doc" are explained below.

 release        core       lib         ext        t         doc
 ======================================================================
 1.000           212  29      -   -      -   -     38  51     62   3
 1.014           219  29      -   -      -   -     39  52     68   4
 2.000           309  31      2   3      -   -     55  57     92   4
 2.001           312  31      2   3      -   -     55  57     94   4
 3.000           508  36     24  11      -   -     79  73    156   5
 3.044           645  37     61  20      -   -     90  74    190   6
 4.000           635  37     59  20      -   -     91  75    198   4
 4.019           680  37     85  29      -   -     98  76    199   4
 4.036           709  37     89  30      -   -     98  76    208   5
 5.000alpha2     785  50    114  32      -   -    112  86    209   5
 5.000alpha3     801  50    117  33      -   -    121  87    209   5
 5.000alpha9    1022  56    149  43    116  29    125  90    217   6
 5.000a12h       978  49    140  49    205  46    152  97    228   9
 5.000b3h       1035  53    232  70    216  38    162  94    218  21
 5.000          1038  53    250  76    216  38    154  92    536  62
 5.001m         1071  54    388  82    240  38    159  95    544  29
 5.002          1121  54    661 101    287  43    155  94    847  35
 5.003          1129  54    680 102    291  43    166 100    853  35
 5.003_07       1231  60    748 106    396  53    213 137    976  39
 5.004          1351  60   1230 136    408  51    355 161   1587  55
 5.004_01       1356  60   1258 138    410  51    358 161   1587  55
 5.004_04       1375  60   1294 139    413  51    394 162   1629  55
 5.004_05       1463  60   1435 150    394  50    445 175   1855  59
 5.004_51       1401  61   1260 140    413  53    358 162   1594  56
 5.004_53       1422  62   1295 141    438  70    394 162   1637  56
 5.004_56       1501  66   1301 140    447  74    408 165   1648  57
 5.004_59       1555  72   1317 142    448  74    424 171   1678  58
 5.004_62       1602  77   1327 144    629  92    428 173   1674  58
 5.004_65       1626  77   1358 146    615  92    446 179   1698  60
 5.004_68       1856  74   1382 152    619  92    463 187   1784  60
 5.004_70       1863  75   1456 154    675  92    494 194   1809  60
 5.004_73       1874  76   1467 152    762 102    506 196   1883  61
 5.004_75       1877  76   1467 152    770 103    508 196   1896  62
 5.005          1896  76   1469 152    795 103    509 197   1945  63
 5.005_03       1936  77   1541 153    813 104    551 201   2176  72
 5.005_50       1969  78   1842 301    795 103    514 198   1948  63
 5.005_53       1999  79   1885 303    806 104    602 224   2002  67
 5.005_56       2086  79   1970 307    866 113    672 238   2221  75
 5.6.0          2930  80   2626 364   1096 129    868 281   2841  93
 5.7.0          2977  80   2801 425   1250 132    975 307   3206 100
 5.6.1          3049  80   3764 484   1924 159   1025 304   3593 119
 5.7.1          3351  84   3442 455   1944 167   1334 357   3698 124
 5.7.2          3491  87   4858 618   3290 298   1598 449   3910 139
 5.7.3          3415  87   5367 630  14448 410   2205 640   4491 148

The "core"..."doc" mean the following files from the Perl source code distribution. The glob notation ** means recursively, (.) means regular files.

 core   *.[hcy]
 lib    lib/**/*.p[ml]
 ext    ext/**/*.{[hcyt],xs,pm}
 t      t/**/*(.) (for 1-5.005_56) or **/*.t (for 5.6.0-5.7.3)
 doc    {README*,INSTALL,*[_.]man{,.?},pod/**/*.pod}

Here are some statistics for the other subdirectories and one file in the Perl source distribution for somewhat more selected releases.

 ======================================================================
   Legend:  kB   #
            1.014   2.001   3.044   4.000   4.019   4.036
 atarist      -  -    -  -    -  -    -  -    -  -  113 31
 Configure   31  1   37  1   62  1   73  1   83  1   86  1
 eg           -  -   34 28   47 39   47 39   47 39   47 39
 emacs        -  -    -  -    -  -   67  4   67  4   67  4
 h2pl         -  -    -  -   12 12   12 12   12 12   12 12
 hints        -  -    -  -    -  -    -  -    5 42   11 56
 msdos        -  -    -  -   41 13   57 15   58 15   60 15
 os2          -  -    -  -   63 22   81 29   81 29  113 31
 usub         -  -    -  -   21 16   25  7   43  8   43  8
 x2p        103 17  104 17  137 17  147 18  152 19  154 19
 ======================================================================
            5.000a2 5.000a12h 5.000b3h 5.000  5.001m  5.002   5.003
 atarist    113 31  113 31    -  -      -  -    -  -    -  -    -  -
 bench        -  -    0  1    -  -      -  -    -  -    -  -    -  -
 Bugs         2  5   26  1    -  -      -  -    -  -    -  -    -  -
 dlperl      40  5    -  -    -  -      -  -    -  -    -  -    -  -
 do         127 71    -  -    -  -      -  -    -  -    -  -    -  -
 Configure    -  -  153  1  159  1    160  1  180  1  201  1  201  1
 Doc          -  -   26  1   75  7     11  1   11  1    -  -    -  -
 eg          79 58   53 44   51 43     54 44   54 44   54 44   54 44
 emacs       67  4  104  6  104  6    104  1  104  6  108  1  108  1
 h2pl        12 12   12 12   12 12     12 12   12 12   12 12   12 12
 hints       11 56   12 46   18 48     18 48   44 56   73 59   77 60
 msdos       60 15   60 15    -  -      -  -    -  -    -  -    -  -
 os2        113 31  113 31    -  -      -  -    -  -   84 17   56 10
 U            -  -   62  8  112 42      -  -    -  -    -  -    -  -
 usub        43  8    -  -    -  -      -  -    -  -    -  -    -  -
 utils        -  -    -  -    -  -      -  -    -  -   87  7   88  7
 vms          -  -   80  7  123  9    184 15  304 20  500 24  475 26
 x2p        171 22  171 21  162 20    162 20  279 20  280 20  280 20
 ======================================================================
            5.003_07 5.004   5.004_04 5.004_62 5.004_65 5.004_68
 beos         -  -     -  -    -  -     -  -     1   1    1   1
 Configure  217  1   225  1  225  1   240  1   248   1  256   1
 cygwin32     -  -    23  5   23  5    23  5    24   5   24   5
 djgpp        -  -     -  -    -  -    14  5    14   5   14   5
 eg          54 44    81 62   81 62    81 62    81  62   81  62
 emacs      143  1   194  1  204  1   212  2   212   2  212   2
 h2pl        12 12    12 12   12 12    12 12    12  12   12  12
 hints       90 62   129 69  132 71   144 72   151  74  155  74
 os2        117 42   121 42  127 42   127 44   129  44  129  44
 plan9       79 15    82 15   82 15    82 15    82  15   82  15
 Porting     51  1    94  2  109  4   203  6   234   8  241   9
 qnx          -  -     1  2    1  2     1  2     1   2    1   2
 utils       97  7   112  8  118  8   124  8   156   9  159   9
 vms        505 27   518 34  524 34   538 34   569  34  569  34
 win32        -  -   285 33  378 36   470 39   493  39  575  41
 x2p        280 19   281 19  281 19   281 19   282  19  281  19
 ======================================================================
            5.004_70 5.004_73 5.004_75  5.005  5.005_03
 apollo       -   -    -   -    -   -    -   -    0   1
 beos         1   1    1   1    1   1    1   1    1   1
 Configure  256   1  256   1  264   1  264   1  270   1
 cygwin32    24   5   24   5   24   5   24   5   24   5
 djgpp       14   5   14   5   14   5   14   5   15   5
 eg          86  65   86  65   86  65   86  65   86  65
 emacs      262   2  262   2  262   2  262   2  274   2
 h2pl        12  12   12  12   12  12   12  12   12  12
 hints      157  74  157  74  159  74  160  74  179  77
 mint         -   -    -   -    -   -    -   -    4   7
 mpeix        -   -    -   -    5   3    5   3    5   3
 os2        129  44  139  44  142  44  143  44  148  44
 plan9       82  15   82  15   82  15   82  15   82  15
 Porting    241   9  253   9  259  10  264  12  272  13
 qnx          1   2    1   2    1   2    1   2    1   2
 utils      160   9  160   9  160   9  160   9  164   9
 vms        570  34  572  34  573  34  575  34  583  34
 vos          -   -    -   -    -   -    -   -  156  10
 win32      577  41  585  41  585  41  587  41  600  42
 x2p        281  19  281  19  281  19  281  19  281  19

SELECTED PATCH SIZES

The "diff lines kb" means that for example the patch 5.003_08, to be applied on top of the 5.003_07 (or whatever was before the 5.003_08) added lines for 110 kilobytes, it removed lines for 19 kilobytes, and changed lines for 424 kilobytes. Just the lines themselves are counted, not their context. The "+ - !" become from the diff(1) context diff output format.

 Pump-  Release         Date           diff lines kB
 king                                  -------------
                                          +   -   !
 ===========================================================================
 Chip     5.003_08      1996-Nov-19     110  19 424
          5.003_09      1996-Nov-26      38   9 248
          5.003_10      1996-Nov-29      29   2  27
          5.003_11      1996-Dec-06      73  12 165
          5.003_12      1996-Dec-19     275   6 436
          5.003_13      1996-Dec-20      95   1  56
          5.003_14      1996-Dec-23      23   7 333
          5.003_15      1996-Dec-23       0   0   1
          5.003_16      1996-Dec-24      12   3  50
          5.003_17      1996-Dec-27      19   1  14
          5.003_18      1996-Dec-31      21   1  32
          5.003_19      1997-Jan-04      80   3  85
          5.003_20      1997-Jan-07      18   1 146
          5.003_21      1997-Jan-15      38  10 221
          5.003_22      1997-Jan-16       4   0  18
          5.003_23      1997-Jan-25      71  15 119
          5.003_24      1997-Jan-29     426   1  20
          5.003_25      1997-Feb-04      21   8 169
          5.003_26      1997-Feb-10      16   1  15
          5.003_27      1997-Feb-18      32  10  38
          5.003_28      1997-Feb-21      58   4  66
          5.003_90      1997-Feb-25      22   2  34
          5.003_91      1997-Mar-01      37   1  39
          5.003_92      1997-Mar-06      16   3  69
          5.003_93      1997-Mar-10      12   3  15
          5.003_94      1997-Mar-22     407   7 200
          5.003_95      1997-Mar-25      41   1  37
          5.003_96      1997-Apr-01     283   5 261
          5.003_97      1997-Apr-03      13   2  34
          5.003_97a     1997-Apr-05      57   1  27
          5.003_97b     1997-Apr-08      14   1  20
          5.003_97c     1997-Apr-10      20   1  16
          5.003_97d     1997-Apr-13       8   0  16
          5.003_97e     1997-Apr-15      15   4  46
          5.003_97f     1997-Apr-17       7   1  33
          5.003_97g     1997-Apr-18       6   1  42
          5.003_97h     1997-Apr-24      23   3  68
          5.003_97i     1997-Apr-25      23   1  31
          5.003_97j     1997-Apr-28      36   1  49
          5.003_98      1997-Apr-30     171  12 539
          5.003_99      1997-May-01       6   0   7
          5.003_99a     1997-May-09      36   2  61
          p54rc1        1997-May-12       8   1  11
          p54rc2        1997-May-14       6   0  40
        5.004           1997-May-15       4   0   4
 Tim      5.004_01      1997-Jun-13     222  14  57
          5.004_02      1997-Aug-07     112  16 119
          5.004_03      1997-Sep-05     109   0  17
          5.004_04      1997-Oct-15      66   8 173

THE KEEPERS OF THE RECORDS

Jarkko Hietaniemi <jhi@iki.fi>.

Thanks to the collective memory of the Perlfolk. In addition to the Keepers of the Pumpkin also Alan Champion, Mark Dominus, Andreas König, John Macdonald, Matthias Neeracher, Jeff Okamoto, Michael Peppler, Randal Schwartz, and Paul D. Smith sent corrections and additions.


perltodo - Perl TO-DO List

  • The roadmap to 5.10
    • Needed for a 5.9.4 release
    • Needed for a 5.9.5 release
    • Needed for a 5.9.6 release
  • Tasks that only need Perl knowledge
    • common test code for timed bail out
    • POD -> HTML conversion in the core still sucks
    • Parallel testing
    • Make Schwern poorer
    • Improve the coverage of the core tests
    • test B
    • A decent benchmark
    • fix tainting bugs
    • Dual life everything
    • Improving threads::shared
    • POSIX memory footprint
  • Tasks that need a little sysadmin-type knowledge
    • Relocatable perl
    • make HTML install work
    • compressed man pages
    • Add a code coverage target to the Makefile
    • Make Config.pm cope with differences between build and installed perl
    • make parallel builds work
    • linker specification files
  • Tasks that need a little C knowledge
    • Make it clear from -v if this is the exact official release
    • Tidy up global variables
    • Ordering of "global" variables.
    • bincompat functions
    • am I hot or not?
    • emulate the per-thread memory pool on Unix
    • reduce duplication in sv_setsv_flags
  • Tasks that need a knowledge of XS
    • IPv6
    • shrink GVs, CVs
    • merge Perl_sv_2[inpu]v
    • UTF8 caching code
    • Implicit Latin 1 => Unicode translation
    • autovivification
    • Unicode in Filenames
    • Unicode in %ENV
    • use less 'memory'
    • Re-implement :unique in a way that is actually thread-safe
    • Make tainting consistent
    • readpipe(LIST)
  • Tasks that need a knowledge of the interpreter
    • lexical pragmas
    • Attach/detach debugger from running program
    • Constant folding
    • LVALUE functions for lists
    • LVALUE functions in the debugger
    • _ prototype character
    • state variables
    • @INC source filter to Filter::Simple
    • regexp optimiser optional
    • UNITCHECK
    • optional optimizer
    • You WANT *how* many
    • lexical aliases
    • entersub XS vs Perl
    • Self ties
    • Optimize away @_
    • What hooks would assertions need?
  • Big projects
    • make ithreads more robust
    • iCOW
    • (?{...}) closures in regexps
    • A re-entrant regexp engine

NAME

perltodo - Perl TO-DO List

DESCRIPTION

This is a list of wishes for Perl. The tasks we think are smaller or easier are listed first. Anyone is welcome to work on any of these, but it's a good idea to first contact perl5-porters@perl.org to avoid duplication of effort. By all means contact a pumpking privately first if you prefer.

Whilst patches to make the list shorter are most welcome, ideas to add to the list are also encouraged. Check the perl5-porters archives for past ideas, and any discussion about them. One set of archives may be found at:

    http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/

What can we offer you in return? Fame, fortune, and everlasting glory? Maybe not, but if your patch is incorporated, then we'll add your name to the AUTHORS file, which ships in the official distribution. How many other programming languages offer you 1 line of immortality?

The roadmap to 5.10

The roadmap to 5.10 envisages feature based releases, as various items in this TODO are completed.

Needed for a 5.9.4 release

  • Review assertions. Review syntax to combine assertions. Assertions could take advantage of the lexical pragmas work. What hooks would assertions need?

Needed for a 5.9.5 release

  • Implement _ prototype character
  • Implement state variables

Needed for a 5.9.6 release

Stabilisation. If all goes well, this will be the equivalent of a 5.10-beta.

Tasks that only need Perl knowledge

common test code for timed bail out

Write portable self destruct code for tests to stop them burning CPU in infinite loops. This needs to avoid using alarm, as some of the tests are testing alarm/sleep or timers.

POD -> HTML conversion in the core still sucks

Which is crazy given just how simple POD purports to be, and how simple HTML can be. It's not actually as simple as it sounds, particularly with the flexibility POD allows for =item, but it would be good to improve the visual appeal of the HTML generated, and to avoid it having any validation errors. See also make HTML install work, as the layout of installation tree is needed to improve the cross-linking.

The addition of Pod::Simple and its related modules may make this task easier to complete.

Parallel testing

The core regression test suite is getting ever more comprehensive, which has the side effect that it takes longer to run. This isn't so good. Investigate whether it would be feasible to give the harness script the option of running sets of tests in parallel. This would be useful for tests in t/op/*.t and t/uni/*.t and maybe some sets of tests in lib/.

Questions to answer

  1. How does screen layout work when you're running more than one test?

  2. How does the caller of test specify how many tests to run in parallel?

  3. How do setup/teardown tests identify themselves?

Pugs already does parallel testing - can their approach be re-used?

Make Schwern poorer

We should have for everything. When all the core's modules are tested, Schwern has promised to donate to $500 to TPF. We may need volunteers to hold him upside down and shake vigorously in order to actually extract the cash.

See t/lib/1_compile.t for the 3 remaining modules that need tests.

Improve the coverage of the core tests

Use Devel::Cover to ascertain the core's test coverage, then add tests that are currently missing.

test B

A full test suite for the B module would be nice.

A decent benchmark

perlbench seems impervious to any recent changes made to the perl core. It would be useful to have a reasonable general benchmarking suite that roughly represented what current perl programs do, and measurably reported whether tweaks to the core improve, degrade or don't really affect performance, to guide people attempting to optimise the guts of perl. Gisle would welcome new tests for perlbench.

fix tainting bugs

Fix the bugs revealed by running the test suite with the -t switch (via make test.taintwarn).

Dual life everything

As part of the "dists" plan, anything that doesn't belong in the smallest perl distribution needs to be dual lifed. Anything else can be too. Figure out what changes would be needed to package that module and its tests up for CPAN, and do so. Test it with older perl releases, and fix the problems you find.

Improving threads::shared

Investigate whether threads::shared could share aggregates properly with only Perl level changes to shared.pm

POSIX memory footprint

Ilya observed that use POSIX; eats memory like there's no tomorrow, and at various times worked to cut it down. There is probably still fat to cut out - for example POSIX passes Exporter some very memory hungry data structures.

Tasks that need a little sysadmin-type knowledge

Or if you prefer, tasks that you would learn from, and broaden your skills base...

Relocatable perl

The C level patches needed to create a relocatable perl binary are done, as is the work on Config.pm. All that's left to do is the Configure tweaking to let people specify how they want to do the install.

make HTML install work

There is an installhtml target in the Makefile. It's marked as "experimental". It would be good to get this tested, make it work reliably, and remove the "experimental" tag. This would include

  1. Checking that cross linking between various parts of the documentation works. In particular that links work between the modules (files with POD in lib/) and the core documentation (files in pod/)

  2. Work out how to split perlfunc into chunks, preferably one per function group, preferably with general case code that could be used elsewhere. Challenges here are correctly identifying the groups of functions that go together, and making the right named external cross-links point to the right page. Things to be aware of are -X, groups such as getpwnam to endservent, two or more =items giving the different parameter lists, such as

        =item substr EXPR,OFFSET,LENGTH,REPLACEMENT

    =item substr EXPR,OFFSET,LENGTH

    =item substr EXPR,OFFSET

    and different parameter lists having different meanings. (eg select)

compressed man pages

Be able to install them. This would probably need a configure test to see how the system does compressed man pages (same directory/different directory? same filename/different filename), as well as tweaking the installman script to compress as necessary.

Add a code coverage target to the Makefile

Make it easy for anyone to run Devel::Cover on the core's tests. The steps to do this manually are roughly

  • do a normal Configure, but include Devel::Cover as a module to install (see INSTALL for how to do this)

  •     make perl
  •     cd t; HARNESS_PERL_SWITCHES=-MDevel::Cover ./perl -I../lib harness

  • Process the resulting Devel::Cover database

This just give you the coverage of the .pms. To also get the C level coverage you need to

  • Additionally tell Configure to use the appropriate C compiler flags for gcov

  •     make perl.gcov

    (instead of make perl)

  • After running the tests run gcov to generate all the .gcov files. (Including down in the subdirectories of ext/

  • (From the top level perl directory) run gcov2perl on all the .gcov files to get their stats into the cover_db directory.

  • Then process the Devel::Cover database

It would be good to add a single switch to Configure to specify that you wanted to perform perl level coverage, and another to specify C level coverage, and have Configure and the Makefile do all the right things automatically.

Make Config.pm cope with differences between build and installed perl

Quite often vendors ship a perl binary compiled with their (pay-for) compilers. People install a free compiler, such as gcc. To work out how to build extensions, Perl interrogates %Config, so in this situation %Config describes compilers that aren't there, and extension building fails. This forces people into choosing between re-compiling perl themselves using the compiler they have, or only using modules that the vendor ships.

It would be good to find a way teach Config.pm about the installation setup, possibly involving probing at install time or later, so that the %Config in a binary distribution better describes the installed machine, when the installed machine differs from the build machine in some significant way.

make parallel builds work

Currently parallel builds (such as make -j3) don't work reliably. We believe that this is due to incomplete dependency specification in the Makefile. It would be good if someone were able to track down the causes of these problems, so that parallel builds worked properly.

linker specification files

Some platforms mandate that you provide a list of a shared library's external symbols to the linker, so the core already has the infrastructure in place to do this for generating shared perl libraries. My understanding is that the GNU toolchain can accept an optional linker specification file, and restrict visibility just to symbols declared in that file. It would be good to extend makedef.pl to support this format, and to provide a means within Configure to enable it. This would allow Unix users to test that the export list is correct, and to build a perl that does not pollute the global namespace with private symbols.

Tasks that need a little C knowledge

These tasks would need a little C knowledge, but don't need any specific background or experience with XS, or how the Perl interpreter works

Make it clear from -v if this is the exact official release

Currently perl from p4/rsync ships with a patchlevel.h file that usually defines one local patch, of the form "MAINT12345" or "RC1". The output of perl -v doesn't report that a perl isn't an official release, and this information can get lost in bugs reports. Because of this, the minor version isn't bumped up until RC time, to minimise the possibility of versions of perl escaping that believe themselves to be newer than they actually are.

It would be useful to find an elegant way to have the "this is an interim maintenance release" or "this is a release candidate" in the terse -v output, and have it so that it's easy for the pumpking to remove this just as the release tarball is rolled up. This way the version pulled out of rsync would always say "I'm a development release" and it would be safe to bump the reported minor version as soon as a release ships, which would aid perl developers.

This task is really about thinking of an elegant way to arrange the C source such that it's trivial for the Pumpking to flag "this is an official release" when making a tarball, yet leave the default source saying "I'm not the official release".

Tidy up global variables

There's a note in intrpvar.h

  /* These two variables are needed to preserve 5.8.x bincompat because
     we can't change function prototypes of two exported functions.
     Probably should be taken out of blead soon, and relevant prototypes
     changed.  */

So doing this, and removing any of the unused variables still present would be good.

Ordering of "global" variables.

thrdvar.h and intrpvarh define the "global" variables that need to be per-thread under ithreads, where the variables are actually elements in a structure. As C dictates, the variables must be laid out in order of declaration. There is a comment /* Important ones in the first cache line (if alignment is done right) */ which implies that at some point in the past the ordering was carefully chosen (at least in part). However, it's clear that the ordering is less than perfect, as currently there are things such as 7 bools in a row, then something typically requiring 4 byte alignment, and then an odd bool later on. (bools are typically defined as chars). So it would be good for someone to review the ordering of the variables, to see how much alignment padding can be removed.

bincompat functions

There are lots of functions which are retained for binary compatibility. Clean these up. Move them to mathom.c, and don't compile for blead?

am I hot or not?

The idea of pp_hot.c is that it contains the hot ops, the ops that are most commonly used. The idea is that by grouping them, their object code will be adjacent in the executable, so they have a greater chance of already being in the CPU cache (or swapped in) due to being near another op already in use.

Except that it's not clear if these really are the most commonly used ops. So anyone feeling like exercising their skill with coverage and profiling tools might want to determine what ops really are the most commonly used. And in turn suggest evictions and promotions to achieve a better pp_hot.c.

emulate the per-thread memory pool on Unix

For Windows, ithreads allocates memory for each thread from a separate pool, which it discards at thread exit. It also checks that memory is free()d to the correct pool. Neither check is done on Unix, so code developed there won't be subject to such strictures, so can harbour bugs that only show up when the code reaches Windows.

It would be good to be able to optionally emulate the Window pool system on Unix, to let developers who only have access to Unix, or want to use Unix-specific debugging tools, check for these problems. To do this would involve figuring out how the PerlMem_* macros wrap malloc() access, and providing a layer that records/checks the identity of the thread making the call, and recording all the memory allocated by each thread via this API so that it can be summarily free()d at thread exit. One implementation idea would be to increase the size of allocation, and store the my_perl pointer (to identify the thread) at the start, along with pointers to make a linked list of blocks for this thread. To avoid alignment problems it would be necessary to do something like

  union memory_header_padded {
    struct memory_header {
      void *thread_id;   /* For my_perl */
      void *next;        /* Pointer to next block for this thread */
    } data;
    long double padding; /* whatever type has maximal alignment constraint */
  };

although long double might not be the only type to add to the padding union.

reduce duplication in sv_setsv_flags

Perl_sv_setsv_flags has a comment /* There's a lot of redundancy below but we're going for speed here */

Whilst this was true 10 years ago, the growing disparity between RAM and CPU speeds mean that the trade offs have changed. In addition, the duplicate code adds to the maintenance burden. It would be good to see how much of the redundancy can be pruned, particular in the less common paths. (Profiling tools at the ready...). For example, why does the test for "Can't redefine active sort subroutine" need to occur in two places?

Tasks that need a knowledge of XS

These tasks would need C knowledge, and roughly the level of knowledge of the perl API that comes from writing modules that use XS to interface to C.

IPv6

Clean this up. Check everything in core works

shrink GVs, CVs

By removing unused elements and careful re-ordering, the structures for AVs and HVs have recently been shrunk considerably. It's probable that the same approach would find savings in GVs and CVs, if not all the other larger-than-PVMG types.

merge Perl_sv_2[inpu]v

There's a lot of code shared between Perl_sv_2iv_flags, Perl_sv_2uv_flags, Perl_sv_2nv, and Perl_sv_2pv_flags. It would be interesting to see if some of it can be merged into common shared static functions. In particular, Perl_sv_2uv_flags started out as a cut&paste from Perl_sv_2iv_flags around 5.005_50 time, and it may be possible to replace both with a single function that returns a value or union which is split out by the macros in sv.h

UTF8 caching code

The string position/offset cache is not optional. It should be.

Implicit Latin 1 => Unicode translation

Conversions from byte strings to UTF-8 currently map high bit characters to Unicode without translation (or, depending on how you look at it, by implicitly assuming that the byte strings are in Latin-1). As perl assumes the C locale by default, upgrading a string to UTF-8 may change the meaning of its contents regarding character classes, case mapping, etc. This should probably emit a warning (at least).

This task is incremental - even a little bit of work on it will help.

autovivification

Make all autovivification consistent w.r.t LVALUE/RVALUE and strict/no strict;

This task is incremental - even a little bit of work on it will help.

Unicode in Filenames

chdir, chmod, chown, chroot, exec, glob, link, lstat, mkdir, open, opendir, qx, readdir, readlink, rename, rmdir, stat, symlink, sysopen, system, truncate, unlink, utime, -X. All these could potentially accept Unicode filenames either as input or output (and in the case of system and qx Unicode in general, as input or output to/from the shell). Whether a filesystem - an operating system pair understands Unicode in filenames varies.

Known combinations that have some level of understanding include Microsoft NTFS, Apple HFS+ (In Mac OS 9 and X) and Apple UFS (in Mac OS X), NFS v4 is rumored to be Unicode, and of course Plan 9. How to create Unicode filenames, what forms of Unicode are accepted and used (UCS-2, UTF-16, UTF-8), what (if any) is the normalization form used, and so on, varies. Finding the right level of interfacing to Perl requires some thought. Remember that an OS does not implicate a filesystem.

(The Windows -C command flag "wide API support" has been at least temporarily retired in 5.8.1, and the -C has been repurposed, see the perlrun manpage.)

Unicode in %ENV

Currently the %ENV entries are always byte strings.

use less 'memory'

Investigate trade offs to switch out perl's choices on memory usage. Particularly perl should be able to give memory back.

This task is incremental - even a little bit of work on it will help.

Re-implement :unique in a way that is actually thread-safe

The old implementation made bad assumptions on several levels. A good 90% solution might be just to make :unique work to share the string buffer of SvPVs. That way large constant strings can be shared between ithreads, such as the configuration information in Config.

Make tainting consistent

Tainting would be easier to use if it didn't take documented shortcuts and allow taint to "leak" everywhere within an expression.

readpipe(LIST)

system() accepts a LIST syntax (and a PROGRAM LIST syntax) to avoid running a shell. readpipe() (the function behind qx//) could be similarly extended.

Tasks that need a knowledge of the interpreter

These tasks would need C knowledge, and knowledge of how the interpreter works, or a willingness to learn.

lexical pragmas

Document the new support for lexical pragmas in 5.9.3 and how %^H works. Maybe re, encoding, maybe other pragmas could be made lexical.

Attach/detach debugger from running program

The old perltodo notes "With gdb, you can attach the debugger to a running program if you pass the process ID. It would be good to do this with the Perl debugger on a running Perl program, although I'm not sure how it would be done." ssh and screen do this with named pipes in /tmp. Maybe we can too.

Constant folding

The peephole optimiser should trap errors during constant folding, and give up on the folding, rather than bailing out at compile time. It is quite possible that the unfoldable constant is in unreachable code, eg something akin to $a = 0/0 if 0;

LVALUE functions for lists

The old perltodo notes that lvalue functions don't work for list or hash slices. This would be good to fix.

LVALUE functions in the debugger

The old perltodo notes that lvalue functions don't work in the debugger. This would be good to fix.

_ prototype character

Study the possibility of adding a new prototype character, _, meaning "this argument defaults to $_".

state variables

my $foo if 0; is deprecated, and should be replaced with state $x = "initial value\n"; the syntax from Perl 6.

@INC source filter to Filter::Simple

The second return value from a sub in @INC can be a source filter. This isn't documented. It should be changed to use Filter::Simple, tested and documented.

regexp optimiser optional

The regexp optimiser is not optional. It should configurable to be, to allow its performance to be measured, and its bugs to be easily demonstrated.

UNITCHECK

Introduce a new special block, UNITCHECK, which is run at the end of a compilation unit (module, file, eval(STRING) block). This will correspond to the Perl 6 CHECK. Perl 5's CHECK cannot be changed or removed because the O.pm/B.pm backend framework depends on it.

optional optimizer

Make the peephole optimizer optional. Currently it performs two tasks as it walks the optree - genuine peephole optimisations, and necessary fixups of ops. It would be good to find an efficient way to switch out the optimisations whilst keeping the fixups.

You WANT *how* many

Currently contexts are void, scalar and list. split has a special mechanism in place to pass in the number of return values wanted. It would be useful to have a general mechanism for this, backwards compatible and little speed hit. This would allow proposals such as short circuiting sort to be implemented as a module on CPAN.

lexical aliases

Allow lexical aliases (maybe via the syntax my \$alias = \$foo.

entersub XS vs Perl

At the moment pp_entersub is huge, and has code to deal with entering both perl and XS subroutines. Subroutine implementations rarely change between perl and XS at run time, so investigate using 2 ops to enter subs (one for XS, one for perl) and swap between if a sub is redefined.

Self ties

self ties are currently illegal because they caused too many segfaults. Maybe the causes of these could be tracked down and self-ties on all types re- instated.

Optimize away @_

The old perltodo notes "Look at the "reification" code in av.c".

What hooks would assertions need?

Assertions are in the core, and work. However, assertions needed to be added as a core patch, rather than an XS module in ext, or a CPAN module, because the core has no hooks in the necessary places. It would be useful to investigate what hooks would need to be added to make it possible to provide the full assertion support from a CPAN module, so that we aren't constraining the imagination of future CPAN authors.

Big projects

Tasks that will get your name mentioned in the description of the "Highlights of 5.10"

make ithreads more robust

Generally make ithreads more robust. See also iCOW

This task is incremental - even a little bit of work on it will help, and will be greatly appreciated.

iCOW

Sarathy and Arthur have a proposal for an improved Copy On Write which specifically will be able to COW new ithreads. If this can be implemented it would be a good thing.

(?{...}) closures in regexps

Fix (or rewrite) the implementation of the /(?{...})/ closures.

A re-entrant regexp engine

This will allow the use of a regex from inside (?{ }), (??{ }) and (?(?{ })|) constructs.


APR - Perl Interface for Apache Portable Runtime (libapr and libaprutil Libraries)

  • Synopsis
  • Description
  • Using APR modules outside mod_perl 2.0
  • See Also
  • Copyright
  • Authors

NAME

APR - Perl Interface for Apache Portable Runtime (libapr and libaprutil Libraries)

Synopsis

  use APR ();

Description

On load this modules prepares the APR enviroment (initializes memory pools, data structures, etc.)

You don't need to use this module explicitly, since it's already loaded internally by all APR::* modules.

Using APR modules outside mod_perl 2.0

You'd use the APR::* modules outside mod_perl 2.0, just like you'd use it with mod_perl 2.0. For example to get a random unique string you could call:

  % perl -MAPR::UUID -le 'print APR::UUID->new->format'

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Base64 - Perl API for APR base64 encoding/decoding functionality

  • Synopsis
  • Description
  • API
    • decode
    • encode
    • encode_len
  • See Also
  • Copyright
  • Authors

NAME

APR::Base64 - Perl API for APR base64 encoding/decoding functionality

Synopsis

  use APR::Base64 ();

  my $clear   = "foo"
  my $encoded = APR::Base64::encode($clear);
  my $decoded = APR::Base64::decode($encoded);
  my $len_enc = APR::Base64::encode_len(length $clear);

Description

APR::Base64 provides the access to APR's base64 encoding and decoding API.

API

APR::Base64 provides the following functions and/or methods:

decode

Decode a base64 encoded string

  $decoded = decode($encoded);
arg1: $encoded ( string )

The encoded string.

ret: $decoded ( string )

The decoded string.

since: 2.0.00

encode

Encode a string to base64

  $encoded = encode($clear);
arg1: $clear ( string )

The unencoded string.

ret: $encoded ( string )

The encoded string.

since: 2.0.00

encode_len

Given the length of an unencoded string, get the length of the encoded string.

  $len_enc = encode_len($len_clear);
arg1: $len_clear ( integer )

the length of an unencoded string.

ret: $len_enc ( integer )

the length of the string after it is encoded

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Brigade - Perl API for manipulating APR Bucket Brigades

  • Synopsis
  • Description
  • API
    • cleanup
    • concat
    • destroy
    • is_empty
    • first
    • flatten
    • insert_head
    • insert_tail
    • last
    • length
    • new
    • bucket_alloc
    • next
    • pool
    • prev
    • split
  • See Also
  • Copyright
  • Authors

NAME

APR::Brigade - Perl API for manipulating APR Bucket Brigades

Synopsis

  use APR::Brigade ();

  $bb = APR::Brigade->new($r->pool, $c->bucket_alloc);
  $ba = $bb->bucket_alloc();
  $pool = $bb->pool;

  $bb->insert_head($b);
  $bb->insert_tail($b);

  $b_first = $bb->first;
  $b_last  = $bb->last;

  $b_prev = $bb->prev($b_last);
  $b_next = $bb->next($b);

  $bb2 = APR::Brigade->new($r->pool, $c->bucket_alloc);
  $bb1->concat($bb2);

  $len = $bb->flatten($data);
  $len = $bb2->flatten($data, $wanted);

  $len = $bb->length;
  $bb3 = $bb->split($b_last);

  last if $bb->is_empty();
  $bb->cleanup();
  $bb->destroy();

Description

APR::Brigade allows you to create, manipulate and delete APR bucket brigades.

API

APR::Brigade provides the following functions and/or methods:

cleanup

Empty out an entire bucket brigade:

  $bb->cleanup;
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The brigade to cleanup

ret: no return value
since: 2.0.00

This method destroys all of the buckets within the bucket brigade's bucket list. This is similar to destroy()|/C_destroy_, except that it does not deregister the brigade's pool()|/C_pool_ cleanup function.

Generally, you should use destroy()|/C_destroy_. This function can be useful in situations where you have a single brigade that you wish to reuse many times by destroying all of the buckets in the brigade and putting new buckets into it later.

concat

Concatenate brigade $bb2 onto the end of brigade $bb1, leaving brigade $bb2 empty:

  $bb1->concat($bb2);
obj: $bb1 ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The brigade to concatenate to.

arg1: $bb2 ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The brigade to concatenate and empty afterwards.

ret: no return value
since: 2.0.00

destroy

destroy an entire bucket brigade, includes all of the buckets within the bucket brigade's bucket list.

  $bb->destroy();
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The bucket brigade to destroy.

ret: no return value
excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

is_empty

Test whether the bucket brigade is empty

  $ret = $bb->is_empty();
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
ret: $ret ( boolean )
since: 2.0.00

first

Return the first bucket in a brigade

  $b_first = $bb->first;
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
ret: $b_first ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The first bucket in the bucket brigade $bb.

undef is returned if there are no buckets in $bb.

since: 2.0.00

flatten

Get the data from buckets in the bucket brigade as one string

  $len = $bb->flatten($buffer);
  $len = $bb->flatten($buffer, $wanted);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
arg1: $buffer ( SCALAR )

The buffer to fill. All previous data will be lost.

opt arg2: $wanted ( number )

If no argument is passed then all data will be returned. If $wanted is specified -- that number or less bytes will be returned.

ret: $len ( number )

How many bytes were actually read.

$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.

since: 2.0.00
excpt: APR::Error|docs::2.0::api::APR::Error

insert_head

Insert a list of buckets at the front of a brigade

  $bb->insert_head($b);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

Brigade to insert into

arg1: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

the bucket to insert. More buckets could be attached to that bucket.

ret: no return value
since: 2.0.00

insert_tail

Insert a list of buckets at the end of a brigade

  $bb->insert_tail($b);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

Brigade to insert into

arg1: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

the bucket to insert. More buckets could be attached to that bucket.

ret: no return value
since: 2.0.00

last

Return the last bucket in the brigade

  $b_last = $bb->last;
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
ret: $b_last ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The last bucket in the bucket brigade $bb.

undef is returned if there are no buckets in $bb.

since: 2.0.00

length

Return the total length of the data in the brigade (not the number of buckets)

  $len = $bb->length;
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
ret: $len ( number )
since: 2.0.00

new

  my $nbb = APR::Brigade->new($p, $bucket_alloc);
  my $nbb =          $bb->new($p, $bucket_alloc);
obj: $bb ( APR::Brigade object or class|docs::2.0::api::APR::Brigade )
arg1: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
arg2: $bucket_alloc ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )
ret: $nbb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

a newly created bucket brigade object

since: 2.0.00

Example:

Create a new bucket brigade, using the request object's pool:

  use Apache2::Connection ();
  use Apache2::RequestRec ();
  use APR::Brigade ();
  my $bb = APR::Brigade->new($r->pool, $r->connection->bucket_alloc);

bucket_alloc

Get the bucket allocator associated with this brigade.

  my $ba = $bb->bucket_alloc();
obj: $bb ( APR::Brigade object or class|docs::2.0::api::APR::Brigade )
ret: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )
since: 2.0.00

next

Return the next bucket in a brigade

  $b_next = $bb->next($b);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
arg1: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket after which the next bucket $b_next is located

ret: $b_next ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The next bucket after bucket $b.

undef is returned if there is no next bucket (i.e. $b is the last bucket).

since: 2.0.00

pool

The pool the brigade is associated with.

  $pool = $bb->pool;
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
ret: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

The data is not allocated out of the pool, but a cleanup is registered with this pool. If the brigade is destroyed by some mechanism other than pool destruction, the destroying function is responsible for killing the registered cleanup.

prev

Return the previous bucket in the brigade

  $b_prev = $bb->prev($b);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )
arg1: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket located after bucket $b_prev

ret: $b_prev ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket located before bucket $b.

undef is returned if there is no previous bucket (i.e. $b is the first bucket).

since: 2.0.00

split

Split a bucket brigade into two, such that the given bucket is the first in the new bucket brigade.

  $bb2 = $bb->split($b);
obj: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The brigade to split

arg1: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The first bucket of the new brigade

ret: $bb2 ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The new brigade.

since: 2.0.00

This function is useful when a filter wants to pass only the initial part of a brigade to the next filter.

Example:

Create a bucket brigade with three buckets, and split it into two brigade such that the second brigade will have the last two buckets.

  my $bb1 = APR::Brigade->new($r->pool, $c->bucket_alloc);
  my $ba  = $c->bucket_alloc();
  $bb1->insert_tail(APR::Bucket->new($ba, "1"));
  $bb1->insert_tail(APR::Bucket->new($ba, "2"));
  $bb1->insert_tail(APR::Bucket->new($ba, "3"));

$bb1 now contains buckets "1", "2", "3". Now do the split at the second bucket:

  my $b = $bb1->first; # 1
  $b = $bb1->next($b); # 2
  my $bb2 = $bb1->split($b);

Now $bb1 contains bucket "1". $bb2 contains buckets: "2", "3"

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Bucket - Perl API for manipulating APR Buckets

  • Synopsis
  • Description
  • API
    • delete
    • destroy
    • eos_create
    • flush_create
    • insert_after
    • insert_before
    • is_eos
    • is_flush
    • length
    • new
    • read
    • remove
    • setaside
    • type
  • Unsupported API
    • data
    • start
  • See Also
  • Copyright
  • Authors

NAME

APR::Bucket - Perl API for manipulating APR Buckets

Synopsis

  use APR::Bucket ();
  my $ba = $c->bucket_alloc;

  $b1 = APR::Bucket->new($ba, "aaa");
  $b2 = APR::Bucket::eos_create($ba);
  $b3 = APR::Bucket::flush_create($ba);

  $b2->is_eos;
  $b3->is_flush;

  $len = $b1->length;
  $len = $b1->read($data);
  $type = $b1->type;

  $b1->insert_after($b2);
  $b1->insert_before($b3);
  $b1->remove;
  $b1->destroy;

  $b2->delete; # remove+destroy

  $b4 = APR::Bucket->new($ba, "to be setaside");
  $b4->setaside($pool);

Description

APR::Bucket allows you to create, manipulate and delete APR buckets.

You will probably find the various insert methods confusing, the tip is to read the function right to left. The following code sample helps to visualize the operations:

  my $bb = APR::Brigade->new($r->pool, $ba);
  my $d1 = APR::Bucket->new($ba, "d1");
  my $d2 = APR::Bucket->new($ba, "d2");
  my $f1 = APR::Bucket::flush_create($ba);
  my $f2 = APR::Bucket::flush_create($ba);
  my $e1 = APR::Bucket::eos_create($ba);
                           # head->tail
  $bb->insert_head(  $d1); # head->d1->tail
  $d1->insert_after( $d2); # head->d1->d2->tail
  $d2->insert_before($f1); # head->d1->f1->d2->tail
  $d2->insert_after( $f2); # head->d1->f1->d2->f2->tail
  $bb->insert_tail(  $e1); # head->d1->f1->d2->f2->e1->tail

API

APR::Bucket provides the following functions and/or methods:

delete

Tell the bucket to remove itself from the bucket brigade it belongs to, and destroy itself.

  $bucket->delete();
obj: $bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: no return value
since: 2.0.00

If the bucket is not attached to any bucket brigade then this operation just destroys the bucket.

delete is a convenience wrapper, internally doing:

  $b->remove;
  $b->destroy;

Examples:

Assuming that $bb already exists and filled with buckets, replace the existing data buckets with new buckets with upcased data;

  for (my $b = $bb->first; $b; $b = $bb->next($b)) {
     if ($b->read(my $data)) {
          my $nb = APR::Bucket->new($bb->bucket_alloc, uc $data);
          $b->insert_before($nb);
          $b->delete;
          $b = $nb;
      }
  }

destroy

Free the resources used by a bucket. If multiple buckets refer to the same resource it is freed when the last one goes away.

  $bucket->destroy();
obj: $bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: no return value
since: 2.0.00

A bucket needs to be destroyed if it was removed from a bucket brigade, to avoid memory leak.

If a bucket is linked to a bucket brigade, it needs to be removed from it, before it can be destroyed.

Usually instead of calling:

  $b->remove;
  $b->destroy;

it's better to call delete|/C_delete_ which does exactly that.

eos_create

Create an EndOfStream bucket.

  $b = APR::Bucket::eos_create($ba);
arg1: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )

The freelist from which this bucket should be allocated

ret: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The new bucket

since: 2.0.00

This bucket type indicates that there is no more data coming from down the filter stack. All filters should flush any buffered data at this point.

Example:

  use APR::Bucket ();
  use Apache2::Connection ();
  my $ba = $c->bucket_alloc;
  my $eos_b = APR::Bucket::eos_create($ba);

flush_create

Create a flush bucket.

  $b = APR::Bucket::flush_create($ba);
arg1: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )

The freelist from which this bucket should be allocated

ret: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The new bucket

since: 2.0.00

This bucket type indicates that filters should flush their data. There is no guarantee that they will flush it, but this is the best we can do.

insert_after

Insert a list of buckets after a specified bucket

  $after_bucket->insert_after($add_bucket);
obj: $after_bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket to insert after

arg1: $add_bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The buckets to insert. It says buckets, since $add_bucket may have more buckets attached after itself.

ret: no return value
since: 2.0.00

insert_before

Insert a list of buckets before a specified bucket

  $before_bucket->insert_before($add_bucket);
obj: $before_bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket to insert before

arg1: $add_bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The buckets to insert. It says buckets, since $add_bucket may have more buckets attached after itself.

ret: no return value
since: 2.0.00

is_eos

Determine if a bucket is an EOS bucket

  $ret = $bucket->is_eos();
obj: $bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $ret ( boolean )
since: 2.0.00

is_flush

Determine if a bucket is a FLUSH bucket

  $ret = $bucket->is_flush();
obj: $bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $ret ( boolean )
since: 2.0.00

length

Get the length of the data in the bucket.

  $len = $b->length;
obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $len ( integer )

If the length is unknown, $len value will be -1.

since: 2.0.00

new

Create a new bucket and initialize it with data:

  $nb = APR::Bucket->new($ba, $data);
  $nb =          $b->new($ba, $data);
  $nb = APR::Bucket->new($ba, $data, $offset);
  $nb = APR::Bucket->new($ba, $data, $offset, $len);
obj: $b ( APR::Bucket object or class|docs::2.0::api::APR::Bucket )
arg1: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )
arg2: $data ( string )

The data to initialize with.

Important: in order to avoid unnecessary data copying the variable is stored in the bucket object. That means that if you modify $data after passing it to new() you will modify the data in the bucket as well. To avoid that pass to new() a copy which you won't modify.

opt arg3: $offset ( number )

Optional offset inside $data. Default: 0.

opt arg4: $len ( number )

Optional partial length to read.

If $offset is specified, then:

  length $buffer - $offset;

will be used. Otherwise the default is to use:

  length $buffer;
ret: $nb ( APR::Bucket object|docs::2.0::api::APR::Bucket )

a newly created bucket object

since: 2.0.00

Examples:

  • Create a new bucket using a whole string:

      use APR::Bucket ();
  my $data = "my data";
  my $b = APR::Bucket->new($ba, $data);

    now the bucket contains the string 'my data'.

  • Create a new bucket using a sub-string:

      use APR::Bucket ();
  my $data   = "my data";
  my $offset = 3;
  my $b = APR::Bucket->new($ba, $data, $offset);

    now the bucket contains the string 'data'.

  • Create a new bucket not using the whole length and starting from an offset:

      use APR::Bucket ();
  my $data   = "my data";
  my $offset = 3;
  my $len    = 3;
  my $b = APR::Bucket->new($ba, $data, $offset, $len);

    now the bucket contains the string 'dat'.

read

Read the data from the bucket.

  $len = $b->read($buffer);
  $len = $b->read($buffer, $block);
obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )

The bucket to read from

arg1: $buffer ( SCALAR )

The buffer to fill. All previous data will be lost.

opt arg2: $block ( APR::Const :read_type constant|docs::2.0::api::APR::Const/C__read_type_ )

optional reading mode constant.

By default the read is blocking, via APR::Const::BLOCK_READ constant|docs::2.0::api::APR::Const/C_APR__Const__BLOCK_READ_.

ret: $len ( number )

How many bytes were actually read

$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.

since: 2.0.00
excpt: APR::Error|docs::2.0::api::APR::Error

It's important to know that certain bucket types (e.g. file bucket), may perform a split and insert extra buckets following the current one. Therefore never call $b->remove|/C_remove_, before calling $b->read, or you may lose data.

Examples:

Blocking read:

  my $len = $b->read(my $buffer);

Non-blocking read:

  use APR::Const -compile 'NONBLOCK_READ';
  my $len = $b->read(my $buffer, APR::Const::NONBLOCK_READ);

remove

Tell the bucket to remove itself from the bucket brigade it belongs to.

  $bucket->remove();
obj: $bucket ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: no return value
since: 2.0.00

If the bucket is not attached to any bucket brigade then this operation doesn't do anything.

When the bucket is removed, it's not not destroyed. Usually this is done in order to move the bucket to another bucket brigade. Or to copy the data way before destroying the bucket. If the bucket wasn't moved to another bucket brigade it must be destroyed.

Examples:

Assuming that $bb1 already exists and filled with buckets, move every odd bucket number to $bb2 and every even to $bb3:

  my $bb2 = APR::Brigade->new($c->pool, $c->bucket_alloc);
  my $bb3 = APR::Brigade->new($c->pool, $c->bucket_alloc);
  my $count = 0;
  while (my $bucket = $bb->first) {
      $count++;
      $bucket->remove;
      $count % 2
          ? $bb2->insert_tail($bucket)
          : $bb3->insert_tail($bucket);
  }

setaside

Ensure the bucket's data lasts at least as long as the given pool:

  my $status = $b->setaside($pool);
obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )
arg1: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )
ret: ( APR::Const status constant|docs::2.0::api::APR::Const )

On success, APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_ is returned. Otherwise a failure code is returned.

excpt: APR::Error|docs::2.0::api::APR::Error

when your code deals only with mod_perl buckets, you don't have to ask for the return value. If this method is called in the VOID context, i.e.:

  $b->setaside($pool);

mod_perl will do the error checking on your behalf, and if the return code is not APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_, an APR::Error exception|docs::2.0::api::APR::Error will be thrown.

However if your code doesn't know which bucket types it may need to setaside, you may want to check the return code and deal with any errors. For example one of the possible error codes is APR::Const::ENOTIMPL|docs::2.0::api::APR::Const/C_APR__Const__ENOTIMPL_. As of this writing the pipe and socket buckets can't setaside(), in which case you may want to look at the ap_save_brigade() implementation.

since: 2.0.00

Usually setaside is called by certain output filters, in order to buffer socket writes of smaller buckets into a single write. This method works on all bucket types (not only the mod_perl bucket type), but as explained in the exceptions section, not all bucket types implement this method.

When a mod_perl bucket is setaside, its data is detached from the original perl scalar and copied into a pool bucket. That allows downstream filters to deal with the data originally owned by a Perl interpreter, making it possible for that interpreter to go away and do other things, or be destroyed.

type

Get the type of the data in the bucket.

  $type = $b->type;
obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $type ( APR::BucketType object|docs::2.0::api::APR::BucketType )
since: 2.0.00

You need to invoke APR::BucketType|docs::2.0::api::APR::BucketType methods to access the data.

Example:

Create a flush bucket and read its type's name:

  use APR::Bucket ();
  use APR::BucketType ();
  my $b = APR::Bucket::flush_create($ba);
  my $type = $b->type;
  my $type_name =  $type->name; # FLUSH

The type name will be 'FLUSH' in this example.

Unsupported API

APR::Socket also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

data

  $data = $b->data;

Gives a C pointer to the address of the data in the bucket. I can't see what use can be done of it in Perl.

obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $data ( C pointer )
since: subject to change

start

  $start = $b->start;

It gives the offset to when a new bucket is created with a non-zero offset value:

  my $b = APR::Bucket->new($ba, $data, $offset, $len);

So if the offset was 3. $start will be 3 too.

I fail to see what it can be useful for to the end user (it's mainly used internally).

obj: $b ( APR::Bucket object|docs::2.0::api::APR::Bucket )
ret: $start ( offset number )
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::BucketAlloc - Perl API for Bucket Allocation

  • Synopsis
  • Description
    • new
    • destroy
  • See Also
  • Copyright
  • Authors

NAME

APR::BucketAlloc - Perl API for Bucket Allocation

Synopsis

  use APR::BucketAlloc ();
  $ba = APR::BucketAlloc->new($pool);
  $ba->destroy;

Description

APR::BucketAlloc is used for bucket allocation.

new

Create an APR::BucketAlloc object:

  $ba = APR::BucketAlloc->new($pool);
class: APR::BucketAlloc
arg1: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool used to create this object.

ret: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )

The new object.

since: 2.0.00

This bucket allocation list (freelist) is used to create new buckets (via APR::Bucket->new|docs::2.0::api::APR::Bucket/C_new_) and bucket brigades (via APR::Brigade->new|docs::2.0::api::APR::Brigade/C_new_).

You only need to use this method if you aren't running under httpd. If you are running under mod_perl, you already have a bucket allocation available via $c->bucket_alloc|docs::2.0::api::Apache2::Connection/C_bucket_alloc_ and $bb->bucket_alloc|docs::2.0::api::APR::Brigade/C_bucket_alloc_.

Example:

  use APR::BucketAlloc ();
  use APR::Pool ();
  my $ba = APR::BucketAlloc->(APR::Pool->pool);
  my $eos_b = APR::Bucket::eos_create($ba);

destroy

Destroy an APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc:

  $ba->destroy;
arg1: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )

The freelist to destroy.

ret: no return value
since: 2.0.00

Once destroyed this object may not be used again.

You need to destroy $ba only if you have created it via APR::BucketAlloc->new|/C_new_. If you try to destroy an allocation not created by this method, you will get a segmentation fault.

Moreover normally it is not necessary to destroy allocators, since the pool which created them will destroy them during that pool's cleanup phase.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::BucketType - Perl API for APR bucket types

  • Synopsis
  • Description
  • API
    • name
  • See Also
  • Copyright
  • Authors

NAME

APR::BucketType - Perl API for APR bucket types

Synopsis

  use APR::BucketType ();

  my $name = $b_type->name;

Description

APR::BucketType allows you to query bucket object type properties.

API

APR::BucketType provides the following functions and/or methods:

name

Get the name of the bucket type:

  my $bucket_type_name = $b_type->name;
arg1: $b_type ( APR::BucketType object|docs::2.0::api::APR::BucketType )
ret: $bucket_type_name ( string )
since: 2.0.00

Example:

  use APR::Bucket ();
  use APR::BucketType ();
  my $eos_b = APR::Bucket::eos_create($ba);
  my $b_type = $eos_b->type;
  my $name = $b_type->name;

Now $name contains 'EOS'.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Const - Perl Interface for APR Constants

  • Synopsis
  • Description
  • Constants
    • :common
      • APR::Const::SUCCESS
    • :error
      • APR::Const::EABOVEROOT
      • APR::Const::EABSOLUTE
      • APR::Const::EACCES
      • APR::Const::EAGAIN
      • APR::Const::EBADDATE
      • APR::Const::EBADF
      • APR::Const::EBADIP
      • APR::Const::EBADMASK
      • APR::Const::EBADPATH
      • APR::Const::EBUSY
      • APR::Const::ECONNABORTED
      • APR::Const::ECONNREFUSED
      • APR::Const::ECONNRESET
      • APR::Const::EDSOOPEN
      • APR::Const::EEXIST
      • APR::Const::EFTYPE
      • APR::Const::EGENERAL
      • APR::Const::EHOSTUNREACH
      • APR::Const::EINCOMPLETE
      • APR::Const::EINIT
      • APR::Const::EINPROGRESS
      • APR::Const::EINTR
      • APR::Const::EINVAL
      • APR::Const::EINVALSOCK
      • APR::Const::EMFILE
      • APR::Const::EMISMATCH
      • APR::Const::ENAMETOOLONG
      • APR::Const::END
      • APR::Const::ENETUNREACH
      • APR::Const::ENFILE
      • APR::Const::ENODIR
      • APR::Const::ENOENT
      • APR::Const::ENOLOCK
      • APR::Const::ENOMEM
      • APR::Const::ENOPOLL
      • APR::Const::ENOPOOL
      • APR::Const::ENOPROC
      • APR::Const::ENOSHMAVAIL
      • APR::Const::ENOSOCKET
      • APR::Const::ENOSPC
      • APR::Const::ENOSTAT
      • APR::Const::ENOTDIR
      • APR::Const::ENOTEMPTY
      • APR::Const::ENOTHDKEY
      • APR::Const::ENOTHREAD
      • APR::Const::ENOTIME
      • APR::Const::ENOTIMPL
      • APR::Const::ENOTSOCK
      • APR::Const::EOF
      • APR::Const::EPATHWILD
      • APR::Const::EPIPE
      • APR::Const::EPROC_UNKNOWN
      • APR::Const::ERELATIVE
      • APR::Const::ESPIPE
      • APR::Const::ESYMNOTFOUND
      • APR::Const::ETIMEDOUT
      • APR::Const::EXDEV
    • :fopen
      • APR::Const::FOPEN_BINARY
      • APR::Const::FOPEN_BUFFERED
      • APR::Const::FOPEN_CREATE
      • APR::Const::FOPEN_DELONCLOSE
      • APR::Const::FOPEN_EXCL
      • APR::Const::FOPEN_PEND
      • APR::Const::FOPEN_READ
      • APR::Const::FOPEN_TRUNCATE
      • APR::Const::FOPEN_WRITE
    • :filepath
      • APR::Const::FILEPATH_ENCODING_LOCALE
      • APR::Const::FILEPATH_ENCODING_UNKNOWN
      • APR::Const::FILEPATH_ENCODING_UTF8
      • APR::Const::FILEPATH_NATIVE
      • APR::Const::FILEPATH_NOTABOVEROOT
      • APR::Const::FILEPATH_NOTABSOLUTE
      • APR::Const::FILEPATH_NOTRELATIVE
      • APR::Const::FILEPATH_SECUREROOT
      • APR::Const::FILEPATH_SECUREROOTTEST
      • APR::Const::FILEPATH_TRUENAME
    • :fprot
      • APR::Const::FPROT_GEXECUTE
      • APR::Const::FPROT_GREAD
      • APR::Const::FPROT_GSETID
      • APR::Const::FPROT_GWRITE
      • APR::Const::FPROT_OS_DEFAULT
      • APR::Const::FPROT_UEXECUTE
      • APR::Const::FPROT_UREAD
      • APR::Const::FPROT_USETID
      • APR::Const::FPROT_UWRITE
      • APR::Const::FPROT_WEXECUTE
      • APR::Const::FPROT_WREAD
      • APR::Const::FPROT_WSTICKY
      • APR::Const::FPROT_WWRITE
    • :filetype
      • APR::Const::FILETYPE_BLK
      • APR::Const::FILETYPE_CHR
      • APR::Const::FILETYPE_DIR
      • APR::Const::FILETYPE_LNK
      • APR::Const::FILETYPE_NOFILE
      • APR::Const::FILETYPE_PIPE
      • APR::Const::FILETYPE_REG
      • APR::Const::FILETYPE_SOCK
      • APR::Const::FILETYPE_UNKFILE
    • :finfo
      • APR::Const::FINFO_ATIME
      • APR::Const::FINFO_CSIZE
      • APR::Const::FINFO_CTIME
      • APR::Const::FINFO_DEV
      • APR::Const::FINFO_DIRENT
      • APR::Const::FINFO_GPROT
      • APR::Const::FINFO_GROUP
      • APR::Const::FINFO_ICASE
      • APR::Const::FINFO_IDENT
      • APR::Const::FINFO_INODE
      • APR::Const::FINFO_LINK
      • APR::Const::FINFO_MIN
      • APR::Const::FINFO_MTIME
      • APR::Const::FINFO_NAME
      • APR::Const::FINFO_NLINK
      • APR::Const::FINFO_NORM
      • APR::Const::FINFO_OWNER
      • APR::Const::FINFO_PROT
      • APR::Const::FINFO_SIZE
      • APR::Const::FINFO_TYPE
      • APR::Const::FINFO_UPROT
      • APR::Const::FINFO_USER
      • APR::Const::FINFO_WPROT
    • :flock
      • APR::Const::FLOCK_EXCLUSIVE
      • APR::Const::FLOCK_NONBLOCK
      • APR::Const::FLOCK_SHARED
      • APR::Const::FLOCK_TYPEMASK
    • :hook
      • APR::Const::HOOK_FIRST
      • APR::Const::HOOK_LAST
      • APR::Const::HOOK_MIDDLE
      • APR::Const::HOOK_REALLY_FIRST
      • APR::Const::HOOK_REALLY_LAST
    • :limit
      • APR::Const::LIMIT_CPU
      • APR::Const::LIMIT_MEM
      • APR::Const::LIMIT_NOFILE
      • APR::Const::LIMIT_NPROC
    • :lockmech
      • APR::Const::LOCK_DEFAULT
      • APR::Const::LOCK_FCNTL
      • APR::Const::LOCK_FLOCK
      • APR::Const::LOCK_POSIXSEM
      • APR::Const::LOCK_PROC_PTHREAD
      • APR::Const::LOCK_SYSVSEM
    • :poll
      • APR::Const::POLLERR
      • APR::Const::POLLHUP
      • APR::Const::POLLIN
      • APR::Const::POLLNVAL
      • APR::Const::POLLOUT
      • APR::Const::POLLPRI
    • :read_type
      • APR::Const::BLOCK_READ
      • APR::Const::NONBLOCK_READ
    • :shutdown_how
      • APR::Const::SHUTDOWN_READ
      • APR::Const::SHUTDOWN_READWRITE
      • APR::Const::SHUTDOWN_WRITE
    • :socket
      • APR::Const::SO_DEBUG
      • APR::Const::SO_DISCONNECTED
      • APR::Const::SO_KEEPALIVE
      • APR::Const::SO_LINGER
      • APR::Const::SO_NONBLOCK
      • APR::Const::SO_RCVBUF
      • APR::Const::SO_REUSEADDR
      • APR::Const::SO_SNDBUF
    • :status
      • APR::Const::TIMEUP
    • :table
      • APR::Const::OVERLAP_TABLES_MERGE
      • APR::Const::OVERLAP_TABLES_SET
    • :uri
      • APR::Const::URI_ACAP_DEFAULT_PORT
      • APR::Const::URI_FTP_DEFAULT_PORT
      • APR::Const::URI_GOPHER_DEFAULT_PORT
      • APR::Const::URI_HTTPS_DEFAULT_PORT
      • APR::Const::URI_HTTP_DEFAULT_PORT
      • APR::Const::URI_IMAP_DEFAULT_PORT
      • APR::Const::URI_LDAP_DEFAULT_PORT
      • APR::Const::URI_NFS_DEFAULT_PORT
      • APR::Const::URI_NNTP_DEFAULT_PORT
      • APR::Const::URI_POP_DEFAULT_PORT
      • APR::Const::URI_PROSPERO_DEFAULT_PORT
      • APR::Const::URI_RTSP_DEFAULT_PORT
      • APR::Const::URI_SIP_DEFAULT_PORT
      • APR::Const::URI_SNEWS_DEFAULT_PORT
      • APR::Const::URI_SSH_DEFAULT_PORT
      • APR::Const::URI_TELNET_DEFAULT_PORT
      • APR::Const::URI_TIP_DEFAULT_PORT
      • APR::Const::URI_UNP_OMITPASSWORD
      • APR::Const::URI_UNP_OMITPATHINFO
      • APR::Const::URI_UNP_OMITQUERY
      • APR::Const::URI_UNP_OMITSITEPART
      • APR::Const::URI_UNP_OMITUSER
      • APR::Const::URI_UNP_OMITUSERINFO
      • APR::Const::URI_UNP_REVEALPASSWORD
      • APR::Const::URI_WAIS_DEFAULT_PORT
    • Other Constants
      • APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED
  • See Also
  • Copyright
  • Authors

NAME

APR::Const - Perl Interface for APR Constants

Synopsis

  # make the constants available but don't import them
  use APR::Const -compile => qw(constant names ...);

  # w/o the => syntax sugar
  use APR::Const ("-compile", qw(constant names ...));

  # compile and import the constants
  use APR::Const qw(constant names ...);

Description

This package contains constants specific to APR features.

Refer to the Apache2::Const description section|docs::2.0::api::Apache2::Const/Description for more information.

Constants

:common

  use APR::Const -compile => qw(:common);

The :common group is for XXX constants.

APR::Const::SUCCESS

since: 2.0.00

:error

  use APR::Const -compile => qw(:error);

The :error group is for XXX constants.

APR::Const::EABOVEROOT

since: 2.0.00

APR::Const::EABSOLUTE

since: 2.0.00

APR::Const::EACCES

since: 2.0.00

Due to possible variants in conditions matching EACCES, for checking error codes against this you most likely want to use the APR::Status::is_EACCES|docs::2.0::api::APR::Status/C_is_EACCES_ function instead.

APR::Const::EAGAIN

since: 2.0.00

The error Resource temporarily unavailable, may be returned by many different system calls, especially IO calls. Most likely you want to use the APR::Status::is_EAGAIN|docs::2.0::api::APR::Status/C_is_EAGAIN_ function instead.

APR::Const::EBADDATE

since: 2.0.00

APR::Const::EBADF

since: 2.0.00

APR::Const::EBADIP

since: 2.0.00

APR::Const::EBADMASK

since: 2.0.00

APR::Const::EBADPATH

since: 2.0.00

APR::Const::EBUSY

since: 2.0.00

APR::Const::ECONNABORTED

since: 2.0.00

Due to possible variants in conditions matching ECONNABORTED, for checking error codes against this you most likely want to use the APR::Status::is_ECONNABORTED|docs::2.0::api::APR::Status/C_is_ECONNABORTED_ function instead.

APR::Const::ECONNREFUSED

since: 2.0.00

APR::Const::ECONNRESET

since: 2.0.00

Due to possible variants in conditions matching ECONNRESET, for checking error codes against this you most likely want to use the APR::Status::is_ECONNRESET|docs::2.0::api::APR::Status/C_is_ECONNRESET_ function instead.

APR::Const::EDSOOPEN

since: 2.0.00

APR::Const::EEXIST

since: 2.0.00

APR::Const::EFTYPE

since: 2.0.00

APR::Const::EGENERAL

since: 2.0.00

APR::Const::EHOSTUNREACH

since: 2.0.00

APR::Const::EINCOMPLETE

since: 2.0.00

APR::Const::EINIT

since: 2.0.00

APR::Const::EINPROGRESS

since: 2.0.00

APR::Const::EINTR

since: 2.0.00

APR::Const::EINVAL

since: 2.0.00

APR::Const::EINVALSOCK

since: 2.0.00

APR::Const::EMFILE

since: 2.0.00

APR::Const::EMISMATCH

since: 2.0.00

APR::Const::ENAMETOOLONG

since: 2.0.00

APR::Const::END

since: 2.0.00

APR::Const::ENETUNREACH

since: 2.0.00

APR::Const::ENFILE

since: 2.0.00

APR::Const::ENODIR

since: 2.0.00

APR::Const::ENOENT

since: 2.0.00

Due to possible variants in conditions matching ENOENT, for checking error codes against this you most likely want to use the APR::Status::is_ENOENT|docs::2.0::api::APR::Status/C_is_ENOENT_ function instead.

APR::Const::ENOLOCK

since: 2.0.00

APR::Const::ENOMEM

since: 2.0.00

APR::Const::ENOPOLL

since: 2.0.00

APR::Const::ENOPOOL

since: 2.0.00

APR::Const::ENOPROC

since: 2.0.00

APR::Const::ENOSHMAVAIL

since: 2.0.00

APR::Const::ENOSOCKET

since: 2.0.00

APR::Const::ENOSPC

since: 2.0.00

APR::Const::ENOSTAT

since: 2.0.00

APR::Const::ENOTDIR

since: 2.0.00

APR::Const::ENOTEMPTY

since: 2.0.00

APR::Const::ENOTHDKEY

since: 2.0.00

APR::Const::ENOTHREAD

since: 2.0.00

APR::Const::ENOTIME

since: 2.0.00

APR::Const::ENOTIMPL

Something is not implemented

since: 2.0.00

APR::Const::ENOTSOCK

since: 2.0.00

APR::Const::EOF

since: 2.0.00

Due to possible variants in conditions matching EOF, for checking error codes against this you most likely want to use the APR::Status::is_EOF|docs::2.0::api::APR::Status/C_is_EOF_ function instead.

APR::Const::EPATHWILD

since: 2.0.00

APR::Const::EPIPE

since: 2.0.00

APR::Const::EPROC_UNKNOWN

since: 2.0.00

APR::Const::ERELATIVE

since: 2.0.00

APR::Const::ESPIPE

since: 2.0.00

APR::Const::ESYMNOTFOUND

since: 2.0.00

APR::Const::ETIMEDOUT

since: 2.0.00

APR::Const::EXDEV

since: 2.0.00

:fopen

  use APR::Const -compile => qw(:fopen);

The :fopen group is for XXX constants.

APR::Const::FOPEN_BINARY

since: 2.0.00

APR::Const::FOPEN_BUFFERED

since: 2.0.00

APR::Const::FOPEN_CREATE

since: 2.0.00

APR::Const::FOPEN_DELONCLOSE

since: 2.0.00

APR::Const::FOPEN_EXCL

since: 2.0.00

APR::Const::FOPEN_PEND

since: 2.0.00

APR::Const::FOPEN_READ

since: 2.0.00

APR::Const::FOPEN_TRUNCATE

since: 2.0.00

APR::Const::FOPEN_WRITE

since: 2.0.00

:filepath

  use APR::Const -compile => qw(:filepath);

The :filepath group is for XXX constants.

APR::Const::FILEPATH_ENCODING_LOCALE

since: 2.0.00

APR::Const::FILEPATH_ENCODING_UNKNOWN

since: 2.0.00

APR::Const::FILEPATH_ENCODING_UTF8

since: 2.0.00

APR::Const::FILEPATH_NATIVE

since: 2.0.00

APR::Const::FILEPATH_NOTABOVEROOT

since: 2.0.00

APR::Const::FILEPATH_NOTABSOLUTE

since: 2.0.00

APR::Const::FILEPATH_NOTRELATIVE

since: 2.0.00

APR::Const::FILEPATH_SECUREROOT

since: 2.0.00

APR::Const::FILEPATH_SECUREROOTTEST

since: 2.0.00

APR::Const::FILEPATH_TRUENAME

since: 2.0.00

:fprot

  use APR::Const -compile => qw(:fprot);

The :fprot group is used by $finfo->protection|docs::2.0::api::APR::Finfo/C_protection_.

APR::Const::FPROT_GEXECUTE

Execute by group

since: 2.0.00

APR::Const::FPROT_GREAD

Read by group

since: 2.0.00

APR::Const::FPROT_GSETID

Set group id

since: 2.0.00

APR::Const::FPROT_GWRITE

Write by group

since: 2.0.00

APR::Const::FPROT_OS_DEFAULT

use OS's default permissions

since: 2.0.00

APR::Const::FPROT_UEXECUTE

Execute by user

since: 2.0.00

APR::Const::FPROT_UREAD

Read by user

since: 2.0.00

APR::Const::FPROT_USETID

Set user id

since: 2.0.00

APR::Const::FPROT_UWRITE

Write by user

since: 2.0.00

APR::Const::FPROT_WEXECUTE

Execute by others

since: 2.0.00

APR::Const::FPROT_WREAD

Read by others

since: 2.0.00

APR::Const::FPROT_WSTICKY

Sticky bit

since: 2.0.00

APR::Const::FPROT_WWRITE

Write by others

since: 2.0.00

:filetype

  use APR::Const -compile => qw(:filetype);

The :filetype group is used by $finfo->filetype|docs::2.0::api::APR::Finfo/C_filetype_.

APR::Const::FILETYPE_BLK

a file is a block device

since: 2.0.00

APR::Const::FILETYPE_CHR

a file is a character device

since: 2.0.00

APR::Const::FILETYPE_DIR

a file is a directory

since: 2.0.00

APR::Const::FILETYPE_LNK

a file is a symbolic link

since: 2.0.00

APR::Const::FILETYPE_NOFILE

the file type is undedetermined.

since: 2.0.00

APR::Const::FILETYPE_PIPE

a file is a FIFO or a pipe.

since: 2.0.00

APR::Const::FILETYPE_REG

a file is a regular file.

since: 2.0.00

APR::Const::FILETYPE_SOCK

a file is a [unix domain] socket.

since: 2.0.00

APR::Const::FILETYPE_UNKFILE

a file is of some other unknown type or the type cannot be determined.

since: 2.0.00

:finfo

  use APR::Const -compile => qw(:finfo);

The :finfo group is used by stat()|docs::2.0::api::APR::Finfo/C_stat_ and $finfo->valid|docs::2.0::api::APR::Finfo/C_valid_.

APR::Const::FINFO_ATIME

Access Time

since: 2.0.00

APR::Const::FINFO_CSIZE

Storage size consumed by the file

since: 2.0.00

APR::Const::FINFO_CTIME

Creation Time

since: 2.0.00

APR::Const::FINFO_DEV

Device

since: 2.0.00

APR::Const::FINFO_DIRENT

an atomic unix apr_dir_read()

since: 2.0.00

APR::Const::FINFO_GPROT

Group protection bits

since: 2.0.00

APR::Const::FINFO_GROUP

Group id

since: 2.0.00

APR::Const::FINFO_ICASE

whether device is case insensitive

since: 2.0.00

APR::Const::FINFO_IDENT

device and inode

since: 2.0.00

APR::Const::FINFO_INODE

Inode

since: 2.0.00

APR::Const::FINFO_LINK

Stat the link not the file itself if it is a link

since: 2.0.00

APR::Const::FINFO_MIN

type, mtime, ctime, atime, size

since: 2.0.00

APR::Const::FINFO_MTIME

Modification Time

since: 2.0.00

APR::Const::FINFO_NAME

name in proper case

since: 2.0.00

APR::Const::FINFO_NLINK

Number of links

since: 2.0.00

APR::Const::FINFO_NORM

All fields provided by an atomic unix apr_stat()

since: 2.0.00

APR::Const::FINFO_OWNER

user and group

since: 2.0.00

APR::Const::FINFO_PROT

all protections

since: 2.0.00

APR::Const::FINFO_SIZE

Size of the file

since: 2.0.00

APR::Const::FINFO_TYPE

Type

since: 2.0.00

APR::Const::FINFO_UPROT

User protection bits

since: 2.0.00

APR::Const::FINFO_USER

User id

since: 2.0.00

APR::Const::FINFO_WPROT

World protection bits

since: 2.0.00

:flock

  use APR::Const -compile => qw(:flock);

The :flock group is for XXX constants.

APR::Const::FLOCK_EXCLUSIVE

since: 2.0.00

APR::Const::FLOCK_NONBLOCK

since: 2.0.00

APR::Const::FLOCK_SHARED

since: 2.0.00

APR::Const::FLOCK_TYPEMASK

since: 2.0.00

:hook

  use APR::Const -compile => qw(:hook);

The :hook group is for XXX constants.

APR::Const::HOOK_FIRST

since: 2.0.00

APR::Const::HOOK_LAST

since: 2.0.00

APR::Const::HOOK_MIDDLE

since: 2.0.00

APR::Const::HOOK_REALLY_FIRST

since: 2.0.00

APR::Const::HOOK_REALLY_LAST

since: 2.0.00

:limit

  use APR::Const -compile => qw(:limit);

The :limit group is for XXX constants.

APR::Const::LIMIT_CPU

since: 2.0.00

APR::Const::LIMIT_MEM

since: 2.0.00

APR::Const::LIMIT_NOFILE

since: 2.0.00

APR::Const::LIMIT_NPROC

since: 2.0.00

:lockmech

  use APR::Const -compile => qw(:lockmech);

The :lockmech group is for XXX constants.

APR::Const::LOCK_DEFAULT

since: 2.0.00

APR::Const::LOCK_FCNTL

since: 2.0.00

APR::Const::LOCK_FLOCK

since: 2.0.00

APR::Const::LOCK_POSIXSEM

since: 2.0.00

APR::Const::LOCK_PROC_PTHREAD

since: 2.0.00

APR::Const::LOCK_SYSVSEM

since: 2.0.00

:poll

  use APR::Const -compile => qw(:poll);

The :poll group is used by poll|docs::2.0::api::APR::Socket/C_poll_.

APR::Const::POLLERR

since: 2.0.00

Pending error

APR::Const::POLLHUP

since: 2.0.00

Hangup occurred

APR::Const::POLLIN

since: 2.0.00

Can read without blocking

APR::Const::POLLNVAL

since: 2.0.00

Descriptior invalid

APR::Const::POLLOUT

since: 2.0.00

Can write without blocking

APR::Const::POLLPRI

since: 2.0.00

Priority data available

:read_type

  use APR::Const -compile => qw(:read_type);

The :read_type group is for IO constants.

APR::Const::BLOCK_READ

since: 2.0.00

the read function blocks

APR::Const::NONBLOCK_READ

since: 2.0.00

the read function does not block

:shutdown_how

  use APR::Const -compile => qw(:shutdown_how);

The :shutdown_how group is for XXX constants.

APR::Const::SHUTDOWN_READ

since: 2.0.00

APR::Const::SHUTDOWN_READWRITE

since: 2.0.00

APR::Const::SHUTDOWN_WRITE

since: 2.0.00

:socket

  use APR::Const -compile => qw(:socket);

The :socket group is for the
APR::Socket|docs::2.0::api::APR::Socket object constants, in
methods opt_get|docs::2.0::api::APR::Socket/C_opt_get_ and
opt_set|docs::2.0::api::APR::Socket/C_opt_set_.

The following section discusses in detail each of the :socket constants.

APR::Const::SO_DEBUG

Possible values:

XXX

since: 2.0.00

Turns on debugging information

APR::Const::SO_DISCONNECTED

Queries the disconnected state of the socket. (Currently only used on Windows)

Possible values:

XXX

since: 2.0.00

APR::Const::SO_KEEPALIVE

Keeps connections active

Possible values:

XXX

since: 2.0.00

APR::Const::SO_LINGER

Lingers on close if data is present

since: 2.0.00

APR::Const::SO_NONBLOCK

Turns blocking IO mode on/off for socket.

Possible values:

  1 nonblocking
  0 blocking

For example, to set a socket to a blocking IO mode:

  use APR::Socket ();
  use APR::Const    -compile => qw(SO_NONBLOCK);
  ...
  if ($socket->opt_get(APR::Const::SO_NONBLOCK)) {
      $socket->opt_set(APR::Const::SO_NONBLOCK => 0);
  }

You don't have to query for this option, before setting it. It was done for the demonstration purpose.

since: 2.0.00

APR::Const::SO_RCVBUF

Controls the ReceiveBufferSize setting

Possible values:

XXX

since: 2.0.00

APR::Const::SO_REUSEADDR

The rules used in validating addresses supplied to bind should allow reuse of local addresses.

Possible values:

XXX

since: 2.0.00

APR::Const::SO_SNDBUF

Controls the SendBufferSize setting

Possible values:

XXX

since: 2.0.00

:status

  use APR::Const -compile => qw(:status);

The :status group is for the API that return status code, or set the error variable XXXXXX.

The following section discusses in detail each of the available :status constants.

APR::Const::TIMEUP

The operation did not finish before the timeout.

since: 2.0.00

Due to possible variants in conditions matching TIMEUP, for checking error codes against this you most likely want to use the APR::Status::is_TIMEUP|docs::2.0::api::APR::Status/C_is_TIMEUP_ function instead.

:table

  use APR::Const -compile => qw(:table);

The :table group is for overlap() and compress() constants. See APR::Table|docs::2.0::api::APR::Table for details.

APR::Const::OVERLAP_TABLES_MERGE

since: 2.0.00

See APR::Table::compress|docs::2.0::api::APR::Table/C_compress_ and APR::Table::overlap|docs::2.0::api::APR::Table/C_overlap_.

APR::Const::OVERLAP_TABLES_SET

since: 2.0.00

See APR::Table::compress|docs::2.0::api::APR::Table/C_compress_ and APR::Table::overlap|docs::2.0::api::APR::Table/C_overlap_.

:uri

  use APR::Const -compile => qw(:uri);

The :uri group of constants is for manipulating URIs.

APR::Const::URI_ACAP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_FTP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_GOPHER_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_HTTPS_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_HTTP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_IMAP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_LDAP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_NFS_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_NNTP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_POP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_PROSPERO_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_RTSP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_SIP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_SNEWS_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_SSH_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_TELNET_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_TIP_DEFAULT_PORT

since: 2.0.00

APR::Const::URI_UNP_OMITPASSWORD

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_UNP_OMITPATHINFO

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_UNP_OMITQUERY

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_UNP_OMITSITEPART

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_UNP_OMITUSER

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_UNP_OMITUSERINFO

since: 2.0.00

APR::Const::URI_UNP_REVEALPASSWORD

since: 2.0.00

See APR::URI::unparse|docs::2.0::api::APR::URI/C_unparse_.

APR::Const::URI_WAIS_DEFAULT_PORT

since: 2.0.00

Other Constants

APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED

since: 2.0.00

See APR::PerlIO::Constants|docs::2.0::api::APR::PerlIO/Constants)

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Date - Perl API for APR date manipulating functions

  • Synopsis
  • Description
  • API
    • parse_http
    • parse_rfc
  • See Also
  • Copyright
  • Authors

NAME

APR::Date - Perl API for APR date manipulating functions

Synopsis

  use APR::Date ();

  # parse HTTP-complient date string
  $date_string = 'Sun, 06 Nov 1994 08:49:37 GMT';
  $date_parsed = APR::Date::parse_http($date_string);

  # parse RFC822-complient date string
  $date_string = 'Sun, 6 Nov 94 8:49:37 GMT';
  $date_parsed = APR::Date::parse_rfc($date_string);

Description

APR::Socket provides the Perl interface to APR date manipulating functions.

API

APR::Date provides the following functions and/or methods:

parse_http

Parse HTTP date strings

  $date_parsed = parse_http($date_string);
arg1: $date_string ( string )

The date string can be in one of the following formats:

  Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
  Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
  Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format

refer to RFC2616 for the details (GMT is assumed, regardless of the used timezone).

ret: $date_parsed ( number )

the number of microseconds since 1 Jan 1970 GMT, or 0 if out of range or if the date is invalid.

since: 2.0.00

Remember to divide the return value by 1_000_000 if you need it in seconds.

parse_rfc

Parse a string resembling an RFC 822 date. It's meant to be lenient in its parsing of dates. Hence, this will parse a wider range of dates than parse_http()|/C_parse_http_.

  $date_parsed = parse_rfc($date_string);
arg1: $date_string ( string )

The date string can be in one of the following formats:

  Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
  Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
  Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format
  Sun, 6 Nov 1994 08:49:37 GMT   ; RFC 822, updated by RFC 1123
  Sun, 06 Nov 94 08:49:37 GMT    ; RFC 822
  Sun, 6 Nov 94 08:49:37 GMT     ; RFC 822
  Sun, 06 Nov 94 08:49 GMT       ; Unknown [drtr\@ast.cam.ac.uk]
  Sun, 6 Nov 94 08:49 GMT        ; Unknown [drtr\@ast.cam.ac.uk]
  Sun, 06 Nov 94 8:49:37 GMT     ; Unknown [Elm 70.85]
  Sun, 6 Nov 94 8:49:37 GMT      ; Unknown [Elm 70.85]
ret: $date_parsed ( number )

the number of microseconds since 1 Jan 1970 GMT, or 0 if out of range or if the date is invalid.

since: 2.0.00

Remember to divide the return value by 1_000_000 if you need it in seconds.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Error - Perl API for APR/Apache/mod_perl exceptions

  • Synopsis
  • Description
  • API
    • cluck
    • confess
    • strerror
  • See Also
  • Copyright
  • Authors

NAME

APR::Error - Perl API for APR/Apache/mod_perl exceptions

Synopsis

  eval { $obj->mp_method() };
  if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code) {
      # handle the exception
  }
  else {
      die $@; # rethrow it
  }

Description

APR::Error handles APR/Apache/mod_perl exceptions for you, while leaving you in control.

Apache and APR API return a status code for almost all methods, so if you didn't check the return code and handled any possible problems, you may have silent failures which may cause all kind of obscure problems. On the other hand checking the status code after each call is just too much of a kludge and makes quick prototyping/development almost impossible, not talking about the code readability. Having methods return status codes, also complicates the API if you need to return other values.

Therefore to keep things nice and make the API readable we decided to not return status codes, but instead throw exceptions with APR::Error objects for each method that fails. If you don't catch those exceptions, everything works transparently - perl will intercept the exception object and die() with a proper error message. So you get all the errors logged without doing any work.

Now, in certain cases you don't want to just die, but instead the error needs to be trapped and handled. For example if some IO operation times out, may be it is OK to trap that and try again. If we were to die with an error message, you would have had to match the error message, which is ugly, inefficient and may not work at all if locale error strings are involved. Therefore you need to be able to get the original status code that Apache or APR has generated. And the exception objects give you that if you want to. Moreover the objects contain additional information, such as the function name (in case you were eval'ing several commands in one block), file and line number where that function was invoked from. More attributes could be added in the future.

APR::Error uses Perl operator overloading, such that in boolean and numerical contexts, the object returns the status code; in the string context the full error message is returned.

When intercepting exceptions you need to check whether $@ is an object (reference). If your application uses other exception objects you additionally need to check whether this is a an APR::Error object. Therefore most of the time this is enough:

  eval { $obj->mp_method() };
  if ($@ && $ref $@ && $@ == $some_code)
      warn "handled exception: $@";
  }

But with other, non-mod_perl, exception objects you need to do:

  eval { $obj->mp_method() };
  if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
      warn "handled exception: $@";
  }

In theory you could even do:

  eval { $obj->mp_method() };
  if ($@ && $@ == $some_code)
      warn "handled exception: $@";
  }

but it's possible that the method will die with a plain string and not an object, in which case $@ == $some_code won't quite work. Remember that mod_perl throws exception objects only when Apache and APR fail, and in a few other special cases of its own (like exit|docs::2.0::api::ModPerl::Util/C_exit_).

  warn "handled exception: $@" if $@ && $ref $@;

There are two ways to figure out whether an error fits your case. In most cases you just compare $@ with an the error constant. For example if a socket has a timeout set and the data wasn't read within the timeout limit a APR::Const::TIMEUP|docs::2.0::api::APR::Const/C_APR__Const__TIMEUP_)

  use APR::Const -compile => qw(TIMEUP);
  $sock->timeout_set(1_000_000); # 1 sec
  my $buff;
  eval { $sock->recv($buff, BUFF_LEN) };
  if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {

  }

However there are situations, where on different Operating Systems a different error code will be returned. In which case to simplify the code you should use the special subroutines provided by the APR::Status|docs::2.0::api::APR::Status class. One such condition is socket recv() timeout, which on Unix throws the EAGAIN error, but on other system it throws a different error. In this case APR::Status::is_EAGAIN|docs::2.0::api::APR::Status/C_is_EAGAIN_ should be used.

Let's look at a complete example. Here is a code that performs a socket read:

  my $rlen = $sock->recv(my $buff, 1024);
  warn "read $rlen bytes\n";

and in certain cases it times out. The code will die and log the reason for the failure, which is fine, but later on you may decide that you want to have another attempt to read before dying and add some fine grained sleep time between attempts, which can be achieved with select. Which gives us:

  use APR::Status ();
  # ....
  my $tries = 0;
  my $buffer;
  RETRY: my $rlen = eval { $sock->recv($buffer, SIZE) };
  if ($@)
      die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
      if ($tries++ < 3) {
          # sleep 250msec
          select undef, undef, undef, 0.25;
          goto RETRY;
      }
      else {
          # do something else
      }
  }
  warn "read $rlen bytes\n"

Notice that we handle non-object and non-APR::Error exceptions as well, by simply re-throwing them.

Finally, the class is called APR::Error because it needs to be used outside mod_perl as well, when called from APR|docs::2.0::api::APR applications written in Perl.

API

cluck

cluck is an equivalent of Carp::cluck that works with APR::Error exception objects.

confess

confess is an equivalent of Carp::confess that works with APR::Error exception objects.

strerror

Convert APR error code to its string representation.

  $error_str = APR::Error::strerror($rc);
ret: $rc ( APR::Const status constant|docs::2.0::api::APR::Const )

The numerical value for the return (error) code

ret: $error_str ( string )

The string error message corresponding to the numerical value inside $rc. (Similar to the C function strerror(3))

since: 2.0.00

Example:

Try to retrieve the bucket brigade, and if the return value doesn't indicate success or end of file (usually in protocol handlers) die, but give the user the human-readable version of the error and not just the code.

  my $rc = $c->input_filters->get_brigade($bb_in,
                                          Apache2::Const::MODE_GETLINE);
  if ($rc != APR::Const::SUCCESS && $rc != APR::Const::EOF) {
      my $error = APR::Error::strerror($rc);
      die "get_brigade error: $rc: $error\n";
  }

It's probably a good idea not to omit the numerical value in the error message, in case the error string is generated with non-English locale.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Finfo - Perl API for APR fileinfo structure

  • Synopsis
  • Description
  • API
    • atime
    • csize
    • ctime
    • device
    • filetype
    • fname
    • group
    • inode
    • mtime
    • name
    • nlink
    • protection
    • size
    • stat
    • user
    • valid
  • See Also
  • Copyright
  • Authors

NAME

APR::Finfo - Perl API for APR fileinfo structure

Synopsis

  use APR::Finfo ();
  use APR::Const -compile => qw(FINFO_NORM);
  my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);

  $device = $finfo->device;     # (stat $file)[0]
  $inode  = $finfo->inode;      # (stat $file)[1]
  $prot   = $finfo->protection; # (stat $file)[2]
  $nlink  = $finfo->nlink;      # (stat $file)[3]
  $gid    = $finfo->group;      # (stat $file)[4]
  $uid    = $finfo->user;       # (stat $file)[5]
  $size   = $finfo->size;       # (stat $file)[7]
  $atime  = $finfo->atime;      # (stat $file)[8]
  $mtime  = $finfo->mtime;      # (stat $file)[9]
  $ctime  = $finfo->ctime;      # (stat $file)[10]

  $csize = $finfo->csize; # consumed size: not portable!

  $filetype = $finfo->filetype; # file/dir/socket/etc

  $fname = $finfo->fname;
  $name  = $finfo->name;  # in filesystem case:

  # valid fields that can be queried
  $valid = $finfo->valid;

Description

APR fileinfo structure provides somewhat similar information to Perl's stat() call, but you will want to use this module's API to query an already stat()'ed filehandle to avoid an extra system call or to query attributes specific to APR file handles.

During the HTTP request handlers coming after PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler, $r->finfo|docs::2.0::api::Apache2::RequestRec/C_finfo_ already contains the cached values from the apr's stat() call. So you don't want to perform it again, but instead get the ARP::Finfo object via:

  my $finfo = $r->finfo;

API

APR::Finfo provides the following functions and/or methods:

atime

Get the time the file was last accessed:

  $atime = $finfo->atime;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $atime ( integer )

Last access time in seconds since the epoch

since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[8]

Note that this method may not be reliable on all platforms, most notably Win32 -- FAT32 filesystems appear to work properly, but NTFS filesystems do not.

csize

Get the storage size consumed by the file

  $csize = $finfo->csize;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $csize ( integer )
since: 2.0.00

Chances are that you don't want to use this method, since its functionality is not supported on most platforms (in which case it always returns 0).

ctime

Get the time the file was last changed

  $ctime = $finfo->ctime;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $ctime ( integer )

Inode change time in seconds since the epoch

since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[10]

The ctime field is non-portable. In particular, you cannot expect it to be a "creation time", see "Files and Filesystems" in the perlport manpage for details.

device

Get the id of the device the file is on.

  $device = $finfo->device;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $device ( integer )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[0]

Note that this method is non-portable. It doesn't work on all platforms, most notably Win32.

filetype

Get the type of file.

  $filetype = $finfo->filetype;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $filetype ( :filetype constant|docs::2.0::api::APR::Const/C__filetype_ )
since: 2.0.00

For example:

  use APR::Pool;
  use APR::Finfo;
  use APR::Const -compile => qw(FILETYPE_DIR FILETYPE_REG FINFO_NORM);
  my $pool  = APR::Pool->new();
  my $finfo = APR::Finfo::stat("/tmp", APR::Const::FINFO_NORM, $pool);
  my $finfo = $finfo->filetype;
  if ($finfo == APR::Const::FILETYPE_REG) {
      print "regular file";
  }
  elsif ($finfo == APR::Const::FILETYPE_REG) {
      print "directory";
  }
  else {
      print "other file";
  }

Since /tmp is a directory, this will print:

  directory

fname

Get the pathname of the file (possibly unrooted)

  $fname = $finfo->fname;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $filetype ( string )
since: 2.0.00

group

Get the group id that owns the file:

  $gid = $finfo->group;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $gid ( number )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[5]

Note that this method may not be meaningful on all platforms, most notably Win32. Incorrect results have also been reported on some versions of OSX.

inode

Get the inode of the file.

  $inode = $finfo->inode;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $inode ( integer )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[1]

Note that this method may not be meaningful on all platforms, most notably Win32.

mtime

The time the file was last modified

  $mtime = $finfo->mtime;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $mtime ( integer )

Last modify time in seconds since the epoch

since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[9]

name

Get the file's name (no path) in filesystem case:

  $name = $finfo->name;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $device ( string )
since: 2.0.00

nlink

Get the number of hard links to the file.

  $nlink = $finfo->nlink;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $nlink ( integer )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[3]

protection

Get the access permissions of the file. Mimics Unix access rights.

  $prot = $finfo->protection;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $prot ( :fprot constant|docs::2.0::api::APR::Const/C__fprot_ )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[2]

size

Get the size of the file

  $size = $finfo->size;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $size ( integer )

Total size of file, in bytes

since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[7]

stat

Get the specified file's stats.

  $finfo = APR::Finfo::stat($fname, $wanted_fields, $p);
arg1: $fname ( string )

The path to the file to stat().

arg2: $wanted_fields ( :finfo constant|docs::2.0::api::APR::Const/C__finfo_ )

The desired fields, as a bitmask flag of APR::FINFO_*|docs::2.0::api::APR::Const/C__finfo_ constants.

Notice that you can also use the constants that already combine several elements in one. For example APR::Const::FINFO_PROT|docs::2.0::api::APR::Const/C_APR__Const__FINFO_PROT_ asks for all protection bits, APR::Const::FINFO_MIN|docs::2.0::api::APR::Const/C_APR__Const__FINFO_MIN_ asks for the following fields: type, mtime, ctime, atime, size and APR::Const::FINFO_NORM|docs::2.0::api::APR::Const/C_APR__Const__FINFO_NORM_ asks for all atomic unix apr_stat() fields (similar to perl's stat()).

arg3: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

the pool to use to allocate the file stat structure.

ret: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
since: 2.0.00

For example, here is how to get most of the stat fields:

  use APR::Pool ();
  use APR::Finfo ();
  use APR::Const -compile => qw(FINFO_NORM);
  my $pool = APR::Pool->new();
  my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);

user

Get the user id that owns the file:

  $uid = $finfo->user;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
return: $uid ( number )
since: 2.0.00

This method returns the same value as Perl's:

  (stat $filename)[4]

Note that this method may not be meaningful on all platforms, most notably Win32.

valid

The bitmask describing valid fields of this apr_finfo_t structure including all available 'wanted' fields and potentially more

  $valid = $finfo->valid;
obj: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
arg1: $valid ( bitmask )

This bitmask flag should be bit-OR'ed against :finfo constant|docs::2.0::api::APR::Const/C__finfo_ constants.

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::IpSubnet - Perl API for accessing APRs ip_subnet structures

  • Synopsis
  • Description
  • API
    • new
    • test
  • See Also
  • Copyright
  • Authors

NAME

APR::IpSubnet - Perl API for accessing APRs ip_subnet structures

Synopsis

  use APR::IpSubnet ();

  my $ipsub = APR::IpSubnet->new($pool, "127.0.0.1");
  $ok = $ipsub->test($sock_addr);

Description

APR::IpSubnet object represents a range of IP addresses (IPv4/IPv6). A socket connection can be matched against this range to test whether the IP it's coming from is inside or outside of this range.

API

APR::IpSubnet provides the following functions and/or methods:

new

Create an IP subnet represenation object

  $ipsubnet = APR::IpSubnet->new($pool, $ip);
  $ipsubnet = APR::IpSubnet->new($pool, $ip, $mask_or_numbits);
obj: APR::IpSubnet (class name)
arg1: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )
arg2: $ip ( string )

IP address in one of the two formats: IPv4 (e.g. "127.0.0.1") or IPv6 (e.g. "::1"). IPv6 addresses are accepted only if APR has the IPv6 support enabled.

opt arg3: $mask_or_numbits ( string )

An optional IP mask (e.g. "255.0.0.0") or number of bits (e.g. "15").

If none provided, the default is not to mask off.

ret: $ret ( APR::IpSubnet object|docs::2.0::api::APR::IpSubnet )

The IP-subnet object

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

test

Test the IP address in the socket address object against a pre-built ip-subnet representation.

  $ret = $ipsub->test($sockaddr);
obj: $ipsub ( APR::IpSubnet object|docs::2.0::api::APR::IpSubnet )

The ip-subnet representation

arg1: $sockaddr ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

The socket address to test

ret: $ret ( boolean )

true if the socket address is within the subnet, false otherwise

since: 2.0.00

This method is used for testing whether or not an address is within a subnet. It's used by module mod_access to check whether the client IP fits into the IP range, supplied by Allow/Deny directives.

Example:

Allow accesses only from the localhost (IPv4):

  use APR::IpSubnet ();
  use Apache2::Connection ();
  use Apache2::RequestRec ();
  my $ipsub = APR::IpSubnet->new($r->pool, "127.0.0.1");
  ok $ipsub->test($r->connection->remote_addr);

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::OS - Perl API for Platform-specific APR API

  • Synopsis
  • Description
  • API
    • current_thread_id
  • See Also
  • Copyright
  • Authors

NAME

APR::OS - Perl API for Platform-specific APR API

Synopsis

  use APR::OS ();

  # get current thread id
  my $tid = APR::OS::current_thread_id();

Description

APR::OS provides the Perl interface to platform-specific APR API.

You should be extremely careful when relying on any of the API provided by this module, since they are no portable. So if you use those you application will be non-portable as well.

API

APR::OS provides the following methods:

current_thread_id

Get the current thread ID

  $tid = APR::OS::current_thread_id();
ret: $tid ( integer )

under threaded MPMs returns the current thread ID, otherwise 0.

since: 2.0.00

Example:

    use Apache2::MPM ();
    use APR::OS ();
    if (Apache2::MPM->is_threaded) {
        my $tid_obj = APR::OS::current_thread_id();
        print "TID: $tid";
    }
    else {
        print "PID: $$";
    }

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::PerlIO -- Perl IO layer for APR

  • Synopsis
  • Description
  • Prerequisites
  • Constants
    • APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED
  • API
    • open
    • seek
  • C API
  • See Also
  • Copyright
  • Authors

NAME

APR::PerlIO -- Perl IO layer for APR

Synopsis

  # under mod_perl
  use APR::PerlIO ();

  sub handler {
      my $r = shift;

      die "This Perl build doesn't support PerlIO layers"
          unless APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED;

      open my $fh, ">:APR", $filename, $r->pool or die $!;
      # work with $fh as normal $fh
      close $fh;

      return Apache2::Const::OK;
  }

  # outside mod_perl
  % perl -MAPR -MAPR::PerlIO -MAPR::Pool -le \
  'open my $fh, ">:APR", "/tmp/apr", APR::Pool->new or die "$!"; \
   print $fh "whoah!"; \
   close $fh;'

Description

APR::PerlIO implements a Perl IO layer using APR's file manipulation API internally.

Why do you want to use this? Normally you shouldn't, probably it won't be faster than Perl's default layer. It's only useful when you need to manipulate a filehandle opened at the APR side, while using Perl.

Normally you won't call open() with APR layer attribute, but some mod_perl functions will return a filehandle which is internally hooked to APR. But you can use APR Perl IO directly if you want.

Prerequisites

Not every Perl will have full APR::PerlIO functionality available.

Before using the Perl IO APR layer one has to check whether it's supported by the used APR/Perl build. Perl 5.8.x or higher with perlio enabled is required. You can check whether your Perl fits the bill by running:

  % perl -V:useperlio
  useperlio='define';

It should say define.

If you need to do the checking in the code, there is a special constant provided by APR::PerlIO, which can be used as follows:

  use APR::PerlIO ();
  die "This Perl build doesn't support PerlIO layers"
      unless APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED;

Notice that loading APR::PerlIO won't fail when Perl IO layers aren't available since APR::PerlIO provides functionality for Perl builds not supporting Perl IO layers.

Constants

APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED

See Prerequisites.

API

Most of the API is as in normal perl IO with a few nuances listed in the following sections.

META: need to rework the exception mechanism here. Current success in using errno ($!) being set (e.g. on open()) is purely accidental and not guaranteed across all platforms and functions. So don't rely on $!. Will use APR::Error|docs::2.0::api::APR::Error for that purpose.

open

Open a file via APR Perl IO layer.

  open my $fh, ">:APR", $filename, $r->pool or die $!;
arg1: $fh ( GLOB filehandle )

The filehandle.

arg2: $mode ( string )

The mode to open the file, constructed from two sections separated by the : character: the first section is the mode to open the file under (>, <, etc) and the second section must be a string APR. For more information refer to the open entry in the perlfunc manpage.

arg3: $filename ( string )

The path to the filename to open

arg4: $p ( APR::Pool|docs::2.0::api::APR::Pool )

The pool object to use to allocate APR::PerlIO layer.

ret: ( integer )

success or failure value (boolean).

since: 2.0.00

seek

Sets $fh's position, just like the seek() Perl call:

  seek($fh, $offset, $whence);

If $offset is zero, seek() works normally.

However if $offset is non-zero and Perl has been compiled with with large files support (-Duselargefiles), whereas APR wasn't, this function will croak. This is because largefile size Off_t simply cannot fit into a non-largefile size apr_off_t.

To solve the problem, rebuild Perl with -Uuselargefiles. Currently there is no way to force APR to build with large files support.

since: 2.0.00

C API

The C API provides functions to convert between Perl IO and APR Perl IO filehandles.

META: document these

See Also

mod_perl 2.0 documentation. The perliol(1), perlapio(1) and perl(1) manpages.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Pool - Perl API for APR pools

  • Synopsis
  • Description
  • API
    • cleanup_register
    • clear
    • DESTROY
    • destroy
    • is_ancestor
    • new
    • parent_get
    • tag
  • Unsupported API
    • cleanup_for_exec
  • See Also
  • Copyright
  • Authors

NAME

APR::Pool - Perl API for APR pools

Synopsis

  use APR::Pool ();

  my $sp = $r->pool->new;
  my $sp2 = APR::Pool->new;

  # $sp3 is a subpool of $sp,
  # which in turn is a subpool of $r->pool
  $sp3 = $sp->new;
  print '$r->pool is an ancestor of $sp3'
      if $r->pool->is_ancestor($sp3);
  # but sp2 is not a sub-pool of $r->pool
  print '$r->pool is not an ancestor of $sp2'
      unless $r->pool->is_ancestor($sp2);

  # $sp4 and $sp are the same pool (though you can't
  # compare the handle as variables)
  my $sp4 = $sp3->parent_get;

  # register a dummy cleanup function
  # that just prints the passed args
  $sp->cleanup_register(sub { print @{ $_[0] || [] } }, [1..3]);

  # tag the pool
  $sp->tag("My very best pool");

  # clear the pool
  $sp->clear();

  # destroy sub pool
  $sp2->destroy;

Description

APR::Pool provides an access to APR pools, which are used for an easy memory management.

Different pools have different life scopes and therefore one doesn't need to free allocated memory explicitly, but instead it's done when the pool's life is getting to an end. For example a request pool is created at the beginning of a request and destroyed at the end of it, and all the memory allocated during the request processing using the request pool is freed at once at the end of the request.

Most of the time you will just pass various pool objects to the methods that require them. And you must understand the scoping of the pools, since if you pass a long lived server pool to a method that needs the memory only for a short scoped request, you are going to leak memory. A request pool should be used in such a case. And vice versa, if you need to allocate some memory for a scope longer than a single request, then a request pool is inappropriate, since when the request will be over, the memory will be freed and bad things may happen.

If you need to create a new pool, you can always do that via the new()|/C_new_ method.

API

APR::Pool provides the following functions and/or methods:

cleanup_register

Register cleanup callback to run

  $pool->cleanup_register($callback);
  $pool->cleanup_register($callback, $arg);
obj: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool object to register the cleanup callback for

arg1: $callback ( CODE ref or sub name )

a cleanup callback CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

opt arg2: $arg ( SCALAR )

If this optional argument is passed, the $callback function will receive it as the first and only argument when executed.

To pass more than one argument, use an ARRAY or a HASH reference

ret: no return value
excpt:

if the registered callback fails, it happens when the pool is destroyed. The destruction is performed by Apache and it ignores any failures. Even if it didn't ignore the failures, most of the time the pool is destroyed when a request or connection handlers are long gone. However the error is logged to error_log, so if you monitor that file you will spot if there are any problems with it.

since: 2.0.00

If there is more than one callback registered (when cleanup_register is called more than once on the same pool object), the last registered callback will be executed first (LIFO).

Examples:

No arguments, using anon sub as a cleanup callback:

  $r->pool->cleanup_register(sub { warn "running cleanup" });

One or more arguments using a cleanup code reference:

  $r->pool->cleanup_register(\&cleanup, $r);
  $r->pool->cleanup_register(\&cleanup, [$r, $foo]);
  sub cleanup {
      my @args = (@_ && ref $_[0] eq ARRAY) ? @{ +shift } : shift;
      my $r = shift @args;
      warn "cleaning up";
  }

No arguments, using a function name as a cleanup callback:

  $r->pool->cleanup_register('foo');

clear

Clear all memory in the pool and run all the registered cleanups. This also destroys all sub-pools.

  $pool->clear();
obj: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to clear

ret: no return value
since: 2.0.00

This method differs from destroy()|/C_destroy_ in that it is not freeing the previously allocated, but allows the pool to re-use it for the future memory allocations.

DESTROY

DESTROY is an alias to destroy|/C_destroy_. It's there so that custom APR::Pool objects will get properly cleaned up, when the pool object goes out of scope. If you ever want to destroy an APR::Pool object before it goes out of scope, use destroy|/C_destroy_.

since: 2.0.00

destroy

Destroy the pool.

  $pool->destroy();
obj: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to destroy

ret: no return value
since: 2.0.00

This method takes a similar action to clear()|/C_clear_ and then frees all the memory.

is_ancestor

Determine if pool a is an ancestor of pool b

  $ret = $pool_a->is_ancestor($pool_b);
obj: $pool_a ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to search

arg1: $pool_b ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to search for

ret: $ret ( integer )

True if $pool_a is an ancestor of $pool_b.

since: 2.0.00

For example create a sub-pool of a given pool and check that the pool is an ancestor of that sub-pool:

  use APR::Pool ();
  my $pp = $r->pool;
  my $sp = $pp->new();
  $pp->is_ancestor($sp) or die "Don't mess with genes!";

new

Create a new sub-pool

  my $pool_child = $pool_parent->new;
  my $pool_child = APR::Pool->new;
obj: $pool_parent ( APR::Pool object|docs::2.0::api::APR::Pool )

The parent pool.

If you don't have a parent pool to create the sub-pool from, you can use this object method as a class method, in which case the sub-pool will be created from the global pool:

  my $pool_child = APR::Pool->new;
ret: $pool_child ( APR::Pool object|docs::2.0::api::APR::Pool )

The child sub-pool

since: 2.0.00

parent_get

Get the parent pool

  $parent_pool = $child_pool->parent_get();
obj: $child_pool ( APR::Pool object|docs::2.0::api::APR::Pool )

the child pool

ret: $parent_pool ( APR::Pool object|docs::2.0::api::APR::Pool )

the parent pool. undef if there is no parent pool (which is the case for the top-most global pool).

since: 2.0.00

Example: Calculate how big is the pool's ancestry:

  use APR::Pool ();
  sub ancestry_count {
      my $child = shift;
      my $gen = 0;
      while (my $parent = $child->parent_get) {
          $gen++;
          $child = $parent;
      }
      return $gen;
  }

tag

Tag a pool (give it a name)

  $pool->tag($tag);
obj: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to tag

arg1: $tag ( string )

The tag (some unique string)

ret: no return value
since: 2.0.00

Each pool can be tagged with a unique label. This can prove useful when doing low level apr_pool C tracing (when apr is compiled with -DAPR_POOL_DEBUG). It allows you to grep(1) for the tag you have set, to single out the traces relevant to you.

Though there is no way to get read the tag value, since APR doesn't provide such an accessor method.

Unsupported API

APR::Pool also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

cleanup_for_exec

META: Autogenerated - needs to be reviewed/completed

Preparing for exec() --- close files, etc., but *don't* flush I/O buffers, *don't* wait for subprocesses, and *don't* free any memory. Run all of the child_cleanups, so that any unnecessary files are closed because we are about to exec a new program

ret: no return value
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::SockAddr - Perl API for APR socket address structure

  • Synopsis
  • Description
  • API
    • ip_get
    • port
  • Unsupported API
    • equal
  • See Also
  • Copyright
  • Authors

NAME

APR::SockAddr - Perl API for APR socket address structure

Synopsis

  use APR::SockAddr ();

  my $ip = $sock_addr->ip_get;
  my $port = $sock_addr->port;

Description

APR::SockAddr provides an access to a socket address structure fields.

Normally you'd get a socket address object, by calling:

  use Apache2::Connection ();
  my $remote_sock_addr = $c->remote_addr;
  my $local_sock_addr  = $c->remote_local;

API

APR::SockAddr provides the following functions and/or methods:

ip_get

Get the IP address of the socket

  $ip = $sock_addr->ip_get();
obj: $sock_addr ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
ret: $ip ( string )
since: 2.0.00

If you are familiar with how perl's Socket works:

  use Socket 'sockaddr_in';
  my ($serverport, $serverip) = sockaddr_in(getpeername($local_sock));
  my ($remoteport, $remoteip) = sockaddr_in(getpeername($remote_sock));

in apr-speak that'd be written as:

  use APR::SockAddr ();
  use Apache2::Connection ();
  my $serverport = $c->local_addr->port;
  my $serverip   = $c->local_addr->ip_get;
  my $remoteport = $c->remote_addr->port;
  my $remoteip   = $c->remote_addr->ip_get;

port

Get the IP address of the socket

  $port = $sock_addr->port();
obj: $sock_addr ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
ret: $port ( integer )
since: 2.0.00

Example: see ip_get()|/C_ip_get_

Unsupported API

APR::SockAddr also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

equal

META: Autogenerated - needs to be reviewed/completed

See if the IP addresses in two APR socket addresses are equivalent. Appropriate logic is present for comparing IPv4-mapped IPv6 addresses with IPv4 addresses.

  $ret = $addr1->equal($addr2);
obj: $addr1 ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

One of the APR socket addresses.

arg1: $addr2 ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

The other APR socket address.

ret: $ret ( integer )
since: subject to change

The return value will be non-zero if the addresses are equivalent.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Socket - Perl API for APR sockets

  • Synopsis
  • Description
  • API
    • opt_get
    • opt_set
    • poll
    • recv
    • send
    • timeout_get
    • timeout_set
  • Unsupported API
    • bind
    • close
    • connect
    • listen
    • recvfrom
    • sendto
  • See Also
  • Copyright
  • Authors

NAME

APR::Socket - Perl API for APR sockets

Synopsis

  use APR::Socket ();

  ### set the socket to the blocking mode if it isn't already
  ### and read in the loop and echo it back
  use APR::Const -compile => qw(SO_NONBLOCK);
  if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
      $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
  }
  # read from/write to the socket (w/o handling possible failures)
  my $wanted = 1024;
  while ($sock->recv(my $buff, $wanted)) {
      $sock->send($buff);
  }

  ### get/set IO timeout and try to read some data
  use APR::Const -compile => qw(TIMEUP);
  # timeout is in usecs!
  my $timeout = $sock->timeout_get();
  if ($timeout < 10_000_000) {
      $sock->timeout_set(20_000_000); # 20 secs
  }
  # now read, while handling timeouts
  my $wanted = 1024;
  my $buff;
  my $rlen = eval { $sock->recv($buff, $wanted) };
  if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {
      # timeout, do something, e.g.
      warn "timed out, will try again later";
  }
  else {
      warn "asked for $wanted bytes, read $rlen bytes\n";
      # do something with the data
  }

  # non-blocking io poll
  $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
  my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
  if ($rc == APR::Const::SUCCESS) {
      # read the data
  }
  else {
      # handle the condition
  }

Description

APR::Socket provides the Perl interface to APR sockets.

API

APR::Socket provides the following methods:

opt_get

Query socket options for the specified socket

  $val = $sock->opt_get($opt);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

the socket object to query

arg1: $opt ( APR::Const constant|docs::2.0::api::APR::Const/C__socket_ )

the socket option we would like to configure. Here are the available socket options.

ret: $val ( integer )

the currently set value for the socket option you've queried for

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

Examples can be found in the socket options constants section. For example setting the IO to the blocking mode.

opt_set

Setup socket options for the specified socket

  $sock->opt_set($opt, $val);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket object )

the socket object to set up.

arg1: $opt ( APR::Const|docs::2.0::api::APR::Const/C__socket_ constant )

the socket option we would like to configure. Here are the available socket options.

arg2: $val ( integer )

value for the option. Refer to the socket options section to learn about the expected values.

ret: no return value
excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

Examples can be found in the socket options constants section. For example setting the IO to the blocking mode.

poll

Poll the socket for events:

    $rc = $sock->poll($pool, $timeout, $events);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to poll

arg1: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

usually $c->pool|docs::2.0::api::Apache2::Connection/C_pool_.

arg2: $timeout ( integer )

The amount of time to wait (in milliseconds) for the specified events to occur.

arg3: $events ( APR::Const :poll constants|docs::2.0::api::APR::Const/C__poll_ )

The events for which to wait.

For example use APR::Const::POLLIN|docs::2.0::api::APR::Const/C_APR__Const__POLLIN_ to wait for incoming data to be available, APR::Const::POLLOUT|docs::2.0::api::APR::Const/C_APR__Const__POLLOUT_ to wait until it's possible to write data to the socket and APR::Const::POLLPRI|docs::2.0::api::APR::Const/C_APR__Const__POLLPRI_ to wait for priority data to become available.

ret: $rc ( APR::Const constant|docs::2.0::api::APR::Const )

If APR::Const::SUCCESS is received than the polling was successful. If not -- the error code is returned, which can be converted to the error string with help of APR::Error::strerror|docs::2.0::api::APR::Error/C_strerror_.

since: 2.0.00

For example poll a non-blocking socket up to 1 second when reading data from the client:

  use APR::Socket ();
  use APR::Connection ();
  use APR::Error ();

  use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);

  $sock->opt_set(APR::Const::SO_NONBLOCK => 1);

  my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
  if ($rc == APR::Const::SUCCESS) {
      # Data is waiting on the socket to be read.
      # $sock->recv(my $buf, BUFF_LEN)
  }
  elsif ($rc == APR::Const::TIMEUP) {
      # One second elapsed and still there is no data waiting to be
      # read. for example could try again.
  }
  else {
      die "poll error: " . APR::Error::strerror($rc);
  }

recv

Read incoming data from the socket

  $len = $sock->recv($buffer, $wanted);
obj: $sock ( APR::SockAddr object|docs::2.0::api::APR::SockAddr object )

The socket to read from

arg1: $buffer ( SCALAR )

The buffer to fill. All previous data will be lost.

arg2: $wanted ( int )

How many bytes to attempt to read.

ret: $len ( number )

How many bytes were actually read.

$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.

excpt: APR::Error|docs::2.0::api::APR::Error

If you get the '(11) Resource temporarily unavailable' error (exception APR::Const::EAGAIN|docs::2.0::api::APR::Const/C_APR__Const__EAGAIN_) (or another equivalent, which might be different on non-POSIX systems), then you didn't ensure that the socket is in a blocking IO mode before using it. Note that you should use APR::Status::is_EAGAIN|docs::2.0::api::APR::Status/C_is_EAGAIN_ to perform this check (since different error codes may be returned for the same event on different OSes). For example if the socket is set to the non-blocking mode and there is no data right away, you may get this exception thrown. So here is how to check for it and retry a few times after short delays:

  use APR::Status ();
  $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
  # ....
  my $tries = 0;
  my $buffer;
  RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
  if ($@)
      die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
      if ($tries++ < 3) {
          # sleep 250msec
          select undef, undef, undef, 0.25;
          goto RETRY;
      }
      else {
          # do something else
      }
  }
  warn "read $rlen bytes\n"

If timeout was set via timeout_set|/C_timeout_set_, you may need to catch the APR::Const::TIMEUP|docs::2.0::api::APR::Const/C_APR__Const__TIMEUP_ exception. For example:

  use APR::Const -compile => qw(TIMEUP);
  $sock->timeout_set(1_000_000); # 1 sec
  my $buffer;
  eval { $sock->recv($buffer, $wanted) };
  if ($@ && $@ == APR::Const::TIMEUP) {
      # timeout, do something, e.g.
  }

If not handled -- you may get the error '70007: The timeout specified has expired'.

Another error condition that may occur is the '(104) Connection reset by peer' error, which is up to your application logic to decide whether it's an error or not. This error usually happens when the client aborts the connection.

  use APR::Const -compile => qw(ECONNABORTED);
  my $buffer;
  eval { $sock->recv($buffer, $wanted) };
  if ($@ == APR::Const::ECONNABORTED) {
      # ignore it or deal with it
  }
since: 2.0.00

Here is the quick prototype example, which doesn't handle any errors (mod_perl will do that for you):

  use APR::Socket ();

  # set the socket to the blocking mode if it isn't already
  use APR::Const -compile => qw(SO_NONBLOCK);
  if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
      $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
  }
  # read from/write to the socket (w/o handling possible failures)
  my $wanted = 1024;
  while ($sock->recv(my $buffer, $wanted)) {
      $sock->send($buffer);
  }

If you want to handle errors by yourself, the loop may look like:

  use APR::Const -compile => qw(ECONNABORTED);
  # ...
  while (1) {
      my $buf;
      my $len = eval { $sock->recv($buf, $wanted) };
      if ($@) {
          # handle the error, e.g. to ignore aborted connections but
          # rethrow any other errors:
          if ($@ == APR::Const::ECONNABORTED) {
              # ignore
              last;
          }
          else {
              die $@; # retrow
          }
      }

      if ($len) {
          $sock->send($buffer);
      }
      else {
          last;
      }
  }

send

Write data to the socket

  $wlen = $sock->send($buf, $opt_len);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to write to

arg1: $buf ( scalar )

The data to send

opt arg2: $opt_len ( int )

There is no need to pass this argument, unless you want to send less data than contained in $buf.

ret: $wlen ( integer )

How many bytes were sent

since: 2.0.00

For examples see the recv|/C_recv_ item.

timeout_get

Get socket timeout settings

  $usecs = $sock->timeout_get();
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to set up.

ret: $usecs ( number)

Currently set timeout in microseconds (and also the blocking IO behavior). See (APR::timeout_set|/C__timeout_set_) for possible values and their meaning.

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

timeout_set

Setup socket timeout.

  $sock->timeout_set($usecs);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to set up.

arg1: $usecs ( number )

Value for the timeout in microseconds and also the blocking IO behavior.

The possible values are:

t > 0

send()|/C__send_ and recv()|/C__recv_) throw (APR::Const::TIMEUP|docs::2.0::api::APR::Const/C__APR__TIMEUP_ exception) if specified time elapses with no data sent or received.

Notice that the positive value is in micro seconds. So if you want to set the timeout for 5 seconds, the value should be: 5_000_000.

This mode sets the socket into a non-blocking IO mode.

t == 0

send()|/C__send_ and recv()|/C__recv_) calls never block.

t < 0

send()|/C__send_ and recv()|/C__recv_) calls block.

Usually just -1 is used for this case, but any negative value will do.

This mode sets the socket into a blocking IO mode.

ret: no return value
excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

Unsupported API

APR::Socket also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

bind

META: Autogenerated - needs to be reviewed/completed

Bind the socket to its associated port

  $ret = $sock->bind($sa);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to bind

arg1: $sa ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

The socket address to bind to

ret: $ret ( integer )
since: subject to change

This may be where we will find out if there is any other process using the selected port.

close

META: Autogenerated - needs to be reviewed/completed

Close a socket.

  $ret = $sock->close();
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to close

ret: $ret ( integer )
since: subject to change

connect

META: Autogenerated - needs to be reviewed/completed

Issue a connection request to a socket either on the same machine or a different one.

  $ret = $sock->connect($sa);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket we wish to use for our side of the connection

arg1: $sa ( APR::SockAddr object|docs::2.0::api::APR::SockAdrr )

The address of the machine we wish to connect to. If NULL, APR assumes that the sockaddr_in in the apr_socket is completely filled out.

ret: $ret ( integer )
since: subject to change

listen

META: Autogenerated - needs to be reviewed/completed

Listen to a bound socket for connections.

  $ret = $sock->listen($backlog);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to listen on

arg1: $backlog ( integer )

The number of outstanding connections allowed in the sockets listen queue. If this value is less than zero, the listen queue size is set to zero.

ret: $ret ( integer )
since: subject to change

recvfrom

META: Autogenerated - needs to be reviewed/completed

  $ret = $from->recvfrom($sock, $flags, $buf, $len);
obj: $from ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

The apr_sockaddr_t to fill in the recipient info

arg1: $sock ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )

The socket to use

arg2: $flags ( integer )

The flags to use

arg3: $buf ( integer )

The buffer to use

arg4: $len ( string )

The length of the available buffer

ret: $ret ( integer )
since: subject to change

sendto

META: Autogenerated - needs to be reviewed/completed

  $ret = $sock->sendto($where, $flags, $buf, $len);
obj: $sock ( APR::Socket object|docs::2.0::api::APR::Socket )

The socket to send from

arg1: $where ( APR::Socket object|docs::2.0::api::APR::Socket )

The apr_sockaddr_t describing where to send the data

arg2: $flags ( integer )

The flags to use

arg3: $buf ( scalar )

The data to send

arg4: $len ( string )

The length of the data to send

ret: $ret ( integer )
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Status - Perl Interface to the APR_STATUS_IS_* macros

  • Synopsis
  • Description
  • Functions
    • is_EACCES
    • is_EAGAIN
    • is_ENOENT
    • is_EOF
    • is_ECONNABORTED
    • is_ECONNRESET
    • is_TIMEUP
  • See Also
  • Copyright
  • Authors

NAME

APR::Status - Perl Interface to the APR_STATUS_IS_* macros

Synopsis

  use APR::Status ();
  eval { $obj->mp_method() };
  if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
      # APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
  }

Description

An interface to apr_errno.h composite error codes.

As discussed in the APR::Error|docs::2.0::api::APR::Error manpage, it is possible to handle APR/Apache/mod_perl exceptions in the following way:

  eval { $obj->mp_method() };
  if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
      warn "handled exception: $@";
  }

However, in cases where $some_code is an APR::Const constant, there may be more than one condition satisfying the intent of this exception. For this purpose the APR C library provides in apr_errno.h a series of macros, APR_STATUS_IS_*, which are the recommended way to check for such conditions. For example, the APR_STATUS_IS_EAGAIN macro is defined as

  #define APR_STATUS_IS_EAGAIN(s)         ((s) == APR_EAGAIN \
                  || (s) == APR_OS_START_SYSERR + ERROR_NO_DATA \
                  || (s) == APR_OS_START_SYSERR + SOCEWOULDBLOCK \
                  || (s) == APR_OS_START_SYSERR + ERROR_LOCK_VIOLATION)

The purpose of APR::Status is to provide functions corresponding to these macros.

Functions

is_EACCES

Check if the error is matching EACCES and its variants (corresponds to the APR_STATUS_IS_EACCES macro).

  $status = APR::Status::is_EACCES($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

An example of using is_EACCES is when reading the contents of a file where access may be forbidden:

  eval { $obj->slurp_filename(0) };
  if ($@) {
      return Apache2::Const::FORBIDDEN
          if ref $@ eq 'APR::Error' && APR::Status::is_EACCES($@);
      die $@;
   }

Due to possible variants in conditions matching EACCES, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::EACCES|docs::2.0::api::APR::Const/C_APR__Const__EACCES_ directly.

is_EAGAIN

Check if the error is matching EAGAIN and its variants (corresponds to the APR_STATUS_IS_EAGAIN macro).

  $status = APR::Status::is_EAGAIN($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

For example, here is how you may want to handle socket read exceptions and do retries:

  use APR::Status ();
  # ....
  my $tries = 0;
  my $buffer;
  RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
  if ($@ && ref($@) && APR::Status::is_EAGAIN($@)) {
      if ($tries++ < 3) {
          goto RETRY;
      }
      else {
          # do something else
      }
  }
  else {
      die "eval block has failed: $@";
  }

Notice that just checking against APR::Const::EAGAIN|docs::2.0::api::APR::Const/C_APR__Const__EAGAIN_ may work on some Unices, but then it will certainly break on win32. Thefore make sure to use this macro and not APR::Const::EAGAIN unless you know what you are doing.

is_ENOENT

Check if the error is matching ENOENT and its variants (corresponds to the APR_STATUS_IS_ENOENT macro).

  $status = APR::Status::is_ENOENT($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

An example of using is_ENOENT is when reading the contents of a file which may not exist:

  eval { $obj->slurp_filename(0) };
  if ($@) {
      return Apache2::Const::NOT_FOUND
          if ref $@ eq 'APR::Error' && APR::Status::is_ENOENT($@);
      die $@;
  }

Due to possible variants in conditions matching ENOENT, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::ENOENT|docs::2.0::api::APR::Const/C_APR__Const__ENOENT_ directly.

is_EOF

Check if the error is matching EOF and its variants (corresponds to the APR_STATUS_IS_EOF macro).

  $status = APR::Status::is_EOF($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

Due to possible variants in conditions matching EOF, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::EOF|docs::2.0::api::APR::Const/C_APR__Const__EOF_ directly.

is_ECONNABORTED

Check if the error is matching ECONNABORTED and its variants (corresponds to the APR_STATUS_IS_ECONNABORTED macro).

  $status = APR::Status::is_ECONNABORTED($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

Due to possible variants in conditions matching ECONNABORTED, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::ECONNABORTED|docs::2.0::api::APR::Const/C_APR__Const__ECONNABORTED_ directly.

is_ECONNRESET

Check if the error is matching ECONNRESET and its variants (corresponds to the APR_STATUS_IS_ECONNRESET macro).

  $status = APR::Status::is_ECONNRESET($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

Due to possible variants in conditions matching ECONNRESET, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::ECONNRESET|docs::2.0::api::APR::Const/C_APR__Const__ECONNRESET_ directly.

is_TIMEUP

Check if the error is matching TIMEUP and its variants (corresponds to the APR_STATUS_IS_TIMEUP macro).

  $status = APR::Status::is_TIMEUP($error_code);
arg1: $error_code (integer or APR::Error object|docs::2.0::api::APR::Error )

The error code or to check, normally $@ blessed into APR::Error object|docs::2.0::api::APR::Error.

ret: $status ( boolean )
since: 2.0.00

Due to possible variants in conditions matching TIMEUP, the use of this function is recommended for checking error codes against this value, rather than just using APR::Const::TIMEUP|docs::2.0::api::APR::Const/C_APR__Const__TIMEUP_ directly.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::String - Perl API for manipulating APR UUIDs

  • Synopsis
  • Description
  • API
    • format_size
  • See Also
  • Copyright
  • Authors

NAME

APR::String - Perl API for manipulating APR UUIDs

Synopsis

  use APR::String ();

  # 42_000 => " 41K",
  my $size_str = APR::String::format_size($size);

Description

APR::String provides strings manipulation API.

API

APR::String provides the following functions and/or methods:

format_size

  my $size_str = APR::String::format_size($size);
arg1: $size ( integer )
ret: $size_str

returns a formatted size string representation of a number. The size given in the string will be in units of bytes, kilobytes, or megabytes, depending on the size. The length of that string is always 4 chars long. For example:

    0               => "  0 ",
    42              => " 42 ",
    42_000          => " 41K",
    42_000_000      => " 40M",
since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Table - Perl API for manipulating APR opaque string-content tables

  • Synopsis
  • Description
  • API
    • add
    • clear
    • compress
    • copy
    • do
    • get
    • make
    • merge
    • overlap
    • overlay
    • set
    • unset
  • TIE Interface
    • EXISTS
    • CLEAR
    • STORE
    • DELETE
    • FETCH
  • See Also
  • Copyright
  • Authors

NAME

APR::Table - Perl API for manipulating APR opaque string-content tables

Synopsis

  use APR::Table ();

  $table = APR::Table::make($pool, $nelts);
  $table_copy = $table->copy($pool);

  $table->clear();

  $table->set($key => $val);
  $table->unset($key);
  $table->add($key, $val);

  $val = $table->get($key);
  @val = $table->get($key);

  $table->merge($key => $val);

  use APR::Const -compile qw(:table);
  $table_overlay = $table_base->overlay($table_overlay, $pool);
  $table_overlay->compress(APR::Const::OVERLAP_TABLES_MERGE);

  $table_a->overlap($table_b, APR::Const::OVERLAP_TABLES_SET);

  $table->do(sub {print "key $_[0], value $_[1]\n"}, @valid_keys);

  #Tied Interface
  $value = $table->{$key};
  $table->{$key} = $value;
  print "got it" if exists $table->{$key};

  foreach my $key (keys %{$table}) {
      print "$key = $table->{$key}\n";
  }

Description

APR::Table allows its users to manipulate opaque string-content tables.

On the C level the "opaque string-content" means: you can put in '\0'-terminated strings and whatever you put in your get out.

On the Perl level that means that we convert scalars into strings and store those strings. Any special information that was in the Perl scalar is not stored. So for example if a scalar was marked as utf8, tainted or tied, that information is not stored. When you get the data back as a Perl scalar you get only the string.

The table's structure is somewhat similar to the Perl's hash structure, but allows multiple values for the same key. An access to the records stored in the table always requires a key.

The key-value pairs are stored in the order they are added.

The keys are case-insensitive.

However as of the current implementation if more than value for the same key is requested, the whole table is lineary searched, which is very inefficient unless the table is very small.

APR::Table provides a TIE Interface.

See apr/include/apr_tables.h in ASF's apr project for low level details.

API

APR::Table provides the following functions and/or methods:

add

Add data to a table, regardless of whether there is another element with the same key.

  $table->add($key, $val);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to add to.

arg1: $key ( string )

The key to use.

arg2: $val ( string )

The value to add.

ret: no return value
since: 2.0.00

When adding data, this function makes a copy of both the key and the value.

clear

Delete all of the elements from a table.

  $table->clear();
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to clear.

ret: no return value
since: 2.0.00

compress

Eliminate redundant entries in a table by either overwriting or merging duplicates:

  $table->compress($flags);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to compress.

arg1: $flags (APR::Const constant|docs::2.0::api::APR::Const)
  APR::Const::OVERLAP_TABLES_MERGE -- to merge
  APR::Const::OVERLAP_TABLES_SET   -- to overwrite
ret: no return value
since: 2.0.00

Converts multi-valued keys in $table into single-valued keys. This function takes duplicate table entries and flattens them into a single entry. The flattening behavior is controlled by the (mandatory) $flags argument.

When $flags == APR::Const::OVERLAP_TABLES_SET, each key will be set to the last value seen for that key. For example, given key/value pairs 'foo => bar' and 'foo => baz', 'foo' would have a final value of 'baz' after compression -- the 'bar' value would be lost.

When $flags == APR::Const::OVERLAP_TABLES_MERGE, multiple values for the same key are flattened into a comma-separated list. Given key/value pairs 'foo => bar' and 'foo => baz', 'foo' would have a final value of 'bar, baz' after compression.

Access the constants via:

  use APR::Const -compile qw(:table);

or an explicit:

  use APR::Const -compile qw(OVERLAP_TABLES_SET OVERLAP_TABLES_MERGE);

compress() combined with overlay()|/C_overlay_ does the same thing as overlap()|/C_overlap_.

Examples:

  • APR::Const::OVERLAP_TABLES_SET

    Start with table $table:

      foo => "one"
  foo => "two"
  foo => "three"
  bar => "beer"

    which is done by:

      use APR::Const    -compile => ':table';
  my $table = APR::Table::make($r->pool, TABLE_SIZE);

  $table->set(bar => 'beer');
  $table->set(foo => 'one');
  $table->add(foo => 'two');
  $table->add(foo => 'three');

    Now compress it using APR::Const::OVERLAP_TABLES_SET:

      $table->compress(APR::Const::OVERLAP_TABLES_SET);

    Now table $table contains:

      foo => "three"
  bar => "beer"

    The value three for the key foo, that was added last, took over the other values.

  • APR::Const::OVERLAP_TABLES_MERGE

    Start with table $table:

      foo => "one"
  foo => "two"
  foo => "three"
  bar => "beer"

    as in the previous example, now compress it using APR::Const::OVERLAP_TABLES_MERGE:

      $table->compress(APR::Const::OVERLAP_TABLES_MERGE);

    Now table $table contains:

      foo => "one, two, three"
  bar => "beer"

    All the values for the same key were merged into one value.

copy

Create a new table and copy another table into it.

  $table_copy = $table->copy($p);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to copy.

arg1: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to allocate the new table out of.

ret: $table_copy ( APR::Table object|docs::2.0::api::APR::Table )

A copy of the table passed in.

since: 2.0.00

do

Iterate over all the elements of the table, invoking provided subroutine for each element. The subroutine gets passed as argument, a key-value pair.

  $table->do(sub {...}, @filter);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to operate on.

arg1: $sub ( CODE ref/string )

A subroutine reference or name to be called on each item in the table. The subroutine can abort the iteration by returning 0 and should always return 1 otherwise.

opt arg3: @filter ( ARRAY )

If passed, only keys matching one of the entries in f@filter will be processed.

ret: no return value
since: 2.0.00

Examples:

  • This filter simply prints out the key/value pairs and counts how many pairs did it see.

      use constant TABLE_SIZE => 20;
  our $filter_count;
  my $table = APR::Table::make($r->pool, TABLE_SIZE);

  # populate the table with ascii data
  for (1..TABLE_SIZE) {
      $table->set(chr($_+97), $_);
  }

  $filter_count = 0;
  $table->do("my_filter");
  print "Counted $filter_count elements";

  sub my_filter {
      my ($key, $value) = @_;
      warn "$key => $value\n";
      $filter_count++;
      return 1;
  }

    Notice that my_filter always returns 1, ensuring that do() will pass all the key/value pairs.

  • This filter is similar to the one from the previous example, but this time it decides to abort the filtering after seeing half of the table, by returning 0 when this happens.

      sub my_filter {
      my ($key, $value) = @_;
      $filter_count++;
      return $filter_count == int(TABLE_SIZE)/2 ? 0 : 1;
  }

get

Get the value(s) associated with a given key. After this call, the data is still in the table.

  $val = $table->get($key);
  @val = $table->get($key);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to search for the key.

arg1: $key ( string )

The key to search for.

ret: $val or @val

In the scalar context the first matching value returned (the oldest in the table, if there is more than one value). If nothing matches undef is returned.

In the list context the whole table is traversed and all matching values are returned. An empty list is returned if nothing matches.

since: 2.0.00

make

Make a new table.

  $table = APR::Table::make($p, $nelts);
obj: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to allocate the pool out of.

arg1: $nelts ( integer )

The number of elements in the initial table. At least 1 or more. If 0 is passed APR will still allocate 1.

ret: $table ( APR::Table object|docs::2.0::api::APR::Table )

The new table.

since: 2.0.00

This table can only store text data.

merge

Add data to a table by merging the value with data that has already been stored using ", " as a separator:

  $table->merge($key, $val);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to search for the data.

arg1: $key ( string )

The key to merge data for.

arg2: $val ( string )

The data to add.

ret: no return value
since: 2.0.00

If the key is not found, then this function acts like add()|/C_add_.

If there is more than one value for the same key, only the first (the oldest) value gets merged.

Examples:

  • Start with a pair:

      merge => "1"

    and merge "a" to the value:

      $table->set(  merge => '1');
  $table->merge(merge => 'a');
  $val = $table->get('merge');

    Result:

      $val == "1, a";

  • Start with a multivalued pair:

      merge => "1"
  merge => "2"

    and merge "a" to the first value;

      $table->set(  merge => '1');
  $table->add(  merge => '2');
  $table->merge(merge => 'a');
  @val = $table->get('merge');

    Result:

      $val[0] == "1, a";
  $val[1] == "2";

    Only the first value for the same key is affected.

  • Have no entry and merge "a";

      $table->merge(miss => 'a');
  $val = $table->get('miss');

    Result:

      $val == "a";

overlap

For each key/value pair in $table_b, add the data to $table_a. The definition of $flags explains how $flags define the overlapping method.

  $table_a->overlap($table_b, $flags);
obj: $table_a ( APR::Table object|docs::2.0::api::APR::Table )

The table to add the data to.

arg1: $table_b ( APR::Table object|docs::2.0::api::APR::Table )

The table to iterate over, adding its data to table $table_a

arg2: $flags ( integer )

How to add the table to table $table_a.

When $flags == APR::Const::OVERLAP_TABLES_SET, if another element already exists with the same key, this will over-write the old data.

When $flags == APR::Const::OVERLAP_TABLES_MERGE, the key/value pair from $table_b is added, regardless of whether there is another element with the same key in $table_a.

ret: no return value
since: 2.0.00

Access the constants via:

  use APR::Const -compile qw(:table);

or an explicit:

  use APR::Const -compile qw(OVERLAP_TABLES_SET OVERLAP_TABLES_MERGE);

This function is highly optimized, and uses less memory and CPU cycles than a function that just loops through table $table_b calling other functions.

Conceptually, overlap() does this:

  apr_array_header_t *barr = apr_table_elts(b);
  apr_table_entry_t *belt = (apr_table_entry_t *)barr-E<gt>elts;
  int i;

  for (i = 0; i < barr->nelts; ++i) {
      if (flags & APR_OVERLAP_TABLES_MERGE) {
          apr_table_mergen(a, belt[i].key, belt[i].val);
      }
      else {
          apr_table_setn(a, belt[i].key, belt[i].val);
      }
  }

Except that it is more efficient (less space and cpu-time) especially when $table_b has many elements.

Notice the assumptions on the keys and values in $table_b -- they must be in an ancestor of $table_a's pool. In practice $table_b and $table_a are usually from the same pool.

Examples:

  • APR::Const::OVERLAP_TABLES_SET

    Start with table $base:

      foo => "one"
  foo => "two"
  bar => "beer"

    and table $add:

      foo => "three"

    which is done by:

      use APR::Const    -compile => ':table';
  my $base = APR::Table::make($r->pool, TABLE_SIZE);
  my $add  = APR::Table::make($r->pool, TABLE_SIZE);

  $base->set(bar => 'beer');
  $base->set(foo => 'one');
  $base->add(foo => 'two');

  $add->set(foo => 'three');

    Now overlap using APR::Const::OVERLAP_TABLES_SET:

      $base->overlap($add, APR::Const::OVERLAP_TABLES_SET);

    Now table $add is unmodified and table $base contains:

      foo => "three"
  bar => "beer"

    The value from table add has overwritten all previous values for the same key both had (foo). This is the same as doing overlay()|/C_overlay_ followed by compress()|/C_compress_ with APR::Const::OVERLAP_TABLES_SET.

  • APR::Const::OVERLAP_TABLES_MERGE

    Start with table $base:

      foo => "one"
  foo => "two"

    and table $add:

      foo => "three"
  bar => "beer"

    which is done by:

      use APR::Const    -compile => ':table';
  my $base = APR::Table::make($r->pool, TABLE_SIZE);
  my $add  = APR::Table::make($r->pool, TABLE_SIZE);

  $base->set(foo => 'one');
  $base->add(foo => 'two');

  $add->set(foo => 'three');
  $add->set(bar => 'beer');

    Now overlap using APR::Const::OVERLAP_TABLES_MERGE:

      $base->overlap($add, APR::Const::OVERLAP_TABLES_MERGE);

    Now table $add is unmodified and table $base contains:

      foo => "one, two, three"
  bar => "beer"

    Values from both tables for the same key were merged into one value. This is the same as doing overlay()|/C_overlay_ followed by compress()|/C_compress_ with APR::Const::OVERLAP_TABLES_MERGE.

overlay

Merge two tables into one new table. The resulting table may have more than one value for the same key.

  $table = $table_base->overlay($table_overlay, $p);
obj: $table_base ( APR::Table object|docs::2.0::api::APR::Table )

The table to add at the end of the new table.

arg1: $table_overlay ( APR::Table object|docs::2.0::api::APR::Table )

The first table to put in the new table.

arg2: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to use for the new table.

ret: $table ( APR::Table object|docs::2.0::api::APR::Table )

A new table containing all of the data from the two passed in.

since: 2.0.00

Examples:

  • Start with table $base:

      foo => "one"
  foo => "two"
  bar => "beer"

    and table $add:

      foo => "three"

    which is done by:

      use APR::Const    -compile => ':table';
  my $base = APR::Table::make($r->pool, TABLE_SIZE);
  my $add  = APR::Table::make($r->pool, TABLE_SIZE);

  $base->set(bar => 'beer');
  $base->set(foo => 'one');
  $base->add(foo => 'two');

  $add->set(foo => 'three');

    Now overlay using APR::Const::OVERLAP_TABLES_SET:

      my $overlay = $base->overlay($add, APR::Const::OVERLAP_TABLES_SET);

    That resulted in a new table $overlay (tables add and $base are unmodified) which contains:

      foo => "one"
  foo => "two"
  foo => "three"
  bar => "beer"

set

Add a key/value pair to a table, if another element already exists with the same key, this will over-write the old data.

  $table->set($key, $val);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to add the data to.

arg1: $key ( string )

The key to use.

arg2: $val ( string )

The value to add.

ret: no return value
since: 2.0.00

When adding data, this function makes a copy of both the key and the value.

unset

Remove data from the table.

  $table->unset($key);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )

The table to remove data from.

arg1: $key ( string )

The key of the data being removed.

ret: no return value
since: 2.0.00

TIE Interface

APR::Table also implements a tied interface, so you can work with the $table object as a hash reference.

The following tied-hash function are supported: FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY, NEXTKEY and DESTROY.

Note regarding the use of values(). APR::Table can hold more than one key-value pair sharing the same key, so when using a table through the tied interface, the first entry found with the right key will be used, completely disregarding possible other entries with the same key. With Perl 5.8.0 and higher values() will correctly list values the corresponding to the list generated by keys(). That doesn't work with Perl 5.6. Therefore to portably iterate over the key-value pairs, use each() (which fully supports multivalued keys), or APR::Table::do.

EXISTS

  $ret = $table->EXISTS($key);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )
arg1: $key ( string )
ret: $ret ( integer )

true or false

since: 2.0.00

CLEAR

  $table->CLEAR();
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )
ret: no return value
since: 2.0.00

STORE

  $table->STORE($key, $val);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )
arg1: $key ( string )
arg2: $val ( string )
ret: no return value
since: 2.0.00

DELETE

  $table->DELETE($key);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )
arg1: $key ( string )
ret: no return value
since: 2.0.00

FETCH

  $ret = $table->FETCH($key);
obj: $table ( APR::Table object|docs::2.0::api::APR::Table )
arg1: $key ( string )
ret: $ret ( string )
since: 2.0.00

When iterating through the table's entries with each(), FETCH will return the current value of a multivalued key. For example:

  $table->add("a" => 1);
  $table->add("b" => 2);
  $table->add("a" => 3);

  ($k, $v) = each %$table; # (a, 1)
  print $table->{a};       # prints 1

  ($k, $v) = each %$table; # (b, 2)
  print $table->{a};       # prints 1

  ($k, $v) = each %$table; # (a, 3)
  print $table->{a};       # prints 3 !!!

  ($k, $v) = each %$table; # (undef, undef)
  print $table->{a};       # prints 1

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::ThreadMutex - Perl API for APR thread mutexES

  • Synopsis
  • Description
  • API
  • Unsupported API
    • DESTROY
    • lock
    • new
    • pool_get
    • trylock
    • unlock
  • See Also
  • Copyright
  • Authors

NAME

APR::ThreadMutex - Perl API for APR thread mutexES

Synopsis

  use APR::ThreadMutex ();

  my $mutex = APR::ThreadMutex->new($r->pool);
  $mutex->lock;
  $mutex->unlock;
  $mutex->trylock;

Description

APR::ThreadMutex interfaces APR thread mutexes.

API

APR::ThreadMutex provides the following functions and/or methods:

Unsupported API

APR::ThreadMutex also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

DESTROY

META: Autogenerated - needs to be reviewed/completed

Destroy the mutex and free the memory associated with the lock.

  $mutex->DESTROY();
obj: $mutex ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )

the mutex to destroy.

ret: no return value
since: subject to change

lock

META: Autogenerated - needs to be reviewed/completed

Acquire the lock for the given mutex. If the mutex is already locked, the current thread will be put to sleep until the lock becomes available.

  $ret = $mutex->lock();
obj: $mutex ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )

the mutex on which to acquire the lock.

ret: $ret ( integer )
since: subject to change

new

Create a new mutex

  my $mutex = APR::ThreadMutex->new($p);
obj: APR::ThreadMutex ( class name )
arg1: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
ret: $mutex ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )
since: subject to change

pool_get

META: Autogenerated - needs to be reviewed/completed

META: should probably be renamed to pool(), like all other pool accessors

Get the pool used by this thread_mutex.

  $ret = $obj->pool_get();
obj: $obj ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )
ret: $ret ( APR::Pool object|docs::2.0::api::APR::Pool )

apr_pool_t the pool

since: subject to change

trylock

META: Autogenerated - needs to be reviewed/completed

Attempt to acquire the lock for the given mutex. If the mutex has already been acquired, the call returns immediately with APR_EBUSY. Note: it is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was APR_EBUSY, for portability reasons.

  $ret = $mutex->trylock();
obj: $mutex ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )

the mutex on which to attempt the lock acquiring.

ret: $ret (integer)
since: subject to change

unlock

META: Autogenerated - needs to be reviewed/completed

Release the lock for the given mutex.

  $ret = $mutex->unlock();
obj: $mutex ( APR::ThreadMutex object|docs::2.0::api::APR::ThreadMutex )

the mutex from which to release the lock.

ret: $ret ( integer )
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::URI - Perl API for URI manipulations

  • Synopsis
  • Description
  • API
    • fragment
    • hostinfo
    • hostname
    • password
    • parse
    • path
    • rpath
    • port
    • port_of_scheme
    • query
    • scheme
    • user
    • unparse
  • See Also
  • Copyright
  • Authors

NAME

APR::URI - Perl API for URI manipulations

Synopsis

  use APR::URI ();

  my $url = 'http://user:pass@example.com:80/foo?bar#item5';

  # parse and break the url into components
  my $parsed = APR::URI->parse($r->pool, $url);
  print $parsed->scheme;
  print $parsed->user;
  print $parsed->password;
  print $parsed->hostname;
  print $parsed->port;
  print $parsed->path;
  print $parsed->rpath;
  print $parsed->query;
  print $parsed->fragment;

  # reconstruct the url, after changing some components and completely
  # removing other
  $parsed->scheme($new_scheme);
  $parsed->user(undef);
  $parsed->password(undef);
  $parsed->hostname($new_hostname);
  $parsed->port($new_port);
  $parsed->path($new_path);
  $parsed->query(undef);
  $parsed->fragment(undef);
  print $parsed->unparse;

  # get the password field too (by default it's not revealed)
  use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD);
  print $parsed->unparse(APR::Const::URI_UNP_REVEALPASSWORD);

  # what the default port for the ftp protocol?
  my $ftp_port = APR::URI::port_of_scheme("ftp");

Description

APR::URI allows you to parse URI strings, manipulate each of the URI elements and deparse them back into URIs.

All APR::URI object accessors accept a string or an undef value as an argument. Same goes for return value. It's important to distinguish between an empty string and undef. For example let's say your code was:

  my $uri = 'http://example.com/foo?bar#item5';
  my $parsed = APR::URI->parse($r->pool, $uri);

Now you no longer want to the query and fragment components in the final url. If you do:

  $parsed->fragment('');
  $parsed->query('');

followed by:

  my $new_uri = parsed->unparse;

the resulting URI will be:

  http://example.com/foo?#

which is probably not something that you've expected. In order to get rid of the separators, you must completely unset the fields you don't want to see. So, if you do:

  $parsed->fragment(undef);
  $parsed->query(undef);

followed by:

  my $new_uri = parsed->unparse;

the resulting URI will be:

   http://example.com/foo

As mentioned earlier the same goes for return values, so continuing this example:

  my $new_fragment = $parsed->fragment();
  my $new_query    = $parsed->query();

Both values now contain undef, therefore you must be careful when using the return values, when you use them, as you may get warnings.

Also make sure you read through the unparse() section|/C_unparse_ as various optional flags affect how the deparsed URI is rendered.

API

APR::URI provides the following functions and/or methods:

fragment

Get/set trailing "#fragment" string

  $oldval = $parsed->fragment($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

hostinfo

Get/set combined [user[:password]@]host[:port]

  $oldval = $parsed->hostinfo($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

The hostinfo value is set automatically when parse()|/C_parse_ is called.

It's not updated if any of the individual fields is modified.

It's not used when unparse()|/C_unparse_ is called.

hostname

Get/set hostname

  $oldval = $parsed->hostname($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

password

Get/set password (as in http://user:password@host:port/)

  $oldval = $parsed->password($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

parse

Parse the URI string into URI components

  $parsed = APR::URI->parse($pool, $uri);
obj: $parsed ( APR::URI object or class|docs::2.0::api::APR::URI )
arg1: $pool ( string ) ( APR::Pool object|docs::2.0::api::APR::Pool )
arg2: $uri ( string )

The URI to parse

ret: $parsed ( APR::URI object or class|docs::2.0::api::APR::URI )

The parsed URI object

since: 2.0.00

After parsing, if a component existed but was an empty string (e.g. empty query http://hostname/path?) -- the corresponding accessor will return an empty string. If a component didn't exist (e.g. no query part http://hostname/path) -- the corresponding accessor will return undef.

path

Get/set the request path

  $oldval = $parsed->path($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )

"/" if only scheme://host

since: 2.0.00

rpath

Gets the path minus the path_info|docs::2.0::api::Apache2::RequestRec/C_path_info_

  $rpath =  $parsed->rpath();
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )

The path minus the path_info

since: 2.0.00

port

Get/set port number

  $oldval = $parsed->port($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( number or string or undef )
ret: $oldval ( string or undef )

If the port component didn't appear in the parsed URI, APR internally calls port_of_scheme()|/C_port_of_scheme_ to find out the port number for the given scheme()|/C_scheme_.

since: 2.0.00

port_of_scheme

Return the default port for a given scheme. The recognized schemes are http, ftp, https, gopher, wais, nntp, snews and prospero.

  $port = APR::URI::port_of_scheme($scheme);
obj: $scheme ( string )

The scheme string

ret: $port (integer)

The default port for this scheme

since: 2.0.00

query

Get/set the query string (the part starting after '?' and all the way till the end or the '#fragment' part if the latter exists).

  $oldval = $parsed->query($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

scheme

Get/set the protocol scheme ("http", "ftp", ...)

  $oldval = $parsed->scheme($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

user

Get/set user name (as in http://user:password@host:port/)

  $oldval = $parsed->user($newval);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $newval ( string or undef )
ret: $oldval ( string or undef )
since: 2.0.00

unparse

Unparse the URI components back into a URI string

  $new_uri = $parsed->unparse();
  $new_uri = $parsed->unparse($flags);
obj: $parsed ( APR::URI object|docs::2.0::api::APR::URI )
opt arg1: $flags ( the APR::Const :uri constants )

By default the constant APR::Const::URI_UNP_OMITPASSWORD is passed.

If you need to pass more than one flag use unary |, e.g.:

  $flags = APR::Const::URI_UNP_OMITUSER|APR::Const::URI_UNP_OMITPASSWORD;

The valid flags constants are listed next

ret: $new_uri ( string )
since: 2.0.00

Valid flags constants:

To import all URI constants you could do:

  use APR::Const -compile => qw(:uri);

but there is a significant amount of them, most irrelevant to this method. Therefore you probably don't want to do that. Instead specify explicitly the ones that you need. All the relevant to this method constants start with APR::URI_UNP_.

And the available constants are:

APR::Const::URI_UNP_OMITSITEPART

Don't show scheme|/C_scheme_, user|/C_user_, password|/C_password_, hostname|/C_hostname_ and port|/C_port_ components (i.e. if you want only the relative URI)

APR::Const::URI_UNP_OMITUSER

Hide the user|/C_user_ component

APR::Const::URI_UNP_OMITPASSWORD

Hide the password|/C_password_ component (the default)

APR::Const::URI_UNP_REVEALPASSWORD

Reveal the password|/C_password_ component

APR::Const::URI_UNP_OMITPATHINFO

Don't show path|/C_path_, query|/C_query_ and fragment|/C_fragment_ components

APR::Const::URI_UNP_OMITQUERY

Don't show query|/C_query_ and fragment|/C_fragment_ components

Notice that some flags overlap.

If the optional $flags argument is passed and contains no APR::Const::URI_UNP_OMITPASSWORD and no APR::Const::URI_UNP_REVEALPASSWORD -- the password|/C_password_ part will be rendered as a literal "XXXXXXXX" string.

If the port|/C_port_ number matches the port_of_scheme()|/C_port_of_scheme_, the unparsed URI won't include it and there is no flag to force that port|/C_port_ to appear. If the port|/C_port_ number is non-standard it will show up in the unparsed string.

Examples:

Starting with the parsed URL:

  use APR::URI ();
  my $url = 'http://user:pass@example.com:80/foo?bar#item5';
  my $parsed = APR::URI->parse($r->pool, $url);

deparse it back including and excluding parts, using different values for the optional flags argument:

  • Show all but the password|/C_password_ fields:

      print $parsed->unparse;

    Prints:

      http://user@example.com/foo?bar#item5

    Notice that the port|/C_port_ field is gone too, since it was a default port|/C_port_of_scheme_ for scheme|/C_scheme_ http://.

  • Include the password|/C_password_ field (by default it's not revealed)

      use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD);
  print $parsed->unparse(APR::Const::URI_UNP_REVEALPASSWORD);

    Prints:

      http://user:pass@example.com/foo?bar#item5

  • Show all fields but the last three, path|/C_path_, query|/C_query_ and fragment|/C_fragment_:

      use APR::Const -compile => qw(URI_UNP_REVEALPASSWORD
                                APR::Const::URI_UNP_OMITPATHINFO);
  print $parsed->unparse(
      APR::Const::URI_UNP_REVEALPASSWORD|URI_UNP_OMITPATHINFO);

    Prints:

      http://user:pass@example.com

See Also

Apache2::URI|docs::2.0::api::Apache2::URI, mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::UUID - Perl API for manipulating APR UUIDs

  • Synopsis
  • Description
  • API
    • format
    • new
    • DESTROY
    • parse
  • See Also
  • Copyright
  • Authors

NAME

APR::UUID - Perl API for manipulating APR UUIDs

Synopsis

  use APR::UUID ();

  # get a random UUID and format it as a string
  my $uuid = APR::UUID->new->format;
  # $uuid = e.g. 'd48889bb-d11d-b211-8567-ec81968c93c6';

  # same as the object returned by APR::UUID->new
  my $uuid_parsed = APR::UUID->parse($uuid);

Description

APR::UUID is used to get and manipulate random UUIDs.

It allows you to create|/C_new_ random UUIDs, which when format|/C_format_ted returns a string like:

  'd48889bb-d11d-b211-8567-ec81968c93c6';

which can be parsed back into the APR::UUID object with parse()|/C_parse_.

API

APR::UUID provides the following functions and/or methods:

format

Convert an APR::UUID object|docs::2.0::api::APR::UUID object into a string presentation:

  my $uuid_str = $uuid->format;
obj: $uuid ( APR::UUID object|docs::2.0::api::APR::UUID )
ret: $uuid_str

returns a string representation of the object (.e.g 'd48889bb-d11d-b211-8567-ec81968c93c6').

since: 2.0.00

new

Create a APR::UUID object|docs::2.0::api::APR::UUID using the random engine:

  my $uuid = APR::UUID->new;
class: APR::UUID ( APR::UUID class|docs::2.0::api::APR::UUID )
ret: $uuid ( APR::UUID object|docs::2.0::api::APR::UUID )
since: 2.0.00

DESTROY

  $uuid->DESTROY;
obj: APR::UUID ( APR::UUID object|docs::2.0::api::APR::UUID )
ret: no return value
since: 2.0.00

Do not call this method, it's designed to be only called by Perl when the variable goes out of scope. If you call it yourself you will get a segfault when perl will call DESTROY on its own.

parse

Convert a UUID string into an APR::UUID object|docs::2.0::api::APR::UUID object:

  $uuid = APR::UUID->parse($uuid_str)
arg1: $uuid_str (string)

UUID string (.e.g 'd48889bb-d11d-b211-8567-ec81968c93c6')

ret: $uuid ( APR::UUID object|docs::2.0::api::APR::UUID )

The new object.

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


APR::Util - Perl API for Various APR Utilities

  • Synopsis
  • Description
  • API
    • password_validate
  • Unsupported API
    • filepath_name_get
    • password_get
  • See Also
  • Copyright
  • Authors

NAME

APR::Util - Perl API for Various APR Utilities

Synopsis

  use APR::Util ();

  $ok = password_validate($passwd, $hash);

Description

Various APR utilities that don't fit into any other group.

API

APR::Util provides the following functions and/or methods:

password_validate

Validate an encrypted password hash against a plain text password (with lots of restrictions and peculiarities).

  $ok = password_validate($passwd, $hash);
arg1: $passwd ( string )

Plain text password string

arg2: $hash ( string )

Encrypted or encoded hash. See below for supported hash formats.

ret: $ok ( boolean )

The password either matches or not.

since: 2.0.00

The function handles the output of the following functions (it knows to tell md5 and sha1 from the others, since they are have a special pattern recognized by apr):

  • md5

    generated by apr_md5_encode() (for which at the moment we have no perl glue, ask if you need it).

  • sha1

    generated by apr_sha1_base64() (for which at the moment we have no perl glue, ask if you need it).

    and it's available only since Apache 2.0.50

  • crypt

    On all but the following platforms: MSWin32, beos and NetWare. Therefore you probably don't want to use that feature, unless you know that your code will never end up running on those listed platforms.

    Moreover on these three platforms if that function sees that the hash is not of md5 and sha1 formats, it'll do a clear to clear text matching, always returning success, no matter what the hashed value is.

Warning: double check that you understand what this function does and does not before using it.

Unsupported API

APR::Socket also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

filepath_name_get

META: Autogenerated - needs to be reviewed/completed

[We have File::Spec and File::Basename for this purpose, I can't see why this api is needed]

return the final element of the pathname

  $ret = filepath_name_get($pathname);
arg1: $pathname ( string )

The path to get the final element of

ret: $ret ( string )

the final element of the path

For example:

  "/foo/bar/gum"    => "gum"
  "/foo/bar/gum/"   => ""
  "gum"             => "gum"
  "bs\\path\\stuff" => "stuff"
since: subject to change

password_get

META: Autogenerated - needs to be reviewed/completed

Display a prompt and read in the password from stdin.

  $ret = password_get($prompt, $pwbuf, $bufsize);
arg1: $prompt ( string )

The prompt to display

arg2: $pwbuf ( string )

Buffer to store the password

arg3: $bufsize (number)

The length of the password buffer.

ret: $ret (integer)
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


ActivePerl - ActiveState's quality-assured binary build of Perl

    • The ActivePerl:: module
  • SEE ALSO

NAME

ActivePerl - ActiveState's quality-assured binary build of Perl

SYNOPSIS

  use ActivePerl;
  print "$ActivePerl::VERSION\n";

DESCRIPTION

ActivePerl is ActiveState's quality-assured binary build of Perl, available for AIX, HP-UX, Linux, Mac OS X, Solaris and Windows. ActivePerl includes:

  • The binary core distribution of perl. See the perl manpage for details.

  • A set of useful additional CPAN modules "out of the box".

  • The Perl Package Manager, for quick and easy install of additional Perl extension modules. See the ppm manpage for details.

  • Complete documentation in HTML format. This is found in the html sub directory where ActivePerl was installed.

The release notes for this version of ActivePerl is available in the activeperl-release manpage. A list of changes beween builds of ActivePerl is found in the activeperl-changes manpage.

The ActivePerl:: module

The ActivePerl module provide version information about ActivePerl. The module is built in so most of its variables and functions are available without having to require the module. The module was introduced in ActivePerl 813.1.

The following functions are available:

ActivePerl->VERSION
ActivePerl->VERSION( $VERSION )

This method returns the current version of ActivePerl. It is a number like 813.01 or 815. With argument croak if the current version is less than the given number.

This method is inherited from Perl's UNIVERSAL class, and will usually be invoked indirectly by use, for instance:

    use ActivePerl 815;

This statement ensures that the scripts runs under ActivePerl 815 or better. If this perl is not ActivePerl or is older than 815 then this statement would croak.

The version number returned is picked up from the $ActivePerl::VERSION variable. For conditional code it is usually better to test against this variable directly:

   if (($ActivePerl::VERSION || 0) >= 815) {
       ...
   }

The || 0 ensures that this code does not produce a warning if running on ActivePerl 813 or older, or running on standard perl.

ActivePerl::PRODUCT

This constant function returns "ActivePerl" for the free version and "ActivePerlEE" for the Enterprise Edition product.

ActivePerl::BUILD

The value returned is the same as found in $ActivePerl::VERSION, but the subversion number will not be padded with 0. It means that this value is suitable for printing, but unsafe for numeric comparisons.

This returns the same value as Win32::BuildNumber(), but this function is only avalable on the Windows builds of ActivePerl.

ActivePerl::perl_version

Returns a full version number that also include the version of perl this ActivePerl release is based on. It returns a string like "5.8.7.815" or "5.8.7.813.1".

This function is not directly built in and will only be avalable after 'require ActivePerl' has executed.

SEE ALSO

the activeperl-release manpage, the activeperl-changes manpage, the perl manpage


ActivePerl::Config - Override the ActivePerl configuration

    • Windows overrides
    • Mac OS X overrides
    • HP-UX and Solaris overrides
  • ENVIRONMENT
  • SEE ALSO

NAME

ActivePerl::Config - Override the ActivePerl configuration

SYNOPSIS

  use Config qw(%Config);

DESCRIPTION

The standard Config module provides the %Config hash containing information about how this perl was built. These configuration values are used by modules and programs with the assumption that they still apply for the system where perl is deployed. This assumption does not always hold. The ExtUtils::MakeMaker module will for instance assume that it can use the compiler $Config{cc} for building new extensions, but another compiler might be the only one available.

The ActivePerl::Config module provides a solution for this. It overrides the values of %Config to better match the system where perl currently runs. For example, on Windows allows you to build extensions with the free compiler gcc (see http://www.mingw.org/) even though ActivePerl for Windows itself is built with the commercial Microsoft Visual Studio 6 compiler.

The ActivePerl::Config module is not used directly. It is automatically loaded by Config if available and works behind the scenes, overriding the values that are found in the %Config hash. The overriden values from ActivePerl::Config will also show when perl -V:foo is invoked from the command line.

Windows overrides

For ActivePerl on Windows the following %Config overrides are provided:

$Config{make}

This will be nmake by default, but if no nmake program can be found and other compatible make programs are found, then this value will reflect that. Currently dmake is the only other make implementation that is compatible enough to build perl extensions.

$Config{cc}, $Config{ccflags},...

The value of $Config{cc} will be cl by default, but if no cl program can be found and gcc is found, then this value is gcc and other values related to the compiler environment is adjusted accordingly.

Mac OS X overrides

For ActivePerl on Mac OS X the compilation flags (like $Config{ccflags}) are adjusted to make it possible to compile extentions even on 10.3 systems and systems that don't have the SDK for generating Universal binaries installed.

HP-UX and Solaris overrides

For ActivePerl on HP-UX and Solaris the following %Config overrides are provided:

$Config{make}

This will be make by default, but if make can't be found via the PATH, then it's set to /usr/ccs/bin/make if that one is available.

$Config{cc}, $Config{ccflags},...

The value of $Config{cc} will be cc by default and the other compiler environment values are set up for compilation with the HP-UX ANSI C compiler or the Sun Forte/WorkShop compiler respectively. If cc can't be found via the PATH and gcc is found, then $Config{cc} is set to gcc and other values related to the compiler environment is adjusted accordingly.

ENVIRONMENT

The following environment variables can influence the operation of the ActivePerl::Config module:

ACTIVEPERL_CONFIG_DISABLE

If set to a TRUE value (e.g. "1"), prevent ActivePerl::Config from overriding any %Config value; the only values seen in %Config would be those determined at perl build time. Another way to disable ActivePerl::Config permanently is to remove it using ppm (ppm remove ActivePerl-Config)

ACTIVEPERL_CONFIG_SILENT

If set to a TRUE value (e.g. "1"), suppress warnings on STDERR when new compilation environments are set up. This happens when a supported compiler is detected that is different from the one that perl was originally built with.

ACTIVEPERL_CONFIG_FOO

Override the $Config{foo} value. For example if the ACTIVEPERL_CONFIG_MAKE environment variable has the value dmake, then so would $Config{make}.

If the ACTIVEPERL_CONFIG_DISABLE variable is set, all other ACTIVEPERL_CONFIG_FOO variables are ignored.

SEE ALSO

the Config manpage


ActivePerl::DocTools::Pod - Functions to process POD for ActivePerl

  • SEE ALSO
  • BUGS

NAME

ActivePerl::DocTools::Pod - Functions to process POD for ActivePerl

DESCRIPTION

The following functions are provided:

pod2html( %args )

Convert a POD document into an HTML document. This is a wrapper for the pod2html() function of Pod::Html that also modify the document produced with various ActivePerl enhancements.

The following arguments are recognized:

infile => $filename

The name of the POD file you want to convert. This argument is mandatory.

outfile => $filename

The name of the HTML file you want as output. This argument is mandatory.

depth => $int

How many directory levels down from the root of the HTML tree will the generated file eventually be installed. The root of the HTML tree is normally found at $Config{installhtmldir}, which is normally "$Config{prefix}/html".

The default is 0.

podroot => $dirname

Specify the base directory for finding library pods. The default is $Config{prefix}.

podpath => [$dir1, $dir2,...]

What subdirectories of the podroot should be searched for POD files in order to discover targets for links from the generated HTML file. The specified directories must all exist.

The links are generated with the assumption that the discovered POD files are converted into HTML files with and .html extension and placed into an hierarchy (the HTML tree rooted at $Config{installhtmldir}) using the same layout as the one found under podroot.

Instead of passing an array reference, the directories can alternatively be specified as a single string of directory names separated by :.

The default is [qw(bin lib)].

index => $bool

Should a table on contents be created at the start of the HTML document. By default no table of contents is generated.

pod2html_remove_cache_files( )

The pod2html() will create cache files with names starting with pod2htm in the current directory. These cache files allow pod2html to save link state between runs. Call this function to clean up these cache files.

SEE ALSO

the Pod::Html manpage

BUGS

none.


ActivePerl::PPM::Client - Client class

  • BUGS

NAME

ActivePerl::PPM::Client - Client class

SYNOPSIS

  my $ppm = ActivePerl::PPM::Client->new;

DESCRIPTION

The ActivePerl::PPM::Client object ties together a set of install areas and repositories and allow the installed packages to be managed. The install areas are deducted from the values of @INC when the object is constructed.

The following methods are provided:

$client = ActivePerl::PPM::Client->new
$client = ActivePerl::PPM::Client->new( $home_dir )

The constructor creates a new client based on the configuration found in $home_dir which defaults to $ENV{HOME}/.ActivePerl directory of the current user. If no such directory is found it is created.

$client->arch

A string that identifies the architecture for the current perl. This must match the ARCHITECTURE/NAME attribute of PPDs for them to match.

$client->area( $name )

Returns an object representing the given named install area. The method will croak if no install area with the given $name is known. The perl and site areas will always be available. See the ActivePerl::PPM::InstallArea manpage for methods available on the returned object.

$client->areas

Return list of available install area names. The list is ordered to match the corresponding entries in @INC.

$client->default_install_area

Return the name of the area where installations should normally go. Might return undef if there is no appropriate default.

$value = $client->config_get( $key )
($value1, $value2, ...) = $client->config_get( $key1, $key2, ...)

Read back one or more configuration values previosly saved.

($key, $value, ...) = $client->config_list
($key, $value, ...) = $client->config_list( $glob_pattern )

Return all key/value pairs where $key match the given $glob_pattern. If $glob_pattern is missing return all key/value pairs.

$client->config_save( $key => $value )
$client->config_save( %pairs )

Will persistently store the given key/value pairs. The values can be extracted again with $client->config_get().

$client->repo( $repo_id )

Returns a reference to a hash describing the repo with the given identifier. The interesting fields of this hash are:

name

The full (user friendly) name of the repository. Can be modified by $repo->repo_set_name().

enabled

A boolean that indicated if the repo is enabled or not. Can be modified by $repo->repo_enable().

pkgs

The number of packages provided by this repository.

packlist_uri

The URI that the PPM client will monitor for changes to the repository. This URI can denote a packlist.xml, packlist.lst file or an HTML document with links to PPD files (typically a server generated directory listing). The URI can use any scheme that LWP supports and can embed a username and password for HTTP using this syntax: http://user:pass@ppm.example.com/.

packlist_last_status

The HTTP status code reported last time the PPM client tried to access packlist_uri document.

packlist_last_access

When did we last try to to access the packlist_uri document. The value is seconds from epoch as for perl's time() function.

packlist_fresh_until

When do we need to refetch the packlist_uri document. The value is seconds from epoch as for perl's time() function.

$client->repos

Returns list of available repo identifiers.

$client->repo_add( name => $name, packlist_uri => $uri )

Will add a new repository with the given attributes. The method will croak if a repository with the same packlist_uri already exists. The return value is the $repo_id of the new repository.

$client->repo_delete( $repo_id )

Will make the client forget about the given repository.

$client->repo_enable( $repo_id )
$client->repo_enable( $repo_id, $bool )

Makes it possible to enable and disable the given reposiory. If $bool is provided and is FALSE, then the repository is disabled. The return value is TRUE if the given repository was enabled.

$client->repo_set_name( $repo_id, $name )

Will update the name by which the given repo is known.

$client->repo_set_packlist_uri( $repo_id, $uri )

Will update the address of the packlist to monitor for the given repository. Will croak if the $uri is already used by some other repo.

Updating the URI will loose all cached information about the repo. A new 'repo_sync' is needed to update this information.

$client->repo_sync( %args )

Will sync the local cache of packages from the enabled repositories. Remote repositories are not contacted if the cache is not considered stale yet. The following options are recognized:

force => $bool

If TRUE force state to be transfered again from remote repositories. Make requests unconditional.

validate => $bool

If TRUE validate state from remote repositories even if state still believed to be fresh. Will still send conditional requests.

max_ppd => $num

If repository is an HTML document set limit for how many PPD links it might contain. The default is 100.

repo => $repo_id

Pass repo with an identifier to only sync the given repo.

$client->search( $pattern )
$client->search( $pattern, $field,... )

Will search for packages matching the given glob style $pattern. Without further arguments this will return a list of package names. With $field arguments it will return a list of array references, each one filled in with the corresponding values for maching packages.

$client->search_lookup( $num )

Will look up the given package from the last search() result, where $num matches the 1-based index into the list returned by the last search. This will return an the ActivePerl::PPM::RepoPackage manpage object.

$client->packages
$client->packages( $field,... )

Without arguments returns the ids of packages available. In scalar context returns the number of packages.

With arguments return a list of array references each one representing one package. The elements of each array are the fields requested. See the ActivePerl::PPM::RepoPackage manpage for what field names are available.

$client->package( $id )
$client->package( $name )
$client->package( $name, $version )

Returns the the ActivePerl::PPM::RepoPackage manpage object matching the arguments or undef if none match. As there can be multiple packages with the same name, an arbitrary one is selected if $name but no $version is given.

$client->feature_best( $feature )

Returns the highest version number provided for the given feature by the packages found in all enabled repositories. The method return undef if no package provide this feature.

$client->package_best( $feature, $version )

Returns the best package of all enabled repositories that provide the given feature at or better than the given version.

$client->feature_have( $feature )
$client->feature_have( $feature, @areas )

Returns the installed version number of the given feature. Returns undef if none of the installed packages provide this feature.

If one or more @areas are provided, only look in the areas given by these names.

$client->packages_depending_on( $pkg, $area )

Returns the packages (as ActivePerl::PPM::Package objects) that would "break" if the given package was uninstalled. This means that the returned packages are those that depend on features that the given package provide. In scalar context return number of packages.

The $pkg argument can be either a package name or a package object.

$client->packages_missing( %args )

Returns the list of packages to install in order to obtain the requested features. The returned list consist of the ActivePerl::PPM::RepoPackage manpage objects. The attribute _wanted will be TRUE if a package was requested directly. The attribute _needed_by will be an array reference of package names listing packages having resolved dependencies on this package. These attributes do not exclude each other.

The returned list will be empty if all the requested features are already installed.

The method will croak if nothing provides the requested features, if dependencies can't be resolved or if the packages selected have conflicting dependencies.

The arguments to the function are passed as key/value pairs:

want => \@features

This is the list of features to resolve. The elements can be plain strings denoting feature names, or references to arrays containing a $name, $version pair. If $version is provided as undef then this is taken as an upgrade request and the function will try to find the packages that provide the best possible version of this feature.

have => \@pkgs

List of packages you already have decided to install. The function will check if any of these packages provide needed features before looking anywhere else.

want_deps => \@pkgs

Resolve any dependencies for the given packages.

area => \@areas

List of names of install areas to consider when determining if requested features or dependencies are already installed or not.

force => $bool

If TRUE then return packages that provide the given features even if they are already installed. Will also disable check for downgrades.

follow_deps => $str

In what way should packages dependencies be resolved. The provided $str can take the values all, missing, or none. The default is missing. If $str is all then dependent packages are returned even if they are already installed. If $str is missing then only missing dependencies are returned. If $str is none then dependencies are ignored.

error_handler => \&callback

Call the given error handler instead of croaking in the case of trouble. Error messages are provided as argument. There can be more than one.

Providing an error_handler allow the function to return missing packages for working dependencies even if not all dependencies worked out.

$client->install( %args )

Will download, unpack and install the given packages. The function will raise an exception of it gets into trouble, otherwise it will return

The arguments to the function are passed as key/value pairs:

packages => \@pkgs

Mandatory argument that provide the packages to install. The array passed should contain ActivePerl::PPM::Package objects.

area => $area

What install area to install into. If not provided, then $client->default_install_area is used.

run_cb => \&func

A callback function that should behave like &ActivePerl::Run::run which will be called to execute the commands of the post install script. If not provided, then &ActivePerl::Run::run will be used.

BUGS

none.


ActivePerl::PPM::InstallArea - Perl installation area

  • SEE ALSO
  • BUGS

NAME

ActivePerl::PPM::InstallArea - Perl installation area

SYNOPSIS

  my $area = ActivePerl::PPM::InstallArea->new("site");
  # or
  my $area = ActivePerl::PPM::InstallArea->new(prefix => "$ENV{HOME}/perl");

DESCRIPTION

An ActivePerl::PPM::InstallArea object provide an interface to a Perl install area. Different install areas might have different protection policies and each contain a set of installed packages and modules. The concept is the same as INSTALLDIRS provided by the ExtUtils::MakeMaker manpage.

An install area is divided into the following directories:

lib

This is where architecture neutral modules go. Packages that are implemented in pure perl are installed here.

archlib

This is where architecture specific modules go. Packages that are implemented using XS code are installed here. For ActivePerl this will normally be the same as lib.

script

This is where architecture neutral programs go.

bin

This is where architecture specific programs go. For ActivePerl this will normally be the same as script.

etc

This is where configuration files go.

man1

This is where Unix style manual pages describing programs go.

man3

This is where Unix style manual pages describing modules go.

html

This is where HTML files go.

prefix

This just provide a prefix for the install area as a whole. All paths above should be at or below prefix.

The following methods are provided:

$area = ActivePerl::PPM::InstallArea->new( $name )
$area = ActivePerl::PPM::InstallArea->new( %opts )

Constructs a new ActivePerl::PPM::InstallArea object. If constructed based on $name, then the constructor might croak if no install area with the given name is known. The "perl" and "site" install areas are always available. Some perls might also have a "vendor" install area.

Alternatively the directories to use can be specified directly by passing them as key/value pair %opts. Only prefix is mandatory. All other directories are derived from this, except for the man* directories will only set up if specified explicitly.

The option autoinit will if TRUE make the install area call $self->initialize automatically when some method need access to the database.

$area->name

Returns the name. This returns the empty string for nameless InstallArea.

$area->prefix
$area->archlib
$area->lib
$area->bin
$area->script
$area->man1
$area->man3
$area->html
$area->etc

Returns the corresponding path.

$area->inc

Returns the list of directories to be pushed onto perl's @INC for the current install area.

$area->initialized

Returns TRUE if this area has been initialized. If autoinit was specified for the constructor, then this method might have the side effect of actually initializing the database, in which case this returns TRUE.

$area->initialize

Set up the database used to track packages for the install area if not already set up. This invokes sync_db() if the database was created.

Most methods will croak unless the install area has been initialized. Exceptions are name(), readonly(), initialized(), packages() and the directory accessors (like lib(), script(),...).

The autoinit option can be specified for the constructor to make the database be automatically set up on during the first method call than need it.

$area->readonly

Returns TRUE if it is not possible to install or remove packages from the area. This is usually caused by the user does not have permission to modify the files of the area.

This also returns TRUE for unintialized install areas.

$area->install( packages => [\%pkg1, \%pkg2, ...] )

Install the given list of packages as one atomic operation. The function returns TRUE if all packages installed or FALSE if installation failed.

Each package to be installed is described by a hash reference (or an the ActivePerl::PPM::Package manpage object) with the following elements:

name => $name

The name of the package. If a package with the given name is already installed, then it will replaced with the new package. This is the only mandatory attribute.

version => $version

The version identifier for the given package.

author => $string

Who the current maintainer of the package is. Should normally be on the form "Givenname Lastname <user@example.com>".

abstract => $string

A short sentence describing the purpose of the package.

blib => $path

Pick up files to install from the given blib style directory. The codebase directory of PPD packages is usually a tarball of this stuff.

files => \%hash

A hash describing files and directories to install. The keys are where to copy files from and the values are install locations. The install locations selects what type of directory to install into by prefixing them with an dir identifier followed by a colon. Example:

   files => {
      Foo => "archlib:Foo",
      "Bar.pm" => "lib:Bar.pm"
   }

This will install the "Foo" directory into the archlib area and the "Bar.pm" module into the lib area.

$area->uninstall( $name )

Removes the given package and its installed files. Croaks if no such package was installed in the first place. Uninstalling a package might break other packages that depended on features this package provided.

$area->verify( %opts )

Verify that the files of the installed packages are still present and unmodified.

In scalar context returns TRUE if all files where still found good. In array context return key/value pairs suitable for assignment to a hash. The verified value is the number of files checked. The missing, modified, wrong_mode tally the files found to be missing, modified or chmoded.

The following options are recognized:

package => $name

Only verify the given package.

file_cb => \&sub

Function called back for each file visited. The function is called with 3 arguments; the file name, expected md5 checksum and expected file mode.

badfile_cb => \&sub

Function called back each time a bad file is found. The first argument is what kind of badness (same as the status keys in the return value), the second is the file name and the addtional info varies depending on kind.

$area->packages( @fields )

Without arguments returns the sorted list of names of packages currently installed. In scalar context returns the number of packages installed, or undef if database has not been initialized.

With arguments return a list of array references each one representing an installed package. The elements of each array are the fields requested. The list will be sorted by package name. See the ActivePerl::PPM::Package manpage for what field names are available.

$area->package( $id )
$area->package( $name )
$area->package( $name, sloppy => 1 )

Return an package object (see the ActivePerl::PPM::Package manpage) for the given package. Returns undef if no such package is installed.

If no package match the specified name exactly and sloppy is specified then search again ignoring case and even search for features provided that match name. The method will croak if this extended search end up matching multiple packages.

$area->package_id( $name )

Returns the internal identifier for the given package. The package name much match exactly; case matters. Returns undef if no such package is installed. This is the cheapest way to check if a package is installed.

$area->package_id( $name, sloppy => 1 )

Find package even if the name does not match exactly. The package will be found if the name match without regard to case or if it provide the given name as a feature. Will croak if multiple packages match.

$area->feature_have( $feature )

If one of the installed packages provide the given feature, then the feature version number is returned. The method returns undef if no package provide the given feature.

$area->package_files( $id )

Returns the list of names for the files that belong to the given package. In scalar context return the number of files.

$area->package_packlist( $id )

Returns the .packlist file for the given package. See the ExtUtils::Packlist manpage.

$area->packlists

Returns the list of packages that have .packlist files installed. In scalar context return a hash reference; the keys are package names and the values are full paths to the corresponding .packlist file. This will also pick up packages installed by other means that by PPM. See the ExtUtils::Packlist manpage for more information about these files. PPM does not use .packlist files to track the files installed by the packages it manage, but it keeps them in sync for other tools that manage modules.

$area->sync_db( %opt )

Synchronize the state of the PPM database with what modules seems to be installed in the directories of the current install area. Packages where all files are gone will also be deleted from the PPM database.

The following options are recognized:

keep_package_version => $bool

If TRUE don't try to update the package version from the version number of the module with the same name as the pacakge.

SEE ALSO

the ActivePerl::PPM::Package manpage, the ExtUtils::Packlist manpage.

BUGS

none.


ActivePerl::PPM::PPD - Parser for PPD files

  • PPD XML FORMAT
    • Changes since PPM3
  • SEE ALSO

NAME

ActivePerl::PPM::PPD - Parser for PPD files

SYNOPSIS

  my $ppd = ActivePerl::PPM::Package->new_ppd('<SOFTPKG NAME="Foo">...</SOFTPKG>');

DESCRIPTION

This module adds the new_ppd constructor to the ActivePerl::PPM::Package class. This constructor parses PPD files and allow package objects to be initialized from these files. PPD is an XML based format that is used to describe PPM packages.

The following methods are added:

$ppd = ActivePerl::PPM::Package->new_ppd( $ppd_document, %opt )
$ppd = ActivePerl::PPM::Package->new_ppd( $parsed_ppd_hashref, %opt )

The constructor take a literal document as argument and will return and object representing the PPD. The method returns undef if $ppd_document does not contain the expected XML.

The following options are supported:

arch => $archname

The $archname should be specified to select attributes for a specific architecture where the PPD describes multiple implementations. The value noarch is the default and will only select implementation sections without any ARCHITECTURE restriction.

base => $base_uri

All URIs in the PPD will be made absolute with $base_uri as base.

rel_base => $base_uri

All URIs in the PPD will be made relative if they can be resolved from $base_uri. Only safe to use together with base which is applied first. If both base and rel_base are the same, they cancel each other out and the effect is the same as if none of them where specified.

PPD XML FORMAT

The PPM PPD is an XML based format used to describe PPM packages. The format is based on the now defunct OSD specification (http://www.w3.org/TR/NOTE-OSD). This shows an example of a minimal PPD document:

  <SOFTPKG NAME="Acme-Buffy" VERSION="1.3" DATE="2002-03-27">
    <AUTHOR>Leon Brocard (leon@astray.com)</AUTHOR>
    <ABSTRACT>
      An encoding scheme for Buffy the Vampire Slayer fans
    </ABSTRACT>
    <PROVIDE NAME="Acme::Buffy" VERSION="1.3"/>
    <IMPLEMENTATION>
      <CODEBASE HREF="i686-linux-thread-multi-5.8/Acme-Buffy.tar.gz"/>
      <ARCHITECTURE NAME="i686-linux-thread-multi-5.8"/>
    </IMPLEMENTATION>
  </SOFTPKG>

The following elements are used:

<ABSTRACT>...</ABSTRACT>

Content is a short statement describing the purpose of this package. No attributes. Parent must be a SOFTPKG element.

<ARCHITECTURE NAME="..."/>

The required attribute NAME should match $Config{archname}-$major_vers for the perl this package was compiled for. If this element is missing, it's the same as specifying <ARCHITECTURE NAME="noarch"/>. No content. Parent must be either SOFTPKG or IMPLEMENTATION.

Packages or implementations marked with "noarch" are assumed to installable on any architecture.

<AUTHOR>...</AUTHOR>

Content is the package author's name (with email address). No attributes. Parent must be a SOFTPKG element.

<CODEBASE HREF="..."/>

The required HREF attribute provides a URI where the binary package (the tared up blib tree) of the package can be obtained. The URI can be relative and is then resolved based on the URI of the PPD document. No content. Parent must be SOFTPKG or IMPLEMENTATION.

<DEPENDENCY NAME="..." VERSION="..."/>

Deprecated. Required attribute is NAME. Optional attribute is VERSION. No content. Element might be repeated any number of times. Parent must be an IMPLEMENTATION element.

This element expresses a dependency on another package with the given name and with the given version number or better. The other package must be installed for this package to work.

This element is still recommended for PPDs that are to be used by both PPM4 and PPM3 clients, as the PPM3 clients will ignore any REQUIRE elements provided. PPM4 clients regard DEPENDENCY the same as REQUIRE, but will simply ignore the VERSION provided.

<IMPLEMENTATION>...</IMPLEMENTATION>

No attributes. Optional container for ARCHITECTURE, DEPENDENCY, INSTALL, PROVIDE, REQUIRE, UNINSTALL elements. Parent must be SOFTPKG. There can be multiple instances of IMPLEMENTATION but they should each contain an ARCHITECTURE element that differ from each other.

<INSTALL EXEC="..." HREF="..."/>
<INSTALL EXEC="...">...</INSTALL>

Optional attributes are EXEC and HREF. Textual content can be included. Provides a script or commands to run after the blib files of the package have been installed, a so called post-install script. The script to run can either be provided inline or externally via HREF. If both are provided then only the HREF is used. Parent must be either SOFTPKG or IMPLEMENTATION.

If EXEC is provided, it gives the name of the interpreter to run the script. For historical reasons, if the script is not obtained via HREF then any occurences of double semicolon ";;" is replaced by newline before it is saved in a temporary file and passed as the first argument to the EXEC interpreter. The special value "PPM_PERL" ensures that the script runs with the same perl interpreter that runs PPM. The special value "SELF" make the script run as a self contained executable.

If EXEC is not provided, the commands of the script are passed to the system command interpreter (via system(3)) one by one. If the script was obtained via HREF, each line is considered a command. If the script was obtained from the content, then a double semicolon ";;" is used to separate commands.

When the script/command runs it uses the unpacked package tarball (obtained by downloading the CODEREF) as the working directory, and the following environment variables will be set:

PPM_ACTION

One of "install", "upgrade" or "uninstall".

PPM_INSTARCHLIB

The archlib directory of the current install area.

PPM_INSTLIB

The lib directory of the current install area.

PPM_INSTPACKLIST

The name of the installed .packlist file of the package.

PPM_INSTROOT

The prefix directory of the current install area.

PPM_NEW_VERSION

The version label of the package just installed.

PPM_PERL

The path to the perl that runs PPM.

PPM_PREV_VERSION

The version label that the package had before the upgrade started. This variable is only present when PPM_ACTION is "upgrade".

PPM_VERSION

The version of PPM currently running.

<PROVIDE NAME="..." VERSION="..."/>

Required attribute is NAME. Optional attribute is VERSION. No content. Element can be repeated any number of times. Parent must be either SOFTPKG or IMPLEMENTATION.

The NAME represents a feature that this package provides if installed. Any label goes. VERSION is a floating point number.

Packages containing perl modules should have one PROVIDE element for each module installed by the package. Module names that do not naturally contain double colon "::" should have "::" appended to them.

<REPOSITORY>...</REPOSITORY>

Element must be root if present. Container for a set of SOFTPKG elements. Optional attributes are ARCHITECTURE and BASE.

ARCHITECTECTURE provides the default for all contained SOFTPKG elements that do not have an explicit ARCHITECTECTURE element.

BASE overrides the base URI that the relative URIs of CODEBASE, INSTALL and UNINSTALL are resolved from. If BASE itself is relative, it is first resolved based on the URI of the PPD document.

The file name package.xml is commonly used for documents containing a REPOSITORY root.

<REPOSITORYSUMMARY>...</REPOSITORYSUMMARY>

Treated the same as REPOSITORY. Supported for backwards compatibility with old style package.lst files.

<REQUIRE NAME="..." VERSION="..."/>

Required attribute is NAME. Optional attribute is VERSION. No content. Element might be repeated any number of times. Parent must be either SOFTPKG or IMPLEMENTATION.

This element expresses a dependency on some other package that provides the feature given by NAME and with the given version number or better. A package that provides the given feature must be installed for this package to work.

<SOFTPKG NAME="..." VERSION="..." DATE="...">...</SOFTPKG>

Represents a package available for PPM to install. Container for all the other elements defined here (except REPOSITORY and REPOSITORYSUMMARY).

Required attributes are NAME and VERSION. Optional attribute is DATE.

The NAME and VERSION value can be any label. Older versions of this specification had a more strict definition of VERSION as a sequence of exactly 4 numbers in the range 0 to 65535 separated by comma. If such values are encountered then they are converted to "standard" format by replacing the commas with dots and trimming off ".0.0" or ".0".

The DATE attribute should use ISO 8601 formatted date (or datetime) stamps. That is "YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ssZ" format. See http://en.wikipedia.org/wiki/ISO_8601 for more information.

Parent must be REPOSITORY or REPOSITORYSUMMARY, or the SOFTPKG can be the document root. Content elements can be in any order.

Documents where SOFTPKG is root are normally stored in files with the .ppd extension.

<UNINSTALL EXEC="..." HREF="..."/>
<UNINSTALL EXEC="...">...</UNINSTALL>

Used for scripts that run just before the blib files of the package is uninstalled. The attributes and content are treated the same as for INSTALL and the same set of environment variables are availabe to the script.

The uninstall script runs with a new, clean temporary directory as its working directory. The directory and its content is removed after the script finishes.

Changes since PPM3

The PPD format has changed in PPM4. This section lists the differences:

  • The format of the SOFTPKG/VERSION attribute has been relaxed. This attribute should now contain the version identifier as used for the original package. PPM will not be able to order packages based on this label.

  • The SOFTPKG/DATE attribute has been introduced. This should be the release date of the package. For CPAN packages this should be the date when the package was uploaded to CPAN.

  • Added REQUIRE and PROVIDE elements that are used to describe features that this package depends on and provides. The NAME attribute is required for both. The VERSION attribute is optional and should be a floating number. Features are assumed to be backwards compatible and a feature with a higher version number is regarded as better.

  • The DEPENDENCY elements are deprecated. Use REQUIRE instead. If present they are mapped to REQUIRE but their VERSION attribute is ignored.

  • The OS, OSVERSION, PROCESSOR, PERLCORE elements are deprecated and always ignored. Implementations are matched using the ARCHITECTURE element only.

  • The TITLE element is deprecated and ignored. The SOFTPKG/NAME attribute is the title.

SEE ALSO

the ActivePerl::PPM::Package manpage, http://www.w3.org/TR/NOTE-OSD


ActivePerl::PPM::Package - Package class

    • Constructors
    • Attributes
    • Comparators
    • Misc methods
  • BUGS

NAME

ActivePerl::PPM::Package - Package class

SYNOPSIS

  my $pkg = ActivePerl::PPM::Package->new(name => 'Foo',...);
  # or
  my $pkg = ActivePerl::PPM::Package->new(\%hash);

DESCRIPTION

The ActivePerl::PPM::Package class wraps hashes that describes packages; the unit that the PPM system manages.

Constructors

The following constructor methods are provided:

$pkg = ActivePerl::PPM::Package->new( %opt );
$pkg = ActivePerl::PPM::Package->new( \%self );

The constructor either take key/value pairs or a hash reference as argument. The only mandatory field is name. If a hash reference is passed then it is turned into an ActivePerl::PPM::Package object and returned; which basically pass ownership of the hash.

$copy = $pkg->clone

Returns a copy of the current package object. The attributes of the clone can be modified without changing the original.

ActivePerl::PPM::Package->new_dbi($dbh, $id);
ActivePerl::PPM::Package->new_dbi($dbh, $name, $version);

Read object from a database and return it. Returns undef if no package with the given key is found.

$pkg->dbi_store( $dbh )

Writes the current package to a database. If $pkg was constructed by new_dbi then this updates the package, otherwise this creates a new package object in the database.

Returns the $id of the object stored if successful, otherwise undef.

Attributes

The attributes of a package can be accessed directly using hash syntax or by accesor methods. The most common attributes are described below, but the set of attributes is extensible.

$str = $pkg->id

Returns the database id of package. This attribute is set if the object exists in a database.

$str = $pkg->name

Returns the name of the package.

$str = $pkg->version

Returns the version identifier for the package. This string can be anything and there is no reliable way to order packages based on these version strings.

$str = $pkg->name_version

Returns the name and version concatenated together. This form might be handy for display, but there is no reliable way to parse back what is the name and what is the version identifier.

$str = $pkg->release_date

Returns the date the package was released on as an ISO 8601 date (YYYY-MM-DDThh:mm:ss). For CPAN packages this is the date the package was uploaded to CPAN.

$str = $pkg->author

The name and email address of the current maintainer of the package.

$str = $pkg->abstract

A short sentence describing the purpose of the package.

$url = $pkg->ppd_uri

This is the URI for the PPD file itself.

$str = $pkg->ppd_etag

This is the ETag that the server reported for the PPD last time.

$str = $pkg->ppd_lastmod

This is the Last-Modified field that the server reported for the PPD last time.

$url = $pkg->codebase

Returns the URL to implementation; a blib tarball. Interpret this URL relative to ppd_uri.

%features = $pkg->provides

Returns a list of (feature, version) pairs describing what features this package provide. A feature name with a double colon in it represent a perl module. A package always provide its own name as a feature.

%features = $pkg->requires

Returns a list of (feature, version) pairs describing what features this package require to be installed for it to work properly. A feature name with a double colon in it represent a perl module.

Comparators

The following functions/methods can be used to order packages.

$pkg->compare( $other )

Returns -1, 0, 1 like perl's builtin cmp. Return undef if no order is defined.

$pkg->better_than( $other )

Returns TRUE if this package is better than the package passed as argument. This method will croak if no order is defined.

$pkg->best( @others )
ActivePerl::PPM::Package::best( @pkgs )

Returns the best package. Might croak if no order is defined among the packages passed in.

Misc methods

ActivePerl::PPM::Package->sql_create_tables

This returns SQL CREATE TABLE statements used to initialize the database that the new_dbi and dbi_store methods depend on.

$bool = $pkg->features_declared

Returns TRUE if this package declare what features it provide. PPM4 style packages should declare what modules and other features they provide, but packages from older repositories might not.

$pkg->has_script( $kind )

Return TRUE if the package has the given $kind of script attached. The $kind argument should be either "install" or "uninstall".

$pkg->run_script( $kind, $area, $tmpdir, \%pkg_info )

Execute the given kind of script for the package. The $kind argument should be either "install" or "uninstall". The $kind and $area argument must be provided.

BUGS

none.


ActivePerl::PPM::RepoPackage - Package class that tracks PPD file attributes

  • SEE ALSO
  • BUGS

NAME

ActivePerl::PPM::RepoPackage - Package class that tracks PPD file attributes

DESCRIPTION

ActivePerl::PPM::RepoPackage is a subclass of ActivePerl::PPM::Package that adds a few fields that is used to track changes to the corresponding PPD file.

The following are the new attributes:

$id = $pkg->repo_id

What repo does this package come from.

$url = $pkg->ppd_uri

Inherited, but here this might be a relative URI and is then interpreted relative to the packlist_uri of the repo.

$num = $pkg->ppd_fresh_until

At what time should the ppd information be refreshed from the repo.

SEE ALSO

the ActivePerl::PPM::Package manpage, the ActivePerl::PPM::Repo manpage

BUGS

none.


ActiveState::Browser - Interface to invoke the web-browser

  • ENVIRONMENT
  • BUGS

NAME

ActiveState::Browser - Interface to invoke the web-browser

SYNOPSIS

  use ActiveState::Browser;
  ActiveState::Browser::open("http://www.activestate.com");

DESCRIPTION

The ActiveState::Browser module provides an interface to make a web browser pop up showing some URL or file. The following functions are provided:

open( $url )

This will try to open up a web browser displaying the given URL. The function will croak if the $url can't be resolved or if no suitable browser could be found. The can_open() test can be used to protect against such failure, but note that such a test is not race-proof.

If the $url is absolute it is passed directly to the browser.

If the $url is relative it is looked up relative to the directory $ActiveState::Browser::HTML_DIR, which defaults to the current directory.

can_open( $url )

Will return TRUE if we can invoke a browser for the given URL. If the URL is not to a local file, then this always returns TRUE, given that a browser program was found.

ENVIRONMENT

The AS_BROWSER environment variable can be set to override what browser to use. The string %s will be replaced with the URL to open. If no %s is present the string is taken as a command to invoke with the URL as the only argument.

The %s template was inspired by the BROWSER environment variable suggestion that appear quite dead; see http://www.catb.org/~esr/BROWSER/. Note that the AS_BROWSER is not a colon separated list.

BUGS

none.


ActiveState::Bytes - Format byte quantities

  • COPYRIGHT
  • SEE ALSO

NAME

ActiveState::Bytes - Format byte quantities

SYNOPSIS

 use ActiveState::Bytes qw(bytes_format bytes_parse);
 print "The file is ", bytes_format(-s $file), " long.\n";

 print "1 megabyte is ", bytes_parse('1m'), " bytes.\n";

DESCRIPTION

The ActiveState::Bytes module provides functions for dealing with human readable byte strings.

$str = bytes_format( $n )

This formats the number of bytes given as argument as a string using suffixes like "KB", "GB", "TB" to make it concise. The return value is a string like one of these:

   128 bytes
   1.5 KB
   130 MB

Precision might be lost and there is currently no way to influence how precise the result should be. The current implementation gives no more than 3 digits of precision.

$bytes = bytes_parse( $str )

Converts a bytes string ( "1m" ) into actually bytes. Lowercase units are in powers of 10, uppercase are in powers of 2. For example, 1K is 1024 bytes, 1k is 1000 bytes. Supports units are k, m, g, t, p, e, z, and y in ascending order.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.

SEE ALSO

the ActiveState::Duration manpage


ActiveState::Color - Collection of color conversion functions

  • BUGS

NAME

ActiveState::Color - Collection of color conversion functions

SYNOPSIS

 use ActiveState::Color qw(name_from_rgb rgb_from_name
                           rgb_from_hsv hsv_from_rgb
                          );
 my($h, $s, $v) = hsv_from_rgb(rgb_from_name(shift));
 # make the color fully saturated and a bit lighter
 $s = 1; $v *= 1.2;
 print name_from_rgb(rgb_from_hsv($h, $s, $v)), "\n";

DESCRIPTION

The following functions are provided:

($r, $g, $b) = rgb_from_name( $name )

This will convert a color name or a hex RGB-tripplet to a decimal RGB value with $r, $g, $b in the range 0.0 to 1.0. The hex tripplet can have any precision and can optionally be prefixed with "#". If the name is not recognized this function will croak. Examples of valid names are:

    #F0F
    #FF00FF
    #FFF000FFF
    ff00ff
    black
    BLACK
    yellow
$hexname = hex_from_rgb( $r, $g, $b )

This converts a decimal RGB value with $r, $g, $b in the range 0.0 to 1.0 to an 8-bit hex RGB-tripplet. The output will be on the form:

    #ff00ff
$name = name_from_rgb( $r, $g, $b )

This will convert a decimal RGB value to a color name. If the color is one of the 8 primary RGB colors then the name will be returned, otherwise a hex RGB-tripplet is returned. The 8 primary color names are:

    black
    blue
    cyan
    green
    magenta
    red
    yellow
    white
($r, $g, $b) = rgb_from_hsv( $h, $s, $v )
($h, $s, $v) = rgb_from_hsv( $r, $g, $b )

These functions convert between the RGB and HSV color space. The range of $s, $v, $r, $g, and $b is 0.0 to 1.0. The range of $h is 0.0 to 360.0.

BUGS

none.


ActiveState::DateTime - Date and Time utilities

  • COPYRIGHT

NAME

ActiveState::DateTime - Date and Time utilities

SYNOPSIS

 use ActiveState::DateTime qw(is_leap_year days_in_month check_date month_name_short month_name_long gmt_offset);

 if (is_leap_year($year)) {
    ... do stuff ...
 }

 my $max_days = days_in_month($year, $month);

 if (check_date($year, $month, $day)) {
    ... do stuff ...
 }

 my $short_month_name = month_name_short($month);

 my $long_month_name = month_name_long($month);

 my $offset = gmt_offset();

DESCRIPTION

The ActiveState::DateTime module provide functions that can be used for convenient data and time checks.

is_leap_year($year)

This function takes a numerical argument of a year. It returns true if the year is a leap year, otherwise it returns false.

$days = days_in_month($year, $month)

This function returns the number of days in a month and takes into account leap years. The year is a numerical argument. The month is a numerical argument from 1 to 12.

check_date($year, $month, $day)

This function takes numerical arguments for year, month and day and checks to make sure the date is valid. For example:

Is February 29, 2005 a valid date?

Is February 29, 2008 a valid date?

The month is a numerical argument that ranges from 1 to 12.

$month_name = month_name_short($month);

This function returns the English three letter abbreviation of the month name.

$month_name = month_name_long($month);

This function returns the full English month name.

$gmt_offset = gmt_offset();

This function returns the GMT offset.

No functions are exported by default.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.


ActiveState::DiskUsage - Calculate how much diskspace is used

  • BUGS
  • COPYRIGHT
  • SEE ALSO

NAME

ActiveState::DiskUsage - Calculate how much diskspace is used

SYNOPSIS

 use ActiveState::DiskUsage qw(du);
 print du(".") . " bytes allocated in current directory\n";

DESCRIPTION

This module provide a single function called du() that calculate the diskusage for the given file or directory. If the argument is a directory then the diskspace used by all its files and subdirectories are recursively counted as well. Symbolic links are not dereferenced.

The return value of the du() function is the number of bytes allocated.

The du() function is not exported by default.

BUGS

On Windows, this function only sum up the size of the files found at the given location. This number will be lower than the actual allocation as it does not take block allocation and space consumed by the directories themselves into account. The the Win32::DirSize manpage module might give more accurate results on this platform.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.

SEE ALSO

the ActiveState::Bytes manpage


ActiveState::Duration - Format and parse time duration values

  • COPYRIGHT
  • SEE ALSO

NAME

ActiveState::Duration - Format and parse time duration values

SYNOPSIS

 use ActiveState::Duration qw(ago_eng);
 print "It is now ", ago_eng(time), " since time begun.\n";

DESCRIPTION

The ActiveState::Duration module provides functions to format and parse time duration values. Time is expressed as a number of weeks, days, hours, minutes and seconds.

$str = dur_format_XXX( $duration )
$str = dur_format_XXX( $duration, $precision )
$str = dur_format_XXX( $duration, $precision, $frac_part )

The dur_format_XXX() functions take a time $duration value (in seconds) and format it as a readable string. This section describes the common arguments supported by most of dur_format_XXX() functions. The XXX in the function name selects which format it returns and is described below.

The $precision argument specify how close the string much match the duration value. The default is 0.05 which means that up to 5% off is acceptable. Pass 0 as the $precision to request an exact result.

The $frac_part specify at which time unit formatting will start using fractions to achieve the desired precision. It should be one of "week", "day", "hour", "minute", "second" or "first". The default is "second".

A $frac_part value of "first" is special and needs some more explanation. The time units will be considered in order from "week" to "second", and the first one longer than the $duration is used.

$str = dur_format_sm( @ARGS )

Use the Sendmail format which looks like "1h30m". If the $duration value is negative it is formatted like "-1h30m".

$str = dur_format_iso( @ARGS )

Use the ISO 8601 format which looks like "PT1H30M". If the $duration value is negative it is formatter with a leading "-", even though that is not standards conforming.

$str = dur_format_eng( @ARGS )

Use plain English; "1 hour and 30 minutes". If the $duration value is negative then the word "negative" is prepended to the string.

$str = ago_eng( @ARGS )

Same as dur_format_eng() but adds the word "ago" as long as $duration is positive and the words "from now" if $duration is negative. A $duration of 0 is special cased as "just now".

$str = dur_format_clock( $duration )

Use stopwatch format; "1:30:00", i.e. "hhh:mm:ss". This function does not take the $precision or $frac_part arguments yet and the $duration is truncated to whole seconds. A negative $duration value will be formated with a leading "-". A value of 0 is formatted as "0:00:00".

$duration = dur_parse( $str )

This function takes a string representing a duration value and return it as number of seconds. All strings produced by any of the dur_format_XXX() or the ago_eng() functions can be parsed back to an $duration value by dur_parse(). It returns undef if it cannot parse the $str for some reason.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.

SEE ALSO

the Time::Duration manpage, the ActiveState::StopWatch manpage, the ActiveState::Bytes manpage


ActiveState::Handy - Collection of small utility functions

  • BUGS
  • SEE ALSO

NAME

ActiveState::Handy - Collection of small utility functions

SYNOPSIS

 use ActiveState::Handy qw(add);
 my $sum = add(1, 2, 3);

DESCRIPTION

This module provides a collection of small utility functions.

The following functions are provided:

add( @numbers )

Adds the given arguments together.

cat( $file )

Returns the content of a file. Returns undef if the file could not be opened. Unlike the cat(1) command it only takes a single file name argument. The file is read in binary mode.

cat_text( $file )

Just like cat() but will read the file in text mode. Makes a difference on some platforms (like Windows).

ceil( $number )

Rounds the number up to the nearest integer. Same as POSIX::ceil().

cp_files( $from, $to, @files )

Copies files from source to destination directory. Destination directory will be created if it doesn't exist. Function dies if any file cannot be found.

cp_tree( $from, $to )

Recursively copies all files and subdirectories from source to destination directory. All destination directories will be created if they don't already exist.

iso_date( $time )
iso_date( $y, $m, $d )

Returns a ISO 8601 formatted date; YYYY-MM-DD format. See http://www.cl.cam.ac.uk/~mgk25/iso-time.html.

iso_datetime( $time )
iso_datetime( $y, $m, $d, $h, $m, $s )

Returns a ISO 8601 formatted timestamp; YYYY-MM-DDThh:mm:ss format. See http://www.cl.cam.ac.uk/~mgk25/iso-time.html.

xml_esc( $text )

Will escape a piece of text so it can be embedded as text in an XML element.

xml_clean( $text )

Will remove control characters so it can be embedded as text in an XML element. Does not perform escaping.

For legacy reasons this module re-exports the functions run(), shell_quote() and decode_status() from ActiveState::Run.

BUGS

none.

SEE ALSO

the ActiveState::Run manpage


ActiveState::Indenter - Keep track of indentation levels

  • COPYRIGHT

NAME

ActiveState::Indenter - Keep track of indentation levels

SYNOPSIS

 use ActiveState::Indenter;

 my $fh = ActiveState::Indenter->new(*STDOUT);
 $fh->print("if (foo()) {\n")
 $fh->over;
 $fh->print("# do something\n");
 $fh->back;
 $fh->print("}\n");

DESCRIPTION

The ActiveState::Indenter works like an output file handle but will insert whitespace in the printed stream reflecting the current indentation level. It is useful for printing out nicely formatted programs.

The following methods are available:

$fh = ActiveState::Indenter->new( $filehandle )

The object constructor takes a file handle as argument. It will create a new indenter object that prints to the given file handle.

The $filehandle can actually be any object that implement a print() method.

$fh->handle

Returns back the filehandle passed to the constructor.

$fh->line_width
$fh->line_width( $new_width )

This get/set the current line width. The line width is used by the soft_space() method. The default is 70.

$fh->indent_offset
$fh->indent_offset( $new_offset )

This get/set the standard indentation offset. The default is 4.

$fh->print( $string )

The print() will print the string given as argument to the wrapped file handle but with suitable additional leading space added. The indenter object will never buffer output, so all content of the string will have reached the file when print returns.

$fh->soft_space

This will print a space character " " if there is more room on the line, or a newline otherwise.

$col = $fh->indent

This returns the current indentation column.

$fh->over
$fh->over( $offset )

This increase the indentation column with the given amount. Without argument the standard amount is used.

$fh->over_cur

This sets the indentation column the same as the current column.

$fh->over_abs( $col )

This set the indentation column to the number given.

$fh->back

Returns to the previous indentation column.

$col = $fh->column

Returns the current column position.

$line = $fh->line
$fh->line( $new_line )

This get/set the current line number.

$n = $fh->depth

Returns the current indentation depth.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.


ActiveState::Menu - Present a menu

  • SEE ALSO

NAME

ActiveState::Menu - Present a menu

SYNOPSIS

 use ActiveState::Menu qw(menu prompt yes);

 my $sel = menu([qw(Foo Bar Baz)]);

 menu(intro  => "M E N U",
      menu   => [["&Foo", \&do_foo],
                 ["S&ub", {
                     intro      => "S U B  M E N U",
                     menu       => [qw(Apples Oranges Exit)],
                     loop_until => 2,
                 }],
                 ["Ba&r", \&do_bar],
                 "-----",
                 ["&h", \&do_help],
                 ["(Ba&z)", \&do_baz]],
      prompt => "What (type 'h' for help)?",
      force  => 1,
     );

  my $ans = (prompt("What is your favourite colour?", "blue"));

  if (yes("Do you really want to quit?")) {
      print "Bye\n";
      exit;
  }

DESCRIPTION

This module provide the following functions:

menu( %opts )

This function will present a menu on the terminal. The return value is the index of menu item selected (or undef if no item was selected).

The following options are recognised:

   menu:    something to select from (array ref)
   intro:   heading text
   prompt:  prompt text
   force:   force something to be selected (bool)
   disabled_selectable: allow disabled items to be selected
   loop_until: show menu in a loop until a particular item is selected

The items of the menu array can either be plain text strings or an array reference containing a string and a function reference.

If a function is provided, it will be invoked if the item is selected. The value of $_ is set to the menu text before the function is called, so the same function can serve multiple entries and change it behaviour based on what it finds in $_.

If the menu text contains the letter "&" then the next letter is taken as a selector. The menu item can be selected by typing this selector. The "&" character itself is not rendered.

If the menu text is enclosed in parenthesis, then that selection is shown as disabled. Any action associated with the item is not triggered if it is selected.

If the menu text only consist of the letter "&" followed by a selector char, then the given menu item is invisible, but the associated action could still be triggered. This can be used for hidden commands or help behaviour as demonstrated in the synopsis above.

If the menu text consist of a line of at least 3 dashes, then it is taken as a separator. An action is associated with a separator line is always ignored.

If only a single argument is given to the menu() function, it is taken to be the same as the menu option.

The intro text is presented as a heading above the menu. Simple markup like *bold*and _underline_ can be used for visual effect. If not provided, no heading is used.

The prompt option replace the default "Please select an item?" text.

If the force option has a TRUE value then it prevents the menu() function from returning undef (if the user did not select any item). It also prevents the index of any disabled items from being returned. The option disabled_selectable can be used to counter that behaviour.

The loop_until option, if specified, makes the menu run in a loop until one of the indices specified by the option is selected. The value of the option should be either a single index, or a reference to an array of indices.

prompt( $question, $default )

This function will ask a question on the terminal and return the answer given. If the program is not running on a terminal then the $default is returned.

This function comes from the ActiveState::Prompt module. Refer to the documentation of that module for the complete story.

yes( $question, $default )

Will use the prompt function to ask a question and then return a TRUE value if the answer was "yes". If no $default is given it defaults to "no".

This function also comes from the ActiveState::Prompt module.

SEE ALSO

the ActiveState::Prompt manpage.


ActiveState::ModInfo - Queries about installed perl modules

  • BUGS

NAME

ActiveState::ModInfo - Queries about installed perl modules

SYNOPSIS

 use ActiveState::ModInfo qw(list_modules find_module);

DESCRIPTION

The following functions are provided:

$path = find_inc( $fname )
$path = find_inc( $fname, \@inc )

Returns the full path to the given $fname, or undef if not found.

$path = find_module( $mod )
$path = find_module( $mod, \@inc )

Returns the full path to the given module, or undef if not found.

$mod = fixup_module_case( $mod, %opts )

Will for instance change "html::parser" into "HTML::Parser". If multiple mappings are possible return $mod unchanged. The $mod is also returned unchanged if the module can't be located.

The following options are recognized:

inc => \@list

A list of directories to search for modules. If not provided it defaults to all the @INC.

prefix_only => $bool

If true assume $mod to just be a namespace. Will just look for matching directory names, not an actual .pm file.

$mod = fname2mod( $fname )

Convert an fname to a module module name. The function might return undef if the given $fname does not represent a perl module.

%modules = list_modules( %opt )

This function will locate all modules (.pm files) and return a list of module-name/file-location pairs.

The following options are recognized:

inc => \@list

A list of directories to search for modules. If not provided it defaults to all the @INC entries that point inside the perl installation directory ($Config{prefix}).

maxdepth => $n

When to give up when traversing directories, i.e. how many "::"s to allow in the module name. The default is 6. A value of 0 indicate no limit.

allowdup => $bool

If true return all occurrences or any given module. If this option is false or not provided, only the first occurrence of any given module when traversing inc will be returned. This should also be the module that perl would pick up if @INC as the given inc.

namespace => $ns

Only modules in the given namespace is returned. If $ns ends with "::" only submodules of the given namespace is returned.

$fname = mod2fname( $mod )

Convert a module name to an fname.

$fh = open_inc( $fname )
$fh = open_inc( $fname, \@inc )

Returns an opened file handle for the given fname, or undef if not found. Slightly more efficient than using the standard open() function on the path returned by find_inc(), but otherwise just the same. The file is opened in read-only mode.

$fh = open_module( $mod )
$fh = open_module( $mod, \@inc )

Returns an opened file handle for the given module, or undef if not found.

$vers = parse_version( $filename )

Return the $VERSION of a module using the official ExtUtils::MakeMaker algorithm. This is a slightly modified copy of the MakeMaker function. The main difference is that it returns a real undef if no version number is found and do it without producing any warning.

BUGS

none.


ActiveState::Path - Collection of small utility functions

  • BUGS

NAME

ActiveState::Path - Collection of small utility functions

SYNOPSIS

  use ActiveState::Path qw(find_prog);
  my $ls = find_prog("ls");

DESCRIPTION

This module provides a collection of small utility functions dealing with file paths.

The following functions are provided:

abs_path( $path )

Returns an absolute pathname denoting the same file as $path. If $path is already absolute it is returned unchanged. The $path does not have to reference an existing file or directory.

This functions differs from realpath() by only removing "." or ".." segments at the beginning of $path and by only resolving the symlinks needed to process the ".." segments correctly. The realpath() function also requires the file at $path to exist.

find_prog( $name )
find_prog( $path )

This function returns the full path to the given program if it can be located on the system. Otherwise undef is returned.

The returned path might be relative.

is_abs_path( $path )

Returns TRUE if $path is an absolute file name. This function works the same as File::Spec method file_name_is_absolute().

join_path( $base, $path )

Returns a path that will reference the same file as $path does when the current directory is $base. If $path is absolute then it is returned unchanged.

The $base should reference an existing directory. The $path does not have to refence an existing file or directory.

Any leading "." and ".." segments are removed from the $path before the paths are joined. In order to process ".." segments join_path() will need to resolve symlinks in $base, and the function might croak if this involves a symlink cycle.

path_list()

Returns the list of directories that will be searched to find programs. The path_list() is derived from the PATH environment variable. In scalar context this returns the number of paths to be searched.

On Unix when the PATH environment variable is not present then this function returns an empty list, but most shells still default to a path list like (/usr/bin, /bin).

realpath( $path )

Returns the canonicalized absolute pathname of the path passed in. All symbolic links are expanded and references to /./, /../ and extra / characters are resolved. The $path passed in must be an existing file. The function will croak if not, or if the symbolic links can't be expanded.

This differs from the Cwd::realpath() function in that $path does not have to be a directory.

rel_path( $base, $path )

Return a relative pathname that denotes the same file as $path when $base is the current directory.

The $base should reference an existing directory. The $path does not have to refence an existing file or directory.

This function differs from the File::Spec method abs2rel() in that it make sure that any ".." segments in the returned value is correct when the corresponding $base segments are symlinks. If the $base path contains symlink cycles there might not be any relative path that can be produced, and in that case rel_path() falls back to returning abs_path($path).

unsymlinked( $path )

If $path denotes a symlink expand it, otherwise return $path unchanged. The $path must reference an existing file. This function differs from realpath() by only expanding the symlink at the last segment of $path.

On systems that don't implement symlinks this function is a noop, always returning $path unchanged.

This function will croak if it's not possible to expand the symlink because of cycles.

BUGS

none.


ActiveState::Prompt - Interactive questions

  • BUGS

NAME

ActiveState::Prompt - Interactive questions

SYNOPSIS

 use ActiveState::prompt qw(prompt yes enter);

DESCRIPTION

The following functions are provided:

prompt( $question )
prompt( $question, $default )
prompt( $question, %opts )

This function will ask a question on the terminal and return the answer given. The return value will always be defined.

Options can be passed in as key/value pairs. The following options are recognized:

  default
  trim_space
  must_match
  no_match_msg
  use_default
  silent

The default is returned if the user simply press return. The default value is shown in brackets. If no default is provided then no brackets are added to the question.

If trim_space is TRUE, then any leading and trailing space in the anwer is trimmed off and any internal space is collapsed to a single space.

The must_match value is used to validate answers. It can be either a function, array or regular expression. If it is a function, then the function is called with the answer given and should return TRUE if it is to be accepted. If it is an array, then the answer must be one of the values in the array. If it is an regular expression then it must match it.

The no_match_msg is printed if the given answer does not validate as specified in must_match.

If use_default is TRUE, then no answer is read from the terminal and the default is returned (or "" if there is no default). The use_default is by default TRUE if the program is not running on a terminal or if the PERL_MM_USE_DEFAULT environment variable is TRUE.

The silent option works like use_default but it also prevent the prompt text from being printed. This forces prompt() to return the default without actually prompting.

yes( $question )
yes( $question, $default )

Will use the prompt function to ask a question and then return a TRUE value if the answer was "yes" or "y".

The $default can either be a string like "yes", "y", "no" or "n", or a boolean value in which case "yes" will be the default if TRUE and "no" otherwise. If no $default is given it defaults to "no".

enter()

Ask the use to press some key before the function returns.

BUGS

None.


ActiveState::RelocateTree - copy tree substituting paths at the same time

  • SEE ALSO
  • COPYRIGHT

NAME

ActiveState::RelocateTree - copy tree substituting paths at the same time

SYNOPSIS

   use ActiveState::RelocateTree qw(relocate);
   relocate(from => 'C:\Perl', to => 'D:\lang\perl');

DESCRIPTION

When a perl installation is copied into a new location, some of its files need to be modified accordingly. The ActiveState::RelocateTree module provide functions that helps you do this.

The following functions are provided. None of them are exported by default.

relocate( %options )

This is the main entry point that applications will use. The following options are recognized:

to

The tree which must be transformed. Unless the inplace option is true, it will copy the tree at from to to before transforming it. This option is the only one required. The other options have reasonable defaults, so in most cases this is the only option you need to provide.

from

The path from which to copy the perl tree. Defaults to $Config{prefix}, the home of the currently executing perl interpreter.

search

This is the path which will be searched for and replaced in to. This defaults to the value of from.

replace

The replacement value for search. This defaults to the value of to.

inplace

If the tree at to already exists and you just want to transform it in-situ, use this option. It skips the copying step and just transforms the tree. If from equals to, it is set to true and cannot be unset. Otherwise it defaults to false.

killorig

If you're really moving the tree, this option will remove from after copying and transforming to. Use with care! Defaults to false.

bak

While relocating the tree, relocate() creates a backup file for each file being edited. This option allows you to specify the extension of backup files. Defaults to .~1~.

savebaks

Normally relocate() deletes the backup files before returning. savebaks skips that step, leaving the backup files alone. Defaults to false (backups are deleted).

textonly

Normally relocate() edits both text and binary files. Text files are replaced using a normal search-and-replace algorithm, but binary files are NULL-padded so that all offsets remain the same. By default, textonly is false, i.e. relocate() operates on both text and binary files.

ranlib

If ranlib is true, relocate() will call ranlib on binary files which look like library files (have the $Config{_a} extension). Defaults to true.

verbose

If verbose is true, relocate() emits warning messages as it performs certain operations. This may be useful for debugging, or for command-line tools, where user feedback is a good thing.

quiet

Normally, relocate() prints out some status messages even with verbose disabled. If quiet is true, all messages (except error messages) are temporarily silenced. This option overrides verbose, so there isn't much point calling relocate() with both quiet and verbose set. By default, quiet is false.

filelist

If specified, relocate() will write a list of the files modified to filelist, one filename per line. The lines are prefixed with "B " for binary files and "T " for text files.

move_tree( $from, $to )
move_tree( $from, $to, $delete_after, $verbose )

This function will copy the directory tree at $from to the location $to.

If $delete_after is TRUE, then tree at $from will be removed after the copy completes. If $verbose is TRUE, then print a message when deleting the $from tree.

check( $file, $regexp, $is_binary )

Returns TRUE if there are occurrences of $regexp in $file. It is used by relocate() to search for files which should be edited. If $is_binary is TRUE, then read the file in binmode.

edit( $regexp, $from, $dest, $bak, $are_binary, @files )

edit() is designed to rip though a set of files, efficiently replacing $from with $dest. It operates on the whole set of files, which all need to be of the same type (binary or text). It accepts the following parameters:

$regexp

The regular expression to search for. Matching text will be replaced with $dest.

$from

The path to search for and replace. If $are_binary is true, this is used to calculate the amount of NUL-padding required to preserve the length of strings. It is not used otherwise.

$dest

The replacement string. If $are_binary is true and $dest is shorter than $from, then it inserts a NULL-pad to preserve the original length of the strings.

$bak

The extension to use when storing backup files.

$are_binary

A boolean: if true, the files are edited with binary semantics: the filehandles are set to binmode, and strings are NULL-padded. Otherwise a plain-old substitution occurs.

@files

A list of files to edit.

spongedir( $name )

Returns the spongedir associated with a particular product. The $name is the spongedir you're interested in. It's case-insensitive. The following spongedirs are known:

ppm

The sponge directory to be used in PPM packages.

thisperl

The original directory in which this copy of Perl was built. This allows relocate() to detect when a replacement path will not fit into the binary.

SEE ALSO

the reloc_perl manpage

COPYRIGHT

Copyright 2002 ActiveState Software Inc. All Rights Reserved.


ActiveState::Run - Collection of small utility functions

  • ENVIRONMENT
  • BUGS

NAME

ActiveState::Run - Collection of small utility functions

SYNOPSIS

 use ActiveState::Handy qw(run);
 run("ls -l");

DESCRIPTION

This module provides a collection of small utility functions for running external programs.

The following functions are provided:

decode_status( )
decode_status( $rc )

Will decode the given return code (defaults to $?) and return the exit value, the signal it was killed with, and if it dumped core.

In scalar context, it will return a string explaining what happened, or an empty string if no error occured.

  my $foo = `ls`;
  my $err = decode_status;
  die "ls failed: $err" if $err;

In array context, it will return a list of key/value pairs containing:

WIFEXITED

True when the status code indicates normal termination.

WEXITSTATUS

If WIFEXITED, this will contain the low-order 8 bits of the status value the child passed to exit or returned from main.

WIFSIGNALED

Non-zero if process was terminated by a signal.

WTERMSIG

If WIFSIGNALED, the terminating signal.

WIFSTOPPED

Non-zero if the process was stopped.

WSTOPSIG

If WIFSTOPPED, the signal that stopped the process.

WCOREDUMP

Nonzero if the process dumped core.

Example:

  my $foo = `ls`;
  my %err = decode_status;
  die "ls dumped core" if $err{WCOREDUMP};
run( $cmd, @args )

Works like the builtin system() but will by default print commands to stdout before it execute them and raise an exception (die) if the command fails (returns non-zero status). Like for the command specifications for make(1), you can prefix the command with "@" to suppress the echo and with "-" to suppress the status check.

The environment variables AS_RUN_SILENT and AS_RUN_PREFIX influence printing as well, see ENVIRONMENT.

shell_quote( @args )

Will quote the arguments provided so that they can be passed to the command shell without interpretation by the shell. This is useful with run() when you can't provide separate @args, e.g.:

   run(shell_quote("rm", "-f", @files) . " >dev/null");

In list context it returns the same number of values as arguments passed in. Only those arg values that need quoting will be quoted.

In scalar context it will return a single string with all the quoted @args separated by space.

In void context it will attempt inline modification of the @args passed.

ENVIRONMENT

If the AS_RUN_SILENT environment variable is TRUE, then printing of the command about to run for run() is suppressed.

If the AS_RUN_PREFIX environment variable is set, then the printed command is prefixed with the given string. If AS_RUN_SILENT is TRUE, then this value is ignored.

BUGS

none.


ActiveState::Scineplex - Perl extension to access Scineplex code lexer.

    • EXPORT
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

ActiveState::Scineplex - Perl extension to access Scineplex code lexer.

SYNOPSIS

  use ActiveState::Scineplex qw(Annotate);
  $color_info = Annotate($code, $lang, %options);

DESCRIPTION

Currently this module implements an interface consisting of one method, Annotate, which returns a scineplex-driven colorization for one or more lines of source code. It either returns a string giving the colorization or throws an exception.

    $color_info = Annotate($code, $lang, %options);

$code is a block of source-code -- lines are separated by any newline sequence.

$lang must be one of qw/perl python ruby vb xslt/.

%options include the following, with defaults in parentheses:

    outputFormat => 'html' | 'line' | 'classic' ('line')
    parsingStartState => number (0)
    DumpSource => 0 | 1 (0)
    DumpEndState => 0 | 1 (0)
    DumpFoldLevels => 0 | 1 (0)
    StopAfterDataSectionLine1 => 0 | 1 (0)

The outputFormat is the most important option. In classic mode, Annotate echos back each character on the start of a line, followed by separating white-space and its style value:

    $res = Annotate('$abc = 3;', 'perl', outputFormat => 'classic');
    print $res;

    $       12
    a       12
    b       12
    c       12
    chr(32) 0
    =       10
    chr(32) 0
    3       4
    ;       10
    chr(10) 0

The numeric values can be found in the scintilla interface file, and are different for each language.

Setting outputFormat to line gives a terser output, and represents each numeric style with the character corresponding to the style added to the ASCII value of character '0':

    $res = Annotate('$abc = 3;', 'perl', outputFormat => 'line');
    print $res;

    <<<<0:04:

Setting outputFormat to html returns an HTML-encoded string containing the original code wrapped in span tags with generic classes with names like "variable", "operator", etc. This kind of output is designed to be wrapped in pre tags, and styled with a CSS file of that contains rules like

    pre span.comments {
      color: 0x696969;
      font-style: italic;
    }

Default text is not placed in a span tag.

The parsingStartState setting should be used only when you know that the code starts with a given style, such as lines 3-5 of a multi-line string.

The DumpSource flag is used only with line output. It is intended mostly for human consumption, and produces output like the following:

    $res = Annotate('$abc = 3;', 'perl', DumpSource=>1);
    print $res;

    $abc = 3;
    <<<<0:04:

The DumpEndState is used only in line mode, and gives the styles for whichever characters constitute the line-end sequence:

    $res = Annotate(qq($abc = 3;\r\n), 'perl', DumpSource=>1, DumpEndState=>1);
    print $res;

    $abc = 3;
    <<<<0:04:00

The DumpFoldLevels is used only in line mode, and gives the fold levels as a 4-hex-digit sequence in a leading column.

    $res = Annotate(qq(if(1) {\n$abc = 3;\n}\n), 'perl', DumpSource=>1, DumpEndState=>1);
    print $res;

    2400 if(1) {
         55:4:0:
    0401 $abc = 3
         <<<<0:04
    0401 }
         :

The StopAfterDataSectionLine1 is used only for Perl code in line mode.

EXPORT

None by default.

Annotate by request.

SEE ALSO

Info on scintilla available at http://www.scintilla.org.

AUTHOR

Eric Promislow, <ericp@activestate.com>

COPYRIGHT

Copyright (C) 2005 by ActiveState Software Inc.


ActiveState::StopWatch - Time code

  • COPYRIGHT

NAME

ActiveState::StopWatch - Time code

SYNOPSIS

 use ActiveState::StopWatch qw(start_watch stop_watch read_watch real_time);

 my $w = start_watch();
 # ... do stuff ...
 print read_watch($w);
 # ... do stuff ...
 print stop_watch($w);

 # restart it
 start_watch($w);
 print stop_watch($w);

DESCRIPTION

The ActiveState::StopWatch module provide functions that can be used to measure the time spent by sections of code. The following functions are provided:

$w = start_watch()
start_watch( $w )

Without argument this function creates a new watch object. With argument it can restart a watch that has been stopped after invoking the stop_watch() function on it. If the watch provided is not stopped then its state is not affected.

$str = read_watch( $w )

This function returns a string that tells how much real, user and system time has ticked during the time the watch has been running. The string will look like this:

  r=12.5s u=4.90s s=0.55s cu=1.22s cs=0.22s

The 'cu' and 'cs' field gives time spent in children of the current process during the time the watch has been running. The child fields are not shown if they are 0.

$str = stop_watch( $w )

This function return a string of the same format as for read_watch(), but it will also stop the clock from running. This means that read_watch() will continue to return the same result. The watch can be restarted by calling start_watch() with the watch object as argument.

$r = real_time( $w )

This function returns the number of seconds of real time passed during the time the watch has been running.

Only the start_watch() and stop_watch() functions are exported by default.

COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.


ActiveState::Table - Simple table class

  • BUGS
  • SEE ALSO

NAME

ActiveState::Table - Simple table class

SYNOPSIS

 $t = ActiveState::Table->new;
 $t->add_row({ a => 1, b => 2 });
 print $t->as_csv;

DESCRIPTION

Instances of the ActiveState::Table class represent a 2 dimensional table of fields (or columns if you wish) and rows. The fields are ordered and have case-sensitive names. The rows are numbered.

The following methods are provided:

$t = ActiveState::Table->new

This creates a new empty table object.

$t->fields

This returns the current field names. In scalar context it returns the number of fields.

$t->rows

The returns the current rows. Each row is returned as reference to an array of values in the same order as the fields. The array might be shorter than the number of fields, when the trailing values are undef.

In scalar context it returns the number of rows in the table.

$t->fetchrow( $index )

This returns the given row. An array reference is returned in scalar context. The array might be shorter than the number of fields, when the trailing values are undef.

In list context the values are returned one by one. There will be as many values as there are fields in the table. Some values might be undef.

If there is no row with the given $index, then undef is returned in scalar context and the empty list in list context.

$t->fetchrow_arrayref( $index )

Same as fetchrow() but will return an array reference even in list context.

$t->fetchrow_hashref( $index )

This returns the given row. A hash reference is returned with keys corresponding to the field names and the values corresponding to the given row. The values might be undef, but a key for all the fields will exist.

If there is no row with the given $index, then undef is returned.

$t->add_field( $field )

This adds another field to the table. The field must be a string. If the field already exists it is not added again, and the add_field() call does nothing.

There is no return value.

$t->add_row( $row )

This adds another row to the table. The row must currently be a hash reference. If the hash contains new fields they are added automatically in sorted order. To enforce an order add the fields before adding rows.

There is no return value.

$t->sort( $comparator )

This will sort the rows of the table using the given $comparator function to compare elements. The $comparator is called as for perl's builtin sort function. References to the rows to compare is available in $::a and $::b in the form returned by $t->fetchrow_arrayref.

$t->as_box( %options )

This formats the table as text and returns it. The following options might be provided as key/value pairs:

   name                 | default
   ---------------------+----------
   align                | {}
   null                 | "NULL"
   show_header          | 1
   show_trailer         | 1
   box_chars            | "ascii"
   max_width            | undef
   ---------------------+----------

The align option is a hash with field names as keys and the strings "left", "right" or "center" as values. Alignment for fields not found in this hash is "left".

The box_chars is either the name of a box drawing scheme or the 11 characters to use; starting with the upper left corner and going down one row at a time to the lower right corner, and finally the horizontal and vertical line character. The current named schemes are "dos" and "unicode".

If max_width is specified it limits how wide the box can get. The longest fields are truncated until the box is no wider than the given number of characters. Truncated fields are shown with trailing "..." or "+" marker.

$t->as_csv( %options )

This formats the table as a CSV file ("comma-separated-values") and returns it. The following options might be provided as key/value pairs:

   name                 | default
   ---------------------+----------
   field_separator      | ","
   row_separator        | "\n"
   null                 | "NULL"
   show_header          | 1
   ---------------------+----------

Fields that contains the field_separator or the quote character will be quoted.

BUGS

none.

SEE ALSO

RFC 4180 and http://en.wikipedia.org/wiki/Comma-separated_values


ActiveState::Win32::Shell - Windows Shell Functions

  • COPYRIGHT

NAME

ActiveState::Win32::Shell - Windows Shell Functions

SYNOPSIS

  use ActiveState::Win32::Shell qw(BrowseDocument);

  my $document = 'C:\Program Files\ActiveState\Document.html';
  my $fragment = 'anchor_name';

  BrowseDocument($document, $fragment)
    or die "Can't browse document";

DESCRIPTION

The ActiveState::Win32::Shell module provides access to the windows shell (Explorer).

The following methods are provided:

BrowseDocument( $document, $fragment )

Opens $document in default browser and navigates to $fragment. Returns true if the operation was successful.

BrowseUrl( $url )

Opens $url in default browser. Returns true if the operation was successful.

FindExecutable( $document )

Returns the executable registered to open the $document or undef.

COPYRIGHT

Copyright 2006 ActiveState Software Inc.


Algorithm::Diff - Compute `intelligent' differences between two files / lists

  • INTRODUCTION
  • USAGE
    • LCS
    • LCS_length
    • LCSidx
    • new
    • prepare
    • diff
    • sdiff
    • compact_diff
    • traverse_sequences
    • traverse_balanced
  • KEY GENERATION FUNCTIONS
  • ERROR CHECKING
  • AUTHOR
  • LICENSE
  • MAILING LIST
  • CREDITS

NAME

Algorithm::Diff - Compute `intelligent' differences between two files / lists

SYNOPSIS

    require Algorithm::Diff;

    # This example produces traditional 'diff' output:

    my $diff = Algorithm::Diff->new( \@seq1, \@seq2 );

    $diff->Base( 1 );   # Return line numbers, not indices
    while(  $diff->Next()  ) {
        next   if  $diff->Same();
        my $sep = '';
        if(  ! $diff->Items(2)  ) {
            printf "%d,%dd%d\n",
                $diff->Get(qw( Min1 Max1 Max2 ));
        } elsif(  ! $diff->Items(1)  ) {
            printf "%da%d,%d\n",
                $diff->Get(qw( Max1 Min2 Max2 ));
        } else {
            $sep = "---\n";
            printf "%d,%dc%d,%d\n",
                $diff->Get(qw( Min1 Max1 Min2 Max2 ));
        }
        print "< $_"   for  $diff->Items(1);
        print $sep;
        print "> $_"   for  $diff->Items(2);
    }

    # Alternate interfaces:

    use Algorithm::Diff qw(
        LCS LCS_length LCSidx
        diff sdiff compact_diff
        traverse_sequences traverse_balanced );

    @lcs    = LCS( \@seq1, \@seq2 );
    $lcsref = LCS( \@seq1, \@seq2 );
    $count  = LCS_length( \@seq1, \@seq2 );

    ( $seq1idxref, $seq2idxref ) = LCSidx( \@seq1, \@seq2 );

    # Complicated interfaces:

    @diffs  = diff( \@seq1, \@seq2 );

    @sdiffs = sdiff( \@seq1, \@seq2 );

    @cdiffs = compact_diff( \@seq1, \@seq2 );

    traverse_sequences(
        \@seq1,
        \@seq2,
        {   MATCH     => \&callback1,
            DISCARD_A => \&callback2,
            DISCARD_B => \&callback3,
        },
        \&key_generator,
        @extra_args,
    );

    traverse_balanced(
        \@seq1,
        \@seq2,
        {   MATCH     => \&callback1,
            DISCARD_A => \&callback2,
            DISCARD_B => \&callback3,
            CHANGE    => \&callback4,
        },
        \&key_generator,
        @extra_args,
    );

INTRODUCTION

(by Mark-Jason Dominus)

I once read an article written by the authors of diff; they said that they worked very hard on the algorithm until they found the right one.

I think what they ended up using (and I hope someone will correct me, because I am not very confident about this) was the `longest common subsequence' method. In the LCS problem, you have two sequences of items:

    a b c d f g h j q z
    a b c d e f g i j k r x y z

and you want to find the longest sequence of items that is present in both original sequences in the same order. That is, you want to find a new sequence S which can be obtained from the first sequence by deleting some items, and from the secend sequence by deleting other items. You also want S to be as long as possible. In this case S is

    a b c d f g j z

From there it's only a small step to get diff-like output:

    e   h i   k   q r x y
    +   - +   +   - + + +

This module solves the LCS problem. It also includes a canned function to generate diff-like output.

It might seem from the example above that the LCS of two sequences is always pretty obvious, but that's not always the case, especially when the two sequences have many repeated elements. For example, consider

    a x b y c z p d q
    a b c a x b y c z

A naive approach might start by matching up the a and b that appear at the beginning of each sequence, like this:

    a x b y c         z p d q
    a   b   c a b y c z

This finds the common subsequence a b c z. But actually, the LCS is a x b y c z:

          a x b y c z p d q
    a b c a x b y c z

or

    a       x b y c z p d q
    a b c a x b y c z

USAGE

(See also the README file and several example scripts include with this module.)

This module now provides an object-oriented interface that uses less memory and is easier to use than most of the previous procedural interfaces. It also still provides several exportable functions. We'll deal with these in ascending order of difficulty: LCS, LCS_length, LCSidx, OO interface, prepare, diff, sdiff, traverse_sequences, and traverse_balanced.

LCS

Given references to two lists of items, LCS returns an array containing their longest common subsequence. In scalar context, it returns a reference to such a list.

    @lcs    = LCS( \@seq1, \@seq2 );
    $lcsref = LCS( \@seq1, \@seq2 );

LCS may be passed an optional third parameter; this is a CODE reference to a key generation function. See KEY GENERATION FUNCTIONS.

    @lcs    = LCS( \@seq1, \@seq2, \&keyGen, @args );
    $lcsref = LCS( \@seq1, \@seq2, \&keyGen, @args );

Additional parameters, if any, will be passed to the key generation routine.

LCS_length

This is just like LCS except it only returns the length of the longest common subsequence. This provides a performance gain of about 9% compared to LCS.

LCSidx

Like LCS except it returns references to two arrays. The first array contains the indices into @seq1 where the LCS items are located. The second array contains the indices into @seq2 where the LCS items are located.

Therefore, the following three lists will contain the same values:

    my( $idx1, $idx2 ) = LCSidx( \@seq1, \@seq2 );
    my @list1 = @seq1[ @$idx1 ];
    my @list2 = @seq2[ @$idx2 ];
    my @list3 = LCS( \@seq1, \@seq2 );

new

    $diff = Algorithm::Diffs->new( \@seq1, \@seq2 );
    $diff = Algorithm::Diffs->new( \@seq1, \@seq2, \%opts );

new computes the smallest set of additions and deletions necessary to turn the first sequence into the second and compactly records them in the object.

You use the object to iterate over hunks, where each hunk represents a contiguous section of items which should be added, deleted, replaced, or left unchanged.

The following summary of all of the methods looks a lot like Perl code but some of the symbols have different meanings:

    [ ]     Encloses optional arguments
    :       Is followed by the default value for an optional argument
    |       Separates alternate return results

Method summary:

    $obj        = Algorithm::Diff->new( \@seq1, \@seq2, [ \%opts ] );
    $pos        = $obj->Next(  [ $count : 1 ] );
    $revPos     = $obj->Prev(  [ $count : 1 ] );
    $obj        = $obj->Reset( [ $pos : 0 ] );
    $copy       = $obj->Copy(  [ $pos, [ $newBase ] ] );
    $oldBase    = $obj->Base(  [ $newBase ] );

Note that all of the following methods die if used on an object that is "reset" (not currently pointing at any hunk).

    $bits       = $obj->Diff(  );
    @items|$cnt = $obj->Same(  );
    @items|$cnt = $obj->Items( $seqNum );
    @idxs |$cnt = $obj->Range( $seqNum, [ $base ] );
    $minIdx     = $obj->Min(   $seqNum, [ $base ] );
    $maxIdx     = $obj->Max(   $seqNum, [ $base ] );
    @values     = $obj->Get(   @names );

Passing in undef for an optional argument is always treated the same as if no argument were passed in.

Next
    $pos = $diff->Next();    # Move forward 1 hunk
    $pos = $diff->Next( 2 ); # Move forward 2 hunks
    $pos = $diff->Next(-5);  # Move backward 5 hunks

Next moves the object to point at the next hunk. The object starts out "reset", which means it isn't pointing at any hunk. If the object is reset, then Next() moves to the first hunk.

Next returns a true value iff the move didn't go past the last hunk. So Next(0) will return true iff the object is not reset.

Actually, Next returns the object's new position, which is a number between 1 and the number of hunks (inclusive), or returns a false value.

Prev

Prev($N) is almost identical to Next(-$N); it moves to the $Nth previous hunk. On a 'reset' object, Prev() [and Next(-1)] move to the last hunk.

The position returned by Prev is relative to the end of the hunks; -1 for the last hunk, -2 for the second-to-last, etc.

Reset
    $diff->Reset();     # Reset the object's position
    $diff->Reset($pos); # Move to the specified hunk
    $diff->Reset(1);    # Move to the first hunk
    $diff->Reset(-1);   # Move to the last hunk

Reset returns the object, so, for example, you could use $diff->Reset()->Next(-1) to get the number of hunks.

Copy
    $copy = $diff->Copy( $newPos, $newBase );

Copy returns a copy of the object. The copy and the orignal object share most of their data, so making copies takes very little memory. The copy maintains its own position (separate from the original), which is the main purpose of copies. It also maintains its own base.

By default, the copy's position starts out the same as the original object's position. But Copy takes an optional first argument to set the new position, so the following three snippets are equivalent:

    $copy = $diff->Copy($pos);

    $copy = $diff->Copy();
    $copy->Reset($pos);

    $copy = $diff->Copy()->Reset($pos);

Copy takes an optional second argument to set the base for the copy. If you wish to change the base of the copy but leave the position the same as in the original, here are two equivalent ways:

    $copy = $diff->Copy();
    $copy->Base( 0 );

    $copy = $diff->Copy(undef,0);

Here are two equivalent way to get a "reset" copy:

    $copy = $diff->Copy(0);

    $copy = $diff->Copy()->Reset();
Diff
    $bits = $obj->Diff();

Diff returns a true value iff the current hunk contains items that are different between the two sequences. It actually returns one of the follow 4 values:

  1. 3==(1|2). This hunk contains items from @seq1 and the items from @seq2 that should replace them. Both sequence 1 and 2 contain changed items so both the 1 and 2 bits are set.

  2. This hunk only contains items from @seq2 that should be inserted (not items from @seq1). Only sequence 2 contains changed items so only the 2 bit is set.

  3. This hunk only contains items from @seq1 that should be deleted (not items from @seq2). Only sequence 1 contains changed items so only the 1 bit is set.

  4. This means that the items in this hunk are the same in both sequences. Neither sequence 1 nor 2 contain changed items so neither the 1 nor the 2 bits are set.

Same

Same returns a true value iff the current hunk contains items that are the same in both sequences. It actually returns the list of items if they are the same or an emty list if they aren't. In a scalar context, it returns the size of the list.

Items
    $count = $diff->Items(2);
    @items = $diff->Items($seqNum);

Items returns the (number of) items from the specified sequence that are part of the current hunk.

If the current hunk contains only insertions, then $diff->Items(1) will return an empty list (0 in a scalar conext). If the current hunk contains only deletions, then $diff->Items(2) will return an empty list (0 in a scalar conext).

If the hunk contains replacements, then both $diff->Items(1) and $diff->Items(2) will return different, non-empty lists.

Otherwise, the hunk contains identical items and all of the following will return the same lists:

    @items = $diff->Items(1);
    @items = $diff->Items(2);
    @items = $diff->Same();
Range
    $count = $diff->Range( $seqNum );
    @indices = $diff->Range( $seqNum );
    @indices = $diff->Range( $seqNum, $base );

Range is like Items except that it returns a list of indices to the items rather than the items themselves. By default, the index of the first item (in each sequence) is 0 but this can be changed by calling the Base method. So, by default, the following two snippets return the same lists:

    @list = $diff->Items(2);
    @list = @seq2[ $diff->Range(2) ];

You can also specify the base to use as the second argument. So the following two snippets always return the same lists:

    @list = $diff->Items(1);
    @list = @seq1[ $diff->Range(1,0) ];
Base
    $curBase = $diff->Base();
    $oldBase = $diff->Base($newBase);

Base sets and/or returns the current base (usually 0 or 1) that is used when you request range information. The base defaults to 0 so that range information is returned as array indices. You can set the base to 1 if you want to report traditional line numbers instead.

Min
    $min1 = $diff->Min(1);
    $min = $diff->Min( $seqNum, $base );

Min returns the first value that Range would return (given the same arguments) or returns undef if Range would return an empty list.

Max

Max returns the last value that Range would return or undef.

Get
    ( $n, $x, $r ) = $diff->Get(qw( min1 max1 range1 ));
    @values = $diff->Get(qw( 0min2 1max2 range2 same base ));

Get returns one or more scalar values. You pass in a list of the names of the values you want returned. Each name must match one of the following regexes:

    /^(-?\d+)?(min|max)[12]$/i
    /^(range[12]|same|diff|base)$/i

The 1 or 2 after a name says which sequence you want the information for (and where allowed, it is required). The optional number before "min" or "max" is the base to use. So the following equalities hold:

    $diff->Get('min1') == $diff->Min(1)
    $diff->Get('0min2') == $diff->Min(2,0)

Using Get in a scalar context when you've passed in more than one name is a fatal error (die is called).

prepare

Given a reference to a list of items, prepare returns a reference to a hash which can be used when comparing this sequence to other sequences with LCS or LCS_length.

    $prep = prepare( \@seq1 );
    for $i ( 0 .. 10_000 )
    {
        @lcs = LCS( $prep, $seq[$i] );
        # do something useful with @lcs
    }

prepare may be passed an optional third parameter; this is a CODE reference to a key generation function. See KEY GENERATION FUNCTIONS.

    $prep = prepare( \@seq1, \&keyGen );
    for $i ( 0 .. 10_000 )
    {
        @lcs = LCS( $seq[$i], $prep, \&keyGen );
        # do something useful with @lcs
    }

Using prepare provides a performance gain of about 50% when calling LCS many times compared with not preparing.

diff

    @diffs     = diff( \@seq1, \@seq2 );
    $diffs_ref = diff( \@seq1, \@seq2 );

diff computes the smallest set of additions and deletions necessary to turn the first sequence into the second, and returns a description of these changes. The description is a list of hunks; each hunk represents a contiguous section of items which should be added, deleted, or replaced. (Hunks containing unchanged items are not included.)

The return value of diff is a list of hunks, or, in scalar context, a reference to such a list. If there are no differences, the list will be empty.

Here is an example. Calling diff for the following two sequences:

    a b c e h j l m n p
    b c d e f j k l m r s t

would produce the following list:

    (
      [ [ '-', 0, 'a' ] ],
      [ [ '+', 2, 'd' ] ],
      [ [ '-', 4, 'h' ],
        [ '+', 4, 'f' ] ],
      [ [ '+', 6, 'k' ] ],
      [ [ '-',  8, 'n' ],
        [ '-',  9, 'p' ],
        [ '+',  9, 'r' ],
        [ '+', 10, 's' ],
        [ '+', 11, 't' ] ],
    )

There are five hunks here. The first hunk says that the a at position 0 of the first sequence should be deleted (-). The second hunk says that the d at position 2 of the second sequence should be inserted (+). The third hunk says that the h at position 4 of the first sequence should be removed and replaced with the f from position 4 of the second sequence. And so on.

diff may be passed an optional third parameter; this is a CODE reference to a key generation function. See KEY GENERATION FUNCTIONS.

Additional parameters, if any, will be passed to the key generation routine.

sdiff

    @sdiffs     = sdiff( \@seq1, \@seq2 );
    $sdiffs_ref = sdiff( \@seq1, \@seq2 );

sdiff computes all necessary components to show two sequences and their minimized differences side by side, just like the Unix-utility sdiff does:

    same             same
    before     |     after
    old        <     -
    -          >     new

It returns a list of array refs, each pointing to an array of display instructions. In scalar context it returns a reference to such a list. If there are no differences, the list will have one entry per item, each indicating that the item was unchanged.

Display instructions consist of three elements: A modifier indicator (+: Element added, -: Element removed, u: Element unmodified, c: Element changed) and the value of the old and new elements, to be displayed side-by-side.

An sdiff of the following two sequences:

    a b c e h j l m n p
    b c d e f j k l m r s t

results in

    ( [ '-', 'a', ''  ],
      [ 'u', 'b', 'b' ],
      [ 'u', 'c', 'c' ],
      [ '+', '',  'd' ],
      [ 'u', 'e', 'e' ],
      [ 'c', 'h', 'f' ],
      [ 'u', 'j', 'j' ],
      [ '+', '',  'k' ],
      [ 'u', 'l', 'l' ],
      [ 'u', 'm', 'm' ],
      [ 'c', 'n', 'r' ],
      [ 'c', 'p', 's' ],
      [ '+', '',  't' ],
    )

sdiff may be passed an optional third parameter; this is a CODE reference to a key generation function. See KEY GENERATION FUNCTIONS.

Additional parameters, if any, will be passed to the key generation routine.

compact_diff

compact_diff is much like sdiff except it returns a much more compact description consisting of just one flat list of indices. An example helps explain the format:

    my @a = qw( a b c   e  h j   l m n p      );
    my @b = qw(   b c d e f  j k l m    r s t );
    @cdiff = compact_diff( \@a, \@b );
    # Returns:
    #   @a      @b       @a       @b
    #  start   start   values   values
    (    0,      0,   #       =
         0,      0,   #    a  !
         1,      0,   #  b c  =  b c
         3,      2,   #       !  d
         3,      3,   #    e  =  e
         4,      4,   #    f  !  h
         5,      5,   #    j  =  j
         6,      6,   #       !  k
         6,      7,   #  l m  =  l m
         8,      9,   #  n p  !  r s t
        10,     12,   #
    );

The 0th, 2nd, 4th, etc. entries are all indices into @seq1 (@a in the above example) indicating where a hunk begins. The 1st, 3rd, 5th, etc. entries are all indices into @seq2 (@b in the above example) indicating where the same hunk begins.

So each pair of indices (except the last pair) describes where a hunk begins (in each sequence). Since each hunk must end at the item just before the item that starts the next hunk, the next pair of indices can be used to determine where the hunk ends.

So, the first 4 entries (0..3) describe the first hunk. Entries 0 and 1 describe where the first hunk begins (and so are always both 0). Entries 2 and 3 describe where the next hunk begins, so subtracting 1 from each tells us where the first hunk ends. That is, the first hunk contains items $diff[0] through $diff[2] - 1 of the first sequence and contains items $diff[1] through $diff[3] - 1 of the second sequence.

In other words, the first hunk consists of the following two lists of items:

               #  1st pair     2nd pair
               # of indices   of indices
                   @list1 = @a[ $cdiff[0] .. $cdiff[2]-1 ];
                   @list2 = @b[ $cdiff[1] .. $cdiff[3]-1 ];
               # Hunk start   Hunk end

Note that the hunks will always alternate between those that are part of the LCS (those that contain unchanged items) and those that contain changes. This means that all we need to be told is whether the first hunk is a 'same' or 'diff' hunk and we can determine which of the other hunks contain 'same' items or 'diff' items.

By convention, we always make the first hunk contain unchanged items. So the 1st, 3rd, 5th, etc. hunks (all odd-numbered hunks if you start counting from 1) all contain unchanged items. And the 2nd, 4th, 6th, etc. hunks (all even-numbered hunks if you start counting from 1) all contain changed items.

Since @a and @b don't begin with the same value, the first hunk in our example is empty (otherwise we'd violate the above convention). Note that the first 4 index values in our example are all zero. Plug these values into our previous code block and we get:

    @hunk1a = @a[ 0 .. 0-1 ];
    @hunk1b = @b[ 0 .. 0-1 ];

And 0..-1 returns the empty list.

Move down one pair of indices (2..5) and we get the offset ranges for the second hunk, which contains changed items.

Since @diff[2..5] contains (0,0,1,0) in our example, the second hunk consists of these two lists of items:

        @hunk2a = @a[ $cdiff[2] .. $cdiff[4]-1 ];
        @hunk2b = @b[ $cdiff[3] .. $cdiff[5]-1 ];
            # or
        @hunk2a = @a[ 0 .. 1-1 ];
        @hunk2b = @b[ 0 .. 0-1 ];
            # or
        @hunk2a = @a[ 0 .. 0 ];
        @hunk2b = @b[ 0 .. -1 ];
            # or
        @hunk2a = ( 'a' );
        @hunk2b = ( );

That is, we would delete item 0 ('a') from @a.

Since @diff[4..7] contains (1,0,3,2) in our example, the third hunk consists of these two lists of items:

        @hunk3a = @a[ $cdiff[4] .. $cdiff[6]-1 ];
        @hunk3a = @b[ $cdiff[5] .. $cdiff[7]-1 ];
            # or
        @hunk3a = @a[ 1 .. 3-1 ];
        @hunk3a = @b[ 0 .. 2-1 ];
            # or
        @hunk3a = @a[ 1 .. 2 ];
        @hunk3a = @b[ 0 .. 1 ];
            # or
        @hunk3a = qw( b c );
        @hunk3a = qw( b c );

Note that this third hunk contains unchanged items as our convention demands.

You can continue this process until you reach the last two indices, which will always be the number of items in each sequence. This is required so that subtracting one from each will give you the indices to the last items in each sequence.

traverse_sequences

traverse_sequences used to be the most general facility provided by this module (the new OO interface is more powerful and much easier to use).

Imagine that there are two arrows. Arrow A points to an element of sequence A, and arrow B points to an element of the sequence B. Initially, the arrows point to the first elements of the respective sequences. traverse_sequences will advance the arrows through the sequences one element at a time, calling an appropriate user-specified callback function before each advance. It willadvance the arrows in such a way that if there are equal elements $A[$i] and $B[$j] which are equal and which are part of the LCS, there will be some moment during the execution of traverse_sequences when arrow A is pointing to $A[$i] and arrow B is pointing to $B[$j]. When this happens, traverse_sequences will call the MATCH callback function and then it will advance both arrows.

Otherwise, one of the arrows is pointing to an element of its sequence that is not part of the LCS. traverse_sequences will advance that arrow and will call the DISCARD_A or the DISCARD_B callback, depending on which arrow it advanced. If both arrows point to elements that are not part of the LCS, then traverse_sequences will advance one of them and call the appropriate callback, but it is not specified which it will call.

The arguments to traverse_sequences are the two sequences to traverse, and a hash which specifies the callback functions, like this:

    traverse_sequences(
        \@seq1, \@seq2,
        {   MATCH => $callback_1,
            DISCARD_A => $callback_2,
            DISCARD_B => $callback_3,
        }
    );

Callbacks for MATCH, DISCARD_A, and DISCARD_B are invoked with at least the indices of the two arrows as their arguments. They are not expected to return any values. If a callback is omitted from the table, it is not called.

Callbacks for A_FINISHED and B_FINISHED are invoked with at least the corresponding index in A or B.

If arrow A reaches the end of its sequence, before arrow B does, traverse_sequences will call the A_FINISHED callback when it advances arrow B, if there is such a function; if not it will call DISCARD_B instead. Similarly if arrow B finishes first. traverse_sequences returns when both arrows are at the ends of their respective sequences. It returns true on success and false on failure. At present there is no way to fail.

traverse_sequences may be passed an optional fourth parameter; this is a CODE reference to a key generation function. See KEY GENERATION FUNCTIONS.

Additional parameters, if any, will be passed to the key generation function.

If you want to pass additional parameters to your callbacks, but don't need a custom key generation function, you can get the default by passing undef:

    traverse_sequences(
        \@seq1, \@seq2,
        {   MATCH => $callback_1,
            DISCARD_A => $callback_2,
            DISCARD_B => $callback_3,
        },
        undef,     # default key-gen
        $myArgument1,
        $myArgument2,
        $myArgument3,
    );

traverse_sequences does not have a useful return value; you are expected to plug in the appropriate behavior with the callback functions.

traverse_balanced

traverse_balanced is an alternative to traverse_sequences. It uses a different algorithm to iterate through the entries in the computed LCS. Instead of sticking to one side and showing element changes as insertions and deletions only, it will jump back and forth between the two sequences and report changes occurring as deletions on one side followed immediatly by an insertion on the other side.

In addition to the DISCARD_A, DISCARD_B, and MATCH callbacks supported by traverse_sequences, traverse_balanced supports a CHANGE callback indicating that one element got replaced by another:

    traverse_balanced(
        \@seq1, \@seq2,
        {   MATCH => $callback_1,
            DISCARD_A => $callback_2,
            DISCARD_B => $callback_3,
            CHANGE    => $callback_4,
        }
    );

If no CHANGE callback is specified, traverse_balanced will map CHANGE events to DISCARD_A and DISCARD_B actions, therefore resulting in a similar behaviour as traverse_sequences with different order of events.

traverse_balanced might be a bit slower than traverse_sequences, noticable only while processing huge amounts of data.

The sdiff function of this module is implemented as call to traverse_balanced.

traverse_balanced does not have a useful return value; you are expected to plug in the appropriate behavior with the callback functions.

KEY GENERATION FUNCTIONS

Most of the functions accept an optional extra parameter. This is a CODE reference to a key generating (hashing) function that should return a string that uniquely identifies a given element. It should be the case that if two elements are to be considered equal, their keys should be the same (and the other way around). If no key generation function is provided, the key will be the element as a string.

By default, comparisons will use "eq" and elements will be turned into keys using the default stringizing operator '""'.

Where this is important is when you're comparing something other than strings. If it is the case that you have multiple different objects that should be considered to be equal, you should supply a key generation function. Otherwise, you have to make sure that your arrays contain unique references.

For instance, consider this example:

    package Person;

    sub new
    {
        my $package = shift;
        return bless { name => '', ssn => '', @_ }, $package;
    }

    sub clone
    {
        my $old = shift;
        my $new = bless { %$old }, ref($old);
    }

    sub hash
    {
        return shift()->{'ssn'};
    }

    my $person1 = Person->new( name => 'Joe', ssn => '123-45-6789' );
    my $person2 = Person->new( name => 'Mary', ssn => '123-47-0000' );
    my $person3 = Person->new( name => 'Pete', ssn => '999-45-2222' );
    my $person4 = Person->new( name => 'Peggy', ssn => '123-45-9999' );
    my $person5 = Person->new( name => 'Frank', ssn => '000-45-9999' );

If you did this:

    my $array1 = [ $person1, $person2, $person4 ];
    my $array2 = [ $person1, $person3, $person4, $person5 ];
    Algorithm::Diff::diff( $array1, $array2 );

everything would work out OK (each of the objects would be converted into a string like "Person=HASH(0x82425b0)" for comparison).

But if you did this:

    my $array1 = [ $person1, $person2, $person4 ];
    my $array2 = [ $person1, $person3, $person4->clone(), $person5 ];
    Algorithm::Diff::diff( $array1, $array2 );

$person4 and $person4->clone() (which have the same name and SSN) would be seen as different objects. If you wanted them to be considered equivalent, you would have to pass in a key generation function:

    my $array1 = [ $person1, $person2, $person4 ];
    my $array2 = [ $person1, $person3, $person4->clone(), $person5 ];
    Algorithm::Diff::diff( $array1, $array2, \&Person::hash );

This would use the 'ssn' field in each Person as a comparison key, and so would consider $person4 and $person4->clone() as equal.

You may also pass additional parameters to the key generation function if you wish.

ERROR CHECKING

If you pass these routines a non-reference and they expect a reference, they will die with a message.

AUTHOR

This version released by Tye McQueen (http://perlmonks.org/?node=tye).

LICENSE

Parts Copyright (c) 2000-2004 Ned Konz. All rights reserved. Parts by Tye McQueen.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl.

MAILING LIST

Mark-Jason still maintains a mailing list. To join a low-volume mailing list for announcements related to diff and Algorithm::Diff, send an empty mail message to mjd-perl-diff-request@plover.com.

CREDITS

Versions through 0.59 (and much of this documentation) were written by:

Mark-Jason Dominus, mjd-perl-diff@plover.com

This version borrows some documentation and routine names from Mark-Jason's, but Diff.pm's code was completely replaced.

This code was adapted from the Smalltalk code of Mario Wolczko <mario@wolczko.com>, which is available at ftp://st.cs.uiuc.edu/pub/Smalltalk/MANCHESTER/manchester/4.0/diff.st

sdiff and traverse_balanced were written by Mike Schilli <m@perlmeister.com>.

The algorithm is that described in A Fast Algorithm for Computing Longest Common Subsequences, CACM, vol.20, no.5, pp.350-353, May 1977, with a few minor improvements to improve the speed.

Much work was done by Ned Konz (perl@bike-nomad.com)

The OO interface and some other changes are by Tye McQueen.


Algorithm::DiffOld - Compute `intelligent' differences between two files / lists but use the old interface.

  • NOTE
  • SYNOPSIS
  • COMPARISON FUNCTIONS

NAME

Algorithm::DiffOld - Compute `intelligent' differences between two files / lists but use the old (<=0.59) interface.

NOTE

This has been provided as part of the Algorithm::Diff package by Ned Konz. This particular module is ONLY for people who HAVE to have the old interface, which uses a comparison function rather than a key generating function.

Because each of the lines in one array have to be compared with each of the lines in the other array, this does M*N comparisions. This can be very slow. I clocked it at taking 18 times as long as the stock version of Algorithm::Diff for a 4000-line file. It will get worse quadratically as array sizes increase.

SYNOPSIS

  use Algorithm::DiffOld qw(diff LCS traverse_sequences);

  @lcs    = LCS( \@seq1, \@seq2, $comparison_function );

  $lcsref = LCS( \@seq1, \@seq2, $comparison_function );

  @diffs = diff( \@seq1, \@seq2, $comparison_function );

  traverse_sequences( \@seq1, \@seq2,
                     { MATCH => $callback,
                       DISCARD_A => $callback,
                       DISCARD_B => $callback,
                     },
                     $comparison_function );

COMPARISON FUNCTIONS

Each of the main routines should be passed a comparison function. If you aren't passing one in, use Algorithm::Diff instead.

These functions should return a true value when two items should compare as equal.

For instance,

  @lcs    = LCS( \@seq1, \@seq2, sub { my ($a, $b) = @_; $a eq $b } );

but if that is all you're doing with your comparison function, just use Algorithm::Diff and let it do this (this is its default).

Or:

  sub someFunkyComparisonFunction
  {
        my ($a, $b) = @_;
        $a =~ m{$b};
  }

  @diffs = diff( \@lines, \@patterns, \&someFunkyComparisonFunction );

which would allow you to diff an array @lines which consists of text lines with an array @patterns which consists of regular expressions.

This is actually the reason I wrote this version -- there is no way to do this with a key generation function as in the stock Algorithm::Diff.


AnyDBM_File - provide framework for multiple DBMs

    • DBM Comparisons
  • SEE ALSO

NAME

AnyDBM_File - provide framework for multiple DBMs

NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File - various DBM implementations

SYNOPSIS

    use AnyDBM_File;

DESCRIPTION

This module is a "pure virtual base class"--it has nothing of its own. It's just there to inherit from one of the various DBM packages. It prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See DB_File), GDBM, SDBM (which is always there--it comes with Perl), and finally ODBM. This way old programs that used to use NDBM via dbmopen() can still do so, but new ones can reorder @ISA:

    BEGIN { @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File) }
    use AnyDBM_File;

Having multiple DBM implementations makes it trivial to copy database formats:

    use POSIX; use NDBM_File; use DB_File;
    tie %newhash,  'DB_File', $new_filename, O_CREAT|O_RDWR;
    tie %oldhash,  'NDBM_File', $old_filename, 1, 0;
    %newhash = %oldhash;

DBM Comparisons

Here's a partial table of features the different packages offer:

                         odbm    ndbm    sdbm    gdbm    bsd-db
                         ----    ----    ----    ----    ------
 Linkage comes w/ perl   yes     yes     yes     yes     yes
 Src comes w/ perl       no      no      yes     no      no
 Comes w/ many unix os   yes     yes[0]  no      no      no
 Builds ok on !unix      ?       ?       yes     yes     ?
 Code Size               ?       ?       small   big     big
 Database Size           ?       ?       small   big?    ok[1]
 Speed                   ?       ?       slow    ok      fast
 FTPable                 no      no      yes     yes     yes
 Easy to build          N/A     N/A      yes     yes     ok[2]
 Size limits             1k      4k      1k[3]   none    none
 Byte-order independent  no      no      no      no      yes
 Licensing restrictions  ?       ?       no      yes     no
[0]

on mixed universe machines, may be in the bsd compat library, which is often shunned.

[1]

Can be trimmed if you compile for one access method.

[2]

See DB_File. Requires symbolic links.

[3]

By default, but can be redefined.

SEE ALSO

dbm(3), ndbm(3), DB_File(3), the perldbmfilter manpage


Apache::JSONRPC - mod_perl-based JSON-RPC server

  • TRANSITION PLAN
  • DESCRIPTION
  • TODO
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

 Apache::JSONRPC - mod_perl-based JSON-RPC server

SYNOPSIS

httpd.conf or htaccess

 SetHandler perl-script
 PerlHandler Apache::JSONRPC
 PerlModule MyApp::Test
 PerlSetVar dispatch_to "MyApp::Test, MyApp::Test2"
 # URL path base
 # PerlSetVar dispatch_to "MyApp/Test, MyApp/Test2"
 PerlSendHeader On

TRANSITION PLAN

In the next large update version, JSON and JSONRPC modules are split.

  JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
  JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
  Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.

DESCRIPTION

This module inherites JSONRPC::Transport::HTTP and provides JSON-RPC (http://json-rpc.org/) server.

The ideas was borrowed from the SOAP::Lite manpage, the Apache::SOAP manpage.

Currently the modlue(JSONRPC::Transport::HTTP::Apache) does not support Apache2.

TODO

Apache2 support.

SEE ALSO

the SOAP::Lite manpage,
the Apache::SOAP manpage,
the JSONRPC::Transport::HTTP manpage,
http://json-rpc.org/,

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Apache::SOAP - mod_perl-based SOAP server with minimum configuration

  • CONFIGURATION
  • DEPENDENCIES
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

Apache::SOAP - mod_perl-based SOAP server with minimum configuration

SYNOPSIS

httpd.conf (Location), directory-based access
  <Location /mod_soap>
    SetHandler perl-script
    PerlHandler Apache::SOAP
    PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
    PerlSetVar options "compress_threshold => 10000"
  </Location>
httpd.conf (Files), file-based access
  <FilesMatch "\.soap$">
    SetHandler perl-script
    PerlHandler Apache::SOAP
    PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
    PerlSetVar options "compress_threshold => 10000"
  </FilesMatch>
.htaccess, directory-based access
  SetHandler perl-script
  PerlHandler Apache::SOAP
  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
  PerlSetVar options "compress_threshold => 10000"

DESCRIPTION

This Apache Perl module provides the ability to add support for SOAP (Simple Object Access Protocol) protocol with easy configuration (either in .conf or in .htaccess file). This functionality should give you lightweight option for hosting SOAP services and greatly simplify configuration aspects. This module inherites functionality from SOAP::Transport::HTTP::Apache component of SOAP::Lite module.

CONFIGURATION

The module can be placed in <Location>, <Directory>, <Files>, <FilesMatch> directives in main server configuration areas or directly in .htaccess file.

All parameters should be quoted and can be separated with commas or spaces for lists ("a, b, c") and with 'wide arrows' and commas for hash parameters ("key1 => value1, key2 => value2").

All options that you can find in SOAP::Transport::HTTP::Apache component are available for configuration. Here is the description of most important ones.

dispatch_to (LIST)

Specifies path to directory that contains Perl modules you'd like to give access to, or just list of modules (for preloaded modules).

  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
options (HASH)

Specifies list of options for your module, for example threshold for compression. Future versions will support more options. See SOAP::Transport::HTTP documentation for other options.

  PerlSetVar options "compress_threshold => 10000"

DEPENDENCIES

 SOAP::Lite
 mod_perl

SEE ALSO

 SOAP::Transport::HTTP::Apache for implementation details,
 SOAP::Lite for general information, and
 F<examples/server/mod_soap.htaccess> for .htaccess example

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


Apache::Test - Test.pm wrapper with helpers for testing Apache

  • FUNCTIONS
  • Additional Configuration Variables
  • Test::More Integration
  • Apache::TestToString Class
  • SEE ALSO
  • AUTHOR

NAME

Apache::Test - Test.pm wrapper with helpers for testing Apache

SYNOPSIS

    use Apache::Test;

DESCRIPTION

Apache::Test is a wrapper around the standard Test.pm with helpers for testing an Apache server.

FUNCTIONS

plan

This function is a wrapper around Test::plan:

    plan tests => 3;

just like using Test.pm, plan 3 tests.

If the first argument is an object, such as an Apache::RequestRec object, STDOUT will be tied to it. The Test.pm global state will also be refreshed by calling Apache::Test::test_pm_refresh. For example:

    plan $r, tests => 7;

ties STDOUT to the request object $r.

If there is a last argument that doesn't belong to Test::plan (which expects a balanced hash), it's used to decide whether to continue with the test or to skip it all-together. This last argument can be:

  • a SCALAR

    the test is skipped if the scalar has a false value. For example:

      plan tests => 5, 0;

    But this won't hint the reason for skipping therefore it's better to use need():

      plan tests => 5,
      need 'LWP',
           { "not Win32" => sub { $^O eq 'MSWin32'} };

    see need() for more info.

  • an ARRAY reference

    need_module() is called for each value in this array. The test is skipped if need_module() returns false (which happens when at least one C or Perl module from the list cannot be found).

    Watch out for case insensitive file systems or duplicate modules with the same name. I.E. If you mean mod_env.c need_module('mod_env.c') Not need_module('env')

  • a CODE reference

    the tests will be skipped if the function returns a false value. For example:

        plan tests => 5, need_lwp;

    the test will be skipped if LWP is not available

All other arguments are passed through to Test::plan as is.

ok

Same as Test::ok, see Test.pm documentation.

sok

Allows to skip a sub-test, controlled from the command line. The argument to sok() is a CODE reference or a BLOCK whose return value will be passed to ok(). By default behaves like ok(). If all sub-tests of the same test are written using sok(), and a test is executed as:

  % ./t/TEST -v skip_subtest 1 3

only sub-tests 1 and 3 will be run, the rest will be skipped.

skip

Same as Test::skip, see Test.pm documentation.

test_pm_refresh

Normally called by Apache::Test::plan, this function will refresh the global state maintained by Test.pm, allowing plan and friends to be called more than once per-process. This function is not exported.

Functions that can be used as a last argument to the extended plan(). Note that for each need_* function there is a have_* equivalent that performs the exact same function except that it is designed to be used outside of plan(). need_* functions have the side effect of generating skip messages, if the test is skipped. have_* functions don't have this side effect. In other words, use need_apache() with plan() to decide whether a test will run, but have_apache() within test logic to adjust expectations based on older or newer server versions.

need_http11
  plan tests => 5, need_http11;

Require HTTP/1.1 support.

need_ssl
  plan tests => 5, need_ssl;

Require SSL support.

Not exported by default.

need_lwp
  plan tests => 5, need_lwp;

Require LWP support.

need_cgi
  plan tests => 5, need_cgi;

Requires mod_cgi or mod_cgid to be installed.

need_php
  plan tests => 5, need_php;

Requires a PHP module to be installed (version 4 or 5).

need_php4
  plan tests => 5, need_php4;

Requires a PHP version 4 module to be installed.

need_imagemap
  plan tests => 5, need_imagemap;

Requires a mod_imagemap or mod_imap be installed

need_apache
  plan tests => 5, need_apache 2;

Requires Apache 2nd generation httpd-2.x.xx

  plan tests => 5, need_apache 1;

Requires Apache 1st generation (apache-1.3.xx)

See also need_min_apache_version().

need_min_apache_version

Used to require a minimum version of Apache.

For example:

  plan tests => 5, need_min_apache_version("2.0.40");

requires Apache 2.0.40 or higher.

need_apache_version

Used to require a specific version of Apache.

For example:

  plan tests => 5, need_apache_version("2.0.40");

requires Apache 2.0.40.

need_apache_mpm

Used to require a specific Apache Multi-Processing Module.

For example:

  plan tests => 5, need_apache_mpm('prefork');

requires the prefork MPM.

need_perl
  plan tests => 5, need_perl 'iolayers';
  plan tests => 5, need_perl 'ithreads';

Requires a perl extension to be present, or perl compiled with certain capabilities.

The first example tests whether PerlIO is available, the second whether:

  $Config{useithread} eq 'define';
need_min_perl_version

Used to require a minimum version of Perl.

For example:

  plan tests => 5, need_min_perl_version("5.008001");

requires Perl 5.8.1 or higher.

need_module
  plan tests => 5, need_module 'CGI';
  plan tests => 5, need_module qw(CGI Find::File);
  plan tests => 5, need_module ['CGI', 'Find::File', 'cgid'];

Requires Apache C and Perl modules. The function accept a list of arguments or a reference to a list.

In case of C modules, depending on how the module name was passed it may pass through the following completions:

  1. need_module 'proxy_http.c'

    If there is the .c extension, the module name will be looked up as is, i.e. 'proxy_http.c'.

  2. need_module 'mod_cgi'

    The .c extension will be appended before the lookup, turning it into 'mod_cgi.c'.

  3. need_module 'cgi'

    The .c extension and mod_ prefix will be added before the lookup, turning it into 'mod_cgi.c'.

need_min_module_version

Used to require a minimum version of a module

For example:

  plan tests => 5, need_min_module_version(CGI => 2.81);

requires CGI.pm version 2.81 or higher.

Currently works only for perl modules.

need
  plan tests => 5,
      need 'LWP',
           { "perl >= 5.8.0 and w/ithreads is required" =>
             ($Config{useperlio} && $] >= 5.008) },
           { "not Win32"                 => sub { $^O eq 'MSWin32' },
             "foo is disabled"           => \&is_foo_enabled,
           },
           'cgid';

need() is more generic function which can impose multiple requirements at once. All requirements must be satisfied.

need()'s argument is a list of things to test. The list can include scalars, which are passed to need_module(), and hash references. If hash references are used, the keys, are strings, containing a reason for a failure to satisfy this particular entry, the values are the condition, which are satisfaction if they return true. If the value is 0 or 1, it used to decide whether the requirements very satisfied, so you can mix special need_*() functions that return 0 or 1. For example:

  plan tests => 1, need 'Compress::Zlib', 'deflate',
      need_min_apache_version("2.0.49");

If the scalar value is a string, different from 0 or 1, it's passed to need_module(). If the value is a code reference, it gets executed at the time of check and its return value is used to check the condition. If the condition check fails, the provided (in a key) reason is used to tell user why the test was skipped.

In the presented example, we require the presence of the LWP Perl module, mod_cgid, that we run under perl >= 5.7.3 on Win32.

It's possible to put more than one requirement into a single hash reference, but be careful that the keys will be different.

It's also important to mention to avoid using:

  plan tests => 1, requirement1 && requirement2;

technique. While test-wise that technique is equivalent to:

  plan tests => 1, need requirement1, requirement2;

since the test will be skipped, unless all the rules are satisfied, it's not equivalent for the end users. The second technique, deploying need() and a list of requirements, always runs all the requirement checks and reports all the missing requirements. In the case of the first technique, if the first requirement fails, the second is not run, and the missing requirement is not reported. So let's say all the requirements are missing Apache modules, and a user wants to satisfy all of these and run the test suite again. If all the unsatisfied requirements are reported at once, she will need to rebuild Apache once. If only one requirement is reported at a time, she will have to rebuild Apache as many times as there are elements in the && statement.

Also see plan().

under_construction
  plan tests => 5, under_construction;

skip all tests, noting that the tests are under construction

skip_reason
  plan tests => 5, skip_reason('my custom reason');

skip all tests. the reason you specify will be given at runtime. if no reason is given a default reason will be used.

Additional Configuration Variables

basic_config
  my $basic_cfg = Apache::Test::basic_config();
  $basic_cfg->write_perlscript($file, $content);

basic_config() is similar to config(), but doesn't contain any httpd-specific information and should be used for operations that don't require any httpd-specific knowledge.

config
  my $cfg = Apache::Test::config();
  my $server_rev = $cfg->{server}->{rev};
  ...

config() gives an access to the configuration object.

vars
  my $serverroot = Apache::Test::vars->{serverroot};
  my $serverroot = Apache::Test::vars('serverroot');
  my($top_dir, $t_dir) = Apache::Test::vars(qw(top_dir t_dir));

vars() gives an access to the configuration variables, otherwise accessible as:

  $vars = Apache::Test::config()->{vars};

If no arguments are passed, the reference to the variables hash is returned. If one or more arguments are passed the corresponding values are returned.

Test::More Integration

There are a few caveats if you want to use Apache::Test with Test::More instead of the default Test backend. The first is that Test::More requires you to use its own plan() function and not the one that ships with Apache::Test. Test::More also defines ok() and skip() functions that are different, and simply useing both modules in your test script will lead to redefined warnings for these subroutines.

To assist Test::More users we have created a special Apache::Test import tag, :withtestmore, which will export all of the standard Apache::Test symbols into your namespace except the ones that collide with Test::More.

    use Apache::Test qw(:withtestmore);
    use Test::More;

    plan tests => 1;           # Test::More::plan()

    ok ('yes', 'testing ok');  # Test::More::ok()

Now, while this works fine for standard client-side tests (such as t/basic.t), the more advanced features of Apache::Test require using Test::More as the sole driver behind the scenes.

Should you choose to use Test::More as the backend for server-based tests (such as t/response/TestMe/basic.pm) you will need to use the -withtestmore action tag:

    use Apache::Test qw(-withtestmore);

    sub handler {

        my $r = shift;

        plan $r, tests => 1;           # Test::More::plan() with
                                       # Apache::Test features

        ok ('yes', 'testing ok');      # Test::More::ok()
            }

-withtestmore tells Apache::Test to use Test::More instead of Test.pm behind the scenes. Note that you are not required to use Test::More yourself with the -withtestmore option and that the use Test::More tests => 1 syntax may have unexpected results.

Note that Test::More version 0.49, available within the Test::Simple 0.49 distribution on CPAN, or greater is required to use this feature.

Because Apache:Test was initially developed using Test as the framework driver, complete Test::More integration is considered experimental at this time - it is supported as best as possible but is not guaranteed to be as stable as the default Test interface at this time.

Apache::TestToString Class

The Apache::TestToString class is used to capture Test.pm output into a string. Example:

    Apache::TestToString->start;

    plan tests => 4;

    ok $data eq 'foo';

    ...
    # $tests will contain the Test.pm output: 1..4\nok 1\n...
    my $tests = Apache::TestToString->finish;

SEE ALSO

The Apache-Test tutorial: http://perl.apache.org/docs/general/testing/testing.html.

Apache::TestRequest subclasses LWP::UserAgent and exports a number of useful functions for sending request to the Apache test server. You can then test the results of those requests.

Use Apache::TestMM in your Makefile.PL to set up your distribution for testing.

AUTHOR

Doug MacEachern with contributions from Geoffrey Young, Philippe M. Chiasson, Stas Bekman and others.

Questions can be asked at the test-dev <at> httpd.apache.org list For more information see: http://httpd.apache.org/test/.


Apache::TestConfigData - Configuration file for Apache::Test

  • DESCRIPTION
  • FUNCTIONS
  • Environment Variables
    • APACHE_TEST_COLOR
    • APACHE_TEST_LIVE_DEV
    • APACHE_TEST_INTERACTIVE_PROMPT_OK
  • Special Placeholders
    • Configuration Options
    • NextAvailablePort
  • AUTHOR
  • SEE ALSO

NAME

Apache::TestConfigData - Configuration file for Apache::Test

NAME

Apache::TestConfig -- Test Configuration setup module

SYNOPSIS

  use Apache::TestConfig;

  my $cfg = Apache::TestConfig->new(%args)
  my $fh = $cfg->genfile($file);
  $cfg->writefile($file, $content);
  $cfg->gendir($dir);
  ...

DESCRIPTION

Apache::TestConfig is used in creating the Apache::Test configuration files.

FUNCTIONS

genwarning()
  my $warn = $cfg->genwarning($filename)

genwarning() returns a warning string as a comment, saying that the file was autogenerated and that it's not a good idea to modify this file. After the warning a perl trace of calls to this this function is appended. This trace is useful for finding what code has created the file.

  my $warn = $cfg->genwarning($filename, $from_filename)

If $from_filename is specified it'll be used in the warning to tell which file it was generated from.

genwarning() automatically recognizes the comment type based on the file extension. If the extension is not recognized, the default # style is used.

Currently it support <!-- -->, /* ... */ and # styles.

genfile()
  my $fh = $cfg->genfile($file);

genfile() creates a new file $file for writing and returns a file handle.

If parent directories of $file don't exist they will be automagically created.

The file $file and any created parent directories (if found empty) will be automatically removed on cleanup.

A comment with a warning and calls trace is added to the top of this file. See genwarning() for more info about this comment.

  my $fh = $cfg->genfile($file, $from_file);

If $from_filename is specified it'll be used in the warning to tell which file it was generated from.

  my $fh = $cfg->genfile($file, $from_file, $nowarning);

If $nowarning is true, the warning won't be added. If using this optional argument and there is no $from_file you must pass undef as in:

  my $fh = $cfg->genfile($file, undef, $nowarning);
writefile()
  $cfg->writefile($file, $content, [$nowarning]);

writefile() creates a new file $file with the content of $content.

A comment with a warning and calls trace is added to the top of this file unless $nowarnings is passed and set to a true value. See genwarning() for more info about this comment.

If parent directories of $file don't exist they will be automagically created.

The file $file and any created parent directories (if found empty) will be automatically removed on cleanup.

write_perlscript()
  $cfg->write_perlscript($filename, @lines);

Similar to writefile() but creates an executable Perl script with correctly set shebang line.

gendir()
  $cfg->gendir($dir);

gendir() creates a new directory $dir.

If parent directories of $dir don't exist they will be automagically created.

The directory $dir and any created parent directories will be automatically removed on cleanup if found empty.

Environment Variables

The following environment variables affect the configuration and the run-time of the Apache::Test framework:

APACHE_TEST_COLOR

To aid visual control over the configuration process and the run-time phase, Apache::Test uses coloured fonts when the environment variable APACHE_TEST_COLOR is set to a true value.

APACHE_TEST_LIVE_DEV

When using Apache::Test during the project development phase, it's often convenient to have the project/lib (live) directory appearing first in @INC so any changes to the Perl modules, residing in it, immediately affect the server, without a need to rerun make to update blib/lib. When the environment variable APACHE_TEST_LIVE_DEV is set to a true value during the configuration phase (t/TEST -config, Apache::Test will automatically unshift the project/lib directory into @INC, via the autogenerated t/conf/modperl_inc.pl file.

APACHE_TEST_INTERACTIVE_PROMPT_OK

Normally interactive prompts aren't run when STDIN is not attached to a tty. But sometimes there is a program that can answer the prompts (e.g. when testing A-T itself). If this variable is true the interactive config won't be skipped (if needed).

Special Placeholders

When generating configuration files from the *.in templates, special placeholder variables get substituted. To embed a placeholder use the @foo@ syntax. For example in extra.conf.in you can write:

  Include @ServerRoot@/conf/myconfig.conf

When extra.conf is generated, @ServerRoot@ will get replaced with the location of the server root.

Placeholders are case-insensitive.

Available placeholders:

Configuration Options

All configuration variables that can be passed to t/TEST, such as MaxClients, DocumentRoot, ServerRoot, etc. To see the complete list run:

  % t/TEST --help

and you will find them in the configuration options sections.

NextAvailablePort

Every time this placeholder is encountered it'll be replaced with the next available port. This is very useful if you need to allocate a special port, but not hardcode it. Later when running:

  % t/TEST -port=select

it's possible to run several concurrent test suites on the same machine, w/o having port collisions.

AUTHOR

SEE ALSO

perl(1), Apache::Test(3)


Apache::TestMB - Subclass of Module::Build to support Apache::Test

  • INTERFACE
    • Build
    • Constructor
      • new
    • Instance Methods
      • apache_test_args
      • apache_test_script
      • generate_script
  • SEE ALSO
  • AUTHOR

NAME

Apache::TestMB - Subclass of Module::Build to support Apache::Test

SYNOPSIS

Standard process for building & installing modules:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't like the "./" notation, you can do this:

  perl Build.PL
  perl Build
  perl Build test
  perl Build install

DESCRIPTION

This class subclasses Module::Build to add support for testing Apache integration with Apache::Test. It is broadly based on Apache::TestMM, and as such adds a number of build actions to a the Build script, while simplifying the process of creating Build.PL scripts.

Here's how to use Apache::TestMB in a Build.PL script:

  use Module::Build;

  my $build_pkg = eval { require Apache::TestMB }
      ? 'Apache::TestMB' : 'Module::Build';

  my $build = $build_pkg->new(
      module_name => 'My::Module',
  );
  $build->create_build_script;

This is identical to how Module::Build is used. Not all target systems may have Apache::Test (and therefore Apache::TestMB installed, so we test for it to be installed, first. But otherwise, its use can be exactly the same. Consult the Module::Build documentation for more information on how to use it; Module::Build::Cookbook may be especially useful for those looking to migrate from ExtUtils::MakeMaker.

INTERFACE

Build

With the above script, users can build your module in the usual Module::Build way:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

If Apache::TestMB is installed, then Apache will be started before tests are run by the test action, and shut down when the tests complete. Note that Build.PL can be called Apache::Test-specific options in addition to the usual Module::Build options. For example:

  perl Build.PL -apxs=/usr/local/apache/bin/apxs

Consult the Apache::Test documentation for a complete list of options.

In addition to the actions provided by Module::Build (build, clean, code, test, etc.), Apache::TestMB adds a few extra actions:

test_clean

This action cleans out the files generated by the test script, t/TEST. It is also executed by the clean action.

run_tests

This action actually the tests by executing the test script, t/TEST. It is executed by the test action, so most of the time it won't be executed directly.

testcover

Apache::TestMB overrides this action from Module::Build in order to prevent the Apache::Test preference files from being included in the test coverage.

Constructor

new

The new() constructor takes all the same arguments as its parent in Module::Build, but can optionally accept one other parameter:

apache_test_script

The name of the Apache::Test test script. The default value is t/TEST, which will work in the vast majority of cases. If you wish to specify your own file name, do so with a relative file name using Unix-style paths; the file name will automatically be converted for the local platform.

When new() is called it does the following:

  • Processes the Apache::Test-specific options in @ARGV. See the Apache::Test documentation for a complete list of options.

  • Sets the name of the Apache::Test test script to t/TEST, unless it was explicitly specified by the apache_test_script parameter.

  • Calls generate_script() to generate Apache::Test test script, usually t/TEST.

Instance Methods

apache_test_args

Returns a hash reference containing all of the settings specified by options passed to Build.PL, or explicitly added to @ARGV in Build.PL. Consult the Apache::Test documentation for a complete list of options.

apache_test_script

Gets or sets the file name of the Apache::Test test script.

generate_script

  $build->generate_script;
  $build->generate_script('t/FOO');
  $build->generate_script(undef, 'Apache::TestRun');

This method is called by new(), so in most cases it can be ignored. If you'd like it to use other than the default arguments, you can call it explicitly in Build.PL and pass it the arguments you desire. It takes two optional arguments:

  • The name of the Apache::Test test script. Defaults to the value returned by apache_test_script().

  • The name of an Apache::Test test running class. Defaults to Apache::TestRunPerl.

If there is an existing t/TEST.PL (or a script with the same name as specified by the apache_test_script parameter but with .PL appended to it), then that script will be used as the template for the test script. Otherwise, a simple test script will be written similar to what would be written by Apache::TestRun::generate_script() (although that function is not aware of the arguments passed to Build.PL, so use this one instead!).

SEE ALSO

Apache::TestRequest

Demonstrates how to write tests to send requests to the Apache server run by ./Build test.

Module::Build

The parent class for Apache::TestMB; consult it's documentation for more on its interface.

http://www.perl.com/pub/a/2003/05/22/testing.html

This article by Geoffrey Young explains how to configure Apache and write tests for your module using Apache::Test. Just use Apache::TestMB instead of Apache::TestMM to update it for use with Module::Build.

AUTHOR

David Wheeler

Questions can be asked at the test-dev <at> httpd.apache.org list. For more information see: http://httpd.apache.org/test/ and http://perl.apache.org/docs/general/testing/testing.html.


Apache::TestMM - Provide MakeMaker Wrapper Methods

  • FUNCTIONS
    • import
    • filter_args
    • generate_script

NAME

Apache::TestMM - Provide MakeMaker Wrapper Methods

SYNOPSIS

  require Apache::TestMM;

  # import MY::test and MY::clean overrides for MM
  Apache::TestMM->import(qw(test clean));

  # parse command line args
  Apache::TestMM::filter_args();

  # autogenerate the script
  Apache::TestMM::generate_script('t/TEST');

DESCRIPTION

Apache::TestMM provides wrappers for the ExtUtils::MakeMaker craft, making it easier to extend the autogenerated Makefile with Apache::Test.

FUNCTIONS

import

  use Apache::TestMM qw(test clean);

or:

  Apache::TestMM->import(qw(test clean));

Imports MY:: overrides for the default ExtUtils::MakeMaker test and clean targets, as if you have defined:

  sub MY::test {...}
  sub MY::clean {...}

in Makefile.PL. Apache::TestMM does this for you so that these Makefile targets will run the Apache server and the tests for it, and clean up after its mess.

filter_args

  push @ARGV, '-apxs', $apxs_path;
  Apache::TestMM::filter_args();
  WriteMakefile(...);

When WriteMakefile() is called it parses @ARGV, hoping to find special options like PREFIX=/home/stas/perl. Apache::Test accepts a lot of configuration options of its own. When Apache::TestMM::filter_args() is called, it removes any Apache::Test-specific options from @ARGV and stores them internally, so when WriteMakefile() is called they aren't in @ARGV and thus won't be processed by WriteMakefile().

The options can be set when Makefile.PL is called:

  % perl Makefile.PL -apxs /path/to/apxs

Or you can push them manually to @ARGV from the code:

  push @ARGV, '-apxs', $apxs_path;

When:

  Apache::TestMM::generate_script('t/TEST');

is called, Apache::Test-specific options extracted by Apache::TestMM::filter_args() are written to the autogenerated file. In our example, the autogenerated t/TEST will include:

  %Apache::TestConfig::Argv = qw(apxs /path/to/apxs);

which is going to be used by the Apache::Test runtime.

The other frequently used options are: -httpd, telling where to find the httpd (usually when the -apxs option is not used), -libmodperl to use a specific mod_perl shared object (if your mod_perl is built as DSO), -maxclients to change the default number of the configured MaxClients directive, -port to start the server on a specific port, etc. To get the complete list of available configuration options and their purpose and syntax, run:

  % perl -MApache::TestConfig -le 'Apache::TestConfig::usage()'

You may wish to document some of these in your application's README file, especially the -apxs and -httpd options.

generate_script

  Apache::TestMM::generate_script('t/TEST');

generate_script() accepts the name of the script to generate and will look for a template with the same name and suffix .PL. So in our example it'll look for t/TEST.PL. The autogenerated script t/TEST will include the contents of t/TEST.PL, and special directives, including any configuration options passed via filter_args()|/C_filter_args_ called from Makefile.PL, special fixup code, etc.


Apache::TestReport - A parent class for generating bug/success reports

  • Synopsis
  • Description
  • Overridable Methods
    • config
    • report_to
    • postit_note

NAME

Apache::TestReport - A parent class for generating bug/success reports

Synopsis

  use Apache::TestReport;
  Apache::TestReport->new(@ARGV)->run;

Description

This class is used to generate a bug or a success report, providing information about the system the code was running on.

Overridable Methods

config

return the information about user's system

report_to

return a string containing the email address the report should be sent to

postit_note

return a string to close the report with, e.g.:

      my($to, $where) = split '@', $self->report_to;
      return <<EOF;
        Note: Complete the rest of the details and post this bug report to
        $to <at> $where. To subscribe to the list send an empty
        email to $to-subscribe\@$where.


Apache::TestRequest - Send requests to your Apache test server

  • CONFIGURATION FUNCTION
  • FUNCTIONS
    • Optional Parameters
    • The Functions
      • GET
      • GET_STR
      • GET_BODY
      • GET_BODY_ASSERT
      • GET_OK
      • GET_RC
      • GET_HEAD
      • HEAD
      • HEAD_STR
      • HEAD_BODY
      • HEAD_BODY_ASSERT
      • HEAD_OK
      • HEAD_RC
      • HEAD_HEAD
      • PUT
      • PUT_STR
      • PUT_BODY
      • PUT_BODY_ASSERT
      • PUT_OK
      • PUT_RC
      • PUT_HEAD
      • POST
      • POST_STR
      • POST_BODY
      • POST_BODY_ASSERT
      • POST_OK
      • POST_RC
      • POST_HEAD
      • UPLOAD
      • UPLOAD_BODY
      • UPLOAD_BODY_ASSERT
      • OPTIONS
    • URL Manipulation Functions
      • module2path
      • module2url
  • ENVIRONMENT VARIABLES
  • SEE ALSO
  • AUTHOR

NAME

Apache::TestRequest - Send requests to your Apache test server

SYNOPSIS

  use Apache::Test qw(ok have_lwp);
  use Apache::TestRequest qw(GET POST);
  use Apache::Constants qw(HTTP_OK);

  plan tests => 1, have_lwp;

  my $res = GET '/test.html';
  ok $res->code == HTTP_OK, "Request is ok";

DESCRIPTION

Apache::TestRequest provides convenience functions to allow you to make requests to your Apache test server in your test scripts. It subclasses LWP::UserAgent, so that you have access to all if its methods, but also exports a number of useful functions likely useful for majority of your test requests. Users of the old Apache::test (or Apache::testold) module, take note! Herein lie most of the functions you'll need to use to replace Apache::test in your test suites.

Each of the functions exported by Apache::TestRequest uses an LWP::UserAgent object to submit the request and retrieve its results. The return value for many of these functions is an HTTP::Response object. See HTTP::Response for documentation of its methods, which you can use in your tests. For example, use the code() and content() methods to test the response code and content of your request. Using GET, you can perform a couple of tests using these methods like this:

  use Apache::Test qw(ok have_lwp);
  use Apache::TestRequest qw(GET POST);
  use Apache::Constants qw(HTTP_OK);

  plan tests => 2, have_lwp;

  my $uri = "/test.html?foo=1&bar=2";
  my $res = GET $uri;
  ok $res->code == HTTP_OK, "Check that the request was OK";
  ok $res->content eq "foo => 1, bar => 2", "Check its content";

Note that you can also use Apache::TestRequest with Test::Builder and its derivatives, including Test::More:

  use Test::More;
  # ...
  is $res->code, HTTP_OK, "Check that the request was OK";
  is $res->content, "foo => 1, bar => 2", "Check its content";

CONFIGURATION FUNCTION

You can tell Apache::TestRequest what kind of LWP::UserAgent object to use for its convenience functions with user_agent(). This function uses its arguments to construct an internal global LWP::UserAgent object that will be used for all subsequent requests made by the convenience functions. The arguments it takes are the same as for the LWP::UserAgent constructor. See the LWP::UserAgent|LWP::UserAgent documentation for a complete list.

The user_agent() function only creates the internal LWP::UserAgent object the first time it is called. Since this function is called internally by Apache::TestRequest, you should always use the reset parameter to force it to create a new global LWP::UserAgent Object:

  Apache::TestRequest::user_agent(reset => 1, %params);

user_agent() differs from LWP::UserAgent->new in two additional ways. First, it supports an additional parameter, keep_alive, which enables connection persistence, where the same connection is used to process multiple requests (and, according to the LWP::UserAgent|LWP::UserAgent documentation, has the effect of loading and enabling the new experimental HTTP/1.1 protocol module).

And finally, the semantics of the requests_redirectable parameter is different than for LWP::UserAgent in that you can pass it a boolean value as well as an array for LWP::UserAgent. To force Apache::TestRequest not to follow redirects in any of its convenience functions, pass a false value to requests_redirectable:

  Apache::TestRequest::user_agent(reset => 1,
                                  requests_redirectable => 0);

If LWP is not installed, then you can still pass in an array reference as LWP::UserAgent expects. Apache::TestRequest will examine the array and allow redirects if the array contains more than one value or if there is only one value and that value is not "POST":

  # Always allow redirection.
  my $redir = have_lwp() ? [qw(GET HEAD POST)] : 1;
  Apache::TestRequest::user_agent(reset => 1,
                                  requests_redirectable => $redir);

But note that redirection will not work with POST unless LWP is installed. It's best, therefore, to check have_lwp before running tests that rely on a redirection from POST.

Sometimes it is desireable to have Apache::TestRequest remember cookies sent by the pages you are testing and send them back to the server on subsequent requests. This is especially necessary when testing pages whose functionality relies on sessions or the presence of preferences stored in cookies.

By default, LWP::UserAgent does not remember cookies between requests. You can tell it to remember cookies between request by adding:

  Apache::TestRequest::user_agent(cookie_jar => {});

before issuing the requests.

FUNCTIONS

Apache::TestRequest exports a number of functions that will likely prove convenient for use in the majority of your request tests.

Optional Parameters

Each function also takes a number of optional arguments.

redirect_ok

By default a request will follow redirects retrieved from the server. To prevent this behavior, pass a false value to a redirect_ok parameter:

  my $res = GET $uri, redirect_ok => 0;

Alternately, if all of your tests need to disable redirects, tell Apache::TestRequest to use an LWP::UserAgent object that disables redirects:

  Apache::TestRequest::user_agent( reset => 1,
                                   requests_redirectable => 0 );
cert

If you need to force an SSL request to use a particular SSL certificate, pass the name of the certificate via the cert parameter:

  my $res = GET $uri, cert => 'my_cert';
content

If you need to add content to your request, use the content parameter:

  my $res = GET $uri, content => 'hello world!';
filename

The name of a local file on the file system to be sent to the Apache test server via UPLOAD() and its friends.

The Functions

GET

  my $res = GET $uri;

Sends a simple GET request to the Apache test server. Returns an HTTP::Response object.

You can also supply additional headers to be sent with the request by adding their name/value pairs after the url parameter, for example:

  my $res = GET $url, 'Accept-Language' => 'de,en-us,en;q=0.5';

GET_STR

A shortcut function for GET($uri)->as_string.

GET_BODY

A shortcut function for GET($uri)->content.

GET_BODY_ASSERT

Use this function when your test is outputting content that you need to check, and you want to make sure that the request was successful before comparing the contents of the request. If the request was unsuccessful, GET_BODY_ASSERT will return an error message. Otherwise it will simply return the content of the request just as GET_BODY would.

GET_OK

A shortcut function for GET($uri)->is_success.

GET_RC

A shortcut function for GET($uri)->code.

GET_HEAD

Throws out the content of the request, and returns the string representation of the request. Since the body has been thrown out, the representation will consist solely of the headers. Furthermore, GET_HEAD inserts a "#" at the beginning of each line of the return string, so that the contents are suitable for printing to STDERR during your tests without interfering with the workings of Test::Harness.

HEAD

  my $res = HEAD $uri;

Sends a HEAD request to the Apache test server. Returns an HTTP::Response object.

HEAD_STR

A shortcut function for HEAD($uri)->as_string.

HEAD_BODY

A shortcut function for HEAD($uri)->content. Of course, this means that it will likely return nothing.

HEAD_BODY_ASSERT

Use this function when your test is outputting content that you need to check, and you want to make sure that the request was successful before comparing the contents of the request. If the request was unsuccessful, HEAD_BODY_ASSERT will return an error message. Otherwise it will simply return the content of the request just as HEAD_BODY would.

HEAD_OK

A shortcut function for GET($uri)->is_success.

HEAD_RC

A shortcut function for GET($uri)->code.

HEAD_HEAD

Throws out the content of the request, and returns the string representation of the request. Since the body has been thrown out, the representation will consist solely of the headers. Furthermore, GET_HEAD inserts a "#" at the beginning of each line of the return string, so that the contents are suitable for printing to STDERR during your tests without interfering with the workings of Test::Harness.

PUT

  my $res = PUT $uri;

Sends a simple PUT request to the Apache test server. Returns an HTTP::Response object.

PUT_STR

A shortcut function for PUT($uri)->as_string.

PUT_BODY

A shortcut function for PUT($uri)->content.

PUT_BODY_ASSERT

Use this function when your test is outputting content that you need to check, and you want to make sure that the request was successful before comparing the contents of the request. If the request was unsuccessful, PUT_BODY_ASSERT will return an error message. Otherwise it will simply return the content of the request just as PUT_BODY would.

PUT_OK

A shortcut function for PUT($uri)->is_success.

PUT_RC

A shortcut function for PUT($uri)->code.

PUT_HEAD

Throws out the content of the request, and returns the string representation of the request. Since the body has been thrown out, the representation will consist solely of the headers. Furthermore, PUT_HEAD inserts a "#" at the beginning of each line of the return string, so that the contents are suitable for printing to STDERR during your tests without interfering with the workings of Test::Harness.

POST

  my $res = POST $uri, [ arg => $val, arg2 => $val ];

Sends a POST request to the Apache test server and returns an HTTP::Response object. An array reference of parameters passed as the second argument will be submitted to the Apache test server as the POST content. Parameters corresponding to those documented in Optional Parameters can follow the optional array reference of parameters, or after $uri.

To upload a chunk of data, simply use:

  my $res = POST $uri, content => $data;

POST_STR

A shortcut function for POST($uri, @args)->content.

POST_BODY

A shortcut function for POST($uri, @args)->content.

POST_BODY_ASSERT

Use this function when your test is outputting content that you need to check, and you want to make sure that the request was successful before comparing the contents of the request. If the request was unsuccessful, POST_BODY_ASSERT will return an error message. Otherwise it will simply return the content of the request just as POST_BODY would.

POST_OK

A shortcut function for POST($uri, @args)->is_success.

POST_RC

A shortcut function for POST($uri, @args)->code.

POST_HEAD

Throws out the content of the request, and returns the string representation of the request. Since the body has been thrown out, the representation will consist solely of the headers. Furthermore, POST_HEAD inserts a "#" at the beginning of each line of the return string, so that the contents are suitable for printing to STDERR during your tests without interfering with the workings of Test::Harness.

UPLOAD

  my $res = UPLOAD $uri, \@args, filename => $filename;

Sends a request to the Apache test server that includes an uploaded file. Other POST parameters can be passed as a second argument as an array reference.

Apache::TestRequest will read in the contents of the file named via the filename parameter for submission to the server. If you'd rather, you can submit use the content parameter instead of filename, and its value will be submitted to the Apache server as file contents:

  my $res = UPLOAD $uri, undef, content => "This is file content";

The name of the file sent to the server will simply be "b". Note that in this case, you cannot pass other POST arguments to UPLOAD() -- they would be ignored.

UPLOAD_BODY

A shortcut function for UPLOAD($uri, @params)->content.

UPLOAD_BODY_ASSERT

Use this function when your test is outputting content that you need to check, and you want to make sure that the request was successful before comparing the contents of the request. If the request was unsuccessful, UPLOAD_BODY_ASSERT will return an error message. Otherwise it will simply return the content of the request just as UPLOAD_BODY would.

OPTIONS

  my $res = OPTIONS $uri;

Sends an OPTIONS request to the Apache test server. Returns an HTTP::Response object with the Allow header, indicating which methods the server supports. Possible methods include OPTIONS, GET, HEAD and POST. This function thus can be useful for testing what options the Apache server supports. Consult the HTTPD 1.1 specification, section 9.2, at http://www.faqs.org/rfcs/rfc2616.html for more information.

URL Manipulation Functions

Apache::TestRequest also includes a few helper functions to aid in the creation of urls used in the functions above.

module2path

  $path = Apache::TestRequest::module2path($module_name);

Convert a module name to a path, safe for use in the various request methods above. e.g. :: can't be used in URLs on win32. For example:

  $path = Apache::TestRequest::module2path('Foo::Bar');

returns:

  /Foo__Bar

module2url

  $url = Apache::TestRequest::module2url($module);
  $url = Apache::TestRequest::module2url($module, \%options);

Convert a module name to a full URL including the current configurations hostname:port and sets module accordingly.

  $url = Apache::TestRequest::module2url('Foo::Bar');

returns:

  http://$hostname:$port/Foo__Bar

The default scheme used is http. You can override this by passing your preferred scheme into an optional second param. For example:

  $module = 'MyTestModule::TestHandler';
  $url = Apache::TestRequest::module2url($module, {scheme => 'https'});

returns:

  https://$hostname:$port/MyTestModule__TestHandler

You may also override the default path with a path of your own:

  $module = 'MyTestModule::TestHandler';
  $url = Apache::TestRequest::module2url($module, {path => '/foo'});

returns:

  http://$hostname:$port/foo

ENVIRONMENT VARIABLES

The following environment variables can affect the behavior of Apache::TestRequest:

APACHE_TEST_PRETEND_NO_LWP

If the environment variable APACHE_TEST_PRETEND_NO_LWP is set to a true value, Apache::TestRequest will pretend that LWP is not available so one can test whether the test suite will survive on a system which doesn't have libwww-perl installed.

APACHE_TEST_HTTP_09_OK

If the environment variable APACHE_TEST_HTTP_09_OK is set to a true value, Apache::TestRequest will allow HTTP/0.9 responses from the server to proceed. The default behavior is to die if the response protocol is not either HTTP/1.0 or HTTP/1.1.

SEE ALSO

Apache::Test is the main Apache testing module. Use it to set up your tests, create a plan, and to ensure that you have the Apache version and modules you need.

Use Apache::TestMM in your Makefile.PL to set up your distribution for testing.

AUTHOR

Doug MacEachern with contributions from Geoffrey Young, Philippe M. Chiasson, Stas Bekman and others. Documentation by David Wheeler.

Questions can be asked at the test-dev <at> httpd.apache.org list. For more information see: http://httpd.apache.org/test/ and http://perl.apache.org/docs/general/testing/testing.html.


Apache::TestRun - Run the test suite

  • METHODS
    • bug_report
    • pre_configure
    • new_test_config
  • Persistent Custom Configuration
    • Saving Custom Configuration Options

NAME

Apache::TestRun - Run the test suite

SYNOPSIS

DESCRIPTION

The Apache::TestRun package controls the configuration and running of the test suite.

METHODS

Several methods are sub-classable, if the default behavior should be changed.

bug_report

The bug_report() method is executed when t/TEST was executed with the -bugreport option, and make test (or t/TEST) fail. Normally this is callback which you can use to tell the user how to deal with the problem, e.g. suggesting to read some document or email some details to someone who can take care of it. By default nothing is executed.

The -bugreport option is needed so this feature won't become annoying to developers themselves. It's automatically added to the run_tests target in Makefile. So if you repeateadly have to test your code, just don't use make test but run t/TEST directly. Here is an example of a custom t/TEST

  My::TestRun->new->run(@ARGV);

  package My::TestRun;
  use base 'Apache::TestRun';

  sub bug_report {
      my $self = shift;

      print <<EOI;
  +--------------------------------------------------------+
  | Please file a bug report: http://perl.apache.org/bugs/ |
  +--------------------------------------------------------+
  EOI
  }

pre_configure

The pre_configure() method is executed before the configuration for Apache::Test is generated. So if you need to adjust the setup before httpd.conf and other files are autogenerated, this is the right place to do so.

For example if you don't want to inherit a LoadModule directive for mod_apreq.so but to make sure that the local version is used, you can sub-class Apache::TestRun and override this method in t/TEST.PL:

  package My::TestRun;
  use base 'Apache::TestRun';
  use Apache::TestConfig;
  __PACKAGE__->new->run(@ARGV);

  sub pre_configure {
      my $self = shift;
      # Don't load an installed mod_apreq
      Apache::TestConfig::autoconfig_skip_module_add('mod_apreq.c');

      $self->SUPER::pre_configure();
  }

Notice that the extension is .c, and not .so.

Don't forget to run the super class' c<pre_configure()> method.

new_test_config

META: to be completed

Persistent Custom Configuration

When Apache::Test is first installed or used, it will save the values of httpd, apxs, port, user, and group, if set, to a configuration file Apache::TestConfigData. This information will then be used in setting these options for subsequent uses of Apache-Test unless temprorarily overridden, either by setting the appropriate environment variable (APACHE_TEST_HTTPD, APACHE_TEST_APXS, APACHE_TEST_PORT, APACHE_TEST_USER, and APACHE_TEST_GROUP) or by giving the relevant option (-httpd, -apxs, -port, -user, and -group) when the TEST script is run.

To avoid either using previous persistent configurations or saving current configurations, set the APACHE_TEST_NO_STICKY_PREFERENCES environment variable to a true value.

Finally it's possible to permanently override the previously saved options by passing -save|/Saving_Custom_Configuration_Options.

Here is the algorithm of how and when options are saved for the first time and when they are used. We will use a few variables to simplify the pseudo-code/pseudo-chart flow:

$config_exists - custom configuration has already been saved, to get this setting run custom_config_exists(), which tests whether either apxs or httpd values are set. It doesn't check for other values, since all we need is apxs or httpd to get the test suite running. custom_config_exists() checks in the following order lib/Apache/TestConfigData.pm (if during Apache-Test build) , ~/.apache-test/Apache/TestConfigData.pm and Apache/TestConfigData.pm in the perl's libraries.

$config_overriden - that means that we have either apxs or httpd values provided by user, via env vars or command line options.

  1. Building Apache-Test or modperl-2.0 (or any other project that bundles Apache-Test).
      1) perl Apache-Test/Makefile.PL
  (for bundles top-level Makefile.PL will run this as well)
      if $config_exists
      do nothing
  else
      create lib/Apache/TestConfigData.pm w/ empty config: {}

      2) make
      3) make test
      if $config_exists
      if $config_overriden
          override saved options (for those that were overriden)
      else
          use saved options
  else
      if $config_overriden
          save them in lib/Apache/TestConfigData.pm
          (which will be installed on 'make install')
      else
          - run interactive prompt for C<httpd> and optionally for C<apxs>
          - save the custom config in lib/Apache/TestConfigData.pm
          - restart the currently run program
      modperl-2.0 is a special case in (3). it always overrides 'httpd'
  and 'apxs' settings. Other settings like 'port', can be used from
  the saved config.
      4) make install
         if $config_exists only in lib/Apache/TestConfigData.pm
        it will be installed system-wide
     else
        nothing changes (since lib/Apache/TestConfigData.pm won't exist)
  2. Testing 3rd party modules (after Apache-Test was installed)

    Notice that the following situation is quite possible:

      cd Apache-Test
  perl Makefile.PL && make install

    so that Apache-Test was installed but no custom configuration saved (since its make test wasn't run). In which case the interactive configuration should kick in (unless config options were passed) and in any case saved once configured.

    $custom_config_path - perl's Apache/TestConfigData.pm (at the same location as Apache/TestConfig.pm) if that area is writable by that user (e.g. perl's lib is not owned by 'root'). If not, in ~/.apache-test/Apache/TestConfigData.pm.

      1) perl Apache-Test/Makefile.PL
  2) make
  3) make test
      if $config_exists
      if $config_overriden
          override saved options (for those that were overriden)
      else
          use saved options
  else
      if $config_overriden
          save them in $custom_config_path
      else
          - run interactive prompt for C<httpd> and optionally for C<apxs>
          - save the custom config in $custom_config_path
          - restart the currently run program
      4) make install

Saving Custom Configuration Options

If you want to override the existing custom configurations options to Apache::TestConfigData, use the -save flag when running TEST.

If you are running Apache::Test as a user who does not have permission to alter the system Apache::TestConfigData, you can place your own private configuration file TestConfigData.pm under $ENV{HOME}/.apache-test/Apache/, which Apache::Test will use, if present. An example of such a configuration file is

  # file $ENV{HOME}/.apache-test/Apache/TestConfigData.pm
  package Apache::TestConfigData;
  use strict;
  use warnings;
  use vars qw($vars);

  $vars = {
      'group' => 'me',
      'user' => 'myself',
      'port' => '8529',
      'httpd' => '/usr/local/apache/bin/httpd',

  };
  1;


Apache::TestRunPHP - configure and run a PHP-based test suite

  • EXAMPLE
  • SEE ALSO
  • AUTHOR

NAME

Apache::TestRunPHP - configure and run a PHP-based test suite

SYNOPSIS

  use Apache::TestRunPHP;
  Apache::TestRunPHP->new->run(@ARGV);

DESCRIPTION

The Apache::TestRunPHP package controls the configuration and running of the test suite for PHP-based tests. It's a subclass of Apache::TestRun and similar in function to Apache::TestRunPerl.

Refer to the Apache::TestRun manpage for information on the available API.

EXAMPLE

TestRunPHP works almost identially to TestRunPerl, but in case you are new to Apache-Test here is a quick getting started guide. be sure to see the links at the end of this document for places to find additional details.

because Apache-Test is a Perl-based testing framework we start from a Makefile.PL, which should have the following lines (in addition to the standard Makefile.PL parts):

  use Apache::TestMM qw(test clean);
  use Apache::TestRunPHP ();

  Apache::TestMM::filter_args();

  Apache::TestRunPHP->generate_script();

generate_script() will create a script named t/TEST, the gateway to the Perl testing harness and what is invoked when you call make test. filter_args() accepts some Apache::Test-specific arguments and passes them along. for example, to point to a specific httpd installation you would invoke Makefile.PL as follows

  $ perl Makefile.PL -httpd /my/local/apache/bin/httpd

and /my/local/apache/bin/httpd will be propagated throughout the rest of the process. note that PHP needs to be active within Apache prior to configuring the test framework as shown above, either by virtue of PHP being compiled into the httpd binary statically or through an active LoadModule statement within the configuration located in /my/local/apache/conf/httpd.conf. Other required modules are the (very common) mod_alias and mod_env.

now, like with Apache::TestRun and Apache::TestRunPerl, you can place client-side Perl test scripts under t/, such as t/01basic.t, and Apache-Test will run these scripts when you call make test. however, what makes Apache::TestRunPHP unique is some added magic specifically tailored to a PHP environment. here are the mechanics.

Apache::TestRunPHP will look for PHP test scripts in that match the following pattern

  t/response/TestFoo/bar.php

where Foo and bar can be anything you like, and t/response/Test* is case sensitive. when this format is adhered to, Apache::TestRunPHP will create an associated Perl test script called t/foo/bar.t, which will be executed when you call make test. all bar.t does is issue a simple GET to bar.php, leaving the actual testing to bar.php. in essence, you can forget that bar.t even exists.

what does bar.php look like? here is an example:

  <?php
    print "1..1\n";
    print "ok 1\n"
  ?>

if it looks odd, that's ok because it is. I could explain to you exactly what this means, but it isn't important to understand the gory details. instead, it is sufficient to understand that when Apache::Test calls bar.php it feeds the results directly to Test::Harness, a module that comes with every Perl installation, and Test::Harness expects what it receives to be formated in a very specific way. by itself, all of this is pretty useless, so Apache::Test provides PHP testers with something much better. here is a much better example:

  <?php
    # import the Test::More emulation layer
    # see
    #   http://search.cpan.org/dist/Test-Simple/lib/Test/More.pm
    # for Perl's documentation - these functions should behave
    # in the same way
    require 'test-more.php';

    # plan() the number of tests
    plan(6);

    # call ok() for each test you plan
    ok ('foo' == 'foo', 'foo is equal to foo');
    ok ('foo' != 'foo', 'foo is not equal to foo');

    # ok() can be other things as well
    is ('bar', 'bar', 'bar is bar');
    is ('baz', 'bar', 'baz is baz');
    isnt ('bar', 'beer', 'bar is not beer');
    like ('bar', '/ar$/', 'bar matches ar$');

    diag("printing some debugging information");

    # whoops! one too many tests.  I wonder what will happen...
    is ('biff', 'biff', 'baz is a baz');
  ?>

the include library test-more.php is automatically generated by Apache::TestConfigPHP and configurations tweaked in such a a way that your PHP scripts can find it without issue. the functions provided by test-more.php are equivalent in name and function to those in Test::More, a standard Perl testing library, so you can see that manpage for details on the syntax and functionality of each.

at this point, we have enough in place to run some tests from PHP-land - a Makefile.PL to configure Apache for us, and a PHP script in t/response/TestFoo/bar.php to send some results out to the testing engine. issuing make test would start Apache, issue the request to bar.php, generate a report, and shut down Apache. the report would look like something like this after running the tests in verbose mode (eg make test TEST_VERBOSE=1):

  t/php/bar....1..6
  ok 1 - foo is equal to foo
  not ok 2 - foo is not equal to foo
  #     Failed test (/src/devel/perl-php-test/t/response/TestFoo/bar.php at line 13)
  ok 3 - bar is bar
  not ok 4 - baz is baz
  #     Failed test (/src/devel/perl-php-test/t/response/TestFoo/bar.php at line 17)
  #           got: 'baz'
  #      expected: 'bar'
  ok 5 - bar is not beer
  ok 6 - bar matches ar$
  # printing some debugging information
  ok 7 - baz is a baz
  FAILED tests 2, 4, 7
          Failed 3/6 tests, 50.00% okay
  Failed Test Stat Wstat Total Fail  Failed  List of Failed
  -------------------------------------------------------------------------------
  t/php/bar.t                6    3  50.00%  2 4 7
  Failed 1/1 test scripts, 0.00% okay. 1/6 subtests failed, 83.33% okay.

note that the actual test file that was run was t/php/bar.t. this file is autogenerated based on the t/response/TestFoo/bar.php pattern of your PHP script. t/php/bar.t happens to be written in Perl, but you really don't need to worry about it too much.

as an interesting aside, if you are using perl-5.8.3 or later you can actually create your own t/foo.php client-side scripts and they will be run via php (using our php.ini). but more on that later...

SEE ALSO

the best source of information about using Apache-Test with PHP (at this time) is probably the talk given at ApacheCon 2004 (http://xrl.us/phpperl), as well as the code from the talk (http://xrl.us/phpperlcode). there is also the online tutorial http://perl.apache.org/docs/general/testing/testing.html which has all of the mod_perl-specific syntax and features have been ported to PHP with this class.

AUTHOR

Apache-Test is a community effort, maintained by a group of dedicated volunteers.

Questions can be asked at the test-dev <at> httpd.apache.org list For more information see: http://httpd.apache.org/test/.


Apache::TestRunPerl - Run mod_perl-requiring Test Suite

NAME

Apache::TestRunPerl - Run mod_perl-requiring Test Suite

SYNOPSIS

  use Apache::TestRunPerl;
  Apache::TestRunPerl->new->run(@ARGV);

DESCRIPTION

The Apache::TestRunPerl package controls the configuration and running of the test suite. It's a subclass of Apache::TestRun, and should be used only when you need to run mod_perl tests.

Refer to the Apache::TestRun manpage for information on the available API.


site/lib/Apache/TestServer.pm

    • stop()

stop()

attempt to stop the server.

returns:

  on success: $pid of the server
  on failure: -1


Apache::TestSmoke - Special Tests Sequence Failure Finder

    • The Problem
    • The Solution
    • Resolving Sequence Problems
  • Reduction Algorithm
  • t/SMOKE.PL
  • AUTHOR

NAME

Apache::TestSmoke - Special Tests Sequence Failure Finder

SYNOPSIS

  # get the usage and the default values
  % t/SMOKE -help
  # repeat all tests 5 times and try 20 random iterations
  # and save the report into the file 'myreport'
  % t/SMOKE -times=5 -iterations=20 -report=myreport
  # run all tests default number of iterations, and repeat tests
  # default number of times
  % t/SMOKE
  # same as above but work only the specified tests
  % t/SMOKE foo/bar foo/tar
  # run once a sequence of tests in a non-random mode
  # e.g. when trying to reduce a known long sequence that fails
  % t/SMOKE -order=rotate -times=1 foo/bar foo/tar
  # show me each currently running test
  # it's not the same as running the tests in the verbose mode
  % t/SMOKE -verbose
  # run t/TEST, but show any problems after *each* tests is run
  # useful for bug reports (it actually runs t/TEST -start, then
  # t/TEST -run for each test separately and finally t/TEST -stop
  % t/SMOKE -bug_mode
  # now read the created report file

DESCRIPTION

The Problem

When we try to test a stateless machine (i.e. all tests are independent), running all tests once ensures that all tested things properly work. However when a state machine is tested (i.e. where a run of one test may influence another test) it's not enough to run all the tests once to know that the tested features actually work. It's quite possible that if the same tests are run in a different order and/or repeated a few times, some tests may fail. This usually happens when some tests don't restore the system under test to its pristine state at the end of the run, which may influence other tests which rely on the fact that they start on pristine state, when in fact it's not true anymore. In fact it's possible that a single test may fail when run twice or three times in a sequence.

The Solution

To reduce the possibility of such dependency errors, it's helpful to run random testing repeated many times with many different srand seeds. Of course if no failures get spotted that doesn't mean that there are no tests inter-dependencies, which may cause a failure in production. But random testing definitely helps to spot many problems and can give better test coverage.

Resolving Sequence Problems

When this kind of testing is used and a failure is detected there are two problems:

  1. First is to be able to reproduce the problem so if we think we fixed it, we could verify the fix. This one is easy, just remember the sequence of tests run till the failed test and rerun the same sequence once again after the problem has been fixed.

  2. Second is to be able to understand the cause of the problem. If during the random test the failure has happened after running 400 tests, how can we possibly know which previously running tests has caused to the failure of the test 401. Chances are that most of the tests were clean and don't have inter-dependency problem. Therefore it'd be very helpful if we could reduce the long sequence to a minimum. Preferably 1 or 2 tests. That's when we can try to understand the cause of the detected problem.

This utility attempts to solve both problems, and at the end of each iteration print a minimal sequence of tests causing to a failure. This doesn't always succeed, but works in many cases.

This utility:

  1. Runs the tests randomly until the first failure is detected. Or non-randomly if the option -order is set to repeat or rotate.

  2. Then it tries to reduce that sequence of tests to a minimum, and this sequence still causes to the same failure.

  3. (XXX: todo): then it reruns the minimal sequence in the verbose mode and saves the output.

  4. It reports all the successful reductions as it goes to STDOUT and report file of the format: smoke-report-<date>.txt.

    In addition the systems build parameters are logged into the report file, so the detected problems could be reproduced.

  5. Goto 1 and run again using a new random seed, which potentially should detect different failures.

Reduction Algorithm

Currently for each reduction path, the following reduction algorithms get applied:

  1. Binary search: first try the upper half then the lower.

  2. Random window: randomize the left item, then the right item and return the items between these two points.

t/SMOKE.PL

t/SMOKE.PL is driving this module, if you don't have it, create it:

  #!perl

  use strict;
  use warnings FATAL => 'all';

  use FindBin;
  use lib "$FindBin::Bin/../Apache-Test/lib";
  use lib "$FindBin::Bin/../lib";

  use Apache::TestSmoke ();

  Apache::TestSmoke->new(@ARGV)->run;

usually Makefile.PL converts it into t/SMOKE while adjusting the perl path, but you create t/SMOKE in first place as well.

AUTHOR

Stas Bekman


Apache::TestTrace - Helper output generation functions

  • TODO
  • AUTHOR

NAME

Apache::TestTrace - Helper output generation functions

SYNOPSIS

    use Apache::TestTrace;

    debug "foo bar";

    info_sub "missed it";

    error_mark "something is wrong";

    # test sub that exercises all the tracing functions
    sub test {
        print $Apache::TestTrace::LogFH
              "TraceLevel: $Apache::TestTrace::Level\n";
        $_->($_,[1..3],$_) for qw(emerg alert crit error
                                  warning notice info debug todo);
        print $Apache::TestTrace::LogFH "\n\n"
    };

    # demo the trace subs using default setting
    test();

    {
        # override the default trace level with 'crit'
        local $Apache::TestTrace::Level = 'crit';
        # now only 'crit' and higher levels will do tracing lower level
        test();
    }

    {
        # set the trace level to 'debug'
        local $Apache::TestTrace::Level = 'debug';
        # now only 'debug' and higher levels will do tracing lower level
        test();
    }

    {
        open OUT, ">/tmp/foo" or die $!;
        # override the default Log filehandle
        local $Apache::TestTrace::LogFH = \*OUT;
        # now the traces will go into a new filehandle
        test();
        close OUT;
    }

    # override tracing level via -trace opt
    % t/TEST -trace=debug

    # override tracing level via env var
    % env APACHE_TEST_TRACE_LEVEL=debug t/TEST

DESCRIPTION

This module exports a number of functions that make it easier generating various diagnostics messages in your programs in a consistent way and saves some keystrokes as it handles the new lines and sends the messages to STDERR for you.

This module provides the same trace methods as syslog(3)'s log levels. Listed from low level to high level: emerg(), alert(), crit(), error(), warning(), notice(), info(), debug(). The only different function is warning(), since warn is already taken by Perl.

The module provides another trace function called todo() which is useful for todo items. It has the same level as debug (the highest).

There are two more variants of each of these functions. If the _mark suffix is appended (e.g., error_mark) the trace will start with the filename and the line number the function was called from. If the _sub suffix is appended (e.g., error_info) the trace will start with the name of the subroutine the function was called from.

If you have Term::ANSIColor installed the diagnostic messages will be colorized, otherwise a special for each function prefix will be used.

If Data::Dumper is installed and you pass a reference to a variable to any of these functions, the variable will be dumped with Data::Dumper::Dumper().

Functions whose level is above the level set in $Apache::TestTrace::Level become NOPs. For example if the level is set to alert, only alert() and emerg() functions will generate the output. The default setting of this variable is warning. Other valid values are: emerg, alert, crit, error, warning, notice, info, debug.

Another way to affect the trace level is to set $ENV{APACHE_TEST_TRACE_LEVEL}, which takes effect if $Apache::TestTrace::Level is not set. So an explicit setting of $Apache::TestTrace::Level always takes precedence.

By default all the output generated by these functions goes to STDERR. You can override the default filehandler by overriding $Apache::TestTrace::LogFH with a new filehandler.

When you override this package's global variables, think about localizing your local settings, so it won't affect other modules using this module in the same run.

TODO

 o provide an option to disable the coloring altogether via some flag
   or import()

AUTHOR

Stas Bekman with contributions from Doug MacEachern


Apache::TestUtil - Utility functions for writing tests

  • FUNCTIONS
  • AUTHOR
  • SEE ALSO

NAME

Apache::TestUtil - Utility functions for writing tests

SYNOPSIS

  use Apache::Test;
  use Apache::TestUtil;

  ok t_cmp("foo", "foo", "sanity check");
  t_write_file("filename", @content);
  my $fh = t_open_file($filename);
  t_mkdir("/foo/bar");
  t_rmtree("/foo/bar");
  t_is_equal($a, $b);

DESCRIPTION

Apache::TestUtil automatically exports a number of functions useful in writing tests.

All the files and directories created using the functions from this package will be automatically destroyed at the end of the program execution (via END block). You should not use these functions other than from within tests which should cleanup all the created directories and files at the end of the test.

FUNCTIONS

t_cmp()
  t_cmp($received, $expected, $comment);

t_cmp() prints the values of $comment, $expected and $received. e.g.:

  t_cmp(1, 1, "1 == 1?");

prints:

  # testing : 1 == 1?
  # expected: 1
  # received: 1

then it returns the result of comparison of the $expected and the $received variables. Usually, the return value of this function is fed directly to the ok() function, like this:

  ok t_cmp(1, 1, "1 == 1?");

the third argument ($comment) is optional, mostly useful for telling what the comparison is trying to do.

It is valid to use undef as an expected value. Therefore:

  my $foo;
  t_cmp(undef, $foo, "undef == undef?");

will return a true value.

You can compare any two data-structures with t_cmp(). Just make sure that if you pass non-scalars, you have to pass their references. The datastructures can be deeply nested. For example you can compare:

  t_cmp({1 => [2..3,{5..8}], 4 => [5..6]},
        {1 => [2..3,{5..8}], 4 => [5..6]},
        "hash of array of hashes");

You can also compare the second argument against the first as a regex. Use the qr// function in the second argument. For example:

  t_cmp("abcd", qr/^abc/, "regex compare");

will do:

  "abcd" =~ /^abc/;

This function is exported by default.

t_filepath_cmp()

This function is used to compare two filepaths via t_cmp(). For non-Win32, it simply uses t_cmp() for the comparison, but for Win32, Win32::GetLongPathName() is invoked to convert the first two arguments to their DOS long pathname. This is useful when there is a possibility the two paths being compared are not both represented by their long or short pathname.

This function is exported by default.

t_debug()
  t_debug("testing feature foo");
  t_debug("test", [1..3], 5, {a=>[1..5]});

t_debug() prints out any datastructure while prepending # at the beginning of each line, to make the debug printouts comply with Test::Harness's requirements. This function should be always used for debug prints, since if in the future the debug printing will change (e.g. redirected into a file) your tests won't need to be changed.

the special global variable $Apache::TestUtil::DEBUG_OUTPUT can be used to redirect the output from t_debug() and related calls such as t_write_file(). for example, from a server-side test you would probably need to redirect it to STDERR:

  sub handler {
    plan $r, tests => 1;

    local $Apache::TestUtil::DEBUG_OUTPUT = \*STDERR;

    t_write_file('/tmp/foo', 'bar');
    ...
      }

left to its own devices, t_debug() will collide with the standard HTTP protocol during server-side tests, resulting in a situation both confusing difficult to debug. but STDOUT is left as the default, since you probably don't want debug output under normal circumstances unless running under verbose mode.

This function is exported by default.

t_write_file()
  t_write_file($filename, @lines);

t_write_file() creates a new file at $filename or overwrites the existing file with the content passed in @lines. If only the $filename is passed, an empty file will be created.

If parent directories of $filename don't exist they will be automagically created.

The generated file will be automatically deleted at the end of the program's execution.

This function is exported by default.

t_append_file()
  t_append_file($filename, @lines);

t_append_file() is similar to t_write_file(), but it doesn't clobber existing files and appends @lines to the end of the file. If the file doesn't exist it will create it.

If parent directories of $filename don't exist they will be automagically created.

The generated file will be registered to be automatically deleted at the end of the program's execution, only if the file was created by t_append_file().

This function is exported by default.

t_write_shell_script()
  Apache::TestUtil::t_write_shell_script($filename, @lines);

Similar to t_write_file() but creates a portable shell/batch script. The created filename is constructed from $filename and an appropriate extension automatically selected according to the platform the code is running under.

It returns the extension of the created file.

t_write_perl_script()
  Apache::TestUtil::t_write_perl_script($filename, @lines);

Similar to t_write_file() but creates a executable Perl script with correctly set shebang line.

t_open_file()
  my $fh = t_open_file($filename);

t_open_file() opens a file $filename for writing and returns the file handle to the opened file.

If parent directories of $filename don't exist they will be automagically created.

The generated file will be automatically deleted at the end of the program's execution.

This function is exported by default.

t_mkdir()
  t_mkdir($dirname);

t_mkdir() creates a directory $dirname. The operation will fail if the parent directory doesn't exist.

If parent directories of $dirname don't exist they will be automagically created.

The generated directory will be automatically deleted at the end of the program's execution.

This function is exported by default.

t_rmtree()
  t_rmtree(@dirs);

t_rmtree() deletes the whole directories trees passed in @dirs.

This function is exported by default.

t_chown()
  Apache::TestUtil::t_chown($file);

Change ownership of $file to the test's User/Group. This function is noop on platforms where chown(2) is unsupported (e.g. Win32).

t_is_equal()
  t_is_equal($a, $b);

t_is_equal() compares any two datastructures and returns 1 if they are exactly the same, otherwise 0. The datastructures can be nested hashes, arrays, scalars, undefs or a combination of any of these. See t_cmp() for an example.

If $b is a regex reference, the regex comparison $a =~ $b is performed. For example:

  t_is_equal($server_version, qr{^Apache});

If comparing non-scalars make sure to pass the references to the datastructures.

This function is exported by default.

t_server_log_error_is_expected()

If the handler's execution results in an error or a warning logged to the error_log file which is expected, it's a good idea to have a disclaimer printed before the error itself, so one can tell real problems with tests from expected errors. For example when testing how the package behaves under error conditions the error_log file might be loaded with errors, most of which are expected.

For example if a handler is about to generate a run-time error, this function can be used as:

  use Apache::TestUtil;
  ...
  sub handler {
      my $r = shift;
      ...
      t_server_log_error_is_expected();
      die "failed because ...";
  }

After running this handler the error_log file will include:

  *** The following error entry is expected and harmless ***
  [Tue Apr 01 14:00:21 2003] [error] failed because ...

When more than one entry is expected, an optional numerical argument, indicating how many entries to expect, can be passed. For example:

  t_server_log_error_is_expected(2);

will generate:

  *** The following 2 error entries are expected and harmless ***

If the error is generated at compile time, the logging must be done in the BEGIN block at the very beginning of the file:

  BEGIN {
      use Apache::TestUtil;
      t_server_log_error_is_expected();
  }
  use DOES_NOT_exist;

After attempting to run this handler the error_log file will include:

  *** The following error entry is expected and harmless ***
  [Tue Apr 01 14:04:49 2003] [error] Can't locate "DOES_NOT_exist.pm"
  in @INC (@INC contains: ...

Also see t_server_log_warn_is_expected() which is similar but used for warnings.

This function is exported by default.

t_server_log_warn_is_expected()

t_server_log_warn_is_expected() generates a disclaimer for expected warnings.

See the explanation for t_server_log_error_is_expected() for more details.

This function is exported by default.

t_client_log_error_is_expected()

t_client_log_error_is_expected() generates a disclaimer for expected errors. But in contrast to t_server_log_error_is_expected() called by the client side of the script.

See the explanation for t_server_log_error_is_expected() for more details.

For example the following client script fails to find the handler:

  use Apache::Test;
  use Apache::TestUtil;
  use Apache::TestRequest qw(GET);

  plan tests => 1;

  t_client_log_error_is_expected();
  my $url = "/error_document/cannot_be_found";
  my $res = GET($url);
  ok t_cmp(404, $res->code, "test 404");

After running this test the error_log file will include an entry similar to the following snippet:

  *** The following error entry is expected and harmless ***
  [Tue Apr 01 14:02:55 2003] [error] [client 127.0.0.1]
  File does not exist: /tmp/test/t/htdocs/error

When more than one entry is expected, an optional numerical argument, indicating how many entries to expect, can be passed. For example:

  t_client_log_error_is_expected(2);

will generate:

  *** The following 2 error entries are expected and harmless ***

This function is exported by default.

t_client_log_warn_is_expected()

t_client_log_warn_is_expected() generates a disclaimer for expected warnings on the client side.

See the explanation for t_client_log_error_is_expected() for more details.

This function is exported by default.

t_catfile('a', 'b', 'c')

This function is essentially File::Spec->catfile, but on Win32 will use Win32::GetLongpathName() to convert the result to a long path name (if the result is an absolute file). The function is not exported by default.

t_catfile_apache('a', 'b', 'c')

This function is essentially File::Spec::Unix->catfile, but on Win32 will use Win32::GetLongpathName() to convert the result to a long path name (if the result is an absolute file). It is useful when comparing something to that returned by Apache, which uses a Unix-style specification with forward slashes for directory separators. The function is not exported by default.

t_start_error_log_watch(), t_finish_error_log_watch()

This pair of functions provides an easy interface for checking the presence or absense of any particular message or messages in the httpd error_log that were generated by the httpd daemon as part of a test suite. It is likely, that you should proceed this with a call to one of the t_*_is_expected() functions.

  t_start_error_log_watch();
  do_it;
  ok grep {...} t_finish_error_log_watch()

AUTHOR

Stas Bekman <stas@stason.org>

SEE ALSO

perl(1)


Apache::XMLRPC::Lite - mod_perl-based XML-RPC server with minimum configuration

  • CONFIGURATION
  • DEPENDENCIES
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

Apache::XMLRPC::Lite - mod_perl-based XML-RPC server with minimum configuration

SYNOPSIS

httpd.conf (Location), directory-based access
  <Location /mod_xmlrpc>
    SetHandler perl-script
    PerlHandler Apache::XMLRPC::Lite
    PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
    PerlSetVar options "compress_threshold => 10000"
  </Location>
httpd.conf (Files), file-based access
  <FilesMatch "\.xmlrpc$">
    SetHandler perl-script
    PerlHandler Apache::XMLRPC::Lite
    PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
    PerlSetVar options "compress_threshold => 10000"
  </FilesMatch>
.htaccess, directory-based access
  SetHandler perl-script
  PerlHandler Apache::XMLRPC::Lite
  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
  PerlSetVar options "compress_threshold => 10000"

DESCRIPTION

This Apache Perl module provides the ability to add support for XML-RPC protocol with easy configuration (either in .conf or in .htaccess file). This functionality should give you lightweight option for hosting SOAP services and greatly simplify configuration aspects. This module inherites functionality from XMLRPC::Transport::HTTP::Apache component of XMLRPC::Lite module.

CONFIGURATION

The module can be placed in <Location>, <Directory>, <Files>, <FilesMatch> directives in main server configuration areas or directly in .htaccess file.

All parameters should be quoted and can be separated with commas or spaces for lists ("a, b, c") and with 'wide arrows' and commas for hash parameters ("key1 => value1, key2 => value2").

All options that you can find in XMLRPC::Transport::HTTP::Apache component are available for configuration. Here is the description of most important ones.

dispatch_to (LIST)

Specifies path to directory that contains Perl modules you'd like to give access to, or just list of modules (for preloaded modules).

  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
options (HASH)

Specifies list of options for your module, for example threshold for compression. Future versions will support more options. See XMLRPC::Transport::HTTP documentation for other options.

  PerlSetVar options "compress_threshold => 10000"

DEPENDENCIES

 XMLRPC::Lite
 mod_perl

SEE ALSO

 XMLRPC::Transport::HTTP::Apache for implementation details,
 XMLRPC::Lite for general information, and
 F<examples/server/mod_xmlrpc.htaccess> for .htaccess example

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


Apache2::Access - A Perl API for Apache request object: Access, Authentication and Authorization.

  • Synopsis
  • Description
  • API
    • allow_methods
    • allow_options
    • allow_overrides
    • allow_override_opts
    • auth_name
    • auth_type
    • get_basic_auth_pw
    • get_remote_logname
    • note_auth_failure
    • note_basic_auth_failure
    • note_digest_auth_failure
    • requires
    • satisfies
    • some_auth_required
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Access - A Perl API for Apache request object: Access, Authentication and Authorization.

Synopsis

  use Apache2::Access ();

  # allow only GET method
  $r->allow_methods(1, qw(GET));

  # Apache Options value
  $options = $r->allow_options();

  # Apache AllowOverride value
  $allow_override = $r->allow_overrides();

  # which Options are allowed by AllowOverride (since Apache 2.2)
  $allow_override_opts = $r->allow_override_opts();

  # auth name ("foo bar")
  $auth_name = $r->auth_name();

  # auth type
  $auth_type = $r->auth_type();
  $r->auth_type("Digest");

  # Basic authentication process
  my ($rc, $passwd) = $r->get_basic_auth_pw();

  # the login name of the remote user (RFC1413)
  $remote_logname = $r->get_remote_logname();

  # dynamically figure out which auth has failed
  $r->note_auth_failure();

  # note Basic auth failure
  $r->note_basic_auth_failure();

  # note Digest auth failure
  $r->note_digest_auth_failure();

  # Apache Request value(s)
  $requires = $r->requires();

  # Apache Satisfy value (as a number)
  $satisfy = $r->satisfies();

  # check whether some auth is configured
  $need_auth = $r->some_auth_required();

Description

The API provided by this module deals with access, authentication and authorization phases.

Apache2::Access extends Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec|/Description.

API

Apache2::Access provides the following functions and/or methods:

allow_methods

Specify which HTTP methods are allowed

  $r->allow_methods($reset);
  $r->allow_methods($reset, @methods);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $reset ( boolean )

If a true value is passed all the previously allowed methods are removed. Otherwise the list is left intact.

opt arg2: @methods ( array of strings )

a list of HTTP methods to be allowed (e.g. GET and POST)

ret: no return value
since: 2.0.00

For example: here is how to allow only GET and POST methods, regardless to what was the previous setting:

  $r->allow_methods(1, qw(GET POST));

allow_options

Retrieve the value of Options for this request

  $options = $r->allow_options();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $options ( integer )

the Options bitmask. Normally used with bitlogic operators against Apache2::Const :options constants|docs::2.0::api::Apache2::Const/C__options_.

since: 2.0.00

For example if the configuration for the current request was:

  Options None
  Options Indexes FollowSymLinks

The following applies:

  use Apache2::Const -compile => qw(:options);
  $r->allow_options & Apache2::Const::OPT_INDEXES;   # TRUE
  $r->allow_options & Apache2::Const::OPT_SYM_LINKS; # TRUE
  $r->allow_options & Apache2::Const::OPT_EXECCGI;   # FALSE

allow_overrides

Retrieve the value of AllowOverride for this request

  $allow_override = $r->allow_overrides();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $allow_override ( integer )

the AllowOverride bitmask. Normally used with bitlogic operators against Apache2::Const :override constants|docs::2.0::api::Apache2::Const/C__override_.

since: 2.0.00

For example if the configuration for the current request was:

  AllowOverride AuthConfig

The following applies:

  use Apache2::Const -compile => qw(:override);
  $r->allow_overrides & Apache2::Const::OR_AUTHCFG; # TRUE
  $r->allow_overrides & Apache2::Const::OR_LIMIT; # FALSE

allow_override_opts

Retrieve the bitmask of allowed Options set by AllowOverride Options=... for this request

  $override_opts = $r->allow_override_opts();

Enabling single options was introduced in Apache 2.2. For Apache 2.0 this
function returns
Apache2::Const::OPT_UNSET|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_UNSET_ |
Apache2::Const::OPT_ALL|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_ALL_ |
Apache2::Const::OPT_INCNOEXEC|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_INCNOEXEC_ |
Apache2::Const::OPT_SYM_OWNER|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_SYM_OWNER_ |
Apache2::Const::OPT_MULTI|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_MULTI_,
which corresponds to the default value (if not set) for Apache 2.2.

obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $override_opts ( integer )

the override options bitmask. Normally used with bitlogic operators against Apache2::Const :options constants|docs::2.0::api::Apache2::Const/C__options_.

since: 2.0.3

For example if the configuration for the current request was:

  AllowOverride Options=Indexes,ExecCGI

The following applies:

  use Apache2::Const -compile => qw(:options);
  $r->allow_override_opts & Apache2::Const::OPT_EXECCGI; # TRUE
  $r->allow_override_opts & Apache2::Const::OPT_SYM_LINKS; # FALSE

auth_name

Get/set the current Authorization realm (the per directory configuration directive AuthName):

  $auth_name = $r->auth_name();
  $auth_name = $r->auth_name($new_auth_name);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

opt arg1: $new_auth_name ( string )

If $new_auth_name is passed a new AuthName value is set

ret: $ ( integer )

The current value of AuthName

since: 2.0.00

The AuthName directive creates protection realm within the server document space. To quote RFC 1945 "These realms allow the protected resources on a server to be partitioned into a set of protection spaces, each with its own authentication scheme and/or authorization database." The client uses the root URL of the server to determine which authentication credentials to send with each HTTP request. These credentials are tagged with the name of the authentication realm that created them. Then during the authentication stage the server uses the current authentication realm, from $r->auth_name, to determine which set of credentials to authenticate.

auth_type

Get/set the type of authorization required for this request (the per directory configuration directive AuthType):

  $auth_type = $r->auth_type();
  $auth_type = $r->auth_type($new_auth_type);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

opt arg1: $new_auth_type ( string )

If $new_auth_type is passed a new AuthType value is set

ret: $ ( integer )

The current value of AuthType

since: 2.0.00

Normally AuthType would be set to Basic to use the basic authentication scheme defined in RFC 1945, Hypertext Transfer Protocol -- HTTP/1.0. However, you could set to something else and implement your own authentication scheme.

get_basic_auth_pw

Get the password from the request headers

  my ($rc, $passwd) = $r->get_basic_auth_pw();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret1: $rc ( Apache2::Const constant|docs::2.0::api::Apache2::Const )

Apache2::Const::OK if the $passwd value is set (and assured a correct value in $r->user|docs::2.0::api::Apache2::RequestRec/C_user_); otherwise it returns an error code, either Apache2::Const::HTTP_INTERNAL_SERVER_ERROR if things are really confused, Apache2::Const::HTTP_UNAUTHORIZED if no authentication at all seemed to be in use, or Apache2::Const::DECLINED if there was authentication, but it wasn't Basic (in which case, the caller should presumably decline as well).

ret2: $ret (string)

The password as set in the headers (decoded)

since: 2.0.00

If AuthType|/C_auth_type_ is not set, this handler first sets it to Basic.

get_remote_logname

Retrieve the login name of the remote user (RFC1413)

  $remote_logname = $r->get_remote_logname();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $remote_logname ( string )

The username of the user logged in to the client machine, or an empty string if it could not be determined via RFC1413, which involves querying the client's identd or auth daemon.

since: 2.0.00

Do not confuse this method with $r->user|docs::2.0::api::Apache2::RequestRec/C_user_, which provides the username provided by the user during the server authentication.

note_auth_failure

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works for both basic and digest authentication

  $r->note_auth_failure();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: no return value
since: 2.0.00

This method requires AuthType to be set to Basic or Digest. Depending on the setting it'll call either $r->note_basic_auth_failure|/C_note_basic_auth_failure_ or $r->note_digest_auth_failure|/C_note_digest_auth_failure_.

note_basic_auth_failure

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for basic authentication

  $r->note_basic_auth_failure();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: no return value
since: 2.0.00

note_digest_auth_failure

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for digest authentication.

  $r->note_digest_auth_failure();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: no return value
since: 2.0.00

requires

Retrieve information about all of the requires directives for this request

  $requires = $r->requires
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $requires ( ARRAY ref )

Returns an array reference of hash references, containing information related to the require directive.

since: 2.0.00

This is normally used for access control.

For example if the configuration had the following require directives:

    Require user  goo bar
    Require group bar tar

this method will return the following datastructure:

  [
    {
      'method_mask' => -1,
      'requirement' => 'user goo bar'
    },
    {
      'method_mask' => -1,
      'requirement' => 'group bar tar'
    }
  ];

The requirement field is what was passed to the Require directive. The method_mask field is a bitmask which can be modified by the Limit directive, but normally it can be safely ignored as it's mostly used internally. For example if the configuration was:

    Require user goo bar
    Require group bar tar
    <Limit POST>
       Require valid-user
    </Limit>

and the request method was POST, $r->requires will return:

  [
    {
      'method_mask' => -1,
      'requirement' => 'user goo bar'
    },
    {
      'method_mask' => -1,
      'requirement' => 'group bar tar'
    }
    {
      'method_mask' => 4,
      'requirement' => 'valid-user'
    }
  ];

But if the request method was GET, it will return only:

  [
    {
      'method_mask' => -1,
      'requirement' => 'user goo bar'
    },
    {
      'method_mask' => -1,
      'requirement' => 'group bar tar'
    }
  ];

As you can see Apache gives you the requirements relevant for the current request, so the method_mask is irrelevant.

It is also a good time to remind that in the general case, access control directives should not be placed within a <Limit> section. Refer to the Apache documentation for more information.

Using the same configuration and assuming that the request was of type POST, the following code inside an Auth handler:

  my %require =
      map { my ($k, $v) = split /\s+/, $_->{requirement}, 2; ($k, $v||'') }
      @{ $r->requires };

will populate %require with the following pairs:

  'group' => 'bar tar',
  'user' => 'goo bar',
  'valid-user' => '',

satisfies

How the requires lines must be met. What's the applicable value of the Satisfy directive:

  $satisfy = $r->satisfies();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $satisfy ( integer )

How the requirements must be met. One of the Apache2::Const :satisfy constants|docs::2.0::api::Apache2::Const/C__satisfy_:

Apache2::Const::SATISFY_ANY|docs::2.0::api::Apache2::Const/C_Apache2__Const__SATISFY_ANY_, Apache2::Const::SATISFY_ALL|docs::2.0::api::Apache2::Const/C_Apache2__Const__SATISFY_ALL_ and Apache2::Const::SATISFY_NOSPEC|docs::2.0::api::Apache2::Const/C_Apache2__Const__SATISFY_NOSPEC_.

since: 2.0.00

See the documentation for the Satisfy directive in the Apache documentation.

some_auth_required

Can be used within any handler to determine if any authentication is required for the current request:

  $need_auth = $r->some_auth_required();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $need_auth ( boolean )

TRUE if authentication is required, FALSE otherwise

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Build - Methods for locating and parsing bits of Apache source code

  • METHODS
  • AUTHOR

NAME

Apache2::Build - Methods for locating and parsing bits of Apache source code

SYNOPSIS

 use Apache2::Build ();
 my $build = Apache2::Build->new;

 # rebuild mod_perl with build opts from the previous build
 % cd modperl-2.0
 % perl -MApache2::Build -e rebuild

DESCRIPTION

This module provides methods for locating and parsing bits of Apache source code.

Since mod_perl remembers what build options were used to build it, you can use this knowledge to rebuild it using the same options. Simply chdir to the mod_perl source directory and run:

  % cd modperl-2.0
  % perl -MApache2::Build -e rebuild

If you want to rebuild not yet installed, but already built mod_perl, run from its root directory:

  % perl -Ilib -MApache2::Build -e rebuild

METHODS

new

Create an object blessed into the Apache2::Build class.

 my $build = Apache2::Build->new;
dir

Top level directory where source files are located.

 my $dir = $build->dir;
 -d $dir or die "can't stat $dir $!\n";
find

Searches for apache source directories, return a list of those found.

Example:

 for my $dir ($build->find) {
    my $yn = prompt "Configure with $dir ?", "y";
    ...
 }
inc

Print include paths for MakeMaker's INC argument to WriteMakefile.

Example:

 use ExtUtils::MakeMaker;

 use Apache2::Build ();

 WriteMakefile(
     'NAME'    => 'Apache2::Module',
     'VERSION' => '0.01',
     'INC'     => Apache2::Build->new->inc,
 );
module_magic_number

Return the MODULE_MAGIC_NUMBER defined in the apache source.

Example:

 my $mmn = $build->module_magic_number;
httpd_version

Return the server version.

Example:

 my $v = $build->httpd_version;
otherldflags

Return other ld flags for MakeMaker's dynamic_lib argument to WriteMakefile. This might be needed on systems like AIX that need special flags to the linker to be able to reference mod_perl or httpd symbols.

Example:

 use ExtUtils::MakeMaker;

 use Apache2::Build ();

 WriteMakefile(
     'NAME'        => 'Apache2::Module',
     'VERSION'     => '0.01',
     'INC'         => Apache2::Build->new->inc,
     'dynamic_lib' => {
         'OTHERLDFLAGS' => Apache2::Build->new->otherldflags,
     },
 );

AUTHOR

Doug MacEachern


Apache2::CmdParms - Perl API for Apache command parameters object

  • Synopsis
  • Description
  • API
    • add_config
    • check_cmd_context
    • cmd
    • directive
    • info
    • method_is_limited
    • override
    • override_opts
    • path
    • pool
    • server
    • temp_pool
  • Unsupported API
    • context
  • See Also
  • Copyright
  • Authors

NAME

Apache2::CmdParms - Perl API for Apache command parameters object

Synopsis

  use Apache2::CmdParms ();
  use Apache2::Module ();
  use Apache2::Const -compile => qw(NOT_IN_LOCATION);

  my @directives = (
    {
      name => 'MyDirective',
      cmd_data => 'some extra data',
    },
  );

  Apache2::Module::add(__PACKAGE__, \@directives);

  sub MyDirective {
      my ($self, $parms, $args) = @_;

      # push config
      $parms->add_config(['ServerTokens off']);

      # this command's command object
      $cmd = $parms->cmd;

      # check the current command's context
      $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);

      # this command's context
      $context = $parms->context;

      # this command's directive object
      $directive = $parms->directive;

      # the extra information passed thru cmd_data to
      # Apache2::Module::add()
      $info = $parms->info;

      # which methods are <Limit>ed ?
      $is_limited = $parms->method_is_limited('GET');

      # which allow-override bits are set
      $override = $parms->override;

      # which Options are allowed by AllowOverride (since Apache 2.2)
      $override = $parms->override_opts;

      # the path this command is being invoked in
      $path = $parms->path;

      # this command's pool
      $p = $parms->pool;

      # this command's configuration time pool
      $p = $parms->temp_pool;
  }

Description

Apache2::CmdParms provides the Perl API for Apache command parameters object.

API

Apache2::CmdParms provides the following functions and/or methods:

add_config

Dynamically add Apache configuration at request processing runtime:

  $parms->add_config($lines);
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
arg1: $lines (ARRAY ref)

An ARRAY reference containing configuration lines per element, without the new line terminators.

ret: no return value
since: 2.0.00

See also: $s->add_config|docs::2.0::api::Apache2::ServerUtil/C_add_config_, $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_add_config_

check_cmd_context

Check the current command against a context bitmask of forbidden contexts.

  $error = $parms->check_cmd_context($check);
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
arg1: $check ( Apache2::Const :context constant|docs::2.0::api::Apache2::Const/C__context_ )

the context to check against.

ret: $error ( string / undef )

If the context is forbidden, this method returns a textual description of why it was forbidden. If the context is permitted, this method returns undef.

since: 2.0.00

For example here is how to check whether a command is allowed in the <Location> container:

  use Apache2::Const -compile qw(NOT_IN_LOCATION);
  if (my $error = $parms->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
      die "directive ... not allowed in <Location> context"
  }

cmd

This module's command information

  $cmd = $parms->cmd();
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
since: 2.0.00

directive

This command's directive object in the configuration tree

  $directive = $parms->directive;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $directive ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

The current directive node in the configuration tree

since: 2.0.00

info

The extra information passed through cmd_data in Apache2::Module::add()|docs::2.0::api::Apache2::Module/C_add_.

  $info = $parms->info;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $info ( string )

The string passed in cmd_data

since: 2.0.00

For example here is how to pass arbitrary information to a directive subroutine:

  my @directives = (
    {
      name => 'MyDirective1',
      func => \&MyDirective,
      cmd_data => 'One',
    },
    {
      name => 'MyDirective2',
      func => \&MyDirective,
      cmd_data => 'Two',
    },
  );
  Apache2::Module::add(__PACKAGE__, \@directives);

  sub MyDirective {
    my ($self, $parms, $args) = @_;
    my $info = $parms->info;
  }

In this example $info will either be 'One' or 'Two' depending on whether the directive was called as MyDirective1 or MyDirective2.

method_is_limited

Discover if a method is <Limit>ed in the current scope

  $is_limited = $parms->method_is_limited($method);
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
arg1: $method (string)

The name of the method to check for

ret: $is_limited ( boolean )
since: 2.0.00

For example, to check if the GET method is being <Limit>ed in the current scope, do:

  if ($parms->method_is_limited('GET') {
      die "...";
  }

override

Which allow-override bits are set (AllowOverride directive)

  $override = $parms->override;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $override ( bitmask )

the allow-override bits bitmask, which can be tested against Apache2::Const :override constants|docs::2.0::api::Apache2::Const/C__override_.

since: 2.0.00

For example to check that the AllowOverride's AuthConfig and FileInfo options are enabled for this command, do:

  use Apache2::Const -compile qw(:override);
  $wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
  $masked = $parms->override & $wanted;
  unless ($wanted == $masked) {
      die "...";
  }

override_opts

Which options are allowed to be overridden by .htaccess files. This is set by AllowOverride Options=....

  $override_opts = $parms->override_opts;

Enabling single options was introduced with Apache 2.2. For Apache 2.0 this function simply returns a bitmask with all options allowed.

obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $override_opts ( bitmask )

the bitmask, which can be tested against Apache2::Const :options constants|docs::2.0::api::Apache2::Const/C__override_.

since: 2.0.3

path

The current pathname/location/match of the block this command is in

  $path = $parms->path;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $path ( string / undef )

If configuring for a block like <Location>, <LocationMatch>, <Directory>, etc., the pathname part of that directive. Otherwise, undef is returned.

since: 2.0.00

For example for a container block:

  <Location /foo>
  ...
  </Location>

'/foo' will be returned.

pool

Pool associated with this command

  $p = $parms->pool;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

server

The (vhost) server this command was defined in httpd.conf

  $s = $parms->server;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $s ( Apache2::Server object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.00

temp_pool

Pool for scratch memory; persists during configuration, but destroyed before the first request is served.

  $temp_pool = $parms->temp_pool;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $temp_pool ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

Most likely you shouldn't use this pool object, unless you know what you are doing. Use $parms->pool|/C_pool_ instead.

Unsupported API

Apache2::CmdParms also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

context

Get context containing pointers to modules' per-dir config structures.

  $context = $parms->context;
obj: $parms ( Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms )
ret: $newval ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )

Returns the commands' per-dir config structures

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Command - Perl API for accessing Apache module command information

  • Synopsis
  • Description
  • API
    • args_how
    • errmsg
    • name
    • next
    • req_override
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Command - Perl API for accessing Apache module command information

Synopsis

  use Apache2::Module ();
  use Apache2::Command ();
  my $module = Apache2::Module::find_linked_module('mod_perl.c');

  for (my $cmd = $module->cmds; $cmd; $cmd = $cmd->next) {
      $cmd->args_how();
      $cmd->errmsg();
      $cmd->name();
      $cmd->req_override();
  }

Description

Apache2::Command provides the Perl API for accessing Apache module command information

API

Apache2::Command provides the following functions and/or methods:

args_how

What the command expects as arguments:

  $how = $cmd->args_how();
obj: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
ret: $how ( Apache2::Const :cmd_how constant|docs::2.0::api::Apache2::Const/C__cmd_how_ )

The flag value representing the type of this command (i.e. Apache2::Const::ITERATE, Apache2::Const::TAKE2).

since: 2.0.00

errmsg

Get usage message for that command, in case of syntax errors:

  $error = $cmd->errmsg();
obj: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
ret: $error ( string )

The error message

since: 2.0.00

name

Get the name of this command:

  $name = $cmd->name();
obj: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
ret: $name ( string )

The command name

since: 2.0.00

next

Get the next command in the chain of commands for this module:

  $next = $cmd->next();
obj: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
ret: $next ( Apache2::Command object|docs::2.0::api::Apache2::Command )

Returns the next command in the chain for this module, undef for the last command.

since: 2.0.00

req_override

What overrides need to be allowed to enable this command:

  $override = $cmd->req_override
obj: $cmd ( Apache2::Command object|docs::2.0::api::Apache2::Command )
ret: $override ( Apache2::Const :override constant|docs::2.0::api::Apache2::Const/C__override_ )

The bit mask representing the overrides this command is allowed in (i.e Apache2::Const::OR_ALL/Apache2::Const::ACCESS_CONF).

since: 2.0.00

For example:

  use Apache2::Const -compile => qw(:override);
  $cmd->req_override() & Apache2::Const::OR_AUTHCFG;
  $cmd->req_override() & Apache2::Const::OR_LIMIT;

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Connection - Perl API for Apache connection object

  • Synopsis
  • Description
  • API
    • aborted
    • base_server
    • bucket_alloc
    • client_socket
    • get_remote_host
    • id
    • input_filters
    • keepalive
    • keepalives
    • local_addr
    • local_host
    • local_ip
    • notes
    • output_filters
    • pool
    • remote_addr
    • remote_ip
    • remote_host
  • Unsupported API
    • conn_config
    • sbh
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Connection - Perl API for Apache connection object

Synopsis

  use Apache2::Connection ();
  use Apache2::RequestRec ();

  my $c = $r->connection;

  my $c = $r->connection;
  # is connection still open?
  $status = $c->aborted;

  # base server
  $base_server = $c->base_server();

  # needed for creating buckets/brigades
  $ba = $c->bucket_alloc();

  # client's socket
  $socket = $c->client_socket;

  # unique connection id
  $id = $c->id();

  # connection filters stack
  $input_filters = $c->input_filters();
  $output_filters = $c->output_filters();

  # keep the connection alive?
  $status = $c->keepalive();

  # how many requests served over the current connection
  $served = $c->keepalives();

  # this connection's local and remote socket addresses
  $local_sa  = $c->local_addr();
  $remote_sa = $c->remote_addr();

  # local and remote hostnames
  $local_host = $c->local_host();
  $remote_host = $c->get_remote_host();
  $remote_host = $c->remote_host();

  # server and remote client's IP addresses
  $local_ip = $c->local_ip();
  $remote_ip = $c->remote_ip();

  # connection level Apache notes
  $notes = $c->notes();

  # this connection's pool
  $p = $c->pool();

Description

Apache2::RequestRec provides the Perl API for Apache connection record object.

API

Apache2::Connection provides the following functions and/or methods:

aborted

Check whether the connection is still open

  $status = $c->aborted();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $status ( boolean )

true if the connection has been aborted, false if still open

since: 2.0.00

base_server

Physical server this connection came in on (main server or vhost):

  $base_server = $c->base_server();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $base_server ( Apache2::Server object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.00

bucket_alloc

The bucket allocator to use for all bucket/brigade creations

  $ba = $c->bucket_alloc();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $ba ( APR::BucketAlloc object|docs::2.0::api::APR::BucketAlloc )
since: 2.0.00

This object is needed by APR::Bucket|docs::2.0::api::APR::Bucket and APR::Brigade|docs::2.0::api::APR::Brigade methods/functions.

client_socket

Get/set the client socket

  $socket      = $c->client_socket;
  $prev_socket = $c->client_socket($new_socket);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_socket ( APR::Socket object|docs::2.0::api::APR::Socket object )

If passed a new socket will be set.

ret: $socket ( APR::Socket object|docs::2.0::api::APR::Socket object )

current client socket

if the optional argument $new_socket was passed the previous socket object is returned.

since: 2.0.00

get_remote_host

Lookup the client's DNS hostname or IP address

  $remote_host = $c->remote_host();
  $remote_host = $c->remote_host($type);
  $remote_host = $c->remote_host($type, $dir_config);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )

The current connection

opt arg1: $type ( :remotehost constant|docs::2.0::api::Apache2::Const/C__remotehost_ )

The type of lookup to perform:

Apache2::Const::REMOTE_DOUBLE_REV

will always force a DNS lookup, and also force a double reverse lookup, regardless of the HostnameLookups setting. The result is the (double reverse checked) hostname, or undef if any of the lookups fail.

Apache2::Const::REMOTE_HOST

returns the hostname, or undef if the hostname lookup fails. It will force a DNS lookup according to the HostnameLookups setting.

Apache2::Const::REMOTE_NAME

returns the hostname, or the dotted quad if the hostname lookup fails. It will force a DNS lookup according to the HostnameLookups setting.

Apache2::Const::REMOTE_NOLOOKUP

is like Apache2::Const::REMOTE_NAME except that a DNS lookup is never forced.

Default value is Apache2::Const::REMOTE_NAME.

opt arg2: $dir_config ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )

The directory config vector from the request. It's needed to find the container in which the directive HostnameLookups is set. To get one for the current request use $r->per_dir_config|docs::2.0::api::Apache2::RequestRec/C_per_dir_config_.

By default, undef is passed, in which case it's the same as if HostnameLookups was set to Off.

ret: $remote_host ( string/undef )

The remote hostname. If the configuration directive HostNameLookups is set to off, this returns the dotted decimal representation of the client's IP address instead. Might return undef if the hostname is not known.

since: 2.0.00

The result of get_remote_host call is cached in $c->remote_host|/C_remote_host_. If the latter is set, get_remote_host will return that value immediately, w/o doing any checkups.

id

ID of this connection; unique at any point in time

  $id = $c->id();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $id (integer)
since: 2.0.00

input_filters

Get/set the first filter in a linked list of protocol level input filters:

  $input_filters      = $c->input_filters();
  $prev_input_filters = $c->input_filters($new_input_filters);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_input_filters

Set a new value

ret: $input_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the connection input filters chain.

If $new_input_filters was passed, returns the previous value.

since: 2.0.00

For an example see: Bucket Brigades-based Protocol Module

keepalive

This method answers the question: Should the the connection be kept alive for another HTTP request after the current request is completed?

  $status = $c->keepalive();
  $status = $c->keepalive($new_status);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_status ( :conn_keepalive constant|docs::2.0::api::Apache2::Const/C__conn_keepalive_ )

Normally you should not mess with setting this option when handling the HTTP protocol. If you do (for example when sending your own headers set with $r->assbackwards|docs::2.0::api::Apache2::RequestRec/C_assbackwards_) -- take a look at the ap_set_keepalive() function in httpd-2.0/modules/http/http_protocol.c.

ret: $status ( :conn_keepalive constant|docs::2.0::api::Apache2::Const/C__conn_keepalive_ )

The method does not return true or false, but one of the states which can be compared against (:conn_keepalive constants|docs::2.0::api::Apache2::Const/C__conn_keepalive_).

since: 2.0.00

Unless you set this value yourself when implementing non-HTTP protocols, it's only relevant for HTTP requests.

For example:

  use Apache2::RequestRec ();
  use Apache2::Connection ();

  use Apache2::Const -compile => qw(:conn_keepalive);
  ...
  my $c = $r->connection;
  if ($c->keepalive == Apache2::Const::CONN_KEEPALIVE) {
      # do something
  }
  elsif ($c->keepalive == Apache2::Const::CONN_CLOSE) {
      # do something else
  }
  elsif ($c->keepalive == Apache2::Const::CONN_UNKNOWN) {
      # do yet something else
  }
  else {
      # die "unknown state";
  }

Notice that new states could be added later by Apache, so your code should make no assumptions and do things only if the desired state matches.

keepalives

How many requests were already served over the current connection.

  $served = $c->keepalives();
  $served = $c->keepalives($new_served);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_served (integer)

Set the number of served requests over the current connection. Normally you won't do that when handling HTTP requests. (But see below a note regarding $r->assbackwards|docs::2.0::api::Apache2::RequestRec/C_assbackwards_).

ret: $served (integer)

How many requests were already served over the current connection.

In most handlers, but HTTP output filter handlers, that value doesn't count the current request. For the latter it'll count the current request.

since: 2.0.00

This method is only relevant for keepalive connections. The core connection output filter ap_http_header_filter increments this value when the response headers are sent and it decides that the connection should not be closed (see ap_set_keepalive()).

If you send your own set of HTTP headers with $r->assbackwards|docs::2.0::api::Apache2::RequestRec/C_assbackwards_, which includes the Keep-Alive HTTP response header, you must make sure to increment the keepalives counter.

local_addr

Get this connection's local socket address

  $local_sa = $c->local_addr();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $local_sa ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
since: 2.0.00

local_host

used for ap_get_server_name when UseCanonicalName is set to DNS (ignores setting of HostnameLookups)

  $local_host = $c->local_host();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $local_host (string)
since: 2.0.00

META: you probably shouldn't use this method, but ( get_server_name|docs::2.0::api::Apache2::RequestUtil/C_get_server_name_ ) if inside request and $r is available.

local_ip

server IP address

  $local_ip = $c->local_ip();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $local_ip (string)
since: 2.0.00

notes

Get/set text notes for the duration of this connection. These notes can be passed from one module to another (not only mod_perl, but modules in any other language):

  $notes      = $c->notes();
  $prev_notes = $c->notes($new_notes);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_notes ( APR::Table object|docs::2.0::api::APR::Table )
ret: $notes ( APR::Table object|docs::2.0::api::APR::Table )

the current notes table.

if the $new_notes argument was passed, returns the previous value.

since: 2.0.00

Also see $r->notes|docs::2.0::api::Apache2::RequestRec/C_notes_

output_filters

Get the first filter in a linked list of protocol level output filters:

  $output_filters = $c->output_filters();
  $prev_output_filters = $r->output_filters($new_output_filters);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_output_filters

Set a new value

ret: $output_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the connection output filters chain.

If $new_output_filters was passed, returns the previous value.

since: 2.0.00

For an example see: Bucket Brigades-based Protocol Module

pool

Pool associated with this connection

  $p = $c->pool();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

remote_addr

Get this connection's remote socket address

  $remote_sa = $c->remote_addr();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $remote_sa ( APR::SockAddr object|docs::2.0::api::APR::SockAddr )
since: 2.0.00

remote_ip

Client's IP address

  $remote_ip      = $c->remote_ip();
  $prev_remote_ip = $c->remote_ip($new_remote_ip);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $new_remote_ip ( string )

If passed a new value will be set

ret: $remote_ip ( string )

current remote ip address

if the optional argument $new_remote_ip was passed the previous value is returned.

since: 2.0.00

remote_host

Client's DNS name:

  $remote_host = $c->remote_host();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $remote_host ( string/undef )

If $c->get_remote_host|/C_get_remote_host_ was run it returns the cached value, which is a client DNS name or "" if it wasn't found. If the check wasn't run -- undef is returned.

since: 2.0.00

It's best to to call $c->get_remote_host|/C_get_remote_host_ instead of directly accessing this variable.

Unsupported API

Apache2::Connection also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

conn_config

Config vector containing pointers to connections per-server config structures

  $ret = $c->conn_config();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $ret ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )
since: 2.0.00

sbh

META: Autogenerated - needs to be reviewed/completed

handle to scoreboard information for this connection

  $sbh = $c->sbh();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
ret: $sbh (XXX)
since: 2.0.00

META: Not sure how this can be used from mod_perl at the moment. Unless Apache2::Scoreboard is extended to provide a hook to read from this variable.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::ConnectionUtil - Perl API for Apache connection utils

  • Synopsis
  • Description
  • API
    • pnotes
  • See Also
  • Copyright
  • Authors

NAME

Apache2::ConnectionUtil - Perl API for Apache connection utils

Synopsis

   use Apache2::Connection     ();
   use Apache2::ConnectionUtil ();
   use Apache2::RequestRec     ();

   # grab the connection object;
   my $c = $r->connection;

   # share perl objects like $r->pnotes
   $old_val = $c->pnotes($key => $value);

Description

Apache2::ConnectionUtil provides the Apache connection record object utilities API.

API

Apache2::ConnectionUtil provides the following functions and/or methods:

pnotes

Share Perl variables between requests over the lifetime of the connection.

   $old_val  = $c->pnotes($key => $val);
   $val      = $c->pnotes($key);
   $hash_ref = $c->pnotes();
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
opt arg1: $key ( string )

A key value

opt arg2: $val ( SCALAR )

Any scalar value (e.g. a reference to an array)

ret: (3 different possible values)

if both, $key and $val are passed the previous value for $key is returned if such existed, otherwise undef is returned.

if only $key is passed, the current value for the given key is returned.

if no arguments are passed, a hash reference is returned, which can then be directly accessed without going through the pnotes() interface.

since: 2.0.3

See (Apache2::RequestUtil::pnotes|docs::2.0::api::Apache2::RequestUtil/C_pnotes_) for the details of the pnotes method usage. The usage is identical except for a few differences. First is the use of $c instead of $r as the invocant. The second is that the the data persists for the lifetime of the connection instead of the lifetime of the request. If the connection is lost, so is the data stored in pnotes.

See Also

Apache2::Connection.

Apache2::RequestUtil::pnotes.

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Const - Perl Interface for Apache Constants

  • Synopsis
  • Description
  • Constants
    • :cmd_how
      • Apache2::Const::FLAG
      • Apache2::Const::ITERATE
      • Apache2::Const::ITERATE2
      • Apache2::Const::NO_ARGS
      • Apache2::Const::RAW_ARGS
      • Apache2::Const::TAKE1
      • Apache2::Const::TAKE12
      • Apache2::Const::TAKE123
      • Apache2::Const::TAKE13
      • Apache2::Const::TAKE2
      • Apache2::Const::TAKE23
      • Apache2::Const::TAKE3
    • :common
      • Apache2::Const::AUTH_REQUIRED
      • Apache2::Const::DECLINED
      • Apache2::Const::DONE
      • Apache2::Const::FORBIDDEN
      • Apache2::Const::NOT_FOUND
      • Apache2::Const::OK
      • Apache2::Const::REDIRECT
      • Apache2::Const::SERVER_ERROR
    • :config
      • Apache2::Const::DECLINE_CMD
    • :conn_keepalive
      • Apache2::Const::CONN_CLOSE
      • Apache2::Const::CONN_KEEPALIVE
      • Apache2::Const::CONN_UNKNOWN
    • :context
      • Apache2::Const::NOT_IN_VIRTUALHOST
      • Apache2::Const::NOT_IN_LIMIT
      • Apache2::Const::NOT_IN_DIRECTORY
      • Apache2::Const::NOT_IN_LOCATION
      • Apache2::Const::NOT_IN_FILES
      • Apache2::Const::NOT_IN_DIR_LOC_FILE
      • Apache2::Const::GLOBAL_ONLY
    • :filter_type
      • Apache2::Const::FTYPE_CONNECTION
      • Apache2::Const::FTYPE_CONTENT_SET
      • Apache2::Const::FTYPE_NETWORK
      • Apache2::Const::FTYPE_PROTOCOL
      • Apache2::Const::FTYPE_RESOURCE
      • Apache2::Const::FTYPE_TRANSCODE
    • :http
      • Apache2::Const::HTTP_ACCEPTED
      • Apache2::Const::HTTP_BAD_GATEWAY
      • Apache2::Const::HTTP_BAD_REQUEST
      • Apache2::Const::HTTP_CONFLICT
      • Apache2::Const::HTTP_CONTINUE
      • Apache2::Const::HTTP_CREATED
      • Apache2::Const::HTTP_EXPECTATION_FAILED
      • Apache2::Const::HTTP_FAILED_DEPENDENCY
      • Apache2::Const::HTTP_FORBIDDEN
      • Apache2::Const::HTTP_GATEWAY_TIME_OUT
      • Apache2::Const::HTTP_GONE
      • Apache2::Const::HTTP_INSUFFICIENT_STORAGE
      • Apache2::Const::HTTP_INTERNAL_SERVER_ERROR
      • Apache2::Const::HTTP_LENGTH_REQUIRED
      • Apache2::Const::HTTP_LOCKED
      • Apache2::Const::HTTP_METHOD_NOT_ALLOWED
      • Apache2::Const::HTTP_MOVED_PERMANENTLY
      • Apache2::Const::HTTP_MOVED_TEMPORARILY
      • Apache2::Const::HTTP_MULTIPLE_CHOICES
      • Apache2::Const::HTTP_MULTI_STATUS
      • Apache2::Const::HTTP_NON_AUTHORITATIVE
      • Apache2::Const::HTTP_NOT_ACCEPTABLE
      • Apache2::Const::HTTP_NOT_EXTENDED
      • Apache2::Const::HTTP_NOT_FOUND
      • Apache2::Const::HTTP_NOT_IMPLEMENTED
      • Apache2::Const::HTTP_NOT_MODIFIED
      • Apache2::Const::HTTP_NO_CONTENT
      • Apache2::Const::HTTP_OK
      • Apache2::Const::HTTP_PARTIAL_CONTENT
      • Apache2::Const::HTTP_PAYMENT_REQUIRED
      • Apache2::Const::HTTP_PRECONDITION_FAILED
      • Apache2::Const::HTTP_PROCESSING
      • Apache2::Const::HTTP_PROXY_AUTHENTICATION_REQUIRED
      • Apache2::Const::HTTP_RANGE_NOT_SATISFIABLE
      • Apache2::Const::HTTP_REQUEST_ENTITY_TOO_LARGE
      • Apache2::Const::HTTP_REQUEST_TIME_OUT
      • Apache2::Const::HTTP_REQUEST_URI_TOO_LARGE
      • Apache2::Const::HTTP_RESET_CONTENT
      • Apache2::Const::HTTP_SEE_OTHER
      • Apache2::Const::HTTP_SERVICE_UNAVAILABLE
      • Apache2::Const::HTTP_SWITCHING_PROTOCOLS
      • Apache2::Const::HTTP_TEMPORARY_REDIRECT
      • Apache2::Const::HTTP_UNAUTHORIZED
      • Apache2::Const::HTTP_UNPROCESSABLE_ENTITY
      • Apache2::Const::HTTP_UNSUPPORTED_MEDIA_TYPE
      • Apache2::Const::HTTP_UPGRADE_REQUIRED
      • Apache2::Const::HTTP_USE_PROXY
      • Apache2::Const::HTTP_VARIANT_ALSO_VARIES
    • :input_mode
      • Apache2::Const::MODE_EATCRLF
      • Apache2::Const::MODE_EXHAUSTIVE
      • Apache2::Const::MODE_GETLINE
      • Apache2::Const::MODE_INIT
      • Apache2::Const::MODE_READBYTES
      • Apache2::Const::MODE_SPECULATIVE
    • :log
      • Apache2::Const::LOG_ALERT
      • Apache2::Const::LOG_CRIT
      • Apache2::Const::LOG_DEBUG
      • Apache2::Const::LOG_EMERG
      • Apache2::Const::LOG_ERR
      • Apache2::Const::LOG_INFO
      • Apache2::Const::LOG_LEVELMASK
      • Apache2::Const::LOG_NOTICE
      • Apache2::Const::LOG_STARTUP
      • Apache2::Const::LOG_TOCLIENT
      • Apache2::Const::LOG_WARNING
    • :methods
      • Apache2::Const::METHODS
      • Apache2::Const::M_BASELINE_CONTROL
      • Apache2::Const::M_CHECKIN
      • Apache2::Const::M_CHECKOUT
      • Apache2::Const::M_CONNECT
      • Apache2::Const::M_COPY
      • Apache2::Const::M_DELETE
      • Apache2::Const::M_GET
      • Apache2::Const::M_INVALID
      • Apache2::Const::M_LABEL
      • Apache2::Const::M_LOCK
      • Apache2::Const::M_MERGE
      • Apache2::Const::M_MKACTIVITY
      • Apache2::Const::M_MKCOL
      • Apache2::Const::M_MKWORKSPACE
      • Apache2::Const::M_MOVE
      • Apache2::Const::M_OPTIONS
      • Apache2::Const::M_PATCH
      • Apache2::Const::M_POST
      • Apache2::Const::M_PROPFIND
      • Apache2::Const::M_PROPPATCH
      • Apache2::Const::M_PUT
      • Apache2::Const::M_REPORT
      • Apache2::Const::M_TRACE
      • Apache2::Const::M_UNCHECKOUT
      • Apache2::Const::M_UNLOCK
      • Apache2::Const::M_UPDATE
      • Apache2::Const::M_VERSION_CONTROL
    • :mpmq
      • Apache2::Const::MPMQ_NOT_SUPPORTED
      • Apache2::Const::MPMQ_STATIC
      • Apache2::Const::MPMQ_DYNAMIC
      • Apache2::Const::MPMQ_MAX_DAEMON_USED
      • Apache2::Const::MPMQ_IS_THREADED
      • Apache2::Const::MPMQ_IS_FORKED
      • Apache2::Const::MPMQ_HARD_LIMIT_DAEMONS
      • Apache2::Const::MPMQ_HARD_LIMIT_THREADS
      • Apache2::Const::MPMQ_MAX_THREADS
      • Apache2::Const::MPMQ_MIN_SPARE_DAEMONS
      • Apache2::Const::MPMQ_MIN_SPARE_THREADS
      • Apache2::Const::MPMQ_MAX_SPARE_DAEMONS
      • Apache2::Const::MPMQ_MAX_SPARE_THREADS
      • Apache2::Const::MPMQ_MAX_REQUESTS_DAEMON
      • Apache2::Const::MPMQ_MAX_DAEMONS
    • :options
      • Apache2::Const::OPT_ALL
      • Apache2::Const::OPT_EXECCGI
      • Apache2::Const::OPT_INCLUDES
      • Apache2::Const::OPT_INCNOEXEC
      • Apache2::Const::OPT_INDEXES
      • Apache2::Const::OPT_MULTI
      • Apache2::Const::OPT_NONE
      • Apache2::Const::OPT_SYM_LINKS
      • Apache2::Const::OPT_SYM_OWNER
      • Apache2::Const::OPT_UNSET
    • :override
      • Apache2::Const::ACCESS_CONF
      • Apache2::Const::EXEC_ON_READ
      • Apache2::Const::OR_ALL
      • Apache2::Const::OR_AUTHCFG
      • Apache2::Const::OR_FILEINFO
      • Apache2::Const::OR_INDEXES
      • Apache2::Const::OR_LIMIT
      • Apache2::Const::OR_NONE
      • Apache2::Const::OR_OPTIONS
      • Apache2::Const::OR_UNSET
      • Apache2::Const::RSRC_CONF
    • :platform
      • Apache2::Const::CRLF
      • Apache2::Const::CR
      • Apache2::Const::LF
    • :remotehost
      • Apache2::Const::REMOTE_DOUBLE_REV
      • Apache2::Const::REMOTE_HOST
      • Apache2::Const::REMOTE_NAME
      • Apache2::Const::REMOTE_NOLOOKUP
    • :satisfy
      • Apache2::Const::SATISFY_ALL
      • Apache2::Const::SATISFY_ANY
      • Apache2::Const::SATISFY_NOSPEC
    • :types
      • Apache2::Const::DIR_MAGIC_TYPE
    • :proxy
      • Apache2::Const::PROXYREQ_NONE
      • Apache2::Const::PROXYREQ_PROXY
      • Apache2::Const::PROXYREQ_REVERSE
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Const - Perl Interface for Apache Constants

Synopsis

  # make the constants available but don't import them
  use Apache2::Const -compile => qw(constant names ...);

  # w/o the => syntax sugar
  use Apache2::Const ("-compile", qw(constant names ...));

  # compile and import the constants
  use Apache2::Const qw(constant names ...);

Description

This package contains constants specific to Apache features.

mod_perl 2.0 comes with several hundreds of constants, which you don't want to make available to your Perl code by default, due to CPU and memory overhead. Therefore when you want to use a certain constant you need to explicitly ask to make it available.

For example, the code:

  use Apache2::Const -compile => qw(FORBIDDEN OK);

makes the constants Apache2::Const::FORBIDDEN and Apache2::Const::OK available to your code, but they aren't imported. In which case you need to use a fully qualified constants, as in:

  return Apache2::Const::OK;

If you drop the argument -compile and write:

  use Apache2::Const qw(FORBIDDEN OK);

Then both constants are imported into your code's namespace and can be used standalone like so:

  return OK;

Both, due to the extra memory requirement, when importing symbols, and since there are constants in other namespaces (e.g., APR::|docs::2.0::api::APR::Const and ModPerl::|docs::2.0::api::ModPerl::Const, and non-mod_perl modules) which may contain the same names, it's not recommended to import constants. I.e. you want to use the -compile construct.

Finaly, in Perl => is almost the same as the comma operator. It can be used as syntax sugar making it more clear when there is a key-value relation between two arguments, and also it automatically parses its lefthand argument (the key) as a string, so you don't need to quote it.

If you don't want to use that syntax, instead of writing:

 use Apache2::Const -compile => qw(FORBIDDEN OK);

you could write:

 use Apache2::Const "-compile", qw(FORBIDDEN OK);

and for parentheses-lovers:

 use Apache2::Const ("-compile", qw(FORBIDDEN OK));

Constants

:cmd_how

  use Apache2::Const -compile => qw(:cmd_how);

The :cmd_how constants group is used in Apache2::Module::add()|docs::2.0::api::Apache2::Module/C_add_ and $cmds->args_how|docs::2.0::api::Apache2::Command/C_args_how_.

Apache2::Const::FLAG

One of On or Off (full description).

since: 2.0.00

Apache2::Const::ITERATE

One argument, occuring multiple times (full description).

since: 2.0.00

Apache2::Const::ITERATE2

Two arguments, the second occurs multiple times (full description).

since: 2.0.00

Apache2::Const::NO_ARGS

No arguments at all (full description).

since: 2.0.00

Apache2::Const::RAW_ARGS

The command will parse the command line itself (full description).

since: 2.0.00

Apache2::Const::TAKE1

One argument only (full description).

since: 2.0.00

Apache2::Const::TAKE12

One or two arguments (full description).

since: 2.0.00

Apache2::Const::TAKE123

One, two or three arguments (full description).

since: 2.0.00

Apache2::Const::TAKE13

One or three arguments (full description).

since: 2.0.00

Apache2::Const::TAKE2

Two arguments (full description).

since: 2.0.00

Apache2::Const::TAKE23

Two or three arguments (full description).

since: 2.0.00

Apache2::Const::TAKE3

Three arguments (full description).

since: 2.0.00

:common

  use Apache2::Const -compile => qw(:common);

The :common group is for XXX constants.

Apache2::Const::AUTH_REQUIRED

since: 2.0.00

Apache2::Const::DECLINED

since: 2.0.00

Apache2::Const::DONE

since: 2.0.00

Apache2::Const::FORBIDDEN

since: 2.0.00

Apache2::Const::NOT_FOUND

since: 2.0.00

Apache2::Const::OK

since: 2.0.00

Apache2::Const::REDIRECT

since: 2.0.00

Apache2::Const::SERVER_ERROR

since: 2.0.00

:config

  use Apache2::Const -compile => qw(:config);

The :config group is for XXX constants.

Apache2::Const::DECLINE_CMD

since: 2.0.00

:conn_keepalive

  use Apache2::Const -compile => qw(:conn_keepalive);

The :conn_keepalive constants group is used by the ($c->keepalive|docs::2.0::api::Apache2::Connection/C_keepalive_) method.

Apache2::Const::CONN_CLOSE

The connection will be closed at the end of the current HTTP request.

since: 2.0.00

Apache2::Const::CONN_KEEPALIVE

The connection will be kept alive at the end of the current HTTP request.

since: 2.0.00

Apache2::Const::CONN_UNKNOWN

The connection is at an unknown state, e.g., initialized but not open yet.

since: 2.0.00

:context

  use Apache2::Const -compile => qw(:context);

The :context group is used by the $parms->check_cmd_context|docs::2.0::api::Apache2::CmdParms/C_check_cmd_context_ method.

Apache2::Const::NOT_IN_VIRTUALHOST

The command is not in a <VirtualHost> block.

since: 2.0.00

Apache2::Const::NOT_IN_LIMIT

The command is not in a <Limit> block.

since: 2.0.00

Apache2::Const::NOT_IN_DIRECTORY

The command is not in a <Directory> block.

since: 2.0.00

Apache2::Const::NOT_IN_LOCATION

The command is not in a <Location>/<LocationMatch> block.

since: 2.0.00

Apache2::Const::NOT_IN_FILES

The command is not in a <Files>/<FilesMatch> block.

since: 2.0.00

Apache2::Const::NOT_IN_DIR_LOC_FILE

The command is not in a <Files>/<FilesMatch>, <Location>/<LocationMatch> or <Directory> block.

since: 2.0.00

Apache2::Const::GLOBAL_ONLY

The directive appears outside of any container directives.

since: 2.0.00

:filter_type

  use Apache2::Const -compile => qw(:filter_type);

The :filter_type group is for XXX constants.

Apache2::Const::FTYPE_CONNECTION

since: 2.0.00

Apache2::Const::FTYPE_CONTENT_SET

since: 2.0.00

Apache2::Const::FTYPE_NETWORK

since: 2.0.00

Apache2::Const::FTYPE_PROTOCOL

since: 2.0.00

Apache2::Const::FTYPE_RESOURCE

since: 2.0.00

Apache2::Const::FTYPE_TRANSCODE

since: 2.0.00

:http

  use Apache2::Const -compile => qw(:http);

The :http group is for XXX constants.

Apache2::Const::HTTP_ACCEPTED

since: 2.0.00

Apache2::Const::HTTP_BAD_GATEWAY

since: 2.0.00

Apache2::Const::HTTP_BAD_REQUEST

since: 2.0.00

Apache2::Const::HTTP_CONFLICT

since: 2.0.00

Apache2::Const::HTTP_CONTINUE

since: 2.0.00

Apache2::Const::HTTP_CREATED

since: 2.0.00

Apache2::Const::HTTP_EXPECTATION_FAILED

since: 2.0.00

Apache2::Const::HTTP_FAILED_DEPENDENCY

since: 2.0.00

Apache2::Const::HTTP_FORBIDDEN

since: 2.0.00

Apache2::Const::HTTP_GATEWAY_TIME_OUT

since: 2.0.00

Apache2::Const::HTTP_GONE

since: 2.0.00

Apache2::Const::HTTP_INSUFFICIENT_STORAGE

since: 2.0.00

Apache2::Const::HTTP_INTERNAL_SERVER_ERROR

since: 2.0.00

Apache2::Const::HTTP_LENGTH_REQUIRED

since: 2.0.00

Apache2::Const::HTTP_LOCKED

since: 2.0.00

Apache2::Const::HTTP_METHOD_NOT_ALLOWED

since: 2.0.00

Apache2::Const::HTTP_MOVED_PERMANENTLY

since: 2.0.00

Apache2::Const::HTTP_MOVED_TEMPORARILY

since: 2.0.00

Apache2::Const::HTTP_MULTIPLE_CHOICES

since: 2.0.00

Apache2::Const::HTTP_MULTI_STATUS

since: 2.0.00

Apache2::Const::HTTP_NON_AUTHORITATIVE

since: 2.0.00

Apache2::Const::HTTP_NOT_ACCEPTABLE

since: 2.0.00

Apache2::Const::HTTP_NOT_EXTENDED

since: 2.0.00

Apache2::Const::HTTP_NOT_FOUND

since: 2.0.00

Apache2::Const::HTTP_NOT_IMPLEMENTED

since: 2.0.00

Apache2::Const::HTTP_NOT_MODIFIED

since: 2.0.00

Apache2::Const::HTTP_NO_CONTENT

since: 2.0.00

Apache2::Const::HTTP_OK

since: 2.0.00

Apache2::Const::HTTP_PARTIAL_CONTENT

since: 2.0.00

Apache2::Const::HTTP_PAYMENT_REQUIRED

since: 2.0.00

Apache2::Const::HTTP_PRECONDITION_FAILED

since: 2.0.00

Apache2::Const::HTTP_PROCESSING

since: 2.0.00

Apache2::Const::HTTP_PROXY_AUTHENTICATION_REQUIRED

since: 2.0.00

Apache2::Const::HTTP_RANGE_NOT_SATISFIABLE

since: 2.0.00

Apache2::Const::HTTP_REQUEST_ENTITY_TOO_LARGE

since: 2.0.00

Apache2::Const::HTTP_REQUEST_TIME_OUT

since: 2.0.00

Apache2::Const::HTTP_REQUEST_URI_TOO_LARGE

since: 2.0.00

Apache2::Const::HTTP_RESET_CONTENT

since: 2.0.00

Apache2::Const::HTTP_SEE_OTHER

since: 2.0.00

Apache2::Const::HTTP_SERVICE_UNAVAILABLE

since: 2.0.00

Apache2::Const::HTTP_SWITCHING_PROTOCOLS

since: 2.0.00

Apache2::Const::HTTP_TEMPORARY_REDIRECT

since: 2.0.00

Apache2::Const::HTTP_UNAUTHORIZED

since: 2.0.00

Apache2::Const::HTTP_UNPROCESSABLE_ENTITY

since: 2.0.00

Apache2::Const::HTTP_UNSUPPORTED_MEDIA_TYPE

since: 2.0.00

Apache2::Const::HTTP_UPGRADE_REQUIRED

since: 2.0.00

Apache2::Const::HTTP_USE_PROXY

since: 2.0.00

Apache2::Const::HTTP_VARIANT_ALSO_VARIES

since: 2.0.00

:input_mode

  use Apache2::Const -compile => qw(:input_mode);

The :input_mode group is used by get_brigade|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_EATCRLF

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_EXHAUSTIVE

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_GETLINE

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_INIT

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_READBYTES

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

Apache2::Const::MODE_SPECULATIVE

since: 2.0.00

See Apache2::Filter::get_brigade()|docs::2.0::api::Apache2::Filter/C_get_brigade_.

:log

  use Apache2::Const -compile => qw(:log);

The :log group is for constants used by Apache2::Log|docs::2.0::api::Apache2::Log.

Apache2::Const::LOG_ALERT

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_ALERT_.

Apache2::Const::LOG_CRIT

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_CRIT_.

Apache2::Const::LOG_DEBUG

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_DEBUG_.

Apache2::Const::LOG_EMERG

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_EMERG_.

Apache2::Const::LOG_ERR

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_ERR_.

Apache2::Const::LOG_INFO

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_INFO_.

Apache2::Const::LOG_LEVELMASK

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_LEVELMASK_.

Apache2::Const::LOG_NOTICE

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_NOTICE_.

Apache2::Const::LOG_STARTUP

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_STARTUP_.

Apache2::Const::LOG_TOCLIENT

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_TOCLIENT_.

Apache2::Const::LOG_WARNING

since: 2.0.00

See Apache2::Log|docs::2.0::api::Apache2::Log/C_Apache2__LOG_WARNING_.

:methods

  use Apache2::Const -compile => qw(:methods);

The :methods constants group is used in conjunction with $r->method_number|docs::2.0::api::Apache2::RequestRec/C_method_number_.

Apache2::Const::METHODS

since: 2.0.00

Apache2::Const::M_BASELINE_CONTROL

since: 2.0.00

Apache2::Const::M_CHECKIN

since: 2.0.00

Apache2::Const::M_CHECKOUT

since: 2.0.00

Apache2::Const::M_CONNECT

since: 2.0.00

Apache2::Const::M_COPY

since: 2.0.00

Apache2::Const::M_DELETE

since: 2.0.00

Apache2::Const::M_GET

since: 2.0.00

corresponds to the HTTP GET method

Apache2::Const::M_INVALID

since: 2.0.00

Apache2::Const::M_LABEL

since: 2.0.00

Apache2::Const::M_LOCK

since: 2.0.00

Apache2::Const::M_MERGE

since: 2.0.00

Apache2::Const::M_MKACTIVITY

since: 2.0.00

Apache2::Const::M_MKCOL

since: 2.0.00

Apache2::Const::M_MKWORKSPACE

since: 2.0.00

Apache2::Const::M_MOVE

since: 2.0.00

Apache2::Const::M_OPTIONS

since: 2.0.00

Apache2::Const::M_PATCH

since: 2.0.00

Apache2::Const::M_POST

since: 2.0.00

corresponds to the HTTP POST method

Apache2::Const::M_PROPFIND

since: 2.0.00

Apache2::Const::M_PROPPATCH

since: 2.0.00

Apache2::Const::M_PUT

since: 2.0.00

corresponds to the HTTP PUT method

Apache2::Const::M_REPORT

since: 2.0.00

Apache2::Const::M_TRACE

since: 2.0.00

Apache2::Const::M_UNCHECKOUT

since: 2.0.00

Apache2::Const::M_UNLOCK

since: 2.0.00

Apache2::Const::M_UPDATE

since: 2.0.00

Apache2::Const::M_VERSION_CONTROL

since: 2.0.00

:mpmq

  use Apache2::Const -compile => qw(:mpmq);

The :mpmq group is for querying MPM properties.

Apache2::Const::MPMQ_NOT_SUPPORTED

since: 2.0.00

Apache2::Const::MPMQ_STATIC

since: 2.0.00

Apache2::Const::MPMQ_DYNAMIC

since: 2.0.00

Apache2::Const::MPMQ_MAX_DAEMON_USED

since: 2.0.00

Apache2::Const::MPMQ_IS_THREADED

since: 2.0.00

Apache2::Const::MPMQ_IS_FORKED

since: 2.0.00

Apache2::Const::MPMQ_HARD_LIMIT_DAEMONS

since: 2.0.00

Apache2::Const::MPMQ_HARD_LIMIT_THREADS

since: 2.0.00

Apache2::Const::MPMQ_MAX_THREADS

since: 2.0.00

Apache2::Const::MPMQ_MIN_SPARE_DAEMONS

since: 2.0.00

Apache2::Const::MPMQ_MIN_SPARE_THREADS

since: 2.0.00

Apache2::Const::MPMQ_MAX_SPARE_DAEMONS

since: 2.0.00

Apache2::Const::MPMQ_MAX_SPARE_THREADS

since: 2.0.00

Apache2::Const::MPMQ_MAX_REQUESTS_DAEMON

since: 2.0.00

Apache2::Const::MPMQ_MAX_DAEMONS

since: 2.0.00

:options

  use Apache2::Const -compile => qw(:options);

The :options group contains constants corresponding to the Options configuration directive. For examples see: $r->allow_options|docs::2.0::api::Apache2::Access/C_allow_options_.

Apache2::Const::OPT_ALL

since: 2.0.00

Apache2::Const::OPT_EXECCGI

since: 2.0.00

Apache2::Const::OPT_INCLUDES

since: 2.0.00

Apache2::Const::OPT_INCNOEXEC

since: 2.0.00

Apache2::Const::OPT_INDEXES

since: 2.0.00

Apache2::Const::OPT_MULTI

since: 2.0.00

Apache2::Const::OPT_NONE

since: 2.0.00

Apache2::Const::OPT_SYM_LINKS

since: 2.0.00

Apache2::Const::OPT_SYM_OWNER

since: 2.0.00

Apache2::Const::OPT_UNSET

since: 2.0.00

:override

  use Apache2::Const -compile => qw(:override);

The :override group contains constants corresponding to the AllowOverride configuration directive. For examples see: $r->allow_options|docs::2.0::api::Apache2::Access/C_allow_overrides_.

Apache2::Const::ACCESS_CONF

*.conf inside <Directory> or <Location>

since: 2.0.00

Apache2::Const::EXEC_ON_READ

Force directive to execute a command which would modify the configuration (like including another file, or IFModule)

since: 2.0.00

Apache2::Const::OR_ALL

Apache2::Const::OR_LIMIT|/C_Apache2__OR_LIMIT_ |
Apache2::Const::OR_OPTIONS|/C_Apache2__OR_OPTIONS_ |
Apache2::Const::OR_FILEINFO|/C_Apache2__OR_FILEINFO_ |
Apache2::Const::OR_AUTHCFG|/C_Apache2__OR_AUTHCFG_ |
Apache2::Const::OR_INDEXES|/C_Apache2__OR_INDEXES_

since: 2.0.00

Apache2::Const::OR_AUTHCFG

*.conf inside <Directory> or <Location> and .htaccess when AllowOverride AuthConfig

since: 2.0.00

Apache2::Const::OR_FILEINFO

*.conf anywhere and .htaccess when AllowOverride FileInfo

since: 2.0.00

Apache2::Const::OR_INDEXES

*.conf anywhere and .htaccess when AllowOverride Indexes

since: 2.0.00

Apache2::Const::OR_LIMIT

*.conf inside <Directory> or <Location> and .htaccess when AllowOverride Limit

since: 2.0.00

Apache2::Const::OR_NONE

*.conf is not available anywhere in this override

since: 2.0.00

Apache2::Const::OR_OPTIONS

*.conf anywhere and .htaccess when AllowOverride Options

since: 2.0.00

Apache2::Const::OR_UNSET

Unset a directive (in Allow)

since: 2.0.00

Apache2::Const::RSRC_CONF

*.conf outside <Directory> or <Location>

since: 2.0.00

:platform

  use Apache2::Const -compile => qw(:platform);

The :platform group is for constants that may differ from OS to OS.

Apache2::Const::CRLF

since: 2.0.00

Apache2::Const::CR

since: 2.0.00

Apache2::Const::LF

since: 2.0.00

:remotehost

  use Apache2::Const -compile => qw(:remotehost);

The :remotehost constants group is is used by the $c->get_remote_host|docs::2.0::api::Apache2::Connection/C_get_remote_host_ method.

Apache2::Const::REMOTE_DOUBLE_REV

since: 2.0.00

Apache2::Const::REMOTE_HOST

since: 2.0.00

Apache2::Const::REMOTE_NAME

since: 2.0.00

Apache2::Const::REMOTE_NOLOOKUP

since: 2.0.00

:satisfy

  use Apache2::Const -compile => qw(:satisfy);

The :satisfy constants group is used in conjunction with $r->satisfies|docs::2.0::api::Apache2::Access/C_satisfies_.

Apache2::Const::SATISFY_ALL

since: 2.0.00

All of the requirements must be met.

Apache2::Const::SATISFY_ANY

since: 2.0.00

any of the requirements must be met.

Apache2::Const::SATISFY_NOSPEC

since: 2.0.00

There are no applicable satisfy lines

:types

  use Apache2::Const -compile => qw(:types);

The :types group is for XXX constants.

Apache2::Const::DIR_MAGIC_TYPE

since: 2.0.00

:proxy

  use Apache2::Const -compile => qw(:proxy);

The :proxy constants group is used in conjunction with $r->proxyreq|docs::2.0::api::Apache2::RequestRec/C_proxyreq_.

Apache2::Const::PROXYREQ_NONE

since: 2.0.2

Apache2::Const::PROXYREQ_PROXY

since: 2.0.2

Apache2::Const::PROXYREQ_REVERSE

since: 2.0.2

See Also

mod_perl 2.0 documentation.

HTTP Status Codes.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Directive - Perl API for manipulating the Apache configuration tree

  • Synopsis
  • Description
  • API
    • args
    • as_hash
    • as_string
    • conftree
    • directive
    • filename
    • first_child
    • line_num
    • lookup
    • next
    • parent
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Directive - Perl API for manipulating the Apache configuration tree

Synopsis

  use Apache2::Directive ();

  my $tree = Apache2::Directive::conftree();

  my $documentroot = $tree->lookup('DocumentRoot');

  my $vhost = $tree->lookup('VirtualHost', 'localhost:8000');
  my $servername = $vhost->{'ServerName'};

  use Data::Dumper;
  print Dumper $tree->as_hash;

  my $node = $tree;
  while ($node) {
      print $node->as_string;

      #do something with $node

      my $directive = $node->directive;
      my $args = $node->args;
      my $filename = $node->filename;
      my $line_num = $node->line_num;

      if (my $kid = $node->first_child) {
          $node = $kid;
      }
      elsif (my $next = $node->next) {
          $node = $next;
      }
      else {
          if (my $parent = $node->parent) {
              $node = $parent->next;
          }
          else {
              $node = undef;
          }
      }
  }

Description

Apache2::Directive provides the Perl API for manipulating the Apache configuration tree

API

Apache2::Directive provides the following functions and/or methods:

args

Get the arguments for the current directive:

  $args = $node->args();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: $args ( string )

Arguments are separated by a whitespace in the string.

since: 2.0.00

For example, in httpd.conf:

  PerlSwitches -M/opt/lib -M/usr/local/lib -wT

And later:

  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('PerlSwitches');
  my $args = $node->args;

$args now contains the string "-M/opt/lib -M/usr/local/lib -wT"

as_hash

Get a hash representation of the configuration tree, in a format suitable for inclusion in <Perl> sections.

   $config_hash = $conftree->as_hash();
obj: $conftree ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

The config tree to stringify

ret: $config_hash ( HASH reference )
since: 2.0.00

For example: in httpd.conf:

  <Location /test>
    SetHandler perl-script
    PerlHandler Test::Module
  </Location>

And later:

  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('Location', '/test/');
  my $hash = $node->as_hash;

$hash now is:

  {
    'SetHandler'  => 'perl-script',
    'PerlHandler' => 'Test::Module',
  }

as_string

Get a string representation of the configuration node, in httpd.conf format.

   $string = $node->as_string();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

The config tree to stringify

ret: $string ( string )
since: 2.0.00

For example: in httpd.conf:

  <Location /test>
    SetHandler perl-script
    PerlHandler Test::Module
  </Location>

And later:

  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('Location', '/test/');
  my $string = $node->as_string;

$string is now:

  SetHandler perl-script
  PerlHandler Test::Module

conftree

Get the root of the configuration tree:

  $conftree = Apache2::Directive::conftree();
obj: Apache2::Directive ( class name )
ret: $conftree ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
since: 2.0.00

directive

Get the name of the directive in $node:

  $name = $node->directive();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: $name ( string )
since: 2.0.00

filename

Get the filename the configuration node was created from:

  $filename = $node->filename();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: $filename ( string )
since: 2.0.00

For example:

  my $tree = Apache2::Directive::conftree();
  my $node = $tree->lookup('VirtualHost', 'example.com');
  my $filename = $node->filename;

$filename is now the full path to the httpd.conf that VirtualHost was defined in.

If the directive was added with add_config()|docs::2.0::api::Apache2::ServerUtil/C_add_config_, the filename will be the path to the httpd.conf that trigerred that Perl code.

first_child

Get the first child node of this directive:

  $child_node = $node->first_child;
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: $child_node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

Returns the first child node of $node, undef if there is none

since: 2.0.00

line_num

Get the line number in a filename this node was created at:

  $lineno = $node->line_num();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
arg1: $lineno (integer)
since: 2.0.00

lookup

Get the node(s) matching a certain value.

  $node  = $conftree->lookup($directive, $args);
  @nodes = $conftree->lookup($directive, $args);
obj: $conftree ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

The config tree to stringify

arg1: $directive ( string )

The name of the directive to search for

opt arg2: args ( string )

Optional args to the directive to filter for

ret: $string ( string / ARRAY of HASH refs )

In LIST context, it returns all matching nodes.

In SCALAR context, it returns only the first matching node.

If called with only $directive value, this method returns all nodes from that directive. For example:

  @Alias = $conftree->lookup('Alias');

returns all nodes for Alias directives.

If called with an extra $args argument, it returns only nodes where both the directive and the args matched. For example:

  $VHost = $tree->lookup('VirtualHost', '_default_:8000');
since: 2.0.00

next

Get the next directive node in the tree:

  $next_node = $node->next();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: $next_node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

Returns the next sibling of $node, undef if there is none

since: 2.0.00

parent

Get the parent node of this directive:

  $parent_node = $node->parent();
obj: $node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )
ret: parent_node ( Apache2::Directive object|docs::2.0::api::Apache2::Directive )

Returns the parent of $node, undef if this node is the root node

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Filter - Perl API for Apache 2.0 Filtering

  • Synopsis
  • Description
  • Common Filter API
    • c
    • ctx
    • frec
    • next
    • r
    • remove
  • Bucket Brigade Filter API
    • fflush
    • get_brigade
    • pass_brigade
  • Streaming Filter API
    • print
    • read
    • seen_eos
  • Other Filter-related API
    • add_input_filter
    • add_output_filter
  • Filter Handler Attributes
    • FilterRequestHandler
    • FilterConnectionHandler
    • FilterInitHandler
    • FilterHasInitHandler
  • Configuration
    • PerlInputFilterHandler
    • PerlOutputFilterHandler
    • PerlSetInputFilter
    • PerlSetOutputFilter
  • TIE Interface
    • TIEHANDLE
    • PRINT
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Filter - Perl API for Apache 2.0 Filtering

Synopsis

  use Apache2::Filter ();

  # filter attributes
  my $c = $f->c;
  my $r = $f->r;
  my $frec = $f->frec();
  my $next_f = $f->next;

  my $ctx = $f->ctx;
  $f->ctx($ctx);

  # bucket brigade filtering API
  $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
  $rc = $f->next->pass_brigade($bb);
  $rc = $f->fflush($bb);

  # streaming filtering API
  while ($filter->read(my $buffer, $wanted)) {
      # transform $buffer here
      $filter->print($buffer);
  }
  if ($f->seen_eos) {
      $filter->print("filter signature");
  }

  # filter manipulations
  $r->add_input_filter(\&callback);
  $c->add_input_filter(\&callback);
  $r->add_output_filter(\&callback);
  $c->add_output_filter(\&callback);
  $f->remove;

Description

Apache2::Filter provides Perl API for Apache 2.0 filtering framework.

Make sure to read the Filtering tutorial|docs::2.0::user::handlers::filters.

Common Filter API

The following methods can be called from any filter handler:

c

Get the current connection object from a connection or a request filter:

  $c = $f->c;
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
ret: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
since: 2.0.00

ctx

Get/set the filter context data.

  $ctx = $f->ctx;
         $f->ctx($ctx);
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
opt arg2: $ctx ( SCALAR )

next context

ret: $ctx ( SCALAR )

current context

since: 2.0.00

A filter context is created before the filter is called for the first time and it's destroyed at the end of the request. The context is preserved between filter invocations of the same request. So if a filter needs to store some data between invocations it should use the filter context for that. The filter context is initialized with the undef value.

The ctx method accepts a single SCALAR argument. Therefore if you want to store any other perl datastructure you should use a reference to it.

For example you can store a hash reference:

  $f->ctx({ foo => 'bar' });

and then access it:

  $foo = $f->ctx->{foo};

if you access the context more than once it's more efficient to copy it's value before using it:

  my $ctx = $f->ctx;
  $foo = $ctx->{foo};

to avoid redundant method calls. As of this writing $ctx is not a tied variable, so if you modify it need to store it at the end:

  $f->ctx($ctx);

META: later we might make it a TIEd-variable interface, so it'll be stored automatically.

Besides its primary purpose of storing context data across multiple filter invocations, this method is also useful when used as a flag. For example here is how to ensure that something happens only once during the filter's life:

  unless ($f->ctx) {
      do_something_once();
      $f->ctx(1);
  }

frec

Get/set the Apache2::FilterRec|docs::2.0::api::Apache2::FilterRec (filter record) object.

  $frec = $f->frec();
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
ret: $frec ( Apache2::FilterRec object|docs::2.0::api::Apache2::FilterRec )
since: 2.0.00

For example you can call $frec->name|docs::2.0::api::Apache2::FilterRec/C_name_ to get filter's name.

next

Return the Apache2::Filter object of the next filter in chain.

  $next_f = $f->next;
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The current filter object

ret: $next_f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The next filter object in chain

since: 2.0.00

Since Apache inserts several core filters at the end of each chain, normally this method always returns an object. However if it's not a mod_perl filter handler, you can call only the following methods on it: get_brigade|/C_get_brigade_, pass_brigade|/C_pass_brigade_, c|/C_c_, r|/C_r_, frec|/C_frec_ and next|/C_next_. If you call other methods the behavior is undefined.

The next filter can be a mod_perl one or not, it's easy to tell which one is that by calling $f->frec->name|docs::2.0::api::Apache2::FilterRec/C_name_.

r

Inside an HTTP request filter retrieve the current request object:

  $r = $f->r;
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
ret: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
since: 2.0.00

If a sub-request adds filters, then that sub-request object is associated with the filter.

remove

Remove the current filter from the filter chain (for the current request or connection).

  $f->remove;
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
ret: no return value
since: 2.0.00

Notice that you should either complete the current filter invocation normally (by calling get_brigade|/C_get_brigade_ or pass_brigade|/C_pass_brigade_ depending on the filter kind) or if nothing was done, return Apache2::Const::DECLINED and mod_perl will take care of passing the current bucket brigade through unmodified to the next filter in chain.

Note: calling remove() on the very top connection filter doesn't affect the filter chain due to a bug in Apache 2.0 (which may be fixed in 2.1). So don't use it with connection filters, till it gets fixed in Apache and then make sure to require the minimum Apache version if you rely on.

Remember that if the connection is $c->keepalive|docs::2.0::api::Apache2::Connection/C_keepalive_ ) and the connection filter is removed, it won't be added until the connection is closed. Which may happen after many HTTP requests. You may want to keep the filter in place and pass the data through unmodified, by returning Apache2::Const::DECLINED. If you need to reset the whole or parts of the filter context between requests, use the technique based on $c->keepalives counting.

This method works for native Apache (non-mod_perl) filters too.

Bucket Brigade Filter API

The following methods can be called from any filter, directly manipulating bucket brigades:

fflush

Flush a bucket brigade down the filter stack.

  $rc = $f->fflush($bb);
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The current filter

arg1: $bb ( Apache2::Brigade object|docs::2.0::api::APR::Brigade )

The brigade to flush

ret: $rc ( APR::Const status constant|docs::2.0::api::APR::Const )

Refer to the pass_brigade()|/C_pass_brigade_ entry.

excpt: APR::Error|docs::2.0::api::APR::Error

Exceptions are thrown only when this function is called in the VOID context. Refer to the get_brigade()|/C_get_brigade_ entry for details.

since: 2.0.00

fflush is a shortcut method. So instead of doing:

  my $b = APR::Bucket::flush_create($f->c->bucket_alloc);
  $bb->insert_tail($b);
  $f->pass_brigade($bb);

one can just write:

  $f->fflush($bb);

get_brigade

This is a method to use in bucket brigade input filters. It acquires a bucket brigade from the upstream input filter.

  $rc = $next_f->get_brigade($bb, $mode, $block, $readbytes);
  $rc = $next_f->get_brigade($bb, $mode, $block);
  $rc = $next_f->get_brigade($bb, $mode)
  $rc = $next_f->get_brigade($bb);
obj: $next_f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The next filter in the filter chain.

Inside filter handlers it's usually $f->next|/C_next_. Inside protocol handlers: $c->input_filters|docs::2.0::api::Apache2::Connection/C_input_filters_.

arg1: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The original bucket brigade passed to get_brigade(), which must be empty.

Inside input filter handlers it's usually the second argument to the filter handler.

Otherwise it should be created:

  my $bb = APR::Brigade->new($c->pool, $c->bucket_alloc);

On return it gets populated with the next bucket brigade. That brigade may contain nothing if there was no more data to read. The return status tells the outcome.

opt arg2: $mode ( Apache2::Const :input_mode constant|docs::2.0::api::Apache2::Const/C__input_mode_ )

The filter mode in which the data should be read.

If inside the filter handler, you should normally pass the same mode that was passed to the filter handler (the third argument).

At the end of this section the available modes are presented.

If the argument $mode is not passed, Apache2::Const::MODE_READBYTES|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_READBYTES_ is used as a default value.

opt arg3: $block ( APR::Const :read_type constant|docs::2.0::api::APR::Const/C__input_mode_ )

You may ask the reading operation to be blocking: APR::Const::BLOCK_READ|docs::2.0::api::APR::Const/C_APR__Const__BLOCK_READ_, or nonblocking: APR::Const::NONBLOCK_READ|docs::2.0::api::APR::Const/C_APR__Const__NONBLOCK_READ_.

If inside the filter handler, you should normally pass the same blocking mode argument that was passed to the filter handler (the forth argument).

If the argument $block is not passed, APR::Const::BLOCK_READ|docs::2.0::api::APR::Const/C_APR__Const__BLOCK_READ_ is used as a default value.

opt arg4: $readbytes ( integer )

How many bytes to read from the next filter.

If inside the filter handler, you may want the same number of bytes, as the upstream filter, i.e. the argument that was passed to the filter handler (the fifth argument).

If the argument $block is not passed, 8192 is used as a default value.

ret: $rc ( APR::Const status constant|docs::2.0::api::APR::Const )

On success, APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_ is returned and $bb is populated (see the $bb entry).

In case of a failure -- a failure code is returned, in which case normally it should be returned to the caller.

If the bottom-most filter doesn't read from the network, then Apache2::NOBODY_READ is returned (META: need to add this constant).

Inside protocol handlers the return code can also be APR::Const::EOF, which is success as well.

excpt: APR::Error|docs::2.0::api::APR::Error

You don't have to ask for the return value. If this function is called in the VOID context, e.g.:

  $f->next->get_brigade($bb, $mode, $block, $readbytes);

mod_perl will do the error checking on your behalf, and if the return code is not APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_, an APR::Error exception|docs::2.0::api::APR::Error will be thrown. The only time you want to do the error checking yourself, is when return codes besides APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_ are considered as successful and you want to manage them by yourself.

since: 2.0.00

Available input filter modes (the optional second argument $mode) are:

  • Apache2::Const::MODE_READBYTES|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_READBYTES_

    The filter should return at most readbytes data

  • Apache2::Const::MODE_GETLINE|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_GETLINE_

    The filter should return at most one line of CRLF data. (If a potential line is too long or no CRLF is found, the filter may return partial data).

  • Apache2::Const::MODE_EATCRLF|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_EATCRLF_

    The filter should implicitly eat any CRLF pairs that it sees.

  • Apache2::Const::MODE_SPECULATIVE|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_SPECULATIVE_

    The filter read should be treated as speculative and any returned data should be stored for later retrieval in another mode.

  • Apache2::Const::MODE_EXHAUSTIVE|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_EXHAUSTIVE_

    The filter read should be exhaustive and read until it can not read any more. Use this mode with extreme caution.

  • Apache2::Const::MODE_INIT|docs::2.0::api::Apache2::Const/C_Apache2__Const__MODE_INIT_

    The filter should initialize the connection if needed, NNTP or FTP over SSL for example.

Either compile all these constants with:

  use Apache2::Const -compile => qw(:input_mode);

But it's a bit more efficient to compile only those constants that you need.

Example:

Here is a fragment of a filter handler, that receives a bucket brigade from the upstream filter:

  use Apache2::Filter ();
  use APR::Const    -compile => qw(SUCCESS);
  use Apache2::Const -compile => qw(OK);
  sub filter {
      my ($f, $bb, $mode, $block, $readbytes) = @_;

      my $rc = $f->next->get_brigade($bb, $mode, $block, $readbytes);
      return $rc unless $rc == APR::Const::SUCCESS;

      # ... process $bb

      return Apache2::Const::OK;
  }

Usually arguments $mode, $block, $readbytes are the same as passed to the filter itself.

You can see that in case of a failure, the handler returns immediately with that failure code, which gets propagated to the downstream filter.

If you decide not check the return code, you can write it as:

  sub filter {
      my ($f, $bb, $mode, $block, $readbytes) = @_;

      $f->next->get_brigade($bb, $mode, $block, $readbytes);

      # ... process $bb

      return Apache2::Const::OK;
  }

and the error checking will be done on your behalf.

You will find many more examples in the filter handlers|docs::2.0::user::handlers::filters and the protocol handlers|docs::2.0::user::handlers::protocols tutorials.

pass_brigade

This is a method to use in bucket brigade output filters. It passes the current bucket brigade to the downstream output filter.

  $rc = $next_f->pass_brigade($bb);
obj: $next_f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The next filter in the filter chain.

Inside output filter handlers it's usually $f->next|/C_next_. Inside protocol handlers: $c->output_filters|docs::2.0::api::Apache2::Connection/C_output_filters_.

arg1: $bb ( APR::Brigade object|docs::2.0::api::APR::Brigade )

The bucket brigade to pass.

Inside output filter handlers it's usually the second argument to the filter handler (after potential manipulations).

ret: $rc ( APR::Const status constant|docs::2.0::api::APR::Const )

On success, APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_ is returned.

In case of a failure -- a failure code is returned, in which case normally it should be returned to the caller.

If the bottom-most filter doesn't write to the network, then Apache2::NOBODY_WROTE is returned (META: need to add this constant).

Also refer to the get_brigade()|/C_get_brigade_ entry to see how to avoid checking the errors explicitly.

excpt: APR::Error|docs::2.0::api::APR::Error

Exceptions are thrown only when this function is called in the VOID context. Refer to the get_brigade()|/C_get_brigade_ entry for details.

since: 2.0.00

The caller relinquishes ownership of the brigade (i.e. it may get destroyed/overwritten/etc. by the callee).

Example:

Here is a fragment of a filter handler, that passes a bucket brigade to the downstream filter (after some potential processing of the buckets in the bucket brigade):

  use Apache2::Filter ();
  use APR::Const    -compile => qw(SUCCESS);
  use Apache2::Const -compile => qw(OK);
  sub filter {
      my ($f, $bb) = @_;

      # ... process $bb

      my $rc = $f->next->pass_brigade($bb);
      return $rc unless $rc == APR::Const::SUCCESS;

      return Apache2::Const::OK;
  }

Streaming Filter API

The following methods can be called from any filter, which uses the simplified streaming functionality:

print

Send the contents of $buffer to the next filter in chain (via internal buffer).

  $sent = $f->print($buffer);
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
arg1: $buffer ( string )

The data to send.

ret: $sent ( integer )

How many characters were sent. There is no need to check, since all should go through and if something goes work an exception will be thrown.

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

This method should be used only in streaming filters.

read

Read data from the filter

  $read = $f->read($buffer, $wanted);
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )
arg1: $buffer ( SCALAR )

The buffer to fill. All previous data will be lost.

opt arg2: $wanted ( integer )

How many bytes to attempt to read.

If this optional argument is not specified -- the default 8192 will be used.

ret: $read ( integer )

How many bytes were actually read.

$buffer gets populated with the string that is read. It will contain an empty string if there was nothing to read.

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

Reads at most $wanted characters into $buffer. The returned value $read tells exactly how many were read, making it easy to use it in a while loop:

  while ($filter->read(my $buffer, $wanted)) {
      # transform $buffer here
      $filter->print($buffer);
  }

This is a streaming filter method, which acquires a single bucket brigade behind the scenes and reads data from all its buckets. Therefore it can only read from one bucket brigade per filter invocation.

If the EOS bucket is read, the seen_eos|/C_seen_eos_ method will return a true value.

seen_eos

This methods returns a true value when the EOS bucket is seen by the read|/C_read_ method.

  $ok = $f->seen_eos;
obj: $f ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The filter to remove

ret: $ok ( boolean )

a true value if EOS has been seen, otherwise a false value

since: 2.0.00

This method only works in streaming filters which exhaustively $f->read|/C_read_ all the incoming data in a while loop, like so:

      while ($f->read(my $buffer, $wanted)) {
          # do something with $buffer
      }
      if ($f->seen_eos) {
          # do something
      }

The technique in this example is useful when a streaming filter wants to append something to the very end of data, or do something at the end of the last filter invocation. After the EOS bucket is read, the filter should expect not to be invoked again.

If an input streaming filter doesn't consume all data in the bucket brigade (or even in several bucket brigades), it has to generate the EOS event by itself. So when the filter is done it has to set the EOS flag:

  $f->seen_eos(1);

when the filter handler returns, internally mod_perl will take care of creating and sending the EOS bucket to the upstream input filter.

A similar logic may apply for output filters.

In most other cases you shouldn't set this flag. When this flag is prematurely set (before the real EOS bucket has arrived) in the current filter invocation, instead of invoking the filter again, mod_perl will create and send the EOS bucket to the next filter, ignoring any other bucket brigades that may have left to consume. As mentioned earlier this special behavior is useful in writing special tests that test abnormal situations.

Other Filter-related API

Other methods which affect filters, but called on non-Apache2::Filter objects:

add_input_filter

Add &callback filter handler to input request filter chain.

  $r->add_input_filter(\&callback);

Add &callback filter handler to input connection filter chain.

  $c->add_input_filter(\&callback);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection ) or $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: &callback (CODE ref)
ret: no return value
since: 2.0.00

[META: It seems that you can't add a filter when another filter is called. I've tried to add an output connection filter from the input connection filter when it was called for the first time. It didn't have any affect for the first request (over keepalive connection). The only way I succeeded to do that is from that input connection filter's filter_init handler. In fact it does work if there is any filter additional filter of the same kind configured from httpd.conf or via filter_init. It looks like there is a bug in httpd, where it doesn't prepare the chain of 3rd party filter if none were inserted before the first filter was called.]

add_output_filter

Add &callback filter handler to output request filter chain.

  $r->add_output_filter(\&callback);

Add &callback filter handler to output connection filter chain.

  $c->add_output_filter(\&callback);
obj: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection ) or $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: &callback (CODE ref)
ret: no return value
since: 2.0.00

Filter Handler Attributes

Packages using filter attributes have to subclass Apache2::Filter:

  package MyApache2::FilterCool;
  use base qw(Apache2::Filter);

Attributes are parsed during the code compilation, by the function MODIFY_CODE_ATTRIBUTES, inherited from the Apache2::Filter package.

FilterRequestHandler

The FilterRequestHandler attribute tells mod_perl to insert the filter into an HTTP request filter chain.

For example, to configure an output request filter handler, use the FilterRequestHandler attribute in the handler subroutine's declaration:

  package MyApache2::FilterOutputReq;
  sub handler : FilterRequestHandler { ... }

and add the configuration entry:

  PerlOutputFilterHandler MyApache2::FilterOutputReq

This is the default mode. So if you are writing an HTTP request filter, you don't have to specify this attribute.

The section HTTP Request vs. Connection Filters delves into more details.

FilterConnectionHandler

The FilterConnectionHandler attribute tells mod_perl to insert this filter into a connection filter chain.

For example, to configure an output connection filter handler, use the FilterConnectionHandler attribute in the handler subroutine's declaration:

  package MyApache2::FilterOutputCon;
  sub handler : FilterConnectionHandler { ... }

and add the configuration entry:

  PerlOutputFilterHandler MyApache2::FilterOutputCon

The section HTTP Request vs. Connection Filters delves into more details.

FilterInitHandler

The attribute FilterInitHandler marks the function suitable to be used as a filter initialization callback, which is called immediately after a filter is inserted to the filter chain and before it's actually called.

  sub init : FilterInitHandler {
      my $f = shift;
      #...
      return Apache2::Const::OK;
  }

In order to hook this filter callback, the real filter has to assign this callback using the FilterHasInitHandler|/C_FilterHasInitHandler_ which accepts a reference to the callback function.

For further discussion and examples refer to the Filter Initialization Phase tutorial section.

FilterHasInitHandler

If a filter wants to run an initialization callback it can register such using the FilterHasInitHandler attribute. Similar to push_handlers the callback reference is expected, rather than a callback name. The used callback function has to have the FilterInitHandler|/C_FilterInitHandler_ attribute. For example:

  package MyApache2::FilterBar;
  use base qw(Apache2::Filter);
  sub init   : FilterInitHandler { ... }
  sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
      my ($f, $bb) = @_;
      # ...
      return Apache2::Const::OK;
  }

For further discussion and examples refer to the Filter Initialization Phase tutorial section.

Configuration

mod_perl 2.0 filters configuration is explained in the filter handlers tutorial.

PerlInputFilterHandler

See PerlInputFilterHandler|docs::2.0::user::handlers::filters/C_PerlInputFilterHandler_.

PerlOutputFilterHandler

See PerlOutputFilterHandler|docs::2.0::user::handlers::filters/C_PerlOutputFilterHandler_.

PerlSetInputFilter

See PerlSetInputFilter|docs::2.0::user::handlers::filters/C_PerlSetInputFilter_.

PerlSetOutputFilter

See PerlSetInputFilter|docs::2.0::user::handlers::filters/C_PerlSetInputFilter_.

TIE Interface

Apache2::Filter also implements a tied interface, so you can work with the $f object as a hash reference.

The TIE interface is mostly unimplemented and might be implemented post 2.0 release.

TIEHANDLE

  $ret = TIEHANDLE($stashsv, $sv);
obj: $stashsv ( SCALAR )
arg1: $sv ( SCALAR )
ret: $ret ( SCALAR )
since: subject to change

PRINT

  $ret = PRINT(...);
obj: ... (XXX)
ret: $ret ( integer )
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::FilterRec - Perl API for manipulating the Apache filter record

  • Synopsis
  • Description
  • API
    • name
  • See Also
  • Copyright
  • Authors

NAME

Apache2::FilterRec - Perl API for manipulating the Apache filter record

Synopsis

  use Apache2::Filter ();
  use Apache2::FilterRec ();

  my $frec = $filter->frec;
  print "filter name is:", $frec->name;

Description

Apache2::FilterRec provides an access to the filter record structure.

The Apache2::FilterRec object is retrieved by calling frec()|docs::2.0::api::Apache2::Filter/C_frec_:

  $frec = $filter->frec;

API

Apache2::FilterRec provides the following functions and/or methods:

name

The registered name for this filter

  $name = $frec->name();
obj: $frec ( Apache2::FilterRec object|docs::2.0::api::Apache2::FilterRec )
ret: $name (string)
since: 2.0.00

mod_perl filters have four names:

  modperl_request_output
  modperl_request_input
  modperl_connection_output
  modperl_connection_input

You can see the names of the non-mod_perl filters as well. By calling $filter->next->frec->name|docs::2.0::api::Apache2::Filter/C_next_ you can get the name of the next filter in the chain.

Example:

Let's print the name of the current and the filter that follows it:

  use Apache2::Filter ();
  use Apache2::FilterRec ();
  for my $frec ($filter->frec, $filter->next->frec) {
      print "Name: ", $frec->name;
  }

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::HookRun - Perl API for Invoking Apache HTTP phases

  • Synopsis
  • Description
  • API
    • die
    • invoke_handler
    • run_access_checker
    • run_auth_checker
    • run_check_user_id
    • run_fixups
    • run_handler
    • run_header_parser
    • run_log_transaction
    • run_map_to_storage
    • run_post_read_request
    • run_translate_name
    • run_type_checker
  • See Also
  • Copyright
  • Authors

NAME

Apache2::HookRun - Perl API for Invoking Apache HTTP phases

Synopsis

  # httpd.conf
  PerlProcessConnectionHandler MyApache2::PseudoHTTP::handler
  #file:MyApache2/PseudoHTTP.pm
  #---------------------------
  package MyApache2::PseudoHTTP;

  use Apache2::HookRun ();
  use Apache2::RequestUtil ();
  use Apache2::RequestRec ();

  use Apache2::Const -compile => qw(OK DECLINED DONE SERVER_ERROR);

  # implement the HTTP protocol cycle in protocol handler
  sub handler {
      my $c = shift;
      my $r = Apache2::RequestRec->new($c);

      # register any custom callbacks here, e.g.:
      # $r->push_handlers(PerlAccessHandler => \&my_access);

      $rc = $r->run_post_read_request();
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_translate_name;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_map_to_storage;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      # this must be run all a big havoc will happen in the following
      # phases
      $r->location_merge($path);

      $rc = $r->run_header_parser;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      my $args = $r->args || '';
      if ($args eq 'die') {
          $r->die(Apache2::Const::SERVER_ERROR);
          return Apache2::Const::DONE;
      }

      $rc = $r->run_access_checker;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_auth_checker;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_check_user_id;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_type_checker;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_fixups;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      # $r->run_handler is called internally by $r->invoke_handler,
      # invoke_handler sets all kind of filters, and does a few other
      # things but it's possible to call $r->run_handler, bypassing
      # invoke_handler
      $rc = $r->invoke_handler;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      $rc = $r->run_log_transaction;
      return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;

      return Apache2::Const::OK;
  }

Description

Apache2::HookRun exposes parts of the Apache HTTP protocol implementation, responsible for invoking callbacks for each HTTP Request cycle phase.

Armed with that API, you could run some of the http protocol framework parts when implementing your own protocols. For example see how HTTP AAA (access, auth and authz) hooks are called from a protocol handler, implementing a command server, which has nothing to do with HTTP. Also you can see in Synopsis how to re-implement Apache HTTP cycle in the protocol handler.

Using this API you could probably also change the normal Apache behavior (e.g. invoking some hooks earlier than normal, or later), but before doing that you will probably need to spend some time reading through the Apache C code. That's why some of the methods in this document, point you to the specific functions in the Apache source code. If you just try to use the methods from this module, without understanding them well, don't be surprised if you will get some nasty crashes, from which mod_perl can't protect you.

API

Apache2::HookRun provides the following functions and/or methods:

die

Kill the current request

  $r->die($type);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $type ( integer )

Why the request is dieing. Expects an Apache status constant.

ret: no return value
since: 2.0.00

This method doesn't really abort the request, it just handles the sending of the error response, logging the error and such. You want to take a look at the internals of ap_die() in httpd-2.0/modules/http/http_request.c for more details.

invoke_handler

Run the response phase.

  $rc = $r->invoke_handler();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::HTTP_...

since: 2.0.00

invoke_handler() allows modules to insert filters, sets a default handler if none is set, runs run_handler()|/C_run_handler_ and handles some errors.

For more details see ap_invoke_handler() in httpd-2.0/server/config.c.

run_access_checker

Run the resource access control phase.

  $rc = $r->run_access_checker();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

the current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This phase runs before a user is authenticated, so this hook is really to apply additional restrictions independent of a user. It also runs independent of 'Require' directive usage.

run_auth_checker

Run the authentication phase.

  $rc = $r->run_auth_checker();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

the current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This phase is used to check to see if the resource being requested is available for the authenticated user ($r->user and $r->ap_auth_type).

It runs after the access_checker and check_user_id hooks.

Note that it will only be called if Apache determines that access control has been applied to this resource (through a 'Require' directive).

run_check_user_id

Run the authorization phase.

  $rc = $r->run_check_user_id();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This hook is used to analyze the request headers, authenticate the user, and set the user information in the request record ($r->user and $r->ap_auth_type).

This hook is only run when Apache determines that authentication/authorization is required for this resource (as determined by the 'Require' directive).

It runs after the access_checker hook, and before the auth_checker hook.

run_fixups

Run the fixup phase.

  $rc = $r->run_fixups();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This phase allows modules to perform module-specific fixing of HTTP header fields. This is invoked just before the response phase.

run_handler

Run the response phase.

  $rc = $r->run_handler();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The request_rec

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

run_handler() is called internally by invoke_handler()|/C_invoke_handler_. Use run_handler() only if you want to bypass the extra functionality provided by invoke_handler()|/C_invoke_handler_.

run_header_parser

Run the header parser phase.

  $rc = $r->run_header_parser();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

Apache2::Const::OK or Apache2::Const::DECLINED.

since: 2.0.00

run_log_transaction

Run the logging phase.

  $rc = $r->run_log_transaction();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_...

since: 2.0.00

This hook allows modules to perform any module-specific logging activities over and above the normal server things.

run_map_to_storage

Run the map_to_storage phase.

  $rc = $r->run_map_to_storage();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

Apache2::Const::DONE (or Apache2::HTTP_*) if this contextless request was just fulfilled (such as TRACE), Apache2::Const::OK if this is not a file, and Apache2::Const::DECLINED if this is a file. The core map_to_storage (Apache2::HOOK_RUN_LAST) will directory_walk() and file_walk() the $r->filename (all internal C functions).

since: 2.0.00

This phase allows modules to set the per_dir_config based on their own context (such as <Proxy> sections) and responds to contextless requests such as TRACE that need no security or filesystem mapping based on the filesystem.

run_post_read_request

Run the post_read_request phase.

  $rc = $r->run_post_read_request();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK or Apache2::Const::DECLINED.

since: 2.0.00

This phase is run right after read_request() or internal_redirect(), and not run during any subrequests. This hook allows modules to affect the request immediately after the request has been read, and before any other phases have been processes. This allows modules to make decisions based upon the input header fields

run_translate_name

Run the translate phase.

  $rc = $r->run_translate_name();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This phase gives modules an opportunity to translate the URI into an actual filename. If no modules do anything special, the server's default rules will be applied.

run_type_checker

Run the type_checker phase.

  $rc = $r->run_type_checker();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

the current request

ret: $rc ( integer )

The status of the current phase run: Apache2::Const::OK, Apache2::Const::DECLINED, Apache2::HTTP_....

since: 2.0.00

This phase is used to determine and/or set the various document type information bits, like Content-type (via $r->content_type), language, etc.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Log - Perl API for Apache Logging Methods

  • Synopsis
  • Description
  • Constants
    • LogLevel Constants
      • Apache2::Const::LOG_EMERG
      • Apache2::Const::LOG_ALERT
      • Apache2::Const::LOG_CRIT
      • Apache2::Const::LOG_ERR
      • Apache2::Const::LOG_WARNING
      • Apache2::Const::LOG_NOTICE
      • Apache2::Const::LOG_INFO
      • Apache2::Const::LOG_DEBUG
    • Other Constants
      • Apache2::Const::LOG_LEVELMASK
      • Apache2::Const::LOG_TOCLIENT
      • Apache2::Const::LOG_STARTUP
  • Server Logging Methods
    • $s->log
    • $s->log_error
    • $s->log_serror
    • $s->warn
  • Request Logging Methods
    • $r->log
    • $r->log_error
    • $r->log_reason
    • $r->log_rerror
    • $r->warn
  • Other Logging Methods
    • LogLevel Methods
    • alert
    • crit
    • debug
    • emerg
    • error
    • info
    • notice
    • warn
  • General Functions
    • LOG_MARK
  • Virtual Hosts
  • Unsupported API
    • log_pid
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Log - Perl API for Apache Logging Methods

Synopsis

  # in startup.pl
  #--------------
  use Apache2::Log;

  use Apache2::Const -compile => qw(OK :log);
  use APR::Const    -compile => qw(:error SUCCESS);

  my $s = Apache2::ServerUtil->server;

  $s->log_error("server: log_error");
  $s->log_serror(__FILE__, __LINE__, Apache2::Const::LOG_ERR,
                 APR::Const::SUCCESS, "log_serror logging at err level");
  $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
                 APR::Const::ENOTIME, "debug print");
  Apache2::ServerRec->log_error("routine warning");

  Apache2::ServerRec::warn("routine warning");

  # in a handler
  #-------------
  package Foo;

  use strict;
  use warnings FATAL => 'all';

  use Apache2::Log;

  use Apache2::Const -compile => qw(OK :log);
  use APR::Const    -compile => qw(:error SUCCESS);

  sub handler {
      my $r = shift;
      $r->log_error("request: log_error");

      my $rlog = $r->log;
      for my $level qw(emerg alert crit error warn notice info debug) {
          no strict 'refs';
          $rlog->$level($package, "request: $level log level");
      }

      # can use server methods as well
      my $s = $r->server;
      $s->log_error("server: log_error");

      $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
                     APR::Const::ENOTIME, "in debug");

      $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_INFO,
                     APR::Const::SUCCESS, "server info");

      $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
                     APR::Const::ENOTIME, "fatal error");

      $r->log_reason("fatal error");
      $r->warn('routine request warning');
      $s->warn('routine server warning');

      return Apache2::Const::OK;
  }
  1;

  # in a registry script
  # httpd.conf: PerlOptions +GlobalRequest
  use Apache2::ServerRec qw(warn); # override warn locally
  print "Content-type: text/plain\n\n";
  warn "my warning";

Description

Apache2::Log provides the Perl API for Apache logging methods.

Depending on the the current LogLevel setting, only logging with the same log level or higher will be loaded. For example if the current LogLevel is set to warning, only messages with log level of the level warning or higher (err, crit, elert and emerg) will be logged. Therefore this:

  $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
                 APR::Const::ENOTIME, "warning!");

will log the message, but this one won't:

  $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_INFO,
                 APR::Const::ENOTIME, "just an info");

It will be logged only if the server log level is set to info or debug. LogLevel is set in the configuration file, but can be changed using the $s->loglevel()|docs::2.0::api::Apache2::ServerRec/C_loglevel_ method.

The filename and the line number of the caller are logged only if Apache2::Const::LOG_DEBUG is used (because that's how Apache 2.0 logging mechanism works).

Note: On Win32 Apache attempts to lock all writes to a file whenever it's opened for append (which is the case with logging functions), as Unix has this behavior built-in, while Win32 does not. Therefore Apache2::Log functions could be slower than Perl's print()/warn().

Constants

Log level constants can be compiled all at once:

  use Apache2::Const -compile => qw(:log);

or individually:

  use Apache2::Const -compile => qw(LOG_DEBUG LOG_INFO);

LogLevel Constants

The following constants (sorted from the most severe level to the least severe) are used in logging methods to specify the log level at which the message should be logged:

Apache2::Const::LOG_EMERG

Apache2::Const::LOG_ALERT

Apache2::Const::LOG_CRIT

Apache2::Const::LOG_ERR

Apache2::Const::LOG_WARNING

Apache2::Const::LOG_NOTICE

Apache2::Const::LOG_INFO

Apache2::Const::LOG_DEBUG

Other Constants

Make sure to compile the APR status constants before using them. For example to compile APR::Const::SUCCESS and all the APR error status constants do:

  use APR::Const    -compile => qw(:error SUCCESS);

Here is the rest of the logging related constants:

Apache2::Const::LOG_LEVELMASK

used to mask off the level value, to make sure that the log level's value is within the proper bits range. e.g.:

  $loglevel &= LOG_LEVELMASK;

Apache2::Const::LOG_TOCLIENT

used to give content handlers the option of including the error text in the ErrorDocument sent back to the client. When Apache2::Const::LOG_TOCLIENT is passed to log_rerror() the error message will be saved in the $r's notes table, keyed to the string "error-notes", if and only if the severity level of the message is Apache2::Const::LOG_WARNING or greater and there are no other "error-notes" entry already set in the request record's notes table. Once the "error-notes" entry is set, it is up to the error handler to determine whether this text should be sent back to the client. For example:

  use Apache2::Const -compile => qw(:log);
  use APR::Const    -compile => qw(ENOTIME);
  $r->log_rerror(Apache2::Log::LOG_MARK,
                 Apache2::Const::LOG_ERR|Apache2::Const::LOG_TOCLIENT,
                 APR::Const::ENOTIME,
                 "request log_rerror");

now the log message can be retrieved via:

  $r->notes->get("error-notes");

Remember that client-generated text streams sent back to the client MUST be escaped to prevent CSS attacks.

Apache2::Const::LOG_STARTUP

is useful for startup message where no timestamps, logging level is wanted. For example:

  use Apache2::Const -compile => qw(:log);
  use APR::Const    -compile => qw(SUCCESS);
  $s->log_serror(Apache2::Log::LOG_MARK,
                 Apache2::Const::LOG_INFO,
                 APR::Const::SUCCESS,
                 "This log message comes with a header");

will print:

  [Wed May 14 16:47:09 2003] [info] This log message comes with a header

whereas, when Apache2::Const::LOG_STARTUP is binary ORed as in:

  use Apache2::Const -compile => qw(:log);
  use APR::Const    -compile => qw(SUCCESS);
  $s->log_serror(Apache2::Log::LOG_MARK,
                 Apache2::Const::LOG_INFO|Apache2::Const::LOG_STARTUP,
                 APR::Const::SUCCESS,
                 "This log message comes with no header");

then the logging will be:

  This log message comes with no header

Server Logging Methods

$s->log

get a log handle which can be used to log messages of different levels.

  my $slog = $s->log;
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $slog ( Apache2::Log::Server object )

Apache2::Log::Server object to be used with LogLevel methods.

since: 2.0.00

$s->log_error

just logs the supplied message to error_log

  $s->log_error(@message);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: @message ( strings ARRAY )

what to log

ret: no return value
since: 2.0.00

For example:

  $s->log_error("running low on memory");

$s->log_serror

This function provides a fine control of when the message is logged, gives an access to built-in status codes.

  $s->log_serror($file, $line, $level, $status, @message);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $file ( string )

The file in which this function is called

arg2: $line ( number )

The line number on which this function is called

arg3: $level ( Apache2::LOG_* constant|/LogLevel_Constants )

The level of this error message

arg4: $status ( APR::Const status constant|docs::2.0::api::APR::Const )

The status code from the last command (similar to $! in perl), usually APR::Const constant|docs::2.0::api::APR::Const or coming from an exception object.

arg5: @message ( strings ARRAY )

The log message(s)

ret: no return value
since: 2.0.00

For example:

  use Apache2::Const -compile => qw(:log);
  use APR::Const    -compile => qw(ENOTIME SUCCESS);
  $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
                 APR::Const::SUCCESS, "log_serror logging at err level");

  $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
                 APR::Const::ENOTIME, "debug print");

$s->warn

  $s->warn(@warnings);

is the same as:

  $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
                 APR::Const::SUCCESS, @warnings)
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: @warnings ( strings ARRAY )

array of warning strings

ret: no return value
since: 2.0.00

For example:

  $s->warn('routine server warning');

Request Logging Methods

$r->log

get a log handle which can be used to log messages of different levels.

  $rlog = $r->log;
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $rlog ( Apache2::Log::Request object )

Apache2::Log::Request object to be used with LogLevel methods.

since: 2.0.00

$r->log_error

just logs the supplied message (similar to $s->log_error|/C__s_E_gt_log_error_ ).

  $r->log_error(@message);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: @message ( strings ARRAY )

what to log

ret: no return value
since: 2.0.00

For example:

  $r->log_error("the request is about to end");

$r->log_reason

This function provides a convenient way to log errors in a preformatted way:

  $r->log_reason($message);
  $r->log_reason($message, $filename);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $message ( string )

the message to log

opt arg2: $filename ( string )

where to report the error as coming from (e.g. __FILE__)

ret: no return value
since: 2.0.00

For example:

  $r->log_reason("There is no enough data");

will generate a log entry similar to the following:

  [Fri Sep 24 11:58:36 2004] [error] access to /someuri
  failed for 127.0.0.1, reason: There is no enough data.

$r->log_rerror

This function provides a fine control of when the message is logged, gives an access to built-in status codes.

  $r->log_rerror($file, $line, $level, $status, @message);

arguments are identical to $s->log_serror|/C__s_E_gt_log_serror_.

since: 2.0.00

For example:

  use Apache2::Const -compile => qw(:log);
  use APR::Const    -compile => qw(ENOTIME SUCCESS);
  $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
                 APR::Const::SUCCESS, "log_rerror logging at err level");

  $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
                 APR::Const::ENOTIME, "debug print");

$r->warn

  $r->warn(@warnings);

is the same as:

  $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
                 APR::Const::SUCCESS, @warnings)
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: @warnings ( strings ARRAY )

array of warning strings

ret: no return value
since: 2.0.00

For example:

  $r->warn('routine server warning');

Other Logging Methods

LogLevel Methods

after getting the log handle with $s->log|/C__s_E_gt_log_ or $r->log|/C__s_E_gt_log_, use one of the following methods (corresponding to the LogLevel levels):

  emerg(), alert(), crit(), error(), warn(), notice(), info(), debug()

to control when messages should be logged:

  $s->log->emerg(@message);
  $r->log->emerg(@message);
obj: $slog ( server or request log handle )
arg1: @message ( strings ARRAY )
ret: no return value
since: 2.0.00

For example if the LogLevel is error and the following code is executed:

  my $slog = $s->log;
  $slog->debug("just ", "some debug info");
  $slog->warn(@warnings);
  $slog->crit("dying");

only the last command's logging will be performed. This is because warn, debug and other logging command which are listed right to error will be disabled.

alert

See LogLevel Methods.

crit

See LogLevel Methods.

debug

See LogLevel Methods.

emerg

See LogLevel Methods.

error

See LogLevel Methods.

info

See LogLevel Methods.

notice

See LogLevel Methods.

Though Apache treats notice() calls as special. The message is always logged regardless the value of ErrorLog, unless the error log is set to use syslog. (For details see httpd-2.0/server/log.c.)

warn

See LogLevel Methods.

General Functions

LOG_MARK

Though looking like a constant, this is a function, which returns a list of two items: (__FILE__, __LINE__), i.e. the file and the line where the function was called from.

  my ($file, $line) = Apache2::Log::LOG_MARK();
ret1: $file ( string )
ret2: $line ( number )
since: 2.0.00

It's mostly useful to be passed as the first argument to those logging methods, expecting the filename and the line number as the first arguments (e.g., $s->log_serror|/C__s_E_gt_log_serror_ and $r->log_rerror|/C__r_E_gt_log_rerror_ ).

Virtual Hosts

Code running from within a virtual host needs to be able to log into its ErrorLog file, if different from the main log. Calling any of the logging methods on the $r and $s objects will do the logging correctly.

If the core warn() is called, it'll be always logged to the main log file. Here is how to make it log into the vhost error_log file. Let's say that we start with the following code:

  warn "the code is smoking";

  1. First, we need to use mod_perl's logging function, instead of CORE::warn

    Either replace warn with Apache2::ServerRec::warn:

      use Apache2::Log ();
  Apache2::ServerRec::warn("the code is smoking");

    or import it into your code:

      use Apache2::ServerRec qw(warn); # override warn locally
  warn "the code is smoking";

    or override CORE::warn:

      use Apache2::Log ();
  *CORE::GLOBAL::warn = \&Apache2::ServerRec::warn;
  warn "the code is smoking";

    Avoid using the latter suggestion, since it'll affect all the code running on the server, which may break things. Of course you can localize that as well:

      use Apache2::Log ();
  local *CORE::GLOBAL::warn = \&Apache2::ServerRec::warn;
  warn "the code is smoking";

    Chances are that you need to make the internal Perl warnings go into the vhost's error_log file as well. Here is how to do that:

      use Apache2::Log ();
  local $SIG{__WARN__} = \&Apache2::ServerRec::warn;
  eval q[my $x = "aaa" + 1;]; # this issues a warning

    Notice that it'll override any previous setting you may have had, disabling modules like CGI::Carp which also use $SIG{__WARN__}

  2. Next we need to figure out how to get hold of the vhost's server object.

    Inside HTTP request handlers this is possible via Apache2->request|docs::2.0::api::Apache2::RequestUtil/C_request_. Which requires either PerlOptions +GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_ setting or can be also done at runtime if $r is available:

      use Apache2::RequestUtil ();
  sub handler {
      my $r = shift;
      Apache2::RequestUtil->request($r);
      ...

    Outside HTTP handlers at the moment it is not possible, to get hold of the vhost's error_log file. This shouldn't be a problem for the code that runs only under mod_perl, since the always available $s object can invoke a plethora of methods supplied by Apache2::Log. This is only a problem for modules, which are supposed to run outside mod_perl as well.

    META: To solve this we think to introduce 'PerlOptions +GlobalServer', a big brother for 'PerlOptions +GlobalRequest', which will be set in modperl_hook_pre_connection.

Unsupported API

Apache2::Log also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

log_pid

META: what is this method good for? it just calls getpid and logs it. In any case it has nothing to do with the logging API. And it uses static variables, it probably shouldn't be in the Apache public API.

Log the current pid

  Apache2::Log::log_pid($pool, $fname);
obj: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to use for logging

arg1: $fname ( file path )

The name of the file to log to

ret: no return value
since: subject to change

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::MPM - Perl API for accessing Apache MPM information

  • Synopsis
  • Description
  • API
    • query
    • is_threaded
    • show
  • See Also
  • Copyright
  • Authors

NAME

Apache2::MPM - Perl API for accessing Apache MPM information

Synopsis

  use Apache2::MPM ();

  # check whether Apache MPM is threaded
  if (Apache2::MPM->is_threaded) { do_something() }

  # which mpm is used
  my $mpm = lc Apache2::MPM->show;

  # query mpm properties
  use Apache2::Const -compile => qw(:mpmq);
  if (Apache2::MPM->query(Apache2::Const::MPMQ_STATIC)) { ... }

Description

Apache2::MPM provides the Perl API for accessing Apache MPM information.

API

Apache2::MPM provides the following functions and/or methods:

query

Query various attributes of the MPM

  my $query = Apache2::MPM->query($const);
obj: $class ( Apache2::MPM class|docs::2.0::api::Apache2::MPM )

the class name

arg1: $const ( Apache2::Const :mpmq group constant|docs::2.0::api::Apache2::Const/C__mpmq_ )

The MPM attribute to query.

ret: $query ( boolean )

the result of the query

since: 2.0.00

For example to test whether the mpm is static:

  use Apache2::Const -compile => qw(MPMQ_STATIC);
  if (Apache2::MPM->query(Apache2::Const::MPMQ_STATIC)) { ... }

is_threaded

Check whether the running Apache MPM is threaded.

  my $is_threaded = Apache2::MPM->is_threaded;
obj: $class ( Apache2::MPM class|docs::2.0::api::Apache2::MPM )

the class name

ret: $is_threaded ( boolean )

threaded or not

since: 2.0.00

Note that this functionality is just a shortcut for:

  use Apache2::Const -compile => qw(MPMQ_IS_THREADED);
  my $is_threaded = Apache2::MPM->query(Apache2::Const::MPMQ_IS_THREADED);

show

What mpm is used

  my $mpm = Apache2::MPM->show();
obj: $class ( Apache2::MPM class|docs::2.0::api::Apache2::MPM )

the class name

ret: $mpm ( string )

the name of the MPM. e.g., "Prefork".

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Module - Perl API for creating and working with Apache modules

  • Synopsis
  • Description
  • API
    • add
    • ap_api_major_version
    • ap_api_minor_version
    • cmds
    • get_config
    • find_linked_module
    • loaded
    • module_index
    • name
    • next
    • remove_loaded_module
    • top_module
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Module - Perl API for creating and working with Apache modules

Synopsis

  use Apache2::Module ();

  #Define a configuration directive
  my @directives = (
      {
          name => 'MyDirective',
      }
  );

  Apache2::Module::add(__PACKAGE__, \@directives);

  # iterate over the whole module list
  for (my $modp = Apache2::Module::top_module(); $modp; $modp = $modp->next) {
      my $name                  = $modp->name;
      my $index                 = $modp->module_index;
      my $ap_api_major_version  = $modp->ap_api_major_version;
      my $ap_api_minor_version  = $modp->ap_api_minor_version;
      my $commands              = $modp->cmds;
  }

  # find a specific module
  my $module = Apache2::Module::find_linked_module('mod_ssl.c');

  # remove a specific module
  $module->remove_loaded_module();

  # access module configuration from a directive
  sub MyDirective {
      my ($self, $parms, $args) = @_;
      my  $srv_cfg = Apache2::Module::get_config($self, $parms->server);
      [...]
  }

  # test if an Apache module is loaded
  if (Apache2::Module::loaded('mod_ssl.c')) {
      [...]
  }

  # test if a Perl module is loaded
  if (Apache2::Module::loaded('Apache2::Status')) {
      [...]
  }

Description

Apache2::Module provides the Perl API for creating and working with Apache modules

See Apache Server Configuration Customization in Perl.

API

Apache2::Module provides the following functions and/or methods:

add

Add a module's custom configuration directive to Apache.

  Apache2::Module::add($package, $cmds);
arg1: $package ( string )

the package of the module to add

arg2: $cmds ( ARRAY of HASH refs )

the list of configuration directives to add

ret: no return value
since: 2.0.00

See also Apache Server Configuration Customization in Perl.

ap_api_major_version

Get the httpd API version this module was build against, not the module's version.

  $major_version = $module->ap_api_major_version();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $major_version ( integer )
since: 2.0.00

This methid is used to check that module is compatible with this version of the server before loading it.

ap_api_minor_version

Get the module API minor version.

  $minor_version = $module->ap_api_minor_version();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $minor_version ( integer )
since: 2.0.00

ap_api_minor_version() provides API feature milestones.

It's not checked during module init.

cmds

Get the Apache2::Command|docs::2.0::api::Apache2::Command object, describing all of the directives this module defines.

  $command = $module->cmds();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $command ( Apache2::Command object|docs::2.0::api::Apache2::Command )
since: 2.0.00

get_config

Retrieve a module's configuration. Used by configuration directives.

  $cfg = Apache2::Module::get_config($class, $server, $dir_config);
  $cfg = Apache2::Module::get_config($class, $server);
  $cfg =          $self->get_config($server, $dir_config);
  $cfg =          $self->get_config($server);
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
arg1: $class ( string )

The Perl package this configuration is for

arg2: $server ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )

The current server, typically $r->server|docs::2.0::api::Apache2::ServerUtil or $parms->server|docs::2.0::api::Apache2::CmdParms.

opt arg3: $dir_config ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )

By default, the configuration returned is the server level one. To retrieve the per directory configuration, use $r->per_dir_config|docs::2.0::api::Apache2::RequestRec as a last argument.

ret: $cfg (HASH reference)

A reference to the hash holding the module configuration data.

since: 2.0.00

See also Apache Server Configuration Customization in Perl.

find_linked_module

Find a module based on the name of the module

  $module = Apache2::Module::find_linked_module($name);
arg1: $name ( string )

The name of the module ending in .c

ret: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )

The module object if found, undef otherwise.

since: 2.0.00

For example:

  my $module = Apache2::Module::find_linked_module('mod_ssl.c');

loaded

Determine if a certain module is loaded

  $loaded = Apache2::Module::loaded($module);
name: $module ( string )

The name of the module to search for.

If $module ends with .c, search all the modules, statically compiled and dynamically loaded.

If $module ends with .so, search only the dynamically loaded modules.

If $module doesn't contain a ., search the loaded Perl modules (checks %INC).

ret: $loaded ( boolean )

Returns true if the module is loaded, false otherwise.

since: 2.0.00

For example, to test if this server supports ssl:

  if (Apache2::Module::loaded('mod_ssl.c')) {
      [...]
  }

To test is this server dynamically loaded mod_perl:

  if (Apache2::Module::loaded('mod_perl.so')) {
      [...]
  }

To test if Apache2::Status|docs::2.0::api::Apache2::Status is loaded:

  if (Apache2::Module::loaded('Apache2::Status')) {
      [...]
  }

module_index

Get the index to this modules structures in config vectors.

  $index = $module->module_index();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $index ( integer )
since: 2.0.00

name

Get the name of the module's .c file

  $name = $module->name();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $name ( string )
since: 2.0.00

For example a mod_perl module, will return: mod_perl.c.

next

Get the next module in the list, undef if this is the last module in the list.

  $next_module = $module->next();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: $next_module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
since: 2.0.00

remove_loaded_module

Remove a module from the list of loaded modules permanently.

  $module->remove_loaded_module();
obj: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
ret: no return value
since: 2.0.00

top_module

Returns the first module in the module list. Usefull to start a module iteration.

  $module = Apache2::Module::top_module();
ret: $module ( Apache2::Module object|docs::2.0::api::Apache2::Module )
since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::PerlSections - write Apache configuration files in Perl

  • Synopsis
  • Description
  • API
    • server
  • @PerlConfig and $PerlConfig
  • Configuration Variables
    • $Apache2::PerlSections::Save
  • PerlSections Dumping
    • Apache2::PerlSections->dump
    • Apache2::PerlSections->store
  • Advanced API
  • Verifying <Perl> Sections
  • Bugs
    • <Perl> directive missing closing '>'
    • <Perl>[...]> was not closed.
  • See Also
  • Copyright
  • Authors

NAME

Apache2::PerlSections - write Apache configuration files in Perl

Synopsis

  <Perl>
  @PerlModule = qw(Mail::Send Devel::Peek);

  #run the server as whoever starts it
  $User  = getpwuid(>) || >;
  $Group = getgrgid()) || );

  $ServerAdmin = $User;

  </Perl>

Description

With <Perl>...</Perl> sections, it is possible to configure your server entirely in Perl.

<Perl> sections can contain any and as much Perl code as you wish. These sections are compiled into a special package whose symbol table mod_perl can then walk and grind the names and values of Perl variables/structures through the Apache core configuration gears.

Block sections such as <Location>..</Location> are represented in a %Location hash, e.g.:

  <Perl>
  $Location{"/~dougm/"} = {
    AuthUserFile   => '/tmp/htpasswd',
    AuthType       => 'Basic',
    AuthName       => 'test',
    DirectoryIndex => [qw(index.html index.htm)],
    Limit          => {
        "GET POST"    => {
            require => 'user dougm',
        }
    },
  };
  </Perl>

If an Apache directive can take two or three arguments you may push strings (the lowest number of arguments will be shifted off the @list) or use an array reference to handle any number greater than the minimum for that directive:

  push @Redirect, "/foo", "http://www.foo.com/";

  push @Redirect, "/imdb", "http://www.imdb.com/";

  push @Redirect, [qw(temp "/here" "http://www.there.com")];

Other section counterparts include %VirtualHost, %Directory and %Files.

To pass all environment variables to the children with a single configuration directive, rather than listing each one via PassEnv or PerlPassEnv, a <Perl> section could read in a file and:

  push @PerlPassEnv, [$key => $val];

or

  Apache2->httpd_conf("PerlPassEnv $key $val");

These are somewhat simple examples, but they should give you the basic idea. You can mix in any Perl code you desire. See eg/httpd.conf.pl and eg/perl_sections.txt in the mod_perl distribution for more examples.

Assume that you have a cluster of machines with similar configurations and only small distinctions between them: ideally you would want to maintain a single configuration file, but because the configurations aren't exactly the same (e.g. the ServerName directive) it's not quite that simple.

<Perl> sections come to rescue. Now you have a single configuration file and the full power of Perl to tweak the local configuration. For example to solve the problem of the ServerName directive you might have this <Perl> section:

  <Perl>
  $ServerName = `hostname`;
  </Perl>

For example if you want to allow personal directories on all machines except the ones whose names start with secure:

  <Perl>
  $ServerName = `hostname`;
  if ($ServerName !~ /^secure/) {
      $UserDir = "public.html";
  }
  else {
      $UserDir = "DISABLED";
  }
  </Perl>

API

Apache2::PerlSections provides the following functions and/or methods:

server

Get the current server's object for the <Perl> section

  <Perl>
    $s = Apache2::PerlSections->server();
  </Perl>
obj: Apache2::PerlSections (class name)
ret: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.03

@PerlConfig and $PerlConfig

This array and scalar can be used to introduce literal configuration into the apache configuration. For example:

  push @PerlConfig, 'Alias /foo /bar';

Or: $PerlConfig .= "Alias /foo /bar\n";

See also $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_add_config_

Configuration Variables

There are a few variables that can be set to change the default behaviour of <Perl> sections.

$Apache2::PerlSections::Save

Each <Perl> section is evaluated in its unique namespace, by default residing in a sub-namespace of Apache2::ReadConfig::, therefore any local variables will end up in that namespace. For example if a <Perl> section happened to be in file /tmp/httpd.conf starting on line 20, the namespace: Apache2::ReadConfig::tmp::httpd_conf::line_20 will be used. Now if it had:

  <Perl>
    $foo     = 5;
    my $bar  = 6;
    $My::tar = 7;
  </Perl>

The local global variable $foo becomes $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, the other variable remain where they are.

By default, the namespace in which <Perl> sections are evaluated is cleared after each block closes. In our example nuking $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo, leaving the rest untouched.

By setting $Apache2::PerlSections::Save to a true value, the content of those namespaces will be preserved and will be available for inspection by Apache2::Status|docs::2.0::api::Apache2::Status and Apache2::PerlSections->dump|/C_Apache2__PerlSections_E_gt_dump_ In our example $Apache2::ReadConfig::tmp::httpd_conf::line_20::foo will still be accessible from other perl code, after the <Perl> section was parsed.

PerlSections Dumping

Apache2::PerlSections->dump

This method will dump out all the configuration variables mod_perl will be feeding to the apache config gears. The output is suitable to read back in via eval.

  my $dump = Apache2::PerlSections->dump;
ret: $dump ( string / undef )

A string dump of all the Perl code encountered in <Perl> blocks, suitable to be read back via eval

For example:

  <Perl>

  $Apache2::PerlSections::Save = 1;

  $Listen = 8529;

  $Location{"/perl"} = {
     SetHandler => "perl-script",
     PerlHandler => "ModPerl::Registry",
     Options => "ExecCGI",
  };

  @DirectoryIndex = qw(index.htm index.html);

  $VirtualHost{"www.foo.com"} = {
     DocumentRoot => "/tmp/docs",
     ErrorLog => "/dev/null",
     Location => {
       "/" => {
         Allowoverride => 'All',
         Order => 'deny,allow',
         Deny  => 'from all',
         Allow => 'from foo.com',
       },
     },
  };
  </Perl>

  <Perl>
  print Apache2::PerlSections->dump;
  </Perl>

This will print something like this:

  $Listen = 8529;

  @DirectoryIndex = (
    'index.htm',
    'index.html'
  );

  $Location{'/perl'} = (
      PerlHandler => 'Apache2::Registry',
      SetHandler => 'perl-script',
      Options => 'ExecCGI'
  );

  $VirtualHost{'www.foo.com'} = (
      Location => {
        '/' => {
          Deny => 'from all',
          Order => 'deny,allow',
          Allow => 'from foo.com',
          Allowoverride => 'All'
        }
      },
      DocumentRoot => '/tmp/docs',
      ErrorLog => '/dev/null'
  );

  1;
  __END__

It is important to put the call to dump in it's own <Perl> section, otherwise the content of the current <Perl> section will not be dumped.

Apache2::PerlSections->store

This method will call the dump method, writing the output to a file, suitable to be pulled in via require or do.

  Apache2::PerlSections->store($filename);
arg1: $filename (string)

The filename to save the dump output to

ret: no return value

Advanced API

mod_perl 2.0 now introduces the same general concept of handlers to <Perl> sections. Apache2::PerlSections simply being the default handler for them.

To specify a different handler for a given perl section, an extra handler argument must be given to the section:

  <Perl handler="My::PerlSection::Handler" somearg="test1">
    $foo = 1;
    $bar = 2;
  </Perl>

And in My/PerlSection/Handler.pm:

  sub My::Handler::handler : handler {
      my ($self, $parms, $args) = @_;
      #do your thing!
  }

So, when that given <Perl> block in encountered, the code within will first be evaluated, then the handler routine will be invoked with 3 arguments:

arg1: $self

self-explanatory

arg2: $parms ( Apache2::CmdParms|docs::2.0::api::Apache2::CmdParms )

$parms is specific for the current Container, for example, you might want to call $parms->server() to get the current server.

arg3: $args ( APR::Table object|docs::2.0::api::APR::Table)

the table object of the section arguments. The 2 guaranteed ones will be:

  $args->{'handler'} = 'My::PerlSection::Handler';
  $args->{'package'} = 'Apache2::ReadConfig';

Other name="value" pairs given on the <Perl> line will also be included.

At this point, it's up to the handler routing to inspect the namespace of the $args->{'package'} and chooses what to do.

The most likely thing to do is to feed configuration data back into apache. To do that, use Apache2::Server->add_config("directive"), for example:

  $parms->server->add_config("Alias /foo /bar");

Would create a new alias. The source code of Apache2::PerlSections is a good place to look for a practical example.

Verifying <Perl> Sections

If the <Perl> sections include no code requiring a running mod_perl, it is possible to check those from the command line. But the following trick should be used:

  # file: httpd.conf
  <Perl>
  #!perl

  # ... code here ...

  __END__
  </Perl>

Now you can run:

  % perl -c httpd.conf

Bugs

<Perl> directive missing closing '>'

httpd-2.0.47 had a bug in the configuration parser which caused the startup failure with the following error:

  Starting httpd:
  Syntax error on line ... of /etc/httpd/conf/httpd.conf:
  <Perl> directive missing closing '>'     [FAILED]

This has been fixed in httpd-2.0.48. If you can't upgrade to this or a higher version, please add a space before the closing '>' of the opening tag as a workaround. So if you had:

  <Perl>
  # some code
  </Perl>

change it to be:

  <Perl >
  # some code
  </Perl>

<Perl>[...]> was not closed.

On encountering a one-line <Perl> block, httpd's configuration parser will cause a startup failure with an error similar to this one:

  Starting httpd:
  Syntax error on line ... of /etc/httpd/conf/httpd.conf:
  <Perl>use> was not closed.

If you have written a simple one-line <Perl> section like this one :

  <Perl>use Apache::DBI;</Perl>

change it to be:

   <Perl>
   use Apache::DBI;
   </Perl>

This is caused by a limitation of httpd's configuration parser and is not likely to be changed to allow one-line block like the example above. Use multi-line blocks instead.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Process - Perl API for Apache process record

  • Synopsis
  • Description
  • API
    • pconf
    • pool
    • short_name
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Process - Perl API for Apache process record

Synopsis

  use Apache2::Process ();
  use Apache2::ServerRec ();
  my $proc = $s->process;

  # global pool cleared on exit
  my $global_pool = $proc->pool;

  # configuration pool cleared on restart
  my $pconf = $proc->pconf;

  # short program name (e.g. httpd)
  my $proc_name = $proc->short_name;

Description

Apache2::Process provides the API for the Apache process object, which you can retrieve with $s->process|docs::2.0::api::Apache2::ServerRec/C_process_:

  use Apache2::ServerRec ();
  $proc = $s->process;

API

Apache2::Process provides the following functions and/or methods:

pconf

Get configuration pool object.

  $p = $proc->pconf();
obj: $proc ( Apache2::Process object|docs::2.0::api::Apache2::Process )
ret: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

This pool object gets cleared on server restart.

pool

Get the global pool object.

  $p = $proc->pool();
obj: $proc ( Apache2::Process object|docs::2.0::api::Apache2::Process )
ret: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

This pool object gets cleared only on (normal) server exit

short_name

The name of the program used to execute the program

  $short_name = $proc->short_name();
obj: $proc ( Apache2::Process object|docs::2.0::api::Apache2::Process )
ret: $short_name (string)

e.g. httpd

since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Reload - Reload Perl Modules when Changed on Disk

  • Synopsis
  • Description
    • Monitor All Modules in %INC
    • Register Modules Implicitly
    • Register Modules Explicitly
    • Monitor Only Certain Sub Directories
    • Special "Touch" File
    • Unregistering a module
  • Performance Issues
  • Debug
  • Caveats
    • Problems With Reloading Modules Which Do Not Declare Their Package Name
    • Failing to Find a File to Reload
    • Problems with Scripts Running with Registry Handlers that Cache the Code
      • The Problem
      • The Explanation
      • The Solution
  • Threaded MPM and Multiple Perl Interpreters
  • Pseudo-hashes
  • Copyright
  • Authors

NAME

Apache2::Reload - Reload Perl Modules when Changed on Disk

Synopsis

  # Monitor and reload all modules in %INC:
  # httpd.conf:
  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  # when working with protocols and connection filters
  # PerlPreConnectionHandler Apache2::Reload

  # Reload groups of modules:
  # httpd.conf:
  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  PerlSetVar ReloadAll Off
  PerlSetVar ReloadModules "ModPerl::* Apache2::*"
  #PerlSetVar ReloadDebug On

  # Reload a single module from within itself:
  package My::Apache2::Module;
  use Apache2::Reload;
  sub handler { ... }
  1;

Description

Apache2::Reload reloads modules that change on the disk.

When Perl pulls a file via require, it stores the filename in the global hash %INC. The next time Perl tries to require the same file, it sees the file in %INC and does not reload from disk. This module's handler can be configured to iterate over the modules in %INC and reload those that have changed on disk or only specific modules that have registered themselves with Apache2::Reload. It can also do the check for modified modules, when a special touch-file has been modified.

Note that Apache2::Reload operates on the current context of @INC. Which means, when called as a Perl*Handler it will not see @INC paths added or removed by ModPerl::Registry scripts, as the value of @INC is saved on server startup and restored to that value after each request. In other words, if you want Apache2::Reload to work with modules that live in custom @INC paths, you should modify @INC when the server is started. Besides, 'use lib' in the startup script, you can also set the PERL5LIB variable in the httpd's environment to include any non-standard 'lib' directories that you choose. For example, to accomplish that you can include a line:

  PERL5LIB=/home/httpd/perl/extra; export PERL5LIB

in the script that starts Apache. Alternatively, you can set this environment variable in httpd.conf:

  PerlSetEnv PERL5LIB /home/httpd/perl/extra

Monitor All Modules in %INC

To monitor and reload all modules in %INC at the beginning of request's processing, simply add the following configuration to your httpd.conf:

  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload

When working with connection filters and protocol modules Apache2::Reload should be invoked in the pre_connection stage:

  PerlPreConnectionHandler Apache2::Reload

See also the discussion on PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler.

Register Modules Implicitly

To only reload modules that have registered with Apache2::Reload, add the following to the httpd.conf:

  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  PerlSetVar ReloadAll Off
  # ReloadAll defaults to On

Then any modules with the line:

  use Apache2::Reload;

Will be reloaded when they change.

Register Modules Explicitly

You can also register modules explicitly in your httpd.conf file that you want to be reloaded on change:

  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  PerlSetVar ReloadAll Off
  PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"

Note that these are split on whitespace, but the module list must be in quotes, otherwise Apache tries to parse the parameter list.

The * wild character can be used to register groups of files under the same namespace. For example the setting:

  PerlSetVar ReloadModules "ModPerl::* Apache2::*"

will monitor all modules under the namespaces ModPerl:: and Apache2::.

Monitor Only Certain Sub Directories

To reload modules only in certain directories (and their subdirectories) add the following to the httpd.conf:

  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"

You can further narrow the list of modules to be reloaded from the chosen directories with ReloadModules as in:

  PerlModule Apache2::Reload
  PerlInitHandler Apache2::Reload
  PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
  PerlSetVar ReloadAll Off
  PerlSetVar ReloadModules "MyApache2::*"

In this configuration example only modules from the namespace MyApache2:: found in the directories /tmp/project1/ and /tmp/project2/ (and their subdirectories) will be reloaded.

Special "Touch" File

You can also declare a file, which when gets touch(1)ed, causes the reloads to be performed. For example if you set:

  PerlSetVar ReloadTouchFile /tmp/reload_modules

and don't touch(1) the file /tmp/reload_modules, the reloads won't happen until you go to the command line and type:

  % touch /tmp/reload_modules

When you do that, the modules that have been changed, will be magically reloaded on the next request. This option works with any mode described before.

Unregistering a module

In some cases, it might be necessary to explicitely stop reloading a module.

  Apache2::Reload->unregister_module('Some::Module');

But be carefull, since unregistering a module in this way will only do so for the current interpreter. This feature should be used with care.

Performance Issues

This module is perfectly suited for a development environment. Though it's possible that you would like to use it in a production environment, since with Apache2::Reload you don't have to restart the server in order to reload changed modules during software updates. Though this convenience comes at a price:

  • If the "touch" file feature is used, Apache2::Reload has to stat(2) the touch file on each request, which adds a slight but most likely insignificant overhead to response times. Otherwise Apache2::Reload will stat(2) each registered module or even worse--all modules in %INC, which will significantly slow everything down.

  • Once the child process reloads the modules, the memory used by these modules is not shared with the parent process anymore. Therefore the memory consumption may grow significantly.

Therefore doing a full server stop and restart is probably a better solution.

Debug

If you aren't sure whether the modules that are supposed to be reloaded, are actually getting reloaded, turn the debug mode on:

  PerlSetVar ReloadDebug On

Caveats

Problems With Reloading Modules Which Do Not Declare Their Package Name

If you modify modules, which don't declare their package, and rely on Apache2::Reload to reload them, you may encounter problems: i.e., it'll appear as if the module wasn't reloaded when in fact it was. This happens because when Apache2::Reload require()s such a module all the global symbols end up in the Apache2::Reload namespace! So the module does get reloaded and you see the compile time errors if there are any, but the symbols don't get imported to the right namespace. Therefore the old version of the code is running.

Failing to Find a File to Reload

Apache2::Reload uses %INC to find the files on the filesystem. If an entry for a certain filepath in %INC is relative, Apache2::Reload will use @INC to try to resolve that relative path. Now remember that mod_perl freezes the value of @INC at the server startup, and you can modify it only for the duration of one request when you need to load some module which is not in on of the @INC directories. So a module gets loaded, and registered in %INC with a relative path. Now when Apache2::Reload tries to find that module to check whether it has been modified, it can't find since its directory is not in @INC. So Apache2::Reload will silently skip that module.

You can enable the Debug|/Debug mode to see what Apache2::Reload does behind the scenes.

Problems with Scripts Running with Registry Handlers that Cache the Code

The following problem is relevant only to registry handlers that cache the compiled script. For example it concerns ModPerl::Registry|docs::2.0::api::ModPerl::Registry but not ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun.

The Problem

Let's say that there is a module My::Utils:

  #file:My/Utils.pm
  #----------------
  package My::Utils;
  BEGIN { warn __PACKAGE__ , " was reloaded\n" }
  use base qw(Exporter);
  @EXPORT = qw(colour);
  sub colour { "white" }
  1;

And a registry script test.pl:

  #file:test.pl
  #------------
  use My::Utils;
  print "Content-type: text/plain\n\n";
  print "the color is " . colour();

Assuming that the server is running in a single mode, we request the script for the first time and we get the response:

  the color is white

Now we change My/Utils.pm:

  -  sub colour { "white" }
  +  sub colour { "red" }

And issue the request again. Apache2::Reload does its job and we can see that My::Utils was reloaded (look in the error_log file). However the script still returns:

  the color is white

The Explanation

Even though My/Utils.pm was reloaded, ModPerl::Registry's cached code won't run 'use My::Utils;' again (since it happens only once, i.e. during the compile time). Therefore the script doesn't know that the subroutine reference has been changed.

This is easy to verify. Let's change the script to be:

  #file:test.pl
  #------------
  use My::Utils;
  print "Content-type: text/plain\n\n";
  my $sub_int = \&colour;
  my $sub_ext = \&My::Utils::colour;
  print "int $sub_int\n";
  print "ext $sub_ext\n";

Issue a request, you will see something similar to:

  int CODE(0x8510af8)
  ext CODE(0x8510af8)

As you can see both point to the same CODE reference (meaning that it's the same symbol). After modifying My/Utils.pm again:

  -  sub colour { "red" }
  +  sub colour { "blue" }

and calling the script on the secondnd time, we get:

  int CODE(0x8510af8)
  ext CODE(0x851112c)

You can see that the internal CODE reference is not the same as the external one.

The Solution

There are two solutions to this problem:

Solution 1: replace use() with an explicit require() + import().

 - use My::Utils;
 + require My::Utils; My::Utils->import();

now the changed functions will be reimported on every request.

Solution 2: remember to touch the script itself every time you change the module that it requires.

Threaded MPM and Multiple Perl Interpreters

If you use Apache2::Reload with a threaded MPM and multiple Perl interpreters, the modules will be reloaded by each interpreter as they are used, not every interpreters at once. Similar to mod_perl 1.0 where each child has its own Perl interpreter, the modules are reloaded as each child is hit with a request.

If a module is loaded at startup, the syntax tree of each subroutine is shared between interpreters (big win), but each subroutine has its own padlist (where lexical my variables are stored). Once Apache2::Reload reloads a module, this sharing goes away and each Perl interpreter will have its own copy of the syntax tree for the reloaded subroutines.

Pseudo-hashes

The short summary of this is: Don't use pseudo-hashes. They are deprecated since Perl 5.8 and are removed in 5.9.

Use an array with constant indexes. Its faster in the general case, its more guaranteed, and generally, it works.

The long summary is that some work has been done to get this module working with modules that use pseudo-hashes, but it's still broken in the case of a single module that contains multiple packages that all use pseudo-hashes.

So don't do that.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

Matt Sergeant, matt@sergeant.org

Stas Bekman (porting to mod_perl 2.0)

A few concepts borrowed from Stonehenge::Reload by Randal Schwartz and Apache::StatINC (mod_perl 1.x) by Doug MacEachern and Ask Bjoern Hansen.


Apache2::RequestIO - Perl API for Apache request record IO

  • Synopsis
  • Description
  • API
    • discard_request_body
    • print
    • printf
    • puts
    • read
    • rflush
    • sendfile
    • write
  • TIE Interface
    • BINMODE
    • CLOSE
    • FILENO
    • GETC
    • OPEN
    • PRINT
    • PRINTF
    • READ
    • TIEHANDLE
    • UNTIE
    • WRITE
  • Deprecated API
    • get_client_block
    • setup_client_block
    • should_client_block
  • See Also
  • Copyright
  • Authors

NAME

Apache2::RequestIO - Perl API for Apache request record IO

Synopsis

  use Apache2::RequestIO ();

  $rc = $r->discard_request_body();

  $r->print("foo", "bar");
  $r->puts("foo", "bar"); # same as print, but no flushing
  $r->printf("%s $d", "foo", 5);

  $r->read($buffer, $len);

  $r->rflush();

  $r->sendfile($filename);

  $r->write("foobartarcar", 3, 5);

Description

Apache2::RequestIO provides the API to perform IO on the Apache request object.

API

Apache2::RequestIO provides the following functions and/or methods:

discard_request_body

In HTTP/1.1, any method can have a body. However, most GET handlers wouldn't know what to do with a request body if they received one. This helper routine tests for and reads any message body in the request, simply discarding whatever it receives. We need to do this because failing to read the request body would cause it to be interpreted as the next request on a persistent connection.

  $rc = $r->discard_request_body();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $rc ( integer )

APR::Const status constant|docs::2.0::api::APR::Const if request is malformed, Apache2::Const::OK otherwise.

since: 2.0.00

Since we return an error status if the request is malformed, this routine should be called at the beginning of a no-body handler, e.g.,

   use Apache2::Const -compile => qw(OK);
   $rc = $r->discard_request_body;
   return $rc if $rc != Apache2::Const::OK;

print

Send data to the client.

  $cnt = $r->print(@msg);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: @msg ( ARRAY )

Data to send

ret: $cnt ( number )

How many bytes were sent (or buffered). If zero bytes were sent, print will return 0E0, or "zero but true," which will still evaluate to 0 in a numerical context.

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

The data is flushed only if STDOUT stream's $| is true. Otherwise it's buffered up to the size of the buffer, flushing only excessive data.

printf

Format and send data to the client (same as printf).

  $cnt = $r->printf($format, @args);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $format ( string )

Format string, as in the Perl core printf function.

arg2: @args ( ARRAY )

Arguments to be formatted, as in the Perl core printf function.

ret: $cnt ( number )

How many bytes were sent (or buffered)

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

The data is flushed only if STDOUT stream's $| is true. Otherwise it's buffered up to the size of the buffer, flushing only excessive data.

puts

Send data to the client

  $cnt = $r->puts(@msg);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: @msg ( ARRAY )

Data to send

ret: $cnt ( number )

How many bytes were sent (or buffered)

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

puts() is similar to print()|/C_print_, but it won't attempt to flush data, no matter what the value of STDOUT stream's $| is. Therefore assuming that STDOUT stream's $| is true, this method should be a tiny bit faster than print()|/C_print_, especially if small strings are printed.

read

Read data from the client.

  $cnt = $r->read($buffer, $len);
  $cnt = $r->read($buffer, $len, $offset);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $buffer ( SCALAR )

The buffer to populate with the read data

arg2: $len ( number )

How many bytes to attempt to read

opt arg3: $offset ( number )

If a non-zero $offset is specified, the read data will be placed at that offset in the $buffer.

META: negative offset and \0 padding are not supported at the moment

ret: $cnt ( number )

How many characters were actually read

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

This method shares a lot of similarities with the Perl core read() function. The main difference in the error handling, which is done via APR::Error exceptions|docs::2.0::api::APR::Error

rflush

Flush any buffered data to the client.

  $r->rflush();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: no return value
since: 2.0.00

Unless STDOUT stream's $| is false, data sent via $r->print()|/C_print_ is buffered. This method flushes that data to the client.

sendfile

Send a file or a part of it

  $rc = $r->sendfile($filename);
  $rc = $r->sendfile($filename, $offset);
  $rc = $r->sendfile($filename, $offset, $len);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $filename ( string )

The full path to the file (using / on all systems)

opt arg2: $offset ( integer )

Offset into the file to start sending.

No offset is used if $offset is not specified.

opt arg3: $len ( integer )

How many bytes to send.

If not specified the whole file is sent (or a part of it, if $offset if specified)

ret: $rc ( APR::Const status constant|docs::2.0::api::APR::Const )

On success, APR::Const::SUCCESS|docs::2.0::api::APR::Const/C_APR__Const__SUCCESS_ is returned.

In case of a failure -- a failure code is returned, in which case normally it should be returned to the caller.

excpt: APR::Error|docs::2.0::api::APR::Error

Exceptions are thrown only when this function is called in the VOID context. So if you don't want to handle the errors, just don't ask for a return value and the function will handle all the errors on its own.

since: 2.0.00

write

Send partial string to the client

  $cnt = $r->write($buffer);
  $cnt = $r->write($buffer, $len);
  $cnt = $r->write($buffer, $len, $offset);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $buffer ( SCALAR )

The string with data

opt arg2: $len ( SCALAR )

How many bytes to send. If not specified, or -1 is specified, all the data in $buffer (or starting from $offset) will be sent.

opt arg3: $offset ( number )

Offset into the $buffer string.

ret: $cnt ( number )

How many bytes were sent (or buffered)

excpt: APR::Error|docs::2.0::api::APR::Error
since: 2.0.00

Examples:

Assuming that we have a string:

  $string = "123456789";

Then:

  $r->write($string);

sends:

  123456789

Whereas:

  $r->write($string, 3);

sends:

  123

And:

  $r->write($string, 3, 5);

sends:

  678

Finally:

  $r->write($string, -1, 5);

sends:

  6789

TIE Interface

The TIE interface implementation. This interface is used for HTTP request handlers, when running under SetHandler perl-script|docs::2.0::user::config::config/C_perl_script_ and Perl doesn't have perlio enabled.

See the perltie manpage for more information.

BINMODE

since: 2.0.00

NoOP

See the binmode Perl entry in the perlfunc manpage

CLOSE

since: 2.0.00

NoOP

See the close Perl entry in the perlfunc manpage

FILENO

since: 2.0.00

See the fileno Perl entry in the perlfunc manpage

GETC

since: 2.0.00

See the getc Perl entry in the perlfunc manpage

OPEN

since: 2.0.00

See the open Perl entry in the perlfunc manpage

PRINT

since: 2.0.00

See the print Perl entry in the perlfunc manpage

PRINTF

since: 2.0.00

See the printf Perl entry in the perlfunc manpage

READ

since: 2.0.00

See the read Perl entry in the perlfunc manpage

TIEHANDLE

since: 2.0.00

See the tie Perl entry in the perlfunc manpage

UNTIE

since: 2.0.00

NoOP

See the untie Perl entry in the perlfunc manpage

WRITE

since: 2.0.00

See the write Perl entry in the perlfunc manpage

Deprecated API

The following methods are deprecated, Apache plans to remove those in the future, therefore avoid using them.

get_client_block

This method is deprecated since the C implementation is buggy and we don't want you to use it at all. Instead use the plain $r->read()|/C_read_.

setup_client_block

This method is deprecated since $r->get_client_block|/C__get_client_block_ is deprecated.

should_client_block

This method is deprecated since $r->get_client_block|/C__get_client_block_ is deprecated.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::RequestRec - Perl API for Apache request record accessors

  • Synopsis
  • Description
  • API
    • allowed
    • ap_auth_type
    • args
    • assbackwards
    • bytes_sent
    • connection
    • content_encoding
    • content_languages
    • content_type
    • err_headers_out
    • filename
    • finfo
    • handler
    • header_only
    • headers_in
    • headers_out
    • hostname
    • input_filters
    • main
    • method
    • method_number
    • mtime
    • next
    • no_local_copy
    • notes
    • output_filters
    • path_info
    • per_dir_config
    • pool
    • prev
    • proto_input_filters
    • proto_num
    • proto_output_filters
    • protocol
    • proxyreq
    • request_time
    • server
    • status
    • status_line
    • subprocess_env
    • the_request
    • unparsed_uri
    • uri
    • user
  • Unsupported API
    • allowed_methods
    • allowed_xmethods
    • request_config
    • used_path_info
  • See Also
  • Copyright
  • Authors

NAME

Apache2::RequestRec - Perl API for Apache request record accessors

Synopsis

  use Apache2::RequestRec ();

  # set supported by the handler HTTP methods
  $allowed = $r->allowed();

  # auth type
  $auth_type = $r->ap_auth_type();

  # QUERY_STRING
  $args = $r->args();

  # non-parsed-headers handler
  $status = $r->assbackwards();

  # how many bytes were sent
  $bytes_sent = $r->bytes_sent();

  # client connection record
  $c = $r->connection();

  # "Content-Encoding" HTTP response header
  $r->content_encoding("gzip");

  # the languages of the content
  $languages = $r->content_languages();

  # "Content-Encoding" HTTP response header
  $r->content_type('text/plain');

  # special response headers table
  $err_headers_out = $r->err_headers_out();

  # request mapped filename
  $filename = $r->filename();

  # request finfo
  $finfo = $r->finfo();

  # 'SetHandler perl-script' equivalent
  $r->handler('perl-script');

  # was it a HEAD request?
  $status = $r->header_only();

  # request input headers table
  $headers_in = $r->headers_in();

  # request output headers table
  $headers_out = $r->headers_out();

  # hostname
  $hostname = $r->hostname();

  # input filters stack
  $input_filters = $r->input_filters();

  # get the main request obj in a sub-request
  $main_r = $r->main();

  # what's the current request (GET/POST/etc)?
  $method = $r->method();

  # what's the current method number?
  $methnum = $r->method_number();

  # current resource last modified time
  $mtime = $r->mtime();

  # next request object (in redirect)
  $next_r = $r->next();

  # there is no local copy
  $r->no_local_copy();

  # Apache ascii notes table
  $notes = $r->notes();

  # output filters stack
  $output_filters = $r->output_filters();

  # PATH_INFO
  $path_info = $r->path_info();

  # used in configuration directives modules
  $per_dir_config = $r->per_dir_config();

  # pool with life span of the current request
  $p = $r->pool();

  # previous request object in the internal redirect
  $prev_r = $r->prev();

  # connection level input filters stack
  $proto_input_filters = $r->proto_input_filters();

  # HTTP protocol version number
  $proto_num = $r->proto_num();

  # connection level output filters stack
  $proto_output_filters = $r->proto_output_filters();

  # the protocol, the client speaks: "HTTP/1.0", "HTTP/1.1", etc.
  $protocol = $r->protocol();

  # is it a proxy request
  $status = $r->proxyreq($val);

  # Time when the request started
  $request_time = $r->request_time();

  # server object
  $s = $r->server();

  # response status
  $status = $r->status();

  # response status line
  $status_line = $r->status_line();

  # manipulate %ENV of the subprocess
  $r->subprocess_env;
  $r->subprocess_env($key => $val);

  # first HTTP request header
  $request = $r->the_request();

  # the URI without any parsing performed
  $unparsed_uri = $r->unparsed_uri();

  # The path portion of the URI
  $uri = $r->uri();

  # auth username
  $user = $r->user();

Description

Apache2::RequestRec provides the Perl API for Apache request_rec object.

The following packages extend the Apache2::RequestRec functionality:
Apache2::Access|docs::2.0::api::Apache2::Access,
Apache2::Log|docs::2.0::api::Apache2::Log,
Apache2::RequestIO|docs::2.0::api::Apache2::RequestIO,
Apache2::RequestUtil|docs::2.0::api::Apache2::RequestUtil,
Apache2::Response|docs::2.0::api::Apache2::Response,
Apache2::SubRequest|docs::2.0::api::Apache2::SubRequest and
Apache2::URI|docs::2.0::api::Apache2::URI.

API

Apache2::RequestRec provides the following functions and/or methods:

allowed

Get/set the allowed methods bitmask.

  $allowed      = $r->allowed();
  $prev_allowed = $r->allowed($new_allowed);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_allowed ( bitmask )

Set the bitvector.

ret: $allowed ( bitmask )

returns $allowed, which is a bitvector of the allowed methods.

If the $new_allowed argument is passed, the value before the change is returned.

since: 2.0.00

A handler must ensure that the request method is one that it is capable of handling. Generally modules should Apache2::DECLINE any request methods they do not handle. Prior to aborting the handler like this the handler should set $r->allowed to the list of methods that it is willing to handle. This bitvector is used to construct the "Allow:" header required for OPTIONS requests, and Apache2::Const::HTTP_METHOD_NOT_ALLOWED (405) and Apache2::Const::HTTP_NOT_IMPLEMENTED (501) status codes.

Since the default Apache handler deals with the OPTIONS method, all response handlers can usually decline to deal with OPTIONS. For example if the response handler handles only GET and POST methods, and not OPTIONS, it may want to say:

   use Apache2::Const -compile => qw(OK DECLINED M_GET M_POST M_OPTIONS);
   if ($r->method_number == Apache2::Const::M_OPTIONS) {
       $r->allowed($r->allowed | (1<<Apache2::Const::M_GET) | (1<<Apache2::Const::M_POST));
       return Apache2::Const::DECLINED;
   }

TRACE is always allowed, modules don't need to set it explicitly.

Since the default_handler will always handle a GET, a module which does *not* implement GET should probably return Apache2::Const::HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a script GET handler can't be installed by mod_actions.

For example, if the module can handle only POST method it could start with:

   use Apache2::Const -compile => qw(M_POST HTTP_METHOD_NOT_ALLOWED);
   unless ($r->method_number == Apache2::Const::M_POST) {
       $r->allowed($r->allowed | (1<<Apache2::Const::M_POST));
       return Apache2::Const::HTTP_METHOD_NOT_ALLOWED;
   }

ap_auth_type

If an authentication check was made, get or set the ap_auth_type slot in the request record

  $auth_type = $r->ap_auth_type();
  $r->ap_auth_type($newval);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $newval (string)

If this argument is passed then a new auth type is assigned. For example:

  $r->auth_type('Basic');
ret: $auth_type (string)

If $newval is passed, nothing is returned. Otherwise the current auth type is returned.

since: 2.0.00

ap_auth_type holds the authentication type that has been negotiated between the client and server during the actual request. Generally, ap_auth_type is populated automatically when you call $r->get_basic_auth_pw so you don't really need to worry too much about it, but if you want to roll your own authentication mechanism then you will have to populate ap_auth_type yourself.

Note that $r->ap_auth_type was $r->connection->auth_type in the mod_perl 1.0 API.

args

Get/set the request QUERY string

  $args      = $r->args();
  $prev_args = $r->args($new_args);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_args ( string )

Optinally set the new QUERY string

ret: $args ( string )

The current QUERY string

If $new_args was passed, returns the value before the change.

since: 2.0.00

assbackwards

When set to a true value, Apache won't send any HTTP response headers allowing you to send any headers.

  $status      = $r->assbackwards();
  $prev_status = $r->assbackwards($newval);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $newval (integer)

assign a new state.

ret: $status (integer)

current state.

since: 2.0.00

If you send your own set of headers, which includes the Keep-Alive HTTP response header, you must make sure to increment the number of requests served over this connection (which is normally done by the core connection output filter ap_http_header_filter, but skipped when assbackwards is enabled).

  $r->connection->keepalives($r->connection->keepalives + 1);

otherwise code relying on the value of $r->connection->keepalives|docs::2.0::api::Apache2::Connection/C_keepalives_ may malfunction. For example, this counter is used to tell when a new request is coming in over the same connection to a filter that wants to parse only HTTP headers (like Apache2::Filter::HTTPHeadersFixup). Of course you will need to set $r->connection->keepalive(1)|docs::2.0::api::Apache2::Connection/C_keepalive_ ) as well.

bytes_sent

The number of bytes sent to the client, handy for logging, etc.

  $bytes_sent = $r->bytes_sent();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $bytes_sent (integer)
since: 2.0.00

Though as of this writing in Apache 2.0 it doesn't really do what it did in Apache 1.3. It's just set to the size of the response body. The issue is that buckets from one request may get buffered and not sent during the lifetime of the request, so it's not easy to give a truly accurate count of "bytes sent to the network for this response".

connection

Get the client connection record

  $c = $r->connection();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $c ( Apache2::Connection object|docs::2.0::api::Apache2::Connection )
since: 2.0.00

content_encoding

Get/set content encoding (the "Content-Encoding" HTTP header). Content encodings are string like "gzip" or "compress".

  $ce      = $r->content_encoding();
  $prev_ce = $r->content_encoding($new_ce);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_ce ( string )

If passed, sets the content encoding to a new value. It must be a lowercased string.

ret: $ce ( string )

The current content encoding.

If $new_ce is passed, then the previous value is returned.

since: 2.0.00

For example, here is how to send a gzip'ed response:

  require Compress::Zlib;
  $r->content_type("text/plain");
  $r->content_encoding("gzip");
  $r->print(Compress::Zlib::memGzip("some text to be gzipped));

content_languages

Get/set content languages (the "Content-Language" HTTP header). Content languages are string like "en" or "fr".

  $languages = $r->content_languages();
  $prev_lang = $r->content_languages($nev_lang);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_lang ( ARRAY ref )

If passed, sets the content languages to new values. It must be an ARRAY reference of language names, like "en" or "fr"

ret: $languages ( ARRAY ref )

The current list of content languages, as an ARRAY reference.

If $new_lang is passed, then the previous value is returned.

since: 2.0.00

content_type

Get/set the HTTP response Content-type header value.

  my $content_type      = $r->content_type();
  my $prev_content_type = $r->content_type($new_content_type);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_content_type (MIME type string)

Assign a new HTTP response content-type. It will affect the response only if HTTP headers weren't sent yet.

ret: $content_type

The current content-type value.

If $new_content_type was passed, the previous value is returned instead.

since: 2.0.00

For example, set the Content-type header to text/plain.

  $r->content_type('text/plain');

If you set this header via the headers_out|docs::2.0::api::Apache2::RequestRec/C_headers_out_ table directly, it will be ignored by Apache. So do not do that.

err_headers_out

Get/set MIME response headers, printed even on errors and persist across internal redirects.

  $err_headers_out = $r->err_headers_out();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $err_headers_out ( APR::Table object|docs::2.0::api::APR::Table )
since: 2.0.00

The difference between headers_out|/C_headers_out_ and err_headers_out, is that the latter are printed even on error, and persist across internal redirects (so the headers printed for ErrorDocument handlers will have them).

For example, if a handler wants to return a 404 response, but nevertheless to set a cookie, it has to be:

  $r->err_headers_out->add('Set-Cookie' => $cookie);
  return Apache2::Const::NOT_FOUND;

If the handler does:

  $r->headers_out->add('Set-Cookie' => $cookie);
  return Apache2::Const::NOT_FOUND;

the Set-Cookie header won't be sent.

filename

Get/set the filename on disk corresponding to this response (the result of the URI --> filename translation).

  $filename      = $r->filename();
  $prev_filename = $r->filename($new_filename);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_filename ( string )

new value

ret: $filename ( string )

the current filename, or the previous value if the optional $new_filename argument was passed

since: 2.0.00

Note that if you change the filename after the PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler phase was run and expect Apache to serve it, you need to update its stat record, like so:

  use Apache2::RequestRec ();
  use APR::Finfo ();
  use APR::Const -compile => qw(FINFO_NORM);
  $r->filename($newfile);
  $r->finfo(APR::Finfo::stat($newfile, APR::Const::FINFO_NORM, $r->pool));

if you don't, Apache will still try to use the previously cached information about the previously set value of the filename.

finfo

Get and set the finfo request record member:

  $finfo = $r->finfo();
  $r->finfo($finfo);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )
ret: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )

Always returns the current object.

Due to the internal Apache implementation it's not possible to have two different objects originating from $r->finfo at the same time. Whenever $r->finfo is updated all objects will be updated too to the latest value.

since: 2.0.00

Most of the time, this method is used to get the finfo member. The only reason you may want to set it is you need to use it before the Apache's default map_to_storage phase is called.

Examples:

  • What Apache thinks is the current request filename (post the PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler phase):

      use Apache2::RequestRec ();
  use APR::Finfo ();
  print $r->finfo->fname;

  • Populate the finfo member (normally, before the PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler phase):

      use APR::Finfo ();
  use APR::Const -compile => qw(FINFO_NORM);

  my $finfo = APR::Finfo::stat(__FILE__, APR::Const::FINFO_NORM, $r->pool);
  $r->finfo($finfo);

handler

Get/set the equivalent of the SetHandler directive.

  $handler      = $r->handler();
  $prev_handler = $r->handler($new_handler);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_handler ( string )

the new handler.

ret: $handler ( string )

the current handler.

If $new_handler is passed, the previous value is returned.

since: 2.0.00

header_only

Did the client has asked for headers only? e.g. if the request method was HEAD.

  $status = $r->header_only();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $status ( boolean )

Returns true if the client is asking for headers only, false otherwise

since: 2.0.00

headers_in

Get/set the request MIME headers:

  $headers_in = $r->headers_in();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $headers_in ( APR::Table object|docs::2.0::api::APR::Table )
since: 2.0.00

This table is available starting from the PerlHeaderParserHandler|docs::2.0::user::handlers::http/PerlHeaderParserHandler phase.

For example you can use it to retrieve the cookie value sent by the client, in the Cookie: header:

    my $cookie = $r->headers_in->{Cookie} || '';

headers_out

Get/set MIME response headers, printed only on 2xx responses.

  $headers_out = $r->headers_out();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $headers_out ( APR::Table object|docs::2.0::api::APR::Table )
since: 2.0.00

See also err_headers_out|/C_err_headers_out_, which allows to set headers for non-2xx responses and persist across internal redirects.

hostname

Host, as set by full URI or Host:

  $hostname = $r->hostname();
  $prev_hostname = $r->hostname($new_hostname);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_hostname ( string )

new value

ret: $hostname ( string )

the current hostname, or the previous value if the optional $new_hostname argument was passed

since: 2.0.00

input_filters

Get/set the first filter in a linked list of request level input filters:

  $input_filters      = $r->input_filters();
  $prev_input_filters = $r->input_filters($new_input_filters);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_input_filters

Set a new value

ret: $input_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the request level input filters chain.

If $new_input_filters was passed, returns the previous value.

since: 2.0.00

For example instead of using $r->read()|docs::2.0::api::Apache2::RequestIO/C_read_ to read the POST data, one could use an explicit walk through incoming bucket brigades to get that data. The following function read_post() does just that (in fact that's what $r->read()|docs::2.0::api::Apache2::RequestIO/C_read_ does behind the scenes):

  use APR::Brigade ();
  use APR::Bucket ();
  use Apache2::Filter ();

  use Apache2::Const -compile => qw(MODE_READBYTES);
  use APR::Const    -compile => qw(SUCCESS BLOCK_READ);

  use constant IOBUFSIZE => 8192;

  sub read_post {
      my $r = shift;

      my $bb = APR::Brigade->new($r->pool,
                                 $r->connection->bucket_alloc);

      my $data = '';
      my $seen_eos = 0;
      do {
          $r->input_filters->get_brigade($bb, Apache2::Const::MODE_READBYTES,
                                         APR::Const::BLOCK_READ, IOBUFSIZE);

          for (my $b = $bb->first; $b; $b = $bb->next($b)) {
              if ($b->is_eos) {
                  $seen_eos++;
                  last;
              }

              if ($b->read(my $buf)) {
                  $data .= $buf;
              }

              $b->remove; # optimization to reuse memory
          }

      } while (!$seen_eos);

      $bb->destroy;

      return $data;
  }

As you can see $r->input_filters gives us a pointer to the last of the top of the incoming filters stack.

main

Get the main request record

  $main_r = $r->main();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $main_r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

If the current request is a sub-request, this method returns a blessed reference to the main request structure. If the current request is the main request, then this method returns undef.

To figure out whether you are inside a main request or a sub-request/internal redirect, use $r->is_initial_req|docs::2.0::api::Apache2::RequestUtil/C_is_initial_req_.

since: 2.0.00

method

Get/set the current request method (e.g. GET, HEAD, POST, etc.):

  $method     = $r->method();
  $pre_method = $r->method($new_method);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_method ( string )

a new value

ret: $method ( string )

The current method as a string

if $new_method was passed the previous value is returned.

since: 2.0.00

method_number

Get/set the HTTP method, issued by the client (Apache2::Const::M_GET, Apache2::Const::M_POST, etc.)

  $methnum      = $r->method_number();
  $prev_methnum = $r->method_number($new_methnum);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_methnum ( Apache2::Const :methods constant|docs::2.0::api::Apache2::Const/C__methods_ )

a new value

ret: $methnum ( Apache2::Const :methods constant|docs::2.0::api::Apache2::Const/C__methods_ )

The current method as a number

if $new_methnum was passed the previous value is returned.

since: 2.0.00

See the $r->allowed|/C_allowed_ entry for examples.

mtime

Last modified time of the requested resource

  $mtime      = $r->mtime();
  $prev_mtime = $r->mtime($new_mtime);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_mtime (epoch seconds).

a new value

ret: $mtime (epoch seconds).

the current value

if $new_mtime was passed the previous value is returned.

since: 2.0.00

next

Pointer to the redirected request if this is an external redirect

  $next_r = $r->next();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $next_r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

returns a blessed reference to the next (internal) request structure or undef if there is no next request.

since: 2.0.00

no_local_copy

There is no local copy of this response

  $status = $r->no_local_copy();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $status (integer)
since: 2.0.00

Used internally in certain sub-requests to prevent sending Apache2::Const::HTTP_NOT_MODIFIED for a fragment or error documents. For example see the implementation in modules/filters/mod_include.c.

Also used internally in $r->meets_conditions|docs::2.0::api::Apache2::Response/C_meets_conditions_ -- if set to a true value, the conditions are always met.

notes

Get/set text notes for the duration of this request. These notes can be passed from one module to another (not only mod_perl, but modules in any other language):

  $notes      = $r->notes();
  $prev_notes = $r->notes($new_notes);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_notes ( APR::Table object|docs::2.0::api::APR::Table )
ret: $notes ( APR::Table object|docs::2.0::api::APR::Table )

the current notes table.

if the $new_notes argument was passed, returns the previous value.

since: 2.0.00

If you want to pass Perl structures, you can use $r->pnotes|docs::2.0::api::Apache2::RequestUtil/C_pnotes_.

Also see $c->notes|docs::2.0::api::Apache2::Connection/C_notes_

output_filters

Get the first filter in a linked list of request level output filters:

  $output_filters      = $r->output_filters();
  $prev_output_filters = $r->output_filters($new_output_filters);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_output_filters

Set a new value

ret: $output_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the request level output filters chain.

If $new_output_filters was passed, returns the previous value.

since: 2.0.00

For example instead of using $r->print()|docs::2.0::api::Apache2::RequestIO/C_print_ to send the response body, one could send the data directly to the first output filter. The following function send_response_body() does just that:

  use APR::Brigade ();
  use APR::Bucket ();
  use Apache2::Filter ();

  sub send_response_body {
      my ($r, $data) = @_;

      my $bb = APR::Brigade->new($r->pool,
                                 $r->connection->bucket_alloc);

      my $b = APR::Bucket->new($bb->bucket_alloc, $data);
      $bb->insert_tail($b);
      $r->output_filters->fflush($bb);
      $bb->destroy;
  }

In fact that's what $r->read()|docs::2.0::api::Apache2::RequestIO/C_read_ does behind the scenes. But it also knows to parse HTTP headers passed together with the data and it also implements buffering, which the above function does not.

path_info

Get/set the PATH_INFO, what is left in the path after the URI --> filename translation:

  $path_info      = $r->path_info();
  $prev_path_info = $r->path_info($path_info);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $path_info ( string )

Set a new value

ret: $path_info ( string )

Return the current value.

If the optional argument $path_info is passed, the previous value is returned.

since: 2.0.00

per_dir_config

Get the dir config vector:

  $per_dir_config = $r->per_dir_config();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $per_dir_config ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )
since: 2.0.00

For an indepth discussion, refer to the Apache Server Configuration Customization in Perl chapter.

pool

The pool associated with the request

  $p = $r->pool();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $p ( APR::Pool object|docs::2.0::api::APR::Pool )
since: 2.0.00

prev

Pointer to the previous request if this is an internal redirect

  $prev_r = $r->prev();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $prev_r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

a blessed reference to the previous (internal) request structure or undef if there is no previous request.

since: 2.0.00

proto_input_filters

Get the first filter in a linked list of protocol level input filters:

  $proto_input_filters      = $r->proto_input_filters();
  $prev_proto_input_filters = $r->proto_input_filters($new_proto_input_filters);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_proto_input_filters

Set a new value

ret: $proto_input_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the protocol level input filters chain.

If $new_proto_input_filters was passed, returns the previous value.

since: 2.0.00

$r->proto_input_filters points to the same filter as $r->connection->input_filters|docs::2.0::api::Apache2::Connection/C_input_filters_.

proto_num

Get current request's HTTP protocol version number

  $proto_num = $r->proto_num();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $proto_num (integer)

current request's HTTP protocol version number, e.g.: HTTP/1.0 == 1000, HTTP/1.1 = 1001

since: 2.0.00

proto_output_filters

Get the first filter in a linked list of protocol level output filters:

  $proto_output_filters      = $r->proto_output_filters();
  $prev_proto_output_filters = $r->proto_output_filters($new_proto_output_filters);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_proto_output_filters

Set a new value

ret: $proto_output_filters ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter in the protocol level output filters chain.

If $new_proto_output_filters was passed, returns the previous value.

since: 2.0.00

$r->proto_output_filters points to the same filter as $r->connection->output_filters|docs::2.0::api::Apache2::Connection/C_output_filters_.

protocol

Get a string identifying the protocol that the client speaks.

  $protocol = $r->protocol();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $protocl ( string )

Typical values are "HTTP/1.0" or "HTTP/1.1".

If the client didn't specify the protocol version, the default is "HTTP/0.9"

since: 2.0.00

proxyreq

Get/set the proxyrec request record member and optionally adjust other related fields.

  $status = $r->proxyreq($val);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $val ( integer )

0, 1 or none.

ret: $status ( integer )

If $val is 0 or 1, the proxyrec member will be set to that value and previous value will be returned.

If $val is not passed, and $r->proxyreq is not true, and the proxy request is matching the current vhost (scheme, hostname and port), the proxyrec member will be set to 1 and that value will be returned. In addition $r->uri is set to $r->unparsed_uri and $r->filename is set to "modperl-proxy:".$r->uri. If those conditions aren't true 0 is returned.

since: 2.0.00

For example to turn a normal request into a proxy request to be handled on the same server in the PerlTransHandler phase run:

  my $real_url = $r->unparsed_uri;
  $r->proxyreq(1);
  $r->uri($real_url);
  $r->filename("proxy:$real_url");
  $r->handler('proxy-server');

Also remember that if you want to turn a proxy request into a non-proxy request, it's not enough to call:

  $r->proxyreq(0);

You need to adjust $r->uri and $r->filename as well if you run that code in PerlPostReadRequestHandler phase, since if you don't -- mod_proxy's own post_read_request handler will override your settings (as it will run after the mod_perl handler).

request_time

Time when the request started

  $request_time = $r->request_time();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $request_time (epoch seconds).
since: 2.0.00

server

Get the Apache2::Server|docs::2.0::api::Apache2::ServerRec object for the server the request $r is running under.

  $s = $r->server();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.00

status

Get/set the reply status for the client request.

  $status      = $r->status();
  $prev_status = $r->status($new_status);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_status ( integer )

If $new_status is passed the new status is assigned.

Normally you would use some Apache2::Const constant|docs::2.0::api::Apache2::Const, e.g. Apache2::Const::REDIRECT.

ret: $newval ( integer )

The current value.

If $new_status is passed the old value is returned.

since: 2.0.00

Usually you will set this value indirectly by returning the status code as the handler's function result. However, there are rare instances when you want to trick Apache into thinking that the module returned an Apache2::Const::OK status code, but actually send the browser a non-OK status. This may come handy when implementing an HTTP proxy handler. The proxy handler needs to send to the client, whatever status code the proxied server has returned, while returning Apache2::Const::OK to Apache. e.g.:

  $r->status($some_code);
  return Apache2::Const::OK

See also $r->status_line|/C_status_line_, which. if set, overrides $r->status.

status_line

Get/set the response status line. The status line is a string like "200 Document follows" and it will take precedence over the value specified using the $r->status() described above.

  $status_line      = $r->status_line();
  $prev_status_line = $r->status_line($new_status_line);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_status_line ( string )
ret: $status_line ( string )
since: 2.0.00

When discussing $r->status|/C_status_ we have mentioned that sometimes a handler runs to a successful completion, but may need to return a different code, which is the case with the proxy server. Assuming that the proxy handler forwards to the client whatever response the proxied server has sent, it'll usually use status_line(), like so:

  $r->status_line($response->code() . ' ' . $response->message());
  return Apache2::Const::OK;

In this example $response could be for example an HTTP::Response object, if LWP::UserAgent was used to implement the proxy.

This method is also handy when you extend the HTTP protocol and add new response codes. For example you could invent a new error code and tell Apache to use that in the response like so:

  $r->status_line("499 We have been FooBared");
  return Apache2::Const::OK;

Here 499 is the new response code, and We have been FooBared is the custom response message.

subprocess_env

Get/set the Apache subprocess_env table, or optionally set the value of a named entry.

               $r->subprocess_env;
                 $env_table = $r->subprocess_env;

                        $r->subprocess_env($key => $val);
                 $val = $r->subprocess_env($key);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $key ( string )
opt arg2: $val ( string )
ret: ...
since: 2.0.00

When called in VOID context with no arguments, it populate %ENV with special variables (e.g. $ENV{QUERY_STRING}) like mod_cgi does.

When called in a non-VOID context with no arguments, it returns an APR::Table object|docs::2.0::api::APR::Table.

When the $key argument (string) is passed, it returns the corresponding value (if such exists, or undef. The following two lines are equivalent:

  $val = $r->subprocess_env($key);
  $val = $r->subprocess_env->get($key);

When the $key and the $val arguments (strings) are passed, the value is set. The following two lines are equivalent:

  $r->subprocess_env($key => $val);
  $r->subprocess_env->set($key => $val);

The subprocess_env table|docs::2.0::api::APR::Table is used by Apache2::SubProcess|docs::2.0::api::Apache2::SubProcess, to pass environment variables to externally spawned processes. It's also used by various Apache modules, and you should use this table to pass the environment variables. For example if in PerlHeaderParserHandler you do:

   $r->subprocess_env(MyLanguage => "de");

you can then deploy mod_include and write in .shtml document:

   <!--#if expr="$MyLanguage = en" -->
   English
   <!--#elif expr="$MyLanguage = de" -->
   Deutsch
   <!--#else -->
   Sorry
   <!--#endif -->

the_request

First HTTP request header

  $request = $r->the_request();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $request ( string )

For example:

  GET /foo/bar/my_path_info?args=3 HTTP/1.0
since: 2.0.00

unparsed_uri

The URI without any parsing performed

  $unparsed_uri = $r->unparsed_uri();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $unparsed_uri ( string )
since: 2.0.00

If for example the request was:

  GET /foo/bar/my_path_info?args=3 HTTP/1.0

$r->uri|/C_uri_ returns:

  /foo/bar/my_path_info

whereas $r->unparsed_uri returns:

  /foo/bar/my_path_info?args=3

uri

The path portion of the URI

  $uri         = $r->uri();
  my $prec_uri = $r->uri($new_uri);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_uri ( string )
ret: $uri ( string )
since: 2.0.00

See the example in the $r->unparsed_uri|/C_unparsed_uri_ section.

user

Get the user name, if an authentication process was successful. Or set it.

  $user      = $r->user();
  $prev_user = $r->user($new_user);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $new_user ( string )

Pass $new_user to set a new value

ret: $user ( string )

The current username if an authentication process was successful.

If $new_user was passed, the previous value is returned.

since: 2.0.00

For example, let's print the username passed by the client:

  my ($res, $sent_pw) = $r->get_basic_auth_pw;
  return $res if $res != Apache2::Const::OK;
  print "User: ", $r->user;

Unsupported API

Apache2::RequestRec also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

allowed_methods

META: Autogenerated - needs to be reviewed/completed

List of allowed methods

  $list = $r->allowed_methods();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $list ( Apache2::MethodList object|docs::2.0::api::Apache2::MethodList )
since: 2.0.00

META: Apache2::MethodList is not available at the moment

allowed_xmethods

META: Autogenerated - needs to be reviewed/completed

Array of extension methods

  $array = $r->allowed_xmethods();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $array ( APR::ArrayHeader object|docs::2.0::api::APR::ArrayHeader )
since: 2.0.00

META: APR::ArrayHeader is not available at the moment

request_config

Config vector containing pointers to request's per-server config structures

  $ret = $r->request_config($newval);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $newval ( Apache2::ConfVector object|docs::2.0::api::Apache2::ConfVector )
since: 2.0.00

used_path_info

META: Autogenerated - needs to be reviewed/completed

Flag for the handler to accept or reject path_info on the current request. All modules should respect the AP_REQ_ACCEPT_PATH_INFO and AP_REQ_REJECT_PATH_INFO values, while AP_REQ_DEFAULT_PATH_INFO indicates they may follow existing conventions. This is set to the user's preference upon HOOK_VERY_FIRST of the fixups.

  $ret = $r->used_path_info($newval);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $newval (integer)
since: 2.0.00

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::RequestUtil - Perl API for Apache request record utils

  • Synopsis
  • Description
  • API
    • add_config
    • as_string
    • child_terminate
    • default_type
    • dir_config
    • document_root
    • get_handlers
    • get_limit_req_body
    • get_server_name
    • get_server_port
    • get_status_line
    • is_initial_req
    • is_perl_option_enabled
    • location
    • location_merge
    • new
    • no_cache
    • pnotes
    • psignature
    • request
    • push_handlers
    • set_basic_credentials
    • set_handlers
    • slurp_filename
  • See Also
  • Copyright
  • Authors

NAME

Apache2::RequestUtil - Perl API for Apache request record utils

Synopsis

  use Apache2::RequestUtil ();

  # add httpd config dynamically
  $r->add_config(['require valid-user']);

  # dump the request object as a string
  print $r->as_string();

  # default content_type
  $content_type = $r->default_type();

  # get PerlSetVar/PerlAddVar values
  @values = $r->dir_config->get($key);

  # get server docroot
  $docroot = $r->document_root();

  # set server docroot
  $r->document_root($new_root);

  # what are the registered perl handlers for a given phase
  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };

  # push a new handler for a given phase
  $r->push_handlers(PerlCleanupHandler => \&handler);

  # set handlers for a given phase (resetting previous values)
  $r->set_handlers(PerlCleanupHandler => []);

  # what's the request body limit
  $limit = $r->get_limit_req_body();

  # server and port names
  $server = $r->get_server_name();
  $port   = $r->get_server_port();

  # what string Apache is going to send for a given status code
  $status_line = Apache2::RequestUtil::get_status_line(404);

  # are we in the main request?
  $is_initial = $r->is_initial_req();

  # directory level PerlOptions flags lookup
  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');

  # current <Location> value
  $location = $r->location();

  # merge a <Location> container in a request object
  $r->location_merge($location);

  # create a new Apache2::RequestRec object
  $r = Apache2::RequestRec->new($c);

  # tell the client not to cache the response
  $r->no_cache($boolean);

  # share perl objects like $r->notes
  $r->pnotes($key => [$obj1, $obj2]);

  # get HTML signature
  $sig = $r->psignature($prefix);

  # get the global request object (requires PerlOptions +GlobalRequest)
  $r = Apache2::RequestUtil->request;

  # insert auth credentials into the request as if the client did that
  $r->set_basic_credentials($username, $password);

  # slurp the contents of $r->filename
  my $content = ${ $r->slurp_filename() };

  # terminate the current child after this request
  $r->child_terminate();

Description

Apache2::RequestUtil provides the Apache request object utilities API.

API

add_config

Dynamically add Apache configuration at request processing runtime:

  $r->add_config($lines);
  $r->add_config($lines, $override);
  $r->add_config($lines, $override, $path);
  $r->add_config($lines, $override, $path, $override_opts);

Configuration directives are processed as if given in a <Location> block.

obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $lines (ARRAY ref)

An ARRAY reference containing configuration lines per element, without the new line terminators.

opt arg2: $override ( Apache2::Const override constant|docs::2.0::api::Apache2::Const )

Which allow-override bits are set

Default value is: Apache2::Const::OR_AUTHCFG|docs::2.0::api::Apache2::Const/C_Apache2__Const__OR_AUTHCFG_

opt arg3: $path ( string )

Set the Apache2::CmdParms object|docs::2.0::api::Apache2::CmdParms path component. This is the path of the <Location> block. Some directives need this, for example ProxyPassReverse.

If an empty string is passed a NULL pointer is passed further at C-level. This is necessary to make something like this work:

  $r->add_config( [
                   '<Directory />',
                   'AllowOverride Options AuthConfig',
                   '</Directory>',
                  ], ~0, '' );

Note: AllowOverride is valid only in directory context.

Caution: Some directives need a non-empty path otherwise they cause segfaults. Thus, use the empty path with caution.

Default value is: /

opt arg4: $override_opts ( Apache2::Const options constant|docs::2.0::api::Apache2::Const )

Apache limits the applicable directives in certain situations with AllowOverride. With Apache 2.2 comes the possibility to enable or disable single options, for example

  AllowOverride AuthConfig Options=ExecCGI,Indexes

Internally, this directive is parsed into 2 bit fields that are represented by the $override and $override_opts parameters to add_config. The above example is parsed into an $override with 2 bits set, one for AuthConfig the other for Options and an $override_opts with 2 bits set for ExecCGI and Indexes.

When applying other directives, for example AuthType or Options the appropriate bits in $override must be set. For the Options directive additionally $override_opts bits must be set.

The $override and $override_opts parameters to add_config are valid while applying $lines.

$override_opts is new in Apache 2.2. The mod_perl implementation for Apache 2.0 lets you pass the parameter but ignores it.

Default for $override_opts is:
Apache2::Const::OPT_UNSET|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_UNSET_ |
Apache2::Const::OPT_ALL|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_ALL_ |
Apache2::Const::OPT_INCNOEXEC|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_INCNOEXEC_ |
Apache2::Const::OPT_SYM_OWNER|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_SYM_OWNER_ |
Apache2::Const::OPT_MULTI|docs::2.0::api::Apache2::Const/C_Apache2__Const__OPT_MULTI_

That means, all options are allowed.

ret: no return value
since: 2.0.00, $path and $override_opts since 2.0.3

See also: $s->add_config|docs::2.0::api::Apache2::ServerUtil/C_add_config_

For example:

  use Apache2::RequestUtil ();
  use Apache2::Access ();

  $r->add_config(['require valid-user']);

  # this regards the current AllowOverride setting
  $r->add_config(['AuthName secret',
                  'AuthType Basic',
                  'Options ExecCGI'],
                 $r->allow_override, $path, $r->allow_override_opts);

as_string

Dump the request object as a string

  $dump = $r->as_string();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $dump ( string )
since: 2.0.00

Dumps various request and response headers (mainly useful for debugging)

child_terminate

Terminate the current worker process as soon as the current request is over

  $r->child_terminate();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: no return value
since: 2.0.00

This method is not supported in threaded MPMs

default_type

Retrieve the value of the DefaultType directive for the current request. If not set text/plain is returned.

  $content_type = $r->default_type();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $content_type ( string )

The default type

since: 2.0.00

dir_config

$r->dir_config() provides an interface for the per-directory variable specified by the PerlSetVar and PerlAddVar directives, and also can be manipulated via the APR::Table|docs::2.0::api::APR::Table methods.

  $table  = $r->dir_config();
  $value  = $r->dir_config($key);
  @values = $r->dir_config->get($key);
  $r->dir_config($key, $val);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg2: $key ( string )

Key string

opt arg3: $val ( string )

Value string

ret: ...

Depends on the passed arguments, see further discussion

since: 2.0.00

The keys are case-insensitive.

  $apr_table = $r->dir_config();

dir_config() called in a scalar context without the $key argument returns a HASH reference blessed into the APR::Table|docs::2.0::api::APR::Table class. This object can be manipulated via the APR::Table|docs::2.0::api::APR::Table methods. For available methods see the APR::Table|docs::2.0::api::APR::Table manpage.

  $value = $r->dir_config($key);

If the $key argument is passed in the scalar context only a single value will be returned. Since the table preserves the insertion order, if there is more than one value for the same key, the oldest value assosiated with the desired key is returned. Calling in the scalar context is also much faster, as it'll stop searching the table as soon as the first match happens.

  @values = $r->dir_config->get($key);

To receive a list of values you must use get() method from the APR::Table|docs::2.0::api::APR::Table class.

  $r->dir_config($key => $val);

If the $key and the $val arguments are used, the set() operation will happen: all existing values associated with the key $key (and the key itself) will be deleted and $value will be placed instead.

  $r->dir_config($key => undef);

If $val is undef the unset() operation will happen: all existing values associated with the key $key (and the key itself) will be deleted.

document_root

Retrieve the document root for this server

  $docroot = $r->document_root();
  $docroot = $r->document_root($new_root);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

opt arg1: $new_root

Sets the document root to a new value only for the duration of the current request.

Note the limited functionality under threaded MPMs.

ret: $docroot ( string )

The document root

since: 2.0.00

get_handlers

Returns a reference to a list of handlers enabled for a given phase.

  $handlers_list = $r->get_handlers($hook_name);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $hook_name ( string )

a string representing the phase to handle (e.g. PerlLogHandler)

ret: $handlers_list (ref to an ARRAY of CODE refs)

a list of handler subroutines CODE references

since: 2.0.00

See also: $s->add_config|docs::2.0::api::Apache2::ServerUtil/C_get_handlers_

For example:

A list of handlers configured to run at the response phase:

  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };

get_limit_req_body

Return the limit on bytes in request msg body

  $limit = $r->get_limit_req_body();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $limit (integer)

the maximum number of bytes in the request msg body

since: 2.0.00

get_server_name

Get the current request's server name

  $server = $r->get_server_name();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $server ( string )

the server name

since: 2.0.00

For example, consruct a hostport string:

  use Apache2::RequestUtil ();
  my $hostport = join ':', $r->get_server_name, $r->get_server_port;

get_server_port

Get the current server port

  $port = $r->get_server_port();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $port ( integer )

The server's port number

since: 2.0.00

For example, consruct a hostport string:

  use Apache2::RequestUtil ();
  my $hostport = join ':', $r->get_server_name, $r->get_server_port;

get_status_line

Return the Status-Line for a given status code (excluding the HTTP-Version field).

  $status_line = Apache2::RequestUtil::get_status_line($status);
arg1: $status (integer)

The HTTP status code

ret: $status_line ( string )

The Status-Line

If an invalid or unknown status code is passed, "500 Internal Server Error" will be returned.

since: 2.0.00

For example:

  use Apache2::RequestUtil ();
  print Apache2::RequestUtil::get_status_line(400);

will print:

  400 Bad Request

is_initial_req

Determine whether the current request is the main request or a sub-request

  $is_initial = $r->is_initial_req();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

A request or a sub-request object

ret: $is_initial ( boolean )

If true -- it's the main request, otherwise it's a sub-request

since: 2.0.00

is_perl_option_enabled

check whether a directory level PerlOptions flag is enabled or not.

  $result = $r->is_perl_option_enabled($flag);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $flag ( string )
ret: $result ( boolean )
since: 2.0.00

For example to check whether the SetupEnv option is enabled for the current request (which can be disabled with PerlOptions -SetupEnv) and populate the environment variables table if disabled:

  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');

See also: PerlOptions and the equivalent function for server level PerlOptions flags.

location

Get the path of the <Location> section from which the current Perl*Handler is being called.

  $location = $r->location();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $location ( string )
since: 2.0.00

location_merge

Merge a given <Location> container into the current request object:

  $ret = $r->location_merge($location);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $location ( string )

The argument in a <Location> section. For example to merge a container:

  <Location /foo>
      ...
  </Location>

that argument will be /foo

ret: $ret ( boolean )

a true value if the merge was successful (i.e. the request $location match was found), otherwise false.

since: 2.0.00

Useful for insertion of a configuration section into a custom Apache2::RequestRec object, created via the Apache2::RequestRec->new() method. See for example the Command Server protocol example.

new

Create a new Apache2::RequestRec object.

  $r = Apache2::RequestRec->new($c);
  $r = Apache2::RequestRec->new($c, $pool);
obj: Apache2::RequestRec ( Apache2::RequestRec class name|docs::2.0::api::Apache2::RequestRec )
arg1: $c (Apache2::Connection object|docs::2.0::api::Apache2::Connection)
opt arg2: $pool

If no $pool argument is passed, $c->pool is used. That means that the created Apache2::RequestRec object will be valid as long as the connection object is valid.

ret: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
since: 2.0.00

It's possible to reuse the HTTP framework features outside the familiar HTTP request cycle. It's possible to write your own full or partial HTTP implementation without needing a running Apache server. You will need the Apache2::RequestRec object in order to be able to reuse the rich functionality supplied via this object.

See for example the Command Server protocol example which reuses HTTP AAA model under non-HTTP protocol.

no_cache

Add/remove cache control headers:

  $prev_no_cache = $r->no_cache($boolean);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $boolean ( boolean )

A true value sets the no_cache request record member to a true value and inserts:

  Pragma: no-cache
  Cache-control: no-cache

into the response headers, indicating that the data being returned is volatile and the client should not cache it.

A false value unsets the no_cache request record member and the mentioned headers if they were previously set.

ret: $prev_no_cache ( boolean )

Should you care, the no_cache request record member value prior to the change is returned.

since: 2.0.00

This method should be invoked before any response data has been sent out.

pnotes

Share Perl variables between Perl HTTP handlers

  $old_val  = $r->pnotes($key => $val);
  $val      = $r->pnotes($key);
  $hash_ref = $r->pnotes();

Note: sharing variables really means it. The variable is not copied. Only its reference count is incremented. If it is changed after being put in pnotes that change also affects the stored value. The following example illustrates the effect:

  my $v=1;                     my $v=1;
  $r->pnotes( 'v'=>$v );       $r->pnotes->{v}=$v;
  $v++;                        $v++;
  my $x=$r->pnotes('v');       my $x=$r->pnotes->{v};

In both cases $x is 2 not 1. See also Apache2::SafePnotes on CPAN.

obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $key ( string )

A key value

opt arg2: $val ( SCALAR )

Any scalar value (e.g. a reference to an array)

ret: (3 different possible values)

if both, $key and $val are passed the previous value for $key is returned if such existed, otherwise undef is returned.

if only $key is passed, the current value for the given key is returned.

if no arguments are passed, a hash reference is returned, which can then be directly accessed without going through the pnotes() interface.

since: 2.0.00

This method provides functionality similar to (Apache2::RequestRec::notes|docs::2.0::api::Apache2::RequestRec/C_notes_), but values can be any Perl variables. That also means that it can be used only between Perl modules.

The values get reset automatically at the end of each HTTP request.

Examples:

Set a key/value pair:

  $r->pnotes(foo => [1..5]);

Get the value:

  $val = $r->pnotes("foo");

$val now contains an array ref containing 5 elements (1..5).

Now change the existing value:

  $old_val = $r->pnotes(foo => ['a'..'c']);
  $val = $r->pnotes("foo");

$old_val now contains an array ref with 5 elements (1..5) and $val contains an array ref with 3 elements 'a', 'b', 'c'.

Alternatively you can access the hash reference with all pnotes values:

  $pnotes = $r->pnotes;

Now we can read what's in there for the key foo:

  $val = $pnotes->{foo};

and as before $val still gives us an array ref with 3 elements 'a', 'b', 'c'.

Now we can add elements to it:

  push @{ $pnotes{foo} }, 'd'..'f';

and we can try to retrieve them using the hash and non-hash API:

  $val1 = $pnotes{foo};
  $val2 = $r->pnotes("foo");

Both $val1 and $val2 contain an array ref with 6 elements (letters 'a' to 'f').

Finally to reset an entry you could just assign undef as a value:

  $r->pnotes(foo => undef);

but the entry for the key foo still remains with the value undef. If you really want to completely remove it, use the hash interface:

  delete $r->pnotes->{foo};

psignature

Get HTML describing the address and (optionally) admin of the server.

  $sig = $r->psignature($prefix);
obj: $r ( Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec )
arg1: $prefix ( string )

Text which is prepended to the return value

ret: $sig ( string )

HTML text describing the server. Note that depending on the value of the ServerSignature directive, the function may return the address, including the admin information or nothing at all.

since: 2.0.00

request

Get/set the ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec ) object for the current request.

  $r = Apache2::RequestUtil->request;
       Apache2::RequestUtil->request($new_r);
obj: Apache2 (class name)

The Apache class name

opt arg1: $new_r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
since: 2.0.00

The get-able part of this method is only available if PerlOptions +GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_ is in effect or if Apache2->request($new_r) was called earlier. So instead of setting PerlOptions +GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_, one can set the global request from within the handler.

push_handlers

Add one or more handlers to a list of handlers to be called for a given phase.

  $ok = $r->push_handlers($hook_name => \&handler);
  $ok = $r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $hook_name ( string )

the phase to add the handlers to

arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )

a single handler CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

if more than one passed, use a reference to an array of CODE refs and/or subroutine names.

ret: $ok ( boolean )

returns a true value on success, otherwise a false value

since: 2.0.00

See also: $s->add_config|docs::2.0::api::Apache2::ServerUtil/C_push_handlers_

Note that to push input/output filters you have to use Apache2::Filter|docs::2.0::api::Apache2::Filter methods: add_input_filter|docs::2.0::api::Apache2::Filter/C_add_input_filter_ and add_output_filter|docs::2.0::api::Apache2::Filter/C_add_output_filter_.

Examples:

A single handler:

  $r->push_handlers(PerlResponseHandler => \&handler);

Multiple handlers:

  $r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $r->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

set_basic_credentials

Populate the incoming request headers table (headers_in) with authentication headers for Basic Authorization as if the client has submitted those in first place:

  $r->set_basic_credentials($username, $password);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $username ( string )
arg2: $password ( string )
ret: no return value
since: 2.0.00

See for example the Command Server protocol example which reuses HTTP AAA model under non-HTTP protocol.

set_handlers

Set a list of handlers to be called for a given phase. Any previously set handlers are forgotten.

  $ok = $r->set_handlers($hook_name => \&handler);
  $ok = $r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
  $ok = $r->set_handlers($hook_name => []);
  $ok = $r->set_handlers($hook_name => undef);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $hook_name ( string )

the phase to set the handlers in

arg2: $handlers (CODE ref or SUB name or an ARRAY ref)

a reference to a single handler CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

if more than one passed, use a reference to an array of CODE refs and/or subroutine names.

if the argument is undef or [] the list of handlers is reset to zero.

ret: $ok ( boolean )

returns a true value on success, otherwise a false value

since: 2.0.00

See also: $s->add_config|docs::2.0::api::Apache2::ServerUtil/C_set_handlers_

Examples:

A single handler:

  $r->set_handlers(PerlResponseHandler => \&handler);

Multiple handlers:

  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

Reset any previously set handlers:

  $r->set_handlers(PerlCleanupHandler => []);

or

  $r->set_handlers(PerlCleanupHandler => undef);

slurp_filename

Slurp the contents of $r->filename:

  $content_ref = $r->slurp_filename($tainted);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $tainted (number)

If the server is run under the tainting mode (-T) which we hope you do, by default the returned data is tainted. If an optional $tainted flag is set to zero, the data will be marked as non-tainted.

Do not set this flag to zero unless you know what you are doing, you may create a security hole in your program if you do. For more information see the perlsec manpage.

If you wonder why this option is available, it is used internally by the ModPerl::Registry|docs::2.0::api::ModPerl::Registry handler and friends, because the CGI scripts that it reads are considered safe (you could just as well require() them).

ret: $content_ref ( SCALAR ref )

A reference to a string with the contents

excpt: APR::Error|docs::2.0::api::APR::Error

Possible error codes could be: APR::Const::EACCES|docs::2.0::api::APR::Const/C_APR__Const__EACCES_ (permission problems), APR::Const::ENOENT|docs::2.0::api::APR::Const/C_APR__Const__ENOENT_ (file not found), and others. For checking such error codes, see the documentation for, for example, APR::Status::is_EACCES|docs::2.0::api::APR::Status/C_is_EACCES_ and APR::Status::is_ENOENT|docs::2.0::api::APR::Status/C_is_ENOENT_.

since: 2.0.00

Note that if you assign to $r->filename you need to update its stat record.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Resource - Limit resources used by httpd children

  • Synopsis
  • Description
  • Defaults
  • See Also
  • Copyright
  • Author

NAME

Apache2::Resource - Limit resources used by httpd children

Synopsis

  PerlModule Apache2::Resource
  # set child memory limit in megabytes
  # default is 64 Meg
  PerlSetEnv PERL_RLIMIT_DATA 32:48

  # linux does not honor RLIMIT_DATA
  # RLIMIT_AS (address space) will work to limit the size of a process
  PerlSetEnv PERL_RLIMIT_AS 32:48

  # set child cpu limit in seconds
  # default is 360 seconds
  PerlSetEnv PERL_RLIMIT_CPU 120

  PerlChildInitHandler Apache2::Resource

Description

Apache2::Resource uses the BSD::Resource module, which uses the C function setrlimit to set limits on system resources such as memory and cpu usage.

Any RLIMIT operation available to limit on your system can be set by defining that operation as an environment variable with a PERL_ prefix. See your system setrlimit manpage for available resources which can be limited.

The following limit values are in megabytes: DATA, RSS, STACK, FSIZE, CORE, MEMLOCK; all others are treated as their natural unit.

If the value of the variable is of the form S:H, S is treated as the soft limit, and H is the hard limit. If it is just a single number, it is used for both soft and hard limits.

Defaults

To set reasonable defaults for all RLIMITs, add this to your httpd.conf:

  PerlSetEnv PERL_RLIMIT_DEFAULTS On
  PerlModule Apache2::Resource

See Also

BSD::Resource(3), setrlimit(2)

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Author

Doug MacEachern


Apache2::Response - Perl API for Apache HTTP request response methods

  • Synopsis
  • Description
  • API
    • custom_response
    • make_etag
    • meets_conditions
    • rationalize_mtime
    • send_cgi_header
    • set_content_length
    • set_etag
    • set_keepalive
    • set_last_modified
    • update_mtime
  • Unsupported API
    • send_error_response
    • send_mmap
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Response - Perl API for Apache HTTP request response methods

Synopsis

  use Apache2::Response ();

  $r->custom_response(Apache2::Const::FORBIDDEN, "No Entry today");

  $etag = $r->make_etag($force_weak);
  $r->set_etag();
  $status = $r->meets_conditions();

  $mtime_rat = $r->rationalize_mtime($mtime);
  $r->set_last_modified($mtime);
  $r->update_mtime($mtime);

  $r->send_cgi_header($buffer);

  $r->set_content_length($length);

  $ret = $r->set_keepalive();

Description

Apache2::Response provides the Apache request object utilities API for dealing with HTTP response generation process.

API

Apache2::Response provides the following functions and/or methods:

custom_response

Install a custom response handler for a given status

  $r->custom_response($status, $string);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $status ( Apache2::Const constant|docs::2.0::api::Apache2::Const )

The status for which the custom response should be used (e.g. Apache2::Const::AUTH_REQUIRED)

arg2: $string (string)

The custom response to use. This can be a static string, or a URL, full or just the uri path (/foo/bar.txt).

ret: no return value
since: 2.0.00

custom_response() doesn't alter the response code, but is used to replace the standard response body. For example, here is how to change the response body for the access handler failure:

  package MyApache2::MyShop;
  use Apache2::Response ();
  use Apache2::Const -compile => qw(FORBIDDEN OK);
  sub access {
      my $r = shift;

      if (MyApache2::MyShop::tired_squirrels()) {
          $r->custom_response(Apache2::Const::FORBIDDEN,
              "It's siesta time, please try later");
          return Apache2::Const::FORBIDDEN;
      }

      return Apache2::Const::OK;
  }
  ...

  # httpd.conf
  PerlModule MyApache2::MyShop
  <Location /TestAPI__custom_response>
      AuthName dummy
      AuthType none
      PerlAccessHandler   MyApache2::MyShop::access
      PerlResponseHandler MyApache2::MyShop::response
  </Location>

When squirrels can't run any more, the handler will return 403, with the custom message:

  It's siesta time, please try later

make_etag

Construct an entity tag from the resource information. If it's a real file, build in some of the file characteristics.

  $etag = $r->make_etag($force_weak);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $force_weak (number)

Force the entity tag to be weak - it could be modified again in as short an interval.

ret: $etag (string)

The entity tag

since: 2.0.00

meets_conditions

Implements condition GET rules for HTTP/1.1 specification. This function inspects the client headers and determines if the response fulfills the specified requirements.

  $status = $r->meets_conditions();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $status ( Apache2::Const status constant|docs::2.0::api::Apache2::Const )

Apache2::Const::OK if the response fulfills the condition GET rules. Otherwise some other status code (which should be returned to Apache).

since: 2.0.00

Refer to the Generating Correct HTTP Headers document for an indepth discussion of this method.

rationalize_mtime

Return the latest rational time from a request/mtime pair.

  $mtime_rat = $r->rationalize_mtime($mtime);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $mtime ( time in seconds )

The last modified time

ret: $mtime_rat ( time in seconds )

the latest rational time from a request/mtime pair. Mtime is returned unless it's in the future, in which case we return the current time.

since: 2.0.00

send_cgi_header

Parse the header

  $r->send_cgi_header($buffer);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $buffer (string)

headers and optionally a response body

ret: no return value
since: 2.0.00

This method is really for back-compatibility with mod_perl 1.0. It's very inefficient to send headers this way, because of the parsing overhead.

If there is a response body following the headers it'll be handled too (as if it was sent via print()|docs::2.0::api::Apache2::RequestIO::C_print_/).

Notice that if only HTTP headers are included they won't be sent until some body is sent (again the "send" part is retained from the mod_perl 1.0 method).

set_content_length

Set the content length for this request.

  $r->set_content_length($length);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $length (integer)

The new content length

ret: no return value
since: 2.0.00

set_etag

Set the E-tag outgoing header

  $r->set_etag();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
ret: no return value
since: 2.0.00

set_keepalive

Set the keepalive status for this request

  $ret = $r->set_keepalive();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

ret: $ret ( boolean )

true if keepalive can be set, false otherwise

since: 2.0.00

It's called by ap_http_header_filter(). For the complete complicated logic implemented by this method see httpd-2.0/server/http_protocol.c.

set_last_modified

sets the Last-Modified response header field to the value of the mtime field in the request structure -- rationalized to keep it from being in the future.

  $r->set_last_modified($mtime);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
opt arg1: $mtime ( time in seconds )

if the $mtime argument is passed, $r->update_mtime will be first run with that argument.

ret: no return value
since: 2.0.00

update_mtime

Set the $r->mtime|docs::2.0::api::Apache2::RequestRec/C_mtime_ field to the specified value if it's later than what's already there.

  $r->update_mtime($mtime);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $mtime ( time in seconds )
ret: no return value
since: 2.0.00

See also: $r->set_last_modified.

Unsupported API

Apache2::Response also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

send_error_response

Send an "error" response back to client. It is used for any response that can be generated by the server from the request record. This includes all 204 (no content), 3xx (redirect), 4xx (client error), and 5xx (server error) messages that have not been redirected to another handler via the ErrorDocument feature.

  $r->send_error_response($recursive_error);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $recursive_error ( boolean )

the error status in case we get an error in the process of trying to deal with an ErrorDocument to handle some other error. In that case, we print the default report for the first thing that went wrong, and more briefly report on the problem with the ErrorDocument.

ret: no return value
since: 2.0.00

META: it's really an internal Apache method, I'm not quite sure how can it be used externally.

send_mmap

META: Autogenerated - needs to be reviewed/completed

Send an MMAP'ed file to the client

  $ret = $r->send_mmap($mm, $offset, $length);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $mm (APR::Mmap|docs::2.0::api::APR::Mmap)

The MMAP'ed file to send

arg2: $offset (number)

The offset into the MMAP to start sending

arg3: $length (integer)

The amount of data to send

ret: $ret (integer)

The number of bytes sent

since: 2.0.00

META: requires a working APR::Mmap, which is not supported at the moment.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::ServerRec - Perl API for Apache server record accessors

  • Synopsis
  • Description
  • API
    • error_fname
    • is_virtual
    • keep_alive
    • keep_alive_max
    • keep_alive_timeout
    • limit_req_fields
    • limit_req_fieldsize
    • limit_req_line
    • loglevel
    • next
    • path
    • port
    • process
    • server_admin
    • server_hostname
    • timeout
  • Notes
    • Limited Functionality under Threaded MPMs
  • Unsupported API
    • addrs
    • lookup_defaults
    • module_config
    • names
    • wild_names
  • See Also
  • Copyright
  • Authors

NAME

Apache2::ServerRec - Perl API for Apache server record accessors

Synopsis

  use Apache2::ServerRec ();

  $error_fname = $s->error_fname();

  $is_virtual = $s->is_virtual();

  $keep_alive         = $s->keep_alive();
  $keep_alive_max     = $s->keep_alive_max();
  $keep_alive_timeout = $s->keep_alive_timeout();

  $limit_req_fields    = $s->limit_req_fields();
  $limit_req_fieldsize = $s->limit_req_fieldsize();
  $limit_req_line      = $s->limit_req_line();

  $path = $s->path();

  $hostname = $s->server_hostname();
  $port     = $s->port();

  $server_admin = $s->server_admin();

  $proc = $s->process();

  $timeout  = $s->timeout();
  $loglevel = $s->loglevel();

  my $server = Apache2::ServerUtil->server;
  my $vhosts = 0;
  for (my $s = $server->next; $s; $s = $s->next) {
      $vhosts++;
  }
  print "There are $vhosts virtual hosts";

Description

Apache2::ServerRec provides the Perl API for Apache server_rec object.

Apache2::ServerUtil|docs::2.0::api::Apache2::ServerUtil provides an extra functionality.

API

Apache2::ServerRec provides the following functions and/or methods:

error_fname

Get/set the ErrorLog file value (e.g. logs/error_log)

  $error_fname      = $s->error_fname();
  $prev_error_fname = $s->error_fname($new_error_fname);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_error_fname ( string )

If passed, sets the new value for ErrorLog

Note the limited functionality under threaded MPMs.

ret: $error_fname ( string )

Returns the ErrorLog value setting.

If $new_error_fname is passed returns the setting before the change.

since: 2.0.00

is_virtual

Test whether $s is a virtual host object

  $is_virtual = $s->is_virtual();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $is_virtual ( boolean )

Returns the is_virtual setting.

If $new_is_virtual is passed, returns the setting before the change.

since: 2.0.00

Example:

  print "This is a virtual host" if $s->is_virtual();

keep_alive

Get/set the KeepAlive setting, which specifies whether Apache should accept more than one request over the same connection from the same client.

  $keep_alive      = $s->keep_alive();
  $prev_keep_alive = $s->keep_alive($new_keep_alive);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_keep_alive ( boolean )

If passed, sets the new keep_alive.

Note the limited functionality under threaded MPMs.

ret: $keep_alive ( boolean )

Returns the KeepAlive setting.

If $new_keep_alive is passed, returns the setting before the change.

since: 2.0.00

keep_alive_max

Get/set the MaxKeepAliveRequest setting, which specifies the maximum number of requests Apache will serve over a KeepAlive connection.

  $keep_alive_max      = $s->keep_alive_max();
  $prev_keep_alive_max = $s->keep_alive_max($new_keep_alive_max);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_keep_alive_max ( integer )

If passed, sets the new keep_alive_max.

Note the limited functionality under threaded MPMs.

ret: $keep_alive_max ( integer )

Returns the keep_alive_max setting.

If $new_keep_alive_max is passed, returns the setting before the change.

since: 2.0.00

keep_alive_timeout

Get/set the KeepAliveTimeout setting (in microsecs), which specifies how long Apache will wait for another request before breaking a KeepAlive connection.

  $keep_alive_timeout      = $s->keep_alive_timeout();
  $prev_keep_alive_timeout = $s->keep_alive_timeout($new_timeout);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_keep_alive_timeout ( integer )

The expected value is in microsecs.

If passed, sets the new KeepAlive timeout.

Note the limited functionality under threaded MPMs.

ret: $keep_alive_timeout ( integer )

Returns the KeepAlive timeout value (in microsecs).

If $new_timeout is passed, returns the setting before the change.

since: 2.0.00

limit_req_fields

Get/set limit on number of request header fields

  $limit_req_fields      = $s->limit_req_fields();
  $prev_limit_req_fields = $s->limit_req_fields($new_limit_req_fields);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_limit_req_fields ( integer )

If passed, sets the new request headers number limit.

Note the limited functionality under threaded MPMs.

ret: $limit_req_fields ( integer )

Returns the request headers number limit.

If $new_limit_req_fields is passed, returns the setting before the change.

since: 2.0.00

limit_req_fieldsize

Get/set limit on size of any request header field

  $limit_req_fieldsize = $s->limit_req_fieldsize();
  $prev_limit          = $s->limit_req_fieldsize($new_limit);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_limit_req_fieldsize ( integer )

If passed, sets the new request header size limit.

Note the limited functionality under threaded MPMs.

ret: $limit_req_fieldsize ( integer )

Returns the request header size limit.

If $new_limit is passed, returns the setting before the change.

since: 2.0.00

limit_req_line

Get/set limit on size of the HTTP request line

  $limit_req_line      = $s->limit_req_line();
  $prev_limit_req_line = $s->limit_req_line($new_limit_req_line);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_limit_req_line ( integer )

If passed, sets the new request line limit value.

Note the limited functionality under threaded MPMs.

ret: $limit_req_line ( integer )

Returns the request line limit value

If $new_limit_req_line is passed, returns the setting before the change.

since: 2.0.00

loglevel

Get/set the LogLevel directive value

  $loglevel      = $s->loglevel();
  $prev_loglevel = $s->loglevel($new_loglevel);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_loglevel ( Apache2::Const :log constant|docs::2.0::api::Apache2::Const/C__log_ )

If passed, sets a new LogLevel value

Note the limited functionality under threaded MPMs.

ret: $loglevel ( Apache2::Const :log constant|docs::2.0::api::Apache2::Const/C__log_ )

Returns the LogLevel value as a constant.

If $new_loglevel is passed, returns the setting before the change.

since: 2.0.00

For example, to set the LogLevel value to info:

  use Apache2::Const -compile => qw(LOG_INFO);
  $s->loglevel(Apache2::Const::LOG_INFO);

next

The next server record in the list (if there are vhosts)

  $s_next = $s->next();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $s_next ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.00

For example the following code traverses all the servers, starting from the base server and continuing to vhost servers, counting all available vhosts:

  use Apache2::ServerRec ();
  use Apache2::ServerUtil ();
  my $server = Apache2::ServerUtil->server;
  my $vhosts = 0;
  for (my $s = $server->next; $s; $s = $s->next) {
      $vhosts++;
  }
  print "There are $vhosts virtual hosts";

path

Get/set pathname for the ServerPath setting

  $path      = $s->path();
  $prev_path = $s->path($new_path);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_path ( string )

If passed, sets the new path.

Note the limited functionality under threaded MPMs.

ret: $path ( string )

Returns the path setting.

If $new_path is passed, returns the setting before the change.

since: 2.0.00

port

Get/set the port value

  $port      = $s->port();
  $prev_port = $s->port($new_port);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_port ( integer )

If passed, sets the new port.

Note the limited functionality under threaded MPMs.

META: I don't think one should be allowed to change port number after the server has started.

ret: $port ( integer )

Returns the port setting.

If $new_port is passed returns the setting before the change.

since: 2.0.00

process

The process this server is running in

  $proc = $s->process();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $proc ( Apache2::Process object|docs::2.0::api::Apache2::Process )
since: 2.0.00

server_admin

Get/set the ServerAdmin value

  $server_admin      = $s->server_admin();
  $prev_server_admin = $s->server_admin($new_server_admin);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_server_admin ( string )

If passed, sets the new ServerAdmin value.

Note the limited functionality under threaded MPMs.

ret: $server_admin ( string )

Returns the ServerAdmin value.

If $new_server_admin is passed, returns the setting before the change.

since: 2.0.00

server_hostname

Get/set the ServerName value

  $server_hostname      = $s->server_hostname();
  $prev_server_hostname = $s->server_hostname($new_server_hostname);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_server_hostname ( string )

If passed, sets the ServerName value

Note the limited functionality under threaded MPMs.

ret: $server_hostname ( string )

Returns the ServerName value

If $new_server_hostname is passed, returns the setting before the change.

since: 2.0.00

timeout

Get/set the timeout (TimeOut) (in microsecs), which Apache will wait for before it gives up doing something

  $timeout      = $s->timeout();
  $prev_timeout = $s->timeout($new_timeout);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_timeout ( integer )

If passed, sets the new timeout (the value should be in microseconds).

Note the limited functionality under threaded MPMs.

ret: $timeout ( integer )

Returns the timeout setting in microseconds.

If $new_timeout is passed, returns the setting before the change.

since: 2.0.00

Let us repeat again: the timeout values is microseconds. For example to set the timeout to 20 secs:

  $s->timeout(20_000_000);

Notes

Limited Functionality under Threaded MPMs

Note that under threaded MPMs, some of the read/write accessors, will be able to set values only before threads are spawned (i.e. before the ChildInit phase|docs::2.0::user::handlers::server/C_PerlChildInitHandler_). Therefore if you are developing your application on the non-threaded MPM, but planning to have it run under threaded mpm, you should not use those methods to set values after the ChildInit phase.

The affected accessor methods are marked as such in their respective documentation entries.

Unsupported API

Apache2::ServerRec also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

addrs

Get the addrs value

  $addrs = $s->addrs();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $addrs ( Apache2::ServerAddr|docs::2.0::api::Apache2::ServerAddr )

Returns the addrs setting.

since: subject to change

META: this methods returns a vhost-specific Apache2::ServerAddr object, which is not implemented at the moment. See the struct server_addr_rec entry in httpd-2.0/include/httpd.h for more information. It seems that most (all?) of the information in that record is available through other APIs.

lookup_defaults

Get the lookup_defaults value. MIME type info, etc., before we start checking per-directory info.

  $lookup_defaults = $s->lookup_defaults();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $lookup_defaults ( Apache2::ConfVector|docs::2.0::api::Apache2::ConfVector )

Returns the lookup_defaults setting.

since: subject to change

module_config

Get config vector containing pointers to modules' per-server config structures.

  $module_config = $s->module_config();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
ret: $module_config ( Apache2::ConfVector|docs::2.0::api::Apache2::ConfVector )

Returns the module_config setting.

since: subject to change

names

Get/set the value(s) for the ServerAlias setting

  $names      = $s->names();
  $prev_names = $s->names($new_names);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_names ( APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader )

If passed, sets the new names.

Note the limited functionality under threaded MPMs.

ret: $names ( APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader )

Returns the names setting.

If $new_names is passed, returns the setting before the change.

since: 2.0.00

META: we don't have APR::ArrayHeader yet

wild_names

Wildcarded names for ServerAlias servers

  $wild_names      = $s->wild_names();
  $prev_wild_names = $s->wild_names($new_wild_names);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg1: $new_wild_names ( APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader )

If passed, sets the new wild_names.

Note the limited functionality under threaded MPMs.

ret: $wild_names ( APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader )

Returns the wild_names setting.

If $new_wild_names is passed, returns the setting before the change.

since: 2.0.00

META: we don't have APR::ArrayHeader yet

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::ServerUtil - Perl API for Apache server record utils

  • Synopsis
  • Description
  • Methods API
    • add_config
    • add_version_component
    • dir_config
    • exists_config_define
    • get_handlers
    • get_server_built
    • get_server_version
    • group_id
    • is_perl_option_enabled
    • method_register
    • push_handlers
    • restart_count
    • server
    • server_root
    • server_root_relative
    • server_shutdown_cleanup_register
    • set_handlers
    • user_id
  • Unsupported API
    • error_log2stderr
  • See Also
  • Copyright
  • Authors

NAME

Apache2::ServerUtil - Perl API for Apache server record utils

Synopsis

  use Apache2::ServerUtil ();
  $s = Apache2::ServerUtil->server;

  # push config
  $s->add_config(['ServerTokens off']);

  # add components to the Server signature
  $s->add_version_component("MyModule/1.234");

  # access PerlSetVar/PerlAddVar values
  my $srv_cfg = $s->dir_config;

  # check command line defines
  print "this is mp2"
      if Apache2::ServerUtil::exists_config_define('MODPERL2');

  # get PerlChildExitHandler configured handlers
  @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};

  # server build and version info:
  $when_built = Apache2::ServerUtil::get_server_built();
  $version = Apache2::ServerUtil::get_server_version();

  # ServerRoot value
  $server_root = Apache2::ServerUtil::server_root();

  # get 'conf/' dir path (avoid using this function!)
  my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'conf');

  # set child_exit handlers
  $r->set_handlers(PerlChildExitHandler => \&handler);

  # server level PerlOptions flags lookup
  $s->push_handlers(ChildExit => \&child_exit)
      if $s->is_perl_option_enabled('ChildExit');

  # extend HTTP to support a new method
  $s->method_register('NEWGET');

  # register server shutdown callback
  Apache2::ServerUtil::server_shutdown_register_cleanup(sub { Apache2::Const::OK });

  # do something only when the server restarts
  my $cnt = Apache2::ServerUtil::restart_count();
  do_something_once() if $cnt > 1;

  # get the resolved ids from Group and User entries
  my $user_id  = Apache2::ServerUtil->user_id;
  my $group_id = Apache2::ServerUtil->group_id;

Description

Apache2::ServerUtil provides the Apache server object utilities API.

Methods API

Apache2::ServerUtil provides the following functions and/or methods:

add_config

Dynamically add Apache configuration:

  $s->add_config($lines);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $lines ( ARRAY ref )

An ARRAY reference containing configuration lines per element, without the new line terminators.

ret: no return value
since: 2.0.00

See also: $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_add_config_

For example:

Add a configuration section at the server startup (e.g. from startup.pl):

  use Apache2::ServerUtil ();
  my $conf = <<'EOC';
  PerlModule Apache2::MyExample
  <Location /perl>
    SetHandler perl-script
    PerlResponseHandler Apache2::MyExample
  </Location>
  EOC
  Apache2::ServerUtil->server->add_config([split /\n/, $conf]);

add_version_component

Add a component to the version string

  $s->add_version_component($component);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $component ( string )

The string component to add

ret: no return value
since: 2.0.00

This function is usually used by modules to advertise themselves to the world. It's picked up by such statistics collectors, like netcraft.com, which accomplish that by connecting to various servers and grabbing the server version response header (Server). Some servers choose to fully or partially conceal that header.

This method should be invoked in the PerlPostConfigHandler|docs::2.0::user::handlers::server/C_PerlPostConfigHandler_ phase, which will ensure that the Apache core version number will appear first.

For example let's add a component "Hikers, Inc/0.99999" to the server string at the server startup:

  use Apache2::ServerUtil ();
  use Apache2::Const -compile => 'OK';

  Apache2::ServerUtil->server->push_handlers(
      PerlPostConfigHandler => \&add_my_version);

  sub add_my_version {
      my ($conf_pool, $log_pool, $temp_pool, $s) = @_;
      $s->add_version_component("Hikers, Inc/0.99999");
      return Apache2::Const::OK;
  }

or of course you could register the PerlPostConfigHandler|docs::2.0::user::handlers::server/C_PerlPostConfigHandler_ handler directly in httpd.conf

Now when the server starts, you will something like:

  [Thu Jul 15 12:15:28 2004] [notice] Apache/2.0.51-dev (Unix)
  mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.99999
  configured -- resuming normal operations

Also remember that the ServerTokens directive value controls whether the component information is displayed or not.

dir_config

$s->dir_config() provides an interface for the per-server variables specified by the PerlSetVar and PerlAddVar directives, and also can be manipulated via the APR::Table|docs::2.0::api::APR::Table methods.

  $table  = $s->dir_config();
  $value  = $s->dir_config($key);
  @values = $s->dir_config($key);
  $s->dir_config($key, $val);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
opt arg2: $key ( string )

Key string

opt arg3: $val ( string )

Value string

ret: ...

Depends on the passed arguments, see further discussion

since: 2.0.00

The keys are case-insensitive.

  $t = $s->dir_config();

dir_config() called in a scalar context without the $key argument returns a HASH reference blessed into the APR::Table class. This object can be manipulated via the APR::Table methods. For available methods see APR::Table.

  @values = $s->dir_config($key);

If the $key argument is passed in the list context a list of all matching values will be returned. This method is ineffective for big tables, as it does a linear search of the table. Thefore avoid using this way of calling dir_config() unless you know that there could be more than one value for the wanted key and all the values are wanted.

  $value = $s->dir_config($key);

If the $key argument is passed in the scalar context only a single value will be returned. Since the table preserves the insertion order, if there is more than one value for the same key, the oldest value assosiated with the desired key is returned. Calling in the scalar context is also much faster, as it'll stop searching the table as soon as the first match happens.

  $s->dir_config($key => $val);

If the $key and the $val arguments are used, the set() operation will happen: all existing values associated with the key $key (and the key itself) will be deleted and $value will be placed instead.

  $s->dir_config($key => undef);

If $val is undef the unset() operation will happen: all existing values associated with the key $key (and the key itself) will be deleted.

exists_config_define

Check for a definition from the server startup command line (e.g. -DMODPERL2)

  $result = Apache2::ServerUtil::exists_config_define($name);
arg1: $name ( string )

The define string to check for

ret: $result ( boolean )

true if defined, false otherwise

since: 2.0.00

For example:

  print "this is mp2"
      if Apache2::ServerUtil::exists_config_define('MODPERL2');

get_handlers

Returns a reference to a list of handlers enabled for a given phase.

  $handlers_list = $s->get_handlers($hook_name);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $hook_name ( string )

a string representing the phase to handle.

ret: $handlers_list (ref to an ARRAY of CODE refs)

a list of references to the handler subroutines

since: 2.0.00

See also: $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_get_handlers_

For example:

A list of handlers configured to run at the child_exit phase:

  @handlers = @{ $s->get_handlers('PerlChildExitHandler') || []};

get_server_built

Get the date and time that the server was built

  $when_built = Apache2::ServerUtil::get_server_built();
ret: $when_built ( string )

The server build time string

since: 2.0.00

get_server_version

Get the server version string

  $version = Apache2::ServerUtil::get_server_version();
ret: $version ( string )

The server version string

since: 2.0.00

group_id

Get the group id corresponding to the Group directive in httpd.conf:

  $gid = Apache2::ServerUtil->group_id;
obj: Apache2::ServerUtil (class name)
ret: $gid ( integer )

On Unix platforms returns the gid corresponding to the value used in the Group directive in httpd.conf. On other platforms returns 0.

since: 2.0.03

is_perl_option_enabled

check whether a server level PerlOptions flag is enabled or not.

  $result = $s->is_perl_option_enabled($flag);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $flag ( string )
ret: $result ( boolean )
since: 2.0.00

For example to check whether the ChildExit hook is enabled (which can be disabled with PerlOptions -ChildExit) and configure some handlers to run if enabled:

  $s->push_handlers(ChildExit => \&child_exit)
      if $s->is_perl_option_enabled('ChildExit');

See also: PerlOptions and the equivalent function for directory level PerlOptions flags.

method_register

Register a new request method, and return the offset that will be associated with that method.

  $offset = $s->method_register($methname);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $methname ( string )

The name of the new method to register (in addition to the already supported GET, HEAD, etc.)

ret: $offset ( integer )

An int value representing an offset into a bitmask. You can probably ignore it.

since: 2.0.00

This method allows you to extend the HTTP protocol to support new methods, which fit the HTTP paradigm. Of course you will need to write a client that understands that protocol extension. For a good example, refer to the MyApache2::SendEmail example presented in the PerlHeaderParserHandler section|docs::2.0::user::handlers::http/PerlHeaderParserHandler, which demonstrates how a new method EMAIL is registered and used.

push_handlers

Add one or more handlers to a list of handlers to be called for a given phase.

  $ok = $s->push_handlers($hook_name => \&handler);
  $ok = $s->push_handlers($hook_name => [\&handler, \&handler2]);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $hook_name ( string )

the phase to add the handlers to

arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )

a single handler CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

if more than one passed, use a reference to an array of CODE refs and/or subroutine names.

ret: $ok ( boolean )

returns a true value on success, otherwise a false value

since: 2.0.00

See also: $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_push_handlers_

Examples:

A single handler:

  $s->push_handlers(PerlChildExitHandler => \&handler);

Multiple handlers:

  $s->push_handlers(PerlChildExitHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $s->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

restart_count

How many times the server was restarted.

  $restart_count = Apache2::ServerUtil::restart_count();
ret: restart_count ( number )
since: 2.0.00

The following demonstration should make it clear what values to expect from this function. Let's add the following code to startup.pl, so it's run every time httpd.conf is parsed:

  use Apache2::ServerUtil ();
  my $cnt = Apache2::ServerUtil::restart_count();
  open my $fh, ">>/tmp/out" or die "$!";
  print $fh "cnt: $cnt\n";
  close $fh;

Now let's run a series of server starts and restarts and look at what is logged into /tmp/out:

  % httpd -k start
  cnt: 1
  cnt: 2

  % httpd -k graceful
  cnt: 1
  cnt: 3

  % httpd -k graceful
  cnt: 1
  cnt: 4

  % httpd -k stop
  cnt: 1

Remembering that Apache restarts itself immediately after starting, we can see that the restart_count goes from 1 to 2 during the server start. Moreover we can see that every operation forces the parsing of httpd.conf and therefore reinitialization of mod_perl (and running all the code found in httpd.conf). This happens even when the server is shutdown via httpd -k stop.

What conclusions can be drawn from this demonstration:

  • Apache2::ServerUtil::restart_count() returns 1 every time some -k command is passed to Apache (or kill -USR1 or some alternative signal is received).

  • At all other times the count will be 2 or higher. So for example on graceful restart the count will be 3 or higher.

For example if you want to run something every time httpd -k is run you just need to check whether restart_count() returns 1:

  my $cnt = Apache2::ServerUtil::restart_count();
  do_something() if $cnt == 1;

To do something only when server restarts (httpd -k start or httpd -k graceful), check whether restart_count() is bigger than 1:

  my $cnt = Apache2::ServerUtil::restart_count();
  do_something() if $cnt > 1;

server

Get the main server's object

  $main_s = Apache2::ServerUtil->server();
obj: Apache2::ServerUtil (class name)
ret: $main_s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
since: 2.0.00

server_root

returns the value set by the top-level ServerRoot directive.

  $server_root = Apache2::ServerUtil::server_root();
ret: $server_root ( string )
since: 2.0.00

server_root_relative

Returns the canonical form of the filename made absolute to ServerRoot:

  $path = Apache2::ServerUtil::server_root_relative($pool, $fname);
arg1: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

Make sure that you read the following explanation and understand well which pool object you need to pass before using this function.

opt arg2: $fname ( string )
ret: $path ( string )

The concatenation of ServerRoot and the $fname.

If $fname is not specified, the value of ServerRoot is returned with a trailing /. (it's the same as using '' as $fname's value).

since: 2.0.00

$fname is appended to the value of ServerRoot and returned. For example:

  my $dir = Apache2::ServerUtil::server_root_relative($r->pool, 'logs');

You must be extra-careful when using this function. If you aren't sure what you are doing don't use it.

It's much safer to build the path by yourself using use Apache2::ServerUtil::server_root()|/C_Apache2__server_root_, For example:

  use File::Spec::Functions qw(catfile);
  my $path = catfile Apache2::ServerUtil::server_root, qw(t logs);

In this example, no memory allocation happens on the Apache-side and you aren't risking to get a memory leak.

The problem with server_root_relative is that Apache allocates memory to concatenate the path string. The memory is allocated from the pool object. If you call this method on the server pool object it'll allocate the memory from it. If you do that at the server startup, it's perfectly right, since you will do that only once. However if you do that from within a request or a connection handler, you create a memory leak every time it is called -- as the memory gets allocated from the server pool, it will be freed only when the server is shutdown. Therefore if you need to build a relative to the root server path for the duration of the request, use the request pool:

  use Apache2::RequestRec ();
  Apache2::ServerUtil::server_root_relative($r->pool, $fname);

If you need to have the path for the duration of a connection (e.g. inside a protocol handler), you should use:

  use Apache2::Connection ();
  Apache2::ServerUtil::server_root_relative($c->pool, $fname);

And if you want it for the scope of the server file:

  use Apache2::Process ();
  use Apache2::ServerUtil ();
  Apache2::ServerUtil::server_root_relative($s->process->pool, $fname);

Moreover, you could have encountered the opposite problem, where you have used a short-lived pool object to construct the path, but tried to use the resulting path variable, when that pool has been destructed already. In order to avoid mysterious segmentation faults, mod_perl does a wasteful copy of the path string when returning it to you -- another reason to avoid using this function.

server_shutdown_cleanup_register

Register server shutdown cleanup callback:

  Apache2::ServerUtil::server_shutdown_cleanup_register($sub);
arg1: $sub ( CODE ref or SUB name )
ret: no return value
since: 2.0.00

This function can be used to register a callback to be run once at the server shutdown (compared to PerlChildExitHandler|docs::2.0::user::handlers::server/C_PerlChildExitHandler_ which will execute the callback for each exiting child process).

For example in order to arrange the function do_my_cleanups() to be run every time the server shuts down (or restarts), run the following code at the server startup:

  Apache2::ServerUtil::server_shutdown_cleanup_register(\&do_my_cleanups);

It's necessary to run this code at the server startup (normally startup.pl. The function will croak if run after the PerlPostConfigHandler|docs::2.0::user::handlers::server/C_PerlPostConfigHandler_ phase.

set_handlers

Set a list of handlers to be called for a given phase. Any previously set handlers are forgotten.

  $ok = $s->set_handlers($hook_name => \&handler);
  $ok = $s->set_handlers($hook_name => [\&handler, \&handler2]);
  $ok = $s->set_handlers($hook_name => []);
  $ok = $s->set_handlers($hook_name => undef);
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )
arg1: $hook_name ( string )

the phase to set the handlers in

arg2: $handlers ( CODE ref or SUB name or an ARRAY ref )

a reference to a single handler CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

if more than one passed, use a reference to an array of CODE refs and/or subroutine names.

if the argument is undef or [] the list of handlers is reset to zero.

ret: $ok ( boolean )

returns a true value on success, otherwise a false value

since: 2.0.00

See also: $r->add_config|docs::2.0::api::Apache2::RequestUtil/C_set_handlers_

Examples:

A single handler:

  $r->set_handlers(PerlChildExitHandler => \&handler);

Multiple handlers:

  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

Reset any previously set handlers:

  $r->set_handlers(PerlCleanupHandler => []);

or

  $r->set_handlers(PerlCleanupHandler => undef);

user_id

Get the user id corresponding to the User directive in httpd.conf:

  $uid = Apache2::ServerUtil->user_id;
obj: Apache2::ServerUtil (class name)
ret: $uid ( integer )

On Unix platforms returns the uid corresponding to the value used in the User directive in httpd.conf. On other platforms returns 0.

since: 2.0.03

Unsupported API

Apache2::ServerUtil also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

error_log2stderr

Start sending STDERR to the error_log file

  $s->error_log2stderr();
obj: $s ( Apache2::ServerRec object|docs::2.0::api::Apache2::ServerRec )

The current server

ret: no return value
since: 2.0.00

This method may prove useful if you want to start redirecting STDERR to the error_log file before Apache does that on the startup.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::SizeLimit - Because size does matter.

  • Synopsis
  • Description
  • Shared Memory Options
  • Caveats
    • Supported OSes
    • Supported MPMs
  • Copyright
  • Author

NAME

Apache2::SizeLimit - Because size does matter.

Synopsis

This module allows you to kill off Apache httpd processes if they grow too large. You can choose to set up the process size limiter to check the process size on every request:

  # in your startup.pl, or a <Perl> section:
  use Apache2::SizeLimit;
  # sizes are in KB
  $Apache2::SizeLimit::MAX_PROCESS_SIZE  = 12000; # 12MB
  $Apache2::SizeLimit::MIN_SHARE_SIZE    = 6000;  # 6MB
  $Apache2::SizeLimit::MAX_UNSHARED_SIZE = 5000;  # 5MB

  # in your httpd.conf:
  PerlCleanupHandler Apache2::SizeLimit

Or you can just check those requests that are likely to get big, such as CGI requests. This way of checking is also easier for those who are mostly just running CGI scripts under ModPerl::Registry|docs::2.0::api::ModPerl::Registry:

  # in your script:
  use Apache2::SizeLimit;
  # sizes are in KB
  Apache2::SizeLimit::setmax(12000);
  Apache2::SizeLimit::setmin(6000);
  Apache2::SizeLimit::setmax_unshared(5000);

This will work in places where you are using SetHandler perl-script|docs::2.0::user::config::config/C_perl_script_ or anywhere you enable PerlOptions +GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_. If you want to avoid turning on GlobalRequest, you can pass an Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec object as the second argument in these subs:

  my $r = shift; # if you don't have $r already
  Apache2::SizeLimit::setmax(12000, $r);
  Apache2::SizeLimit::setmin(6000, $r);
  Apache2::SizeLimit::setmax_unshared(5000, $r);

Since checking the process size can take a few system calls on some platforms (e.g. linux), you may want to only check the process size every N times. To do so, put this in your startup.pl or CGI:

  $Apache2::SizeLimit::CHECK_EVERY_N_REQUESTS = 2;

This will only check the process size every other time the process size checker is called.

Description

This module is highly platform dependent, please read the Caveats section. It also does not work under threaded MPMs.

This module was written in response to questions on the mod_perl mailing list on how to tell the httpd process to exit if it gets too big.

Actually there are two big reasons your httpd children will grow. First, it could have a bug that causes the process to increase in size dramatically, until your system starts swapping. Second, it may just do things that requires a lot of memory, and the more different kinds of requests your server handles, the larger the httpd processes grow over time.

This module will not really help you with the first problem. For that you should probably look into Apache2::Resource|docs::2.0::api::Apache2::Resource or some other means of setting a limit on the data size of your program. BSD-ish systems have setrlimit() which will croak your memory gobbling processes. However it is a little violent, terminating your process in mid-request.

This module attempts to solve the second situation where your process slowly grows over time. The idea is to check the memory usage after every request, and if it exceeds a threshold, exit gracefully.

By using this module, you should be able to discontinue using the Apache configuration directive MaxRequestsPerChild, although you can use both if you are feeling paranoid. Most users use the technique shown in this module and set their MaxRequestsPerChild value to 0.

Shared Memory Options

In addition to simply checking the total size of a process, this module can factor in how much of the memory used by the process is actually being shared by copy-on-write. If you don't understand how memory is shared in this way, take a look at the extensive documentation at http://perl.apache.org/docs/.

You can take advantage of the shared memory information by setting a minimum shared size and/or a maximum unshared size. Experience on one heavily trafficked mod_perl site showed that setting maximum unshared size and leaving the others unset is the most effective policy. This is because it only kills off processes that are truly using too much physical RAM, allowing most processes to live longer and reducing the process churn rate.

Caveats

This module is platform-dependent, since finding the size of a process is pretty different from OS to OS, and some platforms may not be supported. In particular, the limits on minimum shared memory and maximum shared memory are currently only supported on Linux and BSD. If you can contribute support for another OS, please do.

Supported OSes

linux

For linux we read the process size out of /proc/self/statm. This seems to be fast enough on modern systems. If you are worried about performance, try setting the CHECK_EVERY_N_REQUESTS option.

Since linux 2.6 /proc/self/statm does not report the amount of memory shared by the copy-on-write mechanism as shared memory. Hence decisions made on the basis of MAX_UNSHARED_SIZE or MIN_SHARE_SIZE are inherently wrong.

To correct the situation there is a patch to the linux kernel that adds a /proc/self/smaps entry for each process. At the time of this writing the patch is included in the mm-tree (linux-2.6.13-rc4-mm1) and is expected to make it into the vanilla kernel in the near future.

/proc/self/smaps reports various sizes for each memory segment of a process and allows to count the amount of shared memory correctly.

If Apache2::SizeLimit detects a kernel that supports /proc/self/smaps and if the Linux::Smaps module is installed it will use them instead of /proc/self/statm. You can prevent Apache2::SizeLimit from using /proc/self/smaps and turn on the old behaviour by setting $Apache2::SizeLimit::USE_SMAPS to 0 before the first check.

Apache2::SizeLimit also resets $Apache2::SizeLimit::USE_SMAPS to 0 if it somehow decides not to use /proc/self/smaps. Thus, you can check it to determine what is actually used.

NOTE: Reading /proc/self/smaps is expensive compared to /proc/self/statm. It must look at each page table entry of a process. Further, on multiprocessor systems the access is synchronized with spinlocks. Hence, you are encouraged to set the CHECK_EVERY_N_REQUESTS option.

The following example shows the effect of copy-on-write:

  <Perl>
    require Apache2::SizeLimit;
    package X;
    use strict;
    use Apache2::RequestRec ();
    use Apache2::RequestIO ();
    use Apache2::Const -compile=>qw(OK);

    my $x= "a" x (1024*1024);

    sub handler {
      my $r = shift;
      my ($size, $shared) = $Apache2::SizeLimit::HOW_BIG_IS_IT->();
      $x =~ tr/a/b/;
      my ($size2, $shared2) = $Apache2::SizeLimit::HOW_BIG_IS_IT->();
      $r->content_type('text/plain');
      $r->print("1: size=$size shared=$shared\n");
      $r->print("2: size=$size2 shared=$shared2\n");
      return Apache2::Const::OK;
    }
      </Perl>

  <Location /X>
    SetHandler modperl
    PerlResponseHandler X
  </Location>

The parent apache allocates a megabyte for the string in $x. The tr-command then overwrites all "a" with "b" if the handler is called with an argument. This write is done in place, thus, the process size doesn't change. Only $x is not shared anymore by means of copy-on-write between the parent and the child.

If /proc/self/smaps is available curl shows:

  r2@s93:~/work/mp2> curl http://localhost:8181/X
  1: size=13452 shared=7456
  2: size=13452 shared=6432

Shared memory has lost 1024 kB. The process' overall size remains unchanged.

Without /proc/self/smaps it says:

  r2@s93:~/work/mp2> curl http://localhost:8181/X
  1: size=13052 shared=3628
  2: size=13052 shared=3636

One can see the kernel lies about the shared memory. It simply doesn't count copy-on-write pages as shared.

Solaris 2.6 and above

For Solaris we simply retrieve the size of /proc/self/as, which contains the address-space image of the process, and convert to KB. Shared memory calculations are not supported.

NOTE: This is only known to work for solaris 2.6 and above. Evidently the /proc filesystem has changed between 2.5.1 and 2.6. Can anyone confirm or deny?

BSD

Uses BSD::Resource::getrusage() to determine process size. This is pretty efficient (a lot more efficient than reading it from the /proc fs anyway).

AIX?

Uses BSD::Resource::getrusage() to determine process size. Not sure if the shared memory calculations will work or not. AIX users?

Win32

Under mod_perl 1, SizeLimit provided basic functionality by using Win32::API to access process memory information. This worked because there was only one mod_perl thread. With mod_perl 2, Win32 runs a true threaded MPM, which unfortunately means that we can't tell the size of each interpreter. Win32 support is disabled until a solution for this can be found.

If your platform is not supported, and if you can tell us how to check for the size of a process under your OS (in KB), then we will add it to the list. The more portable/efficient the solution, the better, of course.

Supported MPMs

At this time, Apache2::SizeLimit does not support use under threaded MPMs. This is because there is no efficient way to get the memory usage of a thread, or make a thread exit cleanly. Suggestions and patches are welcome on the mod_perl dev mailing list.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Author

Doug Bagley <doug+modperl bagley.org>, channeling Procrustes.

Brian Moseley <ix maz.org>: Solaris 2.6 support

Doug Steinwand and Perrin Harkins <perrin elem.com>: added support for shared memory and additional diagnostic info

Matt Phillips <mphillips virage.com> and Mohamed Hendawi <mhendawi virage.com>: Win32 support

Torsten Foertsch <torsten.foertsch gmx.net>: Linux::Smaps support


Apache2::Status - Embedded interpreter status information

  • Synopsis
  • Description
  • Options
    • StatusOptionsAll
    • StatusDumper
    • StatusPeek
    • StatusLexInfo
    • StatusDeparse
    • StatusTerse
    • StatusTerseSize
    • StatusTerseSizeMainSummary
    • StatusGraph
    • Dot
    • GraphDir
  • Prerequisites
  • Copyright
  • See Also
  • Authors

NAME

Apache2::Status - Embedded interpreter status information

Synopsis

  <Location /perl-status>
      SetHandler modperl
      PerlOptions +GlobalRequest
      PerlResponseHandler Apache2::Status
  </Location>
  or
  <Location /perl-status>
      SetHandler perl-script
      PerlResponseHandler Apache2::Status
  </Location>

Description

The Apache2::Status module provides some information about the status of the Perl interpreter embedded in the server.

Configure like so:

  <Location /perl-status>
      SetHandler modperl
      PerlOptions +GlobalRequest
      PerlResponseHandler Apache2::Status
  </Location>

Notice that under the "modperl"|docs::2.0::user::config::config/C_modperl_ core handler the Environment menu option will show only the environment under that handler. To see the environment seen by handlers running under the "perl-script"|docs::2.0::user::config::config/C_perl_script_ core handler, configure Apache2::Status as:

  <Location /perl-status>
      SetHandler perl-script
      PerlResponseHandler Apache2::Status
  </Location>

Other modules can "plugin" a menu item like so:

  require Apache2::Module;
  Apache2::Status->menu_item(
      'DBI' => "DBI connections", #item for Apache::DBI module
      sub {
          my ($r, $q) = @_; #request and CGI objects
          my (@strings);
          push @strings,  "blobs of html";
          return \@strings;     #return an array ref
      }
  ) if Apache2::Module::loaded('Apache2::Status');

WARNING: Apache2::Status must be loaded before these modules via the PerlModule or PerlRequire directives (or from startup.pl).

A very common setup might be: Perl Module B::TerseSize

  <Location /perl-status>
      SetHandler perl-script
      PerlResponseHandler Apache2::Status
      PerlSetVar StatusOptionsAll On
      PerlSetVar StatusDeparseOptions "-p -sC"
  </Location>

due to the implementation of Apache2::Status::noh_fileline in B::TerseSize, you must load B::TerseSize first.

Options

StatusOptionsAll

This single directive will enable all of the options described below.

  PerlSetVar StatusOptionsAll On

StatusDumper

When browsing symbol tables, the values of arrays, hashes and scalars can be viewed via Data::Dumper if this configuration variable is set to On:

  PerlSetVar StatusDumper On

StatusPeek

With this option On and the Apache::Peek module installed, functions and variables can be viewed ala Devel::Peek style:

  PerlSetVar StatusPeek On

StatusLexInfo

With this option On and the B::LexInfo module installed, subroutine lexical variable information can be viewed.

  PerlSetVar StatusLexInfo On

StatusDeparse

With this option On subroutines can be "deparsed".

  PerlSetVar StatusDeparse On

Options can be passed to B::Deparse::new like so:

  PerlSetVar StatusDeparseOptions "-p -sC"

See the B::Deparse manpage for details.

StatusTerse

With this option On, text-based op tree graphs of subroutines can be displayed, thanks to B::Terse.

  PerlSetVar StatusTerse On

StatusTerseSize

With this option On and the B::TerseSize module installed, text-based op tree graphs of subroutines and their size can be displayed. See the B::TerseSize docs for more info.

  PerlSetVar StatusTerseSize On

StatusTerseSizeMainSummary

With this option On and the B::TerseSize module installed, a "Memory Usage" will be added to the Apache2::Status main menu. This option is disabled by default, as it can be rather cpu intensive to summarize memory usage for the entire server. It is strongly suggested that this option only be used with a development server running in -X mode, as the results will be cached.

  PerlSetVar StatusTerseSizeMainSummary On

StatusGraph

When StatusDumper is enabled, another link "OP Tree Graph" will be present with the dump if this configuration variable is set to On:

  PerlSetVar StatusGraph

This requires the B module (part of the Perl compiler kit) and B::Graph (version 0.03 or higher) module to be installed along with the dot program.

Dot is part of the graph visualization toolkit from AT&T: http://www.graphviz.org/.

WARNING: Some graphs may produce very large images, some graphs may produce no image if B::Graph's output is incorrect.

Dot

Location of the dot program for StatusGraph, if other than /usr/bin or /usr/local/bin

GraphDir

Directory where StatusGraph should write it's temporary image files. Default is $ServerRoot/logs/b_graphs.

Prerequisites

The Devel::Symdump module, version 2.00 or higher.

Other optional functionality requirements: B::Deparse - 0.59, B::Fathom - 0.05, B::Graph - 0.03.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

See Also

perl(1), Apache(3), Devel::Symdump(3), Data::Dumper(3), B(3), B::Graph(3), mod_perl 2.0 documentation.

Authors

Doug MacEachern with contributions from Stas Bekman


Apache2::SubProcess -- Executing SubProcesses under mod_perl

  • Synopsis
  • Description
  • API
    • spawn_proc_prog
  • See Also
  • Copyright
  • Authors

NAME

Apache2::SubProcess -- Executing SubProcesses under mod_perl

Synopsis

  use Apache2::SubProcess ();

  use Config;
  use constant PERLIO_IS_ENABLED => $Config{useperlio};

  # pass @ARGV / read from the process
  $command = "/tmp/argv.pl";
  @argv = qw(foo bar);
  $out_fh = $r->spawn_proc_prog($command, \@argv);
  $output = read_data($out_fh);

  # pass environment / read from the process
  $command = "/tmp/env.pl";
  $r->subprocess_env->set(foo => "bar");
  $out_fh = $r->spawn_proc_prog($command);
  $output = read_data($out_fh);

  # write to/read from the process
  $command = "/tmp/in_out_err.pl";
  ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
  print $in_fh "hello\n";
  $output = read_data($out_fh);
  $error  = read_data($err_fh);

  # helper function to work w/ and w/o perlio-enabled Perl
  sub read_data {
      my ($fh) = @_;
      my $data;
      if (PERLIO_IS_ENABLED || IO::Select->new($fh)->can_read(10)) {
          $data = <$fh>;
      }
      return defined $data ? $data : '';
  }

  # pass @ARGV but don't ask for any communication channels
  $command = "/tmp/argv.pl";
  @argv = qw(foo bar);
  $r->spawn_proc_prog($command, \@argv);

Description

Apache2::SubProcess provides the Perl API for running and communicating with processes spawned from mod_perl handlers.

At the moment it's possible to spawn only external program in a new process. It's possible to provide other interfaces, e.g. executing a sub-routine reference (via B::Deparse) and may be spawn a new program in a thread (since the APR api includes API for spawning threads, e.g. that's how it's running mod_cgi on win32).

API

spawn_proc_prog

Spawn a sub-process and return STD communication pipes:

                               $r->spawn_proc_prog($command);
                               $r->spawn_proc_prog($command, \@argv);
                                 $out_fh                    = $r->spawn_proc_prog($command);
                                 $out_fh                    = $r->spawn_proc_prog($command, \@argv);
                                 ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command);
                                 ($in_fh, $out_fh, $err_fh) = $r->spawn_proc_prog($command, \@argv);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )
arg1: $command ( string )

The command to be $exec()'ed.

opt arg2: \@argv ( ARRAY ref )

A reference to an array of arguments to be passed to the process as the process' ARGV.

ret: ...

In VOID context returns no filehandles (all std streams to the spawned process are closed).

In SCALAR context returns the output filehandle of the spawned process (the in and err std streams to the spawned process are closed).

In LIST context returns the input, outpur and error filehandles of the spawned process.

since: 2.0.00

It's possible to pass environment variables as well, by calling:

  $r->subprocess_env->set($key => $value);

before spawning the subprocess.

There is an issue with reading from the read filehandle ($in_fh)):

A pipe filehandle returned under perlio-disabled Perl needs to call select() if the other end is not fast enough to send the data, since the read is non-blocking.

A pipe filehandle returned under perlio-enabled Perl on the other hand does the select() internally, because it's really a filehandle opened via :APR layer, which internally uses APR to communicate with the pipe. The way APR is implemented Perl's select() cannot be used with it (mainly because select() wants fileno() and APR is a crossplatform implementation which hides the internal datastructure).

Therefore to write a portable code, you want to use select for perlio-disabled Perl and do nothing for perlio-enabled Perl, hence you can use something similar to the read_data() wrapper shown in the Synopsis section.

Several examples appear in the Synopsis section.

spawn_proc_prog() is similar to fork(), but provides you a better framework to communicate with that process and handles the cleanups for you. But that means that just like fork() it gives you a different process, so you don't use the current Perl interpreter in that new process. If you try to use that method or fork to run a high-performance parallel processing you should look elsewhere. You could try Perl threads, but they are very expensive to start if you have a lot of things loaded into memory (since perl_clone() dups almost everything in the perl land, but the opcode tree). In the mod_perl "paradigm" this is much more expensive than fork, since normally most of the time we have lots of perl things loaded into memory. Most likely the best solution here is to offload the job to PPerl or some other daemon, with the only added complexity of communication.

To spawn a completely independent process, which will be able to run after Apache has been shutdown and which won't prevent Apache from restarting (releasing the ports Apache is listening to) call spawn_proc_prog() in a void context and make the script detach and close/reopen its communication streams. For example, spawn a process as:

  use Apache2::SubProcess ();
  $r->spawn_proc_prog ('/path/to/detach_script.pl', $args);

and the /path/to/detach_script.pl contents are:

  # file:detach_script.pl
  #!/usr/bin/perl -w
  use strict;
  use warnings;

  use POSIX 'setsid';

  chdir '/'                or die "Can't chdir to /: $!";
  open STDIN, '/dev/null'  or die "Can't read /dev/null: $!";
  open STDOUT, '+>>', '/path/to/apache/error_log'
      or die "Can't write to /dev/null: $!";
  open STDERR, '>&STDOUT'  or die "Can't dup stdout: $!";
  setsid or die "Can't start a new session: $!";

  # run your code here or call exec to another program

reopening (or closing) the STD streams and called setsid() makes sure that the process is now fully detached from Apache and has a life of its own. chdir() ensures that no partition is tied, in case you need to remount it.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::SubRequest - Perl API for Apache subrequests

  • Synopsis
  • Description
  • API
    • DESTROY
    • internal_redirect
    • internal_redirect_handler
    • lookup_file
    • lookup_method_uri
    • lookup_uri
    • run
  • Unsupported API
    • internal_fast_redirect
    • lookup_dirent
  • See Also
  • Copyright
  • Authors

NAME

Apache2::SubRequest - Perl API for Apache subrequests

Synopsis

  use Apache2::SubRequest ();

  # run internal redirects at once
  $r->internal_redirect($new_uri);
  $r->internal_redirect_handler($new_uri);

  # create internal redirect objects
  $subr = $r->lookup_uri("/foo");
  $subr = $r->lookup_method_uri("GET", "/tmp/bar")
  $subr = $r->lookup_file("/tmp/bar");
  # optionally manipulate the output through main request filters
  $subr = $r->lookup_uri("/foo", $r->output_filters);
  # now run them
  my $rc = $subr->run;

Description

Apache2::SubRequest contains API for creating and running of Apache sub-requests.

Apache2::SubRequest is a sub-class of Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec.

API

Apache2::SubRequest provides the following functions and/or methods:

DESTROY

Free the memory associated with a sub request:

  undef $subr; # but normally don't do that
obj: $subr ( Apache2::SubRequest object|docs::2.0::api::Apache2::SubRequest/Description )

The sub request to finish

ret: no return value
since: 2.0.00

DESTROY is called automatically when $subr goes out of scope.

If you want to free the memory earlier than that (for example if you run several subrequests), you can undef the object as:

  undef $subr;

but never call DESTROY explicitly, since it'll result in ap_destroy_sub_req being called more than once, resulting in multiple brain injuries and certain hair loss.

internal_redirect

Redirect the current request to some other uri internally

  $r->internal_redirect($new_uri);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $new_uri ( string )

The URI to replace the current request with

ret: no return value
since: 2.0.00

In case that you want some other request to be served as the top-level request instead of what the client requested directly, call this method from a handler, and then immediately return Apache2::Const::OK. The client will be unaware the a different request was served to her behind the scenes.

internal_redirect_handler

Identical to internal_redirect|/C_internal_redirect_, plus automatically sets $r->content_type|docs::2.0::api::Apache2::RequestRec/C_content_type_ is of the sub-request to be the same as of the main request, if $r->handler|docs::2.0::api::Apache2::RequestRec/C_handler_ is true.

  $r->internal_redirect_handler($new_uri);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $new_uri ( string )

The URI to replace the current request with.

ret: no return value
since: 2.0.00

This function is designed for things like actions or CGI scripts, when using AddHandler, and you want to preserve the content type across an internal redirect.

lookup_file

Create a subrequest for the given file. This sub request can be inspected to find information about the requested file

  $ret = $r->lookup_file($new_file);
  $ret = $r->lookup_file($new_file, $next_filter);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $new_file ( string )

The file to lookup

opt arg2: $next_filter ( Apache2::Filter|docs::2.0::api::Apache2::Filter )

See $r->lookup_uri|/C_lookup_uri_ for details.

ret: $ret ( Apache2::SubRequest object|docs::2.0::api::Apache2::SubRequest/Description )

The sub request record.

since: 2.0.00

See $r->lookup_uri|/C_lookup_uri_ for further discussion.

lookup_method_uri

Create a sub request for the given URI using a specific method. This sub request can be inspected to find information about the requested URI

  $ret = $r->lookup_method_uri($method, $new_uri);
  $ret = $r->lookup_method_uri($method, $new_uri, $next_filter);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $method ( string )

The method to use in the new sub request (e.g. "GET")

arg2: $new_uri ( string )

The URI to lookup

opt arg3: $next_filter ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

See $r->lookup_uri|/C_lookup_uri_ for details.

ret: $ret ( Apache2::SubRequest object|docs::2.0::api::Apache2::SubRequest/Description )

The sub request record.

since: 2.0.00

See $r->lookup_uri|/C_lookup_uri_ for further discussion.

lookup_uri

Create a sub request from the given URI. This sub request can be inspected to find information about the requested URI.

  $ret = $r->lookup_uri($new_uri);
  $ret = $r->lookup_uri($new_uri, $next_filter);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $new_uri ( string )

The URI to lookup

opt arg2: $next_filter ( Apache2::Filter object|docs::2.0::api::Apache2::Filter )

The first filter the subrequest should pass the data through. If not specified it defaults to the first connection output filter for the main request $r->proto_output_filters|docs::2.0::api::Apache2::RequestRec/C_proto_output_filters_. So if the subrequest sends any output it will be filtered only once. If for example you desire to apply the main request's output filters to the sub-request output as well pass $r->output_filters|docs::2.0::api::Apache2::RequestRec/C_output_filters_ as an argument.

ret: $ret ( Apache2::SubRequest object|docs::2.0::api::Apache2::SubRequest/Description )

The sub request record

since: 2.0.00

Here is an example of a simple subrequest which serves uri /new_uri:

  sub handler {
      my $r = shift;

      my $subr = $r->lookup_uri("/new_uri");
      $sub->run;

      return Apache2::Const::OK;
  }

If let's say you have three request output filters registered to run for the main request:

  PerlOutputFilterHandler MyApache2::SubReqExample::filterA
  PerlOutputFilterHandler MyApache2::SubReqExample::filterB
  PerlOutputFilterHandler MyApache2::SubReqExample::filterC

and you wish to run them all, the code needs to become:

      my $subr = $r->lookup_uri("/new_uri", $r->output_filters);

and if you wish to run them all, but the first one (filterA), the code needs to be adjusted to be:

      my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);

run

Run a sub-request

  $rc = $subr->run();
obj: $subr ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The sub-request (e.g. returned by lookup_uri|/C_lookup_uri_)

ret: $rc ( integer )

The return code of the handler (Apache2::Const::OK, Apache2::Const::DECLINED, etc.)

since: 2.0.00

Unsupported API

Apache2::SubRequest also provides auto-generated Perl interface for a few other methods which aren't tested at the moment and therefore their API is a subject to change. These methods will be finalized later as a need arises. If you want to rely on any of the following methods please contact the the mod_perl development mailing list so we can help each other take the steps necessary to shift the method to an officially supported API.

internal_fast_redirect

META: Autogenerated - needs to be reviewed/completed

Redirect the current request to a sub_req, merging the pools

  $r->internal_fast_redirect($sub_req);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $sub_req ( string )

A subrequest created from this request

ret: no return value
since: 2.0.00

META: httpd-2.0/modules/http/http_request.c declares this function as:

  /* XXX: Is this function is so bogus and fragile that we deep-6 it? */

do we really want to expose it to mod_perl users?

lookup_dirent

META: Autogenerated - needs to be reviewed/completed

Create a sub request for the given apr_dir_read result. This sub request can be inspected to find information about the requested file

  $lr = $r->lookup_dirent($finfo);
  $lr = $r->lookup_dirent($finfo, $subtype);
  $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request

arg1: $finfo ( APR::Finfo object|docs::2.0::api::APR::Finfo )

The apr_dir_read result to lookup

arg2: $subtype ( integer )

What type of subrequest to perform, one of;

  Apache2::SUBREQ_NO_ARGS     ignore r->args and r->path_info
  Apache2::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info
arg3: $next_filter ( integer )

The first filter the sub_request should use. If this is NULL, it defaults to the first filter for the main request

ret: $lr ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The new request record

since: 2.0.00

META: where do we take the apr_dir_read result from?

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::URI - Perl API for manipulating URIs

  • Synopsis
  • Description
  • API
    • construct_server
    • construct_url
    • parse_uri
    • parsed_uri
    • unescape_url
  • See Also
  • Copyright
  • Authors

NAME

Apache2::URI - Perl API for manipulating URIs

Synopsis

  use Apache2::URI ();

  $hostport = $r->construct_server();
  $hostport = $r->construct_server($hostname);
  $hostport = $r->construct_server($hostname, $port);
  $hostport = $r->construct_server($hostname, $port, $pool);

  $url = $r->construct_url();
  $url = $r->construct_url($rel_uri);
  $url = $r->construct_url($rel_uri, $pool);

  $parsed_uri = $r->parse_uri($uri);

  $parsed_uri = $r->parsed_uri();

  $url = join '%20', qw(one two three);
  Apache2::URI::unescape_url($url);

Description

While APR::URI provides a generic API to dissect, adjust and put together any given URI string, Apache2::URI provides an API specific to Apache, by taking the information directly from the $r object. Therefore when manipulating the URI of the current HTTP request usually methods from both classes are used.

API

Apache2::URI provides the following functions and methods:

construct_server

Construct a string made of hostname and port

  $hostport = $r->construct_server();
  $hostport = $r->construct_server($hostname);
  $hostport = $r->construct_server($hostname, $port);
  $hostport = $r->construct_server($hostname, $port, $pool);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request object

opt arg1: $hostname ( string )

The hostname of the server.

If that argument is not passed, $r->get_server_name|docs::2.0::api::Apache2::RequestUtil/C_get_server_name_ is used.

opt arg2: $port ( string )

The port the server is running on.

If that argument is not passed, $r->get_server_port|docs::2.0::api::Apache2::RequestUtil/C_get_server_port_ is used.

opt arg3: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to allocate the string from.

If that argument is not passed, $r->pool|docs::2.0::api::Apache2::RequestRec/C_pool_ is used.

ret: $hostport ( string )

The server's hostport string

since: 2.0.00

Examples:

  • Assuming that:

      $r->get_server_name == "localhost";
  $r->get_server_port == 8001;

    The code:

      $hostport = $r->construct_server();

    returns a string:

      localhost:8001

  • The following code sets the values explicitly:

      $hostport = $r->construct_server("my.example.com", 8888);

    and it returns a string:

      my.example.com:8888

construct_url

Build a fully qualified URL from the uri and information in the request rec:

  $url = $r->construct_url();
  $url = $r->construct_url($rel_uri);
  $url = $r->construct_url($rel_uri, $pool);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request object

opt arg1: $rel_uri ( string )

The path to the requested file (it may include a concatenation of path, query and fragment components).

If that argument is not passed, $r->uri|docs::2.0::api::Apache2::RequestRec/C_uri_ is used.

opt arg2: $pool ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to allocate the URL from

If that argument is not passed, $r->pool|docs::2.0::api::Apache2::RequestRec/C_pool_ is used.

ret: $url ( string )

A fully qualified URL

since: 2.0.00

Examples:

  • Assuming that the request was

      http://localhost.localdomain:8529/test?args

    The code:

      my $url = $r->construct_url;

    returns the string:

      http://localhost.localdomain:8529/test

    notice that the query (args) component is not in the string. You need to append it manually if it's needed.

  • Assuming that the request was

      http://localhost.localdomain:8529/test?args

    The code:

      my $rel_uri = "/foo/bar?tar";
  my $url = $r->construct_url($rel_uri);

    returns the string:

      http://localhost.localdomain:8529/foo/bar?tar

parse_uri

Break apart URI (affecting the current request's uri components)

  $r->parse_uri($uri);
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request object

arg1: $uri ( string )

The uri to break apart

ret: no return value
warning:

This method has several side-effects explained below

since: 2.0.00

This method call has the following side-effects:

  1. sets $r->args|docs::2.0::api::Apache2::RequestRec/C_args_ to the rest after '?' if such exists in the passed $uri, otherwise sets it to undef.

  2. sets $r->uri|docs::2.0::api::Apache2::RequestRec/C_uri_ to the passed $uri without the $r->args|docs::2.0::api::Apache2::RequestRec/C_args_ part.

  3. sets $r->hostname|docs::2.0::api::Apache2::RequestRec/C_hostname_ (if not set already) using the (scheme://host:port) parts of the passed $uri.

parsed_uri

Get the current request's parsed uri object

  my $uri = $r->parsed_uri();
obj: $r ( Apache2::RequestRec object|docs::2.0::api::Apache2::RequestRec )

The current request object

ret: $uri ( APR::URI object|docs::2.0::api::APR::URI )

The parsed uri

since: 2.0.00

This object is suitable for using with APR::URI::rpath|docs::2.0::api::APR::URI/C_rpath_

unescape_url

Unescape URLs

  Apache2::URI::unescape_url($url);
obj: $url ( string )

The URL to unescape

ret: no return value

The argument $url is now unescaped

since: 2.0.00

Example:

  my $url = join '%20', qw(one two three);
  Apache2::URI::unescape_url($url);

$url now contains the string:

  "one two three";

See Also

APR::URI|docs::2.0::api::APR::URI, mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::Util - Perl API for Misc Apache Utility functions

  • Synopsis
  • Description
  • Functions API
    • escape_path
    • ht_time
  • See Also
  • Copyright
  • Authors

NAME

Apache2::Util - Perl API for Misc Apache Utility functions

Synopsis

  use Apache2::Util ();

  # OS escape path
  $escaped_path = Apache2::Util::escape_path($path, "a 'long' file.html");

  # format time as a string
  my $fmt = "%a, %D %H:%M:%S %Z";
  $fmtdate = Apache2::Util::ht_time($r->pool, $r->request_time, $fmt, 0);

Description

Various Apache utilities that don't fit into any other group.

Functions API

Apache2::Util provides the following functions and/or methods:

escape_path

convert an OS path to a URL in an OS dependant way.

  $escaped_path = Apache2::Util::escape_path($path, $p);
  $escaped_path = Apache2::Util::escape_path($path, $p, $partial);
arg1: $path ( string )

The path to convert

arg2: $p ( APR::Pool|docs::2.0::api::APR::Pool )

The pool to allocate from

opt arg3: $partial ( boolean )

if TRUE, assume that the path will be appended to something with a '/' in it (and thus does not prefix "./")

if FALSE it prepends "./" unless $path contains : optionally followed by /.

the default is TRUE

ret: $escaped_path ( string )

The escaped path

since: 2.0.00

ht_time

Convert time from an integer value into a string in a specified format

  $time_str = Apache2::Util::ht_time($p);
  $time_str = Apache2::Util::ht_time($p, $time);
  $time_str = Apache2::Util::ht_time($p, $time, $fmt);
  $time_str = Apache2::Util::ht_time($p, $time, $fmt, $gmt);
arg1: $p ( APR::Pool object|docs::2.0::api::APR::Pool )

The pool to allocate memory from

opt arg2: $time ( number )

The time to convert (e.g., time() or $r->request_time|docs::2.0::api::Apache2::RequestRec/C_request_time_).

If the value is not passed the current time will be used.

opt arg3: $fmt ( string )

The format to use for the conversion, using strftime(3) tokens.

If the value is not passed the default format used is:

  "%a, %d %b %Y %H:%M:%S %Z"
opt arg4: $gmt ( boolean )

The time will be not converted to GMT if FALSE is passed.

If the value is not passed TRUE (do convert) is used as a default.

ret: $time_str (string)

The string that represents the specified time

since: 2.0.00

Examples:

Use current time, the default format and convert to GMT:

  $fmtdate = Apache2::Util::ht_time($r->pool);

Use my time, the default format and convert to GMT:

  my $time = time+100;
  $fmtdate = Apache2::Util::ht_time($r->pool, $time);

Use the time the request has started, custom format and don't convert to GMT:

  my $fmt = "%a, %D %H:%M:%S %Z";
  $fmtdate = Apache2::Util::ht_time($r->pool, $r->request_time, $fmt, 0);

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::compat -- 1.0 backward compatibility functions deprecated in 2.0

  • Synopsis
  • Description
  • Compatibility Functions Colliding with mod_perl 2.0 API
    • Available Overridable Functions
  • Use in CPAN Modules
  • API
  • See Also
  • Copyright
  • Authors

NAME

Apache2::compat -- 1.0 backward compatibility functions deprecated in 2.0

Synopsis

  # either add at the very beginning of startup.pl
  use Apache2::compat;
  # or httpd.conf
  PerlModule Apache2::compat

  # override and restore compat functions colliding with mp2 API
  Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
  my ($local_port, $local_addr) = sockaddr_in($c->local_addr);
  Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');

Description

Apache2::compat provides mod_perl 1.0 compatibility layer and can be used to smooth the transition process to mod_perl 2.0.

It includes functions that have changed their API or were removed in mod_perl 2.0. If your code uses any of those functions, you should load this module at the server startup, and everything should work as it did in 1.0. If it doesn't please report the bug, but before you do that please make sure that your code does work properly under mod_perl 1.0.

However, remember, that it's implemented in pure Perl and not C, therefore its functionality is not optimized and it's the best to try to port your code not to use deprecated functions and stop using the compatibility layer.

Compatibility Functions Colliding with mod_perl 2.0 API

Most of the functions provided by Apache2::compat don't interfere with mod_perl 2.0 API. However there are several functions which have the same name in the mod_perl 1.0 and mod_perl 2.0 API, accept the same number of arguments, but either the arguments themselves aren't the same or the return values are different. For example the mod_perl 1.0 code:

  require Socket;
  my $sockaddr_in = $c->local_addr;
  my ($local_port, $local_addr) = Socket::sockaddr_in($sockaddr_in);

should be adjusted to be:

  require Apache2::Connection;
  require APR::SockAddr;
  my $sockaddr = $c->local_addr;
  my ($local_port, $local_addr) = ($sockaddr->port, $sockaddr->ip_get);

to work under mod_perl 2.0.

As you can see in mod_perl 1.0 API local_addr() was returning a SOCKADDR_IN object (see the Socket perl manpage), in mod_perl 2.0 API it returns an APR::SockAddr|docs::2.0::api::APR::SockAddr object, which is a totally different beast. If Apache2::compat overrides the function local_addr() to be back-compatible with mod_perl 1.0 API. Any code that relies on this function to work as it should under mod_perl 2.0 will be broken. Therefore the solution is not to override local_addr() by default. Instead a special API is provided which overrides colliding functions only when needed and which can be restored when no longer needed. So for example if you have code from mod_perl 1.0:

  my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);

and you aren't ready to port it to to use the mp2 API:

  my ($local_port, $local_addr) = ($c->local_addr->port,
                                   $c->local_addr->ip_get);

you could do the following:

  Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
  my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
  Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');

Notice that you need to restore the API as soon as possible.

Both override_mp2_api() and restore_mp2_api() accept a list of functions to operate on.

Available Overridable Functions

At the moment the following colliding functions are available for overriding:

  • Apache2::RequestRec::notes
  • Apache2::RequestRec::filename
  • Apache2::RequestRec::finfo
  • Apache2::Connection::local_addr
  • Apache2::Connection::remote_addr
  • Apache2::Util::ht_time
  • APR::URI::unparse

Use in CPAN Modules

The short answer: Do not use Apache2::compat in CPAN modules.

The long answer:

Apache2::compat is useful during the mod_perl 1.0 code porting. Though remember that it's implemented in pure Perl. In certain cases it overrides mod_perl 2.0 methods, because their API is very different and doesn't map 1:1 to mod_perl 1.0. So if anything, not under user's control, loads Apache2::compat user's code is forced to use the potentially slower method. Which is quite bad.

Some users may choose to keep using Apache2::compat in production and it may perform just fine. Other users will choose not to use that module, by porting their code to use mod_perl 2.0 API. However it should be users' choice whether to load this module or not and not to be enforced by CPAN modules.

If you port your CPAN modules to work with mod_perl 2.0, you should follow the porting Perl and XS module guidelines.

Users that are stuck with CPAN modules preloading Apache2::compat, can prevent this from happening by adding

  $INC{'Apache2/compat.pm'} = __FILE__;

at the very beginning of their startup.pl. But this will most certainly break the module that needed this module.

API

You should be reading the mod_perl 1.0 API docs for usage of the methods and functions in this package, since what this module is doing is providing a backwards compatibility and it makes no sense to duplicate documentation.

Another important document to read is: Migrating from mod_perl 1.0 to mod_perl 2.0 which covers all mod_perl 1.0 constants, functions and methods that have changed in mod_perl 2.0.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Apache2::porting -- a helper module for mod_perl 1.0 to mod_perl 2.0 porting

  • Synopsis
  • Description
  • Culprits
  • See Also
  • Copyright
  • Authors

NAME

Apache2::porting -- a helper module for mod_perl 1.0 to mod_perl 2.0 porting

Synopsis

  # either add at the very beginning of startup.pl
  use Apache2::porting;

  # or httpd.conf
  PerlModule Apache2::porting
  # now issue requests and look at the error_log file for hints

Description

Apache2::porting helps to port mod_perl 1.0 code to run under mod_perl 2.0. It doesn't provide any back-compatibility functionality, however it knows to trap methods calls that are no longer in the mod_perl 2.0 API and tell what should be used instead if at all. If you attempts to use mod_perl 2.0 methods without first loading the modules that contain them, it will tell you which modules you need to load. Finally if your code tries to load modules that no longer exist in mod_perl 2.0 it'll also tell you what are the modules that should be used instead.

Apache2::porting communicates with users via the error_log file. Everytime it traps a problem, it logs the solution (if it finds one) to the error log file. If you use this module coupled with Apache2::Reload|docs::2.0::api::Apache2::Reload you will be able to port your applications quickly without needing to restart the server on every modification.

It starts to work only when child process start and doesn't work for the code that gets loaded at the server startup. This limitation is explained in the Culprits section.

It relies heavily on ModPerl::MethodLookup|docs::2.0::api::ModPerl::MethodLookup. which can also be used manually to lookup things.

Culprits

Apache2::porting uses the UNIVERSAL::AUTOLOAD function to provide its functionality. However it seems to be impossible to create UNIVERSAL::AUTOLOAD at the server startup, Apache segfaults on restart. Therefore it performs the setting of UNIVERSAL::AUTOLOAD only during the child_init phase, when child processes start. As a result it can't help you with things that get preloaded at the server startup.

If you know how to resolve this problem, please let us know. To reproduce the problem try to use an earlier phase, e.g. PerlPostConfigHandler:

  Apache2::ServerUtil->server->push_handlers(PerlPostConfigHandler => \&porting_autoload);

META: Though there is a better solution at work, which assigns AUTOLOAD for each class separately, instead of using UNIVERSAL. See the discussion on the dev list (hint: search the archive for EazyLife)

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Archive::Tar - module for manipulations of tar archives

  • Object Methods
    • Archive::Tar->new( [$file, $compressed] )
    • $tar->read ( $filename|$handle, $compressed, {opt => 'val'} )
    • $tar->contains_file( $filename )
    • $tar->extract( [@filenames] )
    • $tar->extract_file( $file, [$extract_path] )
    • $tar->list_files( [\@properties] )
    • $tar->get_files( [@filenames] )
    • $tar->get_content( $file )
    • $tar->replace_content( $file, $content )
    • $tar->rename( $file, $new_name )
    • $tar->remove (@filenamelist)
    • $tar->clear
    • $tar->write ( [$file, $compressed, $prefix] )
    • $tar->add_files( @filenamelist )
    • $tar->add_data ( $filename, $data, [$opthashref] )
    • $tar->error( [$BOOL] )
    • $tar->setcwd( $cwd );
    • $bool = $tar->has_io_string
    • $bool = $tar->has_perlio
  • Class Methods
    • Archive::Tar->create_archive($file, $compression, @filelist)
    • Archive::Tar->list_archive ($file, $compressed, [\@properties])
    • Archive::Tar->extract_archive ($file, $gzip)
    • Archive::Tar->can_handle_compressed_files
  • GLOBAL VARIABLES
    • $Archive::Tar::FOLLOW_SYMLINK
    • $Archive::Tar::CHOWN
    • $Archive::Tar::CHMOD
    • $Archive::Tar::DO_NOT_USE_PREFIX
    • $Archive::Tar::DEBUG
    • $Archive::Tar::WARN
    • $Archive::Tar::error
    • $Archive::Tar::HAS_PERLIO
    • $Archive::Tar::HAS_IO_STRING
  • FAQ
  • TODO
  • SEE ALSO
  • AUTHOR
  • ACKNOWLEDGEMENTS
  • COPYRIGHT

NAME

Archive::Tar - module for manipulations of tar archives

SYNOPSIS

    use Archive::Tar;
    my $tar = Archive::Tar->new;

    $tar->read('origin.tgz',1);
    $tar->extract();

    $tar->add_files('file/foo.pl', 'docs/README');
    $tar->add_data('file/baz.txt', 'This is the contents now');

    $tar->rename('oldname', 'new/file/name');

    $tar->write('files.tar');

DESCRIPTION

Archive::Tar provides an object oriented mechanism for handling tar files. It provides class methods for quick and easy files handling while also allowing for the creation of tar file objects for custom manipulation. If you have the IO::Zlib module installed, Archive::Tar will also support compressed or gzipped tar files.

An object of class Archive::Tar represents a .tar(.gz) archive full of files and things.

Object Methods

Archive::Tar->new( [$file, $compressed] )

Returns a new Tar object. If given any arguments, new() calls the read() method automatically, passing on the arguments provided to the read() method.

If new() is invoked with arguments and the read() method fails for any reason, new() returns undef.

$tar->read ( $filename|$handle, $compressed, {opt => 'val'} )

Read the given tar file into memory. The first argument can either be the name of a file or a reference to an already open filehandle (or an IO::Zlib object if it's compressed) The second argument indicates whether the file referenced by the first argument is compressed.

The read will replace any previous content in $tar!

The second argument may be considered optional if IO::Zlib is installed, since it will transparently Do The Right Thing. Archive::Tar will warn if you try to pass a compressed file if IO::Zlib is not available and simply return.

Note that you can currently not pass a gzip compressed filehandle, which is not opened with IO::Zlib, nor a string containing the full archive information (either compressed or uncompressed). These are worth while features, but not currently implemented. See the TODO section.

The third argument can be a hash reference with options. Note that all options are case-sensitive.

limit

Do not read more than limit files. This is useful if you have very big archives, and are only interested in the first few files.

extract

If set to true, immediately extract entries when reading them. This gives you the same memory break as the extract_archive function. Note however that entries will not be read into memory, but written straight to disk.

All files are stored internally as Archive::Tar::File objects. Please consult the the Archive::Tar::File manpage documentation for details.

Returns the number of files read in scalar context, and a list of Archive::Tar::File objects in list context.

$tar->contains_file( $filename )

Check if the archive contains a certain file. It will return true if the file is in the archive, false otherwise.

Note however, that this function does an exact match using eq on the full path. So it cannot compensate for case-insensitive file- systems or compare 2 paths to see if they would point to the same underlying file.

$tar->extract( [@filenames] )

Write files whose names are equivalent to any of the names in @filenames to disk, creating subdirectories as necessary. This might not work too well under VMS. Under MacPerl, the file's modification time will be converted to the MacOS zero of time, and appropriate conversions will be done to the path. However, the length of each element of the path is not inspected to see whether it's longer than MacOS currently allows (32 characters).

If extract is called without a list of file names, the entire contents of the archive are extracted.

Returns a list of filenames extracted.

$tar->extract_file( $file, [$extract_path] )

Write an entry, whose name is equivalent to the file name provided to disk. Optionally takes a second parameter, which is the full (unix) path (including filename) the entry will be written to.

For example:

    $tar->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );

    $tar->extract_file( $at_file_object,   'name/i/want/to/give/it' );

Returns true on success, false on failure.

$tar->list_files( [\@properties] )

Returns a list of the names of all the files in the archive.

If list_files() is passed an array reference as its first argument it returns a list of hash references containing the requested properties of each file. The following list of properties is supported: name, size, mtime (last modified date), mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix.

Passing an array reference containing only one element, 'name', is special cased to return a list of names rather than a list of hash references, making it equivalent to calling list_files without arguments.

$tar->get_files( [@filenames] )

Returns the Archive::Tar::File objects matching the filenames provided. If no filename list was passed, all Archive::Tar::File objects in the current Tar object are returned.

Please refer to the Archive::Tar::File documentation on how to handle these objects.

$tar->get_content( $file )

Return the content of the named file.

$tar->replace_content( $file, $content )

Make the string $content be the content for the file named $file.

$tar->rename( $file, $new_name )

Rename the file of the in-memory archive to $new_name.

Note that you must specify a Unix path for $new_name, since per tar standard, all files in the archive must be Unix paths.

Returns true on success and false on failure.

$tar->remove (@filenamelist)

Removes any entries with names matching any of the given filenames from the in-memory archive. Returns a list of Archive::Tar::File objects that remain.

$tar->clear

clear clears the current in-memory archive. This effectively gives you a 'blank' object, ready to be filled again. Note that clear only has effect on the object, not the underlying tarfile.

$tar->write ( [$file, $compressed, $prefix] )

Write the in-memory archive to disk. The first argument can either be the name of a file or a reference to an already open filehandle (a GLOB reference). If the second argument is true, the module will use IO::Zlib to write the file in a compressed format. If IO::Zlib is not available, the write method will fail and return.

Note that when you pass in a filehandle, the compression argument is ignored, as all files are printed verbatim to your filehandle. If you wish to enable compression with filehandles, use an IO::Zlib filehandle instead.

Specific levels of compression can be chosen by passing the values 2 through 9 as the second parameter.

The third argument is an optional prefix. All files will be tucked away in the directory you specify as prefix. So if you have files 'a' and 'b' in your archive, and you specify 'foo' as prefix, they will be written to the archive as 'foo/a' and 'foo/b'.

If no arguments are given, write returns the entire formatted archive as a string, which could be useful if you'd like to stuff the archive into a socket or a pipe to gzip or something.

$tar->add_files( @filenamelist )

Takes a list of filenames and adds them to the in-memory archive.

The path to the file is automatically converted to a Unix like equivalent for use in the archive, and, if on MacOS, the file's modification time is converted from the MacOS epoch to the Unix epoch. So tar archives created on MacOS with Archive::Tar can be read both with tar on Unix and applications like suntar or Stuffit Expander on MacOS.

Be aware that the file's type/creator and resource fork will be lost, which is usually what you want in cross-platform archives.

Returns a list of Archive::Tar::File objects that were just added.

$tar->add_data ( $filename, $data, [$opthashref] )

Takes a filename, a scalar full of data and optionally a reference to a hash with specific options.

Will add a file to the in-memory archive, with name $filename and content $data. Specific properties can be set using $opthashref. The following list of properties is supported: name, size, mtime (last modified date), mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type. (On MacOS, the file's path and modification times are converted to Unix equivalents.)

Valid values for the file type are the following constants defined in Archive::Tar::Constants:

FILE

Regular file.

HARDLINK
SYMLINK

Hard and symbolic ("soft") links; linkname should specify target.

CHARDEV
BLOCKDEV

Character and block devices. devmajor and devminor should specify the major and minor device numbers.

DIR

Directory.

FIFO

FIFO (named pipe).

SOCKET

Socket.

Returns the Archive::Tar::File object that was just added, or undef on failure.

$tar->error( [$BOOL] )

Returns the current errorstring (usually, the last error reported). If a true value was specified, it will give the Carp::longmess equivalent of the error, in effect giving you a stacktrace.

For backwards compatibility, this error is also available as $Archive::Tar::error although it is much recommended you use the method call instead.

$tar->setcwd( $cwd );

Archive::Tar needs to know the current directory, and it will run Cwd::cwd() every time it extracts a relative entry from the tarfile and saves it in the file system. (As of version 1.30, however, Archive::Tar will use the speed optimization described below automatically, so it's only relevant if you're using extract_file()).

Since Archive::Tar doesn't change the current directory internally while it is extracting the items in a tarball, all calls to Cwd::cwd() can be avoided if we can guarantee that the current directory doesn't get changed externally.

To use this performance boost, set the current directory via

    use Cwd;
    $tar->setcwd( cwd() );

once before calling a function like extract_file and Archive::Tar will use the current directory setting from then on and won't call Cwd::cwd() internally.

To switch back to the default behaviour, use

    $tar->setcwd( undef );

and Archive::Tar will call Cwd::cwd() internally again.

If you're using Archive::Tar's exract() method, setcwd() will be called for you.

$bool = $tar->has_io_string

Returns true if we currently have IO::String support loaded.

Either IO::String or perlio support is needed to support writing stringified archives. Currently, perlio is the preferred method, if available.

See the GLOBAL VARIABLES section to see how to change this preference.

$bool = $tar->has_perlio

Returns true if we currently have perlio support loaded.

This requires perl-5.8 or higher, compiled with perlio

Either IO::String or perlio support is needed to support writing stringified archives. Currently, perlio is the preferred method, if available.

See the GLOBAL VARIABLES section to see how to change this preference.

Class Methods

Archive::Tar->create_archive($file, $compression, @filelist)

Creates a tar file from the list of files provided. The first argument can either be the name of the tar file to create or a reference to an open file handle (e.g. a GLOB reference).

The second argument specifies the level of compression to be used, if any. Compression of tar files requires the installation of the IO::Zlib module. Specific levels of compression may be requested by passing a value between 2 and 9 as the second argument. Any other value evaluating as true will result in the default compression level being used.

Note that when you pass in a filehandle, the compression argument is ignored, as all files are printed verbatim to your filehandle. If you wish to enable compression with filehandles, use an IO::Zlib filehandle instead.

The remaining arguments list the files to be included in the tar file. These files must all exist. Any files which don't exist or can't be read are silently ignored.

If the archive creation fails for any reason, create_archive will return false. Please use the error method to find the cause of the failure.

Note that this method does not write on the fly as it were; it still reads all the files into memory before writing out the archive. Consult the FAQ below if this is a problem.

Archive::Tar->list_archive ($file, $compressed, [\@properties])

Returns a list of the names of all the files in the archive. The first argument can either be the name of the tar file to list or a reference to an open file handle (e.g. a GLOB reference).

If list_archive() is passed an array reference as its third argument it returns a list of hash references containing the requested properties of each file. The following list of properties is supported: full_path, name, size, mtime (last modified date), mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix.

See Archive::Tar::File for details about supported properties.

Passing an array reference containing only one element, 'name', is special cased to return a list of names rather than a list of hash references.

Archive::Tar->extract_archive ($file, $gzip)

Extracts the contents of the tar file. The first argument can either be the name of the tar file to create or a reference to an open file handle (e.g. a GLOB reference). All relative paths in the tar file will be created underneath the current working directory.

extract_archive will return a list of files it extracted. If the archive extraction fails for any reason, extract_archive will return false. Please use the error method to find the cause of the failure.

Archive::Tar->can_handle_compressed_files

A simple checking routine, which will return true if Archive::Tar is able to uncompress compressed archives on the fly with IO::Zlib, or false if IO::Zlib is not installed.

You can use this as a shortcut to determine whether Archive::Tar will do what you think before passing compressed archives to its read method.

GLOBAL VARIABLES

$Archive::Tar::FOLLOW_SYMLINK

Set this variable to 1 to make Archive::Tar effectively make a copy of the file when extracting. Default is 0, which means the symlink stays intact. Of course, you will have to pack the file linked to as well.

This option is checked when you write out the tarfile using write or create_archive.

This works just like /bin/tar's -h option.

$Archive::Tar::CHOWN

By default, Archive::Tar will try to chown your files if it is able to. In some cases, this may not be desired. In that case, set this variable to 0 to disable chown-ing, even if it were possible.

The default is 1.

$Archive::Tar::CHMOD

By default, Archive::Tar will try to chmod your files to whatever mode was specified for the particular file in the archive. In some cases, this may not be desired. In that case, set this variable to 0 to disable chmod-ing.

The default is 1.

$Archive::Tar::DO_NOT_USE_PREFIX

By default, Archive::Tar will try to put paths that are over 100 characters in the prefix field of your tar header, as defined per POSIX-standard. However, some (older) tar programs do not implement this spec. To retain compatibility with these older or non-POSIX compliant versions, you can set the $DO_NOT_USE_PREFIX variable to a true value, and Archive::Tar will use an alternate way of dealing with paths over 100 characters by using the GNU Extended Header feature.

Note that clients who do not support the GNU Extended Header feature will not be able to read these archives. Such clients include tars on Solaris, Irix and AIX.

The default is 0.

$Archive::Tar::DEBUG

Set this variable to 1 to always get the Carp::longmess output of the warnings, instead of the regular carp. This is the same message you would get by doing:

    $tar->error(1);

Defaults to 0.

$Archive::Tar::WARN

Set this variable to 0 if you do not want any warnings printed. Personally I recommend against doing this, but people asked for the option. Also, be advised that this is of course not threadsafe.

Defaults to 1.

$Archive::Tar::error

Holds the last reported error. Kept for historical reasons, but its use is very much discouraged. Use the error() method instead:

    warn $tar->error unless $tar->extract;

$Archive::Tar::HAS_PERLIO

This variable holds a boolean indicating if we currently have perlio support loaded. This will be enabled for any perl greater than 5.8 compiled with perlio.

If you feel strongly about disabling it, set this variable to false. Note that you will then need IO::String installed to support writing stringified archives.

Don't change this variable unless you really know what you're doing.

$Archive::Tar::HAS_IO_STRING

This variable holds a boolean indicating if we currently have IO::String support loaded. This will be enabled for any perl that has a loadable IO::String module.

If you feel strongly about disabling it, set this variable to false. Note that you will then need perlio support from your perl to be able to write stringified archives.

Don't change this variable unless you really know what you're doing.

FAQ

What's the minimum perl version required to run Archive::Tar?

You will need perl version 5.005_03 or newer.

Isn't Archive::Tar slow?

Yes it is. It's pure perl, so it's a lot slower then your /bin/tar However, it's very portable. If speed is an issue, consider using /bin/tar instead.

Isn't Archive::Tar heavier on memory than /bin/tar?

Yes it is, see previous answer. Since Compress::Zlib and therefore IO::Zlib doesn't support seek on their filehandles, there is little choice but to read the archive into memory. This is ok if you want to do in-memory manipulation of the archive. If you just want to extract, use the extract_archive class method instead. It will optimize and write to disk immediately.

Can't you lazy-load data instead?

No, not easily. See previous question.

How much memory will an X kb tar file need?

Probably more than X kb, since it will all be read into memory. If this is a problem, and you don't need to do in memory manipulation of the archive, consider using /bin/tar instead.

What do you do with unsupported filetypes in an archive?

Unix has a few filetypes that aren't supported on other platforms, like Win32. If we encounter a hardlink or symlink we'll just try to make a copy of the original file, rather than throwing an error.

This does require you to read the entire archive in to memory first, since otherwise we wouldn't know what data to fill the copy with. (This means that you cannot use the class methods on archives that have incompatible filetypes and still expect things to work).

For other filetypes, like chardevs and blockdevs we'll warn that the extraction of this particular item didn't work.

I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!

By default, Archive::Tar is in a completely POSIX-compatible mode, which uses the POSIX-specification of tar to store files. For paths greather than 100 characters, this is done using the POSIX header prefix. Non-POSIX-compatible clients may not support this part of the specification, and may only support the GNU Extended Header functionality. To facilitate those clients, you can set the $Archive::Tar::DO_NOT_USE_PREFIX variable to true. See the GLOBAL VARIABLES section for details on this variable.

How do I extract only files that have property X from an archive?

Sometimes, you might not wish to extract a complete archive, just the files that are relevant to you, based on some criteria.

You can do this by filtering a list of Archive::Tar::File objects based on your criteria. For example, to extract only files that have the string foo in their title, you would use:

    $tar->extract(
        grep { $_->full_path =~ /foo/ } $tar->get_files
    );

This way, you can filter on any attribute of the files in the archive. Consult the Archive::Tar::File documentation on how to use these objects.

How do I access .tar.Z files?

The Archive::Tar module can optionally use Compress::Zlib (via the IO::Zlib module) to access tar files that have been compressed with gzip. Unfortunately tar files compressed with the Unix compress utility cannot be read by Compress::Zlib and so cannot be directly accesses by Archive::Tar.

If the uncompress or gunzip programs are available, you can use one of these workarounds to read .tar.Z files from Archive::Tar

Firstly with uncompress

    use Archive::Tar;

    open F, "uncompress -c $filename |";
    my $tar = Archive::Tar->new(*F);
    ...

and this with gunzip

    use Archive::Tar;

    open F, "gunzip -c $filename |";
    my $tar = Archive::Tar->new(*F);
    ...

Similarly, if the compress program is available, you can use this to write a .tar.Z file

    use Archive::Tar;
    use IO::File;

    my $fh = new IO::File "| compress -c >$filename";
    my $tar = Archive::Tar->new();
    ...
    $tar->write($fh);
    $fh->close ;

TODO

Check if passed in handles are open for read/write

Currently I don't know of any portable pure perl way to do this. Suggestions welcome.

Allow archives to be passed in as string

Currently, we only allow opened filehandles or filenames, but not strings. The internals would need some reworking to facilitate stringified archives.

Facilitate processing an opened filehandle of a compressed archive

Currently, we only support this if the filehandle is an IO::Zlib object. Environments, like apache, will present you with an opened filehandle to an uploaded file, which might be a compressed archive.

SEE ALSO

The GNU tar specification

http://www.gnu.org/software/tar/manual/tar.html

The PAX format specication

The specifcation which tar derives from; http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html

A comparison of GNU and POSIX tar standards; http://www.delorie.com/gnu/docs/tar/tar_114.html
GNU tar intends to switch to POSIX compatibility

GNU Tar authors have expressed their intention to become completely POSIX-compatible; http://www.gnu.org/software/tar/manual/html_node/Formats.html

A Comparison between various tar implementations

Lists known issues and incompatibilities; http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

ACKNOWLEDGEMENTS

Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney and especially Andrew Savige for their help and suggestions.

COPYRIGHT

This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.


Archive::Tar::File - a subclass for in-memory extracted file from Archive::Tar

    • Accessors
  • Methods
    • new( file => $path )
    • new( data => $path, $data, $opt )
    • new( chunk => $chunk )
    • full_path
    • validate
    • has_content
    • get_content
    • get_content_by_ref
    • replace_content( $content )
    • rename( $new_name )
  • Convenience methods

NAME

Archive::Tar::File - a subclass for in-memory extracted file from Archive::Tar

SYNOPSIS

    my @items = $tar->get_files;

    print $_->name, ' ', $_->size, "\n" for @items;

    print $object->get_content;
    $object->replace_content('new content');

    $object->rename( 'new/full/path/to/file.c' );

DESCRIPTION

Archive::Tar::Files provides a neat little object layer for in-memory extracted files. It's mostly used internally in Archive::Tar to tidy up the code, but there's no reason users shouldn't use this API as well.

Accessors

A lot of the methods in this package are accessors to the various fields in the tar header:

name

The file's name

mode

The file's mode

uid

The user id owning the file

gid

The group id owning the file

size

File size in bytes

mtime

Modification time. Adjusted to mac-time on MacOS if required

chksum

Checksum field for the tar header

type

File type -- numeric, but comparable to exported constants -- see Archive::Tar's documentation

linkname

If the file is a symlink, the file it's pointing to

magic

Tar magic string -- not useful for most users

version

Tar version string -- not useful for most users

uname

The user name that owns the file

gname

The group name that owns the file

devmajor

Device major number in case of a special file

devminor

Device minor number in case of a special file

prefix

Any directory to prefix to the extraction path, if any

raw

Raw tar header -- not useful for most users

Methods

new( file => $path )

Returns a new Archive::Tar::File object from an existing file.

Returns undef on failure.

new( data => $path, $data, $opt )

Returns a new Archive::Tar::File object from data.

$path defines the file name (which need not exist), $data the file contents, and $opt is a reference to a hash of attributes which may be used to override the default attributes (fields in the tar header), which are described above in the Accessors section.

Returns undef on failure.

new( chunk => $chunk )

Returns a new Archive::Tar::File object from a raw 512-byte tar archive chunk.

Returns undef on failure.

full_path

Returns the full path from the tar header; this is basically a concatenation of the prefix and name fields.

validate

Done by Archive::Tar internally when reading the tar file: validate the header against the checksum to ensure integer tar file.

Returns true on success, false on failure

has_content

Returns a boolean to indicate whether the current object has content. Some special files like directories and so on never will have any content. This method is mainly to make sure you don't get warnings for using uninitialized values when looking at an object's content.

get_content

Returns the current content for the in-memory file

get_content_by_ref

Returns the current content for the in-memory file as a scalar reference. Normal users won't need this, but it will save memory if you are dealing with very large data files in your tar archive, since it will pass the contents by reference, rather than make a copy of it first.

replace_content( $content )

Replace the current content of the file with the new content. This only affects the in-memory archive, not the on-disk version until you write it.

Returns true on success, false on failure.

rename( $new_name )

Rename the current file to $new_name.

Note that you must specify a Unix path for $new_name, since per tar standard, all files in the archive must be Unix paths.

Returns true on success and false on failure.

Convenience methods

To quickly check the type of a Archive::Tar::File object, you can use the following methods:

is_file

Returns true if the file is of type file

is_dir

Returns true if the file is of type dir

is_hardlink

Returns true if the file is of type hardlink

is_symlink

Returns true if the file is of type symlink

is_chardev

Returns true if the file is of type chardev

is_blockdev

Returns true if the file is of type blockdev

is_fifo

Returns true if the file is of type fifo

is_socket

Returns true if the file is of type socket

is_longlink

Returns true if the file is of type LongLink. Should not happen after a successful read.

is_label

Returns true if the file is of type Label. Should not happen after a successful read.

is_unknown

Returns true if the file type is unknown


Archive::Zip - Provide an interface to ZIP archive files.

  • FILE NAMING
  • OBJECT MODEL
    • Overview
    • Inheritance
  • EXPORTS
  • ERROR CODES
  • COMPRESSION
    • Compression Levels
  • Archive::Zip methods
    • Constructor
    • Zip Archive Utility Methods
    • Zip Archive Accessors
    • Zip Archive Member Operations
    • Zip Archive I/O operations
    • Zip Archive Tree operations
  • MEMBER OPERATIONS
    • Member Class Methods
    • Member Simple accessors
    • Low-level member data reading
  • Archive::Zip::FileMember methods
  • Archive::Zip::ZipFileMember methods
  • REQUIRED MODULES
  • AUTHOR
  • CURRENT MAINTAINER
  • COPYRIGHT
  • SEE ALSO

NAME

Archive::Zip - Provide an interface to ZIP archive files.

SYNOPSIS

   use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
   my $zip = Archive::Zip->new();
   my $member = $zip->addDirectory( 'dirname/' );
   $member = $zip->addString( 'This is a test', 'stringMember.txt' );
   $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
   $member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
   die 'write error' unless $zip->writeToFileNamed( 'someZip.zip' ) == AZ_OK;
   $zip = Archive::Zip->new();
   die 'read error' unless $zip->read( 'someZip.zip' ) == AZ_OK;
   $member = $zip->memberNamed( 'stringMember.txt' );
   $member->desiredCompressionMethod( COMPRESSION_STORED );
   die 'write error' unless $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK;

DESCRIPTION

The Archive::Zip module allows a Perl program to create, manipulate, read, and write Zip archive files. Zip archives can be created, or you can read from existing zip files. Once created, they can be written to files, streams, or strings. Members can be added, removed, extracted, replaced, rearranged, and enumerated. They can also be renamed or have their dates, comments, or other attributes queried or modified. Their data can be compressed or uncompressed as needed. Members can be created from members in existing Zip files, or from existing directories, files, or strings. This module uses the Compress::Zlib library to read and write the compressed streams inside the files.

FILE NAMING

Regardless of what your local file system uses for file naming, names in a Zip file are in Unix format (forward slashes (/) separating directory names, etc.). Archive::Zip tries to be consistent with file naming conventions, and will translate back and forth between native and Zip file names. However, it can't guess which format names are in. So two rules control what kind of file name you must pass various routines:

Names of files are in local format.

File::Spec and File::Basename are used for various file operations. When you're referring to a file on your system, use its file naming conventions.

Names of archive members are in Unix format.

This applies to every method that refers to an archive member, or provides a name for new archive members. The extract() methods that can take one or two names will convert from local to zip names if you call them with a single name.

OBJECT MODEL

Overview

Archive::Zip::Archive objects are what you ordinarily deal with. These maintain the structure of a zip file, without necessarily holding data. When a zip is read from a disk file, the (possibly compressed) data still lives in the file, not in memory. Archive members hold information about the individual members, but not (usually) the actual member data. When the zip is written to a (different) file, the member data is compressed or copied as needed. It is possible to make archive members whose data is held in a string in memory, but this is not done when a zip file is read. Directory members don't have any data.

Inheritance

  Exporter
   Archive::Zip                            Common base class, has defs.
       Archive::Zip::Archive               A Zip archive.
       Archive::Zip::Member                Abstract superclass for all members.
           Archive::Zip::StringMember      Member made from a string
           Archive::Zip::FileMember        Member made from an external file
               Archive::Zip::ZipFileMember Member that lives in a zip file
               Archive::Zip::NewFileMember Member whose data is in a file
           Archive::Zip::DirectoryMember   Member that is a directory

EXPORTS

:CONSTANTS

Exports the following constants: FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST COMPRESSION_LEVEL_BEST_COMPRESSION

:MISC_CONSTANTS

Exports the following constants (only necessary for extending the module): FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED COMPRESSION_DEFLATED_ENHANCED COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED

:ERROR_CODES

Explained below. Returned from most methods. AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR

ERROR CODES

Many of the methods in Archive::Zip return error codes. These are implemented as inline subroutines, using the use constant pragma. They can be imported into your namespace using the :ERROR_CODES tag:

  use Archive::Zip qw( :ERROR_CODES );
  ...
  die "whoops!" unless $zip->read( 'myfile.zip' ) == AZ_OK;
AZ_OK (0)

Everything is fine.

AZ_STREAM_END (1)

The read stream (or central directory) ended normally.

AZ_ERROR (2)

There was some generic kind of error.

AZ_FORMAT_ERROR (3)

There is a format error in a ZIP file being read.

AZ_IO_ERROR (4)

There was an IO error.

COMPRESSION

Archive::Zip allows each member of a ZIP file to be compressed (using the Deflate algorithm) or uncompressed. Other compression algorithms that some versions of ZIP have been able to produce are not supported. Each member has two compression methods: the one it's stored as (this is always COMPRESSION_STORED for string and external file members), and the one you desire for the member in the zip file. These can be different, of course, so you can make a zip member that is not compressed out of one that is, and vice versa. You can inquire about the current compression and set the desired compression method:

  my $member = $zip->memberNamed( 'xyz.txt' );
  $member->compressionMethod();    # return current compression
  # set to read uncompressed
  $member->desiredCompressionMethod( COMPRESSION_STORED );
  # set to read compressed
  $member->desiredCompressionMethod( COMPRESSION_DEFLATED );

There are two different compression methods:

COMPRESSION_STORED

file is stored (no compression)

COMPRESSION_DEFLATED

file is Deflated

Compression Levels

If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can choose different compression levels. This choice may affect the speed of compression and decompression, as well as the size of the compressed member data.

  $member->desiredCompressionLevel( 9 );

The levels given can be:

  1. or COMPRESSION_LEVEL_NONE

    This is the same as saying

      $member->desiredCompressionMethod( COMPRESSION_STORED );
  2. .. 9

    1 gives the best speed and worst compression, and 9 gives the best compression and worst speed.

    3. COMPRESSION_LEVEL_FASTEST

    This is a synonym for level 1.

    COMPRESSION_LEVEL_BEST_COMPRESSION

    This is a synonym for level 9.

    COMPRESSION_LEVEL_DEFAULT

    This gives a good compromise between speed and compression, and is currently equivalent to 6 (this is in the zlib code). This is the level that will be used if not specified.

Archive::Zip methods

The Archive::Zip class (and its invisible subclass Archive::Zip::Archive) implement generic zip file functionality. Creating a new Archive::Zip object actually makes an Archive::Zip::Archive object, but you don't have to worry about this unless you're subclassing.

Constructor

new( [$fileName] )

Make a new, empty zip archive.

    my $zip = Archive::Zip->new();

If an additional argument is passed, new() will call read() to read the contents of an archive:

    my $zip = Archive::Zip->new( 'xyz.zip' );

If a filename argument is passed and the read fails for any reason, new will return undef. For this reason, it may be better to call read separately.

Zip Archive Utility Methods

These Archive::Zip methods may be called as functions or as object methods. Do not call them as class methods:

    $zip = Archive::Zip->new();
    $crc = Archive::Zip::computeCRC32( 'ghijkl' );    # OK
    $crc = $zip->computeCRC32( 'ghijkl' );            # also OK
    $crc = Archive::Zip->computeCRC32( 'ghijkl' );    # NOT OK
Archive::Zip::computeCRC32( $string [, $crc] )

This is a utility function that uses the Compress::Zlib CRC routine to compute a CRC-32. You can get the CRC of a string:

    $crc = Archive::Zip::computeCRC32( $string );

Or you can compute the running CRC:

    $crc = 0;
    $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
    $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
Archive::Zip::setChunkSize( $number )

Report or change chunk size used for reading and writing. This can make big differences in dealing with large files. Currently, this defaults to 32K. This also changes the chunk size used for Compress::Zlib. You must call setChunkSize() before reading or writing. This is not exportable, so you must call it like:

    Archive::Zip::setChunkSize( 4096 );

or as a method on a zip (though this is a global setting). Returns old chunk size.

Archive::Zip::chunkSize()

Returns the current chunk size:

    my $chunkSize = Archive::Zip::chunkSize();
Archive::Zip::setErrorHandler( \&subroutine )

Change the subroutine called with error strings. This defaults to \&Carp::carp, but you may want to change it to get the error strings. This is not exportable, so you must call it like:

    Archive::Zip::setErrorHandler( \&myErrorHandler );

If myErrorHandler is undef, resets handler to default. Returns old error handler. Note that if you call Carp::carp or a similar routine or if you're chaining to the default error handler from your error handler, you may want to increment the number of caller levels that are skipped (do not just set it to a number):

    $Carp::CarpLevel++;
Archive::Zip::tempFile( [$tmpdir] )

Create a uniquely named temp file. It will be returned open for read/write. If $tmpdir is given, it is used as the name of a directory to create the file in. If not given, creates the file using File::Spec::tmpdir(). Generally, you can override this choice using the

    $ENV{TMPDIR}

environment variable. But see the File::Spec documentation for your system. Note that on many systems, if you're running in taint mode, then you must make sure that $ENV{TMPDIR} is untainted for it to be used. Will NOT create $tmpdir if it doesn't exist (this is a change from prior versions!). Returns file handle and name:

    my ($fh, $name) = Archive::Zip::tempFile();
    my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
    my $fh = Archive::Zip::tempFile();  # if you don't need the name

Zip Archive Accessors

members()

Return a copy of the members array

    my @members = $zip->members();
numberOfMembers()

Return the number of members I have

memberNames()

Return a list of the (internal) file names of the zip members

memberNamed( $string )

Return ref to member whose filename equals given filename or undef. $string must be in Zip (Unix) filename format.

membersMatching( $regex )

Return array of members whose filenames match given regular expression in list context. Returns number of matching members in scalar context.

    my @textFileMembers = $zip->membersMatching( '.*\.txt' );
    # or
    my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
diskNumber()

Return the disk that I start on. Not used for writing zips, but might be interesting if you read a zip in. This should be 0, as Archive::Zip does not handle multi-volume archives.

diskNumberWithStartOfCentralDirectory()

Return the disk number that holds the beginning of the central directory. Not used for writing zips, but might be interesting if you read a zip in. This should be 0, as Archive::Zip does not handle multi-volume archives.

numberOfCentralDirectoriesOnThisDisk()

Return the number of CD structures in the zipfile last read in. Not used for writing zips, but might be interesting if you read a zip in.

numberOfCentralDirectories()

Return the number of CD structures in the zipfile last read in. Not used for writing zips, but might be interesting if you read a zip in.

centralDirectorySize()

Returns central directory size, as read from an external zip file. Not used for writing zips, but might be interesting if you read a zip in.

centralDirectoryOffsetWRTStartingDiskNumber()

Returns the offset into the zip file where the CD begins. Not used for writing zips, but might be interesting if you read a zip in.

zipfileComment( [$string] )

Get or set the zipfile comment. Returns the old comment.

    print $zip->zipfileComment();
    $zip->zipfileComment( 'New Comment' );
eocdOffset()

Returns the (unexpected) number of bytes between where the EOCD was found and where it expected to be. This is normally 0, but would be positive if something (a virus, perhaps) had added bytes somewhere before the EOCD. Not used for writing zips, but might be interesting if you read a zip in. Here is an example of how you can diagnose this:

  my $zip = Archive::Zip->new('somefile.zip');
  if ($zip->eocdOffset())
  {
    warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
  }

The eocdOffset() is used to adjust the starting position of member headers, if necessary.

fileName()

Returns the name of the file last read from. If nothing has been read yet, returns an empty string; if read from a file handle, returns the handle in string form.

Zip Archive Member Operations

Various operations on a zip file modify members. When a member is passed as an argument, you can either use a reference to the member itself, or the name of a member. Of course, using the name requires that names be unique within a zip (this is not enforced).

removeMember( $memberOrName )

Remove and return the given member, or match its name and remove it. Returns undef if member or name doesn't exist in this Zip. No-op if member does not belong to this zip.

replaceMember( $memberOrName, $newMember )

Remove and return the given member, or match its name and remove it. Replace with new member. Returns undef if member or name doesn't exist in this Zip, or if $newMember is undefined.

It is an (undiagnosed) error to provide a $newMember that is a member of the zip being modified.

    my $member1 = $zip->removeMember( 'xyz' );
    my $member2 = $zip->replaceMember( 'abc', $member1 );
    # now, $member2 (named 'abc') is not in $zip,
    # and $member1 (named 'xyz') is, having taken $member2's place.
extractMember( $memberOrName [, $extractedName ] )

Extract the given member, or match its name and extract it. Returns undef if member doesn't exist in this Zip. If optional second arg is given, use it as the name of the extracted member. Otherwise, the internal filename of the member is used as the name of the extracted file or directory. If you pass $extractedName, it should be in the local file system's format. All necessary directories will be created. Returns AZ_OK on success.

extractMemberWithoutPaths( $memberOrName [, $extractedName ] )

Extract the given member, or match its name and extract it. Does not use path information (extracts into the current directory). Returns undef if member doesn't exist in this Zip. If optional second arg is given, use it as the name of the extracted member (its paths will be deleted too). Otherwise, the internal filename of the member (minus paths) is used as the name of the extracted file or directory. Returns AZ_OK on success.

addMember( $member )

Append a member (possibly from another zip file) to the zip file. Returns the new member. Generally, you will use addFile(), addDirectory(), addFileOrDirectory(), addString(), or read() to add members.

    # Move member named 'abc' to end of zip:
    my $member = $zip->removeMember( 'abc' );
    $zip->addMember( $member );
updateMember( $memberOrName, $fileName )

Update a single member from the file or directory named $fileName. Returns the (possibly added or updated) member, if any; undef on errors. The comparison is based on lastModTime() and (in the case of a non-directory) the size of the file.

addFile( $fileName [, $newName ] )

Append a member whose data comes from an external file, returning the member or undef. The member will have its file name set to the name of the external file, and its desiredCompressionMethod set to COMPRESSION_DEFLATED. The file attributes and last modification time will be set from the file. If the name given does not represent a readable plain file or symbolic link, undef will be returned. $fileName must be in the format required for the local file system. The optional $newName argument sets the internal file name to something different than the given $fileName. $newName, if given, must be in Zip name format (i.e. Unix). The text mode bit will be set if the contents appears to be text (as returned by the -T perl operator).

NOTE that you shouldn't (generally) use absolute path names in zip member names, as this will cause problems with some zip tools as well as introduce a security hole and make the zip harder to use.

addDirectory( $directoryName [, $fileName ] )

Append a member created from the given directory name. The directory name does not have to name an existing directory. If the named directory exists, the file modification time and permissions are set from the existing directory, otherwise they are set to now and permissive default permissions. $directoryName must be in local file system format. The optional second argument sets the name of the archive member (which defaults to $directoryName). If given, it must be in Zip (Unix) format. Returns the new member.

addFileOrDirectory( $name [, $newName ] )

Append a member from the file or directory named $name. If $newName is given, use it for the name of the new member. Will add or remove trailing slashes from $newName as needed. $name must be in local file system format. The optional second argument sets the name of the archive member (which defaults to $name). If given, it must be in Zip (Unix) format.

addString( $stringOrStringRef, $name )

Append a member created from the given string or string reference. The name is given by the second argument. Returns the new member. The last modification time will be set to now, and the file attributes will be set to permissive defaults.

    my $member = $zip->addString( 'This is a test', 'test.txt' );
contents( $memberOrMemberName [, $newContents ] )

Returns the uncompressed data for a particular member, or undef.

    print "xyz.txt contains " . $zip->contents( 'xyz.txt' );

Also can change the contents of a member:

    $zip->contents( 'xyz.txt', 'This is the new contents' );

If called expecting an array as the return value, it will include the status as the second value in the array.

    ($content, $status) = $zip->contents( 'xyz.txt');

Zip Archive I/O operations

A Zip archive can be written to a file or file handle, or read from one.

writeToFileNamed( $fileName )

Write a zip archive to named file. Returns AZ_OK on success.

    my $status = $zip->writeToFileNamed( 'xx.zip' );
    die "error somewhere" if $status != AZ_OK;

Note that if you use the same name as an existing zip file that you read in, you will clobber ZipFileMembers. So instead, write to a different file name, then delete the original. If you use the overwrite() or overwriteAs() methods, you can re-write the original zip in this way. $fileName should be a valid file name on your system.

writeToFileHandle( $fileHandle [, $seekable] )

Write a zip archive to a file handle. Return AZ_OK on success. The optional second arg tells whether or not to try to seek backwards to re-write headers. If not provided, it is set if the Perl -f test returns true. This could fail on some operating systems, though.

    my $fh = IO::File->new( 'someFile.zip', 'w' );
    if ( $zip->writeToFileHandle( $fh ) != AZ_OK)
        {
                # error handling
        }

If you pass a file handle that is not seekable (like if you're writing to a pipe or a socket), pass a false second argument:

    my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
    $zip->writeToFileHandle( $fh, 0 );   # fh is not seekable

If this method fails during the write of a member, that member and all following it will return false from wasWritten(). See writeCentralDirectory() for a way to deal with this. If you want, you can write data to the file handle before passing it to writeToFileHandle(); this could be used (for instance) for making self-extracting archives. However, this only works reliably when writing to a real file (as opposed to STDOUT or some other possible non-file). See examples/selfex.pl for how to write a self-extracting archive.

writeCentralDirectory( $fileHandle [, $offset ] )

Writes the central directory structure to the given file handle. Returns AZ_OK on success. If given an $offset, will seek to that point before writing. This can be used for recovery in cases where writeToFileHandle or writeToFileNamed returns an IO error because of running out of space on the destination file. You can truncate the zip by seeking backwards and then writing the directory:

    my $fh = IO::File->new( 'someFile.zip', 'w' );
        my $retval = $zip->writeToFileHandle( $fh );
    if ( $retval == AZ_IO_ERROR )
        {
                my @unwritten = grep { not $_->wasWritten() } $zip->members();
                if (@unwritten)
                {
                        $zip->removeMember( $member ) foreach my $member ( @unwritten );
                        $zip->writeCentralDirectory( $fh,
                                $unwritten[0]->writeLocalHeaderRelativeOffset());
                }
        }
overwriteAs( $newName )

Write the zip to the specified file, as safely as possible. This is done by first writing to a temp file, then renaming the original if it exists, then renaming the temp file, then deleting the renamed original if it exists. Returns AZ_OK if successful.

overwrite()

Write back to the original zip file. See overwriteAs() above. If the zip was not ever read from a file, this generates an error.

read( $fileName )

Read zipfile headers from a zip file, appending new members. Returns AZ_OK or error code.

    my $zipFile = Archive::Zip->new();
    my $status = $zipFile->read( '/some/FileName.zip' );
readFromFileHandle( $fileHandle, $filename )

Read zipfile headers from an already-opened file handle, appending new members. Does not close the file handle. Returns AZ_OK or error code. Note that this requires a seekable file handle; reading from a stream is not yet supported.

    my $fh = IO::File->new( '/some/FileName.zip', 'r' );
    my $zip1 = Archive::Zip->new();
    my $status = $zip1->readFromFileHandle( $fh );
    my $zip2 = Archive::Zip->new();
    $status = $zip2->readFromFileHandle( $fh );

Zip Archive Tree operations

These used to be in Archive::Zip::Tree but got moved into Archive::Zip. They enable operation on an entire tree of members or files. A usage example:

  use Archive::Zip;
  my $zip = Archive::Zip->new();
  # add all readable files and directories below . as xyz/*
  $zip->addTree( '.', 'xyz' );
  # add all readable plain files below /abc as def/*
  $zip->addTree( '/abc', 'def', sub { -f && -r } );
  # add all .c files below /tmp as stuff/*
  $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
  # add all .o files below /tmp as stuff/* if they aren't writable
  $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
  # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
  $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
  # and write them into a file
  $zip->writeToFileNamed('xxx.zip');
  # now extract the same files into /tmpx
  $zip->extractTree( 'stuff', '/tmpx' );
$zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip

$root is the root of the tree of files and directories to be added. It is a valid directory name on your system. $dest is the name for the root in the zip file (undef or blank means to use relative pathnames). It is a valid ZIP directory name (that is, it uses forward slashes (/) for separating directory components). $pred is an optional subroutine reference to select files: it is passed the name of the prospective file or directory using $_, and if it returns true, the file or directory will be included. The default is to add all readable files and directories. For instance, using

  my $pred = sub { /\.txt/ };
  $zip->addTree( '.', '', $pred );

will add all the .txt files in and below the current directory, using relative names, and making the names identical in the zipfile:

  original name           zip member name
  ./xyz                   xyz
  ./a/                    a/
  ./a/b                   a/b

To translate absolute to relative pathnames, just pass them in: $zip->addTree( '/c/d', 'a' );

  original name           zip member name
  /c/d/xyz                a/xyz
  /c/d/a/                 a/a/
  /c/d/a/b                a/a/b

Returns AZ_OK on success. Note that this will not follow symbolic links to directories. Note also that this does not check for the validity of filenames.

Note that you generally don't want to make zip archive member names absolute.

$zip->addTreeMatching( $root, $dest, $pattern [,$pred] )

$root is the root of the tree of files and directories to be added $dest is the name for the root in the zip file (undef means to use relative pathnames) $pattern is a (non-anchored) regular expression for filenames to match $pred is an optional subroutine reference to select files: it is passed the name of the prospective file or directory in $_, and if it returns true, the file or directory will be included. The default is to add all readable files and directories. To add all files in and below the current dirctory whose names end in .pl, and make them extract into a subdirectory named xyz, do this:

  $zip->addTreeMatching( '.', 'xyz', '\.pl$' )

To add all writable files in and below the dirctory named /abc whose names end in .pl, and make them extract into a subdirectory named xyz, do this:

  $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )

Returns AZ_OK on success. Note that this will not follow symbolic links to directories.

$zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );

Update a zip file from a directory tree.

updateTree() takes the same arguments as addTree(), but first checks to see whether the file or directory already exists in the zip file, and whether it has been changed.

If the fourth argument $mirror is true, then delete all my members if corresponding files weren't found.

Returns an error code or AZ_OK if all is well.

$zip->extractTree()
$zip->extractTree( $root )
$zip->extractTree( $root, $dest )
$zip->extractTree( $root, $dest, $volume )

If you don't give any arguments at all, will extract all the files in the zip with their original names.

If you supply one argument for $root, extractTree will extract all the members whose names start with $root into the current directory, stripping off $root first. $root is in Zip (Unix) format. For instance,

  $zip->extractTree( 'a' );

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e will extract:

a/x as ./x

a/b/c as ./b/c

If you give two arguments, extractTree extracts all the members whose names start with $root. It will translate $root into $dest to construct the destination file name. $root and $dest are in Zip (Unix) format. For instance,

   $zip->extractTree( 'a', 'd/e' );

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e will extract:

a/x to d/e/x

a/b/c to d/e/b/c and ignore ax/d/e and d/e

If you give three arguments, extractTree extracts all the members whose names start with $root. It will translate $root into $dest to construct the destination file name, and then it will convert to local file system format, using $volume as the name of the destination volume.

$root and $dest are in Zip (Unix) format.

$volume is in local file system format.

For instance, under Windows,

   $zip->extractTree( 'a', 'd/e', 'f:' );

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e will extract:

a/x to f:d/e/x

a/b/c to f:d/e/b/c and ignore ax/d/e and d/e

If you want absolute paths (the prior example used paths relative to the current directory on the destination volume, you can specify these in $dest:

   $zip->extractTree( 'a', '/d/e', 'f:' );

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e will extract:

a/x to f:\d\e\x

a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e

Returns an error code or AZ_OK if everything worked OK.

MEMBER OPERATIONS

Member Class Methods

Several constructors allow you to construct members without adding them to a zip archive. These work the same as the addFile(), addDirectory(), and addString() zip instance methods described above, but they don't add the new members to a zip.

Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )

Construct a new member from the given string. Returns undef on error.

    my $member = Archive::Zip::Member->newFromString( 'This is a test',
                                                 'xyz.txt' );
newFromFile( $fileName )

Construct a new member from the given file. Returns undef on error.

    my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
newDirectoryNamed( $directoryName [, $zipname ] )

Construct a new member from the given directory. $directoryName must be a valid name on your file system; it doesn't have to exist.

If given, $zipname will be the name of the zip member; it must be a valid Zip (Unix) name. If not given, it will be converted from $directoryName.

Returns undef on error.

    my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );

Member Simple accessors

These methods get (and/or set) member attribute values.

versionMadeBy()

Gets the field from the member header.

fileAttributeFormat( [$format] )

Gets or sets the field from the member header. These are FA_* values.

versionNeededToExtract()

Gets the field from the member header.

bitFlag()

Gets the general purpose bit field from the member header. This is where the GPBF_* bits live.

compressionMethod()

Returns the member compression method. This is the method that is currently being used to compress the member data. This will be COMPRESSION_STORED for added string or file members, or any of the COMPRESSION_* values for members from a zip file. However, this module can only handle members whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED format.

desiredCompressionMethod( [$method] )

Get or set the member's desiredCompressionMethod. This is the compression method that will be used when the member is written. Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED or COMPRESSION_STORED are valid arguments. Changing to COMPRESSION_STORED will change the member desiredCompressionLevel to 0; changing to COMPRESSION_DEFLATED will change the member desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.

desiredCompressionLevel( [$method] )

Get or set the member's desiredCompressionLevel This is the method that will be used to write. Returns prior desiredCompressionLevel. Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change the desiredCompressionMethod to COMPRESSION_STORED. All other arguments will change the desiredCompressionMethod to COMPRESSION_DEFLATED.

externalFileName()

Return the member's external file name, if any, or undef.

fileName()

Get or set the member's internal filename. Returns the (possibly new) filename. Names will have backslashes converted to forward slashes, and will have multiple consecutive slashes converted to single ones.

lastModFileDateTime()

Return the member's last modification date/time stamp in MS-DOS format.

lastModTime()

Return the member's last modification date/time stamp, converted to unix localtime format.

    print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
setLastModFileDateTimeFromUnix()

Set the member's lastModFileDateTime from the given unix time.

    $member->setLastModFileDateTimeFromUnix( time() );
internalFileAttributes()

Return the internal file attributes field from the zip header. This is only set for members read from a zip file.

externalFileAttributes()

Return member attributes as read from the ZIP file. Note that these are NOT UNIX!

unixFileAttributes( [$newAttributes] )

Get or set the member's file attributes using UNIX file attributes. Returns old attributes.

    my $oldAttribs = $member->unixFileAttributes( 0666 );

Note that the return value has more than just the file permissions, so you will have to mask off the lowest bits for comparisions.

localExtraField( [$newField] )

Gets or sets the extra field that was read from the local header. This is not set for a member from a zip file until after the member has been written out. The extra field must be in the proper format.

cdExtraField( [$newField] )

Gets or sets the extra field that was read from the central directory header. The extra field must be in the proper format.

extraFields()

Return both local and CD extra fields, concatenated.

fileComment( [$newComment] )

Get or set the member's file comment.

hasDataDescriptor()

Get or set the data descriptor flag. If this is set, the local header will not necessarily have the correct data sizes. Instead, a small structure will be stored at the end of the member data with these values. This should be transparent in normal operation.

crc32()

Return the CRC-32 value for this member. This will not be set for members that were constructed from strings or external files until after the member has been written.

crc32String()

Return the CRC-32 value for this member as an 8 character printable hex string. This will not be set for members that were constructed from strings or external files until after the member has been written.

compressedSize()

Return the compressed size for this member. This will not be set for members that were constructed from strings or external files until after the member has been written.

uncompressedSize()

Return the uncompressed size for this member.

isEncrypted()

Return true if this member is encrypted. The Archive::Zip module does not currently create or extract encrypted members.

isTextFile( [$flag] )

Returns true if I am a text file. Also can set the status if given an argument (then returns old state). Note that this module does not currently do anything with this flag upon extraction or storage. That is, bytes are stored in native format whether or not they came from a text file.

isBinaryFile()

Returns true if I am a binary file. Also can set the status if given an argument (then returns old state). Note that this module does not currently do anything with this flag upon extraction or storage. That is, bytes are stored in native format whether or not they came from a text file.

extractToFileNamed( $fileName )

Extract me to a file with the given name. The file will be created with default modes. Directories will be created as needed. The $fileName argument should be a valid file name on your file system. Returns AZ_OK on success.

isDirectory()

Returns true if I am a directory.

writeLocalHeaderRelativeOffset()

Returns the file offset in bytes the last time I was written.

wasWritten()

Returns true if I was successfully written. Reset at the beginning of a write attempt.

Low-level member data reading

It is possible to use lower-level routines to access member data streams, rather than the extract* methods and contents(). For instance, here is how to print the uncompressed contents of a member in chunks using these methods:

    my ( $member, $status, $bufferRef );
    $member = $zip->memberNamed( 'xyz.txt' );
    $member->desiredCompressionMethod( COMPRESSION_STORED );
    $status = $member->rewindData();
    die "error $status" unless $status == AZ_OK;
    while ( ! $member->readIsDone() )
    {
    ( $bufferRef, $status ) = $member->readChunk();
    die "error $status"
                        if $status != AZ_OK && $status != AZ_STREAM_END;
    # do something with $bufferRef:
    print $$bufferRef;
    }
    $member->endRead();
readChunk( [$chunkSize] )

This reads the next chunk of given size from the member's data stream and compresses or uncompresses it as necessary, returning a reference to the bytes read and a status. If size argument is not given, defaults to global set by Archive::Zip::setChunkSize. Status is AZ_OK on success until the last chunk, where it returns AZ_STREAM_END. Returns ( \$bytes, $status).

    my ( $outRef, $status ) = $self->readChunk();
    print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
rewindData()

Rewind data and set up for reading data streams or writing zip files. Can take options for inflateInit() or deflateInit(), but this isn't likely to be necessary. Subclass overrides should call this method. Returns AZ_OK on success.

endRead()

Reset the read variables and free the inflater or deflater. Must be called to close files, etc. Returns AZ_OK on success.

readIsDone()

Return true if the read has run out of data or errored out.

contents()

Return the entire uncompressed member data or undef in scalar context. When called in array context, returns ( $string, $status ); status will be AZ_OK on success:

    my $string = $member->contents();
    # or
    my ( $string, $status ) = $member->contents();
    die "error $status" unless $status == AZ_OK;

Can also be used to set the contents of a member (this may change the class of the member):

    $member->contents( "this is my new contents" );
extractToFileHandle( $fh )

Extract (and uncompress, if necessary) the member's contents to the given file handle. Return AZ_OK on success.

Archive::Zip::FileMember methods

The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the base class for both ZipFileMember and NewFileMember classes. This class adds an externalFileName and an fh member to keep track of the external file.

externalFileName()

Return the member's external filename.

fh()

Return the member's read file handle. Automatically opens file if necessary.

Archive::Zip::ZipFileMember methods

The Archive::Zip::ZipFileMember class represents members that have been read from external zip files.

diskNumberStart()

Returns the disk number that the member's local header resides in. Should be 0.

localHeaderRelativeOffset()

Returns the offset into the zip file where the member's local header is.

dataOffset()

Returns the offset from the beginning of the zip file to the member's data.

REQUIRED MODULES

Archive::Zip requires several other modules:

Carp

Compress::Zlib

Cwd

File::Basename

File::Copy

File::Find

File::Path

File::Spec

File::Spec

IO::File

IO::Seekable

Time::Local

AUTHOR

Ned Konz, <nedkonz@cpan.org>

CURRENT MAINTAINER

Steve Peters, <steve@fisharerojo.org>

File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>

COPYRIGHT

Copyright (c) 2000-2004 Ned Konz, 2005 Steve Peters. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the Compress::Zlib manpage

the Archive::Tar manpage

There is a Japanese translation of this document at http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html that was done by DEQ <deq@oct.zaq.ne.jp> . Thanks!


Archive::Zip::FAQ - Answers to a few frequently asked questions about Archive::Zip

  • Install problems on RedHat 8 or 9 with Perl 5.8.0
  • Why is my zip file so big?
  • Sample code?
  • Can't Read/modify/write same Zip file
  • File creation time not set
  • Can't use Archive::Zip on gzip files
  • Add a directory/tree to a Zip
  • Extract a directory/tree
  • Update a directory/tree
  • Zip times might be off by 1 second
  • Zip times don't include time zone information
  • How do I make a self-extracting Zip
  • How can I deal with Zips with prepended garbage (i.e. from Sircam)
  • Can't extract Shrunk files
  • Can't do decryption
  • How to test file integrity?
  • Duplicate files in Zip?
  • File ownership/permissions/ACLS/etc
  • I can't compile but ActiveState only has an old version of Archive::Zip
  • My JPEGs (or MP3's) don't compress when I put them into Zips!
  • Under Windows, things lock up/get damaged
  • Zip contents in a scalar
  • Reading from streams

NAME

Archive::Zip::FAQ - Answers to a few frequently asked questions about Archive::Zip

DESCRIPTION

It seems that I keep answering the same questions over and over again. I assume that this is because my documentation is deficient, rather than that people don't read the documentation.

So this FAQ is an attempt to cut down on the number of personal answers I have to give. At least I can now say "You did read the FAQ, right?".

The questions are not in any particular order. The answers assume the current version of Archive::Zip; some of the answers depend on newly added/fixed functionality.

Install problems on RedHat 8 or 9 with Perl 5.8.0

Q: Archive::Zip won't install on my RedHat 9 system! It's broke!

A: This has become something of a FAQ. Basically, RedHat broke some versions of Perl by setting LANG to UTF8. They apparently have a fixed version out as an update.

You might try running CPAN or creating your Makefile after exporting the LANG environment variable as

LANG=C

https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=87682

Why is my zip file so big?

Q: My zip file is actually bigger than what I stored in it! Why?

A: Some things to make sure of:

Make sure that you are requesting COMPRESSION_DEFLATED if you are storing strings.

$member->desiredCompressionMethod( COMPRESSION_DEFLATED );

Don't make lots of little files if you can help it.

Since zip computes the compression tables for each member, small members without much entropy won't compress well. Instead, if you've got lots of repeated strings in your data, try to combine them into one big member.

Make sure that you are requesting COMPRESSION_STORED if you are storing things that are already compressed.

If you're storing a .zip, .jpg, .mp3, or other compressed file in a zip, then don't compress them again. They'll get bigger.

Sample code?

Q: Can you send me code to do (whatever)?

A: Have you looked in the examples/ directory yet? It contains:

examples/calcSizes.pl -- How to find out how big a Zip file will be before writing it
examples/copy.pl -- Copies one Zip file to another
examples/extract.pl -- extract file(s) from a Zip
examples/mailZip.pl -- make and mail a zip file
examples/mfh.pl -- demo for use of MockFileHandle
examples/readScalar.pl -- shows how to use IO::Scalar as the source of a Zip read
examples/selfex.pl -- a brief example of a self-extracting Zip
examples/unzipAll.pl -- uses Archive::Zip::Tree to unzip an entire Zip
examples/updateZip.pl -- shows how to read/modify/write a Zip
examples/updateTree.pl -- shows how to update a Zip in place
examples/writeScalar.pl -- shows how to use IO::Scalar as the destination of a Zip write
examples/writeScalar2.pl -- shows how to use IO::String as the destination of a Zip write
examples/zip.pl -- Constructs a Zip file
examples/zipcheck.pl -- One way to check a Zip file for validity
examples/zipinfo.pl -- Prints out information about a Zip archive file
examples/zipGrep.pl -- Searches for text in Zip files
examples/ziptest.pl -- Lists a Zip file and checks member CRCs
examples/ziprecent.pl -- Puts recent files into a zipfile
examples/ziptest.pl -- Another way to check a Zip file for validity

Can't Read/modify/write same Zip file

Q: Why can't I open a Zip file, add a member, and write it back? I get an error message when I try.

A: Because Archive::Zip doesn't (and can't, generally) read file contents into memory, the original Zip file is required to stay around until the writing of the new file is completed.

The best way to do this is to write the Zip to a temporary file and then rename the temporary file to have the old name (possibly after deleting the old one).

Archive::Zip v1.02 added the archive methods overwrite() and overwriteAs() to do this simply and carefully.

See examples/updateZip.pl for an example of this technique.

File creation time not set

Q: Upon extracting files, I see that their modification (and access) times are set to the time in the Zip archive. However, their creation time is not set to the same time. Why?

A: Mostly because Perl doesn't give cross-platform access to creation time. Indeed, many systems (like Unix) don't support such a concept. However, if yours does, you can easily set it. Get the modification time from the member using lastModTime().

Can't use Archive::Zip on gzip files

Q: Can I use Archive::Zip to extract Unix gzip files?

A: No.

There is a distinction between Unix gzip files, and Zip archives that also can use the gzip compression.

Depending on the format of the gzip file, you can use the Compress::Zlib manpage, or the Archive::Tar manpage to decompress it (and de-archive it in the case of Tar files).

You can unzip PKZIP/WinZip/etc/ archives using Archive::Zip (that's what it's for) as long as any compressed members are compressed using Deflate compression.

Add a directory/tree to a Zip

Q: How can I add a directory (or tree) full of files to a Zip?

A: You can use the Archive::Zip::addTree*() methods:

   use Archive::Zip;
   my $zip = Archive::Zip->new();
   # add all readable files and directories below . as xyz/*
   $zip->addTree( '.', 'xyz' );
   # add all readable plain files below /abc as def/*
   $zip->addTree( '/abc', 'def', sub { -f && -r } );
   # add all .c files below /tmp as stuff/*
   $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
   # add all .o files below /tmp as stuff/* if they aren't writable
   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
   # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
   # and write them into a file
   $zip->writeToFileNamed('xxx.zip');

Extract a directory/tree

Q: How can I extract some (or all) files from a Zip into a different directory?

A: You can use the Archive::Zip::extractTree() method: ??? ||

   # now extract the same files into /tmpx
   $zip->extractTree( 'stuff', '/tmpx' );

Update a directory/tree

Q: How can I update a Zip from a directory tree, adding or replacing only the newer files?

A: You can use the Archive::Zip::updateTree() method that was added in version 1.09.

Zip times might be off by 1 second

Q: It bothers me greatly that my file times are wrong by one second about half the time. Why don't you do something about it?

A: Get over it. This is a result of the Zip format storing times in DOS format, which has a resolution of only two seconds.

Zip times don't include time zone information

Q: My file times don't respect time zones. What gives?

A: If this is important to you, please submit patches to read the various Extra Fields that encode times with time zones. I'm just using the DOS Date/Time, which doesn't have a time zone.

How do I make a self-extracting Zip

Q: I want to make a self-extracting Zip file. Can I do this?

A: Yes. You can write a self-extracting archive stub (that is, a version of unzip) to the output filehandle that you pass to writeToFileHandle(). See examples/selfex.pl for how to write a self-extracting archive.

However, you should understand that this will only work on one kind of platform (the one for which the stub was compiled).

How can I deal with Zips with prepended garbage (i.e. from Sircam)

Q: How can I tell if a Zip has been damaged by adding garbage to the beginning or inside the file?

A: I added code for this for the Amavis virus scanner. You can query archives for their 'eocdOffset' property, which should be 0:

  if ($zip->eocdOffset > 0)
    { warn($zip->eocdOffset . " bytes of garbage at beginning or within Zip") }

When members are extracted, this offset will be used to adjust the start of the member if necessary.

Can't extract Shrunk files

Q: I'm trying to extract a file out of a Zip produced by PKZIP, and keep getting this error message:

  error: Unsupported compression combination: read 6, write 0

A: You can't uncompress this archive member. Archive::Zip only supports uncompressed members, and compressed members that are compressed using the compression supported by Compress::Zlib. That means only Deflated and Stored members.

Your file is compressed using the Shrink format, which isn't supported by Compress::Zlib.

You could, perhaps, use a command-line UnZip program (like the Info-Zip one) to extract this.

Can't do decryption

Q: How do I decrypt encrypted Zip members?

A: With some other program or library. Archive::Zip doesn't support decryption, and probably never will (unless you write it).

How to test file integrity?

Q: How can Archive::Zip can test the validity of a Zip file?

A: If you try to decompress the file, the gzip streams will report errors if you have garbage. Most of the time.

If you try to open the file and a central directory structure can't be found, an error will be reported.

When a file is being read, if we can't find a proper PK.. signature in the right places we report a format error.

If there is added garbage at the beginning of a Zip file (as inserted by some viruses), you can find out about it, but Archive::Zip will ignore it, and you can still use the archive. When it gets written back out the added stuff will be gone.

There are two ready-to-use utilities in the examples directory that can be used to test file integrity, or that you can use as examples for your own code:

examples/zipcheck.pl shows how to use an attempted extraction to test a file.
examples/ziptest.pl shows how to test CRCs in a file.

Duplicate files in Zip?

Q: Archive::Zip let me put the same file in my Zip twice! Why don't you prevent this?

A: As far as I can tell, this is not disallowed by the Zip spec. If you think it's a bad idea, check for it yourself:

  $zip->addFile($someFile, $someName) unless $zip->memberNamed($someName);

I can even imagine cases where this might be useful (for instance, multiple versions of files).

File ownership/permissions/ACLS/etc

Q: Why doesn't Archive::Zip deal with file ownership, ACLs, etc.?

A: There is no standard way to represent these in the Zip file format. If you want to send me code to properly handle the various extra fields that have been used to represent these through the years, I'll look at it.

I can't compile but ActiveState only has an old version of Archive::Zip

Q: I've only installed modules using ActiveState's PPM program and repository. But they have a much older version of Archive::Zip than is in CPAN. Will you send me a newer PPM?

A: Probably not, unless I get lots of extra time. But there's no reason you can't install the version from CPAN. Archive::Zip is pure Perl, so all you need is NMAKE, which you can get for free from Microsoft (see the FAQ in the ActiveState documentation for details on how to install CPAN modules).

My JPEGs (or MP3's) don't compress when I put them into Zips!

Q: How come my JPEGs and MP3's don't compress much when I put them into Zips?

A: Because they're already compressed.

Under Windows, things lock up/get damaged

Q: I'm using Windows. When I try to use Archive::Zip, my machine locks up/makes funny sounds/displays a BSOD/corrupts data. How can I fix this?

A: First, try the newest version of Compress::Zlib. I know of Windows-related problems prior to v1.14 of that library.

If that doesn't get rid of the problem, fix your computer or get rid of Windows.

Zip contents in a scalar

Q: I want to read a Zip file from (or write one to) a scalar variable instead of a file. How can I do this?

A: Use IO::Scalar and the readFromFileHandle() and writeToFileHandle() methods. See examples/readScalar.pl and examples/writeScalar.pl.

Reading from streams

Q: How do I read from a stream (like for the Info-Zip funzip program)?

A: This isn't currently supported, though writing to a stream is.


Archive::Zip::MemberRead - A wrapper that lets you read Zip archive members as if they were files.

  • METHODS
  • AUTHOR
  • COPYRIGHT

NAME

Archive::Zip::MemberRead - A wrapper that lets you read Zip archive members as if they were files.

SYNOPSIS

  use Archive::Zip;
  use Archive::Zip::MemberRead;
  $zip = new Archive::Zip("file.zip");
  $fh  = new Archive::Zip::MemberRead($zip, "subdir/abc.txt");
  while (defined($line = $fh->getline()))
  {
      print $fh->input_line_number . "#: $line\n";
  }

  $read = $fh->read($buffer, 32*1024);
  print "Read $read bytes as :$buffer:\n";

DESCRIPTION

The Archive::Zip::MemberRead module lets you read Zip archive member data just like you read data from files.

METHODS

Archive::Zip::Member::readFileHandle()

You can get a Archive::Zip::MemberRead from an archive member by calling readFileHandle():

  my $member = $zip->memberNamed('abc/def.c');
  my $fh = $member->readFileHandle();
  while (defined($line = $fh->getline()))
  {
          # ...
  }
  $fh->close();
Archive::Zip::MemberRead->new($zip, $fileName)
Archive::Zip::MemberRead->new($zip, $member)
Archive::Zip::MemberRead->new($member)

Construct a new Archive::Zip::MemberRead on the specified member.

  my $fh = Archive::Zip::MemberRead->new($zip, 'fred.c')
rewind()

Rewinds an Archive::Zip::MemberRead so that you can read from it again starting at the beginning.

input_line_number()

Returns the current line number, but only if you're using getline(). Using read() will not update the line number.

close()

Closes the given file handle.

buffer_size([ $size ])

Gets or sets the buffer size used for reads. Default is the chunk size used by Archive::Zip.

getline()

Returns the next line from the currently open member. Makes sense only for text files. A read error is considered fatal enough to die. Returns undef on eof. All subsequent calls would return undef, unless a rewind() is called. Note: The line returned has the newline removed.

read($buffer, $num_bytes_to_read)

Simulates a normal read() system call. Returns the no. of bytes read. undef on error, 0 on eof, e.g.:

  $fh = new Archive::Zip::MemberRead($zip, "sreeji/secrets.bin");
  while (1)
  {
    $read = $fh->read($buffer, 1024);
    die "FATAL ERROR reading my secrets !\n" if (!defined($read));
    last if (!$read);
    # Do processing.
    ....
   }

AUTHOR

Sreeji K. Das, <sreeji_k@yahoo.com> See the Archive::Zip manpage by Ned Konz without which this module does not make any sense!

Minor mods by Ned Konz.

COPYRIGHT

Copyright (c) 2002 Sreeji K. Das. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Archive::Zip::Tree - methods for adding/extracting trees using Archive::Zip

  • AUTHOR
  • COPYRIGHT
  • SEE ALSO

NAME

Archive::Zip::Tree - methods for adding/extracting trees using Archive::Zip

SYNOPSIS

DESCRIPTION

This module is deprecated, because all its methods were moved into the main Archive::Zip module.

It is included in the distribution merely to avoid breaking old code.

See the Archive::Zip manpage.

AUTHOR

Ned Konz, perl@bike-nomad.com

COPYRIGHT

Copyright (c) 2000-2002 Ned Konz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the Archive::Zip manpage


Attribute::Handlers - Simpler definition of attribute handlers

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • Typed lexicals
    • Type-specific attribute handlers
    • Non-interpretive attribute handlers
    • Phase-specific attribute handlers
    • Attributes as tie interfaces
      • Passing the tied object to tie
  • EXAMPLES
  • DIAGNOSTICS
  • AUTHOR
  • BUGS
  • COPYRIGHT

NAME

Attribute::Handlers - Simpler definition of attribute handlers

VERSION

This document describes version 0.78 of Attribute::Handlers, released October 5, 2002.

SYNOPSIS

        package MyClass;
        require v5.6.0;
        use Attribute::Handlers;
        no warnings 'redefine';

        sub Good : ATTR(SCALAR) {
                my ($package, $symbol, $referent, $attr, $data) = @_;

                # Invoked for any scalar variable with a :Good attribute,
                # provided the variable was declared in MyClass (or
                # a derived class) or typed to MyClass.

                # Do whatever to $referent here (executed in CHECK phase).
                ...
        }
        sub Bad : ATTR(SCALAR) {
                # Invoked for any scalar variable with a :Bad attribute,
                # provided the variable was declared in MyClass (or
                # a derived class) or typed to MyClass.
                ...
        }

        sub Good : ATTR(ARRAY) {
                # Invoked for any array variable with a :Good attribute,
                # provided the variable was declared in MyClass (or
                # a derived class) or typed to MyClass.
                ...
        }

        sub Good : ATTR(HASH) {
                # Invoked for any hash variable with a :Good attribute,
                # provided the variable was declared in MyClass (or
                # a derived class) or typed to MyClass.
                ...
        }

        sub Ugly : ATTR(CODE) {
                # Invoked for any subroutine declared in MyClass (or a
                # derived class) with an :Ugly attribute.
                ...
        }

        sub Omni : ATTR {
                # Invoked for any scalar, array, hash, or subroutine
                # with an :Omni attribute, provided the variable or
                # subroutine was declared in MyClass (or a derived class)
                # or the variable was typed to MyClass.
                # Use ref($_[2]) to determine what kind of referent it was.
                ...
        }

        use Attribute::Handlers autotie => { Cycle => Tie::Cycle };

        my $next : Cycle(['A'..'Z']);

DESCRIPTION

This module, when inherited by a package, allows that package's class to define attribute handler subroutines for specific attributes. Variables and subroutines subsequently defined in that package, or in packages derived from that package may be given attributes with the same names as the attribute handler subroutines, which will then be called in one of the compilation phases (i.e. in a BEGIN, CHECK, INIT, or END block).

To create a handler, define it as a subroutine with the same name as the desired attribute, and declare the subroutine itself with the attribute :ATTR. For example:

        package LoudDecl;
        use Attribute::Handlers;

        sub Loud :ATTR {
                my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
                print STDERR
                        ref($referent), " ",
                        *{$symbol}{NAME}, " ",
                        "($referent) ", "was just declared ",
                        "and ascribed the ${attr} attribute ",
                        "with data ($data)\n",
                        "in phase $phase\n";
        }

This creates a handler for the attribute :Loud in the class LoudDecl. Thereafter, any subroutine declared with a :Loud attribute in the class LoudDecl:

        package LoudDecl;

        sub foo: Loud {...}

causes the above handler to be invoked, and passed:

[0]

the name of the package into which it was declared;

[1]

a reference to the symbol table entry (typeglob) containing the subroutine;

[2]

a reference to the subroutine;

[3]

the name of the attribute;

[4]

any data associated with that attribute;

[5]

the name of the phase in which the handler is being invoked.

Likewise, declaring any variables with the :Loud attribute within the package:

        package LoudDecl;

        my $foo :Loud;
        my @foo :Loud;
        my %foo :Loud;

will cause the handler to be called with a similar argument list (except, of course, that $_[2] will be a reference to the variable).

The package name argument will typically be the name of the class into which the subroutine was declared, but it may also be the name of a derived class (since handlers are inherited).

If a lexical variable is given an attribute, there is no symbol table to which it belongs, so the symbol table argument ($_[1]) is set to the string 'LEXICAL' in that case. Likewise, ascribing an attribute to an anonymous subroutine results in a symbol table argument of 'ANON'.

The data argument passes in the value (if any) associated with the attribute. For example, if &foo had been declared:

        sub foo :Loud("turn it up to 11, man!") {...}

then the string "turn it up to 11, man!" would be passed as the last argument.

Attribute::Handlers makes strenuous efforts to convert the data argument ($_[4]) to a useable form before passing it to the handler (but see Non-interpretive attribute handlers). For example, all of these:

        sub foo :Loud(till=>ears=>are=>bleeding) {...}
        sub foo :Loud(['till','ears','are','bleeding']) {...}
        sub foo :Loud(qw/till ears are bleeding/) {...}
        sub foo :Loud(qw/my, ears, are, bleeding/) {...}
        sub foo :Loud(till,ears,are,bleeding) {...}

causes it to pass ['till','ears','are','bleeding'] as the handler's data argument. However, if the data can't be parsed as valid Perl, then it is passed as an uninterpreted string. For example:

        sub foo :Loud(my,ears,are,bleeding) {...}
        sub foo :Loud(qw/my ears are bleeding) {...}

cause the strings 'my,ears,are,bleeding' and 'qw/my ears are bleeding' respectively to be passed as the data argument.

If the attribute has only a single associated scalar data value, that value is passed as a scalar. If multiple values are associated, they are passed as an array reference. If no value is associated with the attribute, undef is passed.

Typed lexicals

Regardless of the package in which it is declared, if a lexical variable is ascribed an attribute, the handler that is invoked is the one belonging to the package to which it is typed. For example, the following declarations:

        package OtherClass;

        my LoudDecl $loudobj : Loud;
        my LoudDecl @loudobjs : Loud;
        my LoudDecl %loudobjex : Loud;

causes the LoudDecl::Loud handler to be invoked (even if OtherClass also defines a handler for :Loud attributes).

Type-specific attribute handlers

If an attribute handler is declared and the :ATTR specifier is given the name of a built-in type (SCALAR, ARRAY, HASH, or CODE), the handler is only applied to declarations of that type. For example, the following definition:

        package LoudDecl;

        sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" }

creates an attribute handler that applies only to scalars:

        package Painful;
        use base LoudDecl;

        my $metal : RealLoud;           # invokes &LoudDecl::RealLoud
        my @metal : RealLoud;           # error: unknown attribute
        my %metal : RealLoud;           # error: unknown attribute
        sub metal : RealLoud {...}      # error: unknown attribute

You can, of course, declare separate handlers for these types as well (but you'll need to specify no warnings 'redefine' to do it quietly):

        package LoudDecl;
        use Attribute::Handlers;
        no warnings 'redefine';

        sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" }
        sub RealLoud :ATTR(ARRAY) { print "Urrrrrrrrrr!" }
        sub RealLoud :ATTR(HASH) { print "Arrrrrgggghhhhhh!" }
        sub RealLoud :ATTR(CODE) { croak "Real loud sub torpedoed" }

You can also explicitly indicate that a single handler is meant to be used for all types of referents like so:

        package LoudDecl;
        use Attribute::Handlers;

        sub SeriousLoud :ATTR(ANY) { warn "Hearing loss imminent" }

(I.e. ATTR(ANY) is a synonym for :ATTR).

Non-interpretive attribute handlers

Occasionally the strenuous efforts Attribute::Handlers makes to convert the data argument ($_[4]) to a useable form before passing it to the handler get in the way.

You can turn off that eagerness-to-help by declaring an attribute handler with the keyword RAWDATA. For example:

        sub Raw          : ATTR(RAWDATA) {...}
        sub Nekkid       : ATTR(SCALAR,RAWDATA) {...}
        sub Au::Naturale : ATTR(RAWDATA,ANY) {...}

Then the handler makes absolutely no attempt to interpret the data it receives and simply passes it as a string:

        my $power : Raw(1..100);        # handlers receives "1..100"

Phase-specific attribute handlers

By default, attribute handlers are called at the end of the compilation phase (in a CHECK block). This seems to be optimal in most cases because most things that can be defined are defined by that point but nothing has been executed.

However, it is possible to set up attribute handlers that are called at other points in the program's compilation or execution, by explicitly stating the phase (or phases) in which you wish the attribute handler to be called. For example:

        sub Early    :ATTR(SCALAR,BEGIN) {...}
        sub Normal   :ATTR(SCALAR,CHECK) {...}
        sub Late     :ATTR(SCALAR,INIT) {...}
        sub Final    :ATTR(SCALAR,END) {...}
        sub Bookends :ATTR(SCALAR,BEGIN,END) {...}

As the last example indicates, a handler may be set up to be (re)called in two or more phases. The phase name is passed as the handler's final argument.

Note that attribute handlers that are scheduled for the BEGIN phase are handled as soon as the attribute is detected (i.e. before any subsequently defined BEGIN blocks are executed).

Attributes as tie interfaces

Attributes make an excellent and intuitive interface through which to tie variables. For example:

        use Attribute::Handlers;
        use Tie::Cycle;

        sub UNIVERSAL::Cycle : ATTR(SCALAR) {
                my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
                $data = [ $data ] unless ref $data eq 'ARRAY';
                tie $$referent, 'Tie::Cycle', $data;
        }

        # and thereafter...

        package main;

        my $next : Cycle('A'..'Z');     # $next is now a tied variable

        while (<>) {
                print $next;
        }

Note that, because the Cycle attribute receives its arguments in the $data variable, if the attribute is given a list of arguments, $data will consist of a single array reference; otherwise, it will consist of the single argument directly. Since Tie::Cycle requires its cycling values to be passed as an array reference, this means that we need to wrap non-array-reference arguments in an array constructor:

        $data = [ $data ] unless ref $data eq 'ARRAY';

Typically, however, things are the other way around: the tieable class expects its arguments as a flattened list, so the attribute looks like:

        sub UNIVERSAL::Cycle : ATTR(SCALAR) {
                my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
                my @data = ref $data eq 'ARRAY' ? @$data : $data;
                tie $$referent, 'Tie::Whatever', @data;
        }

This software pattern is so widely applicable that Attribute::Handlers provides a way to automate it: specifying 'autotie' in the use Attribute::Handlers statement. So, the cycling example, could also be written:

        use Attribute::Handlers autotie => { Cycle => 'Tie::Cycle' };

        # and thereafter...

        package main;

        my $next : Cycle(['A'..'Z']);     # $next is now a tied variable

        while (<>) {
                print $next;

Note that we now have to pass the cycling values as an array reference, since the autotie mechanism passes tie a list of arguments as a list (as in the Tie::Whatever example), not as an array reference (as in the original Tie::Cycle example at the start of this section).

The argument after 'autotie' is a reference to a hash in which each key is the name of an attribute to be created, and each value is the class to which variables ascribed that attribute should be tied.

Note that there is no longer any need to import the Tie::Cycle module -- Attribute::Handlers takes care of that automagically. You can even pass arguments to the module's import subroutine, by appending them to the class name. For example:

        use Attribute::Handlers
                autotie => { Dir => 'Tie::Dir qw(DIR_UNLINK)' };

If the attribute name is unqualified, the attribute is installed in the current package. Otherwise it is installed in the qualifier's package:

        package Here;

        use Attribute::Handlers autotie => {
                Other::Good => Tie::SecureHash, # tie attr installed in Other::
                        Bad => Tie::Taxes,      # tie attr installed in Here::
            UNIVERSAL::Ugly => Software::Patent # tie attr installed everywhere
        };

Autoties are most commonly used in the module to which they actually tie, and need to export their attributes to any module that calls them. To facilitate this, Attribute::Handlers recognizes a special "pseudo-class" -- __CALLER__, which may be specified as the qualifier of an attribute:

        package Tie::Me::Kangaroo:Down::Sport;

        use Attribute::Handlers autotie => { '__CALLER__::Roo' => __PACKAGE__ };

This causes Attribute::Handlers to define the Roo attribute in the package that imports the Tie::Me::Kangaroo:Down::Sport module.

Note that it is important to quote the __CALLER__::Roo identifier because a bug in perl 5.8 will refuse to parse it and cause an unknown error.

Passing the tied object to tie

Occasionally it is important to pass a reference to the object being tied to the TIESCALAR, TIEHASH, etc. that ties it.

The autotie mechanism supports this too. The following code:

        use Attribute::Handlers autotieref => { Selfish => Tie::Selfish };
        my $var : Selfish(@args);

has the same effect as:

        tie my $var, 'Tie::Selfish', @args;

But when "autotieref" is used instead of "autotie":

        use Attribute::Handlers autotieref => { Selfish => Tie::Selfish };
        my $var : Selfish(@args);

the effect is to pass the tie call an extra reference to the variable being tied:

        tie my $var, 'Tie::Selfish', \$var, @args;

EXAMPLES

If the class shown in SYNOPSIS were placed in the MyClass.pm module, then the following code:

        package main;
        use MyClass;

        my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous);

        package SomeOtherClass;
        use base MyClass;

        sub tent { 'acle' }

        sub fn :Ugly(sister) :Omni('po',tent()) {...}
        my @arr :Good :Omni(s/cie/nt/);
        my %hsh :Good(q/bye) :Omni(q/bus/);

would cause the following handlers to be invoked:

        # my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous);

        MyClass::Good:ATTR(SCALAR)( 'MyClass',          # class
                                    'LEXICAL',          # no typeglob
                                    \$slr,              # referent
                                    'Good',             # attr name
                                    undef               # no attr data
                                    'CHECK',            # compiler phase
                                  );

        MyClass::Bad:ATTR(SCALAR)( 'MyClass',           # class
                                   'LEXICAL',           # no typeglob
                                   \$slr,               # referent
                                   'Bad',               # attr name
                                   0                    # eval'd attr data
                                   'CHECK',             # compiler phase
                                 );

        MyClass::Omni:ATTR(SCALAR)( 'MyClass',          # class
                                    'LEXICAL',          # no typeglob
                                    \$slr,              # referent
                                    'Omni',             # attr name
                                    '-vorous'           # eval'd attr data
                                    'CHECK',            # compiler phase
                                  );

        # sub fn :Ugly(sister) :Omni('po',tent()) {...}

        MyClass::UGLY:ATTR(CODE)( 'SomeOtherClass',     # class
                                  \*SomeOtherClass::fn, # typeglob
                                  \&SomeOtherClass::fn, # referent
                                  'Ugly',               # attr name
                                  'sister'              # eval'd attr data
                                  'CHECK',              # compiler phase
                                );

        MyClass::Omni:ATTR(CODE)( 'SomeOtherClass',     # class
                                  \*SomeOtherClass::fn, # typeglob
                                  \&SomeOtherClass::fn, # referent
                                  'Omni',               # attr name
                                  ['po','acle']         # eval'd attr data
                                  'CHECK',              # compiler phase
                                );

        # my @arr :Good :Omni(s/cie/nt/);

        MyClass::Good:ATTR(ARRAY)( 'SomeOtherClass',    # class
                                   'LEXICAL',           # no typeglob
                                   \@arr,               # referent
                                   'Good',              # attr name
                                   undef                # no attr data
                                   'CHECK',             # compiler phase
                                 );

        MyClass::Omni:ATTR(ARRAY)( 'SomeOtherClass',    # class
                                   'LEXICAL',           # no typeglob
                                   \@arr,               # referent
                                   'Omni',              # attr name
                                   ""                   # eval'd attr data
                                   'CHECK',             # compiler phase
                                 );

        # my %hsh :Good(q/bye) :Omni(q/bus/);

        MyClass::Good:ATTR(HASH)( 'SomeOtherClass',     # class
                                  'LEXICAL',            # no typeglob
                                  \%hsh,                # referent
                                  'Good',               # attr name
                                  'q/bye'               # raw attr data
                                  'CHECK',              # compiler phase
                                );

        MyClass::Omni:ATTR(HASH)( 'SomeOtherClass',     # class
                                  'LEXICAL',            # no typeglob
                                  \%hsh,                # referent
                                  'Omni',               # attr name
                                  'bus'                 # eval'd attr data
                                  'CHECK',              # compiler phase
                                );

Installing handlers into UNIVERSAL, makes them...err..universal. For example:

        package Descriptions;
        use Attribute::Handlers;

        my %name;
        sub name { return $name{$_[2]}||*{$_[1]}{NAME} }

        sub UNIVERSAL::Name :ATTR {
                $name{$_[2]} = $_[4];
        }

        sub UNIVERSAL::Purpose :ATTR {
                print STDERR "Purpose of ", &name, " is $_[4]\n";
        }

        sub UNIVERSAL::Unit :ATTR {
                print STDERR &name, " measured in $_[4]\n";
        }

Let's you write:

        use Descriptions;

        my $capacity : Name(capacity)
                     : Purpose(to store max storage capacity for files)
                     : Unit(Gb);

        package Other;

        sub foo : Purpose(to foo all data before barring it) { }

        # etc.

DIAGNOSTICS

Bad attribute type: ATTR(%s)

An attribute handler was specified with an :ATTR(ref_type), but the type of referent it was defined to handle wasn't one of the five permitted: SCALAR, ARRAY, HASH, CODE, or ANY.

Attribute handler %s doesn't handle %s attributes

A handler for attributes of the specified name was defined, but not for the specified type of declaration. Typically encountered whe trying to apply a VAR attribute handler to a subroutine, or a SCALAR attribute handler to some other type of variable.

Declaration of %s attribute in package %s may clash with future reserved word

A handler for an attributes with an all-lowercase name was declared. An attribute with an all-lowercase name might have a meaning to Perl itself some day, even though most don't yet. Use a mixed-case attribute name, instead.

Can't have two ATTR specifiers on one subroutine

You just can't, okay? Instead, put all the specifications together with commas between them in a single ATTR(specification).

Can't autotie a %s

You can only declare autoties for types "SCALAR", "ARRAY", and "HASH". They're the only things (apart from typeglobs -- which are not declarable) that Perl can tie.

Internal error: %s symbol went missing

Something is rotten in the state of the program. An attributed subroutine ceased to exist between the point it was declared and the point at which its attribute handler(s) would have been called.

Won't be able to apply END handler

You have defined an END handler for an attribute that is being applied to a lexical variable. Since the variable may not be available during END this won't happen.

AUTHOR

Damian Conway (damian@conway.org)

BUGS

There are undoubtedly serious bugs lurking somewhere in code this funky :-) Bug reports and other feedback are most welcome.

COPYRIGHT

         Copyright (c) 2001, Damian Conway. All Rights Reserved.
       This module is free software. It may be used, redistributed
           and/or modified under the same terms as Perl itself.


Attribute::Params::Validate - Validate method/function parameters using attributes

    • EXPORT
    • ATTRIBUTES
    • OO
    • CAVEATS
  • SEE ALSO
  • AUTHOR

NAME

Attribute::Params::Validate - Validate method/function parameters using attributes

SYNOPSIS

  use Attribute::Params::Validate qw(:all);

  # takes named params (hash or hashref)
  # foo is mandatory, bar is optional
  sub foo : Validate( foo => 1, bar => 0 )
  {
      ...
  }

  # takes positional params
  # first two are mandatory, third is optional
  sub bar : ValidatePos( 1, 1, 0 )
  {
      ...
  }

  # for some reason Perl insists that the entire attribute be on one line
  sub foo2 : Validate( foo => { type => ARRAYREF }, bar => { can => [ 'print', 'flush', 'frobnicate' ] }, baz => { type => SCALAR, callbacks => { 'numbers only' => sub { shift() =~ /^\d+$/ }, 'less than 90' => sub { shift() < 90 } } } )
  {
      ...
  }

  # note that this is marked as a method.  This is very important!
  sub baz : Validate( foo => { type => ARRAYREF }, bar => { isa => 'Frobnicator' } ) method
  {
      ...
  }

DESCRIPTION

The Attribute::Params::Validate module allows you to validate method or function call parameters just like Params::Validate does. However, this module allows you to specify your validation spec as an attribute, rather than by calling the validate routine.

Please see Params::Validate for more information on how you can specify what validation is performed.

EXPORT

This module exports everthing that Params::Validate does except for the validate and validate_pos subroutines.

ATTRIBUTES

  • Validate

    This attribute corresponse to the validate subroutine in Params::Validate.

  • ValidatePos

    This attribute corresponse to the validate_pos subroutine in Params::Validate.

OO

If you are using this module to mark methods for validation, as opposed to subroutines, it is crucial that you mark these methods with the :method attribute, as well as the Validate or ValidatePos attribute.

If you do not do this, then the object or class used in the method call will be passed to the validation routines, which is probably not what you want.

CAVEATS

You must put all the arguments to the Validate or ValidatePos attribute on a single line, or Perl will complain.

SEE ALSO

Params::Validate

AUTHOR

Dave Rolsky, <autarch@urth.org>


AutoLoader - load subroutines only on demand

    • Subroutine Stubs
    • Using AutoLoader's AUTOLOAD Subroutine
    • Overriding AutoLoader's AUTOLOAD Subroutine
    • Package Lexicals
    • Not Using AutoLoader
    • AutoLoader vs. SelfLoader
  • CAVEATS
  • SEE ALSO

NAME

AutoLoader - load subroutines only on demand

SYNOPSIS

    package Foo;
    use AutoLoader 'AUTOLOAD';   # import the default AUTOLOAD subroutine

    package Bar;
    use AutoLoader;              # don't import AUTOLOAD, define our own
    sub AUTOLOAD {
        ...
        $AutoLoader::AUTOLOAD = "...";
        goto &AutoLoader::AUTOLOAD;
    }

DESCRIPTION

The AutoLoader module works with the AutoSplit module and the __END__ token to defer the loading of some subroutines until they are used rather than loading them all at once.

To use AutoLoader, the author of a module has to place the definitions of subroutines to be autoloaded after an __END__ token. (See the perldata manpage.) The AutoSplit module can then be run manually to extract the definitions into individual files auto/funcname.al.

AutoLoader implements an AUTOLOAD subroutine. When an undefined subroutine in is called in a client module of AutoLoader, AutoLoader's AUTOLOAD subroutine attempts to locate the subroutine in a file with a name related to the location of the file from which the client module was read. As an example, if POSIX.pm is located in /usr/local/lib/perl5/POSIX.pm, AutoLoader will look for perl subroutines POSIX in /usr/local/lib/perl5/auto/POSIX/*.al, where the .al file has the same name as the subroutine, sans package. If such a file exists, AUTOLOAD will read and evaluate it, thus (presumably) defining the needed subroutine. AUTOLOAD will then goto the newly defined subroutine.

Once this process completes for a given function, it is defined, so future calls to the subroutine will bypass the AUTOLOAD mechanism.

Subroutine Stubs

In order for object method lookup and/or prototype checking to operate correctly even when methods have not yet been defined it is necessary to "forward declare" each subroutine (as in sub NAME;). See SYNOPSIS in the perlsub manpage. Such forward declaration creates "subroutine stubs", which are place holders with no code.

The AutoSplit and AutoLoader modules automate the creation of forward declarations. The AutoSplit module creates an 'index' file containing forward declarations of all the AutoSplit subroutines. When the AutoLoader module is 'use'd it loads these declarations into its callers package.

Because of this mechanism it is important that AutoLoader is always used and not required.

Using AutoLoader's AUTOLOAD Subroutine

In order to use AutoLoader's AUTOLOAD subroutine you must explicitly import it:

    use AutoLoader 'AUTOLOAD';

Overriding AutoLoader's AUTOLOAD Subroutine

Some modules, mainly extensions, provide their own AUTOLOAD subroutines. They typically need to check for some special cases (such as constants) and then fallback to AutoLoader's AUTOLOAD for the rest.

Such modules should not import AutoLoader's AUTOLOAD subroutine. Instead, they should define their own AUTOLOAD subroutines along these lines:

    use AutoLoader;
    use Carp;

    sub AUTOLOAD {
        my $sub = $AUTOLOAD;
        (my $constname = $sub) =~ s/.*:://;
        my $val = constant($constname, @_ ? $_[0] : 0);
        if ($! != 0) {
            if ($! =~ /Invalid/ || $!{EINVAL}) {
                $AutoLoader::AUTOLOAD = $sub;
                goto &AutoLoader::AUTOLOAD;
            }
            else {
                croak "Your vendor has not defined constant $constname";
            }
        }
        *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
        goto &$sub;
    }

If any module's own AUTOLOAD subroutine has no need to fallback to the AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit subroutines), then that module should not use AutoLoader at all.

Package Lexicals

Package lexicals declared with my in the main block of a package using AutoLoader will not be visible to auto-loaded subroutines, due to the fact that the given scope ends at the __END__ marker. A module using such variables as package globals will not work properly under the AutoLoader.

The vars pragma (see vars in the perlmod manpage) may be used in such situations as an alternative to explicitly qualifying all globals with the package namespace. Variables pre-declared with this pragma will be visible to any autoloaded routines (but will not be invisible outside the package, unfortunately).

Not Using AutoLoader

You can stop using AutoLoader by simply

        no AutoLoader;

AutoLoader vs. SelfLoader

The AutoLoader is similar in purpose to SelfLoader: both delay the loading of subroutines.

SelfLoader uses the __DATA__ marker rather than __END__. While this avoids the use of a hierarchy of disk files and the associated open/close for each routine loaded, SelfLoader suffers a startup speed disadvantage in the one-time parsing of the lines after __DATA__, after which routines are cached. SelfLoader can also handle multiple packages in a file.

AutoLoader only reads code as it is requested, and in many cases should be faster, but requires a mechanism like AutoSplit be used to create the individual files. the ExtUtils::MakeMaker manpage will invoke AutoSplit automatically if AutoLoader is used in a module source file.

CAVEATS

AutoLoaders prior to Perl 5.002 had a slightly different interface. Any old modules which use AutoLoader should be changed to the new calling style. Typically this just means changing a require to a use, adding the explicit 'AUTOLOAD' import if needed, and removing AutoLoader from @ISA.

On systems with restrictions on file name length, the file corresponding to a subroutine may have a shorter name that the routine itself. This can lead to conflicting file names. The AutoSplit package warns of these potential conflicts when used to split a module.

AutoLoader may fail to find the autosplit files (or even find the wrong ones) in cases where @INC contains relative paths, and the program does chdir.

SEE ALSO

the SelfLoader manpage - an autoloader that doesn't use external files.


AutoSplit - split a package for autoloading

    • Multiple packages
  • DIAGNOSTICS

NAME

AutoSplit - split a package for autoloading

SYNOPSIS

 autosplit($file, $dir, $keep, $check, $modtime);

 autosplit_lib_modules(@modules);

DESCRIPTION

This function will split up your program into files that the AutoLoader module can handle. It is used by both the standard perl libraries and by the MakeMaker utility, to automatically configure libraries for autoloading.

The autosplit interface splits the specified file into a hierarchy rooted at the directory $dir. It creates directories as needed to reflect class hierarchy, and creates the file autosplit.ix. This file acts as both forward declaration of all package routines, and as timestamp for the last update of the hierarchy.

The remaining three arguments to autosplit govern other options to the autosplitter.

$keep

If the third argument, $keep, is false, then any pre-existing *.al files in the autoload directory are removed if they are no longer part of the module (obsoleted functions). $keep defaults to 0.

$check

The fourth argument, $check, instructs autosplit to check the module currently being split to ensure that it includes a use specification for the AutoLoader module, and skips the module if AutoLoader is not detected. $check defaults to 1.

$modtime

Lastly, the $modtime argument specifies that autosplit is to check the modification time of the module against that of the autosplit.ix file, and only split the module if it is newer. $modtime defaults to 1.

Typical use of AutoSplit in the perl MakeMaker utility is via the command-line with:

 perl -e 'use AutoSplit; autosplit($ARGV[0], $ARGV[1], 0, 1, 1)'

Defined as a Make macro, it is invoked with file and directory arguments; autosplit will split the specified file into the specified directory and delete obsolete .al files, after checking first that the module does use the AutoLoader, and ensuring that the module is not already currently split in its current form (the modtime test).

The autosplit_lib_modules form is used in the building of perl. It takes as input a list of files (modules) that are assumed to reside in a directory lib relative to the current directory. Each file is sent to the autosplitter one at a time, to be split into the directory lib/auto.

In both usages of the autosplitter, only subroutines defined following the perl __END__ token are split out into separate files. Some routines may be placed prior to this marker to force their immediate loading and parsing.

Multiple packages

As of version 1.01 of the AutoSplit module it is possible to have multiple packages within a single file. Both of the following cases are supported:

   package NAME;
   __END__
   sub AAA { ... }
   package NAME::option1;
   sub BBB { ... }
   package NAME::option2;
   sub BBB { ... }

   package NAME;
   __END__
   sub AAA { ... }
   sub NAME::option1::BBB { ... }
   sub NAME::option2::BBB { ... }

DIAGNOSTICS

AutoSplit will inform the user if it is necessary to create the top-level directory specified in the invocation. It is preferred that the script or installation process that invokes AutoSplit have created the full directory path ahead of time. This warning may indicate that the module is being split into an incorrect path.

AutoSplit will warn the user of all subroutines whose name causes potential file naming conflicts on machines with drastically limited (8 characters or less) file name length. Since the subroutine name is used as the file name, these warnings can aid in portability to such systems.

Warnings are issued and the file skipped if AutoSplit cannot locate either the __END__ marker or a "package Name;"-style specification.

AutoSplit will also emit general diagnostics for inability to create directories or files.


B - The Perl Compiler

  • OVERVIEW
  • Utility Functions
    • Functions Returning B::SV, B::AV, B::HV, and B::CV objects
    • Functions for Examining the Symbol Table
    • Functions Returning B::OP objects or for walking op trees
    • Miscellaneous Utility Functions
  • OVERVIEW OF CLASSES
    • SV-RELATED CLASSES
    • B::SV Methods
    • B::IV Methods
    • B::NV Methods
    • B::RV Methods
    • B::PV Methods
    • B::PVMG Methods
    • B::MAGIC Methods
    • B::PVLV Methods
    • B::BM Methods
    • B::GV Methods
    • B::IO Methods
    • B::AV Methods
    • B::CV Methods
    • B::HV Methods
    • OP-RELATED CLASSES
    • B::OP Methods
    • B::UNOP METHOD
    • B::BINOP METHOD
    • B::LOGOP METHOD
    • B::LISTOP METHOD
    • B::PMOP Methods
    • B::SVOP METHOD
    • B::PADOP METHOD
    • B::PVOP METHOD
    • B::LOOP Methods
    • B::COP Methods
  • AUTHOR

NAME

B - The Perl Compiler

SYNOPSIS

        use B;

DESCRIPTION

The B module supplies classes which allow a Perl program to delve into its own innards. It is the module used to implement the "backends" of the Perl compiler. Usage of the compiler does not require knowledge of this module: see the O module for the user-visible part. The B module is of use to those who want to write new compiler backends. This documentation assumes that the reader knows a fair amount about perl's internals including such things as SVs, OPs and the internal symbol table and syntax tree of a program.

OVERVIEW

The B module contains a set of utility functions for querying the current state of the Perl interpreter; typically these functions return objects from the B::SV and B::OP classes, or their derived classes. These classes in turn define methods for querying the resulting objects about their own internal state.

Utility Functions

The B module exports a variety of functions: some are simple utility functions, others provide a Perl program with a way to get an initial "handle" on an internal object.

Functions Returning B::SV, B::AV, B::HV, and B::CV objects

For descriptions of the class hierarchy of these objects and the methods that can be called on them, see below, OVERVIEW OF CLASSES and SV-RELATED CLASSES.

sv_undef

Returns the SV object corresponding to the C variable sv_undef.

sv_yes

Returns the SV object corresponding to the C variable sv_yes.

sv_no

Returns the SV object corresponding to the C variable sv_no.

svref_2object(SVREF)

Takes a reference to any Perl value, and turns the referred-to value into an object in the appropriate B::OP-derived or B::SV-derived class. Apart from functions such as main_root, this is the primary way to get an initial "handle" on an internal perl data structure which can then be followed with the other access methods.

The returned object will only be valid as long as the underlying OPs and SVs continue to exist. Do not attempt to use the object after the underlying structures are freed.

amagic_generation

Returns the SV object corresponding to the C variable amagic_generation.

init_av

Returns the AV object (i.e. in class B::AV) representing INIT blocks.

check_av

Returns the AV object (i.e. in class B::AV) representing CHECK blocks.

begin_av

Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.

end_av

Returns the AV object (i.e. in class B::AV) representing END blocks.

comppadlist

Returns the AV object (i.e. in class B::AV) of the global comppadlist.

regex_padav

Only when perl was compiled with ithreads.

main_cv

Return the (faked) CV corresponding to the main part of the Perl program.

Functions for Examining the Symbol Table

walksymtable(SYMREF, METHOD, RECURSE, PREFIX)

Walk the symbol table starting at SYMREF and call METHOD on each symbol (a B::GV object) visited. When the walk reaches package symbols (such as "Foo::") it invokes RECURSE, passing in the symbol name, and only recurses into the package if that sub returns true.

PREFIX is the name of the SYMREF you're walking.

For example:

  # Walk CGI's symbol table calling print_subs on each symbol.
  # Recurse only into CGI::Util::
  walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' },
               'CGI::');

print_subs() is a B::GV method you have declared. Also see B::GV Methods, below.

Functions Returning B::OP objects or for walking op trees

For descriptions of the class hierarchy of these objects and the methods that can be called on them, see below, OVERVIEW OF CLASSES and OP-RELATED CLASSES.

main_root

Returns the root op (i.e. an object in the appropriate B::OP-derived class) of the main part of the Perl program.

main_start

Returns the starting op of the main part of the Perl program.

walkoptree(OP, METHOD)

Does a tree-walk of the syntax tree based at OP and calls METHOD on each op it visits. Each node is visited before its children. If walkoptree_debug (see below) has been called to turn debugging on then the method walkoptree_debug is called on each op before METHOD is called.

walkoptree_debug(DEBUG)

Returns the current debugging flag for walkoptree. If the optional DEBUG argument is non-zero, it sets the debugging flag to that. See the description of walkoptree above for what the debugging flag does.

Miscellaneous Utility Functions

ppname(OPNUM)

Return the PP function name (e.g. "pp_add") of op number OPNUM.

hash(STR)

Returns a string in the form "0x..." representing the value of the internal hash function used by perl on string STR.

cast_I32(I)

Casts I to the internal I32 type used by that perl.

minus_c

Does the equivalent of the -c command-line option. Obviously, this is only useful in a BEGIN block or else the flag is set too late.

cstring(STR)

Returns a double-quote-surrounded escaped version of STR which can be used as a string in C source code.

perlstring(STR)

Returns a double-quote-surrounded escaped version of STR which can be used as a string in Perl source code.

class(OBJ)

Returns the class of an object without the part of the classname preceding the first "::". This is used to turn "B::UNOP" into "UNOP" for example.

threadsv_names

In a perl compiled for threads, this returns a list of the special per-thread threadsv variables.

OVERVIEW OF CLASSES

The C structures used by Perl's internals to hold SV and OP information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a class hierarchy and the B module gives access to them via a true object hierarchy. Structure fields which point to other objects (whether types of SV or types of OP) are represented by the B module as Perl objects of the appropriate class.

The bulk of the B module is the methods for accessing fields of these structures.

Note that all access is read-only. You cannot modify the internals by using this module. Also, note that the B::OP and B::SV objects created by this module are only valid for as long as the underlying objects exist; their creation doesn't increase the reference counts of the underlying objects. Trying to access the fields of a freed object will give incomprehensible results, or worse.

SV-RELATED CLASSES

B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM, B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes correspond in the obvious way to the underlying C structures of similar names. The inheritance hierarchy mimics the underlying C "inheritance". For 5.9.1 and later this is:

                             B::SV
                               |
                +--------------+----------+------------+
                |              |          |            |
              B::PV          B::IV      B::NV        B::RV
                   \         /          /
                    \       /          /
                     B::PVIV          /
                         \           /
                          \         /
                           \       /
                            B::PVNV
                               |
                               |
                            B::PVMG
                               |
                    +-----+----+------+-----+-----+
                    |     |    |      |     |     |
                  B::BM B::AV B::GV B::HV B::CV B::IO
                               |            |
                            B::PVLV         |
                                          B::FM

For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, so the base of this diagram is

                           |
                        B::PVMG
                           |
         +------+-----+----+------+-----+-----+
         |      |     |    |      |     |     |
      B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
                                        |
                                        |
                                      B::FM

Access methods correspond to the underlying C macros for field access, usually with the leading "class indication" prefix removed (Sv, Av, Hv, ...). The leading prefix is only left in cases where its removal would cause a clash in method name. For example, GvREFCNT stays as-is since its abbreviation would clash with the "superclass" method REFCNT (corresponding to the C function SvREFCNT).

B::SV Methods

REFCNT
FLAGS
object_2svref

Returns a reference to the regular scalar corresponding to this B::SV object. In other words, this method is the inverse operation to the svref_2object() subroutine. This scalar and other data it points at should be considered read-only: modifying them is neither safe nor guaranteed to have a sensible effect.

B::IV Methods

IV

Returns the value of the IV, interpreted as a signed integer. This will be misleading if FLAGS & SVf_IVisUV. Perhaps you want the int_value method instead?

IVX
UVX
int_value

This method returns the value of the IV as an integer. It differs from IV in that it returns the correct value regardless of whether it's stored signed or unsigned.

needs64bits
packiv

B::NV Methods

NV
NVX

B::RV Methods

RV

B::PV Methods

PV

This method is the one you usually want. It constructs a string using the length and offset information in the struct: for ordinary scalars it will return the string that you'd see from Perl, even if it contains null characters.

RV

Same as B::RV::RV, except that it will die() if the PV isn't a reference.

PVX

This method is less often useful. It assumes that the string stored in the struct is null-terminated, and disregards the length information.

It is the appropriate method to use if you need to get the name of a lexical variable from a padname array. Lexical variable names are always stored with a null terminator, and the length field (SvCUR) is overloaded for other purposes and can't be relied on here.

B::PVMG Methods

MAGIC
SvSTASH

B::MAGIC Methods

MOREMAGIC
precomp

Only valid on r-magic, returns the string that generated the regexp.

PRIVATE
TYPE
FLAGS
OBJ

Will die() if called on r-magic.

PTR
REGEX

Only valid on r-magic, returns the integer value of the REGEX stored in the MAGIC.

B::PVLV Methods

TARGOFF
TARGLEN
TYPE
TARG

B::BM Methods

USEFUL
PREVIOUS
RARE
TABLE

B::GV Methods

is_empty

This method returns TRUE if the GP field of the GV is NULL.

NAME
SAFENAME

This method returns the name of the glob, but if the first character of the name is a control character, then it converts it to ^X first, so that *^G would return "^G" rather than "\cG".

It's useful if you want to print out the name of a variable. If you restrict yourself to globs which exist at compile-time then the result ought to be unambiguous, because code like ${"^G"} = 1 is compiled as two ops - a constant string and a dereference (rv2gv) - so that the glob is created at runtime.

If you're working with globs at runtime, and need to disambiguate *^G from *{"^G"}, then you should use the raw NAME method.

STASH
SV
IO
FORM
AV
HV
EGV
CV
CVGEN
LINE
FILE
FILEGV
GvREFCNT
FLAGS

B::IO Methods

LINES
PAGE
PAGE_LEN
LINES_LEFT
TOP_NAME
TOP_GV
FMT_NAME
FMT_GV
BOTTOM_NAME
BOTTOM_GV
SUBPROCESS
IoTYPE
IoFLAGS
IsSTD

Takes one arguments ( 'stdin' | 'stdout' | 'stderr' ) and returns true if the IoIFP of the object is equal to the handle whose name was passed as argument ( i.e. $io->IsSTD('stderr') is true if IoIFP($io) == PerlIO_stdin() ).

B::AV Methods

FILL
MAX
OFF
ARRAY
ARRAYelt

Like ARRAY, but takes an index as an argument to get only one element, rather than a list of all of them.

AvFLAGS

B::CV Methods

STASH
START
ROOT
GV
FILE
DEPTH
PADLIST
OUTSIDE
OUTSIDE_SEQ
XSUB
XSUBANY

For constant subroutines, returns the constant SV returned by the subroutine.

CvFLAGS
const_sv

B::HV Methods

FILL
MAX
KEYS
RITER
NAME
PMROOT
ARRAY

OP-RELATED CLASSES

B::OP, B::UNOP, B::BINOP, B::LOGOP, B::LISTOP, B::PMOP, B::SVOP, B::PADOP, B::PVOP, B::LOOP, B::COP.

These classes correspond in the obvious way to the underlying C structures of similar names. The inheritance hierarchy mimics the underlying C "inheritance":

                                 B::OP
                                   |
                   +---------------+--------+--------+
                   |               |        |        |
                B::UNOP          B::SVOP B::PADOP  B::COP
                 ,'  `-.
                /       `--.
           B::BINOP     B::LOGOP
               |
               |
           B::LISTOP
             ,' `.
            /     \
        B::LOOP B::PMOP

Access methods correspond to the underlying C structre field names, with the leading "class indication" prefix ("op_") removed.

B::OP Methods

These methods get the values of similarly named fields within the OP data structure. See top of op.h for more info.

next
sibling
name

This returns the op name as a string (e.g. "add", "rv2av").

ppaddr

This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").

desc

This returns the op description from the global C PL_op_desc array (e.g. "addition" "array deref").

targ
type
opt
static
flags
private
spare

B::UNOP METHOD

first

B::BINOP METHOD

last

B::LOGOP METHOD

other

B::LISTOP METHOD

children

B::PMOP Methods

pmreplroot
pmreplstart
pmnext
pmregexp
pmflags
pmdynflags
pmpermflags
precomp
pmoffset

Only when perl was compiled with ithreads.

B::SVOP METHOD

sv
gv

B::PADOP METHOD

padix

B::PVOP METHOD

pv

B::LOOP Methods

redoop
nextop
lastop

B::COP Methods

label
stash
stashpv
file
cop_seq
arybase
line
warnings
io

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Asmdata - Autogenerated data about Perl ops, used to generate bytecode

  • AUTHOR

NAME

B::Asmdata - Autogenerated data about Perl ops, used to generate bytecode

SYNOPSIS

        use B::Asmdata qw(%insn_data @insn_name @optype @specialsv_name);

DESCRIPTION

Provides information about Perl ops in order to generate bytecode via a bunch of exported variables. Its mostly used by B::Assembler and B::Disassembler.

%insn_data
  my($bytecode_num, $put_sub, $get_meth) = @$insn_data{$op_name};

For a given $op_name (for example, 'cop_label', 'sv_flags', etc...) you get an array ref containing the bytecode number of the op, a reference to the subroutine used to 'PUT', and the name of the method used to 'GET'.

@insn_name
  my $op_name = $insn_name[$bytecode_num];

A simple mapping of the bytecode number to the name of the op. Suitable for using with %insn_data like so:

  my $op_info = $insn_data{$insn_name[$bytecode_num]};
@optype
  my $op_type = $optype[$op_type_num];

A simple mapping of the op type number to its type (like 'COP' or 'BINOP').

@specialsv_name
  my $sv_name = $specialsv_name[$sv_index];

Certain SV types are considered 'special'. They're represented by B::SPECIAL and are referred to by a number from the specialsv_list. This array maps that number back to the name of the SV (like 'Nullsv' or '&PL_sv_undef').

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Assembler - Assemble Perl bytecode

  • AUTHORS

NAME

B::Assembler - Assemble Perl bytecode

SYNOPSIS

        use B::Assembler qw(newasm endasm assemble);
        newasm(\&printsub);     # sets up for assembly
        assemble($buf);         # assembles one line
        endasm();               # closes down

        use B::Assembler qw(assemble_fh);
        assemble_fh($fh, \&printsub);   # assemble everything in $fh

DESCRIPTION

See ext/B/B/Assembler.pm.

AUTHORS

Malcolm Beattie, mbeattie@sable.ox.ac.uk Per-statement interface by Benjamin Stuhl, sho_pi@hotmail.com


B::Bblock - Walk basic blocks

    • Functions
  • AUTHOR

NAME

B::Bblock - Walk basic blocks

SYNOPSIS

  # External interface
  perl -MO=Bblock[,OPTIONS] foo.pl
  # Programmatic API
  use B::Bblock qw(find_leaders);
  my $leaders = find_leaders($root_op, $start_op);

DESCRIPTION

This module is used by the B::CC back end. It walks "basic blocks". A basic block is a series of operations which is known to execute from start to finish, with no possibility of branching or halting.

It can be used either stand alone or from inside another program.

Functions

find_leaders
  my $leaders = find_leaders($root_op, $start_op);

Given the root of the op tree and an op from which to start processing, it will return a hash ref representing all the ops which start a block.

The values of %$leaders are the op objects themselves. Keys are $$op addresses.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Bytecode - Perl compiler's bytecode backend

  • EXAMPLE
  • OPTIONS
  • KNOWN BUGS
  • NOTICE
  • AUTHORS

NAME

B::Bytecode - Perl compiler's bytecode backend

SYNOPSIS

perl -MO=Bytecode[,-H][,-o script.plc] script.pl

DESCRIPTION

Compiles a Perl script into a bytecode format that could be loaded later by the ByteLoader module and executed as a regular Perl script.

EXAMPLE

    $ perl -MO=Bytecode,-H,-ohi -e 'print "hi!\n"'
    $ perl hi
    hi!

OPTIONS

-b

Save all the BEGIN blocks. Normally only BEGIN blocks that require other files (ex. use Foo;) are saved.

-H

prepend a use ByteLoader VERSION; line to the produced bytecode.

-k

keep the syntax tree - it is stripped by default.

-o outfile

put the bytecode in <outfile> instead of dumping it to STDOUT.

-s

scan the script for # line .. directives and for <goto LABEL> expressions. When gotos are found keep the syntax tree.

KNOWN BUGS

  • BEGIN { goto A: while 1; A: } won't even compile.

  • ?...? and reset do not work as expected.

  • variables in (?{ ... }) constructs are not properly scoped.

  • scripts that use source filters will fail miserably.

NOTICE

There are also undocumented bugs and options.

THIS CODE IS HIGHLY EXPERIMENTAL. USE AT YOUR OWN RISK.

AUTHORS

Originally written by Malcolm Beattie <mbeattie@sable.ox.ac.uk> and modified by Benjamin Stuhl <sho_pi@hotmail.com>.

Rewritten by Enache Adrian <enache@rdslink.ro>, 2003 a.d.


B::C - Perl compiler's C backend

  • OPTIONS
  • EXAMPLES
  • BUGS
  • AUTHOR

NAME

B::C - Perl compiler's C backend

SYNOPSIS

        perl -MO=C[,OPTIONS] foo.pl

DESCRIPTION

This compiler backend takes Perl source and generates C source code corresponding to the internal structures that perl uses to run your program. When the generated C source is compiled and run, it cuts out the time which perl would have taken to load and parse your program into its internal semi-compiled form. That means that compiling with this backend will not help improve the runtime execution speed of your program but may improve the start-up time. Depending on the environment in which your program runs this may be either a help or a hindrance.

OPTIONS

If there are any non-option arguments, they are taken to be names of objects to be saved (probably doesn't work properly yet). Without extra arguments, it saves the main program.

-ofilename

Output to filename instead of STDOUT

-v

Verbose compilation (currently gives a few compilation statistics).

--

Force end of options

-uPackname

Force apparently unused subs from package Packname to be compiled. This allows programs to use eval "foo()" even when sub foo is never seen to be used at compile time. The down side is that any subs which really are never used also have code generated. This option is necessary, for example, if you have a signal handler foo which you initialise with $SIG{BAR} = "foo". A better fix, though, is just to change it to $SIG{BAR} = \&foo. You can have multiple -u options. The compiler tries to figure out which packages may possibly have subs in which need compiling but the current version doesn't do it very well. In particular, it is confused by nested packages (i.e. of the form A::B) where package A does not contain any subs.

-D

Debug options (concatenated or separate flags like perl -D).

-Do

OPs, prints each OP as it's processed

-Dc

COPs, prints COPs as processed (incl. file & line num)

-DA

prints AV information on saving

-DC

prints CV information on saving

-DM

prints MAGIC information on saving

-f

Force options/optimisations on or off one at a time. You can explicitly disable an option using -fno-option. All options default to disabled.

-fcog

Copy-on-grow: PVs declared and initialised statically.

-fsave-data

Save package::DATA filehandles ( only available with PerlIO ).

-fppaddr

Optimize the initialization of op_ppaddr.

-fwarn-sv

Optimize the initialization of cop_warnings.

-fuse-script-name

Use the script name instead of the program name as $0.

-fsave-sig-hash

Save compile-time modifications to the %SIG hash.

-On

Optimisation level (n = 0, 1, 2, ...). -O means -O1.

-O0

Disable all optimizations.

-O1

Enable -fcog.

-O2

Enable -fppaddr, -fwarn-sv.

-llimit

Some C compilers impose an arbitrary limit on the length of string constants (e.g. 2048 characters for Microsoft Visual C++). The -llimit options tells the C backend not to generate string literals exceeding that limit.

EXAMPLES

    perl -MO=C,-ofoo.c foo.pl
    perl cc_harness -o foo foo.c

Note that cc_harness lives in the B subdirectory of your perl library directory. The utility called perlcc may also be used to help make use of this compiler.

    perl -MO=C,-v,-DcA,-l2048 bar.pl > /dev/null

BUGS

Plenty. Current status: experimental.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::CC - Perl compiler's optimized C translation backend

  • OPTIONS
  • EXAMPLES
  • BUGS
  • DIFFERENCES
    • Loops
    • Context of ".."
    • Arithmetic
    • Deprecated features
  • AUTHOR

NAME

B::CC - Perl compiler's optimized C translation backend

SYNOPSIS

        perl -MO=CC[,OPTIONS] foo.pl

DESCRIPTION

This compiler backend takes Perl source and generates C source code corresponding to the flow of your program. In other words, this backend is somewhat a "real" compiler in the sense that many people think about compilers. Note however that, currently, it is a very poor compiler in that although it generates (mostly, or at least sometimes) correct code, it performs relatively few optimisations. This will change as the compiler develops. The result is that running an executable compiled with this backend may start up more quickly than running the original Perl program (a feature shared by the C compiler backend--see B::C) and may also execute slightly faster. This is by no means a good optimising compiler--yet.

OPTIONS

If there are any non-option arguments, they are taken to be names of objects to be saved (probably doesn't work properly yet). Without extra arguments, it saves the main program.

-ofilename

Output to filename instead of STDOUT

-v

Verbose compilation (currently gives a few compilation statistics).

--

Force end of options

-uPackname

Force apparently unused subs from package Packname to be compiled. This allows programs to use eval "foo()" even when sub foo is never seen to be used at compile time. The down side is that any subs which really are never used also have code generated. This option is necessary, for example, if you have a signal handler foo which you initialise with $SIG{BAR} = "foo". A better fix, though, is just to change it to $SIG{BAR} = \&foo. You can have multiple -u options. The compiler tries to figure out which packages may possibly have subs in which need compiling but the current version doesn't do it very well. In particular, it is confused by nested packages (i.e. of the form A::B) where package A does not contain any subs.

-mModulename

Instead of generating source for a runnable executable, generate source for an XSUB module. The boot_Modulename function (which DynaLoader can look for) does the appropriate initialisation and runs the main part of the Perl source that is being compiled.

-D

Debug options (concatenated or separate flags like perl -D).

-Dr

Writes debugging output to STDERR just as it's about to write to the program's runtime (otherwise writes debugging info as comments in its C output).

-DO

Outputs each OP as it's compiled

-Ds

Outputs the contents of the shadow stack at each OP

-Dp

Outputs the contents of the shadow pad of lexicals as it's loaded for each sub or the main program.

-Dq

Outputs the name of each fake PP function in the queue as it's about to process it.

-Dl

Output the filename and line number of each original line of Perl code as it's processed (pp_nextstate).

-Dt

Outputs timing information of compilation stages.

-f

Force optimisations on or off one at a time.

-ffreetmps-each-bblock

Delays FREETMPS from the end of each statement to the end of the each basic block.

-ffreetmps-each-loop

Delays FREETMPS from the end of each statement to the end of the group of basic blocks forming a loop. At most one of the freetmps-each-* options can be used.

-fomit-taint

Omits generating code for handling perl's tainting mechanism.

-On

Optimisation level (n = 0, 1, 2, ...). -O means -O1. Currently, -O1 sets -ffreetmps-each-bblock and -O2 sets -ffreetmps-each-loop.

EXAMPLES

        perl -MO=CC,-O2,-ofoo.c foo.pl
        perl cc_harness -o foo foo.c

Note that cc_harness lives in the B subdirectory of your perl library directory. The utility called perlcc may also be used to help make use of this compiler.

        perl -MO=CC,-mFoo,-oFoo.c Foo.pm
        perl cc_harness -shared -c -o Foo.so Foo.c

BUGS

Plenty. Current status: experimental.

DIFFERENCES

These aren't really bugs but they are constructs which are heavily tied to perl's compile-and-go implementation and with which this compiler backend cannot cope.

Loops

Standard perl calculates the target of "next", "last", and "redo" at run-time. The compiler calculates the targets at compile-time. For example, the program

    sub skip_on_odd { next NUMBER if $_[0] % 2 }
    NUMBER: for ($i = 0; $i < 5; $i++) {
        skip_on_odd($i);
        print $i;
    }

produces the output

    024

with standard perl but gives a compile-time error with the compiler.

Context of ".."

The context (scalar or array) of the ".." operator determines whether it behaves as a range or a flip/flop. Standard perl delays until runtime the decision of which context it is in but the compiler needs to know the context at compile-time. For example,

    @a = (4,6,1,0,0,1);
    sub range { (shift @a)..(shift @a) }
    print range();
    while (@a) { print scalar(range()) }

generates the output

    456123E0

with standard Perl but gives a compile-time error with compiled Perl.

Arithmetic

Compiled Perl programs use native C arithmetic much more frequently than standard perl. Operations on large numbers or on boundary cases may produce different behaviour.

Deprecated features

Features of standard perl such as $[ which have been deprecated in standard perl since Perl5 was released have not been implemented in the compiler.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Concise - Walk Perl syntax tree, printing concise info about ops

  • EXAMPLE
  • OPTIONS
    • Options for Opcode Ordering
    • Options for Line-Style
    • Options for tree-specific formatting
    • Options controlling sequence numbering
    • Other options
    • Option Stickiness
  • ABBREVIATIONS
    • OP class abbreviations
    • OP flags abbreviations
  • FORMATTING SPECIFICATIONS
    • Special Patterns
    • # Variables
  • Using B::Concise outside of the O framework
    • Example: Altering Concise Renderings
    • set_style()
    • set_style_standard($name)
    • add_style()
    • add_callback()
    • Running B::Concise::compile()
    • B::Concise::reset_sequence()
    • Errors
  • AUTHOR

NAME

B::Concise - Walk Perl syntax tree, printing concise info about ops

SYNOPSIS

    perl -MO=Concise[,OPTIONS] foo.pl
    use B::Concise qw(set_style add_callback);

DESCRIPTION

This compiler backend prints the internal OPs of a Perl program's syntax tree in one of several space-efficient text formats suitable for debugging the inner workings of perl or other compiler backends. It can print OPs in the order they appear in the OP tree, in the order they will execute, or in a text approximation to their tree structure, and the format of the information displayed is customizable. Its function is similar to that of perl's -Dx debugging flag or the B::Terse module, but it is more sophisticated and flexible.

EXAMPLE

Here's an example of 2 outputs (aka 'renderings'), using the -exec and -basic (i.e. default) formatting conventions on the same code snippet.

    % perl -MO=Concise,-exec -e '$a = $b + 42'
    1  <0> enter
    2  <;> nextstate(main 1 -e:1) v
    3  <#> gvsv[*b] s
    4  <$> const[IV 42] s
     *  5  <2> add[t3] sK/2
    6  <#> gvsv[*a] s
    7  <2> sassign vKS/2
    8  <@> leave[1 ref] vKP/REFC

Each line corresponds to an opcode. The opcode marked with '*' is used in a few examples below.

The 1st column is the op's sequence number, starting at 1, and is displayed in base 36 by default. This rendering is in -exec (i.e. execution) order.

The symbol between angle brackets indicates the op's type, for example; <2> is a BINOP, <@> a LISTOP, and <#> is a PADOP, which is used in threaded perls. (see OP class abbreviations).

The opname, as in 'add[t1]', which may be followed by op-specific information in parentheses or brackets (ex '[t1]').

The op-flags (ex 'sK/2') follow, and are described in (OP flags abbreviations).

    % perl -MO=Concise -e '$a = $b + 42'
    8  <@> leave[1 ref] vKP/REFC ->(end)
    1     <0> enter ->2
    2     <;> nextstate(main 1 -e:1) v ->3
    7     <2> sassign vKS/2 ->8
     *  5        <2> add[t1] sK/2 ->6
    -           <1> ex-rv2sv sK/1 ->4
    3              <$> gvsv(*b) s ->4
    4           <$> const(IV 42) s ->5
    -        <1> ex-rv2sv sKRM*/1 ->7
    6           <$> gvsv(*a) s ->7

The default rendering is top-down, so they're not in execution order. This form reflects the way the stack is used to parse and evaluate expressions; the add operates on the two terms below it in the tree.

Nullops appear as ex-opname, where opname is an op that has been optimized away by perl. They're displayed with a sequence-number of '-', because they are not executed (they don't appear in previous example), they're printed here because they reflect the parse.

The arrow points to the sequence number of the next op; they're not displayed in -exec mode, for obvious reasons.

Note that because this rendering was done on a non-threaded perl, the PADOPs in the previous examples are now SVOPs, and some (but not all) of the square brackets have been replaced by round ones. This is a subtle feature to provide some visual distinction between renderings on threaded and un-threaded perls.

OPTIONS

Arguments that don't start with a hyphen are taken to be the names of subroutines to print the OPs of; if no such functions are specified, the main body of the program (outside any subroutines, and not including use'd or require'd files) is rendered. Passing BEGIN, CHECK, INIT, or END will cause all of the corresponding special blocks to be printed.

Options affect how things are rendered (ie printed). They're presented here by their visual effect, 1st being strongest. They're grouped according to how they interrelate; within each group the options are mutually exclusive (unless otherwise stated).

Options for Opcode Ordering

These options control the 'vertical display' of opcodes. The display 'order' is also called 'mode' elsewhere in this document.

-basic

Print OPs in the order they appear in the OP tree (a preorder traversal, starting at the root). The indentation of each OP shows its level in the tree, and the '->' at the end of the line indicates the next opcode in execution order. This mode is the default, so the flag is included simply for completeness.

-exec

Print OPs in the order they would normally execute (for the majority of constructs this is a postorder traversal of the tree, ending at the root). In most cases the OP that usually follows a given OP will appear directly below it; alternate paths are shown by indentation. In cases like loops when control jumps out of a linear path, a 'goto' line is generated.

-tree

Print OPs in a text approximation of a tree, with the root of the tree at the left and 'left-to-right' order of children transformed into 'top-to-bottom'. Because this mode grows both to the right and down, it isn't suitable for large programs (unless you have a very wide terminal).

Options for Line-Style

These options select the line-style (or just style) used to render each opcode, and dictates what info is actually printed into each line.

-concise

Use the author's favorite set of formatting conventions. This is the default, of course.

-terse

Use formatting conventions that emulate the output of B::Terse. The basic mode is almost indistinguishable from the real B::Terse, and the exec mode looks very similar, but is in a more logical order and lacks curly brackets. B::Terse doesn't have a tree mode, so the tree mode is only vaguely reminiscent of B::Terse.

-linenoise

Use formatting conventions in which the name of each OP, rather than being written out in full, is represented by a one- or two-character abbreviation. This is mainly a joke.

-debug

Use formatting conventions reminiscent of B::Debug; these aren't very concise at all.

-env

Use formatting conventions read from the environment variables B_CONCISE_FORMAT, B_CONCISE_GOTO_FORMAT, and B_CONCISE_TREE_FORMAT.

Options for tree-specific formatting

-compact

Use a tree format in which the minimum amount of space is used for the lines connecting nodes (one character in most cases). This squeezes out a few precious columns of screen real estate.

-loose

Use a tree format that uses longer edges to separate OP nodes. This format tends to look better than the compact one, especially in ASCII, and is the default.

-vt

Use tree connecting characters drawn from the VT100 line-drawing set. This looks better if your terminal supports it.

-ascii

Draw the tree with standard ASCII characters like + and |. These don't look as clean as the VT100 characters, but they'll work with almost any terminal (or the horizontal scrolling mode of less(1)) and are suitable for text documentation or email. This is the default.

These are pairwise exclusive, i.e. compact or loose, vt or ascii.

Options controlling sequence numbering

-base n

Print OP sequence numbers in base n. If n is greater than 10, the digit for 11 will be 'a', and so on. If n is greater than 36, the digit for 37 will be 'A', and so on until 62. Values greater than 62 are not currently supported. The default is 36.

-bigendian

Print sequence numbers with the most significant digit first. This is the usual convention for Arabic numerals, and the default.

-littleendian

Print seqence numbers with the least significant digit first. This is obviously mutually exclusive with bigendian.

Other options

These are pairwise exclusive.

-main

Include the main program in the output, even if subroutines were also specified. This rendering is normally suppressed when a subroutine name or reference is given.

-nomain

This restores the default behavior after you've changed it with '-main' (it's not normally needed). If no subroutine name/ref is given, main is rendered, regardless of this flag.

-nobanner

Renderings usually include a banner line identifying the function name or stringified subref. This suppresses the printing of the banner.

TBC: Remove the stringified coderef; while it provides a 'cookie' for each function rendered, the cookies used should be 1,2,3.. not a random hex-address. It also complicates string comparison of two different trees.

-banner

restores default banner behavior.

-banneris => subref

TBC: a hookpoint (and an option to set it) for a user-supplied function to produce a banner appropriate for users needs. It's not ideal, because the rendering-state variables, which are a natural candidate for use in concise.t, are unavailable to the user.

Option Stickiness

If you invoke Concise more than once in a program, you should know that the options are 'sticky'. This means that the options you provide in the first call will be remembered for the 2nd call, unless you re-specify or change them.

ABBREVIATIONS

The concise style uses symbols to convey maximum info with minimal clutter (like hex addresses). With just a little practice, you can start to see the flowers, not just the branches, in the trees.

OP class abbreviations

These symbols appear before the op-name, and indicate the B:: namespace that represents the ops in your Perl code.

    0      OP (aka BASEOP)  An OP with no children
    1      UNOP             An OP with one child
    2      BINOP            An OP with two children
    |      LOGOP            A control branch OP
    @      LISTOP           An OP that could have lots of children
    /      PMOP             An OP with a regular expression
    $      SVOP             An OP with an SV
    "      PVOP             An OP with a string
    {      LOOP             An OP that holds pointers for a loop
    ;      COP              An OP that marks the start of a statement
    #      PADOP            An OP with a GV on the pad

OP flags abbreviations

OP flags are either public or private. The public flags alter the behavior of each opcode in consistent ways, and are represented by 0 or more single characters.

    v      OPf_WANT_VOID    Want nothing (void context)
    s      OPf_WANT_SCALAR  Want single value (scalar context)
    l      OPf_WANT_LIST    Want list of any length (list context)
                            Want is unknown
    K      OPf_KIDS         There is a firstborn child.
    P      OPf_PARENS       This operator was parenthesized.
                             (Or block needs explicit scope entry.)
    R      OPf_REF          Certified reference.
                             (Return container, not containee).
    M      OPf_MOD          Will modify (lvalue).
    S      OPf_STACKED      Some arg is arriving on the stack.
    *      OPf_SPECIAL      Do something weird for this op (see op.h)

Private flags, if any are set for an opcode, are displayed after a '/'

    8  <@> leave[1 ref] vKP/REFC ->(end)
    7     <2> sassign vKS/2 ->8

They're opcode specific, and occur less often than the public ones, so they're represented by short mnemonics instead of single-chars; see op.h for gory details, or try this quick 2-liner:

  $> perl -MB::Concise -de 1
  DB<1> |x \%B::Concise::priv

FORMATTING SPECIFICATIONS

For each line-style ('concise', 'terse', 'linenoise', etc.) there are 3 format-specs which control how OPs are rendered.

The first is the 'default' format, which is used in both basic and exec modes to print all opcodes. The 2nd, goto-format, is used in exec mode when branches are encountered. They're not real opcodes, and are inserted to look like a closing curly brace. The tree-format is tree specific.

When a line is rendered, the correct format-spec is copied and scanned for the following items; data is substituted in, and other manipulations like basic indenting are done, for each opcode rendered.

There are 3 kinds of items that may be populated; special patterns, #vars, and literal text, which is copied verbatim. (Yes, it's a set of s///g steps.)

Special Patterns

These items are the primitives used to perform indenting, and to select text from amongst alternatives.

(x(exec_text;basic_text)x)

Generates exec_text in exec mode, or basic_text in basic mode.

(*(text)*)

Generates one copy of text for each indentation level.

(*(text1;text2)*)

Generates one fewer copies of text1 than the indentation level, followed by one copy of text2 if the indentation level is more than 0.

(?(text1#varText2)?)

If the value of var is true (not empty or zero), generates the value of var surrounded by text1 and Text2, otherwise nothing.

~

Any number of tildes and surrounding whitespace will be collapsed to a single space.

# Variables

These #vars represent opcode properties that you may want as part of your rendering. The '#' is intended as a private sigil; a #var's value is interpolated into the style-line, much like "read $this".

These vars take 3 forms:

#var

A property named 'var' is assumed to exist for the opcodes, and is interpolated into the rendering.

#varN

Generates the value of var, left justified to fill N spaces. Note that this means while you can have properties 'foo' and 'foo2', you cannot render 'foo2', but you could with 'foo2a'. You would be wise not to rely on this behavior going forward ;-)

#Var

This ucfirst form of #var generates a tag-value form of itself for display; it converts '#Var' into a 'Var => #var' style, which is then handled as described above. (Imp-note: #Vars cannot be used for conditional-fills, because the => #var transform is done after the check for #Var's value).

The following variables are 'defined' by B::Concise; when they are used in a style, their respective values are plugged into the rendering of each opcode.

Only some of these are used by the standard styles, the others are provided for you to delve into optree mechanics, should you wish to add a new style (see add_style below) that uses them. You can also add new ones using add_callback.

#addr

The address of the OP, in hexadecimal.

#arg

The OP-specific information of the OP (such as the SV for an SVOP, the non-local exit pointers for a LOOP, etc.) enclosed in parentheses.

#class

The B-determined class of the OP, in all caps.

#classsym

A single symbol abbreviating the class of the OP.

#coplabel

The label of the statement or block the OP is the start of, if any.

#exname

The name of the OP, or 'ex-foo' if the OP is a null that used to be a foo.

#extarg

The target of the OP, or nothing for a nulled OP.

#firstaddr

The address of the OP's first child, in hexadecimal.

#flags

The OP's flags, abbreviated as a series of symbols.

#flagval

The numeric value of the OP's flags.

#hyphseq

The sequence number of the OP, or a hyphen if it doesn't have one.

#label

'NEXT', 'LAST', or 'REDO' if the OP is a target of one of those in exec mode, or empty otherwise.

#lastaddr

The address of the OP's last child, in hexadecimal.

#name

The OP's name.

#NAME

The OP's name, in all caps.

#next

The sequence number of the OP's next OP.

#nextaddr

The address of the OP's next OP, in hexadecimal.

#noise

A one- or two-character abbreviation for the OP's name.

#private

The OP's private flags, rendered with abbreviated names if possible.

#privval

The numeric value of the OP's private flags.

#seq

The sequence number of the OP. Note that this is a sequence number generated by B::Concise.

#seqnum

5.8.x and earlier only. 5.9 and later do not provide this.

The real sequence number of the OP, as a regular number and not adjusted to be relative to the start of the real program. (This will generally be a fairly large number because all of B::Concise is compiled before your program is).

#opt

Whether or not the op has been optimised by the peephole optimiser.

Only available in 5.9 and later.

#static

Whether or not the op is statically defined. This flag is used by the B::C compiler backend and indicates that the op should not be freed.

Only available in 5.9 and later.

#sibaddr

The address of the OP's next youngest sibling, in hexadecimal.

#svaddr

The address of the OP's SV, if it has an SV, in hexadecimal.

#svclass

The class of the OP's SV, if it has one, in all caps (e.g., 'IV').

#svval

The value of the OP's SV, if it has one, in a short human-readable format.

#targ

The numeric value of the OP's targ.

#targarg

The name of the variable the OP's targ refers to, if any, otherwise the letter t followed by the OP's targ in decimal.

#targarglife

Same as #targarg, but followed by the COP sequence numbers that delimit the variable's lifetime (or 'end' for a variable in an open scope) for a variable.

#typenum

The numeric value of the OP's type, in decimal.

Using B::Concise outside of the O framework

The common (and original) usage of B::Concise was for command-line renderings of simple code, as given in EXAMPLE. But you can also use B::Concise from your code, and call compile() directly, and repeatedly. By doing so, you can avoid the compile-time only operation of O.pm, and even use the debugger to step through B::Concise::compile() itself.

Once you're doing this, you may alter Concise output by adding new rendering styles, and by optionally adding callback routines which populate new variables, if such were referenced from those (just added) styles.

Example: Altering Concise Renderings

    use B::Concise qw(set_style add_callback);
    add_style($yourStyleName => $defaultfmt, $gotofmt, $treefmt);
    add_callback
      ( sub {
            my ($h, $op, $format, $level, $stylename) = @_;
            $h->{variable} = some_func($op);
        });
    $walker = B::Concise::compile(@options,@subnames,@subrefs);
    $walker->();

set_style()

set_style accepts 3 arguments, and updates the three format-specs comprising a line-style (basic-exec, goto, tree). It has one minor drawback though; it doesn't register the style under a new name. This can become an issue if you render more than once and switch styles. Thus you may prefer to use add_style() and/or set_style_standard() instead.

set_style_standard($name)

This restores one of the standard line-styles: terse, concise, linenoise, debug, env, into effect. It also accepts style names previously defined with add_style().

add_style()

This subroutine accepts a new style name and three style arguments as above, and creates, registers, and selects the newly named style. It is an error to re-add a style; call set_style_standard() to switch between several styles.

add_callback()

If your newly minted styles refer to any new #variables, you'll need to define a callback subroutine that will populate (or modify) those variables. They are then available for use in the style you've chosen.

The callbacks are called for each opcode visited by Concise, in the same order as they are added. Each subroutine is passed five parameters.

  1. A hashref, containing the variable names and values which are
     populated into the report-line for the op
  2. the op, as a B<B::OP> object
  3. a reference to the format string
  4. the formatting (indent) level
  5. the selected stylename

To define your own variables, simply add them to the hash, or change existing values if you need to. The level and format are passed in as references to scalars, but it is unlikely that they will need to be changed or even used.

Running B::Concise::compile()

compile accepts options as described above in OPTIONS, and arguments, which are either coderefs, or subroutine names.

It constructs and returns a $treewalker coderef, which when invoked, traverses, or walks, and renders the optrees of the given arguments to STDOUT. You can reuse this, and can change the rendering style used each time; thereafter the coderef renders in the new style.

walk_output lets you change the print destination from STDOUT to another open filehandle, or into a string passed as a ref (unless you've built perl with -Uuseperlio).

    my $walker = B::Concise::compile('-terse','aFuncName', \&aSubRef);  # 1
    walk_output(\my $buf);
    $walker->();                        # 1 renders -terse
    set_style_standard('concise');      # 2
    $walker->();                        # 2 renders -concise
    $walker->(@new);                    # 3 renders whatever
    print "3 different renderings: terse, concise, and @new: $buf\n";

When $walker is called, it traverses the subroutines supplied when it was created, and renders them using the current style. You can change the style afterwards in several different ways:

  1. call C<compile>, altering style or mode/order
  2. call C<set_style_standard>
  3. call $walker, passing @new options

Passing new options to the $walker is the easiest way to change amongst any pre-defined styles (the ones you add are automatically recognized as options), and is the only way to alter rendering order without calling compile again. Note however that rendering state is still shared amongst multiple $walker objects, so they must still be used in a coordinated manner.

B::Concise::reset_sequence()

This function (not exported) lets you reset the sequence numbers (note that they're numbered arbitrarily, their goal being to be human readable). Its purpose is mostly to support testing, i.e. to compare the concise output from two identical anonymous subroutines (but different instances). Without the reset, B::Concise, seeing that they're separate optrees, generates different sequence numbers in the output.

Errors

Errors in rendering (non-existent function-name, non-existent coderef) are written to the STDOUT, or wherever you've set it via walk_output().

Errors using the various *style* calls, and bad args to walk_output(), result in die(). Use an eval if you wish to catch these errors and continue processing.

AUTHOR

Stephen McCamant, <smcc@CSUA.Berkeley.EDU>.


B::Debug - Walk Perl syntax tree, printing debug info about ops

  • AUTHOR

NAME

B::Debug - Walk Perl syntax tree, printing debug info about ops

SYNOPSIS

        perl -MO=Debug[,OPTIONS] foo.pl

DESCRIPTION

See ext/B/README.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Deparse - Perl compiler backend to produce perl code

  • OPTIONS
  • USING B::Deparse AS A MODULE
    • Synopsis
    • Description
    • new
    • ambient_pragmas
    • coderef2text
  • BUGS
  • AUTHOR

NAME

B::Deparse - Perl compiler backend to produce perl code

SYNOPSIS

perl -MO=Deparse[,-d][,-f FILE][,-p][,-q][,-l] [,-s LETTERS][,-x LEVEL] prog.pl

DESCRIPTION

B::Deparse is a backend module for the Perl compiler that generates perl source code, based on the internal compiled structure that perl itself creates after parsing a program. The output of B::Deparse won't be exactly the same as the original source, since perl doesn't keep track of comments or whitespace, and there isn't a one-to-one correspondence between perl's syntactical constructions and their compiled form, but it will often be close. When you use the -p option, the output also includes parentheses even when they are not required by precedence, which can make it easy to see if perl is parsing your expressions the way you intended.

While B::Deparse goes to some lengths to try to figure out what your original program was doing, some parts of the language can still trip it up; it still fails even on some parts of Perl's own test suite. If you encounter a failure other than the most common ones described in the BUGS section below, you can help contribute to B::Deparse's ongoing development by submitting a bug report with a small example.

OPTIONS

As with all compiler backend options, these must follow directly after the '-MO=Deparse', separated by a comma but not any white space.

-d

Output data values (when they appear as constants) using Data::Dumper. Without this option, B::Deparse will use some simple routines of its own for the same purpose. Currently, Data::Dumper is better for some kinds of data (such as complex structures with sharing and self-reference) while the built-in routines are better for others (such as odd floating-point values).

-f FILE

Normally, B::Deparse deparses the main code of a program, and all the subs defined in the same file. To include subs defined in other files, pass the -f option with the filename. You can pass the -f option several times, to include more than one secondary file. (Most of the time you don't want to use it at all.) You can also use this option to include subs which are defined in the scope of a #line directive with two parameters.

-l

Add '#line' declarations to the output based on the line and file locations of the original code.

-p

Print extra parentheses. Without this option, B::Deparse includes parentheses in its output only when they are needed, based on the structure of your program. With -p, it uses parentheses (almost) whenever they would be legal. This can be useful if you are used to LISP, or if you want to see how perl parses your input. If you say

    if ($var & 0x7f == 65) {print "Gimme an A!"}
    print ($which ? $a : $b), "\n";
    $name = $ENV{USER} or "Bob";

B::Deparse,-p will print

    if (($var & 0)) {
        print('Gimme an A!')
    };
    (print(($which ? $a : $b)), '???');
    (($name = $ENV{'USER'}) or '???')

which probably isn't what you intended (the '???' is a sign that perl optimized away a constant value).

-P

Disable prototype checking. With this option, all function calls are deparsed as if no prototype was defined for them. In other words,

    perl -MO=Deparse,-P -e 'sub foo (\@) { 1 } foo @x'

will print

    sub foo (\@) {
        1;
    }
    &foo(\@x);

making clear how the parameters are actually passed to foo.

-q

Expand double-quoted strings into the corresponding combinations of concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and join. For instance, print

    print "Hello, $world, @ladies, \u$gentlemen\E, \u\L$me!";

as

    print 'Hello, ' . $world . ', ' . join($", @ladies) . ', '
          . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');

Note that the expanded form represents the way perl handles such constructions internally -- this option actually turns off the reverse translation that B::Deparse usually does. On the other hand, note that $x = "$y" is not the same as $x = $y: the former makes the value of $y into a string before doing the assignment.

-s LETTERS

Tweak the style of B::Deparse's output. The letters should follow directly after the 's', with no space or punctuation. The following options are available:

C

Cuddle elsif, else, and continue blocks. For example, print

    if (...) {
         ...
    } else {
         ...
    }

instead of

    if (...) {
         ...
    }
    else {
         ...
    }

The default is not to cuddle.

i NUMBER

Indent lines by multiples of NUMBER columns. The default is 4 columns.

T

Use tabs for each 8 columns of indent. The default is to use only spaces. For instance, if the style options are -si4T, a line that's indented 3 times will be preceded by one tab and four spaces; if the options were -si8T, the same line would be preceded by three tabs.

v STRING.

Print STRING for the value of a constant that can't be determined because it was optimized away (mnemonic: this happens when a constant is used in void context). The end of the string is marked by a period. The string should be a valid perl expression, generally a constant. Note that unless it's a number, it probably needs to be quoted, and on a command line quotes need to be protected from the shell. Some conventional values include 0, 1, 42, '', 'foo', and 'Useless use of constant omitted' (which may need to be -sv"'Useless use of constant omitted'." or something similar depending on your shell). The default is '???'. If you're using B::Deparse on a module or other file that's require'd, you shouldn't use a value that evaluates to false, since the customary true constant at the end of a module will be in void context when the file is compiled as a main program.

-x LEVEL

Expand conventional syntax constructions into equivalent ones that expose their internal operation. LEVEL should be a digit, with higher values meaning more expansion. As with -q, this actually involves turning off special cases in B::Deparse's normal operations.

If LEVEL is at least 3, for loops will be translated into equivalent while loops with continue blocks; for instance

    for ($i = 0; $i < 10; ++$i) {
        print $i;
    }

turns into

    $i = 0;
    while ($i < 10) {
        print $i;
    } continue {
        ++$i
    }

Note that in a few cases this translation can't be perfectly carried back into the source code -- if the loop's initializer declares a my variable, for instance, it won't have the correct scope outside of the loop.

If LEVEL is at least 5, use declarations will be translated into BEGIN blocks containing calls to require and import; for instance,

    use strict 'refs';

turns into

    sub BEGIN {
        require strict;
        do {
            'strict'->import('refs')
        };
    }

If LEVEL is at least 7, if statements will be translated into equivalent expressions using &&, ?: and do {}; for instance

    print 'hi' if $nice;
    if ($nice) {
        print 'hi';
    }
    if ($nice) {
        print 'hi';
    } else {
        print 'bye';
    }

turns into

    $nice and print 'hi';
    $nice and do { print 'hi' };
    $nice ? do { print 'hi' } : do { print 'bye' };

Long sequences of elsifs will turn into nested ternary operators, which B::Deparse doesn't know how to indent nicely.

USING B::Deparse AS A MODULE

Synopsis

    use B::Deparse;
    $deparse = B::Deparse->new("-p", "-sC");
    $body = $deparse->coderef2text(\&func);
    eval "sub func $body"; # the inverse operation

Description

B::Deparse can also be used on a sub-by-sub basis from other perl programs.

new

    $deparse = B::Deparse->new(OPTIONS)

Create an object to store the state of a deparsing operation and any options. The options are the same as those that can be given on the command line (see OPTIONS); options that are separated by commas after -MO=Deparse should be given as separate strings. Some options, like -u, don't make sense for a single subroutine, so don't pass them.

ambient_pragmas

    $deparse->ambient_pragmas(strict => 'all', '$[' => $[);

The compilation of a subroutine can be affected by a few compiler directives, pragmas. These are:

  • use strict;

  • use warnings;

  • Assigning to the special variable $[

  • use integer;

  • use bytes;

  • use utf8;

  • use re;

Ordinarily, if you use B::Deparse on a subroutine which has been compiled in the presence of one or more of these pragmas, the output will include statements to turn on the appropriate directives. So if you then compile the code returned by coderef2text, it will behave the same way as the subroutine which you deparsed.

However, you may know that you intend to use the results in a particular context, where some pragmas are already in scope. In this case, you use the ambient_pragmas method to describe the assumptions you wish to make.

Not all of the options currently have any useful effect. See BUGS for more details.

The parameters it accepts are:

strict

Takes a string, possibly containing several values separated by whitespace. The special values "all" and "none" mean what you'd expect.

    $deparse->ambient_pragmas(strict => 'subs refs');
$[

Takes a number, the value of the array base $[.

bytes
utf8
integer

If the value is true, then the appropriate pragma is assumed to be in the ambient scope, otherwise not.

re

Takes a string, possibly containing a whitespace-separated list of values. The values "all" and "none" are special. It's also permissible to pass an array reference here.

    $deparser->ambient_pragmas(re => 'eval');
warnings

Takes a string, possibly containing a whitespace-separated list of values. The values "all" and "none" are special, again. It's also permissible to pass an array reference here.

    $deparser->ambient_pragmas(warnings => [qw[void io]]);

If one of the values is the string "FATAL", then all the warnings in that list will be considered fatal, just as with the warnings pragma itself. Should you need to specify that some warnings are fatal, and others are merely enabled, you can pass the warnings parameter twice:

    $deparser->ambient_pragmas(
        warnings => 'all',
        warnings => [FATAL => qw/void io/],
    );

See the perllexwarn manpage for more information about lexical warnings.

hint_bits
warning_bits

These two parameters are used to specify the ambient pragmas in the format used by the special variables $^H and ${^WARNING_BITS}.

They exist principally so that you can write code like:

    { my ($hint_bits, $warning_bits);
    BEGIN {($hint_bits, $warning_bits) = ($^H, ${^WARNING_BITS})}
    $deparser->ambient_pragmas (
        hint_bits    => $hint_bits,
        warning_bits => $warning_bits,
        '$['         => 0 + $[
    ); }

which specifies that the ambient pragmas are exactly those which are in scope at the point of calling.

coderef2text

    $body = $deparse->coderef2text(\&func)
    $body = $deparse->coderef2text(sub ($$) { ... })

Return source code for the body of a subroutine (a block, optionally preceded by a prototype in parens), given a reference to the sub. Because a subroutine can have no names, or more than one name, this method doesn't return a complete subroutine definition -- if you want to eval the result, you should prepend "sub subname ", or "sub " for an anonymous function constructor. Unless the sub was defined in the main:: package, the code will include a package declaration.

BUGS

  • The only pragmas to be completely supported are: use warnings, use strict 'refs', use bytes, and use integer. ($[, which behaves like a pragma, is also supported.)

    Excepting those listed above, we're currently unable to guarantee that B::Deparse will produce a pragma at the correct point in the program. (Specifically, pragmas at the beginning of a block often appear right before the start of the block instead.) Since the effects of pragmas are often lexically scoped, this can mean that the pragma holds sway over a different portion of the program than in the input file.

  • In fact, the above is a specific instance of a more general problem: we can't guarantee to produce BEGIN blocks or use declarations in exactly the right place. So if you use a module which affects compilation (such as by over-riding keywords, overloading constants or whatever) then the output code might not work as intended.

    This is the most serious outstanding problem, and will require some help from the Perl core to fix.

  • If a keyword is over-ridden, and your program explicitly calls the built-in version by using CORE::keyword, the output of B::Deparse will not reflect this. If you run the resulting code, it will call the over-ridden version rather than the built-in one. (Maybe there should be an option to always print keyword calls as CORE::name.)

  • Some constants don't print correctly either with or without -d. For instance, neither B::Deparse nor Data::Dumper know how to print dual-valued scalars correctly, as in:

        use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y;

  • An input file that uses source filtering probably won't be deparsed into runnable code, because it will still include the use declaration for the source filtering module, even though the code that is produced is already ordinary Perl which shouldn't be filtered again.

  • Optimised away statements are rendered as '???'. This includes statements that have a compile-time side-effect, such as the obscure

        my $x if 0;

    which is not, consequently, deparsed correctly.

  • There are probably many more bugs on non-ASCII platforms (EBCDIC).

AUTHOR

Stephen McCamant <smcc@CSUA.Berkeley.EDU>, based on an earlier version by Malcolm Beattie <mbeattie@sable.ox.ac.uk>, with contributions from Gisle Aas, James Duncan, Albert Dvornik, Robin Houston, Dave Mitchell, Hugo van der Sanden, Gurusamy Sarathy, Nick Ing-Simmons, and Rafael Garcia-Suarez.


B::Disassembler - Disassemble Perl bytecode

  • AUTHOR

NAME

B::Disassembler - Disassemble Perl bytecode

SYNOPSIS

        use Disassembler;

DESCRIPTION

See ext/B/B/Disassembler.pm.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Lint - Perl lint

  • OPTIONS AND LINT CHECKS
  • NON LINT-CHECK OPTIONS
  • BUGS
  • AUTHOR

NAME

B::Lint - Perl lint

SYNOPSIS

perl -MO=Lint[,OPTIONS] foo.pl

DESCRIPTION

The B::Lint module is equivalent to an extended version of the -w option of perl. It is named after the program lint which carries out a similar process for C programs.

OPTIONS AND LINT CHECKS

Option words are separated by commas (not whitespace) and follow the usual conventions of compiler backend options. Following any options (indicated by a leading -) come lint check arguments. Each such argument (apart from the special all and none options) is a word representing one possible lint check (turning on that check) or is no-foo (turning off that check). Before processing the check arguments, a standard list of checks is turned on. Later options override earlier ones. Available options are:

context

Produces a warning whenever an array is used in an implicit scalar context. For example, both of the lines

    $foo = length(@bar);
    $foo = @bar;

will elicit a warning. Using an explicit scalar() silences the warning. For example,

    $foo = scalar(@bar);
implicit-read and implicit-write

These options produce a warning whenever an operation implicitly reads or (respectively) writes to one of Perl's special variables. For example, implicit-read will warn about these:

    /foo/;

and implicit-write will warn about these:

    s/foo/bar/;

Both implicit-read and implicit-write warn about this:

    for (@a) { ... }
bare-subs

This option warns whenever a bareword is implicitly quoted, but is also the name of a subroutine in the current package. Typical mistakes that it will trap are:

    use constant foo => 'bar';
    @a = ( foo => 1 );
    $b{foo} = 2;

Neither of these will do what a naive user would expect.

dollar-underscore

This option warns whenever $_ is used either explicitly anywhere or as the implicit argument of a print statement.

private-names

This option warns on each use of any variable, subroutine or method name that lives in a non-current package but begins with an underscore ("_"). Warnings aren't issued for the special case of the single character name "_" by itself (e.g. $_ and @_).

undefined-subs

This option warns whenever an undefined subroutine is invoked. This option will only catch explicitly invoked subroutines such as foo() and not indirect invocations such as &$subref() or $obj->meth(). Note that some programs or modules delay definition of subs until runtime by means of the AUTOLOAD mechanism.

regexp-variables

This option warns whenever one of the regexp variables $`, $& or $' is used. Any occurrence of any of these variables in your program can slow your whole program down. See the perlre manpage for details.

all

Turn all warnings on.

none

Turn all warnings off.

NON LINT-CHECK OPTIONS

-u Package

Normally, Lint only checks the main code of the program together with all subs defined in package main. The -u option lets you include other package names whose subs are then checked by Lint.

BUGS

This is only a very preliminary version.

This module doesn't work correctly on thread-enabled perls.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk.


B::Showlex - Show lexical variables used in functions or files

  • EXAMPLES
    • OPTIONS
  • SEE ALSO
  • TODO
  • AUTHOR

NAME

B::Showlex - Show lexical variables used in functions or files

SYNOPSIS

        perl -MO=Showlex[,-OPTIONS][,SUBROUTINE] foo.pl

DESCRIPTION

When a comma-separated list of subroutine names is given as options, Showlex prints the lexical variables used in those subroutines. Otherwise, it prints the file-scope lexicals in the file.

EXAMPLES

Traditional form:

 $ perl -MO=Showlex -e 'my ($i,$j,$k)=(1,"foo")'
 Pad of lexical names for comppadlist has 4 entries
 0: SPECIAL #1 &PL_sv_undef
 1: PVNV (0x9db0fb0) $i
 2: PVNV (0x9db0f38) $j
 3: PVNV (0x9db0f50) $k
 Pad of lexical values for comppadlist has 5 entries
 0: SPECIAL #1 &PL_sv_undef
 1: NULL (0x9da4234)
 2: NULL (0x9db0f2c)
 3: NULL (0x9db0f44)
 4: NULL (0x9da4264)
 -e syntax OK

New-style form:

 $ perl -MO=Showlex,-newlex -e 'my ($i,$j,$k)=(1,"foo")'
 main Pad has 4 entries
 0: SPECIAL #1 &PL_sv_undef
 1: PVNV (0xa0c4fb8) "$i" = NULL (0xa0b8234)
 2: PVNV (0xa0c4f40) "$j" = NULL (0xa0c4f34)
 3: PVNV (0xa0c4f58) "$k" = NULL (0xa0c4f4c)
 -e syntax OK

New form, no specials, outside O framework:

 $ perl -MB::Showlex -e \
    'my ($i,$j,$k)=(1,"foo"); B::Showlex::compile(-newlex,-nosp)->()'
 main Pad has 4 entries
 1: PVNV (0x998ffb0) "$i" = IV (0x9983234) 1
 2: PVNV (0x998ff68) "$j" = PV (0x998ff5c) "foo"
 3: PVNV (0x998ff80) "$k" = NULL (0x998ff74)

Note that this example shows the values of the lexicals, whereas the other examples did not (as they're compile-time only).

OPTIONS

The -newlex option produces a more readable name => value format, and is shown in the second example above.

The -nosp option eliminates reporting of SPECIALs, such as 0: SPECIAL #1 &PL_sv_undef above. Reporting of SPECIALs can sometimes overwhelm your declared lexicals.

SEE ALSO

B::Showlex can also be used outside of the O framework, as in the third example. See B::Concise for a fuller explanation of reasons.

TODO

Some of the reported info, such as hex addresses, is not particularly valuable. Other information would be more useful for the typical programmer, such as line-numbers, pad-slot reuses, etc.. Given this, -newlex isnt a particularly good flag-name.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Stackobj - Helper module for CC backend

  • AUTHOR

NAME

B::Stackobj - Helper module for CC backend

SYNOPSIS

        use B::Stackobj;

DESCRIPTION

See ext/B/README.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


B::Stash - show what stashes are loaded

  • NAME

NAME

B::Stash - show what stashes are loaded


B::Terse - Walk Perl syntax tree, printing terse info about ops

  • AUTHOR

NAME

B::Terse - Walk Perl syntax tree, printing terse info about ops

SYNOPSIS

        perl -MO=Terse[,OPTIONS] foo.pl

DESCRIPTION

This version of B::Terse is really just a wrapper that calls B::Concise with the -terse option. It is provided for compatibility with old scripts (and habits) but using B::Concise directly is now recommended instead.

For compatibility with the old B::Terse, this module also adds a method named terse to B::OP and B::SV objects. The B::SV method is largely compatible with the old one, though authors of new software might be advised to choose a more user-friendly output format. The B::OP terse method, however, doesn't work well. Since B::Terse was first written, much more information in OPs has migrated to the scratchpad datastructure, but the terse interface doesn't have any way of getting to the correct pad. As a kludge, the new version will always use the pad for the main program, but for OPs in subroutines this will give the wrong answer or crash.

AUTHOR

The original version of B::Terse was written by Malcolm Beattie, <mbeattie@sable.ox.ac.uk>. This wrapper was written by Stephen McCamant, <smcc@MIT.EDU>.


B::Xref - Generates cross reference reports for Perl programs

  • OPTIONS
  • BUGS
  • AUTHOR

NAME

B::Xref - Generates cross reference reports for Perl programs

SYNOPSIS

perl -MO=Xref[,OPTIONS] foo.pl

DESCRIPTION

The B::Xref module is used to generate a cross reference listing of all definitions and uses of variables, subroutines and formats in a Perl program. It is implemented as a backend for the Perl compiler.

The report generated is in the following format:

    File filename1
      Subroutine subname1
        Package package1
          object1        line numbers
          object2        line numbers
          ...
        Package package2
        ...

Each File section reports on a single file. Each Subroutine section reports on a single subroutine apart from the special cases "(definitions)" and "(main)". These report, respectively, on subroutine definitions found by the initial symbol table walk and on the main part of the program or module external to all subroutines.

The report is then grouped by the Package of each variable, subroutine or format with the special case "(lexicals)" meaning lexical variables. Each object name (implicitly qualified by its containing Package) includes its type character(s) at the beginning where possible. Lexical variables are easier to track and even included dereferencing information where possible.

The line numbers are a comma separated list of line numbers (some preceded by code letters) where that object is used in some way. Simple uses aren't preceded by a code letter. Introductions (such as where a lexical is first defined with my) are indicated with the letter "i". Subroutine and method calls are indicated by the character "&". Subroutine definitions are indicated by "s" and format definitions by "f".

OPTIONS

Option words are separated by commas (not whitespace) and follow the usual conventions of compiler backend options.

-oFILENAME

Directs output to FILENAME instead of standard output.

-r

Raw output. Instead of producing a human-readable report, outputs a line in machine-readable form for each definition/use of a variable/sub/format.

-d

Don't output the "(definitions)" sections.

-D[tO]

(Internal) debug options, probably only useful if -r included. The t option prints the object on the top of the stack as it's being tracked. The O option prints each operator as it's being processed in the execution order of the program.

BUGS

Non-lexical variables are quite difficult to track through a program. Sometimes the type of a non-lexical variable's use is impossible to determine. Introductions of non-lexical non-scalars don't seem to be reported properly.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk.


Benchmark - benchmark running times of Perl code

    • Methods
    • Standard Exports
    • Optional Exports
    • :hireswallclock
  • NOTES
  • EXAMPLES
  • INHERITANCE
  • CAVEATS
  • SEE ALSO
  • AUTHORS
  • MODIFICATION HISTORY

NAME

Benchmark - benchmark running times of Perl code

SYNOPSIS

    use Benchmark qw(:all) ;

    timethis ($count, "code");

    # Use Perl code in strings...
    timethese($count, {
        'Name1' => '...code1...',
        'Name2' => '...code2...',
    });

    # ... or use subroutine references.
    timethese($count, {
        'Name1' => sub { ...code1... },
        'Name2' => sub { ...code2... },
    });

    # cmpthese can be used both ways as well
    cmpthese($count, {
        'Name1' => '...code1...',
        'Name2' => '...code2...',
    });

    cmpthese($count, {
        'Name1' => sub { ...code1... },
        'Name2' => sub { ...code2... },
    });

    # ...or in two stages
    $results = timethese($count,
        {
            'Name1' => sub { ...code1... },
            'Name2' => sub { ...code2... },
        },
        'none'
    );
    cmpthese( $results ) ;

    $t = timeit($count, '...other code...')
    print "$count loops of other code took:",timestr($t),"\n";

    $t = countit($time, '...other code...')
    $count = $t->iters ;
    print "$count loops of other code took:",timestr($t),"\n";

    # enable hires wallclock timing if possible
    use Benchmark ':hireswallclock';

DESCRIPTION

The Benchmark module encapsulates a number of routines to help you figure out how long it takes to execute some code.

timethis - run a chunk of code several times

timethese - run several chunks of code several times

cmpthese - print results of timethese as a comparison chart

timeit - run a chunk of code and see how long it goes

countit - see how many times a chunk of code runs in a given time

Methods

new

Returns the current time. Example:

    use Benchmark;
    $t0 = new Benchmark;
    # ... your code here ...
    $t1 = new Benchmark;
    $td = timediff($t1, $t0);
    print "the code took:",timestr($td),"\n";
debug

Enables or disable debugging by setting the $Benchmark::Debug flag:

    debug Benchmark 1;
    $t = timeit(10, ' 5 ** $Global ');
    debug Benchmark 0;
iters

Returns the number of iterations.

Standard Exports

The following routines will be exported into your namespace if you use the Benchmark module:

timeit(COUNT, CODE)

Arguments: COUNT is the number of times to run the loop, and CODE is the code to run. CODE may be either a code reference or a string to be eval'd; either way it will be run in the caller's package.

Returns: a Benchmark object.

timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )

Time COUNT iterations of CODE. CODE may be a string to eval or a code reference; either way the CODE will run in the caller's package. Results will be printed to STDOUT as TITLE followed by the times. TITLE defaults to "timethis COUNT" if none is provided. STYLE determines the format of the output, as described for timestr() below.

The COUNT can be zero or negative: this means the minimum number of CPU seconds to run. A zero signifies the default of 3 seconds. For example to run at least for 10 seconds:

        timethis(-10, $code)

or to run two pieces of code tests for at least 3 seconds:

        timethese(0, { test1 => '...', test2 => '...'})

CPU seconds is, in UNIX terms, the user time plus the system time of the process itself, as opposed to the real (wallclock) time and the time spent by the child processes. Less than 0.1 seconds is not accepted (-0.01 as the count, for example, will cause a fatal runtime exception).

Note that the CPU seconds is the minimum time: CPU scheduling and other operating system factors may complicate the attempt so that a little bit more time is spent. The benchmark output will, however, also tell the number of $code runs/second, which should be a more interesting number than the actually spent seconds.

Returns a Benchmark object.

timethese ( COUNT, CODEHASHREF, [ STYLE ] )

The CODEHASHREF is a reference to a hash containing names as keys and either a string to eval or a code reference for each value. For each (KEY, VALUE) pair in the CODEHASHREF, this routine will call

        timethis(COUNT, VALUE, KEY, STYLE)

The routines are called in string comparison order of KEY.

The COUNT can be zero or negative, see timethis().

Returns a hash of Benchmark objects, keyed by name.

timediff ( T1, T2 )

Returns the difference between two Benchmark times as a Benchmark object suitable for passing to timestr().

timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )

Returns a string that formats the times in the TIMEDIFF object in the requested STYLE. TIMEDIFF is expected to be a Benchmark object similar to that returned by timediff().

STYLE can be any of 'all', 'none', 'noc', 'nop' or 'auto'. 'all' shows each of the 5 times available ('wallclock' time, user time, system time, user time of children, and system time of children). 'noc' shows all except the two children times. 'nop' shows only wallclock and the two children times. 'auto' (the default) will act as 'all' unless the children times are both zero, in which case it acts as 'noc'. 'none' prevents output.

FORMAT is the printf(3)-style format specifier (without the leading '%') to use to print the times. It defaults to '5.2f'.

Optional Exports

The following routines will be exported into your namespace if you specifically ask that they be imported:

clearcache ( COUNT )

Clear the cached time for COUNT rounds of the null loop.

clearallcache ( )

Clear all cached times.

cmpthese ( COUNT, CODEHASHREF, [ STYLE ] )
cmpthese ( RESULTSHASHREF, [ STYLE ] )

Optionally calls timethese(), then outputs comparison chart. This:

    cmpthese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;

outputs a chart like:

           Rate    b    a
    b 2831802/s   -- -61%
    a 7208959/s 155%   --

This chart is sorted from slowest to fastest, and shows the percent speed difference between each pair of tests.

c<cmpthese> can also be passed the data structure that timethese() returns:

    $results = timethese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;
    cmpthese( $results );

in case you want to see both sets of results.

Returns a reference to an ARRAY of rows, each row is an ARRAY of cells from the above chart, including labels. This:

    my $rows = cmpthese( -1, { a => '++$i', b => '$i *= 2' }, "none" );

returns a data structure like:

    [
        [ '',       'Rate',   'b',    'a' ],
        [ 'b', '2885232/s',  '--', '-59%' ],
        [ 'a', '7099126/s', '146%',  '--' ],
    ]

NOTE: This result value differs from previous versions, which returned the timethese() result structure. If you want that, just use the two statement timethese...cmpthese idiom shown above.

Incidently, note the variance in the result values between the two examples; this is typical of benchmarking. If this were a real benchmark, you would probably want to run a lot more iterations.

countit(TIME, CODE)

Arguments: TIME is the minimum length of time to run CODE for, and CODE is the code to run. CODE may be either a code reference or a string to be eval'd; either way it will be run in the caller's package.

TIME is not negative. countit() will run the loop many times to calculate the speed of CODE before running it for TIME. The actual time run for will usually be greater than TIME due to system clock resolution, so it's best to look at the number of iterations divided by the times that you are concerned with, not just the iterations.

Returns: a Benchmark object.

disablecache ( )

Disable caching of timings for the null loop. This will force Benchmark to recalculate these timings for each new piece of code timed.

enablecache ( )

Enable caching of timings for the null loop. The time taken for COUNT rounds of the null loop will be calculated only once for each different COUNT used.

timesum ( T1, T2 )

Returns the sum of two Benchmark times as a Benchmark object suitable for passing to timestr().

:hireswallclock

If the Time::HiRes module has been installed, you can specify the special tag :hireswallclock for Benchmark (if Time::HiRes is not available, the tag will be silently ignored). This tag will cause the wallclock time to be measured in microseconds, instead of integer seconds. Note though that the speed computations are still conducted in CPU time, not wallclock time.

NOTES

The data is stored as a list of values from the time and times functions:

      ($real, $user, $system, $children_user, $children_system, $iters)

in seconds for the whole loop (not divided by the number of rounds).

The timing is done using time(3) and times(3).

Code is executed in the caller's package.

The time of the null loop (a loop with the same number of rounds but empty loop body) is subtracted from the time of the real loop.

The null loop times can be cached, the key being the number of rounds. The caching can be controlled using calls like these:

    clearcache($key);
    clearallcache();

    disablecache();
    enablecache();

Caching is off by default, as it can (usually slightly) decrease accuracy and does not usually noticably affect runtimes.

EXAMPLES

For example,

    use Benchmark qw( cmpthese ) ;
    $x = 3;
    cmpthese( -5, {
        a => sub{$x*$x},
        b => sub{$x**2},
    } );

outputs something like this:

   Benchmark: running a, b, each for at least 5 CPU seconds...
          Rate    b    a
   b 1559428/s   -- -62%
   a 4152037/s 166%   --

while

    use Benchmark qw( timethese cmpthese ) ;
    $x = 3;
    $r = timethese( -5, {
        a => sub{$x*$x},
        b => sub{$x**2},
    } );
    cmpthese $r;

outputs something like this:

    Benchmark: running a, b, each for at least 5 CPU seconds...
             a: 10 wallclock secs ( 5.14 usr +  0.13 sys =  5.27 CPU) @ 3835055.60/s (n=20210743)
             b:  5 wallclock secs ( 5.41 usr +  0.00 sys =  5.41 CPU) @ 1574944.92/s (n=8520452)
           Rate    b    a
    b 1574945/s   -- -59%
    a 3835056/s 144%   --

INHERITANCE

Benchmark inherits from no other class, except of course for Exporter.

CAVEATS

Comparing eval'd strings with code references will give you inaccurate results: a code reference will show a slightly slower execution time than the equivalent eval'd string.

The real time timing is done using time(2) and the granularity is therefore only one second.

Short tests may produce negative figures because perl can appear to take longer to execute the empty loop than a short test; try:

    timethis(100,'1');

The system time of the null loop might be slightly more than the system time of the loop with the actual code and therefore the difference might end up being < 0.

SEE ALSO

the Devel::DProf manpage - a Perl code profiler

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi>, Tim Bunce <Tim.Bunce@ig.co.uk>

MODIFICATION HISTORY

September 8th, 1994; by Tim Bunce.

March 28th, 1997; by Hugo van der Sanden: added support for code references and the already documented 'debug' method; revamped documentation.

April 04-07th, 1997: by Jarkko Hietaniemi, added the run-for-some-time functionality.

September, 1999; by Barrie Slaymaker: math fixes and accuracy and efficiency tweaks. Added cmpthese(). A result is now returned from timethese(). Exposed countit() (was runfor()).

December, 2001; by Nicholas Clark: make timestr() recognise the style 'none' and return an empty string. If cmpthese is calling timethese, make it pass the style in. (so that 'none' will suppress output). Make sub new dump its debugging output to STDERR, to be consistent with everything else. All bugs found while writing a regression test.

September, 2002; by Jarkko Hietaniemi: add ':hireswallclock' special tag.

February, 2004; by Chia-liang Kao: make cmpthese and timestr use time statistics for children instead of parent when the style is 'nop'.


Bundle::Apache2 - Install Apache mod_perl2 and related modules

  • CONTENTS
  • DESCRIPTION
  • AUTHOR

NAME

Bundle::Apache2 - Install Apache mod_perl2 and related modules

SYNOPSIS

perl -MCPAN -e 'install Bundle::Apache2'

CONTENTS

Bundle::ApacheTest - Needs for testing

CGI 3.11 - Used in testing (it's in core, but some vendors exclude it)

Chatbot::Eliza - Used in testing

Compress::Zlib - Used in testing

Devel::Symdump - Symbol table browsing with Apache::Status

HTML::HeadParser - Used in testing

IPC::Run3 - Used in testing

LWP - Used in testing

DESCRIPTION

This bundle contains modules used by Apache mod_perl2.

Asking CPAN.pm to install a bundle means to install the bundle itself along with all the modules contained in the CONTENTS section above. Modules that are up to date are not installed, of course.

AUTHOR

mod_perl 2 development team


Bundle::ApacheTest - A bundle to install all Apache-Test related modules

  • CONTENTS
  • DESCRIPTION

NAME

Bundle::ApacheTest - A bundle to install all Apache-Test related modules

SYNOPSIS

 perl -MCPAN -e 'install Bundle::ApacheTest'

CONTENTS

Crypt::SSLeay - For https support

Devel::CoreStack - For getting core stack info

Devel::Symdump - For, uh, dumping symbols

Digest::MD5 - Needed for Digest authentication

URI - There are URIs everywhere

Net::Cmd - For libnet

MIME::Base64 - Used in authentication headers

HTML::Tagset - Needed by HTML::Parser

HTML::Parser - Need by HTML::HeadParser

HTML::HeadParser - To get the correct $res->base

LWP - For libwww-perl

IPC::Run3 - Used in Apache::TestSmoke

DESCRIPTION

This bundle lists all the CPAN modules used by Apache-Test.


Bundle::DBD::mysql - A bundle to install Perl drivers for MySQL

  • CONTENTS
  • DESCRIPTION

NAME

Bundle::DBD::mysql - A bundle to install Perl drivers for MySQL

SYNOPSIS

perl -MCPAN -e 'install Bundle::DBD::mysql'

CONTENTS

DBI

DBD::mysql

DESCRIPTION

This bundle includes all that is needed to connect with a MySQL server using DBI.


Bundle::DBI - A bundle to install DBI and required modules.

  • CONTENTS
  • DESCRIPTION
  • AUTHORS

NAME

Bundle::DBI - A bundle to install DBI and required modules.

SYNOPSIS

  perl -MCPAN -e 'install Bundle::DBI'

CONTENTS

DBI - for to get to know thyself

DBI::Shell 11.91 - the DBI command line shell

Storable 2.06 - for DBD::Proxy, DBI::ProxyServer, DBD::Forward

Net::Daemon 0.37 - for DBD::Proxy and DBI::ProxyServer

RPC::PlServer 0.2016 - for DBD::Proxy and DBI::ProxyServer

DBD::Multiplex 1.19 - treat multiple db handles as one

DESCRIPTION

This bundle includes all the modules used by the Perl Database Interface (DBI) module, created by Tim Bunce.

A Bundle is a module that simply defines a collection of other modules. It is used by the the CPAN manpage module to automate the fetching, building and installing of modules from the CPAN ftp archive sites.

This bundle does not deal with the various database drivers (e.g. DBD::Informix, DBD::Oracle etc), most of which require software from sources other than CPAN. You'll need to fetch and build those drivers yourself.

AUTHORS

Jonathan Leffler, Jochen Wiedmann and Tim Bunce.


Bundle::HTML::Mason - A bundle to install the HTML::Mason package

  • CONTENTS
  • DESCRIPTION

NAME

Bundle::HTML::Mason - A bundle to install the HTML::Mason package

SYNOPSIS

perl -MCPAN -e 'install Bundle::HTML::Mason'

CONTENTS

File::Spec 0.8

Params::Validate 0.24

Exception::Class 1.01

Cache::Cache 1.00

Class::Container 0.07

HTML::Mason

DESCRIPTION

This bundle includes all that's needed to run the HTML::Mason package.


Bundle::LWP - install all libwww-perl related modules

  • CONTENTS
  • DESCRIPTION
  • SEE ALSO

NAME

Bundle::LWP - install all libwww-perl related modules

SYNOPSIS

 perl -MCPAN -e 'install Bundle::LWP'

CONTENTS

MIME::Base64 - Used in authentication headers

Digest::MD5 - Needed to do Digest authentication

URI 1.10 - There are URIs everywhere

Net::FTP 2.58 - If you want ftp://-support

HTML::Tagset - Needed by HTML::Parser

HTML::Parser - Need by HTML::HeadParser

HTML::HeadParser - To get the correct $res->base

LWP - The reason why you need the modules above

DESCRIPTION

This bundle defines all prereq modules for libwww-perl. Bundles have special meaning for the CPAN module. When you install the bundle module all modules mentioned in CONTENTS will be installed instead.

SEE ALSO

Bundles in the CPAN manpage


ByteLoader - load byte compiled perl code

  • AUTHOR
  • SEE ALSO

NAME

ByteLoader - load byte compiled perl code

SYNOPSIS

  use ByteLoader 0.06;
  <byte code>

  or just
  perl -MByteLoader bytecode_file

DESCRIPTION

This module is used to load byte compiled perl code as produced by perl -MO=Bytecode=.... It uses the source filter mechanism to read the byte code and insert it into the compiled code at the appropriate point.

AUTHOR

Tom Hughes <tom@compton.nu> based on the ideas of Tim Bunce and others. Many changes by Enache Adrian <enache@rdslink.ro> 2003 a.d.

SEE ALSO

perl(1).


CGI - Simple Common Gateway Interface Class

  • ABSTRACT
  • DESCRIPTION
    • PROGRAMMING STYLE
    • CALLING CGI.PM ROUTINES
    • CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):
    • CREATING A NEW QUERY OBJECT FROM AN INPUT FILE
    • FETCHING A LIST OF KEYWORDS FROM THE QUERY:
    • FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:
    • FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:
    • SETTING THE VALUE(S) OF A NAMED PARAMETER:
    • APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:
    • IMPORTING ALL PARAMETERS INTO A NAMESPACE:
    • DELETING A PARAMETER COMPLETELY:
    • DELETING ALL PARAMETERS:
    • HANDLING NON-URLENCODED ARGUMENTS
    • DIRECT ACCESS TO THE PARAMETER LIST:
    • FETCHING THE PARAMETER LIST AS A HASH:
    • SAVING THE STATE OF THE SCRIPT TO A FILE:
    • RETRIEVING CGI ERRORS
    • USING THE FUNCTION-ORIENTED INTERFACE
    • PRAGMAS
    • SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS
  • GENERATING DYNAMIC DOCUMENTS
    • CREATING A STANDARD HTTP HEADER:
    • GENERATING A REDIRECTION HEADER
    • CREATING THE HTML DOCUMENT HEADER
    • ENDING THE HTML DOCUMENT:
    • CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
    • OBTAINING THE SCRIPT'S URL
    • MIXING POST AND URL PARAMETERS
  • CREATING STANDARD HTML ELEMENTS:
    • PROVIDING ARGUMENTS TO HTML SHORTCUTS
    • THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS
    • HTML SHORTCUTS AND LIST INTERPOLATION
    • NON-STANDARD HTML SHORTCUTS
    • AUTOESCAPING HTML
    • PRETTY-PRINTING HTML
  • CREATING FILL-OUT FORMS:
    • CREATING AN ISINDEX TAG
    • STARTING AND ENDING A FORM
    • FORM ELEMENTS
    • CREATING A TEXT FIELD
    • CREATING A BIG TEXT FIELD
    • CREATING A PASSWORD FIELD
    • CREATING A FILE UPLOAD FIELD
    • CREATING A POPUP MENU
    • CREATING AN OPTION GROUP
    • CREATING A SCROLLING LIST
    • CREATING A GROUP OF RELATED CHECKBOXES
    • CREATING A STANDALONE CHECKBOX
    • CREATING A RADIO BUTTON GROUP
    • CREATING A SUBMIT BUTTON
    • CREATING A RESET BUTTON
    • CREATING A DEFAULT BUTTON
    • CREATING A HIDDEN FIELD
    • CREATING A CLICKABLE IMAGE BUTTON
    • CREATING A JAVASCRIPT ACTION BUTTON
  • HTTP COOKIES
  • WORKING WITH FRAMES
  • SUPPORT FOR JAVASCRIPT
  • LIMITED SUPPORT FOR CASCADING STYLE SHEETS
  • DEBUGGING
    • DUMPING OUT ALL THE NAME/VALUE PAIRS
  • FETCHING ENVIRONMENT VARIABLES
  • USING NPH SCRIPTS
  • Server Push
  • Avoiding Denial of Service Attacks
  • COMPATIBILITY WITH CGI-LIB.PL
  • AUTHOR INFORMATION
  • CREDITS
  • A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
  • BUGS
  • SEE ALSO

NAME

CGI - Simple Common Gateway Interface Class

SYNOPSIS

  # CGI script that creates a fill-out form
  # and echoes back its values.

  use CGI qw/:standard/;
  print header,
        start_html('A Simple Example'),
        h1('A Simple Example'),
        start_form,
        "What's your name? ",textfield('name'),p,
        "What's the combination?", p,
        checkbox_group(-name=>'words',
                       -values=>['eenie','meenie','minie','moe'],
                       -defaults=>['eenie','minie']), p,
        "What's your favorite color? ",
        popup_menu(-name=>'color',
                   -values=>['red','green','blue','chartreuse']),p,
        submit,
        end_form,
        hr;

   if (param()) {
       my $name      = param('name');
       my $keywords  = join ', ',param('words');
       my $color     = param('color');
       print "Your name is",em(escapeHTML($name)),p,
             "The keywords are: ",em(escapeHTML($keywords)),p,
             "Your favorite color is ",em(escapeHTML($color)),
             hr;
   }

ABSTRACT

This perl library uses perl5 objects to make it easy to create Web fill-out forms and parse their contents. This package defines CGI objects, entities that contain the values of the current query string and other state variables. Using a CGI object's methods, you can examine keywords and parameters passed to your script, and create forms whose initial values are taken from the current query (thereby preserving state information). The module provides shortcut functions that produce boilerplate HTML, reducing typing and coding errors. It also provides functionality for some of the more advanced features of CGI scripting, including support for file uploads, cookies, cascading style sheets, server push, and frames.

CGI.pm also provides a simple function-oriented programming style for those who don't need its object-oriented features.

The current version of CGI.pm is available at

  http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
  ftp://ftp-genome.wi.mit.edu/pub/software/WWW/

DESCRIPTION

PROGRAMMING STYLE

There are two styles of programming with CGI.pm, an object-oriented style and a function-oriented style. In the object-oriented style you create one or more CGI objects and then use object methods to create the various elements of the page. Each CGI object starts out with the list of named parameters that were passed to your CGI script by the server. You can modify the objects, save them to a file or database and recreate them. Because each object corresponds to the "state" of the CGI script, and because each object's parameter list is independent of the others, this allows you to save the state of the script and restore it later.

For example, using the object oriented style, here is how you create a simple "Hello World" HTML page:

   #!/usr/local/bin/perl -w
   use CGI;                             # load CGI routines
   $q = new CGI;                        # create new CGI object
   print $q->header,                    # create the HTTP header
         $q->start_html('hello world'), # start the HTML
         $q->h1('hello world'),         # level 1 header
         $q->end_html;                  # end the HTML

In the function-oriented style, there is one default CGI object that you rarely deal with directly. Instead you just call functions to retrieve CGI parameters, create HTML tags, manage cookies, and so on. This provides you with a cleaner programming interface, but limits you to using one CGI object at a time. The following example prints the same page, but uses the function-oriented interface. The main differences are that we now need to import a set of functions into our name space (usually the "standard" functions), and we don't need to create the CGI object.

   #!/usr/local/bin/perl
   use CGI qw/:standard/;           # load standard CGI routines
   print header,                    # create the HTTP header
         start_html('hello world'), # start the HTML
         h1('hello world'),         # level 1 header
         end_html;                  # end the HTML

The examples in this document mainly use the object-oriented style. See HOW TO IMPORT FUNCTIONS for important information on function-oriented programming in CGI.pm

CALLING CGI.PM ROUTINES

Most CGI.pm routines accept several arguments, sometimes as many as 20 optional ones! To simplify this interface, all routines use a named argument calling style that looks like this:

   print $q->header(-type=>'image/gif',-expires=>'+3d');

Each argument name is preceded by a dash. Neither case nor order matters in the argument list. -type, -Type, and -TYPE are all acceptable. In fact, only the first argument needs to begin with a dash. If a dash is present in the first argument, CGI.pm assumes dashes for the subsequent ones.

Several routines are commonly called with just one argument. In the case of these routines you can provide the single argument without an argument name. header() happens to be one of these routines. In this case, the single argument is the document type.

   print $q->header('text/html');

Other such routines are documented below.

Sometimes named arguments expect a scalar, sometimes a reference to an array, and sometimes a reference to a hash. Often, you can pass any type of argument and the routine will do whatever is most appropriate. For example, the param() routine is used to set a CGI parameter to a single or a multi-valued value. The two cases are shown below:

   $q->param(-name=>'veggie',-value=>'tomato');
   $q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']);

A large number of routines in CGI.pm actually aren't specifically defined in the module, but are generated automatically as needed. These are the "HTML shortcuts," routines that generate HTML tags for use in dynamically-generated pages. HTML tags have both attributes (the attribute="value" pairs within the tag itself) and contents (the part between the opening and closing pairs.) To distinguish between attributes and contents, CGI.pm uses the convention of passing HTML attributes as a hash reference as the first argument, and the contents, if any, as any subsequent arguments. It works out like this:

   Code                           Generated HTML
   ----                           --------------
   h1()                           <h1>
   h1('some','contents');         <h1>some contents</h1>
   h1({-align=>left});            <h1 align="LEFT">
   h1({-align=>left},'contents'); <h1 align="LEFT">contents</h1>

HTML tags are described in more detail later.

Many newcomers to CGI.pm are puzzled by the difference between the calling conventions for the HTML shortcuts, which require curly braces around the HTML tag attributes, and the calling conventions for other routines, which manage to generate attributes without the curly brackets. Don't be confused. As a convenience the curly braces are optional in all but the HTML shortcuts. If you like, you can use curly braces when calling any routine that takes named arguments. For example:

   print $q->header( {-type=>'image/gif',-expires=>'+3d'} );

If you use the -w switch, you will be warned that some CGI.pm argument names conflict with built-in Perl functions. The most frequent of these is the -values argument, used to create multi-valued menus, radio button clusters and the like. To get around this warning, you have several choices:

  1. Use another name for the argument, if one is available. For example, -value is an alias for -values.

  2. Change the capitalization, e.g. -Values

  3. Put quotes around the argument name, e.g. '-values'

Many routines will do something useful with a named argument that it doesn't recognize. For example, you can produce non-standard HTTP header fields by providing them as named arguments:

  print $q->header(-type  =>  'text/html',
                   -cost  =>  'Three smackers',
                   -annoyance_level => 'high',
                   -complaints_to   => 'bit bucket');

This will produce the following nonstandard HTTP header:

   HTTP/1.0 200 OK
   Cost: Three smackers
   Annoyance-level: high
   Complaints-to: bit bucket
   Content-type: text/html

Notice the way that underscores are translated automatically into hyphens. HTML-generating routines perform a different type of translation.

This feature allows you to keep up with the rapidly changing HTTP and HTML "standards".

CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):

     $query = new CGI;

This will parse the input (from both POST and GET methods) and store it into a perl5 object called $query.

CREATING A NEW QUERY OBJECT FROM AN INPUT FILE

     $query = new CGI(INPUTFILE);

If you provide a file handle to the new() method, it will read parameters from the file (or STDIN, or whatever). The file can be in any of the forms describing below under debugging (i.e. a series of newline delimited TAG=VALUE pairs will work). Conveniently, this type of file is created by the save() method (see below). Multiple records can be saved and restored.

Perl purists will be pleased to know that this syntax accepts references to file handles, or even references to filehandle globs, which is the "official" way to pass a filehandle:

    $query = new CGI(\*STDIN);

You can also initialize the CGI object with a FileHandle or IO::File object.

If you are using the function-oriented interface and want to initialize CGI state from a file handle, the way to do this is with restore_parameters(). This will (re)initialize the default CGI object from the indicated file handle.

    open (IN,"test.in") || die;
    restore_parameters(IN);
    close IN;

You can also initialize the query object from an associative array reference:

    $query = new CGI( {'dinosaur'=>'barney',
                       'song'=>'I love you',
                       'friends'=>[qw/Jessica George Nancy/]}
                    );

or from a properly formatted, URL-escaped query string:

    $query = new CGI('dinosaur=barney&color=purple');

or from a previously existing CGI object (currently this clones the parameter list, but none of the other object-specific fields, such as autoescaping):

    $old_query = new CGI;
    $new_query = new CGI($old_query);

To create an empty query, initialize it from an empty string or hash:

   $empty_query = new CGI("");

       -or-
   $empty_query = new CGI({});

FETCHING A LIST OF KEYWORDS FROM THE QUERY:

     @keywords = $query->keywords

If the script was invoked as the result of an <ISINDEX> search, the parsed keywords can be obtained as an array using the keywords() method.

FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:

     @names = $query->param

If the script was invoked with a parameter list (e.g. "name1=value1&name2=value2&name3=value3"), the param() method will return the parameter names as a list. If the script was invoked as an <ISINDEX> script and contains a string without ampersands (e.g. "value1+value2+value3") , there will be a single parameter named "keywords" containing the "+"-delimited keywords.

NOTE: As of version 1.5, the array of parameter names returned will be in the same order as they were submitted by the browser. Usually this order is the same as the order in which the parameters are defined in the form (however, this isn't part of the spec, and so isn't guaranteed).

FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:

    @values = $query->param('foo');

              -or-
    $value = $query->param('foo');

Pass the param() method a single argument to fetch the value of the named parameter. If the parameter is multivalued (e.g. from multiple selections in a scrolling list), you can ask to receive an array. Otherwise the method will return a single value.

If a value is not given in the query string, as in the queries "name1=&name2=" or "name1&name2", it will be returned as an empty string. This feature is new in 2.63.

If the parameter does not exist at all, then param() will return undef in a scalar context, and the empty list in a list context.

SETTING THE VALUE(S) OF A NAMED PARAMETER:

    $query->param('foo','an','array','of','values');

This sets the value for the named parameter 'foo' to an array of values. This is one way to change the value of a field AFTER the script has been invoked once before. (Another way is with the -override parameter accepted by all methods that generate form elements.)

param() also recognizes a named parameter style of calling described in more detail later:

    $query->param(-name=>'foo',-values=>['an','array','of','values']);

                              -or-
    $query->param(-name=>'foo',-value=>'the value');

APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:

   $query->append(-name=>'foo',-values=>['yet','more','values']);

This adds a value or list of values to the named parameter. The values are appended to the end of the parameter if it already exists. Otherwise the parameter is created. Note that this method only recognizes the named argument calling syntax.

IMPORTING ALL PARAMETERS INTO A NAMESPACE:

   $query->import_names('R');

This creates a series of variables in the 'R' namespace. For example, $R::foo, @R:foo. For keyword lists, a variable @R::keywords will appear. If no namespace is given, this method will assume 'Q'. WARNING: don't import anything into 'main'; this is a major security risk!!!!

NOTE 1: Variable names are transformed as necessary into legal Perl variable names. All non-legal characters are transformed into underscores. If you need to keep the original names, you should use the param() method instead to access CGI variables by name.

NOTE 2: In older versions, this method was called import(). As of version 2.20, this name has been removed completely to avoid conflict with the built-in Perl module import operator.

DELETING A PARAMETER COMPLETELY:

    $query->delete('foo','bar','baz');

This completely clears a list of parameters. It sometimes useful for resetting parameters that you don't want passed down between script invocations.

If you are using the function call interface, use "Delete()" instead to avoid conflicts with Perl's built-in delete operator.

DELETING ALL PARAMETERS:

   $query->delete_all();

This clears the CGI object completely. It might be useful to ensure that all the defaults are taken when you create a fill-out form.

Use Delete_all() instead if you are using the function call interface.

HANDLING NON-URLENCODED ARGUMENTS

If POSTed data is not of type application/x-www-form-urlencoded or multipart/form-data, then the POSTed data will not be processed, but instead be returned as-is in a parameter named POSTDATA. To retrieve it, use code like this:

   my $data = $query->param('POSTDATA');

(If you don't know what the preceding means, don't worry about it. It only affects people trying to use CGI for XML processing and other specialized tasks.)

DIRECT ACCESS TO THE PARAMETER LIST:

   $q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
   unshift @{$q->param_fetch(-name=>'address')},'George Munster';

If you need access to the parameter list in a way that isn't covered by the methods above, you can obtain a direct reference to it by calling the param_fetch() method with the name of the . This will return an array reference to the named parameters, which you then can manipulate in any way you like.

You can also use a named argument style using the -name argument.

FETCHING THE PARAMETER LIST AS A HASH:

    $params = $q->Vars;
    print $params->{'address'};
    @foo = split("\0",$params->{'foo'});
    %params = $q->Vars;

    use CGI ':cgi-lib';
    $params = Vars;

Many people want to fetch the entire parameter list as a hash in which the keys are the names of the CGI parameters, and the values are the parameters' values. The Vars() method does this. Called in a scalar context, it returns the parameter list as a tied hash reference. Changing a key changes the value of the parameter in the underlying CGI parameter list. Called in a list context, it returns the parameter list as an ordinary hash. This allows you to read the contents of the parameter list, but not to change it.

When using this, the thing you must watch out for are multivalued CGI parameters. Because a hash cannot distinguish between scalar and list context, multivalued parameters will be returned as a packed string, separated by the "\0" (null) character. You must split this packed string in order to get at the individual values. This is the convention introduced long ago by Steve Brenner in his cgi-lib.pl module for Perl version 4.

If you wish to use Vars() as a function, import the :cgi-lib set of function calls (also see the section on CGI-LIB compatibility).

SAVING THE STATE OF THE SCRIPT TO A FILE:

    $query->save(\*FILEHANDLE)

This will write the current state of the form to the provided filehandle. You can read it back in by providing a filehandle to the new() method. Note that the filehandle can be a file, a pipe, or whatever!

The format of the saved file is:

        NAME1=VALUE1
        NAME1=VALUE1'
        NAME2=VALUE2
        NAME3=VALUE3
        =

Both name and value are URL escaped. Multi-valued CGI parameters are represented as repeated names. A session record is delimited by a single = symbol. You can write out multiple records and read them back in with several calls to new. You can do this across several sessions by opening the file in append mode, allowing you to create primitive guest books, or to keep a history of users' queries. Here's a short example of creating multiple session records:

   use CGI;

   open (OUT,">>test.out") || die;
   $records = 5;
   foreach (0..$records) {
       my $q = new CGI;
       $q->param(-name=>'counter',-value=>$_);
       $q->save(\*OUT);
   }
   close OUT;

   # reopen for reading
   open (IN,"test.out") || die;
   while (!eof(IN)) {
       my $q = new CGI(\*IN);
       print $q->param('counter'),"\n";
   }

The file format used for save/restore is identical to that used by the Whitehead Genome Center's data exchange format "Boulderio", and can be manipulated and even databased using Boulderio utilities. See

  http://stein.cshl.org/boulder/

for further details.

If you wish to use this method from the function-oriented (non-OO) interface, the exported name for this method is save_parameters().

RETRIEVING CGI ERRORS

Errors can occur while processing user input, particularly when processing uploaded files. When these errors occur, CGI will stop processing and return an empty parameter list. You can test for the existence and nature of errors using the cgi_error() function. The error messages are formatted as HTTP status codes. You can either incorporate the error text into an HTML page, or use it as the value of the HTTP status:

    my $error = $q->cgi_error;
    if ($error) {
        print $q->header(-status=>$error),
              $q->start_html('Problems'),
              $q->h2('Request not processed'),
              $q->strong($error);
        exit 0;
    }

When using the function-oriented interface (see the next section), errors may only occur the first time you call param(). Be ready for this!

USING THE FUNCTION-ORIENTED INTERFACE

To use the function-oriented interface, you must specify which CGI.pm routines or sets of routines to import into your script's namespace. There is a small overhead associated with this importation, but it isn't much.

   use CGI <list of methods>;

The listed methods will be imported into the current package; you can call them directly without creating a CGI object first. This example shows how to import the param() and header() methods, and then use them directly:

   use CGI 'param','header';
   print header('text/plain');
   $zipcode = param('zipcode');

More frequently, you'll import common sets of functions by referring to the groups by name. All function sets are preceded with a ":" character as in ":html3" (for tags defined in the HTML 3 standard).

Here is a list of the function sets you can import:

:cgi

Import all CGI-handling methods, such as param(), path_info() and the like.

:form

Import all fill-out form generating methods, such as textfield().

:html2

Import all methods that generate HTML 2.0 standard elements.

:html3

Import all methods that generate HTML 3.0 elements (such as <table>, <super> and <sub>).

:html4

Import all methods that generate HTML 4 elements (such as <abbrev>, <acronym> and <thead>).

:netscape

Import all methods that generate Netscape-specific HTML extensions.

:html

Import all HTML-generating shortcuts (i.e. 'html2' + 'html3' + 'netscape')...

:standard

Import "standard" features, 'html2', 'html3', 'html4', 'form' and 'cgi'.

:all

Import all the available methods. For the full list, see the CGI.pm code, where the variable %EXPORT_TAGS is defined.

If you import a function name that is not part of CGI.pm, the module will treat it as a new HTML tag and generate the appropriate subroutine. You can then use it like any other HTML tag. This is to provide for the rapidly-evolving HTML "standard." For example, say Microsoft comes out with a new tag called <gradient> (which causes the user's desktop to be flooded with a rotating gradient fill until his machine reboots). You don't need to wait for a new version of CGI.pm to start using it immediately:

   use CGI qw/:standard :html3 gradient/;
   print gradient({-start=>'red',-end=>'blue'});

Note that in the interests of execution speed CGI.pm does not use the standard the Exporter manpage syntax for specifying load symbols. This may change in the future.

If you import any of the state-maintaining CGI or form-generating methods, a default CGI object will be created and initialized automatically the first time you use any of the methods that require one to be present. This includes param(), textfield(), submit() and the like. (If you need direct access to the CGI object, you can find it in the global variable $CGI::Q). By importing CGI.pm methods, you can create visually elegant scripts:

   use CGI qw/:standard/;
   print
       header,
       start_html('Simple Script'),
       h1('Simple Script'),
       start_form,
       "What's your name? ",textfield('name'),p,
       "What's the combination?",
       checkbox_group(-name=>'words',
                      -values=>['eenie','meenie','minie','moe'],
                      -defaults=>['eenie','moe']),p,
       "What's your favorite color?",
       popup_menu(-name=>'color',
                  -values=>['red','green','blue','chartreuse']),p,
       submit,
       end_form,
       hr,"\n";

    if (param) {
       print
           "Your name is ",em(param('name')),p,
           "The keywords are: ",em(join(", ",param('words'))),p,
           "Your favorite color is ",em(param('color')),".\n";
    }
    print end_html;

PRAGMAS

In addition to the function sets, there are a number of pragmas that you can import. Pragmas, which are always preceded by a hyphen, change the way that CGI.pm functions in various ways. Pragmas, function sets, and individual functions can all be imported in the same use() line. For example, the following use statement imports the standard set of functions and enables debugging mode (pragma -debug):

   use CGI qw/:standard -debug/;

The current list of pragmas is as follows:

-any

When you use CGI -any, then any method that the query object doesn't recognize will be interpreted as a new HTML tag. This allows you to support the next ad hoc Netscape or Microsoft HTML extension. This lets you go wild with new and unsupported tags:

   use CGI qw(-any);
   $q=new CGI;
   print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});

Since using <cite>any</cite> causes any mistyped method name to be interpreted as an HTML tag, use it with care or not at all.

-compile

This causes the indicated autoloaded methods to be compiled up front, rather than deferred to later. This is useful for scripts that run for an extended period of time under FastCGI or mod_perl, and for those destined to be crunched by Malcom Beattie's Perl compiler. Use it in conjunction with the methods or method families you plan to use.

   use CGI qw(-compile :standard :html3);

or even

   use CGI qw(-compile :all);

Note that using the -compile pragma in this way will always have the effect of importing the compiled functions into the current namespace. If you want to compile without importing use the compile() method instead:

   use CGI();
   CGI->compile();

This is particularly useful in a mod_perl environment, in which you might want to precompile all CGI routines in a startup script, and then import the functions individually in each mod_perl script.

-nosticky

By default the CGI module implements a state-preserving behavior called "sticky" fields. The way this works is that if you are regenerating a form, the methods that generate the form field values will interrogate param() to see if similarly-named parameters are present in the query string. If they find a like-named parameter, they will use it to set their default values.

Sometimes this isn't what you want. The -nosticky pragma prevents this behavior. You can also selectively change the sticky behavior in each element that you generate.

-tabindex

Automatically add tab index attributes to each form field. With this option turned off, you can still add tab indexes manually by passing a -tabindex option to each field-generating method.

-no_undef_params

This keeps CGI.pm from including undef params in the parameter list.

-no_xhtml

By default, CGI.pm versions 2.69 and higher emit XHTML (http://www.w3.org/TR/xhtml1/). The -no_xhtml pragma disables this feature. Thanks to Michalis Kabrianis <kabrianis@hellug.gr> for this feature.

If start_html()'s -dtd parameter specifies an HTML 2.0 or 3.2 DTD, XHTML will automatically be disabled without needing to use this pragma.

-nph

This makes CGI.pm produce a header appropriate for an NPH (no parsed header) script. You may need to do other things as well to tell the server that the script is NPH. See the discussion of NPH scripts below.

-newstyle_urls

Separate the name=value pairs in CGI parameter query strings with semicolons rather than ampersands. For example:

   ?name=fred;age=24;favorite_color=3

Semicolon-delimited query strings are always accepted, but will not be emitted by self_url() and query_string() unless the -newstyle_urls pragma is specified.

This became the default in version 2.64.

-oldstyle_urls

Separate the name=value pairs in CGI parameter query strings with ampersands rather than semicolons. This is no longer the default.

-autoload

This overrides the autoloader so that any function in your program that is not recognized is referred to CGI.pm for possible evaluation. This allows you to use all the CGI.pm functions without adding them to your symbol table, which is of concern for mod_perl users who are worried about memory consumption. Warning: when -autoload is in effect, you cannot use "poetry mode" (functions without the parenthesis). Use hr() rather than hr, or add something like use subs qw/hr p header/ to the top of your script.

-no_debug

This turns off the command-line processing features. If you want to run a CGI.pm script from the command line to produce HTML, and you don't want it to read CGI parameters from the command line or STDIN, then use this pragma:

   use CGI qw(-no_debug :standard);
-debug

This turns on full debugging. In addition to reading CGI arguments from the command-line processing, CGI.pm will pause and try to read arguments from STDIN, producing the message "(offline mode: enter name=value pairs on standard input)" features.

See the section on debugging for more details.

-private_tempfiles

CGI.pm can process uploaded file. Ordinarily it spools the uploaded file to a temporary directory, then deletes the file when done. However, this opens the risk of eavesdropping as described in the file upload section. Another CGI script author could peek at this data during the upload, even if it is confidential information. On Unix systems, the -private_tempfiles pragma will cause the temporary file to be unlinked as soon as it is opened and before any data is written into it, reducing, but not eliminating the risk of eavesdropping (there is still a potential race condition). To make life harder for the attacker, the program chooses tempfile names by calculating a 32 bit checksum of the incoming HTTP headers.

To ensure that the temporary file cannot be read by other CGI scripts, use suEXEC or a CGI wrapper program to run your script. The temporary file is created with mode 0600 (neither world nor group readable).

The temporary directory is selected using the following algorithm:

    1. if the current user (e.g. "nobody") has a directory named
    "tmp" in its home directory, use that (Unix systems only).
    2. if the environment variable TMPDIR exists, use the location
    indicated.
    3. Otherwise try the locations /usr/tmp, /var/tmp, C:\temp,
    /tmp, /temp, ::Temporary Items, and \WWW_ROOT.

Each of these locations is checked that it is a directory and is writable. If not, the algorithm tries the next choice.

SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS

Many of the methods generate HTML tags. As described below, tag functions automatically generate both the opening and closing tags. For example:

  print h1('Level 1 Header');

produces

  <h1>Level 1 Header</h1>

There will be some times when you want to produce the start and end tags yourself. In this case, you can use the form start_tag_name and end_tag_name, as in:

  print start_h1,'Level 1 Header',end_h1;

With a few exceptions (described below), start_tag_name and end_tag_name functions are not generated automatically when you use CGI. However, you can specify the tags you want to generate start/end functions for by putting an asterisk in front of their name, or, alternatively, requesting either "start_tag_name" or "end_tag_name" in the import list.

Example:

  use CGI qw/:standard *table start_ul/;

In this example, the following functions are generated in addition to the standard ones:

  1. start_table() (generates a <table> tag)
  2. end_table() (generates a </table> tag)
  3. start_ul() (generates a <ul> tag)
  4. end_ul() (generates a </ul> tag)

GENERATING DYNAMIC DOCUMENTS

Most of CGI.pm's functions deal with creating documents on the fly. Generally you will produce the HTTP header first, followed by the document itself. CGI.pm provides functions for generating HTTP headers of various types as well as for generating HTML. For creating GIF images, see the GD.pm module.

Each of these functions produces a fragment of HTML or HTTP which you can print out directly so that it displays in the browser window, append to a string, or save to a file for later use.

CREATING A STANDARD HTTP HEADER:

Normally the first thing you will do in any CGI script is print out an HTTP header. This tells the browser what type of document to expect, and gives other optional information, such as the language, expiration date, and whether to cache the document. The header can also be manipulated for special purposes, such as server push and pay per view pages.

        print header;

             -or-
        print header('image/gif');

             -or-
        print header('text/html','204 No response');

             -or-
        print header(-type=>'image/gif',
                             -nph=>1,
                             -status=>'402 Payment required',
                             -expires=>'+3d',
                             -cookie=>$cookie,
                             -charset=>'utf-7',
                             -attachment=>'foo.gif',
                             -Cost=>'$2.00');

header() returns the Content-type: header. You can provide your own MIME type if you choose, otherwise it defaults to text/html. An optional second parameter specifies the status code and a human-readable message. For example, you can specify 204, "No response" to create a script that tells the browser to do nothing at all.

The last example shows the named argument style for passing arguments to the CGI methods using named parameters. Recognized parameters are -type, -status, -expires, and -cookie. Any other named parameters will be stripped of their initial hyphens and turned into header fields, allowing you to specify any HTTP header you desire. Internal underscores will be turned into hyphens:

    print header(-Content_length=>3002);

Most browsers will not cache the output from CGI scripts. Every time the browser reloads the page, the script is invoked anew. You can change this behavior with the -expires parameter. When you specify an absolute or relative expiration interval with this parameter, some browsers and proxy servers will cache the script's output until the indicated expiration date. The following forms are all valid for the -expires field:

        +30s                              30 seconds from now
        +10m                              ten minutes from now
        +1h                               one hour from now
        -1d                               yesterday (i.e. "ASAP!")
        now                               immediately
        +3M                               in three months
        +10y                              in ten years time
        Thursday, 25-Apr-1999 00:40:33 GMT  at the indicated time & date

The -cookie parameter generates a header that tells the browser to provide a "magic cookie" during all subsequent transactions with your script. Netscape cookies have a special format that includes interesting attributes such as expiration time. Use the cookie() method to create and retrieve session cookies.

The -nph parameter, if set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script. This is important to use with certain servers that expect all their scripts to be NPH.

The -charset parameter can be used to control the character set sent to the browser. If not provided, defaults to ISO-8859-1. As a side effect, this sets the charset() method as well.

The -attachment parameter can be used to turn the page into an attachment. Instead of displaying the page, some browsers will prompt the user to save it to disk. The value of the argument is the suggested name for the saved file. In order for this to work, you may have to set the -type to "application/octet-stream".

The -p3p parameter will add a P3P tag to the outgoing header. The parameter can be an arrayref or a space-delimited string of P3P tags. For example:

   print header(-p3p=>[qw(CAO DSP LAW CURa)]);
   print header(-p3p=>'CAO DSP LAW CURa');

In either case, the outgoing header will be formatted as:

  P3P: policyref="/w3c/p3p.xml" cp="CAO DSP LAW CURa"

GENERATING A REDIRECTION HEADER

   print redirect('http://somewhere.else/in/movie/land');

Sometimes you don't want to produce a document yourself, but simply redirect the browser elsewhere, perhaps choosing a URL based on the time of day or the identity of the user.

The redirect() function redirects the browser to a different URL. If you use redirection like this, you should not print out a header as well.

You should always use full URLs (including the http: or ftp: part) in redirection requests. Relative URLs will not work correctly.

You can also use named arguments:

    print redirect(-uri=>'http://somewhere.else/in/movie/land',
                           -nph=>1,
                           -status=>301);

The -nph parameter, if set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script. This is important to use with certain servers, such as Microsoft IIS, which expect all their scripts to be NPH.

The -status parameter will set the status of the redirect. HTTP defines three different possible redirection status codes:

     301 Moved Permanently
     302 Found
     303 See Other

The default if not specified is 302, which means "moved temporarily." You may change the status to another status code if you wish. Be advised that changing the status to anything other than 301, 302 or 303 will probably break redirection.

CREATING THE HTML DOCUMENT HEADER

   print start_html(-title=>'Secrets of the Pyramids',
                            -author=>'fred@capricorn.org',
                            -base=>'true',
                            -target=>'_blank',
                            -meta=>{'keywords'=>'pharaoh secret mummy',
                                    'copyright'=>'copyright 1996 King Tut'},
                            -style=>{'src'=>'/styles/style1.css'},
                            -BGCOLOR=>'blue');

After creating the HTTP header, most CGI scripts will start writing out an HTML document. The start_html() routine creates the top of the page, along with a lot of optional information that controls the page's appearance and behavior.

This method returns a canned HTML header and the opening <body> tag. All parameters are optional. In the named parameter form, recognized parameters are -title, -author, -base, -xbase, -dtd, -lang and -target (see below for the explanation). Any additional parameters you provide, such as the Netscape unofficial BGCOLOR attribute, are added to the <body> tag. Additional parameters must be proceeded by a hyphen.

The argument -xbase allows you to provide an HREF for the <base> tag different from the current location, as in

    -xbase=>"http://home.mcom.com/";

All relative links will be interpreted relative to this tag.

The argument -target allows you to provide a default target frame for all the links and fill-out forms on the page. This is a non-standard HTTP feature which only works with Netscape browsers! See the Netscape documentation on frames for details of how to manipulate this.

    -target=>"answer_window"

All relative links will be interpreted relative to this tag. You add arbitrary meta information to the header with the -meta argument. This argument expects a reference to an associative array containing name/value pairs of meta information. These will be turned into a series of header <meta> tags that look something like this:

    <meta name="keywords" content="pharaoh secret mummy">
    <meta name="description" content="copyright 1996 King Tut">

To create an HTTP-EQUIV type of <meta> tag, use -head, described below.

The -style argument is used to incorporate cascading stylesheets into your code. See the section on CASCADING STYLESHEETS for more information.

The -lang argument is used to incorporate a language attribute into the <html> tag. For example:

    print $q->start_html(-lang=>'fr-CA');

The default if not specified is "en-US" for US English, unless the -dtd parameter specifies an HTML 2.0 or 3.2 DTD, in which case the lang attribute is left off. You can force the lang attribute to left off in other cases by passing an empty string (-lang=>'').

The -encoding argument can be used to specify the character set for XHTML. It defaults to iso-8859-1 if not specified.

The -declare_xml argument, when used in conjunction with XHTML, will put a <?xml> declaration at the top of the HTML header. The sole purpose of this declaration is to declare the character set encoding. In the absence of -declare_xml, the output HTML will contain a <meta> tag that specifies the encoding, allowing the HTML to pass most validators. The default for -declare_xml is false.

You can place other arbitrary HTML elements to the <head> section with the -head tag. For example, to place the rarely-used <link> element in the head section, use this:

    print start_html(-head=>Link({-rel=>'next',
                                  -href=>'http://www.capricorn.com/s2.html'}));

To incorporate multiple HTML elements into the <head> section, just pass an array reference:

    print start_html(-head=>[
                             Link({-rel=>'next',
                                   -href=>'http://www.capricorn.com/s2.html'}),
                             Link({-rel=>'previous',
                                   -href=>'http://www.capricorn.com/s1.html'})
                             ]
                     );

And here's how to create an HTTP-EQUIV <meta> tag:

      print start_html(-head=>meta({-http_equiv => 'Content-Type',
                                    -content    => 'text/html'}))

JAVASCRIPTING: The -script, -noScript, -onLoad, -onMouseOver, -onMouseOut and -onUnload parameters are used to add Netscape JavaScript calls to your pages. -script should point to a block of text containing JavaScript function definitions. This block will be placed within a <script> block inside the HTML (not HTTP) header. The block is placed in the header in order to give your page a fighting chance of having all its JavaScript functions in place even if the user presses the stop button before the page has loaded completely. CGI.pm attempts to format the script in such a way that JavaScript-naive browsers will not choke on the code: unfortunately there are some browsers, such as Chimera for Unix, that get confused by it nevertheless.

The -onLoad and -onUnload parameters point to fragments of JavaScript code to execute when the page is respectively opened and closed by the browser. Usually these parameters are calls to functions defined in the -script field:

      $query = new CGI;
      print header;
      $JSCRIPT=<<END;
      // Ask a silly question
      function riddle_me_this() {
         var r = prompt("What walks on four legs in the morning, " +
                       "two legs in the afternoon, " +
                       "and three legs in the evening?");
         response(r);
      }
      // Get a silly answer
      function response(answer) {
         if (answer == "man")
            alert("Right you are!");
         else
            alert("Wrong!  Guess again.");
      }
      END
      print start_html(-title=>'The Riddle of the Sphinx',
                               -script=>$JSCRIPT);

Use the -noScript parameter to pass some HTML text that will be displayed on browsers that do not have JavaScript (or browsers where JavaScript is turned off).

Netscape 3.0 recognizes several attributes of the <script> tag, including LANGUAGE and SRC. The latter is particularly interesting, as it allows you to keep the JavaScript code in a file or CGI script rather than cluttering up each page with the source. To use these attributes pass a HASH reference in the -script parameter containing one or more of -language, -src, or -code:

    print $q->start_html(-title=>'The Riddle of the Sphinx',
                         -script=>{-language=>'JAVASCRIPT',
                                   -src=>'/javascript/sphinx.js'}
                         );

    print $q->(-title=>'The Riddle of the Sphinx',
               -script=>{-language=>'PERLSCRIPT',
                         -code=>'print "hello world!\n;"'}
               );

A final feature allows you to incorporate multiple <script> sections into the header. Just pass the list of script sections as an array reference. this allows you to specify different source files for different dialects of JavaScript. Example:

     print $q->start_html(-title=>'The Riddle of the Sphinx',
                          -script=>[
                                    { -language => 'JavaScript1.0',
                                      -src      => '/javascript/utilities10.js'
                                    },
                                    { -language => 'JavaScript1.1',
                                      -src      => '/javascript/utilities11.js'
                                    },
                                    { -language => 'JavaScript1.2',
                                      -src      => '/javascript/utilities12.js'
                                    },
                                    { -language => 'JavaScript28.2',
                                      -src      => '/javascript/utilities219.js'
                                    }
                                 ]
                             );

If this looks a bit extreme, take my advice and stick with straight CGI scripting.

See

   http://home.netscape.com/eng/mozilla/2.0/handbook/javascript/

for more information about JavaScript.

The old-style positional parameters are as follows:

Parameters:

  • The title

  • The author's e-mail address (will create a <link rev="MADE"> tag if present

  • A 'true' flag if you want to include a <base> tag in the header. This helps resolve relative addresses to absolute ones when the document is moved, but makes the document hierarchy non-portable. Use with care!

  • , 5, 6...

    Any other parameters you want to include in the <body> tag. This is a good place to put Netscape extensions, such as colors and wallpaper patterns.

    • ENDING THE HTML DOCUMENT:

            print end_html

    This ends an HTML document by printing the </body></html> tags.

    CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:

        $myself = self_url;
    print q(<a href="$myself">I'm talking to myself.</a>);

    self_url() will return a URL, that, when selected, will reinvoke this script with all its state information intact. This is most useful when you want to jump around within the document using internal anchors but you don't want to disrupt the current contents of the form(s). Something like this will do the trick.

         $myself = self_url;
     print "<a href=\"$myself#table1\">See table 1</a>";
     print "<a href=\"$myself#table2\">See table 2</a>";
     print "<a href=\"$myself#yourself\">See for yourself</a>";

    If you want more control over what's returned, using the url() method instead.

    You can also retrieve the unprocessed query string with query_string():

        $the_string = query_string;

    OBTAINING THE SCRIPT'S URL

        $full_url      = url();
    $full_url      = url(-full=>1);  #alternative syntax
    $relative_url  = url(-relative=>1);
    $absolute_url  = url(-absolute=>1);
    $url_with_path = url(-path_info=>1);
    $url_with_path_and_query = url(-path_info=>1,-query=>1);
    $netloc        = url(-base => 1);

    url() returns the script's URL in a variety of formats. Called without any arguments, it returns the full form of the URL, including host name and port number

        http://your.host.com/path/to/script.cgi

    You can modify this format with the following named arguments:

    -absolute

    If true, produce an absolute URL, e.g.

        /path/to/script.cgi
    -relative

    Produce a relative URL. This is useful if you want to reinvoke your script with different parameters. For example:

        script.cgi
    -full

    Produce the full URL, exactly as if called without any arguments. This overrides the -relative and -absolute arguments.

    -path (-path_info)

    Append the additional path information to the URL. This can be combined with -full, -absolute or -relative. -path_info is provided as a synonym.

    -query (-query_string)

    Append the query string to the URL. This can be combined with -full, -absolute or -relative. -query_string is provided as a synonym.

    -base

    Generate just the protocol and net location, as in http://www.foo.com:8000

    -rewrite

    If Apache's mod_rewrite is turned on, then the script name and path info probably won't match the request that the user sent. Set -rewrite=>1 (default) to return URLs that match what the user sent (the original request URI). Set -rewrite->0 to return URLs that match the URL after mod_rewrite's rules have run. Because the additional path information only makes sense in the context of the rewritten URL, -rewrite is set to false when you request path info in the URL.

    MIXING POST AND URL PARAMETERS

       $color = url_param('color');

    It is possible for a script to receive CGI parameters in the URL as well as in the fill-out form by creating a form that POSTs to a URL containing a query string (a "?" mark followed by arguments). The param() method will always return the contents of the POSTed fill-out form, ignoring the URL's query string. To retrieve URL parameters, call the url_param() method. Use it in the same way as param(). The main difference is that it allows you to read the parameters, but not set them.

    Under no circumstances will the contents of the URL query string interfere with similarly-named CGI parameters in POSTed forms. If you try to mix a URL query string with a form submitted with the GET method, the results will not be what you expect.

    CREATING STANDARD HTML ELEMENTS:

    CGI.pm defines general HTML shortcut methods for most, if not all of the HTML 3 and HTML 4 tags. HTML shortcuts are named after a single HTML element and return a fragment of HTML text that you can then print or manipulate as you like. Each shortcut returns a fragment of HTML code that you can append to a string, save to a file, or, most commonly, print out so that it displays in the browser window.

    This example shows how to use the HTML methods:

       print $q->blockquote(
                     "Many years ago on the island of",
                     $q->a({href=>"http://crete.org/"},"Crete"),
                     "there lived a Minotaur named",
                     $q->strong("Fred."),
                    ),
       $q->hr;

    This results in the following HTML code (extra newlines have been added for readability):

       <blockquote>
   Many years ago on the island of
   <a href="http://crete.org/">Crete</a> there lived
   a minotaur named <strong>Fred.</strong>
   </blockquote>
   <hr>

    If you find the syntax for calling the HTML shortcuts awkward, you can import them into your namespace and dispense with the object syntax completely (see the next section for more details):

       use CGI ':standard';
   print blockquote(
      "Many years ago on the island of",
      a({href=>"http://crete.org/"},"Crete"),
      "there lived a minotaur named",
      strong("Fred."),
      ),
      hr;

    PROVIDING ARGUMENTS TO HTML SHORTCUTS

    The HTML methods will accept zero, one or multiple arguments. If you provide no arguments, you get a single tag:

       print hr;    #  <hr>

    If you provide one or more string arguments, they are concatenated together with spaces and placed between opening and closing tags:

       print h1("Chapter","1"); # <h1>Chapter 1</h1>"

    If the first argument is an associative array reference, then the keys and values of the associative array become the HTML tag's attributes:

       print a({-href=>'fred.html',-target=>'_new'},
      "Open a new frame");

                <a href="fred.html",target="_new">Open a new frame</a>

    You may dispense with the dashes in front of the attribute names if you prefer:

       print img {src=>'fred.gif',align=>'LEFT'};

               <img align="LEFT" src="fred.gif">

    Sometimes an HTML tag attribute has no argument. For example, ordered lists can be marked as COMPACT. The syntax for this is an argument that that points to an undef string:

       print ol({compact=>undef},li('one'),li('two'),li('three'));

    Prior to CGI.pm version 2.41, providing an empty ('') string as an attribute argument was the same as providing undef. However, this has changed in order to accommodate those who want to create tags of the form <img alt="">. The difference is shown in these two pieces of code:

       CODE                   RESULT
   img({alt=>undef})      <img alt>
   img({alt=>''})         <img alt="">

    THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS

    One of the cool features of the HTML shortcuts is that they are distributive. If you give them an argument consisting of a reference to a list, the tag will be distributed across each element of the list. For example, here's one way to make an ordered list:

       print ul(
             li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy'])
           );

    This example will result in HTML output that looks like this:

       <ul>
     <li type="disc">Sneezy</li>
     <li type="disc">Doc</li>
     <li type="disc">Sleepy</li>
     <li type="disc">Happy</li>
   </ul>

    This is extremely useful for creating tables. For example:

       print table({-border=>undef},
           caption('When Should You Eat Your Vegetables?'),
           Tr({-align=>CENTER,-valign=>TOP},
           [
              th(['Vegetable', 'Breakfast','Lunch','Dinner']),
              td(['Tomatoes' , 'no', 'yes', 'yes']),
              td(['Broccoli' , 'no', 'no',  'yes']),
              td(['Onions'   , 'yes','yes', 'yes'])
           ]
           )
        );

    HTML SHORTCUTS AND LIST INTERPOLATION

    Consider this bit of code:

       print blockquote(em('Hi'),'mom!'));

    It will ordinarily return the string that you probably expect, namely:

       <blockquote><em>Hi</em> mom!</blockquote>

    Note the space between the element "Hi" and the element "mom!". CGI.pm puts the extra space there using array interpolation, which is controlled by the magic $" variable. Sometimes this extra space is not what you want, for example, when you are trying to align a series of images. In this case, you can simply change the value of $" to an empty string.

       {
      local($") = '';
      print blockquote(em('Hi'),'mom!'));
    }

    I suggest you put the code in a block as shown here. Otherwise the change to $" will affect all subsequent code until you explicitly reset it.

    NON-STANDARD HTML SHORTCUTS

    A few HTML tags don't follow the standard pattern for various reasons.

    comment() generates an HTML comment (<!-- comment -->). Call it like

        print comment('here is my comment');

    Because of conflicts with built-in Perl functions, the following functions begin with initial caps:

        Select
    Tr
    Link
    Delete
    Accept
    Sub

    In addition, start_html(), end_html(), start_form(), end_form(), start_multipart_form() and all the fill-out form tags are special. See their respective sections.

    AUTOESCAPING HTML

    By default, all HTML that is emitted by the form-generating functions is passed through a function called escapeHTML():

    $escaped_string = escapeHTML("unescaped string");

    Escape HTML formatting characters in a string.

    Provided that you have specified a character set of ISO-8859-1 (the default), the standard HTML escaping rules will be used. The "<" character becomes "&lt;", ">" becomes "&gt;", "&" becomes "&amp;", and the quote character becomes "&quot;". In addition, the hexadecimal 0x8b and 0x9b characters, which some browsers incorrectly interpret as the left and right angle-bracket characters, are replaced by their numeric character entities ("&#8249" and "&#8250;"). If you manually change the charset, either by calling the charset() method explicitly or by passing a -charset argument to header(), then all characters will be replaced by their numeric entities, since CGI.pm has no lookup table for all the possible encodings.

    The automatic escaping does not apply to other shortcuts, such as h1(). You should call escapeHTML() yourself on untrusted data in order to protect your pages against nasty tricks that people may enter into guestbooks, etc.. To change the character set, use charset(). To turn autoescaping off completely, use autoEscape(0):

    $charset = charset([$charset]);

    Get or set the current character set.

    $flag = autoEscape([$flag]);

    Get or set the value of the autoescape flag.

    PRETTY-PRINTING HTML

    By default, all the HTML produced by these functions comes out as one long line without carriage returns or indentation. This is yuck, but it does reduce the size of the documents by 10-20%. To get pretty-printed output, please use the CGI::Pretty manpage, a subclass contributed by Brian Paulsen.

    CREATING FILL-OUT FORMS:

    General note The various form-creating methods all return strings to the caller, containing the tag or tags that will create the requested form element. You are responsible for actually printing out these strings. It's set up this way so that you can place formatting tags around the form elements.

    Another note The default values that you specify for the forms are only used the first time the script is invoked (when there is no query string). On subsequent invocations of the script (when there is a query string), the former values are used even if they are blank.

    If you want to change the value of a field from its previous value, you have two choices:

    (1) call the param() method to set it.

    (2) use the -override (alias -force) parameter (a new feature in version 2.15). This forces the default value to be used, regardless of the previous value:

       print textfield(-name=>'field_name',
                           -default=>'starting value',
                           -override=>1,
                           -size=>50,
                           -maxlength=>80);

    Yet another note By default, the text and labels of form elements are escaped according to HTML rules. This means that you can safely use "<CLICK ME>" as the label for a button. However, it also interferes with your ability to incorporate special HTML character sequences, such as &Aacute;, into your fields. If you wish to turn off automatic escaping, call the autoEscape() method with a false value immediately after creating the CGI object:

       $query = new CGI;
   autoEscape(undef);

    A Lurking Trap! Some of the form-element generating methods return multiple tags. In a scalar context, the tags will be concatenated together with spaces, or whatever is the current value of the $" global. In a list context, the methods will return a list of elements, allowing you to modify them if you wish. Usually you will not notice this behavior, but beware of this:

        printf("%s\n",end_form())

    end_form() produces several tags, and only the first of them will be printed because the format only expects one value.

    <p>

    CREATING AN ISINDEX TAG

       print isindex(-action=>$action);

             -or-
       print isindex($action);

    Prints out an <isindex> tag. Not very exciting. The parameter -action specifies the URL of the script to process the query. The default is to process the query with the current script.

    STARTING AND ENDING A FORM

        print start_form(-method=>$method,
                    -action=>$action,
                    -enctype=>$encoding);
      <... various form stuff ...>
    print endform;

            -or-
        print start_form($method,$action,$encoding);
      <... various form stuff ...>
    print endform;

    start_form() will return a <form> tag with the optional method, action and form encoding that you specify. The defaults are:

        method: POST
    action: this script
    enctype: application/x-www-form-urlencoded

    endform() returns the closing </form> tag.

    Start_form()'s enctype argument tells the browser how to package the various fields of the form before sending the form to the server. Two values are possible:

    Note: This method was previously named startform(), and startform() is still recognized as an alias.

    application/x-www-form-urlencoded

    This is the older type of encoding used by all browsers prior to Netscape 2.0. It is compatible with many CGI scripts and is suitable for short fields containing text data. For your convenience, CGI.pm stores the name of this encoding type in &CGI::URL_ENCODED.

    multipart/form-data

    This is the newer type of encoding introduced by Netscape 2.0. It is suitable for forms that contain very large fields or that are intended for transferring binary data. Most importantly, it enables the "file upload" feature of Netscape 2.0 forms. For your convenience, CGI.pm stores the name of this encoding type in &CGI::MULTIPART

    Forms that use this type of encoding are not easily interpreted by CGI scripts unless they use CGI.pm or another library designed to handle them.

    If XHTML is activated (the default), then forms will be automatically created using this type of encoding.

    For compatibility, the start_form() method uses the older form of encoding by default. If you want to use the newer form of encoding by default, you can call start_multipart_form() instead of start_form().

    JAVASCRIPTING: The -name and -onSubmit parameters are provided for use with JavaScript. The -name parameter gives the form a name so that it can be identified and manipulated by JavaScript functions. -onSubmit should point to a JavaScript function that will be executed just before the form is submitted to your server. You can use this opportunity to check the contents of the form for consistency and completeness. If you find something wrong, you can put up an alert box or maybe fix things up yourself. You can abort the submission by returning false from this function.

    Usually the bulk of JavaScript functions are defined in a <script> block in the HTML header and -onSubmit points to one of these function call. See start_html() for details.

    FORM ELEMENTS

    After starting a form, you will typically create one or more textfields, popup menus, radio groups and other form elements. Each of these elements takes a standard set of named arguments. Some elements also have optional arguments. The standard arguments are as follows:

    -name

    The name of the field. After submission this name can be used to retrieve the field's value using the param() method.

    -value, -values

    The initial value of the field which will be returned to the script after form submission. Some form elements, such as text fields, take a single scalar -value argument. Others, such as popup menus, take a reference to an array of values. The two arguments are synonyms.

    -tabindex

    A numeric value that sets the order in which the form element receives focus when the user presses the tab key. Elements with lower values receive focus first.

    -id

    A string identifier that can be used to identify this element to JavaScript and DHTML.

    -override

    A boolean, which, if true, forces the element to take on the value specified by -value, overriding the sticky behavior described earlier for the -no_sticky pragma.

    -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect

    These are used to assign JavaScript event handlers. See the JavaScripting section for more details.

    Other common arguments are described in the next section. In addition to these, all attributes described in the HTML specifications are supported.

    CREATING A TEXT FIELD

        print textfield(-name=>'field_name',
                    -value=>'starting value',
                    -size=>50,
                    -maxlength=>80);
        -or-

        print textfield('field_name','starting value',50,80);

    textfield() will return a text input field.

    Parameters

  • The first parameter is the required name for the field (-name).

  • The optional second parameter is the default starting value for the field contents (-value, formerly known as -default).

  • The optional third parameter is the size of the field in characters (-size).

  • The optional fourth parameter is the maximum number of characters the field will accept (-maxlength).

    • As with all these methods, the field will be initialized with its previous contents from earlier invocations of the script. When the form is processed, the value of the text field can be retrieved with:

           $value = param('foo');

    If you want to reset it from its initial value after the script has been called once, you can do so like this:

           param('foo',"I'm taking over this value!");

    CREATING A BIG TEXT FIELD

       print textarea(-name=>'foo',
                          -default=>'starting value',
                          -rows=>10,
                          -columns=>50);

            -or
       print textarea('foo','starting value',10,50);

    textarea() is just like textfield, but it allows you to specify rows and columns for a multiline text entry box. You can provide a starting value for the field, which can be long and contain multiple lines.

    CREATING A PASSWORD FIELD

       print password_field(-name=>'secret',
                                -value=>'starting value',
                                -size=>50,
                                -maxlength=>80);
        -or-

       print password_field('secret','starting value',50,80);

    password_field() is identical to textfield(), except that its contents will be starred out on the web page.

    CREATING A FILE UPLOAD FIELD

        print filefield(-name=>'uploaded_file',
                            -default=>'starting value',
                            -size=>50,
                            -maxlength=>80);
        -or-

        print filefield('uploaded_file','starting value',50,80);

    filefield() will return a file upload field for Netscape 2.0 browsers. In order to take full advantage of this you must use the new multipart encoding scheme for the form. You can do this either by calling start_form() with an encoding type of &CGI::MULTIPART, or by calling the new method start_multipart_form() instead of vanilla start_form().

    Parameters

  • The first parameter is the required name for the field (-name).

  • The optional second parameter is the starting value for the field contents to be used as the default file name (-default).

    For security reasons, browsers don't pay any attention to this field, and so the starting value will always be blank. Worse, the field loses its "sticky" behavior and forgets its previous contents. The starting value field is called for in the HTML specification, however, and possibly some browser will eventually provide support for it.

  • The optional third parameter is the size of the field in characters (-size).

  • The optional fourth parameter is the maximum number of characters the field will accept (-maxlength).

    • When the form is processed, you can retrieve the entered filename by calling param():

           $filename = param('uploaded_file');

    Different browsers will return slightly different things for the name. Some browsers return the filename only. Others return the full path to the file, using the path conventions of the user's machine. Regardless, the name returned is always the name of the file on the user's machine, and is unrelated to the name of the temporary file that CGI.pm creates during upload spooling (see below).

    The filename returned is also a file handle. You can read the contents of the file using standard Perl file reading calls:

            # Read a text file and print it out
        while (<$filename>) {
           print;
        }

            # Copy a binary file to somewhere safe
        open (OUTFILE,">>/usr/local/web/users/feedback");
        while ($bytesread=read($filename,$buffer,1024)) {
           print OUTFILE $buffer;
        }

    However, there are problems with the dual nature of the upload fields. If you use strict, then Perl will complain when you try to use a string as a filehandle. You can get around this by placing the file reading code in a block containing the no strict pragma. More seriously, it is possible for the remote user to type garbage into the upload field, in which case what you get from param() is not a filehandle at all, but a string.

    To be safe, use the upload() function (new in version 2.47). When called with the name of an upload field, upload() returns a filehandle, or undef if the parameter is not a valid filehandle.

         $fh = upload('uploaded_file');
     while (<$fh>) {
           print;
     }

    In an list context, upload() will return an array of filehandles. This makes it possible to create forms that use the same name for multiple upload fields.

    This is the recommended idiom.

    When a file is uploaded the browser usually sends along some information along with it in the format of headers. The information usually includes the MIME content type. Future browsers may send other information as well (such as modification date and size). To retrieve this information, call uploadInfo(). It returns a reference to an associative array containing all the document headers.

           $filename = param('uploaded_file');
       $type = uploadInfo($filename)->{'Content-Type'};
       unless ($type eq 'text/html') {
          die "HTML FILES ONLY!";
       }

    If you are using a machine that recognizes "text" and "binary" data modes, be sure to understand when and how to use them (see the Camel book). Otherwise you may find that binary files are corrupted during file uploads.

    There are occasionally problems involving parsing the uploaded file. This usually happens when the user presses "Stop" before the upload is finished. In this case, CGI.pm will return undef for the name of the uploaded file and set cgi_error() to the string "400 Bad request (malformed multipart POST)". This error message is designed so that you can incorporate it into a status code to be sent to the browser. Example:

       $file = upload('uploaded_file');
   if (!$file && cgi_error) {
      print header(-status=>cgi_error);
      exit 0;
   }

    You are free to create a custom HTML page to complain about the error, if you wish.

    You can set up a callback that will be called whenever a file upload is being read during the form processing. This is much like the UPLOAD_HOOK facility available in Apache::Request, with the exception that the first argument to the callback is an Apache::Upload object, here it's the remote filename.

     $q = CGI->new(\&hook [,$data [,$use_tempfile]]);

     sub hook
 {
        my ($filename, $buffer, $bytes_read, $data) = @_;
        print  "Read $bytes_read bytes of $filename\n";
 }

    The $data field is optional; it lets you pass configuration information (e.g. a database handle) to your hook callback.

    The $use_tempfile field is a flag that lets you turn on and off CGI.pm's use of a temporary disk-based file during file upload. If you set this to a FALSE value (default true) then param('uploaded_file') will no longer work, and the only way to get at the uploaded data is via the hook you provide.

    If using the function-oriented interface, call the CGI::upload_hook() method before calling param() or any other CGI functions:

      CGI::upload_hook(\&hook [,$data [,$use_tempfile]]);

    This method is not exported by default. You will have to import it explicitly if you wish to use it without the CGI:: prefix.

    If you are using CGI.pm on a Windows platform and find that binary files get slightly larger when uploaded but that text files remain the same, then you have forgotten to activate binary mode on the output filehandle. Be sure to call binmode() on any handle that you create to write the uploaded file to disk.

    JAVASCRIPTING: The -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut and -onSelect parameters are recognized. See textfield() for details.

    CREATING A POPUP MENU

       print popup_menu('menu_name',
                            ['eenie','meenie','minie'],
                            'meenie');

          -or-
       %labels = ('eenie'=>'your first choice',
              'meenie'=>'your second choice',
              'minie'=>'your third choice');
   %attributes = ('eenie'=>{'class'=>'class of first choice'});
   print popup_menu('menu_name',
                            ['eenie','meenie','minie'],
          'meenie',\%labels,\%attributes);

            -or (named parameter style)-
       print popup_menu(-name=>'menu_name',
                            -values=>['eenie','meenie','minie'],
                            -default=>'meenie',
          -labels=>\%labels,
          -attributes=>\%attributes);

    popup_menu() creates a menu.

    1. The required first argument is the menu's name (-name).

    2. The required second argument (-values) is an array reference containing the list of menu items in the menu. You can pass the method an anonymous array, as shown in the example, or a reference to a named array, such as "\@foo".

    3. The optional third parameter (-default) is the name of the default menu choice. If not specified, the first item will be the default. The values of the previous choice will be maintained across queries.

    4. The optional fourth parameter (-labels) is provided for people who want to use different values for the user-visible label inside the popup menu and the value returned to your script. It's a pointer to an associative array relating menu values to user-visible labels. If you leave this parameter blank, the menu values will be displayed by default. (You can also leave a label undefined if you want to).

    5. The optional fifth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to an associative array relating menu values to another associative array with the attribute's name as the key and the attribute's value as the value.

    When the form is processed, the selected value of the popup menu can be retrieved using:

          $popup_menu_value = param('menu_name');

    CREATING AN OPTION GROUP

    Named parameter style

      print popup_menu(-name=>'menu_name',
                  -values=>[qw/eenie meenie minie/,
                            optgroup(-name=>'optgroup_name',
                                             -values => ['moe','catch'],
                                             -attributes=>{'catch'=>{'class'=>'red'}})],
                  -labels=>{'eenie'=>'one',
                            'meenie'=>'two',
                            'minie'=>'three'},
                  -default=>'meenie');

      Old style
  print popup_menu('menu_name',
                  ['eenie','meenie','minie',
                   optgroup('optgroup_name', ['moe', 'catch'],
                                   {'catch'=>{'class'=>'red'}})],'meenie',
                  {'eenie'=>'one','meenie'=>'two','minie'=>'three'});

    optgroup() creates an option group within a popup menu.

    1. The required first argument (-name) is the label attribute of the optgroup and is not inserted in the parameter list of the query.

    2. The required second argument (-values) is an array reference containing the list of menu items in the menu. You can pass the method an anonymous array, as shown in the example, or a reference to a named array, such as \@foo. If you pass a HASH reference, the keys will be used for the menu values, and the values will be used for the menu labels (see -labels below).

    3. The optional third parameter (-labels) allows you to pass a reference to an associative array containing user-visible labels for one or more of the menu items. You can use this when you want the user to see one menu string, but have the browser return your program a different one. If you don't specify this, the value string will be used instead ("eenie", "meenie" and "minie" in this example). This is equivalent to using a hash reference for the -values parameter.

    4. An optional fourth parameter (-labeled) can be set to a true value and indicates that the values should be used as the label attribute for each option element within the optgroup.

    5. An optional fifth parameter (-novals) can be set to a true value and indicates to suppress the val attribute in each option element within the optgroup.

      See the discussion on optgroup at W3C (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP) for details.

    6. An optional sixth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to an associative array relating menu values to another associative array with the attribute's name as the key and the attribute's value as the value.

    CREATING A SCROLLING LIST

       print scrolling_list('list_name',
                                ['eenie','meenie','minie','moe'],
        ['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
      -or-

       print scrolling_list('list_name',
                                ['eenie','meenie','minie','moe'],
                                ['eenie','moe'],5,'true',
        \%labels,%attributes);

            -or-
       print scrolling_list(-name=>'list_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
                                -size=>5,
                                -multiple=>'true',
        -labels=>\%labels,
        -attributes=>\%attributes);

    scrolling_list() creates a scrolling list.

    Parameters:

  • The first and second arguments are the list name (-name) and values (-values). As in the popup menu, the second argument should be an array reference.

  • The optional third argument (-default) can be either a reference to a list containing the values to be selected by default, or can be a single value to select. If this argument is missing or undefined, then nothing is selected when the list first appears. In the named parameter version, you can use the synonym "-defaults" for this parameter.

  • The optional fourth argument is the size of the list (-size).

  • The optional fifth argument can be set to true to allow multiple simultaneous selections (-multiple). Otherwise only one selection will be allowed at a time.

  • The optional sixth argument is a pointer to an associative array containing long user-visible labels for the list items (-labels). If not provided, the values will be displayed.

  • The optional sixth parameter (-attributes) is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to an associative array relating menu values to another associative array with the attribute's name as the key and the attribute's value as the value.

    When this form is processed, all selected list items will be returned as a list under the parameter name 'list_name'. The values of the selected items can be retrieved with:

          @selected = param('list_name');

    • CREATING A GROUP OF RELATED CHECKBOXES

       print checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
                                -linebreak=>'true',
        -labels=>\%labels,
        -attributes=>\%attributes);

       print checkbox_group('group_name',
                                ['eenie','meenie','minie','moe'],
        ['eenie','moe'],'true',\%labels,
        {'moe'=>{'class'=>'red'}});

       HTML3-COMPATIBLE BROWSERS ONLY:
       print checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -rows=2,-columns=>2);

    checkbox_group() creates a list of checkboxes that are related by the same name.

    Parameters:

  • The first and second arguments are the checkbox name and values, respectively (-name and -values). As in the popup menu, the second argument should be an array reference. These values are used for the user-readable labels printed next to the checkboxes as well as for the values passed to your script in the query string.

  • The optional third argument (-default) can be either a reference to a list containing the values to be checked by default, or can be a single value to checked. If this argument is missing or undefined, then nothing is selected when the list first appears.

  • The optional fourth argument (-linebreak) can be set to true to place line breaks between the checkboxes so that they appear as a vertical list. Otherwise, they will be strung together on a horizontal line.

    • The optional b<-labels> argument is a pointer to an associative array relating the checkbox values to the user-visible labels that will be printed next to them. If not provided, the values will be used as the default.

    Modern browsers can take advantage of the optional parameters -rows, and -columns. These parameters cause checkbox_group() to return an HTML3 compatible table containing the checkbox group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; checkbox_group will calculate the correct number of rows for you.

    The optional -attributes argument is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to an associative array relating menu values to another associative array with the attribute's name as the key and the attribute's value as the value.

    The optional -tabindex argument can be used to control the order in which radio buttons receive focus when the user presses the tab button. If passed a scalar numeric value, the first element in the group will receive this tab index and subsequent elements will be incremented by one. If given a reference to an array of radio button values, then the indexes will be jiggered so that the order specified in the array will correspond to the tab order. You can also pass a reference to a hash in which the hash keys are the radio button values and the values are the tab indexes of each button. Examples:

      -tabindex => 100    #  this group starts at index 100 and counts up
  -tabindex => ['moe','minie','eenie','meenie']  # tab in this order
  -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order

    When the form is processed, all checked boxes will be returned as a list under the parameter name 'group_name'. The values of the "on" checkboxes can be retrieved with:

          @turned_on = param('group_name');

    The value returned by checkbox_group() is actually an array of button elements. You can capture them and use them within tables, lists, or in other creative ways:

        @h = checkbox_group(-name=>'group_name',-values=>\@values);
    &use_in_creative_way(@h);

    CREATING A STANDALONE CHECKBOX

        print checkbox(-name=>'checkbox_name',
                           -checked=>1,
                           -value=>'ON',
                           -label=>'CLICK ME');

            -or-
        print checkbox('checkbox_name','checked','ON','CLICK ME');

    checkbox() is used to create an isolated checkbox that isn't logically related to any others.

    Parameters:

  • The first parameter is the required name for the checkbox (-name). It will also be used for the user-readable label printed next to the checkbox.

  • The optional second parameter (-checked) specifies that the checkbox is turned on by default. Synonyms are -selected and -on.

  • The optional third parameter (-value) specifies the value of the checkbox when it is checked. If not provided, the word "on" is assumed.

  • The optional fourth parameter (-label) is the user-readable label to be attached to the checkbox. If not provided, the checkbox name is used.

    • The value of the checkbox can be retrieved using:

        $turned_on = param('checkbox_name');

    CREATING A RADIO BUTTON GROUP

       print radio_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie'],
                             -default=>'meenie',
                             -linebreak=>'true',
           -labels=>\%labels,
           -attributes=>\%attributes);

            -or-
       print radio_group('group_name',['eenie','meenie','minie'],
            'meenie','true',\%labels,\%attributes);

       HTML3-COMPATIBLE BROWSERS ONLY:
       print radio_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -rows=2,-columns=>2);

    radio_group() creates a set of logically-related radio buttons (turning one member of the group on turns the others off)

    Parameters:

  • The first argument is the name of the group and is required (-name).

  • The second argument (-values) is the list of values for the radio buttons. The values and the labels that appear on the page are identical. Pass an array reference in the second argument, either using an anonymous array, as shown, or by referencing a named array as in "\@foo".

  • The optional third parameter (-default) is the name of the default button to turn on. If not specified, the first item will be the default. You can provide a nonexistent button name, such as "-" to start up with no buttons selected.

  • The optional fourth parameter (-linebreak) can be set to 'true' to put line breaks between the buttons, creating a vertical list.

  • The optional fifth parameter (-labels) is a pointer to an associative array relating the radio button values to user-visible labels to be used in the display. If not provided, the values themselves are displayed.

    • All modern browsers can take advantage of the optional parameters -rows, and -columns. These parameters cause radio_group() to return an HTML3 compatible table containing the radio group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; radio_group will calculate the correct number of rows for you.

    To include row and column headings in the returned table, you can use the -rowheader and -colheader parameters. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpretation of the radio buttons -- they're still a single named unit.

    The optional -tabindex argument can be used to control the order in which radio buttons receive focus when the user presses the tab button. If passed a scalar numeric value, the first element in the group will receive this tab index and subsequent elements will be incremented by one. If given a reference to an array of radio button values, then the indexes will be jiggered so that the order specified in the array will correspond to the tab order. You can also pass a reference to a hash in which the hash keys are the radio button values and the values are the tab indexes of each button. Examples:

      -tabindex => 100    #  this group starts at index 100 and counts up
  -tabindex => ['moe','minie','eenie','meenie']  # tab in this order
  -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order

    The optional -attributes argument is provided to assign any of the common HTML attributes to an individual menu item. It's a pointer to an associative array relating menu values to another associative array with the attribute's name as the key and the attribute's value as the value.

    When the form is processed, the selected radio button can be retrieved using:

          $which_radio_button = param('group_name');

    The value returned by radio_group() is actually an array of button elements. You can capture them and use them within tables, lists, or in other creative ways:

        @h = radio_group(-name=>'group_name',-values=>\@values);
    &use_in_creative_way(@h);

    CREATING A SUBMIT BUTTON

       print submit(-name=>'button_name',
                        -value=>'value');

            -or-
       print submit('button_name','value');

    submit() will create the query submission button. Every form should have one of these.

    Parameters:

  • The first argument (-name) is optional. You can give the button a name if you have several submission buttons in your form and you want to distinguish between them.

  • The second argument (-value) is also optional. This gives the button a value that will be passed to your script in the query string. The name will also be used as the user-visible label.

  • You can use -label as an alias for -value. I always get confused about which of -name and -value changes the user-visible label on the button.

    • You can figure out which button was pressed by using different values for each one:

         $which_one = param('button_name');

    CREATING A RESET BUTTON

       print reset

    reset() creates the "reset" button. Note that it restores the form to its value from the last time the script was called, NOT necessarily to the defaults.

    Note that this conflicts with the Perl reset() built-in. Use CORE::reset() to get the original reset function.

    CREATING A DEFAULT BUTTON

       print defaults('button_label')

    defaults() creates a button that, when invoked, will cause the form to be completely reset to its defaults, wiping out all the changes the user ever made.

    CREATING A HIDDEN FIELD

            print hidden(-name=>'hidden_name',
                             -default=>['value1','value2'...]);

                    -or-
            print hidden('hidden_name','value1','value2'...);

    hidden() produces a text field that can't be seen by the user. It is useful for passing state variable information from one invocation of the script to the next.

    Parameters:

  • The first argument is required and specifies the name of this field (-name).

  • The second argument is also required and specifies its value (-default). In the named parameter style of calling, you can provide a single value here or a reference to a whole list

    • Fetch the value of a hidden field this way:

         $hidden_value = param('hidden_name');

    Note, that just like all the other form elements, the value of a hidden field is "sticky". If you want to replace a hidden field with some other values after the script has been called once you'll have to do it manually:

         param('hidden_name','new','values','here');

    CREATING A CLICKABLE IMAGE BUTTON

         print image_button(-name=>'button_name',
                                -src=>'/source/URL',
                                -align=>'MIDDLE');

            -or-
         print image_button('button_name','/source/URL','MIDDLE');

    image_button() produces a clickable image. When it's clicked on the position of the click is returned to your script as "button_name.x" and "button_name.y", where "button_name" is the name you've assigned to it.

    Parameters:

  • The first argument (-name) is required and specifies the name of this field.

  • The second argument (-src) is also required and specifies the URL

  • The third option (-align, optional) is an alignment type, and may be TOP, BOTTOM or MIDDLE

    • Fetch the value of the button this way: $x = param('button_name.x'); $y = param('button_name.y');

    CREATING A JAVASCRIPT ACTION BUTTON

         print button(-name=>'button_name',
                          -value=>'user visible label',
                          -onClick=>"do_something()");

            -or-
         print button('button_name',"do_something()");

    button() produces a button that is compatible with Netscape 2.0's JavaScript. When it's pressed the fragment of JavaScript code pointed to by the -onClick parameter will be executed. On non-Netscape browsers this form element will probably not even display.

    HTTP COOKIES

    Netscape browsers versions 1.1 and higher, and all versions of Internet Explorer, support a so-called "cookie" designed to help maintain state within a browser session. CGI.pm has several methods that support cookies.

    A cookie is a name=value pair much like the named parameters in a CGI query string. CGI scripts create one or more cookies and send them to the browser in the HTTP header. The browser maintains a list of cookies that belong to a particular Web server, and returns them to the CGI script during subsequent interactions.

    In addition to the required name=value pair, each cookie has several optional attributes:

    1. an expiration time

      This is a time/date string (in a special GMT format) that indicates when a cookie expires. The cookie will be saved and returned to your script until this expiration date is reached if the user exits the browser and restarts it. If an expiration date isn't specified, the cookie will remain active until the user quits the browser.

    2. a domain

      This is a partial or complete domain name for which the cookie is valid. The browser will return the cookie to any host that matches the partial domain name. For example, if you specify a domain name of ".capricorn.com", then the browser will return the cookie to Web servers running on any of the machines "www.capricorn.com", "www2.capricorn.com", "feckless.capricorn.com", etc. Domain names must contain at least two periods to prevent attempts to match on top level domains like ".edu". If no domain is specified, then the browser will only return the cookie to servers on the host the cookie originated from.

    3. a path

      If you provide a cookie path attribute, the browser will check it against your script's URL before returning the cookie. For example, if you specify the path "/cgi-bin", then the cookie will be returned to each of the scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl", but not to the script "/cgi-private/site_admin.pl". By default, path is set to "/", which causes the cookie to be sent to any CGI script on your site.

    4. a "secure" flag

      If the "secure" attribute is set, the cookie will only be sent to your script if the CGI request is occurring on a secure channel, such as SSL.

    The interface to HTTP cookies is the cookie() method:

        $cookie = cookie(-name=>'sessionID',
                             -value=>'xyzzy',
                             -expires=>'+1h',
                             -path=>'/cgi-bin/database',
                             -domain=>'.capricorn.org',
                             -secure=>1);
    print header(-cookie=>$cookie);

    cookie() creates a new cookie. Its parameters include:

    -name

    The name of the cookie (required). This can be any string at all. Although browsers limit their cookie names to non-whitespace alphanumeric characters, CGI.pm removes this restriction by escaping and unescaping cookies behind the scenes.

    -value

    The value of the cookie. This can be any scalar value, array reference, or even associative array reference. For example, you can store an entire associative array into a cookie this way:

            $cookie=cookie(-name=>'family information',
                               -value=>\%childrens_ages);
    -path

    The optional partial path for which this cookie will be valid, as described above.

    -domain

    The optional partial domain for which this cookie will be valid, as described above.

    -expires

    The optional expiration date for this cookie. The format is as described in the section on the header() method:

            "+1h"  one hour from now
    -secure

    If set to true, this cookie will only be used within a secure SSL session.

    The cookie created by cookie() must be incorporated into the HTTP header within the string returned by the header() method:

            print header(-cookie=>$my_cookie);

    To create multiple cookies, give header() an array reference:

            $cookie1 = cookie(-name=>'riddle_name',
                                  -value=>"The Sphynx's Question");
        $cookie2 = cookie(-name=>'answers',
                                  -value=>\%answers);
        print header(-cookie=>[$cookie1,$cookie2]);

    To retrieve a cookie, request it by name by calling cookie() method without the -value parameter:

            use CGI;
        $query = new CGI;
        $riddle = cookie('riddle_name');
        %answers = cookie('answers');

    Cookies created with a single scalar value, such as the "riddle_name" cookie, will be returned in that form. Cookies with array and hash values can also be retrieved.

    The cookie and CGI namespaces are separate. If you have a parameter named 'answers' and a cookie named 'answers', the values retrieved by param() and cookie() are independent of each other. However, it's simple to turn a CGI parameter into a cookie, and vice-versa:

       # turn a CGI parameter into a cookie
   $c=cookie(-name=>'answers',-value=>[param('answers')]);
   # vice-versa
   param(-name=>'answers',-value=>[cookie('answers')]);

    If you call cookie() without any parameters, it will return a list of the names of all cookies passed to your script:

      @cookies = cookie();

    See the cookie.cgi example script for some ideas on how to use cookies effectively.

    WORKING WITH FRAMES

    It's possible for CGI.pm scripts to write into several browser panels and windows using the HTML 4 frame mechanism. There are three techniques for defining new frames programmatically:

    1. Create a <Frameset> document

      After writing out the HTTP header, instead of creating a standard HTML document using the start_html() call, create a <frameset> document that defines the frames on the page. Specify your script(s) (with appropriate parameters) as the SRC for each of the frames.

      There is no specific support for creating <frameset> sections in CGI.pm, but the HTML is very simple to write. See the frame documentation in Netscape's home pages for details

        http://home.netscape.com/assist/net_sites/frames.html
    2. Specify the destination for the document in the HTTP header

      You may provide a -target parameter to the header() method:

          print header(-target=>'ResultsWindow');

      This will tell the browser to load the output of your script into the frame named "ResultsWindow". If a frame of that name doesn't already exist, the browser will pop up a new window and load your script's document into that. There are a number of magic names that you can use for targets. See the frame documents on Netscape's home pages for details.

    3. Specify the destination for the document in the <form> tag

      You can specify the frame to load in the FORM tag itself. With CGI.pm it looks like this:

          print start_form(-target=>'ResultsWindow');

      When your script is reinvoked by the form, its output will be loaded into the frame named "ResultsWindow". If one doesn't already exist a new window will be created.

    The script "frameset.cgi" in the examples directory shows one way to create pages in which the fill-out form and the response live in side-by-side frames.

    SUPPORT FOR JAVASCRIPT

    Netscape versions 2.0 and higher incorporate an interpreted language called JavaScript. Internet Explorer, 3.0 and higher, supports a closely-related dialect called JScript. JavaScript isn't the same as Java, and certainly isn't at all the same as Perl, which is a great pity. JavaScript allows you to programmatically change the contents of fill-out forms, create new windows, and pop up dialog box from within Netscape itself. From the point of view of CGI scripting, JavaScript is quite useful for validating fill-out forms prior to submitting them.

    You'll need to know JavaScript in order to use it. There are many good sources in bookstores and on the web.

    The usual way to use JavaScript is to define a set of functions in a <SCRIPT> block inside the HTML header and then to register event handlers in the various elements of the page. Events include such things as the mouse passing over a form element, a button being clicked, the contents of a text field changing, or a form being submitted. When an event occurs that involves an element that has registered an event handler, its associated JavaScript code gets called.

    The elements that can register event handlers include the <BODY> of an HTML document, hypertext links, all the various elements of a fill-out form, and the form itself. There are a large number of events, and each applies only to the elements for which it is relevant. Here is a partial list:

    onLoad

    The browser is loading the current document. Valid in:

         + The HTML <BODY> section only.
    onUnload

    The browser is closing the current page or frame. Valid for:

         + The HTML <BODY> section only.
    onSubmit

    The user has pressed the submit button of a form. This event happens just before the form is submitted, and your function can return a value of false in order to abort the submission. Valid for:

         + Forms only.
    onClick

    The mouse has clicked on an item in a fill-out form. Valid for:

         + Buttons (including submit, reset, and image buttons)
     + Checkboxes
     + Radio buttons
    onChange

    The user has changed the contents of a field. Valid for:

         + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists
    onFocus

    The user has selected a field to work with. Valid for:

         + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists
    onBlur

    The user has deselected a field (gone to work somewhere else). Valid for:

         + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists
    onSelect

    The user has changed the part of a text field that is selected. Valid for:

         + Text fields
     + Text areas
     + Password fields
     + File fields
    onMouseOver

    The mouse has moved over an element.

         + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists
    onMouseOut

    The mouse has moved off an element.

         + Text fields
     + Text areas
     + Password fields
     + File fields
     + Popup Menus
     + Scrolling lists

    In order to register a JavaScript event handler with an HTML element, just use the event name as a parameter when you call the corresponding CGI method. For example, to have your validateAge() JavaScript code executed every time the textfield named "age" changes, generate the field like this:

     print textfield(-name=>'age',-onChange=>"validateAge(this)");

    This example assumes that you've already declared the validateAge() function by incorporating it into a <SCRIPT> block. The CGI.pm start_html() method provides a convenient way to create this section.

    Similarly, you can create a form that checks itself over for consistency and alerts the user if some essential value is missing by creating it this way: print startform(-onSubmit=>"validateMe(this)");

    See the javascript.cgi script for a demonstration of how this all works.

    LIMITED SUPPORT FOR CASCADING STYLE SHEETS

    CGI.pm has limited support for HTML3's cascading style sheets (css). To incorporate a stylesheet into your document, pass the start_html() method a -style parameter. The value of this parameter may be a scalar, in which case it is treated as the source URL for the stylesheet, or it may be a hash reference. In the latter case you should provide the hash with one or more of -src or -code. -src points to a URL where an externally-defined stylesheet can be found. -code points to a scalar value to be incorporated into a <style> section. Style definitions in -code override similarly-named ones in -src, hence the name "cascading."

    You may also specify the type of the stylesheet by adding the optional -type parameter to the hash pointed to by -style. If not specified, the style defaults to 'text/css'.

    To refer to a style within the body of your document, add the -class parameter to any HTML element:

        print h1({-class=>'Fancy'},'Welcome to the Party');

    Or define styles on the fly with the -style parameter:

        print h1({-style=>'Color: red;'},'Welcome to Hell');

    You may also use the new span() element to apply a style to a section of text:

        print span({-style=>'Color: red;'},
               h1('Welcome to Hell'),
               "Where did that handbasket get to?"
               );

    Note that you must import the ":html3" definitions to have the span() method available. Here's a quick and dirty example of using CSS's. See the CSS specification at http://www.w3.org/pub/WWW/TR/Wd-css-1.html for more information.

        use CGI qw/:standard :html3/;

        #here's a stylesheet incorporated directly into the page
    $newStyle=<<END;
    <!--
    P.Tip {
        margin-right: 50pt;
        margin-left: 50pt;
        color: red;
    }
    P.Alert {
        font-size: 30pt;
        font-family: sans-serif;
      color: red;
    }
    -->
    END
    print header();
    print start_html( -title=>'CGI with Style',
                      -style=>{-src=>'http://www.capricorn.com/style/st1.css',
                               -code=>$newStyle}
                     );
    print h1('CGI with Style'),
          p({-class=>'Tip'},
            "Better read the cascading style sheet spec before playing with this!"),
          span({-style=>'color: magenta'},
               "Look Mom, no hands!",
               p(),
               "Whooo wee!"
               );
    print end_html;

    Pass an array reference to -code or -src in order to incorporate multiple stylesheets into your document.

    Should you wish to incorporate a verbatim stylesheet that includes arbitrary formatting in the header, you may pass a -verbatim tag to the -style hash, as follows:

    print start_html (-STYLE => {-verbatim => '@import url("/server-common/css/'.$cssFile.'");', -src => '/server-common/css/core.css'}); </blockquote></pre>

    This will generate an HTML header that contains this:

     <link rel="stylesheet" type="text/css"  href="/server-common/css/core.css">
   <style type="text/css">
   @import url("/server-common/css/main.css");
   </style>

    Any additional arguments passed in the -style value will be incorporated into the <link> tag. For example:

     start_html(-style=>{-src=>['/styles/print.css','/styles/layout.css'],
                          -media => 'all'});

    This will give:

     <link rel="stylesheet" type="text/css" href="/styles/print.css" media="all"/>
 <link rel="stylesheet" type="text/css" href="/styles/layout.css" media="all"/>

    <p>

    To make more complicated <link> tags, use the Link() function and pass it to start_html() in the -head argument, as in:

      @h = (Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/ss.css',-media=>'all'}),
        Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/fred.css',-media=>'paper'}));
  print start_html({-head=>\@h})

    DEBUGGING

    If you are running the script from the command line or in the perl debugger, you can pass the script a list of keywords or parameter=value pairs on the command line or from standard input (you don't have to worry about tricking your script into reading from environment variables). You can pass keywords like this:

        your_script.pl keyword1 keyword2 keyword3

    or this:

       your_script.pl keyword1+keyword2+keyword3

    or this:

        your_script.pl name1=value1 name2=value2

    or this:

        your_script.pl name1=value1&name2=value2

    To turn off this feature, use the -no_debug pragma.

    To test the POST method, you may enable full debugging with the -debug pragma. This will allow you to feed newline-delimited name=value pairs to the script on standard input.

    When debugging, you can use quotes and backslashes to escape characters in the familiar shell manner, letting you place spaces and other funny characters in your parameter=value pairs:

       your_script.pl "name1='I am a long value'" "name2=two\ words"

    Finally, you can set the path info for the script by prefixing the first name/value parameter with the path followed by a question mark (?):

        your_script.pl /your/path/here?name1=value1&name2=value2

    DUMPING OUT ALL THE NAME/VALUE PAIRS

    The Dump() method produces a string consisting of all the query's name/value pairs formatted nicely as a nested list. This is useful for debugging purposes:

        print Dump

    Produces something that looks like:

        <ul>
    <li>name1
        <ul>
        <li>value1
        <li>value2
        </ul>
    <li>name2
        <ul>
        <li>value1
        </ul>
    </ul>

    As a shortcut, you can interpolate the entire CGI object into a string and it will be replaced with the a nice HTML dump shown above:

        $query=new CGI;
    print "<h2>Current Values</h2> $query\n";

    FETCHING ENVIRONMENT VARIABLES

    Some of the more useful environment variables can be fetched through this interface. The methods are as follows:

    Accept()

    Return a list of MIME types that the remote browser accepts. If you give this method a single argument corresponding to a MIME type, as in Accept('text/html'), it will return a floating point value corresponding to the browser's preference for this type from 0.0 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept list are handled correctly.

    Note that the capitalization changed between version 2.43 and 2.44 in order to avoid conflict with Perl's accept() function.

    raw_cookie()

    Returns the HTTP_COOKIE variable, an HTTP extension implemented by Netscape browsers version 1.1 and higher, and all versions of Internet Explorer. Cookies have a special format, and this method call just returns the raw form (?cookie dough). See cookie() for ways of setting and retrieving cooked cookies.

    Called with no parameters, raw_cookie() returns the packed cookie structure. You can separate it into individual cookies by splitting on the character sequence "; ". Called with the name of a cookie, retrieves the unescaped form of the cookie. You can use the regular cookie() method to get the names, or use the raw_fetch() method from the CGI::Cookie module.

    user_agent()

    Returns the HTTP_USER_AGENT variable. If you give this method a single argument, it will attempt to pattern match on it, allowing you to do something like user_agent(netscape);

    path_info()

    Returns additional path information from the script URL. E.G. fetching /cgi-bin/your_script/additional/stuff will result in path_info() returning "/additional/stuff".

    NOTE: The Microsoft Internet Information Server is broken with respect to additional path information. If you use the Perl DLL library, the IIS server will attempt to execute the additional path information as a Perl script. If you use the ordinary file associations mapping, the path information will be present in the environment, but incorrect. The best thing to do is to avoid using additional path information in CGI scripts destined for use with IIS.

    path_translated()

    As per path_info() but returns the additional path information translated into a physical path, e.g. "/usr/local/etc/httpd/htdocs/additional/stuff".

    The Microsoft IIS is broken with respect to the translated path as well.

    remote_host()

    Returns either the remote host name or IP address. if the former is unavailable.

    script_name() Return the script name as a partial URL, for self-refering scripts.
    referer()

    Return the URL of the page the browser was viewing prior to fetching your script. Not available for all browsers.

    auth_type ()

    Return the authorization/verification method in use for this script, if any.

    server_name ()

    Returns the name of the server, usually the machine's host name.

    virtual_host ()

    When using virtual hosts, returns the name of the host that the browser attempted to contact

    server_port ()

    Return the port that the server is listening on.

    virtual_port ()

    Like server_port() except that it takes virtual hosts into account. Use this when running with virtual hosts.

    server_software ()

    Returns the server software and version number.

    remote_user ()

    Return the authorization/verification name used for user verification, if this script is protected.

    user_name ()

    Attempt to obtain the remote user's name, using a variety of different techniques. This only works with older browsers such as Mosaic. Newer browsers do not report the user name for privacy reasons!

    request_method()

    Returns the method used to access your script, usually one of 'POST', 'GET' or 'HEAD'.

    content_type()

    Returns the content_type of data submitted in a POST, generally multipart/form-data or application/x-www-form-urlencoded

    http()

    Called with no arguments returns the list of HTTP environment variables, including such things as HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the like-named HTTP header fields in the request. Called with the name of an HTTP header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.

    For example, all three of these examples are equivalent:

       $requested_language = http('Accept-language');
   $requested_language = http('Accept_language');
   $requested_language = http('HTTP_ACCEPT_LANGUAGE');
    https()

    The same as http(), but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.

    USING NPH SCRIPTS

    NPH, or "no-parsed-header", scripts bypass the server completely by sending the complete HTTP header directly to the browser. This has slight performance benefits, but is of most use for taking advantage of HTTP extensions that are not directly supported by your server, such as server push and PICS headers.

    Servers use a variety of conventions for designating CGI scripts as NPH. Many Unix servers look at the beginning of the script's name for the prefix "nph-". The Macintosh WebSTAR server and Microsoft's Internet Information Server, in contrast, try to decide whether a program is an NPH script by examining the first line of script output.

    CGI.pm supports NPH scripts with a special NPH mode. When in this mode, CGI.pm will output the necessary extra header information when the header() and redirect() methods are called.

    The Microsoft Internet Information Server requires NPH mode. As of version 2.30, CGI.pm will automatically detect when the script is running under IIS and put itself into this mode. You do not need to do this manually, although it won't hurt anything if you do. However, note that if you have applied Service Pack 6, much of the functionality of NPH scripts, including the ability to redirect while setting a cookie, b<do not work at all> on IIS without a special patch from Microsoft. See http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP: Non-Parsed Headers Stripped From CGI Applications That Have nph- Prefix in Name.

    In the use statement

    Simply add the "-nph" pragmato the list of symbols to be imported into your script:

          use CGI qw(:standard -nph)
    By calling the nph() method:

    Call nph() with a non-zero parameter at any point after using CGI.pm in your program.

          CGI->nph(1)
    By using -nph parameters

    in the header() and redirect() statements:

          print header(-nph=>1);

    Server Push

    CGI.pm provides four simple functions for producing multipart documents of the type needed to implement server push. These functions were graciously provided by Ed Jordan <ed@fidalgo.net>. To import these into your namespace, you must import the ":push" set. You are also advised to put the script into NPH mode and to set $| to 1 to avoid buffering problems.

    Here is a simple script that demonstrates server push:

      #!/usr/local/bin/perl
  use CGI qw/:push -nph/;
  $| = 1;
  print multipart_init(-boundary=>'----here we go!');
  foreach (0 .. 4) {
      print multipart_start(-type=>'text/plain'),
            "The current time is ",scalar(localtime),"\n";
      if ($_ < 4) {
              print multipart_end;
      } else {
              print multipart_final;
      }
      sleep 1;
  }

    This script initializes server push by calling multipart_init(). It then enters a loop in which it begins a new multipart section by calling multipart_start(), prints the current local time, and ends a multipart section with multipart_end(). It then sleeps a second, and begins again. On the final iteration, it ends the multipart section with multipart_final() rather than with multipart_end().

    multipart_init()
      multipart_init(-boundary=>$boundary);

    Initialize the multipart system. The -boundary argument specifies what MIME boundary string to use to separate parts of the document. If not provided, CGI.pm chooses a reasonable boundary for you.

    multipart_start()
      multipart_start(-type=>$type)

    Start a new part of the multipart document using the specified MIME type. If not specified, text/html is assumed.

    multipart_end()
      multipart_end()

    End a part. You must remember to call multipart_end() once for each multipart_start(), except at the end of the last part of the multipart document when multipart_final() should be called instead of multipart_end().

    multipart_final()
      multipart_final()

    End all parts. You should call multipart_final() rather than multipart_end() at the end of the last part of the multipart document.

    Users interested in server push applications should also have a look at the CGI::Push module.

    Only Netscape Navigator supports server push. Internet Explorer browsers do not.

    Avoiding Denial of Service Attacks

    A potential problem with CGI.pm is that, by default, it attempts to process form POSTings no matter how large they are. A wily hacker could attack your site by sending a CGI script a huge POST of many megabytes. CGI.pm will attempt to read the entire POST into a variable, growing hugely in size until it runs out of memory. While the script attempts to allocate the memory the system may slow down dramatically. This is a form of denial of service attack.

    Another possible attack is for the remote user to force CGI.pm to accept a huge file upload. CGI.pm will accept the upload and store it in a temporary directory even if your script doesn't expect to receive an uploaded file. CGI.pm will delete the file automatically when it terminates, but in the meantime the remote user may have filled up the server's disk space, causing problems for other programs.

    The best way to avoid denial of service attacks is to limit the amount of memory, CPU time and disk space that CGI scripts can use. Some Web servers come with built-in facilities to accomplish this. In other cases, you can use the shell limit or ulimit commands to put ceilings on CGI resource usage.

    CGI.pm also has some simple built-in protections against denial of service attacks, but you must activate them before you can use them. These take the form of two global variables in the CGI name space:

    $CGI::POST_MAX

    If set to a non-negative integer, this variable puts a ceiling on the size of POSTings, in bytes. If CGI.pm detects a POST that is greater than the ceiling, it will immediately exit with an error message. This value will affect both ordinary POSTs and multipart POSTs, meaning that it limits the maximum size of file uploads as well. You should set this to a reasonably high value, such as 1 megabyte.

    $CGI::DISABLE_UPLOADS

    If set to a non-zero value, this will disable file uploads completely. Other fill-out form values will work as usual.

    You can use these variables in either of two ways.

    1. 1. On a script-by-script basis

      Set the variable at the top of the script, right after the "use" statement:

          use CGI qw/:standard/;
    use CGI::Carp 'fatalsToBrowser';
    $CGI::POST_MAX=1024 * 100;  # max 100K posts
    $CGI::DISABLE_UPLOADS = 1;  # no uploads
    2. 2. Globally for all scripts

      Open up CGI.pm, find the definitions for $POST_MAX and $DISABLE_UPLOADS, and set them to the desired values. You'll find them towards the top of the file in a subroutine named initialize_globals().

    An attempt to send a POST larger than $POST_MAX bytes will cause param() to return an empty CGI parameter list. You can test for this event by checking cgi_error(), either after you create the CGI object or, if you are using the function-oriented interface, call <param()> for the first time. If the POST was intercepted, then cgi_error() will return the message "413 POST too large".

    This error message is actually defined by the HTTP protocol, and is designed to be returned to the browser as the CGI script's status code. For example:

       $uploaded_file = param('upload');
   if (!$uploaded_file && cgi_error()) {
      print header(-status=>cgi_error());
      exit 0;
   }

    However it isn't clear that any browser currently knows what to do with this status code. It might be better just to create an HTML page that warns the user of the problem.

    COMPATIBILITY WITH CGI-LIB.PL

    To make it easier to port existing programs that use cgi-lib.pl the compatibility routine "ReadParse" is provided. Porting is simple:

    OLD VERSION
    require "cgi-lib.pl";
    &ReadParse;
    print "The value of the antique is $in{antique}.\n";

    NEW VERSION
    use CGI;
    CGI::ReadParse();
    print "The value of the antique is $in{antique}.\n";

    CGI.pm's ReadParse() routine creates a tied variable named %in, which can be accessed to obtain the query variables. Like ReadParse, you can also provide your own variable. Infrequently used features of ReadParse, such as the creation of @in and $in variables, are not supported.

    Once you use ReadParse, you can retrieve the query object itself this way:

        $q = $in{CGI};
    print textfield(-name=>'wow',
                        -value=>'does this really work?');

    This allows you to start using the more interesting features of CGI.pm without rewriting your old scripts from scratch.

    AUTHOR INFORMATION

    Copyright 1995-1998, Lincoln D. Stein. All rights reserved.

    This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

    Address bug reports and comments to: lstein@cshl.org. When sending bug reports, please provide the version of CGI.pm, the version of Perl, the name and version of your Web server, and the name and version of the operating system you are using. If the problem is even remotely browser dependent, please provide information about the affected browers as well.

    CREDITS

    Thanks very much to:

    Matt Heffron (heffron@falstaff.css.beckman.com)
    James Taylor (james.taylor@srs.gov)
    Scott Anguish <sanguish@digifix.com>
    Mike Jewell (mlj3u@virginia.edu)
    Timothy Shimmin (tes@kbs.citri.edu.au)
    Joergen Haegg (jh@axis.se)
    Laurent Delfosse (delfosse@delfosse.com)
    Richard Resnick (applepi1@aol.com)
    Craig Bishop (csb@barwonwater.vic.gov.au)
    Tony Curtis (tc@vcpc.univie.ac.at)
    Tim Bunce (Tim.Bunce@ig.co.uk)
    Tom Christiansen (tchrist@convex.com)
    Andreas Koenig (k@franz.ww.TU-Berlin.DE)
    Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)
    Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)
    Stephen Dahmen (joyfire@inxpress.net)
    Ed Jordan (ed@fidalgo.net)
    David Alan Pisoni (david@cnation.com)
    Doug MacEachern (dougm@opengroup.org)
    Robin Houston (robin@oneworld.org)
    ...and many many more...

    for suggestions and bug fixes.

    A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT

            #!/usr/local/bin/perl

            use CGI ':standard';

            print header;
        print start_html("Example CGI.pm Form");
        print "<h1> Example CGI.pm Form</h1>\n";
        print_prompt();
        do_work();
        print_tail();
        print end_html;

            sub print_prompt {
           print start_form;
           print "<em>What's your name?</em><br>";
           print textfield('name');
           print checkbox('Not my real name');

               print "<p><em>Where can you find English Sparrows?</em><br>";
           print checkbox_group(
                                 -name=>'Sparrow locations',
                                 -values=>[England,France,Spain,Asia,Hoboken],
                                 -linebreak=>'yes',
                                 -defaults=>[England,Asia]);

               print "<p><em>How far can they fly?</em><br>",
                radio_group(
                        -name=>'how far',
                        -values=>['10 ft','1 mile','10 miles','real far'],
                        -default=>'1 mile');

               print "<p><em>What's your favorite color?</em>  ";
           print popup_menu(-name=>'Color',
                                    -values=>['black','brown','red','yellow'],
                                    -default=>'red');

               print hidden('Reference','Monty Python and the Holy Grail');

               print "<p><em>What have you got there?</em><br>";
           print scrolling_list(
                         -name=>'possessions',
                         -values=>['A Coconut','A Grail','An Icon',
                                   'A Sword','A Ticket'],
                         -size=>5,
                         -multiple=>'true');

               print "<p><em>Any parting comments?</em><br>";
           print textarea(-name=>'Comments',
                                  -rows=>10,
                                  -columns=>50);

               print "<p>",reset;
           print submit('Action','Shout');
           print submit('Action','Scream');
           print endform;
           print "<hr>\n";
                   }

            sub do_work {
           my(@values,$key);

               print "<h2>Here are the current settings in this form</h2>";

               foreach $key (param) {
              print "<strong>$key</strong> -> ";
              @values = param($key);
              print join(", ",@values),"<br>\n";
                     }
                   }

            sub print_tail {
           print <<END;
        <hr>
        <address>Lincoln D. Stein</address><br>
        <a href="/">Home Page</a>
        END
        }

    BUGS

    Please report them.

    SEE ALSO

    the CGI::Carp manpage, the CGI::Fast manpage, the CGI::Pretty manpage


CGI::Apache - Backward compatibility module for CGI.pm

  • ABSTRACT
  • DESCRIPTION
  • AUTHOR INFORMATION
  • BUGS
  • SEE ALSO

NAME

CGI::Apache - Backward compatibility module for CGI.pm

SYNOPSIS

Do not use this module. It is deprecated.

ABSTRACT

DESCRIPTION

AUTHOR INFORMATION

BUGS

SEE ALSO


B<CGI::Carp> - CGI routines for writing to the HTTPD error log

  • REDIRECTING ERROR MESSAGES
  • MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW
    • Changing the default message
  • MAKING WARNINGS APPEAR AS HTML COMMENTS
  • OVERRIDING THE NAME OF THE PROGRAM
  • AUTHORS
  • SEE ALSO

NAME

CGI::Carp - CGI routines for writing to the HTTPD (or other) error log

SYNOPSIS

    use CGI::Carp;

    croak "We're outta here!";
    confess "It was my fault: $!";
    carp "It was your fault!";
    warn "I'm confused";
    die  "I'm dying.\n";

    use CGI::Carp qw(cluck);
    cluck "I wouldn't do that if I were you";

    use CGI::Carp qw(fatalsToBrowser);
    die "Fatal error messages are now sent to browser";

DESCRIPTION

CGI scripts have a nasty habit of leaving warning messages in the error logs that are neither time stamped nor fully identified. Tracking down the script that caused the error is a pain. This fixes that. Replace the usual

    use Carp;

with

    use CGI::Carp

And the standard warn(), die (), croak(), confess() and carp() calls will automagically be replaced with functions that write out nicely time-stamped messages to the HTTP server error log.

For example:

   [Fri Nov 17 21:40:43 1995] test.pl: I'm confused at test.pl line 3.
   [Fri Nov 17 21:40:43 1995] test.pl: Got an error message: Permission denied.
   [Fri Nov 17 21:40:43 1995] test.pl: I'm dying.

REDIRECTING ERROR MESSAGES

By default, error messages are sent to STDERR. Most HTTPD servers direct STDERR to the server's error log. Some applications may wish to keep private error logs, distinct from the server's error log, or they may wish to direct error messages to STDOUT so that the browser will receive them.

The carpout() function is provided for this purpose. Since carpout() is not exported by default, you must import it explicitly by saying

   use CGI::Carp qw(carpout);

The carpout() function requires one argument, which should be a reference to an open filehandle for writing errors. It should be called in a BEGIN block at the top of the CGI application so that compiler errors will be caught. Example:

   BEGIN {
     use CGI::Carp qw(carpout);
     open(LOG, ">>/usr/local/cgi-logs/mycgi-log") or
       die("Unable to open mycgi-log: $!\n");
     carpout(LOG);
   }

carpout() does not handle file locking on the log for you at this point.

The real STDERR is not closed -- it is moved to CGI::Carp::SAVEERR. Some servers, when dealing with CGI scripts, close their connection to the browser when the script closes STDOUT and STDERR. CGI::Carp::SAVEERR is there to prevent this from happening prematurely.

You can pass filehandles to carpout() in a variety of ways. The "correct" way according to Tom Christiansen is to pass a reference to a filehandle GLOB:

    carpout(\*LOG);

This looks weird to mere mortals however, so the following syntaxes are accepted as well:

    carpout(LOG);
    carpout(main::LOG);
    carpout(main'LOG);
    carpout(\LOG);
    carpout(\'main::LOG');

    ... and so on

FileHandle and other objects work as well.

Use of carpout() is not great for performance, so it is recommended for debugging purposes or for moderate-use applications. A future version of this module may delay redirecting STDERR until one of the CGI::Carp methods is called to prevent the performance hit.

MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW

If you want to send fatal (die, confess) errors to the browser, ask to import the special "fatalsToBrowser" subroutine:

    use CGI::Carp qw(fatalsToBrowser);
    die "Bad error here";

Fatal errors will now be echoed to the browser as well as to the log. CGI::Carp arranges to send a minimal HTTP header to the browser so that even errors that occur in the early compile phase will be seen. Nonfatal errors will still be directed to the log file only (unless redirected with carpout).

Note that fatalsToBrowser does not work with mod_perl version 2.0 and higher.

Changing the default message

By default, the software error message is followed by a note to contact the Webmaster by e-mail with the time and date of the error. If this message is not to your liking, you can change it using the set_message() routine. This is not imported by default; you should import it on the use() line:

    use CGI::Carp qw(fatalsToBrowser set_message);
    set_message("It's not a bug, it's a feature!");

You may also pass in a code reference in order to create a custom error message. At run time, your code will be called with the text of the error message that caused the script to die. Example:

    use CGI::Carp qw(fatalsToBrowser set_message);
    BEGIN {
       sub handle_errors {
          my $msg = shift;
          print "<h1>Oh gosh</h1>";
          print "<p>Got an error: $msg</p>";
      }
      set_message(\&handle_errors);
    }

In order to correctly intercept compile-time errors, you should call set_message() from within a BEGIN{} block.

MAKING WARNINGS APPEAR AS HTML COMMENTS

It is now also possible to make non-fatal errors appear as HTML comments embedded in the output of your program. To enable this feature, export the new "warningsToBrowser" subroutine. Since sending warnings to the browser before the HTTP headers have been sent would cause an error, any warnings are stored in an internal buffer until you call the warningsToBrowser() subroutine with a true argument:

    use CGI::Carp qw(fatalsToBrowser warningsToBrowser);
    use CGI qw(:standard);
    print header();
    warningsToBrowser(1);

You may also give a false argument to warningsToBrowser() to prevent warnings from being sent to the browser while you are printing some content where HTML comments are not allowed:

    warningsToBrowser(0);    # disable warnings
    print "<script type=\"text/javascript\"><!--\n";
    print_some_javascript_code();
    print "//--></script>\n";
    warningsToBrowser(1);    # re-enable warnings

Note: In this respect warningsToBrowser() differs fundamentally from fatalsToBrowser(), which you should never call yourself!

OVERRIDING THE NAME OF THE PROGRAM

CGI::Carp includes the name of the program that generated the error or warning in the messages written to the log and the browser window. Sometimes, Perl can get confused about what the actual name of the executed program was. In these cases, you can override the program name that CGI::Carp will use for all messages.

The quick way to do that is to tell CGI::Carp the name of the program in its use statement. You can do that by adding "name=cgi_carp_log_name" to your "use" statement. For example:

    use CGI::Carp qw(name=cgi_carp_log_name);

. If you want to change the program name partway through the program, you can use the set_progname() function instead. It is not exported by default, you must import it explicitly by saying

    use CGI::Carp qw(set_progname);

Once you've done that, you can change the logged name of the program at any time by calling

    set_progname(new_program_name);

You can set the program back to the default by calling

    set_progname(undef);

Note that this override doesn't happen until after the program has compiled, so any compile-time errors will still show up with the non-overridden program name

=head1 CHANGE LOG

1.29 Patch from Peter Whaite to fix the unfixable problem of CGI::Carp not behaving correctly in an eval() context.

1.05 carpout() added and minor corrections by Marc Hedlund <hedlund@best.com> on 11/26/95.

1.06 fatalsToBrowser() no longer aborts for fatal errors within eval() statements.

1.08 set_message() added and carpout() expanded to allow for FileHandle objects.

1.09 set_message() now allows users to pass a code REFERENCE for really custom error messages. croak and carp are now exported by default. Thanks to Gunther Birznieks for the patches.

1.10 Patch from Chris Dean (ctdean@cogit.com) to allow module to run correctly under mod_perl.

1.11 Changed order of &gt; and &lt; escapes.

1.12 Changed die() on line 217 to CORE::die to avoid -w warning.

1.13 Added cluck() to make the module orthogonal with Carp. More mod_perl related fixes.

1.20 Patch from Ilmari Karonen (perl@itz.pp.sci.fi) Added warningsToBrowser(). Replaced <CODE> tags with <PRE> in fatalsToBrowser() output.

1.23 ineval() now checks both $^S and inspects the message for the "eval" pattern (hack alert!) in order to accomodate various combinations of Perl and mod_perl.

1.24 Patch from Scott Gifford (sgifford@suspectclass.com) Add support for overriding program name.

1.26 Replaced CORE::GLOBAL::die with the evil $SIG{__DIE__} because the former isn't working in some people's hands. There is no such thing as reliable exception handling in Perl.

1.27 Replaced tell STDOUT with bytes=tell STDOUT.

AUTHORS

Copyright 1995-2002, Lincoln D. Stein. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org

SEE ALSO

Carp, CGI::Base, CGI::BasePlus, CGI::Request, CGI::MiniSvr, CGI::Form,
CGI::Response
    if (defined($CGI::Carp::PROGNAME))
    {
      $file = $CGI::Carp::PROGNAME;
    }


CGI::Cookie - Interface to Netscape Cookies

  • USING CGI::Cookie
    • Creating New Cookies
    • Sending the Cookie to the Browser
    • Recovering Previous Cookies
    • Manipulating Cookies
  • AUTHOR INFORMATION
  • BUGS
  • SEE ALSO

NAME

CGI::Cookie - Interface to Netscape Cookies

SYNOPSIS

    use CGI qw/:standard/;
    use CGI::Cookie;

    # Create new cookies and send them
    $cookie1 = new CGI::Cookie(-name=>'ID',-value=>123456);
    $cookie2 = new CGI::Cookie(-name=>'preferences',
                               -value=>{ font => Helvetica,
                                         size => 12 }
                               );
    print header(-cookie=>[$cookie1,$cookie2]);

    # fetch existing cookies
    %cookies = fetch CGI::Cookie;
    $id = $cookies{'ID'}->value;

    # create cookies returned from an external source
    %cookies = parse CGI::Cookie($ENV{COOKIE});

DESCRIPTION

CGI::Cookie is an interface to Netscape (HTTP/1.1) cookies, an innovation that allows Web servers to store persistent information on the browser's side of the connection. Although CGI::Cookie is intended to be used in conjunction with CGI.pm (and is in fact used by it internally), you can use this module independently.

For full information on cookies see

        http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt

USING CGI::Cookie

CGI::Cookie is object oriented. Each cookie object has a name and a value. The name is any scalar value. The value is any scalar or array value (associative arrays are also allowed). Cookies also have several optional attributes, including:

  1. 1. expiration date

    The expiration date tells the browser how long to hang on to the cookie. If the cookie specifies an expiration date in the future, the browser will store the cookie information in a disk file and return it to the server every time the user reconnects (until the expiration date is reached). If the cookie species an expiration date in the past, the browser will remove the cookie from the disk file. If the expiration date is not specified, the cookie will persist only until the user quits the browser.

  2. 2. domain

    This is a partial or complete domain name for which the cookie is valid. The browser will return the cookie to any host that matches the partial domain name. For example, if you specify a domain name of ".capricorn.com", then Netscape will return the cookie to Web servers running on any of the machines "www.capricorn.com", "ftp.capricorn.com", "feckless.capricorn.com", etc. Domain names must contain at least two periods to prevent attempts to match on top level domains like ".edu". If no domain is specified, then the browser will only return the cookie to servers on the host the cookie originated from.

  3. 3. path

    If you provide a cookie path attribute, the browser will check it against your script's URL before returning the cookie. For example, if you specify the path "/cgi-bin", then the cookie will be returned to each of the scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl", but not to the script "/cgi-private/site_admin.pl". By default, the path is set to "/", so that all scripts at your site will receive the cookie.

  4. 4. secure flag

    If the "secure" attribute is set, the cookie will only be sent to your script if the CGI request is occurring on a secure channel, such as SSL.

Creating New Cookies

        my $c = new CGI::Cookie(-name    =>  'foo',
                             -value   =>  'bar',
                             -expires =>  '+3M',
                             -domain  =>  '.capricorn.com',
                             -path    =>  '/cgi-bin/database',
                             -secure  =>  1
                            );

Create cookies from scratch with the new method. The -name and -value parameters are required. The name must be a scalar value. The value can be a scalar, an array reference, or a hash reference. (At some point in the future cookies will support one of the Perl object serialization protocols for full generality).

-expires accepts any of the relative or absolute date formats recognized by CGI.pm, for example "+3M" for three months in the future. See CGI.pm's documentation for details.

-domain points to a domain name or to a fully qualified host name. If not specified, the cookie will be returned only to the Web server that created it.

-path points to a partial URL on the current server. The cookie will be returned to all URLs beginning with the specified path. If not specified, it defaults to '/', which returns the cookie to all pages at your site.

-secure if set to a true value instructs the browser to return the cookie only when a cryptographic protocol is in use.

For compatibility with Apache::Cookie, you may optionally pass in a mod_perl request object as the first argument to new(). It will simply be ignored:

  my $c = new CGI::Cookie($r,
                          -name    =>  'foo',
                          -value   =>  ['bar','baz']);

Sending the Cookie to the Browser

The simplest way to send a cookie to the browser is by calling the bake() method:

  $c->bake;

Under mod_perl, pass in an Apache request object:

  $c->bake($r);

If you want to set the cookie yourself, Within a CGI script you can send a cookie to the browser by creating one or more Set-Cookie: fields in the HTTP header. Here is a typical sequence:

  my $c = new CGI::Cookie(-name    =>  'foo',
                          -value   =>  ['bar','baz'],
                          -expires =>  '+3M');

  print "Set-Cookie: $c\n";
  print "Content-Type: text/html\n\n";

To send more than one cookie, create several Set-Cookie: fields.

If you are using CGI.pm, you send cookies by providing a -cookie argument to the header() method:

  print header(-cookie=>$c);

Mod_perl users can set cookies using the request object's header_out() method:

  $r->headers_out->set('Set-Cookie' => $c);

Internally, Cookie overloads the "" operator to call its as_string() method when incorporated into the HTTP header. as_string() turns the Cookie's internal representation into an RFC-compliant text representation. You may call as_string() yourself if you prefer:

  print "Set-Cookie: ",$c->as_string,"\n";

Recovering Previous Cookies

        %cookies = fetch CGI::Cookie;

fetch returns an associative array consisting of all cookies returned by the browser. The keys of the array are the cookie names. You can iterate through the cookies this way:

        %cookies = fetch CGI::Cookie;
        foreach (keys %cookies) {
           do_something($cookies{$_});
        }

In a scalar context, fetch() returns a hash reference, which may be more efficient if you are manipulating multiple cookies.

CGI.pm uses the URL escaping methods to save and restore reserved characters in its cookies. If you are trying to retrieve a cookie set by a foreign server, this escaping method may trip you up. Use raw_fetch() instead, which has the same semantics as fetch(), but performs no unescaping.

You may also retrieve cookies that were stored in some external form using the parse() class method:

       $COOKIES = `cat /usr/tmp/Cookie_stash`;
       %cookies = parse CGI::Cookie($COOKIES);

If you are in a mod_perl environment, you can save some overhead by passing the request object to fetch() like this:

   CGI::Cookie->fetch($r);

Manipulating Cookies

Cookie objects have a series of accessor methods to get and set cookie attributes. Each accessor has a similar syntax. Called without arguments, the accessor returns the current value of the attribute. Called with an argument, the accessor changes the attribute and returns its new value.

name()

Get or set the cookie's name. Example:

        $name = $c->name;
        $new_name = $c->name('fred');
value()

Get or set the cookie's value. Example:

        $value = $c->value;
        @new_value = $c->value(['a','b','c','d']);

value() is context sensitive. In a list context it will return the current value of the cookie as an array. In a scalar context it will return the first value of a multivalued cookie.

domain()

Get or set the cookie's domain.

path()

Get or set the cookie's path.

expires()

Get or set the cookie's expiration time.

AUTHOR INFORMATION

Copyright 1997-1998, Lincoln D. Stein. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org

BUGS

This section intentionally left blank.

SEE ALSO

the CGI::Carp manpage, the CGI manpage


CGI::Fast - CGI Interface for Fast CGI

  • OTHER PIECES OF THE PUZZLE
  • WRITING FASTCGI PERL SCRIPTS
  • INSTALLING FASTCGI SCRIPTS
  • USING FASTCGI SCRIPTS AS CGI SCRIPTS
  • EXTERNAL FASTCGI SERVER INVOCATION
  • CAVEATS
  • AUTHOR INFORMATION
  • BUGS
  • SEE ALSO

NAME

CGI::Fast - CGI Interface for Fast CGI

SYNOPSIS

    use CGI::Fast qw(:standard);
    $COUNTER = 0;
    while (new CGI::Fast) {
        print header;
        print start_html("Fast CGI Rocks");
        print
            h1("Fast CGI Rocks"),
            "Invocation number ",b($COUNTER++),
            " PID ",b($$),".",
            hr;
        print end_html;
    }

DESCRIPTION

CGI::Fast is a subclass of the CGI object created by CGI.pm. It is specialized to work well with the Open Market FastCGI standard, which greatly speeds up CGI scripts by turning them into persistently running server processes. Scripts that perform time-consuming initialization processes, such as loading large modules or opening persistent database connections, will see large performance improvements.

OTHER PIECES OF THE PUZZLE

In order to use CGI::Fast you'll need a FastCGI-enabled Web server. See http://www.fastcgi.com/ for details.

WRITING FASTCGI PERL SCRIPTS

FastCGI scripts are persistent: one or more copies of the script are started up when the server initializes, and stay around until the server exits or they die a natural death. After performing whatever one-time initialization it needs, the script enters a loop waiting for incoming connections, processing the request, and waiting some more.

A typical FastCGI script will look like this:

    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
    use CGI::Fast;
    &do_some_initialization();
    while ($q = new CGI::Fast) {
        &process_request($q);
    }

Each time there's a new request, CGI::Fast returns a CGI object to your loop. The rest of the time your script waits in the call to new(). When the server requests that your script be terminated, new() will return undef. You can of course exit earlier if you choose. A new version of the script will be respawned to take its place (this may be necessary in order to avoid Perl memory leaks in long-running scripts).

CGI.pm's default CGI object mode also works. Just modify the loop this way:

    while (new CGI::Fast) {
        &process_request;
    }

Calls to header(), start_form(), etc. will all operate on the current request.

INSTALLING FASTCGI SCRIPTS

See the FastCGI developer's kit documentation for full details. On the Apache server, the following line must be added to srm.conf:

    AddType application/x-httpd-fcgi .fcgi

FastCGI scripts must end in the extension .fcgi. For each script you install, you must add something like the following to srm.conf:

    FastCgiServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -processes 2

This instructs Apache to launch two copies of file_upload.fcgi at startup time.

USING FASTCGI SCRIPTS AS CGI SCRIPTS

Any script that works correctly as a FastCGI script will also work correctly when installed as a vanilla CGI script. However it will not see any performance benefit.

EXTERNAL FASTCGI SERVER INVOCATION

FastCGI supports a TCP/IP transport mechanism which allows FastCGI scripts to run external to the webserver, perhaps on a remote machine. To configure the webserver to connect to an external FastCGI server, you would add the following to your srm.conf:

    FastCgiExternalServer /usr/etc/httpd/fcgi-bin/file_upload.fcgi -host sputnik:8888

Two environment variables affect how the CGI::Fast object is created, allowing CGI::Fast to be used as an external FastCGI server. (See FCGI documentation for FCGI::OpenSocket for more information.)

FCGI_SOCKET_PATH

The address (TCP/IP) or path (UNIX Domain) of the socket the external FastCGI script to which bind an listen for incoming connections from the web server.

FCGI_LISTEN_QUEUE

Maximum length of the queue of pending connections.

For example:

    #!/usr/local/bin/perl    # must be a FastCGI version of perl!
    use CGI::Fast;
    &do_some_initialization();
    $ENV{FCGI_SOCKET_PATH} = "sputnik:8888";
    $ENV{FCGI_LISTEN_QUEUE} = 100;
    while ($q = new CGI::Fast) {
        &process_request($q);
    }

CAVEATS

I haven't tested this very much.

AUTHOR INFORMATION

Copyright 1996-1998, Lincoln D. Stein. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org

BUGS

This section intentionally left blank.

SEE ALSO

the CGI::Carp manpage, the CGI manpage


CGI::Pretty - module to produce nicely formatted HTML code

    • Tags that won't be formatted
    • Customizing the Indenting
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

CGI::Pretty - module to produce nicely formatted HTML code

SYNOPSIS

    use CGI::Pretty qw( :html3 );

    # Print a table with a single data element
    print table( TR( td( "foo" ) ) );

DESCRIPTION

CGI::Pretty is a module that derives from CGI. It's sole function is to allow users of CGI to output nicely formatted HTML code.

When using the CGI module, the following code: print table( TR( td( "foo" ) ) );

produces the following output: <TABLE><TR><TD>foo</TD></TR></TABLE>

If a user were to create a table consisting of many rows and many columns, the resultant HTML code would be quite difficult to read since it has no carriage returns or indentation.

CGI::Pretty fixes this problem. What it does is add a carriage return and indentation to the HTML code so that one can easily read it.

    print table( TR( td( "foo" ) ) );

now produces the following output: <TABLE> <TR> <TD> foo </TD> </TR> </TABLE>

Tags that won't be formatted

The <A> and <PRE> tags are not formatted. If these tags were formatted, the user would see the extra indentation on the web browser causing the page to look different than what would be expected. If you wish to add more tags to the list of tags that are not to be touched, push them onto the @AS_IS array:

    push @CGI::Pretty::AS_IS,qw(CODE XMP);

Customizing the Indenting

If you wish to have your own personal style of indenting, you can change the $INDENT variable:

    $CGI::Pretty::INDENT = "\t\t";

would cause the indents to be two tabs.

Similarly, if you wish to have more space between lines, you may change the $LINEBREAK variable:

    $CGI::Pretty::LINEBREAK = "\n\n";

would create two carriage returns between lines.

If you decide you want to use the regular CGI indenting, you can easily do the following:

    $CGI::Pretty::INDENT = $CGI::Pretty::LINEBREAK = "";

BUGS

This section intentionally left blank.

AUTHOR

Brian Paulsen <Brian@ThePaulsens.com>, with minor modifications by Lincoln Stein <lstein@cshl.org> for incorporation into the CGI.pm distribution.

Copyright 1999, Brian Paulsen. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Bug reports and comments to Brian@ThePaulsens.com. You can also write to lstein@cshl.org, but this code looks pretty hairy to me and I'm not sure I understand it!

SEE ALSO

the CGI manpage


CGI::Push - Simple Interface to Server Push

  • USING CGI::Push
    • Heterogeneous Pages
    • Changing the Page Delay on the Fly
  • INSTALLING CGI::Push SCRIPTS
  • AUTHOR INFORMATION
  • BUGS
  • SEE ALSO

NAME

CGI::Push - Simple Interface to Server Push

SYNOPSIS

    use CGI::Push qw(:standard);

    do_push(-next_page=>\&next_page,
            -last_page=>\&last_page,
            -delay=>0.5);

    sub next_page {
        my($q,$counter) = @_;
        return undef if $counter >= 10;
        return start_html('Test'),
               h1('Visible'),"\n",
               "This page has been called ", strong($counter)," times",
               end_html();
    }

    sub last_page {
        my($q,$counter) = @_;
        return start_html('Done'),
               h1('Finished'),
               strong($counter - 1),' iterations.',
               end_html;
    }

DESCRIPTION

CGI::Push is a subclass of the CGI object created by CGI.pm. It is specialized for server push operations, which allow you to create animated pages whose content changes at regular intervals.

You provide CGI::Push with a pointer to a subroutine that will draw one page. Every time your subroutine is called, it generates a new page. The contents of the page will be transmitted to the browser in such a way that it will replace what was there beforehand. The technique will work with HTML pages as well as with graphics files, allowing you to create animated GIFs.

Only Netscape Navigator supports server push. Internet Explorer browsers do not.

USING CGI::Push

CGI::Push adds one new method to the standard CGI suite, do_push(). When you call this method, you pass it a reference to a subroutine that is responsible for drawing each new page, an interval delay, and an optional subroutine for drawing the last page. Other optional parameters include most of those recognized by the CGI header() method.

You may call do_push() in the object oriented manner or not, as you prefer:

    use CGI::Push;
    $q = new CGI::Push;
    $q->do_push(-next_page=>\&draw_a_page);

        -or-
    use CGI::Push qw(:standard);
    do_push(-next_page=>\&draw_a_page);

Parameters are as follows:

-next_page
    do_push(-next_page=>\&my_draw_routine);

This required parameter points to a reference to a subroutine responsible for drawing each new page. The subroutine should expect two parameters consisting of the CGI object and a counter indicating the number of times the subroutine has been called. It should return the contents of the page as an array of one or more items to print. It can return a false value (or an empty array) in order to abort the redrawing loop and print out the final page (if any)

    sub my_draw_routine {
        my($q,$counter) = @_;
        return undef if $counter > 100;
        return start_html('testing'),
               h1('testing'),
               "This page called $counter times";
    }

You are of course free to refer to create and use global variables within your draw routine in order to achieve special effects.

-last_page

This optional parameter points to a reference to the subroutine responsible for drawing the last page of the series. It is called after the -next_page routine returns a false value. The subroutine itself should have exactly the same calling conventions as the -next_page routine.

-type

This optional parameter indicates the content type of each page. It defaults to "text/html". Normally the module assumes that each page is of a homogenous MIME type. However if you provide either of the magic values "heterogeneous" or "dynamic" (the latter provided for the convenience of those who hate long parameter names), you can specify the MIME type -- and other header fields -- on a per-page basis. See "heterogeneous pages" for more details.

-delay

This indicates the delay, in seconds, between frames. Smaller delays refresh the page faster. Fractional values are allowed.

If not specified, -delay will default to 1 second

-cookie, -target, -expires, -nph

These have the same meaning as the like-named parameters in CGI::header().

If not specified, -nph will default to 1 (as needed for many servers, see below).

Heterogeneous Pages

Ordinarily all pages displayed by CGI::Push share a common MIME type. However by providing a value of "heterogeneous" or "dynamic" in the do_push() -type parameter, you can specify the MIME type of each page on a case-by-case basis.

If you use this option, you will be responsible for producing the HTTP header for each page. Simply modify your draw routine to look like this:

    sub my_draw_routine {
        my($q,$counter) = @_;
        return header('text/html'),   # note we're producing the header here
               start_html('testing'),
               h1('testing'),
               "This page called $counter times";
    }

You can add any header fields that you like, but some (cookies and status fields included) may not be interpreted by the browser. One interesting effect is to display a series of pages, then, after the last page, to redirect the browser to a new URL. Because redirect() does b<not> work, the easiest way is with a -refresh header field, as shown below:

    sub my_draw_routine {
        my($q,$counter) = @_;
        return undef if $counter > 10;
        return header('text/html'),   # note we're producing the header here
               start_html('testing'),
               h1('testing'),
               "This page called $counter times";
    }

    sub my_last_page {
        return header(-refresh=>'5; URL=http://somewhere.else/finished.html',
                      -type=>'text/html'),
               start_html('Moved'),
               h1('This is the last page'),
               'Goodbye!'
               hr,
               end_html;
    }

Changing the Page Delay on the Fly

If you would like to control the delay between pages on a page-by-page basis, call push_delay() from within your draw routine. push_delay() takes a single numeric argument representing the number of seconds you wish to delay after the current page is displayed and before displaying the next one. The delay may be fractional. Without parameters, push_delay() just returns the current delay.

INSTALLING CGI::Push SCRIPTS

Server push scripts must be installed as no-parsed-header (NPH) scripts in order to work correctly on many servers. On Unix systems, this is most often accomplished by prefixing the script's name with "nph-". Recognition of NPH scripts happens automatically with WebSTAR and Microsoft IIS. Users of other servers should see their documentation for help.

Apache web server from version 1.3b2 on does not need server push scripts installed as NPH scripts: the -nph parameter to do_push() may be set to a false value to disable the extra headers needed by an NPH script.

AUTHOR INFORMATION

Copyright 1995-1998, Lincoln D. Stein. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org

BUGS

This section intentionally left blank.

SEE ALSO

the CGI::Carp manpage, the CGI manpage


CGI::Switch - Backward compatibility module for defunct CGI::Switch

  • ABSTRACT
  • DESCRIPTION
  • AUTHOR INFORMATION
  • BUGS
  • SEE ALSO

NAME

CGI::Switch - Backward compatibility module for defunct CGI::Switch

SYNOPSIS

Do not use this module. It is deprecated.

ABSTRACT

DESCRIPTION

AUTHOR INFORMATION

BUGS

SEE ALSO


CGI::Util - Internal utilities used by CGI module

  • AUTHOR INFORMATION
  • SEE ALSO

NAME

CGI::Util - Internal utilities used by CGI module

SYNOPSIS

none

DESCRIPTION

no public subroutines

AUTHOR INFORMATION

Copyright 1995-1998, Lincoln D. Stein. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: lstein@cshl.org. When sending bug reports, please provide the version of CGI.pm, the version of Perl, the name and version of your Web server, and the name and version of the operating system you are using. If the problem is even remotely browser dependent, please provide information about the affected browers as well.

SEE ALSO

the CGI manpage


CPAN - query, download and build perl modules from CPAN sites

  • STATUS
  • DESCRIPTION
    • Interactive Mode
    • CPAN::Shell
    • autobundle
    • recompile
    • The four CPAN::* Classes: Author, Bundle, Module, Distribution
    • Programmer's interface
    • Methods in the other Classes
    • Cache Manager
    • Bundles
    • Prerequisites
    • Finding packages and VERSION
    • Debugging
    • Floppy, Zip, Offline Mode
  • CONFIGURATION
    • Note on urllist parameter's format
    • urllist parameter has CD-ROM support
  • SECURITY
  • EXPORT
  • POPULATE AN INSTALLATION WITH LOTS OF MODULES
  • WORKING WITH CPAN.pm BEHIND FIREWALLS
    • Three basic types of firewalls
    • Configuring lynx or ncftp for going through a firewall
  • FAQ
  • BUGS
  • AUTHOR
  • TRANSLATIONS
  • SEE ALSO

NAME

CPAN - query, download and build perl modules from CPAN sites

SYNOPSIS

Interactive mode:

  perl -MCPAN -e shell;

Batch mode:

  use CPAN;

  autobundle, clean, install, make, recompile, test

STATUS

This module will eventually be replaced by CPANPLUS. CPANPLUS is kind of a modern rewrite from ground up with greater extensibility and more features but no full compatibility. If you're new to CPAN.pm, you probably should investigate if CPANPLUS is the better choice for you. If you're already used to CPAN.pm you're welcome to continue using it, if you accept that its development is mostly (though not completely) stalled.

DESCRIPTION

The CPAN module is designed to automate the make and install of perl modules and extensions. It includes some primitive searching capabilities and knows how to use Net::FTP or LWP (or lynx or an external ftp client) to fetch the raw data from the net.

Modules are fetched from one or more of the mirrored CPAN (Comprehensive Perl Archive Network) sites and unpacked in a dedicated directory.

The CPAN module also supports the concept of named and versioned bundles of modules. Bundles simplify the handling of sets of related modules. See Bundles below.

The package contains a session manager and a cache manager. There is no status retained between sessions. The session manager keeps track of what has been fetched, built and installed in the current session. The cache manager keeps track of the disk space occupied by the make processes and deletes excess space according to a simple FIFO mechanism.

For extended searching capabilities there's a plugin for CPAN available, CPAN::WAIT. CPAN::WAIT is a full-text search engine that indexes all documents available in CPAN authors directories. If CPAN::WAIT is installed on your system, the interactive shell of CPAN.pm will enable the wq, wr, wd, wl, and wh commands which send queries to the WAIT server that has been configured for your installation.

All other methods provided are accessible in a programmer style and in an interactive shell style.

Interactive Mode

The interactive mode is entered by running

    perl -MCPAN -e shell

which puts you into a readline interface. You will have the most fun if you install Term::ReadKey and Term::ReadLine to enjoy both history and command completion.

Once you are on the command line, type 'h' and the rest should be self-explanatory.

The function call shell takes two optional arguments, one is the prompt, the second is the default initial command line (the latter only works if a real ReadLine interface module is installed).

The most common uses of the interactive modes are

Searching for authors, bundles, distribution files and modules

There are corresponding one-letter commands a, b, d, and m for each of the four categories and another, i for any of the mentioned four. Each of the four entities is implemented as a class with slightly differing methods for displaying an object.

Arguments you pass to these commands are either strings exactly matching the identification string of an object or regular expressions that are then matched case-insensitively against various attributes of the objects. The parser recognizes a regular expression only if you enclose it between two slashes.

The principle is that the number of found objects influences how an item is displayed. If the search finds one item, the result is displayed with the rather verbose method as_string, but if we find more than one, we display each object with the terse method <as_glimpse>.

make, test, install, clean modules or distributions

These commands take any number of arguments and investigate what is necessary to perform the action. If the argument is a distribution file name (recognized by embedded slashes), it is processed. If it is a module, CPAN determines the distribution file in which this module is included and processes that, following any dependencies named in the module's Makefile.PL (this behavior is controlled by prerequisites_policy.)

Any make or test are run unconditionally. An

  install <distribution_file>

also is run unconditionally. But for

  install <module>

CPAN checks if an install is actually needed for it and prints module up to date in the case that the distribution file containing the module doesn't need to be updated.

CPAN also keeps track of what it has done within the current session and doesn't try to build a package a second time regardless if it succeeded or not. The force command takes as a first argument the method to invoke (currently: make, test, or install) and executes the command from scratch.

Example:

    cpan> install OpenGL
    OpenGL is up to date.
    cpan> force install OpenGL
    Running make
    OpenGL-0.4/
    OpenGL-0.4/COPYRIGHT
    [...]

A clean command results in a

  make clean

being executed within the distribution file's working directory.

get, readme, look module or distribution

get downloads a distribution file without further action. readme displays the README file of the associated distribution. Look gets and untars (if not yet done) the distribution file, changes to the appropriate directory and opens a subshell process in that directory.

ls author

ls lists all distribution files in and below an author's CPAN directory. Only those files that contain modules are listed and if there is more than one for any given module, only the most recent one is listed.

Signals

CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are in the cpan-shell it is intended that you can press ^C anytime and return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell to clean up and leave the shell loop. You can emulate the effect of a SIGTERM by sending two consecutive SIGINTs, which usually means by pressing ^C twice.

CPAN.pm ignores a SIGPIPE. If the user sets inactivity_timeout, a SIGALRM is used during the run of the perl Makefile.PL subprocess.

CPAN::Shell

The commands that are available in the shell interface are methods in the package CPAN::Shell. If you enter the shell command, all your input is split by the Text::ParseWords::shellwords() routine which acts like most shells do. The first word is being interpreted as the method to be called and the rest of the words are treated as arguments to this method. Continuation lines are supported if a line ends with a literal backslash.

autobundle

autobundle writes a bundle file into the $CPAN::Config->{cpan_home}/Bundle directory. The file contains a list of all modules that are both available from CPAN and currently installed within @INC. The name of the bundle file is based on the current date and a counter.

recompile

recompile() is a very special command in that it takes no argument and runs the make/test/install cycle with brute force over all installed dynamically loadable extensions (aka XS modules) with 'force' in effect. The primary purpose of this command is to finish a network installation. Imagine, you have a common source tree for two different architectures. You decide to do a completely independent fresh installation. You start on one architecture with the help of a Bundle file produced earlier. CPAN installs the whole Bundle for you, but when you try to repeat the job on the second architecture, CPAN responds with a "Foo up to date" message for all modules. So you invoke CPAN's recompile on the second architecture and you're done.

Another popular use for recompile is to act as a rescue in case your perl breaks binary compatibility. If one of the modules that CPAN uses is in turn depending on binary compatibility (so you cannot run CPAN commands), then you should try the CPAN::Nox module for recovery.

The four CPAN::* Classes: Author, Bundle, Module, Distribution

Although it may be considered internal, the class hierarchy does matter for both users and programmer. CPAN.pm deals with above mentioned four classes, and all those classes share a set of methods. A classical single polymorphism is in effect. A metaclass object registers all objects of all kinds and indexes them with a string. The strings referencing objects have a separated namespace (well, not completely separated):

         Namespace                         Class
   words containing a "/" (slash)      Distribution
    words starting with Bundle::          Bundle
          everything else            Module or Author

Modules know their associated Distribution objects. They always refer to the most recent official release. Developers may mark their releases as unstable development versions (by inserting an underbar into the module version number which will also be reflected in the distribution name when you run 'make dist'), so the really hottest and newest distribution is not always the default. If a module Foo circulates on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient way to install version 1.23 by saying

    install Foo

This would install the complete distribution file (say BAR/Foo-1.23.tar.gz) with all accompanying material. But if you would like to install version 1.23_90, you need to know where the distribution file resides on CPAN relative to the authors/id/ directory. If the author is BAR, this might be BAR/Foo-1.23_90.tar.gz; so you would have to say

    install BAR/Foo-1.23_90.tar.gz

The first example will be driven by an object of the class CPAN::Module, the second by an object of class CPAN::Distribution.

Programmer's interface

If you do not enter the shell, the available shell commands are both available as methods (CPAN::Shell->install(...)) and as functions in the calling package (install(...)).

There's currently only one class that has a stable interface - CPAN::Shell. All commands that are available in the CPAN shell are methods of the class CPAN::Shell. Each of the commands that produce listings of modules (r, autobundle, u) also return a list of the IDs of all modules within the list.

expand($type,@things)

The IDs of all objects available within a program are strings that can be expanded to the corresponding real objects with the CPAN::Shell->expand("Module",@things) method. Expand returns a list of CPAN::Module objects according to the @things arguments given. In scalar context it only returns the first element of the list.

expandany(@things)

Like expand, but returns objects of the appropriate type, i.e. CPAN::Bundle objects for bundles, CPAN::Module objects for modules and CPAN::Distribution objects fro distributions.

Programming Examples

This enables the programmer to do operations that combine functionalities that are available in the shell.

    # install everything that is outdated on my disk:
    perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
    # install my favorite programs if necessary:
    for $mod (qw(Net::FTP Digest::MD5 Data::Dumper)){
        my $obj = CPAN::Shell->expand('Module',$mod);
        $obj->install;
    }

    # list all modules on my disk that have no VERSION number
    for $mod (CPAN::Shell->expand("Module","/./")){
        next unless $mod->inst_file;
        # MakeMaker convention for undefined $VERSION:
        next unless $mod->inst_version eq "undef";
        print "No VERSION in ", $mod->id, "\n";
    }

    # find out which distribution on CPAN contains a module:
    print CPAN::Shell->expand("Module","Apache::Constants")->cpan_file

Or if you want to write a cronjob to watch The CPAN, you could list all modules that need updating. First a quick and dirty way:

    perl -e 'use CPAN; CPAN::Shell->r;'

If you don't want to get any output in the case that all modules are up to date, you can parse the output of above command for the regular expression //modules are up to date// and decide to mail the output only if it doesn't match. Ick?

If you prefer to do it more in a programmer style in one single process, maybe something like this suits you better:

  # list all modules on my disk that have newer versions on CPAN
  for $mod (CPAN::Shell->expand("Module","/./")){
    next unless $mod->inst_file;
    next if $mod->uptodate;
    printf "Module %s is installed as %s, could be updated to %s from CPAN\n",
        $mod->id, $mod->inst_version, $mod->cpan_version;
  }

If that gives you too much output every day, you maybe only want to watch for three modules. You can write

  for $mod (CPAN::Shell->expand("Module","/Apache|LWP|CGI/")){

as the first line instead. Or you can combine some of the above tricks:

  # watch only for a new mod_perl module
  $mod = CPAN::Shell->expand("Module","mod_perl");
  exit if $mod->uptodate;
  # new mod_perl arrived, let me know all update recommendations
  CPAN::Shell->r;

Methods in the other Classes

The programming interface for the classes CPAN::Module, CPAN::Distribution, CPAN::Bundle, and CPAN::Author is still considered beta and partially even alpha. In the following paragraphs only those methods are documented that have proven useful over a longer time and thus are unlikely to change.

CPAN::Author::as_glimpse()

Returns a one-line description of the author

CPAN::Author::as_string()

Returns a multi-line description of the author

CPAN::Author::email()

Returns the author's email address

CPAN::Author::fullname()

Returns the author's name

CPAN::Author::name()

An alias for fullname

CPAN::Bundle::as_glimpse()

Returns a one-line description of the bundle

CPAN::Bundle::as_string()

Returns a multi-line description of the bundle

CPAN::Bundle::clean()

Recursively runs the clean method on all items contained in the bundle.

CPAN::Bundle::contains()

Returns a list of objects' IDs contained in a bundle. The associated objects may be bundles, modules or distributions.

CPAN::Bundle::force($method,@args)

Forces CPAN to perform a task that normally would have failed. Force takes as arguments a method name to be called and any number of additional arguments that should be passed to the called method. The internals of the object get the needed changes so that CPAN.pm does not refuse to take the action. The force is passed recursively to all contained objects.

CPAN::Bundle::get()

Recursively runs the get method on all items contained in the bundle

CPAN::Bundle::inst_file()

Returns the highest installed version of the bundle in either @INC or $CPAN::Config-{cpan_home}>. Note that this is different from CPAN::Module::inst_file.

CPAN::Bundle::inst_version()

Like CPAN::Bundle::inst_file, but returns the $VERSION

CPAN::Bundle::uptodate()

Returns 1 if the bundle itself and all its members are uptodate.

CPAN::Bundle::install()

Recursively runs the install method on all items contained in the bundle

CPAN::Bundle::make()

Recursively runs the make method on all items contained in the bundle

CPAN::Bundle::readme()

Recursively runs the readme method on all items contained in the bundle

CPAN::Bundle::test()

Recursively runs the test method on all items contained in the bundle

CPAN::Distribution::as_glimpse()

Returns a one-line description of the distribution

CPAN::Distribution::as_string()

Returns a multi-line description of the distribution

CPAN::Distribution::clean()

Changes to the directory where the distribution has been unpacked and runs make clean there.

CPAN::Distribution::containsmods()

Returns a list of IDs of modules contained in a distribution file. Only works for distributions listed in the 02packages.details.txt.gz file. This typically means that only the most recent version of a distribution is covered.

CPAN::Distribution::cvs_import()

Changes to the directory where the distribution has been unpacked and runs something like

    cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version

there.

CPAN::Distribution::dir()

Returns the directory into which this distribution has been unpacked.

CPAN::Distribution::force($method,@args)

Forces CPAN to perform a task that normally would have failed. Force takes as arguments a method name to be called and any number of additional arguments that should be passed to the called method. The internals of the object get the needed changes so that CPAN.pm does not refuse to take the action.

CPAN::Distribution::get()

Downloads the distribution from CPAN and unpacks it. Does nothing if the distribution has already been downloaded and unpacked within the current session.

CPAN::Distribution::install()

Changes to the directory where the distribution has been unpacked and runs the external command make install there. If make has not yet been run, it will be run first. A make test will be issued in any case and if this fails, the install will be canceled. The cancellation can be avoided by letting force run the install for you.

CPAN::Distribution::isa_perl()

Returns 1 if this distribution file seems to be a perl distribution. Normally this is derived from the file name only, but the index from CPAN can contain a hint to achieve a return value of true for other filenames too.

CPAN::Distribution::look()

Changes to the directory where the distribution has been unpacked and opens a subshell there. Exiting the subshell returns.

CPAN::Distribution::make()

First runs the get method to make sure the distribution is downloaded and unpacked. Changes to the directory where the distribution has been unpacked and runs the external commands perl Makefile.PL and make there.

CPAN::Distribution::prereq_pm()

Returns the hash reference that has been announced by a distribution as the PREREQ_PM hash in the Makefile.PL. Note: works only after an attempt has been made to make the distribution. Returns undef otherwise.

CPAN::Distribution::readme()

Downloads the README file associated with a distribution and runs it through the pager specified in $CPAN::Config-{pager}>.

CPAN::Distribution::test()

Changes to the directory where the distribution has been unpacked and runs make test there.

CPAN::Distribution::uptodate()

Returns 1 if all the modules contained in the distribution are uptodate. Relies on containsmods.

CPAN::Index::force_reload()

Forces a reload of all indices.

CPAN::Index::reload()

Reloads all indices if they have been read more than $CPAN::Config-{index_expire}> days.

CPAN::InfoObj::dump()

CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution inherit this method. It prints the data structure associated with an object. Useful for debugging. Note: the data structure is considered internal and thus subject to change without notice.

CPAN::Module::as_glimpse()

Returns a one-line description of the module

CPAN::Module::as_string()

Returns a multi-line description of the module

CPAN::Module::clean()

Runs a clean on the distribution associated with this module.

CPAN::Module::cpan_file()

Returns the filename on CPAN that is associated with the module.

CPAN::Module::cpan_version()

Returns the latest version of this module available on CPAN.

CPAN::Module::cvs_import()

Runs a cvs_import on the distribution associated with this module.

CPAN::Module::description()

Returns a 44 character description of this module. Only available for modules listed in The Module List (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz)

CPAN::Module::force($method,@args)

Forces CPAN to perform a task that normally would have failed. Force takes as arguments a method name to be called and any number of additional arguments that should be passed to the called method. The internals of the object get the needed changes so that CPAN.pm does not refuse to take the action.

CPAN::Module::get()

Runs a get on the distribution associated with this module.

CPAN::Module::inst_file()

Returns the filename of the module found in @INC. The first file found is reported just like perl itself stops searching @INC when it finds a module.

CPAN::Module::inst_version()

Returns the version number of the module in readable format.

CPAN::Module::install()

Runs an install on the distribution associated with this module.

CPAN::Module::look()

Changes to the directory where the distribution associated with this module has been unpacked and opens a subshell there. Exiting the subshell returns.

CPAN::Module::make()

Runs a make on the distribution associated with this module.

CPAN::Module::manpage_headline()

If module is installed, peeks into the module's manpage, reads the headline and returns it. Moreover, if the module has been downloaded within this session, does the equivalent on the downloaded module even if it is not installed.

CPAN::Module::readme()

Runs a readme on the distribution associated with this module.

CPAN::Module::test()

Runs a test on the distribution associated with this module.

CPAN::Module::uptodate()

Returns 1 if the module is installed and up-to-date.

CPAN::Module::userid()

Returns the author's ID of the module.

Cache Manager

Currently the cache manager only keeps track of the build directory ($CPAN::Config->{build_dir}). It is a simple FIFO mechanism that deletes complete directories below build_dir as soon as the size of all directories there gets bigger than $CPAN::Config->{build_cache} (in MB). The contents of this cache may be used for later re-installations that you intend to do manually, but will never be trusted by CPAN itself. This is due to the fact that the user might use these directories for building modules on different architectures.

There is another directory ($CPAN::Config->{keep_source_where}) where the original distribution files are kept. This directory is not covered by the cache manager and must be controlled by the user. If you choose to have the same directory as build_dir and as keep_source_where directory, then your sources will be deleted with the same fifo mechanism.

Bundles

A bundle is just a perl module in the namespace Bundle:: that does not define any functions or methods. It usually only contains documentation.

It starts like a perl module with a package declaration and a $VERSION variable. After that the pod section looks like any other pod with the only difference being that one special pod section exists starting with (verbatim):

        =head1 CONTENTS

In this pod section each line obeys the format

        Module_Name [Version_String] [- optional text]

The only required part is the first field, the name of a module (e.g. Foo::Bar, ie. not the name of the distribution file). The rest of the line is optional. The comment part is delimited by a dash just as in the man page header.

The distribution of a bundle should follow the same convention as other distributions.

Bundles are treated specially in the CPAN package. If you say 'install Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all the modules in the CONTENTS section of the pod. You can install your own Bundles locally by placing a conformant Bundle file somewhere into your @INC path. The autobundle() command which is available in the shell interface does that for you by including all currently installed modules in a snapshot bundle file.

Prerequisites

If you have a local mirror of CPAN and can access all files with "file:" URLs, then you only need a perl better than perl5.003 to run this module. Otherwise Net::FTP is strongly recommended. LWP may be required for non-UNIX systems or if your nearest CPAN site is associated with a URL that is not ftp:.

If you have neither Net::FTP nor LWP, there is a fallback mechanism implemented for an external ftp command or for an external lynx command.

Finding packages and VERSION

This module presumes that all packages on CPAN

  • declare their $VERSION variable in an easy to parse manner. This prerequisite can hardly be relaxed because it consumes far too much memory to load all packages into the running program just to determine the $VERSION variable. Currently all programs that are dealing with version use something like this

        perl -MExtUtils::MakeMaker -le \
        'print MM->parse_version(shift)' filename

    If you are author of a package and wonder if your $VERSION can be parsed, please try the above method.

  • come as compressed or gzipped tarfiles or as zip files and contain a Makefile.PL (well, we try to handle a bit more, but without much enthusiasm).

Debugging

The debugging of this module is a bit complex, because we have interferences of the software producing the indices on CPAN, of the mirroring process on CPAN, of packaging, of configuration, of synchronicity, and of bugs within CPAN.pm.

For code debugging in interactive mode you can try "o debug" which will list options for debugging the various parts of the code. You should know that "o debug" has built-in completion support.

For data debugging there is the dump command which takes the same arguments as make/test/install and outputs the object's Data::Dumper dump.

Floppy, Zip, Offline Mode

CPAN.pm works nicely without network too. If you maintain machines that are not networked at all, you should consider working with file: URLs. Of course, you have to collect your modules somewhere first. So you might use CPAN.pm to put together all you need on a networked machine. Then copy the $CPAN::Config->{keep_source_where} (but not $CPAN::Config->{build_dir}) directory on a floppy. This floppy is kind of a personal CPAN. CPAN.pm on the non-networked machines works nicely with this floppy. See also below the paragraph about CD-ROM support.

CONFIGURATION

When the CPAN module is used for the first time, a configuration dialog tries to determine a couple of site specific options. The result of the dialog is stored in a hash reference $CPAN::Config in a file CPAN/Config.pm.

The default values defined in the CPAN/Config.pm file can be overridden in a user specific file: CPAN/MyConfig.pm. Such a file is best placed in $HOME/.cpan/CPAN/MyConfig.pm, because $HOME/.cpan is added to the search path of the CPAN module before the use() or require() statements.

The configuration dialog can be started any time later again by issueing the command o conf init in the CPAN shell.

Currently the following keys in the hash reference $CPAN::Config are defined:

  build_cache        size of cache for directories to build modules
  build_dir          locally accessible directory to build modules
  index_expire       after this many days refetch index files
  cache_metadata     use serializer to cache metadata
  cpan_home          local directory reserved for this package
  dontload_hash      anonymous hash: modules in the keys will not be
                     loaded by the CPAN::has_inst() routine
  gzip               location of external program gzip
  histfile           file to maintain history between sessions
  histsize           maximum number of lines to keep in histfile
  inactivity_timeout breaks interactive Makefile.PLs after this
                     many seconds inactivity. Set to 0 to never break.
  inhibit_startup_message
                     if true, does not print the startup message
  keep_source_where  directory in which to keep the source (if we do)
  make               location of external make program
  make_arg           arguments that should always be passed to 'make'
  make_install_arg   same as make_arg for 'make install'
  makepl_arg         arguments passed to 'perl Makefile.PL'
  pager              location of external program more (or any pager)
  prerequisites_policy
                     what to do if you are missing module prerequisites
                     ('follow' automatically, 'ask' me, or 'ignore')
  proxy_user         username for accessing an authenticating proxy
  proxy_pass         password for accessing an authenticating proxy
  scan_cache         controls scanning of cache ('atstart' or 'never')
  tar                location of external program tar
  term_is_latin      if true internal UTF-8 is translated to ISO-8859-1
                     (and nonsense for characters outside latin range)
  unzip              location of external program unzip
  urllist            arrayref to nearby CPAN sites (or equivalent locations)
  wait_list          arrayref to a wait server to try (See CPAN::WAIT)
  ftp_proxy,      }  the three usual variables for configuring
    http_proxy,   }  proxy requests. Both as CPAN::Config variables
    no_proxy      }  and as environment variables configurable.

You can set and query each of these options interactively in the cpan shell with the command set defined within the o conf command:

o conf <scalar option>

prints the current value of the scalar option

o conf <scalar option> <value>

Sets the value of the scalar option to value

o conf <list option>

prints the current value of the list option in MakeMaker's neatvalue format.

o conf <list option> [shift|pop]

shifts or pops the array in the list option variable

o conf <list option> [unshift|push|splice] <list>

works like the corresponding perl commands.

Note on urllist parameter's format

urllist parameters are URLs according to RFC 1738. We do a little guessing if your URL is not compliant, but if you have problems with file URLs, please try the correct format. Either:

    file://localhost/whatever/ftp/pub/CPAN/

or

    file:///home/ftp/pub/CPAN/

urllist parameter has CD-ROM support

The urllist parameter of the configuration table contains a list of URLs that are to be used for downloading. If the list contains any file URLs, CPAN always tries to get files from there first. This feature is disabled for index files. So the recommendation for the owner of a CD-ROM with CPAN contents is: include your local, possibly outdated CD-ROM as a file URL at the end of urllist, e.g.

  o conf urllist push file://localhost/CDROM/CPAN

CPAN.pm will then fetch the index files from one of the CPAN sites that come at the beginning of urllist. It will later check for each module if there is a local copy of the most recent version.

Another peculiarity of urllist is that the site that we could successfully fetch the last file from automatically gets a preference token and is tried as the first site for the next request. So if you add a new site at runtime it may happen that the previously preferred site will be tried another time. This means that if you want to disallow a site for the next transfer, it must be explicitly removed from urllist.

SECURITY

There's no strong security layer in CPAN.pm. CPAN.pm helps you to install foreign, unmasked, unsigned code on your machine. We compare to a checksum that comes from the net just as the distribution file itself. If somebody has managed to tamper with the distribution file, they may have as well tampered with the CHECKSUMS file. Future development will go towards strong authentication.

EXPORT

Most functions in package CPAN are exported per default. The reason for this is that the primary use is intended for the cpan shell or for one-liners.

POPULATE AN INSTALLATION WITH LOTS OF MODULES

Populating a freshly installed perl with my favorite modules is pretty easy if you maintain a private bundle definition file. To get a useful blueprint of a bundle definition file, the command autobundle can be used on the CPAN shell command line. This command writes a bundle definition file for all modules that are installed for the currently running perl interpreter. It's recommended to run this command only once and from then on maintain the file manually under a private name, say Bundle/my_bundle.pm. With a clever bundle file you can then simply say

    cpan> install Bundle::my_bundle

then answer a few questions and then go out for a coffee.

Maintaining a bundle definition file means keeping track of two things: dependencies and interactivity. CPAN.pm sometimes fails on calculating dependencies because not all modules define all MakeMaker attributes correctly, so a bundle definition file should specify prerequisites as early as possible. On the other hand, it's a bit annoying that many distributions need some interactive configuring. So what I try to accomplish in my private bundle file is to have the packages that need to be configured early in the file and the gentle ones later, so I can go out after a few minutes and leave CPAN.pm untended.

WORKING WITH CPAN.pm BEHIND FIREWALLS

Thanks to Graham Barr for contributing the following paragraphs about the interaction between perl, and various firewall configurations. For further informations on firewalls, it is recommended to consult the documentation that comes with the ncftp program. If you are unable to go through the firewall with a simple Perl setup, it is very likely that you can configure ncftp so that it works for your firewall.

Three basic types of firewalls

Firewalls can be categorized into three basic types.

http firewall

This is where the firewall machine runs a web server and to access the outside world you must do it via the web server. If you set environment variables like http_proxy or ftp_proxy to a values beginning with http:// or in your web browser you have to set proxy information then you know you are running an http firewall.

To access servers outside these types of firewalls with perl (even for ftp) you will need to use LWP.

ftp firewall

This where the firewall machine runs an ftp server. This kind of firewall will only let you access ftp servers outside the firewall. This is usually done by connecting to the firewall with ftp, then entering a username like "user@outside.host.com"

To access servers outside these type of firewalls with perl you will need to use Net::FTP.

One way visibility

I say one way visibility as these firewalls try to make themselves look invisible to the users inside the firewall. An FTP data connection is normally created by sending the remote server your IP address and then listening for the connection. But the remote server will not be able to connect to you because of the firewall. So for these types of firewall FTP connections need to be done in a passive mode.

There are two that I can think off.

SOCKS

If you are using a SOCKS firewall you will need to compile perl and link it with the SOCKS library, this is what is normally called a 'socksified' perl. With this executable you will be able to connect to servers outside the firewall as if it is not there.

IP Masquerade

This is the firewall implemented in the Linux kernel, it allows you to hide a complete network behind one IP address. With this firewall no special compiling is needed as you can access hosts directly.

For accessing ftp servers behind such firewalls you may need to set the environment variable FTP_PASSIVE to a true value, e.g.

    env FTP_PASSIVE=1 perl -MCPAN -eshell

or

    perl -MCPAN -e '$ENV{FTP_PASSIVE} = 1; shell'

Configuring lynx or ncftp for going through a firewall

If you can go through your firewall with e.g. lynx, presumably with a command such as

    /usr/local/bin/lynx -pscott:tiger

then you would configure CPAN.pm with the command

    o conf lynx "/usr/local/bin/lynx -pscott:tiger"

That's all. Similarly for ncftp or ftp, you would configure something like

    o conf ncftp "/usr/bin/ncftp -f /home/scott/ncftplogin.cfg"

Your mileage may vary...

FAQ

  1. )

    I installed a new version of module X but CPAN keeps saying, I have the old version installed

    Most probably you do have the old version installed. This can happen if a module installs itself into a different directory in the @INC path than it was previously installed. This is not really a CPAN.pm problem, you would have the same problem when installing the module manually. The easiest way to prevent this behaviour is to add the argument UNINST=1 to the make install call, and that is why many people add this argument permanently by configuring

      o conf make_install_arg UNINST=1
  2. )

    So why is UNINST=1 not the default?

    Because there are people who have their precise expectations about who may install where in the @INC path and who uses which @INC array. In fine tuned environments UNINST=1 can cause damage.

  3. )

    I want to clean up my mess, and install a new perl along with all modules I have. How do I go about it?

    Run the autobundle command for your old perl and optionally rename the resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl with the Configure option prefix, e.g.

        ./Configure -Dprefix=/usr/local/perl-5.6.78.9

    Install the bundle file you produced in the first step with something like

        cpan> install Bundle::mybundle

    and you're done.

  4. )

    When I install bundles or multiple modules with one command there is too much output to keep track of.

    You may want to configure something like

      o conf make_arg "| tee -ai /root/.cpan/logs/make.out"
  o conf make_install_arg "| tee -ai /root/.cpan/logs/make_install.out"

    so that STDOUT is captured in a file for later inspection.

  5. )

    I am not root, how can I install a module in a personal directory?

    You will most probably like something like this:

      o conf makepl_arg "LIB=~/myperl/lib \
                    INSTALLMAN1DIR=~/myperl/man/man1 \
                    INSTALLMAN3DIR=~/myperl/man/man3"
  install Sybase::Sybperl

    You can make this setting permanent like all o conf settings with o conf commit.

    You will have to add ~/myperl/man to the MANPATH environment variable and also tell your perl programs to look into ~/myperl/lib, e.g. by including

      use lib "$ENV{HOME}/myperl/lib";

    or setting the PERL5LIB environment variable.

    Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root.

  6. )

    How to get a package, unwrap it, and make a change before building it?

      look Sybase::Sybperl
  7. )

    I installed a Bundle and had a couple of fails. When I retried, everything resolved nicely. Can this be fixed to work on first try?

    The reason for this is that CPAN does not know the dependencies of all modules when it starts out. To decide about the additional items to install, it just uses data found in the generated Makefile. An undetected missing piece breaks the process. But it may well be that your Bundle installs some prerequisite later than some depending item and thus your second try is able to resolve everything. Please note, CPAN.pm does not know the dependency tree in advance and cannot sort the queue of things to install in a topologically correct order. It resolves perfectly well IFF all modules declare the prerequisites correctly with the PREREQ_PM attribute to MakeMaker. For bundles which fail and you need to install often, it is recommended sort the Bundle definition file manually. It is planned to improve the metadata situation for dependencies on CPAN in general, but this will still take some time.

  8. )

    In our intranet we have many modules for internal use. How can I integrate these modules with CPAN.pm but without uploading the modules to CPAN?

    Have a look at the CPAN::Site module.

  9. )

    When I run CPAN's shell, I get error msg about line 1 to 4, setting meta input/output via the /etc/inputrc file.

    Some versions of readline are picky about capitalization in the /etc/inputrc file and specifically RedHat 6.2 comes with a /etc/inputrc that contains the word on in lowercase. Change the occurrences of on to On and the bug should disappear.

  10. )

    Some authors have strange characters in their names.

    Internally CPAN.pm uses the UTF-8 charset. If your terminal is expecting ISO-8859-1 charset, a converter can be activated by setting term_is_latin to a true value in your config file. One way of doing so would be

        cpan> ! $CPAN::Config->{term_is_latin}=1

    Extended support for converters will be made available as soon as perl becomes stable with regard to charset issues.

BUGS

We should give coverage for all of the CPAN and not just the PAUSE part, right? In this discussion CPAN and PAUSE have become equal -- but they are not. PAUSE is authors/, modules/ and scripts/. CPAN is PAUSE plus the clpa/, doc/, misc/, ports/, and src/.

Future development should be directed towards a better integration of the other parts.

If a Makefile.PL requires special customization of libraries, prompts the user for special input, etc. then you may find CPAN is not able to build the distribution. In that case, you should attempt the traditional method of building a Perl module package from a shell.

AUTHOR

Andreas Koenig <andreas.koenig@anima.de>

TRANSLATIONS

Kawai,Takanori provides a Japanese translation of this manpage at http://member.nifty.ne.jp/hippo2000/perltips/CPAN.htm

SEE ALSO

perl(1), CPAN::Nox(3)


CPAN::FirstTime - Utility for CPAN::Config file Initialization

NAME

CPAN::FirstTime - Utility for CPAN::Config file Initialization

SYNOPSIS

CPAN::FirstTime::init()

DESCRIPTION

The init routine asks a few questions and writes a CPAN::Config file. Nothing special.


CPAN::Nox - Wrapper around CPAN.pm without using any XS module

  • SEE ALSO

NAME

CPAN::Nox - Wrapper around CPAN.pm without using any XS module

SYNOPSIS

Interactive mode:

  perl -MCPAN::Nox -e shell;

DESCRIPTION

This package has the same functionality as CPAN.pm, but tries to prevent the usage of compiled extensions during its own execution. Its primary purpose is a rescue in case you upgraded perl and broke binary compatibility somehow.

SEE ALSO

CPAN(3)


Cache::BaseCache -- abstract cache base class

  • SEE ALSO
  • AUTHOR

NAME

Cache::BaseCache -- abstract cache base class

DESCRIPTION

BaseCache provides functionality common to all instances of a cache. It differes from the CacheUtils package insofar as it is designed to be used as superclass for cache implementations.

SYNOPSIS

Cache::BaseCache is to be used as a superclass for cache implementations. The most effective way to use BaseCache is to use the protected _set_backend method, which will be used to retrieve the persistance mechanism. The subclass can then inherit the BaseCache's implentation of get, set, etc. However, due to the difficulty inheriting static methods in Perl, the subclass will likely need to explicitly implement Clear, Purge, and Size. Also, a factory pattern should be used to invoke the _complete_initialization routine after the object is constructed.

  package Cache::MyCache;

  use vars qw( @ISA );
  use Cache::BaseCache;
  use Cache::MyBackend;

  @ISA = qw( Cache::BaseCache );

  sub new
  {
    my ( $self ) = _new( @_ );

    $self->_complete_initialization( );

    return $self;
      }

  sub _new
  {
    my ( $proto, $p_options_hash_ref ) = @_;
    my $class = ref( $proto ) || $proto;
    my $self = $class->SUPER::_new( $p_options_hash_ref );
    $self->_set_backend( new Cache::MyBackend( ) );
    return $self;
  }

  sub Clear
  {
    foreach my $namespace ( _Namespaces( ) )
    {
      _Get_Backend( )->delete_namespace( $namespace );
    }
  }

  sub Purge
  {
    foreach my $namespace ( _Namespaces( ) )
    {
      _Get_Cache( $namespace )->purge( );
    }
  }

  sub Size
  {
    my $size = 0;

    foreach my $namespace ( _Namespaces( ) )
    {
      $size += _Get_Cache( $namespace )->size( );
    }

    return $size;
      }

SEE ALSO

Cache::Cache, Cache::FileCache, Cache::MemoryCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::BaseCacheTester -- abstract cache tester base class

  • METHODS
  • SEE ALSO
  • AUTHOR

NAME

Cache::BaseCacheTester -- abstract cache tester base class

DESCRIPTION

BaseCacheTester provides functionality common to all instances of a class that will test cache implementations.

SYNOPSIS

BaseCacheTester provides functionality common to all instances of a class that will test cache implementations.

  package Cache::MyCacheTester;

  use vars qw( @ISA );
  use Cache::BaseCacheTester;

  @ISA = qw( Cache::BaseCacheTester );

METHODS

new( $base_test_count )

Construct a new BaseCacheTester and initialize the test count to $base_test_count.

ok( )

Print a message to stdout in the form "ok $test_count" and incremements the test count.

not_ok( $message )

Print a message to stdout in the form "not ok $test_count # $message " and incremements the test count.

skip( $message )

Print a message to stdout in the form "ok $test_count # skipped $message " and incremements the test count.

SEE ALSO

Cache::CacheTester, Cache::SizeAwareCacheTester

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::Cache -- the Cache interface.

  • USAGE
  • CONSTANTS
  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::Cache -- the Cache interface.

DESCRIPTION

The Cache modules are designed to assist a developer in persisting data for a specified period of time. Often these modules are used in web applications to store data locally to save repeated and redundant expensive calls to remote machines or databases. People have also been known to use Cache::Cache for its straightforward interface in sharing data between runs of an application or invocations of a CGI-style script or simply as an easy to use abstraction of the filesystem or shared memory.

The Cache::Cache interface is implemented by classes that support the get, set, remove, size, purge, and clear instance methods and their corresponding static methods for persisting data across method calls.

USAGE

First, choose the best type of cache implementation for your needs. The simplest cache is the MemoryCache, which is suitable for applications that are serving multiple sequential requests, and wish to avoid making redundant expensive queries, such as an Apache/mod_perl application talking to a database. If you wish to share that data between processes, then perhaps the SharedMemoryCache is appropriate, although its behavior is tightly bound to the underlying IPC mechanism, which varies from system to system, and is unsuitable for large objects or large numbers of objects. When the SharedMemoryCache is not acceptable, then FileCache offers all of the same functionality with similar performance metrics, and it is not limited in terms of the number of objects or their size. If you wish to maintain a strict limit on the size of a file system based cache, then the SizeAwareFileCache is the way to go. Similarly, the SizeAwareMemoryCache and the SizeAwareSharedMemoryCache add size management functionality to the MemoryCache and SharedMemoryCache classes respectively.

Using a cache is simple. Here is some sample code for instantiating and using a file system based cache.

  use Cache::FileCache;

  my $cache = new Cache::FileCache( );

  my $customer = $cache->get( $name );

  if ( not defined $customer )
  {
    $customer = get_customer_from_db( $name );
    $cache->set( $name, $customer, "10 minutes" );
  }

  return $customer;

CONSTANTS

$EXPIRES_NEVER

The item being set in the cache will never expire.

$EXPIRES_NOW

The item being set in the cache will expire immediately.

METHODS

Clear( )

Remove all objects from all caches of this type.

Purge( )

Remove all objects that have expired from all caches of this type.

Size( )

Returns the total size of all objects in all caches of this type.

new( $options_hash_ref )

Construct a new instance of a Cache::Cache. $options_hash_ref is a reference to a hash containing configuration options; see the section OPTIONS below.

clear( )

Remove all objects from the namespace associated with this cache instance.

get( $key )

Returns the data associated with $key.

get_object( $key )

Returns the underlying Cache::Object object used to store the cached data associated with $key. This will not trigger a removal of the cached object even if the object has expired.

purge( )

Remove all objects that have expired from the namespace associated with this cache instance.

remove( $key )

Delete the data associated with the $key from the cache.

set( $key, $data, [$expires_in] )

Associates $data with $key in the cache. $expires_in indicates the time in seconds until this data should be erased, or the constant $EXPIRES_NOW, or the constant $EXPIRES_NEVER. Defaults to $EXPIRES_NEVER. This variable can also be in the extended format of "[number] [unit]", e.g., "10 minutes". The valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w, week, weeks, M, month, months, y, year, and years. Additionally, $EXPIRES_NOW can be represented as "now" and $EXPIRES_NEVER can be represented as "never".

set_object( $key, $object )

Associates $key with Cache::Object $object. Using set_object (as opposed to set) does not trigger an automatic removal of expired objects.

size( )

Returns the total size of all objects in the namespace associated with this cache instance.

get_namespaces( )

Returns all the namespaces associated with this type of cache.

OPTIONS

The options are set by passing in a reference to a hash containing any of the following keys:

namespace

The namespace associated with this cache. Defaults to "Default" if not explicitly set.

default_expires_in

The default expiration time for objects place in the cache. Defaults to $EXPIRES_NEVER if not explicitly set.

auto_purge_interval

Sets the auto purge interval. If this option is set to a particular time ( in the same format as the expires_in ), then the purge( ) routine will be called during the first set after the interval expires. The interval will then be reset.

auto_purge_on_set

If this option is true, then the auto purge interval routine will be checked on every set.

auto_purge_on_get

If this option is true, then the auto purge interval routine will be checked on every get. This is probably not the desired behavior, as the purge could be a very expensive operation.

PROPERTIES

(get|set)_namespace( )

The namespace of this cache instance

get_default_expires_in( )

The default expiration time for objects placed in this cache instance

get_keys( )

The list of keys specifying objects in the namespace associated with this cache instance

get_identifiers( )

This method has been deprecated in favor of get_keys( ).

(get|set)_auto_purge_interval( )

Accesses the auto purge interval. If this option is set to a particular time ( in the same format as the expires_in ), then the purge( ) routine will be called during the first get after the interval expires. The interval will then be reset.

(get|set)_auto_purge_on_set( )

If this property is true, then the auto purge interval routine will be checked on every set.

(get|set)_auto_purge_on_get( )

If this property is true, then the auto purge interval routine will be checked on every get.

SEE ALSO

Cache::Object, Cache::MemoryCache, Cache::FileCache, Cache::SharedMemoryCache, and Cache::SizeAwareFileCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::CacheMetaData -- data about objects in the cache

  • METHODS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::CacheMetaData -- data about objects in the cache

DESCRIPTION

The CacheMetaData object is used by size aware caches to keep track of the state of the cache and effeciently return information such as an objects size or an ordered list of indentifiers to be removed when a cache size is being limited. End users will not normally use CacheMetaData directly.

SYNOPSIS

 use Cache::CacheMetaData;

 my $cache_meta_data = new Cache::CacheMetaData( );

 foreach my $key ( $cache->get_keys( ) )
 {
    my $object = $cache->get_object( $key ) or
      next;

    $cache_meta_data->insert( $object );
      }

 my $current_size = $cache_meta_data->get_cache_size( );

 my @removal_list = $cache_meta_data->build_removal_list( );

METHODS

new( )

Construct a new Cache::CacheMetaData object

insert( $object )

Inform the CacheMetaData about the object $object in the cache.

remove( $key )

Inform the CacheMetaData that the object specified by $key is no longer in the cache.

build_removal_list( )

Create a list of the keys in the cache, ordered as follows:

1) objects that expire now

2) objects expiring at a particular time, with ties broken by the time at which they were least recently accessed

3) objects that never expire, sub ordered by the time at which they were least recently accessed

NOTE: This could be improved further by taking the size into account on accessed_at ties. However, this type of tie is unlikely in normal usage.

build_object_size( $key )

Return the size of an object specified by $key.

PROPERTIES

get_cache_size

The total size of the objects in the cache

SEE ALSO

Cache::Cache, Cache::CacheSizer, Cache::SizeAwareCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::CacheSizer -- component object for mamanging the size of caches

  • METHODS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::CacheSizer -- component object for mamanging the size of caches

DESCRIPTION

The CacheSizer class is used internally in SizeAware caches such as SizeAwareFileCache to encapsulate the logic of limiting cache size.

SYNOPSIS

  use Cache::CacheSizer;

  my $sizer = new Cache::CacheSizer( $cache, $max_size );

  $sizer->limit_size( $new_size );

METHODS

new( $cache, $max_size )

Construct a new Cache::CacheSizer object for the cache $cache with a maximum size of $max_size.

update_access_time( $key )

Inform the cache that the object specified by $key has been accessed.

limit_size( $new_size )

Use the sizing algorithms to get the cache down under $new_size if possible.

PROPERTIES

get_max_size

The desired size limit for the cache under control.

SEE ALSO

Cache::Cache, Cache::CacheMetaData, Cache::SizeAwareCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::CacheTester -- a class for regression testing caches

  • METHODS
  • SEE ALSO
  • AUTHOR

NAME

Cache::CacheTester -- a class for regression testing caches

DESCRIPTION

The CacheTester is used to verify that a cache implementation honors its contract.

SYNOPSIS

  use Cache::MemoryCache;
  use Cache::CacheTester;

  my $cache = new Cache::MemoryCache( );

  my $cache_tester = new Cache::CacheTester( 1 );

  $cache_tester->test( $cache );

METHODS

new( $initial_count )

Construct a new CacheTester object, with the counter starting at $initial_count.

test( )

Run the tests.

SEE ALSO

Cache::Cache, Cache::BaseCacheTester

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::CacheUtils -- miscellaneous utility routines

  • AUTHOR

NAME

Cache::CacheUtils -- miscellaneous utility routines

DESCRIPTION

The CacheUtils package is a collection of static methods that provide functionality useful to many different classes.

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::FileBackend -- a filesystem based persistance mechanism

  • METHODS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::FileBackend -- a filesystem based persistance mechanism

DESCRIPTION

The FileBackend class is used to persist data to the filesystem

SYNOPSIS

  my $backend = new Cache::FileBackend( '/tmp/FileCache', 3, 000 );

  See Cache::Backend for the usage synopsis.
  $backend->store( 'namespace', 'foo', 'bar' );

  my $bar = $backend->restore( 'namespace', 'foo' );

  my $size_of_bar = $backend->get_size( 'namespace', 'foo' );

  foreach my $key ( $backend->get_keys( 'namespace' ) )
  {
    $backend->delete_key( 'namespace', $key );
  }

  foreach my $namespace ( $backend->get_namespaces( ) )
  {
    $backend->delete_namespace( $namespace );
  }

METHODS

See Cache::Backend for the API documentation.

new( $root, $depth, $directory_umask )

Construct a new FileBackend that writes data to the $root directory, automatically creates subdirectories $depth levels deep, and uses the umask of $directory_umask when creating directories.

PROPERTIES

(get|set)_root

The location of the parent directory in which to store the files

(get|set)_depth

The branching factor of the subdirectories created to store the files

(get|set)_directory_umask

The umask to be used when creating directories

SEE ALSO

Cache::Backend, Cache::MemoryBackend, Cache::SharedMemoryBackend

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::FileCache -- implements the Cache interface.

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::FileCache -- implements the Cache interface.

DESCRIPTION

The FileCache class implements the Cache interface. This cache stores data in the filesystem so that it can be shared between processes.

SYNOPSIS

  use Cache::FileCache;

  my $cache = new Cache::FileCache( { 'namespace' => 'MyNamespace',
                                      'default_expires_in' => 600 } );

  See Cache::Cache for the usage synopsis.

METHODS

See Cache::Cache for the API documentation.

Clear( [$cache_root] )

See Cache::Cache, with the optional $cache_root parameter.

Purge( [$cache_root] )

See Cache::Cache, with the optional $cache_root parameter.

Size( [$cache_root] )

See Cache::Cache, with the optional $cache_root parameter.

OPTIONS

See Cache::Cache for standard options. Additionally, options are set by passing in a reference to a hash containing any of the following keys:

cache_root

The location in the filesystem that will hold the root of the cache. Defaults to the 'FileCache' under the OS default temp directory ( often '/tmp' on UNIXes ) unless explicitly set.

cache_depth

The number of subdirectories deep to cache object item. This should be large enough that no cache directory has more than a few hundred objects. Defaults to 3 unless explicitly set.

directory_umask

The directories in the cache on the filesystem should be globally writable to allow for multiple users. While this is a potential security concern, the actual cache entries are written with the user's umask, thus reducing the risk of cache poisoning. If you desire it to only be user writable, set the 'directory_umask' option to '077' or similar. Defaults to '000' unless explicitly set.

PROPERTIES

See Cache::Cache for default properties.

(get|set)_cache_root

See the definition above for the option cache_root

(get|set)_cache_depth

See the definition above for the option cache_depth

(get|set)_directory_umask

See the definition above for the option directory_umask

SEE ALSO

Cache::Cache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::MemoryBackend -- a memory based persistance mechanism

  • METHODS
  • SEE ALSO
  • AUTHOR

NAME

Cache::MemoryBackend -- a memory based persistance mechanism

DESCRIPTION

The MemoryBackend class is used to persist data to memory

SYNOPSIS

  my $backend = new Cache::MemoryBackend( );

  See Cache::Backend for the usage synopsis.

METHODS

See Cache::Backend for the API documentation.

SEE ALSO

Cache::Backend, Cache::FileBackend, Cache::ShareMemoryBackend

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::MemoryCache -- implements the Cache interface.

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::MemoryCache -- implements the Cache interface.

DESCRIPTION

The MemoryCache class implements the Cache interface. This cache stores data on a per-process basis. This is the fastest of the cache implementations, but data can not be shared between processes with the MemoryCache. However, the data will remain in the cache until cleared, it expires, or the process dies. The cache object simply going out of scope will not destroy the data.

SYNOPSIS

  use Cache::MemoryCache;

  my $cache = new Cache::MemoryCache( { 'namespace' => 'MyNamespace',
                                        'default_expires_in' => 600 } );

  See Cache::Cache for the usage synopsis.

METHODS

See Cache::Cache for the API documentation.

OPTIONS

See Cache::Cache for standard options.

PROPERTIES

See Cache::Cache for default properties.

SEE ALSO

Cache::Cache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::NullCache -- implements the Cache interface.

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::NullCache -- implements the Cache interface.

DESCRIPTION

The NullCache class implements the Cache::Cache interface, but does not actually persist data. This is useful when developing and debugging a system and you wish to easily turn off caching. As a result, all calls to get and get_object will return undef.

SYNOPSIS

  use Cache::NullCache;

  my $cache = new Cache::NullCache( );

  See Cache::Cache for the usage synopsis.

METHODS

See Cache::Cache for the API documentation.

OPTIONS

See Cache::Cache for standard options.

PROPERTIES

See Cache::Cache for default properties.

SEE ALSO

Cache::Cache

AUTHOR

Original author: Jay Sachs

Last author: $Author: dclinton $

Copyright (C) 2001 Jay Sachs, 2002 DeWitt Clinton


Cache::Object -- the data stored in a Cache.

  • METHODS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::Object -- the data stored in a Cache.

DESCRIPTION

Object is used by classes implementing the Cache interface as an object oriented wrapper around the data. End users will not normally use Object directly, but it can be retrieved via the get_object method on the Cache::Cache interface.

SYNOPSIS

 use Cache::Object;

 my $object = new Cache::Object( );

 $object->set_key( $key );
 $object->set_data( $data );
 $object->set_expires_at( $expires_at );
 $object->set_created_at( $created_at );

METHODS

new( )

Construct a new Cache::Object.

PROPERTIES

(get|set)_accessed_at

The time at which the object was last accessed. Various cache implementations will use the accessed_at property to store information for LRU algorithms. There is no guarentee that all caches will update this field, however.

(get|set)_created_at

The time at which the object was created.

(get|set)_data

A scalar containing or a reference pointing to the data to be stored.

(get|set)_expires_at

The time at which the object should expire from the cache.

(get|set)_key

The key under which the object was stored.

(get|set)_size

The size of the frozen version of this object

SEE ALSO

Cache::Cache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SharedMemoryBackend -- a shared memory based persistance mechanism

  • METHODS
  • SEE ALSO
  • AUTHOR

NAME

Cache::SharedMemoryBackend -- a shared memory based persistance mechanism

DESCRIPTION

The SharedMemoryBackend class is used to persist data to shared memory

SYNOPSIS

  my $backend = new Cache::SharedMemoryBackend( );

  See Cache::Backend for the usage synopsis.

METHODS

See Cache::Backend for the API documentation.

SEE ALSO

Cache::Backend, Cache::FileBackend, Cache::ShareMemoryBackend

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SharedMemoryCache -- extends the MemoryCache.

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::SharedMemoryCache -- extends the MemoryCache.

DESCRIPTION

The SharedMemoryCache extends the MemoryCache class and binds the data store to shared memory so that separate process can use the same cache.

The official recommendation is now to use FileCache instead of SharedMemoryCache. The reasons for this include:

1) FileCache provides equal or better performance in all cases that we've been able to test. This is due to all modern OS's ability to buffer and cache file system accesses very well.

2) FileCache has no real limits on cached object size or the number of cached objects, whereas the SharedMemoryCache has limits, and rather low ones at that.

3) FileCache works well on every OS, whereas the SharedMemoryCache works only on systems that support IPC::ShareLite. And IPC::ShareLite is an impressive effort -- but think about how hard it is to get shared memory working properly on *one* system. Now imagine writing a wrapper around shared memory for many operating systems.

SYNOPSIS

  use Cache::SharedMemoryCache;

  my %cache_options_= ( 'namespace' => 'MyNamespace',
                        'default_expires_in' => 600 );

  my $shared_memory_cache =
    new Cache::SharedMemoryCache( \%cache_options ) or
      croak( "Couldn't instantiate SharedMemoryCache" );

METHODS

See Cache::Cache for the API documentation.

OPTIONS

See Cache::Cache for the standard options.

PROPERTIES

See Cache::Cache for the default properties.

SEE ALSO

Cache::Cache, Cache::MemoryCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SizeAwareCache -- extends the Cache interface.

  • CONSTANTS
  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::SizeAwareCache -- extends the Cache interface.

DESCRIPTION

The SizeAwareCache interface is implemented by classes that support all of the Cache::Cache interface in addition to the limit_size and max_size features of a size aware cache.

The default cache size limiting algorithm works by removing cache objects in the following order until the desired limit is reached:

  1) objects that have expired
  2) objects that are least recently accessed
  3) objects that that expire next

SYNOPSIS

  use Cache::SizeAwareCache;
  use vars qw( @ISA );

  @ISA = qw( Cache::SizeAwareCache );

CONSTANTS

Please see Cache::Cache for standard constants

$NO_MAX_SIZE

The cache has no size restrictions

METHODS

Please see Cache::Cache for the standard methods

limit_size( $new_size )

Attempt to resize the cache such that the total disk usage is under the $new_size parameter. $new_size represents t size (in bytes) that the cache should be limited to. Note that this is only a one time adjustment. To maintain the cache size, consider using the max_size option, although it is considered very expensive, and can often be better achieved by peridocally calling limit_size.

OPTIONS

Please see Cache::Cache for the standard options

max_size

Sets the max_size property (size in bytes), which is described in detail below. Defaults to $NO_MAX_SIZE.

PROPERTIES

Please see Cache::Cache for standard properties

(get|set)_max_size

If this property is set, then the cache will try not to exceed the max size value (in bytes) specified. NOTE: This causes the size of the cache to be checked on every set, and can be considered *very* expensive in some implementations. A good alternative approach is leave max_size as $NO_MAX_SIZE and to periodically limit the size of the cache by calling the limit_size( $size ) method.

SEE ALSO

Cache::Cache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SizeAwareCacheTester -- a class for regression testing size aware caches

  • METHODS
  • SEE ALSO
  • AUTHOR

NAME

Cache::SizeAwareCacheTester -- a class for regression testing size aware caches

DESCRIPTION

The SizeCacheTester is used to verify that a cache implementation honors its contract with respect to resizing capabilities

SYNOPSIS

  use Cache::SizeAwareMemoryCache;
  use Cache::SizeAwareCacheTester;

  my $cache = new Cache::SizeAwareMemoryCache( );

  my $cache_tester = new Cache::SizeAwareCacheTester( 1 );

  $cache_tester->test( $cache );

METHODS

new( $initial_count )

Construct a new SizeAwareCacheTester object, with the counter starting at $initial_count.

test( )

Run the tests.

SEE ALSO

Cache::Cache, Cache::BaseCacheTester, Cache::CacheTester

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SizeAwareFileCache -- extends Cache::FileCache

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::SizeAwareFileCache -- extends Cache::FileCache

DESCRIPTION

The SizeAwareFileCache class adds the ability to dynamically limit the size (in bytes) of a file system based cache. This class also implements the SizeAwareCache interface, providing the 'max_size' option and the 'limit_size( $size )' method.

SYNOPSIS

  use Cache::SizeAwareFileCache;

  my $cache =
    new Cache::SizeAwareFileCache( { 'namespace' => 'MyNamespace',
                                     'default_expires_in' => 600,
                                     'max_size' => 10000 } );

METHODS

See Cache::Cache and Cache::SizeAwareCache for the API documentation.

OPTIONS

See Cache::Cache and Cache::SizeAwareCache for the standard options.

PROPERTIES

See Cache::Cache and Cache::SizeAwareCache for the default properties.

SEE ALSO

Cache::Cache, Cache::SizeAwareCache, Cache::FileCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Also: Portions of this code are a rewrite of David Coppit's excellent extentions to the original File::Cache

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SizeAwareMemoryCache -- extends Cache::MemoryCache

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::SizeAwareMemoryCache -- extends Cache::MemoryCache

DESCRIPTION

The SizeAwareMemoryCache class adds the ability to dynamically limit the size (in bytes) of a memory based cache. This class also implements the SizeAwareCache interface, providing the 'max_size' option and the 'limit_size( $size )' method.

SYNOPSIS

  use Cache::SizeAwareMemoryCache;

  my $cache =
    new Cache::SizeAwareMemoryCache( { 'namespace' => 'MyNamespace',
                                       'default_expires_in' => 600,
                                       'max_size' => 10000 } );

METHODS

See Cache::Cache and Cache::SizeAwareCache for the API documentation.

OPTIONS

See Cache::Cache and Cache::SizeAwareCache for the standard options.

PROPERTIES

See Cache::Cache and Cache::SizeAwareCache for the default properties.

SEE ALSO

Cache::Cache, Cache::SizeAwareCache, Cache::MemoryCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


Cache::SizeAwareSharedMemoryCache -- extends Cache::SizeAwareMemoryCache

  • METHODS
  • OPTIONS
  • PROPERTIES
  • SEE ALSO
  • AUTHOR

NAME

Cache::SizeAwareSharedMemoryCache -- extends Cache::SizeAwareMemoryCache

DESCRIPTION

The SizeAwareSharedMemoryCache class adds the ability to dynamically limit the size (in bytes) of a shared memory based cache. This class also implements the SizeAwareCache interface, providing the 'max_size' option and the 'limit_size( $size )' method.

SYNOPSIS

  use Cache::SizeAwareSharedMemoryCache;

  my $cache =
    new Cache::SizeAwareSharedMemoryCache( { 'namespace' => 'MyNamespace',
                                             'default_expires_in' => 600,
                                             'max_size' => 10000 } );

METHODS

See Cache::Cache and Cache::SizeAwareCache for the API documentation.

OPTIONS

See Cache::Cache and Cache::SizeAwareCache for the standard options.

PROPERTIES

See Cache::Cache and Cache::SizeAwareCache for the default properties.

SEE ALSO

Cache::Cache, Cache::SizeAwareCache, Cache::SharedMemoryCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001-2003 DeWitt Clinton


carp - warn of errors

    • Forcing a Stack Trace
  • GLOBAL VARIABLES
    • $Carp::CarpLevel
    • $Carp::MaxEvalLen
    • $Carp::MaxArgLen
    • $Carp::MaxArgNums
    • $Carp::Verbose
  • BUGS

NAME

carp - warn of errors (from perspective of caller)

cluck - warn of errors with stack backtrace (not exported by default)

croak - die of errors (from perspective of caller)

confess - die of errors with stack backtrace

shortmess - return the message that carp and croak produce

longmess - return the message that cluck and confess produce

SYNOPSIS

    use Carp;
    croak "We're outta here!";

    use Carp qw(cluck);
    cluck "This is how we got here!";

    print FH Carp::shortmess("This will have caller's details added");
    print FH Carp::longmess("This will have stack backtrace added");

DESCRIPTION

The Carp routines are useful in your own modules because they act like die() or warn(), but with a message which is more likely to be useful to a user of your module. In the case of cluck, confess, and longmess that context is a summary of every call in the call-stack. For a shorter message you can use carp, croak or shortmess which report the error as being from where your module was called. There is no guarantee that that is where the error was, but it is a good educated guess.

You can also alter the way the output and logic of Carp works, by changing some global variables in the Carp namespace. See the section on GLOBAL VARIABLES below.

Here is a more complete description of how shortmess works. What it does is search the call-stack for a function call stack where it hasn't been told that there shouldn't be an error. If every call is marked safe, it then gives up and gives a full stack backtrace instead. In other words it presumes that the first likely looking potential suspect is guilty. Its rules for telling whether a call shouldn't generate errors work as follows:

  1. Any call from a package to itself is safe.

  2. Packages claim that there won't be errors on calls to or from packages explicitly marked as safe by inclusion in @CARP_NOT, or (if that array is empty) @ISA. The ability to override what @ISA says is new in 5.8.

  3. The trust in item 2 is transitive. If A trusts B, and B trusts C, then A trusts C. So if you do not override @ISA with @CARP_NOT, then this trust relationship is identical to, "inherits from".

  4. Any call from an internal Perl module is safe. (Nothing keeps user modules from marking themselves as internal to Perl, but this practice is discouraged.)

  5. Any call to Carp is safe. (This rule is what keeps it from reporting the error where you call carp/croak/shortmess.)

Forcing a Stack Trace

As a debugging aid, you can force Carp to treat a croak as a confess and a carp as a cluck across all modules. In other words, force a detailed stack trace to be given. This can be very helpful when trying to understand why, or from where, a warning or error is being generated.

This feature is enabled by 'importing' the non-existent symbol 'verbose'. You would typically enable it by saying

    perl -MCarp=verbose script.pl

or by including the string MCarp=verbose in the PERL5OPT environment variable.

Alternately, you can set the global variable $Carp::Verbose to true. See the GLOBAL VARIABLES section below.

GLOBAL VARIABLES

$Carp::CarpLevel

This variable determines how many call frames are to be skipped when reporting where an error occurred on a call to one of Carp's functions. For example:

    $Carp::CarpLevel = 1;
    sub bar     { .... or _error('Wrong input') }
    sub _error  { Carp::carp(@_) }

This would make Carp report the error as coming from bar's caller, rather than from _error's caller, as it normally would.

Defaults to 0.

$Carp::MaxEvalLen

This variable determines how many characters of a string-eval are to be shown in the output. Use a value of 0 to show all text.

Defaults to 0.

$Carp::MaxArgLen

This variable determines how many characters of each argument to a function to print. Use a value of 0 to show the full length of the argument.

Defaults to 64.

$Carp::MaxArgNums

This variable determines how many arguments to each function to show. Use a value of 0 to show all arguments to a function call.

Defaults to 8.

$Carp::Verbose

This variable makes Carp use the longmess function at all times. This effectively means that all calls to carp become cluck and all calls to croak become confess.

Note, this is analogous to using use Carp 'verbose'.

Defaults to 0.

BUGS

The Carp routines don't handle exception objects currently. If called with a first argument that is a reference, they simply call die() or warn(), as appropriate.


Carp::Heavy - heavy machinery, no user serviceable parts inside

  • NAME

NAME

Carp::Heavy - heavy machinery, no user serviceable parts inside


Class::Container - Glues object frameworks together transparently

    • Scenario
  • METHODS
    • new()
    • __PACKAGE__->contained_objects()
    • __PACKAGE__->valid_params(...)
    • $self->create_delayed_object()
    • $self->delayed_object_params($name, [params])
    • $self->delayed_object_class($name)
    • __PACKAGE__->decorates()
    • $self->validation_spec()
    • $class->allowed_params(\%args)
    • $self->container()
    • $object->show_containers
    • $package->show_containers
    • $object->dump_parameters
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Class::Container - Glues object frameworks together transparently

SYNOPSIS

 package Car;
 use Class::Container;
 @ISA = qw(Class::Container);

 __PACKAGE__->valid_params
   (
    paint  => {default => 'burgundy'},
    style  => {default => 'coupe'},
    windshield => {isa => 'Glass'},
    radio  => {isa => 'Audio::Device'},
   );

 __PACKAGE__->contained_objects
   (
    windshield => 'Glass::Shatterproof',
    wheel      => { class => 'Vehicle::Wheel',
                    delayed => 1 },
    radio      => 'Audio::MP3',
   );

 sub new {
   my $package = shift;

   # 'windshield' and 'radio' objects are created automatically by
   # SUPER::new()
   my $self = $package->SUPER::new(@_);

   $self->{right_wheel} = $self->create_delayed_object('wheel');
   ... do any more initialization here ...
   return $self;
 }

DESCRIPTION

This class facilitates building frameworks of several classes that inter-operate. It was first designed and built for HTML::Mason, in which the Compiler, Lexer, Interpreter, Resolver, Component, Buffer, and several other objects must create each other transparently, passing the appropriate parameters to the right class, possibly substituting other subclasses for any of these objects.

The main features of Class::Container are:

  • Explicit declaration of containment relationships (aggregation, factory creation, etc.)

  • Declaration of constructor parameters accepted by each member in a class framework

  • Transparent passing of constructor parameters to the class that needs them

  • Ability to create one (automatic) or many (manual) contained objects automatically and transparently

Scenario

Suppose you've got a class called Parent, which contains an object of the class Child, which in turn contains an object of the class GrandChild. Each class creates the object that it contains. Each class also accepts a set of named parameters in its new() method. Without using Class::Container, Parent will have to know all the parameters that Child takes, and Child will have to know all the parameters that GrandChild takes. And some of the parameters accepted by Parent will really control aspects of Child or GrandChild. Likewise, some of the parameters accepted by Child will really control aspects of GrandChild. So, what happens when you decide you want to use a GrandDaughter class instead of the generic GrandChild? Parent and Child must be modified accordingly, so that any additional parameters taken by GrandDaughter can be accommodated. This is a pain - the kind of pain that object-oriented programming was supposed to shield us from.

Now, how can Class::Container help? Using Class::Container, each class (Parent, Child, and GrandChild) will declare what arguments they take, and declare their relationships to the other classes (Parent creates/contains a Child, and Child creates/contains a GrandChild). Then, when you create a Parent object, you can pass Parent->new() all the parameters for all three classes, and they will trickle down to the right places. Furthermore, Parent and Child won't have to know anything about the parameters of its contained objects. And finally, if you replace GrandChild with GrandDaughter, no changes to Parent or Child will likely be necessary.

METHODS

new()

Any class that inherits from Class::Container should also inherit its new() method. You can do this simply by omitting it in your class, or by calling SUPER::new(@_) as indicated in the SYNOPSIS. The new() method ensures that the proper parameters and objects are passed to the proper constructor methods.

At the moment, the only possible constructor method is new(). If you need to create other constructor methods, they should call new() internally.

__PACKAGE__->contained_objects()

This class method is used to register what other objects, if any, a given class creates. It is called with a hash whose keys are the parameter names that the contained class's constructor accepts, and whose values are the default class to create an object of.

For example, consider the HTML::Mason::Compiler class, which uses the following code:

  __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

This defines the relationship between the HTML::Mason::Compiler class and the class it creates to go in its lexer slot. The HTML::Mason::Compiler class "has a" lexer. The < HTML::Mason::Compiler-new() >> method will accept a lexer parameter and, if no such parameter is given, an object of the HTML::Mason::Lexer class should be constructed.

We implement a bit of magic here, so that if < HTML::Mason::Compiler-new() >> is called with a lexer_class parameter, it will load the indicated class (presumably a subclass of HTML::Mason::Lexer), instantiate a new object of that class, and use it for the Compiler's lexer object. We're also smart enough to notice if parameters given to HTML::Mason::Compiler->new() actually should go to the lexer contained object, and it will make sure that they get passed along.

Furthermore, an object may be declared as "delayed", which means that an object won't be created when its containing class is constructed. Instead, these objects will be created "on demand", potentially more than once. The constructors will still enjoy the automatic passing of parameters to the correct class. See the create_delayed_object() for more.

To declare an object as "delayed", call this method like this:

  __PACKAGE__->contained_objects( train => { class => 'Big::Train',
                                             delayed => 1 } );

__PACKAGE__->valid_params(...)

Specifies the parameters accepted by this class's new() method as a set of key/value pairs. Any parameters accepted by a superclass/subclass will also be accepted, as well as any parameters accepted by contained objects. This method is a get/set accessor method, so it returns a reference to a hash of these key/value pairs. As a special case, if you wish to set the valid params to an empty set and you previously set it to a non-empty set, you may call __PACKAGE__->valid_params(undef).

valid_params() is called with a hash that contains parameter names as its keys and validation specifications as values. This validation specification is largely the same as that used by the Params::Validate module, because we use Params::Validate internally.

As an example, consider the following situation:

  use Class::Container;
  use Params::Validate qw(:types);
  __PACKAGE__->valid_params
      (
       allow_globals        => { type => ARRAYREF, parse => 'list',   default => [] },
       default_escape_flags => { type => SCALAR,   parse => 'string', default => '' },
       lexer                => { isa => 'HTML::Mason::Lexer' },
       preprocess           => { type => CODEREF,  parse => 'code',   optional => 1 },
       postprocess_perl     => { type => CODEREF,  parse => 'code',   optional => 1 },
       postprocess_text     => { type => CODEREF,  parse => 'code',   optional => 1 },
      );

  __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

The type, default, and optional parameters are part of the validation specification used by Params::Validate. The various constants used, ARRAYREF, SCALAR, etc. are all exported by Params::Validate. This means that any of these six parameter names, plus the lexer_class parameter (because of the contained_objects() specification given earlier), are valid arguments to the Compiler's new() method.

Note that there are also some parse attributes declared. These have nothing to do with Class::Container or Params::Validate - any extra entries like this are simply ignored, so you are free to put extra information in the specifications as long as it doesn't overlap with what Class::Container or Params::Validate are looking for.

$self->create_delayed_object()

If a contained object was declared with delayed => 1, use this method to create an instance of the object. Note that this is an object method, not a class method:

   my $foo =       $self->create_delayed_object('foo', ...); # YES!
   my $foo = __PACKAGE__->create_delayed_object('foo', ...); # NO!

The first argument should be a key passed to the contained_objects() method. Any additional arguments will be passed to the new() method of the object being created, overriding any parameters previously passed to the container class constructor. (Could I possibly be more alliterative? Veni, vedi, vici.)

$self->delayed_object_params($name, [params])

Allows you to adjust the parameters that will be used to create any delayed objects in the future. The first argument specifies the "name" of the object, and any additional arguments are key-value pairs that will become parameters to the delayed object.

When called with only a $name argument and no list of parameters to set, returns a hash reference containing the parameters that will be passed when creating objects of this type.

$self->delayed_object_class($name)

Returns the class that will be used when creating delayed objects of the given name. Use this sparingly - in most situations you shouldn't care what the class is.

__PACKAGE__->decorates()

Version 0.09 of Class::Container added [as yet experimental] support for so-called "decorator" relationships, using the term as defined in Design Patterns by Gamma, et al. (the Gang of Four book). To declare a class as a decorator of another class, simply set @ISA to the class which will be decorated, and call the decorator class's decorates() method.

Internally, this will ensure that objects are instantiated as decorators. This means that you can mix & match extra add-on functionality classes much more easily.

In the current implementation, if only a single decoration is used on an object, it will be instantiated as a simple subclass, thus avoiding a layer of indirection.

$self->validation_spec()

Returns a hash reference suitable for passing to the Params::Validate validate function. Does not include any arguments that can be passed to contained objects.

$class->allowed_params(\%args)

Returns a hash reference of every parameter this class will accept, including parameters it will pass on to its own contained objects. The keys are the parameter names, and the values are their corresponding specifications from their valid_params() definitions. If a parameter is used by both the current object and one of its contained objects, the specification returned will be from the container class, not the contained.

Because the parameters accepted by new() can vary based on the parameters passed to new(), you can pass any parameters to the allowed_params() method too, ensuring that the hash you get back is accurate.

$self->container()

Returns the object that created you. This is remembered by storing a reference to that object, so we use the Scalar::Utils weakref() function to avoid persistent circular references that would cause memory leaks. If you don't have Scalar::Utils installed, we don't make these references in the first place, and calling container() will result in a fatal error.

If you weren't created by another object via Class::Container, container() returns undef.

In most cases you shouldn't care what object created you, so use this method sparingly.

$object->show_containers

$package->show_containers

This method returns a string meant to describe the containment relationships among classes. You should not depend on the specific formatting of the string, because I may change things in a future release to make it prettier.

For example, the HTML::Mason code returns the following when you do $interp->show_containers:

 HTML::Mason::Interp=HASH(0x238944)
   resolver -> HTML::Mason::Resolver::File
   compiler -> HTML::Mason::Compiler::ToObject
     lexer -> HTML::Mason::Lexer
   request -> HTML::Mason::Request (delayed)
     buffer -> HTML::Mason::Buffer (delayed)

Currently, containment is shown by indentation, so the Interp object contains a resolver and a compiler, and a delayed request (or several delayed requests). The compiler contains a lexer, and each request contains a delayed buffer (or several delayed buffers).

$object->dump_parameters

Returns a hash reference containing a set of parameters that should be sufficient to re-create the given object using its class's new() method. This is done by fetching the current value for each declared parameter (i.e. looking in $object for hash entries of the same name), then recursing through all contained objects and doing the same.

A few words of caution here. First, the dumped parameters represent the current state of the object, not the state when it was originally created.

Second, a class's declared parameters may not correspond exactly to its data members, so it might not be possible to recover the former from the latter. If it's possible but requires some manual fudging, you can override this method in your class, something like so:

 sub dump_parameters {
   my $self = shift;
   my $dump = $self->SUPER::dump_parameters();

   # Perform fudgery
   $dump->{incoming} = $self->{_private};
   delete $dump->{superfluous};
   return $dump;
 }

SEE ALSO

the Params::Validate manpage

AUTHOR

Originally by Ken Williams <ken@mathforum.org> and Dave Rolsky <autarch@urth.org> for the HTML::Mason project. Important feedback contributed by Jonathan Swartz <swartz@pobox.com>. Extended by Ken Williams for the AI::Categorizer project.

Currently maintained by Ken Williams.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Class::Data::Inheritable - Inheritable, overridable class data

  • Methods
    • mk_classdata
  • AUTHOR
  • BUGS and QUERIES
  • COPYRIGHT and LICENSE
  • SEE ALSO

NAME

Class::Data::Inheritable - Inheritable, overridable class data

SYNOPSIS

  package Stuff;
  use base qw(Class::Data::Inheritable);

  # Set up DataFile as inheritable class data.
  Stuff->mk_classdata('DataFile');

  # Declare the location of the data file for this class.
  Stuff->DataFile('/etc/stuff/data');

  # Or, all in one shot:
  Stuff->mk_classdata(DataFile => '/etc/stuff/data');

DESCRIPTION

Class::Data::Inheritable is for creating accessor/mutators to class data. That is, if you want to store something about your class as a whole (instead of about a single object). This data is then inherited by your subclasses and can be overriden.

For example:

  Pere::Ubu->mk_classdata('Suitcase');

will generate the method Suitcase() in the class Pere::Ubu.

This new method can be used to get and set a piece of class data.

  Pere::Ubu->Suitcase('Red');
  $suitcase = Pere::Ubu->Suitcase;

The interesting part happens when a class inherits from Pere::Ubu:

  package Raygun;
  use base qw(Pere::Ubu);

  # Raygun's suitcase is Red.
  $suitcase = Raygun->Suitcase;

Raygun inherits its Suitcase class data from Pere::Ubu.

Inheritance of class data works analogous to method inheritance. As long as Raygun does not "override" its inherited class data (by using Suitcase() to set a new value) it will continue to use whatever is set in Pere::Ubu and inherit further changes:

  # Both Raygun's and Pere::Ubu's suitcases are now Blue
  Pere::Ubu->Suitcase('Blue');

However, should Raygun decide to set its own Suitcase() it has now "overridden" Pere::Ubu and is on its own, just like if it had overriden a method:

  # Raygun has an orange suitcase, Pere::Ubu's is still Blue.
  Raygun->Suitcase('Orange');

Now that Raygun has overridden Pere::Ubu futher changes by Pere::Ubu no longer effect Raygun.

  # Raygun still has an orange suitcase, but Pere::Ubu is using Samsonite.
  Pere::Ubu->Suitcase('Samsonite');

Methods

mk_classdata

  Class->mk_classdata($data_accessor_name);
  Class->mk_classdata($data_accessor_name => $value);

This is a class method used to declare new class data accessors. A new accessor will be created in the Class using the name from $data_accessor_name, and optionally initially setting it to the given value.

To facilitate overriding, mk_classdata creates an alias to the accessor, _field_accessor(). So Suitcase() would have an alias _Suitcase_accessor() that does the exact same thing as Suitcase(). This is useful if you want to alter the behavior of a single accessor yet still get the benefits of inheritable class data. For example.

  sub Suitcase {
      my($self) = shift;
      warn "Fashion tragedy" if @_ and $_[0] eq 'Plaid';

      $self->_Suitcase_accessor(@_);
        }

AUTHOR

Original code by Damian Conway.

Maintained by Michael G Schwern until September 2005.

Now maintained by Tony Bowden.

BUGS and QUERIES

Please direct all correspondence regarding this module to: bug-Class-Data-Inheritable@rt.cpan.org

COPYRIGHT and LICENSE

Copyright (c) 2000-2005, Damian Conway and Michael G Schwern. All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)

SEE ALSO

perltootc has a very elaborate discussion of class data in Perl.


Class::ISA -- report the search path for a class's ISA tree

  • FUNCTIONS
  • CAUTIONARY NOTES
  • COPYRIGHT
  • AUTHOR

NAME

Class::ISA -- report the search path for a class's ISA tree

SYNOPSIS

  # Suppose you go: use Food::Fishstick, and that uses and
  # inherits from other things, which in turn use and inherit
  # from other things.  And suppose, for sake of brevity of
  # example, that their ISA tree is the same as:

  @Food::Fishstick::ISA = qw(Food::Fish  Life::Fungus  Chemicals);
  @Food::Fish::ISA = qw(Food);
  @Food::ISA = qw(Matter);
  @Life::Fungus::ISA = qw(Life);
  @Chemicals::ISA = qw(Matter);
  @Life::ISA = qw(Matter);
  @Matter::ISA = qw();

  use Class::ISA;
  print "Food::Fishstick path is:\n ",
        join(", ", Class::ISA::super_path('Food::Fishstick')),
        "\n";

That prints:

  Food::Fishstick path is:
   Food::Fish, Food, Matter, Life::Fungus, Life, Chemicals

DESCRIPTION

Suppose you have a class (like Food::Fish::Fishstick) that is derived, via its @ISA, from one or more superclasses (as Food::Fish::Fishstick is from Food::Fish, Life::Fungus, and Chemicals), and some of those superclasses may themselves each be derived, via its @ISA, from one or more superclasses (as above).

When, then, you call a method in that class ($fishstick->calories), Perl first searches there for that method, but if it's not there, it goes searching in its superclasses, and so on, in a depth-first (or maybe "height-first" is the word) search. In the above example, it'd first look in Food::Fish, then Food, then Matter, then Life::Fungus, then Life, then Chemicals.

This library, Class::ISA, provides functions that return that list -- the list (in order) of names of classes Perl would search to find a method, with no duplicates.

FUNCTIONS

the function Class::ISA::super_path($CLASS)

This returns the ordered list of names of classes that Perl would search thru in order to find a method, with no duplicates in the list. $CLASS is not included in the list. UNIVERSAL is not included -- if you need to consider it, add it to the end.

the function Class::ISA::self_and_super_path($CLASS)

Just like super_path, except that $CLASS is included as the first element.

the function Class::ISA::self_and_super_versions($CLASS)

This returns a hash whose keys are $CLASS and its (super-)superclasses, and whose values are the contents of each class's $VERSION (or undef, for classes with no $VERSION).

The code for self_and_super_versions is meant to serve as an example for precisely the kind of tasks I anticipate that self_and_super_path and super_path will be used for. You are strongly advised to read the source for self_and_super_versions, and the comments there.

CAUTIONARY NOTES

* Class::ISA doesn't export anything. You have to address the functions with a "Class::ISA::" on the front.

* Contrary to its name, Class::ISA isn't a class; it's just a package. Strange, isn't it?

* Say you have a loop in the ISA tree of the class you're calling one of the Class::ISA functions on: say that Food inherits from Matter, but Matter inherits from Food (for sake of argument). If Perl, while searching for a method, actually discovers this cyclicity, it will throw a fatal error. The functions in Class::ISA effectively ignore this cyclicity; the Class::ISA algorithm is "never go down the same path twice", and cyclicities are just a special case of that.

* The Class::ISA functions just look at @ISAs. But theoretically, I suppose, AUTOLOADs could bypass Perl's ISA-based search mechanism and do whatever they please. That would be bad behavior, tho; and I try not to think about that.

* If Perl can't find a method anywhere in the ISA tree, it then looks in the magical class UNIVERSAL. This is rarely relevant to the tasks that I expect Class::ISA functions to be put to, but if it matters to you, then instead of this:

  @supers = Class::Tree::super_path($class);

do this:

  @supers = (Class::Tree::super_path($class), 'UNIVERSAL');

And don't say no-one ever told ya!

* When you call them, the Class::ISA functions look at @ISAs anew -- that is, there is no memoization, and so if ISAs change during runtime, you get the current ISA tree's path, not anything memoized. However, changing ISAs at runtime is probably a sign that you're out of your mind!

COPYRIGHT

Copyright (c) 1999, 2000 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Sean M. Burke sburke@cpan.org


Class::Inspector - Get information about a class and its structure

  • METHODS
    • installed $class
    • loaded $class
    • filename $class
    • resolved_filename $class, @try_first
    • loaded_filename $class
    • functions $class
    • function_refs $class
    • function_exists $class, $function
    • methods $class, @options
    • subclasses $class
  • TO DO
  • SUPPORT
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

Class::Inspector - Get information about a class and its structure

SYNOPSIS

  use Class::Inspector;

  # Is a class installed and/or loaded
  Class::Inspector->installed( 'Foo::Class' );
  Class::Inspector->loaded( 'Foo::Class' );

  # Filename related information
  Class::Inspector->filename( 'Foo::Class' );
  Class::Inspector->resolved_filename( 'Foo::Class' );

  # Get subroutine related information
  Class::Inspector->functions( 'Foo::Class' );
  Class::Inspector->function_refs( 'Foo::Class' );
  Class::Inspector->function_exists( 'Foo::Class', 'bar' );
  Class::Inspector->methods( 'Foo::Class', 'full', 'public' );

  # Find all loaded subclasses or something
  Class::Inspector->subclasses( 'Foo::Class' );

DESCRIPTION

Class::Inspector allows you to get information about a loaded class. Most or all of this information can be found in other ways, but they arn't always very friendly, and usually involve a relatively high level of Perl wizardry, or strange and unusual looking code. Class::Inspector attempts to provide an easier, more friendly interface to this information.

METHODS

installed $class

The installed static method tries to determine if a class is installed on the machine, or at least available to Perl. It does this by wrapping around resolved_filename.

Returns true if installed/available, false if the class is not installed, or undef if the class name is invalid.

loaded $class

The loaded static method tries to determine if a class is loaded by looking for symbol table entries.

This method it uses to determine this will work even if the class does not have its own file, but is contained inside a single file with multiple classes in it. Even in the case of some sort of run-time loading class being used, these typically leave some trace in the symbol table, so an Autoload or the Class::Autouse manpage-based class should correctly appear loaded.

Returns true if the class is loaded, false if not, or undef if the class name is invalid.

filename $class

For a given class, returns the base filename for the class. This will NOT be a fully resolved filename, just the part of the filename BELOW the @INC entry.

  print Class->filename( 'Foo::Bar' );
  > Foo/Bar.pm

This filename will be returned with the right seperator for the local platform, and should work on all platforms.

Returns the filename on success or undef if the class name is invalid.

resolved_filename $class, @try_first

For a given class, the resolved_filename static method returns the fully resolved filename for a class. That is, the file that the class would be loaded from.

This is not nescesarily the file that the class WAS loaded from, as the value returned is determined each time it runs, and the @INC include path may change.

To get the actual file for a loaded class, see the loaded_filename method.

Returns the filename for the class, or undef if the class name is invalid.

loaded_filename $class

For a given loaded class, the loaded_filename static method determines (via the %INC hash) the name of the file that it was originally loaded from.

Returns a resolved file path, or false if the class did not have it's own file.

functions $class

For a loaded class, the functions static method returns a list of the names of all the functions in the classes immediate namespace.

Note that this is not the METHODS of the class, just the functions.

Returns a reference to an array of the function names on success, or undef if the class name is invalid or the class is not loaded.

function_refs $class

For a loaded class, the function_refs static method returns references to all the functions in the classes immediate namespace.

Note that this is not the METHODS of the class, just the functions.

Returns a reference to an array of CODE refs of the functions on success, or undef if the class is not loaded.

function_exists $class, $function

Given a class and function name the function_exists static method will check to see if the function exists in the class.

Note that this is as a function, not as a method. To see if a method exists for a class, use the can method for any class or object.

Returns true if the function exists, false if not, or undef if the class or function name are invalid, or the class is not loaded.

methods $class, @options

For a given class name, the methods static method will returns ALL the methods available to that class. This includes all methods available from every class up the class' @ISA tree.

Returns a reference to an array of the names of all the available methods on success, or undef if the class name is invalid or the class is not loaded.

A number of options are available to the methods method that will alter the results returned. These should be listed after the class name, in any order.

  # Only get public methods
  my $method = Class::Inspector->methods( 'My::Class', 'public' );
public

The public option will return only 'public' methods, as defined by the Perl convention of prepending an underscore to any 'private' methods. The public option will effectively remove any methods that start with an underscore.

private

The private options will return only 'private' methods, as defined by the Perl convention of prepending an underscore to an private methods. The private option will effectively remove an method that do not start with an underscore.

Note: The public and private options are mutually exclusive

full

methods normally returns just the method name. Supplying the full option will cause the methods to be returned as the full names. That is, instead of returning [ 'method1', 'method2', 'method3' ], you would instead get [ 'Class::method1', 'AnotherClass::method2', 'Class::method3' ].

expanded

The expanded option will cause a lot more information about method to be returned. Instead of just the method name, you will instead get an array reference containing the method name as a single combined name, ala full, the seperate class and method, and a CODE ref to the actual function ( if available ). Please note that the function reference is not guarenteed to be available. Class::Inspector is intended at some later time, work with modules that have some some of common run-time loader in place ( e.g Autoloader or Class::Autouse for example.

The response from methods( 'Class', 'expanded' ) would look something like the following.

  [
    [ 'Class::method1',   'Class',   'method1', \&Class::method1   ],
    [ 'Another::method2', 'Another', 'method2', \&Another::method2 ],
    [ 'Foo::bar',         'Foo',     'bar',     \&Foo::bar         ],
  ]

subclasses $class

The subclasses static method will search then entire namespace (and thus all currently loaded classes) to find all classes that are subclasses of the class provided as a the parameter.

The actual test will be done by calling isa on the class as a static method. (i.e. My::Class->isa($class).

Returns a reference to a list of the loaded classes that match the class provided, or false is none match, or undef if the class name provided is invalid.

TO DO

- Adding Class::Inspector::Functions

SUPPORT

Bugs should be reported via the CPAN bug tracker

http://rt.cpan.org/NoAuth/ReportBug.html

For other issues, or commercial enhancement or support, contact the author.

AUTHOR

Adam Kennedy <cpan@ali.as>

SEE ALSO

http://ali.as/, the Class::Handle manpage

COPYRIGHT

Copyright (c) 2002 - 2006 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Class::Struct - declare struct-like datatypes as Perl classes

    • The struct() function
    • Class Creation at Compile Time
    • Element Types and Accessor Methods
    • Initializing with new
  • EXAMPLES
  • Author and Modification History

NAME

Class::Struct - declare struct-like datatypes as Perl classes

SYNOPSIS

    use Class::Struct;
            # declare struct, based on array:
    struct( CLASS_NAME => [ ELEMENT_NAME => ELEMENT_TYPE, ... ]);
            # declare struct, based on hash:
    struct( CLASS_NAME => { ELEMENT_NAME => ELEMENT_TYPE, ... });

    package CLASS_NAME;
    use Class::Struct;
            # declare struct, based on array, implicit class name:
    struct( ELEMENT_NAME => ELEMENT_TYPE, ... );

    # Declare struct at compile time
    use Class::Struct CLASS_NAME => [ ELEMENT_NAME => ELEMENT_TYPE, ... ];
    use Class::Struct CLASS_NAME => { ELEMENT_NAME => ELEMENT_TYPE, ... };

    # declare struct at compile time, based on array, implicit class name:
    package CLASS_NAME;
    use Class::Struct ELEMENT_NAME => ELEMENT_TYPE, ... ;

    package Myobj;
    use Class::Struct;
            # declare struct with four types of elements:
    struct( s => '$', a => '@', h => '%', c => 'My_Other_Class' );

    $obj = new Myobj;               # constructor

                                    # scalar type accessor:
                                        $element_value = $obj->s;           # element value
                                        $obj->s('new value');               # assign to element

                                    # array type accessor:
                                        $ary_ref = $obj->a;                 # reference to whole array
                                        $ary_element_value = $obj->a(2);    # array element value
                                        $obj->a(2, 'new value');            # assign to array element

                                    # hash type accessor:
                                        $hash_ref = $obj->h;                # reference to whole hash
                                        $hash_element_value = $obj->h('x'); # hash element value
                                        $obj->h('x', 'new value');          # assign to hash element

                                    # class type accessor:
                                        $element_value = $obj->c;           # object reference
                                        $obj->c->method(...);               # call method of object
                                        $obj->c(new My_Other_Class);        # assign a new object

DESCRIPTION

Class::Struct exports a single function, struct. Given a list of element names and types, and optionally a class name, struct creates a Perl 5 class that implements a "struct-like" data structure.

The new class is given a constructor method, new, for creating struct objects.

Each element in the struct data has an accessor method, which is used to assign to the element and to fetch its value. The default accessor can be overridden by declaring a sub of the same name in the package. (See Example 2.)

Each element's type can be scalar, array, hash, or class.

The struct() function

The struct function has three forms of parameter-list.

    struct( CLASS_NAME => [ ELEMENT_LIST ]);
    struct( CLASS_NAME => { ELEMENT_LIST });
    struct( ELEMENT_LIST );

The first and second forms explicitly identify the name of the class being created. The third form assumes the current package name as the class name.

An object of a class created by the first and third forms is based on an array, whereas an object of a class created by the second form is based on a hash. The array-based forms will be somewhat faster and smaller; the hash-based forms are more flexible.

The class created by struct must not be a subclass of another class other than UNIVERSAL.

It can, however, be used as a superclass for other classes. To facilitate this, the generated constructor method uses a two-argument blessing. Furthermore, if the class is hash-based, the key of each element is prefixed with the class name (see Perl Cookbook, Recipe 13.12).

A function named new must not be explicitly defined in a class created by struct.

The ELEMENT_LIST has the form

    NAME => TYPE, ...

Each name-type pair declares one element of the struct. Each element name will be defined as an accessor method unless a method by that name is explicitly defined; in the latter case, a warning is issued if the warning flag (-w) is set.

Class Creation at Compile Time

Class::Struct can create your class at compile time. The main reason for doing this is obvious, so your class acts like every other class in Perl. Creating your class at compile time will make the order of events similar to using any other class ( or Perl module ).

There is no significant speed gain between compile time and run time class creation, there is just a new, more standard order of events.

Element Types and Accessor Methods

The four element types -- scalar, array, hash, and class -- are represented by strings -- '$', '@', '%', and a class name -- optionally preceded by a '*'.

The accessor method provided by struct for an element depends on the declared type of the element.

Scalar ('$' or '*$')

The element is a scalar, and by default is initialized to undef (but see Initializing with new).

The accessor's argument, if any, is assigned to the element.

If the element type is '$', the value of the element (after assignment) is returned. If the element type is '*$', a reference to the element is returned.

Array ('@' or '*@')

The element is an array, initialized by default to ().

With no argument, the accessor returns a reference to the element's whole array (whether or not the element was specified as '@' or '*@').

With one or two arguments, the first argument is an index specifying one element of the array; the second argument, if present, is assigned to the array element. If the element type is '@', the accessor returns the array element value. If the element type is '*@', a reference to the array element is returned.

As a special case, when the accessor is called with an array reference as the sole argument, this causes an assignment of the whole array element. The object reference is returned.

Hash ('%' or '*%')

The element is a hash, initialized by default to ().

With no argument, the accessor returns a reference to the element's whole hash (whether or not the element was specified as '%' or '*%').

With one or two arguments, the first argument is a key specifying one element of the hash; the second argument, if present, is assigned to the hash element. If the element type is '%', the accessor returns the hash element value. If the element type is '*%', a reference to the hash element is returned.

As a special case, when the accessor is called with a hash reference as the sole argument, this causes an assignment of the whole hash element. The object reference is returned.

Class ('Class_Name' or '*Class_Name')

The element's value must be a reference blessed to the named class or to one of its subclasses. The element is not initialized by default.

The accessor's argument, if any, is assigned to the element. The accessor will croak if this is not an appropriate object reference.

If the element type does not start with a '*', the accessor returns the element value (after assignment). If the element type starts with a '*', a reference to the element itself is returned.

Initializing with new

struct always creates a constructor called new. That constructor may take a list of initializers for the various elements of the new struct.

Each initializer is a pair of values: element name => value. The initializer value for a scalar element is just a scalar value. The initializer for an array element is an array reference. The initializer for a hash is a hash reference.

The initializer for a class element is an object of the corresponding class, or of one of it's subclasses, or a reference to a hash containing named arguments to be passed to the element's constructor.

See Example 3 below for an example of initialization.

EXAMPLES

Example 1

Giving a struct element a class type that is also a struct is how structs are nested. Here, Timeval represents a time (seconds and microseconds), and Rusage has two elements, each of which is of type Timeval.

    use Class::Struct;

    struct( Rusage => {
        ru_utime => 'Timeval',  # user time used
        ru_stime => 'Timeval',  # system time used
    });

    struct( Timeval => [
        tv_secs  => '$',        # seconds
        tv_usecs => '$',        # microseconds
    ]);

        # create an object:
            my $t = Rusage->new(ru_utime=>Timeval->new(), ru_stime=>Timeval->new());

        # $t->ru_utime and $t->ru_stime are objects of type Timeval.
        # set $t->ru_utime to 100.0 sec and $t->ru_stime to 5.0 sec.
            $t->ru_utime->tv_secs(100);
            $t->ru_utime->tv_usecs(0);
            $t->ru_stime->tv_secs(5);
            $t->ru_stime->tv_usecs(0);
Example 2

An accessor function can be redefined in order to provide additional checking of values, etc. Here, we want the count element always to be nonnegative, so we redefine the count accessor accordingly.

    package MyObj;
    use Class::Struct;

    # declare the struct
    struct ( 'MyObj', { count => '$', stuff => '%' } );

    # override the default accessor method for 'count'
    sub count {
        my $self = shift;
        if ( @_ ) {
            die 'count must be nonnegative' if $_[0] < 0;
            $self->{'MyObj::count'} = shift;
            warn "Too many args to count" if @_;
        }
        return $self->{'MyObj::count'};
    }

    package main;
    $x = new MyObj;
    print "\$x->count(5) = ", $x->count(5), "\n";
                            # prints '$x->count(5) = 5'

    print "\$x->count = ", $x->count, "\n";
                            # prints '$x->count = 5'

    print "\$x->count(-5) = ", $x->count(-5), "\n";
                            # dies due to negative argument!
Example 3

The constructor of a generated class can be passed a list of element=>value pairs, with which to initialize the struct. If no initializer is specified for a particular element, its default initialization is performed instead. Initializers for non-existent elements are silently ignored.

Note that the initializer for a nested class may be specified as an object of that class, or as a reference to a hash of initializers that are passed on to the nested struct's constructor.

    use Class::Struct;

    struct Breed =>
    {
        name  => '$',
        cross => '$',
    };

    struct Cat =>
    [
        name     => '$',
        kittens  => '@',
        markings => '%',
        breed    => 'Breed',
    ];

    my $cat = Cat->new( name     => 'Socks',
                        kittens  => ['Monica', 'Kenneth'],
                        markings => { socks=>1, blaze=>"white" },
                        breed    => Breed->new(name=>'short-hair', cross=>1),
                   or:  breed    => {name=>'short-hair', cross=>1},
                      );

    print "Once a cat called ", $cat->name, "\n";
    print "(which was a ", $cat->breed->name, ")\n";
    print "had two kittens: ", join(' and ', @{$cat->kittens}), "\n";

Author and Modification History

Modified by Damian Conway, 2001-09-10, v0.62.

   Modified implicit construction of nested objects.
   Now will also take an object ref instead of requiring a hash ref.
   Also default initializes nested object attributes to undef, rather
   than calling object constructor without args
   Original over-helpfulness was fraught with problems:
       * the class's constructor might not be called 'new'
       * the class might not have a hash-like-arguments constructor
       * the class might not have a no-argument constructor
       * "recursive" data structures didn't work well:
                 package Person;
                 struct { mother => 'Person', father => 'Person'};

Modified by Casey West, 2000-11-08, v0.59.

    Added the ability for compile time class creation.

Modified by Damian Conway, 1999-03-05, v0.58.

    Added handling of hash-like arg list to class ctor.
    Changed to two-argument blessing in ctor to support
    derivation from created classes.
    Added classname prefixes to keys in hash-based classes
    (refer to "Perl Cookbook", Recipe 13.12 for rationale).
    Corrected behaviour of accessors for '*@' and '*%' struct
    elements.  Package now implements documented behaviour when
    returning a reference to an entire hash or array element.
    Previously these were returned as a reference to a reference
    to the element.

Renamed to Class::Struct and modified by Jim Miner, 1997-04-02.

    members() function removed.
    Documentation corrected and extended.
    Use of struct() in a subclass prohibited.
    User definition of accessor allowed.
    Treatment of '*' in element types corrected.
    Treatment of classes as element types corrected.
    Class name to struct() made optional.
    Diagnostic checks added.

Originally Class::Template by Dean Roehrich.

    # Template.pm   --- struct/member template builder
    #   12mar95
    #   Dean Roehrich
    #
    # changes/bugs fixed since 28nov94 version:
    #  - podified
    # changes/bugs fixed since 21nov94 version:
    #  - Fixed examples.
    # changes/bugs fixed since 02sep94 version:
    #  - Moved to Class::Template.
    # changes/bugs fixed since 20feb94 version:
    #  - Updated to be a more proper module.
    #  - Added "use strict".
    #  - Bug in build_methods, was using @var when @$var needed.
    #  - Now using my() rather than local().
    #
    # Uses perl5 classes to create nested data types.
    # This is offered as one implementation of Tom Christiansen's "structs.pl"
    # idea.


Clone - recursively copy Perl datatypes

  • AUTHOR
  • SEE ALSO

NAME

Clone - recursively copy Perl datatypes

SYNOPSIS

  use Clone;

  push @Foo::ISA, 'Clone';

  $a = new Foo;
  $b = $a->clone();

  # or

  use Clone qw(clone);

  $a = { 'foo' => 'bar', 'move' => 'zig' };
  $b = [ 'alpha', 'beta', 'gamma', 'vlissides' ];
  $c = new Foo();

  $d = clone($a);
  $e = clone($b);
  $f = clone($c);

DESCRIPTION

This module provides a clone() method which makes recursive copies of nested hash, array, scalar and reference types, including tied variables and objects.

clone() takes a scalar argument and an optional parameter that can be used to limit the depth of the copy. To duplicate lists, arrays or hashes, pass them in by reference. e.g.

    my $copy = clone (\@array);

    # or

    my %copy = %{ clone (\%hash) };

For a slower, but more flexible solution see Storable's dclone().

AUTHOR

Ray Finch, rdf@cpan.org

Copyright 2001 Ray Finch.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Storable(3).


Compress::Zlib - Interface to zlib compression library

  • DEFLATE
    • ($d, $status) = deflateInit( [OPT] )
    • ($out, $status) = $d->deflate($buffer)
    • ($out, $status) = $d->flush([flush_type])
    • $status = $d->deflateParams([OPT])
    • $d->dict_adler()
    • $d->msg()
    • $d->total_in()
    • $d->total_out()
    • Example
  • INFLATE
    • ($i, $status) = inflateInit()
    • ($out, $status) = $i->inflate($buffer)
    • $status = $i->inflateSync($buffer)
    • $i->dict_adler()
    • $i->msg()
    • $i->total_in()
    • $i->total_out()
    • Example
  • COMPRESS/UNCOMPRESS
  • GZIP INTERFACE
    • Examples
    • Compress::Zlib::memGzip
    • Compress::Zlib::memGunzip
  • CHECKSUM FUNCTIONS
  • FAQ
    • Compatibility with Unix compress/uncompress.
    • Accessing .tar.Z files
    • Accessing ZIP Files
  • CONSTANTS
  • AUTHOR
  • MODIFICATION HISTORY

NAME

Compress::Zlib - Interface to zlib compression library

SYNOPSIS

    use Compress::Zlib ;

    ($d, $status) = deflateInit( [OPT] ) ;
    ($out, $status) = $d->deflate($buffer) ;
    $status = $d->deflateParams([OPT]) ;
    ($out, $status) = $d->flush() ;
    $d->dict_adler() ;
    $d->total_in() ;
    $d->total_out() ;
    $d->msg() ;

    ($i, $status) = inflateInit( [OPT] ) ;
    ($out, $status) = $i->inflate($buffer) ;
    $status = $i->inflateSync($buffer) ;
    $i->dict_adler() ;
    $i->total_in() ;
    $i->total_out() ;
    $i->msg() ;

    $dest = compress($source, [$level]) ;
    $dest = uncompress($source) ;

    $gz = gzopen($filename or filehandle, $mode) ;
    $bytesread = $gz->gzread($buffer [,$size]) ;
    $bytesread = $gz->gzreadline($line) ;
    $byteswritten = $gz->gzwrite($buffer) ;
    $status = $gz->gzflush($flush) ;
    $status = $gz->gzclose() ;
    $status = $gz->gzeof() ;
    $status = $gz->gzsetparams($level, $strategy) ;
    $errstring = $gz->gzerror() ;
    $gzerrno

    $dest = Compress::Zlib::memGzip($buffer) ;
    $dest = Compress::Zlib::memGunzip($buffer) ;

    $crc = adler32($buffer [,$crc]) ;
    $crc = crc32($buffer [,$crc]) ;

    ZLIB_VERSION

DESCRIPTION

The Compress::Zlib module provides a Perl interface to the zlib compression library (see AUTHOR for details about where to get zlib). Most of the functionality provided by zlib is available in Compress::Zlib.

The module can be split into two general areas of functionality, namely in-memory compression/decompression and read/write access to gzip files. Each of these areas will be discussed separately below.

DEFLATE

The interface Compress::Zlib provides to the in-memory deflate (and inflate) functions has been modified to fit into a Perl model.

The main difference is that for both inflation and deflation, the Perl interface will always consume the complete input buffer before returning. Also the output buffer returned will be automatically grown to fit the amount of output available.

Here is a definition of the interface available:

($d, $status) = deflateInit( [OPT] )

Initialises a deflation stream.

It combines the features of the zlib functions deflateInit, deflateInit2 and deflateSetDictionary.

If successful, it will return the initialised deflation stream, $d and $status of Z_OK in a list context. In scalar context it returns the deflation stream, $d, only.

If not successful, the returned deflation stream ($d) will be undef and $status will hold the exact zlib error code.

The function optionally takes a number of named options specified as -Name=>value pairs. This allows individual options to be tailored without having to specify them all in the parameter list.

For backward compatibility, it is also possible to pass the parameters as a reference to a hash containing the name=>value pairs.

The function takes one optional parameter, a reference to a hash. The contents of the hash allow the deflation interface to be tailored.

Here is a list of the valid options:

-Level

Defines the compression level. Valid values are 0 through 9, Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, and Z_DEFAULT_COMPRESSION.

The default is -Level =>Z_DEFAULT_COMPRESSION.

-Method

Defines the compression method. The only valid value at present (and the default) is -Method =>Z_DEFLATED.

-WindowBits

For a definition of the meaning and valid values for WindowBits refer to the zlib documentation for deflateInit2.

Defaults to -WindowBits =>MAX_WBITS.

-MemLevel

For a definition of the meaning and valid values for MemLevel refer to the zlib documentation for deflateInit2.

Defaults to -MemLevel =>MAX_MEM_LEVEL.

-Strategy

Defines the strategy used to tune the compression. The valid values are Z_DEFAULT_STRATEGY, Z_FILTERED and Z_HUFFMAN_ONLY.

The default is -Strategy =>Z_DEFAULT_STRATEGY.

-Dictionary

When a dictionary is specified Compress::Zlib will automatically call deflateSetDictionary directly after calling deflateInit. The Adler32 value for the dictionary can be obtained by calling the method $d-dict_adler()>.

The default is no dictionary.

-Bufsize

Sets the initial size for the deflation buffer. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

The default is 4096.

Here is an example of using the deflateInit optional parameter list to override the default buffer size and compression level. All other options will take their default values.

    deflateInit( -Bufsize => 300,
                 -Level => Z_BEST_SPEED  ) ;

($out, $status) = $d->deflate($buffer)

Deflates the contents of $buffer. The buffer can either be a scalar or a scalar reference. When finished, $buffer will be completely processed (assuming there were no errors). If the deflation was successful it returns the deflated output, $out, and a status value, $status, of Z_OK.

On error, $out will be undef and $status will contain the zlib error code.

In a scalar context deflate will return $out only.

As with the deflate function in zlib, it is not necessarily the case that any output will be produced by this method. So don't rely on the fact that $out is empty for an error test.

($out, $status) = $d->flush([flush_type])

Typically used to finish the deflation. Any pending output will be returned via $out. $status will have a value Z_OK if successful.

In a scalar context flush will return $out only.

Note that flushing can seriously degrade the compression ratio, so it should only be used to terminate a decompression (using Z_FINISH) or when you want to create a full flush point (using Z_FULL_FLUSH).

By default the flush_type used is Z_FINISH. Other valid values for flush_type are Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH and Z_FULL_FLUSH. It is strongly recommended that you only set the flush_type parameter if you fully understand the implications of what it does. See the zlib documentation for details.

$status = $d->deflateParams([OPT])

Change settings for the deflate stream $d.

The list of the valid options is shown below. Options not specified will remain unchanged.

-Level

Defines the compression level. Valid values are 0 through 9, Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, and Z_DEFAULT_COMPRESSION.

-Strategy

Defines the strategy used to tune the compression. The valid values are Z_DEFAULT_STRATEGY, Z_FILTERED and Z_HUFFMAN_ONLY.

$d->dict_adler()

Returns the adler32 value for the dictionary.

$d->msg()

Returns the last error message generated by zlib.

$d->total_in()

Returns the total number of bytes uncompressed bytes input to deflate.

$d->total_out()

Returns the total number of compressed bytes output from deflate.

Example

Here is a trivial example of using deflate. It simply reads standard input, deflates it and writes it to standard output.

    use strict ;
    use warnings ;

    use Compress::Zlib ;

    binmode STDIN;
    binmode STDOUT;
    my $x = deflateInit()
       or die "Cannot create a deflation stream\n" ;

    my ($output, $status) ;
    while (<>)
    {
        ($output, $status) = $x->deflate($_) ;

        $status == Z_OK
            or die "deflation failed\n" ;

        print $output ;
    }

    ($output, $status) = $x->flush() ;

    $status == Z_OK
        or die "deflation failed\n" ;

    print $output ;

INFLATE

Here is a definition of the interface:

($i, $status) = inflateInit()

Initialises an inflation stream.

In a list context it returns the inflation stream, $i, and the zlib status code ($status). In a scalar context it returns the inflation stream only.

If successful, $i will hold the inflation stream and $status will be Z_OK.

If not successful, $i will be undef and $status will hold the zlib error code.

The function optionally takes a number of named options specified as -Name=>value pairs. This allows individual options to be tailored without having to specify them all in the parameter list.

For backward compatibility, it is also possible to pass the parameters
as a reference to a hash containing the name=>value pairs.

The function takes one optional parameter, a reference to a hash.  The
contents of the hash allow the deflation interface to be tailored.

Here is a list of the valid options:
-WindowBits

For a definition of the meaning and valid values for WindowBits refer to the zlib documentation for inflateInit2.

Defaults to -WindowBits =>MAX_WBITS.

-Bufsize

Sets the initial size for the inflation buffer. If the buffer has to be reallocated to increase the size, it will grow in increments of Bufsize.

Default is 4096.

-Dictionary

The default is no dictionary.

Here is an example of using the inflateInit optional parameter to override the default buffer size.

    inflateInit( -Bufsize => 300 ) ;

($out, $status) = $i->inflate($buffer)

Inflates the complete contents of $buffer. The buffer can either be a scalar or a scalar reference.

Returns Z_OK if successful and Z_STREAM_END if the end of the compressed data has been successfully reached. If not successful, $out will be undef and $status will hold the zlib error code.

The $buffer parameter is modified by inflate. On completion it will contain what remains of the input buffer after inflation. This means that $buffer will be an empty string when the return status is Z_OK. When the return status is Z_STREAM_END the $buffer parameter will contains what (if anything) was stored in the input buffer after the deflated data stream.

This feature is useful when processing a file format that encapsulates a compressed data stream (e.g. gzip, zip).

$status = $i->inflateSync($buffer)

Scans $buffer until it reaches either a full flush point or the end of the buffer.

If a full flush point is found, Z_OK is returned and $buffer will be have all data up to the flush point removed. This can then be passed to the deflate method.

Any other return code means that a flush point was not found. If more data is available, inflateSync can be called repeatedly with more compressed data until the flush point is found.

$i->dict_adler()

Returns the adler32 value for the dictionary.

$i->msg()

Returns the last error message generated by zlib.

$i->total_in()

Returns the total number of bytes compressed bytes input to inflate.

$i->total_out()

Returns the total number of uncompressed bytes output from inflate.

Example

Here is an example of using inflate.

    use strict ;
    use warnings ;

    use Compress::Zlib ;

    my $x = inflateInit()
       or die "Cannot create a inflation stream\n" ;

    my $input = '' ;
    binmode STDIN;
    binmode STDOUT;

    my ($output, $status) ;
    while (read(STDIN, $input, 4096))
    {
        ($output, $status) = $x->inflate(\$input) ;

        print $output
            if $status == Z_OK or $status == Z_STREAM_END ;

        last if $status != Z_OK ;
    }

    die "inflation failed\n"
        unless $status == Z_STREAM_END ;

COMPRESS/UNCOMPRESS

Two high-level functions are provided by zlib to perform in-memory compression/uncompression of RFC1950 data streams. They are called compress and uncompress.

The two Perl subs defined below provide the equivalent functionality.

$dest = compress($source [, $level] ) ;

Compresses $source. If successful it returns the compressed data. Otherwise it returns undef.

The source buffer can either be a scalar or a scalar reference.

The $level paramter defines the compression level. Valid values are 0 through 9, Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, and Z_DEFAULT_COMPRESSION. If $level is not specified Z_DEFAULT_COMPRESSION will be used.

$dest = uncompress($source) ;

Uncompresses $source. If successful it returns the uncompressed data. Otherwise it returns undef.

The source buffer can either be a scalar or a scalar reference.

Please note: the two functions defined above are not compatible with the Unix commands of the same name.

GZIP INTERFACE

A number of functions are supplied in zlib for reading and writing gzip files. This module provides an interface to most of them. In general the interface provided by this module operates identically to the functions provided by zlib. Any differences are explained below.

$gz = gzopen(filename or filehandle, mode)

This function operates identically to the zlib equivalent except that it returns an object which is used to access the other gzip methods.

As with the zlib equivalent, the mode parameter is used to specify both whether the file is opened for reading or writing and to optionally specify a a compression level. Refer to the zlib documentation for the exact format of the mode parameter.

If a reference to an open filehandle is passed in place of the filename, gzdopen will be called behind the scenes. The third example at the end of this section, gzstream, uses this feature.

$bytesread = $gz->gzread($buffer [, $size]) ;

Reads $size bytes from the compressed file into $buffer. If $size is not specified, it will default to 4096. If the scalar $buffer is not large enough, it will be extended automatically.

Returns the number of bytes actually read. On EOF it returns 0 and in the case of an error, -1.

$bytesread = $gz->gzreadline($line) ;

Reads the next line from the compressed file into $line.

Returns the number of bytes actually read. On EOF it returns 0 and in the case of an error, -1.

It is legal to intermix calls to gzread and gzreadline.

At this time gzreadline ignores the variable $/ ($INPUT_RECORD_SEPARATOR or $RS when English is in use). The end of a line is denoted by the C character '\n'.

$byteswritten = $gz->gzwrite($buffer) ;

Writes the contents of $buffer to the compressed file. Returns the number of bytes actually written, or 0 on error.

$status = $gz->gzflush($flush) ;

Flushes all pending output to the compressed file. Works identically to the zlib function it interfaces to. Note that the use of gzflush can degrade compression.

Returns Z_OK if $flush is Z_FINISH and all output could be flushed. Otherwise the zlib error code is returned.

Refer to the zlib documentation for the valid values of $flush.

$status = $gz->gzeof() ;

Returns 1 if the end of file has been detected while reading the input file, otherwise returns 0.

$gz->gzclose

Closes the compressed file. Any pending data is flushed to the file before it is closed.

$gz->gzsetparams($level, $strategy

Change settings for the deflate stream $gz.

The list of the valid options is shown below. Options not specified will remain unchanged.

Note: This method is only available if you are running zlib 1.0.6 or better.

$level

Defines the compression level. Valid values are 0 through 9, Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, and Z_DEFAULT_COMPRESSION.

$strategy

Defines the strategy used to tune the compression. The valid values are Z_DEFAULT_STRATEGY, Z_FILTERED and Z_HUFFMAN_ONLY.

$gz->gzerror

Returns the zlib error message or number for the last operation associated with $gz. The return value will be the zlib error number when used in a numeric context and the zlib error message when used in a string context. The zlib error number constants, shown below, are available for use.

    Z_OK
    Z_STREAM_END
    Z_ERRNO
    Z_STREAM_ERROR
    Z_DATA_ERROR
    Z_MEM_ERROR
    Z_BUF_ERROR
$gzerrno

The $gzerrno scalar holds the error code associated with the most recent gzip routine. Note that unlike gzerror(), the error is not associated with a particular file.

As with gzerror() it returns an error number in numeric context and an error message in string context. Unlike gzerror() though, the error message will correspond to the zlib message when the error is associated with zlib itself, or the UNIX error message when it is not (i.e. zlib returned Z_ERRORNO).

As there is an overlap between the error numbers used by zlib and UNIX, $gzerrno should only be used to check for the presence of an error in numeric context. Use gzerror() to check for specific zlib errors. The gzcat example below shows how the variable can be used safely.

Examples

Here is an example script which uses the interface. It implements a gzcat function.

    use strict ;
    use warnings ;

    use Compress::Zlib ;

    die "Usage: gzcat file...\n"
        unless @ARGV ;

    my $file ;

    foreach $file (@ARGV) {
        my $buffer ;

        my $gz = gzopen($file, "rb")
             or die "Cannot open $file: $gzerrno\n" ;

        print $buffer while $gz->gzread($buffer) > 0 ;

        die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n"
            if $gzerrno != Z_STREAM_END ;

        $gz->gzclose() ;
    }

Below is a script which makes use of gzreadline. It implements a very simple grep like script.

    use strict ;
    use warnings ;

    use Compress::Zlib ;

    die "Usage: gzgrep pattern file...\n"
        unless @ARGV >= 2;

    my $pattern = shift ;

    my $file ;

    foreach $file (@ARGV) {
        my $gz = gzopen($file, "rb")
             or die "Cannot open $file: $gzerrno\n" ;

        while ($gz->gzreadline($_) > 0) {
            print if /$pattern/ ;
        }

        die "Error reading from $file: $gzerrno\n"
            if $gzerrno != Z_STREAM_END ;

        $gz->gzclose() ;
    }

This script, gzstream, does the opposite of the gzcat script above. It reads from standard input and writes a gzip file to standard output.

    use strict ;
    use warnings ;

    use Compress::Zlib ;

    binmode STDOUT;     # gzopen only sets it on the fd

    my $gz = gzopen(\*STDOUT, "wb")
          or die "Cannot open stdout: $gzerrno\n" ;

    while (<>) {
        $gz->gzwrite($_)
        or die "error writing: $gzerrno\n" ;
    }

    $gz->gzclose ;

Compress::Zlib::memGzip

This function is used to create an in-memory gzip file. It creates a minimal gzip header.

    $dest = Compress::Zlib::memGzip($buffer) ;

If successful, it returns the in-memory gzip file, otherwise it returns undef.

The buffer parameter can either be a scalar or a scalar reference.

Compress::Zlib::memGunzip

This function is used to uncompress an in-memory gzip file.

    $dest = Compress::Zlib::memGunzip($buffer) ;

If successful, it returns the uncompressed gzip file, otherwise it returns undef.

The buffer parameter can either be a scalar or a scalar reference. The contents of the buffer parameter are destroyed after calling this function.

CHECKSUM FUNCTIONS

Two functions are provided by zlib to calculate a checksum. For the Perl interface, the order of the two parameters in both functions has been reversed. This allows both running checksums and one off calculations to be done.

    $crc = adler32($buffer [,$crc]) ;
    $crc = crc32($buffer [,$crc]) ;

The buffer parameters can either be a scalar or a scalar reference.

If the $crc parameters is undef, the crc value will be reset.

FAQ

Compatibility with Unix compress/uncompress.

Although Compress::Zlib has a pair of functions called compress and uncompress, they are not the same as the Unix programs of the same name. The Compress::Zlib library is not compatable with Unix compress.

If you have the uncompress program available, you can use this to read compressed files

    open F, "uncompress -c $filename |";
    while (<F>)
    {
        ...

If you have the gunzip program available, you can use this to read compressed files

    open F, "gunzip -c $filename |";
    while (<F>)
    {
        ...

and this to write compress files if you have the compress program available

    open F, "| compress -c $filename ";
    print F "data";
    ...
    close F ;

Accessing .tar.Z files

The Archive::Tar module can optionally use Compress::Zlib (via the IO::Zlib module) to access tar files that have been compressed with gzip. Unfortunately tar files compressed with the Unix compress utility cannot be read by Compress::Zlib and so cannot be directly accesses by Archive::Tar.

If the uncompress or gunzip programs are available, you can use one of these workarounds to read .tar.Z files from Archive::Tar

Firstly with uncompress

    use strict;
    use warnings;
    use Archive::Tar;

    open F, "uncompress -c $filename |";
    my $tar = Archive::Tar->new(*F);
    ...

and this with gunzip

    use strict;
    use warnings;
    use Archive::Tar;

    open F, "gunzip -c $filename |";
    my $tar = Archive::Tar->new(*F);
    ...

Similarly, if the compress program is available, you can use this to write a .tar.Z file

    use strict;
    use warnings;
    use Archive::Tar;
    use IO::File;

    my $fh = newIO::File "| compress -c >$filename";
    my $tar = Archive::Tar->new();
    ...
    $tar->write($fh);
    $fh->close ;

Accessing ZIP Files

Although it is possible to use this module to access .zip files, there is a module on CPAN that will do all the hard work for you. Check out

    http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz

Assuming you don't want to use this module to access zip files there are a number of undocumented features in the zlib library you need to be aware of.

  1. When calling inflateInit or deflateInit the WindowBits parameter must be set to -MAX_WBITS. This disables the creation of the zlib header.

  2. The zlib function inflate, and so the inflate method supplied in this module, assume that there is at least one trailing byte after the compressed data stream. Normally this isn't a problem because both the gzip and zip file formats will guarantee that there is data directly after the compressed data stream.

CONSTANTS

All the zlib constants are automatically imported when you make use of Compress::Zlib.

AUTHOR

The Compress::Zlib module was written by Paul Marquess, pmqs@cpan.org. The latest copy of the module can be found on CPAN in modules/by-module/Compress/Compress-Zlib-x.x.tar.gz.

The primary site for the zlib compression library is http://www.zlib.org.

MODIFICATION HISTORY

See the Changes file.


Config - access Perl configuration information

  • EXAMPLE
  • WARNING
  • GLOSSARY
    • _
    • a
    • b
    • c
    • d
    • e
    • f
    • g
    • h
    • i
    • k
    • l
    • m
    • M
    • n
    • o
    • p
    • P
    • q
    • r
    • s
    • t
    • u
    • v
    • x
    • y
    • z
  • NOTE

NAME

Config - access Perl configuration information

SYNOPSIS

    use Config;
    if ($Config{usethreads}) {
        print "has thread support\n"
    }

    use Config qw(myconfig config_sh config_vars config_re);

    print myconfig();

    print config_sh();

    print config_re();

    config_vars(qw(osname archname));

DESCRIPTION

The Config module contains all the information that was available to the Configure program at Perl build time (over 900 values).

Shell variables from the config.sh file (written by Configure) are stored in the readonly-variable %Config, indexed by their names.

Values stored in config.sh as 'undef' are returned as undefined values. The perl exists function can be used to check if a named variable exists.

myconfig()

Returns a textual summary of the major perl configuration values. See also -V in Switches in the perlrun manpage.

config_sh()

Returns the entire perl configuration information in the form of the original config.sh shell variable assignment script.

config_re($regex)

Like config_sh() but returns, as a list, only the config entries who's names match the $regex.

config_vars(@names)

Prints to STDOUT the values of the named configuration variable. Each is printed on a separate line in the form:

  name='value';

Names which are unknown are output as name='UNKNOWN';. See also -V:name in Switches in the perlrun manpage.

EXAMPLE

Here's a more sophisticated example of using %Config:

    use Config;
    use strict;

    my %sig_num;
    my @sig_name;
    unless($Config{sig_name} && $Config{sig_num}) {
        die "No sigs?";
    } else {
        my @names = split ' ', $Config{sig_name};
        @sig_num{@names} = split ' ', $Config{sig_num};
        foreach (@names) {
            $sig_name[$sig_num{$_}] ||= $_;
        }
    }

    print "signal #17 = $sig_name[17]\n";
    if ($sig_num{ALRM}) {
        print "SIGALRM is $sig_num{ALRM}\n";
    }

WARNING

Because this information is not stored within the perl executable itself it is possible (but unlikely) that the information does not relate to the actual perl binary which is being used to access it.

The Config module is installed into the architecture and version specific library directory ($Config{installarchlib}) and it checks the perl version number when loaded.

The values stored in config.sh may be either single-quoted or double-quoted. Double-quoted strings are handy for those cases where you need to include escape sequences in the strings. To avoid runtime variable interpolation, any $ and @ characters are replaced by \$ and \@, respectively. This isn't foolproof, of course, so don't embed \$ or \@ in double-quoted strings unless you're willing to deal with the consequences. (The slashes will end up escaped and the $ or @ will trigger variable interpolation)

GLOSSARY

Most Config variables are determined by the Configure script on platforms supported by it (which is most UNIX platforms). Some platforms have custom-made Config variables, and may thus not have some of the variables described below, or may have extraneous variables specific to that particular port. See the port specific documentation in such cases.

_

_a

From Unix.U:

This variable defines the extension used for ordinary library files. For unix, it is .a. The . is included. Other possible values include .lib.

_exe

From Unix.U:

This variable defines the extension used for executable files. DJGPP, Cygwin and OS/2 use .exe. Stratus VOS uses .pm. On operating systems which do not require a specific extension for executable files, this variable is empty.

_o

From Unix.U:

This variable defines the extension used for object files. For unix, it is .o. The . is included. Other possible values include .obj.

a

afs

From afs.U:

This variable is set to true if AFS (Andrew File System) is used on the system, false otherwise. It is possible to override this with a hint value or command line option, but you'd better know what you are doing.

afsroot

From afs.U:

This variable is by default set to /afs. In the unlikely case this is not the correct root, it is possible to override this with a hint value or command line option. This will be used in subsequent tests for AFSness in the Perl configure and test process.

alignbytes

From alignbytes.U:

This variable holds the number of bytes required to align a double-- or a long double when applicable. Usual values are 2, 4 and 8. The default is eight, for safety.

ansi2knr

From ansi2knr.U:

This variable is set if the user needs to run ansi2knr. Currently, this is not supported, so we just abort.

aphostname

From d_gethname.U:

This variable contains the command which can be used to compute the host name. The command is fully qualified by its absolute path, to make it safe when used by a process with super-user privileges.

api_revision

From patchlevel.U:

The three variables, api_revision, api_version, and api_subversion, specify the version of the oldest perl binary compatible with the present perl. In a full version string such as 5.6.1, api_revision is the 5. Prior to 5.5.640, the format was a floating point number, like 5.00563.

perl.c:incpush() and lib/lib.pm will automatically search in $sitelib/.. for older directories back to the limit specified by these api_ variables. This is only useful if you have a perl library directory tree structured like the default one. See INSTALL for how this works. The versioned site_perl directory was introduced in 5.005, so that is the lowest possible value. The version list appropriate for the current system is determined in inc_version_list.U.

XXX To do: Since compatibility can depend on compile time options (such as bincompat, longlong, etc.) it should (perhaps) be set by Configure, but currently it isn't. Currently, we read a hard-wired value from patchlevel.h. Perhaps what we ought to do is take the hard-wired value from patchlevel.h but then modify it if the current Configure options warrant. patchlevel.h then would use an #ifdef guard.

api_subversion

From patchlevel.U:

The three variables, api_revision, api_version, and api_subversion, specify the version of the oldest perl binary compatible with the present perl. In a full version string such as 5.6.1, api_subversion is the 1. See api_revision for full details.

api_version

From patchlevel.U:

The three variables, api_revision, api_version, and api_subversion, specify the version of the oldest perl binary compatible with the present perl. In a full version string such as 5.6.1, api_version is the 6. See api_revision for full details. As a special case, 5.5.0 is rendered in the old-style as 5.005. (In the 5.005_0x maintenance series, this was the only versioned directory in $sitelib.)

api_versionstring

From patchlevel.U:

This variable combines api_revision, api_version, and api_subversion in a format such as 5.6.1 (or 5_6_1) suitable for use as a directory name. This is filesystem dependent.

ar

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the ar program. After Configure runs, the value is reset to a plain ar and is not useful.

archlib

From archlib.U:

This variable holds the name of the directory in which the user wants to put architecture-dependent public library files for $package. It is most often a local directory such as /usr/local/lib. Programs using this variable must be prepared to deal with filename expansion.

archlibexp

From archlib.U:

This variable is the same as the archlib variable, but is filename expanded at configuration time, for convenient use.

archname64

From use64bits.U:

This variable is used for the 64-bitness part of $archname.

archname

From archname.U:

This variable is a short name to characterize the current architecture. It is used mainly to construct the default archlib.

archobjs

From Unix.U:

This variable defines any additional objects that must be linked in with the program on this architecture. On unix, it is usually empty. It is typically used to include emulations of unix calls or other facilities. For perl on OS/2, for example, this would include os2/os2.obj.

asctime_r_proto

From d_asctime_r.U:

This variable encodes the prototype of asctime_r. It is zero if d_asctime_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_asctime_r is defined.

awk

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the awk program. After Configure runs, the value is reset to a plain awk and is not useful.

b

baserev

From baserev.U:

The base revision level of this package, from the .package file.

bash

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

bin

From bin.U:

This variable holds the name of the directory in which the user wants to put publicly executable images for the package in question. It is most often a local directory such as /usr/local/bin. Programs using this variable must be prepared to deal with ~name substitution.

binexp

From bin.U:

This is the same as the bin variable, but is filename expanded at configuration time, for use in your makefiles.

bison

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the bison program. After Configure runs, the value is reset to a plain bison and is not useful.

byacc

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the byacc program. After Configure runs, the value is reset to a plain byacc and is not useful.

byteorder

From byteorder.U:

This variable holds the byte order in a UV. In the following, larger digits indicate more significance. The variable byteorder is either 4321 on a big-endian machine, or 1234 on a little-endian, or 87654321 on a Cray ... or 3412 with weird order !

c

c

From n.U:

This variable contains the \c string if that is what causes the echo command to suppress newline. Otherwise it is null. Correct usage is $echo $n "prompt for a question: $c".

castflags

From d_castneg.U:

This variable contains a flag that precise difficulties the
compiler has casting odd floating values to unsigned long:
0 = ok
1 = couldn't cast < 0
2 = couldn't cast >= 0x80000000
4 = couldn't cast in argument expression list

cat

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the cat program. After Configure runs, the value is reset to a plain cat and is not useful.

cc

From cc.U:

This variable holds the name of a command to execute a C compiler which can resolve multiple global references that happen to have the same name. Usual values are cc and gcc. Fervent ANSI compilers may be called c89. AIX has xlc.

cccdlflags

From dlsrc.U:

This variable contains any special flags that might need to be passed with cc -c to compile modules to be used to create a shared library that will be used for dynamic loading. For hpux, this should be +z. It is up to the makefile to use it.

ccdlflags

From dlsrc.U:

This variable contains any special flags that might need to be passed to cc to link with a shared library for dynamic loading. It is up to the makefile to use it. For sunos 4.1, it should be empty.

ccflags

From ccflags.U:

This variable contains any additional C compiler flags desired by the user. It is up to the Makefile to use this.

ccflags_uselargefiles

From uselfs.U:

This variable contains the compiler flags needed by large file builds and added to ccflags by hints files.

ccname

From Checkcc.U:

This can set either by hints files or by Configure. If using gcc, this is gcc, and if not, usually equal to cc, unimpressive, no? Some platforms, however, make good use of this by storing the flavor of the C compiler being used here. For example if using the Sun WorkShop suite, ccname will be workshop.

ccsymbols

From Cppsym.U:

The variable contains the symbols defined by the C compiler alone. The symbols defined by cpp or by cc when it calls cpp are not in this list, see cppsymbols and cppccsymbols. The list is a space-separated list of symbol=value tokens.

ccversion

From Checkcc.U:

This can set either by hints files or by Configure. If using a (non-gcc) vendor cc, this variable may contain a version for the compiler.

cf_by

From cf_who.U:

Login name of the person who ran the Configure script and answered the questions. This is used to tag both config.sh and config_h.SH.

cf_email

From cf_email.U:

Electronic mail address of the person who ran Configure. This can be used by units that require the user's e-mail, like MailList.U.

cf_time

From cf_who.U:

Holds the output of the date command when the configuration file was produced. This is used to tag both config.sh and config_h.SH.

charsize

From charsize.U:

This variable contains the value of the CHARSIZE symbol, which indicates to the C program how many bytes there are in a character.

chgrp

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

chmod

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the chmod program. After Configure runs, the value is reset to a plain chmod and is not useful.

chown

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

clocktype

From d_times.U:

This variable holds the type returned by times(). It can be long, or clock_t on BSD sites (in which case <sys/types.h> should be included).

comm

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the comm program. After Configure runs, the value is reset to a plain comm and is not useful.

compress

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

contains

From contains.U:

This variable holds the command to do a grep with a proper return status. On most sane systems it is simply grep. On insane systems it is a grep followed by a cat followed by a test. This variable is primarily for the use of other Configure units.

cp

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the cp program. After Configure runs, the value is reset to a plain cp and is not useful.

cpio

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

cpp

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the cpp program. After Configure runs, the value is reset to a plain cpp and is not useful.

cpp_stuff

From cpp_stuff.U:

This variable contains an identification of the concatenation mechanism used by the C preprocessor.

cppccsymbols

From Cppsym.U:

The variable contains the symbols defined by the C compiler when it calls cpp. The symbols defined by the cc alone or cpp alone are not in this list, see ccsymbols and cppsymbols. The list is a space-separated list of symbol=value tokens.

cppflags

From ccflags.U:

This variable holds the flags that will be passed to the C pre- processor. It is up to the Makefile to use it.

cpplast

From cppstdin.U:

This variable has the same functionality as cppminus, only it applies to cpprun and not cppstdin.

cppminus

From cppstdin.U:

This variable contains the second part of the string which will invoke the C preprocessor on the standard input and produce to standard output. This variable will have the value - if cppstdin needs a minus to specify standard input, otherwise the value is "".

cpprun

From cppstdin.U:

This variable contains the command which will invoke a C preprocessor on standard input and put the output to stdout. It is guaranteed not to be a wrapper and may be a null string if no preprocessor can be made directly available. This preprocessor might be different from the one used by the C compiler. Don't forget to append cpplast after the preprocessor options.

cppstdin

From cppstdin.U:

This variable contains the command which will invoke the C preprocessor on standard input and put the output to stdout. It is primarily used by other Configure units that ask about preprocessor symbols.

cppsymbols

From Cppsym.U:

The variable contains the symbols defined by the C preprocessor alone. The symbols defined by cc or by cc when it calls cpp are not in this list, see ccsymbols and cppccsymbols. The list is a space-separated list of symbol=value tokens.

crypt_r_proto

From d_crypt_r.U:

This variable encodes the prototype of crypt_r. It is zero if d_crypt_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_crypt_r is defined.

cryptlib

From d_crypt.U:

This variable holds -lcrypt or the path to a libcrypt.a archive if the crypt() function is not defined in the standard C library. It is up to the Makefile to use this.

csh

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the csh program. After Configure runs, the value is reset to a plain csh and is not useful.

ctermid_r_proto

From d_ctermid_r.U:

This variable encodes the prototype of ctermid_r. It is zero if d_ctermid_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_ctermid_r is defined.

ctime_r_proto

From d_ctime_r.U:

This variable encodes the prototype of ctime_r. It is zero if d_ctime_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_ctime_r is defined.

d

d__fwalk

From d__fwalk.U:

This variable conditionally defines HAS__FWALK if _fwalk() is available to apply a function to all the file handles.

d_access

From d_access.U:

This variable conditionally defines HAS_ACCESS if the access() system call is available to check for access permissions using real IDs.

d_accessx

From d_accessx.U:

This variable conditionally defines the HAS_ACCESSX symbol, which indicates to the C program that the accessx() routine is available.

d_aintl

From d_aintl.U:

This variable conditionally defines the HAS_AINTL symbol, which indicates to the C program that the aintl() routine is available. If copysignl is also present we can emulate modfl.

d_alarm

From d_alarm.U:

This variable conditionally defines the HAS_ALARM symbol, which indicates to the C program that the alarm() routine is available.

d_archlib

From archlib.U:

This variable conditionally defines ARCHLIB to hold the pathname of architecture-dependent library files for $package. If $archlib is the same as $privlib, then this is set to undef.

d_asctime_r

From d_asctime_r.U:

This variable conditionally defines the HAS_ASCTIME_R symbol, which indicates to the C program that the asctime_r() routine is available.

d_atolf

From atolf.U:

This variable conditionally defines the HAS_ATOLF symbol, which indicates to the C program that the atolf() routine is available.

d_atoll

From atoll.U:

This variable conditionally defines the HAS_ATOLL symbol, which indicates to the C program that the atoll() routine is available.

d_attribute_format

From d_attribut_format.U:

This variable conditionally defines HASATTRIBUTE_FORMAT, which indicates the C compiler can check for printf-like formats.

d_attribute_malloc

From d_attribute_malloc.U:

This variable conditionally defines HASATTRIBUTE_MALLOC, which indicates the C compiler can understand functions as having malloc-like semantics.

d_attribute_nonnull

From d_attribute_nonnull.U:

This variable conditionally defines HASATTRIBUTE_NONNULL, which indicates that the C compiler can know that certain arguments must not be NULL, and will check accordingly at compile time.

d_attribute_noreturn

From d_attribute_noreturn.U:

This variable conditionally defines HASATTRIBUTE_NORETURN, which indicates that the C compiler can know that certain functions are guaranteed never to return.

d_attribute_pure

From d_attribute_pure.U:

This variable conditionally defines HASATTRIBUTE_PURE, which indicates that the C compiler can know that certain functions are pure functions, meaning that they have no side effects, and only rely on function input and/or global data for their results.

d_attribute_unused

From d_attribute_unused.U:

This variable conditionally defines HASATTRIBUTE_UNUSED, which indicates that the C compiler can know that certain variables and arguments may not always be used, and to not throw warnings if they don't get used.

d_attribute_warn_unused_result

From d_attribute_warn_unused_result.U:

This variable conditionally defines HASATTRIBUTE_WARN_UNUSED_RESULT, which indicates that the C compiler can know that certain functions have a return values that must not be ignored, such as malloc() or open().

d_bcmp

From d_bcmp.U:

This variable conditionally defines the HAS_BCMP symbol if the bcmp() routine is available to compare strings.

d_bcopy

From d_bcopy.U:

This variable conditionally defines the HAS_BCOPY symbol if the bcopy() routine is available to copy strings.

d_bsd

From Guess.U:

This symbol conditionally defines the symbol BSD when running on a BSD system.

d_bsdgetpgrp

From d_getpgrp.U:

This variable conditionally defines USE_BSD_GETPGRP if getpgrp needs one arguments whereas USG one needs none.

d_bsdsetpgrp

From d_setpgrp.U:

This variable conditionally defines USE_BSD_SETPGRP if setpgrp needs two arguments whereas USG one needs none. See also d_setpgid for a POSIX interface.

d_bzero

From d_bzero.U:

This variable conditionally defines the HAS_BZERO symbol if the bzero() routine is available to set memory to 0.

d_casti32

From d_casti32.U:

This variable conditionally defines CASTI32, which indicates whether the C compiler can cast large floats to 32-bit ints.

d_castneg

From d_castneg.U:

This variable conditionally defines CASTNEG, which indicates wether the C compiler can cast negative float to unsigned.

d_charvspr

From d_vprintf.U:

This variable conditionally defines CHARVSPRINTF if this system has vsprintf returning type (char*). The trend seems to be to declare it as "int vsprintf()".

d_chown

From d_chown.U:

This variable conditionally defines the HAS_CHOWN symbol, which indicates to the C program that the chown() routine is available.

d_chroot

From d_chroot.U:

This variable conditionally defines the HAS_CHROOT symbol, which indicates to the C program that the chroot() routine is available.

d_chsize

From d_chsize.U:

This variable conditionally defines the CHSIZE symbol, which indicates to the C program that the chsize() routine is available to truncate files. You might need a -lx to get this routine.

d_class

From d_class.U:

This variable conditionally defines the HAS_CLASS symbol, which indicates to the C program that the class() routine is available.

d_clearenv

From d_clearenv.U:

This variable conditionally defines the HAS_CLEARENV symbol, which indicates to the C program that the clearenv () routine is available.

d_closedir

From d_closedir.U:

This variable conditionally defines HAS_CLOSEDIR if closedir() is available.

d_cmsghdr_s

From d_cmsghdr_s.U:

This variable conditionally defines the HAS_STRUCT_CMSGHDR symbol, which indicates that the struct cmsghdr is supported.

d_const

From d_const.U:

This variable conditionally defines the HASCONST symbol, which indicates to the C program that this C compiler knows about the const type.

d_copysignl

From d_copysignl.U:

This variable conditionally defines the HAS_COPYSIGNL symbol, which indicates to the C program that the copysignl() routine is available. If aintl is also present we can emulate modfl.

d_crypt

From d_crypt.U:

This variable conditionally defines the CRYPT symbol, which indicates to the C program that the crypt() routine is available to encrypt passwords and the like.

d_crypt_r

From d_crypt_r.U:

This variable conditionally defines the HAS_CRYPT_R symbol, which indicates to the C program that the crypt_r() routine is available.

d_csh

From d_csh.U:

This variable conditionally defines the CSH symbol, which indicates to the C program that the C-shell exists.

d_ctermid_r

From d_ctermid_r.U:

This variable conditionally defines the HAS_CTERMID_R symbol, which indicates to the C program that the ctermid_r() routine is available.

d_ctime_r

From d_ctime_r.U:

This variable conditionally defines the HAS_CTIME_R symbol, which indicates to the C program that the ctime_r() routine is available.

d_cuserid

From d_cuserid.U:

This variable conditionally defines the HAS_CUSERID symbol, which indicates to the C program that the cuserid() routine is available to get character login names.

d_dbl_dig

From d_dbl_dig.U:

This variable conditionally defines d_dbl_dig if this system's header files provide DBL_DIG, which is the number of significant digits in a double precision number.

d_dbminitproto

From d_dbminitproto.U:

This variable conditionally defines the HAS_DBMINIT_PROTO symbol, which indicates to the C program that the system provides a prototype for the dbminit() function. Otherwise, it is up to the program to supply one.

d_difftime

From d_difftime.U:

This variable conditionally defines the HAS_DIFFTIME symbol, which indicates to the C program that the difftime() routine is available.

d_dirfd

From d_dirfd.U:

This variable conditionally defines the HAS_DIRFD constant, which indicates to the C program that dirfd() is available to return the file descriptor of a directory stream.

d_dirnamlen

From i_dirent.U:

This variable conditionally defines DIRNAMLEN, which indicates to the C program that the length of directory entry names is provided by a d_namelen field.

d_dlerror

From d_dlerror.U:

This variable conditionally defines the HAS_DLERROR symbol, which indicates to the C program that the dlerror() routine is available.

d_dlopen

From d_dlopen.U:

This variable conditionally defines the HAS_DLOPEN symbol, which indicates to the C program that the dlopen() routine is available.

d_dlsymun

From d_dlsymun.U:

This variable conditionally defines DLSYM_NEEDS_UNDERSCORE, which indicates that we need to prepend an underscore to the symbol name before calling dlsym().

d_dosuid

From d_dosuid.U:

This variable conditionally defines the symbol DOSUID, which tells the C program that it should insert setuid emulation code on hosts which have setuid #! scripts disabled.

d_drand48_r

From d_drand48_r.U:

This variable conditionally defines the HAS_DRAND48_R symbol, which indicates to the C program that the drand48_r() routine is available.

d_drand48proto

From d_drand48proto.U:

This variable conditionally defines the HAS_DRAND48_PROTO symbol, which indicates to the C program that the system provides a prototype for the drand48() function. Otherwise, it is up to the program to supply one.

d_dup2

From d_dup2.U:

This variable conditionally defines HAS_DUP2 if dup2() is available to duplicate file descriptors.

d_eaccess

From d_eaccess.U:

This variable conditionally defines the HAS_EACCESS symbol, which indicates to the C program that the eaccess() routine is available.

d_endgrent

From d_endgrent.U:

This variable conditionally defines the HAS_ENDGRENT symbol, which indicates to the C program that the endgrent() routine is available for sequential access of the group database.

d_endgrent_r

From d_endgrent_r.U:

This variable conditionally defines the HAS_ENDGRENT_R symbol, which indicates to the C program that the endgrent_r() routine is available.

d_endhent

From d_endhent.U:

This variable conditionally defines HAS_ENDHOSTENT if endhostent() is available to close whatever was being used for host queries.

d_endhostent_r

From d_endhostent_r.U:

This variable conditionally defines the HAS_ENDHOSTENT_R symbol, which indicates to the C program that the endhostent_r() routine is available.

d_endnent

From d_endnent.U:

This variable conditionally defines HAS_ENDNETENT if endnetent() is available to close whatever was being used for network queries.

d_endnetent_r

From d_endnetent_r.U:

This variable conditionally defines the HAS_ENDNETENT_R symbol, which indicates to the C program that the endnetent_r() routine is available.

d_endpent

From d_endpent.U:

This variable conditionally defines HAS_ENDPROTOENT if endprotoent() is available to close whatever was being used for protocol queries.

d_endprotoent_r

From d_endprotoent_r.U:

This variable conditionally defines the HAS_ENDPROTOENT_R symbol, which indicates to the C program that the endprotoent_r() routine is available.

d_endpwent

From d_endpwent.U:

This variable conditionally defines the HAS_ENDPWENT symbol, which indicates to the C program that the endpwent() routine is available for sequential access of the passwd database.

d_endpwent_r

From d_endpwent_r.U:

This variable conditionally defines the HAS_ENDPWENT_R symbol, which indicates to the C program that the endpwent_r() routine is available.

d_endsent

From d_endsent.U:

This variable conditionally defines HAS_ENDSERVENT if endservent() is available to close whatever was being used for service queries.

d_endservent_r

From d_endservent_r.U:

This variable conditionally defines the HAS_ENDSERVENT_R symbol, which indicates to the C program that the endservent_r() routine is available.

d_eofnblk

From nblock_io.U:

This variable conditionally defines EOF_NONBLOCK if EOF can be seen when reading from a non-blocking I/O source.

d_eunice

From Guess.U:

This variable conditionally defines the symbols EUNICE and VAX, which alerts the C program that it must deal with ideosyncracies of VMS.

d_faststdio

From d_faststdio.U:

This variable conditionally defines the HAS_FAST_STDIO symbol, which indicates to the C program that the "fast stdio" is available to manipulate the stdio buffers directly.

d_fchdir

From d_fchdir.U:

This variable conditionally defines the HAS_FCHDIR symbol, which indicates to the C program that the fchdir() routine is available.

d_fchmod

From d_fchmod.U:

This variable conditionally defines the HAS_FCHMOD symbol, which indicates to the C program that the fchmod() routine is available to change mode of opened files.

d_fchown

From d_fchown.U:

This variable conditionally defines the HAS_FCHOWN symbol, which indicates to the C program that the fchown() routine is available to change ownership of opened files.

d_fcntl

From d_fcntl.U:

This variable conditionally defines the HAS_FCNTL symbol, and indicates whether the fcntl() function exists

d_fcntl_can_lock

From d_fcntl_can_lock.U:

This variable conditionally defines the FCNTL_CAN_LOCK symbol and indicates whether file locking with fcntl() works.

d_fd_macros

From d_fd_set.U:

This variable contains the eventual value of the HAS_FD_MACROS symbol, which indicates if your C compiler knows about the macros which manipulate an fd_set.

d_fd_set

From d_fd_set.U:

This variable contains the eventual value of the HAS_FD_SET symbol, which indicates if your C compiler knows about the fd_set typedef.

d_fds_bits

From d_fd_set.U:

This variable contains the eventual value of the HAS_FDS_BITS symbol, which indicates if your fd_set typedef contains the fds_bits member. If you have an fd_set typedef, but the dweebs who installed it did a half-fast job and neglected to provide the macros to manipulate an fd_set, HAS_FDS_BITS will let us know how to fix the gaffe.

d_fgetpos

From d_fgetpos.U:

This variable conditionally defines HAS_FGETPOS if fgetpos() is available to get the file position indicator.

d_finite

From d_finite.U:

This variable conditionally defines the HAS_FINITE symbol, which indicates to the C program that the finite() routine is available.

d_finitel

From d_finitel.U:

This variable conditionally defines the HAS_FINITEL symbol, which indicates to the C program that the finitel() routine is available.

d_flexfnam

From d_flexfnam.U:

This variable conditionally defines the FLEXFILENAMES symbol, which indicates that the system supports filenames longer than 14 characters.

d_flock

From d_flock.U:

This variable conditionally defines HAS_FLOCK if flock() is available to do file locking.

d_flockproto

From d_flockproto.U:

This variable conditionally defines the HAS_FLOCK_PROTO symbol, which indicates to the C program that the system provides a prototype for the flock() function. Otherwise, it is up to the program to supply one.

d_fork

From d_fork.U:

This variable conditionally defines the HAS_FORK symbol, which indicates to the C program that the fork() routine is available.

d_fp_class

From d_fp_class.U:

This variable conditionally defines the HAS_FP_CLASS symbol, which indicates to the C program that the fp_class() routine is available.

d_fpathconf

From d_pathconf.U:

This variable conditionally defines the HAS_FPATHCONF symbol, which indicates to the C program that the pathconf() routine is available to determine file-system related limits and options associated with a given open file descriptor.

d_fpclass

From d_fpclass.U:

This variable conditionally defines the HAS_FPCLASS symbol, which indicates to the C program that the fpclass() routine is available.

d_fpclassify

From d_fpclassify.U:

This variable conditionally defines the HAS_FPCLASSIFY symbol, which indicates to the C program that the fpclassify() routine is available.

d_fpclassl

From d_fpclassl.U:

This variable conditionally defines the HAS_FPCLASSL symbol, which indicates to the C program that the fpclassl() routine is available.

d_fpos64_t

From d_fpos64_t.U:

This symbol will be defined if the C compiler supports fpos64_t.

d_frexpl

From d_frexpl.U:

This variable conditionally defines the HAS_FREXPL symbol, which indicates to the C program that the frexpl() routine is available.

d_fs_data_s

From d_fs_data_s.U:

This variable conditionally defines the HAS_STRUCT_FS_DATA symbol, which indicates that the struct fs_data is supported.

d_fseeko

From d_fseeko.U:

This variable conditionally defines the HAS_FSEEKO symbol, which indicates to the C program that the fseeko() routine is available.

d_fsetpos

From d_fsetpos.U:

This variable conditionally defines HAS_FSETPOS if fsetpos() is available to set the file position indicator.

d_fstatfs

From d_fstatfs.U:

This variable conditionally defines the HAS_FSTATFS symbol, which indicates to the C program that the fstatfs() routine is available.

d_fstatvfs

From d_statvfs.U:

This variable conditionally defines the HAS_FSTATVFS symbol, which indicates to the C program that the fstatvfs() routine is available.

d_fsync

From d_fsync.U:

This variable conditionally defines the HAS_FSYNC symbol, which indicates to the C program that the fsync() routine is available.

d_ftello

From d_ftello.U:

This variable conditionally defines the HAS_FTELLO symbol, which indicates to the C program that the ftello() routine is available.

d_ftime

From d_ftime.U:

This variable conditionally defines the HAS_FTIME symbol, which indicates that the ftime() routine exists. The ftime() routine is basically a sub-second accuracy clock.

d_futimes

From f_futimes.U:

This variable conditionally defines the HAS_FUTIMES symbol, which indicates to the C program that the futimes() routine is available.

d_Gconvert

From d_gconvert.U:

This variable holds what Gconvert is defined as to convert floating point numbers into strings. By default, Configure sets this macro to use the first of gconvert, gcvt, or sprintf that pass sprintf-%g-like behaviour tests. If perl is using long doubles, the macro uses the first of the following functions that pass Configure's tests: qgcvt, sprintf (if Configure knows how to make sprintf format long doubles--see sPRIgldbl), gconvert, gcvt, and sprintf (casting to double). The gconvert_preference and gconvert_ld_preference variables can be used to alter Configure's preferences, for doubles and long doubles, respectively. If present, they contain a space-separated list of one or more of the above function names in the order they should be tried.

d_Gconvert may be set to override Configure with a platform- specific function. If this function expects a double, a different value may need to be set by the uselongdouble.cbu call-back unit so that long doubles can be formatted without loss of precision.

d_getcwd

From d_getcwd.U:

This variable conditionally defines the HAS_GETCWD symbol, which indicates to the C program that the getcwd() routine is available to get the current working directory.

d_getespwnam

From d_getespwnam.U:

This variable conditionally defines HAS_GETESPWNAM if getespwnam() is available to retrieve enchanced (shadow) password entries by name.

d_getfsstat

From d_getfsstat.U:

This variable conditionally defines the HAS_GETFSSTAT symbol, which indicates to the C program that the getfsstat() routine is available.

d_getgrent

From d_getgrent.U:

This variable conditionally defines the HAS_GETGRENT symbol, which indicates to the C program that the getgrent() routine is available for sequential access of the group database.

d_getgrent_r

From d_getgrent_r.U:

This variable conditionally defines the HAS_GETGRENT_R symbol, which indicates to the C program that the getgrent_r() routine is available.

d_getgrgid_r

From d_getgrgid_r.U:

This variable conditionally defines the HAS_GETGRGID_R symbol, which indicates to the C program that the getgrgid_r() routine is available.

d_getgrnam_r

From d_getgrnam_r.U:

This variable conditionally defines the HAS_GETGRNAM_R symbol, which indicates to the C program that the getgrnam_r() routine is available.

d_getgrps

From d_getgrps.U:

This variable conditionally defines the HAS_GETGROUPS symbol, which indicates to the C program that the getgroups() routine is available to get the list of process groups.

d_gethbyaddr

From d_gethbyad.U:

This variable conditionally defines the HAS_GETHOSTBYADDR symbol, which indicates to the C program that the gethostbyaddr() routine is available to look up hosts by their IP addresses.

d_gethbyname

From d_gethbynm.U:

This variable conditionally defines the HAS_GETHOSTBYNAME symbol, which indicates to the C program that the gethostbyname() routine is available to look up host names in some data base or other.

d_gethent

From d_gethent.U:

This variable conditionally defines HAS_GETHOSTENT if gethostent() is available to look up host names in some data base or another.

d_gethname

From d_gethname.U:

This variable conditionally defines the HAS_GETHOSTNAME symbol, which indicates to the C program that the gethostname() routine may be used to derive the host name.

d_gethostbyaddr_r

From d_gethostbyaddr_r.U:

This variable conditionally defines the HAS_GETHOSTBYADDR_R symbol, which indicates to the C program that the gethostbyaddr_r() routine is available.

d_gethostbyname_r

From d_gethostbyname_r.U:

This variable conditionally defines the HAS_GETHOSTBYNAME_R symbol, which indicates to the C program that the gethostbyname_r() routine is available.

d_gethostent_r

From d_gethostent_r.U:

This variable conditionally defines the HAS_GETHOSTENT_R symbol, which indicates to the C program that the gethostent_r() routine is available.

d_gethostprotos

From d_gethostprotos.U:

This variable conditionally defines the HAS_GETHOST_PROTOS symbol, which indicates to the C program that <netdb.h> supplies prototypes for the various gethost*() functions. See also netdbtype.U for probing for various netdb types.

d_getitimer

From d_getitimer.U:

This variable conditionally defines the HAS_GETITIMER symbol, which indicates to the C program that the getitimer() routine is available.

d_getlogin

From d_getlogin.U:

This variable conditionally defines the HAS_GETLOGIN symbol, which indicates to the C program that the getlogin() routine is available to get the login name.

d_getlogin_r

From d_getlogin_r.U:

This variable conditionally defines the HAS_GETLOGIN_R symbol, which indicates to the C program that the getlogin_r() routine is available.

d_getmnt

From d_getmnt.U:

This variable conditionally defines the HAS_GETMNT symbol, which indicates to the C program that the getmnt() routine is available to retrieve one or more mount info blocks by filename.

d_getmntent

From d_getmntent.U:

This variable conditionally defines the HAS_GETMNTENT symbol, which indicates to the C program that the getmntent() routine is available to iterate through mounted files to get their mount info.

d_getnbyaddr

From d_getnbyad.U:

This variable conditionally defines the HAS_GETNETBYADDR symbol, which indicates to the C program that the getnetbyaddr() routine is available to look up networks by their IP addresses.

d_getnbyname

From d_getnbynm.U:

This variable conditionally defines the HAS_GETNETBYNAME symbol, which indicates to the C program that the getnetbyname() routine is available to look up networks by their names.

d_getnent

From d_getnent.U:

This variable conditionally defines HAS_GETNETENT if getnetent() is available to look up network names in some data base or another.

d_getnetbyaddr_r

From d_getnetbyaddr_r.U:

This variable conditionally defines the HAS_GETNETBYADDR_R symbol, which indicates to the C program that the getnetbyaddr_r() routine is available.

d_getnetbyname_r

From d_getnetbyname_r.U:

This variable conditionally defines the HAS_GETNETBYNAME_R symbol, which indicates to the C program that the getnetbyname_r() routine is available.

d_getnetent_r

From d_getnetent_r.U:

This variable conditionally defines the HAS_GETNETENT_R symbol, which indicates to the C program that the getnetent_r() routine is available.

d_getnetprotos

From d_getnetprotos.U:

This variable conditionally defines the HAS_GETNET_PROTOS symbol, which indicates to the C program that <netdb.h> supplies prototypes for the various getnet*() functions. See also netdbtype.U for probing for various netdb types.

d_getpagsz

From d_getpagsz.U:

This variable conditionally defines HAS_GETPAGESIZE if getpagesize() is available to get the system page size.

d_getpbyname

From d_getprotby.U:

This variable conditionally defines the HAS_GETPROTOBYNAME symbol, which indicates to the C program that the getprotobyname() routine is available to look up protocols by their name.

d_getpbynumber

From d_getprotby.U:

This variable conditionally defines the HAS_GETPROTOBYNUMBER symbol, which indicates to the C program that the getprotobynumber() routine is available to look up protocols by their number.

d_getpent

From d_getpent.U:

This variable conditionally defines HAS_GETPROTOENT if getprotoent() is available to look up protocols in some data base or another.

d_getpgid

From d_getpgid.U:

This variable conditionally defines the HAS_GETPGID symbol, which indicates to the C program that the getpgid(pid) function is available to get the process group id.

d_getpgrp2

From d_getpgrp2.U:

This variable conditionally defines the HAS_GETPGRP2 symbol, which indicates to the C program that the getpgrp2() (as in DG/UX) routine is available to get the current process group.

d_getpgrp

From d_getpgrp.U:

This variable conditionally defines HAS_GETPGRP if getpgrp() is available to get the current process group.

d_getppid

From d_getppid.U:

This variable conditionally defines the HAS_GETPPID symbol, which indicates to the C program that the getppid() routine is available to get the parent process ID.

d_getprior

From d_getprior.U:

This variable conditionally defines HAS_GETPRIORITY if getpriority() is available to get a process's priority.

d_getprotobyname_r

From d_getprotobyname_r.U:

This variable conditionally defines the HAS_GETPROTOBYNAME_R symbol, which indicates to the C program that the getprotobyname_r() routine is available.

d_getprotobynumber_r

From d_getprotobynumber_r.U:

This variable conditionally defines the HAS_GETPROTOBYNUMBER_R symbol, which indicates to the C program that the getprotobynumber_r() routine is available.

d_getprotoent_r

From d_getprotoent_r.U:

This variable conditionally defines the HAS_GETPROTOENT_R symbol, which indicates to the C program that the getprotoent_r() routine is available.

d_getprotoprotos

From d_getprotoprotos.U:

This variable conditionally defines the HAS_GETPROTO_PROTOS symbol, which indicates to the C program that <netdb.h> supplies prototypes for the various getproto*() functions. See also netdbtype.U for probing for various netdb types.

d_getprpwnam

From d_getprpwnam.U:

This variable conditionally defines HAS_GETPRPWNAM if getprpwnam() is available to retrieve protected (shadow) password entries by name.

d_getpwent

From d_getpwent.U:

This variable conditionally defines the HAS_GETPWENT symbol, which indicates to the C program that the getpwent() routine is available for sequential access of the passwd database.

d_getpwent_r

From d_getpwent_r.U:

This variable conditionally defines the HAS_GETPWENT_R symbol, which indicates to the C program that the getpwent_r() routine is available.

d_getpwnam_r

From d_getpwnam_r.U:

This variable conditionally defines the HAS_GETPWNAM_R symbol, which indicates to the C program that the getpwnam_r() routine is available.

d_getpwuid_r

From d_getpwuid_r.U:

This variable conditionally defines the HAS_GETPWUID_R symbol, which indicates to the C program that the getpwuid_r() routine is available.

d_getsbyname

From d_getsrvby.U:

This variable conditionally defines the HAS_GETSERVBYNAME symbol, which indicates to the C program that the getservbyname() routine is available to look up services by their name.

d_getsbyport

From d_getsrvby.U:

This variable conditionally defines the HAS_GETSERVBYPORT symbol, which indicates to the C program that the getservbyport() routine is available to look up services by their port.

d_getsent

From d_getsent.U:

This variable conditionally defines HAS_GETSERVENT if getservent() is available to look up network services in some data base or another.

d_getservbyname_r

From d_getservbyname_r.U:

This variable conditionally defines the HAS_GETSERVBYNAME_R symbol, which indicates to the C program that the getservbyname_r() routine is available.

d_getservbyport_r

From d_getservbyport_r.U:

This variable conditionally defines the HAS_GETSERVBYPORT_R symbol, which indicates to the C program that the getservbyport_r() routine is available.

d_getservent_r

From d_getservent_r.U:

This variable conditionally defines the HAS_GETSERVENT_R symbol, which indicates to the C program that the getservent_r() routine is available.

d_getservprotos

From d_getservprotos.U:

This variable conditionally defines the HAS_GETSERV_PROTOS symbol, which indicates to the C program that <netdb.h> supplies prototypes for the various getserv*() functions. See also netdbtype.U for probing for various netdb types.

d_getspnam

From d_getspnam.U:

This variable conditionally defines HAS_GETSPNAM if getspnam() is available to retrieve SysV shadow password entries by name.

d_getspnam_r

From d_getspnam_r.U:

This variable conditionally defines the HAS_GETSPNAM_R symbol, which indicates to the C program that the getspnam_r() routine is available.

d_gettimeod

From d_ftime.U:

This variable conditionally defines the HAS_GETTIMEOFDAY symbol, which indicates that the gettimeofday() system call exists (to obtain a sub-second accuracy clock). You should probably include <sys/resource.h>.

d_gmtime_r

From d_gmtime_r.U:

This variable conditionally defines the HAS_GMTIME_R symbol, which indicates to the C program that the gmtime_r() routine is available.

d_gnulibc

From d_gnulibc.U:

Defined if we're dealing with the GNU C Library.

d_grpasswd

From i_grp.U:

This variable conditionally defines GRPASSWD, which indicates that struct group in <grp.h> contains gr_passwd.

d_hasmntopt

From d_hasmntopt.U:

This variable conditionally defines the HAS_HASMNTOPT symbol, which indicates to the C program that the hasmntopt() routine is available to query the mount options of file systems.

d_htonl

From d_htonl.U:

This variable conditionally defines HAS_HTONL if htonl() and its friends are available to do network order byte swapping.

d_ilogbl

From d_ilogbl.U:

This variable conditionally defines the HAS_ILOGBL symbol, which indicates to the C program that the ilogbl() routine is available. If scalbnl is also present we can emulate frexpl.

d_inc_version_list

From inc_version_list.U:

This variable conditionally defines PERL_INC_VERSION_LIST. It is set to undef when PERL_INC_VERSION_LIST is empty.

d_index

From d_strchr.U:

This variable conditionally defines HAS_INDEX if index() and rindex() are available for string searching.

d_inetaton

From d_inetaton.U:

This variable conditionally defines the HAS_INET_ATON symbol, which indicates to the C program that the inet_aton() function is available to parse IP address dotted-quad strings.

d_int64_t

From d_int64_t.U:

This symbol will be defined if the C compiler supports int64_t.

d_isascii

From d_isascii.U:

This variable conditionally defines the HAS_ISASCII constant, which indicates to the C program that isascii() is available.

d_isfinite

From d_isfinite.U:

This variable conditionally defines the HAS_ISFINITE symbol, which indicates to the C program that the isfinite() routine is available.

d_isinf

From d_isinf.U:

This variable conditionally defines the HAS_ISINF symbol, which indicates to the C program that the isinf() routine is available.

d_isnan

From d_isnan.U:

This variable conditionally defines the HAS_ISNAN symbol, which indicates to the C program that the isnan() routine is available.

d_isnanl

From d_isnanl.U:

This variable conditionally defines the HAS_ISNANL symbol, which indicates to the C program that the isnanl() routine is available.

d_killpg

From d_killpg.U:

This variable conditionally defines the HAS_KILLPG symbol, which indicates to the C program that the killpg() routine is available to kill process groups.

d_lchown

From d_lchown.U:

This variable conditionally defines the HAS_LCHOWN symbol, which indicates to the C program that the lchown() routine is available to operate on a symbolic link (instead of following the link).

d_ldbl_dig

From d_ldbl_dig.U:

This variable conditionally defines d_ldbl_dig if this system's header files provide LDBL_DIG, which is the number of significant digits in a long double precision number.

d_link

From d_link.U:

This variable conditionally defines HAS_LINK if link() is available to create hard links.

d_localtime_r

From d_localtime_r.U:

This variable conditionally defines the HAS_LOCALTIME_R symbol, which indicates to the C program that the localtime_r() routine is available.

d_locconv

From d_locconv.U:

This variable conditionally defines HAS_LOCALECONV if localeconv() is available for numeric and monetary formatting conventions.

d_lockf

From d_lockf.U:

This variable conditionally defines HAS_LOCKF if lockf() is available to do file locking.

d_longdbl

From d_longdbl.U:

This variable conditionally defines HAS_LONG_DOUBLE if the long double type is supported.

d_longlong

From d_longlong.U:

This variable conditionally defines HAS_LONG_LONG if the long long type is supported.

d_lseekproto

From d_lseekproto.U:

This variable conditionally defines the HAS_LSEEK_PROTO symbol, which indicates to the C program that the system provides a prototype for the lseek() function. Otherwise, it is up to the program to supply one.

d_lstat

From d_lstat.U:

This variable conditionally defines HAS_LSTAT if lstat() is available to do file stats on symbolic links.

d_madvise

From d_madvise.U:

This variable conditionally defines HAS_MADVISE if madvise() is available to map a file into memory.

d_malloc_size

From d_malloc_size.U:

This symbol, if defined, indicates that the malloc_size routine is available for use.

d_malloc_good_size

From d_malloc_good_size.U:

This symbol, if defined, indicates that the malloc_good_size routine is available for use.

d_mblen

From d_mblen.U:

This variable conditionally defines the HAS_MBLEN symbol, which indicates to the C program that the mblen() routine is available to find the number of bytes in a multibye character.

d_mbstowcs

From d_mbstowcs.U:

This variable conditionally defines the HAS_MBSTOWCS symbol, which indicates to the C program that the mbstowcs() routine is available to convert a multibyte string into a wide character string.

d_mbtowc

From d_mbtowc.U:

This variable conditionally defines the HAS_MBTOWC symbol, which indicates to the C program that the mbtowc() routine is available to convert multibyte to a wide character.

d_memchr

From d_memchr.U:

This variable conditionally defines the HAS_MEMCHR symbol, which indicates to the C program that the memchr() routine is available to locate characters within a C string.

d_memcmp

From d_memcmp.U:

This variable conditionally defines the HAS_MEMCMP symbol, which indicates to the C program that the memcmp() routine is available to compare blocks of memory.

d_memcpy

From d_memcpy.U:

This variable conditionally defines the HAS_MEMCPY symbol, which indicates to the C program that the memcpy() routine is available to copy blocks of memory.

d_memmove

From d_memmove.U:

This variable conditionally defines the HAS_MEMMOVE symbol, which indicates to the C program that the memmove() routine is available to copy potentatially overlapping blocks of memory.

d_memset

From d_memset.U:

This variable conditionally defines the HAS_MEMSET symbol, which indicates to the C program that the memset() routine is available to set blocks of memory.

d_mkdir

From d_mkdir.U:

This variable conditionally defines the HAS_MKDIR symbol, which indicates to the C program that the mkdir() routine is available to create directories..

d_mkdtemp

From d_mkdtemp.U:

This variable conditionally defines the HAS_MKDTEMP symbol, which indicates to the C program that the mkdtemp() routine is available to exclusively create a uniquely named temporary directory.

d_mkfifo

From d_mkfifo.U:

This variable conditionally defines the HAS_MKFIFO symbol, which indicates to the C program that the mkfifo() routine is available.

d_mkstemp

From d_mkstemp.U:

This variable conditionally defines the HAS_MKSTEMP symbol, which indicates to the C program that the mkstemp() routine is available to exclusively create and open a uniquely named temporary file.

d_mkstemps

From d_mkstemps.U:

This variable conditionally defines the HAS_MKSTEMPS symbol, which indicates to the C program that the mkstemps() routine is available to exclusively create and open a uniquely named (with a suffix) temporary file.

d_mktime

From d_mktime.U:

This variable conditionally defines the HAS_MKTIME symbol, which indicates to the C program that the mktime() routine is available.

d_mmap

From d_mmap.U:

This variable conditionally defines HAS_MMAP if mmap() is available to map a file into memory.

d_modfl

From d_modfl.U:

This variable conditionally defines the HAS_MODFL symbol, which indicates to the C program that the modfl() routine is available.

d_modfl_pow32_bug

From d_modfl.U:

This variable conditionally defines the HAS_MODFL_POW32_BUG symbol, which indicates that modfl() is broken for long doubles >= pow(2, 32). For example from 4294967303.150000 one would get 4294967302.000000 and 1.150000. The bug has been seen in certain versions of glibc, release 2.2.2 is known to be okay.

d_modflproto

From d_modfl.U:

This symbol, if defined, indicates that the system provides a prototype for the modfl() function. Otherwise, it is up to the program to supply one. C99 says it should be long double modfl(long double, long double *);

d_mprotect

From d_mprotect.U:

This variable conditionally defines HAS_MPROTECT if mprotect() is available to modify the access protection of a memory mapped file.

d_msg

From d_msg.U:

This variable conditionally defines the HAS_MSG symbol, which indicates that the entire msg*(2) library is present.

d_msg_ctrunc

From d_socket.U:

This variable conditionally defines the HAS_MSG_CTRUNC symbol, which indicates that the MSG_CTRUNC is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_msg_dontroute

From d_socket.U:

This variable conditionally defines the HAS_MSG_DONTROUTE symbol, which indicates that the MSG_DONTROUTE is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_msg_oob

From d_socket.U:

This variable conditionally defines the HAS_MSG_OOB symbol, which indicates that the MSG_OOB is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_msg_peek

From d_socket.U:

This variable conditionally defines the HAS_MSG_PEEK symbol, which indicates that the MSG_PEEK is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_msg_proxy

From d_socket.U:

This variable conditionally defines the HAS_MSG_PROXY symbol, which indicates that the MSG_PROXY is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_msgctl

From d_msgctl.U:

This variable conditionally defines the HAS_MSGCTL symbol, which indicates to the C program that the msgctl() routine is available.

d_msgget

From d_msgget.U:

This variable conditionally defines the HAS_MSGGET symbol, which indicates to the C program that the msgget() routine is available.

d_msghdr_s

From d_msghdr_s.U:

This variable conditionally defines the HAS_STRUCT_MSGHDR symbol, which indicates that the struct msghdr is supported.

d_msgrcv

From d_msgrcv.U:

This variable conditionally defines the HAS_MSGRCV symbol, which indicates to the C program that the msgrcv() routine is available.

d_msgsnd

From d_msgsnd.U:

This variable conditionally defines the HAS_MSGSND symbol, which indicates to the C program that the msgsnd() routine is available.

d_msync

From d_msync.U:

This variable conditionally defines HAS_MSYNC if msync() is available to synchronize a mapped file.

d_munmap

From d_munmap.U:

This variable conditionally defines HAS_MUNMAP if munmap() is available to unmap a region mapped by mmap().

d_mymalloc

From mallocsrc.U:

This variable conditionally defines MYMALLOC in case other parts of the source want to take special action if MYMALLOC is used. This may include different sorts of profiling or error detection.

d_nanosleep

From d_nanosleep.U:

This variable conditionally defines HAS_NANOSLEEP if nanosleep() is available to sleep with 1E-9 sec accuracy.

d_nice

From d_nice.U:

This variable conditionally defines the HAS_NICE symbol, which indicates to the C program that the nice() routine is available.

d_nl_langinfo

From d_nl_langinfo.U:

This variable conditionally defines the HAS_NL_LANGINFO symbol, which indicates to the C program that the nl_langinfo() routine is available.

d_nv_preserves_uv

From perlxv.U:

This variable indicates whether a variable of type nvtype can preserve all the bits a variable of type uvtype.

d_nv_zero_is_allbits_zero

From perlxv.U:

This variable indicates whether a variable of type nvtype stores 0.0 in memory as all bits zero.

d_off64_t

From d_off64_t.U:

This symbol will be defined if the C compiler supports off64_t.

d_old_pthread_create_joinable

From d_pthrattrj.U:

This variable conditionally defines pthread_create_joinable. undef if pthread.h defines PTHREAD_CREATE_JOINABLE.

d_oldpthreads

From usethreads.U:

This variable conditionally defines the OLD_PTHREADS_API symbol, and indicates that Perl should be built to use the old draft POSIX threads API. This is only potentially meaningful if usethreads is set.

d_oldsock

From d_socket.U:

This variable conditionally defines the OLDSOCKET symbol, which indicates that the BSD socket interface is based on 4.1c and not 4.2.

d_open3

From d_open3.U:

This variable conditionally defines the HAS_OPEN3 manifest constant, which indicates to the C program that the 3 argument version of the open(2) function is available.

d_pathconf

From d_pathconf.U:

This variable conditionally defines the HAS_PATHCONF symbol, which indicates to the C program that the pathconf() routine is available to determine file-system related limits and options associated with a given filename.

d_pause

From d_pause.U:

This variable conditionally defines the HAS_PAUSE symbol, which indicates to the C program that the pause() routine is available to suspend a process until a signal is received.

d_perl_otherlibdirs

From otherlibdirs.U:

This variable conditionally defines PERL_OTHERLIBDIRS, which contains a colon-separated set of paths for the perl binary to include in @INC. See also otherlibdirs.

d_phostname

From d_gethname.U:

This variable conditionally defines the HAS_PHOSTNAME symbol, which contains the shell command which, when fed to popen(), may be used to derive the host name.

d_pipe

From d_pipe.U:

This variable conditionally defines the HAS_PIPE symbol, which indicates to the C program that the pipe() routine is available to create an inter-process channel.

d_poll

From d_poll.U:

This variable conditionally defines the HAS_POLL symbol, which indicates to the C program that the poll() routine is available to poll active file descriptors.

d_portable

From d_portable.U:

This variable conditionally defines the PORTABLE symbol, which indicates to the C program that it should not assume that it is running on the machine it was compiled on.

d_PRId64

From quadfio.U:

This variable conditionally defines the PERL_PRId64 symbol, which indiciates that stdio has a symbol to print 64-bit decimal numbers.

d_PRIeldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles.

d_PRIEUldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles. The U in the name is to separate this from d_PRIeldbl so that even case-blind systems can see the difference.

d_PRIfldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles.

d_PRIFUldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles. The U in the name is to separate this from d_PRIfldbl so that even case-blind systems can see the difference.

d_PRIgldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles.

d_PRIGUldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to print long doubles. The U in the name is to separate this from d_PRIgldbl so that even case-blind systems can see the difference.

d_PRIi64

From quadfio.U:

This variable conditionally defines the PERL_PRIi64 symbol, which indiciates that stdio has a symbol to print 64-bit decimal numbers.

d_PRIo64

From quadfio.U:

This variable conditionally defines the PERL_PRIo64 symbol, which indiciates that stdio has a symbol to print 64-bit octal numbers.

d_PRIu64

From quadfio.U:

This variable conditionally defines the PERL_PRIu64 symbol, which indiciates that stdio has a symbol to print 64-bit unsigned decimal numbers.

d_PRIx64

From quadfio.U:

This variable conditionally defines the PERL_PRIx64 symbol, which indiciates that stdio has a symbol to print 64-bit hexadecimal numbers.

d_PRIXU64

From quadfio.U:

This variable conditionally defines the PERL_PRIXU64 symbol, which indiciates that stdio has a symbol to print 64-bit hExADECimAl numbers. The U in the name is to separate this from d_PRIx64 so that even case-blind systems can see the difference.

d_procselfexe

From d_procselfexe.U:

Defined if $procselfexe is symlink to the absolute pathname of the executing program.

d_pthread_atfork

From d_pthread_atfork.U:

This variable conditionally defines the HAS_PTHREAD_ATFORK symbol, which indicates to the C program that the pthread_atfork() routine is available.

d_pthread_attr_setscope

From d_pthread_attr_ss.U:

This variable conditionally defines HAS_PTHREAD_ATTR_SETSCOPE if pthread_attr_setscope() is available to set the contention scope attribute of a thread attribute object.

d_pthread_yield

From d_pthread_y.U:

This variable conditionally defines the HAS_PTHREAD_YIELD symbol if the pthread_yield routine is available to yield the execution of the current thread.

d_pwage

From i_pwd.U:

This variable conditionally defines PWAGE, which indicates that struct passwd contains pw_age.

d_pwchange

From i_pwd.U:

This variable conditionally defines PWCHANGE, which indicates that struct passwd contains pw_change.

d_pwclass

From i_pwd.U:

This variable conditionally defines PWCLASS, which indicates that struct passwd contains pw_class.

d_pwcomment

From i_pwd.U:

This variable conditionally defines PWCOMMENT, which indicates that struct passwd contains pw_comment.

d_pwexpire

From i_pwd.U:

This variable conditionally defines PWEXPIRE, which indicates that struct passwd contains pw_expire.

d_pwgecos

From i_pwd.U:

This variable conditionally defines PWGECOS, which indicates that struct passwd contains pw_gecos.

d_pwpasswd

From i_pwd.U:

This variable conditionally defines PWPASSWD, which indicates that struct passwd contains pw_passwd.

d_pwquota

From i_pwd.U:

This variable conditionally defines PWQUOTA, which indicates that struct passwd contains pw_quota.

d_qgcvt

From d_qgcvt.U:

This variable conditionally defines the HAS_QGCVT symbol, which indicates to the C program that the qgcvt() routine is available.

d_quad

From quadtype.U:

This variable, if defined, tells that there's a 64-bit integer type, quadtype.

d_random_r

From d_random_r.U:

This variable conditionally defines the HAS_RANDOM_R symbol, which indicates to the C program that the random_r() routine is available.

d_readdir64_r

From d_readdir64_r.U:

This variable conditionally defines the HAS_READDIR64_R symbol, which indicates to the C program that the readdir64_r() routine is available.

d_readdir

From d_readdir.U:

This variable conditionally defines HAS_READDIR if readdir() is available to read directory entries.

d_readdir_r

From d_readdir_r.U:

This variable conditionally defines the HAS_READDIR_R symbol, which indicates to the C program that the readdir_r() routine is available.

d_readlink

From d_readlink.U:

This variable conditionally defines the HAS_READLINK symbol, which indicates to the C program that the readlink() routine is available to read the value of a symbolic link.

d_readv

From d_readv.U:

This variable conditionally defines the HAS_READV symbol, which indicates to the C program that the readv() routine is available.

d_recvmsg

From d_recvmsg.U:

This variable conditionally defines the HAS_RECVMSG symbol, which indicates to the C program that the recvmsg() routine is available.

d_rename

From d_rename.U:

This variable conditionally defines the HAS_RENAME symbol, which indicates to the C program that the rename() routine is available to rename files.

d_rewinddir

From d_readdir.U:

This variable conditionally defines HAS_REWINDDIR if rewinddir() is available.

d_rmdir

From d_rmdir.U:

This variable conditionally defines HAS_RMDIR if rmdir() is available to remove directories.

d_safebcpy

From d_safebcpy.U:

This variable conditionally defines the HAS_SAFE_BCOPY symbol if the bcopy() routine can do overlapping copies. Normally, you should probably use memmove().

d_safemcpy

From d_safemcpy.U:

This variable conditionally defines the HAS_SAFE_MEMCPY symbol if the memcpy() routine can do overlapping copies. For overlapping copies, memmove() should be used, if available.

d_sanemcmp

From d_sanemcmp.U:

This variable conditionally defines the HAS_SANE_MEMCMP symbol if the memcpy() routine is available and can be used to compare relative magnitudes of chars with their high bits set.

d_sbrkproto

From d_sbrkproto.U:

This variable conditionally defines the HAS_SBRK_PROTO symbol, which indicates to the C program that the system provides a prototype for the sbrk() function. Otherwise, it is up to the program to supply one.

d_scalbnl

From d_scalbnl.U:

This variable conditionally defines the HAS_SCALBNL symbol, which indicates to the C program that the scalbnl() routine is available. If ilogbl is also present we can emulate frexpl.

d_sched_yield

From d_pthread_y.U:

This variable conditionally defines the HAS_SCHED_YIELD symbol if the sched_yield routine is available to yield the execution of the current thread.

d_scm_rights

From d_socket.U:

This variable conditionally defines the HAS_SCM_RIGHTS symbol, which indicates that the SCM_RIGHTS is available. #ifdef is not enough because it may be an enum, glibc has been known to do this.

d_SCNfldbl

From longdblfio.U:

This variable conditionally defines the PERL_PRIfldbl symbol, which indiciates that stdio has a symbol to scan long doubles.

d_seekdir

From d_readdir.U:

This variable conditionally defines HAS_SEEKDIR if seekdir() is available.

d_select

From d_select.U:

This variable conditionally defines HAS_SELECT if select() is available to select active file descriptors. A <sys/time.h> inclusion may be necessary for the timeout field.

d_sem

From d_sem.U:

This variable conditionally defines the HAS_SEM symbol, which indicates that the entire sem*(2) library is present.

d_semctl

From d_semctl.U:

This variable conditionally defines the HAS_SEMCTL symbol, which indicates to the C program that the semctl() routine is available.

d_semctl_semid_ds

From d_union_semun.U:

This variable conditionally defines USE_SEMCTL_SEMID_DS, which indicates that struct semid_ds * is to be used for semctl IPC_STAT.

d_semctl_semun

From d_union_semun.U:

This variable conditionally defines USE_SEMCTL_SEMUN, which indicates that union semun is to be used for semctl IPC_STAT.

d_semget

From d_semget.U:

This variable conditionally defines the HAS_SEMGET symbol, which indicates to the C program that the semget() routine is available.

d_semop

From d_semop.U:

This variable conditionally defines the HAS_SEMOP symbol, which indicates to the C program that the semop() routine is available.

d_sendmsg

From d_sendmsg.U:

This variable conditionally defines the HAS_SENDMSG symbol, which indicates to the C program that the sendmsg() routine is available.

d_setegid

From d_setegid.U:

This variable conditionally defines the HAS_SETEGID symbol, which indicates to the C program that the setegid() routine is available to change the effective gid of the current program.

d_seteuid

From d_seteuid.U:

This variable conditionally defines the HAS_SETEUID symbol, which indicates to the C program that the seteuid() routine is available to change the effective uid of the current program.

d_setgrent

From d_setgrent.U:

This variable conditionally defines the HAS_SETGRENT symbol, which indicates to the C program that the setgrent() routine is available for initializing sequential access to the group database.

d_setgrent_r

From d_setgrent_r.U:

This variable conditionally defines the HAS_SETGRENT_R symbol, which indicates to the C program that the setgrent_r() routine is available.

d_setgrps

From d_setgrps.U:

This variable conditionally defines the HAS_SETGROUPS symbol, which indicates to the C program that the setgroups() routine is available to set the list of process groups.

d_sethent

From d_sethent.U:

This variable conditionally defines HAS_SETHOSTENT if sethostent() is available.

d_sethostent_r

From d_sethostent_r.U:

This variable conditionally defines the HAS_SETHOSTENT_R symbol, which indicates to the C program that the sethostent_r() routine is available.

d_setitimer

From d_setitimer.U:

This variable conditionally defines the HAS_SETITIMER symbol, which indicates to the C program that the setitimer() routine is available.

d_setlinebuf

From d_setlnbuf.U:

This variable conditionally defines the HAS_SETLINEBUF symbol, which indicates to the C program that the setlinebuf() routine is available to change stderr or stdout from block-buffered or unbuffered to a line-buffered mode.

d_setlocale

From d_setlocale.U:

This variable conditionally defines HAS_SETLOCALE if setlocale() is available to handle locale-specific ctype implementations.

d_setlocale_r

From d_setlocale_r.U:

This variable conditionally defines the HAS_SETLOCALE_R symbol, which indicates to the C program that the setlocale_r() routine is available.

d_setnent

From d_setnent.U:

This variable conditionally defines HAS_SETNETENT if setnetent() is available.

d_setnetent_r

From d_setnetent_r.U:

This variable conditionally defines the HAS_SETNETENT_R symbol, which indicates to the C program that the setnetent_r() routine is available.

d_setpent

From d_setpent.U:

This variable conditionally defines HAS_SETPROTOENT if setprotoent() is available.

d_setpgid

From d_setpgid.U:

This variable conditionally defines the HAS_SETPGID symbol if the setpgid(pid, gpid) function is available to set process group ID.

d_setpgrp2

From d_setpgrp2.U:

This variable conditionally defines the HAS_SETPGRP2 symbol, which indicates to the C program that the setpgrp2() (as in DG/UX) routine is available to set the current process group.

d_setpgrp

From d_setpgrp.U:

This variable conditionally defines HAS_SETPGRP if setpgrp() is available to set the current process group.

d_setprior

From d_setprior.U:

This variable conditionally defines HAS_SETPRIORITY if setpriority() is available to set a process's priority.

d_setproctitle

From d_setproctitle.U:

This variable conditionally defines the HAS_SETPROCTITLE symbol, which indicates to the C program that the setproctitle() routine is available.

d_setprotoent_r

From d_setprotoent_r.U:

This variable conditionally defines the HAS_SETPROTOENT_R symbol, which indicates to the C program that the setprotoent_r() routine is available.

d_setpwent

From d_setpwent.U:

This variable conditionally defines the HAS_SETPWENT symbol, which indicates to the C program that the setpwent() routine is available for initializing sequential access to the passwd database.

d_setpwent_r

From d_setpwent_r.U:

This variable conditionally defines the HAS_SETPWENT_R symbol, which indicates to the C program that the setpwent_r() routine is available.

d_setregid

From d_setregid.U:

This variable conditionally defines HAS_SETREGID if setregid() is available to change the real and effective gid of the current process.

d_setresgid

From d_setregid.U:

This variable conditionally defines HAS_SETRESGID if setresgid() is available to change the real, effective and saved gid of the current process.

d_setresuid

From d_setreuid.U:

This variable conditionally defines HAS_SETREUID if setresuid() is available to change the real, effective and saved uid of the current process.

d_setreuid

From d_setreuid.U:

This variable conditionally defines HAS_SETREUID if setreuid() is available to change the real and effective uid of the current process.

d_setrgid

From d_setrgid.U:

This variable conditionally defines the HAS_SETRGID symbol, which indicates to the C program that the setrgid() routine is available to change the real gid of the current program.

d_setruid

From d_setruid.U:

This variable conditionally defines the HAS_SETRUID symbol, which indicates to the C program that the setruid() routine is available to change the real uid of the current program.

d_setsent

From d_setsent.U:

This variable conditionally defines HAS_SETSERVENT if setservent() is available.

d_setservent_r

From d_setservent_r.U:

This variable conditionally defines the HAS_SETSERVENT_R symbol, which indicates to the C program that the setservent_r() routine is available.

d_setsid

From d_setsid.U:

This variable conditionally defines HAS_SETSID if setsid() is available to set the process group ID.

d_setvbuf

From d_setvbuf.U:

This variable conditionally defines the HAS_SETVBUF symbol, which indicates to the C program that the setvbuf() routine is available to change buffering on an open stdio stream.

d_sfio

From d_sfio.U:

This variable conditionally defines the USE_SFIO symbol, and indicates whether sfio is available (and should be used).

d_shm

From d_shm.U:

This variable conditionally defines the HAS_SHM symbol, which indicates that the entire shm*(2) library is present.

d_shmat

From d_shmat.U:

This variable conditionally defines the HAS_SHMAT symbol, which indicates to the C program that the shmat() routine is available.

d_shmatprototype

From d_shmat.U:

This variable conditionally defines the HAS_SHMAT_PROTOTYPE symbol, which indicates that sys/shm.h has a prototype for shmat.

d_shmctl

From d_shmctl.U:

This variable conditionally defines the HAS_SHMCTL symbol, which indicates to the C program that the shmctl() routine is available.

d_shmdt

From d_shmdt.U:

This variable conditionally defines the HAS_SHMDT symbol, which indicates to the C program that the shmdt() routine is available.

d_shmget

From d_shmget.U:

This variable conditionally defines the HAS_SHMGET symbol, which indicates to the C program that the shmget() routine is available.

d_sigaction

From d_sigaction.U:

This variable conditionally defines the HAS_SIGACTION symbol, which indicates that the Vr4 sigaction() routine is available.

d_sigprocmask

From d_sigprocmask.U:

This variable conditionally defines HAS_SIGPROCMASK if sigprocmask() is available to examine or change the signal mask of the calling process.

d_sigsetjmp

From d_sigsetjmp.U:

This variable conditionally defines the HAS_SIGSETJMP symbol, which indicates that the sigsetjmp() routine is available to call setjmp() and optionally save the process's signal mask.

d_sitearch

From sitearch.U:

This variable conditionally defines SITEARCH to hold the pathname of architecture-dependent library files for $package. If $sitearch is the same as $archlib, then this is set to undef.

d_sockatmark

From d_sockatmark.U:

This variable conditionally defines the HAS_SOCKATMARK symbol, which indicates to the C program that the sockatmark() routine is available.

d_sockatmarkproto

From d_sockatmarkproto.U:

This variable conditionally defines the HAS_SOCKATMARK_PROTO symbol, which indicates to the C program that the system provides a prototype for the sockatmark() function. Otherwise, it is up to the program to supply one.

d_socket

From d_socket.U:

This variable conditionally defines HAS_SOCKET, which indicates that the BSD socket interface is supported.

d_socklen_t

From d_socklen_t.U:

This symbol will be defined if the C compiler supports socklen_t.

d_sockpair

From d_socket.U:

This variable conditionally defines the HAS_SOCKETPAIR symbol, which indicates that the BSD socketpair() is supported.

d_socks5_init

From d_socks5_init.U:

This variable conditionally defines the HAS_SOCKS5_INIT symbol, which indicates to the C program that the socks5_init() routine is available.

d_sprintf_returns_strlen

From d_sprintf_returns_strlen.U:

This variable defines whether sprintf returns the length of the string (as per the ANSI spec). Some C libraries retain compatibility with pre-ANSI C and return a pointer to the passed in buffer; for these this variable will be undef.

d_sqrtl

From d_sqrtl.U:

This variable conditionally defines the HAS_SQRTL symbol, which indicates to the C program that the sqrtl() routine is available.

d_srand48_r

From d_srand48_r.U:

This variable conditionally defines the HAS_SRAND48_R symbol, which indicates to the C program that the srand48_r() routine is available.

d_srandom_r

From d_srandom_r.U:

This variable conditionally defines the HAS_SRANDOM_R symbol, which indicates to the C program that the srandom_r() routine is available.

d_sresgproto

From d_sresgproto.U:

This variable conditionally defines the HAS_SETRESGID_PROTO symbol, which indicates to the C program that the system provides a prototype for the setresgid() function. Otherwise, it is up to the program to supply one.

d_sresuproto

From d_sresuproto.U:

This variable conditionally defines the HAS_SETRESUID_PROTO symbol, which indicates to the C program that the system provides a prototype for the setresuid() function. Otherwise, it is up to the program to supply one.

d_statblks

From d_statblks.U:

This variable conditionally defines USE_STAT_BLOCKS if this system has a stat structure declaring st_blksize and st_blocks.

d_statfs_f_flags

From d_statfs_f_flags.U:

This variable conditionally defines the HAS_STRUCT_STATFS_F_FLAGS symbol, which indicates to struct statfs from has f_flags member. This kind of struct statfs is coming from sys/mount.h (BSD), not from sys/statfs.h (SYSV).

d_statfs_s

From d_statfs_s.U:

This variable conditionally defines the HAS_STRUCT_STATFS symbol, which indicates that the struct statfs is supported.

d_statvfs

From d_statvfs.U:

This variable conditionally defines the HAS_STATVFS symbol, which indicates to the C program that the statvfs() routine is available.

d_stdio_cnt_lval

From d_stdstdio.U:

This variable conditionally defines STDIO_CNT_LVALUE if the FILE_cnt macro can be used as an lvalue.

d_stdio_ptr_lval

From d_stdstdio.U:

This variable conditionally defines STDIO_PTR_LVALUE if the FILE_ptr macro can be used as an lvalue.

d_stdio_ptr_lval_nochange_cnt

From d_stdstdio.U:

This symbol is defined if using the FILE_ptr macro as an lvalue to increase the pointer by n leaves File_cnt(fp) unchanged.

d_stdio_ptr_lval_sets_cnt

From d_stdstdio.U:

This symbol is defined if using the FILE_ptr macro as an lvalue to increase the pointer by n has the side effect of decreasing the value of File_cnt(fp) by n.

d_stdio_stream_array

From stdio_streams.U:

This variable tells whether there is an array holding the stdio streams.

d_stdiobase

From d_stdstdio.U:

This variable conditionally defines USE_STDIO_BASE if this system has a FILE structure declaring a usable _base field (or equivalent) in stdio.h.

d_stdstdio

From d_stdstdio.U:

This variable conditionally defines USE_STDIO_PTR if this system has a FILE structure declaring usable _ptr and _cnt fields (or equivalent) in stdio.h.

d_strchr

From d_strchr.U:

This variable conditionally defines HAS_STRCHR if strchr() and strrchr() are available for string searching.

d_strcoll

From d_strcoll.U:

This variable conditionally defines HAS_STRCOLL if strcoll() is available to compare strings using collating information.

d_strctcpy

From d_strctcpy.U:

This variable conditionally defines the USE_STRUCT_COPY symbol, which indicates to the C program that this C compiler knows how to copy structures.

d_strerrm

From d_strerror.U:

This variable holds what Strerrr is defined as to translate an error code condition into an error message string. It could be strerror or a more complex macro emulating strrror with sys_errlist[], or the unknown string when both strerror and sys_errlist are missing.

d_strerror

From d_strerror.U:

This variable conditionally defines HAS_STRERROR if strerror() is available to translate error numbers to strings.

d_strerror_r

From d_strerror_r.U:

This variable conditionally defines the HAS_STRERROR_R symbol, which indicates to the C program that the strerror_r() routine is available.

d_strftime

From d_strftime.U:

This variable conditionally defines the HAS_STRFTIME symbol, which indicates to the C program that the strftime() routine is available.

d_strlcat

From d_strlcat.U:

This variable conditionally defines the HAS_STRLCAT symbol, which indicates to the C program that the strlcat () routine is available.

d_strlcpy

From d_strlcpy.U:

This variable conditionally defines the HAS_STRLCPY symbol, which indicates to the C program that the strlcpy () routine is available.

d_strtod

From d_strtod.U:

This variable conditionally defines the HAS_STRTOD symbol, which indicates to the C program that the strtod() routine is available to provide better numeric string conversion than atof().

d_strtol

From d_strtol.U:

This variable conditionally defines the HAS_STRTOL symbol, which indicates to the C program that the strtol() routine is available to provide better numeric string conversion than atoi() and friends.

d_strtold

From d_strtold.U:

This variable conditionally defines the HAS_STRTOLD symbol, which indicates to the C program that the strtold() routine is available.

d_strtoll

From d_strtoll.U:

This variable conditionally defines the HAS_STRTOLL symbol, which indicates to the C program that the strtoll() routine is available.

d_strtoq

From d_strtoq.U:

This variable conditionally defines the HAS_STRTOQ symbol, which indicates to the C program that the strtoq() routine is available.

d_strtoul

From d_strtoul.U:

This variable conditionally defines the HAS_STRTOUL symbol, which indicates to the C program that the strtoul() routine is available to provide conversion of strings to unsigned long.

d_strtoull

From d_strtoull.U:

This variable conditionally defines the HAS_STRTOULL symbol, which indicates to the C program that the strtoull() routine is available.

d_strtouq

From d_strtouq.U:

This variable conditionally defines the HAS_STRTOUQ symbol, which indicates to the C program that the strtouq() routine is available.

d_strxfrm

From d_strxfrm.U:

This variable conditionally defines HAS_STRXFRM if strxfrm() is available to transform strings.

d_suidsafe

From d_dosuid.U:

This variable conditionally defines SETUID_SCRIPTS_ARE_SECURE_NOW if setuid scripts can be secure. This test looks in /dev/fd/.

d_symlink

From d_symlink.U:

This variable conditionally defines the HAS_SYMLINK symbol, which indicates to the C program that the symlink() routine is available to create symbolic links.

d_syscall

From d_syscall.U:

This variable conditionally defines HAS_SYSCALL if syscall() is available call arbitrary system calls.

d_syscallproto

From d_syscallproto.U:

This variable conditionally defines the HAS_SYSCALL_PROTO symbol, which indicates to the C program that the system provides a prototype for the syscall() function. Otherwise, it is up to the program to supply one.

d_sysconf

From d_sysconf.U:

This variable conditionally defines the HAS_SYSCONF symbol, which indicates to the C program that the sysconf() routine is available to determine system related limits and options.

d_sysernlst

From d_strerror.U:

This variable conditionally defines HAS_SYS_ERRNOLIST if sys_errnolist[] is available to translate error numbers to the symbolic name.

d_syserrlst

From d_strerror.U:

This variable conditionally defines HAS_SYS_ERRLIST if sys_errlist[] is available to translate error numbers to strings.

d_system

From d_system.U:

This variable conditionally defines HAS_SYSTEM if system() is available to issue a shell command.

d_tcgetpgrp

From d_tcgtpgrp.U:

This variable conditionally defines the HAS_TCGETPGRP symbol, which indicates to the C program that the tcgetpgrp() routine is available. to get foreground process group ID.

d_tcsetpgrp

From d_tcstpgrp.U:

This variable conditionally defines the HAS_TCSETPGRP symbol, which indicates to the C program that the tcsetpgrp() routine is available to set foreground process group ID.

d_telldir

From d_readdir.U:

This variable conditionally defines HAS_TELLDIR if telldir() is available.

d_telldirproto

From d_telldirproto.U:

This variable conditionally defines the HAS_TELLDIR_PROTO symbol, which indicates to the C program that the system provides a prototype for the telldir() function. Otherwise, it is up to the program to supply one.

d_time

From d_time.U:

This variable conditionally defines the HAS_TIME symbol, which indicates that the time() routine exists. The time() routine is normaly provided on UNIX systems.

d_times

From d_times.U:

This variable conditionally defines the HAS_TIMES symbol, which indicates that the times() routine exists. The times() routine is normaly provided on UNIX systems. You may have to include <sys/times.h>.

d_tm_tm_gmtoff

From i_time.U:

This variable conditionally defines HAS_TM_TM_GMTOFF, which indicates indicates to the C program that the struct tm has the tm_gmtoff field.

d_tm_tm_zone

From i_time.U:

This variable conditionally defines HAS_TM_TM_ZONE, which indicates indicates to the C program that the struct tm has the tm_zone field.

d_tmpnam_r

From d_tmpnam_r.U:

This variable conditionally defines the HAS_TMPNAM_R symbol, which indicates to the C program that the tmpnam_r() routine is available.

d_truncate

From d_truncate.U:

This variable conditionally defines HAS_TRUNCATE if truncate() is available to truncate files.

d_ttyname_r

From d_ttyname_r.U:

This variable conditionally defines the HAS_TTYNAME_R symbol, which indicates to the C program that the ttyname_r() routine is available.

d_tzname

From d_tzname.U:

This variable conditionally defines HAS_TZNAME if tzname[] is available to access timezone names.

d_u32align

From d_u32align.U:

This variable tells whether you must access character data through U32-aligned pointers.

d_ualarm

From d_ualarm.U:

This variable conditionally defines the HAS_UALARM symbol, which indicates to the C program that the ualarm() routine is available.

d_umask

From d_umask.U:

This variable conditionally defines the HAS_UMASK symbol, which indicates to the C program that the umask() routine is available. to set and get the value of the file creation mask.

d_uname

From d_gethname.U:

This variable conditionally defines the HAS_UNAME symbol, which indicates to the C program that the uname() routine may be used to derive the host name.

d_union_semun

From d_union_semun.U:

This variable conditionally defines HAS_UNION_SEMUN if the union semun is defined by including <sys/sem.h>.

d_unordered

From d_unordered.U:

This variable conditionally defines the HAS_UNORDERED symbol, which indicates to the C program that the unordered() routine is available.

d_unsetenv

From d_unsetenv.U:

This variable conditionally defines the HAS_UNSETENV symbol, which indicates to the C program that the unsetenv () routine is available.

d_usleep

From d_usleep.U:

This variable conditionally defines HAS_USLEEP if usleep() is available to do high granularity sleeps.

d_usleepproto

From d_usleepproto.U:

This variable conditionally defines the HAS_USLEEP_PROTO symbol, which indicates to the C program that the system provides a prototype for the usleep() function. Otherwise, it is up to the program to supply one.

d_ustat

From d_ustat.U:

This variable conditionally defines HAS_USTAT if ustat() is available to query file system statistics by dev_t.

d_vendorarch

From vendorarch.U:

This variable conditionally defined PERL_VENDORARCH.

d_vendorbin

From vendorbin.U:

This variable conditionally defines PERL_VENDORBIN.

d_vendorlib

From vendorlib.U:

This variable conditionally defines PERL_VENDORLIB.

d_vendorscript

From vendorscript.U:

This variable conditionally defines PERL_VENDORSCRIPT.

d_vfork

From d_vfork.U:

This variable conditionally defines the HAS_VFORK symbol, which indicates the vfork() routine is available.

d_void_closedir

From d_closedir.U:

This variable conditionally defines VOID_CLOSEDIR if closedir() does not return a value.

d_voidsig

From d_voidsig.U:

This variable conditionally defines VOIDSIG if this system declares "void (*signal(...))()" in signal.h. The old way was to declare it as "int (*signal(...))()".

d_voidtty

From i_sysioctl.U:

This variable conditionally defines USE_IOCNOTTY to indicate that the ioctl() call with TIOCNOTTY should be used to void tty association. Otherwise (on USG probably), it is enough to close the standard file decriptors and do a setpgrp().

d_volatile

From d_volatile.U:

This variable conditionally defines the HASVOLATILE symbol, which indicates to the C program that this C compiler knows about the volatile declaration.

d_vprintf

From d_vprintf.U:

This variable conditionally defines the HAS_VPRINTF symbol, which indicates to the C program that the vprintf() routine is available to printf with a pointer to an argument list.

d_wait4

From d_wait4.U:

This variable conditionally defines the HAS_WAIT4 symbol, which indicates the wait4() routine is available.

d_waitpid

From d_waitpid.U:

This variable conditionally defines HAS_WAITPID if waitpid() is available to wait for child process.

d_wcstombs

From d_wcstombs.U:

This variable conditionally defines the HAS_WCSTOMBS symbol, which indicates to the C program that the wcstombs() routine is available to convert wide character strings to multibyte strings.

d_wctomb

From d_wctomb.U:

This variable conditionally defines the HAS_WCTOMB symbol, which indicates to the C program that the wctomb() routine is available to convert a wide character to a multibyte.

d_writev

From d_writev.U:

This variable conditionally defines the HAS_WRITEV symbol, which indicates to the C program that the writev() routine is available.

d_xenix

From Guess.U:

This variable conditionally defines the symbol XENIX, which alerts the C program that it runs under Xenix.

date

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the date program. After Configure runs, the value is reset to a plain date and is not useful.

db_hashtype

From i_db.U:

This variable contains the type of the hash structure element in the <db.h> header file. In older versions of DB, it was int, while in newer ones it is u_int32_t.

db_prefixtype

From i_db.U:

This variable contains the type of the prefix structure element in the <db.h> header file. In older versions of DB, it was int, while in newer ones it is size_t.

db_version_major

From i_db.U:

This variable contains the major version number of Berkeley DB found in the <db.h> header file.

db_version_minor

From i_db.U:

This variable contains the minor version number of Berkeley DB found in the <db.h> header file. For DB version 1 this is always 0.

db_version_patch

From i_db.U:

This variable contains the patch version number of Berkeley DB found in the <db.h> header file. For DB version 1 this is always 0.

defvoidused

From voidflags.U:

This variable contains the default value of the VOIDUSED symbol (15).

direntrytype

From i_dirent.U:

This symbol is set to struct direct or struct dirent depending on whether dirent is available or not. You should use this pseudo type to portably declare your directory entries.

dlext

From dlext.U:

This variable contains the extension that is to be used for the dynamically loaded modules that perl generaties.

dlsrc

From dlsrc.U:

This variable contains the name of the dynamic loading file that will be used with the package.

doublesize

From doublesize.U:

This variable contains the value of the DOUBLESIZE symbol, which indicates to the C program how many bytes there are in a double.

drand01

From randfunc.U:

Indicates the macro to be used to generate normalized random numbers. Uses randfunc, often divided by (double) (((unsigned long) 1 << randbits)) in order to normalize the result. In C programs, the macro Drand01 is mapped to drand01.

drand48_r_proto

From d_drand48_r.U:

This variable encodes the prototype of drand48_r. It is zero if d_drand48_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_drand48_r is defined.

dynamic_ext

From Extensions.U:

This variable holds a list of XS extension files we want to link dynamically into the package. It is used by Makefile.

e

eagain

From nblock_io.U:

This variable bears the symbolic errno code set by read() when no data is present on the file and non-blocking I/O was enabled (otherwise, read() blocks naturally).

ebcdic

From ebcdic.U:

This variable conditionally defines EBCDIC if this system uses EBCDIC encoding. Among other things, this means that the character ranges are not contiguous. See trnl.U

echo

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the echo program. After Configure runs, the value is reset to a plain echo and is not useful.

egrep

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the egrep program. After Configure runs, the value is reset to a plain egrep and is not useful.

emacs

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

endgrent_r_proto

From d_endgrent_r.U:

This variable encodes the prototype of endgrent_r. It is zero if d_endgrent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endgrent_r is defined.

endhostent_r_proto

From d_endhostent_r.U:

This variable encodes the prototype of endhostent_r. It is zero if d_endhostent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endhostent_r is defined.

endnetent_r_proto

From d_endnetent_r.U:

This variable encodes the prototype of endnetent_r. It is zero if d_endnetent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endnetent_r is defined.

endprotoent_r_proto

From d_endprotoent_r.U:

This variable encodes the prototype of endprotoent_r. It is zero if d_endprotoent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endprotoent_r is defined.

endpwent_r_proto

From d_endpwent_r.U:

This variable encodes the prototype of endpwent_r. It is zero if d_endpwent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endpwent_r is defined.

endservent_r_proto

From d_endservent_r.U:

This variable encodes the prototype of endservent_r. It is zero if d_endservent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_endservent_r is defined.

eunicefix

From Init.U:

When running under Eunice this variable contains a command which will convert a shell script to the proper form of text file for it to be executable by the shell. On other systems it is a no-op.

exe_ext

From Unix.U:

This is an old synonym for _exe.

expr

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the expr program. After Configure runs, the value is reset to a plain expr and is not useful.

extensions

From Extensions.U:

This variable holds a list of all extension files (both XS and non-xs linked into the package. It is propagated to Config.pm and is typically used to test whether a particular extesion is available.

extras

From Extras.U:

This variable holds a list of extra modules to install.

f

fflushall

From fflushall.U:

This symbol, if defined, tells that to flush all pending stdio output one must loop through all the stdio file handles stored in an array and fflush them. Note that if fflushNULL is defined, fflushall will not even be probed for and will be left undefined.

fflushNULL

From fflushall.U:

This symbol, if defined, tells that fflush(NULL) does flush all pending stdio output.

find

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

firstmakefile

From Unix.U:

This variable defines the first file searched by make. On unix, it is makefile (then Makefile). On case-insensitive systems, it might be something else. This is only used to deal with convoluted make depend tricks.

flex

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

fpossize

From fpossize.U:

This variable contains the size of a fpostype in bytes.

fpostype

From fpostype.U:

This variable defines Fpos_t to be something like fpos_t, long, uint, or whatever type is used to declare file positions in libc.

freetype

From mallocsrc.U:

This variable contains the return type of free(). It is usually void, but occasionally int.

from

From Cross.U:

This variable contains the command used by Configure to copy files from the target host. Useful and available only during Perl build. The string : if not cross-compiling.

full_ar

From Loc_ar.U:

This variable contains the full pathname to ar, whether or not the user has specified portability. This is only used in the Makefile.SH.

full_csh

From d_csh.U:

This variable contains the full pathname to csh, whether or not the user has specified portability. This is only used in the compiled C program, and we assume that all systems which can share this executable will have the same full pathname to csh.

full_sed

From Loc_sed.U:

This variable contains the full pathname to sed, whether or not the user has specified portability. This is only used in the compiled C program, and we assume that all systems which can share this executable will have the same full pathname to sed.

g

gccansipedantic

From gccvers.U:

If GNU cc (gcc) is used, this variable will enable (if set) the -ansi and -pedantic ccflags for building core files (through cflags script). (See Porting/pumpkin.pod for full description).

gccosandvers

From gccvers.U:

If GNU cc (gcc) is used, this variable holds the operating system and version used to compile gcc. It is set to '' if not gcc, or if nothing useful can be parsed as the os version.

gccversion

From gccvers.U:

If GNU cc (gcc) is used, this variable holds 1 or 2 to indicate whether the compiler is version 1 or 2. This is used in setting some of the default cflags. It is set to '' if not gcc.

getgrent_r_proto

From d_getgrent_r.U:

This variable encodes the prototype of getgrent_r. It is zero if d_getgrent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getgrent_r is defined.

getgrgid_r_proto

From d_getgrgid_r.U:

This variable encodes the prototype of getgrgid_r. It is zero if d_getgrgid_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getgrgid_r is defined.

getgrnam_r_proto

From d_getgrnam_r.U:

This variable encodes the prototype of getgrnam_r. It is zero if d_getgrnam_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getgrnam_r is defined.

gethostbyaddr_r_proto

From d_gethostbyaddr_r.U:

This variable encodes the prototype of gethostbyaddr_r. It is zero if d_gethostbyaddr_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_gethostbyaddr_r is defined.

gethostbyname_r_proto

From d_gethostbyname_r.U:

This variable encodes the prototype of gethostbyname_r. It is zero if d_gethostbyname_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_gethostbyname_r is defined.

gethostent_r_proto

From d_gethostent_r.U:

This variable encodes the prototype of gethostent_r. It is zero if d_gethostent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_gethostent_r is defined.

getlogin_r_proto

From d_getlogin_r.U:

This variable encodes the prototype of getlogin_r. It is zero if d_getlogin_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getlogin_r is defined.

getnetbyaddr_r_proto

From d_getnetbyaddr_r.U:

This variable encodes the prototype of getnetbyaddr_r. It is zero if d_getnetbyaddr_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getnetbyaddr_r is defined.

getnetbyname_r_proto

From d_getnetbyname_r.U:

This variable encodes the prototype of getnetbyname_r. It is zero if d_getnetbyname_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getnetbyname_r is defined.

getnetent_r_proto

From d_getnetent_r.U:

This variable encodes the prototype of getnetent_r. It is zero if d_getnetent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getnetent_r is defined.

getprotobyname_r_proto

From d_getprotobyname_r.U:

This variable encodes the prototype of getprotobyname_r. It is zero if d_getprotobyname_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getprotobyname_r is defined.

getprotobynumber_r_proto

From d_getprotobynumber_r.U:

This variable encodes the prototype of getprotobynumber_r. It is zero if d_getprotobynumber_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getprotobynumber_r is defined.

getprotoent_r_proto

From d_getprotoent_r.U:

This variable encodes the prototype of getprotoent_r. It is zero if d_getprotoent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getprotoent_r is defined.

getpwent_r_proto

From d_getpwent_r.U:

This variable encodes the prototype of getpwent_r. It is zero if d_getpwent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getpwent_r is defined.

getpwnam_r_proto

From d_getpwnam_r.U:

This variable encodes the prototype of getpwnam_r. It is zero if d_getpwnam_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getpwnam_r is defined.

getpwuid_r_proto

From d_getpwuid_r.U:

This variable encodes the prototype of getpwuid_r. It is zero if d_getpwuid_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getpwuid_r is defined.

getservbyname_r_proto

From d_getservbyname_r.U:

This variable encodes the prototype of getservbyname_r. It is zero if d_getservbyname_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getservbyname_r is defined.

getservbyport_r_proto

From d_getservbyport_r.U:

This variable encodes the prototype of getservbyport_r. It is zero if d_getservbyport_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getservbyport_r is defined.

getservent_r_proto

From d_getservent_r.U:

This variable encodes the prototype of getservent_r. It is zero if d_getservent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getservent_r is defined.

getspnam_r_proto

From d_getspnam_r.U:

This variable encodes the prototype of getspnam_r. It is zero if d_getspnam_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_getspnam_r is defined.

gidformat

From gidf.U:

This variable contains the format string used for printing a Gid_t.

gidsign

From gidsign.U:

This variable contains the signedness of a gidtype. 1 for unsigned, -1 for signed.

gidsize

From gidsize.U:

This variable contains the size of a gidtype in bytes.

gidtype

From gidtype.U:

This variable defines Gid_t to be something like gid_t, int, ushort, or whatever type is used to declare the return type of getgid(). Typically, it is the type of group ids in the kernel.

glibpth

From libpth.U:

This variable holds the general path (space-separated) used to find libraries. It may contain directories that do not exist on this platform, libpth is the cleaned-up version.

gmake

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the gmake program. After Configure runs, the value is reset to a plain gmake and is not useful.

gmtime_r_proto

From d_gmtime_r.U:

This variable encodes the prototype of gmtime_r. It is zero if d_gmtime_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_gmtime_r is defined.

gnulibc_version

From d_gnulibc.U:

This variable contains the version number of the GNU C library. It is usually something like 2.2.5. It is a plain '' if this is not the GNU C library, or if the version is unknown.

grep

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the grep program. After Configure runs, the value is reset to a plain grep and is not useful.

groupcat

From nis.U:

This variable contains a command that produces the text of the /etc/group file. This is normally "cat /etc/group", but can be "ypcat group" when NIS is used. On some systems, such as os390, there may be no equivalent command, in which case this variable is unset.

groupstype

From groupstype.U:

This variable defines Groups_t to be something like gid_t, int, ushort, or whatever type is used for the second argument to getgroups() and setgroups(). Usually, this is the same as gidtype (gid_t), but sometimes it isn't.

gzip

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the gzip program. After Configure runs, the value is reset to a plain gzip and is not useful.

h

h_fcntl

From h_fcntl.U:

This is variable gets set in various places to tell i_fcntl that <fcntl.h> should be included.

h_sysfile

From h_sysfile.U:

This is variable gets set in various places to tell i_sys_file that <sys/file.h> should be included.

hint

From Oldconfig.U:

Gives the type of hints used for previous answers. May be one of default, recommended or previous.

hostcat

From nis.U:

This variable contains a command that produces the text of the /etc/hosts file. This is normally "cat /etc/hosts", but can be "ypcat hosts" when NIS is used. On some systems, such as os390, there may be no equivalent command, in which case this variable is unset.

html1dir

From html1dir.U:

This variable contains the name of the directory in which html source pages are to be put. This directory is for pages that describe whole programs, not libraries or modules. It is intended to correspond roughly to section 1 of the Unix manuals.

html1direxp

From html1dir.U:

This variable is the same as the html1dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

html3dir

From html3dir.U:

This variable contains the name of the directory in which html source pages are to be put. This directory is for pages that describe libraries or modules. It is intended to correspond roughly to section 3 of the Unix manuals.

html3direxp

From html3dir.U:

This variable is the same as the html3dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

i

i16size

From perlxv.U:

This variable is the size of an I16 in bytes.

i16type

From perlxv.U:

This variable contains the C type used for Perl's I16.

i32size

From perlxv.U:

This variable is the size of an I32 in bytes.

i32type

From perlxv.U:

This variable contains the C type used for Perl's I32.

i64size

From perlxv.U:

This variable is the size of an I64 in bytes.

i64type

From perlxv.U:

This variable contains the C type used for Perl's I64.

i8size

From perlxv.U:

This variable is the size of an I8 in bytes.

i8type

From perlxv.U:

This variable contains the C type used for Perl's I8.

i_arpainet

From i_arpainet.U:

This variable conditionally defines the I_ARPA_INET symbol, and indicates whether a C program should include <arpa/inet.h>.

i_bsdioctl

From i_sysioctl.U:

This variable conditionally defines the I_SYS_BSDIOCTL symbol, which indicates to the C program that <sys/bsdioctl.h> exists and should be included.

i_crypt

From i_crypt.U:

This variable conditionally defines the I_CRYPT symbol, and indicates whether a C program should include <crypt.h>.

i_db

From i_db.U:

This variable conditionally defines the I_DB symbol, and indicates whether a C program may include Berkeley's DB include file <db.h>.

i_dbm

From i_dbm.U:

This variable conditionally defines the I_DBM symbol, which indicates to the C program that <dbm.h> exists and should be included.

i_dirent

From i_dirent.U:

This variable conditionally defines I_DIRENT, which indicates to the C program that it should include <dirent.h>.

i_dld

From i_dld.U:

This variable conditionally defines the I_DLD symbol, which indicates to the C program that <dld.h> (GNU dynamic loading) exists and should be included.

i_dlfcn

From i_dlfcn.U:

This variable conditionally defines the I_DLFCN symbol, which indicates to the C program that <dlfcn.h> exists and should be included.

i_fcntl

From i_fcntl.U:

This variable controls the value of I_FCNTL (which tells the C program to include <fcntl.h>).

i_float

From i_float.U:

This variable conditionally defines the I_FLOAT symbol, and indicates whether a C program may include <float.h> to get symbols like DBL_MAX or DBL_MIN, i.e. machine dependent floating point values.

i_fp

From i_fp.U:

This variable conditionally defines the I_FP symbol, and indicates whether a C program should include <fp.h>.

i_fp_class

From i_fp_class.U:

This variable conditionally defines the I_FP_CLASS symbol, and indicates whether a C program should include <fp_class.h>.

i_gdbm

From i_gdbm.U:

This variable conditionally defines the I_GDBM symbol, which indicates to the C program that <gdbm.h> exists and should be included.

i_grp

From i_grp.U:

This variable conditionally defines the I_GRP symbol, and indicates whether a C program should include <grp.h>.

i_ieeefp

From i_ieeefp.U:

This variable conditionally defines the I_IEEEFP symbol, and indicates whether a C program should include <ieeefp.h>.

i_inttypes

From i_inttypes.U:

This variable conditionally defines the I_INTTYPES symbol, and indicates whether a C program should include <inttypes.h>.

i_langinfo

From i_langinfo.U:

This variable conditionally defines the I_LANGINFO symbol, and indicates whether a C program should include <langinfo.h>.

i_libutil

From i_libutil.U:

This variable conditionally defines the I_LIBUTIL symbol, and indicates whether a C program should include <libutil.h>.

i_limits

From i_limits.U:

This variable conditionally defines the I_LIMITS symbol, and indicates whether a C program may include <limits.h> to get symbols like WORD_BIT and friends.

i_locale

From i_locale.U:

This variable conditionally defines the I_LOCALE symbol, and indicates whether a C program should include <locale.h>.

i_machcthr

From i_machcthr.U:

This variable conditionally defines the I_MACH_CTHREADS symbol, and indicates whether a C program should include <mach/cthreads.h>.

i_malloc

From i_malloc.U:

This variable conditionally defines the I_MALLOC symbol, and indicates whether a C program should include <malloc.h>.

i_math

From i_math.U:

This variable conditionally defines the I_MATH symbol, and indicates whether a C program may include <math.h>.

i_memory

From i_memory.U:

This variable conditionally defines the I_MEMORY symbol, and indicates whether a C program should include <memory.h>.

i_mntent

From i_mntent.U:

This variable conditionally defines the I_MNTENT symbol, and indicates whether a C program should include <mntent.h>.

i_ndbm

From i_ndbm.U:

This variable conditionally defines the I_NDBM symbol, which indicates to the C program that <ndbm.h> exists and should be included.

i_netdb

From i_netdb.U:

This variable conditionally defines the I_NETDB symbol, and indicates whether a C program should include <netdb.h>.

i_neterrno

From i_neterrno.U:

This variable conditionally defines the I_NET_ERRNO symbol, which indicates to the C program that <net/errno.h> exists and should be included.

i_netinettcp

From i_netinettcp.U:

This variable conditionally defines the I_NETINET_TCP symbol, and indicates whether a C program should include <netinet/tcp.h>.

i_niin

From i_niin.U:

This variable conditionally defines I_NETINET_IN, which indicates to the C program that it should include <netinet/in.h>. Otherwise, you may try <sys/in.h>.

i_poll

From i_poll.U:

This variable conditionally defines the I_POLL symbol, and indicates whether a C program should include <poll.h>.

i_prot

From i_prot.U:

This variable conditionally defines the I_PROT symbol, and indicates whether a C program should include <prot.h>.

i_pthread

From i_pthread.U:

This variable conditionally defines the I_PTHREAD symbol, and indicates whether a C program should include <pthread.h>.

i_pwd

From i_pwd.U:

This variable conditionally defines I_PWD, which indicates to the C program that it should include <pwd.h>.

i_rpcsvcdbm

From i_dbm.U:

This variable conditionally defines the I_RPCSVC_DBM symbol, which indicates to the C program that <rpcsvc/dbm.h> exists and should be included. Some System V systems might need this instead of <dbm.h>.

i_sfio

From i_sfio.U:

This variable conditionally defines the I_SFIO symbol, and indicates whether a C program should include <sfio.h>.

i_sgtty

From i_termio.U:

This variable conditionally defines the I_SGTTY symbol, which indicates to the C program that it should include <sgtty.h> rather than <termio.h>.

i_shadow

From i_shadow.U:

This variable conditionally defines the I_SHADOW symbol, and indicates whether a C program should include <shadow.h>.

i_socks

From i_socks.U:

This variable conditionally defines the I_SOCKS symbol, and indicates whether a C program should include <socks.h>.

i_stdarg

From i_varhdr.U:

This variable conditionally defines the I_STDARG symbol, which indicates to the C program that <stdarg.h> exists and should be included.

i_stddef

From i_stddef.U:

This variable conditionally defines the I_STDDEF symbol, which indicates to the C program that <stddef.h> exists and should be included.

i_stdlib

From i_stdlib.U:

This variable conditionally defines the I_STDLIB symbol, which indicates to the C program that <stdlib.h> exists and should be included.

i_string

From i_string.U:

This variable conditionally defines the I_STRING symbol, which indicates that <string.h> should be included rather than <strings.h>.

i_sunmath

From i_sunmath.U:

This variable conditionally defines the I_SUNMATH symbol, and indicates whether a C program should include <sunmath.h>.

i_sysaccess

From i_sysaccess.U:

This variable conditionally defines the I_SYS_ACCESS symbol, and indicates whether a C program should include <sys/access.h>.

i_sysdir

From i_sysdir.U:

This variable conditionally defines the I_SYS_DIR symbol, and indicates whether a C program should include <sys/dir.h>.

i_sysfile

From i_sysfile.U:

This variable conditionally defines the I_SYS_FILE symbol, and indicates whether a C program should include <sys/file.h> to get R_OK and friends.

i_sysfilio

From i_sysioctl.U:

This variable conditionally defines the I_SYS_FILIO symbol, which indicates to the C program that <sys/filio.h> exists and should be included in preference to <sys/ioctl.h>.

i_sysin

From i_niin.U:

This variable conditionally defines I_SYS_IN, which indicates to the C program that it should include <sys/in.h> instead of <netinet/in.h>.

i_sysioctl

From i_sysioctl.U:

This variable conditionally defines the I_SYS_IOCTL symbol, which indicates to the C program that <sys/ioctl.h> exists and should be included.

i_syslog

From i_syslog.U:

This variable conditionally defines the I_SYSLOG symbol, and indicates whether a C program should include <syslog.h>.

i_sysmman

From i_sysmman.U:

This variable conditionally defines the I_SYS_MMAN symbol, and indicates whether a C program should include <sys/mman.h>.

i_sysmode

From i_sysmode.U:

This variable conditionally defines the I_SYSMODE symbol, and indicates whether a C program should include <sys/mode.h>.

i_sysmount

From i_sysmount.U:

This variable conditionally defines the I_SYSMOUNT symbol, and indicates whether a C program should include <sys/mount.h>.

i_sysndir

From i_sysndir.U:

This variable conditionally defines the I_SYS_NDIR symbol, and indicates whether a C program should include <sys/ndir.h>.

i_sysparam

From i_sysparam.U:

This variable conditionally defines the I_SYS_PARAM symbol, and indicates whether a C program should include <sys/param.h>.

i_sysresrc

From i_sysresrc.U:

This variable conditionally defines the I_SYS_RESOURCE symbol, and indicates whether a C program should include <sys/resource.h>.

i_syssecrt

From i_syssecrt.U:

This variable conditionally defines the I_SYS_SECURITY symbol, and indicates whether a C program should include <sys/security.h>.

i_sysselct

From i_sysselct.U:

This variable conditionally defines I_SYS_SELECT, which indicates to the C program that it should include <sys/select.h> in order to get the definition of struct timeval.

i_syssockio

From i_sysioctl.U:

This variable conditionally defines I_SYS_SOCKIO to indicate to the C program that socket ioctl codes may be found in <sys/sockio.h> instead of <sys/ioctl.h>.

i_sysstat

From i_sysstat.U:

This variable conditionally defines the I_SYS_STAT symbol, and indicates whether a C program should include <sys/stat.h>.

i_sysstatfs

From i_sysstatfs.U:

This variable conditionally defines the I_SYSSTATFS symbol, and indicates whether a C program should include <sys/statfs.h>.

i_sysstatvfs

From i_sysstatvfs.U:

This variable conditionally defines the I_SYSSTATVFS symbol, and indicates whether a C program should include <sys/statvfs.h>.

i_systime

From i_time.U:

This variable conditionally defines I_SYS_TIME, which indicates to the C program that it should include <sys/time.h>.

i_systimek

From i_time.U:

This variable conditionally defines I_SYS_TIME_KERNEL, which indicates to the C program that it should include <sys/time.h> with KERNEL defined.

i_systimes

From i_systimes.U:

This variable conditionally defines the I_SYS_TIMES symbol, and indicates whether a C program should include <sys/times.h>.

i_systypes

From i_systypes.U:

This variable conditionally defines the I_SYS_TYPES symbol, and indicates whether a C program should include <sys/types.h>.

i_sysuio

From i_sysuio.U:

This variable conditionally defines the I_SYSUIO symbol, and indicates whether a C program should include <sys/uio.h>.

i_sysun

From i_sysun.U:

This variable conditionally defines I_SYS_UN, which indicates to the C program that it should include <sys/un.h> to get UNIX domain socket definitions.

i_sysutsname

From i_sysutsname.U:

This variable conditionally defines the I_SYSUTSNAME symbol, and indicates whether a C program should include <sys/utsname.h>.

i_sysvfs

From i_sysvfs.U:

This variable conditionally defines the I_SYSVFS symbol, and indicates whether a C program should include <sys/vfs.h>.

i_syswait

From i_syswait.U:

This variable conditionally defines I_SYS_WAIT, which indicates to the C program that it should include <sys/wait.h>.

i_termio

From i_termio.U:

This variable conditionally defines the I_TERMIO symbol, which indicates to the C program that it should include <termio.h> rather than <sgtty.h>.

i_termios

From i_termio.U:

This variable conditionally defines the I_TERMIOS symbol, which indicates to the C program that the POSIX <termios.h> file is to be included.

i_time

From i_time.U:

This variable conditionally defines I_TIME, which indicates to the C program that it should include <time.h>.

i_unistd

From i_unistd.U:

This variable conditionally defines the I_UNISTD symbol, and indicates whether a C program should include <unistd.h>.

i_ustat

From i_ustat.U:

This variable conditionally defines the I_USTAT symbol, and indicates whether a C program should include <ustat.h>.

i_utime

From i_utime.U:

This variable conditionally defines the I_UTIME symbol, and indicates whether a C program should include <utime.h>.

i_values

From i_values.U:

This variable conditionally defines the I_VALUES symbol, and indicates whether a C program may include <values.h> to get symbols like MAXLONG and friends.

i_varargs

From i_varhdr.U:

This variable conditionally defines I_VARARGS, which indicates to the C program that it should include <varargs.h>.

i_varhdr

From i_varhdr.U:

Contains the name of the header to be included to get va_dcl definition. Typically one of varargs.h or stdarg.h.

i_vfork

From i_vfork.U:

This variable conditionally defines the I_VFORK symbol, and indicates whether a C program should include vfork.h.

ignore_versioned_solibs

From libs.U:

This variable should be non-empty if non-versioned shared libraries (libfoo.so.x.y) are to be ignored (because they cannot be linked against).

inc_version_list

From inc_version_list.U:

This variable specifies the list of subdirectories in over which perl.c:incpush() and lib/lib.pm will automatically search when adding directories to @INC. The elements in the list are separated by spaces. This is only useful if you have a perl library directory tree structured like the default one. See INSTALL for how this works. The versioned site_perl directory was introduced in 5.005, so that is the lowest possible value.

inc_version_list_init

From inc_version_list.U:

This variable holds the same list as inc_version_list, but each item is enclosed in double quotes and separated by commas, suitable for use in the PERL_INC_VERSION_LIST initialization.

incpath

From usrinc.U:

This variable must preceed the normal include path to get hte right one, as in $incpath/usr/include or $incpath/usr/lib. Value can be "" or /bsd43 on mips.

inews

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

installarchlib

From archlib.U:

This variable is really the same as archlibexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installbin

From bin.U:

This variable is the same as binexp unless AFS is running in which case the user is explicitely prompted for it. This variable should always be used in your makefiles for maximum portability.

installhtml1dir

From html1dir.U:

This variable is really the same as html1direxp, unless you are using a different installprefix. For extra portability, you should only use this variable within your makefiles.

installhtml3dir

From html3dir.U:

This variable is really the same as html3direxp, unless you are using a different installprefix. For extra portability, you should only use this variable within your makefiles.

installman1dir

From man1dir.U:

This variable is really the same as man1direxp, unless you are using AFS in which case it points to the read/write location whereas man1direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installman3dir

From man3dir.U:

This variable is really the same as man3direxp, unless you are using AFS in which case it points to the read/write location whereas man3direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installprefix

From installprefix.U:

This variable holds the name of the directory below which "make install" will install the package. For most users, this is the same as prefix. However, it is useful for installing the software into a different (usually temporary) location after which it can be bundled up and moved somehow to the final location specified by prefix.

installprefixexp

From installprefix.U:

This variable holds the full absolute path of installprefix with all ~-expansion done.

installprivlib

From privlib.U:

This variable is really the same as privlibexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installscript

From scriptdir.U:

This variable is usually the same as scriptdirexp, unless you are on a system running AFS, in which case they may differ slightly. You should always use this variable within your makefiles for portability.

installsitearch

From sitearch.U:

This variable is really the same as sitearchexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installsitebin

From sitebin.U:

This variable is usually the same as sitebinexp, unless you are on a system running AFS, in which case they may differ slightly. You should always use this variable within your makefiles for portability.

installsitehtml1dir

From sitehtml1dir.U:

This variable is really the same as sitehtml1direxp, unless you are using AFS in which case it points to the read/write location whereas html1direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installsitehtml3dir

From sitehtml3dir.U:

This variable is really the same as sitehtml3direxp, unless you are using AFS in which case it points to the read/write location whereas html3direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installsitelib

From sitelib.U:

This variable is really the same as sitelibexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installsiteman1dir

From siteman1dir.U:

This variable is really the same as siteman1direxp, unless you are using AFS in which case it points to the read/write location whereas man1direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installsiteman3dir

From siteman3dir.U:

This variable is really the same as siteman3direxp, unless you are using AFS in which case it points to the read/write location whereas man3direxp only points to the read-only access location. For extra portability, you should only use this variable within your makefiles.

installsitescript

From sitescript.U:

This variable is usually the same as sitescriptexp, unless you are on a system running AFS, in which case they may differ slightly. You should always use this variable within your makefiles for portability.

installstyle

From installstyle.U:

This variable describes the style of the perl installation. This is intended to be useful for tools that need to manipulate entire perl distributions. Perl itself doesn't use this to find its libraries -- the library directories are stored directly in Config.pm. Currently, there are only two styles: lib and lib/perl5. The default library locations (e.g. privlib, sitelib) are either $prefix/lib or $prefix/lib/perl5. The former is useful if $prefix is a directory dedicated to perl (e.g. /opt/perl), while the latter is useful if $prefix is shared by many packages, e.g. if $prefix=/usr/local.

Unfortunately, while this style variable is used to set defaults for all three directory hierarchies (core, vendor, and site), there is no guarantee that the same style is actually appropriate for all those directories. For example, $prefix might be /opt/perl, but $siteprefix might be /usr/local. (Perhaps, in retrospect, the lib style should never have been supported, but it did seem like a nice idea at the time.)

The situation is even less clear for tools such as MakeMaker that can be used to install additional modules into non-standard places. For example, if a user intends to install a module into a private directory (perhaps by setting PREFIX on the Makefile.PL command line), then there is no reason to assume that the Configure-time $installstyle setting will be relevant for that PREFIX.

This may later be extended to include other information, so be careful with pattern-matching on the results.

For compatibility with perl5.005 and earlier, the default setting is based on whether or not $prefix contains the string perl.

installusrbinperl

From instubperl.U:

This variable tells whether Perl should be installed also as /usr/bin/perl in addition to $installbin/perl

installvendorarch

From vendorarch.U:

This variable is really the same as vendorarchexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorbin

From vendorbin.U:

This variable is really the same as vendorbinexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorhtml1dir

From vendorhtml1dir.U:

This variable is really the same as vendorhtml1direxp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorhtml3dir

From vendorhtml3dir.U:

This variable is really the same as vendorhtml3direxp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorlib

From vendorlib.U:

This variable is really the same as vendorlibexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorman1dir

From vendorman1dir.U:

This variable is really the same as vendorman1direxp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorman3dir

From vendorman3dir.U:

This variable is really the same as vendorman3direxp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

installvendorscript

From vendorscript.U:

This variable is really the same as vendorscriptexp but may differ on those systems using AFS. For extra portability, only this variable should be used in makefiles.

intsize

From intsize.U:

This variable contains the value of the INTSIZE symbol, which indicates to the C program how many bytes there are in an int.

issymlink

From issymlink.U:

This variable holds the test command to test for a symbolic link (if they are supported). Typical values include test -h and test -L.

ivdformat

From perlxvf.U:

This variable contains the format string used for printing a Perl IV as a signed decimal integer.

ivsize

From perlxv.U:

This variable is the size of an IV in bytes.

ivtype

From perlxv.U:

This variable contains the C type used for Perl's IV.

k

known_extensions

From Extensions.U:

This variable holds a list of all XS extensions included in the package.

ksh

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

l

ld

From dlsrc.U:

This variable indicates the program to be used to link libraries for dynamic loading. On some systems, it is ld. On ELF systems, it should be $cc. Mostly, we'll try to respect the hint file setting.

lddlflags

From dlsrc.U:

This variable contains any special flags that might need to be passed to $ld to create a shared library suitable for dynamic loading. It is up to the makefile to use it. For hpux, it should be -b. For sunos 4.1, it is empty.

ldflags

From ccflags.U:

This variable contains any additional C loader flags desired by the user. It is up to the Makefile to use this.

ldflags_uselargefiles

From uselfs.U:

This variable contains the loader flags needed by large file builds and added to ldflags by hints files.

ldlibpthname

From libperl.U:

This variable holds the name of the shared library search path, often LD_LIBRARY_PATH. To get an empty string, the hints file must set this to none.

less

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the less program. After Configure runs, the value is reset to a plain less and is not useful.

lib_ext

From Unix.U:

This is an old synonym for _a.

libc

From libc.U:

This variable contains the location of the C library.

libperl

From libperl.U:

The perl executable is obtained by linking perlmain.c with libperl, any static extensions (usually just DynaLoader), and any other libraries needed on this system. libperl is usually libperl.a, but can also be libperl.so.xxx if the user wishes to build a perl executable with a shared library.

libpth

From libpth.U:

This variable holds the general path (space-separated) used to find libraries. It is intended to be used by other units.

libs

From libs.U:

This variable holds the additional libraries we want to use. It is up to the Makefile to deal with it. The list can be empty.

libsdirs

From libs.U:

This variable holds the directory names aka dirnames of the libraries we found and accepted, duplicates are removed.

libsfiles

From libs.U:

This variable holds the filenames aka basenames of the libraries we found and accepted.

libsfound

From libs.U:

This variable holds the full pathnames of the libraries we found and accepted.

libspath

From libs.U:

This variable holds the directory names probed for libraries.

libswanted

From Myinit.U:

This variable holds a list of all the libraries we want to search. The order is chosen to pick up the c library ahead of ucb or bsd libraries for SVR4.

libswanted_uselargefiles

From uselfs.U:

This variable contains the libraries needed by large file builds and added to ldflags by hints files. It is a space separated list of the library names without the lib prefix or any suffix, just like libswanted..

line

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

lint

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

lkflags

From ccflags.U:

This variable contains any additional C partial linker flags desired by the user. It is up to the Makefile to use this.

ln

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the ln program. After Configure runs, the value is reset to a plain ln and is not useful.

lns

From lns.U:

This variable holds the name of the command to make symbolic links (if they are supported). It can be used in the Makefile. It is either ln -s or ln

localtime_r_proto

From d_localtime_r.U:

This variable encodes the prototype of localtime_r. It is zero if d_localtime_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_localtime_r is defined.

locincpth

From ccflags.U:

This variable contains a list of additional directories to be searched by the compiler. The appropriate -I directives will be added to ccflags. This is intended to simplify setting local directories from the Configure command line. It's not much, but it parallels the loclibpth stuff in libpth.U.

loclibpth

From libpth.U:

This variable holds the paths (space-separated) used to find local libraries. It is prepended to libpth, and is intended to be easily set from the command line.

longdblsize

From d_longdbl.U:

This variable contains the value of the LONG_DOUBLESIZE symbol, which indicates to the C program how many bytes there are in a long double, if this system supports long doubles.

longlongsize

From d_longlong.U:

This variable contains the value of the LONGLONGSIZE symbol, which indicates to the C program how many bytes there are in a long long, if this system supports long long.

longsize

From intsize.U:

This variable contains the value of the LONGSIZE symbol, which indicates to the C program how many bytes there are in a long.

lp

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

lpr

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

ls

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the ls program. After Configure runs, the value is reset to a plain ls and is not useful.

lseeksize

From lseektype.U:

This variable defines lseektype to be something like off_t, long, or whatever type is used to declare lseek offset's type in the kernel (which also appears to be lseek's return type).

lseektype

From lseektype.U:

This variable defines lseektype to be something like off_t, long, or whatever type is used to declare lseek offset's type in the kernel (which also appears to be lseek's return type).

m

mail

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

mailx

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

make

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the make program. After Configure runs, the value is reset to a plain make and is not useful.

make_set_make

From make.U:

Some versions of make set the variable MAKE. Others do not. This variable contains the string to be included in Makefile.SH so that MAKE is set if needed, and not if not needed. Possible values are:

make_set_make=# # If your make program handles this for you,

make_set_make=MAKE=$make # if it doesn't.

This uses a comment character to distinguish a set value (from a previous config.sh or Configure -D option) from an uncomputed value.

mallocobj

From mallocsrc.U:

This variable contains the name of the malloc.o that this package generates, if that malloc.o is preferred over the system malloc. Otherwise the value is null. This variable is intended for generating Makefiles. See mallocsrc.

mallocsrc

From mallocsrc.U:

This variable contains the name of the malloc.c that comes with the package, if that malloc.c is preferred over the system malloc. Otherwise the value is null. This variable is intended for generating Makefiles.

malloctype

From mallocsrc.U:

This variable contains the kind of ptr returned by malloc and realloc.

man1dir

From man1dir.U:

This variable contains the name of the directory in which manual source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself.

man1direxp

From man1dir.U:

This variable is the same as the man1dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

man1ext

From man1dir.U:

This variable contains the extension that the manual page should have: one of n, l, or 1. The Makefile must supply the .. See man1dir.

man3dir

From man3dir.U:

This variable contains the name of the directory in which manual source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself.

man3direxp

From man3dir.U:

This variable is the same as the man3dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

man3ext

From man3dir.U:

This variable contains the extension that the manual page should have: one of n, l, or 3. The Makefile must supply the .. See man3dir.

M

Mcc

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the Mcc program. After Configure runs, the value is reset to a plain Mcc and is not useful.

mips_type

From usrinc.U:

This variable holds the environment type for the mips system. Possible values are "BSD 4.3" and "System V".

mistrustnm

From Csym.U:

This variable can be used to establish a fallthrough for the cases where nm fails to find a symbol. If usenm is false or usenm is true and mistrustnm is false, this variable has no effect. If usenm is true and mistrustnm is compile, a test program will be compiled to try to find any symbol that can't be located via nm lookup. If mistrustnm is run, the test program will be run as well as being compiled.

mkdir

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the mkdir program. After Configure runs, the value is reset to a plain mkdir and is not useful.

mmaptype

From d_mmap.U:

This symbol contains the type of pointer returned by mmap() (and simultaneously the type of the first argument). It can be void * or caddr_t.

modetype

From modetype.U:

This variable defines modetype to be something like mode_t, int, unsigned short, or whatever type is used to declare file modes for system calls.

more

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the more program. After Configure runs, the value is reset to a plain more and is not useful.

multiarch

From multiarch.U:

This variable conditionally defines the MULTIARCH symbol which signifies the presence of multiplatform files. This is normally set by hints files.

mv

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

myarchname

From archname.U:

This variable holds the architecture name computed by Configure in a previous run. It is not intended to be perused by any user and should never be set in a hint file.

mydomain

From myhostname.U:

This variable contains the eventual value of the MYDOMAIN symbol, which is the domain of the host the program is going to run on. The domain must be appended to myhostname to form a complete host name. The dot comes with mydomain, and need not be supplied by the program.

myhostname

From myhostname.U:

This variable contains the eventual value of the MYHOSTNAME symbol, which is the name of the host the program is going to run on. The domain is not kept with hostname, but must be gotten from mydomain. The dot comes with mydomain, and need not be supplied by the program.

myuname

From Oldconfig.U:

The output of uname -a if available, otherwise the hostname. On Xenix, pseudo variables assignments in the output are stripped, thank you. The whole thing is then lower-cased.

n

n

From n.U:

This variable contains the -n flag if that is what causes the echo command to suppress newline. Otherwise it is null. Correct usage is $echo $n "prompt for a question: $c".

need_va_copy

From need_va_copy.U:

This symbol, if defined, indicates that the system stores the variable argument list datatype, va_list, in a format that cannot be copied by simple assignment, so that some other means must be used when copying is required. As such systems vary in their provision (or non-provision) of copying mechanisms, handy.h defines a platform- independent macro, Perl_va_copy(src, dst), to do the job.

netdb_hlen_type

From netdbtype.U:

This variable holds the type used for the 2nd argument to gethostbyaddr(). Usually, this is int or size_t or unsigned. This is only useful if you have gethostbyaddr(), naturally.

netdb_host_type

From netdbtype.U:

This variable holds the type used for the 1st argument to gethostbyaddr(). Usually, this is char * or void *, possibly with or without a const prefix. This is only useful if you have gethostbyaddr(), naturally.

netdb_name_type

From netdbtype.U:

This variable holds the type used for the argument to gethostbyname(). Usually, this is char * or const char *. This is only useful if you have gethostbyname(), naturally.

netdb_net_type

From netdbtype.U:

This variable holds the type used for the 1st argument to getnetbyaddr(). Usually, this is int or long. This is only useful if you have getnetbyaddr(), naturally.

nm

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the nm program. After Configure runs, the value is reset to a plain nm and is not useful.

nm_opt

From usenm.U:

This variable holds the options that may be necessary for nm.

nm_so_opt

From usenm.U:

This variable holds the options that may be necessary for nm to work on a shared library but that can not be used on an archive library. Currently, this is only used by Linux, where nm --dynamic is *required* to get symbols from an ELF library which has been stripped, but nm --dynamic is *fatal* on an archive library. Maybe Linux should just always set usenm=false.

nonxs_ext

From Extensions.U:

This variable holds a list of all non-xs extensions included in the package. All of them will be built.

nroff

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the nroff program. After Configure runs, the value is reset to a plain nroff and is not useful.

nv_preserves_uv_bits

From perlxv.U:

This variable indicates how many of bits type uvtype a variable nvtype can preserve.

nveformat

From perlxvf.U:

This variable contains the format string used for printing a Perl NV using %e-ish floating point format.

nvEUformat

From perlxvf.U:

This variable contains the format string used for printing a Perl NV using %E-ish floating point format.

nvfformat

From perlxvf.U:

This variable confains the format string used for printing a Perl NV using %f-ish floating point format.

nvFUformat

From perlxvf.U:

This variable confains the format string used for printing a Perl NV using %F-ish floating point format.

nvgformat

From perlxvf.U:

This variable contains the format string used for printing a Perl NV using %g-ish floating point format.

nvGUformat

From perlxvf.U:

This variable contains the format string used for printing a Perl NV using %G-ish floating point format.

nvsize

From perlxv.U:

This variable is the size of an NV in bytes.

nvtype

From perlxv.U:

This variable contains the C type used for Perl's NV.

o

o_nonblock

From nblock_io.U:

This variable bears the symbol value to be used during open() or fcntl() to turn on non-blocking I/O for a file descriptor. If you wish to switch between blocking and non-blocking, you may try ioctl(FIOSNBIO) instead, but that is only supported by some devices.

obj_ext

From Unix.U:

This is an old synonym for _o.

old_pthread_create_joinable

From d_pthrattrj.U:

This variable defines the constant to use for creating joinable (aka undetached) pthreads. Unused if pthread.h defines PTHREAD_CREATE_JOINABLE. If used, possible values are PTHREAD_CREATE_UNDETACHED and __UNDETACHED.

optimize

From ccflags.U:

This variable contains any optimizer/debugger flag that should be used. It is up to the Makefile to use it.

orderlib

From orderlib.U:

This variable is true if the components of libraries must be ordered (with `lorder $* | tsort`) before placing them in an archive. Set to false if ranlib or ar can generate random libraries.

osname

From Oldconfig.U:

This variable contains the operating system name (e.g. sunos, solaris, hpux, etc.). It can be useful later on for setting defaults. Any spaces are replaced with underscores. It is set to a null string if we can't figure it out.

osvers

From Oldconfig.U:

This variable contains the operating system version (e.g. 4.1.3, 5.2, etc.). It is primarily used for helping select an appropriate hints file, but might be useful elsewhere for setting defaults. It is set to '' if we can't figure it out. We try to be flexible about how much of the version number to keep, e.g. if 4.1.1, 4.1.2, and 4.1.3 are essentially the same for this package, hints files might just be os_4.0 or os_4.1, etc., not keeping separate files for each little release.

otherlibdirs

From otherlibdirs.U:

This variable contains a colon-separated set of paths for the perl binary to search for additional library files or modules. These directories will be tacked to the end of @INC. Perl will automatically search below each path for version- and architecture-specific directories. See inc_version_list for more details. A value of means none and is used to preserve this value for the next run through Configure.

p

package

From package.U:

This variable contains the name of the package being constructed. It is primarily intended for the use of later Configure units.

pager

From pager.U:

This variable contains the name of the preferred pager on the system. Usual values are (the full pathnames of) more, less, pg, or cat.

passcat

From nis.U:

This variable contains a command that produces the text of the /etc/passwd file. This is normally "cat /etc/passwd", but can be "ypcat passwd" when NIS is used. On some systems, such as os390, there may be no equivalent command, in which case this variable is unset.

patchlevel

From patchlevel.U:

The patchlevel level of this package. The value of patchlevel comes from the patchlevel.h file. In a version number such as 5.6.1, this is the 6. In patchlevel.h, this is referred to as PERL_VERSION.

path_sep

From Unix.U:

This is an old synonym for p_ in Head.U, the character used to separate elements in the command shell search PATH.

perl5

From perl5.U:

This variable contains the full path (if any) to a previously installed perl5.005 or later suitable for running the script to determine inc_version_list.

perl

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

perl_patchlevel

From patchlevel.U:

This is the Perl patch level, a numeric change identifier, as defined by whichever source code maintenance system is used to maintain the patches; currently Perforce. It does not correlate with the Perl version numbers or the maintenance versus development dichotomy except by also being increasing.

P

PERL_REVISION

From Oldsyms.U:

In a Perl version number such as 5.6.2, this is the 5. This value is manually set in patchlevel.h

PERL_SUBVERSION

From Oldsyms.U:

In a Perl version number such as 5.6.2, this is the 2. Values greater than 50 represent potentially unstable development subversions. This value is manually set in patchlevel.h

PERL_VERSION

From Oldsyms.U:

In a Perl version number such as 5.6.2, this is the 6. This value is manually set in patchlevel.h

perladmin

From perladmin.U:

Electronic mail address of the perl5 administrator.

perllibs

From End.U:

The list of libraries needed by Perl only (any libraries needed by extensions only will by dropped, if using dynamic loading).

perlpath

From perlpath.U:

This variable contains the eventual value of the PERLPATH symbol, which contains the name of the perl interpreter to be used in shell scripts and in the "eval exec" idiom. This variable is not necessarily the pathname of the file containing the perl interpreter; you must append the executable extension (_exe) if it is not already present. Note that Perl code that runs during the Perl build process cannot reference this variable, as Perl may not have been installed, or even if installed, may be a different version of Perl.

pg

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the pg program. After Configure runs, the value is reset to a plain pg and is not useful.

phostname

From myhostname.U:

This variable contains the eventual value of the PHOSTNAME symbol, which is a command that can be fed to popen() to get the host name. The program should probably not presume that the domain is or isn't there already.

pidtype

From pidtype.U:

This variable defines PIDTYPE to be something like pid_t, int, ushort, or whatever type is used to declare process ids in the kernel.

plibpth

From libpth.U:

Holds the private path used by Configure to find out the libraries. Its value is prepend to libpth. This variable takes care of special machines, like the mips. Usually, it should be empty.

pmake

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

pr

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

prefix

From prefix.U:

This variable holds the name of the directory below which the user will install the package. Usually, this is /usr/local, and executables go in /usr/local/bin, library stuff in /usr/local/lib, man pages in /usr/local/man, etc. It is only used to set defaults for things in bin.U, mansrc.U, privlib.U, or scriptdir.U.

prefixexp

From prefix.U:

This variable holds the full absolute path of the directory below which the user will install the package. Derived from prefix.

privlib

From privlib.U:

This variable contains the eventual value of the PRIVLIB symbol, which is the name of the private library for this package. It may have a ~ on the front. It is up to the makefile to eventually create this directory while performing installation (with ~ substitution).

privlibexp

From privlib.U:

This variable is the ~name expanded version of privlib, so that you may use it directly in Makefiles or shell scripts.

procselfexe

From d_procselfexe.U:

If d_procselfexe is defined, $procselfexe is the filename of the symbolic link pointing to the absolute pathname of the executing program.

prototype

From prototype.U:

This variable holds the eventual value of CAN_PROTOTYPE, which indicates the C compiler can handle funciton prototypes.

ptrsize

From ptrsize.U:

This variable contains the value of the PTRSIZE symbol, which indicates to the C program how many bytes there are in a pointer.

q

quadkind

From quadtype.U:

This variable, if defined, encodes the type of a quad: 1 = int, 2 = long, 3 = long long, 4 = int64_t.

quadtype

From quadtype.U:

This variable defines Quad_t to be something like long, int, long long, int64_t, or whatever type is used for 64-bit integers.

r

randbits

From randfunc.U:

Indicates how many bits are produced by the function used to generate normalized random numbers.

randfunc

From randfunc.U:

Indicates the name of the random number function to use. Values include drand48, random, and rand. In C programs, the Drand01 macro is defined to generate uniformly distributed random numbers over the range [0., 1.[ (see drand01 and nrand).

random_r_proto

From d_random_r.U:

This variable encodes the prototype of random_r. It is zero if d_random_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_random_r is defined.

randseedtype

From randfunc.U:

Indicates the type of the argument of the seedfunc.

ranlib

From orderlib.U:

This variable is set to the pathname of the ranlib program, if it is needed to generate random libraries. Set to : if ar can generate random libraries or if random libraries are not supported

rd_nodata

From nblock_io.U:

This variable holds the return code from read() when no data is present. It should be -1, but some systems return 0 when O_NDELAY is used, which is a shame because you cannot make the difference between no data and an EOF.. Sigh!

readdir64_r_proto

From d_readdir64_r.U:

This variable encodes the prototype of readdir64_r. It is zero if d_readdir64_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_readdir64_r is defined.

readdir_r_proto

From d_readdir_r.U:

This variable encodes the prototype of readdir_r. It is zero if d_readdir_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_readdir_r is defined.

revision

From patchlevel.U:

The value of revision comes from the patchlevel.h file. In a version number such as 5.6.1, this is the 5. In patchlevel.h, this is referred to as PERL_REVISION.

rm

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the rm program. After Configure runs, the value is reset to a plain rm and is not useful.

rmail

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

run

From Cross.U:

This variable contains the command used by Configure to copy and execute a cross-compiled executable in the target host. Useful and available only during Perl build. Empty string '' if not cross-compiling.

runnm

From usenm.U:

This variable contains true or false depending whether the nm extraction should be performed or not, according to the value of usenm and the flags on the Configure command line.

s

sched_yield

From d_pthread_y.U:

This variable defines the way to yield the execution of the current thread.

scriptdir

From scriptdir.U:

This variable holds the name of the directory in which the user wants to put publicly scripts for the package in question. It is either the same directory as for binaries, or a special one that can be mounted across different architectures, like /usr/share. Programs must be prepared to deal with ~name expansion.

scriptdirexp

From scriptdir.U:

This variable is the same as scriptdir, but is filename expanded at configuration time, for programs not wanting to bother with it.

sed

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the sed program. After Configure runs, the value is reset to a plain sed and is not useful.

seedfunc

From randfunc.U:

Indicates the random number generating seed function. Values include srand48, srandom, and srand.

selectminbits

From selectminbits.U:

This variable holds the minimum number of bits operated by select. That is, if you do select(n, ...), how many bits at least will be cleared in the masks if some activity is detected. Usually this is either n or 32*ceil(n/32), especially many little-endians do the latter. This is only useful if you have select(), naturally.

selecttype

From selecttype.U:

This variable holds the type used for the 2nd, 3rd, and 4th arguments to select. Usually, this is fd_set *, if HAS_FD_SET is defined, and int * otherwise. This is only useful if you have select(), naturally.

sendmail

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

setgrent_r_proto

From d_setgrent_r.U:

This variable encodes the prototype of setgrent_r. It is zero if d_setgrent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setgrent_r is defined.

sethostent_r_proto

From d_sethostent_r.U:

This variable encodes the prototype of sethostent_r. It is zero if d_sethostent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_sethostent_r is defined.

setlocale_r_proto

From d_setlocale_r.U:

This variable encodes the prototype of setlocale_r. It is zero if d_setlocale_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setlocale_r is defined.

setnetent_r_proto

From d_setnetent_r.U:

This variable encodes the prototype of setnetent_r. It is zero if d_setnetent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setnetent_r is defined.

setprotoent_r_proto

From d_setprotoent_r.U:

This variable encodes the prototype of setprotoent_r. It is zero if d_setprotoent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setprotoent_r is defined.

setpwent_r_proto

From d_setpwent_r.U:

This variable encodes the prototype of setpwent_r. It is zero if d_setpwent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setpwent_r is defined.

setservent_r_proto

From d_setservent_r.U:

This variable encodes the prototype of setservent_r. It is zero if d_setservent_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_setservent_r is defined.

sh

From sh.U:

This variable contains the full pathname of the shell used on this system to execute Bourne shell scripts. Usually, this will be /bin/sh, though it's possible that some systems will have /bin/ksh, /bin/pdksh, /bin/ash, /bin/bash, or even something such as D:/bin/sh.exe. This unit comes before Options.U, so you can't set sh with a -D option, though you can override this (and startsh) with -O -Dsh=/bin/whatever -Dstartsh=whatever

shar

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

sharpbang

From spitshell.U:

This variable contains the string #! if this system supports that construct.

shmattype

From d_shmat.U:

This symbol contains the type of pointer returned by shmat(). It can be void * or char *.

shortsize

From intsize.U:

This variable contains the value of the SHORTSIZE symbol which indicates to the C program how many bytes there are in a short.

shrpenv

From libperl.U:

If the user builds a shared libperl.so, then we need to tell the perl executable where it will be able to find the installed libperl.so. One way to do this on some systems is to set the environment variable LD_RUN_PATH to the directory that will be the final location of the shared libperl.so. The makefile can use this with something like $shrpenv $(CC) -o perl perlmain.o $libperl $libs Typical values are shrpenv="env LD_RUN_PATH=$archlibexp/CORE" or shrpenv='' See the main perl Makefile.SH for actual working usage. Alternatively, we might be able to use a command line option such as -R $archlibexp/CORE (Solaris) or -Wl,-rpath $archlibexp/CORE (Linux).

shsharp

From spitshell.U:

This variable tells further Configure units whether your sh can handle # comments.

sig_count

From sig_name.U:

This variable holds a number larger than the largest valid signal number. This is usually the same as the NSIG macro.

sig_name

From sig_name.U:

This variable holds the signal names, space separated. The leading SIG in signal name is removed. A ZERO is prepended to the list. This is currently not used, sig_name_init is used instead.

sig_name_init

From sig_name.U:

This variable holds the signal names, enclosed in double quotes and separated by commas, suitable for use in the SIG_NAME definition below. A ZERO is prepended to the list, and the list is terminated with a plain 0. The leading SIG in signal names is removed. See sig_num.

sig_num

From sig_name.U:

This variable holds the signal numbers, space separated. A ZERO is prepended to the list (corresponding to the fake SIGZERO). Those numbers correspond to the value of the signal listed in the same place within the sig_name list. This is currently not used, sig_num_init is used instead.

sig_num_init

From sig_name.U:

This variable holds the signal numbers, enclosed in double quotes and separated by commas, suitable for use in the SIG_NUM definition below. A ZERO is prepended to the list, and the list is terminated with a plain 0.

sig_size

From sig_name.U:

This variable contains the number of elements of the sig_name and sig_num arrays.

signal_t

From d_voidsig.U:

This variable holds the type of the signal handler (void or int).

sitearch

From sitearch.U:

This variable contains the eventual value of the SITEARCH symbol, which is the name of the private library for this package. It may have a ~ on the front. It is up to the makefile to eventually create this directory while performing installation (with ~ substitution). The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local architecture-dependent modules in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitearchexp

From sitearch.U:

This variable is the ~name expanded version of sitearch, so that you may use it directly in Makefiles or shell scripts.

sitebin

From sitebin.U:

This variable holds the name of the directory in which the user wants to put add-on publicly executable files for the package in question. It is most often a local directory such as /usr/local/bin. Programs using this variable must be prepared to deal with ~name substitution. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local executables in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitebinexp

From sitebin.U:

This is the same as the sitebin variable, but is filename expanded at configuration time, for use in your makefiles.

sitehtml1dir

From sitehtml1dir.U:

This variable contains the name of the directory in which site-specific html source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local html pages in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitehtml1direxp

From sitehtml1dir.U:

This variable is the same as the sitehtml1dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

sitehtml3dir

From sitehtml3dir.U:

This variable contains the name of the directory in which site-specific library html source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local library html pages in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitehtml3direxp

From sitehtml3dir.U:

This variable is the same as the sitehtml3dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

sitelib

From sitelib.U:

This variable contains the eventual value of the SITELIB symbol, which is the name of the private library for this package. It may have a ~ on the front. It is up to the makefile to eventually create this directory while performing installation (with ~ substitution). The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local architecture-independent modules in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitelib_stem

From sitelib.U:

This variable is $sitelibexp with any trailing version-specific component removed. The elements in inc_version_list (inc_version_list.U) can be tacked onto this variable to generate a list of directories to search.

sitelibexp

From sitelib.U:

This variable is the ~name expanded version of sitelib, so that you may use it directly in Makefiles or shell scripts.

siteman1dir

From siteman1dir.U:

This variable contains the name of the directory in which site-specific manual source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local man1 pages in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

siteman1direxp

From siteman1dir.U:

This variable is the same as the siteman1dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

siteman3dir

From siteman3dir.U:

This variable contains the name of the directory in which site-specific library man source pages are to be put. It is the responsibility of the Makefile.SH to get the value of this into the proper command. You must be prepared to do the ~name expansion yourself. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local man3 pages in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

siteman3direxp

From siteman3dir.U:

This variable is the same as the siteman3dir variable, but is filename expanded at configuration time, for convenient use in makefiles.

siteprefix

From siteprefix.U:

This variable holds the full absolute path of the directory below which the user will install add-on packages. See INSTALL for usage and examples.

siteprefixexp

From siteprefix.U:

This variable holds the full absolute path of the directory below which the user will install add-on packages. Derived from siteprefix.

sitescript

From sitescript.U:

This variable holds the name of the directory in which the user wants to put add-on publicly executable files for the package in question. It is most often a local directory such as /usr/local/bin. Programs using this variable must be prepared to deal with ~name substitution. The standard distribution will put nothing in this directory. After perl has been installed, users may install their own local scripts in this directory with MakeMaker Makefile.PL or equivalent. See INSTALL for details.

sitescriptexp

From sitescript.U:

This is the same as the sitescript variable, but is filename expanded at configuration time, for use in your makefiles.

sizesize

From sizesize.U:

This variable contains the size of a sizetype in bytes.

sizetype

From sizetype.U:

This variable defines sizetype to be something like size_t, unsigned long, or whatever type is used to declare length parameters for string functions.

sleep

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

smail

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

so

From so.U:

This variable holds the extension used to identify shared libraries (also known as shared objects) on the system. Usually set to so.

sockethdr

From d_socket.U:

This variable has any cpp -I flags needed for socket support.

socketlib

From d_socket.U:

This variable has the names of any libraries needed for socket support.

socksizetype

From socksizetype.U:

This variable holds the type used for the size argument for various socket calls like accept. Usual values include socklen_t, size_t, and int.

sort

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the sort program. After Configure runs, the value is reset to a plain sort and is not useful.

spackage

From package.U:

This variable contains the name of the package being constructed, with the first letter uppercased, i.e. suitable for starting sentences.

spitshell

From spitshell.U:

This variable contains the command necessary to spit out a runnable shell on this system. It is either cat or a grep -v for # comments.

sPRId64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit decimal numbers (format d) for output.

sPRIeldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format e) for output.

sPRIEUldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format E) for output. The U in the name is to separate this from sPRIeldbl so that even case-blind systems can see the difference.

sPRIfldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format f) for output.

sPRIFUldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format F) for output. The U in the name is to separate this from sPRIfldbl so that even case-blind systems can see the difference.

sPRIgldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format g) for output.

sPRIGUldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format G) for output. The U in the name is to separate this from sPRIgldbl so that even case-blind systems can see the difference.

sPRIi64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit decimal numbers (format i) for output.

sPRIo64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit octal numbers (format o) for output.

sPRIu64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit unsigned decimal numbers (format u) for output.

sPRIx64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit hexadecimal numbers (format x) for output.

sPRIXU64

From quadfio.U:

This variable, if defined, contains the string used by stdio to format 64-bit hExADECimAl numbers (format X) for output. The U in the name is to separate this from sPRIx64 so that even case-blind systems can see the difference.

srand48_r_proto

From d_srand48_r.U:

This variable encodes the prototype of srand48_r. It is zero if d_srand48_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_srand48_r is defined.

srandom_r_proto

From d_srandom_r.U:

This variable encodes the prototype of srandom_r. It is zero if d_srandom_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_srandom_r is defined.

src

From src.U:

This variable holds the path to the package source. It is up to the Makefile to use this variable and set VPATH accordingly to find the sources remotely.

sSCNfldbl

From longdblfio.U:

This variable, if defined, contains the string used by stdio to format long doubles (format f) for input.

ssizetype

From ssizetype.U:

This variable defines ssizetype to be something like ssize_t, long or int. It is used by functions that return a count of bytes or an error condition. It must be a signed type. We will pick a type such that sizeof(SSize_t) == sizeof(Size_t).

startperl

From startperl.U:

This variable contains the string to put on the front of a perl script to make sure (hopefully) that it runs with perl and not some shell. Of course, that leading line must be followed by the classical perl idiom: eval 'exec perl -S $0 ${1+$@}' if $running_under_some_shell; to guarantee perl startup should the shell execute the script. Note that this magic incatation is not understood by csh.

startsh

From startsh.U:

This variable contains the string to put on the front of a shell script to make sure (hopefully) that it runs with sh and not some other shell.

static_ext

From Extensions.U:

This variable holds a list of XS extension files we want to link statically into the package. It is used by Makefile.

stdchar

From stdchar.U:

This variable conditionally defines STDCHAR to be the type of char used in stdio.h. It has the values "unsigned char" or char.

stdio_base

From d_stdstdio.U:

This variable defines how, given a FILE pointer, fp, to access the _base field (or equivalent) of stdio.h's FILE structure. This will be used to define the macro FILE_base(fp).

stdio_bufsiz

From d_stdstdio.U:

This variable defines how, given a FILE pointer, fp, to determine the number of bytes store in the I/O buffer pointer to by the _base field (or equivalent) of stdio.h's FILE structure. This will be used to define the macro FILE_bufsiz(fp).

stdio_cnt

From d_stdstdio.U:

This variable defines how, given a FILE pointer, fp, to access the _cnt field (or equivalent) of stdio.h's FILE structure. This will be used to define the macro FILE_cnt(fp).

stdio_filbuf

From d_stdstdio.U:

This variable defines how, given a FILE pointer, fp, to tell stdio to refill its internal buffers (?). This will be used to define the macro FILE_filbuf(fp).

stdio_ptr

From d_stdstdio.U:

This variable defines how, given a FILE pointer, fp, to access the _ptr field (or equivalent) of stdio.h's FILE structure. This will be used to define the macro FILE_ptr(fp).

stdio_stream_array

From stdio_streams.U:

This variable tells the name of the array holding the stdio streams. Usual values include _iob, __iob, and __sF.

strerror_r_proto

From d_strerror_r.U:

This variable encodes the prototype of strerror_r. It is zero if d_strerror_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_strerror_r is defined.

strings

From i_string.U:

This variable holds the full path of the string header that will be used. Typically /usr/include/string.h or /usr/include/strings.h.

submit

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

subversion

From patchlevel.U:

The subversion level of this package. The value of subversion comes from the patchlevel.h file. In a version number such as 5.6.1, this is the 1. In patchlevel.h, this is referred to as PERL_SUBVERSION. This is unique to perl.

sysman

From sysman.U:

This variable holds the place where the manual is located on this system. It is not the place where the user wants to put his manual pages. Rather it is the place where Configure may look to find manual for unix commands (section 1 of the manual usually). See mansrc.

t

tail

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

tar

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

targetarch

From Cross.U:

If cross-compiling, this variable contains the target architecture. If not, this will be empty.

tbl

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

tee

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

test

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the test program. After Configure runs, the value is reset to a plain test and is not useful.

timeincl

From i_time.U:

This variable holds the full path of the included time header(s).

timetype

From d_time.U:

This variable holds the type returned by time(). It can be long, or time_t on BSD sites (in which case <sys/types.h> should be included). Anyway, the type Time_t should be used.

tmpnam_r_proto

From d_tmpnam_r.U:

This variable encodes the prototype of tmpnam_r. It is zero if d_tmpnam_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_tmpnam_r is defined.

to

From Cross.U:

This variable contains the command used by Configure to copy to from the target host. Useful and available only during Perl build. The string : if not cross-compiling.

touch

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the touch program. After Configure runs, the value is reset to a plain touch and is not useful.

tr

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the tr program. After Configure runs, the value is reset to a plain tr and is not useful.

trnl

From trnl.U:

This variable contains the value to be passed to the tr(1) command to transliterate a newline. Typical values are \012 and \n. This is needed for EBCDIC systems where newline is not necessarily \012.

troff

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

ttyname_r_proto

From d_ttyname_r.U:

This variable encodes the prototype of ttyname_r. It is zero if d_ttyname_r is undef, and one of the REENTRANT_PROTO_T_ABC macros of reentr.h if d_ttyname_r is defined.

u

u16size

From perlxv.U:

This variable is the size of an U16 in bytes.

u16type

From perlxv.U:

This variable contains the C type used for Perl's U16.

u32size

From perlxv.U:

This variable is the size of an U32 in bytes.

u32type

From perlxv.U:

This variable contains the C type used for Perl's U32.

u64size

From perlxv.U:

This variable is the size of an U64 in bytes.

u64type

From perlxv.U:

This variable contains the C type used for Perl's U64.

u8size

From perlxv.U:

This variable is the size of an U8 in bytes.

u8type

From perlxv.U:

This variable contains the C type used for Perl's U8.

uidformat

From uidf.U:

This variable contains the format string used for printing a Uid_t.

uidsign

From uidsign.U:

This variable contains the signedness of a uidtype. 1 for unsigned, -1 for signed.

uidsize

From uidsize.U:

This variable contains the size of a uidtype in bytes.

uidtype

From uidtype.U:

This variable defines Uid_t to be something like uid_t, int, ushort, or whatever type is used to declare user ids in the kernel.

uname

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the uname program. After Configure runs, the value is reset to a plain uname and is not useful.

uniq

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the uniq program. After Configure runs, the value is reset to a plain uniq and is not useful.

uquadtype

From quadtype.U:

This variable defines Uquad_t to be something like unsigned long, unsigned int, unsigned long long, uint64_t, or whatever type is used for 64-bit integers.

use5005threads

From usethreads.U:

This variable conditionally defines the USE_5005THREADS symbol, and indicates that Perl should be built to use the 5.005-based threading implementation.

use64bitall

From use64bits.U:

This variable conditionally defines the USE_64_BIT_ALL symbol, and indicates that 64-bit integer types should be used when available. The maximal possible 64-bitness is employed: LP64 or ILP64, meaning that you will be able to use more than 2 gigabytes of memory. This mode is even more binary incompatible than USE_64_BIT_INT. You may not be able to run the resulting executable in a 32-bit CPU at all or you may need at least to reboot your OS to 64-bit mode.

use64bitint

From use64bits.U:

This variable conditionally defines the USE_64_BIT_INT symbol, and indicates that 64-bit integer types should be used when available. The minimal possible 64-bitness is employed, just enough to get 64-bit integers into Perl. This may mean using for example "long longs", while your memory may still be limited to 2 gigabytes.

usecrosscompile

From Cross.U:

This variable conditionally defines the USE_CROSS_COMPILE symbol, and indicates that Perl has been cross-compiled.

usedl

From dlsrc.U:

This variable indicates if the system supports dynamic loading of some sort. See also dlsrc and dlobj.

usefaststdio

From usefaststdio.U:

This variable conditionally defines the USE_FAST_STDIO symbol, and indicates that Perl should be built to use fast stdio. Defaults to define in Perls 5.8 and earlier, to undef later.

useithreads

From usethreads.U:

This variable conditionally defines the USE_ITHREADS symbol, and indicates that Perl should be built to use the interpreter-based threading implementation.

uselargefiles

From uselfs.U:

This variable conditionally defines the USE_LARGE_FILES symbol, and indicates that large file interfaces should be used when available.

uselongdouble

From uselongdbl.U:

This variable conditionally defines the USE_LONG_DOUBLE symbol, and indicates that long doubles should be used when available.

usemallocwrap

From mallocsrc.U:

This variable contains y if we are wrapping malloc to prevent integer overflow during size calculations.

usemorebits

From usemorebits.U:

This variable conditionally defines the USE_MORE_BITS symbol, and indicates that explicit 64-bit interfaces and long doubles should be used when available.

usemultiplicity

From usemultiplicity.U:

This variable conditionally defines the MULTIPLICITY symbol, and indicates that Perl should be built to use multiplicity.

usemymalloc

From mallocsrc.U:

This variable contains y if the malloc that comes with this package is desired over the system's version of malloc. People often include special versions of malloc for effiency, but such versions are often less portable. See also mallocsrc and mallocobj. If this is y, then -lmalloc is removed from $libs.

usenm

From usenm.U:

This variable contains true or false depending whether the nm extraction is wanted or not.

useopcode

From Extensions.U:

This variable holds either true or false to indicate whether the Opcode extension should be used. The sole use for this currently is to allow an easy mechanism for users to skip the Opcode extension from the Configure command line.

useperlio

From useperlio.U:

This variable conditionally defines the USE_PERLIO symbol, and indicates that the PerlIO abstraction should be used throughout.

useposix

From Extensions.U:

This variable holds either true or false to indicate whether the POSIX extension should be used. The sole use for this currently is to allow an easy mechanism for hints files to indicate that POSIX will not compile on a particular system.

usereentrant

From usethreads.U:

This variable conditionally defines the USE_REENTRANT_API symbol, which indicates that the thread code may try to use the various _r versions of library functions. This is only potentially meaningful if usethreads is set and is very experimental, it is not even prompted for.

usesfio

From d_sfio.U:

This variable is set to true when the user agrees to use sfio. It is set to false when sfio is not available or when the user explicitely requests not to use sfio. It is here primarily so that command-line settings can override the auto-detection of d_sfio without running into a "WHOA THERE".

useshrplib

From libperl.U:

This variable is set to true if the user wishes to build a shared libperl, and false otherwise.

usesocks

From usesocks.U:

This variable conditionally defines the USE_SOCKS symbol, and indicates that Perl should be built to use SOCKS.

usethreads

From usethreads.U:

This variable conditionally defines the USE_THREADS symbol, and indicates that Perl should be built to use threads.

usevendorprefix

From vendorprefix.U:

This variable tells whether the vendorprefix and consequently other vendor* paths are in use.

usevfork

From d_vfork.U:

This variable is set to true when the user accepts to use vfork. It is set to false when no vfork is available or when the user explicitely requests not to use vfork.

usrinc

From usrinc.U:

This variable holds the path of the include files, which is usually /usr/include. It is mainly used by other Configure units.

uuname

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

uvoformat

From perlxvf.U:

This variable contains the format string used for printing a Perl UV as an unsigned octal integer.

uvsize

From perlxv.U:

This variable is the size of a UV in bytes.

uvtype

From perlxv.U:

This variable contains the C type used for Perl's UV.

uvuformat

From perlxvf.U:

This variable contains the format string used for printing a Perl UV as an unsigned decimal integer.

uvxformat

From perlxvf.U:

This variable contains the format string used for printing a Perl UV as an unsigned hexadecimal integer in lowercase abcdef.

uvXUformat

From perlxvf.U:

This variable contains the format string used for printing a Perl UV as an unsigned hexadecimal integer in uppercase ABCDEF.

v

vendorarch

From vendorarch.U:

This variable contains the value of the PERL_VENDORARCH symbol. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own architecture-dependent modules and extensions in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorarchexp

From vendorarch.U:

This variable is the ~name expanded version of vendorarch, so that you may use it directly in Makefiles or shell scripts.

vendorbin

From vendorbin.U:

This variable contains the eventual value of the VENDORBIN symbol. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place additional binaries in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorbinexp

From vendorbin.U:

This variable is the ~name expanded version of vendorbin, so that you may use it directly in Makefiles or shell scripts.

vendorhtml1dir

From vendorhtml1dir.U:

This variable contains the name of the directory for html pages. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own html pages in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorhtml1direxp

From vendorhtml1dir.U:

This variable is the ~name expanded version of vendorhtml1dir, so that you may use it directly in Makefiles or shell scripts.

vendorhtml3dir

From vendorhtml3dir.U:

This variable contains the name of the directory for html library pages. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own html pages for modules and extensions in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorhtml3direxp

From vendorhtml3dir.U:

This variable is the ~name expanded version of vendorhtml3dir, so that you may use it directly in Makefiles or shell scripts.

vendorlib

From vendorlib.U:

This variable contains the eventual value of the VENDORLIB symbol, which is the name of the private library for this package. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own modules in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorlib_stem

From vendorlib.U:

This variable is $vendorlibexp with any trailing version-specific component removed. The elements in inc_version_list (inc_version_list.U) can be tacked onto this variable to generate a list of directories to search.

vendorlibexp

From vendorlib.U:

This variable is the ~name expanded version of vendorlib, so that you may use it directly in Makefiles or shell scripts.

vendorman1dir

From vendorman1dir.U:

This variable contains the name of the directory for man1 pages. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own man1 pages in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorman1direxp

From vendorman1dir.U:

This variable is the ~name expanded version of vendorman1dir, so that you may use it directly in Makefiles or shell scripts.

vendorman3dir

From vendorman3dir.U:

This variable contains the name of the directory for man3 pages. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place their own man3 pages in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorman3direxp

From vendorman3dir.U:

This variable is the ~name expanded version of vendorman3dir, so that you may use it directly in Makefiles or shell scripts.

vendorprefix

From vendorprefix.U:

This variable holds the full absolute path of the directory below which the vendor will install add-on packages. See INSTALL for usage and examples.

vendorprefixexp

From vendorprefix.U:

This variable holds the full absolute path of the directory below which the vendor will install add-on packages. Derived from vendorprefix.

vendorscript

From vendorscript.U:

This variable contains the eventual value of the VENDORSCRIPT symbol. It may have a ~ on the front. The standard distribution will put nothing in this directory. Vendors who distribute perl may wish to place additional executable scripts in this directory with MakeMaker Makefile.PL INSTALLDIRS=vendor or equivalent. See INSTALL for details.

vendorscriptexp

From vendorscript.U:

This variable is the ~name expanded version of vendorscript, so that you may use it directly in Makefiles or shell scripts.

version

From patchlevel.U:

The full version number of this package, such as 5.6.1 (or 5_6_1). This combines revision, patchlevel, and subversion to get the full version number, including any possible subversions. This is suitable for use as a directory name, and hence is filesystem dependent.

version_patchlevel_string

From patchlevel.U:

This is a string combining version, subversion and perl_patchlevel (if perl_patchlevel is non-zero). It is typically something like 'version 7 subversion 1' or 'version 7 subversion 1 patchlevel 11224' It is computed here to avoid duplication of code in myconfig.SH and lib/Config.pm.

versiononly

From versiononly.U:

If set, this symbol indicates that only the version-specific components of a perl installation should be installed. This may be useful for making a test installation of a new version without disturbing the existing installation. Setting versiononly is equivalent to setting installperl's -v option. In particular, the non-versioned scripts and programs such as a2p, c2ph, h2xs, pod2*, and perldoc are not installed (see INSTALL for a more complete list). Nor are the man pages installed. Usually, this is undef.

vi

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

voidflags

From voidflags.U:

This variable contains the eventual value of the VOIDFLAGS symbol, which indicates how much support of the void type is given by this compiler. See VOIDFLAGS for more info.

x

xlibpth

From libpth.U:

This variable holds extra path (space-separated) used to find libraries on this platform, for example CPU-specific libraries (on multi-CPU platforms) may be listed here.

y

yacc

From yacc.U:

This variable holds the name of the compiler compiler we want to use in the Makefile. It can be yacc, byacc, or bison -y.

yaccflags

From yacc.U:

This variable contains any additional yacc flags desired by the user. It is up to the Makefile to use this.

z

zcat

From Loc.U:

This variable is defined but not used by Configure. The value is a plain '' and is not useful.

zip

From Loc.U:

This variable is used internally by Configure to determine the full pathname (if any) of the zip program. After Configure runs, the value is reset to a plain zip and is not useful.

NOTE

This module contains a good example of how to use tie to implement a cache and an example of how to make a tied variable readonly to those outside of it.


Config::Tiny - Read/Write .ini style files with as little code as possible

  • CONFIGURATION FILE SYNTAX
  • METHODS
    • new
    • read $filename
    • read_string $string;
    • write $filename
    • write_string
    • errstr
  • SUPPORT
  • AUTHOR
  • ACKNOWLEGEMENTS
  • SEE ALSO
  • COPYRIGHT

NAME

Config::Tiny - Read/Write .ini style files with as little code as possible

SYNOPSIS

    # In your configuration file
    rootproperty=blah
    [section]
    one=twp
    three= four
    Foo =Bar
    empty=
    # In your program
    use Config::Tiny;

    # Create a config
    my $Config = Config::Tiny->new();

    # Open the config
    $Config = Config::Tiny->read( 'file.conf' );

    # Reading properties
    my $rootproperty = $Config->{_}->{rootproperty};
    my $one = $Config->{section}->{one};
    my $Foo = $Config->{section}->{Foo};

    # Changing data
    $Config->{newsection} = { this => 'that' }; # Add a section
    $Config->{section}->{Foo} = 'Not Bar!';     # Change a value
    delete $Config->{_};                        # Delete a value or section

    # Save a config
    $Config->write( 'file.conf' );

DESCRIPTION

Config::Tiny is a perl class to read and write .ini style configuration files with as little code as possible, reducing load time and memory overhead. Most of the time it is accepted that Perl applications use a lot of memory and modules. The ::Tiny family of modules is specifically intended to provide an ultralight alternative to the standard modules.

This module is primarily for reading human written files, and anything we write shouldn't need to have documentation/comments. If you need something with more power move up to the Config::Simple manpage, the Config::General manpage or one of the many other Config:: modules. To rephrase, the Config::Tiny manpage does not preserve your comments, whitespace, or the order of your config file.

CONFIGURATION FILE SYNTAX

Files are the same format as for windows .ini files. For example:

        [section]
        var1=value1
        var2=value2

If a property is outside of a section at the beginning of a file, it will be assigned to the "root section", available at $Config->{_}.

Lines starting with '#' or ';' are considered comments and ignored, as are blank lines.

When writing back to the config file, all comments, custom whitespace, and the ordering of your config file elements is discarded. If you need to keep the human elements of a config when writing back, upgrade to something better, this module is not for you.

METHODS

new

The constructor new creates and returns an empty Config::Tiny object.

read $filename

The read constructor reads a config file, and returns a new Config::Tiny object containing the properties in the file.

Returns the object on success, or undef on error.

When read fails, Config::Tiny sets an error message internally you can recover via <Config::Tiny-errstr>>. Although in some cases a failed read will also set the operating system error variable $!, not all errors do and you should not rely on using the $! variable.

read_string $string;

The read_string method takes as argument the contents of a config file as a string and returns the Config::Tiny object for it.

write $filename

The write method generates the file content for the properties, and writes it to disk to the filename specified.

Returns true on success or undef on error.

write_string

Generates the file content for the object and returns it as a string.

errstr

When an error occurs, you can retrieve the error message either from the $Config::Tiny::errstr variable, or using the errstr() method.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html

For other issues, or commercial enhancement or support, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

ACKNOWLEGEMENTS

Thanks to Sherzod Ruzmetov <sherzodr@cpan.org> for the Config::Simple manpage, which inspired this module by being not quite "simple" enough for me :)

SEE ALSO

the Config::Simple manpage, the Config::General manpage, ali.as

COPYRIGHT

Copyright 2002 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Cwd - get pathname of current working directory

    • getcwd and friends
    • abs_path and friends
    • $ENV{PWD}
  • NOTES
  • AUTHOR
  • COPYRIGHT
  • SEE ALSO

NAME

Cwd - get pathname of current working directory

SYNOPSIS

    use Cwd;
    my $dir = getcwd;

    use Cwd 'abs_path';
    my $abs_path = abs_path($file);

DESCRIPTION

This module provides functions for determining the pathname of the current working directory. It is recommended that getcwd (or another *cwd() function) be used in all code to ensure portability.

By default, it exports the functions cwd(), getcwd(), fastcwd(), and fastgetcwd() (and, on Win32, getdcwd()) into the caller's namespace.

getcwd and friends

Each of these functions are called without arguments and return the absolute path of the current working directory.

getcwd
    my $cwd = getcwd();

Returns the current working directory.

Re-implements the getcwd(3) (or getwd(3)) functions in Perl.

cwd
    my $cwd = cwd();

The cwd() is the most natural form for the current architecture. For most systems it is identical to `pwd` (but without the trailing line terminator).

fastcwd
    my $cwd = fastcwd();

A more dangerous version of getcwd(), but potentially faster.

It might conceivably chdir() you out of a directory that it can't chdir() you back into. If fastcwd encounters a problem it will return undef but will probably leave you in a different directory. For a measure of extra security, if everything appears to have worked, the fastcwd() function will check that it leaves you in the same directory that it started in. If it has changed it will die with the message "Unstable directory path, current directory changed unexpectedly". That should never happen.

fastgetcwd
  my $cwd = fastgetcwd();

The fastgetcwd() function is provided as a synonym for cwd().

getdcwd
    my $cwd = getdcwd();
    my $cwd = getdcwd('C:');

The getdcwd() function is also provided on Win32 to get the current working directory on the specified drive, since Windows maintains a separate current working directory for each drive. If no drive is specified then the current drive is assumed.

This function simply calls the Microsoft C library _getdcwd() function.

abs_path and friends

These functions are exported only on request. They each take a single argument and return the absolute pathname for it. If no argument is given they'll use the current working directory.

abs_path
  my $abs_path = abs_path($file);

Uses the same algorithm as getcwd(). Symbolic links and relative-path components ("." and "..") are resolved to return the canonical pathname, just like realpath(3).

realpath
  my $abs_path = realpath($file);

A synonym for abs_path().

fast_abs_path
  my $abs_path = fast_abs_path($file);

A more dangerous, but potentially faster version of abs_path.

$ENV{PWD}

If you ask to override your chdir() built-in function,

  use Cwd qw(chdir);

then your PWD environment variable will be kept up to date. Note that it will only be kept up to date if all packages which use chdir import it from Cwd.

NOTES

  • Since the path seperators are different on some operating systems ('/' on Unix, ':' on MacPerl, etc...) we recommend you use the File::Spec modules wherever portability is a concern.

  • Actually, on Mac OS, the getcwd(), fastgetcwd() and fastcwd() functions are all aliases for the cwd() function, which, on Mac OS, calls `pwd`. Likewise, the abs_path() function is an alias for fast_abs_path().

AUTHOR

Originally by the perl5-porters.

Maintained by Ken Williams <KWILLIAMS@cpan.org>

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Portions of the C code in this library are copyright (c) 1994 by the Regents of the University of California. All rights reserved. The license on this code is compatible with the licensing of the rest of the distribution - please see the source code in Cwd.xs for the details.

SEE ALSO

the File::chdir manpage


DB - programmatic interface to the Perl debugging API (draft, subject to change)

    • Global Variables
    • API Methods
    • Client Callback Methods
  • BUGS
  • AUTHOR

NAME

DB - programmatic interface to the Perl debugging API (draft, subject to change)

SYNOPSIS

    package CLIENT;
    use DB;
    @ISA = qw(DB);

    # these (inherited) methods can be called by the client

    CLIENT->register()      # register a client package name
    CLIENT->done()          # de-register from the debugging API
    CLIENT->skippkg('hide::hide')  # ask DB not to stop in this package
    CLIENT->cont([WHERE])       # run some more (until BREAK or another breakpt)
    CLIENT->step()              # single step
    CLIENT->next()              # step over
    CLIENT->ret()               # return from current subroutine
    CLIENT->backtrace()         # return the call stack description
    CLIENT->ready()             # call when client setup is done
    CLIENT->trace_toggle()      # toggle subroutine call trace mode
    CLIENT->subs([SUBS])        # return subroutine information
    CLIENT->files()             # return list of all files known to DB
    CLIENT->lines()             # return lines in currently loaded file
    CLIENT->loadfile(FILE,LINE) # load a file and let other clients know
    CLIENT->lineevents()        # return info on lines with actions
    CLIENT->set_break([WHERE],[COND])
    CLIENT->set_tbreak([WHERE])
    CLIENT->clr_breaks([LIST])
    CLIENT->set_action(WHERE,ACTION)
    CLIENT->clr_actions([LIST])
    CLIENT->evalcode(STRING)  # eval STRING in executing code's context
    CLIENT->prestop([STRING]) # execute in code context before stopping
    CLIENT->poststop([STRING])# execute in code context before resuming
    # These methods will be called at the appropriate times.
    # Stub versions provided do nothing.
    # None of these can block.

    CLIENT->init()          # called when debug API inits itself
    CLIENT->stop(FILE,LINE) # when execution stops
    CLIENT->idle()          # while stopped (can be a client event loop)
    CLIENT->cleanup()       # just before exit
    CLIENT->output(LIST)    # called to print any output that API must show

DESCRIPTION

Perl debug information is frequently required not just by debuggers, but also by modules that need some "special" information to do their job properly, like profilers.

This module abstracts and provides all of the hooks into Perl internal debugging functionality, so that various implementations of Perl debuggers (or packages that want to simply get at the "privileged" debugging data) can all benefit from the development of this common code. Currently used by Swat, the perl/Tk GUI debugger.

Note that multiple "front-ends" can latch into this debugging API simultaneously. This is intended to facilitate things like debugging with a command line and GUI at the same time, debugging debuggers etc. [Sounds nice, but this needs some serious support -- GSAR]

In particular, this API does not provide the following functions:

  • data display

  • command processing

  • command alias management

  • user interface (tty or graphical)

These are intended to be services performed by the clients of this API.

This module attempts to be squeaky clean w.r.t use strict; and when warnings are enabled.

Global Variables

The following "public" global names can be read by clients of this API. Beware that these should be considered "readonly".

$DB::sub

Name of current executing subroutine.

%DB::sub

The keys of this hash are the names of all the known subroutines. Each value is an encoded string that has the sprintf(3) format ("%s:%d-%d", filename, fromline, toline).

$DB::single

Single-step flag. Will be true if the API will stop at the next statement.

$DB::signal

Signal flag. Will be set to a true value if a signal was caught. Clients may check for this flag to abort time-consuming operations.

$DB::trace

This flag is set to true if the API is tracing through subroutine calls.

@DB::args

Contains the arguments of current subroutine, or the @ARGV array if in the toplevel context.

@DB::dbline

List of lines in currently loaded file.

%DB::dbline

Actions in current file (keys are line numbers). The values are strings that have the sprintf(3) format ("%s\000%s", breakcondition, actioncode).

$DB::package

Package namespace of currently executing code.

$DB::filename

Currently loaded filename.

$DB::subname

Fully qualified name of currently executing subroutine.

$DB::lineno

Line number that will be executed next.

API Methods

The following are methods in the DB base class. A client must access these methods by inheritance (*not* by calling them directly), since the API keeps track of clients through the inheritance mechanism.

CLIENT->register()

register a client object/package

CLIENT->evalcode(STRING)

eval STRING in executing code context

CLIENT->skippkg('D::hide')

ask DB not to stop in these packages

CLIENT->run()

run some more (until a breakpt is reached)

CLIENT->step()

single step

CLIENT->next()

step over

CLIENT->done()

de-register from the debugging API

Client Callback Methods

The following "virtual" methods can be defined by the client. They will be called by the API at appropriate points. Note that unless specified otherwise, the debug API only defines empty, non-functional default versions of these methods.

CLIENT->init()

Called after debug API inits itself.

CLIENT->prestop([STRING])

Usually inherited from DB package. If no arguments are passed, returns the prestop action string.

CLIENT->stop()

Called when execution stops (w/ args file, line).

CLIENT->idle()

Called while stopped (can be a client event loop).

CLIENT->poststop([STRING])

Usually inherited from DB package. If no arguments are passed, returns the poststop action string.

CLIENT->evalcode(STRING)

Usually inherited from DB package. Ask for a STRING to be eval-ed in executing code context.

CLIENT->cleanup()

Called just before exit.

CLIENT->output(LIST)

Called when API must show a message (warnings, errors etc.).

BUGS

The interface defined by this module is missing some of the later additions to perl's debugging functionality. As such, this interface should be considered highly experimental and subject to change.

AUTHOR

Gurusamy Sarathy gsar@activestate.com

This code heavily adapted from an early version of perl5db.pl attributable to Larry Wall and the Perl Porters.


DBD::DBM - a DBI driver for DBM & MLDBM files

  • QUICK START
  • USAGE
    • Specifiying Files and Directories
    • Table locking and flock()
    • Specifying the DBM type
    • Adding multi-column support with MLDBM
    • Support for Berkeley DB
    • Supported SQL syntax
    • Optimizing use of key fields
    • Specifying Column Names
    • Statement handle ($sth) attributes and methods
    • The $dbh->dbm_versions() method
    • Storing Objects
  • GOTCHAS AND WARNINGS
  • GETTING HELP, MAKING SUGGESTIONS, AND REPORTING BUGS
  • ACKNOWLEDGEMENTS
  • AUTHOR AND COPYRIGHT
  • SEE ALSO

NAME

DBD::DBM - a DBI driver for DBM & MLDBM files

SYNOPSIS

 use DBI;
 $dbh = DBI->connect('dbi:DBM:');                # defaults to SDBM_File
 $dbh = DBI->connect('DBI:DBM(RaiseError=1):');  # defaults to SDBM_File
 $dbh = DBI->connect('dbi:DBM:type=GDBM_File');  # defaults to GDBM_File
 $dbh = DBI->connect('dbi:DBM:mldbm=Storable');  # MLDBM with SDBM_File
                                                 # and Storable

or

 $dbh = DBI->connect('dbi:DBM:', undef, undef);
 $dbh = DBI->connect('dbi:DBM:', undef, undef, { dbm_type => 'ODBM_File' });

and other variations on connect() as shown in the DBI docs and with the dbm_ attributes shown below

... and then use standard DBI prepare, execute, fetch, placeholders, etc., see QUICK START for an example

DESCRIPTION

DBD::DBM is a database management sytem that can work right out of the box. If you have a standard installation of Perl and a standard installation of DBI, you can begin creating, accessing, and modifying database tables without any further installation. You can also add some other modules to it for more robust capabilities if you wish.

The module uses a DBM file storage layer. DBM file storage is common on many platforms and files can be created with it in many languges. That means that, in addition to creating files with DBI/SQL, you can also use DBI/SQL to access and modify files created by other DBM modules and programs. You can also use those programs to access files created with DBD::DBM.

DBM files are stored in binary format optimized for quick retrieval when using a key field. That optimization can be used advantageously to make DBD::DBM SQL operations that use key fields very fast. There are several different "flavors" of DBM - different storage formats supported by different sorts of perl modules such as SDBM_File and MLDBM. This module supports all of the flavors that perl supports and, when used with MLDBM, supports tables with any number of columns and insertion of Perl objects into tables.

DBD::DBM has been tested with the following DBM types: SDBM_File, NDBM_File, ODBM_File, GDBM_File, DB_File, BerekeleyDB. Each type was tested both with and without MLDBM.

QUICK START

DBD::DBM operates like all other DBD drivers - it's basic syntax and operation is specified by DBI. If you're not familiar with DBI, you should start by reading the DBI manpage and the documents it points to and then come back and read this file. If you are familiar with DBI, you already know most of what you need to know to operate this module. Just jump in and create a test script something like the one shown below.

You should be aware that there are several options for the SQL engine underlying DBD::DBM, see Supported SQL syntax. There are also many options for DBM support, see especially the section on Adding multi-column support with MLDBM.

But here's a sample to get you started.

 use DBI;
 my $dbh = DBI->connect('dbi:DBM:');
 $dbh->{RaiseError} = 1;
 for my $sql( split /;\n+/,"
     CREATE TABLE user ( user_name TEXT, phone TEXT );
     INSERT INTO user VALUES ('Fred Bloggs','233-7777');
     INSERT INTO user VALUES ('Sanjay Patel','777-3333');
     INSERT INTO user VALUES ('Junk','xxx-xxxx');
     DELETE FROM user WHERE user_name = 'Junk';
     UPDATE user SET phone = '999-4444' WHERE user_name = 'Sanjay Patel';
     SELECT * FROM user
 "){
     my $sth = $dbh->prepare($sql);
     $sth->execute;
     $sth->dump_results if $sth->{NUM_OF_FIELDS};
 }
 $dbh->disconnect;

USAGE

Specifiying Files and Directories

DBD::DBM will automatically supply an appropriate file extension for the type of DBM you are using. For example, if you use SDBM_File, a table called "fruit" will be stored in two files called "fruit.pag" and "fruit.dir". You should never specify the file extensions in your SQL statements.

However, I am not aware (and therefore DBD::DBM is not aware) of all possible extensions for various DBM types. If your DBM type uses an extension other than .pag and .dir, you should set the dbm_ext attribute to the extension. And you should write me with the name of the implementation and extension so I can add it to DBD::DBM! Thanks in advance for that :-).

    $dbh = DBI->connect('dbi:DBM:ext=.db');  # .db extension is used
    $dbh = DBI->connect('dbi:DBM:ext=');     # no extension is used

or

    $dbh->{dbm_ext}='.db';                      # global setting
    $dbh->{dbm_tables}->{'qux'}->{ext}='.db';   # setting for table 'qux'

By default files are assumed to be in the current working directory. To have the module look in a different directory, specify the f_dir attribute in either the connect string or by setting the database handle attribute.

For example, this will look for the file /foo/bar/fruit (or /foo/bar/fruit.pag for DBM types that use that extension)

   my $dbh = DBI->connect('dbi:DBM:f_dir=/foo/bar');
   my $ary = $dbh->selectall_arrayref(q{ SELECT * FROM fruit });

And this will too:

   my $dbh = DBI->connect('dbi:DBM:');
   $dbh->{f_dir} = '/foo/bar';
   my $ary = $dbh->selectall_arrayref(q{ SELECT x FROM fruit });

You can also use delimited identifiers to specify paths directly in SQL statements. This looks in the same place as the two examples above but without setting f_dir:

   my $dbh = DBI->connect('dbi:DBM:');
   my $ary = $dbh->selectall_arrayref(q{
       SELECT x FROM "/foo/bar/fruit"
   });

If you have SQL::Statement installed, you can use table aliases:

   my $dbh = DBI->connect('dbi:DBM:');
   my $ary = $dbh->selectall_arrayref(q{
       SELECT f.x FROM "/foo/bar/fruit" AS f
   });

See the GOTCHAS AND WARNINGS for using DROP on tables.

Table locking and flock()

Table locking is accomplished using a lockfile which has the same name as the table's file but with the file extension '.lck' (or a lockfile extension that you suppy, see belwo). This file is created along with the table during a CREATE and removed during a DROP. Every time the table itself is opened, the lockfile is flocked(). For SELECT, this is an shared lock. For all other operations, it is an exclusive lock.

Since the locking depends on flock(), it only works on operating systems that support flock(). In cases where flock() is not implemented, DBD::DBM will not complain, it will simply behave as if the flock() had occurred although no actual locking will happen. Read the documentation for flock() if you need to understand this.

Even on those systems that do support flock(), the locking is only advisory - as is allways the case with flock(). This means that if some other program tries to access the table while DBD::DBM has the table locked, that other program will *succeed* at opening the table. DBD::DBM's locking only applies to DBD::DBM. An exception to this would be the situation in which you use a lockfile with the other program that has the same name as the lockfile used in DBD::DBM and that program also uses flock() on that lockfile. In that case, DBD::DBM and your other program will respect each other's locks.

If you wish to use a lockfile extension other than '.lck', simply specify the dbm_lockfile attribute:

  $dbh = DBI->connect('dbi:DBM:lockfile=.foo');
  $dbh->{dbm_lockfile} = '.foo';
  $dbh->{dbm_tables}->{qux}->{lockfile} = '.foo';

If you wish to disable locking, set the dbm_lockfile equal to 0.

  $dbh = DBI->connect('dbi:DBM:lockfile=0');
  $dbh->{dbm_lockfile} = 0;
  $dbh->{dbm_tables}->{qux}->{lockfile} = 0;

Specifying the DBM type

Each "flavor" of DBM stores its files in a different format and has different capabilities and different limitations. See the AnyDBM_File manpage for a comparison of DBM types.

By default, DBD::DBM uses the SDBM_File type of storage since SDBM_File comes with Perl itself. But if you have other types of DBM storage available, you can use any of them with DBD::DBM also.

You can specify the DBM type using the "dbm_type" attribute which can be set in the connection string or with the $dbh->{dbm_type} attribute for global settings or with the $dbh->{dbm_tables}->{$table_name}->{type} attribute for per-table settings in cases where a single script is accessing more than one kind of DBM file.

In the connection string, just set type=TYPENAME where TYPENAME is any DBM type such as GDBM_File, DB_File, etc. Do not use MLDBM as your dbm_type, that is set differently, see below.

 my $dbh=DBI->connect('dbi:DBM:');               # uses the default SDBM_File
 my $dbh=DBI->connect('dbi:DBM:type=GDBM_File'); # uses the GDBM_File

You can also use $dbh->{dbm_type} to set global DBM type:

 $dbh->{dbm_type} = 'GDBM_File';  # set the global DBM type
 print $dbh->{dbm_type};          # display the global DBM type

If you are going to have several tables in your script that come from different DBM types, you can use the $dbh->{dbm_tables} hash to store different settings for the various tables. You can even use this to perform joins on files that have completely different storage mechanisms.

 my $dbh->('dbi:DBM:type=GDBM_File');
 #
 # sets global default of GDBM_File

 my $dbh->{dbm_tables}->{foo}->{type} = 'DB_File';
 #
 # over-rides the global setting, but only for the table called "foo"

 print $dbh->{dbm_tables}->{foo}->{type};
 #
 # prints the dbm_type for the table "foo"

Adding multi-column support with MLDBM

Most of the DBM types only support two columns. However a CPAN module called MLDBM overcomes this limitation by allowing more than two columns. It does this by serializing the data - basically it puts a reference to an array into the second column. It can also put almost any kind of Perl object or even Perl coderefs into columns.

If you want more than two columns, you must install MLDBM. It's available for many platforms and is easy to install.

MLDBM can use three different modules to serialize the column - Data::Dumper, Storable, and FreezeThaw. Data::Dumper is the default, Storable is the fastest. MLDBM can also make use of user-defined serialization methods. All of this is available to you through DBD::DBM with just one attribute setting.

To use MLDBM with DBD::DBM, you need to set the dbm_mldbm attribute to the name of the serialization module.

Some examples:

 $dbh=DBI->connect('dbi:DBM:mldbm=Storable');  # use MLDBM with Storable
 $dbh=DBI->connect(
    'dbi:DBM:mldbm=MySerializer'           # use MLDBM with a user defined module
 );
 $dbh->{dbm_mldbm} = 'MySerializer';       # same as above
 print $dbh->{dbm_mldbm}                   # show the MLDBM serializer
 $dbh->{dbm_tables}->{foo}->{mldbm}='Data::Dumper';   # set Data::Dumper for table "foo"
 print $dbh->{dbm_tables}->{foo}->{mldbm}; # show serializer for table "foo"

MLDBM works on top of other DBM modules so you can also set a DBM type along with setting dbm_mldbm. The examples above would default to using SDBM_File with MLDBM. If you wanted GDBM_File instead, here's how:

 $dbh = DBI->connect('dbi:DBM:type=GDBM_File;mldbm=Storable');
 #
 # uses GDBM_File with MLDBM and Storable

SDBM_File, the default file type is quite limited, so if you are going to use MLDBM, you should probably use a different type, see the AnyDBM_File manpage.

See below for some GOTCHAS AND WARNINGS about MLDBM.

Support for Berkeley DB

The Berkeley DB storage type is supported through two different Perl modules - DB_File (which supports only features in old versions of Berkeley DB) and BerkeleyDB (which supports all versions). DBD::DBM supports specifying either "DB_File" or "BerkeleyDB" as a dbm_type, with or without MLDBM support.

The "BerkeleyDB" dbm_type is experimental and its interface is likely to chagne. It currently defaults to BerkeleyDB::Hash and does not currently support ::Btree or ::Recno.

With BerkeleyDB, you can specify initialization flags by setting them in your script like this:

 my $dbh = DBI->connect('dbi:DBM:type=BerkeleyDB;mldbm=Storable');
 use BerkeleyDB;
 my $env = new BerkeleyDB::Env -Home => $dir;  # and/or other Env flags
 $dbh->{dbm_berkeley_flags} = {
      'DB_CREATE'  => DB_CREATE  # pass in constants
    , 'DB_RDONLY'  => DB_RDONLY  # pass in constants
    , '-Cachesize' => 1000       # set a ::Hash flag
    , '-Env'       => $env       # pass in an environment
 };

Do not set the -Flags or -Filename flags, those are determined by the SQL (e.g. -Flags => DB_RDONLY is set automatically when you issue a SELECT statement).

Time has not permitted me to provide support in this release of DBD::DBM for further Berkeley DB features such as transactions, concurrency, locking, etc. I will be working on these in the future and would value suggestions, patches, etc.

See DB_File and BerkeleyDB for further details.

Supported SQL syntax

DBD::DBM uses a subset of SQL. The robustness of that subset depends on what other modules you have installed. Both options support basic SQL operations including CREATE TABLE, DROP TABLE, INSERT, DELETE, UPDATE, and SELECT.

Option #1: By default, this module inherits its SQL support from DBI::SQL::Nano that comes with DBI. Nano is, as its name implies, a *very* small SQL engine. Although limited in scope, it is faster than option #2 for some operations. See the DBI::SQL::Nano manpage for a description of the SQL it supports and comparisons of it with option #2.

Option #2: If you install the pure Perl CPAN module SQL::Statement, DBD::DBM will use it instead of Nano. This adds support for table aliases, for functions, for joins, and much more. If you're going to use DBD::DBM for anything other than very simple tables and queries, you should install SQL::Statement. You don't have to change DBD::DBM or your scripts in any way, simply installing SQL::Statement will give you the more robust SQL capabilities without breaking scripts written for DBI::SQL::Nano. See the SQL::Statement manpage for a description of the SQL it supports.

To find out which SQL module is working in a given script, you can use the dbm_versions() method or, if you don't need the full output and version numbers, just do this:

 print $dbh->{sql_handler};

That will print out either "SQL::Statement" or "DBI::SQL::Nano".

Optimizing use of key fields

Most "flavors" of DBM have only two physical columns (but can contain multiple logical columns as explained below). They work similarly to a Perl hash with the first column serving as the key. Like a Perl hash, DBM files permit you to do quick lookups by specifying the key and thus avoid looping through all records. Also like a Perl hash, the keys must be unique. It is impossible to create two records with the same key. To put this all more simply and in SQL terms, the key column functions as the PRIMARY KEY.

In DBD::DBM, you can take advantage of the speed of keyed lookups by using a WHERE clause with a single equal comparison on the key field. For example, the following SQL statements are optimized for keyed lookup:

 CREATE TABLE user ( user_name TEXT, phone TEXT);
 INSERT INTO user VALUES ('Fred Bloggs','233-7777');
 # ... many more inserts
 SELECT phone FROM user WHERE user_name='Fred Bloggs';

The "user_name" column is the key column since it is the first column. The SELECT statement uses the key column in a single equal comparision - "user_name='Fred Bloggs' - so the search will find it very quickly without having to loop through however many names were inserted into the table.

In contrast, thes searches on the same table are not optimized:

 1. SELECT phone FROM user WHERE user_name < 'Fred';
 2. SELECT user_name FROM user WHERE phone = '233-7777';

In #1, the operation uses a less-than (<) comparison rather than an equals comparison, so it will not be optimized for key searching. In #2, the key field "user_name" is not specified in the WHERE clause, and therefore the search will need to loop through all rows to find the desired result.

Specifying Column Names

DBM files don't have a standard way to store column names. DBD::DBM gets around this issue with a DBD::DBM specific way of storing the column names. If you are working only with DBD::DBM and not using files created by or accessed with other DBM programs, you can ignore this section.

DBD::DBM stores column names as a row in the file with the key _metadata \0. So this code

 my $dbh = DBI->connect('dbi:DBM:');
 $dbh->do("CREATE TABLE baz (foo CHAR(10), bar INTEGER)");
 $dbh->do("INSERT INTO baz (foo,bar) VALUES ('zippy',1)");

Will create a file that has a structure something like this:

  _metadata \0 | foo,bar
  zippy        | 1

The next time you access this table with DBD::DBM, it will treat the _metadata row as a header rather than as data and will pull the column names from there. However, if you access the file with something other than DBD::DBM, the row will be treated as a regular data row.

If you do not want the column names stored as a data row in the table you can set the dbm_store_metadata attribute to 0.

 my $dbh = DBI->connect('dbi:DBM:store_metadata=0');

or

 $dbh->{dbm_store_metadata} = 0;

or, for per-table setting

 $dbh->{dbm_tables}->{qux}->{store_metadata} = 0;

By default, DBD::DBM assumes that you have two columns named "k" and "v" (short for "key" and "value"). So if you have dbm_store_metadata set to 1 and you want to use alternate column names, you need to specify the column names like this:

 my $dbh = DBI->connect('dbi:DBM:store_metadata=0;cols=foo,bar');

or

 $dbh->{dbm_store_metadata} = 0;
 $dbh->{dbm_cols}           = 'foo,bar';

To set the column names on per-table basis, do this:

 $dbh->{dbm_tables}->{qux}->{store_metadata} = 0;
 $dbh->{dbm_tables}->{qux}->{cols}           = 'foo,bar';
 #
 # sets the column names only for table "qux"

If you have a file that was created by another DBM program or created with dbm_store_metadata set to zero and you want to convert it to using DBD::DBM's column name storage, just use one of the methods above to name the columns but *without* specifying dbm_store_metadata as zero. You only have to do that once - thereafter you can get by without setting either dbm_store_metadata or setting dbm_cols because the names will be stored in the file.

Statement handle ($sth) attributes and methods

Most statement handle attributes such as NAME, NUM_OF_FIELDS, etc. are available only after an execute. The same is true of $sth->rows which is available after the execute but does not require a fetch.

The $dbh->dbm_versions() method

The private method dbm_versions() presents a summary of what other modules are being used at any given time. DBD::DBM can work with or without many other modules - it can use either SQL::Statement or DBI::SQL::Nano as its SQL engine, it can be run with DBI or DBI::PurePerl, it can use many kinds of DBM modules, and many kinds of serializers when run with MLDBM. The dbm_versions() method reports on all of that and more.

  print $dbh->dbm_versions;               # displays global settings
  print $dbh->dbm_versions($table_name);  # displays per table settings

An important thing to note about this method is that when called with no arguments, it displays the *global* settings. If you over-ride these by setting per-table attributes, these will not be shown unless you specifiy a table name as an argument to the method call.

Storing Objects

If you are using MLDBM, you can use DBD::DBM to take advantage of its serializing abilities to serialize any Perl object that MLDBM can handle. To store objects in columns, you should (but don't absolutely need to) declare it as a column of type BLOB (the type is *currently* ignored by the SQL engine, but heh, it's good form).

You *must* use placeholders to insert or refer to the data.

GOTCHAS AND WARNINGS

Using the SQL DROP command will remove any file that has the name specified in the command with either '.pag' or '.dir' or your {dbm_ext} appended to it. So this be dangerous if you aren't sure what file it refers to:

 $dbh->do(qq{DROP TABLE "/path/to/any/file"});

Each DBM type has limitations. SDBM_File, for example, can only store values of less than 1,000 characters. *You* as the script author must ensure that you don't exceed those bounds. If you try to insert a value that is bigger than the DBM can store, the results will be unpredictable. See the documentation for whatever DBM you are using for details.

Different DBM implementations return records in different orders. That means that you can not depend on the order of records unless you use an ORDER BY statement. DBI::SQL::Nano does not currently support ORDER BY (though it may soon) so if you need ordering, you'll have to install SQL::Statement.

DBM data files are platform-specific. To move them from one platform to another, you'll need to do something along the lines of dumping your data to CSV on platform #1 and then dumping from CSV to DBM on platform #2. DBD::AnyData and DBD::CSV can help with that. There may also be DBM conversion tools for your platforms which would probably be quickest.

When using MLDBM, there is a very powerful serializer - it will allow you to store Perl code or objects in database columns. When these get de-serialized, they may be evaled - in other words MLDBM (or actually Data::Dumper when used by MLDBM) may take the values and try to execute them in Perl. Obviously, this can present dangers, so if you don't know what's in a file, be careful before you access it with MLDBM turned on!

See the entire section on Table locking and flock() for gotchas and warnings about the use of flock().

GETTING HELP, MAKING SUGGESTIONS, AND REPORTING BUGS

If you need help installing or using DBD::DBM, please write to the DBI users mailing list at dbi-users@perl.org or to the comp.lang.perl.modules newsgroup on usenet. I'm afraid I can't always answer these kinds of questions quickly and there are many on the mailing list or in the newsgroup who can.

If you have suggestions, ideas for improvements, or bugs to report, please write me directly at the email shown below.

When reporting bugs, please send the output of $dbh->dbm_versions($table) for a table that exhibits the bug and, if possible, as small a sample as you can make of the code that produces the bug. And of course, patches are welcome too :-).

ACKNOWLEDGEMENTS

Many, many thanks to Tim Bunce for prodding me to write this, and for copious, wise, and patient suggestions all along the way.

AUTHOR AND COPYRIGHT

This module is written and maintained by

Jeff Zucker < jzucker AT cpan.org >

Copyright (c) 2004 by Jeff Zucker, all rights reserved.

You may freely distribute and/or modify this module under the terms of either the GNU General Public License (GPL) or the Artistic License, as specified in the Perl README file.

SEE ALSO

the DBI manpage, the SQL::Statement manpage, the DBI::SQL::Nano manpage, the AnyDBM_File manpage, MLDBM


DBD::File - Base class for writing DBI drivers

    • Metadata
    • Driver private methods
  • KNOWN BUGS
  • AUTHOR AND COPYRIGHT
  • SEE ALSO

NAME

DBD::File - Base class for writing DBI drivers

SYNOPSIS

 This module is a base class for writing other DBDs.
 It is not intended to function as a DBD itself.
 If you want to access flatfiles, use DBD::AnyData, or DBD::CSV,
 (both of which are subclasses of DBD::File).

DESCRIPTION

The DBD::File module is not a true DBI driver, but an abstract base class for deriving concrete DBI drivers from it. The implication is, that these drivers work with plain files, for example CSV files or INI files. The module is based on the SQL::Statement module, a simple SQL engine.

See the DBI manpage for details on DBI, the SQL::Statement manpage for details on SQL::Statement and the DBD::CSV manpage or the DBD::IniFile manpage for example drivers.

Metadata

The following attributes are handled by DBI itself and not by DBD::File, thus they all work like expected:

    Active
    ActiveKids
    CachedKids
    CompatMode             (Not used)
    InactiveDestroy
    Kids
    PrintError
    RaiseError
    Warn                   (Not used)

The following DBI attributes are handled by DBD::File:

AutoCommit

Always on

ChopBlanks

Works

NUM_OF_FIELDS

Valid after $sth-execute>

NUM_OF_PARAMS

Valid after $sth-prepare>

NAME

Valid after $sth-execute>; undef for Non-Select statements.

NULLABLE

Not really working, always returns an array ref of one's, as DBD::CSV doesn't verify input data. Valid after $sth-execute>; undef for Non-Select statements.

These attributes and methods are not supported:

    bind_param_inout
    CursorName
    LongReadLen
    LongTruncOk

Additional to the DBI attributes, you can use the following dbh attribute:

f_dir

This attribute is used for setting the directory where CSV files are opened. Usually you set it in the dbh, it defaults to the current directory ("."). However, it is overwritable in the statement handles.

Driver private methods

data_sources

The data_sources method returns a list of subdirectories of the current directory in the form "DBI:CSV:f_dir=$dirname".

If you want to read the subdirectories of another directory, use

    my($drh) = DBI->install_driver("CSV");
    my(@list) = $drh->data_sources('f_dir' => '/usr/local/csv_data' );
list_tables

This method returns a list of file names inside $dbh->{'f_dir'}. Example:

    my($dbh) = DBI->connect("DBI:CSV:f_dir=/usr/local/csv_data");
    my(@list) = $dbh->func('list_tables');

Note that the list includes all files contained in the directory, even those that have non-valid table names, from the view of SQL.

KNOWN BUGS

  • The module is using flock() internally. However, this function is not available on all platforms. Using flock() is disabled on MacOS and Windows 95: There's no locking at all (perhaps not so important on MacOS and Windows 95, as there's a single user anyways).

AUTHOR AND COPYRIGHT

This module is currently maintained by

Jeff Zucker < jzucker @ cpan.org >

The original author is Jochen Wiedmann.

Copyright (C) 2004 by Jeff Zucker Copyright (C) 1998 by Jochen Wiedmann

All rights reserved.

You may freely distribute and/or modify this module under the terms of either the GNU General Public License (GPL) or the Artistic License, as specified in the Perl README file.

SEE ALSO

the DBI manpage, the Text::CSV_XS manpage, the SQL::Statement manpage


DBD::Gofer - A stateless-proxy driver for communicating with a remote DBI

    • Use Cases
    • Advantages
      • Connection Pooling and Throttling
      • Simple Scaling
      • Caching
      • Fewer Network Round-trips
      • Thin Clients / Unsupported Platforms
  • CONSTRAINTS
    • You can't change database handle attributes after connect()
    • You can't change statement handle attributes after prepare()
    • You can't use transactions
    • You can't call driver-private sth methods
  • GENERAL CAVEATS
    • Temporary tables, locks, and other per-connection persistent state
    • Driver-private Database Handle Attributes
    • Driver-private Statement Handle Attributes
    • Multiple Resultsets
    • Statement activity that also updates dbh attributes
    • Methods that report an error always return undef
    • Subclassing only applies to client-side
  • CAVEATS FOR SPECIFIC METHODS
    • last_insert_id
    • execute_for_fetch
  • TRANSPORTS
    • Bundled Transports
      • null
      • pipeone
      • stream
    • Other Transports
      • http
      • Gearman
  • CONNECTING
    • Using DBI_AUTOPROXY
  • CONFIGURING VIA POLICY
  • AUTHOR
  • LICENCE AND COPYRIGHT
  • ACKNOWLEDGEMENTS
  • SEE ALSO
  • Caveats for specific drivers
  • TODO

NAME

DBD::Gofer - A stateless-proxy driver for communicating with a remote DBI

SYNOPSIS

  use DBI;

  $original_dsn = "dbi:..."; # your original DBI Data Source Name

  $dbh = DBI->connect("dbi:Gofer:transport=$transport;...;dsn=$original_dsn",
                      $user, $passwd, \%attributes);

  ... use $dbh as if it was connected to $original_dsn ...

The transport=$transport part specifies the name of the module to use to transport the requests to the remote DBI. If $transport doesn't contain any double colons then it's prefixed with DBD::Gofer::Transport::.

The dsn=$original_dsn part must be the last element of the DSN because everything after dsn= is assumed to be the DSN that the remote DBI should use.

The ... represents attributes that influence the operation of the Gofer driver or transport. These are described below or in the documentation of the transport module being used.

DESCRIPTION

DBD::Gofer is a DBI database driver that forwards requests to another DBI driver, usually in a seperate process, often on a separate machine. It tries to be as transparent as possible so it appears that you are using the remote driver directly.

DBD::Gofer is very similar to DBD::Proxy. The major difference is that with DBD::Gofer no state is maintained on the remote end. That means every request contains all the information needed to create the required state. (So, for example, every request includes the DSN to connect to.) Each request can be sent to any available server. The server executes the request and returns a single response that includes all the data.

This is very similar to the way http works as a stateless protocol for the web. Each request from your web browser can be handled by a different web server process.

Use Cases

This may seem like pointless overhead but there are situations where this is a very good thing. Let's consider a specific case.

Imagine using DBD::Gofer with an http transport. Your application calls connect(), prepare("select * from table where foo=?"), bind_param(), and execute(). At this point DBD::Gofer builds a request containing all the information about the method calls. It then uses the httpd transport to send that request to an apache web server.

This 'dbi execute' web server executes the request (using DBI::Gofer::Execute and related modules) and builds a response that contains all the rows of data, if the statement returned any, along with all the attributes that describe the results, such as $sth->{NAME}. This response is sent back to DBD::Gofer which unpacks it and presents it to the application as if it had executed the statement itself.

Advantages

Okay, but you still don't see the point? Well let's consider what we've gained:

Connection Pooling and Throttling

The 'dbi execute' web server leverages all the functionality of web infrastructure in terms of load balancing, high-availability, firewalls, access management, proxying, caching.

At its most basic level you get a configurable pool of persistent database connections.

Simple Scaling

Got thousands of processes all trying to connect to the database? You can use DBD::Gofer to connect them to your smaller pool of 'dbi execute' web servers instead.

Caching

Not yet implemented, but the single request-response architecture lends itself to caching.

Fewer Network Round-trips

DBD::Gofer sends as few requests as possible (dependent on the policy being used).

Thin Clients / Unsupported Platforms

You no longer need drivers for your database on every system. DBD::Gofer is pure perl.

CONSTRAINTS

There are some natural constraints imposed by the DBD::Gofer 'stateless' approach. But not many:

You can't change database handle attributes after connect()

You can't change database handle attributes after you've connected. Use the connect() call to specify all the attribute settings you want.

This is because it's critical that when a request is complete the database handle is left in the same state it was when first connected.

An exception is made for attributes with names starting "private_": They can be set after connect() but the change is only applied locally.

You can't change statement handle attributes after prepare()

You can't change statment handle attributes after prepare.

An exception is made for attributes with names starting "private_": They can be set after prepare() but the change is only applied locally.

You can't use transactions

AutoCommit only. Transactions aren't supported.

(In theory transactions could be supported when using a transport that maintains a connection, like stream does. If you're interested in this please get in touch via dbi-dev@perl.org)

You can't call driver-private sth methods

But that's rarely needed anyway.

GENERAL CAVEATS

A few important things to keep in mind when using DBD::Gofer:

Temporary tables, locks, and other per-connection persistent state

You shouldn't expect any per-session state to persist between requests. This includes locks and temporary tables.

Because the server-side may execute your requests via a different database connections, you can't rely on any per-connection persistent state, such as temporary tables, being available from one request to the next.

This is an easy trap to fall into. A good way to check for this is to test your code with a Gofer policy package that sets the connect_method policy to 'connect' to force a new connection for each request. The pedantic policy does this.

Driver-private Database Handle Attributes

Some driver-private dbh attributes may not be available if the driver has not implemented the private_attribute_info() method (added in DBI 1.54).

Driver-private Statement Handle Attributes

Driver-private sth attributes can be set in the prepare() call. TODO

Some driver-private dbh attributes may not be available if the driver has not implemented the private_attribute_info() method (added in DBI 1.54).

Multiple Resultsets

Multiple resultsets are supported only if the driver supports the more_results() method (an exception is made for DBD::Sybase).

Statement activity that also updates dbh attributes

Some drivers may update one or more dbh attributes after performing activity on a child sth. For example, DBD::mysql provides $dbh->{mysql_insertid} in addition to $sth->{mysql_insertid}. Currently mysql_insertid is supported via a hack but a more general mechanism is needed for other drivers to use.

Methods that report an error always return undef

With DBD::Gofer, a method that sets an error always return an undef or empty list. That shouldn't be a problem in practice because the DBI doesn't define any methods that return meaningful values while also reporting an error.

Subclassing only applies to client-side

The RootClass and DbTypeSubclass attributes are not passed to the Gofer server.

CAVEATS FOR SPECIFIC METHODS

last_insert_id

To enable use of last_insert_id you need to indicate to DBD::Gofer that you'd like to use it. You do that my adding a go_last_insert_id_args attribute to the do() or prepare() method calls. For example:

    $dbh->do($sql, { go_last_insert_id_args => [...] });

or

    $sth = $dbh->prepare($sql, { go_last_insert_id_args => [...] });

The array reference should contains the args that you want passed to the last_insert_id() method.

execute_for_fetch

The array methods bind_param_array() and execute_array() are supported. When execute_array() is called the data is serialized and executed in a single round-trip to the Gofer server. This makes it very fast, but requires enough memory to store all the serialized data.

The execute_for_fetch() method currently isn't optimised, it uses the DBI fallback behaviour of executing each tuple individually. (It could be implemented as a wrapper for execute_array() - patches welcome.)

TRANSPORTS

DBD::Gofer doesn't concern itself with transporting requests and responses to and fro. For that it uses special Gofer transport modules.

Gofer transport modules usually come in pairs: one for the 'client' DBD::Gofer driver to use and one for the remote 'server' end. They have very similar names:

    DBD::Gofer::Transport::<foo>
    DBI::Gofer::Transport::<foo>

Sometimes the transports on the DBD and DBI sides may have different names. For example DBD::Gofer::Transport::http is typically used with DBI::Gofer::Transport::mod_perl (DBD::Gofer::Transport::http and DBI::Gofer::Transport::mod_perl modules are part of the GoferTransport-http distribution).

Bundled Transports

Several transport modules are provided with DBD::Gofer:

null

The null transport is the simplest of them all. It doesn't actually transport the request anywhere. It just serializes (freezes) the request into a string, then thaws it back into a data structure before passing it to DBI::Gofer::Execute to execute. The same freeze and thaw is applied to the results.

The null transport is the best way to test if your application will work with Gofer. Just set the DBI_AUTOPROXY environment variable to "dbi:Gofer:transport=null;policy=pedantic" (see Using DBI_AUTOPROXY below) and run your application, or ideally its test suite, as usual.

It doesn't take any parameters.

pipeone

The pipeone transport launches a subprocess for each request. It passes in the request and reads the response.

The fact that a new subprocess is started for each request ensures that the server side is truly stateless. While this does make the transport very slow, it is useful as a way to test that your application doesn't depend on per-connection state, such as temporary tables, persisting between requests.

It's also useful both as a proof of concept and as a base class for the stream driver.

stream

The stream driver also launches a subprocess and writes requests and reads responses, like the pipeone transport. In this case, however, the subprocess is expected to handle more that one request. (Though it will be automitically restarted if it exits.)

This is the first transport that is truly useful because it can launch the subprocess on a remote machine using ssh. This means you can now use DBD::Gofer to easily access any databases that's accessible from any system you can login to. You also get all the benefits of ssh, including encryption and optional compression.

See Using DBI_AUTOPROXY below for an example.

Other Transports

Implementing a Gofer transport is very simple, and more transports are very welcome. Just take a look at any existing transports that are similar to your needs.

http

See the GoferTransport-http distribution on CPAN.

Gearman

I know Ask Bjørn Hansen has implemented a transport for the gearman distributed job system, though it's not on CPAN at the time of writing this.

CONNECTING

Simply prefix your existing DSN with "dbi:Gofer:transport=$transport;dsn=" where $transport is the name of the Gofer transport you want to use (see TRANSPORTS). The transport and dsn attributes must be specified and the dsn attributes must be last.

Other attributes can be specified in the DSN to configure DBD::Gofer and/or the Gofer transport module being used. The main attributes after transport, are url and policy. These are described below.

Using DBI_AUTOPROXY

The simplest way to try out DBD::Gofer is to set the DBI_AUTOPROXY environment variable. In this case you don't include the dsn= part. For example:

    export DBI_AUTOPROXY="dbi:Gofer:transport=null"

or, for a more useful example, try:

    export DBI_AUTOPROXY="dbi:Gofer:transport=stream;url=ssh:user@example.com"

CONFIGURING VIA POLICY

DBD::Gofer supports a 'policy' mechanism that allows you to fine-tune the number of round-trips to the Gofer server. The policies are grouped into classes (which may be subclassed) and referenced by the name of the class.

The the DBD::Gofer::Policy::Base manpage class is the base class for all the policy packages and describes all the available policies.

Three policy packages are supplied with DBD::Gofer:

the DBD::Gofer::Policy::pedantic manpage is most 'transparent' but slowest because it makes more round-trips to the Gofer server.

the DBD::Gofer::Policy::classic manpage is a reasonable compromise - it's the default policy.

the DBD::Gofer::Policy::rush manpage is fastest, but may require code changes in your applications.

Generally the default classic policy is fine. When first testing an existing application with Gofer it is a good idea to start with the pedantic policy first and then switch to classic or a custom policy, for final testing.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

ACKNOWLEDGEMENTS

The development of DBD::Gofer and related modules was sponsored by Shopzilla.com (http://Shopzilla.com), where I currently work.

SEE ALSO

the DBI::Gofer::Request manpage, the DBI::Gofer::Response manpage, the DBI::Gofer::Execute manpage.

the DBI::Gofer::Transport::Base manpage, the DBD::Gofer::Policy::Base manpage.

the DBI manpage

Caveats for specific drivers

This section aims to record issues to be aware of when using Gofer with specific drivers. It usually only documents issues that are not natural consequences of the limitations of the Gofer approach - as documented avove.

TODO

This is just a random brain dump... (There's more in the source of the Changes file, not the pod)

Document policy mechanism

Add mechanism for transports to list config params and for Gofer to apply any that match (and warn if any left over?)

Driver-private sth attributes - set via prepare() - change DBI spec

add hooks into transport base class for checking & updating a result set cache ie via a standard cache interface such as: http://search.cpan.org/~robm/Cache-FastMmap/FastMmap.pm http://search.cpan.org/~bradfitz/Cache-Memcached/lib/Cache/Memcached.pm http://search.cpan.org/~dclinton/Cache-Cache/ http://search.cpan.org/~cleishman/Cache/ Also caching instructions could be passed through the httpd transport layer in such a way that appropriate http cache headers are added to the results so that web caches (squid etc) could be used to implement the caching. (MUST require the use of GET rather than POST requests.)

Rework handling of installed_methods to not piggback on dbh_attributes?

Perhaps support transactions for transports where it's possible (ie null and stream)? Would make stream transport (ie ssh) more useful to more people.

Make sth_result_attr more like dbh_attributes (using '*' etc)

Add @val = FETCH_many(@names) to DBI in C and use in Gofer/Execute?

Implement _new_sth in C.


DBD::Gofer::Policy::Base - Base class for DBD::Gofer policies

  • POLICY CLASSES
  • POLICY ITEMS
  • POLICY CUSTOMIZATION
  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBD::Gofer::Policy::Base - Base class for DBD::Gofer policies

SYNOPSIS

  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=...", ...)

DESCRIPTION

DBD::Gofer can be configured via a 'policy' mechanism that allows you to fine-tune the number of round-trips to the Gofer server. The policies are grouped into classes (which may be subclassed) and referenced by the name of the class.

The the DBD::Gofer::Policy::Base manpage class is the base class for all the policy classes and describes all the individual policy items.

The Base policy is not used directly. You should use a policy class derived from it.

POLICY CLASSES

Three policy classes are supplied with DBD::Gofer:

L<DBD::Gofer::Policy::pedantic> is most 'transparent' but slowest because it
makes more  round-trips to the Gofer server.

the DBD::Gofer::Policy::classic manpage is a reasonable compromise - it's the default policy.

L<DBD::Gofer::Policy::rush> is fastest, but may require code changes in your applications.

Generally the default classic policy is fine. When first testing an existing application with Gofer it is a good idea to start with the pedantic policy first and then switch to classic or a custom policy, for final testing.

POLICY ITEMS

These are temporary docs: See the source code for list of policies and their defaults.

In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.

See the source code to this module for more details.

POLICY CUSTOMIZATION

XXX This area of DBD::Gofer is subject to change.

There are three ways to customize policies:

Policy classes are designed to influence the overall behaviour of DBD::Gofer with existing, unaltered programs, so they work in a reasonably optimal way without requiring code changes. You can implement new policy classes as subclasses of existing policies.

In many cases individual policy items can be overridden on a case-by-case basis within your application code. You do this by passing a corresponding <go_<policy_name>> attribute into DBI methods by your application code. This let's you fine-tune the behaviour for special cases.

The policy items are implemented as methods. In many cases the methods are passed parameters relating to the DBD::Gofer code being executed. This means the policy can implement dynamic behaviour that varies depending on the particular circumstances, such as the particular statement being executed.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBD::Gofer::Policy::classic - The 'classic' policy for DBD::Gofer

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBD::Gofer::Policy::classic - The 'classic' policy for DBD::Gofer

SYNOPSIS

  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=classic", ...)

The classic policy is the default DBD::Gofer policy, so need not be included in the DSN.

DESCRIPTION

Temporary docs: See the source code for list of policies and their defaults.

In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBD::Gofer::Policy::pedantic - The 'pedantic' policy for DBD::Gofer

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBD::Gofer::Policy::pedantic - The 'pedantic' policy for DBD::Gofer

SYNOPSIS

  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=pedantic", ...)

DESCRIPTION

The pedantic policy tries to be as transparent as possible. To do this it makes round-trips to the server for almost every DBI method call.

This is the best policy to use when first testing existing code with Gofer. Once it's working well you should consider moving to the classic policy or defining your own policy class.

Temporary docs: See the source code for list of policies and their defaults.

In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBD::Gofer::Policy::rush - The 'rush' policy for DBD::Gofer

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBD::Gofer::Policy::rush - The 'rush' policy for DBD::Gofer

SYNOPSIS

  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=rush", ...)

DESCRIPTION

The rush policy tries to make as few round-trips as possible. It's the opposite end of the policy spectrum to the pedantic policy.

Temporary docs: See the source code for list of policies and their defaults.

In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBD::Gofer::Transport::Base - base class for DBD::Gofer client transports

  • ATTRIBUTES
    • go_dsn
    • go_timeout
    • go_retry_limit
    • go_retry_hook
  • RETRY ON ERROR
  • TRACING
  • AUTHOR
  • LICENCE AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Gofer::Transport::Base - base class for DBD::Gofer client transports

SYNOPSIS

  my $remote_dsn = "..."
  DBI->connect("dbi:Gofer:transport=...;url=...;timeout=...;retry_limit=...;dsn=$remote_dsn",...)

or, enable by setting the DBI_AUTOPROXY environment variable:

  export DBI_AUTOPROXY='dbi:Gofer:transport=...;url=...'

which will force all DBI connections to be made via that Gofer server.

DESCRIPTION

This is the base class for all DBD::Gofer client transports.

ATTRIBUTES

Gofer transport attributes can be specified either in the attributes parameter of the connect() method call, or in the DSN string. When used in the DSN string, attribute names don't have the go_ prefix.

go_dsn

The full DBI DSN that the Gofer server should connect to on your behalf.

When used in the DSN it must be the last element in the DSN string.

go_timeout

A time limit for sending a request and receiving a response. Some drivers may implement sending and receiving as separate steps, in which case (currently) the timeout applies to each separately.

If a request needs to be resent then the timeout is restarted for each sending of a request and receiving of a response.

go_retry_limit

The maximum number of times an request may be retried. The default is 2.

go_retry_hook

This subroutine reference is called, if defined, for each response received where $response->err is true.

The subroutine is pass three parameters: the request object, the response object, and the transport object.

If it returns an undefined value then the default retry behaviour is used. See RETRY ON ERROR below.

If it returns a defined but false value then the request is not resent.

If it returns true value then the request is resent, so long as the number of retries does not exceed go_retry_limit.

RETRY ON ERROR

The default retry on error behaviour is:

 - Retry if the error was due to DBI_GOFER_RANDOM. See L<DBI::Gofer::Execute>.
 - Retry if $request->is_idempotent returns true. See L<DBI::Gofer::Request>.

A retry won't be allowed if the number of previous retries has reached go_retry_limit.

TRACING

Tracing of gofer requests and reponses can be enabled by setting the DBD_GOFER_TRACE environment variable. A value of 1 gives a reasonably compact summary of each request and response. A value of 2 or more gives a detailed, and voluminous, dump.

The trace is written using DBI->trace_msg() and so is written to the default DBI trace output, which is usually STDERR.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

SEE ALSO

the DBD::Gofer manpage, the DBI::Gofer::Request manpage, the DBI::Gofer::Response manpage, the DBI::Gofer::Execute manpage.

and some example transports:

the DBD::Gofer::Transport::stream manpage

the DBD::Gofer::Transport::http manpage

the DBI::Gofer::Transport::mod_perl manpage


DBD::Gofer::Transport::null - DBD::Gofer client transport for testing

  • AUTHOR
  • LICENCE AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Gofer::Transport::null - DBD::Gofer client transport for testing

SYNOPSIS

  my $original_dsn = "..."
  DBI->connect("dbi:Gofer:transport=null;dsn=$original_dsn",...)

or, enable by setting the DBI_AUTOPROXY environment variable:

  export DBI_AUTOPROXY="dbi:Gofer:transport=null"

DESCRIPTION

Connect via DBD::Gofer but execute the requests within the same process.

This is a quick and simple way to test applications for compatibility with the (few) restrictions that DBD::Gofer imposes.

It also provides a simple, portable way for the DBI test suite to be used to test DBD::Gofer on all platforms with no setup.

Also, by measuring the difference in performance between normal connections and connections via dbi:Gofer:transport=null the basic cost of using DBD::Gofer can be measured. Furthermore, the additional cost of more advanced transports can be isolated by comparing their performance with the null transport.

The t/85gofer.t script in the DBI distribution includes a comparative benchmark.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

SEE ALSO

the DBD::Gofer::Transport::Base manpage

the DBD::Gofer manpage


DBD::Gofer::Transport::pipeone - DBD::Gofer client transport for testing

  • AUTHOR
  • LICENCE AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Gofer::Transport::pipeone - DBD::Gofer client transport for testing

SYNOPSIS

  $original_dsn = "...";
  DBI->connect("dbi:Gofer:transport=pipeone;dsn=$original_dsn",...)

or, enable by setting the DBI_AUTOPROXY environment variable:

  export DBI_AUTOPROXY="dbi:Gofer:transport=pipeone"

DESCRIPTION

Connect via DBD::Gofer and execute each request by starting executing a subprocess.

This is, as you might imagine, spectacularly inefficient!

It's only intended for testing. Specifically it demonstrates that the server side is completely stateless.

It also provides a base class for the much more useful the DBD::Gofer::Transport::stream manpage transport.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

SEE ALSO

the DBD::Gofer::Transport::Base manpage

the DBD::Gofer manpage


DBD::Gofer::Transport::stream - DBD::Gofer transport for stdio streaming

  • PERSISTENCE
  • TO DO
  • AUTHOR
  • LICENCE AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Gofer::Transport::stream - DBD::Gofer transport for stdio streaming

SYNOPSIS

  DBI->connect('dbi:Gofer:transport=stream;url=ssh:username@host.example.com;dsn=dbi:...',...)

or, enable by setting the DBI_AUTOPROXY environment variable:

  export DBI_AUTOPROXY='dbi:Gofer:transport=stream;url=ssh:username@host.example.com'

DESCRIPTION

Without the url= parameter it launches a subprocess as

  perl -MDBI::Gofer::Transport::stream -e run_stdio_hex

and feeds requests into it and reads responses from it. But that's not very useful.

With a url=ssh:username@host.example.com parameter it uses ssh to launch the subprocess on a remote system. That's much more useful!

It gives you secure remote access to DBI databases on any system you can login to. Using ssh also gives you optional compression and many other features (see the ssh manual for how to configure that and many other options via ~/.ssh/config file).

The actual command invoked is something like:

  ssh -xq ssh:username@host.example.com bash -c $setup $run

where $run is the command shown above, and $command is

  . .bash_profile 2>/dev/null || . .bash_login 2>/dev/null || . .profile 2>/dev/null; exec "$@"

which is trying (in a limited and fairly unportable way) to setup the environment (PATH, PERL5LIB etc) as it would be if you had logged in to that system.

The "perl" used in the command will default to the value of $^X when not using ssh. On most systems that's the full path to the perl that's currently executing.

PERSISTENCE

Currently gofer stream connections persist (remain connected) after all database handles have been disconnected. This makes later connections in the same process very fast.

Currently up to 5 different gofer stream connections (based on url) can persist. If more than 5 are in the cache when a new connection is made then the cache is cleared before adding the new connection. Simple but effective.

TO DO

Document go_perl attribute

Automatically reconnect (within reason) if there's a transport error.

Decide on default for persistent connection - on or off? limits? ttl?

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

SEE ALSO

the DBD::Gofer::Transport::Base manpage

the DBD::Gofer manpage


DBD::Oracle - Oracle database driver for the DBI module

  • CONNECTING TO ORACLE
    • Connecting without environment variables or tnsname.ora file
    • Oracle Environment Variables
    • Connection Examples Using DBD::Oracle
    • Optimizing Oracle's listener
    • Oracle utilities
    • Constants
    • Connect Attributes
    • Database Handle Attributes
    • Prepare Attributes
    • Placeholder Binding Attributes
    • Trailing Spaces
  • Metadata
    • get_info()
    • table_info()
    • primary_key_info()
    • foreign_key_info()
    • column_info()
  • Unicode
    • Perl and Unicode
    • Oracle and Unicode
    • Oracle UTF8 is not UTF-8
    • DBD::Oracle and Unicode
    • DBD::Oracle and Other Character Sets and Encodings
  • Other Data Types
  • PL/SQL Examples
  • Private database handle functions
    • plsql_errstr
    • dbms_output_enable / dbms_output_put / dbms_output_get
  • Prepare postponed till execute
  • Handling LOBs
    • Simple Usage
    • LOB Locator Methods
    • LOB Locator Method Examples
    • Example: Inserting a new row with large data
    • Example: Updating an existing row with large data
    • Example: Streaming character data from the database
    • Example: Truncating existing large data
  • Binding Cursors
  • Fetching Nested Cursors
    • Pre-fetching Nested Cursors
  • Returning A Value from an INSERT
  • Returning A Recordset
  • Timezones
  • Oracle Related Links
    • Oracle on Linux
    • Free Oracle Tools and Links
    • Commercial Oracle Tools and Links
  • SEE ALSO
  • AUTHOR
  • ACKNOWLEDGEMENTS
  • MAINTAINER
  • COPYRIGHT
  • CONTRIBUTING
    • How to create a patch using Subversion
    • How to create a patch without Subversion
    • Speak before you patch

NAME

DBD::Oracle - Oracle database driver for the DBI module

SYNOPSIS

  use DBI;

  $dbh = DBI->connect("dbi:Oracle:$dbname", $user, $passwd);

  $dbh = DBI->connect("dbi:Oracle:host=$host;sid=$sid", $user, $passwd);

  # See the DBI module documentation for full details

  # for some advanced uses you may need Oracle type values:
  use DBD::Oracle qw(:ora_types);

DESCRIPTION

DBD::Oracle is a Perl module which works with the DBI module to provide access to Oracle databases.

CONNECTING TO ORACLE

This is a topic which often causes problems. Mainly due to Oracle's many and sometimes complex ways of specifying and connecting to databases. (James Taylor and Lane Sharman have contributed much of the text in this section.)

Connecting without environment variables or tnsname.ora file

If you use the host=$host;sid=$sid style syntax, for example:

  $dbh = DBI->connect("dbi:Oracle:host=myhost.com;sid=ORCL", $user, $passwd);

then DBD::Oracle will construct a full connection descriptor string for you and Oracle will not need to consult the tnsname.ora file.

If a port number is not specified then the descriptor will try both 1526 and 1521 in that order (e.g., new then old). You can check which port(s) are in use by typing "$ORACLE_HOME/bin/lsnrctl stat" on the server.

Oracle Environment Variables

Oracle typically uses two environment variables to specify default connections: ORACLE_SID and TWO_TASK.

ORACLE_SID is really unnecessary to set since TWO_TASK provides the same functionality in addition to allowing remote connections.

  % setenv TWO_TASK T:hostname:ORACLE_SID            # for csh shell
  $ TWO_TASK=T:hostname:ORACLE_SID export TWO_TASK   # for sh shell
  % sqlplus username/password

Note that if you have *both* local and remote databases, and you have ORACLE_SID *and* TWO_TASK set, and you don't specify a fully qualified connect string on the command line, TWO_TASK takes precedence over ORACLE_SID (i.e. you get connected to remote system).

  TWO_TASK=P:sid

will use the pipe driver for local connections using SQL*Net v1.

  TWO_TASK=T:machine:sid

will use TCP/IP (or D for DECNET, etc.) for remote SQL*Net v1 connection.

  TWO_TASK=dbname

will use the info stored in the SQL*Net v2 tnsnames.ora configuration file for local or remote connections.

The ORACLE_HOME environment variable should be set correctly. In general, the value used should match the version of Oracle that was used to build DBD::Oracle. If using dynamic linking then ORACLE_HOME should match the version of Oracle that will be used to load in the Oracle client libraries (via LD_LIBRARY_PATH, ldconfig, or similar on Unix).

ORACLE_HOME can be left unset if you aren't using any of Oracle's executables, but it is not recommended and error messages may not display. It should be set to the ORACLE_HOME directory of the version of Oracle that DBD::Oracle was compiled with.

Discouraging the use of ORACLE_SID makes it easier on the users to see what is going on. (It's unfortunate that TWO_TASK couldn't be renamed, since it makes no sense to the end user, and doesn't have the ORACLE prefix).

Connection Examples Using DBD::Oracle

First, how to connect to a local database without using a Listener:

  $dbh = DBI->connect('dbi:Oracle:SID','scott', 'tiger');

you can also leave the SID empty:

  $dbh = DBI->connect('dbi:Oracle:','scott', 'tiger');

in which case Oracle client code will use the ORACLE_SID environment variable (if TWO_TASK env var isn't defined).

Below are various ways of connecting to an oracle database using SQL*Net 1.x and SQL*Net 2.x. "Machine" is the computer the database is running on, "SID" is the SID of the database, "DB" is the SQL*Net 2.x connection descriptor for the database.

Note: Some of these formats may not work with Oracle 8+.

  BEGIN {
     $ENV{ORACLE_HOME} = '/home/oracle/product/7.x.x';
     $ENV{TWO_TASK}    = 'DB';
  }
  $dbh = DBI->connect('dbi:Oracle:','scott', 'tiger');
  #  - or -
  $dbh = DBI->connect('dbi:Oracle:','scott/tiger');

Refer to your Oracle documentatiion for valid values of TWO_TASK.

Here are some variations (not setting TWO_TASK) in order of preference:

  $dbh = DBI->connect('dbi:Oracle:DB','username','password')
  $dbh = DBI->connect('dbi:Oracle:DB','username/password','')
  $dbh = DBI->connect('dbi:Oracle:','username@DB','password')
  $dbh = DBI->connect('dbi:Oracle:host=foobar;sid=ORCL;port=1521', 'scott/tiger', '')

  $dbh = DBI->connect('dbi:Oracle:', q{scott/tiger@(DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCP)(HOST= foobar)(PORT=1521))
  (CONNECT_DATA=(SID=ORCL)))}, "")

If you are having problems with login taking a long time (>10 secs say) then you might have tripped up on an Oracle bug. You can try using one of the ...@DB variants as a workaround. E.g.,

  $dbh = DBI->connect('','username/password@DB','');

On the other hand, that may cause you to trip up on another Oracle bug that causes alternating connection attempts to fail! (In reality only a small proportion of people experience these problems.)

To connect to a local database with a user which has been set-up to authenticate via the OS ("ALTER USER username IDENTIFIED EXTERNALLY"):

  $dbh = DBI->connect('dbi:Oracle:','/','');

Note the lack of a connection name (use the ORACLE_SID environment variable). If an explicit SID is used you'll probably get an ORA-01004 error.

That only works for local databases. (Authentication to remote Oracle databases using your unix login name without a password and is possible but it's not secure and not recommended so not documented here. If you can't find the information elsewhere then you probably shouldn't be trying to do it.)

Optimizing Oracle's listener

[By Lane Sharman <lane@bienlogic.com>] I spent a LOT of time optimizing listener.ora and I am including it here for anyone to benefit from. My connections over tnslistener on the same humble Netra 1 take an average of 10-20 milli seconds according to tnsping. If anyone knows how to make it better, please let me know!

 LISTENER =
  (ADDRESS_LIST =
    (ADDRESS =
      (PROTOCOL = TCP)
      (Host = aa.bbb.cc.d)
      (Port = 1521)
      (QUEUESIZE=10)
    )
  )
 STARTUP_WAIT_TIME_LISTENER = 0
 CONNECT_TIMEOUT_LISTENER = 10
 TRACE_LEVEL_LISTENER = OFF
 SID_LIST_LISTENER =
  (SID_LIST =
    (SID_DESC =
      (SID_NAME = xxxx)
      (ORACLE_HOME = /xxx/local/oracle7-3)
        (PRESPAWN_MAX = 40)
        (PRESPAWN_LIST=
        (PRESPAWN_DESC=(PROTOCOL=tcp) (POOL_SIZE=40) (TIMEOUT=120))
      )
    )
  )

1) When the application is co-located on the host AND there is no need for outside SQLNet connectivity, stop the listener. You do not need it. Get your application/cgi/whatever working using pipes and shared memory. I am convinced that this is one of the connection bugs (sockets over the same machine). Note the $ENV{ORAPIPES} env var. The essential code to do this at the end of this section.

2) Be careful in how you implement the multi-threaded server. Currently I am not using it in the initxxxx.ora file but will be doing some more testing.

3) Be sure to create user rollback segments and use them; do not use the system rollback segments; however, you must also create a small rollback space for the system as well.

5) Use large tuning settings and get lots of RAM. Check out all the parameters you can set in v$parameters because there are quite a few not documented you may to set in your initxxx.ora file.

6) Use svrmgrl to control oracle from the command line. Write lots of small SQL scripts to get at V$ info.

  use DBI;
  # Environmental variables used by Oracle
  $ENV{ORACLE_SID}   = "xxx";
  $ENV{ORACLE_HOME}  = "/opt/oracle7";
  $ENV{EPC_DISABLED} = "TRUE";
  $ENV{ORAPIPES} = "V2";
  my $dbname = "xxx";
  my $dbuser = "xxx";
  my $dbpass = "xxx";
  my $dbh = DBI->connect("dbi:Oracle:$dbname", $dbuser, $dbpass)
             || die "Unale to connect to $dbname: $DBI::errstr\n";

Oracle utilities

If you are still having problems connecting then the Oracle adapters utility may offer some help. Run these two commands:

  $ORACLE_HOME/bin/adapters
  $ORACLE_HOME/bin/adapters $ORACLE_HOME/bin/sqlplus

and check the output. The "Protocol Adapters" section should be the same. It should include at least "IPC Protocol Adapter" and "TCP/IP Protocol Adapter".

If it generates any errors which look relevant then please talk to yor Oracle technical support (and not the dbi-users mailing list). Thanks. Thanks to Mark Dedlow for this information.

Constants

:ora_session_modes
  ORA_SYSDBA ORA_SYSOPER
:ora_types
  ORA_VARCHAR2 ORA_STRING ORA_NUMBER ORA_LONG ORA_ROWID ORA_DATE
  ORA_RAW ORA_LONGRAW ORA_CHAR ORA_CHARZ ORA_MLSLABEL ORA_NTY
  ORA_CLOB ORA_BLOB ORA_RSET
SQLCS_IMPLICIT
SQLCS_NCHAR

SQLCS_IMPLICIT and SQLCS_NCHAR are character set form values. See notes about Unicode elsewhere in this document.

ORA_OCI

Oracle doesn't provide a formal API for determining the exact version number of the OCI client library used, so DBD::Oracle has to go digging (and sometimes has to more or less guess). The ORA_OCI constant holds the result of that process.

In string context ORA_OCI returns the full "A.B.C.D" version string.

In numeric context ORA_OCI returns the major.minor version number (8.1, 9.2, 10.0 etc). But note that version numbers are not actually floating point and so if Oracle ever makes a release that has a two digit minor version, such as 9.10 it will have a lower numeric value than the preceeding 9.9 release. So use with care.

The contents and format of ORA_OCI are subject to change (it may, for example, become a version object in later releases). I recommend that you avoid checking for exact values.

Connect Attributes

ora_session_mode

The ora_session_mode attribute can be used to connect with SYSDBA authorization and SYSOPER authorization. The ORA_SYSDBA and ORA_SYSOPER constants can be imported using

  use DBD::Oracle qw(:ora_session_modes);

This is one case where setting ORACLE_SID may be useful since connecting as SYSDBA or SYSOPER via SQL*Net is frequently disabled for security reasons.

Example:

  $dsn = "dbi:Oracle:";       # no dbname here
  $ENV{ORACLE_SID} = "orcl";  # set ORACLE_SID as needed
  delete $ENV{TWO_TASK};      # make sure TWO_TASK isn't set

  $dbh = DBI->connect($dsn, "", "", { ora_session_mode => ORA_SYSDBA });

It has been reported that this only works if $dsn does not contain a SID so that Oracle then uses the value of the ORACLE_SID (not TWO_TASK) environment variable to connect to a local instance. Also the username and password should be empty, and the user executing the script needs to be part of the dba group or osdba group.

ora_oratab_orahome

Passing a true value for the ora_oratab_orahome attribute will make DBD::Oracle change $ENV{ORACLE_HOME} to make the Oracle home directory specified in the /etc/oratab file if the database to connect to is specified as a SID that exists in the oratab file, and DBD::Oracle was built to use the Oracle 7 OCI API (not Oracle 8+).

ora_module_name

After connecting to the database the value of this attribute is passed to the SET_MODULE() function in the DBMS_APPLICATION_INFO PL/SQL package. This can be used to identify the application to the DBA for monitoring and performance tuning purposes. For example:

  DBI->connect($dsn, $user, $passwd, { ora_module_name => $0 });
ora_dbh_share

Needs at least Perl 5.8.0 compiled with ithreads. Allows to share database connections between threads. The first connect will make the connection, all following calls to connect with the same ora_dbh_share attribute will use the same database connection. The value must be a reference to a already shared scalar which is initialized to an empty string.

  our $orashr : shared = '' ;

  $dbh = DBI->connect ($dsn, $user, $passwd, {ora_dbh_share => \$orashr}) ;
ora_use_proc_connection

This attribute allows to create a DBI handle for an existing SQLLIB database connection. This can be used to share database connections between Oracle ProC code and DBI running in an embedded Perl interpreter. The SQLLIB connection id is appended after the "dbi:Oracle:" initial argument to DBI::connect.

For example, if in ProC a connection is made like

    EXEC SQL CONNECT 'user/pass@db' AT 'CONID';

the connection may be used from DBI after running something like

    my $dbh = DBI->connect("dbi:Oracle:CONID", "", "",
                           { ora_use_proc_connection => 1 });

To disconnect, first call $dbh->disconnect(), then disconnect in ProC.

This attribute requires DBD::Oracle to be built with the -ProC option to Makefile.PL. It is not available with OCI_V7. Not tested with Perl ithreads or with the ora_dbh_share connect attribute.

ora_envhp

The first time a connection is made a new OCI 'environment' is created by DBD::Oracle and stored in the driver handle. Subsequent connects reuse (share) that same OCI environment by default.

The ora_envhp attribute can be used to disable the reuse of the OCI environment from a previous connect. If the value is 0 then a new OCI environment is allocated and used for this connection.

The OCI environment is what holds information about the client side context, such as the local NLS environment. So by altering %ENV and setting ora_envhp to 0 you can create connections with different NLS settings. This is most useful for testing.

Database Handle Attributes

ora_ph_type

The default placeholder data type for the database session. The TYPE or ora_type attributes to bind_param in the DBI manpage and bind_param_inout in the DBI manpage override the data type for individual placeholders. The most frequent reason for using this attribute is to permit trailing spaces in values passed by placeholders.

Constants for the values allowed for this attribute can be imported using

  use DBD::Oracle qw(:ora_types);

Only the following values are permitted for this attribute.

ORA_VARCHAR2

Strip trailing spaces and allow embedded \0 bytes. This is the normal default placeholder type.

ORA_STRING

Don't strip trailing spaces and end the string at the first \0.

ORA_CHAR

Don't strip trailing spaces and allow embedded \0. Force 'blank-padded comparison semantics'.

ora_parse_error_offset

If the previous error was from a failed prepare due to a syntax error, this attribute gives the offset into the Statement attribute where the error was found.

Prepare Attributes

These attributes may be used in the \%attr parameter of the prepare in the DBI manpage database handle method.

ora_placeholders

Set to false to disable processing of placeholders. Used mainly for loading a PL/SQL package that has been wrapped with Oracle's wrap utility.

ora_parse_lang

Tells the connected database how to interpret the SQL statement. If 1 (default), the native SQL version for the database is used. Other recognized values are 0 (old V6, treated as V7 in OCI8), 2 (old V7), 7 (V7), and 8 (V8). All other values have the same effect as 1.

ora_auto_lob

If true (the default), fetching retreives the contents of the CLOB or BLOB column in most circumstances. If false, fetching retreives the Oracle "LOB Locator" of the CLOB or BLOB value.

See Handling LOBs for more details. See also the LOB tests in 05dbi.t of Oracle::OCI for examples of how to use LOB Locators.

ora_check_sql

If 1 (default), force SELECT statements to be described in prepare(). If 0, allow SELECT statements to defer describe until execute().

See Prepare postponed till execute for more information.

Placeholder Binding Attributes

These attributes may be used in the \%attr parameter of the bind_param in the DBI manpage or bind_param_inout in the DBI manpage statement handle methods.

ora_type

Specify the placeholder's data type using an Oracle data type. A fatal error is raised if ora_type and the DBI TYPE attribute are used for the same placeholder. Some of these types are not supported by the current version of DBD::Oracle and will cause a fatal error if used. Constants for the Oracle datatypes may be imported using

  use DBD::Oracle qw(:ora_types);

Potentially useful values when DBD::Oracle was built using OCI 7 and later:

  ORA_VARCHAR2, ORA_STRING, ORA_LONG, ORA_RAW, ORA_LONGRAW,
  ORA_CHAR, ORA_MLSLABEL, ORA_RSET

Additional values when DBD::Oracle was built using OCI 8 and later:

  ORA_CLOB, ORA_BLOB, ORA_NTY

See Binding Cursors for the correct way to use ORA_RSET.

See Handling LOBs for how to use ORA_CLOB and ORA_BLOB.

See Other Data Types for more information.

See also Placeholders and Bind Values in the DBI manpage.

ora_csform

Specify the OCI_ATTR_CHARSET_FORM for the bind value. Valid values are SQLCS_IMPLICIT (1) and SQLCS_NCHAR (2). Both those constants can be imported from the DBD::Oracle module. Rarely needed.

ora_csid

Specify the integer OCI_ATTR_CHARSET_ID for the bind value. Character set names can't be used currently.

ora_maxdata_size

Specify the integer OCI_ATTR_MAXDATA_SIZE for the bind value. May be needed if a character set conversion from client to server causes the data to use more space and so fail with a truncation error.

Trailing Spaces

The Oracle strips trailing spaces from VARCHAR placeholder values and uses Nonpadded Comparison Semantics with the result. This causes trouble if the spaces are needed for comparison with a CHAR value or to prevent the value from becoming '' which Oracle treats as NULL. Look for Blank-padded Comparison Semantics and Nonpadded Comparison Semantics in Oracle's SQL Reference or Server SQL Reference for more details.

Please remember that using spaces as a value or at the end of a value makes visually distinguishing values with different numbers of spaces difficult and should be avoided.

To preserve trailing spaces in placeholder values, either change the default placeholder type with ora_ph_type or the placeholder type for a particular call to bind in the DBI manpage or bind_param_inout in the DBI manpage with ora_type or TYPE. Using ORA_CHAR with ora_type or SQL_CHAR with TYPE allows the placeholder to be used with Padded Comparison Semantics if the value it is being compared to is a CHAR, NCHAR, or literal.

Metadata

get_info()

DBD::Oracle supports get_info(), but (currently) only a few info types.

table_info()

DBD::Oracle supports attributes for table_info().

In Oracle, the concept of user and schema is (currently) the same. Because database objects are owned by an user, the owner names in the data dictionary views correspond to schema names. Oracle does not support catalogs so TABLE_CAT is ignored as selection criterion.

Search patterns are supported for TABLE_SCHEM and TABLE_NAME.

TABLE_TYPE may contain a comma-separated list of table types. The following table types are supported:

  TABLE
  VIEW
  SYNONYM
  SEQUENCE

The result set is ordered by TABLE_TYPE, TABLE_SCHEM, TABLE_NAME.

The special enumerations of catalogs, schemas and table types are supported. However, TABLE_CAT is always NULL.

An identifier is passed as is, i.e. as the user provides or Oracle returns it. table_info() performs a case-sensitive search. So, a selection criterion should respect upper and lower case. Normally, an identifier is case-insensitive. Oracle stores and returns it in upper case. Sometimes, database objects are created with quoted identifiers (for reserved words, mixed case, special characters, ...). Such an identifier is case-sensitive (if not all upper case). Oracle stores and returns it as given. table_info() has no special quote handling, neither adds nor removes quotes.

primary_key_info()

Oracle does not support catalogs so TABLE_CAT is ignored as selection criterion. The TABLE_CAT field of a fetched row is always NULL (undef). See table_info() for more detailed information.

If the primary key constraint was created without an identifier, PK_NAME contains a system generated name with the form SYS_Cn.

The result set is ordered by TABLE_SCHEM, TABLE_NAME, KEY_SEQ.

An identifier is passed as is, i.e. as the user provides or Oracle returns it. See table_info() for more detailed information.

foreign_key_info()

This method (currently) supports the extended behavior of SQL/CLI, i.e. the result set contains foreign keys that refer to primary and alternate keys. The field UNIQUE_OR_PRIMARY distinguishes these keys.

Oracle does not support catalogs, so $pk_catalog and $fk_catalog are ignored as selection criteria (in the new style interface). The UK_TABLE_CAT and FK_TABLE_CAT fields of a fetched row are always NULL (undef). See table_info() for more detailed information.

If the primary or foreign key constraints were created without an identifier, UK_NAME or FK_NAME contains a system generated name with the form SYS_Cn.

The UPDATE_RULE field is always 3 ('NO ACTION'), because Oracle (currently) does not support other actions.

The DELETE_RULE field may contain wrong values. This is a known Bug (#1271663) in Oracle's data dictionary views. Currently (as of 8.1.7), 'RESTRICT' and 'SET DEFAULT' are not supported, 'CASCADE' is mapped correctly and all other actions (incl. 'SET NULL') appear as 'NO ACTION'.

The DEFERABILITY field is always NULL, because this columns is not present in the ALL_CONSTRAINTS view of older Oracle releases.

The result set is ordered by UK_TABLE_SCHEM, UK_TABLE_NAME, FK_TABLE_SCHEM, FK_TABLE_NAME, ORDINAL_POSITION.

An identifier is passed as is, i.e. as the user provides or Oracle returns it. See table_info() for more detailed information.

column_info()

Oracle does not support catalogs so TABLE_CAT is ignored as selection criterion. The TABLE_CAT field of a fetched row is always NULL (undef). See table_info() for more detailed information.

The CHAR_OCTET_LENGTH field is (currently) always NULL (undef).

Don't rely on the values of the BUFFER_LENGTH field! Especially the length of FLOATs may be wrong.

Datatype codes for non-standard types are subject to change.

Attention! The DATA_DEFAULT (COLUMN_DEF) column is of type LONG.

The result set is ordered by TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION.

An identifier is passed as is, i.e. as the user provides or Oracle returns it. See table_info() for more detailed information.

Unicode

DBD::Oracle now supports Unicode UTF-8. There are, however, a number of issues you should be aware of, so please read all this section carefully.

In this section we'll discuss "Perl and Unicode", then "Oracle and Unicode", and finally "DBD::Oracle and Unicode".

Information about Unicode in general can be found at: http://www.unicode.org/. It is well worth reading because there are many misconceptions about Unicode and you may be holding some of them.

Perl and Unicode

Perl began implementing Unicode with version 5.6, but the implementaion did not mature until version 5.8 and later. If you plan to use Unicode you are strongly urged to use perl 5.8.2 or later and to carefully read the perl documention on Unicode:

   perldoc perluniintro    # in perl 5.8 or later
   perldoc perlunicode

And then read it again.

Perl's internal unicode format is UTF-8 which corresponds to the Oracle character set called AL32UTF8.

Oracle and Unicode

Oracle supports many characters sets, including several different forms of Unicode. These include:

  AL16UTF16  =>  valid for NCHAR columns (CSID=2000)
  UTF8       =>  valid for NCHAR columns (CSID=871), deprecated
  AL32UTF8   =>  valid for NCHAR and CHAR columns (CSID=873)

When you create an Oracle database, you must specify the DATABASE character set (used for DDL, DML and CHAR datatypes) and the NATIONAL character set (used for NCHAR and NCLOB types). The character sets used in your database can be found using:

  $hash_ref = $dbh->ora_nls_parameters()
  $database_charset = $hash_ref->{NLS_CHARACTERSET};
  $national_charset = $hash_ref->{NLS_NCHAR_CHARACTERSET};

The Oracle 9.2 and later default for the national character set is AL16UTF16. The default for the database character set is often US7ASCII. Although many experienced DBAs will consider an 8bit character set like WE8ISO8859P1 or WE8MSWIN1252. To use any character set with Oracle other than US7ASCII, requires that the NLS_LANG environment variable be set. See the International NLS / 8-bit text issues section below.

You are strongly urged to read the Oracle Internationalization documentation specifically with respect the choices and trade offs for creating a databases for use with international character sets.

Oracle uses the NLS_LANG environment variable to indicate what character set is being used on the client. When fetching data Oracle will convert from whatever the database character set is to the client character set specified by NLS_LANG. Similarly, when sending data to the database Oracle will convert from the character set specified by NLS_LANG to the database character set.

The NLS_NCHAR environment variable can be used to define a different character set for 'national' (NCHAR) character types.

Both UTF8 and AL32UTF32 can be used in NLS_LANG and NLS_NCHAR. For example:

   NLS_LANG=AMERICAN_AMERICA.UTF8
   NLS_LANG=AMERICAN_AMERICA.AL32UTF8
   NLS_NCHAR=UTF8
   NLS_NCHAR=AL32UTF8

Oracle 8 client libraries have a number of bugs related to character set handling, especially when connected to an Oracle 9+ server. For this reason a number of DBD::Oracle tests are disabled when using an Oracle 8 client. If you wish to use Unicode, I recommend upgrading client and server to Oracle 9 or later.

Oracle UTF8 is not UTF-8

AL32UTF8 should be used in preference to UTF8 if it works for you, which it should for Oracle 9.2 or later. If you're using an old version of Oracle that doesn't support AL32UTF8 then you should avoid using any Unicode characters that require surrogates, in other words characters beyond the Unicode BMP (Basic Multilingual Plane).

That's because the character set that Oracle calls "UTF8" doesn't conform to the UTF-8 standard in its handling of surrogate characters. Technically the encoding that Oracle calls "UTF8" is known as "CESU-8". Here are a couple of extracts from http://www.unicode.org/reports/tr26/:

  CESU-8 is useful in 8-bit processing environments where binary
  collation with UTF-16 is required. It is designed and recommended
  for use only within products requiring this UTF-16 binary collation
  equivalence. It is not intended nor recommended for open interchange.
  As a very small percentage of characters in a typical data stream
  are expected to be supplementary characters, there is a strong
  possibility that CESU-8 data may be misinterpreted as UTF-8.
  Therefore, all use of CESU-8 outside closed implementations is
  strongly discouraged, such as the emittance of CESU-8 in output
  files, markup language or other open transmission forms.

Oracle uses this internally because it collates (sorts) in the same order as UTF16, which is the basis of Oracle's internal collation definitions.

Rather than change UTF8 for clients Oracle chose to define a new character set called "AL32UTF8" which does conform to the UTF-8 standard. (The AL32UTF8 character set can't be used on the server because it would break collation.)

Because of that, for the rest of this document we'll use "AL32UTF8". If you're using an Oracle version below 9.2 you'll need to use "UTF8" until you upgrade.

DBD::Oracle and Unicode

DBD::Oracle Unicode support has been implemented for Oracle versions 9 or greater, and perl version 5.6 or greater (though we strongly suggest that you use perl 5.8.2 or later).

You can check which Oracle version your DBD::Oracle was built with by importing the ORA_OCI constant from DBD::Oracle.

Fetching Data

Any data returned from Oracle to DBD::Oracle in the AL32UTF8 character set will be marked as UTF-8 to ensure correct handling by perl.

For Oracle to return data in the AL32UTF8 character set the NLS_LANG or NLS_NCHAR environment variable must be set as described in the previous section.

When fetching NCHAR, NVARCHAR, or NCLOB data from Oracle, DBD::Oracle will set the perl UTF-8 flag on the returned data if either NLS_NCHAR is AL32UTF8, or NLS_NCHAR is not set and NLS_LANG is AL32UTF8.

When fetching other character data from Oracle, DBD::Oracle will set the perl UTF-8 flag on the returned data if NLS_LANG is AL32UTF8.

Sending Data using Placeholders

Data bound to a placeholder is assumed to be in the default client character set (specified by NLS_LANG) except for a few special cases. These are listed here with the highest precedence first:

If the ora_csid attribute is given to bind_param() then that is passed to Oracle and takes precedence.

If the value is a Perl Unicode string (UTF-8) then DBD::Oracle ensures that Oracle uses the Unicode character set, regardless of the NLS_LANG and NLS_NCHAR settings.

If the placeholder is for inserting an NCLOB then the client NLS_NCHAR character set is used. (That's useful but inconsistent with the other behaviour so may change. Best to be explicit by using the ora_csform attribute.)

If the ora_csform attribute is given to bind_param() then that determines if the value should be assumed to be in the default (NLS_LANG) or NCHAR (NLS_NCHAR) client character set.

   use DBD::Oracle qw( SQLCS_IMPLICIT SQLCS_NCHAR );
   ...
   $sth->bind_param(1, $value, { ora_csform => SQLCS_NCHAR });

or

   $dbh->{ora_ph_csform} = SQLCS_NCHAR; # default for all future placeholders

Sending Data using SQL

Oracle assumes the SQL statement is in the default client character set (as specified by NLS_LANG). So Unicode strings containing non-ASCII characters should not be used unless the default client character set is AL32UTF8.

DBD::Oracle and Other Character Sets and Encodings

The only multi-byte Oracle character set supported by DBD::Oracle is "AL32UTF8" (and "UTF8"). Single-byte character sets should work well.

Other Data Types

DBD::Oracle does not explicitly support most Oracle data types. It simply asks Oracle to return them as strings and Oracle does so. Mostly. Similarly when binding placeholder values DBD::Oracle binds them as strings and Oracle converts them to the appropriate type, such as DATE, when used.

Some of these automatic conversions to and from strings use NLS setings to control the formating for output and the parsing for input. The most common example is the DATE type. The default NLS format for DATE might be DD-MON-YYYY and so when a DATE type is fetched that's how Oracle will format the date. NLS settings also control the default parsing of strings into DATE values. An error will be generated if the contents of the string don't match the NLS format. If you're dealing in dates which don't match the default NLS format then you can either change the default NLS format or, more commonly, use TO_CHAR(field, "format") and TO_DATE(?, "format") to explicitly specify formats for converting to and from strings.

A slightly more subtle problem can occur with NUMBER types. The default NLS settings might format numbers with a fullstop (".") to separate thousands and a comma (",") as the decimal point. Perl will generate warnings and use incorrect values when numbers, returned and formatted as strings in this way by Oracle, are used in a numeric context. You could explicitly convert each numeric value using the TO_CHAR(...) function but that gets tedious very quickly. The best fix is to change the NLS settings. That can be done for an individual connection by doing:

  $dbh->do("ALTER SESSION SET NLS_NUMERIC_CHARACTERS = '.,'");

There are some types, like BOOLEAN, that Oracle does not automatically convert to or from strings (pity). These need to be converted explicitly using SQL or PL/SQL functions.

Examples:

   # DATE values
   my $sth0 = $dbh->prepare( <<SQL_END );
   SELECT username, TO_CHAR( created, ? )
      FROM all_users
      WHERE created >= TO_DATE( ?, ? )
   SQL_END
   $sth0->execute( 'YYYY-MM-DD HH24:MI:SS', "2003", 'YYYY' );

   # BOOLEAN values
   my $sth2 = $dbh->prepare( <<PLSQL_END );
   DECLARE
      b0 BOOLEAN;
      b1 BOOLEAN;
      o0 VARCHAR2(32);
      o1 VARCHAR2(32);

      FUNCTION to_bool( i VARCHAR2 ) RETURN BOOLEAN IS
      BEGIN
         IF    i IS NULL          THEN RETURN NULL;
         ELSIF i = 'F' OR i = '0' THEN RETURN FALSE;
         ELSE                          RETURN TRUE;
         END IF;
      END;
      FUNCTION from_bool( i BOOLEAN ) RETURN NUMBER IS
      BEGIN
         IF    i IS NULL THEN RETURN NULL;
         ELSIF i         THEN RETURN 1;
         ELSE                 RETURN 0;
         END IF;
      END;
         BEGIN
      -- Converting values to BOOLEAN
      b0 := to_bool( :i0 );
      b1 := to_bool( :i1 );

      -- Converting values from BOOLEAN
      :o0 := from_bool( b0 );
      :o1 := from_bool( b1 );
         END;
         PLSQL_END
         my ( $i0, $i1, $o0, $o1 ) = ( "", "Something else" );
         $sth2->bind_param( ":i0", $i0 );
         $sth2->bind_param( ":i1", $i1 );
         $sth2->bind_param_inout( ":o0", \$o0, 32 );
         $sth2->bind_param_inout( ":o1", \$o1, 32 );
         $sth2->execute();
         foreach ( $i0, $b0, $o0, $i1, $b1, $o1 ) {
      $_ = "(undef)" if ! defined $_;
         }
         print "$i0 to $o0, $i1 to $o1\n";
         # Result is : "'' to '(undef)', 'Something else' to '1'"

PL/SQL Examples

Most of these PL/SQL examples come from: Eric Bartley <bartley@cc.purdue.edu>.

   /*
    * PL/SQL to create package with stored procedures invoked by
    * Perl examples.  Execute using sqlplus.
    *
    * Use of "... OR REPLACE" prevents failure in the event that the
    * package already exists.
    */
    CREATE OR REPLACE PACKAGE plsql_example
    IS
      PROCEDURE proc_np;

      PROCEDURE proc_in (
          err_code IN NUMBER
      );

      PROCEDURE proc_in_inout (
          test_num IN NUMBER,
          is_odd IN OUT NUMBER
      );

      FUNCTION func_np
        RETURN VARCHAR2;

    END plsql_example;
  /
    CREATE OR REPLACE PACKAGE BODY plsql_example
    IS
      PROCEDURE proc_np
      IS
        whoami VARCHAR2(20) := NULL;
      BEGIN
        SELECT USER INTO whoami FROM DUAL;
      END;

      PROCEDURE proc_in (
        err_code IN NUMBER
      )
      IS
      BEGIN
        RAISE_APPLICATION_ERROR(err_code, 'This is a test.');
      END;

      PROCEDURE proc_in_inout (
        test_num IN NUMBER,
        is_odd IN OUT NUMBER
      )
      IS
      BEGIN
        is_odd := MOD(test_num, 2);
      END;

      FUNCTION func_np
        RETURN VARCHAR2
      IS
        ret_val VARCHAR2(20);
      BEGIN
        SELECT USER INTO ret_val FROM DUAL;
        RETURN ret_val;
      END;

    END plsql_example;
      /
      /* End PL/SQL for example package creation. */

  use DBI;

  my($db, $csr, $ret_val);

  $db = DBI->connect('dbi:Oracle:database','user','password')
        or die "Unable to connect: $DBI::errstr";

  # So we don't have to check every DBI call we set RaiseError.
  # See the DBI docs now if you're not familiar with RaiseError.
  $db->{RaiseError} = 1;

  # Example 1   Eric Bartley <bartley@cc.purdue.edu>
  #
  # Calling a PLSQL procedure that takes no parameters. This shows you the
  # basic's of what you need to execute a PLSQL procedure. Just wrap your
  # procedure call in a BEGIN END; block just like you'd do in SQL*Plus.
  #
  # p.s. If you've used SQL*Plus's exec command all it does is wrap the
  #      command in a BEGIN END; block for you.

  $csr = $db->prepare(q{
    BEGIN
      PLSQL_EXAMPLE.PROC_NP;
    END;
  });
  $csr->execute;

  # Example 2   Eric Bartley <bartley@cc.purdue.edu>
  #
  # Now we call a procedure that has 1 IN parameter. Here we use bind_param
  # to bind out parameter to the prepared statement just like you might
  # do for an INSERT, UPDATE, DELETE, or SELECT statement.
  #
  # I could have used positional placeholders (e.g. :1, :2, etc.) or
  # ODBC style placeholders (e.g. ?), but I prefer Oracle's named
  # placeholders (but few DBI drivers support them so they're not portable).

  my $err_code = -20001;

  $csr = $db->prepare(q{
        BEGIN
            PLSQL_EXAMPLE.PROC_IN(:err_code);
        END;
  });

  $csr->bind_param(":err_code", $err_code);

  # PROC_IN will RAISE_APPLICATION_ERROR which will cause the execute to 'fail'.
  # Because we set RaiseError, the DBI will croak (die) so we catch that with eval.
  eval {
    $csr->execute;
  };
  print 'After proc_in: $@=',"'$@', errstr=$DBI::errstr, ret_val=$ret_val\n";

  # Example 3   Eric Bartley <bartley@cc.purdue.edu>
  #
  # Building on the last example, I've added 1 IN OUT parameter. We still
  # use a placeholders in the call to prepare, the difference is that
  # we now call bind_param_inout to bind the value to the place holder.
  #
  # Note that the third parameter to bind_param_inout is the maximum size
  # of the variable. You normally make this slightly larger than necessary.
  # But note that the perl variable will have that much memory assigned to
  # it even if the actual value returned is shorter.

  my $test_num = 5;
  my $is_odd;

  $csr = $db->prepare(q{
        BEGIN
            PLSQL_EXAMPLE.PROC_IN_INOUT(:test_num, :is_odd);
        END;
  });

  # The value of $test_num is _copied_ here
  $csr->bind_param(":test_num", $test_num);

  $csr->bind_param_inout(":is_odd", \$is_odd, 1);

  # The execute will automagically update the value of $is_odd
  $csr->execute;

  print "$test_num is ", ($is_odd) ? "odd - ok" : "even - error!", "\n";

  # Example 4   Eric Bartley <bartley@cc.purdue.edu>
  #
  # What about the return value of a PLSQL function? Well treat it the same
  # as you would a call to a function from SQL*Plus. We add a placeholder
  # for the return value and bind it with a call to bind_param_inout so
  # we can access it's value after execute.

  my $whoami = "";

  $csr = $db->prepare(q{
        BEGIN
            :whoami := PLSQL_EXAMPLE.FUNC_NP;
        END;
  });

  $csr->bind_param_inout(":whoami", \$whoami, 20);
  $csr->execute;
  print "Your database user name is $whoami\n";

  $db->disconnect;

You can find more examples in the t/plsql.t file in the DBD::Oracle source directory.

Oracle 9.2 appears to have a bug where a variable bound with bind_param_inout() that isn't assigned to by the executed PL/SQL block may contain garbage. See http://www.mail-archive.com/dbi-users@perl.org/msg18835.html

Private database handle functions

These functions are called through the method func() which is described in the DBI documentation.

plsql_errstr

This function returns a string which describes the errors from the most recent PL/SQL function, procedure, package, or package body compile in a format similar to the output of the SQL*Plus command 'show errors'.

The function returns undef if the error string could not be retrieved due to a database error. Look in $dbh->errstr for the cause of the failure.

If there are no compile errors, an empty string is returned.

Example:

    # Show the errors if CREATE PROCEDURE fails
    $dbh->{RaiseError} = 0;
    if ( $dbh->do( q{
        CREATE OR REPLACE PROCEDURE perl_dbd_oracle_test as
        BEGIN
            PROCEDURE filltab( stuff OUT TAB ); asdf
        END; } ) ) {} # Statement succeeded
    }
    elsif ( 6550 != $dbh->err ) { die $dbh->errstr; } # Utter failure
    else {
        my $msg = $dbh->func( 'plsql_errstr' );
        die $dbh->errstr if ! defined $msg;
        die $msg if $msg;
    }

dbms_output_enable / dbms_output_put / dbms_output_get

These functions use the PL/SQL DBMS_OUTPUT package to store and retrieve text using the DBMS_OUTPUT buffer. Text stored in this buffer by dbms_output_put or any PL/SQL block can be retrieved by dbms_output_get or any PL/SQL block connected to the same database session.

Stored text is not available until after dbms_output_put or the PL/SQL block that saved it completes its execution. This means you CAN NOT use these functions to monitor long running PL/SQL procedures.

Example 1:

  # Enable DBMS_OUTPUT and set the buffer size
  $dbh->{RaiseError} = 1;
  $dbh->func( 1000000, 'dbms_output_enable' );

  # Put text in the buffer . . .
  $dbh->func( @text, 'dbms_output_put' );

  # . . . and retreive it later
  @text = $dbh->func( 'dbms_output_get' );

Example 2:

  $dbh->{RaiseError} = 1;
  $sth = $dbh->prepare(q{
    DECLARE tmp VARCHAR2(50);
    BEGIN
      SELECT SYSDATE INTO tmp FROM DUAL;
      dbms_output.put_line('The date is '||tmp);
    END;
  });
  $sth->execute;

  # retreive the string
  $date_string = $dbh->func( 'dbms_output_get' );
dbms_output_enable ( [ buffer_size ] )

This function calls DBMS_OUTPUT.ENABLE to enable calls to package DBMS_OUTPUT procedures GET, GET_LINE, PUT, and PUT_LINE. Calls to these procedures are ignored unless DBMS_OUTPUT.ENABLE is called first.

The buffer_size is the maximum amount of text that can be saved in the buffer and must be between 2000 and 1,000,000. If buffer_size is not given, the default is 20,000 bytes.

dbms_output_put ( [ @lines ] )

This function calls DBMS_OUTPUT.PUT_LINE to add lines to the buffer.

If all lines were saved successfully the function returns 1. Depending on the context, an empty list or undef is returned for failure.

If any line causes buffer_size to be exceeded, a buffer overflow error is raised and the function call fails. Some of the text might be in the buffer.

dbms_output_get

This function calls DBMS_OUTPUT.GET_LINE to retrieve lines of text from the buffer.

In an array context, all complete lines are removed from the buffer and returned as a list. If there are no complete lines, an empty list is returned.

In a scalar context, the first complete line is removed from the buffer and returned. If there are no complete lines, undef is returned.

Any text in the buffer after a call to DBMS_OUTPUT.GET_LINE or DBMS_OUTPUT.GET is discarded by the next call to DBMS_OUTPUT.PUT_LINE, DBMS_OUTPUT.PUT, or DBMS_OUTPUT.NEW_LINE.

reauthenticate ( $username, $password )

Starts a new session against the current database using the credentials supplied.

ora_nls_parameters ( [ $refresh ] )

Returns a hash reference containing the current NLS parameters, as given by the v$nls_parameters view. The values fetched are cached between calls. To cause the latest values to be fetched, pass a true value to the function.

ora_can_unicode ( [ $refresh ] )

Returns a number indicating whether either of the database character sets is a Unicode encoding. Calls ora_nls_parameters() and passes the optional $refresh parameter to it.

0 = Neither character set is a Unicode encoding.

1 = National character set is a Unicode encoding.

2 = Database character set is a Unicode encoding.

3 = Both character sets are Unicode encodings.

Prepare postponed till execute

The DBD::Oracle module can avoid an explicit 'describe' operation prior to the execution of the statement unless the application requests information about the results (such as $sth->{NAME}). This reduces communication with the server and increases performance (reducing the number of PARSE_CALLS inside the server).

However, it also means that SQL errors are not detected until execute() (or $sth->{NAME} etc) is called instead of when prepare() is called. Note that if the describe is triggered by the use of $sth->{NAME} or a similar attribute and the describe fails then an exception is thrown even if RaiseError is false!

Set ora_check_sql to 0 in prepare() to enable this behaviour.

Handling LOBs

Simple Usage

The value of an Oracle LOB column is not the content of the LOB. It's a 'LOB Locator' which, after being selected or inserted needs extra processing to read or write the content of the LOB.

When fetching LOBs they are, by default, made to look just like LONGs and are subject to the LongReadLen and LongTruncOk attributes. Note that with OCI 7 DBD::Oracle pre-allocates the whole buffer (LongReadLen) at the time the statement is prepared. With OCI 8+ it grows the buffer to the amount needed for the largest LOB to be fetched so far.

When inserting or updating LOBs some major magic has to be performed behind the scenes to make it transparent. Basically the driver has to insert a 'LOB Locator' and then refetch the newly inserted LOB Locator before being able to write the data into it. However, it works well most of the time, and I've made it as fast as possible, just one extra server-round-trip per insert or update after the first. For the time being, only single-row LOB updates are supported.

To insert or update a large LOB using a placeholder, DBD::Oracle has to know in advance that it is a LOB type. So you need to say:

  $sth->bind_param($field_num, $lob_value, { ora_type => ORA_CLOB });

The ORA_CLOB and ORA_BLOB constants can be imported using

  use DBD::Oracle qw(:ora_types);

or use the corresponding integer values (112 and 113).

One further wrinkle: for inserts and updates of LOBs, DBD::Oracle has to be able to tell which parameters relate to which table fields. In all cases where it can possibly work it out for itself, it does, however, if there are multiple LOB fields of the same type in the table then you need to tell it which field each LOB param relates to:

  $sth->bind_param($idx, $value, { ora_type=>ORA_CLOB, ora_field=>'foo' });

There are some limitations inherent in the way DBD::Oracle makes typical LOB operations simple by hiding the LOB Locator processing:

 - Can't pass LOBs to/from PL/SQL (except as strings less than 32KB)
 - Can't read/write LOBs in chunks (except via DBMS_LOB.WRITEAPPEND in PL/SQL)
 - To INSERT a LOB, you need UPDATE privilege.

The alternative is to disable the automatic LOB Locator processing. If ora_auto_lob is 0 in prepare(), you can fetch the LOB Locators and do all the work yourself using the ora_lob_*() methods and/or Oracle::OCI. See the LOB Methods section below.

LOB Locator Methods

The following driver-specific methods let you manipulate "LOB Locators". LOB locators can be selected from tables directly, if the ora_auto_lob attribute is false, or returned via PL/SQL procedure calls.

(If using a DBI version earlier than 1.36 they must be called via the func() method. Note that methods called via func() don't honour RaiseError etc, and so it's important to check $dbh->err after each call. It's recommended that you upgrade to DBI 1.38 or later.)

Warning: Currently multi-byte character set issues have not been fully worked out. So these methods may not do what you expect if either the perl data is utf8 or the CLOB is a multi-byte character set (including uft8). The current behaviour in these situations may not be correct and is subject to change. Testing and patches are most welcome.

ora_lob_read
  $data = $dbh->ora_lob_read($lob_locator, $offset, $length);

Read a portion of the LOB. $offset starts at 1. Uses the Oracle OCILobRead function.

ora_lob_write
  $rc = $dbh->ora_lob_write($lob_locator, $offset, $data);

Write/overwrite a portion of the LOB. $offset starts at 1. Uses the Oracle OCILobWrite function.

ora_lob_append
  $rc = $dbh->ora_lob_append($lob_locator, $data);

Append $data to the LOB. Uses the Oracle OCILobWriteAppend function.

NOTE: This method should not be used if either the client or the server are Oracle version 8 due to Oracle bug #886191.

ora_lob_trim
  $rc = $dbh->ora_lob_trim($lob_locator, $length);

Trims the length of the LOB to $length. Uses the Oracle OCILobTrim function.

ora_lob_length
  $length = $dbh->ora_lob_length($lob_locator);

Returns the length of the LOB. Uses the Oracle OCILobGetLength function.

LOB Locator Method Examples

Note: Make sure you first read the note in the section above about multi-byte character set issues with these methods.

The following examples demonstrate the usage of LOB Locators to read, write, and append data, and to query the size of large data.

The following examples assume a table containing two large object columns, one binary and one character, with a primary key column, defined as follows:

   CREATE TABLE lob_example (
      lob_id      INTEGER PRIMARY KEY,
      bindata     BLOB,
      chardata    CLOB
   )

It also assumes a sequence for use in generating unique lob_id field values, defined as follows:

   CREATE SEQUENCE lob_example_seq

Example: Inserting a new row with large data

Unless enough memory is available to store and bind the entire lob data for insert all at once, the lob columns must be written iteratively, piece by piece. In the case of a new row, this is performed by first inserting a row, with empty values in the lob columns, then modifying the row by writing the large data iteratively to the lob columns using their LOB locators as handles.

The insert statement must create token values in the lob columns. Here, we use the empty string for both the binary and character large object columns 'bindata' and 'chardata'.

After the INSERT statement, a SELECT statement is used to acquire lob locators to the 'bindata' and 'chardata' fields of the newly inserted row. Because these lob locators are subsequently written, they must be acquired from a select statement containing the clause 'FOR UPDATE' (lob locators are only valid within the transaction that fetched them, so can't be used effectively if AutoCommit is enabled).

   my $lob_id = $dbh->selectrow_array( <<"   SQL" );
      SELECT lob_example_seq.nextval FROM DUAL
   SQL

   my $sth = $dbh->prepare( <<"   SQL" );
      INSERT INTO lob_example
      ( lob_id, bindata, chardata )
      VALUES ( ?, EMPTY_BLOB(),EMPTY_CLOB() )
   SQL
   $sth->execute( $lob_id );

   $sth = $dbh->prepare( <<"   SQL", { ora_auto_lob => 0 } );
      SELECT bindata, chardata
      FROM lob_example
      WHERE lob_id = ?
      FOR UPDATE
   SQL
   $sth->execute( $lob_id );
   my ( $bin_locator, $char_locator ) = $sth->fetchrow_array();
   $sth->finish();

   open BIN_FH, "/binary/data/source" or die;
   open CHAR_FH, "/character/data/source" or die;
   my $chunk_size = 4096;   # Arbitrary chunk size

   # BEGIN WRITING BIN_DATA COLUMN
   my $offset = 1;   # Offsets start at 1, not 0
   my $length = 0;
   my $buffer = '';
   while( $length = read( BIN_FH, $buffer, $chunk_size ) ) {
      $dbh->ora_lob_write( $bin_locator, $offset, $buffer );
      $offset += $length;
   }

   # BEGIN WRITING CHAR_DATA COLUMN
   $offset = 1;   # Offsets start at 1, not 0
   $length = 0;
   $buffer = '';
   while( $length = read( CHAR_FH, $buffer, $chunk_size ) ) {
      $dbh->ora_lob_write( $char_locator, $offset, $buffer );
      $offset += $length;
   }

In this example we demonstrate the use of ora_lob_write() iteratively to append data to the columns 'bin_data' and 'char_data'. Had we used ora_lob_append(), we could have saved ourselves the trouble of keeping track of the offset into the lobs. The snippet of code beneath the comment 'BEGIN WRITING BIN_DATA COLUMN' could look as follows:

   my $buffer = '';
   while ( read( BIN_FH, $buffer, $chunk_size ) ) {
      $dbh->ora_lob_append( $bin_locator, $buffer );
   }

The scalar variables $offset and $length are no longer needed, because ora_lob_append() keeps track of the offset for us.

Example: Updating an existing row with large data

In this example, we demonstrate a technique for overwriting a portion of a blob field with new binary data. The blob data before and after the section overwritten remains unchanged. Hence, this technique could be used for updating fixed length subfields embedded in a binary field.

   my $lob_id = 5;   # Arbitrary row identifier, for example

   $sth = $dbh->prepare( <<"   SQL", { ora_auto_lob => 0 } );
      SELECT bindata
      FROM lob_example
      WHERE lob_id = ?
      FOR UPDATE
   SQL
   $sth->execute( $lob_id );
   my ( $bin_locator ) = $sth->fetchrow_array();

   my $offset = 100234;
   my $data = "This string will overwrite a portion of the blob";
   $dbh->ora_lob_write( $bin_locator, $offset, $data );

After running this code, the row where lob_id = 5 will contain, starting at position 100234 in the bin_data column, the string "This string will overwrite a portion of the blob".

Example: Streaming character data from the database

In this example, we demonstrate a technique for streaming data from the database to a file handle, in this case STDOUT. This allows more data to be read in and written out than could be stored in memory at a given time.

   my $lob_id = 17;   # Arbitrary row identifier, for example

   $sth = $dbh->prepare( <<"   SQL", { ora_auto_lob => 0 } );
      SELECT chardata
      FROM lob_example
      WHERE lob_id = ?
   SQL
   $sth->execute( $lob_id );
   my ( $char_locator ) = $sth->fetchrow_array();

   my $chunk_size = 1034;   # Arbitrary chunk size, for example
   my $offset = 1;   # Offsets start at 1, not 0
   while( my $data = $dbh->ora_lob_read( $char_locator, $offset, $chunk_size ) ) {
      print STDOUT $data;
      $offset += $chunk_size;
   }

Notice that the select statement does not contain the phrase "FOR UPDATE". Because we are only reading from the lob locator returned, and not modifying the lob it refers to, the select statement does not require the "FOR UPDATE" clause.

Example: Truncating existing large data

In this example, we truncate the data already present in a large object column in the database. Specifically, for each row in the table, we truncate the 'bindata' value to half its previous length.

After acquiring a lob locator for the column, we query its length, then we trim the length by half. Because we modify the large objects with the call to ora_lob_trim(), we must select the lob locators 'FOR UPDATE'.

   my $sth = $dbh->prepare( <<"   SQL", { ora_auto_lob => 0 } );
      SELECT bindata
      FROM lob_example
      FOR UPATE
   SQL
   $sth->execute();
   while( my ( $bin_locator ) = $sth->fetchrow_array() ) {
      my $binlength = $dbh->ora_lob_length( $bin_locator );
      if( $binlength > 0 ) {
         $dbh->ora_lob_trim( $bin_locator, $binlength/2 );
      }
   }

Binding Cursors

Cursors can be returned from PL/SQL blocks, either from stored functions (or procedures with OUT parameters) or from direct OPEN statements, as shown below:

  use DBI;
  use DBD::Oracle qw(:ora_types);
  my $dbh = DBI->connect(...);
  my $sth1 = $dbh->prepare(q{
      BEGIN OPEN :cursor FOR
          SELECT table_name, tablespace_name
          FROM user_tables WHERE tablespace_name = :space;
      END;
  });
  $sth1->bind_param(":space", "USERS");
  my $sth2;
  $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
  $sth1->execute;
  # $sth2 is now a valid DBI statement handle for the cursor
  while ( my @row = $sth2->fetchrow_array ) { ... }

The only special requirement is the use of bind_param_inout() with an attribute hash parameter that specifies ora_type as ORA_RSET. If you don't do that you'll get an error from the execute() like: "ORA-06550: line X, column Y: PLS-00306: wrong number or types of arguments in call to ...".

Here's an alternative form using a function that returns a cursor. This example uses the pre-defined weak (or generic) REF CURSOR type SYS_REFCURSOR. This is an Oracle 9 feature. For Oracle 8, you must create your own REF CURSOR type in a package (see the curref.pl script mentioned at the end of this section).

  # Create the function that returns a cursor
  $dbh->do(q{
      CREATE OR REPLACE FUNCTION sp_ListEmp RETURN SYS_REFCURSOR
      AS l_cursor SYS_REFCURSOR;
      BEGIN
          OPEN l_cursor FOR select ename, empno from emp
              ORDER BY ename;
          RETURN l_cursor;
      END;
  });

  # Use the function that returns a cursor
  my $sth1 = $dbh->prepare(q{BEGIN :cursor := sp_ListEmp; END;});
  my $sth2;
  $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
  $sth1->execute;
  # $sth2 is now a valid DBI statement handle for the cursor
  while ( my @row = $sth2->fetchrow_array ) { ... }

A cursor obtained from PL/SQL as above may be passed back to PL/SQL by binding for input, as shown in this example, which explicitly closes a cursor:

  my $sth3 = $dbh->prepare("BEGIN CLOSE :cursor; END;");
  $sth3->bind_param(":cursor", $sth2, { ora_type => ORA_RSET } );
  $sth3->execute;

It is not normally necessary to close a cursor explicitly in this way. Oracle will close the cursor automatically at the first client-server interaction after the cursor statement handle is destroyed. An explicit close may be desirable if the reference to the cursor handle from the PL/SQL statement handle delays the destruction of the cursor handle for too long. This reference remains until the PL/SQL handle is re-bound, re-executed or destroyed.

See the curref.pl script in the Oracle.ex directory in the DBD::Oracle source distribution for a complete working example.

Fetching Nested Cursors

Oracle supports the use of select list expressions of type REF CURSOR. These may be explicit cursor expressions - CURSOR(SELECT ...), or calls to PL/SQL functions which return REF CURSOR values. The values of these expressions are known as nested cursors.

The value returned to a Perl program when a nested cursor is fetched is a statement handle. This statement handle is ready to be fetched from. It should not (indeed, must not) be executed.

Oracle imposes a restriction on the order of fetching when nested cursors are used. Suppose $sth1 is a handle for a select statement involving nested cursors, and $sth2 is a nested cursor handle fetched from $sth1. $sth2 can only be fetched from while $sth1 is still active, and the row containing $sth2 is still current in $sth1. Any attempt to fetch another row from $sth1 renders all nested cursor handles previously fetched from $sth1 defunct.

Fetching from such a defunct handle results in an error with the message ERROR nested cursor is defunct (parent row is no longer current).

This means that the fetchall... or selectall... methods are not useful for queries returning nested cursors. By the time such a method returns, all the nested cursor handles it has fetched will be defunct.

It is necessary to use an explicit fetch loop, and to do all the fetching of nested cursors within the loop, as the following example shows:

    use DBI;
    my $dbh = DBI->connect(...);
    my $sth = $dbh->prepare(q{
        SELECT dname, CURSOR(
            SELECT ename FROM emp
                WHERE emp.deptno = dept.deptno
                ORDER BY ename
        ) FROM dept ORDER BY dname
    });
    $sth->execute;
    while ( my ($dname, $nested) = $sth->fetchrow_array ) {
        print "$dname\n";
        while ( my ($ename) = $nested->fetchrow_array ) {
            print "        $ename\n";
        }
    }

The cursor returned by the function sp_ListEmp defined in the previous section can be fetched as a nested cursor as follows:

    my $sth = $dbh->prepare(q{SELECT sp_ListEmp FROM dual});
    $sth->execute;
    my ($nested) = $sth->fetchrow_array;
    while ( my @row = $nested->fetchrow_array ) { ... }

Pre-fetching Nested Cursors

By default, DBD::Oracle pre-fetches rows in order to reduce the number of round trips to the server. For queries which do not involve nested cursors, the number of pre-fetched rows is controlled by the DBI database handle attribute RowCacheSize (q.v.).

In Oracle, server side open cursors are a controlled resource, limited in number, on a per session basis, to the value of the initialization parameter OPEN_CURSORS. Nested cursors count towards ths limit. Each nested cursor in the current row counts 1, as does each nested cursor in a pre-fetched row. Defunct nested cursors do not count.

An Oracle specific database handle attribute, ora_max_nested_cursors, further controls pre-fetching for queries involving nested cursors. For each statement handle, the total number of nested cursors in pre-fetched rows is limited to the value of this parameter. The default value is 0, which disables pre-fetching for queries involving nested cursors.

Returning A Value from an INSERT

Oracle supports an extended SQL insert syntax which will return one or more of the values inserted. This can be particularly useful for single-pass insertion of values with re-used sequence values (avoiding a separate "select seq.nextval from dual" step).

  $sth = $dbh->prepare(qq{
      INSERT INTO foo (id, bar)
      VALUES (foo_id_seq.nextval, :bar)
      RETURNING id INTO :id
  });
  $sth->bind_param(":bar", 42);
  $sth->bind_param_inout(":id", \my $new_id, 99);
  $sth->execute;
  print "The id of the new record is $new_id\n";

If you have many columns to bind you can use code like this:

  @params = (... column values for record to be inserted ...);
  $sth->bind_param($_, $params[$_-1]) for (1..@params);
  $sth->bind_param_inout(@params+1, \my $new_id, 99);
  $sth->execute;

Returning A Recordset

DBD::Oracle does not currently support binding a PL/SQL table (aka array) as an IN OUT parameter to any Perl data structure. You cannot therefore call a PL/SQL function or procedure from DBI that uses a non-atomic data type as either a parameter, or a return value. However, if you are using Oracle 9.0.1 or later, you can make use of table (or pipelined) functions.

For example, assume you have the existing PL/SQL Package :

CREATE OR REPLACE PACKAGE Array_Example AS -- TYPE tRec IS RECORD ( Col1 NUMBER, Col2 VARCHAR2 (10), Col3 DATE) ; -- TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ; -- FUNCTION Array_Func RETURN taRec ; -- END Array_Example ;

CREATE OR REPLACE PACKAGE BODY Array_Example AS -- FUNCTION Array_Func RETURN taRec AS -- l_Ret taRec ; -- BEGIN FOR i IN 1 .. 5 LOOP l_Ret (i).Col1 := i ; l_Ret (i).Col2 := 'Row : ' || i ; l_Ret (i).Col3 := TRUNC (SYSDATE) + i ; END LOOP ; RETURN l_Ret ; END ; -- END Array_Example ; /

Currently, there is no way to directly call the function Array_Example.Array_Func from DBI. However, by making the following relatively painless additions, its not only possible, but extremely efficient.

First, you need to create database object types that correspond to the record and table types in the package. From the above example, these would be :

  CREATE OR REPLACE TYPE tArray_Example__taRec
  AS OBJECT (
      Col1    NUMBER,
      Col2    VARCHAR2 (10),
      Col3    DATE
  ) ;

  CREATE OR REPLACE TYPE taArray_Example__taRec
  AS TABLE OF tArray_Example__taRec ;

Now, assuming the existing function needs to remain unchanged (it is probably being called from other PL/SQL code), we need to add a new function to the package. Here's the new package specification and body :

  CREATE OR REPLACE PACKAGE Array_Example AS
      --
      TYPE tRec IS RECORD (
          Col1    NUMBER,
          Col2    VARCHAR2 (10),
          Col3    DATE) ;
      --
      TYPE taRec IS TABLE OF tRec INDEX BY BINARY_INTEGER ;
      --
      FUNCTION Array_Func RETURN taRec ;
      FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED ;
      --
  END Array_Example ;

  CREATE OR REPLACE PACKAGE BODY Array_Example AS
  --
  FUNCTION Array_Func RETURN taRec AS
      l_Ret  taRec ;
  BEGIN
      FOR i IN 1 .. 5 LOOP
          l_Ret (i).Col1 := i ;
          l_Ret (i).Col2 := 'Row : ' || i ;
          l_Ret (i).Col3 := TRUNC (SYSDATE) + i ;
      END LOOP ;
      RETURN l_Ret ;
  END ;

  FUNCTION Array_Func_DBI RETURN taArray_Example__taRec PIPELINED AS
      l_Set  taRec ;
  BEGIN
      l_Set := Array_Func ;
      FOR i IN l_Set.FIRST .. l_Set.LAST LOOP
          PIPE ROW (
              tArray_Example__taRec (
                  l_Set (i).Col1,
                  l_Set (i).Col2,
                  l_Set (i).Col3
              )
          ) ;
      END LOOP ;
      RETURN ;
  END ;
  --
  END Array_Example ;

As you can see, the new function is very simple. Now, it is a simple matter of calling the function as a straight-forward SELECT from your DBI code. From the above example, the code would look something like this :

  my $sth = $dbh->prepare('SELECT * FROM TABLE(Array_Example.Array_Func_DBI)');
  $sth->execute;
  while ( my ($col1, $col2, $col3) = $sth->fetchrow_array {
    ...
  }

Timezones

If TWO_TASK isn't set, Oracle uses the TZ variable from the local environment.

If TWO_TASK IS set, Oracle uses the TZ variable of the listener process running on the server.

You could have multiple listeners, each with their own TZ, and assign users to the appropriate listener by setting TNS_ADMIN to a directory that contains a tnsnames.ora file that points to the port that their listener is on.

[Brad Howerter, who supplied this info said: "I've done this to simulate running a perl script at the end of the previous month even though it was the 6th of the new month. I had the dba start up a listener with TZ=X+144. (144 hours = 6 days)"]

Oracle Related Links

Oracle on Linux

  http://www.datamgmt.com/maillist.html
  http://www.eGroups.com/list/oracle-on-linux
  http://www.wmd.de/wmd/staff/pauck/misc/oracle_on_linux.html
  ftp://oracle-ftp.oracle.com/server/patch_sets/LINUX
  http://www.ixora.com.au/

Free Oracle Tools and Links

  ora_explain supplied and installed with DBD::Oracle.
  http://www.orafaq.com/
  http://vonnieda.org/oracletool/

Commercial Oracle Tools and Links

Assorted tools and references for general information. No recommendation implied.

  http://www.platinum.com/products/oracle.htm
  http://www.SoftTreeTech.com
  http://www.databasegroup.com

Also PL/Vision from RevealNet and Steven Feuerstein, and "Q" from Savant Corporation.

SEE ALSO

the DBI manpage

http://search.cpan.org/~timb/DBD-Oracle/MANIFEST for all files in the DBD::Oracle source distribution including the examples in the Oracle.ex directory

  http://search.cpan.org/search?query=Oracle&mode=dist

AUTHOR

DBD::Oracle by Tim Bunce. DBI by Tim Bunce.

ACKNOWLEDGEMENTS

A great many people have helped me with DBD::Oracle over the 12 years between 1994 and 2006. Far too many to name, but I thank them all. Many are named in the Changes file.

See also ACKNOWLEDGEMENTS in the DBI manpage.

MAINTAINER

As of release 1.17 in February 2006 The Pythian Group, Inc. (http://www.pythian.com) are taking the lead in maintaining DBD::Oracle with my assistance and gratitude. That frees more of my time to work on DBI for perl 5 and perl 6.

COPYRIGHT

The DBD::Oracle module is Copyright (c) 1994-2006 Tim Bunce. Ireland.

The DBD::Oracle module is free open source software; you can redistribute it and/or modify it under the same terms as Perl 5.

CONTRIBUTING

If you'd like DBD::Oracle to do something new or different the best way to make that happen is to do it yourself and email to dbi-dev@perl.org a patch of the source code (using 'diff' - see below) that shows the changes.

How to create a patch using Subversion

The DBD::Oracle source code is maintained using Subversion (a replacement for CVS, see http://subversion.tigris.org/). To access the source you'll need to install a Subversion client. Then, to get the source code, do:

  svn checkout http://svn.perl.org/modules/dbd-oracle/trunk

If it prompts for a username and password use your perl.org account if you have one, else just 'guest' and 'guest'. The source code will be in a new subdirectory called trunk.

To keep informed about changes to the source you can send an empty email to dbd-oracle-changes-subscribe@perl.org after which you'll get an email with the change log message and diff of each change checked-in to the source.

After making your changes you can generate a patch file, but before you do, make sure your source is still upto date using:

  svn update

If you get any conflicts reported you'll need to fix them first. Then generate the patch file from within the trunk directory using:

  svn diff > foo.patch

Read the patch file, as a sanity check, and then email it to dbi-dev@perl.org.

How to create a patch without Subversion

Unpack a fresh copy of the distribution:

  tar xfz DBD-Oracle-1.40.tar.gz

Rename the newly created top level directory:

  mv DBD-Oracle-1.40 DBD-Oracle-1.40.your_foo

Edit the contents of DBD-Oracle-1.40.your_foo/* till it does what you want.

Test your changes and then remove all temporary files:

  make test && make distclean

Go back to the directory you originally unpacked the distribution:

  cd ..

Unpack another copy of the original distribution you started with:

  tar xfz DBD-Oracle-1.40.tar.gz

Then create a patch file by performing a recursive diff on the two top level directories:

  diff -r -u DBD-Oracle-1.40 DBD-Oracle-1.40.your_foo > DBD-Oracle-1.40.your_foo.patch

Speak before you patch

For anything non-trivial or possibly controversial it's a good idea to discuss (on dbi-dev@perl.org) the changes you propose before actually spending time working on them. Otherwise you run the risk of them being rejected because they don't fit into some larger plans you may not be aware of.


DBD::Pg - PostgreSQL database driver for the DBI module

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • MODULE DOCUMENTATION
  • THE DBI CLASS
    • DBI Class Methods
  • METHODS COMMON TO ALL HANDLES
  • ATTRIBUTES COMMON TO ALL HANDLES
  • DBI DATABASE HANDLE OBJECTS
    • Database Handle Methods
    • Database Handle Attributes
  • DBI STATEMENT HANDLE OBJECTS
    • Statement Handle Methods
    • Statement Handle Attributes
  • FURTHER INFORMATION
    • Transactions
    • Savepoints
    • COPY support
    • Large Objects
    • Cursors
    • Datatype bool
    • Schema support
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT
  • ACKNOWLEDGMENTS

NAME

DBD::Pg - PostgreSQL database driver for the DBI module

VERSION

This documents version 1.45 of the DBD::Pg module

SYNOPSIS

  use DBI;

  $dbh = DBI->connect("dbi:Pg:dbname=$dbname", "", "", {AutoCommit => 0});

  # For some advanced uses you may need PostgreSQL type values:
  use DBD::Pg qw(:pg_types);

  # See the DBI module documentation for full details

DESCRIPTION

DBD::Pg is a Perl module that works with the DBI module to provide access to PostgreSQL databases.

MODULE DOCUMENTATION

This documentation describes driver specific behavior and restrictions. It is not supposed to be used as the only reference for the user. In any case consult the DBI documentation first!

THE DBI CLASS

DBI Class Methods

connect

To connect to a database with a minimum of parameters, use the following syntax:

  $dbh = DBI->connect("dbi:Pg:dbname=$dbname", "", "");

This connects to the database $dbname at localhost without any user authentication. This is sufficient for the defaults of PostgreSQL (excluding some package-installed versions).

The following connect statement shows almost all possible parameters:

  $dbh = DBI->connect("dbi:Pg:dbname=$dbname;host=$host;port=$port;" .
                      "options=$options", "$username", "$password",
                      {AutoCommit => 0});

If a parameter is undefined PostgreSQL first looks for specific environment variables and then it uses hard-coded defaults:

  parameter  environment variable  hard coded default
  --------------------------------------------------
  host       PGHOST                local domain socket
  hostaddr*  PGHOSTADDR            local domain socket
  port       PGPORT                5432
  dbname**   PGDATABASE            current userid
  username   PGUSER                current userid
  password   PGPASSWORD            ""
  options    PGOPTIONS             ""
  service*   PGSERVICE             ""
  sslmode*   PGSSLMODE             ""

* Only for servers running version 7.4 or greater

** Can also use "db" or "database"

The options parameter specifies runtime options for the Postgres backend. Common usage is to increase the number of buffers with the -B option. Also important is the -F option, which disables automatic fsync() call after each transaction. For further details please refer to the PostgreSQL documentation at http://www.postgresql.org/docs/.

For authentication with username and password, appropriate entries have to be made in pg_hba.conf. Please refer to the comments in the pg_hba.conf and the pg_passwd files for the different types of authentication. Note that for these two parameters DBI distinguishes between empty and undefined. If these parameters are undefined DBI substitutes the values of the environment variables DBI_USER and DBI_PASS if present.

available_drivers
  @driver_names = DBI->available_drivers;

Implemented by DBI, no driver-specific impact.

data_sources
  @data_sources = DBI->data_sources('Pg');

This driver supports this method. Note that the necessary database connection to the database "template1" will be made on the localhost without any user authentication. Other preferences can only be set with the environment variables PGHOST, PGPORT, DBI_USER, and DBI_PASS.

METHODS COMMON TO ALL HANDLES

err
  $rv = $h->err;

Supported by this driver as proposed by DBI. For the connect method it returns PQstatus. In all other cases it returns PQresultStatus of the current handle.

errstr
  $str = $h->errstr;

Supported by this driver as proposed by DBI. It returns the PQerrorMessage related to the current handle.

state
  $str = $h->state;

Supported by this driver. Returns a five-character "SQLSTATE" code. Success is indicated by a "00000" code, which gets mapped to an empty string by DBI. A code of S8006 indicates a connection failure, usually because the connection to the PostgreSQL server has been lost. Note that this can be called as both $sth->state and $dbh->state.

PostgreSQL servers version less than 7.4 will return a small subset of the available codes, and should not be relied upon.

The list of codes used by PostgreSQL can be found at: http://www.postgresql.org/docs/current/static/errcodes-appendix.html

trace
  $h->trace($trace_level, $trace_filename);

Implemented by DBI, no driver-specific impact.

trace_msg
  $h->trace_msg($message_text);

Implemented by DBI, no driver-specific impact.

func

This driver supports a variety of driver specific functions accessible via the func method. Note that the name of the function comes last, after the arguments.

table_attributes
  $attrs = $dbh->func($table, 'table_attributes');

The table_attributes function is no longer recommended. Instead, you can use the more portable column_info and primary_key methods to access the same information.

The table_attributes method returns, for the given table argument, a reference to an array of hashes, each of which contains the following keys:

  NAME        attribute name
  TYPE        attribute type
  SIZE        attribute size (-1 for variable size)
  NULLABLE    flag nullable
  DEFAULT     default value
  CONSTRAINT  constraint
  PRIMARY_KEY flag is_primary_key
  REMARKS     attribute description

The REMARKS field will be returned as NULL for Postgres versions 7.1.x and older.

lo_creat
  $lobjId = $dbh->func($mode, 'lo_creat');

Creates a new large object and returns the object-id. $mode is a bitmask describing different attributes of the new object. Use the following constants:

  $dbh->{pg_INV_WRITE}
  $dbh->{pg_INV_READ}

Upon failure it returns undef.

lo_open
  $lobj_fd = $dbh->func($lobjId, $mode, 'lo_open');

Opens an existing large object and returns an object-descriptor for use in subsequent lo_* calls. For the mode bits see lo_creat. Returns undef upon failure. Note that 0 is a perfectly correct object descriptor!

lo_write
  $nbytes = $dbh->func($lobj_fd, $buf, $len, 'lo_write');

Writes $len bytes of $buf into the large object $lobj_fd. Returns the number of bytes written and undef upon failure.

lo_read
  $nbytes = $dbh->func($lobj_fd, $buf, $len, 'lo_read');

Reads $len bytes into $buf from large object $lobj_fd. Returns the number of bytes read and undef upon failure.

lo_lseek
  $loc = $dbh->func($lobj_fd, $offset, $whence, 'lo_lseek');

Changes the current read or write location on the large object $obj_id. Currently $whence can only be 0 (L_SET). Returns the current location and undef upon failure.

lo_tell
  $loc = $dbh->func($lobj_fd, 'lo_tell');

Returns the current read or write location on the large object $lobj_fd and undef upon failure.

lo_close
  $lobj_fd = $dbh->func($lobj_fd, 'lo_close');

Closes an existing large object. Returns true upon success and false upon failure.

lo_unlink
  $ret = $dbh->func($lobjId, 'lo_unlink');

Deletes an existing large object. Returns true upon success and false upon failure.

lo_import
  $lobjId = $dbh->func($filename, 'lo_import');

Imports a Unix file as large object and returns the object id of the new object or undef upon failure.

lo_export
  $ret = $dbh->func($lobjId, $filename, 'lo_export');

Exports a large object into a Unix file. Returns false upon failure, true otherwise.

pg_notifies
  $ret = $dbh->func('pg_notifies');

Returns either undef or a reference to two-element array [ $table, $backend_pid ] of asynchronous notifications received.

getfd
  $fd = $dbh->func('getfd');

Returns fd of the actual connection to server. Can be used with select() and func('pg_notifies'). Deprecated in favor of $dbh->{pg_socket}.

ATTRIBUTES COMMON TO ALL HANDLES

Warn (boolean, inherited)

Implemented by DBI, no driver-specific impact.

Active (boolean, read-only)

Supported by this driver as proposed by DBI. A database handle is active while it is connected and statement handle is active until it is finished.

Kids (integer, read-only)

Implemented by DBI, no driver-specific impact.

ActiveKids (integer, read-only)

Implemented by DBI, no driver-specific impact.

CachedKids (hash ref)

Implemented by DBI, no driver-specific impact.

CompatMode (boolean, inherited)

Not used by this driver.

InactiveDestroy (boolean)

Implemented by DBI, no driver-specific impact.

PrintError (boolean, inherited)

Implemented by DBI, no driver-specific impact.

RaiseError (boolean, inherited)

Implemented by DBI, no driver-specific impact.

HandleError (boolean, inherited)

Implemented by DBI, no driver-specific impact.

ChopBlanks (boolean, inherited)

Supported by this driver as proposed by DBI. This method is similar to the SQL function RTRIM.

LongReadLen (integer, inherited)

Implemented by DBI, not used by this driver.

LongTruncOk (boolean, inherited)

Implemented by DBI, not used by this driver.

Taint (boolean, inherited)

Implemented by DBI, no driver-specific impact.

DBI DATABASE HANDLE OBJECTS

Database Handle Methods

selectrow_array
  @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);

Implemented by DBI, no driver-specific impact.

selectrow_arrayref
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);

Implemented by DBI, no driver-specific impact.

selectrow_hashref
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values);

Implemented by DBI, no driver-specific impact.

selectall_arrayref
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);

Implemented by DBI, no driver-specific impact.

selectall_hashref
  $hash_ref = $dbh->selectall_hashref($statement, $key_field);

Implemented by DBI, no driver-specific impact.

selectcol_arrayref
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);

Implemented by DBI, no driver-specific impact.

prepare
  $sth = $dbh->prepare($statement, \%attr);

WARNING: DBD::Pg now uses true prepared statements by sending them to the backend to be prepared by the PostgreSQL server. Statements that were legal before may no longer work. See below for details.

Prepares a statement for later execution. PostgreSQL supports prepared statements, which enables DBD::Pg to only send the query once, and simply send the arguments for every subsequent call to execute(). DBD::Pg can use these server-side prepared statements, or it can just send the entire query to the server each time. The best way is automatically chosen for each query. This will be sufficient for most users: keep reading for a more detailed explanation and some optional flags.

Statements that do not begin with the word "SELECT", "INSERT", "UPDATE", or "DELETE" will not be sent to be server-side prepared.

Deciding whether or not to use prepared statements depends on many factors, but you can force them to be used or not used by passing the pg_server_prepare attribute to prepare(). A "0" means to never use prepared statements. This is the default when connected to servers earlier than version 7.4, which is when prepared statements were introduced. Setting pg_server_prepare to "1" means that prepared statements should be used whenever possible. This is the default for servers version 8.0 or higher. Servers that are version 7.4 get a special default value of "2", because server-side statements were only partially supported in that version. In this case, it only uses server-side prepares if all parameters are specifically bound.

The pg_server_prepare attribute can also be set at connection time like so:

  $dbh = DBI->connect($DBNAME, $DBUSER, $DBPASS,
                      { AutoCommit => 0,
                        RaiseError => 1,
                        pg_server_prepare => 0 });

or you may set it after your database handle is created:

  $dbh->{pg_server_prepare} = 1;

To enable it for just one particular statement:

  $sth = $dbh->prepare("SELECT id FROM mytable WHERE val = ?",
                       { pg_server_prepare => 1 });

You can even toggle between the two as you go:

  $sth->{pg_server_prepare} = 1;
  $sth->execute(22);
  $sth->{pg_server_prepare} = 0;
  $sth->execute(44);
  $sth->{pg_server_prepare} = 1;
  $sth->execute(66);

In the above example, the first execute will use the previously prepared statement. The second execute will not, but will build the query into a single string and send it to the server. The third one will act like the first and only send the arguments. Even if you toggle back and forth, a statement is only prepared once.

Using prepared statements is in theory quite a bit faster: not only does the PostgreSQL backend only have to prepare the query only once, but DBD::Pg no longer has to worry about quoting each value before sending it to the server.

However, there are some drawbacks. The server cannot always choose the ideal parse plan because it will not know the arguments before hand. But for most situations in which you will be executing similar data many times, the default plan will probably work out well. Further discussion on this subject is beyond the scope of this documentation: please consult the pgsql-performance mailing list, http://archives.postgresql.org/pgsql-performance/

Only certain commands will be sent to a server-side prepare: currently these include SELECT, INSERT, UPDATE, and DELETE. DBD::Pg uses a simple naming scheme for the prepared statements: dbdpg_#, where "#" starts at 1 and increases. This number is tracked at the database handle level, so multiple statement handles will not collide. If you use your own prepare statements, do not name them "dbdpg_"!

The actual PREPARE is not performed until the first execute is called, due to the fact that information on the data types (provided by bind_param) may be given after the prepare but before the execute.

A server-side prepare can also happen before the first execute. If the server can handle the server-side prepare and the statement has no placeholders, it will be prepared right away. It will also be prepared if the pg_prepare_now attribute is passed. Similarly, the <pg_prepare_now> attribute can be set to 0 to ensure that the statement is not prepared immediately, although cases in which you would want this may be rare. Finally, you can set the default behavior of all prepare statements by setting the pg_prepare_now attribute on the database handle:

  $dbh->{pg_prepare_now} = 1;

The following two examples will be prepared right away:

  $sth->prepare("SELECT 123"); ## no placeholders

  $sth->prepare("SELECT 123, ?", {pg_prepare_now = 1});

The following two examples will NOT be prepared right away:

  $sth->prepare("SELECT 123, ?"); ## has a placeholder

  $sth->prepare("SELECT 123", {pg_prepare_now = 0});

There are times when you may want to prepare a statement yourself. To do this, simply send the PREPARE statement directly to the server (e.g. with "do"). Create a statement handle and set the prepared name via pg_prepare_name attribute. The statement handle can be created with a dummy statement, as it will not be executed. However, it should have the same number of placeholders as your prepared statement. Example:

  $dbh->do("PREPARE mystat AS SELECT COUNT(*) FROM pg_class WHERE reltuples < ?");
  $sth = $dbh->prepare("SELECT ?");
  $sth->bind_param(1, 1, SQL_INTEGER);
  $sth->{pg_prepare_name} = "mystat";
  $sth->execute(123);

The above will run this query:

  SELECT COUNT(*) FROM pg_class WHERE reltuples < 123;

Note: DBD::Pg will not escape your custom prepared statement name, so don't use a name that needs escaping! DBD::Pg uses the prepare names dbdpg_# internally, so please do not use those either.

You can force DBD::Pg to send your query directly to the server by adding the pg_direct attribute to your prepare call. This is not recommended, but is added just in case you need it.

Placeholders

There are three types of placeholders that can be used in DBD::Pg. The first is the question mark method, in which each placeholder is represented by a single question mark. This is the method recommended by the DBI specs and is the most portable. Each question mark is replaced by a "dollar sign number" in the order in which they appear in the query (important when using bind_param).

The second method is to use "dollar sign numbers" directly. This is the method that PostgreSQL uses internally and is overall probably the best method to use if you do not need compatibility with other database systems. DBD::Pg, like PostgreSQL, allows the same number to be used more than once in the query. Numbers must start with "1" and increment by one value. If the same number appears more than once in a query, it is treated as a single parameter and all instances are replaced at once. Examples:

Not legal:

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages > $2";

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages BETWEEN $1 AND $3";

Legal:

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages > $1";

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages BETWEEN $1 AND $2";

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages BETWEEN $1 AND $2 AND reltuples > $1";

  $SQL = "SELECT count(*) FROM pg_class WHERE relpages > $1 AND reltuples > $1";

In the final statement above, DBI thinks there is only one placeholder, so this statement will replace both placeholders:

  $sth->bind_param(1, 2045);

While execute requires only a single argument as well:

  $sth->execute(2045);

The final placeholder method is the named parameters in the format ":foo". While this syntax is supported by DBD::Pg, its use is highly discouraged.

The different types of placeholders cannot be mixed within a statement, but you may use different ones for each statement handle you have. Again, this is not encouraged.

prepare_cached
  $sth = $dbh->prepare_cached($statement, \%attr);

Implemented by DBI, no driver-specific impact. This method is most useful when using a server that supports server-side prepares, and you have asked the prepare to happen immediately via the pg_prepare_now attribute.

do
  $rv  = $dbh->do($statement, \%attr, @bind_values);

Prepare and execute a single statement. Note that an empty statement (string with no length) will not be passed to the server; if you want a simple test, use "SELECT 123" or the ping() function. If neither attr nor bind_values is given, the query will be sent directly to the server without the overhead of creating a statement handle and running prepare and execute.

last_insert_id
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field);
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr);

Attempts to return the id of the last value to be inserted into a table. You can either provide a sequence name (preferred) or provide a table name with optional schema. The $catalog and $field arguments are always ignored. The current value of the sequence is returned by a call to the CURRVAL() PostgreSQL function. This will fail if the sequence has not yet been used in the current database connection.

If you do not know the name of the sequence, you can provide a table name and DBD::Pg will attempt to return the correct value. To do this, there must be at least one column in the table with a NOT NULL constraint, that has a unique constraint, and which uses a sequence as a default value. If more than one column meets these conditions, the primary key will be used. This involves some looking up of things in the system table, so DBD::Pg will cache the sequence name for susequent calls. If you need to disable this caching for some reason, you can control it via the pg_cache attribute.

Please keep in mind that this method is far from foolproof, so make your script use it properly. Specifically, make sure that it is called immediately after the insert, and that the insert does not add a value to the column that is using the sequence as a default value.

Some examples:

  $dbh->do("CREATE SEQUENCE lii_seq START 1");
  $dbh->do("CREATE TABLE lii (
    foobar INTEGER NOT NULL UNIQUE DEFAULT nextval('lii_seq'),
    baz VARCHAR)");
  $SQL = "INSERT INTO lii(baz) VALUES (?)";
  $sth = $dbh->prepare($SQL);
  for (qw(uno dos tres cuatro)) {
    $sth->execute($_);
    my $newid = $dbh->last_insert_id(C<undef>,undef,undef,undef,{sequence=>'lii_seq'});
    print "Last insert id was $newid\n";
  }

If you did not want to worry about the sequence name:

  $dbh->do("CREATE TABLE lii2 (
    foobar SERIAL UNIQUE,
    baz VARCHAR)");
  $SQL = "INSERT INTO lii2(baz) VALUES (?)";
  $sth = $dbh->prepare($SQL);
  for (qw(uno dos tres cuatro)) {
    $sth->execute($_);
    my $newid = $dbh->last_insert_id(undef,undef,"lii2",undef);
    print "Last insert id was $newid\n";
  }
commit
  $rc  = $dbh->commit;

Supported by this driver as proposed by DBI. See also the notes about Transactions elsewhere in this document.

rollback
  $rc  = $dbh->rollback;

Supported by this driver as proposed by DBI. See also the notes about Transactions elsewhere in this document.

disconnect
  $rc  = $dbh->disconnect;

Supported by this driver as proposed by DBI.

ping
  $rc = $dbh->ping;

This driver supports the ping method, which can be used to check the validity of a database handle. The value returned is either 0, indicating that the connection is no longer valid, or a positive integer, indicating the following:

  Value    Meaning
  --------------------------------------------------
    1      Database is idle (not in a transaction)
    2      Database is active, there is a command in progress (usually seen after a COPY command)
    3      Database is idle within a transaction
    4      Database is idle, within a failed transaction

Additional information on why a handle is not valid can be obtained by using the pg_ping method.

pg_ping
  $rc = $dbh->pg_ping;

This is a Postgres-specific extension to the ping command. This will check the validity of a database handle in exactly the same way as ping, but instead of returning a 0 for an invalid connection, it will return a negative number. The positive numbers are documented at ping, the negative ones indicate:

  Value    Meaning
  --------------------------------------------------
   -1      There is no connection to the database at all (e.g. after C<disconnect>)
   -2      An unknown transaction status was returned (e.g. after forking)
   -3      The handle exists, but no data was returned from a test query.

In practice, you should only ever see -1 and -2.

column_info
  $sth = $dbh->column_info( $catalog, $schema, $table, $column );

Supported by this driver as proposed by DBI with the follow exceptions. These fields are currently always returned with NULL (undef) values:

   TABLE_CAT
   BUFFER_LENGTH
   DECIMAL_DIGITS
   NUM_PREC_RADIX
   SQL_DATA_TYPE
   SQL_DATETIME_SUB
   CHAR_OCTET_LENGTH

Also, two additional non-standard fields are returned:

  pg_type - data type with additional info i.e. "character varying(20)"
  pg_constraint - holds column constraint definition

The REMARKS field will be returned as NULL (undef for PostgreSQL versions older than 7.2. The TABLE_SCHEM field will be returned as NULL (undef) for versions older than 7.4.

table_info
  $sth = $dbh->table_info( $catalog, $schema, $table, $type );

Supported by this driver as proposed by DBI. This method returns all tables and views visible to the current user. The $catalog argument is currently unused. The schema and table arguments will do a LIKE search if a percent sign (%) or an underscore (_) is detected in the argument. The $type argument accepts a value of either "TABLE" or "VIEW" (using both is the default action).

The TABLE_CAT field will always return NULL (undef). The TABLE_SCHEM field returns NULL (undef) if the server is older than version 7.4.

If your database supports tablespaces (version 8.0 or greater), two additional columns are returned, "pg_tablespace_name" and "pg_tablespace_location", that contain the name and location of the tablespace associated with this table. Tables that have not been assigned to a particular tablespace will return NULL (undef) for both of these columns.

primary_key_info
  $sth = $dbh->primary_key_info( $catalog, $schema, $table, \%attr );

Supported by this driver as proposed by DBI. The $catalog argument is currently unused, and the $schema argument has no effect against servers running version 7.2 or older. There are no search patterns allowed, but leaving the $schema argument blank will cause the first table found in the schema search path to be used. An additional field, "DATA_TYPE", is returned and shows the data type for each of the arguments in the "COLUMN_NAME" field.

This method will also return tablespace information for servers that support tablespaces. See the table_info entry for more information.

In addition to the standard format of returning one row for each column found for the primary key, you can pass the pg_onerow attribute to force a single row to be used. If the primary key has multiple columns, the "KEY_SEQ", "COLUMN_NAME", and "DATA_TYPE" fields will return a comma-delimited string. If the pg_onerow attribute is set to "2", the fields will be returned as an arrayref, which can be useful when multiple columns are involved:

  $sth = $dbh->primary_key_info('', '', 'dbd_pg_test', {pg_onerow => 2});
  if (defined $sth) {
    my $pk = $sth->fetchall_arrayref()->[0];
    print "Table $pk->[2] has a primary key on these columns:\n";
    for (my $x=0; defined $pk->[3][$x]; $x++) {
      print "Column: $pk->[3][$x]  (data type: $pk->[6][$x])\n";
    }
  }
primary_key

Supported by this driver as proposed by DBI.

foreign_key_info
  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table,
                                 $fk_catalog, $fk_schema, $fk_table );

Supported by this driver as proposed by DBI, using the SQL/CLI variant. This function returns undef for PostgreSQL servers earlier than version 7.3. There are no search patterns allowed, but leaving the $schema argument blank will cause the first table found in the schema search path to be used. Two additional fields, "UK_DATA_TYPE" and "FK_DATA_TYPE", are returned to show the data type for the unique and foreign key columns. Foreign keys that have no named constraint (where the referenced column only has an unique index) will return undef for the "UK_NAME" field.

tables
  @names = $dbh->tables( $catalog, $schema, $table, $type, \%attr );

Supported by this driver as proposed by DBI. This method returns all tables and/or views which are visible to the current user: see table_info() for more information about the arguments. If the database is version 7.3 or later, the name of the schema appears before the table or view name. This can be turned off by adding in the pg_noprefix attribute:

  my @tables = $dbh->tables( '', '', 'dbd_pg_test', '', {pg_noprefix => 1} );
type_info_all
  $type_info_all = $dbh->type_info_all;

Supported by this driver as proposed by DBI. Information is only provided for SQL datatypes and for frequently used datatypes. The mapping between the PostgreSQL typename and the SQL92 datatype (if possible) has been done according to the following table:

  +---------------+------------------------------------+
  | typname       | SQL92                              |
  |---------------+------------------------------------|
  | bool          | BOOL                               |
  | text          | /                                  |
  | bpchar        | CHAR(n)                            |
  | varchar       | VARCHAR(n)                         |
  | int2          | SMALLINT                           |
  | int4          | INT                                |
  | int8          | /                                  |
  | money         | /                                  |
  | float4        | FLOAT(p)   p<7=float4, p<16=float8 |
  | float8        | REAL                               |
  | abstime       | /                                  |
  | reltime       | /                                  |
  | tinterval     | /                                  |
  | date          | /                                  |
  | time          | /                                  |
  | datetime      | /                                  |
  | timespan      | TINTERVAL                          |
  | timestamp     | TIMESTAMP                          |
  +---------------+------------------------------------+

For further details concerning the PostgreSQL specific datatypes please read pgbuiltin.

type_info
  @type_info = $dbh->type_info($data_type);

Implemented by DBI, no driver-specific impact.

quote
  $sql = $dbh->quote($value, $data_type);

This module implements its own quote method. In addition to the DBI method it also doubles the backslash, because PostgreSQL treats a backslash as an escape character.

NOTE: The undocumented (and invalid) support for the SQL_BINARY data type is officially deprecated. Use PG_BYTEA with bind_param() instead:

  $rv = $sth->bind_param($param_num, $bind_value,
                         { pg_type => DBD::Pg::PG_BYTEA });
pg_server_trace
  $dbh->pg_server_trace($filehandle);

Writes debugging information from the PostgreSQL backend to a file. This is not the same as the trace() method and you should not use this method unless you know what you are doing. If you do enable this, be aware that the file will grow very large, very quick. To stop logging to the file, use the pg_server_untrace function. The first argument must be a file handle, not a filename. Example:

  my $pid = $dbh->{pg_pid};
  my $file = "pgbackend.$pid.debug.log";
  open(my $fh, ">$file") or die qq{Could not open "$file": $!\n};
  $dbh->pg_server_trace($fh);
  ## Run code you want to trace here
  $dbh->pg_server_untrace;
  close($fh);
pg_server_untrace
  $dbh->pg_server_untrace

Stop server logging to a previously opened file.

Database Handle Attributes

AutoCommit (boolean)

Supported by this driver as proposed by DBI. According to the classification of DBI, PostgreSQL is a database in which a transaction must be explicitly started. Without starting a transaction, every change to the database becomes immediately permanent. The default of AutoCommit is on, but this may change in the future, so it is highly recommended that you explicitly set it when calling connect(). For details see the notes about Transactions elsewhere in this document.

pg_bool_tf (boolean)

PostgreSQL specific attribute. If true, boolean values will be returned as the characters 't' and 'f' instead of '1' and '0'.

Driver (handle)

Implemented by DBI, no driver-specific impact.

Name (string, read-only)

The default DBI method is overridden by a driver specific method that returns only the database name. Anything else from the connection string is stripped off. Note that, in contrast to the DBI specs, the DBD::Pg implementation fo this method is read-only.

RowCacheSize (integer)

Implemented by DBI, not used by this driver.

pg_auto_escape (boolean)

PostgreSQL specific attribute. If true, then quotes and backslashes in all parameters will be escaped in the following way:

  escape quote with a quote (SQL)
  escape backslash with a backslash

The default is on. Note that PostgreSQL also accepts quotes that are escaped by a backslash. Any other ASCII character can be used directly in a string constant.

pg_enable_utf8 (boolean)

PostgreSQL specific attribute. If true, then the utf8 flag will be turned for returned character data (if the data is valid UTF-8). For details about the utf8 flag, see Encode. This attribute only relevant under perl 5.8 and later.

NB: This attribute is experimental and may be subject to change.

pg_INV_READ (integer, read-only)

Constant to be used for the mode in lo_creat and lo_open.

pg_INV_WRITE (integer, read-only)

Constant to be used for the mode in lo_creat and lo_open.

pg_errorlevel (integer)

PostgreSQL specific attribute, only works for servers version 7.4 and above. Sets the amount of information returned by the server's error messages. Valid entries are 0, 1, and 2. Any other number will be forced to the default value of 1.

A value of 0 ("TERSE") will show severity, primary text, and position only and will usually fit on a single line. A value of 1 ("DEFAULT") will also show any detail, hint, or context fields. A value of 2 ("VERBOSE") will show all available information.

pg_protocol (integer, read-only)

PostgreSQL specific attribute. Returns the version of the PostgreSQL server. If DBD::Pg is unable to figure out the version (e.g. it was compiled against pre 7.4 libraries), it will return a "0". Otherwise, servers below version 7.4 return a "2", and (currently) 7.4 and above return a "3".

pg_lib_version (integer, read-only)

PostgreSQL specific attribute. Indicates which version of PostgreSQL that DBD::Pg was compiled against. In other words, which libraries were used. Returns a number with major, minor, and revision together; version 7.4.2 would be returned as 70402.

pg_server_version (integer, read-only)

PostgreSQL specific attribute. Indicates which version of PostgreSQL that the current database handle is connected to. Returns a number with major, minor, and revision together; version 8.0.1 would be 80001.

pg_db (string, read-only)

PostgreSQL specific attribute. Returns the name of the current database.

pg_user (string, read-only)

PostgreSQL specific attribute. Returns the name of the user that connected to the server.

pg_pass (string, read-only)

PostgreSQL specific attribute. Returns the password used to connect to the server.

pg_host (string, read-only)

PostgreSQL specific attribute. Returns the host of the current server connection. Locally connected hosts will return an empty string.

pg_port (integer, read-only)

PostgreSQL specific attribute. Returns the port of the connection to the server.

pg_default_port (integer, read-only)

PostgreSQL specific attribute. Returns the default port used if none is specifically givem.

pg_options (string, read-only)

PostgreSQL specific attribute. Returns the command-line options passed to the server. May be an empty string.

pg_socket (number, read-only)

PostgreSQL specific attribute. Returns the file description number of the connection socket to the server.

pg_pid (number, read-only)

PostgreSQL specific attribute. Returns the process id (PID) of the backend server process handling the connection.

DBI STATEMENT HANDLE OBJECTS

Statement Handle Methods

bind_param
  $rv = $sth->bind_param($param_num, $bind_value, \%attr);

Allows the user to bind a value and/or a data type to a placeholder. This is especially important when using the new server-side prepare system with PostgreSQL 7.4. See the prepare() method for more information.

The value of $param_num is a number if using the '?' or '$1' style placeholders. If using ":foo" style placeholders, the complete name (e.g. ":foo") must be given. For numeric values, you can either use a number or use a literal '$1'. See the examples below.

The $bind_value argument is fairly self-explanatory. A value of undef will bind a NULL to the placeholder. Using undef is useful when you want to change just the type and will be overwriting the value later. (Any value is actually usable, but undef is easy and efficient).

The %attr hash is used to indicate the data type of the placeholder. The default value is "varchar". If you need something else, you must use one of the values provided by DBI or by DBD::Pg. To use a SQL value, modify your "use DBI" statement at the top of your script as follows:

  use DBI qw(:sql_types);

This will import some constants into your script. You can plug those directly into the bind_param call. Some common ones that you will encounter are:

  SQL_INTEGER

To use PostgreSQL data types, import the list of values like this:

  use DBD::Pg qw(:pg_types);

You can then set the data types by setting the value of the pg_type key in the hash passed to bind_param.

Data types are "sticky," in that once a data type is set to a certain placeholder, it will remain for that placeholder, unless it is explicitly set to something else afterwards. If the statement has already been prepared, and you switch the data type to something else, DBD::Pg will re-prepare the statement for you before doing the next execute.

Examples:

  use DBI qw(:sql_types);
  use DBD::Pg qw(:pg_types);

  $SQL = "SELECT id FROM ptable WHERE size > ? AND title = ?";
  $sth = $dbh->prepare($SQL);

  ## Both arguments below are bound to placeholders as "varchar"
  $sth->execute(123, "Merk");

  ## Reset the datatype for the first placeholder to an integer
  $sth->bind_param(1, undef, SQL_INTEGER);

  ## The "undef" bound above is not used, since we supply params to execute
  $sth->execute(123, "Merk");

  ## Set the first placeholder's value and data type
  $sth->bind_param(1, 234, { pg_type => PG_TIMESTAMP });

  ## Set the second placeholder's value and data type.
  ## We don't send a third argument, so the default "varchar" is used
  $sth->bind_param("$2", "Zool");

  ## We realize that the wrong data type was set above, so we change it:
  $sth->bind_param("$1", 234, { pg_type => PG_INTEGER });

  ## We also got the wrong value, so we change that as well.
  ## Because the data type is sticky, we don't need to change it
  $sth->bind_param(1, 567);

  ## This executes the statement with 567 (integer) and "Zool" (varchar)
  $sth->execute();
bind_param_inout

Currently not supported by this driver.

execute
  $rv = $sth->execute(@bind_values);

Executes a previously prepared statement. In addition to UPDATE, DELETE, INSERT statements, for which it returns always the number of affected rows, the execute method can also be used for SELECT ... INTO table statements.

The "prepare/bind/execute" process has changed significantly for PostgreSQL servers 7.4 and later: please see the prepare() and bind_param() entries for much more information.

Setting one of the bind_values to "undef" is the equivalent of setting the value to NULL in the database. Setting the bind_value to $DBDPG_DEFAULT is equivalent to sending the literal string 'DEFAULT' to the backend. Note that using this option will force server-side prepares off until such time as PostgreSQL supports using DEFAULT in prepared statements.

fetchrow_arrayref
  $ary_ref = $sth->fetchrow_arrayref;

Supported by this driver as proposed by DBI.

fetchrow_array
  @ary = $sth->fetchrow_array;

Supported by this driver as proposed by DBI.

fetchrow_hashref
  $hash_ref = $sth->fetchrow_hashref;

Supported by this driver as proposed by DBI.

fetchall_arrayref
  $tbl_ary_ref = $sth->fetchall_arrayref;

Implemented by DBI, no driver-specific impact.

finish
  $rc = $sth->finish;

Supported by this driver as proposed by DBI.

rows
  $rv = $sth->rows;

Supported by this driver as proposed by DBI. In contrast to many other drivers the number of rows is available immediately after executing the statement.

bind_col
  $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr);

Supported by this driver as proposed by DBI.

bind_columns
  $rc = $sth->bind_columns(\%attr, @list_of_refs_to_vars_to_bind);

Supported by this driver as proposed by DBI.

dump_results
  $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);

Implemented by DBI, no driver-specific impact.

blob_read
  $blob = $sth->blob_read($id, $offset, $len);

Supported by this driver as proposed by DBI. Implemented by DBI but not documented, so this method might change.

This method seems to be heavily influenced by the current implementation of blobs in Oracle. Nevertheless we try to be as compatible as possible. Whereas Oracle suffers from the limitation that blobs are related to tables and every table can have only one blob (datatype LONG), PostgreSQL handles its blobs independent of any table by using so-called object identifiers. This explains why the blob_read method is blessed into the STATEMENT package and not part of the DATABASE package. Here the field parameter has been used to handle this object identifier. The offset and len parameters may be set to zero, in which case the driver fetches the whole blob at once.

Starting with PostgreSQL 6.5, every access to a blob has to be put into a transaction. This holds even for a read-only access.

See also the PostgreSQL-specific functions concerning blobs, which are available via the func interface.

For further information and examples about blobs, please read the chapter about Large Objects in the PostgreSQL Programmer's Guide at http://www.postgresql.org/docs/current/static/largeobjects.html.

Statement Handle Attributes

NUM_OF_FIELDS (integer, read-only)

Implemented by DBI, no driver-specific impact.

NUM_OF_PARAMS (integer, read-only)

Implemented by DBI, no driver-specific impact.

NAME (array-ref, read-only)

Supported by this driver as proposed by DBI.

NAME_lc (array-ref, read-only)

Implemented by DBI, no driver-specific impact.

NAME_uc (array-ref, read-only)

Implemented by DBI, no driver-specific impact.

NAME_hash (hash-ref, read-only)

Implemented by DBI, no driver-specific impact.

NAME_lc_hash (hash-ref, read-only)

Implemented by DBI, no driver-specific impact.

NAME_uc_hash (hash-ref, read-only)

Implemented by DBI, no driver-specific impact.

TYPE (array-ref, read-only)

Supported by this driver as proposed by DBI

PRECISION (array-ref, read-only)

Supported by this driver. NUMERIC types will return the precision. Types of CHAR and VARCHAR will return their size (number of characters). Other types will return the number of bytes.

SCALE (array-ref, read-only)

Supported by this driver as proposed by DBI. The only type that will return a value currently is NUMERIC.

NULLABLE (array-ref, read-only)

Supported by this driver as proposed by DBI. This is only available for servers version 7.3 and later. Others will return "2" for all columns.

CursorName (string, read-only)

Not supported by this driver. See the note about Cursors elsewhere in this document.

Database (dbh, read-only)

Implemented by DBI, no driver-specific impact.

ParamValues (hash ref, read-only)

Supported by this driver as proposed by DBI. If called before execute, the literal values passed in are returned. If called after execute, then the quoted versions of the values are shown.

Statement (string, read-only)

Supported by this driver as proposed by DBI.

RowCache (integer, read-only)

Not supported by this driver.

pg_size (array-ref, read-only)

PostgreSQL specific attribute. It returns a reference to an array of integer values for each column. The integer shows the size of the column in bytes. Variable length columns are indicated by -1.

pg_type (array-ref, read-only)

PostgreSQL specific attribute. It returns a reference to an array of strings for each column. The string shows the name of the data_type.

pg_oid_status (integer, read-only)

PostgreSQL specific attribute. It returns the OID of the last INSERT command.

pg_cmd_status (integer, read-only)

PostgreSQL specific attribute. It returns the type of the last command. Possible types are: "INSERT", "DELETE", "UPDATE", "SELECT".

FURTHER INFORMATION

Transactions

Transaction behavior is controlled via the AutoCommit attribute. For a complete definition of AutoCommit please refer to the DBI documentation.

According to the DBI specification the default for AutoCommit is a true value. In this mode, any change to the database becomes valid immediately. Any BEGIN, COMMIT or ROLLBACK statements will be rejected. DBD::Pg implements AutoCommit by issuing a BEGIN statement immediately before executing a statement, and a COMMIT afterwards.

Savepoints

PostgreSQL version 8.0 introduced the concept of savepoints, which allows transactions to be rolled back to a certain point without affecting the rest of the transaction. DBD::Pg encourages using the following methods to control savepoints:

pg_savepoint

Creates a savepoint. This will fail unless you are inside of a transaction. The only argument is the name of the savepoint. Note that PostgreSQL DOES allow multiple savepoints with the same name to exist.

  $dbh->pg_savepoint("mysavepoint");
pg_rollback_to

Rolls the database back to a named savepoint, discarding any work performed after that point. If more than one savepoint with that name exists, rolls back to the most recently created one.

  $dbh->pg_rollback_to("mysavepoint");
pg_release

Releases (or removes) a named savepoint. If more than one savepoint with that name exists, it will only destroy the most recently created one. Note that all savepoints created after the one being released are also destroyed.

  $dbh->pg_release("mysavepoint");

COPY support

DBD::Pg supports the COPY command through three functions: pg_putline, pg_getline, and pg_endcopy. The COPY command allows data to be quickly loaded or read from a table. The basic process is to issue a COPY command via $dbh->do(), do either $dbh->pg_putline or $dbh->pg_getline, and then issue a $dbh->pg_endcopy (for pg_putline only).

The first step is to put the server into "COPY" mode. This is done by sending a complete COPY command to the server, by using the do() method. For example:

  $dbh->do("COPY foobar FROM STDIN");

This would tell the server to enter a COPY IN state. It is now ready to receive information via the pg_putline method. The complete syntax of the COPY command is more complex and not documented here: the canonical PostgreSQL documentation for COPY be found at:

http://www.postgresql.org/docs/current/static/sql-copy.html

Note that 7.2 servers can only accept a small subset of later features in the COPY command: most notably they do not accept column specifications.

Once the COPY command has been issued, no other SQL commands are allowed until after pg_endcopy has been successfully called. If in a COPY IN state, you cannot use pg_getline, and if in COPY OUT state, you cannot use pg_putline.

pg_putline

Used to put data into a table after the server has been put into COPY IN mode by calling "COPY tablename FROM STDIN". The only argument is the data you want inserted. The default delimiter is a tab character, but this can be changed in the COPY statement. Returns a 1 on sucessful input. Examples:

  $dbh->do("COPY mytable FROM STDIN");
  $dbh->pg_putline("123\tPepperoni\t3\n");
  $dbh->pg_putline("314\tMushroom\t8\n");
  $dbh->pg_putline("6\tAnchovies\t100\n");
  $dbh->pg_endcopy;

  ## This example uses explicit columns and a custom delimiter
  $dbh->do("COPY mytable(flavor, slices) FROM STDIN WITH DELIMITER '~'");
  $dbh->pg_putline("Pepperoni~123\n");
  $dbh->pg_putline("Mushroom~314\n");
  $dbh->pg_putline("Anchovies~6\n");
  $dbh->pg_endcopy;
pg_getline

Used to retrieve data from a table after the server has been put into COPY OUT mode by calling "COPY tablename TO STDOUT". The first argument to pg_getline is the variable into which the data will be stored. The second argument is the size of the variable: this should be greater than the expected size of the row. Returns a 1 on success, and an empty string when the last row has been fetched. Example:

  $dbh->do("COPY mytable TO STDOUT");
  my @data;
  my $x=0;
  1 while($dbh->pg_getline($data[$x++], 100));
  pop @data; ## Remove final "\\.\n" line

If DBD::Pg is compiled with pre-7.4 libraries, this function will not work: you will have to use the old $dbh->func($data, 100, 'getline') command, and call pg_getline manually. Users are highly encouraged to upgrade to a newer version of PostgreSQL if this is the case.

pg_endcopy

When done with pg_putline, call pg_endcopy to put the server back in a normal state. Returns a 1 on success. This method will fail if called when not in a COPY IN or COPY OUT state. Note that you no longer need to send "\\.\n" when in COPY IN mode: pg_endcopy will do this for you automatically as needed. pg_endcopy is only needed after getline if you are using the old-style method, $dbh->func($data, 100, 'getline').

Large Objects

This driver supports all largeobject functions provided by libpq via the func method. Please note that, starting with PostgreSQL 6.5, any access to a large object -- even read-only large objects -- must be put into a transaction!

Cursors

Although PostgreSQL has a cursor concept, it has not been used in the current implementation. Cursors in PostgreSQL can only be used inside a transaction block. Because only one transaction block at a time is allowed, this would have implied the restriction not to use any nested SELECT statements. Hence the execute method fetches all data at once into data structures located in the front-end application. This approach must to be considered when selecting large amounts of data!

Datatype bool

The current implementation of PostgreSQL returns 't' for true and 'f' for false. From the Perl point of view, this is a rather unfortunate choice. DBD::Pg therefore translates the result for the BOOL data type in a Perlish manner: 'f' -> '0' and 't' -> '1'. This way the application does not have to check the database-specific returned values for the data-type BOOL because Perl treats '0' as false and '1' as true. You may set the pg_bool_tf attribute to a true value to change the values back to 't' and 'f' if you wish.

Boolean values can be passed to PostgreSQL as TRUE, 't', 'true', 'y', 'yes' or '1' for true and FALSE, 'f', 'false', 'n', 'no' or '0' for false.

Schema support

PostgreSQL version 7.3 introduced schema support. Note that the PostgreSQL schema concept may differ from those of other databases. In a nutshell, a schema is a named collection of objects within a single database. Please refer to the PostgreSQL documentation for more details.

Currently, DBD::Pg does not provide explicit support for PostgreSQL schemas. However, schema functionality may be used without any restrictions by explicitly addressing schema objects, e.g.

  my $res = $dbh->selectall_arrayref("SELECT * FROM my_schema.my_table");

or by manipulating the schema search path with SET search_path, e.g.

  $dbh->do("SET search_path TO my_schema, public");

SEE ALSO

the DBI manpage

AUTHORS

DBI and DBD-Oracle by Tim Bunce (Tim.Bunce@ig.co.uk)

DBD-Pg by Edmund Mergl (E.Mergl@bawue.de) and Jeffrey W. Baker (jwbaker@acm.org) By David Wheeler <david@justatheory.com>, Jason Stewart <jason@openinformatics.com>, Bruce Momjian <pgman@candle.pha.pa.us>, Greg Sabino Mullane <greg@turnstep.com>, and others after v1.13.

Parts of this package have been copied from DBI and DBD-Oracle.

Mailing List

The current maintainers may be reached through the 'dbdpg-general' mailing list: http://gborg.postgresql.org/mailman/listinfo/dbdpg-general/.

This list is available through Gmane (http://www.gmane.org/) as a newsgroup with the name: gmane.comp.db.postgresql.dbdpg

Bug Reports

If you feel certain you have found a bug, you can report it by sending an email to <bug-dbd-pg@rt.cpan.org>.

COPYRIGHT

The DBD::Pg module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

ACKNOWLEDGMENTS

See also DBI/ACKNOWLEDGMENTS.


DBD::Proxy - A proxy driver for the DBI

  • CONNECTING TO THE DATABASE
  • KNOWN ISSUES
    • Unproxied method calls
    • Complex handle attributes
  • AUTHOR AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Proxy - A proxy driver for the DBI

SYNOPSIS

  use DBI;

  $dbh = DBI->connect("dbi:Proxy:hostname=$host;port=$port;dsn=$db",
                      $user, $passwd);

  # See the DBI module documentation for full details

DESCRIPTION

DBD::Proxy is a Perl module for connecting to a database via a remote DBI driver.

This is of course not needed for DBI drivers which already support connecting to a remote database, but there are engines which don't offer network connectivity.

Another application is offering database access through a firewall, as the driver offers query based restrictions. For example you can restrict queries to exactly those that are used in a given CGI application.

Speaking of CGI, another application is (or rather, will be) to reduce the database connect/disconnect overhead from CGI scripts by using proxying the connect_cached method. The proxy server will hold the database connections open in a cache. The CGI script then trades the database connect/disconnect overhead for the DBD::Proxy connect/disconnect overhead which is typically much less. Note that the connect_cached method is new and still experimental.

CONNECTING TO THE DATABASE

Before connecting to a remote database, you must ensure, that a Proxy server is running on the remote machine. There's no default port, so you have to ask your system administrator for the port number. See the DBI::ProxyServer manpage for details.

Say, your Proxy server is running on machine "alpha", port 3334, and you'd like to connect to an ODBC database called "mydb" as user "joe" with password "hello". When using DBD::ODBC directly, you'd do a

  $dbh = DBI->connect("DBI:ODBC:mydb", "joe", "hello");

With DBD::Proxy this becomes

  $dsn = "DBI:Proxy:hostname=alpha;port=3334;dsn=DBI:ODBC:mydb";
  $dbh = DBI->connect($dsn, "joe", "hello");

You see, this is mainly the same. The DBD::Proxy module will create a connection to the Proxy server on "alpha" which in turn will connect to the ODBC database.

Refer to the the DBI manpage documentation on the connect method for a way to automatically use DBD::Proxy without having to change your code.

DBD::Proxy's DSN string has the format

  $dsn = "DBI:Proxy:key1=val1; ... ;keyN=valN;dsn=valDSN";

In other words, it is a collection of key/value pairs. The following keys are recognized:

hostname
port

Hostname and port of the Proxy server; these keys must be present, no defaults. Example:

    hostname=alpha;port=3334
dsn

The value of this attribute will be used as a dsn name by the Proxy server. Thus it must have the format DBI:driver:..., in particular it will contain colons. The dsn value may contain semicolons, hence this key *must* be the last and it's value will be the complete remaining part of the dsn. Example:

    dsn=DBI:ODBC:mydb
cipher
key
usercipher
userkey

By using these fields you can enable encryption. If you set, for example,

    cipher=$class;key=$key

(note the semicolon) then DBD::Proxy will create a new cipher object by executing

    $cipherRef = $class->new(pack("H*", $key));

and pass this object to the RPC::PlClient module when creating a client. See the RPC::PlClient manpage. Example:

    cipher=IDEA;key=97cd2375efa329aceef2098babdc9721

The usercipher/userkey attributes allow you to use two phase encryption: The cipher/key encryption will be used in the login and authorisation phase. Once the client is authorised, he will change to usercipher/userkey encryption. Thus the cipher/key pair is a host based secret, typically less secure than the usercipher/userkey secret and readable by anyone. The usercipher/userkey secret is your private secret.

Of course encryption requires an appropriately configured server. See <DBD::ProxyServer/CONFIGURATION FILE>.

debug

Turn on debugging mode

stderr

This attribute will set the corresponding attribute of the RPC::PlClient object, thus logging will not use syslog(), but redirected to stderr. This is the default under Windows.

    stderr=1
logfile

Similar to the stderr attribute, but output will be redirected to the given file.

    logfile=/dev/null
RowCacheSize

The DBD::Proxy driver supports this attribute (which is DBI standard, as of DBI 1.02). It's used to reduce network round-trips by fetching multiple rows in one go. The current default value is 20, but this may change.

proxy_no_finish

This attribute can be used to reduce network traffic: If the application is calling $sth->finish() then the proxy tells the server to finish the remote statement handle. Of course this slows down things quite a lot, but is prefectly good for reducing memory usage with persistent connections.

However, if you set the proxy_no_finish attribute to a TRUE value, either in the database handle or in the statement handle, then finish() calls will be supressed. This is what you want, for example, in small and fast CGI applications.

proxy_quote

This attribute can be used to reduce network traffic: By default calls to $dbh->quote() are passed to the remote driver. Of course this slows down things quite a lot, but is the safest default behaviour.

However, if you set the proxy_quote attribute to the value 'local' either in the database handle or in the statement handle, and the call to quote has only one parameter, then the local default DBI quote method will be used (which will be faster but may be wrong).

KNOWN ISSUES

Unproxied method calls

If a method isn't being proxied, try declaring a stub sub in the appropriate package (DBD::Proxy::db for a dbh method, and DBD::Proxy::st for an sth method). For example:

    sub DBD::Proxy::db::selectall_arrayref;

That will enable selectall_arrayref to be proxied.

Currently many methods aren't explicitly proxied and so you get the DBI's default methods executed on the client.

Some of those methods, like selectall_arrayref, may then call other methods that are proxied (selectall_arrayref calls fetchall_arrayref which calls fetch which is proxied). So things may appear to work but operate more slowly than the could.

This may all change in a later version.

Complex handle attributes

Sometimes handles are having complex attributes like hash refs or array refs and not simple strings or integers. For example, with DBD::CSV, you would like to write something like

  $dbh->{"csv_tables"}->{"passwd"} =
        { "sep_char" => ":", "eol" => "\n";

The above example would advice the CSV driver to assume the file "passwd" to be in the format of the /etc/passwd file: Colons as separators and a line feed without carriage return as line terminator.

Surprisingly this example doesn't work with the proxy driver. To understand the reasons, you should consider the following: The Perl compiler is executing the above example in two steps:

  1. The first step is fetching the value of the key "csv_tables" in the handle $dbh. The value returned is complex, a hash ref.

  2. The second step is storing some value (the right hand side of the assignment) as the key "passwd" in the hash ref from step 1.

This becomes a little bit clearer, if we rewrite the above code:

  $tables = $dbh->{"csv_tables"};
  $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";

While the examples work fine without the proxy, the fail due to a subtile difference in step 1: By DBI magic, the hash ref $dbh->{'csv_tables'} is returned from the server to the client. The client creates a local copy. This local copy is the result of step 1. In other words, step 2 modifies a local copy of the hash ref, but not the server's hash ref.

The workaround is storing the modified local copy back to the server:

  $tables = $dbh->{"csv_tables"};
  $tables->{"passwd"} = { "sep_char" => ":", "eol" => "\n";
  $dbh->{"csv_tables"} = $tables;

AUTHOR AND COPYRIGHT

This module is Copyright (c) 1997, 1998

    Jochen Wiedmann
    Am Eisteich 9
    72555 Metzingen
    Germany
    Email: joe@ispsoft.de
    Phone: +49 7123 14887

The DBD::Proxy module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. In particular permission is granted to Tim Bunce for distributing this as a part of the DBI.

SEE ALSO

the DBI manpage, the RPC::PlClient manpage, the Storable manpage


DBD::SQLite - Self Contained RDBMS in a DBI Driver

  • CONFORMANCE WITH DBI SPECIFICATION
  • DRIVER PRIVATE ATTRIBUTES
    • Database Handle Attributes
  • DRIVER PRIVATE METHODS
    • $dbh->func('last_insert_rowid')
    • $dbh->func( 'busy_timeout' )
    • $dbh->func( $ms, 'busy_timeout' )
    • $dbh->func( $name, $argc, $func_ref, "create_function" )
    • $dbh->func( $name, $argc, $pkg, 'create_aggregate' )
  • BLOBS
  • NOTES
  • PERFORMANCE
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

DBD::SQLite - Self Contained RDBMS in a DBI Driver

SYNOPSIS

  use DBI;
  my $dbh = DBI->connect("dbi:SQLite:dbname=dbfile","","");

DESCRIPTION

SQLite is a public domain RDBMS database engine that you can find at http://www.hwaci.com/sw/sqlite/.

Rather than ask you to install SQLite first, because SQLite is public domain, DBD::SQLite includes the entire thing in the distribution. So in order to get a fast transaction capable RDBMS working for your perl project you simply have to install this module, and nothing else.

SQLite supports the following features:

Implements a large subset of SQL92

See http://www.hwaci.com/sw/sqlite/lang.html for details.

A complete DB in a single disk file

Everything for your database is stored in a single disk file, making it easier to move things around than with DBD::CSV.

Atomic commit and rollback

Yes, DBD::SQLite is small and light, but it supports full transactions!

Extensible

User-defined aggregate or regular functions can be registered with the SQL parser.

There's lots more to it, so please refer to the docs on the SQLite web page, listed above, for SQL details. Also refer to the DBI manpage for details on how to use DBI itself.

CONFORMANCE WITH DBI SPECIFICATION

The API works like every DBI module does. Please see the DBI manpage for more details about core features.

Currently many statement attributes are not implemented or are limited by the typeless nature of the SQLite database.

DRIVER PRIVATE ATTRIBUTES

Database Handle Attributes

sqlite_version

Returns the version of the SQLite library which DBD::SQLite is using, e.g., "2.8.0". Can only be read.

unicode

If set to a true value, DBD::SQLite will turn the UTF-8 flag on for all text strings coming out of the database. For more details on the UTF-8 flag see the perlunicode manpage. The default is for the UTF-8 flag to be turned off.

Also note that due to some bizareness in SQLite's type system (see http://www.sqlite.org/datatype3.html), if you want to retain blob-style behavior for some columns under $dbh->{unicode} = 1 >> (say, to store images in the database), you have to state so explicitely using the 3-argument form of L<DBI/bind_param> when doing updates:

    use DBI qw(:sql_types);
    $dbh->{unicode} = 1;
    my $sth = $dbh->prepare
         ("INSERT INTO mytable (blobcolumn) VALUES (?)");
    $sth->bind_param(1, $binary_data, SQL_BLOB); # binary_data will
    # be stored as-is.

Defining the column type as BLOB in the DDL is not sufficient.

DRIVER PRIVATE METHODS

$dbh->func('last_insert_rowid')

This method returns the last inserted rowid. If you specify an INTEGER PRIMARY KEY as the first column in your table, that is the column that is returned. Otherwise, it is the hidden ROWID column. See the sqlite docs for details.

Note: You can now use $dbh->last_insert_id() if you have a recent version of DBI.

$dbh->func( 'busy_timeout' )

Retrieve the current busy timeout.

$dbh->func( $ms, 'busy_timeout' )

Set the current busy timeout. The timeout is in milliseconds.

$dbh->func( $name, $argc, $func_ref, "create_function" )

This method will register a new function which will be useable in SQL query. The method's parameters are:

$name

The name of the function. This is the name of the function as it will be used from SQL.

$argc

The number of arguments taken by the function. If this number is -1, the function can take any number of arguments.

$func_ref

This should be a reference to the function's implementation.

For example, here is how to define a now() function which returns the current number of seconds since the epoch:

    $dbh->func( 'now', 0, sub { return time }, 'create_function' );

After this, it could be use from SQL as:

    INSERT INTO mytable ( now() );

$dbh->func( $name, $argc, $pkg, 'create_aggregate' )

This method will register a new aggregate function which can then used from SQL. The method's parameters are:

$name

The name of the aggregate function, this is the name under which the function will be available from SQL.

$argc

This is an integer which tells the SQL parser how many arguments the function takes. If that number is -1, the function can take any number of arguments.

$pkg

This is the package which implements the aggregator interface.

The aggregator interface consists of defining three methods:

new()

This method will be called once to create an object which should be used to aggregate the rows in a particular group. The step() and finalize() methods will be called upon the reference return by the method.

step(@_)

This method will be called once for each rows in the aggregate.

finalize()

This method will be called once all rows in the aggregate were processed and it should return the aggregate function's result. When there is no rows in the aggregate, finalize() will be called right after new().

Here is a simple aggregate function which returns the variance (example adapted from pysqlite):

    package variance;

    sub new { bless [], shift; }

    sub step {
        my ( $self, $value ) = @_;

        push @$self, $value;
            }

    sub finalize {
        my $self = $_[0];

        my $n = @$self;

        # Variance is NULL unless there is more than one row
        return undef unless $n || $n == 1;

        my $mu = 0;
        foreach my $v ( @$self ) {
            $mu += $v;
        }
        $mu /= $n;

        my $sigma = 0;
        foreach my $v ( @$self ) {
            $sigma += ($x - $mu)**2;
        }
        $sigma = $sigma / ($n - 1);

        return $sigma;
            }

    $dbh->func( "variance", 1, 'variance', "create_aggregate" );

The aggregate function can then be used as:

    SELECT group_name, variance(score) FROM results
    GROUP BY group_name;

BLOBS

As of version 1.11, blobs should "just work" in SQLite as text columns. However this will cause the data to be treated as a string, so SQL statements such as length(x) will return the length of the column as a NUL terminated string, rather than the size of the blob in bytes. In order to store natively as a BLOB use the following code:

  use DBI qw(:sql_types);
  my $dbh = DBI->connect("dbi:sqlite:/path/to/db");

  my $blob = `cat foo.jpg`;
  my $sth = $dbh->prepare("INSERT INTO mytable VALUES (1, ?)");
  $sth->bind_param(1, $blob, SQL_BLOB);
  $sth->execute();

And then retreival just works:

  $sth = $dbh->prepare("SELECT * FROM mytable WHERE id = 1");
  $sth->execute();
  my $row = $sth->fetch;
  my $blobo = $row->[1];

  # now $blobo == $blob

NOTES

To access the database from the command line, try using dbish which comes with the DBI module. Just type:

  dbish dbi:SQLite:foo.db

On the command line to access the file foo.db.

Alternatively you can install SQLite from the link above without conflicting with DBD::SQLite and use the supplied sqlite command line tool.

PERFORMANCE

SQLite is fast, very fast. I recently processed my 72MB log file with it, inserting the data (400,000+ rows) by using transactions and only committing every 1000 rows (otherwise the insertion is quite slow), and then performing queries on the data.

Queries like count(*) and avg(bytes) took fractions of a second to return, but what surprised me most of all was:

  SELECT url, count(*) as count FROM access_log
    GROUP BY url
    ORDER BY count desc
    LIMIT 20

To discover the top 20 hit URLs on the site (http://axkit.org), and it returned within 2 seconds. I'm seriously considering switching my log analysis code to use this little speed demon!

Oh yeah, and that was with no indexes on the table, on a 400MHz PIII.

For best performance be sure to tune your hdparm settings if you are using linux. Also you might want to set:

  PRAGMA default_synchronous = OFF

Which will prevent sqlite from doing fsync's when writing (which slows down non-transactional writes significantly) at the expense of some peace of mind. Also try playing with the cache_size pragma.

BUGS

Likely to be many, please use http://rt.cpan.org/ for reporting bugs.

AUTHOR

Matt Sergeant, matt@sergeant.org

Perl extension functions contributed by Francis J. Lacoste <flacoste@logreport.org> and Wolfgang Sourdeau <wolfgang@logreport.org>

SEE ALSO

the DBI manpage.


DBD::Sponge - Create a DBI statement handle from Perl data

  • METHODS
    • connect()
    • prepare()
  • BUGS
  • AUTHOR AND COPYRIGHT
  • SEE ALSO

NAME

DBD::Sponge - Create a DBI statement handle from Perl data

SYNOPSIS

  my $sponge = DBI->connect("dbi:Sponge:","","",{ RaiseError => 1 });
  my $sth = $sponge->prepare($statement, {
          rows => $data,
          NAME => $names,
          %attr
      }
  );

DESCRIPTION

DBD::Sponge is useful for making a Perl data structure accessible through a standard DBI statement handle. This may be useful to DBD module authors who need to transform data in this way.

METHODS

connect()

  my $sponge = DBI->connect("dbi:Sponge:","","",{ RaiseError => 1 });

Here's a sample syntax for creating a database handle for the Sponge driver. No username and password are needed.

prepare()

  my $sth = $sponge->prepare($statement, {
          rows => $data,
          NAME => $names,
          %attr
      }
  );

  • The $statement here is an arbitrary statement or name you want to provide as identity of your data. If you're using DBI::Profile it will appear in the profile data.

    Generally it's expected that you are preparing a statement handle as if a select statement happened.

  • $data is a reference to the data you are providing, given as an array of arrays.

  • $names is a reference an array of column names for the $data you are providing. The number and order should match the number and ordering of the $data columns.

  • %attr is a hash of other standard DBI attributes that you might pass to a prepare statement.

    Currently only NAME, TYPE, and PRECISION are supported.

BUGS

Using this module to prepare INSERT-like statements is not currently documented.

AUTHOR AND COPYRIGHT

This module is Copyright (c) 2003 Tim Bunce

Documentation initially written by Mark Stosberg

The DBD::Sponge module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. In particular permission is granted to Tim Bunce for distributing this as a part of the DBI.

SEE ALSO

the DBI manpage


DBD::mysql - MySQL driver for the Perl5 Database Interface

  • EXAMPLE
  • DESCRIPTION
    • Class Methods
    • Private MetaData Methods
    • Server Administration
  • DATABASE HANDLES
  • STATEMENT HANDLES
  • TRANSACTION SUPPORT
  • MULTIPLE RESULT SETS
    • Issues with Multiple result sets
  • MULTITHREADING
  • INSTALLATION
  • WIN32 INSTALLATION
  • AUTHORS
  • COPYRIGHT
  • MAILING LIST SUPPORT
  • ADDITIONAL DBI INFORMATION
  • BUG REPORTING, ENHANCEMENT/FEATURE REQUESTS

NAME

DBD::mysql - MySQL driver for the Perl5 Database Interface (DBI)

SYNOPSIS

    use DBI;

    $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port";

    $dbh = DBI->connect($dsn, $user, $password);

    $drh = DBI->install_driver("mysql");
    @databases = DBI->data_sources("mysql");
       or
    @databases = DBI->data_sources("mysql",
      {"host" => $host, "port" => $port, "user" => $user, password => $pass});

    $sth = $dbh->prepare("SELECT * FROM foo WHERE bla");
       or
    $sth = $dbh->prepare("LISTFIELDS $table");
       or
    $sth = $dbh->prepare("LISTINDEX $table $index");
    $sth->execute;
    $numRows = $sth->rows;
    $numFields = $sth->{'NUM_OF_FIELDS'};
    $sth->finish;

    $rc = $drh->func('createdb', $database, $host, $user, $password, 'admin');
    $rc = $drh->func('dropdb', $database, $host, $user, $password, 'admin');
    $rc = $drh->func('shutdown', $host, $user, $password, 'admin');
    $rc = $drh->func('reload', $host, $user, $password, 'admin');

    $rc = $dbh->func('createdb', $database, 'admin');
    $rc = $dbh->func('dropdb', $database, 'admin');
    $rc = $dbh->func('shutdown', 'admin');
    $rc = $dbh->func('reload', 'admin');

EXAMPLE

  #!/usr/bin/perl

  use strict;
  use DBI();

  # Connect to the database.
  my $dbh = DBI->connect("DBI:mysql:database=test;host=localhost",
                         "joe", "joe's password",
                         {'RaiseError' => 1});

  # Drop table 'foo'. This may fail, if 'foo' doesn't exist.
  # Thus we put an eval around it.
  eval { $dbh->do("DROP TABLE foo") };
  print "Dropping foo failed: $@\n" if $@;

  # Create a new table 'foo'. This must not fail, thus we don't
  # catch errors.
  $dbh->do("CREATE TABLE foo (id INTEGER, name VARCHAR(20))");

  # INSERT some data into 'foo'. We are using $dbh->quote() for
  # quoting the name.
  $dbh->do("INSERT INTO foo VALUES (1, " . $dbh->quote("Tim") . ")");

  # Same thing, but using placeholders
  $dbh->do("INSERT INTO foo VALUES (?, ?)", undef, 2, "Jochen");

  # Now retrieve data from the table.
  my $sth = $dbh->prepare("SELECT * FROM foo");
  $sth->execute();
  while (my $ref = $sth->fetchrow_hashref()) {
    print "Found a row: id = $ref->{'id'}, name = $ref->{'name'}\n";
  }
  $sth->finish();

  # Disconnect from the database.
  $dbh->disconnect();

DESCRIPTION

DBD::mysql is the Perl5 Database Interface driver for the MySQL database. In other words: DBD::mysql is an interface between the Perl programming language and the MySQL programming API that comes with the MySQL relational database management system. Most functions provided by this programming API are supported. Some rarely used functions are missing, mainly because noone ever requested them. :-)

In what follows we first discuss the use of DBD::mysql, because this is what you will need the most. For installation, see the sections on INSTALLATION, and WIN32 INSTALLATION below. See EXAMPLE for a simple example above.

From perl you activate the interface with the statement

    use DBI;

After that you can connect to multiple MySQL database servers and send multiple queries to any of them via a simple object oriented interface. Two types of objects are available: database handles and statement handles. Perl returns a database handle to the connect method like so:

  $dbh = DBI->connect("DBI:mysql:database=$db;host=$host",
                      $user, $password, {RaiseError => 1});

Once you have connected to a database, you can can execute SQL statements with:

  my $query = sprintf("INSERT INTO foo VALUES (%d, %s)",
                      $number, $dbh->quote("name"));
  $dbh->do($query);

See DBI(3) for details on the quote and do methods. An alternative approach is

  $dbh->do("INSERT INTO foo VALUES (?, ?)", undef,
           $number, $name);

in which case the quote method is executed automatically. See also the bind_param method in DBI(3). See DATABASE HANDLES below for more details on database handles.

If you want to retrieve results, you need to create a so-called statement handle with:

  $sth = $dbh->prepare("SELECT * FROM $table");
  $sth->execute();

This statement handle can be used for multiple things. First of all you can retreive a row of data:

  my $row = $sth->fetchrow_hashref();

If your table has columns ID and NAME, then $row will be hash ref with keys ID and NAME. See STATEMENT HANDLES below for more details on statement handles.

But now for a more formal approach:

Class Methods

connect
    use DBI;

    $dsn = "DBI:mysql:$database";
    $dsn = "DBI:mysql:database=$database;host=$hostname";
    $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port";

    $dbh = DBI->connect($dsn, $user, $password);

A database must always be specified.

host
port

The hostname, if not specified or specified as '' or 'localhost', will default to a MySQL server running on the local machine using the default for the UNIX socket. To connect to a MySQL server on the local machine via TCP, you must specify the loopback IP address (127.0.0.1) as the host.

Should the MySQL server be running on a non-standard port number, you may explicitly state the port number to connect to in the hostname argument, by concatenating the hostname and port number together separated by a colon ( : ) character or by using the port argument.

To connect to a MySQL server on localhost using TCP/IP, you must specify the hostname as 127.0.0.1 (with the optional port).

mysql_client_found_rows

Enables (TRUE value) or disables (FALSE value) the flag CLIENT_FOUND_ROWS while connecting to the MySQL server. This has a somewhat funny effect: Without mysql_client_found_rows, if you perform a query like

  UPDATE $table SET id = 1 WHERE id = 1

then the MySQL engine will always return 0, because no rows have changed. With mysql_client_found_rows however, it will return the number of rows that have an id 1, as some people are expecting. (At least for compatibility to other engines.)

mysql_compression

As of MySQL 3.22.3, a new feature is supported: If your DSN contains the option "mysql_compression=1", then the communication between client and server will be compressed.

mysql_connect_timeout

If your DSN contains the option "mysql_connect_timeout=##", the connect request to the server will timeout if it has not been successful after the given number of seconds.

mysql_read_default_file
mysql_read_default_group

These options can be used to read a config file like /etc/my.cnf or ~/.my.cnf. By default MySQL's C client library doesn't use any config files unlike the client programs (mysql, mysqladmin, ...) that do, but outside of the C client library. Thus you need to explicitly request reading a config file, as in

    $dsn = "DBI:mysql:test;mysql_read_default_file=/home/joe/my.cnf";
    $dbh = DBI->connect($dsn, $user, $password)

The option mysql_read_default_group can be used to specify the default group in the config file: Usually this is the client group, but see the following example:

    [client]
    host=localhost
    [perl]
    host=perlhost

(Note the order of the entries! The example won't work, if you reverse the [client] and [perl] sections!)

If you read this config file, then you'll be typically connected to localhost. However, by using

    $dsn = "DBI:mysql:test;mysql_read_default_group=perl;"
        . "mysql_read_default_file=/home/joe/my.cnf";
    $dbh = DBI->connect($dsn, $user, $password);

you'll be connected to perlhost. Note that if you specify a default group and do not specify a file, then the default config files will all be read. See the documentation of the C function mysql_options() for details.

mysql_socket

As of MySQL 3.21.15, it is possible to choose the Unix socket that is used for connecting to the server. This is done, for example, with

    mysql_socket=/dev/mysql

Usually there's no need for this option, unless you are using another location for the socket than that built into the client.

mysql_ssl

A true value turns on the CLIENT_SSL flag when connecting to the MySQL database:

  mysql_ssl=1

This means that your communication with the server will be encrypted.

If you turn mysql_ssl on, you might also wish to use the following flags:

mysql_ssl_client_key
mysql_ssl_client_cert
mysql_ssl_ca_file
mysql_ssl_ca_path
mysql_ssl_cipher

These are used to specify the respective parameters of a call to mysql_ssl_set, if mysql_ssl is turned on.

mysql_local_infile

As of MySQL 3.23.49, the LOCAL capability for LOAD DATA may be disabled in the MySQL client library by default. If your DSN contains the option "mysql_local_infile=1", LOAD DATA LOCAL will be enabled. (However, this option is *ineffective* if the server has also been configured to disallow LOCAL.)

mysql_multi_statements

As of MySQL 4.1, support for multiple statements seperated by a semicolon (;) may be enabled by using this option. Enabling this option may cause problems if server-side prepared statements are also enabled.

Prepared statement support (server side prepare)

As of 3.0002_1, server side prepare statements were on by default (if your server was >= 4.1.3). As of 3.0009, they were off by default again due to issues with the prepared statement API (all other mysql connectors are set this way until C API issues are resolved). The requirement to use prepared statements still remains that you have a server >= 4.1.3

To use server side prepared statements, all you need to do is set the variable mysql_server_prepare in the connect:

$dbh = DBI->connect( "DBI:mysql:database=test;host=localhost;mysql_server_prepare=1", "", "", { RaiseError => 1, AutoCommit => 1 } );

* Note: delimiter for this param is ';'

There are many benefits to using server side prepare statements, mostly if you are performing many inserts because of that fact that a single statement is prepared to accept multiple insert values.

To make sure that the 'make test' step tests whether server prepare works, you just need to export the env variable MYSQL_SERVER_PREPARE:

export MYSQL_SERVER_PREPARE=1

mysql_embedded_options

The option <mysql_embedded_options> can be used to pass 'command-line' options to embedded server.

Example:

$testdsn="DBI:mysqlEmb:database=test;mysql_embedded_options=--help,--verbose";

mysql_embedded_groups

The option <mysql_embedded_groups> can be used to specify the groups in the config file(my.cnf) which will be used to get options for embedded server. If not specified [server] and [embedded] groups will be used.

Example:

$testdsn="DBI:mysqlEmb:database=test;mysql_embedded_groups=embedded_server,common";

Private MetaData Methods

ListDBs
    my $drh = DBI->install_driver("mysql");
    @dbs = $drh->func("$hostname:$port", '_ListDBs');
    @dbs = $drh->func($hostname, $port, '_ListDBs');
    @dbs = $dbh->func('_ListDBs');

Returns a list of all databases managed by the MySQL server running on $hostname, port $port. This is a legacy method. Instead, you should use the portable method

    @dbs = DBI->data_sources("mysql");

Server Administration

admin
    $rc = $drh->func("createdb", $dbname, [host, user, password,], 'admin');
    $rc = $drh->func("dropdb", $dbname, [host, user, password,], 'admin');
    $rc = $drh->func("shutdown", [host, user, password,], 'admin');
    $rc = $drh->func("reload", [host, user, password,], 'admin');

      or
    $rc = $dbh->func("createdb", $dbname, 'admin');
    $rc = $dbh->func("dropdb", $dbname, 'admin');
    $rc = $dbh->func("shutdown", 'admin');
    $rc = $dbh->func("reload", 'admin');

For server administration you need a server connection. For obtaining this connection you have two options: Either use a driver handle (drh) and supply the appropriate arguments (host, defaults localhost, user, defaults to '' and password, defaults to ''). A driver handle can be obtained with

    $drh = DBI->install_driver('mysql');

Otherwise reuse the existing connection of a database handle (dbh).

There's only one function available for administrative purposes, comparable to the m(y)sqladmin programs. The command being execute depends on the first argument:

createdb

Creates the database $dbname. Equivalent to "m(y)sqladmin create $dbname".

dropdb

Drops the database $dbname. Equivalent to "m(y)sqladmin drop $dbname".

It should be noted that database deletion is not prompted for in any way. Nor is it undo-able from DBI.

    Once you issue the dropDB() method, the database will be gone!

These method should be used at your own risk.

shutdown

Silently shuts down the database engine. (Without prompting!) Equivalent to "m(y)sqladmin shutdown".

reload

Reloads the servers configuration files and/or tables. This can be particularly important if you modify access privileges or create new users.

DATABASE HANDLES

The DBD::mysql driver supports the following attributes of database handles (read only):

  $errno = $dbh->{'mysql_errno'};
  $error = $dbh->{'mysql_error'};
  $info = $dbh->{'mysql_hostinfo'};
  $info = $dbh->{'mysql_info'};
  $insertid = $dbh->{'mysql_insertid'};
  $info = $dbh->{'mysql_protoinfo'};
  $info = $dbh->{'mysql_serverinfo'};
  $info = $dbh->{'mysql_stat'};
  $threadId = $dbh->{'mysql_thread_id'};

These correspond to mysql_errno(), mysql_error(), mysql_get_host_info(),
mysql_info(), mysql_insert_id(), mysql_get_proto_info(),
mysql_get_server_info(), mysql_stat() and mysql_thread_id(),
respectively.

 $info_hashref = $dhb->{mysql_dbd_stats}

DBD::mysql keeps track of some statistics in the mysql_dbd_stats attribute. The following stats are being maintained:

auto_reconnects_ok

The number of times that DBD::mysql successfully reconnected to the mysql server.

auto_reconnects_failed

The number of times that DBD::mysql tried to reconnect to mysql but failed.

The DBD::mysql driver also supports the following attribute(s) of database handles (read/write):

 $bool_value = $dbh->{mysql_auto_reconnect};
 $dbh->{mysql_auto_reconnect} = $AutoReconnect ? 1 : 0;
mysql_auto_reconnect

This attribute determines whether DBD::mysql will automatically reconnect to mysql if the connection be lost. This feature defaults to off; however, if either the GATEWAY_INTERFACE or MOD_PERL envionment variable is set, DBD::mysql will turn mysql_auto_reconnect on. Setting mysql_auto_reconnect to on is not advised if 'lock tables' is used because if DBD::mysql reconnect to mysql all table locks will be lost. This attribute is ignored when AutoCommit is turned off, and when AutoCommit is turned off, DBD::mysql will not automatically reconnect to the server.

mysql_use_result

This attribute forces the driver to use mysql_use_result rather than mysql_store_result. The former is faster and less memory consuming, but tends to block other processes. (That's why mysql_store_result is the default.)

It is possible to set default value of the mysql_use_result attribute for $dbh using several ways:

 - through DSN
   $dbh= DBI->connect("DBI:mysql:test;mysql_use_result=1", "root", "");

 - after creation of database handle
   $dbh->{'mysql_use_result'}=0; #disable
   $dbh->{'mysql_use_result'}=1; #enable

It is possible to set/unset the mysql_use_result attribute after creation of statement handle. See below.

mysql_enable_utf8

This attribute determines whether DBD::mysql should assume strings stored in the database are utf8. This feature defaults to off.

When set, a data retrieved from a textual column type (char, varchar, etc) will have the UTF-8 flag turned on if necessary. This enables character semantics on that string. You will also need to ensure that your database / table / column is configured to use UTF8. See Chapter 10 of the mysql manual for details.

Additionally, turning on this flag tells MySQL that incoming data should be treated as UTF-8. This will only take effect if used as part of the call to connect(). If you turn the flag on after connecting, you will need to issue the command SET NAMES utf8 to get the same effect.

This option is experimental and may change in future versions.

STATEMENT HANDLES

The statement handles of DBD::mysql support a number of attributes. You access these by using, for example,

  my $numFields = $sth->{'NUM_OF_FIELDS'};

Note, that most attributes are valid only after a successfull execute. An undef value will returned in that case. The most important exception is the mysql_use_result attribute: This forces the driver to use mysql_use_result rather than mysql_store_result. The former is faster and less memory consuming, but tends to block other processes. (That's why mysql_store_result is the default.)

To set the mysql_use_result attribute, use either of the following:

  my $sth = $dbh->prepare("QUERY", { "mysql_use_result" => 1});

or

  my $sth = $dbh->prepare("QUERY");
  $sth->{"mysql_use_result"} = 1;

Column dependent attributes, for example NAME, the column names, are returned as a reference to an array. The array indices are corresponding to the indices of the arrays returned by fetchrow and similar methods. For example the following code will print a header of table names together with all rows:

  my $sth = $dbh->prepare("SELECT * FROM $table");
  if (!$sth) {
      die "Error:" . $dbh->errstr . "\n";
  }
  if (!$sth->execute) {
      die "Error:" . $sth->errstr . "\n";
  }
  my $names = $sth->{'NAME'};
  my $numFields = $sth->{'NUM_OF_FIELDS'};
  for (my $i = 0;  $i < $numFields;  $i++) {
      printf("%s%s", $i ? "," : "", $$names[$i]);
  }
  print "\n";
  while (my $ref = $sth->fetchrow_arrayref) {
      for (my $i = 0;  $i < $numFields;  $i++) {
          printf("%s%s", $i ? "," : "", $$ref[$i]);
      }
      print "\n";
  }

For portable applications you should restrict yourself to attributes with capitalized or mixed case names. Lower case attribute names are private to DBD::mysql. The attribute list includes:

ChopBlanks

this attribute determines whether a fetchrow will chop preceding and trailing blanks off the column values. Chopping blanks does not have impact on the max_length attribute.

mysql_insertid

MySQL has the ability to choose unique key values automatically. If this happened, the new ID will be stored in this attribute. An alternative way for accessing this attribute is via $dbh->{'mysql_insertid'}. (Note we are using the $dbh in this case!)

mysql_is_blob

Reference to an array of boolean values; TRUE indicates, that the respective column is a blob. This attribute is valid for MySQL only.

mysql_is_key

Reference to an array of boolean values; TRUE indicates, that the respective column is a key. This is valid for MySQL only.

mysql_is_num

Reference to an array of boolean values; TRUE indicates, that the respective column contains numeric values.

mysql_is_pri_key

Reference to an array of boolean values; TRUE indicates, that the respective column is a primary key.

mysql_is_auto_increment

Reference to an array of boolean values; TRUE indicates that the respective column is an AUTO_INCREMENT column. This is only valid for MySQL.

mysql_length
mysql_max_length

A reference to an array of maximum column sizes. The max_length is the maximum physically present in the result table, length gives the theoretically possible maximum. max_length is valid for MySQL only.

NAME

A reference to an array of column names.

NULLABLE

A reference to an array of boolean values; TRUE indicates that this column may contain NULL's.

NUM_OF_FIELDS

Number of fields returned by a SELECT or LISTFIELDS statement. You may use this for checking whether a statement returned a result: A zero value indicates a non-SELECT statement like INSERT, DELETE or UPDATE.

mysql_table

A reference to an array of table names, useful in a JOIN result.

TYPE

A reference to an array of column types. The engine's native column types are mapped to portable types like DBI::SQL_INTEGER() or DBI::SQL_VARCHAR(), as good as possible. Not all native types have a meaningfull equivalent, for example DBD::mysql::FIELD_TYPE_INTERVAL is mapped to DBI::SQL_VARCHAR(). If you need the native column types, use mysql_type. See below.

mysql_type

A reference to an array of MySQL's native column types, for example DBD::mysql::FIELD_TYPE_SHORT() or DBD::mysql::FIELD_TYPE_STRING(). Use the TYPE attribute, if you want portable types like DBI::SQL_SMALLINT() or DBI::SQL_VARCHAR().

mysql_type_name

Similar to mysql, but type names and not numbers are returned. Whenever possible, the ANSI SQL name is preferred.

mysql_warning_count

The number of warnings generated during execution of the SQL statement.

TRANSACTION SUPPORT

Beginning with DBD::mysql 2.0416, transactions are supported. The transaction support works as follows:

  • By default AutoCommit mode is on, following the DBI specifications.

  • If you execute

        $dbh->{'AutoCommit'} = 0;

    or

        $dbh->{'AutoCommit'} = 1;

    then the driver will set the MySQL server variable autocommit to 0 or 1, respectively. Switching from 0 to 1 will also issue a COMMIT, following the DBI specifications.

  • The methods

        $dbh->rollback();
    $dbh->commit();

    will issue the commands COMMIT and ROLLBACK, respectively. A ROLLBACK will also be issued if AutoCommit mode is off and the database handles DESTROY method is called. Again, this is following the DBI specifications.

Given the above, you should note the following:

  • You should never change the server variable autocommit manually, unless you are ignoring DBI's transaction support.

  • Switching AutoCommit mode from on to off or vice versa may fail. You should always check for errors, when changing AutoCommit mode. The suggested way of doing so is using the DBI flag RaiseError. If you don't like RaiseError, you have to use code like the following:

      $dbh->{'AutoCommit'} = 0;
  if ($dbh->{'AutoCommit'}) {
    # An error occurred!
  }

  • If you detect an error while changing the AutoCommit mode, you should no longer use the database handle. In other words, you should disconnect and reconnect again, because the transaction mode is unpredictable. Alternatively you may verify the transaction mode by checking the value of the server variable autocommit. However, such behaviour isn't portable.

  • DBD::mysql has a "reconnect" feature that handles the so-called MySQL "morning bug": If the server has disconnected, most probably due to a timeout, then by default the driver will reconnect and attempt to execute the same SQL statement again. However, this behaviour is disabled when AutoCommit is off: Otherwise the transaction state would be completely unpredictable after a reconnect.

  • The "reconnect" feature of DBD::mysql can be toggled by using the mysql_auto_reconnect attribute. This behaviour should be turned off in code that uses LOCK TABLE because if the database server time out and DBD::mysql reconnect, table locks will be lost without any indication of such loss.

MULTIPLE RESULT SETS

As of version 3.0002_5, DBD::mysql supports multiple result sets (Thanks to Guy Harrison!). This is the first release of this functionality, so there may be issues. Please report bugs if you run into them!

The basic usage of multiple result sets is

  do
  {
    while (@row= $sth->fetchrow_array())
    {
      do stuff;
    }
  } while ($sth->more_results)

An example would be:

  $dbh->do("drop procedure if exists someproc") or print $DBI::errstr;

  $dbh->do("create procedure somproc() deterministic
   begin
   declare a,b,c,d int;
   set a=1;
   set b=2;
   set c=3;
   set d=4;
   select a, b, c, d;
   select d, c, b, a;
   select b, a, c, d;
   select c, b, d, a;
  end") or print $DBI::errstr;

  $sth=$dbh->prepare('call someproc()') ||
  die $DBI::err.": ".$DBI::errstr;

  $sth->execute || die DBI::err.": ".$DBI::errstr; $rowset=0;
  do {
    print "\nRowset ".++$i."\n---------------------------------------\n\n";
    foreach $colno (0..$sth->{NUM_OF_FIELDS}) {
      print $sth->{NAME}->[$colno]."\t";
    }
    print "\n";
    while (@row= $sth->fetchrow_array())  {
      foreach $field (0..$#row) {
        print $row[$field]."\t";
      }
      print "\n";
    }
  } until (!$sth->more_results)

  For more examples, please see the eg/ directory. This is where helpful
  DBD::mysql code snippits will be added in the future.

Issues with Multiple result sets

So far, the main issue is if your result sets are "jagged", meaning, the number of columns of your results vary. Varying numbers of columns could result in your script crashing. This is something that will be fixed soon.

MULTITHREADING

The multithreading capabilities of DBD::mysql depend completely on the underlying C libraries: The modules are working with handle data only, no global variables are accessed or (to the best of my knowledge) thread unsafe functions are called. Thus DBD::mysql is believed to be completely thread safe, if the C libraries are thread safe and you don't share handles among threads.

The obvious question is: Are the C libraries thread safe? In the case of MySQL the answer is "mostly" and, in theory, you should be able to get a "yes", if the C library is compiled for being thread safe (By default it isn't.) by passing the option -with-thread-safe-client to configure. See the section on How to make a threadsafe client in the manual.

INSTALLATION

Windows users may skip this section and pass over to WIN32 INSTALLATION below. Others, go on reading.

First of all, you do not need an installed MySQL server for installing DBD::mysql. However, you need at least the client libraries and possibly the header files, if you are compiling DBD::mysql from source. In the case of MySQL you can create a client-only version by using the configure option --without-server. If you are using precompiled binaries, then it may be possible to use just selected RPM's like MySQL-client and MySQL-devel or something similar, depending on the distribution.

First you need to install the DBI module. For using dbimon, a simple DBI shell it is recommended to install Data::ShowTable another Perl module.

I recommend trying automatic installation via the CPAN module. Try

  perl -MCPAN -e shell

If you are using the CPAN module for the first time, it will prompt you a lot of questions. If you finally receive the CPAN prompt, enter

  install Bundle::DBD::mysql

If this fails (which may be the case for a number of reasons, for example because you are behind a firewall or don't have network access), you need to do a manual installation. First of all you need to fetch the modules from CPAN search

   http://search.cpan.org/

The following modules are required

  DBI
  Data::ShowTable
  DBD::mysql

Then enter the following commands (note - versions are just examples):

  gzip -cd DBI-(version).tar.gz | tar xf -
  cd DBI-(version)
  perl Makefile.PL
  make
  make test
  make install
  cd ..
  gzip -cd Data-ShowTable-(version).tar.gz | tar xf -
  cd Data-ShowTable-3.3
  perl Makefile.PL
  make
  make install
  cd ..
  gzip -cd DBD-mysql-(version)-tar.gz | tar xf -
  cd DBD-mysql-(version)
  perl Makefile.PL
  make
  make test
  make install

During "perl Makefile.PL" you will be prompted some questions. Other questions are the directories with header files and libraries. For example, of your file mysql.h is in /usr/include/mysql/mysql.h, then enter the header directory /usr, likewise for /usr/lib/mysql/libmysqlclient.a or /usr/lib/libmysqlclient.so.

WIN32 INSTALLATION

If you are using ActivePerl, you may use ppm to install DBD-mysql. For Perl 5.6, upgrade to Build 623 or later, then it is sufficient to run

  ppm install DBI
  ppm install DBD::mysql

If you need an HTTP proxy, you might need to set the environment variable http_proxy, for example like this:

  set http_proxy=http://myproxy.com:8080/

As of this writing, DBD::mysql is missing in the ActivePerl 5.8.0 repository. However, Randy Kobes has kindly donated an own distribution and the following might succeed:

  ppm install http://theoryx5.uwinnipeg.ca/ppms/DBD-mysql.ppd

Otherwise you definitely *need* a C compiler. And it *must* be the same compiler that was being used for compiling Perl itself. If you don't have a C compiler, the file README.win32 from the Perl source distribution tells you where to obtain freely distributable C compilers like egcs or gcc. The Perl sources are available via CPAN search

  http://search.cpan.org

I recommend using the win32clients package for installing DBD::mysql under Win32, available for download on www.tcx.se. The following steps have been required for me:

-

The current Perl versions (5.6, as of this writing) do have a problem with detecting the C libraries. I recommend to apply the following patch:

  *** c:\Perl\lib\ExtUtils\Liblist.pm.orig Sat Apr 15 20:03:40 2000
  --- c:\Perl\lib\ExtUtils\Liblist.pm      Sat Apr 15 20:03:45 2000
  ***************
  *** 230,235 ****
  --- 230,239 ----
      # add "$Config{installarchlib}/CORE" to default search path
      push @libpath, "$Config{installarchlib}/CORE";

  +     if ($VC  and  exists($ENV{LIB})  and  defined($ENV{LIB})) {
  +       push(@libpath, split(/;/, $ENV{LIB}));
  +     }
  +
      foreach (Text::ParseWords::quotewords('\s+', 0, $potential_libs)){

        $thislib = $_;

        =item -

Extract sources into C:\. This will create a directory C:\mysql with subdirectories include and lib.

IMPORTANT: Make sure this subdirectory is not shared by other TCX files! In particular do *not* store the MySQL server in the same directory. If the server is already installed in C:\mysql, choose a location like C:\tmp, extract the win32clients there. Note that you can remove this directory entirely once you have installed DBD::mysql.

-

Extract the DBD::mysql sources into another directory, for example C:\src\siteperl

-

Open a DOS shell and change directory to C:\src\siteperl.

-

The next step is only required if you repeat building the modules: Make sure that you have a clean build tree by running

  nmake realclean

If you don't have VC++, replace nmake with your flavour of make. If error messages are reported in this step, you may safely ignore them.

-

Run

  perl Makefile.PL

which will prompt you for some settings. The really important ones are:

  Which DBMS do you want to use?

enter a 1 here (MySQL only), and

  Where is your mysql installed? Please tell me the directory that
  contains the subdir include.

where you have to enter the win32clients directory, for example C:\mysql or C:\tmp\mysql.

-

Continued in the usual way:

  nmake
  nmake install

If you want to create a PPM package for the ActiveState Perl version, then modify the above steps as follows: Run

  perl Makefile.PL NAME=DBD-mysql BINARY_LOCATION=DBD-mysql.tar.gz
  nmake ppd
  nmake

Once that is done, use tar and gzip (for example those from the CygWin32 distribution) to create an archive:

  mkdir x86
  tar cf x86/DBD-mysql.tar blib
  gzip x86/DBD-mysql.tar

Put the files x86/DBD-mysql.tar.gz and DBD-mysql.ppd onto some WWW server and install them by typing

  install http://your.server.name/your/directory/DBD-mysql.ppd

in the PPM program.

AUTHORS

The current version of DBD::mysql is almost completely written by Jochen Wiedmann, and is now being maintained by Patrick Galbraith (patg@mysql.com). The first version's author was Alligator Descartes, who was aided and abetted by Gary Shea, Andreas König and Tim Bunce amongst others.

The Mysql module was originally written by Andreas König <koenig@kulturbox.de>. The current version, mainly an emulation layer, is from Jochen Wiedmann.

COPYRIGHT

This module is Large Portions Copyright (c) 2004-2006 MySQL Patrick Galbraith, Alexey Stroganov, Large Portions Copyright (c) 2003-2005 Rudolf Lippan; Large Portions Copyright (c) 1997-2003 Jochen Wiedmann, with code portions Copyright (c)1994-1997 their original authors This module is released under the same license as Perl itself. See the Perl README for details.

MAILING LIST SUPPORT

This module is maintained and supported on a mailing list,

    perl@lists.mysql.com

To subscribe to this list, go to

http://lists.mysql.com/perl?sub=1

Mailing list archives are available at

http://lists.mysql.com/perl

Additionally you might try the dbi-user mailing list for questions about DBI and its modules in general. Subscribe via

dbi-users-subscribe@perl.org

Mailing list archives are at

http://groups.google.com/group/perl.dbi.users?hl=en&lr=

Also, the main DBI site is at

http://dbi.perl.org/

ADDITIONAL DBI INFORMATION

Additional information on the DBI project can be found on the World Wide Web at the following URL:

    http://dbi.perl.org

where documentation, pointers to the mailing lists and mailing list archives and pointers to the most current versions of the modules can be used.

Information on the DBI interface itself can be gained by typing:

    perldoc DBI

right now!

BUG REPORTING, ENHANCEMENT/FEATURE REQUESTS

Please report bugs, including all the information needed such as DBD::mysql version, MySQL version, OS type/version, etc to this link:

http://bugs.mysql.com/


INSTALL - How to install and configure DBD::mysql

  • PREREQUISITES
  • BINARY INSTALLATION
    • Windows
    • Red Hat Linux
    • Fedora Core Linux
    • Other systems
  • SOURCE INSTALLATION
    • CPAN installation
    • Manual installation
    • Configuration
    • Linker flags
  • SPECIAL SYSTEMS
    • Windows/CygWin
  • KNOWN PROBLEMS
  • SUPPORT

NAME

INSTALL - How to install and configure DBD::mysql

SYNOPSIS

  perl Makefile.PL [options]
  make
  make test
  make install

DESCRIPTION

This document describes the installation and configuration of DBD::mysql, the Perl DBI driver for the MySQL database. Before reading on, make sure that you have the prerequisites available: Perl, MySQL and DBI. For details see the separate section. PREREQUISITES.

Depending on your version of Perl, it might be possible to use a binary distribution of DBD::mysql. If possible, this is recommended. Otherwise you need to install from the sources. If so, you will definitely need a C compiler. Installation from binaries and sources are both described in separate sections. BINARY INSTALLATION. SOURCE INSTALLATION.

Finally, if you encounter any problems, do not forget to read the section on known problems. KNOWN PROBLEMS. If that doesn't help, you should look into the archive of the mailing list perl@lists.mysql.com. See http://www.mysql.com for archive locations. And if that still doesn't help, please post a question on this mailing list.

PREREQUISITES

Perl

Preferrably a version of Perl, that comes preconfigured with your system. For example, all Linux and FreeBSD distributions come with Perl. For Windows, ActivePerl is recommended, see http://www.activestate.com for details.

MySQL

You need not install the actual MySQL database server, the client files and the devlopment files are sufficient. For example, Fedora Core 4 Linux distribution comes with RPM files (using YUM) mysql.i386 and mysql-server.i386 (use "yum search" to find exact package names). These are sufficient, if the MySQL server is located on a foreign machine. You may also create client files by compiling from the MySQL source distribution and using

  configure --without-server

If you are using Windows and need to compile from sources (which is only the case if you are not using ActivePerl), then you must ensure that the header and library files are installed. This may require choosing a "Custom installation" and selecting the appropriate option when running the MySQL setup program.

DBI

DBD::mysql is a DBI driver, hence you need DBI. It is available from the same source where you got the DBD::mysql distribution from.

C compiler

A C compiler is only required, if you install from source. In most cases there are binary distributions of DBD::mysql available. However, if you need a C compiler, make sure, that it is the same C compiler that was used for compiling Perl and MySQL! Otherwise you will almost definitely encounter problems because of differences in the underlying C runtime libraries.

In the worst case, this might mean to compile Perl and MySQL yourself. But believe me, experience shows that a lot of problems are fixed this way.

Gzip libraries

Late versions of MySQL come with support for compression. Thus it may be required that you have install an RPM package like libz-devel, libgz-devel or something similar.

BINARY INSTALLATION

Binary installation is possible in the most cases, depending on your system. I give some examples:

Windows

ActivePerl offers a PPM archive of DBD::mysql. All you need to do is typing

  ppm
  install DBI
  install DBD-mysql

This will fetch the modules via HTTP and install them. If you need to use a WWW proxy server, the environment variable HTTP_proxy must be set:

  set HTTP_proxy=http://my.proxy.server:8000/
  ppm
  install DBI
  install DBD-mysql

Of course you need to replace the host name my.proxy.server and the port number 8000 with your local values.

If the above procedure doesn't work, please upgrade to the latest version of ActivePerl. Versions before build 623 are known to have problems.

PPM 3 is said to miss DBD::mysql in the repository. Thus use of PPM 3 is discouraged, in favour of PPM 2. If you need to use PPM 3, try

  ppm
  rep add PPM2 http://ppm.activestate.com/PPMPackages/5.6plus/
  rep 2
  install DBI
  install DBD-mysql

Red Hat Linux

As of version 7.1, Red Hat Linux comes with MySQL and DBD::mysql. You need to ensure that the following RPM's are installed:

  mysql
  perl-DBI
  perl-DBD-MySQL

For installation from source the following RPM's are required

  mysql-devel
  libz-devel

Optional are

  mysql-server

Fedora Core Linux

As of version 3, Fedora Linux comes with MySQL and DBD::mysql. You need to ensure that the following RPM's are installed:

  mysql or mysql-server
  perl-DBD-MySQL

For installation from source the following RPM's are required

  mysql-devel
  libz-devel

Please try

  yum search mysql

To see the exact names

Note: (important) FC 3 comes with MySQL 3.x, and some people have upgraded using MySQL RPMs for newer versions. If you do this, you must re-compile you DBD::mysql because your existing DBD::mysql will be linked against the old version of MySQL's client libs. CPAN has no way to know or detect that you have upgraded MySQL.

Other systems

In the case of Linux or FreeBSD distributions it is very likely that all you need comes with your distribution, as in the case of Red Hat Linux. I just cannot give you names, as I am not using these systems.

Please let me know if you find the files in your SuSE Linux, Debian Linux or FreeBSD distribution so that I can extend the above list.

SOURCE INSTALLATION

So you need to install from sources. If you are lucky, the Perl module CPAN will do all for you, thanks to the excellent work of Andreas Koenig. Otherwise you will need to do a manual installation. Some of you, in particular system administrators of multiple sites, will choose automatic installation. All of these installation types have an own section. CPAN installation. Manual installation. Configuration.

The DBD::mysql Makefile.PL needs to know where to find your MySQL installation. This may be achieved using command line switches (see Configuration) or automatically using the mysql_config binary which comes with most MySQL distributions. If your MySQL distribution contains mysql_config the easiest method is to ensure this binary is on your path.

e.g.
  PATH=$PATH:/usr/local/mysql/bin
  export PATH

CPAN installation

Installation of DBD::mysql can be incredibly easy:

  cpan
  install DBD::mysql

If you are using the CPAN module for the first time, just answer the questions by accepting the defaults which are fine in most cases. If you are using an older version of Perl, you might instead need a

  perl -MCPAN -e shell
  install DBD::mysql

If you cannot get the CPAN module working, you might try manual installation. If installation with CPAN fails because the your local settings have been guessed wrong, you need to ensure MySQL's mysql_config is on your path (see SOURCE INSTALLATION) or alternatively create a script called mysql_config. This is described in more details later. Configuration.

Manual installation

For a manual installation you need to fetch the DBD::mysql source distribution. The latest version is always available from

  http://www.cpan.org/modules/by-module/DBD/

The name is typically something like

  DBD-mysql-1.2216.tar.gz

The archive needs to be extracted. On Windows you may use a tool like WinZip, on Unix you type

  gzip -cd DBD-mysql-1.2216.tar.gz | tar xf -

This will create a subdirectory DBD-mysql-1.2216. Enter this subdirectory and type

  perl Makefile.PL
  make
  make test

(On Windows you may need to replace "make" with "nmake" or "dmake".) If the tests seem to look fine, you may continue with

  make install

If the compilation (make) or tests fail, you might need to configure some settings.

For example you might choose a different database, the C compiler or the linker might need some flags. Configuration. Compiler flags. Linker flags.

For Windows/CygWin there is a special section below. Windows/CygWin.

Configuration

The install script "Makefile.PL" can be configured via a lot of switches. All switches can be used on the command line. For example, the test database:

  perl Makefile.PL --testdb=<db>

If you do not like configuring these switches on the command line, you may alternatively create a script called mysql_config. This is described later on.

Available switches are:

testdb

Name of the test database, defaults to test.

testuser

Name of the test user, defaults to empty. If the name is empty, then the currently logged in users name will be used.

testpassword

Password of the test user, defaults to empty.

testhost

Host name or IP number of the test database; defaults to localhost.

testport

Port number of the test database

ps-protcol=1 or 0

Whether to run the test suite using server prepared statements or driver emulated prepared statemetns. ps-protocol=1 means use server prepare, ps-protocol=0 means driver emulated.

cflags

This is a list of flags that you want to give to the C compiler. The most important flag is the location of the MySQL header files. For example, on Red Hat Linux the header files are in /usr/include/mysql and you might try

  -I/usr/include/mysql

On Windows the header files may be in C:\mysql\include and you might try

  -IC:\mysql\include

The default flags are determined by running

  mysql_config --cflags

More details on the C compiler flags can be found in the following section. Compiler flags.

libs

This is a list of flags that you want to give to the linker or loader. The most important flags are the locations and names of additional libraries. For example, on Red Hat Linux your MySQL client libraries are in /usr/lib/mysql and you might try

  -L/usr/lib/mysql -lmysqlclient -lz

On Windows the libraries may be in C:\mysql\lib and

  -LC:\mysql\lib -lmysqlclient

might be a good choice. The default flags are determined by running

  mysql_config --libs

More details on the linker flags can be found in a separate section. Linker flags.

If a switch is not present on the command line, then the script mysql_config will be executed. This script comes as part of the MySQL distribution. For example, to determine the C compiler flags, we are executing

  mysql_config --cflags
  mysql_config --libs

If you want to configure your own settings for database name, database user and so on, then you have to create a script with the same name, that replies

=head2 Compiler flags

Note: the folling info about compiler and linker flags, you shouldn't have to use these options because Makefile.PL is pretty good at utilising mysql_config to get the flags that you need for a successful compile.

It is typically not so difficult to determine the appropriate flags for the C compiler. The linker flags, which you find in the next section, are another story.

The determination of the C compiler flags is usually left to a configuration script called mysql_config, which can be invoked with

  mysql_config --cflags

When doing so, it will emit a line with suggested C compiler flags, for example like this:

  -L/usr/include/mysql

The C compiler must find some header files. Header files have the extension .h. MySQL header files are, for example, mysql.h and mysql_version.h. In most cases the header files are not installed by default. For example, on Windows it is an installation option of the MySQL setup program (Custom installation), whether the header files are installed or not. On Red Hat Linux, you need to install an RPM archive mysql-devel or MySQL-devel.

If you know the location of the header files, then you will need to add an option

  -L<header directory>

to the C compiler flags, for example -L/usr/include/mysql.

Linker flags

Appropriate linker flags are the most common source of problems while installing DBD::mysql. I will only give a rough overview, you'll find more details in the troubleshooting section. KNOWN PROBLEMS

The determination of the C compiler flags is usually left to a configuration script called mysql_config, which can be invoked with

  mysql_config --libs

When doing so, it will emit a line with suggested C compiler flags, for example like this:

   -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm   -lz -lcrypt

The following items typically need to be configured for the linker:

The mysqlclient library

The MySQL client library comes as part of the MySQL distribution. Depending on your system it may be a file called

  F<libmysqlclient.a>   statically linked library, Unix
  F<libmysqlclient.so>  dynamically linked library, Unix
  F<mysqlclient.lib>    statically linked library, Windows
  F<mysqlclient.dll>    dynamically linked library, Windows

or something similar.

As in the case of the header files, the client library is typically not installed by default. On Windows you will need to select them while running the MySQL setup program (Custom installation). On Red Hat Linux an RPM archive mysql-devel or MySQL-devel must be installed.

The linker needs to know the location and name of the mysqlclient library. This can be done by adding the flags

  -L<lib directory> -lmysqlclient

or by adding the complete path name. Examples:

  -L/usr/lib/mysql -lmysqlclient
  -LC:\mysql\lib -lmysqlclient

If you would like to use the static libraries (and there are excellent reasons to do so), you need to create a separate directory, copy the static libraries to that place and use the -L switch above to point to your new directory. For example:

  mkdir /tmp/mysql-static
  cp /usr/lib/mysql/*.a /tmp/mysql-static
  perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
  make
  make test
  make install
  rm -rf /tmp/mysql-static
The gzip library

The MySQL client can use compression when talking to the MySQL server, a nice feature when sending or receiving large texts over a slow network.

On Unix you typically find the appropriate file name by running

  ldconfig -p | grep libz
  ldconfig -p | grep libgz

Once you know the name (libz.a or libgz.a is best), just add it to the list of linker flags. If this seems to be causing problem you may also try to link without gzip libraries.

SPECIAL SYSTEMS

Below you find information on particular systems:

Windows/CygWin

If you are a user of Cygwin (the Redhat distribution) you already know, it contains a nicely running perl 5.6.1, installation of additional modules usually works as a charme via the standard procedure of

    perl makefile.PL
    make
    make test
    make install

The Windows binary distribution of MySQL runs smoothly under Cygwin. You can start/stop the server and use all Windows clients without problem. But to install DBD::mysql you have to take a little special action.

Don't attempt to build DBD::mysql against either the MySQL Windows or Linux/Unix BINARY distributions: neither will work!

You MUST compile the MySQL clients yourself under Cygwin, to get a 'libmysqlclient.a' compiled under Cygwin. Really! You'll only need that library and the header files, you don't need any other client parts. Continue to use the Windows binaries. And don't attempt (currently) to build the MySQL Server part, it is unneccessary, as MySQL AB does an excellent job to deliver optimized binaries for the mainstream operating systems, and it is told, that the server compiled under Cygwin is unstable.

Install MySQL (if you havn't already)

-

download the MySQL Windows Binaries from http://www.mysql.com/downloads/index.html

-

unzip mysql-<version>-win.zip into some temporary location

-

start the setup.exe there and follow the instructions

-

start the server

-

alternatively download, install and start the server on a remote server, on what supported OS ever

Build MySQL clients under Cygwin:

-

download the MySQL LINUX source from http://www.mysql.com/downloads/index.html

-

unpack mysql-<version>.tar.gz into some tmp location

-

cd into the unpacked dir mysql-<version>

  ./configure --prefix=/usr/local/mysql --without-server

This prepares the Makefile with the installed Cygwin features. It takes some time, but should finish without error. The 'prefix', as given, installs the whole Cygwin/MySQL thingy into a location not normally in your PATH, so that you continue to use already installed Windows binaries. The --without-server parameter tells configure to only build the clients.

-
  make

This builds all MySQL client parts ... be patient. It should finish finally without any error.

-
  make install

This installs the compiled client files under /usr/local/mysql/. Remember, you don't need anything except the library under /usr/local/mysql/lib and the headers under /usr/local/mysql/include!

Essentially you are now done with this part. If you want, you may try your compiled binaries shortly; for that, do:

-
  cd /usr/local/mysql/bin
  ./mysql -h 127.0.0.1

The host (-h) parameter 127.0.0.1 targets the local host, but forces the mysql client to use a TCP/IP connection. The default would be a pipe/socket connection (even if you say '-h localhost') and this doesn't work between Cygwin and Windows (as far as I know).

If you have your MySQL server running on some other box, then please substitute '127.0.0.1' with the name or IP-number of that box.

Please note, in my environment the 'mysql' client did not accept a simple RETURN, I had to use CTRL-RETURN to send commands ... strange, but I didn't attempt to fix that, as we are only interested in the built lib and headers.

At the 'mysql>' prompt do a quick check:

  mysql> use mysql
  mysql> show tables;
  mysql> select * from db;
  mysql> exit

You are now ready to build DBD::mysql!

Build DBD::mysql:

-

download DBD-mysql-<version>.tar.gz from CPAN

-

unpack DBD-mysql-<version>.tar.gz

-

cd into unpacked dir DBD-mysql-<version> you probably did that already, if you are reading this!

-
  cp /usr/local/mysql/bin/mysql_config .

This copies the executable script mentioned in the DBD::mysql docs from your just built Cywin/MySQL client directory; it knows about your Cygwin installation, especially about the right libraries to link with.

-
  perl Makefile.PL --testhost=127.0.0.1

The --testhost=127.0.0.1 parameter again forces a TCP/IP connection to the MySQL server on the local host instead of a pipe/socket connection for the 'make test' phase.

-
  make

This should run without error

-
  make test

with DBD-mysql-2.1022 or earlier you will see several errors in dbdadmin.t, mysql.t and mysql2.t; with later versions you should not get errors (except possibly one, indicating, that some tables could not be dropped. I'm hunting for a solution to that problem, but have none yet).

-
  make install

This installs DBD::mysql into the Perl hierarchy.

Notes:

This was tested with MySQL version 3.23.54a and DBD::mysql version 2.1022. I patched the above mentioned test scripts and sent the patches to the author of DBD::mysql Jochen Wiedman.

Georg Rehfeld 15. Jan. 2003

KNOWN PROBLEMS

  1. )

    Some Linux distributions don't come with a gzip library by default. Running "make" terminates with an error message like

      LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
    -o blib/arch/auto/DBD/mysql/mysql.so  -shared
    -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
    -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
    -lgcc -lz
  /usr/bin/ld: cannot find -lz
  collect2: ld returned 1 exit status
  make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1

    If this is the case for you, install an RPM archive like libz-devel, libgz-devel, zlib-devel or gzlib-devel or something similar.

  2. )

    If Perl was compiled with gcc or egcs, but MySQL was compiled with another compiler or on another system, an error message like this is very likely when running "Make test":

      t/00base............install_driver(mysql) failed: Can't load
  '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
  ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
  at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
  line 168.

    This means, that your linker doesn't include libgcc.a. You have the following options:

    The solution is telling the linker to use libgcc. Run

      gcc --print-libgcc-file

    to determine the exact location of libgcc.a or for older versions of gcc

      gcc -v

    to determine the directory. If you know the directory, add a

      -L<directory> -lgcc

    to the list of C compiler flags. Configuration. Linker flags.

  3. )

    There are known problems with shared versions of libmysqlclient, at least on some Linux boxes. If you receive an error message similar to

      install_driver(mysql) failed: Can't load
  '/usr/lib/perl5/site_perl/i586-linux/auto/DBD/mysql/mysql.so'
  for module DBD::mysql: File not found at
  /usr/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166

    then this error message can be misleading: It's not mysql.so that fails being loaded, but libmysqlclient.so! The usual problem is that this file is located in a directory like

      /usr/lib/mysql

    where the linker doesn't look for it.

    The best workaround is using a statically linked mysqlclient library, for example

      /usr/lib/mysql/libmysqlclient.a

    The use of a statically linked library is described in the previous section on linker flags. Configuration. Linker flags.

  4. )

    Red Hat 8 & 9 set the Default locale to UTF which causes problems with MakeMaker. To build DBD::mysql on these systems, do a 'unset LANG' before runing 'perl Makefile.PL'

SUPPORT

Finally, if everything else fails, you are not alone. First of all, for an immediate answer, you should look into the archives of the mailing list perl@lists.mysql.com. See http://www.mysql.com for archive locations.

If you don't find an appropriate posting and reply in the mailing list, please post a question. Typically a reply will be seen within one or two days.


DBI - Database independent interface for Perl

    • GETTING HELP
    • NOTES
  • DESCRIPTION
    • Architecture of a DBI Application
    • Notation and Conventions
    • Outline Usage
    • General Interface Rules & Caveats
    • Naming Conventions and Name Space
    • SQL - A Query Language
    • Placeholders and Bind Values
  • THE DBI PACKAGE AND CLASS
    • DBI Constants
    • DBI Class Methods
      • parse_dsn
      • connect
      • connect_cached
      • available_drivers
      • installed_drivers
      • installed_versions
      • data_sources
      • trace
    • DBI Utility Functions
      • data_string_desc
      • data_string_diff
      • data_diff
      • neat
      • neat_list
      • looks_like_number
      • hash
    • DBI Dynamic Attributes
      • $DBI::err
      • $DBI::errstr
      • $DBI::state
      • $DBI::rows
      • $DBI::lasth
  • METHODS COMMON TO ALL HANDLES
      • err
      • errstr
      • state
      • set_err
      • trace
      • trace_msg
      • func
      • can
      • parse_trace_flags
      • parse_trace_flag
      • private_attribute_info
      • swap_inner_handle
  • ATTRIBUTES COMMON TO ALL HANDLES
      • Warn (boolean, inherited)
      • Active (boolean, read-only)
      • Executed (boolean)
      • Kids (integer, read-only)
      • ActiveKids (integer, read-only)
      • CachedKids (hash ref)
      • Type (scalar, read-only)
      • ChildHandles (array ref)
      • CompatMode (boolean, inherited)
      • InactiveDestroy (boolean)
      • PrintWarn (boolean, inherited)
      • PrintError (boolean, inherited)
      • RaiseError (boolean, inherited)
      • HandleError (code ref, inherited)
      • HandleSetErr (code ref, inherited)
      • ErrCount (unsigned integer)
      • ShowErrorStatement (boolean, inherited)
      • TraceLevel (integer, inherited)
      • FetchHashKeyName (string, inherited)
      • ChopBlanks (boolean, inherited)
      • LongReadLen (unsigned integer, inherited)
      • LongTruncOk (boolean, inherited)
      • TaintIn (boolean, inherited)
      • TaintOut (boolean, inherited)
      • Taint (boolean, inherited)
      • Profile (inherited)
      • ReadOnly (boolean, inherited)
      • private_your_module_name_*
  • DBI DATABASE HANDLE OBJECTS
    • Database Handle Methods
      • clone
      • data_sources
      • do
      • last_insert_id
      • selectrow_array
      • selectrow_arrayref
      • selectrow_hashref
      • selectall_arrayref
      • selectall_hashref
      • selectcol_arrayref
      • prepare
      • prepare_cached
      • commit
      • rollback
      • begin_work
      • disconnect
      • ping
      • get_info
      • table_info
      • column_info
      • primary_key_info
      • primary_key
      • foreign_key_info
      • statistics_info
      • tables
      • type_info_all
      • type_info
      • quote
      • quote_identifier
      • take_imp_data
    • Database Handle Attributes
      • AutoCommit (boolean)
      • Driver (handle)
      • Name (string)
      • Statement (string, read-only)
      • RowCacheSize (integer)
      • Username (string)
  • DBI STATEMENT HANDLE OBJECTS
    • Statement Handle Methods
      • bind_param
      • bind_param_inout
      • bind_param_array
      • execute
      • execute_array
      • execute_for_fetch
      • fetchrow_arrayref
      • fetchrow_array
      • fetchrow_hashref
      • fetchall_arrayref
      • fetchall_hashref
      • finish
      • rows
      • bind_col
      • bind_columns
      • dump_results
    • Statement Handle Attributes
      • NUM_OF_FIELDS (integer, read-only)
      • NUM_OF_PARAMS (integer, read-only)
      • NAME (array-ref, read-only)
      • NAME_lc (array-ref, read-only)
      • NAME_uc (array-ref, read-only)
      • NAME_hash (hash-ref, read-only)
      • NAME_lc_hash (hash-ref, read-only)
      • NAME_uc_hash (hash-ref, read-only)
      • TYPE (array-ref, read-only)
      • PRECISION (array-ref, read-only)
      • SCALE (array-ref, read-only)
      • NULLABLE (array-ref, read-only)
      • CursorName (string, read-only)
      • Database (dbh, read-only)
      • ParamValues (hash ref, read-only)
      • ParamArrays (hash ref, read-only)
      • ParamTypes (hash ref, read-only)
      • Statement (string, read-only)
      • RowsInCache (integer, read-only)
  • FURTHER INFORMATION
    • Catalog Methods
    • Transactions
    • Handling BLOB / LONG / Memo Fields
    • Simple Examples
    • Threads and Thread Safety
    • Signal Handling and Canceling Operations
    • Subclassing the DBI
  • TRACING
    • Trace Settings
    • Trace Levels
    • Trace Flags
    • Enabling Trace
    • Trace Output
    • Tracing to Layered Filehandles
    • Trace Content
    • Tracing Tips
  • DBI ENVIRONMENT VARIABLES
    • DBI_DSN
    • DBI_DRIVER
    • DBI_AUTOPROXY
    • DBI_USER
    • DBI_PASS
    • DBI_DBNAME (obsolete)
    • DBI_TRACE
    • PERL_DBI_DEBUG (obsolete)
    • DBI_PROFILE
    • DBI_PUREPERL
  • WARNING AND ERROR MESSAGES
    • Fatal Errors
  • Pure-Perl DBI
  • SEE ALSO
    • Driver and Database Documentation
    • ODBC and SQL/CLI Standards Reference Information
    • Standards Reference Information
    • Books and Articles
    • Perl Modules
    • Mailing List
    • Assorted Related WWW Links
    • FAQ
  • AUTHORS
  • COPYRIGHT
  • SUPPORT / WARRANTY
    • Support
    • Sponsor Enhancements
  • ACKNOWLEDGEMENTS
  • CONTRIBUTING
    • Browsing the source code repository
    • How to create a patch using Subversion
    • How to create a patch without Subversion
    • Speak before you patch
  • TRANSLATIONS
  • TRAINING
  • OTHER RELATED WORK AND PERL MODULES

NAME

DBI - Database independent interface for Perl

SYNOPSIS

  use DBI;

  @driver_names = DBI->available_drivers;
  %drivers      = DBI->installed_drivers;
  @data_sources = DBI->data_sources($driver_name, \%attr);

  $dbh = DBI->connect($data_source, $username, $auth, \%attr);

  $rv  = $dbh->do($statement);
  $rv  = $dbh->do($statement, \%attr);
  $rv  = $dbh->do($statement, \%attr, @bind_values);

  $ary_ref  = $dbh->selectall_arrayref($statement);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field);

  $ary_ref  = $dbh->selectcol_arrayref($statement);
  $ary_ref  = $dbh->selectcol_arrayref($statement, \%attr);

  @row_ary  = $dbh->selectrow_array($statement);
  $ary_ref  = $dbh->selectrow_arrayref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement);

  $sth = $dbh->prepare($statement);
  $sth = $dbh->prepare_cached($statement);

  $rc = $sth->bind_param($p_num, $bind_value);
  $rc = $sth->bind_param($p_num, $bind_value, $bind_type);
  $rc = $sth->bind_param($p_num, $bind_value, \%attr);

  $rv = $sth->execute;
  $rv = $sth->execute(@bind_values);
  $rv = $sth->execute_array(\%attr, ...);

  $rc = $sth->bind_col($col_num, \$col_variable);
  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

  @row_ary  = $sth->fetchrow_array;
  $ary_ref  = $sth->fetchrow_arrayref;
  $hash_ref = $sth->fetchrow_hashref;

  $ary_ref  = $sth->fetchall_arrayref;
  $ary_ref  = $sth->fetchall_arrayref( $slice, $max_rows );

  $hash_ref = $sth->fetchall_hashref( $key_field );

  $rv  = $sth->rows;

  $rc  = $dbh->begin_work;
  $rc  = $dbh->commit;
  $rc  = $dbh->rollback;

  $quoted_string = $dbh->quote($string);

  $rc  = $h->err;
  $str = $h->errstr;
  $rv  = $h->state;

  $rc  = $dbh->disconnect;

The synopsis above only lists the major methods and parameters.

GETTING HELP

If you have questions about DBI, or DBD driver modules, you can get help from the dbi-users@perl.org mailing list. You can get help on subscribing and using the list by emailing dbi-users-help@perl.org.

To help you make the best use of the dbi-users mailing list, and any other lists or forums you may use, I strongly recommend that you read "How To Ask Questions The Smart Way" by Eric Raymond: http://www.catb.org/~esr/faqs/smart-questions.html.

If you think you've found a bug then please also read "How to Report Bugs Effectively" by Simon Tatham: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html.

The DBI home page at http://dbi.perl.org/ is always worth a visit and includes an FAQ and links to other resources.

Before asking any questions, reread this document, consult the archives and read the DBI FAQ. The archives are listed at the end of this document and on the DBI home page. An FAQ is installed as a the DBI::FAQ manpage module so you can read it by executing perldoc DBI::FAQ. However the DBI::FAQ module is currently (2004) outdated relative to the online FAQ on the DBI home page.

This document often uses terms like references, objects, methods. If you're not familar with those terms then it would be a good idea to read at least the following perl manuals first: the perlreftut manpage, the perldsc manpage, the perllol manpage, and the perlboot manpage.

Please note that Tim Bunce does not maintain the mailing lists or the web page (generous volunteers do that). So please don't send mail directly to him; he just doesn't have the time to answer questions personally. The dbi-users mailing list has lots of experienced people who should be able to help you if you need it. If you do email Tim he's very likely to just forward it to the mailing list.

NOTES

This is the DBI specification that corresponds to the DBI version 1.57 ($Revision: 9655 $).

The DBI is evolving at a steady pace, so it's good to check that you have the latest copy.

The significant user-visible changes in each release are documented in the the DBI::Changes manpage module so you can read them by executing perldoc DBI::Changes.

Some DBI changes require changes in the drivers, but the drivers can take some time to catch up. Newer versions of the DBI have added features that may not yet be supported by the drivers you use. Talk to the authors of your drivers if you need a new feature that's not yet supported.

Features added after DBI 1.21 (February 2002) are marked in the text with the version number of the DBI release they first appeared in.

Extensions to the DBI API often use the DBIx::* namespace. See Naming Conventions and Name Space. DBI extension modules can be found at http://search.cpan.org/search. And all modules related to the DBI can be found at http://search.cpan.org/search.

DESCRIPTION

The DBI is a database access module for the Perl programming language. It defines a set of methods, variables, and conventions that provide a consistent database interface, independent of the actual database being used.

It is important to remember that the DBI is just an interface. The DBI is a layer of "glue" between an application and one or more database driver modules. It is the driver modules which do most of the real work. The DBI provides a standard interface and framework for the drivers to operate within.

Architecture of a DBI Application

             |<- Scope of DBI ->|
                  .-.   .--------------.   .-------------.
  .-------.       | |---| XYZ Driver   |---| XYZ Engine  |
  | Perl  |       | |   `--------------'   `-------------'
  | script|  |A|  |D|   .--------------.   .-------------.
  | using |--|P|--|B|---|Oracle Driver |---|Oracle Engine|
  | DBI   |  |I|  |I|   `--------------'   `-------------'
  | API   |       | |...
  |methods|       | |... Other drivers
  `-------'       | |...
                  `-'

The API, or Application Programming Interface, defines the call interface and variables for Perl scripts to use. The API is implemented by the Perl DBI extension.

The DBI "dispatches" the method calls to the appropriate driver for actual execution. The DBI is also responsible for the dynamic loading of drivers, error checking and handling, providing default implementations for methods, and many other non-database specific duties.

Each driver contains implementations of the DBI methods using the private interface functions of the corresponding database engine. Only authors of sophisticated/multi-database applications or generic library functions need be concerned with drivers.

Notation and Conventions

The following conventions are used in this document:

  $dbh    Database handle object
  $sth    Statement handle object
  $drh    Driver handle object (rarely seen or used in applications)
  $h      Any of the handle types above ($dbh, $sth, or $drh)
  $rc     General Return Code  (boolean: true=ok, false=error)
  $rv     General Return Value (typically an integer)
  @ary    List of values returned from the database, typically a row of data
  $rows   Number of rows processed (if available, else -1)
  $fh     A filehandle
  undef   NULL values are represented by undefined values in Perl
  \%attr  Reference to a hash of attribute values passed to methods

Note that Perl will automatically destroy database and statement handle objects if all references to them are deleted.

Outline Usage

To use DBI, first you need to load the DBI module:

  use DBI;
  use strict;

(The use strict; isn't required but is strongly recommended.)

Then you need to connect to your data source and get a handle for that connection:

  $dbh = DBI->connect($dsn, $user, $password,
                      { RaiseError => 1, AutoCommit => 0 });

Since connecting can be expensive, you generally just connect at the start of your program and disconnect at the end.

Explicitly defining the required AutoCommit behaviour is strongly recommended and may become mandatory in a later version. This determines whether changes are automatically committed to the database when executed, or need to be explicitly committed later.

The DBI allows an application to "prepare" statements for later execution. A prepared statement is identified by a statement handle held in a Perl variable. We'll call the Perl variable $sth in our examples.

The typical method call sequence for a SELECT statement is:

  prepare,
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...

for example:

  $sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?");

  $sth->execute( $baz );

  while ( @row = $sth->fetchrow_array ) {
    print "@row\n";
  }

The typical method call sequence for a non-SELECT statement is:

  prepare,
    execute,
    execute,
    execute.

for example:

  $sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)");

  while(<CSV>) {
    chomp;
    my ($foo,$bar,$baz) = split /,/;
        $sth->execute( $foo, $bar, $baz );
  }

The do() method can be used for non repeated non-SELECT statement (or with drivers that don't support placeholders):

  $rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1");

To commit your changes to the database (when AutoCommit is off):

  $dbh->commit;  # or call $dbh->rollback; to undo changes

Finally, when you have finished working with the data source, you should disconnect from it:

  $dbh->disconnect;

General Interface Rules & Caveats

The DBI does not have a concept of a "current session". Every session has a handle object (i.e., a $dbh) returned from the connect method. That handle object is used to invoke database related methods.

Most data is returned to the Perl script as strings. (Null values are returned as undef.) This allows arbitrary precision numeric data to be handled without loss of accuracy. Beware that Perl may not preserve the same accuracy when the string is used as a number.

Dates and times are returned as character strings in the current default format of the corresponding database engine. Time zone effects are database/driver dependent.

Perl supports binary data in Perl strings, and the DBI will pass binary data to and from the driver without change. It is up to the driver implementors to decide how they wish to handle such binary data.

Perl supports two kinds of strings: unicode (utf8 internally) and non-unicode (defaults to iso-8859-1 if forced to assume an encoding). Drivers should accept both kinds of strings and, if required, convert them to the character set of the database being used. Similarly, when fetching from the database character data that isn't iso-8859-1 the driver should convert it into utf8.

Multiple SQL statements may not be combined in a single statement handle ($sth), although some databases and drivers do support this (notably Sybase and SQL Server).

Non-sequential record reads are not supported in this version of the DBI. In other words, records can only be fetched in the order that the database returned them, and once fetched they are forgotten.

Positioned updates and deletes are not directly supported by the DBI. See the description of the CursorName attribute for an alternative.

Individual driver implementors are free to provide any private functions and/or handle attributes that they feel are useful. Private driver functions can be invoked using the DBI func() method. Private driver attributes are accessed just like standard attributes.

Many methods have an optional \%attr parameter which can be used to pass information to the driver implementing the method. Except where specifically documented, the \%attr parameter can only be used to pass driver specific hints. In general, you can ignore \%attr parameters or pass it as undef.

Naming Conventions and Name Space

The DBI package and all packages below it (DBI::*) are reserved for use by the DBI. Extensions and related modules use the DBIx:: namespace (see http://www.perl.com/CPAN/modules/by-module/DBIx/). Package names beginning with DBD:: are reserved for use by DBI database drivers. All environment variables used by the DBI or by individual DBDs begin with "DBI_" or "DBD_".

The letter case used for attribute names is significant and plays an important part in the portability of DBI scripts. The case of the attribute name is used to signify who defined the meaning of that name and its values.

  Case of name  Has a meaning defined by
  ------------  ------------------------
  UPPER_CASE    Standards, e.g.,  X/Open, ISO SQL92 etc (portable)
  MixedCase     DBI API (portable), underscores are not used.
  lower_case    Driver or database engine specific (non-portable)

It is of the utmost importance that Driver developers only use lowercase attribute names when defining private attributes. Private attribute names must be prefixed with the driver name or suitable abbreviation (e.g., "ora_" for Oracle, "ing_" for Ingres, etc).

SQL - A Query Language

Most DBI drivers require applications to use a dialect of SQL (Structured Query Language) to interact with the database engine. The Standards Reference Information section provides links to useful information about SQL.

The DBI itself does not mandate or require any particular language to be used; it is language independent. In ODBC terms, the DBI is in "pass-thru" mode, although individual drivers might not be. The only requirement is that queries and other statements must be expressed as a single string of characters passed as the first argument to the prepare or do methods.

For an interesting diversion on the real history of RDBMS and SQL, from the people who made it happen, see:

  http://ftp.digital.com/pub/DEC/SRC/technical-notes/SRC-1997-018-html/sqlr95.html

Follow the "Full Contents" then "Intergalactic dataspeak" links for the SQL history.

Placeholders and Bind Values

Some drivers support placeholders and bind values. Placeholders, also called parameter markers, are used to indicate values in a database statement that will be supplied later, before the prepared statement is executed. For example, an application might use the following to insert a row of data into the SALES table:

  INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)

or the following, to select the description for a product:

  SELECT description FROM products WHERE product_code = ?

The ? characters are the placeholders. The association of actual values with placeholders is known as binding, and the values are referred to as bind values.

Note that the ? is not enclosed in quotation marks, even when the placeholder represents a string. Some drivers also allow placeholders like :name and :n (e.g., :1, :2, and so on) in addition to ?, but their use is not portable.

With most drivers, placeholders can't be used for any element of a statement that would prevent the database server from validating the statement and creating a query execution plan for it. For example:

  "SELECT name, age FROM ?"         # wrong (will probably fail)
  "SELECT name, ?   FROM people"    # wrong (but may not 'fail')

Also, placeholders can only represent single scalar values. For example, the following statement won't work as expected for more than one value:

  "SELECT name, age FROM people WHERE name IN (?)"    # wrong
  "SELECT name, age FROM people WHERE name IN (?,?)"  # two names

When using placeholders with the SQL LIKE qualifier, you must remember that the placeholder substitutes for the whole string. So you should use "... LIKE ? ..." and include any wildcard characters in the value that you bind to the placeholder.

NULL Values

Undefined values, or undef, are used to indicate NULL values. You can insert and update columns with a NULL value as you would a non-NULL value. These examples insert and update the column age with a NULL value:

  $sth = $dbh->prepare(qq{
    INSERT INTO people (fullname, age) VALUES (?, ?)
  });
  $sth->execute("Joe Bloggs", undef);

  $sth = $dbh->prepare(qq{
    UPDATE people SET age = ? WHERE fullname = ?
  });
  $sth->execute(undef, "Joe Bloggs");

However, care must be taken when trying to use NULL values in a WHERE clause. Consider:

  SELECT fullname FROM people WHERE age = ?

Binding an undef (NULL) to the placeholder will not select rows which have a NULL age! At least for database engines that conform to the SQL standard. Refer to the SQL manual for your database engine or any SQL book for the reasons for this. To explicitly select NULLs you have to say "WHERE age IS NULL".

A common issue is to have a code fragment handle a value that could be either defined or undef (non-NULL or NULL) at runtime. A simple technique is to prepare the appropriate statement as needed, and substitute the placeholder for non-NULL cases:

  $sql_clause = defined $age? "age = ?" : "age IS NULL";
  $sth = $dbh->prepare(qq{
    SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(defined $age ? $age : ());

The following technique illustrates qualifying a WHERE clause with several columns, whose associated values (defined or undef) are in a hash %h:

  for my $col ("age", "phone", "email") {
    if (defined $h{$col}) {
      push @sql_qual, "$col = ?";
      push @sql_bind, $h{$col};
    }
    else {
      push @sql_qual, "$col IS NULL";
    }
  }
  $sql_clause = join(" AND ", @sql_qual);
  $sth = $dbh->prepare(qq{
      SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(@sql_bind);

The techniques above call prepare for the SQL statement with each call to execute. Because calls to prepare() can be expensive, performance can suffer when an application iterates many times over statements like the above.

A better solution is a single WHERE clause that supports both NULL and non-NULL comparisons. Its SQL statement would need to be prepared only once for all cases, thus improving performance. Several examples of WHERE clauses that support this are presented below. But each example lacks portability, robustness, or simplicity. Whether an example is supported on your database engine depends on what SQL extensions it provides, and where it supports the ? placeholder in a statement.

  0)  age = ?
  1)  NVL(age, xx) = NVL(?, xx)
  2)  ISNULL(age, xx) = ISNULL(?, xx)
  3)  DECODE(age, ?, 1, 0) = 1
  4)  age = ? OR (age IS NULL AND ? IS NULL)
  5)  age = ? OR (age IS NULL AND SP_ISNULL(?) = 1)
  6)  age = ? OR (age IS NULL AND ? = 1)

Statements formed with the above WHERE clauses require execute statements as follows. The arguments are required, whether their values are defined or undef.

  0,1,2,3)  $sth->execute($age);
  4,5)      $sth->execute($age, $age);
  6)        $sth->execute($age, defined($age) ? 0 : 1);

Example 0 should not work (as mentioned earlier), but may work on a few database engines anyway (e.g. Sybase). Example 0 is part of examples 4, 5, and 6, so if example 0 works, these other examples may work, even if the engine does not properly support the right hand side of the OR expression.

Examples 1 and 2 are not robust: they require that you provide a valid column value xx (e.g. '~') which is not present in any row. That means you must have some notion of what data won't be stored in the column, and expect clients to adhere to that.

Example 5 requires that you provide a stored procedure (SP_ISNULL in this example) that acts as a function: it checks whether a value is null, and returns 1 if it is, or 0 if not.

Example 6, the least simple, is probably the most portable, i.e., it should work with with most, if not all, database engines.

Here is a table that indicates which examples above are known to work on various database engines:

                   -----Examples------
                   0  1  2  3  4  5  6
                   -  -  -  -  -  -  -
  Oracle 9         N  Y  N  Y  Y  ?  Y
  Informix IDS 9   N  N  N  Y  N  Y  Y
  MS SQL           N  N  Y  N  Y  ?  Y
  Sybase           Y  N  N  N  N  N  Y
  AnyData,DBM,CSV  Y  N  N  N  Y  Y* Y
  SQLite 3.3       N  N  N  N  Y  N  N

* Works only because Example 0 works.

DBI provides a sample perl script that will test the examples above on your database engine and tell you which ones work. It is located in the ex/ subdirectory of the DBI source distribution, or here: http://svn.perl.org/modules/dbi/trunk/ex/perl_dbi_nulls_test.pl Please use the script to help us fill-in and maintain this table.

Performance

Without using placeholders, the insert statement shown previously would have to contain the literal values to be inserted and would have to be re-prepared and re-executed for each row. With placeholders, the insert statement only needs to be prepared once. The bind values for each row can be given to the execute method each time it's called. By avoiding the need to re-prepare the statement for each row, the application typically runs many times faster. Here's an example:

  my $sth = $dbh->prepare(q{
    INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)
  }) or die $dbh->errstr;
  while (<>) {
      chomp;
      my ($product_code, $qty, $price) = split /,/;
      $sth->execute($product_code, $qty, $price) or die $dbh->errstr;
  }
  $dbh->commit or die $dbh->errstr;

See execute and bind_param for more details.

The q{...} style quoting used in this example avoids clashing with quotes that may be used in the SQL statement. Use the double-quote like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

See also the bind_columns method, which is used to associate Perl variables with the output columns of a SELECT statement.

THE DBI PACKAGE AND CLASS

In this section, we cover the DBI class methods, utility functions, and the dynamic attributes associated with generic DBI handles.

DBI Constants

Constants representing the values of the SQL standard types can be imported individually by name, or all together by importing the special :sql_types tag.

The names and values of all the defined SQL standard types can be produced like this:

  foreach (@{ $DBI::EXPORT_TAGS{sql_types} }) {
    printf "%s=%d\n", $_, &{"DBI::$_"};
  }

These constants are defined by SQL/CLI, ODBC or both. SQL_BIGINT is (currently) omitted, because SQL/CLI and ODBC provide conflicting codes.

See the type_info, type_info_all, and bind_param methods for possible uses.

Note that just because the DBI defines a named constant for a given data type doesn't mean that drivers will support that data type.

DBI Class Methods

The following methods are provided by the DBI class:

parse_dsn

  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn) = DBI->parse_dsn($dsn)
      or die "Can't parse DBI DSN '$dsn'";

Breaks apart a DBI Data Source Name (DSN) and returns the individual parts. If $dsn doesn't contain a valid DSN then parse_dsn() returns an empty list.

$scheme is the first part of the DSN and is currently always 'dbi'. $driver is the driver name, possibly defaulted to $ENV{DBI_DRIVER}, and may be undefined. $attr_string is the contents of the optional attribute string, which may be undefined. If $attr_string is not empty then $attr_hash is a reference to a hash containing the parsed attribute names and values. $driver_dsn is the last part of the DBI DSN string. For example:

  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn)
      = DBI->parse_dsn("DBI:MyDriver(RaiseError=>1):db=test;port=42");
  $scheme      = 'dbi';
  $driver      = 'MyDriver';
  $attr_string = 'RaiseError=>1';
  $attr_hash   = { 'RaiseError' => '1' };
  $driver_dsn  = 'db=test;port=42';

The parse_dsn() method was added in DBI 1.43.

connect

  $dbh = DBI->connect($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

Establishes a database connection, or session, to the requested $data_source. Returns a database handle object if the connection succeeds. Use $dbh->disconnect to terminate the connection.

If the connect fails (see below), it returns undef and sets both $DBI::err and $DBI::errstr. (It does not explicitly set $!.) You should generally test the return status of connect and print $DBI::errstr if it has failed.

Multiple simultaneous connections to multiple databases through multiple drivers can be made via the DBI. Simply make one connect call for each database and keep a copy of each returned database handle.

The $data_source value must begin with "dbi:driver_name:". The driver_name specifies the driver that will be used to make the connection. (Letter case is significant.)

As a convenience, if the $data_source parameter is undefined or empty, the DBI will substitute the value of the environment variable DBI_DSN. If just the driver_name part is empty (i.e., the $data_source prefix is "dbi::"), the environment variable DBI_DRIVER is used. If neither variable is set, then connect dies.

Examples of $data_source values are:

  dbi:DriverName:database_name
  dbi:DriverName:database_name@hostname:port
  dbi:DriverName:database=database_name;host=hostname;port=port

There is no standard for the text following the driver name. Each driver is free to use whatever syntax it wants. The only requirement the DBI makes is that all the information is supplied in a single string. You must consult the documentation for the drivers you are using for a description of the syntax they require.

It is recommended that drivers support the ODBC style, shown in the last example above. It is also recommended that that they support the three common names 'host', 'port', and 'database' (plus 'db' as an alias for database). This simplifies automatic construction of basic DSNs: "dbi:$driver:database=$db;host=$host;port=$port". Drivers should aim to 'do something reasonable' when given a DSN in this form, but if any part is meaningless for that driver (such as 'port' for Informix) it should generate an error if that part is not empty.

If the environment variable DBI_AUTOPROXY is defined (and the driver in $data_source is not "Proxy") then the connect request will automatically be changed to:

  $ENV{DBI_AUTOPROXY};dsn=$data_source

DBI_AUTOPROXY is typically set as "dbi:Proxy:hostname=...;port=...". If $ENV{DBI_AUTOPROXY} doesn't begin with 'dbi:' then "dbi:Proxy:" will be prepended to it first. See the DBD::Proxy documentation for more details.

If $username or $password are undefined (rather than just empty), then the DBI will substitute the values of the DBI_USER and DBI_PASS environment variables, respectively. The DBI will warn if the environment variables are not defined. However, the everyday use of these environment variables is not recommended for security reasons. The mechanism is primarily intended to simplify testing. See below for alternative way to specify the username and password.

DBI->connect automatically installs the driver if it has not been installed yet. Driver installation either returns a valid driver handle, or it dies with an error message that includes the string "install_driver" and the underlying problem. So DBI->connect will die on a driver installation failure and will only return undef on a connect failure, in which case $DBI::errstr will hold the error message. Use eval { ... } if you need to catch the "install_driver" error.

The $data_source argument (with the "dbi:...:" prefix removed) and the $username and $password arguments are then passed to the driver for processing. The DBI does not define any interpretation for the contents of these fields. The driver is free to interpret the $data_source, $username, and $password fields in any way, and supply whatever defaults are appropriate for the engine being accessed. (Oracle, for example, uses the ORACLE_SID and TWO_TASK environment variables if no $data_source is specified.)

The AutoCommit and PrintError attributes for each connection default to "on". (See AutoCommit and PrintError for more information.) However, it is strongly recommended that you explicitly define AutoCommit rather than rely on the default. The PrintWarn attribute defaults to on if $^W is true, i.e., perl is running with warnings enabled.

The \%attr parameter can be used to alter the default settings of PrintError, RaiseError, AutoCommit, and other attributes. For example:

  $dbh = DBI->connect($data_source, $user, $pass, {
        PrintError => 0,
        AutoCommit => 0
  });

The username and password can also be specified using the attributes Username and Password, in which case they take precedence over the $username and $password parameters.

You can also define connection attribute values within the $data_source parameter. For example:

  dbi:DriverName(PrintWarn=>1,PrintError=>0,Taint=>1):...

Individual attributes values specified in this way take precedence over any conflicting values specified via the \%attr parameter to connect.

The dbi_connect_method attribute can be used to specify which driver method should be called to establish the connection. The only useful values are 'connect', 'connect_cached', or some specialized case like 'Apache::DBI::connect' (which is automatically the default when running within Apache).

Where possible, each session ($dbh) is independent from the transactions in other sessions. This is useful when you need to hold cursors open across transactions--for example, if you use one session for your long lifespan cursors (typically read-only) and another for your short update transactions.

For compatibility with old DBI scripts, the driver can be specified by passing its name as the fourth argument to connect (instead of \%attr):

  $dbh = DBI->connect($data_source, $user, $pass, $driver);

In this "old-style" form of connect, the $data_source should not start with "dbi:driver_name:". (If it does, the embedded driver_name will be ignored). Also note that in this older form of connect, the $dbh->{AutoCommit} attribute is undefined, the $dbh->{PrintError} attribute is off, and the old DBI_DBNAME environment variable is checked if DBI_DSN is not defined. Beware that this "old-style" connect will soon be withdrawn in a future version of DBI.

connect_cached

  $dbh = DBI->connect_cached($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect_cached($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

connect_cached is like connect, except that the database handle returned is also stored in a hash associated with the given parameters. If another call is made to connect_cached with the same parameter values, then the corresponding cached $dbh will be returned if it is still valid. The cached database handle is replaced with a new connection if it has been disconnected or if the ping method fails.

That the behaviour of this method differs in several respects from the behaviour of persistent connections implemented by Apache::DBI. However, if Apache::DBI is loaded then connect_cached will use it.

Caching connections can be useful in some applications, but it can also cause problems, such as too many connections, and so should be used with care. In particular, avoid changing the attributes of a database handle created via connect_cached() because it will affect other code that may be using the same handle.

Where multiple separate parts of a program are using connect_cached() to connect to the same database with the same (initial) attributes it is a good idea to add a private attribute to the connect_cached() call to effectively limit the scope of the caching. For example:

  DBI->connect_cached(..., { private_foo_cachekey => "Bar", ... });

Handles returned from that connect_cached() call will only be returned by other connect_cached() call elsewhere in the code if those other calls also pass in the same attribute values, including the private one. (I've used private_foo_cachekey here as an example, you can use any attribute name with a private_ prefix.)

Taking that one step further, you can limit a particular connect_cached() call to return handles unique to that one place in the code by setting the private attribute to a unique value for that place:

  DBI->connect_cached(..., { private_foo_cachekey => __FILE__.__LINE__, ... });

By using a private attribute you still get connection caching for the individual calls to connect_cached() but, by making separate database conections for separate parts of the code, the database handles are isolated from any attribute changes made to other handles.

The cache can be accessed (and cleared) via the CachedKids attribute:

  my $CachedKids_hashref = $dbh->{Driver}->{CachedKids};
  %$CachedKids_hashref = () if $CachedKids_hashref;

available_drivers

  @ary = DBI->available_drivers;
  @ary = DBI->available_drivers($quiet);

Returns a list of all available drivers by searching for DBD::* modules through the directories in @INC. By default, a warning is given if some drivers are hidden by others of the same name in earlier directories. Passing a true value for $quiet will inhibit the warning.

installed_drivers

  %drivers = DBI->installed_drivers();

Returns a list of driver name and driver handle pairs for all drivers 'installed' (loaded) into the current process. The driver name does not include the 'DBD::' prefix.

To get a list of all drivers available in your perl instalation you can use available_drivers.

Added in DBI 1.49.

installed_versions

  DBI->installed_versions;
  @ary  = DBI->installed_versions;
  %hash = DBI->installed_versions;

Calls available_drivers() and attempts to load each of them in turn using install_driver(). For each load that succeeds the driver name and version number are added to a hash. When running under the DBI::PurePerl manpage drivers which appear not be pure-perl are ignored.

When called in array context the list of successfully loaded drivers is returned (without the 'DBD::' prefix).

When called in scalar context a reference to the hash is returned and the hash will also contain other entries for the DBI version, OS name, etc.

When called in a void context the installed_versions() method will print out a formatted list of the hash contents, one per line.

Due to the potentially high memory cost and unknown risks of loading in an unknown number of drivers that just happen to be installed on the system, this method is not recommended for general use. Use available_drivers() instead.

The installed_versions() method is primarily intended as a quick way to see from the command line what's installed. For example:

  perl -MDBI -e 'DBI->installed_versions'

The installed_versions() method was added in DBI 1.38.

data_sources

  @ary = DBI->data_sources($driver);
  @ary = DBI->data_sources($driver, \%attr);

Returns a list of data sources (databases) available via the named driver. If $driver is empty or undef, then the value of the DBI_DRIVER environment variable is used.

The driver will be loaded if it hasn't been already. Note that if the driver loading fails then data_sources() dies with an error message that includes the string "install_driver" and the underlying problem.

Data sources are returned in a form suitable for passing to the connect method (that is, they will include the "dbi:$driver:" prefix).

Note that many drivers have no way of knowing what data sources might be available for it. These drivers return an empty or incomplete list or may require driver-specific attributes.

There is also a data_sources() method defined for database handles.

trace

  DBI->trace($trace_setting)
  DBI->trace($trace_setting, $trace_filename)
  DBI->trace($trace_setting, $trace_filehandle)
  $trace_setting = DBI->trace;

The DBI->trace method sets the global default trace settings and returns the previous trace settings. It can also be used to change where the trace output is sent.

There's a similar method, $h->trace, which sets the trace settings for the specific handle it's called on.

See the TRACING section for full details about the DBI's powerful tracing facilities.

DBI Utility Functions

In addition to the DBI methods listed in the previous section, the DBI package also provides several utility functions.

These can be imported into your code by listing them in the use statement. For example:

  use DBI qw(neat data_diff);

Alternatively, all these utility functions (except hash) can be imported using the :utils import tag. For example:

  use DBI qw(:utils);

data_string_desc

  $description = data_string_desc($string);

Returns an informal description of the string. For example:

  UTF8 off, ASCII, 42 characters 42 bytes
  UTF8 off, non-ASCII, 42 characters 42 bytes
  UTF8 on, non-ASCII, 4 characters 6 bytes
  UTF8 on but INVALID encoding, non-ASCII, 4 characters 6 bytes
  UTF8 off, undef

The initial UTF8 on/off refers to Perl's internal SvUTF8 flag. If $string has the SvUTF8 flag set but the sequence of bytes it contains are not a valid UTF-8 encoding then data_string_desc() will report UTF8 on but INVALID encoding.

The ASCII vs non-ASCII portion shows ASCII if all the characters in the string are ASCII (have code points <= 127).

The data_string_desc() function was added in DBI 1.46.

data_string_diff

  $diff = data_string_diff($a, $b);

Returns an informal description of the first character difference between the strings. If both $a and $b contain the same sequence of characters then data_string_diff() returns an empty string. For example:

 Params a & b     Result
 ------------     ------
 'aaa', 'aaa'     ''
 'aaa', 'abc'     'Strings differ at index 2: a[2]=a, b[2]=b'
 'aaa', undef     'String b is undef, string a has 3 characters'
 'aaa', 'aa'      'String b truncated after 2 characters'

Unicode characters are reported in \x{XXXX} format. Unicode code points in the range U+0800 to U+08FF are unassigned and most likely to occur due to double-encoding. Characters in this range are reported as \x{08XX}='C' where C is the corresponding latin-1 character.

The data_string_diff() function only considers logical characters and not the underlying encoding. See data_diff for an alternative.

The data_string_diff() function was added in DBI 1.46.

data_diff

  $diff = data_diff($a, $b);
  $diff = data_diff($a, $b, $logical);

Returns an informal description of the difference between two strings. It calls data_string_desc and data_string_diff and returns the combined results as a multi-line string.

For example, data_diff("abc", "ab\x{263a}") will return:

  a: UTF8 off, ASCII, 3 characters 3 bytes
  b: UTF8 on, non-ASCII, 3 characters 5 bytes
  Strings differ at index 2: a[2]=c, b[2]=\x{263A}

If $a and $b are identical in both the characters they contain and their physical encoding then data_diff() returns an empty string. If $logical is true then physical encoding differences are ignored (but are still reported if there is a difference in the characters).

The data_diff() function was added in DBI 1.46.

neat

  $str = neat($value);
  $str = neat($value, $maxlen);

Return a string containing a neat (and tidy) representation of the supplied value.

Strings will be quoted, although internal quotes will not be escaped. Values known to be numeric will be unquoted. Undefined (NULL) values will be shown as undef (without quotes).

If the string is flagged internally as utf8 then double quotes will be used, otherwise single quotes are used and unprintable characters will be replaced by dot (.).

For result strings longer than $maxlen the result string will be truncated to $maxlen-4 and "...'" will be appended. If $maxlen is 0 or undef, it defaults to $DBI::neat_maxlen which, in turn, defaults to 400.

This function is designed to format values for human consumption. It is used internally by the DBI for trace output. It should typically not be used for formatting values for database use. (See also quote.)

neat_list

  $str = neat_list(\@listref, $maxlen, $field_sep);

Calls neat on each element of the list and returns a string containing the results joined with $field_sep. $field_sep defaults to ", ".

looks_like_number

  @bool = looks_like_number(@array);

Returns true for each element that looks like a number. Returns false for each element that does not look like a number. Returns undef for each element that is undefined or empty.

hash

  $hash_value = DBI::hash($buffer, $type);

Return a 32-bit integer 'hash' value corresponding to the contents of $buffer. The $type parameter selects which kind of hash algorithm should be used.

For the technically curious, type 0 (which is the default if $type isn't specified) is based on the Perl 5.1 hash except that the value is forced to be negative (for obscure historical reasons). Type 1 is the better "Fowler / Noll / Vo" (FNV) hash. See http://www.isthe.com/chongo/tech/comp/fnv/ for more information. Both types are implemented in C and are very fast.

This function doesn't have much to do with databases, except that it can be handy to store hash values in a database.

DBI Dynamic Attributes

Dynamic attributes are always associated with the last handle used (that handle is represented by $h in the descriptions below).

Where an attribute is equivalent to a method call, then refer to the method call for all related documentation.

Warning: these attributes are provided as a convenience but they do have limitations. Specifically, they have a short lifespan: because they are associated with the last handle used, they should only be used immediately after calling the method that "sets" them. If in any doubt, use the corresponding method call.

$DBI::err

Equivalent to $h->err.

$DBI::errstr

Equivalent to $h->errstr.

$DBI::state

Equivalent to $h->state.

$DBI::rows

Equivalent to $h->rows. Please refer to the documentation for the rows method.

$DBI::lasth

Returns the DBI object handle used for the most recent DBI method call. If the last DBI method call was a DESTROY then $DBI::lasth will return the handle of the parent of the destroyed handle, if there is one.

METHODS COMMON TO ALL HANDLES

The following methods can be used by all types of DBI handles.

err

  $rv = $h->err;

Returns the native database engine error code from the last driver method called. The code is typically an integer but you should not assume that.

The DBI resets $h->err to undef before almost all DBI method calls, so the value only has a short lifespan. Also, for most drivers, the statement handles share the same error variable as the parent database handle, so calling a method on one handle may reset the error on the related handles.

(Methods which don't reset err before being called include err() and errstr(), obviously, state(), rows(), func(), trace(), trace_msg(), ping(), and the tied hash attribute FETCH() and STORE() methods.)

If you need to test for specific error conditions and have your program be portable to different database engines, then you'll need to determine what the corresponding error codes are for all those engines and test for all of them.

A driver may return 0 from err() to indicate a warning condition after a method call. Similarly, a driver may return an empty string to indicate a 'success with information' condition. In both these cases the value is false but not undef. The errstr() and state() methods may be used to retrieve extra information in these cases.

See set_err for more information.

errstr

  $str = $h->errstr;

Returns the native database engine error message from the last DBI method called. This has the same lifespan issues as the err method described above.

The returned string may contain multiple messages separated by newline characters.

The errstr() method should not be used to test for errors, use err() for that, because drivers may return 'success with information' or warning messages via errstr() for methods that have not 'failed'.

See set_err for more information.

state

  $str = $h->state;

Returns a state code in the standard SQLSTATE five character format. Note that the specific success code 00000 is translated to any empty string (false). If the driver does not support SQLSTATE (and most don't), then state() will return S1000 (General Error) for all errors.

The driver is free to return any value via state, e.g., warning codes, even if it has not declared an error by returning a true value via the err method described above.

The state() method should not be used to test for errors, use err() for that, because drivers may return a 'success with information' or warning state code via state() for methods that have not 'failed'.

set_err

  $rv = $h->set_err($err, $errstr);
  $rv = $h->set_err($err, $errstr, $state);
  $rv = $h->set_err($err, $errstr, $state, $method);
  $rv = $h->set_err($err, $errstr, $state, $method, $rv);

Set the err, errstr, and state values for the handle. This method is typically only used by DBI drivers and DBI subclasses.

If the HandleSetErr attribute holds a reference to a subroutine it is called first. The subroutine can alter the $err, $errstr, $state, and $method values. See HandleSetErr for full details. If the subroutine returns a true value then the handle err, errstr, and state values are not altered and set_err() returns an empty list (it normally returns $rv which defaults to undef, see below).

Setting err to a true value indicates an error and will trigger the normal DBI error handling mechanisms, such as RaiseError and HandleError, if they are enabled, when execution returns from the DBI back to the application.

Setting err to "" indicates an 'information' state, and setting it to "0" indicates a 'warning' state. Setting err to undef also sets errstr to undef, and state to "", irrespective of the values of the $errstr and $state parameters.

The $method parameter provides an alternate method name for the RaiseError/PrintError/PrintWarn error string instead of the fairly unhelpful 'set_err'.

The set_err method normally returns undef. The $rv parameter provides an alternate return value.

Some special rules apply if the err or errstr values for the handle are already set...

If errstr is true then: " [err was %s now %s]" is appended if $err is true and err is already true and the new err value differs from the original one. Similarly " [state was %s now %s]" is appended if $state is true and state is already true and the new state value differs from the original one. Finally "\n" and the new $errstr are appended if $errstr differs from the existing errstr value. Obviously the %s's above are replaced by the corresponding values.

The handle err value is set to $err if: $err is true; or handle err value is undef; or $err is defined and the length is greater than the handle err length. The effect is that an 'information' state only overrides undef; a 'warning' overrides undef or 'information', and an 'error' state overrides anything.

The handle state value is set to $state if $state is true and the handle err value was set (by the rules above).

Support for warning and information states was added in DBI 1.41.

trace

  $h->trace($trace_settings);
  $h->trace($trace_settings, $trace_filename);
  $trace_settings = $h->trace;

The trace() method is used to alter the trace settings for a handle (and any future children of that handle). It can also be used to change where the trace output is sent.

There's a similar method, DBI->trace, which sets the global default trace settings.

See the TRACING section for full details about the DBI's powerful tracing facilities.

trace_msg

  $h->trace_msg($message_text);
  $h->trace_msg($message_text, $min_level);

Writes $message_text to the trace file if the trace level is greater than or equal to $min_level (which defaults to 1). Can also be called as DBI->trace_msg($msg).

See TRACING for more details.

func

  $h->func(@func_arguments, $func_name) or die ...;

The func method can be used to call private non-standard and non-portable methods implemented by the driver. Note that the function name is given as the last argument.

It's also important to note that the func() method does not clear a previous error ($DBI::err etc.) and it does not trigger automatic error detection (RaiseError etc.) so you must check the return status and/or $h->err to detect errors.

(This method is not directly related to calling stored procedures. Calling stored procedures is currently not defined by the DBI. Some drivers, such as DBD::Oracle, support it in non-portable ways. See driver documentation for more details.)

See also install_method() in the DBI::DBD manpage for how you can avoid needing to use func() and gain direct access to driver-private methods.

can

  $is_implemented = $h->can($method_name);

Returns true if $method_name is implemented by the driver or a default method is provided by the DBI. It returns false where a driver hasn't implemented a method and the default method is provided by the DBI is just an empty stub.

parse_trace_flags

  $trace_settings_integer = $h->parse_trace_flags($trace_settings);

Parses a string containing trace settings and returns the corresponding integer value used internally by the DBI and drivers.

The $trace_settings argument is a string containing a trace level between 0 and 15 and/or trace flag names separated by vertical bar ("|") or comma (",") characters. For example: "SQL|3|foo".

It uses the parse_trace_flag() method, described below, to process the individual trage flag names.

The parse_trace_flags() method was added in DBI 1.42.

parse_trace_flag

  $bit_flag = $h->parse_trace_flag($trace_flag_name);

Returns the bit flag corresponding to the trace flag name in $trace_flag_name. Drivers are expected to override this method and check if $trace_flag_name is a driver specific trace flags and, if not, then call the DBIs default parse_trace_flag().

The parse_trace_flag() method was added in DBI 1.42.

private_attribute_info

  $hash_ref = $h->private_attribute_info();

Returns a reference to a hash whose keys are the names of driver-private attributes available for the kind of handle (driver, database, statement) that the method was called on.

For example, the return value when called with a DBD::Sybase $dbh could look like this:

  {
      syb_dynamic_supported => undef,
      syb_oc_version => undef,
      syb_server_version => undef,
      syb_server_version_string => undef,
  }

and when called with a DBD::Sybase $sth they could look like this:

  {
      syb_types => undef,
      syb_proc_status => undef,
      syb_result_type => undef,
  }

The values should be undef. Meanings may be assigned to particular values in future.

swap_inner_handle

  $rc = $h1->swap_inner_handle( $h2 );
  $rc = $h1->swap_inner_handle( $h2, $allow_reparent );

Brain transplants for handles. You don't need to know about this unless you want to become a handle surgeon.

A DBI handle is a reference to a tied hash. A tied hash has an inner hash that actually holds the contents. The swap_inner_handle() method swaps the inner hashes between two handles. The $h1 and $h2 handles still point to the same tied hashes, but what those hashes are tied to has been swapped. In effect $h1 becomes $h2 and vice-versa. This is powerful stuff, expect problems. Use with care.

As a small safety measure, the two handles, $h1 and $h2, have to share the same parent unless $allow_reparent is true.

The swap_inner_handle() method was added in DBI 1.44.

Here's a quick kind of 'diagram' as a worked example to help think about what's happening:

    Original state:
            dbh1o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh2o -> dbh2i
    swap_inner_handle dbh1o with dbh2o:
            dbh2o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh1o -> dbh2i
    create new sth from dbh1o:
            dbh2o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh1o -> dbh2i
            sthBo -> sthBi(dbh2i)
    swap_inner_handle sthAo with sthBo:
            dbh2o -> dbh1i
            sthBo -> sthAi(dbh1i)
            dbh1o -> dbh2i
            sthAo -> sthBi(dbh2i)

ATTRIBUTES COMMON TO ALL HANDLES

These attributes are common to all types of DBI handles.

Some attributes are inherited by child handles. That is, the value of an inherited attribute in a newly created statement handle is the same as the value in the parent database handle. Changes to attributes in the new statement handle do not affect the parent database handle and changes to the database handle do not affect existing statement handles, only future ones.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver specific attributes (which all have names starting with a lowercase letter).

Example:

  $h->{AttributeName} = ...;    # set/write
  ... = $h->{AttributeName};    # get/read

Warn (boolean, inherited)

The Warn attribute enables useful warnings for certain bad practices. It is enabled by default and should only be disabled in rare circumstances. Since warnings are generated using the Perl warn function, they can be intercepted using the Perl $SIG{__WARN__} hook.

The Warn attribute is not related to the PrintWarn attribute.

Active (boolean, read-only)

The Active attribute is true if the handle object is "active". This is rarely used in applications. The exact meaning of active is somewhat vague at the moment. For a database handle it typically means that the handle is connected to a database ($dbh->disconnect sets Active off). For a statement handle it typically means that the handle is a SELECT that may have more data to fetch. (Fetching all the data or calling $sth->finish sets Active off.)

Executed (boolean)

The Executed attribute is true if the handle object has been "executed". Currently only the $dbh do() method and the $sth execute(), execute_array(), and execute_for_fetch() methods set the Executed attribute.

When it's set on a handle it is also set on the parent handle at the same time. So calling execute() on a $sth also sets the Executed attribute on the parent $dbh.

The Executed attribute for a database handle is cleared by the commit() and rollback() methods (even if they fail). The Executed attribute of a statement handle is not cleared by the DBI under any circumstances and so acts as a permanent record of whether the statement handle was ever used.

The Executed attribute was added in DBI 1.41.

Kids (integer, read-only)

For a driver handle, Kids is the number of currently existing database handles that were created from that driver handle. For a database handle, Kids is the number of currently existing statement handles that were created from that database handle. For a statement handle, the value is zero.

ActiveKids (integer, read-only)

Like Kids, but only counting those that are Active (as above).

CachedKids (hash ref)

For a database handle, CachedKids returns a reference to the cache (hash) of statement handles created by the prepare_cached method. For a driver handle, returns a reference to the cache (hash) of database handles created by the connect_cached method.

Type (scalar, read-only)

The Type attribute identifies the type of a DBI handle. Returns "dr" for driver handles, "db" for database handles and "st" for statement handles.

ChildHandles (array ref)

The ChildHandles attribute contains a reference to an array of all the handles created by this handle which are still accessible. The contents of the array are weak-refs and will become undef when the handle goes out of scope.

ChildHandles returns undef if your perl version does not support weak references (check the Scalar::Util module). The referenced array returned should be treated as read-only.

For example, to enumerate all driver handles, database handles and statement handles:

    sub show_child_handles {
        my ($h, $level) = @_;
        $level ||= 0;
        printf "%sh %s %s\n", $h->{Type}, "\t" x $level, $h;
        show_child_handles($_, $level + 1)
            for (grep { defined } @{$h->{ChildHandles}});
    }

    my %drivers = DBI->installed_drivers();
    show_child_handles($_) for (values %drivers);

CompatMode (boolean, inherited)

The CompatMode attribute is used by emulation layers (such as Oraperl) to enable compatible behaviour in the underlying driver (e.g., DBD::Oracle) for this handle. Not normally set by application code.

It also has the effect of disabling the 'quick FETCH' of attribute values from the handles attribute cache. So all attribute values are handled by the drivers own FETCH method. This makes them slightly slower but is useful for special-purpose drivers like DBD::Multiplex.

InactiveDestroy (boolean)

The default value, false, means a handle will be fully destroyed as normal when the last reference to it is removed, just as you'd expect.

If set true then the handle will be treated by the DESTROY as if it was no longer Active, and so the database engine related effects of DESTROYing a handle will be skipped.

Think of the name as meaning 'treat the handle as not-Active in the DESTROY method'.

For a database handle, this attribute does not disable an explicit call to the disconnect method, only the implicit call from DESTROY that happens if the handle is still marked as Active.

This attribute is specifically designed for use in Unix applications that "fork" child processes. Either the parent or the child process, but not both, should set InactiveDestroy true on all their shared handles. (Note that some databases, including Oracle, don't support passing a database connection across a fork.)

To help tracing applications using fork the process id is shown in the trace log whenever a DBI or handle trace() method is called. The process id also shown for every method call if the DBI trace level (not handle trace level) is set high enough to show the trace from the DBI's method dispatcher, e.g. >= 9.

PrintWarn (boolean, inherited)

The PrintWarn attribute controls the printing of warnings recorded by the driver. When set to a true value the DBI will check method calls to see if a warning condition has been set. If so, the DBI will effectively do a warn("$class $method warning: $DBI::errstr") where $class is the driver class and $method is the name of the method which failed. E.g.,

  DBD::Oracle::db execute warning: ... warning text here ...

By default, DBI->connect sets PrintWarn "on" if $^W is true, i.e., perl is running with warnings enabled.

If desired, the warnings can be caught and processed using a $SIG{__WARN__} handler or modules like CGI::Carp and CGI::ErrorWrap.

See also set_err for how warnings are recorded and HandleSetErr for how to influence it.

Fetching the full details of warnings can require an extra round-trip to the database server for some drivers. In which case the driver may opt to only fetch the full details of warnings if the PrintWarn attribute is true. If PrintWarn is false then these drivers should still indicate the fact that there were warnings by setting the warning string to, for example: "3 warnings".

PrintError (boolean, inherited)

The PrintError attribute can be used to force errors to generate warnings (using warn) in addition to returning error codes in the normal way. When set "on", any method which results in an error occuring will cause the DBI to effectively do a warn("$class $method failed: $DBI::errstr") where $class is the driver class and $method is the name of the method which failed. E.g.,

  DBD::Oracle::db prepare failed: ... error text here ...

By default, DBI->connect sets PrintError "on".

If desired, the warnings can be caught and processed using a $SIG{__WARN__} handler or modules like CGI::Carp and CGI::ErrorWrap.

RaiseError (boolean, inherited)

The RaiseError attribute can be used to force errors to raise exceptions rather than simply return error codes in the normal way. It is "off" by default. When set "on", any method which results in an error will cause the DBI to effectively do a die("$class $method failed: $DBI::errstr"), where $class is the driver class and $method is the name of the method that failed. E.g.,

  DBD::Oracle::db prepare failed: ... error text here ...

If you turn RaiseError on then you'd normally turn PrintError off. If PrintError is also on, then the PrintError is done first (naturally).

Typically RaiseError is used in conjunction with eval { ... } to catch the exception that's been thrown and followed by an if ($@) { ... } block to handle the caught exception. For example:

  eval {
    ...
    $sth->execute();
    ...
  };
  if ($@) {
    # $sth->err and $DBI::err will be true if error was from DBI
    warn $@; # print the error
    ... # do whatever you need to deal with the error
  }

In that eval block the $DBI::lasth variable can be useful for diagnosis and reporting if you can't be sure which handle triggered the error. For example, $DBI::lasth->{Type} and $DBI::lasth->{Statement}.

See also Transactions.

If you want to temporarily turn RaiseError off (inside a library function that is likely to fail, for example), the recommended way is like this:

  {
    local $h->{RaiseError};  # localize and turn off for this block
    ...
  }

The original value will automatically and reliably be restored by Perl, regardless of how the block is exited. The same logic applies to other attributes, including PrintError.

HandleError (code ref, inherited)

The HandleError attribute can be used to provide your own alternative behaviour in case of errors. If set to a reference to a subroutine then that subroutine is called when an error is detected (at the same point that RaiseError and PrintError are handled).

The subroutine is called with three parameters: the error message string that RaiseError and PrintError would use, the DBI handle being used, and the first value being returned by the method that failed (typically undef).

If the subroutine returns a false value then the RaiseError and/or PrintError attributes are checked and acted upon as normal.

For example, to die with a full stack trace for any error:

  use Carp;
  $h->{HandleError} = sub { confess(shift) };

Or to turn errors into exceptions:

  use Exception; # or your own favourite exception module
  $h->{HandleError} = sub { Exception->new('DBI')->raise($_[0]) };

It is possible to 'stack' multiple HandleError handlers by using closures:

  sub your_subroutine {
    my $previous_handler = $h->{HandleError};
    $h->{HandleError} = sub {
      return 1 if $previous_handler and &$previous_handler(@_);
      ... your code here ...
    };
  }

Using a my inside a subroutine to store the previous HandleError value is important. See the perlsub manpage and the perlref manpage for more information about closures.

It is possible for HandleError to alter the error message that will be used by RaiseError and PrintError if it returns false. It can do that by altering the value of $_[0]. This example appends a stack trace to all errors and, unlike the previous example using Carp::confess, this will work PrintError as well as RaiseError:

  $h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; };

It is also possible for HandleError to hide an error, to a limited degree, by using set_err to reset $DBI::err and $DBI::errstr, and altering the return value of the failed method. For example:

  $h->{HandleError} = sub {
    return 0 unless $_[0] =~ /^\S+ fetchrow_arrayref failed:/;
    return 0 unless $_[1]->err == 1234; # the error to 'hide'
    $h->set_err(undef,undef);   # turn off the error
    $_[2] = [ ... ];    # supply alternative return value
    return 1;
  };

This only works for methods which return a single value and is hard to make reliable (avoiding infinite loops, for example) and so isn't recommended for general use! If you find a good use for it then please let me know.

HandleSetErr (code ref, inherited)

The HandleSetErr attribute can be used to intercept the setting of handle err, errstr, and state values. If set to a reference to a subroutine then that subroutine is called whenever set_err() is called, typically by the driver or a subclass.

The subroutine is called with five arguments, the first five that were passed to set_err(): the handle, the err, errstr, and state values being set, and the method name. These can be altered by changing the values in the @_ array. The return value affects set_err() behaviour, see set_err for details.

It is possible to 'stack' multiple HandleSetErr handlers by using closures. See HandleError for an example.

The HandleSetErr and HandleError subroutines differ in subtle but significant ways. HandleError is only invoked at the point where the DBI is about to return to the application with err set true. It's not invoked by the failure of a method that's been called by another DBI method. HandleSetErr, on the other hand, is called whenever set_err() is called with a defined err value, even if false. So it's not just for errors, despite the name, but also warn and info states. The set_err() method, and thus HandleSetErr, may be called multiple times within a method and is usually invoked from deep within driver code.

In theory a driver can use the return value from HandleSetErr via set_err() to decide whether to continue or not. If set_err() returns an empty list, indicating that the HandleSetErr code has 'handled' the 'error', the driver could then continue instead of failing (if that's a reasonable thing to do). This isn't excepted to be common and any such cases should be clearly marked in the driver documentation and discussed on the dbi-dev mailing list.

The HandleSetErr attribute was added in DBI 1.41.

ErrCount (unsigned integer)

The ErrCount attribute is incremented whenever the set_err() method records an error. It isn't incremented by warnings or information states. It is not reset by the DBI at any time.

The ErrCount attribute was added in DBI 1.41. Older drivers may not have been updated to use set_err() to record errors and so this attribute may not be incremented when using them.

ShowErrorStatement (boolean, inherited)

The ShowErrorStatement attribute can be used to cause the relevant Statement text to be appended to the error messages generated by the RaiseError, PrintError, and PrintWarn attributes. Only applies to errors on statement handles plus the prepare(), do(), and the various select*() database handle methods. (The exact format of the appended text is subject to change.)

If $h->{ParamValues} returns a hash reference of parameter (placeholder) values then those are formatted and appended to the end of the Statement text in the error message.

TraceLevel (integer, inherited)

The TraceLevel attribute can be used as an alternative to the trace method to set the DBI trace level and trace flags for a specific handle. See TRACING for more details.

The TraceLevel attribute is especially useful combined with local to alter the trace settings for just a single block of code.

FetchHashKeyName (string, inherited)

The FetchHashKeyName attribute is used to specify whether the fetchrow_hashref() method should perform case conversion on the field names used for the hash keys. For historical reasons it defaults to 'NAME' but it is recommended to set it to 'NAME_lc' (convert to lower case) or 'NAME_uc' (convert to upper case) according to your preference. It can only be set for driver and database handles. For statement handles the value is frozen when prepare() is called.

ChopBlanks (boolean, inherited)

The ChopBlanks attribute can be used to control the trimming of trailing space characters from fixed width character (CHAR) fields. No other field types are affected, even where field values have trailing spaces.

The default is false (although it is possible that the default may change). Applications that need specific behaviour should set the attribute as needed.

Drivers are not required to support this attribute, but any driver which does not support it must arrange to return undef as the attribute value.

LongReadLen (unsigned integer, inherited)

The LongReadLen attribute may be used to control the maximum length of 'long' type fields (LONG, BLOB, CLOB, MEMO, etc.) which the driver will read from the database automatically when it fetches each row of data.

The LongReadLen attribute only relates to fetching and reading long values; it is not involved in inserting or updating them.

A value of 0 means not to automatically fetch any long data. Drivers may return undef or an empty string for long fields when LongReadLen is 0.

The default is typically 0 (zero) bytes but may vary between drivers. Applications fetching long fields should set this value to slightly larger than the longest long field value to be fetched.

Some databases return some long types encoded as pairs of hex digits. For these types, LongReadLen relates to the underlying data length and not the doubled-up length of the encoded string.

Changing the value of LongReadLen for a statement handle after it has been prepare'd will typically have no effect, so it's common to set LongReadLen on the $dbh before calling prepare.

For most drivers the value used here has a direct effect on the memory used by the statement handle while it's active, so don't be too generous. If you can't be sure what value to use you could execute an extra select statement to determine the longest value. For example:

  $dbh->{LongReadLen} = $dbh->selectrow_array(qq{
      SELECT MAX(OCTET_LENGTH(long_column_name))
      FROM table WHERE ...
  });
  $sth = $dbh->prepare(qq{
      SELECT long_column_name, ... FROM table WHERE ...
  });

You may need to take extra care if the table can be modified between the first select and the second being executed. You may also need to use a different function if OCTET_LENGTH() does not work for long types in your database. For example, for Sybase use DATALENGTH() and for Oracle use LENGTHB().

See also LongTruncOk for information on truncation of long types.

LongTruncOk (boolean, inherited)

The LongTruncOk attribute may be used to control the effect of fetching a long field value which has been truncated (typically because it's longer than the value of the LongReadLen attribute).

By default, LongTruncOk is false and so fetching a long value that needs to be truncated will cause the fetch to fail. (Applications should always be sure to check for errors after a fetch loop in case an error, such as a divide by zero or long field truncation, caused the fetch to terminate prematurely.)

If a fetch fails due to a long field truncation when LongTruncOk is false, many drivers will allow you to continue fetching further rows.

See also LongReadLen.

TaintIn (boolean, inherited)

If the TaintIn attribute is set to a true value and Perl is running in taint mode (e.g., started with the -T option), then all the arguments to most DBI method calls are checked for being tainted. This may change.

The attribute defaults to off, even if Perl is in taint mode. See the perlsec manpage for more about taint mode. If Perl is not running in taint mode, this attribute has no effect.

When fetching data that you trust you can turn off the TaintIn attribute, for that statement handle, for the duration of the fetch loop.

The TaintIn attribute was added in DBI 1.31.

TaintOut (boolean, inherited)

If the TaintOut attribute is set to a true value and Perl is running in taint mode (e.g., started with the -T option), then most data fetched from the database is considered tainted. This may change.

The attribute defaults to off, even if Perl is in taint mode. See the perlsec manpage for more about taint mode. If Perl is not running in taint mode, this attribute has no effect.

When fetching data that you trust you can turn off the TaintOut attribute, for that statement handle, for the duration of the fetch loop.

Currently only fetched data is tainted. It is possible that the results of other DBI method calls, and the value of fetched attributes, may also be tainted in future versions. That change may well break your applications unless you take great care now. If you use DBI Taint mode, please report your experience and any suggestions for changes.

The TaintOut attribute was added in DBI 1.31.

Taint (boolean, inherited)

The Taint attribute is a shortcut for TaintIn and TaintOut (it is also present for backwards compatibility).

Setting this attribute sets both TaintIn and TaintOut, and retrieving it returns a true value if and only if TaintIn and TaintOut are both set to true values.

Profile (inherited)

The Profile attribute enables the collection and reporting of method call timing statistics. See the the DBI::Profile manpage module documentation for much more detail.

The Profile attribute was added in DBI 1.24.

ReadOnly (boolean, inherited)

An application can set the ReadOnly attribute of a handle to a true value to indicate that it will not be attempting to make any changes using that handle or any children of it.

Note that the exact definition of 'read only' is rather fuzzy. For more details see the documentation for the driver you're using.

If the driver can make the handle truly read-only (by issuing a statement like "set transaction read only" as needed, for example) then it should. Otherwise the attribute is simply advisory.

A driver can set the ReadOnly attribute itself to indicate that the data it is connected to cannot be changed for some reason.

Library modules and proxy drivers can use the attribute to influence their behavior. For example, the DBD::Gofer driver considers the ReadOnly attribute when making a decison about whether to retry an operation that failed.

The attribute should be set to 1 or 0 (or undef). Other values are reserved.

private_your_module_name_*

The DBI provides a way to store extra information in a DBI handle as "private" attributes. The DBI will allow you to store and retrieve any attribute which has a name starting with "private_".

It is strongly recommended that you use just one private attribute (e.g., use a hash ref) and give it a long and unambiguous name that includes the module or application name that the attribute relates to (e.g., "private_YourFullModuleName_thingy").

Because of the way the Perl tie mechanism works you cannot reliably use the ||= operator directly to initialise the attribute, like this:

  my $foo = $dbh->{private_yourmodname_foo} ||= { ... }; # WRONG

you should use a two step approach like this:

  my $foo = $dbh->{private_yourmodname_foo};
  $foo ||= $dbh->{private_yourmodname_foo} = { ... };

This attribute is primarily of interest to people sub-classing DBI, or for applications to piggy-back extra information onto DBI handles.

DBI DATABASE HANDLE OBJECTS

This section covers the methods and attributes associated with database handles.

Database Handle Methods

The following methods are specified for DBI database handles:

clone

  $new_dbh = $dbh->clone();
  $new_dbh = $dbh->clone(\%attr);

The clone method duplicates the $dbh connection by connecting with the same parameters ($dsn, $user, $password) as originally used.

The attributes for the cloned connect are the same as those used for the original connect, with some other attribute merged over them depending on the \%attr parameter.

If \%attr is given then the attributes it contains are merged into the original attributes and override any with the same names. Effectively the same as doing:

  %attribues_used = ( %original_attributes, %attr );

If \%attr is not given then it defaults to a hash containing all the attributes in the attribute cache of $dbh excluding any non-code references, plus the main boolean attributes (RaiseError, PrintError, AutoCommit, etc.). This behaviour is subject to change.

The clone method can be used even if the database handle is disconnected.

The clone method was added in DBI 1.33. It is very new and likely to change.

data_sources

  @ary = $dbh->data_sources();
  @ary = $dbh->data_sources(\%attr);

Returns a list of data sources (databases) available via the $dbh driver's data_sources() method, plus any extra data sources that the driver can discover via the connected $dbh. Typically the extra data sources are other databases managed by the same server process that the $dbh is connected to.

Data sources are returned in a form suitable for passing to the connect method (that is, they will include the "dbi:$driver:" prefix).

The data_sources() method, for a $dbh, was added in DBI 1.38.

do

  $rows = $dbh->do($statement)           or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr)   or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr, @bind_values) or die ...

Prepare and execute a single statement. Returns the number of rows affected or undef on error. A return value of -1 means the number of rows is not known, not applicable, or not available.

This method is typically most useful for non-SELECT statements that either cannot be prepared in advance (due to a limitation of the driver) or do not need to be executed repeatedly. It should not be used for SELECT statements because it does not return a statement handle (so you can't fetch any data).

The default do method is logically similar to:

  sub do {
      my($dbh, $statement, $attr, @bind_values) = @_;
      my $sth = $dbh->prepare($statement, $attr) or return undef;
      $sth->execute(@bind_values) or return undef;
      my $rows = $sth->rows;
      ($rows == 0) ? "0E0" : $rows; # always return true if no error
  }

For example:

  my $rows_deleted = $dbh->do(q{
      DELETE FROM table
      WHERE status = ?
  }, undef, 'DONE') or die $dbh->errstr;

Using placeholders and @bind_values with the do method can be useful because it avoids the need to correctly quote any variables in the $statement. But if you'll be executing the statement many times then it's more efficient to prepare it once and call execute many times instead.

The q{...} style quoting used in this example avoids clashing with quotes that may be used in the SQL statement. Use the double-quote-like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

last_insert_id

  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field);
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr);

Returns a value 'identifying' the row just inserted, if possible. Typically this would be a value assigned by the database server to a column with an auto_increment or serial type. Returns undef if the driver does not support the method or can't determine the value.

The $catalog, $schema, $table, and $field parameters may be required for some drivers (see below). If you don't know the parameter values and your driver does not need them, then use undef for each.

There are several caveats to be aware of with this method if you want to use it for portable applications:

* For some drivers the value may only available immediately after the insert statement has executed (e.g., mysql, Informix).

* For some drivers the $catalog, $schema, $table, and $field parameters are required, for others they are ignored (e.g., mysql).

* Drivers may return an indeterminate value if no insert has been performed yet.

* For some drivers the value may only be available if placeholders have not been used (e.g., Sybase, MS SQL). In this case the value returned would be from the last non-placeholder insert statement.

* Some drivers may need driver-specific hints about how to get the value. For example, being told the name of the database 'sequence' object that holds the value. Any such hints are passed as driver-specific attributes in the \%attr parameter.

* If the underlying database offers nothing better, then some drivers may attempt to implement this method by executing "select max($field) from $table". Drivers using any approach like this should issue a warning if AutoCommit is true because it is generally unsafe - another process may have modified the table between your insert and the select. For situations where you know it is safe, such as when you have locked the table, you can silence the warning by passing Warn => 0 in \%attr.

* If no insert has been performed yet, or the last insert failed, then the value is implementation defined.

Given all the caveats above, it's clear that this method must be used with care.

The last_insert_id method was added in DBI 1.38.

selectrow_array

  @row_ary = $dbh->selectrow_array($statement);
  @row_ary = $dbh->selectrow_array($statement, \%attr);
  @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_array into a single call. If called in a list context, it returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_array will return an empty list.

If called in a scalar context for a statement handle that has more than one column, it is undefined whether the driver will return the value of the first column or the last. So don't do that. Also, in a scalar context, an undef is returned if there are no more rows or if an error occurred. That undef can't be distinguished from an undef returned because the first field value was NULL. For these reasons you should exercise some caution if you use selectrow_array in a scalar context, or just don't do that.

selectrow_arrayref

  $ary_ref = $dbh->selectrow_arrayref($statement);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_arrayref into a single call. It returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_array will return undef.

selectrow_hashref

  $hash_ref = $dbh->selectrow_hashref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_hashref into a single call. It returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_hashref will return undef.

selectall_arrayref

  $ary_ref = $dbh->selectall_arrayref($statement);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchall_arrayref into a single call. It returns a reference to an array containing a reference to an array (or hash, see below) for each row of data fetched.

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

If RaiseError is not set and any method except fetchall_arrayref fails then selectall_arrayref will return undef; if fetchall_arrayref fails then it will return with whatever data has been fetched thus far. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

The fetchall_arrayref method called by selectall_arrayref supports a $max_rows parameter. You can specify a value for $max_rows by including a 'MaxRows' attribute in \%attr. In which case finish() is called for you after fetchall_arrayref() returns.

The fetchall_arrayref method called by selectall_arrayref also supports a $slice parameter. You can specify a value for $slice by including a 'Slice' or 'Columns' attribute in \%attr. The only difference between the two is that if Slice is not defined and Columns is an array ref, then the array is assumed to contain column index values (which count from 1), rather than perl array index values. In which case the array is copied and each value decremented before passing to /fetchall_arrayref.

You may often want to fetch an array of rows where each row is stored as a hash. That can be done simple using:

  my $emps = $dbh->selectall_arrayref(
      "SELECT ename FROM emp ORDER BY ename",
      { Slice => {} }
  );
  foreach my $emp ( @$emps ) {
      print "Employee: $emp->{ename}\n";
  }

Or, to fetch into an array instead of an array ref:

  @result = @{ $dbh->selectall_arrayref($sql, { Slice => {} }) };

See fetchall_arrayref method for more details.

selectall_hashref

  $hash_ref = $dbh->selectall_hashref($statement, $key_field);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_values);

This utility method combines prepare, execute and fetchall_hashref into a single call. It returns a reference to a hash containing one entry, at most, for each row, as returned by fetchall_hashref().

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

The $key_field parameter defines which column, or columns, are used as keys in the returned hash. It can either be the name of a single field, or a reference to an array containing multiple field names. Using multiple names yields a tree of nested hashes.

If a row has the same key as an earlier row then it replaces the earlier row.

If any method except fetchrow_hashref fails, and RaiseError is not set, selectall_hashref will return undef. If fetchrow_hashref fails and RaiseError is not set, then it will return with whatever data it has fetched thus far. $DBI::err should be checked to catch that.

See fetchall_hashref() for more details.

selectcol_arrayref

  $ary_ref = $dbh->selectcol_arrayref($statement);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute, and fetching one column from all the rows, into a single call. It returns a reference to an array containing the values of the first column from each row.

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

If any method except fetch fails, and RaiseError is not set, selectcol_arrayref will return undef. If fetch fails and RaiseError is not set, then it will return with whatever data it has fetched thus far. $DBI::err should be checked to catch that.

The selectcol_arrayref method defaults to pushing a single column value (the first) from each row into the result array. However, it can also push another column, or even multiple columns per row, into the result array. This behaviour can be specified via a 'Columns' attribute which must be a ref to an array containing the column number or numbers to use. For example:

  # get array of id and name pairs:
  my $ary_ref = $dbh->selectcol_arrayref("select id, name from table", { Columns=>[1,2] });
  my %hash = @$ary_ref; # build hash from key-value pairs so $hash{$id} => name

You can specify a maximum number of rows to fetch by including a 'MaxRows' attribute in \%attr.

prepare

  $sth = $dbh->prepare($statement)          or die $dbh->errstr;
  $sth = $dbh->prepare($statement, \%attr)  or die $dbh->errstr;

Prepares a statement for later execution by the database engine and returns a reference to a statement handle object.

The returned statement handle can be used to get attributes of the statement and invoke the execute method. See Statement Handle Methods.

Drivers for engines without the concept of preparing a statement will typically just store the statement in the returned handle and process it when $sth->execute is called. Such drivers are unlikely to give much useful information about the statement, such as $sth->{NUM_OF_FIELDS}, until after $sth->execute has been called. Portable applications should take this into account.

In general, DBI drivers do not parse the contents of the statement (other than simply counting any Placeholders). The statement is passed directly to the database engine, sometimes known as pass-thru mode. This has advantages and disadvantages. On the plus side, you can access all the functionality of the engine being used. On the downside, you're limited if you're using a simple engine, and you need to take extra care if writing applications intended to be portable between engines.

Portable applications should not assume that a new statement can be prepared and/or executed while still fetching results from a previous statement.

Some command-line SQL tools use statement terminators, like a semicolon, to indicate the end of a statement. Such terminators should not normally be used with the DBI.

prepare_cached

  $sth = $dbh->prepare_cached($statement)
  $sth = $dbh->prepare_cached($statement, \%attr)
  $sth = $dbh->prepare_cached($statement, \%attr, $if_active)

Like prepare except that the statement handle returned will be stored in a hash associated with the $dbh. If another call is made to prepare_cached with the same $statement and %attr parameter values, then the corresponding cached $sth will be returned without contacting the database server.

The $if_active parameter lets you adjust the behaviour if an already cached statement handle is still Active. There are several alternatives:

  1. 0: A warning will be generated, and finish() will be called on the statement handle before it is returned. This is the default behaviour if $if_active is not passed.
  2. 1: finish() will be called on the statement handle, but the warning is suppressed.
  3. 2: Disables any checking.
  4. 3: The existing active statement handle will be removed from the cache and a new statement handle prepared and cached in its place. This is the safest option because it doesn't affect the state of the old handle, it just removes it from the cache. [Added in DBI 1.40]

Here are some examples of prepare_cached:

  sub insert_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $sql = sprintf "insert into %s (%s) values (%s)",
        $table, join(",", @fields), join(",", ("?")x@fields);
    my $sth = $dbh->prepare_cached($sql);
    return $sth->execute(@values);
  }

  sub search_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $qualifier = "";
    $qualifier = "where ".join(" and ", map { "$_=?" } @fields) if @fields;
    $sth = $dbh->prepare_cached("SELECT * FROM $table $qualifier");
    return $dbh->selectall_arrayref($sth, {}, @values);
  }

Caveat emptor: This caching can be useful in some applications, but it can also cause problems and should be used with care. Here is a contrived case where caching would cause a significant problem:

  my $sth = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
  $sth->execute(...);
  while (my $data = $sth->fetchrow_hashref) {

    # later, in some other code called within the loop...
    my $sth2 = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
    $sth2->execute(...);
    while (my $data2 = $sth2->fetchrow_arrayref) {
      do_stuff(...);
    }
      }

In this example, since both handles are preparing the exact same statement, $sth2 will not be its own statement handle, but a duplicate of $sth returned from the cache. The results will certainly not be what you expect. Typically the the inner fetch loop will work normally, fetching all the records and terminating when there are no more, but now $sth is the same as $sth2 the outer fetch loop will also terminate.

You'll know if you run into this problem because prepare_cached() will generate a warning by default (when $if_active is false).

The cache used by prepare_cached() is keyed by both the statement and any attributes so you can also avoid this issue by doing something like:

  $sth = $dbh->prepare_cached("...", { dbi_dummy => __FILE__.__LINE__ });

which will ensure that prepare_cached only returns statements cached by that line of code in that source file.

If you'd like the cache to managed intelligently, you can tie the hashref returned by CachedKids to an appropriate caching module, such as the Tie::Cache::LRU manpage:

  my $cache = $dbh->{CachedKids};
  tie %$cache, 'Tie::Cache::LRU', 500;

commit

  $rc  = $dbh->commit     or die $dbh->errstr;

Commit (make permanent) the most recent series of database changes if the database supports transactions and AutoCommit is off.

If AutoCommit is on, then calling commit will issue a "commit ineffective with AutoCommit" warning.

See also Transactions in the FURTHER INFORMATION section below.

rollback

  $rc  = $dbh->rollback   or die $dbh->errstr;

Rollback (undo) the most recent series of uncommitted database changes if the database supports transactions and AutoCommit is off.

If AutoCommit is on, then calling rollback will issue a "rollback ineffective with AutoCommit" warning.

See also Transactions in the FURTHER INFORMATION section below.

begin_work

  $rc  = $dbh->begin_work   or die $dbh->errstr;

Enable transactions (by turning AutoCommit off) until the next call to commit or rollback. After the next commit or rollback, AutoCommit will automatically be turned on again.

If AutoCommit is already off when begin_work is called then it does nothing except return an error. If the driver does not support transactions then when begin_work attempts to set AutoCommit off the driver will trigger a fatal error.

See also Transactions in the FURTHER INFORMATION section below.

disconnect

  $rc = $dbh->disconnect  or warn $dbh->errstr;

Disconnects the database from the database handle. disconnect is typically only used before exiting the program. The handle is of little use after disconnecting.

The transaction behaviour of the disconnect method is, sadly, undefined. Some database systems (such as Oracle and Ingres) will automatically commit any outstanding changes, but others (such as Informix) will rollback any outstanding changes. Applications not using AutoCommit should explicitly call commit or rollback before calling disconnect.

The database is automatically disconnected by the DESTROY method if still connected when there are no longer any references to the handle. The DESTROY method for each driver should implicitly call rollback to undo any uncommitted changes. This is vital behaviour to ensure that incomplete transactions don't get committed simply because Perl calls DESTROY on every object before exiting. Also, do not rely on the order of object destruction during "global destruction", as it is undefined.

Generally, if you want your changes to be commited or rolled back when you disconnect, then you should explicitly call commit or rollback before disconnecting.

If you disconnect from a database while you still have active statement handles (e.g., SELECT statement handles that may have more data to fetch), you will get a warning. The warning may indicate that a fetch loop terminated early, perhaps due to an uncaught error. To avoid the warning call the finish method on the active handles.

ping

  $rc = $dbh->ping;

Attempts to determine, in a reasonably efficient way, if the database server is still running and the connection to it is still working. Individual drivers should implement this function in the most suitable manner for their database engine.

The current default implementation always returns true without actually doing anything. Actually, it returns "0 but true" which is true but zero. That way you can tell if the return value is genuine or just the default. Drivers should override this method with one that does the right thing for their type of database.

Few applications would have direct use for this method. See the specialized Apache::DBI module for one example usage.

get_info

  $value = $dbh->get_info( $info_type );

Returns information about the implementation, i.e. driver and data source capabilities, restrictions etc. It returns undef for unknown or unimplemented information types. For example:

  $database_version  = $dbh->get_info(  18 ); # SQL_DBMS_VER
  $max_select_tables = $dbh->get_info( 106 ); # SQL_MAXIMUM_TABLES_IN_SELECT

See Standards Reference Information for more detailed information about the information types and their meanings and possible return values.

The DBI::Const::GetInfoType module exports a %GetInfoType hash that can be used to map info type names to numbers. For example:

  $database_version = $dbh->get_info( $GetInfoType{SQL_DBMS_VER} );

The names are a merging of the ANSI and ODBC standards (which differ in some cases). See the DBI::Const::GetInfoType manpage for more details.

Because some DBI methods make use of get_info(), drivers are strongly encouraged to support at least the following very minimal set of information types to ensure the DBI itself works properly:

 Type  Name                        Example A     Example B
 ----  --------------------------  ------------  ----------------
   17  SQL_DBMS_NAME               'ACCESS'      'Oracle'
   18  SQL_DBMS_VER                '03.50.0000'  '08.01.0721 ...'
   29  SQL_IDENTIFIER_QUOTE_CHAR   '`'           '"'
   41  SQL_CATALOG_NAME_SEPARATOR  '.'           '@'
  114  SQL_CATALOG_LOCATION        1             2

table_info

  $sth = $dbh->table_info( $catalog, $schema, $table, $type );
  $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Returns an active statement handle that can be used to fetch information about tables and views that exist in the database.

The arguments $catalog, $schema and $table may accept search patterns according to the database/driver, for example: $table = '%FOO%'; Remember that the underscore character ('_') is a search pattern that means match any character, so 'FOO_%' is the same as 'FOO%' and 'FOO_BAR%' will match names like 'FOO1BAR'.

The value of $type is a comma-separated list of one or more types of tables to be returned in the result set. Each value may optionally be quoted, e.g.:

  $type = "TABLE";
  $type = "'TABLE','VIEW'";

In addition the following special cases may also be supported by some drivers:

  • If the value of $catalog is '%' and $schema and $table name are empty strings, the result set contains a list of catalog names. For example:
      $sth = $dbh->table_info('%', '', '');
  • If the value of $schema is '%' and $catalog and $table are empty strings, the result set contains a list of schema names.
  • If the value of $type is '%' and $catalog, $schema, and $table are all empty strings, the result set contains a list of table types.

If your driver doesn't support one or more of the selection filter parameters then you may get back more than you asked for and can do the filtering yourself.

This method can be expensive, and can return a large amount of data. (For example, small Oracle installation returns over 2000 rows.) So it's a good idea to use the filters to limit the data as much as possible.

The statement handle returned has at least the following fields in the order show below. Other fields, after these, may also be present.

TABLE_CAT: Table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is usually the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The name of the schema containing the TABLE_NAME value. This field is NULL (undef) if not applicable to data source, and empty if not applicable to the table.

TABLE_NAME: Name of the table (or view, synonym, etc).

TABLE_TYPE: One of the following: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" or a type identifier that is specific to the data source.

REMARKS: A description of the table. May be NULL (undef).

Note that table_info might not return records for all tables. Applications can use any valid table regardless of whether it's returned by table_info.

See also tables, Catalog Methods and Standards Reference Information.

column_info

  $sth = $dbh->column_info( $catalog, $schema, $table, $column );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Returns an active statement handle that can be used to fetch information about columns in specified tables.

The arguments $schema, $table and $column may accept search patterns according to the database/driver, for example: $table = '%FOO%';

Note: The support for the selection criteria is driver specific. If the driver doesn't support one or more of them then you may get back more than you asked for and can do the filtering yourself.

If the arguments don't match any tables then you'll still get a statement handle, it'll just return no rows.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier. Note: A driver may provide column metadata not only for base tables, but also for derived objects like SYNONYMS etc.

COLUMN_NAME: The column identifier.

DATA_TYPE: The concise data type code.

TYPE_NAME: A data source dependent data type name.

COLUMN_SIZE: The column size. This is the maximum length in characters for character data types, the number of digits or bits for numeric data types or the length in the representation of temporal types. See the relevant specifications for detailed information.

BUFFER_LENGTH: The length in bytes of transferred data.

DECIMAL_DIGITS: The total number of significant digits to the right of the decimal point.

NUM_PREC_RADIX: The radix for numeric precision. The value is 10 or 2 for numeric data types and NULL (undef) if not applicable.

NULLABLE: Indicates if a column can accept NULLs. The following values are defined:

  SQL_NO_NULLS          0
  SQL_NULLABLE          1
  SQL_NULLABLE_UNKNOWN  2

REMARKS: A description of the column.

COLUMN_DEF: The default value of the column.

SQL_DATA_TYPE: The SQL data type.

SQL_DATETIME_SUB: The subtype code for datetime and interval data types.

CHAR_OCTET_LENGTH: The maximum length in bytes of a character or binary data type column.

ORDINAL_POSITION: The column sequence number (starting with 1).

IS_NULLABLE: Indicates if the column can accept NULLs. Possible values are: 'NO', 'YES' and ''.

SQL/CLI defines the following additional columns:

  CHAR_SET_CAT
  CHAR_SET_SCHEM
  CHAR_SET_NAME
  COLLATION_CAT
  COLLATION_SCHEM
  COLLATION_NAME
  UDT_CAT
  UDT_SCHEM
  UDT_NAME
  DOMAIN_CAT
  DOMAIN_SCHEM
  DOMAIN_NAME
  SCOPE_CAT
  SCOPE_SCHEM
  SCOPE_NAME
  MAX_CARDINALITY
  DTD_IDENTIFIER
  IS_SELF_REF

Drivers capable of supplying any of those values should do so in the corresponding column and supply undef values for the others.

Drivers wishing to provide extra database/driver specific information should do so in extra columns beyond all those listed above, and use lowercase field names with the driver-specific prefix (i.e., 'ora_...'). Applications accessing such fields should do so by name and not by column number.

The result set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION.

Note: There is some overlap with statement attributes (in perl) and SQLDescribeCol (in ODBC). However, SQLColumns provides more metadata.

See also Catalog Methods and Standards Reference Information.

primary_key_info

  $sth = $dbh->primary_key_info( $catalog, $schema, $table );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Returns an active statement handle that can be used to fetch information about columns that make up the primary key for a table. The arguments don't accept search patterns (unlike table_info()).

The statement handle will return one row per column, ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and KEY_SEQ. If there is no primary key then the statement handle will fetch no rows.

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier.

COLUMN_NAME: The column identifier.

KEY_SEQ: The column sequence number (starting with 1). Note: This field is named ORDINAL_POSITION in SQL/CLI.

PK_NAME: The primary key constraint identifier. This field is NULL (undef) if not applicable to the data source.

See also Catalog Methods and Standards Reference Information.

primary_key

  @key_column_names = $dbh->primary_key( $catalog, $schema, $table );

Simple interface to the primary_key_info() method. Returns a list of the column names that comprise the primary key of the specified table. The list is in primary key column sequence order. If there is no primary key then an empty list is returned.

foreign_key_info

  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table );

  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table
                               , \%attr );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Returns an active statement handle that can be used to fetch information about foreign keys in and/or referencing the specified table(s). The arguments don't accept search patterns (unlike table_info()).

$pk_catalog, $pk_schema, $pk_table identify the primary (unique) key table (PKT).

$fk_catalog, $fk_schema, $fk_table identify the foreign key table (FKT).

If both PKT and FKT are given, the function returns the foreign key, if any, in table FKT that refers to the primary (unique) key of table PKT. (Note: In SQL/CLI, the result is implementation-defined.)

If only PKT is given, then the result set contains the primary key of that table and all foreign keys that refer to it.

If only FKT is given, then the result set contains all foreign keys in that table and the primary keys to which they refer. (Note: In SQL/CLI, the result includes unique keys too.)

For example:

  $sth = $dbh->foreign_key_info( undef, $user, 'master');
  $sth = $dbh->foreign_key_info( undef, undef,   undef , undef, $user, 'detail');
  $sth = $dbh->foreign_key_info( undef, $user, 'master', undef, $user, 'detail');

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has the following fields in the order shown below. Because ODBC never includes unique keys, they define different columns in the result set than SQL/CLI. SQL/CLI column names are shown in parentheses.

PKTABLE_CAT ( UK_TABLE_CAT ): The primary (unique) key table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

PKTABLE_SCHEM ( UK_TABLE_SCHEM ): The primary (unique) key table schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

PKTABLE_NAME ( UK_TABLE_NAME ): The primary (unique) key table identifier.

PKCOLUMN_NAME (UK_COLUMN_NAME ): The primary (unique) key column identifier.

FKTABLE_CAT ( FK_TABLE_CAT ): The foreign key table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

FKTABLE_SCHEM ( FK_TABLE_SCHEM ): The foreign key table schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

FKTABLE_NAME ( FK_TABLE_NAME ): The foreign key table identifier.

FKCOLUMN_NAME ( FK_COLUMN_NAME ): The foreign key column identifier.

KEY_SEQ ( ORDINAL_POSITION ): The column sequence number (starting with 1).

UPDATE_RULE ( UPDATE_RULE ): The referential action for the UPDATE rule. The following codes are defined:

  CASCADE              0
  RESTRICT             1
  SET NULL             2
  NO ACTION            3
  SET DEFAULT          4

DELETE_RULE ( DELETE_RULE ): The referential action for the DELETE rule. The codes are the same as for UPDATE_RULE.

FK_NAME ( FK_NAME ): The foreign key name.

PK_NAME ( UK_NAME ): The primary (unique) key name.

DEFERRABILITY ( DEFERABILITY ): The deferrability of the foreign key constraint. The following codes are defined:

  INITIALLY DEFERRED   5
  INITIALLY IMMEDIATE  6
  NOT DEFERRABLE       7

( UNIQUE_OR_PRIMARY ): This column is necessary if a driver includes all candidate (i.e. primary and alternate) keys in the result set (as specified by SQL/CLI). The value of this column is UNIQUE if the foreign key references an alternate key and PRIMARY if the foreign key references a primary key, or it may be undefined if the driver doesn't have access to the information.

See also Catalog Methods and Standards Reference Information.

statistics_info

Warning: This method is experimental and may change.

  $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

Returns an active statement handle that can be used to fetch statistical information about a table and its indexes.

The arguments don't accept search patterns (unlike table_info).

If the boolean argument $unique_only is true, only UNIQUE indexes will be returned in the result set, otherwise all indexes will be returned.

If the boolean argument $quick is set, the actual statistical information columns (CARDINALITY and PAGES) will only be returned if they are readily available from the server, and might not be current. Some databases may return stale statistics or no statistics at all with this flag set.

The statement handle will return at most one row per column name per index, plus at most one row for the entire table itself, ordered by NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, and ORDINAL_POSITION.

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier.

NON_UNIQUE: Unique index indicator. Returns 0 for unique indexes, 1 for non-unique indexes

INDEX_QUALIFIER: Index qualifier identifier. The identifier that is used to qualify the index name when doing a DROP INDEX; NULL (undef) is returned if an index qualifier is not supported by the data source. If a non-NULL (defined) value is returned in this column, it must be used to qualify the index name on a DROP INDEX statement; otherwise, the TABLE_SCHEM should be used to qualify the index name.

INDEX_NAME: The index identifier.

TYPE: The type of information being returned. Can be any of the following values: 'table', 'btree', 'clustered', 'content', 'hashed', or 'other'.

In the case that this field is 'table', all fields other than TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TYPE, CARDINALITY, and PAGES will be NULL (undef).

ORDINAL_POSITION: Column sequence number (starting with 1).

COLUMN_NAME: The column identifier.

ASC_OR_DESC: Column sort sequence. A for Ascending, D for Descending, or NULL (undef) if not supported for this index.

CARDINALITY: Cardinality of the table or index. For indexes, this is the number of unique values in the index. For tables, this is the number of rows in the table. If not supported, the value will be NULL (undef).

PAGES: Number of storage pages used by this table or index. If not supported, the value will be NULL (undef).

FILTER_CONDITION: The index filter condition as a string. If the index is not a filtered index, or it cannot be determined whether the index is a filtered index, this value is NULL (undef). If the index is a filtered index, but the filter condition cannot be determined, this value is the empty string ''. Otherwise it will be the literal filter condition as a string, such as SALARY <= 4500.

See also Catalog Methods and Standards Reference Information.

tables

  @names = $dbh->tables( $catalog, $schema, $table, $type );
  @names = $dbh->tables;        # deprecated

Simple interface to table_info(). Returns a list of matching table names, possibly including a catalog/schema prefix.

See table_info for a description of the parameters.

If $dbh->get_info(29) returns true (29 is SQL_IDENTIFIER_QUOTE_CHAR) then the table names are constructed and quoted by quote_identifier to ensure they are usable even if they contain whitespace or reserved words etc. This means that the table names returned will include quote characters.

type_info_all

  $type_info_all = $dbh->type_info_all;

Returns a reference to an array which holds information about each data type variant supported by the database and driver. The array and its contents should be treated as read-only.

The first item is a reference to an 'index' hash of Name => Index pairs. The items following that are references to arrays, one per supported data type variant. The leading index hash defines the names and order of the fields within the arrays that follow it. For example:

  $type_info_all = [
    {   TYPE_NAME         => 0,
        DATA_TYPE         => 1,
        COLUMN_SIZE       => 2,     # was PRECISION originally
        LITERAL_PREFIX    => 3,
        LITERAL_SUFFIX    => 4,
        CREATE_PARAMS     => 5,
        NULLABLE          => 6,
        CASE_SENSITIVE    => 7,
        SEARCHABLE        => 8,
        UNSIGNED_ATTRIBUTE=> 9,
        FIXED_PREC_SCALE  => 10,    # was MONEY originally
        AUTO_UNIQUE_VALUE => 11,    # was AUTO_INCREMENT originally
        LOCAL_TYPE_NAME   => 12,
        MINIMUM_SCALE     => 13,
        MAXIMUM_SCALE     => 14,
        SQL_DATA_TYPE     => 15,
        SQL_DATETIME_SUB  => 16,
        NUM_PREC_RADIX    => 17,
        INTERVAL_PRECISION=> 18,
    },
    [ 'VARCHAR', SQL_VARCHAR,
        undef, "'","'", undef,0, 1,1,0,0,0,undef,1,255, undef
    ],
    [ 'INTEGER', SQL_INTEGER,
        undef,  "", "", undef,0, 0,1,0,0,0,undef,0,  0, 10
    ],
  ];

More than one row may have the same value in the DATA_TYPE field if there are different ways to spell the type name and/or there are variants of the type with different attributes (e.g., with and without AUTO_UNIQUE_VALUE set, with and without UNSIGNED_ATTRIBUTE, etc).

The rows are ordered by DATA_TYPE first and then by how closely each type maps to the corresponding ODBC SQL data type, closest first.

The meaning of the fields is described in the documentation for the type_info method.

An 'index' hash is provided so you don't need to rely on index values defined above. However, using DBD::ODBC with some old ODBC drivers may return older names, shown as comments in the example above. Another issue with the index hash is that the lettercase of the keys is not defined. It is usually uppercase, as show here, but drivers may return names with any lettercase.

Drivers are also free to return extra driver-specific columns of information - though it's recommended that they start at column index 50 to leave room for expansion of the DBI/ODBC specification.

The type_info_all() method is not normally used directly. The type_info method provides a more usable and useful interface to the data.

type_info

  @type_info = $dbh->type_info($data_type);

Returns a list of hash references holding information about one or more variants of $data_type. The list is ordered by DATA_TYPE first and then by how closely each type maps to the corresponding ODBC SQL data type, closest first. If called in a scalar context then only the first (best) element is returned.

If $data_type is undefined or SQL_ALL_TYPES, then the list will contain hashes for all data type variants supported by the database and driver.

If $data_type is an array reference then type_info returns the information for the first type in the array that has any matches.

The keys of the hash follow the same letter case conventions as the rest of the DBI (see Naming Conventions and Name Space). The following uppercase items should always exist, though may be undef:

TYPE_NAME (string)

Data type name for use in CREATE TABLE statements etc.

DATA_TYPE (integer)

SQL data type number.

COLUMN_SIZE (integer)

For numeric types, this is either the total number of digits (if the NUM_PREC_RADIX value is 10) or the total number of bits allowed in the column (if NUM_PREC_RADIX is 2).

For string types, this is the maximum size of the string in characters.

For date and interval types, this is the maximum number of characters needed to display the value.

LITERAL_PREFIX (string)

Characters used to prefix a literal. A typical prefix is "'" for characters, or possibly "0x" for binary values passed as hexadecimal. NULL (undef) is returned for data types for which this is not applicable.

LITERAL_SUFFIX (string)

Characters used to suffix a literal. Typically "'" for characters. NULL (undef) is returned for data types where this is not applicable.

CREATE_PARAMS (string)

Parameter names for data type definition. For example, CREATE_PARAMS for a DECIMAL would be "precision,scale" if the DECIMAL type should be declared as DECIMAL(precision,scale) where precision and scale are integer values. For a VARCHAR it would be "max length". NULL (undef) is returned for data types for which this is not applicable.

NULLABLE (integer)

Indicates whether the data type accepts a NULL value: 0 or an empty string = no, 1 = yes, 2 = unknown.

CASE_SENSITIVE (boolean)

Indicates whether the data type is case sensitive in collations and comparisons.

SEARCHABLE (integer)

Indicates how the data type can be used in a WHERE clause, as follows:

  0 - Cannot be used in a WHERE clause
  1 - Only with a LIKE predicate
  2 - All comparison operators except LIKE
  3 - Can be used in a WHERE clause with any comparison operator
UNSIGNED_ATTRIBUTE (boolean)

Indicates whether the data type is unsigned. NULL (undef) is returned for data types for which this is not applicable.

FIXED_PREC_SCALE (boolean)

Indicates whether the data type always has the same precision and scale (such as a money type). NULL (undef) is returned for data types for which this is not applicable.

AUTO_UNIQUE_VALUE (boolean)

Indicates whether a column of this data type is automatically set to a unique value whenever a new row is inserted. NULL (undef) is returned for data types for which this is not applicable.

LOCAL_TYPE_NAME (string)

Localized version of the TYPE_NAME for use in dialog with users. NULL (undef) is returned if a localized name is not available (in which case TYPE_NAME should be used).

MINIMUM_SCALE (integer)

The minimum scale of the data type. If a data type has a fixed scale, then MAXIMUM_SCALE holds the same value. NULL (undef) is returned for data types for which this is not applicable.

MAXIMUM_SCALE (integer)

The maximum scale of the data type. If a data type has a fixed scale, then MINIMUM_SCALE holds the same value. NULL (undef) is returned for data types for which this is not applicable.

SQL_DATA_TYPE (integer)

This column is the same as the DATA_TYPE column, except for interval and datetime data types. For interval and datetime data types, the SQL_DATA_TYPE field will return SQL_INTERVAL or SQL_DATETIME, and the SQL_DATETIME_SUB field below will return the subcode for the specific interval or datetime data type. If this field is NULL, then the driver does not support or report on interval or datetime subtypes.

SQL_DATETIME_SUB (integer)

For interval or datetime data types, where the SQL_DATA_TYPE field above is SQL_INTERVAL or SQL_DATETIME, this field will hold the subcode for the specific interval or datetime data type. Otherwise it will be NULL (undef).

Although not mentioned explicitly in the standards, it seems there is a simple relationship between these values:

  DATA_TYPE == (10 * SQL_DATA_TYPE) + SQL_DATETIME_SUB
NUM_PREC_RADIX (integer)

The radix value of the data type. For approximate numeric types, NUM_PREC_RADIX contains the value 2 and COLUMN_SIZE holds the number of bits. For exact numeric types, NUM_PREC_RADIX contains the value 10 and COLUMN_SIZE holds the number of decimal digits. NULL (undef) is returned either for data types for which this is not applicable or if the driver cannot report this information.

INTERVAL_PRECISION (integer)

The interval leading precision for interval types. NULL is returned either for data types for which this is not applicable or if the driver cannot report this information.

For example, to find the type name for the fields in a select statement you can do:

  @names = map { scalar $dbh->type_info($_)->{TYPE_NAME} } @{ $sth->{TYPE} }

Since DBI and ODBC drivers vary in how they map their types into the ISO standard types you may need to search for more than one type. Here's an example looking for a usable type to store a date:

  $my_date_type = $dbh->type_info( [ SQL_DATE, SQL_TIMESTAMP ] );

Similarly, to more reliably find a type to store small integers, you could use a list starting with SQL_SMALLINT, SQL_INTEGER, SQL_DECIMAL, etc.

See also Standards Reference Information.

quote

  $sql = $dbh->quote($value);
  $sql = $dbh->quote($value, $data_type);

Quote a string literal for use as a literal value in an SQL statement, by escaping any special characters (such as quotation marks) contained within the string and adding the required type of outer quotation marks.

  $sql = sprintf "SELECT foo FROM bar WHERE baz = %s",
                $dbh->quote("Don't");

For most database types, quote would return 'Don''t' (including the outer quotation marks).

An undefined $value value will be returned as the string NULL (without single quotation marks) to match how NULLs are represented in SQL.

If $data_type is supplied, it is used to try to determine the required quoting behaviour by using the information returned by type_info. As a special case, the standard numeric types are optimized to return $value without calling type_info.

Quote will probably not be able to deal with all possible input (such as binary data or data containing newlines), and is not related in any way with escaping or quoting shell meta-characters.

It is valid for the quote() method to return an SQL expression that evaluates to the desired string. For example:

  $quoted = $dbh->quote("one\ntwo\0three")

may return something like:

  CONCAT('one', CHAR(12), 'two', CHAR(0), 'three')

The quote() method should not be used with Placeholders and Bind Values.

quote_identifier

  $sql = $dbh->quote_identifier( $name );
  $sql = $dbh->quote_identifier( $catalog, $schema, $table, \%attr );

Quote an identifier (table name etc.) for use in an SQL statement, by escaping any special characters (such as double quotation marks) it contains and adding the required type of outer quotation marks.

Undefined names are ignored and the remainder are quoted and then joined together, typically with a dot (.) character. For example:

  $id = $dbh->quote_identifier( undef, 'Her schema', 'My table' );

would, for most database types, return "Her schema"."My table" (including all the double quotation marks).

If three names are supplied then the first is assumed to be a catalog name and special rules may be applied based on what get_info returns for SQL_CATALOG_NAME_SEPARATOR (41) and SQL_CATALOG_LOCATION (114). For example, for Oracle:

  $id = $dbh->quote_identifier( 'link', 'schema', 'table' );

would return "schema"."table"@"link".

take_imp_data

  $imp_data = $dbh->take_imp_data;

Leaves the $dbh in an almost dead, zombie-like, state and returns a binary string of raw implementation data from the driver which describes the current database connection. Effectively it detaches the underlying database API connection data from the DBI handle. After calling take_imp_data(), all other methods except DESTROY will generate a warning and return undef.

Why would you want to do this? You don't, forget I even mentioned it. Unless, that is, you're implementing something advanced like a multi-threaded connection pool. See the DBI::Pool manpage.

The returned $imp_data can be passed as a dbi_imp_data attribute to a later connect() call, even in a separate thread in the same process, where the driver can use it to 'adopt' the existing connection that the implementation data was taken from.

Some things to keep in mind...

* the $imp_data holds the only reference to the underlying database API connection data. That connection is still 'live' and won't be cleaned up properly unless the $imp_data is used to create a new $dbh which is then allowed to disconnect() normally.

* using the same $imp_data to create more than one other new $dbh at a time may well lead to unpleasant problems. Don't do that.

Any child statement handles are effectively destroyed when take_imp_data() is called.

The take_imp_data method was added in DBI 1.36 but wasn't useful till 1.49.

Database Handle Attributes

This section describes attributes specific to database handles.

Changes to these database handle attributes do not affect any other existing or future database handles.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver-specific attributes (which all have names starting with a lowercase letter).

Example:

  $h->{AutoCommit} = ...;       # set/write
  ... = $h->{AutoCommit};       # get/read

AutoCommit (boolean)

If true, then database changes cannot be rolled-back (undone). If false, then database changes automatically occur within a "transaction", which must either be committed or rolled back using the commit or rollback methods.

Drivers should always default to AutoCommit mode (an unfortunate choice largely forced on the DBI by ODBC and JDBC conventions.)

Attempting to set AutoCommit to an unsupported value is a fatal error. This is an important feature of the DBI. Applications that need full transaction behaviour can set $dbh->{AutoCommit} = 0 (or set AutoCommit to 0 via connect) without having to check that the value was assigned successfully.

For the purposes of this description, we can divide databases into three categories:

  Databases which don't support transactions at all.
  Databases in which a transaction is always active.
  Databases in which a transaction must be explicitly started (C<'BEGIN WORK'>).

* Databases which don't support transactions at all

For these databases, attempting to turn AutoCommit off is a fatal error. commit and rollback both issue warnings about being ineffective while AutoCommit is in effect.

* Databases in which a transaction is always active

These are typically mainstream commercial relational databases with "ANSI standard" transaction behaviour. If AutoCommit is off, then changes to the database won't have any lasting effect unless commit is called (but see also disconnect). If rollback is called then any changes since the last commit are undone.

If AutoCommit is on, then the effect is the same as if the DBI called commit automatically after every successful database operation. So calling commit or rollback explicitly while AutoCommit is on would be ineffective because the changes would have already been commited.

Changing AutoCommit from off to on will trigger a commit.

For databases which don't support a specific auto-commit mode, the driver has to commit each statement automatically using an explicit COMMIT after it completes successfully (and roll it back using an explicit ROLLBACK if it fails). The error information reported to the application will correspond to the statement which was executed, unless it succeeded and the commit or rollback failed.

* Databases in which a transaction must be explicitly started

For these databases, the intention is to have them act like databases in which a transaction is always active (as described above).

To do this, the driver will automatically begin an explicit transaction when AutoCommit is turned off, or after a commit or rollback (or when the application issues the next database operation after one of those events).

In this way, the application does not have to treat these databases as a special case.

See commit, disconnect and Transactions for other important notes about transactions.

Driver (handle)

Holds the handle of the parent driver. The only recommended use for this is to find the name of the driver using:

  $dbh->{Driver}->{Name}

Name (string)

Holds the "name" of the database. Usually (and recommended to be) the same as the "dbi:DriverName:..." string used to connect to the database, but with the leading "dbi:DriverName:" removed.

Statement (string, read-only)

Returns the statement string passed to the most recent prepare method called in this database handle, even if that method failed. This is especially useful where RaiseError is enabled and the exception handler checks $@ and sees that a 'prepare' method call failed.

RowCacheSize (integer)

A hint to the driver indicating the size of the local row cache that the application would like the driver to use for future SELECT statements. If a row cache is not implemented, then setting RowCacheSize is ignored and getting the value returns undef.

Some RowCacheSize values have special meaning, as follows:

  0 - Automatically determine a reasonable cache size for each C<SELECT>
  1 - Disable the local row cache
 >1 - Cache this many rows
 <0 - Cache as many rows that will fit into this much memory for each C<SELECT>.

Note that large cache sizes may require a very large amount of memory (cached rows * maximum size of row). Also, a large cache will cause a longer delay not only for the first fetch, but also whenever the cache needs refilling.

See also the RowsInCache statement handle attribute.

Username (string)

Returns the username used to connect to the database.

DBI STATEMENT HANDLE OBJECTS

This section lists the methods and attributes associated with DBI statement handles.

Statement Handle Methods

The DBI defines the following methods for use on DBI statement handles:

bind_param

  $sth->bind_param($p_num, $bind_value)
  $sth->bind_param($p_num, $bind_value, \%attr)
  $sth->bind_param($p_num, $bind_value, $bind_type)

The bind_param method takes a copy of $bind_value and associates it (binds it) with a placeholder, identified by $p_num, embedded in the prepared statement. Placeholders are indicated with question mark character (?). For example:

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("SELECT name, age FROM people WHERE name LIKE ?");
  $sth->bind_param(1, "John%");  # placeholders are numbered from 1
  $sth->execute;
  DBI::dump_results($sth);

See Placeholders and Bind Values for more information.

Data Types for Placeholders

The \%attr parameter can be used to hint at the data type the placeholder should have. This is rarely needed. Typically, the driver is only interested in knowing if the placeholder should be bound as a number or a string.

  $sth->bind_param(1, $value, { TYPE => SQL_INTEGER });

As a short-cut for the common case, the data type can be passed directly, in place of the \%attr hash reference. This example is equivalent to the one above:

  $sth->bind_param(1, $value, SQL_INTEGER);

The TYPE value indicates the standard (non-driver-specific) type for this parameter. To specify the driver-specific type, the driver may support a driver-specific attribute, such as { ora_type => 97 }.

The SQL_INTEGER and other related constants can be imported using

  use DBI qw(:sql_types);

See DBI Constants for more information.

The data type for a placeholder cannot be changed after the first bind_param call. In fact the whole \%attr parameter is 'sticky' in the sense that a driver only needs to consider the \%attr parameter for the first call, for a given $sth and parameter. After that the driver may ignore the \%attr parameter for that placeholder.

Perl only has string and number scalar data types. All database types that aren't numbers are bound as strings and must be in a format the database will understand except where the bind_param() TYPE attribute specifies a type that implies a particular format. For example, given:

  $sth->bind_param(1, $value, SQL_DATETIME);

the driver should expect $value to be in the ODBC standard SQL_DATETIME format, which is 'YYYY-MM-DD HH:MM:SS'. Similarly for SQL_DATE, SQL_TIME etc.

As an alternative to specifying the data type in the bind_param call, you can let the driver pass the value as the default type (VARCHAR). You can then use an SQL function to convert the type within the statement. For example:

  INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?))

The CONVERT function used here is just an example. The actual function and syntax will vary between different databases and is non-portable.

See also Placeholders and Bind Values for more information.

bind_param_inout

  $rc = $sth->bind_param_inout($p_num, \$bind_value, $max_len)  or die $sth->errstr;
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, \%attr)     or ...
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, $bind_type) or ...

This method acts like bind_param, but also enables values to be updated by the statement. The statement is typically a call to a stored procedure. The $bind_value must be passed as a reference to the actual value to be used.

Note that unlike bind_param, the $bind_value variable is not copied when bind_param_inout is called. Instead, the value in the variable is read at the time execute is called.

The additional $max_len parameter specifies the minimum amount of memory to allocate to $bind_value for the new value. If the value returned from the database is too big to fit, then the execution should fail. If unsure what value to use, pick a generous length, i.e., a length larger than the longest value that would ever be returned. The only cost of using a larger value than needed is wasted memory.

Undefined values or undef are used to indicate null values. See also Placeholders and Bind Values for more information.

bind_param_array

  $rc = $sth->bind_param_array($p_num, $array_ref_or_value)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, \%attr)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, $bind_type)

The bind_param_array method is used to bind an array of values to a placeholder embedded in the prepared statement which is to be executed with execute_array. For example:

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name, dept) VALUES(?, ?, ?)");
  $sth->bind_param_array(1, [ 'John', 'Mary', 'Tim' ]);
  $sth->bind_param_array(2, [ 'Booth', 'Todd', 'Robinson' ]);
  $sth->bind_param_array(3, "SALES"); # scalar will be reused for each row
  $sth->execute_array( { ArrayTupleStatus => \my @tuple_status } );

The %attr ($bind_type) argument is the same as defined for bind_param. Refer to bind_param for general details on using placeholders.

(Note that bind_param_array() can not be used to expand a placeholder into a list of values for a statement like "SELECT foo WHERE bar IN (?)". A placeholder can only ever represent one value per execution.)

Scalar values, including undef, may also be bound by bind_param_array. In which case the same value will be used for each execute call. Driver-specific implementations may behave differently, e.g., when binding to a stored procedure call, some databases may permit mixing scalars and arrays as arguments.

The default implementation provided by DBI (for drivers that have not implemented array binding) is to iteratively call execute for each parameter tuple provided in the bound arrays. Drivers may provide more optimized implementations using whatever bulk operation support the database API provides. The default driver behaviour should match the default DBI behaviour, but always consult your driver documentation as there may be driver specific issues to consider.

Note that the default implementation currently only supports non-data returning statements (INSERT, UPDATE, but not SELECT). Also, bind_param_array and bind_param cannot be mixed in the same statement execution, and bind_param_array must be used with execute_array; using bind_param_array will have no effect for execute.

The bind_param_array method was added in DBI 1.22.

execute

  $rv = $sth->execute                or die $sth->errstr;
  $rv = $sth->execute(@bind_values)  or die $sth->errstr;

Perform whatever processing is necessary to execute the prepared statement. An undef is returned if an error occurs. A successful execute always returns true regardless of the number of rows affected, even if it's zero (see below). It is always important to check the return status of execute (and most other DBI methods) for errors if you're not using RaiseError.

For a non-SELECT statement, execute returns the number of rows affected, if known. If no rows were affected, then execute returns "0E0", which Perl will treat as 0 but will regard as true. Note that it is not an error for no rows to be affected by a statement. If the number of rows affected is not known, then execute returns -1.

For SELECT statements, execute simply "starts" the query within the database engine. Use one of the fetch methods to retrieve the data after calling execute. The execute method does not return the number of rows that will be returned by the query (because most databases can't tell in advance), it simply returns a true value.

You can tell if the statement was a SELECT statement by checking if $sth->{NUM_OF_FIELDS} is greater than zero after calling execute.

If any arguments are given, then execute will effectively call bind_param for each value before executing the statement. Values bound in this way are usually treated as SQL_VARCHAR types unless the driver can determine the correct type (which is rare), or unless bind_param (or bind_param_inout) has already been used to specify the type.

If execute() is called on a statement handle that's still active ($sth->{Active} is true) then it should effectively call finish() to tidy up the previous execution results before starting this new execution.

execute_array

  $tuples = $sth->execute_array(\%attr) or die $sth->errstr;
  $tuples = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;

  ($tuples, $rows) = $sth->execute_array(\%attr) or die $sth->errstr;
  ($tuples, $rows) = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;

Execute the prepared statement once for each parameter tuple (group of values) provided either in the @bind_values, or by prior calls to bind_param_array, or via a reference passed in \%attr.

When called in scalar context the execute_array() method returns the number of tuples executed, or undef if an error occured. Like execute(), a successful execute_array() always returns true regardless of the number of tuples executed, even if it's zero. If there were any errors the ArrayTupleStatus array can be used to discover which tuples failed and with what errors.

When called in list context the execute_array() method returns two scalars; $tuples is the same as calling execute_array() in scalar context and $rows is the sum of the number of rows affected for each tuple, if available or -1 if the driver cannot determine this. If you are doing an update operation the returned rows affected may not be what you expect if, for instance, one or more of the tuples affected the same row multiple times. Some drivers may not yet support list context, in which case $rows will be undef, or may not be able to provide the number of rows affected when performing this batch operation, in which case $rows will be -1.

Bind values for the tuples to be executed may be supplied row-wise by an ArrayTupleFetch attribute, or else column-wise in the @bind_values argument, or else column-wise by prior calls to bind_param_array.

Where column-wise binding is used (via the @bind_values argument or calls to bind_param_array()) the maximum number of elements in any one of the bound value arrays determines the number of tuples executed. Placeholders with fewer values in their parameter arrays are treated as if padded with undef (NULL) values.

If a scalar value is bound, instead of an array reference, it is treated as a variable length array with all elements having the same value. It's does not influence the number of tuples executed, so if all bound arrays have zero elements then zero tuples will be executed. If all bound values are scalars then one tuple will be executed, making execute_array() act just like execute().

The ArrayTupleFetch attribute can be used to specify a reference to a subroutine that will be called to provide the bind values for each tuple execution. The subroutine should return an reference to an array which contains the appropriate number of bind values, or return an undef if there is no more data to execute.

As a convienience, the ArrayTupleFetch attribute can also be used to specify a statement handle. In which case the fetchrow_arrayref() method will be called on the given statement handle in order to provide the bind values for each tuple execution.

The values specified via bind_param_array() or the @bind_values parameter may be either scalars, or arrayrefs. If any @bind_values are given, then execute_array will effectively call bind_param_array for each value before executing the statement. Values bound in this way are usually treated as SQL_VARCHAR types unless the driver can determine the correct type (which is rare), or unless bind_param, bind_param_inout, bind_param_array, or bind_param_inout_array has already been used to specify the type. See bind_param_array for details.

The ArrayTupleStatus attribute can be used to specify a reference to an array which will receive the execute status of each executed parameter tuple. Note the ArrayTupleStatus attribute was mandatory until DBI 1.38.

For tuples which are successfully executed, the element at the same ordinal position in the status array is the resulting rowcount. If the execution of a tuple causes an error, then the corresponding status array element will be set to a reference to an array containing the error code and error string set by the failed execution.

If any tuple execution returns an error, execute_array will return undef. In that case, the application should inspect the status array to determine which parameter tuples failed. Some databases may not continue executing tuples beyond the first failure. In this case the status array will either hold fewer elements, or the elements beyond the failure will be undef.

If all parameter tuples are successfully executed, execute_array returns the number tuples executed. If no tuples were executed, then execute_array() returns "0E0", just like execute() does, which Perl will treat as 0 but will regard as true.

For example:

  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name) VALUES (?, ?)");
  my $tuples = $sth->execute_array(
      { ArrayTupleStatus => \my @tuple_status },
      \@first_names,
      \@last_names,
  );
  if ($tuples) {
      print "Successfully inserted $tuples records\n";
  }
  else {
      for my $tuple (0..@last_names-1) {
          my $status = $tuple_status[$tuple];
          $status = [0, "Skipped"] unless defined $status;
          next unless ref $status;
          printf "Failed to insert (%s, %s): %s\n",
              $first_names[$tuple], $last_names[$tuple], $status->[1];
      }
  }

Support for data returning statements such as SELECT is driver-specific and subject to change. At present, the default implementation provided by DBI only supports non-data returning statements.

Transaction semantics when using array binding are driver and database specific. If AutoCommit is on, the default DBI implementation will cause each parameter tuple to be inidividually committed (or rolled back in the event of an error). If AutoCommit is off, the application is responsible for explicitly committing the entire set of bound parameter tuples. Note that different drivers and databases may have different behaviours when some parameter tuples cause failures. In some cases, the driver or database may automatically rollback the effect of all prior parameter tuples that succeeded in the transaction; other drivers or databases may retain the effect of prior successfully executed parameter tuples. Be sure to check your driver and database for its specific behaviour.

Note that, in general, performance will usually be better with AutoCommit turned off, and using explicit commit after each execute_array call.

The execute_array method was added in DBI 1.22, and ArrayTupleFetch was added in 1.36.

execute_for_fetch

  $tuples = $sth->execute_for_fetch($fetch_tuple_sub);
  $tuples = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);

  ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub);
  ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);

The execute_for_fetch() method is used to perform bulk operations and is most often used via the execute_array() method, not directly.

The fetch subroutine, referenced by $fetch_tuple_sub, is expected to return a reference to an array (known as a 'tuple') or undef.

The execute_for_fetch() method calls $fetch_tuple_sub, without any parameters, until it returns a false value. Each tuple returned is used to provide bind values for an $sth->execute(@$tuple) call.

In scalar context execute_for_fetch() returns undef if there were any errors and the number of tuples executed otherwise. Like execute() and execute_array() a zero is returned as "0E0" so execute_for_fetch() is only false on error. If there were any errors the @tuple_status array can be used to discover which tuples failed and with what errors.

When called in list context execute_for_fetch() returns two scalars; $tuples is the same as calling execute_for_fetch() in scalar context and $rows is the sum of the number of rows affected for each tuple, if available or -1 if the driver cannot determine this. If you are doing an update operation the returned rows affected may not be what you expect if, for instance, one or more of the tuples affected the same row multiple times. Some drivers may not yet support list context, in which case $rows will be undef, or may not be able to provide the number of rows affected when performing this batch operation, in which case $rows will be -1.

If \@tuple_status is passed then the execute_for_fetch method uses it to return status information. The tuple_status array holds one element per tuple. If the corresponding execute() did not fail then the element holds the return value from execute(), which is typically a row count. If the execute() did fail then the element holds a reference to an array containing ($sth->err, $sth->errstr, $sth->state).

If the driver detects an error that it knows means no further tuples can be executed then it may return, with an error status, even though $fetch_tuple_sub may still have more tuples to be executed.

Although each tuple returned by $fetch_tuple_sub is effectively used to call $sth->execute(@$tuple_array_ref) the exact timing may vary. Drivers are free to accumulate sets of tuples to pass to the database server in bulk group operations for more efficient execution. However, the $fetch_tuple_sub is specifically allowed to return the same array reference each time (which is what fetchrow_arrayref() usually does).

For example:

  my $sel = $dbh1->prepare("select foo, bar from table1");
  $sel->execute;

  my $ins = $dbh2->prepare("insert into table2 (foo, bar) values (?,?)");
  my $fetch_tuple_sub = sub { $sel->fetchrow_arrayref };

  my @tuple_status;
  $rc = $ins->execute_for_fetch($fetch_tuple_sub, \@tuple_status);
  my @errors = grep { ref $_ } @tuple_status;

Similarly, if you already have an array containing the data rows to be processed you'd use a subroutine to shift off and return each array ref in turn:

  $ins->execute_for_fetch( sub { shift @array_of_arrays }, \@tuple_status);

The execute_for_fetch method was added in DBI 1.38.

fetchrow_arrayref

  $ary_ref = $sth->fetchrow_arrayref;
  $ary_ref = $sth->fetch;    # alias

Fetches the next row of data and returns a reference to an array holding the field values. Null fields are returned as undef values in the array. This is the fastest way to fetch data, particularly if used with $sth->bind_columns.

If there are no more rows or if an error occurs, then fetchrow_arrayref returns an undef. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the undef returned was due to an error.

Note that the same array reference is returned for each fetch, so don't store the reference and then use it after a later fetch. Also, the elements of the array are also reused for each row, so take care if you want to take a reference to an element. See also bind_columns.

fetchrow_array

 @ary = $sth->fetchrow_array;

An alternative to fetchrow_arrayref. Fetches the next row of data and returns it as a list containing the field values. Null fields are returned as undef values in the list.

If there are no more rows or if an error occurs, then fetchrow_array returns an empty list. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the empty list returned was due to an error.

If called in a scalar context for a statement handle that has more than one column, it is undefined whether the driver will return the value of the first column or the last. So don't do that. Also, in a scalar context, an undef is returned if there are no more rows or if an error occurred. That undef can't be distinguished from an undef returned because the first field value was NULL. For these reasons you should exercise some caution if you use fetchrow_array in a scalar context.

fetchrow_hashref

 $hash_ref = $sth->fetchrow_hashref;
 $hash_ref = $sth->fetchrow_hashref($name);

An alternative to fetchrow_arrayref. Fetches the next row of data and returns it as a reference to a hash containing field name and field value pairs. Null fields are returned as undef values in the hash.

If there are no more rows or if an error occurs, then fetchrow_hashref returns an undef. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the undef returned was due to an error.

The optional $name parameter specifies the name of the statement handle attribute. For historical reasons it defaults to "NAME", however using either "NAME_lc" or "NAME_uc" is recomended for portability.

The keys of the hash are the same names returned by $sth->{$name}. If more than one field has the same name, there will only be one entry in the returned hash for those fields.

Because of the extra work fetchrow_hashref and Perl have to perform, it is not as efficient as fetchrow_arrayref or fetchrow_array.

By default a reference to a new hash is returned for each row. It is likely that a future version of the DBI will support an attribute which will enable the same hash to be reused for each row. This will give a significant performance boost, but it won't be enabled by default because of the risk of breaking old code.

fetchall_arrayref

  $tbl_ary_ref = $sth->fetchall_arrayref;
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice );
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows  );

The fetchall_arrayref method can be used to fetch all the data to be returned from a prepared and executed statement handle. It returns a reference to an array that contains one reference per row.

If there are no rows to return, fetchall_arrayref returns a reference to an empty array. If an error occurs, fetchall_arrayref returns the data fetched thus far, which may be none. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

If $slice is an array reference, fetchall_arrayref uses fetchrow_arrayref to fetch each row as an array ref. If the $slice array is not empty then it is used as a slice to select individual columns by perl array index number (starting at 0, unlike column and parameter numbers which start at 1).

With no parameters, or if $slice is undefined, fetchall_arrayref acts as if passed an empty array ref.

If $slice is a hash reference, fetchall_arrayref uses fetchrow_hashref to fetch each row as a hash reference. If the $slice hash is empty then fetchrow_hashref() is simply called in a tight loop and the keys in the hashes have whatever name lettercase is returned by default from fetchrow_hashref. (See FetchHashKeyName attribute.) If the $slice hash is not empty, then it is used as a slice to select individual columns by name. The values of the hash should be set to 1. The key names of the returned hashes match the letter case of the names in the parameter hash, regardless of the FetchHashKeyName attribute.

For example, to fetch just the first column of every row:

  $tbl_ary_ref = $sth->fetchall_arrayref([0]);

To fetch the second to last and last column of every row:

  $tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]);

To fetch all fields of every row as a hash ref:

  $tbl_ary_ref = $sth->fetchall_arrayref({});

To fetch only the fields called "foo" and "bar" of every row as a hash ref (with keys named "foo" and "BAR"):

  $tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, BAR=>1 });

The first two examples return a reference to an array of array refs. The third and forth return a reference to an array of hash refs.

If $max_rows is defined and greater than or equal to zero then it is used to limit the number of rows fetched before returning. fetchall_arrayref() can then be called again to fetch more rows. This is especially useful when you need the better performance of fetchall_arrayref() but don't have enough memory to fetch and return all the rows in one go. Here's an example:

  my $rows = []; # cache for batches of rows
  while( my $row = ( shift(@$rows) || # get row from cache, or reload cache:
                     shift(@{$rows=$sth->fetchall_arrayref(undef,10_000)||[]}) )
  ) {
    ...
  }

That can be the fastest way to fetch and process lots of rows using the DBI, but it depends on the relative cost of method calls vs memory allocation.

A standard while loop with column binding is often faster because the cost of allocating memory for the batch of rows is greater than the saving by reducing method calls. It's possible that the DBI may provide a way to reuse the memory of a previous batch in future, which would then shift the balance back towards fetchall_arrayref().

fetchall_hashref

  $hash_ref = $sth->fetchall_hashref($key_field);

The fetchall_hashref method can be used to fetch all the data to be returned from a prepared and executed statement handle. It returns a reference to a hash containing a key for each distinct value of the $key_field column that was fetched. For each key the corresponding value is a reference to a hash containing all the selected columns and their values, as returned by fetchrow_hashref().

If there are no rows to return, fetchall_hashref returns a reference to an empty hash. If an error occurs, fetchall_hashref returns the data fetched thus far, which may be none. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

The $key_field parameter provides the name of the field that holds the value to be used for the key for the returned hash. For example:

  $dbh->{FetchHashKeyName} = 'NAME_lc';
  $sth = $dbh->prepare("SELECT FOO, BAR, ID, NAME, BAZ FROM TABLE");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref('id');
  print "Name for id 42 is $hash_ref->{42}->{name}\n";

The $key_field parameter can also be specified as an integer column number (counting from 1). If $key_field doesn't match any column in the statement, as a name first then as a number, then an error is returned.

For queries returing more than one 'key' column, you can specify multiple column names by passing $key_field as a reference to an array containing one or more key column names (or index numbers). For example:

  $sth = $dbh->prepare("SELECT foo, bar, baz FROM table");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref( [ qw(foo bar) ] );
  print "For foo 42 and bar 38, baz is $hash_ref->{42}->{38}->{baz}\n";

The fetchall_hashref() method is normally used only where the key fields values for each row are unique. If multiple rows are returned with the same values for the key fields then later rows overwrite earlier ones.

finish

  $rc  = $sth->finish;

Indicate that no more data will be fetched from this statement handle before it is either executed again or destroyed. The finish method is rarely needed, and frequently overused, but can sometimes be helpful in a few very specific situations to allow the server to free up resources (such as sort buffers).

When all the data has been fetched from a SELECT statement, the driver should automatically call finish for you. So you should not normally need to call it explicitly except when you know that you've not fetched all the data from a statement handle. The most common example is when you only want to fetch one row, but in that case the selectrow_* methods are usually better anyway. Adding calls to finish after each fetch loop is a common mistake, don't do it, it can mask genuine problems like uncaught fetch errors.

Consider a query like:

  SELECT foo FROM table WHERE bar=? ORDER BY foo

where you want to select just the first (smallest) "foo" value from a very large table. When executed, the database server will have to use temporary buffer space to store the sorted rows. If, after executing the handle and selecting one row, the handle won't be re-executed for some time and won't be destroyed, the finish method can be used to tell the server that the buffer space can be freed.

Calling finish resets the Active attribute for the statement. It may also make some statement handle attributes (such as NAME and TYPE) unavailable if they have not already been accessed (and thus cached).

The finish method does not affect the transaction status of the database connection. It has nothing to do with transactions. It's mostly an internal "housekeeping" method that is rarely needed. See also disconnect and the Active attribute.

The finish method should have been called discard_pending_rows.

rows

  $rv = $sth->rows;

Returns the number of rows affected by the last row affecting command, or -1 if the number of rows is not known or not available.

Generally, you can only rely on a row count after a non-SELECT execute (for some specific operations like UPDATE and DELETE), or after fetching all the rows of a SELECT statement.

For SELECT statements, it is generally not possible to know how many rows will be returned except by fetching them all. Some drivers will return the number of rows the application has fetched so far, but others may return -1 until all rows have been fetched. So use of the rows method or $DBI::rows with SELECT statements is not recommended.

One alternative method to get a row count for a SELECT is to execute a "SELECT COUNT(*) FROM ..." SQL statement with the same "..." as your query and then fetch the row count from that.

bind_col

  $rc = $sth->bind_col($column_number, \$var_to_bind);
  $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr );
  $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type );

Binds a Perl variable and/or some attributes to an output column (field) of a SELECT statement. Column numbers count up from 1. You do not need to bind output columns in order to fetch data. For maximum portability between drivers, bind_col() should be called after execute() and not before. See also bind_columns for an example.

The binding is performed at a low level using Perl aliasing. Whenever a row is fetched from the database $var_to_bind appears to be automatically updated simply because it now refers to the same memory location as the corresponding column value. This makes using bound variables very efficient. Binding a tied variable doesn't work, currently.

The bind_param method performs a similar, but opposite, function for input variables.

Data Types for Column Binding

The \%attr parameter can be used to hint at the data type formatting the column should have. For example, you can use:

  $sth->bind_col(1, undef, { TYPE => SQL_DATETIME });

to specify that you'd like the column (which presumably is some kind of datetime type) to be returned in the standard format for SQL_DATETIME, which is 'YYYY-MM-DD HH:MM:SS', rather than the native formatting the database would normally use.

There's no $var_to_bind in that example to emphasize the point that bind_col() works on the underlying column value and not just a particular bound variable.

As a short-cut for the common case, the data type can be passed directly, in place of the \%attr hash reference. This example is equivalent to the one above:

  $sth->bind_col(1, undef, SQL_DATETIME);

The TYPE value indicates the standard (non-driver-specific) type for this parameter. To specify the driver-specific type, the driver may support a driver-specific attribute, such as { ora_type => 97 }.

The SQL_DATETIME and other related constants can be imported using

  use DBI qw(:sql_types);

See DBI Constants for more information.

The data type for a bind variable cannot be changed after the first bind_col call. In fact the whole \%attr parameter is 'sticky' in the sense that a driver only needs to consider the \%attr parameter for the first call for a given $sth and column.

The TYPE attribute for bind_col() was first specified in DBI 1.41.

bind_columns

  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

Calls bind_col for each column of the SELECT statement.

The list of references should have the same number of elements as the number of columns in the SELECT statement. If it doesn't then bind_columns will bind the elements given, upto the number of columns, and then return an error.

For maximum portability between drivers, bind_columns() should be called after execute() and not before.

For example:

  $dbh->{RaiseError} = 1; # do this, or check every call for errors
  $sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
  $sth->execute;
  my ($region, $sales);

  # Bind Perl variables to columns:
  $rv = $sth->bind_columns(\$region, \$sales);

  # you can also use Perl's \(...) syntax (see perlref docs):
  #     $sth->bind_columns(\($region, $sales));

  # Column binding is the most efficient way to fetch data
  while ($sth->fetch) {
      print "$region: $sales\n";
  }

For compatibility with old scripts, the first parameter will be ignored if it is undef or a hash reference.

Here's a more fancy example that binds columns to the values inside a hash (thanks to H.Merijn Brand):

  $sth->execute;
  my %row;
  $sth->bind_columns( \( @row{ @{$sth->{NAME_lc} } } ));
  while ($sth->fetch) {
      print "$row{region}: $row{sales}\n";
  }

dump_results

  $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);

Fetches all the rows from $sth, calls DBI::neat_list for each row, and prints the results to $fh (defaults to STDOUT) separated by $lsep (default "\n"). $fsep defaults to ", " and $maxlen defaults to 35.

This method is designed as a handy utility for prototyping and testing queries. Since it uses neat_list to format and edit the string for reading by humans, it is not recomended for data transfer applications.

Statement Handle Attributes

This section describes attributes specific to statement handles. Most of these attributes are read-only.

Changes to these statement handle attributes do not affect any other existing or future statement handles.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver specific attributes (which all have names starting with a lowercase letter).

Example:

  ... = $h->{NUM_OF_FIELDS};    # get/read

Some drivers cannot provide valid values for some or all of these attributes until after $sth->execute has been successfully called. Typically the attribute will be undef in these situations.

Some attributes, like NAME, are not appropriate to some types of statement, like SELECT. Typically the attribute will be undef in these situations.

See also finish to learn more about the effect it may have on some attributes.

NUM_OF_FIELDS (integer, read-only)

Number of fields (columns) in the data the prepared statement may return. Statements that don't return rows of data, like DELETE and CREATE set NUM_OF_FIELDS to 0 (though it may be undef in some drivers).

NUM_OF_PARAMS (integer, read-only)

The number of parameters (placeholders) in the prepared statement. See SUBSTITUTION VARIABLES below for more details.

NAME (array-ref, read-only)

Returns a reference to an array of field names for each column. The names may contain spaces but should not be truncated or have any trailing space. Note that the names have the letter case (upper, lower or mixed) as returned by the driver being used. Portable applications should use NAME_lc or NAME_uc.

  print "First column name: $sth->{NAME}->[0]\n";

NAME_lc (array-ref, read-only)

Like NAME but always returns lowercase names.

NAME_uc (array-ref, read-only)

Like NAME but always returns uppercase names.

NAME_hash (hash-ref, read-only)

NAME_lc_hash (hash-ref, read-only)

NAME_uc_hash (hash-ref, read-only)

The NAME_hash, NAME_lc_hash, and NAME_uc_hash attributes return column name information as a reference to a hash.

The keys of the hash are the names of the columns. The letter case of the keys corresponds to the letter case returned by the NAME, NAME_lc, and NAME_uc attributes respectively (as described above).

The value of each hash entry is the perl index number of the corresponding column (counting from 0). For example:

  $sth = $dbh->prepare("select Id, Name from table");
  $sth->execute;
  @row = $sth->fetchrow_array;
  print "Name $row[ $sth->{NAME_lc_hash}{name} ]\n";

TYPE (array-ref, read-only)

Returns a reference to an array of integer values for each column. The value indicates the data type of the corresponding column.

The values correspond to the international standards (ANSI X3.135 and ISO/IEC 9075) which, in general terms, means ODBC. Driver-specific types that don't exactly match standard types should generally return the same values as an ODBC driver supplied by the makers of the database. That might include private type numbers in ranges the vendor has officially registered with the ISO working group:

  ftp://sqlstandards.org/SC32/SQL_Registry/

Where there's no vendor-supplied ODBC driver to be compatible with, the DBI driver can use type numbers in the range that is now officially reserved for use by the DBI: -9999 to -9000.

All possible values for TYPE should have at least one entry in the output of the type_info_all method (see type_info_all).

PRECISION (array-ref, read-only)

Returns a reference to an array of integer values for each column.

For numeric columns, the value is the maximum number of digits (without considering a sign character or decimal point). Note that the "display size" for floating point types (REAL, FLOAT, DOUBLE) can be up to 7 characters greater than the precision (for the sign + decimal point + the letter E + a sign + 2 or 3 digits).

For any character type column the value is the OCTET_LENGTH, in other words the number of bytes, not characters.

(More recent standards refer to this as COLUMN_SIZE but we stick with PRECISION for backwards compatibility.)

SCALE (array-ref, read-only)

Returns a reference to an array of integer values for each column. NULL (undef) values indicate columns where scale is not applicable.

NULLABLE (array-ref, read-only)

Returns a reference to an array indicating the possibility of each column returning a null. Possible values are 0 (or an empty string) = no, 1 = yes, 2 = unknown.

  print "First column may return NULL\n" if $sth->{NULLABLE}->[0];

CursorName (string, read-only)

Returns the name of the cursor associated with the statement handle, if available. If not available or if the database driver does not support the "where current of ..." SQL syntax, then it returns undef.

Database (dbh, read-only)

Returns the parent $dbh of the statement handle.

ParamValues (hash ref, read-only)

Returns a reference to a hash containing the values currently bound to placeholders. The keys of the hash are the 'names' of the placeholders, typically integers starting at 1. Returns undef if not supported by the driver.

See ShowErrorStatement for an example of how this is used.

If the driver supports ParamValues but no values have been bound yet then the driver should return a hash with placeholders names in the keys but all the values undef, but some drivers may return a ref to an empty hash.

It is possible that the values in the hash returned by ParamValues are not exactly the same as those passed to bind_param() or execute(). The driver may have slightly modified values in some way based on the TYPE the value was bound with. For example a floating point value bound as an SQL_INTEGER type may be returned as an integer. The values returned by ParamValues can be passed to another bind_param() method with the same TYPE and will be seen by the database as the same value.

It is also possible that the keys in the hash returned by ParamValues are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

The ParamValues attribute was added in DBI 1.28.

ParamArrays (hash ref, read-only)

Returns a reference to a hash containing the values currently bound to placeholders with execute_array or bind_param_array. The keys of the hash are the 'names' of the placeholders, typically integers starting at 1. Returns undef if not supported by the driver or no arrays of parameters are bound.

Each key value is an array reference containing a list of the bound parameters for that column.

For example:

  $sth = $dbh->prepare("INSERT INTO staff (id, name) values (?,?)");
  $sth->execute_array({},[1,2], ['fred','dave']);
  if ($sth->{ParamArrays}) {
      foreach $param (keys %{$sth->{ParamArrays}}) {
          printf "Parameters for %s : %s\n", $param,
          join(",", @{$sth->{ParamArrays}->{$param}});
      }
  }

It is possible that the values in the hash returned by ParamArrays are not exactly the same as those passed to bind_param_array or execute_array. The driver may have slightly modified values in some way based on the TYPE the value was bound with. For example a floating point value bound as an SQL_INTEGER type may be returned as an integer.

It is also possible that the keys in the hash returned by ParamArrays are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

ParamTypes (hash ref, read-only)

Returns a reference to a hash containing the type information currently bound to placeholders. The keys of the hash are the 'names' of the placeholders: either integers starting at 1, or, for drivers that support named placeholders, the actual parameter name string. The hash values are hashrefs of type information in the same form as that provided to the various bind_param() methods (See bind_param for the format and values), plus anything else that was passed as the third argument to bind_param(). Returns undef if not supported by the driver.

If the driver supports ParamTypes, but no values have been bound yet, then the driver should return a hash with the placeholder name keys, but all the values undef; however, some drivers may return a ref to an empty hash, or, alternately, may provide type information supplied by the database (only a few databases can do that).

It is possible that the values in the hash returned by ParamTypes are not exactly the same as those passed to bind_param() or execute(). The driver may have modified the type information in some way based on the bound values, other hints provided by the prepare()'d SQL statement, or alternate type mappings required by the driver or target database system.

It is also possible that the keys in the hash returned by ParamTypes are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

The ParamTypes attribute was added in DBI 1.49. Implementation is the responsibility of individual drivers; the DBI layer default implementation simply returns undef.

Statement (string, read-only)

Returns the statement string passed to the prepare method.

RowsInCache (integer, read-only)

If the driver supports a local row cache for SELECT statements, then this attribute holds the number of un-fetched rows in the cache. If the driver doesn't, then it returns undef. Note that some drivers pre-fetch rows on execute, whereas others wait till the first fetch.

See also the RowCacheSize database handle attribute.

FURTHER INFORMATION

Catalog Methods

An application can retrieve metadata information from the DBMS by issuing appropriate queries on the views of the Information Schema. Unfortunately, INFORMATION_SCHEMA views are seldom supported by the DBMS. Special methods (catalog methods) are available to return result sets for a small but important portion of that metadata:

  column_info
  foreign_key_info
  primary_key_info
  table_info
  statistics_info

All catalog methods accept arguments in order to restrict the result sets. Passing undef to an optional argument does not constrain the search for that argument. However, an empty string ('') is treated as a regular search criteria and will only match an empty value.

Note: SQL/CLI and ODBC differ in the handling of empty strings. An empty string will not restrict the result set in SQL/CLI.

Most arguments in the catalog methods accept only ordinary values, e.g. the arguments of primary_key_info(). Such arguments are treated as a literal string, i.e. the case is significant and quote characters are taken literally.

Some arguments in the catalog methods accept search patterns (strings containing '_' and/or '%'), e.g. the $table argument of column_info(). Passing '%' is equivalent to leaving the argument undef.

Caveat: The underscore ('_') is valid and often used in SQL identifiers. Passing such a value to a search pattern argument may return more rows than expected! To include pattern characters as literals, they must be preceded by an escape character which can be achieved with

  $esc = $dbh->get_info( 14 );  # SQL_SEARCH_PATTERN_ESCAPE
  $search_pattern =~ s/([_%])/$esc$1/g;

The ODBC and SQL/CLI specifications define a way to change the default behaviour described above: All arguments (except list value arguments) are treated as identifier if the SQL_ATTR_METADATA_ID attribute is set to SQL_TRUE. Quoted identifiers are very similar to ordinary values, i.e. their body (the string within the quotes) is interpreted literally. Unquoted identifiers are compared in UPPERCASE.

The DBI (currently) does not support the SQL_ATTR_METADATA_ID attribute, i.e. it behaves like an ODBC driver where SQL_ATTR_METADATA_ID is set to SQL_FALSE.

Transactions

Transactions are a fundamental part of any robust database system. They protect against errors and database corruption by ensuring that sets of related changes to the database take place in atomic (indivisible, all-or-nothing) units.

This section applies to databases that support transactions and where AutoCommit is off. See AutoCommit for details of using AutoCommit with various types of databases.

The recommended way to implement robust transactions in Perl applications is to use RaiseError and eval { ... } (which is very fast, unlike eval "..."). For example:

  $dbh->{AutoCommit} = 0;  # enable transactions, if possible
  $dbh->{RaiseError} = 1;
  eval {
      foo(...)        # do lots of work here
      bar(...)        # including inserts
      baz(...)        # and updates
      $dbh->commit;   # commit the changes if we get this far
  };
  if ($@) {
      warn "Transaction aborted because $@";
      # now rollback to undo the incomplete changes
      # but do it in an eval{} as it may also fail
      eval { $dbh->rollback };
      # add other application on-error-clean-up code here
  }

If the RaiseError attribute is not set, then DBI calls would need to be manually checked for errors, typically like this:

  $h->method(@args) or die $h->errstr;

With RaiseError set, the DBI will automatically die if any DBI method call on that handle (or a child handle) fails, so you don't have to test the return value of each method call. See RaiseError for more details.

A major advantage of the eval approach is that the transaction will be properly rolled back if any code (not just DBI calls) in the inner application dies for any reason. The major advantage of using the $h->{RaiseError} attribute is that all DBI calls will be checked automatically. Both techniques are strongly recommended.

After calling commit or rollback many drivers will not let you fetch from a previously active SELECT statement handle that's a child of the same database handle. A typical way round this is to connect the the database twice and use one connection for SELECT statements.

See AutoCommit and disconnect for other important information about transactions.

Handling BLOB / LONG / Memo Fields

Many databases support "blob" (binary large objects), "long", or similar datatypes for holding very long strings or large amounts of binary data in a single field. Some databases support variable length long values over 2,000,000,000 bytes in length.

Since values of that size can't usually be held in memory, and because databases can't usually know in advance the length of the longest long that will be returned from a SELECT statement (unlike other data types), some special handling is required.

In this situation, the value of the $h->{LongReadLen} attribute is used to determine how much buffer space to allocate when fetching such fields. The $h->{LongTruncOk} attribute is used to determine how to behave if a fetched value can't fit into the buffer.

See the description of LongReadLen for more information.

When trying to insert long or binary values, placeholders should be used since there are often limits on the maximum size of an INSERT statement and the quote method generally can't cope with binary data. See Placeholders and Bind Values.

Simple Examples

Here's a complete example program to select and fetch some data:

  my $data_source = "dbi::DriverName:db_name";
  my $dbh = DBI->connect($data_source, $user, $password)
      or die "Can't connect to $data_source: $DBI::errstr";

  my $sth = $dbh->prepare( q{
          SELECT name, phone
          FROM mytelbook
  }) or die "Can't prepare statement: $DBI::errstr";

  my $rc = $sth->execute
      or die "Can't execute statement: $DBI::errstr";

  print "Query will return $sth->{NUM_OF_FIELDS} fields.\n\n";
  print "Field names: @{ $sth->{NAME} }\n";

  while (($name, $phone) = $sth->fetchrow_array) {
      print "$name: $phone\n";
  }
  # check for problems which may have terminated the fetch early
  die $sth->errstr if $sth->err;

  $dbh->disconnect;

Here's a complete example program to insert some data from a file. (This example uses RaiseError to avoid needing to check each call).

  my $dbh = DBI->connect("dbi:DriverName:db_name", $user, $password, {
      RaiseError => 1, AutoCommit => 0
  });

  my $sth = $dbh->prepare( q{
      INSERT INTO table (name, phone) VALUES (?, ?)
  });

  open FH, "<phone.csv" or die "Unable to open phone.csv: $!";
  while (<FH>) {
      chomp;
      my ($name, $phone) = split /,/;
      $sth->execute($name, $phone);
  }
  close FH;

  $dbh->commit;
  $dbh->disconnect;

Here's how to convert fetched NULLs (undefined values) into empty strings:

  while($row = $sth->fetchrow_arrayref) {
    # this is a fast and simple way to deal with nulls:
    foreach (@$row) { $_ = '' unless defined }
    print "@$row\n";
  }

The q{...} style quoting used in these examples avoids clashing with quotes that may be used in the SQL statement. Use the double-quote like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

Threads and Thread Safety

Perl 5.7 and later support a new threading model called iThreads. (The old "5.005 style" threads are not supported by the DBI.)

In the iThreads model each thread has it's own copy of the perl interpreter. When a new thread is created the original perl interpreter is 'cloned' to create a new copy for the new thread.

If the DBI and drivers are loaded and handles created before the thread is created then it will get a cloned copy of the DBI, the drivers and the handles.

However, the internal pointer data within the handles will refer to the DBI and drivers in the original interpreter. Using those handles in the new interpreter thread is not safe, so the DBI detects this and croaks on any method call using handles that don't belong to the current thread (except for DESTROY).

Because of this (possibly temporary) restriction, newly created threads must make their own connctions to the database. Handles can't be shared across threads.

But BEWARE, some underlying database APIs (the code the DBD driver uses to talk to the database, often supplied by the database vendor) are not thread safe. If it's not thread safe, then allowing more than one thread to enter the code at the same time may cause subtle/serious problems. In some cases allowing more than one thread to enter the code, even if not at the same time, can cause problems. You have been warned.

Using DBI with perl threads is not yet recommended for production environments. For more information see http://www.perlmonks.org/index.pl

Note: There is a bug in perl 5.8.2 when configured with threads and debugging enabled (bug #24463) which causes a DBI test to fail.

Signal Handling and Canceling Operations

[The following only applies to systems with unix-like signal handling. I'd welcome additions for other systems, especially Windows.]

The first thing to say is that signal handling in Perl versions less than 5.8 is not safe. There is always a small risk of Perl crashing and/or core dumping when, or after, handling a signal because the signal could arrive and be handled while internal data structures are being changed. If the signal handling code used those same internal data structures it could cause all manner of subtle and not-so-subtle problems. The risk was reduced with 5.4.4 but was still present in all perls up through 5.8.0.

Beginning in perl 5.8.0 perl implements 'safe' signal handling if your system has the POSIX sigaction() routine. Now when a signal is delivered perl just makes a note of it but does not run the %SIG handler. The handling is 'defered' until a 'safe' moment.

Although this change made signal handling safe, it also lead to a problem with signals being defered for longer than you'd like. If a signal arrived while executing a system call, such as waiting for data on a network connection, the signal is noted and then the system call that was executing returns with an EINTR error code to indicate that it was interrupted. All fine so far.

The problem comes when the code that made the system call sees the EINTR code and decides it's going to call it again. Perl doesn't do that, but database code sometimes does. If that happens then the signal handler doesn't get called untill later. Maybe much later.

Fortunately there are ways around this which we'll discuss below. Unfortunately they make signals unsafe again.

The two most common uses of signals in relation to the DBI are for canceling operations when the user types Ctrl-C (interrupt), and for implementing a timeout using alarm() and $SIG{ALRM}.

Cancel

The DBI provides a cancel method for statement handles. The cancel method should abort the current operation and is designed to be called from a signal handler. For example:

  $SIG{INT} = sub { $sth->cancel };

However, few drivers implement this (the DBI provides a default method that just returns undef) and, even if implemented, there is still a possibility that the statement handle, and even the parent database handle, will not be usable afterwards.

If cancel returns true, then it has successfully invoked the database engine's own cancel function. If it returns false, then cancel failed. If it returns undef, then the database driver does not have cancel implemented - very few do.

Timeout

The traditional way to implement a timeout is to set $SIG{ALRM} to refer to some code that will be executed when an ALRM signal arrives and then to call alarm($seconds) to schedule an ALRM signal to be delivered $seconds in the future. For example:

  eval {
    local $SIG{ALRM} = sub { die "TIMEOUT\n" };
    alarm($seconds);
    ... code to execute with timeout here ...
    alarm(0);  # cancel alarm (if code ran fast)
  };
  alarm(0);    # cancel alarm (if eval failed)
  if ( $@ eq "TIMEOUT\n" ) { ... }

Unfortunately, as described above, this won't always work as expected, depending on your perl version and the underlying database code.

With Oracle for instance (DBD::Oracle), if the system which hosts the database is down the DBI->connect() call will hang for several minutes before returning an error.

The solution on these systems is to use the POSIX::sigaction() routine to gain low level access to how the signal handler is installed.

The code would look something like this (for the DBD-Oracle connect()):

   use POSIX ':signal_h';

   my $mask = POSIX::SigSet->new( SIGALRM ); # signals to mask in the handler
   my $action = POSIX::SigAction->new(
       sub { die "connect timeout" },        # the handler code ref
       $mask,
       # not using (perl 5.8.2 and later) 'safe' switch or sa_flags
   );
   my $oldaction = POSIX::SigAction->new();
   sigaction( 'ALRM', $action, $oldaction );
   my $dbh;
   eval {
      alarm(5); # seconds before time out
      $dbh = DBI->connect("dbi:Oracle:$dsn" ... );
      alarm(0); # cancel alarm (if connect worked fast)
   };
   alarm(0);    # cancel alarm (if eval failed)
   sigaction( 'ALRM', $oldaction );  # restore original signal handler
   if ( $@ ) ....

Similar techniques can be used for canceling statement execution.

Unfortunately, this solution is somewhat messy, and it does not work with perl versions less than perl 5.8 where POSIX::sigaction() appears to be broken.

For a cleaner implementation that works across perl versions, see Lincoln Baxter's Sys::SigAction module at http://search.cpan.org/~lbaxter/Sys-SigAction/. The documentation for Sys::SigAction includes an longer discussion of this problem, and a DBD::Oracle test script.

Be sure to read all the signal handling sections of the the perlipc manpage manual.

And finally, two more points to keep firmly in mind. Firstly, remember that what we've done here is essentially revert to old style unsafe handling of these signals. So do as little as possible in the handler. Ideally just die(). Secondly, the handles in use at the time the signal is handled may not be safe to use afterwards.

Subclassing the DBI

DBI can be subclassed and extended just like any other object oriented module. Before we talk about how to do that, it's important to be clear about the various DBI classes and how they work together.

By default $dbh = DBI->connect(...) returns a $dbh blessed into the DBI::db class. And the $dbh->prepare method returns an $sth blessed into the DBI::st class (actually it simply changes the last four characters of the calling handle class to be ::st).

The leading 'DBI' is known as the 'root class' and the extra '::db' or '::st' are the 'handle type suffixes'. If you want to subclass the DBI you'll need to put your overriding methods into the appropriate classes. For example, if you want to use a root class of MySubDBI and override the do(), prepare() and execute() methods, then your do() and prepare() methods should be in the MySubDBI::db class and the execute() method should be in the MySubDBI::st class.

To setup the inheritance hierarchy the @ISA variable in MySubDBI::db should include DBI::db and the @ISA variable in MySubDBI::st should include DBI::st. The MySubDBI root class itself isn't currently used for anything visible and so, apart from setting @ISA to include DBI, it can be left empty.

So, having put your overriding methods into the right classes, and setup the inheritance hierarchy, how do you get the DBI to use them? You have two choices, either a static method call using the name of your subclass:

  $dbh = MySubDBI->connect(...);

or specifying a RootClass attribute:

  $dbh = DBI->connect(..., { RootClass => 'MySubDBI' });

If both forms are used then the attribute takes precedence.

The only differences between the two are that using an explicit RootClass attribute will a) make the DBI automatically attempt to load a module by that name if the class doesn't exist, and b) won't call your MySubDBI::connect() method, if you have one.

When subclassing is being used then, after a successful new connect, the DBI->connect method automatically calls:

  $dbh->connected($dsn, $user, $pass, \%attr);

The default method does nothing. The call is made just to simplify any post-connection setup that your subclass may want to perform. The parameters are the same as passed to DBI->connect. If your subclass supplies a connected method, it should be part of the MySubDBI::db package.

One more thing to note: you must let the DBI do the handle creation. If you want to override the connect() method in your *::dr class then it must still call SUPER::connect to get a $dbh to work with. Similarly, an overridden prepare() method in *::db must still call SUPER::prepare to get a $sth. If you try to create your own handles using bless() then you'll find the DBI will reject them with an "is not a DBI handle (has no magic)" error.

Here's a brief example of a DBI subclass. A more thorough example can be found in t/subclass.t in the DBI distribution.

  package MySubDBI;

  use strict;

  use DBI;
  use vars qw(@ISA);
  @ISA = qw(DBI);

  package MySubDBI::db;
  use vars qw(@ISA);
  @ISA = qw(DBI::db);

  sub prepare {
    my ($dbh, @args) = @_;
    my $sth = $dbh->SUPER::prepare(@args)
        or return;
    $sth->{private_mysubdbi_info} = { foo => 'bar' };
    return $sth;
  }

  package MySubDBI::st;
  use vars qw(@ISA);
  @ISA = qw(DBI::st);

  sub fetch {
    my ($sth, @args) = @_;
    my $row = $sth->SUPER::fetch(@args)
        or return;
    do_something_magical_with_row_data($row)
        or return $sth->set_err(1234, "The magic failed", undef, "fetch");
    return $row;
  }

When calling a SUPER::method that returns a handle, be careful to check the return value before trying to do other things with it in your overridden method. This is especially important if you want to set a hash attribute on the handle, as Perl's autovivification will bite you by (in)conveniently creating an unblessed hashref, which your method will then return with usually baffling results later on like the error "dbih_getcom handle HASH(0xa4451a8) is not a DBI handle (has no magic". It's best to check right after the call and return undef immediately on error, just like DBI would and just like the example above.

If your method needs to record an error it should call the set_err() method with the error code and error string, as shown in the example above. The error code and error string will be recorded in the handle and available via $h->err and $DBI::errstr etc. The set_err() method always returns an undef or empty list as approriate. Since your method should nearly always return an undef or empty list as soon as an error is detected it's handy to simply return what set_err() returns, as shown in the example above.

If the handle has RaiseError, PrintError, or HandleError etc. set then the set_err() method will honour them. This means that if RaiseError is set then set_err() won't return in the normal way but will 'throw an exception' that can be caught with an eval block.

You can stash private data into DBI handles via $h->{private_..._*}. See the entry under ATTRIBUTES COMMON TO ALL HANDLES for info and important caveats.

TRACING

The DBI has a powerful tracing mechanism built in. It enables you to see what's going on 'behind the scenes', both within the DBI and the drivers you're using.

Trace Settings

Which details are written to the trace output is controlled by a combination of a trace level, an integer from 0 to 15, and a set of trace flags that are either on or off. Together these are known as the trace settings and are stored together in a single integer. For normal use you only need to set the trace level, and generally only to a value between 1 and 4.

Each handle has it's own trace settings, and so does the DBI. When you call a method the DBI merges the handles settings into its own for the duration of the call: the trace flags of the handle are OR'd into the trace flags of the DBI, and if the handle has a higher trace level then the DBI trace level is raised to match it. The previous DBI trace setings are restored when the called method returns.

Trace Levels

Trace levels are as follows:

  0 - Trace disabled.
  1 - Trace DBI method calls returning with results or errors.
  2 - Trace method entry with parameters and returning with results.
  3 - As above, adding some high-level information from the driver
      and some internal information from the DBI.
  4 - As above, adding more detailed information from the driver.
  5 to 15 - As above but with more and more obscure information.

Trace level 1 is best for a simple overview of what's happening. Trace level 2 is a good choice for general purpose tracing. Levels 3 and above are best reserved for investigating a specific problem, when you need to see "inside" the driver and DBI.

The trace output is detailed and typically very useful. Much of the trace output is formatted using the neat function, so strings in the trace output may be edited and truncated by that function.

Trace Flags

Trace flags are used to enable tracing of specific activities within the DBI and drivers. The DBI defines some trace flags and drivers can define others. DBI trace flag names begin with a capital letter and driver specific names begin with a lowercase letter, as usual.

Curently the DBI only defines two trace flags:

  ALL - turn on all DBI and driver flags (not recommended)
  SQL - trace SQL statements executed (not yet implemented)

The parse_trace_flags and parse_trace_flag methods are used to convert trace flag names into the coresponding integer bit flags.

Enabling Trace

The $h->trace method sets the trace settings for a handle and DBI->trace does the same for the DBI.

In addition to the trace method, you can enable the same trace information, and direct the output to a file, by setting the DBI_TRACE environment variable before starting Perl. See DBI_TRACE for more information.

Finally, you can set, or get, the trace settings for a handle using the TraceLevel attribute.

All of those methods use parse_trace_flags() and so allow you set both the trace level and multiple trace flags by using a string containing the trace level and/or flag names separated by vertical bar ("|") or comma (",") characters. For example:

  local $h->{TraceLevel} = "3|SQL|foo";

Trace Output

Initially trace output is written to STDERR. Both the $h->trace and DBI->trace methods take an optional $trace_file parameter, which may be either the name of a file to be openned by DBI in append mode, or a reference to an existing writable (possibly layered) filehandle. If $trace_file is a filename, and can be opened in append mode, or $trace_file is a writable filehandle, then all trace output (currently including that from other handles) is redirected to that file. A warning is generated if $trace_file can't be opened or is not writable.

Further calls to trace() without $trace_file do not alter where the trace output is sent. If $trace_file is undefined, then trace output is sent to STDERR and, if the prior trace was openned with $trace_file as a filename, the previous trace file is closed; if $trace_file was a filehandle, the filehandle is not closed.

NOTE: If $trace_file is specified as a filehandle, the filehandle should not be closed until all DBI operations are completed, or the application has reset the trace file via another call to trace() that changes the trace file.

Tracing to Layered Filehandles

NOTE:

  • Tied filehandles are not currently supported, as tie operations are not available to the PerlIO methods used by the DBI.
  • PerlIO layer support requires Perl version 5.8 or higher.

As of version 5.8, Perl provides the ability to layer various "disciplines" on an open filehandle via the the PerlIO manpage module.

A simple example of using PerlIO layers is to use a scalar as the output:

    my $scalar = '';
    open( my $fh, "+>:scalar", \$scalar );
    $dbh->trace( 2, $fh );

Now all trace output is simply appended to $scalar.

A more complex application of tracing to a layered filehandle is the use of a custom layer (Refer to the Perlio::via manpage for details on creating custom PerlIO layers.). Consider an application with the following logger module:

    package MyFancyLogger;

    sub new
    {
        my $self = {};
        my $fh;
        open $fh, '>', 'fancylog.log';
        $self->{_fh} = $fh;
        $self->{_buf} = '';
        return bless $self, shift;
    }

    sub log
    {
        my $self = shift;
        return unless exists $self->{_fh};
        my $fh = $self->{_fh};
        $self->{_buf} .= shift;
    #
    # DBI feeds us pieces at a time, so accumulate a complete line
    # before outputing
    #
        print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and
        $self->{_buf} = ''
            if $self->{_buf}=~tr/\n//;
    }

    sub close {
        my $self = shift;
        return unless exists $self->{_fh};
        my $fh = $self->{_fh};
        print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and
        $self->{_buf} = ''
            if $self->{_buf};
        close $fh;
        delete $self->{_fh};
    }

    1;

To redirect DBI traces to this logger requires creating a package for the layer:

    package PerlIO::via::MyFancyLogLayer;

    sub PUSHED
    {
        my ($class,$mode,$fh) = @_;
        my $logger;
        return bless \$logger,$class;
    }

    sub OPEN {
        my ($self, $path, $mode, $fh) = @_;
        #
        # $path is actually our logger object
        #
        $$self = $path;
        return 1;
    }

    sub WRITE
    {
        my ($self, $buf, $fh) = @_;
        $$self->log($buf);
        return length($buf);
    }

    sub CLOSE {
        my $self = shift;
        $$self->close();
        return 0;
    }

    1;

The application can then cause DBI traces to be routed to the logger using

    use PerlIO::via::MyFancyLogLayer;

    open my $fh, '>:via(MyFancyLogLayer)', MyFancyLogger->new();

    $dbh->trace('SQL', $fh);

Now all trace output will be processed by MyFancyLogger's log() method.

Trace Content

Many of the values embeded in trace output are formatted using the neat() utility function. This means they may be quoted, sanitized, and possibly truncated if longer than $DBI::neat_maxlen. See neat for more details.

Tracing Tips

You can add tracing to your own application code using the trace_msg method.

It can sometimes be handy to compare trace files from two different runs of the same script. However using a tool like diff on the original log output doesn't work well because the trace file is full of object addresses that may differ on each run.

The DBI includes a handy utility called dbilogstrip that can be used to 'normalize' the log content. It can be used as a filter like this:

    DBI_TRACE=2 perl yourscript.pl ...args1... 2>&1 | dbilogstrip > dbitrace1.log
    DBI_TRACE=2 perl yourscript.pl ...args2... 2>&1 | dbilogstrip > dbitrace2.log
    diff -u dbitrace1.log dbitrace2.log

See the dbilogstrip manpage for more information.

DBI ENVIRONMENT VARIABLES

The DBI module recognizes a number of environment variables, but most of them should not be used most of the time. It is better to be explicit about what you are doing to avoid the need for environment variables, especially in a web serving system where web servers are stingy about which environment variables are available.

DBI_DSN

The DBI_DSN environment variable is used by DBI->connect if you do not specify a data source when you issue the connect. It should have a format such as "dbi:Driver:databasename".

DBI_DRIVER

The DBI_DRIVER environment variable is used to fill in the database driver name in DBI->connect if the data source string starts "dbi::" (thereby omitting the driver). If DBI_DSN omits the driver name, DBI_DRIVER can fill the gap.

DBI_AUTOPROXY

The DBI_AUTOPROXY environment variable takes a string value that starts "dbi:Proxy:" and is typically followed by "hostname=...;port=...". It is used to alter the behaviour of DBI->connect. For full details, see DBI::Proxy documentation.

DBI_USER

The DBI_USER environment variable takes a string value that is used as the user name if the DBI->connect call is given undef (as distinct from an empty string) as the username argument. Be wary of the security implications of using this.

DBI_PASS

The DBI_PASS environment variable takes a string value that is used as the password if the DBI->connect call is given undef (as distinct from an empty string) as the password argument. Be extra wary of the security implications of using this.

DBI_DBNAME (obsolete)

The DBI_DBNAME environment variable takes a string value that is used only when the obsolescent style of DBI->connect (with driver name as fourth parameter) is used, and when no value is provided for the first (database name) argument.

DBI_TRACE

The DBI_TRACE environment variable specifies the global default trace settings for the DBI at startup. Can also be used to direct trace output to a file. When the DBI is loaded it does:

  DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE};

So if DBI_TRACE contains an "=" character then what follows it is used as the name of the file to append the trace to.

output appended to that file. If the name begins with a number followed by an equal sign (=), then the number and the equal sign are stripped off from the name, and the number is used to set the trace level. For example:

  DBI_TRACE=1=dbitrace.log perl your_test_script.pl

On Unix-like systems using a Bourne-like shell, you can do this easily on the command line:

  DBI_TRACE=2 perl your_test_script.pl

See TRACING for more information.

PERL_DBI_DEBUG (obsolete)

An old variable that should no longer be used; equivalent to DBI_TRACE.

DBI_PROFILE

The DBI_PROFILE environment variable can be used to enable profiling of DBI method calls. See the DBI::Profile manpage for more information.

DBI_PUREPERL

The DBI_PUREPERL environment variable can be used to enable the use of DBI::PurePerl. See the DBI::PurePerl manpage for more information.

WARNING AND ERROR MESSAGES

Fatal Errors

Can't call method "prepare" without a package or object reference

The $dbh handle you're using to call prepare is probably undefined because the preceding connect failed. You should always check the return status of DBI methods, or use the RaiseError attribute.

Can't call method "execute" without a package or object reference

The $sth handle you're using to call execute is probably undefined because the preceeding prepare failed. You should always check the return status of DBI methods, or use the RaiseError attribute.

DBI/DBD internal version mismatch

The DBD driver module was built with a different version of DBI than the one currently being used. You should rebuild the DBD module under the current version of DBI.

(Some rare platforms require "static linking". On those platforms, there may be an old DBI or DBD driver version actually embedded in the Perl executable being used.)

DBD driver has not implemented the AutoCommit attribute

The DBD driver implementation is incomplete. Consult the author.

Can't [sg]et %s->{%s}: unrecognised attribute

You attempted to set or get an unknown attribute of a handle. Make sure you have spelled the attribute name correctly; case is significant (e.g., "Autocommit" is not the same as "AutoCommit").

Pure-Perl DBI

A pure-perl emulation of the DBI is included in the distribution for people using pure-perl drivers who, for whatever reason, can't install the compiled DBI. See the DBI::PurePerl manpage.

SEE ALSO

Driver and Database Documentation

Refer to the documentation for the DBD driver that you are using.

Refer to the SQL Language Reference Manual for the database engine that you are using.

ODBC and SQL/CLI Standards Reference Information

More detailed information about the semantics of certain DBI methods that are based on ODBC and SQL/CLI standards is available on-line via microsoft.com, for ODBC, and www.jtc1sc32.org for the SQL/CLI standard:

 DBI method        ODBC function     SQL/CLI Working Draft
 ----------        -------------     ---------------------
 column_info       SQLColumns        Page 124
 foreign_key_info  SQLForeignKeys    Page 163
 get_info          SQLGetInfo        Page 214
 primary_key_info  SQLPrimaryKeys    Page 254
 table_info        SQLTables         Page 294
 type_info         SQLGetTypeInfo    Page 239
 statistics_info   SQLStatistics

For example, for ODBC information on SQLColumns you'd visit:

  http://msdn.microsoft.com/library/en-us/odbc/htm/odbcsqlcolumns.asp

If that URL ceases to work then use the MSDN search facility at:

  http://search.microsoft.com/us/dev/

and search for SQLColumns returns using the exact phrase option. The link you want will probably just be called SQLColumns and will be part of the Data Access SDK.

And for SQL/CLI standard information on SQLColumns you'd read page 124 of the (very large) SQL/CLI Working Draft available from:

  http://jtc1sc32.org/doc/N0701-0750/32N0744T.pdf

Standards Reference Information

A hyperlinked, browsable version of the BNF syntax for SQL92 (plus Oracle 7 SQL and PL/SQL) is available here:

  http://cui.unige.ch/db-research/Enseignement/analyseinfo/SQL92/BNFindex.html

A BNF syntax for SQL3 is available here:

  http://www.sqlstandards.org/SC32/WG3/Progression_Documents/Informal_working_drafts/iso-9075-2-1999.bnf

The following links provide further useful information about SQL. Some of these are rather dated now but may still be useful.

  http://www.jcc.com/SQLPages/jccs_sql.htm
  http://www.contrib.andrew.cmu.edu/~shadow/sql.html
  http://www.altavista.com/query?q=sql+tutorial

Books and Articles

Programming the Perl DBI, by Alligator Descartes and Tim Bunce. http://books.perl.org/book/154

Programming Perl 3rd Ed. by Larry Wall, Tom Christiansen & Jon Orwant. http://books.perl.org/book/134

Learning Perl by Randal Schwartz. http://books.perl.org/book/101

Details of many other books related to perl can be found at http://books.perl.org

Perl Modules

Index of DBI related modules available from CPAN:

 http://search.cpan.org/search?mode=module&query=DBIx%3A%3A
 http://search.cpan.org/search?mode=doc&query=DBI

For a good comparison of RDBMS-OO mappers and some OO-RDBMS mappers (including Class::DBI, Alzabo, and DBIx::RecordSet in the former category and Tangram and SPOPS in the latter) see the Perl Object-Oriented Persistence project pages at:

 http://poop.sourceforge.net

A similar page for Java toolkits can be found at:

 http://c2.com/cgi-bin/wiki?ObjectRelationalToolComparison

Mailing List

The dbi-users mailing list is the primary means of communication among users of the DBI and its related modules. For details send email to:

 dbi-users-help@perl.org

There are typically between 700 and 900 messages per month. You have to subscribe in order to be able to post. However you can opt for a 'post-only' subscription.

Mailing list archives (of variable quality) are held at:

 http://groups.google.com/groups?group=perl.dbi.users
 http://www.xray.mpe.mpg.de/mailing-lists/dbi/
 http://www.mail-archive.com/dbi-users%40perl.org/

Assorted Related WWW Links

The DBI "Home Page":

 http://dbi.perl.org/

Other DBI related links:

 http://tegan.deltanet.com/~phlip/DBUIdoc.html
 http://dc.pm.org/perl_db.html
 http://wdvl.com/Authoring/DB/Intro/toc.html
 http://www.hotwired.com/webmonkey/backend/tutorials/tutorial1.html
 http://bumppo.net/lists/macperl/1999/06/msg00197.html
 http://gmax.oltrelinux.com/dbirecipes.html

Other database related links:

 http://www.jcc.com/sql_stnd.html
 http://cuiwww.unige.ch/OSG/info/FreeDB/FreeDB.home.html
 http://www.connectionstrings.com/

Security, especially the "SQL Injection" attack:

 http://www.ngssoftware.com/research/papers.html
 http://www.ngssoftware.com/papers/advanced_sql_injection.pdf
 http://www.ngssoftware.com/papers/more_advanced_sql_injection.pdf
 http://www.esecurityplanet.com/trends/article.php/2243461
 http://www.spidynamics.com/papers/SQLInjectionWhitePaper.pdf
 http://www.imperva.com/application_defense_center/white_papers/blind_sql_server_injection.html
 http://online.securityfocus.com/infocus/1644

Commercial and Data Warehouse Links

 http://www.dwinfocenter.org
 http://www.datawarehouse.com
 http://www.datamining.org
 http://www.olapcouncil.org
 http://www.idwa.org
 http://www.knowledgecenters.org/dwcenter.asp

Recommended Perl Programming Links

 http://language.perl.com/style/

FAQ

Please also read the DBI FAQ which is installed as a DBI::FAQ module. You can use perldoc to read it by executing the perldoc DBI::FAQ command.

AUTHORS

DBI by Tim Bunce, http://www.linkedin.com/in/timbunce

This pod text by Tim Bunce, J. Douglas Dunlop, Jonathan Leffler and others. Perl by Larry Wall and the perl5-porters.

COPYRIGHT

The DBI module is Copyright (c) 1994-2004 Tim Bunce. Ireland. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SUPPORT / WARRANTY

The DBI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

Support

My consulting company, Data Plan Services, offers annual and multi-annual support contracts for the DBI. These provide sustained support for DBI development, and sustained value for you in return. Contact me for details.

Sponsor Enhancements

The DBI Roadmap is available at http://search.cpan.org/~timb/DBI/Roadmap.pod

If your company would benefit from a specific new DBI feature, please consider sponsoring its development. Work is performed rapidly, and usually on a fixed-price payment-on-delivery basis. Contact me for details.

Using such targeted financing allows you to contribute to DBI development, and rapidly get something specific and valuable in return.

ACKNOWLEDGEMENTS

I would like to acknowledge the valuable contributions of the many people I have worked with on the DBI project, especially in the early years (1992-1994). In no particular order: Kevin Stock, Buzz Moschetti, Kurt Andersen, Ted Lemon, William Hails, Garth Kennedy, Michael Peppler, Neil S. Briscoe, Jeff Urlwin, David J. Hughes, Jeff Stander, Forrest D Whitcher, Larry Wall, Jeff Fried, Roy Johnson, Paul Hudson, Georg Rehfeld, Steve Sizemore, Ron Pool, Jon Meek, Tom Christiansen, Steve Baumgarten, Randal Schwartz, and a whole lot more.

Then, of course, there are the poor souls who have struggled through untold and undocumented obstacles to actually implement DBI drivers. Among their ranks are Jochen Wiedmann, Alligator Descartes, Jonathan Leffler, Jeff Urlwin, Michael Peppler, Henrik Tougaard, Edwin Pratomo, Davide Migliavacca, Jan Pazdziora, Peter Haworth, Edmund Mergl, Steve Williams, Thomas Lowery, and Phlip Plumlee. Without them, the DBI would not be the practical reality it is today. I'm also especially grateful to Alligator Descartes for starting work on the first edition of the "Programming the Perl DBI" book and letting me jump on board.

The DBI and DBD::Oracle were originally developed while I was Technical Director (CTO) of Ingeneering in the UK (http://www.ig.co.uk) (formerly known as the Paul Ingram Group). So I'd especially like to thank Paul for his generosity and vision in supporting this work for many years.

A couple of specific DBI features have been sponsored by enlightened companies:

The development of the swap_inner_handle() method was sponsored by BizRate.com (http://BizRate.com)

The development of DBD::Gofer and related modules was sponsored by Shopzilla.com (http://Shopzilla.com), where I currently work.

CONTRIBUTING

As you can see above, many people have contributed to the DBI and drivers in many ways over many years.

If you'd like to help then see http://dbi.perl.org/contributing and http://search.cpan.org/~timb/DBI/Roadmap.pod

If you'd like the DBI to do something new or different then a good way to make that happen is to do it yourself and send me a patch to the source code that shows the changes. (But read "Speak before you patch" below.)

Browsing the source code repository

Use http://svn.perl.org/modules/dbi/trunk (basic) or http://svn.perl.org/viewcvs/modules/ (more useful)

How to create a patch using Subversion

The DBI source code is maintained using Subversion (a replacement for CVS, see http://subversion.tigris.org/). To access the source you'll need to install a Subversion client. Then, to get the source code, do:

  svn checkout http://svn.perl.org/modules/dbi/trunk

If it prompts for a username and password use your perl.org account if you have one, else just 'guest' and 'guest'. The source code will be in a new subdirectory called trunk.

To keep informed about changes to the source you can send an empty email to svn-commit-modules-dbi-subscribe@perl.org after which you'll get an email with the change log message and diff of each change checked-in to the source.

After making your changes you can generate a patch file, but before you do, make sure your source is still upto date using:

  svn update

If you get any conflicts reported you'll need to fix them first. Then generate the patch file from within the trunk directory using:

  svn diff > foo.patch

Read the patch file, as a sanity check, and then email it to dbi-dev@perl.org.

How to create a patch without Subversion

Unpack a fresh copy of the distribution:

  tar xfz DBI-1.40.tar.gz

Rename the newly created top level directory:

  mv DBI-1.40 DBI-1.40.your_foo

Edit the contents of DBI-1.40.your_foo/* till it does what you want.

Test your changes and then remove all temporary files:

  make test && make distclean

Go back to the directory you originally unpacked the distribution:

  cd ..

Unpack another copy of the original distribution you started with:

  tar xfz DBI-1.40.tar.gz

Then create a patch file by performing a recursive diff on the two top level directories:

  diff -r -u DBI-1.40 DBI-1.40.your_foo > DBI-1.40.your_foo.patch

Speak before you patch

For anything non-trivial or possibly controversial it's a good idea to discuss (on dbi-dev@perl.org) the changes you propose before actually spending time working on them. Otherwise you run the risk of them being rejected because they don't fit into some larger plans you may not be aware of.

TRANSLATIONS

A German translation of this manual (possibly slightly out of date) is available, thanks to O'Reilly, at:

  http://www.oreilly.de/catalog/perldbiger/

Some other translations:

 http://cronopio.net/perl/                              - Spanish
 http://member.nifty.ne.jp/hippo2000/dbimemo.htm        - Japanese

TRAINING

References to DBI related training resources. No recommendation implied.

  http://www.treepax.co.uk/
  http://www.keller.com/dbweb/

(If you offer professional DBI related training services, please send me your details so I can add them here.)

OTHER RELATED WORK AND PERL MODULES

Apache::DBI by E.Mergl@bawue.de

To be used with the Apache daemon together with an embedded Perl interpreter like mod_perl. Establishes a database connection which remains open for the lifetime of the HTTP daemon. This way the CGI connect and disconnect for every database access becomes superfluous.

SQL Parser

See also the the SQL::Statement manpage module, SQL parser and engine.


DBI::Changes - List of significant changes to the DBI

  • NAME
    • Changes in DBI 1.57 (svn rev 9639), 13th June 2007
    • Changes in DBI 1.56 (svn rev 9660), 18th June 2007
    • Changes in DBI 1.55 (svn rev 9504), 4th May 2007
    • Changes in DBI 1.54 (svn rev 9157), 23rd February 2007
    • Changes in DBI 1.53 (svn rev 7995), 31st October 2006
    • Changes in DBI 1.52 (svn rev 6840), 30th July 2006
    • Changes in DBI 1.51 (svn rev 6475), 6th June 2006
    • Changes in DBI 1.50 (svn rev 2307), 13 December 2005
    • Changes in DBI 1.49 (svn rev 2287), 29th November 2005
    • Changes in DBI 1.48 (svn rev 928), 14th March 2005
    • Changes in DBI 1.47 (svn rev 854), 2nd February 2005
    • Changes in DBI 1.46 (svn rev 584), 16th November 2004
    • Changes in DBI 1.45 (svn rev 480), 6th October 2004
    • Changes in DBI 1.44 (svn rev 478), 5th October 2004
    • Changes in DBI 1.43 (svn rev 377), 2nd July 2004
    • Changes in DBI 1.42 (svn rev 222), 12th March 2004
    • Changes in DBI 1.41 (svn rev 130), 22nd February 2004
    • Changes in DBI 1.40, 7th January 2004
    • Changes in DBI 1.39, 27th November 2003
    • Changes in DBI 1.38, 21th August 2003
    • Changes in DBI 1.37, 15th May 2003
    • Changes in DBI 1.36, 11th May 2003
    • Changes in DBI 1.35, 7th March 2003
    • Changes in DBI 1.34, 28th February 2003
    • Changes in DBI 1.33, 27th February 2003
    • Changes in DBI 1.32, 1st December 2002
    • Changes in DBI 1.31, 29th November 2002
    • Changes in DBI 1.30, 18th July 2002
    • Changes in DBI 1.29, 15th July 2002
    • Changes in DBI 1.28, 14th June 2002
    • Changes in DBI 1.27, 13th June 2002
    • Changes in DBI 1.26, 13th June 2002
    • Changes in DBI 1.25, 5th June 2002
    • Changes in DBI 1.24, 4th June 2002
    • Changes in DBI 1.23, 25th May 2002
    • Changes in DBI 1.22, 22nd May 2002
    • Changes in DBI 1.21, 7th February 2002
    • Changes in DBI 1.20, 24th August 2001
    • Changes in DBI 1.19, 20th July 2001
    • Changes in DBI 1.18, 4th June 2001
    • Changes in DBI 1.16, 30th May 2001
    • Changes in DBI 1.15, 28th March 2001
    • Changes in DBI 1.14, 14th June 2000
    • Changes in DBI 1.13, 11th July 1999
    • Changes in DBI 1.12, 29th June 1999
    • Changes in DBI 1.11, 17th June 1999
    • Changes in DBI 1.10, 14th June 1999
    • Changes in DBI 1.09, 9th June 1999
    • Changes in DBI 1.08, 12th May 1999
    • Changes in DBI 1.07, 6th May 1999
    • Changes in DBI 1.06, 6th January 1999
    • Changes in DBI 1.05, 4th January 1999
    • Changes in DBI 1.04, 3rd January 1999
    • Changes in DBI 1.03, 1st January 1999
    • Changes in DBI 1.02, 2nd September 1998
    • Changes in DBI 1.01, 2nd September 1998
    • Changes in DBI 1.00, 14th August 1998
    • Changes in DBI 0.95, 10th August 1998
    • Changes in DBI 0.94, 9th August 1998
    • Changes in DBI 0.93, 13th February 1998
    • Changes in DBI 0.92, 3rd February 1998
    • Changes in DBI 0.91, 10th December 1997
    • Changes in DBI 0.90, 6th September 1997
    • Changes in DBI 0.89, 25th July 1997
    • Changes in DBI 0.88, 22nd July 1997
    • Changes in DBI 0.87, 18th July 1997
    • Changes in DBI 0.86, 16th July 1997
    • Changes in DBI 0.85, 25th June 1997
    • Changes in DBI 0.84, 20th June 1997
    • Changes in DBI 0.83, 11th June 1997
    • Changes in DBI 0.82, 23rd May 1997
    • Changes in DBI 0.81, 7th May 1997
    • Changes in DBI 0.80, 6th May 1997
    • Changes in DBI 0.79, 7th Apr 1997
    • Changes in DBI 0.78, 28th Mar 1997
    • Changes in DBI 0.77, 21st Feb 1997
    • Changes in DBI 0.76, 3rd Feb 1997
    • Changes in DBI 0.75, 27th Jan 1997
    • Changes in DBI 0.74, 14th Jan 1997
    • Changes in DBI 0.73, 10th Oct 1996
    • Changes in DBI 0.72, 23 Sep 1996
    • Changes in DBI 0.71, 10 July 1996
    • Changes in DBI 0.70, 16 June 1996
    • Changes in DBI 0.69
    • Changes in DBI 0.68, 2 Mar 1996
    • Changes in DBI 0.67, 15 Feb 1996
    • Changes in DBI 0.66, 29 Jan 1996
    • Changes in DBI 0.65, 23 Oct 1995
    • Changes in DBI 0.64, 23 Oct 1995
    • Changes in DBI 0.63, 1 Sep 1995
    • Changes in DBI 0.62, 26 Aug 1995
    • Changes in DBI 0.61, 22 Aug 1995
    • Changes in DBI 0.60, 17 Aug 1995
    • Changes in DBI 0.59 15 Aug 1995
    • Changes in DBI 0.58 21 June 1995
  • ANCIENT HISTORY

NAME

DBI::Changes - List of significant changes to the DBI

(As of $Date: 2007-06-18 15:19:45 +0100 (Mon, 18 Jun 2007) $ $Revision: 9659 $)

Changes in DBI 1.57 (svn rev 9639), 13th June 2007

  Note: this release includes a change to the DBI::hash() function which will
  now produce different values than before *if* your perl was built with 64-bit
  'int' type (i.e. "perl -V:intsize" says intsize='4').  It's relatively rare
  for perl to be configured that way, even on 64-bit systems.
  Fixed XS versions of select*_*() methods to call execute()
    fetch() etc., with inner handle instead of outer.
  Fixed execute_for_fetch() to not cache errstr values
    thanks to Bart Degryse.
  Fixed unused var compiler warning thanks to JDHEDDEN.
  Fixed t/86gofer_fail tests to be less likely to fail falsely.
  Changed DBI::hash to return 'I32' type instead of 'int' so results are
    portable/consistent regardless of size of the int type.
  Corrected timeout example in docs thanks to Egmont Koblinger.
  Changed t/01basic.t to warn instead of failing when it detects
    a problem with Math::BigInt (some recent versions had problems).
  Added support for !Time and !Time~N to DBI::Profile Path. See docs.
  Added extra trace info to connect_cached thanks to Walery Studennikov.
  Added non-random (deterministic) mode to DBI_GOFER_RANDOM mechanism.
  Added DBIXS_REVISION macro that drivers can use.
  Added more docs for private_attribute_info() method.
  DBI::Profile changes:
    dbi_profile() now returns ref to relevant leaf node.
    Don't profile DESTROY during global destruction.
    Added as_node_path_list() and as_text() methods.
  DBI::ProfileDumper changes:
    Don't write file if there's no profile data.
    Uses full natural precision when saving data (was using %.6f)
    Optimized flush_to_disk().
    Locks the data file while writing.
    Enabled filename to be a code ref for dynamic names.
  DBI::ProfileDumper::Apache changes:
    Added Quiet=>1 to avoid write to STDERR in flush_to_disk().
    Added Dir=>... to specify a writable destination directory.
    Enabled DBI_PROFILE_APACHE_LOG_DIR for mod_perl 1 as well as 2.
    Added parent pid to default data file name.
  DBI::ProfileData changes:
    Added DeleteFiles option to rename & delete files once read.
    Locks the data files while reading.
    Added ability to sort by Path elements.
  dbiprof changes:
    Added --dumpnodes and --delete options.
  Added/updated docs for both DBI::ProfileDumper && ::Apache.

Changes in DBI 1.56 (svn rev 9660), 18th June 2007

  Fixed printf arg warnings thanks to JDHEDDEN.
  Fixed returning driver-private sth attributes via gofer.
  Changed pod docs docs to use =head3 instead of =item
    so now in html you get links to individual methods etc.
  Changed default gofer retry_limit from 2 to 0.
  Changed tests to workaround Math::BigInt broken versions.
  Changed dbi_profile_merge() to dbi_profile_merge_nodes()
    old name still works as an alias for the new one.
  Removed old DBI internal sanity check that's no longer valid
    causing "panic: DESTROY (dbih_clearcom)" when tracing enabled
  Added DBI_GOFER_RANDOM env var that can be use to trigger random
    failures and delays when executing gofer requests. Designed to help
    test automatic retry on failures and timeout handling.
  Added lots more docs to all the DBD::Gofer and DBI::Gofer classes.

Changes in DBI 1.55 (svn rev 9504), 4th May 2007

  Fixed set_err() so HandleSetErr hook is executed reliably, if set.
  Fixed accuracy of profiling when perl configured to use long doubles.
  Fixed 42prof_data.t on fast systems with poor timers thanks to Malcolm Nooning.
  Fixed potential corruption in selectall_arrayref and selectrow_arrayref
    for compiled drivers, thanks to Rob Davies.
    Rebuild your compiled drivers after installing DBI.
  Changed some handle creation code from perl to C code,
    to reduce handle creation cost by ~20%.
  Changed internal implementation of the CachedKids attribute
    so it's a normal handle attribute (and initially undef).
  Changed connect_cached and prepare_cached to avoid a FETCH method call,
    and thereby reduced cost by ~5% and ~30% respectively.
  Changed _set_fbav to not croak when given a wrongly sized array,
    it now warns and adjusts the row buffer to match.
  Changed some internals to improve performance with threaded perls.
  Changed DBD::NullP to be slightly more useful for testing.
  Changed File::Spec prerequisite to not require a minimum version.
  Changed tests to work with other DBMs thanks to ZMAN.
  Changed ex/perl_dbi_nulls_test.pl to be more descriptive.
  Added more functionality to the (undocumented) Callback mechanism.
    Callbacks can now elect to provide a value to be returned, in which case
    the method won't be called. A callback for "*" is applied to all methods
    that don't have their own callback.
  Added $h->{ReadOnly} attribute.
  Added support for DBI Profile Path to contain refs to scalars
    which will be de-ref'd for each profile sample.
  Added dbilogstrip utility to edit DBI logs for diff'ing (gets installed)
  Added details for SQLite 3.3 to NULL handling docs thanks to Alex Teslik.
  Added take_imp_data() to DBI::PurePerl.

  Gofer related changes:
    Fixed gofer pipeone & stream transports to avoid risk of hanging.
    Improved error handling and tracing significantly.
    Added way to generate random 1-in-N failures for methods.
    Added automatic retry-on-error mechanism to gofer transport base class.
    Added tests to show automatic retry mechanism works a treat!
    Added go_retry_hook callback hook so apps can fine-tune retry behaviour.
    Added header to request and response packets for sanity checking
      and to enable version skew between client and server.
    Added forced_single_resultset, max_cached_sth_per_dbh and max_cached_dbh_per_drh
      to gofer executor config.
    Driver-private methods installed with install_method are now proxied.
    No longer does a round-trip to the server for methods it knows
      have not been overridden by the remote driver.
    Most significant aspects of gofer behaviour are controlled by policy mechanism.
    Added policy-controlled caching of results for some methods, such as schema metadata.
    The connect_cached and prepare_cached methods cache on client and server.
    The bind_param_array and execute_array methods are now supported.
    Worked around a DBD::Sybase bind_param bug (which is fixed in DBD::Sybase 1.07)
    Added goferperf.pl utility (doesn't get installed).
    Many other assorted Gofer related bug fixes, enhancements and docs.
    The http and mod_perl transports have been remove to their own distribution.
    Client and server will need upgrading together for this release.

Changes in DBI 1.54 (svn rev 9157), 23rd February 2007

  NOTE: This release includes the 'next big thing': DBD::Gofer.
  Take a look!
  WARNING: This version has some subtle changes in DBI internals.
  It's possible, though doubtful, that some may affect your code.
  I recommend some extra testing before using this release.
  Or perhaps I'm just being over cautious...
  Fixed type_info when called for multiple dbh thanks to Cosimo Streppone.
  Fixed compile warnings in bleadperl on freebsd-6.1-release
    and solaris 10g thanks to Philip M. Gollucci.
  Fixed to compile for perl built with -DNO_MATHOMS thanks to Jerry D. Hedden.
  Fixed to work for bleadperl (r29544) thanks to Nicholas Clark.
    Users of Perl >= 5.9.5 will require DBI >= 1.54.
  Fixed rare error when profiling access to $DBI::err etc tied variables.
  Fixed DBI::ProfileDumper to not be affected by changes to $/ and $,
    thanks to Michael Schwern.
  Changed t/40profile.t to skip tests for perl < 5.8.0.
  Changed setting trace file to no longer write "Trace file set" to new file.
  Changed 'handle cleared whilst still active' warning for dbh
    to only be given for dbh that have active sth or are not AutoCommit.
  Changed take_imp_data to call finish on all Active child sth.
  Changed DBI::PurePerl trace() method to be more consistent.
  Changed set_err method to effectively not append to errstr if the new errstr
    is the same as the current one.
  Changed handle factory methods, like connect, prepare, and table_info,
    to copy any error/warn/info state of the handle being returned
    up into the handle the method was called on.
  Changed row buffer handling to not alter NUM_OF_FIELDS if it's
    inconsistent with number of elements in row buffer array.
  Updated DBI::DBD docs re handling multiple result sets.
  Updated DBI::DBD docs for driver authors thanks to Ammon Riley
    and Dean Arnold.
  Updated column_info docs to note that if a table doesn't exist
    you get an sth for an empty result set and not an error.
  Added new DBD::Gofer 'stateless proxy' driver and framework,
    and the DBI test suite is now also executed via DBD::Gofer,
    and DBD::Gofer+DBI::PurePerl, in addition to DBI::PurePerl.
  Added ability for trace() to support filehandle argument,
    including tracing into a string, thanks to Dean Arnold.
  Added ability for drivers to implement func() method
    so proxy drivers can proxy the func method itself.
  Added SQL_BIGINT type code (resolved to the ODBC/JDBC value (-5))
  Added $h->private_attribute_info method.

Changes in DBI 1.53 (svn rev 7995), 31st October 2006

  Fixed checks for weaken to work with early 5.8.x versions
  Fixed DBD::Proxy handling of some methods, including commit and rollback.
  Fixed t/40profile.t to be more insensitive to long double precision.
  Fixed t/40profile.t to be insensitive to small negative shifts in time
    thanks to Jamie McCarthy.
  Fixed t/40profile.t to skip tests for perl < 5.8.0.
  Fixed to work with current 'bleadperl' (~5.9.5) thanks to Steve Peters.
    Users of Perl >= 5.9.5 will require DBI >= 1.53.
  Fixed to be more robust against drivers not handling multiple result
    sets properly, thanks to Gisle Aas.
  Added array context support to execute_array and execute_for_fetch
    methods which returns executed tuples and rows affected.
  Added Tie::Cache::LRU example to docs thanks to Brandon Black.

Changes in DBI 1.52 (svn rev 6840), 30th July 2006

  Fixed memory leak (per handle) thanks to Nicholas Clark and Ephraim Dan.
  Fixed memory leak (16 bytes per sth) thanks to Doru Theodor Petrescu.
  Fixed execute_for_fetch/execute_array to RaiseError thanks to Martin J. Evans.
  Fixed for perl 5.9.4. Users of Perl >= 5.9.4 will require DBI >= 1.52.
  Updated DBD::File to 0.35 to match the latest release on CPAN.
  Added $dbh->statistics_info specification thanks to Brandon Black.
  Many changes and additions to profiling:
    Profile Path can now uses sane strings instead of obscure numbers,
    can refer to attributes, assorted magical values, and even code refs!
    Parsing of non-numeric DBI_PROFILE env var values has changed.
    Changed DBI::Profile docs extensively - many new features.
    See DBI::Profile docs for more information.

Changes in DBI 1.51 (svn rev 6475), 6th June 2006

  Fixed $dbh->clone method 'signature' thanks to Jeffrey Klein.
  Fixed default ping() method to return false if !$dbh->{Active}.
  Fixed t/40profile.t to be insensitive to long double precision.
  Fixed for perl 5.8.0's more limited weaken() function.
  Fixed DBD::Proxy to not alter $@ in disconnect or AUTOLOADd methods.
  Fixed bind_columns() to use return set_err(...) instead of die()
    to report incorrect number of parameters, thanks to Ben Thul.
  Fixed bind_col() to ignore undef as bind location, thanks to David Wheeler.
  Fixed for perl 5.9.x for non-threaded builds thanks to Nicholas Clark.
    Users of Perl >= 5.9.x will require DBI >= 1.51.
  Fixed fetching of rows as hash refs to preserve utf8 on field names
    from $sth->{NAME} thanks to Alexey Gaidukov.
  Fixed build on Win32 (dbd_postamble) thanks to David Golden.

  Improved performance for thread-enabled perls thanks to Gisle Aas.
  Drivers can now use PERL_NO_GET_CONTEXT thanks to Gisle Aas.
    Driver authors please read the notes in the DBI::DBD docs.
  Changed DBI::Profile format to always include a percentage,
    if not exiting then uses time between the first and last DBI call.
  Changed DBI::ProfileData to be more forgiving of systems with
    unstable clocks (where time may go backwards occasionally).
  Clarified the 'Subclassing the DBI' docs.
  Assorted minor changes to docs from comments on annocpan.org.
  Changed Makefile.PL to avoid incompatible options for old gcc.
  Added 'fetch array of hash refs' example to selectall_arrayref
    docs thanks to Tom Schindl.
  Added docs for $sth->{ParamArrays} thanks to Martin J. Evans.
  Added reference to $DBI::neat_maxlen in TRACING section of docs.
  Added ability for DBI::Profile Path to include attributes
    and a summary of where the code was called from.

Changes in DBI 1.50 (svn rev 2307), 13 December 2005

  Fixed Makefile.PL options for gcc bug introduced in 1.49.
  Fixed handle magic order to keep DBD::Oracle happy.
  Fixed selectrow_array to return empty list on error.
  Changed dbi_profile_merge() to be able to recurse and merge
    sub-trees of profile data.
  Added documentation for dbi_profile_merge(), including how to
    measure the time spent inside the DBI for an http request.

Changes in DBI 1.49 (svn rev 2287), 29th November 2005

  Fixed assorted attribute handling bugs in DBD::Proxy.
  Fixed croak() in DBD::NullP thanks to Sergey Skvortsov.
  Fixed handling of take_imp_data() and dbi_imp_data attribute.
  Fixed bugs in DBD::DBM thanks to Jeff Zucker.
  Fixed bug in DBI::ProfileDumper thanks to Sam Tregar.
  Fixed ping in DBD::Proxy thanks to George Campbell.
  Fixed dangling ref in $sth after parent $dbh destroyed
    with thanks to il@rol.ru for the bug report #13151
  Fixed prerequisites to include Storable thanks to Michael Schwern.
  Fixed take_imp_data to be more practical.
  Change to require perl 5.6.1 (as advertised in 2003) not 5.6.0.
  Changed internals to be more strictly coded thanks to Andy Lester.
  Changed warning about multiple copies of Driver.xst found in @INC
    to ignore duplicated directories thanks to Ed Avis.
  Changed Driver.xst to enable drivers to define an dbd_st_prepare_sv
    function where the statement parameter is an SV. That enables
    compiled drivers to support SQL strings that are UTF-8.
  Changed "use DBI" to only set $DBI::connect_via if not already set.
  Changed docs to clarify pre-method clearing of err values.
  Added ability for DBI::ProfileData to edit profile path on loading.
    This enables aggregation of different SQL statements into the same
    profile node - very handy when not using placeholders or when working
    multiple separate tables for the same thing (ie logtable_2005_11_28)
  Added $sth->{ParamTypes} specification thanks to Dean Arnold.
  Added $h->{Callbacks} attribute to enable code hooks to be invoked
    when certain methods are called. For example:
    $dbh->{Callbacks}->{prepare} = sub { ... };
    With thanks to David Wheeler for the kick start.
  Added $h->{ChildHandles} (using weakrefs) thanks to Sam Tregar
    I've recoded it in C so there's no significant performance impact.
  Added $h->{Type} docs (returns 'dr', 'db', or 'st')
  Adding trace message in DESTROY if InactiveDestroy enabled.
  Added %drhs = DBI->installed_drivers();

  Ported DBI::ProfileDumper::Apache to mod_perl2 RC5+
    thanks to Philip M. Golluci

Changes in DBI 1.48 (svn rev 928), 14th March 2005

  Fixed DBI::DBD::Metadata generation of type_info_all thanks to Steffen Goeldner
    (driver authors who have used it should rerun it).
  Updated docs for NULL Value placeholders thanks to Brian Campbell.

  Added multi-keyfield nested hash fetching to fetchall_hashref()
    thanks to Zhuang (John) Li for polishing up my draft.
  Added registered driver prefixes: amzn_ for DBD::Amazon and yaswi_ for DBD::Yaswi.

Changes in DBI 1.47 (svn rev 854), 2nd February 2005

  Fixed DBI::ProxyServer to not create pid files by default.
    References: Ubuntu Security Notice USN-70-1, CAN-2005-0077
    Thanks to Javier Fernández-Sanguino Peña from the
    Debian Security Audit Project, and Jonathan Leffler.
  Fixed some tests to work with older Test::More versions.
  Fixed setting $DBI::err/errstr in DBI::PurePerl.
  Fixed potential undef warning from connect_cached().
  Fixed $DBI::lasth handling for DESTROY so lasth points to
    parent even if DESTROY called other methods.
  Fixed DBD::Proxy method calls to not alter $@.
  Fixed DBD::File problem with encoding pragma thanks to Erik Rijkers.
  Changed error handling so undef errstr doesn't cause warning.
  Changed DBI::DBD docs to use =head3/=head4 pod thanks to
    Jonathan Leffler. This may generate warnings for perl 5.6.
  Changed DBI::PurePerl to set autoflush on trace filehandle.
  Changed DBD::Proxy to treat Username as a local attribute
    so recent DBI version can be used with old DBI::ProxyServer.
  Changed driver handle caching in DBD::File.
  Added $GetInfoType{SQL_DATABASE_NAME} thanks to Steffen Goeldner.

  Updated docs to recommend some common DSN string attributes.
  Updated connect_cached() docs with issues and suggestions.
  Updated docs for NULL Value placeholders thanks to Brian Campbell.
  Updated docs for primary_key_info and primary_keys.
  Updated docs to clarify that the default fetchrow_hashref behaviour,
    of returning a ref to a new hash for each row, will not change.
  Updated err/errstr/state docs for DBD authors thanks to Steffen Goeldner.
  Updated handle/attribute docs for DBD authors thanks to Steffen Goeldner.
  Corrected and updated LongReadLen docs thanks to Bart Lateur.
  Added DBD::JDBC as a registered driver.

Changes in DBI 1.46 (svn rev 584), 16th November 2004

  Fixed parsing bugs in DBI::SQL::Nano thanks to Jeff Zucker.
  Fixed a couple of bad links in docs thanks to Graham Barr.
  Fixed test.pl Win32 undef warning thanks to H.Merijn Brand & David Repko.
  Fixed minor issues in DBI::DBD::Metadata thanks to Steffen Goeldner.
  Fixed DBI::PurePerl neat() to use double quotes for utf8.
  Changed execute_array() definition, and default implementation,
    to not consider scalar values for execute tuple count. See docs.
  Changed DBD::File to enable ShowErrorStatement by default,
    which affects DBD::File subclasses such as DBD::CSV and DBD::DBM.
  Changed use DBI qw(:utils) tag to include $neat_maxlen.
  Updated Roadmap and ToDo.
  Added data_string_diff() data_string_desc() and data_diff()
    utility functions to help diagnose Unicode issues.
    All can be imported via the use DBI qw(:utils) tag.

Changes in DBI 1.45 (svn rev 480), 6th October 2004

  Fixed DBI::DBD code for drivers broken in 1.44.
  Fixed "Free to wrong pool"/"Attempt to free unreferenced scalar" in FETCH.

Changes in DBI 1.44 (svn rev 478), 5th October 2004

  Fixed build issues on VMS thanks to Jakob Snoer.
  Fixed DBD::File finish() method to return 1 thanks to Jan Dubois.
  Fixed rare core dump during global destruction thanks to Mark Jason Dominus.
  Fixed risk of utf8 flag persisting from one row to the next.
  Changed bind_param_array() so it doesn't require all bind arrays
    to have the same number of elements.
  Changed bind_param_array() to error if placeholder number <= 0.
  Changed execute_array() definition, and default implementation,
    to effectively NULL-pad shorter bind arrays.
  Changed execute_array() to return "0E0" for 0 as per the docs.
  Changed execute_for_fetch() definition, and default implementation,
    to return "0E0" for 0 like execute() and execute_array().
  Changed Test::More prerequisite to Test::Simple (which is also the name
    of the distribution both are packaged in) to work around ppm behaviour.
  Corrected docs to say that get/set of unknown attribute generates
    a warning and is no longer fatal. Thanks to Vadim.
  Corrected fetchall_arrayref() docs example thanks to Drew Broadley.
  Added $h1->swap_inner_handle($h2) sponsored by BizRate.com

Changes in DBI 1.43 (svn rev 377), 2nd July 2004

  Fixed connect() and connect_cached() RaiseError/PrintError
    which would sometimes show "(no error string)" as the error.
  Fixed compiler warning thanks to Paul Marquess.
  Fixed "trace level set to" trace message thanks to H.Merijn Brand.
  Fixed DBD::DBM $dbh->{dbm_tables}->{...} to be keyed by the
    table name not the file name thanks to Jeff Zucker.
  Fixed last_insert_id(...) thanks to Rudy Lippan.
  Fixed propagation of scalar/list context into proxied methods.
  Fixed DBI::Profile::DESTROY to not alter $@.
  Fixed DBI::ProfileDumper new() docs thanks to Michael Schwern.
  Fixed _load_class to propagate $@ thanks to Drew Taylor.
  Fixed compile warnings on Win32 thanks to Robert Baron.
  Fixed problem building with recent versions of MakeMaker.
  Fixed DBD::Sponge not to generate warning with threads.
  Fixed DBI_AUTOPROXY to work more than once thanks to Steven Hirsch.

  Changed TraceLevel 1 to not show recursive/nested calls.
  Changed getting or setting an invalid attribute to no longer be
    a fatal error but generate a warning instead.
  Changed selectall_arrayref() to call finish() if
    $attr->{MaxRows} is defined.
  Changed all tests to use Test::More and enhanced the tests thanks
    to Stevan Little and Andy Lester. See http://qa.perl.org/phalanx/
  Changed Test::More minimum prerequisite version to 0.40 (2001).
  Changed DBI::Profile header to include the date and time.

  Added DBI->parse_dsn($dsn) method.
  Added warning if build directory path contains whitespace.
  Added docs for parse_trace_flags() and parse_trace_flag().
  Removed "may change" warnings from the docs for table_info(),
    primary_key_info(), and foreign_key_info() methods.

Changes in DBI 1.42 (svn rev 222), 12th March 2004

  Fixed $sth->{NUM_OF_FIELDS} of non-executed statement handle
    to be undef as per the docs (it was 0).
  Fixed t/41prof_dump.t to work with perl5.9.1.
  Fixed DBD_ATTRIB_DELETE macro thanks to Marco Paskamp.
  Fixed DBI::PurePerl looks_like_number() and $DBI::rows.
  Fixed ref($h)->can("foo") to not croak.

  Changed attributes (NAME, TYPE etc) of non-executed statement
    handle to be undef instead of triggering an error.
  Changed ShowErrorStatement to apply to more $dbh methods.
  Changed DBI_TRACE env var so just does this at load time:
    DBI->trace(split '=', $ENV{DBI_TRACE}, 2);
  Improved "invalid number of parameters" error message.
  Added DBI::common as base class for DBI::db, DBD::st etc.
  Moved methods common to all handles into DBI::common.

  Major tracing enhancement:
  Added $h->parse_trace_flags("foo|SQL|7") to map a group of
    trace flags into the corresponding trace flag bits.
  Added automatic calling of parse_trace_flags() if
    setting the trace level to a non-numeric value:
    $h->{TraceLevel}="foo|SQL|7"; $h->trace("foo|SQL|7");
    DBI->connect("dbi:Driver(TraceLevel=SQL|foo):...", ...);
    Currently no trace flags have been defined.
  Added to, and reworked, the trace documentation.
  Added dbivport.h for driver authors to use.

  Major driver additions that Jeff Zucker and I have been working on:
  Added DBI::SQL::Nano a 'smaller than micro' SQL parser
    with an SQL::Statement compatible API. If SQL::Statement
    is installed then DBI::SQL::Nano becomes an empty subclass
    of SQL::Statement, unless the DBI_SQL_NANO env var is true.
  Added DBD::File, modified to use DBI::SQL::Nano.
  Added DBD::DBM, an SQL interface to DBM files using DBD::File.
  Documentation changes:
  Corrected typos in docs thanks to Steffen Goeldner.
  Corrected execute_for_fetch example thanks to Dean Arnold.

Changes in DBI 1.41 (svn rev 130), 22nd February 2004

  Fixed execute_for_array() so tuple_status parameter is optional
    as per docs, thanks to Ed Avis.
  Fixed execute_for_array() docs to say that it returns undef if
    any of the execute() calls fail.
  Fixed take_imp_data() test on m68k reported by Christian Hammers.
  Fixed write_typeinfo_pm inconsistencies in DBI::DBD::Metadata
    thanks to Andy Hassall.
  Fixed $h->{TraceLevel} to not return DBI->trace trace level
    which it used to if DBI->trace trace level was higher.

  Changed set_err() to append to errstr, with a leading "\n" if it's
    not empty, so that multiple error/warning messages are recorded.
  Changed trace to limit elements dumped when an array reference is
    returned from a method to the max(40, $DBI::neat_maxlen/10)
    so that fetchall_arrayref(), for example, doesn't flood the trace.
  Changed trace level to be a four bit integer (levels 0 thru 15)
    and a set of topic flags (no topics have been assigned yet).
  Changed column_info() to check argument count.
  Extended bind_param() TYPE attribute specification to imply
    standard formating of value, eg SQL_DATE implies 'YYYY-MM-DD'.
  Added way for drivers to indicate 'success with info' or 'warning'
    by setting err to "0" for warning and "" for information.
    Both values are false and so don't trigger RaiseError etc.
    Thanks to Steffen Goeldner for the original idea.
  Added $h->{HandleSetErr} = sub { ... } to be called at the
    point that an error, warn, or info state is recorded.
    The code can alter the err, errstr, and state values
    (e.g., to promote an error to a warning, or the reverse).
  Added $h->{PrintWarn} attribute to enable printing of warnings
    recorded by the driver. Defaults to same value as $^W (perl -w).
  Added $h->{ErrCount} attribute, incremented whenever an error is
    recorded by the driver via set_err().
  Added $h->{Executed} attribute, set if do()/execute() called.
  Added \%attr parameter to foreign_key_info() method.
  Added ref count of inner handle to "DESTROY ignored for outer" msg.
  Added Win32 build config checks to DBI::DBD thanks to Andy Hassall.
  Added bind_col to Driver.xst so drivers can define their own.
  Added TYPE attribute to bind_col and specified the expected
    driver behaviour.

  Major update to signal handling docs thanks to Lincoln Baxter.
  Corrected dbiproxy usage doc thanks to Christian Hammers.
  Corrected type_info_all index hash docs thanks to Steffen Goeldner.
  Corrected type_info COLUMN_SIZE to chars not bytes thanks to Dean Arnold.
  Corrected get_info() docs to include details of DBI::Const::GetInfoType.
  Clarified that $sth->{PRECISION} is OCTET_LENGTH for char types.

Changes in DBI 1.40, 7th January 2004

  Fixed handling of CachedKids when DESTROYing threaded handles.
  Fixed sql_user_name() in DBI::DBD::Metadata (used by write_getinfo_pm)
    to use $dbh->{Username}. Driver authors please update your code.

  Changed connect_cached() when running under Apache::DBI
    to route calls to Apache::DBI::connect().
  Added CLONE() to DBD::Sponge and DBD::ExampleP.
  Added warning when starting a new thread about any loaded driver
    which does not have a CLONE() function.
  Added new prepare_cache($sql, \%attr, 3) option to manage Active handles.
  Added SCALE and NULLABLE support to DBD::Sponge.
  Added missing execute() in fetchall_hashref docs thanks to Iain Truskett.
  Added a CONTRIBUTING section to the docs with notes on creating patches.

Changes in DBI 1.39, 27th November 2003

  Fixed STORE to not clear error during nested DBI call, again/better,
    thanks to Tony Bowden for the report and helpful test case.
  Fixed DBI dispatch to not try to use AUTOLOAD for driver methods unless
    the method has been declared (as methods should be when using AUTOLOAD).
    This fixes a problem when the Attribute::Handlers module is loaded.
  Fixed cwd check code to use $Config{path_sep} thanks to Steve Hay.
  Fixed unqualified croak() calls thanks to Steffen Goeldner.
  Fixed DBD::ExampleP TYPE and PRECISION attributes thanks to Tom Lowery.
  Fixed tracing of methods that only get traced at high trace levels.

  The level 1 trace no longer includes nested method calls so it generally
    just shows the methods the application explicitly calls.
  Added line to trace log (level>=4) when err/errstr is cleared.
  Updated docs for InactiveDestroy and point out where and when the
    trace includes the process id.
  Update DBI::DBD docs thanks to Steffen Goeldner.
  Removed docs saying that the DBI->data_sources method could be
    passed a $dbh. The $dbh->data_sources method should be used instead.
  Added link to 'DBI recipes' thanks to Giuseppe Maxia:
    http://gmax.oltrelinux.com/dbirecipes.html (note that this
    is not an endorsement that the recipies are 'optimal')
  Note: There is a bug in perl 5.8.2 when configured with threads
  and debugging enabled (bug #24463) which causes a DBI test to fail.

Changes in DBI 1.38, 21th August 2003

  NOTE: The DBI now requires perl version 5.6.0 or later.
  (As per notice in DBI 1.33 released 27th February 2003)
  Fixed spurious t/03handles failure on 64bit perls reported by H.Merijn Brand.
  Fixed spurious t/15array failure on some perl versions thanks to Ed Avis.
  Fixed build using dmake on windows thanks to Steffen Goeldner.
  Fixed build on using some shells thanks to Gurusamy Sarathy.
  Fixed ParamValues to only be appended to ShowErrorStatement if not empty.
  Fixed $dbh->{Statement} not being writable by drivers in some cases.
  Fixed occasional undef warnings on connect failures thanks to Ed Avis.
  Fixed small memory leak when using $sth->{NAME..._hash}.
  Fixed 64bit warnings thanks to Marian Jancar.
  Fixed DBD::Proxy::db::DESTROY to not alter $@ thanks to Keith Chapman.
  Fixed Makefile.PL status from WriteMakefile() thanks to Leon Brocard.

  Changed "Can't set ...->{Foo}: unrecognised attribute" from an error to a
    warning when running with DBI::ProxyServer to simplify upgrades.
  Changed execute_array() to no longer require ArrayTupleStatus attribute.
  Changed DBI->available_drivers to not hide DBD::Sponge.
  Updated/moved placeholder docs to a better place thanks to Johan Vromans.
  Changed dbd_db_do4 api in Driver.xst to match dbd_st_execute (return int,
    not bool), relevant only to driver authors.
  Changed neat(), and thus trace(), so strings marked as utf8 are presented
    in double quotes instead of single quotes and are not sanitized.

  Added $dbh->data_sources method.
  Added $dbh->last_insert_id method.
  Added $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status) method.
  Added DBI->installed_versions thanks to Jeff Zucker.
  Added $DBI::Profile::ON_DESTROY_DUMP variable.
  Added docs for DBD::Sponge thanks to Mark Stosberg.

Changes in DBI 1.37, 15th May 2003

  Fixed "Can't get dbh->{Statement}: unrecognised attribute" error in test
    caused by change to perl internals in 5.8.0
  Fixed to build with latest development perl (5.8.1@19525).
  Fixed C code to use all ANSI declarations thanks to Steven Lembark.

Changes in DBI 1.36, 11th May 2003

  Fixed DBI->connect to carp instead of croak on 'old-style' usage.
  Fixed connect(,,, { RootClass => $foo }) to not croak if module not found.
  Fixed code generated by DBI::DBD::Metadata thanks to DARREN@cpan.org (#2270)
  Fixed DBI::PurePerl to not reset $@ during method dispatch.
  Fixed VMS build thanks to Michael Schwern.
  Fixed Proxy disconnect thanks to Steven Hirsch.
  Fixed error in DBI::DBD docs thanks to Andy Hassall.

  Changed t/40profile.t to not require Time::HiRes.
  Changed DBI::ProxyServer to load DBI only on first request, which
    helps threaded server mode, thanks to Bob Showalter.
  Changed execute_array() return value from row count to executed
    tuple count, and now the ArrayTupleStatus attribute is mandatory.
    NOTE: That is an API definition change that may affect your code.
  Changed CompatMode attribute to also disable attribute 'quick FETCH'.
  Changed attribute FETCH to be slightly faster thanks to Stas Bekman.
  Added workaround for perl bug #17575 tied hash nested FETCH
    thanks to Silvio Wanka.
  Added Username and Password attributes to connect(..., \%attr) and so
    also embedded in DSN like "dbi:Driver(Username=user,Password=pass):..."
    Username and Password can't contain ")", ",", or "=" characters.
    The predence is DSN first, then \%attr, then $user & $pass parameters,
    and finally the DBI_USER & DBI_PASS environment variables.
    The Username attribute is stored in the $dbh but the Password is not.
  Added ProxyServer HOWTO configure restrictions docs thanks to Jochen Wiedmann.
  Added MaxRows attribute to selectcol_arrayref prompted by Wojciech Pietron.
  Added dump_handle as a method not just a DBI:: utility function.
  Added on-demand by-row data feed into execute_array() using code ref,
    or statement handle. For example, to insert from a select:
    $insert_sth->execute_array( { ArrayTupleFetch => $select_sth, ... } )
  Added warning to trace log when $h->{foo}=... is ignored due to
    invalid prefix (e.g., not 'private_').

Changes in DBI 1.35, 7th March 2003

  Fixed memory leak in fetchrow_hashref introduced in DBI 1.33.
  Fixed various DBD::Proxy errors introduced in DBI 1.33.
  Fixed to ANSI C in dbd_dr_data_sources thanks to Jonathan Leffler.
  Fixed $h->can($method_name) to return correct code ref.
  Removed DBI::Format from distribution as it's now part of the
    separate DBI::Shell distribution by Tom Lowery.
  Updated DBI::DBD docs with a note about the CLONE method.
  Updated DBI::DBD docs thanks to Jonathan Leffler.
  Updated DBI::DBD::Metadata for perl 5.5.3 thanks to Jonathan Leffler.
  Added note to install_method docs about setup_driver() method.

Changes in DBI 1.34, 28th February 2003

  Fixed DBI::DBD docs to refer to DBI::DBD::Metadata thanks to Jonathan Leffler.
  Fixed dbi_time() compile using BorlandC on Windows thanks to Steffen Goeldner.
  Fixed profile tests to do enough work to measure on Windows.
  Fixed disconnect_all() to not be required by drivers.
  Added $okay = $h->can($method_name) to check if a method exists.
  Added DBD::*::*->install_method($method_name, \%attr) so driver private
    methods can be 'installed' into the DBI dispatcher and no longer
    need to be called using $h->func(..., $method_name).
  Enhanced $dbh->clone() and documentation.
  Enhanced docs to note that dbi_time(), and thus profiling, is limited
    to only millisecond (seconds/1000) resolution on Windows.
  Removed old DBI::Shell from distribution and added Tom Lowery's improved
    version to the Bundle::DBI file.
  Updated minimum version numbers for modules in Bundle::DBI.

Changes in DBI 1.33, 27th February 2003

  NOTE: Future versions of the DBI *will not* support perl 5.6.0 or earlier.
  : Perl 5.6.1 will be the minimum supported version.
  NOTE: The "old-style" connect: DBI->connect($database, $user, $pass, $driver);
  : has been deprecated for several years and will now generate a warning.
  : It will be removed in a later release. Please change any old connect() calls.

  Added $dbh2 = $dbh1->clone to make a new connection to the database
    that is identical to the original one. clone() can be called even after
    the original handle has been disconnected. See the docs for more details.
  Fixed merging of profile data to not sum DBIprof_FIRST_TIME values.
  Fixed unescaping of newlines in DBI::ProfileData thanks to Sam Tregar.
  Fixed Taint bug with fetchrow_hashref with help from Bradley Baetz.
  Fixed $dbh->{Active} for DBD::Proxy, reported by Bob Showalter.
  Fixed STORE to not clear error during nested DBI call,
    thanks to Tony Bowden for the report and helpful test case.
  Fixed DBI::PurePerl error clearing behaviour.
  Fixed dbi_time() and thus DBI::Profile on Windows thanks to Smejkal Petr.
  Fixed problem that meant ShowErrorStatement could show wrong statement,
   thanks to Ron Savage for the report and test case.
  Changed Apache::DBI hook to check for $ENV{MOD_PERL} instead of
    $ENV{GATEWAY_INTERFACE} thanks to Ask Bjoern Hansen.
  No longer tries to dup trace logfp when an interpreter is being cloned.
  Database handles no longer inherit shared $h->err/errstr/state storage
    from their drivers, so each $dbh has it's own $h->err etc. values
    and is no longer affected by calls made on other dbh's.
    Now when a dbh is destroyed it's err/errstr/state values are copied
    up to the driver so checking $DBI::errstr still works as expected.

  Build / portability fixes:
    Fixed t/40profile.t to not use Time::HiRes.
    Fixed t/06attrs.t to not be locale sensitive, reported by Christian Hammers.
    Fixed sgi compiler warnings, reported by Paul Blake.
    Fixed build using make -j4, reported by Jonathan Leffler.
    Fixed build and tests under VMS thanks to Craig A. Berry.
  Documentation changes:
    Documented $high_resolution_time = dbi_time() function.
    Documented that bind_col() can take an atribute hash.
    Clarified documentation for ParamValues attribute hash keys.
    Many good DBI documentation tweaks from Jonathan Leffler,
      including a major update to the DBI::DBD driver author guide.
    Clarified that execute() should itself call finish() if it's
      called on a statement handle that's still active.
    Clarified $sth->{ParamValues}. Driver authors please note.
    Removed "NEW" markers on some methods and attributes and
      added text to each giving the DBI version it was added in,
      if it was added after DBI 1.21 (Feb 2002).

  Changes of note for authors of all drivers:
    Added SQL_DATA_TYPE, SQL_DATETIME_SUB, NUM_PREC_RADIX, and
      INTERVAL_PRECISION fields to docs for type_info_all. There were
      already in type_info(), but type_info_all() didn't specify the
      index values.  Please check and update your type_info_all() code.
    Added DBI::DBD::Metadata module that auto-generates your drivers
      get_info and type_info_all data and code, thanks mainly to
      Jonathan Leffler and Steffen Goeldner. If you've not implemented
      get_info and type_info_all methods and your database has an ODBC
      driver available then this will do all the hard work for you!
    Drivers should no longer pass Err, Errstr, or State to _new_drh
      or _new_dbh functions.
    Please check that you support the slightly modified behaviour of
      $sth->{ParamValues}, e.g., always return hash with keys if possible.

  Changes of note for authors of compiled drivers:
    Added dbd_db_login6 & dbd_st_finish3 prototypes thanks to Jonathan Leffler.
    All dbd_*_*() functions implemented by drivers must have a
      corresponding #define dbd_*_* <driver_prefix>_*_* otherwise
      the driver may not work with a future release of the DBI.
  Changes of note for authors of drivers which use Driver.xst:
    Some new method hooks have been added are are enabled by
      defining corresponding macros:
          $drh->data_sources()      - dbd_dr_data_sources
          $dbh->do()                - dbd_db_do4
    The following methods won't be compiled into the driver unless
      the corresponding macro has been #defined:
          $drh->disconnect_all()    - dbd_discon_all

Changes in DBI 1.32, 1st December 2002

  Fixed to work with 5.005_03 thanks to Tatsuhiko Miyagawa (I've not tested it).
  Reenabled taint tests (accidentally left disabled) spotted by Bradley Baetz.
  Improved docs for FetchHashKeyName attribute thanks to Ian Barwick.
  Fixed core dump if fetchrow_hashref given bad argument (name of attribute
    with a value that wasn't an array reference), spotted by Ian Barwick.
  Fixed some compiler warnings thanks to David Wheeler.
  Updated Steven Hirsch's enhanced proxy work (seems I left out a bit).
  Made t/40profile.t tests more reliable, reported by Randy, who is part of
    the excellent CPAN testers team: http://testers.cpan.org/
    (Please visit, see the valuable work they do and, ideally, join in!)

Changes in DBI 1.31, 29th November 2002

  The fetchall_arrayref method, when called with a $maxrows parameter,
    no longer gives an error if called again after all rows have been
    fetched. This simplifies application logic when fetching in batches.
    Also added batch-fetch while() loop example to the docs.
  The proxy now supports non-lazy (synchronous) prepare, positioned
    updates (for selects containing 'for update'), PlRPC config set
    via attributes, and accurate propagation of errors, all thanks
    to Steven Hirsch (plus a minor fix from Sean McMurray and doc
    tweaks from Michael A Chase).
  The DBI_AUTOPROXY env var can now hold the full dsn of the proxy driver
    plus attributes, like "dbi:Proxy(proxy_foo=>1):host=...".
  Added TaintIn & TaintOut attributes to give finer control over
    tainting thanks to Bradley Baetz.
  The RootClass attribute no longer ignores failure to load a module,
    but also doesn't try to load a module if the class already exists,
    with thanks to James FitzGibbon.
  HandleError attribute works for connect failures thanks to David Wheeler.
  The connect() RaiseError/PrintError message now includes the username.
  Changed "last handle unknown or destroyed" warning to be a trace message.
  Removed undocumented $h->event() method.
  Further enhancements to DBD::PurePerl accuracy.
  The CursorName attribute now defaults to undef and not an error.
  DBI::Profile changes:
    New DBI::ProfileDumper, DBI::ProfileDumper::Apache, and
    DBI::ProfileData modules (to manage the storage and processing
    of profile data), plus dbiprof program for analyzing profile
    data - with many thanks to Sam Tregar.
    Added $DBI::err (etc) tied variable lookup time to profile.
    Added time for DESTROY method into parent handles profile (used to be ignored).
  Documentation changes:
    Documented $dbh = $sth->{Database} attribute.
    Documented $dbh->connected(...) post-connection call when subclassing.
    Updated some minor doc issues thanks to H.Merijn Brand.
    Updated Makefile.PL example in DBI::DBD thanks to KAWAI,Takanori.
    Fixed execute_array() example thanks to Peter van Hardenberg.

  Changes for driver authors, not required but strongly recommended:
    Change DBIS to DBIc_DBISTATE(imp_xxh)   [or imp_dbh, imp_sth etc]
    Change DBILOGFP to DBIc_LOGPIO(imp_xxh) [or imp_dbh, imp_sth etc]
    Any function from which all instances of DBIS and DBILOGFP are
    removed can also have dPERLINTERP removed (a good thing).
    All use of the DBIh_EVENT* macros should be removed.
    Major update to DBI::DBD docs thanks largely to Jonathan Leffler.
    Add these key values: 'Err' => \my $err, 'Errstr' => \my $errstr,
    to the hash passed to DBI::_new_dbh() in your driver source code.
    That will make each $dbh have it's own $h->err and $h->errstr
    values separate from other $dbh belonging to the same driver.
    If you have a ::db or ::st DESTROY methods that do nothing
    you can now remove them - which speeds up handle destruction.

Changes in DBI 1.30, 18th July 2002

  Fixed problems with selectrow_array, selectrow_arrayref, and
    selectall_arrayref introduced in DBI 1.29.
  Fixed FETCHing a handle attribute to not clear $DBI::err etc (broken in 1.29).
  Fixed core dump at trace level 9 or above.
  Fixed compilation with perl 5.6.1 + ithreads (i.e. Windows).
  Changed definition of behaviour of selectrow_array when called in a scalar
    context to match fetchrow_array.
  Corrected selectrow_arrayref docs which showed selectrow_array thanks to Paul DuBois.

Changes in DBI 1.29, 15th July 2002

  NOTE: This release changes the specified behaviour for the
  : fetchrow_array method when called in a scalar context:
  : The DBI spec used to say that it would return the FIRST field.
  : Which field it returns (i.e., the first or the last) is now undefined.
  : This does not affect statements that only select one column, which is
  : usually the case when fetchrow_array is called in a scalar context.
  : FYI, this change was triggered by discovering that the fetchrow_array
  : implementation in Driver.xst (used by most compiled drivers)
  : didn't match the DBI specification. Rather than change the code
  : to match, and risk breaking existing applications, I've changed the
  : specification (that part was always of dubious value anyway).
  NOTE: Future versions of the DBI may not support for perl 5.5 much longer.
  : If you are still using perl 5.005_03 you should be making plans to
  : upgrade to at least perl 5.6.1, or 5.8.0. Perl 5.8.0 is due to be
  : released in the next week or so.  (Although it's a "point 0" release,
  : it is the most throughly tested release ever.)
  Added XS/C implementations of selectrow_array, selectrow_arrayref, and
    selectall_arrayref to Driver.xst. See DBI 1.26 Changes for more info.
  Removed support for the old (fatally flawed) "5005" threading model.
  Added support for new perl 5.8 iThreads thanks to Gerald Richter.
    (Threading support and safety should still be regarded as beta
    quality until further notice. But it's much better than it was.)
  Updated the "Threads and Thread Safety" section of the docs.
  The trace output can be sent to STDOUT instead of STDERR by using
    "STDOUT" as the name of the file, i.e., $h->trace(..., "STDOUT")
  Added pointer to perlreftut, perldsc, perllol, and perlboot manuals
    into the intro section of the docs, suggested by Brian McCain.
  Fixed DBI::Const::GetInfo::* pod docs thanks to Zack Weinberg.
  Some changes to how $dbh method calls are treated by DBI::Profile:
    Meta-data methods now clear $dbh->{Statement} on entry.
    Some $dbh methods are now profiled as if $dbh->{Statement} was empty
    (because thet're unlikely to actually relate to its contents).
  Updated dbiport.h to ppport.h from perl 5.8.0.
  Tested with perl 5.5.3 (vanilla, Solaris), 5.6.1 (vanilla, Solaris), and
    perl 5.8.0 (RC3@17527 with iThreads & Multiplicity on Solaris and FreeBSD).

Changes in DBI 1.28, 14th June 2002

  Added $sth->{ParamValues} to return a hash of the most recent
    values bound to placeholders via bind_param() or execute().
    Individual drivers need to be updated to support it.
  Enhanced ShowErrorStatement to include ParamValues if available:
    "DBD::foo::st execute failed: errstr [for statement ``...'' with params: 1='foo']"
  Further enhancements to DBD::PurePerl accuracy.

Changes in DBI 1.27, 13th June 2002

  Fixed missing column in C implementation of fetchall_arrayref()
    thanks to Philip Molter for the prompt reporting of the problem.

Changes in DBI 1.26, 13th June 2002

  Fixed t/40profile.t to work on Windows thanks to Smejkal Petr.
  Fixed $h->{Profile} to return undef, not error, if not set.
  Fixed DBI->available_drivers in scalar context thanks to Michael Schwern.

  Added C implementations of selectrow_arrayref() and fetchall_arrayref()
    in Driver.xst.  All compiled drivers using Driver.xst will now be
    faster making those calls. Most noticable with fetchall_arrayref for
    many rows or selectrow_arrayref with a fast query. For example, using
    DBD::mysql a selectrow_arrayref for a single row using a primary key
    is ~20% faster, and fetchall_arrayref for 20000 rows is twice as fast!
    Drivers just need to be recompiled and reinstalled to enable it.
    The fetchall_arrayref speed up only applies if $slice parameter is not used.
  Added $max_rows parameter to fetchall_arrayref() to optionally limit
    the number of rows returned. Can now fetch batches of rows.
  Added MaxRows attribute to selectall_arrayref()
    which then passes it to fetchall_arrayref().
  Changed selectrow_array to make use of selectrow_arrayref.
  Trace level 1 now shows first two parameters of all methods
    (used to only for that for some, like prepare,execute,do etc)
  Trace indicator for recursive calls (first char on trace lines)
    now starts at 1 not 2.
  Documented that $h->func() does not trigger RaiseError etc
    so applications must explicitly check for errors.
  DBI::Profile with DBI_PROFILE now shows percentage time inside DBI.
  HandleError docs updated to show that handler can edit error message.
  HandleError subroutine interface is now regarded as stable.

Changes in DBI 1.25, 5th June 2002

  Fixed build problem on Windows and some compiler warnings.
  Fixed $dbh->{Driver} and $sth->{Statement} for driver internals
    These are 'inner' handles as per behaviour prior to DBI 1.16.
  Further minor improvements to DBI::PurePerl accuracy.

Changes in DBI 1.24, 4th June 2002

  Fixed reference loop causing a handle/memory leak
    that was introduced in DBI 1.16.
  Fixed DBI::Format to work with 'filehandles' from IO::Scalar
    and similar modules thanks to report by Jeff Boes.
  Fixed $h->func for DBI::PurePerl thanks to Jeff Zucker.
  Fixed $dbh->{Name} for DBI::PurePerl thanks to Dean Arnold.

  Added DBI method call profiling and benchmarking.
    This is a major new addition to the DBI.
    See $h->{Profile} attribute and DBI::Profile module.
    For a quick trial, set the DBI_PROFILE environment variable and
    run your favourite DBI script. Try it with DBI_PROFILE set to 1,
    then try 2, 4, 8, 10, and -10. Have fun!

  Added execute_array() and bind_param_array() documentation
    with thanks to Dean Arnold.
  Added notes about the DBI having not yet been tested with iThreads
    (testing and patches for SvLOCK etc welcome).
  Removed undocumented Handlers attribute (replaced by HandleError).
  Tested with 5.5.3 and 5.8.0 RC1.

Changes in DBI 1.23, 25th May 2002

  Greatly improved DBI::PurePerl in performance and accuracy.
  Added more detail to DBI::PurePerl docs about what's not supported.
  Fixed undef warnings from t/15array.t and DBD::Sponge.

Changes in DBI 1.22, 22nd May 2002

  Added execute_array() and bind_param_array() with special thanks
    to Dean Arnold. Not yet documented. See t/15array.t for examples.
    All drivers now automatically support these methods.
  Added DBI::PurePerl, a transparent DBI emulation for pure-perl drivers
    with special thanks to Jeff Zucker. Perldoc DBI::PurePerl for details.
  Added DBI::Const::GetInfo* modules thanks to Steffen Goeldner.
  Added write_getinfo_pm utility to DBI::DBD thanks to Steffen Goeldner.
  Added $allow_active==2 mode for prepare_cached() thanks to Stephen Clouse.
  Updated DBI::Format to Revision 11.4 thanks to Tom Lowery.
  Use File::Spec in Makefile.PL (helps VMS etc) thanks to Craig Berry.
  Extend $h->{Warn} to commit/rollback ineffective warning thanks to Jeff Baker.
  Extended t/preparse.t and removed "use Devel::Peek" thanks to Scott Hildreth.
  Only copy Changes to blib/lib/Changes.pm once thanks to Jonathan Leffler.
  Updated internals for modern perls thanks to Jonathan Leffler and Jeff Urlwin.
  Tested with perl 5.7.3 (just using default perl config).

  Documentation changes:
  Added 'Catalog Methods' section to docs thanks to Steffen Goeldner.
  Updated README thanks to Michael Schwern.
  Clarified that driver may choose not to start new transaction until
    next use of $dbh after commit/rollback.
  Clarified docs for finish method.
  Clarified potentials problems with prepare_cached() thanks to Stephen Clouse.

Changes in DBI 1.21, 7th February 2002

  The minimum supported perl version is now 5.005_03.
  Fixed DBD::Proxy support for AutoCommit thanks to Jochen Wiedmann.
  Fixed DBI::ProxyServer bind_param(_inout) handing thanks to Oleg Mechtcheriakov.
  Fixed DBI::ProxyServer fetch loop thanks to nobull@mail.com.
  Fixed install_driver do-the-right-thing with $@ on error. It, and connect(),
    will leave $@ empty on success and holding the error message on error.
    Thanks to Jay Lawrence, Gavin Sherlock and others for the bug report.
  Fixed fetchrow_hashref to assign columns to the hash left-to-right
    so later fields with the same name overwrite earlier ones
    as per DBI < 1.15, thanks to Kay Roepke.
  Changed tables() to use quote_indentifier() if the driver returns a
    true value for $dbh->get_info(29) # SQL_IDENTIFIER_QUOTE_CHAR
  Changed ping() so it no longer triggers RaiseError/PrintError.
  Changed connect() to not call $class->install_driver unless needed.
  Changed DESTROY to catch fatal exceptions and append to $@.
  Added ISO SQL/CLI & ODBCv3 data type definitions thanks to Steffen Goeldner.
  Removed the definition of SQL_BIGINT data type constant as the value is
    inconsistent between standards (ODBC=-5, SQL/CLI=25).
  Added $dbh->column_info(...) thanks to Steffen Goeldner.
  Added $dbh->foreign_key_info(...) thanks to Steffen Goeldner.
  Added $dbh->quote_identifier(...) insipred by Simon Oliver.
  Added $dbh->set_err(...) for DBD authors and DBI subclasses
    (actually been there for a while, now expanded and documented).
  Added $h->{HandleError} = sub { ... } addition and/or alternative
    to RaiseError/PrintError. See the docs for more info.
  Added $h->{TraceLevel} = N attribute to set/get trace level of handle
    thus can set trace level via an (eg externally specified) DSN
    using the embedded attribute syntax:
      $dsn = 'dbi:DB2(PrintError=1,TraceLevel=2):dbname';
    Plus, you can also now do: local($h->{TraceLevel}) = N;
    (but that leaks a little memory in some versions of perl).
  Added some call tree information to trace output if trace level >= 3
    With thanks to Graham Barr for the stack walking code.
  Added experimental undocumented $dbh->preparse(), see t/preparse.t
    With thanks to Scott T. Hildreth for much of the work.
  Added Fowler/Noll/Vo hash type as an option to DBI::hash().

  Documentation changes:
  Added DBI::Changes so now you can "perldoc DBI::Changes", yeah!
  Added selectrow_arrayref & selectrow_hashref docs thanks to Doug Wilson.
  Added 'Standards Reference Information' section to docs to gather
    together all references to relevant on-line standards.
  Added link to poop.sourceforge.net into the docs thanks to Dave Rolsky.
  Added link to hyperlinked BNF for SQL92 thanks to Jeff Zucker.
  Added 'Subclassing the DBI' docs thanks to Stephen Clouse, and
    then changed some of them to reflect the new approach to subclassing.
  Added stronger wording to description of $h->{private_*} attributes.
  Added docs for DBI::hash.

  Driver API changes:
  Now a COPY of the DBI->connect() attributes is passed to the driver
    connect() method, so it can process and delete any elements it wants.
    Deleting elements reduces/avoids the explicit
      $dbh->{$_} = $attr->{$_} foreach keys %$attr;
    that DBI->connect does after the driver connect() method returns.

Changes in DBI 1.20, 24th August 2001

  WARNING: This release contains two changes that may affect your code.
  : Any code using selectall_hashref(), which was added in March 2001, WILL
  : need to be changed. Any code using fetchall_arrayref() with a non-empty
  : hash slice parameter may, in a few rare cases, need to be changed.
  : See the change list below for more information about the changes.
  : See the DBI documentation for a description of current behaviour.
  Fixed memory leak thanks to Toni Andjelkovic.
  Changed fetchall_arrayref({ foo=>1, ...}) specification again (sorry):
    The key names of the returned hashes is identical to the letter case of
    the names in the parameter hash, regardless of the L</FetchHashKeyName>
    attribute. The letter case is ignored for matching.
  Changed fetchall_arrayref([...]) array slice syntax specification to
    clarify that the numbers in the array slice are perl index numbers
    (which start at 0) and not column numbers (which start at 1).
  Added { Columns=>... } and { Slice =>... } attributes to selectall_arrayref()
    which is passed to fetchall_arrayref() so it can fetch hashes now.
  Added a { Columns => [...] } attribute to selectcol_arrayref() so that
    the list it returns can be built from more than one column per row.
    Why? Consider my %hash = @{$dbh->selectcol_arrayref($sql,{ Columns=>[1,2]})}
    to return id-value pairs which can be used directly to build a hash.
  Added $hash_ref = $sth->fetchall_hashref( $key_field )
    which returns a ref to a hash with, typically, one element per row.
    $key_field is the name of the field to get the key for each row from.
    The value of the hash for each row is a hash returned by fetchrow_hashref.
  Changed selectall_hashref to return a hash ref (from fetchall_hashref)
    and not an array of hashes as it has since DBI 1.15 (end March 2001).
    WARNING: THIS CHANGE WILL BREAK ANY CODE USING selectall_hashref()!
    Sorry, but I think this is an important regularization of the API.
    To get previous selectall_hashref() behaviour (an array of hash refs)
    change $ary_ref = $dbh->selectall_hashref( $statement, undef, @bind);
        to $ary_ref = $dbh->selectall_arrayref($statement, { Columns=>{} }, @bind);
  Added NAME_lc_hash, NAME_uc_hash, NAME_hash statement handle attributes.
    which return a ref to a hash of field_name => field_index (0..n-1) pairs.
  Fixed select_hash() example thanks to Doug Wilson.
  Removed (unbundled) DBD::ADO and DBD::Multiplex from the DBI distribution.
    The latest versions of those modules are available from CPAN sites.
  Added $dbh->begin_work. This method causes AutoCommit to be turned
    off just until the next commit() or rollback().
    Driver authors: if the DBIcf_BegunWork flag is set when your commit or
    rollback method is called then please turn AutoCommit on and clear the
    DBIcf_BegunWork flag. If you don't then the DBI will but it'll be much
    less efficient and won't handle error conditions very cleanly.
  Retested on perl 5.4.4, but the DBI won't support 5.4.x much longer.
  Added text to SUPPORT section of the docs:
    For direct DBI and DBD::Oracle support, enhancement, and related work
    I am available for consultancy on standard commercial terms.
  Added text to ACKNOWLEDGEMENTS section of the docs:
    Much of the DBI and DBD::Oracle was developed while I was Technical
    Director (CTO) of the Paul Ingram Group (www.ig.co.uk).  So I'd
    especially like to thank Paul for his generosity and vision in
    supporting this work for many years.

Changes in DBI 1.19, 20th July 2001

  Made fetchall_arrayref({ foo=>1, ...}) be more strict to the specification
    in relation to wanting hash slice keys to be lowercase names.
    WARNING: If you've used fetchall_arrayref({...}) with a hash slice
    that contains keys with uppercase letters then your code will break.
    (As far as I recall the spec has always said don't do that.)
  Fixed $sth->execute() to update $dbh->{Statement} to $sth->{Statement}.
  Added row number to trace output for fetch method calls.
  Trace level 1 no longer shows fetches with row>1 (to reduce output volume).
  Added $h->{FetchHashKeyName} = 'NAME_lc' or 'NAME_uc' to alter
    behaviour of fetchrow_hashref() method. See docs.
  Added type_info quote caching to quote() method thanks to Dean Kopesky.
    Makes using quote() with second data type param much much faster.
  Added type_into_all() caching to type_info(), spotted by Dean Kopesky.
  Added new API definition for table_info() and tables(),
    driver authors please note!
  Added primary_key_info() to DBI API thanks to Steffen Goeldner.
  Added primary_key() to DBI API as simpler interface to primary_key_info().
  Indent and other fixes for DBI::DBD doc thanks to H.Merijn Brand.
  Added prepare_cached() insert_hash() example thanks to Doug Wilson.
  Removed false docs for fetchall_hashref(), use fetchall_arrayref({}).

Changes in DBI 1.18, 4th June 2001

  Fixed that altering ShowErrorStatement also altered AutoCommit!
    Thanks to Jeff Boes for spotting that clanger.
  Fixed DBD::Proxy to handle commit() and rollback(). Long overdue, sorry.
  Fixed incompatibility with perl 5.004 (but no one's using that right? :)
  Fixed connect_cached and prepare_cached to not be affected by the order
    of elements in the attribute hash. Spotted by Mitch Helle-Morrissey.
  Fixed version number of DBI::Shell
    reported by Stuhlpfarrer Gerhard and others.
  Defined and documented table_info() attribute semantics (ODBC compatible)
    thanks to Olga Voronova, who also implemented then in DBD::Oracle.
  Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.

Changes in DBI 1.16, 30th May 2001

  Reimplemented fetchrow_hashref in C, now fetches about 25% faster!
  Changed behaviour if both PrintError and RaiseError are enabled
    to simply do both (in that order, obviously :)
  Slight reduction in DBI handle creation overhead.
  Fixed $dbh->{Driver} & $sth->{Database} to return 'outer' handles.
  Fixed execute param count check to honour RaiseError spotted by Belinda Giardie.
  Fixed build for perl5.6.1 with PERLIO thanks to H.Merijn Brand.
  Fixed client sql restrictions in ProxyServer.pm thanks to Jochen Wiedmann.
  Fixed batch mode command parsing in Shell thanks to Christian Lemburg.
  Fixed typo in selectcol_arrayref docs thanks to Jonathan Leffler.
  Fixed selectrow_hashref to be available to callers thanks to T.J.Mather.
  Fixed core dump if statement handle didn't define Statement attribute.
  Added bind_param_inout docs to DBI::DBD thanks to Jonathan Leffler.
  Added note to data_sources() method docs that some drivers may
    require a connected database handle to be supplied as an attribute.
  Trace of install_driver method now shows path of driver file loaded.
  Changed many '||' to 'or' in the docs thanks to H.Merijn Brand.
  Updated DBD::ADO again (improvements in error handling) from Tom Lowery.
  Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.
  Updated email and web addresses in DBI::FAQ thanks to Michael A Chase.

Changes in DBI 1.15, 28th March 2001

  Added selectrow_arrayref
  Added selectrow_hashref
  Added selectall_hashref thanks to Leon Brocard.
  Added DBI->connect(..., { dbi_connect_method => 'method' })
  Added $dbh->{Statement} aliased to most recent child $sth->{Statement}.
  Added $h->{ShowErrorStatement}=1 to cause the appending of the
    relevant Statement text to the RaiseError/PrintError text.
  Modified type_info to always return hash keys in uppercase and
    to not require uppercase 'DATA_TYPE' key from type_info_all.
    Thanks to Jennifer Tong and Rob Douglas.
  Added \%attr param to tables() and table_info() methods.
  Trace method uses warn() if it can't open the new file.
  Trace shows source line and filename during global destruction.
  Updated packages:
    Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.
    Updated DBD::ADO to much improved version 0.4 from Tom Lowery.
    Updated DBD::Sponge to include $sth->{PRECISION} thanks to Tom Lowery.
    Changed DBD::ExampleP to use lstat() instead of stat().
  Documentation:
    Documented $DBI::lasth (which has been there since day 1).
    Documented SQL_* names.
    Clarified and extended docs for $h->state thanks to Masaaki Hirose.
    Clarified fetchall_arrayref({}) docs (thanks to, er, someone!).
    Clarified type_info_all re lettercase and index values.
    Updated DBI::FAQ to 0.38 thanks to Alligator Descartes.
    Added cute bind_columns example thanks to H.Merijn Brand.
    Extended docs on \%attr arg to data_sources method.
  Makefile.PL
    Removed obscure potential 'rm -rf /' (thanks to Ulrich Pfeifer).
    Removed use of glob and find (thanks to Michael A. Chase).
  Proxy:
    Removed debug messages from DBD::Proxy AUTOLOAD thanks to Brian McCauley.
    Added fix for problem using table_info thanks to Tom Lowery.
    Added better determination of where to put the pid file, and...
    Added KNOWN ISSUES section to DBD::Proxy docs thanks to Jochen Wiedmann.
  Shell:
    Updated DBI::Format to include DBI::Format::String thanks to Tom Lowery.
    Added describe command thanks to Tom Lowery.
    Added columnseparator option thanks to Tom Lowery (I think).
    Added 'raw' format thanks to, er, someone, maybe Tom again.
  Known issues:
    Perl 5.005 and 5.006 both leak memory doing local($handle->{Foo}).
    Perl 5.004 doesn't. The leak is not a DBI or driver bug.

Changes in DBI 1.14, 14th June 2000

  NOTE: This version is the one the DBI book is based on.
  NOTE: This version requires at least Perl 5.004.
  Perl 5.6 ithreads changes with thanks to Doug MacEachern.
  Changed trace output to use PerlIO thanks to Paul Moore.
  Fixed bug in RaiseError/PrintError handling.
    (% chars in the error string could cause a core dump.)
  Fixed Win32 PerlEx IIS concurrency bugs thanks to Murray Nesbitt.
  Major documentation polishing thanks to Linda Mui at O'Reilly.
  Password parameter now shown as **** in trace output.
  Added two fields to type_info and type_info_all.
  Added $dsn to PrintError/RaiseError message from DBI->connect().
  Changed prepare_cached() croak to carp if sth still Active.
  Added prepare_cached() example to the docs.
  Added further DBD::ADO enhancements from Thomas Lowery.

Changes in DBI 1.13, 11th July 1999

  Fixed Win32 PerlEx IIS concurrency bugs thanks to Murray Nesbitt.
  Fixed problems with DBD::ExampleP long_list test mode.
  Added SQL_WCHAR SQL_WVARCHAR SQL_WLONGVARCHAR and SQL_BIT
    to list of known and exportable SQL types.
  Improved data fetch performance of DBD::ADO.
  Added GetTypeInfo to DBD::ADO thanks to Thomas Lowery.
  Actually documented connect_cached thanks to Michael Schwern.
  Fixed user/key/cipher bug in ProxyServer thanks to Joshua Pincus.

Changes in DBI 1.12, 29th June 1999

  Fixed significant DBD::ADO bug (fetch skipped first row).
  Fixed ProxyServer bug handling non-select statements.
  Fixed VMS problem with t/examp.t thanks to Craig Berry.
  Trace only shows calls to trace_msg and _set_fbav at high levels.
  Modified t/examp.t to workaround Cygwin buffering bug.

Changes in DBI 1.11, 17th June 1999

  Fixed bind_columns argument checking to allow a single arg.
  Fixed problems with internal default_user method.
  Fixed broken DBD::ADO.
  Made default $DBI::rows more robust for some obscure cases.

Changes in DBI 1.10, 14th June 1999

  Fixed trace_msg.al error when using Apache.
  Fixed dbd_st_finish enhancement in Driver.xst (internals).
  Enable drivers to define default username and password
    and temporarily disabled warning added in 1.09.
  Thread safety optimised for single thread case.

Changes in DBI 1.09, 9th June 1999

  Added optional minimum trace level parameter to trace_msg().
  Added warning in Makefile.PL that DBI will require 5.004 soon.
  Added $dbh->selectcol_arrayref($statement) method.
  Fixed fetchall_arrayref hash-slice mode undef NAME problem.
  Fixed problem with tainted parameter checking and t/examp.t.
  Fixed problem with thread safety code, including 64 bit machines.
  Thread safety now enabled by default for threaded perls.
  Enhanced code for MULTIPLICITY/PERL_OBJECT from ActiveState.
  Enhanced prepare_cached() method.
  Minor changes to trace levels (less internal info at level 2).
  Trace log now shows "!! ERROR..." before the "<- method" line.
  DBI->connect() now warn's if user / password is undefined and
    DBI_USER / DBI_PASS environment variables are not defined.
  The t/proxy.t test now ignores any /etc/dbiproxy.conf file.
  Added portability fixes for MacOS from Chris Nandor.
  Updated mailing list address from fugue.com to isc.org.

Changes in DBI 1.08, 12th May 1999

  Much improved DBD::ADO driver thanks to Phlip Plumlee and others.
  Connect now allows you to specify attribute settings within the DSN
    E.g., "dbi:Driver(RaiseError=>1,Taint=>1,AutoCommit=>0):dbname"
  The $h->{Taint} attribute now also enables taint checking of
    arguments to almost all DBI methods.
  Improved trace output in various ways.
  Fixed bug where $sth->{NAME_xx} was undef in some situations.
  Fixed code for MULTIPLICITY/PERL_OBJECT thanks to Alex Smishlajev.
  Fixed and documented DBI->connect_cached.
  Workaround for Cygwin32 build problem with help from Jong-Pork Park.
  bind_columns no longer needs undef or hash ref as first parameter.

Changes in DBI 1.07, 6th May 1999

  Trace output now shows contents of array refs returned by DBI.
  Changed names of some result columns from type_info, type_info_all,
    tables and table_info to match ODBC 3.5 / ISO/IEC standards.
  Many fixes for DBD::Proxy and ProxyServer.
  Fixed error reporting in install_driver.
  Major enhancement to DBI::W32ODBC from Patrick Hollins.
  Added $h->{Taint} to taint fetched data if tainting (perl -T).
  Added code for MULTIPLICITY/PERL_OBJECT contributed by ActiveState.
  Added $sth->more_results (undocumented for now).

Changes in DBI 1.06, 6th January 1999

  Fixed Win32 Makefile.PL problem in 1.04 and 1.05.
  Significant DBD::Proxy enhancements and fixes
    including support for bind_param_inout (Jochen and I)
  Added experimental DBI->connect_cached method.
  Added $sth->{NAME_uc} and $sth->{NAME_lc} attributes.
  Enhanced fetchrow_hashref to take an attribute name arg.

Changes in DBI 1.05, 4th January 1999

  Improved DBD::ADO connect (thanks to Phlip Plumlee).
  Improved thread safety (thanks to Jochen Wiedmann).
  [Quick release prompted by truncation of copies on CPAN]

Changes in DBI 1.04, 3rd January 1999

  Fixed error in Driver.xst. DBI build now tests Driver.xst.
  Removed unused variable compiler warnings in Driver.xst.
  DBI::DBD module now tested during DBI build.
  Further clarification in the DBI::DBD driver writers manual.
  Added optional name parameter to $sth->fetchrow_hashref.

Changes in DBI 1.03, 1st January 1999

  Now builds with Perl>=5.005_54 (PERL_POLLUTE in DBIXS.h)
  DBI trace trims path from "at yourfile.pl line nnn".
  Trace level 1 now shows statement passed to prepare.
  Assorted improvements to the DBI manual.
  Assorted improvements to the DBI::DBD driver writers manual.
  Fixed $dbh->quote prototype to include optional $data_type.
  Fixed $dbh->prepare_cached problems.
  $dbh->selectrow_array behaves better in scalar context.
  Added a (very) experimental DBD::ADO driver for Win32 ADO.
  Added experimental thread support (perl Makefile.PL -thread).
  Updated the DBI::FAQ - thanks to Alligator Descartes.
  The following changes were implemented and/or packaged
    by Jochen Wiedmann - thanks Jochen:
  Added a Bundle for CPAN installation of DBI, the DBI proxy
    server and prerequisites (lib/Bundle/DBI.pm).
  DBI->available_drivers uses File::Spec, if available.
    This makes it work on MacOS. (DBI.pm)
  Modified type_info to work with read-only values returned
    by type_info_all. (DBI.pm)
  Added handling of magic values in $sth->execute,
    $sth->bind_param and other methods (Driver.xst)
  Added Perl's CORE directory to the linkers path on Win32,
    required by recent versions of ActiveState Perl.
  Fixed DBD::Sponge to work with empty result sets.
  Complete rewrite of DBI::ProxyServer and DBD::Proxy.

Changes in DBI 1.02, 2nd September 1998

  Fixed DBI::Shell including @ARGV and /current.
  Added basic DBI::Shell test.
  Renamed DBI::Shell /display to /format.

Changes in DBI 1.01, 2nd September 1998

  Many enhancements to Shell (with many contributions from
  Jochen Wiedmann, Tom Lowery and Adam Marks).
  Assorted fixes to DBD::Proxy and DBI::ProxyServer.
  Tidied up trace messages - trace(2) much cleaner now.
  Added $dbh->{RowCacheSize} and $sth->{RowsInCache}.
  Added experimental DBI::Format (mainly for DBI::Shell).
  Fixed fetchall_arrayref($slice_hash).
  DBI->connect now honours PrintError=1 if connect fails.
  Assorted clarifications to the docs.

Changes in DBI 1.00, 14th August 1998

  The DBI is no longer 'alpha' software!
  Added $dbh->tables and $dbh->table_info.
  Documented \%attr arg to data_sources method.
  Added $sth->{TYPE}, $sth->{PRECISION} and $sth->{SCALE}.
  Added $sth->{Statement}.
  DBI::Shell now uses neat_list to print results
  It also escapes "'" chars and converts newlines to spaces.

Changes in DBI 0.95, 10th August 1998

  WARNING: THIS IS AN EXPERIMENTAL RELEASE!
  Fixed 0.94 slip so it will build on pre-5.005 again.
  Added DBI_AUTOPROXY environment variable.
  Array ref returned from fetch/fetchrow_arrayref now readonly.
  Improved connect error reporting by DBD::Proxy.
  All trace/debug messages from DBI now go to trace file.

Changes in DBI 0.94, 9th August 1998

  WARNING: THIS IS AN EXPERIMENTAL RELEASE!
  Added DBD::Shell and dbish interactive DBI shell. Try it!
  Any database attribs can be set via DBI->connect(,,, \%attr).
  Added _get_fbav and _set_fbav methods for Perl driver developers
    (see ExampleP driver for perl usage). Drivers which don't use
    one of these methods (either via XS or Perl) are not compliant.
  DBI trace now shows adds " at yourfile.pl line nnn"!
  PrintError and RaiseError now prepend driver and method name.
  The available_drivers method no longer returns NullP or Sponge.
  Added $dbh->{Name}.
  Added $dbh->quote($value, $data_type).
  Added more hints to install_driver failure message.
  Added DBD::Proxy and DBI::ProxyServer (from Jochen Wiedmann).
  Added $DBI::neat_maxlen to control truncation of trace output.
  Added $dbh->selectall_arrayref and $dbh->selectrow_array methods.
  Added $dbh->tables.
  Added $dbh->type_info and $dbh->type_info_all.
  Added $h->trace_msg($msg) to write to trace log.
  Added @bool = DBI::looks_like_number(@ary).
  Many assorted improvements to the DBI docs.

Changes in DBI 0.93, 13th February 1998

  Fixed DBI::DBD::dbd_postamble bug causing 'Driver.xsi not found' errors.
  Changes to handling of 'magic' values in neatsvpv (used by trace).
  execute (in Driver.xst) stops binding after first bind error.
  This release requires drivers to be rebuilt.

Changes in DBI 0.92, 3rd February 1998

  Fixed per-handle memory leak (with many thanks to Irving Reid).
  Added $dbh->prepare_cached() caching variant of $dbh->prepare.
  Added some attributes:
    $h->{Active}       is the handle 'Active' (vague concept) (boolean)
    $h->{Kids}         e.g. number of sth's associated with a dbh
    $h->{ActiveKids}   number of the above which are 'Active'
    $dbh->{CachedKids} ref to prepare_cached sth cache
  Added support for general-purpose 'private_' attributes.
  Added experimental support for subclassing the DBI: see t/subclass.t
  Added SQL_ALL_TYPES to exported :sql_types.
  Added dbd_dbi_dir() and dbd_dbi_arch_dir() to DBI::DBD module so that
  DBD Makefile.PLs can work with the DBI installed in non-standard locations.
  Fixed 'Undefined value' warning and &sv_no output from neatsvpv/trace.
  Fixed small 'once per interpreter' leak.
  Assorted minor documentation fixes.

Changes in DBI 0.91, 10th December 1997

  NOTE: This fix may break some existing scripts:
  DBI->connect("dbi:...",$user,$pass) was not setting AutoCommit and PrintError!
  DBI->connect(..., { ... }) no longer sets AutoCommit or PrintError twice.
  DBI->connect(..., { RaiseError=>1 }) now croaks if connect fails.
  Fixed $fh parameter of $sth->dump_results;
  Added default statement DESTROY method which carps.
  Added default driver DESTROY method to silence AUTOLOAD/__DIE__/CGI::Carp
  Added more SQL_* types to %EXPORT_TAGS and @EXPORT_OK.
  Assorted documentation updates (mainly clarifications).
  Added workaround for perl's 'sticky lvalue' bug.
  Added better warning for bind_col(umns) where fields==0.
  Fixed to build okay with 5.004_54 with or without USE_THREADS.
  Note that the DBI has not been tested for thread safety yet.

Changes in DBI 0.90, 6th September 1997

  Can once again be built with Perl 5.003.
  The DBI class can be subclassed more easily now.
  InactiveDestroy fixed for drivers using the *.xst template.
  Slightly faster handle creation.
  Changed prototype for dbd_*_*_attrib() to add extra param.
  Note: 0.90, 0.89 and possibly some other recent versions have
  a small memory leak. This will be fixed in the next release.

Changes in DBI 0.89, 25th July 1997

  Minor fix to neatsvpv (mainly used for debug trace) to workaround
  bug in perl where SvPV removes IOK flag from an SV.
  Minor updates to the docs.

Changes in DBI 0.88, 22nd July 1997

  Fixed build for perl5.003 and Win32 with Borland.
  Fixed documentation formatting.
  Fixed DBI_DSN ignored for old-style connect (with explicit driver).
  Fixed AutoCommit in DBD::ExampleP
  Fixed $h->trace.
  The DBI can now export SQL type values: use DBI ':sql_types';
  Modified Driver.xst and renamed DBDI.h to dbd_xsh.h

Changes in DBI 0.87, 18th July 1997

  Fixed minor type clashes.
  Added more docs about placeholders and bind values.

Changes in DBI 0.86, 16th July 1997

  Fixed failed connect causing 'unblessed ref' and other errors.
  Drivers must handle AutoCommit FETCH and STORE else DBI croaks.
  Added $h->{LongReadLen} and $h->{LongTruncOk} attributes for BLOBS.
  Added DBI_USER and DBI_PASS env vars. See connect docs for usage.
  Added DBI->trace() to set global trace level (like per-handle $h->trace).
  PERL_DBI_DEBUG env var renamed DBI_DEBUG (old name still works for now).
  Updated docs, including commit, rollback, AutoCommit and Transactions sections.
  Added bind_param method and execute(@bind_values) to docs.
  Fixed fetchall_arrayref.

  Since the DBIS structure has change the internal version numbers have also
  changed (DBIXS_VERSION == 9 and DBISTATE_VERSION == 9) so drivers will have
  to be recompiled. The test is also now more sensitive and the version
  mismatch error message now more clear about what to do. Old drivers are
  likely to core dump (this time) until recompiled for this DBI. In future
  DBI/DBD version mismatch will always produce a clear error message.
  Note that this DBI release contains and documents many new features
  that won't appear in drivers for some time. Driver writers might like
  to read perldoc DBI::DBD and comment on or apply the information given.

Changes in DBI 0.85, 25th June 1997

  NOTE: New-style connect now defaults to AutoCommit mode unless
  { AutoCommit => 0 } specified in connect attributes. See the docs.
  AutoCommit attribute now defined and tracked by DBI core.
  Drivers should use/honour this and not implement their own.
  Added pod doc changes from Andreas and Jonathan.
  New DBI_DSN env var default for connect method. See docs.
  Documented the func method.
  Fixed "Usage: DBD::_::common::DESTROY" error.
  Fixed bug which set some attributes true when there value was fetched.
  Added new internal DBIc_set() macro for drivers to use.

Changes in DBI 0.84, 20th June 1997

  Added $h->{PrintError} attribute which, if set true, causes all errors to
  trigger a warn().
  New-style DBI->connect call now automatically sets PrintError=1 unless
  { PrintError => 0 } specified in the connect attributes. See the docs.
  The old-style connect with a separate driver parameter is deprecated.
  Fixed fetchrow_hashref.
  Renamed $h->debug to $h->trace() and added a trace filename arg.
  Assorted other minor tidy-ups.

Changes in DBI 0.83, 11th June 1997

  Added driver specification syntax to DBI->connect data_source
  parameter: DBI->connect('dbi:driver:...', $user, $passwd);
  The DBI->data_sources method should return data_source
  names with the appropriate 'dbi:driver:' prefix.
  DBI->connect will warn if \%attr is true but not a hash ref.
  Added the new fetchrow methods:
    @row_ary  = $sth->fetchrow_array;
    $ary_ref  = $sth->fetchrow_arrayref;
    $hash_ref = $sth->fetchrow_hashref;
  The old fetch and fetchrow methods still work.
  Driver implementors should implement the new names for
  fetchrow_array and fetchrow_arrayref ASAP (use the xs ALIAS:
  directive to define aliases for fetch and fetchrow).
  Fixed occasional problems with t/examp.t test.
  Added automatic errstr reporting to the debug trace output.
  Added the DBI FAQ from Alligator Descartes in module form for
  easy reading via "perldoc DBI::FAQ". Needs reformatting.
  Unknown driver specific attribute names no longer croak.
  Fixed problem with internal neatsvpv macro.

Changes in DBI 0.82, 23rd May 1997

  Added $h->{RaiseError} attribute which, if set true, causes all errors to
  trigger a die(). This makes it much easier to implement robust applications
  in terms of higher level eval { ... } blocks and rollbacks.
  Added DBI->data_sources($driver) method for implementation by drivers.
  The quote method now returns the string NULL (without quotes) for undef.
  Added VMS support thanks to Dan Sugalski.
  Added a 'quick start guide' to the README.
  Added neatsvpv function pointer to DBIS structure to make it available for
  use by drivers. A macro defines neatsvpv(sv,len) as (DBIS->neatsvpv(sv,len)).
  Old XS macro SV_YES_NO changes to standard boolSV.
  Since the DBIS structure has change the internal version numbers have also
  changed (DBIXS_VERSION == 8 and DBISTATE_VERSION == 8) so drivers will have
  to be recompiled.

Changes in DBI 0.81, 7th May 1997

  Minor fix to let DBI build using less modern perls.
  Fixed a suprious typo warning.

Changes in DBI 0.80, 6th May 1997

  Builds with no changes on NT using perl5.003_99 (with thanks to Jeffrey Urlwin).
  Automatically supports Apache::DBI (with thanks to Edmund Mergl).
    DBI scripts no longer need to be modified to make use of Apache::DBI.
  Added a ping method and an experimental connect_test_perf method.
  Added a fetchhash and fetch_all methods.
  The func method no longer pre-clears err and errstr.
  Added ChopBlanks attribute (currently defaults to off, that may change).
    Support for the attribute needs to be implemented by individual drivers.
  Reworked tests into standard t/*.t form.
  Added more pod text.  Fixed assorted bugs.

Changes in DBI 0.79, 7th Apr 1997

  Minor release. Tidied up pod text and added some more descriptions
  (especially disconnect). Minor changes to DBI.xs to remove compiler
  warnings.

Changes in DBI 0.78, 28th Mar 1997

  Greatly extended the pod documentation in DBI.pm, including the under
  used bind_columns method. Use 'perldoc DBI' to read after installing.
  Fixed $h->err. Fetching an attribute value no longer resets err.
  Added $h->{InactiveDestroy}, see documentation for details.
  Improved debugging of cached ('quick') attribute fetches.
  errstr will return err code value if there is no string value.
  Added DBI/W32ODBC to the distribution. This is a pure-perl experimental
  DBI emulation layer for Win32::ODBC. Note that it's unsupported, your
  mileage will vary, and bug reports without fixes will probably be ignored.

Changes in DBI 0.77, 21st Feb 1997

  Removed erroneous $h->errstate and $h->errmsg methods from DBI.pm.
  Added $h->err, $h->errstr and $h->state default methods in DBI.xs.
  Updated informal DBI API notes in DBI.pm. Updated README slightly.
  DBIXS.h now correctly installed into INST_ARCHAUTODIR.
  (DBD authors will need to edit their Makefile.PL's to use
  -I$(INSTALLSITEARCH)/auto/DBI -I$(INSTALLSITEARCH)/DBI)

Changes in DBI 0.76, 3rd Feb 1997

  Fixed a compiler type warnings (pedantic IRIX again).

Changes in DBI 0.75, 27th Jan 1997

  Fix problem introduced by a change in Perl5.003_XX.
  Updated README and DBI.pm docs.

Changes in DBI 0.74, 14th Jan 1997

  Dispatch now sets dbi_debug to the level of the current handle
  (this makes tracing/debugging individual handles much easier).
  The '>> DISPATCH' log line now only logged at debug >= 3 (was 2).
  The $csr->NUM_OF_FIELDS attribute can be set if not >0 already.
  You can log to a file using the env var PERL_DBI_DEBUG=/tmp/dbi.log.
  Added a type cast needed by IRIX.
  No longer sets perl_destruct_level unless debug set >= 4.
  Make compatible with PerlIO and sfio.

Changes in DBI 0.73, 10th Oct 1996

  Fixed some compiler type warnings (IRIX).
  Fixed DBI->internal->{DebugLog} = $filename.
  Made debug log file unbuffered.
  Added experimental bind_param_inout method to interface.
  Usage: $dbh->bind_param_inout($param, \$value, $maxlen [, \%attribs ])
  (only currently used by DBD::Oracle at this time.)

Changes in DBI 0.72, 23 Sep 1996

  Using an undefined value as a handle now gives a better
  error message (mainly useful for emulators like Oraperl).
  $dbh->do($sql, @params) now works for binding placeholders.

Changes in DBI 0.71, 10 July 1996

  Removed spurious abort() from invalid handle check.
  Added quote method to DBI interface and added test.

Changes in DBI 0.70, 16 June 1996

  Added extra invalid handle check (dbih_getcom)
  Fixed broken $dbh->quote method.
  Added check for old GCC in Makefile.PL

Changes in DBI 0.69

  Fixed small memory leak.
  Clarified the behaviour of DBI->connect.
  $dbh->do now returns '0E0' instead of 'OK'.
  Fixed "Can't read $DBI::errstr, lost last handle" problem.

Changes in DBI 0.68, 2 Mar 1996

  Changes to suit perl5.002 and site_lib directories.
  Detects old versions ahead of new in @INC.

Changes in DBI 0.67, 15 Feb 1996

  Trivial change to test suite to fix a problem shown up by the
  Perl5.002gamma release Test::Harness.

Changes in DBI 0.66, 29 Jan 1996

  Minor changes to bring the DBI into line with 5.002 mechanisms,
  specifically the xs/pm VERSION checking mechanism.
  No functionality changes. One no-last-handle bug fix (rare problem).
  Requires 5.002 (beta2 or later).

Changes in DBI 0.65, 23 Oct 1995

  Added $DBI::state to hold SQL CLI / ODBC SQLSTATE value.
  SQLSTATE "00000" (success) is returned as "" (false), all else is true.
  If a driver does not explicitly initialise it (via $h->{State} or
  DBIc_STATE(imp_xxh) then $DBI::state will automatically return "" if
  $DBI::err is false otherwise "S1000" (general error).
  As always, this is a new feature and liable to change.

  The is *no longer* a default error handler!
  You can add your own using push(@{$h->{Handlers}}, sub { ... })
  but be aware that this interface may change (or go away).

  The DBI now automatically clears $DBI::err, errstr and state before
  calling most DBI methods. Previously error conditions would persist.
  Added DBIh_CLEAR_ERROR(imp_xxh) macro.
  DBI now EXPORT_OK's some utility functions, neat($value),
  neat_list(@values) and dump_results($sth).
  Slightly enhanced t/min.t minimal test script in an effort to help
  narrow down the few stray core dumps that some porters still report.
  Renamed readblob to blob_read (old name still works but warns).
  Added default blob_copy_to_file method.
  Added $sth = $dbh->tables method. This returns an $sth for a query
  which has these columns: TABLE_CATALOGUE, TABLE_OWNER, TABLE_NAME,
  TABLE_TYPE, REMARKS in that order. The TABLE_CATALOGUE column
  should be ignored for now.

Changes in DBI 0.64, 23 Oct 1995

  Fixed 'disconnect invalidates 1 associated cursor(s)' problem.
  Drivers using DBIc_ACTIVE_on/off() macros should not need any changes
  other than to test for DBIc_ACTIVE_KIDS() instead of DBIc_KIDS().
  Fixed possible core dump in dbih_clearcom during global destruction.

Changes in DBI 0.63, 1 Sep 1995

  Minor update. Fixed uninitialised memory bug in method
  attribute handling and streamlined processing and debugging.
  Revised usage definitions for bind_* methods and readblob.

Changes in DBI 0.62, 26 Aug 1995

  Added method redirection method $h->func(..., $method_name).
  This is now the official way to call private driver methods
  that are not part of the DBI standard.  E.g.:
      @ary = $sth->func('ora_types');
  It can also be used to call existing methods. Has very low cost.

  $sth->bind_col columns now start from 1 (not 0) to match SQL.
  $sth->bind_columns now takes a leading attribute parameter (or undef),
  e.g., $sth->bind_columns($attribs, \$col1 [, \$col2 , ...]);

  Added handy DBD_ATTRIBS_CHECK macro to vet attribs in XS.
  Added handy DBD_ATTRIB_GET_SVP, DBD_ATTRIB_GET_BOOL and
  DBD_ATTRIB_GET_IV macros for handling attributes.
  Fixed STORE for NUM_OF_FIELDS and NUM_OF_PARAMS.
  Added FETCH for NUM_OF_FIELDS and NUM_OF_PARAMS.
  Dispatch no longer bothers to call _untie().
  Faster startup via install_method/_add_dispatch changes.

Changes in DBI 0.61, 22 Aug 1995

  Added $sth->bind_col($column, \$var [, \%attribs ]);

  This method enables perl variable to be directly and automatically
  updated when a row is fetched. It requires no driver support
  (if the driver has been written to use DBIS->get_fbav).
  Currently \%attribs is unused.
  Added $sth->bind_columns(\$var [, \$var , ...]);

  This method is a short-cut for bind_col which binds all the
  columns of a query in one go (with no attributes). It also
  requires no driver support.
  Added $sth->bind_param($parameter, $var [, \%attribs ]);

  This method enables attributes to be specified when values are
  bound to placeholders. It also enables binding to occur away
  from the execute method to improve execute efficiency.
  The DBI does not provide a default implementation of this.
  See the DBD::Oracle module for a detailed example.
  The DBI now provides default implementations of both fetch and
  fetchrow.  Each is written in terms of the other. A driver is
  expected to implement at least one of them.
  More macro and assorted structure changes in DBDXS.h. Sorry!
  The old dbihcom definitions have gone. All fields have macros.
  The imp_xxh_t type is now used within the DBI as well as drivers.
  Drivers must set DBIc_NUM_FIELDS(imp_sth) and DBIc_NUM_PARAMS(imp_sth).
  test.pl includes a trivial test of bind_param and bind_columns.

Changes in DBI 0.60, 17 Aug 1995

  This release has significant code changes but much less
  dramatic than the previous release. The new implementors data
  handling mechanism has matured significantly (don't be put off
  by all the struct typedefs in DBIXS.h, there's just to make it
  easier for drivers while keeping things type-safe).
  The DBI now includes two new methods:
  do            $dbh->do($statement)
  This method prepares, executes and finishes a statement. It is
  designed to be used for executing one-off non-select statements
  where there is no benefit in reusing a prepared statement handle.
  fetch         $array_ref = $sth->fetch;

  This method is the new 'lowest-level' row fetching method. The
  previous @row = $sth->fetchrow method now defaults to calling
  the fetch method and expanding the returned array reference.
  The DBI now provides fallback attribute FETCH and STORE functions
  which drivers should call if they don't recognise an attribute.
  THIS RELEASE IS A GOOD STARTING POINT FOR DRIVER DEVELOPERS!
  Study DBIXS.h from the DBI and Oracle.xs etc from DBD::Oracle.
  There will be further changes in the interface but nothing
  as dramatic as these last two releases! (I hope :-)

Changes in DBI 0.59 15 Aug 1995

  NOTE: THIS IS AN UNSTABLE RELEASE!
  Major reworking of internal data management!
  Performance improvements and memory leaks fixed.
  Added a new NullP (empty) driver and a -m flag
  to test.pl to help check for memory leaks.
  Study DBD::Oracle version 0.21 for more details.
  (Comparing parts of v0.21 with v0.20 may be useful.)

Changes in DBI 0.58 21 June 1995

  Added DBI->internal->{DebugLog} = $filename;
  Reworked internal logging.
  Added $VERSION.
  Made disconnect_all a compulsary method for drivers.

ANCIENT HISTORY

12th Oct 1994: First public release of the DBI module. (for Perl 5.000-beta-3h)

19th Sep 1994: DBperl project renamed to DBI.

29th Sep 1992: DBperl project started.


DBI::Const::GetInfo::ANSI - ISO/IEC SQL/CLI Constants for GetInfo

  • REFERENCES
    • %ReturnTypes
    • %ReturnValues
  • TODO

NAME

DBI::Const::GetInfo::ANSI - ISO/IEC SQL/CLI Constants for GetInfo

SYNOPSIS

  The API for this module is private and subject to change.

DESCRIPTION

Information requested by GetInfo().

See: A.1 C header file SQLCLI.H, Page 316, 317.

The API for this module is private and subject to change.

REFERENCES

  ISO/IEC FCD 9075-3:200x Information technology - Database Languages -
  SQL - Part 3: Call-Level Interface (SQL/CLI)
  SC32 N00744 = WG3:VIE-005 = H2-2002-007
  Date: 2002-01-15

%ReturnTypes

See: Codes and data types for implementation information (Table 28), Page 85, 86.

Mapped to ODBC datatype names.

%ReturnValues

See: A.1 C header file SQLCLI.H, Page 317, 318.

TODO

Corrections, e.g.:

  SQL_TRANSACTION_ISOLATION_OPTION vs. SQL_TRANSACTION_ISOLATION


DBI::Const::GetInfo::ODBC - ODBC Constants for GetInfo

  • REFERENCES
    • %ReturnTypes
    • %ReturnValues
  • TODO

NAME

DBI::Const::GetInfo::ODBC - ODBC Constants for GetInfo

SYNOPSIS

 The API for this module is private and subject to change.

DESCRIPTION

Information requested by GetInfo().

The API for this module is private and subject to change.

REFERENCES

  MDAC SDK 2.6
  ODBC version number (0x0351)
  sql.h
  sqlext.h

%ReturnTypes

See: mk:@MSITStore:X:\dm\cli\mdac\sdk26\Docs\odbc.chm::/htm/odbcsqlgetinfo.htm

  =>     : alias
  => !!! : edited

%ReturnValues

See: sql.h, sqlext.h Edited: SQL_TXN_ISOLATION_OPTION

TODO

  Corrections?
  SQL_NULL_COLLATION: ODBC vs ANSI
  Unique values for $ReturnValues{...}?, e.g. SQL_FILE_USAGE


DBI::Const::GetInfoReturn - Data and functions for describing GetInfo results

NAME

DBI::Const::GetInfoReturn - Data and functions for describing GetInfo results

SYNOPSIS

The interface to this module is undocumented and liable to change.

DESCRIPTION

Data and functions for describing GetInfo results


DBI::Const::GetInfoType - Data describing GetInfo type codes

NAME

DBI::Const::GetInfoType - Data describing GetInfo type codes

SYNOPSIS

  use DBI::Const::GetInfoType;

DESCRIPTION

Imports a %GetInfoType hash which maps names for GetInfo Type Codes into their corresponding numeric values. For example:

  $database_version = $dbh->get_info( $GetInfoType{SQL_DBMS_VER} );

The interface to this module is new and nothing beyond what is written here is guaranteed.


DBI::DBD - Perl DBI Database Driver Writer's Guide

    • Version and volatility
  • DESCRIPTION
  • CREATING A NEW DRIVER
    • URLs and mailing lists
    • The Cheetah book
    • Locating drivers
    • Registering a new driver
    • Two styles of database driver
    • What code will you write?
      • Files common to pure Perl and C/XS drivers
      • Extra files needed by C/XS drivers
    • Requirements on a driver and driver writer
  • CREATING A PURE PERL DRIVER
    • Pure Perl version of Makefile.PL
    • README
    • MANIFEST
    • lib/Bundle/DBD/Driver.pm
    • lib/DBD/Driver/Summary.pm
    • Pure Perl version of Driver.pm
      • The DBD::Driver package
        • The header
        • The driver constructor
        • Using install_method() to expose driver-private methods
        • The CLONE special subroutine
      • The DBD::Driver::dr package
        • The database handle constructor
        • The data_sources() method
        • The disconnect_all() method
        • Other driver handle methods
        • Error handling
      • The DBD::Driver::db package
        • The statement handle constructor
        • Transaction handling
        • The STORE() and FETCH() methods
        • Other database handle methods
      • The DBD::Driver::st package
        • The execute() and bind_param() methods
        • The execute_array(), execute_for_fetch() and bind_param_array() methods
        • Fetching data
        • The more_results method
        • Statement attributes
        • Other statement methods
    • Tests
  • CREATING A C/XS DRIVER
    • C/XS version of Driver.pm
      • The connect method
      • The disconnect_all method
      • The data_sources method
      • The prepare method
      • The execute method
      • The fetchrow_arrayref method
      • Other methods?
    • Driver.xs
    • Driver.h
    • Implementation header dbdimp.h
    • Implementation source dbdimp.c
      • The dbd_init method
      • The dbd_drv_error method
      • The dbd_dr_data_sources method
      • The dbd_db_login6 method
      • The dbd_db_commit and dbd_db_rollback methods
      • The dbd_db_disconnect method
      • The dbd_db_discon_all method
      • The dbd_db_destroy method
      • The dbd_db_STORE_attrib method
      • The dbd_db_FETCH_attrib method
      • The dbd_st_prepare method
      • The dbd_st_execute method
      • The dbd_st_fetch method
      • The dbd_st_finish3 method
      • The dbd_st_destroy method
      • The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods
      • The dbd_bind_ph method
      • Implementing bind_param_inout support
    • C/XS version of Makefile.PL
    • Methods which do not need to be written
  • METADATA METHODS
    • Using DBI::DBD::Metadata
      • Generating the get_info method
      • Generating the type_info method
    • Writing DBD::Driver::db::get_info
    • Writing DBD::Driver::db::type_info_all
    • Writing DBD::Driver::db::type_info
    • Writing DBD::Driver::db::table_info
    • Writing DBD::Driver::db::column_info
    • Writing DBD::Driver::db::primary_key_info
    • Writing DBD::Driver::db::primary_key
    • Writing DBD::Driver::db::foreign_key_info
    • Writing DBD::Driver::db::tables
    • Writing DBD::Driver::db::quote
    • Writing DBD::Driver::db::quote_identifier
  • WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE
    • Setting emulation perl variables
  • OTHER MISCELLANEOUS INFORMATION
    • The imp_xyz_t types
    • Using DBIc_IMPSET_on
    • Using DBIc_is(), DBIc_has(), DBIc_on() and DBIc_off()
    • Using the get_fbav() method
  • SUBCLASSING DBI DRIVERS
    • Overwriting methods
    • Attribute handling
  • AUTHORS

NAME

DBI::DBD - Perl DBI Database Driver Writer's Guide

SYNOPSIS

  perldoc DBI::DBD

Version and volatility

This document is still a minimal draft which is in need of further work.

The changes will occur both because the DBI specification is changing and hence the requirements on DBD drivers change, and because feedback from people reading this document will suggest improvements to it.

Please read the DBI documentation first and fully, including the DBI FAQ. Then reread the DBI specification again as you're reading this. It'll help.

This document is a patchwork of contributions from various authors. More contributions (preferably as patches) are very welcome.

DESCRIPTION

This document is primarily intended to help people writing new database drivers for the Perl Database Interface (Perl DBI). It may also help others interested in discovering why the internals of a DBD driver are written the way they are.

This is a guide. Few (if any) of the statements in it are completely authoritative under all possible circumstances. This means you will need to use judgement in applying the guidelines in this document. If in any doubt at all, please do contact the dbi-dev mailing list (details given below) where Tim Bunce and other driver authors can help.

CREATING A NEW DRIVER

The first rule for creating a new database driver for the Perl DBI is very simple: DON'T!

There is usually a driver already available for the database you want to use, almost regardless of which database you choose. Very often, the database will provide an ODBC driver interface, so you can often use DBD::ODBC to access the database. This is typically less convenient on a Unix box than on a Microsoft Windows box, but there are numerous options for ODBC driver managers on Unix too, and very often the ODBC driver is provided by the database supplier.

Before deciding that you need to write a driver, do your homework to ensure that you are not wasting your energies.

[As of December 2002, the consensus is that if you need an ODBC driver manager on Unix, then the unixODBC driver (available from http://www.unixodbc.org/) is the way to go.]

The second rule for creating a new database driver for the Perl DBI is also very simple: Don't -- get someone else to do it for you!

Nevertheless, there are occasions when it is necessary to write a new driver, often to use a proprietary language or API to access the database more swiftly, or more comprehensively, than an ODBC driver can. Then you should read this document very carefully, but with a suitably sceptical eye.

If there is something in here that does not make any sense, question it. You might be right that the information is bogus, but don't come to that conclusion too quickly.

URLs and mailing lists

The primary web-site for locating DBI software and information is

  http://dbi.perl.org/

There are two main and one auxilliary mailing lists for people working with DBI. The primary lists are dbi-users@perl.org for general users of DBI and DBD drivers, and dbi-dev@perl.org mainly for DBD driver writers (don't join the dbi-dev list unless you have a good reason). The auxilliary list is dbi-announce@perl.org for announcing new releases of DBI or DBD drivers.

You can join these lists by accessing the web-site http://dbi.perl.org/. The lists are closed so you cannot send email to any of the lists unless you join the list first.

You should also consider monitoring the comp.lang.perl.* newsgroups, especially comp.lang.perl.modules.

The Cheetah book

The definitive book on Perl DBI is the Cheetah book, so called because of the picture on the cover. Its proper title is 'Programming the Perl DBI: Database programming with Perl' by Alligator Descartes and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN 1-56592-699-4. Buy it now if you have not already done so, and read it.

Locating drivers

Before writing a new driver, it is in your interests to find out whether there already is a driver for your database. If there is such a driver, it would be much easier to make use of it than to write your own!

The primary web-site for locating Perl software is http://search.cpan.org/. You should look under the various modules listings for the software you are after. For example:

  http://search.cpan.org/modlist/Database_Interfaces

Follow the DBD:: and DBIx:: links at the top to see those subsets.

See the DBI docs for information on DBI web sites and mailing lists.

Registering a new driver

Before going through any official registration process, you will need to establish that there is no driver already in the works. You'll do that by asking the DBI mailing lists whether there is such a driver available, or whether anybody is working on one.

When you get the go ahead, you will need to establish the name of the driver and a prefix for the driver. Typically, the name is based on the name of the database software it uses, and the prefix is a contraction of that. Hence, DBD::Oracle has the name Oracle and the prefix 'ora_'.

This information will be recorded in the DBI module. Apart from documentation purposes, registration is a prerequisite for installing private methods.

If you are writing a driver which will not be distributed on CPAN, then you should choose a prefix beginning with 'x_', to avoid potential prefix collisions with drivers registered in the future. Thus, if you wrote a non-CPAN distributed driver called DBD::CustomDB, the prefix might be 'x_cdb_'.

This document assumes you are writing a driver called DBD::Driver, and that the prefix 'drv_' is assigned to the driver.

Two styles of database driver

There are two distinct styles of database driver that can be written to work with the Perl DBI.

Your driver can be written in pure Perl, requiring no C compiler. When feasible, this is the best solution, but most databases are not written in such a way that this can be done. Some examples of pure Perl drivers are DBD::File and DBD::CSV.

Alternatively, and most commonly, your driver will need to use some C code to gain access to the database. This will be classified as a C/XS driver.

What code will you write?

There are a number of files that need to be written for either a pure Perl driver or a C/XS driver. There are no extra files needed only by a pure Perl driver, but there are several extra files needed only by a C/XS driver.

Files common to pure Perl and C/XS drivers

Assuming that your driver is called DBD::Driver, these files are:

  • Makefile.PL
  • README
  • MANIFEST
  • Driver.pm
  • lib/Bundle/DBD/Driver.pm
  • lib/DBD/Driver/Summary.pm
  • t/*.t

The first four files are mandatory. Makefile.PL is used to control how the driver is built and installed. The README file tells people who download the file about how to build the module and any prerequisite software that must be installed. The MANIFEST file is used by the standard Perl module distribution mechanism. It lists all the source files that need to be distributed with your module. Driver.pm is what is loaded by the DBI code; it contains the methods peculiar to your driver.

The lib/Bundle/DBD/Driver.pm file allows you to specify other Perl modules on which yours depends in a format that allows someone to type a simple command and ensure that all the pre-requisites are in place as well as building your driver.

The lib/DBD/Driver/Summary.pm file contains (an updated version of) the information that was included - or that would have been included - in the appendices of the Cheetah book as a summary of the abilities of your driver and the associated database.

The files in the t subdirectory are unit tests for your driver. You should write your tests as stringently as possible, while taking into account the diversity of installations that you can encounter:

  • Your tests should not casually modify operational databases.

  • You should never damage existing tables in a database.

  • You should code your tests to use a constrained name space within the database. For example, the tables (and all other named objects) that are created could all begin with 'dbd_drv_'.

  • At the end of a test run, there should be no testing objects left behind in the database.

  • If you create any databases, you should remove them.

  • If your database supports temporary tables that are automatically removed at the end of a session, then exploit them as often as possible.

  • Try to make your tests independent of each other. If you have a test t/t11dowhat.t that depends upon the successful running of t/t10thingamy.t, people cannot run the single test case t/t11dowhat.t. Further, running t/t11dowhat.t twice in a row is likely to fail (at least, if t/t11dowhat.t modifies the database at all) because the database at the start of the second run is not what you saw at the start of the first run.

  • Document in your README file what you do, and what privileges people need to do it.

  • You can, and probably should, sequence your tests by including a test number before an abbreviated version of the test name; the tests are run in the order in which the names are expanded by shell-style globbing.

  • It is in your interests to ensure that your tests work as widely as possible.

Many drivers also install sub-modules DBD::Driver::SubModule for any of a variety of different reasons, such as to support the metadata methods (see the discussion of METADATA METHODS below). Such sub-modules are conventionally stored in the directory lib/DBD/Driver. The module itself would usually be in a file SubModule.pm. All such sub-modules should themselves be version stamped (see the discussions far below).

Extra files needed by C/XS drivers

The software for a C/XS driver will typically contain at least four extra files that are not relevant to a pure Perl driver.

  • Driver.xs
  • Driver.h
  • dbdimp.h
  • dbdimp.c

The Driver.xs file is used to generate C code that Perl can call to gain access to the C functions you write that will, in turn, call down onto your database software.

The Driver.h header is a stylized header that ensures you can access the necessary Perl and DBI macros, types, and function declarations.

The dbdimp.h is used to specify which functions have been implemented by your driver.

The dbdimp.c file is where you write the C code that does the real work of translating between Perl-ish data types and what the database expects to use and return.

There are some (mainly small, but very important) differences between the contents of Makefile.PL and Driver.pm for pure Perl and C/XS drivers, so those files are described both in the section on creating a pure Perl driver and in the section on creating a C/XS driver.

Obviously, you can add extra source code files to the list.

Requirements on a driver and driver writer

To be remotely useful, your driver must be implemented in a format that allows it to be distributed via CPAN, the Comprehensive Perl Archive Network (http://www.cpan.org/ and http://search.cpan.org). Of course, it is easier if you do not have to meet this criterion, but you will not be able to ask for much help if you do not do so, and no-one is likely to want to install your module if they have to learn a new installation mechanism.

CREATING A PURE PERL DRIVER

Writing a pure Perl driver is surprisingly simple. However, there are some problems you should be aware of. The best option is of course picking up an existing driver and carefully modifying one method after the other.

Also look carefully at DBD::AnyData and DBD::Template.

As an example we take a look at the DBD::File driver, a driver for accessing plain files as tables, which is part of the DBD::CSV package.

The minimal set of files we have to implement are Makefile.PL, README, MANIFEST and Driver.pm.

Pure Perl version of Makefile.PL

You typically start with writing Makefile.PL, a Makefile generator. The contents of this file are described in detail in the the ExtUtils::MakeMaker manpage man pages. It is definitely a good idea if you start reading them. At least you should know about the variables CONFIGURE, DEFINED, PM, DIR, EXE_FILES, INC, LIBS, LINKTYPE, NAME, OPTIMIZE, PL_FILES, VERSION, VERSION_FROM, clean, depend, realclean from the the ExtUtils::MakeMaker manpage man page: these are used in almost any Makefile.PL.

Additionally read the section on Overriding MakeMaker Methods and the descriptions of the distcheck, disttest and dist targets: They will definitely be useful for you.

Of special importance for DBI drivers is the postamble method from the the ExtUtils::MM_Unix manpage man page.

For Emacs users, I recommend the libscan method, which removes Emacs backup files (file names which end with a tilde '~') from lists of files.

Now an example, I use the word Driver wherever you should insert your driver's name:

  # -*- perl -*-

  use DBI 1.03;
  use DBI::DBD;
  use ExtUtils::MakeMaker;

  WriteMakefile(
      dbd_edit_mm_attribs( {
          'NAME'         => 'DBD::Driver',
          'VERSION_FROM' => 'Driver.pm',
          'INC'          => $DBI_INC_DIR,
          'dist'         => { 'SUFFIX'   => '.gz',
                              'COMPRESS' => 'gzip -9f' },
          'realclean'    => { FILES => '*.xsi' },
      },
      { create_pp_tests => 1})
  );

  package MY;
  sub postamble { return main::dbd_postamble(@_); }
  sub libscan {
      my ($self, $path) = @_;
      ($path =~ m/\~$/) ? undef : $path;
  }

Note the calls to dbd_edit_mm_attribs() and dbd_postamble().

The second hash reference in the call to dbd_edit_mm_attribs() (containing create_pp_tests()) is optional; you should not use it unless your driver is a pure Perl driver (that is, it does not use C and XS code). Therefore, the call to dbd_edit_mm_attribs() is not relevant for C/XS drivers and may be omitted; simply use the (single) hash reference containing NAME etc as the only argument to WriteMakefile().

Note that the dbd_edit_mm_attribs() code will fail if you do not have a t sub-directory containing at least one test case.

All drivers must use dbd_postamble() or risk running into problems.

Note the specification of VERSION_FROM; the named file (Driver.pm) will be scanned for the first line that looks like an assignment to $VERSION, and the subsequent text will be used to determine the version number. Note the commentary in the ExtUtils::MakeMaker manpage on the subject of correctly formatted version numbers.

If your driver depends upon external software (it usually will), you will need to add code to ensure that your environment is workable before the call to WriteMakefile().

A full-fledged Makefile.PL can be quite large (for example, the files for DBD::Oracle and DBD::Informix are both over 1000 lines long, and the Informix one uses - and creates - auxilliary modules too).

See also the ExtUtils::MakeMaker manpage and the ExtUtils::MM_Unix manpage. Consider using the CPAN::MakeMaker manpage in place of ExtUtils::MakeMaker.

README

The README file should describe what the driver is for, the pre-requisites for the build process, the actual build process, how to report errors, and who to report them to.

Users will find ways of breaking the driver build and test process which you would never even have dreamed to be possible in your worst nightmares. Therefore, you need to write this document defensively, precisely and concisely.

As always, use the README from one of the established drivers as a basis for your own; the version in DBD::Informix is worth a look as it has been quite successful in heading off problems.

  • Note that users will have versions of Perl and DBI that are both older and newer than you expected, but this will seldom cause much trouble. When it does, it will be because you are using features of DBI that are not supported in the version they are using.

  • Note that users will have versions of the database software that are both older and newer than you expected. You will save yourself time in the long run if you can identify the range of versions which have been tested and warn about versions which are not known to be OK.

  • Note that many people trying to install your driver will not be experts in the database software.

  • Note that many people trying to install your driver will not be experts in C or Perl.

MANIFEST

The MANIFEST will be used by the Makefile's dist target to build the distribution tar file that is uploaded to CPAN. It should list every file that you want to include in your distribution, one per line.

lib/Bundle/DBD/Driver.pm

The CPAN module provides an extremely powerful bundle mechanism that allows you to specify pre-requisites for your driver.

The primary pre-requisite is Bundle::DBI; you may want or need to add some more. With the bundle set up correctly, the user can type:

        perl -MCPAN -e 'install Bundle::DBD::Driver'

and Perl will download, compile, test and install all the Perl modules needed to build your driver.

The prerequisite modules are listed in the CONTENTS section, with the official name of the module followed by a dash and an informal name or description.

  • Listing Bundle::DBI as the main pre-requisite simplifies life.

  • Don't forget to list your driver.

  • Note that unless the DBMS is itself a Perl module, you cannot list it as a pre-requisite in this file.

  • You should keep the version of the bundle the same as the version of your driver.

  • You should add configuration management, copyright, and licencing information at the top.

A suitable skeleton for this file is shown below.

  package Bundle::DBD::Driver;

  $VERSION = '0.01';

  1;

  __END__
  =head1 NAME
  Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules
  =head1 SYNOPSIS
  C<perl -MCPAN -e 'install Bundle::DBD::Driver'>
  =head1 CONTENTS
  Bundle::DBI  - Bundle for DBI by TIMB (Tim Bunce)
  DBD::Driver  - DBD::Driver by YOU (Your Name)
  =head1 DESCRIPTION
  This bundle includes all the modules used by the Perl Database
  Interface (DBI) driver for Driver (DBD::Driver), assuming the
  use of DBI version 1.13 or later, created by Tim Bunce.
  If you've not previously used the CPAN module to install any
  bundles, you will be interrogated during its setup phase.
  But when you've done it once, it remembers what you told it.
  You could start by running:
    C<perl -MCPAN -e 'install Bundle::CPAN'>
  =head1 SEE ALSO
  Bundle::DBI
  =head1 AUTHOR
  Your Name E<lt>F<you@yourdomain.com>E<gt>
  =head1 THANKS
  This bundle was created by ripping off Bundle::libnet created by
  Graham Barr E<lt>F<gbarr@ti.com>E<gt>, and radically simplified
  with some information from Jochen Wiedmann E<lt>F<joe@ispsoft.de>E<gt>.
  The template was then included in the DBI::DBD documentation by
  Jonathan Leffler E<lt>F<jleffler@informix.com>E<gt>.
  =cut

lib/DBD/Driver/Summary.pm

There is no substitute for taking the summary file from a driver that was documented in the Perl book (such as DBD::Oracle or DBD::Informix or DBD::ODBC, to name but three), and adapting it to describe the facilities available via DBD::Driver when accessing the Driver database.

Pure Perl version of Driver.pm

The Driver.pm file defines the Perl module DBD::Driver for your driver. It will define a package DBD::Driver along with some version information, some variable definitions, and a function driver() which will have a more or less standard structure.

It will also define three sub-packages of DBD::Driver:

DBD::Driver::dr

with methods connect(), data_sources() and disconnect_all();

DBD::Driver::db

with methods such as prepare();

DBD::Driver::st

with methods such as execute() and fetch().

The Driver.pm file will also contain the documentation specific to DBD::Driver in the format used by perldoc.

In a pure Perl driver, the Driver.pm file is the core of the implementation. You will need to provide all the key methods needed by DBI.

Now let's take a closer look at an excerpt of File.pm as an example. We ignore things that are common to any module (even non-DBI modules) or really specific to the DBD::File package.

The DBD::Driver package

The header

  package DBD::File;

  use strict;
  use vars qw($VERSION $drh);

  $VERSION = "1.23.00"  # Version number of DBD::File

This is where the version number of your driver is specified, and is where Makefile.PL looks for this information. Please ensure that any other modules added with your driver are also version stamped so that CPAN does not get confused.

It is recommended that you use a two-part (1.23) or three-part (1.23.45) version number. Also consider the CPAN system, which gets confused and considers version 1.10 to precede version 1.9, so that using a raw CVS, RCS or SCCS version number is probably not appropriate (despite being very common).

For Subversion you could use:

  $VERSION = sprintf("12.%06d", q$Revision: 12345 $ =~ /(\d+)/o);

(use lots of leading zeros on the second portion so if you move the code to a shared repository like svn.perl.org the much larger revision numbers won't cause a problem, at least not for a few years). For RCS or CVS you can use:

  $VERSION = sprintf "%d.%02d", '$Revision: 11.21 $ ' =~ /(\d+)\.(\d+)/;

which pads out the fractional part with leading zeros so all is well (so long as you don't go past x.99)

  $drh = undef;         # holds driver handle once initialized

This is where the driver handle will be stored, once created. Note that you may assume there is only one handle for your driver.

The driver constructor

The driver() method is the driver handle constructor. Note that the driver() method is in the DBD::Driver package, not in one of the sub-packages DBD::Driver::dr, DBD::Driver::db, or DBD::Driver::db.

  sub driver
  {
      return $drh if $drh;      # already created - return same one
      my ($class, $attr) = @_;

      $class .= "::dr";

      DBD::Driver::db->install_method('drv_example_dbh_method');
      DBD::Driver::st->install_method('drv_example_sth_method');

      # not a 'my' since we use it above to prevent multiple drivers
      $drh = DBI::_new_drh($class, {
              'Name'        => 'File',
              'Version'     => $VERSION,
              'Attribution' => 'DBD::File by Jochen Wiedmann',
          })
          or return undef;

      return $drh;
        }

This is a reasonable example of how DBI implements its handles. There are three kinds: driver handles (typically stored in $drh; from now on called drh or $drh), database handles (from now on called dbh or $dbh) and statement handles (from now on called sth or $sth).

The prototype of DBI::_new_drh() is

  $drh = DBI::_new_drh($class, $public_attrs, $private_attrs);

with the following arguments:

$class

is typically the class for your driver, (for example, "DBD::File::dr"), passed as the first argument to the driver() method.

$public_attrs

is a hash ref to attributes like Name, Version, and Attribution. These are processed and used by DBI. You had better not make any assumptions about them nor should you add private attributes here.

$private_attrs

This is another (optional) hash ref with your private attributes. DBI will store them and otherwise leave them alone.

The DBI::_new_drh() method and the driver() method both return undef for failure (in which case you must look at $DBI::err and $DBI::errstr for the failure information, because you have no driver handle to use).

Using install_method() to expose driver-private methods

    DBD::Foo::db->install_method($method_name, \%attr);

Installs the driver-private method named by $method_name into the DBI method dispatcher so it can be called directly, avoiding the need to use the func() method.

It is called as a static method on the driver class to which the method belongs. The method name must begin with the corresponding registered driver-private prefix. For example, for DBD::Oracle $method_name must being with 'ora_', and for DBD::AnyData it must begin with 'ad_'.

The attributes can be used to provide fine control over how the DBI dispatcher handles the dispatching of the method. However, at this point, it's undocumented and very liable to change. (Volunteers to polish up and document the interface are very welcome to get in touch via dbi-dev@perl.org)

Methods installed using install_method default to the standard error handling behaviour for DBI methods: clearing err and errstr before calling the method, and checking for errors to trigger RaiseError etc. on return. This differs from the default behaviour of func().

Note for driver authors: The DBD::Foo::xx->install_method call won't work until the class-hierarchy has been setup. Normally the DBI looks after that just after the driver is loaded. This means install_method() can't be called at the time the driver is loaded unless the class-hierarchy is set up first. The way to do that is to call the setup_driver() method:

    DBI->setup_driver('DBD::Foo');

before using install_method().

The CLONE special subroutine

Also needed here, in the DBD::Driver package, is a CLONE() method that will be called by perl when an intrepreter is cloned. All your CLONE() method needs to do, currently, is clear the cached $drh so the new interpreter won't start using the cached $drh from the old interpreter:

  sub CLONE {
    undef $drh;
  }

See http://search.cpan.org/dist/perl/pod/perlmod.pod#Making_your_module_threadsafe for details.

The DBD::Driver::dr package

The next lines of code look as follows:

  package DBD::Driver::dr; # ====== DRIVER ======

  $DBD::Driver::dr::imp_data_size = 0;

Note that no @ISA is needed here, or for the other DBD::Driver::* classes, because the DBI takes care of that for you when the driver is loaded.

 *FIX ME* Explain what the imp_data_size is, so that implementors aren't
 practicing cargo-cult programming.

The database handle constructor

The database handle constructor is the driver's (hence the changed namespace) connect() method:

  sub connect
  {
      my ($drh, $dr_dsn, $user, $auth, $attr) = @_;

      # Some database specific verifications, default settings
      # and the like can go here. This should only include
      # syntax checks or similar stuff where it's legal to
      # 'die' in case of errors.
      # For example, many database packages requires specific
      # environment variables to be set; this could be where you
      # validate that they are set, or default them if they are not set.

      my $driver_prefix = "drv_"; # the assigned prefix for this driver

      # Process attributes from the DSN; we assume ODBC syntax
      # here, that is, the DSN looks like var1=val1;...;varN=valN
      foreach my $var ( split /;/, $dr_dsn ) {
          my ($attr_name, $attr_value) = split '=', $var, 2;
          return $drh->set_err(1, "Can't parse DSN part '$var'")
              unless defined $attr_value;

          # add driver prefix to attribute name if it doesn't have it already
          $attr_name = $driver_prefix.$attr_name
              unless $attr_name =~ /^$driver_prefix/o;

          # Store attribute into %$attr, replacing any existing value.
          # The DBI will STORE() these into $dbh after we've connected
          $attr->{$attr_name} = $attr_value;
                }

      # Get the attributes we'll use to connect.
      # We use delete here because these no need to STORE them
      my $db = delete $attr->{drv_database} || delete $attr->{drv_db}
          or return $drh->set_err(1, "No database name given in DSN '$dr_dsn'");
      my $host = delete $attr->{drv_host} || 'localhost';
      my $port = delete $attr->{drv_port} || 123456;

      # Assume you can attach to your database via drv_connect:
      my $connection = drv_connect($db, $host, $port, $user, $auth)
          or return $drh->set_err(1, "Can't connect to $dr_dsn: ...");

      # create a 'blank' dbh (call superclass constructor)
      my ($outer, $dbh) = DBI::_new_dbh($drh, { Name => $dr_dsn });

      $dbh->STORE('Active', 1 );
      $dbh->{drv_connection} = $connection;

      return $outer;
        }

This is mostly the same as in the driver handle constructor above. The arguments are described in the DBI manpage.

The constructor DBI::_new_dbh() is called, returning a database handle. The constructor's prototype is:

  ($outer, $inner) = DBI::_new_dbh($drh, $public_attr, $private_attr);

with similar arguments to those in the driver handle constructor, except that the $class is replaced by $drh. The Name attribute is a standard DBI attribute (see Database Handle Attributes in the DBI manpage).

In scalar context, only the outer handle is returned.

Note the use of the STORE() method for setting the dbh attributes. That's because within the driver code, the handle object you have is the 'inner' handle of a tied hash, not the outer handle that the users of your driver have.

Because you have the inner handle, tie magic doesn't get invoked when you get or set values in the hash. This is often very handy for speed when you want to get or set simple non-special driver-specific attributes.

However, some attribute values, such as those handled by the DBI like PrintError, don't actually exist in the hash and must be read via $h->FETCH($attrib) and set via $h->STORE($attrib, $value). If in any doubt, use these methods.

The data_sources() method

The data_sources() method must populate and return a list of valid data sources, prefixed with the "dbi:Driver" incantation that allows them to be used in the first argument of the DBI->connect() method. An example of this might be scanning the $HOME/.odbcini file on Unix for ODBC data sources (DSNs).

As a trivial example, consider a fixed list of data sources:

  sub data_sources
  {
      my($drh, $attr) = @_;
      my(@list) = ();
      # You need more sophisticated code than this to set @list...
      push @list, "dbi:Driver:abc";
      push @list, "dbi:Driver:def";
      push @list, "dbi:Driver:ghi";
      # End of code to set @list
      return @list;
  }

The disconnect_all() method

If you need to release any resources when the driver is unloaded, you can provide a disconnect_all method.

Other driver handle methods

If you need any other driver handle methods, they can follow here.

Error handling

It is quite likely that something fails in the connect method. With DBD::File for example, you might catch an error when setting the current directory to something not existent by using the (driver-specific) f_dir attribute.

To report an error, you use the set_err() method:

  $h->set_err($err, $errmsg, $state);

This will ensure that the error is recorded correctly and that RaiseError and PrintError etc are handled correctly.

Typically you'll always use the method instance, aka your method's first argument.

As set_err() always returns undef your error handling code can usually be simplified to something like this:

  return $h->set_err($err, $errmsg, $state) if ...;

The DBD::Driver::db package

  package DBD::Driver::db; # ====== DATABASE ======

  $DBD::Driver::db::imp_data_size = 0;

The statement handle constructor

There's nothing much new in the statement handle constructor, which is the prepare() method:

  sub prepare
  {
      my ($dbh, $statement, @attribs) = @_;

      # create a 'blank' sth
      my ($outer, $sth) = DBI::_new_sth($dbh, { Statement => $statement });

      $sth->STORE('NUM_OF_PARAMS', ($statement =~ tr/?//));

      $sth->{drv_params} = [];

      return $outer;
        }

This is still the same -- check the arguments and call the super class constructor DBI::_new_sth(). Again, in scalar context, only the outer handle is returned. The Statement attribute should be cached as shown.

Note the prefix drv_ in the attribute names: it is required that all your private attributes use a lowercase prefix unique to your driver. As mentioned earlier in this document, the DBI contains a registry of known driver prefixes and may one day warn about unknown attributes that don't have a registered prefix.

Note that we parse the statement here in order to set the attribute NUM_OF_PARAMS. The technique illustrated is not very reliable; it can be confused by question marks appearing in quoted strings, delimited identifiers or in SQL comments that are part of the SQL statement. We could set NUM_OF_PARAMS in the execute() method instead because the DBI specification explicitly allows a driver to defer this, but then the user could not call bind_param().

Transaction handling

Pure Perl drivers will rarely support transactions. Thus your commit() and rollback() methods will typically be quite simple:

  sub commit
  {
      my ($dbh) = @_;
      if ($dbh->FETCH('Warn')) {
          warn("Commit ineffective while AutoCommit is on");
      }
      0;
  }

  sub rollback {
      my ($dbh) = @_;
      if ($dbh->FETCH('Warn')) {
          warn("Rollback ineffective while AutoCommit is on");
      }
      0;
  }

Or even simpler, just use the default methods provided by the DBI that do nothing except return undef.

The DBI's default begin_work() method can be used by inheritance.

The STORE() and FETCH() methods

These methods (that we have already used, see above) are called for you, whenever the user does a:

  $dbh->{$attr} = $val;

or, respectively,

  $val = $dbh->{$attr};

See the perltie manpage for details on tied hash refs to understand why these methods are required.

The DBI will handle most attributes for you, in particular attributes like RaiseError or PrintError. All you have to do is handle your driver's private attributes and any attributes, like AutoCommit and ChopBlanks, that the DBI can't handle for you.

A good example might look like this:

  sub STORE
  {
      my ($dbh, $attr, $val) = @_;
      if ($attr eq 'AutoCommit') {
          # AutoCommit is currently the only standard attribute we have
          # to consider.
          if (!$val) { die "Can't disable AutoCommit"; }
          return 1;
      }
      if ($attr =~ m/^drv_/) {
          # Handle only our private attributes here
          # Note that we could trigger arbitrary actions.
          # Ideally we should warn about unknown attributes.
          $dbh->{$attr} = $val; # Yes, we are allowed to do this,
          return 1;             # but only for our private attributes
      }
      # Else pass up to DBI to handle for us
      $dbh->SUPER::STORE($attr, $val);
  }

  sub FETCH
  {
      my ($dbh, $attr) = @_;
      if ($attr eq 'AutoCommit') { return 1; }
      if ($attr =~ m/^drv_/) {
          # Handle only our private attributes here
          # Note that we could trigger arbitrary actions.
          return $dbh->{$attr}; # Yes, we are allowed to do this,
                                # but only for our private attributes
      }
      # Else pass up to DBI to handle
      $dbh->SUPER::FETCH($attr);
  }

The DBI will actually store and fetch driver-specific attributes (with all lowercase names) without warning or error, so there's actually no need to implement driver-specific any code in your FETCH() and STORE() methods unless you need extra logic/checks, beyond getting or setting the value.

Unless your driver documentation indicates otherwise, the return value of the STORE() method is unspecified and the caller shouldn't use that value.

Other database handle methods

As with the driver package, other database handle methods may follow here. In particular you should consider a (possibly empty) disconnect() method and possibly a quote() method if DBI's default isn't correct for you. You may also need the type_info_all() and get_info() methods, as described elsewhere in this document.

Where reasonable use $h->SUPER::foo() to call the DBI's method in some or all cases and just wrap your custom behavior around that.

If you want to use private trace flags you'll probably want to be able to set them by name. To do that you'll need to define a parse_trace_flag() method (note that's "parse_trace_flag", singular, not "parse_trace_flags", plural).

  sub parse_trace_flag {
      my ($h, $name) = @_;
      return 0x01000000 if $name eq 'foo';
      return 0x02000000 if $name eq 'bar';
      return 0x04000000 if $name eq 'baz';
      return 0x08000000 if $name eq 'boo';
      return 0x10000000 if $name eq 'bop';
      return $h->SUPER::parse_trace_flag($name);
  }

All private flag names must be lowercase, and all private flags must be in the top 8 of the 32 bits.

The DBD::Driver::st package

This package follows the same pattern the others do:

  package DBD::Driver::st;

  $DBD::Driver::st::imp_data_size = 0;

The execute() and bind_param() methods

This is perhaps the most difficult method because we have to consider parameter bindings here. In addition to that, there are a number of statement attributes which must be set for inherited DBI methods to function correctly (see Statement attributes below).

We present a simplified implementation by using the drv_params attribute from above:

  sub bind_param
  {
      my ($sth, $pNum, $val, $attr) = @_;
      my $type = (ref $attr) ? $attr->{TYPE} : $attr;
      if ($type) {
          my $dbh = $sth->{Database};
          $val = $dbh->quote($sth, $type);
      }
      my $params = $sth->{drv_params};
      $params->[$pNum-1] = $val;
      1;
  }

  sub execute
  {
      my ($sth, @bind_values) = @_;

      # start of by finishing any previous execution if still active
      $sth->finish if $sth->FETCH('Active');

      my $params = (@bind_values) ?
          \@bind_values : $sth->{drv_params};
      my $numParam = $sth->FETCH('NUM_OF_PARAMS');
      return $sth->set_err(1, "Wrong number of parameters")
          if @$params != $numParam;
      my $statement = $sth->{'Statement'};
      for (my $i = 0;  $i < $numParam;  $i++) {
          $statement =~ s/?/$params->[$i]/; # XXX doesn't deal with quoting etc!
      }
      # Do anything ... we assume that an array ref of rows is
      # created and store it:
      $sth->{'drv_data'} = $data;
      $sth->{'drv_rows'} = @$data; # number of rows
      $sth->STORE('NUM_OF_FIELDS') = $numFields;
      $sth->{Active} = 1;
      @$data || '0E0';
        }

There are a number of things you should note here.

We initialize the NUM_OF_FIELDS and Active attributes here, because they are essential for bind_columns() to work.

We use attribute $sth->{Statement} which we created within prepare(). The attribute $sth->{Database}, which is nothing else than the dbh, was automatically created by DBI.

Finally, note that (as specified in the DBI specification) we return the string '0E0' instead of the number 0, so that the result tests true but equal to zero.

  $sth->execute() or die $sth->errstr;

The execute_array(), execute_for_fetch() and bind_param_array() methods

In general, DBD's only need to implement execute_for_fetch() and bind_param_array. DBI's default execute_array() will invoke the DBD's execute_for_fetch() as needed.

The following sequence describes the interaction between DBI execute_array and a DBD's execute_for_fetch:

  1. App calls $sth->execute_array(\%attrs, @array_of_arrays)

  2. If @array_of_arrays was specified, DBI processes @array_of_arrays by calling DBD's bind_param_array(). Alternately, App may have directly called bind_param_array()

  3. DBD validates and binds each array

  4. DBI retrieves the validated param arrays from DBD's ParamArray attribute

  5. DBI calls DBD's execute_for_fetch($fetch_tuple_sub, \@tuple_status), where &$fetch_tuple_sub is a closure to iterate over the returned ParamArray values, and \@tuple_status is an array to receive the disposition status of each tuple.

  6. DBD iteratively calls &$fetch_tuple_sub to retrieve parameter tuples to be added to its bulk database operation/request.

  7. when DBD reaches the limit of tuples it can handle in a single database operation/request, or the &$fetch_tuple_sub indicates no more tuples by returning undef, the DBD executes the bulk operation, and reports the disposition of each tuple in \@tuple_status.

  8. DBD repeats steps 6 and 7 until all tuples are processed.

E.g., here's the essence of the DBD::Oracle manpage's execute_for_fetch:

       while (1) {
           my @tuple_batch;
           for (my $i = 0; $i < $batch_size; $i++) {
                push @tuple_batch, [ @{$fetch_tuple_sub->() || last} ];
           }
           last unless @tuple_batch;
           my $res = ora_execute_array($sth, \@tuple_batch,
              scalar(@tuple_batch), $tuple_batch_status);
           push @$tuple_status, @$tuple_batch_status;
       }

Note that DBI's default execute_array()/execute_for_fetch() implementation requires the use of positional (i.e., '?') placeholders. Drivers which require named placeholders must either emulate positional placeholders (e.g., see the DBD::Oracle manpage), or must implement their own execute_array()/execute_for_fetch() methods to properly sequence bound parameter arrays.

Fetching data

Only one method needs to be written for fetching data, fetchrow_arrayref(). The other methods, fetchrow_array(), fetchall_arrayref(), etc, as well as the database handle's select* methods are part of DBI, and call fetchrow_arrayref() as necessary.

  sub fetchrow_arrayref
  {
      my ($sth) = @_;
      my $data = $sth->{drv_data};
      my $row = shift @$data;
      if (!$row) {
          $sth->STORE(Active => 0); # mark as no longer active
          return undef;
      }
      if ($sth->FETCH('ChopBlanks')) {
          map { $_ =~ s/\s+$//; } @$row;
      }
      return $sth->_set_fbav($row);
  }
  *fetch = \&fetchrow_arrayref; # required alias for fetchrow_arrayref

Note the use of the method _set_fbav() -- this is required so that bind_col() and bind_columns() work.

If an error occurs which leaves the $sth in a state where remaining rows can't be fetched then Active should be turned off before the method returns.

The rows() method for this driver can be implemented like this:

  sub rows { shift->{drv_rows} }

because it knows in advance how many rows it has fetched. Alternatively you could delete that method and so fallback to the DBI's own method which does the right thing based on the number of calls to _set_fbav().

The more_results method

If your driver doesn't support multiple result sets, then don't even implement this method.

Otherwise, this method needs to get the statement handle ready to fetch results from the next result set, if there is one. Typically you'd start with:

    $sth->finish;

then you should delete all the attributes from the attribute cache that may no longer be relevant for the new result set:

    delete $sth->{$_}
        for qw(NAME TYPE PRECISION SCALE ...);

for drivers written in C use:

    hv_delete((HV*)SvRV(sth), "NAME", 4, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "NULLABLE", 8, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "NUM_OF_FIELDS", 13, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "PRECISION", 9, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "SCALE", 5, G_DISCARD);
    hv_delete((HV*)SvRV(sth), "TYPE", 4, G_DISCARD);

Don't forget to also delete, or update, any driver-private attributes that may not be correct for the next resultset.

The NUM_OF_FIELDS attribute is a special case. It should be set using STORE:

    $sth->STORE(NUM_OF_FIELDS => 0); /* for DBI <= 1.53 */
    $sth->STORE(NUM_OF_FIELDS => $new_value);

for drivers written in C use this incantation:

    /* Adjust NUM_OF_FIELDS - which also adjusts the row buffer size */
    DBIc_NUM_FIELDS(imp_sth) = 0; /* for DBI <= 1.53 */
    DBIc_STATE(imp_xxh)->set_attr_k(sth, sv_2mortal(newSVpvn("NUM_OF_FIELDS",13)), 0,
        sv_2mortal(newSViv(mysql_num_fields(imp_sth->result)))
    );

For DBI versions prior to 1.54 you'll also need to explicitly adjust the number of elements in the row buffer array (DBIc_FIELDS_AV(imp_sth)) to match the new result set. Fill any new values with newSV(0) not &sv_undef. Alternatively you could free DBIc_FIELDS_AV(imp_sth) and set it to null, but that would mean bind_columns() woudn't work across result sets.

Statement attributes

The main difference between dbh and sth attributes is, that you should implement a lot of attributes here that are required by the DBI, such as NAME, NULLABLE, TYPE, etc. See Statement Handle Attributes in the DBI manpage for a complete list.

Pay attention to attributes which are marked as read only, such as NUM_OF_PARAMS. These attributes can only be set the first time a statement is executed. If a statement is prepared, then executed multiple times, warnings may be generated.

You can protect against these warnings, and prevent the recalculation of attributes which might be expensive to calculate (such as the NAME and NAME_* attributes):

    my $storedNumParams = $sth->FETCH('NUM_OF_PARAMS');
    if (!defined $storedNumParams or $storedNumFields < 0) {
        $sth->STORE('NUM_OF_PARAMS') = $numParams;

        # Set other useful attributes that only need to be set once
        # for a statement, like $sth->{NAME} and $sth->{TYPE}
            }

One particularly important attribute to set correctly (mentioned in ATTRIBUTES COMMON TO ALL HANDLES in the DBI manpage is Active. Many DBI methods, including bind_columns(), depend on this attribute.

Besides that the STORE() and FETCH() methods are mainly the same as above for dbh's.

Other statement methods

A trivial finish() method to discard stored data, reset any attributes (such as Active) and do $sth->SUPER::finish().

If you've defined a parse_trace_flag() method in ::db you'll also want it in ::st, so just alias it in:

  *parse_trace_flag = \&DBD::foo:db::parse_trace_flag;

And perhaps some other methods that are not part of the DBI specification, in particular to make metadata available. Remember that they must have names that begin with your drivers registered prefix so they can be installed using install_method().

If DESTROY() is called on a statement handle that's still active ($sth->{Active} is true) then it should effectively call finish().

    sub DESTROY {
        my $sth = shift;
        $sth->finish if $sth->FETCH('Active');
    }

Tests

The test process should conform as closely as possibly to the Perl standard test harness.

In particular, most (all) of the tests should be run in the t sub-directory, and should simply produce an ok when run under make test. For details on how this is done, see the Camel book and the section in Chapter 7, "The Standard Perl Library" on the Test::Harness manpage.

The tests may need to adapt to the type of database which is being used for testing, and to the privileges of the user testing the driver. For example, the DBD::Informix test code has to adapt in a number of places to the type of database to which it is connected as different Informix databases have different capabilities: some of the tests are for databases without transaction logs; others are for databases with a transaction log; some versions of the server have support for blobs, or stored procedures, or user-defined data types, and others do not.

When a complete file of tests must be skipped, you can provide a reason in a pseudo-comment:

    if ($no_transactions_available)
    {
        print "1..0 # Skip: No transactions available\n";
        exit 0;
    }

Consider downloading the DBD::Informix code and look at the code in DBD/Informix/TestHarness.pm which is used throughout the DBD::Informix tests in the t sub-directory.

CREATING A C/XS DRIVER

Creating a new C/XS driver from scratch will always be a daunting task. You can and should greatly simplify your task by taking a good reference driver implementation and modifying that to match the database product for which you are writing a driver.

The de facto reference driver has been the one for DBD::Oracle written by Tim Bunce, who is also the author of the DBI package. The DBD::Oracle module is a good example of a driver implemented around a C-level API.

Nowadays it it seems better to base on DBD::ODBC, another driver maintained by Tim and Jeff Urlwin, because it offers a lot of metadata and seems to become the guideline for the future development. (Also as DBD::Oracle digs deeper into the Oracle 8 OCI interface it'll get even more hairy than it is now.)

The DBD::Informix driver is one driver implemented using embedded SQL instead of a function-based API. DBD::Ingres may also be worth a look.

C/XS version of Driver.pm

A lot of the code in the Driver.pm file is very similar to the code for pure Perl modules - see above. However, there are also some subtle (and not so subtle) differences, including:

  • The variables $DBD::Driver::{dr|db|st}::imp_data_size are not defined here, but in the XS code, because they declare the size of certain C structures.

  • Some methods are typically moved to the XS code, in particular prepare(), execute(), disconnect(), disconnect_all() and the STORE() and FETCH() methods.

  • Other methods are still part of Driver.pm, but have callbacks to the XS code.

  • If the driver-specific parts of the imp_drh_t structure need to be formally initialized (which does not seem to be a common requirement), then you need to add a call to an appropriate XS function in the driver method of DBD::Driver::driver(), and you define the corresponding function in Driver.xs, and you define the C code in dbdimp.c and the prototype in dbdimp.h.

    For example, DBD::Informix has such a requirement, and adds the following call after the call to _new_drh() in Informix.pm:

      DBD::Informix::dr::driver_init($drh);

    and the following code in Informix.xs:

      # Initialize the DBD::Informix driver data structure
  void
  driver_init(drh)
      SV *drh
      CODE:
      ST(0) = dbd_ix_dr_driver_init(drh) ? &sv_yes : &sv_no;

    and the code in dbdimp.h declares:

      extern int dbd_ix_dr_driver_init(SV *drh);

    and the code in dbdimp.ec (equivalent to dbdimp.c) defines:

      /* Formally initialize the DBD::Informix driver structure */
  int
  dbd_ix_dr_driver(SV *drh)
  {
      D_imp_drh(drh);
      imp_drh->n_connections = 0;       /* No active connections */
      imp_drh->current_connection = 0;  /* No current connection */
      imp_drh->multipleconnections = (ESQLC_VERSION >= 600) ? True : False;
      dbd_ix_link_newhead(&imp_drh->head);  /* Empty linked list of connections */
      return 1;
  }

    DBD::Oracle has a similar requirement but gets around it by checking whether the private data part of the driver handle is all zeroed out, rather than add extra functions.

Now let's take a closer look at an excerpt from Oracle.pm (revised heavily to remove idiosyncrasies) as an example, ignoring things that were already discussed for pure Perl drivers.

The connect method

The connect method is the database handle constructor. You could write either of two versions of this method: either one which takes connection attributes (new code) and one which ignores them (old code only).

If you ignore the connection attributes, then you omit all mention of the $auth variable (which is a reference to a hash of attributes), and the XS system manages the differences for you.

  sub connect
  {
      my ($drh, $dbname, $user, $auth, $attr) = @_;

      # Some database specific verifications, default settings
      # and the like following here. This should only include
      # syntax checks or similar stuff where it's legal to
      # 'die' in case of errors.

      my $dbh = DBI::_new_dbh($drh, {
              'Name'   => $dbname,
          })
          or return undef;

      # Call the driver-specific function _login in Driver.xs file which
      # calls the DBMS-specific function(s) to connect to the database,
      # and populate internal handle data.
      DBD::Driver::db::_login($dbh, $dbname, $user, $auth, $attr)
          or return undef;

      $dbh;
        }

This is mostly the same as in the pure Perl case, the exception being the use of the private _login() callback, which is the function that will really connect to the database. It is implemented in Driver.xst (you should not implement it) and calls dbd_db_login6() from dbdimp.c. See below for details.

 *FIX ME* Discuss removing attributes from hash reference as an optimization
 to skip later calls to $dbh->STORE made by DBI->connect.
 *FIX ME* Discuss removing attributes in Perl code.
 *FIX ME* Discuss removing attributes in C code.

The disconnect_all method

 *FIX ME* T.B.S

The data_sources method

If your data_sources() method can be implemented in pure Perl, then do so because it is easier than doing it in XS code (see the section above for pure Perl drivers).

If your data_sources() method must call onto compiled functions, then you will need to define dbd_dr_data_sources in your dbdimp.h file, which will trigger Driver.xst (in DBI v1.33 or greater) to generate the XS code that calls your actual C function (see the discussion below for details) and you do not code anything in Driver.pm to handle it.

The prepare method

The prepare method is the statement handle constructor, and most of it is not new. Like the connect() method, it now has a C callback:

  package DBD::Driver::db; # ====== DATABASE ======
  use strict;

  sub prepare
  {
      my ($dbh, $statement, $attribs) = @_;

      # create a 'blank' sth
      my $sth = DBI::_new_sth($dbh, {
          'Statement' => $statement,
          })
          or return undef;

      # Call the driver-specific function _prepare in Driver.xs file
      # which calls the DBMS-specific function(s) to prepare a statement
      # and populate internal handle data.
      DBD::Driver::st::_prepare($sth, $statement, $attribs)
          or return undef;
      $sth;
        }

The execute method

 *FIX ME* T.B.S

The fetchrow_arrayref method

 *FIX ME* T.B.S

Other methods?

 *FIX ME* T.B.S

Driver.xs

Driver.xs should look something like this:

  #include "Driver.h"

  DBISTATE_DECLARE;

  INCLUDE: Driver.xsi
  MODULE = DBD::Driver    PACKAGE = DBD::Driver::dr
  /* Non-standard drh XS methods following here, if any.       */
  /* If none (the usual case), omit the MODULE line above too. */
  MODULE = DBD::Driver    PACKAGE = DBD::Driver::db
  /* Non-standard dbh XS methods following here, if any.       */
  /* Currently this includes things like _list_tables from     */
  /* DBD::mSQL and DBD::mysql.                                 */
  MODULE = DBD::Driver    PACKAGE = DBD::Driver::st
  /* Non-standard sth XS methods following here, if any.       */
  /* In particular this includes things like _list_fields from */
  /* DBD::mSQL and DBD::mysql for accessing metadata.          */

Note especially the include of Driver.xsi here: DBI inserts stub functions for almost all private methods here which will typically do much work for you.

Wherever you really have to implement something, it will call a private function in dbdimp.c, and this is what you have to implement.

You need to set up an extra routine if your driver needs to export constants of its own, analogous to the SQL types available when you say:

  use DBI qw(:sql_types);

 *FIX ME* T.B.S

Driver.h

Driver.h is very simple and the operational contents should look like this:

  #ifndef DRIVER_H_INCLUDED
  #define DRIVER_H_INCLUDED

  #define NEED_DBIXS_VERSION 93    /* 93 for DBI versions 1.00 to 1.51+ */
  #define PERL_NO_GET_CONTEXT      /* if used require DBI 1.51+ */

  #include <DBIXS.h>      /* installed by the DBI module  */

  #include "dbdimp.h"

  #include "dbivport.h"   /* see below                    */

  #include <dbd_xsh.h>    /* installed by the DBI module  */

  #endif /* DRIVER_H_INCLUDED */

The DBIXS.h header defines most of the interesting information that the writer of a driver needs.

The file dbd_xsh.h header provides prototype declarations for the C functions that you might decide to implement. Note that you should normally only define one of dbd_db_login() and dbd_db_login6() unless you are intent on supporting really old versions of DBI (prior to DBI 1.06) as well as modern versions. The only standard, DBI-mandated functions that you need write are those specified in the dbd_xsh.h header. You might also add extra driver-specific functions in Driver.xs.

The dbivport.h file should be copied from the latest DBI release into your distribution each time you modify your driver. Its job is to allow you to enhance your code to work with the latest DBI API while still allowing your driver to be compiled and used with older versions of the DBI (for example, when the DBIh_SET_ERR_CHAR() macro was added to DBI 1.41, an emulation of it was added to dbivport.h). This makes users happy and your life easier. Always read the notes in dbivport.h to check for any limitations in the emulation that you should be aware of.

With DBI v1.51 or better I recommend that the driver defines PERL_NO_GET_CONTEXT before DBIXS.h is included. This can significantly improve efficiency when running under a thread enabled perl. (Remember that the standard perl in most Linux distributions is built with threads enabled. So is ActiveState perl for Windows, and perl built for Apache mod_perl2.) If you do this there are some things to keep in mind:

  • If PERL_NO_GET_CONTEXT is defined, then every function that calls the Perl API will need to start out with a dTHX; declaration.

  • You'll know which functions need this, because the C compiler will complain that the undeclared identifier my_perl is used if and only if the perl you are using to develop and test your driver has threads enabled.

  • If you don't remember to test with a thread-enabled perl before making a release it's likely that you'll get failure reports from users who are.

  • For driver private functions it is possible to gain even more efficiency by replacing dTHX; with pTHX_ prepended to the parameter list and then aTHX_ prepended to the argument list where the function is called.

See How multiple interpreters and concurrency are supported in the perlguts manpage for additional information about PERL_NO_GET_CONTEXT.

Implementation header dbdimp.h

This header file has two jobs:

First it defines data structures for your private part of the handles.

Second it defines macros that rename the generic names like dbd_db_login() to database specific names like ora_db_login(). This avoids name clashes and enables use of different drivers when you work with a statically linked perl.

It also will have the important task of disabling XS methods that you don't want to implement.

Finally, the macros will also be used to select alternate implementations of some functions. For example, the dbd_db_login() function is not passed the attribute hash.

Since DBI v1.06, if a dbd_db_login6() macro is defined (for a function with 6 arguments), it will be used instead with the attribute hash passed as the sixth argument.

People used to just pick Oracle's dbdimp.c and use the same names, structures and types. I strongly recommend against that. At first glance this saves time, but your implementation will be less readable. It was just hell when I had to separate DBI specific parts, Oracle specific parts, mSQL specific parts and mysql specific parts in DBD::mysql's dbdimp.h and dbdimp.c. (DBD::mysql was a port of DBD::mSQL which was based on DBD::Oracle.) [Seconded, based on the experience taking DBD::Informix apart, even though the version inherited in 1996 was only based on DBD::Oracle.]

This part of the driver is your exclusive part. Rewrite it from scratch, so it will be clean and short: in other words, a better piece of code. (Of course keep an eye on other people's work.)

  struct imp_drh_st {
      dbih_drc_t com;           /* MUST be first element in structure   */
      /* Insert your driver handle attributes here */
  };

  struct imp_dbh_st {
      dbih_dbc_t com;           /* MUST be first element in structure   */
      /* Insert your database handle attributes here */
  };

  struct imp_sth_st {
      dbih_stc_t com;           /* MUST be first element in structure   */
      /* Insert your statement handle attributes here */
  };

  /*  Rename functions for avoiding name clashes; prototypes are  */
  /*  in dbd_xst.h                                                */
  #define dbd_init         drv_dr_init
  #define dbd_db_login6    drv_db_login
  #define dbd_db_do        drv_db_do
  ... many more here ...

These structures implement your private part of the handles.

You have to use the name imp_dbh_{dr|db|st} and the first field must be of type dbih_drc_t|_dbc_t|_stc_t and must be called com.

You should never access these fields directly, except by using the DBIc_xxx() macros below.

Implementation source dbdimp.c

Conventionally, dbdimp.c is the main implementation file (but DBD::Informix calls the file dbdimp.ec). This section includes a short note on each function that is used in the Driver.xsi template and thus has to be implemented.

Of course, you will probably also need to implement other support functions, which should usually be file static if they are placed in dbdimp.c. If they are placed in other files, you need to list those files in Makefile.PL (and MANIFEST) to handle them correctly.

It is wise to adhere to a namespace convention for your functions to avoid conflicts. For example, for a driver with prefix drv_, you might call externally visible functions dbd_drv_xxxx. You should also avoid non-constant global variables as much as possible to improve the support for threading.

Since Perl requires support for function prototypes (ANSI or ISO or Standard C), you should write your code using function prototypes too.

It is possible to use either the unmapped names such as dbd_init() or the mapped names such as dbd_ix_dr_init() in the dbdimp.c file. DBD::Informix uses the mapped names which makes it easier to identify where to look for linkage problems at runtime (which will report errors using the mapped names).

Most other drivers, and in particular DBD::Oracle, use the unmapped names in the source code which makes it a little easier to compare code between drivers and eases discussions on the dbi-dev mailing list. The majority of the code fragments here will use the unmapped names.

Ultimately, you should provide implementations for most fo the functions listed in the dbd_xsh.h header. The exceptions are optional functions (such as dbd_st_rows()) and those functions with alternative signatures, such as dbd_db_login6() and dbd_db_login(). Then you should only implement one of the alternatives, and generally the newer one of the alternatives.

The dbd_init method

  #include "Driver.h"

  DBISTATE_DECLARE;

  void dbd_init(dbistate_t* dbistate)
  {
      DBISTATE_INIT;  /*  Initialize the DBI macros  */
  }

The dbd_init() function will be called when your driver is first loaded; the bootstrap command in DBD::Driver::dr::driver() triggers this, and the call is generated in the BOOT section of Driver.xst. These statements are needed to allow your driver to use the DBI macros. They will include your private header file dbdimp.h in turn. Note that DBISTATE_INIT requires the name of the argument to dbd_init() to be called dbistate().

The dbd_drv_error method

You need a function to record errors so DBI can access them properly. You can call it whatever you like, but we'll call it dbd_drv_error() here.

The argument list depends on your database software; different systems provide different ways to get at error information.

  static void dbd_drv_error(SV *h, int rc, const char *what)
  {

Note that h is a generic handle, may it be a driver handle, a database or a statement handle.

      D_imp_xxh(h);

This macro will declare and initialize a variable imp_xxh with a pointer to your private handle pointer. You may cast this to to imp_drh_t, imp_dbh_t or imp_sth_t.

To record the error correctly, equivalent to the set_err() method, use one of the DBIh_SET_ERR_CHAR(...) or DBIh_SET_ERR_SV(...) macros, which were added in DBI 1.41:

  DBIh_SET_ERR_SV(h, imp_xxh, err, errstr, state, method);
  DBIh_SET_ERR_CHAR(h, imp_xxh, err_c, err_i, errstr, state, method);

For DBIh_SET_ERR_SV the err, errstr, state, and method parameters are SV*.

For DBIh_SET_ERR_CHAR the err_c, errstr, state, method parameters are char*.

The err_i parameter is an IV that's used instead of err_c if err_c is Null.

The method parameter can be ignored.

The DBIh_SET_ERR_CHAR macro is usually the simplest to use when you just have an integer error code and an error message string:

  DBIh_SET_ERR_CHAR(h, imp_xxh, Nullch, rc, what, Nullch, Nullch);

As you can see, any parameters that aren't relevant to you can be Null.

To make drivers compatible with DBI < 1.41 you should be using dbivport.h as described in Driver.h above.

The (obsolete) macros such as DBIh_EVENT2 should be removed from drivers.

The names dbis and DBIS, which were used in previous versions of this document, should be replaced with the DBIc_STATE(imp_xxh) macro.

The name DBILOGFP, which was also used in previous versions of this document, should be replaced by DBIc_LOGPIO(imp_xxh).

Your code should not call the C <stdio.h> I/O functions; you should use PerlIO_printf() as shown:

      if (DBIc_TRACE_LEVEL(imp_xxh) >= 2)
          PerlIO_printf(DBIc_LOGPIO(imp_xxh), "foobar %s: %s\n",
              foo, neatsvpv(errstr,0));

That's the first time we see how tracing works within a DBI driver. Make use of this as often as you can, but don't output anything at a trace level less than 3. Levels 1 and 2 are reserved for the DBI.

You can define up to 8 private trace flags using the top 8 bits of DBIc_TRACE_FLAGS(imp), that is: 0xFF000000. See the parse_trace_flag() method elsewhere in this document.

The dbd_dr_data_sources method

This method is optional; the support for it was added in DBI v1.33.

As noted in the discussion of Driver.pm, if the data sources can be determined by pure Perl code, do it that way. If, as in DBD::Informix, the information is obtained by a C function call, then you need to define a function that matches the prototype:

  extern AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attrs);

An outline implementation for DBD::Informix follows, assuming that the sqgetdbs() function call shown will return up to 100 databases names, with the pointers to each name in the array dbsname and the name strings themselves being stores in dbsarea.

  AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attr)
  {
      int ndbs;
      int i;
      char *dbsname[100];
      char  dbsarea[10000];
      AV *av = Nullav;

      if (sqgetdbs(&ndbs, dbsname, 100, dbsarea, sizeof(dbsarea)) == 0)
      {
          av = NewAV();
          av_extend(av, (I32)ndbs);
          sv_2mortal((SV *)av);
          for (i = 0; i < ndbs; i++)
            av_store(av, i, newSVpvf("dbi:Informix:%s", dbsname[i]));
      }
      return(av);
        }

The actual DBD::Informix implementation has a number of extra lines of code, logs function entry and exit, reports the error from sqgetdbs(), and uses #define'd constants for the array sizes.

The dbd_db_login6 method

  int dbd_db_login6(SV* dbh, imp_dbh_t* imp_dbh, char* dbname,
                   char* user, char* auth, SV *attr);

This function will really connect to the database. The argument dbh is the database handle. imp_dbh is the pointer to the handles private data, as is imp_xxx in dbd_drv_error() above. The arguments dbname, user, auth and attr correspond to the arguments of the driver handle's connect() method.

You will quite often use database specific attributes here, that are specified in the DSN. I recommend you parse the DSN (using Perl) within the connect() method and pass the segments of the DSN via the attributes parameter through _login() to dbd_db_login6().

Here's how you fetch them; as an example we use hostname attribute, which can be up to 12 characters long excluding null terminator:

  SV** svp;
  STRLEN len;
  char* hostname;

  if ( (svp = DBD_ATTRIB_GET_SVP(attr, "drv_hostname", 12)) && SvTRUE(*svp)) {
      hostname = SvPV(*svp, len);
      DBD__ATTRIB_DELETE(attr, "drv_hostname", 12); /* avoid later STORE */
  } else {
      hostname = "localhost";
  }

Note that you can also obtain standard attributes such as AutoCommit and ChopBlanks from the attributes parameter, using DBD_ATTRIB_GET_IV for integer attributes.

If, for example, your database does not support transactions but AutoCommit is set off (requesting transaction support), then you can emulate a 'failure to connect'.

Now you should really connect to the database. In general, if the connection fails, it is best to ensure that all allocated resources are released so that the handle does not need to be destroyed separately. If you are successful (and possibly even if you fail but you have allocated some resources), you should use the following macros:

  DBIc_IMPSET_on(imp_dbh);

This indicates that the driver (implementor) has allocated resources in the imp_dbh structure and that the implementors private dbd_db_destroy() function should be called when the handle is destroyed.

  DBIc_ACTIVE_on(imp_dbh);

This indicates that the handle has an active connection to the server and that the dbd_db_disconnect() function should be called before the handle is destroyed.

Note that if you do need to fail, you should report errors via the drh or imp_drh rather than via dbh or imp_dbh because imp_dbh will be destroyed by the failure, so errors recorded in that handle will not be visible to DBI, and hence not the user either.

Note too, that the function is passed dbh and imp_dbh, and there is a macro D_imp_drh_from_dbh which can recover the imp_drh from the imp_dbh. However, there is no DBI macro to provide you with the drh given either the imp_dbh or the dbh or the imp_drh (and there's no way to recover the dbh given just the imp_dbh).

This suggests that, despite the above notes about dbd_drv_error() taking an SV *, it may be better to have two error routines, one taking imp_dbh and one taking imp_drh instead. With care, you can factor most of the formatting code out so that these are small routines calling a common error formatter. See the code in DBD::Informix 1.05.00 for more information.

The dbd_db_login6() function should return TRUE for success, FALSE otherwise.

Drivers implemented long ago may define the five-argument function dbd_db_login() instead of dbd_db_login6(). The missing argument is the attributes. There are ways to work around the missing attributes, but they are ungainly; it is much better to use the 6-argument form.

The dbd_db_commit and dbd_db_rollback methods

  int dbd_db_commit(SV *dbh, imp_dbh_t *imp_dbh);
  int dbd_db_rollback(SV* dbh, imp_dbh_t* imp_dbh);

These are used for commit and rollback. They should return TRUE for success, FALSE for error.

The arguments dbh and imp_dbh are the same as for dbd_db_login6() above; I will omit describing them in what follows, as they appear always.

These functions should return TRUE for success, FALSE otherwise.

The dbd_db_disconnect method

This is your private part of the disconnect() method. Any dbh with the ACTIVE flag on must be disconnected. (Note that you have to set it in dbd_db_connect() above.)

  int dbd_db_disconnect(SV* dbh, imp_dbh_t* imp_dbh);

The database handle will return TRUE for success, FALSE otherwise. In any case it should do a:

  DBIc_ACTIVE_off(imp_dbh);

before returning so DBI knows that dbd_db_disconnect() was executed.

Note that there's nothing to stop a dbh being disconnected while it still have active children. If your database API reacts badly to trying to use an sth in this situation then you'll need to add code like this to all sth methods:

  if (!DBIc_ACTIVE(DBIc_PARENT_COM(imp_sth)))
    return 0;

Alternatively, you can add code to your driver to keep explicit track of the statement handles that exist for each database handle and arrange to destroy those handles before disconnecting from the database. There is code to do this in DBD::Informix. Similar comments apply to the driver handle keeping track of all the database handles.

Note that the code which destroys the subordinate handles should only release the associated database resources and mark the handles inactive; it does not attempt to free the actual handle structures.

This function should return TRUE for success, FALSE otherwise, but it is not clear what anything can do about a failure.

The dbd_db_discon_all method

  int dbd_discon_all (SV *drh, imp_drh_t *imp_drh);

This function may be called at shutdown time. It should make best-efforts to disconnect all database handles - if possible. Some databases don't support that, in which case you can do nothing but return 'success'.

This function should return TRUE for success, FALSE otherwise, but it is not clear what anything can do about a failure.

The dbd_db_destroy method

This is your private part of the database handle destructor. Any dbh with the IMPSET flag on must be destroyed, so that you can safely free resources. (Note that you have to set it in dbd_db_connect() above.)

  void dbd_db_destroy(SV* dbh, imp_dbh_t* imp_dbh)
  {
      DBIc_IMPSET_off(imp_dbh);
  }

The DBI Driver.xst code will have called dbd_db_disconnect() for you, if the handle is still 'active', before calling dbd_db_destroy().

Before returning the function must switch IMPSET to off, so DBI knows that the destructor was called.

A DBI handle doesn't keep references to its children. But children do keep references to their parents. So a database handle won't be DESTROY'd until all its children have been DESTROY'd.

The dbd_db_STORE_attrib method

This function handles

  $dbh->{$key} = $value;

Its prototype is:

  int dbd_db_STORE_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv,
                          SV* valuesv);

You do not handle all attributes; on the contrary, you should not handle DBI attributes here: leave this to DBI. (There are two exceptions, AutoCommit and ChopBlanks, which you should care about.)

The return value is TRUE if you have handled the attribute or FALSE otherwise. If you are handling an attribute and something fails, you should call dbd_drv_error(), so DBI can raise exceptions, if desired. If dbd_drv_error() returns, however, you have a problem: the user will never know about the error, because he typically will not check $dbh->errstr().

I cannot recommend a general way of going on, if dbd_drv_error() returns, but there are examples where even the DBI specification expects that you croak(). (See the AutoCommit method in the DBI manpage.)

If you have to store attributes, you should either use your private data structure imp_xxx, the handle hash (via (HV*)SvRV(dbh)), or use the private imp_data.

The first is best for internal C values like integers or pointers and where speed is important within the driver. The handle hash is best for values the user may want to get/set via driver-specific attributes. The private imp_data is an additional SV attached to the handle. You could think of it as an unnamed handle attribute. It's not normally used.

The dbd_db_FETCH_attrib method

This is the counterpart of dbd_db_STORE_attrib(), needed for:

  $value = $dbh->{$key};

Its prototype is:

  SV* dbd_db_FETCH_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv);

Unlike all previous methods this returns an SV with the value. Note that you should normally execute sv_2mortal(), if you return a nonconstant value. (Constant values are &sv_undef, &sv_no and &sv_yes.)

Note, that DBI implements a caching algorithm for attribute values. If you think, that an attribute may be fetched, you store it in the dbh itself:

  if (cacheit) /* cache value for later DBI 'quick' fetch? */
      hv_store((HV*)SvRV(dbh), key, kl, cachesv, 0);

The dbd_st_prepare method

This is the private part of the prepare() method. Note that you must not really execute the statement here. You may, however, preparse and validate the statement, or do similar things.

  int dbd_st_prepare(SV* sth, imp_sth_t* imp_sth, char* statement,
                     SV* attribs);

A typical, simple, possibility is to do nothing and rely on the perl prepare() code that set the Statement attribute on the handle. This attribute can then be used by dbd_st_execute().

If the driver supports placeholders then the NUM_OF_PARAMS attribute must be set correctly by dbd_st_prepare():

  DBIc_NUM_PARAMS(imp_sth) = ...

If you can, you should also setup attributes like NUM_OF_FIELDS, NAME, etc. here, but DBI doesn't require that - they can be deferred until execute() is called. However, if you do, document it.

In any case you should set the IMPSET flag, as you did in dbd_db_connect() above:

  DBIc_IMPSET_on(imp_sth);

The dbd_st_execute method

This is where a statement will really be executed.

  int dbd_st_execute(SV* sth, imp_sth_t* imp_sth);

Note that you must be aware a statement may be executed repeatedly. Also, you should not expect that finish() will be called between two executions, so you might need code, like the following, near the start of the function:

  if (DBIc_ACTIVE(imp_sth))
      dbd_st_finish(h, imp_sth);

If your driver supports the binding of parameters (it should!), but the database doesn't, you must do it here. This can be done as follows:

  SV *svp;
  char* statement = DBD_ATTRIB_GET_PV(h, "Statement", 9, svp, "");
  int numParam = DBIc_NUM_PARAMS(imp_sth);
  int i;

  for (i = 0; i < numParam; i++)
  {
      char* value = dbd_db_get_param(sth, imp_sth, i);
      /* It is your drivers task to implement dbd_db_get_param,    */
      /* it must be setup as a counterpart of dbd_bind_ph.         */
      /* Look for '?' and replace it with 'value'.  Difficult      */
      /* task, note that you may have question marks inside        */
      /* quotes and comments the like ...  :-(                     */
      /* See DBD::mysql for an example. (Don't look too deep into  */
      /* the example, you will notice where I was lazy ...)        */
  }

The next thing is to really execute the statement.

Note that you must set the attributes NUM_OF_FIELDS, NAME, etc when the statement is successfully executed if the driver has not already done so: they may be used even before a potential fetchrow(). In particular you have to tell DBI the number of fields that the statement has, because it will be used by DBI internally. Thus the function will typically ends with:

  if (isSelectStatement) {
      DBIc_NUM_FIELDS(imp_sth) = numFields;
      DBIc_ACTIVE_on(imp_sth);
  }

It is important that the ACTIVE flag only be set for SELECT statements (or any other statements that can return many values from the database using a cursor-like mechanism). See dbd_db_connect() above for more explanations.

There plans for a preparse function to be provided by DBI, but this has not reached fruition yet. Meantime, if you want to know how ugly it can get, try looking at the dbd_ix_preparse() in DBD::Informix dbdimp.ec and the related functions in iustoken.c and sqltoken.c.

The dbd_st_fetch method

This function fetches a row of data. The row is stored in in an array, of SV's that DBI prepares for you. This has two advantages: it is fast (you even reuse the SV's, so they don't have to be created after the first fetchrow()), and it guarantees that DBI handles bind_cols() for you.

What you do is the following:

  AV* av;
  int numFields = DBIc_NUM_FIELDS(imp_sth); /* Correct, if NUM_FIELDS
      is constant for this statement. There are drivers where this is
      not the case! */
  int chopBlanks = DBIc_is(imp_sth, DBIcf_ChopBlanks);
  int i;

  if (!fetch_new_row_of_data(...)) {
      ... /* check for error or end-of-data */
      DBIc_ACTIVE_off(imp_sth); /* turn off Active flag automatically */
      return Nullav;
  }
  /* get the fbav (field buffer array value) for this row       */
  /* it is very important to only call this after you know      */
  /* that you have a row of data to return.                     */
  av = DBIc_DBISTATE(imp_sth)->get_fbav(imp_sth);
  for (i = 0; i < numFields; i++) {
      SV* sv = fetch_a_field(..., i);
      if (chopBlanks && SvOK(sv) && type_is_blank_padded(field_type[i])) {
          /*  Remove white space from end (only) of sv  */
      }
      sv_setsv(AvARRAY(av)[i], sv); /* Note: (re)use! */
  }
  return av;

There's no need to use a fetch_a_field() function returning an SV*. It's more common to use your database API functions to fetch the data as character strings and use code like this:

  sv_setpvn(AvARRAY(av)[i], char_ptr, char_count);

NULL values must be returned as undef. You can use code like this:

  SvOK_off(AvARRAY(av)[i]);

The function returns the AV prepared by DBI for success or Nullav otherwise.

 *FIX ME* Discuss what happens when there's no more data to fetch.
 Are errors permitted if another fetch occurs after the first fetch
 that reports no more data. (Permitted, not required.)

If an error occurs which leaves the $sth in a state where remaining rows can't be fetched then Active should be turned off before the method returns.

The dbd_st_finish3 method

The $sth->finish() method can be called if the user wishes to indicate that no more rows will be fetched even if the database has more rows to offer, and the DBI code can call the function when handles are being destroyed. See the DBI specification for more background details.

In both circumstances, the DBI code ends up calling the dbd_st_finish3() method (if you provide a mapping for dbd_st_finish3() in dbdimp.h), or dbd_st_finish() otherwise. The difference is that dbd_st_finish3() takes a third argument which is an int with the value 1 if it is being called from a destroy() method and 0 otherwise.

Note that DBI v1.32 and earlier test on dbd_db_finish3() to call dbd_st_finish3(); if you provide dbd_st_finish3(), either define dbd_db_finish3() too, or insist on DBI v1.33 or later.

All it needs to do is turn off the Active flag for the sth. It will only be called by Driver.xst code, if the driver has set ACTIVE to on for the sth.

Outline example:

  int dbd_st_finish3(SV* sth, imp_sth_t* imp_sth, int from_destroy) {
      if (DBIc_ACTIVE(imp_sth))
      {
          /* close cursor or equivalent action */
          DBIc_ACTIVE_off(imp_sth);
      }
      return 1;
  }

The from_destroy parameter is true if dbd_st_finish3() is being called from DESTROY() - and so the statement is about to be destroyed. For many drivers there's no point in doing anything more than turing of the Active flag in this case.

The function returns TRUE for success, FALSE otherwise, but there isn't a lot anyone can do to recover if there is an error.

The dbd_st_destroy method

This function is the private part of the statement handle destructor.

  void dbd_st_destroy(SV* sth, imp_sth_t* imp_sth) {
      ... /* any clean-up that's needed */
      DBIc_IMPSET_off(imp_sth); /* let DBI know we've done it   */
  }

The DBI Driver.xst code will call dbd_st_finish() for you, if the sth has the ACTIVE flag set, before calling dbd_st_destroy().

The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods

These functions correspond to dbd_db_STORE() and dbd_db_FETCH() attrib above, except that they are for statement handles. See above.

  int dbd_st_STORE_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv,
                          SV* valuesv);
  SV* dbd_st_FETCH_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv);

The dbd_bind_ph method

This function is internally used by the bind_param() method, the bind_param_inout() method and by the DBI Driver.xst code if execute() is called with any bind parameters.

  int dbd_bind_ph (SV *sth, imp_sth_t *imp_sth, SV *param,
                   SV *value, IV sql_type, SV *attribs,
                   int is_inout, IV maxlen);

The param argument holds an IV with the parameter number (1, 2, ...). The value argument is the parameter value and sql_type is its type.

If your driver does not support bind_param_inout() then you should ignore maxlen and croak if is_inout is TRUE.

If your driver does support bind_param_inout() then you should note that value is the SV after dereferencing the reference passed to bind_param_inout().

In drivers of simple databases the function will, for example, store the value in a parameter array and use it later in dbd_st_execute(). See the DBD::mysql driver for an example.

Implementing bind_param_inout support

To provide support for parameters bound by reference rather than by value, the driver must do a number of things. First, and most importantly, it must note the references and stash them in its own driver structure. Secondly, when a value is bound to a column, the driver must discard any previous reference bound to the column. On each execute, the driver must evaluate the references and internally bind the values resulting from the references. This is only applicable if the user writes:

  $sth->execute;

If the user writes:

  $sth->execute(@values);

then DBI automatically calls the binding code for each element of @values. These calls are indistinguishable from explicit user calls to bind_param().

C/XS version of Makefile.PL

The Makefile.PL file for a C/XS driver is similar to the code needed for a pure Perl driver, but there are a number of extra bits of information needed by the build system.

For example, the attributes list passed to WriteMakefile() needs to specify the object files that need to be compiled and built into the shared object (DLL). This is often, but not necessarily, just dbdimp.o (unless that should be dbdimp.obj because you're building on MS Windows).

Note that you can reliably determine the extension of the object files from the $Config{obj_ext} values, and there are many other useful pieces of configuration information lurking in that hash. You get access to it with:

    use Config;

Methods which do not need to be written

The DBI code implements the majority of the methods which are accessed using the notation DBI->function(), the only exceptions being DBI->connect() and DBI->data_sources() which require support from the driver.

The DBI code implements the following documented driver, database and statement functions which do not need to be written by the DBD driver writer.

$dbh->do()

The default implementation of this function prepares, executes and destroys the statement. This can be replaced if there is a better way to implement this, such as EXECUTE IMMEDIATE which can sometimes be used if there are no parameters.

$h->errstr()
$h->err()
$h->state()
$h->trace()

The DBD driver does not need to worry about these routines at all.

$h->{ChopBlanks}

This attribute needs to be honored during fetch() operations, but does not need to be handled by the attribute handling code.

$h->{RaiseError}

The DBD driver does not need to worry about this attribute at all.

$h->{PrintError}

The DBD driver does not need to worry about this attribute at all.

$sth->bind_col()

Assuming the driver uses the DBIc_DBISTATE(imp_xxh)->get_fbav() function (C drivers, see below), or the $sth->_set_fbav($data) method (Perl drivers) the driver does not need to do anything about this routine.

$sth->bind_columns()

Regardless of whether the driver uses DBIc_DBISTATE(imp_xxh)->get_fbav(), the driver does not need to do anything about this routine as it simply iteratively calls $sth->bind_col().

The DBI code implements a default implementation of the following functions which do not need to be written by the DBD driver writer unless the default implementation is incorrect for the Driver.

$dbh->quote()

This should only be written if the database does not accept the ANSI SQL standard for quoting strings, with the string enclosed in single quotes and any embedded single quotes replaced by two consecutive single quotes.

For the two argument form of quote, you need to implement the type_info() method to provide the information that quote needs.

$dbh->ping()

This should be implemented as a simple efficient way to determine whether the connection to the database is still alive. Typically code like this:

  sub ping {
      my $dbh = shift;
      $sth = $dbh->prepare_cached(q{
          select * from A_TABLE_NAME where 1=0
      }) or return 0;
      $sth->execute or return 0;
      $sth->finish;
      return 1;
  }

where A_TABLE_NAME is the name of a table that always exists (such as a database system catalogue).

METADATA METHODS

The exposition above ignores the DBI MetaData methods. The metadata methods are all associated with a database handle.

Using DBI::DBD::Metadata

The DBI::DBD::Metadata module is a good semi-automatic way for the developer of a DBD module to write the get_info() and type_info() functions quickly and accurately.

Generating the get_info method

Prior to DBI v1.33, this existed as the method write_getinfo_pm() in the DBI::DBD module. From DBI v1.33, it exists as the method write_getinfo_pm() in the DBI::DBD::Metadata module. This discussion assumes you have DBI v1.33 or later.

You examine the documentation for write_getinfo_pm() using:

    perldoc DBI::DBD::Metadata

To use it, you need a Perl DBI driver for your database which implements the get_info() method. In practice, this means you need to install DBD::ODBC, an ODBC driver manager, and an ODBC driver for your database.

With the pre-requisites in place, you might type:

    perl -MDBI::DBD::Metadata -e write_getinfo_pm \
            dbi:ODBC:foo_db username password Driver

The procedure writes to standard output the code that should be added to your Driver.pm file and the code that should be written to lib/DBD/Driver/GetInfo.pm.

You should review the output to ensure that it is sensible.

Generating the type_info method

Given the idea of the write_getinfo_pm() method, it was not hard to devise a parallel method, write_typeinfo_pm(), which does the analogous job for the DBI type_info_all() metadata method. The write_typeinfo_pm() method was added to DBI v1.33.

You examine the documentation for write_typeinfo_pm() using:

    perldoc DBI::DBD::Metadata

The setup is exactly analogous to the mechanism descibed in Generating the get_info method.

With the pre-requisites in place, you might type:

    perl -MDBI::DBD::Metadata -e write_typeinfo \
            dbi:ODBC:foo_db username password Driver

The procedure writes to standard output the code that should be added to your Driver.pm file and the code that should be written to lib/DBD/Driver/TypeInfo.pm.

You should review the output to ensure that it is sensible.

Writing DBD::Driver::db::get_info

If you use the DBI::DBD::Metadata module, then the code you need is generated for you.

If you decide not to use the DBI::DBD::Metadata module, you should probably borrow the code from a driver that has done so (eg DBD::Informix from version 1.05 onwards) and crib the code from there, or look at the code that generates that module and follow that. The method in Driver.pm will be very simple; the method in lib/DBD/Driver/GetInfo.pm is not very much more complex unless your DBMS itself is much more complex.

Note that some of the DBI utility methods rely on information from the get_info() method to perform their operations correctly. See, for example, the quote_identifier() and quote methods, discussed below.

Writing DBD::Driver::db::type_info_all

If you use the DBI::DBD::Metadata module, then the code you need is generated for you.

If you decide not to use the DBI::DBD::Metadata module, you should probably borrow the code from a driver that has done so (eg DBD::Informix from version 1.05 onwards) and crib the code from there, or look at the code that generates that module and follow that. The method in Driver.pm will be very simple; the method in lib/DBD/Driver/TypeInfo.pm is not very much more complex unless your DBMS itself is much more complex.

Writing DBD::Driver::db::type_info

The guidelines on writing this method are still not really clear. No sample implementation is available.

Writing DBD::Driver::db::table_info

 *FIX ME* The guidelines on writing this method have not been written yet.
 No sample implementation is available.

Writing DBD::Driver::db::column_info

 *FIX ME* The guidelines on writing this method have not been written yet.
 No sample implementation is available.

Writing DBD::Driver::db::primary_key_info

 *FIX ME* The guidelines on writing this method have not been written yet.
 No sample implementation is available.

Writing DBD::Driver::db::primary_key

 *FIX ME* The guidelines on writing this method have not been written yet.
 No sample implementation is available.

Writing DBD::Driver::db::foreign_key_info

 *FIX ME* The guidelines on writing this method have not been written yet.
 No sample implementation is available.

Writing DBD::Driver::db::tables

This method generates an array of names in a format suitable for being embedded in SQL statements in places where a table name is expected.

If your database hews close enough to the SQL standard or if you have implemented an appropriate table_info() function and and the appropriate quote_identifier() function, then the DBI default version of this method will work for your driver too.

Otherwise, you have to write a function yourself, such as:

    sub tables
    {
        my($dbh, $cat, $sch, $tab, $typ) = @_;
        my(@res);
        my($sth) = $dbh->table_info($cat, $sch, $tab, $typ);
        my(@arr);
        while (@arr = $sth->fetchrow_array)
        {
            push @res, $dbh->quote_identifier($arr[0], $arr[1], $arr[2]);
        }
        return @res;
    }

See also the default implementation in DBI.pm.

Writing DBD::Driver::db::quote

This method takes a value and converts it into a string suitable for embedding in an SQL statement as a string literal.

If your DBMS accepts the SQL standard notation for strings (single quotes around the string as a whole with any embedded single quotes doubled up), then you do not need to write this method as DBI provides a default method that does it for you.

If your DBMS uses an alternative notation or escape mechanism, then you need to provide an equivalent function. For example, suppose your DBMS used C notation with double quotes around the string and backslashes escaping both double quotes and backslashes themselves. Then you might write the function as:

    sub quote
    {
        my($dbh, $str) = @_;
        $str =~ s/["\\]/\\$&/gmo;
        return qq{"$str"};
    }

Handling newlines and other control characters is left as an exercise for the reader.

This sample method ignores the $data_type indicator which is the optional second argument to the method.

Writing DBD::Driver::db::quote_identifier

This method is called to ensure that the name of the given table (or other database object) can be embedded into an SQL statement without danger of misinterpretation. The result string should be usable in the text of an SQL statement as the identifier for a table.

If your DBMS accepts the SQL standard notation for quoted identifiers (which uses double quotes around the identifier as a whole, with any embedded double quotes doubled up) and accepts "schema"."identifier" (and "catalog"."schema"."identifier" when a catalog is specified), then you do not need to write this method as DBI provides a default method that does it for you.

In fact, even if your DBMS does not handle exactly that notation but you have implemented the get_info() method and it gives the correct responses, then it will work for you. If your database is fussier, then you need to implement your own version of the function.

For example, DBD::Informix has to deal with an environment variable DELIMIDENT. If it is not set, then the DBMS treats names enclosed in double quotes as strings rather than names, which is usually a syntax error. Additionally, the catalog portion of the name is separated from the schema and table by a different delimiter (colon instead of dot), and the catalog portion is never enclosed in quotes. (Fortunately, valid strings for the catalog will never contain weird characters that might need to be escaped, unless you count dots, dashes, slashes and at-signs as weird.) Finally, an Informix database can contain objects that cannot be accessed because they were created by a user with the DELIMIDENT environment variable set, but the current user does not have it set. By design choice, the quote_identifier() method encloses those identifiers in double quotes anyway, which generally triggers a syntax error, and the metadata methods which generate lists of tables etc omit those identifiers from the result sets.

    sub quote_identifier
    {
        my($dbh, $cat, $sch, $obj) = @_;
        my($rv) = "";
        my($qq) = (defined $ENV{DELIMIDENT}) ? '"' : '';
        $rv .= qq{$cat:} if (defined $cat);
        if (defined $sch)
        {
            if ($sch !~ m/^\w+$/o)
            {
                $qq = '"';
                $sch =~ s/$qq/$qq$qq/gm;
            }
            $rv .= qq{$qq$sch$qq.};
        }
        if (defined $obj)
        {
            if ($obj !~ m/^\w+$/o)
            {
                $qq = '"';
                $obj =~ s/$qq/$qq$qq/gm;
            }
            $rv .= qq{$qq$obj$qq};
        }
        return $rv;
    }

Handling newlines and other control characters is left as an exercise for the reader.

Note that there is an optional fourth parameter to this function which is a reference to a hash of attributes; this sample implementation ignores that.

This sample implementation also ignores the single-argument variant of the method.

WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE

Study Oraperl.pm (supplied with DBD::Oracle) and Ingperl.pm (supplied with DBD::Ingres) and the corresponding dbdimp.c files for ideas.

Note that the emulation code sets $dbh->{CompatMode} = 1; for each connection so that the internals of the driver can implement behaviour compatible with the old interface when dealing with those handles.

Setting emulation perl variables

For example, ingperl has a $sql_rowcount variable. Rather than try to manually update this in Ingperl.pm it can be done faster in C code. In dbd_init():

  sql_rowcount = perl_get_sv("Ingperl::sql_rowcount", GV_ADDMULTI);

In the relevant places do:

  if (DBIc_COMPAT(imp_sth))     /* only do this for compatibility mode handles */
      sv_setiv(sql_rowcount, the_row_count);

OTHER MISCELLANEOUS INFORMATION

The imp_xyz_t types

Any handle has a corresponding C structure filled with private data. Some of this data is reserved for use by DBI (except for using the DBIc macros below), some is for you. See the description of the dbdimp.h file above for examples. Most functions in dbdimp.c are passed both the handle xyz and a pointer to imp_xyz. In rare cases, however, you may use the following macros:

D_imp_dbh(dbh)

Given a function argument dbh, declare a variable imp_dbh and initialize it with a pointer to the handles private data. Note: This must be a part of the function header, because it declares a variable.

D_imp_sth(sth)

Likewise for statement handles.

D_imp_xxx(h)

Given any handle, declare a variable imp_xxx and initialize it with a pointer to the handles private data. It is safe, for example, to cast imp_xxx to imp_dbh_t*, if DBIc_TYPE(imp_xxx) == DBIt_DB. (You can also call sv_derived_from(h, "DBI::db"), but that's much slower.)

D_imp_dbh_from_sth

Given a imp_sth, declare a variable imp_dbh and initialize it with a pointer to the parent database handle's implementors structure.

Using DBIc_IMPSET_on

The driver code which initializes a handle should use DBIc_IMPSET_on() as soon as its state is such that the cleanup code must be called. When this happens is determined by your driver code.

Failure to call this can lead to corruption of data structures.

For example, DBD::Informix maintains a linked list of database handles in the driver, and within each handle, a linked list of statements. Once a statement is added to the linked list, it is crucial that it is cleaned up (removed from the list). When DBIc_IMPSET_on() was being called too late, it was able to cause all sorts of problems.

Using DBIc_is(), DBIc_has(), DBIc_on() and DBIc_off()

Once upon a long time ago, the only way of handling the internal DBI boolean flags/attributes was through macros such as:

  DBIc_WARN       DBIc_WARN_on        DBIc_WARN_off
  DBIc_COMPAT     DBIc_COMPAT_on      DBIc_COMPAT_off

Each of these took an imp_xxh pointer as an argument.

Since then, new attributes have been added such as ChopBlanks, RaiseError and PrintError, and these do not have the full set of macros. The approved method for handling these is now the four macros:

  DBIc_is(imp, flag)
  DBIc_has(imp, flag)       an alias for DBIc_is
  DBIc_on(imp, flag)
  DBIc_off(imp, flag)
  DBIc_set(imp, flag, on)   set if on is true, else clear

Consequently, the DBIc_XXXXX family of macros is now mostly deprecated and new drivers should avoid using them, even though the older drivers will probably continue to do so for quite a while yet. However...

There is an important exception to that. The ACTIVE and IMPSET flags should be set via the DBIc_ACTIVE_on() and DBIc_IMPSET_on() macros, and unset via the DBIc_ACTIVE_off() and DBIc_IMPSET_off() macros.

Using the get_fbav() method

THIS IS CRITICAL for C/XS drivers.

The $sth->bind_col() and $sth->bind_columns() documented in the DBI specification do not have to be implemented by the driver writer because DBI takes care of the details for you.

However, the key to ensuring that bound columns work is to call the function DBIc_DBISTATE(imp_xxh)->get_fbav() in the code which fetches a row of data.

This returns an AV, and each element of the AV contains the SV which should be set to contain the returned data.

The pure Perl equivalent is the $sth->_set_fbav($data) method, as described in the part on pure Perl drivers.

SUBCLASSING DBI DRIVERS

This is definitely an open subject. It can be done, as demonstrated by the DBD::File driver, but it is not as simple as one might think.

(Note that this topic is different from subclassing the DBI. For an example of that, see the t/subclass.t file supplied with the DBI.)

The main problem is that the dbh's and sth's that your connect() and prepare() methods return are not instances of your DBD::Driver::db or DBD::Driver::st packages, they are not even derived from it. Instead they are instances of the DBI::db or DBI::st classes or a derived subclass. Thus, if you write a method mymethod() and do a

  $dbh->mymethod()

then the autoloader will search for that method in the package DBI::db. Of course you can instead to a

  $dbh->func('mymethod')

and that will indeed work, even if mymethod() is inherited, but not without additional work. Setting @ISA is not sufficient.

Overwriting methods

The first problem is, that the connect() method has no idea of subclasses. For example, you cannot implement base class and subclass in the same file: The install_driver() method wants to do a

  require DBD::Driver;

In particular, your subclass has to be a separate driver, from the view of DBI, and you cannot share driver handles.

Of course that's not much of a problem. You should even be able to inherit the base classes connect() method. But you cannot simply overwrite the method, unless you do something like this, quoted from DBD::CSV:

  sub connect ($$;$$$) {
      my ($drh, $dbname, $user, $auth, $attr) = @_;

      my $this = $drh->DBD::File::dr::connect($dbname, $user, $auth, $attr);
      if (!exists($this->{csv_tables})) {
          $this->{csv_tables} = {};
      }

      $this;
        }

Note that we cannot do a

  $drh->SUPER::connect($dbname, $user, $auth, $attr);

as we would usually do in a an OO environment, because $drh is an instance of DBI::dr. And note, that the connect() method of DBD::File is able to handle subclass attributes. See the description of Pure Perl drivers above.

It is essential that you always call superclass method in the above manner. However, that should do.

Attribute handling

Fortunately the DBI specifications allow a simple, but still performant way of handling attributes. The idea is based on the convention that any driver uses a prefix driver_ for its private methods. Thus it's always clear whether to pass attributes to the super class or not. For example, consider this STORE() method from the DBD::CSV class:

  sub STORE {
      my ($dbh, $attr, $val) = @_;
      if ($attr !~ /^driver_/) {
          return $dbh->DBD::File::db::STORE($attr, $val);
      }
      if ($attr eq 'driver_foo') {
      ...
  }

AUTHORS

Jonathan Leffler <jleffler@us.ibm.com> (previously <jleffler@informix.com>), Jochen Wiedmann <joe@ispsoft.de>, Steffen Goeldner <sgoeldner@cpan.org>, and Tim Bunce <dbi-users@perl.org>.


DBI::DBD::Metadata - Generate the code and data for some DBI metadata methods

  • Generating a GetInfo package for a driver
  • Generating a TypeInfo package for a driver
  • AUTHORS

NAME

DBI::DBD::Metadata - Generate the code and data for some DBI metadata methods

SYNOPSIS

The idea is to extract metadata information from a good quality ODBC driver and use it to generate code and data to use in your own DBI driver for the same database.

For generating code to support the get_info method:

  perl -MDBI::DBD::Metadata -e "write_getinfo_pm('dbi:ODBC:dsn-name','user','pass','Driver')"
  perl -MDBI::DBD::Metadata -e write_getinfo_pm dbi:ODBC:foo_db username password Driver

For generating code to support the type_info method:

  perl -MDBI::DBD::Metadata -e "write_typeinfo_pm('dbi:ODBC:dsn-name','user','pass','Driver')"
  perl -MDBI::DBD::Metadata -e write_typeinfo_pm dbi:ODBC:dsn-name user pass Driver

Where dbi:ODBC:dsn-name is the connection to use to extract the data, and Driver is the name of the driver you want the code generated for (the driver name gets embedded into the output in many places).

Generating a GetInfo package for a driver

The write_getinfo_pm in the DBI::DBD::Metadata module generates a DBD::Driver::GetInfo package on standard output.

This method generates a DBD::Driver::GetInfo package from the data source you specified in the parameter list or in the environment variable DBI_DSN. DBD::Driver::GetInfo should help a DBD author implementing the DBI get_info() method. Because you are just creating this package, it's very unlikely that DBD::Driver already provides a good implementation for get_info(). Thus you will probably connect via DBD::ODBC.

Once you are sure that it is producing semi-sane data, you would typically redirect the standard output to lib/DBD/Driver/GetInfo.pm, and then hand edit the result. Do not forget to update your Makefile.PL and MANIFEST to include this as an extra PM file that should be installed.

If you connect via DBD::ODBC, you should use version 0.38 or greater;

Please take a critical look at the data returned! ODBC drivers vary dramatically in their quality.

The generator assumes that most values are static and places these values directly in the %info hash. A few examples show the use of CODE references and the implementation via subroutines. It is very likely that you have to write additional subroutines for values depending on the session state or server version, e.g. SQL_DBMS_VER.

A possible implementation of DBD::Driver::db::get_info() may look like:

  sub get_info {
    my($dbh, $info_type) = @_;
    require DBD::Driver::GetInfo;
    my $v = $DBD::Driver::GetInfo::info{int($info_type)};
    $v = $v->($dbh) if ref $v eq 'CODE';
    return $v;
  }

Please replace Driver (or "<foo>") with the name of your driver. Note that this stub function is generated for you by write_getinfo_pm function, but you must manually transfer the code to Driver.pm.

Generating a TypeInfo package for a driver

The write_typeinfo_pm function in the DBI::DBD::Metadata module generates on standard output the data needed for a driver's type_info_all method. It also provides default implementations of the type_info_all method for inclusion in the driver's main implementation file.

The driver parameter is the name of the driver for which the methods will be generated; for the sake of examples, this will be "Driver". Typically, the dsn parameter will be of the form "dbi:ODBC:odbc_dsn", where the odbc_dsn is a DSN for one of the driver's databases. The user and pass parameters are the other optional connection parameters that will be provided to the DBI connect method.

Once you are sure that it is producing semi-sane data, you would typically redirect the standard output to lib/DBD/Driver/TypeInfo.pm, and then hand edit the result if necessary. Do not forget to update your Makefile.PL and MANIFEST to include this as an extra PM file that should be installed.

Please take a critical look at the data returned! ODBC drivers vary dramatically in their quality.

The generator assumes that all the values are static and places these values directly in the %info hash.

A possible implementation of DBD::Driver::type_info_all() may look like:

  sub type_info_all {
    my ($dbh) = @_;
    require DBD::Driver::TypeInfo;
    return [ @$DBD::Driver::TypeInfo::type_info_all ];
  }

Please replace Driver (or "<foo>") with the name of your driver. Note that this stub function is generated for you by the write_typeinfo_pm function, but you must manually transfer the code to Driver.pm.

AUTHORS

Jonathan Leffler <jleffler@us.ibm.com> (previously <jleffler@informix.com>), Jochen Wiedmann <joe@ispsoft.de>, Steffen Goeldner <sgoeldner@cpan.org>, and Tim Bunce <dbi-users@perl.org>.


DBI::FAQ -- The Frequently Asked Questions for the Perl5 Database Interface

  • VERSION
  • DESCRIPTION
  • Basic Information & Information Sources
    • 1.1 What is DBI, DBperl, Oraperl and *perl?
    • 1.2. Where can I get it from?
    • 1.3. Where can I get more information?
  • Compilation Problems
    • 2.1. Compilation problems or "It fails the test!"
  • Platform and Driver Issues
    • 3.1 What's the difference between ODBC and DBI?
    • 3.2 What's the difference between Win32::ODBC and DBD::ODBC?
    • 3.3 Is DBI supported under Windows 95 / NT platforms?
    • 3.4 Can I access Microsoft Access or SQL-Server databases with DBI?
    • 3.5 Is the a DBD for <insert favourite database here>?
    • 3.6 What's DBM? And why should I use DBI instead?
    • 3.7 What database do you recommend me using?
    • 3.8 Is <insert feature here> supported in DBI?
  • Programming Questions
    • 4.1 Is DBI any use for CGI programming?
    • 4.2 How do I get faster connection times with DBD::Oracle and CGI?
    • 4.3 How do I get persistent connections with DBI and CGI?
    • 4.4 ``When I run a perl script from the command line, it works, but, when I run it under the httpd, it fails!'' Why?
    • 4.5 How do I get the number of rows returned from a SELECT statement?
  • Miscellaneous Questions
    • 5.1 Can I do multi-threading with DBI?
    • 5.2 How do I handle BLOB data with DBI?
    • 5.3 How can I invoke stored procedures with DBI?
    • 5.4 How can I get return values from stored procedures with DBI?
    • 5.5 How can I create or drop a database with DBI?
    • 5.6 How can I commit or rollback a statement with DBI?
    • 5.7 How are NULL values handled by DBI?
    • 5.8 What are these func() methods all about?
    • 5.9 Is DBI Year 2000 Compliant?
  • Support and Training
    • Commercial Support
    • Training
  • Other References
  • AUTHOR
  • COPYRIGHT

NAME

DBI::FAQ -- The Frequently Asked Questions for the Perl5 Database Interface

DBI Frequently Asked Questions v.0.38
Last updated: February 8th, 2000

SYNOPSIS

    perldoc DBI::FAQ

VERSION

This document is currently at version 0.38, as of February 8th, 2000.

DESCRIPTION

This document serves to answer the most frequently asked questions on both the DBI Mailing Lists and personally to members of the DBI development team.

Basic Information & Information Sources

1.1 What is DBI, DBperl, Oraperl and *perl?

To quote Tim Bunce, the architect and author of DBI:

    ``DBI is a database access Application Programming Interface (API)
      for the Perl Language. The DBI API Specification defines a set
      of functions, variables and conventions that provide a consistent
      database interface independant of the actual database being used.''

In simple language, the DBI interface allows users to access multiple database types transparently. So, if you connecting to an Oracle, Informix, mSQL, Sybase or whatever database, you don't need to know the underlying mechanics of the 3GL layer. The API defined by DBI will work on all these database types.

A similar benefit is gained by the ability to connect to two different databases of different vendor within the one perl script, ie, I want to read data from an Oracle database and insert it back into an Informix database all within one program. The DBI layer allows you to do this simply and powerfully.

Here's a diagram that demonstrates the principle:

[ DBI Architecture ]

DBperl is the old name for the interface specification. It's usually now used to denote perl4 modules on database interfacing, such as, oraperl, isqlperl, ingperl and so on. These interfaces didn't have a standard API and are generally not supported.

Here's a list of DBperl modules, their corresponding DBI counterparts and support information. Please note, the author's listed here generally do not maintain the DBI module for the same database. These email addresses are unverified and should only be used for queries concerning the perl4 modules listed below. DBI driver queries should be directed to the dbi-users mailing list.

    Module Name Database Required   Author          DBI
    ----------- -----------------   ------          ---
    Sybperl     Sybase              Michael Peppler DBD::Sybase
                                    <mpeppler@itf.ch>
    Oraperl     Oracle 6 & 7        Kevin Stock     DBD::Oracle
                                    <dbi-users@perl.org>
    Ingperl     Ingres              Tim Bunce &     DBD::Ingres
                                    Ted Lemon
                                    <dbi-users@perl.org>
    Interperl   Interbase           Buzz Moschetti  DBD::Interbase
                                    <buzz@bear.com>
    Uniperl     Unify 5.0           Rick Wargo      None
                                    <rickers@coe.drexel.edu>
    Pgperl      Postgres            Igor Metz       DBD::Pg
                                    <metz@iam.unibe.ch>
    Btreeperl   NDBM                John Conover    SDBM?
                                    <john@johncon.com>
    Ctreeperl   C-Tree              John Conover    None
                                    <john@johncon.com>
    Cisamperl   Informix C-ISAM     Mathias Koerber None
                                    <mathias@unicorn.swi.com.sg>
    Duaperl     X.500 Directory     Eric Douglas    None
                User Agent

However, some DBI modules have DBperl emulation layers, so, DBD::Oracle comes with an Oraperl emulation layer, which allows you to run legacy oraperl scripts without modification. The emulation layer translates the oraperl API calls into DBI calls and executes them through the DBI switch.

Here's a table of emulation layer information:

    Module                  Emulation Layer     Status
    ------          ---------------     ------
    DBD::Oracle     Oraperl             Complete
    DBD::Informix   Isqlperl            Under development
    DBD::Ingres     Ingperl             Complete?
    DBD::Sybase     Sybperl             Working? ( Needs verification )
    DBD::mSQL       Msqlperl            Experimentally released with
                                        DBD::mSQL-0.61

The Msqlperl emulation is a special case. Msqlperl is a perl5 driver for mSQL databases, but does not conform to the DBI Specification. It's use is being deprecated in favour of DBD::mSQL. Msqlperl may be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Msqlperl

1.2. Where can I get it from?

The Comprehensive Perl Archive Network resources should be used for retrieving up-to-date versions of the DBI and drivers. CPAN may be accessed via Tom Christiansen's splendid CPAN multiplexer program located at:

    http://www.perl.com/CPAN/

For more specific version information and exact URLs of drivers, please see the DBI drivers list and the DBI module pages which can be found on:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

This list is automatically generated on a nightly basis from CPAN and should be up-to-date.

1.3. Where can I get more information?

There are a few information sources on DBI.

"Programming the Perl DBI"

"Programming the Perl DBI" is the official book on the DBI written by Alligator Descartes and Tim Bunce and published by O'Reilly & Associates. The book was released on February 9th, 2000.

The table of contents is:

    Preface
    1. Introduction
        From Mainframes to Workstations
        Perl
        DBI in the Real World
        A Historical Interlude and Standing Stones
    2. Basic Non-DBI Databases
        Storage Managers and Layers
        Query Languages and Data Functions
        Standing Stones and the Sample Database
        Flat-File Databases
        Putting Complex Data into Flat Files
        Concurrent Database Access and Locking
        DBM Files and the Berkeley Database Manager
        The MLDBM Module
        Summary
    3. SQL and Relational Databases
        The Relational Database Methodology
        Datatypes and NULL Values
        Querying Data
        Modifying Data Within Tables
        Creating and Destroying Tables
    4. Programming with the DBI
        DBI Architecture
        Handles
        Data Source Names
        Connection and Disconnection
        Error Handling
        Utility Methods and Functions
    5. Interacting with the Database
        Issuing Simple Queries
        Executing Non-SELECT Statements
        Binding Parameters to Statements
        Binding Output Columns
        do() Versus prepare()
        Atomic and Batch Fetching
    6. Advanced DBI
        Handle Attributes and Metadata
        Handling LONG/LOB Data
        Transactions, Locking, and Isolation
    7. ODBC and the DBI
        ODBC -- Embraced and Extended
        DBI -- Thrashed and Mutated
        The Nuts and Bolts of ODBC
        ODBC from Perl
        The Marriage of DBI and ODBC
        Questions and Choices
        Moving Between Win32::ODBC and the DBI
        And What About ADO?
    8. DBI Shell and Database Proxying
        dbish -- The DBI Shell
        Database Proxying
    A. DBI Specification
    B. Driver and Database Characteristics
    C. ASLaN Sacred Site Charter
    Index

The book should be available from all good bookshops and can be ordered online either <I>via</I> O'Reilly & Associates

    http://www.oreilly.com/catalog/perldbi

or Amazon

    http://www.amazon.com/exec/obidos/ASIN/1565926994/dbi
POD documentation

PODs are chunks of documentation usually embedded within perl programs that document the code ``in place'', providing a useful resource for programmers and users of modules. POD for DBI and drivers is beginning to become more commonplace, and documentation for these modules can be read with the perldoc program included with Perl.

The DBI Specification

The POD for the DBI Specification can be read with the:

    perldoc DBI

command. The Specification also forms Appendix A of "Programming the Perl DBI".

Oraperl

Users of the Oraperl emulation layer bundled with DBD::Oracle, may read up on how to program with the Oraperl interface by typing:

    perldoc Oraperl

This will produce an updated copy of the original oraperl man page written by Kevin Stock for perl4. The oraperl API is fully listed and described there.

Drivers

Users of the DBD modules may read about some of the private functions and quirks of that driver by typing:

    perldoc <driver>

For example, the DBD::mSQL driver is bundled with driver-specific documentation that can be accessed by typing

    perldoc DBD::mSQL
Frequently Asked Questions

This document, the Frequently Asked Questions is also available as POD documentation! You can read this on your own system by typing:

    perldoc DBI::FAQ

This may be more convenient to persons not permanently, or conveniently, connected to the Internet. The DBI::FAQ module should be downloaded and installed for the more up-to-date version.

The version of DBI::FAQ shipped with the DBI module may be slightly out of date.

POD in general

Information on writing POD, and on the philosophy of POD in general, can be read by typing:

    perldoc perlpod

Users with the Tk module installed may be interested to learn there is a Tk-based POD reader available called tkpod, which formats POD in a convenient and readable way. This is available via CPAN as the module called Tk::POD and is highly recommended.

Driver and Database Characteristics

The driver summaries that were produced for Appendix B of "Programming the Perl DBI" are available online at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

in the driver information table. These summaries contain standardised information on each driver and database which should aid you in selecting a database to use. It will also inform you quickly of any issues within drivers or whether a driver is not fully compliant with the DBI Specification.

Rambles, Tidbits and Observations
    http://dbi.perl.org/tidbits
    http://www.symbolstone.org/technology/perl/DBI/tidbits

There are a series of occasional rambles from various people on the DBI mailing lists who, in an attempt to clear up a simple point, end up drafting fairly comprehensive documents. These are quite often varying in quality, but do provide some insights into the workings of the interfaces.

Articles

A list of articles discussing the DBI can be found on the DBI WWW page at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

These articles are of varying quality and age, from the original Perl Journal article written by Alligator and Tim, to more recent debacles published online from about.com.

README files

The README files included with each driver occasionally contains some useful information ( no, really! ) that may be pertinent to the user. Please read them. It makes our worthless existences more bearable. These can all be read from the main DBI WWW page at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI
Mailing Lists

There are three mailing lists for DBI:

    dbi-announce@perl.org     -- for announcements, very low traffic
    dbi-users@perl.org        -- general user support
    dbi-dev@perl.org          -- for driver developers (no user support)

For information on how to subscribe, set digest mode etc, and unsubscribe, send an email message (the content will be ignored) to:

    dbi-announce-help@perl.org
    dbi-users-help@perl.org
    dbi-dev-help@perl.org
Mailing List Archives
US Mailing List Archives
    http://outside.organic.com/mail-archives/dbi-users/

Searchable hypermail archives of the three mailing lists, and some of the much older traffic have been set up for users to browse.

European Mailing List Archives
    http://www.rosat.mpe-garching.mpg.de/mailing-lists/PerlDB-Interest

As per the US archive above.

Compilation Problems

2.1. Compilation problems or "It fails the test!"

First off, consult the README for that driver in case there is useful information about the problem. It may be a known problem for your given architecture and operating system or database. You can check the README files for each driver in advance online at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

If it's a known problem, you'll probably have to wait till it gets fixed. If you're really needing it fixed, try the following:

Attempt to fix it yourself

This technique is generally not recommended to the faint-hearted. If you do think you have managed to fix it, then, send a patch file ( context diff ) to the author with an explanation of:

  • What the problem was, and test cases, if possible.

  • What you needed to do to fix it. Please make sure you mention everything.

  • Platform information, database version, perl version, module version and DBI version.

Email the author Do NOT whinge!

Please email the address listed in the WWW pages for whichever driver you are having problems with. Do not directly email the author at a known address unless it corresponds with the one listed.

We tend to have real jobs to do, and we do read the mailing lists for problems. Besides, we may not have access to <insert your favourite brain-damaged platform here> and couldn't be of any assistance anyway! Apologies for sounding harsh, but that's the way of it!

However, you might catch one of these creative genii at 3am when we're doing this sort of stuff anyway, and get a patch within 5 minutes. The atmosphere in the DBI circle is that we do appreciate the users' problems, since we work in similar environments.

If you are planning to email the author, please furnish as much information as possible, ie:

  • ALL the information asked for in the README file in the problematic module. And we mean ALL of it. We don't put lines like that in documentation for the good of our health, or to meet obscure README file standards of length.

  • If you have a core dump, try the Devel::CoreStack module for generating a stack trace from the core dump. Send us that too. Devel::CoreStack can be found on CPAN at:

        http://www.perl.com/cgi-bin/cpan_mod?module=Devel::CoreStack

  • Module versions, perl version, test cases, operating system versions and any other pertinent information.

Remember, the more information you send us, the quicker we can track problems down. If you send us no useful information, expect nothing back.

Finally, please be aware that some authors, including Tim Bunce, specifically request that you do not mail them directly. Please respect their wishes and use the email addresses listed in the appropriate module README file.

Email the dbi-users Mailing List

It's usually a fairly intelligent idea to cc the mailing list anyway with problems. The authors all read the lists, so you lose nothing by mailing there.

Platform and Driver Issues

3.1 What's the difference between ODBC and DBI?

In terms of architecture - not much: Both define programming interfaces. Both allow multiple drivers to be loaded to do the actual work.

In terms of ease of use - much: The DBI is a 'high level' interface that, like Perl itself, strives to make the simple things easy while still making the hard things possible. The ODBC is a 'low level' interface. All nuts-bolts-knobs-and-dials.

Now there's an ODBC driver for the DBI (DBD::ODBC) the "What's the difference" question is more usefully rephrased as:

Chapter 7 of "Programming the Perl DBI" covers this topic in far more detail and should be consulted.

3.2 What's the difference between Win32::ODBC and DBD::ODBC?

The DBI, and thus DBD::ODBC, has a different philosophy from the Win32::ODBC module:

The Win32::ODBC module is a 'thin' layer over the low-level ODBC API. The DBI defines a simpler 'higher level' interface.

The Win32::ODBC module gives you access to more of the ODBC API. The DBI and DBD::ODBC give you access to only the essentials. (But, unlike Win32::ODBC, the DBI and DBD::ODBC do support parameter binding and multiple prepared statements which reduces the load on the database server and can dramatically increase performance.)

The Win32::ODBC module only works on Win32 systems. The DBI and DBD::ODBC are very portable and work on Win32 and Unix.

The DBI and DBD::ODBC modules are supplied as a standard part of the Perl 5.004 binary distribution for Win32 (they don't work with the older, non-standard, ActiveState port).

Scripts written with the DBI and DBD::ODBC are faster than Win32::ODBC on Win32 and are trivially portable to other supported database types.

The DBI offers optional automatic printing or die()ing on errors which makes applications simpler and more robust.

The current DBD::ODBC driver version 0.16 is new and not yet fully stable. A new release is due soon [relative to the date of the next TPJ issue :-] and will be much improved and offer more ODBC functionality.

To summarise: The Win32::ODBC module is your best choice if you need access to more of the ODBC API than the DBI gives you. Otherwise, the DBI and DBD::ODBC combination may be your best bet.

Chapter 7 of "Programming the Perl DBI" covers this topic in far more detail and should be consulted.

3.3 Is DBI supported under Windows 95 / NT platforms?

Finally, yes! Jeff Urlwin has been working diligently on building DBI and DBD::ODBC under these platforms, and, with the advent of a stabler perl and a port of MakeMaker, the project has come on by great leaps and bounds.

The DBI and DBD::Oracle Win32 ports are now a standard part of DBI, so, downloading DBI of version higher than 0.81 should work fine as should using the most recent DBD::Oracle version.

3.4 Can I access Microsoft Access or SQL-Server databases with DBI?

Yes, use the DBD::ODBC driver.

3.5 Is the a DBD for <insert favourite database here>?

Is is listed on the DBI drivers page?

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

If not, no. A complete absence of a given database driver from that page means that no-one has announced any intention to work on it, not that such a driver is impossible to write.

A corollary of the above statement implies that if you see an announcement for a driver not on the above page, there's a good chance it's not actually a DBI driver, and may not conform to the specifications. Therefore, questions concerning problems with that code should not really be addressed to the DBI Mailing Lists.

3.6 What's DBM? And why should I use DBI instead?

Extracted from ``DBI - The Database Interface for Perl 5'':

    ``UNIX was originally blessed with simple file-based ``databases'', namely
    the dbm system. dbm lets you store data in files, and retrieve
    that data quickly. However, it also has serious drawbacks.
        File Locking
        The dbm systems did not allow particularly robust file locking
        capabilities, nor any capability for correcting problems arising through
        simultaneous writes [ to the database ].
        Arbitrary Data Structures
        The dbm systems only allows a single fixed data structure:
        key-value pairs. That value could be a complex object, such as a
        [ C ] struct, but the key had to be unique. This was a large
        limitation on the usefulness of dbm systems.
    However, dbm systems still provide a useful function for users with
    simple datasets and limited resources, since they are fast, robust and
    extremely well-tested. Perl modules to access dbm systems have now
    been integrated into the core Perl distribution via the
    AnyDBM_File module.''

To sum up, DBM is a perfectly satisfactory solution for essentially read-only databases, or small and simple datasets. However, for more scaleable dataset handling, not to mention robust transactional locking, users are recommended to use a more powerful database engine via DBI.

Chapter 2 of "Programming the Perl DBI" discusses DBM files in detail.

3.7 What database do you recommend me using?

This is a particularly thorny area in which an objective answer is difficult to come by, since each dataset, proposed usage and system configuration differs from person to person.

From the current author's point of view, if the dataset is relatively small, being tables of less than 1 million rows, and less than 1000 tables in a given database, then mSQL is a perfectly acceptable solution to your problem. This database is extremely cheap, is wonderfully robust and has excellent support. More information is available on the Hughes Technology WWW site at:

    http://www.hughes.com.au

You may also wish to look at MySQL which is a more powerful database engine that has a similar feel to mSQL.

    http://www.tcx.se

If the dataset is larger than 1 million row tables or 1000 tables, or if you have either more money, or larger machines, I would recommend Oracle RDBMS. Oracle's WWW site is an excellent source of more information.

    http://www.oracle.com

Informix is another high-end RDBMS that is worth considering. There are several differences between Oracle and Informix which are too complex for this document to detail. Information on Informix can be found on their WWW site at:

    http://www.informix.com

In the case of WWW fronted applications, mSQL may be a better option due to slow connection times between a CGI script and the Oracle RDBMS and also the amount of resource each Oracle connection will consume. mSQL is lighter resource-wise and faster.

These views are not necessarily representative of anyone else's opinions, and do not reflect any corporate sponsorship or views. They are provided as-is.

3.8 Is <insert feature here> supported in DBI?

Given that we're making the assumption that the feature you have requested is a non-standard database-specific feature, then the answer will be no.

DBI reflects a generic API that will work for most databases, and has no database-specific functionality.

However, driver authors may, if they so desire, include hooks to database-specific functionality through the func() method defined in the DBI API. Script developers should note that use of functionality provided via the func() methods is very unlikely to be portable across databases.

Programming Questions

4.1 Is DBI any use for CGI programming?

In a word, yes! DBI is hugely useful for CGI programming! In fact, I would tentatively say that CGI programming is one of two top uses for DBI.

DBI confers the ability to CGI programmers to power WWW-fronted databases to their users, which provides users with vast quantities of ordered data to play with. DBI also provides the possibility that, if a site is receiving far too much traffic than their database server can cope with, they can upgrade the database server behind the scenes with no alterations to the CGI scripts.

4.2 How do I get faster connection times with DBD::Oracle and CGI?

    Contributed by John D. Groenveld

The Apache httpd maintains a pool of httpd children to service client requests.

Using the Apache mod_perl module by Doug MacEachern, the perl interpreter is embedded with the httpd children. The CGI, DBI, and your other favorite modules can be loaded at the startup of each child. These modules will not be reloaded unless changed on disk.

For more information on Apache, see the Apache Project's WWW site:

    http://www.apache.org

The mod_perl module can be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Apache

4.3 How do I get persistent connections with DBI and CGI?

    Contributed by John D. Groenveld

Using Edmund Mergl's Apache::DBI module, database logins are stored in a hash with each of these httpd child. If your application is based on a single database user, this connection can be started with each child. Currently, database connections cannot be shared between httpd children.

Apache::DBI can be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Apache::DBI

4.4 ``When I run a perl script from the command line, it works, but, when I run it under the httpd, it fails!'' Why?

Basically, a good chance this is occurring is due to the fact that the user that you ran it from the command line as has a correctly configured set of environment variables, in the case of DBD::Oracle, variables like ORACLE_HOME, ORACLE_SID or TWO_TASK.

The httpd process usually runs under the user id of nobody, which implies there is no configured environment. Any scripts attempting to execute in this situation will correctly fail.

One way to solve this problem is to set the environment for your database in a BEGIN { } block at the top of your script. Another technique is to configure your WWW server to pass-through certain environment variables to your CGI scripts.

Similarly, you should check your httpd error logfile for any clues, as well as the ``Idiot's Guide To Solving Perl / CGI Problems'' and ``Perl CGI Programming FAQ'' for further information. It is unlikely the problem is DBI-related.

The ``Idiot's Guide To Solving Perl / CGI Problems'' can be located at:

    http://www.perl.com/perl/faq/index.html

as can the ``Perl CGI Programming FAQ''. Read BOTH these documents carefully!

4.5 How do I get the number of rows returned from a SELECT statement?

Count them. Read the DBI docs for the rows() method.

Miscellaneous Questions

5.1 Can I do multi-threading with DBI?

Perl version 5.005 and later can be built to support multi-threading. The DBI, as of version 1.02, does not yet support multi-threading so it would be unsafe to let more than one thread enter the DBI at the same time.

It is expected that some future version of the DBI will at least be thread-safe (but not thread-hot) by automatically blocking threads intering the DBI while it's already in use.

For some OCI example code for Oracle that has multi-threaded SELECT statements, see:

    http://www.symbolstone.org/technology/oracle/oci/orathreads.tar.gz

5.2 How do I handle BLOB data with DBI?

Handling BLOB data with the DBI is very straight-forward. BLOB columns are specified in a SELECT statement as per normal columns. However, you also need to specify a maximum BLOB size that the <I>database handle</I> can fetch using the LongReadLen attribute.

For example:

    ### $dbh is a connected database handle
    $sth = $dbh->prepare( "SELECT blob_column FROM blobby_table" );
    $sth->execute;

would fail.

    ### $dbh is a connected database handle
    ### Set the maximum BLOB size...
    $dbh->{LongReadLen} = 16384;        ### 16Kb...Not much of a BLOB!

    $sth = $dbh->prepare( "..." );

would succeed <I>provided no column values were larger than the specified value</I>.

If the BLOB data is longer than the value of LongReadLen, then an error will occur. However, the DBI provides an additional piece of functionality that will automatically truncate the fetched BLOB to the size of LongReadLen if it is longer. This does not cause an error to occur, but may make your fetched BLOB data useless.

This behaviour is regulated by the LongTruncOk attribute which is defaultly set to a false value ( thus making overlong BLOB fetches fail ).

    ### Set BLOB handling such that it's 16Kb and can be truncated
    $dbh->{LongReadLen} = 16384;
    $dbh->{LongTruncOk} = 1;

Truncation of BLOB data may not be a big deal in cases where the BLOB contains run-length encoded data, but data containing checksums at the end, for example, a ZIP file, would be rendered useless.

5.3 How can I invoke stored procedures with DBI?

The DBI does not define a database-independent way of calling stored procedures.

However, most database that support them also provide a way to call them from SQL statements - and the DBI certainly supports that.

So, assuming that you have created a stored procedure within the target database, eg, an Oracle database, you can use $dbh->do() to immediately execute the procedure. For example,

    $dbh->do( "BEGIN someProcedure; END;" );   # Oracle-specific

You should also be able to prepare and execute, which is the recommended way if you'll be calling the procedure often.

5.4 How can I get return values from stored procedures with DBI?

    Contributed by Jeff Urlwin
    $sth = $dbh->prepare( "BEGIN foo(:1, :2, :3); END;" );
    $sth->bind_param(1, $a);
    $sth->bind_param_inout(2, \$path, 2000);
    $sth->bind_param_inout(3, \$success, 2000);
    $sth->execute;

Remember to perform error checking, though! ( Or use the RaiseError attribute ).

5.5 How can I create or drop a database with DBI?

Database creation and deletion are concepts that are entirely too abstract to be adequately supported by DBI. For example, Oracle does not support the concept of dropping a database at all! Also, in Oracle, the database server essentially is the database, whereas in mSQL, the server process runs happily without any databases created in it. The problem is too disparate to attack in a worthwhile way.

Some drivers, therefore, support database creation and deletion through the private func() methods. You should check the documentation for the drivers you are using to see if they support this mechanism.

5.6 How can I commit or rollback a statement with DBI?

See the commit() and rollback() methods in the DBI Specification.

Chapter 6 of "Programming the Perl DBI" discusses transaction handling within the context of DBI in more detail.

5.7 How are NULL values handled by DBI?

NULL values in DBI are specified to be treated as the value undef. NULLs can be inserted into databases as NULL, for example:

    $rv = $dbh->do( "INSERT INTO table VALUES( NULL )" );

but when queried back, the NULLs should be tested against undef. This is standard across all drivers.

5.8 What are these func() methods all about?

The func() method is defined within DBI as being an entry point for database-specific functionality, eg, the ability to create or drop databases. Invoking these driver-specific methods is simple, for example, to invoke a createDatabase method that has one argument, we would write:

    $rv =$dbh->func( 'argument', 'createDatabase' );

Software developers should note that the func() methods are non-portable between databases.

5.9 Is DBI Year 2000 Compliant?

DBI has no knowledge of understanding of what dates are. Therefore, DBI itself does not have a Year 2000 problem. Individual drivers may use date handling code internally and therefore be potentially susceptible to the Year 2000 problem, but this is unlikely.

You may also wish to read the ``Does Perl have a Year 2000 problem?'' section of the Perl FAQ at:

    http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html

Support and Training

The Perl5 Database Interface is FREE software. IT COMES WITHOUT WARRANTY OF ANY KIND. See the DBI README for more details.

However, some organizations are providing either technical support or training programs on DBI. The present author has no knowledge as to the quality of these services. The links are included for reference purposes only and should not be regarded as recommendations in any way. Caveat emptor.

Commercial Support

The Perl Clinic

The Perl Clinic provides commercial support for Perl and Perl related problems, including the DBI and its drivers. Support is provided by the company with whom Tim Bunce, author of DBI and DBD::Oracle, works and ActiveState. For more information on their services, please see:

    http://www.perlclinic.com

Training

Westlake Solutions

A hands-on class for experienced Perl CGI developers that teaches how to write database-connected CGI scripts using Perl and DBI.pm. This course, along with four other courses on CGI scripting with Perl, is taught in Washington, DC; Arlington, Virginia; and on-site worldwide upon request.

See:

    http://www.westlake.com/training

for more details.

Other References

In this section, we present some miscellaneous WWW links that may be of some interest to DBI users. These are not verified and may result in unknown sites or missing documents.

    http://www-ccs.cs.umass.edu/db.html
    http://www.odmg.org/odmg93/updates_dbarry.html
    http://www.jcc.com/sql_stnd.html

AUTHOR

Alligator Descartes <http://www.symbolstone.org/descarte/contact.html>. Portions are Copyright their original stated authors.

COPYRIGHT

This document is Copyright (c)1994-2000 Alligator Descartes, with portions Copyright (c)1994-2000 their original authors. This module is released under the 'Artistic' license which you can find in the perl distribution.

This document is Copyright (c)1997-2000 Alligator Descartes. All rights reserved. Permission to distribute this document, in full or in part, via email, Usenet, ftp archives or http is granted providing that no charges are involved, reasonable attempt is made to use the most current version and all credits and copyright notices are retained ( the AUTHOR and COPYRIGHT sections ). Requests for other distribution rights, including incorporation into commercial products, such as books, magazine articles or CD-ROMs should be made to Alligator Descartes <http://www.symbolstone.org/descarte/contact.html>.


DBI::Gofer::Execute - Executes Gofer requests and returns Gofer responses

  • CONFIGURATION
    • check_request_sub
    • forced_connect_dsn
    • default_connect_dsn
    • forced_connect_attributes
    • default_connect_attributes
    • max_cached_dbh_per_drh
    • max_cached_sth_per_dbh
    • forced_single_resultset
    • forced_response_attributes
    • track_recent
    • forced_gofer_random
  • DRIVER-SPECIFIC ISSUES
  • TESTING
    • DBI_GOFER_RANDOM
  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Execute - Executes Gofer requests and returns Gofer responses

SYNOPSIS

  $executor = DBI::Gofer::Execute->new( { ...config... });

  $response = $executor->execute_request( $request );

DESCRIPTION

Accepts a DBI::Gofer::Request object, executes the requested DBI method calls, and returns a DBI::Gofer::Response object.

Any error, including any internal 'fatal' errors are caught and converted into a DBI::Gofer::Response object.

This module is usually invoked by a 'server-side' Gofer transport module. They usually have names in the "DBI::Gofer::Transport::*" namespace. Examples include: the DBI::Gofer::Transport::stream manpage and the DBI::Gofer::Transport::mod_perl manpage.

CONFIGURATION

check_request_sub

If defined, it must be a reference to a subroutine that will 'check' the request. It is pass the request object and the executor as its only arguments.

The subroutine can either return the original request object or die with a suitable error message (which will be turned into a Gofer response).

It can also construct and return a new request that should be executed instead of the original request.

forced_connect_dsn

If set, this DSN is always used instead of the one in the request.

default_connect_dsn

If set, this DSN is used if forced_connect_dsn is not set and the request does not contain a DSN itself.

forced_connect_attributes

A reference to a hash of connect() attributes. Individual attributes in forced_connect_attributes will take precedence over corresponding attributes in the request.

default_connect_attributes

A reference to a hash of connect() attributes. Individual attributes in the request take precedence over corresponding attributes in default_connect_attributes.

max_cached_dbh_per_drh

If set, the loaded drivers will be checked to ensure they don't have more than this number of cached connections. There is no default value. This limit is not enforced for every request.

max_cached_sth_per_dbh

If set, all the cached statement handles will be cleared once the number of cached statement handles rises above this limit. The default is 1000.

forced_single_resultset

If true, then only the first result set will be fetched and returned in the response.

forced_response_attributes

A reference to a data structure that can specify extra attributes to be returned in responses.

  forced_response_attributes => {
      DriverName => {
          dbh => [ qw(dbh_attrib_name) ],
          sth => [ qw(sth_attrib_name) ],
      },
  },

This can be useful in cases where the driver has not implemented the private_attribute_info() method and DBI::Gofer::Execute's own fallback list of private attributes doesn't include the driver or attributes you need.

track_recent

If set, specifies the number of recent requests and responses that should be kept by the update_stats() method for diagnostics. See the DBI::Gofer::Transport::mod_perl manpage.

Note that this setting can significantly increase memory use. Use with caution.

forced_gofer_random

Enable forced random failures and/or delays for testing. See DBI_GOFER_RANDOM below.

DRIVER-SPECIFIC ISSUES

Gofer needs to know about any driver-private attributes that should have their values sent back to the client.

If the driver doesn't support private_attribute_info() method, and very few do, then the module fallsback to using some hard-coded details, if available, for the driver being used. Currently hard-coded details are available for the mysql, Pg, Sybase, and SQLite drivers.

TESTING

DBD::Gofer, DBD::Execute and related packages are well tested by executing the DBI test suite with DBI_AUTOPROXY configured to route all DBI calls via DBD::Gofer.

Because Gofer includes timeout and 'retry on error' mechanisms there is a need for some way to trigger delays and/or errors. This can be done via the forced_gofer_random configuration item, or else the DBI_GOFER_RANDOM environment variable.

DBI_GOFER_RANDOM

The value of the forced_gofer_random configuration item (or else the DBI_GOFER_RANDOM environment variable) is treated as a series of tokens separated by commas.

The tokens can be one of three types:

fail=R%

Set the current failure rate to R where R is a percentage. The value R can be floating point, e.g., fail=0.05%. Negative values for R have special meaning, see below.

delayN=R%

Set the current random delay rate to R where R is a percentage, and set the current delay duration to N seconds. The values of R and N can be floating point, e.g., delay120=0.1%. Negative values for R have special meaning, see below.

methodname

Applies the current current random failure rate and random delay rate and duration to the named method. If neither a fail nor delay have been set yet then a warning is generated.

For example:

  $executor = DBI::Gofer::Execute->new( {
    forced_gofer_random => "fail=0.01%,do,delay60=1%,execute",
  });

will cause the do() method to fail for 0.01% of calls, and the execute() method to fail 0.01% of calls and be delayed by 60 seconds on 1% of calls.

If the percentage value (R) is negative then instead of the failures being triggered randomly (via the rand() function) they are triggered via a sequence number. In other words "fail=-20%" will mean every fifth call will fail. Each method has a distinct sequence number.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Gofer::Request - Encapsulate a request from DBD::Gofer to DBI::Gofer::Execute

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Request - Encapsulate a request from DBD::Gofer to DBI::Gofer::Execute

DESCRIPTION

This is an internal class.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Gofer::Response - Encapsulate a response from DBI::Gofer::Execute to DBD::Gofer

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Response - Encapsulate a response from DBI::Gofer::Execute to DBD::Gofer

DESCRIPTION

This is an internal class.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Gofer::Transport::Base - Base class for Gofer transports

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Transport::Base - Base class for Gofer transports

DESCRIPTION

This is the base class for server-side Gofer transports.

It's also the base class for the client-side base class the DBD::Gofer::Transport::Base manpage.

This is an internal class.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Gofer::Transport::pipeone - DBD::Gofer server-side transport for pipeone

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Transport::pipeone - DBD::Gofer server-side transport for pipeone

SYNOPSIS

See the DBD::Gofer::Transport::pipeone manpage.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Gofer::Transport::stream - DBD::Gofer server-side transport for stream

  • AUTHOR
  • LICENCE AND COPYRIGHT

NAME

DBI::Gofer::Transport::stream - DBD::Gofer server-side transport for stream

SYNOPSIS

See the DBD::Gofer::Transport::stream manpage.

AUTHOR

Tim Bunce, http://www.linkedin.com/in/timbunce

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.


DBI::Profile - Performance profiling and benchmarking for the DBI

  • OVERVIEW
  • ENABLING A PROFILE
  • THE PROFILE OBJECT
    • Data
    • Path
      • Special Constant
      • Code Reference
      • Subroutine Specifier
      • Attribute Specifier
      • Reference to a Scalar
      • Other Values
  • REPORTING
    • Report Format
    • Report Destination
  • CHILD HANDLES
  • PROFILE OBJECT METHODS
    • format
    • as_node_path_list
    • as_text
  • CUSTOM DATA MANIPULATION
    • dbi_profile_merge_nodes
  • CUSTOM DATA COLLECTION
    • Using The Path Attribute
    • Adding Your Own Samples
  • SUBCLASSING
  • CAVEATS

NAME

DBI::Profile - Performance profiling and benchmarking for the DBI

SYNOPSIS

The easiest way to enable DBI profiling is to set the DBI_PROFILE environment variable to 2 and then run your code as usual:

  DBI_PROFILE=2 prog.pl

This will profile your program and then output a textual summary grouped by query when the program exits. You can also enable profiling by setting the Profile attribute of any DBI handle:

  $dbh->{Profile} = 2;

Then the summary will be printed when the handle is destroyed.

Many other values apart from are possible - see ENABLING A PROFILE below.

DESCRIPTION

The DBI::Profile module provides a simple interface to collect and report performance and benchmarking data from the DBI.

For a more elaborate interface, suitable for larger programs, see DBI::ProfileDumper and dbiprof. For Apache/mod_perl applications see DBI::ProfileDumper::Apache.

OVERVIEW

Performance data collection for the DBI is built around several concepts which are important to understand clearly.

Method Dispatch

Every method call on a DBI handle passes through a single 'dispatch' function which manages all the common aspects of DBI method calls, such as handling the RaiseError attribute.

Data Collection

If profiling is enabled for a handle then the dispatch code takes a high-resolution timestamp soon after it is entered. Then, after calling the appropriate method and just before returning, it takes another high-resolution timestamp and calls a function to record the information. That function is passed the two timestamps plus the DBI handle and the name of the method that was called. That data about a single DBI method call is called a profile sample.

Data Filtering

If the method call was invoked by the DBI or by a driver then the call is ignored for profiling because the time spent will be accounted for by the original 'outermost' call for your code.

For example, the calls that the selectrow_arrayref() method makes to prepare() and execute() etc. are not counted individually because the time spent in those methods is going to be allocated to the selectrow_arrayref() method when it returns. If this was not done then it would be very easy to double count time spent inside the DBI.

Data Storage Tree

The profile data is accumulated as 'leaves on a tree'. The 'path' through the branches of the tree to a particular leaf is determined dynamically for each sample. This is a key feature of DBI profiliing.

For each profiled method call the DBI walks along the Path and uses each value in the Path to step into and grow the Data tree.

For example, if the Path is

  [ 'foo', 'bar', 'baz' ]

then the new profile sample data will be merged into the tree at

  $h->{Profile}->{Data}->{foo}->{bar}->{baz}

But it's not very useful to merge all the call data into one leaf node (except to get an overall 'time spent inside the DBI' total). It's more common to want the Path to include dynamic values such as the current statement text and/or the name of the method called to show what the time spent inside the DBI was for.

The Path can contain some 'magic cookie' values that are automatically replaced by corresponding dynamic values when they're used. These magic cookies always start with a punctuation character.

For example a value of '!MethodName' in the Path causes the corresponding entry in the Data to be the name of the method that was called. For example, if the Path was:

  [ 'foo', '!MethodName', 'bar' ]

and the selectall_arrayref() method was called, then the profile sample data for that call will be merged into the tree at:

  $h->{Profile}->{Data}->{foo}->{selectall_arrayref}->{bar}
Profile Data

Profile data is stored at the 'leaves' of the tree as references to an array of numeric values. For example:

  [
    106,                  # 0: count of samples at this node
    0.0312958955764771,   # 1: total duration
    0.000490069389343262, # 2: first duration
    0.000176072120666504, # 3: shortest duration
    0.00140702724456787,  # 4: longest duration
    1023115819.83019,     # 5: time of first sample
    1023115819.86576,     # 6: time of last sample
  ]

After the first sample, later samples always update elements 0, 1, and 6, and may update 3 or 4 depending on the duration of the sampled call.

ENABLING A PROFILE

Profiling is enabled for a handle by assigning to the Profile attribute. For example:

  $h->{Profile} = DBI::Profile->new();

The Profile attribute holds a blessed reference to a hash object that contains the profile data and attributes relating to it.

The class the Profile object is blessed into is expected to provide at least a DESTROY method which will dump the profile data to the DBI trace file handle (STDERR by default).

All these examples have the same effect as each other:

  $h->{Profile} = 0;
  $h->{Profile} = "/DBI::Profile";
  $h->{Profile} = DBI::Profile->new();
  $h->{Profile} = {};
  $h->{Profile} = { Path => [] };

Similarly, these examples have the same effect as each other:

  $h->{Profile} = 6;
  $h->{Profile} = "6/DBI::Profile";
  $h->{Profile} = "!Statement:!MethodName/DBI::Profile";
  $h->{Profile} = { Path => [ '!Statement', '!MethodName' ] };

If a non-blessed hash reference is given then the DBI::Profile module is automatically require'd and the reference is blessed into that class.

If a string is given then it is processed like this:

    ($path, $module, $args) = split /\//, $string, 3
    @path = split /:/, $path
    @args = split /:/, $args
    eval "require $module" if $module
    $module ||= "DBI::Profile"
    $module->new( Path => \@Path, @args )

So the first value is used to select the Path to be used (see below). The second value, if present, is used as the name of a module which will be loaded and it's new method called. If not present it defaults to DBI::Profile. Any other values are passed as arguments to the new method. For example: "2/DBIx::OtherProfile/Foo:42".

Numbers can be used as a shorthand way to enable common Path values. The simplest way to explain how the values are interpreted is to show the code:

    push @Path, "DBI"           if $path_elem & 0x01;
    push @Path, "!Statement"    if $path_elem & 0x02;
    push @Path, "!MethodName"   if $path_elem & 0x04;
    push @Path, "!MethodClass"  if $path_elem & 0x08;
    push @Path, "!Caller2"      if $path_elem & 0x10;

So "2" is the same as "!Statement" and "6" (2+4) is the same as "!Statement:!Method". Those are the two most commonly used values. Using a negative number will reverse the path. Thus "-6" will group by method name then statement.

The spliting and parsing of string values assigned to the Profile attribute may seem a little odd, but there's a good reason for it. Remember that attributes can be embedded in the Data Source Name string which can be passed in to a script as a parameter. For example:

    dbi:DriverName(Profile=>2):dbname
    dbi:DriverName(Profile=>{Username}:!Statement/MyProfiler/Foo:42):dbname

And also, if the DBI_PROFILE environment variable is set then The DBI arranges for every driver handle to share the same profile object. When perl exits a single profile summary will be generated that reflects (as nearly as practical) the total use of the DBI by the application.

THE PROFILE OBJECT

The DBI core expects the Profile attribute value to be a hash reference and if the following values don't exist it will create them as needed:

Data

A reference to a hash containing the collected profile data.

Path

The Path value is a reference to an array. Each element controls the value to use at the corresponding level of the profile Data tree.

If the value of Path is anything other than an array reference, it is treated as if it was:

        [ '!Statement' ]

The elements of Path array can be one of the following types:

Special Constant

!Statement

Use the current Statement text. Typically that's the value of the Statement attribute for the handle the method was called with. Some methods, like commit() and rollback(), are unrelated to a particular statement. For those methods !Statement records an empty string.

For statement handles this is always simply the string that was given to prepare() when the handle was created. For database handles this is the statement that was last prepared or executed on that database handle. That can lead to a little 'fuzzyness' because, for example, calls to the quote() method to build a new statement will typically be associated with the previous statement. In practice this isn't a significant issue and the dynamic Path mechanism can be used to setup your own rules.

!MethodName

Use the name of the DBI method that the profile sample relates to.

!MethodClass

Use the fully qualified name of the DBI method, including the package, that the profile sample relates to. This shows you where the method was implemented. For example:

  'DBD::_::db::selectrow_arrayref' =>
      0.022902s
  'DBD::mysql::db::selectrow_arrayref' =>
      2.244521s / 99 = 0.022445s avg (first 0.022813s, min 0.022051s, max 0.028932s)

The "DBD::_::db::selectrow_arrayref" shows that the driver has inherited the selectrow_arrayref method provided by the DBI.

But you'll note that there is only one call to DBD::_::db::selectrow_arrayref but another 99 to DBD::mysql::db::selectrow_arrayref. Currently the first call Pern't record the true location. That may change.

!Caller

Use a string showing the filename and line number of the code calling the method.

!Caller2

Use a string showing the filename and line number of the code calling the method, as for !Caller, but also include filename and line number of the code that called that. Calls from DBI:: and DBD:: packages are skipped.

!File

Same as !Caller above except that only the filename is included, not the line number.

!File2

Same as !Caller2 above except that only the filenames are included, not the line number.

!Time

Use the current value of time(). Rarely used. See the more useful !Time~N below.

!Time~N

Where N is an integer. Use the current value of time() but with reduced precision. The value used is determined in this way:

    int( time() / N ) * N

This is a useful way to segregate a profile into time slots. For example:

    [ '!Time~60', '!Statement' ]

Code Reference

The subroutine is passed the handle it was called on and the DBI method name. The current Statement is in $_. The statement string should not be modified, so most subs start with local $_ = $_;.

The list of values it returns is used at that point in the Profile Path.

The sub can 'veto' (reject) a profile sample by including a reference to undef in the returned list. That can be useful when you want to only profile statements that match a certain pattern, or only profile certain methods.

Subroutine Specifier

A Path element that begins with '&' is treated as the name of a subroutine in the DBI::ProfileSubs namespace and replaced with the corresponding code reference.

Currently this only works when the Path is specified by the DBI_PROFILE environment variable.

Also, currently, the only subroutine in the DBI::ProfileSubs namespace is '&norm_std_n3'. That's a very handy subroutine when profiling code that doesn't use placeholders. See the DBI::ProfileSubs manpage for more information.

Attribute Specifier

A string enclosed in braces, such as '{Username}', specifies that the current value of the corresponding database handle attribute should be used at that point in the Path.

Reference to a Scalar

Specifies that the current value of the referenced scalar be used at that point in the Path. This provides an efficient way to get 'contextual' values into your profile.

Other Values

Any other values are stringified and used literally.

(References, and values that begin with punctuation characters are reserved.)

REPORTING

Report Format

The current accumulated profile data can be formatted and output using

    print $h->{Profile}->format;

To discard the profile data and start collecting fresh data you can do:

    $h->{Profile}->{Data} = undef;

The default results format looks like this:

  DBI::Profile: 0.001015s 42.7% (5 calls) programname @ YYYY-MM-DD HH:MM:SS
  '' =>
      0.000024s / 2 = 0.000012s avg (first 0.000015s, min 0.000009s, max 0.000015s)
  'SELECT mode,size,name FROM table' =>
      0.000991s / 3 = 0.000330s avg (first 0.000678s, min 0.000009s, max 0.000678s)

Which shows the total time spent inside the DBI, with a count of the total number of method calls and the name of the script being run, then a formated version of the profile data tree.

If the results are being formated when the perl process is exiting (which is usually the case when the DBI_PROFILE environment variable is used) then the percentage of time the process spent inside the DBI is also shown. If the process is not exiting then the percentage is calculated using the time between the first and last call to the DBI.

In the example above the paths in the tree are only one level deep and use the Statement text as the value (that's the default behaviour).

The merged profile data at the 'leaves' of the tree are presented as total time spent, count, average time spent (which is simply total time divided by the count), then the time spent on the first call, the time spent on the fastest call, and finally the time spent on the slowest call.

The 'avg', 'first', 'min' and 'max' times are not particularly useful when the profile data path only contains the statement text. Here's an extract of a more detailed example using both statement text and method name in the path:

  'SELECT mode,size,name FROM table' =>
      'FETCH' =>
          0.000076s
      'fetchrow_hashref' =>
          0.036203s / 108 = 0.000335s avg (first 0.000490s, min 0.000152s, max 0.002786s)

Here you can see the 'avg', 'first', 'min' and 'max' for the 108 calls to fetchrow_hashref() become rather more interesting. Also the data for FETCH just shows a time value because it was only called once.

Currently the profile data is output sorted by branch names. That may change in a later version so the leaf nodes are sorted by total time per leaf node.

Report Destination

The default method of reporting is for the DESTROY method of the Profile object to format the results and write them using:

    DBI->trace_msg($results, 0);  # see $ON_DESTROY_DUMP below

to write them to the DBI trace() filehandle (which defaults to STDERR). To direct the DBI trace filehandle to write to a file without enabling tracing the trace() method can be called with a trace level of 0. For example:

    DBI->trace(0, $filename);

The same effect can be achieved without changing the code by setting the DBI_TRACE environment variable to 0=filename.

The $DBI::Profile::ON_DESTROY_DUMP variable holds a code ref that's called to perform the output of the formatted results. The default value is:

  $ON_DESTROY_DUMP = sub { DBI->trace_msg($results, 0) };

Apart from making it easy to send the dump elsewhere, it can also be useful as a simple way to disable dumping results.

CHILD HANDLES

Child handles inherit a reference to the Profile attribute value of their parent. So if profiling is enabled for a database handle then by default the statement handles created from it all contribute to the same merged profile data tree.

PROFILE OBJECT METHODS

format

See REPORTING.

as_node_path_list

  @ary = $dbh->{Profile}->as_node_path_list();
  @ary = $dbh->{Profile}->as_node_path_list($node, $path);

Returns the collected data ($dbh->{Profile}{Data}) restructured into a list of array refs, one for each leaf node in the Data tree. This 'flat' structure is often much simpler for applications to work with.

The first element of each array ref is a reference to the leaf node. The remaining elements are the 'path' through the data tree to that node.

For example, given a data tree like this:

    {key1a}{key2a}[node1]
    {key1a}{key2b}[node2]
    {key1b}{key2a}{key3a}[node3]

The as_node_path_list() method will return this list:

    [ [node1], 'key1a', 'key2a' ]
    [ [node2], 'key1a', 'key2b' ]
    [ [node3], 'key1b', 'key2a', 'key3a' ]

The nodes are ordered by key, depth-first.

The $node argument can be used to focus on a sub-tree. If not specified it defaults to $dbh->{Profile}{Data}.

The $path argument can be used to specify a list of path elements that will be added to each element of the returned list. If not specified it defaults to a a ref to an empty array.

as_text

  @txt = $dbh->{Profile}->as_text();
  $txt = $dbh->{Profile}->as_text({
      node      => undef,
      path      => [],
      separator => " > ",
      format    => '%1$s: %11$fs / %10$d = %2$fs avg (first %12$fs, min %13$fs, max %14$fs)'."\n";
      sortsub   => sub { ... },
  );

Returns the collected data ($dbh->{Profile}{Data}) reformatted into a list of formatted strings. In scalar context the list is returned as a single contatenated string.

A hashref can be used to pass in arguments, the default values are shown in the example above.

The node and <path> arguments are passed to as_node_path_list().

The separator argument is used to join the elemets of the path for each leaf node.

The sortsub argument is used to pass in a ref to a sub that will order the list. The subroutine will be passed a reference to the array returned by as_node_path_list().

The format argument is a sprintf format string that specifies the format to use for each leaf node. It uses the explicit format parameter index mechanism to specify which of the arguments should appear where in the string. The arguments to sprintf are:

     1:  path to node, joined with the separator
     2:  average duration (total/count)
         (3 thru 9 are currently unused)
    10:  count
    11:  total duration
    12:  first_duration
    13:  smallest duration
    14:  largest duration
    15:  time of first call
    16:  time of first call

CUSTOM DATA MANIPULATION

Recall that $h-{Profile}->{Data}> is a reference to the collected data. Either to a 'leaf' array (when the Path is empty, i.e., DBI_PROFILE env var is 1), or a reference to hash containing values that are either further hash references or leaf array references.

Sometimes it's useful to be able to summarise some or all of the collected data. The dbi_profile_merge_nodes() function can be used to merge leaf node values.

dbi_profile_merge_nodes

  use DBI qw(dbi_profile_merge_nodes);

  $time_in_dbi = dbi_profile_merge_nodes(my $totals=[], @$leaves);

Merges profile data node. Given a reference to a destination array, and zero or more references to profile data, merges the profile data into the destination array. For example:

  $time_in_dbi = dbi_profile_merge_nodes(
      my $totals=[],
      [ 10, 0.51, 0.11, 0.01, 0.22, 1023110000, 1023110010 ],
      [ 15, 0.42, 0.12, 0.02, 0.23, 1023110005, 1023110009 ],
  );

$totals will then contain

  [ 25, 0.93, 0.11, 0.01, 0.23, 1023110000, 1023110010 ]

and $time_in_dbi will be 0.93;

The second argument need not be just leaf nodes. If given a reference to a hash then the hash is recursively searched for for leaf nodes and all those found are merged.

For example, to get the time spent 'inside' the DBI during an http request, your logging code run at the end of the request (i.e. mod_perl LogHandler) could use:

  my $time_in_dbi = 0;
  if (my $Profile = $dbh->{Profile}) { # if DBI profiling is enabled
      $time_in_dbi = dbi_profile_merge_nodes(my $total=[], $Profile->{Data});
      $Profile->{Data} = {}; # reset the profile data
  }

If profiling has been enabled then $time_in_dbi will hold the time spent inside the DBI for that handle (and any other handles that share the same profile data) since the last request.

Prior to DBI 1.56 the dbi_profile_merge_nodes() function was called dbi_profile_merge(). That name still exists as an alias.

CUSTOM DATA COLLECTION

Using The Path Attribute

  XXX example to be added later using a selectall_arrayref call
  XXX nested inside a fetch loop where the first column of the
  XXX outer loop is bound to the profile Path using
  XXX bind_column(1, \${ $dbh->{Profile}->{Path}->[0] })
  XXX so you end up with separate profiles for each loop
  XXX (patches welcome to add this to the docs :)

Adding Your Own Samples

The dbi_profile() function can be used to add extra sample data into the profile data tree. For example:

    use DBI;
    use DBI::Profile (dbi_profile dbi_time);

    my $t1 = dbi_time(); # floating point high-resolution time

    ... execute code you want to profile here ...
    my $t2 = dbi_time();
    dbi_profile($h, $statement, $method, $t1, $t2);

The $h parameter is the handle the extra profile sample should be associated with. The $statement parameter is the string to use where the Path specifies !Statement. If $statement is undef then $h->{Statement} will be used. Similarly $method is the string to use if the Path specifies !MethodName. There is no default value for $method.

The $h->{Profile}{Path} attribute is processed by dbi_profile() in the usual way.

It is recommended that you keep these extra data samples separate from the DBI profile data samples by using values for $statement and $method that are distinct from any that are likely to appear in the profile data normally.

SUBCLASSING

Alternate profile modules must subclass DBI::Profile to help ensure they work with future versions of the DBI.

CAVEATS

Applications which generate many different statement strings (typically because they don't use placeholders) and profile with !Statement in the Path (the default) will consume memory in the Profile Data structure for each statement. Use a code ref in the Path to return an edited (simplified) form of the statement.

If a method throws an exception itself (not via RaiseError) then it won't be counted in the profile.

If a HandleError subroutine throws an exception (rather than returning 0 and letting RaiseError do it) then the method call won't be counted in the profile.

Time spent in DESTROY is added to the profile of the parent handle.

Time spent in DBI->*() methods is not counted. The time spent in the driver connect method, $drh->connect(), when it's called by DBI->connect is counted if the DBI_PROFILE environment variable is set.

Time spent fetching tied variables, $DBI::errstr, is counted.

Time spent in FETCH for $h->{Profile} is not counted, so getting the profile data doesn't alter it.

DBI::PurePerl does not support profiling (though it could in theory).

A few platforms don't support the gettimeofday() high resolution time function used by the DBI (and available via the dbi_time() function). In which case you'll get integer resolution time which is mostly useless.

On Windows platforms the dbi_time() function is limited to millisecond resolution. Which isn't sufficiently fine for our needs, but still much better than integer resolution. This limited resolution means that fast method calls will often register as taking 0 time. And timings in general will have much more 'jitter' depending on where within the 'current millisecond' the start and and timing was taken.

This documentation could be more clear. Probably needs to be reordered to start with several examples and build from there. Trying to explain the concepts first seems painful and to lead to just as many forward references. (Patches welcome!)


DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

  • METHODS
    • $prof = DBI::ProfileData->new(File => "dbi.prof")
    • $prof = DBI::ProfileData->new(File => "dbi.prof", Filter => sub { ... })
    • $prof = DBI::ProfileData->new(Files => [ "dbi.prof.1", "dbi.prof.2" ])
      • Files
      • File
      • DeleteFiles
      • Filter
    • $copy = $prof->clone();
    • $header = $prof->header();
    • $nodes = $prof->nodes()
    • $count = $prof->count()
    • $prof->sort(field => "field")
    • $prof->sort(field => "field", reverse => 1)
    • $count = $prof->exclude(key2 => "disconnect")
    • $count = $prof->exclude(key2 => "disconnect", case_sensitive => 1)
    • $count = $prof->exclude(key1 => qr/^SELECT/i)
    • $count = $prof->match(key2 => "disconnect")
    • $count = $prof->match(key2 => "disconnect", case_sensitive => 1)
    • $count = $prof->match(key1 => qr/^SELECT/i)
    • $Data = $prof->Data()
    • $text = $prof->format($nodes->[0])
    • $text = $prof->report(number => 10)
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

SYNOPSIS

The easiest way to use this module is through the dbiprof frontend (see the dbiprof manpage for details):

  dbiprof --number 15 --sort count

This module can also be used to roll your own profile analysis:

  # load data from dbi.prof
  $prof = DBI::ProfileData->new(File => "dbi.prof");

  # get a count of the records (unique paths) in the data set
  $count = $prof->count();

  # sort by longest overall time
  $prof->sort(field => "longest");

  # sort by longest overall time, least to greatest
  $prof->sort(field => "longest", reverse => 1);

  # exclude records with key2 eq 'disconnect'
  $prof->exclude(key2 => 'disconnect');

  # exclude records with key1 matching /^UPDATE/i
  $prof->exclude(key1 => qr/^UPDATE/i);

  # remove all records except those where key1 matches /^SELECT/i
  $prof->match(key1 => qr/^SELECT/i);

  # produce a formatted report with the given number of items
  $report = $prof->report(number => 10);

  # clone the profile data set
  $clone = $prof->clone();

  # get access to hash of header values
  $header = $prof->header();

  # get access to sorted array of nodes
  $nodes = $prof->nodes();

  # format a single node in the same style as report()
  $text = $prof->format($nodes->[0]);

  # get access to Data hash in DBI::Profile format
  $Data = $prof->Data();

DESCRIPTION

This module offers the ability to read, manipulate and format DBI::ProfileDumper profile data.

Conceptually, a profile consists of a series of records, or nodes, each of each has a set of statistics and set of keys. Each record must have a unique set of keys, but there is no requirement that every record have the same number of keys.

METHODS

The following methods are supported by DBI::ProfileData objects.

$prof = DBI::ProfileData->new(File => "dbi.prof")

$prof = DBI::ProfileData->new(File => "dbi.prof", Filter => sub { ... })

$prof = DBI::ProfileData->new(Files => [ "dbi.prof.1", "dbi.prof.2" ])

Creates a a new DBI::ProfileData object. Takes either a single file through the File option or a list of Files in an array ref. If multiple files are specified then the header data from the first file is used.

Files

Reference to an array of file names to read.

File

Name of file to read. Takes precedence over Files.

DeleteFiles

If true, the files are deleted after being read.

Actually the files are renamed with a C.deleteme> suffix before being read, and then, after reading all the files, they're all deleted together.

The files are locked while being read which, combined with the rename, makes it safe to 'consume' files that are still being generated by the DBI::ProfileDumper manpage.

Filter

The Filter parameter can be used to supply a code reference that can manipulate the profile data as it is being read. This is most useful for editing SQL statements so that slightly different statements in the raw data will be merged and aggregated in the loaded data. For example:

  Filter => sub {
      my ($path_ref, $data_ref) = @_;
      s/foo = '.*?'/foo = '...'/ for @$path_ref;
  }

Here's an example that performs some normalization on the SQL. It converts all numbers to N and all quoted strings to S. It can also convert digits to N within names. Finally, it summarizes long "IN (...)" clauses.

It's aggressive and simplistic, but it's often sufficient, and serves as an example that you can tailor to suit your own needs:

  Filter => sub {
      my ($path_ref, $data_ref) = @_;
      local $_ = $path_ref->[0]; # whichever element contains the SQL Statement
      s/\b\d+\b/N/g;             # 42 -> N
      s/\b0x[0-9A-Fa-f]+\b/N/g;  # 0xFE -> N
      s/'.*?'/'S'/g;             # single quoted strings (doesn't handle escapes)
      s/".*?"/"S"/g;             # double quoted strings (doesn't handle escapes)
      # convert names like log_20001231 into log_NNNNNNNN, controlled by $opt{n}
      s/([a-z_]+)(\d{$opt{n},})/$1.('N' x length($2))/ieg if $opt{n};
      # abbreviate massive "in (...)" statements and similar
      s!(([NS],){100,})!sprintf("$2,{repeated %d times}",length($1)/2)!eg;
  }

It's often better to perform this kinds of normalization in the DBI while the data is being collected, to avoid too much memory being used by storing profile data for many different SQL statement. See the DBI::Profile manpage.

$copy = $prof->clone();

Clone a profile data set creating a new object.

$header = $prof->header();

Returns a reference to a hash of header values. These are the key value pairs included in the header section of the DBI::ProfileDumper data format. For example:

  $header = {
    Path    => [ '!Statement', '!MethodName' ],
    Program => 't/42profile_data.t',
  };

Note that modifying this hash will modify the header data stored inside the profile object.

$nodes = $prof->nodes()

Returns a reference the sorted nodes array. Each element in the array is a single record in the data set. The first seven elements are the same as the elements provided by DBI::Profile. After that each key is in a separate element. For example:

 $nodes = [
            [
              2,                      # 0, count
              0.0312958955764771,     # 1, total duration
              0.000490069389343262,   # 2, first duration
              0.000176072120666504,   # 3, shortest duration
              0.00140702724456787,    # 4, longest duration
              1023115819.83019,       # 5, time of first event
              1023115819.86576,       # 6, time of last event
              'SELECT foo FROM bar'   # 7, key1
              'execute'               # 8, key2
                                      # 6+N, keyN
            ],
                                      # ...
          ];

Note that modifying this array will modify the node data stored inside the profile object.

$count = $prof->count()

Returns the number of items in the profile data set.

$prof->sort(field => "field")

$prof->sort(field => "field", reverse => 1)

Sorts data by the given field. Available fields are:

  longest
  total
  count
  shortest

The default sort is greatest to smallest, which is the opposite of the normal Perl meaning. This, however, matches the expected behavior of the dbiprof frontend.

$count = $prof->exclude(key2 => "disconnect")

$count = $prof->exclude(key2 => "disconnect", case_sensitive => 1)

$count = $prof->exclude(key1 => qr/^SELECT/i)

Removes records from the data set that match the given string or regular expression. This method modifies the data in a permanent fashion - use clone() first to maintain the original data after exclude(). Returns the number of nodes left in the profile data set.

$count = $prof->match(key2 => "disconnect")

$count = $prof->match(key2 => "disconnect", case_sensitive => 1)

$count = $prof->match(key1 => qr/^SELECT/i)

Removes records from the data set that do not match the given string or regular expression. This method modifies the data in a permanent fashion - use clone() first to maintain the original data after match(). Returns the number of nodes left in the profile data set.

$Data = $prof->Data()

Returns the same Data hash structure as seen in DBI::Profile. This structure is not sorted. The nodes() structure probably makes more sense for most analysis.

$text = $prof->format($nodes->[0])

Formats a single node into a human-readable block of text.

$text = $prof->report(number => 10)

Produces a report with the given number of items.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


DBI::ProfileDumper - profile DBI usage and output data to a file

  • USAGE
  • METHODS
    • flush_to_disk
    • empty
    • filename
  • DATA FORMAT
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileDumper - profile DBI usage and output data to a file

SYNOPSIS

To profile an existing program using DBI::ProfileDumper, set the DBI_PROFILE environment variable and run your program as usual. For example, using bash:

  DBI_PROFILE=2/DBI::ProfileDumper program.pl

Then analyze the generated file (dbi.prof) with dbiprof:

  dbiprof

You can also activate DBI::ProfileDumper from within your code:

  use DBI;

  # profile with default path (2) and output file (dbi.prof)
  $dbh->{Profile} = "!Statement/DBI::ProfileDumper";

  # same thing, spelled out
  $dbh->{Profile} = "!Statement/DBI::ProfileDumper/File:dbi.prof";

  # another way to say it
  use DBI::ProfileDumper;
  $dbh->{Profile} = DBI::ProfileDumper->new(
                        Path => [ '!Statement' ]
                        File => 'dbi.prof' );

  # using a custom path
  $dbh->{Profile} = DBI::ProfileDumper->new(
      Path => [ "foo", "bar" ],
      File => 'dbi.prof',
  );

DESCRIPTION

DBI::ProfileDumper is a subclass of DBI::Profile which dumps profile data to disk instead of printing a summary to your screen. You can then use dbiprof to analyze the data in a number of interesting ways, or you can roll your own analysis using DBI::ProfileData.

NOTE: For Apache/mod_perl applications, use DBI::ProfileDumper::Apache.

USAGE

One way to use this module is just to enable it in your $dbh:

  $dbh->{Profile} = "1/DBI::ProfileDumper";

This will write out profile data by statement into a file called dbi.prof. If you want to modify either of these properties, you can construct the DBI::ProfileDumper object yourself:

  use DBI::ProfileDumper;
  $dbh->{Profile} = DBI::ProfileDumper->new(
      Path => [ '!Statement' ],
      File => 'dbi.prof'
  );

The Path option takes the same values as in the DBI::Profile manpage. The File option gives the name of the file where results will be collected. If it already exists it will be overwritten.

You can also activate this module by setting the DBI_PROFILE environment variable:

  $ENV{DBI_PROFILE} = "!Statement/DBI::ProfileDumper";

This will cause all DBI handles to share the same profiling object.

METHODS

The following methods are available to be called using the profile object. You can get access to the profile object from the Profile key in any DBI handle:

  my $profile = $dbh->{Profile};

flush_to_disk

  $profile->flush_to_disk()

Flushes all collected profile data to disk and empties the Data hash. Returns the filename writen to. If no profile data has been collected then the file is not written and flush_to_disk() returns undef.

The file is locked while it's being written. A process 'consuming' the files while they're being written to, should rename the file first, then lock it, then read it, then close and delete it. The DeleteFiles option to the DBI::ProfileData manpage does the right thing.

This method may be called multiple times during a program run.

empty

  $profile->empty()

Clears the Data hash without writing to disk.

filename

  $filename = $profile->filename();

Get or set the filename.

The filename can be specified as a CODE reference, in which case the referenced code should return the filename to be used. The code will be called with the profile object as its first argument.

DATA FORMAT

The data format written by DBI::ProfileDumper starts with a header containing the version number of the module used to generate it. Then a block of variable declarations describes the profile. After two newlines, the profile data forms the body of the file. For example:

  DBI::ProfileDumper 2.003762
  Path = [ '!Statement', '!MethodName' ]
  Program = t/42profile_data.t
  + 1 SELECT name FROM users WHERE id = ?
  + 2 prepare
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 execute
  1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 fetchrow_hashref
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 1 UPDATE users SET name = ? WHERE id = ?
  + 2 prepare
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 execute
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576

The lines beginning with + signs signify keys. The number after the + sign shows the nesting level of the key. Lines beginning with = are the actual profile data, in the same order as in DBI::Profile.

Note that the same path may be present multiple times in the data file since format() may be called more than once. When read by DBI::ProfileData the data points will be merged to produce a single data set for each distinct path.

The key strings are transformed in three ways. First, all backslashes are doubled. Then all newlines and carriage-returns are transformed into \n and \r respectively. Finally, any NULL bytes (\0) are entirely removed. When DBI::ProfileData reads the file the first two transformations will be reversed, but NULL bytes will not be restored.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


DBI::ProfileDumper::Apache - capture DBI profiling data from Apache/mod_perl

  • USAGE
    • LOADING THE MODULE
    • WRITING PROFILE DATA
      • When using mod_perl2
      • Naming the files
      • Silencing the log
    • GATHERING PROFILE DATA
    • CLEANING UP
  • OTHER ISSUES
    • Memory usage
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileDumper::Apache - capture DBI profiling data from Apache/mod_perl

SYNOPSIS

Add this line to your httpd.conf:

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache

(If you're using mod_perl2, see When using mod_perl2 for some additional notes.)

Then restart your server. Access the code you wish to test using a web browser, then shutdown your server. This will create a set of dbi.prof.* files in your Apache log directory.

Get a profiling report with dbiprof:

  dbiprof /path/to/your/apache/logs/dbi.prof.*

When you're ready to perform another profiling run, delete the old files and start again.

DESCRIPTION

This module interfaces DBI::ProfileDumper to Apache/mod_perl. Using this module you can collect profiling data from mod_perl applications. It works by creating a DBI::ProfileDumper data file for each Apache process. These files are created in your Apache log directory. You can then use the dbiprof utility to analyze the profile files.

USAGE

LOADING THE MODULE

The easiest way to use this module is just to set the DBI_PROFILE environment variable in your httpd.conf:

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache

The DBI will look after loading and using the module when the first DBI handle is created.

It's also possible to use this module by setting the Profile attribute of any DBI handle:

  $dbh->{Profile} = "2/DBI::ProfileDumper::Apache";

See the DBI::ProfileDumper manpage for more possibilities, and the DBI::Profile manpage for full details of the DBI's profiling mechanism.

WRITING PROFILE DATA

The profile data files will be written to your Apache log directory by default.

The user that the httpd processes run as will need write access to the directory. So, for example, if you're running the child httpds as user 'nobody' and using chronolog to write to the logs directory, then you'll need to change the default.

You can change the destination directory either by secifying a Dir value when creating the profile (like File in the the DBI::ProfileDumper manpage docs), or you can use the DBI_PROFILE_APACHE_LOG_DIR env var to change that. For example:

  PerlSetEnv DBI_PROFILE_APACHE_LOG_DIR /server_root/logs

When using mod_perl2

Under mod_perl2 you'll need to either set the DBI_PROFILE_APACHE_LOG_DIR env var, or enable the mod_perl2 GlobalRequest option, like this:

  PerlOptions +GlobalRequest

to the global config section you're about test with DBI::ProfileDumper::Apache. If you don't do one of those then you'll see messages in your error_log similar to:

  DBI::ProfileDumper::Apache on_destroy failed: Global $r object is not available. Set:
    PerlOptions +GlobalRequest in httpd.conf at ..../DBI/ProfileDumper/Apache.pm line 144

Naming the files

The default file name is inherited from the DBI::ProfileDumper manpage via the filename() method, but DBI::ProfileDumper::Apache appends the parent pid and the current pid, separated by dots, to that name.

Silencing the log

By default a message is written to STDERR (i.e., the apache error_log file) when flush_to_disk() is called (either explicitly, or implicitly via DESTROY).

That's usually very useful. If you don't want the log message you can silence it by setting the Quiet attribute true.

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache/Quiet:1
  $dbh->{Profile} = "!Statement/DBI::ProfileDumper/Quiet:1";

  $dbh->{Profile} = DBI::ProfileDumper->new(
      Path => [ '!Statement' ]
      Quiet => 1
  );

GATHERING PROFILE DATA

Once you have the module loaded, use your application as you normally would. Stop the webserver when your tests are complete. Profile data files will be produced when Apache exits and you'll see something like this in your error_log:

  DBI::ProfileDumper::Apache writing to /usr/local/apache/logs/dbi.prof.2604.2619

Now you can use dbiprof to examine the data:

  dbiprof /usr/local/apache/logs/dbi.prof.2604.*

By passing dbiprof a list of all generated files, dbiprof will automatically merge them into one result set. You can also pass dbiprof sorting and querying options, see the dbiprof manpage for details.

CLEANING UP

Once you've made some code changes, you're ready to start again. First, delete the old profile data files:

  rm /usr/local/apache/logs/dbi.prof.*

Then restart your server and get back to work.

OTHER ISSUES

Memory usage

DBI::Profile can use a lot of memory for very active applications because it collects profiling data in memory for each distinct query run. Calling flush_to_disk() will write the current data to disk and free the memory it's using. For example:

  $dbh->{Profile}->flush_to_disk() if $dbh->{Profile};

or, rather than flush every time, you could flush less often:

  $dbh->{Profile}->flush_to_disk()
    if $dbh->{Profile} and ++$i % 100;

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


DBI::ProfileSubs - Subroutines for dynamic profile Path

  • TO DO

NAME

DBI::ProfileSubs - Subroutines for dynamic profile Path

SYNOPSIS

  DBI_PROFILE='&norm_std_n3' prog.pl

This is new and still experimental.

TO DO

Define come kind of naming convention for the subs.


DBI::ProxyServer - a server for the DBD::Proxy driver

  • OPTIONS
  • CONFIGURATION FILE
  • Proxyserver Configuration file (bigger example)
    • Testing the connection from a remote machine
    • Testing the connection with a perl-script
    • How the configuration works
    • Problems
  • AUTHOR
  • SEE ALSO

NAME

DBI::ProxyServer - a server for the DBD::Proxy driver

SYNOPSIS

    use DBI::ProxyServer;
    DBI::ProxyServer::main(@ARGV);

DESCRIPTION

DBI::Proxy Server is a module for implementing a proxy for the DBI proxy driver, DBD::Proxy. It allows access to databases over the network if the DBMS does not offer networked operations. But the proxy server might be usefull for you, even if you have a DBMS with integrated network functionality: It can be used as a DBI proxy in a firewalled environment.

DBI::ProxyServer runs as a daemon on the machine with the DBMS or on the firewall. The client connects to the agent using the DBI driver DBD::Proxy, thus in the exactly same way than using DBD::mysql, DBD::mSQL or any other DBI driver.

The agent is implemented as a RPC::PlServer application. Thus you have access to all the possibilities of this module, in particular encryption and a similar configuration file. DBI::ProxyServer adds the possibility of query restrictions: You can define a set of queries that a client may execute and restrict access to those. (Requires a DBI driver that supports parameter binding.) See CONFIGURATION FILE.

The provided driver script, the dbiproxy manpage, may either be used as it is or used as the basis for a local version modified to meet your needs.

OPTIONS

When calling the DBI::ProxyServer::main() function, you supply an array of options. These options are parsed by the Getopt::Long module. The ProxyServer inherits all of RPC::PlServer's and hence Net::Daemon's options and option handling, in particular the ability to read options from either the command line or a config file. See the RPC::PlServer manpage. See the Net::Daemon manpage. Available options include

chroot (--chroot=dir)

(UNIX only) After doing a bind(), change root directory to the given directory by doing a chroot(). This is usefull for security, but it restricts the environment a lot. For example, you need to load DBI drivers in the config file or you have to create hard links to Unix sockets, if your drivers are using them. For example, with MySQL, a config file might contain the following lines:

    my $rootdir = '/var/dbiproxy';
    my $unixsockdir = '/tmp';
    my $unixsockfile = 'mysql.sock';
    foreach $dir ($rootdir, "$rootdir$unixsockdir") {
        mkdir 0755, $dir;
    }
    link("$unixsockdir/$unixsockfile",
         "$rootdir$unixsockdir/$unixsockfile");
    require DBD::mysql;

    {
        'chroot' => $rootdir,
        ...
    }

If you don't know chroot(), think of an FTP server where you can see a certain directory tree only after logging in. See also the --group and --user options.

clients

An array ref with a list of clients. Clients are hash refs, the attributes accept (0 for denying access and 1 for permitting) and mask, a Perl regular expression for the clients IP number or its host name.

configfile (--configfile=file)

Config files are assumed to return a single hash ref that overrides the arguments of the new method. However, command line arguments in turn take precedence over the config file. See the CONFIGURATION FILE section below for details on the config file.

debug (--debug)

Turn debugging mode on. Mainly this asserts that logging messages of level "debug" are created.

facility (--facility=mode)

(UNIX only) Facility to use for the Sys::Syslog manpage. The default is daemon.

group (--group=gid)

After doing a bind(), change the real and effective GID to the given. This is usefull, if you want your server to bind to a privileged port (<1024), but don't want the server to execute as root. See also the --user option.

GID's can be passed as group names or numeric values.

localaddr (--localaddr=ip)

By default a daemon is listening to any IP number that a machine has. This attribute allows to restrict the server to the given IP number.

localport (--localport=port)

This attribute sets the port on which the daemon is listening. It must be given somehow, as there's no default.

logfile (--logfile=file)

Be default logging messages will be written to the syslog (Unix) or to the event log (Windows NT). On other operating systems you need to specify a log file. The special value "STDERR" forces logging to stderr. See the Net::Daemon::Log manpage for details.

mode (--mode=modename)

The server can run in three different modes, depending on the environment.

If you are running Perl 5.005 and did compile it for threads, then the server will create a new thread for each connection. The thread will execute the server's Run() method and then terminate. This mode is the default, you can force it with "--mode=threads".

If threads are not available, but you have a working fork(), then the server will behave similar by creating a new process for each connection. This mode will be used automatically in the absence of threads or if you use the "--mode=fork" option.

Finally there's a single-connection mode: If the server has accepted a connection, he will enter the Run() method. No other connections are accepted until the Run() method returns (if the client disconnects). This operation mode is usefull if you have neither threads nor fork(), for example on the Macintosh. For debugging purposes you can force this mode with "--mode=single".

pidfile (--pidfile=file)

(UNIX only) If this option is present, a PID file will be created at the given location. Default is to not create a pidfile.

user (--user=uid)

After doing a bind(), change the real and effective UID to the given. This is usefull, if you want your server to bind to a privileged port (<1024), but don't want the server to execute as root. See also the --group and the --chroot options.

UID's can be passed as group names or numeric values.

version (--version)

Supresses startup of the server; instead the version string will be printed and the program exits immediately.

CONFIGURATION FILE

The configuration file is just that of RPC::PlServer or Net::Daemon with some additional attributes in the client list.

The config file is a Perl script. At the top of the file you may include arbitraty Perl source, for example load drivers at the start (usefull to enhance performance), prepare a chroot environment and so on.

The important thing is that you finally return a hash ref of option name/value pairs. The possible options are listed above.

All possibilities of Net::Daemon and RPC::PlServer apply, in particular

Host and/or User dependent access control
Host and/or User dependent encryption
Changing UID and/or GID after binding to the port
Running in a chroot() environment

Additionally the server offers you query restrictions. Suggest the following client list:

    'clients' => [
        { 'mask' => '^admin\.company\.com$',
          'accept' => 1,
          'users' => [ 'root', 'wwwrun' ],
        },
        {
          'mask' => '^admin\.company\.com$',
          'accept' => 1,
          'users' => [ 'root', 'wwwrun' ],
          'sql' => {
               'select' => 'SELECT * FROM foo',
               'insert' => 'INSERT INTO foo VALUES (?, ?, ?)'
               }
        }

then only the users root and wwwrun may connect from admin.company.com, executing arbitrary queries, but only wwwrun may connect from other hosts and is restricted to

    $sth->prepare("select");

or

    $sth->prepare("insert");

which in fact are "SELECT * FROM foo" or "INSERT INTO foo VALUES (?, ?, ?)".

Proxyserver Configuration file (bigger example)

This section tells you how to restrict a DBI-Proxy: Not every user from every workstation shall be able to execute every query.

There is a perl program "dbiproxy" which runs on a machine which is able to connect to all the databases we wish to reach. All Perl-DBD-drivers must be installed on this machine. You can also reach databases for which drivers are not available on the machine where you run the programm querying the database, e.g. ask MS-Access-database from Linux.

Create a configuration file "proxy_oracle.cfg" at the dbproxy-server:

    {
        # This shall run in a shell or a DOS-window
        # facility => 'daemon',
        pidfile => 'your_dbiproxy.pid',
        logfile => 1,
        debug => 0,
        mode => 'single',
        localport => '12400',

        # Access control, the first match in this list wins!
        # So the order is important
        clients => [
                # hint to organize:
                # the most specialized rules for single machines/users are 1st
                # then the denying rules
                # the the rules about whole networks
                # rule: internal_webserver
                # desc: to get statistical information
                {
                        # this IP-address only is meant
                        mask => '^10\.95\.81\.243$',
                        # accept (not defer) connections like this
                        accept => 1,
                        # only users from this list
                        # are allowed to log on
                        users => [ 'informationdesk' ],
                        # only this statistical query is allowed
                        # to get results for a web-query
                        sql => {
                                alive => 'select count(*) from dual',
                                statistic_area => 'select count(*) from e01admin.e01e203 where geb_bezei like ?',
                        }
                },

                # rule: internal_bad_guy_1
                {
                        mask => '^10\.95\.81\.1$',
                        accept => 0,
                },

                # rule: employee_workplace
                # desc: get detailled informations
                {
                        # any IP-address is meant here
                        mask => '^10\.95\.81\.(\d+)$',
                        # accept (not defer) connections like this
                        accept => 1,
                        # only users from this list
                        # are allowed to log on
                        users => [ 'informationdesk', 'lippmann' ],
                        # all these queries are allowed:
                        sql => {
                                search_city => 'select ort_nr, plz, ort from e01admin.e01e200 where plz like ?',
                                search_area => 'select gebiettyp, geb_bezei from e01admin.e01e203 where geb_bezei like ? or geb_bezei like ?',
                        }
                },

                # rule: internal_bad_guy_2
                # This does NOT work, because rule "employee_workplace" hits
                # with its ip-address-mask of the whole network
                {
                        # don't accept connection from this ip-address
                        mask => '^10\.95\.81\.5$',
                        accept => 0,
                }
                        ]
                    }

Start the proxyserver like this:

        rem well-set Oracle_home needed for Oracle
        set ORACLE_HOME=d:\oracle\ora81
        dbiproxy --configfile proxy_oracle.cfg

Testing the connection from a remote machine

Call a programm "dbish" from your commandline. I take the machine from rule "internal_webserver"

        dbish "dbi:Proxy:hostname=oracle.zdf;port=12400;dsn=dbi:Oracle:e01" informationdesk xxx

There will be a shell-prompt:

        informationdesk@dbi...> alive
        Current statement buffer (enter '/'...):
        alive
        informationdesk@dbi...> /
        COUNT(*)
        '1'
        [1 rows of 1 fields returned]

Testing the connection with a perl-script

Create a perl-script like this:

        # file: oratest.pl
        # call me like this: perl oratest.pl user password

        use strict;
        use DBI;

        my $user = shift || die "Usage: $0 user password";
        my $pass = shift || die "Usage: $0 user password";
        my $config = {
                dsn_at_proxy => "dbi:Oracle:e01",
                proxy => "hostname=oechsle.zdf;port=12400",
        };
        my $dsn = sprintf "dbi:Proxy:%s;dsn=%s",
                $config->{proxy},
                $config->{dsn_at_proxy};

        my $dbh = DBI->connect( $dsn, $user, $pass )
                || die "connect did not work: $DBI::errstr";

        my $sql = "search_city";
        printf "%s\n%s\n%s\n", "="x40, $sql, "="x40;
        my $cur = $dbh->prepare($sql);
        $cur->bind_param(1,'905%');
        &show_result ($cur);

        my $sql = "search_area";
        printf "%s\n%s\n%s\n", "="x40, $sql, "="x40;
        my $cur = $dbh->prepare($sql);
        $cur->bind_param(1,'Pfarr%');
        $cur->bind_param(2,'Bronnamberg%');
        &show_result ($cur);

        my $sql = "statistic_area";
        printf "%s\n%s\n%s\n", "="x40, $sql, "="x40;
        my $cur = $dbh->prepare($sql);
        $cur->bind_param(1,'Pfarr%');
        &show_result ($cur);

        $dbh->disconnect;
        exit;

        sub show_result {
                my $cur = shift;
                unless ($cur->execute()) {
                        print "Could not execute\n";
                        return;
                }

                my $rownum = 0;
                while (my @row = $cur->fetchrow_array()) {
                        printf "Row is: %s\n", join(", ",@row);
                        if ($rownum++ > 5) {
                                print "... and so on\n";
                                last;
                        }
                }
                $cur->finish;
                        }

The result

        C:\>perl oratest.pl informationdesk xxx
        ========================================
        search_city
        ========================================
        Row is: 3322, 9050, Chemnitz
        Row is: 3678, 9051, Chemnitz
        Row is: 10447, 9051, Chemnitz
        Row is: 12128, 9051, Chemnitz
        Row is: 10954, 90513, Zirndorf
        Row is: 5808, 90513, Zirndorf
        Row is: 5715, 90513, Zirndorf
        ... and so on
        ========================================
        search_area
        ========================================
        Row is: 101, Bronnamberg
        Row is: 400, Pfarramt Zirndorf
        Row is: 400, Pfarramt Rosstal
        Row is: 400, Pfarramt Oberasbach
        Row is: 401, Pfarramt Zirndorf
        Row is: 401, Pfarramt Rosstal
        ========================================
        statistic_area
        ========================================
        DBD::Proxy::st execute failed: Server returned error: Failed to execute method CallMethod: Unknown SQL query: statistic_area at E:/Perl/site/lib/DBI/ProxyServer.pm line 258.
        Could not execute

How the configuration works

The most important section to control access to your dbi-proxy is "client=>" in the file "proxy_oracle.cfg":

Controlling which person at which machine is allowed to access

  • "mask" is a perl regular expression against the plain ip-address of the machine which wishes to connect _or_ the reverse-lookup from a nameserver.
  • "accept" tells the dbiproxy-server wether ip-adresse like in "mask" are allowed to connect or not (0/1)
  • "users" is a reference to a list of usernames which must be matched, this is NOT a regular expression.

Controlling which SQL-statements are allowed

You can put every SQL-statement you like in simply ommiting "sql => ...", but the more important thing is to restrict the connection so that only allowed queries are possible.

If you include an sql-section in your config-file like this:

        sql => {
                alive => 'select count(*) from dual',
                statistic_area => 'select count(*) from e01admin.e01e203 where geb_bezei like ?',
        }

The user is allowed to put two queries against the dbi-proxy. The queries are _not_ "select count(*)...", the queries are "alive" and "statistic_area"! These keywords are replaced by the real query. So you can run a query for "alive":

        my $sql = "alive";
        my $cur = $dbh->prepare($sql);
        ...

The flexibility is that you can put parameters in the where-part of the query so the query are not static. Simply replace a value in the where-part of the query through a question mark and bind it as a parameter to the query.

        my $sql = "statistic_area";
        my $cur = $dbh->prepare($sql);
        $cur->bind_param(1,'905%');
        # A second parameter would be called like this:
        # $cur->bind_param(2,'98%');

The result is this query:

        select count(*) from e01admin.e01e203
        where geb_bezei like '905%'

Don't try to put parameters into the sql-query like this:

        # Does not work like you think.
        # Only the first word of the query is parsed,
        # so it's changed to "statistic_area", the rest is omitted.
        # You _have_ to work with $cur->bind_param.
        my $sql = "statistic_area 905%";
        my $cur = $dbh->prepare($sql);
        ...

Problems

  • I don't know how to restrict users to special databases.
  • I don't know how to pass query-parameters via dbish

AUTHOR

    Copyright (c) 1997    Jochen Wiedmann
                          Am Eisteich 9
                          72555 Metzingen
                          Germany
                          Email: joe@ispsoft.de
                          Phone: +49 7123 14881

The DBI::ProxyServer module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. In particular permission is granted to Tim Bunce for distributing this as a part of the DBI.

SEE ALSO

the dbiproxy manpage, the DBD::Proxy manpage, the DBI manpage, the RPC::PlServer manpage, the RPC::PlClient manpage, the Net::Daemon manpage, the Net::Daemon::Log manpage, the Sys::Syslog manpage, the Win32::EventLog manpage, syslog


DBI::PurePerl -- a DBI emulation using pure perl

  • EXPERIMENTAL STATUS
  • USAGE
  • INSTALLATION
  • DIFFERENCES BETWEEN DBI AND DBI::PurePerl
    • Attributes
    • Tracing
    • Parameter Usage Checking
    • Speed
    • May not fully support hash()
    • Doesn't support preparse()
    • Doesn't support DBD::Proxy
    • Others
  • AUTHORS
  • COPYRIGHT

NAME

DBI::PurePerl -- a DBI emulation using pure perl (no C/XS compilation required)

SYNOPSIS

 BEGIN { $ENV{DBI_PUREPERL} = 2 }
 use DBI;

DESCRIPTION

This is a pure perl emulation of the DBI internals. In almost all cases you will be better off using standard DBI since the portions of the standard version written in C make it *much* faster.

However, if you are in a situation where it isn't possible to install a compiled version of standard DBI, and you're using pure-perl DBD drivers, then this module allows you to use most common features of DBI without needing any changes in your scripts.

EXPERIMENTAL STATUS

DBI::PurePerl is new so please treat it as experimental pending more extensive testing. So far it has passed all tests with DBD::CSV, DBD::AnyData, DBD::XBase, DBD::Sprite, DBD::mysqlPP. Please send bug reports to Jeff Zucker at <jeff@vpservices.com> with a cc to <dbi-dev@perl.org>.

USAGE

The usage is the same as for standard DBI with the exception that you need to set the enviornment variable DBI_PUREPERL if you want to use the PurePerl version.

 DBI_PUREPERL == 0 (the default) Always use compiled DBI, die
                   if it isn't properly compiled & installed
 DBI_PUREPERL == 1 Use compiled DBI if it is properly compiled
                   & installed, otherwise use PurePerl
 DBI_PUREPERL == 2 Always use PurePerl

You may set the enviornment variable in your shell (e.g. with set or setenv or export, etc) or else set it in your script like this:

 BEGIN { $ENV{DBI_PUREPERL}=2 }

before you use DBI;.

INSTALLATION

In most situations simply install DBI (see the DBI pod for details).

In the situation in which you can not install DBI itself, you may manually copy DBI.pm and PurePerl.pm into the appropriate directories.

For example:

 cp DBI.pm      /usr/jdoe/mylibs/.
 cp PurePerl.pm /usr/jdoe/mylibs/DBI/.

Then add this to the top of scripts:

 BEGIN {
   $ENV{DBI_PUREPERL} = 1;      # or =2
   unshift @INC, '/usr/jdoe/mylibs';
 }

(Or should we perhaps patch Makefile.PL so that if DBI_PUREPERL is set to 2 prior to make, the normal compile process is skipped and the files are installed automatically?)

DIFFERENCES BETWEEN DBI AND DBI::PurePerl

Attributes

Boolean attributes still return boolean values but the actual values used may be different, i.e., 0 or undef instead of an empty string.

Some handle attributes are either not supported or have very limited functionality:

  ActiveKids
  InactiveDestroy
  Kids
  Taint
  TaintIn
  TaintOut

(and probably others)

Tracing

Trace functionality is more limited and the code to handle tracing is only embeded into DBI:PurePerl if the DBI_TRACE environment variable is defined. To enable total tracing you can set the DBI_TRACE environment variable as usual. But to enable individual handle tracing using the trace() method you also need to set the DBI_TRACE environment variable, but set it to 0.

Parameter Usage Checking

The DBI does some basic parameter count checking on method calls. DBI::PurePerl doesn't.

Speed

DBI::PurePerl is slower. Although, with some drivers in some contexts this may not be very significant for you.

By way of example... the test.pl script in the DBI source distribution has a simple benchmark that just does:

    my $null_dbh = DBI->connect('dbi:NullP:','','');
    my $i = 10_000;
    $null_dbh->prepare('') while $i--;

In other words just prepares a statement, creating and destroying a statement handle, over and over again. Using the real DBI this runs at ~4550 handles per second whereas DBI::PurePerl manages ~2800 per second on the same machine (not too bad really).

May not fully support hash()

If you want to use type 1 hash, i.e., hash($string,1) with DBI::PurePerl, you'll need version 1.56 or higher of Math::BigInt (available on CPAN).

Doesn't support preparse()

The DBI->preparse() method isn't supported in DBI::PurePerl.

Doesn't support DBD::Proxy

There's a subtle problem somewhere I've not been able to identify. DBI::ProxyServer seem to work fine with DBI::PurePerl but DBD::Proxy does not work 100% (which is sad because that would be far more useful :) Try re-enabling t/80proxy.t for DBI::PurePerl to see if the problem that remains will affect you're usage.

Others

  can() - doesn't have any special behaviour

Please let us know if you find any other differences between DBI and DBI::PurePerl.

AUTHORS

Tim Bunce and Jeff Zucker.

Tim provided the direction and basis for the code. The original idea for the module and most of the brute force porting from C to Perl was by Jeff. Tim then reworked some core parts to boost the performance and accuracy of the emulation. Thanks also to Randal Schwartz and John Tobey for patches.

COPYRIGHT

Copyright (c) 2002 Tim Bunce Ireland.

See COPYRIGHT section in DBI.pm for usage and distribution rights.


DBI::Roadmap - Planned Enhancements for the DBI

  • SCOPE
  • CHANGES AND ENHANCEMENTS
    • Performance
    • Testing
    • High Availability and Load Balancing
    • Unicode
    • Batch Statements
    • Introspection
    • Extensibility
    • Debugability
    • Database Portability
    • Intellectual Property
    • Other Enhancements
    • Parrot and Perl 6
  • PRIORITIES
    • Transition Drivers
    • Transition Applications
    • Incremental Developments
    • DBI v1
  • RESOURCES AND CONTRIBUTIONS

NAME

DBI::Roadmap - Planned Enhancements for the DBI

Tim Bunce - 12th November 2004

SYNOPSIS

This document gives a high level overview of the future of the Perl DBI module.

The DBI module is the standard database interface for Perl applications. It is used worldwide in countless applications, in every kind of business, and on platforms from clustered super-computers to PDAs. Database interface drivers are available for all common databases and many not-so-common ones.

The planned enhancements cover testing, performance, high availability and load balancing, batch statements, Unicode, database portability, and more.

Addressing these issues together, in coordinated way, will help ensure maximum future functionality with minimal disruptive (incompatible) upgrades.

SCOPE

Broad categories of changes are outlined here along with some rationale, but implementation details and minor planned enhancements are omitted. More details can be found in: http://svn.perl.org/modules/dbi/trunk/ToDo

CHANGES AND ENHANCEMENTS

These are grouped into categories and are not listed in any particular order.

Performance

The DBI has always treated performance as a priority. Some parts of the implementation, however, remain unoptimized, especially in relation to threads.

* When the DBI is used with a Perl built with thread support enabled (such as for Apache mod_perl 2, and some common Linux distributions) it runs significantly slower. There are two reasons for this and both can be fixed but require non-trivial changes to both the DBI and drivers.

* Connection pooling in a threaded application, such as mod_perl, is difficult because DBI handles cannot be passed between threads. An alternative mechanism for passing connections between threads has been defined, and an experimental connection pool module implemented using it, but development has stalled.

* The majority of DBI handle creation code is implemented in Perl. Moving most of this to C will speed up handle creation significantly.

* The popular fetchrow_hashref() method is many times slower than fetchrow_arrayref(). It has to get the names of the columns, then create and load a new hash each time. A $h->{FetchHashReuse} attribute would allow the same hash to be reused each time making fetchrow_hashref() about the same speed as fetchrow_arrayref().

* Support for asynchronous (non-blocking) DBI method calls would enable applications to continue processing in parallel with database activity. This is also relevant for GUI and other event-driven applications. The DBI needs to define a standard interface for this so drivers can implement it in a portable way, where possible.

These changes would significantly enhance the performance of the DBI and many applications which use the DBI.

Testing

The DBI has a test suite. Every driver has a test suite. Each is limited in its scope. The driver test suite is testing for behavior that the driver author thinks the DBI specifies, but may be subtly incorrect. These test suites are poorly maintained because the return on investment for a single driver is too low to provide sufficient incentive.

A common test suite that can be reused by all the drivers is needed. It would:

* Improve the quality of the DBI and drivers.

* Ensure all drivers conform to the DBI specification. Easing the porting of applications between databases, and the implementation of database independent modules layered over the DBI.

* Improve the DBI specification by clarifying unclear issues in order to implement test cases.

* Encourage expansion of the test suite as driver authors and others will be motivated by the greater benefits of their contributions.

* Detect and record optional functionality that a driver has not yet implemented.

* Improve the testing of DBI subclassing, DBI::PurePerl and the various "transparent" drivers, such as DBD::Proxy and DBD::Multiplex, by automatically running the test suite through them.

These changes would improve the quality of all applications using the DBI.

High Availability and Load Balancing

* The DBD::Multiplex driver provides a framework to enable a wide range of dynamic functionality, including support for high-availability, failover, load-balancing, caching, and access to distributed data. It is currently being enhanced but development has stalled.

* The DBD::Proxy module is complex and relatively inefficient because it's trying to be a complete proxy for most DBI method calls. For many applications a simpler proxy architecture that operates with a single round-trip to the server would be simpler, faster, and more flexible.

New proxy client and server classes are needed, which could be subclassed to support specific client to server transport mechanisms (such as HTTP and Spread::Queue). Apart from the efficiency gains, this would also enable the use of a load-balanced pool of stateless servers for greater scalability and reliability.

* The DBI currently offers no support for distributed transactions. The most useful elements of the standard XA distributed transaction interface standard could be included in the DBI specification. Drivers for databases which support distributed transactions could then be extended to support it.

These changes would enable new kinds of DBI applications for critical environments.

Unicode

Use of Unicode with the DBI is growing rapidly. The DBI should do more to help drivers support Unicode and help applications work with drivers that don't yet support Unicode directly.

* Define expected behavior for fetching data and binding parameters.

* Provide interfaces to support Unicode issues for XS and pure Perl drivers and applications.

* Provide functions for applications to help diagnose inconsistencies between byte string contents and setting of the SvUTF8 flag.

These changes would smooth the transition to Unicode for many applications and drivers.

Batch Statements

Batch statements are a sequence of SQL statements, or a stored procedure containing a sequence of SQL statements, which can be executed as a whole.

Currently the DBI has no standard interface for dealing with multiple results from batch statements. After considerable discussion, an interface design has been agreed upon with driver authors, but has not yet been implemented.

These changes would enable greater application portability between databases, and greater performance for databases that directly support batch statements.

Introspection

* The methods of the DBI API are installed dynamically when the DBI is loaded. The data structure used to define the methods and their dispatch behavior should be made part of the DBI API. This would enable more flexible and correct behavior by modules subclassing the DBI and by dynamic drivers such as DBD::Proxy and DBD::Multiplex.

* Handle attribute information should also be made available, for the same reasons.

* Currently is it not possible to discover all the child statement handles that belong to a database handle (or all database handles that belong to a driver handle). This makes certain tasks more difficult, especially some debugging scenarios. A cache of weak references to child handles would solve the problem without creating reference loops.

* It is often useful to know which handle attributes have been changed since the handle was created (e.g., in mod_perl where a handle needs to be reset or cloned). This will become more important as developers start exploring use of the newly added $h1->swap_inner_handle($h2) method.

These changes would simplify and improve the stability of many advanced uses of the DBI.

Extensibility

The DBI can be extended in three main dimensions: subclassing the DBI, subclassing a driver, and callback hooks. Each has different pros and cons, each is applicable in different situations, and all need enhancing.

* Subclassing the DBI is functional but not well defined and some key elements are incomplete, particularly the DbTypeSubclass mechanism (that automatically subclasses to a class tree according to the type of database being used). It also needs more thorough testing.

* Subclassing a driver is undocumented, poorly tested and very probably incomplete. However it's a powerful way to embed certain kinds of functionality 'below' applications while avoiding some of the side-effects of subclassing the DBI (especially in relation to error handling).

* Callbacks are currently limited to error handling (the HandleError and HandleSetError attributes). Providing callback hooks for more events, such as a row being fetched, would enable utility modules, for example, to modify the behavior of a handle independent of any subclassing in use.

These changes would enable cleaner and more powerful integration between applications, layered modules, and the DBI.

Debugability

* Enabling DBI trace output at a high level of detail causes a large volume of output, much of it probably unrelated to the problem being investigated. Trace output should be controlled by the new named-topic mechanism instead of just the trace level.

* Calls to XS functions (such as many DBI and driver methods) don't normally appear in the call stack. Optionally enabling that would enable more useful diagnostics to be produced.

* Integration with the Perl debugger would make it simpler to perform actions on a per-handle basis (such as breakpoint on execute, breakpoint on error).

These changes would enable more rapid application development and fault finding.

Database Portability

* The DBI has not yet addressed the issue of portability among SQL dialects. This is the main hurdle limiting database portability for DBI applications.

The goal is not to fully parse the SQL and rewrite it in a different dialect. That's well beyond the scope of the DBI and should be left to layered modules. A simple token rewriting mechanism for five comment styles, two quoting styles, four placeholder styles, plus the ODBC "{foo ...}" escape syntax, is sufficient to significantly raise the level of SQL portability.

* Another problem area is date/time formatting. Since version 1.41 the DBI has defined a way to express that dates should be fetched in SQL standard date format (YYYY-MM-DD). This is one example of the more general case where bind_col() needs to be called with particular attributes on all columns of a particular type.

A mechanism is needed whereby an application can specify default bind_col() attributes to be applied automatically for each column type. With a single step, all DATE type columns, for example, can be set to be returned in the standard format.

These changes would enable greater database portability for applications and greater functionality for layered modules.

Intellectual Property

* Clarify current intellectual property status, including a review of past contributions to ensure the DBI is unemcumbered.

* Establish a procedure for vetting future contributions for any intellectual property issues.

These changes are important for companies taking a formal approach to assessing their risks in using Open Source software.

Other Enhancements

* Reduce the work needed to create new database interface drivers.

* Definition of an interface to support scrollable cursors.

Parrot and Perl 6

The current DBI implementation in C code is unlikely to run on Perl 6. Perl 6 will target the Parrot virtual machine and so the internal architecture will be radically different from Perl 5.

One of the goals of the Parrot project is to be a platform for many dynamic languages (including Python, PHP, Ruby, etc) and to enable those languages to reuse each others modules. A database interface for Parrot is also a database interface for any and all languages that run on Parrot.

The Perl DBI would make an excellent base for a Parrot database interface because it has more functionality, and is more mature and extensible, than the database interfaces of the other dynamic languages.

I plan to better define the API between the DBI and the drivers and use that API as the primary API for the 'raw' Parrot database interface. This project is known a Parrot DBDI (for "DataBase Driver Interface"). The announcement can be read in <http://groups.google.com/groups?selm=20040127225639.GF38394@dansat.data-plan.com>

The bulk of the work will be translating the DBI C and Perl base class code into Parrot PIR, or a suitable language that generates PIR. The project stalled, due to Parrot not having key functionality at the time. That has been resolved but the project has not yet restarted.

Each language targeting Parrot would implement their own small 'thin' language-specific method dispatcher (a "Perl6 DBI", "Python DBI", "PHP DBI" etc) layered over the common Parrot DBDI interface and drivers.

The major benefit of the DBDI project is that a much wider community of developers share the same database drivers. There would be more developers maintaining less code so the benefits of the Open Source model are magnified.

PRIORITIES

Transition Drivers

The first priority is to make all the infrastructure changes that impact drivers and make an alpha release available for driver authors.

As far as possible, the changes will be implemented in a way that enables driver authors use the same code base for DBI v1 and DBI v2.

The main changes required by driver authors are:

* Code changes for PERL_NO_GET_CONTEXT, plus removing PERL_POLLUTE and DBIS

* Code changes in DBI/DBD interface (new way to create handles, new callbacks etc)

* Common test suite infrastructure (driver-specific test base class)

Transition Applications

A small set of incompatible changes that may impact some applications will also be made in v2.0. See http://svn.perl.org/modules/dbi/trunk/ToDo

Incremental Developments

Once DBI v2.0 is available, the other enhancements can be implemented incrementally on the updated foundations. Priorities for those changes have not been set.

DBI v1

DBI v1 will continue to be maintained on a separate branch for bug fixes and any enhancements that ease the transition to DBI v2.

RESOURCES AND CONTRIBUTIONS

See http://dbi.perl.org/contributing for how you can help.

If your company has benefited from the DBI, please consider if it could make a donation to The Perl Foundation "DBI Development" fund at http://dbi.perl.org/donate to secure future development.

Alternatively, if your company would benefit from a specific new DBI feature, please consider sponsoring its development through my consulting company, Data Plan Services. Work is performed rapidly on a fixed-price payment-on-delivery basis. Contact me for details.

Using such targeted financing allows you to contribute to DBI development and rapidly get something specific and directly valuable to you in return.

My company also offers annual support contracts for the DBI, which provide another way to support the DBI and get something specific in return. Contact me for details.

Thank you.


DBI::SQL::Nano - a very tiny SQL engine

  • USAGE
    • Setting the DBI_SQL_NANO flag
    • Supported SQL syntax
  • ACKNOWLEDGEMENTS
  • AUTHOR AND COPYRIGHT

NAME

DBI::SQL::Nano - a very tiny SQL engine

SYNOPSIS

 BEGIN { $ENV{DBI_SQL_NANO}=1 } # forces use of Nano rather than SQL::Statement
 use DBI::SQL::Nano;
 use Data::Dumper;
 my $stmt = DBI::SQL::Nano::Statement->new(
     "SELECT bar,baz FROM foo WHERE qux = 1"
 ) or die "Couldn't parse";
 print Dumper $stmt;

DESCRIPTION

DBI::SQL::Nano is meant as a *very* minimal SQL engine for use in situations where SQL::Statement is not available. In most situations you are better off installing SQL::Statement although DBI::SQL::Nano may be faster for some very simple tasks.

DBI::SQL::Nano, like SQL::Statement is primarily intended to provide a SQL engine for use with some pure perl DBDs including DBD::DBM, DBD::CSV, DBD::AnyData, and DBD::Excel. It isn't of much use in and of itself. You can dump out the structure of a parsed SQL statement, but that's about it.

USAGE

Setting the DBI_SQL_NANO flag

By default, when a DBD uses DBI::SQL::Nano, the module will look to see if SQL::Statement is installed. If it is, SQL::Statement objects are used. If SQL::Statement is not available, DBI::SQL::Nano objects are used.

In some cases, you may wish to use DBI::SQL::Nano objects even if SQL::Statement is available. To force usage of DBI::SQL::Nano objects regardless of the availability of SQL::Statement, set the environment variable DBI_SQL_NANO to 1.

You can set the environment variable in your shell prior to running your script (with SET or EXPORT or whatever), or else you can set it in your script by putting this at the top of the script:

 BEGIN { $ENV{DBI_SQL_NANO} = 1 }

Supported SQL syntax

 Here's a pseudo-BNF.  Square brackets [] indicate optional items;
 Angle brackets <> indicate items defined elsewhere in the BNF.

  statement ::=
      DROP TABLE [IF EXISTS] <table_name>
    | CREATE TABLE <table_name> <col_def_list>
    | INSERT INTO <table_name> [<insert_col_list>] VALUES <val_list>
    | DELETE FROM <table_name> [<where_clause>]
    | UPDATE <table_name> SET <set_clause> <where_clause>
    | SELECT <select_col_list> FROM <table_name> [<where_clause>]
                                                 [<order_clause>]
  the optional IF EXISTS clause ::=
    * similar to MySQL - prevents errors when trying to drop
      a table that doesn't exist
  identifiers ::=
    * table and column names should be valid SQL identifiers
    * especially avoid using spaces and commas in identifiers
    * note: there is no error checking for invalid names, some
      will be accepted, others will cause parse failures
  table_name ::=
    * only one table (no multiple table operations)
    * see identifier for valid table names
  col_def_list ::=
    * a parens delimited, comma-separated list of column names
    * see identifier for valid column names
    * column types and column constraints may be included but are ignored
      e.g. these are all the same:
        (id,phrase)
        (id INT, phrase VARCHAR(40))
        (id INT PRIMARY KEY, phrase VARCHAR(40) NOT NULL)
    * you are *strongly* advised to put in column types even though
      they are ignored ... it increases portability
  insert_col_list ::=
    * a parens delimited, comma-separated list of column names
    * as in standard SQL, this is optional
  select_col_list ::=
    * a comma-separated list of column names
    * or an asterisk denoting all columns
  val_list ::=
    * a parens delimited, comma-separated list of values which can be:
       * placeholders (an unquoted question mark)
       * numbers (unquoted numbers)
       * column names (unquoted strings)
       * nulls (unquoted word NULL)
       * strings (delimited with single quote marks);
       * note: leading and trailing percent mark (%) and underscore (_)
         can be used as wildcards in quoted strings for use with
         the LIKE and CLIKE operators
       * note: escaped single quote marks within strings are not
         supported, neither are embedded commas, use placeholders instead

  set_clause ::=
    * a comma-separated list of column = value pairs
    * see val_list for acceptable value formats
  where_clause ::=
    * a single "column/value <op> column/value" predicate, optionally
      preceded by "NOT"
    * note: multiple predicates combined with ORs or ANDs are not supported
    * see val_list for acceptable value formats
    * op may be one of:
         < > >= <= = <> LIKE CLIKE IS
    * CLIKE is a case insensitive LIKE
  order_clause ::= column_name [ASC|DESC]
    * a single column optional ORDER BY clause is supported
    * as in standard SQL, if neither ASC (ascending) nor
      DESC (descending) is specified, ASC becomes the default

ACKNOWLEDGEMENTS

Tim Bunce provided the original idea for this module, helped me out of the tangled trap of namespace, and provided help and advice all along the way. Although I wrote it from the ground up, it is based on Jochen Weidmann's orignal design of SQL::Statement, so much of the credit for the API goes to him.

AUTHOR AND COPYRIGHT

This module is written and maintained by

Jeff Zucker < jzucker AT cpan.org >

Copyright (C) 2004 by Jeff Zucker, all rights reserved.

You may freely distribute and/or modify this module under the terms of either the GNU General Public License (GPL) or the Artistic License, as specified in the Perl README file.


DBI::W32ODBC - An experimental DBI emulation layer for Win32::ODBC

    • Some Things Not Yet Implemented

NAME

DBI::W32ODBC - An experimental DBI emulation layer for Win32::ODBC

SYNOPSIS

  use DBI::W32ODBC;

  # apart from the line above everything is just the same as with
  # the real DBI when using a basic driver with few features.

DESCRIPTION

This is an experimental pure perl DBI emulation layer for Win32::ODBC

If you can improve this code I'd be interested in hearing about it. If you are having trouble using it please respect the fact that it's very experimental. Ideally fix it yourself and send me the details.

Some Things Not Yet Implemented

        Most attributes including PrintError & RaiseError.
        type_info and table_info

Volunteers welcome!


DBM_Filter -- Filter DBM keys/values

  • What is a DBM Filter?
    • So what's new?
  • METHODS
    • $db->Filter_Push()
    • $db->Filter_Key_Push()
    • $db->Filter_Value_Push()
    • $db->Filter_Pop()
    • $db->Filtered()
  • Writing a Filter
    • Immediate Filters
    • Canned Filters
  • Filters Included
  • NOTES
    • Maintain Round Trip Integrity
    • Don't mix filtered & non-filtered data in the same database file.
  • EXAMPLE
  • SEE ALSO
  • AUTHOR

NAME

DBM_Filter -- Filter DBM keys/values

SYNOPSIS

    use DBM_Filter ;
    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File

    $db = tie %hash, ...
    $db->Filter_Push(Fetch => sub {...},
                     Store => sub {...});

    $db->Filter_Push('my_filter1');
    $db->Filter_Push('my_filter2', params...);

    $db->Filter_Key_Push(...) ;
    $db->Filter_Value_Push(...) ;

    $db->Filter_Pop();
    $db->Filtered();

    package DBM_Filter::my_filter1;

    sub Store { ... }
    sub Fetch { ... }

    1;

    package DBM_Filter::my_filter2;

    sub Filter
    {
        my @opts = @_;
        ...
        return (
            sub Store { ... },
            sub Fetch { ... } );
    }

    1;

DESCRIPTION

This module provides an interface that allows filters to be applied to tied Hashes associated with DBM files. It builds on the DBM Filter hooks that are present in all the *DB*_File modules included with the standard Perl source distribution from version 5.6.1 onwards. In addition to the *DB*_File modules distributed with Perl, the BerkeleyDB module, available on CPAN, supports the DBM Filter hooks. See the perldbmfilter manpage for more details on the DBM Filter hooks.

What is a DBM Filter?

A DBM Filter allows the keys and/or values in a tied hash to be modified by some user-defined code just before it is written to the DBM file and just after it is read back from the DBM file. For example, this snippet of code

    $some_hash{"abc"} = 42;

could potentially trigger two filters, one for the writing of the key "abc" and another for writing the value 42. Similarly, this snippet

    my ($key, $value) = each %some_hash

will trigger two filters, one for the reading of the key and one for the reading of the value.

Like the existing DBM Filter functionality, this module arranges for the $_ variable to be populated with the key or value that a filter will check. This usually means that most DBM filters tend to be very short.

So what's new?

The main enhancements over the standard DBM Filter hooks are:

  • A cleaner interface.

  • The ability to easily apply multiple filters to a single DBM file.

  • The ability to create "canned" filters. These allow commonly used filters to be packaged into a stand-alone module.

METHODS

This module will arrange for the following methods to be available via the object returned from the tie call.

$db->Filter_Push()

$db->Filter_Key_Push()

$db->Filter_Value_Push()

Add a filter to filter stack for the database, $db. The three formats vary only in whether they apply to the DBM key, the DBM value or both.

Filter_Push

The filter is applied to both keys and values.

Filter_Key_Push

The filter is applied to the key only.

Filter_Value_Push

The filter is applied to the value only.

$db->Filter_Pop()

Removes the last filter that was applied to the DBM file associated with $db, if present.

$db->Filtered()

Returns TRUE if there are any filters applied to the DBM associated with $db. Otherwise returns FALSE.

Writing a Filter

Filters can be created in two main ways

Immediate Filters

An immediate filter allows you to specify the filter code to be used at the point where the filter is applied to a dbm. In this mode the Filter_*_Push methods expects to receive exactly two parameters.

    my $db = tie %hash, 'SDBM_File', ...
    $db->Filter_Push( Store => sub { },
                      Fetch => sub { });

The code reference associated with Store will be called before any key/value is written to the database and the code reference associated with Fetch will be called after any key/value is read from the database.

For example, here is a sample filter that adds a trailing NULL character to all strings before they are written to the DBM file, and removes the trailing NULL when they are read from the DBM file

    my $db = tie %hash, 'SDBM_File', ...
    $db->Filter_Push( Store => sub { $_ .= "\x00" ; },
                      Fetch => sub { s/\x00$// ;    });

Points to note:

  1. Both the Store and Fetch filters manipulate $_.

Canned Filters

Immediate filters are useful for one-off situations. For more generic problems it can be useful to package the filter up in its own module.

The usage is for a canned filter is:

    $db->Filter_Push("name", params)

where

"name"

is the name of the module to load. If the string specified does not contain the package separator characters "::", it is assumed to refer to the full module name "DBM_Filter::name". This means that the full names for canned filters, "null" and "utf8", included with this module are:

    DBM_Filter::null
    DBM_Filter::utf8
params

any optional parameters that need to be sent to the filter. See the encode filter for an example of a module that uses parameters.

The module that implements the canned filter can take one of two forms. Here is a template for the first

    package DBM_Filter::null ;

    use strict;
    use warnings;

    sub Store
    {
        # store code here
    }

    sub Fetch
    {
        # fetch code here
    }

    1;

Notes:

  1. The package name uses the DBM_Filter:: prefix.

  2. The module must have both a Store and a Fetch method. If only one is present, or neither are present, a fatal error will be thrown.

The second form allows the filter to hold state information using a closure, thus:

    package DBM_Filter::encoding ;

    use strict;
    use warnings;

    sub Filter
    {
        my @params = @_ ;

        ...
        return {
            Store   => sub { $_ = $encoding->encode($_) },
            Fetch   => sub { $_ = $encoding->decode($_) }
            } ;
            }

    1;

In this instance the "Store" and "Fetch" methods are encapsulated inside a "Filter" method.

Filters Included

A number of canned filers are provided with this module. They cover a number of the main areas that filters are needed when interfacing with DBM files. They also act as templates for your own filters.

The filter included are:

  • utf8

    This module will ensure that all data written to the DBM will be encoded in UTF-8.

    This module needs the Encode module.

  • encode

    Allows you to choose the character encoding will be store in the DBM file.

  • compress

    This filter will compress all data before it is written to the database and uncompressed it on reading.

    This module needs Compress::Zlib.

  • int32

    This module is used when interoperating with a C/C++ application that uses a C int as either the key and/or value in the DBM file.

  • null

    This module ensures that all data written to the DBM file is null terminated. This is useful when you have a perl script that needs to interoperate with a DBM file that a C program also uses. A fairly common issue is for the C application to include the terminating null in a string when it writes to the DBM file. This filter will ensure that all data written to the DBM file can be read by the C application.

NOTES

Maintain Round Trip Integrity

When writing a DBM filter it is very important to ensure that it is possible to retrieve all data that you have written when the DBM filter is in place. In practice, this means that whatever transformation is applied to the data in the Store method, the exact inverse operation should be applied in the Fetch method.

If you don't provide an exact inverse transformation, you will find that code like this will not behave as you expect.

     while (my ($k, $v) = each %hash)
     {
         ...
     }

Depending on the transformation, you will find that one or more of the following will happen

  1. The loop will never terminate.

  2. Too few records will be retrieved.

  3. Too many will be retrieved.

  4. The loop will do the right thing for a while, but it will unexpectedly fail.

Don't mix filtered & non-filtered data in the same database file.

This is just a restatement of the previous section. Unless you are completely certain you know what you are doing, avoid mixing filtered & non-filtered data.

EXAMPLE

Say you need to interoperate with a legacy C application that stores keys as C ints and the values and null terminated UTF-8 strings. Here is how you would set that up

    my $db = tie %hash, 'SDBM_File', ...
    $db->Filter_Key_Push('int32') ;

    $db->Filter_Value_Push('utf8');
    $db->Filter_Value_Push('null');

SEE ALSO

<DB_File>, GDBM_File, the NDBM_File manpage, ODBM_File, the SDBM_File manpage, the perldbmfilter manpage

AUTHOR

Paul Marquess <pmqs@cpan.org>


lib/DBM_Filter/compress.pm

  • DBM_Filter::compress
  • SYNOPSIS
  • SEE ALSO
  • AUTHOR

DBM_Filter::compress

SYNOPSIS

    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
    use DBM_Filter ;

    $db = tie %hash, ...
    $db->Filter_Push('compress');

    =head1 DESCRIPTION

This DBM filter will compress all data before it is written to the database and uncompressed it on reading.

A fatal error will be thrown if the Compress::Zlib module is not available.

SEE ALSO

the DBM_Filter manpage, the perldbmfilter manpage, the Compress::Zlib manpage

AUTHOR

Paul Marquess pmqs@cpan.org


lib/DBM_Filter/encode.pm

  • DBM_Filter::encode
  • SYNOPSIS
  • SEE ALSO
  • AUTHOR

DBM_Filter::encode

SYNOPSIS

    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
    use DBM_Filter ;

    $db = tie %hash, ...
    $db->Filter_Push('encode' => 'iso-8859-16');

    =head1 DESCRIPTION

This DBM filter allows you to choose the character encoding will be store in the DBM file. The usage is

    $db->Filter_Push('encode' => ENCODING);

where "ENCODING" must be a valid encoding name that the Encode module recognises.

A fatal error will be thrown if:

  1. The Encode module is not available.

  2. The encoding requested is not supported by the Encode module.

SEE ALSO

the DBM_Filter manpage, the perldbmfilter manpage, the Encode manpage

AUTHOR

Paul Marquess pmqs@cpan.org


lib/DBM_Filter/int32.pm

  • DBM_Filter::int32
  • SYNOPSIS
  • SEE ALSO
  • AUTHOR

DBM_Filter::int32

SYNOPSIS

    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
    use DBM_Filter ;

    $db = tie %hash, ...
    $db->Filter_Push('int32');

    =head1 DESCRIPTION

This DBM filter is used when interoperating with a C/C++ application that uses a C int as either the key and/or value in the DBM file.

SEE ALSO

the DBM_Filter manpage, the perldbmfilter manpage

AUTHOR

Paul Marquess pmqs@cpan.org


lib/DBM_Filter/null.pm

  • DBM_Filter::null
  • SYNOPSIS
  • SEE ALSO
  • AUTHOR

DBM_Filter::null

SYNOPSIS

    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
    use DBM_Filter ;

    $db = tie %hash, ...
    $db->Filter_Push('null');

    =head1 DESCRIPTION

This filter ensures that all data written to the DBM file is null terminated. This is useful when you have a perl script that needs to interoperate with a DBM file that a C program also uses. A fairly common issue is for the C application to include the terminating null in a string when it writes to the DBM file. This filter will ensure that all data written to the DBM file can be read by the C application.

SEE ALSO

the DBM_Filter manpage, the perldbmfilter manpage

AUTHOR

Paul Marquess pmqs@cpan.org


lib/DBM_Filter/utf8.pm

  • DBM_Filter::utf8
  • SYNOPSIS
  • SEE ALSO
  • AUTHOR

DBM_Filter::utf8

SYNOPSIS

    use SDBM_File; # or DB_File, or GDBM_File, or NDBM_File, or ODBM_File
    use DBM_Filter ;

    $db = tie %hash, ...
    $db->Filter_Push('utf8');

    =head1 DESCRIPTION

This Filter will ensure that all data written to the DBM will be encoded in UTF-8.

This module uses the Encode module.

SEE ALSO

the DBM_Filter manpage, the perldbmfilter manpage, the Encode manpage

AUTHOR

Paul Marquess pmqs@cpan.org


Data::Dump - Pretty printing of data structures

  • HISTORY
  • SEE ALSO
  • AUTHORS

NAME

Data::Dump - Pretty printing of data structures

SYNOPSIS

 use Data::Dump qw(dump);

 $str = dump(@list)
 @copy_of_list = eval $str;

DESCRIPTION

This module provides a single function called dump() that takes a list of values as its argument and produces a string as its result. The string contains Perl code that, when evaled, produces a deep copy of the original arguments. The string is formatted for easy reading.

If dump() is called in a void context, then the dump is printed on STDERR instead of being returned.

If you don't like importing a function that overrides Perl's not-so-useful builtin, then you can also import the same function as pp(), mnemonic for "pretty-print".

HISTORY

The Data::Dump module grew out of frustration with Sarathy's in-most-cases-excellent Data::Dumper. Basic ideas and some code are shared with Sarathy's module.

The Data::Dump module provides a much simpler interface than Data::Dumper. No OO interface is available and there are no configuration options to worry about (yet :-). The other benefit is that the dump produced does not try to set any variables. It only returns what is needed to produce a copy of the arguments. This means that dump("foo") simply returns "foo", and dump(1..5) simply returns (1, 2, 3, 4, 5).

SEE ALSO

the Data::Dumper manpage, the Storable manpage

AUTHORS

The Data::Dump module is written by Gisle Aas <gisle@aas.no>, based on Data::Dumper by Gurusamy Sarathy <gsar@umich.edu>.

 Copyright 1998-2000,2003-2004 Gisle Aas.
 Copyright 1996-1998 Gurusamy Sarathy.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Data::Dumper - stringified perl data structures, suitable for both printing and C<eval>

    • Methods
    • Functions
    • Configuration Variables or Methods
    • Exports
  • EXAMPLES
  • BUGS
    • NOTE
  • AUTHOR
  • VERSION
  • SEE ALSO

NAME

Data::Dumper - stringified perl data structures, suitable for both printing and eval

SYNOPSIS

    use Data::Dumper;

    # simple procedural interface
    print Dumper($foo, $bar);

    # extended usage with names
    print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);

    # configuration variables
    {
      local $Data::Dumper::Purity = 1;
      eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
    }

    # OO usage
    $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
       ...
    print $d->Dump;
       ...
    $d->Purity(1)->Terse(1)->Deepcopy(1);
    eval $d->Dump;

DESCRIPTION

Given a list of scalars or reference variables, writes out their contents in perl syntax. The references can also be objects. The contents of each variable is output in a single Perl statement. Handles self-referential structures correctly.

The return value can be evaled to get back an identical copy of the original reference structure.

Any references that are the same as one of those passed in will be named $VAR n (where n is a numeric suffix), and other duplicate references to substructures within $VAR n will be appropriately labeled using arrow notation. You can specify names for individual values to be dumped if you use the Dump() method, or you can change the default $VAR prefix to something else. See $Data::Dumper::Varname and $Data::Dumper::Terse below.

The default output of self-referential structures can be evaled, but the nested references to $VAR n will be undefined, since a recursive structure cannot be constructed using one Perl statement. You should set the Purity flag to 1 to get additional statements that will correctly fill in these references. Moreover, if evaled when strictures are in effect, you need to ensure that any variables it accesses are previously declared.

In the extended usage form, the references to be dumped can be given user-specified names. If a name begins with a *, the output will describe the dereferenced type of the supplied reference for hashes and arrays, and coderefs. Output of names will be avoided where possible if the Terse flag is set.

In many cases, methods that are used to set the internal state of the object will return the object itself, so method calls can be conveniently chained together.

Several styles of output are possible, all controlled by setting the Indent flag. See Configuration Variables or Methods below for details.

Methods

PACKAGE->new(ARRAYREF [, ARRAYREF])

Returns a newly created Data::Dumper object. The first argument is an anonymous array of values to be dumped. The optional second argument is an anonymous array of names for the values. The names need not have a leading $ sign, and must be comprised of alphanumeric characters. You can begin a name with a * to specify that the dereferenced type must be dumped instead of the reference itself, for ARRAY and HASH references.

The prefix specified by $Data::Dumper::Varname will be used with a numeric suffix if the name for a value is undefined.

Data::Dumper will catalog all references encountered while dumping the values. Cross-references (in the form of names of substructures in perl syntax) will be inserted at all possible points, preserving any structural interdependencies in the original set of values. Structure traversal is depth-first, and proceeds in order from the first supplied value to the last.

$OBJ->Dump or PACKAGE->Dump(ARRAYREF [, ARRAYREF])

Returns the stringified form of the values stored in the object (preserving the order in which they were supplied to new), subject to the configuration options below. In a list context, it returns a list of strings corresponding to the supplied values.

The second form, for convenience, simply calls the new method on its arguments before dumping the object immediately.

$OBJ->Seen([HASHREF])

Queries or adds to the internal table of already encountered references. You must use Reset to explicitly clear the table if needed. Such references are not dumped; instead, their names are inserted wherever they are encountered subsequently. This is useful especially for properly dumping subroutine references.

Expects an anonymous hash of name => value pairs. Same rules apply for names as in new. If no argument is supplied, will return the "seen" list of name => value pairs, in a list context. Otherwise, returns the object itself.

$OBJ->Values([ARRAYREF])

Queries or replaces the internal array of values that will be dumped. When called without arguments, returns the values. Otherwise, returns the object itself.

$OBJ->Names([ARRAYREF])

Queries or replaces the internal array of user supplied names for the values that will be dumped. When called without arguments, returns the names. Otherwise, returns the object itself.

$OBJ->Reset

Clears the internal table of "seen" references and returns the object itself.

Functions

Dumper(LIST)

Returns the stringified form of the values in the list, subject to the configuration options below. The values will be named $VAR n in the output, where n is a numeric suffix. Will return a list of strings in a list context.

Configuration Variables or Methods

Several configuration variables can be used to control the kind of output generated when using the procedural interface. These variables are usually localized in a block so that other parts of the code are not affected by the change.

These variables determine the default state of the object created by calling the new method, but cannot be used to alter the state of the object thereafter. The equivalent method names should be used instead to query or set the internal state of the object.

The method forms return the object itself when called with arguments, so that they can be chained together nicely.

  • $Data::Dumper::Indent or $OBJ->Indent([NEWVAL])

    Controls the style of indentation. It can be set to 0, 1, 2 or 3. Style 0 spews output without any newlines, indentation, or spaces between list items. It is the most compact format possible that can still be called valid perl. Style 1 outputs a readable form with newlines but no fancy indentation (each level in the structure is simply indented by a fixed amount of whitespace). Style 2 (the default) outputs a very readable form which takes into account the length of hash keys (so the hash value lines up). Style 3 is like style 2, but also annotates the elements of arrays with their index (but the comment is on its own line, so array output consumes twice the number of lines). Style 2 is the default.

  • $Data::Dumper::Purity or $OBJ->Purity([NEWVAL])

    Controls the degree to which the output can be evaled to recreate the supplied reference structures. Setting it to 1 will output additional perl statements that will correctly recreate nested references. The default is 0.

  • $Data::Dumper::Pad or $OBJ->Pad([NEWVAL])

    Specifies the string that will be prefixed to every line of the output. Empty string by default.

  • $Data::Dumper::Varname or $OBJ->Varname([NEWVAL])

    Contains the prefix to use for tagging variable names in the output. The default is "VAR".

  • $Data::Dumper::Useqq or $OBJ->Useqq([NEWVAL])

    When set, enables the use of double quotes for representing string values. Whitespace other than space will be represented as [\n\t\r], "unsafe" characters will be backslashed, and unprintable characters will be output as quoted octal integers. Since setting this variable imposes a performance penalty, the default is 0. Dump() will run slower if this flag is set, since the fast XSUB implementation doesn't support it yet.

  • $Data::Dumper::Terse or $OBJ->Terse([NEWVAL])

    When set, Data::Dumper will emit single, non-self-referential values as atoms/terms rather than statements. This means that the $VAR n names will be avoided where possible, but be advised that such output may not always be parseable by eval.

  • $Data::Dumper::Freezer or $OBJ->Freezer([NEWVAL])

    Can be set to a method name, or to an empty string to disable the feature. Data::Dumper will invoke that method via the object before attempting to stringify it. This method can alter the contents of the object (if, for instance, it contains data allocated from C), and even rebless it in a different package. The client is responsible for making sure the specified method can be called via the object, and that the object ends up containing only perl data types after the method has been called. Defaults to an empty string.

    If an object does not support the method specified (determined using UNIVERSAL::can()) then the call will be skipped. If the method dies a warning will be generated.

  • $Data::Dumper::Toaster or $OBJ->Toaster([NEWVAL])

    Can be set to a method name, or to an empty string to disable the feature. Data::Dumper will emit a method call for any objects that are to be dumped using the syntax bless(DATA, CLASS)->METHOD(). Note that this means that the method specified will have to perform any modifications required on the object (like creating new state within it, and/or reblessing it in a different package) and then return it. The client is responsible for making sure the method can be called via the object, and that it returns a valid object. Defaults to an empty string.

  • $Data::Dumper::Deepcopy or $OBJ->Deepcopy([NEWVAL])

    Can be set to a boolean value to enable deep copies of structures. Cross-referencing will then only be done when absolutely essential (i.e., to break reference cycles). Default is 0.

  • $Data::Dumper::Quotekeys or $OBJ->Quotekeys([NEWVAL])

    Can be set to a boolean value to control whether hash keys are quoted. A false value will avoid quoting hash keys when it looks like a simple string. Default is 1, which will always enclose hash keys in quotes.

  • $Data::Dumper::Bless or $OBJ->Bless([NEWVAL])

    Can be set to a string that specifies an alternative to the bless builtin operator used to create objects. A function with the specified name should exist, and should accept the same arguments as the builtin. Default is bless.

  • $Data::Dumper::Pair or $OBJ->Pair([NEWVAL])

    Can be set to a string that specifies the separator between hash keys and values. To dump nested hash, array and scalar values to JavaScript, use: $Data::Dumper::Pair = ' : ';. Implementing bless in JavaScript is left as an exercise for the reader. A function with the specified name exists, and accepts the same arguments as the builtin.

    Default is: => .

  • $Data::Dumper::Maxdepth or $OBJ->Maxdepth([NEWVAL])

    Can be set to a positive integer that specifies the depth beyond which which we don't venture into a structure. Has no effect when Data::Dumper::Purity is set. (Useful in debugger when we often don't want to see more than enough). Default is 0, which means there is no maximum depth.

  • $Data::Dumper::Useperl or $OBJ->Useperl([NEWVAL])

    Can be set to a boolean value which controls whether the pure Perl implementation of Data::Dumper is used. The Data::Dumper module is a dual implementation, with almost all functionality written in both pure Perl and also in XS ('C'). Since the XS version is much faster, it will always be used if possible. This option lets you override the default behavior, usually for testing purposes only. Default is 0, which means the XS implementation will be used if possible.

  • $Data::Dumper::Sortkeys or $OBJ->Sortkeys([NEWVAL])

    Can be set to a boolean value to control whether hash keys are dumped in sorted order. A true value will cause the keys of all hashes to be dumped in Perl's default sort order. Can also be set to a subroutine reference which will be called for each hash that is dumped. In this case Data::Dumper will call the subroutine once for each hash, passing it the reference of the hash. The purpose of the subroutine is to return a reference to an array of the keys that will be dumped, in the order that they should be dumped. Using this feature, you can control both the order of the keys, and which keys are actually used. In other words, this subroutine acts as a filter by which you can exclude certain keys from being dumped. Default is 0, which means that hash keys are not sorted.

  • $Data::Dumper::Deparse or $OBJ->Deparse([NEWVAL])

    Can be set to a boolean value to control whether code references are turned into perl source code. If set to a true value, B::Deparse will be used to get the source of the code reference. Using this option will force using the Perl implementation of the dumper, since the fast XSUB implementation doesn't support it.

    Caution : use this option only if you know that your coderefs will be properly reconstructed by B::Deparse.

Exports

Dumper

EXAMPLES

Run these code snippets to get a quick feel for the behavior of this module. When you are through with these examples, you may want to add or change the various configuration variables described above, to see their behavior. (See the testsuite in the Data::Dumper distribution for more examples.)

    use Data::Dumper;

    package Foo;
    sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};

    package Fuz;                       # a weird REF-REF-SCALAR object
    sub new {bless \($_ = \ 'fu\'z'), $_[0]};

    package main;
    $foo = Foo->new;
    $fuz = Fuz->new;
    $boo = [ 1, [], "abcd", \*foo,
             {1 => 'a', 023 => 'b', 0x45 => 'c'},
             \\"p\q\'r", $foo, $fuz];

    ########
    # simple usage
    ########

    $bar = eval(Dumper($boo));
    print($@) if $@;
    print Dumper($boo), Dumper($bar);  # pretty print (no array indices)

    $Data::Dumper::Terse = 1;          # don't output names where feasible
    $Data::Dumper::Indent = 0;         # turn off all pretty print
    print Dumper($boo), "\n";

    $Data::Dumper::Indent = 1;         # mild pretty print
    print Dumper($boo);

    $Data::Dumper::Indent = 3;         # pretty print with array indices
    print Dumper($boo);

    $Data::Dumper::Useqq = 1;          # print strings in double quotes
    print Dumper($boo);

    $Data::Dumper::Pair = " : ";       # specify hash key/value separator
    print Dumper($boo);

    ########
    # recursive structures
    ########

    @c = ('c');
    $c = \@c;
    $b = {};
    $a = [1, $b, $c];
    $b->{a} = $a;
    $b->{b} = $a->[1];
    $b->{c} = $a->[2];
    print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);

    $Data::Dumper::Purity = 1;         # fill in the holes for eval
    print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
    print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b

    $Data::Dumper::Deepcopy = 1;       # avoid cross-refs
    print Data::Dumper->Dump([$b, $a], [qw(*b a)]);

    $Data::Dumper::Purity = 0;         # avoid cross-refs
    print Data::Dumper->Dump([$b, $a], [qw(*b a)]);

    ########
    # deep structures
    ########

    $a = "pearl";
    $b = [ $a ];
    $c = { 'b' => $b };
    $d = [ $c ];
    $e = { 'd' => $d };
    $f = { 'e' => $e };
    print Data::Dumper->Dump([$f], [qw(f)]);

    $Data::Dumper::Maxdepth = 3;       # no deeper than 3 refs down
    print Data::Dumper->Dump([$f], [qw(f)]);

    ########
    # object-oriented usage
    ########

    $d = Data::Dumper->new([$a,$b], [qw(a b)]);
    $d->Seen({'*c' => $c});            # stash a ref without printing it
    $d->Indent(3);
    print $d->Dump;
    $d->Reset->Purity(0);              # empty the seen cache
    print join "----\n", $d->Dump;

    ########
    # persistence
    ########

    package Foo;
    sub new { bless { state => 'awake' }, shift }
    sub Freeze {
        my $s = shift;
        print STDERR "preparing to sleep\n";
        $s->{state} = 'asleep';
        return bless $s, 'Foo::ZZZ';
    }

    package Foo::ZZZ;
    sub Thaw {
        my $s = shift;
        print STDERR "waking up\n";
        $s->{state} = 'awake';
        return bless $s, 'Foo';
    }

    package Foo;
    use Data::Dumper;
    $a = Foo->new;
    $b = Data::Dumper->new([$a], ['c']);
    $b->Freezer('Freeze');
    $b->Toaster('Thaw');
    $c = $b->Dump;
    print $c;
    $d = eval $c;
    print Data::Dumper->Dump([$d], ['d']);

    ########
    # symbol substitution (useful for recreating CODE refs)
    ########

    sub foo { print "foo speaking\n" }
    *other = \&foo;
    $bar = [ \&other ];
    $d = Data::Dumper->new([\&other,$bar],['*other','bar']);
    $d->Seen({ '*foo' => \&foo });
    print $d->Dump;

    ########
    # sorting and filtering hash keys
    ########

    $Data::Dumper::Sortkeys = \&my_filter;
    my $foo = { map { (ord, "$_$_$_") } 'I'..'Q' };
    my $bar = { %$foo };
    my $baz = { reverse %$foo };
    print Dumper [ $foo, $bar, $baz ];

    sub my_filter {
        my ($hash) = @_;
        # return an array ref containing the hash keys to dump
        # in the order that you want them to be dumped
        return [
          # Sort the keys of %$foo in reverse numeric order
            $hash eq $foo ? (sort {$b <=> $a} keys %$hash) :
          # Only dump the odd number keys of %$bar
            $hash eq $bar ? (grep {$_ % 2} keys %$hash) :
          # Sort keys in default order for all other hashes
            (sort keys %$hash)
        ];
    }

BUGS

Due to limitations of Perl subroutine call semantics, you cannot pass an array or hash. Prepend it with a \ to pass its reference instead. This will be remedied in time, now that Perl has subroutine prototypes. For now, you need to use the extended usage form, and prepend the name with a * to output it as a hash or array.

Data::Dumper cheats with CODE references. If a code reference is encountered in the structure being processed (and if you haven't set the Deparse flag), an anonymous subroutine that contains the string '"DUMMY"' will be inserted in its place, and a warning will be printed if Purity is set. You can eval the result, but bear in mind that the anonymous sub that gets created is just a placeholder. Someday, perl will have a switch to cache-on-demand the string representation of a compiled piece of code, I hope. If you have prior knowledge of all the code refs that your data structures are likely to have, you can use the Seen method to pre-seed the internal reference table and make the dumped output point to them, instead. See EXAMPLES above.

The Useqq and Deparse flags makes Dump() run slower, since the XSUB implementation does not support them.

SCALAR objects have the weirdest looking bless workaround.

Pure Perl version of Data::Dumper escapes UTF-8 strings correctly only in Perl 5.8.0 and later.

NOTE

Starting from Perl 5.8.1 different runs of Perl will have different ordering of hash keys. The change was done for greater security, see Algorithmic Complexity Attacks in the perlsec manpage. This means that different runs of Perl will have different Data::Dumper outputs if the data contains hashes. If you need to have identical Data::Dumper outputs from different runs of Perl, use the environment variable PERL_HASH_SEED, see PERL_HASH_SEED in the perlrun manpage. Using this restores the old (platform-specific) ordering: an even prettier solution might be to use the Sortkeys filter of Data::Dumper.

AUTHOR

Gurusamy Sarathy gsar@activestate.com

Copyright (c) 1996-98 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.

VERSION

Version 2.121 (Aug 24 2003)

SEE ALSO

perl(1)


Date::Format - Date formating subroutines

  • MULTI-LANGUAGE SUPPORT
  • CONVERSION SPECIFICATION
  • AUTHOR
  • COPYRIGHT

NAME

Date::Format - Date formating subroutines

SYNOPSIS

        use Date::Format;

        @lt = localtime(time);

        print time2str($template, time);
        print strftime($template, @lt);

        print time2str($template, time, $zone);
        print strftime($template, @lt, $zone);

        print ctime(time);
        print asctime(@lt);

        print ctime(time, $zone);
        print asctime(@lt, $zone);

DESCRIPTION

This module provides routines to format dates into ASCII strings. They correspond to the C library routines strftime and ctime.

time2str(TEMPLATE, TIME [, ZONE])

time2str converts TIME into an ASCII string using the conversion specification given in TEMPLATE. ZONE if given specifies the zone which the output is required to be in, ZONE defaults to your current zone.

strftime(TEMPLATE, TIME [, ZONE])

strftime is similar to time2str with the exception that the time is passed as an array, such as the array returned by localtime.

ctime(TIME [, ZONE])

ctime calls time2str with the given arguments using the conversion specification "%a %b %e %T %Y\n"

asctime(TIME [, ZONE])

asctime calls time2str with the given arguments using the conversion specification "%a %b %e %T %Y\n"

MULTI-LANGUAGE SUPPORT

Date::Format is capable of formating into several languages, these are English, French, German and Italian. Changing the language is done via a static method call, for example

        Date::Format->language('German');

will change the language in which all subsequent dates are formatted.

This is only a first pass, I am considering changing this to be

        $lang = Date::Language->new('German');
        $lang->time2str("%a %b %e %T %Y\n", time);

I am open to suggestions on this.

CONVERSION SPECIFICATION

Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of the program's locale.

        %%      PERCENT
        %a      day of the week abbr
        %A      day of the week
        %b      month abbr
        %B      month
        %c      MM/DD/YY HH:MM:SS
        %C      ctime format: Sat Nov 19 21:05:57 1994
        %d      numeric day of the month, with leading zeros (eg 01..31)
        %e      numeric day of the month, without leading zeros (eg 1..31)
        %D      MM/DD/YY
        %G      GPS week number (weeks since January 6, 1980)
        %h      month abbr
        %H      hour, 24 hour clock, leading 0's)
        %I      hour, 12 hour clock, leading 0's)
        %j      day of the year
        %k      hour
        %l      hour, 12 hour clock
        %L      month number, starting with 1
        %m      month number, starting with 01
        %M      minute, leading 0's
        %n      NEWLINE
        %o      ornate day of month -- "1st", "2nd", "25th", etc.
        %p      AM or PM
        %P      am or pm (Yes %p and %P are backwards :)
        %q      Quarter number, starting with 1
        %r      time format: 09:05:57 PM
        %R      time format: 21:05
        %s      seconds since the Epoch, UCT
        %S      seconds, leading 0's
        %t      TAB
        %T      time format: 21:05:57
        %U      week number, Sunday as first day of week
        %w      day of the week, numerically, Sunday == 0
        %W      week number, Monday as first day of week
        %x      date format: 11/19/94
        %X      time format: 21:05:57
        %y      year (2 digits)
        %Y      year (4 digits)
        %Z      timezone in ascii. eg: PST
        %z      timezone in format -/+0000

%d, %e, %H, %I, %j, %k, %l, %m, %M, %q, %y and %Y can be output in Roman numerals by prefixing the letter with O, e.g. %OY will output the year as roman numerals.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995-1999 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Date::Parse - Parse date strings into time values

  • MULTI-LANGUAGE SUPPORT
  • EXAMPLE DATES
  • LIMITATION
  • BUGS
  • AUTHOR
  • COPYRIGHT

NAME

Date::Parse - Parse date strings into time values

SYNOPSIS

        use Date::Parse;

        $time = str2time($date);

        ($ss,$mm,$hh,$day,$month,$year,$zone) = strptime($date);

DESCRIPTION

Date::Parse provides two routines for parsing date strings into time values.

str2time(DATE [, ZONE])

str2time parses DATE and returns a unix time value, or undef upon failure. ZONE, if given, specifies the timezone to assume when parsing if the date string does not specify a timezome.

strptime(DATE [, ZONE])

strptime takes the same arguments as str2time but returns an array of values ($ss,$mm,$hh,$day,$month,$year,$zone). Elements are only defined if they could be extracted from the date string. The $zone element is the timezone offset in seconds from GMT. An empty array is returned upon failure.

MULTI-LANGUAGE SUPPORT

Date::Parse is capable of parsing dates in several languages, these are English, French, German and Italian.

        $lang = Date::Language->new('German');
        $lang->str2time("25 Jun 1996 21:09:55 +0100");

EXAMPLE DATES

Below is a sample list of dates that are known to be parsable with Date::Parse

 1995:01:24T09:08:17.1823213           ISO-8601
 1995-01-24T09:08:17.1823213
 Wed, 16 Jun 94 07:29:35 CST           Comma and day name are optional
 Thu, 13 Oct 94 10:13:13 -0700
 Wed, 9 Nov 1994 09:50:32 -0500 (EST)  Text in ()'s will be ignored.
 21 dec 17:05                          Will be parsed in the current time zone
 21-dec 17:05
 21/dec 17:05
 21/dec/93 17:05
 1999 10:02:18 "GMT"
 16 Nov 94 22:28:20 PST

LIMITATION

Date::Parse uses Time::Local internally, so is limited to only parsing dates which result in valid values for Time::Local::timelocal

BUGS

When both the month and the date are specified in the date as numbers they are always parsed assuming that the month number comes before the date. This is the usual format used in American dates.

The reason why it is like this and not dynamic is that it must be deterministic. Several people have suggested using the current locale, but this will not work as the date being parsed may not be in the format of the current locale.

My plans to address this, which will be in a future release, is to allow the programmer to state what order they want these values parsed in.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Devel::DProf - a Perl code profiler

  • PROFILE FORMAT
  • AUTOLOAD
  • ENVIRONMENT
  • BUGS
  • SEE ALSO

NAME

Devel::DProf - a Perl code profiler

SYNOPSIS

        perl -d:DProf test.pl

DESCRIPTION

The Devel::DProf package is a Perl code profiler. This will collect information on the execution time of a Perl script and of the subs in that script. This information can be used to determine which subroutines are using the most time and which subroutines are being called most often. This information can also be used to create an execution graph of the script, showing subroutine relationships.

To profile a Perl script run the perl interpreter with the -d debugging switch. The profiler uses the debugging hooks. So to profile script test.pl the following command should be used:

        perl -d:DProf test.pl

When the script terminates (or when the output buffer is filled) the profiler will dump the profile information to a file called tmon.out. A tool like dprofpp can be used to interpret the information which is in that profile. The following command will print the top 15 subroutines which used the most time:

        dprofpp

To print an execution graph of the subroutines in the script use the following command:

        dprofpp -T

Consult dprofpp for other options.

PROFILE FORMAT

The old profile is a text file which looks like this:

        #fOrTyTwO
        $hz=100;
        $XS_VERSION='DProf 19970606';
        # All values are given in HZ
        $rrun_utime=2; $rrun_stime=0; $rrun_rtime=7
        PART2
        + 26 28 566822884 DynaLoader::import
        - 26 28 566822884 DynaLoader::import
        + 27 28 566822885 main::bar
        - 27 28 566822886 main::bar
        + 27 28 566822886 main::baz
        + 27 28 566822887 main::bar
        - 27 28 566822888 main::bar
        [....]

The first line is the magic number. The second line is the hertz value, or clock ticks, of the machine where the profile was collected. The third line is the name and version identifier of the tool which created the profile. The fourth line is a comment. The fifth line contains three variables holding the user time, system time, and realtime of the process while it was being profiled. The sixth line indicates the beginning of the sub entry/exit profile section.

The columns in PART2 are:

        sub entry(+)/exit(-) mark
        app's user time at sub entry/exit mark, in ticks
        app's system time at sub entry/exit mark, in ticks
        app's realtime at sub entry/exit mark, in ticks
        fully-qualified sub name, when possible

With newer perls another format is used, which may look like this:

        #fOrTyTwO
        $hz=10000;
        $XS_VERSION='DProf 19971213';
        # All values are given in HZ
        $over_utime=5917; $over_stime=0; $over_rtime=5917;
        $over_tests=10000;
        $rrun_utime=1284; $rrun_stime=0; $rrun_rtime=1284;
        $total_marks=6;

        PART2
        @ 406 0 406
        & 2 main bar
        + 2
        @ 456 0 456
        - 2
        @ 1 0 1
        & 3 main baz
        + 3
        @ 141 0 141
        + 2
        @ 141 0 141
        - 2
        @ 1 0 1
        & 4 main foo
        + 4
        @ 142 0 142
        + & Devel::DProf::write
        @ 5 0 5
        - & Devel::DProf::write

(with high value of $ENV{PERL_DPROF_TICKS}).

New $over_* values show the measured overhead of making $over_tests calls to the profiler These values are used by the profiler to subtract the overhead from the runtimes.

The lines starting with @ mark time passed from the previous @ line. The lines starting with & introduce new subroutine id and show the package and the subroutine name of this id. Lines starting with +, - and * mark entering and exit of subroutines by ids, and goto &subr.

The old-style +- and --lines are used to mark the overhead related to writing to profiler-output file.

AUTOLOAD

When Devel::DProf finds a call to an &AUTOLOAD subroutine it looks at the $AUTOLOAD variable to find the real name of the sub being called. See Autoloading in the perlsub manpage.

ENVIRONMENT

PERL_DPROF_BUFFER sets size of output buffer in words. Defaults to 2**14.

PERL_DPROF_TICKS sets number of ticks per second on some systems where a replacement for times() is used. Defaults to the value of HZ macro.

PERL_DPROF_OUT_FILE_NAME sets the name of the output file. If not set, defaults to tmon.out.

BUGS

Builtin functions cannot be measured by Devel::DProf.

With a newer Perl DProf relies on the fact that the numeric slot of $DB::sub contains an address of a subroutine. Excessive manipulation of this variable may overwrite this slot, as in

  $DB::sub = 'current_sub';
  ...
  $addr = $DB::sub + 0;

will set this numeric slot to numeric value of the string current_sub, i.e., to 0. This will cause a segfault on the exit from this subroutine. Note that the first assignment above does not change the numeric slot (it will mark it as invalid, but will not write over it).

Another problem is that if a subroutine exits using goto(LABEL), last(LABEL) or next(LABEL) then perl may crash or Devel::DProf will die with the error:

   panic: Devel::DProf inconsistent subroutine return

For example, this code will break under Devel::DProf:

   sub foo {
     last FOO;
   }
   FOO: {
     foo();
   }

A pattern like this is used by Test::More's skip() function, for example. See the perldiag manpage for more details.

Mail bug reports and feature requests to the perl5-porters mailing list at <perl5-porters@perl.org>.

SEE ALSO

the perl manpage, dprofpp, times(2)


Devel::InnerPackage - find all the inner packages of a package

  • METHODS
    • list_packages <package name>
  • AUTHOR
  • COPYING
  • BUGS

NAME

Devel::InnerPackage - find all the inner packages of a package

SYNOPSIS

    use Foo::Bar;
    use Devel::innerPackage qw(list_packages);

    my @inner_packages = list_packages('Foo::Bar');

DESCRIPTION

Given a file like this

    package Foo::Bar;

    sub foo {}

    package Foo::Bar::Quux;

    sub quux {}

    package Foo::Bar::Quirka;

    sub quirka {}

    1;

then

    list_packages('Foo::Bar');

will return

    Foo::Bar::Quux
    Foo::Bar::Quirka

METHODS

list_packages <package name>

Return a list of all inner packages of that package.

AUTHOR

Simon Wistow <simon@thegestalt.org>

COPYING

Copyright, 2005 Simon Wistow

Distributed under the same terms as Perl itself.

BUGS

None known.


Devel::PPPort - Perl/Pollution/Portability

    • Why use ppport.h?
    • How to use ppport.h
    • Running ppport.h
  • FUNCTIONS
    • WriteFile
  • COMPATIBILITY
    • Provided Perl compatibility API
    • Perl API not supported by ppport.h
  • BUGS
  • AUTHORS
  • COPYRIGHT
  • SEE ALSO

NAME

Devel::PPPort - Perl/Pollution/Portability

SYNOPSIS

    Devel::PPPort::WriteFile();   # defaults to ./ppport.h
    Devel::PPPort::WriteFile('someheader.h');

DESCRIPTION

Perl's API has changed over time, gaining new features, new functions, increasing its flexibility, and reducing the impact on the C namespace environment (reduced pollution). The header file written by this module, typically ppport.h, attempts to bring some of the newer Perl API features to older versions of Perl, so that you can worry less about keeping track of old releases, but users can still reap the benefit.

Devel::PPPort contains a single function, called WriteFile. Its only purpose is to write the ppport.h C header file. This file contains a series of macros and, if explicitly requested, functions that allow XS modules to be built using older versions of Perl. Currently, Perl versions from 5.003 to 5.9.3 are supported.

This module is used by h2xs to write the file ppport.h.

Why use ppport.h?

You should use ppport.h in modern code so that your code will work with the widest range of Perl interpreters possible, without significant additional work.

You should attempt older code to fully use ppport.h, because the reduced pollution of newer Perl versions is an important thing. It's so important that the old polluting ways of original Perl modules will not be supported very far into the future, and your module will almost certainly break! By adapting to it now, you'll gain compatibility and a sense of having done the electronic ecology some good.

How to use ppport.h

Don't direct the users of your module to download Devel::PPPort. They are most probably no XS writers. Also, don't make ppport.h optional. Rather, just take the most recent copy of ppport.h that you can find (e.g. by generating it with the latest Devel::PPPort release from CPAN), copy it into your project, adjust your project to use it, and distribute the header along with your module.

Running ppport.h

But ppport.h is more than just a C header. It's also a Perl script that can check your source code. It will suggest hints and portability notes, and can even make suggestions on how to change your code. You can run it like any other Perl program:

    perl ppport.h [options] [files]

It also has embedded documentation, so you can use

    perldoc ppport.h

to find out more about how to use it.

FUNCTIONS

WriteFile

WriteFile takes one optional argument. When called with one argument, it expects to be passed a filename. When called with no arguments, it defaults to the filename ppport.h.

The function returns a true value if the file was written successfully. Otherwise it returns a false value.

COMPATIBILITY

ppport.h supports Perl versions from 5.003 to 5.9.3 in threaded and non-threaded configurations.

Provided Perl compatibility API

The header file written by this module, typically ppport.h, provides access to the following elements of the Perl API that is not available in older Perl releases:

    _aMY_CXT
    _pMY_CXT
    aMY_CXT
    aMY_CXT_
    aTHX
    aTHX_
    AvFILLp
    boolSV
    call_argv
    call_method
    call_pv
    call_sv
    CopFILE
    CopFILE_set
    CopFILEAV
    CopFILEGV
    CopFILEGV_set
    CopFILESV
    CopSTASH
    CopSTASH_eq
    CopSTASH_set
    CopSTASHPV
    CopSTASHPV_set
    CopyD
    dAX
    DEFSV
    dITEMS
    dMY_CXT
    dMY_CXT_SV
    dNOOP
    dTHR
    dTHX
    dTHXa
    dTHXoa
    dUNDERBAR
    dXCPT
    dXSTARG
    END_EXTERN_C
    ERRSV
    eval_pv
    eval_sv
    EXTERN_C
    get_av
    get_cv
    get_hv
    get_sv
    grok_bin
    grok_hex
    grok_number
    GROK_NUMERIC_RADIX
    grok_numeric_radix
    grok_oct
    gv_stashpvn
    IN_LOCALE
    IN_LOCALE_COMPILETIME
    IN_LOCALE_RUNTIME
    IN_PERL_COMPILETIME
    INT2PTR
    IS_NUMBER_GREATER_THAN_UV_MAX
    IS_NUMBER_IN_UV
    IS_NUMBER_INFINITY
    IS_NUMBER_NAN
    IS_NUMBER_NEG
    IS_NUMBER_NOT_INT
    IVdf
    IVSIZE
    IVTYPE
    memEQ
    memNE
    MoveD
    mPUSHi
    mPUSHn
    mPUSHp
    mPUSHu
    mXPUSHi
    mXPUSHn
    mXPUSHp
    mXPUSHu
    MY_CXT
    MY_CXT_CLONE
    MY_CXT_INIT
    newCONSTSUB
    newRV_inc
    newRV_noinc
    newSVpvn
    newSVuv
    NOOP
    NUM2PTR
    NVef
    NVff
    NVgf
    NVTYPE
    PERL_BCDVERSION
    PERL_GCC_BRACE_GROUPS_FORBIDDEN
    PERL_INT_MAX
    PERL_INT_MIN
    PERL_LONG_MAX
    PERL_LONG_MIN
    PERL_MAGIC_arylen
    PERL_MAGIC_backref
    PERL_MAGIC_bm
    PERL_MAGIC_collxfrm
    PERL_MAGIC_dbfile
    PERL_MAGIC_dbline
    PERL_MAGIC_defelem
    PERL_MAGIC_env
    PERL_MAGIC_envelem
    PERL_MAGIC_ext
    PERL_MAGIC_fm
    PERL_MAGIC_glob
    PERL_MAGIC_isa
    PERL_MAGIC_isaelem
    PERL_MAGIC_mutex
    PERL_MAGIC_nkeys
    PERL_MAGIC_overload
    PERL_MAGIC_overload_elem
    PERL_MAGIC_overload_table
    PERL_MAGIC_pos
    PERL_MAGIC_qr
    PERL_MAGIC_regdata
    PERL_MAGIC_regdatum
    PERL_MAGIC_regex_global
    PERL_MAGIC_shared
    PERL_MAGIC_shared_scalar
    PERL_MAGIC_sig
    PERL_MAGIC_sigelem
    PERL_MAGIC_substr
    PERL_MAGIC_sv
    PERL_MAGIC_taint
    PERL_MAGIC_tied
    PERL_MAGIC_tiedelem
    PERL_MAGIC_tiedscalar
    PERL_MAGIC_utf8
    PERL_MAGIC_uvar
    PERL_MAGIC_uvar_elem
    PERL_MAGIC_vec
    PERL_MAGIC_vstring
    PERL_QUAD_MAX
    PERL_QUAD_MIN
    PERL_REVISION
    PERL_SCAN_ALLOW_UNDERSCORES
    PERL_SCAN_DISALLOW_PREFIX
    PERL_SCAN_GREATER_THAN_UV_MAX
    PERL_SCAN_SILENT_ILLDIGIT
    PERL_SHORT_MAX
    PERL_SHORT_MIN
    PERL_SUBVERSION
    PERL_UCHAR_MAX
    PERL_UCHAR_MIN
    PERL_UINT_MAX
    PERL_UINT_MIN
    PERL_ULONG_MAX
    PERL_ULONG_MIN
    PERL_UNUSED_DECL
    PERL_UQUAD_MAX
    PERL_UQUAD_MIN
    PERL_USHORT_MAX
    PERL_USHORT_MIN
    PERL_VERSION
    PL_compiling
    PL_copline
    PL_curcop
    PL_curstash
    PL_DBsingle
    PL_DBsub
    PL_debstash
    PL_defgv
    PL_diehook
    PL_dirty
    PL_dowarn
    PL_errgv
    PL_hexdigit
    PL_hints
    PL_na
    PL_no_modify
    PL_perl_destruct_level
    PL_perldb
    PL_ppaddr
    PL_rsfp
    PL_rsfp_filters
    PL_stack_base
    PL_stack_sp
    PL_stdingv
    PL_Sv
    PL_sv_arenaroot
    PL_sv_no
    PL_sv_undef
    PL_sv_yes
    PL_tainted
    PL_tainting
    pMY_CXT
    pMY_CXT_
    Poison
    pTHX
    pTHX_
    PTR2IV
    PTR2NV
    PTR2ul
    PTR2UV
    PTRV
    PUSHmortal
    PUSHu
    SAVE_DEFSV
    START_EXTERN_C
    START_MY_CXT
    STMT_END
    STMT_START
    sv_2pv_nolen
    sv_2pvbyte
    sv_2uv
    sv_catpv_mg
    sv_catpvf_mg
    sv_catpvf_mg_nocontext
    sv_catpvn_mg
    sv_catpvn_nomg
    sv_catsv_mg
    sv_catsv_nomg
    sv_pvn
    sv_pvn_force
    sv_pvn_nomg
    sv_setiv_mg
    sv_setnv_mg
    sv_setpv_mg
    sv_setpvf_mg
    sv_setpvf_mg_nocontext
    sv_setpvn_mg
    sv_setsv_mg
    sv_setsv_nomg
    sv_setuv
    sv_setuv_mg
    sv_usepvn_mg
    sv_uv
    sv_vcatpvf
    sv_vcatpvf_mg
    sv_vsetpvf
    sv_vsetpvf_mg
    SvGETMAGIC
    SvIV_nomg
    SvPV_force_nomg
    SvPV_nolen
    SvPV_nomg
    SvPVbyte
    SvUV
    SvUV_nomg
    SvUVX
    SvUVx
    SvUVXx
    UNDERBAR
    UVof
    UVSIZE
    UVTYPE
    UVuf
    UVXf
    UVxf
    vnewSVpvf
    XCPT_CATCH
    XCPT_RETHROW
    XCPT_TRY_END
    XCPT_TRY_START
    XPUSHmortal
    XPUSHu
    XSRETURN_UV
    XST_mUV
    ZeroD

Perl API not supported by ppport.h

There is still a big part of the API not supported by ppport.h. Either because it doesn't make sense to back-port that part of the API, or simply because it hasn't been implemented yet. Patches welcome!

Here's a list of the currently unsupported API, and also the version of Perl below which it is unsupported:

perl 5.9.3
  SvMAGIC_set
  SvRV_set
  SvSTASH_set
  SvUV_set
  av_arylen_p
  dAXMARK
  hv_eiter_p
  hv_eiter_set
  hv_name_set
  hv_placeholders_get
  hv_placeholders_p
  hv_placeholders_set
  hv_riter_p
  hv_riter_set
  is_utf8_string_loclen
  newSVhek
  newWHILEOP
  stashpv_hvname_match
perl 5.9.2
  SvPVbyte_force
  find_rundefsvoffset
  gv_fetchpvn_flags
  gv_fetchsv
  op_refcnt_lock
  op_refcnt_unlock
  savesvpv
  vnormal
perl 5.9.1
  hv_assert
  hv_clear_placeholders
  hv_scalar
  scan_version
  sv_2iv_flags
  sv_2uv_flags
perl 5.9.0
  new_version
  save_set_svflags
  upg_version
  vcmp
  vnumify
  vstringify
perl 5.8.3
  SvIsCOW
  SvIsCOW_shared_hash
perl 5.8.1
  SvVOK
  doing_taint
  is_utf8_string_loc
  packlist
  save_bool
  savestack_grow_cnt
  scan_vstring
  sv_cat_decode
  sv_compile_2op
  sv_setpviv
  sv_setpviv_mg
  unpackstring
perl 5.8.0
  hv_iternext_flags
  hv_store_flags
  is_utf8_idcont
  nothreadhook
perl 5.7.3
  PerlIO_clearerr
  PerlIO_close
  PerlIO_eof
  PerlIO_error
  PerlIO_fileno
  PerlIO_fill
  PerlIO_flush
  PerlIO_get_base
  PerlIO_get_bufsiz
  PerlIO_get_cnt
  PerlIO_get_ptr
  PerlIO_read
  PerlIO_seek
  PerlIO_set_cnt
  PerlIO_set_ptrcnt
  PerlIO_setlinebuf
  PerlIO_stderr
  PerlIO_stdin
  PerlIO_stdout
  PerlIO_tell
  PerlIO_unread
  PerlIO_write
  SvLOCK
  SvSHARE
  SvUNLOCK
  atfork_lock
  atfork_unlock
  custom_op_desc
  custom_op_name
  deb
  debstack
  debstackptrs
  gv_fetchmeth_autoload
  ibcmp_utf8
  my_fork
  my_socketpair
  pack_cat
  perl_destruct
  pv_uni_display
  regclass_swash
  save_shared_pvref
  savesharedpv
  sortsv
  sv_copypv
  sv_magicext
  sv_nolocking
  sv_nosharing
  sv_nounlocking
  sv_recode_to_utf8
  sv_uni_display
  to_uni_fold
  to_uni_lower
  to_uni_title
  to_uni_upper
  to_utf8_case
  to_utf8_fold
  to_utf8_lower
  to_utf8_title
  to_utf8_upper
  unpack_str
  uvchr_to_utf8_flags
  uvuni_to_utf8_flags
  vdeb
perl 5.7.2
  calloc
  getcwd_sv
  init_tm
  malloc
  mfree
  mini_mktime
  my_atof2
  my_strftime
  op_null
  realloc
  sv_2pv_flags
  sv_catpvn_flags
  sv_catsv_flags
  sv_pvn_force_flags
  sv_setsv_flags
  sv_utf8_upgrade_flags
  swash_fetch
perl 5.7.1
  POPpbytex
  SvUOK
  bytes_from_utf8
  csighandler
  despatch_signals
  do_openn
  gv_handler
  is_lvalue_sub
  my_popen_list
  newSVpvn_share
  save_mortalizesv
  save_padsv
  scan_num
  sv_force_normal_flags
  sv_setref_uv
  sv_unref_flags
  sv_utf8_upgrade
  utf8_length
  utf8_to_uvchr
  utf8_to_uvuni
  utf8n_to_uvchr
  utf8n_to_uvuni
  uvchr_to_utf8
  uvuni_to_utf8
perl 5.6.1
  apply_attrs_string
  bytes_to_utf8
  gv_efullname4
  gv_fullname4
  is_utf8_string
  save_generic_pvref
  utf16_to_utf8
  utf16_to_utf8_reversed
  utf8_to_bytes
perl 5.6.0
  SvIOK_UV
  SvIOK_notUV
  SvIOK_only_UV
  SvPOK_only_UTF8
  SvPVbyte_nolen
  SvPVbytex
  SvPVbytex_force
  SvPVutf8
  SvPVutf8_force
  SvPVutf8_nolen
  SvPVutf8x
  SvPVutf8x_force
  SvUTF8
  SvUTF8_off
  SvUTF8_on
  av_delete
  av_exists
  call_atexit
  cast_i32
  cast_iv
  cast_ulong
  cast_uv
  do_gv_dump
  do_gvgv_dump
  do_hv_dump
  do_magic_dump
  do_op_dump
  do_open9
  do_pmop_dump
  do_sv_dump
  dump_all
  dump_eval
  dump_form
  dump_indent
  dump_packsubs
  dump_sub
  dump_vindent
  get_context
  get_ppaddr
  gv_dump
  init_i18nl10n
  init_i18nl14n
  is_uni_alnum
  is_uni_alnum_lc
  is_uni_alnumc
  is_uni_alnumc_lc
  is_uni_alpha
  is_uni_alpha_lc
  is_uni_ascii
  is_uni_ascii_lc
  is_uni_cntrl
  is_uni_cntrl_lc
  is_uni_digit
  is_uni_digit_lc
  is_uni_graph
  is_uni_graph_lc
  is_uni_idfirst
  is_uni_idfirst_lc
  is_uni_lower
  is_uni_lower_lc
  is_uni_print
  is_uni_print_lc
  is_uni_punct
  is_uni_punct_lc
  is_uni_space
  is_uni_space_lc
  is_uni_upper
  is_uni_upper_lc
  is_uni_xdigit
  is_uni_xdigit_lc
  is_utf8_alnum
  is_utf8_alnumc
  is_utf8_alpha
  is_utf8_ascii
  is_utf8_char
  is_utf8_cntrl
  is_utf8_digit
  is_utf8_graph
  is_utf8_idfirst
  is_utf8_lower
  is_utf8_mark
  is_utf8_print
  is_utf8_punct
  is_utf8_space
  is_utf8_upper
  is_utf8_xdigit
  load_module
  magic_dump
  mess
  my_atof
  my_fflush_all
  newANONATTRSUB
  newATTRSUB
  newMYSUB
  newPADOP
  newXS
  newXSproto
  new_collate
  new_ctype
  new_numeric
  op_dump
  perl_parse
  pmop_dump
  pv_display
  re_intuit_start
  re_intuit_string
  reginitcolors
  require_pv
  safesyscalloc
  safesysfree
  safesysmalloc
  safesysrealloc
  save_I8
  save_alloc
  save_destructor
  save_destructor_x
  save_re_context
  save_vptr
  scan_bin
  set_context
  set_numeric_local
  set_numeric_radix
  set_numeric_standard
  str_to_version
  sv_2pvutf8
  sv_2pvutf8_nolen
  sv_force_normal
  sv_len_utf8
  sv_pos_b2u
  sv_pos_u2b
  sv_pv
  sv_pvbyte
  sv_pvbyten
  sv_pvbyten_force
  sv_pvutf8
  sv_pvutf8n
  sv_pvutf8n_force
  sv_rvweaken
  sv_utf8_decode
  sv_utf8_downgrade
  sv_utf8_encode
  swash_init
  tmps_grow
  to_uni_lower_lc
  to_uni_title_lc
  to_uni_upper_lc
  utf8_distance
  utf8_hop
  vcroak
  vform
  vload_module
  vmess
  vwarn
  vwarner
  warner
perl 5.005_03
  POPpx
  get_vtbl
  save_generic_svref
perl 5.005
  PL_modglobal
  cx_dump
  debop
  debprofdump
  fbm_compile
  fbm_instr
  get_op_descs
  get_op_names
  init_stacks
  mg_length
  mg_size
  newHVhv
  new_stackinfo
  regdump
  regexec_flags
  regnext
  runops_debug
  runops_standard
  save_hints
  save_iv
  save_threadsv
  screaminstr
  sv_iv
  sv_nv
  sv_peek
  sv_true
perl 5.004_05
  do_binmode
  save_aelem
  save_helem
perl 5.004
  GIMME_V
  G_VOID
  HEf_SVKEY
  HeHASH
  HeKEY
  HeKLEN
  HePV
  HeSVKEY
  HeSVKEY_force
  HeSVKEY_set
  HeVAL
  SvSetMagicSV
  SvSetMagicSV_nosteal
  SvSetSV_nosteal
  SvTAINTED
  SvTAINTED_off
  SvTAINTED_on
  block_gimme
  call_list
  cv_const_sv
  delimcpy
  do_open
  form
  gv_autoload4
  gv_efullname3
  gv_fetchmethod_autoload
  gv_fullname3
  hv_delayfree_ent
  hv_delete_ent
  hv_exists_ent
  hv_fetch_ent
  hv_free_ent
  hv_iterkeysv
  hv_ksplit
  hv_store_ent
  ibcmp_locale
  my_failure_exit
  my_memcmp
  my_pclose
  my_popen
  newSVpvf
  rsignal
  rsignal_state
  save_I16
  save_gp
  start_subparse
  sv_catpvf
  sv_catpvf_mg
  sv_cmp_locale
  sv_derived_from
  sv_gets
  sv_setpvf
  sv_setpvf_mg
  sv_taint
  sv_tainted
  sv_untaint
  sv_vcatpvf
  sv_vcatpvf_mg
  sv_vcatpvfn
  sv_vsetpvf
  sv_vsetpvf_mg
  sv_vsetpvfn
  unsharepvn
  vnewSVpvf

BUGS

If you find any bugs, Devel::PPPort doesn't seem to build on your system or any of its tests fail, please use the CPAN Request Tracker at http://rt.cpan.org/ to create a ticket for the module.

AUTHORS

  • Version 1.x of Devel::PPPort was written by Kenneth Albanowski.

  • Version 2.x was ported to the Perl core by Paul Marquess.

  • Version 3.x was ported back to CPAN by Marcus Holland-Moritz.

COPYRIGHT

Version 3.x, Copyright (C) 2004-2005, Marcus Holland-Moritz.

Version 2.x, Copyright (C) 2001, Paul Marquess.

Version 1.x, Copyright (C) 1999, Kenneth Albanowski.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See h2xs, ppport.h.


Devel::Peek - A data debugging tool for the XS programmer

    • Runtime debugging
    • Memory footprint debugging
  • EXAMPLES
    • A simple scalar string
    • A simple scalar number
    • A simple scalar with an extra reference
    • A reference to a simple scalar
    • A reference to an array
    • A reference to a hash
    • Dumping a large array or hash
    • A reference to an SV which holds a C pointer
    • A reference to a subroutine
  • EXPORTS
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

Devel::Peek - A data debugging tool for the XS programmer

SYNOPSIS

        use Devel::Peek;
        Dump( $a );
        Dump( $a, 5 );
        DumpArray( 5, $a, $b, ... );
        mstat "Point 5";

        use Devel::Peek ':opd=st';

DESCRIPTION

Devel::Peek contains functions which allows raw Perl datatypes to be manipulated from a Perl script. This is used by those who do XS programming to check that the data they are sending from C to Perl looks as they think it should look. The trick, then, is to know what the raw datatype is supposed to look like when it gets to Perl. This document offers some tips and hints to describe good and bad raw data.

It is very possible that this document will fall far short of being useful to the casual reader. The reader is expected to understand the material in the first few sections of the perlguts manpage.

Devel::Peek supplies a Dump() function which can dump a raw Perl datatype, and mstat("marker") function to report on memory usage (if perl is compiled with corresponding option). The function DeadCode() provides statistics on the data "frozen" into inactive CV. Devel::Peek also supplies SvREFCNT(), SvREFCNT_inc(), and SvREFCNT_dec() which can query, increment, and decrement reference counts on SVs. This document will take a passive, and safe, approach to data debugging and for that it will describe only the Dump() function.

Function DumpArray() allows dumping of multiple values (useful when you need to analyze returns of functions).

The global variable $Devel::Peek::pv_limit can be set to limit the number of character printed in various string values. Setting it to 0 means no limit.

If use Devel::Peek directive has a :opd=FLAGS argument, this switches on debugging of opcode dispatch. FLAGS should be a combination of s, t, and P (see -D flags in the perlrun manpage). :opd is a shortcut for :opd=st.

Runtime debugging

CvGV($cv) return one of the globs associated to a subroutine reference $cv.

debug_flags() returns a string representation of $^D (similar to what is allowed for -D flag). When called with a numeric argument, sets $^D to the corresponding value. When called with an argument of the form "flags-flags", set on/off bits of $^D corresponding to letters before/after -. (The returned value is for $^D before the modification.)

runops_debug() returns true if the current opcode dispatcher is the debugging one. When called with an argument, switches to debugging or non-debugging dispatcher depending on the argument (active for newly-entered subs/etc only). (The returned value is for the dispatcher before the modification.)

Memory footprint debugging

When perl is compiled with support for memory footprint debugging (default with Perl's malloc()), Devel::Peek provides an access to this API.

Use mstat() function to emit a memory state statistic to the terminal. For more information on the format of output of mstat() see Using $ENV{PERL_DEBUG_MSTATS} in the perldebguts manpage.

Three additional functions allow access to this statistic from Perl. First, use mstats_fillhash(%hash) to get the information contained in the output of mstat() into %hash. The field of this hash are

  minbucket nbuckets sbrk_good sbrk_slack sbrked_remains sbrks start_slack
  topbucket topbucket_ev topbucket_odd total total_chain total_sbrk totfree

Two additional fields free, used contain array references which provide per-bucket count of free and used chunks. Two other fields mem_size, available_size contain array references which provide the information about the allocated size and usable size of chunks in each bucket. Again, see Using $ENV{PERL_DEBUG_MSTATS} in the perldebguts manpage for details.

Keep in mind that only the first several "odd-numbered" buckets are used, so the information on size of the "odd-numbered" buckets which are not used is probably meaningless.

The information in

 mem_size available_size minbucket nbuckets

is the property of a particular build of perl, and does not depend on the current process. If you do not provide the optional argument to the functions mstats_fillhash(), fill_mstats(), mstats2hash(), then the information in fields mem_size, available_size is not updated.

fill_mstats($buf) is a much cheaper call (both speedwise and memory-wise) which collects the statistic into $buf in machine-readable form. At a later moment you may need to call mstats2hash($buf, %hash) to use this information to fill %hash.

All three APIs fill_mstats($buf), mstats_fillhash(%hash), and mstats2hash($buf, %hash) are designed to allocate no memory if used the second time on the same $buf and/or %hash.

So, if you want to collect memory info in a cycle, you may call

  $#buf = 999;
  fill_mstats($_) for @buf;
  mstats_fillhash(%report, 1);          # Static info too

  foreach (@buf) {
    # Do something...
    fill_mstats $_;                     # Collect statistic
  }
  foreach (@buf) {
    mstats2hash($_, %report);           # Preserve static info
    # Do something with %report
  }

EXAMPLES

The following examples don't attempt to show everything as that would be a monumental task, and, frankly, we don't want this manpage to be an internals document for Perl. The examples do demonstrate some basics of the raw Perl datatypes, and should suffice to get most determined people on their way. There are no guidewires or safety nets, nor blazed trails, so be prepared to travel alone from this point and on and, if at all possible, don't fall into the quicksand (it's bad for business).

Oh, one final bit of advice: take the perlguts manpage with you. When you return we expect to see it well-thumbed.

A simple scalar string

Let's begin by looking a simple scalar which is holding a string.

        use Devel::Peek;
        $a = "hello";
        Dump $a;

The output:

        SV = PVIV(0xbc288)
          REFCNT = 1
          FLAGS = (POK,pPOK)
          IV = 0
          PV = 0xb2048 "hello"\0
          CUR = 5
          LEN = 6

This says $a is an SV, a scalar. The scalar is a PVIV, a string. Its reference count is 1. It has the POK flag set, meaning its current PV field is valid. Because POK is set we look at the PV item to see what is in the scalar. The \0 at the end indicate that this PV is properly NUL-terminated. If the FLAGS had been IOK we would look at the IV item. CUR indicates the number of characters in the PV. LEN indicates the number of bytes requested for the PV (one more than CUR, in this case, because LEN includes an extra byte for the end-of-string marker).

A simple scalar number

If the scalar contains a number the raw SV will be leaner.

        use Devel::Peek;
        $a = 42;
        Dump $a;

The output:

        SV = IV(0xbc818)
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 42

This says $a is an SV, a scalar. The scalar is an IV, a number. Its reference count is 1. It has the IOK flag set, meaning it is currently being evaluated as a number. Because IOK is set we look at the IV item to see what is in the scalar.

A simple scalar with an extra reference

If the scalar from the previous example had an extra reference:

        use Devel::Peek;
        $a = 42;
        $b = \$a;
        Dump $a;

The output:

        SV = IV(0xbe860)
          REFCNT = 2
          FLAGS = (IOK,pIOK)
          IV = 42

Notice that this example differs from the previous example only in its reference count. Compare this to the next example, where we dump $b instead of $a.

A reference to a simple scalar

This shows what a reference looks like when it references a simple scalar.

        use Devel::Peek;
        $a = 42;
        $b = \$a;
        Dump $b;

The output:

        SV = RV(0xf041c)
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xbab08
        SV = IV(0xbe860)
          REFCNT = 2
          FLAGS = (IOK,pIOK)
          IV = 42

Starting from the top, this says $b is an SV. The scalar is an RV, a reference. It has the ROK flag set, meaning it is a reference. Because ROK is set we have an RV item rather than an IV or PV. Notice that Dump follows the reference and shows us what $b was referencing. We see the same $a that we found in the previous example.

Note that the value of RV coincides with the numbers we see when we stringify $b. The addresses inside RV() and IV() are addresses of X*** structure which holds the current state of an SV. This address may change during lifetime of an SV.

A reference to an array

This shows what a reference to an array looks like.

        use Devel::Peek;
        $a = [42];
        Dump $a;

The output:

        SV = RV(0xf041c)
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb2850
        SV = PVAV(0xbd448)
          REFCNT = 1
          FLAGS = ()
          IV = 0
          NV = 0
          ARRAY = 0xb2048
          ALLOC = 0xb2048
          FILL = 0
          MAX = 0
          ARYLEN = 0x0
          FLAGS = (REAL)
        Elt No. 0 0xb5658
        SV = IV(0xbe860)
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 42

This says $a is an SV and that it is an RV. That RV points to another SV which is a PVAV, an array. The array has one element, element zero, which is another SV. The field FILL above indicates the last element in the array, similar to $#$a.

If $a pointed to an array of two elements then we would see the following.

        use Devel::Peek 'Dump';
        $a = [42,24];
        Dump $a;

The output:

        SV = RV(0xf041c)
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb2850
        SV = PVAV(0xbd448)
          REFCNT = 1
          FLAGS = ()
          IV = 0
          NV = 0
          ARRAY = 0xb2048
          ALLOC = 0xb2048
          FILL = 0
          MAX = 0
          ARYLEN = 0x0
          FLAGS = (REAL)
        Elt No. 0  0xb5658
        SV = IV(0xbe860)
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 42
        Elt No. 1  0xb5680
        SV = IV(0xbe818)
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 24

Note that Dump will not report all the elements in the array, only several first (depending on how deep it already went into the report tree).

A reference to a hash

The following shows the raw form of a reference to a hash.

        use Devel::Peek;
        $a = {hello=>42};
        Dump $a;

The output:

        SV = RV(0x8177858) at 0x816a618
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0x814fc10
          SV = PVHV(0x8167768) at 0x814fc10
            REFCNT = 1
            FLAGS = (SHAREKEYS)
            IV = 1
            NV = 0
            ARRAY = 0x816c5b8  (0:7, 1:1)
            hash quality = 100.0%
            KEYS = 1
            FILL = 1
            MAX = 7
            RITER = -1
            EITER = 0x0
            Elt "hello" HASH = 0xc8fd181b
            SV = IV(0x816c030) at 0x814fcf4
              REFCNT = 1
              FLAGS = (IOK,pIOK)
              IV = 42

This shows $a is a reference pointing to an SV. That SV is a PVHV, a hash. Fields RITER and EITER are used by each.

The "quality" of a hash is defined as the total number of comparisons needed to access every element once, relative to the expected number needed for a random hash. The value can go over 100%.

The total number of comparisons is equal to the sum of the squares of the number of entries in each bucket. For a random hash of <n> keys into <k> buckets, the expected value is:

                n + n(n-1)/2k

Dumping a large array or hash

The Dump() function, by default, dumps up to 4 elements from a toplevel array or hash. This number can be increased by supplying a second argument to the function.

        use Devel::Peek;
        $a = [10,11,12,13,14];
        Dump $a;

Notice that Dump() prints only elements 10 through 13 in the above code. The following code will print all of the elements.

        use Devel::Peek 'Dump';
        $a = [10,11,12,13,14];
        Dump $a, 5;

A reference to an SV which holds a C pointer

This is what you really need to know as an XS programmer, of course. When an XSUB returns a pointer to a C structure that pointer is stored in an SV and a reference to that SV is placed on the XSUB stack. So the output from an XSUB which uses something like the T_PTROBJ map might look something like this:

        SV = RV(0xf381c)
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb8ad8
        SV = PVMG(0xbb3c8)
          REFCNT = 1
          FLAGS = (OBJECT,IOK,pIOK)
          IV = 729160
          NV = 0
          PV = 0
          STASH = 0xc1d10       "CookBookB::Opaque"

This shows that we have an SV which is an RV. That RV points at another SV. In this case that second SV is a PVMG, a blessed scalar. Because it is blessed it has the OBJECT flag set. Note that an SV which holds a C pointer also has the IOK flag set. The STASH is set to the package name which this SV was blessed into.

The output from an XSUB which uses something like the T_PTRREF map, which doesn't bless the object, might look something like this:

        SV = RV(0xf381c)
          REFCNT = 1
          FLAGS = (ROK)
          RV = 0xb8ad8
        SV = PVMG(0xbb3c8)
          REFCNT = 1
          FLAGS = (IOK,pIOK)
          IV = 729160
          NV = 0
          PV = 0

A reference to a subroutine

Looks like this:

        SV = RV(0x798ec)
          REFCNT = 1
          FLAGS = (TEMP,ROK)
          RV = 0x1d453c
        SV = PVCV(0x1c768c)
          REFCNT = 2
          FLAGS = ()
          IV = 0
          NV = 0
          COMP_STASH = 0x31068  "main"
          START = 0xb20e0
          ROOT = 0xbece0
          XSUB = 0x0
          XSUBANY = 0
          GVGV::GV = 0x1d44e8   "MY" :: "top_targets"
          FILE = "(eval 5)"
          DEPTH = 0
          PADLIST = 0x1c9338

This shows that

  • the subroutine is not an XSUB (since START and ROOT are non-zero, and XSUB is zero);

  • that it was compiled in the package main;

  • under the name MY::top_targets;

  • inside a 5th eval in the program;

  • it is not currently executed (see DEPTH);

  • it has no prototype (PROTOTYPE field is missing).

EXPORTS

Dump, mstat, DeadCode, DumpArray, DumpWithOP and DumpProg, fill_mstats, mstats_fillhash, mstats2hash by default. Additionally available SvREFCNT, SvREFCNT_inc and SvREFCNT_dec.

BUGS

Readers have been known to skip important parts of the perlguts manpage, causing much frustration for all.

AUTHOR

Ilya Zakharevich ilya@math.ohio-state.edu

Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Author of this software makes no claim whatsoever about suitability, reliability, edability, editability or usability of this product, and should not be kept liable for any damage resulting from the use of it. If you can use it, you are in luck, if not, I should not be kept responsible. Keep a handy copy of your backup tape at hand.

SEE ALSO

the perlguts manpage, and the perlguts manpage, again.


Devel::SelfStubber - generate stubs for a SelfLoading module

NAME

Devel::SelfStubber - generate stubs for a SelfLoading module

SYNOPSIS

To generate just the stubs:

    use Devel::SelfStubber;
    Devel::SelfStubber->stub('MODULENAME','MY_LIB_DIR');

or to generate the whole module with stubs inserted correctly

    use Devel::SelfStubber;
    $Devel::SelfStubber::JUST_STUBS=0;
    Devel::SelfStubber->stub('MODULENAME','MY_LIB_DIR');

MODULENAME is the Perl module name, e.g. Devel::SelfStubber, NOT 'Devel/SelfStubber' or 'Devel/SelfStubber.pm'.

MY_LIB_DIR defaults to '.' if not present.

DESCRIPTION

Devel::SelfStubber prints the stubs you need to put in the module before the __DATA__ token (or you can get it to print the entire module with stubs correctly placed). The stubs ensure that if a method is called, it will get loaded. They are needed specifically for inherited autoloaded methods.

This is best explained using the following example:

Assume four classes, A,B,C & D.

A is the root class, B is a subclass of A, C is a subclass of B, and D is another subclass of A.

                        A
                       / \
                      B   D
                     /
                    C

If D calls an autoloaded method 'foo' which is defined in class A, then the method is loaded into class A, then executed. If C then calls method 'foo', and that method was reimplemented in class B, but set to be autoloaded, then the lookup mechanism never gets to the AUTOLOAD mechanism in B because it first finds the method already loaded in A, and so erroneously uses that. If the method foo had been stubbed in B, then the lookup mechanism would have found the stub, and correctly loaded and used the sub from B.

So, for classes and subclasses to have inheritance correctly work with autoloading, you need to ensure stubs are loaded.

The SelfLoader can load stubs automatically at module initialization with the statement 'SelfLoader->load_stubs()';, but you may wish to avoid having the stub loading overhead associated with your initialization (though note that the SelfLoader::load_stubs method will be called sooner or later - at latest when the first sub is being autoloaded). In this case, you can put the sub stubs before the __DATA__ token. This can be done manually, but this module allows automatic generation of the stubs.

By default it just prints the stubs, but you can set the global $Devel::SelfStubber::JUST_STUBS to 0 and it will print out the entire module with the stubs positioned correctly.

At the very least, this is useful to see what the SelfLoader thinks are stubs - in order to ensure future versions of the SelfStubber remain in step with the SelfLoader, the SelfStubber actually uses the SelfLoader to determine which stubs are needed.


Devel::StackTrace - Stack trace and stack trace frame objects

  • 'TOP' AND 'BOTTOM' OF THE STACK
  • Devel::StackTrace METHODS
  • Devel::StackTraceFrame METHODS
    • These only contain data as of Perl 5.6.0 or later
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

Devel::StackTrace - Stack trace and stack trace frame objects

SYNOPSIS

  use Devel::StackTrace;

  my $trace = Devel::StackTrace->new;

  print $trace->as_string; # like carp

  # from top (most recent) of stack to bottom.
  while (my $frame = $trace->next_frame)
  {
      print "Has args\n" if $frame->hasargs;
  }

  # from bottom (least recent) of stack to top.
  while (my $frame = $trace->prev_frame)
  {
      print "Sub: ", $frame->subroutine, "\n";
  }

DESCRIPTION

The Devel::StackTrace module contains two classes, Devel::StackTrace and Devel::StackTraceFrame. The goal of this object is to encapsulate the information that can found through using the caller() function, as well as providing a simple interface to this data.

The Devel::StackTrace object contains a set of Devel::StackTraceFrame objects, one for each level of the stack. The frames contain all the data available from caller() as of Perl 5.6.0 though this module still works with 5.00503.

This code was created to support my the Exception::Class::Base manpage class (part of Exception::Class) but may be useful in other contexts.

'TOP' AND 'BOTTOM' OF THE STACK

When describing the methods of the trace object, I use the words 'top' and 'bottom'. In this context, the 'top' frame on the stack is the most recent frame and the 'bottom' is the least recent.

Here's an example:

  foo();  # bottom frame is here

  sub foo
  {
     bar();
  }

  sub bar
  {
     Devel::StackTrace->new;  # top frame is here.
  }

Devel::StackTrace METHODS

  • Devel::StackTrace->new(%named_params)

    Returns a new Devel::StackTrace object.

    Takes the following parameters:

    • ignore_package => $package_name OR \@package_names

      Any frames where the package is one of these packages will not be on the stack.

    • ignore_class => $package_name OR \@package_names

      Any frames where the package is a subclass of one of these packages (or is the same package) will not be on the stack.

      Devel::StackTrace internally adds itself to the 'ignore_package' parameter, meaning that the Devel::StackTrace package is ALWAYS ignored. However, if you create a subclass of Devel::StackTrace it will not be ignored.

    • no_refs => $boolean

      If this parameter is true, then Devel::StackTrace will not store references internally when generating stacktrace frames. This lets your objects go out of scope.

      Devel::StackTrace replaces any references with their stringified representation.

    • respect_overload => $boolean

      By default, Devel::StackTrace will call overload::StrVal() to get the underlying string representation of an object, instead of respecting the object's stringification overloading. If you would prefer to see the overloaded representation of objects in stack traces, then set this parameter to true.

  • $trace->next_frame

    Returns the next Devel::StackTraceFrame object down on the stack. If it hasn't been called before it returns the first frame. It returns undef when it reaches the bottom of the stack and then resets its pointer so the next call to next_frame or prev_frame will work properly.

  • $trace->prev_frame

    Returns the next Devel::StackTraceFrame object up on the stack. If it hasn't been called before it returns the last frame. It returns undef when it reaches the top of the stack and then resets its pointer so pointer so the next call to next_frame or prev_frame will work properly.

  • $trace->reset_pointer

    Resets the pointer so that the next call next_frame or prev_frame will start at the top or bottom of the stack, as appropriate.

  • $trace->frames

    Returns a list of Devel::StackTraceFrame objects. The order they are returned is from top (most recent) to bottom.

  • $trace->frame ($index)

    Given an index, returns the relevant frame or undef if there is not frame at that index. The index is exactly like a Perl array. The first frame is 0 and negative indexes are allowed.

  • $trace->frame_count

    Returns the number of frames in the trace object.

  • $trace->as_string

    Calls as_string on each frame from top to bottom, producing output quite similar to the Carp module's cluck/confess methods.

Devel::StackTraceFrame METHODS

See the caller documentation for more information on what these methods return.

  • $frame->package
  • $frame->filename
  • $frame->line
  • $frame->subroutine
  • $frame->hasargs
  • $frame->wantarray
  • $frame->evaltext

    Returns undef if the frame was not part of an eval.

  • $frame->is_require

    Returns undef if the frame was not part of a require.

  • $frame->args

    Returns the arguments passed to the frame. Note that any arguments that are references are returned as references, not copies.

These only contain data as of Perl 5.6.0 or later

  • $frame->hints
  • $frame->bitmask

SUPPORT

Please submit bugs to the CPAN RT system at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel%3A%3AStackTrace or via email at bug-devel-stacktrace@rt.cpan.org.

AUTHOR

Dave Rolsky, <autarch@urth.org>

COPYRIGHT

Copyright (c) 2000-2006 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Digest - Modules that calculate message digests

  • OO INTERFACE
  • Digest speed
  • SEE ALSO
  • AUTHOR

NAME

Digest - Modules that calculate message digests

SYNOPSIS

  $md5  = Digest->new("MD5");
  $sha1 = Digest->new("SHA-1");
  $sha256 = Digest->new("SHA-256");
  $sha384 = Digest->new("SHA-384");
  $sha512 = Digest->new("SHA-512");

  $hmac = Digest->HMAC_MD5($key);

DESCRIPTION

The Digest:: modules calculate digests, also called "fingerprints" or "hashes", of some data, called a message. The digest is (usually) some small/fixed size string. The actual size of the digest depend of the algorithm used. The message is simply a sequence of arbitrary bytes or bits.

An important property of the digest algorithms is that the digest is likely to change if the message change in some way. Another property is that digest functions are one-way functions, that is it should be hard to find a message that correspond to some given digest. Algorithms differ in how "likely" and how "hard", as well as how efficient they are to compute.

Note that the properties of the algorithms change over time, as the algorithms are analyzed and machines grow faster. If your application for instance depends on it being "impossible" to generate the same digest for a different message it is wise to make it easy to plug in stronger algorithms as the one used grow weaker. Using the interface documented here should make it easy to change algorithms later.

All Digest:: modules provide the same programming interface. A functional interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly.

The digest can be delivered in three formats:

binary

This is the most compact form, but it is not well suited for printing or embedding in places that can't handle arbitrary data.

hex

A twice as long string of lowercase hexadecimal digits.

base64

A string of portable printable characters. This is the base64 encoded representation of the digest with any trailing padding removed. The string will be about 30% longer than the binary version. the MIME::Base64 manpage tells you more about this encoding.

The functional interface is simply importable functions with the same name as the algorithm. The functions take the message as argument and return the digest. Example:

  use Digest::MD5 qw(md5);
  $digest = md5($message);

There are also versions of the functions with "_hex" or "_base64" appended to the name, which returns the digest in the indicated form.

OO INTERFACE

The following methods are available for all Digest:: modules:

$ctx = Digest->XXX($arg,...)
$ctx = Digest->new(XXX => $arg,...)
$ctx = Digest::XXX->new($arg,...)

The constructor returns some object that encapsulate the state of the message-digest algorithm. You can add data to the object and finally ask for the digest. The "XXX" should of course be replaced by the proper name of the digest algorithm you want to use.

The two first forms are simply syntactic sugar which automatically load the right module on first use. The second form allow you to use algorithm names which contains letters which are not legal perl identifiers, e.g. "SHA-1". If no implementation for the given algorithm can be found, then an exception is raised.

If new() is called as an instance method (i.e. $ctx->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case, and the return value is the reference to the object (i.e. $ctx).

$other_ctx = $ctx->clone

The clone method creates a copy of the digest state object and returns a reference to the copy.

$ctx->reset

This is just an alias for $ctx->new.

$ctx->add( $data, ... )

The $data provided as argument are appended to the message we calculate the digest for. The return value is the $ctx object itself.

$ctx->addfile( $io_handle )

The $io_handle is read until EOF and the content is appended to the message we calculate the digest for. The return value is the $ctx object itself.

$ctx->add_bits( $data, $nbits )
$ctx->add_bits( $bitstring )

The bits provided are appended to the message we calculate the digest for. The return value is the $ctx object itself.

The two argument form of add_bits() will add the first $nbits bits from data. For the last potentially partial byte only the high order $nbits % 8 bits are used. If $nbits is greater than < length($data) * 8 >, then this method would do the same as < $ctx- add($data) >>, that is $nbits is silently ignored.

The one argument form of add_bits() takes a $bitstring of "1" and "0" chars as argument. It's a shorthand for $ctx->add_bits(pack("B*", $bitstring), length($bitstring)).

This example shows two calls that should have the same effect:

   $ctx->add_bits("111100001010");
   $ctx->add_bits("\xF0\xA0", 12);

Most digest algorithms are byte based. For those it is not possible to add bits that are not a multiple of 8, and the add_bits() method will croak if you try.

$ctx->digest

Return the binary digest for the message.

Note that the digest operation is effectively a destructive, read-once operation. Once it has been performed, the $ctx object is automatically reset and can be used to calculate another digest value. Call $ctx->clone->digest if you want to calculate the digest without reseting the digest state.

$ctx->hexdigest

Same as $ctx->digest, but will return the digest in hexadecimal form.

$ctx->b64digest

Same as $ctx->digest, but will return the digest as a base64 encoded string.

Digest speed

This table should give some indication on the relative speed of different algorithms. It is sorted by throughput based on a benchmark done with of some implementations of this API:

 Algorithm      Size    Implementation                  MB/s
 MD4            128     Digest::MD4 v1.3               165.0
 MD5            128     Digest::MD5 v2.33               98.8
 SHA-256        256     Digest::SHA2 v1.1.0             66.7
 SHA-1          160     Digest::SHA v4.3.1              58.9
 SHA-1          160     Digest::SHA1 v2.10              48.8
 SHA-256        256     Digest::SHA v4.3.1              41.3
 Haval-256      256     Digest::Haval256 v1.0.4         39.8
 SHA-384        384     Digest::SHA2 v1.1.0             19.6
 SHA-512        512     Digest::SHA2 v1.1.0             19.3
 SHA-384        384     Digest::SHA v4.3.1              19.2
 SHA-512        512     Digest::SHA v4.3.1              19.2
 Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
 MD2            128     Digest::MD2 v2.03                9.5
 Adler-32        32     Digest::Adler32 v0.03            1.3
 CRC-16          16     Digest::CRC v0.05                1.1
 CRC-32          32     Digest::CRC v0.05                1.1
 MD5            128     Digest::Perl::MD5 v1.5           1.0
 CRC-CCITT       16     Digest::CRC v0.05                0.8

These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running under Linux on a P4 2.8 GHz CPU. The last 5 entries differ by being pure perl implementations of the algorithms, which explains why they are so slow.

SEE ALSO

the Digest::Adler32 manpage, the Digest::CRC manpage, the Digest::Haval256 manpage, the Digest::HMAC manpage, the Digest::MD2 manpage, the Digest::MD4 manpage, the Digest::MD5 manpage, the Digest::SHA manpage, the Digest::SHA1 manpage, the Digest::SHA2 manpage, the Digest::Whirlpool manpage

New digest implementations should consider subclassing from the Digest::base manpage.

the MIME::Base64 manpage

AUTHOR

Gisle Aas <gisle@aas.no>

The Digest:: interface is based on the interface originally developed by Neil Winton for his MD5 module.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

    Copyright 1998-2001,2003-2004 Gisle Aas.
    Copyright 1995-1996 Neil Winton.


Digest::HMAC - Keyed-Hashing for Message Authentication

  • SEE ALSO
  • AUTHORS

NAME

Digest::HMAC - Keyed-Hashing for Message Authentication

SYNOPSIS

 # Functional style
 use Digest::HMAC qw(hmac hmac_hex);
 $digest = hmac($data, $key, \&myhash);
 print hmac_hex($data, $key, \&myhash);

 # OO style
 use Digest::HMAC;
 $hmac = Digest::HMAC->new($key, "Digest::MyHash");

 $hmac->add($data);
 $hmac->addfile(*FILE);

 $digest = $hmac->digest;
 $digest = $hmac->hexdigest;
 $digest = $hmac->b64digest;

DESCRIPTION

HMAC is used for message integrity checks between two parties that share a secret key, and works in combination with some other Digest algorithm, usually MD5 or SHA-1. The HMAC mechanism is described in RFC 2104.

HMAC follow the common Digest:: interface, but the constructor takes the secret key and the name of some other simple Digest:: as argument.

SEE ALSO

the Digest::HMAC_MD5 manpage, the Digest::HMAC_SHA1 manpage

RFC 2104

AUTHORS

Graham Barr <gbarr@ti.com>, Gisle Aas <gisle@aas.no>


Digest::HMAC_MD5 - Keyed-Hashing for Message Authentication

  • SEE ALSO
  • AUTHOR

NAME

Digest::HMAC_MD5 - Keyed-Hashing for Message Authentication

SYNOPSIS

 # Functional style
 use Digest::HMAC_MD5 qw(hmac_md5 hmac_md5_hex);
 $digest = hmac_md5($data, $key);
 print hmac_md5_hex($data, $key);

 # OO style
 use Digest::HMAC_MD5;
 $hmac = Digest::HMAC_MD5->new($key);

 $hmac->add($data);
 $hmac->addfile(*FILE);

 $digest = $hmac->digest;
 $digest = $hmac->hexdigest;
 $digest = $hmac->b64digest;

DESCRIPTION

This module provide HMAC-MD5 hashing.

SEE ALSO

the Digest::HMAC manpage, the Digest::MD5 manpage, the Digest::HMAC_SHA1 manpage

AUTHOR

Gisle Aas <gisle@aas.no>


Digest::HMAC_SHA1 - Keyed-Hashing for Message Authentication

  • SEE ALSO
  • AUTHOR

NAME

Digest::HMAC_SHA1 - Keyed-Hashing for Message Authentication

SYNOPSIS

 # Functional style
 use Digest::HMAC_SHA1 qw(hmac_sha1 hmac_sha1_hex);
 $digest = hmac_sha1($data, $key);
 print hmac_sha1_hex($data, $key);

 # OO style
 use Digest::HMAC_SHA1;
 $hmac = Digest::HMAC_SHA1->new($key);

 $hmac->add($data);
 $hmac->addfile(*FILE);

 $digest = $hmac->digest;
 $digest = $hmac->hexdigest;
 $digest = $hmac->b64digest;

DESCRIPTION

This module provide HMAC-SHA-1 hashing.

SEE ALSO

the Digest::HMAC manpage, the Digest::SHA1 manpage, the Digest::HMAC_MD5 manpage

AUTHOR

Gisle Aas <gisle@aas.no>


Digest::MD2 - Perl interface to the MD2 Algorithm

  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

Digest::MD2 - Perl interface to the MD2 Algorithm

SYNOPSIS

 # Functional style
 use Digest::MD2  qw(md2 md2_hex md2_base64);

 $digest = md2($data);
 $digest = md2_hex($data);
 $digest = md2_base64($data);

 # OO style
 use Digest::MD2;

 $ctx = Digest::MD2->new;

 $ctx->add($data);
 $ctx->addfile(*FILE);

 $digest = $ctx->digest;
 $digest = $ctx->hexdigest;
 $digest = $ctx->b64digest;

DESCRIPTION

The Digest::MD2 module allows you to use the RSA Data Security Inc. MD2 Message Digest algorithm from within Perl programs. The algorithm takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input.

The Digest::MD2 programming interface is identical to the interface of Digest::MD5.

SEE ALSO

the Digest::MD5 manpage

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Copyright 1998-2003 Gisle Aas.
 Copyright 1990-1992 RSA Data Security, Inc.

AUTHOR

Gisle Aas <gisle@aas.no>


Digest::MD4 - Perl interface to the MD4 Algorithm

  • FUNCTIONS
  • METHODS
  • EXAMPLES
  • SEE ALSO
  • COPYRIGHT
  • AUTHORS

NAME

Digest::MD4 - Perl interface to the MD4 Algorithm

SYNOPSIS

 # Functional style
 use Digest::MD4 qw(md4 md4_hex md4_base64);

 $digest = md4($data);
 $digest = md4_hex($data);
 $digest = md4_base64($data);

 # OO style
 use Digest::MD4;

 $ctx = Digest::MD4->new;

 $ctx->add($data);
 $ctx->addfile(*FILE);

 $digest = $ctx->digest;
 $digest = $ctx->hexdigest;
 $digest = $ctx->b64digest;

DESCRIPTION

The Digest::MD4 module allows you to use the RSA Data Security Inc. MD4 Message Digest algorithm from within Perl programs. The algorithm takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input.

The Digest::MD4 module provide a procedural interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly.

FUNCTIONS

The following functions are provided by the Digest::MD4 module. None of these functions are exported by default.

md4($data,...)

This function will concatenate all arguments, calculate the MD4 digest of this "message", and return it in binary form. The returned string will be 16 bytes long.

The result of md4("a", "b", "c") will be exactly the same as the result of md4("abc").

md4_hex($data,...)

Same as md4(), but will return the digest in hexadecimal form. The length of the returned string will be 32 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

md4_base64($data,...)

Same as md4(), but will return the digest as a base64 encoded string. The length of the returned string will be 22 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

Note that the base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded md4 digests you might want to append the redundant string "==" to the result.

METHODS

The object oriented interface to Digest::MD4 is described in this section. After a Digest::MD4 object has been created, you will add data to it and finally ask for the digest in a suitable format. A single object can be used to calculate multiple digests.

The following methods are provided:

$md4 = Digest::MD4->new

The constructor returns a new Digest::MD4 object which encapsulate the state of the MD4 message-digest algorithm.

If called as an instance method (i.e. $md4->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case.

$md4->reset

This is just an alias for $md4->new.

$md4->clone

This a copy of the $md4 object. It is useful when you do not want to destroy the digests state, but need an intermediate value of the digest, e.g. when calculating digests iteratively on a continuous data stream. Example:

    my $md4 = Digest::MD4->new;
    while (<>) {
        $md4->add($_);
        print "Line $.: ", $md4->clone->hexdigest, "\n";
    }
$md4->add($data,...)

The $data provided as argument are appended to the message we calculate the digest for. The return value is the $md4 object itself.

All these lines will have the same effect on the state of the $md4 object:

    $md4->add("a"); $md4->add("b"); $md4->add("c");
    $md4->add("a")->add("b")->add("c");
    $md4->add("a", "b", "c");
    $md4->add("abc");
$md4->addfile($io_handle)

The $io_handle will be read until EOF and its content appended to the message we calculate the digest for. The return value is the $md4 object itself.

The addfile() method will croak() if it fails reading data for some reason. If it croaks it is unpredictable what the state of the $md4 object will be in. The addfile() method might have been able to read the file partially before it failed. It is probably wise to discard or reset the $md4 object if this occurs.

In most cases you want to make sure that the $io_handle is in binmode before you pass it as argument to the addfile() method.

$md4->digest

Return the binary digest for the message. The returned string will be 16 bytes long.

Note that the digest operation is effectively a destructive, read-once operation. Once it has been performed, the Digest::MD4 object is automatically reset and can be used to calculate another digest value. Call $md4->clone->digest if you want to calculate the digest without reseting the digest state.

$md4->hexdigest

Same as $md4->digest, but will return the digest in hexadecimal form. The length of the returned string will be 32 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

$md4->b64digest

Same as $md4->digest, but will return the digest as a base64 encoded string. The length of the returned string will be 22 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

The base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded md4 digests you might want to append the string "==" to the result.

EXAMPLES

The simplest way to use this library is to import the md4_hex() function (or one of its cousins):

    use Digest::MD4 qw(md4_hex);
    print "Digest is ", md4_hex("foobarbaz"), "\n";

The above example would print out the message:

    Digest is 6df23dc03f9b54cc38a0fc1483df6e21

The same checksum can also be calculated in OO style:

    use Digest::MD4;

    $md4 = Digest::MD4->new;
    $md4->add('foo', 'bar');
    $md4->add('baz');
    $digest = $md4->hexdigest;

    print "Digest is $digest\n";

With OO style you can break the message arbitrary. This means that we are no longer limited to have space for the whole message in memory, i.e. we can handle messages of any size.

This is useful when calculating checksum for files:

    use Digest::MD4;

    my $file = shift || "/etc/passwd";
    open(FILE, $file) or die "Can't open '$file': $!";
    binmode(FILE);

    $md4 = Digest::MD4->new;
    while (<FILE>) {
        $md4->add($_);
    }
    close(FILE);
    print $md4->b64digest, " $file\n";

Or we can use the addfile method for more efficient reading of the file:

    use Digest::MD4;

    my $file = shift || "/etc/passwd";
    open(FILE, $file) or die "Can't open '$file': $!";
    binmode(FILE);

    print Digest::MD4->new->addfile(*FILE)->hexdigest, " $file\n";

Perl 5.8 support Unicode characters in strings. Since the MD4 algorithm is only defined for strings of bytes, it can not be used on strings that contains chars with ordinal number above 255. The MD4 functions and methods will croak if you try to feed them such input data:

    use Digest::MD4 qw(md4_hex);

    my $str = "abc\x{300}";
    print md4_hex($str), "\n";  # croaks
    # Wide character in subroutine entry

What you can do is calculate the MD4 checksum of the UTF-8 representation of such strings. This is achieved by filtering the string through encode_utf8() function:

    use Digest::MD4 qw(md4_hex);
    use Encode qw(encode_utf8);

    my $str = "abc\x{300}";
    print md4_hex(encode_utf8($str)), "\n";
    # 8c2d46911f3f5a326455f0ed7a8ed3b3

SEE ALSO

the Digest manpage,
the Digest::MD2 manpage,
the Digest::SHA1 manpage,
the Digest::HMAC manpage

md4sum(1)

RFC 1320

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Copyright 1998-2003 Gisle Aas.
 Copyright 1995-1996 Neil Winton.
 Copyright 1991-1992 RSA Data Security, Inc.

The MD4 algorithm is defined in RFC 1320. This implementation is derived from the reference C code in RFC 1320 which is covered by the following copyright statement:

   Copyright (C) 1990-2, RSA Data Security, Inc. All rights reserved.
   License to copy and use this software is granted provided that it
   is identified as the "RSA Data Security, Inc. MD4 Message-Digest
   Algorithm" in all material mentioning or referencing this software
   or this function.
   License is also granted to make and use derivative works provided
   that such works are identified as "derived from the RSA Data
   Security, Inc. MD4 Message-Digest Algorithm" in all material
   mentioning or referencing the derived work.
   RSA Data Security, Inc. makes no representations concerning either
   the merchantability of this software or the suitability of this
   software for any particular purpose. It is provided "as is"
   without express or implied warranty of any kind.
   These notices must be retained in any copies of any part of this
   documentation and/or software.

This copyright does not prohibit distribution of any version of Perl containing this extension under the terms of the GNU or Artistic licenses.

AUTHORS

The original MD5 interface was written by Neil Winton (N.Winton@axion.bt.co.uk).

The Digest::MD5 module is written by Gisle Aas <gisle@ActiveState.com>.

The Digest::MD4 module is derived from Digest::MD5 by Mike McCauley (mikem@open.com.au)


Digest::MD5 - Perl interface to the MD5 Algorithm

  • FUNCTIONS
  • METHODS
  • EXAMPLES
  • SEE ALSO
  • COPYRIGHT
  • AUTHORS

NAME

Digest::MD5 - Perl interface to the MD5 Algorithm

SYNOPSIS

 # Functional style
 use Digest::MD5 qw(md5 md5_hex md5_base64);

 $digest = md5($data);
 $digest = md5_hex($data);
 $digest = md5_base64($data);

 # OO style
 use Digest::MD5;

 $ctx = Digest::MD5->new;

 $ctx->add($data);
 $ctx->addfile(*FILE);

 $digest = $ctx->digest;
 $digest = $ctx->hexdigest;
 $digest = $ctx->b64digest;

DESCRIPTION

The Digest::MD5 module allows you to use the RSA Data Security Inc. MD5 Message Digest algorithm from within Perl programs. The algorithm takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input.

Note that the MD5 algorithm is not as strong as it used to be. It has since 2005 been easy to generate different messages that produce the same MD5 digest. It still seems hard to generate messages that produce a given digest, but it is probably wise to move to stronger algorithms for applications that depend on the digest to uniquely identify a message.

The Digest::MD5 module provide a procedural interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly.

FUNCTIONS

The following functions are provided by the Digest::MD5 module. None of these functions are exported by default.

md5($data,...)

This function will concatenate all arguments, calculate the MD5 digest of this "message", and return it in binary form. The returned string will be 16 bytes long.

The result of md5("a", "b", "c") will be exactly the same as the result of md5("abc").

md5_hex($data,...)

Same as md5(), but will return the digest in hexadecimal form. The length of the returned string will be 32 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

md5_base64($data,...)

Same as md5(), but will return the digest as a base64 encoded string. The length of the returned string will be 22 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

Note that the base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded md5 digests you might want to append the redundant string "==" to the result.

METHODS

The object oriented interface to Digest::MD5 is described in this section. After a Digest::MD5 object has been created, you will add data to it and finally ask for the digest in a suitable format. A single object can be used to calculate multiple digests.

The following methods are provided:

$md5 = Digest::MD5->new

The constructor returns a new Digest::MD5 object which encapsulate the state of the MD5 message-digest algorithm.

If called as an instance method (i.e. $md5->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case.

$md5->reset

This is just an alias for $md5->new.

$md5->clone

This a copy of the $md5 object. It is useful when you do not want to destroy the digests state, but need an intermediate value of the digest, e.g. when calculating digests iteratively on a continuous data stream. Example:

    my $md5 = Digest::MD5->new;
    while (<>) {
        $md5->add($_);
        print "Line $.: ", $md5->clone->hexdigest, "\n";
    }
$md5->add($data,...)

The $data provided as argument are appended to the message we calculate the digest for. The return value is the $md5 object itself.

All these lines will have the same effect on the state of the $md5 object:

    $md5->add("a"); $md5->add("b"); $md5->add("c");
    $md5->add("a")->add("b")->add("c");
    $md5->add("a", "b", "c");
    $md5->add("abc");
$md5->addfile($io_handle)

The $io_handle will be read until EOF and its content appended to the message we calculate the digest for. The return value is the $md5 object itself.

The addfile() method will croak() if it fails reading data for some reason. If it croaks it is unpredictable what the state of the $md5 object will be in. The addfile() method might have been able to read the file partially before it failed. It is probably wise to discard or reset the $md5 object if this occurs.

In most cases you want to make sure that the $io_handle is in binmode before you pass it as argument to the addfile() method.

$md5->add_bits($data, $nbits)
$md5->add_bits($bitstring)

Since the MD5 algorithm is byte oriented you might only add bits as multiples of 8, so you probably want to just use add() instead. The add_bits() method is provided for compatibility with other digest implementations. See the Digest manpage for description of the arguments that add_bits() take.

$md5->digest

Return the binary digest for the message. The returned string will be 16 bytes long.

Note that the digest operation is effectively a destructive, read-once operation. Once it has been performed, the Digest::MD5 object is automatically reset and can be used to calculate another digest value. Call $md5->clone->digest if you want to calculate the digest without resetting the digest state.

$md5->hexdigest

Same as $md5->digest, but will return the digest in hexadecimal form. The length of the returned string will be 32 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

$md5->b64digest

Same as $md5->digest, but will return the digest as a base64 encoded string. The length of the returned string will be 22 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

The base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded md5 digests you might want to append the string "==" to the result.

EXAMPLES

The simplest way to use this library is to import the md5_hex() function (or one of its cousins):

    use Digest::MD5 qw(md5_hex);
    print "Digest is ", md5_hex("foobarbaz"), "\n";

The above example would print out the message:

    Digest is 6df23dc03f9b54cc38a0fc1483df6e21

The same checksum can also be calculated in OO style:

    use Digest::MD5;

    $md5 = Digest::MD5->new;
    $md5->add('foo', 'bar');
    $md5->add('baz');
    $digest = $md5->hexdigest;

    print "Digest is $digest\n";

With OO style you can break the message arbitrary. This means that we are no longer limited to have space for the whole message in memory, i.e. we can handle messages of any size.

This is useful when calculating checksum for files:

    use Digest::MD5;

    my $file = shift || "/etc/passwd";
    open(FILE, $file) or die "Can't open '$file': $!";
    binmode(FILE);

    $md5 = Digest::MD5->new;
    while (<FILE>) {
        $md5->add($_);
    }
    close(FILE);
    print $md5->b64digest, " $file\n";

Or we can use the addfile method for more efficient reading of the file:

    use Digest::MD5;

    my $file = shift || "/etc/passwd";
    open(FILE, $file) or die "Can't open '$file': $!";
    binmode(FILE);

    print Digest::MD5->new->addfile(*FILE)->hexdigest, " $file\n";

Perl 5.8 support Unicode characters in strings. Since the MD5 algorithm is only defined for strings of bytes, it can not be used on strings that contains chars with ordinal number above 255. The MD5 functions and methods will croak if you try to feed them such input data:

    use Digest::MD5 qw(md5_hex);

    my $str = "abc\x{300}";
    print md5_hex($str), "\n";  # croaks
    # Wide character in subroutine entry

What you can do is calculate the MD5 checksum of the UTF-8 representation of such strings. This is achieved by filtering the string through encode_utf8() function:

    use Digest::MD5 qw(md5_hex);
    use Encode qw(encode_utf8);

    my $str = "abc\x{300}";
    print md5_hex(encode_utf8($str)), "\n";
    # 8c2d46911f3f5a326455f0ed7a8ed3b3

SEE ALSO

the Digest manpage,
the Digest::MD2 manpage,
the Digest::SHA1 manpage,
the Digest::HMAC manpage

md5sum(1)

RFC 1321

http://en.wikipedia.org/wiki/MD5

The paper "How to Break MD5 and Other Hash Functions" by Xiaoyun Wang and Hongbo Yu.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Copyright 1998-2003 Gisle Aas.
 Copyright 1995-1996 Neil Winton.
 Copyright 1991-1992 RSA Data Security, Inc.

The MD5 algorithm is defined in RFC 1321. This implementation is derived from the reference C code in RFC 1321 which is covered by the following copyright statement:

Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved.

License to copy and use this software is granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing this software or this function.

License is also granted to make and use derivative works provided that such works are identified as "derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing the derived work.

RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided "as is" without express or implied warranty of any kind.

These notices must be retained in any copies of any part of this documentation and/or software.

This copyright does not prohibit distribution of any version of Perl containing this extension under the terms of the GNU or Artistic licenses.

AUTHORS

The original MD5 interface was written by Neil Winton (N.Winton@axion.bt.co.uk).

The Digest::MD5 module is written by Gisle Aas <gisle@ActiveState.com>.


Digest::SHA1 - Perl interface to the SHA-1 algorithm

  • FUNCTIONS
  • METHODS
  • SEE ALSO
  • COPYRIGHT
  • AUTHORS

NAME

Digest::SHA1 - Perl interface to the SHA-1 algorithm

SYNOPSIS

 # Functional style
 use Digest::SHA1  qw(sha1 sha1_hex sha1_base64);

 $digest = sha1($data);
 $digest = sha1_hex($data);
 $digest = sha1_base64($data);
 $digest = sha1_transform($data);

 # OO style
 use Digest::SHA1;

 $sha1 = Digest::SHA1->new;

 $sha1->add($data);
 $sha1->addfile(*FILE);

 $sha1_copy = $sha1->clone;

 $digest = $sha1->digest;
 $digest = $sha1->hexdigest;
 $digest = $sha1->b64digest;
 $digest = $sha1->transform;

DESCRIPTION

The Digest::SHA1 module allows you to use the NIST SHA-1 message digest algorithm from within Perl programs. The algorithm takes as input a message of arbitrary length and produces as output a 160-bit "fingerprint" or "message digest" of the input.

The Digest::SHA1 module provide a procedural interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly.

FUNCTIONS

The following functions can be exported from the Digest::SHA1 module. No functions are exported by default.

sha1($data,...)

This function will concatenate all arguments, calculate the SHA-1 digest of this "message", and return it in binary form. The returned string will be 20 bytes long.

The result of sha1("a", "b", "c") will be exactly the same as the result of sha1("abc").

sha1_hex($data,...)

Same as sha1(), but will return the digest in hexadecimal form. The length of the returned string will be 40 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

sha1_base64($data,...)

Same as sha1(), but will return the digest as a base64 encoded string. The length of the returned string will be 27 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

Note that the base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded sha1 digests you might want to append the redundant string "=" to the result.

sha1_transform($data)

Implements the basic SHA1 transform on a 64 byte block. The $data argument and the returned $digest are in binary form. This algorithm is used in NIST FIPS 186-2

METHODS

The object oriented interface to Digest::SHA1 is described in this section. After a Digest::SHA1 object has been created, you will add data to it and finally ask for the digest in a suitable format. A single object can be used to calculate multiple digests.

The following methods are provided:

$sha1 = Digest::SHA1->new

The constructor returns a new Digest::SHA1 object which encapsulate the state of the SHA-1 message-digest algorithm.

If called as an instance method (i.e. $sha1->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case.

$sha1->reset

This is just an alias for $sha1->new.

$sha1->clone

This a copy of the $sha1 object. It is useful when you do not want to destroy the digests state, but need an intermediate value of the digest, e.g. when calculating digests iteratively on a continuous data stream. Example:

    my $sha1 = Digest::SHA1->new;
    while (<>) {
        $sha1->add($_);
        print "Line $.: ", $sha1->clone->hexdigest, "\n";
    }
$sha1->add($data,...)

The $data provided as argument are appended to the message we calculate the digest for. The return value is the $sha1 object itself.

All these lines will have the same effect on the state of the $sha1 object:

    $sha1->add("a"); $sha1->add("b"); $sha1->add("c");
    $sha1->add("a")->add("b")->add("c");
    $sha1->add("a", "b", "c");
    $sha1->add("abc");
$sha1->addfile($io_handle)

The $io_handle will be read until EOF and its content appended to the message we calculate the digest for. The return value is the $sha1 object itself.

The addfile() method will croak() if it fails reading data for some reason. If it croaks it is unpredictable what the state of the $sha1 object will be in. The addfile() method might have been able to read the file partially before it failed. It is probably wise to discard or reset the $sha1 object if this occurs.

In most cases you want to make sure that the $io_handle is in binmode before you pass it as argument to the addfile() method.

$sha1->add_bits($data, $nbits)
$sha1->add_bits($bitstring)

This implementation of SHA-1 only supports byte oriented input so you might only add bits as multiples of 8. If you need bit level support please consider using the Digest::SHA module instead. The add_bits() method is provided here for compatibility with other digest implementations. See the Digest manpage for description of the arguments that add_bits() take.

$sha1->digest

Return the binary digest for the message. The returned string will be 20 bytes long.

Note that the digest operation is effectively a destructive, read-once operation. Once it has been performed, the Digest::SHA1 object is automatically reset and can be used to calculate another digest value. Call $sha1->clone->digest if you want to calculate the digest without reseting the digest state.

$sha1->hexdigest

Same as $sha1->digest, but will return the digest in hexadecimal form. The length of the returned string will be 40 and it will only contain characters from this set: '0'..'9' and 'a'..'f'.

$sha1->b64digest

Same as $sha1->digest, but will return the digest as a base64 encoded string. The length of the returned string will be 27 and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.

The base64 encoded string returned is not padded to be a multiple of 4 bytes long. If you want interoperability with other base64 encoded SHA-1 digests you might want to append the string "=" to the result.

SEE ALSO

the Digest manpage, the Digest::HMAC_SHA1 manpage, the Digest::SHA manpage, the Digest::MD5 manpage

http://www.itl.nist.gov/fipspubs/fip180-1.htm

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Copyright 1999-2004 Gisle Aas.
 Copyright 1997 Uwe Hollerbach.

AUTHORS

Peter C. Gutmann, Uwe Hollerbach <uh@alumni.caltech.edu>, Gisle Aas <gisle@aas.no>


Digest::base - Digest base class

  • SEE ALSO

NAME

Digest::base - Digest base class

SYNOPSIS

  package Digest::Foo;
  use base 'Digest::base';

DESCRIPTION

The Digest::base class provide implementations of the methods addfile and add_bits in terms of add, and of the methods hexdigest and b64digest in terms of digest.

Digest implementations might want to inherit from this class to get this implementations of the alternative add and digest methods. A minimal subclass needs to implement the following methods by itself:

    new
    clone
    add
    digest

The arguments and expected behaviour of these methods are described in the Digest manpage.

SEE ALSO

the Digest manpage


Digest::file - Calculate digests of files

  • SEE ALSO

NAME

Digest::file - Calculate digests of files

SYNOPSIS

  # Poor mans "md5sum" command
  use Digest::file qw(digest_file_hex);
  for (@ARGV) {
      print digest_file_hex($_, "MD5"), "  $_\n";
  }

DESCRIPTION

This module provide 3 convenience functions to calculate the digest of files. The following functions are provided:

digest_file( $file, $algorithm, [$arg,...] )

This function will calculate and return the binary digest of the bytes of the given file. The function will croak if it fails to open or read the file.

The $algorithm is a string like "MD2", "MD5", "SHA-1", "SHA-512". Additional arguments are passed to the constructor for the implementation of the given algorithm.

digest_file_hex( $file, $algorithm, [$arg,...] )

Same as digest_file(), but return the digest in hex form.

digest_file_base64( $file, $algorithm, [$arg,...] )

Same as digest_file(), but return the digest as a base64 encoded string.

SEE ALSO

the Digest manpage


DirHandle - supply object methods for directory handles

  • NOTES

NAME

DirHandle - supply object methods for directory handles

SYNOPSIS

    use DirHandle;
    $d = new DirHandle ".";
    if (defined $d) {
        while (defined($_ = $d->read)) { something($_); }
        $d->rewind;
        while (defined($_ = $d->read)) { something_else($_); }
        undef $d;
    }

DESCRIPTION

The DirHandle method provide an alternative interface to the opendir(), closedir(), readdir(), and rewinddir() functions.

The only objective benefit to using DirHandle is that it avoids namespace pollution by creating globs to hold directory handles.

NOTES

  • On Mac OS (Classic), the path separator is ':', not '/', and the current directory is denoted as ':', not '.'. You should be careful about specifying relative pathnames. While a full path always begins with a volume name, a relative pathname should always begin with a ':'. If specifying a volume name only, a trailing ':' is required.


Dumpvalue - provides screen dump of Perl data.

    • Creation
    • Methods

NAME

Dumpvalue - provides screen dump of Perl data.

SYNOPSIS

  use Dumpvalue;
  my $dumper = new Dumpvalue;
  $dumper->set(globPrint => 1);
  $dumper->dumpValue(\*::);
  $dumper->dumpvars('main');
  my $dump = $dumper->stringify($some_value);

DESCRIPTION

Creation

A new dumper is created by a call

  $d = new Dumpvalue(option1 => value1, option2 => value2)

Recognized options:

arrayDepth, hashDepth

Print only first N elements of arrays and hashes. If false, prints all the elements.

compactDump, veryCompact

Change style of array and hash dump. If true, short array may be printed on one line.

globPrint

Whether to print contents of globs.

dumpDBFiles

Dump arrays holding contents of debugged files.

dumpPackages

Dump symbol tables of packages.

dumpReused

Dump contents of "reused" addresses.

tick, quoteHighBit, printUndef

Change style of string dump. Default value of tick is auto, one can enable either double-quotish dump, or single-quotish by setting it to " or '. By default, characters with high bit set are printed as is. If quoteHighBit is set, they will be quoted.

usageOnly

rudimentally per-package memory usage dump. If set, dumpvars calculates total size of strings in variables in the package.

unctrl

Changes the style of printout of strings. Possible values are unctrl and quote.

subdump

Whether to try to find the subroutine name given the reference.

bareStringify

Whether to write the non-overloaded form of the stringify-overloaded objects.

quoteHighBit

Whether to print chars with high bit set in binary or "as is".

stopDbSignal

Whether to abort printing if debugger signal flag is raised.

Later in the life of the object the methods may be queries with get() method and set() method (which accept multiple arguments).

Methods

dumpValue
  $dumper->dumpValue($value);
  $dumper->dumpValue([$value1, $value2]);

Prints a dump to the currently selected filehandle.

dumpValues
  $dumper->dumpValues($value1, $value2);

Same as $dumper-dumpValue([$value1, $value2]); >.

stringify
  my $dump = $dumper->stringify($value [,$noticks] );

Returns the dump of a single scalar without printing. If the second argument is true, the return value does not contain enclosing ticks. Does not handle data structures.

dumpvars
  $dumper->dumpvars('my_package');
  $dumper->dumpvars('my_package', 'foo', '~bar$', '!......');

The optional arguments are considered as literal strings unless they start with ~ or !, in which case they are interpreted as regular expressions (possibly negated).

The second example prints entries with names foo, and also entries with names which ends on bar, or are shorter than 5 chars.

set_quote
  $d->set_quote('"');

Sets tick and unctrl options to suitable values for printout with the given quote char. Possible values are auto, ' and ".

set_unctrl
  $d->set_unctrl('unctrl');

Sets unctrl option with checking for an invalid argument. Possible values are unctrl and quote.

compactDump
  $d->compactDump(1);

Sets compactDump option. If the value is 1, sets to a reasonable big number.

veryCompact
  $d->veryCompact(1);

Sets compactDump and veryCompact options simultaneously.

set
  $d->set(option1 => value1, option2 => value2);
get
  @values = $d->get('option1', 'option2');


DynaLoader - Dynamically load C libraries into Perl code

  • AUTHOR

NAME

DynaLoader - Dynamically load C libraries into Perl code

SYNOPSIS

    package YourPackage;
    require DynaLoader;
    @ISA = qw(... DynaLoader ...);
    bootstrap YourPackage;

    # optional method for 'global' loading
    sub dl_load_flags { 0x01 }

DESCRIPTION

This document defines a standard generic interface to the dynamic linking mechanisms available on many platforms. Its primary purpose is to implement automatic dynamic loading of Perl modules.

This document serves as both a specification for anyone wishing to implement the DynaLoader for a new platform and as a guide for anyone wishing to use the DynaLoader directly in an application.

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 and other platforms.

It is also hoped that the interface will cover the needs of OS/2, NT etc and also allow pseudo-dynamic linking (using ld -A at runtime).

It must be stressed that the DynaLoader, by itself, 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 arguments. A C::DynaLib module is available from CPAN sites which performs that function for some common system types. And since the year 2000, there's also Inline::C, a module that allows you to write Perl subroutines in C. Also available from your local CPAN site.

DynaLoader Interface Summary

  @dl_library_path
  @dl_resolve_using
  @dl_require_symbols
  $dl_debug
  @dl_librefs
  @dl_modules
  @dl_shared_objects
                                                  Implemented in:
  bootstrap($modulename)                               Perl
  @filepaths = dl_findfile(@names)                     Perl
  $flags = $modulename->dl_load_flags                  Perl
  $symref  = dl_find_symbol_anywhere($symbol)          Perl
  $libref  = dl_load_file($filename, $flags)           C
  $status  = dl_unload_file($libref)                   C
  $symref  = dl_find_symbol($libref, $symbol)          C
  @symbols = dl_undef_symbols()                        C
  dl_install_xsub($name, $symref [, $filename])        C
  $message = dl_error                                  C
@dl_library_path

The standard/default list of directories in which dl_findfile() will search for libraries etc. Directories are searched in order: $dl_library_path[0], [1], ... etc

@dl_library_path is initialised to hold the list of 'normal' directories (/usr/lib, etc) determined by Configure ($Config{'libpth'}). This should ensure portability across a wide range of platforms.

@dl_library_path should also be initialised with any other directories that can be determined from the environment at runtime (such as LD_LIBRARY_PATH for SunOS).

After initialisation @dl_library_path can be manipulated by an application using push and unshift before calling dl_findfile(). Unshift can be used to add directories to the front of the search order either to save search time or to override libraries with the same name in the 'normal' directories.

The load function that dl_load_file() calls may require an absolute pathname. The dl_findfile() function and @dl_library_path can be used to search for and return the absolute pathname for the library/object that you wish to load.

@dl_resolve_using

A list of additional libraries or other shared objects which can be used to resolve any undefined symbols that might be generated by a later call to load_file().

This is only required on some platforms which do not handle dependent libraries automatically. For example the Socket Perl extension library (auto/Socket/Socket.so) contains references to many socket functions which need to be resolved when it's loaded. Most platforms will automatically know where to find the 'dependent' library (e.g., /usr/lib/libsocket.so). A few platforms need to be told the location of the dependent library explicitly. Use @dl_resolve_using for this.

Example usage:

    @dl_resolve_using = dl_findfile('-lsocket');
@dl_require_symbols

A list of one or more symbol names that are in the library/object file to be dynamically loaded. This is only required on some platforms.

@dl_librefs

An array of the handles returned by successful calls to dl_load_file(), made by bootstrap, in the order in which they were loaded. Can be used with dl_find_symbol() to look for a symbol in any of the loaded files.

@dl_modules

An array of module (package) names that have been bootstrap'ed.

@dl_shared_objects

An array of file names for the shared objects that were loaded.

dl_error()

Syntax:

    $message = dl_error();

Error message text from the last failed DynaLoader function. 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 (e.g., dlerror()).

$dl_debug

Internal debugging messages are enabled when $dl_debug is set true. Currently setting $dl_debug only affects the Perl side of the DynaLoader. These messages should help an application developer to resolve any DynaLoader usage problems.

$dl_debug is set to $ENV{'PERL_DL_DEBUG'} if defined.

For the DynaLoader developer/porter there is a similar debugging variable added to the C code (see dlutils.c) and enabled if Perl was built with the -DDEBUGGING flag. This can also be set via the PERL_DL_DEBUG environment variable. Set to 1 for minimal information or higher for more.

dl_findfile()

Syntax:

    @filepaths = dl_findfile(@names)

Determine the full paths (including file suffix) of one or more loadable files given their generic names and optionally one or more directories. Searches directories in @dl_library_path by default and returns an empty list if no files were found.

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 and/or suffix then the corresponding file will be searched for by trying combinations of prefix and suffix 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));
dl_expandspec()

Syntax:

    $filepath = dl_expandspec($spec)

Some unusual systems, such as VMS, require special filename handling in order to deal with symbolic names for files (i.e., VMS's Logical Names).

To support these systems a dl_expandspec() function can be implemented either in the dl_*.xs file or code can be added to the autoloadable dl_expandspec() function in DynaLoader.pm. See DynaLoader.pm for more information.

dl_load_file()

Syntax:

    $libref = dl_load_file($filename, $flags)

Dynamically load $filename, which must be the path to a shared object or library. An opaque 'library reference' is returned as a handle for the loaded object. Returns undef on error.

The $flags argument to alters dl_load_file behaviour. Assigned bits:

 0x01  make symbols available for linking later dl_load_file's.
       (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
       (ignored under VMS; this is a normal part of image linking)

(On systems that provide a handle for the loaded object such as SunOS and HPUX, $libref will be that handle. 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.)

This is the function that does the real work. It 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])

(The dlopen() function is also used by Solaris and some versions of Linux, and is a common choice when providing a "wrapper" on other mechanisms as is done in the OS/2 port.)

dl_unload_file()

Syntax:

    $status = dl_unload_file($libref)

Dynamically unload $libref, which must be an opaque 'library reference' as returned from dl_load_file. Returns one on success and zero on failure.

This function is optional and may not necessarily be provided on all platforms. If it is defined, it is called automatically when the interpreter exits for every shared object or library loaded by DynaLoader::bootstrap. All such library references are stored in @dl_librefs by DynaLoader::Bootstrap as it loads the libraries. The files are unloaded in last-in, first-out order.

This unloading is usually necessary when embedding a shared-object perl (e.g. one configured with -Duseshrplib) within a larger application, and the perl interpreter is created and destroyed several times within the lifetime of the application. In this case it is possible that the system dynamic linker will unload and then subsequently reload the shared libperl without relocating any references to it from any files DynaLoaded by the previous incarnation of the interpreter. As a result, any shared objects opened by DynaLoader may point to a now invalid 'ghost' of the libperl shared object, causing apparently random memory corruption and crashes. This behaviour is most commonly seen when using Apache and mod_perl built with the APXS mechanism.

    SunOS: dlclose($libref)
    HP-UX: ???
    Linux: ???
    NeXT:  ???
    VMS:   ???

(The dlclose() function is also used by Solaris and some versions of Linux, and is a common choice when providing a "wrapper" on other mechanisms as is done in the OS/2 port.)

dl_load_flags()

Syntax:

    $flags = dl_load_flags $modulename;

Designed to be a method call, and to be overridden by a derived class (i.e. a class which has DynaLoader in its @ISA). The definition in DynaLoader itself returns 0, which produces standard behavior from dl_load_file().

dl_find_symbol()

Syntax:

    $symref = dl_find_symbol($libref, $symbol)

Return the address of the symbol $symbol or undef if not found. 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 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().

    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)
dl_find_symbol_anywhere()

Syntax:

    $symref = dl_find_symbol_anywhere($symbol)

Applies dl_find_symbol() to the members of @dl_librefs and returns the first match found.

dl_undef_symbols()

Example

    @symbols = dl_undef_symbols()

Return a list of symbol names which remain undefined after load_file(). Returns () if not known. Don't worry if your platform does not provide a mechanism for this. Most do not need it and hence do not provide it, they just return an empty list.

dl_install_xsub()

Syntax:

    dl_install_xsub($perl_name, $symref [, $filename])

Create a new Perl external subroutine named $perl_name using $symref as a pointer to the function which implements the routine. This is simply a direct call to newXSUB(). 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()

Syntax:

bootstrap($module)

This is the normal entry point for automatic dynamic loading in Perl.

It performs the following actions:

  • locates an auto/$module directory by searching @INC

  • uses dl_findfile() to determine the filename to load

  • sets @dl_require_symbols to ("boot_$module")

  • executes an auto/$module/$module.bs file if it exists (typically used to add to @dl_resolve_using any files which are required to load the module on the current platform)

  • calls dl_load_flags() to determine how to load the file.

  • calls dl_load_file() to load the file

  • calls dl_undef_symbols() and warns if any symbols are undefined

  • calls dl_find_symbol() for "boot_$module"

  • calls dl_install_xsub() to install it as "${module}::bootstrap"

  • calls &{"${module}::bootstrap"} to bootstrap the module (actually it uses the function reference returned by dl_install_xsub for speed)

AUTHOR

Tim Bunce, 11 August 1994.

This interface is based on the work and comments of (in no particular order): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, myself and others.

Larry Wall designed the elegant inherited bootstrap mechanism and implemented the first Perl 5 dynamic loader using it.

Solaris global loading added by Nick Ing-Simmons with design/coding assistance from Tim Bunce, January 1996.


Encode - character encodings

    • Table of Contents
  • DESCRIPTION
    • TERMINOLOGY
  • PERL ENCODING API
    • Listing available encodings
    • Defining Aliases
  • Encoding via PerlIO
  • Handling Malformed Data
    • coderef for CHECK
  • Defining Encodings
  • The UTF-8 flag
    • Messing with Perl's Internals
  • UTF-8 vs. utf8
  • SEE ALSO
  • MAINTAINER

NAME

Encode - character encodings

SYNOPSIS

    use Encode;

Table of Contents

Encode consists of a collection of modules whose details are too big to fit in one document. This POD itself explains the top-level APIs and general topics at a glance. For other topics and more details, see the PODs below:

  Name                          Description
  --------------------------------------------------------
  Encode::Alias         Alias definitions to encodings
  Encode::Encoding      Encode Implementation Base Class
  Encode::Supported     List of Supported Encodings
  Encode::CN            Simplified Chinese Encodings
  Encode::JP            Japanese Encodings
  Encode::KR            Korean Encodings
  Encode::TW            Traditional Chinese Encodings
  --------------------------------------------------------

DESCRIPTION

The Encode module provides the interfaces between Perl's strings and the rest of the system. Perl strings are sequences of characters.

The repertoire of characters that Perl can represent is at least that defined by the Unicode Consortium. On most platforms the ordinal values of the characters (as returned by ord(ch)) is the "Unicode codepoint" for the character (the exceptions are those platforms where the legacy encoding is some variant of EBCDIC rather than a super-set of ASCII - see the perlebcdic manpage).

Traditionally, computer data has been moved around in 8-bit chunks often called "bytes". These chunks are also known as "octets" in networking standards. Perl is widely used to manipulate data of many types - not only strings of characters representing human or computer languages but also "binary" data being the machine's representation of numbers, pixels in an image - or just about anything.

When Perl is processing "binary data", the programmer wants Perl to process "sequences of bytes". This is not a problem for Perl - as a byte has 256 possible values, it easily fits in Perl's much larger "logical character".

TERMINOLOGY

  • character: a character in the range 0..(2**32-1) (or more). (What Perl's strings are made of.)

  • byte: a character in the range 0..255 (A special case of a Perl character.)

  • octet: 8 bits of data, with ordinal values 0..255 (Term for bytes passed to or from a non-Perl context, e.g. a disk file.)

PERL ENCODING API

$octets = encode(ENCODING, $string [, CHECK])

Encodes a string from Perl's internal form into ENCODING and returns a sequence of octets. ENCODING can be either a canonical name or an alias. For encoding names and aliases, see Defining Aliases. For CHECK, see Handling Malformed Data.

For example, to convert a string from Perl's internal format to iso-8859-1 (also known as Latin1),

  $octets = encode("iso-8859-1", $string);

CAVEAT: When you run $octets = encode("utf8", $string), then $octets may not be equal to $string. Though they both contain the same data, the utf8 flag for $octets is always off. When you encode anything, utf8 flag of the result is always off, even when it contains completely valid utf8 string. See The UTF-8 flag below.

If the $string is undef then undef is returned.

$string = decode(ENCODING, $octets [, CHECK])

Decodes a sequence of octets assumed to be in ENCODING into Perl's internal form and returns the resulting string. As in encode(), ENCODING can be either a canonical name or an alias. For encoding names and aliases, see Defining Aliases. For CHECK, see Handling Malformed Data.

For example, to convert ISO-8859-1 data to a string in Perl's internal format:

  $string = decode("iso-8859-1", $octets);

CAVEAT: When you run $string = decode("utf8", $octets), then $string may not be equal to $octets. Though they both contain the same data, the utf8 flag for $string is on unless $octets entirely consists of ASCII data (or EBCDIC on EBCDIC machines). See The UTF-8 flag below.

If the $string is undef then undef is returned.

[$length =] from_to($octets, FROM_ENC, TO_ENC [, CHECK])

Converts in-place data between two encodings. The data in $octets must be encoded as octets and not as characters in Perl's internal format. For example, to convert ISO-8859-1 data to Microsoft's CP1250 encoding:

  from_to($octets, "iso-8859-1", "cp1250");

and to convert it back:

  from_to($octets, "cp1250", "iso-8859-1");

Note that because the conversion happens in place, the data to be converted cannot be a string constant; it must be a scalar variable.

from_to() returns the length of the converted string in octets on success, undef on error.

CAVEAT: The following operations look the same but are not quite so;

  from_to($data, "iso-8859-1", "utf8"); #1
  $data = decode("iso-8859-1", $data);  #2

Both #1 and #2 make $data consist of a completely valid UTF-8 string but only #2 turns utf8 flag on. #1 is equivalent to

  $data = encode("utf8", decode("iso-8859-1", $data));

See The UTF-8 flag below.

$octets = encode_utf8($string);

Equivalent to $octets = encode("utf8", $string); The characters that comprise $string are encoded in Perl's internal format and the result is returned as a sequence of octets. All possible characters have a UTF-8 representation so this function cannot fail.

$string = decode_utf8($octets [, CHECK]);

equivalent to $string = decode("utf8", $octets [, CHECK]). The sequence of octets represented by $octets is decoded from UTF-8 into a sequence of logical characters. Not all sequences of octets form valid UTF-8 encodings, so it is possible for this call to fail. For CHECK, see Handling Malformed Data.

Listing available encodings

  use Encode;
  @list = Encode->encodings();

Returns a list of the canonical names of the available encodings that are loaded. To get a list of all available encodings including the ones that are not loaded yet, say

  @all_encodings = Encode->encodings(":all");

Or you can give the name of a specific module.

  @with_jp = Encode->encodings("Encode::JP");

When "::" is not in the name, "Encode::" is assumed.

  @ebcdic = Encode->encodings("EBCDIC");

To find out in detail which encodings are supported by this package, see the Encode::Supported manpage.

Defining Aliases

To add a new alias to a given encoding, use:

  use Encode;
  use Encode::Alias;
  define_alias(newName => ENCODING);

After that, newName can be used as an alias for ENCODING. ENCODING may be either the name of an encoding or an encoding object

But before you do so, make sure the alias is nonexistent with resolve_alias(), which returns the canonical name thereof. i.e.

  Encode::resolve_alias("latin1") eq "iso-8859-1" # true
  Encode::resolve_alias("iso-8859-12")   # false; nonexistent
  Encode::resolve_alias($name) eq $name  # true if $name is canonical

resolve_alias() does not need use Encode::Alias; it can be exported via use Encode qw(resolve_alias).

See the Encode::Alias manpage for details.

Encoding via PerlIO

If your perl supports PerlIO (which is the default), you can use a PerlIO layer to decode and encode directly via a filehandle. The following two examples are totally identical in their functionality.

  # via PerlIO
  open my $in,  "<:encoding(shiftjis)", $infile  or die;
  open my $out, ">:encoding(euc-jp)",   $outfile or die;
  while(<$in>){ print $out $_; }

  # via from_to
  open my $in,  "<", $infile  or die;
  open my $out, ">", $outfile or die;
  while(<$in>){
    from_to($_, "shiftjis", "euc-jp", 1);
    print $out $_;
  }

Unfortunately, it may be that encodings are PerlIO-savvy. You can check if your encoding is supported by PerlIO by calling the perlio_ok method.

  Encode::perlio_ok("hz");             # False
  find_encoding("euc-cn")->perlio_ok;  # True where PerlIO is available

  use Encode qw(perlio_ok);            # exported upon request
  perlio_ok("euc-jp")

Fortunately, all encodings that come with Encode core are PerlIO-savvy except for hz and ISO-2022-kr. For gory details, see the Encode::Encoding manpage and the Encode::PerlIO manpage.

Handling Malformed Data

The optional CHECK argument tells Encode what to do when it encounters malformed data. Without CHECK, Encode::FB_DEFAULT ( == 0 ) is assumed.

As of version 2.12 Encode supports coderef values for CHECK. See below.

NOTE: Not all encoding support this feature

Some encodings ignore CHECK argument. For example, the Encode::Unicode manpage ignores CHECK and it always croaks on error.

Now here is the list of CHECK values available

CHECK = Encode::FB_DEFAULT ( == 0)

If CHECK is 0, (en|de)code will put a substitution character in place of a malformed character. When you encode, <subchar> will be used. When you decode the code point 0xFFFD is used. If the data is supposed to be UTF-8, an optional lexical warning (category utf8) is given.

CHECK = Encode::FB_CROAK ( == 1)

If CHECK is 1, methods will die on error immediately with an error message. Therefore, when CHECK is set to 1, you should trap the error with eval{} unless you really want to let it die.

CHECK = Encode::FB_QUIET

If CHECK is set to Encode::FB_QUIET, (en|de)code will immediately return the portion of the data that has been processed so far when an error occurs. The data argument will be overwritten with everything after that point (that is, the unprocessed part of data). This is handy when you have to call decode repeatedly in the case where your source data may contain partial multi-byte character sequences, (i.e. you are reading with a fixed-width buffer). Here is a sample code that does exactly this:

  my $buffer = ''; my $string = '';
  while(read $fh, $buffer, 256, length($buffer)){
    $string .= decode($encoding, $buffer, Encode::FB_QUIET);
    # $buffer now contains the unprocessed partial character
  }
CHECK = Encode::FB_WARN

This is the same as above, except that it warns on error. Handy when you are debugging the mode above.

perlqq mode (CHECK = Encode::FB_PERLQQ)
HTML charref mode (CHECK = Encode::FB_HTMLCREF)
XML charref mode (CHECK = Encode::FB_XMLCREF)

For encodings that are implemented by Encode::XS, CHECK == Encode::FB_PERLQQ turns (en|de)code into perlqq fallback mode.

When you decode, \xHH will be inserted for a malformed character, where HH is the hex representation of the octet that could not be decoded to utf8. And when you encode, \x{HHHH} will be inserted, where HHHH is the Unicode ID of the character that cannot be found in the character repertoire of the encoding.

HTML/XML character reference modes are about the same, in place of \x{HHHH}, HTML uses &#NNN; where NNN is a decimal number and XML uses &#xHHHH; where HHHH is the hexadecimal number.

In Encode 2.10 or later, LEAVE_SRC is also implied.

The bitmask

These modes are actually set via a bitmask. Here is how the FB_XX constants are laid out. You can import the FB_XX constants via use Encode qw(:fallbacks); you can import the generic bitmask constants via use Encode qw(:fallback_all).

                     FB_DEFAULT FB_CROAK FB_QUIET FB_WARN  FB_PERLQQ
 DIE_ON_ERR    0x0001             X
 WARN_ON_ERR   0x0002                               X
 RETURN_ON_ERR 0x0004                      X        X
 LEAVE_SRC     0x0008                                        X
 PERLQQ        0x0100                                        X
 HTMLCREF      0x0200
 XMLCREF       0x0400

coderef for CHECK

As of Encode 2.12 CHECK can also be a code reference which takes the ord value of unmapped caharacter as an argument and returns a string that represents the fallback character. For instance,

  $ascii = encode("ascii", $utf8, sub{ sprintf "<U+%04X>", shift });

Acts like FB_PERLQQ but <U+XXXX> is used instead of \x{XXXX}.

Defining Encodings

To define a new encoding, use:

    use Encode qw(define_encoding);
    define_encoding($object, 'canonicalName' [, alias...]);

canonicalName will be associated with $object. The object should provide the interface described in the Encode::Encoding manpage. If more than two arguments are provided then additional arguments are taken as aliases for $object.

See the Encode::Encoding manpage for more details.

The UTF-8 flag

Before the introduction of utf8 support in perl, The eq operator just compared the strings represented by two scalars. Beginning with perl 5.8, eq compares two strings with simultaneous consideration of the utf8 flag. To explain why we made it so, I will quote page 402 of Programming Perl, 3rd ed.

Goal #1:

Old byte-oriented programs should not spontaneously break on the old byte-oriented data they used to work on.

Goal #2:

Old byte-oriented programs should magically start working on the new character-oriented data when appropriate.

Goal #3:

Programs should run just as fast in the new character-oriented mode as in the old byte-oriented mode.

Goal #4:

Perl should remain one language, rather than forking into a byte-oriented Perl and a character-oriented Perl.

Back when Programming Perl, 3rd ed. was written, not even Perl 5.6.0 was born and many features documented in the book remained unimplemented for a long time. Perl 5.8 corrected this and the introduction of the UTF-8 flag is one of them. You can think of this perl notion as of a byte-oriented mode (utf8 flag off) and a character-oriented mode (utf8 flag on).

Here is how Encode takes care of the utf8 flag.

  • When you encode, the resulting utf8 flag is always off.

  • When you decode, the resulting utf8 flag is on unless you can unambiguously represent data. Here is the definition of dis-ambiguity.

    After $utf8 = decode('foo', $octet);,

      When $octet is...   The utf8 flag in $utf8 is
  ---------------------------------------------
  In ASCII only (or EBCDIC only)            OFF
  In ISO-8859-1                              ON
  In any other Encoding                      ON
  ---------------------------------------------

    As you see, there is one exception, In ASCII. That way you can assume Goal #1. And with Encode Goal #2 is assumed but you still have to be careful in such cases mentioned in CAVEAT paragraphs.

    This utf8 flag is not visible in perl scripts, exactly for the same reason you cannot (or you don't have to) see if a scalar contains a string, integer, or floating point number. But you can still peek and poke these if you will. See the section below.

Messing with Perl's Internals

The following API uses parts of Perl's internals in the current implementation. As such, they are efficient but may change.

is_utf8(STRING [, CHECK])

[INTERNAL] Tests whether the UTF-8 flag is turned on in the STRING. If CHECK is true, also checks the data in STRING for being well-formed UTF-8. Returns true if successful, false otherwise.

As of perl 5.8.1, the utf8 manpage also has utf8::is_utf8().

_utf8_on(STRING)

[INTERNAL] Turns on the UTF-8 flag in STRING. The data in STRING is not checked for being well-formed UTF-8. Do not use unless you know that the STRING is well-formed UTF-8. Returns the previous state of the UTF-8 flag (so please don't treat the return value as indicating success or failure), or undef if STRING is not a string.

_utf8_off(STRING)

[INTERNAL] Turns off the UTF-8 flag in STRING. Do not use frivolously. Returns the previous state of the UTF-8 flag (so please don't treat the return value as indicating success or failure), or undef if STRING is not a string.

UTF-8 vs. utf8

  ....We now view strings not as sequences of bytes, but as sequences
  of numbers in the range 0 .. 2**32-1 (or in the case of 64-bit
  computers, 0 .. 2**64-1) -- Programming Perl, 3rd ed.

That has been the perl's notion of UTF-8 but official UTF-8 is more strict; Its ranges is much narrower (0 .. 10FFFF), some sequences are not allowed (i.e. Those used in the surrogate pair, 0xFFFE, et al).

Now that is overruled by Larry Wall himself.

  From: Larry Wall <larry@wall.org>
  Date: December 04, 2004 11:51:58 JST
  To: perl-unicode@perl.org
  Subject: Re: Make Encode.pm support the real UTF-8
  Message-Id: <20041204025158.GA28754@wall.org>

  On Fri, Dec 03, 2004 at 10:12:12PM +0000, Tim Bunce wrote:
  : I've no problem with 'utf8' being perl's unrestricted uft8 encoding,
  : but "UTF-8" is the name of the standard and should give the
  : corresponding behaviour.

  For what it's worth, that's how I've always kept them straight in my
  head.

  Also for what it's worth, Perl 6 will mostly default to strict but
  make it easy to switch back to lax.

  Larry

Do you copy? As of Perl 5.8.7, UTF-8 means strict, official UTF-8 while utf8 means liberal, lax, version thereof. And Encode version 2.10 or later thus groks the difference between UTF-8 and C"utf8".

  encode("utf8",  "\x{FFFF_FFFF}", 1); # okay
  encode("UTF-8", "\x{FFFF_FFFF}", 1); # croaks

UTF-8 in Encode is actually a canonical name for utf-8-strict. Yes, the hyphen between "UTF" and "8" is important. Without it Encode goes "liberal"

  find_encoding("UTF-8")->name # is 'utf-8-strict'
  find_encoding("utf-8")->name # ditto. names are case insensitive
  find_encoding("utf8")->name  # ditto. "_" are treated as "-"
  find_encoding("UTF8")->name  # is 'utf8'.

SEE ALSO

the Encode::Encoding manpage, the Encode::Supported manpage, the Encode::PerlIO manpage, the encoding manpage, the perlebcdic manpage, open in the perlfunc manpage, the perlunicode manpage, the utf8 manpage, the Perl Unicode Mailing List <perl-unicode@perl.org>

MAINTAINER

This project was originated by Nick Ing-Simmons and later maintained by Dan Kogai <dankogai@dan.co.jp>. See AUTHORS for a full list of people involved. For any questions, use <perl-unicode@perl.org> so we can all share.


Encode::Alias - alias definitions to encodings

      • Changes in code reference aliasing
    • Alias overloading
  • SEE ALSO

NAME

Encode::Alias - alias definitions to encodings

SYNOPSIS

  use Encode;
  use Encode::Alias;
  define_alias( newName => ENCODING);

DESCRIPTION

Allows newName to be used as an alias for ENCODING. ENCODING may be either the name of an encoding or an encoding object (as described in the Encode manpage).

Currently newName can be specified in the following ways:

As a simple string.
As a qr// compiled regular expression, e.g.:
  define_alias( qr/^iso8859-(\d+)$/i => '"iso-8859-$1"' );

In this case, if ENCODING is not a reference, it is eval-ed in order to allow $1 etc. to be substituted. The example is one way to alias names as used in X11 fonts to the MIME names for the iso-8859-* family. Note the double quotes inside the single quotes.

(or, you don't have to do this yourself because this example is predefined)

If you are using a regex here, you have to use the quotes as shown or it won't work. Also note that regex handling is tricky even for the experienced. Use this feature with caution.

As a code reference, e.g.:
  define_alias( sub {shift =~ /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } );

The same effect as the example above in a different way. The coderef takes the alias name as an argument and returns a canonical name on success or undef if not. Note the second argument is not required. Use this with even more caution than the regex version.

Changes in code reference aliasing

As of Encode 1.87, the older form

  define_alias( sub { return  /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } );

no longer works.

Encode up to 1.86 internally used "local $_" to implement ths older form. But consider the code below;

  use Encode;
  $_ = "eeeee" ;
  while (/(e)/g) {
    my $utf = decode('aliased-encoding-name', $1);
    print "position:",pos,"\n";
  }

Prior to Encode 1.86 this fails because of "local $_".

Alias overloading

You can override predefined aliases by simply applying define_alias(). The new alias is always evaluated first, and when necessary, define_alias() flushes the internal cache to make the new definition available.

  # redirect SHIFT_JIS to MS/IBM Code Page 932, which is a
  # superset of SHIFT_JIS

  define_alias( qr/shift.*jis$/i  => '"cp932"' );
  define_alias( qr/sjis$/i        => '"cp932"' );

If you want to zap all predefined aliases, you can use

  Encode::Alias->undef_aliases;

to do so. And

  Encode::Alias->init_aliases;

gets the factory settings back.

SEE ALSO

the Encode manpage, the Encode::Supported manpage


Encode::Byte - Single Byte Encodings

  • ABSTRACT
  • DESCRIPTION
  • SEE ALSO

NAME

Encode::Byte - Single Byte Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $greek = encode("iso-8859-7", $utf8);  # loads Encode::Byte implicitly
    $utf8  = decode("iso-8859-7", $greek); # ditto

ABSTRACT

This module implements various single byte encodings. For most cases it uses \x80-\xff (upper half) to map non-ASCII characters. Encodings supported are as follows.

  Canonical      Alias                                Description
  --------------------------------------------------------------------
  # ISO 8859 series
  (iso-8859-1   is in built-in)
  iso-8859-2    latin2                                       [ISO]
  iso-8859-3    latin3                                       [ISO]
  iso-8859-4    latin4                                       [ISO]
  iso-8859-5                                                 [ISO]
  iso-8859-6                                                 [ISO]
  iso-8859-7                                                 [ISO]
  iso-8859-8                                                 [ISO]
  iso-8859-9    latin5                                       [ISO]
  iso-8859-10   latin6                                       [ISO]
  iso-8859-11
  (iso-8859-12 is nonexistent)
  iso-8859-13   latin7                                       [ISO]
  iso-8859-14   latin8                                       [ISO]
  iso-8859-15   latin9                                       [ISO]
  iso-8859-16   latin10                                      [ISO]
  # Cyrillic
  koi8-f
  koi8-r        cp878                                    [RFC1489]
  koi8-u                                                 [RFC2319]
  # Vietnamese
  viscii
  # all cp* are also available as ibm-*, ms-*, and windows-*
  # also see L<http://msdn.microsoft.com/workshop/author/dhtml/reference/charsets/charset4.asp>

  cp424
  cp437
  cp737
  cp775
  cp850
  cp852
  cp855
  cp856
  cp857
  cp860
  cp861
  cp862
  cp863
  cp864
  cp865
  cp866
  cp869
  cp874
  cp1006
  cp1250        WinLatin2
  cp1251        WinCyrillic
  cp1252        WinLatin1
  cp1253        WinGreek
  cp1254        WinTurkish
  cp1255        WinHebrew
  cp1256        WinArabic
  cp1257        WinBaltic
  cp1258        WinVietnamese
  # Macintosh
  # Also see L<http://developer.apple.com/technotes/tn/tn1150.html>;
  MacArabic
  MacCentralEurRoman
  MacCroatian
  MacCyrillic
  MacFarsi
  MacGreek
  MacHebrew
  MacIcelandic
  MacRoman
  MacRomanian
  MacRumanian
  MacSami
  MacThai
  MacTurkish
  MacUkrainian
  # More vendor encodings
  AdobeStandardEncoding
  nextstep
  gsm0338       # used in GSM handsets
  hp-roman8

DESCRIPTION

To find how to use this module in detail, see the Encode manpage.

SEE ALSO

the Encode manpage


Encode::CJKConstants.pm -- Internally used by Encode::??::ISO_2022_*

  • NAME

NAME

Encode::CJKConstants.pm -- Internally used by Encode::??::ISO_2022_*


Encode::CN - China-based Chinese Encodings

  • NOTES
  • BUGS
  • SEE ALSO

NAME

Encode::CN - China-based Chinese Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $euc_cn = encode("euc-cn", $utf8);   # loads Encode::CN implicitly
    $utf8   = decode("euc-cn", $euc_cn); # ditto

DESCRIPTION

This module implements China-based Chinese charset encodings. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  euc-cn      /\beuc.*cn$/i     EUC (Extended Unix Character)
              /\bcn.*euc$/i
              /\bGB[-_ ]?2312(?:\D.*$|$)/i (see below)
  gb2312-raw                    The raw (low-bit) GB2312 character map
  gb12345-raw                   Traditional chinese counterpart to
                                GB2312 (raw)
  iso-ir-165                    GB2312 + GB6345 + GB8565 + additions
  MacChineseSimp                GB2312 + Apple Additions
  cp936                         Code Page 936, also known as GBK
                                (Extended GuoBiao)
  hz                            7-bit escaped GB2312 encoding
  --------------------------------------------------------------------

To find how to use this module in detail, see the Encode manpage.

NOTES

Due to size concerns, GB 18030 (an extension to GBK) is distributed separately on CPAN, under the name the Encode::HanExtra manpage. That module also contains extra Taiwan-based encodings.

BUGS

When you see charset=gb2312 on mails and web pages, they really mean euc-cn encodings. To fix that, gb2312 is aliased to euc-cn. Use gb2312-raw when you really mean it.

The ASCII region (0x00-0x7f) is preserved for all encodings, even though this conflicts with mappings by the Unicode Consortium. See

http://www.debian.or.jp/~kubota/unicode-symbols.html.en

to find out why it is implemented that way.

SEE ALSO

the Encode manpage


Encode::CN::HZ -- internally used by Encode::CN

  • NAME

NAME

Encode::CN::HZ -- internally used by Encode::CN


Encode::Config -- internally used by Encode

  • NAME

NAME

Encode::Config -- internally used by Encode


Encode::EBCDIC - EBCDIC Encodings

  • ABSTRACT
  • DESCRIPTION
  • SEE ALSO

NAME

Encode::EBCDIC - EBCDIC Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $posix_bc  = encode("posix-bc", $utf8); # loads Encode::EBCDIC implicitly
    $utf8 = decode("", $posix_bc);          # ditto

ABSTRACT

This module implements various EBCDIC-Based encodings. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  cp37
  cp500
  cp875
  cp1026
  cp1047
  posix-bc

DESCRIPTION

To find how to use this module in detail, see the Encode manpage.

SEE ALSO

the Encode manpage, the perlebcdic manpage


Encode::Encoder -- Object Oriented Encoder

  • ABSTRACT
  • Description
    • Predefined Methods
    • Example: base64 transcoder
    • Operator Overloading
  • SEE ALSO

NAME

Encode::Encoder -- Object Oriented Encoder

SYNOPSIS

  use Encode::Encoder;
  # Encode::encode("ISO-8859-1", $data);
  Encode::Encoder->new($data)->iso_8859_1; # OOP way
  # shortcut
  use Encode::Encoder qw(encoder);
  encoder($data)->iso_8859_1;
  # you can stack them!
  encoder($data)->iso_8859_1->base64;  # provided base64() is defined
  # you can use it as a decoder as well
  encoder($base64)->bytes('base64')->latin1;
  # stringified
  print encoder($data)->utf8->latin1;  # prints the string in latin1
  # numified
  encoder("\x{abcd}\x{ef}g")->utf8 == 6; # true. bytes::length($data)

ABSTRACT

Encode::Encoder allows you to use Encode in an object-oriented style. This is not only more intuitive than a functional approach, but also handier when you want to stack encodings. Suppose you want your UTF-8 string converted to Latin1 then Base64: you can simply say

  my $base64 = encoder($utf8)->latin1->base64;

instead of

  my $latin1 = encode("latin1", $utf8);
  my $base64 = encode_base64($utf8);

or the lazier and more convoluted

  my $base64 = encode_base64(encode("latin1", $utf8));

Description

Here is how to use this module.

  • There are at least two instance variables stored in a hash reference, {data} and {encoding}.

  • When there is no method, it takes the method name as the name of the encoding and encodes the instance data with encoding. If successful, the instance encoding is set accordingly.

  • You can retrieve the result via ->data but usually you don't have to because the stringify operator ("") is overridden to do exactly that.

Predefined Methods

This module predefines the methods below:

$e = Encode::Encoder->new([$data, $encoding]);

returns an encoder object. Its data is initialized with $data if present, and its encoding is set to $encoding if present.

When $encoding is omitted, it defaults to utf8 if $data is already in utf8 or "" (empty string) otherwise.

encoder()

is an alias of Encode::Encoder->new(). This one is exported on demand.

$e->data([$data])

When $data is present, sets the instance data to $data and returns the object itself. Otherwise, the current instance data is returned.

$e->encoding([$encoding])

When $encoding is present, sets the instance encoding to $encoding and returns the object itself. Otherwise, the current instance encoding is returned.

$e->bytes([$encoding])

decodes instance data from $encoding, or the instance encoding if omitted. If the conversion is successful, the instance encoding will be set to "".

The name bytes was deliberately picked to avoid namespace tainting -- this module may be used as a base class so method names that appear in Encode::Encoding are avoided.

Example: base64 transcoder

This module is designed to work with the Encode::Encoding manpage. To make the Base64 transcoder example above really work, you could write a module like this:

  package Encode::Base64;
  use base 'Encode::Encoding';
  __PACKAGE__->Define('base64');
  use MIME::Base64;
  sub encode{
      my ($obj, $data) = @_;
      return encode_base64($data);
  }
  sub decode{
      my ($obj, $data) = @_;
      return decode_base64($data);
  }
  1;
  __END__

And your caller module would be something like this:

  use Encode::Encoder;
  use Encode::Base64;

  # now you can really do the following

  encoder($data)->iso_8859_1->base64;
  encoder($base64)->bytes('base64')->latin1;

Operator Overloading

This module overloads two operators, stringify ("") and numify (0+).

Stringify dumps the data inside the object.

Numify returns the number of bytes in the instance data.

They come in handy when you want to print or find the size of data.

SEE ALSO

the Encode manpage, the Encode::Encoding manpage


Encode::Encoding - Encode Implementation Base Class

    • Methods you should implement
    • Other methods defined in Encode::Encodings
    • Example: Encode::ROT13
  • Why the heck Encode API is different?
    • Compiled Encodings
  • SEE ALSO

NAME

Encode::Encoding - Encode Implementation Base Class

SYNOPSIS

  package Encode::MyEncoding;
  use base qw(Encode::Encoding);

  __PACKAGE__->Define(qw(myCanonical myAlias));

DESCRIPTION

As mentioned in the Encode manpage, encodings are (in the current implementation at least) defined as objects. The mapping of encoding name to object is via the %Encode::Encoding hash. Though you can directly manipulate this hash, it is strongly encouraged to use this base class module and add encode() and decode() methods.

Methods you should implement

You are strongly encouraged to implement methods below, at least either encode() or decode().

->encode($string [,$check])

MUST return the octet sequence representing $string.

  • If $check is true, it SHOULD modify $string in place to remove the converted part (i.e. the whole string unless there is an error). If perlio_ok() is true, SHOULD becomes MUST.

  • If an error occurs, it SHOULD return the octet sequence for the fragment of string that has been converted and modify $string in-place to remove the converted part leaving it starting with the problem fragment. If perlio_ok() is true, SHOULD becomes MUST.

  • If $check is is false then encode MUST make a "best effort" to convert the string - for example, by using a replacement character.

->decode($octets [,$check])

MUST return the string that $octets represents.

  • If $check is true, it SHOULD modify $octets in place to remove the converted part (i.e. the whole sequence unless there is an error). If perlio_ok() is true, SHOULD becomes MUST.

  • If an error occurs, it SHOULD return the fragment of string that has been converted and modify $octets in-place to remove the converted part leaving it starting with the problem fragment. If perlio_ok() is true, SHOULD becomes MUST.

  • If $check is false then decode should make a "best effort" to convert the string - for example by using Unicode's "\x{FFFD}" as a replacement character.

If you want your encoding to work with the encoding manpage pragma, you should also implement the method below.

->cat_decode($destination, $octets, $offset, $terminator [,$check])

MUST decode $octets with $offset and concatenate it to $destination. Decoding will terminate when $terminator (a string) appears in output. $offset will be modified to the last $octets position at end of decode. Returns true if $terminator appears output, else returns false.

Other methods defined in Encode::Encodings

You do not have to override methods shown below unless you have to.

->name

Predefined As:

  sub name  { return shift->{'Name'} }

MUST return the string representing the canonical name of the encoding.

->renew

Predefined As:

  sub renew {
    my $self = shift;
    my $clone = bless { %$self } => ref($self);
    $clone->{renewed}++;
    return $clone;
  }

This method reconstructs the encoding object if necessary. If you need to store the state during encoding, this is where you clone your object.

PerlIO ALWAYS calls this method to make sure it has its own private encoding object.

->renewed

Predefined As:

  sub renewed { $_[0]->{renewed} || 0 }

Tells whether the object is renewed (and how many times). Some modules emit Use of uninitialized value in null operation warning unless the value is numeric so return 0 for false.

->perlio_ok()

Predefined As:

  sub perlio_ok {
      eval{ require PerlIO::encoding };
      return $@ ? 0 : 1;
  }

If your encoding does not support PerlIO for some reasons, just;

 sub perlio_ok { 0 }
->needs_lines()

Predefined As:

  sub needs_lines { 0 };

If your encoding can work with PerlIO but needs line buffering, you MUST define this method so it returns true. 7bit ISO-2022 encodings are one example that needs this. When this method is missing, false is assumed.

Example: Encode::ROT13

  package Encode::ROT13;
  use strict;
  use base qw(Encode::Encoding);

  __PACKAGE__->Define('rot13');

  sub encode($$;$){
      my ($obj, $str, $chk) = @_;
      $str =~ tr/A-Za-z/N-ZA-Mn-za-m/;
      $_[1] = '' if $chk; # this is what in-place edit means
      return $str;
  }

  # Jr pna or ynml yvxr guvf;
  *decode = \&encode;

  1;

Why the heck Encode API is different?

It should be noted that the $check behaviour is different from the outer public API. The logic is that the "unchecked" case is useful when the encoding is part of a stream which may be reporting errors (e.g. STDERR). In such cases, it is desirable to get everything through somehow without causing additional errors which obscure the original one. Also, the encoding is best placed to know what the correct replacement character is, so if that is the desired behaviour then letting low level code do it is the most efficient.

By contrast, if $check is true, the scheme above allows the encoding to do as much as it can and tell the layer above how much that was. What is lacking at present is a mechanism to report what went wrong. The most likely interface will be an additional method call to the object, or perhaps (to avoid forcing per-stream objects on otherwise stateless encodings) an additional parameter.

It is also highly desirable that encoding classes inherit from Encode::Encoding as a base class. This allows that class to define additional behaviour for all encoding objects.

  package Encode::MyEncoding;
  use base qw(Encode::Encoding);

  __PACKAGE__->Define(qw(myCanonical myAlias));

to create an object with bless {Name => ...}, $class, and call define_encoding. They inherit their name method from Encode::Encoding.

Compiled Encodings

For the sake of speed and efficiency, most of the encodings are now supported via a compiled form: XS modules generated from UCM files. Encode provides the enc2xs tool to achieve that. Please see enc2xs for more details.

SEE ALSO

the perlmod manpage, enc2xs


Encode::Guess -- Guesses encoding from data

  • ABSTRACT
  • DESCRIPTION
  • CAVEATS
  • TO DO
  • SEE ALSO

NAME

Encode::Guess -- Guesses encoding from data

SYNOPSIS

  # if you are sure $data won't contain anything bogus

  use Encode;
  use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;
  my $utf8 = decode("Guess", $data);
  my $data = encode("Guess", $utf8);   # this doesn't work!

  # more elaborate way
  use Encode::Guess;
  my $enc = guess_encoding($data, qw/euc-jp shiftjis 7bit-jis/);
  ref($enc) or die "Can't guess: $enc"; # trap error this way
  $utf8 = $enc->decode($data);
  # or
  $utf8 = decode($enc->name, $data)

ABSTRACT

Encode::Guess enables you to guess in what encoding a given data is encoded, or at least tries to.

DESCRIPTION

By default, it checks only ascii, utf8 and UTF-16/32 with BOM.

  use Encode::Guess; # ascii/utf8/BOMed UTF

To use it more practically, you have to give the names of encodings to check (suspects as follows). The name of suspects can either be canonical names or aliases.

CAVEAT: Unlike UTF-(16|32), BOM in utf8 is NOT AUTOMATICALLY STRIPPED.

 # tries all major Japanese Encodings as well
  use Encode::Guess qw/euc-jp shiftjis 7bit-jis/;

If the $Encode::Guess::NoUTFAutoGuess variable is set to a true value, no heuristics will be applied to UTF8/16/32, and the result will be limited to the suspects and ascii.

Encode::Guess->set_suspects

You can also change the internal suspects list via set_suspects method.

  use Encode::Guess;
  Encode::Guess->set_suspects(qw/euc-jp shiftjis 7bit-jis/);
Encode::Guess->add_suspects

Or you can use add_suspects method. The difference is that set_suspects flushes the current suspects list while add_suspects adds.

  use Encode::Guess;
  Encode::Guess->add_suspects(qw/euc-jp shiftjis 7bit-jis/);
  # now the suspects are euc-jp,shiftjis,7bit-jis, AND
  # euc-kr,euc-cn, and big5-eten
  Encode::Guess->add_suspects(qw/euc-kr euc-cn big5-eten/);
Encode::decode("Guess" ...)

When you are content with suspects list, you can now

  my $utf8 = Encode::decode("Guess", $data);
Encode::Guess->guess($data)

But it will croak if:

  • Two or more suspects remain

  • No suspects left

So you should instead try this;

  my $decoder = Encode::Guess->guess($data);

On success, $decoder is an object that is documented in the Encode::Encoding manpage. So you can now do this;

  my $utf8 = $decoder->decode($data);

On failure, $decoder now contains an error message so the whole thing would be as follows;

  my $decoder = Encode::Guess->guess($data);
  die $decoder unless ref($decoder);
  my $utf8 = $decoder->decode($data);
guess_encoding($data, [, list of suspects])

You can also try guess_encoding function which is exported by default. It takes $data to check and it also takes the list of suspects by option. The optional suspect list is not reflected to the internal suspects list.

  my $decoder = guess_encoding($data, qw/euc-jp euc-kr euc-cn/);
  die $decoder unless ref($decoder);
  my $utf8 = $decoder->decode($data);
  # check only ascii and utf8
  my $decoder = guess_encoding($data);

CAVEATS

  • Because of the algorithm used, ISO-8859 series and other single-byte encodings do not work well unless either one of ISO-8859 is the only one suspect (besides ascii and utf8).

      use Encode::Guess;
  # perhaps ok
  my $decoder = guess_encoding($data, 'latin1');
  # definitely NOT ok
  my $decoder = guess_encoding($data, qw/latin1 greek/);

    The reason is that Encode::Guess guesses encoding by trial and error. It first splits $data into lines and tries to decode the line for each suspect. It keeps it going until all but one encoding is eliminated out of suspects list. ISO-8859 series is just too successful for most cases (because it fills almost all code points in \x00-\xff).

  • Do not mix national standard encodings and the corresponding vendor encodings.

      # a very bad idea
  my $decoder
     = guess_encoding($data, qw/shiftjis MacJapanese cp932/);

    The reason is that vendor encoding is usually a superset of national standard so it becomes too ambiguous for most cases.

  • On the other hand, mixing various national standard encodings automagically works unless $data is too short to allow for guessing.

     # This is ok if $data is long enough
 my $decoder =
  guess_encoding($data, qw/euc-cn
                           euc-jp shiftjis 7bit-jis
                           euc-kr
                           big5-eten/);

  • DO NOT PUT TOO MANY SUSPECTS! Don't you try something like this!

      my $decoder = guess_encoding($data,
                               Encode->encodings(":all"));

It is, after all, just a guess. You should alway be explicit when it comes to encodings. But there are some, especially Japanese, environment that guess-coding is a must. Use this module with care.

TO DO

Encode::Guess does not work on EBCDIC platforms.

SEE ALSO

the Encode manpage, the Encode::Encoding manpage


Encode::JP - Japanese Encodings

  • ABSTRACT
  • DESCRIPTION
  • Note on ISO-2022-JP(-1)?
  • BUGS
  • SEE ALSO

NAME

Encode::JP - Japanese Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $euc_jp = encode("euc-jp", $utf8);   # loads Encode::JP implicitly
    $utf8   = decode("euc-jp", $euc_jp); # ditto

ABSTRACT

This module implements Japanese charset encodings. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  euc-jp      /\beuc.*jp$/i     EUC (Extended Unix Character)
              /\bjp.*euc/i
              /\bujis$/i
  shiftjis    /\bshift.*jis$/i  Shift JIS (aka MS Kanji)
              /\bsjis$/i
  7bit-jis    /\bjis$/i         7bit JIS
  iso-2022-jp                   ISO-2022-JP                  [RFC1468]
                                = 7bit JIS with all Halfwidth Kana
                                  converted to Fullwidth
  iso-2022-jp-1                 ISO-2022-JP-1                [RFC2237]
                                = ISO-2022-JP with JIS X 0212-1990
                                  support.  See below
  MacJapanese                   Shift JIS + Apple vendor mappings
  cp932       /\bwindows-31j$/i Code Page 932
                                = Shift JIS + MS/IBM vendor mappings
  jis0201-raw                   JIS0201, raw format
  jis0208-raw                   JIS0201, raw format
  jis0212-raw                   JIS0201, raw format
  --------------------------------------------------------------------

DESCRIPTION

To find out how to use this module in detail, see the Encode manpage.

Note on ISO-2022-JP(-1)?

ISO-2022-JP-1 (RFC2237) is a superset of ISO-2022-JP (RFC1468) which adds support for JIS X 0212-1990. That means you can use the same code to decode to utf8 but not vice versa.

  $utf8 = decode('iso-2022-jp-1', $stream);

and

  $utf8 = decode('iso-2022-jp',   $stream);

yield the same result but

  $with_0212 = encode('iso-2022-jp-1', $utf8);

is now different from

  $without_0212 = encode('iso-2022-jp', $utf8 );

In the latter case, characters that map to 0212 are first converted to U+3013 (0xA2AE in EUC-JP; a white square also known as 'Tofu' or 'geta mark') then fed to the decoding engine. U+FFFD is not used, in order to preserve text layout as much as possible.

BUGS

The ASCII region (0x00-0x7f) is preserved for all encodings, even though this conflicts with mappings by the Unicode Consortium. See

http://www.debian.or.jp/~kubota/unicode-symbols.html.en

to find out why it is implemented that way.

SEE ALSO

the Encode manpage


Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*

  • NAME

NAME

Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*


Encode::JP::JIS7 -- internally used by Encode::JP

  • NAME

NAME

Encode::JP::JIS7 -- internally used by Encode::JP


Encode::KR - Korean Encodings

  • BUGS
  • SEE ALSO

NAME

Encode::KR - Korean Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $euc_kr = encode("euc-kr", $utf8);   # loads Encode::KR implicitly
    $utf8   = decode("euc-kr", $euc_kr); # ditto

DESCRIPTION

This module implements Korean charset encodings. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  euc-kr      /\beuc.*kr$/i     EUC (Extended Unix Character)
              /\bkr.*euc$/i
  ksc5601-raw                   Korean standard code set (as is)
  cp949       /(?:x-)?uhc$/i
              /(?:x-)?windows-949$/i
              /\bks_c_5601-1987$/i
                                Code Page 949 (EUC-KR + 8,822
                                (additional Hangul syllables)
  MacKorean                     EUC-KR + Apple Vendor Mappings
  johab       JOHAB             A supplementary encoding defined in
                                             Annex 3 of KS X 1001:1998
  iso-2022-kr                   iso-2022-kr                  [RFC1557]
  --------------------------------------------------------------------

To find how to use this module in detail, see the Encode manpage.

BUGS

When you see charset=ks_c_5601-1987 on mails and web pages, they really mean "cp949" encodings. To fix that, the following aliases are set;

  qr/(?:x-)?uhc$/i         => '"cp949"'
  qr/(?:x-)?windows-949$/i => '"cp949"'
  qr/ks_c_5601-1987$/i     => '"cp949"'

The ASCII region (0x00-0x7f) is preserved for all encodings, even though this conflicts with mappings by the Unicode Consortium. See

http://www.debian.or.jp/~kubota/unicode-symbols.html.en

to find out why it is implemented that way.

SEE ALSO

the Encode manpage


Encode::KR::2022_KR -- internally used by Encode::KR

  • NAME

NAME

Encode::KR::2022_KR -- internally used by Encode::KR


Encode::MIME::Header -- MIME 'B' and 'Q' header encoding

  • ABSTRACT
  • DESCRIPTION
  • BUGS
  • SEE ALSO

NAME

Encode::MIME::Header -- MIME 'B' and 'Q' header encoding

SYNOPSIS

    use Encode qw/encode decode/;
    $utf8   = decode('MIME-Header', $header);
    $header = encode('MIME-Header', $utf8);

ABSTRACT

This module implements RFC 2047 Mime Header Encoding. There are 3 variant encoding names; MIME-Header, MIME-B and MIME-Q. The difference is described below

              decode()          encode()
  ----------------------------------------------
  MIME-Header Both B and Q      =?UTF-8?B?....?=
  MIME-B      B only; Q croaks  =?UTF-8?B?....?=
  MIME-Q      Q only; B croaks  =?UTF-8?Q?....?=

DESCRIPTION

When you decode(=?encoding?X?ENCODED WORD?=), ENCODED WORD is extracted and decoded for X encoding (B for Base64, Q for Quoted-Printable). Then the decoded chunk is fed to decode(encoding). So long as encoding is supported by Encode, any source encoding is fine.

When you encode, it just encodes UTF-8 string with X encoding then quoted with =?UTF-8?X?....?= . The parts that RFC 2047 forbids to encode are left as is and long lines are folded within 76 bytes per line.

BUGS

It would be nice to support encoding to non-UTF8, such as =?ISO-2022-JP? and =?ISO-8859-1?= but that makes the implementation too complicated. These days major mail agents all support =?UTF-8? so I think it is just good enough.

Due to popular demand, 'MIME-Header-ISO_2022_JP' was introduced by Makamaka. Thre are still too many MUAs especially cellular phone handsets which does not grok UTF-8.

SEE ALSO

the Encode manpage

RFC 2047, http://www.faqs.org/rfcs/rfc2047.html and many other locations.


Encode::PerlIO -- a detailed document on Encode and PerlIO

  • Overview
  • How does it work?
  • Line Buffering
    • How can I tell whether my encoding fully supports PerlIO ?
  • SEE ALSO

NAME

Encode::PerlIO -- a detailed document on Encode and PerlIO

Overview

It is very common to want to do encoding transformations when reading or writing files, network connections, pipes etc. If Perl is configured to use the new 'perlio' IO system then Encode provides a "layer" (see the PerlIO manpage) which can transform data as it is read or written.

Here is how the blind poet would modernise the encoding:

    use Encode;
    open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
    open(my $utf8,'>:utf8','iliad.utf8');
    my @epic = <$iliad>;
    print $utf8 @epic;
    close($utf8);
    close($illiad);

In addition, the new IO system can also be configured to read/write UTF-8 encoded characters (as noted above, this is efficient):

    open(my $fh,'>:utf8','anything');
    print $fh "Any \x{0021} string \N{SMILEY FACE}\n";

Either of the above forms of "layer" specifications can be made the default for a lexical scope with the use open ... pragma. See the open manpage.

Once a handle is open, its layers can be altered using binmode.

Without any such configuration, or if Perl itself is built using the system's own IO, then write operations assume that the file handle accepts only bytes and will die if a character larger than 255 is written to the handle. When reading, each octet from the handle becomes a byte-in-a-character. Note that this default is the same behaviour as bytes-only languages (including Perl before v5.6) would have, and is sufficient to handle native 8-bit encodings e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling other encodings and binary data.

In other cases, it is the program's responsibility to transform characters into bytes using the API above before doing writes, and to transform the bytes read from a handle into characters before doing "character operations" (e.g. lc, /\W+/, ...).

You can also use PerlIO to convert larger amounts of data you don't want to bring into memory. For example, to convert between ISO-8859-1 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):

    open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
    open(G, ">:utf8",                 "data.utf") or die $!;
    while (<F>) { print G }

    # Could also do "print G <F>" but that would pull
    # the whole file into memory just to write it out again.

More examples:

    open(my $f, "<:encoding(cp1252)")
    open(my $g, ">:encoding(iso-8859-2)")
    open(my $h, ">:encoding(latin9)")       # iso-8859-15

See also the encoding manpage for how to change the default encoding of the data in your script.

How does it work?

Here is a crude diagram of how filehandle, PerlIO, and Encode interact.

  filehandle <-> PerlIO        PerlIO <-> scalar (read/printed)
                       \      /
                        Encode

When PerlIO receives data from either direction, it fills a buffer (currently with 1024 bytes) and passes the buffer to Encode. Encode tries to convert the valid part and passes it back to PerlIO, leaving invalid parts (usually a partial character) in the buffer. PerlIO then appends more data to the buffer, calls Encode again, and so on until the data stream ends.

To do so, PerlIO always calls (de|en)code methods with CHECK set to 1. This ensures that the method stops at the right place when it encounters partial character. The following is what happens when PerlIO and Encode tries to encode (from utf8) more than 1024 bytes and the buffer boundary happens to be in the middle of a character.

   A   B   C   ....   ~     \x{3000}    ....
     41  42  43   ....  7E   e3   80   80  ....
     <- buffer --------------->
     << encoded >>>>>>>>>>
                       <- next buffer ------

Encode converts from the beginning to \x7E, leaving \xe3 in the buffer because it is invalid (partial character).

Unfortunately, this scheme does not work well with escape-based encodings such as ISO-2022-JP.

Line Buffering

Now let's see what happens when you try to decode from ISO-2022-JP and the buffer ends in the middle of a character.

                          JIS208-ESC   \x{5f3e}
                             A   B   C   ....   ~   \e   $   B  |DAN | ....
                            41  42  43   ....  7E   1b  24  41  43  46 ....
                            <- buffer --------------------------->
                            << encoded >>>>>>>>>>>>>>>>>>>>>>>

As you see, the next buffer begins with \x43. But \x43 is 'C' in ASCII, which is wrong in this case because we are now in JISX 0208 area so it has to convert \x43\x46, not \x43. Unlike utf8 and EUC, in escape-based encodings you can't tell if a given octet is a whole character or just part of it.

Fortunately PerlIO also supports line buffer if you tell PerlIO to use one instead of fixed buffer. Since ISO-2022-JP is guaranteed to revert to ASCII at the end of the line, partial character will never happen when line buffer is used.

To tell PerlIO to use line buffer, implement ->needs_lines method for your encoding object. See the Encode::Encoding manpage for details.

Thanks to these efforts most encodings that come with Encode support PerlIO but that still leaves following encodings.

  iso-2022-kr
  MIME-B
  MIME-Header
  MIME-Q

Fortunately iso-2022-kr is hardly used (according to Jungshik) and MIME-* are very unlikely to be fed to PerlIO because they are for mail headers. See the Encode::MIME::Header manpage for details.

How can I tell whether my encoding fully supports PerlIO ?

As of this writing, any encoding whose class belongs to Encode::XS and Encode::Unicode works. The Encode module has a perlio_ok method which you can use before applying PerlIO encoding to the filehandle. Here is an example:

  my $use_perlio = perlio_ok($enc);
  my $layer = $use_perlio ? "<:raw" : "<:encoding($enc)";
  open my $fh, $layer, $file or die "$file : $!";
  while(<$fh>){
    $_ = decode($enc, $_) unless $use_perlio;
    # ....
  }

SEE ALSO

the Encode::Encoding manpage, the Encode::Supported manpage, the Encode::PerlIO manpage, the encoding manpage, the perlebcdic manpage, open in the perlfunc manpage, the perlunicode manpage, the utf8 manpage, the Perl Unicode Mailing List <perl-unicode@perl.org>


Encode::Supported -- Encodings supported by Encode

    • Encoding Names
  • Supported Encodings
    • Built-in Encodings
    • Encode::Unicode - other Unicode encodings
    • Encode::Byte - Extended ASCII
    • CJK: Chinese, Japanese, Korean (Multibyte)
    • Miscellaneous encodings
  • Unsupported encodings
  • Encoding vs. Charset - terminology
  • Encoding Classification (by Anton Tagunov and Dan Kogai)
    • Microsoft-related naming mess
  • Glossary
  • See Also
  • References
    • Other Notable Sites
    • Offline sources

NAME

Encode::Supported -- Encodings supported by Encode

DESCRIPTION

Encoding Names

Encoding names are case insensitive. White space in names is ignored. In addition, an encoding may have aliases. Each encoding has one "canonical" name. The "canonical" name is chosen from the names of the encoding by picking the first in the following sequence (with a few exceptions).

  • The name used by the Perl community. That includes 'utf8' and 'ascii'. Unlike aliases, canonical names directly reach the method so such frequently used words like 'utf8' don't need to do alias lookups.

  • The MIME name as defined in IETF RFCs. This includes all "iso-"s.

  • The name in the IANA registry.

  • The name used by the organization that defined it.

In case de jure canonical names differ from that of the Encode module, they are always aliased if it ever be implemented. So you can safely tell if a given encoding is implemented or not just by passing the canonical name.

Because of all the alias issues, and because in the general case encodings have state, "Encode" uses an encoding object internally once an operation is in progress.

Supported Encodings

As of Perl 5.8.0, at least the following encodings are recognized. Note that unless otherwise specified, they are all case insensitive (via alias) and all occurrence of spaces are replaced with '-'. In other words, "ISO 8859 1" and "iso-8859-1" are identical.

Encodings are categorized and implemented in several different modules but you don't have to use Encode::XX to make them available for most cases. Encode.pm will automatically load those modules on demand.

Built-in Encodings

The following encodings are always available.

  Canonical     Aliases                      Comments & References
  ----------------------------------------------------------------
  ascii         US-ascii ISO-646-US                         [ECMA]
  ascii-ctrl                                      Special Encoding
  iso-8859-1    latin1                                       [ISO]
  null                                            Special Encoding
  utf8          UTF-8                                    [RFC2279]
  ----------------------------------------------------------------

null and ascii-ctrl are special. "null" fails for all character so when you set fallback mode to PERLQQ, HTMLCREF or XMLCREF, ALL CHARACTERS will fall back to character references. Ditto for "ascii-ctrl" except for control characters. For fallback modes, see the Encode manpage.

Encode::Unicode -- other Unicode encodings

Unicode coding schemes other than native utf8 are supported by Encode::Unicode, which will be autoloaded on demand.

  ----------------------------------------------------------------
  UCS-2BE       UCS-2, iso-10646-1                      [IANA, UC]
  UCS-2LE                                                     [UC]
  UTF-16                                                      [UC]
  UTF-16BE                                                    [UC]
  UTF-16LE                                                    [UC]
  UTF-32                                                      [UC]
  UTF-32BE      UCS-4                                         [UC]
  UTF-32LE                                                    [UC]
  UTF-7                                                  [RFC2152]
  ----------------------------------------------------------------

To find how (UCS-2|UTF-(16|32))(LE|BE)? differ from one another, see the Encode::Unicode manpage.

UTF-7 is a special encoding which "re-encodes" UTF-16BE into a 7-bit encoding. It is implemented seperately by Encode::Unicode::UTF7.

Encode::Byte -- Extended ASCII

Encode::Byte implements most single-byte encodings except for Symbols and EBCDIC. The following encodings are based on single-byte encodings implemented as extended ASCII. Most of them map \x80-\xff (upper half) to non-ASCII characters.

ISO-8859 and corresponding vendor mappings

Since there are so many, they are presented in table format with languages and corresponding encoding names by vendors. Note that the table is sorted in order of ISO-8859 and the corresponding vendor mappings are slightly different from that of ISO. See http://czyborra.com/charsets/iso8859.html for details.

  Lang/Regions  ISO/Other Std.  DOS     Windows Macintosh  Others
  ----------------------------------------------------------------
  N. America    (ASCII)         cp437        AdobeStandardEncoding
                                cp863 (DOSCanadaF)
  W. Europe     iso-8859-1      cp850   cp1252  MacRoman  nextstep
                                                         hp-roman8
                                cp860 (DOSPortuguese)
  Cntrl. Europe iso-8859-2      cp852   cp1250  MacCentralEurRoman
                                                MacCroatian
                                                MacRomanian
                                                MacRumanian
  Latin3[1]     iso-8859-3
  Latin4[2]     iso-8859-4
  Cyrillics     iso-8859-5      cp855   cp1251  MacCyrillic
    (See also next section)     cp866           MacUkrainian
  Arabic        iso-8859-6      cp864   cp1256  MacArabic
                                cp1006          MacFarsi
  Greek         iso-8859-7      cp737   cp1253  MacGreek
                                cp869 (DOSGreek2)
  Hebrew        iso-8859-8      cp862   cp1255  MacHebrew
  Turkish       iso-8859-9      cp857   cp1254  MacTurkish
  Nordics       iso-8859-10     cp865
                                cp861           MacIcelandic
                                                MacSami
  Thai          iso-8859-11[3]  cp874           MacThai
  (iso-8859-12 is nonexistent. Reserved for Indics?)
  Baltics       iso-8859-13     cp775           cp1257
  Celtics       iso-8859-14
  Latin9 [4]    iso-8859-15
  Latin10       iso-8859-16
  Vietnamese    viscii                  cp1258  MacVietnamese
  ----------------------------------------------------------------
  [1] Esperanto, Maltese, and Turkish. Turkish is now on 8859-9.
  [2] Baltics.  Now on 8859-10, except for Latvian.
  [3] TIS 620 +  Non-Breaking Space (0xA0 / U+00A0)
  [4] Nicknamed Latin0; the Euro sign as well as French and Finnish
      letters that are missing from 8859-1 were added.

All cp* are also available as ibm-*, ms-*, and windows-* . See also http://czyborra.com/charsets/codepages.html.

Macintosh encodings don't seem to be registered in such entities as IANA. "Canonical" names in Encode are based upon Apple's Tech Note 1150. See http://developer.apple.com/technotes/tn/tn1150.html for details.

KOI8 - De Facto Standard for the Cyrillic world

Though ISO-8859 does have ISO-8859-5, the KOI8 series is far more popular in the Net. the Encode manpage comes with the following KOI charsets. For gory details, see http://czyborra.com/charsets/cyrillic.html

  ----------------------------------------------------------------
  koi8-f
  koi8-r cp878                                           [RFC1489]
  koi8-u                                                 [RFC2319]
  ----------------------------------------------------------------
gsm0338 - Hentai Latin 1

GSM0338 is for GSM handsets. Though it shares alphanumerals with ASCII, control character ranges and other parts are mapped very differently, mainly to store Greek characters. There are also escape sequences (starting with 0x1B) to cover e.g. the Euro sign. Some special cases like a trailing 0x00 byte or a lone 0x1B byte are not well-defined and decode() will return an empty string for them. One possible workaround is

   $gsm =~ s/\x00\z/\x00\x00/;
   $uni = decode("gsm0338", $gsm);
   $uni .= "\xA0" if $gsm =~ /\x1B\z/;

Note that the Encode implementation of GSM0338 does not implement the reuse of Latin capital letters as Greek capital letters (for example, the 0x5A is U+005A (LATIN CAPITAL LETTER Z), not U+0396 (GREEK CAPITAL LETTER ZETA).

The GSM0338 is also covered in Encode::Byte even though it is not an "extended ASCII" encoding.

CJK: Chinese, Japanese, Korean (Multibyte)

Note that Vietnamese is listed above. Also read "Encoding vs Charset" below. Also note that these are implemented in distinct modules by countries, due to the size concerns (simplified Chinese is mapped to 'CN', continental China, while traditional Chinese is mapped to 'TW', Taiwan). Please refer to their respective documentation pages.

Encode::CN -- Continental China
  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  euc-cn [1]            MacChineseSimp
  (gbk)         cp936 [2]
  gb12345-raw                      { GB12345 without CES }
  gb2312-raw                       { GB2312  without CES }
  hz
  iso-ir-165
  ----------------------------------------------------------------

  [1] GB2312 is aliased to this.  See L<Microsoft-related naming mess>
  [2] gbk is aliased to this.  See L<Microsoft-related naming mess>
Encode::JP -- Japan
  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  euc-jp
  shiftjis      cp932   macJapanese
  7bit-jis
  iso-2022-jp                                            [RFC1468]
  iso-2022-jp-1                                          [RFC2237]
  jis0201-raw  { JIS X 0201 (roman + halfwidth kana) without CES }
  jis0208-raw  { JIS X 0208 (Kanji + fullwidth kana) without CES }
  jis0212-raw  { JIS X 0212 (Extended Kanji)         without CES }
  ----------------------------------------------------------------
Encode::KR -- Korea
  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  euc-kr                MacKorean                        [RFC1557]
                cp949 [1]
  iso-2022-kr                                            [RFC1557]
  johab                                  [KS X 1001:1998, Annex 3]
  ksc5601-raw                              { KSC5601 without CES }
  ----------------------------------------------------------------

  [1] ks_c_5601-1987, (x-)?windows-949, and uhc are aliased to this.
  See below.
Encode::TW -- Taiwan
  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  big5-eten     cp950   MacChineseTrad {big5 aliased to big5-eten}
  big5-hkscs
  ----------------------------------------------------------------
Encode::HanExtra -- More Chinese via CPAN

Due to the size concerns, additional Chinese encodings below are distributed separately on CPAN, under the name Encode::HanExtra.

  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  big5ext                                   CMEX's Big5e Extension
  big5plus                                  CMEX's Big5+ Extension
  cccii         Chinese Character Code for Information Interchange
  euc-tw                             EUC (Extended Unix Character)
  gb18030                          GBK with Traditional Characters
  ----------------------------------------------------------------
Encode::JIS2K -- JIS X 0213 encodings via CPAN

Due to size concerns, additional Japanese encodings below are distributed separately on CPAN, under the name Encode::JIS2K.

  Standard      DOS/Win Macintosh                Comment/Reference
  ----------------------------------------------------------------
  euc-jisx0213
  shiftjisx0123
  iso-2022-jp-3
  jis0213-1-raw
  jis0213-2-raw
  ----------------------------------------------------------------

Miscellaneous encodings

Encode::EBCDIC

See the perlebcdic manpage for details.

  ----------------------------------------------------------------
  cp37
  cp500
  cp875
  cp1026
  cp1047
  posix-bc
  ----------------------------------------------------------------
Encode::Symbols

For symbols and dingbats.

  ----------------------------------------------------------------
  symbol
  dingbats
  MacDingbats
  AdobeZdingbat
  AdobeSymbol
  ----------------------------------------------------------------
Encode::MIME::Header

Strictly speaking, MIME header encoding documented in RFC 2047 is more of encapsulation than encoding. However, their support in modern world is imperative so they are supported.

  ----------------------------------------------------------------
  MIME-Header                                            [RFC2047]
  MIME-B                                                 [RFC2047]
  MIME-Q                                                 [RFC2047]
  ----------------------------------------------------------------
Encode::Guess

This one is not a name of encoding but a utility that lets you pick up the most appropriate encoding for a data out of given suspects. See the Encode::Guess manpage for details.

Unsupported encodings

The following encodings are not supported as yet; some because they are rarely used, some because of technical difficulties. They may be supported by external modules via CPAN in the future, however.

ISO-2022-JP-2 [RFC1554]

Not very popular yet. Needs Unicode Database or equivalent to implement encode() (because it includes JIS X 0208/0212, KSC5601, and GB2312 simultaneously, whose code points in Unicode overlap. So you need to lookup the database to determine to what character set a given Unicode character should belong).

ISO-2022-CN [RFC1922]

Not very popular. Needs CNS 11643-1 and -2 which are not available in this module. CNS 11643 is supported (via euc-tw) in Encode::HanExtra. Autrijus Tang may add support for this encoding in his module in future.

Various HP-UX encodings

The following are unsupported due to the lack of mapping data.

  '8'  - arabic8, greek8, hebrew8, kana8, thai8, and turkish8
  '15' - japanese15, korean15, and roi15
Cyrillic encoding ISO-IR-111

Anton Tagunov doubts its usefulness.

ISO-8859-8-1 [Hebrew]

None of the Encode team knows Hebrew enough (ISO-8859-8, cp1255 and MacHebrew are supported because and just because there were mappings available at http://www.unicode.org/). Contributions welcome.

ISIRI 3342, Iran System, ISIRI 2900 [Farsi]

Ditto.

Thai encoding TCVN

Ditto.

Vietnamese encodings VPS

Though Jungshik Shin has reported that Mozilla supports this encoding, it was too late before 5.8.0 for us to add it. In the future, it may be available via a separate module. See http://lxr.mozilla.org/seamonkey/source/intl/uconv/ucvlatin/vps.uf and http://lxr.mozilla.org/seamonkey/source/intl/uconv/ucvlatin/vps.ut if you are interested in helping us.

Various Mac encodings

The following are unsupported due to the lack of mapping data.

  MacArmenian,  MacBengali,   MacBurmese,   MacEthiopic
  MacExtArabic, MacGeorgian,  MacKannada,   MacKhmer
  MacLaotian,   MacMalayalam, MacMongolian, MacOriya
  MacSinhalese, MacTamil,     MacTelugu,    MacTibetan
  MacVietnamese

The rest which are already available are based upon the vendor mappings at http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/ .

(Mac) Indic encodings

The maps for the following are available at http://www.unicode.org/ but remain unsupport because those encodings need algorithmical approach, currently unsupported by enc2xs:

  MacDevanagari
  MacGurmukhi
  MacGujarati

For details, please see Unicode mapping issues and notes: at http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/DEVANAGA.TXT .

I believe this issue is prevalent not only for Mac Indics but also in other Indic encodings, but the above were the only Indic encodings maps that I could find at http://www.unicode.org/ .

Encoding vs. Charset -- terminology

We are used to using the term (character) encoding and character set interchangeably. But just as confusing the terms byte and character is dangerous and the terms should be differentiated when needed, we need to differentiate encoding and character set.

To understand that, here is a description of how we make computers grok our characters.

  • First we start with which characters to include. We call this collection of characters character repertoire.

  • Then we have to give each character a unique ID so your computer can tell the difference between 'a' and 'A'. This itemized character repertoire is now a character set.

  • If your computer can grow the character set without further processing, you can go ahead and use it. This is called a coded character set (CCS) or raw character encoding. ASCII is used this way for most cases.

  • But in many cases, especially multi-byte CJK encodings, you have to tweak a little more. Your network connection may not accept any data with the Most Significant Bit set, and your computer may not be able to tell if a given byte is a whole character or just half of it. So you have to encode the character set to use it.

    A character encoding scheme (CES) determines how to encode a given character set, or a set of multiple character sets. 7bit ISO-2022 is an example of a CES. You switch between character sets via escape sequences.

Technically, or mathematically, speaking, a character set encoded in such a CES that maps character by character may form a CCS. EUC is such an example. The CES of EUC is as follows:

  • Map ASCII unchanged.

  • Map such a character set that consists of 94 or 96 powered by N members by adding 0x80 to each byte.

  • You can also use 0x8e and 0x8f to indicate that the following sequence of characters belongs to yet another character set. To each following byte is added the value 0x80.

By carefully looking at the encoded byte sequence, you can find that the byte sequence conforms a unique number. In that sense, EUC is a CCS generated by a CES above from up to four CCS (complicated?). UTF-8 falls into this category. See perlUnicode/"UTF-8" to find out how UTF-8 maps Unicode to a byte sequence.

You may also have found out by now why 7bit ISO-2022 cannot comprise a CCS. If you look at a byte sequence \x21\x21, you can't tell if it is two !'s or IDEOGRAPHIC SPACE. EUC maps the latter to \xA1\xA1 so you have no trouble differentiating between "!!". and " ".

Encoding Classification (by Anton Tagunov and Dan Kogai)

This section tries to classify the supported encodings by their applicability for information exchange over the Internet and to choose the most suitable aliases to name them in the context of such communication.

  • To (en|de)code encodings marked by (**), you need Encode::HanExtra, available from CPAN.

Encoding names

  US-ASCII    UTF-8    ISO-8859-*  KOI8-R
  Shift_JIS   EUC-JP   ISO-2022-JP ISO-2022-JP-1
  EUC-KR      Big5     GB2312

are registered with IANA as preferred MIME names and may be used over the Internet.

Shift_JIS has been officialized by JIS X 0208:1997. Microsoft-related naming mess gives details.

GB2312 is the IANA name for EUC-CN. See Microsoft-related naming mess for details.

GB_2312-80 raw encoding is available as gb2312-raw with Encode. See the Encode::CN manpage for details.

  EUC-CN
  KOI8-U        [RFC2319]

have not been registered with IANA (as of March 2002) but seem to be supported by major web browsers. The IANA name for EUC-CN is GB2312.

  KS_C_5601-1987

is heavily misused. See Microsoft-related naming mess for details.

KS_C_5601-1987 raw encoding is available as kcs5601-raw with Encode. See the Encode::KR manpage for details.

  UTF-16 UTF-16BE UTF-16LE

are IANA-registered charsets. See [RFC 2781] for details. Jungshik Shin reports that UTF-16 with a BOM is well accepted by MS IE 5/6 and NS 4/6. Beware however that

  • UTF-16 support in any software you're going to be using/interoperating with has probably been less tested then UTF-8 support

  • UTF-8 coded data seamlessly passes traditional command piping (cat, more, etc.) while UTF-16 coded data is likely to cause confusion (with its zero bytes, for example)

  • it is beyond the power of words to describe the way HTML browsers encode non-ASCII form data. To get a general impression, visit http://ppewww.ph.gla.ac.uk/~flavell/charset/form-i18n.html. While encoding of form data has stabilized for UTF-8 encoded pages (at least IE 5/6, NS 6, and Opera 6 behave consistently), be sure to expect fun (and cross-browser discrepancies) with UTF-16 encoded pages!

The rule of thumb is to use UTF-8 unless you know what you're doing and unless you really benefit from using UTF-16.

  ISO-IR-165    [RFC1345]
  VISCII
  GB 12345
  GB 18030 (**)  (see links bellow)
  EUC-TW   (**)

are totally valid encodings but not registered at IANA. The names under which they are listed here are probably the most widely-known names for these encodings and are recommended names.

  BIG5PLUS (**)

is a proprietary name.

Microsoft-related naming mess

Microsoft products misuse the following names:

KS_C_5601-1987

Microsoft extension to EUC-KR.

Proper names: CP949, UHC, x-windows-949 (as used by Mozilla).

See http://lists.w3.org/Archives/Public/ietf-charsets/2001AprJun/0033.html for details.

Encode aliases KS_C_5601-1987 to cp949 to reflect this common misusage. Raw KS_C_5601-1987 encoding is available as kcs5601-raw.

See the Encode::KR manpage for details.

GB2312

Microsoft extension to EUC-CN.

Proper names: CP936, GBK.

GB2312 has been registered in the EUC-CN meaning at IANA. This has partially repaired the situation: Microsoft's GB2312 has become a superset of the official GB2312.

Encode aliases GB2312 to euc-cn in full agreement with IANA registration. cp936 is supported separately. Raw GB_2312-80 encoding is available as gb2312-raw.

See the Encode::CN manpage for details.

Big5

Microsoft extension to Big5.

Proper name: CP950.

Encode separately supports Big5 and cp950.

Shift_JIS

Microsoft's understanding of Shift_JIS.

JIS has not endorsed the full Microsoft standard however. The official Shift_JIS includes only JIS X 0201 and JIS X 0208 character sets, while Microsoft has always used Shift_JIS to encode a wider character repertoire. See IANA registration for Windows-31J.

As a historical predecessor, Microsoft's variant probably has more rights for the name, though it may be objected that Microsoft shouldn't have used JIS as part of the name in the first place.

Unambiguous name: CP932. IANA name (also used by Mozilla, and provided as an alias by Encode): Windows-31J.

Encode separately supports Shift_JIS and cp932.

Glossary

character repertoire

A collection of unique characters. A character set in the strictest sense. At this stage, characters are not numbered.

coded character set (CCS)

A character set that is mapped in a way computers can use directly. Many character encodings, including EUC, fall in this category.

character encoding scheme (CES)

An algorithm to map a character set to a byte sequence. You don't have to be able to tell which character set a given byte sequence belongs. 7-bit ISO-2022 is a CES but it cannot be a CCS. EUC is an example of being both a CCS and CES.

charset (in MIME context)

has long been used in the meaning of encoding, CES.

While the word combination character set has lost this meaning in MIME context since [RFC 2130], the charset abbreviation has retained it. This is how [RFC 2277] and [RFC 2278] bless charset:

 This document uses the term "charset" to mean a set of rules for
 mapping from a sequence of octets to a sequence of characters, such
 as the combination of a coded character set and a character encoding
 scheme; this is also what is used as an identifier in MIME "charset="
 parameters, and registered in the IANA charset registry ...  (Note
 that this is NOT a term used by other standards bodies, such as ISO).
 [RFC 2277]
EUC

Extended Unix Character. See ISO-2022.

ISO-2022

A CES that was carefully designed to coexist with ASCII. There are a 7 bit version and an 8 bit version.

The 7 bit version switches character set via escape sequence so it cannot form a CCS. Since this is more difficult to handle in programs than the 8 bit version, the 7 bit version is not very popular except for iso-2022-jp, the de facto standard CES for e-mails.

The 8 bit version can form a CCS. EUC and ISO-8859 are two examples thereof. Pre-5.6 perl could use them as string literals.

UCS

Short for Universal Character Set. When you say just UCS, it means Unicode.

UCS-2

ISO/IEC 10646 encoding form: Universal Character Set coded in two octets.

Unicode

A character set that aims to include all character repertoires of the world. Many character sets in various national as well as industrial standards have become, in a way, just subsets of Unicode.

UTF

Short for Unicode Transformation Format. Determines how to map a Unicode character into a byte sequence.

UTF-16

A UTF in 16-bit encoding. Can either be in big endian or little endian. The big endian version is called UTF-16BE (equal to UCS-2 + surrogate support) and the little endian version is called UTF-16LE.

See Also

the Encode manpage, the Encode::Byte manpage, the Encode::CN manpage, the Encode::JP manpage, the Encode::KR manpage, the Encode::TW manpage, the Encode::EBCDIC manpage, the Encode::Symbol manpage the Encode::MIME::Header manpage, the Encode::Guess manpage

References

ECMA

European Computer Manufacturers Association http://www.ecma.ch

ECMA-035 (eq ISO-2022)

http://www.ecma.ch/ecma1/STAND/ECMA-035.HTM

The specification of ISO-2022 is available from the link above.

IANA

Internet Assigned Numbers Authority http://www.iana.org/

Assigned Charset Names by IANA

http://www.iana.org/assignments/character-sets

Most of the canonical names in Encode derive from this list so you can directly apply the string you have extracted from MIME header of mails and web pages.

ISO

International Organization for Standardization http://www.iso.ch/

RFC

Request For Comments -- need I say more? http://www.rfc-editor.org/, http://www.rfc.net/, http://www.faqs.org/rfcs/

UC

Unicode Consortium http://www.unicode.org/

Unicode Glossary

http://www.unicode.org/glossary/

The glossary of this document is based upon this site.

Other Notable Sites

czyborra.com

http://czyborra.com/

Contains a lot of useful information, especially gory details of ISO vs. vendor mappings.

CJK.inf

http://www.oreilly.com/people/authors/lunde/cjk_inf.html

Somewhat obsolete (last update in 1996), but still useful. Also try

ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/pdf/GB18030_Summary.pdf

You will find brief info on EUC-CN, GBK and mostly on GB 18030.

Jungshik Shin's Hangul FAQ

http://jshin.net/faq

And especially its subject 8.

http://jshin.net/faq/qa8.html

A comprehensive overview of the Korean (KS *) standards.

debian.org: "Introduction to i18n"

A brief description for most of the mentioned CJK encodings is contained in http://www.debian.org/doc/manuals/intro-i18n/ch-codes.en.html

Offline sources

CJKV Information Processing by Ken Lunde

CJKV Information Processing 1999 O'Reilly & Associates, ISBN : 1-56592-224-7

The modern successor of CJK.inf.

Features a comprehensive coverage of CJKV character sets and encodings along with many other issues faced by anyone trying to better support CJKV languages/scripts in all the areas of information processing.

To purchase this book, visit http://www.oreilly.com/catalog/cjkvinfo/ or your favourite bookstore.


Encode::Symbol - Symbol Encodings

  • ABSTRACT
  • DESCRIPTION
  • SEE ALSO

NAME

Encode::Symbol - Symbol Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $symbol  = encode("symbol", $utf8); # loads Encode::Symbol implicitly
    $utf8 = decode("", $symbol);        # ditto

ABSTRACT

This module implements symbol and dingbats encodings. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  symbol
  dingbats
  AdobeZDingbat
  AdobeSymbol
  MacDingbats

DESCRIPTION

To find out how to use this module in detail, see the Encode manpage.

SEE ALSO

the Encode manpage


Encode::TW - Taiwan-based Chinese Encodings

  • NOTES
  • BUGS
  • SEE ALSO

NAME

Encode::TW - Taiwan-based Chinese Encodings

SYNOPSIS

    use Encode qw/encode decode/;
    $big5 = encode("big5", $utf8); # loads Encode::TW implicitly
    $utf8 = decode("big5", $big5); # ditto

DESCRIPTION

This module implements tradition Chinese charset encodings as used in Taiwan and Hong Kong. Encodings supported are as follows.

  Canonical   Alias             Description
  --------------------------------------------------------------------
  big5-eten   /\bbig-?5$/i      Big5 encoding (with ETen extensions)
              /\bbig5-?et(en)?$/i
              /\btca-?big5$/i
  big5-hkscs  /\bbig5-?hk(scs)?$/i
              /\bhk(scs)?-?big5$/i
                                Big5 + Cantonese characters in Hong Kong
  MacChineseTrad                Big5 + Apple Vendor Mappings
  cp950                         Code Page 950
                                = Big5 + Microsoft vendor mappings
  --------------------------------------------------------------------

To find out how to use this module in detail, see the Encode manpage.

NOTES

Due to size concerns, EUC-TW (Extended Unix Character), CCCII (Chinese Character Code for Information Interchange), BIG5PLUS (CMEX's Big5+) and BIG5EXT (CMEX's Big5e) are distributed separately on CPAN, under the name the Encode::HanExtra manpage. That module also contains extra China-based encodings.

BUGS

Since the original big5 encoding (1984) is not supported anywhere (glibc and DOS-based systems uses big5 to mean big5-eten; Microsoft uses big5 to mean cp950), a conscious decision was made to alias big5 to big5-eten, which is the de facto superset of the original big5.

The CNS11643 encoding files are not complete. For common CNS11643 manipulation, please use EUC-TW in the Encode::HanExtra manpage, which contains planes 1-7.

The ASCII region (0x00-0x7f) is preserved for all encodings, even though this conflicts with mappings by the Unicode Consortium. See

http://www.debian.or.jp/~kubota/unicode-symbols.html.en

to find out why it is implemented that way.

SEE ALSO

the Encode manpage


Encode::Unicode -- Various Unicode Transformation Formats

  • ABSTRACT
  • Size, Endianness, and BOM
    • by size
    • by endianness
  • Surrogate Pairs
  • Error Checking
  • SEE ALSO

NAME

Encode::Unicode -- Various Unicode Transformation Formats

SYNOPSIS

    use Encode qw/encode decode/;
    $ucs2 = encode("UCS-2BE", $utf8);
    $utf8 = decode("UCS-2BE", $ucs2);

ABSTRACT

This module implements all Character Encoding Schemes of Unicode that are officially documented by Unicode Consortium (except, of course, for UTF-8, which is a native format in perl).

http://www.unicode.org/glossary/ says:

Character Encoding Scheme A character encoding form plus byte serialization. There are Seven character encoding schemes in Unicode: UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32 (UCS-4), UTF-32BE (UCS-4BE) and UTF-32LE (UCS-4LE), and UTF-7.

Since UTF-7 is a 7-bit (re)encoded version of UTF-16BE, It is not part of Unicode's Character Encoding Scheme. It is separately implemented in Encode::Unicode::UTF7. For details see the Encode::Unicode::UTF7 manpage.

Quick Reference
                Decodes from ord(N)           Encodes chr(N) to...
                       octet/char BOM S.P d800-dfff  ord > 0xffff     \x{1abcd} ==
                  ---------------+-----------------+------------------------------
                  UCS-2BE       2   N   N  is bogus                  Not Available
                  UCS-2LE       2   N   N     bogus                  Not Available
                  UTF-16      2/4   Y   Y  is   S.P           S.P            BE/LE
                  UTF-16BE    2/4   N   Y       S.P           S.P    0xd82a,0xdfcd
                  UTF-16LE      2   N   Y       S.P           S.P    0x2ad8,0xcddf
                  UTF-32        4   Y   -  is bogus         As is            BE/LE
                  UTF-32BE      4   N   -     bogus         As is       0x0001abcd
                  UTF-32LE      4   N   -     bogus         As is       0xcdab0100
                  UTF-8       1-4   -   -     bogus   >= 4 octets   \xf0\x9a\af\8d
                  ---------------+-----------------+------------------------------

Size, Endianness, and BOM

You can categorize these CES by 3 criteria: size of each character, endianness, and Byte Order Mark.

by size

UCS-2 is a fixed-length encoding with each character taking 16 bits. It does not support surrogate pairs. When a surrogate pair is encountered during decode(), its place is filled with \x{FFFD} if CHECK is 0, or the routine croaks if CHECK is 1. When a character whose ord value is larger than 0xFFFF is encountered, its place is filled with \x{FFFD} if CHECK is 0, or the routine croaks if CHECK is 1.

UTF-16 is almost the same as UCS-2 but it supports surrogate pairs. When it encounters a high surrogate (0xD800-0xDBFF), it fetches the following low surrogate (0xDC00-0xDFFF) and desurrogates them to form a character. Bogus surrogates result in death. When \x{10000} or above is encountered during encode(), it ensurrogates them and pushes the surrogate pair to the output stream.

UTF-32 (UCS-4) is a fixed-length encoding with each character taking 32 bits. Since it is 32-bit, there is no need for surrogate pairs.

by endianness

The first (and now failed) goal of Unicode was to map all character repertoires into a fixed-length integer so that programmers are happy. Since each character is either a short or long in C, you have to pay attention to the endianness of each platform when you pass data to one another.

Anything marked as BE is Big Endian (or network byte order) and LE is Little Endian (aka VAX byte order). For anything not marked either BE or LE, a character called Byte Order Mark (BOM) indicating the endianness is prepended to the string.

CAVEAT: Though BOM in utf8 (\xEF\xBB\xBF) is valid, it is meaningless and as of this writing Encode suite just leave it as is (\x{FeFF}).

BOM as integer when fetched in network byte order
              16         32 bits/char
  -------------------------
  BE      0xFeFF 0x0000FeFF
  LE      0xFFeF 0xFFFe0000
  -------------------------

This modules handles the BOM as follows.

  • When BE or LE is explicitly stated as the name of encoding, BOM is simply treated as a normal character (ZERO WIDTH NO-BREAK SPACE).

  • When BE or LE is omitted during decode(), it checks if BOM is at the beginning of the string; if one is found, the endianness is set to what the BOM says. If no BOM is found, the routine dies.

  • When BE or LE is omitted during encode(), it returns a BE-encoded string with BOM prepended. So when you want to encode a whole text file, make sure you encode() the whole text at once, not line by line or each line, not file, will have a BOM prepended.

  • UCS-2 is an exception. Unlike others, this is an alias of UCS-2BE. UCS-2 is already registered by IANA and others that way.

Surrogate Pairs

To say the least, surrogate pairs were the biggest mistake of the Unicode Consortium. But according to the late Douglas Adams in The Hitchhiker's Guide to the Galaxy Trilogy, In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move. Their mistake was not of this magnitude so let's forgive them.

(I don't dare make any comparison with Unicode Consortium and the Vogons here ;) Or, comparing Encode to Babel Fish is completely appropriate -- if you can only stick this into your ear :)

Surrogate pairs were born when the Unicode Consortium finally admitted that 16 bits were not big enough to hold all the world's character repertoires. But they already made UCS-2 16-bit. What do we do?

Back then, the range 0xD800-0xDFFF was not allocated. Let's split that range in half and use the first half to represent the upper half of a character and the second half to represent the lower half of a character. That way, you can represent 1024 * 1024 = 1048576 more characters. Now we can store character ranges up to \x{10ffff} even with 16-bit encodings. This pair of half-character is now called a surrogate pair and UTF-16 is the name of the encoding that embraces them.

Here is a formula to ensurrogate a Unicode character \x{10000} and above;

  $hi = ($uni - 0x10000) / 0x400 + 0xD800;
  $lo = ($uni - 0x10000) % 0x400 + 0xDC00;

And to desurrogate;

 $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00);

Note this move has made \x{D800}-\x{DFFF} into a forbidden zone but perl does not prohibit the use of characters within this range. To perl, every one of \x{0000_0000} up to \x{ffff_ffff} (*) is a character.

  (*) or \x{ffff_ffff_ffff_ffff} if your perl is compiled with 64-bit
  integer support!

Error Checking

Unlike most encodings which accept various ways to handle errors, Unicode encodings simply croaks.

  % perl -MEncode -e '$_ = "\xfe\xff\xd8\xd9\xda\xdb\0\n"' \
         -e 'Encode::from_to($_, "utf16","shift_jis", 0); print'
  UTF-16:Malformed LO surrogate d8d9 at /path/to/Encode.pm line 184.
  % perl -MEncode -e '$a = "BOM missing"' \
         -e ' Encode::from_to($a, "utf16", "shift_jis", 0); print'
  UTF-16:Unrecognised BOM 424f at /path/to/Encode.pm line 184.

Unlike other encodings where mappings are not one-to-one against Unicode, UTFs are supposed to map 100% against one another. So Encode is more strict on UTFs.

Consider that "division by zero" of Encode :)

SEE ALSO

the Encode manpage, the Encode::Unicode::UTF7 manpage, http://www.unicode.org/glossary/, http://www.unicode.org/unicode/faq/utf_bom.html,

RFC 2781 http://rfc.net/rfc2781.html,

The whole Unicode standard http://www.unicode.org/unicode/uni2book/u2.html

Ch. 15, pp. 403 of Programming Perl (3rd Edition) by Larry Wall, Tom Christiansen, Jon Orwant; O'Reilly & Associates; ISBN 0-596-00027-8


Encode::Unicode::UTF7 -- UTF-7 encoding

  • ABSTRACT
  • In Practice
  • SEE ALSO

NAME

Encode::Unicode::UTF7 -- UTF-7 encoding

SYNOPSIS

    use Encode qw/encode decode/;
    $utf7 = encode("UTF-7", $utf8);
    $utf8 = decode("UTF-7", $ucs2);

ABSTRACT

This module implements UTF-7 encoding documented in RFC 2152. UTF-7, as its name suggests, is a 7-bit re-encoded version of UTF-16BE. It is designed to be MTA-safe and expected to be a standard way to exchange Unicoded mails via mails. But with the advent of UTF-8 and 8-bit compliant MTAs, UTF-7 is hardly ever used.

UTF-7 was not supported by Encode until version 1.95 because of that. But Unicode::String, a module by Gisle Aas which adds Unicode supports to non-utf8-savvy perl did support UTF-7, the UTF-7 support was added so Encode can supersede Unicode::String 100%.

In Practice

When you want to encode Unicode for mails and web pages, however, do not use UTF-7 unless you are sure your recipients and readers can handle it. Very few MUAs and WWW Browsers support these days (only Mozilla seems to support one). For general cases, use UTF-8 for message body and MIME-Header for header instead.

SEE ALSO

the Encode manpage, the Encode::Unicode manpage, the Unicode::String manpage

RFC 2781 http://www.ietf.org/rfc/rfc2152.txt


English - use nice English names for ugly punctuation variables

  • PERFORMANCE

NAME

English - use nice English (or awk) names for ugly punctuation variables

SYNOPSIS

    use English qw( -no_match_vars ) ;  # Avoids regex performance penalty
    use English;
    ...
    if ($ERRNO =~ /denied/) { ... }

DESCRIPTION

This module provides aliases for the built-in variables whose names no one seems to like to read. Variables with side-effects which get triggered just by accessing them (like $0) will still be affected.

For those variables that have an awk version, both long and short English alternatives are provided. For example, the $/ variable can be referred to either $RS or $INPUT_RECORD_SEPARATOR if you are using the English module.

See the perlvar manpage for a complete list of these.

PERFORMANCE

This module can provoke sizeable inefficiencies for regular expressions, due to unfortunate implementation details. If performance matters in your application and you don't need $PREMATCH, $MATCH, or $POSTMATCH, try doing

   use English qw( -no_match_vars ) ;

. It is especially important to do this in modules to avoid penalizing all applications which use them.


Env - perl module that imports environment variables as scalars or arrays

  • LIMITATIONS
  • AUTHOR

NAME

Env - perl module that imports environment variables as scalars or arrays

SYNOPSIS

    use Env;
    use Env qw(PATH HOME TERM);
    use Env qw($SHELL @LD_LIBRARY_PATH);

DESCRIPTION

Perl maintains environment variables in a special hash named %ENV. For when this access method is inconvenient, the Perl module Env allows environment variables to be treated as scalar or array variables.

The Env::import() function ties environment variables with suitable names to global Perl variables with the same names. By default it ties all existing environment variables (keys %ENV) to scalars. If the import function receives arguments, it takes them to be a list of variables to tie; it's okay if they don't yet exist. The scalar type prefix '$' is inferred for any element of this list not prefixed by '$' or '@'. Arrays are implemented in terms of split and join, using $Config::Config{path_sep} as the delimiter.

After an environment variable is tied, merely use it like a normal variable. You may access its value

    @path = split(/:/, $PATH);
    print join("\n", @LD_LIBRARY_PATH), "\n";

or modify it

    $PATH .= ":.";
    push @LD_LIBRARY_PATH, $dir;

however you'd like. Bear in mind, however, that each access to a tied array variable requires splitting the environment variable's string anew.

The code:

    use Env qw(@PATH);
    push @PATH, '.';

is equivalent to:

    use Env qw(PATH);
    $PATH .= ":.";

except that if $ENV{PATH} started out empty, the second approach leaves it with the (odd) value ":.", but the first approach leaves it with ".".

To remove a tied environment variable from the environment, assign it the undefined value

    undef $PATH;
    undef @LD_LIBRARY_PATH;

LIMITATIONS

On VMS systems, arrays tied to environment variables are read-only. Attempting to change anything will cause a warning.

AUTHOR

Chip Salzenberg <chip@fin.uucp> and Gregor N. Purdy <gregor@focusresearch.com>


Errno - System errno constants

  • CAVEATS
  • AUTHOR
  • COPYRIGHT

NAME

Errno - System errno constants

SYNOPSIS

    use Errno qw(EINTR EIO :POSIX);

DESCRIPTION

Errno defines and conditionally exports all the error constants defined in your system errno.h include file. It has a single export tag, :POSIX, which will export all POSIX defined error numbers.

Errno also makes %! magic such that each element of %! has a non-zero value only if $! is set to that value. For example:

    use Errno;

    unless (open(FH, "/fangorn/spouse")) {
        if ($!{ENOENT}) {
            warn "Get a wife!\n";
        } else {
            warn "This path is barred: $!";
        }
    }

If a specified constant EFOO does not exist on the system, $!{EFOO} returns "". You may use exists $!{EFOO} to check whether the constant is available on the system.

CAVEATS

Importing a particular constant may not be very portable, because the import will fail on platforms that do not have that constant. A more portable way to set $! to a valid value is to use:

    if (exists &Errno::EFOO) {
        $! = &Errno::EFOO;
    }

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1997-8 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Error - Error/exception handling in an OO-ish way

  • PROCEDURAL INTERFACE
  • CLASS INTERFACE
    • CONSTRUCTORS
    • STATIC METHODS
    • OBJECT METHODS
    • OVERLOAD METHODS
  • PRE-DEFINED ERROR CLASSES
  • $Error::ObjectifyCallback
  • KNOWN BUGS
  • AUTHORS
  • MAINTAINER
  • PAST MAINTAINERS

NAME

Error - Error/exception handling in an OO-ish way

SYNOPSIS

    use Error qw(:try);

    throw Error::Simple( "A simple error");

    sub xyz {
        ...
        record Error::Simple("A simple error")
            and return;
    }

    unlink($file) or throw Error::Simple("$file: $!",$!);

    try {
        do_some_stuff();
        die "error!" if $condition;
        throw Error::Simple -text => "Oops!" if $other_condition;
    }
    catch Error::IO with {
        my $E = shift;
        print STDERR "File ", $E->{'-file'}, " had a problem\n";
    }
    except {
        my $E = shift;
        my $general_handler=sub {send_message $E->{-description}};
        return {
            UserException1 => $general_handler,
            UserException2 => $general_handler
        };
    }
    otherwise {
        print STDERR "Well I don't know what to say\n";
    }
    finally {
        close_the_garage_door_already(); # Should be reliable
    }; # Don't forget the trailing ; or you might be surprised

DESCRIPTION

The Error package provides two interfaces. Firstly Error provides a procedural interface to exception handling. Secondly Error is a base class for errors/exceptions that can either be thrown, for subsequent catch, or can simply be recorded.

Errors in the class Error should not be thrown directly, but the user should throw errors from a sub-class of Error.

PROCEDURAL INTERFACE

Error exports subroutines to perform exception handling. These will be exported if the :try tag is used in the use line.

try BLOCK CLAUSES

try is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine.

The BLOCK will be evaluated and, if no error is throw, try will return the result of the block.

CLAUSES are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK.

catch CLASS with BLOCK

This clauses will cause all errors that satisfy $err->isa(CLASS) to be caught and handled by evaluating BLOCK.

BLOCK will be passed two arguments. The first will be the error being thrown. The second is a reference to a scalar variable. If this variable is set by the catch block then, on return from the catch block, try will continue processing as if the catch block was never found.

To propagate the error the catch block may call $err->throw

If the scalar reference by the second argument is not set, and the error is not thrown. Then the current try block will return with the result from the catch block.

except BLOCK

When try is looking for a handler, if an except clause is found BLOCK is evaluated. The return value from this block should be a HASHREF or a list of key-value pairs, where the keys are class names and the values are CODE references for the handler of errors of that type.

otherwise BLOCK

Catch any error by executing the code in BLOCK

When evaluated BLOCK will be passed one argument, which will be the error being processed.

Only one otherwise block may be specified per try block

finally BLOCK

Execute the code in BLOCK either after the code in the try block has successfully completed, or if the try block throws an error then BLOCK will be executed after the handler has completed.

If the handler throws an error then the error will be caught, the finally block will be executed and the error will be re-thrown.

Only one finally block may be specified per try block

CLASS INTERFACE

CONSTRUCTORS

The Error object is implemented as a HASH. This HASH is initialized with the arguments that are passed to it's constructor. The elements that are used by, or are retrievable by the Error class are listed below, other classes may add to these.

        -file
        -line
        -text
        -value
        -object

If -file or -line are not specified in the constructor arguments then these will be initialized with the file name and line number where the constructor was called from.

If the error is associated with an object then the object should be passed as the -object argument. This will allow the Error package to associate the error with the object.

The Error package remembers the last error created, and also the last error associated with a package. This could either be the last error created by a sub in that package, or the last error which passed an object blessed into that package as the -object argument.

throw ( [ ARGS ] )

Create a new Error object and throw an error, which will be caught by a surrounding try block, if there is one. Otherwise it will cause the program to exit.

throw may also be called on an existing error to re-throw it.

with ( [ ARGS ] )

Create a new Error object and returns it. This is defined for syntactic sugar, eg

    die with Some::Error ( ... );
record ( [ ARGS ] )

Create a new Error object and returns it. This is defined for syntactic sugar, eg

    record Some::Error ( ... )
        and return;

STATIC METHODS

prior ( [ PACKAGE ] )

Return the last error created, or the last error associated with PACKAGE

flush ( [ PACKAGE ] )

Flush the last error created, or the last error associated with PACKAGE.It is necessary to clear the error stack before exiting the package or uncaught errors generated using record will be reported.

     $Error->flush;

OBJECT METHODS

stacktrace

If the variable $Error::Debug was non-zero when the error was created, then stacktrace returns a string created by calling Carp::longmess. If the variable was zero the stacktrace returns the text of the error appended with the filename and line number of where the error was created, providing the text does not end with a newline.

object

The object this error was associated with

file

The file where the constructor of this error was called from

line

The line where the constructor of this error was called from

text

The text of the error

OVERLOAD METHODS

stringify

A method that converts the object into a string. This method may simply return the same as the text method, or it may append more information. For example the file name and line number.

By default this method returns the -text argument that was passed to the constructor, or the string "Died" if none was given.

value

A method that will return a value that can be associated with the error. For example if an error was created due to the failure of a system call, then this may return the numeric value of $! at the time.

By default this method returns the -value argument that was passed to the constructor.

PRE-DEFINED ERROR CLASSES

Error::Simple

This class can be used to hold simple error strings and values. It's constructor takes two arguments. The first is a text value, the second is a numeric value. These values are what will be returned by the overload methods.

If the text value ends with at file line 1 as $@ strings do, then this infomation will be used to set the -file and -line arguments of the error object.

This class is used internally if an eval'd block die's with an error that is a plain string. (Unless $Error::ObjectifyCallback is modified)

$Error::ObjectifyCallback

This variable holds a reference to a subroutine that converts errors that are plain strings to objects. It is used by Error.pm to convert textual errors to objects, and can be overrided by the user.

It accepts a single argument which is a hash reference to named parameters. Currently the only named parameter passed is 'text' which is the text of the error, but others may be available in the future.

For example the following code will cause Error.pm to throw objects of the class MyError::Bar by default:

    sub throw_MyError_Bar
    {
        my $args = shift;
        my $err = MyError::Bar->new();
        $err->{'MyBarText'} = $args->{'text'};
        return $err;
    }

    {
        local $Error::ObjectifyCallback = \&throw_MyError_Bar;

        # Error handling here.
    }

KNOWN BUGS

None, but that does not mean there are not any.

AUTHORS

Graham Barr <gbarr@pobox.com>

The code that inspired me to write this was originally written by Peter Seibel <peter@weblogic.com> and adapted by Jesse Glick <jglick@sig.bsh.com>.

MAINTAINER

Shlomi Fish <shlomif@iglu.org.il>

PAST MAINTAINERS

Arun Kumar U <u_arunkumar@yahoo.com>


Error::Simple - the simple error sub-class of Error

  • KNOWN BUGS
  • AUTHORS
  • SEE ALSO

SYNOPSIS

    use base 'Error::Simple';

DESCRIPTION

The only purpose of this module is to allow one to say:

    use base 'Error::Simple';

and the only thing it does is "use" Error.pm. Refer to the documentation of the Error manpage for more information about Error::Simple.

KNOWN BUGS

None.

AUTHORS

Shlomi Fish ( shlomif@iglu.org.il )

SEE ALSO

the Error manpage


Exception::Class - A module that allows you to declare real exception classes in Perl

  • DECLARING EXCEPTION CLASSES
  • Catching Exceptions
    • Uncatchable Exceptions
  • Exception::Class::Base CLASS METHODS
  • Exception::Class::Base OBJECT METHODS
  • OVERLOADING
  • OVERRIDING THE as_string METHOD
  • USAGE RECOMMENDATION
    • Subclassing Exception::Class::Base
  • Exception::Class FUNCTIONS
  • OTHER EXCEPTION MODULES (try/catch syntax)
  • AUTHOR
  • SEE ALSO

NAME

Exception::Class - A module that allows you to declare real exception classes in Perl

SYNOPSIS

  use Exception::Class
      ( 'MyException',
        'AnotherException' =>
        { isa => 'MyException' },

        'YetAnotherException' =>
        { isa => 'AnotherException',
          description => 'These exceptions are related to IPC' },

        'ExceptionWithFields' =>
        { isa => 'YetAnotherException',
          fields => [ 'grandiosity', 'quixotic' ],
          alias => 'throw_fields',
        },
              );

  # try
  eval { MyException->throw( error => 'I feel funny.' ) };

  my $e;
  # catch
  if ( $e = Exception::Class->caught('MyException') )
  {
     warn $e->error, "\n", $e->trace->as_string, "\n";
     warn join ' ',  $e->euid, $e->egid, $e->uid, $e->gid, $e->pid, $e->time;

     exit;
       }
       elsif ( $e = Exception::Class->caught('ExceptionWithFields') )
       {
     $e->quixotic ? do_something_wacky() : do_something_sane();
       }
       else
       {
     $e = Exception::Class->caught();
     ref $e ? $e->rethrow : die $e;
       }

  # use an alias - without parens subroutine name is checked at
  # compile time
  throw_fields error => "No strawberry", grandiosity => "quite a bit";

DESCRIPTION

Exception::Class allows you to declare exception hierarchies in your modules in a "Java-esque" manner.

It features a simple interface allowing programmers to 'declare' exception classes at compile time. It also has a base exception class, Exception::Class::Base, that can be easily extended.

It is designed to make structured exception handling simpler and better by encouraging people to use hierarchies of exceptions in their applications, as opposed to a single catch-all exception class.

This module does not implement any try/catch syntax. Please see the "OTHER EXCEPTION MODULES (try/catch syntax)" section for more information on how to get this syntax.

DECLARING EXCEPTION CLASSES

Importing Exception::Class allows you to automagically create Exception::Class::Base subclasses. You can also create subclasses via the traditional means of defining your own subclass with @ISA. These two methods may be easily combined, so that you could subclass an exception class defined via the automagic import, if you desired this.

The syntax for the magic declarations is as follows:

'MANDATORY CLASS NAME' => \%optional_hashref

The hashref may contain the following options:

  • isa

    This is the class's parent class. If this isn't provided then the class name in $Exception::Class::BASE_EXC_CLASS is assumed to be the parent (see below).

    This parameter lets you create arbitrarily deep class hierarchies. This can be any other Exception::Class::Base subclass in your declaration or a subclass loaded from a module.

    To change the default exception class you will need to change the value of $Exception::Class::BASE_EXC_CLASS before calling import(). To do this simply do something like this:

    BEGIN { $Exception::Class::BASE_EXC_CLASS = 'SomeExceptionClass'; }

    If anyone can come up with a more elegant way to do this please let me know.

    CAVEAT: If you want to automagically subclass an Exception::Class::Base subclass loaded from a file, then you must compile the class (via use or require or some other magic) before you import Exception::Class or you'll get a compile time error.

  • fields

    This allows you to define additional attributes for your exception class. Any field you define can be passed to the throw() or new() methods as additional parameters for the constructor. In addition, your exception object will have an accessor method for the fields you define.

    This parameter can be either a scalar (for a single field) or an array reference if you need to define multiple fields.

    Fields will be inherited by subclasses.

  • alias

    Specifying an alias causes this class to create a subroutine of the specified name in the caller's namespace. Calling this subroutine is equivalent to calling <class>->throw(@_) for the given exception class.

    Besides convenience, using aliases also allows for additional compile time checking. If the alias is called without parentheses, as in throw_fields "an error occurred", then Perl checks for the existence of the throw_fields() subroutine at compile time. If instead you do ExceptionWithFields->throw(...), then Perl checks the class name at runtime, meaning that typos may sneak through.

  • description

    Each exception class has a description method that returns a fixed string. This should describe the exception class (as opposed to any particular exception object). This may be useful for debugging if you start catching exceptions you weren't expecting (particularly if someone forgot to document them) and you don't understand the error messages.

The Exception::Class magic attempts to detect circular class hierarchies and will die if it finds one. It also detects missing links in a chain, for example if you declare Bar to be a subclass of Foo and never declare Foo.

Catching Exceptions

Exception::Class provides some syntactic sugar for catching exceptions in a safe manner:

 eval { ... }

 if ( my $e = Exception::Class->caught('My::Error') )
 {
     cleanup();
     do_something_with_exception($e);
 }

The caught() method takes a class name and returns an exception object if the last thrown exception is of the given class, or a subclass of that class. If it is not given any arguments, it simply returns $@.

You should always make a copy of the exception object, rather than using $@ directly. This is necessary because if your cleanup() function uses eval, or calls something which uses it, then $@ is overwritten. Copying the exception preserves it for the call to do_something_with_exception().

Exception objects also provide a caught method so you can write:

 if ( my $e = My::Error->caught() )
 {
     cleanup();
     do_something_with_exception($e);
 }

Uncatchable Exceptions

Internally, the caught() method will call isa() on the exception object. You could make an exception "uncatchable" by overriding isa() in that class like this:

 package Exception::Uncatchable;

 sub isa { shift->rethrow }

Of course, this only works if you always call Exception::Class->caught() after an eval.

Exception::Class::Base CLASS METHODS

  • Trace($boolean)

    Each Exception::Class::Base subclass can be set individually to include a a stracktrace when the as_string method is called. The default is to not include a stacktrace. Calling this method with a value changes this behavior. It always returns the current value (after any change is applied).

    This value is inherited by any subclasses. However, if this value is set for a subclass, it will thereafter be independent of the value in Exception::Class::Base.

    This is a class method, not an object method.

  • NoRefs($boolean)

    When a Devel::StackTrace object is created, it walks through the stack and stores the arguments which were passed to each subroutine on the stack. If any of these arguments are references, then that means that the Devel::StackTrace ends up increasing the refcount of these references, delaying their destruction.

    Since Exception::Class::Base uses Devel::StackTrace internally, this method provides a way to tell Devel::StackTrace not to store these references. Instead, Devel::StackTrace replaces references with their stringified representation.

    This method defaults to true. As with Trace(), it is inherited by subclasses but setting it in a subclass makes it independent thereafter.

  • RespectOverload($boolean)

    When a Devel::StackTrace object stringifies, by default it ignores stringification overloading on any objects being dealt with.

    Since Exception::Class::Base uses Devel::StackTrace internally, this method provides a way to tell Devel::StackTrace to respect overloading.

    This method defaults to false. As with Trace(), it is inherited by subclasses but setting it in a subclass makes it independent thereafter.

  • Fields

    This method returns the extra fields defined for the given class, as an array.

  • throw( $message )
  • throw( message => $message )
  • throw( error => $error )

    This method creates a new object with the given error message. If no error message is given, $! is used. It then die's with this object as its argument.

    This method also takes a show_trace parameter which indicates whether or not the particular exception object being created should show a stacktrace when its as_string() method is called. This overrides the value of Trace() for this class if it is given.

    The frames included in the trace can be controlled by the ignore_class and ignore_package parameters. These are passed directly to Devel::Stacktrace's constructor. See Devel::Stacktrace for more details.

    If only a single value is given to the constructor it is assumed to be the message parameter.

    Additional keys corresponding to the fields defined for the particular exception subclass will also be accepted.

  • new

    This method takes the same parameters as throw(), but instead of dying simply returns a new exception object.

    This method is always called when constructing a new exception object via the throw() method.

  • description

    Returns the description for the given Exception::Class::Base subclass. The Exception::Class::Base class's description is "Generic exception" (this may change in the future). This is also an object method.

Exception::Class::Base OBJECT METHODS

  • rethrow

    Simply dies with the object as its sole argument. It's just syntactic sugar. This does not change any of the object's attribute values. However, it will cause caller() to report the die as coming from within the Exception::Class::Base class rather than where rethrow was called.

    Of course, you always have access to the original stacktrace for the exception object.

  • message
  • error

    Returns the error/message associated with the exception.

  • pid

    Returns the pid at the time the exception was thrown.

  • uid

    Returns the real user id at the time the exception was thrown.

  • gid

    Returns the real group id at the time the exception was thrown.

  • euid

    Returns the effective user id at the time the exception was thrown.

  • egid

    Returns the effective group id at the time the exception was thrown.

  • time

    Returns the time in seconds since the epoch at the time the exception was thrown.

  • package

    Returns the package from which the exception was thrown.

  • file

    Returns the file within which the exception was thrown.

  • line

    Returns the line where the exception was thrown.

  • trace

    Returns the trace object associated with the object.

  • show_trace($boolean)

    This method can be used to set whether or not a strack trace is included when the as_string method is called or the object is stringified.

  • as_string

    Returns a string form of the error message (something like what you'd expect from die). If the class or object is set to show traces then then the full trace is also included. The result looks like Carp::confess().

  • full_message

    Called by the as_string() method to get the message. By default, this is the same as calling the message() method, but may be overridden by a subclass. See below for details.

OVERLOADING

The Exception::Class::Base object is overloaded so that stringification produces a normal error message. It just calls the as_string method described above. This means that you can just print $@ after an eval and not worry about whether or not its an actual object. It also means an application or module could do this:

 $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); };

and this would probably not break anything (unless someone was expecting a different type of exception object from die()).

OVERRIDING THE as_string METHOD

By default, the as_string() method simply returns the value message or error param plus a stack trace, if the class's Trace() method returns a true value or show_trace was set when creating the exception.

However, once you add new fields to a subclass, you may want to include those fields in the stringified error.

Inside the as_string() method, the message (non-stack trace) portion of the error is generated by calling the full_message() method. This can be easily overridden. For example:

  sub full_message
  {
      my $self = shift;

      my $msg = $self->message;

      $msg .= " and foo was " . $self->foo;

      return $msg;
        }

USAGE RECOMMENDATION

If you're creating a complex system that throws lots of different types of exceptions, consider putting all the exception declarations in one place. For an app called Foo you might make a Foo::Exceptions module and use that in all your code. This module could just contain the code to make Exception::Class do its automagic class creation. Doing this allows you to more easily see what exceptions you have, and makes it easier to keep track of them.

This might look something like this:

  package Foo::Bar::Exceptions;

  use Exception::Class ( Foo::Bar::Exception::Senses =>
                        { description => 'sense-related exception' },

                         Foo::Bar::Exception::Smell =>
                         { isa => 'Foo::Bar::Exception::Senses',
                           fields => 'odor',
                           description => 'stinky!' },

                         Foo::Bar::Exception::Taste =>
                         { isa => 'Foo::Bar::Exception::Senses',
                           fields => [ 'taste', 'bitterness' ],
                           description => 'like, gag me with a spoon!' },

                         ... );

You may want to create a real module to subclass Exception::Class::Base as well, particularly if you want your exceptions to have more methods.

Subclassing Exception::Class::Base

As part of your usage of Exception::Class, you may want to create your own base exception class which subclasses Exception::Class::Base. You should feel free to subclass any of the methods documented above. For example, you may want to subclass new() to add additional information to your exception objects.

Exception::Class FUNCTIONS

The Exception::Class method offers one function, Classes(), which is not exported. This method returns a list of the classes that have been created by calling the Exception::Class import() method. Note that this is all the subclasses that have been created, so it may include subclasses created by things like CPAN modules, etc. Also note that if you simply define a subclass via the normal Perl method of setting @ISA or use base, then your subclass will not be included.

OTHER EXCEPTION MODULES (try/catch syntax)

If you are interested in adding try/catch/finally syntactic sugar to your code then I recommend you check out U. Arun Kumar's Error.pm module, which implements this syntax. It also includes its own base exception class, Error::Simple.

If you would prefer to use the Exception::Class::Base class included with this module, you'll have to add this to your code somewhere:

  push @Exception::Class::Base::ISA, 'Error'
      unless Exception::Class::Base->isa('Error');

It's a hack but apparently it works.

AUTHOR

Dave Rolsky, <autarch@urth.org>

SEE ALSO

Devel::StackTrace - used by this module to create stack traces

Error.pm - implements try/catch in Perl. Also provides an exception base class.

Test::Exception - a module that helps you test exception based code.

Numerous other modules/frameworks seem to have their own exception classes (SPOPS and Template Toolkit, to name two) but none of these seem to be designed for use outside of these packages.


Exporter - Implements default import method for modules

    • How to Export
    • Selecting What To Export
    • How to Import
  • Advanced features
    • Specialised Import Lists
    • Exporting without using Exporter's import method
    • Exporting without inheriting from Exporter
    • Module Version Checking
    • Managing Unknown Symbols
    • Tag Handling Utility Functions
    • Generating combined tags
    • AUTOLOADed Constants

NAME

Exporter - Implements default import method for modules

SYNOPSIS

In module YourModule.pm:

  package YourModule;
  require Exporter;
  @ISA = qw(Exporter);
  @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request

or

  package YourModule;
  use Exporter 'import'; # gives you Exporter's import() method directly
  @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request

In other files which wish to use YourModule:

  use ModuleName qw(frobnicate);      # import listed symbols
  frobnicate ($left, $right)          # calls YourModule::frobnicate

DESCRIPTION

The Exporter module implements an import method which allows a module to export functions and variables to its users' namespaces. Many modules use Exporter rather than implementing their own import method because Exporter provides a highly flexible interface, with an implementation optimised for the common case.

Perl automatically calls the import method when processing a use statement for a module. Modules and use are documented in the perlfunc manpage and the perlmod manpage. Understanding the concept of modules and how the use statement operates is important to understanding the Exporter.

How to Export

The arrays @EXPORT and @EXPORT_OK in a module hold lists of symbols that are going to be exported into the users name space by default, or which they can request to be exported, respectively. The symbols can represent functions, scalars, arrays, hashes, or typeglobs. The symbols must be given by full name with the exception that the ampersand in front of a function is optional, e.g.

    @EXPORT    = qw(afunc $scalar @array);   # afunc is a function
    @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc

If you are only exporting function names it is recommended to omit the ampersand, as the implementation is faster this way.

Selecting What To Export

Do not export method names!

Do not export anything else by default without a good reason!

Exports pollute the namespace of the module user. If you must export try to use @EXPORT_OK in preference to @EXPORT and avoid short or common symbol names to reduce the risk of name clashes.

Generally anything not exported is still accessible from outside the module using the ModuleName::item_name (or $blessed_ref->method) syntax. By convention you can use a leading underscore on names to informally indicate that they are 'internal' and not for public use.

(It is actually possible to get private functions by saying:

  my $subref = sub { ... };
  $subref->(@args);            # Call it as a function
  $obj->$subref(@args);        # Use it as a method

However if you use them for methods it is up to you to figure out how to make inheritance work.)

As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then @EXPORT_OK anything but use @EXPORT with caution. For function and method names use barewords in preference to names prefixed with ampersands for the export lists.

Other module design guidelines can be found in the perlmod manpage.

How to Import

In other files which wish to use your module there are three basic ways for them to load your module and import its symbols:

use ModuleName;

This imports all the symbols from ModuleName's @EXPORT into the namespace of the use statement.

use ModuleName ();

This causes perl to load your module but does not import any symbols.

use ModuleName qw(...);

This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your @EXPORT or @EXPORT_OK, else an error occurs. The advanced export features of Exporter are accessed like this, but with list entries that are syntactically distinct from symbol names.

Unless you want to use its advanced features, this is probably all you need to know to use Exporter.

Advanced features

Specialised Import Lists

If any of the entries in an import list begins with !, : or / then the list is treated as a series of specifications which either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form:

    [!]name         This name only
    [!]:DEFAULT     All names in @EXPORT
    [!]:tag         All names in $EXPORT_TAGS{tag} anonymous list
    [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match

A leading ! indicates that matching names should be deleted from the list of names to import. If the first specification is a deletion it is treated as though preceded by :DEFAULT. If you just want to import extra names in addition to the default set you will still need to include :DEFAULT explicitly.

e.g., Module.pm defines:

    @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)]);

    Note that you cannot use tags in @EXPORT or @EXPORT_OK.
    Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.

An application using Module can say something like:

    use Module qw(:DEFAULT :T2 !B3 A3);

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 ^, e.g., /^EXIT/ rather than /EXIT/.

You can say BEGIN { $Exporter::Verbose=1 } to see how the specifications are being processed and what is actually being imported into modules.

Exporting without using Exporter's import method

Exporter has a special method, 'export_to_level' which is used in situations where you can't directly call Exporter's import method. The export_to_level method looks like:

    MyPackage->export_to_level($where_to_export, $package, @what_to_export);

where $where_to_export is an integer telling how far up the calling stack to export your symbols, and @what_to_export is an array telling what symbols *to* export (usually this is @_). The $package argument is currently unused.

For example, suppose that you have a module, A, which already has an import function:

    package A;

    @ISA = qw(Exporter);
    @EXPORT_OK = qw ($b);

    sub import
    {
        $A::b = 1;     # not a very useful import method
    }

and you want to Export symbol $A::b back to the module that called package A. Since Exporter relies on the import method to work, via inheritance, as it stands Exporter::import() will never get called. Instead, say the following:

    package A;
    @ISA = qw(Exporter);
    @EXPORT_OK = qw ($b);

    sub import
    {
        $A::b = 1;
        A->export_to_level(1, @_);
    }

This will export the symbols one level 'above' the current package - ie: to the program or module that used package A.

Note: Be careful not to modify @_ at all before you call export_to_level - or people using your package will get very unexplained results!

Exporting without inheriting from Exporter

By including Exporter in your @ISA you inherit an Exporter's import() method but you also inherit several other helper methods which you probably don't want. To avoid this you can do

  package YourModule;
  use Exporter qw( import );

which will export Exporter's own import() method into YourModule. Everything will work as before but you won't need to include Exporter in @YourModule::ISA.

Module Version Checking

The 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 supplies a default require_version method which checks the value of $VERSION in the exporting module.

Since the default require_version method treats the $VERSION number as a simple numeric value it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that you use numbers with at least two decimal places, e.g., 1.09.

Managing Unknown Symbols

In some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions which have 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 export_fail method with a list of the failed symbols:

  @failed_symbols = $module_name->export_fail(@failed_symbols);

If the export_fail method returns an empty list then no error is recorded and all the 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 which simply returns the list unchanged.

Uses for the export_fail method include giving better error messages for some symbols and performing lazy architectural checks (put more symbols into @EXPORT_FAIL by default and then take them out if someone actually tries to use them and an expensive check shows that they are usable on that platform).

Tag Handling Utility Functions

Since the symbols listed within %EXPORT_TAGS must also appear in either @EXPORT or @EXPORT_OK, two utility functions are provided which allow you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:

  %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);

  Exporter::export_tags('foo');     # add aa, bb and cc to @EXPORT
  Exporter::export_ok_tags('bar');  # add aa, cc and dd to @EXPORT_OK

Any names which are not tags are added to @EXPORT or @EXPORT_OK unchanged but will trigger a warning (with -w) to avoid misspelt tags names being silently added to @EXPORT or @EXPORT_OK. Future versions may make this a fatal error.

Generating combined tags

If several symbol categories exist in %EXPORT_TAGS, it's usually useful to create the utility ":all" to simplify "use" statements.

The simplest way to do this is:

  %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);

  # add all the other ":class" tags to the ":all" class,
  # deleting duplicates
  {
    my %seen;

    push @{$EXPORT_TAGS{all}},
      grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
      }

CGI.pm creates an ":all" tag which contains some (but not really all) of its categories. That could be done with one small change:

  # add some of the other ":class" tags to the ":all" class,
  # deleting duplicates
  {
    my %seen;

    push @{$EXPORT_TAGS{all}},
      grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
        foreach qw/html2 html3 netscape form cgi internal/;
      }

Note that the tag names in %EXPORT_TAGS don't have the leading ':'.

AUTOLOADed Constants

Many modules make use of AUTOLOADing for constant subroutines to avoid having to compile and waste memory on rarely used values (see the perlsub manpage for details on constant subroutines). Calls to such constant subroutines are not optimized away at compile time because they can't be checked at compile time for constancy.

Even if a prototype is available at compile time, the body of the subroutine is not (it hasn't been AUTOLOADed yet). perl needs to examine both the () prototype and the body of a subroutine at compile time to detect that it can safely replace calls to that subroutine with the constant value.

A workaround for this is to call the constants once in a BEGIN block:

   package My ;

   use Socket ;

   foo( SO_LINGER );     ## SO_LINGER NOT optimized away; called at runtime
   BEGIN { SO_LINGER }
   foo( SO_LINGER );     ## SO_LINGER optimized away at compile time.

This forces the AUTOLOAD for SO_LINGER to take place before SO_LINGER is encountered later in My package.

If you are writing a package that AUTOLOADs, consider forcing an AUTOLOAD for any constants explicitly imported by other packages or which are usually used when your package is used.


Exporter::Heavy - Exporter guts

NAME

Exporter::Heavy - Exporter guts

SYNOPSIS

(internal use only)

DESCRIPTION

No user-serviceable parts inside.


ExtUtils::Command - utilities to replace common UNIX commands in Makefiles etc.

  • SEE ALSO
  • AUTHOR

NAME

ExtUtils::Command - utilities to replace common UNIX commands in Makefiles etc.

SYNOPSIS

  perl -MExtUtils::Command  -e cat files... > destination
  perl -MExtUtils::Command  -e mv source... destination
  perl -MExtUtils::Command  -e cp source... destination
  perl -MExtUtils::Command  -e touch files...
  perl -MExtUtils::Command  -e rm_f files...
  perl -MExtUtils::Command  -e rm_rf directories...
  perl -MExtUtils::Command  -e mkpath directories...
  perl -MExtUtils::Command  -e eqtime source destination
  perl -MExtUtils::Command  -e test_f file
  perl -MExtUtils::Command  -e chmod mode files...
  ...

DESCRIPTION

The module is used to replace common UNIX commands. In all cases the functions work from @ARGV rather than taking arguments. This makes them easier to deal with in Makefiles.

  perl -MExtUtils::Command -e some_command some files to work on

NOT

  perl -MExtUtils::Command -e 'some_command qw(some files to work on)'

For that use the Shell::Command manpage.

Filenames with * and ? will be glob expanded.

cat
    cat file ...

Concatenates all files mentioned on command line to STDOUT.

eqtime
    eqtime source destination

Sets modified time of destination to that of source.

rm_rf
    rm_rf files or directories ...

Removes files and directories - recursively (even if readonly)

rm_f
    rm_f file ...

Removes files (even if readonly)

touch
    touch file ...

Makes files exist, with current timestamp

mv
    mv source_file destination_file
    mv source_file source_file destination_dir

Moves source to destination. Multiple sources are allowed if destination is an existing directory.

Returns true if all moves succeeded, false otherwise.

cp
    cp source_file destination_file
    cp source_file source_file destination_dir

Copies sources to the destination. Multiple sources are allowed if destination is an existing directory.

Returns true if all copies succeeded, false otherwise.

chmod
    chmod mode files ...

Sets UNIX like permissions 'mode' on all the files. e.g. 0666

mkpath
    mkpath directory ...

Creates directories, including any parent directories.

test_f
    test_f file

Tests if a file exists

dos2unix
    dos2unix files or dirs ...

Converts DOS and OS/2 linefeeds to Unix style recursively.

SEE ALSO

Shell::Command which is these same functions but take arguments normally.

AUTHOR

Nick Ing-Simmons ni-s@cpan.org

Currently maintained by Michael G Schwern schwern@pobox.com.


ExtUtils::Command::MM - Commands for the MM's to use in Makefiles

NAME

ExtUtils::Command::MM - Commands for the MM's to use in Makefiles

SYNOPSIS

  perl "-MExtUtils::Command::MM" -e "function" "--" arguments...

DESCRIPTION

FOR INTERNAL USE ONLY! The interface is not stable.

ExtUtils::Command::MM encapsulates code which would otherwise have to be done with large "one" liners.

Any $(FOO) used in the examples are make variables, not Perl.

test_harness
  test_harness($verbose, @test_libs);

Runs the tests on @ARGV via Test::Harness passing through the $verbose flag. Any @test_libs will be unshifted onto the test's @INC.

@test_libs are run in alphabetical order.

pod2man
  pod2man( '--option=value',
           $podfile1 => $manpage1,
           $podfile2 => $manpage2,
           ...
         );

  # or args on @ARGV

pod2man() is a function performing most of the duties of the pod2man program. Its arguments are exactly the same as pod2man as of 5.8.0 with the addition of:

    --perm_rw   octal permission to set the resulting manpage to

And the removal of:

    --verbose/-v
    --help/-h

If no arguments are given to pod2man it will read from @ARGV.

warn_if_old_packlist
  perl "-MExtUtils::Command::MM" -e warn_if_old_packlist <somefile>

Displays a warning that an old packlist file was found. Reads the filename from @ARGV.

perllocal_install
    perl "-MExtUtils::Command::MM" -e perllocal_install
        <type> <module name> <key> <value> ...
    # VMS only, key|value pairs come on STDIN
    perl "-MExtUtils::Command::MM" -e perllocal_install
        <type> <module name> < <key>|<value> ...

Prints a fragment of POD suitable for appending to perllocal.pod. Arguments are read from @ARGV.

'type' is the type of what you're installing. Usually 'Module'.

'module name' is simply the name of your module. (Foo::Bar)

Key/value pairs are extra information about the module. Fields include:

    installed into      which directory your module was out into
    LINKTYPE            dynamic or static linking
    VERSION             module version number
    EXE_FILES           any executables installed in a space seperated
                        list
uninstall
    perl "-MExtUtils::Command::MM" -e uninstall <packlist>

A wrapper around ExtUtils::Install::uninstall(). Warns that uninstallation is deprecated and doesn't actually perform the uninstallation.


ExtUtils::Constant - generate XS code to import C header constants

  • USAGE
  • FUNCTIONS
  • AUTHOR

NAME

ExtUtils::Constant - generate XS code to import C header constants

SYNOPSIS

    use ExtUtils::Constant qw (WriteConstants);
    WriteConstants(
        NAME => 'Foo',
        NAMES => [qw(FOO BAR BAZ)],
    );
    # Generates wrapper code to make the values of the constants FOO BAR BAZ
    #  available to perl

DESCRIPTION

ExtUtils::Constant facilitates generating C and XS wrapper code to allow perl modules to AUTOLOAD constants defined in C library header files. It is principally used by the h2xs utility, on which this code is based. It doesn't contain the routines to scan header files to extract these constants.

USAGE

Generally one only needs to call the WriteConstants function, and then

    #include "const-c.inc"

in the C section of Foo.xs

    INCLUDE: const-xs.inc

in the XS section of Foo.xs.

For greater flexibility use constant_types(), C_constant and XS_constant, with which WriteConstants is implemented.

Currently this module understands the following types. h2xs may only know a subset. The sizes of the numeric types are chosen by the Configure script at compile time.

IV

signed integer, at least 32 bits.

UV

unsigned integer, the same size as IV

NV

floating point type, probably double, possibly long double

PV

NUL terminated string, length will be determined with strlen

PVN

A fixed length thing, given as a [pointer, length] pair. If you know the length of a string at compile time you may use this instead of PV

SV

A mortal SV.

YES

Truth. (PL_sv_yes) The value is not needed (and ignored).

NO

Defined Falsehood. (PL_sv_no) The value is not needed (and ignored).

UNDEF

undef. The value of the macro is not needed.

FUNCTIONS

constant_types

A function returning a single scalar with #define definitions for the constants used internally between the generated C and XS functions.

XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME

A function to generate the XS code to implement the perl subroutine PACKAGE::constant used by PACKAGE::AUTOLOAD to load constants. This XS code is a wrapper around a C subroutine usually generated by C_constant, and usually named constant.

TYPES should be given either as a comma separated list of types that the C subroutine constant will generate or as a reference to a hash. It should be the same list of types as C_constant was given. [Otherwise XS_constant and C_constant may have different ideas about the number of parameters passed to the C function constant]

You can call the perl visible subroutine something other than constant if you give the parameter SUBNAME. The C subroutine it calls defaults to the name of the perl visible subroutine, unless you give the parameter C_SUBNAME.

autoload PACKAGE, VERSION, AUTOLOADER

A function to generate the AUTOLOAD subroutine for the module PACKAGE VERSION is the perl version the code should be backwards compatible with. It defaults to the version of perl running the subroutine. If AUTOLOADER is true, the AUTOLOAD subroutine falls back on AutoLoader::AUTOLOAD for all names that the constant() routine doesn't recognise.

WriteMakefileSnippet

WriteMakefileSnippet ATTRIBUTE => VALUE [, ...]

A function to generate perl code for Makefile.PL that will regenerate the constant subroutines. Parameters are named as passed to WriteConstants, with the addition of INDENT to specify the number of leading spaces (default 2).

Currently only INDENT, NAME, DEFAULT_TYPE, NAMES, C_FILE and XS_FILE are recognised.

WriteConstants ATTRIBUTE => VALUE [, ...]

Writes a file of C code and a file of XS code which you should #include and INCLUDE in the C and XS sections respectively of your module's XS code. You probably want to do this in your Makefile.PL, so that you can easily edit the list of constants without touching the rest of your module. The attributes supported are

NAME

Name of the module. This must be specified

DEFAULT_TYPE

The default type for the constants. If not specified IV is assumed.

BREAKOUT_AT

The names of the constants are grouped by length. Generate child subroutines for each group with this number or more names in.

NAMES

An array of constants' names, either scalars containing names, or hashrefs as detailed in C_constant.

C_FILE

The name of the file to write containing the C code. The default is const-c.inc. The - in the name ensures that the file can't be mistaken for anything related to a legitimate perl package name, and not naming the file .c avoids having to override Makefile.PL's .xs to .c rules.

XS_FILE

The name of the file to write containing the XS code. The default is const-xs.inc.

SUBNAME

The perl visible name of the XS subroutine generated which will return the constants. The default is constant.

C_SUBNAME

The name of the C subroutine generated which will return the constants. The default is SUBNAME. Child subroutines have _ and the name length appended, so constants with 10 character names would be in constant_10 with the default XS_SUBNAME.

AUTHOR

Nicholas Clark <nick@ccl4.org> based on the code in h2xs by Larry Wall and others


ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

  • USAGE
  • BUGS
  • AUTHOR

NAME

ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

SYNOPSIS

    require ExtUtils::Constant::Base;
    @ISA = 'ExtUtils::Constant::Base';

DESCRIPTION

ExtUtils::Constant::Base provides a base implementation of methods to generate C code to give fast constant value lookup by named string. Currently it's mostly used ExtUtils::Constant::XS, which generates the lookup code for the constant() subroutine found in many XS modules.

USAGE

ExtUtils::Constant::Base exports no subroutines. The following methods are available

header

A method returning a scalar containing definitions needed, typically for a C header file.

memEQ_clause args_hashref

A method to return a suitable C if statement to check whether name is equal to the C variable name. If checked_at is defined, then it is used to avoid memEQ for short names, or to generate a comment to highlight the position of the character in the switch statement.

If i<checked_at> is a reference to a scalar, then instead it gives the characters pre-checked at the beginning, (and the number of chars by which the C variable name has been advanced. These need to be chopped from the front of name).

dump_names arg_hashref, ITEM...

An internal function to generate the embedded perl code that will regenerate the constant subroutines. default_type, types and ITEMs are the same as for C_constant. indent is treated as number of spaces to indent by. If declare_types is true a $types is always declared in the perl code generated, if defined and false never declared, and if undefined $types is only declared if the values in types as passed in cannot be inferred from default_types and the ITEMs.

assign arg_hashref, VALUE...

A method to return a suitable assignment clause. If type is aggregate (eg PVN expects both pointer and length) then there should be multiple VALUEs for the components. pre and post if defined give snippets of C code to proceed and follow the assignment. pre will be at the start of a block, so variables may be defined in it.

return_clause arg_hashref, ITEM

A method to return a suitable #ifdef clause. ITEM is a hashref (as passed to C_constant and match_clause. indent is the number of spaces to indent, defaulting to 6.

switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM...

An internal method to generate a suitable switch clause, called by C_constant ITEMs are in the hash ref format as given in the description of C_constant, and must all have the names of the same length, given by NAMELEN. ITEMHASH is a reference to a hash, keyed by name, values being the hashrefs in the ITEM list. (No parameters are modified, and there can be keys in the ITEMHASH that are not in the list of ITEMs without causing problems - the hash is passed in to save generating it afresh for each call).

params WHAT

An "internal" method, subject to change, currently called to allow an overriding class to cache information that will then be passed into all the *param* calls. (Yes, having to read the source to make sense of this is considered a known bug). WHAT is be a hashref of types the constant function will return. In ExtUtils::Constant::XS this method is used to returns a hashref keyed IV NV PV SV to show which combination of pointers will be needed in the C argument list generated by C_constant_other_params_definition and C_constant_other_params

dogfood arg_hashref, ITEM...

An internal function to generate the embedded perl code that will regenerate the constant subroutines. Parameters are the same as for C_constant.

Currently the base class does nothing and returns an empty string.

C_constant arg_hashref, ITEM...

A function that returns a list of C subroutine definitions that return the value and type of constants when passed the name by the XS wrapper. ITEM... gives a list of constant names. Each can either be a string, which is taken as a C macro name, or a reference to a hash with the following keys

name

The name of the constant, as seen by the perl code.

type

The type of the constant (IV, NV etc)

value

A C expression for the value of the constant, or a list of C expressions if the type is aggregate. This defaults to the name if not given.

macro

The C pre-processor macro to use in the #ifdef. This defaults to the name, and is mainly used if value is an enum. If a reference an array is passed then the first element is used in place of the #ifdef line, and the second element in place of the #endif. This allows pre-processor constructions such as

    #if defined (foo)
    #if !defined (bar)
    ...
    #endif
    #endif

to be used to determine if a constant is to be defined.

A "macro" 1 signals that the constant is always defined, so the #if/#endif test is omitted.

default

Default value to use (instead of croaking with "your vendor has not defined...") to return if the macro isn't defined. Specify a reference to an array with type followed by value(s).

pre

C code to use before the assignment of the value of the constant. This allows you to use temporary variables to extract a value from part of a struct and return this as value. This C code is places at the start of a block, so you can declare variables in it.

post

C code to place between the assignment of value (to a temporary) and the return from the function. This allows you to clear up anything in pre. Rarely needed.

def_pre
def_post

Equivalents of pre and post for the default value.

utf8

Generated internally. Is zero or undefined if name is 7 bit ASCII, "no" if the name is 8 bit (and so should only match if SvUTF8() is false), "yes" if the name is utf8 encoded.

The internals automatically clone any name with characters 128-255 but none 256+ (ie one that could be either in bytes or utf8) into a second entry which is utf8 encoded.

weight

Optional sorting weight for names, to determine the order of linear testing when multiple names fall in the same case of a switch clause. Higher comes earlier, undefined defaults to zero.

In the argument hashref, package is the name of the package, and is only used in comments inside the generated C code. subname defaults to constant if undefined.

default_type is the type returned by ITEMs that don't specify their type. It defaults to the value of default_type(). types should be given either as a comma separated list of types that the C subroutine subname will generate or as a reference to a hash. default_type will be added to the list if not present, as will any types given in the list of ITEMs. The resultant list should be the same list of types that XS_constant is given. [Otherwise XS_constant and C_constant may differ in the number of parameters to the constant function. indent is currently unused and ignored. In future it may be used to pass in information used to change the C indentation style used.] The best way to maintain consistency is to pass in a hash reference and let this function update it.

breakout governs when child functions of subname are generated. If there are breakout or more ITEMs with the same length of name, then the code to switch between them is placed into a function named subname_len, for example constant_5 for names 5 characters long. The default breakout is 3. A single ITEM is always inlined.

BUGS

Not everything is documented yet.

Probably others.

AUTHOR

Nicholas Clark <nick@ccl4.org> based on the code in h2xs by Larry Wall and others


ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant

  • USAGE
  • AUTHOR

NAME

ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant

SYNOPSIS

    use ExtUtils::Constant::Utils qw (C_stringify);
    $C_code = C_stringify $stuff;

DESCRIPTION

ExtUtils::Constant::Utils packages up utility subroutines used by ExtUtils::Constant, ExtUtils::Constant::Base and derived classes. All its functions are explicitly exportable.

USAGE

C_stringify NAME

A function which returns a 7 bit ASCII correctly \ escaped version of the string passed suitable for C's "" or ''. It will die if passed Unicode characters.

perl_stringify NAME

A function which returns a 7 bit ASCII correctly \ escaped version of the string passed suitable for a perl "" string.

AUTHOR

Nicholas Clark <nick@ccl4.org> based on the code in h2xs by Larry Wall and others


ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

  • BUGS
  • AUTHOR

NAME

ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

SYNOPSIS

    require ExtUtils::Constant::XS;

DESCRIPTION

ExtUtils::Constant::XS overrides ExtUtils::Constant::Base to generate C code for XS modules' constants.

BUGS

Nothing is documented.

Probably others.

AUTHOR

Nicholas Clark <nick@ccl4.org> based on the code in h2xs by Larry Wall and others


ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications

  • @EXPORT
  • FUNCTIONS
  • EXAMPLES
  • SEE ALSO
  • AUTHOR

NAME

ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications

SYNOPSIS

 perl -MExtUtils::Embed -e xsinit
 perl -MExtUtils::Embed -e ccopts
 perl -MExtUtils::Embed -e ldopts

DESCRIPTION

ExtUtils::Embed provides utility functions for embedding a Perl interpreter and extensions in your C/C++ applications. Typically, an application Makefile will invoke ExtUtils::Embed functions while building your application.

@EXPORT

ExtUtils::Embed exports the following functions:

xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(), ccdlflags(), xsi_header(), xsi_protos(), xsi_body()

FUNCTIONS

xsinit()

Generate C/C++ code for the XS initializer function.

When invoked as `perl -MExtUtils::Embed -e xsinit --` the following options are recognized:

-o <output filename> (Defaults to perlxsi.c)

-o STDOUT will print to STDOUT.

-std (Write code for extensions that are linked with the current Perl.)

Any additional arguments are expected to be names of modules to generate code for.

When invoked with parameters the following are accepted and optional:

xsinit($filename,$std,[@modules])

Where,

$filename is equivalent to the -o option.

$std is boolean, equivalent to the -std option.

[@modules] is an array ref, same as additional arguments mentioned above.

Examples
 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket

This will generate code with an xs_init function that glues the perl Socket::bootstrap function to the C boot_Socket function and writes it to a file named xsinit.c.

Note that DynaLoader is a special case where it must call boot_DynaLoader directly.

 perl -MExtUtils::Embed -e xsinit

This will generate code for linking with DynaLoader and each static extension found in $Config{static_ext}. The code is written to the default file name perlxsi.c.

 perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle

Here, code is written for all the currently linked extensions along with code for DBI and DBD::Oracle.

If you have a working DynaLoader then there is rarely any need to statically link in any other extensions.

ldopts()

Output arguments for linking the Perl library and extensions to your application.

When invoked as `perl -MExtUtils::Embed -e ldopts --` the following options are recognized:

-std

Output arguments for linking the Perl library and any extensions linked with the current Perl.

-I <path1:path2>

Search path for ModuleName.a archives. Default path is @INC. Library archives are expected to be found as /some/path/auto/ModuleName/ModuleName.a For example, when looking for Socket.a relative to a search path, we should find auto/Socket/Socket.a

When looking for DBD::Oracle relative to a search path, we should find auto/DBD/Oracle/Oracle.a

Keep in mind that you can always supply /my/own/path/ModuleName.a as an additional linker argument.

-- <list of linker args>

Additional linker arguments to be considered.

Any additional arguments found before the -- token are expected to be names of modules to generate code for.

When invoked with parameters the following are accepted and optional:

ldopts($std,[@modules],[@link_args],$path)

Where:

$std is boolean, equivalent to the -std option.

[@modules] is equivalent to additional arguments found before the -- token.

[@link_args] is equivalent to arguments found after the -- token.

$path is equivalent to the -I option.

In addition, when ldopts is called with parameters, it will return the argument string rather than print it to STDOUT.

Examples
 perl -MExtUtils::Embed -e ldopts

This will print arguments for linking with libperl.a, DynaLoader and extensions found in $Config{static_ext}. This includes libraries found in $Config{libs} and the first ModuleName.a library for each extension that is found by searching @INC or the path specified by the -I option. In addition, when ModuleName.a is found, additional linker arguments are picked up from the extralibs.ld file in the same directory.

 perl -MExtUtils::Embed -e ldopts -- -std Socket

This will do the same as the above example, along with printing additional arguments for linking with the Socket extension.

 perl -MExtUtils::Embed -e ldopts -- DynaLoader

This will print arguments for linking with just the DynaLoader extension and libperl.a.

 perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql

Any arguments after the second '--' token are additional linker arguments that will be examined for potential conflict. If there is no conflict, the additional arguments will be part of the output.

perl_inc()

For including perl header files this function simply prints:

 -I$Config{archlibexp}/CORE

So, rather than having to say:

 perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'

Just say:

 perl -MExtUtils::Embed -e perl_inc
ccflags(), ccdlflags()

These functions simply print $Config{ccflags} and $Config{ccdlflags}

ccopts()

This function combines perl_inc(), ccflags() and ccdlflags() into one.

xsi_header()

This function simply returns a string defining the same EXTERN_C macro as perlmain.c along with #including perl.h and EXTERN.h.

xsi_protos(@modules)

This function returns a string of boot_$ModuleName prototypes for each @modules.

xsi_body(@modules)

This function returns a string of calls to newXS() that glue the module bootstrap function to boot_ModuleName for each @modules.

xsinit() uses the xsi_* functions to generate most of its code.

EXAMPLES

For examples on how to use ExtUtils::Embed for building C/C++ applications with embedded perl, see the perlembed manpage.

SEE ALSO

the perlembed manpage

AUTHOR

Doug MacEachern <dougm@osf.org>

Based on ideas from Tim Bunce <Tim.Bunce@ig.co.uk> and minimod.pl by Andreas Koenig <k@anna.in-berlin.de> and Tim Bunce.


ExtUtils::Install - install files from here to there

    • Functions
  • ENVIRONMENT
  • AUTHOR
  • LICENSE

NAME

ExtUtils::Install - install files from here to there

SYNOPSIS

  use ExtUtils::Install;

  install({ 'blib/lib' => 'some/install/dir' } );

  uninstall($packlist);

  pm_to_blib({ 'lib/Foo/Bar.pm' => 'blib/lib/Foo/Bar.pm' });

DESCRIPTION

Handles the installing and uninstalling of perl modules, scripts, man pages, etc...

Both install() and uninstall() are specific to the way ExtUtils::MakeMaker handles the installation and deinstallation of perl modules. They are not designed as general purpose tools.

Functions

install
    install(\%from_to);
    install(\%from_to, $verbose, $dont_execute, $uninstall_shadows);

Copies each directory tree of %from_to to its corresponding value preserving timestamps and permissions.

There are two keys with a special meaning in the hash: "read" and "write". These contain packlist files. After the copying is done, install() will write the list of target files to $from_to{write}. If $from_to{read} is given the contents of this file will be merged into the written file. The read and the written file may be identical, but on AFS it is quite likely that people are installing to a different directory than the one where the files later appear.

If $verbose is true, will print out each file removed. Default is false. This is "make install VERBINST=1"

If $dont_execute is true it will only print what it was going to do without actually doing it. Default is false.

If $uninstall_shadows is true any differing versions throughout @INC will be uninstalled. This is "make install UNINST=1"

install_default DISCOURAGED
    install_default();
    install_default($fullext);

Calls install() with arguments to copy a module from blib/ to the default site installation location.

$fullext is the name of the module converted to a directory (ie. Foo::Bar would be Foo/Bar). If $fullext is not specified, it will attempt to read it from @ARGV.

This is primarily useful for install scripts.

NOTE This function is not really useful because of the hard-coded install location with no way to control site vs core vs vendor directories and the strange way in which the module name is given. Consider its use discouraged.

uninstall
    uninstall($packlist_file);
    uninstall($packlist_file, $verbose, $dont_execute);

Removes the files listed in a $packlist_file.

If $verbose is true, will print out each file removed. Default is false.

If $dont_execute is true it will only print what it was going to do without actually doing it. Default is false.

pm_to_blib
    pm_to_blib(\%from_to, $autosplit_dir);
    pm_to_blib(\%from_to, $autosplit_dir, $filter_cmd);

Copies each key of %from_to to its corresponding value efficiently. Filenames with the extension .pm are autosplit into the $autosplit_dir. Any destination directories are created.

$filter_cmd is an optional shell command to run each .pm file through prior to splitting and copying. Input is the contents of the module, output the new module contents.

You can have an environment variable PERL_INSTALL_ROOT set which will be prepended as a directory to each installed file (and directory).

ENVIRONMENT

PERL_INSTALL_ROOT

Will be prepended to each install path.

AUTHOR

Original author lost in the mists of time. Probably the same as Makemaker.

Currently maintained by Michael G Schwern schwern@pobox.com

Send patches and ideas to makemaker@perl.org.

Send bug reports via http://rt.cpan.org/. Please send your generated Makefile along with your report.

For more up-to-date information, see http://www.makemaker.org.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


ExtUtils::Installed - Inventory management of installed modules

  • USAGE
  • FUNCTIONS
  • EXAMPLE
  • AUTHOR

NAME

ExtUtils::Installed - Inventory management of installed modules

SYNOPSIS

   use ExtUtils::Installed;
   my ($inst) = ExtUtils::Installed->new();
   my (@modules) = $inst->modules();
   my (@missing) = $inst->validate("DBI");
   my $all_files = $inst->files("DBI");
   my $files_below_usr_local = $inst->files("DBI", "all", "/usr/local");
   my $all_dirs = $inst->directories("DBI");
   my $dirs_below_usr_local = $inst->directory_tree("DBI", "prog");
   my $packlist = $inst->packlist("DBI");

DESCRIPTION

ExtUtils::Installed provides a standard way to find out what core and module files have been installed. It uses the information stored in .packlist files created during installation to provide this information. In addition it provides facilities to classify the installed files and to extract directory information from the .packlist files.

USAGE

The new() function searches for all the installed .packlists on the system, and stores their contents. The .packlists can be queried with the functions described below.

FUNCTIONS

new()

This takes no parameters, and searches for all the installed .packlists on the system. The packlists are read using the ExtUtils::packlist module.

modules()

This returns a list of the names of all the installed modules. The perl 'core' is given the special name 'Perl'.

files()

This takes one mandatory parameter, the name of a module. It returns a list of all the filenames from the package. To obtain a list of core perl files, use the module name 'Perl'. Additional parameters are allowed. The first is one of the strings "prog", "doc" or "all", to select either just program files, just manual files or all files. The remaining parameters are a list of directories. The filenames returned will be restricted to those under the specified directories.

directories()

This takes one mandatory parameter, the name of a module. It returns a list of all the directories from the package. Additional parameters are allowed. The first is one of the strings "prog", "doc" or "all", to select either just program directories, just manual directories or all directories. The remaining parameters are a list of directories. The directories returned will be restricted to those under the specified directories. This method returns only the leaf directories that contain files from the specified module.

directory_tree()

This is identical in operation to directories(), except that it includes all the intermediate directories back up to the specified directories.

validate()

This takes one mandatory parameter, the name of a module. It checks that all the files listed in the modules .packlist actually exist, and returns a list of any missing files. If an optional second argument which evaluates to true is given any missing files will be removed from the .packlist

packlist()

This returns the ExtUtils::Packlist object for the specified module.

version()

This returns the version number for the specified module.

EXAMPLE

See the example in the ExtUtils::Packlist manpage.

AUTHOR

Alan Burlison <Alan.Burlison@uk.sun.com>


ExtUtils::Liblist - determine libraries to use and how to use them

    • EXTRALIBS
    • LDLOADLIBS and LD_RUN_PATH
    • BSLOADLIBS
  • PORTABILITY
    • VMS implementation
    • Win32 implementation
  • SEE ALSO

NAME

ExtUtils::Liblist - determine libraries to use and how to use them

SYNOPSIS

  require ExtUtils::Liblist;

  $MM->ext($potential_libs, $verbose, $need_names);

  # Usually you can get away with:
  ExtUtils::Liblist->ext($potential_libs, $verbose, $need_names)

DESCRIPTION

This utility takes a list of libraries in the form -llib1 -llib2 -llib3 and returns lines suitable for inclusion in an extension Makefile. Extra library paths may be included with the form -L/another/path this will affect the searches for all subsequent libraries.

It returns an array of four or five scalar values: EXTRALIBS, BSLOADLIBS, LDLOADLIBS, LD_RUN_PATH, and, optionally, a reference to the array of the filenames of actual libraries. Some of these don't mean anything unless on Unix. See the details about those platform specifics below. The list of the filenames is returned only if $need_names argument is true.

Dependent libraries can be linked in one of three ways:

  • For static extensions

    by the ld command when the perl binary is linked with the extension library. See EXTRALIBS below.

  • For dynamic extensions at build/link time

    by the ld command when the shared object is built/linked. See LDLOADLIBS below.

  • For dynamic extensions at load time

    by the DynaLoader when the shared object is loaded. See BSLOADLIBS below.

EXTRALIBS

List of libraries that need to be linked with when linking a perl binary which includes this extension. Only those libraries that actually exist are included. These are written to a file and used when linking perl.

LDLOADLIBS and LD_RUN_PATH

List of those libraries which can or must be linked into the shared library when created using ld. These may be static or dynamic libraries. LD_RUN_PATH is a colon separated list of the directories in LDLOADLIBS. It is passed as an environment variable to the process that links the shared library.

BSLOADLIBS

List of those libraries that are needed but can be linked in dynamically at run time on this platform. SunOS/Solaris does not need this because ld records the information (from LDLOADLIBS) into the object file. This list is used to create a .bs (bootstrap) file.

PORTABILITY

This module deals with a lot of system dependencies and has quite a few architecture specific ifs in the code.

VMS implementation

The version of ext() which is executed under VMS differs from the Unix-OS/2 version in several respects:

  • Input library and path specifications are accepted with or without the -l and -L prefixes used by Unix linkers. If neither prefix is present, a token is considered a directory to search if it is in fact a directory, and a library to search for otherwise. Authors who wish their extensions to be portable to Unix or OS/2 should use the Unix prefixes, since the Unix-OS/2 version of ext() requires them.

  • Wherever possible, shareable images are preferred to object libraries, and object libraries to plain object files. In accordance with VMS naming conventions, ext() looks for files named libshr and librtl; it also looks for liblib and liblib to accommodate Unix conventions used in some ported software.

  • For each library that is found, an appropriate directive for a linker options file is generated. The return values are space-separated strings of these directives, rather than elements used on the linker command line.

  • LDLOADLIBS contains both the libraries found based on $potential_libs and the CRTLs, if any, specified in Config.pm. EXTRALIBS contains just those libraries found based on $potential_libs. BSLOADLIBS and LD_RUN_PATH are always empty.

In addition, an attempt is made to recognize several common Unix library names, and filter them out or convert them to their VMS equivalents, as appropriate.

In general, the VMS version of ext() should properly handle input from extensions originally designed for a Unix or VMS environment. If you encounter problems, or discover cases where the search could be improved, please let us know.

Win32 implementation

The version of ext() which is executed under Win32 differs from the Unix-OS/2 version in several respects:

  • If $potential_libs is empty, the return value will be empty. Otherwise, the libraries specified by $Config{perllibs} (see Config.pm) will be appended to the list of $potential_libs. The libraries will be searched for in the directories specified in $potential_libs, $Config{libpth}, and in $Config{installarchlib}/CORE. For each library that is found, a space-separated list of fully qualified library pathnames is generated.

  • Input library and path specifications are accepted with or without the -l and -L prefixes used by Unix linkers.

    An entry of the form -La:\foo specifies the a:\foo directory to look for the libraries that follow.

    An entry of the form -lfoo specifies the library foo, which may be spelled differently depending on what kind of compiler you are using. If you are using GCC, it gets translated to libfoo.a, but for other win32 compilers, it becomes foo.lib. If no files are found by those translated names, one more attempt is made to find them using either foo.a or libfoo.lib, depending on whether GCC or some other win32 compiler is being used, respectively.

    If neither the -L or -l prefix is present in an entry, the entry is considered a directory to search if it is in fact a directory, and a library to search for otherwise. The $Config{lib_ext} suffix will be appended to any entries that are not directories and don't already have the suffix.

    Note that the -L and -l prefixes are not required, but authors who wish their extensions to be portable to Unix or OS/2 should use the prefixes, since the Unix-OS/2 version of ext() requires them.

  • Entries cannot be plain object files, as many Win32 compilers will not handle object files in the place of libraries.

  • Entries in $potential_libs beginning with a colon and followed by alphanumeric characters are treated as flags. Unknown flags will be ignored.

    An entry that matches /:nodefault/i disables the appending of default libraries found in $Config{perllibs} (this should be only needed very rarely).

    An entry that matches /:nosearch/i disables all searching for the libraries specified after it. Translation of -Lfoo and -lfoo still happens as appropriate (depending on compiler being used, as reflected by $Config{cc}), but the entries are not verified to be valid files or directories.

    An entry that matches /:search/i reenables searching for the libraries specified after it. You can put it at the end to enable searching for default libraries specified by $Config{perllibs}.

  • The libraries specified may be a mixture of static libraries and import libraries (to link with DLLs). Since both kinds are used pretty transparently on the Win32 platform, we do not attempt to distinguish between them.

  • LDLOADLIBS and EXTRALIBS are always identical under Win32, and BSLOADLIBS and LD_RUN_PATH are always empty (this may change in future).

  • You must make sure that any paths and path components are properly surrounded with double-quotes if they contain spaces. For example, $potential_libs could be (literally):

            "-Lc:\Program Files\vc\lib" msvcrt.lib "la test\foo bar.lib"

    Note how the first and last entries are protected by quotes in order to protect the spaces.

  • Since this module is most often used only indirectly from extension Makefile.PL files, here is an example Makefile.PL entry to add a library to the build process for an extension:

            LIBS => ['-lgl']

    When using GCC, that entry specifies that MakeMaker should first look for libgl.a (followed by gl.a) in all the locations specified by $Config{libpth}.

    When using a compiler other than GCC, the above entry will search for gl.lib (followed by libgl.lib).

    If the library happens to be in a location not in $Config{libpth}, you need:

            LIBS => ['-Lc:\gllibs -lgl']

    Here is a less often used example:

            LIBS => ['-lgl', ':nosearch -Ld:\mesalibs -lmesa -luser32']

    This specifies a search for library gl as before. If that search fails to find the library, it looks at the next item in the list. The :nosearch flag will prevent searching for the libraries that follow, so it simply returns the value as -Ld:\mesalibs -lmesa -luser32, since GCC can use that value as is with its linker.

    When using the Visual C compiler, the second item is returned as -libpath:d:\mesalibs mesa.lib user32.lib.

    When using the Borland compiler, the second item is returned as -Ld:\mesalibs mesa.lib user32.lib, and MakeMaker takes care of moving the -Ld:\mesalibs to the correct place in the linker command line.

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass

NAME

ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass

SYNOPSIS

  require ExtUtils::MM;
  my $mm = MM->new(...);

DESCRIPTION

FOR INTERNAL USE ONLY

ExtUtils::MM is a subclass of ExtUtils::MakeMaker which automatically chooses the appropriate OS specific subclass for you (ie. ExtUils::MM_Unix, etc...).

It also provides a convenient alias via the MM class (I didn't want MakeMaker modules outside of ExtUtils/).

This class might turn out to be a temporary solution, but MM won't go away.


ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix

    • Overridden methods
      • dlsyms
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix

SYNOPSIS

  Don't use this module directly.
  Use ExtUtils::MM and let it choose.

DESCRIPTION

This is a subclass of ExtUtils::MM_Unix which contains functionality for AIX.

Unless otherwise stated it works just like ExtUtils::MM_Unix

Overridden methods

dlsyms

Define DL_FUNCS and DL_VARS and write the *.exp files.

AUTHOR

Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MM_Any - Platform-agnostic MM methods

  • METHODS
    • Cross-platform helper methods
      • os_flavor Abstract
      • os_flavor_is
      • split_command
      • echo
      • wraplist
      • cd Abstract
      • oneliner Abstract
      • quote_literal Abstract
      • escape_newlines Abstract
      • max_exec_len Abstract
    • Targets
      • all_target
      • blibdirs_target
      • clean (o)
      • clean_subdirs_target
      • dir_target
      • distdir
      • dist_test
      • dynamic (o)
      • htmlifypods
      • htmlifypods_target
      • makemakerdflt_target
      • manifypods_target
      • metafile_target
      • distmeta_target
      • realclean (o)
      • realclean_subdirs_target
      • signature_target
      • distsignature_target
      • special_targets
    • Init methods
      • init_INST
      • init_INSTALL
      • init_INSTALL_from_PREFIX
      • init_from_INSTALLBASE
      • init_VERSION Abstract
      • init_others Abstract
      • init_DIRFILESEP Abstract
      • init_linker Abstract
      • init_platform
    • Tools
      • manifypods
      • POD2HTML_macro
      • POD2MAN_macro
      • test_via_harness
      • test_via_script
      • tool_autosplit
    • File::Spec wrappers
      • catfile
    • Misc
      • find_tests
      • extra_clean_files
      • installvars
      • libscan
      • platform_constants
  • AUTHOR

NAME

ExtUtils::MM_Any - Platform-agnostic MM methods

SYNOPSIS

  FOR INTERNAL USE ONLY!
  package ExtUtils::MM_SomeOS;

  # Temporarily, you have to subclass both.  Put MM_Any first.
  require ExtUtils::MM_Any;
  require ExtUtils::MM_Unix;
  @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);

DESCRIPTION

FOR INTERNAL USE ONLY!

ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of modules. It contains methods which are either inherently cross-platform or are written in a cross-platform manner.

Subclass off of ExtUtils::MM_Any and ExtUtils::MM_Unix. This is a temporary solution.

THIS MAY BE TEMPORARY!

METHODS

Any methods marked Abstract must be implemented by subclasses.

Cross-platform helper methods

These are methods which help writing cross-platform code.

os_flavor Abstract

    my @os_flavor = $mm->os_flavor;

@os_flavor is the style of operating system this is, usually corresponding to the MM_*.pm file we're using.

The first element of @os_flavor is the major family (ie. Unix, Windows, VMS, OS/2, etc...) and the rest are sub families.

Some examples:

    Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
    Windows NT     ('Win32', 'WinNT')
    Win98          ('Win32', 'Win9x')
    Linux          ('Unix',  'Linux')
    MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
    OS/2           ('OS/2')

This is used to write code for styles of operating system. See os_flavor_is() for use.

os_flavor_is

    my $is_this_flavor = $mm->os_flavor_is($this_flavor);
    my $is_this_flavor = $mm->os_flavor_is(@one_of_these_flavors);

Checks to see if the current operating system is one of the given flavors.

This is useful for code like:

    if( $mm->os_flavor_is('Unix') ) {
        $out = `foo 2>&1`;
    }
    else {
        $out = `foo`;
    }

split_command

    my @cmds = $MM->split_command($cmd, @args);

Most OS have a maximum command length they can execute at once. Large modules can easily generate commands well past that limit. Its necessary to split long commands up into a series of shorter commands.

split_command will return a series of @cmds each processing part of the args. Collectively they will process all the arguments. Each individual line in @cmds will not be longer than the $self->max_exec_len being careful to take into account macro expansion.

$cmd should include any switches and repeated initial arguments.

If no @args are given, no @cmds will be returned.

Pairs of arguments will always be preserved in a single command, this is a heuristic for things like pm_to_blib and pod2man which work on pairs of arguments. This makes things like this safe:

    $self->split_command($cmd, %pod2man);

echo

    my @commands = $MM->echo($text);
    my @commands = $MM->echo($text, $file);
    my @commands = $MM->echo($text, $file, $appending);

Generates a set of @commands which print the $text to a $file.

If $file is not given, output goes to STDOUT.

If $appending is true the $file will be appended to rather than overwritten.

wraplist

  my $args = $mm->wraplist(@list);

Takes an array of items and turns them into a well-formatted list of arguments. In most cases this is simply something like:

    FOO \
    BAR \
    BAZ

cd Abstract

  my $subdir_cmd = $MM->cd($subdir, @cmds);

This will generate a make fragment which runs the @cmds in the given $dir. The rough equivalent to this, except cross platform.

  cd $subdir && $cmd

Currently $dir can only go down one level. "foo" is fine. "foo/bar" is not. "../foo" is right out.

The resulting $subdir_cmd has no leading tab nor trailing newline. This makes it easier to embed in a make string. For example.

      my $make = sprintf <<'CODE', $subdir_cmd;
        foo :
      $(ECHO) what
      %s
      $(ECHO) mouche
        CODE

oneliner Abstract

  my $oneliner = $MM->oneliner($perl_code);
  my $oneliner = $MM->oneliner($perl_code, \@switches);

This will generate a perl one-liner safe for the particular platform you're on based on the given $perl_code and @switches (a -e is assumed) suitable for using in a make target. It will use the proper shell quoting and escapes.

$(PERLRUN) will be used as perl.

Any newlines in $perl_code will be escaped. Leading and trailing newlines will be stripped. Makes this idiom much easier:

    my $code = $MM->oneliner(<<'CODE', [...switches...]);
    some code here
    another line here
    CODE

Usage might be something like:

    # an echo emulation
    $oneliner = $MM->oneliner('print "Foo\n"');
    $make = '$oneliner > somefile';

All dollar signs must be doubled in the $perl_code if you expect them to be interpreted normally, otherwise it will be considered a make macro. Also remember to quote make macros else it might be used as a bareword. For example:

    # Assign the value of the $(VERSION_FROM) make macro to $vf.
    $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');

Its currently very simple and may be expanded sometime in the figure to include more flexible code and switches.

quote_literal Abstract

    my $safe_text = $MM->quote_literal($text);

This will quote $text so it is interpreted literally in the shell.

For example, on Unix this would escape any single-quotes in $text and put single-quotes around the whole thing.

escape_newlines Abstract

    my $escaped_text = $MM->escape_newlines($text);

Shell escapes newlines in $text.

max_exec_len Abstract

    my $max_exec_len = $MM->max_exec_len;

Calculates the maximum command size the OS can exec. Effectively, this is the max size of a shell command line.

Targets

These are methods which produce make targets.

all_target

Generate the default target 'all'.

blibdirs_target

    my $make_frag = $mm->blibdirs_target;

Creates the blibdirs target which creates all the directories we use in blib/.

The blibdirs.ts target is deprecated. Depend on blibdirs instead.

clean (o)

Defines the clean target.

clean_subdirs_target

  my $make_frag = $MM->clean_subdirs_target;

Returns the clean_subdirs target. This is used by the clean target to call clean on any subdirectories which contain Makefiles.

dir_target

    my $make_frag = $mm->dir_target(@directories);

Generates targets to create the specified directories and set its permission to 0755.

Because depending on a directory to just ensure it exists doesn't work too well (the modified time changes too often) dir_target() creates a .exists file in the created directory. It is this you should depend on. For portability purposes you should use the $(DIRFILESEP) macro rather than a '/' to seperate the directory from the file.

    yourdirectory$(DIRFILESEP).exists

distdir

Defines the scratch directory target that will hold the distribution before tar-ing (or shar-ing).

dist_test

Defines a target that produces the distribution in the scratchdirectory, and runs 'perl Makefile.PL; make ;make test' in that subdirectory.

dynamic (o)

Defines the dynamic target.

htmlifypods

Defines targets and routines to translate the pods into html and put them into the INST_* directories.

htmlifypods_target

  my $htmlifypods_target = $self->htmlifypods_target;

Generates the htmlifypods target. This target generates html pages from all POD files in MAN1PODS and MAN3PODS.

makemakerdflt_target

  my $make_frag = $mm->makemakerdflt_target

Returns a make fragment with the makemakerdeflt_target specified. This target is the first target in the Makefile, is the default target and simply points off to 'all' just in case any make variant gets confused or something gets snuck in before the real 'all' target.

manifypods_target

  my $manifypods_target = $self->manifypods_target;

Generates the manifypods target. This target generates man pages from all POD files in MAN1PODS and MAN3PODS.

metafile_target

    my $target = $mm->metafile_target;

Generate the metafile target.

Writes the file META.yml YAML encoded meta-data about the module in the distdir. The format follows Module::Build's as closely as possible. Additionally, we include:

    version_from
    installdirs

distmeta_target

    my $make_frag = $mm->distmeta_target;

Generates the distmeta target to add META.yml to the MANIFEST in the distdir.

realclean (o)

Defines the realclean target.

realclean_subdirs_target

  my $make_frag = $MM->realclean_subdirs_target;

Returns the realclean_subdirs target. This is used by the realclean target to call realclean on any subdirectories which contain Makefiles.

signature_target

    my $target = $mm->signature_target;

Generate the signature target.

Writes the file SIGNATURE with "cpansign -s".

distsignature_target

    my $make_frag = $mm->distsignature_target;

Generates the distsignature target to add SIGNATURE to the MANIFEST in the distdir.

special_targets

  my $make_frag = $mm->special_targets

Returns a make fragment containing any targets which have special meaning to make. For example, .SUFFIXES and .PHONY.

Init methods

Methods which help initialize the MakeMaker object and macros.

init_INST

    $mm->init_INST;

Called by init_main. Sets up all INST_* variables except those related to XS code. Those are handled in init_xs.

init_INSTALL

    $mm->init_INSTALL;

Called by init_main. Sets up all INSTALL_* variables (except INSTALLDIRS) and *PREFIX.

init_INSTALL_from_PREFIX

  $mm->init_INSTALL_from_PREFIX;

init_from_INSTALLBASE

    $mm->init_from_INSTALLBASE

init_VERSION Abstract

    $mm->init_VERSION

Initialize macros representing versions of MakeMaker and other tools

MAKEMAKER: path to the MakeMaker module.

MM_VERSION: ExtUtils::MakeMaker Version

MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards compat)

VERSION: version of your module

VERSION_MACRO: which macro represents the version (usually 'VERSION')

VERSION_SYM: like version but safe for use as an RCS revision number

DEFINE_VERSION: -D line to set the module version when compiling

XS_VERSION: version in your .xs file. Defaults to $(VERSION)

XS_VERSION_MACRO: which macro represents the XS version.

XS_DEFINE_VERSION: -D line to set the xs version when compiling.

Called by init_main.

init_others Abstract

    $MM->init_others();

Initializes the macro definitions used by tools_other() and places them in the $MM object.

If there is no description, its the same as the parameter to WriteMakefile() documented in ExtUtils::MakeMaker.

Defines at least these macros.

  Macro             Description
  NOOP              Do nothing
  NOECHO            Tell make not to display the command itself
  MAKEFILE
  FIRST_MAKEFILE
  MAKEFILE_OLD
  MAKE_APERL_FILE   File used by MAKE_APERL
  SHELL             Program used to run
                    shell commands
  ECHO              Print text adding a newline on the end
  RM_F              Remove a file
  RM_RF             Remove a directory
  TOUCH             Update a file's timestamp
  TEST_F            Test for a file's existence
  CP                Copy a file
  MV                Move a file
  CHMOD             Change permissions on a
                    file
  UMASK_NULL        Nullify umask
  DEV_NULL          Supress all command output

init_DIRFILESEP Abstract

  $MM->init_DIRFILESEP;
  my $dirfilesep = $MM->{DIRFILESEP};

Initializes the DIRFILESEP macro which is the seperator between the directory and filename in a filepath. ie. / on Unix, \ on Win32 and nothing on VMS.

For example:

    # instead of $(INST_ARCHAUTODIR)/extralibs.ld
    $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld

Something of a hack but it prevents a lot of code duplication between MM_* variants.

Do not use this as a seperator between directories. Some operating systems use different seperators between subdirectories as between directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).

init_linker Abstract

    $mm->init_linker;

Initialize macros which have to do with linking.

PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic extensions.

PERL_ARCHIVE_AFTER: path to a library which should be put on the linker command line after the external libraries to be linked to dynamic extensions. This may be needed if the linker is one-pass, and Perl includes some overrides for C RTL functions, such as malloc().

EXPORT_LIST: name of a file that is passed to linker to define symbols to be exported.

Some OSes do not need these in which case leave it blank.

init_platform

    $mm->init_platform

Initialize any macros which are for platform specific use only.

A typical one is the version number of your OS specific mocule. (ie. MM_Unix_VERSION or MM_VMS_VERSION).

Tools

A grab bag of methods to generate specific macros and commands.

manifypods

Defines targets and routines to translate the pods into manpages and put them into the INST_* directories.

POD2HTML_macro

  my $pod2html_macro = $self->POD2HTML_macro

Returns a definition for the POD2HTML macro. This is a program which emulates the pod2html utility. You can add more switches to the command by simply appending them on the macro.

Typical usage:

    $(POD2HTML) podfile1 html_page1 ...

POD2MAN_macro

  my $pod2man_macro = $self->POD2MAN_macro

Returns a definition for the POD2MAN macro. This is a program which emulates the pod2man utility. You can add more switches to the command by simply appending them on the macro.

Typical usage:

    $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...

test_via_harness

  my $command = $mm->test_via_harness($perl, $tests);

Returns a $command line which runs the given set of $tests with Test::Harness and the given $perl.

Used on the t/*.t files.

test_via_script

  my $command = $mm->test_via_script($perl, $script);

Returns a $command line which just runs a single test without Test::Harness. No checks are done on the results, they're just printed.

Used for test.pl, since they don't always follow Test::Harness formatting.

tool_autosplit

Defines a simple perl call that runs autosplit. May be deprecated by pm_to_blib soon.

File::Spec wrappers

ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here override File::Spec.

catfile

File::Spec <= 0.83 has a bug where the file part of catfile is not canonicalized. This override fixes that bug.

Misc

Methods I can't really figure out where they should go yet.

find_tests

  my $test = $mm->find_tests;

Returns a string suitable for feeding to the shell to return all tests in t/*.t.

extra_clean_files

    my @files_to_clean = $MM->extra_clean_files;

Returns a list of OS specific files to be removed in the clean target in addition to the usual set.

installvars

    my @installvars = $mm->installvars;

A list of all the INSTALL* variables without the INSTALL prefix. Useful for iteration or building related variable sets.

libscan

  my $wanted = $self->libscan($path);

Takes a path to a file or dir and returns an empty string if we don't want to include this file in the library. Otherwise it returns the the $path unchanged.

Mainly used to exclude version control administrative directories from installation.

platform_constants

    my $make_frag = $mm->platform_constants

Returns a make fragment defining all the macros initialized in init_platform() rather than put them in constants().

AUTHOR

Michael G Schwern <schwern@pobox.com> and the denizens of makemaker@perl.org with code from ExtUtils::MM_Unix and ExtUtils::MM_Win32.


ExtUtils::MM_BeOS - methods to override UN*X behaviour in ExtUtils::MakeMaker

NAME

ExtUtils::MM_BeOS - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

 use ExtUtils::MM_BeOS; # Done internally by ExtUtils::MakeMaker if needed

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

os_flavor

BeOS is BeOS.

init_linker

libperl.a equivalent to be linked to dynamic extensions.

1; __END__


ExtUtils::MM_Cygwin - methods to override UN*X behaviour in ExtUtils::MakeMaker

NAME

ExtUtils::MM_Cygwin - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

 use ExtUtils::MM_Cygwin; # Done internally by ExtUtils::MakeMaker if needed

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there.

os_flavor

We're Unix and Cygwin.

cflags

if configured for dynamic loading, triggers #define EXT in EXTERN.h

replace_manpage_separator

replaces strings '::' with '.' in MAN*POD man page names

init_linker

points to libperl.a


ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix

    • Overridden methods
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix

SYNOPSIS

  Don't use this module directly.
  Use ExtUtils::MM and let it choose.

DESCRIPTION

This is a subclass of ExtUtils::MM_Unix which contains functionality for DOS.

Unless otherwise stated, it works just like ExtUtils::MM_Unix

Overridden methods

os_flavor
replace_manpage_separator

Generates Foo__Bar.3 style man page names

AUTHOR

Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix

SEE ALSO

the ExtUtils::MM_Unix manpage, the ExtUtils::MakeMaker manpage


ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic

NAME

ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic

SYNOPSIS

  # MM_MacOS no longer contains any code.  This is just a stub.

DESCRIPTION

Once upon a time, MakeMaker could produce an approximation of a correct Makefile on MacOS Classic (MacPerl). Due to a lack of maintainers, this fell out of sync with the rest of MakeMaker and hadn't worked in years. Since there's little chance of it being repaired, MacOS Classic is fading away, and the code was icky to begin with, the code has been deleted to make maintenance easier.

Those interested in writing modules for MacPerl should use Module::Build which works better than MakeMaker ever did.

Anyone interested in resurrecting this file should pull the old version from the MakeMaker CVS repository and contact makemaker@perl.org, but we really encourage you to work on Module::Build instead.


ExtUtils::MM_NW5 - methods to override UN*X behaviour in ExtUtils::MakeMaker

NAME

ExtUtils::MM_NW5 - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

 use ExtUtils::MM_NW5; # Done internally by ExtUtils::MakeMaker if needed

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

os_flavor

We're Netware in addition to being Windows.

init_platform

Add Netware macros.

LIBPTH, BASE_IMPORT, NLM_VERSION, MPKTOOL, TOOLPATH, BOOT_SYMBOL, NLM_SHORT_NAME, INCLUDE, PATH, MM_NW5_REVISION

platform_constants

Add Netware macros initialized above to the Makefile.

const_cccmd
static_lib
dynamic_lib

Defines how to produce the *.so (or equivalent) files.


ExtUtils::MM_OS2 - methods to override UN*X behaviour in ExtUtils::MakeMaker

  • METHODS

NAME

ExtUtils::MM_OS2 - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

 use ExtUtils::MM_OS2; # Done internally by ExtUtils::MakeMaker if needed

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

METHODS

init_dist

Define TO_UNIX to convert OS2 linefeeds to Unix style.

init_linker
os_flavor

OS/2 is OS/2


ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix

    • Overridden methods
      • extra_clean_files
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix

SYNOPSIS

  Don't use this module directly.
  Use ExtUtils::MM and let it choose.

DESCRIPTION

This is a subclass of ExtUtils::MM_Unix which contains functionality for QNX.

Unless otherwise stated it works just like ExtUtils::MM_Unix

Overridden methods

extra_clean_files

Add .err files corresponding to each .c file.

AUTHOR

Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix

    • Overridden methods
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix

SYNOPSIS

  Don't use this module directly.
  Use ExtUtils::MM and let it choose.

DESCRIPTION

This is a subclass of ExtUtils::MM_Unix which contains functionality for the AT&T U/WIN UNIX on Windows environment.

Unless otherwise stated it works just like ExtUtils::MM_Unix

Overridden methods

os_flavor

In addition to being Unix, we're U/WIN.

replace_manpage_separator

AUTHOR

Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix

SEE ALSO

the ExtUtils::MM_Win32 manpage, the ExtUtils::MakeMaker manpage


ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker

  • METHODS
    • Methods
  • SEE ALSO

NAME

ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker

SYNOPSIS

require ExtUtils::MM_Unix;

DESCRIPTION

The methods provided by this package are designed to be used in conjunction with ExtUtils::MakeMaker. When MakeMaker writes a Makefile, it creates one or more objects that inherit their methods from a package MM. MM itself doesn't provide any methods, but it ISA ExtUtils::MM_Unix class. The inheritance tree of MM lets operating specific packages take the responsibility for all the methods provided by MM_Unix. We are trying to reduce the number of the necessary overrides by defining rather primitive operations within ExtUtils::MM_Unix.

If you are going to write a platform specific MM package, please try to limit the necessary overrides to primitive methods, and if it is not possible to do so, let's work out how to achieve that gain.

If you are overriding any of these methods in your Makefile.PL (in the MY class), please report that to the makemaker mailing list. We are trying to minimize the necessary method overrides and switch to data driven Makefile.PLs wherever possible. In the long run less methods will be overridable via the MY class.

METHODS

The following description of methods is still under development. Please refer to the code for not suitably documented sections and complain loudly to the makemaker@perl.org mailing list. Better yet, provide a patch.

Not all of the methods below are overridable in a Makefile.PL. Overridable methods are marked as (o). All methods are overridable by a platform specific MM_*.pm file.

Cross-platform methods are being moved into MM_Any. If you can't find something that used to be in here, look in MM_Any.

Methods

os_flavor

Simply says that we're Unix.

c_o (o)

Defines the suffix rules to compile different flavors of C files to object files.

cflags (o)

Does very much the same as the cflags script in the perl distribution. It doesn't return the whole compiler command line, but initializes all of its parts. The const_cccmd method then actually returns the definition of the CCCMD macro which uses these parts.

const_cccmd (o)

Returns the full compiler call for C programs and stores the definition in CONST_CCCMD.

const_config (o)

Defines a couple of constants in the Makefile that are imported from %Config.

const_loadlibs (o)

Defines EXTRALIBS, LDLOADLIBS, BSLOADLIBS, LD_RUN_PATH. See the ExtUtils::Liblist manpage for details.

constants (o)
  my $make_frag = $mm->constants;

Prints out macros for lots of constants.

depend (o)

Same as macro for the depend attribute.

init_DEST
  $mm->init_DEST

Defines the DESTDIR and DEST* variables paralleling the INSTALL*.

init_dist
  $mm->init_dist;

Defines a lot of macros for distribution support.

  macro         description                     default
  TAR           tar command to use              tar
  TARFLAGS      flags to pass to TAR            cvf
  ZIP           zip command to use              zip
  ZIPFLAGS      flags to pass to ZIP            -r
  COMPRESS      compression command to          gzip --best
                use for tarfiles
  SUFFIX        suffix to put on                .gz
                compressed files
  SHAR          shar command to use             shar
  PREOP         extra commands to run before
                making the archive
  POSTOP        extra commands to run after
                making the archive
  TO_UNIX       a command to convert linefeeds
                to Unix style in your archive
  CI            command to checkin your         ci -u
                sources to version control
  RCS_LABEL     command to label your sources   rcs -Nv$(VERSION_SYM): -q
                just after CI is run
  DIST_CP       $how argument to manicopy()     best
                when the distdir is created
  DIST_DEFAULT  default target to use to        tardist
                create a distribution
  DISTVNAME     name of the resulting archive   $(DISTNAME)-$(VERSION)
                (minus suffixes)
dist (o)
  my $dist_macros = $mm->dist(%overrides);

Generates a make fragment defining all the macros initialized in init_dist.

%overrides can be used to override any of the above.

dist_basics (o)

Defines the targets distclean, distcheck, skipcheck, manifest, veryclean.

dist_ci (o)

Defines a check in target for RCS.

dist_core (o)
  my $dist_make_fragment = $MM->dist_core;

Puts the targets necessary for 'make dist' together into one make fragment.

dist_target
  my $make_frag = $MM->dist_target;

Returns the 'dist' target to make an archive for distribution. This target simply checks to make sure the Makefile is up-to-date and depends on $(DIST_DEFAULT).

tardist_target
  my $make_frag = $MM->tardist_target;

Returns the 'tardist' target which is simply so 'make tardist' works. The real work is done by the dynamically named tardistfile_target() method, tardist should have that as a dependency.

zipdist_target
  my $make_frag = $MM->zipdist_target;

Returns the 'zipdist' target which is simply so 'make zipdist' works. The real work is done by the dynamically named zipdistfile_target() method, zipdist should have that as a dependency.

tarfile_target
  my $make_frag = $MM->tarfile_target;

The name of this target is the name of the tarball generated by tardist. This target does the actual work of turning the distdir into a tarball.

zipfile_target
  my $make_frag = $MM->zipfile_target;

The name of this target is the name of the zip file generated by zipdist. This target does the actual work of turning the distdir into a zip file.

uutardist_target
  my $make_frag = $MM->uutardist_target;

Converts the tarfile into a uuencoded file

shdist_target
  my $make_frag = $MM->shdist_target;

Converts the distdir into a shell archive.

dlsyms (o)

Used by some OS' to define DL_FUNCS and DL_VARS and write the *.exp files.

Normally just returns an empty string.

dynamic_bs (o)

Defines targets for bootstrap files.

dynamic_lib (o)

Defines how to produce the *.so (or equivalent) files.

exescan

Deprecated method. Use libscan instead.

extliblist

Called by init_others, and calls ext ExtUtils::Liblist. See the ExtUtils::Liblist manpage for details.

find_perl

Finds the executables PERL and FULLPERL

fixin
  $mm->fixin(@files);

Inserts the sharpbang or equivalent magic number to a set of @files.

force (o)

Writes an empty FORCE: target.

guess_name

Guess the name of this package by examining the working directory's name. MakeMaker calls this only if the developer has not supplied a NAME attribute.

has_link_code

Returns true if C, XS, MYEXTLIB or similar objects exist within this object that need a compiler. Does not descend into subdirectories as needs_linking() does.

init_dirscan

Scans the directory structure and initializes DIR, XS, XS_FILES, PM, C, C_FILES, O_FILES, H, H_FILES, PL_FILES, MAN*PODS, EXE_FILES.

Called by init_main.

init_DIRFILESEP

Using / for Unix. Called by init_main.

init_main

Initializes AR, AR_STATIC_ARGS, BASEEXT, CONFIG, DISTNAME, DLBASE, EXE_EXT, FULLEXT, FULLPERL, FULLPERLRUN, FULLPERLRUNINST, INST_*, INSTALL*, INSTALLDIRS, LIB_EXT, LIBPERL_A, MAP_TARGET, NAME, OBJ_EXT, PARENT_NAME, PERL, PERL_ARCHLIB, PERL_INC, PERL_LIB, PERL_SRC, PERLRUN, PERLRUNINST, PREFIX, VERSION, VERSION_SYM, XS_VERSION.

init_others

Initializes EXTRALIBS, BSLOADLIBS, LDLOADLIBS, LIBS, LD_RUN_PATH, LD, OBJECT, BOOTDEP, PERLMAINCC, LDFROM, LINKTYPE, SHELL, NOOP, FIRST_MAKEFILE, MAKEFILE_OLD, NOECHO, RM_F, RM_RF, TEST_F, TOUCH, CP, MV, CHMOD, UMASK_NULL, ECHO, ECHO_N

init_linker

Unix has no need of special linker flags.

init_PERL
    $mm->init_PERL;

Called by init_main. Sets up ABSPERL, PERL, FULLPERL and all the *PERLRUN* permutations.

    PERL is allowed to be miniperl
    FULLPERL must be a complete perl
    ABSPERL is PERL converted to an absolute path
    *PERLRUN contains everything necessary to run perl, find it's
         libraries, etc...
    *PERLRUNINST is *PERLRUN + everything necessary to find the
         modules being built.
init_platform
platform_constants

Add MM_Unix_VERSION.

init_PERM
  $mm->init_PERM

Called by init_main. Initializes PERL_*

init_xs
    $mm->init_xs

Sets up macros having to do with XS code. Currently just INST_STATIC, INST_DYNAMIC and INST_BOOT.

install (o)

Defines the install target.

installbin (o)

Defines targets to make and to install EXE_FILES.

linkext (o)

Defines the linkext target which in turn defines the LINKTYPE.

lsdir

Takes as arguments a directory name and a regular expression. Returns all entries in the directory that match the regular expression.

macro (o)

Simple subroutine to insert the macros defined by the macro attribute into the Makefile.

makeaperl (o)

Called by staticmake. Defines how to write the Makefile to produce a static new perl.

By default the Makefile produced includes all the static extensions in the perl library. (Purified versions of library files, e.g., DynaLoader_pure_p1_c0_032.a are automatically ignored to avoid link errors.)

makefile (o)

Defines how to rewrite the Makefile.

maybe_command

Returns true, if the argument is likely to be a command.

needs_linking (o)

Does this module need linking? Looks into subdirectory objects (see also has_link_code())

nicetext

misnamed method (will have to be changed). The MM_Unix method just returns the argument without further processing.

On VMS used to insure that colons marking targets are preceded by space - most Unix Makes don't need this, but it's necessary under VMS to distinguish the target delimiter from a colon appearing as part of a filespec.

parse_abstract

parse a file and return what you think is the ABSTRACT

parse_version

parse a file and return what you think is $VERSION in this file set to. It will return the string "undef" if it can't figure out what $VERSION is. $VERSION should be for all to see, so our $VERSION or plain $VERSION are okay, but my $VERSION is not.

pasthru (o)

Defines the string that is passed to recursive make calls in subdirectories.

perl_script

Takes one argument, a file name, and returns the file name, if the argument is likely to be a perl script. On MM_Unix this is true for any ordinary, readable file.

perldepend (o)

Defines the dependency from all *.h files that come with the perl distribution.

perm_rw (o)

Returns the attribute PERM_RW or the string 644. Used as the string that is passed to the chmod command to set the permissions for read/writeable files. MakeMaker chooses 644 because it has turned out in the past that relying on the umask provokes hard-to-track bug reports. When the return value is used by the perl function chmod, it is interpreted as an octal value.

perm_rwx (o)

Returns the attribute PERM_RWX or the string 755, i.e. the string that is passed to the chmod command to set the permissions for executable files. See also perl_rw.

pm_to_blib

Defines target that copies all files in the hash PM to their destination and autosplits them. See DESCRIPTION in the ExtUtils::Install manpage

post_constants (o)

Returns an empty string per default. Dedicated to overrides from within Makefile.PL after all constants have been defined.

post_initialize (o)

Returns an empty string per default. Used in Makefile.PLs to add some chunk of text to the Makefile after the object is initialized.

postamble (o)

Returns an empty string. Can be used in Makefile.PLs to write some text to the Makefile at the end.

ppd

Defines target that creates a PPD (Perl Package Description) file for a binary distribution.

prefixify
  $MM->prefixify($var, $prefix, $new_prefix, $default);

Using either $MM->{uc $var} || $Config{lc $var}, it will attempt to replace it's $prefix with a $new_prefix.

Should the $prefix fail to match AND a PREFIX was given as an argument to WriteMakefile() it will set it to the $new_prefix + $default. This is for systems whose file layouts don't neatly fit into our ideas of prefixes.

This is for heuristics which attempt to create directory structures that mirror those of the installed perl.

For example:

    $MM->prefixify('installman1dir', '/usr', '/home/foo', 'man/man1');

this will attempt to remove '/usr' from the front of the $MM->{INSTALLMAN1DIR} path (initializing it to $Config{installman1dir} if necessary) and replace it with '/home/foo'. If this fails it will simply use '/home/foo/man/man1'.

processPL (o)

Defines targets to run *.PL files.

quote_paren

Backslashes parentheses () in command line arguments. Doesn't handle recursive Makefile $(...) constructs, but handles simple ones.

replace_manpage_separator
  my $man_name = $MM->replace_manpage_separator($file_path);

Takes the name of a package, which may be a nested package, in the form 'Foo/Bar.pm' and replaces the slash with :: or something else safe for a man page file name. Returns the replacement.

cd
oneliner
quote_literal
escape_newlines
max_exec_len

Using POSIX::ARG_MAX. Otherwise falling back to 4096.

static (o)

Defines the static target.

static_lib (o)

Defines how to produce the *.a (or equivalent) files.

staticmake (o)

Calls makeaperl.

subdir_x (o)

Helper subroutine for subdirs

subdirs (o)

Defines targets to process subdirectories.

test (o)

Defines the test targets.

test_via_harness (override)

For some reason which I forget, Unix machines like to have PERL_DL_NONLAZY set for tests.

test_via_script (override)

Again, the PERL_DL_NONLAZY thing.

tools_other (o)
    my $make_frag = $MM->tools_other;

Returns a make fragment containing definitions for the macros init_others() initializes.

tool_xsubpp (o)

Determines typemaps, xsubpp version, prototype behaviour.

all_target

Build man pages, too

top_targets (o)

Defines the targets all, subdirs, config, and O_FILES

writedoc

Obsolete, deprecated method. Not used since Version 5.21.

xs_c (o)

Defines the suffix rules to compile XS files to C.

xs_cpp (o)

Defines the suffix rules to compile XS files to C++.

xs_o (o)

Defines suffix rules to go from XS to object files directly. This is only intended for broken make implementations.

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MM_VMS - methods to override UN*X behaviour in ExtUtils::MakeMaker

    • Methods always loaded
    • Methods
  • AUTHOR

NAME

ExtUtils::MM_VMS - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

  Do not use this directly.
  Instead, use ExtUtils::MM and it will figure out which MM_*
  class to use for you.

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

Methods always loaded

wraplist

Converts a list into a string wrapped at approximately 80 columns.

Methods

Those methods which override default MM_Unix methods are marked "(override)", while methods unique to MM_VMS are marked "(specific)". For overridden methods, documentation is limited to an explanation of why this method overrides the MM_Unix method; see the ExtUtils::MM_Unix documentation for more details.

guess_name (override)

Try to determine name of extension being built. We begin with the name of the current directory. Since VMS filenames are case-insensitive, however, we look for a .pm file whose name matches that of the current directory (presumably the 'main' .pm file for this extension), and try to find a package statement from which to obtain the Mixed::Case package name.

find_perl (override)

Use VMS file specification syntax and CLI commands to find and invoke Perl images.

maybe_command (override)

Follows VMS naming conventions for executable files. If the name passed in doesn't exactly match an executable file, appends .Exe (or equivalent) to check for executable image, and .Com to check for DCL procedure. If this fails, checks directories in DCL$PATH and finally Sys$System: for an executable file having the name specified, with or without the .Exe-equivalent suffix.

pasthru (override)

VMS has $(MMSQUALIFIERS) which is a listing of all the original command line options. This is used in every invokation of make in the VMS Makefile so PASTHRU should not be necessary. Using PASTHRU tends to blow commands past the 256 character limit.

pm_to_blib (override)

VMS wants a dot in every file so we can't have one called 'pm_to_blib', it becomes 'pm_to_blib.' and MMS/K isn't smart enough to know that when you have a target called 'pm_to_blib' it should look for 'pm_to_blib.'.

So in VMS its pm_to_blib.ts.

perl_script (override)

If name passed in doesn't specify a readable file, appends .com or .pl and tries again, since it's customary to have file types on all files under VMS.

replace_manpage_separator

Use as separator a character which is legal in a VMS-syntax file name.

init_DEST

(override) Because of the difficulty concatenating VMS filepaths we must pre-expand the DEST* variables.

init_DIRFILESEP

No seperator between a directory path and a filename on VMS.

init_main (override)
init_others (override)

Provide VMS-specific forms of various utility commands, then hand off to the default MM_Unix method.

DEV_NULL should probably be overriden with something.

Also changes EQUALIZE_TIMESTAMP to set revision date of target file to one second later than source file, since MMK interprets precisely equal revision dates for a source and target file as a sign that the target needs to be updated.

init_platform (override)

Add PERL_VMS, MM_VMS_REVISION and MM_VMS_VERSION.

MM_VMS_REVISION is for backwards compatibility before MM_VMS had a $VERSION.

platform_constants
init_VERSION (override)

Override the *DEFINE_VERSION macros with VMS semantics. Translate the MAKEMAKER filepath to VMS style.

constants (override)

Fixes up numerous file and directory macros to insure VMS syntax regardless of input syntax. Also makes lists of files comma-separated.

special_targets

Clear the default .SUFFIXES and put in our own list.

cflags (override)

Bypass shell script and produce qualifiers for CC directly (but warn user if a shell script for this extension exists). Fold multiple /Defines into one, since some C compilers pay attention to only one instance of this qualifier on the command line.

const_cccmd (override)

Adds directives to point C preprocessor to the right place when handling #include <sys/foo.h> directives. Also constructs CC command line a bit differently than MM_Unix method.

tools_other (override)

Throw in some dubious extra macros for Makefile args.

Also keep around the old $(SAY) macro in case somebody's using it.

init_dist (override)

VMSish defaults for some values.

  macro         description                     default
  ZIPFLAGS      flags to pass to ZIP            -Vu
  COMPRESS      compression command to          gzip
                use for tarfiles
  SUFFIX        suffix to put on                -gz
                compressed files
  SHAR          shar command to use             vms_share
  DIST_DEFAULT  default target to use to        tardist
                create a distribution
  DISTVNAME     Use VERSION_SYM instead of      $(DISTNAME)-$(VERSION_SYM)
                VERSION for the name
c_o (override)

Use VMS syntax on command line. In particular, $(DEFINE) and $(PERL_INC) have been pulled into $(CCCMD). Also use MM[SK] macros.

xs_c (override)

Use MM[SK] macros.

xs_o (override)

Use MM[SK] macros, and VMS command line for C compiler.

dlsyms (override)

Create VMS linker options files specifying universal symbols for this extension's shareable image, and listing other shareable images or libraries to which it should be linked.

dynamic_lib (override)

Use VMS Link command.

static_lib (override)

Use VMS commands to manipulate object library.

extra_clean_files

Clean up some OS specific files. Plus the temp file used to shorten a lot of commands.

zipfile_target
tarfile_target
shdist_target

Syntax for invoking shar, tar and zip differs from that for Unix.

install (override)

Work around DCL's 255 character limit several times,and use VMS-style command line quoting in a few cases.

perldepend (override)

Use VMS-style syntax for files; it's cheaper to just do it directly here than to have the MM_Unix method call catfile repeatedly. Also, if we have to rebuild Config.pm, use MM[SK] to do it.

makeaperl (override)

Undertake to build a new set of Perl images using VMS commands. Since VMS does dynamic loading, it's not necessary to statically link each extension into the Perl image, so this isn't the normal build path. Consequently, it hasn't really been tested, and may well be incomplete.

nicetext (override)

Insure that colons marking targets are preceded by space, in order to distinguish the target delimiter from a colon appearing as part of a filespec.

prefixify (override)

prefixifying on VMS is simple. Each should simply be:

    perl_root:[some.dir]

which can just be converted to:

    volume:[your.prefix.some.dir]

otherwise you get the default layout.

In effect, your search prefix is ignored and $Config{vms_prefix} is used instead.

cd
oneliner
echo

perl trips up on "<foo>" thinking it's an input redirect. So we use the native Write command instead. Besides, its faster.

quote_literal
escape_newlines
max_exec_len

256 characters.

init_linker
eliminate_macros

Expands MM[KS]/Make macros in a text string, using the contents of identically named elements of %$self, and returns the result as a file specification in Unix syntax.

NOTE: This is the canonical version of the method. The version in File::Spec::VMS is deprecated.

fixpath
   my $path = $mm->fixpath($path);
   my $path = $mm->fixpath($path, $is_dir);

Catchall routine to clean up problem MM[SK]/Make macros. Expands macros in any directory specification, in order to avoid juxtaposing two VMS-syntax directories when MM[SK] is run. Also expands expressions which are all macro, so that we can tell how long the expansion is, and avoid overrunning DCL's command buffer when MM[KS] is running.

fixpath() checks to see whether the result matches the name of a directory in the current default directory and returns a directory or file specification accordingly. $is_dir can be set to true to force fixpath() to consider the path to be a directory or false to force it to be a file.

NOTE: This is the canonical version of the method. The version in File::Spec::VMS is deprecated.

os_flavor

VMS is VMS.

AUTHOR

Original author Charles Bailey bailey@newman.upenn.edu

Maintained by Michael G Schwern schwern@pobox.com

See the ExtUtils::MakeMaker manpage for patching and contact information.


ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix

    • Overridden methods
      • extra_clean_files
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix

SYNOPSIS

  Don't use this module directly.
  Use ExtUtils::MM and let it choose.

DESCRIPTION

This is a subclass of ExtUtils::MM_Unix which contains functionality for VOS.

Unless otherwise stated it works just like ExtUtils::MM_Unix

Overridden methods

extra_clean_files

Cleanup VOS core files

AUTHOR

Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MM_Win32 - methods to override UN*X behaviour in ExtUtils::MakeMaker

    • Overridden methods

NAME

ExtUtils::MM_Win32 - methods to override UN*X behaviour in ExtUtils::MakeMaker

SYNOPSIS

 use ExtUtils::MM_Win32; # Done internally by ExtUtils::MakeMaker if needed

DESCRIPTION

See ExtUtils::MM_Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

Overridden methods

dlsyms
replace_manpage_separator

Changes the path separator with .

maybe_command

Since Windows has nothing as simple as an executable bit, we check the file extension.

The PATHEXT env variable will be used to get a list of extensions that might indicate a command, otherwise .com, .exe, .bat and .cmd will be used by default.

init_DIRFILESEP

Using \ for Windows.

init_others

Override some of the Unix specific commands with portable ExtUtils::Command ones.

Also provide defaults for LD and AR in case the %Config values aren't set.

LDLOADLIBS's default is changed to $Config{libs}.

Adjustments are made for Borland's quirks needing -L to come first.

init_platform

Add MM_Win32_VERSION.

platform_constants
special_targets

Add .USESHELL target for dmake.

static_lib

Changes how to run the linker.

The rest is duplicate code from MM_Unix. Should move the linker code to its own method.

dynamic_lib

Complicated stuff for Win32 that I don't understand. :(

extra_clean_files

Clean out some extra dll.{base,exp} files which might be generated by gcc. Otherwise, take out all *.pdb files.

init_linker
perl_script

Checks for the perl program under several common perl extensions.

xs_o

This target is stubbed out. Not sure why.

pasthru

All we send is -nologo to nmake to prevent it from printing its damned banner.

oneliner

These are based on what command.com does on Win98. They may be wrong for other Windows shells, I don't know.

cd

dmake can handle Unix style cd'ing but nmake (at least 1.5) cannot. It wants:

    cd dir
    command
    another_command
    cd ..

NOTE This cd can only go one level down. So far this sufficient for what MakeMaker needs.

max_exec_len

nmake 1.50 limits command length to 2048 characters.

os_flavor

Windows is Win32.


ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X

    • Overriden methods
  • AUTHOR

NAME

ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X

SYNOPSIS

  You should not be using this module directly.

DESCRIPTION

This is a subclass of ExtUtils::MM_Win32 containing changes necessary to get MakeMaker playing nice with command.com and other Win9Xisms.

Overriden methods

Most of these make up for limitations in the Win9x/nmake command shell. Mostly its lack of &&.

xs_c

The && problem.

xs_cpp

The && problem

xs_o

The && problem.

max_exec_len

Win98 chokes on things like Encode if we set the max length to nmake's max of 2K. So we go for a more conservative value of 1K.

os_flavor

Win95 and Win98 and WinME are collectively Win9x and Win32

AUTHOR

Code originally inside MM_Win32. Original author unknown.

Currently maintained by Michael G Schwern schwern@pobox.com.

Send patches and ideas to makemaker@perl.org.

See http://www.makemaker.org.


ExtUtils::MY - ExtUtils::MakeMaker subclass for customization

NAME

ExtUtils::MY - ExtUtils::MakeMaker subclass for customization

SYNOPSIS

  # in your Makefile.PL
  sub MY::whatever {
      ...
  }

DESCRIPTION

FOR INTERNAL USE ONLY

ExtUtils::MY is a subclass of ExtUtils::MM. Its provided in your Makefile.PL for you to add and override MakeMaker functionality.

It also provides a convenient alias via the MY class.

ExtUtils::MY might turn out to be a temporary solution, but MY won't go away.


ExtUtils::MakeMaker - Create a module Makefile

    • How To Write A Makefile.PL
    • Default Makefile Behaviour
    • make test
    • make testdb
    • make install
    • PREFIX and LIB attribute
    • AFS users
    • Static Linking of a new Perl Binary
    • Determination of Perl Library and Installation Locations
    • Which architecture dependent directory?
    • Using Attributes and Parameters
    • Additional lowercase attributes
    • Overriding MakeMaker Methods
    • The End Of Cargo Cult Programming
    • Hintsfile support
    • Distribution Support
    • Module Meta-Data
    • Disabling an extension
    • Other Handy Functions
  • ENVIRONMENT
  • SEE ALSO
  • AUTHORS
  • LICENSE

NAME

ExtUtils::MakeMaker - Create a module Makefile

SYNOPSIS

  use ExtUtils::MakeMaker;

  WriteMakefile( ATTRIBUTE => VALUE [, ...] );

DESCRIPTION

This utility is designed to write a Makefile for an extension module from a Makefile.PL. It is based on the Makefile.SH model provided by Andy Dougherty and the perl5-porters.

It splits the task of generating the Makefile into several subroutines that can be individually overridden. Each subroutine returns the text it wishes to have written to the Makefile.

MakeMaker is object oriented. Each directory below the current directory that contains a Makefile.PL is treated as a separate object. This makes it possible to write an unlimited number of Makefiles with a single invocation of WriteMakefile().

How To Write A Makefile.PL

See ExtUtils::MakeMaker::Tutorial.

The long answer is the rest of the manpage :-)

Default Makefile Behaviour

The generated Makefile enables the user of the extension to invoke

  perl Makefile.PL # optionally "perl Makefile.PL verbose"
  make
  make test        # optionally set TEST_VERBOSE=1
  make install     # See below

The Makefile to be produced may be altered by adding arguments of the form KEY=VALUE. E.g.

  perl Makefile.PL PREFIX=~

Other interesting targets in the generated Makefile are

  make config     # to check if the Makefile is up-to-date
  make clean      # delete local temp files (Makefile gets renamed)
  make realclean  # delete derived files (including ./blib)
  make ci         # check in all the files in the MANIFEST file
  make dist       # see below the Distribution Support section

make test

MakeMaker checks for the existence of a file named test.pl in the current directory and if it exists it execute the script with the proper set of perl -I options.

MakeMaker also checks for any files matching glob("t/*.t"). It will execute all matching files in alphabetical order via the the Test::Harness manpage module with the -I switches set correctly.

If you'd like to see the raw output of your tests, set the TEST_VERBOSE variable to true.

  make test TEST_VERBOSE=1

make testdb

A useful variation of the above is the target testdb. It runs the test under the Perl debugger (see the perldebug manpage). If the file test.pl exists in the current directory, it is used for the test.

If you want to debug some other testfile, set the TEST_FILE variable thusly:

  make testdb TEST_FILE=t/mytest.t

By default the debugger is called using -d option to perl. If you want to specify some other option, set the TESTDB_SW variable:

  make testdb TESTDB_SW=-Dx

make install

make alone puts all relevant files into directories that are named by the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR, INST_MAN3DIR INST_HTMLDIR. All these default to something below ./blib if you are not building below the perl source directory. If you are building below the perl source, INST_LIB and INST_ARCHLIB default to ../../lib, and INST_SCRIPT is not defined.

The install target of the generated Makefile copies the files found below each of the INST_* directories to their INSTALL* counterparts. Which counterparts are chosen depends on the setting of INSTALLDIRS according to the following table:

                                 INSTALLDIRS set to
                           perl        site          vendor
                 PERLPREFIX      SITEPREFIX          VENDORPREFIX
  INST_ARCHLIB   INSTALLARCHLIB  INSTALLSITEARCH     INSTALLVENDORARCH
  INST_LIB       INSTALLPRIVLIB  INSTALLSITELIB      INSTALLVENDORLIB
  INST_BIN       INSTALLBIN      INSTALLSITEBIN      INSTALLVENDORBIN
  INST_SCRIPT    INSTALLSCRIPT   INSTALLSITESCRIPT   INSTALLVENDORSCRIPT
  INST_MAN1DIR   INSTALLMAN1DIR  INSTALLSITEMAN1DIR  INSTALLVENDORMAN1DIR
  INST_MAN3DIR   INSTALLMAN3DIR  INSTALLSITEMAN3DIR  INSTALLVENDORMAN3DIR
  INST_HTMLDIR   INSTALLHTMLDIR  INSTALLSITEHTMLDIR  INSTALLVENDORHTMLDIR

The INSTALL... macros in turn default to their %Config ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.

You can check the values of these variables on your system with

    perl '-V:install.*'

And to check the sequence in which the library directories are searched by perl, run

    perl -le 'print join $/, @INC'

Sometimes older versions of the module you're installing live in other directories in @INC. Because Perl loads the first version of a module it finds, not the newest, you might accidentally get one of these older versions even after installing a brand new version. To delete all other versions of the module you're installing (not simply older ones) set the UNINST variable.

    make install UNINST=1

PREFIX and LIB attribute

PREFIX and LIB can be used to set several INSTALL* attributes in one go. The quickest way to install a module in a non-standard place might be

    perl Makefile.PL PREFIX=~

This will install all files in the module under your home directory, with man pages and libraries going into an appropriate place (usually ~/man and ~/lib).

Another way to specify many INSTALL directories with a single parameter is LIB.

    perl Makefile.PL LIB=~/lib

This will install the module's architecture-independent files into ~/lib, the architecture-dependent files into ~/lib/$archname.

Note, that in both cases the tilde expansion is done by MakeMaker, not by perl by default, nor by make.

Conflicts between parameters LIB, PREFIX and the various INSTALL* arguments are resolved so that:

  • setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);

  • without LIB, setting PREFIX replaces the initial $Config{prefix} part of those INSTALL* arguments, even if the latter are explicitly set (but are set to still start with $Config{prefix}).

If the user has superuser privileges, and is not working on AFS or relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSCRIPT, etc. will be appropriate, and this incantation will be the best:

    perl Makefile.PL;
    make;
    make test
    make install

make install per default writes some documentation of what has been done into the file $(INSTALLARCHLIB)/perllocal.pod. This feature can be bypassed by calling make pure_install.

AFS users

will have to specify the installation directories as these most probably have changed since perl itself has been installed. They will have to do this by calling

    perl Makefile.PL INSTALLSITELIB=/afs/here/today \
        INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
    make

Be careful to repeat this procedure every time you recompile an extension, unless you are sure the AFS installation directories are still valid.

Static Linking of a new Perl Binary

An extension that is built with the above steps is ready to use on systems supporting dynamic loading. On systems that do not support dynamic loading, any newly created extension has to be linked together with the available resources. MakeMaker supports the linking process by creating appropriate targets in the Makefile whenever an extension is built. You can invoke the corresponding section of the makefile with

    make perl

That produces a new perl binary in the current directory with all extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP, and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on UNIX, this is called Makefile.aperl (may be system dependent). If you want to force the creation of a new perl, it is recommended, that you delete this Makefile.aperl, so the directories are searched-through for linkable libraries again.

The binary can be installed into the directory where perl normally resides on your machine with

    make inst_perl

To produce a perl binary with a different name than perl, either say

    perl Makefile.PL MAP_TARGET=myperl
    make myperl
    make inst_perl

or say

    perl Makefile.PL
    make myperl MAP_TARGET=myperl
    make inst_perl MAP_TARGET=myperl

In any case you will be prompted with the correct invocation of the inst_perl target that installs the new binary into INSTALLBIN.

make inst_perl per default writes some documentation of what has been done into the file $(INSTALLARCHLIB)/perllocal.pod. This can be bypassed by calling make pure_inst_perl.

Warning: the inst_perl: target will most probably overwrite your existing perl binary. Use with care!

Sometimes you might want to build a statically linked perl although your system supports dynamic loading. In this case you may explicitly set the linktype with the invocation of the Makefile.PL or make:

    perl Makefile.PL LINKTYPE=static    # recommended

or

    make LINKTYPE=static                # works on most systems

Determination of Perl Library and Installation Locations

MakeMaker needs to know, or to guess, where certain things are located. Especially INST_LIB and INST_ARCHLIB (where to put the files during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read existing modules from), and PERL_INC (header files and libperl*.*).

Extensions may be built either using the contents of the perl source directory tree or from the installed perl library. The recommended way is to build extensions after you have run 'make install' on perl itself. You can do that in any directory on your hard disk that is not below the perl source tree. The support for extensions below the ext directory of the perl distribution is only good for the standard extensions that come with perl.

If an extension is being built below the ext/ directory of the perl source then MakeMaker will set PERL_SRC automatically (e.g., ../..). If PERL_SRC is defined and the extension is recognized as a standard extension, then other variables default to the following:

  PERL_INC     = PERL_SRC
  PERL_LIB     = PERL_SRC/lib
  PERL_ARCHLIB = PERL_SRC/lib
  INST_LIB     = PERL_LIB
  INST_ARCHLIB = PERL_ARCHLIB

If an extension is being built away from the perl source then MakeMaker will leave PERL_SRC undefined and default to using the installed copy of the perl library. The other variables default to the following:

  PERL_INC     = $archlibexp/CORE
  PERL_LIB     = $privlibexp
  PERL_ARCHLIB = $archlibexp
  INST_LIB     = ./blib/lib
  INST_ARCHLIB = ./blib/arch

If perl has not yet been installed then PERL_SRC can be defined on the command line as shown in the previous section.

Which architecture dependent directory?

If you don't want to keep the defaults for the INSTALL* macros, MakeMaker helps you to minimize the typing needed: the usual relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined by Configure at perl compilation time. MakeMaker supports the user who sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not, then MakeMaker defaults the latter to be the same subdirectory of INSTALLPRIVLIB as Configure decided for the counterparts in %Config , otherwise it defaults to INSTALLPRIVLIB. The same relationship holds for INSTALLSITELIB and INSTALLSITEARCH.

MakeMaker gives you much more freedom than needed to configure internal variables and get different results. It is worth to mention, that make(1) also lets you configure most of the variables that are used in the Makefile. But in the majority of situations this will not be necessary, and should only be done if the author of a package recommends it (or you know what you're doing).

Using Attributes and Parameters

The following attributes may be specified as arguments to WriteMakefile() or as NAME=VALUE pairs on the command line.

ABSTRACT

One line description of the module. Will be included in PPD file.

ABSTRACT_FROM

Name of the file that contains the package description. MakeMaker looks for a line in the POD matching /^($package\s-\s)(.*)/. This is typically the first line in the "=head1 NAME" section. $2 becomes the abstract.

AUTHOR

String containing name (and email address) of package author(s). Is used in PPD (Perl Package Description) files for PPM (Perl Package Manager).

BINARY_LOCATION

Used when creating PPD files for binary packages. It can be set to a full or relative path or URL to the binary archive for a particular architecture. For example:

        perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz

builds a PPD package that references a binary of the Agent package, located in the x86 directory relative to the PPD itself.

C

Ref to array of *.c file names. Initialised from a directory scan and the values portion of the XS attribute hash. This is not currently used by MakeMaker but may be handy in Makefile.PLs.

CCFLAGS

String that will be included in the compiler call command line between the arguments INC and OPTIMIZE.

CONFIG

Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from config.sh. MakeMaker will add to CONFIG the following values anyway: ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc lib_ext obj_ext ranlib sitelibexp sitearchexp so

CONFIGURE

CODE reference. The subroutine should return a hash reference. The hash may contain further attributes, e.g. {LIBS => ...}, that have to be determined by some evaluation method.

DEFINE

Something like "-DHAVE_UNISTD_H"

DESTDIR

This is the root directory into which the code will be installed. It prepends itself to the normal prefix. For example, if your code would normally go into /usr/local/lib/perl you could set DESTDIR=~/tmp/ and installation would go into ~/tmp/usr/local/lib/perl.

This is primarily of use for people who repackage Perl modules.

NOTE: Due to the nature of make, it is important that you put the trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.

DIR

Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm' ] in ext/SDBM_File

DISTNAME

A safe filename for the package.

Defaults to NAME above but with :: replaced with -.

For example, Foo::Bar becomes Foo-Bar.

DISTVNAME

Your name for distributing the package with the version number included. This is used by 'make dist' to name the resulting archive file.

Defaults to DISTNAME-VERSION.

For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.

On some OS's where . has special meaning VERSION_SYM may be used in place of VERSION.

DL_FUNCS

Hashref of symbol names for routines to be made available as universal symbols. Each key/value pair consists of the package name and an array of routine names in that package. Used only under AIX, OS/2, VMS and Win32 at present. The routine names supplied will be expanded in the same way as XSUB names are expanded by the XS() macro. Defaults to

  {"$(NAME)" => ["boot_$(NAME)" ] }

e.g.

  {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
   "NetconfigPtr" => [ 'DESTROY'] }

Please see the the ExtUtils::Mksymlists manpage documentation for more information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.

DL_VARS

Array of symbol names for variables to be made available as universal symbols. Used only under AIX, OS/2, VMS and Win32 at present. Defaults to []. (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])

EXCLUDE_EXT

Array of extension names to exclude when doing a static build. This is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more details. (e.g. [ qw( Socket POSIX ) ] )

This attribute may be most useful when specified as a string on the command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'

EXE_FILES

Ref to array of executable files. The files will be copied to the INST_SCRIPT directory. Make realclean will delete them from there again.

If your executables start with something like #!perl or #!/usr/bin/perl MakeMaker will change this to the path of the perl 'Makefile.PL' was invoked with so the programs will be sure to run properly even if perl is not in /usr/bin/perl.

FIRST_MAKEFILE

The name of the Makefile to be produced. This is used for the second Makefile that will be produced for the MAP_TARGET.

Defaults to 'Makefile' or 'Descrip.MMS' on VMS.

(Note: we couldn't use MAKEFILE because dmake uses this for something else).

FULLPERL

Perl binary able to run this extension, load XS modules, etc...

FULLPERLRUN

Like PERLRUN, except it uses FULLPERL.

FULLPERLRUNINST

Like PERLRUNINST, except it uses FULLPERL.

FUNCLIST

This provides an alternate means to specify function names to be exported from the extension. Its value is a reference to an array of function names to be exported by the extension. These names are passed through unaltered to the linker options file.

H

Ref to array of *.h file names. Similar to C.

IMPORTS

This attribute is used to specify names to be imported into the extension. Takes a hash ref.

It is only used on OS/2 and Win32.

INC

Include file dirs eg: "-I/usr/5include -I/path/to/inc"

INCLUDE_EXT

Array of extension names to be included when doing a static build. MakeMaker will normally build with all of the installed extensions when doing a static build, and that is usually the desired behavior. If INCLUDE_EXT is present then MakeMaker will build only with those extensions which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])

It is not necessary to mention DynaLoader or the current extension when filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then only DynaLoader and the current extension will be included in the build.

This attribute may be most useful when specified as a string on the command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'

INSTALLARCHLIB

Used by 'make install', which copies files from INST_ARCHLIB to this directory if INSTALLDIRS is set to perl.

INSTALLBIN

Directory to install binary files (e.g. tkperl) into if INSTALLDIRS=perl.

INSTALLDIRS

Determines which of the sets of installation directories to choose: perl, site or vendor. Defaults to site.

INSTALLMAN1DIR
INSTALLMAN3DIR

These directories get the man pages at 'make install' time if INSTALLDIRS=perl. Defaults to $Config{installman*dir}.

If set to 'none', no man pages will be installed.

INSTALLPRIVLIB

Used by 'make install', which copies files from INST_LIB to this directory if INSTALLDIRS is set to perl.

Defaults to $Config{installprivlib}.

INSTALLSCRIPT

Used by 'make install' which copies files from INST_SCRIPT to this directory if INSTALLDIRS=perl.

INSTALLSITEARCH

Used by 'make install', which copies files from INST_ARCHLIB to this directory if INSTALLDIRS is set to site (default).

INSTALLSITEBIN

Used by 'make install', which copies files from INST_BIN to this directory if INSTALLDIRS is set to site (default).

INSTALLSITELIB

Used by 'make install', which copies files from INST_LIB to this directory if INSTALLDIRS is set to site (default).

INSTALLSITEMAN1DIR
INSTALLSITEMAN3DIR

These directories get the man pages at 'make install' time if INSTALLDIRS=site (default). Defaults to $(SITEPREFIX)/man/man$(MAN*EXT).

If set to 'none', no man pages will be installed.

INSTALLSITESCRIPT

Used by 'make install' which copies files from INST_SCRIPT to this directory if INSTALLDIRS is set to site (default).

INSTALLVENDORARCH

Used by 'make install', which copies files from INST_ARCHLIB to this directory if INSTALLDIRS is set to vendor.

INSTALLVENDORBIN

Used by 'make install', which copies files from INST_BIN to this directory if INSTALLDIRS is set to vendor.

INSTALLVENDORLIB

Used by 'make install', which copies files from INST_LIB to this directory if INSTALLDIRS is set to vendor.

INSTALLVENDORMAN1DIR
INSTALLVENDORMAN3DIR

These directories get the man pages at 'make install' time if INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).

If set to 'none', no man pages will be installed.

INSTALLVENDORSCRIPT

Used by 'make install' which copies files from INST_SCRIPT to this directory if INSTALLDIRS is set to is set to vendor.

INST_ARCHLIB

Same as INST_LIB for architecture dependent files.

INST_BIN

Directory to put real binary files during 'make'. These will be copied to INSTALLBIN during 'make install'

INST_LIB

Directory where we put library files of this extension while building it.

INST_MAN1DIR

Directory to hold the man pages at 'make' time

INST_MAN3DIR

Directory to hold the man pages at 'make' time

INST_HTMLDIR

Directory to hold the html documentation at 'make' time

INST_SCRIPT

Directory, where executable files should be installed during 'make'. Defaults to "./blib/script", just to have a dummy location during testing. make install will copy the files in INST_SCRIPT to INSTALLSCRIPT.

LD

Program to be used to link libraries for dynamic loading.

Defaults to $Config{ld}.

LDDLFLAGS

Any special flags that might need to be passed to ld to create a shared library suitable for dynamic loading. It is up to the makefile to use it. (See lddlflags in the Config manpage)

Defaults to $Config{lddlflags}.

LDFROM

Defaults to "$(OBJECT)" and is used in the ld command to specify what files to link/load from (also see dynamic_lib below for how to specify ld flags)

LIB

LIB should only be set at perl Makefile.PL time but is allowed as a MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB and INSTALLSITELIB to that value regardless any explicit setting of those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH are set to the corresponding architecture subdirectory.

LIBPERL_A

The filename of the perllibrary that will be used together with this extension. Defaults to libperl.a.

LIBS

An anonymous array of alternative library specifications to be searched for (in order) until at least one library is found. E.g.

  'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]

Mind, that any element of the array contains a complete set of arguments for the ld command. So do not specify

  'LIBS' => ["-ltcl", "-ltk", "-lX11"]

See ODBM_File/Makefile.PL for an example, where an array is needed. If you specify a scalar as in

  'LIBS' => "-ltcl -ltk -lX11"

MakeMaker will turn it into an array with one element.

LINKTYPE

'static' or 'dynamic' (default unless usedl=undef in config.sh). Should only be used to force static linking (also see linkext below).

MAKEAPERL

Boolean which tells MakeMaker, that it should include the rules to make a perl. This is handled automatically as a switch by MakeMaker. The user normally does not need it.

MAKEFILE_OLD

When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be backed up at this location.

Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.

MAN1PODS

Hashref of pod-containing files. MakeMaker will default this to all EXE_FILES files that include POD directives. The files listed here will be converted to man pages and installed as was requested at Configure time.

MAN3PODS

Hashref that assigns to *.pm and *.pod files the files into which the manpages are to be written. MakeMaker parses all *.pod and *.pm files for POD directives. Files that contain POD will be the default keys of the MAN3PODS hashref. These will then be converted to man pages during make and will be installed during make install.

MAP_TARGET

If it is intended, that a new perl binary be produced, this variable may hold a name for that binary. Defaults to perl

MYEXTLIB

If the extension links to a library that it builds set this to the name of the library (see SDBM_File)

NAME

Perl module name for this extension (DBD::Oracle). This will default to the directory name but should be explicitly defined in the Makefile.PL.

NEEDS_LINKING

MakeMaker will figure out if an extension contains linkable code anywhere down the directory tree, and will set this variable accordingly, but you can speed it up a very little bit if you define this boolean variable yourself.

NOECHO

Command so make does not print the literal commands its running.

By setting it to an empty string you can generate a Makefile that prints all commands. Mainly used in debugging MakeMaker itself.

Defaults to @.

NORECURS

Boolean. Attribute to inhibit descending into subdirectories.

NO_META

When true, suppresses the generation and addition to the MANIFEST of the META.yml module meta-data file during 'make distdir'.

Defaults to false.

NO_VC

In general, any generated Makefile checks for the current version of MakeMaker and the version the Makefile was built under. If NO_VC is set, the version check is neglected. Do not write this into your Makefile.PL, use it interactively instead.

OBJECT

List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long string containing all object files, e.g. "tkpBind.o tkpButton.o tkpCanvas.o"

(Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)

OPTIMIZE

Defaults to -O. Set it to -g to turn debugging on. The flag is passed to subdirectory makes.

PERL

Perl binary for tasks that can be done by miniperl

PERL_CORE

Set only when MakeMaker is building the extensions of the Perl core distribution.

PERLMAINCC

The call to the program that is able to compile perlmain.c. Defaults to $(CC).

PERL_ARCHLIB

Same as for PERL_LIB, but for architecture dependent files.

Used only when MakeMaker is building the extensions of the Perl core distribution (because normally $(PERL_ARCHLIB) is automatically in @INC, and adding it would get in the way of PERL5LIB).

PERL_LIB

Directory containing the Perl library to use.

Used only when MakeMaker is building the extensions of the Perl core distribution (because normally $(PERL_LIB) is automatically in @INC, and adding it would get in the way of PERL5LIB).

PERL_MALLOC_OK

defaults to 0. Should be set to TRUE if the extension can work with the memory allocation routines substituted by the Perl malloc() subsystem. This should be applicable to most extensions with exceptions of those

  • with bugs in memory allocations which are caught by Perl's malloc();

  • which interact with the memory allocator in other ways than via malloc(), realloc(), free(), calloc(), sbrk() and brk();

  • which rely on special alignment which is not provided by Perl's malloc().

NOTE. Negligence to set this flag in any one of loaded extension nullifies many advantages of Perl's malloc(), such as better usage of system resources, error detection, memory usage reporting, catchable failure of memory allocations, etc.

PERLPREFIX

Directory under which core modules are to be installed.

Defaults to $Config{installprefixexp} falling back to $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should $Config{installprefixexp} not exist.

Overridden by PREFIX.

PERLRUN

Use this instead of $(PERL) when you wish to run perl. It will set up extra necessary flags for you.

PERLRUNINST

Use this instead of $(PERL) when you wish to run perl to work with modules. It will add things like -I$(INST_ARCH) and other necessary flags so perl can see the modules you're about to install.

PERL_SRC

Directory containing the Perl source code (use of this should be avoided, it may be undefined)

PERM_RW

Desired permission for read/writable files. Defaults to 644. See also perm_rw in the MM_Unix manpage.

PERM_RWX

Desired permission for executable files. Defaults to 755. See also perm_rwx in the MM_Unix manpage.

PL_FILES

MakeMaker can run programs to generate files for you at build time. By default any file named *.PL (except Makefile.PL and Build.PL) in the top level directory will be assumed to be a Perl program and run passing its own basename in as an argument. For example...

    perl foo.PL foo

This behavior can be overridden by supplying your own set of files to search. PL_FILES accepts a hash ref, the key being the file to run and the value is passed in as the first argument when the PL file is run.

    PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}

Would run bin/foobar.PL like this:

    perl bin/foobar.PL bin/foobar

If multiple files from one program are desired an array ref can be used.

    PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}

In this case the program will be run multiple times using each target file.

    perl bin/foobar.PL bin/foobar1
    perl bin/foobar.PL bin/foobar2

PL files are normally run after pm_to_blib and include INST_LIB and INST_ARCH in its @INC so the just built modules can be accessed... unless the PL file is making a module (or anything else in PM) in which case it is run before pm_to_blib and does not include INST_LIB and INST_ARCH in its @INC. This apparently odd behavior is there for backwards compatibility (and its somewhat DWIM).

PM

Hashref of .pm files and *.pl files to be installed. e.g.

  {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}

By default this will include *.pm and *.pl and the files found in the PMLIBDIRS directories. Defining PM in the Makefile.PL will override PMLIBDIRS.

PMLIBDIRS

Ref to array of subdirectories containing library files. Defaults to [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files they contain will be installed in the corresponding location in the library. A libscan() method can be used to alter the behaviour. Defining PM in the Makefile.PL will override PMLIBDIRS.

(Where BASEEXT is the last component of NAME.)

PM_FILTER

A filter program, in the traditional Unix sense (input from stdin, output to stdout) that is passed on each .pm file during the build (in the pm_to_blib() phase). It is empty by default, meaning no filtering is done.

Great care is necessary when defining the command if quoting needs to be done. For instance, you would need to say:

  {'PM_FILTER' => 'grep -v \\"^\\#\\"'}

to remove all the leading coments on the fly during the build. The extra \\ are necessary, unfortunately, because this variable is interpolated within the context of a Perl program built on the command line, and double quotes are what is used with the -e switch to build that command line. The # is escaped for the Makefile, since what is going to be generated will then be:

  PM_FILTER = grep -v \"^\#\"

Without the \\ before the #, we'd have the start of a Makefile comment, and the macro would be incorrectly defined.

POLLUTE

Release 5.005 grandfathered old global symbol names by providing preprocessor macros for extension source compatibility. As of release 5.6, these preprocessor definitions are not available by default. The POLLUTE flag specifies that the old names should still be defined:

  perl Makefile.PL POLLUTE=1

Please inform the module author if this is necessary to successfully install a module under 5.6 or later.

PPM_INSTALL_EXEC

Name of the executable used to run PPM_INSTALL_SCRIPT below. (e.g. perl)

PPM_INSTALL_SCRIPT

Name of the script that gets executed by the Perl Package Manager after the installation of a package.

PREFIX

This overrides all the default install locations. Man pages, libraries, scripts, etc... MakeMaker will try to make an educated guess about where to place things under the new PREFIX based on your Config defaults. Failing that, it will fall back to a structure which should be sensible for your platform.

If you specify LIB or any INSTALL* variables they will not be effected by the PREFIX.

PREREQ_FATAL

Bool. If this parameter is true, failing to have the required modules (or the right versions thereof) will be fatal. perl Makefile.PL will die with the proper message.

Note: see the Test::Harness manpage for a shortcut for stopping tests early if you are missing dependencies.

Do not use this parameter for simple requirements, which could be resolved at a later time, e.g. after an unsuccessful make test of your module.

It is extremely rare to have to use PREREQ_FATAL at all!

PREREQ_PM

Hashref: Names of modules that need to be available to run this extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the desired version is the value. If the required version number is 0, we only check if any version is installed already.

PREREQ_PRINT

Bool. If this parameter is true, the prerequisites will be printed to stdout and MakeMaker will exit. The output format is an evalable hash ref.

$PREREQ_PM = {
               'A::B' => Vers1,
               'C::D' => Vers2,
               ...
             };

PRINT_PREREQ

RedHatism for PREREQ_PRINT. The output format is different, though:

    perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
SITEPREFIX

Like PERLPREFIX, but only for the site install locations.

Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have an explicit siteprefix in the Config. In those cases $Config{installprefix} will be used.

Overridable by PREFIX

SIGN

When true, perform the generation and addition to the MANIFEST of the SIGNATURE file in the distdir during 'make distdir', via 'cpansign -s'.

Note that you need to install the Module::Signature module to perform this operation.

Defaults to false.

SKIP

Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the Makefile. Caution! Do not use the SKIP attribute for the negligible speedup. It may seriously damage the resulting Makefile. Only use it if you really need it.

TYPEMAPS

Ref to array of typemap file names. Use this when the typemaps are in some directory other than the current directory or when they are not named typemap. The last typemap in the list takes precedence. A typemap in the current directory has highest precedence, even if it isn't listed in TYPEMAPS. The default system typemap has lowest precedence.

VENDORPREFIX

Like PERLPREFIX, but only for the vendor install locations.

Defaults to $Config{vendorprefixexp}.

Overridable by PREFIX

VERBINST

If true, make install will be verbose

VERSION

Your version number for distributing the package. This defaults to 0.1.

VERSION_FROM

Instead of specifying the VERSION in the Makefile.PL you can let MakeMaker parse a file to determine the version number. The parsing routine requires that the file named by VERSION_FROM contains one single line to compute the version number. The first line in the file that contains the regular expression

    /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/

will be evaluated with eval() and the value of the named variable after the eval() will be assigned to the VERSION attribute of the MakeMaker object. The following lines will be parsed o.k.:

    $VERSION = '1.00';
    *VERSION = \'1.01';
    $VERSION = sprintf "%d.%03d", q$Revision: 4535 $ =~ /(\d+)/g;
    $FOO::VERSION = '1.10';
    *FOO::VERSION = \'1.11';
    our $VERSION = 1.2.3;       # new for perl5.6.0

but these will fail:

    my $VERSION = '1.01';
    local $VERSION = '1.02';
    local $FOO::VERSION = '1.30';

(Putting my or local on the preceding line will work o.k.)

The file named in VERSION_FROM is not added as a dependency to Makefile. This is not really correct, but it would be a major pain during development to have to rewrite the Makefile for any smallish change in that file. If you want to make sure that the Makefile contains the correct VERSION macro after any change of the file, you would have to do something like

    depend => { Makefile => '$(VERSION_FROM)' }

See attribute depend below.

VERSION_SYM

A sanitized VERSION with . replaced by _. For places where . has special meaning (some filesystems, RCS labels, etc...)

XS

Hashref of .xs files. MakeMaker will default this. e.g.

  {'name_of_file.xs' => 'name_of_file.c'}

The .c files will automatically be included in the list of files deleted by a make clean.

XSOPT

String of options to pass to xsubpp. This might include -C++ or -extern. Do not include typemaps here; the TYPEMAP parameter exists for that purpose.

XSPROTOARG

May be set to an empty string, which is identical to -prototypes, or -noprototypes. See the xsubpp documentation for details. MakeMaker defaults to the empty string.

XS_VERSION

Your version number for the .xs file of this package. This defaults to the value of the VERSION attribute.

Additional lowercase attributes

can be used to pass parameters to the methods which implement that part of the Makefile. Parameters are specified as a hash ref but are passed to the method as a hash.

clean
  {FILES => "*.xyz foo"}
depend
  {ANY_TARGET => ANY_DEPENDECY, ...}

(ANY_TARGET must not be given a double-colon rule by MakeMaker.)

dist
  {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
  SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
  ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }

If you specify COMPRESS, then SUFFIX should also be altered, as it is needed to tell make the target file of the compression. Setting DIST_CP to ln can be useful, if you need to preserve the timestamps on your files. DIST_CP can take the values 'cp', which copies the file, 'ln', which links the file, and 'best' which copies symbolic links and links the rest. Default is 'best'.

dynamic_lib
  {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
linkext
  {LINKTYPE => 'static', 'dynamic' or ''}

NB: Extensions that have nothing but *.pm files had to say

  {LINKTYPE => ''}

with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line can be deleted safely. MakeMaker recognizes when there's nothing to be linked.

macro
  {ANY_MACRO => ANY_VALUE, ...}
postamble

Anything put here will be passed to MY::postamble() if you have one.

realclean
  {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
test
  {TESTS => 't/*.t'}
tool_autosplit
  {MAXLEN => 8}

Overriding MakeMaker Methods

If you cannot achieve the desired Makefile behaviour by specifying attributes you may define private subroutines in the Makefile.PL. Each subroutine returns the text it wishes to have written to the Makefile. To override a section of the Makefile you can either say:

        sub MY::c_o { "new literal text" }

or you can edit the default by saying something like:

        package MY; # so that "SUPER" works right
        sub c_o {
            my $inherited = shift->SUPER::c_o(@_);
            $inherited =~ s/old text/new text/;
            $inherited;
        }

If you are running experiments with embedding perl as a library into other applications, you might find MakeMaker is not sufficient. You'd better have a look at ExtUtils::Embed which is a collection of utilities for embedding.

If you still need a different solution, try to develop another subroutine that fits your needs and submit the diffs to makemaker@perl.org

For a complete description of all MakeMaker methods see the ExtUtils::MM_Unix manpage.

Here is a simple example of how to add a new target to the generated Makefile:

    sub MY::postamble {
        return <<'MAKE_FRAG';
    $(MYEXTLIB): sdbm/Makefile
            cd sdbm && $(MAKE) all

    MAKE_FRAG
    }

The End Of Cargo Cult Programming

WriteMakefile() now does some basic sanity checks on its parameters to protect against typos and malformatted values. This means some things which happened to work in the past will now throw warnings and possibly produce internal errors.

Some of the most common mistakes:

MAN3PODS => ' '

This is commonly used to supress the creation of man pages. MAN3PODS takes a hash ref not a string, but the above worked by accident in old versions of MakeMaker.

The correct code is MAN3PODS => { }.

Hintsfile support

MakeMaker.pm uses the architecture specific information from Config.pm. In addition it evaluates architecture specific hints files in a hints/ directory. The hints files are expected to be named like their counterparts in PERL_SRC/hints, but with an .pl file name extension (eg. next_3_2.pl). They are simply evaled by MakeMaker within the WriteMakefile() subroutine, and can be used to execute commands as well as to include special variables. The rules which hintsfile is chosen are the same as in Configure.

The hintsfile is eval()ed immediately after the arguments given to WriteMakefile are stuffed into a hash reference $self but before this reference becomes blessed. So if you want to do the equivalent to override or create an attribute you would say something like

    $self->{LIBS} = ['-ldbm -lucb -lc'];

Distribution Support

For authors of extensions MakeMaker provides several Makefile targets. Most of the support comes from the ExtUtils::Manifest module, where additional documentation can be found.

make distcheck

reports which files are below the build directory but not in the MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for details)

make skipcheck

reports which files are skipped due to the entries in the MANIFEST.SKIP file (See ExtUtils::Manifest::skipcheck() for details)

make distclean

does a realclean first and then the distcheck. Note that this is not needed to build a new distribution as long as you are sure that the MANIFEST file is ok.

make manifest

rewrites the MANIFEST file, adding all remaining files found (See ExtUtils::Manifest::mkmanifest() for details)

make distdir

Copies all the files that are in the MANIFEST file to a newly created directory with the name $(DISTNAME)-$(VERSION). If that directory exists, it will be removed first.

Additionally, it will create a META.yml module meta-data file in the distdir and add this to the distdir's MANFIEST. You can shut this behavior off with the NO_META flag.

make disttest

Makes a distdir first, and runs a perl Makefile.PL, a make, and a make test in that directory.

make tardist

First does a distdir. Then a command $(PREOP) which defaults to a null command, followed by $(TOUNIX), which defaults to a null command under UNIX, and will convert files in distribution directory to UNIX format otherwise. Next it runs tar on that directory into a tarfile and deletes the directory. Finishes with a command $(POSTOP) which defaults to a null command.

make dist

Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.

make uutardist

Runs a tardist first and uuencodes the tarfile.

make shdist

First does a distdir. Then a command $(PREOP) which defaults to a null command. Next it runs shar on that directory into a sharfile and deletes the intermediate directory again. Finishes with a command $(POSTOP) which defaults to a null command. Note: For shdist to work properly a shar program that can handle directories is mandatory.

make zipdist

First does a distdir. Then a command $(PREOP) which defaults to a null command. Runs $(ZIP) $(ZIPFLAGS) on that directory into a zipfile. Then deletes that directory. Finishes with a command $(POSTOP) which defaults to a null command.

make ci

Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.

Customization of the dist targets can be done by specifying a hash reference to the dist attribute of the WriteMakefile call. The following parameters are recognized:

    CI           ('ci -u')
    COMPRESS     ('gzip --best')
    POSTOP       ('@ :')
    PREOP        ('@ :')
    TO_UNIX      (depends on the system)
    RCS_LABEL    ('rcs -q -Nv$(VERSION_SYM):')
    SHAR         ('shar')
    SUFFIX       ('.gz')
    TAR          ('tar')
    TARFLAGS     ('cvf')
    ZIP          ('zip')
    ZIPFLAGS     ('-r')

An example:

    WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })

Module Meta-Data

Long plaguing users of MakeMaker based modules has been the problem of getting basic information about the module out of the sources without running the Makefile.PL and doing a bunch of messy heuristics on the resulting Makefile. To this end a simple module meta-data file has been introduced, META.yml.

META.yml is a YAML document (see http://www.yaml.org) containing basic information about the module (name, version, prerequisites...) in an easy to read format. The format is developed and defined by the Module::Build developers (see http://module-build.sourceforge.net/META-spec.html)

MakeMaker will automatically generate a META.yml file for you and add it to your MANIFEST as part of the 'distdir' target (and thus the 'dist' target). This is intended to seamlessly and rapidly populate CPAN with module meta-data. If you wish to shut this feature off, set the NO_META WriteMakefile() flag to true.

Disabling an extension

If some events detected in Makefile.PL imply that there is no way to create the Module, but this is a normal state of things, then you can create a Makefile which does nothing, but succeeds on all the "usual" build targets. To do so, use

   ExtUtils::MakeMaker::WriteEmptyMakefile();

instead of WriteMakefile().

This may be useful if other modules expect this module to be built OK, as opposed to work OK (say, this system-dependent module builds in a subdirectory of some other distribution, or is listed as a dependency in a CPAN::Bundle, but the functionality is supported by different means on the current architecture).

Other Handy Functions

prompt
    my $value = prompt($message);
    my $value = prompt($message, $default);

The prompt() function provides an easy way to request user input used to write a makefile. It displays the $message as a prompt for input. If a $default is provided it will be used as a default. The function returns the $value selected by the user.

If prompt() detects that it is not running interactively and there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable is set to true, the $default will be used without prompting. This prevents automated processes from blocking on user input.

If no $default is provided an empty string will be used instead.

ENVIRONMENT

PERL_MM_OPT

Command line options used by MakeMaker->new(), and thus by WriteMakefile(). The string is split on whitespace, and the result is processed before any actual command line arguments are processed.

PERL_MM_USE_DEFAULT

If set to a true value then MakeMaker's prompt function will always return the default without waiting for user input.

PERL_CORE

Same as the PERL_CORE parameter. The parameter overrides this.

SEE ALSO

ExtUtils::MM_Unix, ExtUtils::Manifest ExtUtils::Install, ExtUtils::Embed

AUTHORS

Andy Dougherty doughera@lafayette.edu, Andreas König andreas.koenig@mind.de, Tim Bunce timb@cpan.org. VMS support by Charles Bailey bailey@newman.upenn.edu. OS/2 support by Ilya Zakharevich ilya@math.ohio-state.edu.

Currently maintained by Michael G Schwern schwern@pobox.com

Send patches and ideas to makemaker@perl.org.

Send bug reports via http://rt.cpan.org/. Please send your generated Makefile along with your report.

For more up-to-date information, see http://www.makemaker.org.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


ExtUtils::MakeMaker::Config - Wrapper around Config.pm

NAME

ExtUtils::MakeMaker::Config - Wrapper around Config.pm

SYNOPSIS

  use ExtUtils::MakeMaker::Config;
  print $Config{installbin};  # or whatever

DESCRIPTION

FOR INTERNAL USE ONLY

A very thin wrapper around Config.pm so MakeMaker is easier to test.


ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker

    • Module Installation
    • Philosophy and History
    • Module Writing
    • XS
  • PATCHING
  • AUTHOR
  • SEE ALSO

NAME

ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker

DESCRIPTION

FAQs, tricks and tips for ExtUtils::MakeMaker.

Module Installation

How do I keep from installing man pages?

Recent versions of MakeMaker will only install man pages on Unix like operating systems.

For an individual module:

        perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none

If you want to suppress man page installation for all modules you have to reconfigure Perl and tell it 'none' when it asks where to install man pages.

How do I use a module without installing it?

Two ways. One is to build the module normally...

        perl Makefile.PL
        make

...and then set the PERL5LIB environment variable to point at the blib/lib and blib/arch directories.

The other is to install the module in a temporary location.

        perl Makefile.PL PREFIX=~/tmp LIB=~/tmp/lib/perl

And then set PERL5LIB to ~/tmp/lib/perl. This works well when you have multiple modules to work with. It also ensures that the module goes through its full installation process which may modify it.

Philosophy and History

Why not just use <insert other build config tool here>?

Why did MakeMaker reinvent the build configuration wheel? Why not just use autoconf or automake or ppm or Ant or ...

There are many reasons, but the major one is cross-platform compatibility.

Perl is one of the most ported pieces of software ever. It works on operating systems I've never even heard of (see perlport for details). It needs a build tool that can work on all those platforms and with any wacky C compilers and linkers they might have.

No such build tool exists. Even make itself has wildly different dialects. So we have to build our own.

What is Module::Build and how does it relate to MakeMaker?

Module::Build is a project by Ken Williams to supplant MakeMaker. Its primary advantages are:

  • pure perl. no make, no shell commands
  • easier to customize
  • cleaner internals
  • less cruft

Module::Build is the official heir apparent to MakeMaker and we encourage people to work on M::B rather than spending time adding features to MakeMaker.

Module Writing

How do I keep my $VERSION up to date without resetting it manually?

Often you want to manually set the $VERSION in the main module distribution because this is the version that everybody sees on CPAN and maybe you want to customize it a bit. But for all the other modules in your dist, $VERSION is really just bookkeeping and all that's important is it goes up every time the module is changed. Doing this by hand is a pain and you often forget.

Simplest way to do it automatically is to use your version control system's revision number (you are using version control, right?).

In CVS, RCS and SVN you use $Revision$ (see the documentation of your version control system for details) writing it like so:

    $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)/g;

Every time the file is checked in the $Revision$ will be updated, updating your $VERSION.

In CVS version 1.9 is followed by 1.10. Since CPAN compares version numbers numerically we use a sprintf() to convert 1.9 to 1.009 and 1.10 to 1.010 which compare properly.

If branches are involved (ie. $Revision: 1.5.3.4$) its a little more complicated.

    # must be all on one line or MakeMaker will get confused.
    $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
What's this META.yml thing and how did it get in my MANIFEST?!

META.yml is a module meta-data file pioneered by Module::Build and automatically generated as part of the 'distdir' target (and thus 'dist'). See Module Meta-Data in the ExtUtils::MakeMaker manpage.

To shut off its generation, pass the NO_META flag to WriteMakefile().

XS

How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?

XS code is very sensitive to the module version number and will complain if the version number in your Perl module doesn't match. If you change your module's version # without reruning Makefile.PL the old version number will remain in the Makefile causing the XS code to be built with the wrong number.

To avoid this, you can force the Makefile to be rebuilt whenever you change the module containing the version number by adding this to your WriteMakefile() arguments.

    depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' }
How do I make two or more XS files coexist in the same directory?

Sometimes you need to have two and more XS files in the same package. One way to go is to put them into separate directories, but sometimes this is not the most suitable solution. The following technique allows you to put two (and more) XS files in the same directory.

Let's assume that we have a package Cool::Foo, which includes Cool::Foo and Cool::Bar modules each having a separate XS file. First we use the following Makefile.PL:

  use ExtUtils::MakeMaker;

  WriteMakefile(
      NAME              => 'Cool::Foo',
      VERSION_FROM      => 'Foo.pm',
      OBJECT              => q/$(O_FILES)/,
      # ... other attrs ...
  );

Notice the OBJECT attribute. MakeMaker generates the following variables in Makefile:

  # Handy lists of source code files:
  XS_FILES= Bar.xs \
        Foo.xs
  C_FILES = Bar.c \
        Foo.c
  O_FILES = Bar.o \
        Foo.o

Therefore we can use the O_FILES variable to tell MakeMaker to use these objects into the shared library.

That's pretty much it. Now write Foo.pm and Foo.xs, Bar.pm and Bar.xs, where Foo.pm bootstraps the shared library and Bar.pm simply loading Foo.pm.

The only issue left is to how to bootstrap Bar.xs. This is done from Foo.xs:

  MODULE = Cool::Foo PACKAGE = Cool::Foo
  BOOT:
  # boot the second XS file
  boot_Cool__Bar(aTHX_ cv);

If you have more than two files, this is the place where you should boot extra XS files from.

The following four files sum up all the details discussed so far.

  Foo.pm:
  -------
  package Cool::Foo;

  require DynaLoader;

  our @ISA = qw(DynaLoader);
  our $VERSION = '0.01';
  bootstrap Cool::Foo $VERSION;

  1;

  Bar.pm:
  -------
  package Cool::Bar;

  use Cool::Foo; # bootstraps Bar.xs

  1;

  Foo.xs:
  -------
  #include "EXTERN.h"
  #include "perl.h"
  #include "XSUB.h"
  MODULE = Cool::Foo  PACKAGE = Cool::Foo
  BOOT:
  # boot the second XS file
  boot_Cool__Bar(aTHX_ cv);

  MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
  void
  cool_foo_perl_rules()
      CODE:
      fprintf(stderr, "Cool::Foo says: Perl Rules\n");

  Bar.xs:
  -------
  #include "EXTERN.h"
  #include "perl.h"
  #include "XSUB.h"
  MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
  void
  cool_bar_perl_rules()
      CODE:
      fprintf(stderr, "Cool::Bar says: Perl Rules\n");

And of course a very basic test:

  test.pl:
  --------
  use Test;
  BEGIN { plan tests => 1 };
  use Cool::Foo;
  use Cool::Bar;
  Cool::Foo::perl_rules();
  Cool::Bar::perl_rules();
  ok 1;

This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.

PATCHING

If you have a question you'd like to see added to the FAQ (whether or not you have the answer) please send it to makemaker@perl.org.

AUTHOR

The denizens of makemaker@perl.org.

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker

    • The Mantra
    • The Layout
  • SEE ALSO

NAME

ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker

SYNOPSIS

    use ExtUtils::MakeMaker;

    WriteMakefile(
        NAME            => 'Your::Module',
        VERSION_FROM    => 'lib/Your/Module.pm'
    );

DESCRIPTION

This is a short tutorial on writing a simple module with MakeMaker. Its really not that hard.

The Mantra

MakeMaker modules are installed using this simple mantra

        perl Makefile.PL
        make
        make test
        make install

There are lots more commands and options, but the above will do it.

The Layout

The basic files in a module look something like this.

        Makefile.PL
        MANIFEST
        lib/Your/Module.pm

That's all that's strictly necessary. There's additional files you might want:

        lib/Your/Other/Module.pm
        t/some_test.t
        t/some_other_test.t
        Changes
        README
        INSTALL
        MANIFEST.SKIP
        bin/some_program
Makefile.PL

When you run Makefile.PL, it makes a Makefile. That's the whole point of MakeMaker. The Makefile.PL is a simple program which loads ExtUtils::MakeMaker and runs the WriteMakefile() function to generate a Makefile.

Here's an example of what you need for a simple module:

    use ExtUtils::MakeMaker;

    WriteMakefile(
        NAME            => 'Your::Module',
        VERSION_FROM    => 'lib/Your/Module.pm'
    );

NAME is the top-level namespace of your module. VERSION_FROM is the file which contains the $VERSION variable for the entire distribution. Typically this is the same as your top-level module.

MANIFEST

A simple listing of all the files in your distribution.

        Makefile.PL
        MANIFEST
        lib/Your/Module.pm

File paths in a MANIFEST always use Unix conventions (ie. /) even if you're not on Unix.

You can write this by hand or generate it with 'make manifest'.

See the ExtUtils::Manifest manpage for more details.

lib/

This is the directory where your .pm and .pod files you wish to have installed go. They are layed out according to namespace. So Foo::Bar is lib/Foo/Bar.pm.

t/

Tests for your modules go here. Each test filename ends with a .t. So t/foo.t/ 'make test' will run these tests. The directory is flat, you cannot, for example, have t/foo/bar.t run by 'make test'.

Tests are run from the top level of your distribution. So inside a test you would refer to ./lib to enter the lib directory, for example.

Changes

A log of changes you've made to this module. The layout is free-form. Here's an example:

    1.01 Fri Apr 11 00:21:25 PDT 2003
        - thing() does some stuff now
        - fixed the wiggy bug in withit()
    1.00 Mon Apr  7 00:57:15 PDT 2003
        - "Rain of Frogs" now supported
README

A short description of your module, what it does, why someone would use it and its limitations. CPAN automatically pulls your README file out of the archive and makes it available to CPAN users, it is the first thing they will read to decide if your module is right for them.

INSTALL

Instructions on how to install your module along with any dependencies. Suggested information to include here:

    any extra modules required for use
    the minimum version of Perl required
    if only works on certain operating systems
MANIFEST.SKIP

A file full of regular expressions to exclude when using 'make manifest' to generate the MANIFEST. These regular expressions are checked against each file path found in the distribution (so you're matching against "t/foo.t" not "foo.t").

Here's a sample:

    ~$          # ignore emacs and vim backup files
    .bak$       # ignore manual backups
    \#          # ignore CVS old revision files and emacs temp files

Since # can be used for comments, # must be escaped.

MakeMaker comes with a default MANIFEST.SKIP to avoid things like version control directories and backup files. Specifying your own will override this default.

bin/

SEE ALSO

the perlmodstyle manpage gives stylistic help writing a module.

the perlnewmod manpage gives more information about how to write a module.

There are modules to help you through the process of writing a module: the ExtUtils::ModuleMaker manpage, the Module::Install manpage, PAR


ExtUtils::MakeMaker::bytes - Version-agnostic bytes.pm

NAME

ExtUtils::MakeMaker::bytes - Version-agnostic bytes.pm

SYNOPSIS

  use just like bytes.pm

DESCRIPTION

bytes.pm was introduced with 5.6. This means any code which has 'use bytes' in it won't even compile on 5.5.X. Since bytes is a lexical pragma and must be used at compile time we can't simply wrap it in a BEGIN { eval 'use bytes' } block.

ExtUtils::MakeMaker::bytes is just a very thin wrapper around bytes which works just like it when bytes.pm exists and everywhere else it does nothing.


ExtUtils::MakeMaker::vmsish - Platform-agnostic vmsish.pm

NAME

ExtUtils::MakeMaker::vmsish - Platform-agnostic vmsish.pm

SYNOPSIS

  use just like vmsish.pm

DESCRIPTION

Until 5.8.0, vmsish.pm is only installed on VMS. This means any code which has 'use vmsish' in it won't even compile outside VMS. This makes ExtUtils::MM_VMS very hard to test.

ExtUtils::MakeMaker::vmsish is just a very thin wrapper around vmsish which works just like it on VMS and everywhere else it does nothing.


ExtUtils::Manifest - utilities to write and check a MANIFEST file

    • Functions
    • MANIFEST
    • MANIFEST.SKIP
    • EXPORT_OK
    • GLOBAL VARIABLES
  • DIAGNOSTICS
  • ENVIRONMENT
  • SEE ALSO
  • AUTHOR

NAME

ExtUtils::Manifest - utilities to write and check a MANIFEST file

SYNOPSIS

    use ExtUtils::Manifest qw(...funcs to import...);

    mkmanifest();

    my @missing_files    = manicheck;
    my @skipped          = skipcheck;
    my @extra_files      = filecheck;
    my($missing, $extra) = fullcheck;

    my $found    = manifind();

    my $manifest = maniread();

    manicopy($read,$target);

    maniadd({$file => $comment, ...});

DESCRIPTION

Functions

ExtUtils::Manifest exports no functions by default. The following are exported on request

mkmanifest
    mkmanifest();

Writes all files in and below the current directory to your MANIFEST. It works similar to

    find . > MANIFEST

All files that match any regular expression in a file MANIFEST.SKIP (if it exists) are ignored.

Any existing MANIFEST file will be saved as MANIFEST.bak. Lines from the old MANIFEST file is preserved, including any comments that are found in the existing MANIFEST file in the new one.

manifind
    my $found = manifind();

returns a hash reference. The keys of the hash are the files found below the current directory.

manicheck
    my @missing_files = manicheck();

checks if all the files within a MANIFEST in the current directory really do exist. If MANIFEST and the tree below the current directory are in sync it silently returns an empty list. Otherwise it returns a list of files which are listed in the MANIFEST but missing from the directory, and by default also outputs these names to STDERR.

filecheck
    my @extra_files = filecheck();

finds files below the current directory that are not mentioned in the MANIFEST file. An optional file MANIFEST.SKIP will be consulted. Any file matching a regular expression in such a file will not be reported as missing in the MANIFEST file. The list of any extraneous files found is returned, and by default also reported to STDERR.

fullcheck
    my($missing, $extra) = fullcheck();

does both a manicheck() and a filecheck(), returning then as two array refs.

skipcheck
    my @skipped = skipcheck();

lists all the files that are skipped due to your MANIFEST.SKIP file.

maniread
    my $manifest = maniread();
    my $manifest = maniread($manifest_file);

reads a named MANIFEST file (defaults to MANIFEST in the current directory) and returns a HASH reference with files being the keys and comments being the values of the HASH. Blank lines and lines which start with # in the MANIFEST file are discarded.

manicopy
    manicopy(\%src, $dest_dir);
    manicopy(\%src, $dest_dir, $how);

Copies the files that are the keys in %src to the $dest_dir. %src is typically returned by the maniread() function.

    manicopy( maniread(), $dest_dir );

This function is useful for producing a directory tree identical to the intended distribution tree.

$how can be used to specify a different methods of "copying". Valid values are cp, which actually copies the files, ln which creates hard links, and best which mostly links the files but copies any symbolic link to make a tree without any symbolic link. cp is the default.

maniadd
  maniadd({ $file => $comment, ...});

Adds an entry to an existing MANIFEST unless its already there.

$file will be normalized (ie. Unixified). UNIMPLEMENTED

MANIFEST

A list of files in the distribution, one file per line. The MANIFEST always uses Unix filepath conventions even if you're not on Unix. This means foo/bar style not foo\bar.

Anything between white space and an end of line within a MANIFEST file is considered to be a comment. Any line beginning with # is also a comment.

    # this a comment
    some/file
    some/other/file            comment about some/file

MANIFEST.SKIP

The file MANIFEST.SKIP may contain regular expressions of files that should be ignored by mkmanifest() and filecheck(). The regular expressions should appear one on each line. Blank lines and lines which start with # are skipped. Use \# if you need a regular expression to start with a #.

For example:

    # Version control files and dirs.
    \bRCS\b
    \bCVS\b
    ,v$
    \B\.svn\b
    # Makemaker generated files and dirs.
    ^MANIFEST\.
    ^Makefile$
    ^blib/
    ^MakeMaker-\d
    # Temp, old and emacs backup files.
    ~$
    \.old$
    ^#.*#$
    ^\.#

If no MANIFEST.SKIP file is found, a default set of skips will be used, similar to the example above. If you want nothing skipped, simply make an empty MANIFEST.SKIP file.

EXPORT_OK

&mkmanifest, &manicheck, &filecheck, &fullcheck, &maniread, and &manicopy are exportable.

GLOBAL VARIABLES

$ExtUtils::Manifest::MANIFEST defaults to MANIFEST. Changing it results in both a different MANIFEST and a different MANIFEST.SKIP file. This is useful if you want to maintain different distributions for different audiences (say a user version and a developer version including RCS).

$ExtUtils::Manifest::Quiet defaults to 0. If set to a true value, all functions act silently.

$ExtUtils::Manifest::Debug defaults to 0. If set to a true value, or if PERL_MM_MANIFEST_DEBUG is true, debugging output will be produced.

DIAGNOSTICS

All diagnostic output is sent to STDERR.

Not in MANIFEST: file

is reported if a file is found which is not in MANIFEST.

Skipping file

is reported if a file is skipped due to an entry in MANIFEST.SKIP.

No such file: file

is reported if a file mentioned in a MANIFEST file does not exist.

MANIFEST: $!

is reported if MANIFEST could not be opened.

Added to MANIFEST: file

is reported by mkmanifest() if $Verbose is set and a file is added to MANIFEST. $Verbose is set to 1 by default.

ENVIRONMENT

PERL_MM_MANIFEST_DEBUG

Turns on debugging

SEE ALSO

the ExtUtils::MakeMaker manpage which has handy targets for most of the functionality.

AUTHOR

Andreas Koenig andreas.koenig@anima.de

Currently maintained by Michael G Schwern schwern@pobox.com


writemain - write the C code for perlmain.c

  • SEE ALSO

NAME

ExtUtils::Miniperl, writemain - write the C code for perlmain.c

SYNOPSIS

use ExtUtils::Miniperl;

writemain(@directories);

DESCRIPTION

This whole module is written when perl itself is built from a script called minimod.PL. In case you want to patch it, please patch minimod.PL in the perl distribution instead.

writemain() takes an argument list of directories containing archive libraries that relate to perl modules and should be linked into a new perl binary. It writes to STDOUT a corresponding perlmain.c file that is a plain C file containing all the bootstrap code to make the modules associated with the libraries available from within perl.

The typical usage is from within a Makefile generated by ExtUtils::MakeMaker. So under normal circumstances you won't have to deal with this module directly.

SEE ALSO

the ExtUtils::MakeMaker manpage


ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader

NAME

ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader

SYNOPSIS

Mkbootstrap

DESCRIPTION

Mkbootstrap typically gets called from an extension Makefile.

There is no *.bs file supplied with the extension. Instead, there may be a *_BS file which has code for the special cases, like posix for berkeley db on the NeXT.

This file will get parsed, and produce a maybe empty @DynaLoader::dl_resolve_using array for the current architecture. That will be extended by $BSLOADLIBS, which was computed by ExtUtils::Liblist::ext(). If this array still is empty, we do nothing, else we write a .bs file with an @DynaLoader::dl_resolve_using array.

The *_BS file can put some code into the generated *.bs file by placing it in $bscode. This is a handy 'escape' mechanism that may prove useful in complex situations.

If @DynaLoader::dl_resolve_using contains -L* or -l* entries then Mkbootstrap will automatically add a dl_findfile() call to the generated *.bs file.


ExtUtils::Mksymlists - write linker options files for dynamic extension

  • AUTHOR
  • REVISION

NAME

ExtUtils::Mksymlists - write linker options files for dynamic extension

SYNOPSIS

    use ExtUtils::Mksymlists;
    Mksymlists({ NAME     => $name ,
                 DL_VARS  => [ $var1, $var2, $var3 ],
                 DL_FUNCS => { $pkg1 => [ $func1, $func2 ],
                               $pkg2 => [ $func3 ] });

DESCRIPTION

ExtUtils::Mksymlists produces files used by the linker under some OSs during the creation of shared libraries for dynamic extensions. It is normally called from a MakeMaker-generated Makefile when the extension is built. The linker option file is generated by calling the function Mksymlists, which is exported by default from ExtUtils::Mksymlists. It takes one argument, a list of key-value pairs, in which the following keys are recognized:

DLBASE

This item specifies the name by which the linker knows the extension, which may be different from the name of the extension itself (for instance, some linkers add an '_' to the name of the extension). If it is not specified, it is derived from the NAME attribute. It is presently used only by OS2 and Win32.

DL_FUNCS

This is identical to the DL_FUNCS attribute available via MakeMaker, from which it is usually taken. Its value is a reference to an associative array, in which each key is the name of a package, and each value is an a reference to an array of function names which should be exported by the extension. For instance, one might say DL_FUNCS => { Homer::Iliad => [ qw(trojans greeks) ], Homer::Odyssey =E<gt> [ qw(travellers family suitors) ] }. The function names should be identical to those in the XSUB code; Mksymlists will alter the names written to the linker option file to match the changes made by xsubpp. In addition, if none of the functions in a list begin with the string boot_, Mksymlists will add a bootstrap function for that package, just as xsubpp does. (If a boot_<pkg> function is present in the list, it is passed through unchanged.) If DL_FUNCS is not specified, it defaults to the bootstrap function for the extension specified in NAME.

DL_VARS

This is identical to the DL_VARS attribute available via MakeMaker, and, like DL_FUNCS, it is usually specified via MakeMaker. Its value is a reference to an array of variable names which should be exported by the extension.

FILE

This key can be used to specify the name of the linker option file (minus the OS-specific extension), if for some reason you do not want to use the default value, which is the last word of the NAME attribute (e.g. for Tk::Canvas, FILE defaults to Canvas).

FUNCLIST

This provides an alternate means to specify function names to be exported from the extension. Its value is a reference to an array of function names to be exported by the extension. These names are passed through unaltered to the linker options file. Specifying a value for the FUNCLIST attribute suppresses automatic generation of the bootstrap function for the package. To still create the bootstrap name you have to specify the package name in the DL_FUNCS hash:

    Mksymlists({ NAME     => $name ,
                 FUNCLIST => [ $func1, $func2 ],
                 DL_FUNCS => { $pkg => [] } });
IMPORTS

This attribute is used to specify names to be imported into the extension. It is currently only used by OS/2 and Win32.

NAME

This gives the name of the extension (e.g. Tk::Canvas) for which the linker option file will be produced.

When calling Mksymlists, one should always specify the NAME attribute. In most cases, this is all that's necessary. In the case of unusual extensions, however, the other attributes can be used to provide additional information to the linker.

AUTHOR

Charles Bailey <bailey@newman.upenn.edu>

REVISION

Last revised 14-Feb-1996, for Perl 5.002.


ExtUtils::Packlist - manage .packlist files

  • USAGE
  • FUNCTIONS
  • EXAMPLE
  • AUTHOR

NAME

ExtUtils::Packlist - manage .packlist files

SYNOPSIS

   use ExtUtils::Packlist;
   my ($pl) = ExtUtils::Packlist->new('.packlist');
   $pl->read('/an/old/.packlist');
   my @missing_files = $pl->validate();
   $pl->write('/a/new/.packlist');

   $pl->{'/some/file/name'}++;
      or
   $pl->{'/some/other/file/name'} = { type => 'file',
                                      from => '/some/file' };

DESCRIPTION

ExtUtils::Packlist provides a standard way to manage .packlist files. Functions are provided to read and write .packlist files. The original .packlist format is a simple list of absolute pathnames, one per line. In addition, this package supports an extended format, where as well as a filename each line may contain a list of attributes in the form of a space separated list of key=value pairs. This is used by the installperl script to differentiate between files and links, for example.

USAGE

The hash reference returned by the new() function can be used to examine and modify the contents of the .packlist. Items may be added/deleted from the .packlist by modifying the hash. If the value associated with a hash key is a scalar, the entry written to the .packlist by any subsequent write() will be a simple filename. If the value is a hash, the entry written will be the filename followed by the key=value pairs from the hash. Reading back the .packlist will recreate the original entries.

FUNCTIONS

new()

This takes an optional parameter, the name of a .packlist. If the file exists, it will be opened and the contents of the file will be read. The new() method returns a reference to a hash. This hash holds an entry for each line in the .packlist. In the case of old-style .packlists, the value associated with each key is undef. In the case of new-style .packlists, the value associated with each key is a hash containing the key=value pairs following the filename in the .packlist.

read()

This takes an optional parameter, the name of the .packlist to be read. If no file is specified, the .packlist specified to new() will be read. If the .packlist does not exist, Carp::croak will be called.

write()

This takes an optional parameter, the name of the .packlist to be written. If no file is specified, the .packlist specified to new() will be overwritten.

validate()

This checks that every file listed in the .packlist actually exists. If an argument which evaluates to true is given, any missing files will be removed from the internal hash. The return value is a list of the missing files, which will be empty if they all exist.

packlist_file()

This returns the name of the associated .packlist file

EXAMPLE

Here's modrm, a little utility to cleanly remove an installed module.

    #!/usr/local/bin/perl -w

    use strict;
    use IO::Dir;
    use ExtUtils::Packlist;
    use ExtUtils::Installed;

    sub emptydir($) {
        my ($dir) = @_;
        my $dh = IO::Dir->new($dir) || return(0);
        my @count = $dh->read();
        $dh->close();
        return(@count == 2 ? 1 : 0);
    }

    # Find all the installed packages
    print("Finding all installed modules...\n");
    my $installed = ExtUtils::Installed->new();

    foreach my $module (grep(!/^Perl$/, $installed->modules())) {
       my $version = $installed->version($module) || "???";
       print("Found module $module Version $version\n");
       print("Do you want to delete $module? [n] ");
       my $r = <STDIN>; chomp($r);
       if ($r && $r =~ /^y/i) {
          # Remove all the files
          foreach my $file (sort($installed->files($module))) {
             print("rm $file\n");
             unlink($file);
          }
          my $pf = $installed->packlist($module)->packlist_file();
          print("rm $pf\n");
          unlink($pf);
          foreach my $dir (sort($installed->directory_tree($module))) {
             if (emptydir($dir)) {
                print("rmdir $dir\n");
                rmdir($dir);
             }
          }
       }
    }

AUTHOR

Alan Burlison <Alan.Burlison@uk.sun.com>


ExtUtils::testlib - add blib/* directories to @INC

NAME

ExtUtils::testlib - add blib/* directories to @INC

SYNOPSIS

  use ExtUtils::testlib;

DESCRIPTION

After an extension has been built and before it is installed it may be desirable to test it bypassing make test. By adding

    use ExtUtils::testlib;

to a test program the intermediate directories used by make are added to @INC.


Fatal - replace functions with equivalents which succeed or die

  • AUTHOR

NAME

Fatal - replace functions with equivalents which succeed or die

SYNOPSIS

    use Fatal qw(open close);

    sub juggle { . . . }
    import Fatal 'juggle';

DESCRIPTION

Fatal provides a way to conveniently replace functions which normally return a false value when they fail with equivalents which raise exceptions if they are not successful. This lets you use these functions without having to test their return values explicitly on each call. Exceptions can be caught using eval{}. See the perlfunc manpage and the perlvar manpage for details.

The do-or-die equivalents are set up simply by calling Fatal's import routine, passing it the names of the functions to be replaced. You may wrap both user-defined functions and overridable CORE operators (except exec, system which cannot be expressed via prototypes) in this way.

If the symbol :void appears in the import list, then functions named later in that import list raise an exception only when these are called in void context--that is, when their return values are ignored. For example

        use Fatal qw/:void open close/;

        # properly checked, so no exception raised on error
        if(open(FH, "< /bogotic") {
                warn "bogo file, dude: $!";
        }

        # not checked, so error raises an exception
        close FH;

AUTHOR

Lionel.Cons@cern.ch

prototype updates by Ilya Zakharevich ilya@math.ohio-state.edu


Fcntl - load the C Fcntl.h defines

  • NOTE
  • EXPORTED SYMBOLS

NAME

Fcntl - load the C Fcntl.h defines

SYNOPSIS

    use Fcntl;
    use Fcntl qw(:DEFAULT :flock);

DESCRIPTION

This module is just a translation of the C fcntl.h file. Unlike the old mechanism of requiring a translated fcntl.ph file, this uses the h2xs program (see the Perl source distribution) and your native C compiler. This means that it has a far more likely chance of getting the numbers right.

NOTE

Only #define symbols get translated; you must still correctly pack up your own arguments to pass as args for locking functions, etc.

EXPORTED SYMBOLS

By default your system's F_* and O_* constants (eg, F_DUPFD and O_CREAT) and the FD_CLOEXEC constant are exported into your namespace.

You can request that the flock() constants (LOCK_SH, LOCK_EX, LOCK_NB and LOCK_UN) be provided by using the tag :flock. See the Exporter manpage.

You can request that the old constants (FAPPEND, FASYNC, FCREAT, FDEFER, FEXCL, FNDELAY, FNONBLOCK, FSYNC, FTRUNC) be provided for compatibility reasons by using the tag :Fcompat. For new applications the newer versions of these constants are suggested (O_APPEND, O_ASYNC, O_CREAT, O_DEFER, O_EXCL, O_NDELAY, O_NONBLOCK, O_SYNC, O_TRUNC).

For ease of use also the SEEK_* constants (for seek() and sysseek(), e.g. SEEK_END) and the S_I* constants (for chmod() and stat()) are available for import. They can be imported either separately or using the tags :seek and :mode.

Please refer to your native fcntl(2), open(2), fseek(3), lseek(2) (equal to Perl's seek() and sysseek(), respectively), and chmod(2) documentation to see what constants are implemented in your system.

See the perlopentut manpage to learn about the uses of the O_* constants with sysopen().

See seek in the perlfunc manpage and sysseek in the perlfunc manpage about the SEEK_* constants.

See stat in the perlfunc manpage about the S_I* constants.


File::Basename - Parse file paths into directory, filename and suffix.

  • SEE ALSO

NAME

File::Basename - Parse file paths into directory, filename and suffix.

SYNOPSIS

    use File::Basename;

    ($name,$path,$suffix) = fileparse($fullname,@suffixlist);
    $name = fileparse($fullname,@suffixlist);

    $basename = basename($fullname,@suffixlist);
    $dirname  = dirname($fullname);

DESCRIPTION

These routines allow you to parse file paths into their directory, filename and suffix.

NOTE: dirname() and basename() emulate the behaviours, and quirks, of the shell and C functions of the same name. See each function's documentation for details. If your concern is just parsing paths it is safer to use the File::Spec manpage's splitpath() and splitdir() methods.

It is guaranteed that

    # Where $path_separator is / for Unix, \ for Windows, etc...
    dirname($path) . $path_separator . basename($path);

is equivalent to the original path for all systems but VMS.

fileparse
    my($filename, $directories, $suffix) = fileparse($path);
    my($filename, $directories, $suffix) = fileparse($path, @suffixes);
    my $filename                         = fileparse($path, @suffixes);

The fileparse() routine divides a file path into its $directories, $filename and (optionally) the filename $suffix.

$directories contains everything up to and including the last directory separator in the $path including the volume (if applicable). The remainder of the $path is the $filename.

     # On Unix returns ("baz", "/foo/bar/", "")
     fileparse("/foo/bar/baz");

     # On Windows returns ("baz", "C:\foo\bar\", "")
     fileparse("C:\foo\bar\baz");

     # On Unix returns ("", "/foo/bar/baz/", "")
     fileparse("/foo/bar/baz/");

If @suffixes are given each element is a pattern (either a string or a qr//) matched against the end of the $filename. The matching portion is removed and becomes the $suffix.

     # On Unix returns ("baz", "/foo/bar", ".txt")
     fileparse("/foo/bar/baz", qr/\.[^.]*/);

If type is non-Unix (see fileparse_set_fstype()) then the pattern matching for suffix removal is performed case-insensitively, since those systems are not case-sensitive when opening existing files.

You are guaranteed that $directories . $filename . $suffix will denote the same location as the original $path.

basename
    my $filename = basename($path);
    my $filename = basename($path, @suffixes);

This function is provided for compatibility with the Unix shell command basename(1). It does NOT always return the file name portion of a path as you might expect. To be safe, if you want the file name portion of a path use fileparse().

basename() returns the last level of a filepath even if the last level is clearly directory. In effect, it is acting like pop() for paths. This differs from fileparse()'s behaviour.

    # Both return "bar"
    basename("/foo/bar");
    basename("/foo/bar/");

@suffixes work as in fileparse() except all regex metacharacters are quoted.

    # These two function calls are equivalent.
    my $filename = basename("/foo/bar/baz.txt",  ".txt");
    my $filename = fileparse("/foo/bar/baz.txt", qr/\Q.txt\E/);

Also note that in order to be compatible with the shell command, basename() does not strip off a suffix if it is identical to the remaining characters in the filename.

dirname

This function is provided for compatibility with the Unix shell command dirname(1) and has inherited some of its quirks. In spite of its name it does NOT always return the directory name as you might expect. To be safe, if you want the directory name of a path use fileparse().

Only on VMS (where there is no ambiguity between the file and directory portions of a path) and AmigaOS (possibly due to an implementation quirk in this module) does dirname() work like fileparse($path), returning just the $directories.

    # On VMS and AmigaOS
    my $directories = dirname($path);

When using Unix or MSDOS syntax this emulates the dirname(1) shell function which is subtly different from how fileparse() works. It returns all but the last level of a file path even if the last level is clearly a directory. In effect, it is not returning the directory portion but simply the path one level up acting like chop() for file paths.

Also unlike fileparse(), dirname() does not include a trailing slash on its returned path.

    # returns /foo/bar.  fileparse() would return /foo/bar/
    dirname("/foo/bar/baz");

    # also returns /foo/bar despite the fact that baz is clearly a
    # directory.  fileparse() would return /foo/bar/baz/
    dirname("/foo/bar/baz/");

    # returns '.'.  fileparse() would return 'foo/'
    dirname("foo/");

Under VMS, if there is no directory information in the $path, then the current default device and directory is used.

fileparse_set_fstype
  my $type = fileparse_set_fstype();
  my $previous_type = fileparse_set_fstype($type);

Normally File::Basename will assume a file path type native to your current operating system (ie. /foo/bar style on Unix, \foo\bar on Windows, etc...). With this function you can override that assumption.

Valid $types are "MacOS", "VMS", "AmigaOS", "OS2", "RISCOS", "MSWin32", "DOS" (also "MSDOS" for backwards bug compatibility), "Epoc" and "Unix" (all case-insensitive). If an unrecognized $type is given "Unix" will be assumed.

If you've selected VMS syntax, and the file specification you pass to one of these routines contains a "/", they assume you are using Unix emulation and apply the Unix syntax rules instead, for that function call only.

SEE ALSO

dirname(1), basename(1), the File::Spec manpage


validate - run many filetest checks on a tree

  • AUTHOR
  • HISTORY

NAME

validate - run many filetest checks on a tree

SYNOPSIS

    use File::CheckTree;

    $num_warnings = validate( q{
        /vmunix                 -e || die
        /boot                   -e || die
        /bin                    cd
            csh                 -ex
            csh                 !-ug
            sh                  -ex
            sh                  !-ug
        /usr                    -d || warn "What happened to $file?\n"
    });

DESCRIPTION

The validate() routine takes a single multiline string consisting of directives, each containing a filename plus a file test to try on it. (The file test may also be a "cd", causing subsequent relative filenames to be interpreted relative to that directory.) After the file test you may put || die to make it a fatal error if the file test fails. The default is || warn. The file test may optionally have a "!' prepended to test for the opposite condition. If you do a cd and then list some relative filenames, you may want to indent them slightly for readability. If you supply your own die() or warn() message, you can use $file to interpolate the filename.

Filetests may be bunched: "-rwx" tests for all of -r, -w, and -x. Only the first failed test of the bunch will produce a warning.

The routine returns the number of warnings issued.

AUTHOR

File::CheckTree was derived from lib/validate.pl which was written by Larry Wall. Revised by Paul Grassie <grassie@perl.com> in 2002.

HISTORY

File::CheckTree used to not display fatal error messages. It used to count only those warnings produced by a generic || warn (and not those in which the user supplied the message). In addition, the validate() routine would leave the user program in whatever directory was last entered through the use of "cd" directives. These bugs were fixed during the development of perl 5.8. The first fixed version of File::CheckTree was 4.2.


File::Compare - Compare files or filehandles

  • RETURN
  • AUTHOR

NAME

File::Compare - Compare files or filehandles

SYNOPSIS

        use File::Compare;

        if (compare("file1","file2") == 0) {
            print "They're equal\n";
        }

DESCRIPTION

The File::Compare::compare function compares the contents of two sources, each of which can be a file or a file handle. It is exported from File::Compare by default.

File::Compare::cmp is a synonym for File::Compare::compare. It is exported from File::Compare only by request.

File::Compare::compare_text does a line by line comparison of the two files. It stops as soon as a difference is detected. compare_text() accepts an optional third argument: This must be a CODE reference to a line comparison function, which returns 0 when both lines are considered equal. For example:

    compare_text($file1, $file2)

is basically equivalent to

    compare_text($file1, $file2, sub {$_[0] ne $_[1]} )

RETURN

File::Compare::compare and its sibling functions return 0 if the files are equal, 1 if the files are unequal, or -1 if an error was encountered.

AUTHOR

File::Compare was written by Nick Ing-Simmons. Its original documentation was written by Chip Salzenberg.


File::Copy - Copy files or filehandles

    • Special behaviour if syscopy is defined (OS/2, VMS and Win32)
  • RETURN
  • NOTES
  • AUTHOR

NAME

File::Copy - Copy files or filehandles

SYNOPSIS

        use File::Copy;

        copy("file1","file2") or die "Copy failed: $!";
        copy("Copy.pm",\*STDOUT);
        move("/dev1/fileA","/dev2/fileB");

        use File::Copy "cp";

        $n = FileHandle->new("/a/file","r");
        cp($n,"x");

DESCRIPTION

The File::Copy module provides two basic functions, copy and move, which are useful for getting the contents of a file from one place to another.

  • The copy function takes two parameters: a file to copy from and a file to copy to. Either argument may be a string, a FileHandle reference or a FileHandle glob. Obviously, if the first argument is a filehandle of some sort, it will be read from, and if it is a file name it will be opened for reading. Likewise, the second argument will be written to (and created if need be). Trying to copy a file on top of itself is a fatal error.

    Note that passing in files as handles instead of names may lead to loss of information on some operating systems; it is recommended that you use file names whenever possible. Files are opened in binary mode where applicable. To get a consistent behaviour when copying from a filehandle to a file, use binmode on the filehandle.

    An optional third parameter can be used to specify the buffer size used for copying. This is the number of bytes from the first file, that wil be held in memory at any given time, before being written to the second file. The default buffer size depends upon the file, but will generally be the whole file (up to 2Mb), or 1k for filehandles that do not reference files (eg. sockets).

    You may use the syntax use File::Copy "cp" to get at the "cp" alias for this function. The syntax is exactly the same.

  • The move function also takes two parameters: the current name and the intended name of the file to be moved. If the destination already exists and is a directory, and the source is not a directory, then the source file will be renamed into the directory specified by the destination.

    If possible, move() will simply rename the file. Otherwise, it copies the file to the new location and deletes the original. If an error occurs during this copy-and-delete process, you may be left with a (possibly partial) copy of the file under the destination name.

    You may use the "mv" alias for this function in the same way that you may use the "cp" alias for copy.

File::Copy also provides the syscopy routine, which copies the file specified in the first parameter to the file specified in the second parameter, preserving OS-specific attributes and file structure. For Unix systems, this is equivalent to the simple copy routine, which doesn't preserve OS-specific attributes. For VMS systems, this calls the rmscopy routine (see below). For OS/2 systems, this calls the syscopy XSUB directly. For Win32 systems, this calls Win32::CopyFile.

On Mac OS (Classic), syscopy calls Mac::MoreFiles::FSpFileCopy, if available.

Special behaviour if syscopy is defined (OS/2, VMS and Win32)

If both arguments to copy are not file handles, then copy will perform a "system copy" of the input file to a new output file, in order to preserve file attributes, indexed file structure, etc. The buffer size parameter is ignored. If either argument to copy is a handle to an opened file, then data is copied using Perl operators, and no effort is made to preserve file attributes or record structure.

The system copy routine may also be called directly under VMS and OS/2 as File::Copy::syscopy (or under VMS as File::Copy::rmscopy, which is the routine that does the actual work for syscopy).

rmscopy($from,$to[,$date_flag])

The first and second arguments may be strings, typeglobs, typeglob references, or objects inheriting from IO::Handle; they are used in all cases to obtain the filespec of the input and output files, respectively. The name and type of the input file are used as defaults for the output file, if necessary.

A new version of the output file is always created, which inherits the structure and RMS attributes of the input file, except for owner and protections (and possibly timestamps; see below). All data from the input file is copied to the output file; if either of the first two parameters to rmscopy is a file handle, its position is unchanged. (Note that this means a file handle pointing to the output file will be associated with an old version of that file after rmscopy returns, not the newly created version.)

The third parameter is an integer flag, which tells rmscopy how to handle timestamps. If it is < 0, none of the input file's timestamps are propagated to the output file. If it is > 0, then it is interpreted as a bitmask: if bit 0 (the LSB) is set, then timestamps other than the revision date are propagated; if bit 1 is set, the revision date is propagated. If the third parameter to rmscopy is 0, then it behaves much like the DCL COPY command: if the name or type of the output file was explicitly specified, then no timestamps are propagated, but if they were taken implicitly from the input filespec, then all timestamps other than the revision date are propagated. If this parameter is not supplied, it defaults to 0.

Like copy, rmscopy returns 1 on success. If an error occurs, it sets $!, deletes the output file, and returns 0.

RETURN

All functions return 1 on success, 0 on failure. $! will be set if an error was encountered.

NOTES

  • On Mac OS (Classic), the path separator is ':', not '/', and the current directory is denoted as ':', not '.'. You should be careful about specifying relative pathnames. While a full path always begins with a volume name, a relative pathname should always begin with a ':'. If specifying a volume name only, a trailing ':' is required.

    E.g.

      copy("file1", "tmp");        # creates the file 'tmp' in the current directory
  copy("file1", ":tmp:");      # creates :tmp:file1
  copy("file1", ":tmp");       # same as above
  copy("file1", "tmp");        # same as above, if 'tmp' is a directory (but don't do
                               # that, since it may cause confusion, see example #1)
  copy("file1", "tmp:file1");  # error, since 'tmp:' is not a volume
  copy("file1", ":tmp:file1"); # ok, partial path
  copy("file1", "DataHD:");    # creates DataHD:file1

  move("MacintoshHD:fileA", "DataHD:fileB"); # moves (don't copies) files from one
                                             # volume to another

AUTHOR

File::Copy was written by Aaron Sherman <ajs@ajs.com> in 1995, and updated by Charles Bailey <bailey@newman.upenn.edu> in 1996.


File::CounterFile - Persistent counter class

  • COPYRIGHT
  • AUTHOR

NAME

File::CounterFile - Persistent counter class

SYNOPSIS

 use File::CounterFile;
 $c = File::CounterFile->new("COUNTER", "aa00");

 $id = $c->inc;
 open(F, ">F$id");

DESCRIPTION

This module implements a persistent counter class. Each counter is represented by a separate file in the file system. File locking is applied, so multiple processes can attempt to access a counter simultaneously without risk of counter destruction.

You give the file name as the first parameter to the object constructor (new). The file is created if it does not exist.

If the file name does not start with "/" or ".", then it is interpreted as a file relative to $File::CounterFile::DEFAULT_DIR. The default value for this variable is initialized from the environment variable TMPDIR, or /usr/tmp if no environment variable is defined. You may want to assign a different value to this variable before creating counters.

If you pass a second parameter to the constructor, it sets the initial value for a new counter. This parameter only takes effect when the file is created (i.e. it does not exist before the call).

When you call the inc() method, you increment the counter value by one. When you call dec(), the counter value is decremented. In both cases the new value is returned. The dec() method only works for numerical counters (digits only).

You can peek at the value of the counter (without incrementing it) by using the value() method.

The counter can be locked and unlocked with the lock() and unlock() methods. Incrementing and value retrieval are faster when the counter is locked, because we do not have to update the counter file all the time. You can query whether the counter is locked with the locked() method.

There is also an operator overloading interface to the File::CounterFile object. This means that you can use the ++ operator for incrementing and the -- operator for decrementing the counter, and you can interpolate counters directly into strings.

COPYRIGHT

Copyright (c) 1995-1998,2002,2003 Gisle Aas. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Gisle Aas <gisle@aas.no>


File::DosGlob - DOS like globbing and then some

  • NOTES
  • EXPORTS (by request only)
  • BUGS
  • AUTHOR
  • HISTORY
  • SEE ALSO

NAME

File::DosGlob - DOS like globbing and then some

SYNOPSIS

    require 5.004;

    # override CORE::glob in current package
    use File::DosGlob 'glob';

    # override CORE::glob in ALL packages (use with extreme caution!)
    use File::DosGlob 'GLOBAL_glob';

    @perlfiles = glob  "..\\pe?l/*.p?";
    print <..\\pe?l/*.p?>;

    # from the command line (overrides only in main::)
    > perl -MFile::DosGlob=glob -e "print <../pe*/*p?>"

DESCRIPTION

A module that implements DOS-like globbing with a few enhancements. It is largely compatible with perlglob.exe (the M$ setargv.obj version) in all but one respect--it understands wildcards in directory components.

For example, <..\\l*b\\file/*glob.p?> will work as expected (in that it will find something like '..\lib\File/DosGlob.pm' alright). Note that all path components are case-insensitive, and that backslashes and forward slashes are both accepted, and preserved. You may have to double the backslashes if you are putting them in literally, due to double-quotish parsing of the pattern by perl.

Spaces in the argument delimit distinct patterns, so glob('*.exe *.dll') globs all filenames that end in .exe or .dll. If you want to put in literal spaces in the glob pattern, you can escape them with either double quotes, or backslashes. e.g. glob('c:/"Program Files"/*/*.dll'), or glob('c:/Program\ Files/*/*.dll'). The argument is tokenized using Text::ParseWords::parse_line(), so see the Text::ParseWords manpage for details of the quoting rules used.

Extending it to csh patterns is left as an exercise to the reader.

NOTES

  • Mac OS (Classic) users should note a few differences. The specification of pathnames in glob patterns adheres to the usual Mac OS conventions: The path separator is a colon ':', not a slash '/' or backslash '\'. A full path always begins with a volume name. A relative pathname on Mac OS must always begin with a ':', except when specifying a file or directory name in the current working directory, where the leading colon is optional. If specifying a volume name only, a trailing ':' is required. Due to these rules, a glob like <*:> will find all mounted volumes, while a glob like <*> or <:*> will find all files and directories in the current directory.

    Note that updirs in the glob pattern are resolved before the matching begins, i.e. a pattern like "*HD:t?p::a*" will be matched as "*HD:a*". Note also, that a single trailing ':' in the pattern is ignored (unless it's a volume name pattern like "*HD:"), i.e. a glob like <:*:> will find both directories and files (and not, as one might expect, only directories).

    The metachars '*', '?' and the escape char '\' are valid characters in volume, directory and file names on Mac OS. Hence, if you want to match a '*', '?' or '\' literally, you have to escape these characters. Due to perl's quoting rules, things may get a bit complicated, when you want to match a string like '\*' literally, or when you want to match '\' literally, but treat the immediately following character '*' as metachar. So, here's a rule of thumb (applies to both single- and double-quoted strings): escape each '*' or '?' or '\' with a backslash, if you want to treat them literally, and then double each backslash and your are done. E.g.

    - Match '\*' literally

       escape both '\' and '*'  : '\\\*'
   double the backslashes   : '\\\\\\*'

    (Internally, the glob routine sees a '\\\*', which means that both '\' and '*' are escaped.)

    - Match '\' literally, treat '*' as metachar

       escape '\' but not '*'   : '\\*'
   double the backslashes   : '\\\\*'

    (Internally, the glob routine sees a '\\*', which means that '\' is escaped and '*' is not.)

    Note that you also have to quote literal spaces in the glob pattern, as described above.

EXPORTS (by request only)

glob()

BUGS

Should probably be built into the core, and needs to stop pandering to DOS habits. Needs a dose of optimizium too.

AUTHOR

Gurusamy Sarathy <gsar@activestate.com>

HISTORY

  • Support for globally overriding glob() (GSAR 3-JUN-98)

  • Scalar context, independent iterator context fixes (GSAR 15-SEP-97)

  • A few dir-vs-file optimizations result in glob importation being 10 times faster than using perlglob.exe, and using perlglob.bat is only twice as slow as perlglob.exe (GSAR 28-MAY-97)

  • Several cleanups prompted by lack of compatible perlglob.exe under Borland (GSAR 27-MAY-97)

  • Initial version (GSAR 20-FEB-97)

SEE ALSO

perl

perlglob.bat

Text::ParseWords


File::Find - Traverse a directory tree.

    • %options
    • The wanted function
  • WARNINGS
  • CAVEAT
  • NOTES
  • BUGS AND CAVEATS
  • HISTORY

NAME

File::Find - Traverse a directory tree.

SYNOPSIS

    use File::Find;
    find(\&wanted, @directories_to_search);
    sub wanted { ... }

    use File::Find;
    finddepth(\&wanted, @directories_to_search);
    sub wanted { ... }

    use File::Find;
    find({ wanted => \&process, follow => 1 }, '.');

DESCRIPTION

These are functions for searching through directory trees doing work on each file found similar to the Unix find command. File::Find exports two functions, find and finddepth. They work similarly but have subtle differences.

find
  find(\&wanted,  @directories);
  find(\%options, @directories);

find() does a depth-first search over the given @directories in the order they are given. For each file or directory found, it calls the &wanted subroutine. (See below for details on how to use the &wanted function). Additionally, for each directory found, it will chdir() into that directory and continue the search, invoking the &wanted function on each file or subdirectory in the directory.

finddepth
  finddepth(\&wanted,  @directories);
  finddepth(\%options, @directories);

finddepth() works just like find() except that is invokes the &wanted function for a directory after invoking it for the directory's contents. It does a postorder traversal instead of a preorder traversal, working from the bottom of the directory tree up where find() works from the top of the tree down.

%options

The first argument to find() is either a code reference to your &wanted function, or a hash reference describing the operations to be performed for each file. The code reference is described in The wanted function below.

Here are the possible keys for the hash:

wanted

The value should be a code reference. This code reference is described in The wanted function below.

bydepth

Reports the name of a directory only AFTER all its entries have been reported. Entry point finddepth() is a shortcut for specifying <{ bydepth = 1 }>> in the first argument of find().

preprocess

The value should be a code reference. This code reference is used to preprocess the current directory. The name of the currently processed directory is in $File::Find::dir. Your preprocessing function is called after readdir(), but before the loop that calls the wanted() function. It is called with a list of strings (actually file/directory names) and is expected to return a list of strings. The code can be used to sort the file/directory names alphabetically, numerically, or to filter out directory entries based on their name alone. When follow or follow_fast are in effect, preprocess is a no-op.

postprocess

The value should be a code reference. It is invoked just before leaving the currently processed directory. It is called in void context with no arguments. The name of the current directory is in $File::Find::dir. This hook is handy for summarizing a directory, such as calculating its disk usage. When follow or follow_fast are in effect, postprocess is a no-op.

follow

Causes symbolic links to be followed. Since directory trees with symbolic links (followed) may contain files more than once and may even have cycles, a hash has to be built up with an entry for each file. This might be expensive both in space and time for a large directory tree. See follow_fast and follow_skip below. If either follow or follow_fast is in effect:

  • It is guaranteed that an lstat has been called before the user's wanted() function is called. This enables fast file checks involving _. Note that this guarantee no longer holds if follow or follow_fast are not set.

  • There is a variable $File::Find::fullname which holds the absolute pathname of the file with all symbolic links resolved. If the link is a dangling symbolic link, then fullname will be set to undef.

This is a no-op on Win32.

follow_fast

This is similar to follow except that it may report some files more than once. It does detect cycles, however. Since only symbolic links have to be hashed, this is much cheaper both in space and time. If processing a file more than once (by the user's wanted() function) is worse than just taking time, the option follow should be used.

This is also a no-op on Win32.

follow_skip

follow_skip==1, which is the default, causes all files which are neither directories nor symbolic links to be ignored if they are about to be processed a second time. If a directory or a symbolic link are about to be processed a second time, File::Find dies.

follow_skip==0 causes File::Find to die if any file is about to be processed a second time.

follow_skip==2 causes File::Find to ignore any duplicate files and directories but to proceed normally otherwise.

dangling_symlinks

If true and a code reference, will be called with the symbolic link name and the directory it lives in as arguments. Otherwise, if true and warnings are on, warning "symbolic_link_name is a dangling symbolic link\n" will be issued. If false, the dangling symbolic link will be silently ignored.

no_chdir

Does not chdir() to each directory as it recurses. The wanted() function will need to be aware of this, of course. In this case, $_ will be the same as $File::Find::name.

untaint

If find is used in taint-mode (-T command line switch or if EUID != UID or if EGID != GID) then internally directory names have to be untainted before they can be chdir'ed to. Therefore they are checked against a regular expression untaint_pattern. Note that all names passed to the user's wanted() function are still tainted. If this option is used while not in taint-mode, untaint is a no-op.

untaint_pattern

See above. This should be set using the qr quoting operator. The default is set to qr|^([-+@\w./]+)$|. Note that the parentheses are vital.

untaint_skip

If set, a directory which fails the untaint_pattern is skipped, including all its sub-directories. The default is to 'die' in such a case.

The wanted function

The wanted() function does whatever verifications you want on each file and directory. Note that despite its name, the wanted() function is a generic callback function, and does not tell File::Find if a file is "wanted" or not. In fact, its return value is ignored.

The wanted function takes no arguments but rather does its work through a collection of variables.

$File::Find::dir is the current directory name,
$_ is the current filename within that directory
$File::Find::name is the complete pathname to the file.

Don't modify these variables.

For example, when examining the file /some/path/foo.ext you will have:

    $File::Find::dir  = /some/path/
    $_                = foo.ext
    $File::Find::name = /some/path/foo.ext

You are chdir()'d to $File::Find::dir when the function is called, unless no_chdir was specified. Note that when changing to directories is in effect the root directory (/) is a somewhat special case inasmuch as the concatenation of $File::Find::dir, '/' and $_ is not literally equal to $File::Find::name. The table below summarizes all variants:

              $File::Find::name  $File::Find::dir  $_
 default      /                  /                 .
 no_chdir=>0  /etc               /                 etc
              /etc/x             /etc              x
 no_chdir=>1  /                  /                 /
              /etc               /                 /etc
              /etc/x             /etc              /etc/x

When <follow> or <follow_fast> are in effect, there is also a $File::Find::fullname. The function may set $File::Find::prune to prune the tree unless bydepth was specified. Unless follow or follow_fast is specified, for compatibility reasons (find.pl, find2perl) there are in addition the following globals available: $File::Find::topdir, $File::Find::topdev, $File::Find::topino, $File::Find::topmode and $File::Find::topnlink.

This library is useful for the find2perl tool, which when fed,

    find2perl / -name .nfs\* -mtime +7 \
        -exec rm -f {} \; -o -fstype nfs -prune

produces something like:

    sub wanted {
        /^\.nfs.*\z/s &&
        (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
        int(-M _) > 7 &&
        unlink($_)
        ||
        ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
        $dev < 0 &&
        ($File::Find::prune = 1);
    }

Notice the _ in the above int(-M _): the _ is a magical filehandle that caches the information from the preceding stat(), lstat(), or filetest.

Here's another interesting wanted function. It will find all symbolic links that don't resolve:

    sub wanted {
         -l && !-e && print "bogus link: $File::Find::name\n";
    }

See also the script pfind on CPAN for a nice application of this module.

WARNINGS

If you run your program with the -w switch, or if you use the warnings pragma, File::Find will report warnings for several weird situations. You can disable these warnings by putting the statement

    no warnings 'File::Find';

in the appropriate scope. See the perllexwarn manpage for more info about lexical warnings.

CAVEAT

$dont_use_nlink

You can set the variable $File::Find::dont_use_nlink to 1, if you want to force File::Find to always stat directories. This was used for file systems that do not have an nlink count matching the number of sub-directories. Examples are ISO-9660 (CD-ROM), AFS, HPFS (OS/2 file system), FAT (DOS file system) and a couple of others.

You shouldn't need to set this variable, since File::Find should now detect such file systems on-the-fly and switch itself to using stat. This works even for parts of your file system, like a mounted CD-ROM.

If you do set $File::Find::dont_use_nlink to 1, you will notice slow-downs.

symlinks

Be aware that the option to follow symbolic links can be dangerous. Depending on the structure of the directory tree (including symbolic links to directories) you might traverse a given (physical) directory more than once (only if follow_fast is in effect). Furthermore, deleting or changing files in a symbolically linked directory might cause very unpleasant surprises, since you delete or change files in an unknown directory.

NOTES

  • Mac OS (Classic) users should note a few differences:

    • The path separator is ':', not '/', and the current directory is denoted as ':', not '.'. You should be careful about specifying relative pathnames. While a full path always begins with a volume name, a relative pathname should always begin with a ':'. If specifying a volume name only, a trailing ':' is required.

    • $File::Find::dir is guaranteed to end with a ':'. If $_ contains the name of a directory, that name may or may not end with a ':'. Likewise, $File::Find::name, which contains the complete pathname to that directory, and $File::Find::fullname, which holds the absolute pathname of that directory with all symbolic links resolved, may or may not end with a ':'.

    • The default untaint_pattern (see above) on Mac OS is set to qr|^(.+)$|. Note that the parentheses are vital.

    • The invisible system file "Icon\015" is ignored. While this file may appear in every directory, there are some more invisible system files on every volume, which are all located at the volume root level (i.e. "MacintoshHD:"). These system files are not excluded automatically. Your filter may use the following code to recognize invisible files or directories (requires Mac::Files):

       use Mac::Files;

       # invisible() --  returns 1 if file/directory is invisible,
 # 0 if it's visible or undef if an error occurred

       sub invisible($) {
   my $file = shift;
   my ($fileCat, $fileInfo);
   my $invisible_flag =  1 << 14;

         if ( $fileCat = FSpGetCatInfo($file) ) {
     if ($fileInfo = $fileCat->ioFlFndrInfo() ) {
       return (($fileInfo->fdFlags & $invisible_flag) && 1);
     }
   }
   return undef;
    }

      Generally, invisible files are system files, unless an odd application decides to use invisible files for its own purposes. To distinguish such files from system files, you have to look at the type and creator file attributes. The MacPerl built-in functions GetFileInfo(FILE) and SetFileInfo(CREATOR, TYPE, FILES) offer access to these attributes (see MacPerl.pm for details).

      Files that appear on the desktop actually reside in an (hidden) directory named "Desktop Folder" on the particular disk volume. Note that, although all desktop files appear to be on the same "virtual" desktop, each disk volume actually maintains its own "Desktop Folder" directory.

BUGS AND CAVEATS

Despite the name of the finddepth() function, both find() and finddepth() perform a depth-first search of the directory hierarchy.

HISTORY

File::Find used to produce incorrect results if called recursively. During the development of perl 5.8 this bug was fixed. The first fixed version of File::Find was 1.01.


File::Glob - Perl extension for BSD glob routine

    • META CHARACTERS
    • POSIX FLAGS
  • DIAGNOSTICS
  • NOTES
  • SEE ALSO
  • AUTHOR

NAME

File::Glob - Perl extension for BSD glob routine

SYNOPSIS

  use File::Glob ':glob';

  @list = bsd_glob('*.[ch]');
  $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);

  if (GLOB_ERROR) {
    # an error occurred reading $homedir
  }

  ## override the core glob (CORE::glob() does this automatically
  ## by default anyway, since v5.6.0)
  use File::Glob ':globally';
  my @sources = <*.{c,h,y}>;

  ## override the core glob, forcing case sensitivity
  use File::Glob qw(:globally :case);
  my @sources = <*.{c,h,y}>;

  ## override the core glob forcing case insensitivity
  use File::Glob qw(:globally :nocase);
  my @sources = <*.{c,h,y}>;

  ## glob on all files in home directory
  use File::Glob ':globally';
  my @sources = <~gnat/*>;

DESCRIPTION

The glob angle-bracket operator <> is a pathname generator that implements the rules for file name pattern matching used by Unix-like shells such as the Bourne shell or C shell.

File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2"). bsd_glob() takes a mandatory pattern argument, and an optional flags argument, and returns a list of filenames matching the pattern, with interpretation of the pattern modified by the flags variable.

Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). Note that they don't share the same prototype--CORE::glob() only accepts a single argument. Due to historical reasons, CORE::glob() will also split its argument on whitespace, treating it as multiple patterns, whereas bsd_glob() considers them as one pattern.

META CHARACTERS

  \       Quote the next metacharacter
  []      Character class
  {}      Multiple pattern
  *       Match any string of characters
  ?       Match any single character
  ~       User name home directory

The metanotation a{b,c,d}e is a shorthand for abe ace ade. Left to right order is preserved, with results of matches being sorted separately at a low level to preserve this order. As a special case {, }, and {} are passed undisturbed.

POSIX FLAGS

The POSIX defined flags for bsd_glob() are:

GLOB_ERR

Force bsd_glob() to return an error when it encounters a directory it cannot open or read. Ordinarily bsd_glob() continues to find matches.

GLOB_LIMIT

Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands to a size bigger than the system constant ARG_MAX (usually found in limits.h). If your system does not define this constant, bsd_glob() uses sysconf(_SC_ARG_MAX) or _POSIX_ARG_MAX where available (in that order). You can inspect these values using the standard POSIX extension.

GLOB_MARK

Each pathname that is a directory that matches the pattern has a slash appended.

GLOB_NOCASE

By default, file names are assumed to be case sensitive; this flag makes bsd_glob() treat case differences as not significant.

GLOB_NOCHECK

If the pattern does not match any pathname, then bsd_glob() returns a list consisting of only the pattern. If GLOB_QUOTE is set, its effect is present in the pattern returned.

GLOB_NOSORT

By default, the pathnames are sorted in ascending ASCII order; this flag prevents that sorting (speeding up bsd_glob()).

The FreeBSD extensions to the POSIX standard are the following flags:

GLOB_BRACE

Pre-process the string to expand {pat,pat,...} strings like csh(1). The pattern '{}' is left unexpanded for historical reasons (and csh(1) does the same thing to ease typing of find(1) patterns).

GLOB_NOMAGIC

Same as GLOB_NOCHECK but it only returns the pattern if it does not contain any of the special characters "*", "?" or "[". NOMAGIC is provided to simplify implementing the historic csh(1) globbing behaviour and should probably not be used anywhere else.

GLOB_QUOTE

Use the backslash ('\') character for quoting: every occurrence of a backslash followed by a character in the pattern is replaced by that character, avoiding any special interpretation of the character. (But see below for exceptions on DOSISH systems).

GLOB_TILDE

Expand patterns that start with '~' to user name home directories.

GLOB_CSH

For convenience, GLOB_CSH is a synonym for GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT.

The POSIX provided GLOB_APPEND, GLOB_DOOFFS, and the FreeBSD extensions GLOB_ALTDIRFUNC, and GLOB_MAGCHAR flags have not been implemented in the Perl version because they involve more complex interaction with the underlying C structures.

The following flag has been added in the Perl implementation for csh compatibility:

GLOB_ALPHASORT

If GLOB_NOSORT is not in effect, sort filenames is alphabetical order (case does not matter) rather than in ASCII order.

DIAGNOSTICS

bsd_glob() returns a list of matching paths, possibly zero length. If an error occurred, &File::Glob::GLOB_ERROR will be non-zero and $! will be set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, or one of the following values otherwise:

GLOB_NOSPACE

An attempt to allocate memory failed.

GLOB_ABEND

The glob was stopped because an error was encountered.

In the case where bsd_glob() has found some matching paths, but is interrupted by an error, it will return a list of filenames and set &File::Glob::ERROR.

Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour by not considering ENOENT and ENOTDIR as errors - bsd_glob() will continue processing despite those errors, unless the GLOB_ERR flag is set.

Be aware that all filenames returned from File::Glob are tainted.

NOTES

  • If you want to use multiple patterns, e.g. bsd_glob("a* b*"), you should probably throw them in a set as in bsd_glob("{a*,b*}"). This is because the argument to bsd_glob() isn't subjected to parsing by the C shell. Remember that you can use a backslash to escape things.

  • On DOSISH systems, backslash is a valid directory separator character. In this case, use of backslash as a quoting character (via GLOB_QUOTE) interferes with the use of backslash as a directory separator. The best (simplest, most portable) solution is to use forward slashes for directory separators, and backslashes for quoting. However, this does not match "normal practice" on these systems. As a concession to user expectation, therefore, backslashes (under GLOB_QUOTE) only quote the glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself. All other backslashes are passed through unchanged.

  • Win32 users should use the real slash. If you really want to use backslashes, consider using Sarathy's File::DosGlob, which comes with the standard Perl distribution.

  • Mac OS (Classic) users should note a few differences. Since Mac OS is not Unix, when the glob code encounters a tilde glob (e.g. ~user) and the GLOB_TILDE flag is used, it simply returns that pattern without doing any expansion.

    Glob on Mac OS is case-insensitive by default (if you don't use any flags). If you specify any flags at all and still want glob to be case-insensitive, you must include GLOB_NOCASE in the flags.

    The path separator is ':' (aka colon), not '/' (aka slash). Mac OS users should be careful about specifying relative pathnames. While a full path always begins with a volume name, a relative pathname should always begin with a ':'. If specifying a volume name only, a trailing ':' is required.

    The specification of pathnames in glob patterns adheres to the usual Mac OS conventions: The path separator is a colon ':', not a slash '/'. A full path always begins with a volume name. A relative pathname on Mac OS must always begin with a ':', except when specifying a file or directory name in the current working directory, where the leading colon is optional. If specifying a volume name only, a trailing ':' is required. Due to these rules, a glob like <*:> will find all mounted volumes, while a glob like <*> or <:*> will find all files and directories in the current directory.

    Note that updirs in the glob pattern are resolved before the matching begins, i.e. a pattern like "*HD:t?p::a*" will be matched as "*HD:a*". Note also, that a single trailing ':' in the pattern is ignored (unless it's a volume name pattern like "*HD:"), i.e. a glob like <:*:> will find both directories and files (and not, as one might expect, only directories). You can, however, use the GLOB_MARK flag to distinguish (without a file test) directory names from file names.

    If the GLOB_MARK flag is set, all directory paths will have a ':' appended. Since a directory like 'lib:' is not a valid relative path on Mac OS, both a leading and a trailing colon will be added, when the directory name in question doesn't contain any colons (e.g. 'lib' becomes ':lib:').

SEE ALSO

glob in the perlfunc manpage, glob(3)

AUTHOR

The Perl interface was written by Nathan Torkington <gnat@frii.com>, and is released under the artistic license. Further modifications were made by Greg Bacon <gbacon@cs.uah.edu>, Gurusamy Sarathy <gsar@activestate.com>, and Thomas Wegner <wegner_thomas@yahoo.com>. The C glob code has the following copyright:

    Copyright (c) 1989, 1993 The Regents of the University of California.
    All rights reserved.
    This code is derived from software contributed to Berkeley by
    Guido van Rossum.
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    3. Neither the name of the University nor the names of its contributors
       may be used to endorse or promote products derived from this software
       without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.


File::Listing - parse directory listing

  • CREDITS

NAME

File::Listing - parse directory listing

SYNOPSIS

 use File::Listing qw(parse_dir);
 for (parse_dir(`ls -l`)) {
     ($name, $type, $size, $mtime, $mode) = @$_;
     next if $type ne 'f'; # plain file
     #...
 }

 # directory listing can also be read from a file
 open(LISTING, "zcat ls-lR.gz|");
 $dir = parse_dir(\*LISTING, '+0000');

DESCRIPTION

This module exports a single function called parse_dir(), which can be used to parse directory listings. Currently it only understand Unix 'ls -l' and 'ls -lR' format. It should eventually be able to most things you might get back from a ftp server file listing (LIST command), i.e. VMS listings, NT listings, DOS listings,...

The first parameter to parse_dir() is the directory listing to parse. It can be a scalar, a reference to an array of directory lines or a glob representing a filehandle to read the directory listing from.

The second parameter is the time zone to use when parsing time stamps in the listing. If this value is undefined, then the local time zone is assumed.

The third parameter is the type of listing to assume. The values will be strings like 'unix', 'vms', 'dos'. Currently only 'unix' is implemented and this is also the default value. Ideally, the listing type should be determined automatically.

The fourth parameter specifies how unparseable lines should be treated. Values can be 'ignore', 'warn' or a code reference. Warn means that the perl warn() function will be called. If a code reference is passed, then this routine will be called and the return value from it will be incorporated in the listing. The default is 'ignore'.

Only the first parameter is mandatory.

The return value from parse_dir() is a list of directory entries. In a scalar context the return value is a reference to the list. The directory entries are represented by an array consisting of [ $filename, $filetype, $filesize, $filetime, $filemode ]. The $filetype value is one of the letters 'f', 'd', 'l' or '?'. The $filetime value is the seconds since Jan 1, 1970. The $filemode is a bitmask like the mode returned by stat().

CREDITS

Based on lsparse.pl (from Lee McLoughlin's ftp mirror package) and Net::FTP's parse_dir (Graham Barr).


File::Path - create or remove directory trees

  • DIAGNOSTICS
  • AUTHORS

NAME

File::Path - create or remove directory trees

SYNOPSIS

    use File::Path;

    mkpath(['/foo/bar/baz', 'blurfl/quux'], 1, 0711);
    rmtree(['foo/bar/baz', 'blurfl/quux'], 1, 1);

DESCRIPTION

The mkpath function provides a convenient way to create directories, even if your mkdir kernel call won't create more than one level of directory at a time. mkpath takes three arguments:

  • the name of the path to create, or a reference to a list of paths to create,

  • a boolean value, which if TRUE will cause mkpath to print the name of each directory as it is created (defaults to FALSE), and

  • the numeric mode to use when creating the directories (defaults to 0777), to be modified by the current umask.

It returns a list of all directories (including intermediates, determined using the Unix '/' separator) created.

If a system error prevents a directory from being created, then the mkpath function throws a fatal error with Carp::croak. This error can be trapped with an eval block:

  eval { mkpath($dir) };
  if ($@) {
    print "Couldn't create $dir: $@";
  }

Similarly, the rmtree function provides a convenient way to delete a subtree from the directory structure, much like the Unix command rm -r. rmtree takes three arguments:

  • the root of the subtree to delete, or a reference to a list of roots. All of the files and directories below each root, as well as the roots themselves, will be deleted.

  • a boolean value, which if TRUE will cause rmtree to print a message each time it examines a file, giving the name of the file, and indicating whether it's using rmdir or unlink to remove it, or that it's skipping it. (defaults to FALSE)

  • a boolean value, which if FALSE (the default for non-root users) will cause rmtree to adjust the mode of directories (if required) prior to attempting to remove the contents. Note that on interruption or failure of rmtree, directories may be left with more permissive modes for the owner.

It returns the number of files successfully deleted. Symlinks are simply deleted and not followed.

DIAGNOSTICS

  • On Windows, if mkpath gives you the warning: No such file or directory, this may mean that you've exceeded your filesystem's maximum path length.

AUTHORS

Tim Bunce <Tim.Bunce@ig.co.uk> and Charles Bailey <bailey@newman.upenn.edu>


File::Slurp - Efficient Reading/Writing of Complete Files

    • read_file
      • binmode
      • array_ref
      • scalar_ref
      • buf_ref
      • blk_size
      • err_mode
    • write_file
      • binmode
      • buf_ref
      • atomic
      • append
      • no_clobber
      • err_mode
    • overwrite_file
    • append_file
    • read_dir
      • keep_dot_dot
    • EXPORT
    • SEE ALSO
    • BUGS
  • AUTHOR

NAME

File::Slurp - Efficient Reading/Writing of Complete Files

SYNOPSIS

  use File::Slurp;

  my $text = read_file( 'filename' ) ;
  my @lines = read_file( 'filename' ) ;

  write_file( 'filename', @lines ) ;

  use File::Slurp qw( slurp ) ;

  my $text = slurp( 'filename' ) ;

DESCRIPTION

This module provides subs that allow you to read or write entire files with one simple call. They are designed to be simple to use, have flexible ways to pass in or get the file contents and to be very efficient. There is also a sub to read in all the files in a directory other than . and ..

These slurp/spew subs work for files, pipes and sockets, and stdio, pseudo-files, and DATA.

read_file

This sub reads in an entire file and returns its contents to the caller. In list context it will return a list of lines (using the current value of $/ as the separator including support for paragraph mode when it is set to ''). In scalar context it returns the entire file as a single scalar.

  my $text = read_file( 'filename' ) ;
  my @lines = read_file( 'filename' ) ;

The first argument to read_file is the filename and the rest of the arguments are key/value pairs which are optional and which modify the behavior of the call. Other than binmode the options all control how the slurped file is returned to the caller.

If the first argument is a file handle reference or I/O object (if ref is true), then that handle is slurped in. This mode is supported so you slurp handles such as DATA, STDIN. See the test handle.t for an example that does open( '-|' ) and child process spews data to the parant which slurps it in. All of the options that control how the data is returned to the caller still work in this case.

NOTE: as of version 9999.06, read_file works correctly on the DATA handle. It used to need a sysseek workaround but that is now handled when needed by the module itself.

You can optionally request that slurp() is exported to your code. This is an alias for read_file and is meant to be forward compatible with Perl 6 (which will have slurp() built-in).

The options are:

binmode

If you set the binmode option, then the file will be slurped in binary mode.

        my $bin_data = read_file( $bin_file, binmode => ':raw' ) ;

NOTE: this actually sets the O_BINARY mode flag for sysopen. It probably should call binmode and pass its argument to support other file modes.

array_ref

If this boolean option is set, the return value (only in scalar context) will be an array reference which contains the lines of the slurped file. The following two calls are equivalent:

        my $lines_ref = read_file( $bin_file, array_ref => 1 ) ;
        my $lines_ref = [ read_file( $bin_file ) ] ;

scalar_ref

If this boolean option is set, the return value (only in scalar context) will be an scalar reference to a string which is the contents of the slurped file. This will usually be faster than returning the plain scalar.

        my $text_ref = read_file( $bin_file, scalar_ref => 1 ) ;

buf_ref

You can use this option to pass in a scalar reference and the slurped file contents will be stored in the scalar. This can be used in conjunction with any of the other options.

        my $text_ref = read_file( $bin_file, buf_ref => \$buffer,
                                             array_ref => 1 ) ;
        my @lines = read_file( $bin_file, buf_ref => \$buffer ) ;

blk_size

You can use this option to set the block size used when slurping from an already open handle (like \*STDIN). It defaults to 1MB.

        my $text_ref = read_file( $bin_file, blk_size => 10_000_000,
                                             array_ref => 1 ) ;

err_mode

You can use this option to control how read_file behaves when an error occurs. This option defaults to 'croak'. You can set it to 'carp' or to 'quiet to have no error handling. This code wants to carp and then read abother file if it fails.

        my $text_ref = read_file( $file, err_mode => 'carp' ) ;
        unless ( $text_ref ) {

                # read a different file but croak if not found
                $text_ref = read_file( $another_file ) ;
                        }

                        # process ${$text_ref}

write_file

This sub writes out an entire file in one call.

  write_file( 'filename', @data ) ;

The first argument to write_file is the filename. The next argument is an optional hash reference and it contains key/values that can modify the behavior of write_file. The rest of the argument list is the data to be written to the file.

  write_file( 'filename', {append => 1 }, @data ) ;
  write_file( 'filename', {binmode => ':raw' }, $buffer ) ;

As a shortcut if the first data argument is a scalar or array reference, it is used as the only data to be written to the file. Any following arguments in @_ are ignored. This is a faster way to pass in the output to be written to the file and is equivilent to the buf_ref option. These following pairs are equivilent but the pass by reference call will be faster in most cases (especially with larger files).

  write_file( 'filename', \$buffer ) ;
  write_file( 'filename', $buffer ) ;

  write_file( 'filename', \@lines ) ;
  write_file( 'filename', @lines ) ;

If the first argument is a file handle reference or I/O object (if ref is true), then that handle is slurped in. This mode is supported so you spew to handles such as \*STDOUT. See the test handle.t for an example that does open( '-|' ) and child process spews data to the parant which slurps it in. All of the options that control how the data is passes into write_file still work in this case.

write_file returns 1 upon successfully writing the file or undef if it encountered an error.

The options are:

binmode

If you set the binmode option, then the file will be written in binary mode.

        write_file( $bin_file, {binmode => ':raw'}, @data ) ;

NOTE: this actually sets the O_BINARY mode flag for sysopen. It probably should call binmode and pass its argument to support other file modes.

buf_ref

You can use this option to pass in a scalar reference which has the data to be written. If this is set then any data arguments (including the scalar reference shortcut) in @_ will be ignored. These are equivilent:

        write_file( $bin_file, { buf_ref => \$buffer } ) ;
        write_file( $bin_file, \$buffer ) ;
        write_file( $bin_file, $buffer ) ;

atomic

If you set this boolean option, the file will be written to in an atomic fashion. A temporary file name is created by appending the pid ($$) to the file name argument and that file is spewed to. After the file is closed it is renamed to the original file name (and rename is an atomic operation on most OS's). If the program using this were to crash in the middle of this, then the file with the pid suffix could be left behind.

append

If you set this boolean option, the data will be written at the end of the current file.

        write_file( $file, {append => 1}, @data ) ;

write_file croaks if it cannot open the file. It returns true if it succeeded in writing out the file and undef if there was an error. (Yes, I know if it croaks it can't return anything but that is for when I add the options to select the error handling mode).

no_clobber

If you set this boolean option, an existing file will not be overwritten.

        write_file( $file, {no_clobber => 1}, @data ) ;

err_mode

You can use this option to control how write_file behaves when an error occurs. This option defaults to 'croak'. You can set it to 'carp' or to 'quiet' to have no error handling other than the return value. If the first call to write_file fails it will carp and then write to another file. If the second call to write_file fails, it will croak.

        unless ( write_file( $file, { err_mode => 'carp', \$data ) ;

                # write a different file but croak if not found
                write_file( $other_file, \$data ) ;
                        }

overwrite_file

This sub is just a typeglob alias to write_file since write_file always overwrites an existing file. This sub is supported for backwards compatibility with the original version of this module. See write_file for its API and behavior.

append_file

This sub will write its data to the end of the file. It is a wrapper around write_file and it has the same API so see that for the full documentation. These calls are equivilent:

        append_file( $file, @data ) ;
        write_file( $file, {append => 1}, @data ) ;

read_dir

This sub reads all the file names from directory and returns them to the caller but . and .. are removed by default.

        my @files = read_dir( '/path/to/dir' ) ;

It croaks if it cannot open the directory.

In a list context read_dir returns a list of the entries in the directory. In a scalar context it returns an array reference which has the entries.

keep_dot_dot

If this boolean option is set, . and .. are not removed from the list of files.

        my @all_files = read_dir( '/path/to/dir', keep_dot_dot => 1 ) ;

EXPORT

  read_file write_file overwrite_file append_file read_dir

SEE ALSO

An article on file slurping in extras/slurp_article.pod. There is also a benchmarking script in extras/slurp_bench.pl.

BUGS

If run under Perl 5.004, slurping from the DATA handle will fail as that requires B.pm which didn't get into core until 5.005.

AUTHOR

Uri Guttman, <uri@stemsystems.com>


File::Spec - portably perform operations on file names

  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

File::Spec - portably perform operations on file names

SYNOPSIS

        use File::Spec;

        $x=File::Spec->catfile('a', 'b', 'c');

which returns 'a/b/c' under Unix. Or:

        use File::Spec::Functions;

        $x = catfile('a', 'b', 'c');

DESCRIPTION

This module is designed to support operations commonly performed on file specifications (usually called "file names", but not to be confused with the contents of a file, or Perl's file handles), such as concatenating several directory and file names into a single path, or determining whether a path is rooted. It is based on code directly taken from MakeMaker 5.17, code written by Andreas König, Andy Dougherty, Charles Bailey, Ilya Zakharevich, Paul Schinder, and others.

Since these functions are different for most operating systems, each set of OS specific routines is available in a separate module, including:

        File::Spec::Unix
        File::Spec::Mac
        File::Spec::OS2
        File::Spec::Win32
        File::Spec::VMS

The module appropriate for the current OS is automatically loaded by File::Spec. Since some modules (like VMS) make use of facilities available only under that OS, it may not be possible to load all modules under all operating systems.

Since File::Spec is object oriented, subroutines should not be called directly, as in:

        File::Spec::catfile('a','b');

but rather as class methods:

        File::Spec->catfile('a','b');

For simple uses, the File::Spec::Functions manpage provides convenient functional forms of these methods.

METHODS

canonpath

No physical check on the filesystem, but a logical cleanup of a path.

    $cpath = File::Spec->canonpath( $path ) ;

Note that this does *not* collapse x/../y sections into y. This is by design. If /foo on your system is a symlink to /bar/baz, then /foo/../quux is actually /bar/quux, not /quux as a naive ../-removal would give you. If you want to do this kind of processing, you probably want Cwd's realpath() function to actually traverse the filesystem cleaning up paths like this.

catdir

Concatenate two or more directory names to form a complete path ending with a directory. But remove the trailing slash from the resulting string, because it doesn't look good, isn't necessary and confuses OS/2. Of course, if this is the root directory, don't cut off the trailing slash :-)

    $path = File::Spec->catdir( @directories );
catfile

Concatenate one or more directory names and a filename to form a complete path ending with a filename

    $path = File::Spec->catfile( @directories, $filename );
curdir

Returns a string representation of the current directory.

    $curdir = File::Spec->curdir();
devnull

Returns a string representation of the null device.

    $devnull = File::Spec->devnull();
rootdir

Returns a string representation of the root directory.

    $rootdir = File::Spec->rootdir();
tmpdir

Returns a string representation of the first writable directory from a list of possible temporary directories. Returns the current directory if no writable temporary directories are found. The list of directories checked depends on the platform; e.g. File::Spec::Unix checks $ENV{TMPDIR} (unless taint is on) and /tmp.

    $tmpdir = File::Spec->tmpdir();
updir

Returns a string representation of the parent directory.

    $updir = File::Spec->updir();
no_upwards

Given a list of file names, strip out those that refer to a parent directory. (Does not strip symlinks, only '.', '..', and equivalents.)

    @paths = File::Spec->no_upwards( @paths );
case_tolerant

Returns a true or false value indicating, respectively, that alphabetic case is not or is significant when comparing file specifications.

    $is_case_tolerant = File::Spec->case_tolerant();
file_name_is_absolute

Takes as its argument a path, and returns true if it is an absolute path.

    $is_absolute = File::Spec->file_name_is_absolute( $path );

This does not consult the local filesystem on Unix, Win32, OS/2, or Mac OS (Classic). It does consult the working environment for VMS (see file_name_is_absolute in the File::Spec::VMS manpage).

path

Takes no argument. Returns the environment variable PATH (or the local platform's equivalent) as a list.

    @PATH = File::Spec->path();
join

join is the same as catfile.

splitpath

Splits a path in to volume, directory, and filename portions. On systems with no concept of volume, returns '' for volume.

    ($volume,$directories,$file) = File::Spec->splitpath( $path );
    ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );

For systems with no syntax differentiating filenames from directories, assumes that the last file is a path unless $no_file is true or a trailing separator or /. or /.. is present. On Unix, this means that $no_file true makes this return ( '', $path, '' ).

The directory portion may or may not be returned with a trailing '/'.

The results can be passed to catpath() to get back a path equivalent to (usually identical to) the original path.

splitdir

The opposite of catdir().

    @dirs = File::Spec->splitdir( $directories );

$directories must be only the directory portion of the path on systems that have the concept of a volume or that have path syntax that differentiates files from directories.

Unlike just splitting the directories on the separator, empty directory names ('') can be returned, because these are significant on some OSes.

catpath()

Takes volume, directory and file portions and returns an entire path. Under Unix, $volume is ignored, and directory and file are concatenated. A '/' is inserted if need be. On other OSes, $volume is significant.

    $full_path = File::Spec->catpath( $volume, $directory, $file );
abs2rel

Takes a destination path and an optional base path returns a relative path from the base path to the destination path:

    $rel_path = File::Spec->abs2rel( $path ) ;
    $rel_path = File::Spec->abs2rel( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

On systems with the concept of volume, if $path and $base appear to be on two different volumes, we will not attempt to resolve the two paths, and we will instead simply return $path. Note that previous versions of this module ignored the volume of $base, which resulted in garbage results part of the time.

On systems that have a grammar that indicates filenames, this ignores the $base filename as well. Otherwise all path components are assumed to be directories.

If $path is relative, it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

No checks against the filesystem are made. On VMS, there is interaction with the working environment, as logicals and macros are expanded.

Based on code written by Shigio Yamaguchi.

rel2abs()

Converts a relative path to an absolute path.

    $abs_path = File::Spec->rel2abs( $path ) ;
    $abs_path = File::Spec->rel2abs( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

On systems with the concept of volume, if $path and $base appear to be on two different volumes, we will not attempt to resolve the two paths, and we will instead simply return $path. Note that previous versions of this module ignored the volume of $base, which resulted in garbage results part of the time.

On systems that have a grammar that indicates filenames, this ignores the $base filename as well. Otherwise all path components are assumed to be directories.

If $path is absolute, it is cleaned up and returned using canonpath().

No checks against the filesystem are made. On VMS, there is interaction with the working environment, as logicals and macros are expanded.

Based on code written by Shigio Yamaguchi.

For further information, please see the File::Spec::Unix manpage, the File::Spec::Mac manpage, the File::Spec::OS2 manpage, the File::Spec::Win32 manpage, or the File::Spec::VMS manpage.

SEE ALSO

the File::Spec::Unix manpage, the File::Spec::Mac manpage, the File::Spec::OS2 manpage, the File::Spec::Win32 manpage, the File::Spec::VMS manpage, the File::Spec::Functions manpage, the ExtUtils::MakeMaker manpage

AUTHOR

Currently maintained by Ken Williams <KWILLIAMS@cpan.org>.

The vast majority of the code was written by Kenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty <doughera@lafayette.edu>, Andreas König <A.Koenig@franz.ww.TU-Berlin.DE>, Tim Bunce <Tim.Bunce@ig.co.uk>. VMS support by Charles Bailey <bailey@newman.upenn.edu>. OS/2 support by Ilya Zakharevich <ilya@math.ohio-state.edu>. Mac support by Paul Schinder <schinder@pobox.com>, and Thomas Wegner <wegner_thomas@yahoo.com>. abs2rel() and rel2abs() written by Shigio Yamaguchi <shigio@tamacom.com>, modified by Barrie Slaymaker <barries@slaysys.com>. splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


File::Spec::Cygwin - methods for Cygwin file specs

  • COPYRIGHT

NAME

File::Spec::Cygwin - methods for Cygwin file specs

SYNOPSIS

 require File::Spec::Cygwin; # Done internally by File::Spec if needed

DESCRIPTION

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.

This module is still in beta. Cygwin-knowledgeable folks are invited to offer patches and suggestions.

canonpath

Any \ (backslashes) are converted to / (forward slashes), and then File::Spec::Unix canonpath() is called on the result.

file_name_is_absolute

True is returned if the file name begins with drive_letter:, and if not, File::Spec::Unix file_name_is_absolute() is called.

tmpdir (override)

Returns a string representation of the first existing directory from the following list:

    $ENV{TMPDIR}
    /tmp
    C:/temp

Since Perl 5.8.0, if running under taint mode, and if the environment variables are tainted, they are not used.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


File::Spec::Epoc - methods for Epoc file specs

  • AUTHOR
  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::Epoc - methods for Epoc file specs

SYNOPSIS

 require File::Spec::Epoc; # Done internally by File::Spec if needed

DESCRIPTION

See File::Spec::Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

This package is still work in progress ;-)

canonpath()

No physical check on the filesystem, but a logical cleanup of a path. On UNIX eliminated successive slashes and successive "/.".

AUTHOR

o.flebbe@gmx.de

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.


File::Spec::Functions - portably perform operations on file names

    • Exports
  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::Functions - portably perform operations on file names

SYNOPSIS

        use File::Spec::Functions;
        $x = catfile('a','b');

DESCRIPTION

This module exports convenience functions for all of the class methods provided by File::Spec.

For a reference of available functions, please consult the File::Spec::Unix manpage, which contains the entire set, and which is inherited by the modules for other platforms. For further information, please see the File::Spec::Mac manpage, the File::Spec::OS2 manpage, the File::Spec::Win32 manpage, or the File::Spec::VMS manpage.

Exports

The following functions are exported by default.

        canonpath
        catdir
        catfile
        curdir
        rootdir
        updir
        no_upwards
        file_name_is_absolute
        path

The following functions are exported only by request.

        devnull
        tmpdir
        splitpath
        splitdir
        catpath
        abs2rel
        rel2abs
        case_tolerant

All the functions may be imported using the :ALL tag.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

File::Spec, File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32, File::Spec::VMS, ExtUtils::MakeMaker


File::Spec::Mac - File::Spec for Mac OS

  • METHODS
  • AUTHORS
  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::Mac - File::Spec for Mac OS (Classic)

SYNOPSIS

 require File::Spec::Mac; # Done internally by File::Spec if needed

DESCRIPTION

Methods for manipulating file specifications.

METHODS

canonpath

On Mac OS, there's nothing to be done. Returns what it's given.

catdir()

Concatenate two or more directory names to form a path separated by colons (":") ending with a directory. Resulting paths are relative by default, but can be forced to be absolute (but avoid this, see below). Automatically puts a trailing ":" on the end of the complete path, because that's what's done in MacPerl's environment and helps to distinguish a file path from a directory path.

IMPORTANT NOTE: Beginning with version 1.3 of this module, the resulting path is relative by default and not absolute. This decision was made due to portability reasons. Since File::Spec->catdir() returns relative paths on all other operating systems, it will now also follow this convention on Mac OS. Note that this may break some existing scripts.

The intended purpose of this routine is to concatenate directory names. But because of the nature of Macintosh paths, some additional possibilities are allowed to make using this routine give reasonable results for some common situations. In other words, you are also allowed to concatenate paths instead of directory names (strictly speaking, a string like ":a" is a path, but not a name, since it contains a punctuation character ":").

So, beside calls like

    catdir("a") = ":a:"
    catdir("a","b") = ":a:b:"
    catdir() = ""                    (special case)

calls like the following

    catdir(":a:") = ":a:"
    catdir(":a","b") = ":a:b:"
    catdir(":a:","b") = ":a:b:"
    catdir(":a:",":b:") = ":a:b:"
    catdir(":") = ":"

are allowed.

Here are the rules that are used in catdir(); note that we try to be as compatible as possible to Unix:

  1. The resulting path is relative by default, i.e. the resulting path will have a leading colon.

  2. A trailing colon is added automatically to the resulting path, to denote a directory.

  3. Generally, each argument has one leading ":" and one trailing ":" removed (if any). They are then joined together by a ":". Special treatment applies for arguments denoting updir paths like "::lib:", see (4), or arguments consisting solely of colons ("colon paths"), see (5).

  4. When an updir path like ":::lib::" is passed as argument, the number of directories to climb up is handled correctly, not removing leading or trailing colons when necessary. E.g.

        catdir(":::a","::b","c")    = ":::a::b:c:"
    catdir(":::a::","::b","c")  = ":::a:::b:c:"

  5. Adding a colon ":" or empty string "" to a path at any position doesn't alter the path, i.e. these arguments are ignored. (When a "" is passed as the first argument, it has a special meaning, see (6)). This way, a colon ":" is handled like a "." (curdir) on Unix, while an empty string "" is generally ignored (see Unix->canonpath() ). Likewise, a "::" is handled like a ".." (updir), and a ":::" is handled like a "../.." etc. E.g.

        catdir("a",":",":","b")   = ":a:b:"
    catdir("a",":","::",":b") = ":a::b:"

  6. If the first argument is an empty string "" or is a volume name, i.e. matches the pattern /^[^:]+:/, the resulting path is absolute.

  7. Passing an empty string "" as the first argument to catdir() is like passingFile::Spec->rootdir() as the first argument, i.e.

        catdir("","a","b")          is the same as
        catdir(rootdir(),"a","b").

    This is true on Unix, where catdir("","a","b") yields "/a/b" and rootdir() is "/". Note that rootdir() on Mac OS is the startup volume, which is the closest in concept to Unix' "/". This should help to run existing scripts originally written for Unix.

  8. For absolute paths, some cleanup is done, to ensure that the volume name isn't immediately followed by updirs. This is invalid, because this would go beyond "root". Generally, these cases are handled like their Unix counterparts:

     Unix:
    Unix->catdir("","")                 =  "/"
    Unix->catdir("",".")                =  "/"
    Unix->catdir("","..")               =  "/"              # can't go beyond root
    Unix->catdir("",".","..","..","a")  =  "/a"
 Mac:
    Mac->catdir("","")                  =  rootdir()         # (e.g. "HD:")
    Mac->catdir("",":")                 =  rootdir()
    Mac->catdir("","::")                =  rootdir()         # can't go beyond root
    Mac->catdir("",":","::","::","a")   =  rootdir() . "a:"  # (e.g. "HD:a:")

    However, this approach is limited to the first arguments following "root" (again, see Unix->canonpath() ). If there are more arguments that move up the directory tree, an invalid path going beyond root can be created.

As you've seen, you can force catdir() to create an absolute path by passing either an empty string or a path that begins with a volume name as the first argument. However, you are strongly encouraged not to do so, since this is done only for backward compatibility. Newer versions of File::Spec come with a method called catpath() (see below), that is designed to offer a portable solution for the creation of absolute paths. It takes volume, directory and file portions and returns an entire path. While catdir() is still suitable for the concatenation of directory names, you are encouraged to use catpath() to concatenate volume names and directory paths. E.g.

    $dir      = File::Spec->catdir("tmp","sources");
    $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");

yields

    "MacintoshHD:tmp:sources:" .
catfile

Concatenate one or more directory names and a filename to form a complete path ending with a filename. Resulting paths are relative by default, but can be forced to be absolute (but avoid this).

IMPORTANT NOTE: Beginning with version 1.3 of this module, the resulting path is relative by default and not absolute. This decision was made due to portability reasons. Since File::Spec->catfile() returns relative paths on all other operating systems, it will now also follow this convention on Mac OS. Note that this may break some existing scripts.

The last argument is always considered to be the file portion. Since catfile() uses catdir() (see above) for the concatenation of the directory portions (if any), the following with regard to relative and absolute paths is true:

    catfile("")     = ""
    catfile("file") = "file"

but

    catfile("","")        = rootdir()         # (e.g. "HD:")
    catfile("","file")    = rootdir() . file  # (e.g. "HD:file")
    catfile("HD:","file") = "HD:file"

This means that catdir() is called only when there are two or more arguments, as one might expect.

Note that the leading ":" is removed from the filename, so that

    catfile("a","b","file")  = ":a:b:file"    and
    catfile("a","b",":file") = ":a:b:file"

give the same answer.

To concatenate volume names, directory paths and filenames, you are encouraged to use catpath() (see below).

curdir

Returns a string representing the current directory. On Mac OS, this is ":".

devnull

Returns a string representing the null device. On Mac OS, this is "Dev:Null".

rootdir

Returns a string representing the root directory. Under MacPerl, returns the name of the startup volume, since that's the closest in concept, although other volumes aren't rooted there. The name has a trailing ":", because that's the correct specification for a volume name on Mac OS.

If Mac::Files could not be loaded, the empty string is returned.

tmpdir

Returns the contents of $ENV{TMPDIR}, if that directory exits or the current working directory otherwise. Under MacPerl, $ENV{TMPDIR} will contain a path like "MacintoshHD:Temporary Items:", which is a hidden directory on your startup volume.

updir

Returns a string representing the parent directory. On Mac OS, this is "::".

file_name_is_absolute

Takes as argument a path and returns true, if it is an absolute path. If the path has a leading ":", it's a relative path. Otherwise, it's an absolute path, unless the path doesn't contain any colons, i.e. it's a name like "a". In this particular case, the path is considered to be relative (i.e. it is considered to be a filename). Use ":" in the appropriate place in the path if you want to distinguish unambiguously. As a special case, the filename '' is always considered to be absolute. Note that with version 1.2 of File::Spec::Mac, this does no longer consult the local filesystem.

E.g.

    File::Spec->file_name_is_absolute("a");             # false (relative)
    File::Spec->file_name_is_absolute(":a:b:");         # false (relative)
    File::Spec->file_name_is_absolute("MacintoshHD:");  # true (absolute)
    File::Spec->file_name_is_absolute("");              # true (absolute)
path

Returns the null list for the MacPerl application, since the concept is usually meaningless under Mac OS. But if you're using the MacPerl tool under MPW, it gives back $ENV{Commands} suitably split, as is done in :lib:ExtUtils:MM_Mac.pm.

splitpath
    ($volume,$directories,$file) = File::Spec->splitpath( $path );
    ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );

Splits a path into volume, directory, and filename portions.

On Mac OS, assumes that the last part of the path is a filename unless $no_file is true or a trailing separator ":" is present.

The volume portion is always returned with a trailing ":". The directory portion is always returned with a leading (to denote a relative path) and a trailing ":" (to denote a directory). The file portion is always returned without a leading ":". Empty portions are returned as empty string ''.

The results can be passed to catpath() to get back a path equivalent to (usually identical to) the original path.

splitdir

The opposite of catdir().

    @dirs = File::Spec->splitdir( $directories );

$directories should be only the directory portion of the path on systems that have the concept of a volume or that have path syntax that differentiates files from directories. Consider using splitpath() otherwise.

Unlike just splitting the directories on the separator, empty directory names ("") can be returned. Since catdir() on Mac OS always appends a trailing colon to distinguish a directory path from a file path, a single trailing colon will be ignored, i.e. there's no empty directory name after it.

Hence, on Mac OS, both

    File::Spec->splitdir( ":a:b::c:" );    and
    File::Spec->splitdir( ":a:b::c" );

yield:

    ( "a", "b", "::", "c")

while

    File::Spec->splitdir( ":a:b::c::" );

yields:

    ( "a", "b", "::", "c", "::")
catpath
    $path = File::Spec->catpath($volume,$directory,$file);

Takes volume, directory and file portions and returns an entire path. On Mac OS, $volume, $directory and $file are concatenated. A ':' is inserted if need be. You may pass an empty string for each portion. If all portions are empty, the empty string is returned. If $volume is empty, the result will be a relative path, beginning with a ':'. If $volume and $directory are empty, a leading ":" (if any) is removed form $file and the remainder is returned. If $file is empty, the resulting path will have a trailing ':'.

abs2rel

Takes a destination path and an optional base path and returns a relative path from the base path to the destination path:

    $rel_path = File::Spec->abs2rel( $path ) ;
    $rel_path = File::Spec->abs2rel( $path, $base ) ;

Note that both paths are assumed to have a notation that distinguishes a directory path (with trailing ':') from a file path (without trailing ':').

If $base is not present or '', then the current working directory is used. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to the current working directory.

If $path and $base appear to be on two different volumes, we will not attempt to resolve the two paths, and we will instead simply return $path. Note that previous versions of this module ignored the volume of $base, which resulted in garbage results part of the time.

If $base doesn't have a trailing colon, the last element of $base is assumed to be a filename. This filename is ignored. Otherwise all path components are assumed to be directories.

If $path is relative, it is converted to absolute form using rel2abs(). This means that it is taken to be relative to the current working directory.

Based on code written by Shigio Yamaguchi.

rel2abs

Converts a relative path to an absolute path:

    $abs_path = File::Spec->rel2abs( $path ) ;
    $abs_path = File::Spec->rel2abs( $path, $base ) ;

Note that both paths are assumed to have a notation that distinguishes a directory path (with trailing ':') from a file path (without trailing ':').

If $base is not present or '', then $base is set to the current working directory. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to the current working directory.

If $base doesn't have a trailing colon, the last element of $base is assumed to be a filename. This filename is ignored. Otherwise all path components are assumed to be directories.

If $path is already absolute, it is returned and $base is ignored.

Based on code written by Shigio Yamaguchi.

AUTHORS

See the authors list in File::Spec. Mac OS support by Paul Schinder <schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.


File::Spec::OS2 - methods for OS/2 file specs

  • COPYRIGHT

NAME

File::Spec::OS2 - methods for OS/2 file specs

SYNOPSIS

 require File::Spec::OS2; # Done internally by File::Spec if needed

DESCRIPTION

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.

Amongst the changes made for OS/2 are...

tmpdir

Modifies the list of places temp directory information is looked for.

    $ENV{TMPDIR}
    $ENV{TEMP}
    $ENV{TMP}
    /tmp
    /
splitpath

Volumes can be drive letters or UNC sharenames (\\server\share).

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


File::Spec::Unix - File::Spec for Unix, base for other File::Spec modules

  • METHODS
  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::Unix - File::Spec for Unix, base for other File::Spec modules

SYNOPSIS

 require File::Spec::Unix; # Done automatically by File::Spec

DESCRIPTION

Methods for manipulating file specifications. Other File::Spec modules, such as File::Spec::Mac, inherit from File::Spec::Unix and override specific methods.

METHODS

canonpath()

No physical check on the filesystem, but a logical cleanup of a path. On UNIX eliminates successive slashes and successive "/.".

    $cpath = File::Spec->canonpath( $path ) ;

Note that this does *not* collapse x/../y sections into y. This is by design. If /foo on your system is a symlink to /bar/baz, then /foo/../quux is actually /bar/quux, not /quux as a naive ../-removal would give you. If you want to do this kind of processing, you probably want Cwd's realpath() function to actually traverse the filesystem cleaning up paths like this.

catdir()

Concatenate two or more directory names to form a complete path ending with a directory. But remove the trailing slash from the resulting string, because it doesn't look good, isn't necessary and confuses OS2. Of course, if this is the root directory, don't cut off the trailing slash :-)

catfile

Concatenate one or more directory names and a filename to form a complete path ending with a filename

curdir

Returns a string representation of the current directory. "." on UNIX.

devnull

Returns a string representation of the null device. "/dev/null" on UNIX.

rootdir

Returns a string representation of the root directory. "/" on UNIX.

tmpdir

Returns a string representation of the first writable directory from the following list or the current directory if none from the list are writable:

    $ENV{TMPDIR}
    /tmp

Since perl 5.8.0, if running under taint mode, and if $ENV{TMPDIR} is tainted, it is not used.

updir

Returns a string representation of the parent directory. ".." on UNIX.

no_upwards

Given a list of file names, strip out those that refer to a parent directory. (Does not strip symlinks, only '.', '..', and equivalents.)

case_tolerant

Returns a true or false value indicating, respectively, that alphabetic is not or is significant when comparing file specifications.

file_name_is_absolute

Takes as argument a path and returns true if it is an absolute path.

This does not consult the local filesystem on Unix, Win32, OS/2 or Mac OS (Classic). It does consult the working environment for VMS (see file_name_is_absolute in the File::Spec::VMS manpage).

path

Takes no argument, returns the environment variable PATH as an array.

join

join is the same as catfile.

splitpath
    ($volume,$directories,$file) = File::Spec->splitpath( $path );
    ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );

Splits a path into volume, directory, and filename portions. On systems with no concept of volume, returns '' for volume.

For systems with no syntax differentiating filenames from directories, assumes that the last file is a path unless $no_file is true or a trailing separator or /. or /.. is present. On Unix this means that $no_file true makes this return ( '', $path, '' ).

The directory portion may or may not be returned with a trailing '/'.

The results can be passed to catpath() to get back a path equivalent to (usually identical to) the original path.

splitdir

The opposite of catdir().

    @dirs = File::Spec->splitdir( $directories );

$directories must be only the directory portion of the path on systems that have the concept of a volume or that have path syntax that differentiates files from directories.

Unlike just splitting the directories on the separator, empty directory names ('') can be returned, because these are significant on some OSs.

On Unix,

    File::Spec->splitdir( "/a/b//c/" );

Yields:

    ( '', 'a', 'b', '', 'c', '' )
catpath()

Takes volume, directory and file portions and returns an entire path. Under Unix, $volume is ignored, and directory and file are concatenated. A '/' is inserted if needed (though if the directory portion doesn't start with '/' it is not added). On other OSs, $volume is significant.

abs2rel

Takes a destination path and an optional base path returns a relative path from the base path to the destination path:

    $rel_path = File::Spec->abs2rel( $path ) ;
    $rel_path = File::Spec->abs2rel( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

On systems that have a grammar that indicates filenames, this ignores the $base filename. Otherwise all path components are assumed to be directories.

If $path is relative, it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

No checks against the filesystem are made. On VMS, there is interaction with the working environment, as logicals and macros are expanded.

Based on code written by Shigio Yamaguchi.

rel2abs()

Converts a relative path to an absolute path.

    $abs_path = File::Spec->rel2abs( $path ) ;
    $abs_path = File::Spec->rel2abs( $path, $base ) ;

If $base is not present or '', then cwd() is used. If $base is relative, then it is converted to absolute form using rel2abs(). This means that it is taken to be relative to cwd().

On systems that have a grammar that indicates filenames, this ignores the $base filename. Otherwise all path components are assumed to be directories.

If $path is absolute, it is cleaned up and returned using canonpath().

No checks against the filesystem are made. On VMS, there is interaction with the working environment, as logicals and macros are expanded.

Based on code written by Shigio Yamaguchi.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the File::Spec manpage


File::Spec::VMS - methods for VMS file specs

  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::VMS - methods for VMS file specs

SYNOPSIS

 require File::Spec::VMS; # Done internally by File::Spec if needed

DESCRIPTION

See File::Spec::Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

canonpath (override)

Removes redundant portions of file specifications according to VMS syntax.

catdir (override)

Concatenates a list of file specifications, and returns the result as a VMS-syntax directory specification. No check is made for "impossible" cases (e.g. elements other than the first being absolute filespecs).

catfile (override)

Concatenates a list of file specifications, and returns the result as a VMS-syntax file specification.

curdir (override)

Returns a string representation of the current directory: '[]'

devnull (override)

Returns a string representation of the null device: '_NLA0:'

rootdir (override)

Returns a string representation of the root directory: 'SYS$DISK:[000000]'

tmpdir (override)

Returns a string representation of the first writable directory from the following list or '' if none are writable:

    sys$scratch:
    $ENV{TMPDIR}

Since perl 5.8.0, if running under taint mode, and if $ENV{TMPDIR} is tainted, it is not used.

updir (override)

Returns a string representation of the parent directory: '[-]'

case_tolerant (override)

VMS file specification syntax is case-tolerant.

path (override)

Translate logical name DCL$PATH as a searchlist, rather than trying to split string value of $ENV{'PATH'}.

file_name_is_absolute (override)

Checks for VMS directory spec as well as Unix separators.

splitpath (override)

Splits using VMS syntax.

splitdir (override)

Split dirspec using VMS syntax.

catpath (override)

Construct a complete filespec using VMS syntax

abs2rel (override)

Use VMS syntax when converting filespecs.

rel2abs (override)

Use VMS syntax when converting filespecs.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.

An explanation of VMS file specs can be found at http://h71000.www7.hp.com/doc/731FINAL/4506/4506pro_014.html#apps_locating_naming_files.


File::Spec::Win32 - methods for Win32 file specs

    • Note For File::Spec::Win32 Maintainers
  • COPYRIGHT
  • SEE ALSO

NAME

File::Spec::Win32 - methods for Win32 file specs

SYNOPSIS

 require File::Spec::Win32; # Done internally by File::Spec if needed

DESCRIPTION

See File::Spec::Unix for a documentation of the methods provided there. This package overrides the implementation of these methods, not the semantics.

devnull

Returns a string representation of the null device.

tmpdir

Returns a string representation of the first existing directory from the following list:

    $ENV{TMPDIR}
    $ENV{TEMP}
    $ENV{TMP}
    SYS:/temp
    C:\system\temp
    C:/temp
    /tmp
    /

The SYS:/temp is preferred in Novell NetWare and the C:\system\temp for Symbian (the File::Spec::Win32 is used also for those platforms).

Since Perl 5.8.0, if running under taint mode, and if the environment variables are tainted, they are not used.

catfile

Concatenate one or more directory names and a filename to form a complete path ending with a filename

canonpath

No physical check on the filesystem, but a logical cleanup of a path. On UNIX eliminated successive slashes and successive "/.". On Win32 makes

        dir1\dir2\dir3\..\..\dir4 -> \dir\dir4 and even
        dir1\dir2\dir3\...\dir4   -> \dir\dir4
splitpath
    ($volume,$directories,$file) = File::Spec->splitpath( $path );
    ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );

Splits a path into volume, directory, and filename portions. Assumes that the last file is a path unless the path ends in '\\', '\\.', '\\..' or $no_file is true. On Win32 this means that $no_file true makes this return ( $volume, $path, '' ).

Separators accepted are \ and /.

Volumes can be drive letters or UNC sharenames (\\server\share).

The results can be passed to catpath to get back a path equivalent to (usually identical to) the original path.

splitdir

The opposite of catdir().

    @dirs = File::Spec->splitdir( $directories );

$directories must be only the directory portion of the path on systems that have the concept of a volume or that have path syntax that differentiates files from directories.

Unlike just splitting the directories on the separator, leading empty and trailing directory entries can be returned, because these are significant on some OSs. So,

    File::Spec->splitdir( "/a/b/c" );

Yields:

    ( '', 'a', 'b', '', 'c', '' )
catpath

Takes volume, directory and file portions and returns an entire path. Under Unix, $volume is ignored, and this is just like catfile(). On other OSs, the $volume become significant.

Note For File::Spec::Win32 Maintainers

Novell NetWare inherits its File::Spec behaviour from File::Spec::Win32.

COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

See the File::Spec manpage and the File::Spec::Unix manpage. This package overrides the implementation of these methods, not the semantics.


File::Temp - return name and handle of a temporary file safely

  • PORTABILITY
  • SYNOPSIS
  • DESCRIPTION
  • OBJECT-ORIENTED INTERFACE
  • FUNCTIONS
  • MKTEMP FUNCTIONS
  • POSIX FUNCTIONS
  • ADDITIONAL FUNCTIONS
  • UTILITY FUNCTIONS
  • PACKAGE VARIABLES
  • WARNING
    • Temporary files and NFS
    • Forking
    • BINMODE
  • HISTORY
  • SEE ALSO
  • AUTHOR

NAME

File::Temp - return name and handle of a temporary file safely

SYNOPSIS

  use File::Temp qw/ tempfile tempdir /;

  $fh = tempfile();
  ($fh, $filename) = tempfile();

  ($fh, $filename) = tempfile( $template, DIR => $dir);
  ($fh, $filename) = tempfile( $template, SUFFIX => '.dat');

  $dir = tempdir( CLEANUP => 1 );
  ($fh, $filename) = tempfile( DIR => $dir );

Object interface:

  require File::Temp;
  use File::Temp ();

  $fh = new File::Temp($template);
  $fname = $fh->filename;

  $tmp = new File::Temp( UNLINK => 0, SUFFIX => '.dat' );
  print $tmp "Some data\n";
  print "Filename is $tmp\n";

The following interfaces are provided for compatibility with existing APIs. They should not be used in new code.

MkTemp family:

  use File::Temp qw/ :mktemp  /;

  ($fh, $file) = mkstemp( "tmpfileXXXXX" );
  ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix);

  $tmpdir = mkdtemp( $template );

  $unopened_file = mktemp( $template );

POSIX functions:

  use File::Temp qw/ :POSIX /;

  $file = tmpnam();
  $fh = tmpfile();

  ($fh, $file) = tmpnam();

Compatibility functions:

  $unopened_file = File::Temp::tempnam( $dir, $pfx );

DESCRIPTION

File::Temp can be used to create and open temporary files in a safe way. There is both a function interface and an object-oriented interface. The File::Temp constructor or the tempfile() function can be used to return the name and the open filehandle of a temporary file. The tempdir() function can be used to create a temporary directory.

The security aspect of temporary file creation is emphasized such that a filehandle and filename are returned together. This helps guarantee that a race condition can not occur where the temporary file is created by another process between checking for the existence of the file and its opening. Additional security levels are provided to check, for example, that the sticky bit is set on world writable directories. See safe_level for more information.

For compatibility with popular C library functions, Perl implementations of the mkstemp() family of functions are provided. These are, mkstemp(), mkstemps(), mkdtemp() and mktemp().

Additionally, implementations of the standard POSIX tmpnam() and tmpfile() functions are provided if required.

Implementations of mktemp(), tmpnam(), and tempnam() are provided, but should be used with caution since they return only a filename that was valid when function was called, so cannot guarantee that the file will not exist by the time the caller opens the filename.

OBJECT-ORIENTED INTERFACE

This is the primary interface for interacting with File::Temp. Using the OO interface a temporary file can be created when the object is constructed and the file can be removed when the object is no longer required.

Note that there is no method to obtain the filehandle from the File::Temp object. The object itself acts as a filehandle. Also, the object is configured such that it stringifies to the name of the temporary file.

new

Create a temporary file object.

  my $tmp = new File::Temp();

by default the object is constructed as if tempfile was called without options, but with the additional behaviour that the temporary file is removed by the object destructor if UNLINK is set to true (the default).

Supported arguments are the same as for tempfile: UNLINK (defaulting to true), DIR and SUFFIX. Additionally, the filename template is specified using the TEMPLATE option. The OPEN option is not supported (the file is always opened).

 $tmp = new File::Temp( TEMPLATE => 'tempXXXXX',
                        DIR => 'mydir',
                        SUFFIX => '.dat');

Arguments are case insensitive.

filename

Return the name of the temporary file associated with this object.

  $filename = $tmp->filename;

This method is called automatically when the object is used as a string.

unlink_on_destroy

Control whether the file is unlinked when the object goes out of scope. The file is removed if this value is true and $KEEP_ALL is not.

 $fh->unlink_on_destroy( 1 );

Default is for the file to be removed.

DESTROY

When the object goes out of scope, the destructor is called. This destructor will attempt to unlink the file (using unlink1) if the constructor was called with UNLINK set to 1 (the default state if UNLINK is not specified).

No error is given if the unlink fails.

If the global variable $KEEP_ALL is true, the file will not be removed.

FUNCTIONS

This section describes the recommended interface for generating temporary files and directories.

tempfile

This is the basic function to generate temporary files. The behaviour of the file can be changed using various options:

  $fh = tempfile();
  ($fh, $filename) = tempfile();

Create a temporary file in the directory specified for temporary files, as specified by the tmpdir() function in the File::Spec manpage.

  ($fh, $filename) = tempfile($template);

Create a temporary file in the current directory using the supplied template. Trailing `X' characters are replaced with random letters to generate the filename. At least four `X' characters must be present at the end of the template.

  ($fh, $filename) = tempfile($template, SUFFIX => $suffix)

Same as previously, except that a suffix is added to the template after the `X' translation. Useful for ensuring that a temporary filename has a particular extension when needed by other applications. But see the WARNING at the end.

  ($fh, $filename) = tempfile($template, DIR => $dir);

Translates the template as before except that a directory name is specified.

  ($fh, $filename) = tempfile($template, UNLINK => 1);

Return the filename and filehandle as before except that the file is automatically removed when the program exits (dependent on $KEEP_ALL). Default is for the file to be removed if a file handle is requested and to be kept if the filename is requested. In a scalar context (where no filename is returned) the file is always deleted either (depending on the operating system) on exit or when it is closed (unless $KEEP_ALL is true when the temp file is created).

Use the object-oriented interface if fine-grained control of when a file is removed is required.

If the template is not specified, a template is always automatically generated. This temporary file is placed in tmpdir() (the File::Spec manpage) unless a directory is specified explicitly with the DIR option.

  $fh = tempfile( $template, DIR => $dir );

If called in scalar context, only the filehandle is returned and the file will automatically be deleted when closed on operating systems that support this (see the description of tmpfile() elsewhere in this document). This is the preferred mode of operation, as if you only have a filehandle, you can never create a race condition by fumbling with the filename. On systems that can not unlink an open file or can not mark a file as temporary when it is opened (for example, Windows NT uses the O_TEMPORARY flag) the file is marked for deletion when the program ends (equivalent to setting UNLINK to 1). The UNLINK flag is ignored if present.

  (undef, $filename) = tempfile($template, OPEN => 0);

This will return the filename based on the template but will not open this file. Cannot be used in conjunction with UNLINK set to true. Default is to always open the file to protect from possible race conditions. A warning is issued if warnings are turned on. Consider using the tmpnam() and mktemp() functions described elsewhere in this document if opening the file is not required.

Options can be combined as required.

tempdir

This is the recommended interface for creation of temporary directories. The behaviour of the function depends on the arguments:

  $tempdir = tempdir();

Create a directory in tmpdir() (see File::Spec).

  $tempdir = tempdir( $template );

Create a directory from the supplied template. This template is similar to that described for tempfile(). `X' characters at the end of the template are replaced with random letters to construct the directory name. At least four `X' characters must be in the template.

  $tempdir = tempdir ( DIR => $dir );

Specifies the directory to use for the temporary directory. The temporary directory name is derived from an internal template.

  $tempdir = tempdir ( $template, DIR => $dir );

Prepend the supplied directory name to the template. The template should not include parent directory specifications itself. Any parent directory specifications are removed from the template before prepending the supplied directory.

  $tempdir = tempdir ( $template, TMPDIR => 1 );

Using the supplied template, create the temporary directory in a standard location for temporary files. Equivalent to doing

  $tempdir = tempdir ( $template, DIR => File::Spec->tmpdir);

but shorter. Parent directory specifications are stripped from the template itself. The TMPDIR option is ignored if DIR is set explicitly. Additionally, TMPDIR is implied if neither a template nor a directory are supplied.

  $tempdir = tempdir( $template, CLEANUP => 1);

Create a temporary directory using the supplied template, but attempt to remove it (and all files inside it) when the program exits. Note that an attempt will be made to remove all files from the directory even if they were not created by this module (otherwise why ask to clean it up?). The directory removal is made with the rmtree() function from the File::Path module. Of course, if the template is not specified, the temporary directory will be created in tmpdir() and will also be removed at program exit.

MKTEMP FUNCTIONS

The following functions are Perl implementations of the mktemp() family of temp file generation system calls.

mkstemp

Given a template, returns a filehandle to the temporary file and the name of the file.

  ($fh, $name) = mkstemp( $template );

In scalar context, just the filehandle is returned.

The template may be any filename with some number of X's appended to it, for example /tmp/temp.XXXX. The trailing X's are replaced with unique alphanumeric combinations.

mkstemps

Similar to mkstemp(), except that an extra argument can be supplied with a suffix to be appended to the template.

  ($fh, $name) = mkstemps( $template, $suffix );

For example a template of testXXXXXX and suffix of .dat would generate a file similar to testhGji_w.dat.

Returns just the filehandle alone when called in scalar context.

mkdtemp

Create a directory from a template. The template must end in X's that are replaced by the routine.

  $tmpdir_name = mkdtemp($template);

Returns the name of the temporary directory created. Returns undef on failure.

Directory must be removed by the caller.

mktemp

Returns a valid temporary filename but does not guarantee that the file will not be opened by someone else.

  $unopened_file = mktemp($template);

Template is the same as that required by mkstemp().

POSIX FUNCTIONS

This section describes the re-implementation of the tmpnam() and tmpfile() functions described in the POSIX manpage using the mkstemp() from this module.

Unlike the POSIX implementations, the directory used for the temporary file is not specified in a system include file (P_tmpdir) but simply depends on the choice of tmpdir() returned by File::Spec. On some implementations this location can be set using the TMPDIR environment variable, which may not be secure. If this is a problem, simply use mkstemp() and specify a template.

tmpnam

When called in scalar context, returns the full name (including path) of a temporary file (uses mktemp()). The only check is that the file does not already exist, but there is no guarantee that that condition will continue to apply.

  $file = tmpnam();

When called in list context, a filehandle to the open file and a filename are returned. This is achieved by calling mkstemp() after constructing a suitable template.

  ($fh, $file) = tmpnam();

If possible, this form should be used to prevent possible race conditions.

See tmpdir in the File::Spec manpage for information on the choice of temporary directory for a particular operating system.

tmpfile

Returns the filehandle of a temporary file.

  $fh = tmpfile();

The file is removed when the filehandle is closed or when the program exits. No access to the filename is provided.

If the temporary file can not be created undef is returned. Currently this command will probably not work when the temporary directory is on an NFS file system.

ADDITIONAL FUNCTIONS

These functions are provided for backwards compatibility with common tempfile generation C library functions.

They are not exported and must be addressed using the full package name.

tempnam

Return the name of a temporary file in the specified directory using a prefix. The file is guaranteed not to exist at the time the function was called, but such guarantees are good for one clock tick only. Always use the proper form of sysopen with O_CREAT | O_EXCL if you must open such a filename.

  $filename = File::Temp::tempnam( $dir, $prefix );

Equivalent to running mktemp() with $dir/$prefixXXXXXXXX (using unix file convention as an example)

Because this function uses mktemp(), it can suffer from race conditions.

UTILITY FUNCTIONS

Useful functions for dealing with the filehandle and filename.

unlink0

Given an open filehandle and the associated filename, make a safe unlink. This is achieved by first checking that the filename and filehandle initially point to the same file and that the number of links to the file is 1 (all fields returned by stat() are compared). Then the filename is unlinked and the filehandle checked once again to verify that the number of links on that file is now 0. This is the closest you can come to making sure that the filename unlinked was the same as the file whose descriptor you hold.

  unlink0($fh, $path)
     or die "Error unlinking file $path safely";

Returns false on error. The filehandle is not closed since on some occasions this is not required.

On some platforms, for example Windows NT, it is not possible to unlink an open file (the file must be closed first). On those platforms, the actual unlinking is deferred until the program ends and good status is returned. A check is still performed to make sure that the filehandle and filename are pointing to the same thing (but not at the time the end block is executed since the deferred removal may not have access to the filehandle).

Additionally, on Windows NT not all the fields returned by stat() can be compared. For example, the dev and rdev fields seem to be different. Also, it seems that the size of the file returned by stat() does not always agree, with stat(FH) being more accurate than stat(filename), presumably because of caching issues even when using autoflush (this is usually overcome by waiting a while after writing to the tempfile before attempting to unlink0 it).

Finally, on NFS file systems the link count of the file handle does not always go to zero immediately after unlinking. Currently, this command is expected to fail on NFS disks.

This function is disabled if the global variable $KEEP_ALL is true and an unlink on open file is supported. If the unlink is to be deferred to the END block, the file is still registered for removal.

cmpstat

Compare stat of filehandle with stat of provided filename. This can be used to check that the filename and filehandle initially point to the same file and that the number of links to the file is 1 (all fields returned by stat() are compared).

  cmpstat($fh, $path)
     or die "Error comparing handle with file";

Returns false if the stat information differs or if the link count is greater than 1.

On certain platofms, eg Windows, not all the fields returned by stat() can be compared. For example, the dev and rdev fields seem to be different in Windows. Also, it seems that the size of the file returned by stat() does not always agree, with stat(FH) being more accurate than stat(filename), presumably because of caching issues even when using autoflush (this is usually overcome by waiting a while after writing to the tempfile before attempting to unlink0 it).

Not exported by default.

unlink1

Similar to unlink0 except after file comparison using cmpstat, the filehandle is closed prior to attempting to unlink the file. This allows the file to be removed without using an END block, but does mean that the post-unlink comparison of the filehandle state provided by unlink0 is not available.

  unlink1($fh, $path)
     or die "Error closing and unlinking file";

Usually called from the object destructor when using the OO interface.

Not exported by default.

This function is disabled if the global variable $KEEP_ALL is true.

cleanup

Calling this function will cause any temp files or temp directories that are registered for removal to be removed. This happens automatically when the process exits but can be triggered manually if the caller is sure that none of the temp files are required. This method can be registered as an Apache callback.

On OSes where temp files are automatically removed when the temp file is closed, calling this function will have no effect other than to remove temporary directories (which may include temporary files).

  File::Temp::cleanup();

Not exported by default.

PACKAGE VARIABLES

These functions control the global state of the package.

safe_level

Controls the lengths to which the module will go to check the safety of the temporary file or directory before proceeding. Options are:

STANDARD

Do the basic security measures to ensure the directory exists and is writable, that the umask() is fixed before opening of the file, that temporary files are opened only if they do not already exist, and that possible race conditions are avoided. Finally the unlink0 function is used to remove files safely.

MEDIUM

In addition to the STANDARD security, the output directory is checked to make sure that it is owned either by root or the user running the program. If the directory is writable by group or by other, it is then checked to make sure that the sticky bit is set.

Will not work on platforms that do not support the -k test for sticky bit.

HIGH

In addition to the MEDIUM security checks, also check for the possibility of ``chown() giveaway'' using the POSIX sysconf() function. If this is a possibility, each directory in the path is checked in turn for safeness, recursively walking back to the root directory.

For platforms that do not support the POSIX _PC_CHOWN_RESTRICTED symbol (for example, Windows NT) it is assumed that ``chown() giveaway'' is possible and the recursive test is performed.

The level can be changed as follows:

  File::Temp->safe_level( File::Temp::HIGH );

The level constants are not exported by the module.

Currently, you must be running at least perl v5.6.0 in order to run with MEDIUM or HIGH security. This is simply because the safety tests use functions from Fcntl that are not available in older versions of perl. The problem is that the version number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though they are different versions.

On systems that do not support the HIGH or MEDIUM safety levels (for example Win NT or OS/2) any attempt to change the level will be ignored. The decision to ignore rather than raise an exception allows portable programs to be written with high security in mind for the systems that can support this without those programs failing on systems where the extra tests are irrelevant.

If you really need to see whether the change has been accepted simply examine the return value of safe_level.

  $newlevel = File::Temp->safe_level( File::Temp::HIGH );
  die "Could not change to high security"
      if $newlevel != File::Temp::HIGH;
TopSystemUID

This is the highest UID on the current system that refers to a root UID. This is used to make sure that the temporary directory is owned by a system UID (root, bin, sys etc) rather than simply by root.

This is required since on many unix systems /tmp is not owned by root.

Default is to assume that any UID less than or equal to 10 is a root UID.

  File::Temp->top_system_uid(10);
  my $topid = File::Temp->top_system_uid;

This value can be adjusted to reduce security checking if required. The value is only relevant when safe_level is set to MEDIUM or higher.

$KEEP_ALL

Controls whether temporary files and directories should be retained regardless of any instructions in the program to remove them automatically. This is useful for debugging but should not be used in production code.

  $File::Temp::KEEP_ALL = 1;

Default is for files to be removed as requested by the caller.

In some cases, files will only be retained if this variable is true when the file is created. This means that you can not create a temporary file, set this variable and expect the temp file to still be around when the program exits.

$DEBUG

Controls whether debugging messages should be enabled.

  $File::Temp::DEBUG = 1;

Default is for debugging mode to be disabled.

WARNING

For maximum security, endeavour always to avoid ever looking at, touching, or even imputing the existence of the filename. You do not know that that filename is connected to the same file as the handle you have, and attempts to check this can only trigger more race conditions. It's far more secure to use the filehandle alone and dispense with the filename altogether.

If you need to pass the handle to something that expects a filename then, on a unix system, use "/dev/fd/" . fileno($fh) for arbitrary programs, or more generally "+<=&" . fileno($fh) for Perl programs. You will have to clear the close-on-exec bit on that file descriptor before passing it to another process.

    use Fcntl qw/F_SETFD F_GETFD/;
    fcntl($tmpfh, F_SETFD, 0)
        or die "Can't clear close-on-exec flag on temp fh: $!\n";

Temporary files and NFS

Some problems are associated with using temporary files that reside on NFS file systems and it is recommended that a local filesystem is used whenever possible. Some of the security tests will most probably fail when the temp file is not local. Additionally, be aware that the performance of I/O operations over NFS will not be as good as for a local disk.

Forking

In some cases files created by File::Temp are removed from within an END block. Since END blocks are triggered when a child process exits (unless POSIX::_exit() is used by the child) File::Temp takes care to only remove those temp files created by a particular process ID. This means that a child will not attempt to remove temp files created by the parent process.

BINMODE

The file returned by File::Temp will have been opened in binary mode if such a mode is available. If that is not correct, use the binmode() function to change the mode of the filehandle.

HISTORY

Originally began life in May 1999 as an XS interface to the system mkstemp() function. In March 2000, the OpenBSD mkstemp() code was translated to Perl for total control of the code's security checking, to ensure the presence of the function regardless of operating system and to help with portability. The module was shipped as a standard part of perl from v5.6.1.

SEE ALSO

tmpnam in the POSIX manpage, tmpfile in the POSIX manpage, the File::Spec manpage, the File::Path manpage

See the IO::File manpage and the File::MkTemp manpage, the Apachae::TempFile manpage for different implementations of temporary file handling.

AUTHOR

Tim Jenness <tjenness@cpan.org>

Copyright (C) 1999-2005 Tim Jenness and the UK Particle Physics and Astronomy Research Council. All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Original Perl implementation loosely based on the OpenBSD C code for mkstemp(). Thanks to Tom Christiansen for suggesting that this module should be written and providing ideas for code improvements and security enhancements.


File::stat - by-name interface to Perl's built-in stat functions

  • BUGS
  • NOTE
  • AUTHOR

NAME

File::stat - by-name interface to Perl's built-in stat() functions

SYNOPSIS

 use File::stat;
 $st = stat($file) or die "No $file: $!";
 if ( ($st->mode & 0111) && $st->nlink > 1) ) {
     print "$file is executable with lotsa links\n";
 }

 use File::stat qw(:FIELDS);
 stat($file) or die "No $file: $!";
 if ( ($st_mode & 0111) && $st_nlink > 1) ) {
     print "$file is executable with lotsa links\n";
 }

DESCRIPTION

This module's default exports override the core stat() and lstat() functions, replacing them with versions that return "File::stat" objects. This object has methods that return the similarly named structure field name from the stat(2) function; namely, dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, and blocks.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your stat() and lstat() functions.) Access these fields as variables named with a preceding st_ in front their method names. Thus, $stat_obj->dev() corresponds to $st_dev if you import the fields.

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

BUGS

As of Perl 5.8.0 after using this module you cannot use the implicit $_ or the special filehandle _ with stat() or lstat(), trying to do so leads into strange errors. The workaround is for $_ to be explicit

    my $stat_obj = stat $_;

and for _ to explicitly populate the object using the unexported and undocumented populate() function with CORE::stat():

    my $stat_obj = File::stat::populate(CORE::stat(_));

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


FileCache - keep more files open than the system permits

  • CAVEATS
  • BUGS

NAME

FileCache - keep more files open than the system permits

SYNOPSIS

    use FileCache;
    # or
    use FileCache maxopen => 16;

    cacheout $mode, $path;
    # or
    cacheout $path;
    print $path @data;

    $fh = cacheout $mode, $path;
    # or
    $fh = cacheout $path;
    print $fh @data;

DESCRIPTION

The cacheout function will make sure that there's a filehandle open for reading or writing available as the pathname you give it. It automatically closes and re-opens files if you exceed your system's maximum number of file descriptors, or the suggested maximum maxopen.

cacheout EXPR

The 1-argument form of cacheout will open a file for writing ('>') on it's first use, and appending ('>>') thereafter.

Returns EXPR on success for convenience. You may neglect the return value and manipulate EXPR as the filehandle directly if you prefer.

cacheout MODE, EXPR

The 2-argument form of cacheout will use the supplied mode for the initial and subsequent openings. Most valid modes for 3-argument open are supported namely; '>', '+>', '<', '<+', '>>', '|-' and '-|'

To pass supplemental arguments to a program opened with '|-' or '-|' append them to the command string as you would system EXPR.

Returns EXPR on success for convenience. You may neglect the return value and manipulate EXPR as the filehandle directly if you prefer.

CAVEATS

While it is permissible to close a FileCache managed file, do not do so if you are calling FileCache::cacheout from a package other than which it was imported, or with another module which overrides close. If you must, use FileCache::cacheout_close.

Although FileCache can be used with piped opens ('-|' or '|-') doing so is strongly discouraged. If FileCache finds it necessary to close and then reopen a pipe, the command at the far end of the pipe will be reexecuted - the results of performing IO on FileCache'd pipes is unlikely to be what you expect. The ability to use FileCache on pipes may be removed in a future release.

FileCache does not store the current file offset if it finds it necessary to close a file. When the file is reopened, the offset will be as specified by the original open file mode. This could be construed to be a bug.

BUGS

sys/param.h lies with its NOFILE define on some systems, so you may have to set maxopen yourself.


FileHandle - supply object methods for filehandles

  • SEE ALSO

NAME

FileHandle - supply object methods for filehandles

SYNOPSIS

    use FileHandle;

    $fh = new FileHandle;
    if ($fh->open("< file")) {
        print <$fh>;
        $fh->close;
    }

    $fh = new FileHandle "> FOO";
    if (defined $fh) {
        print $fh "bar\n";
        $fh->close;
    }

    $fh = new FileHandle "file", "r";
    if (defined $fh) {
        print <$fh>;
        undef $fh;       # automatically closes the file
    }

    $fh = new FileHandle "file", O_WRONLY|O_APPEND;
    if (defined $fh) {
        print $fh "corge\n";
        undef $fh;       # automatically closes the file
    }

    $pos = $fh->getpos;
    $fh->setpos($pos);

    $fh->setvbuf($buffer_var, _IOLBF, 1024);

    ($readfh, $writefh) = FileHandle::pipe;

    autoflush STDOUT 1;

DESCRIPTION

NOTE: This class is now a front-end to the IO::* classes.

FileHandle::new creates a FileHandle, which is a reference to a newly created symbol (see the Symbol package). If it receives any parameters, they are passed to FileHandle::open; if the open fails, the FileHandle object is destroyed. Otherwise, it is returned to the caller.

FileHandle::new_from_fd creates a FileHandle like new does. It requires two parameters, which are passed to FileHandle::fdopen; if the fdopen fails, the FileHandle object is destroyed. Otherwise, it is returned to the caller.

FileHandle::open accepts one parameter or two. With one parameter, it is just a front end for the built-in open function. With two parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode, optionally followed by a file permission value.

If FileHandle::open receives a Perl mode string (">", "+<", etc.) or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic Perl open operator.

If FileHandle::open is given a numeric mode, it passes that mode and the optional permissions value to the Perl sysopen operator. For convenience, FileHandle::import tries to import the O_XXX constants from the Fcntl module. If dynamic loading is not available, this may fail, but the rest of FileHandle will still work.

FileHandle::fdopen is like open except that its first parameter is not a filename but rather a file handle name, a FileHandle object, or a file descriptor number.

If the C functions fgetpos() and fsetpos() are available, then FileHandle::getpos returns an opaque value that represents the current position of the FileHandle, and FileHandle::setpos uses that value to return to a previously visited position.

If the C function setvbuf() is available, then FileHandle::setvbuf sets the buffering policy for the FileHandle. The calling sequence for the Perl function is the same as its C counterpart, including the macros _IOFBF, _IOLBF, and _IONBF, except that the buffer parameter specifies a scalar variable to use as a buffer. WARNING: A variable used as a buffer by FileHandle::setvbuf must not be modified in any way until the FileHandle is closed or until FileHandle::setvbuf is called again, or memory corruption may result!

See the perlfunc manpage for complete descriptions of each of the following supported FileHandle methods, which are just front ends for the corresponding built-in functions:

    close
    fileno
    getc
    gets
    eof
    clearerr
    seek
    tell

See the perlvar manpage for complete descriptions of each of the following supported FileHandle methods:

    autoflush
    output_field_separator
    output_record_separator
    input_record_separator
    input_line_number
    format_page_number
    format_lines_per_page
    format_lines_left
    format_name
    format_top_name
    format_line_break_characters
    format_formfeed

Furthermore, for doing normal I/O you might need these:

$fh->print

See print in the perlfunc manpage.

$fh->printf

See printf in the perlfunc manpage.

$fh->getline

This works like <$fh> described in I/O Operators in the perlop manpage except that it's more readable and can be safely called in a list context but still returns just one line.

$fh->getlines

This works like <$fh> when called in a list context to read all the remaining lines in a file, except that it's more readable. It will also croak() if accidentally called in a scalar context.

There are many other functions available since FileHandle is descended from IO::File, IO::Seekable, and IO::Handle. Please see those respective pages for documentation on more functions.

SEE ALSO

The IO extension, the perlfunc manpage, I/O Operators in the perlop manpage.


Filter::Simple - Simplified source filtering

    • The Problem
    • A Solution
    • Disabling or changing <no> behaviour
    • All-in-one interface
    • Filtering only specific components of source code
    • Filtering only the code parts of source code
    • Using Filter::Simple with an explicit import subroutine
    • Using Filter::Simple and Exporter together
    • How it works
  • AUTHOR
  • COPYRIGHT

NAME

Filter::Simple - Simplified source filtering

SYNOPSIS

 # in MyFilter.pm:

     package MyFilter;

     use Filter::Simple;

     FILTER { ... };

     # or just:
     #
     # use Filter::Simple sub { ... };

 # in user's code:

     use MyFilter;

     # this code is filtered

     no MyFilter;

     # this code is not

DESCRIPTION

The Problem

Source filtering is an immensely powerful feature of recent versions of Perl. It allows one to extend the language itself (e.g. the Switch module), to simplify the language (e.g. Language::Pythonesque), or to completely recast the language (e.g. Lingua::Romana::Perligata). Effectively, it allows one to use the full power of Perl as its own, recursively applied, macro language.

The excellent Filter::Util::Call module (by Paul Marquess) provides a usable Perl interface to source filtering, but it is often too powerful and not nearly as simple as it could be.

To use the module it is necessary to do the following:

  1. Download, build, and install the Filter::Util::Call module. (If you have Perl 5.7.1 or later, this is already done for you.)

  2. Set up a module that does a use Filter::Util::Call.

  3. Within that module, create an import subroutine.

  4. Within the import subroutine do a call to filter_add, passing it either a subroutine reference.

  5. Within the subroutine reference, call filter_read or filter_read_exact to "prime" $_ with source code data from the source file that will use your module. Check the status value returned to see if any source code was actually read in.

  6. Process the contents of $_ to change the source code in the desired manner.

  7. Return the status value.

  8. If the act of unimporting your module (via a no) should cause source code filtering to cease, create an unimport subroutine, and have it call filter_del. Make sure that the call to filter_read or filter_read_exact in step 5 will not accidentally read past the no. Effectively this limits source code filters to line-by-line operation, unless the import subroutine does some fancy pre-pre-parsing of the source code it's filtering.

For example, here is a minimal source code filter in a module named BANG.pm. It simply converts every occurrence of the sequence BANG\s+BANG to the sequence die 'BANG' if $BANG in any piece of code following a use BANG; statement (until the next no BANG; statement, if any):

    package BANG;

    use Filter::Util::Call ;

    sub import {
        filter_add( sub {
        my $caller = caller;
        my ($status, $no_seen, $data);
        while ($status = filter_read()) {
            if (/^\s*no\s+$caller\s*;\s*?$/) {
                $no_seen=1;
                last;
            }
            $data .= $_;
            $_ = "";
        }
        $_ = $data;
        s/BANG\s+BANG/die 'BANG' if \$BANG/g
            unless $status < 0;
        $_ .= "no $class;\n" if $no_seen;
        return 1;
        })
    }

    sub unimport {
        filter_del();
    }

    1 ;

This level of sophistication puts filtering out of the reach of many programmers.

A Solution

The Filter::Simple module provides a simplified interface to Filter::Util::Call; one that is sufficient for most common cases.

Instead of the above process, with Filter::Simple the task of setting up a source code filter is reduced to:

  1. Download and install the Filter::Simple module. (If you have Perl 5.7.1 or later, this is already done for you.)

  2. Set up a module that does a use Filter::Simple and then calls FILTER { ... }.

  3. Within the anonymous subroutine or block that is passed to FILTER, process the contents of $_ to change the source code in the desired manner.

In other words, the previous example, would become:

    package BANG;
    use Filter::Simple;

    FILTER {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    };

    1 ;

Note that the source code is passed as a single string, so any regex that uses ^ or $ to detect line boundaries will need the /m flag.

Disabling or changing <no> behaviour

By default, the installed filter only filters up to a line consisting of one of the three standard source "terminators":

    no ModuleName;  # optional comment

or:

    __END__

or:

    __DATA__

but this can be altered by passing a second argument to use Filter::Simple or FILTER (just remember: there's no comma after the initial block when you use FILTER).

That second argument may be either a qr'd regular expression (which is then used to match the terminator line), or a defined false value (which indicates that no terminator line should be looked for), or a reference to a hash (in which case the terminator is the value associated with the key 'terminator'.

For example, to cause the previous filter to filter only up to a line of the form:

    GNAB esu;

you would write:

    package BANG;
    use Filter::Simple;

    FILTER {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    }
    qr/^\s*GNAB\s+esu\s*;\s*?$/;

or:

    FILTER {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    }
    { terminator => qr/^\s*GNAB\s+esu\s*;\s*?$/ };

and to prevent the filter's being turned off in any way:

    package BANG;
    use Filter::Simple;

    FILTER {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    }
    "";    # or: 0

or:

    FILTER {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    }
    { terminator => "" };

Note that, no matter what you set the terminator pattern to, the actual terminator itself must be contained on a single source line.

All-in-one interface

Separating the loading of Filter::Simple:

    use Filter::Simple;

from the setting up of the filtering:

    FILTER { ... };

is useful because it allows other code (typically parser support code or caching variables) to be defined before the filter is invoked. However, there is often no need for such a separation.

In those cases, it is easier to just append the filtering subroutine and any terminator specification directly to the use statement that loads Filter::Simple, like so:

    use Filter::Simple sub {
        s/BANG\s+BANG/die 'BANG' if \$BANG/g;
    };

This is exactly the same as:

    use Filter::Simple;
    BEGIN {
        Filter::Simple::FILTER {
            s/BANG\s+BANG/die 'BANG' if \$BANG/g;
        };
    }

except that the FILTER subroutine is not exported by Filter::Simple.

Filtering only specific components of source code

One of the problems with a filter like:

    use Filter::Simple;

    FILTER { s/BANG\s+BANG/die 'BANG' if \$BANG/g };

is that it indiscriminately applies the specified transformation to the entire text of your source program. So something like:

    warn 'BANG BANG, YOU'RE DEAD';
    BANG BANG;

will become:

    warn 'die 'BANG' if $BANG, YOU'RE DEAD';
    die 'BANG' if $BANG;

It is very common when filtering source to only want to apply the filter to the non-character-string parts of the code, or alternatively to only the character strings.

Filter::Simple supports this type of filtering by automatically exporting the FILTER_ONLY subroutine.

FILTER_ONLY takes a sequence of specifiers that install separate (and possibly multiple) filters that act on only parts of the source code. For example:

    use Filter::Simple;

    FILTER_ONLY
        code      => sub { s/BANG\s+BANG/die 'BANG' if \$BANG/g },
        quotelike => sub { s/BANG\s+BANG/CHITTY CHITTY/g };

The "code" subroutine will only be used to filter parts of the source code that are not quotelikes, POD, or __DATA__. The quotelike subroutine only filters Perl quotelikes (including here documents).

The full list of alternatives is:

"code"

Filters only those sections of the source code that are not quotelikes, POD, or __DATA__.

"code_no_comments"

Filters only those sections of the source code that are not quotelikes, POD, comments, or __DATA__.

"executable"

Filters only those sections of the source code that are not POD or __DATA__.

"executable_no_comments"

Filters only those sections of the source code that are not POD, comments, or __DATA__.

"quotelike"

Filters only Perl quotelikes (as interpreted by &Text::Balanced::extract_quotelike).

"string"

Filters only the string literal parts of a Perl quotelike (i.e. the contents of a string literal, either half of a tr///, the second half of an s///).

"regex"

Filters only the pattern literal parts of a Perl quotelike (i.e. the contents of a qr// or an m//, the first half of an s///).

"all"

Filters everything. Identical in effect to FILTER.

Except for FILTER_ONLY code => sub {...}, each of the component filters is called repeatedly, once for each component found in the source code.

Note that you can also apply two or more of the same type of filter in a single FILTER_ONLY. For example, here's a simple macro-preprocessor that is only applied within regexes, with a final debugging pass that prints the resulting source code:

    use Regexp::Common;
    FILTER_ONLY
        regex => sub { s/!\[/[^/g },
        regex => sub { s/%d/$RE{num}{int}/g },
        regex => sub { s/%f/$RE{num}{real}/g },
        all   => sub { print if $::DEBUG };

Filtering only the code parts of source code

Most source code ceases to be grammatically correct when it is broken up
into the pieces between string literals and regexes. So the C<'code'>
and C<'code_no_comments'> component filter behave slightly differently
from the other partial filters described in the previous section.

Rather than calling the specified processor on each individual piece of code (i.e. on the bits between quotelikes), the 'code...' partial filters operate on the entire source code, but with the quotelike bits (and, in the case of 'code_no_comments', the comments) "blanked out".

That is, a 'code...' filter replaces each quoted string, quotelike, regex, POD, and __DATA__ section with a placeholder. The delimiters of this placeholder are the contents of the $; variable at the time the filter is applied (normally "\034"). The remaining four bytes are a unique identifier for the component being replaced.

This approach makes it comparatively easy to write code preprocessors without worrying about the form or contents of strings, regexes, etc.

For convenience, during a 'code...' filtering operation, Filter::Simple provides a package variable ($Filter::Simple::placeholder) that contains a pre-compiled regex that matches any placeholder...and captures the identifier within the placeholder. Placeholders can be moved and re-ordered within the source code as needed.

In addition, a second package variable (@Filter::Simple::components) contains a list of the various pieces of $_, as they were originally split up to allow placeholders to be inserted.

Once the filtering has been applied, the original strings, regexes, POD, etc. are re-inserted into the code, by replacing each placeholder with the corresponding original component (from @components). Note that this means that the @components variable must be treated with extreme care within the filter. The @components array stores the "back- translations" of each placeholder inserted into $_, as well as the interstitial source code between placeholders. If the placeholder backtranslations are altered in @components, they will be similarly changed when the placeholders are removed from $_ after the filter is complete.

For example, the following filter detects concatentated pairs of strings/quotelikes and reverses the order in which they are concatenated:

    package DemoRevCat;
    use Filter::Simple;

    FILTER_ONLY code => sub {
        my $ph = $Filter::Simple::placeholder;
        s{ ($ph) \s* [.] \s* ($ph) }{ $2.$1 }gx
    };

Thus, the following code:

    use DemoRevCat;

    my $str = "abc" . q(def);

    print "$str\n";

would become:

    my $str = q(def)."abc";

    print "$str\n";

and hence print:

    defabc

Using Filter::Simple with an explicit import subroutine

Filter::Simple generates a special import subroutine for your module (see How it works) which would normally replace any import subroutine you might have explicitly declared.

However, Filter::Simple is smart enough to notice your existing import and Do The Right Thing with it. That is, if you explicitly define an import subroutine in a package that's using Filter::Simple, that import subroutine will still be invoked immediately after any filter you install.

The only thing you have to remember is that the import subroutine must be declared before the filter is installed. If you use FILTER to install the filter:

    package Filter::TurnItUpTo11;

    use Filter::Simple;

    FILTER { s/(\w+)/\U$1/ };

    that will almost never be a problem, but if you install a filtering
    subroutine by passing it directly to the C<use Filter::Simple>
    statement:

    package Filter::TurnItUpTo11;

    use Filter::Simple sub{ s/(\w+)/\U$1/ };

then you must make sure that your import subroutine appears before that use statement.

Using Filter::Simple and Exporter together

Likewise, Filter::Simple is also smart enough to Do The Right Thing if you use Exporter:

    package Switch;
    use base Exporter;
    use Filter::Simple;

    @EXPORT    = qw(switch case);
    @EXPORT_OK = qw(given  when);

    FILTER { $_ = magic_Perl_filter($_) }

Immediately after the filter has been applied to the source, Filter::Simple will pass control to Exporter, so it can do its magic too.

Of course, here too, Filter::Simple has to know you're using Exporter before it applies the filter. That's almost never a problem, but if you're nervous about it, you can guarantee that things will work correctly by ensuring that your use base Exporter always precedes your use Filter::Simple.

How it works

The Filter::Simple module exports into the package that calls FILTER (or uses it directly) -- such as package "BANG" in the above example -- two automagically constructed subroutines -- import and unimport -- which take care of all the nasty details.

In addition, the generated import subroutine passes its own argument list to the filtering subroutine, so the BANG.pm filter could easily be made parametric:

    package BANG;

    use Filter::Simple;

    FILTER {
        my ($die_msg, $var_name) = @_;
        s/BANG\s+BANG/die '$die_msg' if \${$var_name}/g;
    };

    # and in some user code:

    use BANG "BOOM", "BAM";  # "BANG BANG" becomes: die 'BOOM' if $BAM

The specified filtering subroutine is called every time a use BANG is encountered, and passed all the source code following that call, up to either the next no BANG; (or whatever terminator you've set) or the end of the source file, whichever occurs first. By default, any no BANG; call must appear by itself on a separate line, or it is ignored.

AUTHOR

Damian Conway (damian@conway.org)

COPYRIGHT

    Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
    This module is free software. It may be used, redistributed
    and/or modified under the same terms as Perl itself.


Filter::Util::Call - Perl Source Filter Utility Module

    • use Filter::Util::Call
    • import()
    • filter() and anonymous sub
  • EXAMPLES
    • Example 1: A simple filter.
    • Example 2: Using the context
    • Example 3: Using the context within the filter
    • Example 4: Using filter_del
  • Filter::Simple
  • AUTHOR
  • DATE

NAME

Filter::Util::Call - Perl Source Filter Utility Module

SYNOPSIS

    use Filter::Util::Call ;

DESCRIPTION

This module provides you with the framework to write Source Filters in Perl.

An alternate interface to Filter::Util::Call is now available. See the Filter::Simple manpage for more details.

A Perl Source Filter is implemented as a Perl module. The structure of the module can take one of two broadly similar formats. To distinguish between them, the first will be referred to as method filter and the second as closure filter.

Here is a skeleton for the method 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 ;

and this is the equivalent skeleton for the closure filter:

    package MyFilter ;

    use Filter::Util::Call ;

    sub import
    {
        my($type, @arguments) = @_ ;

        filter_add(
            sub
            {
                my($status) ;
                $status = filter_read() ;
                $status ;
            } )
            }

    1 ;

To make use of either of the two filter modules above, place the line below in a Perl source file.

    use MyFilter;

In fact, the skeleton modules shown above are fully functional Source Filters, albeit fairly useless ones. All they does is filter the source stream 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 import method. The difference between them is that the method filter requires a filter method, whereas the closure filter gets the equivalent of a filter method with the anonymous sub passed to filter_add.

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.

use Filter::Util::Call

The following functions are exported by Filter::Util::Call:

    filter_add()
    filter_read()
    filter_read_exact()
    filter_del()

import()

The import method is used to create an instance of the filter. It is called indirectly by Perl when it encounters the use MyFilter line in a source file (See import in the perlfunc manpage for more details on import).

It will always have at least one parameter automatically passed by Perl - this corresponds to the name of the package. In the example above it will be "MyFilter".

Apart from the first parameter, import can accept an optional list of parameters. These can be used to pass parameters to the filter. For example:

    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.

filter_add()

The function, filter_add, actually installs the filter. It takes one parameter which should be a reference. The kind of reference used will dictate which of the two filter types will be used.

If a CODE reference is used then a closure filter will be assumed.

If a CODE reference is not used, a method filter will be assumed. In a method filter, the reference can be used to store context information. The reference will be blessed into the package by filter_add.

See the filters at the end of this documents for examples of using context information using both method filters and closure filters.

filter() and anonymous sub

Both the filter method used with a method filter and the anonymous sub used with a closure filter is where the main processing for the filter is done.

The big difference between the two types of filter is that the method filter uses the object passed to the method to store any context data, whereas the closure filter uses the lexical variables that are maintained by the closure.

Note that the single parameter passed to the method filter, $self, is the same reference that was passed to filter_add blessed into the filter's package. See the example filters later on for details of using $self.

Here is a list of the common features of the anonymous sub and the filter() method.

$_

Although $_ doesn't actually appear explicitly in the sample filters above, it is implicitly used in a number of places.

Firstly, when either filter or the anonymous sub are called, a local copy of $_ will automatically be created. It will always contain the empty string at this point.

Next, both filter_read and filter_read_exact will append any source data that is read to the end of $_.

Finally, when filter or the anonymous sub are finished processing, they are expected to return the filtered source using $_.

This implicit use of $_ greatly simplifies the filter.

$status

The status value that is returned by the user's filter method or anonymous sub and the filter_read and read_exact functions take the same set of values, namely:

    < 0  Error
    = 0  EOF
    > 0  OK
filter_read and filter_read_exact

These functions are used by the filter to obtain either a line or block from the next filter in the chain or the actual source file if there aren't any other filters.

The function filter_read takes two forms:

    $status = filter_read() ;
    $status = filter_read($size) ;

The first form is used to request a line, the second requests a block.

In line mode, filter_read will append the next source line to the end of the $_ scalar.

In block mode, filter_read will append a block of data which is <= $size to the end of the $_ scalar. It is important to emphasise the that filter_read will not necessarily read a block which is precisely $size bytes.

If you need to be able to read a block which has an exact size, you can use the function filter_read_exact. It works identically to filter_read in block mode, except it will try to read a block which is exactly $size bytes in length. The only circumstances when it will not return a block which is $size bytes long is on EOF or error.

It is very important to check the value of $status after every call to filter_read or filter_read_exact.

filter_del

The function, filter_del, is used to disable the current filter. It does not affect the running of the filter. All it does is tell Perl not to call filter any more.

See Example 4: Using filter_del for details.

EXAMPLES

Here are a few examples which illustrate the key concepts - as such most of them are of little practical use.

The examples sub-directory has copies of all these filters implemented both as method filters and as closure filters.

Example 1: A simple filter.

Below is a method filter which is hard-wired to replace all occurrences of the string "Joe" to "Jim". Not particularly Useful, but it is the first example and I wanted to keep it simple.

    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" ;

And this is what the script above will print:

    Where is Jim?

Example 2: Using the context

The previous example was not particularly useful. To make it more general purpose we will make use of the context data and allow any arbitrary from and to strings to be used. This time we will use a closure filter. To reflect its enhanced role, the filter is called Subst.

    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 filter

Here is a filter which a variation of the Joe2Jim 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 ($status is zero) the filter will insert an extra line into the source stream. When this extra line is executed it will print a count of the number of substitutions actually made. Note that $status is set to 1 in this case.

    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 it:

    use Count ;
    print "Hello Joe\n" ;
    print "Where is Joe\n" ;

Outputs:

    Hello Jim
    Where is Jim
    Made 2 substitutions

Example 4: Using filter_del

Another variation on a theme. This time we will modify the Subst 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 the equivalent of 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 ;

Filter::Simple

If you intend using the Filter::Call functionality, I would strongly recommend that you check out Damian Conway's excellent Filter::Simple module. Damian's module provides a much cleaner interface than Filter::Util::Call. Although it doesn't allow the fine control that Filter::Util::Call does, it should be adequate for the majority of applications. It's available at

   http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz
   http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz

AUTHOR

Paul Marquess

DATE

26th January 1996


FindBin - Locate directory of original perl script

  • EXPORTABLE VARIABLES
  • KNOWN ISSUES
  • KNOWN BUGS
  • AUTHORS
  • COPYRIGHT

NAME

FindBin - Locate directory of original perl script

SYNOPSIS

 use FindBin;
 use lib "$FindBin::Bin/../lib";

 or
 use FindBin qw($Bin);
 use lib "$Bin/../lib";

DESCRIPTION

Locates the full path to the script bin directory to allow the use of paths relative to the bin directory.

This allows a user to setup a directory tree for some software with directories <root>/bin and <root>/lib, and then the above example will allow the use of modules in the lib directory without knowing where the software tree is installed.

If perl is invoked using the -e option or the perl script is read from STDIN then FindBin sets both $Bin and $RealBin to the current directory.

EXPORTABLE VARIABLES

 $Bin         - path to bin directory from where script was invoked
 $Script      - basename of script from which perl was invoked
 $RealBin     - $Bin with all links resolved
 $RealScript  - $Script with all links resolved

KNOWN ISSUES

If there are two modules using FindBin from different directories under the same interpreter, this won't work. Since FindBin uses a BEGIN block, it'll be executed only once, and only the first caller will get it right. This is a problem under mod_perl and other persistent Perl environments, where you shouldn't use this module. Which also means that you should avoid using FindBin in modules that you plan to put on CPAN. To make sure that FindBin will work is to call the again function:

  use FindBin;
  FindBin::again(); # or FindBin->again;

In former versions of FindBin there was no again function. The workaround was to force the BEGIN block to be executed again:

  delete $INC{'FindBin.pm'};
  require FindBin;

KNOWN BUGS

If perl is invoked as

   perl filename

and filename does not have executable rights and a program called filename exists in the users $ENV{PATH} which satisfies both -x and -T then FindBin assumes that it was invoked via the $ENV{PATH}.

Workaround is to invoke perl as

 perl ./filename

AUTHORS

FindBin is supported as part of the core perl distribution. Please send bug reports to <perlbug@perl.org> using the perlbug program included with perl.

Graham Barr <gbarr@pobox.com> Nick Ing-Simmons <nik@tiuk.ti.com>

COPYRIGHT

Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Font::AFM - Interface to Adobe Font Metrics files

  • ENVIRONMENT
  • BUGS
  • COPYRIGHT

NAME

Font::AFM - Interface to Adobe Font Metrics files

SYNOPSIS

 use Font::AFM;
 $h = new Font::AFM "Helvetica";
 $copyright = $h->Notice;
 $w = $h->Wx->{"aring"};
 $w = $h->stringwidth("Gisle", 10);
 $h->dump;  # for debugging

DESCRIPTION

This module implements the Font::AFM class. Objects of this class are initialised from an AFM (Adobe Font Metrics) file and allow you to obtain information about the font and the metrics of the various glyphs in the font.

All measurements in AFM files are given in terms of units equal to 1/1000 of the scale factor of the font being used. To compute actual sizes in a document, these amounts should be multiplied by (scale factor of font)/1000.

The following methods are available:

$afm = Font::AFM->new($fontname)

Object constructor. Takes the name of the font as argument. Croaks if the font can not be found.

$afm->latin1_wx_table()

Returns a 256-element array, where each element contains the width of the corresponding character in the iso-8859-1 character set.

$afm->stringwidth($string, [$fontsize])

Returns the width of the argument string. The string is assumed to be encoded in the iso-8859-1 character set. A second argument can be used to scale the width according to the font size.

$afm->FontName

The name of the font as presented to the PostScript language findfont operator, for instance "Times-Roman".

$afm->FullName

Unique, human-readable name for an individual font, for instance "Times Roman".

$afm->FamilyName

Human-readable name for a group of fonts that are stylistic variants of a single design. All fonts that are members of such a group should have exactly the same FamilyName. Example of a family name is "Times".

$afm->Weight

Human-readable name for the weight, or "boldness", attribute of a font. Examples are Roman, Bold, Light.

$afm->ItalicAngle

Angle in degrees counterclockwise from the vertical of the dominant vertical strokes of the font.

$afm->IsFixedPitch

If true, the font is a fixed-pitch (monospaced) font.

$afm->FontBBox

A string of four numbers giving the lower-left x, lower-left y, upper-right x, and upper-right y of the font bounding box. The font bounding box is the smallest rectangle enclosing the shape that would result if all the characters of the font were placed with their origins coincident, and then painted.

$afm->UnderlinePosition

Recommended distance from the baseline for positioning underline strokes. This number is the y coordinate of the center of the stroke.

$afm->UnderlineThickness

Recommended stroke width for underlining.

$afm->Version

Version number of the font.

$afm->Notice

Trademark or copyright notice, if applicable.

$afm->Comment

Comments found in the AFM file.

$afm->EncodingScheme

The name of the standard encoding scheme for the font. Most Adobe fonts use the AdobeStandardEncoding. Special fonts might state FontSpecific.

$afm->CapHeight

Usually the y-value of the top of the capital H.

$afm->XHeight

Typically the y-value of the top of the lowercase x.

$afm->Ascender

Typically the y-value of the top of the lowercase d.

$afm->Descender

Typically the y-value of the bottom of the lowercase p.

$afm->Wx

Returns a hash table that maps from glyph names to the width of that glyph.

$afm->BBox

Returns a hash table that maps from glyph names to bounding box information. The bounding box consist of four numbers: llx, lly, urx, ury.

$afm->dump

Dumps the content of the Font::AFM object to STDOUT. Might sometimes be useful for debugging.

The AFM specification can be found at:

   http://partners.adobe.com/asn/developer/pdfs/tn/5004.AFM_Spec.pdf

ENVIRONMENT

METRICS

Contains the path to search for AFM-files. Format is as for the PATH environment variable. The default path built into this library is:

 /usr/lib/afm:/usr/local/lib/afm:/usr/openwin/lib/fonts/afm/:.

BUGS

Kerning data and composite character data are not yet parsed. Ligature data is not parsed.

COPYRIGHT

Copyright 1995-1998 Gisle Aas. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Getopt::Long - Extended processing of command line options

  • Command Line Options, an Introduction
  • Getting Started with Getopt::Long
    • Simple options
    • A little bit less simple options
    • Mixing command line option with other arguments
    • Options with values
    • Options with multiple values
    • Options with hash values
    • User-defined subroutines to handle options
    • Options with multiple names
    • Case and abbreviations
    • Summary of Option Specifications
  • Advanced Possibilities
    • Object oriented interface
    • Thread Safety
    • Documentation and help texts
    • Storing option values in a hash
    • Bundling
    • The lonesome dash
    • Argument callback
  • Configuring Getopt::Long
  • Exportable Methods
  • Return values and Errors
  • Legacy
    • Default destinations
    • Alternative option starters
    • Configuration variables
  • Trouble Shooting
    • GetOptions does not return a false result when an option is not supplied
    • GetOptions does not split the command line correctly
    • Undefined subroutine &main::GetOptions called
    • How do I put a "-?" option into a Getopt::Long?
  • AUTHOR
  • COPYRIGHT AND DISCLAIMER

NAME

Getopt::Long - Extended processing of command line options

SYNOPSIS

  use Getopt::Long;
  my $data   = "file.dat";
  my $length = 24;
  my $verbose;
  $result = GetOptions ("length=i" => \$length,    # numeric
                        "file=s"   => \$data,      # string
                        "verbose"  => \$verbose);  # flag

DESCRIPTION

The Getopt::Long module implements an extended getopt function called GetOptions(). This function adheres to the POSIX syntax for command line options, with GNU extensions. In general, this means that options have long names instead of single letters, and are introduced with a double dash "--". Support for bundling of command line options, as was the case with the more traditional single-letter approach, is provided but not enabled by default.

Command Line Options, an Introduction

Command line operated programs traditionally take their arguments from the command line, for example filenames or other information that the program needs to know. Besides arguments, these programs often take command line options as well. Options are not necessary for the program to work, hence the name 'option', but are used to modify its default behaviour. For example, a program could do its job quietly, but with a suitable option it could provide verbose information about what it did.

Command line options come in several flavours. Historically, they are preceded by a single dash -, and consist of a single letter.

    -l -a -c

Usually, these single-character options can be bundled:

    -lac

Options can have values, the value is placed after the option character. Sometimes with whitespace in between, sometimes not:

    -s 24 -s24

Due to the very cryptic nature of these options, another style was developed that used long names. So instead of a cryptic -l one could use the more descriptive --long. To distinguish between a bundle of single-character options and a long one, two dashes are used to precede the option name. Early implementations of long options used a plus + instead. Also, option values could be specified either like

    --size=24

or

    --size 24

The + form is now obsolete and strongly deprecated.

Getting Started with Getopt::Long

Getopt::Long is the Perl5 successor of newgetopt.pl. This was the first Perl module that provided support for handling the new style of command line options, hence the name Getopt::Long. This module also supports single-character options and bundling. Single character options may be any alphabetic character, a question mark, and a dash. Long options may consist of a series of letters, digits, and dashes. Although this is currently not enforced by Getopt::Long, multiple consecutive dashes are not allowed, and the option name must not end with a dash.

To use Getopt::Long from a Perl program, you must include the following line in your Perl program:

    use Getopt::Long;

This will load the core of the Getopt::Long module and prepare your program for using it. Most of the actual Getopt::Long code is not loaded until you really call one of its functions.

In the default configuration, options names may be abbreviated to uniqueness, case does not matter, and a single dash is sufficient, even for long option names. Also, options may be placed between non-option arguments. See Configuring Getopt::Long for more details on how to configure Getopt::Long.

Simple options

The most simple options are the ones that take no values. Their mere presence on the command line enables the option. Popular examples are:

    --all --verbose --quiet --debug

Handling simple options is straightforward:

    my $verbose = '';   # option variable with default value (false)
    my $all = '';       # option variable with default value (false)
    GetOptions ('verbose' => \$verbose, 'all' => \$all);

The call to GetOptions() parses the command line arguments that are present in @ARGV and sets the option variable to the value 1 if the option did occur on the command line. Otherwise, the option variable is not touched. Setting the option value to true is often called enabling the option.

The option name as specified to the GetOptions() function is called the option specification. Later we'll see that this specification can contain more than just the option name. The reference to the variable is called the option destination.

GetOptions() will return a true value if the command line could be processed successfully. Otherwise, it will write error messages to STDERR, and return a false result.

A little bit less simple options

Getopt::Long supports two useful variants of simple options: negatable options and incremental options.

A negatable option is specified with an exclamation mark ! after the option name:

    my $verbose = '';   # option variable with default value (false)
    GetOptions ('verbose!' => \$verbose);

Now, using --verbose on the command line will enable $verbose, as expected. But it is also allowed to use --noverbose, which will disable $verbose by setting its value to 0. Using a suitable default value, the program can find out whether $verbose is false by default, or disabled by using --noverbose.

An incremental option is specified with a plus + after the option name:

    my $verbose = '';   # option variable with default value (false)
    GetOptions ('verbose+' => \$verbose);

Using --verbose on the command line will increment the value of $verbose. This way the program can keep track of how many times the option occurred on the command line. For example, each occurrence of --verbose could increase the verbosity level of the program.

Mixing command line option with other arguments

Usually programs take command line options as well as other arguments, for example, file names. It is good practice to always specify the options first, and the other arguments last. Getopt::Long will, however, allow the options and arguments to be mixed and 'filter out' all the options before passing the rest of the arguments to the program. To stop Getopt::Long from processing further arguments, insert a double dash -- on the command line:

    --size 24 -- --all

In this example, --all will not be treated as an option, but passed to the program unharmed, in @ARGV.

Options with values

For options that take values it must be specified whether the option value is required or not, and what kind of value the option expects.

Three kinds of values are supported: integer numbers, floating point numbers, and strings.

If the option value is required, Getopt::Long will take the command line argument that follows the option and assign this to the option variable. If, however, the option value is specified as optional, this will only be done if that value does not look like a valid command line option itself.

    my $tag = '';       # option variable with default value
    GetOptions ('tag=s' => \$tag);

In the option specification, the option name is followed by an equals sign = and the letter s. The equals sign indicates that this option requires a value. The letter s indicates that this value is an arbitrary string. Other possible value types are i for integer values, and f for floating point values. Using a colon : instead of the equals sign indicates that the option value is optional. In this case, if no suitable value is supplied, string valued options get an empty string '' assigned, while numeric options are set to 0.

Options with multiple values

Options sometimes take several values. For example, a program could use multiple directories to search for library files:

    --library lib/stdlib --library lib/extlib

To accomplish this behaviour, simply specify an array reference as the destination for the option:

    GetOptions ("library=s" => \@libfiles);

Alternatively, you can specify that the option can have multiple values by adding a "@", and pass a scalar reference as the destination:

    GetOptions ("library=s@" => \$libfiles);

Used with the example above, @libfiles (or @$libfiles) would contain two strings upon completion: "lib/srdlib" and "lib/extlib", in that order. It is also possible to specify that only integer or floating point numbers are acceptable values.

Often it is useful to allow comma-separated lists of values as well as multiple occurrences of the options. This is easy using Perl's split() and join() operators:

    GetOptions ("library=s" => \@libfiles);
    @libfiles = split(/,/,join(',',@libfiles));

Of course, it is important to choose the right separator string for each purpose.

Warning: What follows is an experimental feature.

Options can take multiple values at once, for example

    --coordinates 52.2 16.4 --rgbcolor 255 255 149

This can be accomplished by adding a repeat specifier to the option specification. Repeat specifiers are very similar to the {...} repeat specifiers that can be used with regular expression patterns. For example, the above command line would be handled as follows:

    GetOptions('coordinates=f{2}' => \@coor, 'rgbcolor=i{3}' => \@color);

The destination for the option must be an array or array reference.

It is also possible to specify the minimal and maximal number of arguments an option takes. foo=s{2,4} indicates an option that takes at least two and at most 4 arguments. foo=s{,} indicates one or more values; foo:s{,} indicates zero or more option values.

Options with hash values

If the option destination is a reference to a hash, the option will take, as value, strings of the form key=value. The value will be stored with the specified key in the hash.

    GetOptions ("define=s" => \%defines);

Alternatively you can use:

    GetOptions ("define=s%" => \$defines);

When used with command line options:

    --define os=linux --define vendor=redhat

the hash %defines (or %$defines) will contain two keys, "os" with value "linux and "vendor" with value "redhat". It is also possible to specify that only integer or floating point numbers are acceptable values. The keys are always taken to be strings.

User-defined subroutines to handle options

Ultimate control over what should be done when (actually: each time) an option is encountered on the command line can be achieved by designating a reference to a subroutine (or an anonymous subroutine) as the option destination. When GetOptions() encounters the option, it will call the subroutine with two or three arguments. The first argument is the name of the option. For a scalar or array destination, the second argument is the value to be stored. For a hash destination, the second arguments is the key to the hash, and the third argument the value to be stored. It is up to the subroutine to store the value, or do whatever it thinks is appropriate.

A trivial application of this mechanism is to implement options that are related to each other. For example:

    my $verbose = '';   # option variable with default value (false)
    GetOptions ('verbose' => \$verbose,
                'quiet'   => sub { $verbose = 0 });

Here --verbose and --quiet control the same variable $verbose, but with opposite values.

If the subroutine needs to signal an error, it should call die() with the desired error message as its argument. GetOptions() will catch the die(), issue the error message, and record that an error result must be returned upon completion.

If the text of the error message starts with an exclamation mark ! it is interpreted specially by GetOptions(). There is currently one special command implemented: die("!FINISH") will cause GetOptions() to stop processing options, as if it encountered a double dash --.

Options with multiple names

Often it is user friendly to supply alternate mnemonic names for options. For example --height could be an alternate name for --length. Alternate names can be included in the option specification, separated by vertical bar | characters. To implement the above example:

    GetOptions ('length|height=f' => \$length);

The first name is called the primary name, the other names are called aliases. When using a hash to store options, the key will always be the primary name.

Multiple alternate names are possible.

Case and abbreviations

Without additional configuration, GetOptions() will ignore the case of option names, and allow the options to be abbreviated to uniqueness.

    GetOptions ('length|height=f' => \$length, "head" => \$head);

This call will allow --l and --L for the length option, but requires a least --hea and --hei for the head and height options.

Summary of Option Specifications

Each option specifier consists of two parts: the name specification and the argument specification.

The name specification contains the name of the option, optionally followed by a list of alternative names separated by vertical bar characters.

    length            option name is "length"
    length|size|l     name is "length", aliases are "size" and "l"

The argument specification is optional. If omitted, the option is considered boolean, a value of 1 will be assigned when the option is used on the command line.

The argument specification can be

!

The option does not take an argument and may be negated by prefixing it with "no" or "no-". E.g. "foo!" will allow --foo (a value of 1 will be assigned) as well as --nofoo and --no-foo (a value of 0 will be assigned). If the option has aliases, this applies to the aliases as well.

Using negation on a single letter option when bundling is in effect is pointless and will result in a warning.

+

The option does not take an argument and will be incremented by 1 every time it appears on the command line. E.g. "more+", when used with --more --more --more, will increment the value three times, resulting in a value of 3 (provided it was 0 or undefined at first).

The + specifier is ignored if the option destination is not a scalar.

= type [ desttype ] [ repeat ]

The option requires an argument of the given type. Supported types are:

s

String. An arbitrary sequence of characters. It is valid for the argument to start with - or --.

i

Integer. An optional leading plus or minus sign, followed by a sequence of digits.

o

Extended integer, Perl style. This can be either an optional leading plus or minus sign, followed by a sequence of digits, or an octal string (a zero, optionally followed by '0', '1', .. '7'), or a hexadecimal string (0x followed by '0' .. '9', 'a' .. 'f', case insensitive), or a binary string (0b followed by a series of '0' and '1').

f

Real number. For example 3.14, -6.23E24 and so on.

The desttype can be @ or % to specify that the option is list or a hash valued. This is only needed when the destination for the option value is not otherwise specified. It should be omitted when not needed.

The repeat specifies the number of values this option takes per occurrence on the command line. It has the format { [ min ] [ , [ max ] ] }.

min denotes the minimal number of arguments. It defaults to 1 for options with = and to 0 for options with :, see below. Note that min overrules the = / : semantics.

max denotes the maximum number of arguments. It must be at least min. If max is omitted, but the comma is not, there is no upper bound to the number of argument values taken.

: type [ desttype ]

Like =, but designates the argument as optional. If omitted, an empty string will be assigned to string values options, and the value zero to numeric options.

Note that if a string argument starts with - or --, it will be considered an option on itself.

: number [ desttype ]

Like :i, but if the value is omitted, the number will be assigned.

: + [ desttype ]

Like :i, but if the value is omitted, the current value for the option will be incremented.

Advanced Possibilities

Object oriented interface

Getopt::Long can be used in an object oriented way as well:

    use Getopt::Long;
    $p = new Getopt::Long::Parser;
    $p->configure(...configuration options...);
    if ($p->getoptions(...options descriptions...)) ...

Configuration options can be passed to the constructor:

    $p = new Getopt::Long::Parser
             config => [...configuration options...];

Thread Safety

Getopt::Long is thread safe when using ithreads as of Perl 5.8. It is not thread safe when using the older (experimental and now obsolete) threads implementation that was added to Perl 5.005.

Documentation and help texts

Getopt::Long encourages the use of Pod::Usage to produce help messages. For example:

    use Getopt::Long;
    use Pod::Usage;

    my $man = 0;
    my $help = 0;

    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
    pod2usage(1) if $help;
    pod2usage(-exitstatus => 0, -verbose => 2) if $man;

    __END__
    =head1 NAME
    sample - Using Getopt::Long and Pod::Usage
    =head1 SYNOPSIS
    sample [options] [file ...]
     Options:
       -help            brief help message
       -man             full documentation
    =head1 OPTIONS
    =over 8
    =item B<-help>
    Print a brief help message and exits.
    =item B<-man>
    Prints the manual page and exits.
    =back
    =head1 DESCRIPTION
    B<This program> will read the given input file(s) and do something
    useful with the contents thereof.
    =cut

See the Pod::Usage manpage for details.

Storing option values in a hash

Sometimes, for example when there are a lot of options, having a separate variable for each of them can be cumbersome. GetOptions() supports, as an alternative mechanism, storing options in a hash.

To obtain this, a reference to a hash must be passed as the first argument to GetOptions(). For each option that is specified on the command line, the option value will be stored in the hash with the option name as key. Options that are not actually used on the command line will not be put in the hash, on other words, exists($h{option}) (or defined()) can be used to test if an option was used. The drawback is that warnings will be issued if the program runs under use strict and uses $h{option} without testing with exists() or defined() first.

    my %h = ();
    GetOptions (\%h, 'length=i');       # will store in $h{length}

For options that take list or hash values, it is necessary to indicate this by appending an @ or % sign after the type:

    GetOptions (\%h, 'colours=s@');     # will push to @{$h{colours}}

To make things more complicated, the hash may contain references to the actual destinations, for example:

    my $len = 0;
    my %h = ('length' => \$len);
    GetOptions (\%h, 'length=i');       # will store in $len

This example is fully equivalent with:

    my $len = 0;
    GetOptions ('length=i' => \$len);   # will store in $len

Any mixture is possible. For example, the most frequently used options could be stored in variables while all other options get stored in the hash:

    my $verbose = 0;                    # frequently referred
    my $debug = 0;                      # frequently referred
    my %h = ('verbose' => \$verbose, 'debug' => \$debug);
    GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
    if ( $verbose ) { ... }
    if ( exists $h{filter} ) { ... option 'filter' was specified ... }

Bundling

With bundling it is possible to set several single-character options at once. For example if a, v and x are all valid options,

    -vax

would set all three.

Getopt::Long supports two levels of bundling. To enable bundling, a call to Getopt::Long::Configure is required.

The first level of bundling can be enabled with:

    Getopt::Long::Configure ("bundling");

Configured this way, single-character options can be bundled but long options must always start with a double dash -- to avoid ambiguity. For example, when vax, a, v and x are all valid options,

    -vax

would set a, v and x, but

    --vax

would set vax.

The second level of bundling lifts this restriction. It can be enabled with:

    Getopt::Long::Configure ("bundling_override");

Now, -vax would set the option vax.

When any level of bundling is enabled, option values may be inserted in the bundle. For example:

    -h24w80

is equivalent to

    -h 24 -w 80

When configured for bundling, single-character options are matched case sensitive while long options are matched case insensitive. To have the single-character options matched case insensitive as well, use:

    Getopt::Long::Configure ("bundling", "ignorecase_always");

It goes without saying that bundling can be quite confusing.

The lonesome dash

Normally, a lone dash - on the command line will not be considered an option. Option processing will terminate (unless "permute" is configured) and the dash will be left in @ARGV.

It is possible to get special treatment for a lone dash. This can be achieved by adding an option specification with an empty name, for example:

    GetOptions ('' => \$stdio);

A lone dash on the command line will now be a legal option, and using it will set variable $stdio.

Argument callback

A special option 'name' <> can be used to designate a subroutine to handle non-option arguments. When GetOptions() encounters an argument that does not look like an option, it will immediately call this subroutine and passes it one parameter: the argument name.

For example:

    my $width = 80;
    sub process { ... }
    GetOptions ('width=i' => \$width, '<>' => \&process);

When applied to the following command line:

    arg1 --width=72 arg2 --width=60 arg3

This will call
process("arg1") while $width is 80,
process("arg2") while $width is 72, and
process("arg3") while $width is 60.

This feature requires configuration option permute, see section Configuring Getopt::Long.

Configuring Getopt::Long

Getopt::Long can be configured by calling subroutine Getopt::Long::Configure(). This subroutine takes a list of quoted strings, each specifying a configuration option to be enabled, e.g. ignore_case, or disabled, e.g. no_ignore_case. Case does not matter. Multiple calls to Configure() are possible.

Alternatively, as of version 2.24, the configuration options may be passed together with the use statement:

    use Getopt::Long qw(:config no_ignore_case bundling);

The following options are available:

default

This option causes all configuration options to be reset to their default values.

posix_default

This option causes all configuration options to be reset to their default values as if the environment variable POSIXLY_CORRECT had been set.

auto_abbrev

Allow option names to be abbreviated to uniqueness. Default is enabled unless environment variable POSIXLY_CORRECT has been set, in which case auto_abbrev is disabled.

getopt_compat

Allow + to start options. Default is enabled unless environment variable POSIXLY_CORRECT has been set, in which case getopt_compat is disabled.

gnu_compat

gnu_compat controls whether --opt= is allowed, and what it should do. Without gnu_compat, --opt= gives an error. With gnu_compat, --opt= will give option opt and empty value. This is the way GNU getopt_long() does it.

gnu_getopt

This is a short way of setting gnu_compat bundling permute no_getopt_compat. With gnu_getopt, command line handling should be fully compatible with GNU getopt_long().

require_order

Whether command line arguments are allowed to be mixed with options. Default is disabled unless environment variable POSIXLY_CORRECT has been set, in which case require_order is enabled.

See also permute, which is the opposite of require_order.

permute

Whether command line arguments are allowed to be mixed with options. Default is enabled unless environment variable POSIXLY_CORRECT has been set, in which case permute is disabled. Note that permute is the opposite of require_order.

If permute is enabled, this means that

    --foo arg1 --bar arg2 arg3

is equivalent to

    --foo --bar arg1 arg2 arg3

If an argument callback routine is specified, @ARGV will always be empty upon successful return of GetOptions() since all options have been processed. The only exception is when -- is used:

    --foo arg1 --bar arg2 -- arg3

This will call the callback routine for arg1 and arg2, and then terminate GetOptions() leaving "arg2" in @ARGV.

If require_order is enabled, options processing terminates when the first non-option is encountered.

    --foo arg1 --bar arg2 arg3

is equivalent to

    --foo -- arg1 --bar arg2 arg3

If pass_through is also enabled, options processing will terminate at the first unrecognized option, or non-option, whichever comes first.

bundling (default: disabled)

Enabling this option will allow single-character options to be bundled. To distinguish bundles from long option names, long options must be introduced with -- and bundles with -.

Note that, if you have options a, l and all, and auto_abbrev enabled, possible arguments and option settings are:

    using argument               sets option(s)
    ------------------------------------------
    -a, --a                      a
    -l, --l                      l
    -al, -la, -ala, -all,...     a, l
    --al, --all                  all

The surprising part is that --a sets option a (due to auto completion), not all.

Note: disabling bundling also disables bundling_override.

bundling_override (default: disabled)

If bundling_override is enabled, bundling is enabled as with bundling but now long option names override option bundles.

Note: disabling bundling_override also disables bundling.

Note: Using option bundling can easily lead to unexpected results, especially when mixing long options and bundles. Caveat emptor.

ignore_case (default: enabled)

If enabled, case is ignored when matching long option names. If, however, bundling is enabled as well, single character options will be treated case-sensitive.

With ignore_case, option specifications for options that only differ in case, e.g., "foo" and "Foo", will be flagged as duplicates.

Note: disabling ignore_case also disables ignore_case_always.

ignore_case_always (default: disabled)

When bundling is in effect, case is ignored on single-character options also.

Note: disabling ignore_case_always also disables ignore_case.

auto_version (default:disabled)

Automatically provide support for the --version option if the application did not specify a handler for this option itself.

Getopt::Long will provide a standard version message that includes the program name, its version (if $main::VERSION is defined), and the versions of Getopt::Long and Perl. The message will be written to standard output and processing will terminate.

auto_version will be enabled if the calling program explicitly specified a version number higher than 2.32 in the use or require statement.

auto_help (default:disabled)

Automatically provide support for the --help and -? options if the application did not specify a handler for this option itself.

Getopt::Long will provide a help message using module the Pod::Usage manpage. The message, derived from the SYNOPSIS POD section, will be written to standard output and processing will terminate.

auto_help will be enabled if the calling program explicitly specified a version number higher than 2.32 in the use or require statement.

pass_through (default: disabled)

Options that are unknown, ambiguous or supplied with an invalid option value are passed through in @ARGV instead of being flagged as errors. This makes it possible to write wrapper scripts that process only part of the user supplied command line arguments, and pass the remaining options to some other program.

If require_order is enabled, options processing will terminate at the first unrecognized option, or non-option, whichever comes first. However, if permute is enabled instead, results can become confusing.

Note that the options terminator (default --), if present, will also be passed through in @ARGV.

prefix

The string that starts options. If a constant string is not sufficient, see prefix_pattern.

prefix_pattern

A Perl pattern that identifies the strings that introduce options. Default is --|-|\+ unless environment variable POSIXLY_CORRECT has been set, in which case it is --|-.

long_prefix_pattern

A Perl pattern that allows the disambiguation of long and short prefixes. Default is --.

Typically you only need to set this if you are using nonstandard prefixes and want some or all of them to have the same semantics as '--' does under normal circumstances.

For example, setting prefix_pattern to --|-|\+|\/ and long_prefix_pattern to --|\/ would add Win32 style argument handling.

debug (default: disabled)

Enable debugging output.

Exportable Methods

VersionMessage

This subroutine provides a standard version message. Its argument can be:

  • A string containing the text of a message to print before printing the standard message.

  • A numeric value corresponding to the desired exit status.

  • A reference to a hash.

If more than one argument is given then the entire argument list is assumed to be a hash. If a hash is supplied (either as a reference or as a list) it should contain one or more elements with the following keys:

-message
-msg

The text of a message to print immediately prior to printing the program's usage message.

-exitval

The desired exit status to pass to the exit() function. This should be an integer, or else the string "NOEXIT" to indicate that control should simply be returned without terminating the invoking process.

-output

A reference to a filehandle, or the pathname of a file to which the usage message should be written. The default is \*STDERR unless the exit value is less than 2 (in which case the default is \*STDOUT).

You cannot tie this routine directly to an option, e.g.:

    GetOptions("version" => \&VersionMessage);

Use this instead:

    GetOptions("version" => sub { VersionMessage() });
HelpMessage

This subroutine produces a standard help message, derived from the program's POD section SYNOPSIS using the Pod::Usage manpage. It takes the same arguments as VersionMessage(). In particular, you cannot tie it directly to an option, e.g.:

    GetOptions("help" => \&HelpMessage);

Use this instead:

    GetOptions("help" => sub { HelpMessage() });

Return values and Errors

Configuration errors and errors in the option definitions are signalled using die() and will terminate the calling program unless the call to Getopt::Long::GetOptions() was embedded in eval { ... }, or die() was trapped using $SIG{__DIE__}.

GetOptions returns true to indicate success. It returns false when the function detected one or more errors during option parsing. These errors are signalled using warn() and can be trapped with $SIG{__WARN__}.

Legacy

The earliest development of newgetopt.pl started in 1990, with Perl version 4. As a result, its development, and the development of Getopt::Long, has gone through several stages. Since backward compatibility has always been extremely important, the current version of Getopt::Long still supports a lot of constructs that nowadays are no longer necessary or otherwise unwanted. This section describes briefly some of these 'features'.

Default destinations

When no destination is specified for an option, GetOptions will store the resultant value in a global variable named opt_XXX, where XXX is the primary name of this option. When a progam executes under use strict (recommended), these variables must be pre-declared with our() or use vars.

    our $opt_length = 0;
    GetOptions ('length=i');    # will store in $opt_length

To yield a usable Perl variable, characters that are not part of the syntax for variables are translated to underscores. For example, --fpp-struct-return will set the variable $opt_fpp_struct_return. Note that this variable resides in the namespace of the calling program, not necessarily main. For example:

    GetOptions ("size=i", "sizes=i@");

with command line "-size 10 -sizes 24 -sizes 48" will perform the equivalent of the assignments

    $opt_size = 10;
    @opt_sizes = (24, 48);

Alternative option starters

A string of alternative option starter characters may be passed as the first argument (or the first argument after a leading hash reference argument).

    my $len = 0;
    GetOptions ('/', 'length=i' => $len);

Now the command line may look like:

    /length 24 -- arg

Note that to terminate options processing still requires a double dash --.

GetOptions() will not interpret a leading "<>" as option starters if the next argument is a reference. To force "<" and ">" as option starters, use "><". Confusing? Well, using a starter argument is strongly deprecated anyway.

Configuration variables

Previous versions of Getopt::Long used variables for the purpose of configuring. Although manipulating these variables still work, it is strongly encouraged to use the Configure routine that was introduced in version 2.17. Besides, it is much easier.

Trouble Shooting

GetOptions does not return a false result when an option is not supplied

That's why they're called 'options'.

GetOptions does not split the command line correctly

The command line is not split by GetOptions, but by the command line interpreter (CLI). On Unix, this is the shell. On Windows, it is COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.

It is important to know that these CLIs may behave different when the command line contains special characters, in particular quotes or backslashes. For example, with Unix shells you can use single quotes (') and double quotes (") to group words together. The following alternatives are equivalent on Unix:

    "two words"
    'two words'
    two\ words

In case of doubt, insert the following statement in front of your Perl program:

    print STDERR (join("|",@ARGV),"\n");

to verify how your CLI passes the arguments to the program.

Undefined subroutine &main::GetOptions called

Are you running Windows, and did you write

    use GetOpt::Long;

(note the capital 'O')?

How do I put a "-?" option into a Getopt::Long?

You can only obtain this using an alias, and Getopt::Long of at least version 2.13.

    use Getopt::Long;
    GetOptions ("help|?");    # -help and -? will both set $opt_help

AUTHOR

Johan Vromans <jvromans@squirrel.nl>

COPYRIGHT AND DISCLAIMER

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

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

If you do not have a copy of the GNU General Public License write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


getopts - Process single-character switches with switch clustering

  • -help and -version

NAME

getopt, getopts - Process single-character switches with switch clustering

SYNOPSIS

    use Getopt::Std;

    getopt('oDI');    # -o, -D & -I take arg.  Sets $opt_* as a side effect.
    getopt('oDI', \%opts);    # -o, -D & -I take arg.  Values in %opts
    getopts('oif:');  # -o & -i are boolean flags, -f takes an argument
                      # Sets $opt_* as a side effect.
    getopts('oif:', \%opts);  # options as above. Values in %opts

DESCRIPTION

The getopt() function processes single-character switches with switch clustering. Pass one argument which is a string containing all switches that take an argument. For each switch found, sets $opt_x (where x is the switch name) to the value of the argument if an argument is expected, or 1 otherwise. Switches which take an argument don't care whether there is a space between the switch and the argument.

The getopts() function is similar, but you should pass to it the list of all switches to be recognized. If unspecified switches are found on the command-line, the user will be warned that an unknown option was given.

Note that, if your code is running under the recommended use strict 'vars' pragma, you will need to declare these package variables with "our":

    our($opt_x, $opt_y);

For those of you who don't like additional global variables being created, getopt() and getopts() will also accept a hash reference as an optional second argument. Hash keys will be x (where x is the switch name) with key values the value of the argument or 1 if no argument is specified.

To allow programs to process arguments that look like switches, but aren't, both functions will stop processing switches when they see the argument --. The -- will be removed from @ARGV.

--help and --version

If - is not a recognized switch letter, getopts() supports arguments --help and --version. If main::HELP_MESSAGE() and/or main::VERSION_MESSAGE() are defined, they are called; the arguments are the output file handle, the name of option-processing package, its version, and the switches string. If the subroutines are not defined, an attempt is made to generate intelligent messages; for best results, define $main::VERSION.

If embedded documentation (in pod format, see the perlpod manpage) is detected in the script, --help will also show how to access the documentation.

Note that due to excessive paranoia, if $Getopt::Std::STANDARD_HELP_VERSION isn't true (the default is false), then the messages are printed on STDERR, and the processing continues after the messages are printed. This being the opposite of the standard-conforming behaviour, it is strongly recommended to set $Getopt::Std::STANDARD_HELP_VERSION to true.

One can change the output file handle of the messages by setting $Getopt::Std::OUTPUT_HELP_VERSION. One can print the messages of --help (without the Usage: line) and --version by calling functions help_mess() and version_mess() with the switches string as an argument.


Graphics::Magick - Perl extension for calling GraphicsMagick's libGraphicsMagick routines

  • AUTHOR
  • BUGS
  • SEE ALSO

NAME

Graphics::Magick - Perl extension for calling GraphicsMagick's libGraphicsMagick routines

SYNOPSIS

  use Graphics::Magick;
  p = new Graphics::Magick;
  p->Read("imagefile");
  p->Set(attribute => value, ...)
  ($a, ...) = p->Get("attribute", ...)
  p->routine(parameter => value, ...)
  p->Mogrify("Routine", parameter => value, ...)
  p->Write("filename");

DESCRIPTION

This Perl extension allows the reading, manipulation and writing of a large number of image file formats using the GraphicsMagick library. It was originally developed to be used by CGI scripts for Web pages.

A Web page has been set up for this extension. See:

        http://www.GraphicsMagick.org/www/perl.html

AUTHOR

Kyle Shorter magick@wizards.dupont.com

BUGS

Has all the bugs of GraphicsMagick and much, much more!

SEE ALSO

perl(1).


HTML::AsSubs - functions that construct a HTML syntax tree

  • ACKNOWLEDGEMENT
  • BUGS
  • SEE ALSO
  • Private Functions
    • _elem()

NAME

HTML::AsSubs - functions that construct a HTML syntax tree

SYNOPSIS

 use HTML::AsSubs;
 $h = body(
           h1("This is the heading"),
           p("This is the first paragraph which contains a ",
             a({href=>'link.html'}, "link"),
             " and an ",
             img({src=>'img.gif', alt=>'image'}),
             "."
            ),
          );
 print $h->as_HTML;

DESCRIPTION

This module exports functions that can be used to construct various HTML elements. The functions are named after the tags of the correponding HTML element and are all written in lower case. If the first argument is a hash reference then it will be used to initialize the attributes of this element. The remaining arguments are regarded as content.

For a similar idea (i.e., it's another case where the syntax tree of the Perl source mirrors the syntax tree of the HTML produced), see HTML::Element's new_from_lol method.

For what I now think is a cleaner implementation of this same idea, see the excellent module XML::Generator, which is what I suggest for actual real-life use. (I suggest this over HTML::AsSubs and over CGI.pm's HTML-making functions.)

ACKNOWLEDGEMENT

This module was inspired by the following message:

 Date: Tue, 4 Oct 1994 16:11:30 +0100
 Subject: Wow! I have a large lightbulb above my head!
 Take a moment to consider these lines:
 %OVERLOAD=( '""' => sub { join("", @{$_[0]}) } );

 sub html { my($type)=shift; bless ["<$type>", @_, "</$type>"]; }

 :-)  I *love* Perl 5!  Thankyou Larry and Ilya.
 Regards,
 Tim Bunce.
 p.s. If you didn't get it, think about recursive data types: html(html())
 p.p.s. I'll turn this into a much more practical example in a day or two.
 p.p.p.s. It's a pity that overloads are not inherited. Is this a bug?

BUGS

The exported link() function overrides the builtin link() function. The exported tr() function must be called using &tr(...) syntax because it clashes with the builtin tr/../../ operator.

SEE ALSO

the HTML::Element manpage, the XML::Generator manpage

Private Functions

_elem()

The _elem() function is wrapped by all the html 'tag' functions. It takes a tag-name, optional hashref of attributes and a list of content as parameters.


HTML::Element - Class for objects that represent HTML elements

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • HOW WE REPRESENT TREES
  • BASIC METHODS
    • $h = HTML::Element->new('tag', 'attrname' => 'value', ... )
    • $h->attr('attr') or $h->attr('attr', 'value')
    • $h->tag() or $h->tag('tagname')
    • $h->parent() or $h->parent($new_parent)
    • $h->content_list()
    • $h->content()
    • $h->content_array_ref()
    • $h->content_refs_list
    • $h->implicit() or $h->implicit($bool)
    • $h-> pos() or $h->pos($element)
    • $h->all_attr()
    • $h->all_attr_names()
    • $h->all_external_attr()
    • $h->all_external_attr_names()
    • $h->id() or $h->id($string)
    • $h->idf() or $h->idf($string)
  • STRUCTURE-MODIFYING METHODS
    • $h->push_content($element_or_text, ...)
    • $h->unshift_content($element_or_text, ...)
    • $h->splice_content($offset, $length, $element_or_text, ...)
    • $h->detach()
    • $h->detach_content()
    • $h->replace_with( $element_or_text, ... )
    • $h->preinsert($element_or_text...)
    • $h->postinsert($element_or_text...)
    • $h->replace_with_content()
    • $h->delete_content()
    • $h->delete()
    • $h->clone()
    • HTML::Element->clone_list(...nodes...)
    • $h->normalize_content
    • $h->delete_ignorable_whitespace()
    • $h->insert_element($element, $implicit)
  • DUMPING METHODS
    • $h-> dump()
    • $h-> dump(*FH) ; # or *FH{IO} or $fh_obj
    • $h->as_HTML() or $h->as_HTML($entities)
    • or $h->as_HTML($entities, $indent_char)
    • or $h->as_HTML($entities, $indent_char, \%optional_end_tags)
    • $h->as_text()
    • $h->as_text(skip_dels => 1)
    • $h->as_trimmed_text(...)
    • $h->as_XML()
    • $h->as_Lisp_form()
    • $h->starttag() or $h->starttag($entities)
    • $h->endtag()
  • SECONDARY STRUCTURAL METHODS
    • $h->is_inside('tag', ...) or $h->is_inside($element, ...)
    • $h->is_empty()
    • $h->pindex()
    • $h->left()
    • $h->right()
    • $h->address()
    • $h->address($address)
    • $h->depth()
    • $h->root()
    • $h->lineage()
    • $h->lineage_tag_names()
    • $h->descendants()
    • $h->descendents()
    • $h->find_by_tag_name('tag', ...)
    • $h->find('tag', ...)
    • $h->find_by_attribute('attribute', 'value')
    • $h->look_down( ...criteria... )
    • $h->look_up( ...criteria... )
    • $h->traverse(...options...)
    • $h->attr_get_i('attribute')
    • $h->attr_get_i('a1', 'a2', 'a3')
    • $h->tagname_map()
    • $h->extract_links() or $h->extract_links(@wantedTypes)
    • $h->simplify_pres
    • $h->same_as($i)
    • $h = HTML::Element->new_from_lol(ARRAYREF)
    • @elements = HTML::Element->new_from_lol(ARRAYREFS)
    • $h->objectify_text()
    • $h->deobjectify_text()
    • $h->number_lists()
    • $h->has_insane_linkage
  • BUGS
  • NOTES ON SUBCLASSING
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

HTML::Element - Class for objects that represent HTML elements

VERSION

Version 3.20

SYNOPSIS

    use HTML::Element;
    $a = HTML::Element->new('a', href => 'http://www.perl.com/');
    $a->push_content("The Perl Homepage");

    $tag = $a->tag;
    print "$tag starts out as:",  $a->starttag, "\n";
    print "$tag ends as:",  $a->endtag, "\n";
    print "$tag\'s href attribute is: ", $a->attr('href'), "\n";

    $links_r = $a->extract_links();
    print "Hey, I found ", scalar(@$links_r), " links.\n";

    print "And that, as HTML, is: ", $a->as_HTML, "\n";
    $a = $a->delete;

DESCRIPTION

(This class is part of the HTML::Tree dist.)

Objects of the HTML::Element class can be used to represent elements of HTML document trees. These objects have attributes, notably attributes that designates each element's parent and content. The content is an array of text segments and other HTML::Element objects. A tree with HTML::Element objects as nodes can represent the syntax tree for a HTML document.

HOW WE REPRESENT TREES

Consider this HTML document:

  <html lang='en-US'>
    <head>
      <title>Stuff</title>
      <meta name='author' content='Jojo'>
    </head>
    <body>
     <h1>I like potatoes!</h1>
    </body>
  </html>

Building a syntax tree out of it makes a tree-structure in memory that could be diagrammed as:

                     html (lang='en-US')
                      / \
                    /     \
                  /         \
                head        body
               /\               \
             /    \               \
           /        \               \
         title     meta              h1
          |       (name='author',     |
       "Stuff"    content='Jojo')    "I like potatoes"

This is the traditional way to diagram a tree, with the "root" at the top, and it's this kind of diagram that people have in mind when they say, for example, that "the meta element is under the head element instead of under the body element". (The same is also said with "inside" instead of "under" -- the use of "inside" makes more sense when you're looking at the HTML source.)

Another way to represent the above tree is with indenting:

  html (attributes: lang='en-US')
    head
      title
        "Stuff"
      meta (attributes: name='author' content='Jojo')
    body
      h1
        "I like potatoes"

Incidentally, diagramming with indenting works much better for very large trees, and is easier for a program to generate. The $tree->dump method uses indentation just that way.

However you diagram the tree, it's stored the same in memory -- it's a network of objects, each of which has attributes like so:

  element #1:  _tag: 'html'
               _parent: none
               _content: [element #2, element #5]
               lang: 'en-US'
  element #2:  _tag: 'head'
               _parent: element #1
               _content: [element #3, element #4]
  element #3:  _tag: 'title'
               _parent: element #2
               _content: [text segment "Stuff"]
  element #4   _tag: 'meta'
               _parent: element #2
               _content: none
               name: author
               content: Jojo
  element #5   _tag: 'body'
               _parent: element #1
               _content: [element #6]
  element #6   _tag: 'h1'
               _parent: element #5
               _content: [text segment "I like potatoes"]

The "treeness" of the tree-structure that these elements comprise is not an aspect of any particular object, but is emergent from the relatedness attributes (_parent and _content) of these element-objects and from how you use them to get from element to element.

While you could access the content of a tree by writing code that says "access the 'src' attribute of the root's first child's seventh child's third child", you're more likely to have to scan the contents of a tree, looking for whatever nodes, or kinds of nodes, you want to do something with. The most straightforward way to look over a tree is to "traverse" it; an HTML::Element method ($h->traverse) is provided for this purpose; and several other HTML::Element methods are based on it.

(For everything you ever wanted to know about trees, and then some, see Niklaus Wirth's Algorithms + Data Structures = Programs or Donald Knuth's The Art of Computer Programming, Volume 1.)

BASIC METHODS

$h = HTML::Element->new('tag', 'attrname' => 'value', ... )

This constructor method returns a new HTML::Element object. The tag name is a required argument; it will be forced to lowercase. Optionally, you can specify other initial attributes at object creation time.

$h->attr('attr') or $h->attr('attr', 'value')

Returns (optionally sets) the value of the given attribute of $h. The attribute name (but not the value, if provided) is forced to lowercase. If trying to read the value of an attribute not present for this element, the return value is undef. If setting a new value, the old value of that attribute is returned.

If methods are provided for accessing an attribute (like $h->tag for "_tag", $h->content_list, etc. below), use those instead of calling attr $h->attr, whether for reading or setting.

Note that setting an attribute to undef (as opposed to "", the empty string) actually deletes the attribute.

$h->tag() or $h->tag('tagname')

Returns (optionally sets) the tag name (also known as the generic identifier) for the element $h. In setting, the tag name is always converted to lower case.

There are four kinds of "pseudo-elements" that show up as HTML::Element objects:

Comment pseudo-elements

These are element objects with a $h->tag value of "~comment", and the content of the comment is stored in the "text" attribute ($h->attr("text")). For example, parsing this code with HTML::TreeBuilder...

  <!-- I like Pie.
     Pie is good
  -->

produces an HTML::Element object with these attributes:

  "_tag",
  "~comment",
  "text",
  " I like Pie.\n     Pie is good\n  "
Declaration pseudo-elements

Declarations (rarely encountered) are represented as HTML::Element objects with a tag name of "~declaration", and content in the "text" attribute. For example, this:

  <!DOCTYPE foo>

produces an element whose attributes include:

  "_tag", "~declaration", "text", "DOCTYPE foo"
Processing instruction pseudo-elements

PIs (rarely encountered) are represented as HTML::Element objects with a tag name of "~pi", and content in the "text" attribute. For example, this:

  <?stuff foo?>

produces an element whose attributes include:

  "_tag", "~pi", "text", "stuff foo?"

(assuming a recent version of HTML::Parser)

~literal pseudo-elements

These objects are not currently produced by HTML::TreeBuilder, but can be used to represent a "super-literal" -- i.e., a literal you want to be immune from escaping. (Yes, I just made that term up.)

That is, this is useful if you want to insert code into a tree that you plan to dump out with as_HTML, where you want, for some reason, to suppress as_HTML's normal behavior of amp-quoting text segments.

For example, this:

  my $literal = HTML::Element->new('~literal',
    'text' => 'x < 4 & y > 7'
  );
  my $span = HTML::Element->new('span');
  $span->push_content($literal);
  print $span->as_HTML;

prints this:

  <span>x < 4 & y > 7</span>

Whereas this:

  my $span = HTML::Element->new('span');
  $span->push_content('x < 4 & y > 7');
    # normal text segment
  print $span->as_HTML;

prints this:

  <span>x &lt; 4 &amp; y &gt; 7</span>

Unless you're inserting lots of pre-cooked code into existing trees, and dumping them out again, it's not likely that you'll find ~literal pseudo-elements useful.

$h->parent() or $h->parent($new_parent)

Returns (optionally sets) the parent (aka "container") for this element. The parent should either be undef, or should be another element.

You should not use this to directly set the parent of an element. Instead use any of the other methods under "Structure-Modifying Methods", below.

Note that not($h->parent) is a simple test for whether $h is the root of its subtree.

$h->content_list()

Returns a list of the child nodes of this element -- i.e., what nodes (elements or text segments) are inside/under this element. (Note that this may be an empty list.)

In a scalar context, this returns the count of the items, as you may expect.

$h->content()

This somewhat deprecated method returns the content of this element; but unlike content_list, this returns either undef (which you should understand to mean no content), or a reference to the array of content items, each of which is either a text segment (a string, i.e., a defined non-reference scalar value), or an HTML::Element object. Note that even if an arrayref is returned, it may be a reference to an empty array.

While older code should feel free to continue to use $h->content, new code should use $h->content_list in almost all conceivable cases. It is my experience that in most cases this leads to simpler code anyway, since it means one can say:

    @children = $h->content_list;

instead of the inelegant:

    @children = @{$h->content || []};

If you do use $h->content (or $h->content_array_ref), you should not use the reference returned by it (assuming it returned a reference, and not undef) to directly set or change the content of an element or text segment! Instead use content_refs_list or any of the other methods under "Structure-Modifying Methods", below.

$h->content_array_ref()

This is like content (with all its caveats and deprecations) except that it is guaranteed to return an array reference. That is, if the given node has no _content attribute, the content method would return that undef, but content_array_ref would set the given node's _content value to [] (a reference to a new, empty array), and return that.

$h->content_refs_list

This returns a list of scalar references to each element of $h's content list. This is useful in case you want to in-place edit any large text segments without having to get a copy of the current value of that segment value, modify that copy, then use the splice_content to replace the old with the new. Instead, here you can in-place edit:

    foreach my $item_r ($h->content_refs_list) {
        next if ref $$item_r;
        $$item_r =~ s/honour/honor/g;
    }

You could currently achieve the same affect with:

    foreach my $item (@{ $h->content_array_ref }) {
        # deprecated!
        next if ref $item;
        $item =~ s/honour/honor/g;
    }

...except that using the return value of $h->content or $h->content_array_ref to do that is deprecated, and just might stop working in the future.

$h->implicit() or $h->implicit($bool)

Returns (optionally sets) the "_implicit" attribute. This attribute is a flag that's used for indicating that the element was not originally present in the source, but was added to the parse tree (by HTML::TreeBuilder, for example) in order to conform to the rules of HTML structure.

$h->pos() or $h->pos($element)

Returns (and optionally sets) the "_pos" (for "current position") pointer of $h. This attribute is a pointer used during some parsing operations, whose value is whatever HTML::Element element at or under $h is currently "open", where $h->insert_element(NEW) will actually insert a new element.

(This has nothing to do with the Perl function called "pos", for controlling where regular expression matching starts.)

If you set $h->pos($element), be sure that $element is either $h, or an element under $h.

If you've been modifying the tree under $h and are no longer sure $h->pos is valid, you can enforce validity with:

    $h->pos(undef) unless $h->pos->is_inside($h);

$h->all_attr()

Returns all this element's attributes and values, as key-value pairs. This will include any "internal" attributes (i.e., ones not present in the original element, and which will not be represented if/when you call $h->as_HTML). Internal attributes are distinguished by the fact that the first character of their key (not value! key!) is an underscore ("_").

Example output of $h->all_attr() : '_parent', [object_value] , '_tag', 'em', 'lang', 'en-US', '_content', [array-ref value].

$h->all_attr_names()

Like all_attr, but only returns the names of the attributes.

Example output of $h->all_attr() : '_parent', '_tag', 'lang', '_content', .

$h->all_external_attr()

Like all_attr, except that internal attributes are not present.

$h->all_external_attr_names()

Like all_external_attr_names, except that internal attributes' names are not present.

$h->id() or $h->id($string)

Returns (optionally sets to $string) the "id" attribute. $h->id(undef) deletes the "id" attribute.

$h->idf() or $h->idf($string)

Just like the id method, except that if you call $h->idf() and no "id" attribute is defined for this element, then it's set to a likely-to-be-unique value, and returned. (The "f" is for "force".)

STRUCTURE-MODIFYING METHODS

These methods are provided for modifying the content of trees by adding or changing nodes as parents or children of other nodes.

$h->push_content($element_or_text, ...)

Adds the specified items to the end of the content list of the element $h. The items of content to be added should each be either a text segment (a string), an HTML::Element object, or an arrayref. Arrayrefs are fed thru $h->new_from_lol(that_arrayref) to convert them into elements, before being added to the content list of $h. This means you can say things concise things like:

  $body->push_content(
    ['br'],
    ['ul',
      map ['li', $_]
      qw(Peaches Apples Pears Mangos)
    ]
  );

See new_from_lol method's documentation, far below, for more explanation.

The push_content method will try to consolidate adjacent text segments while adding to the content list. That's to say, if $h's content_list is

  ('foo bar ', $some_node, 'baz!')

and you call

   $h->push_content('quack?');

then the resulting content list will be this:

  ('foo bar ', $some_node, 'baz!quack?')

and not this:

  ('foo bar ', $some_node, 'baz!', 'quack?')

If that latter is what you want, you'll have to override the feature of consolidating text by using splice_content, as in:

  $h->splice_content(scalar($h->content_list),0,'quack?');

Similarly, if you wanted to add 'Skronk' to the beginning of the content list, calling this:

   $h->unshift_content('Skronk');

then the resulting content list will be this:

  ('Skronkfoo bar ', $some_node, 'baz!')

and not this:

  ('Skronk', 'foo bar ', $some_node, 'baz!')

What you'd to do get the latter is:

  $h->splice_content(0,0,'Skronk');

$h->unshift_content($element_or_text, ...)

Just like push_content, but adds to the beginning of the $h element's content list.

The items of content to be added should each be either a text segment (a string), an HTML::Element object, or an arrayref (which is fed thru new_from_lol).

The unshift_content method will try to consolidate adjacent text segments while adding to the content list. See above for a discussion of this.

$h->splice_content($offset, $length, $element_or_text, ...)

Detaches the elements from $h's list of content-nodes, starting at $offset and continuing for $length items, replacing them with the elements of the following list, if any. Returns the elements (if any) removed from the content-list. If $offset is negative, then it starts that far from the end of the array, just like Perl's normal splice function. If $length and the following list is omitted, removes everything from $offset onward.

The items of content to be added (if any) should each be either a text segment (a string), an arrayref (which is fed thru new_from_lol), or an HTML::Element object that's not already a child of $h.

$h->detach()

This unlinks $h from its parent, by setting its 'parent' attribute to undef, and by removing it from the content list of its parent (if it had one). The return value is the parent that was detached from (or undef, if $h had no parent to start with). Note that neither $h nor its parent are explicitly destroyed.

$h->detach_content()

This unlinks all of $h's children from $h, and returns them. Note that these are not explicitly destroyed; for that, you can just use $h->delete_content.

$h->replace_with( $element_or_text, ... )

This replaces $h in its parent's content list with the nodes specified. The element $h (which by then may have no parent) is returned. This causes a fatal error if $h has no parent. The list of nodes to insert may contain $h, but at most once. Aside from that possible exception, the nodes to insert should not already be children of $h's parent.

Also, note that this method does not destroy $h -- use $h->replace_with(...)->delete if you need that.

$h->preinsert($element_or_text...)

Inserts the given nodes right BEFORE $h in $h's parent's content list. This causes a fatal error if $h has no parent. None of the given nodes should be $h or other children of $h. Returns $h.

$h->postinsert($element_or_text...)

Inserts the given nodes right AFTER $h in $h's parent's content list. This causes a fatal error if $h has no parent. None of the given nodes should be $h or other children of $h. Returns $h.

$h->replace_with_content()

This replaces $h in its parent's content list with its own content. The element $h (which by then has no parent or content of its own) is returned. This causes a fatal error if $h has no parent. Also, note that this does not destroy $h -- use $h->replace_with_content->delete if you need that.

$h->delete_content()

Clears the content of $h, calling $h->delete for each content element. Compare with $h->detach_content.

Returns $h.

$h->delete()

Detaches this element from its parent (if it has one) and explicitly destroys the element and all its descendants. The return value is undef.

Perl uses garbage collection based on reference counting; when no references to a data structure exist, it's implicitly destroyed -- i.e., when no value anywhere points to a given object anymore, Perl knows it can free up the memory that the now-unused object occupies.

But this fails with HTML::Element trees, because a parent element always holds references to its children, and its children elements hold references to the parent, so no element ever looks like it's not in use. So, to destroy those elements, you need to call $h->delete on the parent.

$h->clone()

Returns a copy of the element (whose children are clones (recursively) of the original's children, if any).

The returned element is parentless. Any '_pos' attributes present in the source element/tree will be absent in the copy. For that and other reasons, the clone of an HTML::TreeBuilder object that's in mid-parse (i.e, the head of a tree that HTML::TreeBuilder is elaborating) cannot (currently) be used to continue the parse.

You are free to clone HTML::TreeBuilder trees, just as long as: 1) they're done being parsed, or 2) you don't expect to resume parsing into the clone. (You can continue parsing into the original; it is never affected.)

HTML::Element->clone_list(...nodes...)

Returns a list consisting of a copy of each node given. Text segments are simply copied; elements are cloned by calling $it->clone on each of them.

Note that this must be called as a class method, not as an instance method. clone_list will croak if called as an instance method. You can also call it like so:

    ref($h)->clone_list(...nodes...)

$h->normalize_content

Normalizes the content of $h -- i.e., concatenates any adjacent text nodes. (Any undefined text segments are turned into empty-strings.) Note that this does not recurse into $h's descendants.

$h->delete_ignorable_whitespace()

This traverses under $h and deletes any text segments that are ignorable whitespace. You should not use this if $h under a 'pre' element.

$h->insert_element($element, $implicit)

Inserts (via push_content) a new element under the element at $h->pos(). Then updates $h->pos() to point to the inserted element, unless $element is a prototypically empty element like "br", "hr", "img", etc. The new $h->pos() is returned. This method is useful only if your particular tree task involves setting $h->pos().

DUMPING METHODS

$h->dump()

$h->dump(*FH) ; # or *FH{IO} or $fh_obj

Prints the element and all its children to STDOUT (or to a specified filehandle), in a format useful only for debugging. The structure of the document is shown by indentation (no end tags).

$h->as_HTML() or $h->as_HTML($entities)

or $h->as_HTML($entities, $indent_char)

or $h->as_HTML($entities, $indent_char, \%optional_end_tags)

Returns a string representing in HTML the element and its descendants. The optional argument $entities specifies a string of the entities to encode. For compatibility with previous versions, specify '<>&' here. If omitted or undef, all unsafe characters are encoded as HTML entities. See the HTML::Entities manpage for details.

If $indent_char is specified and defined, the HTML to be output is intented, using the string you specify (which you probably should set to "\t", or some number of spaces, if you specify it).

If \%optional_end_tags is specified and defined, it should be a reference to a hash that holds a true value for every tag name whose end tag is optional. Defaults to \%HTML::Element::optionalEndTag, which is an alias to %HTML::Tagset::optionalEndTag, which, at time of writing, contains true values for p, li, dt, dd. A useful value to pass is an empty hashref, {}, which means that no end-tags are optional for this dump. Otherwise, possibly consider copying %HTML::Tagset::optionalEndTag to a hash of your own, adding or deleting values as you like, and passing a reference to that hash.

$h->as_text()

$h->as_text(skip_dels => 1)

Returns a string consisting of only the text parts of the element's descendants.

Text under 'script' or 'style' elements is never included in what's returned. If skip_dels is true, then text content under "del" nodes is not included in what's returned.

$h->as_trimmed_text(...)

This is just like as_text(...) except that leading and trailing whitespace is deleted, and any internal whitespace is collapsed.

$h->as_XML()

Returns a string representing in XML the element and its descendants.

The XML is not indented.

$h->as_Lisp_form()

Returns a string representing the element and its descendants as a Lisp form. Unsafe characters are encoded as octal escapes.

The Lisp form is indented, and contains external ("href", etc.) as well as internal attributes ("_tag", "_content", "_implicit", etc.), except for "_parent", which is omitted.

Current example output for a given element:

  ("_tag" "img" "border" "0" "src" "pie.png" "usemap" "#main.map")

$h->starttag() or $h->starttag($entities)

Returns a string representing the complete start tag for the element. I.e., leading "<", tag name, attributes, and trailing ">". All values are surrounded with double-quotes, and appropriate characters are encoded. If $entities is omitted or undef, all unsafe characters are encoded as HTML entities. See the HTML::Entities manpage for details. If you specify some value for $entities, remember to include the double-quote character in it. (Previous versions of this module would basically behave as if '&">' were specified for $entities.)

$h->endtag()

Returns a string representing the complete end tag for this element. I.e., "</", tag name, and ">".

SECONDARY STRUCTURAL METHODS

These methods all involve some structural aspect of the tree; either they report some aspect of the tree's structure, or they involve traversal down the tree, or walking up the tree.

$h->is_inside('tag', ...) or $h->is_inside($element, ...)

Returns true if the $h element is, or is contained anywhere inside an element that is any of the ones listed, or whose tag name is any of the tag names listed.

$h->is_empty()

Returns true if $h has no content, i.e., has no elements or text segments under it. In other words, this returns true if $h is a leaf node, AKA a terminal node. Do not confuse this sense of "empty" with another sense that it can have in SGML/HTML/XML terminology, which means that the element in question is of the type (like HTML's "hr", "br", "img", etc.) that can't have any content.

That is, a particular "p" element may happen to have no content, so $that_p_element->is_empty will be true -- even though the prototypical "p" element isn't "empty" (not in the way that the prototypical "hr" element is).

If you think this might make for potentially confusing code, consider simply using the clearer exact equivalent: not($h->content_list)

$h->pindex()

Return the index of the element in its parent's contents array, such that $h would equal

  $h->parent->content->[$h->pindex]
  or
  ($h->parent->content_list)[$h->pindex]

assuming $h isn't root. If the element $h is root, then $h->pindex returns undef.

$h->left()

In scalar context: returns the node that's the immediate left sibling of $h. If $h is the leftmost (or only) child of its parent (or has no parent), then this returns undef.

In list context: returns all the nodes that're the left siblings of $h (starting with the leftmost). If $h is the leftmost (or only) child of its parent (or has no parent), then this returns empty-list.

(See also $h->preinsert(LIST).)

$h->right()

In scalar context: returns the node that's the immediate right sibling of $h. If $h is the rightmost (or only) child of its parent (or has no parent), then this returns undef.

In list context: returns all the nodes that're the right siblings of $h, starting with the leftmost. If $h is the rightmost (or only) child of its parent (or has no parent), then this returns empty-list.

(See also $h->postinsert(LIST).)

$h->address()

Returns a string representing the location of this node in the tree. The address consists of numbers joined by a '.', starting with '0', and followed by the pindexes of the nodes in the tree that are ancestors of $h, starting from the top.

So if the way to get to a node starting at the root is to go to child 2 of the root, then child 10 of that, and then child 0 of that, and then you're there -- then that node's address is "0.2.10.0".

As a bit of a special case, the address of the root is simply "0".

I forsee this being used mainly for debugging, but you may find your own uses for it.

$h->address($address)

This returns the node (whether element or text-segment) at the given address in the tree that $h is a part of. (That is, the address is resolved starting from $h->root.)

If there is no node at the given address, this returns undef.

You can specify "relative addressing" (i.e., that indexing is supposed to start from $h and not from $h->root) by having the address start with a period -- e.g., $h->address(".3.2") will look at child 3 of $h, and child 2 of that.

$h->depth()

Returns a number expressing $h's depth within its tree, i.e., how many steps away it is from the root. If $h has no parent (i.e., is root), its depth is 0.

$h->root()

Returns the element that's the top of $h's tree. If $h is root, this just returns $h. (If you want to test whether $h is the root, instead of asking what its root is, just test not($h->parent).)

$h->lineage()

Returns the list of $h's ancestors, starting with its parent, and then that parent's parent, and so on, up to the root. If $h is root, this returns an empty list.

If you simply want a count of the number of elements in $h's lineage, use $h->depth.

$h->lineage_tag_names()

Returns the list of the tag names of $h's ancestors, starting with its parent, and that parent's parent, and so on, up to the root. If $h is root, this returns an empty list. Example output: ('em', 'td', 'tr', 'table', 'body', 'html')

$h->descendants()

In list context, returns the list of all $h's descendant elements, listed in pre-order (i.e., an element appears before its content-elements). Text segments DO NOT appear in the list. In scalar context, returns a count of all such elements.

$h->descendents()

This is just an alias to the descendants method.

$h->find_by_tag_name('tag', ...)

In list context, returns a list of elements at or under $h that have any of the specified tag names. In scalar context, returns the first (in pre-order traversal of the tree) such element found, or undef if none.

$h->find('tag', ...)

This is just an alias to find_by_tag_name. (There was once going to be a whole find_* family of methods, but then look_down filled that niche, so there turned out not to be much reason for the verboseness of the name "find_by_tag_name".)

$h->find_by_attribute('attribute', 'value')

In a list context, returns a list of elements at or under $h that have the specified attribute, and have the given value for that attribute. In a scalar context, returns the first (in pre-order traversal of the tree) such element found, or undef if none.

This method is deprecated in favor of the more expressive look_down method, which new code should use instead.

$h->look_down( ...criteria... )

This starts at $h and looks thru its element descendants (in pre-order), looking for elements matching the criteria you specify. In list context, returns all elements that match all the given criteria; in scalar context, returns the first such element (or undef, if nothing matched).

There are three kinds of criteria you can specify:

(attr_name, attr_value)

This means you're looking for an element with that value for that attribute. Example: "alt", "pix!". Consider that you can search on internal attribute values too: "_tag", "p".

(attr_name, qr/.../)

This means you're looking for an element whose value for that attribute matches the specified Regexp object.

a coderef

This means you're looking for elements where coderef->(each_element) returns true. Example:

  my @wide_pix_images
    = $h->look_down(
                    "_tag", "img",
                    "alt", "pix!",
                    sub { $_[0]->attr('width') > 350 }
                   );

Note that (attr_name, attr_value) and (attr_name, qr/.../) criteria are almost always faster than coderef criteria, so should presumably be put before them in your list of criteria. That is, in the example above, the sub ref is called only for elements that have already passed the criteria of having a "_tag" attribute with value "img", and an "alt" attribute with value "pix!". If the coderef were first, it would be called on every element, and then what elements pass that criterion (i.e., elements for which the coderef returned true) would be checked for their "_tag" and "alt" attributes.

Note that comparison of string attribute-values against the string value in (attr_name, attr_value) is case-INsensitive! A criterion of ('align', 'right') will match an element whose "align" value is "RIGHT", or "right" or "rIGhT", etc.

Note also that look_down considers "" (empty-string) and undef to be different things, in attribute values. So this:

  $h->look_down("alt", "")

will find elements with an "alt" attribute, but where the value for the "alt" attribute is "". But this:

  $h->look_down("alt", undef)

is the same as:

  $h->look_down(sub { !defined($_[0]->attr('alt')) } )

That is, it finds elements that do not have an "alt" attribute at all (or that do have an "alt" attribute, but with a value of undef -- which is not normally possible).

Note that when you give several criteria, this is taken to mean you're looking for elements that match all your criterion, not just any of them. In other words, there is an implicit "and", not an "or". So if you wanted to express that you wanted to find elements with a "name" attribute with the value "foo" or with an "id" attribute with the value "baz", you'd have to do it like:

  @them = $h->look_down(
    sub {
      # the lcs are to fold case
      lc($_[0]->attr('name')) eq 'foo'
      or lc($_[0]->attr('id')) eq 'baz'
    }
  );

Coderef criteria are more expressive than (attr_name, attr_value) and (attr_name, qr/.../) criteria, and all (attr_name, attr_value) and (attr_name, qr/.../) criteria could be expressed in terms of coderefs. However, (attr_name, attr_value) and (attr_name, qr/.../) criteria are a convenient shorthand. (In fact, look_down itself is basically "shorthand" too, since anything you can do with look_down you could do by traversing the tree, either with the traverse method or with a routine of your own. However, look_down often makes for very concise and clear code.)

$h->look_up( ...criteria... )

This is identical to $h->look_down, except that whereas $h->look_down basically scans over the list:

   ($h, $h->descendants)

$h->look_up instead scans over the list

   ($h, $h->lineage)

So, for example, this returns all ancestors of $h (possibly including $h itself) that are "td" elements with an "align" attribute with a value of "right" (or "RIGHT", etc.):

   $h->look_up("_tag", "td", "align", "right");

$h->traverse(...options...)

Lengthy discussion of HTML::Element's unnecessary and confusing traverse method has been moved to a separate file: the HTML::Element::traverse manpage

$h->attr_get_i('attribute')

In list context, returns a list consisting of the values of the given attribute for $self and for all its ancestors starting from $self and working its way up. Nodes with no such attribute are skipped. ("attr_get_i" stands for "attribute get, with inheritance".) In scalar context, returns the first such value, or undef if none.

Consider a document consisting of:

   <html lang='i-klingon'>
     <head><title>Pati Pata</title></head>
     <body>
       <h1 lang='la'>Stuff</h1>
       <p lang='es-MX' align='center'>
         Foo bar baz <cite>Quux</cite>.
       </p>
       <p>Hooboy.</p>
     </body>
   </html>

If $h is the "cite" element, $h->attr_get_i("lang") in list context will return the list ('es-MX', 'i-klingon'). In scalar context, it will return the value 'es-MX'.

If you call with multiple attribute names...

$h->attr_get_i('a1', 'a2', 'a3')

...in list context, this will return a list consisting of the values of these attributes which exist in $self and its ancestors. In scalar context, this returns the first value (i.e., the value of the first existing attribute from the first element that has any of the attributes listed). So, in the above example,

  $h->attr_get_i('lang', 'align');

will return:

   ('es-MX', 'center', 'i-klingon') # in list context
  or
   'es-MX' # in scalar context.

But note that this:

 $h->attr_get_i('align', 'lang');

will return:

   ('center', 'es-MX', 'i-klingon') # in list context
  or
   'center' # in scalar context.

$h->tagname_map()

Scans across $h and all its descendants, and makes a hash (a reference to which is returned) where each entry consists of a key that's a tag name, and a value that's a reference to a list to all elements that have that tag name. I.e., this method returns:

   {
     # Across $h and all descendants...
     'a'   => [ ...list of all 'a'   elements... ],
     'em'  => [ ...list of all 'em'  elements... ],
     'img' => [ ...list of all 'img' elements... ],
   }

(There are entries in the hash for only those tagnames that occur at/under $h -- so if there's no "img" elements, there'll be no "img" entry in the hashr(ref) returned.)

Example usage:

    my $map_r = $h->tagname_map();
    my @heading_tags = sort grep m/^h\d$/s, keys %$map_r;
    if(@heading_tags) {
      print "Heading levels used: @heading_tags\n";
    } else {
      print "No headings.\n"
    }

$h->extract_links() or $h->extract_links(@wantedTypes)

Returns links found by traversing the element and all of its children and looking for attributes (like "href" in an "a" element, or "src" in an "img" element) whose values represent links. The return value is a reference to an array. Each element of the array is reference to an array with four items: the link-value, the element that has the attribute with that link-value, and the name of that attribute, and the tagname of that element. (Example: ['http://www.suck.com/', $elem_obj , 'href', 'a'].) You may or may not end up using the element itself -- for some purposes, you may use only the link value.

You might specify that you want to extract links from just some kinds of elements (instead of the default, which is to extract links from all the kinds of elements known to have attributes whose values represent links). For instance, if you want to extract links from only "a" and "img" elements, you could code it like this:

  for (@{  $e->extract_links('a', 'img')  }) {
      my($link, $element, $attr, $tag) = @$_;
      print
        "Hey, there's a $tag that links to "
        $link, ", in its $attr attribute, at ",
        $element->address(), ".\n";
  }

$h->simplify_pres

In text bits under PRE elements that are at/under $h, this routine nativizes all newlines, and expands all tabs.

That is, if you read a file with lines delimited by \cm\cj's, the text under PRE areas will have \cm\cj's instead of \n's. Calling $h->nativize_pre_newlines on such a tree will turn \cm\cj's into \n's.

Tabs are expanded to however many spaces it takes to get to the next 8th column -- the usual way of expanding them.

$h->same_as($i)

Returns true if $h and $i are both elements representing the same tree of elements, each with the same tag name, with the same explicit attributes (i.e., not counting attributes whose names start with "_"), and with the same content (textual, comments, etc.).

Sameness of descendant elements is tested, recursively, with $child1->same_as($child_2), and sameness of text segments is tested with $segment1 eq $segment2.

$h = HTML::Element->new_from_lol(ARRAYREF)

Resursively constructs a tree of nodes, based on the (non-cyclic) data structure represented by ARRAYREF, where that is a reference to an array of arrays (of arrays (of arrays (etc.))).

In each arrayref in that structure, different kinds of values are treated as follows:

  • Arrayrefs

    Arrayrefs are considered to designate a sub-tree representing children for the node constructed from the current arrayref.

  • Hashrefs

    Hashrefs are considered to contain attribute-value pairs to add to the element to be constructed from the current arrayref

  • Text segments

    Text segments at the start of any arrayref will be considered to specify the name of the element to be constructed from the current araryref; all other text segments will be considered to specify text segments as children for the current arrayref.

  • Elements

    Existing element objects are either inserted into the treelet constructed, or clones of them are. That is, when the lol-tree is being traversed and elements constructed based what's in it, if an existing element object is found, if it has no parent, then it is added directly to the treelet constructed; but if it has a parent, then $that_node->clone is added to the treelet at the appropriate place.

An example will hopefully make this more obvious:

  my $h = HTML::Element->new_from_lol(
    ['html',
      ['head',
        [ 'title', 'I like stuff!' ],
      ],
      ['body',
        {'lang', 'en-JP', _implicit => 1},
        'stuff',
        ['p', 'um, p < 4!', {'class' => 'par123'}],
        ['div', {foo => 'bar'}, '123'],
      ]
    ]
  );
  $h->dump;

Will print this:

  <html> @0
    <head> @0.0
      <title> @0.0.0
        "I like stuff!"
    <body lang="en-JP"> @0.1 (IMPLICIT)
      "stuff"
      <p class="par123"> @0.1.1
        "um, p < 4!"
      <div foo="bar"> @0.1.2
        "123"

And printing $h->as_HTML will give something like:

  <html><head><title>I like stuff!</title></head>
  <body lang="en-JP">stuff<p class="par123">um, p &lt; 4!
  <div foo="bar">123</div></body></html>

You can even do fancy things with map:

  $body->push_content(
    # push_content implicitly calls new_from_lol on arrayrefs...
    ['br'],
    ['blockquote',
      ['h2', 'Pictures!'],
      map ['p', $_],
      $body2->look_down("_tag", "img"),
        # images, to be copied from that other tree.
    ],
    # and more stuff:
    ['ul',
      map ['li', ['a', {'href'=>"$_.png"}, $_ ] ],
      qw(Peaches Apples Pears Mangos)
    ],
  );

@elements = HTML::Element->new_from_lol(ARRAYREFS)

Constructs several elements, by calling new_from_lol for every arrayref in the ARRAYREFS list.

  @elements = HTML::Element->new_from_lol(
    ['hr'],
    ['p', 'And there, on the door, was a hook!'],
  );
   # constructs two elements.

$h->objectify_text()

This turns any text nodes under $h from mere text segments (strings) into real objects, pseudo-elements with a tag-name of "~text", and the actual text content in an attribute called "text". (For a discussion of pseudo-elements, see the "tag" method, far above.) This method is provided because, for some purposes, it is convenient or necessary to be able, for a given text node, to ask what element is its parent; and clearly this is not possible if a node is just a text string.

Note that these "~text" objects are not recognized as text nodes by methods like as_text. Presumably you will want to call $h->objectify_text, perform whatever task that you needed that for, and then call $h->deobjectify_text before calling anything like $h->as_text.

$h->deobjectify_text()

This undoes the effect of $h->objectify_text. That is, it takes any "~text" pseudo-elements in the tree at/under $h, and deletes each one, replacing each with the content of its "text" attribute.

Note that if $h itself is a "~text" pseudo-element, it will be destroyed -- a condition you may need to treat specially in your calling code (since it means you can't very well do anything with $h after that). So that you can detect that condition, if $h is itself a "~text" pseudo-element, then this method returns the value of the "text" attribute, which should be a defined value; in all other cases, it returns undef.

(This method assumes that no "~text" pseudo-element has any children.)

$h->number_lists()

For every UL, OL, DIR, and MENU element at/under $h, this sets a "_bullet" attribute for every child LI element. For LI children of an OL, the "_bullet" attribute's value will be something like "4.", "d.", "D.", "IV.", or "iv.", depending on the OL element's "type" attribute. LI children of a UL, DIR, or MENU get their "_bullet" attribute set to "*". There should be no other LIs (i.e., except as children of OL, UL, DIR, or MENU elements), and if there are, they are unaffected.

$h->has_insane_linkage

This method is for testing whether this element or the elements under it have linkage attributes (_parent and _content) whose values are deeply aberrant: if there are undefs in a content list; if an element appears in the content lists of more than one element; if the _parent attribute of an element doesn't match its actual parent; or if an element appears as its own descendant (i.e., if there is a cyclicity in the tree).

This returns empty list (or false, in scalar context) if the subtree's linkage methods are sane; otherwise it returns two items (or true, in scalar context): the element where the error occurred, and a string describing the error.

This method is provided is mainly for debugging and troubleshooting -- it should be quite impossible for any document constructed via HTML::TreeBuilder to parse into a non-sane tree (since it's not the content of the tree per se that's in question, but whether the tree in memory was properly constructed); and it should be impossible for you to produce an insane tree just thru reasonable use of normal documented structure-modifying methods. But if you're constructing your own trees, and your program is going into infinite loops as during calls to traverse() or any of the secondary structural methods, as part of debugging, consider calling is_insane on the tree.

BUGS

* If you want to free the memory associated with a tree built of HTML::Element nodes, then you will have to delete it explicitly. See the $h->delete method, above.

* There's almost nothing to stop you from making a "tree" with cyclicities (loops) in it, which could, for example, make the traverse method go into an infinite loop. So don't make cyclicities! (If all you're doing is parsing HTML files, and looking at the resulting trees, this will never be a problem for you.)

* There's no way to represent comments or processing directives in a tree with HTML::Elements. Not yet, at least.

* There's (currently) nothing to stop you from using an undefined value as a text segment. If you're running under perl -w, however, this may make HTML::Element's code produce a slew of warnings.

NOTES ON SUBCLASSING

You are welcome to derive subclasses from HTML::Element, but you should be aware that the code in HTML::Element makes certain assumptions about elements (and I'm using "element" to mean ONLY an object of class HTML::Element, or of a subclass of HTML::Element):

* The value of an element's _parent attribute must either be undef or otherwise false, or must be an element.

* The value of an element's _content attribute must either be undef or otherwise false, or a reference to an (unblessed) array. The array may be empty; but if it has items, they must ALL be either mere strings (text segments), or elements.

* The value of an element's _tag attribute should, at least, be a string of printable characters.

Moreover, bear these rules in mind:

* Do not break encapsulation on objects. That is, access their contents only thru $obj->attr or more specific methods.

* You should think twice before completely overriding any of the methods that HTML::Element provides. (Overriding with a method that calls the superclass method is not so bad, though.)

SEE ALSO

the HTML::Tree manpage; the HTML::TreeBuilder manpage; the HTML::AsSubs manpage; the HTML::Tagset manpage; and, for the morbidly curious, the HTML::Element::traverse manpage.

COPYRIGHT

Copyright 1995-1998 Gisle Aas, 1999-2001 Sean M. Burke, 2005 Andy Lester.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Currently maintained by Andy Lester <andy at petdance.com>.

Original authors: Gisle Aas and Sean Burke.


HTML::Element::traverse - discussion of HTML::Element's traverse method

  • EXAMPLES
  • THE TRAVERSE METHOD
    • Traversing with Recursive Anonymous Routines
    • Doing Recursive Things Iteratively
    • Pruning and Whatnot
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

HTML::Element::traverse - discussion of HTML::Element's traverse method

SYNOPSIS

  # $element->traverse is unnecessary and obscure.
  #   Don't use it in new code.

DESCRIPTION

HTML::Element provides a method traverse that traverses the tree and calls user-specified callbacks for each node, in pre- or post-order. However, use of the method is quite superfluous: if you want to recursively visit every node in the tree, it's almost always simpler to write a subroutine does just that, than it is to bundle up the pre- and/or post-order code in callbacks for the traverse method.

EXAMPLES

Suppose you want to traverse at/under a node $tree and give elements an 'id' attribute unless they already have one.

You can use the traverse method:

  {
    my $counter = 'x0000';
    $start_node->traverse(
      [ # Callbacks;
        # pre-order callback:
        sub {
          my $x = $_[0];
          $x->attr('id', $counter++) unless defined $x->attr('id');
          return HTML::Element::OK; # keep traversing
        },
        # post-order callback:
        undef
      ],
      1, # don't call the callbacks for text nodes
    );
  }

or you can just be simple and clear (and not have to understand the calling format for traverse) by writing a sub that traverses the tree by just calling itself:

  {
    my $counter = 'x0000';
    sub give_id {
      my $x = $_[0];
      $x->attr('id', $counter++) unless defined $x->attr('id');
      foreach my $c ($x->content_list) {
        give_id($c) if ref $c; # ignore text nodes
      }
    };
    give_id($start_node);
  }

See, isn't that nice and clear?

But, if you really need to know:

THE TRAVERSE METHOD

The traverse() method is a general object-method for traversing a tree or subtree and calling user-specified callbacks. It accepts the following syntaxes:

$h->traverse(\&callback)
or $h->traverse(\&callback, $ignore_text)
or $h->traverse( [\&pre_callback,\&post_callback] , $ignore_text)

These all mean to traverse the element and all of its children. That is, this method starts at node $h, "pre-order visits" $h, traverses its children, and then will "post-order visit" $h. "Visiting" means that the callback routine is called, with these arguments:

    $_[0] : the node (element or text segment),
    $_[1] : a startflag, and
    $_[2] : the depth

If the $ignore_text parameter is given and true, then the pre-order call will not be happen for text content.

The startflag is 1 when we enter a node (i.e., in pre-order calls) and 0 when we leave the node (in post-order calls).

Note, however, that post-order calls don't happen for nodes that are text segments or are elements that are prototypically empty (like "br", "hr", etc.).

If we visit text nodes (i.e., unless $ignore_text is given and true), then when text nodes are visited, we will also pass two extra arguments to the callback:

    $_[3] : the element that's the parent
             of this text node
    $_[4] : the index of this text node
             in its parent's content list

Note that you can specify that the pre-order routine can be a different routine from the post-order one:

    $h->traverse( [\&pre_callback,\&post_callback], ...);

You can also specify that no post-order calls are to be made, by providing a false value as the post-order routine:

    $h->traverse([ \&pre_callback,0 ], ...);

And similarly for suppressing pre-order callbacks:

    $h->traverse([ 0,\&post_callback ], ...);

Note that these two syntaxes specify the same operation:

    $h->traverse([\&foo,\&foo], ...);
    $h->traverse( \&foo       , ...);

The return values from calls to your pre- or post-order routines are significant, and are used to control recursion into the tree.

These are the values you can return, listed in descending order of my estimation of their usefulness:

HTML::Element::OK, 1, or any other true value

...to keep on traversing.

Note that HTML::Element::OK et al are constants. So if you're running under use strict (as I hope you are), and you say: return HTML::Element::PRUEN the compiler will flag this as an error (an unallowable bareword, specifically), whereas if you spell PRUNE correctly, the compiler will not complain.

undef, 0, '0', '', or HTML::Element::PRUNE

...to block traversing under the current element's content. (This is ignored if received from a post-order callback, since by then the recursion has already happened.) If this is returned by a pre-order callback, no post-order callback for the current node will happen. (Recall that if your callback exits with just return;, it is returning undef -- at least in scalar context, and traverse always calls your callbacks in scalar context.)

HTML::Element::ABORT

...to abort the whole traversal immediately. This is often useful when you're looking for just the first node in the tree that meets some criterion of yours.

HTML::Element::PRUNE_UP

...to abort continued traversal into this node and its parent node. No post-order callback for the current or parent node will happen.

HTML::Element::PRUNE_SOFTLY

Like PRUNE, except that the post-order call for the current node is not blocked.

Almost every task to do with extracting information from a tree can be expressed in terms of traverse operations (usually in only one pass, and usually paying attention to only pre-order, or to only post-order), or operations based on traversing. (In fact, many of the other methods in this class are basically calls to traverse() with particular arguments.)

The source code for HTML::Element and HTML::TreeBuilder contain several examples of the use of the "traverse" method to gather information about the content of trees and subtrees.

(Note: you should not change the structure of a tree while you are traversing it.)

[End of documentation for the traverse() method]

Traversing with Recursive Anonymous Routines

Now, if you've been reading Structure and Interpretation of Computer Programs too much, maybe you even want a recursive lambda. Go ahead:

  {
    my $counter = 'x0000';
    my $give_id;
    $give_id = sub {
      my $x = $_[0];
      $x->attr('id', $counter++) unless defined $x->attr('id');
      foreach my $c ($x->content_list) {
        $give_id->($c) if ref $c; # ignore text nodes
      }
    };
    $give_id->($start_node);
    undef $give_id;
  }

It's a bit nutty, and it's still more concise than a call to the traverse method!

It is left as an exercise to the reader to figure out how to do the same thing without using a $give_id symbol at all.

It is also left as an exercise to the reader to figure out why I undefine $give_id, above; and why I could achieved the same effect with any of:

    $give_id = 'I like pie!';
       # or...
    $give_id = [];
       # or even;
    $give_id = sub { print "Mmmm pie!\n" };

But not:

    $give_id = sub { print "I'm $give_id and I like pie!\n" };
       # nor...
    $give_id = \$give_id;
       # nor...
    $give_id = { 'pie' => \$give_id, 'mode' => 'a la' };

Doing Recursive Things Iteratively

Note that you may at times see an iterative implementation of pre-order traversal, like so:

   {
     my @to_do = ($tree); # start-node
     while(@to_do) {
       my $this = shift @to_do;

       # "Visit" the node:
       $this->attr('id', $counter++)
        unless defined $this->attr('id');

       unshift @to_do, grep ref $_, $this->content_list;
        # Put children on the stack -- they'll be visited next
            }
          }

This can under certain circumstances be more efficient than just a normal recursive routine, but at the cost of being rather obscure. It gains efficiency by avoiding the overhead of function-calling, but since there are several method dispatches however you do it (to attr and content_list), the overhead for a simple function call is insignificant.

Pruning and Whatnot

The traverse method does have the fairly neat features of the ABORT, PRUNE_UP and PRUNE_SOFTLY signals. None of these can be implemented totally straightforwardly with recursive routines, but it is quite possible. ABORT-like behavior can be implemented either with using non-local returning with eval/die:

  my $died_on; # if you need to know where...
  sub thing {
    ... visits $_[0]...
    ... maybe set $died_on to $_[0] and die "ABORT_TRAV" ...
    ... else call thing($child) for each child...
    ...any post-order visiting $_[0]...
  }
  eval { thing($node) };
  if($@) {
    if($@ =~ m<^ABORT_TRAV>) {
      ...it died (aborted) on $died_on...
    } else {
      die $@; # some REAL error happened
    }
  }

or you can just do it with flags:

  my($abort_flag, $died_on);
  sub thing {
    ... visits $_[0]...
    ... maybe set $abort_flag = 1; $died_on = $_[0]; return;
    foreach my $c ($_[0]->content_list) {
      thing($c);
      return if $abort_flag;
    }
    ...any post-order visiting $_[0]...
    return;
  }

  $abort_flag = $died_on = undef;
  thing($node);
  ...if defined $abort_flag, it died on $died_on

SEE ALSO

the HTML::Element manpage

COPYRIGHT

Copyright 2000,2001 Sean M. Burke

AUTHOR

Sean M. Burke, <sburke@cpan.org>


HTML::Entities - Encode or decode strings with HTML entities

  • COPYRIGHT

NAME

HTML::Entities - Encode or decode strings with HTML entities

SYNOPSIS

 use HTML::Entities;

 $a = "V&aring;re norske tegn b&oslash;r &#230res";
 decode_entities($a);
 encode_entities($a, "\200-\377");

For example, this:

 $input = "vis-à-vis Beyoncé's naïve\npapier-mâché résumé";
 print encode_entities($input), "\n"

Prints this out:

 vis-&agrave;-vis Beyonc&eacute;'s na&iuml;ve
 papier-m&acirc;ch&eacute; r&eacute;sum&eacute;

DESCRIPTION

This module deals with encoding and decoding of strings with HTML character entities. The module provides the following functions:

decode_entities( $string, ... )

This routine replaces HTML entities found in the $string with the corresponding Unicode character. Under perl 5.6 and earlier only characters in the Latin-1 range are replaced. Unrecognized entities are left alone.

If multiple strings are provided as argument they are each decoded separately and the same number of strings are returned.

If called in void context the arguments are decoded in-place.

This routine is exported by default.

_decode_entities( $string, \%entity2char )
_decode_entities( $string, \%entity2char, $expand_prefix )

This will in-place replace HTML entities in $string. The %entity2char hash must be provided. Named entities not found in the %entity2char hash are left alone. Numeric entities are expanded unless their value overflow.

The keys in %entity2char are the entity names to be expanded and their values are what they should expand into. The values do not have to be single character strings. If a key has ";" as suffix, then occurrences in $string are only expanded if properly terminated with ";". Entities without ";" will be expanded regardless of how they are terminated for compatiblity with how common browsers treat entities in the Latin-1 range.

If $expand_prefix is TRUE then entities without trailing ";" in %entity2char will even be expanded as a prefix of a longer unrecognized name. The longest matching name in %entity2char will be used. This is mainly present for compatibility with an MSIE misfeature.

   $string = "foo&nbspbar";
   _decode_entities($string, { nb => "@", nbsp => "\xA0" }, 1);
   print $string;  # will print "foo bar"

This routine is exported by default.

encode_entities( $string )
encode_entities( $string, $unsafe_chars )

This routine replaces unsafe characters in $string with their entity representation. A second argument can be given to specify which characters to consider unsafe (i.e., which to escape). The default set of characters to encode are control chars, high-bit chars, and the <, &, >, ' and " characters. But this, for example, would encode just the <, &, >, and " characters:

  $encoded = encode_entities($input, '<>&"');

This routine is exported by default.

encode_entities_numeric( $string )
encode_entities_numeric( $string, $unsafe_chars )

This routine works just like encode_entities, except that the replacement entities are always &#xhexnum; and never &entname;. For example, encode_entities("r\xF4le") returns "r&ocirc;le", but encode_entities_numeric("r\xF4le") returns "r&#xF4;le".

This routine is not exported by default. But you can always export it with use HTML::Entities qw(encode_entities_numeric); or even use HTML::Entities qw(:DEFAULT encode_entities_numeric);

All these routines modify the string passed as the first argument, if called in a void context. In scalar and array contexts, the encoded or decoded string is returned (without changing the input string).

If you prefer not to import these routines into your namespace, you can call them as:

  use HTML::Entities ();
  $decoded = HTML::Entities::decode($a);
  $encoded = HTML::Entities::encode($a);
  $encoded = HTML::Entities::encode_numeric($a);

The module can also export the %char2entity and the %entity2char hashes, which contain the mapping from all characters to the corresponding entities (and vice versa, respectively).

COPYRIGHT

Copyright 1995-2006 Gisle Aas. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::Filter - Filter HTML text through the parser

  • NOTE
  • SYNOPSIS
  • DESCRIPTION
  • EXAMPLES
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::Filter - Filter HTML text through the parser

NOTE

This module is deprecated. The HTML::Parser now provides the functionally of HTML::Filter much more efficiently with the the default handler.

SYNOPSIS

 require HTML::Filter;
 $p = HTML::Filter->new->parse_file("index.html");

DESCRIPTION

HTML::Filter is an HTML parser that by default prints the original text of each HTML element (a slow version of cat(1) basically). The callback methods may be overridden to modify the filtering for some HTML elements and you can override output() method which is called to print the HTML text.

HTML::Filter is a subclass of HTML::Parser. This means that the document should be given to the parser by calling the $p->parse() or $p->parse_file() methods.

EXAMPLES

The first example is a filter that will remove all comments from an HTML file. This is achieved by simply overriding the comment method to do nothing.

  package CommentStripper;
  require HTML::Filter;
  @ISA=qw(HTML::Filter);
  sub comment { }  # ignore comments

The second example shows a filter that will remove any <TABLE>s found in the HTML file. We specialize the start() and end() methods to count table tags and then make output not happen when inside a table.

  package TableStripper;
  require HTML::Filter;
  @ISA=qw(HTML::Filter);
  sub start
  {
     my $self = shift;
     $self->{table_seen}++ if $_[0] eq "table";
     $self->SUPER::start(@_);
  }

  sub end
  {
     my $self = shift;
     $self->SUPER::end(@_);
     $self->{table_seen}-- if $_[0] eq "table";
  }

  sub output
  {
      my $self = shift;
      unless ($self->{table_seen}) {
          $self->SUPER::output(@_);
      }
  }

If you want to collect the parsed text internally you might want to do something like this:

  package FilterIntoString;
  require HTML::Filter;
  @ISA=qw(HTML::Filter);
  sub output { push(@{$_[0]->{fhtml}}, $_[1]) }
  sub filtered_html { join("", @{$_[0]->{fhtml}}) }

SEE ALSO

the HTML::Parser manpage

COPYRIGHT

Copyright 1997-1999 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::Form - Class that represents an HTML form element

  • INPUTS
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::Form - Class that represents an HTML form element

SYNOPSIS

 use HTML::Form;
 $form = HTML::Form->parse($html, $base_uri);
 $form->value(query => "Perl");

 use LWP::UserAgent;
 $ua = LWP::UserAgent->new;
 $response = $ua->request($form->click);

DESCRIPTION

Objects of the HTML::Form class represents a single HTML <form> ... </form> instance. A form consists of a sequence of inputs that usually have names, and which can take on various values. The state of a form can be tweaked and it can then be asked to provide HTTP::Request objects that can be passed to the request() method of LWP::UserAgent.

The following methods are available:

@forms = HTML::Form->parse( $response )
@forms = HTML::Form->parse( $html_document, $base )
@forms = HTML::Form->parse( $html_document, %opt )

The parse() class method will parse an HTML document and build up HTML::Form objects for each <form> element found. If called in scalar context only returns the first <form>. Returns an empty list if there are no forms to be found.

The $base is the URI used to retrieve the $html_document. It is needed to resolve relative action URIs. If the document was retrieved with LWP then this this parameter is obtained from the $response->base() method, as shown by the following example:

    my $ua = LWP::UserAgent->new;
    my $response = $ua->get("http://www.example.com/form.html");
    my @forms = HTML::Form->parse($response->decoded_content,
                                  $response->base);

The parse() method can parse from an HTTP::Response object directly, so the example above can be more conveniently written as:

    my $ua = LWP::UserAgent->new;
    my $response = $ua->get("http://www.example.com/form.html");
    my @forms = HTML::Form->parse($response);

Note that any object that implements a decoded_content() and base() method with similar behaviour as HTTP::Response will do.

Finally options might be passed in to control how the parse method behaves. The following options are currently recognized:

base

Another way to provide the base URI.

verbose

Print messages to STDERR about any bad HTML form constructs found.

$method = $form->method
$form->method( $new_method )

This method is gets/sets the method name used for the HTTP::Request generated. It is a string like "GET" or "POST".

$action = $form->action
$form->action( $new_action )

This method gets/sets the URI which we want to apply the request method to.

$enctype = $form->enctype
$form->enctype( $new_enctype )

This method gets/sets the encoding type for the form data. It is a string like "application/x-www-form-urlencoded" or "multipart/form-data".

$value = $form->attr( $name )
$form->attr( $name, $new_value )

This method give access to the original HTML attributes of the <form> tag. The $name should always be passed in lower case.

Example:

   @f = HTML::Form->parse( $html, $foo );
   @f = grep $_->attr("id") eq "foo", @f;
   die "No form named 'foo' found" unless @f;
   $foo = shift @f;
@inputs = $form->inputs

This method returns the list of inputs in the form. If called in scalar context it returns the number of inputs contained in the form. See INPUTS for what methods are available for the input objects returned.

$input = $form->find_input( $name )
$input = $form->find_input( $name, $type )
$input = $form->find_input( $name, $type, $index )

This method is used to locate specific inputs within the form. All inputs that match the arguments given are returned. In scalar context only the first is returned, or undef if none match.

If $name is specified, then the input must have the indicated name.

If $type is specified, then the input must have the specified type. The following type names are used: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" and "option".

The $index is the sequence number of the input matched where 1 is the first. If combined with $name and/or $type then it select the nth input with the given name and/or type.

$value = $form->value( $name )
$form->value( $name, $new_value )

The value() method can be used to get/set the value of some input. If no input has the indicated name, then this method will croak.

If multiple inputs have the same name, only the first one will be affected.

The call:

    $form->value('foo')

is a short-hand for:

    $form->find_input('foo')->value;
@names = $form->param
@values = $form->param( $name )
$form->param( $name, $value, ... )
$form->param( $name, \@values )

Alternative interface to examining and setting the values of the form.

If called without arguments then it returns the names of all the inputs in the form. The names will not repeat even if multiple inputs have the same name. In scalar context the number of different names is returned.

If called with a single argument then it returns the value or values of inputs with the given name. If called in scalar context only the first value is returned. If no input exists with the given name, then undef is returned.

If called with 2 or more arguments then it will set values of the named inputs. This form will croak if no inputs have the given name or if any of the values provided does not fit. Values can also be provided as a reference to an array. This form will allow unsetting all values with the given name as well.

This interface resembles that of the param() function of the CGI module.

$form->try_others( \&callback )

This method will iterate over all permutations of unvisited enumerated values (<select>, <radio>, <checkbox>) and invoke the callback for each. The callback is passed the $form as argument. The return value from the callback is ignored and the try_others() method itself does not return anything.

$request = $form->make_request

Will return an HTTP::Request object that reflects the current setting of the form. You might want to use the click() method instead.

$request = $form->click
$request = $form->click( $name )
$request = $form->click( $x, $y )
$request = $form->click( $name, $x, $y )

Will "click" on the first clickable input (which will be of type submit or image). The result of clicking is an HTTP::Request object that can then be passed to LWP::UserAgent if you want to obtain the server response.

If a $name is specified, we will click on the first clickable input with the given name, and the method will croak if no clickable input with the given name is found. If $name is not specified, then it is ok if the form contains no clickable inputs. In this case the click() method returns the same request as the make_request() method would do.

If there are multiple clickable inputs with the same name, then there is no way to get the click() method of the HTML::Form to click on any but the first. If you need this you would have to locate the input with find_input() and invoke the click() method on the given input yourself.

A click coordinate pair can also be provided, but this only makes a difference if you clicked on an image. The default coordinate is (1,1). The upper-left corner of the image is (0,0), but some badly coded CGI scripts are known to not recognize this. Therefore (1,1) was selected as a safer default.

@kw = $form->form

Returns the current setting as a sequence of key/value pairs. Note that keys might be repeated, which means that some values might be lost if the return values are assigned to a hash.

In scalar context this method returns the number of key/value pairs generated.

$form->dump

Returns a textual representation of current state of the form. Mainly useful for debugging. If called in void context, then the dump is printed on STDERR.

INPUTS

An HTML::Form objects contains a sequence of inputs. References to the inputs can be obtained with the $form->inputs or $form->find_input methods.

Note that there is not a one-to-one correspondence between input objects and <input> elements in the HTML document. An input object basically represents a name/value pair, so when multiple HTML elements contribute to the same name/value pair in the submitted form they are combined.

The input elements that are mapped one-to-one are "text", "textarea", "password", "hidden", "file", "image", "submit" and "checkbox". For the "radio" and "option" inputs the story is not as simple: All <input type="radio"> elements with the same name will contribute to the same input radio object. The number of radio input objects will be the same as the number of distinct names used for the <input type="radio"> elements. For a <select> element without the multiple attribute there will be one input object of type of "option". For a <select multiple> element there will be one input object for each contained <option> element. Each one of these option objects will have the same name.

The following methods are available for the input objects:

$input->type

Returns the type of this input. The type is one of the following strings: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" or "option".

$name = $input->name
$input->name( $new_name )

This method can be used to get/set the current name of the input.

$value = $input->value
$input->value( $new_value )

This method can be used to get/set the current value of an input.

If the input only can take an enumerated list of values, then it is an error to try to set it to something else and the method will croak if you try.

You will also be able to set the value of read-only inputs, but a warning will be generated if running under perl -w.

$input->possible_values

Returns a list of all values that an input can take. For inputs that do not have discrete values, this returns an empty list.

$input->other_possible_values

Returns a list of all values not tried yet.

$input->value_names

For some inputs the values can have names that are different from the values themselves. The number of names returned by this method will match the number of values reported by $input->possible_values.

When setting values using the value() method it is also possible to use the value names in place of the value itself.

$bool = $input->readonly
$input->readonly( $bool )

This method is used to get/set the value of the readonly attribute. You are allowed to modify the value of readonly inputs, but setting the value will generate some noise when warnings are enabled. Hidden fields always start out readonly.

$bool = $input->disabled
$input->disabled( $bool )

This method is used to get/set the value of the disabled attribute. Disabled inputs do not contribute any key/value pairs for the form value.

$input->form_name_value

Returns a (possible empty) list of key/value pairs that should be incorporated in the form value from this input.

$input->check

Some input types represent toggles that can be turned on/off. This includes "checkbox" and "option" inputs. Calling this method turns this input on without having to know the value name. If the input is already on, then nothing happens.

This has the same effect as:

    $input->value($input->possible_values[1]);

The input can be turned off with:

    $input->value(undef);
$input->click($form, $x, $y)

Some input types (currently "submit" buttons and "images") can be clicked to submit the form. The click() method returns the corresponding HTTP::Request object.

If the input is of type file, then it has these additional methods:

$input->file

This is just an alias for the value() method. It sets the filename to read data from.

$filename = $input->filename
$input->filename( $new_filename )

This get/sets the filename reported to the server during file upload. This attribute defaults to the value reported by the file() method.

$content = $input->content
$input->content( $new_content )

This get/sets the file content provided to the server during file upload. This method can be used if you do not want the content to be read from an actual file.

@headers = $input->headers
input->headers($key => $value, .... )

This get/set additional header fields describing the file uploaded. This can for instance be used to set the Content-Type reported for the file.

SEE ALSO

the LWP manpage, the LWP::UserAgent manpage, the HTML::Parser manpage

COPYRIGHT

Copyright 1998-2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::HeadParser - Parse <HEAD> section of a HTML document

  • METHODS
  • EXAMPLE
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::HeadParser - Parse <HEAD> section of a HTML document

SYNOPSIS

 require HTML::HeadParser;
 $p = HTML::HeadParser->new;
 $p->parse($text) and  print "not finished";

 $p->header('Title')          # to access <title>....</title>
 $p->header('Content-Base')   # to access <base href="http://...">
 $p->header('Foo')            # to access <meta http-equiv="Foo" content="...">

DESCRIPTION

The HTML::HeadParser is a specialized (and lightweight) HTML::Parser that will only parse the <HEAD>...</HEAD> section of an HTML document. The parse() method will return a FALSE value as soon as some <BODY> element or body text are found, and should not be called again after this.

Note that the HTML::HeadParser might get confused if raw undecoded UTF-8 is passed to the parse() method. Make sure the strings are properly decoded before passing them on.

The HTML::HeadParser keeps a reference to a header object, and the parser will update this header object as the various elements of the <HEAD> section of the HTML document are recognized. The following header fields are affected:

Content-Base:

The Content-Base header is initialized from the <base href="..."> element.

Title:

The Title header is initialized from the <title>...</title> element.

Isindex:

The Isindex header will be added if there is a <isindex> element in the <head>. The header value is initialized from the prompt attribute if it is present. If no prompt attribute is given it will have '?' as the value.

X-Meta-Foo:

All <meta> elements will initialize headers with the prefix "X-Meta-" on the name. If the <meta> element contains a http-equiv attribute, then it will be honored as the header name.

METHODS

The following methods (in addition to those provided by the superclass) are available:

$hp = HTML::HeadParser->new
$hp = HTML::HeadParser->new( $header )

The object constructor. The optional $header argument should be a reference to an object that implement the header() and push_header() methods as defined by the HTTP::Headers class. Normally it will be of some class that isa or delegates to the HTTP::Headers class.

If no $header is given HTML::HeadParser will create an HTTP::Header object by itself (initially empty).

$hp->header;

Returns a reference to the header object.

$hp->header( $key )

Returns a header value. It is just a shorter way to write $hp->header->header($key).

EXAMPLE

 $h = HTTP::Headers->new;
 $p = HTML::HeadParser->new($h);
 $p->parse(<<EOT);
 <title>Stupid example</title>
 <base href="http://www.linpro.no/lwp/">
 Normal text starts here.
 EOT
 undef $p;
 print $h->title;   # should print "Stupid example"

SEE ALSO

the HTML::Parser manpage, the HTTP::Headers manpage

The HTTP::Headers class is distributed as part of the libwww-perl package. If you don't have that distribution installed you need to provide the $header argument to the HTML::HeadParser constructor with your own object that implements the documented protocol.

COPYRIGHT

Copyright 1996-2001 Gisle Aas. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::LinkExtor - Extract links from an HTML document

  • EXAMPLE
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::LinkExtor - Extract links from an HTML document

SYNOPSIS

 require HTML::LinkExtor;
 $p = HTML::LinkExtor->new(\&cb, "http://www.perl.org/");
 sub cb {
     my($tag, %links) = @_;
     print "$tag @{[%links]}\n";
 }
 $p->parse_file("index.html");

DESCRIPTION

HTML::LinkExtor is an HTML parser that extracts links from an HTML document. The HTML::LinkExtor is a subclass of HTML::Parser. This means that the document should be given to the parser by calling the $p->parse() or $p->parse_file() methods.

$p = HTML::LinkExtor->new
$p = HTML::LinkExtor->new( $callback )
$p = HTML::LinkExtor->new( $callback, $base )

The constructor takes two optional arguments. The first is a reference to a callback routine. It will be called as links are found. If a callback is not provided, then links are just accumulated internally and can be retrieved by calling the $p->links() method.

The $base argument is an optional base URL used to absolutize all URLs found. You need to have the URI module installed if you provide $base.

The callback is called with the lowercase tag name as first argument, and then all link attributes as separate key/value pairs. All non-link attributes are removed.

$p->links

Returns a list of all links found in the document. The returned values will be anonymous arrays with the follwing elements:

  [$tag, $attr => $url1, $attr2 => $url2,...]

The $p->links method will also truncate the internal link list. This means that if the method is called twice without any parsing between them the second call will return an empty list.

Also note that $p->links will always be empty if a callback routine was provided when the HTML::LinkExtor was created.

EXAMPLE

This is an example showing how you can extract links from a document received using LWP:

  use LWP::UserAgent;
  use HTML::LinkExtor;
  use URI::URL;

  $url = "http://www.perl.org/";  # for instance
  $ua = LWP::UserAgent->new;

  # Set up a callback that collect image links
  my @imgs = ();
  sub callback {
     my($tag, %attr) = @_;
     return if $tag ne 'img';  # we only look closer at <img ...>
     push(@imgs, values %attr);
  }

  # Make the parser.  Unfortunately, we don't know the base yet
  # (it might be diffent from $url)
  $p = HTML::LinkExtor->new(\&callback);

  # Request document and parse it as it arrives
  $res = $ua->request(HTTP::Request->new(GET => $url),
                      sub {$p->parse($_[0])});

  # Expand all image URLs to absolute ones
  my $base = $res->base;
  @imgs = map { $_ = url($_, $base)->abs; } @imgs;

  # Print them out
  print join("\n", @imgs), "\n";

SEE ALSO

the HTML::Parser manpage, the HTML::Tagset manpage, the LWP manpage, the URI::URL manpage

COPYRIGHT

Copyright 1996-2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Mason - High-performance, dynamic web site authoring system

  • INSTALLATION
  • CONFIGURING MASON
  • DOCUMENTATION ROADMAP
  • AUTHORS
  • SEE ALSO

NAME

Mason - High-performance, dynamic web site authoring system

SYNOPSIS

    PerlModule HTML::Mason::ApacheHandler
    <Location />
        SetHandler perl-script
        PerlHandler HTML::Mason::ApacheHandler
    </Location>

DESCRIPTION

Mason is a tool for building, serving and managing large web sites. Its features make it an ideal backend for high load sites serving dynamic content, such as online newspapers or database driven e-commerce sites.

Actually, Mason can be used to generate any sort of text, whether for a web site or not. But it was originally built for web sites and since that's why most people are interested in it, that is the focus of this documentation.

Mason's various pieces revolve around the notion of "components''. A component is a mix of HTML, Perl, and special Mason commands, one component per file. So-called "top-level" components represent entire web-pages, while smaller components typically return HTML snippets for embedding in top-level components. This object-like architecture greatly simplifies site maintenance: change a shared component, and you instantly changed all dependant pages that refer to it across a site (or across many virtual sites).

Mason's component syntax lets designers separate a web page into programmatic and design elements. This means the esoteric Perl bits can be hidden near the bottom of a component, preloading simple variables for use above in the HTML. In our own experience, this frees content managers (i.e., non-programmers) to work on the layout without getting mired in programming details. Techies, however, still enjoy the full power of Perl.

Mason works by intercepting innocent-looking requests (say, http://www.yoursite.com/index.html) and mapping them to requests for Mason components. Mason then compiles the component, runs it, and feeds the output back to the client.

Consider this simple Mason component:

    % my $noun = 'World';
    Hello <% $noun %>!
    How are ya?

The output of this component is:

    Hello World!
    How are ya?

In this component you see a mix of standard HTML and Mason elements. The bare '%' prefixing the first line tells Mason that this is a line of Perl code. One line below, the embedded <% ... %> tag gets replaced with the return value of its contents, evaluated as a Perl expression.

Beyond this trivial example, components can also embed serious chunks of Perl code (say, to pull records from a database). They can also call other components, cache results for later reuse, and perform all the tricks you expect from a regular Perl program.

INSTALLATION

Mason has been tested under Linux, FreeBSD, Solaris, HPUX, and Win32. As an all-Perl solution, it should work on any machine that has working versions of Perl 5.00503+, mod_perl, and the required CPAN modules.

Mason has a standard MakeMaker-driven installation. See the README file for details.

CONFIGURING MASON

This section assumes that you are able to install and configure a mod_perl server. Relevant documentation is available at http://www.apache.org (Apache) and http://perl.apache.org (mod_perl). The mod_perl mailing list, archive, and guide are also great resources.

The simplest configuration of Mason requires a few lines in your httpd.conf:

    PerlModule HTML::Mason::ApacheHandler
    <Location />
        SetHandler perl-script
        PerlHandler HTML::Mason::ApacheHandler
    </Location>

The PerlModule directive simply ensures that the Mason code is loaded in the parent process before forking, which can save some memory when running mod_perl.

The <Location> section routes all requests to the Mason handler, which is a simple way to try out Mason. A more refined setup is discussed in the Controlling Access via Filename Extension section of the administrator's manual.

Once you have added the configuration directives, restart the server. First, go to a standard URL on your site to make sure you haven't broken anything. If all goes well you should see the same page as before. If not, recheck your Apache config files and also tail your server's error log.

If you are getting "404 Not Found" errors even when the files clearly exist, Mason may be having trouble with your document root. One situation that will unfortunately confuse Mason is if your document root goes through a symbolic link. Try expressing your document root in terms of the true filesystem path.

Next, try adding the tag <% 2+2 %> at the top of some HTML file. If you reload this page and see a "4", Mason is working!

DOCUMENTATION ROADMAP

Once Mason is on its feet, the next step is to write a component or two. The Mason Developer's Manual is a complete tutorial for writing, using, and debugging components. A reference companion to the Developer's Manual is the Request API documentation, HTML::Mason::Request.

Whoever is responsible for setting up and tuning Mason should read the Administrator's Manual, though developers will also benefit from reading it as well. This document covers more advanced configuration scenarios and performance optimization. The reference companion to the Administrator's manual is the Parameters Reference, which describes all the parameters you can use to configure Mason.

Most of this documentation assumes that you're running Mason on top of mod_perl, since that is the most common configuration. If you would like to run Mason via a CGI script, refer to the HTML::Mason::CGIHandler documentation. If you are using Mason from a standalone program, refer to the Using Mason from a Standalone Script section of the administrator's manual.

There is also a book about Mason, Embedding Perl in HTML with Mason, by Dave Rolsky and Ken Williams, published by O'Reilly and Associates. The book's website is at http://www.masonbook.com/. This book goes into detail on a number of topics, and includes a chapter of recipes as well as a sample Mason-based website.

AUTHORS

Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken Williams <ken@mathforum.org>

SEE ALSO

HTML::Mason::Devel, HTML::Mason::Admin


HTML::Mason::Admin - Mason Administrator's Manual

  • SITE CONFIGURATION METHODS
  • BASIC CONFIGURATION VIA httpd.conf DIRECTIVES
    • Controlling Access via Filename Extension
    • Configuration Parameters
  • GENERAL SERVER CONFIGURATION
    • Component Root
    • Data Directory
    • External Modules
    • Allowing Directory Requests
    • Configuring Virtual Sites
      • Multiple sites, one component root
      • Multiple sites, multiple component roots
  • ADVANCED CONFIGURATION
    • Writing a Wrapper
    • Wrapping with a <Perl> block
    • Wrapping with a Module
    • The Wrapper Code
    • External Modules Revisited
      • Example: Controlling access with component attributes
    • Wrappers with Virtual Hosts
      • Creating apachehandler objects on the fly
      • Other uses for a wrapper
    • Mixing httpd.conf Configuration with a Wrapper
  • DEVELOPMENT
    • Global Variables
    • Sessions
    • Data Caching
  • PERFORMANCE
    • Code Cache
    • Object Files
    • Write a handler subroutine
    • Static Source Mode
    • Preloading Components
  • ERROR REPORTING AND EXCEPTIONS
    • Exceptions Under the Hood
      • Calling a Component to Handle Errors
  • RUNNING OUTSIDE OF MOD_PERL
    • Using Mason from a CGI Script
    • Using Mason from a Standalone Script
  • AUTHORS
  • SEE ALSO

NAME

HTML::Mason::Admin - Mason Administrator's Manual

DESCRIPTION

This manual is written for the sysadmin/webmaster in charge of installing, configuring, or tuning a Mason system. The bulk of the documentation assumes that you are using mod_perl. See RUNNING OUTSIDE OF MOD_PERL for more details. For more details on mod_perl, visit the mod_perl website at http://perl.apache.org/.

SITE CONFIGURATION METHODS

Mason includes module specifically designed to integrate Mason and mod_perl, HTML::Mason::ApacheHandler. By telling mod_perl to hand content requests to this module, you can use Mason to generate web pages. There are two ways to configure Mason under mod_perl.

  • Basic

    Mason provides reasonable default behavior under mod_perl, so using Mason can be as simple as adding two directives to your Apache configuration file. Throughout this document, we will assume that your Apache configuration file is called httpd.conf. By adding more configuration parameters to this file you can implement more complex behaviors.

  • Advanced

    If the basic method does not provide enough flexibility for you, you can wrap Mason in a custom mod_perl handler. The wrapper code you write can create its own Mason objects, or it can take advantage of httpd.conf configuration parameters and let Mason create the objects it needs by itself.

We recommend that you start with the basic method and work your way forward as the need for flexibility arises.

Mason is very flexible, and you can replace parts of it by creating your own classes. This documentation assumes that you are simply using the classes provided in the Mason distribution. Subclassing is covered in the Subclassing document. The two topics are orthogonal, as you can mix the configuration techniques discussed here with your own custom subclasses.

BASIC CONFIGURATION VIA httpd.conf DIRECTIVES

The absolutely most minimal configuration looks like this:

    PerlModule HTML::Mason::ApacheHandler
    <Location />
      SetHandler   perl-script
      PerlHandler  HTML::Mason::ApacheHandler
    </Location>

This configuration tells Apache to serve all URLs through Mason (see the next section for a more realistic strategy). We use the PerlModule line to tell mod_perl to load Mason once at startup time, saving time and memory. This example does not set any Mason configuration parameters, so Mason uses its default values.

If this is your first time installing and using Mason, we recommend that you use the above configuration in a test webserver to start with. This will let you play with Mason under mod_perl with a minimum of fuss. Once you've gotten this working, then come back and read the rest of the document for further possibilities.

Controlling Access via Filename Extension

As it turns out, serving every URL through Mason is a bad idea for two reasons:

  1. Mason should be prevented from handling images, tarballs, and other binary files. Not only will performance suffer, but binary files may inadvertently contain a Mason character sequence such as "<%". These files should be instead served by Apache's default content handler.

  2. Mason should be prevented from serving private (non-top-level) Mason components to users. For example, if you used a utility component for performing arbitrary sql queries, you wouldn't want external users to be able to access it via a URL. Requests for private components should simply result in a 404 NOT_FOUND.

The easiest way to distinguish between different types of files is with filename extensions. While many naming schemes are possible, we suggest using "normal" extensions for top-level components and adding an "m" prefix for private components. For example,

                             Top-level       Private
   Component outputs HTML    .html           .mhtml
   Component outputs text    .txt            .mtxt
   Component executes Perl   .pl             .mpl

This scheme minimizes the chance of confusing browsers about content type, scales well for new classes of content (e.g. .js/.mjs for javascript), and makes transparent the fact that you are using Mason versus some other package.

Here is a configuration that enforces this naming scheme:

    PerlModule HTML::Mason::ApacheHandler
    <LocationMatch "(\.html|\.txt|\.pl)$">
      SetHandler perl-script
      PerlHandler HTML::Mason::ApacheHandler
    </LocationMatch>
    <LocationMatch "(\.m(html|txt|pl)|dhandler|autohandler)$">
      SetHandler perl-script
      PerlInitHandler Apache::Constants::NOT_FOUND
    </LocationMatch>

The first block causes URLs ending in .html, .txt, or .pl to be served through Mason. The second block causes requests to private components to return 404 NOT_FOUND, preventing unscrupulous users from even knowing which private components exist. Any other file extensions (e.g. .gif, .tgz) will be served by Apache's default content handler.

You might prefer FilesMatch to LocationMatch. However, be aware that LocationMatch will work best in conjunction with Mason's dhandlers.

Configuration Parameters

Mason allows you to flexibly configure its behavior via httpd.conf configuration parameters.

These configuration parameters are set via mod_perl's PerlSetVar and PerlAddVar directives (the latter is only available in mod_perl version 1.24 and greater). Though these parameters are all strings in your httpd.conf file, Mason treats different directives as containing different types of values:

  • string

    The variable's value is simply taken literally and used. The string should be surrounded by quotes if the it contains whitespace. The quotes will be automatically removed by Apache before Mason sees the variable.

  • boolean

    The variable's value is used as a boolean, and is subject to Perl's rules on truth/falseness. It is recommended that you use 0 (false) or 1 (true) for these arguments.

  • code

    The string is treated as a piece of code and eval'ed. This is used for parameters that expect subroutine references. For example, an anonymous subroutine might look like:

     PerlSetVar  MasonOutMode  "sub { ... }"

    A named subroutine reference would look like this:

     PerlSetVar  MasonOutMode  "\&Some::Module::handle_output"
  • list

    To set a list parameter, use PerlAddVar for the values, like this:

     PerlAddVar  MasonPreloads  /foo/bar/baz.comp
 PerlAddVar  MasonPreloads  /foo/bar/quux.comp

    As noted above, PerlAddVar is only available in mod_perl 1.24 and up. This means that it is only possible to assign a single value (using PerlSetVar) to list parameters if you are using a mod_perl older than 1.24.

  • hash_list

    Just like a list parameter, use PerlAddVar for the values. However, in the case of a hash_list, each element should be a key/value pair separated by "=>":

     PerlAddVar  MasonDataCacheDefaults  "cache_class => MemoryCache"
 PerlAddVar  MasonDataCacheDefaults  "namespace => foo"

    Take note that the right hand side of the each pair should not be quoted.

See HTML::Mason::Params for a full list of parameters, and their associated types.

GENERAL SERVER CONFIGURATION

Component Root

The component root (comp_root) marks the top of your component hierarchy. When running Mason with the ApacheHandler or CGIHandler modules, this defaults to your document root.

The component root defines how component paths are translated into real file paths. If your component root is /usr/local/httpd/docs, a component path of /products/index.html translates to the file /usr/local/httpd/docs/products/index.html.

One cannot call a component outside the component root. If Apache passes a file through Mason that is outside the component root (say, as the result of an Alias) you will get a 404 and a warning in the logs.

You may also specify multiple component roots in the spirit of Perl's @INC. Each root is assigned a key that identifies the root mnemonically. For example, in httpd.conf:

    PerlAddVar  MasonCompRoot  "private => /usr/home/joe/comps"
    PerlAddVar  MasonCompRoot  "main => /usr/local/www/htdocs"

This specifies two component roots, a main component tree and a private tree which overrides certain components. The order is respected ala @INC, so private is searched first and main second.

The component root keys must be unique in a case-insensitive comparison.

Data Directory

The data directory (data_dir) is a writable directory that Mason uses for various features and optimizations. By default, it is a directory called "mason" under your Apache server root. Because Mason will not use a default data directory under a top-level directory, you will need to change this on certain systems that assign a high-level server root such as /usr or /etc.

Mason will create the directory on startup, if necessary, and set its permissions according to the web server User/Group.

External Modules

Components will often need access to external Perl modules. There are several ways to load them.

  • The httpd PerlModule directive:

        PerlModule CGI
    PerlModule LWP

  • In the <%once> section of the component(s) that use the module.

        <%once>
    use CGI ':standard';
    use LWP;
    </%once>

Each method has its own trade-offs:

The first method ensures that the module will be loaded by the Apache parent process at startup time, saving time and memory. The second method, in contrast, will cause the modules to be loaded by each server child. On the other hand this could save memory if the component and module are rarely used. See the mod_perl guide's tuning section and Vivek Khera's mod_perl tuning guide for more details on this issue.

The second method uses the modules from inside the package used by components (HTML::Mason::Commands), meaning that exported method names and other symbols will be usable from components. The first method, in contrast, will import symbols into the main package. The significance of this depends on whether the modules export symbols and whether you want to use them from components.

If you want to preload the modules in your httpd.conf file, and still have them export symbols into the HTML::Mason::Commands namespace, you can do this:

  <Perl>
  { package HTML::Mason::Commands;
    use CGI;
    use LWP;
  }
  </Perl>

A Perl section will also work for including local library paths:

  <Perl>
  use lib '/path/to/local/lib';
  </Perl>

Allowing Directory Requests

By default Mason will decline requests for directories, leaving Apache to serve up a directory index or a FORBIDDEN as appropriate. Unfortunately this rule applies even if there is a dhandler in the directory: /foo/bar/dhandler does not get a chance to handle a request for /foo/bar/.

If you would like Mason to handle directory requests, set decline_dirs to 0. The dhandler that catches a directory request is responsible for setting a reasonable content type via $r->content_type()

Configuring Virtual Sites

These examples extend the single site configurations given so far.

Multiple sites, one component root

If you want to share some components between your sites, arrange your httpd.conf so that all DocumentRoots live under a single component space:

    # Web site #1
    <VirtualHost www.site1.com>
      DocumentRoot  /usr/local/www/htdocs/site1
      <LocationMatch ...>
        SetHandler   perl-script
        PerlHandler  HTML::Mason::ApacheHandler
      </LocationMatch>
    </VirtualHost>
    # Web site #2
    <VirtualHost www.site2.com>
      DocumentRoot  /usr/local/www/htdocs/site2
      <LocationMatch ...>
        SetHandler   perl-script
        PerlHandler  HTML::Mason::ApacheHandler
      </LocationMatch>
    </VirtualHost>
    # Mason configuration
    PerlSetVar  MasonCompRoot  /usr/local/www/htdocs
    PerlSetVar  MasonDataDir   /usr/local/mason
    PerlModule  HTML::Mason::ApacheHandler

The directory structure for this scenario might look like:

    /usr/local/www/htdocs/  # component root
        +- shared/          # shared components
        +- site1/           # DocumentRoot for first site
        +- site2/           # DocumentRoot for second site

Incoming URLs for each site can only request components in their respective DocumentRoots, while components internally can call other components anywhere in the component space. The shared/ directory is a private directory for use by components, inaccessible from the Web.

Multiple sites, multiple component roots

If your sites need to have completely distinct component hierarchies, e.g. if you are providing Mason ISP services for multiple users, then the component root must change depending on the site requested.

    <VirtualHost www.site1.com>
      DocumentRoot  /usr/local/www/htdocs/site1
      # Mason configuration
      PerlSetVar  MasonCompRoot    /usr/local/www/htdocs/site1
      PerlSetVar  MasonDataDir     /usr/local/mason/site1
      <LocationMatch ...>
        SetHandler   perl-script
        PerlHandler  HTML::Mason::ApacheHandler
      </LocationMatch>
    </VirtualHost>
    # Web site #2
    <VirtualHost www.site2.com>
      DocumentRoot  /usr/local/www/htdocs/site2
      # Mason configuration
      PerlSetVar  MasonCompRoot    /usr/local/www/htdocs/site2
      PerlSetVar  MasonDataDir     /usr/local/mason/site2
      <LocationMatch ...>
        SetHandler   perl-script
        PerlHandler  HTML::Mason::ApacheHandler
      </LocationMatch>
    </VirtualHost>

ADVANCED CONFIGURATION

As mentioned previously, it is possible to write a custom mod_perl content handler that wraps around Mason and provides basically unlimited flexibility when handling requests. In this section, we show some basic wrappers and re-implement some of the functionality previously discussed, such as declining image requests and protecting private components.

In addition, we discuss some of the possibilities that become available when you create a custom wrapper around Mason's request handling mechanism. This wrapper generally consists of two parts. The initialization portion, run at server startup, will load any needed modules and create objects. The other portion is the handler() subroutine, which handles web page requests.

Writing a Wrapper

To create a wrapper, you simply need to define a handler() subroutine in the package of your choice, and tell mod_perl to use it as a content handler. The file that defines the handler() subroutine can be a module, or you can simply load a simple file that contains this subroutine definition. The latter solution was, for a long time, the only way to configure Mason, and the file used was traditionally called handler.pl. This file was usually placed in the Apache configuration directory and was loaded like this:

  PerlRequire  handler.pl

The eg/ directory of the Mason distribution contains a couple sample handler.pl scripts. Let's assume that your script, like the example script, defines a handler in the package MyApp::Mason. In this case, your Apache configuration would look like this:

  PerlRequire  handler.pl
  <LocationMatch ...>
    SetHandler   perl-script
    PerlHandler  MyApp::Mason
  </LocationMatch>

You may still see references to a handler.pl file in the Mason users list archives, as well as the FAQ. These references will generally be applicable to any custom code wrapping Mason.

Wrapping with a <Perl> block

You can also put your wrapper code in a <Perl> block as part of your httpd.conf file. The result is no different than loading a file via the PerlRequire directive.

Wrapping with a Module

Remember, this wrapper code doesn't have to be in a file handler.pl. You could just as easily create an actual module called MyApp::Mason, install it just like any other module, and load it with:

  PerlModule  MyApp::Mason

The advantage to this approach is that it uses well-known techniques for creating and installing modules, but it does require a bit more work than simply dropping a handler.pl file into the Apache configuration directory. But because the process is better defined, it may "feel" more solid to some folks than the handler.pl approach.

The Wrapper Code

Regardless of how you load your wrapper code, it will always work the same way. The handler() subroutine should expect to receive the Apache request object representing the current request. This request object is used by the ApacheHandler module to determine what component is being called.

Let's look at the guts of some wrapper code. Here's a first version:

  package MyApp::Mason;

  use strict;
  use HTML::Mason::ApacheHandler;

  my $ah =
      HTML::Mason::ApacheHandler->new
          ( comp_root => '/path/to/comp/root',
            data_dir  => '/path/to/data/dir' );

  sub handler {
      my ($r) = @_;

      return $ah->handle_request($r);
        }

This wrapper is fully functional, but it doesn't actually do anything you couldn't do more easily by configuring Mason via the httpd.conf file. However, it does serve as a good skeleton to which additional functionality can easily be added.

External Modules Revisited

Since you are loading an arbitrary piece of code to define your wrapper, you can easily load other modules needed for your application at the same time. For example, you might simple add these lines to the wrapper code above:

  {
      package HTML::Mason::Commands;

      use MIME::Base64;
        }

Explicitly setting the package to HTML::Mason::Commands makes sure that any symbols that the loaded modules export (constants, subroutines, etc.) get exported into the namespace under which components run. Of course, if you've changed the component namespace, make sure to change the package name here as well.

Alternatively, you might consider creating a separate piece of code to load the modules you need. For example, you might create a module called MyApp::MasonInit:

  {
      package HTML::Mason::Commands;

      use Apache::Constants qw(:common);
      use Apache::URI;
      use File::Temp;
        }

  1;

This can be loaded via a PerlModule directive in the httpd.conf file, or in the wrapper code itself via use.

Example: Controlling access with component attributes

An example of something you can only do with wrapper code is deciding at run-time whether a component can be accessed at the top-level based on a complex property of the component. For example, here's a piece of code that uses the current user and a component's access_level attribute to control access:

  sub handler {
      my ($r) = @_;

      my $req = $ah->prepare_request($r);

      my $comp = $req->request_comp;

      # this is done via magic hand-waving ...
      my $user = get_user_from_cookie();

      # remember, attributes are inherited so this could come from a
      # component higher up the inheritance chain
      my $required_access = $comp->attr('access_level');

      return NOT_FOUND
          if $user->access_level < $required_access;

      return $req->exec;
        }

Wrappers with Virtual Hosts

If you had several virtual hosts, each of which had a separate component root, you'd need to create a separate ApacheHandler object for each host, one for each host. Here's some sample code for that:

    my %ah;
    foreach my $site ( qw( site1 site2 site3 ) ) {
        $ah{$site} =
            HTML::Mason::ApacheHandler->new
                ( comp_root => "/usr/local/www/$site",
                  data_dir => "/usr/local/mason/$site" );
    }

    sub handler {
        my ($r) = @_;

        my $site = $r->dir_config('SiteName');

        return DECLINED unless exists $ah{$site};

        return $ah{$site}->handle_request($r);
            }

This code assumes that you set the SiteName variable via a PerlSetVar directive in each VirtualHost block, like this:

  <VirtualHost site1.example.com>
    PerlSetVar  SiteName  site1
    <LocationMatch ...>
      SetHandler   perl-script
      PerlHandler  MyApp::Mason
    </LocationMatch>
  </VirtualHost>

Creating apachehandler objects on the fly

You might also consider creating ApacheHandler objects on the fly, like this:

    my %ah;
    sub handler {
        my ($r) = @_;
        my $site = $r->dir_config('SiteName');

        return DECLINED unless $site;

        unless exists($ah{$site}) {
            $ah{$site} = HTML::Mason::ApacheHandler->new( ... );
        }

        $ah{$site}->handle_request($r);
            }

This is more flexible but you lose the memory savings of creating all your objects during server startup.

Other uses for a wrapper

If you have some code which must always run after a request, then the only way to guarantee that this happens is to wrap the $ah->handle_request() call in an eval {} block, and then run the needed code after the request returns. You can then handle errors however you like.

Mixing httpd.conf Configuration with a Wrapper

You can take advantage of Mason's httpd.conf configuration system while at the same time providing your own wrapper code. The key to doing this is not creating your own ApacheHandler object. Instead, you call the HTML::Mason::ApacheHandler->handler() class method from your handler() subroutine. Here's a complete wrapper that does this:

  package MyApp::Mason;

  use strict;
  use HTML::Mason::ApacheHandler;

  sub handler {
      my ($r) = @_;

      return HTML::Mason::ApacheHandler->handler($r);
        }

The HTML::Mason::ApacheHandler->handler method will create an ApacheHandler object based on the configuration directives it finds in your httpd.conf file. Obviously, this wrapper is again a skeleton, but you could mix and match this wrapper code with any of the code shown above.

Alternately you could subclass the HTML::Mason::ApacheHandler class, and override the handler() method it provides. See the Subclassing documentation for more details. Of course, you could even create a subclass and write a wrapper that called it.

DEVELOPMENT

This section describes how to set up common developer features.

Global Variables

Global variables can make programs harder to read, maintain, and debug, and this is no less true for Mason components. Due to the persistent mod_perl environment, globals require extra initialization and cleanup care.

That said, there are times when it is very useful to make a value available to all Mason components: a DBI database handle, a hash of user session information, the server root for forming absolute URLs.

Because Mason by default parses components in strict mode, you'll need to declare a global if you don't want to access it with an explicit package name. The easiest way to declare a global is with the allow_globals parameter.

Since all components run in the same package, you'll be able to set the global in one component and access it in all the others.

Autohandlers are common places to assign values to globals. Use the <%once> section if the global only needs to be initialized at load time, or the <%init> section if it needs to be initialized every request.

Sessions

Mason does not have a built-in session mechanism, but you can use the MasonX::Request::WithApacheSession module, available from CPAN, to add a session to every request. It can also automatically set and read cookies containing the session id.

Data Caching

Data caching is implemented with DeWitt Clinton's Cache::Cache module. For full understanding of this section you should read the documentation for Cache::Cache as well as for relevant subclasses (e.g. Cache::FileCache).

Cache files

By default, Cache::FileCache is the subclass used for data caching, although this may be overriden by the developer. Cache::FileCache creates a separate subdirectory for every component that uses caching, and one file some number of levels underneath that subdirectory for each cached item. The root of the cache tree is data_dir/cache. The name of the cache subdirectory for a component is determined by the function HTML::Mason::Utils::data_cache_namespace.

Default constructor options

Ordinarily, when $m->cache is called, Mason passes to the cache constructor the namespace, and cache_root options, along with any other options given in the $m->cache method.

You may specify other default constructor options with the data_cache_defaults parameter. For example,

    PerlSetVar  MasonDataCacheDefaults  "cache_class => SizeAwareFileCache"
    PerlAddVar  MasonDataCacheDefaults  "cache_depth => 2"
    PerlAddVar  MasonDataCacheDefaults  "default_expires_in => 1 hour"

Any options passed to individual $m->cache calls override these defaults.

Disabling data caching

If for some reason you want to disable data caching entirely, set the default cache_class to "NullCache". This subclass faithfully implements the cache API but never stores data.

PERFORMANCE

This section explains Mason's various performance enhancements and how to administer them.

Code Cache

When Mason loads a component, it places it in a memory cache.

The maximum size of the cache is specified with the code_cache_max_size parameter. When the cache fills up, Mason frees up space by discarding a number of components. The discard algorithm is least frequently used (LFU), with a periodic decay to gradually eliminate old frequency information. In a nutshell, the components called most often in recent history should remain in the cache. Very large components (over 20% of the maximum cache size) never get cached, on the theory that they would force out too many other components.

Note that the "size" of a component in memory cannot literally be measured. It is estimated by the length of the source text plus some overhead. Your process growth will not match the code cache size exactly.

You can prepopulate the cache with components that you know will be accessed often; see Preloading Components. Note that preloaded components possess no special status in the cache and can be discarded like any others.

Naturally, a cache entry is invalidated if the corresponding component source file changes.

To turn off code caching completely, set code_cache_max_size to 0.

Object Files

The in-memory code cache is only useful on a per-process basis. Each process must build and maintain its own cache. Shared memory caches are conceivable in the future, but even those will not survive between web server restarts.

As a secondary, longer-term cache mechanism, Mason stores a compiled form of each component in an object file under data_dir/obj. Any server process can eval the object file and save time on parsing the component source file. The object file is recreated whenever the source file changes.

Besides improving performance, object files can be useful for debugging. If you feel the need to see what your source has been translated into, you can peek inside an object file to see exactly how Mason converted a given component to a Perl object. This was crucial for pre-1.10 Mason, in which error line numbers were based on the object file rather than the source file.

If for some reason you don't want Mason to create object files, set use_object_files to 0.

Write a handler subroutine

Writing your own handler() subroutine which uses an ApacheHandler object (or objects) created during server startup is slightly faster (around 5% or so) than configuring mason via your httpd.conf file and letting Mason create its own ApacheHandler objects internally.

Static Source Mode

As described above, Mason checks the timestamp of a component source file every time that component is called. This can add up to a lot of file stats.

If you have a live site with infrequent and well-controlled updates, you may choose to use static_source mode. In this mode Mason will not check source timestamps when it uses an in-memory cache or object file. The disadvantage is that you must remove object files and restart the server whenever you change component source; however this process can be easily automated.

Preloading Components

You can tell Mason to preload a set of components in the parent process, rather than loading them on demand, using the preloads parameter. Each child server will start with those components loaded in the memory cache. The trade-offs are:

time

a small one-time startup cost, but children save time by not having to load the components

memory

a fatter initial server, but the memory for preloaded components are shared by all children. This is similar to the advantage of using modules only in the parent process.

Try to preload components that are used frequently and do not change often. (If a preloaded component changes, all the children will have to reload it from scratch.)

ERROR REPORTING AND EXCEPTIONS

When an error occurs, Mason can respond by:

  • showing a detailed error message in the browser in HTML.

  • die'ing, which sends a 500 status to the browser and lets the error message go to the error logs.

The first behavior is ideal for development, where you want immediate feedback on the error. The second behavior is usually desired for production so that users are not exposed to messy error messages. You choose the behavior by setting error_mode to "output" or "fatal" respectively.

Error formatting is controlled by the error_format parameter. When showing errors in the browser, Mason defaults to the "html" format. When the error_mode is set to "fatal", the default format is "line", which puts the entire error message on one line in a format suitable for web server error logs. Mason also offers other formats, which are covered in the Request class documentation.

Finally, you can use Apache's ErrorDocument directive to specify a custom error handler for 500 errors. In this case, you'd set the error_mode to "fatal". The URL specified by the ErrorDocument directive could point to a Mason component.

Exceptions Under the Hood

The way that Mason really reports errors is through the use of exception objects, which are implemented with the Exception::Class module from CPAN, and some custom code in the HTML::Mason::Exceptions module.

If, during the execution of a component, execution stops because some code calls die(), then Mason will catch this exception. If the exception being thrown is just a string, then it will be converted to an HTML::Mason::Exception object. If the exception being thrown is an object with a rethrow() method, then this method will be called. Otherwise, Mason simply leaves the exception untouched and calls die() again.

Calling a Component to Handle Errors

Returning to the topic of wrapper code that we covered earlier, what if you wanted to handle all request errors by calling an error handling component? There is no way to do this without wrapper code. Here's an example handler() subroutine that does this:

    sub handler {
        my ($r) = @_;

        my $return = eval { $ah->handle_request($r) };

        if ( my $err = $@ )
        {
            $r->pnotes( error => $err );
            $r->filename( $r->document_root . '/error/500.html' );

            return $ah->handle_request($r);
                    }

        return $return;
            }

First, we wrap our call to $ah->handle_request() in an eval{} block. If an error occurs, we store it in the request object using the $r->pnotes() method. Then we change the filename property of the Apache request object to point to our error-handling component and call the $ah->handle_request() method again, passing it the altered request object. We could have put the exception in $r->args, but we want to leave this untouched so that the error-handling component can see the original arguments.

Here's what that component error-handling component might look like:

 <html>
 <head>
 <title>Error</title>
 </head>
 <body>
 <p>
 Looks like our application broke.  Whatever you did, don't do it again!
 </p>
 <p>
 If you have further questions, please feel free to contact us at <a
 href="mailto:support@example.com">support@example.com</a>.
 </p>
 <p><a href="/">Click here</a> to continue.</p>
 </body>
 </html>
 <%init>
  my $error = $r->pnotes('error');

  my $error_text = "Page is " . $r->parsed_uri->unparse . "\n\n";

  $error_text .= UNIVERSAL::can( $error, 'as_text' ) ? $error->as_text : $error;

  $r->log_error($error_text);

  my $mail =
      MIME::Lite->new
          ( From => 'error-handler@example.com',
            To   => 'rt@example.com',
            Subject => 'Application error',
            Data => $error_text,
          );

  $r->register_cleanup( sub { $mail->send } );
   </%init>

 <%flags>
  inherit => undef
 </%flags>

This component does several things. First of all, it logs the complete error to the Apache error logs, along with the complete URL, including query string, that was requested. The $r->parsed_uri() method that we use above is only available if the Apache::URI module has been loaded.

The component also sends an email containing the error, in this case to an RT installation, so that the error is logged in a bug tracking system. Finally, it displays a less technical error message to the user.

For this to work properly, you must set error_mode to "fatal", so that Mason doesn't just display its own HTML error page.

RUNNING OUTSIDE OF MOD_PERL

Although Mason is most commonly used in conjunction with mod_perl, the APIs are flexible enough to use in any environment. Below we describe the two most common alternative environments, CGI and standalone scripts.

Using Mason from a CGI Script

The easiest way to use Mason via a CGI script is with the CGIHandler module module.

Here is a skeleton CGI script that calls a component and sends the output to the browser.

    #!/usr/bin/perl
    use HTML::Mason::CGIHandler;

    my $h = HTML::Mason::CGIHandler->new
     (
      data_dir  => '/home/jethro/code/mason_data',
     );

    $h->handle_request;

The relevant portions of the httpd.conf file look like:

    DocumentRoot /path/to/comp/root
    ScriptAlias /cgi-bin/ /path/to/cgi-bin/
    Action html-mason /cgi-bin/mason_handler.cgi
    <LocationMatch "\.html$">
      SetHandler html-mason
    </LocationMatch>

This simply causes Apache to call the mason_handler.cgi script every time a URL ending in ".html" under the component root is requested. This script uses the CGIHandler class to do most of the heavy lifting. See that class's documentation for more details.

Using Mason from a Standalone Script

Mason can be used as a pure text templating solution -- like Text::Template and its brethren, but with more power (and of course more complexity).

Here is a bare-bones script that calls a component file and sends the result to standard output:

    #!/usr/bin/perl
    use HTML::Mason;
    use strict;

    my $interp = HTML::Mason::Interp->new ();
    $interp->exec(<path-to-file-from-cwd>, <args>...);

Because no component root was specified, the root is set to your current working directory. (The path supplied to exec still needs to start with a slash, even though it is effectively a relative path from the current directory.) If you have a well defined and contained component tree, you'll probably want to specify a component root.

Because no data directory was specified, object files will not be created and data caching will not work in the default manner. If performance is an issue, you will want to specify a data directory.

Here's a slightly fuller script that specifies a component root and data directory, and captures the result in a variable rather than sending to standard output:

    #!/usr/bin/perl
    use HTML::Mason;
    use strict;

    my $outbuf;
    my $interp = HTML::Mason::Interp->new
        (comp_root  => '/path/to/comp_root',
         data_dir   => '/path/to/data_dir',
         out_method => \$outbuf
        );
    $interp->exec(<component-path>, <args>...);

    # Do something with $outbuf

AUTHORS

Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken Williams <ken@mathforum.org>

SEE ALSO

HTML::Mason,
HTML::Mason::Interp,
HTML::Mason::ApacheHandler,
HTML::Mason::Lexer,
HTML::Mason::Compiler


HTML::Mason::ApacheHandler - Mason/mod_perl interface

  • PARAMETERS TO THE new() CONSTRUCTOR
  • ACCESSOR METHODS
  • OTHER METHODS
  • SEE ALSO

NAME

HTML::Mason::ApacheHandler - Mason/mod_perl interface

SYNOPSIS

    use HTML::Mason::ApacheHandler;

    my $ah = HTML::Mason::ApacheHandler->new (..name/value params..);
    ...
    sub handler {
        my $r = shift;
        $ah->handle_request($r);
    }

DESCRIPTION

The ApacheHandler object links Mason to mod_perl, running components in response to HTTP requests. It is controlled primarily through parameters to the new() constructor.

handle_request() is not a user method, but rather is called from the HTML::Mason::handler() routine in handler.pl.

PARAMETERS TO THE new() CONSTRUCTOR

apache_status_title

Title that you want this ApacheHandler to appear as under Apache::Status. Default is "HTML::Mason status". This is useful if you create more than one ApacheHandler object and want them all visible via Apache::Status.

args_method

Method to use for unpacking GET and POST arguments. The valid options are 'CGI' and 'mod_perl'; these indicate that a CGI.pm or Apache::Request object (respectively) will be created for the purposes of argument handling.

'mod_perl' is the default and requires that you have installed the Apache::Request package.

If args_method is 'mod_perl', the $r global is upgraded to an Apache::Request object. This object inherits all Apache methods and adds a few of its own, dealing with parameters and file uploads. See Apache::Request for more information.

If the args_method is 'CGI', the Mason request object ($m) will have a method called cgi_object available. This method returns the CGI object used for argument processing.

While Mason will load Apache::Request or CGI as needed at runtime, it is recommended that you preload the relevant module either in your httpd.conf or handler.pl file, as this will save some memory.

decline_dirs

True or false, default is true. Indicates whether Mason should decline directory requests, leaving Apache to serve up a directory index or a FORBIDDEN error as appropriate. See the allowing directory requests section of the administrator's manual for more information about handling directories with Mason.

interp

The interpreter object to associate with this compiler. By default a new object of the specified interp_class will be created.

interp_class

The class to use when creating a interpreter. Defaults to HTML::Mason::Interp.

ACCESSOR METHODS

All of the above properties, except interp_class, have standard accessor methods of the same name: no arguments retrieves the value, and one argument sets it, except for args_method, which is not settable. For example:

    my $ah = HTML::Mason::ApacheHandler->new;
    my $decline_dirs = $ah->decline_dirs;
    $ah->decline_dirs(1);

OTHER METHODS

The ApacheHandler object has a few other publically accessible methods that may be of interest to end users.

handle_request ($r)

This method takes an Apache object representing a request and translates that request into a form Mason can understand. It's return value is an Apache status code.

prepare_request ($r)

This method takes an Apache object representing a request and returns a new Mason request object or an Apache status code. If it is a request object you can manipulate that object as you like, and then call the request object's exec method to have it generate output.

If this method returns an Apache status code, that means that it could not create a Mason request object.

This method is useful if you would like to have a chance to decline a request based on properties of the Mason request object or a component object. For example:

    my $req = $ah->prepare_request($r);
    # $req must be an Apache status code if it's not an object
    return $req unless ref($req);

    return DECLINED
        unless $req->request_comp->source_file =~ /\.html$/;

    $req->exec;
request_args ($r)

Given an Apache request object, this method returns a three item list. The first item is a hash reference containing the arguments passed by the client's request.

The second is an Apache request object. This is returned for backwards compatibility from when this method was responsible for turning a plain Apache object into an Apache::Request object.

The third item may be a CGI.pm object or undef, depending on the value of the args_method parameter.

SEE ALSO

HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::Interp


HTML::Mason::Buffer - Objects for Handling Component Output

  • CONSTRUCTOR
  • METHODS

NAME

HTML::Mason::Buffer - Objects for Handling Component Output

SYNOPSIS

  my $buffer = HTML::Mason::Buffer->new( sink => sub { print @_ } );

  my $child = $buffer->new_child;

  $child->receive( 'foo', 'bar' );

DESCRIPTION

Mason's buffer objects handle all output generated by components. They are used to implement <%filter> blocks, the $m->scomp method, the store component call modifier, and content-filtering component feature.

Buffers can either store output in a scalar, internally, or they can be given a callback to call immediately when output is generated.

Most users will never have to deal with buffer objects directly, but will instead use Request object methods such as print or clear_buffer.

CONSTRUCTOR

Buffer objects can be constructed in two different ways. Like any other Mason object, they can be created via their new method.

This method takes several parameters, all of them optional.

sink

This should be either a subroutine reference or a scalar reference.

If this is a subroutine reference, then any output received by the buffer will be passed to this subroutine reference as a list of one or more items.

If this is a scalar reference, then data will be concatenated onto this scalar as it is received.

If no parameter is given, then output will be buffered internally, to be retrieved by the output method.

ignore_flush

If this parameter is true, then the created buffer will ignore calls to its flush method. This parameter defaults to true for buffers created via the new method, and false for those created via the new_child method.

filter

This parameter should be a subroutine reference which should expect to receive a single argument, the output to be filtered. It should return the output after transforming it in any way it desires.

New buffers can also be created via the new_child method, which takes the same parameters as the new method. The new_child method is an object method, not a class method.

It creates a new buffer object which will eventually pass its output to the buffer object that created it.

This allows you to create a stack of buffers.

METHODS

receive

This method takes a list of items to be sent to the buffer's sink.

flush

This method tells the buffer to pass any output it may currently have stored internally to its parent, if it has one. It then clears the buffer.

This method does nothing if the buffer does not have any stored output, which is the case for buffers that were given a subroutine reference as their sink argument.

clear

For buffers which store output internally, this clears any pending output.

output

For buffers which store output internally, this returns any pending output, possibly passing it through a buffer's filter, if it has one. This does not clear the buffer.


HTML::Mason::CGIHandler - Use Mason in a CGI environment

    • HTML::Mason::CGIHandler Methods
    • $r Methods
    • Added $m methods
    • HTML::Mason::FakeTable Methods
  • SEE ALSO

NAME

HTML::Mason::CGIHandler - Use Mason in a CGI environment

SYNOPSIS

In httpd.conf or .htaccess:

   Action html-mason /cgi-bin/mason_handler.cgi
   <LocationMatch "\.html$">
    SetHandler html-mason
   </LocationMatch>

A script at /cgi-bin/mason_handler.pl :

   #!/usr/bin/perl
   use HTML::Mason::CGIHandler;

   my $h = HTML::Mason::CGIHandler->new
    (
     data_dir  => '/home/jethro/code/mason_data',
     allow_globals => [qw(%session $u)],
    );

   $h->handle_request;

A .html component somewhere in the web server's document root:

   <%args>
    $mood => 'satisfied'
   </%args>
   % $r->err_header_out(Location => "http://blahblahblah.com/moodring/$mood.html");
   ...

DESCRIPTION

This module lets you execute Mason components in a CGI environment. It lets you keep your top-level components in the web server's document root, using regular component syntax and without worrying about the particular details of invoking Mason on each request.

If you want to use Mason components from within a regular CGI script (or any other Perl program, for that matter), then you don't need this module. You can simply follow the directions in the Using Mason from a standalone script section of the administrator's manual.

This module also provides an $r request object for use inside components, similar to the Apache request object under HTML::Mason::ApacheHandler, but limited in functionality. Please note that we aim to replicate the mod_perl functionality as closely as possible - if you find differences, do not depend on them to stay different. We may fix them in a future release. Also, if you need some missing functionality in $r, let us know, we might be able to provide it.

Finally, this module alters the HTML::Mason::Request object $m to provide direct access to the CGI query, should such access be necessary.

HTML::Mason::CGIHandler Methods

  • new()

    Creates a new handler. Accepts any parameter that the Interpreter accepts.

    If no comp_root parameter is passed to new(), the component root will be $ENV{DOCUMENT_ROOT}.

  • handle_request()

    Handles the current request, reading input from $ENV{QUERY_STRING} or STDIN and sending headers and component output to STDOUT. This method doesn't accept any parameters. The initial component will be the one specified in $ENV{PATH_INFO}.

  • handle_comp()

    Like handle_request(), but the first (only) parameter is a component path or component object. This is useful within a traditional CGI environment, in which you're essentially using Mason as a templating language but not an application server.

    handle_component() will create a CGI query object, parse the query parameters, and send the HTTP header and component output to STDOUT. If you want to handle those parts yourself, see the Using Mason from a standalone script section of the administrator's manual.

  • handle_cgi_object()

    Also like handle_request(), but this method takes only a CGI object as its parameter. This can be quite useful if you want to use this module with CGI::Fast.

    The component path will be the value of the CGI object's path_info() method.

  • request_args()

    Given an HTML::Mason::FakeApache object, this method is expected to return a hash containing the arguments to be passed to the component. It is a separate method in order to make it easily overrideable in a subclass.

  • interp()

    Returns the Mason Interpreter associated with this handler. The Interpreter lasts for the entire lifetime of the handler.

$r Methods

  • headers_in()

    This works much like the Apache method of the same name. In an array context, it will return a %hash of response headers. In a scalar context, it will return a reference to the case-insensitive hash blessed into the HTML::Mason::FakeTable class. The values initially populated in this hash are extracted from the CGI environment variables as best as possible. The pattern is to merely reverse the conversion from HTTP headers to CGI variables as documented here: http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1.

  • header_in()

    This works much like the Apache method of the same name. When passed the name of a header, returns the value of the given incoming header. When passed a name and a value, sets the value of the header. Setting the header to undef will actually unset the header (instead of setting its value to undef), removing it from the table of headers returned from future calls to headers_in() or header_in().

  • headers_out()

    This works much like the Apache method of the same name. In an array context, it will return a %hash of response headers. In a scalar context, it will return a reference to the case-insensitive hash blessed into the HTML::Mason::FakeTable class. Changes made to this hash will be made to the headers that will eventually be passed to the CGI module's header() method.

  • header_out()

    This works much like the Apache method of the same name. When passed the name of a header, returns the value of the given outgoing header. When passed a name and a value, sets the value of the header. Setting the header to undef will actually unset the header (instead of setting its value to undef), removing it from the table of headers that will be sent to the client.

    The headers are eventually passed to the CGI module's header() method.

  • err_headers_out()

    This works much like the Apache method of the same name. In an array context, it will return a %hash of error response headers. In a scalar context, it will return a reference to the case-insensitive hash blessed into the HTML::Mason::FakeTable class. Changes made to this hash will be made to the error headers that will eventually be passed to the CGI module's header() method.

  • err_header_out()

    This works much like the Apache method of the same name. When passed the name of a header, returns the value of the given outgoing error header. When passed a name and a value, sets the value of the error header. Setting the header to undef will actually unset the header (instead of setting its value to undef), removing it from the table of headers that will be sent to the client.

    The headers are eventually passed to the CGI module's header() method.

    One header currently gets special treatment - if you set a Location header, you'll cause the CGI module's redirect() method to be used instead of the header() method. This means that in order to do a redirect, all you need to do is:

     $r->err_header_out(Location => 'http://redirect.to/here');

    You may be happier using the $m->redirect method, though, because it hides most of the complexities of sending headers and getting the status code right.

  • content_type()

    When passed an argument, sets the content type of the current request to the value of the argument. Use this method instead of setting a Content-Type header directly with header_out(). Like header_out(), setting the content type to undef will remove any content type set previously.

    When called without arguments, returns the value set by a previous call to content_type(). The behavior when content_type() hasn't already been set is undefined - currently it returns undef.

    If no content type is set during the request, the default MIME type text/html will be used.

  • method()

    Returns the request method used for the current request, e.g., "GET", "POST", etc.

  • http_header()

    This method returns the outgoing headers as a string, suitable for sending to the client.

  • send_http_header()

    Sends the outgoing headers to the client.

  • notes()

    This works much like the Apache method of the same name. When passed a $key argument, it returns the value of the note for that key. When passed a $value argument, it stores that value under the key. Keys are case-insensitive, and both the key and the value must be strings. When called in a scalar context with no $key argument, it returns a hash reference blessed into the HTML::Mason::FakeTable class.

  • pnotes()

    Like notes(), but takes any scalar as an value, and stores the values in a case-sensitive hash.

  • subprocess_env()

    Works like the Apache method of the same name, but is simply populated with the current values of the environment. Still, it's useful, because values can be changed and then seen by later components, but the environment itself remains unchanged. Like the Apache method, it will reset all of its values to the current environment again if it's called without a $key argument.

  • params()

    This method returns a hash containing the parameters sent by the client. Multiple parameters of the same name are represented by array references. If both POST and query string arguments were submitted, these will be merged together.

Added $m methods

The $m object provided in components has all the functionality of the regular HTML::Mason::Request object $m, and the following:

  • cgi_object()

    Returns the current CGI request object. This is handy for processing cookies or perhaps even doing HTML generation (but is that really what you want to do?). If you pass an argument to this method, you can set the request object to the argument passed. Use this with care, as it may affect components called after the current one (they may check the content length of the request, for example).

    Note that the ApacheHandler class (for using Mason under mod_perl) also provides a cgi_object() method that does the same thing as this one. This makes it easier to write components that function equally well under CGIHandler and ApacheHandler.

  • cgi_request()

    Returns the object that is used to emulate Apache's request object. In other words, this is the object that $r is set to when you use this class.

HTML::Mason::FakeTable Methods

This class emulates the behavior of the Apache::Table class, and is used to store manage the tables of values for the following attributes of <$r>:

headers_in
headers_out
err_headers_out
notes
subprocess_env

HTML::Mason::FakeTable is designed to behave exactly like Apache::Table, and differs in only one respect. When a given key has multiple values in an Apache::Table object, one can fetch each of the values for that key using Perl's each operator:

  while (my ($k, $v) = each %{$r->headers_out}) {
      push @cookies, $v if lc $k eq 'set-cookie';
  }

If anyone knows how Apache::Table does this, let us know! In the meantime, use get() or do() to get at all of the values for a given key (get() is much more efficient, anyway).

Since the methods named for these attributes return an HTML::Mason::FakeTable object hash in a scalar reference, it seemed only fair to document its interface.

  • new()

    Returns a new HTML::Mason::FakeTable object. Any parameters passed to new() will be added to the table as initial values.

  • add()

    Adds a new value to the table. If the value did not previously exist under the given key, it will be created. Otherwise, it will be added as a new value to the key.

  • clear()

    Clears the table of all values.

  • do()

    Pass a code reference to this method to have it iterate over all of the key/value pairs in the table. Keys will multiple values will trigger the execution of the code reference multiple times for each value. The code reference should expect two arguments: a key and a value. Iteration terminates when the code reference returns false, to be sure to have it return a true value if you wan it to iterate over every value in the table.

  • get()

    Gets the value stored for a given key in the table. If a key has multiple values, all will be returned when get() is called in an array context, and only the first value when it is called in a scalar context.

  • merge()

    Merges a new value with an existing value by concatenating the new value onto the existing. The result is a comma-separated list of all of the values merged for a given key.

  • set()

    Takes key and value arguments and sets the value for that key. Previous values for that key will be discarded. The value must be a string, or set() will turn it into one. A value of undef will have the same behavior as unset().

  • unset()

    Takes a single key argument and deletes that key from the table, so that none of its values will be in the table any longer.

SEE ALSO

HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::ApacheHandler


HTML::Mason::Cache::BaseCache - Base cache object

  • METHODS

NAME

HTML::Mason::Cache::BaseCache - Base cache object

DESCRIPTION

This is the base module for all cache implementations used in Mason. It provides a few additional methods on top of Cache::BaseCache in Dewitt Clinton's Cache::Cache package.

An object of this class is returned from $m->cache.

METHODS

clear ()

Remove all values in the cache.

get (key, [%params])

Returns the value associated with key or undef if it is non-existent or expired. This is extended with the following optional name/value parameters:

busy_lock => duration

If the value has expired, set its expiration time to the current time plus duration (instead of removing it from the cache) before returning undef. This is used to prevent multiple processes from recomputing the same expensive value simultaneously. The duration may be of any form acceptable to set.

expire_if => sub

If the value exists and has not expired, call sub with the cache object as a single parameter. If sub returns a true value, expire the value.

get_object (key)

Returns the underlying Cache::Object object associated with key. The most useful methods on this object are

    $co->get_created_at();    # when was object stored in cache
    $co->get_accessed_at();   # when was object last accessed
    $co->get_expires_at();    # when does object expire
expire (key)

Expires the value associated with key, if it exists. Differs from remove only in that the cache object is left around, e.g. for retrieval by get_object.

remove (key)

Removes the cache object associated with key, if it exists.

set (key, data, [duration])

Associates data with key in the cache. duration indicates the time until the value should be erased. If duration is unspecified, the value will never expire by time.

$expires_in may be a simple number of seconds, or a string of the form "[number] [unit]", e.g., "10 minutes". The valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w, week, weeks, M, month, months, y, year, and years.


HTML::Mason::Compiler - Compile Mason component source

  • PARAMETERS TO THE new() CONSTRUCTOR
  • METHODS
    • Compilation Callbacks
  • SEE ALSO

NAME

HTML::Mason::Compiler - Compile Mason component source

SYNOPSIS

  package My::Funky::Compiler;

  use base qw(HTML::Mason::Compiler);

DESCRIPTION

The compiler starts the compilation process by calling its lexer's lex method and passing itself as the compiler parameter. The lexer then calls various methods in the compiler as it parses the component source.

PARAMETERS TO THE new() CONSTRUCTOR

allow_globals

List of variable names, complete with prefix ($@%), that you intend to use as globals in components. Normally global variables are forbidden by strict, but any variable mentioned in this list is granted a reprieve via a "use vars" statement. For example:

    allow_globals => [qw($DBH %session)]

In a mod_perl environment, $r (the request object) is automatically added to this list.

default_escape_flags

Escape flags to apply to all <% %> expressions by default. The current valid flags are

    h - escape for HTML ('<' => '&lt;', etc.)
    u - escape for URL (':' => '%3A', etc.)

The developer can override default escape flags on a per-expression basis; see the escaping expressions section of the developer's manual.

If you want to set multiple flags as the default, this should be given as a reference to an array of flags.

lexer

The Lexer object to associate with this Compiler. By default a new object of class lexer_class will be created.

lexer_class

The class to use when creating a lexer. Defaults to HTML::Mason::Lexer.

preprocess

Sub reference that is called to preprocess each component before the compiler does it's magic. The sub is called with a single parameter, a scalar reference to the script. The sub is expected to process the script in-place. This is one way to extend the HTML::Mason syntax with new tags, etc., although a much more flexible way is to subclass the Lexer or Compiler class. See also postprocess_text and postprocess_perl.

postprocess_text

Sub reference that is called to postprocess the text portion of a compiled component, just before it is assembled into its final subroutine form. The sub is called with a single parameter, a scalar reference to the text portion of the component. The sub is expected to process the string in-place. See also preprocess and postprocess_perl.

postprocess_perl

Sub reference that is called to postprocess the Perl portion of a compiled component, just before it is assembled into its final subroutine form. The sub is called with a single parameter, a scalar reference to the Perl portion of the component. The sub is expected to process the string in-place. See also preprocess and postprocess_text.

use_source_line_numbers

True or false, default is true. Indicates whether component line numbers that appear in error messages, stack traces, etc. are in terms of the source file instead of the object file. Mason does this by inserting '#line' directives into compiled components. While source line numbers are more immediately helpful, object file line numbers may be more appropriate for in-depth debugging sessions.

METHODS

There are several methods besides the compilation callbacks below that a Compiler subclass needs to implement.

compile(comp_source => <string>, name => <string>, comp_class => <string>)

The "comp_class" parameter may be ignored by the compiler.

object_id

This method should return a unique id for the given compiler object. This is used by the interpreter when loading previously compiled objects in order to determine whether or not the object should be re-compiled.

Compilation Callbacks

These are methods called by the Lexer while processing a component source. You may wish to override some of these methods if you're implementing your own custom Compiler class.

start_component()

This method is called by the Lexer when it starts processing a component.

end_component()

This method is called by the Lexer when it finishes processing a component.

start_block(block_type => <string>)

This method is called by the Lexer when it encounters an opening Mason block tag like <%perl> or <%args>. Its main purpose is to keep track of the nesting of different kinds of blocks within each other. The type of block ("init", "once", etc.) is passed via the "block_type" parameter.

end_block(block_type => <string>)

This method is called by the Lexer when it encounters a closing Mason block tag like </%perl> or </%args>. Like start_block(), its main purpose is to help maintain syntactic integrity.

  • Several compiler methods like doc_block(), text_block(), and raw_block() are called by the Lexer after start_block() when it encounters blocks of certain types. These methods actually do the work of putting the body of a block into the compiled data structure.

    The methods that follow this pattern are init_block(), perl_block(), doc_block(), text_block(), and raw_block(). The last method is called for all <%once>, <%cleanup>, <%filter>, <%init>, <%perl>, and <%shared> blocks.

    • text(text => <string>)

    Inserts the text contained in a text parameter into the component for verbatim output.

    This is called when the lexer finds plain text in a component.

    variable_declaration( type => <string>, name => <string>, default => <string> )

    Inserts a variable declaration from the <%args> section into the component.

    The type will be either "$", "@", or "%", indicating a scalar, array, or hash. The name is the variable name without the leading sigil. The default is everything found after the first "=>" on an <%args> block line, and may include a comment.

    key_value_pair(block_type => <string>, key => <string>, value => <string>)

    Inserts a key-value pair from a <%flags> or <%attr> section into the component.

    The "block_type" parameter will be either "flags" or "attr".

    start_named_block(block_type => <string>, name => <name>)

    Analogous to item_start_block, but starts a "named" block (<%method> or <%def>).

    end_named_block()

    Called by the Lexer to end a "named" block.

    substitution(substitution => <string>, escape => <string>)

    Called by the Lexer when it encounters a substitution tag (<% ... %>).

    The value of the "escape" parameter will be everything found after the pipe (|) in the substitution tag, and may be more than one character such as "nh".

    component_call(call => <string>)

    Called by the Lexer when it encounters a component call tag without embedded content (<& ... &>).

    The "call" parameter contains the entire contents of the tag.

    component_content_call(call => <string>)

    Called by the Lexer when it encounters a component call tag with embedded content (<&| ... &>).

    component_content_call_end()

    Called by the Lexer when it encounters an ending tag for a component call with content (</&>). Note that there is no corresponding component_call_end() method for component calls without content, because these calls don't have ending tags.

    perl_line(line => <string>)

    Called by the Lexer when it encounters a %-line.

    SEE ALSO

    HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::Interp


HTML::Mason::Compiler::ToObject - A Compiler subclass that generates Mason object code

  • PARAMETERS TO THE new() CONSTRUCTOR
  • METHODS

NAME

HTML::Mason::Compiler::ToObject - A Compiler subclass that generates Mason object code

SYNOPSIS

  my $compiler = HTML::Mason::Compiler::ToObject->new;

  my $object_code = $compiler->compile( comp_source => $source, name => $comp_name );

DESCRIPTION

This Compiler subclass generates Mason object code (Perl code). It is the default Compiler class used by Mason.

PARAMETERS TO THE new() CONSTRUCTOR

All of these parameters are optional.

comp_class

The class into which component objects are blessed. This defaults to HTML::Mason::Component.

subcomp_class

The class into which subcomponent objects are blessed. This defaults to HTML::Mason::Component::Subcomponent.

in_package

This is the package in which a component's code is executed. For historical reasons, this defaults to HTML::Mason::Commands.

preamble

Text given for this parameter is placed at the beginning of each component. See also postamble.

postamble

Text given for this parameter is placed at the end of each component. See also preamble.

use_strict

True or false, default is true. Indicates whether or not a given component should use strict.

define_args_hash

One of "always", "auto", or "never". This determines whether or not an %ARGS hash is created in components. If it is set to "always", one is always defined. If set to "never", it is never defined.

The default, "auto", will cause the hash to be defined only if some part of the component contains the string "ARGS". This is somewhat crude, and may result in some false positives, but this is preferable to false negatives.

Not defining the args hash means that we can avoid copying component arguments, which can save memory and slightly improve execution speed.

METHODS

This class is primarily meant to be used by the Interpreter object, and as such has a very limited public API.

compile (comp_source => $source, name => $name, comp_class = $comp_class)

This method will take component source and return the compiled object code for that source. The comp_source and name parameters are optional. The comp_class can be used to change the component class for this one comonent.


HTML::Mason::Component - Mason Component Class

    • CREATING AND ACCESSING COMPONENTS
  • METHODS
  • FILE-BASED METHODS
  • SEE ALSO

NAME

HTML::Mason::Component - Mason Component Class

SYNOPSIS

    my $comp1 = $m->current_comp;
    my $comp2 = $m->callers(1);
    my $comp3 = $m->fetch_comp('foo/bar');

    foreach ($comp1,$comp2,$comp3) {
       print "My name is ".$_->title.".\n";
    }

DESCRIPTION

Mason uses the Component class to store components loaded into memory. Components come from three distinct sources:

  1. File-based: loaded from a source or object file.

  2. Subcomponents: embedded components defined with the <%def> or <%method> tags.

  3. Anonymous: created on-the-fly with the make_component Interp method.

Some of the methods below return different values (or nothing at all) depending on the component type.

The component API is primarily useful for introspection, e.g. "what component called me" or "does the next component take a certain argument". You can build complex Mason sites without ever dealing directly with a component object.

CREATING AND ACCESSING COMPONENTS

Common ways to get handles on existing component objects include the
Request->current_comp,
Request->callers, and
Request->fetch_comp methods.

There is no published new method, because creating a component requires an Interpreter. Use the make_component method to create a new component dynamically.

Similarly, there is no execute or call method, because calling a component requires a request. All of the interfaces for calling a component (<& &>, $m-comp>, $interp->exec) which normally take a component path will also take a component object.

METHODS

attr (name)

Looks for the specified attribute in this component and its parents, returning the first value found. Dies with an error if not found. Attributes are declared in the <%attr> section.

attr_if_exists (name)

This method works exactly like the one above but returns undef if the attribute does not exist.

attr_exists (name)

Returns true if the specified attribute exists in this component or one of its parents, undef otherwise.

attributes

Returns a hashref containing the attributes defined in this component, with the attribute names as keys. This does not return attributes inherited from parent components.

call_method (name, args...)

Looks for the specified user-defined method in this component and its parents, calling the first one found. Dies with an error if not found. Methods are declared in the <%method> section.

create_time

A synonym for load_time (deprecated).

declared_args

Returns a reference to a hash of hashes representing the arguments declared in the <%args> section. The keys of the main hash are the variable names including prefix (e.g. $foo, @list). Each secondary hash contains:

  • 'default': the string specified for default value (e.g. 'fido') or undef if none specified. Note that in general this is not the default value itself but rather a Perl expression that gets evaluated every time the component runs.

For example:

  # does $comp have an argument called $fido?
  if (exists($comp->declared_args->{'$fido'})) { ... }

  # does $fido have a default value?
  if (defined($comp->declared_args->{'$fido'}->{default})) { ... }
dir_path

Returns the component's notion of a current directory, relative to the component root; this is used to resolve relative component paths. For file-based components this is the full component path minus the filename. For subcomponents this is the same as the component that defines it. Undefined for anonymous components.

flag (name)

Returns the value for the specified system flag. Flags are declared in the <%flags> section and affect the behavior of the component. Unlike attributes, flags values do not get inherited from parent components.

is_subcomp

Returns true if this is a subcomponent of another component. For historical reasons, this returns true for both methods and subcomponents.

is_method

Returns true if this is a method.

is_file_based

Returns true if this component was loaded from a source or object file.

load_time

Returns the time (in Perl time() format) when this component object was created.

method_exists (name)

Returns true if the specified user-defined method exists in this component or one of its parents, undef otherwise.

methods

This method works exactly like the subcomps method, but it returns methods, not subcomponents. This does not return methods inherited from parent components.

Methods are declared in <%method> sections.

name

Returns a short name of the component. For file-based components this is the filename without the path. For subcomponents this is the name specified in <%def>. Undefined for anonymous components.

object_file

Returns the object filename for this component.

owner

Defined only for subcomponents; returns the component that this subcomponent was defined in.

parent

Returns the parent of this component for inheritance purposes, by default the nearest autohandler in or above the component's directory. Can be changed via the inherit flag.

path

Returns the entire path of this component, relative to the component root.

scall_method (name, args...)

Like item_call_method, but returns the method output as a string instead of printing it. (Think sprintf versus printf.) The method's return value, if any, is discarded.

subcomps

With no arguments, returns a hashref containing the subcomponents defined in this component, with names as keys and component objects as values. With one argument, returns the subcomponent of that name or undef if no such subcomponent exists. e.g.

    if (my $subcomp = $comp->subcomps('.link')) {
        ...
    }

Subcomponents are declared in <%def> sections.

title

Returns a printable string denoting this component. It is intended to uniquely identify a component within a given interpreter although this is not 100% guaranteed. Mason uses this string in error messages, among other places.

For file-based components this is the component path. For subcomponents this is "parent_component_path:subcomponent_name". For anonymous components this is a unique label like "[anon 17]".

FILE-BASED METHODS

The following methods apply only to file-based components (those loaded from source or object files). They return undef for other component types.

source_file

Returns the source filename for this component.

source_dir

Returns the directory of the source filename for this component.

SEE ALSO

HTML::Mason,
HTML::Mason::Devel,
HTML::Mason::Request


HTML::Mason::Component::FileBased - Mason File-Based Component Class

  • METHODS
  • SEE ALSO

NAME

HTML::Mason::Component::FileBased - Mason File-Based Component Class

DESCRIPTION

This is a subclass of HTML::Mason::Component. Mason uses it to implement components which are stored in files.

METHODS

See the FILE-BASED METHODS section of HTML::Mason::Component for documentation.

SEE ALSO

HTML::Mason::Component


HTML::Mason::Component::Subcomponent - Mason Subcomponent Class

  • METHODS
  • SEE ALSO

NAME

HTML::Mason::Component::Subcomponent - Mason Subcomponent Class

DESCRIPTION

This is a subclass of HTML::Mason::Component. Mason uses it to implement both subcomponents (defined by <%def>) and methods (defined by <%method>).

A subcomponent gets most of its properties from its owner.

METHODS

is_method

Returns 1 if this is a method (declared by <%method>), 0 if it is a subcomponent (defined by c<< <%def> >>).

owner

Return the component object that this subcomponent or method was defined within.

SEE ALSO

HTML::Mason::Component


HTML::Mason::ComponentSource - represents information about an component

  • METHODS

NAME

HTML::Mason::ComponentSource - represents information about an component

SYNOPSIS

    my $info = $resolver->get_info($comp_path);

DESCRIPTION

Mason uses the ComponentSource class to store information about a source component, one that has yet to be compiled.

METHODS

new

This method takes the following arguments:

  • comp_path

    The component's component path.

  • last_modified

    This is the last modificatoin time for the component, in Unix time (seconds since the epoch).

  • comp_id

    This is a unique id for the component used to distinguish two components with the same name in different component roots.

    If your resolver does not support multiple component roots, this can simply be the same as the "comp_path" key or it can be any other id you wish.

    This value will be used when constructing filesystem paths so it needs to be something that works on different filesystems. If it contains forward slashes, these will be converted to the appropriate filesystem-specific path separator.

    In fact, we encourage you to make sure that your component ids have some forward slashes in them or also all of your generated object files will end up in a single directory, which could affect performance.

  • comp_class

    The component class into which this particular component should be blessed when it is created. This must be a subclass of HTML::Mason::Component, which is the default.

  • friendly_name

    This is used when displaying error messages related to the component, like parsing errors. This should be something that will help whoever sees the message identify the component. For example, for component stored on the filesystem, this should be the absolute path to the component.

  • source_callback

    This is a subroutine reference which, when called, returns the component source.

    The reasoning behind using this parameter is that it helps avoid a profusion of tiny little HTML::Mason::ComponentSource subclasses that don't do very much.

  • extra

    This optional parameter should be a hash reference. It is used to pass information from the resolver to the component class.

    This is needed since a HTML::Mason::Resolver subclass and a HTML::Mason::Component subclass can be rather tightly coupled, but they must communicate with each through the interpreter (this may change in the future).

comp_path
last_modified
comp_id
comp_class
friendly_name
extra

These are all simple accessors that return the value given to the constructor.

comp_source

Returns the source of the component.

object_code ( compiler => $compiler )

Given a compiler, this method returns the object code for the component.

HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::Component


HTML::Mason::Devel - Mason Developer's Manual

  • HOW TO USE THIS MANUAL
  • WHAT ARE COMPONENTS?
  • IN-LINE PERL SECTIONS
    • Examples and Recommended Usage
  • MASON OBJECTS
    • Request Objects
    • Component Objects
    • System Objects
  • CALLING COMPONENTS
    • Components that output HTML
    • Component Calls with Content
    • Advanced Components Calls with Content
    • Components that compute values
    • Subrequests
  • TOP-LEVEL COMPONENTS
    • dhandlers
    • autohandlers
    • dhandlers vs. autohandlers
  • PASSING PARAMETERS
    • In Component Calls
    • In HTTP requests
    • Accessing Parameters
    • Parameter Passing Examples
    • Using @_ instead
  • INITIALIZATION AND CLEANUP
    • <%init>
    • <%cleanup>
    • <%once>
    • <%shared>
  • EMBEDDED COMPONENTS
    • <%def name>
    • <%method name>
  • FLAGS AND ATTRIBUTES
    • <%flags>
    • <%attr>
  • FILTERING
    • <%filter> section
  • OTHER SYNTAX
    • <%doc>
    • <%text>
    • Escaping expressions
      • User-defined Escapes
      • Manually applying escapes
    • Backslash at end of line
  • DATA CACHING
    • Basic Usage
    • Multiple Keys/Values
    • Expiration
    • Avoiding Concurrent Recomputation with Busy Locks
    • Caching All Output
    • Cache Object
    • Choosing a Cache Subclass
    • Accessing a Cache Externally
    • Mason 1.0x Cache API
  • WEB-SPECIFIC FEATURES
    • Sending HTTP Headers
    • Returning HTTP Status
      • Filters and $m->abort
    • External Redirects
    • Internal Redirects
  • USING THE PERL DEBUGGER
  • OBJECT-ORIENTED TECHNIQUES
    • Determining inheritance
    • Content wrapping
    • Accessing methods and attributes
    • Sharing data
    • Example
  • COMMON TRAPS
  • MASON AND SOURCE FILTERS
  • AUTHORS
  • SEE ALSO

NAME

HTML::Mason::Devel - Mason Developer's Manual

DESCRIPTION

This manual is written for content developers who know HTML and at least a little Perl. The goal is to write, run, and debug Mason components.

If you are the webmaster (or otherwise responsible for the Mason installation), you should also read the administrator's manual. There you will find information about site configuration, performance tuning, component caching, and so on.

If you are a developer just interested in knowing more about Mason's capabilities and implementation, then the administrator's manual is for you too.

We strongly suggest that you have a working Mason to play with as you work through these examples. Other component examples can be found in the samples/ directory.

While Mason can be used for tasks besides implementing a dynamic web site, that is what most people want to do with Mason, and is thus the focus of this manual.

If you are planning to use Mason outside of the web, this manual will still be useful, of course. Also make sure to read the running outside of mod_perl section of the administrator's manual.

HOW TO USE THIS MANUAL

If you are just learning Mason and want to get started quickly, we recommend the following sections:

o What Are Components?

o In-Line Perl Sections

o Calling Components

o Top-Level Components

o Passing Parameters

o Initialization and Cleanup (mainly <%init>)

o Web-Specific Features

o Common Traps

WHAT ARE COMPONENTS?

The component - a mix of Perl and HTML - is Mason's basic building block and computational unit. Under Mason, web pages are formed by combining the output from multiple components. An article page for a news publication, for example, might call separate components for the company masthead, ad banner, left table of contents, and article body. Consider this layout sketch:

    +---------+------------------+
    |Masthead | Banner Ad        |
    +---------+------------------+
    |         |                  |
    |+-------+|Text of Article ..|
    ||       ||                  |
    ||Related||Text of Article ..|
    ||Stories||                  |
    ||       ||Text of Article ..|
    |+-------+|                  |
    |         +------------------+
    |         | Footer           |
    +---------+------------------+

The top level component decides the overall page layout, perhaps with HTML tables. Individual cells are then filled by the output of subordinate components, one for the Masthead, one for the Footer, etc. In practice pages are built up from as few as one, to as many as twenty or more components.

This component approach reaps many benefits in a web environment. The first benefit is consistency: by embedding standard design elements in components, you ensure a consistent look and make it possible to update the entire site with just a few edits. The second benefit is concurrency: in a multi-person environment, one person can edit the masthead while another edits the table of contents. A last benefit is reuseability: a component produced for one site might be useful on another. You can develop a library of generally useful components to employ on your sites and to share with others.

Most components emit chunks of HTML. "Top level" components, invoked from a URL, represent an entire web page. Other, subordinate components emit smaller bits of HTML destined for inclusion in top level components.

Components receive form and query data from HTTP requests. When called from another component, they can accept arbitrary parameter lists just like a subroutine, and optionally return values. This enables a type of component that does not print any HTML, but simply serves as a function, computing and returning a result.

Mason actually compiles components down to Perl subroutines, so you can debug and profile component-based web pages with standard Perl tools that understand the subroutine concept, e.g. you can use the Perl debugger to step through components, and Devel::DProf to profile their performance.

IN-LINE PERL SECTIONS

Here is a simple component example:

    <%perl>
    my $noun = 'World';
    my @time = localtime;
    </%perl>
    Hello <% $noun %>,
    % if ( $time[2] < 12 ) {
    good morning.
    % } else {
    good afternoon.
    % }

After 12 pm, the output of this component is:

    Hello World, good afternoon.

This short example demonstrates the three primary "in-line" Perl sections. In-line sections are generally embedded within HTML and execute in the order they appear. Other sections (<%init>, <%args>, etc.) are tied to component events like initialization, cleanup, and argument definition.

The parsing rules for these Perl sections are as follows:

  1. Blocks of the form <% xxx %> are replaced with the result of evaluating xxx as a single Perl expression. These are often used for variable replacement. such as 'Hello, <% $name %>!'.

  2. Lines beginning with a '%' character are treated as Perl.

  3. Multiline blocks of Perl code can be inserted with the <%perl> .. </%perl> tag. The enclosed text is executed as Perl and the return value, if any, is discarded.

    The <%perl> tag, like all block tags in Mason, is case-insensitive. It may appear anywhere in the text, and may span any number of lines. <%perl> blocks cannot be nested inside one another.

Examples and Recommended Usage

% lines

Most useful for conditional and loop structures - if, while, foreach, , etc. - as well as side-effect commands like assignments. Examples:

o Conditional code

    % my $ua = $r->header_in('User-Agent');
    % if ($ua =~ /msie/i) {
    Welcome, Internet Explorer users
    ...
    % } elsif ($ua =~ /mozilla/i) {
    Welcome, Netscape users
    ...
    % }

o HTML list formed from array

    <ul>
    % foreach $item (@list) {
    <li><% $item %>
    % }
    </ul>

o HTML list formed from hash

    <ul>
    % while (my ($key,$value) = each(%ENV)) {
    <li>
    <b><% $key %></b>: <% $value %>
    % }
    </ul>

o HTML table formed from list of hashes

    <table>
    % foreach my $h (@loh) {
    <tr>
    <td><% $h->{foo} %></td>
    <td bgcolor=#ee0000><% $h->{bar} %></td>
    <td><% $h->{baz} %></td>
    </tr>
    % }
    </table>

<% xxx % >>

Most useful for printing out variables, as well as more complex expressions. Examples:

  Dear <% $name %>: We will come to your house at <% $address %> in the
  fair city of <% $city %> to deliver your $<% $amount %> dollar prize!
  The answer is <% ($y+8) % 2 %>.
  You are <% $age < 18 ? 'not' : '' %> permitted to enter this site.

<%perl xxx </%perl> >>

Useful for Perl blocks of more than a few lines.

MASON OBJECTS

This section describes the various objects in the Mason universe. If you're just starting out, all you need to worry about initially are the request objects.

Request Objects

Two global per-request objects are available to all components: $r and $m.

$r, the mod_perl request object, provides a Perl API to the current Apache request. It is fully described in Apache.pod. Here is a sampling of methods useful to component developers:

    $r->uri             # the HTTP request URI
    $r->header_in(..)   # get the named HTTP header line
    $r->content_type    # set or retrieve content-type
    $r->header_out(..)  # set or retrieve an outgoing header
    $r->content         # don't use this one! (see Tips and Traps)

$m, the Mason request object, provides an analogous API for Mason. Almost all Mason features not activated by syntactic tags are accessed via $m methods. You'll be introduced to these methods throughout this document as they are needed. For a description of all methods see HTML::Mason::Request.

Because these are always set inside components, you should not ever define other variables with the same name, or else your code may fail in strange and mysterious ways.

Component Objects

Mason provides an object API for components, allowing you to query a component's various asociated files, arguments, etc. For a description of all methods see HTML::Mason::Component. Typically you get a handle on a component object from request methods like < $m-current_comp >> and $m->fetch_comp.

Note that for many basic applications all you'll want to do with components is call them, for which no object method is needed. See next section.

System Objects

Many system objects share the work of serving requests in Mason: HTML::Mason::Lexer, HTML::Mason::Compiler, HTML::Mason::Interp, HTML::Mason::Resolver, and HTML::Mason::ApacheHandler are examples. The administrator creates these objects and provides parameters that shape Mason's behavior. As a pure component developer you shouldn't need to worry about or access these objects, but occasionally we'll mention a relevant parameter.

CALLING COMPONENTS

Mason pages often are built not from a single component, but from multiple components that call each other in a hierarchical fashion.

Components that output HTML

To call one component from another, use the <& &> tag:

    <& comp_path, [name=>value, ...] &>
comp_path:

The component path. With a leading '/', the path is relative to the component root (comp_root). Otherwise, it is relative to the location of the calling component.

name => value pairs:

Parameters are passed as one or more name => value pairs, e.g. player => 'M. Jordan'.

comp_path may be a literal string (quotes optional) or a Perl expression that evaluates to a string. To eliminate the need for quotes in most cases, Mason employs some magic parsing: If the first character is one of [\w/_.], comp_path is assumed to be a literal string running up to the first comma or &>. Otherwise, comp_path is evaluated as an expression.

Here are some examples:

    # relative component paths
    <& topimage &>
    <& tools/searchbox &>
    # absolute component path
    <& /shared/masthead, color=>'salmon' &>
    # this component path MUST have quotes because it contains a comma
    <& "sugar,eggs", mix=>1 &>
    # variable component path
    <& $comp &>
    # variable component and arguments
    <& $comp, %args &>
    # you can use arbitrary expression for component path, but it cannot
    # begin with a letter or number; delimit with () to remedy this
    <& (int(rand(2)) ? 'thiscomp' : 'thatcomp'), id=>123 &>

Several request methods also exist for calling components. $m->comp performs the equivalent action to <& &>:

    $m->comp('/shared/masthead', color=>'salmon');

$m->scomp is like the sprintf version of $m->comp: it returns the component output, allowing the caller to examine and modify it before printing:

    my $masthead = $m->scomp('/shared/masthead', color=>'salmon');
    $masthead =~ ...;
    $m->print($masthead);

Component Calls with Content

Components can be used to filter part of the page's content using an extended component syntax.

    <&| /path/to/comp &> this is the content </&>
    <&| comp, arg1 => 'hi' &> filters can take arguments </&>
    <&| comp &> content can include <% "tags" %> of all kinds </&>
    <&| comp1 &> nesting is also <&| comp2 &> OK </&> </&>
    <&| SELF:method1 &> subcomponents can be filters </&>

The filtering component can be called in all the same ways a normal component is called, with arguments and so forth. The only difference between a filtering component and a normal component is that a filtering component is expected to fetch the content by calling $m->content and do something with it.

Here is an example of a component used for localization. Its content is a series of strings in different languages, and it selects the correct one based on a global $lang variable, which could be setup in a site-level autohandler.

   <&| /i18n/itext &>
      <en>Hello, <% $name %> This is a string in English</en>
      <de>Schoene Gruesse, <% $name %>, diese Worte sind auf Deutsch</de>
      <pig>ellohay <% substr($name,2).substr($name,1,1).'ay' %>,
      isthay isay igpay atinlay</pig>
   </&>

Here is the /i18n/itext component:

   <% $text %>
   <%init>
   # this assumes $lang is a global variable which has been set up earlier.
   local $_ = $m->content;
   my ($text) = m{<$lang>(.*?)</$lang>};
   </%init>

You can explicitly check whether a component has passed content by checking the boolean $m->has_content. This allows you to write a component that will do different things depending on whether it was passed content. However, before overloading a component in this way, consider whether splitting the behavior into two distinct components would work as well.

If a normal component which does not call $m->content is called with content, the content will not be output.

If you wrap a filtering component call around the entire component, the result will be functionally similar to a <%filter> section. See also Filtering.

Advanced Components Calls with Content

Internally $m->content is implemented with a closure containing the part of the component which is the content. In English, that means that any mason tags and perl code in the content are evaluated when $m->content is called, and $m->content returns the text which would have been output by mason. Because the contents are evaluated at the time that $m->content is called, one can write components which act as control structures or which output their contents multiple times with different values for the variables (can you say taglibs?).

The tricky part of using filter components as control structures is setting up variables which can be accessed from both the filter component and the content, which is in the component which calls the filter component. The content has access to all variables in the surrounding component, but the filtering component does not. There are two ways to do this: use global variables, or pass a reference to a lexical variable to the filter component.

Here is a simple example using the second method:

    % my $var;
    <ol>
    <&| list_items , list => \@items, var => \$var &>
    <li> <% $var %>
    </&>
    </ol>

list_items component:

    <%args>
    @list
    $var
    </%args>
    % foreach (@list) {
    % $$var = $_;  # $var is a reference
    <% $m->content %>
    % }

Using global variables can be somewhat simpler. Below is the same example, with $var defined as a global variable. The site administrator must make sure that $var is included in Mason's allow_globals parameter. Local-izing $var within the filter component will allow the list_items component to be nested.

    <ol>
    <&| list_items, list => \@items &>
    <li> <% $var %>
    </&>
    </ol>

list_items component:

    <%args>
    @list
    </%args>
    % foreach (@list) {
    % local $var = $_;
    <% $m->content %>
    % }

Besides remembering to include $var in allow_globals, the developers should take care not to use that variable is other places where it might conflict with usage by the filter component. Local-izing $var will also provide some protection against using it in other places.

An even simpler method is to use the $_ variable. It is already global, and is automatically local-ized by the foreach statement:

    <ol>
    <&| list_items, list => \@items &>
    <li> <% $_ %>
    </&>
    </ol>

list_items component:

    <%args>
    @list
    </%args>
    % foreach (@list) {
    <% $m->content %>
    % }

Components that compute values

So far you have seen components used solely to output HTML. However, components may also be used to compute a value. For example, you might have a component is_netscape that analyzes the user agent to determine whether it is a Netscape browser:

    <%perl>
    my $ua = $r->header_in('User-Agent');
    return ($ua =~ /Mozilla/i && $ua !~ /MSIE/i) ? 1 : 0;
    </%perl>

Because components are implemented underneath with Perl subroutines, they can return values and even understand scalar/list context. e.g. The result of wantarray() inside a component will reflect whether the component was called in scalar or list context.

The <& &> notation only calls a component for its side-effect, and discards its return value, if any. To get at the return value of a component, use the $m->comp command:

    % if ($m->comp('is_netscape')) {
    Welcome, Netscape user!
    % }

Mason adds a return undef to the bottom of each component to provide an empty default return value. To return your own value from a component, you must use an explicit return statement. You cannot rely on the usual Perl trick of letting return values "fall through".

Generally components are divided into two types: those that output HTML, and those that return a value. There is very little reason for a component to do both. For example, it would not be very friendly for is_netscape to output "hi Mom" while it was computing its value, thereby surprising the if statement! Conversely, any value returned by an HTML component would typically be discarded by the <& &> tag that invoked it.

Subrequests

You may sometimes want to have a component call go through all the steps that the initial component call goes through, such as checking for autohandlers and dhandlers. To do this, you need to execute a subrequest.

A subrequest is simply a Mason Request object and has all of the methods normally associated with one.

To create a subrequest you simply use the $m->make_subrequest method. This method can take any parameters belonging to HTML::Mason::Request, such as autoflush or out_method. Once you have a new request object you simply call its exec method to execute it, which takes exactly the same parameters as the comp method.

Since subrequests inherit their parent request's parameters, output from a component called via a subrequest goes to the same desintation as output from components caled during the parent request. Of course, you can change this.

Here are some examples:

  <%perl>
   my $req = $m->make_subrequest( comp => '/some/comp', args => [ id => 172 ] );
   $req->exec;
  </%perl>

If you want to capture the subrequest's output in a scalar, you can simply pass an out_method parameter to $m->make_subrequest:

  <%perl>
   my $buffer;
   my $req =
       $m->make_subrequest
           ( comp => '/some/comp', args => [ id => 172 ], out_method => \$buffer );
   $req->exec;
  </%perl>

Now $buffer contains all the output from that call to /some/comp.

For convenience, Mason also provides an $m->subexec method. This method takes the same arguments as $m->comp and internally calls $m->make_subrequest and then exec on the created request, all in one fell swoop. This is useful in cases where you have no need to override any of the parent request object's attributes.

By default, output from a subrequest appears inline in the calling component, at the point where it is executed. If you wish to do something else, you will need to explicitly override the subrequest's out_method parameter.

Mason Request objects are only designed to handle a single call to exec. If you wish to make multiple subrequests, you must create a new subrequest object for each one.

TOP-LEVEL COMPONENTS

The first component invoked for a page (the "top-level component") resides within the DocumentRoot and is chosen based on the URL. For example:

    http://www.foo.com/mktg/prods.html?id=372

Mason converts this URL to a filename, e.g. /usr/local/www/htdocs/mktg/prods.html. Mason loads and executes that file as a component. In effect, Mason calls

    $m->comp('/mktg/prods.html', id=>372)

This component might in turn call other components and execute some Perl code, or it might contain nothing more than static HTML.

dhandlers

What happens when a user requests a component that doesn't exist? In this case Mason scans backward through the URI, checking each directory for a component named dhandler ("default handler"). If found, the dhandler is invoked and is expected to use $m->dhandler_arg as the parameter to some access function, perhaps a database lookup or location in another filesystem. In a sense, dhandlers are similar in spirit to Perl's AUTOLOAD feature; they are the "component of last resort" when a URL points to a non-existent component.

Consider the following URL, in which newsfeeds/ exists but not the subdirectory LocalNews nor the component Story1:

    http://myserver/newsfeeds/LocalNews/Story1

In this case Mason constructs the following search path:

    /newsfeeds/LocalNews/Story1         => no such thing
    /newsfeeds/LocalNews/dhandler       => no such thing
    /newsfeeds/dhandler                 => found! (search ends)
    /dhandler

The found dhandler would read "LocalNews/Story1" from $m->dhandler_arg and use it as a retrieval key into a database of stories.

Here's how a simple /newsfeeds/dhandler might look:

    <& header &>
    <b><% $headline %></b><p>
    <% $body %>
    <& footer &>
    <%init>
    my $arg = $m->dhandler_arg;                # get rest of path
    my ($section, $story) = split("/", $arg);  # split out pieces
    my $sth = $DBH->prepare
        (qq{SELECT headline,body FROM news
            WHERE section = ? AND story = ?);
    $sth->execute($section, $story);
    my ($headline, $body) = $sth->fetchrow_array;
    return 404 if !$headline;                  # return "not found" if no such story
    </%init>

By default dhandlers do not get a chance to handle requests to a directory itself (e.g. /newsfeeds). These are automatically deferred to Apache, which generates an index page or a FORBIDDEN error. Often this is desirable, but if necessary the administrator can let in directory requests as well; see the allowing directory requests section of the administrator's manual.

A component or dhandler that does not want to handle a particular request may defer control to the next dhandler by calling < $m-decline >>.

When using dhandlers under mod_perl, you may find that sometimes Apache will not set a content type for a response. This usually happens when a dhandler handles a request for a non-existent file or directory. You can add a <Location> or <LocationMatch> block containing a SetType directive to your Apache config file, or you can just set the content type dynamically by calling < $r-content_type >>.

The administrator can customize the file name used for dhandlers with the dhandler_name parameter.

autohandlers

Autohandlers allow you to grab control and perform some action just before Mason calls the top-level component. This might mean adding a standard header and footer, applying an output filter, or setting up global variables.

Autohandlers are directory based. When Mason determines the top-level component, it checks that directory and all parent directories for a component called autohandler. If found, the autohandler is called first. After performing its actions, the autohandler typically calls $m->call_next to transfer control to the original intended component.

$m->call_next works just like $m->comp except that the component path and arguments are implicit. You can pass additional arguments to $m->call_next; these are merged with the original arguments, taking precedence in case of conflict. This allows you, for example, to override arguments passed in the URL.

Here is an autohandler that adds a common header and footer to each page underneath its directory:

    <HTML>
    <HEAD><TITLE>McHuffy Incorporated</TITLE></HEAD>
    <BODY BGCOLOR="salmon">
    % $m->call_next;

    <HR>
    Copyright 1999 McHuffy Inc.
    </BODY>
    </HTML>

Same idea, using components for the header/footer:

    <& /shared/header &>
    % $m->call_next;
    <& /shared/footer &>

The next autohandler applies a filter to its pages, adding an absolute hostname to relative image URLs:

    % $m->call_next;

    <%filter>
    s{(<img[^>]+src=\")/} {$1http://images.mysite.com/}ig;
    </%filter>

Most of the time autohandler can simply call $m->call_next without needing to know what the next component is. However, should you need it, the component object is available from $m->fetch_next. This is useful for calling the component manually, e.g. if you want to suppress some original arguments or if you want to use $m->scomp to store and process the output.

What happens if more than one autohandler applies to a page? Prior to version 0.85, only the most specific autohandler would execute. In 0.85 and beyond each autohandler gets a chance to run. The top-most autohandler runs first; each $m->call_next transfers control to the next autohandler and finally to the originally called component. This allows you, for example, to combine general site-wide templates and more specific section-based templates.

Autohandlers can be made even more powerful in conjunction with Mason's object-oriented style features: methods, attributes, and inheritance. In the interest of space these are discussed in a separate section, Object-Oriented Techniques.

The administrator can customize the file name used for autohandlers with the autohandler_name parameter.

dhandlers vs. autohandlers

dhandlers and autohandlers both provide a way to exert control over a large set of URLs. However, each specializes in a very different application. The key difference is that dhandlers are invoked only when no appropriate component exists, while autohandlers are invoked only in conjunction with a matching component.

As a rule of thumb: use an autohandler when you have a set of components to handle your pages and you want to augment them with a template/filter. Use a dhandler when you want to create a set of "virtual URLs" that don't correspond to any actual components, or to provide default behavior for a directory.

dhandlers and autohandlers can even be used in the same directory. For example, you might have a mix of real URLs and virtual URLs to which you would like to apply a common template/filter.

PASSING PARAMETERS

This section describes Mason's facilities for passing parameters to components (either from HTTP requests or component calls) and for accessing parameter values inside components.

In Component Calls

Any Perl data type can be passed in a component call:

    <& /sales/header, s => 'dog', l => [2, 3, 4], h => {a => 7, b => 8} &>

This command passes a scalar ($s), a list (@l), and a hash (%h). The list and hash must be passed as references, but they will be automatically dereferenced in the called component.

In HTTP requests

Consider a CGI-style URL with a query string:

    http://www.foo.com/mktg/prods.html?str=dog&lst=2&lst=3&lst=4

or an HTTP request with some POST content. Mason automatically parses the GET/POST values and makes them available to the component as parameters.

Accessing Parameters

Component parameters, whether they come from GET/POST or another component, can be accessed in two ways.

1. Declared named arguments: Components can define an <%args> section listing argument names, types, and default values. For example:

    <%args>
    $a
    @b       # a comment
    %c
    # another comment
    $d => 5
    $e => $d*2
    @f => ('foo', 'baz')
    %g => (joe => 1, bob => 2)
    </%args>

Here, $a, @b, and %c are required arguments; the component generates an error if the caller leaves them unspecified. $d, $e, @f and %g are optional arguments; they are assigned the specified default values if unspecified. All the arguments are available as lexically scoped ("my") variables in the rest of the component.

Arguments are separated by one or more newlines. Comments may be used at the end of a line or on their own line.

Default expressions are evaluated in top-to-bottom order, and one expression may reference an earlier one (as $e references $d above).

Only valid Perl variable names may be used in <%args> sections. Parameters with non-valid variable names cannot be pre-declared and must be fetched manually out of the %ARGS hash (see below). One common example of undeclarable parameters are the "button.x/button.y" parameters sent for a form submit.

2. %ARGS hash: This variable, always available, contains all of the parameters passed to the component (whether or not they were declared). It is especially handy for dealing with large numbers of parameters, dynamically named parameters, or parameters with non-valid variable names. %ARGS can be used with or without an <%args> section, and its contents are unrelated to what you have declared in <%args>.

Here's how to pass all of a component's parameters to another component:

    <& template, %ARGS &>

Parameter Passing Examples

The following examples illustrate the different ways to pass and receive parameters.

1. Passing a scalar id with value 5.

  In a URL: /my/URL?id=5
  In a component call: <& /my/comp, id => 5 &>
  In the called component, if there is a declared argument named...
    $id, then $id will equal 5
    @id, then @id will equal (5)
    %id, then an error occurs
  In addition, $ARGS{id} will equal 5.

2. Passing a list colors with values red, blue, and green.

  In a URL: /my/URL?colors=red&colors=blue&colors=green
  In an component call: <& /my/comp, colors => ['red', 'blue', 'green'] &>
  In the called component, if there is a declared argument named...
    $colors, then $colors will equal ['red', 'blue', 'green']
    @colors, then @colors will equal ('red', 'blue', 'green')
    %colors, then an error occurs
  In addition, $ARGS{colors} will equal ['red', 'blue', 'green'].

3. Passing a hash grades with pairs Alice => 92 and Bob => 87.

  In a URL: /my/URL?grades=Alice&grades=92&grades=Bob&grades=87
  In an component call: <& /my/comp, grades => {Alice => 92, Bob => 87} &>
  In the called component, if there is a declared argument named...
    @grades, then @grades will equal ('Alice', 92, 'Bob', 87)
    %grades, then %grades will equal (Alice => 92, Bob => 87)
  In addition, $grade and $ARGS{grades} will equal
    ['Alice',92,'Bob',87] in the URL case, or {Alice => 92, Bob => 87}
    in the component call case.  (The discrepancy exists because, in a
    query string, there is no detectable difference between a list or
    hash.)

Using @_ instead

If you don't like named parameters, you can pass a traditional list of ordered parameters:

    <& /mktg/prods.html', 'dog', [2, 3, 4], {a => 7, b => 8} &>

and access them as usual through Perl's @_ array:

    my ($scalar, $listref, $hashref) = @_;

In this case no <%args> section is necessary.

We generally recommend named parameters for the benefits of readability, syntax checking, and default value automation. However using @_ may be convenient for very small components, especially subcomponents created with <%def>.

Before Mason 1.21, @_ contained copies of the caller's arguments. In Mason 1.21 and beyond, this unnecessary copying was eliminated and @_ now contains aliases to the caller's arguments, just as with regular Perl subroutines. For example, if a component updates $_[0], the corresponding argument is updated (or an error occurs if it is not updatable).

Most users won't notice this change because <%args> variables and the %ARGS hash always contain copies of arguments.

See perlsub for more information on @_ aliasing.

INITIALIZATION AND CLEANUP

The following sections contain blocks of Perl to execute at specific times.

<%init>

This section contains initialization code that executes as soon as the component is called. For example: checking that a user is logged in; selecting rows from a database into a list; parsing the contents of a file into a data structure.

Technically an <%init> block is equivalent to a <%perl> block at the beginning of the component. However, there is an aesthetic advantage of placing this block at the end of the component rather than the beginning.

We've found that the most readable components (especially for non-programmers) contain HTML in one continuous block at the top, with simple substitutions for dynamic elements but no distracting blocks of Perl code. At the bottom an <%init> block sets up the substitution variables. This organization allows non-programmers to work with the HTML without getting distracted or discouraged by Perl code. For example:

    <html>
    <head><title><% $headline %></title></head>
    <body>
    <h2><% $headline %></h2>
    By <% $author %>, <% $date %><p>
    <% $body %>
    </body></html>
    <%init>
    # Fetch article from database
    my $dbh = DBI::connect ...;
    my $sth = $dbh->prepare("select * from articles where id = ?");
    $sth->execute($article_id);
    my ($headline, $date, $author, $body) = $sth->fetchrow_array;
    # Massage the fields
    $headline = uc($headline);
    my ($year, $month, $day) = split('-', $date);
    $date = "$month/$day";
    </%init>

    <%args>
    $article_id
    </%args>

<%cleanup>

This section contains cleanup code that executes just before the component exits. For example: closing a database connection or closing a file handle.

Technically a << <%cleanup> >> block is equivalent to a <%perl> block at the end of the component. Since a component corresponds a subroutine block, and since Perl is so darned good at cleaning up stuff at the end of blocks, <%cleanup> sections are rarely needed.

The <%cleanup> block is not executed if the component returns (via an explicit return statement) or if an error or abort occurs in this component or one of its children. This makes <%cleanup> useless for real cleanup code that needs a guarantee of execution. We hope to remedy this in the next major release.

<%once>

This code executes once when the component is loaded. Variables declared in this section can be seen in all of a component's code and persist for the lifetime of the component.

This section is useful for declaring persistent component-scoped lexical variables (especially objects that are expensive to create), declaring subroutines (both named and anonymous), and initializing state.

This code does not run inside a request context. You cannot call components or access $m or $r from this section. Also, do not attempt to return() from a <%once> section; the current compiler cannot properly handle it.

Normally this code will execute individually from every HTTP child that uses the component. However, if the component is preloaded, this code will only execute once in the parent. Unless you have total control over what components will be preloaded, it is safest to avoid initializing variables that can't survive a fork(), e.g. DBI handles. Use code like this to initialize such variables in the <%init> section:

    <%once>
    my $dbh;      # declare but don't assign
    ...
    </%once>

    <%init>
    $dbh ||= DBI::connect ...
    ...
    </%init>

In addition, using $m or <$r> in this section will not work in a preloaded component, because neither of those variable exist when a component is preloaded.

<%shared>

As with <%once>, lexical (my) variables declared in this section can be seen in all the rest of a component's code: the main body, subcomponents, and methods. However, unlike <%once>, the code runs once per request (whenever the component is used) and its variables last only until the end of the request.

A <%shared> section is useful for initializing variables needed in, say, the main body and one more subcomponents or methods. See Object-Oriented Techniques for an example of usage.

It's important to realize that you do not have access to the %ARGS hash or variables created via an <%args> block inside a shared section. However, you can access arguments via $m->request_args.

Additionally, you cannot call a components' own methods or subcomponents from inside a <%shared>, though you can call other components.

Avoid using <%shared> for side-effect code that needs to run at a predictable time during page generation. You may assume only that <%shared> runs just before the first code that needs it and runs at most once per request.

In the current implementation, the scope sharing is done with closures, so variables will only be shared if they are visible at compile-time in the other parts of the component. In addition, you can't rely on the specific destruction time of the shared variables, because they may not be destroyed until the first time the < <%shared >> section executes in a future request. <%init> offers a more predictable execution and destruction time.

Currently any component with a <%shared> section incurs an extra performance penalty, because Mason must recreate its anonymous subroutines the first time each new request uses the component. The exact penalty varies between systems and for most applications will be unnoticeable. However, one should avoid using <%shared> when patently unnecessary, e.g. when an <%init> would work just as well.

Do not attempt to return() from a <%shared> section; the current compiler cannot properly handle it.

EMBEDDED COMPONENTS

<%def name>

Each instance of this section creates a subcomponent embedded inside the current component. Inside you may place anything that a regular component contains, with the exception of <%def>, <%method>, <%once>, and <%shared> tags.

The name consists of characters in the set [\w._-]. To call a subcomponent simply use its name in <& &> or $m->comp. A subcomponent can only be seen from the surrounding component.

If you define a subcomponent with the same name as a file-based component in the current directory, the subcomponent takes precedence. You would need to use an absolute path to call the file-based component. To avoid this situation and for general clarity, we recommend that you pick a unique way to name all of your subcomponents that is unlikely to interfere with file-based components. A commonly accepted practice is to start subcomponent names with ".".

While inside a subcomponent, you may use absolute or relative paths to call file-based components and also call any of your "sibling" subcomponents.

The lexical scope of a subcomponent is separate from the main component. However a subcomponent can declare its own <%args> section and have relevant values passed in. You can also use a <%shared> section to declare variables visible from both scopes.

In the following example, we create a ".link" subcomponent to produce a standardized hyperlink:

    <%def .link>
    <font size="4" face="Verdana,Arial,Helvetica">
    <a href="http://www.<% $site %>.com"><% $label %></a>
    </font><br>
    <%args>
    $site
    $label=>ucfirst($site)
    </%args>
    </%def>
    Visit these sites:
    <ul>
    <li><& .link, site=>'yahoo' &><br>
    <li><& .link, site=>'cmp', label=>'CMP Media' &><br>
    <li><& .link, site=>'excite' &>
    </ul>

<%method name>

Each instance of this section creates a method embedded inside the current component. Methods resemble subcomponents in terms of naming, contents, and scope. However, while subcomponents can only be seen from the parent component, methods are meant to be called from other components.

There are two ways to call a method. First, via a path of the form "comp:method":

    <& /foo/bar:method1 &>
    $m->comp('/foo/bar:method1');

Second, via the call_method component method:

    my $comp = $m->fetch_comp('/foo/bar');
    ...
    $comp->call_method('method1');

Methods are commonly used in conjunction with autohandlers to make templates more flexible. See Object-Oriented Techniques for more information.

You cannot create a subcomponent and method with the same name. This is mostly to prevent obfuscation and accidental errors.

FLAGS AND ATTRIBUTES

The <%flags> and <%attr> sections consist of key/value pairs, one per line, joined by '=>'. In each pair, the key must be any valid Perl "bareword identifier" (made of letters, numbers, and the underscore character), and the value may be any scalar value, including references. An optional comment may follow each line.

<%flags>

Use this section to set official Mason flags that affect the current component's behavior.

Currently there is only one flag, inherit, which specifies the component's parent in the form of a relative or absolute component path. A component inherits methods and attributes from its parent; see Object-Oriented Techniques for examples.

    <%flags>
    inherit=>'/site_handler'
    </%flags>

<%attr>

Use this section to assign static key/value attributes that can be queried from other components.

    <%attr>
    color => 'blue'
    fonts => [qw(arial geneva helvetica)]
    </%attr>

To query an attribute of a component, use the attr method:

    my $color = $comp->attr('color')

where $comp is a component object.

Mason evaluates attribute values once when loading the component. This makes them faster but less flexible than methods.

FILTERING

This section describes several ways to apply filtering functions over the results of the current component. By separating out and hiding a filter that, say, changes HTML in a complex way, we allow non-programmers to work in a cleaner HTML environment.

<%filter> section

The <%filter> section allows you to arbitrarily filter the output of the current component. Upon entry to this code, $_ contains the component output, and you are expected to modify it in place. The code has access to component arguments and can invoke subroutines, call other components, etc.

This simple filter converts the component output to UPPERCASE:

    <%filter>
    tr/a-z/A-Z/
    </%filter>

The following navigation bar uses a filter to "unlink" and highlight the item corresponding to the current page:

    <a href="/">Home</a> | <a href="/products/">Products</a> |
    <a href="/bg.html">Background</a> | <a href="/finance/">Financials</a> |
    <a href="/support/">Tech Support</a> | <a href="/contact.html">Contact Us</a>
    <%filter>
    my $uri = $r->uri;
    s{<a href="$uri/?">(.*?)</a>} {<b>$1</b>}i;
    </%filter>

This allows a designer to code such a navigation bar intuitively without if statements surrounding each link! Note that the regular expression need not be very robust as long as you have control over what will appear in the body.

A filter block does not have access to variables declared in a component's <%init> section, though variables declared in the <%args>, <%once> or <%shared> blocks are usable in a filter.

It should be noted that a filter cannot rely on receiving all of a component's output at once, and so may be called multiple times with different chunks of output. This can happen if autoflush is on, or if a filter-containing component, or the components it calls, call the $m->flush_buffer() method.

You should never call Perl's return() function inside a filter section, or you will not see any output at all.

You can use Component Calls with Content if you want to filter specific parts of a component rather than the entire component.

OTHER SYNTAX

<%doc>

Text in this section is treated as a comment and ignored. Most useful for a component's main documentation. One can easily write a program to sift through a set of components and pull out their <%doc> blocks to form a reference page.

Can also be used for in-line comments, though it is an admittedly cumbersome comment marker. Another option is '%#':

    %# this is a comment

These comments differ from HTML comments in that they do not appear in the HTML.

<%text>

Text in this section is passed through unmodified by Mason. Any Mason syntax inside it is ignored. This is useful, for example, when documenting Mason itself from a component:

    <%text>
    % This is an example of a Perl line.
    <% This is an example of an expression block. %>
    </%text>

This works for almost everything, but doesn't let you output </%text> itself! When all else fails, use $m->print:

    % $m->print('The tags are <%text> and </%text>.');

Escaping expressions

Mason has facilities for escaping the output from <% %> tags, on either a site-wide or a per-expression basis.

Any <% %> expression may be terminated by a '|' and one or more escape flags (plus arbitrary whitespace), separated by commas:

    <% $file_data |h %>

The current valid flags are:

  • h

    Escape HTML ('<' => '&lt;', etc.) using HTML::Entities::encode(). Before Perl 5.8.0 this module assumes that text is in the ISO-8859-1 character set; see the next section for how to override this escaping. After 5.8.0, the encoding assumes that text is in Unicode.

  • u

    Escape a URL query string (':' => '%3A', etc.) - all but [a-zA-Z0-9_.-]

  • n

    This is a special flag indicating that the default escape flags should not be used for this substitution.

The administrator may specify a set of default escape flags via the default_escape_flags parameter. For example, if the administrator sets default_escape_flags to ['h'], then all <% %> expressions will automatically be HTML-escaped. In this case you would use the n flag to turn off HTML-escaping for a specific expression:

    <% $html_block |n %>

Multiple escapes can be specified as a comma-separated list:

    <% $uri | u, n %>

The old pre-defined escapes, 'h', 'u', and 'n', can be used without commas, so that this is legal:

    <% $uri | un %>

However, this only works for these three escapes, and no others. If you are using user-defined escapes as well, you must use a comma:

    <% $uri | u, add_session %>

User-defined Escapes

Besides the default escapes mentioned above, it is possible for the user to define their own escapes or to override the built-in 'h' and 'u' escapes.

This is done via the Interp object's escape_flags parameter or set_escape() method. Escape names may be any number of characters as long as it matches the regex /^[\w-]+$/. The one exception is that you cannot override the 'n' flag.

Each escape flag is associated with a subroutine reference. The subroutine should expect to receive a scalar reference, which should be manipulated in place. Any return value from this subroutine is ignored.

Escapes can be defined at any time but using an escape that is not defined will cause an error when executing that component.

A common use for this feature is to override the built-in HTML escaping, which will not work with non-ISO-8559-1 encodings. If you are using such an encoding and want to switch the 'h' flag to do escape just the minimal set of characters (<, >, &, "), put this in your Apache configuration:

   PerlSetVar  MasonEscapeFlags  "h => \&HTML::Mason::Escapes::basic_html_escape"

Or, in a top-level autohandler:

    $m->interp->set_escape( h => \&HTML::Mason::Escapes::basic_html_escape );

Or you could write your own escape function for a particular encoding:

    $ah->interp->set_escape( h => \&my_html_escape );

And of course this can be used for all sorts of other things, like a naughty words filter for the easily offended:

    $interp->set_escape( 'no-naughty' => \&remove_naughty_words );

Manually applying escapes

You can manually apply one or more escapes to text using the Interp object's apply_escapes() method. e.g.

    $m->interp->apply_escapes( 'some html content', 'h' );

Backslash at end of line

A backslash (\) at the end of a line suppresses the newline. In HTML components, this is mostly useful for fixed width areas like <pre> tags, since browsers ignore white space for the most part. An example:

    <pre>
    foo
    % if (1) {
    bar
    % }
    baz
    </pre>

outputs

    foo
    bar
    baz

because of the newlines on lines 2 and 4. (Lines 3 and 5 do not generate a newline because the entire line is taken by Perl.) To suppress the newlines:

    <pre>
    foo\
    % if (1) {
    bar\
    % }
    baz
    </pre>

which prints

    foobarbaz

DATA CACHING

Mason's data caching interface allows components to cache the results of computation for improved performance. Anything may be cached, from a block of HTML to a complex data structure.

Each component gets its own private, persistent data cache. Except under special circumstances, one component does not access another component's cache. Each cached value may be set to expire at a certain time.

Data caching is implemented on top of DeWitt Clinton's Cache::Cache package. Mason implements its own extended subclass of Dewitt's module called HTML::Mason::Cache::BaseCache. See that module's documentation for a companion API reference to this section.

Basic Usage

The $m->cache method returns an object representing the cache for this component. Here's the typical usage of $m->cache:

    my $result = $m->cache->get('key');
    if (!defined($result)) {
        ... compute $result ...
        $m->cache->set('key', $result);
    }

$m->cache->get attempts to retrieve this component's cache value. If the value is available it is placed in $result. If the value is not available, $result is computed and stored in the cache by $m->cache->set.

Multiple Keys/Values

A cache can store multiple key/value pairs. A value can be anything serializable by Storable, from a simple scalar to an arbitrary complex list or hash reference:

    $m->cache->set(name => $string);
    $m->cache->set(friends => \@list);
    $m->cache->set(map => \%hash);

You can fetch all the keys in a cache with

    my @idents = $m->cache->get_keys;

It should be noted that Mason reserves all keys beginning with __mason for its own use.

Expiration

You can pass an optional third argument to $m->cache->set indicating when the item should expire:

    $m->cache->set('name1', $string1, '5 min');  # Expire in 5 minutes
    $m->cache->set('name2', $string2, '3h');     # Expire in 3 hours

To change the expiration time for a piece of data, call set again with the new expiration. To expire an item immediately, use $m->cache->remove.

You can also specify an expiration condition when you fetch the item, using the expire_if option:

    my $result = $m->cache->get('key',
        expire_if=>sub { $_[0]->get_created_at < (stat($file))[9] });

expire_if takes an anonymous subroutine, which is called with the cache object as its only parameter. If the subroutine returns a true value, the item is expired. In the example above, we expire the item whenever a certain file changes.

Finally, you can expire a cache item from an external script; see Accessing a Cache Externally below.

Avoiding Concurrent Recomputation with Busy Locks

The code shown in "Basic Usage" above,

   my $result = $m->cache->get('key');
   if (!defined($result)) {
       ... compute $result ...
       $m->cache->set('key', $result);
   }

can suffer from a kind of race condition for caches that are accessed frequently and take a long time to recompute.

Suppose that a particular cache value is accessed five times a second and takes three seconds to recompute. When the cache expires, the first process comes in, sees that it is expired, and starts to recompute the value. The second process comes in and does the same thing. This sequence continues until the first process finishes and stores the new value. On average, the value will be recomputed and written to the cache 15 times!

Mason offers a solution with the busy_lock flag:

   my $result = $m->cache->get('key', busy_lock=>'30 sec');

In this case, when the value cannot be retrieved, get() sets the expiration time of the value 30 seconds in the future before returning undef. This tells the first process to compute the new value while causing subsequent processes to use the old value for 30 seconds.

Should the 30 seconds expire before the first process is done, a second process will start computing the new value while setting the expiration time yet another 30 seconds in the future, and so on.

Caching All Output

Occasionally you will need to cache the complete output of a component. For this purpose, Mason offers the $m->cache_self method. This method causes Mason to check to see if this component has already been run and its output cached. If this is the case, this output is simply sent as output. Otherwise, the component run normally and its output and return value cached.

It is typically used right at the top of an <%init> section:

    <%init>
    return if $m->cache_self([key => 'fookey', expires_in => '3 hours',
                             ... <other cache options> ... ]);
     ... <rest of init> ...
    </%init>

A full list of parameters and examples are available in the cache_self section of the Request manual.

Cache Object

$m->cache->get_object returns the Cache::Object associated with a particular key. You can use this to retrieve useful meta-data:

    my $co = $m->cache->get_object('name1');
    $co->get_created_at();    # when was object stored in cache
    $co->get_accessed_at();   # when was object last accessed
    $co->get_expires_at();    # when does object expire

Choosing a Cache Subclass

The cache API is implemented by a variety of backend subclasses. For example, FileCache implements the interface with a set of directories and files, MemoryCache implements the interface in process memory, and SharedMemoryCache implements the interface in shared memory. See the Cache::Cache package for a full list of backend subclasses.

By default $m->cache uses FileCache, but you can override this with the cache_class keyword. The value must be the name of a Cache::Cache subclass; the prefix "Cache::" need not be included. For example:

    my $result = $m->cache(cache_class => 'MemoryCache')->get('key');
    $m->cache(cache_class => 'MemoryCache')->set(key => $result);

You can even specify different subclasses for different keys in the same component. Just make sure the correct value is passed to all calls to $m->cache; Mason does not remember which subclass you have used for a given component or key.

The administrator can set the default cache subclass used by all components with the data_cache_defaults parameter.

Accessing a Cache Externally

To access a component's cache from outside the component (e.g. in an external Perl script), you'll need have the following information:

  • the namespace associated with the component. The function HTML::Mason::Utils::data_cache_namespace, given a component id (usually just the component path), returns the namespace.

  • the cache_root, for file-based caches only. Defaults to the "cache" subdirectory under the Mason data directory.

Given this information you can get a handle on the component's cache. For example, the following code removes a cache item for component /foo/bar, assuming the data directory is /usr/local/www/mason and the cache subclass is FileCache:

    use HTML::Mason::Utils qw(data_cache_namespace);

    my $cache = new Cache::FileCache
        ( { namespace => data_cache_namespace("/foo/bar"),
            cache_root => "/usr/local/www/mason/cache" } );

    # Remove one key
    $cache->remove('key1');

    # Remove all keys
    $cache->clear;

Mason 1.0x Cache API

For users upgrading from 1.0x and earlier, any existing $m->cache code will be incompatible with the new API. However, if you wish to continue using the 1.0x cache API for a while, you (or your administrator) can set data_cache_api to '1.0'. All of the $m->cache options with the exception of tie_class should be supported.

The access_data_cache function is no longer available; this will need to be converted to use Cache::Cache directly, as described in the previous section.

WEB-SPECIFIC FEATURES

Sending HTTP Headers

Mason automatically sends HTTP headers via $r->send_http_header but it will not send headers if they've already been sent manually.

To determine the exact header behavior on your system, you need to know whether your server's default is to have autoflush on or off. Your administrator should have this information. If your administrator doesn't know then it is probably off, the default.

With autoflush off the header situation is extremely simple: Mason waits until the very end of the request to send headers. Any component can modify or augment the headers.

With autoflush on the header situation is more complex. Mason will send headers just before sending the first output. This means that if you want to affect the headers with autoflush on, you must do so before any component sends any output. Generally this takes place in an <%init> section.

For example, the following top-level component calls another component to see whether the user has a cookie; if not, it inserts a new cookie into the header.

    <%init>
    my $cookie = $m->comp('/shared/get_user_cookie');
    if (!$cookie) {
        $cookie = new CGI::Cookie (...);
        $r->header_out('Set-cookie' => $cookie);
    }
    ...
    </%init>

With autoflush off this code will always work. Turn autoflush on and this code will only work as long as /shared/get_user_cookie doesn't output anything (given its functional nature, it shouldn't).

The administrator can turn off automatic header sending via the auto_send_headers parameter.

Returning HTTP Status

The value returned from the top-most component becomes the status code of the request. If no value is explicitly returned, it defaults to OK (0).

Simply returning an error status (such as 404) from the top-most component has two problems in practice. First, the decision to return an error status often resides further down in the component stack. Second, you may have generated some content by the time this decision is made. (Both of these are more likely to be true when using autohandlers.)

Thus the safer way to generate an error status is

   $m->clear_buffer;
   $m->abort($status);

$m->abort bypasses the component stack and ensures that $status is returned from the top-most component. It works by throwing an exception. If you wrapped this code (directly or indirectly) in an eval, you must take care to rethrow the exception, or the status will not make it out:

   eval { $m->comp('...') };
   if (my $err = $@) {
      if ($m->aborted) {
          die $err;
      } else {
          # deal with non-abort exceptions
      }
   }

Filters and $m->abort

A filter section will still be called after a component aborts with $m->abort. You can always check $m->aborted in your <%filter> block if you don't want to run the filter after an abort.

  <%filter>
  unless ( $m->aborted ) {
      $_ .= ' filter stuff';
  }
  </%filter>

External Redirects

Because it is so commonly needed, Mason 1.1x and on provides an external redirect method:

    $m->redirect($url);    # Redirects with 302 status

This method uses the clear_buffer/abort technique mentioned above, so the same warnings apply regarding evals.

Also, if you generate any output after calling $m->redirect, then this output will be sent, and will break the redirect. For example:

  % eval { $m->comp('redirect', ...) };

  % die $@ if $@;

The blank line between the two Perl lines is new output generated after the redirect. Either remove it or call $m->clear_buffer immediately before calling die().

Internal Redirects

There are two ways to perform redirects that are invisible to the client.

First, you can use a Mason subrequest (see Subrequests). This only works if you are redirecting to another Mason page.

Second, you can use Apache's internal_redirect method, which works whether or not the new URL will be handled by Mason. Use it this way:

    $r->internal_redirect($url);
    $m->auto_send_headers(0);
    $m->clear_buffer;
    $m->abort;

The last three lines prevent the original request from accidentally generating extra headers or content.

USING THE PERL DEBUGGER

You can use the perl debugger in conjunction with a live mod_perl/Mason server with the help of Apache::DB, available from CPAN. Refer to the Apache::DB documentation for details.

The only tricky thing about debugging Mason pages is that components are implemented by anonymous subroutines, which are not easily breakpoint'able. To remedy this, Mason calls the dummy subroutine debug_hook at the beginning of each component. You can breakpoint this subroutine like so:

    b HTML::Mason::Request::debug_hook

debug_hook is called with two parameters: the current Request object and the full component path. Thus you can breakpoint specific components using a conditional on $_[1]:

    b HTML::Mason::Request::debug_hook $_[1] =~ /component name/

You can avoid all that typing by adding the following to your ~/.perldb file:

    # Perl debugger aliases for Mason
    $DB::alias{mb} = 's/^mb\b/b HTML::Mason::Request::debug_hook/';

which reduces the previous examples to just:

    mb
    mb $_[1] =~ /component name/

Mason normally inserts '#line' directives into compiled components so that line numbers are reported relative to the source file. Depending on your task, this can be a help or a hindrance when using the debugger. The administrator can turn off '#line' directives with the use_source_line_numbers parameter.

OBJECT-ORIENTED TECHNIQUES

Earlier you learned how to assign a common template to an entire hierarchy of pages using autohandlers. The basic template looks like:

    header HTML
    % $m->call_next;
    footer HTML

However, sometimes you'll want a more flexible template that adjusts to the requested page. You might want to allow each page or subsection to specify a title, background color, or logo image while leaving the rest of the template intact. You might want some pages or subsections to use a different template, or to ignore templates entirely.

These issues can be addressed with the object-oriented style primitives introduced in Mason 0.85.

Note: we use the term object-oriented loosely. Mason borrows concepts like inheritance, methods, and attributes from object methodology but implements them in a shallow way to solve a particular set of problems. Future redesigns may incorporate a deeper object architecture if the current prototype proves successful.

Determining inheritance

Every component may have a single parent. The default parent is a component named autohandler in the closest parent directory. This rule applies to autohandlers too: an autohandler may not have itself as a parent but may have an autohandler further up the tree as its parent.

You can use the inherit flag to override a component's parent:

    <%flags>
    inherit => '/foo/bar'
    </%flags>

If you specify undef as the parent, then the component inherits from no one. This is how to suppress templates.

Currently there is no way to specify a parent dynamically at run-time, or to specify multiple parents.

Content wrapping

At page execution time, Mason builds a chain of components from the called component, its parent, its parent's parent, and so on. Execution begins with the top-most component; calling $m->call_next passes control to the next component in the chain. This is the familiar autohandler "wrapping" behavior, generalized for any number of arbitrarily named templates.

Accessing methods and attributes

A template can access methods and/or attributes of the requested page. First, use $m->request_comp to get a handle on the appropriate component:

    my $self = $m->request_comp;

$self now refers to the component corresponding to the requested page (the component at the end of the chain).

To access a method for the page, use call_method:

    $self->call_method('header');

This looks for a method named 'header' in the page component. If no such method exists, the chain of parents is searched upwards, until ultimately a "method not found" error occurs. Use 'method_exists' to avoid this error for questionable method calls:

    if ($self->method_exists('header')) { ...

The component returned by the $m->request_comp method never changes during request execution. In contrast, the component returned by $m->base_comp may change several times during request execution.

When execution starts, the base component is the same as the requested component. Whenever a component call is executed, the base component may become the component that was called. The base component will change for all component calls except in the following cases:

  • A component is called via its component object rather than its path, for example:

      <& $m->fetch_comp('/some/comp'), foo => 1 &>

  • A method is called via the use of SELF:, PARENT:, or REQUEST:. These are covered in more detail below.

In all other cases, the base component is the called component or the called component's owner component if that called component is a method.

As hinted at above, Mason provides a shortcut syntax for method calls.

If a component call path starts with SELF:, then Mason will start looking for the method (the portion of the call after SELF:), in the base component.

    <& SELF:header &>
    $m->comp('SELF:header')

If the call path starts with PARENT:, then Mason will start looking in the current component's parent for the named method.

    <& PARENT:header &>
    $m->comp('PARENT:header')

In the context of a component path, PARENT is shorthand for $m->current_comp->parent.

If the call path begins with REQUEST:, then Mason looks for the method in the requested component. REQUEST is shorthand for < $m-request_comp >>.

The rules for attributes are similar. To access an attribute for the page, use attr:

    my $color = $self->attr('color')

This looks for an attribute named 'color' in the $self component. If no such attribute exists, the chain of parents is searched upwards, until ultimately an "attribute not found" error occurs. Use attr_exists or attr_if_exist to avoid this error for questionable attributes:

    if ($self->attr_exists('color')) { ...

    my $color = $self->attr_if_exists('color'); # if it doesn't exist $color is undef

Sharing data

A component's main body and its methods occupy separate lexical scopes. Variables declared, say, in the <%init> section of the main component cannot be seen from methods.

To share variables, declare them either in the <%once> or <%shared> section. Both sections have an all-inclusive scope. The <%once> section runs once when the component loads; its variables are persistent for the lifetime of the component. The <%shared> section runs once per request (when needed), just before any code in the component runs; its variables last only til the end of the request.

In the following example, various sections of code require information about the logged-in user. We use a <%shared> section to fetch these in a single request.

    <%attr>
    title=>sub { "Account for $full_name" }
    </%attr>

    <%method lefttoc>
    <i><% $full_name %></i>
    (<a href="logout.html">Log out</a>)<br>
    ...
    </%method>
    Welcome, <% $fname %>. Here are your options:
    <%shared>
    my $dbh = DBI::connect ...;
    my $user = $r->connection->user;
    my $sth = $dbh->prepare("select lname,fname, from users where user_id = ?");
    $sth->execute($user);
    my ($lname, $fname) = $sth->fetchrow_array;
    my $full_name = "$first $last";
    </%shared>

<%shared> presents a good alternative to <%init> when data is needed across multiple scopes. Outside these situations, <%init> is preferred for its slightly greater speed and predictable execution model.

Example

Let's say we have three components:

    /autohandler
    /products/autohandler
    /products/index.html

and that a request comes in for /products/index.html.

/autohandler contains a general template for the site, referring to a number of standard methods and attributes for each page:

    <head>
    <title><& SELF:title &></title>
    </head>
    <body bgcolor="<% $self->attr('bgcolor') %>">
    <& SELF:header &>
    <table><tr><td>
    % $m->call_next;

    </td></tr></table>
    <& SELF:footer &>
    </body>
    <%init>
    my $self = $m->base_comp;
    ...
    </%init>

    <%attr>
    bgcolor => 'white'
    </%attr>
    <%method title>
    McGuffey Inc.
    </%method>
    <%method header>
    <h2><& SELF:title &></h2><p>
    </%method>
    <%method footer>
    </%method>

Notice how we provide defaults for each method and attribute, even if blank.

/products/autohandler overrides some attributes and methods for the /products section of the site.

    <%attr>
    bgcolor => 'beige'
    </%attr>
    <%method title>
    McGuffey Inc.: Products
    </%method>
    % $m->call_next;

Note that this component, though it only defines attributes and methods, must call $m->call_next if it wants the rest of the chain to run.

/products/index.html might override a few attributes, but mainly provides a primary section for the body.

COMMON TRAPS

Do not call $r->content or "new CGI"

Mason calls $r->content itself to read request input, emptying the input buffer and leaving a trap for the unwary: subsequent calls to $r->content hang the server. This is a mod_perl "feature" that may be fixed in an upcoming release.

For the same reason you should not create a CGI object like

  my $query = new CGI;

when handling a POST; the CGI module will try to reread request input and hang. Instead, create an empty object:

  my $query = new CGI ("");

such an object can still be used for all of CGI's useful HTML output functions. Or, if you really want to use CGI's input functions, initialize the object from %ARGS:

  my $query = new CGI (\%ARGS);

MASON AND SOURCE FILTERS

Modules which work as source filters, such as Switch.pm, will only work when you are using object files. This is because of how source filters are implemented, and cannot be changed by the Mason authors.

AUTHORS

Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken Williams <ken@mathforum.org>

SEE ALSO

HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::Request


HTML::Mason::Escapes - Functions to escape text for Mason

NAME

HTML::Mason::Escapes - Functions to escape text for Mason

DESCRIPTION

This module contains functions for implementing Mason's substitution escaping feature. These functions may also be called directly.

html_entities_escape

This function takes a scalar reference and HTML-escapes it using the HTML::Entities module. By default, this module assumes that the string it is escaping is in ISO-8859-1 (pre Perl 5.8.0) or UTF-8 (Perl 5.8.0 onwards). If this is not the case for your data, you will want to override this escape to do the right thing for your encoding. See the section on User-defined Escapes in the Developer's Manual for more details on how to do this.

url_escape

This takes a scalar reference and replaces any text it contains matching [^a-zA-Z0-9_.-] with the URL-escaped equivalent, a percent sign (%) followed by the hexadecimal number of that character.

basic_html_escape

This function takes a scalar reference and HTML-escapes it, escaping the following characters: '&', '>', '<', and '"'.

It is provided for those who wish to use it to replace (or supplement) the existing 'h' escape flag, via the Interpreter's set_escape() method.

This function is provided in order to allow people to return the HTML escaping behavior in 1.0x. However, this behavior presents a potential security risk of allowing cross-site scripting attacks. HTML escaping should always be done based on the character set a page is in. Merely escaping the four characters mentioned above is not sufficient. The quick summary of why is that for some character sets, characters other than '<' may be interpreted as a "less than" sign, meaning that just filtering '<' and '>' will not stop all cross-site scripting attacks. See http://www.megasecurity.org/Info/cross-site_scripting.txt for more details.


HTML::Mason::Exceptions - Exception objects thrown by Mason

  • IMPORT
  • EXCEPTIONS
  • FIELDS
  • EXCEPTION METHODS
  • EXCEPTION CLASS CHECKING

NAME

HTML::Mason::Exceptions - Exception objects thrown by Mason

SYNOPSIS

  use HTML::Mason::Exceptions ( abbr => [ qw(system_error) ] );

  open FH, 'foo' or system_error "cannot open foo: $!";

DESCRIPTION

This module creates the hierarchy of exception objects used by Mason, and provides some extra methods for them beyond those provided by Exception::Class

IMPORT

When this module is imported, it is possible to specify a list of abbreviated function names that you want to use to throw exceptions. In the SYNOPSIS example, we use the system_error function to throw a HTML::Mason::Exception::System exception.

These abbreviated functions do not allow you to set additional fields in the exception, only the message.

EXCEPTIONS

HTML::Mason::Exception

This is the parent class for all exceptions thrown by Mason. Mason sometimes throws exceptions in this class when we could not find a better category for the message.

Abbreviated as error

HTML::Mason::Exception::Abort

The $m->abort method was called.

Exceptions in this class contain the field aborted_value.

HTML::Mason::Exception::Decline

The $m->decline method was called.

Exceptions in this class contain the field declined_value.

HTML::Mason::Exception::Compilation

An exception occurred when attempting to eval an existing object file.

Exceptions in this class have the field filename, which indicates what file contained the code that caused the error.

Abbreviated as compilation_error.

HTML::Mason::Exception::Compiler

The compiler threw an exception because it received incorrect input. For example, this would be thrown if the lexer told the compiler to initialize compilation while it was in the middle of compiling another component.

Abbreviated as compiler_error.

HTML::Mason::Exception::Compilation::IncompatibleCompiler

A component was compiled by a compiler or lexer with incompatible options. This is used to tell Mason to recompile a component.

Abbreviated as wrong_compiler_error.

HTML::Mason::Exception::Params

Invalid parameters were passed to a method or function.

Abbreviated as param_error.

HTML::Mason::Exception::Syntax

This exception indicates that a component contained invalid syntax.

Exceptions in this class have the fields source_line, which is the actual source where the error was found, comp_name, and line_number.

Abbreviated as syntax_error.

HTML::Mason::Exception::System

A system call of some sort, such as a file open, failed.

Abbreviated as system_error.

HTML::Mason::Exception::TopLevelNotFound

The requested top level component could not be found.

Abbreviated as top_level_not_found_error.

HTML::Mason::VirtualMethod

Some piece of code attempted to call a virtual method which was not overridden.

Abbreviated as virtual_error

FIELDS

Some of the exceptions mentioned above have additional fields, which are available via accessors. For example, to get the line number of an HTML::Mason::Exception::Syntax exception, you call the line_number method on the exception object.

EXCEPTION METHODS

All of the Mason exceptions implement the following methods:

as_brief

This simply returns the exception message, without any trace information.

as_line

This returns the exception message and its trace information, all on a single line with tabs between the message and each frame of the stack trace.

as_text

This returns the exception message and stack information, with each frame on a separate line.

as_html

This returns the exception message and stack as an HTML page.

Each of these methods corresponds to a valid error_format parameter for the Request object such as text or html.

You can create your own method in the HTML::Mason::Exception namespace, such as as_you_wish, in which case you could set this parameter to "you_wish". This method will receive a single argument, the exception object, and is expected to return some sort of string containing the formatted error message.

EXCEPTION CLASS CHECKING

This module also exports the isa_mason_exception function. This function takes the exception object and an optional string parameter indicating what subclass to check for.

So it can be called either as:

  if ( isa_mason_exception($@) ) { ... }

or

  if ( isa_mason_exception($@, 'Syntax') ) { ... }

Note that when specifying a subclass you should not include the leading "HTML::Mason::Exception::" portion of the class name.


HTML::Mason::FakeApache - An Apache object emulator for use with Mason

NAME

HTML::Mason::FakeApache - An Apache object emulator for use with Mason

SYNOPSIS

See HTML::Mason::CGIHandler.

DESCRIPTION

This class's API is documented in HTML::Mason::CGIHandler.


HTML::Mason::Interp - Mason Component Interpreter

  • PARAMETERS TO THE new() CONSTRUCTOR
  • ACCESSOR METHODS
  • ESCAPE FLAG METHODS
  • OTHER METHODS
  • MEMORY LEAK WARNING
  • SEE ALSO

NAME

HTML::Mason::Interp - Mason Component Interpreter

SYNOPSIS

    my $i = HTML::Mason::Interp->new (data_dir=>'/usr/local/mason',
                                     comp_root=>'/usr/local/www/htdocs/',
                                     ...other params...);

DESCRIPTION

Interp is the Mason workhorse, executing components and routing their output and errors to all the right places. In a mod_perl environment, Interp objects are handed off immediately to an ApacheHandler object which internally calls the Interp implementation methods. In that case the only user method is the new() constructor.

PARAMETERS TO THE new() CONSTRUCTOR

autohandler_name

File name used for autohandlers. Default is "autohandler". If this is set to an empty string ("") then autohandlers are turned off entirely.

code_cache_max_size

Specifies the maximum size, in bytes, of the in-memory code cache where components are stored. Default is 10 MB. See the code cache section of the administrator's manual for further details.

compiler

The Compiler object to associate with this Interpreter. By default a new object of class compiler_class will be created.

compiler_class

The class to use when creating a compiler. Defaults to HTML::Mason::Compiler.

current_time

Interpreter's notion of the current time (deprecated).

data_dir

The data directory is a writable directory that Mason uses for various features and optimizations: for example, component object files and data cache files. Mason will create the directory on startup, if necessary, and set its permissions according to the web server User/Group.

Under Apache, data_dir defaults to a directory called "mason" under the Apache server root. You will need to change this on certain systems that assign a high-level server root such as /usr!

In non-Apache environments, data_dir has no default. If it is left unspecified, Mason will not use object files, and the default data cache class will be MemoryCache instead of FileCache.

escape_flags

A hash reference of escape flags to set for this object. See the section on the set_escape method for more details.

ignore_warnings_expr

Regular expression indicating which warnings to ignore when loading components. Any warning that is not ignored will prevent the component from being loaded and executed. For example:

    ignore_warnings_expr =>
        'Global symbol.*requires explicit package'

If set to undef, all warnings are heeded. If set to '.', warnings are turned off completely as a specially optimized case.

By default, this is set to 'Subroutine .* redefined'. This allows you to declare global subroutines inside <%once> sections and not receive an error when the component is reloaded.

preloads

A list of component paths, optionally with glob wildcards, to load when the interpreter initializes. e.g.

    preloads => ['/foo/index.html','/bar/*.pl']

Default is the empty list. For maximum performance, this should only be used for components that are frequently viewed and rarely updated. See the preloading components section of the administrator's manual for further details.

As mentioned in the developer's manual, a component's <%once> section is executed when it is loaded. For preloaded components, this means that this section will be executed before a Mason or Apache request exist, so preloading a component that uses $m or $r in a <%once> section will fail.

request_class

The class to use when creating requests. Defaults to HTML::Mason::Request.

resolver

The Resolver object to associate with this Compiler. By default a new object of class resolver_class will be created.

resolver_class

The class to use when creating a resolver. Defaults to HTML::Mason::Resolver::File.

static_source

True or false, default is false. When false, Mason checks the timestamp of the component source file each time the component is used to see if it has changed. This provides the instant feedback for source changes that is expected for development. However it does entail a file stat for each component executed.

When true, Mason assumes that the component source tree is unchanging: it will not check component source files to determine if the memory cache or object file has expired. This can save many file stats per request. However, in order to get Mason to recognize a component source change, you must remove object files and restart the server (so as to clear the memory cache).

Use this feature for live sites where performance is crucial and where updates are infrequent and well-controlled.

use_object_files

True or false, default is true. Specifies whether Mason creates object files to save the results of component parsing. You may want to turn off object files for disk space reasons, but otherwise this should be left alone.

ACCESSOR METHODS

All of the above properties have standard accessor methods of the same name. In general, no arguments retrieves the value, and one argument sets and returns the value. For example:

    my $interp = HTML::Mason::Interp->new (...);
    my $c = $interp->compiler;
    $interp->code_cache_max_size(20 * 1024 * 1024);

The following properties can be queried but not modified: data_dir, preloads.

ESCAPE FLAG METHODS

apply_escapes ($text, $flags, [more flags...])

This method applies a one or more escapes to a piece of text. The escapes are specified by giving their flag. Each escape is applied to the text in turn, after which the now-modified text is returned.

remove_escape ($name)

Given an escape name, this removes that escape from the interpreter's known escapes. If the name is not recognized, it is simply ignored.

set_escape ($name => see below])

This method is called to add an escape flag to the list of known escapes for the interpreter. The flag may only consist of the characters matching \w and the dash (-). It must start with an alpha character or an underscore (_).

The right hand side may be one of several things. It can be a subroutine reference. It can also be a string match /^\w+$/, in which case it is assumed to be the name of a subroutine in the HTML::Mason::Escapes module. Finally, if it is a string that does not match the above regex, then it is assumed to be evalable code, which will return a subroutine reference.

When setting these with PerlSetVar directives in an Apache configuration file, you can set them like this:

  PerlSetVar  MasonEscapeFlags  "h => \&HTML::Mason::Escapes::basic_html_escape"
  PerlSetVar  MasonEscapeFlags  "flag  => \&subroutine"
  PerlSetVar  MasonEscapeFlags  "uc    => sub { ${$_[0]} = uc ${$_[0]}; }"
  PerlAddVar  MasonEscapeFlags  "thing => other_thing"

OTHER METHODS

comp_exists (path)

Given an absolute component path, this method returns a boolean value indicating whether or not a component exists for that path.

comp_root (comp_root)

This is a convenience method which simply calls the comp_root method in the resolver object, which by default is in the HTML::Mason::Resolver::File class.

Obviously, if you are using a custom resolver class which does not have a comp_root method, then this convenience method will not work.

exec (comp, args...)

Creates a new HTML::Mason::Request object for the given comp and args, and executes it. The return value is the return value of comp, if any.

This is useful for running Mason outside of a web environment. See using Mason from a standalone script in the HTML::Mason::Admin manpage for examples.

This method isn't generally useful in a mod_perl environment; see subrequests instead.

flush_code_cache

Empties the component cache. When using Perl 5.00503 or earlier, you should call this when finished with an interpreter, in order to remove circular references that would prevent the interpreter from being destroyed.

load (path)

Returns the component object corresponding to an absolute component path, or undef if none exists.

make_component (comp_source => ... )
make_component (comp_file => ... )

This method compiles Mason component source code and returns a Component object. The source may be passed in as a string in comp_source, or as a filename in comp_file. When using comp_file, the filename is specified as a path on the file system, not as a path relative to Mason's component root (see $m->fetch_comp for that).

If Mason encounters an error during processing, an exception will be thrown.

Example of usage:

    # Make an anonymous component
    my $anon_comp =
      eval { $interp->make_component
               ( comp_source => '<%perl>my $name = "World";</%perl>Hello <% $name %>!' ) };
    die $@ if $@;

    $m->comp($anon_comp);
make_request (@request_params)

This method creates a Mason request object. The arguments to be passed are the same as those for the HTML::Mason::Request->new constructor or its relevant subclass. This method will likely only be of interest to those attempting to write new handlers or to subclass HTML::Mason::Interp. If you want to create a subrequest, see subrequests instead.

purge_code_cache ()

Called during request execution in order to clear out the code cache. Mainly useful to subclasses that may want to take some custom action upon clearing the cache.

set_global ($varname, [values...])

This method sets a global to be used in components. varname is a variable name, optionally preceded with a prefix ($, @, or %); if the prefix is omitted then $ is assumed. varname is followed by a value, in the case of a scalar, or by one or more values in the case of a list or hash. For example:

    # Set a global variable $dbh containing the database handle
    $interp->set_global(dbh => DBI->connect(...));

    # Set a global hash %session from a local hash
    $interp->set_global('%session', %s);

The global is set in the package that components run in: usually HTML::Mason::Commands, although this can be overridden via the in_package parameter. The lines above, for example, are equivalent to:

    $HTML::Mason::Commands::dbh = DBI->connect(...);
    %HTML::Mason::Commands::session = %s;

assuming that in_package has not been changed.

Any global that you set should also be registered with the allow_globals parameter; otherwise you'll get warnings from strict.

MEMORY LEAK WARNING

When using Perl 5.00503 or earlier, using the code cache creates a circular reference between Interp and component objects. This means that Interp objects will not be destroyed unless you call flush_code_cache. If you are using Perl 5.6.0 or greater, and you have the XS version of Scalar::Util installed, Mason uses weak references to prevent this problem.

Win32 users should note that as of this writing, ActiveState's PPD for Scalar-List-Utils only includes the pure Perl version of these modules, which don't include the weak references functionality.

SEE ALSO

HTML::Mason,
HTML::Mason::Admin,
HTML::Mason::ApacheHandler


HTML::Mason::Lexer - Generates events based on component source lexing

  • METHODS
  • SUBCLASSING

NAME

HTML::Mason::Lexer - Generates events based on component source lexing

SYNOPSIS

  my $lexer = HTML::Mason::Lexer->new;

  $lexer->lex( comp_source => $source, name => $comp_name, compiler => $compiler );

DESCRIPTION

The Lexer works in tandem with the Compiler to turn Mason component source into something else, generally Perl code.

As the lexer finds component elements, like a tag or block, it calls the appropriate event methods in the compiler object it was given.

It has only a few public methods.

You can replace this lexer with one of your own simply by telling the Compiler to use a different lexer class. Your lexer class simply needs to call the appropriate methods in the Component Class's API as it scans the source.

METHODS

The lexer has very few public methods.

new

This method creates a new Lexer object. This methods takes no parameters.

lex ( comp_source => ..., name => ..., compiler => ... )

This method tells the lexer to start scanning the given component source. All of these parameters are required. The name parameter will be used in any error messages generated during lexing. The compiler object must be an object that implements the Mason Component API.

line_number

The current line number that the lexer has reached.

name

The name of the component currently being lexed.

throw_syntax_error ($error)

This throws an HTML::Mason::Exception::Syntax error with the given error message as well as additional information about the component source.

This method is used by both the Lexer and the Compiler.

SUBCLASSING

Any subclass of the lexer should declare itself to be a subclass of HTML::Mason::Lexer, even if it plans to override all of its public methods.

If you want your subclass to work with the existing Compiler classes in Mason, you must implement the methods listed above. If you plan to use a custom Compiler class that you're writing, you can do whatever you want.


HTML::Mason::MethodMaker - Used to create simple get & get/set methods in other classes

  • USAGE
  • SEE ALSO

NAME

HTML::Mason::MethodMaker - Used to create simple get & get/set methods in other classes

SYNOPSIS

 use HTML::Mason::MethodMaker
     ( read_only => 'foo',
       read_write => [
                      [ bar => { type => SCALAR } ],
                      [ baz => { isa => 'HTML::Mason::Baz' } ],
                      'quux', # no validation
                     ],
       read_write_contained => { other_object =>
                                 [
                                  [ 'thing1' => { isa => 'Thing1' } ],
                                  'thing2', # no validation
                                 ]
                               },
     );

DESCRIPTION

This automates the creation of simple accessor methods.

USAGE

This module creates methods when it is use'd by another module. There are three types of methods: 'read_only', 'read_write', 'read_write_contained'.

Attributes specified as 'read_only' get an accessor that only returns the value of the attribute. Presumably, these attributes are set via more complicated methods in the class or as a side effect of one of its methods.

Attributes specified as 'read_write' will take a single optional parameter. If given, this parameter will become the new value of the attribute. This value is then returned from the method. If no parameter is given, then the current value is returned.

If you want the accessor to use Params::Validate to validate any values passed to the accessor (and you _do_), then the the accessor specification should be an array reference containing two elements. The first element is the accessor name and the second is the validation spec.

The 'read_write_contained' parameter is used to create accessor for delayed contained objects. A delayed contained object is one that is not created in the containing object's accessor, but rather at some point after the containing object is constructed. For example, the Interpreter object creates Request objects after the Interpreter itself has been created.

The value of the 'read_write_contained' parameter should be a hash reference. The keys are the internal name of the contained object, such as "request" or "buffer". The values for the keys are the same as the parameters given for 'read_write' accessors.

SEE ALSO

HTML::Mason


HTML::Mason::Params - Mason configuration parameters

  • PERL AND APACHE NAMES
    • Where Apache Names Are Used
    • Where Perl Names Are Used
  • PARAMETERS
    • allow_globals
    • apache_status_title
    • args_method
    • auto_send_headers
    • autoflush
    • autohandler_name
    • buffer_class
    • code_cache_max_size
    • comp_class
    • comp_root
    • compiler_class
    • current_time
    • data_cache_api
    • data_cache_defaults
    • data_dir
    • decline_dirs
    • default_escape_flags
    • define_args_hash
    • dhandler_name
    • error_format
    • error_mode
    • escape_flags
    • ignore_warnings_expr
    • in_package
    • interp_class
    • lexer_class
    • max_recurse
    • out_method
    • postamble
    • postprocess_perl
    • postprocess_text
    • preamble
    • preloads
    • preprocess
    • request_class
    • resolver_class
    • static_source
    • subcomp_class
    • use_object_files
    • use_source_line_numbers
    • use_strict

NAME

HTML::Mason::Params - Mason configuration parameters

DESCRIPTION

This document lists all of the Mason configuration parameters that are intended to be used by end users.

PERL AND APACHE NAMES

Each parameter has two names: a Perl version and an Apache version. The Perl version uses lowercase_with_underscores, while the Apache version uses StudlyCaps with a Mason prefix. The conversion from one version to the other is otherwise very predictable. For example,

  • autohandler_name <--> MasonAutohandlerName

  • comp_root <--> MasonCompRoot

  • data_cache_defaults <--> MasonDataCacheDefaults

Where Apache Names Are Used

The Apache parameter names are used in the Apache configuration file in an httpd-based configuration.

Where Perl Names Are Used

The Perl parameter names are used from Perl code, i.e. anywhere other than the Apache configuration file. For example,

  • In an custom wrapper-based configuraiton, you can pass most of these parameters to the ApacheHandler constructor.

  • In a standalone Mason script, you can pass most of these parameters to the Interp constructor.

  • When launching a subrequest, you can pass any of the HTML::Mason::Request parameters to make_subrequest.

PARAMETERS

allow_globals

  • Perl name: allow_globals
  • Apache name: MasonAllowGlobals
  • Type in httpd.conf: list
  • Default: []
  • Belongs to: HTML::Mason::Compiler

List of variable names, complete with prefix ($@%), that you intend to use as globals in components. Normally global variables are forbidden by strict, but any variable mentioned in this list is granted a reprieve via a "use vars" statement. For example:

    allow_globals => [qw($DBH %session)]

In a mod_perl environment, $r (the request object) is automatically added to this list.

apache_status_title

  • Perl name: apache_status_title
  • Apache name: MasonApacheStatusTitle
  • Type in httpd.conf: string
  • Default: HTML::Mason status
  • Belongs to: HTML::Mason::ApacheHandler

Title that you want this ApacheHandler to appear as under Apache::Status. Default is "HTML::Mason status". This is useful if you create more than one ApacheHandler object and want them all visible via Apache::Status.

args_method

  • Perl name: args_method
  • Apache name: MasonArgsMethod
  • Type in httpd.conf: string
  • Default: mod_perl
  • Belongs to: HTML::Mason::ApacheHandler

Method to use for unpacking GET and POST arguments. The valid options are 'CGI' and 'mod_perl'; these indicate that a CGI.pm or Apache::Request object (respectively) will be created for the purposes of argument handling.

'mod_perl' is the default and requires that you have installed the Apache::Request package.

If args_method is 'mod_perl', the $r global is upgraded to an Apache::Request object. This object inherits all Apache methods and adds a few of its own, dealing with parameters and file uploads. See Apache::Request for more information.

If the args_method is 'CGI', the Mason request object ($m) will have a method called cgi_object available. This method returns the CGI object used for argument processing.

While Mason will load Apache::Request or CGI as needed at runtime, it is recommended that you preload the relevant module either in your httpd.conf or handler.pl file, as this will save some memory.

auto_send_headers

  • Perl name: auto_send_headers
  • Apache name: MasonAutoSendHeaders
  • Type in httpd.conf: boolean
  • Default: 1
  • Belongs to: HTML::Mason::Request::ApacheHandler

True or false, default is true. Indicates whether Mason should automatically send HTTP headers before sending content back to the client. If you set to false, you should call $r->send_http_header manually.

See the sending HTTP headers section of the developer's manual for more details about the automatic header feature.

autoflush

  • Perl name: autoflush
  • Apache name: MasonAutoflush
  • Type in httpd.conf: boolean
  • Default: 0
  • Belongs to: HTML::Mason::Request

True or false, default is false. Indicates whether to flush the output buffer after every string is output. Turn on autoflush if you need to send partial output to the client, for example in a progress meter.

autohandler_name

  • Perl name: autohandler_name
  • Apache name: MasonAutohandlerName
  • Type in httpd.conf: string
  • Default: autohandler
  • Belongs to: HTML::Mason::Interp

File name used for autohandlers. Default is "autohandler". If this is set to an empty string ("") then autohandlers are turned off entirely.

buffer_class

  • Perl name: buffer_class
  • Apache name: MasonBufferClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Buffer
  • Belongs to: HTML::Mason::Request

The class to use when creating buffers. Defaults to HTML::Mason::Buffer.

code_cache_max_size

  • Perl name: code_cache_max_size
  • Apache name: MasonCodeCacheMaxSize
  • Type in httpd.conf: string
  • Default: 10485760
  • Belongs to: HTML::Mason::Interp

Specifies the maximum size, in bytes, of the in-memory code cache where components are stored. Default is 10 MB. See the code cache section of the administrator's manual for further details.

comp_class

  • Perl name: comp_class
  • Apache name: MasonCompClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Component
  • Belongs to: HTML::Mason::Compiler::ToObject

The class into which component objects are blessed. This defaults to HTML::Mason::Component.

comp_root

  • Perl name: comp_root
  • Apache name: MasonCompRoot
  • Type in httpd.conf: list
  • Default: Varies
  • Belongs to: HTML::Mason::Resolver::File::ApacheHandler

The component root marks the top of your component hierarchy and defines how component paths are translated into real file paths. For example, if your component root is /usr/local/httpd/docs, a component path of /products/index.html translates to the file /usr/local/httpd/docs/products/index.html.

Under Apache and CGI, comp_root defaults to the server's document root. In standalone mode comp_root defaults to the current working directory.

This parameter may be either a scalar or an array reference. If it is a scalar, it should be a filesystem path indicating the component root. If it is an array reference, it should be of the following form:

 [ [ key1 => '/path/to/root' ],
   [ key2 => '/path/to/other/root' ] ]

The "keys" for each path must be unique names and their "values" must be filesystem paths. These paths will be searched in the provided order whenever a component path must be resolved to a filesystem path.

If no component root is specified, the current working directory is used.

compiler_class

  • Perl name: compiler_class
  • Apache name: MasonCompilerClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Compiler::ToObject
  • Belongs to: HTML::Mason::Interp

The class to use when creating a compiler. Defaults to HTML::Mason::Compiler.

current_time

  • Perl name: current_time
  • Apache name: MasonCurrentTime
  • Type in httpd.conf: string
  • Default: real
  • Belongs to: HTML::Mason::Interp

Interpreter's notion of the current time (deprecated).

data_cache_api

  • Perl name: data_cache_api
  • Apache name: MasonDataCacheApi
  • Type in httpd.conf: string
  • Default: 1.1
  • Belongs to: HTML::Mason::Request

The $m->cache API to use. '1.1', the default, indicates the newer API documented in this manual. '1.0' indicates the old API documented in 1.0x and earlier. This compatibility layer is provided as a convenience for users upgrading from older versions of Mason, but will not be supported indefinitely.

data_cache_defaults

  • Perl name: data_cache_defaults
  • Apache name: MasonDataCacheDefaults
  • Type in httpd.conf: hash_list
  • Default: None
  • Belongs to: HTML::Mason::Request

A hash reference of default options to use for the $m->cache command. For example, to use the MemoryCache implementation by default,

    data_cache_defaults => {cache_class => 'MemoryCache'}

These settings are overriden by options given to particular $m->cache calls.

data_dir

  • Perl name: data_dir
  • Apache name: MasonDataDir
  • Type in httpd.conf: string
  • Default: None
  • Belongs to: HTML::Mason::Interp

The data directory is a writable directory that Mason uses for various features and optimizations: for example, component object files and data cache files. Mason will create the directory on startup, if necessary, and set its permissions according to the web server User/Group.

Under Apache, data_dir defaults to a directory called "mason" under the Apache server root. You will need to change this on certain systems that assign a high-level server root such as /usr!

In non-Apache environments, data_dir has no default. If it is left unspecified, Mason will not use object files, and the default data cache class will be MemoryCache instead of FileCache.

decline_dirs

  • Perl name: decline_dirs
  • Apache name: MasonDeclineDirs
  • Type in httpd.conf: boolean
  • Default: 1
  • Belongs to: HTML::Mason::ApacheHandler

True or false, default is true. Indicates whether Mason should decline directory requests, leaving Apache to serve up a directory index or a FORBIDDEN error as appropriate. See the allowing directory requests section of the administrator's manual for more information about handling directories with Mason.

default_escape_flags

  • Perl name: default_escape_flags
  • Apache name: MasonDefaultEscapeFlags
  • Type in httpd.conf: string
  • Default: []
  • Belongs to: HTML::Mason::Compiler

Escape flags to apply to all <% %> expressions by default. The current valid flags are

    h - escape for HTML ('<' => '&lt;', etc.)
    u - escape for URL (':' => '%3A', etc.)

The developer can override default escape flags on a per-expression basis; see the escaping expressions section of the developer's manual.

If you want to set multiple flags as the default, this should be given as a reference to an array of flags.

define_args_hash

  • Perl name: define_args_hash
  • Apache name: MasonDefineArgsHash
  • Type in httpd.conf: string
  • Default: auto
  • Belongs to: HTML::Mason::Compiler::ToObject

One of "always", "auto", or "never". This determines whether or not an %ARGS hash is created in components. If it is set to "always", one is always defined. If set to "never", it is never defined.

The default, "auto", will cause the hash to be defined only if some part of the component contains the string "ARGS". This is somewhat crude, and may result in some false positives, but this is preferable to false negatives.

Not defining the args hash means that we can avoid copying component arguments, which can save memory and slightly improve execution speed.

dhandler_name

  • Perl name: dhandler_name
  • Apache name: MasonDhandlerName
  • Type in httpd.conf: string
  • Default: dhandler
  • Belongs to: HTML::Mason::Request

File name used for dhandlers. Default is "dhandler". If this is set to an empty string ("") then dhandlers are turned off entirely.

error_format

  • Perl name: error_format
  • Apache name: MasonErrorFormat
  • Type in httpd.conf: string
  • Default: Varies
  • Belongs to: HTML::Mason::Request

Indicates how errors are formatted. The built-in choices are

  • brief - just the error message with no trace information

  • text - a multi-line text format

  • line - a single-line text format, with different pieces of information separated by tabs (useful for log files)

  • html - a fancy html format

The default format under Apache and CGI is either line or html depending on whether the error mode is fatal or output, respectively. The default for standalone mode is text.

The formats correspond to HTML::Mason::Exception methods named as_format. You can define your own format by creating an appropriately named method; for example, to define an "xml" format, create a method HTML::Mason::Exception::as_xml patterned after one of the built-in methods.

error_mode

  • Perl name: error_mode
  • Apache name: MasonErrorMode
  • Type in httpd.conf: string
  • Default: Varies
  • Belongs to: HTML::Mason::Request

Indicates how errors are returned to the caller. The choices are fatal, meaning die with the error, and output, meaning output the error just like regular output.

The default under Apache and CGI is output, causing the error to be displayed in the browser. The default for standalone mode is fatal.

escape_flags

  • Perl name: escape_flags
  • Apache name: MasonEscapeFlags
  • Type in httpd.conf: hash_list
  • Default: None
  • Belongs to: HTML::Mason::Interp

A hash reference of escape flags to set for this object. See the section on the set_escape method for more details.

ignore_warnings_expr

  • Perl name: ignore_warnings_expr
  • Apache name: MasonIgnoreWarningsExpr
  • Type in httpd.conf: regex
  • Default: qr/Subroutine .* redefined/i
  • Belongs to: HTML::Mason::Interp

Regular expression indicating which warnings to ignore when loading components. Any warning that is not ignored will prevent the component from being loaded and executed. For example:

    ignore_warnings_expr =>
        'Global symbol.*requires explicit package'

If set to undef, all warnings are heeded. If set to '.', warnings are turned off completely as a specially optimized case.

By default, this is set to 'Subroutine .* redefined'. This allows you to declare global subroutines inside <%once> sections and not receive an error when the component is reloaded.

in_package

  • Perl name: in_package
  • Apache name: MasonInPackage
  • Type in httpd.conf: string
  • Default: HTML::Mason::Commands
  • Belongs to: HTML::Mason::Compiler::ToObject

This is the package in which a component's code is executed. For historical reasons, this defaults to HTML::Mason::Commands.

interp_class

  • Perl name: interp_class
  • Apache name: MasonInterpClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Interp
  • Belongs to: HTML::Mason::ApacheHandler

The class to use when creating a interpreter. Defaults to HTML::Mason::Interp.

lexer_class

  • Perl name: lexer_class
  • Apache name: MasonLexerClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Lexer
  • Belongs to: HTML::Mason::Compiler

The class to use when creating a lexer. Defaults to HTML::Mason::Lexer.

max_recurse

  • Perl name: max_recurse
  • Apache name: MasonMaxRecurse
  • Type in httpd.conf: string
  • Default: 32
  • Belongs to: HTML::Mason::Request

The maximum recursion depth for the component stack, for the request stack, and for the inheritance stack. An error is signalled if the maximum is exceeded. Default is 32.

out_method

  • Perl name: out_method
  • Apache name: MasonOutMethod
  • Type in httpd.conf: code
  • Default: Print to STDOUT
  • Belongs to: HTML::Mason::Request

Indicates where to send output. If out_method is a reference to a scalar, output is appended to the scalar. If out_method is a reference to a subroutine, the subroutine is called with each output string. For example, to send output to a file called "mason.out":

    my $fh = new IO::File ">mason.out";
    ...
    out_method => sub { $fh->print($_[0]) }

By default, out_method prints to standard output. Under Apache, standard output is redirected to $r->print.

postamble

  • Perl name: postamble
  • Apache name: MasonPostamble
  • Type in httpd.conf: string
  • Default: None
  • Belongs to: HTML::Mason::Compiler::ToObject

Text given for this parameter is placed at the end of each component. See also preamble.

postprocess_perl

  • Perl name: postprocess_perl
  • Apache name: MasonPostprocessPerl
  • Type in httpd.conf: code
  • Default: None
  • Belongs to: HTML::Mason::Compiler

Sub reference that is called to postprocess the Perl portion of a compiled component, just before it is assembled into its final subroutine form. The sub is called with a single parameter, a scalar reference to the Perl portion of the component. The sub is expected to process the string in-place. See also preprocess and postprocess_text.

postprocess_text

  • Perl name: postprocess_text
  • Apache name: MasonPostprocessText
  • Type in httpd.conf: code
  • Default: None
  • Belongs to: HTML::Mason::Compiler

Sub reference that is called to postprocess the text portion of a compiled component, just before it is assembled into its final subroutine form. The sub is called with a single parameter, a scalar reference to the text portion of the component. The sub is expected to process the string in-place. See also preprocess and postprocess_perl.

preamble

  • Perl name: preamble
  • Apache name: MasonPreamble
  • Type in httpd.conf: string
  • Default: None
  • Belongs to: HTML::Mason::Compiler::ToObject

Text given for this parameter is placed at the beginning of each component. See also postamble.

preloads

  • Perl name: preloads
  • Apache name: MasonPreloads
  • Type in httpd.conf: list
  • Default: None
  • Belongs to: HTML::Mason::Interp

A list of component paths, optionally with glob wildcards, to load when the interpreter initializes. e.g.

    preloads => ['/foo/index.html','/bar/*.pl']

Default is the empty list. For maximum performance, this should only be used for components that are frequently viewed and rarely updated. See the preloading components section of the administrator's manual for further details.

As mentioned in the developer's manual, a component's <%once> section is executed when it is loaded. For preloaded components, this means that this section will be executed before a Mason or Apache request exist, so preloading a component that uses $m or $r in a <%once> section will fail.

preprocess

  • Perl name: preprocess
  • Apache name: MasonPreprocess
  • Type in httpd.conf: code
  • Default: None
  • Belongs to: HTML::Mason::Compiler

Sub reference that is called to preprocess each component before the compiler does it's magic. The sub is called with a single parameter, a scalar reference to the script. The sub is expected to process the script in-place. This is one way to extend the HTML::Mason syntax with new tags, etc., although a much more flexible way is to subclass the Lexer or Compiler class. See also postprocess_text and postprocess_perl.

request_class

  • Perl name: request_class
  • Apache name: MasonRequestClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Request
  • Belongs to: HTML::Mason::Interp

The class to use when creating requests. Defaults to HTML::Mason::Request.

resolver_class

  • Perl name: resolver_class
  • Apache name: MasonResolverClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Resolver::File
  • Belongs to: HTML::Mason::Interp

The class to use when creating a resolver. Defaults to HTML::Mason::Resolver::File.

static_source

  • Perl name: static_source
  • Apache name: MasonStaticSource
  • Type in httpd.conf: boolean
  • Default: 0
  • Belongs to: HTML::Mason::Interp

True or false, default is false. When false, Mason checks the timestamp of the component source file each time the component is used to see if it has changed. This provides the instant feedback for source changes that is expected for development. However it does entail a file stat for each component executed.

When true, Mason assumes that the component source tree is unchanging: it will not check component source files to determine if the memory cache or object file has expired. This can save many file stats per request. However, in order to get Mason to recognize a component source change, you must remove object files and restart the server (so as to clear the memory cache).

Use this feature for live sites where performance is crucial and where updates are infrequent and well-controlled.

subcomp_class

  • Perl name: subcomp_class
  • Apache name: MasonSubcompClass
  • Type in httpd.conf: string
  • Default: HTML::Mason::Component::Subcomponent
  • Belongs to: HTML::Mason::Compiler::ToObject

The class into which subcomponent objects are blessed. This defaults to HTML::Mason::Component::Subcomponent.

use_object_files

  • Perl name: use_object_files
  • Apache name: MasonUseObjectFiles
  • Type in httpd.conf: boolean
  • Default: 1
  • Belongs to: HTML::Mason::Interp

True or false, default is true. Specifies whether Mason creates object files to save the results of component parsing. You may want to turn off object files for disk space reasons, but otherwise this should be left alone.

use_source_line_numbers

  • Perl name: use_source_line_numbers
  • Apache name: MasonUseSourceLineNumbers
  • Type in httpd.conf: boolean
  • Default: 1
  • Belongs to: HTML::Mason::Compiler

True or false, default is true. Indicates whether component line numbers that appear in error messages, stack traces, etc. are in terms of the source file instead of the object file. Mason does this by inserting '#line' directives into compiled components. While source line numbers are more immediately helpful, object file line numbers may be more appropriate for in-depth debugging sessions.

use_strict

  • Perl name: use_strict
  • Apache name: MasonUseStrict
  • Type in httpd.conf: boolean
  • Default: 1
  • Belongs to: HTML::Mason::Compiler::ToObject

True or false, default is true. Indicates whether or not a given component should use strict.


HTML::Mason::Parser - Old module for compiling components

NAME

HTML::Mason::Parser - Old module for compiling components

DESCRIPTION

The Parser object is no longer part of Mason. It has been replaced by the Compiler and Lexer objects. See the Developer's Manual and the Administrator's Manual for more details.


HTML::Mason::Request - Mason Request Class

  • COMPONENT PATHS
  • PARAMETERS TO THE new() CONSTRUCTOR
  • METHODS
  • APACHE-ONLY METHODS
  • CGI-ONLY METHODS
  • APACHE- OR CGI-ONLY METHODS
  • AUTHORS
  • SEE ALSO

NAME

HTML::Mason::Request - Mason Request Class

SYNOPSIS

    $m->abort (...)
    $m->comp (...)
    etc.

DESCRIPTION

The Request API is your gateway to all Mason features not provided by syntactic tags. Mason creates a new Request object for every web request. Inside a component you access the current request object via the global $m. Outside of a component, you can use the class method instance.

COMPONENT PATHS

The methods Request->comp, Request->comp_exists, and Request->fetch_comp take a component path argument. Component paths are like URL paths, and always use a forward slash (/) as the separator, regardless of what your operating system uses.

  • If the path is absolute (starting with a '/'), then the component is found relative to the component root.

  • If the path is relative (no leading '/'), then the component is found relative to the current component directory.

  • If the path matches both a subcomponent and file-based component, the subcomponent takes precedence.

PARAMETERS TO THE new() CONSTRUCTOR

autoflush

True or false, default is false. Indicates whether to flush the output buffer after every string is output. Turn on autoflush if you need to send partial output to the client, for example in a progress meter.

buffer_class

The class to use when creating buffers. Defaults to HTML::Mason::Buffer.

data_cache_api

The $m->cache API to use. '1.1', the default, indicates the newer API documented in this manual. '1.0' indicates the old API documented in 1.0x and earlier. This compatibility layer is provided as a convenience for users upgrading from older versions of Mason, but will not be supported indefinitely.

data_cache_defaults

A hash reference of default options to use for the $m->cache command. For example, to use the MemoryCache implementation by default,

    data_cache_defaults => {cache_class => 'MemoryCache'}

These settings are overriden by options given to particular $m->cache calls.

dhandler_name

File name used for dhandlers. Default is "dhandler". If this is set to an empty string ("") then dhandlers are turned off entirely.

error_format

Indicates how errors are formatted. The built-in choices are

  • brief - just the error message with no trace information

  • text - a multi-line text format

  • line - a single-line text format, with different pieces of information separated by tabs (useful for log files)

  • html - a fancy html format

The default format under Apache and CGI is either line or html depending on whether the error mode is fatal or output, respectively. The default for standalone mode is text.

The formats correspond to HTML::Mason::Exception methods named as_format. You can define your own format by creating an appropriately named method; for example, to define an "xml" format, create a method HTML::Mason::Exception::as_xml patterned after one of the built-in methods.

error_mode

Indicates how errors are returned to the caller. The choices are fatal, meaning die with the error, and output, meaning output the error just like regular output.

The default under Apache and CGI is output, causing the error to be displayed in the browser. The default for standalone mode is fatal.

max_recurse

The maximum recursion depth for the component stack, for the request stack, and for the inheritance stack. An error is signalled if the maximum is exceeded. Default is 32.

out_method

Indicates where to send output. If out_method is a reference to a scalar, output is appended to the scalar. If out_method is a reference to a subroutine, the subroutine is called with each output string. For example, to send output to a file called "mason.out":

    my $fh = new IO::File ">mason.out";
    ...
    out_method => sub { $fh->print($_[0]) }

By default, out_method prints to standard output. Under Apache, standard output is redirected to $r->print.

METHODS

abort ([return value])

Ends the current request, finishing the page without returning through components. The optional argument specifies the return value from Interp::exec; in a web environment, this ultimately becomes the HTTP status code.

abort is implemented by throwing an HTML::Mason::Exception::Abort object and can thus be caught by eval(). The aborted method is a shortcut for determining whether a caught error was generated by abort.

If abort is called from a component that has a <%filter>, than any output generated up to that point is filtered, unless abort is called from a <%shared> block.

aborted ([$err])

Returns true or undef indicating whether the specified $err was generated by abort. If no $err was passed, uses $@.

In this code, we catch and process fatal errors while letting abort exceptions pass through:

    eval { code_that_may_fail_or_abort() };
    if ($@) {
        die $@ if $m->aborted;

        # handle fatal errors...

$@ can lose its value quickly, so if you are planning to call $m->aborted more than a few lines after the eval, you should save $@ to a temporary variable.

base_comp

Returns the current base component for method and attributes. Initially, the base component is the same as the requested component (returned by $m->request_comp. However, whenever a component call is made, the base component changes to the called component, unless the component call was made uses a component object for its first argument, or the call starts with SELF:, PARENT:, or REQUEST.

cache (cache_class=>'...', [cache_options])

$m->cache returns a new cache object with a namespace specific to this component.

cache_class specifies the class of cache object to create. It defaults to FileCache in most cases, or MemoryCache if the interpreter has no data directory, and must be a backend subclass of Cache::Cache. The prefix "Cache::" need not be included. See the Cache::Cache package for a full list of backend subclasses.

I<cache_options> may include any valid options to the new() method of
the cache class. e.g. for C<FileCache>, valid options include
default_expires_in and cache_depth.

See the data caching section of the developer's manual for a caching tutorial and examples. See the HTML::Mason::Cache::BaseCache documentation for a method reference.

Note: users upgrading from 1.0x and earlier can continue to use the old $m->cache API by setting data_cache_api to '1.0'. This support will be removed at a later date.

cache_self ([expires_in => '...'], [key => '...'], [get_options], [cache_options])

$m->cache_self caches the entire output and return result of a component.

cache_self either returns undef, or a list containing the return value of the component followed by '1'. You should return immediately upon getting the latter result, as this indicates that you are inside the second invocation of the component.

cache_self takes any of parameters to $m->cache (e.g. cache_depth), any of the optional parameters to $cache->get (expire_if, busy_lock), and two additional options:

  • expire_in or expires_in: Indicates when the cache expires - it is passed as the third argument to $cache->set. e.g. '10 sec', '5 min', '2 hours'.

  • key: An identifier used to uniquely identify the cache results - it is passed as the first argument to $cache->get and $cache->set. The default key is '__mason_cache_self__'.

To cache the component's output:

    <%init>
    return if $m->cache_self(expire_in => '10 sec'[, key => 'fookey']);
    ... <rest of init> ...
    </%init>

To cache the component's scalar return value:

    <%init>
    my ($result, $cached) = $m->cache_self(expire_in => '5 min'[, key => 'fookey']);

    return $result if $cached;
    ... <rest of init> ...
    </%init>

To cache the component's list return value:

    <%init>
    my (@retval) = $m->cache_self(expire_in => '3 hours'[, key => 'fookey']);

    return @retval if pop @retval;
    ... <rest of init> ...
    </%init>

We call pop on @retval to remove the mandatory '1' at the end of the list.

If a component has a <%filter> block, then the filtered output is cached.

Note: users upgrading from 1.0x and earlier can continue to use the old $m->cache_self API by setting data_cache_api to '1.0'. This support will be removed at a later date.

caller_args

Returns the arguments passed by the component at the specified stack level. Use a positive argument to count from the current component and a negative argument to count from the component at the bottom of the stack. e.g.

    $m->caller_args(0)   # arguments passed to current component
    $m->caller_args(1)   # arguments passed to component that called us
    $m->caller_args(-1)  # arguments passed to first component executed

When called in scalar context, a hash reference is returned. When called in list context, a list of arguments (which may be assigned to a hash) is returned. Returns undef or an empty list, depending on context, if the specified stack level does not exist.

callers

With no arguments, returns the current component stack as a list of component objects, starting with the current component and ending with the top-level component. With one numeric argument, returns the component object at that index in the list. Use a positive argument to count from the current component and a negative argument to count from the component at the bottom of the stack. e.g.

    my @comps = $m->callers   # all components
    $m->callers(0)            # current component
    $m->callers(1)            # component that called us
    $m->callers(-1)           # first component executed

Returns undef or an empty list, depending on context, if the specified stack level does not exist.

caller

A synonym for $m->callers(1), i.e. the component that called the currently executing component.

call_next ([args...])

Calls the next component in the content wrapping chain; usually called from an autohandler. With no arguments, the original arguments are passed to the component. Any arguments specified here serve to augment and override (in case of conflict) the original arguments. Works like $m->comp in terms of return value and scalar/list context. See the autohandlers section of the developer's manual for examples.

call_self (output, return)

This method allows a component to call itself so that it can filter both its output and return values. It is fairly advanced; for most purposes the <%filter> tag will be sufficient and simpler.

$m->call_self takes two arguments. The first is a scalar reference and will be populated with the component output. The second is either a scalar or list reference and will be populated with the component return value; the type of reference determines whether the component will be called in scalar or list context. Both of these arguments are optional; you may pass undef for either of them.

$m->call_self acts like a fork() in the sense that it will return twice with different values. When it returns 0, you allow control to pass through to the rest of your component. When it returns 1, that means the component has finished and you can begin filtering the output and/or return value. (Don't worry, it doesn't really do a fork! See next section for explanation.)

The following examples would generally appear at the top of a < <%init >> section. Here is a no-op $m->call_self that leaves the output and return value untouched:

    <%init>
    my ($output, $retval);
    if ($m->call_self(\$output, \$retval)) {
        $m->print($output);
        return $retval;
    }
    ...

Here is a simple output filter that makes the output all uppercase. Note that we ignore both the original and the final return value.

    <%init>
    my $output;
    if ($m->call_self(\$output, undef)) {
        $m->print(uc $output);
        return;
    }
    ...

Here is a piece of code that traps all errors occuring anywhere in the component or its children, e.g. for the purpose of handling application-specific exceptions. This is difficult to do with a manual eval because it would have to span multiple code sections and the main component body.

    <%init>
    # Run this component with an eval around it
    my $in_parent = eval { $m->call_self() };
    if ($@) {
        # check $@ and do something with it
    }
    return if $in_parent;
    ...
clear_buffer

Clears the Mason output buffer. Any output sent before this line is discarded. Useful for handling error conditions that can only be detected in the middle of a request.

clear_buffer is, of course, thwarted by flush_buffer.

comp (comp, args...)

Calls the component designated by comp with the specified option/value pairs. comp may be a component path or a component object.

Components work exactly like Perl subroutines in terms of return values and context. A component can return any type of value, which is then returned from the $m->comp call.

The <& &> tag provides a convenient shortcut for $m->comp.

As of 1.10, component calls can accept an initial hash reference of modifiers. The only currently supported modifier is store, which stores the component's output in a scalar reference. For example:

  my $buf;
  my $return = $m->comp( { store => \$buf }, '/some/comp', type => 'big' );

This mostly duplicates the behavior of scomp, but can be useful in rare cases where you need to capture both a component's output and return value.

This modifier can be used with the <& &> tag as well, for example:

  <& { store => \$buf }, '/some/comp', size => 'medium' &>
comp_exists (comp_path)

Returns 1 if comp_path is the path of an existing component, 0 otherwise. That path given may be relative, in which case the current component's directory path will be prepended.

content

Evaluates the content (passed between <&| comp &> and </&> tags) of the current component, and returns the resulting text.

Returns undef if there is no content.

has_content

Returns true if the component was called with content (i.e. with <&| comp &> and </&> tags instead of a single <& comp &> tag). This is generally better than checking the defined'ness of $m->content because it will not try to evaluate the content.

count

Returns the number of this request, which is unique for a given request and interpreter.

current_comp

Returns the current component object.

decline

Used from a top-level component or dhandler, this method clears the output buffer, aborts the current request and restarts with the next applicable dhandler up the tree. If no dhandler is available, an error occurs. This method bears no relation to the Apache DECLINED status except in name.

declined ([$err])

Returns true or undef indicating whether the specified $err was generated by decline. If no $err was passed, uses $@.

depth

Returns the current size of the component stack. The lowest possible value is 1, which indicates we are in the top-level component.

dhandler_arg

If the request has been handled by a dhandler, this method returns the remainder of the URI or Interp::exec path when the dhandler directory is removed. Otherwise returns undef.

dhandler_arg may be called from any component in the request, not just the dhandler.

exec (comp, args...)

Starts the request by executing the top-level component and arguments. This is normally called for you on the main request, but you can use it to execute subrequests.

A request can only be executed once; e.g. it is an error to call this recursively on the same request.

fetch_comp (comp_path)

Given a comp_path, returns the corresponding component object or undef if no such component exists.

fetch_next

Returns the next component in the content wrapping chain, or undef if there is no next component. Usually called from an autohandler. See the autohandlers section of the developer's manual for usage and examples.

fetch_next_all

Returns a list of the remaining components in the content wrapping chain. Usually called from an autohandler. See the autohandlers section of the developer's manual for usage and examples.

file (filename)

Returns the contents of filename as a string. If filename is a relative path, Mason prepends the current component directory.

flush_buffer

Flushes the Mason output buffer. Under mod_perl, also sends HTTP headers if they haven't been sent and calls $r->rflush to flush the Apache buffer. Flushing the initial bytes of output can make your servers appear more responsive.

Attempts to flush the buffers are ignored within the context of a call to $m->scomp or when output is being stored in a scalar reference, as with the { store => \$out } component call modifier.

Additionally, if a component has a <%filter> block, that component is buffered until its entire output is generated. This means that inside that component and any components that it calls, the buffer cannot be flushed.

instance

This class method returns the HTML::Mason::Request currently in use. If called when no Mason request is active it will return undef.

If called inside a subrequest, it returns the subrequest object.

interp

Returns the Interp object associated with this request.

make_subrequest (comp => path, args => arrayref, other parameters)

This method creates a new Request object which inherits its parent's settable properties, such as autoflush and out_method. These values may be overridden by passing parameters to this method.

The comp parameter is required, while all other parameters are optional. It may be specified as an absolute path or as a path relative to the current component.

See the subrequests section of the developer's manual for more information about subrequests.

notes (key, value)

The notes() method provides a place to store application data, giving developers a way to share data among multiple components. Any data stored here persists for the duration of the request, i.e. the same lifetime as the Request object.

Conceptually, notes() contains a hash of key-value pairs. notes($key, $value) stores a new entry in this hash. notes($key) returns a previously stored value. notes() without any arguments returns a reference to the entire hash of key-value pairs.

notes() is similar to the mod_perl method $r->pnotes(). The main differences are that this notes() can be used in a non-mod_perl environment, and that its lifetime is tied to the Mason request object, not the Apache request object. In particular, a Mason subrequest has its own notes() structure, but would access the same $r->pnotes() structure.

out (string)

A synonym for $m->print.

print (string)

Print the given string. Rarely needed, since normally all text is just placed in the component body and output implicitly. $m->print is useful if you need to output something in the middle of a Perl block.

In 1.1 and on, print and $r->print are remapped to $m->print, so they may be used interchangeably. Before 1.1, one should only use $m->print.

request_args

Returns the arguments originally passed to the top level component (see request_comp for definition). When called in scalar context, a hash reference is returned. When called in list context, a list of arguments (which may be assigned to a hash) is returned.

request_comp

Returns the component originally called in the request. Without autohandlers, this is the same as the first component executed. With autohandlers, this is the component at the end of the $m->call_next chain.

scomp (comp, args...)

Like comp, but returns the component output as a string instead of printing it. (Think sprintf versus printf.) The component's return value is discarded.

subexec (comp, args...)

This method creates a new subrequest with the specified top-level component and arguments, and executes it. This is most often used to perform an "internal redirect" to a new component such that autohandlers and dhandlers take effect.

time

Returns the interpreter's notion of the current time (deprecated).

APACHE-ONLY METHODS

These additional methods are available when running Mason with mod_perl and the ApacheHandler.

ah

Returns the ApacheHandler object associated with this request.

apache_req

Returns the Apache request object. This is also available in the global $r.

auto_send_headers

True or false, default is true. Indicates whether Mason should automatically send HTTP headers before sending content back to the client. If you set to false, you should call $r->send_http_header manually.

See the sending HTTP headers section of the developer's manual for more details about the automatic header feature.

CGI-ONLY METHODS

This additional method is available when running Mason with the CGIHandler module.

cgi_request

Returns the Apache request emulation object, which is available as $r inside components.

See the CGIHandler docs for more details.

APACHE- OR CGI-ONLY METHODS

This method is available when Mason is running under either the ApacheHandler or CGIHandler modules.

cgi_object

Returns the CGI object used to parse any CGI parameters submitted to the component, assuming that you have not changed the default value of the ApacheHandler args_method parameter. If you are using the 'mod_perl' args method, then calling this method is a fatal error. See the ApacheHandler and CGIHandler documentation for more details.

redirect ($url, [$status])

Given a url, this generates a proper HTTP redirect for that URL. It uses $m->clear_buffer to clear out any previous output, and < $m-abort >> to abort the request. By default, the status code used is 302, but this can be overridden by the user.

Since this is implemented using $m->abort, it will be trapped by an eval {} block. If you are using an eval {} block in your code to trap errors, you need to make sure to rethrow these exceptions, like this:

  eval {
      ...
  };

  die $@ if $m->aborted;

  # handle other exceptions

AUTHORS

Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken Williams <ken@mathforum.org>

SEE ALSO

HTML::Mason,
HTML::Mason::Devel,
HTML::Mason::Component


HTML::Mason::Resolver - Component path resolver base class

  • Class::Container
  • METHODS
    • Using a Resolver with HTML::Mason::ApacheHandler
  • SEE ALSO

NAME

HTML::Mason::Resolver - Component path resolver base class

SYNOPSIS

  # make a subclass and use it

DESCRIPTION

The resolver is responsible for translating a component path like /foo/index.html into a component. By default, Mason expects components to be stored on the filesystem, and uses the HTML::Mason::Resolver::File class to get information on these components.

The HTML::Mason::Resolver provides a virtual parent class from which all resolver implementations should inherit.

Class::Container

This class is used by most of the Mason object's to manage constructor parameters and has-a relationships with other objects.

See the documentation on this class for details on how to declare what paremeters are valid for your subclass's constructor.

HTML::Mason::Resolver is a subclass of Class::Container so you do not need to subclass it yourself.

METHODS

If you are interested in creating a resolver subclass, you must implement the following methods.

new

This method is optional. The new method included in this class is simply inherited from Class::Container. If you need something more complicated done in your new method you will need to override it in your subclass.

get_info

Given an absolute component path, returns a new HTML::Mason::ComponentSource object.

glob_path

The only argument to this method is a path glob pattern, something like "/foo/*" or "/foo/*/bar". Given this path, it should return a list of component paths for components which match this glob pattern.

For example, the filesystem resolver simply appends this pattern to each component root in turn and calls the Perl glob() function to find matching files on the filesystem.

Using a Resolver with HTML::Mason::ApacheHandler

If you are creating a new resolver that you intend to use with the HTML::Mason::ApacheHandler module, then you must implement the following method as well, possibly in a different subclass.

apache_request_to_comp_path ($r)

This method, given an Apache object, should return a component path. This method is used by the HTML::Mason::ApacheHandler class to translate web requests into component paths. You can omit this method if your resolver subclass will never be used in conjunction with HTML::Mason::ApacheHandler.

For example, Mason includes the HTML::Mason::Resolver::File and HTML::Mason::Resolver::File::ApacheHandler classes. The latter simply adds an implementation of the apache_request_to_comp_path method for file based components.

SEE ALSO

HTML::Mason


HTML::Mason::Resolver::File - Component path resolver for file-based components

  • PARAMETERS TO THE new() CONSTRUCTOR
  • ADDITIONAL METHODS
  • SEE ALSO

NAME

HTML::Mason::Resolver::File - Component path resolver for file-based components

SYNOPSIS

  my $resolver = HTML::Mason::Resolver::File->new( comp_root => '/var/www/mason' );

  my $info = $resolver->get_info('/some/comp.html');
  my $comp_root = $resolver->comp_root;

DESCRIPTION

This HTML::Mason::Resolver subclass is used when components are stored on the filesystem, which is the norm for most Mason-based applications.

PARAMETERS TO THE new() CONSTRUCTOR

The new method takes a single parameter, comp_root.

comp_root

The component root marks the top of your component hierarchy and defines how component paths are translated into real file paths. For example, if your component root is /usr/local/httpd/docs, a component path of /products/index.html translates to the file /usr/local/httpd/docs/products/index.html.

Under Apache and CGI, comp_root defaults to the server's document root. In standalone mode comp_root defaults to the current working directory.

This parameter may be either a scalar or an array reference. If it is a scalar, it should be a filesystem path indicating the component root. If it is an array reference, it should be of the following form:

 [ [ key1 => '/path/to/root' ],
   [ key2 => '/path/to/other/root' ] ]

The "keys" for each path must be unique names and their "values" must be filesystem paths. These paths will be searched in the provided order whenever a component path must be resolved to a filesystem path.

If no component root is specified, the current working directory is used.

ADDITIONAL METHODS

comp_root

This method returns the component root, which will either be a scalar or an array reference, as documented here.

comp_root_array

Returns the component root as an array of name/path pairs. Can be used like the following:

  foreach my $pair ($self->comp_root_array) {
    my ($name, $path) = @$pair;
    ...
  }

SEE ALSO

HTML::Mason


HTML::Mason::Resolver::Null - a do-nothing resolver

  • SEE ALSO

NAME

HTML::Mason::Resolver::Null - a do-nothing resolver

SYNOPSIS

  my $resolver = HTML::Mason::Resolver::Null->new;

DESCRIPTION

This HTML::Mason::Resolver subclass is useful if you want to create components via the HTML::Mason::Interp->make_component method and you never plan to interact with the filesystem.

Basically, it provides all of the necessary resolver methods but none of them do anything.

This means that if you use this method things like $interp->exec will simply not work at all.

However, if you just want to make an component with an interepreter and execute it then it can be useful. For example:

  my $interp = HTML::Mason::Interp->new( resolver_class => 'HTML::Mason::Resolver::Null',
                                         data_dir => '/tmp' );

  my $comp = $interp->make_component( comp_source => <<'EOF' );
  % my $var = 'World';
  Hello, <% $var %>!
  EOF

  my $buffer;
  my $output = $interp->make_request( out_method => \$var )->comp($comp);

  print $buffer;

SEE ALSO

HTML::Mason


HTML::Mason::Subclassing - Documentation on Subclassing Internal Mason classes

  • Class::Container
  • SUBCLASSABLE CLASSES
  • CONSTRUCTORS
  • Request
    • What to Subclass?
    • The exec() method
    • Subrequests
    • Examples
  • Resolver and ComponentSource
  • Lexer
  • Compiler
  • Buffer
  • ApacheHandler
  • CGIHandler
  • USING SUBCLASSES

NAME

HTML::Mason::Subclassing - Documentation on Subclassing Internal Mason classes

DESCRIPTION

This is the deep voodoo guide, for folks who want to create their own custom subclasses for parts of Mason, such as the Request or Buffer objects.

Class::Container

A number of modules in Mason are subclasses of Class::Container. This module was originally part of the Mason core as HTML::Mason::Container, but Ken Williams decided to release it separately on CPAN.

It was created to encapsulate some common behaviors for Mason objects such as parameter validation and the creation of "contained" objects.

Basically, any Mason object which takes parameters to its constructor must inherit from this module. Of course, since all of the classes that you might consider subclassing already inherit from Class::Container, you won't need to inherit from it directly. However, you may need to use some of its methods.

So before you go further we highly recommend familiarizing yourself with Class::Container and its methods. Also feel free to look at some of the Mason core modules to see how Class::Container is used within Mason itself.

SUBCLASSABLE CLASSES

The following classes have been designed with subclassing in mind:

  • HTML::Mason::Request

    This object is your old friend $m. The request contains information about the current request context, and provides methods for calling other components.

  • HTML::Mason::Resolver

    The resolver's job is to translate a component paths into an actual component. Mason comes with a single Resolver subclass, HTML::Mason::Resolver::File, which is used to translate component paths into filesystem paths.

  • HTML::Mason::ComponentSource

    An object of this class represents a component's source. These objects are instantiated by the resolver when it finds a component matching a given path.

  • HTML::Mason::Lexer

    The lexer is responsible for parsing a component. Creating a new lexer would allow you to change Mason's component syntax.

  • HTML::Mason::Compiler

    The compiler takes the parsed chunks from the lexer and gives them meaning. The default compiler, HTML::Mason::Compiler::ToObject, turns a Mason component into a Mason "object file", which contains actual Perl code.

  • HTML::Mason::Buffer

    Buffers are created and manipulated (mostly) by the request class and are responsible for handling output. Buffers apply filters to output and buffer it (surprise) as well.

  • HTML::Mason::ApacheHandler

    The ApacheHandler class is the bridge between the mod_perl world and Mason, primarily Mason's Interp class.

    It also provides its own HTML::Mason::Request and HTML::Resolver::File subclasses which implement some mod_perl specific behaviors and features.

  • HTML::Mason::Interp

    The Interp is the core of Mason, and is primarily responsible for making all the other objects do their jobs.

CONSTRUCTORS

If you choose to override the constructor, which is always new with Mason objects, that you make sure to call the superclass's constructor and that you use the object returned by it. A good boilerplate for an overridden constructor looks something like this:

  sub new
  {
      my $class = shift;

      my $self = $class->SUPER::new(@_);

      $self->_do_some_init;

      return $self;
        }

Request

What to Subclass?

One important thing to know about this class is that it is actually several classes. The first, HTML::Mason::Request, is used when ApacheHandler is not loaded. The other, HTML::Mason::Request::ApacheHandler, is loaded by ApacheHandler and used to provide some mod_perl specific features. Similar, the CGIHandler class provides its own request subclass, HTML::Mason::Request::CGIHandler.

It is impossible to know which one of these to subclass at compile time, since it is possible that your subclass will be loaded before either ApacheHandler or CGIHandler.

To handle this, simply call the alter_superclass() method in your constructor, like this:

  sub new
  {
      my $class = shift;

      $class->alter_superclass( $HTML::Mason::ApacheHandler::VERSION ?
                                'HTML::Mason::Request::ApacheHandler' :
                                $HTML::Mason::CGIHandler::VERSION ?
                                'HTML::Mason::Request::CGI' :
                                'HTML::Mason::Request' );

      my $self = $class->SUPER::new(@_);

      ...
      return $self;
        }

It is quite important that you do this as these handler-specific subclasses provide important functionality. The alter_superclass() method is implemented in the HTML::Mason::Request base class, and will do the right thing even in cases of multiple inheritance. It also cooperates with Class::Container to make sure that it sees changes to the inheritance hierarchy.

The exec() method

The exec method is called in order to execute a request, and is the method that you are most likely to want to override.

However, if you do override it we suggest that you make sure to call the parent class's exec method to implement the actual component execution and there is no need for you to re-implement them.

Since the exec() method is scalar/list context-sensitive, your exec method will need to preserve that. Here is a boilerplate:

  sub exec
  {
      my $self = shift;

      ... # do something cool
      my @r;
      if (wantarray)
      {
          @r = $self->SUPER::exec(@_);
      }
      else
      {
          $r[0] = $self->SUPER::exec(@_);
      }

      ... # maybe do some cleanup
      return wantarray ? @r : $r[0];
        }

Subrequests

Your custom request class will also be used to implement subrequests, which are implemented by calling exec just like any other method. If you only want to do certain things in exec for the first request, you can simply check the value of $self->is_subrequest.

Examples

See the MasonX::Request::WithApacheSession module on CPAN.

Resolver and ComponentSource

The resolver takes a component path and figures out what component that path corresponds to.

All resolver classes must implement two methods, get_info and glob_path. The first takes a component path and returns a new HTML::Mason::ComponentSource object. This object contains information about the component, such as its last modified time and its source. See the HTML::Mason::ComponentSource documentation for more details.

You may choose to provide your own ComponentSource subclass as well, if your resolver implementation can take advantage of it.

The glob_path method is responsible for translating a component path like /foo/*/bar into a list of component paths that match that glob pattern.

Lexer

The rationale for providing your own lexer would be to extend or replace Mason's syntax.

The lexer is called by the compiler via its lex method. The arguments it receives are the component name, source, and the compiler object. See the Compiler class documentation for details on what methods the lexer can call.

Compiler

See the Compiler class documentation for details on what methods a subclass of this class needs to provide.

If you simply want to tweak Mason's existing behavior, you will probably want to subclass HTML::Mason::Compiler::ToObject, which is the default Compiler class. For example, if you wanted to do something like make attributes dynamic, you could override the _flags_or_attr() method in ToObject.

If you want to drastically change the behavior, you can subclass HTML::Mason::Compiler instead. An example of this would be creating a compiler that generates EmbPerl or Apache::ASP as output.

Buffer

The public API documented in HTML::Mason::Buffer is the complete Buffer class API, except for one method, _initialize, which is called as part of the buffer's construction, from the new method.

Those interested in subclassing this class should also know that the constructor may take an additional parameter, parent, which should be a Buffer object. This parameter is automatically supplied by the new_child method.

Any subclass of this class you create should declare itself to be a subclass of the HTML::Mason::Buffer class.

ApacheHandler

The methods that you are most likely to want to subclass are documented in the ApacheHandler class documentation.

Providing an ApacheHandler subclass gives you a chance to do your own client parameter parsing, as well as the capability of providing a different way of handling requests.

CGIHandler

Like the ApacheHandler, you could subclass this module in order to provide your own argument processing or to step in and provide a different way to handle requests.

USING SUBCLASSES

When using your custom subclasses, we recommend that you take advantage of Mason's ability to construct subclassed object on the fly.

For example, if you're subclassed the Interp object, you can still let the ApacheHandler object create the Interp object for you, as long as you give it the appropriate interp_class parameter. This is important because Mason may internally set up certain defaults for contained objects. For example, the ApacheHandler, by default, will tell the Interp object to use the HTML::Mason::Request::ApacheHandler Request subclass. If you create an Interp object manually and you want to use that Interp object with ApacheHandler, you'll have to specify the same Request class.

For example:

  my $interp =
      My::Interp->new
          ( request_class  => 'HTML::Mason::Request::ApacheHandler',
            resolver_class => 'HTML::Mason::Resolver::File::ApacheHandler',
            my_new_interp_param => 42,
          );

  my $ah = HTML::Mason::ApacheHandler->new( interp => $interp );

It is far easier to simply do this:

  my $ah =
      HTML::Mason::ApacheHandler->new
          ( interp_class => 'My::Interp',
            my_new_interp_param => 42,
          );

Your new parameter, my_new_interp_param, will still be passed to the My::Interp constructor, but this also gives ApacheHandler a chance to set various parameters for the Interp object. Of course, you can still override these defaults explicitly:

  my $ah =
      HTML::Mason::ApacheHandler->new
          ( interp_class => 'My::Interp',
            resolver_class => 'My::Resolver'.
            my_new_interp_param => 42,
          );

If you need access to the interp object's methods directly, it will be always be available via $ah->interp.


HTML::Mason::Tests - Test harness for testing Mason

  • METHODS
    • new
    • add_support
    • add_test
    • run
    • Class methods
    • base_path
    • comp_root
    • data_dir
    • check_output ( actual => $actual_output, expect => $expected_output )
  • ADDITIONAL RUN MODES
    • Verbose mode
    • Debug mode
    • No cleanup mode
    • Create mode
    • Running and/or skipping selected tests
    • Subclassing this module
  • SEE ALSO

NAME

HTML::Mason::Tests - Test harness for testing Mason

SYNOPSIS

 use HTML::Mason::Tests;

 my $group = HTML::Mason::Tests->new( name => 'name of group', description => 'tests something' );
 $group->add_test( name => 'foo',
                   description => 'tests foo',
                   component => <<'EOF'
 <%args>
 $foo => 1
 </%args>
 <% $foo %>
 EOF
                   expect => <<'EOF',
 1
 EOF
                 );

 $group->run;

DESCRIPTION

This module is designed to automate as much as possible of the Mason test suite. It does tasks like write component files to disk, call them, compare the actual results to the expected results, and more. In addition, it also is capable of printing out useful information about test failures when run in verbose mode. See the ADDITIONAL RUN MODES section for more information.

It also makes sure that any given group of tests provides all the information needed to run them (test names, components and results, etc.).

Now you have no excuse for writing new tests (and that goes double for me!).

METHODS

new

Takes the following parameters:

  • name (required)

    The name of the entire group of tests.

  • description (required)

    What this group tests.

  • pre_test_cleanup (optional, default=1)

    If this is true (the default), the component root and data directory will be deleted both before and after running tests.

add_support

Takes the following parameters:

  • path (required)

    The path that other components will expect this component to be reachable at. All paths are prepended with the group name. So '/bar' as a support component in the 'foo' group's ultimate path would be '/foo/bar'.

  • component

    Text of the support component. This parameter must have a value unless the skip_component parameter is true.

  • skip_component

    If true, then the test harness will not write a component to disk for this test.

add_test

Takes the following parameters:

  • name (required)

    The name of this test.

  • description (required)

    What this test is testing.

  • component (required)

    Text of the component.

  • path (optional)

    The path that this component should written to. As with support components, this path is prepended with the group's name. If no path is given, the value of the name parameter is used.

  • call_path (optional)

    The path that should be used to call the component. If none is given, then the value is the same as the path option, if that exists, otherwise it is /<group name>/<test name>. If a value is given, it is still prepended by /<group name>/.

  • call_args (optional)

    The arguments that should be passed to the component, in list or hash reference form. If none is given, no arguments are passed.

  • compiler_params

    This is a hash reference of parameters to be passed to the Compiler->new method.

  • interp_params

    This is a hash reference of parameters to be passed to the Interp->new method.

  • interp

    Provide an HTML::Mason::Interp object to be used for the test.

One of the following three options is required:

  • expect

    The text expected as a result of calling the component. This parameter is _not_ required when running in Create mode.

  • expect_error

    A regex containing that will be matched against the error returned from the component execution.

  • skip_expect

    This causes the component to be run but its output is ignored. However, if the component execution causes an error this will cause the test to fail. This is used in a few situations where it is necessary to just run a component as part the preparation for another test.

run

Run the tests in the group.

Class methods

These methods are provided since some tests may need to know these values.

base_path

The base path under which the component root and data directory for the tests are created.

comp_root

Returns the component root directory.

data_dir

Return the data directory

check_output ( actual => $actual_output, expect => $expected_output )

Given the parameters shown above, this method will check to see if the two are equal. If they're not equal, it will print out an error message attempting to highlight the difference.

ADDITIONAL RUN MODES

The following additional modes are available for running tests.

Verbose mode

To turn this on, set the environment variables MASON_VERBOSE or MASON_DEBUG as true or run the tests as 'make test TEST_VERBOSE=1'. In this mode, the run method will output information about tests as they are run. If a test fails, then it will also show the cause of the failure.

Debug mode

To turn this on, set the MASON_DEBUG environment variable to a true value. In this mode, the run method will print detailed information of its actions. This mode includes the output printed in VERBOSE mode.

No cleanup mode

Setting the MASON_NO_CLEANUP environment variable will tell the module to not clean up generated data from running the tests. This includes the components written to disk and the data directory used during testing. This can be useful when debugging.

Create mode

If the individual tests are run from the command line with the '--create' flag, then instead of checking the output of a component, the test harness will simply output its results. This allows you to cut and paste these results back into the test file (assuming they are correct!).

Running and/or skipping selected tests

You can run just some of a test file with the '--tests-to-run' flag or the MASON_TESTS_TO_RUN environment variable. Similarly you can skip specific tests with the '--tests-to-skip' flag or the MASON_TESTS_TO_SKIP environment variable.

The value of either flag is a comma-separated list of one or more of

   [test_file_name:](test_number|test_name|*)

e.g.

    perl ./01-syntax.t --tests-to-run=3,5
    MASON_TESTS_TO_SKIP=fake_percent,empty_percents perl ./01-syntax.t
    MASON_TESTS_TO_RUN="misc:autohandler, request:*, interp:private1" make test

Subclassing this module

You can run tests with your own Tests.pm subclass using the '--tests-class' flag or the MASON_TESTS_CLASS environment variable. The value is a fully qualified package name that will be loaded before each test file is run. e.g.

    perl ./01-syntax.t --tests-class=HTML::Mason::Tests::MyTests
    MASON_TESTS_CLASS=HTML::Mason::Tests::MyTests make test

For example, if you have created your own lexer subclass and want to make sure that tests still pass with it, create a Tests subclass that overrides the _make_interp method to use your subclass:

    sub _make_interp
    {
        my ($self, %interp_params) = @_;

        return HTML::Mason::Interp->new
            ( lexer_class => HTML::Mason::MyLexer,
              %interp_params );
    }

SEE ALSO

HTML::Mason


HTML::Mason::Tools - Function library used internally in Mason

  • FUNCTIONS

NAME

HTML::Mason::Tools - Function library used internally in Mason

DESCRIPTION

This module contains exportable functions that are intended to be used by other Mason modules.

The documentation here is primarily intended to be used by Mason core developers.

Others who choose to use these functions do so at their own risk, as they may change from release to release. You have been warned.

FUNCTIONS

read_file

This function takes a file name and an optional argument indicating whether or not to open the final in binary mode. It will return the entire contents of the file as a scalar.

paths_eq

Given to paths, this function indicates whether they represent the same location on the filesystem. It does not account for symlinks.

compress_path

This turns a component path into a filesystem-friendly path by escaping potentially meaningful characters.

absolute_comp_path

Given a component path and a directory path, this function returns the absolute component path, prepending the directory path if needed.

mason_canonpath

This function cleans up a component path and returns its canonical version. It is largely the same as File::Spec::Unix::canonpath, with a few additional cleanups.

pkg_installed

Given a module name, this function returns true or false to indicate whether or not a corresponding .pm file exists.

pkg_loaded

Given a module name, this function returns true or false to indicate whether or not the module has been loaded into memory.

load_pkg

Given a module name, this function attempts to load it. It takes an additional boolean parameter indicating whether or not to throw an exception if the module cannot be found. By default, if the module cannot be found, this function simply returns false.

All errors generate exceptions no matter what.

If the module is loaded successfully, this function returns true.

taint_is_on

Returns a boolean value indicating whether taint mode is on or not.

make_fh

This function returns something suitable to be passed to the first argument of an open function call.

coerce_to_array

Given a scalar, which may be a reference, this function attempts to return an array. It throws an HTML::Mason::Exception::Params exception if this can't be done.

This function is called from the generated component code as part of a component's argument handling.

coerce_to_hash

Given a scalar, which may be a reference, this function attempts to return a hash. It throws an HTML::Mason::Exception::Params exception if this can't be done.

This function is called from the generated component code as part of a component's argument handling.


HTML::Mason::Utils - Publically available functions useful outside of Mason

  • FUNCTIONS

NAME

HTML::Mason::Utils - Publically available functions useful outside of Mason

DESCRIPTION

The functions in this module are useful when you need to interface code you have written with Mason.

FUNCTIONS

data_cache_namespace ($comp_id)

Given a component id, this method returns its default Cache::Cache namespace. This can be useful if you want to access the cached data outside of Mason.

With a single component root, the component id is just the component path. With multiple component roots, the component id is key/path, where key is the key corresponding to the root that the component falls under.

cgi_request_args ($cgi, $method)

This function expects to receive a CGI.pm object and the request method (GET, POST, etc). Given these two things, it will return a hash in list context or a hashref in scalar context. The hash(ref) will contain all the arguments passed via the CGI request. The keys will be argument names and the values will be either scalars or array references.


HTML::Parse - Deprecated, a wrapper around HTML::TreeBuilder

  • REMEMBER!
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

HTML::Parse - Deprecated, a wrapper around HTML::TreeBuilder

SYNOPSIS

  See the documentation for HTML::TreeBuilder

DESCRIPTION

Disclaimer: This module is provided only for backwards compatibility with earlier versions of this library. New code should not use this module, and should really use the HTML::Parser and HTML::TreeBuilder modules directly, instead.

The HTML::Parse module provides functions to parse HTML documents. There are two functions exported by this module:

parse_html($html) or parse_html($html, $obj)

This function is really just a synonym for $obj->parse($html) and $obj is assumed to be a subclass of HTML::Parser. Refer to the HTML::Parser manpage for more documentation.

If $obj is not specified, the $obj will default to an internally created new HTML::TreeBuilder object configured with strict_comment() turned on. That class implements a parser that builds (and is) a HTML syntax tree with HTML::Element objects as nodes.

The return value from parse_html() is $obj.

parse_htmlfile($file, [$obj])

Same as parse_html(), but pulls the HTML to parse, from the named file.

Returns undef if the file could not be opened, or $obj otherwise.

When a HTML::TreeBuilder object is created, the following variables control how parsing takes place:

$HTML::Parse::IMPLICIT_TAGS

Setting this variable to true will instruct the parser to try to deduce implicit elements and implicit end tags. If this variable is false you get a parse tree that just reflects the text as it stands. Might be useful for quick & dirty parsing. Default is true.

Implicit elements have the implicit() attribute set.

$HTML::Parse::IGNORE_UNKNOWN

This variable contols whether unknow tags should be represented as elements in the parse tree. Default is true.

$HTML::Parse::IGNORE_TEXT

Do not represent the text content of elements. This saves space if all you want is to examine the structure of the document. Default is false.

$HTML::Parse::WARN

Call warn() with an apropriate message for syntax errors. Default is false.

REMEMBER!

HTML::TreeBuilder objects should be explicitly destroyed when you're finished with them. See the HTML::TreeBuilder manpage.

SEE ALSO

the HTML::Parser manpage, the HTML::TreeBuilder manpage, the HTML::Element manpage

COPYRIGHT

Copyright 1995-1998 Gisle Aas. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Maintained by Andy Lester andy at petdance.com. Originally by Gisle Aas <gisle@aas.no> and Sean M. Burke <sburke@cpan.org>.


HTML::Parser - HTML parser class

  • METHODS
    • Argspec
    • Events
    • Unicode
  • VERSION 2 COMPATIBILITY
  • SUBCLASSING
  • EXAMPLES
  • BUGS
  • DIAGNOSTICS
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::Parser - HTML parser class

SYNOPSIS

 use HTML::Parser ();

 # Create parser object
 $p = HTML::Parser->new( api_version => 3,
                         start_h => [\&start, "tagname, attr"],
                         end_h   => [\&end,   "tagname"],
                         marked_sections => 1,
                       );

 # Parse document text chunk by chunk
 $p->parse($chunk1);
 $p->parse($chunk2);
 #...
 $p->eof;                 # signal end of document

 # Parse directly from file
 $p->parse_file("foo.html");
 # or
 open(my $fh, "<:utf8", "foo.html") || die;
 $p->parse_file($fh);

DESCRIPTION

Objects of the HTML::Parser class will recognize markup and separate it from plain text (alias data content) in HTML documents. As different kinds of markup and text are recognized, the corresponding event handlers are invoked.

HTML::Parser is not a generic SGML parser. We have tried to make it able to deal with the HTML that is actually "out there", and it normally parses as closely as possible to the way the popular web browsers do it instead of strictly following one of the many HTML specifications from W3C. Where there is disagreement, there is often an option that you can enable to get the official behaviour.

The document to be parsed may be supplied in arbitrary chunks. This makes on-the-fly parsing as documents are received from the network possible.

If event driven parsing does not feel right for your application, you might want to use HTML::PullParser. This is an HTML::Parser subclass that allows a more conventional program structure.

METHODS

The following method is used to construct a new HTML::Parser object:

$p = HTML::Parser->new( %options_and_handlers )

This class method creates a new HTML::Parser object and returns it. Key/value argument pairs may be provided to assign event handlers or initialize parser options. The handlers and parser options can also be set or modified later by the method calls described below.

If a top level key is in the form "<event>_h" (e.g., "text_h") then it assigns a handler to that event, otherwise it initializes a parser option. The event handler specification value must be an array reference. Multiple handlers may also be assigned with the 'handlers => [%handlers]' option. See examples below.

If new() is called without any arguments, it will create a parser that uses callback methods compatible with version 2 of HTML::Parser. See the section on "version 2 compatibility" below for details.

The special constructor option 'api_version => 2' can be used to initialize version 2 callbacks while still setting other options and handlers. The 'api_version => 3' option can be used if you don't want to set any options and don't want to fall back to v2 compatible mode.

Examples:

 $p = HTML::Parser->new(api_version => 3,
                        text_h => [ sub {...}, "dtext" ]);

This creates a new parser object with a text event handler subroutine that receives the original text with general entities decoded.

 $p = HTML::Parser->new(api_version => 3,
                        start_h => [ 'my_start', "self,tokens" ]);

This creates a new parser object with a start event handler method that receives the $p and the tokens array.

 $p = HTML::Parser->new(api_version => 3,
                        handlers => { text => [\@array, "event,text"],
                                      comment => [\@array, "event,text"],
                                    });

This creates a new parser object that stores the event type and the original text in @array for text and comment events.

The following methods feed the HTML document to the HTML::Parser object:

$p->parse( $string )

Parse $string as the next chunk of the HTML document. The return value is normally a reference to the parser object (i.e. $p). Handlers invoked should not attempt to modify the $string in-place until $p->parse returns.

If an invoked event handler aborts parsing by calling $p->eof, then $p->parse() will return a FALSE value.

$p->parse( $code_ref )

If a code reference is passed as the argument to be parsed, then the chunks to be parsed are obtained by invoking this function repeatedly. Parsing continues until the function returns an empty (or undefined) result. When this happens $p->eof is automatically signaled.

Parsing will also abort if one of the event handlers calls $p->eof.

The effect of this is the same as:

 while (1) {
    my $chunk = &$code_ref();
    if (!defined($chunk) || !length($chunk)) {
        $p->eof;
        return $p;
    }
    $p->parse($chunk) || return undef;
 }

But it is more efficient as this loop runs internally in XS code.

$p->parse_file( $file )

Parse text directly from a file. The $file argument can be a filename, an open file handle, or a reference to an open file handle.

If $file contains a filename and the file can't be opened, then the method returns an undefined value and $! tells why it failed. Otherwise the return value is a reference to the parser object.

If a file handle is passed as the $file argument, then the file will normally be read until EOF, but not closed.

If an invoked event handler aborts parsing by calling $p->eof, then $p->parse_file() may not have read the entire file.

On systems with multi-byte line terminators, the values passed for the offset and length argspecs may be too low if parse_file() is called on a file handle that is not in binary mode.

If a filename is passed in, then parse_file() will open the file in binary mode.

$p->eof

Signals the end of the HTML document. Calling the $p->eof method outside a handler callback will flush any remaining buffered text (which triggers the text event if there is any remaining text).

Calling $p->eof inside a handler will terminate parsing at that point and cause $p->parse to return a FALSE value. This also terminates parsing by $p->parse_file().

After $p->eof has been called, the parse() and parse_file() methods can be invoked to feed new documents with the parser object.

The return value from eof() is a reference to the parser object.

Most parser options are controlled by boolean attributes. Each boolean attribute is enabled by calling the corresponding method with a TRUE argument and disabled with a FALSE argument. The attribute value is left unchanged if no argument is given. The return value from each method is the old attribute value.

Methods that can be used to get and/or set parser options are:

$p->attr_encoded
$p->attr_encoded( $bool )

By default, the attr and @attr argspecs will have general entities for attribute values decoded. Enabling this attribute leaves entities alone.

$p->boolean_attribute_value( $val )

This method sets the value reported for boolean attributes inside HTML start tags. By default, the name of the attribute is also used as its value. This affects the values reported for tokens and attr argspecs.

$p->case_sensitive
$p->case_sensitive( $bool )

By default, tagnames and attribute names are down-cased. Enabling this attribute leaves them as found in the HTML source document.

$p->closing_plaintext
$p->closing_plaintext( $bool )

By default, "plaintext" element can never be closed. Everything up to the end of the document is parsed in CDATA mode. This historical behaviour is what at least MSIE does. Enabling this attribute makes closing "</plaintext>" tag effective and the parsing process will resume after seeing this tag. This emulates gecko-based browsers.

$p->empty_element_tags
$p->empty_element_tags( $bool )

By default, empty element tags are not recognized as such and the "/" before ">" is just treated like a normal name character (unless strict_names is enabled). Enabling this attribute make HTML::Parser recognize these tags.

Empty element tags look like start tags, but end with the character sequence "/>" instead of ">". When recognized by HTML::Parser they cause an artificial end event in addition to the start event. The text for the artificial end event will be empty and the tokenpos array will be undefined even though the the token array will have one element containing the tag name.

$p->marked_sections
$p->marked_sections( $bool )

By default, section markings like <![CDATA[...]]> are treated like ordinary text. When this attribute is enabled section markings are honoured.

There are currently no events associated with the marked section markup, but the text can be returned as skipped_text.

$p->strict_comment
$p->strict_comment( $bool )

By default, comments are terminated by the first occurrence of "-->". This is the behaviour of most popular browsers (like Mozilla, Opera and MSIE), but it is not correct according to the official HTML standard. Officially, you need an even number of "--" tokens before the closing ">" is recognized and there may not be anything but whitespace between an even and an odd "--".

The official behaviour is enabled by enabling this attribute.

Enabling of 'strict_comment' also disables recognizing these forms as comments:

  </ comment>
  <! comment>
$p->strict_end
$p->strict_end( $bool )

By default, attributes and other junk are allowed to be present on end tags in a manner that emulates MSIE's behaviour.

The official behaviour is enabled with this attribute. If enabled, only whitespace is allowed between the tagname and the final ">".

$p->strict_names
$p->strict_names( $bool )

By default, almost anything is allowed in tag and attribute names. This is the behaviour of most popular browsers and allows us to parse some broken tags with invalid attribute values like:

   <IMG SRC=newprevlstGr.gif ALT=[PREV LIST] BORDER=0>

By default, "LIST]" is parsed as a boolean attribute, not as part of the ALT value as was clearly intended. This is also what Mozilla sees.

The official behaviour is enabled by enabling this attribute. If enabled, it will cause the tag above to be reported as text since "LIST]" is not a legal attribute name.

$p->unbroken_text
$p->unbroken_text( $bool )

By default, blocks of text are given to the text handler as soon as possible (but the parser takes care always to break text at a boundary between whitespace and non-whitespace so single words and entities can always be decoded safely). This might create breaks that make it hard to do transformations on the text. When this attribute is enabled, blocks of text are always reported in one piece. This will delay the text event until the following (non-text) event has been recognized by the parser.

Note that the offset argspec will give you the offset of the first segment of text and length is the combined length of the segments. Since there might be ignored tags in between, these numbers can't be used to directly index in the original document file.

$p->utf8_mode
$p->utf8_mode( $bool )

Enable this option when parsing raw undecoded UTF-8. This tells the parser that the entities expanded for strings reported by attr, @attr and dtext should be expanded as decoded UTF-8 so they end up compatible with the surrounding text.

If utf8_mode is enabled then it is an error to pass strings containing characters with code above 255 to the parse() method, and the parse() method will croak if you try.

Example: The Unicode character "\x{2665}" is "\xE2\x99\xA5" when UTF-8 encoded. The character can also be represented by the entity "&hearts;" or "&#x2665". If we feed the parser:

  $p->parse("\xE2\x99\xA5&hearts;");

then dtext will be reported as "\xE2\x99\xA5\x{2665}" without utf8_mode enabled, but as "\xE2\x99\xA5\xE2\x99\xA5" when enabled. The later string is what you want.

This option is only available with perl-5.8 or better.

$p->xml_mode
$p->xml_mode( $bool )

Enabling this attribute changes the parser to allow some XML constructs. This enables the behaviour controlled by individually by the case_sensitive, empty_element_tags, strict_names and xml_pic attributes and also suppresses special treatment of elements that are parsed as CDATA for HTML.

$p->xml_pic
$p->xml_pic( $bool )

By default, processing instructions are terminated by ">". When this attribute is enabled, processing instructions are terminated by "?>" instead.

As markup and text is recognized, handlers are invoked. The following method is used to set up handlers for different events:

$p->handler( event => \&subroutine, $argspec )
$p->handler( event => $method_name, $argspec )
$p->handler( event => \@accum, $argspec )
$p->handler( event => "" );
$p->handler( event => undef );
$p->handler( event );

This method assigns a subroutine, method, or array to handle an event.

Event is one of text, start, end, declaration, comment, process, start_document, end_document or default.

The \&subroutine is a reference to a subroutine which is called to handle the event.

The $method_name is the name of a method of $p which is called to handle the event.

The @accum is an array that will hold the event information as sub-arrays.

If the second argument is "", the event is ignored. If it is undef, the default handler is invoked for the event.

The $argspec is a string that describes the information to be reported for the event. Any requested information that does not apply to a specific event is passed as undef. If argspec is omitted, then it is left unchanged.

The return value from $p->handler is the old callback routine or a reference to the accumulator array.

Any return values from handler callback routines/methods are always ignored. A handler callback can request parsing to be aborted by invoking the $p->eof method. A handler callback is not allowed to invoke the $p->parse() or $p->parse_file() method. An exception will be raised if it tries.

Examples:

    $p->handler(start =>  "start", 'self, attr, attrseq, text' );

This causes the "start" method of object $p to be called for 'start' events. The callback signature is $p->start(\%attr, \@attr_seq, $text).

    $p->handler(start =>  \&start, 'attr, attrseq, text' );

This causes subroutine start() to be called for 'start' events. The callback signature is start(\%attr, \@attr_seq, $text).

    $p->handler(start =>  \@accum, '"S", attr, attrseq, text' );

This causes 'start' event information to be saved in @accum. The array elements will be ['S', \%attr, \@attr_seq, $text].

   $p->handler(start => "");

This causes 'start' events to be ignored. It also suppresses invocations of any default handler for start events. It is in most cases equivalent to $p->handler(start => sub {}), but is more efficient. It is different from the empty-sub-handler in that skipped_text is not reset by it.

   $p->handler(start => undef);

This causes no handler to be associated with start events. If there is a default handler it will be invoked.

Filters based on tags can be set up to limit the number of events reported. The main bottleneck during parsing is often the huge number of callbacks made from the parser. Applying filters can improve performance significantly.

The following methods control filters:

$p->ignore_elements( @tags )

Both the start event and the end event as well as any events that would be reported in between are suppressed. The ignored elements can contain nested occurrences of itself. Example:

   $p->ignore_elements(qw(script style));

The script and style tags will always nest properly since their content is parsed in CDATA mode. For most other tags ignore_elements must be used with caution since HTML is often not well formed.

$p->ignore_tags( @tags )

Any start and end events involving any of the tags given are suppressed. To reset the filter (i.e. don't suppress any start and end events), call ignore_tags without an argument.

$p->report_tags( @tags )

Any start and end events involving any of the tags not given are suppressed. To reset the filter (i.e. report all start and end events), call report_tags without an argument.

Internally, the system has two filter lists, one for report_tags and one for ignore_tags, and both filters are applied. This effectively gives ignore_tags precedence over report_tags.

Examples:

   $p->ignore_tags(qw(style));
   $p->report_tags(qw(script style));

results in only script events being reported.

Argspec

Argspec is a string containing a comma-separated list that describes the information reported by the event. The following argspec identifier names can be used:

attr

Attr causes a reference to a hash of attribute name/value pairs to be passed.

Boolean attributes' values are either the value set by $p->boolean_attribute_value, or the attribute name if no value has been set by $p->boolean_attribute_value.

This passes undef except for start events.

Unless xml_mode or case_sensitive is enabled, the attribute names are forced to lower case.

General entities are decoded in the attribute values and one layer of matching quotes enclosing the attribute values is removed.

The Unicode character set is assumed for entity decoding. With Perl version 5.6 or earlier only the Latin-1 range is supported, and entities for characters outside the range 0..255 are left unchanged.

@attr

Basically the same as attr, but keys and values are passed as individual arguments and the original sequence of the attributes is kept. The parameters passed will be the same as the @attr calculated here:

   @attr = map { $_ => $attr->{$_} } @$attrseq;

assuming $attr and $attrseq here are the hash and array passed as the result of attr and attrseq argspecs.

This passes no values for events besides start.

attrseq

Attrseq causes a reference to an array of attribute names to be passed. This can be useful if you want to walk the attr hash in the original sequence.

This passes undef except for start events.

Unless xml_mode or case_sensitive is enabled, the attribute names are forced to lower case.

column

Column causes the column number of the start of the event to be passed. The first column on a line is 0.

dtext

Dtext causes the decoded text to be passed. General entities are automatically decoded unless the event was inside a CDATA section or was between literal start and end tags (script, style, xmp, and plaintext).

The Unicode character set is assumed for entity decoding. With Perl version 5.6 or earlier only the Latin-1 range is supported, and entities for characters outside the range 0..255 are left unchanged.

This passes undef except for text events.

event

Event causes the event name to be passed.

The event name is one of text, start, end, declaration, comment, process, start_document or end_document.

is_cdata

Is_cdata causes a TRUE value to be passed if the event is inside a CDATA section or between literal start and end tags (script, style, xmp, and plaintext).

if the flag is FALSE for a text event, then you should normally either use dtext or decode the entities yourself before the text is processed further.

length

Length causes the number of bytes of the source text of the event to be passed.

line

Line causes the line number of the start of the event to be passed. The first line in the document is 1. Line counting doesn't start until at least one handler requests this value to be reported.

offset

Offset causes the byte position in the HTML document of the start of the event to be passed. The first byte in the document has offset 0.

offset_end

Offset_end causes the byte position in the HTML document of the end of the event to be passed. This is the same as offset + length.

self

Self causes the current object to be passed to the handler. If the handler is a method, this must be the first element in the argspec.

An alternative to passing self as an argspec is to register closures that capture $self by themselves as handlers. Unfortunately this creates circular references which prevent the HTML::Parser object from being garbage collected. Using the self argspec avoids this problem.

skipped_text

Skipped_text returns the concatenated text of all the events that have been skipped since the last time an event was reported. Events might be skipped because no handler is registered for them or because some filter applies. Skipped text also includes marked section markup, since there are no events that can catch it.

If an ""-handler is registered for an event, then the text for this event is not included in skipped_text. Skipped text both before and after the ""-event is included in the next reported skipped_text.

tag

Same as tagname, but prefixed with "/" if it belongs to an end event and "!" for a declaration. The tag does not have any prefix for start events, and is in this case identical to tagname.

tagname

This is the element name (or generic identifier in SGML jargon) for start and end tags. Since HTML is case insensitive, this name is forced to lower case to ease string matching.

Since XML is case sensitive, the tagname case is not changed when xml_mode is enabled. The same happens if the case_sensitive attribute is set.

The declaration type of declaration elements is also passed as a tagname, even if that is a bit strange. In fact, in the current implementation tagname is identical to token0 except that the name may be forced to lower case.

token0

Token0 causes the original text of the first token string to be passed. This should always be the same as $tokens->[0].

For declaration events, this is the declaration type.

For start and end events, this is the tag name.

For process and non-strict comment events, this is everything inside the tag.

This passes undef if there are no tokens in the event.

tokenpos

Tokenpos causes a reference to an array of token positions to be passed. For each string that appears in tokens, this array contains two numbers. The first number is the offset of the start of the token in the original text and the second number is the length of the token.

Boolean attributes in a start event will have (0,0) for the attribute value offset and length.

This passes undef if there are no tokens in the event (e.g., text) and for artificial end events triggered by empty element tags.

If you are using these offsets and lengths to modify text, you should either work from right to left, or be very careful to calculate the changes to the offsets.

tokens

Tokens causes a reference to an array of token strings to be passed. The strings are exactly as they were found in the original text, no decoding or case changes are applied.

For declaration events, the array contains each word, comment, and delimited string starting with the declaration type.

For comment events, this contains each sub-comment. If $p->strict_comments is disabled, there will be only one sub-comment.

For start events, this contains the original tag name followed by the attribute name/value pairs. The values of boolean attributes will be either the value set by $p->boolean_attribute_value, or the attribute name if no value has been set by $p->boolean_attribute_value.

For end events, this contains the original tag name (always one token).

For process events, this contains the process instructions (always one token).

This passes undef for text events.

text

Text causes the source text (including markup element delimiters) to be passed.

undef

Pass an undefined value. Useful as padding where the same handler routine is registered for multiple events.

'...'

A literal string of 0 to 255 characters enclosed in single (') or double (") quotes is passed as entered.

The whole argspec string can be wrapped up in '@{...}' to signal that the resulting event array should be flattened. This only makes a difference if an array reference is used as the handler target. Consider this example:

   $p->handler(text => [], 'text');
   $p->handler(text => [], '@{text}']);

With two text events; "foo", "bar"; then the first example will end up with [["foo"], ["bar"]] and the second with ["foo", "bar"] in the handler target array.

Events

Handlers for the following events can be registered:

comment

This event is triggered when a markup comment is recognized.

Example:

  <!-- This is a comment -- -- So is this -->
declaration

This event is triggered when a markup declaration is recognized.

For typical HTML documents, the only declaration you are likely to find is <!DOCTYPE ...>.

Example:

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html40/strict.dtd">

DTDs inside <!DOCTYPE ...> will confuse HTML::Parser.

default

This event is triggered for events that do not have a specific handler. You can set up a handler for this event to catch stuff you did not want to catch explicitly.

end

This event is triggered when an end tag is recognized.

Example:

  </A>
end_document

This event is triggered when $p->eof is called and after any remaining text is flushed. There is no document text associated with this event.

process

This event is triggered when a processing instructions markup is recognized.

The format and content of processing instructions are system and application dependent.

Examples:

  <? HTML processing instructions >
  <? XML processing instructions ?>
start

This event is triggered when a start tag is recognized.

Example:

  <A HREF="http://www.perl.com/">
start_document

This event is triggered before any other events for a new document. A handler for it can be used to initialize stuff. There is no document text associated with this event.

text

This event is triggered when plain text (characters) is recognized. The text may contain multiple lines. A sequence of text may be broken between several text events unless $p->unbroken_text is enabled.

The parser will make sure that it does not break a word or a sequence of whitespace between two text events.

Unicode

The HTML::Parser can parse Unicode strings when running under perl-5.8 or better. If Unicode is passed to $p->parse() then chunks of Unicode will be reported to the handlers. The offset and length argspecs will also report their position in terms of characters.

It is safe to parse raw undecoded UTF-8 if you either avoid decoding entities and make sure to not use argspecs that do, or enable the utf8_mode for the parser. Parsing of undecoded UTF-8 might be useful when parsing from a file where you need the reported offsets and lengths to match the byte offsets in the file.

If a filename is passed to $p->parse_file() then the file will be read in binary mode. This will be fine if the file contains only ASCII or Latin-1 characters. If the file contains UTF-8 encoded text then care must be taken when decoding entities as described in the previous paragraph, but better is to open the file with the UTF-8 layer so that it is decoded properly:

   open(my $fh, "<:utf8", "index.html") || die "...: $!";
   $p->parse_file($fh);

If the file contains text encoded in a charset besides ASCII, Latin-1 or UTF-8 then decoding will always be needed.

VERSION 2 COMPATIBILITY

When an HTML::Parser object is constructed with no arguments, a set of handlers is automatically provided that is compatible with the old HTML::Parser version 2 callback methods.

This is equivalent to the following method calls:

   $p->handler(start   => "start",   "self, tagname, attr, attrseq, text");
   $p->handler(end     => "end",     "self, tagname, text");
   $p->handler(text    => "text",    "self, text, is_cdata");
   $p->handler(process => "process", "self, token0, text");
   $p->handler(comment =>
             sub {
                 my($self, $tokens) = @_;
                 for (@$tokens) {$self->comment($_);}},
             "self, tokens");
   $p->handler(declaration =>
             sub {
                 my $self = shift;
                 $self->declaration(substr($_[0], 2, -1));},
             "self, text");

Setting up these handlers can also be requested with the "api_version => 2" constructor option.

SUBCLASSING

The HTML::Parser class is subclassable. Parser objects are plain hashes and HTML::Parser reserves only hash keys that start with "_hparser". The parser state can be set up by invoking the init() method, which takes the same arguments as new().

EXAMPLES

The first simple example shows how you might strip out comments from an HTML document. We achieve this by setting up a comment handler that does nothing and a default handler that will print out anything else:

  use HTML::Parser;
  HTML::Parser->new(default_h => [sub { print shift }, 'text'],
                    comment_h => [""],
                   )->parse_file(shift || die) || die $!;

An alternative implementation is:

  use HTML::Parser;
  HTML::Parser->new(end_document_h => [sub { print shift },
                                       'skipped_text'],
                    comment_h      => [""],
                   )->parse_file(shift || die) || die $!;

This will in most cases be much more efficient since only a single callback will be made.

The next example prints out the text that is inside the <title> element of an HTML document. Here we start by setting up a start handler. When it sees the title start tag it enables a text handler that prints any text found and an end handler that will terminate parsing as soon as the title end tag is seen:

  use HTML::Parser ();

  sub start_handler
  {
    return if shift ne "title";
    my $self = shift;
    $self->handler(text => sub { print shift }, "dtext");
    $self->handler(end  => sub { shift->eof if shift eq "title"; },
                           "tagname,self");
  }

  my $p = HTML::Parser->new(api_version => 3);
  $p->handler( start => \&start_handler, "tagname,self");
  $p->parse_file(shift || die) || die $!;
  print "\n";

More examples are found in the eg/ directory of the HTML-Parser distribution: the program hrefsub shows how you can edit all links found in a document; the program htextsub shows how to edit the text only; the program hstrip shows how you can strip out certain tags/elements and/or attributes; and the program htext show how to obtain the plain text, but not any script/style content.

You can browse the eg/ directory online from the [Browse] link on the http://search.cpan.org/~gaas/HTML-Parser/ page.

BUGS

The <style> and <script> sections do not end with the first "</", but need the complete corresponding end tag. The standard behaviour is not really practical.

When the strict_comment option is enabled, we still recognize comments where there is something other than whitespace between even and odd "--" markers.

Once $p->boolean_attribute_value has been set, there is no way to restore the default behaviour.

There is currently no way to get both quote characters into the same literal argspec.

Empty tags, e.g. "<>" and "</>", are not recognized. SGML allows them to repeat the previous start tag or close the previous start tag respectively.

NET tags, e.g. "code/.../" are not recognized. This is SGML shorthand for "<code>...</code>".

Unclosed start or end tags, e.g. "<tt<b>...</b</tt>" are not recognized.

DIAGNOSTICS

The following messages may be produced by HTML::Parser. The notation in this listing is the same as used in the perldiag manpage:

Not a reference to a hash

(F) The object blessed into or subclassed from HTML::Parser is not a hash as required by the HTML::Parser methods.

Bad signature in parser state object at %p

(F) The _hparser_xs_state element does not refer to a valid state structure. Something must have changed the internal value stored in this hash element, or the memory has been overwritten.

_hparser_xs_state element is not a reference

(F) The _hparser_xs_state element has been destroyed.

Can't find '_hparser_xs_state' element in HTML::Parser hash

(F) The _hparser_xs_state element is missing from the parser hash. It was either deleted, or not created when the object was created.

API version %s not supported by HTML::Parser %s

(F) The constructor option 'api_version' with an argument greater than or equal to 4 is reserved for future extensions.

Bad constructor option '%s'

(F) An unknown constructor option key was passed to the new() or init() methods.

Parse loop not allowed

(F) A handler invoked the parse() or parse_file() method. This is not permitted.

marked sections not supported

(F) The $p->marked_sections() method was invoked in a HTML::Parser module that was compiled without support for marked sections.

Unknown boolean attribute (%d)

(F) Something is wrong with the internal logic that set up aliases for boolean attributes.

Only code or array references allowed as handler

(F) The second argument for $p->handler must be either a subroutine reference, then name of a subroutine or method, or a reference to an array.

No handler for %s events

(F) The first argument to $p->handler must be a valid event name; i.e. one of "start", "end", "text", "process", "declaration" or "comment".

Unrecognized identifier %s in argspec

(F) The identifier is not a known argspec name. Use one of the names mentioned in the argspec section above.

Literal string is longer than 255 chars in argspec

(F) The current implementation limits the length of literals in an argspec to 255 characters. Make the literal shorter.

Backslash reserved for literal string in argspec

(F) The backslash character "\" is not allowed in argspec literals. It is reserved to permit quoting inside a literal in a later version.

Unterminated literal string in argspec

(F) The terminating quote character for a literal was not found.

Bad argspec (%s)

(F) Only identifier names, literals, spaces and commas are allowed in argspecs.

Missing comma separator in argspec

(F) Identifiers in an argspec must be separated with ",".

Parsing of undecoded UTF-8 will give garbage when decoding entities

(W) The first chunk parsed appears to contain undecoded UTF-8 and one or more argspecs that decode entities are used for the callback handlers.

The result of decoding will be a mix of encoded and decoded characters for any entities that expand to characters with code above 127. This is not a good thing.

The solution is to use the Encode::encode_utf8() on the data before feeding it to the $p->parse(). For $p->parse_file() pass a file that has been opened in ":utf8" mode.

The parser can process raw undecoded UTF-8 sanely if the utf8_mode is enabled or if the "attr", "@attr" or "dtext" argspecs is avoided.

Parsing string decoded with wrong endianess

(W) The first character in the document is U+FFFE. This is not a legal Unicode character but a byte swapped BOM. The result of parsing will likely be garbage.

Parsing of undecoded UTF-32

(W) The parser found the Unicode UTF-32 BOM signature at the start of the document. The result of parsing will likely be garbage.

Parsing of undecoded UTF-16

(W) The parser found the Unicode UTF-16 BOM signature at the start of the document. The result of parsing will likely be garbage.

SEE ALSO

the HTML::Entities manpage, the HTML::PullParser manpage, the HTML::TokeParser manpage, the HTML::HeadParser manpage, the HTML::LinkExtor manpage, the HTML::Form manpage

the HTML::TreeBuilder manpage (part of the HTML-Tree distribution)

http://www.w3.org/TR/html4

More information about marked sections and processing instructions may be found at http://www.sgml.u-net.com/book/sgml-8.htm.

COPYRIGHT

 Copyright 1996-2007 Gisle Aas. All rights reserved.
 Copyright 1999-2000 Michael A. Chase.  All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::PullParser - Alternative HTML::Parser interface

  • EXAMPLES
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::PullParser - Alternative HTML::Parser interface

SYNOPSIS

 use HTML::PullParser;

 $p = HTML::PullParser->new(file => "index.html",
                            start => 'event, tagname, @attr',
                            end   => 'event, tagname',
                            ignore_elements => [qw(script style)],
                           ) || die "Can't open: $!";
 while (my $token = $p->get_token) {
     #...do something with $token
 }

DESCRIPTION

The HTML::PullParser is an alternative interface to the HTML::Parser class. It basically turns the HTML::Parser inside out. You associate a file (or any IO::Handle object or string) with the parser at construction time and then repeatedly call $parser->get_token to obtain the tags and text found in the parsed document.

The following methods are provided:

$p = HTML::PullParser->new( file => $file, %options )
$p = HTML::PullParser->new( doc => \$doc, %options )

A HTML::PullParser can be made to parse from either a file or a literal document based on whether the file or doc option is passed to the parser's constructor.

The file passed in can either be a file name or a file handle object. If a file name is passed, and it can't be opened for reading, then the constructor will return an undefined value and $! will tell you why it failed. Otherwise the argument is taken to be some object that the HTML::PullParser can read() from when it needs more data. The stream will be read() until EOF, but not closed.

A doc can be passed plain or as a reference to a scalar. If a reference is passed then the value of this scalar should not be changed before all tokens have been extracted.

Next the information to be returned for the different token types must be set up. This is done by simply associating an argspec (as defined in the HTML::Parser manpage) with the events you have an interest in. For instance, if you want start tokens to be reported as the string 'S' followed by the tagname and the attributes you might pass an start-option like this:

   $p = HTML::PullParser->new(
          doc   => $document_to_parse,
          start => '"S", tagname, @attr',
          end   => '"E", tagname',
        );

At last other HTML::Parser options, like ignore_tags, and unbroken_text, can be passed in. Note that you should not use the event_h options to set up parser handlers. That would confuse the inner logic of HTML::PullParser.

$token = $p->get_token

This method will return the next token found in the HTML document, or undef at the end of the document. The token is returned as an array reference. The content of this array match the argspec set up during HTML::PullParser construction.

$p->unget_token( @tokens )

If you find out you have read too many tokens you can push them back, so that they are returned again the next time $p->get_token is called.

EXAMPLES

The 'eg/hform' script shows how we might parse the form section of HTML::Documents using HTML::PullParser.

SEE ALSO

the HTML::Parser manpage, the HTML::TokeParser manpage

COPYRIGHT

Copyright 1998-2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::Tagset - data tables useful in parsing HTML

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • VARIABLES
    • hashset %HTML::Tagset::emptyElement
    • hashset %HTML::Tagset::optionalEndTag
    • hash %HTML::Tagset::linkElements
    • hash %HTML::Tagset::boolean_attr
    • hashset %HTML::Tagset::isPhraseMarkup
    • hashset %HTML::Tagset::is_Possible_Strict_P_Content
    • hashset %HTML::Tagset::isHeadElement
    • hashset %HTML::Tagset::isList
    • hashset %HTML::Tagset::isTableElement
    • hashset %HTML::Tagset::isFormElement
    • hashset %HTML::Tagset::isBodyMarkup
    • hashset %HTML::Tagset::isHeadOrBodyElement
    • hashset %HTML::Tagset::isKnown
    • hashset %HTML::Tagset::canTighten
    • array @HTML::Tagset::p_closure_barriers
    • hashset %isCDATA_Parent
  • CAVEATS
  • SEE ALSO
  • COPYRIGHT & LICENSE
  • ACKNOWLEDGEMENTS
  • AUTHOR
  • BUGS

NAME

HTML::Tagset - data tables useful in parsing HTML

VERSION

Version 3.10

SYNOPSIS

  use HTML::Tagset;
  # Then use any of the items in the HTML::Tagset package
  #  as need arises

DESCRIPTION

This module contains several data tables useful in various kinds of HTML parsing operations.

Note that all tag names used are lowercase.

In the following documentation, a "hashset" is a hash being used as a set -- the hash conveys that its keys are there, and the actual values associated with the keys are not significant. (But what values are there, are always true.)

VARIABLES

Note that none of these variables are exported.

hashset %HTML::Tagset::emptyElement

This hashset has as values the tag-names (GIs) of elements that cannot have content. (For example, "base", "br", "hr".) So $HTML::Tagset::emptyElement{'hr'} exists and is true. $HTML::Tagset::emptyElement{'dl'} does not exist, and so is not true.

hashset %HTML::Tagset::optionalEndTag

This hashset lists tag-names for elements that can have content, but whose end-tags are generally, "safely", omissible. Example: $HTML::Tagset::emptyElement{'li'} exists and is true.

hash %HTML::Tagset::linkElements

Values in this hash are tagnames for elements that might contain links, and the value for each is a reference to an array of the names of attributes whose values can be links.

hash %HTML::Tagset::boolean_attr

This hash (not hashset) lists what attributes of what elements can be printed without showing the value (for example, the "noshade" attribute of "hr" elements). For elements with only one such attribute, its value is simply that attribute name. For elements with many such attributes, the value is a reference to a hashset containing all such attributes.

hashset %HTML::Tagset::isPhraseMarkup

This hashset contains all phrasal-level elements.

hashset %HTML::Tagset::is_Possible_Strict_P_Content

This hashset contains all phrasal-level elements that be content of a P element, for a strict model of HTML.

hashset %HTML::Tagset::isHeadElement

This hashset contains all elements that elements that should be present only in the 'head' element of an HTML document.

hashset %HTML::Tagset::isList

This hashset contains all elements that can contain "li" elements.

hashset %HTML::Tagset::isTableElement

This hashset contains all elements that are to be found only in/under a "table" element.

hashset %HTML::Tagset::isFormElement

This hashset contains all elements that are to be found only in/under a "form" element.

hashset %HTML::Tagset::isBodyMarkup

This hashset contains all elements that are to be found only in/under the "body" element of an HTML document.

hashset %HTML::Tagset::isHeadOrBodyElement

This hashset includes all elements that I notice can fall either in the head or in the body.

hashset %HTML::Tagset::isKnown

This hashset lists all known HTML elements.

hashset %HTML::Tagset::canTighten

This hashset lists elements that might have ignorable whitespace as children or siblings.

array @HTML::Tagset::p_closure_barriers

This array has a meaning that I have only seen a need for in HTML::TreeBuilder, but I include it here on the off chance that someone might find it of use:

When we see a "<p>" token, we go lookup up the lineage for a p element we might have to minimize. At first sight, we might say that if there's a p anywhere in the lineage of this new p, it should be closed. But that's wrong. Consider this document:

  <html>
    <head>
      <title>foo</title>
    </head>
    <body>
      <p>foo
        <table>
          <tr>
            <td>
               foo
               <p>bar
            </td>
          </tr>
        </table>
      </p>
    </body>
  </html>

The second p is quite legally inside a much higher p.

My formalization of the reason why this is legal, but this:

  <p>foo<p>bar</p></p>

isn't, is that something about the table constitutes a "barrier" to the application of the rule about what p must minimize.

So @HTML::Tagset::p_closure_barriers is the list of all such barrier-tags.

hashset %isCDATA_Parent

This hashset includes all elements whose content is CDATA.

CAVEATS

You may find it useful to alter the behavior of modules (like HTML::Element or HTML::TreeBuilder) that use HTML::Tagset's data tables by altering the data tables themselves. You are welcome to try, but be careful; and be aware that different modules may or may react differently to the data tables being changed.

Note that it may be inappropriate to use these tables for producing HTML -- for example, %isHeadOrBodyElement lists the tagnames for all elements that can appear either in the head or in the body, such as "script". That doesn't mean that I am saying your code that produces HTML should feel free to put script elements in either place! If you are producing programs that spit out HTML, you should be intimately familiar with the DTDs for HTML or XHTML (available at http://www.w3.org/), and you should slavishly obey them, not the data tables in this document.

SEE ALSO

the HTML::Element manpage, the HTML::TreeBuilder manpage, the HTML::LinkExtor manpage

COPYRIGHT & LICENSE

Copyright 1995-2000 Gisle Aas.

Copyright 2000-2005 Sean M. Burke.

Copyright 2005 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

Most of the code/data in this module was adapted from code written by Gisle Aas for HTML::Element, HTML::TreeBuilder, and HTML::LinkExtor. Then it was maintained by Sean M. Burke.

AUTHOR

Current maintainer: Andy Lester, <andy at petdance.com>

BUGS

Please report any bugs or feature requests to bug-html-tagset at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


HTML::TokeParser - Alternative HTML::Parser interface

  • EXAMPLES
  • SEE ALSO
  • COPYRIGHT

NAME

HTML::TokeParser - Alternative HTML::Parser interface

SYNOPSIS

 require HTML::TokeParser;
 $p = HTML::TokeParser->new("index.html") ||
      die "Can't open: $!";
 $p->empty_element_tags(1);  # configure its behaviour

 while (my $token = $p->get_token) {
     #...
 }

DESCRIPTION

The HTML::TokeParser is an alternative interface to the HTML::Parser class. It is an HTML::PullParser subclass with a predeclared set of token types. If you wish the tokens to be reported differently you probably want to use the HTML::PullParser directly.

The following methods are available:

$p = HTML::TokeParser->new( $filename, %opt );
$p = HTML::TokeParser->new( $filehandle, %opt );
$p = HTML::TokeParser->new( \$document, %opt );

The object constructor argument is either a file name, a file handle object, or the complete document to be parsed. Extra options can be provided as key/value pairs and are processed as documented by the base classes.

If the argument is a plain scalar, then it is taken as the name of a file to be opened and parsed. If the file can't be opened for reading, then the constructor will return undef and $! will tell you why it failed.

If the argument is a reference to a plain scalar, then this scalar is taken to be the literal document to parse. The value of this scalar should not be changed before all tokens have been extracted.

Otherwise the argument is taken to be some object that the HTML::TokeParser can read() from when it needs more data. Typically it will be a filehandle of some kind. The stream will be read() until EOF, but not closed.

A newly constructed HTML::TokeParser differ from its base classes by having the unbroken_text attribute enabled by default. See the HTML::Parser manpage for a description of this and other attributes that influence how the document is parsed. It is often a good idea to enable empty_element_tags behaviour.

Note that the parsing result will likely not be valid if raw undecoded UTF-8 is used as a source. When parsing UTF-8 encoded files turn on UTF-8 decoding:

   open(my $fh, "<:utf8", "index.html") || die "Can't open 'index.html': $!";
   my $p = HTML::TokeParser->new( $fh );
   # ...

If a $filename is passed to the constructor the file will be opened in raw mode and the parsing result will only be valid if its content is Latin-1 or pure ASCII.

If parsing from an UTF-8 encoded string buffer decode it first:

   utf8::decode($document);
   my $p = HTML::TokeParser->new( \$document );
   # ...
$p->get_token

This method will return the next token found in the HTML document, or undef at the end of the document. The token is returned as an array reference. The first element of the array will be a string denoting the type of this token: "S" for start tag, "E" for end tag, "T" for text, "C" for comment, "D" for declaration, and "PI" for process instructions. The rest of the token array depend on the type like this:

  ["S",  $tag, $attr, $attrseq, $text]
  ["E",  $tag, $text]
  ["T",  $text, $is_data]
  ["C",  $text]
  ["D",  $text]
  ["PI", $token0, $text]

where $attr is a hash reference, $attrseq is an array reference and the rest are plain scalars. The Argspec in the HTML::Parser manpage explains the details.

$p->unget_token( @tokens )

If you find you have read too many tokens you can push them back, so that they are returned the next time $p->get_token is called.

$p->get_tag
$p->get_tag( @tags )

This method returns the next start or end tag (skipping any other tokens), or undef if there are no more tags in the document. If one or more arguments are given, then we skip tokens until one of the specified tag types is found. For example:

   $p->get_tag("font", "/font");

will find the next start or end tag for a font-element.

The tag information is returned as an array reference in the same form as for $p->get_token above, but the type code (first element) is missing. A start tag will be returned like this:

  [$tag, $attr, $attrseq, $text]

The tagname of end tags are prefixed with "/", i.e. end tag is returned like this:

  ["/$tag", $text]
$p->get_text
$p->get_text( @endtags )

This method returns all text found at the current position. It will return a zero length string if the next token is not text. Any entities will be converted to their corresponding character.

If one or more arguments are given, then we return all text occurring before the first of the specified tags found. For example:

   $p->get_text("p", "br");

will return the text up to either a paragraph of linebreak element.

The text might span tags that should be textified. This is controlled by the $p->{textify} attribute, which is a hash that defines how certain tags can be treated as text. If the name of a start tag matches a key in this hash then this tag is converted to text. The hash value is used to specify which tag attribute to obtain the text from. If this tag attribute is missing, then the upper case name of the tag enclosed in brackets is returned, e.g. "[IMG]". The hash value can also be a subroutine reference. In this case the routine is called with the start tag token content as its argument and the return value is treated as the text.

The default $p->{textify} value is:

  {img => "alt", applet => "alt"}

This means that <IMG> and <APPLET> tags are treated as text, and that the text to substitute can be found in the ALT attribute.

$p->get_trimmed_text
$p->get_trimmed_text( @endtags )

Same as $p->get_text above, but will collapse any sequences of white space to a single space character. Leading and trailing white space is removed.

$p->get_phrase

This will return all text found at the current position ignoring any phrasal-level tags. Text is extracted until the first non phrasal-level tag. Textification of tags is the same as for get_text(). This method will collapse white space in the same way as get_trimmed_text() does.

The definition of <i>phrasal-level tags</i> is obtained from the HTML::Tagset module.

EXAMPLES

This example extracts all links from a document. It will print one line for each link, containing the URL and the textual description between the <A>...</A> tags:

  use HTML::TokeParser;
  $p = HTML::TokeParser->new(shift||"index.html");

  while (my $token = $p->get_tag("a")) {
      my $url = $token->[1]{href} || "-";
      my $text = $p->get_trimmed_text("/a");
      print "$url\t$text\n";
  }

This example extract the <TITLE> from the document:

  use HTML::TokeParser;
  $p = HTML::TokeParser->new(shift||"index.html");
  if ($p->get_tag("title")) {
      my $title = $p->get_trimmed_text;
      print "Title: $title\n";
  }

SEE ALSO

the HTML::PullParser manpage, the HTML::Parser manpage

COPYRIGHT

Copyright 1998-2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTML::Tree - overview of HTML::TreeBuilder et al

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • SUPPORT
  • SEE ALSO
  • SOURCE REPOSITORY
  • ACKNOWLEDGEMENTS
  • AUTHOR
  • COPYRIGHT

NAME

HTML::Tree - overview of HTML::TreeBuilder et al

VERSION

Version 3.20

SYNOPSIS

    use HTML::TreeBuilder;
    my $tree = HTML::TreeBuilder->new();
    $tree->parse_file($filename);

        # Then do something with the tree, using HTML::Element
        # methods -- for example:

    $tree->dump
        # Finally:

    $tree->delete;

DESCRIPTION

HTML-Tree is a suite of Perl modules for making parse trees out of HTML source. It consists of mainly two modules, whose documentation you should refer to: HTML::TreeBuilder and HTML::Element.

HTML::TreeBuilder is the module that builds the parse trees. (It uses HTML::Parser to do the work of breaking the HTML up into tokens.)

The tree that TreeBuilder builds for you is made up of objects of the class HTML::Element.

If you find that you do not properly understand the documentation for HTML::TreeBuilder and HTML::Element, it may be because you are unfamiliar with tree-shaped data structures, or with object-oriented modules in general. Sean Burke has written some articles for The Perl Journal (www.tpj.com) that seek to provide that background. The full text of those articles is contained in this distribution, as:

HTML::Tree::AboutObjects

"User's View of Object-Oriented Modules" from TPJ17.

HTML::Tree::AboutTrees

"Trees" from TPJ18

HTML::Tree::Scanning

"Scanning HTML" from TPJ19

Readers already familiar with object-oriented modules and tree-shaped data structures should read just the last article. Readers without that background should read the first, then the second, and then the third.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc HTML::Tree
    You can also look for information at:
  • AnnoCPAN: Annotated CPAN documentation

    http://annocpan.org/dist/HTML-Tree

  • CPAN Ratings

    http://cpanratings.perl.org/d/HTML-Tree

  • RT: CPAN's request tracker

    http://rt.cpan.org/NoAuth/Bugs.html

  • Search CPAN

    http://search.cpan.org/dist/HTML-Tree

SEE ALSO

the HTML::TreeBuilder manpage, the HTML::Element manpage, the HTML::Tagset manpage, the HTML::Parser manpage, the HTML::DOMbo manpage

The book Perl & LWP by Sean M. Burke published by O'Reilly and Associates, 2002. ISBN: 0-596-00178-9

It has several chapters to do with HTML processing in general, and HTML-Tree specifically. There's more info at:

    http://www.oreilly.com/catalog/perllwp/
    http://www.amazon.com/exec/obidos/ASIN/0596001789

SOURCE REPOSITORY

HTML::Tree is maintained in Subversion hosted at perl.org.

    http://svn.perl.org/modules/HTML-Tree

The latest development work is always at:

    http://svn.perl.org/modules/HTML-Tree/trunk

Any patches sent should be diffed against this repository.

ACKNOWLEDGEMENTS

Thanks to Gisle Aas and Sean Burke for their original work. Thanks to Chicago Perl Mongers (http://chicago.pm.org) for their patches submitted to HTML::Tree as part of the Phalanx project (http://qa.perl.org/phalanx). Thanks to Terrence Brannon for additional patches.

AUTHOR

Original HTML-Tree author Gisle Aas. Handed off to Sean M. Burke. Currently maintained by Andy Lester <andy at petdance.com>.

COPYRIGHT

Copyright 1995-1998 Gisle Aas; copyright 1999-2002 Sean M. Burke. (Except the articles contained in HTML::Tree::AboutObjects, HTML::Tree::AboutTrees, and HTML::Tree::Scanning, which are all copyright 2000 The Perl Journal.)

Except for those three TPJ articles, the whole HTML-Tree distribution, of which this file is a part, is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Those three TPJ articles may be distributed under the same terms as Perl itself.

The programs and documentation in this dist are distributed in the hope that they will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.


HTML::Tree::AboutObjects -- article: "User's View of Object-Oriented Modules"

  • A User's View of Object-Oriented Modules
    • Modules and Their Functional Interfaces
    • Modules with Object-Oriented Interfaces
    • What Can You Do with Objects?
    • What's in an Object?
    • What is an Object Value?
    • So Why Do Some Modules Use Objects?
    • [Author Credit]
    • The Gory Details
  • BACK

NAME

HTML::Tree::AboutObjects -- article: "User's View of Object-Oriented Modules"

SYNOPSIS

  # This an article, not a module.

DESCRIPTION

The following article by Sean M. Burke first appeared in The Perl Journal #17 and is copyright 2000 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.

A User's View of Object-Oriented Modules

-- Sean M. Burke

The first time that most Perl programmers run into object-oriented programming when they need to use a module whose interface is object-oriented. This is often a mystifying experience, since talk of "methods" and "constructors" is unintelligible to programmers who thought that functions and variables was all there was to worry about.

Articles and books that explain object-oriented programming (OOP), do so in terms of how to program that way. That's understandable, and if you learn to write object-oriented code of your own, you'd find it easy to use object-oriented code that others write. But this approach is the long way around for people whose immediate goal is just to use existing object-oriented modules, but who don't yet want to know all the gory details of having to write such modules for themselves.

This article is for those programmers -- programmers who want to know about objects from the perspective of using object-oriented modules.

Modules and Their Functional Interfaces

Modules are the main way that Perl provides for bundling up code for later use by yourself or others. As I'm sure you can't help noticing from reading The Perl Journal, CPAN (the Comprehensive Perl Archive Network) is the repository for modules (or groups of modules) that others have written, to do anything from composing music to accessing Web pages. A good deal of those modules even come with every installation of Perl.

One module that you may have used before, and which is fairly typical in its interface, is Text::Wrap. It comes with Perl, so you don't even need to install it from CPAN. You use it in a program of yours, by having your program code say early on:

  use Text::Wrap;

and after that, you can access a function called wrap, which inserts line-breaks in text that you feed it, so that the text will be wrapped to seventy-two (or however many) columns.

The way this use Text::Wrap business works is that the module Text::Wrap exists as a file "Text/Wrap.pm" somewhere in one of your library directories. That file contains Perl code...

Footnote: And mixed in with the Perl code, there's documentation, which is what you read with "perldoc Text::Wrap". The perldoc program simply ignores the code and formats the documentation text, whereas "use Text::Wrap" loads and runs the code while ignoring the documentation.

...which, among other things, defines a function called Text::Wrap::wrap, and then exports that function, which means that when you say wrap after having said "use Text::Wrap", you'll be actually calling the Text::Wrap::wrap function. Some modules don't export their functions, so you have to call them by their full name, like Text::Wrap::wrap(...parameters...).

Regardless of whether the typical module exports the functions it provides, a module is basically just a container for chunks of code that do useful things. The way the module allows for you to interact with it, is its interface. And when, like with Text::Wrap, its interface consists of functions, the module is said to have a functional interface.

Footnote: the term "function" (and therefore "functional") has various senses. I'm using the term here in its broadest sense, to refer to routines -- bits of code that are called by some name and which take parameters and return some value.

Using modules with functional interfaces is straightforward -- instead of defining your own "wrap" function with sub wrap { ... }, you entrust "use Text::Wrap" to do that for you, along with whatever other functions its defines and exports, according to the module's documentation. Without too much bother, you can even write your own modules to contain your frequently used functions; I suggest having a look at the perlmod man page for more leads on doing this.

Modules with Object-Oriented Interfaces

So suppose that one day you want to write a program that will automate the process of ftping a bunch of files from one server down to your local machine, and then off to another server.

A quick browse through search.cpan.org turns up the module "Net::FTP", which you can download and install it using normal installation instructions (unless your sysadmin has already installed it, as many have).

Like Text::Wrap or any other module with a familiarly functional interface, you start off using Net::FTP in your program by saying:

  use Net::FTP;

However, that's where the similarity ends. The first hint of difference is that the documentation for Net::FTP refers to it as a class. A class is a kind of module, but one that has an object-oriented interface.

Whereas modules like Text::Wrap provide bits of useful code as functions, to be called like function(...parameters...) or like PackageName::function(...parameters...), Net::FTP and other modules with object-oriented interfaces provide methods. Methods are sort of like functions in that they have a name and parameters; but methods look different, and are different, because you have to call them with a syntax that has a class name or an object as a special argument. I'll explain the syntax for method calls, and then later explain what they all mean.

Some methods are meant to be called as class methods, with the class name (same as the module name) as a special argument. Class methods look like this:

  ClassName->methodname(parameter1, parameter2, ...)
  ClassName->methodname()   # if no parameters
  ClassName->methodname     # same as above

which you will sometimes see written:

  methodname ClassName (parameter1, parameter2, ...)
  methodname ClassName      # if no parameters

Basically all class methods are for making new objects, and methods that make objects are called "constructors" (and the process of making them is called "constructing" or "instantiating"). Constructor methods typically have the name "new", or something including "new" ("new_from_file", etc.); but they can conceivably be named anything -- DBI's constructor method is named "connect", for example.

The object that a constructor method returns is typically captured in a scalar variable:

  $object = ClassName->new(param1, param2...);

Once you have an object (more later on exactly what that is), you can use the other kind of method call syntax, the syntax for object method calls. Calling object methods is just like class methods, except that instead of the ClassName as the special argument, you use an expression that yeilds an "object". Usually this is just a scalar variable that you earlier captured the output of the constructor in. Object method calls look like this:

  $object->methodname(parameter1, parameter2, ...);
  $object->methodname()   # if no parameters
  $object->methodname     # same as above

  which is occasionally written as:

  methodname $object (parameter1, parameter2, ...)
  methodname $object      # if no parameters

Examples of method calls are:

  my $session1 = Net::FTP->new("ftp.myhost.com");
    # Calls a class method "new", from class Net::FTP,
    #  with the single parameter "ftp.myhost.com",
    #  and saves the return value (which is, as usual,
    #  an object), in $session1.
    # Could also be written:
    #  new Net::FTP('ftp.myhost.com')
  $session1->login("sburke","aoeuaoeu")
    || die "failed to login!\n";
     # calling the object method "login"
  print "Dir:\n", $session1->dir(), "\n";
  $session1->quit;
    # same as $session1->quit()
  print "Done\n";
  exit;

Incidentally, I suggest always using the syntaxes with parentheses and "->" in them,

Footnote: the character-pair "->" is supposed to look like an arrow, not "negative greater-than"!

and avoiding the syntaxes that start out "methodname $object" or "methodname ModuleName". When everything's going right, they all mean the same thing as the "->" variants, but the syntax with "->" is more visually distinct from function calls, as well as being immune to some kinds of rare but puzzling ambiguities that can arise when you're trying to call methods that have the same name as subroutines you've defined.

But, syntactic alternatives aside, all this talk of constructing objects and object methods begs the question -- what is an object? There are several angles to this question that the rest of this article will answer in turn: what can you do with objects? what's in an object? what's an object value? and why do some modules use objects at all?

What Can You Do with Objects?

You've seen that you can make objects, and call object methods with them. But what are object methods for? The answer depends on the class:

A Net::FTP object represents a session between your computer and an FTP server. So the methods you call on a Net::FTP object are for doing whatever you'd need to do across an FTP connection. You make the session and log in:

  my $session = Net::FTP->new('ftp.aol.com');
  die "Couldn't connect!" unless defined $session;
    # The class method call to "new" will return
    # the new object if it goes OK, otherwise it
    # will return undef.

  $session->login('sburke', 'p@ssw3rD')
   || die "Did I change my password again?";
    # The object method "login" will give a true
    # return value if actually logs in, otherwise
    # it'll return false.

  You can use the session object to change directory on that session:

  $session->cwd("/home/sburke/public_html")
     || die "Hey, that was REALLY supposed to work!";
   # if the cwd fails, it'll return false

...get files from the machine at the other end of the session...

  foreach my $f ('log_report_ua.txt', 'log_report_dom.txt',
                 'log_report_browsers.txt')
  {
    $session->get($f) || warn "Getting $f failed!"
  };

...and plenty else, ending finally with closing the connection:

  $session->quit();

In short, object methods are for doing things related to (or with) whatever the object represents. For FTP sessions, it's about sending commands to the server at the other end of the connection, and that's about it -- there, methods are for doing something to the world outside the object, and the objects is just something that specifies what bit of the world (well, what FTP session) to act upon.

With most other classes, however, the object itself stores some kind of information, and it typically makes no sense to do things with such an object without considering the data that's in the object.

What's in an Object?

An object is (with rare exceptions) a data structure containing a bunch of attributes, each of which has a value, as well as a name that you use when you read or set the attribute's value. Some of the object's attributes are private, meaning you'll never see them documented because they're not for you to read or write; but most of the object's documented attributes are at least readable, and usually writeable, by you. Net::FTP objects are a bit thin on attributes, so we'll use objects from the class Business::US_Amort for this example. Business::US_Amort is a very simple class (available from CPAN) that I wrote for making calculations to do with loans (specifically, amortization, using US-style algorithms).

An object of the class Business::US_Amort represents a loan with particular parameters, i.e., attributes. The most basic attributes of a "loan object" are its interest rate, its principal (how much money it's for), and it's term (how long it'll take to repay). You need to set these attributes before anything else can be done with the object. The way to get at those attributes for loan objects is just like the way to get at attributes for any class's objects: through accessors. An accessor is simply any method that accesses (whether reading or writing, AKA getting or putting) some attribute in the given object. Moreover, accessors are the only way that you can change an object's attributes. (If a module's documentation wants you to know about any other way, it'll tell you.)

Usually, for simplicity's sake, an accessor is named after the attribute it reads or writes. With Business::US_Amort objects, the accessors you need to use first are principal, interest_rate, and term. Then, with at least those attributes set, you can call the run method to figure out several things about the loan. Then you can call various accessors, like total_paid_toward_interest, to read the results:

  use Business::US_Amort;
  my $loan = Business::US_Amort->new;
  # Set the necessary attributes:
  $loan->principal(123654);
  $loan->interest_rate(9.25);
  $loan->term(20); # twenty years

  # NOW we know enough to calculate:
  $loan->run;

  # And see what came of that:
  print
    "Total paid toward interest: A WHOPPING ",
    $loan->total_paid_interest, "!!\n";

This illustrates a convention that's common with accessors: calling the accessor with no arguments (as with $loan->total_paid_interest) usually means to read the value of that attribute, but providing a value (as with $loan->term(20)) means you want that attribute to be set to that value. This stands to reason: why would you be providing a value, if not to set the attribute to that value?

Although a loan's term, principal, and interest rates are all single numeric values, an objects values can any kind of scalar, or an array, or even a hash. Moreover, an attribute's value(s) can be objects themselves. For example, consider MIDI files (as I wrote about in TPJ#13): a MIDI file usually consists of several tracks. A MIDI file is complex enough to merit being an object with attributes like its overall tempo, the file-format variant it's in, and the list of instrument tracks in the file. But tracks themselves are complex enough to be objects too, with attributes like their track-type, a list of MIDI commands if they're a MIDI track, or raw data if they're not. So I ended up writing the MIDI modules so that the "tracks" attribute of a MIDI::Opus object is an array of objects from the class MIDI::Track. This may seem like a runaround -- you ask what's in one object, and get another object, or several! But in this case, it exactly reflects what the module is for -- MIDI files contain MIDI tracks, which then contain data.

What is an Object Value?

When you call a constructor like Net::FTP->new(hostname), you get back an object value, a value you can later use, in combination with a method name, to call object methods.

Now, so far we've been pretending, in the above examples, that the variables $session or $loan are the objects you're dealing with. This idea is innocuous up to a point, but it's really a misconception that will, at best, limit you in what you know how to do. The reality is not that the variables $session or $query are objects; it's a little more indirect -- they hold values that symbolize objects. The kind of value that $session or $query hold is what I'm calling an object value.

To understand what kind of value this is, first think about the other kinds of scalar values you know about: The first two scalar values you probably ever ran into in Perl are numbers and strings, which you learned (or just assumed) will usually turn into each other on demand; that is, the three-character string "2.5" can become the quantity two and a half, and vice versa. Then, especially if you started using perl -w early on, you learned about the undefined value, which can turn into 0 if you treat it as a number, or the empty-string if you treat it as a string.

Footnote: You may also have been learning about references, in which case you're ready to hear that object values are just a kind of reference, except that they reflect the class that created thing they point to, instead of merely being a plain old array reference, hash reference, etc. If this makes makes sense to you, and you want to know more about how objects are implemented in Perl, have a look at the perltoot man page.

And now you're learning about object values. An object value is a value that points to a data structure somewhere in memory, which is where all the attributes for this object are stored. That data structure as a whole belongs to a class (probably the one you named in the constructor method, like ClassName->new), so that the object value can be used as part of object method calls.

If you want to actually see what an object value is, you might try just saying "print $object". That'll get you something like this:

  Net::FTP=GLOB(0x20154240)

or

  Business::US_Amort=HASH(0x15424020)

That's not very helpful if you wanted to really get at the object's insides, but that's because the object value is only a symbol for the object. This may all sound very abstruse and metaphysical, so a real-world allegory might be very helpful:

You get an advertisement in the mail saying that you have been (im)personally selected to have the rare privilege of applying for a credit card. For whatever reason, this offer sounds good to you, so you fill out the form and mail it back to the credit card company. They gleefully approve the application and create your account, and send you a card with a number on it.

Now, you can do things with the number on that card -- clerks at stores can ring up things you want to buy, and charge your account by keying in the number on the card. You can pay for things you order online by punching in the card number as part of your online order. You can pay off part of the account by sending the credit card people some of your money (well, a check) with some note (usually the pre-printed slip) that has the card number for the account you want to pay toward. And you should be able to call the credit card company's computer and ask it things about the card, like its balance, its credit limit, its APR, and maybe an itemization of recent purchases ad payments.

Now, what you're really doing is manipulating a credit card account, a completely abstract entity with some data attached to it (balance, APR, etc). But for ease of access, you have a credit card number that is a symbol for that account. Now, that symbol is just a bunch of digits, and the number is effectively meaningless and useless in and of itself -- but in the appropriate context, it's understood to mean the credit card account you're accessing.

This is exactly the relationship between objects and object values, and from this analogy, several facts about object values are a bit more explicable:

* An object value does nothing in and of itself, but it's useful when you use it in the context of an $object->method call, the same way that a card number is useful in the context of some operation dealing with a card account.

Moreover, several copies of the same object value all refer to the same object, the same way that making several copies of your card number won't change the fact that they all still refer to the same single account (this is true whether you're "copying" the number by just writing it down on different slips of paper, or whether you go to the trouble of forging exact replicas of your own plastic credit card). That's why this:

  $x = Net::FTP->new("ftp.aol.com");
  $x->login("sburke", "aoeuaoeu");

does the same thing as this:

  $x = Net::FTP->new("ftp.aol.com");
  $y = $x;
  $z = $y;
  $z->login("sburke", "aoeuaoeu");

That is, $z and $y and $x are three different slots for values, but what's in those slots are all object values pointing to the same object -- you don't have three different FTP connections, just three variables with values pointing to the some single FTP connection.

* You can't tell much of anything about the object just by looking at the object value, any more than you can see your credit account balance by holding the plastic card up to the light, or by adding up the digits in your credit card number.

* You can't just make up your own object values and have them work -- they can come only from constructor methods of the appropriate class. Similarly, you get a credit card number only by having a bank approve your application for a credit card account -- at which point they let you know what the number of your new card is.

Now, there's even more to the fact that you can't just make up your own object value: even though you can print an object value and get a string like "Net::FTP=GLOB(0x20154240)", that string is just a representation of an object value.

Internally, an object value has a basically different type from a string, or a number, or the undefined value -- if $x holds a real string, then that value's slot in memory says "this is a value of type string, and its characters are...", whereas if it's an object value, the value's slot in memory says, "this is a value of type reference, and the location in memory that it points to is..." (and by looking at what's at that location, Perl can tell the class of what's there).

Perl programmers typically don't have to think about all these details of Perl's internals. Many other languages force you to be more conscious of the differences between all of these (and also between types of numbers, which are stored differently depending on their size and whether they have fractional parts). But Perl does its best to hide the different types of scalars from you -- it turns numbers into strings and back as needed, and takes the string or number representation of undef or of object values as needed. However, you can't go from a string representation of an object value, back to an object value. And that's why this doesn't work:

   $x = Net::FTP->new('ftp.aol.com');
   $y = Net::FTP->new('ftp.netcom.com');
   $z = Net::FTP->new('ftp.qualcomm.com');
   $all = join(' ', $x,$y,$z);           # !!!
     ...later...
   ($aol, $netcom, $qualcomm) = split(' ', $all);  # !!!
   $aol->login("sburke", "aoeuaoeu");
   $netcom->login("sburke", "qjkxqjkx");
   $qualcomm->login("smb", "dhtndhtn");

This fails because $aol ends up holding merely the string representation of the object value from $x, not the object value itself -- when join tried to join the characters of the "strings" $x, $y, and $z, Perl saw that they weren't strings at all, so it gave join their string representations.

Unfortunately, this distinction between object values and their string representations doesn't really fit into the analogy of credit card numbers, because credit card numbers really are numbers -- even thought they don't express any meaningful quantity, if you stored them in a database as a quantity (as opposed to just an ASCII string), that wouldn't stop them from being valid as credit card numbers.

This may seem rather academic, but there's there's two common mistakes programmers new to objects often make, which make sense only in terms of the distinction between object values and their string representations:

The first common error involves forgetting (or never having known in the first place) that when you go to use a value as a hash key, Perl uses the string representation of that value. When you want to use the numeric value two and a half as a key, Perl turns it into the three-character string "2.5". But if you then want to use that string as a number, Perl will treat it as meaning two and a half, so you're usually none the wiser that Perl converted the number to a string and back. But recall that Perl can't turn strings back into objects -- so if you tried to use a Net::FTP object value as a hash key, Perl actually used its string representation, like "Net::FTP=GLOB(0x20154240)", but that string is unusable as an object value. (Incidentally, there's a module Tie::RefHash that implements hashes that do let you use real object-values as keys.)

The second common error with object values is in trying to save an object value to disk (whether printing it to a file, or storing it in a conventional database file). All you'll get is the string, which will be useless.

When you want to save an object and restore it later, you may find that the object's class already provides a method specifically for this. For example, MIDI::Opus provides methods for writing an object to disk as a standard MIDI file. The file can later be read back into memory by a MIDI::Opus constructor method, which will return a new MIDI::Opus object representing whatever file you tell it to read into memory. Similar methods are available with, for example, classes that manipulate graphic images and can save them to files, which can be read back later.

But some classes, like Business::US_Amort, provide no such methods for storing an object in a file. When this is the case, you can try using any of the Data::Dumper, Storable, or FreezeThaw modules. Using these will be unproblematic for objects of most classes, but it may run into limitations with others. For example, a Business::US_Amort object can be turned into a string with Data::Dumper, and that string written to a file. When it's restored later, its attributes will be accessable as normal. But in the unlikely case that the loan object was saved in mid-calculation, the calculation may not be resumable. This is because of the way that that particular class does its calculations, but similar limitations may occur with objects from other classses.

But often, even wanting to save an object is basically wrong -- what would saving an ftp session even mean? Saving the hostname, username, and password? current directory on both machines? the local TCP/IP port number? In the case of "saving" a Net::FTP object, you're better off just saving whatever details you actually need for your own purposes, so that you can make a new object later and just set those values for it.

So Why Do Some Modules Use Objects?

All these details of using objects are definitely enough to make you wonder -- is it worth the bother? If you're a module author, writing your module with an object-oriented interface restricts the audience of potential users to those who understand the basic concepts of objects and object values, as well as Perl's syntax for calling methods. Why complicate things by having an object-oriented interface?

A somewhat esoteric answer is that a module has an object-oriented interface because the module's insides are written in an object-oriented style. This article is about the basics of object-oriented interfaces, and it'd be going far afield to explain what object-oriented design is. But the short story is that object-oriented design is just one way of attacking messy problems. It's a way that many programmers find very helpful (and which others happen to find to be far more of a hassle than it's worth, incidentally), and it just happens to show up for you, the module user, as merely the style of interface.

But a simpler answer is that a functional interface is sometimes a hindrance, because it limits the number of things you can do at once -- limiting it, in fact, to one. For many problems that some modules are meant to solve, doing without an object-oriented interface would be like wishing that Perl didn't use filehandles. The ideas are rather simpler -- just imagine that Perl let you access files, but only one at a time, with code like:

  open("foo.txt") || die "Can't open foo.txt: $!";
  while(readline) {
    print $_ if /bar/;
  }
  close;

That hypothetical kind of Perl would be simpler, by doing without filehandles. But you'd be out of luck if you wanted to read from one file while reading from another, or read from two and print to a third.

In the same way, a functional FTP module would be fine for just uploading files to one server at a time, but it wouldn't allow you to easily write programs that make need to use several simultaneous sessions (like "look at server A and server B, and if A has a file called X.dat, then download it locally and then upload it to server B -- except if B has a file called Y.dat, in which case do it the other way around").

Some kinds of problems that modules solve just lend themselves to an object-oriented interface. For those kinds of tasks, a functional interface would be more familiar, but less powerful. Learning to use object-oriented modules' interfaces does require becoming comfortable with the concepts from this article. But in the end it will allow you to use a broader range of modules and, with them, to write programs that can do more.

[end body of article]

[Author Credit]

Sean M. Burke has contributed several modules to CPAN, about half of them object-oriented.

[The next section should be in a greybox:]

The Gory Details

For sake of clarity of explanation, I had to oversimplify some of the facts about objects. Here's a few of the gorier details:

* Every example I gave of a constructor was a class method. But object methods can be constructors, too, if the class was written to work that way: $new = $old->copy, $node_y = $node_x->new_subnode, or the like.

* I've given the impression that there's two kinds of methods: object methods and class methods. In fact, the same method can be both, because it's not the kind of method it is, but the kind of calls it's written to accept -- calls that pass an object, or calls that pass a class-name.

* The term "object value" isn't something you'll find used much anywhere else. It's just my shorthand for what would properly be called an "object reference" or "reference to a blessed item". In fact, people usually say "object" when they properly mean a reference to that object.

* I mentioned creating objects with constructors, but I didn't mention destroying them with destructor -- a destructor is a kind of method that you call to tidy up the object once you're done with it, and want it to neatly go away (close connections, delete temporary files, free up memory, etc). But because of the way Perl handles memory, most modules won't require the user to know about destructors.

* I said that class method syntax has to have the class name, as in $session = Net::FTP->new($host). Actually, you can instead use any expression that returns a class name: $ftp_class = 'Net::FTP'; $session = $ftp_class->new($host). Moreover, instead of the method name for object- or class-method calls, you can use a scalar holding the method name: $foo->$method($host). But, in practice, these syntaxes are rarely useful.

And finally, to learn about objects from the perspective of writing your own classes, see the perltoot documentation, or Damian Conway's exhaustive and clear book Object Oriented Perl (Manning Publications 1999, ISBN 1-884777-79-1).

BACK

Return to the HTML::Tree docs.


HTML::Tree::AboutTrees -- article on tree-shaped data structures in Perl

  • Trees
    • Socratic Dialogues: "What is a Tree?"
    • Trees Defined Formally
    • Markup Language Trees: HTML-Tree
    • Building Your Own Trees
    • Implementation: Game Trees for Alak
    • Digression: Links to Parents
    • Recursively Printing the Tree
    • Growing the Tree
    • [Author Credit]
    • References
  • BACK

NAME

HTML::Tree::AboutTrees -- article on tree-shaped data structures in Perl

SYNOPSIS

  # This an article, not a module.

DESCRIPTION

The following article by Sean M. Burke first appeared in The Perl Journal #18 and is copyright 2000 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.

Trees

-- Sean M. Burke

"AaaAAAaauugh! Watch out for that tree!" -- George of the Jungle theme

Perl's facility with references, combined with its automatic management of memory allocation, makes it straightforward to write programs that store data in structures of arbitrary form and complexity.

But I've noticed that many programmers, especially those who started out with more restrictive languages, seem at home with complex but uniform data structures -- N-dimensional arrays, or more struct-like things like hashes-of-arrays(-of-hashes(-of-hashes), etc.) -- but they're often uneasy with buliding more freeform, less tabular structures, like tree-shaped data structures.

But trees are easy to build and manage in Perl, as I'll demonstrate by showing off how the HTML::Element class manages elements in an HTML document tree, and by walking you through a from-scratch implementation of game trees. But first we need to nail down what we mean by a "tree".

Socratic Dialogues: "What is a Tree?"

My first brush with tree-shaped structures was in linguistics classes, where tree diagrams are used to describe the syntax underlying natural language sentences. After learning my way around those trees, I started to wonder -- are what I'm used to calling "trees" the same as what programmers call "trees"? So I asked lots of helpful and patient programmers how they would define a tree. Many replied with a answer in jargon that they could not really explain (understandable, since explaining things, especially defining things, is harder than people think):

-- So what is a "tree", a tree-shaped data structure?

-- A tree is a special case of an acyclic directed graph!

-- What's a "graph"?

-- Um... lines... and... you draw it... with... arcs! nodes! um...

The most helpful were folks who couldn't explain directly, but with whom I could get into a rather Socratic dialog (where I asked the half-dim half-earnest questions), often with much doodling of illustrations...

Question: so what's a tree?

Answer: A tree is a collection of nodes that are linked together in a, well, tree-like way! Like this [drawing on a napkin]:

     A
    / \
   B   C
     / | \
    D  E  F

Q: So what do these letters represent?

A: Each is a different node, a bunch of data. Maybe C is a bunch of data that stores a number, maybe a hash table, maybe nothing at all besides the fact that it links to D, E, and F (which are other nodes).

Q: So what're the lines between the nodes?

A: Links. Also called "arcs". They just symbolize the fact that each node holds a list of nodes it links to.

Q: So what if I draw nodes and links, like this...

     B -- E
    / \  / \
   A   C
    \ /
     E

Is that still a tree?

A: No, not at all. There's a lot of un-treelike things about that. First off, E has a link coming off of it going into nowhere. You can't have a link to nothing -- you can only link to another node. Second off, I don't know what that sideways link between B and E means...

Q: Okay, let's work our way up from something simpler. Is this a tree...?

    A

A: Yes, I suppose. It's a tree of just one node.

Q: And how about...

   A
   B

A: No, you can't just have nodes floating there, unattached.

Q: Okay, I'll link A and B. How's this?

   A
   |
   B

A: Yup, that's a tree. There's a node A, and a node B, and they're linked.

Q: How is that tree any different from this one...?

   B
   |
   A

A: Well, in both cases A and B are linked. But it's in a different direction.

Q: Direction? What does the direction mean?

A: Well, it depends what the tree represents. If it represents a categorization, like this:

          citrus
       /    |    \
   orange  lemon  kumquat ...

then you mean to say that oranges, lemons, kumquats, etc., are a kind of citrus. But if you drew it upside down, you'd be saying, falsely, that citrus is a kind of kumquat, a kind of lemon, and a kind of orange. If the tree represented cause-and-effect (or at least what situations could follow others), or represented what's a part of what, you wouldn't want to get those backwards, either. So with the nodes you draw together on paper, one has to be over the other, so you can tell which way the relationship in the tree works.

Q: So are these two trees the same?

     A          A
    / \        / \
   B   C      B   \
                   C

A: Yes, although by convention we often try to line up things in the same generation, like it is in the diagram on the left.

Q: "generation"? This is a family tree?

A: No, not unless it's a family tree for just yeast cells or something else that reproduces asexually. But for sake of having lots of terms to use, we just pretend that links in the tree represent the "is a child of" relationship, instead of "is a kind of" or "is a part of", or "could result from", or whatever the real relationship is. So we get to borrow a lot of kinship words for describing trees -- B and C are "children" (or "daughters") of A; A is the "parent" (or "mother") of B and C. Node C is a "sibling" (or "sister") of node C; and so on, with terms like "descedants" (a node's children, children's children, etc.), and "generation" (all the nodes at the same "level" in the tree, i.e., are either all grandchildren of the top node, or all great-grand-children, etc.), and "lineage" or "ancestors" (parents, and parent's parents, etc., all the way to the topmost node).

So then we get to express rules in terms like "A node cannot have more than one parent", which means that this is not a valid tree:

    A
   / \
  B   C
   \ /
    E

And: "A node can't be its own parent", which excludes this looped-up connection:

    /\
   A  |
    \/

Or, put more generally: "A node can't be its own ancestor", which excludes the above loop, as well as the one here:

      /\
     Z  |
    /   |
   A    |
  / \   |
 B   C  |
      \/

That tree is excluded because A is a child of Z, and Z is a child of C, and C is a child of A, which means A is its own great-grandparent. So this whole network can't be a tree, because it breaks the sort of meta-rule: once any node in the supposed tree breaks the rules for trees, you don't have a tree anymore.

Q: Okay, now, are these two trees the same?

     A         A
   / | \     / | \
  B  C  D   D  C  B

A: It depends whether you're basing your concept of trees on each node having a set (unordered list) of children, or an (ordered) list of children. It's a question of whether ordering is important for what you're doing. With my diagram of citrus types, ordering isn't important, so these tree diagrams express the same thing:

          citrus
       /    |    \
   orange  lemon  kumquat
           citrus
       /     |    \
   kumquat  orange  lemon

because it doesn't make sense to say that oranges are "before" or "after" kumquats in the whole botanical scheme of things. (Unless, of course, you are using ordering to mean something, like a degree of genetic similarity.)

But consider a tree that's a diagram of what steps are comprised in an activity, to some degree of specificity:

           make tea
         /    |     \
   pour     infuse   serve
 hot water    / \
in cup/pot  /     \
           add     let
           tea     sit
          leaves

This means that making tea consists of putting hot water in a cup or put, infusing it (which itself consists of adding tea leaves and letting it sit), then serving it -- in that order. If you serve an empty dry pot (sipping from empty cups, etc.), let it sit, add tea leaves, and pour in hot water, then what you're doing is performance art, not tea preparation:

          perfomance
            art
        /    |     \
   serve   infuse    pour
            / \       hot water
          /     \      in cup/pot
         let     add
         sit     tea
                leaves

Except for my having renamed the root, this tree is the same as the making-tea tree as far as what's under what, but it differs in order, and what the tree means makes the order important.

Q: Wait -- "root"? What's a root?

A: Besides kinship terms like "mother" and "daugher", the jargon for tree parts also has terms from real-life tree parts: the part that everything else grows from is called the root; and nodes that don't have nodes attached to them (i.e., childless nodes) are called "leaves".

Q: But you've been drawing all your trees with the root at the top and leaves at the bottom.

A: Yes, but for some reason, that's the way everyone seems to think of trees. They can draw trees as above; or they can draw them sort of sideways with indenting representing what nodes are children of what:

  * make tea
     * pour hot water in cup/pot
     * infuse
        * add tea leaves
        * let sit
     * serve

...but folks almost never seem to draw trees with the root at the bottom. So imagine it's based on spider plant in a hanging pot. Unfortunately, spider plants aren't botanically trees, they're plants; but "spider plant diagram" is rather a mouthful, so let's just call them trees.

Trees Defined Formally

In time, I digested all these assorted facts about programmers' ideas of trees (which turned out to be just a more general case of linguistic ideas of trees) into a single rule:

* A node is an item that contains ("is over", "is parent of", etc.) zero or more other nodes.

From this you can build up formal definitions for useful terms, like so:

* A node's descendants are defined as all its children, and all their children, and so on. Or, stated recursively: a node's descendants are all its children, and all its children's descendants. (And if it has no children, it has no descendants.)

* A node's ancestors consist of its parent, and its parent's parent, etc, up to the root. Or, recursively: a node's ancestors consist of its parent and its parent's ancestors. (If it has no parent, it has no ancestors.)

* A tree is a root node and all the root's descendants.

And you can add a proviso or two to clarify exactly what I impute to the word "other" in "other nodes":

* A node cannot contain itself, or contain any node that contains it, etc. Looking at it the other way: a node cannot be its own parent or ancestor.

* A node can be root (i.e., no other node contains it) or can be contained by only one parent; no node can be the child of two or more parents.

Add to this the idea that children are sometimes ordered, and sometimes not, and that's about all you need to know about defining what a tree is. From there it's a matter of using them.

Markup Language Trees: HTML-Tree

While not all markup languages are inherently tree-like, the best-known family of markup languages, HTML, SGML, and XML, are about as tree-like as you can get. In these languages, a document consists of elements and character data in a tree structure where there is one root element, and elements can contain either other elements, or character data.

Footnote: For sake of simplicity, I'm glossing over comments (<!-- ... -->), processing instructions (<?xml version='1.0'>), and declarations (<!ELEMENT ...>, <!DOCTYPE ...>). And I'm not bothering to distinguish entity references (&lt;, &#64;) or CDATA sections (<![CDATA[ ...]]>) from normal text.

For example, consider this HTML document:

  <html lang="en-US">
    <head>
      <title>
        Blank Document!
      </title>
    </head>
    <body bgcolor="#d010ff">
      I've got
      <em>
        something to saaaaay
      </em>
      !
    </body>
  </html>

I've indented this to point out what nodes (elements or text items) are children of what, with each node on a line of its own.

The HTML::TreeBuilder module (in the CPAN distribution HTML-Tree) does the work of taking HTML source and building in memory the tree that the document source represents.

Footnote: it requires the HTML::Parser module, which tokenizes the source -- i.e., identifies each tag, bit of text, comment, etc.

The trees structures that it builds represent bits of text with normal Perl scalar string values; but elements are represented with objects -- that is, chunks of data that belong to a class (in this case, HTML::Element), a class that provides methods (routines) for accessing the pieces of data in each element, and otherwise doing things with elements. (See my article in TPJ#17 for a quick explanation of objects, the POD document perltoot for a longer explanation, or Damian Conway's excellent book Object-Oriented Perl for the full story.)

Each HTML::Element object contains a number of pieces of data:

* its element name ("html", "h1", etc., accessed as $element->tag)

* a list of elements (or text segments) that it contains, if any (accessed as $element->content_list or $element->content, depending on whether you want a list, or an arrayref)

* what element, if any, contains it (accessed as $element->parent)

* and any SGML attributes that the element has, such as lang="en-US", align="center", etc. (accessed as $element->attr('lang'), $element->attr('center'), etc.)

So, for example, when HTML::TreeBuilder builds the tree for the above HTML document source, the object for the "body" element has these pieces of data:

 * element name: "body"
 * nodes it contains:
    the string "I've got "
    the object for the "em" element
    the string "!"
 * its parent:
    the object for the "html" element
 * bgcolor: "#d010ff"

Now, once you have this tree of objects, almost anything you'd want to do with it starts with searching the tree for some bit of information in some element.

Accessing a piece of information in, say, a hash of hashes of hashes, is straightforward:

  $password{'sean'}{'sburke1'}{'hpux'}

because you know that all data points in that structure are accessible with that syntax, but with just different keys. Now, the "em" element in the above HTML tree does happen to be accessible as the root's child #1's child #1:

  $root->content->[1]->content->[1]

But with trees, you typically don't know the exact location (via indexes) of the data you're looking for. Instead, finding what you want will typically involve searching through the tree, seeing if every node is the kind you want. Searching the whole tree is simple enough -- look at a given node, and if it's not what you want, look at its children, and so on. HTML-Tree provides several methods that do this for you, such as find_by_tag_name, which returns the elements (or the first element, if called in scalar context) under a given node (typically the root) whose tag name is whatever you specify.

For example, that "em" node can be found as:

  my $that_em = $root->find_by_tag_name('em');

or as:

  @ems = $root->find_by_tag_name('em');
   # will only have one element for this particular tree

Now, given an HTML document of whatever structure and complexity, if you wanted to do something like change every

<em>stuff</em>

to

<em class="funky"> <b>[-</b> stuff <b>-]</b> </em>

the first step is to frame this operation in terms of what you're doing to the tree. You're changing this:

      em
       |
      ...

to this:

      em
    /  |  \
   b  ...   b
   |        |
  "[-"     "-]"

In other words, you're finding all elements whose tag name is "em", setting its class attribute to "funky", and adding one child to the start of its content list -- a new "b" element whose content is the text string "[-" -- and one to the end of its content list -- a new "b" element whose content is the text string "-]".

Once you've got it in these terms, it's just a matter of running to the HTML::Element documentation, and coding this up with calls to the appropriate methods, like so:

  use HTML::Element 1.53;
  use HTML::TreeBuilder 2.96;
  # Build the tree by parsing the document
  my $root = HTML::TreeBuilder->new;
  $root->parse_file('whatever.html'); # source file

  # Now make new nodes where needed
  foreach my $em ($root->find_by_tag_name('em')) {
    $em->attr('class', 'funky'); # Set that attribute

    # Make the two new B nodes
    my $new1 = HTML::Element->new('b');
    my $new2 = HTML::Element->new('b');
    # Give them content (they have none at first)
    $new1->push_content('[-');
    $new2->push_content('-]');

    # And put 'em in place!
    $em->unshift_content($new1);
    $em->push_content($new2);
      }
      print
       "<!-- Looky see what I did! -->\n",
       $root->as_HTML(), "\n";

The class HTML::Element provides just about every method I can image you needing, for manipulating trees made of HTML::Element objects. (And what it doesn't directly provide, it will give you the components to build it with.)

Building Your Own Trees

Theoretically, any tree is pretty much like any other tree, so you could use HTML::Element for anything you'd ever want to do with tree-arranged objects. However, as its name implies, HTML::Element is basically for HTML elements; it has lots of features that make sense only for HTML elements (like the idea that every element must have a tag-name). And it lacks some features that might be useful for general applications -- such as any sort of checking to make sure that you're not trying to arrange objects in a non-treelike way. For a general-purpose tree class that does have such features, you can use Tree::DAG_Node, also available from CPAN.

However, if your task is simple enough, you might find it overkill to bother using Tree::DAG_Node. And, in any case, I find that the best way to learn how something works is to implement it (or something like it, but simpler) yourself. So I'll here discuss how you'd implement a tree structure, without using any of the existing classes for tree nodes.

Implementation: Game Trees for Alak

Suppose that the task at hand is to write a program that can play against a human opponent at a strategic board game (as opposed to a board game where there's an element of chance). For most such games, a "game tree" is an essential part of the program (as I will argue, below), and this will be our test case for implementing a tree structure from stratch.

For sake of simplicity, our game is not chess or backgammon, but instead a much simpler game called Alak. Alak was invented by the mathematician A. K. Dewdney, and described in his 1984 book Planiverse. The rules of Alak are simple:

Footnote: Actually, I'm describing only my interpetation of the rules Dewdney describes in Planiverse. Many other interpretations are possible.

* Alak is a two-player game played on a one-dimensional board with eleven slots on it. Each slot can hold at most one piece at a time. There's two kinds of pieces, which I represent here as "x" and "o" -- x's belong to one player (called X), o's to the other (called O).

* The initial configuration of the board is:

   xxxx___oooo

For sake of the article, the slots are numbered from 1 (on the left) to 11 (on the right), and X always has the first move.

* The players take turns moving. At each turn, each player can move only one piece, once. (This unlike checkers, where you move one piece per move but get to keep moving it if you jump an your opponent's piece.) A player cannot pass up on his turn. A player can move any one of his pieces to the next unoccupied slot to its right or left, which may involve jumping over occupied slots. A player cannot move a piece off the side of the board.

* If a move creates a pattern where the opponent's pieces are surrounded, on both sides, by two pieces of the mover's color (with no intervening unoccupied blank slot), then those surrounded pieces are removed from the board.

* The goal of the game is to remove all of your opponent's pieces, at which point the game ends. Removing all-but-one ends the game as well, since the opponent can't surround you with one piece, and so will always lose within a few moves anyway.

Consider, then, this rather short game where X starts:

  xxxx___oooo
    ^         Move 1: X moves from 3 (shown with caret) to 5
               (Note that any of X's pieces could move, but
               that the only place they could move to is 5.)
  xx_xx__oooo
          ^   Move 2: O moves from 9 to 7.
  xx_xx_oo_oo
     ^        Move 3: X moves from 4 to 6.
  xx__xxoo_oo
           ^  Move 4: O (stupidly) moves from 10 to 9.
  xx__xxooo_o
      ^       Move 5: X moves from 5 to 10, making the board
              "xx___xoooxo".  The three o's that X just
              surrounded are removed.
  xx___x___xo
              O has only one piece, so has lost.

Now, move 4 could have gone quite the other way:

  xx__xxoo_oo
              Move 4: O moves from 8 to 4, making the board
              "xx_oxxo__oo".  The surrounded x's are removed.
  xx_o__o__oo
  ^           Move 5: X moves from 1 to 2.
  _xxo__o__oo
        ^     Move 6: O moves from 7 to 6.
  _xxo_o___oo
   ^          Move 7: X moves from 2 to 5, removing the o at 4.
  __x_xo___oo
              ...and so on.

To teach a computer program to play Alak (as player X, say), it needs to be able to look at the configuration of the board, figure out what moves it can make, and weigh the benefit or costs, immediate or eventual, of those moves.

So consider the board from just before move 3, and figure all the possible moves X could make. X has pieces in slots 1, 2, 4, and 5. The leftmost two x's (at 1 and 2) are up against the end of the board, so they can move only right. The other two x's (at 4 and 5) can move either right or left:

  Starting board: xx_xx_oo_oo
   moving 1 to 3 gives _xxxx_oo_oo
   moving 2 to 3 gives x_xxx_oo_oo
   moving 4 to 3 gives xxx_x_oo_oo
   moving 5 to 3 gives xxxx__oo_oo
   moving 4 to 6 gives xx__xxoo_oo
   moving 5 to 6 gives xx_x_xoo_oo

For the computer to decide which of these is the best move to make, it needs to quantify the benefit of these moves as a number -- call that the "payoff". The payoff of a move can be figured as just the number of x pieces removed by the most recent move, minus the nubmer of o pieces removed by the mots recent move. (It so happens that the rules of the game mean that no move can delete both o's and x's, but the formula still applies.) Since none of these moves removed any pieces, all these moves have the same immediate payoff: 0.

Now, we could race ahead and write an Alak-playing program that could use the immediate payoff to decide which is the best move to make. And when there's more than one best move (as here, where all the moves are equally good), it could choose randomly between the good alternatives. This strategy is simple to implement; but it makes for a very dumb program. Consider what O's response to each of the potential moves (above) could be. Nothing immediately suggests itself for the first four possibilities (X having moved something to position 3), but either of the last two (illustrated below) are pretty perilous, because in either case O has the obvious option (which he would be foolish to pass up) of removing x's from the board:

   xx_xx_oo_oo
      ^        X moves 4 to 6.
   xx__xxoo_oo
          ^    O moves 8 to 4, giving "xx_oxxo__oo".  The two
               surrounded x's are removed.
   xx_o__o__oo

or

   xx_xx_oo_oo
       ^       X moves 5 to 6.
   xx_x_xoo_oo
          ^    O moves 8 to 5, giving "xx_xoxo__oo".  The one
               surrounded x is removed.
   xx_xo_o__oo

Both contingencies are quite bad for X -- but this is not captured by the fact that they start out with X thinking his move will be harmless, having a payoff of zero.

So what's needed is for X to think more than one step ahead -- to consider not merely what it can do in this move, and what the payoff is, but to consider what O might do in response, and the payoff of those potential moves, and so on with X's possible responses to those cases could be. All these possibilities form a game tree -- a tree where each node is a board, and its children are successors of that node -- i.e., the boards that could result from every move possible, given the parent's board.

But how to represent the tree, and how to represent the nodes?

Well, consider that a node holds several pieces of data:

1) the configuration of the board, which, being nice and simple and one-dimensional, can be stored as just a string, like "xx_xx_oo_oo".

2) whose turn it is, X or O. (Or: who moved last, from which we can figure whose turn it is).

3) the successors (child nodes).

4) the immediate payoff of having moved to this board position from its predecessor (parent node).

5) and what move gets us from our predecessor node to here. (Granted, knowing the board configuration before and after the move, it's easy to figure out the move; but it's easier still to store it as one is figuring out a node's successors.)

6) whatever else we might want to add later.

These could be stored equally well in an array or in a hash, but it's my experience that hashes are best for cases where you have more than just two or three bits of data, or especially when you might need to add new bits of data. Moreover, hash key names are mnemonic -- $node->{'last_move_payoff'} is plain as day, whereas it's not so easy having to remember with an array that $node->[3] is where you decided to keep the payoff.

Footnote: Of course, there are ways around that problem: just swear you'll never use a real numeric index to access data in the array, and instead use constants with mnemonic names:

  use strict;
  use constant idx_PAYOFF => 3;
  ...
  $n->[idx_PAYOFF]

Or use a pseudohash. But I prefer to keep it simple, and use a hash.

These are, incidentally, the same arguments that people weigh when trying to decide whether their object-oriented modules should be based on blessed hashes, blessed arrays, or what. Essentially the only difference here is that we're not blessing our nodes or talking in terms of classes and methods.

[end footnote]

So, we might as well represent nodes like so:

  $node = { # hashref
     'board'          => ...board string, e.g., "xx_x_xoo_oo"

     'last_move_payoff' => ...payoff of the move
                            that got us here.
     'last_move_from' =>  ...the start...
     'last_move_to'   =>  ...and end point of the move
                              that got us here.  E.g., 5 and 6,
                              representing a move from 5 to 6.
     'whose_turn'     => ...whose move it then becomes.
                           just an 'x' or 'o'.
     'successors' => ...the successors
       };

Note that we could have a field called something like 'last_move_who' to denote who last moved, but since turns in Alak always alternate (and no-one can pass), storing whose move it is now and who last moved is redundant -- if X last moved, it's O turn now, and vice versa. I chose to have a 'whose_turn' field instead of a 'last_move_who', but it doesn't really matter. Either way, we'll end up inferring one from the other at several points in the program.

When we want to store the successors of a node, should we use an array or a hash? On the one hand, the successors to $node aren't essentially ordered, so there's no reason to use an array per se; on the other hand, if we used a hash, with successor nodes as values, we don't have anything particularly meaningful to use as keys. (And we can't use the successors themselves as keys, since the nodes are referred to by hash references, and you can't use a reference as a hash key.) Given no particularly compelling reason to do otherwise, I choose to just use an array to store all a node's successors, although the order is never actually used for anything:

  $node = {
    ...
    'successors' => [ ...nodes... ],
    ...
  };

In any case, now that we've settled on what should be in a node, let's make a little sample tree out of a few nodes and see what we can do with it:

  # Board just before move 3 in above game
  my $n0 = {
    'board' => 'xx_xx_oo_oo',
    'last_move_payoff' => 0,
    'last_move_from' =>  9,
    'last_move_to'   =>  7,
    'whose_turn' => 'x',
    'successors' => [],
  };

  # And, for now, just two of the successors:

  # X moves 4 to 6, giving xx__xxoo_oo
  my $n1 = {
    'board' => 'xx__xxoo_oo',
    'last_move_payoff' => 0,
    'last_move_from' =>  4,
    'last_move_to'   =>  6,
    'whose_turn' => 'o',
    'successors' => [],
  };

  # or X moves 5 to 6, giving xx_x_xoo_oo
  my $n2 = {
    'board' => 'xx_x_xoo_oo',
    'last_move_payoff' => 0,
    'last_move_from' =>  5,
    'last_move_to'   =>  6,
    'whose_turn' => 'o',
    'successors' => [],
  };

  # Now connect them...
  push @{$n0->{'successors'}}, $n1, $n2;

Digression: Links to Parents

In comparing what we store in an Alak game tree node to what HTML::Element stores in HTML element nodes, you'll note one big difference: every HTML::Element node contains a link to its parent, whereas we don't have our Alak nodes keeping a link to theirs.

The reason this can be an important difference is because it can affect how Perl knows when you're not using pieces of memory anymore. Consider the tree we just built, above:

      node 0
     /      \
  node 1    node 2

There's two ways Perl knows you're using a piece of memory: 1) it's memory that belongs directly to a variable (i.e., is necessary to hold that variable's value, or values in the case of a hash or array), or 2) it's a piece of memory that something holds a reference to. In the above code, Perl knows that the hash for node 0 (for board "xx_xx_oo_oo") is in use because something (namely, the variable $n0) holds a reference to it. Now, even if you followed the above code with this:

  $n1 = $n2 = 'whatever';

to make your variables $n1 and $n2 stop holding references to the hashes for the two successors of node 0, Perl would still know that those hashes are still in use, because node 0's successors array holds a reference to those hashes. And Perl knows that node 0 is still in use because something still holds a reference to it. Now, if you added:

  my $root = $n0;

This would change nothing -- there's just be two things holding a reference to the node 0 hash, which in turn holds a reference to the node 1 and node 2 hashes. And if you then added:

  $n0 = 'stuff';

still nothing would change, because something ($root) still holds a reference to the node 0 hash. But once nothing holds a reference to the node 0 hash, Perl will know it can destroy that hash (and reclaim the memory for later use, say), and once it does that, nothing will hold a reference to the node 1 or the node 2 hashes, and those will be destroyed too.

But consider if the node 1 and node 2 hashes each had an attribute "parent" (or "predecessor") that held a reference to node 0. If your program stopped holding a reference to the node 0 hash, Perl could not then say that nothing holds a reference to node 0 -- because node 1 and node 2 still do. So, the memory for nodes 0, 1, and 2 would never get reclaimed (until your program ended, at which point Perl destroys everything). If your program grew and discarded lots of nodes in the game tree, but didn't let Perl know it could reclaim their memory, your program could grow to use immense amounts of memory -- never a nice thing to have happen. There's three ways around this:

1) When you're finished with a node, delete the reference each of its children have to it (in this case, deleting $n1->{'parent'}, say). When you're finished with a whole tree, just go through the whole tree erasing links that children have to their children.

2) Reconsider whether you really need to have each node hold a reference to its parent. Just not having those links will avoid the whole problem.

3) use the WeakRef module with Perl 5.6 or later. This allows you to "weaken" some references (like the references that node 1 and 2 could hold to their parent) so that they don't count when Perl goes asking whether anything holds a reference to a given piece of memory. This wonderful new module eliminates the headaches that can often crop up with either of the two previous methods.

It so happens that our Alak program is simple enough that we don't need for our nodes to have links to their parents, so the second solution is fine. But in a more advanced program, the first or third solutions might be unavoidable.

Recursively Printing the Tree

I don't like working blind -- if I have any kind of a complex data structure in memory for a program I'm working on, the first thing I do is write something that can dump that structure to the screen so I can make sure that what I think is in memory really is what's in memory. Now, I could just use the "x" pretty-printer command in Perl's interactive debugger, or I could have the program use the Data::Dumper module. But in this case, I think the output from those is rather too verbose. Once we have trees with dozens of nodes in them, we'll really want a dump of the tree to be as concise as possible, hopefully just one line per node. What I'd like is something that can print $n0 and its successors (see above) as something like:

  xx_xx_oo_oo  (O moved 9 to 7, 0 payoff)
    xx__xxoo_oo  (X moved 4 to 6, 0 payoff)
    xx_x_xoo_oo  (X moved 5 to 6, 0 payoff)

A subroutine to print a line for a given node, and then do that again for each successor, would look something like:

  sub dump_tree {
    my $n = $_[0]; # "n" is for node
    print
      ...something expressing $n'n content...
    foreach my $s (@{$n->{'successors'}}) {
      # "s for successor
      dump($s);
    }
  }

And we could just start that out with a call to dump_tree($n0).

Since this routine...

Footnote: I first wrote this routine starting out with "sub dump {". But when I tried actually calling dump($n0), Perl would dump core! Imagine my shock when I discovered that this is absolutely to be expected -- Perl provides a built-in function called dump, the purpose of which is to, yes, make Perl dump core. Calling our routine "dump_tree" instead of "dump" neatly avoids that problem.

...does its work (dumping the subtree at and under the given node) by calling itself, it's recursive. However, there's a special term for this kind of recursion across a tree: traversal. To traverse a tree means to do something to a node, and to traverse its children. There's two prototypical ways to do this, depending on what happens when:

  traversing X in pre-order:
    * do something to X
    * then traverse X's children
  traversing X in post-order:
    * traverse X's children
    * then do something to X

Dumping the tree to the screen the way we want it happens to be a matter of pre-order traversal, since the thing we do (print a description of the node) happens before we recurse into the successors.

When we try writing the print statement for our above dump_tree, we can get something like:

  sub dump_tree {
    my $n = $_[0];

    # "xx_xx_oo_oo  (O moved 9 to 7, 0 payoff)"
    print
      $n->{'board'}, "  (",
      ($n->{'whose_turn'} eq 'o' ? 'X' : 'O'),
      # Infer who last moved from whose turn it is now.
      " moved ", $n->{'last_move_from'},
      " to ",    $n->{'last_move_to'},
      ", ",      $n->{'last_move_payoff'},
      " payoff)\n",
    ;

    foreach my $s (@{$n->{'successors'}}) {
      dump_tree($s);
    }
      }

If we run this on $n0 from above, we get this:

  xx_xx_oo_oo  (O moved 9 to 7, 0 payoff)
  xx__xxoo_oo  (X moved 4 to 6, 0 payoff)
  xx_x_xoo_oo  (X moved 5 to 6, 0 payoff)

Each line on its own is fine, but we forget to allow for indenting, and without that we can't tell what's a child of what. (Imagine if the first successor had successors of its own -- you wouldn't be able to tell if it were a child, or a sibling.) To get indenting, we'll need to have the instances of the dump_tree routine know how far down in the tree they're being called, by passing a depth parameter between them:

  sub dump_tree {
    my $n = $_[0];
    my $depth = $_[1];
    $depth = 0 unless defined $depth;
    print
      "  " x $depth,
      ...stuff...
    foreach my $s (@{$n->{'successors'}}) {
      dump_tree($s, $depth + 1);
    }
  }

When we call dump_tree($n0), $depth (from $_[1]) is undefined, so gets set to 0, which translates into an indenting of no spaces. But when dump_tree invokes itself on $n0's children, those instances see $depth + 1 as their $_[1], giving appropriate indenting.

Footnote: Passing values around between different invocations of a recursive routine, as shown, is a decent way to share the data. Another way to share the data is by keeping it in a global variable, like $Depth, initially set to 0. Each time dump_tree is about to recurse, it must ++$Depth, and when it's back, it must --$Depth.

Or, if the reader is familiar with closures, consider this approach:

  sub dump_tree {
    # A wrapper around calls to a recursive closure:
    my $start_node = $_[0];
    my $depth = 0;
     # to be shared across calls to $recursor.
    my $recursor;
    $recursor = sub {
      my $n = $_[0];
      print "  " x $depth,
        ...stuff...
      ++$depth;
      foreach my $s (@{$n->{'successors'}}) {
        $recursor->($s);
      }
      --$depth;
    }
    $recursor->($start_node); # start recursing
    undef $recursor;
  }

The reader with an advanced understanding of Perl's reference-count-based garbage collection is invited to consider why it is currently necessary to undef $recursor (or otherwise change its value) after all recursion is done.

The reader whose mind is perverse in other ways is invited to consider how (or when!) passing a depth parameter around is unnecessary because of information that Perl's caller(N) function reports!

[end footnote]

Growing the Tree

Our dump_tree routine works fine for the sample tree we've got, so now we should get the program working on making its own trees, starting from a given board.

In Games::Alak (the CPAN-released version of Alak that uses essentially the same code that we're currently discussing the tree-related parts of), there is a routine called figure_successors that, given one childless node, will figure out all its possible successors. That is, it looks at the current board, looks at every piece belonging to the player whose turn it is, and considers the effect of moving each piece every possible way -- notably, it figures out the immediate payoff, and if that move would end the game, it notes that by setting an "endgame" entry in that node's hash. (That way, we know that that's a node that can't have successors.)

In the code for Games::Alak, figure_successors does all these things, in a rather straightforward way. I won't walk you through the details of the figure_successors code I've written, since the code has nothing much to do with trees, and is all just implementation of the Alak rules for what can move where, with what result. Espicially interested readers can puzzle over that part of code in the source listing in the archive from CPAN, but others can just assume that it works as described above.

But consider that figure_successors, regardless of its inner workings, does not grow the tree; it only makes one set of successors for one node at a time. It has to be up to a different routine to call figure_successors, and to keep applying it as needed, in order to make a nice big tree that our game-playing program can base its decisions on.

Now, we could do this by just starting from one node, applying figure_successors to it, then applying figure_successors on all the resulting children, and so on:

  sub grow {  # Just a first attempt at this!
    my $n = $_[0];
    figure_successors($n);
     unless
      @{$n->{'successors'}}
        # already has successors.
      or $n->{'endgame'}
        # can't have successors.
    }
    foreach my $s (@{$n->{'successors'}}) {
      grow($s); # recurse
    }
  }

If you have a game tree for tic-tac-toe, and you grow it without limitation (as above), you will soon enough have a fully "solved" tree, where every node that can have successors does, and all the leaves of the tree are all the possible endgames (where, in each case, the board is filled). But a game of Alak is different from tic-tac-toe, because it can, in theory, go on forever. For example, the following sequence of moves is quite possible:

  xxxx___oooo
  xxx_x__oooo
  xxx_x_o_ooo
  xxxx__o_ooo (x moved back)
  xxxx___oooo (o moved back)
  ...repeat forever...

So if you tried using our above attempt at a grow routine, Perl would happily start trying to construct an infinitely deep tree, containing an infinite number of nodes, consuming an infinite amount of memory, and requiring an infinite amount of time. As the old saying goes: "You can't have everything -- where would you put it?" So we have to place limits on how much we'll grow the tree.

There's more than one way to do this:

1. We could grow the tree until we hit some limit on the number of nodes we'll allow in the tree.

2. We could grow the tree until we hit some limit on the amount of time we're willing to spend.

3. Or we could grow the tree until it is fully fleshed out to a certain depth.

Since we already know to track depth (as we did in writing dump_tree), we'll do it that way, the third way. The implementation for that third approach is also pretty straightforward:

  $Max_depth = 3;
  sub grow {
    my $n = $_[0];
    my $depth = $_[1] || 0;
    figure_successors($n)
     unless
      $depth >= $Max_depth
      or @{$n->{'successors'}}
      or $n->{'endgame'}
    }
    foreach my $s (@{$n->{'successors'}}) {
      grow($s, $depth + 1);
    }
    # If we're at $Max_depth, then figure_successors
    #  didn't get called, so there's no successors
    #  to recurse under -- that's what stops recursion.
  }

If we start from a single node (whether it's a node for the starting board "xxxx___oooo", or for whatever board the computer is faced with), set $Max_depth to 4, and apply grow to it, it will grow the tree to include several hundred nodes.

Footnote: If at each move there are four pieces that can move, and they can each move right or left, the "branching factor" of the tree is eight, giving a tree with 1 (depth 0) + 8 (depth 1) + 8 ** 2 + 8 ** 3 + 8 ** 4 = 4681 nodes in it. But, in practice, not all pieces can move in both directions (none of the x pieces in "xxxx___oooo" can move left, for example), and there may be fewer than four pieces, if some were lost. For example, there are 801 nodes in a tree of depth four starting from "xxxx___oooo", suggesting an average branching factor of about five (801 ** (1/4) is about 5.3), not eight.

What we need to derive from that tree is the information about what are the best moves for X. The simplest way to consider the payoff of different successors is to just average them -- but what we average isn't always their immediate payoffs (because that'd leave us using only one generation of information), but the average payoff of their successors, if any. We can formalize this as:

  To figure a node's average payoff:
    If the node has successors:
      Figure each successor's average payoff.
      My average payoff is the average of theirs.
    Otherwise:
      My average payoff is my immediate payoff.

Since this involves recursing into the successors before doing anything with the current node, this will traverse the tree in post-order.

We could work that up as a routine of its own, and apply that to the tree after we've applied grow to it. But since we'd never grow the tree without also figuring the average benefit, we might as well make that figuring part of the grow routine itself:

  $Max_depth = 3;
  sub grow {
    my $n = $_[0];
    my $depth = $_[1] || 0;
    figure_successors($n);
     unless
      $depth >= $Max_depth
      or @{$n->{'successors'}}
      or $n->{'endgame'}
    }

    if(@{$n->{'successors'}}) {
      my $a_payoff_sum = 0;
      foreach my $s (@{$n->{'successors'}}) {
        grow($s, $depth + 1);  # RECURSE
        $a_payoff_sum += $s->{'average_payoff'};
      }
      $n->{'average_payoff'}
       = $a_payoff_sum / @{$n->{'successors'}};
    } else {
      $n->{'average_payoff'}
       = $n->{'last_move_payoff'};
    }
      }

So, by time grow has applied to a node (wherever in the tree it is), it will have figured successors if possible (which, in turn, sets last_move_payoff for each node it creates), and will have set average_benefit.

Beyond this, all that's needed is to start the board out with a root note of "xxxx___oooo", and have the computer (X) take turns with the user (O) until someone wins. Whenever it's O's turn, Games::Alak presents a prompt to the user, letting him know the state of the current board, and asking what move he selects. When it's X's turn, the computer grows the game tree as necessary (using just the grow routine from above), then selects the move with the highest average payoff (or one of the highest, in case of a tie).

In either case, "selecting" a move means just setting that move's node as the new root of the program's game tree. Its sibling nodes and their descendants (the boards that didn't get selected) and its parent node will be erased from memory, since they will no longer be in use (as Perl can tell by the fact that nothing holds references to them anymore).

The interface code in Games::Alak (the code that prompts the user for his move) actually supports quite a few options besides just moving -- including dumping the game tree to a specified depth (using a slightly fancier version of dump_tree, above), resetting the game, changing $Max_depth in the middle of the game, and quitting the game. Like figure_successors, it's a bit too long to print here, but interested users are welcome to peruse (and freely modify) the code, as well as to enjoy just playing the game.

Now, in practice, there's more to game trees than this: for games with a larger branching factor than Alak has (which is most!), game trees of depth four or larger would contain too many nodes to be manageable, most of those nodes being strategically quite uninteresting for either player; dealing with game trees specifically is therefore a matter of recognizing uninteresting contingencies and not bothering to grow the tree under them.

Footnote: For example, to choose a straightforward case: if O has a choice between moves that put him in immediate danger of X winning and moves that don't, then O won't ever choose the dangerous moves (and if he does, the computer will know enough to end the game), so there's no point in growing the tree any further beneath those nodes.

But this sample implementation should illustrate the basics of how to build and manipulate a simple tree structure in memory. And once you've understood the basics of tree storage here, you should be ready to better understand the complexities and peculiarities of other systems for creating, accessing, and changing trees, including Tree::DAG_Node, HTML::Element, XML::DOM, or related formalisms like XPath and XSL.

[end body of article]

[Author Credit]

Sean M. Burke (sburke@cpan.org) is a tree-dwelling hominid.

References

Dewdney, A[lexander] K[eewatin]. 1984. Planiverse: Computer Contact with a Two-Dimensional World. Poseidon Press, New York.

Knuth, Donald Ervin. 1997. Art of Computer Programming, Volume 1, Third Edition: Fundamental Algorithms. Addison-Wesley, Reading, MA.

Wirth, Niklaus. 1976. Algorithms + Data Structures = Programs Prentice-Hall, Englewood Cliffs, NJ.

Worth, Stan and Allman Sheldon. Circa 1967. George of the Jungle theme. [music by Jay Ward.]

Wirth's classic, currently and lamentably out of print, has a good section on trees. I find it clearer than Knuth's (if not quite as encyclopedic), probably because Wirth's example code is in a block-structured high-level language (basically Pascal), instead of in assembler (MIX). I believe the book was re-issued in the 1980s under the titles Algorithms and Data Structures and, in a German edition, Algorithmen und Datenstrukturen. Cheap copies of these editions should be available through used book services such as abebooks.com.

Worth's classic, however, is available on the soundtrack to the 1997 George of the Jungle movie, as performed by The Presidents of the United States of America.

BACK

Return to the HTML::Tree docs.


HTML::Tree::Scanning -- article: "Scanning HTML"

  • Scanning HTML
    • HTML::Parser, HTML::TreeBuilder, and HTML::Element
    • Scanning HTML trees
    • Complex Criteria in Tree Scanning
    • A Case Study: Scanning Yahoo News's HTML
    • Regardez, duvet!
    • [Author Credit]
  • BACK

NAME

HTML::Tree::Scanning -- article: "Scanning HTML"

SYNOPSIS

  # This an article, not a module.

DESCRIPTION

The following article by Sean M. Burke first appeared in The Perl Journal #19 and is copyright 2000 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.

Scanning HTML

-- Sean M. Burke

In The Perl Journal issue 17, Ken MacFarlane's article "Parsing HTML with HTML::Parser" describes how the HTML::Parser module scans HTML source as a stream of start-tags, end-tags, text, comments, etc. In TPJ #18, my "Trees" article kicked around the idea of tree-shaped data structures. Now I'll try to tie it together, in a discussion of HTML trees.

The CPAN module HTML::TreeBuilder takes the tags that HTML::Parser picks out, and builds a parse tree -- a tree-shaped network of objects...

Footnote: And if you need a quick explanation of objects, see my TPJ17 article "A User's View of Object-Oriented Modules"; or go whole hog and get Damian Conway's excellent book Object-Oriented Perl, from Manning Publications.

...representing the structured content of the HTML document. And once the document is parsed as a tree, you'll find the common tasks of extracting data from that HTML document/tree to be quite straightforward.

HTML::Parser, HTML::TreeBuilder, and HTML::Element

You use HTML::TreeBuilder to make a parse tree out of an HTML source file, by simply saying:

  use HTML::TreeBuilder;
  my $tree = HTML::TreeBuilder->new();
  $tree->parse_file('foo.html');

and then $tree contains a parse tree built from the HTML source from the file "foo.html". The way this parse tree is represented is with a network of objects -- $tree is the root, an element with tag-name "html", and its children typically include a "head" and "body" element, and so on. Elements in the tree are objects of the class HTML::Element.

So, if you take this source:

  <html><head><title>Doc 1</title></head>
  <body>
  Stuff <hr> 2000-08-17
  </body></html>

and feed it to HTML::TreeBuilder, it'll return a tree of objects that looks like this:

               html
             /      \
         head        body
        /          /   |  \
     title    "Stuff"  hr  "2000-08-17"
       |
    "Doc 1"

This is a pretty simple document, but if it were any more complex, it'd be a bit hard to draw in that style, since it's sprawl left and right. The same tree can be represented a bit more easily sideways, with indenting:

  . html
     . head
        . title
           . "Doc 1"
     . body
        . "Stuff"
        . hr
        . "2000-08-17"

Either way expresses the same structure. In that structure, the root node is an object of the class HTML::Element

Footnote: Well actually, the root is of the class HTML::TreeBuilder, but that's just a subclass of HTML::Element, plus the few extra methods like parse_file that elaborate the tree

, with the tag name "html", and with two children: an HTML::Element object whose tag names are "head" and "body". And each of those elements have children, and so on down. Not all elements (as we'll call the objects of class HTML::Element) have children -- the "hr" element doesn't. And note all nodes in the tree are elements -- the text nodes ("Doc 1", "Stuff", and "2000-08-17") are just strings.

Objects of the class HTML::Element each have three noteworthy attributes:

_tag -- (best accessed as $e->tag) this element's tag-name, lowercased (e.g., "em" for an "em" element).

Footnote: Yes, this is misnamed. In proper SGML terminology, this is instead called a "GI", short for "generic identifier"; and the term "tag" is used for a token of SGML source that represents either the start of an element (a start-tag like "<em lang='fr'>") or the end of an element (an end-tag like "</em>". However, since more people claim to have been abducted by aliens than to have ever seen the SGML standard, and since both encounters typically involve a feeling of "missing time", it's not surprising that the terminology of the SGML standard is not closely followed.

_parent -- (best accessed as $e->parent) the element that is $obj's parent, or undef if this element is the root of its tree.
_content -- (best accessed as $e->content_list) the list of nodes (i.e., elements or text segments) that are $e's children.

Moreover, if an element object has any attributes in the SGML sense of the word, then those are readable as $e->attr('name') -- for example, with the object built from having parsed "<a id='foo'>bar</a>", $e->attr('id') will return the string "foo". Moreover, $e->tag on that object returns the string "a", $e->content_list returns a list consisting of just the single scalar "bar", and $e->parent returns the object that's this node's parent -- which may be, for example, a "p" element.

And that's all that there is to it -- you throw HTML source at TreeBuilder, and it returns a tree built of HTML::Element objects and some text strings.

However, what do you do with a tree of objects? People code information into HTML trees not for the fun of arranging elements, but to represent the structure of specific text and images -- some text is in this "li" element, some other text is in that heading, some images are in that other table cell that has those attributes, and so on.

Now, it may happen that you're rendering that whole HTML tree into some layout format. Or you could be trying to make some systematic change to the HTML tree before dumping it out as HTML source again. But, in my experience, by far the most common programming task that Perl programmers face with HTML is in trying to extract some piece of information from a larger document. Since that's so common (and also since it involves concepts that are basic to more complex tasks), that is what the rest of this article will be about.

Scanning HTML trees

Suppose you have a thousand HTML documents, each of them a press release. They all start out:

  [...lots of leading images and junk...]
  <h1>ConGlomCo to Open New Corporate Office in Ougadougou</h1>
  BAKERSFIELD, CA, 2000-04-24 -- ConGlomCo's vice president in charge
  of world conquest, Rock Feldspar, announced today the opening of a
  new office in Ougadougou, the capital city of Burkino Faso, gateway
  to the bustling "Silicon Sahara" of Africa...
  [...etc...]

...and what you've got to do is, for each document, copy whatever text is in the "h1" element, so that you can, for example, make a table of contents of it. Now, there are three ways to do this:

  • You can just use a regexp to scan the file for a text pattern.

    For many very simple tasks, this will do fine. Many HTML documents are, in practice, very consistently formatted as far as placement of linebreaks and whitespace, so you could just get away with scanning the file like so:

      sub get_heading {
    my $filename = $_[0];
    local *HTML;
    open(HTML, $filename)
      or die "Couldn't open $filename);
    my $heading;
   Line:
    while(<HTML>) {
      if( m{<h1>(.*?)</h1>}i ) {  # match it!
        $heading = $1;
        last Line;
      }
    }
    close(HTML);
    warn "No heading in $filename?"
     unless defined $heading;
    return $heading;
  }

    This is quick and fast, but awfully fragile -- if there's a newline in the middle of a heading's text, it won't match the above regexp, and you'll get an error. The regexp will also fail if the "h1" element's start-tag has any attributes. If you have to adapt your code to fit more kinds of start-tags, you'll end up basically reinventing part of HTML::Parser, at which point you should probably just stop, and use HTML::Parser itself:

  • You can use HTML::Parser to scan the file for an "h1" start-tag token, then capture all the text tokens until the "h1" close-tag. This approach is extensively covered in the Ken MacFarlane's TPJ17 article "Parsing HTML with HTML::Parser". (A variant of this approach is to use HTML::TokeParser, which presents a different and rather handier interface to the tokens that HTML::Parser picks out.)

    Using HTML::Parser is less fragile than our first approach, since it's not sensitive to the exact internal formatting of the start-tag (much less whether it's split across two lines). However, when you need more information about the context of the "h1" element, or if you're having to deal with any of the tricky bits of HTML, such as parsing of tables, you'll find out the flat list of tokens that HTML::Parser returns isn't immediately useful. To get something useful out of those tokens, you'll need to write code that knows some things about what elements take no content (as with "hr" elements), and that a "</p>" end-tags are omissible, so a "<p>" will end any currently open paragraph -- and you're well on your way to pointlessly reinventing much of the code in HTML::TreeBuilder

    Footnote: And, as the person who last rewrote that module, I can attest that it wasn't terribly easy to get right! Never underestimate the perversity of people coding HTML.

    , at which point you should probably just stop, and use HTML::TreeBuilder itself:

  • You can use HTML::Treebuilder, and scan the tree of element objects that you get back.

The last approach, using HTML::TreeBuilder, is the diametric opposite of first approach: The first approach involves just elementary Perl and one regexp, whereas the TreeBuilder approach involves being at home with the concept of tree-shaped data structures and modules with object-oriented interfaces, as well as with the particular interfaces that HTML::TreeBuilder and HTML::Element provide.

However, what the TreeBuilder approach has going for it is that it's the most robust, because it involves dealing with HTML in its "native" format -- it deals with the tree structure that HTML code represents, without any consideration of how the source is coded and with what tags omitted.

So, to extract the text from the "h1" elements of an HTML document:

  sub get_heading {
    my $tree = HTML::TreeBuilder->new;
    $tree->parse_file($_[0]);   # !
    my $heading;
    my $h1 = $tree->look_down('_tag', 'h1');  # !
    if($h1) {
      $heading = $h1->as_text;   # !
    } else {
      warn "No heading in $_[0]?";
    }
    $tree->delete; # clear memory!
    return $heading;
  }

This uses some unfamiliar methods that need explaining. The parse_file method that we've seen before, builds a tree based on source from the file given. The delete method is for marking a tree's contents as available for garbage collection, when you're done with the tree. The as_text method returns a string that contains all the text bits that are children (or otherwise descendants) of the given node -- to get the text content of the $h1 object, we could just say:

  $heading = join '', $h1->content_list;

but that will work only if we're sure that the "h1" element's children will be only text bits -- if the document contained:

  <h1>Local Man Sees <cite>Blade</cite> Again</h1>

then the sub-tree would be:

  . h1
    . "Local Man Sees "
    . cite
      . "Blade"
    . " Again'

so join '', $h1->content_list will be something like:

  Local Man Sees HTML::Element=HASH(0x15424040) Again

whereas $h1->as_text would yield:

  Local Man Sees Blade Again

and depending on what you're doing with the heading text, you might want the as_HTML method instead. It returns the (sub)tree represented as HTML source. $h1->as_HTML would yield:

  <h1>Local Man Sees <cite>Blade</cite> Again</h1>

However, if you wanted the contents of $h1 as HTML, but not the $h1 itself, you could say:

  join '',
    map(
      ref($_) ? $_->as_HTML : $_,
      $h1->content_list
    )

This map iterates over the nodes in $h1's list of children; and for each node that's just a text bit (as "Local Man Sees " is), it just passes through that string value, and for each node that's an actual object (causing ref to be true), as_HTML will used instead of the string value of the object itself (which would be something quite useless, as most object values are). So that as_HTML for the "cite" element will be the string "<cite>Blade</cite>". And then, finally, join just puts into one string all the strings that the map returns.

Last but not least, the most important method in our get_heading sub is the look_down method. This method looks down at the subtree starting at the given object ($h1), looking for elements that meet criteria you provide.

The criteria are specified in the method's argument list. Each criterion can consist of two scalars, a key and a value, which express that you want elements that have that attribute (like "_tag", or "src") with the given value ("h1"); or the criterion can be a reference to a subroutine that, when called on the given element, returns true if that is a node you're looking for. If you specify several criteria, then that's taken to mean that you want all the elements that each satisfy all the criteria. (In other words, there's an "implicit AND".)

And finally, there's a bit of an optimization -- if you call the look_down method in a scalar context, you get just the first node (or undef if none) -- and, in fact, once look_down finds that first matching element, it doesn't bother looking any further.

So the example:

  $h1 = $tree->look_down('_tag', 'h1');

returns the first element at-or-under $tree whose "_tag" attribute has the value "h1".

Complex Criteria in Tree Scanning

Now, the above look_down code looks like a lot of bother, with barely more benefit than just grepping the file! But consider if your criteria were more complicated -- suppose you found that some of the press releases that you were scanning had several "h1" elements, possibly before or after the one you actually want. For example:

  <h1><center>Visit Our Corporate Partner
   <br><a href="/dyna/clickthru"
     ><img src="/dyna/vend_ad"></a>
  </center></h1>
  <h1><center>ConGlomCo President Schreck to Visit Regional HQ
   <br><a href="/photos/Schreck_visit_large.jpg"
     ><img src="/photos/Schreck_visit.jpg"></a>
  </center></h1>

Here, you want to ignore the first "h1" element because it contains an ad, and you want the text from the second "h1". The problem is in formalizing the way you know that it's an ad. Since ad banners are always entreating you to "visit" the sponsoring site, you could exclude "h1" elements that contain the word "visit" under them:

  my $real_h1 = $tree->look_down(
    '_tag', 'h1',
    sub {
      $_[0]->as_text !~ m/\bvisit/i
    }
  );

The first criterion looks for "h1" elements, and the second criterion limits those to only the ones whose text content doesn't match m/\bvisit/. But unfortunately, that won't work for our example, since the second "h1" mentions "ConGlomCo President Schreck to Visit Regional HQ".

Instead you could try looking for the first "h1" element that doesn't contain an image:

  my $real_h1 = $tree->look_down(
    '_tag', 'h1',
    sub {
      not $_[0]->look_down('_tag', 'img')
    }
  );

This criterion sub might seem a bit odd, since it calls look_down as part of a larger look_down operation, but that's fine. Note that when considered as a boolean value, a look_down in a scalar context value returns false (specifically, undef) if there's no matching element at or under the given element; and it returns the first matching element (which, being a reference and object, is always a true value), if any matches. So, here,

  sub {
    not $_[0]->look_down('_tag', 'img')
  }

means "return true only if this element has no 'img' element as descendants (and isn't an 'img' element itself)."

This correctly filters out the first "h1" that contains the ad, but it also incorrectly filters out the second "h1" that contains a non-advertisement photo besides the headline text you want.

There clearly are detectable differences between the first and second "h1" elements -- the only second one contains the string "Schreck", and we could just test for that:

  my $real_h1 = $tree->look_down(
    '_tag', 'h1',
    sub {
      $_[0]->as_text =~ m{Schreck}
    }
  );

And that works fine for this one example, but unless all thousand of your press releases have "Schreck" in the headline, that's just not a general solution. However, if all the ads-in-"h1"s that you want to exclude involve a link whose URL involves "/dyna/", then you can use that:

  my $real_h1 = $tree->look_down(
    '_tag', 'h1',
    sub {
      my $link = $_[0]->look_down('_tag','a');
      return 1 unless $link;
        # no link means it's fine
      return 0 if $link->attr('href') =~ m{/dyna/};
        # a link to there is bad
      return 1; # otherwise okay
    }
  );

Or you can look at it another way and say that you want the first "h1" element that either contains no images, or else whose image has a "src" attribute whose value contains "/photos/":

  my $real_h1 = $tree->look_down(
    '_tag', 'h1',
    sub {
      my $img = $_[0]->look_down('_tag','img');
      return 1 unless $img;
        # no image means it's fine
      return 1 if $img->attr('src') =~ m{/photos/};
        # good if a photo
      return 0; # otherwise bad
    }
  );

Recall that this use of look_down in a scalar context means to return the first element at or under $tree that matches all the criteria. But if you notice that you can formulate criteria that'll match several possible "h1" elements, some of which may be bogus but the last one of which is always the one you want, then you can use look_down in a list context, and just use the last element of that list:

  my @h1s = $tree->look_down(
    '_tag', 'h1',
    ...maybe more criteria...
  );
  die "What, no h1s here?" unless @h1s;
  my $real_h1 = $h1s[-1]; # last or only

A Case Study: Scanning Yahoo News's HTML

The above (somewhat contrived) case involves extracting data from a bunch of pre-existing HTML files. In that sort of situation, if your code works for all the files, then you know that the code works -- since the data it's meant to handle won't go changing or growing; and, typically, once you've used the program, you'll never need to use it again.

The other kind of situation faced in many data extraction tasks is where the program is used recurringly to handle new data -- such as from ever-changing Web pages. As a real-world example of this, consider a program that you could use (suppose it's crontabbed) to extract headline-links from subsections of Yahoo News (http://dailynews.yahoo.com/).

Yahoo News has several subsections:

http://dailynews.yahoo.com/h/tc/ for technology news
http://dailynews.yahoo.com/h/sc/ for science news
http://dailynews.yahoo.com/h/hl/ for health news
http://dailynews.yahoo.com/h/wl/ for world news
http://dailynews.yahoo.com/h/en/ for entertainment news

and others. All of them are built on the same basic HTML template -- and a scarily complicated template it is, especially when you look at it with an eye toward making up rules that will select where the real headline-links are, while screening out all the links to other parts of Yahoo, other news services, etc. You will need to puzzle over the HTML source, and scrutinize the output of $tree->dump on the parse tree of that HTML.

Sometimes the only way to pin down what you're after is by position in the tree. For example, headlines of interest may be in the third column of the second row of the second table element in a page:

  my $table = ( $tree->look_down('_tag','table') )[1];
  my $row2  = ( $table->look_down('_tag', 'tr' ) )[1];
  my $col3  = ( $row2->look-down('_tag', 'td')   )[2];
  ...then do things with $col3...

Or they may be all the links in a "p" element that has at least three "br" elements as children:

  my $p = $tree->look_down(
    '_tag', 'p',
    sub {
      2 < grep { ref($_) and $_->tag eq 'br' }
               $_[0]->content_list
    }
  );
  @links = $p->look_down('_tag', 'a');

But almost always, you can get away with looking for properties of the of the thing itself, rather than just looking for contexts. Now, if you're lucky, the document you're looking through has clear semantic tagging, such is as useful in CSS -- note the class="headlinelink" bit here:

  <a href="...long_news_url..." class="headlinelink">Elvis
  seen in tortilla</a>

If you find anything like that, you could leap right in and select links with:

  @links = $tree->look_down('class','headlinelink');

Regrettably, your chances of seeing any sort of semantic markup principles really being followed with actual HTML are pretty thin.

Footnote: In fact, your chances of finding a page that is simply free of HTML errors are even thinner. And surprisingly, sites like Amazon or Yahoo are typically worse as far as quality of code than personal sites whose entire production cycle involves simply being saved and uploaded from Netscape Composer.

The code may be sort of "accidentally semantic", however -- for example, in a set of pages I was scanning recently, I found that looking for "td" elements with a "width" attribute value of "375" got me exactly what I wanted. No-one designing that page ever conceived of "width=375" as meaning "this is a headline", but if you impute it to mean that, it works.

An approach like this happens to work for the Yahoo News code, because the headline-links are distinguished by the fact that they (and they alone) contain a "b" element:

  <a href="...long_news_url..."><b>Elvis seen in tortilla</b></a>

or, diagrammed as a part of the parse tree:

  . a  [href="...long_news_url..."]
    . b
      . "Elvis seen in tortilla"

A rule that matches these can be formalized as "look for any 'a' element that has only one daugher node, which must be a 'b' element". And this is what it looks like when cooked up as a look_down expression and prefaced with a bit of code that retrieves the text of the given Yahoo News page and feeds it to TreeBuilder:

  use strict;
  use HTML::TreeBuilder 2.97;
  use LWP::UserAgent;
  sub get_headlines {
    my $url = $_[0] || die "What URL?";

    my $response = LWP::UserAgent->new->request(
      HTTP::Request->new( GET => $url )
    );
    unless($response->is_success) {
      warn "Couldn't get $url: ", $response->status_line, "\n";
      return;
    }

    my $tree = HTML::TreeBuilder->new();
    $tree->parse($response->content);
    $tree->eof;

    my @out;
    foreach my $link (
      $tree->look_down(   # !
        '_tag', 'a',
        sub {
          return unless $_[0]->attr('href');
          my @c = $_[0]->content_list;
          @c == 1 and ref $c[0] and $c[0]->tag eq 'b';
        }
      )
    ) {
      push @out, [ $link->attr('href'), $link->as_text ];
    }

    warn "Odd, fewer than 6 stories in $url!" if @out < 6;
    $tree->delete;
    return @out;
      }

...and add a bit of code to actually call that routine and display the results...

  foreach my $section (qw[tc sc hl wl en]) {
    my @links = get_headlines(
      "http://dailynews.yahoo.com/h/$section/"
    );
    print
      $section, ": ", scalar(@links), " stories\n",
      map(("  ", $_->[0], " : ", $_->[1], "\n"), @links),
      "\n";
  }

And we've got our own headline-extractor service! This in and of itself isn't no amazingly useful (since if you want to see the headlines, you can just look at the Yahoo News pages), but it could easily be the basis for quite useful features like filtering the headlines for matching certain keywords of interest to you.

Now, one of these days, Yahoo News will decide to change its HTML template. When this happens, this will appear to the above program as there being no links that meet the given criteria; or, less likely, dozens of erroneous links will meet the criteria. In either case, the criteria will have to be changed for the new template; they may just need adjustment, or you may need to scrap them and start over.

Regardez, duvet!

It's often quite a challenge to write criteria to match the desired parts of an HTML parse tree. Very often you can pull it off with a simple $tree->look_down('_tag', 'h1'), but sometimes you do have to keep adding and refining criteria, until you might end up with complex filters like what I've shown in this article. The benefit to learning how to deal with HTML parse trees is that one main search tool, the look_down method, can do most of the work, making simple things easy, while still making hard things possible.

[end body of article]

[Author Credit]

Sean M. Burke (sburke@cpan.org) is the current maintainer of HTML::TreeBuilder and HTML::Element, both originally by Gisle Aas.

Sean adds: "I'd like to thank the folks who listened to me ramble incessantly about HTML::TreeBuilder and HTML::Element at this year's Yet Another Perl Conference and O'Reilly Open Source Software Convention."

BACK

Return to the HTML::Tree docs.


HTML::TreeBuilder - Parser that builds a HTML syntax tree

  • METHODS AND ATTRIBUTES
  • HTML AND ITS DISCONTENTS
  • TRANSLATIONS?
  • BUGS
  • BUG REPORTS
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

HTML::TreeBuilder - Parser that builds a HTML syntax tree

SYNOPSIS

  foreach my $file_name (@ARGV) {
    my $tree = HTML::TreeBuilder->new; # empty tree
    $tree->parse_file($file_name);
    print "Hey, here's a dump of the parse tree of $file_name:\n";
    $tree->dump; # a method we inherit from HTML::Element
    print "And here it is, bizarrely rerendered as HTML:\n",
      $tree->as_HTML, "\n";

    # Now that we're done with it, we must destroy it.
    $tree = $tree->delete;
  }

DESCRIPTION

(This class is part of the HTML::Tree dist.)

This class is for HTML syntax trees that get built out of HTML source. The way to use it is to:

1. start a new (empty) HTML::TreeBuilder object,

2. then use one of the methods from HTML::Parser (presumably with $tree->parse_file($filename) for files, or with $tree->parse($document_content) and $tree->eof if you've got the content in a string) to parse the HTML document into the tree $tree.

(You can combine steps 1 and 2 with the "new_from_file" or "new_from_content" methods.)

2b. call $root->elementify() if you want.

3. do whatever you need to do with the syntax tree, presumably involving traversing it looking for some bit of information in it,

4. and finally, when you're done with the tree, call $tree->delete() to erase the contents of the tree from memory. This kind of thing usually isn't necessary with most Perl objects, but it's necessary for TreeBuilder objects. See HTML::Element for a more verbose explanation of why this is the case.

METHODS AND ATTRIBUTES

Objects of this class inherit the methods of both HTML::Parser and HTML::Element. The methods inherited from HTML::Parser are used for building the HTML tree, and the methods inherited from HTML::Element are what you use to scrutinize the tree. Besides this (HTML::TreeBuilder) documentation, you must also carefully read the HTML::Element documentation, and also skim the HTML::Parser documentation -- probably only its parse and parse_file methods are of interest.

Most of the following methods native to HTML::TreeBuilder control how parsing takes place; they should be set before you try parsing into the given object. You can set the attributes by passing a TRUE or FALSE value as argument. E.g., $root->implicit_tags returns the current setting for the implicit_tags option, $root->implicit_tags(1) turns that option on, and $root->implicit_tags(0) turns it off.

$root = HTML::TreeBuilder->new_from_file(...)

This "shortcut" constructor merely combines constructing a new object (with the "new" method, below), and calling $new->parse_file(...) on it. Returns the new object. Note that this provides no way of setting any parse options like store_comments (for that, call new, and then set options, before calling parse_file). See the notes (below) on parameters to parse_file.

$root = HTML::TreeBuilder->new_from_content(...)

This "shortcut" constructor merely combines constructing a new object (with the "new" method, below), and calling for(...){$new->parse($_)} and $new->eof on it. Returns the new object. Note that this provides no way of setting any parse options like store_comments (for that, call new, and then set options, before calling parse_file). Example usages: HTML::TreeBuilder->new_from_content(@lines), or HTML::TreeBuilder->new_from_content($content)

$root = HTML::TreeBuilder->new()

This creates a new HTML::TreeBuilder object. This method takes no attributes.

$root->parse_file(...)

[An important method inherited from HTML::Parser, which see. Current versions of HTML::Parser can take a filespec, or a filehandle object, like *FOO, or some object from class IO::Handle, IO::File, IO::Socket) or the like. I think you should check that a given file exists before calling $root->parse_file($filespec).]

$root->parse(...)

[A important method inherited from HTML::Parser, which see. See the note below for $root->eof().]

$root->eof()

This signals that you're finished parsing content into this tree; this runs various kinds of crucial cleanup on the tree. This is called for you when you call $root->parse_file(...), but not when you call $root->parse(...). So if you call $root->parse(...), then you must call $root->eof() once you've finished feeding all the chunks to parse(...), and before you actually start doing anything else with the tree in $root.

$root->parse_content(...)

Basically a happly alias for $root->parse(...); $root->eof. Takes the exact same arguments as $root->parse().

$root->delete()

[An important method inherited from HTML::Element, which see.]

$root->elementify()

This changes the class of the object in $root from HTML::TreeBuilder to the class used for all the rest of the elements in that tree (generally HTML::Element). Returns $root.

For most purposes, this is unnecessary, but if you call this after (after!!) you've finished building a tree, then it keeps you from accidentally trying to call anything but HTML::Element methods on it. (I.e., if you accidentally call $root->parse_file(...) on the already-complete and elementified tree, then instead of charging ahead and wreaking havoc, it'll throw a fatal error -- since $root is now an object just of class HTML::Element which has no parse_file method.

Note that elementify currently deletes all the private attributes of $root except for "_tag", "_parent", "_content", "_pos", and "_implicit". If anyone requests that I change this to leave in yet more private attributes, I might do so, in future versions.

@nodes = $root->guts()
$parent_for_nodes = $root->guts()

In list context (as in the first case), this method returns the topmost non-implicit nodes in a tree. This is useful when you're parsing HTML code that you know doesn't expect an HTML document, but instead just a fragment of an HTML document. For example, if you wanted the parse tree for a file consisting of just this:

  <li>I like pie!

Then you would get that with @nodes = $root->guts();. It so happens that in this case, @nodes will contain just one element object, representing the "li" node (with "I like pie!" being its text child node). However, consider if you were parsing this:

  <hr>Hooboy!<hr>

In that case, $root->guts() would return three items: an element object for the first "hr", a text string "Hooboy!", and another "hr" element object.

For cases where you want definitely one element (so you can treat it as a "document fragment", roughly speaking), call guts() in scalar context, as in $parent_for_nodes = $root->guts(). That works like guts() in list context; in fact, guts() in list context would have returned exactly one value, and if it would have been an object (as opposed to a text string), then that's what guts in scalar context will return. Otherwise, if guts() in list context would have returned no values at all, then guts() in scalar context returns undef. In all other cases, guts() in scalar context returns an implicit 'div' element node, with children consisting of whatever nodes guts() in list context would have returned. Note that that may detach those nodes from $root's tree.

@nodes = $root->disembowel()
$parent_for_nodes = $root->disembowel()

The disembowel() method works just like the guts() method, except that disembowel definitively destroys the tree above the nodes that are returned. Usually when you want the guts from a tree, you're just going to toss out the rest of the tree anyway, so this saves you the bother. (Remember, "disembowel" means "remove the guts from".)

$root->implicit_tags(value)

Setting this attribute to true will instruct the parser to try to deduce implicit elements and implicit end tags. If it is false you get a parse tree that just reflects the text as it stands, which is unlikely to be useful for anything but quick and dirty parsing. (In fact, I'd be curious to hear from anyone who finds it useful to have implicit_tags set to false.) Default is true.

Implicit elements have the implicit() attribute set.

$root->implicit_body_p_tag(value)

This controls an aspect of implicit element behavior, if implicit_tags is on: If a text element (PCDATA) or a phrasal element (such as "<em>") is to be inserted under "<body>", two things can happen: if implicit_body_p_tag is true, it's placed under a new, implicit "<p>" tag. (Past DTDs suggested this was the only correct behavior, and this is how past versions of this module behaved.) But if implicit_body_p_tag is false, nothing is implicated -- the PCDATA or phrasal element is simply placed under "<body>". Default is false.

$root->ignore_unknown(value)

This attribute controls whether unknown tags should be represented as elements in the parse tree, or whether they should be ignored. Default is true (to ignore unknown tags.)

$root->ignore_text(value)

Do not represent the text content of elements. This saves space if all you want is to examine the structure of the document. Default is false.

$root->ignore_ignorable_whitespace(value)

If set to true, TreeBuilder will try to avoid creating ignorable whitespace text nodes in the tree. Default is true. (In fact, I'd be interested in hearing if there's ever a case where you need this off, or where leaving it on leads to incorrect behavior.)

$root->no_space_compacting(value)

This determines whether TreeBuilder compacts all whitespace strings in the document (well, outside of PRE or TEXTAREA elements), or leaves them alone. Normally (default, value of 0), each string of contiguous whitespace in the document is turned into a single space. But that's not done if no_space_compacting is set to 1.

Setting no_space_compacting to 1 might be useful if you want to read in a tree just to make some minor changes to it before writing it back out.

This method is experimental. If you use it, be sure to report any problems you might have with it.

$root->p_strict(value)

If set to true (and it defaults to false), TreeBuilder will take a narrower than normal view of what can be under a "p" element; if it sees a non-phrasal element about to be inserted under a "p", it will close that "p". Otherwise it will close p elements only for other "p"'s, headings, and "form" (altho the latter may be removed in future versions).

For example, when going thru this snippet of code,

  <p>stuff
  <ul>

TreeBuilder will normally (with p_strict false) put the "ul" element under the "p" element. However, with p_strict set to true, it will close the "p" first.

In theory, there should be strictness options like this for other/all elements besides just "p"; but I treat this as a specal case simply because of the fact that "p" occurs so frequently and its end-tag is omitted so often; and also because application of strictness rules at parse-time across all elements often makes tiny errors in HTML coding produce drastically bad parse-trees, in my experience.

If you find that you wish you had an option like this to enforce content-models on all elements, then I suggest that what you want is content-model checking as a stage after TreeBuilder has finished parsing.

$root->store_comments(value)

This determines whether TreeBuilder will normally store comments found while parsing content into $root. Currently, this is off by default.

$root->store_declarations(value)

This determines whether TreeBuilder will normally store markup declarations found while parsing content into $root. This is on by default.

$root->store_pis(value)

This determines whether TreeBuilder will normally store processing instructions found while parsing content into $root -- assuming a recent version of HTML::Parser (old versions won't parse PIs correctly). Currently, this is off (false) by default.

It is somewhat of a known bug (to be fixed one of these days, if anyone needs it?) that PIs in the preamble (before the "html" start-tag) end up actually under the "html" element.

$root->warn(value)

This determines whether syntax errors during parsing should generate warnings, emitted via Perl's warn function.

This is off (false) by default.

HTML AND ITS DISCONTENTS

HTML is rather harder to parse than people who write it generally suspect.

Here's the problem: HTML is a kind of SGML that permits "minimization" and "implication". In short, this means that you don't have to close every tag you open (because the opening of a subsequent tag may implicitly close it), and if you use a tag that can't occur in the context you seem to using it in, under certain conditions the parser will be able to realize you mean to leave the current context and enter the new one, that being the only one that your code could correctly be interpreted in.

Now, this would all work flawlessly and unproblematically if: 1) all the rules that both prescribe and describe HTML were (and had been) clearly set out, and 2) everyone was aware of these rules and wrote their code in compliance to them.

However, it didn't happen that way, and so most HTML pages are difficult if not impossible to correctly parse with nearly any set of straightforward SGML rules. That's why the internals of HTML::TreeBuilder consist of lots and lots of special cases -- instead of being just a generic SGML parser with HTML DTD rules plugged in.

TRANSLATIONS?

The techniques that HTML::TreeBuilder uses to perform what I consider very robust parses on everyday code are not things that can work only in Perl. To date, the algorithms at the center of HTML::TreeBuilder have been implemented only in Perl, as far as I know; and I don't foresee getting around to implementing them in any other language any time soon.

If, however, anyone is looking for a semester project for an applied programming class (or if they merely enjoy extra-curricular masochism), they might do well to see about choosing as a topic the implementation/adaptation of these routines to any other interesting programming language that you feel currently suffers from a lack of robust HTML-parsing. I welcome correspondence on this subject, and point out that one can learn a great deal about languages by trying to translate between them, and then comparing the result.

The HTML::TreeBuilder source may seem long and complex, but it is rather well commented, and symbol names are generally self-explanatory. (You are encouraged to read the Mozilla HTML parser source for comparison.) Some of the complexity comes from little-used features, and some of it comes from having the HTML tokenizer (HTML::Parser) being a separate module, requiring somewhat of a different interface than you'd find in a combined tokenizer and tree-builder. But most of the length of the source comes from the fact that it's essentially a long list of special cases, with lots and lots of sanity-checking, and sanity-recovery -- because, as Roseanne Rosannadanna once said, "it's always something".

Users looking to compare several HTML parsers should look at the source for Raggett's Tidy (<http://www.w3.org/People/Raggett/tidy/>), Mozilla (<http://www.mozilla.org/>), and possibly root around the browsers section of Yahoo to find the various open-source ones (<http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Browsers/>).

BUGS

* Framesets seem to work correctly now. Email me if you get a strange parse from a document with framesets.

* Really bad HTML code will, often as not, make for a somewhat objectionable parse tree. Regrettable, but unavoidably true.

* If you're running with implicit_tags off (God help you!), consider that $tree->content_list probably contains the tree or grove from the parse, and not $tree itself (which will, oddly enough, be an implicit 'html' element). This seems counter-intuitive and problematic; but seeing as how almost no HTML ever parses correctly with implicit_tags off, this interface oddity seems the least of your problems.

BUG REPORTS

When a document parses in a way different from how you think it should, I ask that you report this to me as a bug. The first thing you should do is copy the document, trim out as much of it as you can while still producing the bug in question, and then email me that mini-document and the code you're using to parse it, to the HTML::Tree bug queue at bug-html-tree at rt.cpan.org.

Include a note as to how it parses (presumably including its $tree->dump output), and then a careful and clear explanation of where you think the parser is going astray, and how you would prefer that it work instead.

SEE ALSO

the HTML::Tree manpage; the HTML::Parser manpage, the HTML::Element manpage, the HTML::Tagset manpage

the HTML::DOMbo manpage

COPYRIGHT

Copyright 1995-1998 Gisle Aas; copyright 1999-2002 Sean M. Burke. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Original author Gisle Aas <gisle@aas.no>, then Sean M. Burke, <sburke@cpan.org>, and now maintained by Andy Lester andy at petdance.com.


HTTP::Cookies - HTTP cookie jars

  • METHODS
  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Cookies - HTTP cookie jars

SYNOPSIS

  use HTTP::Cookies;
  $cookie_jar = HTTP::Cookies->new(
    file => "$ENV{'HOME'}/lwp_cookies.dat',
    autosave => 1,
  );

  use LWP;
  my $browser = LWP::UserAgent->new;
  $browser->cookie_jar($cookie_jar);

Or for an empty and temporary cookie jar:

  use LWP;
  my $browser = LWP::UserAgent->new;
  $browser->cookie_jar( {} );

DESCRIPTION

This class is for objects that represent a "cookie jar" -- that is, a database of all the HTTP cookies that a given LWP::UserAgent object knows about.

Cookies are a general mechanism which server side connections can use to both store and retrieve information on the client side of the connection. For more information about cookies refer to <URL:http://www.netscape.com/newsref/std/cookie_spec.html> and <URL:http://www.cookiecentral.com/>. This module also implements the new style cookies described in RFC 2965. The two variants of cookies are supposed to be able to coexist happily.

Instances of the class HTTP::Cookies are able to store a collection of Set-Cookie2: and Set-Cookie: headers and are able to use this information to initialize Cookie-headers in HTTP::Request objects. The state of a HTTP::Cookies object can be saved in and restored from files.

METHODS

The following methods are provided:

$cookie_jar = HTTP::Cookies->new

The constructor takes hash style parameters. The following parameters are recognized:

  file:            name of the file to restore cookies from and save cookies to
  autosave:        save during destruction (bool)
  ignore_discard:  save even cookies that are requested to be discarded (bool)
  hide_cookie2:    do not add Cookie2 header to requests

Future parameters might include (not yet implemented):

  max_cookies               300
  max_cookies_per_domain    20
  max_cookie_size           4096
  no_cookies   list of domain names that we never return cookies to
$cookie_jar->add_cookie_header( $request )

The add_cookie_header() method will set the appropriate Cookie:-header for the HTTP::Request object given as argument. The $request must have a valid url attribute before this method is called.

$cookie_jar->extract_cookies( $response )

The extract_cookies() method will look for Set-Cookie: and Set-Cookie2: headers in the HTTP::Response object passed as argument. Any of these headers that are found are used to update the state of the $cookie_jar.

$cookie_jar->set_cookie( $version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \%rest )

The set_cookie() method updates the state of the $cookie_jar. The $key, $val, $domain, $port and $path arguments are strings. The $path_spec, $secure, $discard arguments are boolean values. The $maxage value is a number indicating number of seconds that this cookie will live. A value <= 0 will delete this cookie. %rest defines various other attributes like "Comment" and "CommentURL".

$cookie_jar->save
$cookie_jar->save( $file )

This method file saves the state of the $cookie_jar to a file. The state can then be restored later using the load() method. If a filename is not specified we will use the name specified during construction. If the attribute ignore_discard is set, then we will even save cookies that are marked to be discarded.

The default is to save a sequence of "Set-Cookie3" lines. "Set-Cookie3" is a proprietary LWP format, not known to be compatible with any browser. The HTTP::Cookies::Netscape sub-class can be used to save in a format compatible with Netscape.

$cookie_jar->load
$cookie_jar->load( $file )

This method reads the cookies from the file and adds them to the $cookie_jar. The file must be in the format written by the save() method.

$cookie_jar->revert

This method empties the $cookie_jar and re-loads the $cookie_jar from the last save file.

$cookie_jar->clear
$cookie_jar->clear( $domain )
$cookie_jar->clear( $domain, $path )
$cookie_jar->clear( $domain, $path, $key )

Invoking this method without arguments will empty the whole $cookie_jar. If given a single argument only cookies belonging to that domain will be removed. If given two arguments, cookies belonging to the specified path within that domain are removed. If given three arguments, then the cookie with the specified key, path and domain is removed.

$cookie_jar->clear_temporary_cookies

Discard all temporary cookies. Scans for all cookies in the jar with either no expire field or a true discard flag. To be called when the user agent shuts down according to RFC 2965.

$cookie_jar->scan( \&callback )

The argument is a subroutine that will be invoked for each cookie stored in the $cookie_jar. The subroutine will be invoked with the following arguments:

  0  version
  1  key
  2  val
  3  path
  4  domain
  5  port
  6  path_spec
  7  secure
  8  expires
  9  discard
 10  hash
$cookie_jar->as_string
$cookie_jar->as_string( $skip_discardables )

The as_string() method will return the state of the $cookie_jar represented as a sequence of "Set-Cookie3" header lines separated by "\n". If $skip_discardables is TRUE, it will not return lines for cookies with the Discard attribute.

SEE ALSO

the HTTP::Cookies::Netscape manpage, the HTTP::Cookies::Microsoft manpage

COPYRIGHT

Copyright 1997-2002 Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Cookies::Microsoft - access to Microsoft cookies files

  • METHODS
  • CAVEATS
  • AUTHOR
  • COPYRIGHT

NAME

HTTP::Cookies::Microsoft - access to Microsoft cookies files

SYNOPSIS

 use LWP;
 use HTTP::Cookies::Microsoft;
 use Win32::TieRegistry(Delimiter => "/");
 my $cookies_dir = $Registry->
      {"CUser/Software/Microsoft/Windows/CurrentVersion/Explorer/Shell Folders/Cookies"};

 $cookie_jar = HTTP::Cookies::Microsoft->new(
                   file     => "$cookies_dir\\index.dat",
                   'delayload' => 1,
               );
 my $browser = LWP::UserAgent->new;
 $browser->cookie_jar( $cookie_jar );

DESCRIPTION

This is a subclass of HTTP::Cookies which loads Microsoft Internet Explorer 5.x and 6.x for Windows (MSIE) cookie files.

See the documentation for the HTTP::Cookies manpage.

METHODS

The following methods are provided:

$cookie_jar = HTTP::Cookies::Microsoft->new;

The constructor takes hash style parameters. In addition to the regular HTTP::Cookies parameters, HTTP::Cookies::Microsoft recognizes the following:

  delayload:       delay loading of cookie data until a request
                   is actually made. This results in faster
                   runtime unless you use most of the cookies
                   since only the domain's cookie data
                   is loaded on demand.

CAVEATS

Please note that the code DOESN'T support saving to the MSIE cookie file format.

AUTHOR

Johnny Lee <typo_pl@hotmail.com>

COPYRIGHT

Copyright 2002 Johnny Lee

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Cookies::Netscape - access to Netscape cookies files

  • CAVEATS
  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Cookies::Netscape - access to Netscape cookies files

SYNOPSIS

 use LWP;
 use HTTP::Cookies::Netscape;
 $cookie_jar = HTTP::Cookies::Netscape->new(
   file => "c:/program files/netscape/users/ZombieCharity/cookies.txt",
 );
 my $browser = LWP::UserAgent->new;
 $browser->cookie_jar( $cookie_jar );

DESCRIPTION

This is a subclass of HTTP::Cookies that reads (and optionally writes) Netscape/Mozilla cookie files.

See the documentation for the HTTP::Cookies manpage.

CAVEATS

Please note that the Netscape/Mozilla cookie file format can't store all the information available in the Set-Cookie2 headers, so you will probably lose some information if you save in this format.

At time of writing, this module seems to work fine with Mozilla Phoenix/Firebird.

SEE ALSO

the HTTP::Cookies::Microsoft manpage

COPYRIGHT

Copyright 2002-2003 Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Daemon - a simple http server class

  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Daemon - a simple http server class

SYNOPSIS

  use HTTP::Daemon;
  use HTTP::Status;

  my $d = HTTP::Daemon->new || die;
  print "Please contact me at: <URL:", $d->url, ">\n";
  while (my $c = $d->accept) {
      while (my $r = $c->get_request) {
          if ($r->method eq 'GET' and $r->url->path eq "/xyzzy") {
              # remember, this is *not* recommended practice :-)
              $c->send_file_response("/etc/passwd");
          }
          else {
              $c->send_error(RC_FORBIDDEN)
          }
      }
      $c->close;
      undef($c);
  }

DESCRIPTION

Instances of the HTTP::Daemon class are HTTP/1.1 servers that listen on a socket for incoming requests. The HTTP::Daemon is a subclass of IO::Socket::INET, so you can perform socket operations directly on it too.

The accept() method will return when a connection from a client is available. The returned value will be an HTTP::Daemon::ClientConn object which is another IO::Socket::INET subclass. Calling the get_request() method on this object will read data from the client and return an HTTP::Request object. The ClientConn object also provide methods to send back various responses.

This HTTP daemon does not fork(2) for you. Your application, i.e. the user of the HTTP::Daemon is responsible for forking if that is desirable. Also note that the user is responsible for generating responses that conform to the HTTP/1.1 protocol.

The following methods of HTTP::Daemon are new (or enhanced) relative to the IO::Socket::INET base class:

$d = HTTP::Daemon->new
$d = HTTP::Daemon->new( %opts )

The constructor method takes the same arguments as the IO::Socket::INET constructor, but unlike its base class it can also be called without any arguments. The daemon will then set up a listen queue of 5 connections and allocate some random port number.

A server that wants to bind to some specific address on the standard HTTP port will be constructed like this:

  $d = HTTP::Daemon->new(
           LocalAddr => 'www.thisplace.com',
           LocalPort => 80,
       );

See the IO::Socket::INET manpage for a description of other arguments that can be used configure the daemon during construction.

$c = $d->accept
$c = $d->accept( $pkg )
($c, $peer_addr) = $d->accept

This method works the same the one provided by the base class, but it returns an HTTP::Daemon::ClientConn reference by default. If a package name is provided as argument, then the returned object will be blessed into the given class. It is probably a good idea to make that class a subclass of HTTP::Daemon::ClientConn.

The accept method will return undef if timeouts have been enabled and no connection is made within the given time. The timeout() method is described in the IO::Socket manpage.

In list context both the client object and the peer address will be returned; see the description of the accept method the IO::Socket manpage for details.

$d->url

Returns a URL string that can be used to access the server root.

$d->product_tokens

Returns the name that this server will use to identify itself. This is the string that is sent with the Server response header. The main reason to have this method is that subclasses can override it if they want to use another product name.

The default is the string "libwww-perl-daemon/#.##" where "#.##" is replaced with the version number of this module.

The HTTP::Daemon::ClientConn is a IO::Socket::INET subclass. Instances of this class are returned by the accept() method of HTTP::Daemon. The following methods are provided:

$c->get_request
$c->get_request( $headers_only )

This method read data from the client and turns it into an HTTP::Request object which is returned. It returns undef if reading fails. If it fails, then the HTTP::Daemon::ClientConn object ($c) should be discarded, and you should not try call this method again on it. The $c->reason method might give you some information about why $c->get_request failed.

The get_request() method will normally not return until the whole request has been received from the client. This might not be what you want if the request is an upload of a large file (and with chunked transfer encoding HTTP can even support infinite request messages - uploading live audio for instance). If you pass a TRUE value as the $headers_only argument, then get_request() will return immediately after parsing the request headers and you are responsible for reading the rest of the request content. If you are going to call $c->get_request again on the same connection you better read the correct number of bytes.

$c->read_buffer
$c->read_buffer( $new_value )

Bytes read by $c->get_request, but not used are placed in the read buffer. The next time $c->get_request is called it will consume the bytes in this buffer before reading more data from the network connection itself. The read buffer is invalid after $c->get_request has failed.

If you handle the reading of the request content yourself you need to empty this buffer before you read more and you need to place unconsumed bytes here. You also need this buffer if you implement services like 101 Switching Protocols.

This method always return the old buffer content and can optionally replace the buffer content if you pass it an argument.

$c->reason

When $c->get_request returns undef you can obtain a short string describing why it happened by calling $c->reason.

$c->proto_ge( $proto )

Return TRUE if the client announced a protocol with version number greater or equal to the given argument. The $proto argument can be a string like "HTTP/1.1" or just "1.1".

$c->antique_client

Return TRUE if the client speaks the HTTP/0.9 protocol. No status code and no headers should be returned to such a client. This should be the same as !$c->proto_ge("HTTP/1.0").

$c->force_last_request

Make sure that $c->get_request will not try to read more requests off this connection. If you generate a response that is not self delimiting, then you should signal this fact by calling this method.

This attribute is turned on automatically if the client announces protocol HTTP/1.0 or worse and does not include a "Connection: Keep-Alive" header. It is also turned on automatically when HTTP/1.1 or better clients send the "Connection: close" request header.

$c->send_status_line
$c->send_status_line( $code )
$c->send_status_line( $code, $mess )
$c->send_status_line( $code, $mess, $proto )

Send the status line back to the client. If $code is omitted 200 is assumed. If $mess is omitted, then a message corresponding to $code is inserted. If $proto is missing the content of the $HTTP::Daemon::PROTO variable is used.

$c->send_crlf

Send the CRLF sequence to the client.

$c->send_basic_header
$c->send_basic_header( $code )
$c->send_basic_header( $code, $mess )
$c->send_basic_header( $code, $mess, $proto )

Send the status line and the "Date:" and "Server:" headers back to the client. This header is assumed to be continued and does not end with an empty CRLF line.

See the description of send_status_line() for the description of the accepted arguments.

$c->send_response( $res )

Write a HTTP::Response object to the client as a response. We try hard to make sure that the response is self delimiting so that the connection can stay persistent for further request/response exchanges.

The content attribute of the HTTP::Response object can be a normal string or a subroutine reference. If it is a subroutine, then whatever this callback routine returns is written back to the client as the response content. The routine will be called until it return an undefined or empty value. If the client is HTTP/1.1 aware then we will use chunked transfer encoding for the response.

$c->send_redirect( $loc )
$c->send_redirect( $loc, $code )
$c->send_redirect( $loc, $code, $entity_body )

Send a redirect response back to the client. The location ($loc) can be an absolute or relative URL. The $code must be one the redirect status codes, and defaults to "301 Moved Permanently"

$c->send_error
$c->send_error( $code )
$c->send_error( $code, $error_message )

Send an error response back to the client. If the $code is missing a "Bad Request" error is reported. The $error_message is a string that is incorporated in the body of the HTML entity body.

$c->send_file_response( $filename )

Send back a response with the specified $filename as content. If the file is a directory we try to generate an HTML index of it.

$c->send_file( $filename )
$c->send_file( $fd )

Copy the file to the client. The file can be a string (which will be interpreted as a filename) or a reference to an IO::Handle or glob.

$c->daemon

Return a reference to the corresponding HTTP::Daemon object.

SEE ALSO

RFC 2616

the IO::Socket::INET manpage, the IO::Socket manpage

COPYRIGHT

Copyright 1996-2003, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Date - date conversion routines

  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Date - date conversion routines

SYNOPSIS

 use HTTP::Date;

 $string = time2str($time);    # Format as GMT ASCII time
 $time = str2time($string);    # convert ASCII date to machine time

DESCRIPTION

This module provides functions that deal the date formats used by the HTTP protocol (and then some more). Only the first two functions, time2str() and str2time(), are exported by default.

time2str( [$time] )

The time2str() function converts a machine time (seconds since epoch) to a string. If the function is called without an argument, it will use the current time.

The string returned is in the format preferred for the HTTP protocol. This is a fixed length subset of the format defined by RFC 1123, represented in Universal Time (GMT). An example of a time stamp in this format is:

   Sun, 06 Nov 1994 08:49:37 GMT
str2time( $str [, $zone] )

The str2time() function converts a string to machine time. It returns undef if the format of $str is unrecognized, otherwise whatever the Time::Local functions can make out of the parsed time. Dates before the system's epoch may not work on all operating systems. The time formats recognized are the same as for parse_date().

The function also takes an optional second argument that specifies the default time zone to use when converting the date. This parameter is ignored if the zone is found in the date string itself. If this parameter is missing, and the date string format does not contain any zone specification, then the local time zone is assumed.

If the zone is not "GMT" or numerical (like "-0800" or "+0100"), then the Time::Zone module must be installed in order to get the date recognized.

parse_date( $str )

This function will try to parse a date string, and then return it as a list of numerical values followed by a (possible undefined) time zone specifier; ($year, $month, $day, $hour, $min, $sec, $tz). The $year returned will not have the number 1900 subtracted from it and the $month numbers start with 1.

In scalar context the numbers are interpolated in a string of the "YYYY-MM-DD hh:mm:ss TZ"-format and returned.

If the date is unrecognized, then the empty list is returned.

The function is able to parse the following formats:

 "Wed, 09 Feb 1994 22:23:32 GMT"       -- HTTP format
 "Thu Feb  3 17:03:55 GMT 1994"        -- ctime(3) format
 "Thu Feb  3 00:00:00 1994",           -- ANSI C asctime() format
 "Tuesday, 08-Feb-94 14:15:29 GMT"     -- old rfc850 HTTP format
 "Tuesday, 08-Feb-1994 14:15:29 GMT"   -- broken rfc850 HTTP format
 "03/Feb/1994:17:03:55 -0700"   -- common logfile format
 "09 Feb 1994 22:23:32 GMT"     -- HTTP format (no weekday)
 "08-Feb-94 14:15:29 GMT"       -- rfc850 format (no weekday)
 "08-Feb-1994 14:15:29 GMT"     -- broken rfc850 format (no weekday)
 "1994-02-03 14:15:29 -0100"    -- ISO 8601 format
 "1994-02-03 14:15:29"          -- zone is optional
 "1994-02-03"                   -- only date
 "1994-02-03T14:15:29"          -- Use T as separator
 "19940203T141529Z"             -- ISO 8601 compact format
 "19940203"                     -- only date
 "08-Feb-94"         -- old rfc850 HTTP format    (no weekday, no time)
 "08-Feb-1994"       -- broken rfc850 HTTP format (no weekday, no time)
 "09 Feb 1994"       -- proposed new HTTP format  (no weekday, no time)
 "03/Feb/1994"       -- common logfile format     (no time, no offset)
 "Feb  3  1994"      -- Unix 'ls -l' format
 "Feb  3 17:03"      -- Unix 'ls -l' format
 "11-15-96  03:52PM" -- Windows 'dir' format

The parser ignores leading and trailing whitespace. It also allow the seconds to be missing and the month to be numerical in most formats.

If the year is missing, then we assume that the date is the first matching date before current month. If the year is given with only 2 digits, then parse_date() will select the century that makes the year closest to the current date.

time2iso( [$time] )

Same as time2str(), but returns a "YYYY-MM-DD hh:mm:ss"-formatted string representing time in the local time zone.

time2isoz( [$time] )

Same as time2str(), but returns a "YYYY-MM-DD hh:mm:ssZ"-formatted string representing Universal Time.

SEE ALSO

time in the perlfunc manpage, the Time::Zone manpage

COPYRIGHT

Copyright 1995-1999, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Headers - Class encapsulating HTTP Message headers

  • CONVENIENCE METHODS
  • NON-CANONICALIZED FIELD NAMES
  • COPYRIGHT

NAME

HTTP::Headers - Class encapsulating HTTP Message headers

SYNOPSIS

 require HTTP::Headers;
 $h = HTTP::Headers->new;

 $h->header('Content-Type' => 'text/plain');  # set
 $ct = $h->header('Content-Type');            # get
 $h->remove_header('Content-Type');           # delete

DESCRIPTION

The HTTP::Headers class encapsulates HTTP-style message headers. The headers consist of attribute-value pairs also called fields, which may be repeated, and which are printed in a particular order. The field names are cases insensitive.

Instances of this class are usually created as member variables of the HTTP::Request and HTTP::Response classes, internal to the library.

The following methods are available:

$h = HTTP::Headers->new

Constructs a new HTTP::Headers object. You might pass some initial attribute-value pairs as parameters to the constructor. E.g.:

 $h = HTTP::Headers->new(
       Date         => 'Thu, 03 Feb 1994 00:00:00 GMT',
       Content_Type => 'text/html; version=3.2',
       Content_Base => 'http://www.perl.org/');

The constructor arguments are passed to the header method which is described below.

$h->clone

Returns a copy of this HTTP::Headers object.

$h->header( $field )
$h->header( $field => $value, ... )

Get or set the value of one or more header fields. The header field name ($field) is not case sensitive. To make the life easier for perl users who wants to avoid quoting before the => operator, you can use '_' as a replacement for '-' in header names.

The header() method accepts multiple ($field => $value) pairs, which means that you can update several fields with a single invocation.

The $value argument may be a plain string or a reference to an array of strings for a multi-valued field. If the $value is provided as undef then the field is removed. If the $value is not given, then that header field will remain unchanged.

The old value (or values) of the last of the header fields is returned. If no such field exists undef will be returned.

A multi-valued field will be returned as separate values in list context and will be concatenated with ", " as separator in scalar context. The HTTP spec (RFC 2616) promise that joining multiple values in this way will not change the semantic of a header field, but in practice there are cases like old-style Netscape cookies (see the HTTP::Cookies manpage) where "," is used as part of the syntax of a single field value.

Examples:

 $header->header(MIME_Version => '1.0',
                 User_Agent   => 'My-Web-Client/0.01');
 $header->header(Accept => "text/html, text/plain, image/*");
 $header->header(Accept => [qw(text/html text/plain image/*)]);
 @accepts = $header->header('Accept');  # get multiple values
 $accepts = $header->header('Accept');  # get values as a single string
$h->push_header( $field => $value )

Add a new field value for the specified header field. Previous values for the same field are retained.

As for the header() method, the field name ($field) is not case sensitive and '_' can be used as a replacement for '-'.

The $value argument may be a scalar or a reference to a list of scalars.

 $header->push_header(Accept => 'image/jpeg');
 $header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
$h->init_header( $field => $value )

Set the specified header to the given value, but only if no previous value for that field is set.

The header field name ($field) is not case sensitive and '_' can be used as a replacement for '-'.

The $value argument may be a scalar or a reference to a list of scalars.

$h->remove_header( $field, ... )

This function removes the header fields with the specified names.

The header field names ($field) are not case sensitive and '_' can be used as a replacement for '-'.

The return value is the values of the fields removed. In scalar context the number of fields removed is returned.

Note that if you pass in multiple field names then it is generally not possible to tell which of the returned values belonged to which field.

$h->remove_content_headers

This will remove all the header fields used to describe the content of a message. All header field names prefixed with Content- falls into this category, as well as Allow, Expires and Last-Modified. RFC 2616 denote these fields as Entity Header Fields.

The return value is a new HTTP::Headers object that contains the removed headers only.

$h->clear

This will remove all header fields.

$h->header_field_names

Returns the list of distinct names for the fields present in the header. The field names have case as suggested by HTTP spec, and the names are returned in the recommended "Good Practice" order.

In scalar context return the number of distinct field names.

$h->scan( \&process_header_field )

Apply a subroutine to each header field in turn. The callback routine is called with two parameters; the name of the field and a single value (a string). If a header field is multi-valued, then the routine is called once for each value. The field name passed to the callback routine has case as suggested by HTTP spec, and the headers will be visited in the recommended "Good Practice" order.

Any return values of the callback routine are ignored. The loop can be broken by raising an exception (die), but the caller of scan() would have to trap the exception itself.

$h->as_string
$h->as_string( $eol )

Return the header fields as a formatted MIME header. Since it internally uses the scan method to build the string, the result will use case as suggested by HTTP spec, and it will follow recommended "Good Practice" of ordering the header fields. Long header values are not folded.

The optional $eol parameter specifies the line ending sequence to use. The default is "\n". Embedded "\n" characters in header field values will be substituted with this line ending sequence.

CONVENIENCE METHODS

The most frequently used headers can also be accessed through the following convenience methods. These methods can both be used to read and to set the value of a header. The header value is set if you pass an argument to the method. The old header value is always returned. If the given header did not exist then undef is returned.

Methods that deal with dates/times always convert their value to system time (seconds since Jan 1, 1970) and they also expect this kind of value when the header value is set.

$h->date

This header represents the date and time at which the message was originated. E.g.:

  $h->date(time);  # set current date
$h->expires

This header gives the date and time after which the entity should be considered stale.

$h->if_modified_since
$h->if_unmodified_since

These header fields are used to make a request conditional. If the requested resource has (or has not) been modified since the time specified in this field, then the server will return a 304 Not Modified response instead of the document itself.

$h->last_modified

This header indicates the date and time at which the resource was last modified. E.g.:

  # check if document is more than 1 hour old
  if (my $last_mod = $h->last_modified) {
      if ($last_mod < time - 60*60) {
          ...
      }
  }
$h->content_type

The Content-Type header field indicates the media type of the message content. E.g.:

  $h->content_type('text/html');

The value returned will be converted to lower case, and potential parameters will be chopped off and returned as a separate value if in an array context. If there is no such header field, then the empty string is returned. This makes it safe to do the following:

  if ($h->content_type eq 'text/html') {
     # we enter this place even if the real header value happens to
     # be 'TEXT/HTML; version=3.0'
     ...
  }
$h->content_encoding

The Content-Encoding header field is used as a modifier to the media type. When present, its value indicates what additional encoding mechanism has been applied to the resource.

$h->content_length

A decimal number indicating the size in bytes of the message content.

$h->content_language

The natural language(s) of the intended audience for the message content. The value is one or more language tags as defined by RFC 1766. Eg. "no" for some kind of Norwegian and "en-US" for English the way it is written in the US.

$h->title

The title of the document. In libwww-perl this header will be initialized automatically from the <TITLE>...</TITLE> element of HTML documents. This header is no longer part of the HTTP standard.

$h->user_agent

This header field is used in request messages and contains information about the user agent originating the request. E.g.:

  $h->user_agent('Mozilla/1.2');
$h->server

The server header field contains information about the software being used by the originating server program handling the request.

$h->from

This header should contain an Internet e-mail address for the human user who controls the requesting user agent. The address should be machine-usable, as defined by RFC822. E.g.:

  $h->from('King Kong <king@kong.com>');

This header is no longer part of the HTTP standard.

$h->referer

Used to specify the address (URI) of the document from which the requested resource address was obtained.

The "Free On-line Dictionary of Computing" as this to say about the word referer:

     <World-Wide Web> A misspelling of "referrer" which
     somehow made it into the {HTTP} standard.  A given {web
     page}'s referer (sic) is the {URL} of whatever web page
     contains the link that the user followed to the current
     page.  Most browsers pass this information as part of a
     request.
     (1998-10-19)

By popular demand referrer exists as an alias for this method so you can avoid this misspelling in your programs and still send the right thing on the wire.

When setting the referrer, this method removes the fragment from the given URI if it is present, as mandated by RFC2616. Note that the removal does not happen automatically if using the header(), push_header() or init_header() methods to set the referrer.

$h->www_authenticate

This header must be included as part of a 401 Unauthorized response. The field value consist of a challenge that indicates the authentication scheme and parameters applicable to the requested URI.

$h->proxy_authenticate

This header must be included in a 407 Proxy Authentication Required response.

$h->authorization
$h->proxy_authorization

A user agent that wishes to authenticate itself with a server or a proxy, may do so by including these headers.

$h->authorization_basic

This method is used to get or set an authorization header that use the "Basic Authentication Scheme". In array context it will return two values; the user name and the password. In scalar context it will return "uname:password" as a single string value.

When used to set the header value, it expects two arguments. E.g.:

  $h->authorization_basic($uname, $password);

The method will croak if the $uname contains a colon ':'.

$h->proxy_authorization_basic

Same as authorization_basic() but will set the "Proxy-Authorization" header instead.

NON-CANONICALIZED FIELD NAMES

The header field name spelling is normally canonicalized including the '_' to '-' translation. There are some application where this is not appropriate. Prefixing field names with ':' allow you to force a specific spelling. For example if you really want a header field name to show up as foo_bar instead of "Foo-Bar", you might set it like this:

  $h->header(":foo_bar" => 1);

These field names are returned with the ':' intact for $h->header_field_names and the $h->scan callback, but the colons do not show in $h->as_string.

COPYRIGHT

Copyright 1995-2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Headers::Util - Header value parsing utility functions

  • COPYRIGHT

NAME

HTTP::Headers::Util - Header value parsing utility functions

SYNOPSIS

  use HTTP::Headers::Util qw(split_header_words);
  @values = split_header_words($h->header("Content-Type"));

DESCRIPTION

This module provides a few functions that helps parsing and construction of valid HTTP header values. None of the functions are exported by default.

The following functions are available:

split_header_words( @header_values )

This function will parse the header values given as argument into a list of anonymous arrays containing key/value pairs. The function knows how to deal with ",", ";" and "=" as well as quoted values after "=". A list of space separated tokens are parsed as if they were separated by ";".

If the @header_values passed as argument contains multiple values, then they are treated as if they were a single value separated by comma ",".

This means that this function is useful for parsing header fields that follow this syntax (BNF as from the HTTP/1.1 specification, but we relax the requirement for tokens).

  headers           = #header
  header            = (token | parameter) *( [";"] (token | parameter))

  token             = 1*<any CHAR except CTLs or separators>
  separators        = "(" | ")" | "<" | ">" | "@"
                    | "," | ";" | ":" | "\" | <">
                    | "/" | "[" | "]" | "?" | "="
                    | "{" | "}" | SP | HT

  quoted-string     = ( <"> *(qdtext | quoted-pair ) <"> )
  qdtext            = <any TEXT except <">>
  quoted-pair       = "\" CHAR
  parameter         = attribute "=" value
  attribute         = token
  value             = token | quoted-string

Each header is represented by an anonymous array of key/value pairs. The value for a simple token (not part of a parameter) is undef. Syntactically incorrect headers will not necessary be parsed as you would want.

This is easier to describe with some examples:

   split_header_words('foo="bar"; port="80,81"; discard, bar=baz');
   split_header_words('text/html; charset="iso-8859-1"');
   split_header_words('Basic realm="\\"foo\\\\bar\\""');

will return

   [foo=>'bar', port=>'80,81', discard=> undef], [bar=>'baz' ]
   ['text/html' => undef, charset => 'iso-8859-1']
   [Basic => undef, realm => "\"foo\\bar\""]
join_header_words( @arrays )

This will do the opposite of the conversion done by split_header_words(). It takes a list of anonymous arrays as arguments (or a list of key/value pairs) and produces a single header value. Attribute values are quoted if needed.

Example:

   join_header_words(["text/plain" => undef, charset => "iso-8859/1"]);
   join_header_words("text/plain" => undef, charset => "iso-8859/1");

will both return the string:

   text/plain; charset="iso-8859/1"

COPYRIGHT

Copyright 1997-1998, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Message - HTTP style message

  • COPYRIGHT

NAME

HTTP::Message - HTTP style message (base class)

SYNOPSIS

 use base 'HTTP::Message';

DESCRIPTION

An HTTP::Message object contains some headers and a content body. The following methods are available:

$mess = HTTP::Message->new
$mess = HTTP::Message->new( $headers )
$mess = HTTP::Message->new( $headers, $content )

This constructs a new message object. Normally you would want construct HTTP::Request or HTTP::Response objects instead.

The optional $header argument should be a reference to an HTTP::Headers object or a plain array reference of key/value pairs. If an HTTP::Headers object is provided then a copy of it will be embedded into the constructed message, i.e. it will not be owned and can be modified afterwards without affecting the message.

The optional $content argument should be a string of bytes.

$mess = HTTP::Message->parse( $str )

This constructs a new message object by parsing the given string.

$mess->headers

Returns the embedded HTTP::Headers object.

$mess->headers_as_string
$mess->headers_as_string( $eol )

Call the as_string() method for the headers in the message. This will be the same as

    $mess->headers->as_string

but it will make your program a whole character shorter :-)

$mess->content
$mess->content( $content )

The content() method sets the raw content if an argument is given. If no argument is given the content is not touched. In either case the original raw content is returned.

Note that the content should be a string of bytes. Strings in perl can contain characters outside the range of a byte. The Encode module can be used to turn such strings into a string of bytes.

$mess->add_content( $data )

The add_content() methods appends more data to the end of the current content buffer.

$mess->content_ref
$mess->content_ref( \$content )

The content_ref() method will return a reference to content buffer string. It can be more efficient to access the content this way if the content is huge, and it can even be used for direct manipulation of the content, for instance:

  ${$res->content_ref} =~ s/\bfoo\b/bar/g;

This example would modify the content buffer in-place.

If an argument is passed it will setup the content to reference some external source. The content() and add_content() methods will automatically dereference scalar references passed this way. For other references content() will return the reference itself and add_content() will refuse to do anything.

$mess->decoded_content( %options )

Returns the content with any Content-Encoding undone and strings mapped to perl's Unicode strings. If the Content-Encoding or charset of the message is unknown this method will fail by returning undef.

The following options can be specified.

charset

This override the charset parameter for text content. The value none can used to suppress decoding of the charset.

default_charset

This override the default charset of "ISO-8859-1".

raise_error

If TRUE then raise an exception if not able to decode content. Reason might be that the specified Content-Encoding or charset is not supported. If this option is FALSE, then decode_content() will return undef on errors, but will still set $@.

ref

If TRUE then a reference to decoded content is returned. This might be more efficient in cases where the decoded content is identical to the raw content as no data copying is required in this case.

$mess->parts
$mess->parts( @parts )
$mess->parts( \@parts )

Messages can be composite, i.e. contain other messages. The composite messages have a content type of multipart/* or message/*. This method give access to the contained messages.

The argumentless form will return a list of HTTP::Message objects. If the content type of $msg is not multipart/* or message/* then this will return the empty list. In scalar context only the first object is returned. The returned message parts should be regarded as are read only (future versions of this library might make it possible to modify the parent by modifying the parts).

If the content type of $msg is message/* then there will only be one part returned.

If the content type is message/http, then the return value will be either an HTTP::Request or an HTTP::Response object.

If an @parts argument is given, then the content of the message will modified. The array reference form is provided so that an empty list can be provided. The @parts array should contain HTTP::Message objects. The @parts objects are owned by $mess after this call and should not be modified or made part of other messages.

When updating the message with this method and the old content type of $mess is not multipart/* or message/*, then the content type is set to multipart/mixed and all other content headers are cleared.

This method will croak if the content type is message/* and more than one part is provided.

$mess->add_part( $part )

This will add a part to a message. The $part argument should be another HTTP::Message object. If the previous content type of $mess is not multipart/* then the old content (together with all content headers) will be made part #1 and the content type made multipart/mixed before the new part is added. The $part object is owned by $mess after this call and should not be modified or made part of other messages.

There is no return value.

$mess->clear

Will clear the headers and set the content to the empty string. There is no return value

$mess->protocol
$mess->protocol( $proto )

Sets the HTTP protocol used for the message. The protocol() is a string like HTTP/1.0 or HTTP/1.1.

$mess->clone

Returns a copy of the message object.

$mess->as_string
$mess->as_string( $eol )

Returns the message formatted as a single string.

The optional $eol parameter specifies the line ending sequence to use. The default is "\n". If no $eol is given then as_string will ensure that the returned string is newline terminated (even when the message content is not). No extra newline is appended if an explicit $eol is passed.

All methods unknown to HTTP::Message itself are delegated to the HTTP::Headers object that is part of every message. This allows convenient access to these methods. Refer to the HTTP::Headers manpage for details of these methods:

    $mess->header( $field => $val )
    $mess->push_header( $field => $val )
    $mess->init_header( $field => $val )
    $mess->remove_header( $field )
    $mess->remove_content_headers
    $mess->header_field_names
    $mess->scan( \&doit )
    $mess->date
    $mess->expires
    $mess->if_modified_since
    $mess->if_unmodified_since
    $mess->last_modified
    $mess->content_type
    $mess->content_encoding
    $mess->content_length
    $mess->content_language
    $mess->title
    $mess->user_agent
    $mess->server
    $mess->from
    $mess->referer
    $mess->www_authenticate
    $mess->authorization
    $mess->proxy_authorization
    $mess->authorization_basic
    $mess->proxy_authorization_basic

COPYRIGHT

Copyright 1995-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Negotiate - choose a variant to serve

  • VARIANTS
  • ACCEPT HEADERS
  • COPYRIGHT
  • AUTHOR

NAME

HTTP::Negotiate - choose a variant to serve

SYNOPSIS

 use HTTP::Negotiate qw(choose);

 #  ID       QS     Content-Type   Encoding Char-Set        Lang   Size
 $variants =
  [['var1',  1.000, 'text/html',   undef,   'iso-8859-1',   'en',   3000],
   ['var2',  0.950, 'text/plain',  'gzip',  'us-ascii',     'no',    400],
   ['var3',  0.3,   'image/gif',   undef,   undef,          undef, 43555],
  ];

 @prefered = choose($variants, $request_headers);
 $the_one  = choose($variants);

DESCRIPTION

This module provides a complete implementation of the HTTP content negotiation algorithm specified in draft-ietf-http-v11-spec-00.ps chapter 12. Content negotiation allows for the selection of a preferred content representation based upon attributes of the negotiable variants and the value of the various Accept* header fields in the request.

The variants are ordered by preference by calling the function choose().

The first parameter is reference to an array of the variants to choose among. Each element in this array is an array with the values [$id, $qs, $content_type, $content_encoding, $charset, $content_language, $content_length] whose meanings are described below. The $content_encoding and $content_language can be either a single scalar value or an array reference if there are several values.

The second optional parameter is either a HTTP::Headers or a HTTP::Request object which is searched for "Accept*" headers. If this parameter is missing, then the accept specification is initialized from the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET, HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.

In an array context, choose() returns a list of [variant identifier, calculated quality, size] tuples. The values are sorted by quality, highest quality first. If the calculated quality is the same for two variants, then they are sorted by size (smallest first). E.g.:

  (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);

Note that also zero quality variants are included in the return list even if these should never be served to the client.

In a scalar context, it returns the identifier of the variant with the highest score or undef if none have non-zero quality.

If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of noise is generated on STDOUT during evaluation of choose().

VARIANTS

A variant is described by a list of the following values. If the attribute does not make sense or is unknown for a variant, then use undef instead.

identifier

This is a string that you use as the name for the variant. This identifier for the preferred variants returned by choose().

qs

This is a number between 0.000 and 1.000 that describes the "source quality". This is what draft-ietf-http-v11-spec-00.ps says about this value:

Source quality is measured by the content provider as representing the amount of degradation from the original source. For example, a picture in JPEG form would have a lower qs when translated to the XBM format, and much lower qs when translated to an ASCII-art representation. Note, however, that this is a function of the source - an original piece of ASCII-art may degrade in quality if it is captured in JPEG form. The qs values should be assigned to each variant by the content provider; if no qs value has been assigned, the default is generally "qs=1".

content-type

This is the media type of the variant. The media type does not include a charset attribute, but might contain other parameters. Examples are:

  text/html
  text/html;version=2.0
  text/plain
  image/gif
  image/jpg
content-encoding

This is one or more content encodings that has been applied to the variant. The content encoding is generally used as a modifier to the content media type. The most common content encodings are:

  gzip
  compress
content-charset

This is the character set used when the variant contains text. The charset value should generally be undef or one of these:

  us-ascii
  iso-8859-1 ... iso-8859-9
  iso-2022-jp
  iso-2022-jp-2
  iso-2022-kr
  unicode-1-1
  unicode-1-1-utf-7
  unicode-1-1-utf-8
content-language

This describes one or more languages that are used in the variant. Language is described like this in draft-ietf-http-v11-spec-00.ps: A language is in this context a natural language spoken, written, or otherwise conveyed by human beings for communication of information to other human beings. Computer languages are explicitly excluded.

The language tags are defined by RFC 3066. Examples are:

  no               Norwegian
  en               International English
  en-US            US English
  en-cockney
content-length

This is the number of bytes used to represent the content.

ACCEPT HEADERS

The following Accept* headers can be used for describing content preferences in a request (This description is an edited extract from draft-ietf-http-v11-spec-00.ps):

Accept

This header can be used to indicate a list of media ranges which are acceptable as a response to the request. The "*" character is used to group media types into ranges, with "*/*" indicating all media types and "type/*" indicating all subtypes of that type.

The parameter q is used to indicate the quality factor, which represents the user's preference for that range of media types. The parameter mbx gives the maximum acceptable size of the response content. The default values are: q=1 and mbx=infinity. If no Accept header is present, then the client accepts all media types with q=1.

For example:

  Accept: audio/*;q=0.2;mbx=200000, audio/basic

would mean: "I prefer audio/basic (of any size), but send me any audio type if it is the best available after an 80% mark-down in quality and its size is less than 200000 bytes"

Accept-Charset

Used to indicate what character sets are acceptable for the response. The "us-ascii" character set is assumed to be acceptable for all user agents. If no Accept-Charset field is given, the default is that any charset is acceptable. Example:

  Accept-Charset: iso-8859-1, unicode-1-1
Accept-Encoding

Restricts the Content-Encoding values which are acceptable in the response. If no Accept-Encoding field is present, the server may assume that the client will accept any content encoding. An empty Accept-Encoding means that no content encoding is acceptable. Example:

  Accept-Encoding: compress, gzip
Accept-Language

This field is similar to Accept, but restricts the set of natural languages that are preferred in a response. Each language may be given an associated quality value which represents an estimate of the user's comprehension of that language. For example:

  Accept-Language: no, en-gb;q=0.8, de;q=0.55

would mean: "I prefer Norwegian, but will accept British English (with 80% comprehension) or German (with 55% comprehension).

COPYRIGHT

Copyright 1996,2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Gisle Aas <gisle@aas.no>


HTTP::Request - HTTP style request message

  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Request - HTTP style request message

SYNOPSIS

 require HTTP::Request;
 $request = HTTP::Request->new(GET => 'http://www.example.com/');

and usually used like this:

 $ua = LWP::UserAgent->new;
 $response = $ua->request($request);

DESCRIPTION

HTTP::Request is a class encapsulating HTTP style requests, consisting of a request line, some headers, and a content body. Note that the LWP library uses HTTP style requests even for non-HTTP protocols. Instances of this class are usually passed to the request() method of an LWP::UserAgent object.

HTTP::Request is a subclass of HTTP::Message and therefore inherits its methods. The following additional methods are available:

$r = HTTP::Request->new( $method, $uri )
$r = HTTP::Request->new( $method, $uri, $header )
$r = HTTP::Request->new( $method, $uri, $header, $content )

Constructs a new HTTP::Request object describing a request on the object $uri using method $method. The $method argument must be a string. The $uri argument can be either a string, or a reference to a URI object. The optional $header argument should be a reference to an HTTP::Headers object or a plain array reference of key/value pairs. The optional $content argument should be a string of bytes.

$r = HTTP::Request->parse( $str )

This constructs a new request object by parsing the given string.

$r->method
$r->method( $val )

This is used to get/set the method attribute. The method should be a short string like "GET", "HEAD", "PUT" or "POST".

$r->uri
$r->uri( $val )

This is used to get/set the uri attribute. The $val can be a reference to a URI object or a plain string. If a string is given, then it should be parseable as an absolute URI.

$r->header( $field )
$r->header( $field => $value )

This is used to get/set header values and it is inherited from HTTP::Headers via HTTP::Message. See the HTTP::Headers manpage for details and other similar methods that can be used to access the headers.

$r->content
$r->content( $content )

This is used to get/set the content and it is inherited from the HTTP::Message base class. See the HTTP::Message manpage for details and other methods that can be used to access the content.

Note that the content should be a string of bytes. Strings in perl can contain characters outside the range of a byte. The Encode module can be used to turn such strings into a string of bytes.

$r->as_string
$r->as_string( $eol )

Method returning a textual representation of the request.

SEE ALSO

the HTTP::Headers manpage, the HTTP::Message manpage, the HTTP::Request::Common manpage, the HTTP::Response manpage

COPYRIGHT

Copyright 1995-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Request::Common - Construct common HTTP::Request objects

  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Request::Common - Construct common HTTP::Request objects

SYNOPSIS

  use HTTP::Request::Common;
  $ua = LWP::UserAgent->new;
  $ua->request(GET 'http://www.sn.no/');
  $ua->request(POST 'http://somewhere/foo', [foo => bar, bar => foo]);

DESCRIPTION

This module provide functions that return newly created HTTP::Request objects. These functions are usually more convenient to use than the standard HTTP::Request constructor for the most common requests. The following functions are provided:

GET $url
GET $url, Header => Value,...

The GET() function returns an HTTP::Request object initialized with the "GET" method and the specified URL. It is roughly equivalent to the following call

  HTTP::Request->new(
     GET => $url,
     HTTP::Headers->new(Header => Value,...),
  )

but is less cluttered. What is different is that a header named Content will initialize the content part of the request instead of setting a header field. Note that GET requests should normally not have a content, so this hack makes more sense for the PUT() and POST() functions described below.

The get(...) method of LWP::UserAgent exists as a shortcut for $ua->request(GET ...).

HEAD $url
HEAD $url, Header => Value,...

Like GET() but the method in the request is "HEAD".

The head(...) method of "LWP::UserAgent" exists as a shortcut for $ua->request(HEAD ...).

PUT $url
PUT $url, Header => Value,...
PUT $url, Header => Value,..., Content => $content

Like GET() but the method in the request is "PUT".

POST $url
POST $url, Header => Value,...
POST $url, $form_ref, Header => Value,...
POST $url, Header => Value,..., Content => $form_ref

This works mostly like GET() with "POST" as the method, but this function also takes a second optional array or hash reference parameter ($form_ref). This argument can be used to pass key/value pairs for the form content. By default we will initialize a request using the application/x-www-form-urlencoded content type. This means that you can emulate a HTML <form> POSTing like this:

  POST 'http://www.perl.org/survey.cgi',
       [ name   => 'Gisle Aas',
         email  => 'gisle@aas.no',
         gender => 'M',
         born   => '1964',
         perc   => '3%',
       ];

This will create a HTTP::Request object that looks like this:

  POST http://www.perl.org/survey.cgi
  Content-Length: 66
  Content-Type: application/x-www-form-urlencoded
  name=Gisle%20Aas&email=gisle%40aas.no&gender=M&born=1964&perc=3%25

Multivalued form fields can be specified by either repeating the field name or by passing the value as an array reference.

The POST method also supports the multipart/form-data content used for Form-based File Upload as specified in RFC 1867. You trigger this content format by specifying a content type of 'form-data' as one of the request headers. If one of the values in the $form_ref is an array reference, then it is treated as a file part specification with the following interpretation:

  [ $file, $filename, Header => Value... ]
  [ undef, $filename, Header => Value,..., Content => $content ]

The first value in the array ($file) is the name of a file to open. This file will be read and its content placed in the request. The routine will croak if the file can't be opened. Use an undef as $file value if you want to specify the content directly with a Content header. The $filename is the filename to report in the request. If this value is undefined, then the basename of the $file will be used. You can specify an empty string as $filename if you want to suppress sending the filename when you provide a $file value.

If a $file is provided by no Content-Type header, then Content-Type and Content-Encoding will be filled in automatically with the values returned by LWP::MediaTypes::guess_media_type()

Sending my ~/.profile to the survey used as example above can be achieved by this:

  POST 'http://www.perl.org/survey.cgi',
       Content_Type => 'form-data',
       Content      => [ name  => 'Gisle Aas',
                         email => 'gisle@aas.no',
                         gender => 'M',
                         born   => '1964',
                         init   => ["$ENV{HOME}/.profile"],
                       ]

This will create a HTTP::Request object that almost looks this (the boundary and the content of your ~/.profile is likely to be different):

  POST http://www.perl.org/survey.cgi
  Content-Length: 388
  Content-Type: multipart/form-data; boundary="6G+f"

  --6G+f
  Content-Disposition: form-data; name="name"

  Gisle Aas
  --6G+f
  Content-Disposition: form-data; name="email"

  gisle@aas.no
  --6G+f
  Content-Disposition: form-data; name="gender"

  M
  --6G+f
  Content-Disposition: form-data; name="born"

  1964
  --6G+f
  Content-Disposition: form-data; name="init"; filename=".profile"
  Content-Type: text/plain

  PATH=/local/perl/bin:$PATH
  export PATH
  --6G+f--

If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some TRUE value, then you get back a request object with a subroutine closure as the content attribute. This subroutine will read the content of any files on demand and return it in suitable chunks. This allow you to upload arbitrary big files without using lots of memory. You can even upload infinite files like /dev/audio if you wish; however, if the file is not a plain file, there will be no Content-Length header defined for the request. Not all servers (or server applications) like this. Also, if the file(s) change in size between the time the Content-Length is calculated and the time that the last chunk is delivered, the subroutine will Croak.

The post(...) method of "LWP::UserAgent" exists as a shortcut for $ua->request(POST ...).

SEE ALSO

the HTTP::Request manpage, the LWP::UserAgent manpage

COPYRIGHT

Copyright 1997-2004, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Response - HTTP style response message

  • SEE ALSO
  • COPYRIGHT

NAME

HTTP::Response - HTTP style response message

SYNOPSIS

Response objects are returned by the request() method of the LWP::UserAgent:

    # ...
    $response = $ua->request($request)
    if ($response->is_success) {
        print $response->content;
    }
    else {
        print STDERR $response->status_line, "\n";
    }

DESCRIPTION

The HTTP::Response class encapsulates HTTP style responses. A response consists of a response line, some headers, and a content body. Note that the LWP library uses HTTP style responses even for non-HTTP protocol schemes. Instances of this class are usually created and returned by the request() method of an LWP::UserAgent object.

HTTP::Response is a subclass of HTTP::Message and therefore inherits its methods. The following additional methods are available:

$r = HTTP::Response->new( $code )
$r = HTTP::Response->new( $code, $msg )
$r = HTTP::Response->new( $code, $msg, $header )
$r = HTTP::Response->new( $code, $msg, $header, $content )

Constructs a new HTTP::Response object describing a response with response code $code and optional message $msg. The optional $header argument should be a reference to an HTTP::Headers object or a plain array reference of key/value pairs. The optional $content argument should be a string of bytes. The meaning these arguments are described below.

$r = HTTP::Response->parse( $str )

This constructs a new response object by parsing the given string.

$r->code
$r->code( $code )

This is used to get/set the code attribute. The code is a 3 digit number that encode the overall outcome of a HTTP response. The HTTP::Status module provide constants that provide mnemonic names for the code attribute.

$r->message
$r->message( $message )

This is used to get/set the message attribute. The message is a short human readable single line string that explains the response code.

$r->header( $field )
$r->header( $field => $value )

This is used to get/set header values and it is inherited from HTTP::Headers via HTTP::Message. See the HTTP::Headers manpage for details and other similar methods that can be used to access the headers.

$r->content
$r->content( $content )

This is used to get/set the raw content and it is inherited from the HTTP::Message base class. See the HTTP::Message manpage for details and other methods that can be used to access the content.

$r->decoded_content( %options )

This will return the content after any Content-Encoding and charsets has been decoded. See the HTTP::Message manpage for details.

$r->request
$r->request( $request )

This is used to get/set the request attribute. The request attribute is a reference to the the request that caused this response. It does not have to be the same request passed to the $ua->request() method, because there might have been redirects and authorization retries in between.

$r->previous
$r->previous( $response )

This is used to get/set the previous attribute. The previous attribute is used to link together chains of responses. You get chains of responses if the first response is redirect or unauthorized. The value is undef if this is the first response in a chain.

$r->status_line

Returns the string "<code> <message>". If the message attribute is not set then the official name of <code> (see the HTTP::Status manpage) is substituted.

$r->base

Returns the base URI for this response. The return value will be a reference to a URI object.

The base URI is obtained from one the following sources (in priority order):

  1. Embedded in the document content, for instance <BASE HREF="..."> in HTML documents.

  2. A "Content-Base:" or a "Content-Location:" header in the response.

    For backwards compatibility with older HTTP implementations we will also look for the "Base:" header.

  3. The URI used to request this response. This might not be the original URI that was passed to $ua->request() method, because we might have received some redirect responses first.

If neither of these sources provide an absolute URI, undef is returned.

When the LWP protocol modules produce the HTTP::Response object, then any base URI embedded in the document (step 1) will already have initialized the "Content-Base:" header. This means that this method only performs the last 2 steps (the content is not always available either).

$r->as_string
$r->as_string( $eol )

Returns a textual representation of the response.

$r->is_info
$r->is_success
$r->is_redirect
$r->is_error

These methods indicate if the response was informational, successful, a redirection, or an error. See the HTTP::Status manpage for the meaning of these.

$r->error_as_HTML

Returns a string containing a complete HTML document indicating what error occurred. This method should only be called when $r->is_error is TRUE.

$r->current_age

Calculates the "current age" of the response as specified by RFC 2616 section 13.2.3. The age of a response is the time since it was sent by the origin server. The returned value is a number representing the age in seconds.

$r->freshness_lifetime

Calculates the "freshness lifetime" of the response as specified by RFC 2616 section 13.2.4. The "freshness lifetime" is the length of time between the generation of a response and its expiration time. The returned value is a number representing the freshness lifetime in seconds.

If the response does not contain an "Expires" or a "Cache-Control" header, then this function will apply some simple heuristic based on 'Last-Modified' to determine a suitable lifetime.

$r->is_fresh

Returns TRUE if the response is fresh, based on the values of freshness_lifetime() and current_age(). If the response is no longer fresh, then it has to be refetched or revalidated by the origin server.

$r->fresh_until

Returns the time when this entity is no longer fresh.

SEE ALSO

the HTTP::Headers manpage, the HTTP::Message manpage, the HTTP::Status manpage, the HTTP::Request manpage

COPYRIGHT

Copyright 1995-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


HTTP::Status - HTTP Status code processing

  • CONSTANTS
  • FUNCTIONS
  • BUGS

NAME

HTTP::Status - HTTP Status code processing

SYNOPSIS

 use HTTP::Status;

 if ($rc != RC_OK) {
     print status_message($rc), "\n";
 }

 if (is_success($rc)) { ... }
 if (is_error($rc)) { ... }
 if (is_redirect($rc)) { ... }

DESCRIPTION

HTTP::Status is a library of routines for defining and classifying HTTP status codes for libwww-perl. Status codes are used to encode the overall outcome of a HTTP response message. Codes correspond to those defined in RFC 2616 and RFC 2518.

CONSTANTS

The following constant functions can be used as mnemonic status code names:

   RC_CONTINUE                          (100)
   RC_SWITCHING_PROTOCOLS               (101)
   RC_PROCESSING                        (102)
   RC_OK                                (200)
   RC_CREATED                           (201)
   RC_ACCEPTED                          (202)
   RC_NON_AUTHORITATIVE_INFORMATION     (203)
   RC_NO_CONTENT                        (204)
   RC_RESET_CONTENT                     (205)
   RC_PARTIAL_CONTENT                   (206)
   RC_MULTI_STATUS                      (207)
   RC_MULTIPLE_CHOICES                  (300)
   RC_MOVED_PERMANENTLY                 (301)
   RC_FOUND                             (302)
   RC_SEE_OTHER                         (303)
   RC_NOT_MODIFIED                      (304)
   RC_USE_PROXY                         (305)
   RC_TEMPORARY_REDIRECT                (307)
   RC_BAD_REQUEST                       (400)
   RC_UNAUTHORIZED                      (401)
   RC_PAYMENT_REQUIRED                  (402)
   RC_FORBIDDEN                         (403)
   RC_NOT_FOUND                         (404)
   RC_METHOD_NOT_ALLOWED                (405)
   RC_NOT_ACCEPTABLE                    (406)
   RC_PROXY_AUTHENTICATION_REQUIRED     (407)
   RC_REQUEST_TIMEOUT                   (408)
   RC_CONFLICT                          (409)
   RC_GONE                              (410)
   RC_LENGTH_REQUIRED                   (411)
   RC_PRECONDITION_FAILED               (412)
   RC_REQUEST_ENTITY_TOO_LARGE          (413)
   RC_REQUEST_URI_TOO_LARGE             (414)
   RC_UNSUPPORTED_MEDIA_TYPE            (415)
   RC_REQUEST_RANGE_NOT_SATISFIABLE     (416)
   RC_EXPECTATION_FAILED                (417)
   RC_UNPROCESSABLE_ENTITY              (422)
   RC_LOCKED                            (423)
   RC_FAILED_DEPENDENCY                 (424)
   RC_INTERNAL_SERVER_ERROR             (500)
   RC_NOT_IMPLEMENTED                   (501)
   RC_BAD_GATEWAY                       (502)
   RC_SERVICE_UNAVAILABLE               (503)
   RC_GATEWAY_TIMEOUT                   (504)
   RC_HTTP_VERSION_NOT_SUPPORTED        (505)
   RC_INSUFFICIENT_STORAGE              (507)

FUNCTIONS

The following additional functions are provided. Most of them are exported by default.

status_message( $code )

The status_message() function will translate status codes to human readable strings. The string is the same as found in the constant names above. If the $code is unknown, then undef is returned.

is_info( $code )

Return TRUE if $code is an Informational status code. This class of status code indicates a provisional response which can't have any content.

is_success( $code )

Return TRUE if $code is a Successful status code.

is_redirect( $code )

Return TRUE if $code is a Redirection status code. This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request.

is_error( $code )

Return TRUE if $code is an Error status code. The function return TRUE for both client error or a server error status codes.

is_client_error( $code )

Return TRUE if $code is an Client Error status code. This class of status code is intended for cases in which the client seems to have erred.

This function is not exported by default.

is_server_error( $code )

Return TRUE if $code is an Server Error status code. This class of status codes is intended for cases in which the server is aware that it has erred or is incapable of performing the request.

This function is not exported by default.

BUGS

Wished @EXPORT_OK had been used instead of @EXPORT in the beginning. Now too much is exported by default.


Hash::Util - A selection of general-utility hash subroutines

    • Restricted hashes
  • CAVEATS
  • AUTHOR
  • SEE ALSO

NAME

Hash::Util - A selection of general-utility hash subroutines

SYNOPSIS

  use Hash::Util qw(lock_keys   unlock_keys
                    lock_value  unlock_value
                    lock_hash   unlock_hash
                    hash_seed);

  %hash = (foo => 42, bar => 23);
  lock_keys(%hash);
  lock_keys(%hash, @keyset);
  unlock_keys(%hash);

  lock_value  (%hash, 'foo');
  unlock_value(%hash, 'foo');

  lock_hash  (%hash);
  unlock_hash(%hash);

  my $hashes_are_randomised = hash_seed() != 0;

DESCRIPTION

Hash::Util contains special functions for manipulating hashes that don't really warrant a keyword.

By default Hash::Util does not export anything.

Restricted hashes

5.8.0 introduces the ability to restrict a hash to a certain set of keys. No keys outside of this set can be added. It also introduces the ability to lock an individual key so it cannot be deleted and the value cannot be changed.

This is intended to largely replace the deprecated pseudo-hashes.

lock_keys
unlock_keys
  lock_keys(%hash);
  lock_keys(%hash, @keys);

Restricts the given %hash's set of keys to @keys. If @keys is not given it restricts it to its current keyset. No more keys can be added. delete() and exists() will still work, but will not alter the set of allowed keys. Note: the current implementation prevents the hash from being bless()ed while it is in a locked state. Any attempt to do so will raise an exception. Of course you can still bless() the hash before you call lock_keys() so this shouldn't be a problem.

  unlock_keys(%hash);

Removes the restriction on the %hash's keyset.

lock_value
unlock_value
  lock_value  (%hash, $key);
  unlock_value(%hash, $key);

Locks and unlocks an individual key of a hash. The value of a locked key cannot be changed.

%hash must have already been locked for this to have useful effect.

lock_hash
unlock_hash
    lock_hash(%hash);

lock_hash() locks an entire hash, making all keys and values readonly. No value can be changed, no keys can be added or deleted.

    unlock_hash(%hash);

unlock_hash() does the opposite of lock_hash(). All keys and values are made read/write. All values can be changed and keys can be added and deleted.

hash_seed
    my $hash_seed = hash_seed();

hash_seed() returns the seed number used to randomise hash ordering. Zero means the "traditional" random hash ordering, non-zero means the new even more random hash ordering introduced in Perl 5.8.1.

Note that the hash seed is sensitive information: by knowing it one can craft a denial-of-service attack against Perl code, even remotely, see Algorithmic Complexity Attacks in the perlsec manpage for more information. Do not disclose the hash seed to people who don't need to know it. See also PERL_HASH_SEED_DEBUG in the perlrun manpage.

CAVEATS

Note that the trapping of the restricted operations is not atomic: for example

    eval { %hash = (illegal_key => 1) }

leaves the %hash empty rather than with its original contents.

AUTHOR

Michael G Schwern <schwern@pobox.com> on top of code by Nick Ing-Simmons and Jeffrey Friedl.

SEE ALSO

the Scalar::Util manpage, the List::Util manpage, the Hash::Util manpage, and Algorithmic Complexity Attacks in the perlsec manpage.


I18N::Collate - compare 8-bit scalar data according to the current locale

NAME

I18N::Collate - compare 8-bit scalar data according to the current locale

SYNOPSIS

    use I18N::Collate;
    setlocale(LC_COLLATE, 'locale-of-your-choice');
    $s1 = new I18N::Collate "scalar_data_1";
    $s2 = new I18N::Collate "scalar_data_2";

DESCRIPTION

  ***
  WARNING: starting from the Perl version 5.003_06
  the I18N::Collate interface for comparing 8-bit scalar data
  according to the current locale
        HAS BEEN DEPRECATED
  That is, please do not use it anymore for any new applications
  and please migrate the old applications away from it because its
  functionality was integrated into the Perl core language in the
  release 5.003_06.
  See the perllocale manual page for further information.
  ***

This module provides you with objects that will collate according to your national character set, provided that the POSIX setlocale() function is supported on your system.

You can compare $s1 and $s2 above with

    $s1 le $s2

to extract the data itself, you'll need a dereference: $$s1

This module uses POSIX::setlocale(). The basic collation conversion is done by strxfrm() which terminates at NUL characters being a decent C routine. collate_xfrm() handles embedded NUL characters gracefully.

The available locales depend on your operating system; try whether locale -a shows them or man pages for "locale" or "nlsinfo" or the direct approach ls /usr/lib/nls/loc or ls /usr/lib/nls or ls /usr/lib/locale. Not all the locales that your vendor supports are necessarily installed: please consult your operating system's documentation and possibly your local system administration. The locale names are probably something like xx_XX.(ISO)?8859-N or xx_XX.(ISO)?8859N, for example fr_CH.ISO8859-1 is the Swiss (CH) variant of French (fr), ISO Latin (8859) 1 (-1) which is the Western European character set.


I18N::LangTags - functions for dealing with RFC3066-style language tags

  • ABOUT LOWERCASING
  • ABOUT UNICODE PLAINTEXT LANGUAGE TAGS
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

I18N::LangTags - functions for dealing with RFC3066-style language tags

SYNOPSIS

  use I18N::LangTags();

...or specify whichever of those functions you want to import, like so:

  use I18N::LangTags qw(implicate_supers similarity_language_tag);

All the exportable functions are listed below -- you're free to import only some, or none at all. By default, none are imported. If you say:

    use I18N::LangTags qw(:ALL)

...then all are exported. (This saves you from having to use something less obvious like use I18N::LangTags qw(/./).)

If you don't import any of these functions, assume a &I18N::LangTags:: in front of all the function names in the following examples.

DESCRIPTION

Language tags are a formalism, described in RFC 3066 (obsoleting 1766), for declaring what language form (language and possibly dialect) a given chunk of information is in.

This library provides functions for common tasks involving language tags as they are needed in a variety of protocols and applications.

Please see the "See Also" references for a thorough explanation of how to correctly use language tags.

  • the function is_language_tag($lang1)

    Returns true iff $lang1 is a formally valid language tag.

       is_language_tag("fr")            is TRUE
   is_language_tag("x-jicarilla")   is FALSE
       (Subtags can be 8 chars long at most -- 'jicarilla' is 9)
       is_language_tag("sgn-US")    is TRUE
       (That's American Sign Language)
       is_language_tag("i-Klikitat")    is TRUE
       (True without regard to the fact noone has actually
        registered Klikitat -- it's a formally valid tag)
       is_language_tag("fr-patois")     is TRUE
       (Formally valid -- altho descriptively weak!)
       is_language_tag("Spanish")       is FALSE
   is_language_tag("french-patois") is FALSE
       (No good -- first subtag has to match
        /^([xXiI]|[a-zA-Z]{2,3})$/ -- see RFC3066)

       is_language_tag("x-borg-prot2532") is TRUE
       (Yes, subtags can contain digits, as of RFC3066)
  • the function extract_language_tags($whatever)

    Returns a list of whatever looks like formally valid language tags in $whatever. Not very smart, so don't get too creative with what you want to feed it.

      extract_language_tags("fr, fr-ca, i-mingo")
    returns:   ('fr', 'fr-ca', 'i-mingo')
      extract_language_tags("It's like this: I'm in fr -- French!")
    returns:   ('It', 'in', 'fr')
  (So don't just feed it any old thing.)

    The output is untainted. If you don't know what tainting is, don't worry about it.

  • the function same_language_tag($lang1, $lang2)

    Returns true iff $lang1 and $lang2 are acceptable variant tags representing the same language-form.

       same_language_tag('x-kadara', 'i-kadara')  is TRUE
      (The x/i- alternation doesn't matter)
   same_language_tag('X-KADARA', 'i-kadara')  is TRUE
      (...and neither does case)
   same_language_tag('en',       'en-US')     is FALSE
      (all-English is not the SAME as US English)
   same_language_tag('x-kadara', 'x-kadar')   is FALSE
      (these are totally unrelated tags)
   same_language_tag('no-bok',    'nb')       is TRUE
      (no-bok is a legacy tag for nb (Norwegian Bokmal))

    same_language_tag works by just seeing whether encode_language_tag($lang1) is the same as encode_language_tag($lang2).

    (Yes, I know this function is named a bit oddly. Call it historic reasons.)

  • the function similarity_language_tag($lang1, $lang2)

    Returns an integer representing the degree of similarity between tags $lang1 and $lang2 (the order of which does not matter), where similarity is the number of common elements on the left, without regard to case and to x/i- alternation.

       similarity_language_tag('fr', 'fr-ca')           is 1
      (one element in common)
   similarity_language_tag('fr-ca', 'fr-FR')        is 1
      (one element in common)
       similarity_language_tag('fr-CA-joual',
                           'fr-CA-PEI')             is 2
   similarity_language_tag('fr-CA-joual', 'fr-CA')  is 2
      (two elements in common)
       similarity_language_tag('x-kadara', 'i-kadara')  is 1
      (x/i- doesn't matter)
       similarity_language_tag('en',       'x-kadar')   is 0
   similarity_language_tag('x-kadara', 'x-kadar')   is 0
      (unrelated tags -- no similarity)
       similarity_language_tag('i-cree-syllabic',
                           'i-cherokee-syllabic')   is 0
      (no B<leftmost> elements in common!)
  • the function is_dialect_of($lang1, $lang2)

    Returns true iff language tag $lang1 represents a subform of language tag $lang2.

    Get the order right! It doesn't work the other way around!

       is_dialect_of('en-US', 'en')            is TRUE
     (American English IS a dialect of all-English)
       is_dialect_of('fr-CA-joual', 'fr-CA')   is TRUE
   is_dialect_of('fr-CA-joual', 'fr')      is TRUE
     (Joual is a dialect of (a dialect of) French)
       is_dialect_of('en', 'en-US')            is FALSE
     (all-English is a NOT dialect of American English)
       is_dialect_of('fr', 'en-CA')            is FALSE
       is_dialect_of('en',    'en'   )         is TRUE
   is_dialect_of('en-US', 'en-US')         is TRUE
     (B<Note:> these are degenerate cases)
       is_dialect_of('i-mingo-tom', 'x-Mingo') is TRUE
     (the x/i thing doesn't matter, nor does case)
       is_dialect_of('nn', 'no')               is TRUE
     (because 'nn' (New Norse) is aliased to 'no-nyn',
      as a special legacy case, and 'no-nyn' is a
      subform of 'no' (Norwegian))
  • the function super_languages($lang1)

    Returns a list of language tags that are superordinate tags to $lang1 -- it gets this by removing subtags from the end of $lang1 until nothing (or just "i" or "x") is left.

       super_languages("fr-CA-joual")  is  ("fr-CA", "fr")
       super_languages("en-AU")  is  ("en")
       super_languages("en")  is  empty-list, ()
       super_languages("i-cherokee")  is  empty-list, ()
    ...not ("i"), which would be illegal as well as pointless.

    If $lang1 is not a valid language tag, returns empty-list in a list context, undef in a scalar context.

    A notable and rather unavoidable problem with this method: "x-mingo-tom" has an "x" because the whole tag isn't an IANA-registered tag -- but super_languages('x-mingo-tom') is ('x-mingo') -- which isn't really right, since 'i-mingo' is registered. But this module has no way of knowing that. (But note that same_language_tag('x-mingo', 'i-mingo') is TRUE.)

    More importantly, you assume at your peril that superordinates of $lang1 are mutually intelligible with $lang1. Consider this carefully.

  • the function locale2language_tag($locale_identifier)

    This takes a locale name (like "en", "en_US", or "en_US.ISO8859-1") and maps it to a language tag. If it's not mappable (as with, notably, "C" and "POSIX"), this returns empty-list in a list context, or undef in a scalar context.

       locale2language_tag("en") is "en"
       locale2language_tag("en_US") is "en-US"
       locale2language_tag("en_US.ISO8859-1") is "en-US"
       locale2language_tag("C") is undef or ()
       locale2language_tag("POSIX") is undef or ()
       locale2language_tag("POSIX") is undef or ()

    I'm not totally sure that locale names map satisfactorily to language tags. Think REAL hard about how you use this. YOU HAVE BEEN WARNED.

    The output is untainted. If you don't know what tainting is, don't worry about it.

  • the function encode_language_tag($lang1)

    This function, if given a language tag, returns an encoding of it such that:

    * tags representing different languages never get the same encoding.

    * tags representing the same language always get the same encoding.

    * an encoding of a formally valid language tag always is a string value that is defined, has length, and is true if considered as a boolean.

    Note that the encoding itself is not a formally valid language tag. Note also that you cannot, currently, go from an encoding back to a language tag that it's an encoding of.

    Note also that you must consider the encoded value as atomic; i.e., you should not consider it as anything but an opaque, unanalysable string value. (The internals of the encoding method may change in future versions, as the language tagging standard changes over time.)

    encode_language_tag returns undef if given anything other than a formally valid language tag.

    The reason encode_language_tag exists is because different language tags may represent the same language; this is normally treatable with same_language_tag, but consider this situation:

    You have a data file that expresses greetings in different languages. Its format is "[language tag]=[how to say 'Hello']", like:

              en-US=Hiho
          fr=Bonjour
          i-mingo=Hau'

    And suppose you write a program that reads that file and then runs as a daemon, answering client requests that specify a language tag and then expect the string that says how to greet in that language. So an interaction looks like:

              greeting-client asks:    fr
          greeting-server answers: Bonjour

    So far so good. But suppose the way you're implementing this is:

              my %greetings;
          die unless open(IN, "<in.dat");
          while(<IN>) {
            chomp;
            next unless /^([^=]+)=(.+)/s;
            my($lang, $expr) = ($1, $2);
            $greetings{$lang} = $expr;
          }
          close(IN);

    at which point %greetings has the contents:

              "en-US"   => "Hiho"
          "fr"      => "Bonjour"
          "i-mingo" => "Hau'"

    And suppose then that you answer client requests for language $wanted by just looking up $greetings{$wanted}.

    If the client asks for "fr", that will look up successfully in %greetings, to the value "Bonjour". And if the client asks for "i-mingo", that will look up successfully in %greetings, to the value "Hau'".

    But if the client asks for "i-Mingo" or "x-mingo", or "Fr", then the lookup in %greetings fails. That's the Wrong Thing.

    You could instead do lookups on $wanted with:

              use I18N::LangTags qw(same_language_tag);
          my $repsonse = '';
          foreach my $l2 (keys %greetings) {
            if(same_language_tag($wanted, $l2)) {
              $response = $greetings{$l2};
              last;
            }
          }

    But that's rather inefficient. A better way to do it is to start your program with:

              use I18N::LangTags qw(encode_language_tag);
          my %greetings;
          die unless open(IN, "<in.dat");
          while(<IN>) {
            chomp;
            next unless /^([^=]+)=(.+)/s;
            my($lang, $expr) = ($1, $2);
            $greetings{
                        encode_language_tag($lang)
                      } = $expr;
          }
          close(IN);

    and then just answer client requests for language $wanted by just looking up

              $greetings{encode_language_tag($wanted)}

    And that does the Right Thing.

  • the function alternate_language_tags($lang1)

    This function, if given a language tag, returns all language tags that are alternate forms of this language tag. (I.e., tags which refer to the same language.) This is meant to handle legacy tags caused by the minor changes in language tag standards over the years; and the x-/i- alternation is also dealt with.

    Note that this function does not try to equate new (and never-used, and unusable) ISO639-2 three-letter tags to old (and still in use) ISO639-1 two-letter equivalents -- like "ara" -> "ar" -- because "ara" has never been in use as an Internet language tag, and RFC 3066 stipulates that it never should be, since a shorter tag ("ar") exists.

    Examples:

              alternate_language_tags('no-bok')       is ('nb')
          alternate_language_tags('nb')           is ('no-bok')
          alternate_language_tags('he')           is ('iw')
          alternate_language_tags('iw')           is ('he')
          alternate_language_tags('i-hakka')      is ('zh-hakka', 'x-hakka')
          alternate_language_tags('zh-hakka')     is ('i-hakka', 'x-hakka')
          alternate_language_tags('en')           is ()
          alternate_language_tags('x-mingo-tom')  is ('i-mingo-tom')
          alternate_language_tags('x-klikitat')   is ('i-klikitat')
          alternate_language_tags('i-klikitat')   is ('x-klikitat')

    This function returns empty-list if given anything other than a formally valid language tag.

  • the function @langs = panic_languages(@accept_languages)

    This function takes a list of 0 or more language tags that constitute a given user's Accept-Language list, and returns a list of tags for other (non-super) languages that are probably acceptable to the user, to be used if all else fails.

    For example, if a user accepts only 'ca' (Catalan) and 'es' (Spanish), and the documents/interfaces you have available are just in German, Italian, and Chinese, then the user will most likely want the Italian one (and not the Chinese or German one!), instead of getting nothing. So panic_languages('ca', 'es') returns a list containing 'it' (Italian).

    English ('en') is always in the return list, but whether it's at the very end or not depends on the input languages. This function works by consulting an internal table that stipulates what common languages are "close" to each other.

    A useful construct you might consider using is:

      @fallbacks = super_languages(@accept_languages);
  push @fallbacks, panic_languages(
    @accept_languages, @fallbacks,
  );
  • the function implicate_supers( ...languages... )

    This takes a list of strings (which are presumed to be language-tags; strings that aren't, are ignored); and after each one, this function inserts super-ordinate forms that don't already appear in the list. The original list, plus these insertions, is returned.

    In other words, it takes this:

      pt-br de-DE en-US fr pt-br-janeiro

    and returns this:

      pt-br pt de-DE de en-US en fr pt-br-janeiro

    This function is most useful in the idiom

      implicate_supers( I18N::LangTags::Detect::detect() );

    (See the I18N::LangTags::Detect manpage.)

  • the function implicate_supers_strictly( ...languages... )

    This works like implicate_supers except that the implicated forms are added to the end of the return list.

    In other words, implicate_supers_strictly takes a list of strings (which are presumed to be language-tags; strings that aren't, are ignored) and after the whole given list, it inserts the super-ordinate forms of all given tags, minus any tags that already appear in the input list.

    In other words, it takes this:

      pt-br de-DE en-US fr pt-br-janeiro

    and returns this:

      pt-br de-DE en-US fr pt-br-janeiro pt de en

    The reason this function has "_strictly" in its name is that when you're processing an Accept-Language list according to the RFCs, if you interpret the RFCs quite strictly, then you would use implicate_supers_strictly, but for normal use (i.e., common-sense use, as far as I'm concerned) you'd use implicate_supers.

ABOUT LOWERCASING

I've considered making all the above functions that output language tags return all those tags strictly in lowercase. Having all your language tags in lowercase does make some things easier. But you might as well just lowercase as you like, or call encode_language_tag($lang1) where appropriate.

ABOUT UNICODE PLAINTEXT LANGUAGE TAGS

In some future version of I18N::LangTags, I plan to include support for RFC2482-style language tags -- which are basically just normal language tags with their ASCII characters shifted into Plane 14.

SEE ALSO

* I18N::LangTags::List

* RFC 3066, ftp://ftp.isi.edu/in-notes/rfc3066.txt, "Tags for the Identification of Languages". (Obsoletes RFC 1766)

* RFC 2277, ftp://ftp.isi.edu/in-notes/rfc2277.txt, "IETF Policy on Character Sets and Languages".

* RFC 2231, ftp://ftp.isi.edu/in-notes/rfc2231.txt, "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations".

* RFC 2482, ftp://ftp.isi.edu/in-notes/rfc2482.txt, "Language Tagging in Unicode Plain Text".

* Locale::Codes, in http://www.perl.com/CPAN/modules/by-module/Locale/

* ISO 639-2, "Codes for the representation of names of languages", including two-letter and three-letter codes, http://www.loc.gov/standards/iso639-2/langcodes.html

* The IANA list of registered languages (hopefully up-to-date), http://www.iana.org/assignments/language-tags

COPYRIGHT

Copyright (c) 1998+ Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The programs and documentation in this dist are distributed in the hope that they will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


I18N::LangTags::Detect - detect the user's language preferences

  • FUNCTIONS
  • ENVIRONMENT
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

I18N::LangTags::Detect - detect the user's language preferences

SYNOPSIS

  use I18N::LangTags::Detect;
  my @user_wants = I18N::LangTags::Detect::detect();

DESCRIPTION

It is a common problem to want to detect what language(s) the user would prefer output in.

FUNCTIONS

This module defines one public function, I18N::LangTags::Detect::detect(). This function is not exported (nor is even exportable), and it takes no parameters.

In scalar context, the function returns the most preferred language tag (or undef if no preference was seen).

In list context (which is usually what you want), the function returns a (possibly empty) list of language tags representing (best first) what languages the user apparently would accept output in. You will probably want to pass the output of this through I18N::LangTags::implicate_supers_tightly(...) or I18N::LangTags::implicate_supers(...), like so:

  my @languages =
    I18N::LangTags::implicate_supers_tightly(
      I18N::LangTags::Detect::detect()
    );

ENVIRONMENT

This module looks for several environment variables, including REQUEST_METHOD, HTTP_ACCEPT_LANGUAGE, LANGUAGE, LC_ALL, LC_MESSAGES, and LANG.

It will also use the the Win32::Locale manpage module, if it's installed.

SEE ALSO

the I18N::LangTags manpage, the Win32::Locale manpage, the Locale::Maketext manpage.

(This module's core code started out as a routine in Locale::Maketext; but I moved it here once I realized it was more generally useful.)

COPYRIGHT

Copyright (c) 1998-2004 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The programs and documentation in this dist are distributed in the hope that they will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


I18N::LangTags::List -- tags and names for human languages

  • ABOUT LANGUAGE TAGS
  • LIST OF LANGUAGES
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMER
  • AUTHOR

NAME

I18N::LangTags::List -- tags and names for human languages

SYNOPSIS

  use I18N::LangTags::List;
  print "Parlez-vous... ", join(', ',
      I18N::LangTags::List::name('elx') || 'unknown_language',
      I18N::LangTags::List::name('ar-Kw') || 'unknown_language',
      I18N::LangTags::List::name('en') || 'unknown_language',
      I18N::LangTags::List::name('en-CA') || 'unknown_language',
    ), "?\n";

prints:

  Parlez-vous... Elamite, Kuwait Arabic, English, Canadian English?

DESCRIPTION

This module provides a function I18N::LangTags::List::name( langtag ) that takes a language tag (see I18N::LangTags) and returns the best attempt at an English name for it, or undef if it can't make sense of the tag.

The function I18N::LangTags::List::name(...) is not exported.

This module also provides a function I18N::LangTags::List::is_decent( langtag ) that returns true iff the language tag is syntactically valid and is for general use (like "fr" or "fr-ca", below). That is, it returns false for tags that are syntactically invalid and for tags, like "aus", that are listed in brackets below. This function is not exported.

The map of tags-to-names that it uses is accessable as %I18N::LangTags::List::Name, and it's the same as the list that follows in this documentation, which should be useful to you even if you don't use this module.

ABOUT LANGUAGE TAGS

Internet language tags, as defined in RFC 3066, are a formalism for denoting human languages. The two-letter ISO 639-1 language codes are well known (as "en" for English), as are their forms when qualified by a country code ("en-US"). Less well-known are the arbitrary-length non-ISO codes (like "i-mingo"), and the recently (in 2001) introduced three-letter ISO-639-2 codes.

Remember these important facts:

  • Language tags are not locale IDs. A locale ID is written with a "_" instead of a "-", (almost?) always matches m/^\w\w_\w\w\b/, and means something different than a language tag. A language tag denotes a language. A locale ID denotes a language as used in a particular place, in combination with non-linguistic location-specific information such as what currency is used there. Locales also often denote character set information, as in "en_US.ISO8859-1".

  • Language tags are not for computer languages.

  • "Dialect" is not a useful term, since there is no objective criterion for establishing when two language-forms are dialects of eachother, or are separate languages.

  • Language tags are not case-sensitive. en-US, en-us, En-Us, etc., are all the same tag, and denote the same language.

  • Not every language tag really refers to a single language. Some language tags refer to conditions: i-default (system-message text in English plus maybe other languages), und (undetermined language). Others (notably lots of the three-letter codes) are bibliographic tags that classify whole groups of languages, as with cus "Cushitic (Other)" (i.e., a language that has been classed as Cushtic, but which has no more specific code) or the even less linguistically coherent sai for "South American Indian (Other)". Though useful in bibliography, SUCH TAGS ARE NOT FOR GENERAL USE. For further guidance, email me.

  • Language tags are not country codes. In fact, they are often distinct codes, as with language tag ja for Japanese, and ISO 3166 country code .jp for Japan.

LIST OF LANGUAGES

The first part of each item is the language tag, between {...}. It is followed by an English name for the language or language-group. Language tags that I judge to be not for general use, are bracketed.

This list is in alphabetical order by English name of the language.

{ab} : Abkhazian

eq Abkhaz

{ace} : Achinese
{ach} : Acoli
{ada} : Adangme
{ady} : Adyghe

eq Adygei

{aa} : Afar
{afh} : Afrihili

(Artificial)

{af} : Afrikaans
[{afa} : Afro-Asiatic (Other)]
{ak} : Akan

(Formerly "aka".)

{akk} : Akkadian

(Historical)

{sq} : Albanian
{ale} : Aleut
[{alg} : Algonquian languages]

NOT Algonquin!

[{tut} : Altaic (Other)]
{am} : Amharic

NOT Aramaic!

{i-ami} : Ami

eq Amis. eq 'Amis. eq Pangca.

[{apa} : Apache languages]
{ar} : Arabic

Many forms are mutually un-intelligible in spoken media.
Notable forms:
{ar-ae} UAE Arabic;
{ar-bh} Bahrain Arabic;
{ar-dz} Algerian Arabic;
{ar-eg} Egyptian Arabic;
{ar-iq} Iraqi Arabic;
{ar-jo} Jordanian Arabic;
{ar-kw} Kuwait Arabic;
{ar-lb} Lebanese Arabic;
{ar-ly} Libyan Arabic;
{ar-ma} Moroccan Arabic;
{ar-om} Omani Arabic;
{ar-qa} Qatari Arabic;
{ar-sa} Sauda Arabic;
{ar-sy} Syrian Arabic;
{ar-tn} Tunisian Arabic;
{ar-ye} Yemen Arabic.

{arc} : Aramaic

NOT Amharic! NOT Samaritan Aramaic!

{arp} : Arapaho
{arn} : Araucanian
{arw} : Arawak
{hy} : Armenian
{an} : Aragonese
[{art} : Artificial (Other)]
{ast} : Asturian

eq Bable.

{as} : Assamese
[{ath} : Athapascan languages]

eq Athabaskan. eq Athapaskan. eq Athabascan.

[{aus} : Australian languages]
[{map} : Austronesian (Other)]
{av} : Avaric

(Formerly "ava".)

{ae} : Avestan

eq Zend

{awa} : Awadhi
{ay} : Aymara
{az} : Azerbaijani

eq Azeri

Notable forms: {az-Arab} Azerbaijani in Arabic script; {az-Cyrl} Azerbaijani in Cyrillic script; {az-Latn} Azerbaijani in Latin script.

{ban} : Balinese
[{bat} : Baltic (Other)]
{bal} : Baluchi
{bm} : Bambara

(Formerly "bam".)

[{bai} : Bamileke languages]
{bad} : Banda
[{bnt} : Bantu (Other)]
{bas} : Basa
{ba} : Bashkir
{eu} : Basque
{btk} : Batak (Indonesia)
{bej} : Beja
{be} : Belarusian

eq Belarussian. eq Byelarussian. eq Belorussian. eq Byelorussian. eq White Russian. eq White Ruthenian. NOT Ruthenian!

{bem} : Bemba
{bn} : Bengali

eq Bangla.

[{ber} : Berber (Other)]
{bho} : Bhojpuri
{bh} : Bihari
{bik} : Bikol
{bin} : Bini
{bi} : Bislama

eq Bichelamar.

{bs} : Bosnian
{bra} : Braj
{br} : Breton
{bug} : Buginese
{bg} : Bulgarian
{i-bnn} : Bunun
{bua} : Buriat
{my} : Burmese
{cad} : Caddo
{car} : Carib
{ca} : Catalan

eq Catalán. eq Catalonian.

[{cau} : Caucasian (Other)]
{ceb} : Cebuano
[{cel} : Celtic (Other)]

Notable forms: {cel-gaulish} Gaulish (Historical)

[{cai} : Central American Indian (Other)]
{chg} : Chagatai

(Historical?)

[{cmc} : Chamic languages]
{ch} : Chamorro
{ce} : Chechen
{chr} : Cherokee

eq Tsalagi

{chy} : Cheyenne
{chb} : Chibcha

(Historical) NOT Chibchan (which is a language family).

{ny} : Chichewa

eq Nyanja. eq Chinyanja.

{zh} : Chinese

Many forms are mutually un-intelligible in spoken media.
Notable forms:
{zh-Hans} Chinese, in simplified script;
{zh-Hant} Chinese, in traditional script;
{zh-tw} Taiwan Chinese;
{zh-cn} PRC Chinese;
{zh-sg} Singapore Chinese;
{zh-mo} Macau Chinese;
{zh-hk} Hong Kong Chinese;
{zh-guoyu} Mandarin [Putonghua/Guoyu];
{zh-hakka} Hakka [formerly "i-hakka"];
{zh-min} Hokkien;
{zh-min-nan} Southern Hokkien;
{zh-wuu} Shanghaiese;
{zh-xiang} Hunanese;
{zh-gan} Gan;
{zh-yue} Cantonese.

{chn} : Chinook Jargon

eq Chinook Wawa.

{chp} : Chipewyan
{cho} : Choctaw
{cu} : Church Slavic

eq Old Church Slavonic.

{chk} : Chuukese

eq Trukese. eq Chuuk. eq Truk. eq Ruk.

{cv} : Chuvash
{cop} : Coptic
{kw} : Cornish
{co} : Corsican

eq Corse.

{cr} : Cree

NOT Creek! (Formerly "cre".)

{mus} : Creek

NOT Cree!

[{cpe} : English-based Creoles and pidgins (Other)]
[{cpf} : French-based Creoles and pidgins (Other)]
[{cpp} : Portuguese-based Creoles and pidgins (Other)]
[{crp} : Creoles and pidgins (Other)]
{hr} : Croatian

eq Croat.

[{cus} : Cushitic (Other)]
{cs} : Czech
{dak} : Dakota

eq Nakota. eq Latoka.

{da} : Danish
{dar} : Dargwa
{day} : Dayak
{i-default} : Default (Fallthru) Language

Defined in RFC 2277, this is for tagging text (which must include English text, and might/should include text in other appropriate languages) that is emitted in a context where language-negotiation wasn't possible -- in SMTP mail failure messages, for example.

{del} : Delaware
{din} : Dinka
{dv} : Divehi

eq Maldivian. (Formerly "div".)

{doi} : Dogri

NOT Dogrib!

{dgr} : Dogrib

NOT Dogri!

[{dra} : Dravidian (Other)]
{dua} : Duala
{nl} : Dutch

eq Netherlander. Notable forms: {nl-nl} Netherlands Dutch; {nl-be} Belgian Dutch.

{dum} : Middle Dutch (ca.1050-1350)

(Historical)

{dyu} : Dyula
{dz} : Dzongkha
{efi} : Efik
{egy} : Ancient Egyptian

(Historical)

{eka} : Ekajuk
{elx} : Elamite

(Historical)

{en} : English

Notable forms:
{en-au} Australian English;
{en-bz} Belize English;
{en-ca} Canadian English;
{en-gb} UK English;
{en-ie} Irish English;
{en-jm} Jamaican English;
{en-nz} New Zealand English;
{en-ph} Philippine English;
{en-tt} Trinidad English;
{en-us} US English;
{en-za} South African English;
{en-zw} Zimbabwe English.

{enm} : Old English (1100-1500)

(Historical)

{ang} : Old English (ca.450-1100)

eq Anglo-Saxon. (Historical)

{i-enochian} : Enochian (Artificial)
{myv} : Erzya
{eo} : Esperanto

(Artificial)

{et} : Estonian
{ee} : Ewe

(Formerly "ewe".)

{ewo} : Ewondo
{fan} : Fang
{fat} : Fanti
{fo} : Faroese
{fj} : Fijian
{fi} : Finnish
[{fiu} : Finno-Ugrian (Other)]

eq Finno-Ugric. NOT Ugaritic!

{fon} : Fon
{fr} : French

Notable forms:
{fr-fr} France French;
{fr-be} Belgian French;
{fr-ca} Canadian French;
{fr-ch} Swiss French;
{fr-lu} Luxembourg French;
{fr-mc} Monaco French.

{frm} : Middle French (ca.1400-1600)

(Historical)

{fro} : Old French (842-ca.1400)

(Historical)

{fy} : Frisian
{fur} : Friulian
{ff} : Fulah

(Formerly "ful".)

{gaa} : Ga
{gd} : Scots Gaelic

NOT Scots!

{gl} : Gallegan

eq Galician

{lg} : Ganda

(Formerly "lug".)

{gay} : Gayo
{gba} : Gbaya
{gez} : Geez

eq Ge'ez

{ka} : Georgian
{de} : German

Notable forms:
{de-at} Austrian German;
{de-be} Belgian German;
{de-ch} Swiss German;
{de-de} Germany German;
{de-li} Liechtenstein German;
{de-lu} Luxembourg German.

{gmh} : Middle High German (ca.1050-1500)

(Historical)

{goh} : Old High German (ca.750-1050)

(Historical)

[{gem} : Germanic (Other)]
{gil} : Gilbertese
{gon} : Gondi
{gor} : Gorontalo
{got} : Gothic

(Historical)

{grb} : Grebo
{grc} : Ancient Greek

(Historical) (Until 15th century or so.)

{el} : Modern Greek

(Since 15th century or so.)

{gn} : Guarani

Guaraní

{gu} : Gujarati
{gwi} : Gwich'in

eq Gwichin

{hai} : Haida
{ht} : Haitian

eq Haitian Creole

{ha} : Hausa
{haw} : Hawaiian

Hawai'ian

{he} : Hebrew

(Formerly "iw".)

{hz} : Herero
{hil} : Hiligaynon
{him} : Himachali
{hi} : Hindi
{ho} : Hiri Motu
{hit} : Hittite

(Historical)

{hmn} : Hmong
{hu} : Hungarian
{hup} : Hupa
{iba} : Iban
{is} : Icelandic
{io} : Ido

(Artificial)

{ig} : Igbo

(Formerly "ibo".)

{ijo} : Ijo
{ilo} : Iloko
[{inc} : Indic (Other)]
[{ine} : Indo-European (Other)]
{id} : Indonesian

(Formerly "in".)

{inh} : Ingush
{ia} : Interlingua (International Auxiliary Language Association)

(Artificial) NOT Interlingue!

{ie} : Interlingue

(Artificial) NOT Interlingua!

{iu} : Inuktitut

A subform of "Eskimo".

{ik} : Inupiaq

A subform of "Eskimo".

[{ira} : Iranian (Other)]
{ga} : Irish
{mga} : Middle Irish (900-1200)

(Historical)

{sga} : Old Irish (to 900)

(Historical)

[{iro} : Iroquoian languages]
{it} : Italian

Notable forms: {it-it} Italy Italian; {it-ch} Swiss Italian.

{ja} : Japanese

(NOT "jp"!)

{jv} : Javanese

(Formerly "jw" because of a typo.)

{jrb} : Judeo-Arabic
{jpr} : Judeo-Persian
{kbd} : Kabardian
{kab} : Kabyle
{kac} : Kachin
{kl} : Kalaallisut

eq Greenlandic "Eskimo"

{xal} : Kalmyk
{kam} : Kamba
{kn} : Kannada

eq Kanarese. NOT Canadian!

{kr} : Kanuri

(Formerly "kau".)

{krc} : Karachay-Balkar
{kaa} : Kara-Kalpak
{kar} : Karen
{ks} : Kashmiri
{csb} : Kashubian

eq Kashub

{kaw} : Kawi
{kk} : Kazakh
{kha} : Khasi
{km} : Khmer

eq Cambodian. eq Kampuchean.

[{khi} : Khoisan (Other)]
{kho} : Khotanese
{ki} : Kikuyu

eq Gikuyu.

{kmb} : Kimbundu
{rw} : Kinyarwanda
{ky} : Kirghiz
{i-klingon} : Klingon
{kv} : Komi
{kg} : Kongo

(Formerly "kon".)

{kok} : Konkani
{ko} : Korean
{kos} : Kosraean
{kpe} : Kpelle
{kro} : Kru
{kj} : Kuanyama
{kum} : Kumyk
{ku} : Kurdish
{kru} : Kurukh
{kut} : Kutenai
{lad} : Ladino

eq Judeo-Spanish. NOT Ladin (a minority language in Italy).

{lah} : Lahnda

NOT Lamba!

{lam} : Lamba

NOT Lahnda!

{lo} : Lao

eq Laotian.

{la} : Latin

(Historical) NOT Ladin! NOT Ladino!

{lv} : Latvian

eq Lettish.

{lb} : Letzeburgesch

eq Luxemburgian, eq Luxemburger. (Formerly "i-lux".)

{lez} : Lezghian
{li} : Limburgish

eq Limburger, eq Limburgan. NOT Letzeburgesch!

{ln} : Lingala
{lt} : Lithuanian
{nds} : Low German

eq Low Saxon. eq Low German. eq Low Saxon.

{art-lojban} : Lojban (Artificial)
{loz} : Lozi
{lu} : Luba-Katanga

(Formerly "lub".)

{lua} : Luba-Lulua
{lui} : Luiseno

eq Luiseño.

{lun} : Lunda
{luo} : Luo (Kenya and Tanzania)
{lus} : Lushai
{mk} : Macedonian

eq the modern Slavic language spoken in what was Yugoslavia. NOT the form of Greek spoken in Greek Macedonia!

{mad} : Madurese
{mag} : Magahi
{mai} : Maithili
{mak} : Makasar
{mg} : Malagasy
{ms} : Malay

NOT Malayalam!

{ml} : Malayalam

NOT Malay!

{mt} : Maltese
{mnc} : Manchu
{mdr} : Mandar

NOT Mandarin!

{man} : Mandingo
{mni} : Manipuri

eq Meithei.

[{mno} : Manobo languages]
{gv} : Manx
{mi} : Maori

NOT Mari!

{mr} : Marathi
{chm} : Mari

NOT Maori!

{mh} : Marshall

eq Marshallese.

{mwr} : Marwari
{mas} : Masai
[{myn} : Mayan languages]
{men} : Mende
{mic} : Micmac
{min} : Minangkabau
{i-mingo} : Mingo

eq the Irquoian language West Virginia Seneca. NOT New York Seneca!

[{mis} : Miscellaneous languages]

Don't use this.

{moh} : Mohawk
{mdf} : Moksha
{mo} : Moldavian

eq Moldovan.

[{mkh} : Mon-Khmer (Other)]
{lol} : Mongo
{mn} : Mongolian

eq Mongol.

{mos} : Mossi
[{mul} : Multiple languages]

Not for normal use.

[{mun} : Munda languages]
{nah} : Nahuatl
{nap} : Neapolitan
{na} : Nauru
{nv} : Navajo

eq Navaho. (Formerly "i-navajo".)

{nd} : North Ndebele
{nr} : South Ndebele
{ng} : Ndonga
{ne} : Nepali

eq Nepalese. Notable forms: {ne-np} Nepal Nepali; {ne-in} India Nepali.

{new} : Newari
{nia} : Nias
[{nic} : Niger-Kordofanian (Other)]
[{ssa} : Nilo-Saharan (Other)]
{niu} : Niuean
{nog} : Nogai
{non} : Old Norse

(Historical)

[{nai} : North American Indian]

Do not use this.

{no} : Norwegian

Note the two following forms:

{nb} : Norwegian Bokmal

eq Bokmål, (A form of Norwegian.) (Formerly "no-bok".)

{nn} : Norwegian Nynorsk

(A form of Norwegian.) (Formerly "no-nyn".)

[{nub} : Nubian languages]
{nym} : Nyamwezi
{nyn} : Nyankole
{nyo} : Nyoro
{nzi} : Nzima
{oc} : Occitan (post 1500)

eq Provençal, eq Provencal

{oj} : Ojibwa

eq Ojibwe. (Formerly "oji".)

{or} : Oriya
{om} : Oromo
{osa} : Osage
{os} : Ossetian; Ossetic
[{oto} : Otomian languages]

Group of languages collectively called "Otomí".

{pal} : Pahlavi

eq Pahlevi

{i-pwn} : Paiwan

eq Pariwan

{pau} : Palauan
{pi} : Pali

(Historical?)

{pam} : Pampanga
{pag} : Pangasinan
{pa} : Panjabi

eq Punjabi

{pap} : Papiamento

eq Papiamentu.

[{paa} : Papuan (Other)]
{fa} : Persian

eq Farsi. eq Iranian.

{peo} : Old Persian (ca.600-400 B.C.)
[{phi} : Philippine (Other)]
{phn} : Phoenician

(Historical)

{pon} : Pohnpeian

NOT Pompeiian!

{pl} : Polish
{pt} : Portuguese

eq Portugese. Notable forms: {pt-pt} Portugal Portuguese; {pt-br} Brazilian Portuguese.

[{pra} : Prakrit languages]
{pro} : Old Provencal (to 1500)

eq Old Provençal. (Historical.)

{ps} : Pushto

eq Pashto. eq Pushtu.

{qu} : Quechua

eq Quecha.

{rm} : Raeto-Romance

eq Romansh.

{raj} : Rajasthani
{rap} : Rapanui
{rar} : Rarotongan
[{qaa - qtz} : Reserved for local use.]
[{roa} : Romance (Other)]

NOT Romanian! NOT Romany! NOT Romansh!

{ro} : Romanian

eq Rumanian. NOT Romany!

{rom} : Romany

eq Rom. NOT Romanian!

{rn} : Rundi
{ru} : Russian

NOT White Russian! NOT Rusyn!

[{sal} : Salishan languages]

Large language group.

{sam} : Samaritan Aramaic

NOT Aramaic!

{se} : Northern Sami

eq Lappish. eq Lapp. eq (Northern) Saami.

{sma} : Southern Sami
{smn} : Inari Sami
{smj} : Lule Sami
{sms} : Skolt Sami
[{smi} : Sami languages (Other)]
{sm} : Samoan
{sad} : Sandawe
{sg} : Sango
{sa} : Sanskrit

(Historical)

{sat} : Santali
{sc} : Sardinian

eq Sard.

{sas} : Sasak
{sco} : Scots

NOT Scots Gaelic!

{sel} : Selkup
[{sem} : Semitic (Other)]
{sr} : Serbian

eq Serb. NOT Sorbian.

Notable forms: {sr-Cyrl} : Serbian in Cyrillic script; {sr-Latn} : Serbian in Latin script.

{srr} : Serer
{shn} : Shan
{sn} : Shona
{sid} : Sidamo
{sgn-...} : Sign Languages

Always use with a subtag.  Notable forms:
{sgn-gb} British Sign Language (BSL);
{sgn-ie} Irish Sign Language (ESL);
{sgn-ni} Nicaraguan Sign Language (ISN);
{sgn-us} American Sign Language (ASL).

(And so on with other country codes as the subtag.)

{bla} : Siksika

eq Blackfoot. eq Pikanii.

{sd} : Sindhi
{si} : Sinhalese

eq Sinhala.

[{sit} : Sino-Tibetan (Other)]
[{sio} : Siouan languages]
{den} : Slave (Athapascan)

("Slavey" is a subform.)

[{sla} : Slavic (Other)]
{sk} : Slovak

eq Slovakian.

{sl} : Slovenian

eq Slovene.

{sog} : Sogdian
{so} : Somali
{son} : Songhai
{snk} : Soninke
{wen} : Sorbian languages

eq Wendish. eq Sorb. eq Lusatian. eq Wend. NOT Venda! NOT Serbian!

{nso} : Northern Sotho
{st} : Southern Sotho

eq Sutu. eq Sesotho.

[{sai} : South American Indian (Other)]
{es} : Spanish

Notable forms:
{es-ar} Argentine Spanish;
{es-bo} Bolivian Spanish;
{es-cl} Chilean Spanish;
{es-co} Colombian Spanish;
{es-do} Dominican Spanish;
{es-ec} Ecuadorian Spanish;
{es-es} Spain Spanish;
{es-gt} Guatemalan Spanish;
{es-hn} Honduran Spanish;
{es-mx} Mexican Spanish;
{es-pa} Panamanian Spanish;
{es-pe} Peruvian Spanish;
{es-pr} Puerto Rican Spanish;
{es-py} Paraguay Spanish;
{es-sv} Salvadoran Spanish;
{es-us} US Spanish;
{es-uy} Uruguayan Spanish;
{es-ve} Venezuelan Spanish.

{suk} : Sukuma
{sux} : Sumerian

(Historical)

{su} : Sundanese
{sus} : Susu
{sw} : Swahili

eq Kiswahili

{ss} : Swati
{sv} : Swedish

Notable forms: {sv-se} Sweden Swedish; {sv-fi} Finland Swedish.

{syr} : Syriac
{tl} : Tagalog
{ty} : Tahitian
[{tai} : Tai (Other)]

NOT Thai!

{tg} : Tajik
{tmh} : Tamashek
{ta} : Tamil
{i-tao} : Tao

eq Yami.

{tt} : Tatar
{i-tay} : Tayal

eq Atayal. eq Atayan.

{te} : Telugu
{ter} : Tereno
{tet} : Tetum
{th} : Thai

NOT Tai!

{bo} : Tibetan
{tig} : Tigre
{ti} : Tigrinya
{tem} : Timne

eq Themne. eq Timene.

{tiv} : Tiv
{tli} : Tlingit
{tpi} : Tok Pisin
{tkl} : Tokelau
{tog} : Tonga (Nyasa)

NOT Tsonga!

{to} : Tonga (Tonga Islands)

(Pronounced "Tong-a", not "Tong-ga")

NOT Tsonga!

{tsi} : Tsimshian

eq Sm'algyax

{ts} : Tsonga

NOT Tonga!

{i-tsu} : Tsou
{tn} : Tswana

Same as Setswana.

{tum} : Tumbuka
[{tup} : Tupi languages]
{tr} : Turkish

(Typically in Roman script)

{ota} : Ottoman Turkish (1500-1928)

(Typically in Arabic script) (Historical)

{crh} : Crimean Turkish

eq Crimean Tatar

{tk} : Turkmen

eq Turkmeni.

{tvl} : Tuvalu
{tyv} : Tuvinian

eq Tuvan. eq Tuvin.

{tw} : Twi
{udm} : Udmurt
{uga} : Ugaritic

NOT Ugric!

{ug} : Uighur
{uk} : Ukrainian
{umb} : Umbundu
{und} : Undetermined

Not a tag for normal use.

{ur} : Urdu
{uz} : Uzbek

eq Özbek

Notable forms: {uz-Cyrl} Uzbek in Cyrillic script; {uz-Latn} Uzbek in Latin script.

{vai} : Vai
{ve} : Venda

NOT Wendish! NOT Wend! NOT Avestan! (Formerly "ven".)

{vi} : Vietnamese

eq Viet.

{vo} : Volapuk

eq Volapük. (Artificial)

{vot} : Votic

eq Votian. eq Vod.

[{wak} : Wakashan languages]
{wa} : Walloon
{wal} : Walamo

eq Wolaytta.

{war} : Waray

Presumably the Philippine language Waray-Waray (Samareño), not the smaller Philippine language Waray Sorsogon, nor the extinct Australian language Waray.

{was} : Washo

eq Washoe

{cy} : Welsh
{wo} : Wolof
{x-...} : Unregistered (Semi-Private Use)

"x-" is a prefix for language tags that are not registered with ISO or IANA. Example, x-double-dutch

{xh} : Xhosa
{sah} : Yakut
{yao} : Yao

(The Yao in Malawi?)

{yap} : Yapese

eq Yap

{ii} : Sichuan Yi
{yi} : Yiddish

Formerly "ji". Usually in Hebrew script.

Notable forms: {yi-latn} Yiddish in Latin script

{yo} : Yoruba
[{ypk} : Yupik languages]

Several "Eskimo" languages.

{znd} : Zande
[{zap} : Zapotec]

(A group of languages.)

{zen} : Zenaga

NOT Zend.

{za} : Zhuang
{zu} : Zulu
{zun} : Zuni

eq Zuñi

SEE ALSO

I18N::LangTags and its "See Also" section.

COPYRIGHT AND DISCLAIMER

Copyright (c) 2001+ Sean M. Burke. All rights reserved.

You can redistribute and/or modify this document under the same terms as Perl itself.

This document is provided in the hope that it will be useful, but without any warranty; without even the implied warranty of accuracy, authoritativeness, completeness, merchantability, or fitness for a particular purpose.

Email any corrections or questions to me.

AUTHOR

Sean M. Burke, sburke@cpan.org


IO - load various IO modules

  • DEPRECATED

NAME

IO - load various IO modules

SYNOPSIS

    use IO qw(Handle File);  # loads IO modules, here IO::Handle, IO::File
    use IO;                  # DEPRECATED

DESCRIPTION

IO provides a simple mechanism to load several of the IO modules in one go. The IO modules belonging to the core are:

      IO::Handle
      IO::Seekable
      IO::File
      IO::Pipe
      IO::Socket
      IO::Dir
      IO::Select
      IO::Poll

Some other IO modules don't belong to the perl core but can be loaded as well if they have been installed from CPAN. You can discover which ones exist by searching for "^IO::" on http://search.cpan.org.

For more information on any of these modules, please see its respective documentation.

DEPRECATED

    use IO;                # loads all the modules listed below

The loaded modules are IO::Handle, IO::Seekable, IO::File, IO::Pipe, IO::Socket, IO::Dir. You should instead explicitly import the IO modules you want.


IO::Dir - supply object methods for directory handles

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Dir - supply object methods for directory handles

SYNOPSIS

    use IO::Dir;
    $d = IO::Dir->new(".");
    if (defined $d) {
        while (defined($_ = $d->read)) { something($_); }
        $d->rewind;
        while (defined($_ = $d->read)) { something_else($_); }
        undef $d;
    }

    tie %dir, 'IO::Dir', ".";
    foreach (keys %dir) {
        print $_, " " , $dir{$_}->size,"\n";
    }

DESCRIPTION

The IO::Dir package provides two interfaces to perl's directory reading routines.

The first interface is an object approach. IO::Dir provides an object constructor and methods, which are just wrappers around perl's built in directory reading routines.

new ( [ DIRNAME ] )

new is the constructor for IO::Dir objects. It accepts one optional argument which, if given, new will pass to open

The following methods are wrappers for the directory related functions built into perl (the trailing `dir' has been removed from the names). See the perlfunc manpage for details of these functions.

open ( DIRNAME )
read ()
seek ( POS )
tell ()
rewind ()
close ()

IO::Dir also provides an interface to reading directories via a tied hash. The tied hash extends the interface beyond just the directory reading routines by the use of lstat, from the File::stat package, unlink, rmdir and utime.

tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]

The keys of the hash will be the names of the entries in the directory. Reading a value from the hash will be the result of calling File::stat::lstat. Deleting an element from the hash will delete the corresponding file or subdirectory, provided that DIR_UNLINK is included in the OPTIONS.

Assigning to an entry in the hash will cause the time stamps of the file to be modified. If the file does not exist then it will be created. Assigning a single integer to a hash element will cause both the access and modification times to be changed to that value. Alternatively a reference to an array of two values can be passed. The first array element will be used to set the access time and the second element will be used to set the modification time.

SEE ALSO

the File::stat manpage

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1997-2003 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::File - supply object methods for filehandles

  • CONSTRUCTOR
  • METHODS
  • NOTE
  • SEE ALSO
  • HISTORY

NAME

IO::File - supply object methods for filehandles

SYNOPSIS

    use IO::File;

    $fh = new IO::File;
    if ($fh->open("< file")) {
        print <$fh>;
        $fh->close;
    }

    $fh = new IO::File "> file";
    if (defined $fh) {
        print $fh "bar\n";
        $fh->close;
    }

    $fh = new IO::File "file", "r";
    if (defined $fh) {
        print <$fh>;
        undef $fh;       # automatically closes the file
    }

    $fh = new IO::File "file", O_WRONLY|O_APPEND;
    if (defined $fh) {
        print $fh "corge\n";

        $pos = $fh->getpos;
        $fh->setpos($pos);

        undef $fh;       # automatically closes the file
            }

    autoflush STDOUT 1;

DESCRIPTION

IO::File inherits from IO::Handle and IO::Seekable. It extends these classes with methods that are specific to file handles.

CONSTRUCTOR

new ( FILENAME [,MODE [,PERMS]] )

Creates an IO::File. If it receives any parameters, they are passed to the method open; if the open fails, the object is destroyed. Otherwise, it is returned to the caller.

new_tmpfile

Creates an IO::File opened for read/write on a newly created temporary file. On systems where this is possible, the temporary file is anonymous (i.e. it is unlinked after creation, but held open). If the temporary file cannot be created or opened, the IO::File object is destroyed. Otherwise, it is returned to the caller.

METHODS

open( FILENAME [,MODE [,PERMS]] )
open( FILENAME, IOLAYERS )

open accepts one, two or three parameters. With one parameter, it is just a front end for the built-in open function. With two or three parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode, optionally followed by a file permission value.

If IO::File::open receives a Perl mode string (">", "+<", etc.) or an ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic Perl open operator (but protects any special characters).

If IO::File::open is given a numeric mode, it passes that mode and the optional permissions value to the Perl sysopen operator. The permissions default to 0666.

If IO::File::open is given a mode that includes the : character, it passes all the three arguments to the three-argument open operator.

For convenience, IO::File exports the O_XXX constants from the Fcntl module, if this module is available.

binmode( [LAYER] )

binmode sets binmode on the underlying IO object, as documented in perldoc -f binmode.

binmode accepts one optional parameter, which is the layer to be passed on to the binmode call.

NOTE

Some operating systems may perform IO::File::new() or IO::File::open() on a directory without errors. This behavior is not portable and not suggested for use. Using opendir() and readdir() or IO::Dir are suggested instead.

SEE ALSO

the perlfunc manpage,
I/O Operators in the perlop manpage,
the IO::Handle manpage,
the IO::Seekable manpage,
the IO::Dir manpage

HISTORY

Derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>.


IO::Handle - supply object methods for I/O handles

  • CONSTRUCTOR
  • METHODS
  • NOTE
  • SEE ALSO
  • BUGS
  • HISTORY

NAME

IO::Handle - supply object methods for I/O handles

SYNOPSIS

    use IO::Handle;

    $io = new IO::Handle;
    if ($io->fdopen(fileno(STDIN),"r")) {
        print $io->getline;
        $io->close;
    }

    $io = new IO::Handle;
    if ($io->fdopen(fileno(STDOUT),"w")) {
        $io->print("Some text\n");
    }

    # setvbuf is not available by default on Perls 5.8.0 and later.
    use IO::Handle '_IOLBF';
    $io->setvbuf($buffer_var, _IOLBF, 1024);

    undef $io;       # automatically closes the file if it's open

    autoflush STDOUT 1;

DESCRIPTION

IO::Handle is the base class for all other IO handle classes. It is not intended that objects of IO::Handle would be created directly, but instead IO::Handle is inherited from by several other classes in the IO hierarchy.

If you are reading this documentation, looking for a replacement for the FileHandle package, then I suggest you read the documentation for IO::File too.

CONSTRUCTOR

new ()

Creates a new IO::Handle object.

new_from_fd ( FD, MODE )

Creates an IO::Handle like new does. It requires two parameters, which are passed to the method fdopen; if the fdopen fails, the object is destroyed. Otherwise, it is returned to the caller.

METHODS

See the perlfunc manpage for complete descriptions of each of the following supported IO::Handle methods, which are just front ends for the corresponding built-in functions:

    $io->close
    $io->eof
    $io->fileno
    $io->format_write( [FORMAT_NAME] )
    $io->getc
    $io->read ( BUF, LEN, [OFFSET] )
    $io->print ( ARGS )
    $io->printf ( FMT, [ARGS] )
    $io->stat
    $io->sysread ( BUF, LEN, [OFFSET] )
    $io->syswrite ( BUF, [LEN, [OFFSET]] )
    $io->truncate ( LEN )

See the perlvar manpage for complete descriptions of each of the following supported IO::Handle methods. All of them return the previous value of the attribute and takes an optional single argument that when given will set the value. If no argument is given the previous value is unchanged (except for $io->autoflush will actually turn ON autoflush by default).

    $io->autoflush ( [BOOL] )                         $|
    $io->format_page_number( [NUM] )                  $%
    $io->format_lines_per_page( [NUM] )               $=
    $io->format_lines_left( [NUM] )                   $-
    $io->format_name( [STR] )                         $~
    $io->format_top_name( [STR] )                     $^
    $io->input_line_number( [NUM])                    $.

The following methods are not supported on a per-filehandle basis.

    IO::Handle->format_line_break_characters( [STR] ) $:
    IO::Handle->format_formfeed( [STR])               $^L
    IO::Handle->output_field_separator( [STR] )       $,
    IO::Handle->output_record_separator( [STR] )      $\
    IO::Handle->input_record_separator( [STR] )       $/

Furthermore, for doing normal I/O you might need these:

$io->fdopen ( FD, MODE )

fdopen is like an ordinary open except that its first parameter is not a filename but rather a file handle name, an IO::Handle object, or a file descriptor number.

$io->opened

Returns true if the object is currently a valid file descriptor, false otherwise.

$io->getline

This works like <$io> described in I/O Operators in the perlop manpage except that it's more readable and can be safely called in a list context but still returns just one line. If used as the conditional +within a while or C-style for loop, however, you will need to +emulate the functionality of <$io> with defined($_ = $io->getline).

$io->getlines

This works like <$io> when called in a list context to read all the remaining lines in a file, except that it's more readable. It will also croak() if accidentally called in a scalar context.

$io->ungetc ( ORD )

Pushes a character with the given ordinal value back onto the given handle's input stream. Only one character of pushback per handle is guaranteed.

$io->write ( BUF, LEN [, OFFSET ] )

This write is like write found in C, that is it is the opposite of read. The wrapper for the perl write function is called format_write.

$io->error

Returns a true value if the given handle has experienced any errors since it was opened or since the last call to clearerr, or if the handle is invalid. It only returns false for a valid handle with no outstanding errors.

$io->clearerr

Clear the given handle's error indicator. Returns -1 if the handle is invalid, 0 otherwise.

$io->sync

sync synchronizes a file's in-memory state with that on the physical medium. sync does not operate at the perlio api level, but operates on the file descriptor (similar to sysread, sysseek and systell). This means that any data held at the perlio api level will not be synchronized. To synchronize data that is buffered at the perlio api level you must use the flush method. sync is not implemented on all platforms. Returns "0 but true" on success, undef on error, undef for an invalid handle. See fsync(3c).

$io->flush

flush causes perl to flush any buffered data at the perlio api level. Any unread data in the buffer will be discarded, and any unwritten data will be written to the underlying file descriptor. Returns "0 but true" on success, undef on error.

$io->printflush ( ARGS )

Turns on autoflush, print ARGS and then restores the autoflush status of the IO::Handle object. Returns the return value from print.

$io->blocking ( [ BOOL ] )

If called with an argument blocking will turn on non-blocking IO if BOOL is false, and turn it off if BOOL is true.

blocking will return the value of the previous setting, or the current setting if BOOL is not given.

If an error occurs blocking will return undef and $! will be set.

If the C functions setbuf() and/or setvbuf() are available, then IO::Handle::setbuf and IO::Handle::setvbuf set the buffering policy for an IO::Handle. The calling sequences for the Perl functions are the same as their C counterparts--including the constants _IOFBF, _IOLBF, and _IONBF for setvbuf()--except that the buffer parameter specifies a scalar variable to use as a buffer. You should only change the buffer before any I/O, or immediately after calling flush.

WARNING: The IO::Handle::setvbuf() is not available by default on Perls 5.8.0 and later because setvbuf() is rather specific to using the stdio library, while Perl prefers the new perlio subsystem instead.

WARNING: A variable used as a buffer by setbuf or setvbuf must not be modified in any way until the IO::Handle is closed or setbuf or setvbuf is called again, or memory corruption may result! Remember that the order of global destruction is undefined, so even if your buffer variable remains in scope until program termination, it may be undefined before the file IO::Handle is closed. Note that you need to import the constants _IOFBF, _IOLBF, and _IONBF explicitly. Like C, setbuf returns nothing. setvbuf returns "0 but true", on success, undef on failure.

Lastly, there is a special method for working under -T and setuid/gid scripts:

$io->untaint

Marks the object as taint-clean, and as such data read from it will also be considered taint-clean. Note that this is a very trusting action to take, and appropriate consideration for the data source and potential vulnerability should be kept in mind. Returns 0 on success, -1 if setting the taint-clean flag failed. (eg invalid handle)

NOTE

An IO::Handle object is a reference to a symbol/GLOB reference (see the Symbol package). Some modules that inherit from IO::Handle may want to keep object related variables in the hash table part of the GLOB. In an attempt to prevent modules trampling on each other I propose the that any such module should prefix its variables with its own name separated by _'s. For example the IO::Socket module keeps a timeout variable in 'io_socket_timeout'.

SEE ALSO

the perlfunc manpage, I/O Operators in the perlop manpage, the IO::File manpage

BUGS

Due to backwards compatibility, all filehandles resemble objects of class IO::Handle, or actually classes derived from that class. They actually aren't. Which means you can't derive your own class from IO::Handle and inherit those methods.

HISTORY

Derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>


IO::Pipe - supply object methods for pipes

  • CONSTRUCTOR
  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Pipe - supply object methods for pipes

SYNOPSIS

        use IO::Pipe;

        $pipe = new IO::Pipe;

        if($pid = fork()) { # Parent
            $pipe->reader();

            while(<$pipe>) {
                ...
            }

        }
        elsif(defined $pid) { # Child
            $pipe->writer();

            print $pipe ...
        }
        or
        $pipe = new IO::Pipe;

        $pipe->reader(qw(ls -l));

        while(<$pipe>) {
            ...
        }

DESCRIPTION

IO::Pipe provides an interface to creating pipes between processes.

CONSTRUCTOR

new ( [READER, WRITER] )

Creates an IO::Pipe, which is a reference to a newly created symbol (see the Symbol package). IO::Pipe::new optionally takes two arguments, which should be objects blessed into IO::Handle, or a subclass thereof. These two objects will be used for the system call to pipe. If no arguments are given then method handles is called on the new IO::Pipe object.

These two handles are held in the array part of the GLOB until either reader or writer is called.

METHODS

reader ([ARGS])

The object is re-blessed into a sub-class of IO::Handle, and becomes a handle at the reading end of the pipe. If ARGS are given then fork is called and ARGS are passed to exec.

writer ([ARGS])

The object is re-blessed into a sub-class of IO::Handle, and becomes a handle at the writing end of the pipe. If ARGS are given then fork is called and ARGS are passed to exec.

handles ()

This method is called during construction by IO::Pipe::new on the newly created IO::Pipe object. It returns an array of two objects blessed into IO::Pipe::End, or a subclass thereof.

SEE ALSO

the IO::Handle manpage

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::Poll - Object interface to system poll call

  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Poll - Object interface to system poll call

SYNOPSIS

    use IO::Poll qw(POLLRDNORM POLLWRNORM POLLIN POLLHUP);

    $poll = new IO::Poll;

    $poll->mask($input_handle => POLLIN);
    $poll->mask($output_handle => POLLOUT);

    $poll->poll($timeout);

    $ev = $poll->events($input);

DESCRIPTION

IO::Poll is a simple interface to the system level poll routine.

METHODS

mask ( IO [, EVENT_MASK ] )

If EVENT_MASK is given, then, if EVENT_MASK is non-zero, IO is added to the list of file descriptors and the next call to poll will check for any event specified in EVENT_MASK. If EVENT_MASK is zero then IO will be removed from the list of file descriptors.

If EVENT_MASK is not given then the return value will be the current event mask value for IO.

poll ( [ TIMEOUT ] )

Call the system level poll routine. If TIMEOUT is not specified then the call will block. Returns the number of handles which had events happen, or -1 on error.

events ( IO )

Returns the event mask which represents the events that happened on IO during the last call to poll.

remove ( IO )

Remove IO from the list of file descriptors for the next poll.

handles( [ EVENT_MASK ] )

Returns a list of handles. If EVENT_MASK is not given then a list of all handles known will be returned. If EVENT_MASK is given then a list of handles will be returned which had one of the events specified by EVENT_MASK happen during the last call ti poll

SEE ALSO

poll(2), the IO::Handle manpage, the IO::Select manpage

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::Seekable - supply seek based methods for I/O objects

  • SEE ALSO
  • HISTORY

NAME

IO::Seekable - supply seek based methods for I/O objects

SYNOPSIS

    use IO::Seekable;
    package IO::Something;
    @ISA = qw(IO::Seekable);

DESCRIPTION

IO::Seekable does not have a constructor of its own as it is intended to be inherited by other IO::Handle based objects. It provides methods which allow seeking of the file descriptors.

$io->getpos

Returns an opaque value that represents the current position of the IO::File, or undef if this is not possible (eg an unseekable stream such as a terminal, pipe or socket). If the fgetpos() function is available in your C library it is used to implements getpos, else perl emulates getpos using C's ftell() function.

$io->setpos

Uses the value of a previous getpos call to return to a previously visited position. Returns "0 but true" on success, undef on failure.

See the perlfunc manpage for complete descriptions of each of the following supported IO::Seekable methods, which are just front ends for the corresponding built-in functions:

$io->seek ( POS, WHENCE )

Seek the IO::File to position POS, relative to WHENCE:

WHENCE=0 (SEEK_SET)

POS is absolute position. (Seek relative to the start of the file)

WHENCE=1 (SEEK_CUR)

POS is an offset from the current position. (Seek relative to current)

WHENCE=2 (SEEK_END)

POS is an offset from the end of the file. (Seek relative to end)

The SEEK_* constants can be imported from the Fcntl module if you don't wish to use the numbers 0 1 or 2 in your code.

Returns 1 upon success, 0 otherwise.

$io->sysseek( POS, WHENCE )

Similar to $io->seek, but sets the IO::File's position using the system call lseek(2) directly, so will confuse most perl IO operators except sysread and syswrite (see the perlfunc manpage for full details)

Returns the new position, or undef on failure. A position of zero is returned as the string "0 but true"

$io->tell

Returns the IO::File's current position, or -1 on error.

SEE ALSO

the perlfunc manpage, I/O Operators in the perlop manpage, the IO::Handle manpage the IO::File manpage

HISTORY

Derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>


IO::Select - OO interface to the select system call

  • CONSTRUCTOR
  • METHODS
  • EXAMPLE
  • AUTHOR
  • COPYRIGHT

NAME

IO::Select - OO interface to the select system call

SYNOPSIS

    use IO::Select;

    $s = IO::Select->new();

    $s->add(\*STDIN);
    $s->add($some_handle);

    @ready = $s->can_read($timeout);

    @ready = IO::Select->new(@handles)->can_read(0);

DESCRIPTION

The IO::Select package implements an object approach to the system select function call. It allows the user to see what IO handles, see the IO::Handle manpage, are ready for reading, writing or have an exception pending.

CONSTRUCTOR

new ( [ HANDLES ] )

The constructor creates a new object and optionally initialises it with a set of handles.

METHODS

add ( HANDLES )

Add the list of handles to the IO::Select object. It is these values that will be returned when an event occurs. IO::Select keeps these values in a cache which is indexed by the fileno of the handle, so if more than one handle with the same fileno is specified then only the last one is cached.

Each handle can be an IO::Handle object, an integer or an array reference where the first element is an IO::Handle or an integer.

remove ( HANDLES )

Remove all the given handles from the object. This method also works by the fileno of the handles. So the exact handles that were added need not be passed, just handles that have an equivalent fileno

exists ( HANDLE )

Returns a true value (actually the handle itself) if it is present. Returns undef otherwise.

handles

Return an array of all registered handles.

can_read ( [ TIMEOUT ] )

Return an array of handles that are ready for reading. TIMEOUT is the maximum amount of time to wait before returning an empty list, in seconds, possibly fractional. If TIMEOUT is not given and any handles are registered then the call will block.

can_write ( [ TIMEOUT ] )

Same as can_read except check for handles that can be written to.

has_exception ( [ TIMEOUT ] )

Same as can_read except check for handles that have an exception condition, for example pending out-of-band data.

count ()

Returns the number of handles that the object will check for when one of the can_ methods is called or the object is passed to the select static method.

bits()

Return the bit string suitable as argument to the core select() call.

select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )

select is a static method, that is you call it with the package name like new. READ, WRITE and EXCEPTION are either undef or IO::Select objects. TIMEOUT is optional and has the same effect as for the core select call.

The result will be an array of 3 elements, each a reference to an array which will hold the handles that are ready for reading, writing and have exceptions respectively. Upon error an empty list is returned.

EXAMPLE

Here is a short example which shows how IO::Select could be used to write a server which communicates with several sockets while also listening for more connections on a listen socket

    use IO::Select;
    use IO::Socket;

    $lsn = new IO::Socket::INET(Listen => 1, LocalPort => 8080);
    $sel = new IO::Select( $lsn );

    while(@ready = $sel->can_read) {
        foreach $fh (@ready) {
            if($fh == $lsn) {
                # Create a new socket
                $new = $lsn->accept;
                $sel->add($new);
            }
            else {
                # Process socket

                # Maybe we have finished with the socket
                $sel->remove($fh);
                $fh->close;
                            }
                        }
                    }

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::Socket - Object interface to socket communications

  • CONSTRUCTOR
  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Socket - Object interface to socket communications

SYNOPSIS

    use IO::Socket;

DESCRIPTION

IO::Socket provides an object interface to creating and using sockets. It is built upon the the IO::Handle manpage interface and inherits all the methods defined by the IO::Handle manpage.

IO::Socket only defines methods for those operations which are common to all types of socket. Operations which are specified to a socket in a particular domain have methods defined in sub classes of IO::Socket

IO::Socket will export all functions (and constants) defined by the Socket manpage.

CONSTRUCTOR

new ( [ARGS] )

Creates an IO::Socket, which is a reference to a newly created symbol (see the Symbol package). new optionally takes arguments, these arguments are in key-value pairs. new only looks for one key Domain which tells new which domain the socket will be in. All other arguments will be passed to the configuration method of the package for that domain, See below.

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

As of VERSION 1.18 all IO::Socket objects have autoflush turned on by default. This was not the case with earlier releases.

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

METHODS

See the perlfunc manpage for complete descriptions of each of the following supported IO::Socket methods, which are just front ends for the corresponding built-in functions:

    socket
    socketpair
    bind
    listen
    accept
    send
    recv
    peername (getpeername)
    sockname (getsockname)
    shutdown

Some methods take slightly different arguments to those defined in the perlfunc manpage in attempt to make the interface more flexible. These are

accept([PKG])

perform the system call accept on the socket and return a new object. The new object will be created in the same class as the listen socket, unless PKG is specified. This object can be used to communicate with the client that was trying to connect.

In a scalar context the new socket is returned, or undef upon failure. In a list context a two-element array is returned containing the new socket and the peer address; the list will be empty upon failure.

The timeout in the [PKG] can be specified as zero to effect a "poll", but you shouldn't do that because a new IO::Select object will be created behind the scenes just to do the single poll. This is horrendously inefficient. Use rather true select() with a zero timeout on the handle, or non-blocking IO.

socketpair(DOMAIN, TYPE, PROTOCOL)

Call socketpair and return a list of two sockets created, or an empty list on failure.

Additional methods that are provided are:

atmark

True if the socket is currently positioned at the urgent data mark, false otherwise.

    use IO::Socket;

    my $sock = IO::Socket::INET->new('some_server');
    $sock->read($data, 1024) until $sock->atmark;

Note: this is a reasonably new addition to the family of socket functions, so all systems may not support this yet. If it is unsupported by the system, an attempt to use this method will abort the program.

The atmark() functionality is also exportable as sockatmark() function:

        use IO::Socket 'sockatmark';

This allows for a more traditional use of sockatmark() as a procedural socket function. If your system does not support sockatmark(), the use declaration will fail at compile time.

connected

If the socket is in a connected state the peer address is returned. If the socket is not in a connected state then undef will be returned.

protocol

Returns the numerical number for the protocol being used on the socket, if known. If the protocol is unknown, as with an AF_UNIX socket, zero is returned.

sockdomain

Returns the numerical number for the socket domain type. For example, for an AF_INET socket the value of &AF_INET will be returned.

sockopt(OPT [, VAL])

Unified method to both set and get options in the SOL_SOCKET level. If called with one argument then getsockopt is called, otherwise setsockopt is called.

socktype

Returns the numerical number for the socket type. For example, for a SOCK_STREAM socket the value of &SOCK_STREAM will be returned.

timeout([VAL])

Set or get the timeout value associated with this socket. If called without any arguments then the current setting is returned. If called with an argument the current setting is changed and the previous value returned.

SEE ALSO

the Socket manpage, the IO::Handle manpage, the IO::Socket::INET manpage, the IO::Socket::UNIX manpage

AUTHOR

Graham Barr. atmark() by Lincoln Stein. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The atmark() implementation: Copyright 2001, Lincoln Stein <lstein@cshl.org>. This module is distributed under the same terms as Perl itself. Feel free to use, modify and redistribute it as long as you retain the correct attribution.


IO::Socket::INET - Object interface for AF_INET domain sockets

  • CONSTRUCTOR
    • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Socket::INET - Object interface for AF_INET domain sockets

SYNOPSIS

    use IO::Socket::INET;

DESCRIPTION

IO::Socket::INET provides an object interface to creating and using sockets in the AF_INET domain. It is built upon the the IO::Socket manpage interface and inherits all the methods defined by the IO::Socket manpage.

CONSTRUCTOR

new ( [ARGS] )

Creates an IO::Socket::INET object, which is a reference to a newly created symbol (see the Symbol package). new optionally takes arguments, these arguments are in key-value pairs.

In addition to the key-value pairs accepted by the IO::Socket manpage, IO::Socket::INET provides.

    PeerAddr    Remote host address          <hostname>[:<port>]
    PeerHost    Synonym for PeerAddr
    PeerPort    Remote port or service       <service>[(<no>)] | <no>
    LocalAddr   Local host bind address      hostname[:port]
    LocalHost   Synonym for LocalAddr
    LocalPort   Local host bind port         <service>[(<no>)] | <no>
    Proto       Protocol name (or number)    "tcp" | "udp" | ...
    Type        Socket type                  SOCK_STREAM | SOCK_DGRAM | ...
    Listen      Queue size for listen
    ReuseAddr   Set SO_REUSEADDR before binding
    Reuse       Set SO_REUSEADDR before binding (deprecated, prefer ReuseAddr)
    ReusePort   Set SO_REUSEPORT before binding
    Broadcast   Set SO_BROADCAST before binding
    Timeout     Timeout value for various operations
    MultiHomed  Try all addresses for multi-homed hosts
    Blocking    Determine if connection will be blocking mode

If Listen is defined then a listen socket is created, else if the socket type, which is derived from the protocol, is SOCK_STREAM then connect() is called.

Although it is not illegal, the use of MultiHomed on a socket which is in non-blocking mode is of little use. This is because the first connect will never fail with a timeout as the connect call will not block.

The PeerAddr can be a hostname or the IP-address on the "xx.xx.xx.xx" form. The PeerPort can be a number or a symbolic service name. The service name might be followed by a number in parenthesis which is used if the service is not known by the system. The PeerPort specification can also be embedded in the PeerAddr by preceding it with a ":".

If Proto is not given and you specify a symbolic PeerPort port, then the constructor will try to derive Proto from the service name. As a last resort Proto "tcp" is assumed. The Type parameter will be deduced from Proto if not specified.

If the constructor is only passed a single argument, it is assumed to be a PeerAddr specification.

If Blocking is set to 0, the connection will be in nonblocking mode. If not specified it defaults to 1 (blocking mode).

Examples:

   $sock = IO::Socket::INET->new(PeerAddr => 'www.perl.org',
                                 PeerPort => 'http(80)',
                                 Proto    => 'tcp');

   $sock = IO::Socket::INET->new(PeerAddr => 'localhost:smtp(25)');

   $sock = IO::Socket::INET->new(Listen    => 5,
                                 LocalAddr => 'localhost',
                                 LocalPort => 9000,
                                 Proto     => 'tcp');

   $sock = IO::Socket::INET->new('127.0.0.1:25');

   $sock = IO::Socket::INET->new(PeerPort  => 9999,
                                 PeerAddr  => inet_ntoa(INADDR_BROADCAST),
                                 Proto     => udp,
                                 LocalAddr => 'localhost',
                                 Broadcast => 1 )
                             or die "Can't bind : $@\n";

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

As of VERSION 1.18 all IO::Socket objects have autoflush turned on by default. This was not the case with earlier releases.

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

METHODS

sockaddr ()

Return the address part of the sockaddr structure for the socket

sockport ()

Return the port number that the socket is using on the local host

sockhost ()

Return the address part of the sockaddr structure for the socket in a text form xx.xx.xx.xx

peeraddr ()

Return the address part of the sockaddr structure for the socket on the peer host

peerport ()

Return the port number for the socket on the peer host.

peerhost ()

Return the address part of the sockaddr structure for the socket on the peer host in a text form xx.xx.xx.xx

SEE ALSO

the Socket manpage, the IO::Socket manpage

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::Socket::UNIX - Object interface for AF_UNIX domain sockets

  • CONSTRUCTOR
  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

IO::Socket::UNIX - Object interface for AF_UNIX domain sockets

SYNOPSIS

    use IO::Socket::UNIX;

DESCRIPTION

IO::Socket::UNIX provides an object interface to creating and using sockets in the AF_UNIX domain. It is built upon the the IO::Socket manpage interface and inherits all the methods defined by the IO::Socket manpage.

CONSTRUCTOR

new ( [ARGS] )

Creates an IO::Socket::UNIX object, which is a reference to a newly created symbol (see the Symbol package). new optionally takes arguments, these arguments are in key-value pairs.

In addition to the key-value pairs accepted by the IO::Socket manpage, IO::Socket::UNIX provides.

    Type        Type of socket (eg SOCK_STREAM or SOCK_DGRAM)
    Local       Path to local fifo
    Peer        Path to peer fifo
    Listen      Create a listen socket

If the constructor is only passed a single argument, it is assumed to be a Peer specification.

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

As of VERSION 1.18 all IO::Socket objects have autoflush turned on by default. This was not the case with earlier releases.

 NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE

METHODS

hostpath()

Returns the pathname to the fifo at the local end

peerpath()

Returns the pathanme to the fifo at the peer end

SEE ALSO

the Socket manpage, the IO::Socket manpage

AUTHOR

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs to <perl5-porters@perl.org>.

COPYRIGHT

Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::String - Emulate file interface for in-core strings

  • BUGS
  • SEE ALSO
  • COPYRIGHT

NAME

IO::String - Emulate file interface for in-core strings

SYNOPSIS

 use IO::String;
 $io = IO::String->new;
 $io = IO::String->new($var);
 tie *IO, 'IO::String';

 # read data
 <$io>;
 $io->getline;
 read($io, $buf, 100);

 # write data
 print $io "string\n";
 $io->print(@data);
 syswrite($io, $buf, 100);

 select $io;
 printf "Some text %s\n", $str;

 # seek
 $pos = $io->getpos;
 $io->setpos(0);        # rewind
 $io->seek(-30, -1);
 seek($io, 0, 0);

DESCRIPTION

The IO::String module provides the IO::File interface for in-core strings. An IO::String object can be attached to a string, and makes it possible to use the normal file operations for reading or writing data, as well as for seeking to various locations of the string. This is useful when you want to use a library module that only provides an interface to file handles on data that you have in a string variable.

Note that perl-5.8 and better has built-in support for "in memory" files, which are set up by passing a reference instead of a filename to the open() call. The reason for using this module is that it makes the code backwards compatible with older versions of Perl.

The IO::String module provides an interface compatible with IO::File as distributed with IO-1.20, but the following methods are not available: new_from_fd, fdopen, format_write, format_page_number, format_lines_per_page, format_lines_left, format_name, format_top_name.

The following methods are specific to the IO::String class:

$io = IO::String->new
$io = IO::String->new( $string )

The constructor returns a newly-created IO::String object. It takes an optional argument, which is the string to read from or write into. If no $string argument is given, then an internal buffer (initially empty) is allocated.

The IO::String object returned is tied to itself. This means that you can use most Perl I/O built-ins on it too: readline, <>, getc, print, printf, syswrite, sysread, close.

$io->open
$io->open( $string )

Attaches an existing IO::String object to some other $string, or allocates a new internal buffer (if no argument is given). The position is reset to 0.

$io->string_ref

Returns a reference to the string that is attached to the IO::String object. Most useful when you let the IO::String create an internal buffer to write into.

$io->pad
$io->pad( $char )

Specifies the padding to use if the string is extended by either the seek() or truncate() methods. It is a single character and defaults to "\0".

$io->pos
$io->pos( $newpos )

Yet another interface for reading and setting the current read/write position within the string (the normal getpos/setpos/tell/seek methods are also available). The pos() method always returns the old position, and if you pass it an argument it sets the new position.

There is (deliberately) a difference between the setpos() and seek() methods in that seek() extends the string (with the specified padding) if you go to a location past the end, whereas setpos() just snaps back to the end. If truncate() is used to extend the string, then it works as seek().

BUGS

In Perl versions < 5.6, the TIEHANDLE interface was incomplete. If you use such a Perl, then seek(), tell(), eof(), fileno(), binmode() will not do anything on an IO::String handle. See the perltie manpage for details.

SEE ALSO

the IO::File manpage, the IO::Stringy manpage, open in the perlfunc manpage

COPYRIGHT

Copyright 1998-2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


IO::Zlib - IO:: style interface to L<Compress::Zlib>

  • CONSTRUCTOR
  • OBJECT METHODS
  • USING THE EXTERNAL GZIP
  • CLASS METHODS
  • DIAGNOSTICS
  • SEE ALSO
  • HISTORY
  • COPYRIGHT

NAME

IO::Zlib - IO:: style interface to the Compress::Zlib manpage

SYNOPSIS

With any version of Perl 5 you can use the basic OO interface:

    use IO::Zlib;

    $fh = new IO::Zlib;
    if ($fh->open("file.gz", "rb")) {
        print <$fh>;
        $fh->close;
    }

    $fh = IO::Zlib->new("file.gz", "wb9");
    if (defined $fh) {
        print $fh "bar\n";
        $fh->close;
    }

    $fh = IO::Zlib->new("file.gz", "rb");
    if (defined $fh) {
        print <$fh>;
        undef $fh;       # automatically closes the file
    }

With Perl 5.004 you can also use the TIEHANDLE interface to access compressed files just like ordinary files:

    use IO::Zlib;

    tie *FILE, 'IO::Zlib', "file.gz", "wb";
    print FILE "line 1\nline2\n";

    tie *FILE, 'IO::Zlib', "file.gz", "rb";
    while (<FILE>) { print "LINE: ", $_ };

DESCRIPTION

IO::Zlib provides an IO:: style interface to the Compress::Zlib manpage and hence to gzip/zlib compressed files. It provides many of the same methods as the the IO::Handle manpage interface.

Starting from IO::Zlib version 1.02, IO::Zlib can also use an external gzip command. The default behaviour is to try to use an external gzip if no Compress::Zlib can be loaded, unless explicitly disabled by

    use IO::Zlib qw(:gzip_external 0);

If explicitly enabled by

    use IO::Zlib qw(:gzip_external 1);

then the external gzip is used instead of Compress::Zlib.

CONSTRUCTOR

new ( [ARGS] )

Creates an IO::Zlib object. If it receives any parameters, they are passed to the method open; if the open fails, the object is destroyed. Otherwise, it is returned to the caller.

OBJECT METHODS

open ( FILENAME, MODE )

open takes two arguments. The first is the name of the file to open and the second is the open mode. The mode can be anything acceptable to the Compress::Zlib manpage and by extension anything acceptable to zlib (that basically means POSIX fopen() style mode strings plus an optional number to indicate the compression level).

opened

Returns true if the object currently refers to a opened file.

close

Close the file associated with the object and disassociate the file from the handle. Done automatically on destroy.

getc

Return the next character from the file, or undef if none remain.

getline

Return the next line from the file, or undef on end of string. Can safely be called in an array context. Currently ignores $/ ($INPUT_RECORD_SEPARATOR or $RS when the English manpage is in use) and treats lines as delimited by "\n".

getlines

Get all remaining lines from the file. It will croak() if accidentally called in a scalar context.

print ( ARGS... )

Print ARGS to the file.

read ( BUF, NBYTES, [OFFSET] )

Read some bytes from the file. Returns the number of bytes actually read, 0 on end-of-file, undef on error.

eof

Returns true if the handle is currently positioned at end of file?

seek ( OFFSET, WHENCE )

Seek to a given position in the stream. Not yet supported.

tell

Return the current position in the stream, as a numeric offset. Not yet supported.

setpos ( POS )

Set the current position, using the opaque value returned by getpos(). Not yet supported.

getpos ( POS )

Return the current position in the string, as an opaque object. Not yet supported.

USING THE EXTERNAL GZIP

If the external gzip is used, the following opens are used:

    open(FH, "gzip -dc $filename |")  # for read opens
    open(FH, " | gzip > $filename")   # for write opens

You can modify the 'commands' for example to hardwire an absolute path by e.g.

    use IO::Zlib ':gzip_read_open'  => '/some/where/gunzip -c %s |';
    use IO::Zlib ':gzip_write_open' => '| /some/where/gzip.exe > %s';

The %s is expanded to be the filename (sprintf is used, so be careful to escape any other % signs). The 'commands' are checked for sanity - they must contain the %s, and the read open must end with the pipe sign, and the write open must begin with the pipe sign.

CLASS METHODS

has_Compress_Zlib

Returns true if Compress::Zlib is available. Note that this does not mean that Compress::Zlib is being used: see gzip_external and gzip_used.

gzip_external

Undef if an external gzip can be used if Compress::Zlib is not available (see has_Compress_Zlib), true if an external gzip is explicitly used, false if an external gzip must not be used. See gzip_used.

gzip_used

True if an external gzip is being used, false if not.

gzip_read_open

Return the 'command' being used for opening a file for reading using an external gzip.

gzip_write_open

Return the 'command' being used for opening a file for writing using an external gzip.

DIAGNOSTICS

IO::Zlib::getlines: must be called in list context

If you want read lines, you must read in list context.

IO::Zlib::gzopen_external: mode '...' is illegal

Use only modes 'rb' or 'wb' or /wb[1-9]/.

IO::Zlib::import: '...' is illegal

The known import symbols are the :gzip_external, :gzip_read_open, and :gzip_write_open. Anything else is not recognized.

IO::Zlib::import: ':gzip_external' requires an argument

The :gzip_external requires one boolean argument.

IO::Zlib::import: 'gzip_read_open' requires an argument

The :gzip_external requires one string argument.

IO::Zlib::import: 'gzip_read' '...' is illegal

The :gzip_read_open argument must end with the pipe sign (|) and have the %s for the filename. See USING THE EXTERNAL GZIP.

IO::Zlib::import: 'gzip_write_open' requires an argument

The :gzip_external requires one string argument.

IO::Zlib::import: 'gzip_write_open' '...' is illegal

The :gzip_write_open argument must begin with the pipe sign (|) and have the %s for the filename. An output redirect (>) is also often a good idea, depending on your operating system shell syntax. See USING THE EXTERNAL GZIP.

IO::Zlib::import: no Compress::Zlib and no external gzip

Given that we failed to load Compress::Zlib and that the use of an external gzip was disabled, IO::Zlib has not much chance of working.

IO::Zlib::open: needs a filename

No filename, no open.

IO::Zlib::READ: NBYTES must be specified

We must know how much to read.

IO::Zlib::READ: OFFSET is not supported

Offsets of gzipped streams are not supported.

IO::Zlib::WRITE: too long LENGTH

The LENGTH must be less than or equal to the buffer size.

IO::Zlib::WRITE: OFFSET is not supported

Offsets of gzipped streams are not supported.

SEE ALSO

the perlfunc manpage, I/O Operators in the perlop manpage, the IO::Handle manpage, the Compress::Zlib manpage

HISTORY

Created by Tom Hughes <tom@compton.nu>.

Support for external gzip added by Jarkko Hietaniemi <jhi@iki.fi>.

COPYRIGHT

Copyright (c) 1998-2004 Tom Hughes <tom@compton.nu>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


open2 - open a process for both reading and writing

  • WARNING
  • SEE ALSO

NAME

IPC::Open2, open2 - open a process for both reading and writing

SYNOPSIS

    use IPC::Open2;

    $pid = open2(\*CHLD_OUT, \*CHLD_IN, 'some cmd and args');
      # or without using the shell
    $pid = open2(\*CHLD_OUT, \*CHLD_IN, 'some', 'cmd', 'and', 'args');

    # or with handle autovivification
    my($chld_out, $chld_in);
    $pid = open2($chld_out, $chld_in, 'some cmd and args');
      # or without using the shell
    $pid = open2($chld_out, $chld_in, 'some', 'cmd', 'and', 'args');

DESCRIPTION

The open2() function runs the given $cmd and connects $chld_out for reading and $chld_in for writing. It's what you think should work when you try

    $pid = open(HANDLE, "|cmd args|");

The write filehandle will have autoflush turned on.

If $chld_out is a string (that is, a bareword filehandle rather than a glob or a reference) and it begins with >&, then the child will send output directly to that file handle. If $chld_in is a string that begins with <&, then $chld_in will be closed in the parent, and the child will read from it directly. In both cases, there will be a dup(2) instead of a pipe(2) made.

If either reader or writer is the null string, this will be replaced by an autogenerated filehandle. If so, you must pass a valid lvalue in the parameter slot so it can be overwritten in the caller, or an exception will be raised.

open2() returns the process ID of the child process. It doesn't return on failure: it just raises an exception matching /^open2:/. However, exec failures in the child are not detected. You'll have to trap SIGPIPE yourself.

open2() does not wait for and reap the child process after it exits. Except for short programs where it's acceptable to let the operating system take care of this, you need to do this yourself. This is normally as simple as calling waitpid $pid, 0 when you're done with the process. Failing to do this can result in an accumulation of defunct or "zombie" processes. See waitpid in the perlfunc manpage for more information.

This whole affair is quite dangerous, as you may block forever. It assumes it's going to talk to something like bc, both writing to it and reading from it. This is presumably safe because you "know" that commands like bc will read a line at a time and output a line at a time. Programs like sort that read their entire input stream first, however, are quite apt to cause deadlock.

The big problem with this approach is that if you don't have control over source code being run in the child process, you can't control what it does with pipe buffering. Thus you can't just open a pipe to cat -v and continually read and write a line from it.

The IO::Pty and Expect modules from CPAN can help with this, as they provide a real tty (well, a pseudo-tty, actually), which gets you back to line buffering in the invoked command again.

WARNING

The order of arguments differs from that of open3().

SEE ALSO

See the IPC::Open3 manpage for an alternative that handles STDERR as well. This function is really just a wrapper around open3().


open3 - open a process for reading, writing, and error handling

  • WARNING

NAME

IPC::Open3, open3 - open a process for reading, writing, and error handling

SYNOPSIS

    $pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
                    'some cmd and args', 'optarg', ...);

    my($wtr, $rdr, $err);
    $pid = open3($wtr, $rdr, $err,
                    'some cmd and args', 'optarg', ...);

DESCRIPTION

Extremely similar to open2(), open3() spawns the given $cmd and connects CHLD_OUT for reading from the child, CHLD_IN for writing to the child, and CHLD_ERR for errors. If CHLD_ERR is false, or the same file descriptor as CHLD_OUT, then STDOUT and STDERR of the child are on the same filehandle. The CHLD_IN will have autoflush turned on.

If CHLD_IN begins with <&, then CHLD_IN will be closed in the parent, and the child will read from it directly. If CHLD_OUT or CHLD_ERR begins with >&, then the child will send output directly to that filehandle. In both cases, there will be a dup(2) instead of a pipe(2) made.

If either reader or writer is the null string, this will be replaced by an autogenerated filehandle. If so, you must pass a valid lvalue in the parameter slot so it can be overwritten in the caller, or an exception will be raised.

The filehandles may also be integers, in which case they are understood as file descriptors.

open3() returns the process ID of the child process. It doesn't return on failure: it just raises an exception matching /^open3:/. However, exec failures in the child are not detected. You'll have to trap SIGPIPE yourself.

Note if you specify - as the command, in an analogous fashion to open(FOO, "-|") the child process will just be the forked Perl process rather than an external command. This feature isn't yet supported on Win32 platforms.

open3() does not wait for and reap the child process after it exits. Except for short programs where it's acceptable to let the operating system take care of this, you need to do this yourself. This is normally as simple as calling waitpid $pid, 0 when you're done with the process. Failing to do this can result in an accumulation of defunct or "zombie" processes. See waitpid in the perlfunc manpage for more information.

If you try to read from the child's stdout writer and their stderr writer, you'll have problems with blocking, which means you'll want to use select() or the IO::Select, which means you'd best use sysread() instead of readline() for normal stuff.

This is very dangerous, as you may block forever. It assumes it's going to talk to something like bc, both writing to it and reading from it. This is presumably safe because you "know" that commands like bc will read a line at a time and output a line at a time. Programs like sort that read their entire input stream first, however, are quite apt to cause deadlock.

The big problem with this approach is that if you don't have control over source code being run in the child process, you can't control what it does with pipe buffering. Thus you can't just open a pipe to cat -v and continually read and write a line from it.

WARNING

The order of arguments differs from that of open2().


Image::Magick - Perl extension for calling ImageMagick's libMagick methods

  • AUTHOR
  • BUGS
  • SEE ALSO

NAME

Image::Magick - Perl extension for calling ImageMagick's libMagick methods

SYNOPSIS

  use Image::Magick;
  $p = new Image::Magick;
  $p->Read("imagefile");
  $p->Set(attribute => value, ...)
  ($a, ...) = $p->Get("attribute", ...)
  $p->routine(parameter => value, ...)
  $p->Mogrify("Routine", parameter => value, ...)
  $p->Write("filename");

DESCRIPTION

This Perl extension allows the reading, manipulation and writing of a large number of image file formats using the ImageMagick library. It was originally developed to be used by CGI scripts for Web pages.

A Web page has been set up for this extension. See:

         file:///usr/local/share/doc/ImageMagick-6.3.1/www/perl-magick.html
         http://www.imagemagick.org/script/perl-magick.php

AUTHOR

Kyle Shorter magick-users@imagemagick.org

BUGS

Has all the bugs of ImageMagick and much, much more!

SEE ALSO

perl(1).


Inline - Write Perl subroutines in other programming languages.

    • Why Inline?
  • Using the Inline.pm Module
    • The Basics
    • More about the DATA Section
    • Configuration Options
    • On and Off
    • Playing 'with' Others
    • Inline Shortcuts
    • The Inline DIRECTORY
    • Debugging Inline Errors
    • The 'config' Registry File
  • Configuration Options
    • DIRECTORY
    • NAME
    • AUTONAME
    • VERSION
    • WITH
    • GLOBAL_LOAD
    • UNTAINT
    • SAFEMODE
    • FORCE_BUILD
    • BUILD_NOISY
    • BUILD_TIMERS
    • CLEAN_AFTER_BUILD
    • CLEAN_BUILD_AREA
    • PRINT_INFO
    • PRINT_VERSION
    • REPORTBUG
    • WARNINGS
  • Inline Configuration Shortcuts
  • Writing Modules with Inline
  • How Inline Works
  • SEE ALSO
  • BUGS AND DEFICIENCIES
  • AUTHOR
  • COPYRIGHT

NAME

Inline - Write Perl subroutines in other programming languages.

SYNOPSIS

    use Inline C;

    print "9 + 16 = ", add(9, 16), "\n";
    print "9 - 16 = ", subtract(9, 16), "\n";

    __END__
    __C__
    int add(int x, int y) {
      return x + y;
    }

    int subtract(int x, int y) {
      return x - y;
    }

DESCRIPTION

The Inline module allows you to put source code from other programming languages directly "inline" in a Perl script or module. The code is automatically compiled as needed, and then loaded for immediate access from Perl.

Inline saves you from the hassle of having to write and compile your own glue code using facilities like XS or SWIG. Simply type the code where you want it and run your Perl as normal. All the hairy details are handled for you. The compilation and installation of your code chunks all happen transparently; all you will notice is the delay of compilation on the first run.

The Inline code only gets compiled the first time you run it (or whenever it is modified) so you only take the performance hit once. Code that is Inlined into distributed modules (like on the CPAN) will get compiled when the module is installed, so the end user will never notice the compilation time.

Best of all, it works the same on both Unix and Microsoft Windows. See the Inline-Support manpage for support information.

Why Inline?

Do you want to know "Why would I use other languages in Perl?" or "Why should I use Inline to do it?"? I'll try to answer both.

Why would I use other languages in Perl?

The most obvious reason is performance. For an interpreted language, Perl is very fast. Many people will say "Anything Perl can do, C can do faster". (They never mention the development time :-) Anyway, you may be able to remove a bottleneck in your Perl code by using another language, without having to write the entire program in that language. This keeps your overall development time down, because you're using Perl for all of the non-critical code.

Another reason is to access functionality from existing API-s that use the language. Some of this code may only be available in binary form. But by creating small subroutines in the native language, you can "glue" existing libraries to your Perl. As a user of the CPAN, you know that code reuse is a good thing. So why throw away those Fortran libraries just yet?

If you are using Inline with the C language, then you can access the full internals of Perl itself. This opens up the floodgates to both extreme power and peril.

Maybe the best reason is "Because you want to!". Diversity keeps the world interesting. TMTOWTDI!

Why should I use Inline to do it?

There are already two major facilities for extending Perl with C. They are XS and SWIG. Both are similar in their capabilities, at least as far as Perl is concerned. And both of them are quite difficult to learn compared to Inline.

There is a big fat learning curve involved with setting up and using the XS environment. You need to get quite intimate with the following docs:

 * perlxs
 * perlxstut
 * perlapi
 * perlguts
 * perlmod
 * h2xs
 * xsubpp
 * ExtUtils::MakeMaker

With Inline you can be up and running in minutes. There is a C Cookbook with lots of short but complete programs that you can extend to your real-life problems. No need to learn about the complicated build process going on in the background. You don't even need to compile the code yourself. Inline takes care of every last detail except writing the C code.

Perl programmers cannot be bothered with silly things like compiling. "Tweak, Run, Tweak, Run" is our way of life. Inline does all the dirty work for you.

Another advantage of Inline is that you can use it directly in a script. You can even use it in a Perl one-liner. With XS and SWIG, you always set up an entirely separate module. Even if you only have one or two functions. Inline makes easy things easy, and hard things possible. Just like Perl.

Finally, Inline supports several programming languages (not just C and C++). As of this writing, Inline has support for C, C++, Java, Python, Ruby, Tcl, Assembler, Basic, Guile, Befunge, Octave, Awk, BC, TT (Template Toolkit), WebChat and even PERL. New Inline Language Support Modules (ILSMs) are regularly being added. See the Inline-API manpage for details on how to create your own ILSM.

Using the Inline.pm Module

Inline is a little bit different than most of the Perl modules that you are used to. It doesn't import any functions into your namespace and it doesn't have any object oriented methods. Its entire interface (with two minor exceptions) is specified through the 'use Inline ...' command.

This section will explain all of the different ways to use Inline. If you want to begin using C with Inline immediately, see the Inline::C-Cookbook manpage.

The Basics

The most basic form for using Inline is:

    use Inline X => "X source code";

where 'X' is one of the supported Inline programming languages. The second parameter identifies the source code that you want to bind to Perl. The source code can be specified using any of the following syntaxes:

The DATA Keyword.
    use Inline Java => 'DATA';

    # Perl code goes here ...

    __DATA__
    __Java__
    /* Java code goes here ... */

The easiest and most visually clean way to specify your source code in an Inline Perl program is to use the special DATA keyword. This tells Inline to look for a special marker in your DATA filehandle's input stream. In this example the special marker is __Java__, which is the programming language surrounded by double underscores.

In case you've forgotten, the DATA pseudo file is comprised of all the text after the __END__ or __DATA__ section of your program. If you're working outside the main package, you'd best use the __DATA__ marker or else Inline will not find your code.

Using this scheme keeps your Perl code at the top, and all the ugly Java stuff down below where it belongs. This is visually clean and makes for more maintainable code. An excellent side benefit is that you don't have to escape any characters like you might in a Perl string. The source code is verbatim. For these reasons, I prefer this method the most.

The only problem with this style is that since Perl can't read the DATA filehandle until runtime, it obviously can't bind your functions until runtime. The net effect of this is that you can't use your Inline functions as barewords (without predeclaring them) because Perl has no idea they exist during compile time.

The FILE and BELOW keywords.
    use Inline::Files;
    use Inline Java => 'FILE';

    # Perl code goes here ...

    __JAVA__
    /* Java code goes here ... */

This is the newest method of specifying your source code. It makes use of the Perl module Inline::Files written by Damian Conway. The basic style and meaning are the same as for the DATA keyword, but there are a few syntactic and semantic twists.

First, you must say 'use Inline::Files' before you 'use Inline' code that needs those files. The special 'DATA' keyword is replaced by either 'FILE' or 'BELOW'. This allows for the bad pun idiom of:

    use Inline C => 'BELOW';

You can omit the __DATA__ tag now. Inline::Files is a source filter that will remove these sections from your program before Perl compiles it. They are then available for Inline to make use of. And since this can all be done at compile time, you don't have to worry about the caveats of the 'DATA' keyword.

This module has a couple small gotchas. Since Inline::Files only recognizes file markers with capital letters, you must specify the capital form of your language name. Also, there is a startup time penalty for using a source code filter.

At this point Inline::Files is alpha software and use of it is experimental. Inline's integration of this module is also fledgling at the time being. One of things I plan to do with Inline::Files is to get line number info so when an extension doesn't compile, the error messages will point to the correct source file and line number.

My best advice is to use Inline::Files for testing (especially as support for it improves), but use DATA for production and distributed/CPAN code.

Strings
    use Inline Java => <<'END';

    /* Java code goes here ... */
    END

    # Perl code goes here ...

You also just specify the source code as a single string. A handy way to write the string is to use Perl's "here document" style of quoting. This is ok for small functions but can get unwieldy in the large. On the other hand, the string variant probably has the least startup penalty and all functions are bound at compile time.

If you wish to put the string into a scalar variable, please be aware that the use statement is a compile time directive. As such, all the variables it uses must also be set at compile time, before the 'use Inline' statement. Here is one way to do it:

    my $code;
    BEGIN {
        $code = <<END;

    /* Java code goes here ... */
    END
    }
    use Inline Java => $code;

    # Perl code goes here ...
The bind() Function

An alternative to using the BEGIN block method is to specify the source code at run time using the 'Inline->bind()' method. (This is one of the interface exceptions mentioned above) The bind() method takes the same arguments as 'use Inline ...'.

    my $code = <<END;

    /* Java code goes here ... */
    END

    Inline->bind(Java => $code);

You can think of bind() as a way to eval() code in other programming languages.

Although bind() is a powerful feature, it is not recommended for use in Inline based modules. In fact, it won't work at all for installable modules. See instructions below for creating modules with Inline.

Other Methods

The source code for Inline can also be specified as an external filename, a reference to a subroutine that returns source code, or a reference to an array that contains lines of source code. These methods are less frequently used but may be useful in some situations.

Shorthand

If you are using the 'DATA' or 'FILE' methods described above and there are no extra parameters, you can omit the keyword altogether. For example:

    use Inline 'Java';

    # Perl code goes here ...

    __DATA__
    __Java__
    /* Java code goes here ... */

or

    use Inline::Files;
    use Inline 'Java';

    # Perl code goes here ...

    __JAVA__
    /* Java code goes here ... */

More about the DATA Section

If you are writing a module, you can also use the DATA section for POD and AutoLoader subroutines. Just be sure to put them before the first Inline marker. If you install the helper module Inline::Filters, you can even use POD inside your Inline code. You just have to specify a filter to strip it out.

You can also specify multiple Inline sections, possibly in different programming languages. Here is another example:

    # The module Foo.pm
    package Foo;
    use AutoLoader;

    use Inline C;
    use Inline C => DATA => FILTERS => 'Strip_POD';
    use Inline Python;

    1;

    __DATA__

    sub marine {
        # This is an autoloaded subroutine
    }

    =head1 External subroutines

    =cut

    __C__
    /* First C section */

    __C__
    /* Second C section */
    =head1 My C Function

    Some POD doc.

    =cut

    __Python__
    """A Python Section"""

An important thing to remember is that you need to have one "use Inline Foo => 'DATA'" for each "__Foo__" marker, and they must be in the same order. This allows you to apply different configuration options to each section.

Configuration Options

Inline trys to do the right thing as often as possible. But sometimes you may need to override the default actions. This is easy to do. Simply list the Inline configuration options after the regular Inline parameters. All congiguration options are specified as (key, value) pairs.

    use Inline (C => 'DATA',
                DIRECTORY => './inline_dir',
                LIBS => '-lfoo',
                INC => '-I/foo/include',
                PREFIX => 'XXX_',
                WARNINGS => 0,
               );

You can also specify the configuration options on a separate Inline call like this:

    use Inline (C => Config =>
                DIRECTORY => './inline_dir',
                LIBS => '-lfoo',
                INC => '-I/foo/include',
                PREFIX => 'XXX_',
                WARNINGS => 0,
               );
    use Inline C => <<'END_OF_C_CODE';

The special keyword 'Config' tells Inline that this is a configuration-only call. No source code will be compiled or bound to Perl.

If you want to specify global configuration options that don't apply to a particular language, just leave the language out of the call. Like this:

    use Inline Config => WARNINGS => 0;

The Config options are inherited and additive. You can use as many Config calls as you want. And you can apply different options to different code sections. When a source code section is passed in, Inline will apply whichever options have been specified up to that point. Here is a complex configuration example:

    use Inline (Config =>
                DIRECTORY => './inline_dir',
               );
    use Inline (C => Config =>
                LIBS => '-lglobal',
               );
    use Inline (C => 'DATA',         # First C Section
                LIBS => ['-llocal1', '-llocal2'],
               );
    use Inline (Config =>
                WARNINGS => 0,
               );
    use Inline (Python => 'DATA',    # First Python Section
                LIBS => '-lmypython1',
               );
    use Inline (C => 'DATA',         # Second C Section
                LIBS => [undef, '-llocal3'],
               );

The first Config applies to all subsequent calls. The second Config applies to all subsequent C sections (but not Python sections). In the first C section, the external libraries global, local1 and local2 are used. (Most options allow either string or array ref forms, and do the right thing.) The Python section does not use the global library, but does use the same DIRECTORY, and has warnings turned off. The second C section only uses the local3 library. That's because a value of undef resets the additive behavior.

The DIRECTORY and WARNINGS options are generic Inline options. All other options are language specific. To find out what the C options do, see Inline::C.

On and Off

If a particular config option has value options of 1 and 0, you can use the ENABLE and DISABLE modifiers. In other words, this:

    use Inline Config =>
               FORCE_BUILD => 1,
               CLEAN_AFTER_BUILD => 0;

could be reworded as:

    use Inline Config =>
               ENABLE => FORCE_BUILD,
               DISABLE => CLEAN_AFTER_BUILD;

Playing 'with' Others

Inline has a special configuration syntax that tells it to get more configuration options from other Perl modules. Here is an example:

    use Inline with => 'Event';

This tells Inline to load the module Event.pm and ask it for configuration information. Since Event has a C API of its own, it can pass Inline all of the information it needs to be able to use Event C callbacks seamlessly.

That means that you don't need to specify the typemaps, shared libraries, include files and other information required to get this to work.

You can specify a single module or a list of them. Like:

    use Inline with => qw(Event Foo Bar);

Currently, Event is the only module that works with Inline.

Inline Shortcuts

Inline lets you set many configuration options from the command line. These options are called 'shortcuts'. They can be very handy, especially when you only want to set the options temporarily, for say, debugging.

For instance, to get some general information about your Inline code in the script Foo.pl, use the command:

    perl -MInline=INFO Foo.pl

If you want to force your code to compile, even if its already done, use:

    perl -MInline=FORCE Foo.pl

If you want to do both, use:

    perl -MInline=INFO -MInline=FORCE Foo.pl

or better yet:

    perl -MInline=INFO,FORCE Foo.pl

The Inline DIRECTORY

Inline needs a place to build your code and to install the results of the build. It uses a single directory named '.Inline/' under normal circumstances. If you create this directory in your home directory, the current directory or in the directory where your program resides, Inline will find and use it. You can also specify it in the environment variable PERL_INLINE_DIRECTORY or directly in your program, by using the DIRECTORY keyword option. If Inline cannot find the directory in any of these places it will create a '_Inline/' directory in either your current directory or the directory where your script resides.

One of the key factors to using Inline successfully, is understanding this directory. When developing code it is usually best to create this directory (or let Inline do it) in your current directory. Remember that there is nothing sacred about this directory except that it holds your compiled code. Feel free to delete it at any time. Inline will simply start from scratch and recompile your code on the next run. If you have several programs that you want to force to recompile, just delete your '.Inline/' directory.

It is probably best to have a separate '.Inline/' directory for each project that you are working on. You may want to keep stable code in the <.Inline/> in your home directory. On multi-user systems, each user should have their own '.Inline/' directories. It could be a security risk to put the directory in a shared place like /tmp/.

Debugging Inline Errors

All programmers make mistakes. When you make a mistake with Inline, like writing bad C code, you'll get a big error report on your screen. This report tells you where to look to do the debugging. Some languages may also dump out the error messages generated from the build.

When Inline needs to build something it creates a subdirectory under your DIRECTORY/build/ directory. This is where it writes all the components it needs to build your extension. Things like XS files, Makefiles and output log files.

If everything goes OK, Inline will delete this subdirectory. If there is an error, Inline will leave the directory intact and print its location. The idea is that you are supposed to go into that directory and figure out what happened.

Read the doc for your particular Inline Language Support Module for more information.

The 'config' Registry File

Inline keeps a cached file of all of the Inline Language Support Module's meta data in a file called config. This file can be found in your DIRECTORY directory. If the file does not exist, Inline creates a new one. It will search your system for any module beginning with Inline::. It will then call that module's register() method to get useful information for future invocations.

Whenever you add a new ILSM, you should delete this file so that Inline will auto-discover your newly installed language module.

Configuration Options

This section lists all of the generic Inline configuration options. For language specific configuration, see the doc for that language.

DIRECTORY

The DIRECTORY config option is the directory that Inline uses to both build and install an extension.

Normally Inline will search in a bunch of known places for a directory called '.Inline/'. Failing that, it will create a directory called '_Inline/'

If you want to specify your own directory, use this configuration option.

Note that you must create the DIRECTORY directory yourself. Inline will not do it for you.

NAME

You can use this option to set the name of your Inline extension object module. For example:

    use Inline C => 'DATA',
               NAME => 'Foo::Bar';

would cause your C code to be compiled in to the object:

    lib/auto/Foo/Bar/Bar.so
    lib/auto/Foo/Bar/Bar.inl

(The .inl component contains dependency information to make sure the source code is in sync with the executable)

If you don't use NAME, Inline will pick a name for you based on your program name or package name. In this case, Inline will also enable the AUTONAME option which mangles in a small piece of the MD5 fingerprint into your object name, to make it unique.

AUTONAME

This option is enabled whenever the NAME parameter is not specified. To disable it say:

    use Inline C => 'DATA',
               DISABLE => 'AUTONAME';

AUTONAME mangles in enough of the MD5 fingerprint to make your module name unique. Objects created with AUTONAME will never get replaced. That also means they will never get cleaned up automatically.

AUTONAME is very useful for small throw away scripts. For more serious things, always use the NAME option.

VERSION

Specifies the version number of the Inline extension object. It is used only for modules, and it must match the global variable $VERSION. Additionally, this option should used if (and only if) a module is being set up to be installed permanently into the Perl sitelib tree. Inline will croak if you use it otherwise.

The presence of the VERSION parameter is the official way to let Inline know that your code is an installable/installed module. Inline will never generate an object in the temporary cache (_Inline/ directory) if VERSION is set. It will also never try to recompile a module that was installed into someone's Perl site tree.

So the basic rule is develop without VERSION, and deliver with VERSION.

WITH

WITH can also be used as a configuration option instead of using the special 'with' syntax. Do this if you want to use different sections of Inline code with different modules. (Probably a very rare usage)

    use Event;
    use Inline C => DATA => WITH => 'Event';

Modules specified using the config form of WITH will not be automatically required. You must use them yourself.

GLOBAL_LOAD

This option is for compiled languages only. It tells Inline to tell DynaLoader to load an object file in such a way that its symbols can be dynamically resolved by other object files. May not work on all platforms. See the GLOBAL shortcut below.

UNTAINT

You must use this option whenever you use Perl's -T switch, for taint checking. This option tells Inline to blindly untaint all tainted variables. It also turns on SAFEMODE by default. See the UNTAINT shortcut below.

SAFEMODE

Perform extra safety checking, in an attempt to thwart malicious code. This option cannot guarantee security, but it does turn on all the currently implemented checks.

There is a slight startup penalty by using SAFEMODE. Also, using UNTAINT automatically turns this option on. If you need your code to start faster under -T (taint) checking, you'll need to turn this option off manually. Only do this if you are not worried about security risks. See the UNSAFE shortcut below.

FORCE_BUILD

Makes Inline build (compile) the source code every time the program is run. The default is 0. See the FORCE shortcut below.

BUILD_NOISY

Tells ILSMs that they should dump build messages to the terminal rather than be silent about all the build details.

BUILD_TIMERS

Tells ILSMs to print timing information about how long each build phase took. Usually requires Time::HiRes.

CLEAN_AFTER_BUILD

Tells Inline to clean up the current build area if the build was successful. Sometimes you want to DISABLE this for debugging. Default is 1. See the NOCLEAN shortcut below.

CLEAN_BUILD_AREA

Tells Inline to clean up the old build areas within the entire Inline DIRECTORY. Default is 0. See the CLEAN shortcut below.

PRINT_INFO

Tells Inline to print various information about the source code. Default is 0. See the INFO shortcut below.

PRINT_VERSION

Tells Inline to print Version info about itself. Default is 0. See the VERSION shortcut below.

REPORTBUG

Puts Inline into 'REPORTBUG' mode, which is what you want if you desire to report a bug.

WARNINGS

This option tells Inline whether to print certain warnings. Default is 1.

Inline Configuration Shortcuts

This is a list of all the shorcut configuration options currently available for Inline. Specify them from the command line when running Inline scripts.

    perl -MInline=NOCLEAN inline_script.pl

or

    perl -MInline=Info,force,NoClean inline_script.pl

You can specify multiple shortcuts separated by commas. They are not case sensitive. You can also specify shorcuts inside the Inline program like this:

    use Inline 'Info', 'Force', 'Noclean';

NOTE: If a 'use Inline' statement is used to set shortcuts, it can not be used for additional purposes.

CLEAN

Tells Inline to remove any build directories that may be lying around in your build area. Normally these directories get removed immediately after a successful build. Exceptions are when the build fails, or when you use the NOCLEAN or REPORTBUG options.

FORCE

Forces the code to be recompiled, even if everything is up to date.

GLOBAL

Turns on the GLOBAL_LOAD option.

INFO

This is a very useful option when you want to know what's going on under the hood. It tells Inline to print helpful information to STDERR. Among the things that get printed is a list of which Inline functions were successfully bound to Perl.

NOCLEAN

Tells Inline to leave the build files after compiling.

NOISY

Use the BUILD_NOISY option to print messages during a build.

REPORTBUG

Puts Inline into 'REPORTBUG' mode, which does special processing when you want to report a bug. REPORTBUG also automatically forces a build, and doesn't clean up afterwards. This is so that you can tar and mail the build directory to me. REPORTBUG will print exact instructions on what to do. Please read and follow them carefully.

NOTE: REPORTBUG informs you to use the tar command. If your system does not have tar, please use the equivalent zip command.

SAFE

Turns SAFEMODE on. UNTAINT will turn this on automatically. While this mode performs extra security checking, it does not guarantee safety.

SITE_INSTALL

This parameter used to be used for creating installable Inline modules. It has been removed from Inline altogether and replaced with a much simpler and more powerful mechanism, Inline::MakeMaker. See the section below on how to create modules with Inline.

TIMERS

Turn on BUILD_TIMERS to get extra diagnostic info about builds.

UNSAFE

Turns SAFEMODE off. Use this in combination with UNTAINT for slightly faster startup time under -T. Only use this if you are sure the environment is safe.

UNTAINT

Turn the UNTAINT option on. Used with -T switch.

VERSION

Tells Inline to report its release version.

Writing Modules with Inline

Writing CPAN modules that use C code is easy with Inline. Let's say that you wanted to write a module called Math::Simple. Start by using the following command:

    h2xs -PAXn Math::Simple

This will generate a bunch of files that form a skeleton of what you need for a distributable module. (Read the h2xs manpage to find out what the options do) Next, modify the Simple.pm file to look like this:

    package Math::Simple;
    $VERSION = '1.23';

    use base 'Exporter';
    @EXPORT_OK = qw(add subtract);
    use strict;

    use Inline C => 'DATA',
               VERSION => '1.23',
               NAME => 'Math::Simple';

    1;

    __DATA__

    =pod

    =cut

    __C__
    int add(int x, int y) {
      return x + y;
    }

    int subtract(int x, int y) {
      return x - y;
    }

The important things to note here are that you must specify a NAME and VERSION parameter. The NAME must match your module's package name. The VERSION parameter must match your module's $VERSION variable and they must be of the form /^\d\.\d\d$/.

NOTE: These are Inline's sanity checks to make sure you know what you're doing before uploading your code to CPAN. They insure that once the module has been installed on someone's system, the module would not get automatically recompiled for any reason. This makes Inline based modules work in exactly the same manner as XS based ones.

Finally, you need to modify the Makefile.PL. Simply change:

    use ExtUtils::MakeMaker;

to

    use Inline::MakeMaker;

When the person installing Math::Simple does a "make", the generated Makefile will invoke Inline in such a way that the C code will be compiled and the executable code will be placed into the ./blib directory. Then when a "make install" is done, the module will be copied into the appropiate Perl sitelib directory (which is where an installed module should go).

Now all you need to do is:

    perl Makefile.PL
    make dist

That will generate the file Math-Simple-0.20.tar.gz which is a distributable package. That's all there is to it.

IMPORTANT NOTE: Although the above steps will produce a workable module, you still have a few more responsibilities as a budding new CPAN author. You need to write lots of documentation and write lots of tests. Take a look at some of the better CPAN modules for ideas on creating a killer test harness. Actually, don't listen to me, go read these:

    perldoc perlnewmod
    http://www.cpan.org/modules/04pause.html
    http://www.cpan.org/modules/00modlist.long.html

How Inline Works

In reality, Inline just automates everything you would need to do if you were going to do it by hand (using XS, etc).

Inline performs the following steps:

  1. ) Receive the Source Code

    Inline gets the source code from your script or module with a statements like the following:

        use Inline C => "Source-Code";

    or

        use Inline;
    bind Inline C => "Source-Code";

    where C is the programming language of the source code, and Source-Code is a string, a file name, an array reference, or the special 'DATA' keyword.

    Since Inline is coded in a "use" statement, everything is done during Perl's compile time. If anything needs to be done that will affect the Source-Code, it needs to be done in a BEGIN block that is before the "use Inline ..." statement. If you really need to specify code to Inline at runtime, you can use the bind() method.

    Source code that is stowed in the 'DATA' section of your code, is read in by an INIT subroutine in Inline. That's because the DATA filehandle is not available at compile time.

  2. ) Check if the Source Code has been Built

    Inline only needs to build the source code if it has not yet been built. It accomplishes this seemingly magical task in an extremely simple and straightforward manner. It runs the source text through the Digest::MD5 module to produce a 128-bit "fingerprint" which is virtually unique. The fingerprint along with a bunch of other contingency information is stored in a .inl file that sits next to your executable object. For instance, the C code from a script called example.pl might create these files:

        example_pl_3a9a.so
    example_pl_3a9a.inl

    If all the contingency information matches the values stored in the .inl file, then proceed to step 8. (No compilation is necessary)

  3. ) Find a Place to Build and Install

    At this point Inline knows it needs to build the source code. The first thing to figure out is where to create the great big mess associated with compilation, and where to put the object when it's done.

    By default Inline will try to build and install under the first place that meets one of the following conditions:

        A) The DIRECTORY= config option; if specified
    B) The PERL_INLINE_DIRECTORY environment variable; if set
    C) .Inline/ (in current directory); if exists and $PWD != $HOME
    D) bin/.Inline/ (in directory of your script); if exists
    E) ~/.Inline/; if exists
    F) ./_Inline/; if exists
    G) bin/_Inline; if exists
    H) Create ./_Inline/; if possible
    I) Create bin/_Inline/; if possible

    Failing that, Inline will croak. This is rare and easily remedied by just making a directory that Inline will use;

    If the module option is being compiled for permanent installation, then Inline will only use ./_Inline/ to build in, and the $Config{installsitearch} directory to install the executable in. This action is caused by Inline::MakeMaker, and is intended to be used in modules that are to be distributed on the CPAN, so that they get installed in the proper place.

  4. ) Parse the Source for Semantic Cues

    Inline::C uses the module Parse::RecDescent to parse through your chunks of C source code and look for things that it can create run-time bindings to. In C it looks for all of the function definitions and breaks them down into names and data types. These elements are used to correctly bind the C function to a Perl subroutine. Other Inline languages like Python and Java actually use the python and javac modules to parse the Inline code.

  5. ) Create the Build Environment

    Now Inline can take all of the gathered information and create an environment to build your source code into an executable. Without going into all the details, it just creates the appropriate directories, creates the appropriate source files including an XS file (for C) and a Makefile.PL.

  6. ) Build the Code and Install the Executable

    The planets are in alignment. Now for the easy part. Inline just does what you would do to install a module. "perl Makefile.PL && make && make test && make install". If something goes awry, Inline will croak with a message indicating where to look for more info.

  7. ) Tidy Up

    By default, Inline will remove all of the mess created by the build process, assuming that everything worked. If the build fails, Inline will leave everything intact, so that you can debug your errors. Setting the NOCLEAN shortcut option will also stop Inline from cleaning up.

  8. ) DynaLoad the Executable

    For C (and C++), Inline uses the DynaLoader::bootstrap method to pull your external module into Perl space. Now you can call all of your external functions like Perl subroutines.

    Other languages like Python and Java, provide their own loaders.

SEE ALSO

For information about using Inline with C see the Inline::C manpage.

For sample programs using Inline with C see the Inline::C-Cookbook manpage.

For "Formerly Answered Questions" about Inline, see the Inline-FAQ manpage.

For information on supported languages and platforms see the Inline-Support manpage.

For information on writing your own Inline Language Support Module, see the Inline-API manpage.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

BUGS AND DEFICIENCIES

When reporting a bug, please do the following:

 - Put "use Inline REPORTBUG;" at the top of your code, or
   use the command line option "perl -MInline=REPORTBUG ...".
 - Run your code.
 - Follow the printed directions.

AUTHOR

Brian Ingerson <INGY@cpan.org>

Neil Watkiss <NEILW@cpan.org> is the author of Inline::CPP, Inline::Python, Inline::Ruby, Inline::ASM, Inline::Struct and Inline::Filters. He is known in the innermost Inline circles as the "Boy Wonder".

COPYRIGHT

Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Inline::C - Write Perl Subroutines in C

  • Usage
  • Function Definitions
  • C Configuration Options
    • AUTO_INCLUDE
    • AUTOWRAP
    • BOOT
    • CC
    • CCFLAGS
    • FILTERS
    • INC
    • LD
    • LDDLFLAGS
    • LIBS
    • MAKE
    • MYEXTLIB
    • OPTIMIZE
    • PREFIX
    • TYPEMAPS
  • C-Perl Bindings
  • The Inline Stack Macros
  • Writing C Subroutines
  • Examples
    • Example #1 - Greetings
    • Example #2 - and Salutations
    • Example #3 - Fixing the problem
  • SEE ALSO
  • BUGS AND DEFICIENCIES
  • AUTHOR
  • COPYRIGHT

NAME

Inline::C - Write Perl Subroutines in C

DESCRIPTION

Inline::C is a module that allows you to write Perl subroutines in C. Since version 0.30 the Inline module supports multiple programming languages and each language has its own support module. This document describes how to use Inline with the C programming language. It also goes a bit into Perl C internals.

If you want to start working with programming examples right away, check out the Inline::C-Cookbook manpage. For more information on Inline in general, see the Inline manpage.

Usage

You never actually use Inline::C directly. It is just a support module for using Inline.pm with C. So the usage is always:

    use Inline C => ...;

or

    bind Inline C => ...;

Function Definitions

The Inline grammar for C recognizes certain function definitions (or signatures) in your C code. If a signature is recognized by Inline, then it will be available in Perl-space. That is, Inline will generate the "glue" necessary to call that function as if it were a Perl subroutine. If the signature is not recognized, Inline will simply ignore it, with no complaints. It will not be available from Perl-space, although it will be available from C-space.

Inline looks for ANSI/prototype style function definitions. They must be of the form:

    return-type function-name ( type-name-pairs ) { ... }

The most common types are: int, long, double, char*, and SV*. But you can use any type for which Inline can find a typemap. Inline uses the typemap file distributed with Perl as the default. You can specify more typemaps with the TYPEMAPS configuration option.

A return type of void may also be used. The following are examples of valid function definitions.

    int Foo(double num, char* str) {
    void Foo(double num, char* str) {
    SV* Foo() {
    void Foo(SV*, ...) {
    long Foo(int i, int j, ...) {

The following definitions would not be recognized:

    Foo(int i) {               # no return type
    int Foo(float f) {         # no (default) typemap for float
    int Foo(num, str) double num; char* str; {
    void Foo(void) {           # void only valid for return type

Notice that Inline only looks for function definitions, not function prototypes. Definitions are the syntax directly preceeding a function body. Also Inline does not scan external files, like headers. Only the code passed to Inline is used to create bindings; although other libraries can linked in, and called from C-space.

C Configuration Options

For information on how to specify Inline configuration options, see the Inline manpage. This section describes each of the configuration options available for C. Most of the options correspond either to MakeMaker or XS options of the same name. See the ExtUtils::MakeMaker manpage and the perlxs manpage.

AUTO_INCLUDE

Specifies extra statements to automatically included. They will be added onto the defaults. A newline char will be automatically added.

    use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"';

AUTOWRAP

If you 'ENABLE => AUTOWRAP', Inline::C will parse function declarations (prototype statements) in your C code. For each declaration it can bind to, it will create a dummy wrapper that will call the real function which may be in an external library. This is a nice convenience for functions that would otherwise just require an empty wrapper function.

This is similar to the base functionality you get from h2xs. It can be very useful for binding to external libraries.

BOOT

Specifies C code to be executed in the XS BOOT section. Corresponds to the XS parameter.

CC

Specify which compiler to use.

CCFLAGS

Specify extra compiler flags.

FILTERS

Allows you to specify a list of source code filters. If more than one is requested, be sure to group them with an array ref. The filters can either be subroutine references or names of filters provided by the supplementary Inline::Filters module.

Your source code will be filtered just before it is parsed by Inline. The MD5 fingerprint is generated before filtering. Source code filters can be used to do things like stripping out POD documentation, pre-expanding #include statements or whatever else you please. For example:

    use Inline C => DATA =>
               FILTERS => [Strip_POD => \&MyFilter => Preprocess ];

Filters are invoked in the order specified. See the Inline::Filters manpage for more information.

INC

Specifies an include path to use. Corresponds to the MakeMaker parameter.

    use Inline C => Config => INC => '-I/inc/path';

LD

Specify which linker to use.

LDDLFLAGS

Specify which linker flags to use.

NOTE: These flags will completely override the existing flags, instead of just adding to them. So if you need to use those too, you must respecify them here.

LIBS

Specifies external libraries that should be linked into your code. Corresponds to the MakeMaker parameter.

    use Inline C => Config => LIBS => '-lyourlib';

or

    use Inline C => Config => LIBS => '-L/your/path -lyourlib';

MAKE

Specify the name of the 'make' utility to use.

MYEXTLIB

Specifies a user compiled object that should be linked in. Corresponds to the MakeMaker parameter.

    use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so';

OPTIMIZE

This controls the MakeMaker OPTIMIZE setting. By setting this value to '-g', you can turn on debugging support for your Inline extensions. This will allow you to be able to set breakpoints in your C code using a debugger like gdb.

PREFIX

Specifies a prefix that will be automatically stripped from C functions when they are bound to Perl. Useful for creating wrappers for shared library API-s, and binding to the original names in Perl. Also useful when names conflict with Perl internals. Corresponds to the XS parameter.

    use Inline C => Config => PREFIX => 'ZLIB_';

TYPEMAPS

Specifies extra typemap files to use. These types will modify the behaviour of the C parsing. Corresponds to the MakeMaker parameter.

    use Inline C => Config => TYPEMAPS => '/your/path/typemap';

C-Perl Bindings

This section describes how the Perl variables get mapped to C variables and back again.

First, you need to know how Perl passes arguments back and forth to subroutines. Basically it uses a stack (also known as the Stack). When a sub is called, all of the parenthesized arguments get expanded into a list of scalars and pushed onto the Stack. The subroutine then pops all of its parameters off of the Stack. When the sub is done, it pushes all of its return values back onto the Stack.

The Stack is an array of scalars known internally as SV's. The Stack is actually an array of pointers to SV or SV*; therefore every element of the Stack is natively a SV*. For FMTYEWTK about this, read perldoc perlguts.

So back to variable mapping. XS uses a thing known as "typemaps" to turn each SV* into a C type and back again. This is done through various XS macro calls, casts and the Perl API. See perldoc perlapi. XS allows you to define your own typemaps as well for fancier non-standard types such as typedef-ed structs.

Inline uses the default Perl typemap file for its default types. This file is called /usr/local/lib/perl5/5.6.1/ExtUtils/typemap, or something similar, depending on your Perl installation. It has definitions for over 40 types, which are automatically used by Inline. (You should probably browse this file at least once, just to get an idea of the possibilities.)

Inline parses your code for these types and generates the XS code to map them. The most commonly used types are:

 - int
 - long
 - double
 - char*
 - void
 - SV*

If you need to deal with a type that is not in the defaults, just use the generic SV* type in the function definition. Then inside your code, do the mapping yourself. Alternatively, you can create your own typemap files and specify them using the TYPEMAPS configuration option.

A return type of void has a special meaning to Inline. It means that you plan to push the values back onto the Stack yourself. This is what you need to do to return a list of values. If you really don't want to return anything (the traditional meaning of void) then simply don't push anything back.

If ellipsis or ... is used at the end of an argument list, it means that any number of SV*s may follow. Again you will need to pop the values off of the Stack yourself.

See Examples below.

The Inline Stack Macros

When you write Inline C, the following lines are automatically prepended to your code (by default):

    #include "EXTERN.h"
    #include "perl.h"
    #include "XSUB.h"
    #include "INLINE.h"

The file INLINE.h defines a set of macros that are useful for handling the Perl Stack from your C functions.

Inline_Stack_Vars

You'll need to use this one, if you want to use the others. It sets up a few local variables: sp, items, ax and mark, for use by the other macros. It's not important to know what they do, but I mention them to avoid possible name conflicts.

NOTE: Since this macro declares variables, you'll need to put it with your other variable declarations at the top of your function. It must come before any executable statements and before any other Inline_Stack macros.

Inline_Stack_Items

Returns the number of arguments passed in on the Stack.

Inline_Stack_Item(i)

Refers to a particular SV* in the Stack, where i is an index number starting from zero. Can be used to get or set the value.

Inline_Stack_Reset

Use this before pushing anything back onto the Stack. It resets the internal Stack pointer to the beginning of the Stack.

Inline_Stack_Push(sv)

Push a return value back onto the Stack. The value must be of type SV*.

Inline_Stack_Done

After you have pushed all of your return values, you must call this macro.

Inline_Stack_Return(n)

Return n items on the Stack.

Inline_Stack_Void

A special macro to indicate that you really don't want to return anything. Same as:

    Inline_Stack_Return(0);

Please note that this macro actually returns from your function.

Each of these macros is available in 3 different styles to suit your coding tastes. The following macros are equivalent.

    Inline_Stack_Vars
    inline_stack_vars
    INLINE_STACK_VARS

All of this functionality is available through XS macro calls as well. So why duplicate the functionality? There are a few reasons why I decided to offer this set of macros. First, as a convenient way to access the Stack. Second, for consistent, self documenting, non-cryptic coding. Third, for future compatibility. It occured to me that if a lot of people started using XS macros for their C code, the interface might break under Perl6. By using this set, hopefully I will be able to insure future compatibility of argument handling.

Of course, if you use the rest of the Perl API, your code will most likely break under Perl6. So this is not a 100% guarantee. But since argument handling is the most common interface you're likely to use, it seemed like a wise thing to do.

Writing C Subroutines

The definitions of your C functions will fall into one of the following four categories. For each category there are special considerations.

  1.     int Foo(int arg1, char* arg2, SV* arg3) {

    This is the simplest case. You have a non void return type and a fixed length argument list. You don't need to worry about much. All the conversions will happen automatically.

  2.     void Foo(int arg1, char* arg2, SV* arg3) {

    In this category you have a void return type. This means that either you want to return nothing, or that you want to return a list. In the latter case you'll need to push values onto the Stack yourself. There are a few Inline macros that make this easy. Code something like this:

        int i, max; SV* my_sv[10];
    Inline_Stack_Vars;
    Inline_Stack_Reset;
    for (i = 0; i < max; i++)
      Inline_Stack_Push(my_sv[i]);
    Inline_Stack_Done;

    After resetting the Stack pointer, this code pushes a series of return values. At the end it uses Inline_Stack_Done to mark the end of the return stack.

    If you really want to return nothing, then don't use the Inline_Stack_ macros. If you must use them, then set use Inline_Stack_Void at the end of your function.

  3.     char* Foo(SV* arg1, ...) {

    In this category you have an unfixed number of arguments. This means that you'll have to pop values off the Stack yourself. Do it like this:

        int i;
    Inline_Stack_Vars;
    for (i = 0; i < Inline_Stack_Items; i++)
      handle_sv(Inline_Stack_Item(i));

    The return type of Inline_Stack_Item(i) is SV*.

  4.     void* Foo(SV* arg1, ...) {

    In this category you have both a void return type and an unfixed number of arguments. Just combine the techniques from Categories 3 and 4.

Examples

Here are a few examples. Each one is a complete program that you can try running yourself. For many more examples see the Inline::C-Cookbook manpage.

Example #1 - Greetings

This example will take one string argument (a name) and print a greeting. The function is called with a string and with a number. In the second case the number is forced to a string.

Notice that you do not need to #include <stdio.h>. The perl.h header file which gets included by default, automatically loads the standard C header files for you.

    use Inline C;
    greet('Ingy');
    greet(42);
    __END__
    __C__
    void greet(char* name) {
      printf("Hello %s!\n", name);
    }

Example #2 - and Salutations

This is similar to the last example except that the name is passed in as a SV* (pointer to Scalar Value) rather than a string (char*). That means we need to convert the SV to a string ourselves. This is accomplished using the SvPVX function which is part of the Perl internal API. See perldoc perlapi for more info.

One problem is that SvPVX doesn't automatically convert strings to numbers, so we get a little surprise when we try to greet 42. The program segfaults, a common occurence when delving into the guts of Perl.

    use Inline C;
    greet('Ingy');
    greet(42);
    __END__
    __C__
    void greet(SV* sv_name) {
      printf("Hello %s!\n", SvPVX(sv_name));
    }

Example #3 - Fixing the problem

We can fix the problem in Example #2 by using the SvPV function instead. This function will stringify the SV if it does not contain a string. SvPV returns the length of the string as it's second parameter. Since we don't care about the length, we can just put PL_na there, which is a special variable designed for that purpose.

    use Inline C;
    greet('Ingy');
    greet(42);
    __END__
    __C__
    void greet(SV* sv_name) {
      printf("Hello %s!\n", SvPV(sv_name, PL_na));
    }

SEE ALSO

For general information about Inline see the Inline manpage.

For sample programs using Inline with C see the Inline::C-Cookbook manpage.

For information on supported languages and platforms see the Inline-Support manpage.

For information on writing your own Inline Language Support Module, see the Inline-API manpage.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

BUGS AND DEFICIENCIES

  1. If you use C function names that happen to be used internally by Perl, you will get a load error at run time. There is currently no functionality to prevent this or to warn you. For now, a list of Perl's internal symbols is packaged in the Inline module distribution under the filename 'symbols.perl'. Avoid using these in your code.

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Inline::C::ParseRecDescent - The Classic Inline::C Parser

    • AUTHOR
  • COPYRIGHT

NAME

Inline::C::ParseRecDescent - The Classic Inline::C Parser

SYNOPSIS

    use Inline C => DATA =>
               USING => ParseRecDescent

DESCRIPTION

This module is Inline::C's original Parse::RecDescent based parser. It was previously packaged as Inline::C::grammar.

Try Inline::C::ParseRegExp for an alternative.

AUTHOR

Brian Ingerson <ingy@ttul.org>

COPYRIGHT

Copyright (c) 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Inline::C::ParseRegExp - The New and Improved Inline::C Parser

    • AUTHOR
  • COPYRIGHT

NAME

Inline::C::ParseRegExp - The New and Improved Inline::C Parser

SYNOPSIS

    use Inline C => DATA =>
               USING => ParseRegExp;

DESCRIPTION

This module is a much faster version of Inline::C's Parse::RecDescent parser. It is based on regular expressions instead.

AUTHOR

Mitchell N Charity <mcharity@vendian.org>

COPYRIGHT

Copyright (c) 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Cookbook - A Cornucopia of Inline C Recipes

  • Appetizers
    • Hello, world
    • One Liner
  • Meat & Potatoes
    • Data Types
    • Variable Argument Lists
    • Multiple Return Values
    • Multiple Return Values (Another Way)
    • Using Memory
  • Fast Food
    • Inline CGI
    • mod_perl
    • Object Oriented Inline
  • The Main Course
    • Exposing Shared Libraries
    • Automatic Function Wrappers
    • Complex Data
    • Hash of Lists
  • Just Desserts
    • Win32
    • Embedding Perl in C
  • Entertaining Guests
    • Event handling with Event.pm
  • Food for Thought
    • Calling C from both Perl and C
    • Calling Perl from C
    • Evaling C
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

C Cookbook - A Cornucopia of Inline C Recipes

DESCRIPTION

It's a lot easier for most of us to cook a meal from a recipe, rather than just throwing things into a pot until something edible forms. So it is with programming as well. Inline.pm makes C programming for Perl as easy as possible. Having a set of easy to understand samples, makes it simpler yet.

This Cookbook is intended to be an evergrowing repository of small yet complete coding examples; each showing how to accomplish a particular task with Inline. Each example is followed by a short discussion, explaining in detail the particular features that are being demonstrated.

Many of these recipes are apdapted from email discussions I have had with Inline users around the world. It has been my experience so far, that Inline provides an elegant solution to almost all problems involving Perl and C.

Bon Appetit!

Appetizers

Hello, world

Problem

It seems that the first thing any programmer wants to do when he learns a new programming technique is to use it to greet the Earth. How can I do this using Inline?

Solution
    use Inline C => <<'END_C';

    void greet() {
        printf("Hello, world\n");
    }
    END_C

    greet;
Discussion

Nothing too fancy here. We define a single C function greet() which prints a message to STDOUT. One thing to note is that since the Inline code comes before the function call to greet, we can call it as a bareword (no parentheses).

See Also

See the Inline manpage and the Inline::C manpage for basic info about Inline.pm.

Credits

Brian Kernigan

Dennis Ritchie

One Liner

Problem

A concept is valid in Perl only if it can be shown to work in one line. Can Inline reduce the complexities of Perl/C interaction to a one-liner?

Solution
    perl -e 'use Inline C=>q{void greet(){printf("Hello, world\n");}};greet'
Discussion

Try doing that in XS :-)

See Also

My email signature of late is:

    perl -le 'use Inline C=>q{SV*JAxH(char*x){return newSVpvf("Just Another %s Hacker",x);}};print JAxH+Perl'

A bit fancier but a few bytes too long to qualify as a true one liner :-(

Credits

"Eli the Bearded" <elijah@workspot.net> gave me the idea that I should have an Inline one-liner as a signature.

Meat & Potatoes

Data Types

Problem

How do I pass different types of data to and from Inline C functions; like strings, numbers and integers?

Solution
    # vowels.pl
    use Inline C;

    $filename = $ARGV[0];
    die "Usage: perl vowels.pl filename\n" unless -f $filename;

    $text = join '', <>;           # slurp input file
    $vp = vowel_scan($text);       # call our function
    $vp = sprintf("%03.1f", $vp * 100);  # format for printing
    print "The letters in $filename are $vp% vowels.\n";

    __END__
    __C__

    /* Find percentage of vowels to letters */
    double vowel_scan(char* str) {
        int letters = 0;
        int vowels = 0;
        int i = 0;
        char c;
        char normalize = 'a' ^ 'A';
        /* normalize forces lower case in ASCII; upper in EBCDIC */
        char A = normalize | 'a';
        char E = normalize | 'e';
        char I = normalize | 'i';
        char O = normalize | 'o';
        char U = normalize | 'u';
        char Z = normalize | 'z';

        while(c = str[i++]) {
            c |= normalize;
            if (c >= A && c <= Z) {
                 letters++;
                 if (c == A || c == E || c == I || c == O || c == U)
                     vowels++;
            }
        }

        return letters ? ((double) vowels / letters) : 0.0;
            }
Discussion

This script takes a file name from the command line and prints the ratio of vowels to letters in that file. vowels.pl uses an Inline C function called vowel_scan, that takes a string argument, and returns the percentage of vowels as a floating point number between 0 and 1. It handles upper and lower case letters, and works with ASCII and EBCDIC. It is also quite fast.

Running this script produces:

    > perl vowels.pl /usr/dict/words
    The letters in /usr/dict/words are 37.5% vowels.
See Also

The Perl Journal vol #19 has an article about Inline which uses this example.

Credits

This example was reprinted by permission of The Perl Journal. It was edited to work with Inline v0.30 and higher.

Variable Argument Lists

Problem

How do I pass a variable-sized list of arguments to an Inline C function?

Solution
    greet(qw(Sarathy Jan Sparky Murray Mike));

    use Inline C => <<'END_OF_C_CODE';

    void greet(SV* name1, ...) {
        Inline_Stack_Vars;
        int i;

        for (i = 0; i < Inline_Stack_Items; i++)
            printf("Hello %s!\n", SvPV(Inline_Stack_Item(i), PL_na));

        Inline_Stack_Void;
    }

    END_OF_C_CODE
Discussion

This little program greets a group of people, such as my coworkers. We use the C ellipsis syntax: "...", since the list can be of any size.

Since there are no types or names associated with each argument, we can't expect XS to handle the conversions for us. We'll need to pop them off the Stack ourselves. Luckily there are two functions (macros) that make this a very easy task.

First, we need to begin our function with a "Inline_Stack_Vars" statement. This defines a few internal variables that we need to access the Stack. Now we can use "Inline_Stack_Items", which returns an integer containing the number of arguments passed to us from Perl.

NOTE: It is important to only use "Inline_Stack_" macros when there is an ellipsis (...) in the argument list, or the function has a return type of void.

Second, we use the Inline_Stack_Item(x) function to access each argument where "0 <= x < items".

NOTE: When using a variable length argument list, you have to specify at least one argument before the ellipsis. (On my compiler, anyway.) When XS does it's argument checking, it will complain if you pass in less than the number of defined arguments. Therefore, there is currently no way to pass an empty list when a variable length list is expected.

See Also
Credits

Multiple Return Values

Problem

How do I return a list of values from a C function?

Solution
    print map {"$_\n"} get_localtime(time);

    use Inline C => <<'END_OF_C_CODE';

    #include <time.h>

    void get_localtime(int utc) {
      struct tm *ltime = localtime(&utc);
      Inline_Stack_Vars;

      Inline_Stack_Reset;
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_year)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_mon)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_mday)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_hour)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_min)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_sec)));
      Inline_Stack_Push(sv_2mortal(newSViv(ltime->tm_isdst)));
      Inline_Stack_Done;
    }
    END_OF_C_CODE
Discussion

Perl is a language where it is common to return a list of values from a subroutine call instead of just a single value. C is not such a language. In order to accomplish this in C we need to manipulate the Perl call stack by hand. Luckily, Inline provides macros to make this easy.

This example calls the system localtime, and returns each of the parts of the time struct; much like the perl builtin localtime(). On each stack push, we are creating a new Perl integer (SVIV) and mortalizing it. The sv_2mortal() call makes sure that the reference count is set properly. Without it, the program would leak memory.

NOTE: The #include statement is not really needed, because Inline automatically includes the Perl headers which include almost all standard system calls.

See Also

For more information on the Inline stack macros, see the Inline::C manpage.

Credits

Richard Anderson <starfire@zipcon.net> contributed the original idea for this snippet.

Multiple Return Values (Another Way)

Problem

How can I pass back more than one value without using the Perl Stack?

Solution
    use Inline::Files;
    use Inline C;

    my ($foo, $bar);
    change($foo, $bar);

    print "\$foo = $foo\n";
    print "\$bar = $bar\n";

    __C__

    int change(SV* var1, SV* var2) {
        sv_setpvn(var1, "Perl Rocks!", 11);
        sv_setpvn(var2, "Inline Rules!", 13);
        return 1;
    }
Discussion

Most perl function interfaces return values as a list of one or more scalars. Very few like chomp, will modify an input scalar in place. On the other hand, in C you do this quite often. Values are passed in by reference and modified in place by the called function.

It turns out that we can do that with Inline as well. The secret is to use a type of 'SV*' for each argument that is to be modified. This ensures passing by reference, because no typemapping is needed.

The function can then use the Perl5 API to operate on that argument. When control returns to Perl, the argument will retain the value set by the C function. In this example we passed in 2 empty scalars and assigned values directly to them.

See Also
Credits

Ned Konz <ned@bike-nomad.com> brought this behavior to my attention. He also pointed out that he is not the world famous computer cyclist Steve Roberts (http://www.microship.com), but he is close (http://bike-nomad.com). Thanks Ned.

Using Memory

Problem

How should I allocate buffers in my Inline C code?

Solution
    print greeting('Ingy');

    use Inline C => <<'END_OF_C_CODE';

    SV* greeting(SV* sv_name) {
        return (newSVpvf("Hello %s!\n", SvPV(sv_name, PL_na)));
    }

    END_OF_C_CODE
Discussion

In this example we will return the greeting to the caller, rather than printing it. This would seem mighty easy, except for the fact that we need to allocate a small buffer to create the greeting.

I would urge you to stay away from mallocing your own buffer. Just use Perl's built in memory management. In other words, just create a new Perl string scalar. The function newSVpv does just that. And newSVpvf includes sprintf functionality.

The other problem is getting rid of this new scalar. How will the ref count get decremented after we pass the scalar back? Perl also provides a function called sv_2mortal. Mortal variables die when the context goes out of scope. In other words, Perl will wait until the new scalar gets passed back and then decrement the ref count for you, thereby making it eligible for garbage collection. See perldoc perlguts.

In this example the sv_2mortal call gets done under the hood by XS, because we declared the return type to be SV*.

To view the generated XS code, run the command "perl -MInline=INFO,FORCE,NOCLEAN example004.pl". This will leave the build directory intact and tell you where to find it.

See Also
Credits

Fast Food

Inline CGI

Problem

How do I use Inline securely in a CGI environment?

Solution
    #!/usr/bin/perl

    use CGI qw(:standard);
    use Inline (Config =>
                DIRECTORY => '/usr/local/apache/Inline',
               );

    print (header,
           start_html('Inline CGI Example'),
           h1(JAxH('Inline')),
           end_html
          );

    use Inline C => <<END;
    SV* JAxH(char* x) {
        return newSVpvf("Just Another %s Hacker", x);
    }
    END
Discussion

The problem with running Inline code from a CGI script is that Inline writes to a build area on your disk whenever it compiles code. Most CGI scripts don't (and shouldn't) be able to create a directory and write into it.

The solution is to explicitly tell Inline which directory to use with the 'use Inline Config => DIRECTORY => ...' line. Then you need to give write access to that directory from the web server (CGI script).

If you see this as a security hole, then there is another option. Give write access to yourself, but read-only access to the CGI script. Then run the script once by hand (from the command line). This will cause Inline to precompile the C code. That way the CGI will only need read access to the build directory (to load in the shared library from there).

Just remember that whenever you change the C code, you need to precompile it again.

See Also

See the CGI manpage for more information on using the CGI.pm module.

Credits

mod_perl

Problem

How do I use Inline with mod_perl?

Solution
    package Factorial;
    use strict;
    use Inline Config =>
               DIRECTORY => '/usr/local/apache/Inline',
               ENABLE => 'UNTAINT';
    use Inline 'C';
    Inline->init;

    sub handler {
        my $r = shift;
        $r->send_http_header('text/plain');
        printf "%3d! = %10d\n", $_, factorial($_) for 1..100;
        return Apache::Constants::OK;
    }

    1;
    __DATA__
    __C__
    double factorial(double x) {
        if (x < 2)  return 1;
        return x * factorial(x - 1)
    }
Discussion

This is a fully functional mod_perl handler that prints out the factorial values for the numbers 1 to 100. Since we are using Inline under mod_perl, there are a few considerations to , um, consider.

First, mod_perl handlers are usually run with -T taint detection. Therefore, we need to enable the UNTAINT option. The next thing to deal with is the fact that this handler will most likely be loaded after Perl's compile time. Since we are using the DATA section, we need to use the special init() call. And of course we need to specify a DIRECTORY that mod_perl can compile into. See the above CGI example for more info.

Other than that, this is a pretty straightforward mod_perl handler, tuned for even more speed!

See Also

See Stas Bekman's upcoming O'Reilly book on mod_perl to which this example was contributed.

Credits

Object Oriented Inline

Problem

How do I implement Object Oriented programming in Perl using C objects?

Solution
    my $obj1 = Soldier->new('Benjamin', 'Private', 11111);
    my $obj2 = Soldier->new('Sanders', 'Colonel', 22222);
    my $obj3 = Soldier->new('Matt', 'Sergeant', 33333);

    for my $obj ($obj1, $obj2, $obj3) {
        print ($obj->get_serial, ") ",
               $obj->get_name, " is a ",
               $obj->get_rank, "\n");
    }

    #---------------------------------------------------------

    package Soldier;

    use Inline C => <<'END';

    typedef struct {
        char* name;
        char* rank;
        long  serial;
    } Soldier;

    SV* new(char* class, char* name, char* rank, long serial) {
        Soldier* soldier = malloc(sizeof(Soldier));
        SV*      obj_ref = newSViv(0);
        SV*      obj = newSVrv(obj_ref, class);

        soldier->name = strdup(name);
        soldier->rank = strdup(rank);
        soldier->serial = serial;

        sv_setiv(obj, (IV)soldier);
        SvREADONLY_on(obj);
        return obj_ref;
            }

            char* get_name(SV* obj) {
        return ((Soldier*)SvIV(SvRV(obj)))->name;
            }

            char* get_rank(SV* obj) {
        return ((Soldier*)SvIV(SvRV(obj)))->rank;
            }

            long get_serial(SV* obj) {
        return ((Soldier*)SvIV(SvRV(obj)))->serial;
            }

    void DESTROY(SV* obj) {
        Soldier* soldier = (Soldier*)SvIV(SvRV(obj));
        free(soldier->name);
        free(soldier->rank);
        free(soldier);
    }
    END
Discussion

Damian Conway has given us myriad ways of implementing OOP in Perl. This is one he might not have thought of.

The interesting thing about this example is that it uses Perl for all the OO bindings while using C for the attributes and methods.

If you examine the Perl code everything looks exactly like a regular OO example. There is a new method and several accessor methods. The familiar 'arrow syntax' is used to invoke them.

In the class definition (second part) the Perl package statement is used to name the object class or namespace. But that's where the similarities end Inline takes over.

The idea is that we call a C subroutine called new() which returns a blessed scalar. The scalar contains a readonly integer which is a C pointer to a Soldier struct. This is our object.

The new() function needs to malloc the memory for the struct and then copy the initial values into it using strdup(). This also allocates more memory (which we have to keep track of).

The accessor methods are pretty straightforward. They return the current value of their attribute.

The last method DESTROY() is called automatically by Perl whenever an object goes out of scope. This is where we can free all the memory used by the object.

That's it. It's a very simplistic example. It doesn't show off any advanced OO features, but it is pretty cool to see how easy the implementation can be. The important Perl call is newSVrv() which creates a blessed scalar.

See Also

Read "Object Oriented Perl" by Damian Conway, for more useful ways of doing OOP in Perl.

You can learn more Perl calls in the perlapi manpage. If you don't have Perl 5.6.0 or higher, visit http://www.perldoc.com/perl5.6/pod/perlapi.html

Credits

The Main Course

Exposing Shared Libraries

Problem

You have this great C library and you want to be able to access parts of it with Perl.

Solution
    print get('http://www.axkit.org');

    use Inline C => Config =>
               LIBS => '-lghttp';
    use Inline C => <<'END_OF_C_CODE';

    #include <ghttp.h>

    char *get(SV* uri) {
       SV* buffer;
       ghttp_request* request;

       buffer = NEWSV(0,0);
       request = ghttp_request_new();
       ghttp_set_uri(request, SvPV(uri, PL_na));

       ghttp_set_header(request, http_hdr_Connection, "close");

       ghttp_prepare(request);
       ghttp_process(request);

       sv_catpv(buffer, ghttp_get_body(request));

       ghttp_request_destroy(request);

       return SvPV(buffer, PL_na);
    }

    END_OF_C_CODE
Discussion

This example fetches and prints the HTML from http://www.axkit.org It requires the GNOME http libraries. http://www.gnome.org

One of the most common questions I get is "How can I use Inline to make use of some shared library?". Although it has always been possible to do so, the configuration was ugly, and there were no specific examples.

With version 0.30 and higher, you can specify the use of shared libraries easily with something like this:

    use Inline C => Config => LIBS => '-lghttp';
    use Inline C => "code ...";

or

    use Inline C => "code ...", LIBS => '-lghttp';

To specify a specific library path, use:

    use Inline C => "code ...", LIBS => '-L/your/lib/path -lyourlib';

To specify an include path use:

    use Inline C => "code ...",
               LIBS => '-lghttp',
               INC => '-I/your/inc/path';
See Also

The LIBS and INC configuration options are formatted and passed into MakeMaker. For more info see the ExtUtils::MakeMaker manpage. For more options see the Inline::C manpage.

Credits

This code was written by Matt Sergeant <matt@sergeant.org>, author of many CPAN modules. The configuration syntax has been modified for use with Inline v0.30.

Automatic Function Wrappers

Problem

You have some functions in a C library that you want to access from Perl exactly as you would from C.

Solution

The error function erf() is probably defined in your standard math library. Annoyingly, Perl does not let you access it. To print out a small table of its values, just say:

    perl -le 'use Inline C => q{ double erf(double); }, ENABLE => "AUTOWRAP"; print "$_ @{[erf($_)]}" for (0..10)'

The excellent Term::ReadLine::Gnu implements Term::ReadLine using the GNU ReadLine library. Here is an easy way to access just readline() from that library:

    package MyTerm;

    use Inline C => Config =>
               ENABLE => AUTOWRAP =>
               LIBS => "-lreadline -lncurses -lterminfo -ltermcap ";
    use Inline C => q{ char * readline(char *); };

    package main;
    my $x = MyTerm::readline("xyz: ");

Note however that it fails to free() the memory returned by readline, and that Term::ReadLine::Gnu offers a much richer interface.

Discussion

We access existing functions by merely showing Inline their declarations, rather than a full definition. Of course the function declared must exist, either in a library already linked to Perl or in a library specified using the LIBS option.

The first example wraps a function from the standard math library, so Inline requires no additional LIBS directive. The second uses the Config option to specify the libraries that contain the actual compiled C code.

This behavior is always disabled by default. You must enable the AUTOWRAP option to make it work.

See Also

readline, Term::ReadLine::Gnu

Credits

GNU ReadLine was written by Brian Fox <bfox@ai.mit.edu> and Chet Ramey <chet@ins.cwru.edu>. Term::ReadLine::Gnu was written by Hiroo Hayashi <hiroo.hayashi@computer.org>. Both are far richer than the slim interface given here!

The idea of producing wrapper code given only a function declaration is taken from Swig by David M. Beazley <beazley@cs.uchicago.edu>.

Ingy's inline editorial insight:

This entire entry was contributed by Ariel Scolnicov <ariels@compugen.co.il>. Ariel also first suggested the idea for Inline to support function declaration processing.

Complex Data

Problem

How do I deal with complex data types like hashes in Inline C?

Solution
    use Inline C => <<'END_OF_C_CODE';

    void dump_hash(SV* hash_ref) {
        HV* hash;
        HE* hash_entry;
        int num_keys, i;
        SV* sv_key;
        SV* sv_val;

        if (! SvROK(hash_ref))
            croak("hash_ref is not a reference");

        hash = (HV*)SvRV(hash_ref);
        num_keys = hv_iterinit(hash);
        for (i = 0; i < num_keys; i++) {
            hash_entry = hv_iternext(hash);
            sv_key = hv_iterkeysv(hash_entry);
            sv_val = hv_iterval(hash, hash_entry);
            printf("%s => %s\n", SvPV(sv_key, PL_na), SvPV(sv_val, PL_na));
        }
        return;
    }

    END_OF_C_CODE

    my %hash = (
                Author => "Brian Ingerson",
                Nickname => "INGY",
                Module => "Inline.pm",
                Version => "0.30",
                Language => "C",
               );

    dump_hash(\%hash);
Discussion

The world is not made of scalars alone, although they are definitely the easiest creatures to deal with, when doing Inline stuff. Sometimes we need to deal with arrays, hashes, and code references, among other things.

Since Perl subroutine calls only pass scalars as arguments, we'll need to use the argument type SV* and pass references to more complex types.

The above program dumps the key/value pairs of a hash. To figure it out, just curl up with the perlapi manpage for a couple hours. Actually, its fairly straight forward once you are familiar with the calls.

Note the croak function call. This is the proper way to die from your C extensions.

See Also

See the perlapi manpage for information about the Perl5 internal API.

Credits

Hash of Lists

Problem

How do I create a Hash of Lists from C?

Solution
    use Inline C;
    use Data::Dumper;

    $hash_ref = load_data("./cartoon.txt");
    print Dumper $hash_ref;

    __END__
    __C__

    static int next_word(char**, char*);

    SV* load_data(char* file_name) {
        char buffer[100], word[100], * pos;
        AV* array;
        HV* hash = newHV();
        FILE* fh = fopen(file_name, "r");

        while (fgets(pos = buffer, sizeof(buffer), fh)) {
            if (next_word(&pos, word)) {
                hv_store(hash, word, strlen(word),
                        newRV_noinc((SV*)array = newAV()), 0);
                while (next_word(&pos, word))
                    av_push(array, newSVpvf("%s", word));
            }
        }
        fclose(fh);
        return newRV_noinc((SV*) hash);
    }

    static int next_word(char** text_ptr, char* word) {
        char* text = *text_ptr;
        while(*text != '\0' &&
              *text <= ' ')
            text++;
        if (*text <= ' ')
            return 0;
        while(*text != '\0' &&
              *text > ' ') {
            *word++ = *text++;
        }
        *word = '\0';
        *text_ptr = text;
        return 1;
    }
Discussion

This is one of the larger recipes. But when you consider the number of calories it has, it's not so bad. The function load_data takes the name of a file as it's input. The file cartoon.text might look like:

    flintstones fred barney
    jetsons     george jane elroy
    simpsons    homer marge bart

The function will read the file, parsing each line into words. Then it will create a new hash, whereby the first word in a line becomes a hash key and the remaining words are put into an array whose reference becomes the hash value. The output looks like this:

    $VAR1 = {
              'flintstones' => [
                                 'fred',
                                 'barney'
                               ],
              'simpsons' => [
                              'homer',
                              'marge',
                              'bart'
                            ],
              'jetsons' => [
                             'george',
                             'jane',
                             'elroy'
                           ]
            };
See Also

See the perlapi manpage for information about the Perl5 internal API.

Credits

Al Danial <alnd@pacbell.net> requested a solution to this on comp.lang.perl.misc. He borrowed the idea from the "Hash of Lists" example in the Camel book.

Just Desserts

Win32

Problem

How do I access Win32 DLL-s using Inline?

Solution
    use Inline C => DATA =>
               LIBS => '-luser32';

    $text = "@ARGV" || 'Inline.pm works with MSWin32. Scary...';

    WinBox('Inline Text Box', $text);

    __END__
    __C__

    #include <windows.h>

    int WinBox(char* Caption, char* Text) {
      return MessageBoxA(0, Text, Caption, 0);
    }
Discussion

This example runs on MS Windows. It makes a text box appear on the screen which contains a message of your choice.

The important thing is that its proof that you can use Inline to interact with Windows DLL-s. Very scary indeed. 8-o

To use Inline on Windows with ActivePerl ( http://www.ActiveState.com ) you'll need MS Visual Studio. You can also use the Cygwin environment, available at http://www.cygwin.com .

See Also

See the Inline-Support manpage for more info on MSWin32 programming with Inline.

Credits

This example was adapted from some sample code written by Garrett Goebel <garrett@scriptpro.com>

Embedding Perl in C

Problem

How do I use Perl from a regular C program?

Solution
    #!/usr/bin/cpr

    int main(void) {

        printf("Using Perl version %s from a C program!\n\n",
               CPR_eval("use Config; $Config{version};"));

        CPR_eval("use Data::Dumper;");
        CPR_eval("print Dumper \\%INC;");

        return 0;

    }
Discussion

By using CPR. (C Perl Run)

This example uses another Inline module, Inline::CPR, available separately on CPAN. When you install this module it also installs a binary interpreter called /usr/bin/cpr. (The path may be different on your system)

When you feed a C program to the CPR interpreter, it automatically compiles and runs your code using Inline. This gives you full access to the Perl internals. CPR also provides a set of easy to use C macros for calling Perl internals.

This means that you can effectively "run" C source code by putting a CPR hashbang as the first line of your C program.

See Also

See the Inline::CPR manpage for more information on using CPR.

Inline::CPR can be obtained from http://search.cpan.org/search?dist=Inline-CPR

Credits

Randal Schwartz <merlyn@stonehenge.com>, Randolph Bentson <bentson@grieg.holmsjoen.com>, Richard Anderson <starfire@zipcon.net>, and Tim Maher <tim@consultix-inc.com> helped me figure out how to write a program that would work as a hashbang.

Entertaining Guests

As of version 0.30, Inline has the ability to work in cooperation with other modules that want to expose a C API of their own. The general syntax for doing this is:

    use Inline with => 'Module';
    use Inline C => ... ;

This tells Module to pass configuration options to Inline. Options like typemaps, include paths, and external libraries, are all resolved automatically so you can just concentrate on writing the functions.

Event handling with Event.pm

Problem

You need to write a C callback for the Event.pm module. Can this be done more easily with Inline?

Solution
    use Inline with => 'Event';

    Event->timer(desc     => 'Timer #1',
                 interval => 2,
                 cb       => \&my_callback,
                );

    Event->timer(desc     => 'Timer #2',
                 interval => 3,
                 cb       => \&my_callback,
                );

    print "Starting...\n";
    Event::loop;

    use Inline C => <<'END';
    void my_callback(pe_event* event) {
        pe_timer * watcher = event->up;

        printf("%s\n\tEvent priority = %d\n\tWatcher priority = %d\n\n",
               SvPVX(watcher->base.desc),
               event->prio,
               watcher->base.prio
              );
    }
    END
Discussion

The first line tells Inline to load the Event.pm module. Inline then queries Event for configuration information. It gets the name and location of Event's header files, typemaps and shared objects. The parameters that Event returns look like:

    INC => "-I $path/Event",
    TYPEMAPS => "$path/Event/typemap",
    MYEXTLIB => "$path/auto/Event/Event.$so",
    AUTO_INCLUDE => '#include "EventAPI.h"',
    BOOT => 'I_EVENT_API("Inline");',

Doing all of this automatically allows you, the programmer, to simply write a function that receives a pointer of type 'pe_event*'. This gives you access to the Event structure that was passed to you.

In this example, I simply print values out of the structure. The Perl code defines 2 timer events which each invoke the same callback. The first one, every two seconds, and the second one, every three seconds.

As of this writing, Event.pm is the only CPAN module that works in cooperation with Inline.

See Also

Read the Event.pm documentation for more information. It contains a tutorial showing several examples of using Inline with Event.

Credits

Jochen Stenzel <perl@jochen-stenzel.de> originally came up with the idea of mixing Inline and Event. He also authored the Event tutorial.

Joshua Pritikin <joshua.pritikin@db.com> is the author of Event.pm.

Food for Thought

Calling C from both Perl and C

Problem

I'd like to be able to call the same C function from both Perl and C. Also I like to define a C function that doesn't get bound to Perl. How do I do that?

Solution
    print "9 + 5 = ", add(9, 5), "\n";
    print "SQRT(9^2 + 5^2) = ", pyth(9, 5), "\n";
    print "9 * 5 = ", mult(9, 5), "\n";

    use Inline C => <<'END_C';
    int add(int x, int y) {
        return x + y;
    }
    static int mult(int x, int y) {
        return x * y;
    }
    double pyth(int x, int y) {
        return sqrt(add(mult(x, x), mult(y, y)));
    }
    END_C
Discussion

The program produces:

    9 + 5 = 14
    SQRT(9^2 + 5^2) = 10.295630140987
    Can't locate auto/main/mult.al in @INC ...

Every Inline function that is bound to Perl is also callable by C. You don't have to do anything special. Inline arranges it so that all the typemap code gets done by XS and is out of sight. By the time the C function receives control, everything has been converted from Perl to C.

Of course if your function manipulates the Perl Stack, you probably don't want to call it from C (unless you really know what you're doing).

If you declare a function as static, Inline won't bind it to Perl. That's why we were able to call mult() from C but the call failed from Perl.

See Also
Credits

Calling Perl from C

Problem

So now that I can call C from Perl, how do I call a Perl subroutine from an Inline C function.

Solution
    use Inline C;

    c_func_1('This is the first line');
    c_func_2('This is the second line');

    sub perl_sub_1 {
        print map "$_\n", @_;
    }

    __DATA__
    __C__

    void c_func_1(SV* text) {
        c_func_2(text);
    }

    void c_func_2(SV* text) {
        Inline_Stack_Vars;
        Inline_Stack_Push(newSVpvf("Plus an extra line"));
        Inline_Stack_Done;
        perl_call_pv("main::perl_sub_1", 0);
        Inline_Stack_Void;
    }
Discussion

Actually, this program demonstrates calling a C function which calls another C function which in turn calls a Perl subroutine.

The nice thing about Inline C functions is that you can call them from both Perl-space and C-space. That's because Inline creates a wrapper function around each C function. When you use Perl to call C you're actually calling that function's wrapper. The wrapper handles typemapping and Stack management, and then calls your C function.

The first time we call c_func_1 which calls c_func_2. The second time we call c_func_2 directly. c_func_2 calls the Perl subroutine (perl_sub_1) using the internal perl_call_pv function. It has to put arguments on the stack by hand. Since there is already one argument on the stack when we enter the function, the Inline_Stack_Push adds a second argument. Inline_Stack_Void makes sure that nothing is returned from the function.

See Also

See the Inline::C manpage for more information about Stack macros.

See the perlapi manpage for more information about the Perl5 internal API.

Credits

Evaling C

Problem

I've totally lost my marbles and I want to generate C code at run time, and eval it into Perl. How do I do this?

Solution
    use Inline;
    use Code::Generator;

    my $c_code = generate('foo_function');

    Inline->bind(C => $c_code);

    foo_function(1, 2, 3);
Discussion

I can't think of a real life application where you would want to generate C code on the fly, but at least I know know how I would do it. :)

The bind() function of Inline let's you bind (compile/load/execute) C functions at run time. It takes all of the same arguments as 'use Inline C => ...'.

The nice thing is that once a particular snippet is compiled, it remains cached so that it doesn't need to be compiled again. I can imagine that someday a mad scientist will dream up a self generating modeling system that would run faster and faster over time.

If you know such a person, have them drop me a line.

See Also
Credits

SEE ALSO

For generic information about Inline, see the Inline manpage.

For information about using Inline with C see the Inline::C manpage.

For information on supported languages and platforms see the Inline-Support manpage.

For information on writing your own Inline language support module, see the Inline-API manpage.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright (c) 2001, 2002, Brian Ingerson.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.

See http://www.perl.com/perl/misc/Artistic.html


Inline-API - How to bind a programming language to Perl using Inline.pm

  • A Skeleton
  • The Inline API
    • The register() Callback
    • The validate() Callback
    • The build() Callback
    • The load() Callback
    • The info() Callback
  • The Inline Object
    • The code Attribute
    • The language Attribute
    • The language_id Attribute
    • The module Attribute
    • The modfname Attribute
    • The modpname Attribute
    • The version Attribute
    • The pkg Attribute
    • The install_lib Attribute
    • The build_dir Attribute
    • The script Attribute
    • The location Attribute
    • The suffix Attribute
  • The Inline Namespace
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Inline-API - How to bind a programming language to Perl using Inline.pm

SYNOPSIS

    #!/usr/bin/perl

    use Inline Foo;
    say_it('foo');  # Use Foo to print "Hello, Foo"

    __Foo__
    foo-sub say_it {
        foo-my $foo = foo-shift;
        foo-print "Hello, $foo\n";
    }

DESCRIPTION

So you think Inline C is pretty cool, but what you really need is for Perl to work with the brand new programming language "Foo". Well you're in luck. Inline.pm has support for adding your own Inline Language Support Module (ILSM), like Inline::Foo.

Inline has always been intended to work with lots of different programming languages. Many of the details can be shared between implementations, so that Inline::Java has a similar interface to Inline::ASM. All of the common code is in Inline.pm.

Language specific modules like Inline::Python are subclasses of Inline.pm. They can inherit as much of the common behaviour as they want, and provide specific behaviour of their own. This usually comes in the form of Configuration Options and language specific compilation.

The Inline C support is probably the best boilerplate to copy from. Since version 0.30 all C support was isolated into the module Inline::C and the parsing grammar is further broken out into Inline::C::grammar. All of these components come with the Inline distribution.

This POD gives you all the details you need for implementing an ILSM. For further assistance, contact inline@perl.org See SEE ALSO below.

We'll examine the joke language Inline::Foo which is distributed with Inline. It actually is a full functioning ILSM. I use it in Inline's test harness to test base Inline functionality. It is very short, and can help you get your head wrapped around the Inline API.

A Skeleton

For the remainder of this tutorial, let's assume we're writing an ILSM for the ficticious language Foo. We'll call it Inline::Foo. Here is the entire (working) implementation.

    package Inline::Foo;
    use strict;
    $Inline::Foo::VERSION = '0.01';
    @Inline::Foo::ISA = qw(Inline);
    require Inline;
    use Carp;

    #===========================================================
    # Register Foo as an Inline Language Support Module (ILSM)
    #===========================================================
    sub register {
        return {
            language => 'Foo',
            aliases => ['foo'],
            type => 'interpreted',
            suffix => 'foo',
           };
    }

    #===========================================================
    # Error messages
    #===========================================================
    sub usage_config {
        my ($key) = @_;
        "'$key' is not a valid config option for Inline::Foo\n";
    }

    sub usage_config_bar {
        "Invalid value for Inline::Foo config option BAR";
    }

    #===========================================================
    # Validate the Foo Config Options
    #===========================================================
    sub validate {
        my $o = shift;
        $o->{ILSM}{PATTERN} ||= 'foo-';
        $o->{ILSM}{BAR} ||= 0;
        while (@_) {
        my ($key, $value) = splice @_, 0, 2;
        if ($key eq 'PATTERN') {
            $o->{ILSM}{PATTERN} = $value;
            next;
        }
        if ($key eq 'BAR') {
            croak usage_config_bar
              unless $value =~ /^[01]$/;
            $o->{ILSM}{BAR} = $value;
            next;
        }
        croak usage_config($key);
        }
    }

    #===========================================================
    # Parse and compile Foo code
    #===========================================================
    sub build {
        my $o = shift;
        my $code = $o->{API}{code};
        my $pattern = $o->{ILSM}{PATTERN};
        $code =~ s/$pattern//g;
        $code =~ s/bar-//g if $o->{ILSM}{BAR};
        sleep 1;             # imitate compile delay
        {
            package Foo::Tester;
            eval $code;
        }
        croak "Foo build failed:\n$@" if $@;
        my $path = "$o->{API}{install_lib}/auto/$o->{API}{modpname}";
        my $obj = $o->{API}{location};
        $o->mkpath($path) unless -d $path;
        open FOO_OBJ, "> $obj"
          or croak "Can't open $obj for output\n$!";
        print FOO_OBJ $code;
        close \*FOO_OBJ;
    }

    #===========================================================
    # Only needed for interpreted languages
    #===========================================================
    sub load {
        my $o = shift;
        my $obj = $o->{API}{location};
        open FOO_OBJ, "< $obj"
          or croak "Can't open $obj for output\n$!";
        my $code = join '', <FOO_OBJ>;
        close \*FOO_OBJ;
        eval "package $o->{API}{pkg};\n$code";
        croak "Unable to load Foo module $obj:\n$@" if $@;
    }

    #===========================================================
    # Return a small report about the Foo code.
    #===========================================================
    sub info {
        my $o = shift;
        my $text = <<'END';
    This is a small report about the Foo code. Perhaps it contains
    information about the functions the parser found which will be
    bound to Perl. It will get included in the text produced by the
    Inline 'INFO' command.
    END
        return $text;
    }

    1;

Except for load(), the subroutines in this code are mandatory for an ILSM. What they do is described below. A few things to note:

  1. Inline::Foo must be a subclass of Inline. This is accomplished with:

        @Inline::Foo::ISA = qw(Inline);

  2. The line 'require Inline;' is not necessary. But it is there to remind you not to say 'use Inline;'. This will not work.

  3. Remember, it is not valid for a user to say:

        use Inline::Foo;

    Inline.pm will detect such usage for you in its import method, which is automatically inherited since Inline::Foo is a subclass.

  4. In the build function, you normally need to parse your source code. Inline::C uses Parse::RecDescent to do this. Inline::Foo simply uses eval. (After we strip out all occurances of 'foo-').

    An alternative parsing method that works well for many ILSMs (like Java and Python) is to use the language's compiler itself to parse for you. This works as long as the compiler can be made to give back parse information.

The Inline API

This section is a more formal specification of what functionality you'll need to provide to implement an ILSM.

When Inline determines that some Foo code needs to be compiled it will automatically load your ILSM module. It will then call various subroutines which you need to supply. We'll call these subroutines "callbacks".

You will need to provide the following 5 callback subroutines.

The register() Callback

This subroutine receives no arguments. It returns a reference to a hash of ILSM meta-data. Inline calls this routine only when it is trying to detect new ILSM-s that have been installed on a given system. Here is an example of the has ref you would return for Foo:

    {
     language => 'Foo',
     aliases => ['foo'],
     type => 'interpreted',
     suffix => 'foo',
    };

The meta-data items have the following meanings:

language

This is the proper name of the language. It is usually implemented as Inline::X for a given language 'X'.

aliases

This is a reference to an array of language name aliases. The proper name of a language can only contain word characters. [A-Za-z0-9_] An alias can contain any characters except whitespace and quotes. This is useful for names like 'C++' and 'C#'.

type

Must be set to 'compiled' or 'interpreted'. Indicates the category of the language.

suffix

This is the file extension for the cached object that will be created. For 'compiled' languages, it will probably be 'so' or 'dll'. The appropriate value is in Config.pm.

For interpreted languages, this value can be whatever you want. Python uses pydat. Foo uses foo.

The validate() Callback

This routine gets passed all configuration options that were not already handled by the base Inline module. The options are passed as key/value pairs. It is up to you to validate each option and store its value in the Inline object (which is also passed in). If a particular option is invalid, you should croak with an appropriate error message.

The build() Callback

This subroutine is responsible for doing the parsing and compilation of the Foo source code. The Inline object is passed as the only argument. All pertinent information will be stored in this object. build() is required to create a cache object of a specific name, or to croak with an appropriate error message.

This is the meat of your ILSM. Since it will most likely be quite complicated, it is probably best that you study an existing ILSM like Inline::C.

The load() Callback

This method only needs to be provided for interpreted languages. It's responsibility is to start the interpreter.

For compiled languages, the load routine from Inline.pm is called which uses DynaLoader to load the shared object or DLL.

The info() Callback

This method is called when the user makes use of the INFO shortcut. You should return a string containing a small report about the Inlined code.

The Inline Object

Inline.pm creates a hash based Perl object for each section of Inlined source code it receives. This object contains lots of information about the code, the environment, and the configuration options used.

This object is a hash that is broken into several subhashes. The only two subhashes that an ILSM should use at all are $o->{API} and $o->{ILSM}. The first one contains all of the information that Inline has gather for you in order for you to create/load a cached object of your design. The second one is a repository where your ILSM can freely store data that it might need later on.

This section will describe all of the Inline object "API" attributes.

The code Attribute

This the actual source code passed in by the user. It is stored as one long string.

The language Attribute

The proper name of the language being used.

The language_id Attribute

The language name specified by the user. Could be 'C++' instead of 'CPP'.

The module Attribute

This is the shared object's file name.

The modfname Attribute

This is the shared object's file name.

The modpname Attribute

This is the shared object's installation path extension.

The version Attribute

The version of Inline.pm being used.

The pkg Attribute

The Perl package from which this invocation pf Inline was called.

The install_lib Attribute

This is the directory to write the shared object into.

The build_dir Attribute

This is the directory under which you should write all of your build related files.

The script Attribute

This is the name of the script that invoked Inline.

The location Attribute

This is the full path name of the executable object in question.

The suffix Attribute

This is the shared library extension name. (Usually 'so' or 'dll').

The Inline Namespace

Inline.pm has been set up so that anyone can write their own language support modules. It further allows anyone to write a different implementation of an existing Inline language, like C for instance. You can distribute that module on the CPAN.

If you have plans to implement and distribute an Inline module, I would ask that you please work with the Inline community. We can be reached at the Inline mailing list: inline@perl.org (Send mail to inline-subscribe@perl.org to subscribe). Here you should find the advice and assistance needed to make your module a success.

The Inline community will decide if your implementation of COBOL will be distributed as the official Inline::COBOL or should use an alternate namespace. In matters of dispute, I (Brian Ingerson) retain final authority. (and I hope not to need use of it :-) Actually modules@perl.org retains the final authority.

But even if you want to work alone, you are free and welcome to write and distribute Inline language support modules on CPAN. You'll just need to distribute them under a different package name.

SEE ALSO

For generic information about Inline, see the Inline manpage.

For information about using Inline with C see the Inline::C manpage.

For information on supported languages and platforms see the Inline-Support manpage.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Inline-FAQ - The Inline FAQ

  • General Inline
    • How disposable is a .Inline or _Inline directory?
    • Whatever happened to the SITE_INSTALL option?
    • How do I create a binary distribution using Inline?

NAME

Inline-FAQ - The Inline FAQ

DESCRIPTION

Welcome to the official Inline FAQ. In this case, FAQ means:

    Formerly Answered Questions

This is a collection of old, long-winded emails that myself and others have sent to the Inline mailing list. (inline@perl.org) They have been reviewed and edited for general Inline edification. Some of them may be related to a specific language. They are presented here in a traditional FAQ layout.

General Inline

Since there is only a handful of content so far, all FAQs are currently under this heading.

How disposable is a .Inline or _Inline directory?

I probably need to be more emphatic about the roll of _Inline/ cache directories. Since they are created automatically, they are completely disposable. I delete them all the time. And it is fine to have a different one for each project. In fact as long as you don't have ~/.Inline/ defined, Inline will create a new ./_Inline directory. You can move that to ./.Inline and it will continue to work if you want to give it more longevity and hide it from view. There is a long complicated list of rules about how [_.]Inline/ directories are used/created. But it was designed to give you the most flexibility/ease-of-use. Never be afraid to nuke 'em. They'll just pop right back next time. :)

Whatever happened to the SITE_INSTALL option?

SITE_INSTALL is gone. I was going to leave it in and change the semantics, but thought it better to remove it, so people wouldn't try to use it the old way. There is now _INSTALL_ (but you're not supposed to know that :). It works magically through the use of Inline::MakeMaker. I explained this earlier but it's worth going through again because it's the biggest change for 0.40. Here's how to 'permanently' install an Inline extension (Inline based module) with 0.40:

    1) Create a module with Inline.
    2) Test it using the normal/local _Inline/ cache.
    3) Create a Makefile.PL (like the one produced by h2xs)
    4) Change 'use ExtUtils::MakeMaker' to 'use Inline::MakeMaker'
    5) Change your 'use Inline C => DATA' to 'use Inline C => DATA => NAME
       => Foo => VERSION => 1.23'
    6) Make sure NAME matches your package name ('Foo'), or begins with
       'Foo::'.
    7) Make sure VERSION matches $Foo::VERSION. This must be a string (not a
       number) matching /^\d\.\d\d$/
    8) Do the perl/make/test/install dance (thanks binkley :)

With Inline 0.41 (or thereabouts) you can skip steps 3 & 4, and just say 'perl -MInline=INSTALL ./Foo.pm'. This will work for non-Inline modules too. It will become the defacto standard (since there is no easy standard) way of installing a Perl module. It will allow Makefile.PL parameters 'perl -MInline=INSTALL ./Foo.pm - PREFIX=/home/ingy/perl' and things like that. It will also make use of a MANIFEST if you provide one.

How do I create a binary distribution using Inline?

I've figured out how to create and install a PPM binary distribution; with or without distributing the C code! And I've decided to share it with all of you :)

NOTE: Future versions of Inline will make this process a one line command. But for now just use this simple recipe.

---

The Inline 0.40 distribution comes with a sample extension module called Math::Simple. Theoretically you could distribute this module on CPAN. It has all the necessary support for installation. You can find it in Inline-0.40/modules/Math/Simple/. Here are the steps for converting this into a binary distribution *without* C source code.

NOTE: The recipient of this binary distribution will need to have the PPM.pm module installed. This module requires a lot of other CPAN modules. ActivePerl (available for Win32, Linux, and Solaris) has all of these bundled. While ActivePerl isn't required, it makes things (a lot) easier.

1) cd Inline-0.40/Math/Simple/

2) Divide Simple.pm into two files:

    ---8<--- (Simple.pm)
    package Math::Simple;
    use strict;
    require Exporter;
    @Math::Simple::ISA = qw(Exporter);
    @Math::Simple::EXPORT = qw(add subtract);
    $Math::Simple::VERSION = '1.23';

    use Inline (C => 'src/Simple.c' =>
                NAME => 'Math::Simple',
                VERSION => '1.23',
               );
    1;
    ---8<---
    ---8<--- (src/Simple.c)
    int add (int x, int y) {
        return x + y;
    }
    int subtract (int x, int y) {
        return x - y;
    }
    ---8<---

So now you have the Perl in one file and the C in the other. The C code must be in a subdirectory.

3) Note that I also changed the term 'DATA' to the name of the C file. This will work just as if the C were still inline.

4) Run 'perl Makefile.PL'

5) Run 'make test'

6) Get the MD5 key from 'blib/arch/auto/Math/Simple/Simple.inl'

7) Edit 'blib/lib/Math/Simple.pm'. Change 'src/Simple.c' to '02c61710cab5b659efc343a9a830aa73' (the MD5 key)

8) Run 'make ppd'

9) Edit 'Math-Simple.ppd'. Fill in AUTHOR and ABSTRACT if you wish. Then change:

    <CODEBASE HREF="" />

to

    <CODEBASE HREF="Math-Simple.tar.gz" />

10) Run:

    tar cvf Math-Simple.tar blib
    gzip --best Math-Simple.tar

11) Run:

    tar cvf Math-Simple-1.23.tar Math-Simple.ppd Math-Simple.tar.gz
    gzip --best Math-Simple-1.23.tar

12) Distribute Math-Simple-1.23.tar.gz with the following instructions:

A) Run:

    gzip -d Math-Simple-1.23.tar.gz
    tar xvzf Math-Simple-1.23.tar

B) Run 'ppm install Math-Simple.ppd'

C) Delete Math-Simple.tar and Math-Simple.ppd.

D) Test with:

    perl -MMath::Simple -le 'print add(37, 42)'

---

That's it. The process should also work with zip instead of tar, but I haven't tried it.

The recipient of the binary must have Perl built with a matching architecture. Luckily, ppm will catch this.

For a binary dist *with* C source code, simply omit steps 2, 3, 6, and 7.

If this seems too hard, then in a future version you should be able to just type:

    make ppm


Inline-Support - Support Information for Inline.pm and related modules.

  • SUPPORTED LANGUAGES
  • SUPPORTED PLATFORMS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Inline-Support - Support Information for Inline.pm and related modules.

DESCRIPTION

This document contains all of the latest support information for Inline.pm and the recognized Inline Language Support Modules (ILSMs) available on CPAN.

SUPPORTED LANGUAGES

The most important language that Inline supports is C. That is because Perl itself is written in C. By giving a your Perl scripts access to C, you in effect give them access to the entire glorious internals of Perl. (Caveat scriptor :-)

As of this writing, Inline also supports:

 - C++
 - Java
 - Python
 - Tcl
 - Assembly
 - CPR
 - And even Inline::Foo! :)

Projects that I would most like to see happen in the year 2001 are:

 - Fortran
 - Ruby
 - Lisp
 - Guile
 - Bash
 - Perl4

SUPPORTED PLATFORMS

Inline::C should work anywhere that CPAN extension modules (those that use XS) can be installed, using the typical install format of:

    perl Makefile.PL
    make
    make test
    make install

It has been tested on many Unix and Windows variants.

NOTE: Inline::C requires Perl 5.005 or higher because Parse::RecDescent requires it. (Something to do with the qr operator)

Inline has been successfully tested at one time or another on the following platforms:

    Linux
    Solaris
    SunOS
    HPUX
    AIX
    FreeBSD
    OpenBSD
    BeOS
    OS X
    WinNT
    Win2K
    WinME
    Win98
    Cygwin

The Microsoft tests deserve a little more explanation. I used the following:

 Windows NT 4.0 (service pack 6)
 Perl 5.005_03 (ActiveState build 522)
 MS Visual C++ 6.0
 The "nmake" make utility (distributed w/ Visual C++)

Inline::C pulls all of its base configuration (including which make utility to use) from Config.pm. Since your MSWin32 version of Perl probably came from ActiveState (as a binary distribution) the Config.pm will indicate that nmake is the system's make utility. That is because ActiveState uses Visual C++ to compile Perl.

To install Inline.pm (or any other CPAN module) on MSWin32 w/ Visual C++, use these:

    perl Makefile.PL
    nmake
    nmake test
    nmake install

Inline has also been made to work with Mingw32/gcc on all Windows platforms. This is a free compiler for Windows. You must also use a perl built with that compiler.

The "Cygwin" test was done on a Windows 98 machine using the Cygwin Unix/Win32 porting layer software from Cygnus. The perl binary on this machine was also compiled using the Cygwin tool set (gcc). This software is freely available from http://sources.redhat.com/cygwin/

If you get Inline to work on a new platform, please send me email email. If it doesn't work, let me know as well and I'll see what can be done.

SEE ALSO

For general information about Inline see the Inline manpage.

For information about using Inline with C see the Inline::C manpage.

For sample programs using Inline with C see the Inline::C-Cookbook manpage.

For information on writing your own Inline Language Support Module, see the Inline-API manpage.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Inline::Java - Write Perl classes in Java.

  • USING THE Inline::Java MODULE
  • DEFAULT JAVA 2 SDK
  • CONFIGURATION OPTIONS
  • ENVIRONMENT VARIABLES
  • CLASSES AND OBJECTS
  • METHODS
  • MEMBER VARIABLES
  • ARRAYS
  • EXCEPTIONS
  • FILEHANDLES
  • CALLBACKS
  • STUDYING
  • TYPE CASTING
  • TYPE COERCING
  • JNI vs CLIENT/SERVER MODES
  • SHARED_JVM
  • USING Inline::Java IN A CGI
  • USING Inline::Java UNDER MOD_PERL
  • BUGS AND DEFICIENCIES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Inline::Java - Write Perl classes in Java.

SYNOPSIS

   use Inline Java => <<'END_OF_JAVA_CODE' ;
      class Pod_alu {
         public Pod_alu(){
         }

         public int add(int i, int j){
            return i + j ;
         }

         public int subtract(int i, int j){
            return i - j ;
         }
               }
            END_OF_JAVA_CODE

   my $alu = new Pod_alu() ;
   print($alu->add(9, 16) . "\n") ; # prints 25
   print($alu->subtract(9, 16) . "\n") ; # prints -7

DESCRIPTION

The Inline::Java module allows you to put Java source code directly "inline" in a Perl script or module. A Java compiler is launched and the Java code is compiled. Then Perl asks the Java classes what public methods have been defined. These classes and methods are available to the Perl program as if they had been written in Perl.

The process of interrogating the Java classes for public methods occurs the first time you run your Java code. The namespace is cached, and subsequent calls use the cached version.

USING THE Inline::Java MODULE

Inline::Java is driven by fundamentally the same idea as other Inline language modules, like Inline::C or Inline::CPP. Because Java is both compiled and interpreted, the method of getting your code is different, but overall, using Inline::Java is very similar to any other Inline language module.

This section will explain the different ways to use Inline::Java. For more details on Inline, see 'perldoc Inline'.

Basic Usage

The most basic form for using Inline::Java is:

   use Inline Java => 'Java source code' ;

Of course, you can use Perl's "here document" style of quoting to make the code slightly easier to read:

   use Inline Java => <<'END';

      Java source code goes here.
   END

The source code can also be specified as a filename, a subroutine reference (sub routine should return source code), or an array reference (array contains lines of source code). This information is detailed in 'perldoc Inline'.

In order for Inline::Java to function properly, it needs to know where to find a Java 2 SDK on your machine. This is done using one of the following techniques:

  1. Set the J2SDK configuration option to the correct directory

  2. Set the PERL_INLINE_JAVA_J2SDK environment variable to the correct directory

If none of these are specified, Inline::Java will use the Java 2 SDK that was specified a install time (see below).

DEFAULT JAVA 2 SDK

When Inline::Java was installed, the path to the Java 2 SDK that was used was stored in a file called default_j2sdk.pl that resides with the Inline::Java module. You can find this file by using the following command:

    % perl -MInline::Java=j2sdk

If you wish to permanently change the default Java 2 SDK that is used by Inline::Java, edit this file and change the value found there. If you wish use a different Java 2 SDK temporarily, see the J2SDK configuration option described below.

Additionally, you can use the following command to get the list of directories that you should put in you shared library path when using the JNI extension:

    % perl -MInline::Java=so_dirs

CONFIGURATION OPTIONS

There are a number of configuration options that dictate the behavior of Inline::Java:

J2SDK

Specifies the path to your Java 2 SDK.

   Ex: J2SDK => '/my/java/2/sdk/path'

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

PORT

Specifies the starting port number for the server. If many Inline::Java blocks are declared, the port number is incremented each time. Default is 0 (next available port number), default for SHARED_JVM mode is 7890.

   Ex: PORT => 4567

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

HOST

Specifies the host on which the JVM server is running. This option really only makes sense in SHARED_JVM mode when START_JVM is disabled.

   Ex: HOST => 'jvm.server.com'

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

BIND

Specifies the IP address on which the JVM server will be listening. By default the JVM server listens for connections on 'localhost' only.

   Ex: BIND => '192.168.1.1'
   Ex: BIND => '0.0.0.0'

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

STARTUP_DELAY

Specifies the maximum number of seconds that the Perl script will try to connect to the Java server. In other this is the delay that Perl gives to the Java server to start. Default is 15 seconds.

   Ex: STARTUP_DELAY => 20

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

CLASSPATH

Adds the specified CLASSPATH. This CLASSPATH will only be available threw the user classloader. To set the CLASSPATH globally (which is most probably what you want to do anyways), use the CLASSPATH environment variable.

   Ex: CLASSPATH => '/my/other/java/classses'
JNI

Toggles the execution mode. The default is to use the client/server mode. To use the JNI extension (you must have built it at install time though. See README and README.JNI for more information), set JNI to 1.

   Ex: JNI => 1

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

EXTRA_JAVA_ARGS, EXTRA_JAVAC_ARGS

Specify extra command line parameters to be passed to, respectively, the JVM and the Java compiler. Use with caution as some options may alter normal Inline::Java behavior.

   Ex: EXTRA_JAVA_ARGS => '-Xmx96m'

Note: EXTRA_JAVA_ARGS only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

EMBEDDED_JNI

Same as JNI, except Inline::Java expects the JVM to already be loaded and to have loaded the Perl interpreter that is running the script. This is an advanced feature that should only be need in very specific circumstances.

   Ex: EMBEDDED_JNI => 1

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM. Also, the EMBEDDED_JNI option automatically sets the JNI option.

SHARED_JVM

This mode enables mutiple processes to share the same JVM. It was created mainly in order to be able to use Inline::Java under mod_perl.

   Ex: SHARED_JVM => 1

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

START_JVM

When used with SHARED_JVM, tells Inline::Java that the JVM should already be running and that it should not attempt to start a new one. This option is useful in combination with command line interface described in the BUGS AND DEFICIENCIES section. Default is 1.

   Ex: START_JVM => 0

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

PRIVATE

In SHARED_JVM mode, makes every connection to the JVM use a different classloader so that each connection is isolated from the others.

   Ex: PRIVATE => 1

Note: This configuration option only has an effect on the first 'use Inline Java' call inside a Perl script, since all other calls make use of the same JVM.

DEBUG

Enables debugging info. Debugging now uses levels (1 through 5) that (loosely) follow these definitions:

   1 = Major program steps
   2 = Object creation/destruction
   3 = Method/member accesses + packet dumps
   4 = Everything else
   5 = Data structure dumps
   Ex: DEBUG => 2
DEBUGGER

Starts jdb, (the Java debugger) instead of the regular Java JVM. This option will also cause the Java code to be compiled using the '-g' switch for extra debugging information. EXTRA_JAVA_ARGS can be used use to pass extra options to the debugger.

   Ex: DEBUGGER => 1
WARN_METHOD_SELECT

Throws a warning when Inline::Java has to 'choose' between different method signatures. The warning states the possible choices and the signature chosen.

   Ex: WARN_METHOD_SELECT => 1
STUDY

Takes an array of Java classes that you wish to have Inline::Java learn about so that you can use them inside Perl.

   Ex: STUDY => ['java.lang.HashMap', 'my.class']
AUTOSTUDY

Makes Inline::Java automatically study unknown classes it encounters them.

   Ex: AUTOSTUDY => 1
PACKAGE

Forces Inline::Java to bind the Java code under the specified package instead of under the current (caller) package.

   Ex: PACKAGE => 'main'
NATIVE_DOUBLES

Normally, Inline::Java stringifies floating point numbers when passing them between Perl and Java. In certain cases, this can lead to loss of precision. When NATIVE_DOUBLES is set, Inline::Java will send the actual double bytes in order to preserve precision. Note: This applies only to doubles, not floats. Note: This option may not be portable and may not work properly on some platforms.

   Ex: NATIVE_DOUBLES => 1

ENVIRONMENT VARIABLES

Every configuration option listed above, with the exception of STUDY, can be specified using an environment variable named using the following convention:

   PERL_INLINE_JAVA_<option name>

For example, your can specified the JNI option usng the PERL_INLINE_JAVA_JNI environment variable.

Note that environment variables take precedence over options specified in the script itself.

Under Win32, you can also use set the PERL_INLINE_JAVA_COMMAND_COM environment variable to a true value to indicate that you are using the command.com shell. However, Inline::Java should normally be able to determine this on its own.

CLASSES AND OBJECTS

Because Java is object oriented, any interface between Perl and Java needs to support Java classes adequately.

Example:

   use Inline Java => <<'END' ;
      class Pod_1 {
         String data = "data" ;
         static String sdata = "static data" ;

         public Pod_1(){
         }

         public String get_data(){
            return data ;
         }

         public static String get_static_data(){
            return sdata ;
         }

         public void set_data(String d){
            data = d ;
         }

         private void priv(){
         }
               }
            END

   my $obj = new Pod_1 ;
   print($obj->get_data() . "\n") ; # prints data
   $obj->set_data("new data") ;
   print($obj->get_data() . "\n") ; # prints new data

Inline::Java created a new namespace called main::Pod_1 and created the following functions:

   sub main::Pod_::new { ... }
   sub main::Pod_::Pod_1 { ... }
   sub main::Pod_::get_data { ... }
   sub main::Pod_::get_sdata { ... }
   sub main::Pod_::set_data { ... }
   sub main::Pod_::DESTROY { ... }

Note that only the public methods are exported to Perl.

Inner classes are also supported, you simply need to supply a reference to an outer class object as the first parameter of the constructor:

   use Inline Java => <<'END' ;
      class Pod_2 {
         public Pod_2(){
         }

         public class Pod_2_Inner {
            public String name = "Pod_2_Inner" ;

            public Pod_2_Inner(){
            }
                     }
                  }
               END

   my $obj = new Pod_2() ;
   my $obj2 = new Pod_2::Pod_2_Inner($obj) ;
   print($obj2->{name} . "\n") ; # prints Pod_2_Inner

METHODS

In the previous example we have seen how to call a method. You can also call static methods in the following manner:

   print Pod_1->get_sdata() . "\n" ; # prints static data
   # or
   my $obj = new Pod_1() ;
   print $obj->get_sdata() . "\n" ; # prints static data

You can pass any kind of Perl scalar or any Java object to a method. It will be automatically converted to the correct type:

   use Inline Java => <<'END' ;
      class Pod_3_arg {
         public Pod_3_arg(){
         }
      }
      class Pod_3 {
         public int n ;

         public Pod_3(int i, String j, Pod_3_arg k) {
            n = i ;
         }
               }
            END

   my $obj = new Pod_3_arg() ;
   my $obj2 = new Pod_3(5, "toto", $obj) ;
   print($obj2->{n} . "\n") ; # prints 5

will work fine. These objects can be of any type, even if these types are not known to Inline::Java. This is also true for return types:

   use Inline Java => <<'END' ;
      import java.util.* ;

      class Pod_4 {
         public Pod_4(){
         }

         public HashMap get_hash(){
            HashMap h = new HashMap() ;
            h.put("key", "value") ;

            return h ;
                     }

         public String do_stuff_to_hash(HashMap h){
           return (String)h.get("key") ;
         }
               }
            END

   my $obj = new Pod_4() ;
   my $h = $obj->get_hash() ;
   print($obj->do_stuff_to_hash($h) . "\n") ; # prints value

Objects of types unknown to Perl can exist in the Perl space, you just can't call any of their methods. See the STUDYING section for more information on how to tell Inline::Java to learn about these classes.

MEMBER VARIABLES

You can also access all public member variables (static or not) from Perl. As with method arguments, the types of these variables does not need to be known to Perl:

   use Inline Java => <<'END' ;
      import java.util.* ;

      class Pod_5 {
         public int i ;
         public static HashMap hm ;

         public Pod_5(){
         }
              }
            END

   my $obj = new Pod_5() ;
   $obj->{i} = 2 ;
   print($obj->{i} . "\n") ; # prints 2
   my $hm1 = $obj->{hm} ; # instance way
   my $hm2 = $Pod_4::hm ; # static way

Note: Watch out for typos when accessing members in the static fashion, 'use strict' will not catch them since they have a package name...

ARRAYS

You can also send, receive and modify arrays. This is done simply by using Perl lists:

   use Inline Java => <<'END' ;
      import java.util.* ;

      class Pod_6 {
         public int i[] = {5, 6, 7} ;

         public Pod_6(){
         }

         public String [] f(String a[]){
            return a ;
         }

         public String [][] f(String a[][]){
            return a ;
         }
              }
            END

   my $obj = new Pod_6() ;
   my $i_2 = $obj->{i}->[2] ; # 7
   print($i_2 . "\n") ; # prints 7

   my $a1 = $obj->f(["a", "b", "c"]) ; # String []
   my $a2 = $obj->f([
      ["00", "01"],
      ["10", "11"],
   ]) ; # String [][]
   print($a2->[1]->[0] . "\n") ; # prints 10

EXCEPTIONS

You can now (as of 0.31) catch exceptions as objects when they are thrown from Java. To do this you use the regular Perl exception tools: eval and $@. A helper function named 'caught' is provided to help determine the type of the exception. Here is a example of a typical use:

   use Inline Java => <<'END' ;
      import java.util.* ;

      class Pod_9 {
         public Pod_9(boolean t) throws Exception {
            if (t){
               throw new Exception("ouch!") ;
            }
         }
      }
         END

   use Inline::Java qw(caught) ;

   eval {
           my $obj = new Pod_9(1) ;
   } ;
   if ($@){
      if (caught("java.lang.Exception")){
         my $msg = $@->getMessage() ;
         print($msg . "\n") ; # prints ouch!
      }
      else{
         # It wasn't a Java exception after all...
         die $@ ;
      }
   }

What's important to understand is that $@ actually contains a reference to the Throwable object that was thrown by Java. The getMessage() function is really a method of the java.lang.Exception class. So if Java is throwing a custom exception you have in your code, you will have access to that exception object's public methods just like any other Java object in Inline::Java. Note: Inline::Java uses eval under the hood, so it recommended that you store any exception in a temporary variable before processing it, especially f you will be calling other Inline::Java functions. It is also probably a good idea to undef $@ once you have treated a Java exception, or else the object still has a reference until $@ is reset by the next eval.

FILEHANDLES

Java filehandles (java.io.Reader, java.io.Writer, java.io.InputStream or java.io.OutputStream objects) can be wrapped the Inline::Java::Handle class to allow reading or writing from Perl. Here's an example:

   use Inline Java => <<'END' ;
      import java.io.* ;

      class Pod_91 {
         public static Reader getReader(String file) throws FileNotFoundException {
           return new FileReader(file) ;
         }
      }
         END

    my $o = Pod_91->getReader('data.txt') ;
    my $h = new Inline::Java::Handle($o) ;
    while (<$h>){
      chomp($_) ;
      print($_ . "\n") ; # prints data
    }

What's important to understand is that $@ actually contains a reference to the Throwable object that was thrown by Java. The getMessage() function is really a method of the java.lang.Exception class. So if Java is throwing a custom exception you have in your code, you will have access to that exception object's public methods just like any other Java object in Inline::Java. It is also probably a good idea to undef $@ once you have treated a Java exception, or else the object still has a reference until $@ is reset by the next eval.

CALLBACKS

See the Inline::Java::Callbacks manpage for more information on making callbacks.

STUDYING

As of version 0.21, Inline::Java can learn about other Java classes and use them just like the Java code you write inside your Perl script. In fact you are not even required to write Java code inside your Perl script anymore. Here's how to use the 'studying' function:

   use Inline (
      Java => 'STUDY',
      STUDY => ['java.util.HashMap'],
   ) ;

   my $hm = new java::util::HashMap() ;
   $hm->put("key", "value") ;
   my $val = $hm->get("key") ;
   print($val . "\n") ; # prints value

If you do not wish to put any Java code inside you Perl script, you must use the string 'STUDY' as your code. This will skip the build section.

You can also use the AUTOSTUDY option to tell Inline::Java that you wish to study all classes that it comes across:

   use Inline Java => <<'END', AUTOSTUDY => 1 ;
      import java.util.* ;

      class Pod_10 {
         public Pod_10(){
         }

         public HashMap get_hm(){
            HashMap hm = new HashMap() ;
            return hm ;
         }
               }
            END

   my $obj = new Pod_10() ;
   my $hm = $obj->get_hm() ;
   $hm->put("key", "value") ;
   my $val = $hm->get("key") ;
   print($val . "\n") ; # prints value

In this case Inline::Java intercepts the return value of the get_hm() method, sees that it's of a type that it doesn't know about (java.lang.HashMap), and immediately studies the class. After that call the java::lang::HashMap class is available to use through Perl.

In some cases you may not know which classes to study until runtime. In these cases you can use the study_classes() function:

   use Inline (
      Java => 'STUDY',
      STUDY => [],
   ) ;
   use Inline::Java qw(study_classes) ;

   study_classes(['java.util.HashMap'], undef) ;
   my $hm = new java::util::HashMap() ;
   $hm->put("key", "value") ;
   my $val = $hm->get("key") ;
   print($val . "\n") ; # prints value

The study_classes() function takes 2 arguments, a reference to an array of class names (like the STUDY configuration option) and the name of the package in which to bind those classes. If the name of the package is undefined, the classes will be bound to the current (caller) package.

Note: You can only specify the names of packages in which you have previously "used" Inline::Java.

TYPE CASTING

Sometimes you need to manipulate a Java object using a specific subtype. That's when type casting is necessary. Here's an example of this:

   use Inline (
      Java => 'STUDY',
      STUDY => ['java.util.HashMap'],
      AUTOSTUDY => 1,
   ) ;
   use Inline::Java qw(cast) ;

   my $hm = new java::util::HashMap() ;
   $hm->put('key', 'value') ;

   my $entries = $hm->entrySet()->toArray() ;
   foreach my $e (@{$entries}){
     # print($e->getKey() . "\n") ; # No!
     print(cast('java.util.Map$Entry', $e)->getKey() . "\n") ; # prints key
   }

In this case, Inline::Java knows that $e is of type java.util.HashMap$Entry. The problem is that this type is not public, and therefore we can't access the object through that type. We must cast it to a java.util.Map$Entry, which is a public interface and will allow us to access the getKey() method.

You can also use type casting to force the selection of a specific method signature for methods that have multiple signatures. See examples similar to this in the "TYPE COERCING" section below.

TYPE COERCING

Type coercing is the equivalent of casting for primitives types and arrays. It is used to force the selection if a specific method signature when Inline::Java has multiple choices. The coerce function returns a special object that can only be used when calling Java methods or assigning Java members. Here is an example:

   use Inline Java => <<'END' ;
      class Pod_101 {
         public Pod_101(){
         }

         public String f(int i){
            return "int" ;
         }

         public String f(char c){
            return "char" ;
         }
               }
            END

   my $obj = new Pod_101() ;
   print($obj->f('5') . "\n") ; # prints int

In this case, Inline::Java will call f(int i), because '5' is an integer. But '5' is a valid char as well. So to force the call of f(char c), do the following:

   use Inline::Java qw(coerce) ;
   $obj->f(coerce('char', '5')) ;
   # or
   $obj->f(Inline::Java::coerce('char', '5')) ;

The coerce function forces the selection of the matching signature. Note that the coerce must match the argument type exactly. Coercing to a class that extends the argument type will not work.

Another case where type coercing is needed is when one wants to pass an array as a java.lang.Object:

   use Inline Java => <<'END';
      class Pod_8 {
         public Object o ;
         int a[] = {1, 2, 3} ;

         public Pod_8() {
         }
               }
            END

   my $obj = new Pod_8() ;
   $obj->{o} = [1, 2, 3] ;      # No!

The reason why this will not work is simple. When Inline::Java sees an array, it checks the Java type you are trying to match it against to validate the construction of your Perl list. But in this case, it can't validate the array because you're assigning it to an Object. You must use the 3 parameter version of the coerce function to do this:

   $obj->{o} = Inline::Java::coerce(
     "java.lang.Object",
     [1, 2, 3],
     "[Ljava.lang.String;") ;

This tells Inline::Java to validate your Perl list as a String [], and then coerce it as an Object.

Here is how to construct the array type representations:

  [<type>  -> 1 dimensional <type> array
  [[<type> -> 2 dimensional <type> array
  ...
  where <type> is one of:
    B byte     S short     I int     J long
    F float    D double    C char    Z boolean
    L<class>; array of <class> objects

This is described in more detail in most Java books that talk about reflection.

But you only need to do this if you have a Perl list. If you already have a Java array reference obtained from elsewhere, you don't even need to coerce:

   $obj->{o} = $obj->{a} ;

JNI vs CLIENT/SERVER MODES

Starting in version 0.20, it is possible to use the JNI (Java Native Interface) extension. This enables Inline::Java to load the Java virtual machine as a shared object instead of running it as a stand-alone server. This brings an improvement in performance.

If you have built the JNI extension, you must enable it explicitely by doing one of the following:

  1. Set the JNI configuration option to 1

  2. Set the PERL_INLINE_JAVA_JNI environment variable to 1

Note: Inline::Java only creates one virtual machine instance. Therefore you can't use JNI for some sections and client/server for others. The first section determines the execution mode.

See README.JNI for more information about the JNI extension.

SHARED_JVM

Starting with version 0.30, the Inline::Java JVM can now be shared between multiple processes. The first process to start creates the JVM but does not shut it down on exit. All other processes can then connect as needed to the JVM. If any of these other processes where created by forking the parent process, the Inline::Java->reconnect_JVM() function must be called in the child to get a fresh connection to the JVM. Ex:

   use Inline (
      Java => <<'END',
         class Pod_11 {
            public static int i = 0 ;
            public Pod_11(){
               i++ ;
            }
         }
   END
      SHARED_JVM => 1,
   ) ;

   my $nb = 5 ;
   for (my $i = 0 ; $i < $nb ; $i++){
      if (! fork()){
         Inline::Java::reconnect_JVM() ;
         my $f = new Pod_11() ;
         exit ;
      }
   }
   sleep(5) ;

   my $f = new Pod_11() ;
   print($f->{i} . "\n") ; # prints 6

Once this code was run, each of the 6 processes will have created a different instance of the 't' class. Data can be shared between the processes by using static members in the Java code.

Note: The Java System.out stream is closed in SHARED_JVM mode.

USING Inline::Java IN A CGI

If you want to use Inline::Java in a CGI script, do the following:

   use CGI ;
   use Inline (
      Java => <<'END',
         class Pod_counter {
            public static int cnt = 0 ;
            public Pod_counter(){
               cnt++ ;
            }
         }
   END
      SHARED_JVM => 1,
      DIRECTORY => '/somewhere/your/web/server/can/write',
   ) ;

   my $c = new Pod_counter() ;
   my $q = new CGI() ;
   print
      $q->start_html() .
      "This page has been accessed " . $c->{cnt} . " times." .
      $q->end_html() ;

In this scenario, the first CGI to execute will start the JVM, but does not shut it down on exit. Subsequent CGI, since they have the SHARED_JVM option enabled, will try to connect to the already existing JVM before trying to start a new one. Therefore if the JVM happens to crash or is killed, the next CGI that runs will start a new one. The JVM will be killed when Apache is shut down.

See the BUGS AND DEFICIENCIES section if you have problems starting the SHARED_JVM server in a CGI.

USING Inline::Java UNDER MOD_PERL

Here is an example of how to use Inline::Java under mod_perl:

   use Apache2::Const qw(:common) ;
   use Inline (
      Java => <<'END',
         class Pod_counter {
            public static int cnt = 0 ;
            public Pod_counter(){
               cnt++ ;
            }
         }
   END
      SHARED_JVM => 1,
      DIRECTORY => '/somewhere/your/web/server/can/write',
   ) ;

   my $c = new Pod_counter() ;

   sub handler {
      my $r = shift ;

      my $q = new CGI ;
      print
         $q->start_html() .
         "This page has been accessed " . $c->{cnt} . " times." .
         $q->end_html() ;

      return OK ;
         }

See USING Inline::Java IN A CGI for more details.

If you are using the ModPerl::Registry manpage, make sure to use the PACKAGE configuration option to specifiy the package in which Inline::Java should bind the Java code, since the ModPerl::Registry manpage will place your code in a package with a unpredictable name.

See the BUGS AND DEFICIENCIES section if you have problems starting the SHARED_JVM server under MOD_PERL.

BUGS AND DEFICIENCIES

When reporting a bug, please do the following:

 - Put "use Inline REPORTBUG;" at the top of your code, or
   use the command line option "perl -MInline=REPORTBUG ...".
 - Run your code.
 - Follow the printed instructions.

Here are some things to watch out for:

  1. You shouldn't name any of your classes 'B', 'S', 'I', 'J', 'F', 'D', 'C', 'Z' or 'L'. These classes seem to be used internally by Java to represent the primitive types.

  2. If you upgrade Inline::Java from a previous version, be sure to delete your _Inline directory so that Inline::Java's own Java classes get rebuilt to match the Perl code.

  3. Under certain environments, i.e. CGI or mod_perl, the JVM cannot start properly because of the way these environments set up STDIN and STDOUT. In these cases, you may wish to control the JVM (in shared mode) manually using the following commands:

        % perl -MInline::Java::Server=status
    % perl -MInline::Java::Server=start
    % perl -MInline::Java::Server=stop
    % perl -MInline::Java::Server=restart

You can specify C<Inline::Java> options by setting the proper
environment variables, and you can also set the _Inline directory by using
the PERL_INLINE_JAVA_DIRECTORY environment variable.

    In addition, you may also wish to set the START_JVM option to 0 in your scripts to prevent them from trying to start their own JVM if they can't find one, thereby causing problems.

SEE ALSO

the Inline::Java::Callback manpage, the Inline::Java::PerlNatives manpage, the Inline::Java::PerlInterpreter manpage.

For information about using Inline, see the Inline manpage.

For information about other Inline languages, see the Inline-Support manpage.

Inline::Java's mailing list is <inline@perl.org>. To subscribe, send an email to <inline-subscribe@perl.org>

Inline::Java's home page is http://inline.perl.org/java/

AUTHOR

Patrick LeBoutillier <patl@cpan.org> is the author of Inline::Java.

Brian Ingerson <ingy@cpan.org> is the author of Inline.

COPYRIGHT

Copyright (c) 2001-2005, Patrick LeBoutillier.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License. See http://www.perl.com/perl/misc/Artistic.html for more details.


Inline::Java::Callback - Callback into Perl from Java.

  • CALLBACK API
  • CALLBACK CONTEXT
  • CALLBACK LOOPS
  • SELECT-STYLE CALLBACK LOOPS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Inline::Java::Callback - Callback into Perl from Java.

SYNOPSIS

   use Inline Java => <<'END' ;
      import org.perl.inline.java.* ;

      class Pod_caller extends InlineJavaPerlCaller {
         public Pod_caller() throws InlineJavaException {
         }

         public String perl()
            throws InlineJavaException, InlineJavaPerlException {

            return (String)CallPerlSub("main::perl",
               new Object [] {}) ;
                     }
                  }
               END

   my $pc = new Pod_caller() ;
   print($pc->perl() . "\n") ; # prints perl

   sub perl {
      return "perl" ;
   }

DESCRIPTION

Inline::Java::Callback allows you to call Perl functions from Java. To do this you need to create an org.perl.inline.java.InlinePerlCaller object. Here is a example of a typical use:

   use Inline Java => <<'END' ;
      import java.util.* ;
      import org.perl.inline.java.* ;

      class Pod_regexp extends InlineJavaPerlCaller {
         public Pod_regexp() throws InlineJavaException {
         }

         public boolean match(String target, String pattern)
            throws InlineJavaException {
            try {
               String m = (String)CallPerlSub("main::regexp",
                  new Object [] {target, pattern}) ;
               if (m.equals("1")){
                  return true ;
               }
                           }
                           catch (InlineJavaPerlException pe){
               // $@ is in pe.GetObject()
                           }

            return false ;
                     }
                  }
               END

   my $re = new Pod_regexp() ;
   my $match = $re->match("Inline::Java", "^Inline") ;
   print($match . "\n") ; # prints 1

   sub regexp {
      my $target = shift ;
      my $pattern = shift ;

      return ($target =~ /$pattern/) ;
         }

CALLBACK API

Here are the various methods that one can use to call into Perl:

public Object CallPerlSub(String sub, Object args[], Class cast) throws InlineJavaException, InlineJavaPerlException

Calls the specified subroutine with the supplied arguments and tries
to create an object of type 'cast' with the result.
   /* Example */
   Integer sum = (Integer)CallPerlSub("main::add", new Object [] {new Integer(5), new Integer(3)}, Integer.class) ;

   =item public Object CallPerlStaticMethod(String pkg, String method,
   Object args[], Class cast)
   throws InlineJavaException, InlineJavaPerlException

   Calls the specified static package method (using the $pkg->$method()
   notation) with the supplied arguments and tries to create an object
   of type 'cast' with the result.

   /* Example */
   Integer sum = (Integer)CallPerlStaticMethod("main", "add", new Object [] {new Integer(5), new Integer(3)}, Integer.class) ;
public Object eval(String code, Class cast) throws InlineJavaPerlException, InlineJavaException

Evaluates the given Perl code and tries to create an object
of type 'cast' with the result.
   /* Example */
   Integer sum = (Integer)eval("5 + 3", Integer.class) ;
public Object require(String module_or_file) throws InlineJavaPerlException, InlineJavaException

Requires the specified module/file by using a heuristic (currently,
checks whether or not the file exists) and calling Perl's C<require>
function using the appropriate construct.
   /* Example */
   require("Someting")

=item public Object require_file(String file)
throws InlineJavaPerlException, InlineJavaException

Requires the specified file.
   /* Example */
   require_file("./my_stuff.pl") ;
public Object require_module(String module) throws InlineJavaPerlException, InlineJavaException

Requires the specified module.
   /* Example */
   require_module("Data::Dumper") ;

Note: For all CallPerl* and eval methods, the 'cast' parameter is optional and defaults to 'String.class'.

These methods can throw 2 types of exceptions: C<InlineJavaException> and
C<InlineJavaPerlException> (both of these belong to the C<org.perl.inline.java>
package). The former designates an internal C<Inline::Java> error and the
latter indicates that the Perl callback threw an exception (die() or croak()).
The value of $@ (this can be a scalar or any valid "Inline::Java" object) can
be retreived using the GetObject() method of the C<InlineJavaPerlException>
object (if you are certain that $@ was a Perl scalar, you can use the
GetString() method).
   Z<>

CALLBACK CONTEXT

By default, callback are executed in scalar context. However if you want to call certain functions in list context, you must insert "@" in front of the function name. The result will then be passed on to Java as an Array:

   use Inline Java => <<'END' ;
      import org.perl.inline.java.* ;

      class Pod_Context {
         static private String dummy[] = {} ;

         static public String [] get_list()
            throws InlineJavaException, InlineJavaPerlException {
            InlineJavaPerlCaller pc = new InlineJavaPerlCaller() ;
            return (String [])pc.CallPerlSub("@main::list",
                null, dummy.getClass()) ;
         }
               }
            END

   sub list {
      return ('a', 'b', 'c') ;
   }

   print(Pod_Context->get_list()->[1] . "\n") ; # prints b

Note: When calling a Perl function that returns a list or array, you will need to pass the Class object for the expected array type (in this case String []). Since these Class objects are difficult to access for array types, the easiest way to do this is to create a dummy array of the desired type and call the getClass() method on that object (as seen above).

CALLBACK LOOPS

It is now possible to use callbacks from different Java threads. One of the big advantages of this is that you can now handle, for example, SWING events in Perl. Here's an example:

   use Inline Java => <<'END' ;
      import java.util.* ;
      import org.perl.inline.java.* ;
      import javax.swing.* ;
      import java.awt.event.* ;

      class Pod_Button extends InlineJavaPerlCaller
                       implements ActionListener {
         JFrame frame = null ;

         public Pod_Button() throws InlineJavaException {
            frame = new JFrame("Pod_Button") ;
            frame.setSize(100,100) ;
            JButton button = new JButton("Click Me!") ;
            frame.getContentPane().add(button) ;
            button.addActionListener(this) ;
            frame.setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE) ;
            frame.show() ;
         }

         public void actionPerformed(ActionEvent e){
            try {
               CallPerlSub("main::button_pressed", new Object [] {}) ;
            }
            catch (InlineJavaPerlException pe){
               // $@ is in pe.GetObject()
            }
            catch (InlineJavaException pe) {
               pe.printStackTrace() ;
            }
         }

         public void close(){
            frame.dispose() ;
            frame.hide() ;
            frame = null ;
         }

         public void quit(){
            System.exit(0) ;
         }
               }
            END

   my $b = new Pod_Button() ;
   $b->StartCallbackLoop() ;
   $b->close() ;

   # Maybe do some other stuff

   exit() ;      # in client-server mode, optional
   $b->quit() ;  # in JNI mode

   sub button_pressed {
      print('click!' . "\n") ; # prints click!
      $b->StopCallbackLoop() ;
   }

The StartCallbackLoop method can be called on any InlineJavaPerlCaller object and will block the current thread and allow the reception of callbacks through any InlineJavaPerlCaller that has been created by the same (current) thread. The only way to interrupt such a StartCallbackLoop method is to call the StopCallbackLoop method on any org.perl.inline.java.InlineJavaPerlCaller object that has been created by that same thread.

Also, only threads that communicate with Perl through Inline::Java are allowed to create org.perl.inline.java.InlineJavaPerlCaller objects and invoke their StartCallbackLoop / StopCallbackLoop methods.

SELECT-STYLE CALLBACK LOOPS

The disadvantage with the type of callback loop presented in the previous section is that the main portion of the Perl program is completely blocked while waiting for callbacks. In version 0.51 a new API for callback loops was introduced, allowing for callbacks to be processed much in the same fashion one uses select(2) to read data from a filehandle. Here's an example:

   use Inline Java => <<'END' ;
      import java.util.* ;
      import org.perl.inline.java.* ;
      import javax.swing.* ;
      import java.awt.event.* ;

      class Pod_Button extends InlineJavaPerlCaller
                       implements ActionListener {
         JFrame frame = null ;

         public Pod_Button() throws InlineJavaException {
            frame = new JFrame("Pod_Button") ;
            frame.setSize(100,100) ;
            JButton button = new JButton("Click Me!") ;
            frame.getContentPane().add(button) ;
            button.addActionListener(this) ;
            frame.setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE) ;
            frame.show() ;
         }

         public void actionPerformed(ActionEvent e){
            try {
               CallPerlSub("main::button_pressed", new Object [] {}) ;
            }
            catch (InlineJavaPerlException pe){
               // $@ is in pe.GetObject()
            }
            catch (InlineJavaException pe) {
               pe.printStackTrace() ;
            }
         }

         public void close(){
            frame.dispose() ;
            frame.hide() ;
            frame = null ;
         }

         public void quit(){
            System.exit(0) ;
         }
               }
            END

   my $b = new Pod_Button() ;
   $b->OpenCallbackStream() ;
   while ((my $rc = $b->WaitForCallback(5)) > -1){
      if ($rc > 0){
         # A callback is pending, we must process it.
         $b->ProcessNextCallback() ;
      }
      else {
         # A timeout has occured after, in this case, 5 secs.
         print "5 seconds have passed, still waiting for callback...\n" ;
         # Maybe do some other stuff
      }
   }
   $b->close() ;

   # Maybe do some other stuff

   exit() ;      # in client-server mode, optional
   $b->quit() ;  # in JNI mode

   sub button_pressed {
      print('click!' . "\n") ; # prints click!
      $b->CloseCallbackStream() ;
   }

The StartCallbackStream method can be called on any InlineJavaPerlCaller object to initialize a channel to receive callbacks. The WaitForCallback method can then be called with a float timeout value (-1 means wait forever, 0 means return immediately). The WaitForCallback method can return:

   rc  >  0, indicating that rc callbacks are waiting to be processed
   rc ==  0, indicating that a timeout has occured and no callbacks are waiting
   rc == -1, indicating that the callback stream has been closed

The callback stream can be closed by calling CloseCallbackStream, which works similarly to the StopCallbackLoop method used in the previous section.

Also, the restrictions regarding thread communication stated in the previous section are valid in this case as well.

SEE ALSO

the Inline::Java manpage, the Inline::Java::PerlNatives manpage, the Inline::Java::PerlInterpreter manpage.

AUTHOR

Patrick LeBoutillier <patl@cpan.org> is the author of Inline::Java.

Brian Ingerson <ingy@cpan.org> is the author of Inline.

COPYRIGHT

Copyright (c) 2001-2004, Patrick LeBoutillier.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License. See http://www.perl.com/perl/misc/Artistic.html for more details.


JSON - parse and convert to JSON.

  • TRANSITION PLAN
  • DESCRIPTION
  • METHODS
  • MAPPING
  • PRETTY PRINTING
  • AUTOCONVERT
  • UNMAPPING OPTION
  • BARE KEY OPTION
  • SINGLE QUOTATION OPTION
  • HASH KEY SORT ORDER
  • BLESSED OBJECT
  • UTF8
  • CONVERT WITH SINGLE QUOTES
  • EXPORT
  • TODO
  • SEE ALSO
  • ACKNOWLEDGEMENTS
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

JSON - parse and convert to JSON (JavaScript Object Notation).

SYNOPSIS

 use JSON;

 $obj = {
    id   => ["foo", "bar", { aa => 'bb'}],
    hoge => 'boge'
 };

 $js  = objToJson($obj);
 # this is {"id":["foo","bar",{"aa":"bb"}],"hoge":"boge"}.
 $obj = jsonToObj($js);
 # the data structure was restored.

 # OOP

 my $json = new JSON;

 $obj = {id => 'foo', method => 'echo', params => ['a','b']};
 $js  = $json->objToJson($obj);
 $obj = $json->jsonToObj($js);

 # pretty-printing
 $js = $json->objToJson($obj, {pretty => 1, indent => 2});

 $json = JSON->new(pretty => 1, delimiter => 0);
 $json->objToJson($obj);

TRANSITION PLAN

In the next large update version, JSON and JSONRPC modules are split.

  JSON::Parser and JSON::Converter are deleted from JSON dist.
  JSON and JSON::PP in JSON dist.
  JSON becomes wrapper to JSON::XS and/or JSON::PP.
  JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
  JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
  Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.

DESCRIPTION

This module converts between JSON (JavaScript Object Notation) and Perl data structure into each other. For JSON, See to http://www.crockford.com/JSON/.

METHODS

new()
new( %options )

returns a JSON object. The object delegates the converting and parsing process to the JSON::Converter manpage and the JSON::Parser manpage.

 my $json = new JSON;

new can take some options.

 my $json = new JSON (autoconv => 0, pretty => 1);

Following options are supported:

autoconv

See AUTOCONVERT for more info.

skipinvalid

objToJson() does die() when it encounters any invalid data (for instance, coderefs). If skipinvalid is set with true, the function convets these invalid data into JSON format's null.

execcoderef

objToJson() does die() when it encounters any code reference. However, if execcoderef is set with true, executes the coderef and uses returned value.

pretty

See PRETTY PRINTING for more info.

indent

See PRETTY PRINTING for more info.

delimiter

See PRETTY PRINTING for more info.

keysort

See HASH KEY SORT ORDER for more info.

convblessed

See BLESSED OBJECT for more info.

selfconvert

See BLESSED OBJECT for more info.

singlequote

See CONVERT WITH SINGLE QUOTES for more info.

objToJson( $object )
objToJson( $object, $hashref )

takes perl data structure (basically, they are scalars, arrayrefs and hashrefs) and returns JSON formated string.

 my $obj = [1, 2, {foo => bar}];
 my $js  = $json->objToJson($obj);
 # [1,2,{"foo":"bar"}]

By default, returned string is one-line. However, you can get pretty-printed data with pretty option. Please see below PRETTY PRINTING.

 my $js  = $json->objToJson($obj, {pretty => 1, indent => 2});
 # [
 #   1,
 #   2,
 #   {
 #     "foo" : "bar"
 #   }
 # ]
jsonToObj( $js )

takes a JSON formated data and returns a perl data structure.

autoconv()
autoconv($bool)

This is an accessor to autoconv. See AUTOCONVERT for more info.

pretty()
pretty($bool)

This is an accessor to pretty. It takes true or false. When prrety is true, objToJson() returns prrety-printed string. See PRETTY PRINTING for more info.

indent()
indent($integer)

This is an accessor to indent. See PRETTY PRINTING for more info.

delimiter()

This is an accessor to delimiter. See PRETTY PRINTING for more info.

unmapping()
unmapping($bool)

This is an accessor to unmapping. See UNMAPPING OPTION for more info.

keysort()
keysort($coderef)

This is an accessor to keysort. See HASH KEY SORT ORDER for more info.

convblessed()
convblessed($bool)

This is an accessor to convblessed. See BLESSED OBJECT for more info.

selfconvert()
selfconvert($bool)

This is an accessor to selfconvert. See BLESSED OBJECT for more info.

singlequote()
singlequote($bool)

This is an accessor to singlequote. See CONVERT WITH SINGLE QUOTES for more info.

MAPPING

 (JSON) {"param" : []}
 ( => Perl) {'param' => []};

 (JSON) {"param" : {}}
 ( => Perl) {'param' => {}};

 (JSON) {"param" : "string"}
 ( => Perl) {'param' => 'string'};

 JSON {"param" : null}
  => Perl {'param' => bless( {'value' => undef}, 'JSON::NotString' )};
  or {'param' => undef}

 (JSON) {"param" : true}
 ( => Perl) {'param' => bless( {'value' => 'true'}, 'JSON::NotString' )};
  or {'param' => 1}

 (JSON) {"param" : false}
 ( => Perl) {'param' => bless( {'value' => 'false'}, 'JSON::NotString' )};
  or {'param' => 2}

 (JSON) {"param" : 0xff}
 ( => Perl) {'param' => 255};

 (JSON) {"param" : 010}
 ( => Perl) {'param' => 8};

These JSON::NotString objects are overloaded so you don't care about. Since 1.00, UnMapping option is added. When that option is set, {"param" : null} will be converted into {'param' => undef}, insted of {'param' => bless( {'value' => undef}, 'JSON::NotString' )}.

Perl's undef is converted to 'null'.

PRETTY PRINTING

If you'd like your JSON output to be pretty-printed, pass the pretty parameter to objToJson(). You can affect the indentation (which defaults to 2) by passing the indent parameter to objToJson().

  my $str = $json->objToJson($obj, {pretty => 1, indent => 4});

In addition, you can set some number to delimiter option. The available numbers are only 0, 1 and 2. In pretty-printing mode, when delimiter is 1, one space is added after ':' in object keys. If delimiter is 2, it is ' : ' and 0 is ':' (default is 2). If you give 3 or more to it, the value is taken as 2.

AUTOCONVERT

By default, $JSON::AUTOCONVERT is true.

 (Perl) {num => 10.02}
 ( => JSON) {"num" : 10.02}

it is not {"num" : "10.02"}.

But set false value with $JSON::AUTOCONVERT:

 (Perl) {num => 10.02}
 ( => JSON) {"num" : "10.02"}

it is not {"num" : 10.02}.

You can explicitly sepcify:

 $obj = {
    id     => JSON::Number(10.02),
    bool1  => JSON::True,
    bool2  => JSON::False,
    noval  => JSON::Null,
 };

 $json->objToJson($obj);
 # {"noval" : null, "bool2" : false, "bool1" : true, "id" : 10.02}

JSON::Number() returns undef when an argument invalid format.

UNMAPPING OPTION

By default, $JSON::UnMapping is false and JSON::Parser converts null, true, false into JSON::NotString objects. You can set true into $JSON::UnMapping to stop the mapping function. In that case, JSON::Parser will convert null, true, false into undef, 1, 0.

BARE KEY OPTION

You can set a true value into $JSON::BareKey for JSON::Parser to parse bare keys of objects.

 local $JSON::BareKey = 1;
 $obj = jsonToObj('{foo:"bar"}');

SINGLE QUOTATION OPTION

You can set a true value into $JSON::QuotApos for JSON::Parser to parse any keys and values quoted by single quotations.

 local $JSON::QuotApos = 1;
 $obj = jsonToObj(q|{"foo":'bar'}|);
 $obj = jsonToObj(q|{'foo':'bar'}|);

With $JSON::BareKey:

 local $JSON::BareKey  = 1;
 local $JSON::QuotApos = 1;
 $obj = jsonToObj(q|{foo:'bar'}|);

HASH KEY SORT ORDER

By default objToJSON will serialize hashes with their keys in random order. To control the ordering of hash keys, you can provide a standard 'sort' function that will be used to control how hashes are converted.

You can provide either a fully qualified function name or a CODEREF to $JSON::KeySort or $obj->keysort.

If you give any integers (excluded 0), the sort function will work as:

 sub { $a cmp $b }

Note that since the sort function is external to the JSON module the magical $a and $b arguments will not be in the same package. In order to gain access to the sorting arguments, you must either:

  o use the ($$) prototype (slow)
  o Fully qualify $a and $b from the JSON::Converter namespace

See the documentation on sort for more information.

 local $JSON::KeySort = 'My::Package::sort_function';

 or
 local $JSON::KeySort = \&_some_function;

 sub sort_function {
    $JSON::Converter::a cmp $JSON::Converter::b;
 }

 or
 sub sort_function ($$) {
    my ($a, $b) = @_;

    $a cmp $b
 }

BLESSED OBJECT

By default, JSON::Converter doesn't deal with any blessed object (returns undef or null in the JSON format). If you use $JSON::ConvBlessed or convblessed option, the module can convert most blessed object (hashref or arrayref).

  local $JSON::ConvBlessed = 1;
  print objToJson($blessed);

This option slows down the converting speed.

If you use $JSON::SelfConvert or selfconvert option, the module will test for a toJson() method on the object, and will rely on this method to obtain the converted value of the object.

UTF8

You can set a true value into $JSON::UTF8 for JSON::Parser and JSON::Converter to set UTF8 flag into strings contain utf8.

CONVERT WITH SINGLE QUOTES

You can set a true value into $JSON::SingleQuote for JSON::Converter to quote any keys and values with single quotations.

You want to parse single quoted JSON data, See SINGLE QUOTATION OPTION.

EXPORT

objToJson, jsonToObj.

TODO

Which name is more desirable? JSONRPC or JSON::RPC.

SingleQuote and QuotApos...

SEE ALSO

http://www.crockford.com/JSON/, the JSON::Parser manpage, the JSON::Converter manpage

If you want the speed and the saving of memory usage, check the JSON::Syck manpage.

ACKNOWLEDGEMENTS

I owe most JSONRPC idea to the XMLRPC::Lite manpage and the SOAP::Lite manpage.

SHIMADA pointed out many problems to me.

Mike Castle <dalgoda[at]ix.netcom.com> suggested better packaging way.

Jeremy Muhlich <jmuhlich[at]bitflood.org> help me escaped character handling in JSON::Parser.

Adam Sussman <adam.sussman[at]ticketmaster.com> suggested the octal and hexadecimal formats as number. Sussman also sent the 'key sort' and 'hex number autoconv' patch and 'HASH KEY SORT ORDER' section.

Tatsuhiko Miyagawa <miyagawa[at]bulknews.net> taught a terrible typo and gave some suggestions.

David Wheeler <david[at]kineticode.com> suggested me supporting pretty-printing and gave a part of PRETTY PRINTING.

Rusty Phillips <rphillips[at]edats.com> suggested me supporting the query object other than CGI.pm for JSONRPC::Transport::HTTP::CGI.

Felipe Gasper <gasperfm[at]uc.edu> pointed to a problem of JSON::NotString with undef. And show me patches for 'bare key option' & 'single quotation option'.

Yaman Saqqa <abulyomon[at]gmail.com> helped my decision to support the bare key option.

Alden DoRosario <adorosario[at]chitika.com> tought JSON::Conveter::_stringfy (<= 0.992) is very slow.

Brad Baxter sent to 'key sort' patch and thought a bug in JSON.

Jacob and Jay Buffington sent 'blessed object conversion' patch.

Thanks to Peter Edwards, IVAN, and all testers for bug reports.

Yann Kerherve sent 'selfconverter' patch(code, document and test).

Annocpan users comment on JSON pod. See http://annocpan.org/pod/JSON

And Thanks very much to JSON by JSON.org (Douglas Crockford) and JSON-RPC by http://json-rpc.org/

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005-2007 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/JSON/Converter.pm

  • METHODs
  • COPYRIGHT
  • SEE ALSO

METHODs

objToJson

convert a passed perl data structure into JSON object. can't parse bleesed object by default.

hashToJson

convert a passed hash into JSON object.

arrayToJson

convert a passed array into JSON array.

valueToJson

convert a passed data into a string of JSON.

COPYRIGHT

makamaka [at] donzoko.net

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the JSON manpage, http://www.crockford.com/JSON/index.html


JSON::PP - An experimental JSON::XS compatible Pure Perl module.

    • FEATURES
  • FUNCTIONS
  • METHODS
  • MAPPING
  • COMPARISON
  • TODO
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

JSON::PP - An experimental JSON::XS compatible Pure Perl module.

SYNOPSIS

 use JSON::PP;

 $obj       = from_json($json_text);
 $json_text = to_json($obj);

 # or

 $obj       = jsonToObj($json_text);
 $json_text = objToJson($obj);

 $json = new JSON;
 $json_text = $json->ascii->pretty($obj);

 # you can set options to functions.

 $json_text = to_json($obj, {ascii => 1, intend => 2});
 $obj       = from_json($json_text, {utf8 => 0});

DESCRIPTION

This module is the JSON::XS manpage compatible Pure Perl module. ( Perl better than 5.008 is recommended)

Module variables ($JSON::*) were abolished.

JSON::PP will be renamed JSON (JSON-2.0).

Many things including error handling are learned from the JSON::XS manpage. For t/02_error.t compatible, error messages was copied partially from JSON::XS.

FEATURES

  • perhaps correct unicode handling

    This module knows how to handle Unicode (perhaps), but not yet documents how and when it does so.

    In Perl5.6x, Unicode handling requires the Unicode::String manpage module.

    Perl 5.005_xx, Unicode handling is disable currenlty.

  • round-trip integrity

    This module solved the problem pointed out by JSON::XS using the B manpage module.

  • strict checking of JSON correctness

    I want to bring close to XS. How do you want to carry out?

    you can set strict decoding method.

  • slow

    Compared to other JSON modules, this module does not compare favourably in terms of speed. Very slowly!

  • simple to use

    This module became very simple. Since its interface were anyway made the same as JSON::XS.

  • reasonably versatile output formats

    See to the JSON::XS manpage.

FUNCTIONS

to_json

See to JSON::XS. objToJson is an alias.

from_json

See to JSON::XS. jsonToObj is an alias.

JSON::true

Returns JSON true value which is blessed object. It isa JSON::Literal object.

JSON::false

Returns JSON false value which is blessed object. It isa JSON::Literal object.

JSON::null

Returns JSON null value which is blessed object. It isa JSON::Literal object.

METHODS

new

Returns JSON::PP object.

ascii

See to JSON::XS.

In Perl 5.6, this method requires the Unicode::String manpage. If you don't have Unicode::String, the method is always set to false and warns.

In Perl 5.005, this option is currently disable.

latin1

See to JSON::XS.

In Perl 5.6, this method requires the Unicode::String manpage. If you don't have Unicode::String, the method is always set to false and warns.

In Perl 5.005, this option is currently disable.

utf8

See to JSON::XS.

Currently this module always handles UTF-16 as UTF-16BE.

pretty

See to JSON::XS.

indent

See to JSON::XS. Strictly, this module does not carry out equivalent to XS.

 $json->indent(4);

is not the same as this:

 $json->indent();
space_before

See to JSON::XS.

space_after

See JSON::XS.

canonical

See to JSON::XS. Strictly, this module does not carry out equivalent to XS. This method can take a subref for sorting (see to the JSON manpage).

allow_nonref

See to JSON::XS.

shrink

Not yet implemented.

max_depth

See to JSON::XS. Strictly, this module does not carry out equivalent to XS. By default, not 512 (JSON::XS) but 32.

encode

See to JSON::XS.

decode

See to JSON::XS. In Perl 5.6, if you don't have Unicode::String, the method can't handle UTF-16(BE) char and returns as is.

property

Accessor.

 $json->property(utf8 => 1); # $json->utf8(1);

 $value = $json->property('utf8'); # returns 1.
self_encode

See BLESSED OBJECT in the JSON manpage's self convert function.

disable_UTF8

If this option is set, UTF8 flag in strings generated by encode/decode is off.

allow_tied

Enable.

This option will be obsoleted.

singlequote

Allows to decode single quoted strings.

Unlike the JSON manpage module, this module does not encode Perl string into single quoted string any longer.

allow_barekey

Allows to decode bare key of member.

allow_bigint

When json text has any integer in decoding more than Perl can't handle, If this option is on, they are converted into the Math::BigInt manpage objects.

strict

For JSON format, unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid and JSON::XS decodes just like that. While this module can deocde thoese. But if this option is set, the module strictly decodes.

escape_slash

By default, JSON::PP encodes strings without escaping slash (U+002F). Setting the option to escape slash.

literal_value

MAPPING

COMPARISON

Using a benchmark program in the JSON::XS (v1.11) distribution.

 module     |     encode |     decode |
 -----------|------------|------------|
 JSON::PP   |  11092.260 |   4482.033 |
 -----------+------------+------------+
 JSON::XS   | 341513.380 | 226138.509 |
 -----------+------------+------------+

In case t/12_binary.t (JSON::XS distribution). (shrink of JSON::PP has no effect.)

JSON::PP takes 147 (sec).

JSON::XS takes 4.

TODO

Document!

It is troublesome.

clean up

Under the cleaning.

SEE ALSO

the JSON manpage, the JSON::XS manpage

RFC4627

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


JSON::PP5005 - Helper module in using JSON::PP in Perl 5.005

  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

JSON::PP5005 - Helper module in using JSON::PP in Perl 5.005

DESCRIPTION

JSON::PP calls internally.

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


JSON::PP56 - Helper module in using JSON::PP in Perl 5.6

  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

JSON::PP56 - Helper module in using JSON::PP in Perl 5.6

DESCRIPTION

JSON::PP calls internally.

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2007 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/JSON/Parser.pm

  • SEE ALSO
  • COPYRIGHT

SEE ALSO

http://www.crockford.com/JSON/index.html

This module is an implementation of http://www.crockford.com/JSON/json.js.

COPYRIGHT

makamaka [at] donzoko.net

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


JSONRPC - Perl implementation of JSON-RPC protocol

  • TRANSITION PLAN
  • DESCRIPTION
  • METHOD
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

 JSONRPC - Perl implementation of JSON-RPC protocol

SYNOPSIS

 #--------------------------
 # In your application class
 package MyApp;

 sub own_method { # called by clients
     my ($server, @params) = @_; # $server is JSONRPC object.
     ...
     # return a scalar value or a hashref or an arryaref.
 }

 #--------------------------
 # In your main cgi script.
 use JSONRPC::Transport::HTTP;
 use MyApp;

 # a la XMLRPC::Lite
 JSONRPC::Transport::HTTP::CGI->dispatch_to('MyApp')->handle();

 #--------------------------
 # Client version
 use JSONRPC::Transport::HTTP;
 my $uri = 'http://www.example.com/MyApp/Test/';

 my $res = JSONRPC::Transport::HTTP
            ->proxy($uri)
            ->call('echo',['This is test.'])
            ->result;

 if($res->error){
   print $res->error,"\n";
 }
 else{
   print $res->result,"\n";
 }

 # or

 my $client = JSONRPC::Transport::HTTP->proxy($uri);

 print $client->echo('This is test.'); # the alias, _echo is same.

TRANSITION PLAN

In the next large update version, JSON and JSONRPC modules are split.

  JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
  JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
  Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.

DESCRIPTION

This module implementes JSON-RPC (http://json-rpc.org/) server and client. Most ideas were borrowed from the XMLRPC::Lite manpage. Currently JSONRPC provides CGI server function.

METHOD

dispatch_to
handle
jsonParser

The accessor of a JSON::Parser object.

 my $srv = JSONRPC::Transport::HTTP::CGI->new;
 $srv->jsonParser->{unmapping} = 1;
jsonConverter

The accessor of a JSON::Converter object.

proxy($uri,[$proxy_uri])

takes a service uri and optional proxy uri. returns a client object.

SEE ALSO

the JSONRPC::Transport::HTTP manpage the JSON manpage the XMLRPC::Lite manpage http://json-rpc.org/

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005-2007 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/JSONRPC/Transport/HTTP.pm

  • TRANSITION PLAN
  • DESCRIPTION
  • CHARSET
  • QUERY OBJECT
  • CAUTION
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

JSONRPC::Transport::HTTP

SYNOPSIS

 #--------------------------
 # In your application class
 package MyApp;

 sub own_method { # called by clients
     my ($server, @params) = @_; # $server is JSONRPC object.
     ...
     # return a scalar value or a hashref or an arryaref.
 }

 #--------------------------
 # In your main cgi script.
 use JSONRPC::Transport::HTTP;
 use MyApp;

 # a la XMLRPC::Lite
 JSONRPC::Transport::HTTP::CGI->dispatch_to('MyApp')->handle();

 ##################
 # Daemon version #
 ##################

 use strict;
 use lib qw(. ./lib);
 use JSONRPC::Transport::HTTP;

 my $daemon = JSONRPC::Transport::HTTP::Daemon
        ->new(LocalPort => 8080)
        ->dispatch_to('MyApp/Test', 'MyApp/Test2');

 $daemon->handle();

 ##################
 # Apache version #
 ##################

 http.conf or .htaccess
   SetHandler  perl-script
   PerlHandler Apache::JSONRPC
   PerlModule  MyApp::Test
   PerlSetVar  dispatch_to "MyApp::Test, MyApp/Test2/"
 #--------------------------
 # Client
 #--------------------------

 use JSONRPC::Transport::HTTP;
 my $uri = 'http://www.example.com/MyApp/Test/';

 my $res = JSONRPC::Transport::HTTP
            ->proxy($uri)
            ->call('echo',['This is test.'])
            ->result;

 if($res->error){
   print $res->error,"\n";
 }
 else{
   print $res->result,"\n";
 }

 # or

 my $client = JSONRPC::Transport::HTTP->proxy($uri);

 print $client->echo('This is test.'); # the alias, _echo is same.

TRANSITION PLAN

In the next large update version, JSON and JSONRPC modules are split.

  JSONRPC* and Apache::JSONRPC are deleted from JSON dist.
  JSONRPC::Client, JSONRPC::Server and JSONRPC::Procedure in JSON::RPC dist.
  Modules in JSON::RPC dist supports JSONRPC protocol v1.1 and 1.0.

DESCRIPTION

This module is the JSONRPC manpage subclass. Most ideas were borrowed from the XMLRPC::Lite manpage. Currently JSONRPC provides only CGI server function.

CHARSET

When the module returns response, its charset is UTF-8 by default. You can change it via passing a key/value pair into handle().

 my %charset = (charset => 'EUC-JP');
 JSONRPC::Transport::HTTP::CGI->dispatch_to('MyApp')->handle(%charset);

QUERY OBJECT

If you want to use any other query object instead of CGI for JSONRPC::Transport::HTTP::CGI, you can pass query option and paramName.

 my %opt = (
   query     => $session, # CGI::Session object
   paramName => 'json',
 );

 JSONRPC::Transport::HTTP::CGI->dispatch_to('MyApp')->handle(%opt);

CAUTION

JSONRPC::Transport::HTTP::CGI requires CGI.pm which version is more than 2.9.2. (the core module in Perl 5.8.1.)

Since verion 1.0, JSONRPC::Transport::HTTP requires the HTTP::Request manpage and the HTTP::Response manpage. For using JSONRPC::Transport::HTTP::Client, you need the LWP::UserAgent manpage.

SEE ALSO

the JSONRPC manpage the JSON manpage the XMLRPC::Lite manpage http://json-rpc.org/

AUTHOR

Makamaka Hannyaharamitu, <makamaka[at]cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Makamaka Hannyaharamitu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


LWP - The World-Wide Web library for Perl

  • HTTP STYLE COMMUNICATION
    • The Request Object
    • The Response Object
    • The User Agent
    • An Example
  • NETWORK SUPPORT
    • HTTP Requests
    • HTTPS Requests
    • FTP Requests
    • News Requests
    • Gopher Request
    • File Request
    • Mailto Request
    • CPAN Requests
  • OVERVIEW OF CLASSES AND PACKAGES
  • MORE DOCUMENTATION
  • ENVIRONMENT
  • AUTHORS
  • COPYRIGHT
  • AVAILABILITY

NAME

LWP - The World-Wide Web library for Perl

SYNOPSIS

  use LWP;
  print "This is libwww-perl-$LWP::VERSION\n";

DESCRIPTION

The libwww-perl collection is a set of Perl modules which provides a simple and consistent application programming interface (API) to the World-Wide Web. The main focus of the library is to provide classes and functions that allow you to write WWW clients. The library also contain modules that are of more general use and even classes that help you implement simple HTTP servers.

Most modules in this library provide an object oriented API. The user agent, requests sent and responses received from the WWW server are all represented by objects. This makes a simple and powerful interface to these services. The interface is easy to extend and customize for your own needs.

The main features of the library are:

  • Contains various reusable components (modules) that can be used separately or together.

  • Provides an object oriented model of HTTP-style communication. Within this framework we currently support access to http, https, gopher, ftp, news, file, and mailto resources.

  • Provides a full object oriented interface or a very simple procedural interface.

  • Supports the basic and digest authorization schemes.

  • Supports transparent redirect handling.

  • Supports access through proxy servers.

  • Provides parser for robots.txt files and a framework for constructing robots.

  • Supports parsing of HTML forms.

  • Implements HTTP content negotiation algorithm that can be used both in protocol modules and in server scripts (like CGI scripts).

  • Supports HTTP cookies.

  • Some simple command line clients, for instance lwp-request and lwp-download.

HTTP STYLE COMMUNICATION

The libwww-perl library is based on HTTP style communication. This section tries to describe what that means.

Let us start with this quote from the HTTP specification document <URL:http://www.w3.org/pub/WWW/Protocols/>:

The HTTP protocol is based on a request/response paradigm. A client establishes a connection with a server and sends a request to the server in the form of a request method, URI, and protocol version, followed by a MIME-like message containing request modifiers, client information, and possible body content. The server responds with a status line, including the message's protocol version and a success or error code, followed by a MIME-like message containing server information, entity meta-information, and possible body content.

What this means to libwww-perl is that communication always take place through these steps: First a request object is created and configured. This object is then passed to a server and we get a response object in return that we can examine. A request is always independent of any previous requests, i.e. the service is stateless. The same simple model is used for any kind of service we want to access.

For example, if we want to fetch a document from a remote file server, then we send it a request that contains a name for that document and the response will contain the document itself. If we access a search engine, then the content of the request will contain the query parameters and the response will contain the query result. If we want to send a mail message to somebody then we send a request object which contains our message to the mail server and the response object will contain an acknowledgment that tells us that the message has been accepted and will be forwarded to the recipient(s).

It is as simple as that!

The Request Object

The libwww-perl request object has the class name HTTP::Request. The fact that the class name uses HTTP:: as a prefix only implies that we use the HTTP model of communication. It does not limit the kind of services we can try to pass this request to. For instance, we will send HTTP::Requests both to ftp and gopher servers, as well as to the local file system.

The main attributes of the request objects are:

  • The method is a short string that tells what kind of request this is. The most common methods are GET, PUT, POST and HEAD.

  • The uri is a string denoting the protocol, server and the name of the "document" we want to access. The uri might also encode various other parameters.

  • The headers contain additional information about the request and can also used to describe the content. The headers are a set of keyword/value pairs.

  • The content is an arbitrary amount of data.

The Response Object

The libwww-perl response object has the class name HTTP::Response. The main attributes of objects of this class are:

  • The code is a numerical value that indicates the overall outcome of the request.

  • The message is a short, human readable string that corresponds to the code.

  • The headers contain additional information about the response and describe the content.

  • The content is an arbitrary amount of data.

Since we don't want to handle all possible code values directly in our programs, a libwww-perl response object has methods that can be used to query what kind of response this is. The most commonly used response classification methods are:

is_success()

The request was was successfully received, understood or accepted.

is_error()

The request failed. The server or the resource might not be available, access to the resource might be denied or other things might have failed for some reason.

The User Agent

Let us assume that we have created a request object. What do we actually do with it in order to receive a response?

The answer is that you pass it to a user agent object and this object takes care of all the things that need to be done (like low-level communication and error handling) and returns a response object. The user agent represents your application on the network and provides you with an interface that can accept requests and return responses.

The user agent is an interface layer between your application code and the network. Through this interface you are able to access the various servers on the network.

The class name for the user agent is LWP::UserAgent. Every libwww-perl application that wants to communicate should create at least one object of this class. The main method provided by this object is request(). This method takes an HTTP::Request object as argument and (eventually) returns a HTTP::Response object.

The user agent has many other attributes that let you configure how it will interact with the network and with your application.

  • The timeout specifies how much time we give remote servers to respond before the library disconnects and creates an internal timeout response.

  • The agent specifies the name that your application should use when it presents itself on the network.

  • The from attribute can be set to the e-mail address of the person responsible for running the application. If this is set, then the address will be sent to the servers with every request.

  • The parse_head specifies whether we should initialize response headers from the <head> section of HTML documents.

  • The proxy and no_proxy attributes specify if and when to go through a proxy server. <URL:http://www.w3.org/pub/WWW/Proxies/>

  • The credentials provide a way to set up user names and passwords needed to access certain services.

Many applications want even more control over how they interact with the network and they get this by sub-classing LWP::UserAgent. The library includes a sub-class, LWP::RobotUA, for robot applications.

An Example

This example shows how the user agent, a request and a response are represented in actual perl code:

  # Create a user agent object
  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->agent("MyApp/0.1 ");

  # Create a request
  my $req = HTTP::Request->new(POST => 'http://search.cpan.org/search');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('query=libwww-perl&mode=dist');

  # Pass request to the user agent and get a response back
  my $res = $ua->request($req);

  # Check the outcome of the response
  if ($res->is_success) {
      print $res->content;
  }
  else {
      print $res->status_line, "\n";
  }

The $ua is created once when the application starts up. New request objects should normally created for each request sent.

NETWORK SUPPORT

This section discusses the various protocol schemes and the HTTP style methods that headers may be used for each.

For all requests, a "User-Agent" header is added and initialized from the $ua->agent attribute before the request is handed to the network layer. In the same way, a "From" header is initialized from the $ua->from attribute.

For all responses, the library adds a header called "Client-Date". This header holds the time when the response was received by your application. The format and semantics of the header are the same as the server created "Date" header. You may also encounter other "Client-XXX" headers. They are all generated by the library internally and are not received from the servers.

HTTP Requests

HTTP requests are just handed off to an HTTP server and it decides what happens. Few servers implement methods beside the usual "GET", "HEAD", "POST" and "PUT", but CGI-scripts may implement any method they like.

If the server is not available then the library will generate an internal error response.

The library automatically adds a "Host" and a "Content-Length" header to the HTTP request before it is sent over the network.

For a GET request you might want to add a "If-Modified-Since" or "If-None-Match" header to make the request conditional.

For a POST request you should add the "Content-Type" header. When you try to emulate HTML <FORM> handling you should usually let the value of the "Content-Type" header be "application/x-www-form-urlencoded". See the lwpcook manpage for examples of this.

The libwww-perl HTTP implementation currently support the HTTP/1.1 and HTTP/1.0 protocol.

The library allows you to access proxy server through HTTP. This means that you can set up the library to forward all types of request through the HTTP protocol module. See the LWP::UserAgent manpage for documentation of this.

HTTPS Requests

HTTPS requests are HTTP requests over an encrypted network connection using the SSL protocol developed by Netscape. Everything about HTTP requests above also apply to HTTPS requests. In addition the library will add the headers "Client-SSL-Cipher", "Client-SSL-Cert-Subject" and "Client-SSL-Cert-Issuer" to the response. These headers denote the encryption method used and the name of the server owner.

The request can contain the header "If-SSL-Cert-Subject" in order to make the request conditional on the content of the server certificate. If the certificate subject does not match, no request is sent to the server and an internally generated error response is returned. The value of the "If-SSL-Cert-Subject" header is interpreted as a Perl regular expression.

FTP Requests

The library currently supports GET, HEAD and PUT requests. GET retrieves a file or a directory listing from an FTP server. PUT stores a file on a ftp server.

You can specify a ftp account for servers that want this in addition to user name and password. This is specified by including an "Account" header in the request.

User name/password can be specified using basic authorization or be encoded in the URL. Failed logins return an UNAUTHORIZED response with "WWW-Authenticate: Basic" and can be treated like basic authorization for HTTP.

The library supports ftp ASCII transfer mode by specifying the "type=a" parameter in the URL. It also supports transfer of ranges for FTP transfers using the "Range" header.

Directory listings are by default returned unprocessed (as returned from the ftp server) with the content media type reported to be "text/ftp-dir-listing". The File::Listing module provides methods for parsing of these directory listing.

The ftp module is also able to convert directory listings to HTML and this can be requested via the standard HTTP content negotiation mechanisms (add an "Accept: text/html" header in the request if you want this).

For normal file retrievals, the "Content-Type" is guessed based on the file name suffix. See the LWP::MediaTypes manpage.

The "If-Modified-Since" request header works for servers that implement the MDTM command. It will probably not work for directory listings though.

Example:

  $req = HTTP::Request->new(GET => 'ftp://me:passwd@ftp.some.where.com/');
  $req->header(Accept => "text/html, */*;q=0.1");

News Requests

Access to the USENET News system is implemented through the NNTP protocol. The name of the news server is obtained from the NNTP_SERVER environment variable and defaults to "news". It is not possible to specify the hostname of the NNTP server in news: URLs.

The library supports GET and HEAD to retrieve news articles through the NNTP protocol. You can also post articles to newsgroups by using (surprise!) the POST method.

GET on newsgroups is not implemented yet.

Examples:

  $req = HTTP::Request->new(GET => 'news:abc1234@a.sn.no');

  $req = HTTP::Request->new(POST => 'news:comp.lang.perl.test');
  $req->header(Subject => 'This is a test',
               From    => 'me@some.where.org');
  $req->content(<<EOT);
  This is the content of the message that we are sending to
  the world.
  EOT

Gopher Request

The library supports the GET and HEAD methods for gopher requests. All request header values are ignored. HEAD cheats and returns a response without even talking to server.

Gopher menus are always converted to HTML.

The response "Content-Type" is generated from the document type encoded (as the first letter) in the request URL path itself.

Example:

  $req = HTTP::Request->new(GET => 'gopher://gopher.sn.no/');

File Request

The library supports GET and HEAD methods for file requests. The "If-Modified-Since" header is supported. All other headers are ignored. The host component of the file URL must be empty or set to "localhost". Any other host value will be treated as an error.

Directories are always converted to an HTML document. For normal files, the "Content-Type" and "Content-Encoding" in the response are guessed based on the file suffix.

Example:

  $req = HTTP::Request->new(GET => 'file:/etc/passwd');

Mailto Request

You can send (aka "POST") mail messages using the library. All headers specified for the request are passed on to the mail system. The "To" header is initialized from the mail address in the URL.

Example:

  $req = HTTP::Request->new(POST => 'mailto:libwww@perl.org');
  $req->header(Subject => "subscribe");
  $req->content("Please subscribe me to the libwww-perl mailing list!\n");

CPAN Requests

URLs with scheme cpan: are redirected to the a suitable CPAN mirror. If you have your own local mirror of CPAN you might tell LWP to use it for cpan: URLs by an assignment like this:

  $LWP::Protocol::cpan::CPAN = "file:/local/CPAN/";

Suitable CPAN mirrors are also picked up from the configuration for the CPAN.pm, so if you have used that module a suitable mirror should be picked automatically. If neither of these apply, then a redirect to the generic CPAN http location is issued.

Example request to download the newest perl:

  $req = HTTP::Request->new(GET => "cpan:src/latest.tar.gz");

OVERVIEW OF CLASSES AND PACKAGES

This table should give you a quick overview of the classes provided by the library. Indentation shows class inheritance.

 LWP::MemberMixin   -- Access to member variables of Perl5 classes
   LWP::UserAgent   -- WWW user agent class
     LWP::RobotUA   -- When developing a robot applications
   LWP::Protocol          -- Interface to various protocol schemes
     LWP::Protocol::http  -- http:// access
     LWP::Protocol::file  -- file:// access
     LWP::Protocol::ftp   -- ftp:// access
     ...
 LWP::Authen::Basic -- Handle 401 and 407 responses
 LWP::Authen::Digest
 HTTP::Headers      -- MIME/RFC822 style header (used by HTTP::Message)
 HTTP::Message      -- HTTP style message
   HTTP::Request    -- HTTP request
   HTTP::Response   -- HTTP response
 HTTP::Daemon       -- A HTTP server class
 WWW::RobotRules    -- Parse robots.txt files
   WWW::RobotRules::AnyDBM_File -- Persistent RobotRules
 Net::HTTP          -- Low level HTTP client

The following modules provide various functions and definitions.

 LWP                -- This file.  Library version number and documentation.
 LWP::MediaTypes    -- MIME types configuration (text/html etc.)
 LWP::Debug         -- Debug logging module
 LWP::Simple        -- Simplified procedural interface for common functions
 HTTP::Status       -- HTTP status code (200 OK etc)
 HTTP::Date         -- Date parsing module for HTTP date formats
 HTTP::Negotiate    -- HTTP content negotiation calculation
 File::Listing      -- Parse directory listings
 HTML::Form         -- Processing for <form>s in HTML documents

MORE DOCUMENTATION

All modules contain detailed information on the interfaces they provide. The lwpcook manpage is the libwww-perl cookbook that contain examples of typical usage of the library. You might want to take a look at how the scripts lwp-request, lwp-rget and lwp-mirror are implemented.

ENVIRONMENT

The following environment variables are used by LWP:

HOME

The LWP::MediaTypes functions will look for the .media.types and .mime.types files relative to you home directory.

http_proxy
ftp_proxy
xxx_proxy
no_proxy

These environment variables can be set to enable communication through a proxy server. See the description of the env_proxy method in the LWP::UserAgent manpage.

PERL_LWP_USE_HTTP_10

Enable the old HTTP/1.0 protocol driver instead of the new HTTP/1.1 driver. You might want to set this to a TRUE value if you discover that your old LWP applications fails after you installed LWP-5.60 or better.

PERL_HTTP_URI_CLASS

Used to decide what URI objects to instantiate. The default is URI. You might want to set it to URI::URL for compatibility with old times.

AUTHORS

LWP was made possible by contributions from Adam Newby, Albert Dvornik, Alexandre Duret-Lutz, Andreas Gustafsson, Andreas König, Andrew Pimlott, Andy Lester, Ben Coleman, Benjamin Low, Ben Low, Ben Tilly, Blair Zajac, Bob Dalgleish, BooK, Brad Hughes, Brian J. Murrell, Brian McCauley, Charles C. Fu, Charles Lane, Chris Nandor, Christian Gilmore, Chris W. Unger, Craig Macdonald, Dale Couch, Dan Kubb, Dave Dunkin, Dave W. Smith, David Coppit, David Dick, David D. Kilzer, Doug MacEachern, Edward Avis, erik, Gary Shea, Gisle Aas, Graham Barr, Gurusamy Sarathy, Hans de Graaff, Harald Joerg, Harry Bochner, Hugo, Ilya Zakharevich, INOUE Yoshinari, Ivan Panchenko, Jack Shirazi, James Tillman, Jan Dubois, Jared Rhine, Jim Stern, Joao Lopes, John Klar, Johnny Lee, Josh Kronengold, Josh Rai, Joshua Chamas, Joshua Hoblitt, Kartik Subbarao, Keiichiro Nagano, Ken Williams, KONISHI Katsuhiro, Lee T Lindley, Liam Quinn, Marc Hedlund, Marc Langheinrich, Mark D. Anderson, Marko Asplund, Mark Stosberg, Markus B Krüger, Markus Laker, Martijn Koster, Martin Thurn, Matthew Eldridge, Matthew.van.Eerde, Matt Sergeant, Michael A. Chase, Michael Quaranta, Michael Thompson, Mike Schilli, Moshe Kaminsky, Nathan Torkington, Nicolai Langfeldt, Norton Allen, Olly Betts, Paul J. Schinder, peterm, Philip GuentherDaniel Buenzli, Pon Hwa Lin, Radoslaw Zielinski, Radu Greab, Randal L. Schwartz, Richard Chen, Robin Barker, Roy Fielding, Sander van Zoest, Sean M. Burke, shildreth, Slaven Rezic, Steve A Fink, Steve Hay, Steven Butler, Steve_Kilbane, Takanori Ugai, Thomas Lotterer, Tim Bunce, Tom Hughes, Tony Finch, Ville Skyttä, Ward Vandewege, William York, Yale Huang, and Yitzchak Scott-Thoennes.

LWP owes a lot in motivation, design, and code, to the libwww-perl library for Perl4 by Roy Fielding, which included work from Alberto Accomazzi, James Casey, Brooks Cutter, Martijn Koster, Oscar Nierstrasz, Mel Melchner, Gertjan van Oosten, Jared Rhine, Jack Shirazi, Gene Spafford, Marc VanHeyningen, Steven E. Brenner, Marion Hakanson, Waldemar Kebsch, Tony Sanders, and Larry Wall; see the libwww-perl-0.40 library for details.

COPYRIGHT

  Copyright 1995-2005, Gisle Aas
  Copyright 1995, Martijn Koster

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AVAILABILITY

The latest version of this library is likely to be available from CPAN as well as:

 http://www.linpro.no/lwp/

The best place to discuss this code is on the <libwww@perl.org> mailing list.


LWP::Authen::Ntlm - Library for enabling NTLM authentication in LWP

  • USAGE
  • AVAILABILITY
  • COPYRIGHT
  • SEE ALSO

NAME

LWP::Authen::Ntlm - Library for enabling NTLM authentication (Microsoft) in LWP

SYNOPSIS

 use LWP::UserAgent;
 use HTTP::Request::Common;
 my $url = 'http://www.company.com/protected_page.html';

 # Set up the ntlm client and then the base64 encoded ntlm handshake message
 my $ua = new LWP::UserAgent(keep_alive=>1);
 $ua->credentials('www.company.com:80', '', "MyDomain\\MyUserCode", 'MyPassword');

 $request = GET $url;
 print "--Performing request now...-----------\n";
 $response = $ua->request($request);
 print "--Done with request-------------------\n";

 if ($response->is_success) {print "It worked!->" . $response->code . "\n"}
 else {print "It didn't work!->" . $response->code . "\n"}

DESCRIPTION

LWP::Authen::Ntlm allows LWP to authenticate against servers that are using the NTLM authentication scheme popularized by Microsoft. This type of authentication is common on intranets of Microsoft-centric organizations.

The module takes advantage of the Authen::NTLM module by Mark Bush. Since there is also another Authen::NTLM module available from CPAN by Yee Man Chan with an entirely different interface, it is necessary to ensure that you have the correct NTLM module.

In addition, there have been problems with incompatibilities between different versions of Mime::Base64, which Bush's Authen::NTLM makes use of. Therefore, it is necessary to ensure that your Mime::Base64 module supports exporting of the encode_base64 and decode_base64 functions.

USAGE

The module is used indirectly through LWP, rather than including it directly in your code. The LWP system will invoke the NTLM authentication when it encounters the authentication scheme while attempting to retrieve a URL from a server. In order for the NTLM authentication to work, you must have a few things set up in your code prior to attempting to retrieve the URL:

  • Enable persistent HTTP connections

    To do this, pass the "keep_alive=>1" option to the LWP::UserAgent when creating it, like this:

        my $ua = new LWP::UserAgent(keep_alive=>1);

  • Set the credentials on the UserAgent object

    The credentials must be set like this:

       $ua->credentials('www.company.com:80', '', "MyDomain\\MyUserCode", 'MyPassword');

    Note that you cannot use the HTTP::Request object's authorization_basic() method to set the credentials. Note, too, that the 'www.company.com:80' portion only sets credentials on the specified port AND it is case-sensitive (this is due to the way LWP is coded, and has nothing to do with LWP::Authen::Ntlm)

If you run into trouble and need help troubleshooting your problems, try enabling LWP debugging by putting this line at the top of your code:

    use LWP::Debug qw(+);

You should get copious debugging output, including messages from LWP::Authen::Ntlm itself.

AVAILABILITY

General queries regarding LWP should be made to the LWP Mailing List.

Questions specific to LWP::Authen::Ntlm can be forwarded to jtillman@bigfoot.com

COPYRIGHT

Copyright (c) 2002 James Tillman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the LWP manpage, the LWP::UserAgent manpage, the lwpcook manpage.


LWP::ConnCache - Connection cache manager

  • NOTE
  • SYNOPSIS
  • DESCRIPTION
  • SUBCLASSING
  • SEE ALSO
  • COPYRIGHT

NAME

LWP::ConnCache - Connection cache manager

NOTE

This module is experimental. Details of its interface is likely to change in the future.

SYNOPSIS

 use LWP::ConnCache;
 my $cache = LWP::ConnCache->new;
 $cache->deposit($type, $key, $sock);
 $sock = $cache->withdraw($type, $key);

DESCRIPTION

The LWP::ConnCache class is the standard connection cache manager for LWP::UserAgent.

The following basic methods are provided:

$cache = LWP::ConnCache->new( %options )

This method constructs a new LWP::ConnCache object. The only option currently accepted is 'total_capacity'. If specified it initialize the total_capacity option. It defaults to the value 1.

$cache->total_capacity( [$num_connections] )

Get/sets the number of connection that will be cached. Connections will start to be dropped when this limit is reached. If set to 0, then all connections are immediately dropped. If set to undef, then there is no limit.

$cache->capacity($type, [$num_connections] )

Get/set a limit for the number of connections of the specified type that can be cached. The $type will typically be a short string like "http" or "ftp".

$cache->drop( [$checker, [$reason]] )

Drop connections by some criteria. The $checker argument is a subroutine that is called for each connection. If the routine returns a TRUE value then the connection is dropped. The routine is called with ($conn, $type, $key, $deposit_time) as arguments.

Shortcuts: If the $checker argument is absent (or undef) all cached connections are dropped. If the $checker is a number then all connections untouched that the given number of seconds or more are dropped. If $checker is a string then all connections of the given type are dropped.

The $reason argument is passed on to the dropped() method.

$cache->prune

Calling this method will drop all connections that are dead. This is tested by calling the ping() method on the connections. If the ping() method exists and returns a FALSE value, then the connection is dropped.

$cache->get_types

This returns all the 'type' fields used for the currently cached connections.

$cache->get_connections( [$type] )

This returns all connection objects of the specified type. If no type is specified then all connections are returned. In scalar context the number of cached connections of the specified type is returned.

The following methods are called by low-level protocol modules to try to save away connections and to get them back.

$cache->deposit($type, $key, $conn)

This method adds a new connection to the cache. As a result other already cached connections might be dropped. Multiple connections with the same $type/$key might added.

$conn = $cache->withdraw($type, $key)

This method tries to fetch back a connection that was previously deposited. If no cached connection with the specified $type/$key is found, then undef is returned. There is not guarantee that a deposited connection can be withdrawn, as the cache manger is free to drop connections at any time.

The following methods are called internally. Subclasses might want to override them.

$conn->enforce_limits([$type])

This method is called with after a new connection is added (deposited) in the cache or capacity limits are adjusted. The default implementation drops connections until the specified capacity limits are not exceeded.

$conn->dropping($conn_record, $reason)

This method is called when a connection is dropped. The record belonging to the dropped connection is passed as the first argument and a string describing the reason for the drop is passed as the second argument. The default implementation makes some noise if the $LWP::ConnCache::DEBUG variable is set and nothing more.

SUBCLASSING

For specialized cache policy it makes sense to subclass LWP::ConnCache and perhaps override the deposit(), enforce_limits() and dropping() methods.

The object itself is a hash. Keys prefixed with cc_ are reserved for the base class.

SEE ALSO

the LWP::UserAgent manpage

COPYRIGHT

Copyright 2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


LWP::Debug - debug routines for the libwww-perl library

NAME

LWP::Debug - debug routines for the libwww-perl library

SYNOPSIS

 use LWP::Debug qw(+ -conns);

 # Used internally in the library
 LWP::Debug::trace('send()');
 LWP::Debug::debug('url ok');
 LWP::Debug::conns("read $n bytes: $data");

DESCRIPTION

LWP::Debug provides tracing facilities. The trace(), debug() and conns() function are called within the library and they log information at increasing levels of detail. Which level of detail is actually printed is controlled with the level() function.

The following functions are available:

level(...)

The level() function controls the level of detail being logged. Passing '+' or '-' indicates full and no logging respectively. Individual levels can switched on and of by passing the name of the level with a '+' or '-' prepended. The levels are:

  trace   : trace function calls
  debug   : print debug messages
  conns   : show all data transfered over the connections

The LWP::Debug module provide a special import() method that allows you to pass the level() arguments with initial use statement. If a use argument start with '+' or '-' then it is passed to the level function, else the name is exported as usual. The following two statements are thus equivalent (if you ignore that the second pollutes your namespace):

  use LWP::Debug qw(+);
  use LWP::Debug qw(level); level('+');
trace($msg)

The trace() function is used for tracing function calls. The package and calling subroutine name is printed along with the passed argument. This should be called at the start of every major function.

debug($msg)

The debug() function is used for high-granularity reporting of state in functions.

conns($msg)

The conns() function is used to show data being transferred over the connections. This may generate considerable output.


LWP::DebugFile - routines for tracing/debugging LWP

  • OPTIONS
  • OUTPUT FILE NAMING
  • ENVIRONMENT
  • IMPLEMENTATION NOTES
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

LWP::DebugFile - routines for tracing/debugging LWP

SYNOPSIS

If you want to see just what LWP is doing when your program calls it, add this to the beginning of your program's source:

  use LWP::DebugFile;

For even more verbose debug output, do this instead:

  use LWP::DebugFile ('+');

DESCRIPTION

This module is like LWP::Debug in that it allows you to see what your calls to LWP are doing behind the scenes. But it is unlike LWP::Debug in that it sends the output to a file, instead of to STDERR (as LWP::Debug does).

OPTIONS

The options you can use in use LWP::DebugFile (options) are the same as the non-exporting options available from use LWP::Debug (I<options>). That is, you can do things like this:

  use LWP::DebugFile qw(+);
  use LWP::Debug qw(+ -conns);
  use LWP::Debug qw(trace);

The meanings of these are explained in the documentation for LWP::Debug. The only differences are that by default, LWP::DebugFile has cons debugging on, ad that (as mentioned earlier), only non-exporting options are available. That is, you can't do this:

  use LWP::DebugFile qw(trace); # wrong

You might expect that to export LWP::Debug's trace() function, but it doesn't work -- it's a compile-time error.

OUTPUT FILE NAMING

If you don't do anything, the output file (where all the LWP debug/trace output goes) will be in the current directory, and will be named like lwp_3db7aede_b93.log, where 3db7aede is $^T expressed in hex, and b93 is $$ expressed in hex. Presumably this is a unique-for-all-time filename!

If you don't want the files to go in the current directory, you can set $LWP::DebugFile::outpath before you load the LWP::DebugFile module:

  BEGIN { $LWP::DebugFile::outpath = '/tmp/crunk/' }
  use LWP::DebugFile;

Note that you must end the value with a path separator ("/" in this case -- under MacPerl it would be ":"). With that set, you will have output files named like /tmp/crunk/lwp_3db7aede_b93.log.

If you want the LWP::DebugFile output to go a specific filespec (instead of just a uniquely named file, in whatever directory), instead set the variable $LWP::DebugFile::outname, like so:

  BEGIN { $LWP::DebugFile::outname = '/home/mojojojo/lwp.log' }
  use LWP::DebugFile;

In that case, $LWP::DebugFile::outpath isn't consulted at all, and output is always written to the file /home/mojojojo/lwp.log.

Note that the value of $LWP::DebugFile::outname doesn't need to be an absolute filespec. You can do this:

  BEGIN { $LWP::DebugFile::outname = 'lwp.log' }
  use LWP::DebugFile;

In that case, output goes to a file named lwp.log in the current directory -- specifically, whatever directory is current when LWP::DebugFile is first loaded. $LWP::DebugFile::outpath is still not consulted -- its value is used only if $LWP::DebugFile::outname isn't set.

ENVIRONMENT

If you set the environment variables LWPDEBUGPATH or LWPDEBUGFILE, their values will be used in initializing the values of $LWP::DebugFile::outpath and $LWP::DebugFile::outname.

That is, if you have LWPDEBUGFILE set to /home/mojojojo/lwp.log, then you can just start out your program with:

  use LWP::DebugFile;

and it will act as if you had started it like this:

  BEGIN { $LWP::DebugFile::outname = '/home/mojojojo/lwp.log' }
  use LWP::DebugFile;

IMPLEMENTATION NOTES

This module works by subclassing LWP::Debug, (notably inheriting its import). It also redefines &LWP::Debug::conns and &LWP::Debug::_log to make for output that is a little more verbose, and friendlier for when you're looking at it later in a log file.

SEE ALSO

the LWP::Debug manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


LWP::MediaTypes - guess media type for a file or a URL

  • COPYRIGHT

NAME

LWP::MediaTypes - guess media type for a file or a URL

SYNOPSIS

 use LWP::MediaTypes qw(guess_media_type);
 $type = guess_media_type("/tmp/foo.gif");

DESCRIPTION

This module provides functions for handling media (also known as MIME) types and encodings. The mapping from file extensions to media types is defined by the media.types file. If the ~/.media.types file exists it is used instead. For backwards compatibility we will also look for ~/.mime.types.

The following functions are exported by default:

guess_media_type( $filename )
guess_media_type( $uri )
guess_media_type( $filename_or_uri, $header_to_modify )

This function tries to guess media type and encoding for a file or a URI. It returns the content type, which is a string like "text/html". In array context it also returns any content encodings applied (in the order used to encode the file). You can pass a URI object reference, instead of the file name.

If the type can not be deduced from looking at the file name, then guess_media_type() will let the -T Perl operator take a look. If this works (and -T returns a TRUE value) then we return text/plain as the type, otherwise we return application/octet-stream as the type.

The optional second argument should be a reference to a HTTP::Headers object or any object that implements the $obj->header method in a similar way. When it is present the values of the 'Content-Type' and 'Content-Encoding' will be set for this header.

media_suffix( $type, ... )

This function will return all suffixes that can be used to denote the specified media type(s). Wildcard types can be used. In a scalar context it will return the first suffix found. Examples:

  @suffixes = media_suffix('image/*', 'audio/basic');
  $suffix = media_suffix('text/html');

The following functions are only exported by explicit request:

add_type( $type, @exts )

Associate a list of file extensions with the given media type. Example:

    add_type("x-world/x-vrml" => qw(wrl vrml));
add_encoding( $type, @ext )

Associate a list of file extensions with an encoding type. Example:

 add_encoding("x-gzip" => "gz");
read_media_types( @files )

Parse media types files and add the type mappings found there. Example:

    read_media_types("conf/mime.types");

COPYRIGHT

Copyright 1995-1999 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


LWP::MemberMixin - Member access mixin class

NAME

LWP::MemberMixin - Member access mixin class

SYNOPSIS

 package Foo;
 require LWP::MemberMixin;
 @ISA=qw(LWP::MemberMixin);

DESCRIPTION

A mixin class to get methods that provide easy access to member variables in the %$self. Ideally there should be better Perl language support for this.

There is only one method provided:

_elem($elem [, $val])

Internal method to get/set the value of member variable $elem. If $val is present it is used as the new value for the member variable. If it is not present the current value is not touched. In both cases the previous value of the member variable is returned.


LWP::Protocol - Base class for LWP protocols

  • SEE ALSO
  • COPYRIGHT

NAME

LWP::Protocol - Base class for LWP protocols

SYNOPSIS

 package LWP::Protocol::foo;
 require LWP::Protocol;
 @ISA=qw(LWP::Protocol);

DESCRIPTION

This class is used a the base class for all protocol implementations supported by the LWP library.

When creating an instance of this class using LWP::Protocol::create($url), and you get an initialised subclass appropriate for that access method. In other words, the LWP::Protocol::create() function calls the constructor for one of its subclasses.

All derived LWP::Protocol classes need to override the request() method which is used to service a request. The overridden method can make use of the collect() function to collect together chunks of data as it is received.

The following methods and functions are provided:

$prot = LWP::Protocol->new()

The LWP::Protocol constructor is inherited by subclasses. As this is a virtual base class this method should not be called directly.

$prot = LWP::Protocol::create($scheme)

Create an object of the class implementing the protocol to handle the given scheme. This is a function, not a method. It is more an object factory than a constructor. This is the function user agents should use to access protocols.

$class = LWP::Protocol::implementor($scheme, [$class])

Get and/or set implementor class for a scheme. Returns '' if the specified scheme is not supported.

$prot->request(...)
 $response = $protocol->request($request, $proxy, undef);
 $response = $protocol->request($request, $proxy, '/tmp/sss');
 $response = $protocol->request($request, $proxy, \&callback, 1024);

Dispatches a request over the protocol, and returns a response object. This method needs to be overridden in subclasses. Refer to the LWP::UserAgent manpage for description of the arguments.

$prot->collect($arg, $response, $collector)

Called to collect the content of a request, and process it appropriately into a scalar, file, or by calling a callback. If $arg is undefined, then the content is stored within the $response. If $arg is a simple scalar, then $arg is interpreted as a file name and the content is written to this file. If $arg is a reference to a routine, then content is passed to this routine.

The $collector is a routine that will be called and which is responsible for returning pieces (as ref to scalar) of the content to process. The $collector signals EOF by returning a reference to an empty sting.

The return value from collect() is the $response object reference.

Note: We will only use the callback or file argument if $response->is_success(). This avoids sending content data for redirects and authentication responses to the callback which would be confusing.

$prot->collect_once($arg, $response, $content)

Can be called when the whole response content is available as $content. This will invoke collect() with a collector callback that returns a reference to $content the first time and an empty string the next.

SEE ALSO

Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for examples of usage.

COPYRIGHT

Copyright 1995-2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


LWP::RobotUA - a class for well-behaved Web robots

  • METHODS
  • SEE ALSO
  • COPYRIGHT

NAME

LWP::RobotUA - a class for well-behaved Web robots

SYNOPSIS

  use LWP::RobotUA;
  my $ua = LWP::RobotUA->new('my-robot/0.1', 'me@foo.com');
  $ua->delay(10);  # be very nice -- max one hit every ten minutes!
  ...

  # Then just use it just like a normal LWP::UserAgent:
  my $response = $ua->get('http://whatever.int/...');
  ...

DESCRIPTION

This class implements a user agent that is suitable for robot applications. Robots should be nice to the servers they visit. They should consult the /robots.txt file to ensure that they are welcomed and they should not make requests too frequently.

But before you consider writing a robot, take a look at <URL:http://www.robotstxt.org/>.

When you use a LWP::RobotUA object as your user agent, then you do not really have to think about these things yourself; robots.txt files are automatically consulted and obeyed, the server isn't queried too rapidly, and so on. Just send requests as you do when you are using a normal LWP::UserAgent object (using $ua->get(...), $ua->head(...), $ua->request(...), etc.), and this special agent will make sure you are nice.

METHODS

The LWP::RobotUA is a sub-class of LWP::UserAgent and implements the same methods. In addition the following methods are provided:

$ua = LWP::RobotUA->new( %options )
$ua = LWP::RobotUA->new( $agent, $from )
$ua = LWP::RobotUA->new( $agent, $from, $rules )

The LWP::UserAgent options agent and from are mandatory. The options delay, use_sleep and rules initialize attributes private to the RobotUA. If rules are not provided, then WWW::RobotRules is instantiated providing an internal database of robots.txt.

It is also possible to just pass the value of agent, from and optionally rules as plain positional arguments.

$ua->delay
$ua->delay( $minutes )

Get/set the minimum delay between requests to the same server, in minutes. The default is 1 minute. Note that this number doesn't have to be an integer; for example, this sets the delay to 10 seconds:

    $ua->delay(10/60);
$ua->use_sleep
$ua->use_sleep( $boolean )

Get/set a value indicating whether the UA should sleep() if requests arrive too fast, defined as $ua->delay minutes not passed since last request to the given server. The default is TRUE. If this value is FALSE then an internal SERVICE_UNAVAILABLE response will be generated. It will have an Retry-After header that indicates when it is OK to send another request to this server.

$ua->rules
$ua->rules( $rules )

Set/get which WWW::RobotRules object to use.

$ua->no_visits( $netloc )

Returns the number of documents fetched from this server host. Yeah I know, this method should probably have been named num_visits() or something like that. :-(

$ua->host_wait( $netloc )

Returns the number of seconds (from now) you must wait before you can make a new request to this host.

$ua->as_string

Returns a string that describes the state of the UA. Mainly useful for debugging.

SEE ALSO

the LWP::UserAgent manpage, the WWW::RobotRules manpage

COPYRIGHT

Copyright 1996-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


LWP::Simple - simple procedural interface to LWP

  • CAVEAT
  • SEE ALSO

NAME

LWP::Simple - simple procedural interface to LWP

SYNOPSIS

 perl -MLWP::Simple -e 'getprint "http://www.sn.no";'
 use LWP::Simple;
 $content = get("http://www.sn.no/");
 die "Couldn't get it!" unless defined $content;

 if (mirror("http://www.sn.no/", "foo") == RC_NOT_MODIFIED) {
     ...
 }

 if (is_success(getprint("http://www.sn.no/"))) {
     ...
 }

DESCRIPTION

This module is meant for people who want a simplified view of the libwww-perl library. It should also be suitable for one-liners. If you need more control or access to the header fields in the requests sent and responses received, then you should use the full object-oriented interface provided by the LWP::UserAgent module.

The following functions are provided (and exported) by this module:

get($url)

The get() function will fetch the document identified by the given URL and return it. It returns undef if it fails. The $url argument can be either a simple string or a reference to a URI object.

You will not be able to examine the response code or response headers (like 'Content-Type') when you are accessing the web using this function. If you need that information you should use the full OO interface (see the LWP::UserAgent manpage).

head($url)

Get document headers. Returns the following 5 values if successful: ($content_type, $document_length, $modified_time, $expires, $server)

Returns an empty list if it fails. In scalar context returns TRUE if successful.

getprint($url)

Get and print a document identified by a URL. The document is printed to the selected default filehandle for output (normally STDOUT) as data is received from the network. If the request fails, then the status code and message are printed on STDERR. The return value is the HTTP response code.

getstore($url, $file)

Gets a document identified by a URL and stores it in the file. The return value is the HTTP response code.

mirror($url, $file)

Get and store a document identified by a URL, using If-modified-since, and checking the Content-Length. Returns the HTTP response code.

This module also exports the HTTP::Status constants and procedures. You can use them when you check the response code from getprint(), getstore() or mirror(). The constants are:

   RC_CONTINUE
   RC_SWITCHING_PROTOCOLS
   RC_OK
   RC_CREATED
   RC_ACCEPTED
   RC_NON_AUTHORITATIVE_INFORMATION
   RC_NO_CONTENT
   RC_RESET_CONTENT
   RC_PARTIAL_CONTENT
   RC_MULTIPLE_CHOICES
   RC_MOVED_PERMANENTLY
   RC_MOVED_TEMPORARILY
   RC_SEE_OTHER
   RC_NOT_MODIFIED
   RC_USE_PROXY
   RC_BAD_REQUEST
   RC_UNAUTHORIZED
   RC_PAYMENT_REQUIRED
   RC_FORBIDDEN
   RC_NOT_FOUND
   RC_METHOD_NOT_ALLOWED
   RC_NOT_ACCEPTABLE
   RC_PROXY_AUTHENTICATION_REQUIRED
   RC_REQUEST_TIMEOUT
   RC_CONFLICT
   RC_GONE
   RC_LENGTH_REQUIRED
   RC_PRECONDITION_FAILED
   RC_REQUEST_ENTITY_TOO_LARGE
   RC_REQUEST_URI_TOO_LARGE
   RC_UNSUPPORTED_MEDIA_TYPE
   RC_INTERNAL_SERVER_ERROR
   RC_NOT_IMPLEMENTED
   RC_BAD_GATEWAY
   RC_SERVICE_UNAVAILABLE
   RC_GATEWAY_TIMEOUT
   RC_HTTP_VERSION_NOT_SUPPORTED

The HTTP::Status classification functions are:

is_success($rc)

True if response code indicated a successful request.

is_error($rc)

True if response code indicated that an error occurred.

The module will also export the LWP::UserAgent object as $ua if you ask for it explicitly.

The user agent created by this module will identify itself as "LWP::Simple/#.##" (where "#.##" is the libwww-perl version number) and will initialize its proxy defaults from the environment (by calling $ua->env_proxy).

CAVEAT

Note that if you are using both LWP::Simple and the very popular CGI.pm module, you may be importing a head function from each module, producing a warning like "Prototype mismatch: sub main::head ($) vs none". Get around this problem by just not importing LWP::Simple's head function, like so:

        use LWP::Simple qw(!head);
        use CGI qw(:standard);  # then only CGI.pm defines a head()

Then if you do need LWP::Simple's head function, you can just call it as LWP::Simple::head($url).

SEE ALSO

the LWP manpage, the lwpcook manpage, the LWP::UserAgent manpage, the HTTP::Status manpage, the lwp-request manpage, the lwp-mirror manpage


LWP::UserAgent - Web user agent class

  • CONSTRUCTOR METHODS
  • ATTRIBUTES
    • Proxy attributes
  • REQUEST METHODS
    • Callback methods
  • SEE ALSO
  • COPYRIGHT

NAME

LWP::UserAgent - Web user agent class

SYNOPSIS

 require LWP::UserAgent;

 my $ua = LWP::UserAgent->new;
 $ua->timeout(10);
 $ua->env_proxy;

 my $response = $ua->get('http://search.cpan.org/');

 if ($response->is_success) {
     print $response->content;  # or whatever
 }
 else {
     die $response->status_line;
 }

DESCRIPTION

The LWP::UserAgent is a class implementing a web user agent. LWP::UserAgent objects can be used to dispatch web requests.

In normal use the application creates an LWP::UserAgent object, and then configures it with values for timeouts, proxies, name, etc. It then creates an instance of HTTP::Request for the request that needs to be performed. This request is then passed to one of the request method the UserAgent, which dispatches it using the relevant protocol, and returns a HTTP::Response object. There are convenience methods for sending the most common request types: get(), head() and post(). When using these methods then the creation of the request object is hidden as shown in the synopsis above.

The basic approach of the library is to use HTTP style communication for all protocol schemes. This means that you will construct HTTP::Request objects and receive HTTP::Response objects even for non-HTTP resources like gopher and ftp. In order to achieve even more similarity to HTTP style communications, gopher menus and file directories are converted to HTML documents.

CONSTRUCTOR METHODS

The following constructor methods are available:

$ua = LWP::UserAgent->new( %options )

This method constructs a new LWP::UserAgent object and returns it. Key/value pair arguments may be provided to set up the initial state. The following options correspond to attribute methods described below:

   KEY                     DEFAULT
   -----------             --------------------
   agent                   "libwww-perl/#.##"
   from                    undef
   conn_cache              undef
   cookie_jar              undef
   default_headers         HTTP::Headers->new
   max_size                undef
   max_redirect            7
   parse_head              1
   protocols_allowed       undef
   protocols_forbidden     undef
   requests_redirectable   ['GET', 'HEAD']
   timeout                 180

The following additional options are also accepted: If the env_proxy option is passed in with a TRUE value, then proxy settings are read from environment variables (see env_proxy() method below). If the keep_alive option is passed in, then a LWP::ConnCache is set up (see conn_cache() method below). The keep_alive value is passed on as the total_capacity for the connection cache.

$ua->clone

Returns a copy of the LWP::UserAgent object.

ATTRIBUTES

The settings of the configuration attributes modify the behaviour of the LWP::UserAgent when it dispatches requests. Most of these can also be initialized by options passed to the constructor method.

The following attributes methods are provided. The attribute value is left unchanged if no argument is given. The return value from each method is the old attribute value.

$ua->agent
$ua->agent( $product_id )

Get/set the product token that is used to identify the user agent on the network. The agent value is sent as the "User-Agent" header in the requests. The default is the string returned by the _agent() method (see below).

If the $product_id ends with space then the _agent() string is appended to it.

The user agent string should be one or more simple product identifiers with an optional version number separated by the "/" character. Examples are:

  $ua->agent('Checkbot/0.4 ' . $ua->_agent);
  $ua->agent('Checkbot/0.4 ');    # same as above
  $ua->agent('Mozilla/5.0');
  $ua->agent("");                 # don't identify
$ua->_agent

Returns the default agent identifier. This is a string of the form "libwww-perl/#.##", where "#.##" is substituted with the version number of this library.

$ua->from
$ua->from( $email_address )

Get/set the e-mail address for the human user who controls the requesting user agent. The address should be machine-usable, as defined in RFC 822. The from value is send as the "From" header in the requests. Example:

  $ua->from('gaas@cpan.org');

The default is to not send a "From" header. See the default_headers() method for the more general interface that allow any header to be defaulted.

$ua->cookie_jar
$ua->cookie_jar( $cookie_jar_obj )

Get/set the cookie jar object to use. The only requirement is that the cookie jar object must implement the extract_cookies($request) and add_cookie_header($response) methods. These methods will then be invoked by the user agent as requests are sent and responses are received. Normally this will be a HTTP::Cookies object or some subclass.

The default is to have no cookie_jar, i.e. never automatically add "Cookie" headers to the requests.

Shortcut: If a reference to a plain hash is passed in as the $cookie_jar_object, then it is replaced with an instance of HTTP::Cookies that is initialized based on the hash. This form also automatically loads the HTTP::Cookies module. It means that:

  $ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });

is really just a shortcut for:

  require HTTP::Cookies;
  $ua->cookie_jar(HTTP::Cookies->new(file => "$ENV{HOME}/.cookies.txt"));
$ua->default_headers
$ua->default_headers( $headers_obj )

Get/set the headers object that will provide default header values for any requests sent. By default this will be an empty HTTP::Headers object. Example:

  $ua->default_headers->push_header('Accept-Language' => "no, en");
$ua->default_header( $field )
$ua->default_header( $field => $value )

This is just a short-cut for $ua->default_headers->header( $field => $value ). Example:

  $ua->default_header('Accept-Language' => "no, en");
$ua->conn_cache
$ua->conn_cache( $cache_obj )

Get/set the LWP::ConnCache object to use. See the LWP::ConnCache manpage for details.

$ua->credentials( $netloc, $realm, $uname, $pass )

Set the user name and password to be used for a realm. It is often more useful to specialize the get_basic_credentials() method instead.

$ua->max_size
$ua->max_size( $bytes )

Get/set the size limit for response content. The default is undef, which means that there is no limit. If the returned response content is only partial, because the size limit was exceeded, then a "Client-Aborted" header will be added to the response. The content might end up longer than max_size as we abort once appending a chunk of data makes the length exceed the limit. The "Content-Length" header, if present, will indicate the length of the full content and will normally not be the same as length($res->content).

$ua->max_redirect
$ua->max_redirect( $n )

This reads or sets the object's limit of how many times it will obey redirection responses in a given request cycle.

By default, the value is 7. This means that if you call request() method and the response is a redirect elsewhere which is in turn a redirect, and so on seven times, then LWP gives up after that seventh request.

$ua->parse_head
$ua->parse_head( $boolean )

Get/set a value indicating whether we should initialize response headers from the <head> section of HTML documents. The default is TRUE. Do not turn this off, unless you know what you are doing.

$ua->protocols_allowed
$ua->protocols_allowed( \@protocols )

This reads (or sets) this user agent's list of protocols that the request methods will exclusively allow. The protocol names are case insensitive.

For example: $ua->protocols_allowed( [ 'http', 'https'] ); means that this user agent will allow only those protocols, and attempts to use this user agent to access URLs with any other schemes (like "ftp://...") will result in a 500 error.

To delete the list, call: $ua->protocols_allowed(undef)

By default, an object has neither a protocols_allowed list, nor a protocols_forbidden list.

Note that having a protocols_allowed list causes any protocols_forbidden list to be ignored.

$ua->protocols_forbidden
$ua->protocols_forbidden( \@protocols )

This reads (or sets) this user agent's list of protocols that the request method will not allow. The protocol names are case insensitive.

For example: $ua->protocols_forbidden( [ 'file', 'mailto'] ); means that this user agent will not allow those protocols, and attempts to use this user agent to access URLs with those schemes will result in a 500 error.

To delete the list, call: $ua->protocols_forbidden(undef)

$ua->requests_redirectable
$ua->requests_redirectable( \@requests )

This reads or sets the object's list of request names that $ua->redirect_ok(...) will allow redirection for. By default, this is ['GET', 'HEAD'], as per RFC 2616. To change to include 'POST', consider:

   push @{ $ua->requests_redirectable }, 'POST';
$ua->timeout
$ua->timeout( $secs )

Get/set the timeout value in seconds. The default timeout() value is 180 seconds, i.e. 3 minutes.

The requests is aborted if no activity on the connection to the server is observed for timeout seconds. This means that the time it takes for the complete transaction and the request() method to actually return might be longer.

Proxy attributes

The following methods set up when requests should be passed via a proxy server.

$ua->proxy(\@schemes, $proxy_url)
$ua->proxy($scheme, $proxy_url)

Set/retrieve proxy URL for a scheme:

 $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
 $ua->proxy('gopher', 'http://proxy.sn.no:8001/');

The first form specifies that the URL is to be used for proxying of access methods listed in the list in the first method argument, i.e. 'http' and 'ftp'.

The second form shows a shorthand form for specifying proxy URL for a single access scheme.

$ua->no_proxy( $domain, ... )

Do not proxy requests to the given domains. Calling no_proxy without any domains clears the list of domains. Eg:

 $ua->no_proxy('localhost', 'no', ...);
$ua->env_proxy

Load proxy settings from *_proxy environment variables. You might specify proxies like this (sh-syntax):

  gopher_proxy=http://proxy.my.place/
  wais_proxy=http://proxy.my.place/
  no_proxy="localhost,my.domain"
  export gopher_proxy wais_proxy no_proxy

csh or tcsh users should use the setenv command to define these environment variables.

On systems with case insensitive environment variables there exists a name clash between the CGI environment variables and the HTTP_PROXY environment variable normally picked up by env_proxy(). Because of this HTTP_PROXY is not honored for CGI scripts. The CGI_HTTP_PROXY environment variable can be used instead.

REQUEST METHODS

The methods described in this section are used to dispatch requests via the user agent. The following request methods are provided:

$ua->get( $url )
$ua->get( $url , $field_name => $value, ... )

This method will dispatch a GET request on the given $url. Further arguments can be given to initialize the headers of the request. These are given as separate name/value pairs. The return value is a response object. See the HTTP::Response manpage for a description of the interface it provides.

Fields names that start with ":" are special. These will not initialize headers of the request but will determine how the response content is treated. The following special field names are recognized:

    :content_file   => $filename
    :content_cb     => \&callback
    :read_size_hint => $bytes

If a $filename is provided with the :content_file option, then the response content will be saved here instead of in the response object. If a callback is provided with the :content_cb option then this function will be called for each chunk of the response content as it is received from the server. If neither of these options are given, then the response content will accumulate in the response object itself. This might not be suitable for very large response bodies. Only one of :content_file or :content_cb can be specified. The content of unsuccessful responses will always accumulate in the response object itself, regardless of the :content_file or :content_cb options passed in.

The :read_size_hint option is passed to the protocol module which will try to read data from the server in chunks of this size. A smaller value for the :read_size_hint will result in a higher number of callback invocations.

The callback function is called with 3 arguments: a chunk of data, a reference to the response object, and a reference to the protocol object. The callback can abort the request by invoking die(). The exception message will show up as the "X-Died" header field in the response returned by the get() function.

$ua->head( $url )
$ua->head( $url , $field_name => $value, ... )

This method will dispatch a HEAD request on the given $url. Otherwise it works like the get() method described above.

$ua->post( $url, \%form )
$ua->post( $url, \@form )
$ua->post( $url, \%form, $field_name => $value, ... )

This method will dispatch a POST request on the given $url, with %form or @form providing the key/value pairs for the fill-in form content. Additional headers and content options are the same as for the get() method.

This method will use the POST() function from HTTP::Request::Common to build the request. See the HTTP::Request::Common manpage for a details on how to pass form content and other advanced features.

$ua->mirror( $url, $filename )

This method will get the document identified by $url and store it in file called $filename. If the file already exists, then the request will contain an "If-Modified-Since" header matching the modification time of the file. If the document on the server has not changed since this time, then nothing happens. If the document has been updated, it will be downloaded again. The modification time of the file will be forced to match that of the server.

The return value is the the response object.

$ua->request( $request )
$ua->request( $request, $content_file )
$ua->request( $request, $content_cb )
$ua->request( $request, $content_cb, $read_size_hint )

This method will dispatch the given $request object. Normally this will be an instance of the HTTP::Request class, but any object with a similar interface will do. The return value is a response object. See the HTTP::Request manpage and the HTTP::Response manpage for a description of the interface provided by these classes.

The request() method will process redirects and authentication responses transparently. This means that it may actually send several simple requests via the simple_request() method described below.

The request methods described above; get(), head(), post() and mirror(), will all dispatch the request they build via this method. They are convenience methods that simply hides the creation of the request object for you.

The $content_file, $content_cb and $read_size_hint all correspond to options described with the get() method above.

You are allowed to use a CODE reference as content in the request object passed in. The content function should return the content when called. The content can be returned in chunks. The content function will be invoked repeatedly until it return an empty string to signal that there is no more content.

$ua->simple_request( $request )
$ua->simple_request( $request, $content_file )
$ua->simple_request( $request, $content_cb )
$ua->simple_request( $request, $content_cb, $read_size_hint )

This method dispatches a single request and returns the response received. Arguments are the same as for request() described above.

The difference from request() is that simple_request() will not try to handle redirects or authentication responses. The request() method will in fact invoke this method for each simple request it sends.

$ua->is_protocol_supported( $scheme )

You can use this method to test whether this user agent object supports the specified scheme. (The scheme might be a string (like 'http' or 'ftp') or it might be an URI object reference.)

Whether a scheme is supported, is determined by the user agent's protocols_allowed or protocols_forbidden lists (if any), and by the capabilities of LWP. I.e., this will return TRUE only if LWP supports this protocol and it's permitted for this particular object.

Callback methods

The following methods will be invoked as requests are processed. These methods are documented here because subclasses of LWP::UserAgent might want to override their behaviour.

$ua->prepare_request( $request )

This method is invoked by simple_request(). Its task is to modify the given $request object by setting up various headers based on the attributes of the user agent. The return value should normally be the $request object passed in. If a different request object is returned it will be the one actually processed.

The headers affected by the base implementation are; "User-Agent", "From", "Range" and "Cookie".

$ua->redirect_ok( $prospective_request, $response )

This method is called by request() before it tries to follow a redirection to the request in $response. This should return a TRUE value if this redirection is permissible. The $prospective_request will be the request to be sent if this method returns TRUE.

The base implementation will return FALSE unless the method is in the object's requests_redirectable list, FALSE if the proposed redirection is to a "file://..." URL, and TRUE otherwise.

$ua->get_basic_credentials( $realm, $uri, $isproxy )

This is called by request() to retrieve credentials for documents protected by Basic or Digest Authentication. The arguments passed in is the $realm provided by the server, the $uri requested and a boolean flag to indicate if this is authentication against a proxy server.

The method should return a username and password. It should return an empty list to abort the authentication resolution attempt. Subclasses can override this method to prompt the user for the information. An example of this can be found in lwp-request program distributed with this library.

The base implementation simply checks a set of pre-stored member variables, set up with the credentials() method.

$ua->progress( $status, $response )

This is called frequently as the response is received regardless of how the content is processed. The method is called with $status "begin" at the start of processing the request and with $state "end" before the request method returns. In between these $status will be the fraction of the response currently received or the string "tick" if the fraction can't be calculated.

SEE ALSO

See the LWP manpage for a complete overview of libwww-perl5. See the lwpcook manpage and the scripts lwp-request and lwp-download for examples of usage.

See the HTTP::Request manpage and the HTTP::Response manpage for a description of the message objects dispatched and received. See the HTTP::Request::Common manpage and the HTML::Form manpage for other ways to build request objects.

See the WWW::Mechanize manpage and the WWW::Search manpage for examples of more specialized user agents based on LWP::UserAgent.

COPYRIGHT

Copyright 1995-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


lwpcook - The libwww-perl cookbook

  • GET
  • HEAD
  • POST
  • PROXIES
  • ACCESS TO PROTECTED DOCUMENTS
  • COOKIES
  • HTTPS
  • MIRRORING
  • LARGE DOCUMENTS
  • COPYRIGHT

NAME

lwpcook - The libwww-perl cookbook

DESCRIPTION

This document contain some examples that show typical usage of the libwww-perl library. You should consult the documentation for the individual modules for more detail.

All examples should be runnable programs. You can, in most cases, test the code sections by piping the program text directly to perl.

GET

It is very easy to use this library to just fetch documents from the net. The LWP::Simple module provides the get() function that return the document specified by its URL argument:

  use LWP::Simple;
  $doc = get 'http://www.linpro.no/lwp/';

or, as a perl one-liner using the getprint() function:

  perl -MLWP::Simple -e 'getprint "http://www.linpro.no/lwp/";'

or, how about fetching the latest perl by running this command:

  perl -MLWP::Simple -e '
    getstore "ftp://ftp.sunet.se/pub/lang/perl/CPAN/src/latest.tar.gz";,
             "perl.tar.gz"'

You will probably first want to find a CPAN site closer to you by running something like the following command:

  perl -MLWP::Simple -e 'getprint "http://www.perl.com/perl/CPAN/CPAN.html";'

Enough of this simple stuff! The LWP object oriented interface gives you more control over the request sent to the server. Using this interface you have full control over headers sent and how you want to handle the response returned.

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->agent("$0/0.1 " . $ua->agent);
  # $ua->agent("Mozilla/8.0") # pretend we are very capable browser

  $req = HTTP::Request->new(GET => 'http://www.linpro.no/lwp');
  $req->header('Accept' => 'text/html');

  # send request
  $res = $ua->request($req);

  # check the outcome
  if ($res->is_success) {
     print $res->decoded_content;
  }
  else {
     print "Error: " . $res->status_line . "\n";
  }

The lwp-request program (alias GET) that is distributed with the library can also be used to fetch documents from WWW servers.

HEAD

If you just want to check if a document is present (i.e. the URL is valid) try to run code that looks like this:

  use LWP::Simple;

  if (head($url)) {
     # ok document exists
  }

The head() function really returns a list of meta-information about the document. The first three values of the list returned are the document type, the size of the document, and the age of the document.

More control over the request or access to all header values returned require that you use the object oriented interface described for GET above. Just s/GET/HEAD/g.

POST

There is no simple procedural interface for posting data to a WWW server. You must use the object oriented interface for this. The most common POST operation is to access a WWW form application:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = HTTP::Request->new(POST => 'http://www.perl.com/cgi-bin/BugGlimpse');
  $req->content_type('application/x-www-form-urlencoded');
  $req->content('match=www&errors=0');

  my $res = $ua->request($req);
  print $res->as_string;

Lazy people use the HTTP::Request::Common module to set up a suitable POST request message (it handles all the escaping issues) and has a suitable default for the content_type:

  use HTTP::Request::Common qw(POST);
  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = POST 'http://www.perl.com/cgi-bin/BugGlimpse',
                [ search => 'www', errors => 0 ];

  print $ua->request($req)->as_string;

The lwp-request program (alias POST) that is distributed with the library can also be used for posting data.

PROXIES

Some sites use proxies to go through fire wall machines, or just as cache in order to improve performance. Proxies can also be used for accessing resources through protocols not supported directly (or supported badly :-) by the libwww-perl library.

You should initialize your proxy setting before you start sending requests:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $ua->env_proxy; # initialize from environment variables
  # or
  $ua->proxy(ftp  => 'http://proxy.myorg.com');
  $ua->proxy(wais => 'http://proxy.myorg.com');
  $ua->no_proxy(qw(no se fi));

  my $req = HTTP::Request->new(GET => 'wais://xxx.com/');
  print $ua->request($req)->as_string;

The LWP::Simple interface will call env_proxy() for you automatically. Applications that use the $ua->env_proxy() method will normally not use the $ua->proxy() and $ua->no_proxy() methods.

Some proxies also require that you send it a username/password in order to let requests through. You should be able to add the required header, with something like this:

 use LWP::UserAgent;

 $ua = LWP::UserAgent->new;
 $ua->proxy(['http', 'ftp'] => 'http://username:password@proxy.myorg.com');

 $req = HTTP::Request->new('GET',"http://www.perl.com");

 $res = $ua->request($req);
 print $res->decoded_content if $res->is_success;

Replace proxy.myorg.com, username and password with something suitable for your site.

ACCESS TO PROTECTED DOCUMENTS

Documents protected by basic authorization can easily be accessed like this:

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $req = HTTP::Request->new(GET => 'http://www.linpro.no/secret/');
  $req->authorization_basic('aas', 'mypassword');
  print $ua->request($req)->as_string;

The other alternative is to provide a subclass of LWP::UserAgent that overrides the get_basic_credentials() method. Study the lwp-request program for an example of this.

COOKIES

Some sites like to play games with cookies. By default LWP ignores cookies provided by the servers it visits. LWP will collect cookies and respond to cookie requests if you set up a cookie jar.

  use LWP::UserAgent;
  use HTTP::Cookies;

  $ua = LWP::UserAgent->new;
  $ua->cookie_jar(HTTP::Cookies->new(file => "lwpcookies.txt",
                                     autosave => 1));

  # and then send requests just as you used to do
  $res = $ua->request(HTTP::Request->new(GET => "http://www.yahoo.no"));
  print $res->status_line, "\n";

As you visit sites that send you cookies to keep, then the file lwpcookies.txt" will grow.

HTTPS

URLs with https scheme are accessed in exactly the same way as with http scheme, provided that an SSL interface module for LWP has been properly installed (see the README.SSL file found in the libwww-perl distribution for more details). If no SSL interface is installed for LWP to use, then you will get "501 Protocol scheme 'https' is not supported" errors when accessing such URLs.

Here's an example of fetching and printing a WWW page using SSL:

  use LWP::UserAgent;

  my $ua = LWP::UserAgent->new;
  my $req = HTTP::Request->new(GET => 'https://www.helsinki.fi/');
  my $res = $ua->request($req);
  if ($res->is_success) {
      print $res->as_string;
  }
  else {
      print "Failed: ", $res->status_line, "\n";
  }

MIRRORING

If you want to mirror documents from a WWW server, then try to run code similar to this at regular intervals:

  use LWP::Simple;

  %mirrors = (
     'http://www.sn.no/'             => 'sn.html',
     'http://www.perl.com/'          => 'perl.html',
     'http://www.sn.no/libwww-perl/' => 'lwp.html',
     'gopher://gopher.sn.no/'        => 'gopher.html',
  );

  while (($url, $localfile) = each(%mirrors)) {
     mirror($url, $localfile);
  }

Or, as a perl one-liner:

  perl -MLWP::Simple -e 'mirror("http://www.perl.com/", "perl.html")';

The document will not be transfered unless it has been updated.

LARGE DOCUMENTS

If the document you want to fetch is too large to be kept in memory, then you have two alternatives. You can instruct the library to write the document content to a file (second $ua->request() argument is a file name):

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;

  my $req = HTTP::Request->new(GET =>
                'http://www.linpro.no/lwp/libwww-perl-5.46.tar.gz');
  $res = $ua->request($req, "libwww-perl.tar.gz");
  if ($res->is_success) {
     print "ok\n";
  }
  else {
     print $res->status_line, "\n";
  }

Or you can process the document as it arrives (second $ua->request() argument is a code reference):

  use LWP::UserAgent;
  $ua = LWP::UserAgent->new;
  $URL = 'ftp://ftp.unit.no/pub/rfc/rfc-index.txt';

  my $expected_length;
  my $bytes_received = 0;
  my $res =
     $ua->request(HTTP::Request->new(GET => $URL),
               sub {
                   my($chunk, $res) = @_;
                   $bytes_received += length($chunk);
                   unless (defined $expected_length) {
                      $expected_length = $res->content_length || 0;
                   }
                   if ($expected_length) {
                        printf STDERR "%d%% - ",
                                  100 * $bytes_received / $expected_length;
                   }
                   print STDERR "$bytes_received bytes received\n";

                   # XXX Should really do something with the chunk itself
                   # print $chunk;
                                  });
                      print $res->status_line, "\n";

COPYRIGHT

Copyright 1996-2001, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


lwptut -- An LWP Tutorial

    • Getting documents with LWP::Simple
    • The Basics of the LWP Class Model
    • Adding Other HTTP Request Headers
    • Enabling Cookies
    • Posting Form Data
    • Sending GET Form Data
    • Absolutizing URLs
    • Other Browser Attributes
    • Writing Polite Robots
    • Using Proxies
    • HTTP Authentication
    • Accessing HTTPS URLs
    • Getting Large Documents
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

lwptut -- An LWP Tutorial

DESCRIPTION

LWP (short for "Library for WWW in Perl") is a very popular group of Perl modules for accessing data on the Web. Like most Perl module-distributions, each of LWP's component modules comes with documentation that is a complete reference to its interface. However, there are so many modules in LWP that it's hard to know where to start looking for information on how to do even the simplest most common things.

Really introducing you to using LWP would require a whole book -- a book that just happens to exist, called Perl & LWP. But this article should give you a taste of how you can go about some common tasks with LWP.

Getting documents with LWP::Simple

If you just want to get what's at a particular URL, the simplest way to do it is LWP::Simple's functions.

In a Perl program, you can call its get($url) function. It will try getting that URL's content. If it works, then it'll return the content; but if there's some error, it'll return undef.

  my $url = 'http://freshair.npr.org/dayFA.cfm?todayDate=current';
    # Just an example: the URL for the most recent /Fresh Air/ show

  use LWP::Simple;
  my $content = get $url;
  die "Couldn't get $url" unless defined $content;

  # Then go do things with $content, like this:

  if($content =~ m/jazz/i) {
    print "They're talking about jazz today on Fresh Air!\n";
  }
  else {
    print "Fresh Air is apparently jazzless today.\n";
  }

The handiest variant on get is getprint, which is useful in Perl one-liners. If it can get the page whose URL you provide, it sends it to STDOUT; otherwise it complains to STDERR.

  % perl -MLWP::Simple -e "getprint 'http://cpan.org/RECENT'"

That is the URL of a plaintext file that lists new files in CPAN in the past two weeks. You can easily make it part of a tidy little shell command, like this one that mails you the list of new Acme:: modules:

  % perl -MLWP::Simple -e "getprint 'http://cpan.org/RECENT'"  \
     | grep "/by-module/Acme" | mail -s "New Acme modules! Joy!" $USER

There are other useful functions in LWP::Simple, including one function for running a HEAD request on a URL (useful for checking links, or getting the last-revised time of a URL), and two functions for saving/mirroring a URL to a local file. See the LWP::Simple documentation for the full details, or chapter 2 of Perl & LWP for more examples.

The Basics of the LWP Class Model

LWP::Simple's functions are handy for simple cases, but its functions don't support cookies or authorization, don't support setting header lines in the HTTP request, generally don't support reading header lines in the HTTP response (notably the full HTTP error message, in case of an error). To get at all those features, you'll have to use the full LWP class model.

While LWP consists of dozens of classes, the main two that you have to understand are the LWP::UserAgent manpage and the HTTP::Response manpage. LWP::UserAgent is a class for "virtual browsers" which you use for performing requests, and the HTTP::Response manpage is a class for the responses (or error messages) that you get back from those requests.

The basic idiom is $response = $browser->get($url), or more fully illustrated:

  # Early in your program:

  use LWP 5.64; # Loads all important LWP classes, and makes
                #  sure your version is reasonably recent.

  my $browser = LWP::UserAgent->new;

  ...

  # Then later, whenever you need to make a get request:
  my $url = 'http://freshair.npr.org/dayFA.cfm?todayDate=current';

  my $response = $browser->get( $url );
  die "Can't get $url -- ", $response->status_line
   unless $response->is_success;

  die "Hey, I was expecting HTML, not ", $response->content_type
   unless $response->content_type eq 'text/html';
     # or whatever content-type you're equipped to deal with

  # Otherwise, process the content somehow:

  if($response->decoded_content =~ m/jazz/i) {
    print "They're talking about jazz today on Fresh Air!\n";
  }
  else {
    print "Fresh Air is apparently jazzless today.\n";
  }

There are two objects involved: $browser, which holds an object of class LWP::UserAgent, and then the $response object, which is of class HTTP::Response. You really need only one browser object per program; but every time you make a request, you get back a new HTTP::Response object, which will have some interesting attributes:

  • A status code indicating success or failure (which you can test with $response->is_success).

  • An HTTP status line that is hopefully informative if there's failure (which you can see with $response->status_line, returning something like "404 Not Found").

  • A MIME content-type like "text/html", "image/gif", "application/xml", etc., which you can see with $response->content_type

  • The actual content of the response, in $response->decoded_content. If the response is HTML, that's where the HTML source will be; if it's a GIF, then $response->decoded_content will be the binary GIF data.

  • And dozens of other convenient and more specific methods that are documented in the docs for the HTML::Response manpage, and its superclasses the HTML::Message manpage and the HTML::Headers manpage.

Adding Other HTTP Request Headers

The most commonly used syntax for requests is $response = $browser->get($url), but in truth, you can add extra HTTP header lines to the request by adding a list of key-value pairs after the URL, like so:

  $response = $browser->get( $url, $key1, $value1, $key2, $value2, ... );

For example, here's how to send some more Netscape-like headers, in case you're dealing with a site that would otherwise reject your request:

  my @ns_headers = (
   'User-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
   'Accept' => 'image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
   'Accept-Charset' => 'iso-8859-1,*,utf-8',
   'Accept-Language' => 'en-US',
  );

  ...

  $response = $browser->get($url, @ns_headers);

If you weren't reusing that array, you could just go ahead and do this:

  $response = $browser->get($url,
   'User-Agent' => 'Mozilla/4.76 [en] (Win98; U)',
   'Accept' => 'image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */*',
   'Accept-Charset' => 'iso-8859-1,*,utf-8',
   'Accept-Language' => 'en-US',
  );

If you were only ever changing the 'User-Agent' line, you could just change the $browser object's default line from "libwww-perl/5.65" (or the like) to whatever you like, using the LWP::UserAgent agent method:

   $browser->agent('Mozilla/4.76 [en] (Win98; U)');

Enabling Cookies

A default LWP::UserAgent object acts like a browser with its cookies support turned off. There are various ways of turning it on, by setting its cookie_jar attribute. A "cookie jar" is an object representing a little database of all the HTTP cookies that a browser can know about. It can correspond to a file on disk (the way Netscape uses its cookies.txt file), or it can be just an in-memory object that starts out empty, and whose collection of cookies will disappear once the program is finished running.

To give a browser an in-memory empty cookie jar, you set its cookie_jar attribute like so:

  $browser->cookie_jar({});

To give it a copy that will be read from a file on disk, and will be saved to it when the program is finished running, set the cookie_jar attribute like this:

  use HTTP::Cookies;
  $browser->cookie_jar( HTTP::Cookies->new(
    'file' => '/some/where/cookies.lwp',
        # where to read/write cookies
    'autosave' => 1,
        # save it to disk when done
  ));

That file will be an LWP-specific format. If you want to be access the cookies in your Netscape cookies file, you can use the HTTP::Cookies::Netscape class:

  use HTTP::Cookies;
    # yes, loads HTTP::Cookies::Netscape too

  $browser->cookie_jar( HTTP::Cookies::Netscape->new(
    'file' => 'c:/Program Files/Netscape/Users/DIR-NAME-HERE/cookies.txt',
        # where to read cookies
  ));

You could add an 'autosave' => 1 line as further above, but at time of writing, it's uncertain whether Netscape might discard some of the cookies you could be writing back to disk.

Posting Form Data

Many HTML forms send data to their server using an HTTP POST request, which you can send with this syntax:

 $response = $browser->post( $url,
   [
     formkey1 => value1,
     formkey2 => value2,
     ...
   ],
 );

Or if you need to send HTTP headers:

 $response = $browser->post( $url,
   [
     formkey1 => value1,
     formkey2 => value2,
     ...
   ],
   headerkey1 => value1,
   headerkey2 => value2,
 );

For example, the following program makes a search request to AltaVista (by sending some form data via an HTTP POST request), and extracts from the HTML the report of the number of matches:

  use strict;
  use warnings;
  use LWP 5.64;
  my $browser = LWP::UserAgent->new;

  my $word = 'tarragon';

  my $url = 'http://www.altavista.com/sites/search/web';
  my $response = $browser->post( $url,
    [ 'q' => $word,  # the Altavista query string
      'pg' => 'q', 'avkw' => 'tgz', 'kl' => 'XX',
    ]
  );
  die "$url error: ", $response->status_line
   unless $response->is_success;
  die "Weird content type at $url -- ", $response->content_type
   unless $response->content_type eq 'text/html';

  if( $response->decoded_content =~ m{AltaVista found ([0-9,]+) results} ) {
    # The substring will be like "AltaVista found 2,345 results"
    print "$word: $1\n";
  }
  else {
    print "Couldn't find the match-string in the response\n";
  }

Sending GET Form Data

Some HTML forms convey their form data not by sending the data in an HTTP POST request, but by making a normal GET request with the data stuck on the end of the URL. For example, if you went to imdb.com and ran a search on "Blade Runner", the URL you'd see in your browser window would be:

  http://us.imdb.com/Tsearch?title=Blade%20Runner&restrict=Movies+and+TV

To run the same search with LWP, you'd use this idiom, which involves the URI class:

  use URI;
  my $url = URI->new( 'http://us.imdb.com/Tsearch' );
    # makes an object representing the URL

  $url->query_form(  # And here the form data pairs:
    'title'    => 'Blade Runner',
    'restrict' => 'Movies and TV',
  );

  my $response = $browser->get($url);

See chapter 5 of Perl & LWP for a longer discussion of HTML forms and of form data, and chapters 6 through 9 for a longer discussion of extracting data from HTML.

Absolutizing URLs

The URI class that we just mentioned above provides all sorts of methods for accessing and modifying parts of URLs (such as asking sort of URL it is with $url->scheme, and asking what host it refers to with < $url-host >>, and so on, as described in the docs for the URI class. However, the methods of most immediate interest are the query_form method seen above, and now the new_abs method for taking a probably-relative URL string (like "../foo.html") and getting back an absolute URL (like "http://www.perl.com/stuff/foo.html"), as shown here:

  use URI;
  $abs = URI->new_abs($maybe_relative, $base);

For example, consider this program that matches URLs in the HTML list of new modules in CPAN:

  use strict;
  use warnings;
  use LWP;
  my $browser = LWP::UserAgent->new;

  my $url = 'http://www.cpan.org/RECENT.html';
  my $response = $browser->get($url);
  die "Can't get $url -- ", $response->status_line
   unless $response->is_success;

  my $html = $response->decoded_content;
  while( $html =~ m/<A HREF=\"(.*?)\"/g ) {
    print "$1\n";
  }

When run, it emits output that starts out something like this:

  MIRRORING.FROM
  RECENT
  RECENT.html
  authors/00whois.html
  authors/01mailrc.txt.gz
  authors/id/A/AA/AASSAD/CHECKSUMS
  ...

However, if you actually want to have those be absolute URLs, you can use the URI module's new_abs method, by changing the while loop to this:

  while( $html =~ m/<A HREF=\"(.*?)\"/g ) {
    print URI->new_abs( $1, $response->base ) ,"\n";
  }

(The $response->base method from HTTP::Message is for returning what URL should be used for resolving relative URLs -- it's usually just the same as the URL that you requested.)

That program then emits nicely absolute URLs:

  http://www.cpan.org/MIRRORING.FROM
  http://www.cpan.org/RECENT
  http://www.cpan.org/RECENT.html
  http://www.cpan.org/authors/00whois.html
  http://www.cpan.org/authors/01mailrc.txt.gz
  http://www.cpan.org/authors/id/A/AA/AASSAD/CHECKSUMS
  ...

See chapter 4 of Perl & LWP for a longer discussion of URI objects.

Of course, using a regexp to match hrefs is a bit simplistic, and for more robust programs, you'll probably want to use an HTML-parsing module like the HTML::LinkExtor manpage or the HTML::TokeParser manpage or even maybe the HTML::TreeBuilder manpage.

Other Browser Attributes

LWP::UserAgent objects have many attributes for controlling how they work. Here are a few notable ones:

  • $browser->timeout(15);

    This sets this browser object to give up on requests that don't answer within 15 seconds.

  • $browser->protocols_allowed( [ 'http', 'gopher'] );

    This sets this browser object to not speak any protocols other than HTTP and gopher. If it tries accessing any other kind of URL (like an "ftp:" or "mailto:" or "news:" URL), then it won't actually try connecting, but instead will immediately return an error code 500, with a message like "Access to 'ftp' URIs has been disabled".

  • use LWP::ConnCache; $browser->conn_cache(LWP::ConnCache->new());

    This tells the browser object to try using the HTTP/1.1 "Keep-Alive" feature, which speeds up requests by reusing the same socket connection for multiple requests to the same server.

  • $browser->agent( 'SomeName/1.23 (more info here maybe)' )

    This changes how the browser object will identify itself in the default "User-Agent" line is its HTTP requests. By default, it'll send "libwww-perl/versionnumber", like "libwww-perl/5.65". You can change that to something more descriptive like this:

      $browser->agent( 'SomeName/3.14 (contact@robotplexus.int)' );

    Or if need be, you can go in disguise, like this:

      $browser->agent( 'Mozilla/4.0 (compatible; MSIE 5.12; Mac_PowerPC)' );

  • push @{ $ua->requests_redirectable }, 'POST';

    This tells this browser to obey redirection responses to POST requests (like most modern interactive browsers), even though the HTTP RFC says that should not normally be done.

For more options and information, see the full documentation for LWP::UserAgent.

Writing Polite Robots

If you want to make sure that your LWP-based program respects robots.txt files and doesn't make too many requests too fast, you can use the LWP::RobotUA class instead of the LWP::UserAgent class.

LWP::RobotUA class is just like LWP::UserAgent, and you can use it like so:

  use LWP::RobotUA;
  my $browser = LWP::RobotUA->new('YourSuperBot/1.34', 'you@yoursite.com');
    # Your bot's name and your email address

  my $response = $browser->get($url);

But HTTP::RobotUA adds these features:

  • If the robots.txt on $url's server forbids you from accessing $url, then the $browser object (assuming it's of class LWP::RobotUA) won't actually request it, but instead will give you back (in $response) a 403 error with a message "Forbidden by robots.txt". That is, if you have this line:

      die "$url -- ", $response->status_line, "\nAborted"
   unless $response->is_success;

    then the program would die with an error message like this:

      http://whatever.site.int/pith/x.html -- 403 Forbidden by robots.txt
  Aborted at whateverprogram.pl line 1234

  • If this $browser object sees that the last time it talked to $url's server was too recently, then it will pause (via sleep) to avoid making too many requests too often. How long it will pause for, is by default one minute -- but you can control it with the < $browser-delay( minutes ) >> attribute.

    For example, this code:

      $browser->delay( 7/60 );

    ...means that this browser will pause when it needs to avoid talking to any given server more than once every 7 seconds.

For more options and information, see the full documentation for LWP::RobotUA.

Using Proxies

In some cases, you will want to (or will have to) use proxies for accessing certain sites and/or using certain protocols. This is most commonly the case when your LWP program is running (or could be running) on a machine that is behind a firewall.

To make a browser object use proxies that are defined in the usual environment variables (HTTP_PROXY, etc.), just call the env_proxy on a user-agent object before you go making any requests on it. Specifically:

  use LWP::UserAgent;
  my $browser = LWP::UserAgent->new;

  # And before you go making any requests:
  $browser->env_proxy;

For more information on proxy parameters, see the LWP::UserAgent documentation, specifically the proxy, env_proxy, and no_proxy methods.

HTTP Authentication

Many web sites restrict access to documents by using "HTTP Authentication". This isn't just any form of "enter your password" restriction, but is a specific mechanism where the HTTP server sends the browser an HTTP code that says "That document is part of a protected 'realm', and you can access it only if you re-request it and add some special authorization headers to your request".

For example, the Unicode.org admins stop email-harvesting bots from harvesting the contents of their mailing list archives, by protecting them with HTTP Authentication, and then publicly stating the username and password (at http://www.unicode.org/mail-arch/) -- namely username "unicode-ml" and password "unicode".

For example, consider this URL, which is part of the protected area of the web site:

  http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html

If you access that with a browser, you'll get a prompt like "Enter username and password for 'Unicode-MailList-Archives' at server 'www.unicode.org'".

In LWP, if you just request that URL, like this:

  use LWP;
  my $browser = LWP::UserAgent->new;

  my $url =
   'http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html';
  my $response = $browser->get($url);

  die "Error: ", $response->header('WWW-Authenticate') || 'Error accessing',
    #  ('WWW-Authenticate' is the realm-name)
    "\n ", $response->status_line, "\n at $url\n Aborting"
   unless $response->is_success;

Then you'll get this error:

  Error: Basic realm="Unicode-MailList-Archives"
   401 Authorization Required
   at http://www.unicode.org/mail-arch/unicode-ml/y2002-m08/0067.html
   Aborting at auth1.pl line 9.  [or wherever]

...because the $browser doesn't know any the username and password for that realm ("Unicode-MailList-Archives") at that host ("www.unicode.org"). The simplest way to let the browser know about this is to use the credentials method to let it know about a username and password that it can try using for that realm at that host. The syntax is:

  $browser->credentials(
    'servername:portnumber',
    'realm-name',
   'username' => 'password'
  );

In most cases, the port number is 80, the default TCP/IP port for HTTP; and you usually call the credentials method before you make any requests. For example:

  $browser->credentials(
    'reports.mybazouki.com:80',
    'web_server_usage_reports',
    'plinky' => 'banjo123'
  );

So if we add the following to the program above, right after the < $browser = LWP::UserAgent-new; >> line...

  $browser->credentials(  # add this to our $browser 's "key ring"
    'www.unicode.org:80',
    'Unicode-MailList-Archives',
    'unicode-ml' => 'unicode'
  );

...then when we run it, the request succeeds, instead of causing the die to be called.

Accessing HTTPS URLs

When you access an HTTPS URL, it'll work for you just like an HTTP URL would -- if your LWP installation has HTTPS support (via an appropriate Secure Sockets Layer library). For example:

  use LWP;
  my $url = 'https://www.paypal.com/';   # Yes, HTTPS!
  my $browser = LWP::UserAgent->new;
  my $response = $browser->get($url);
  die "Error at $url\n ", $response->status_line, "\n Aborting"
   unless $response->is_success;
  print "Whee, it worked!  I got that ",
   $response->content_type, " document!\n";

If your LWP installation doesn't have HTTPS support set up, then the response will be unsuccessful, and you'll get this error message:

  Error at https://www.paypal.com/
   501 Protocol scheme 'https' is not supported
   Aborting at paypal.pl line 7.   [or whatever program and line]

If your LWP installation does have HTTPS support installed, then the response should be successful, and you should be able to consult $response just like with any normal HTTP response.

For information about installing HTTPS support for your LWP installation, see the helpful README.SSL file that comes in the libwww-perl distribution.

Getting Large Documents

When you're requesting a large (or at least potentially large) document, a problem with the normal way of using the request methods (like < $response = $browser-get($url) >>) is that the response object in memory will have to hold the whole document -- in memory. If the response is a thirty megabyte file, this is likely to be quite an imposition on this process's memory usage.

A notable alternative is to have LWP save the content to a file on disk, instead of saving it up in memory. This is the syntax to use:

  $response = $ua->get($url,
                         ':content_file' => $filespec,
                      );

For example,

  $response = $ua->get('http://search.cpan.org/',
                         ':content_file' => '/tmp/sco.html'
                      );

When you use this :content_file option, the $response will have all the normal header lines, but $response->content will be empty.

Note that this ":content_file" option isn't supported under older versions of LWP, so you should consider adding use LWP 5.66; to check the LWP version, if you think your program might run on systems with older versions.

If you need to be compatible with older LWP versions, then use this syntax, which does the same thing:

  use HTTP::Request::Common;
  $response = $ua->request( GET($url), $filespec );

SEE ALSO

Remember, this article is just the most rudimentary introduction to LWP -- to learn more about LWP and LWP-related tasks, you really must read from the following:

  • the LWP::Simple manpage -- simple functions for getting/heading/mirroring URLs

  • the LWP manpage -- overview of the libwww-perl modules

  • the LWP::UserAgent manpage -- the class for objects that represent "virtual browsers"

  • the HTTP::Response manpage -- the class for objects that represent the response to a LWP response, as in $response = $browser->get(...)

  • the HTTP::Message manpage and the HTTP::Headers manpage -- classes that provide more methods to HTTP::Response.

  • the URI manpage -- class for objects that represent absolute or relative URLs

  • the URI::Escape manpage -- functions for URL-escaping and URL-unescaping strings (like turning "this & that" to and from "this%20%26%20that").

  • the HTML::Entities manpage -- functions for HTML-escaping and HTML-unescaping strings (like turning "C. & E. Brontë" to and from "C. &amp; E. Bront&euml;")

  • the HTML::TokeParser manpage and the HTML::TreeBuilder manpage -- classes for parsing HTML

  • the HTML::LinkExtor manpage -- class for finding links in HTML documents

  • The book Perl & LWP by Sean M. Burke. O'Reilly & Associates, 2002. ISBN: 0-596-00178-9. http://www.oreilly.com/catalog/perllwp/

COPYRIGHT

Copyright 2002, Sean M. Burke. You can redistribute this document and/or modify it, but only under the same terms as Perl itself.

AUTHOR

Sean M. Burke sburke@cpan.org


List::MoreUtils - Provide the stuff missing in List::Util

  • EXPORTS
  • ENVIRONMENT
  • VERSION
  • BUGS
  • THANKS
  • TODO
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

List::MoreUtils - Provide the stuff missing in List::Util

SYNOPSIS

    use List::MoreUtils qw(any all none notall true false firstidx first_index
                           lastidx last_index insert_after insert_after_string
                           apply after after_incl before before_incl indexes
                           firstval first_value lastval last_value each_array
                           each_arrayref pairwise natatime mesh zip uniq minmax);

DESCRIPTION

List::MoreUtils provides some trivial but commonly needed functionality on lists which is not going to go into List::Util.

All of the below functions are implementable in only a couple of lines of Perl code. Using the functions from this module however should give slightly better performance as everything is implemented in C. The pure-Perl implementation of these functions only serves as a fallback in case the C portions of this module couldn't be compiled on this machine.

any BLOCK LIST

Returns a true value if any item in LIST meets the criterion given through BLOCK. Sets $_ for each item in LIST in turn:

    print "At least one value undefined"
        if any { !defined($_) } @list;

Returns false otherwise, or undef if LIST is empty.

all BLOCK LIST

Returns a true value if all items in LIST meet the criterion given through BLOCK. Sets $_ for each item in LIST in turn:

    print "All items defined"
        if all { defined($_) } @list;

Returns false otherwise, or undef if LIST is empty.

none BLOCK LIST

Logically the negation of any. Returns a true value if no item in LIST meets the criterion given through BLOCK. Sets $_ for each item in LIST in turn:

    print "No value defined"
        if none { defined($_) } @list;

Returns false otherwise, or undef if LIST is empty.

notall BLOCK LIST

Logically the negation of all. Returns a true value if not all items in LIST meet the criterion given through BLOCK. Sets $_ for each item in LIST in turn:

    print "Not all values defined"
        if notall { defined($_) } @list;

Returns false otherwise, or undef if LIST is empty.

true BLOCK LIST

Counts the number of elements in LIST for which the criterion in BLOCK is true. Sets $_ for each item in LIST in turn:

    printf "%i item(s) are defined", true { defined($_) } @list;
false BLOCK LIST

Counts the number of elements in LIST for which the criterion in BLOCK is false. Sets $_ for each item in LIST in turn:

    printf "%i item(s) are not defined", false { defined($_) } @list;
firstidx BLOCK LIST
first_index BLOCK LIST

Returns the index of the first element in LIST for which the criterion in BLOCK is true. Sets $_ for each item in LIST in turn:

    my @list = (1, 4, 3, 2, 4, 6);
    printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
    __END__
    item with index 1 in list is 4

    Returns C<-1> if no such item could be found.

first_index is an alias for firstidx.

lastidx BLOCK LIST
last_index BLOCK LIST

Returns the index of the last element in LIST for which the criterion in BLOCK is true. Sets $_ for each item in LIST in turn:

    my @list = (1, 4, 3, 2, 4, 6);
    printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
    __END__
    item with index 4 in list is 4

Returns -1 if no such item could be found.

last_index is an alias for lastidx.

insert_after BLOCK VALUE LIST

Inserts VALUE after the first item in LIST for which the criterion in BLOCK is true. Sets $_ for each item in LIST in turn.

    my @list = qw/This is a list/;
    insert_after { $_ eq "a" } "longer" => @list;
    print "@list";
    __END__
    This is a longer list
insert_after_string STRING VALUE LIST

Inserts VALUE after the first item in LIST which is equal to STRING.

    my @list = qw/This is a list/;
    insert_after_string "a", "longer" => @list;
    print "@list";
    __END__
    This is a longer list
apply BLOCK LIST

Applies BLOCK to each item in LIST and returns a list of the values after BLOCK has been applied. In scalar context, the last element is returned. This function is similar to map but will not modify the elements of the input list:

    my @list = (1 .. 4);
    my @mult = apply { $_ *= 2 } @list;
    print "\@list = @list\n";
    print "\@mult = @mult\n";
    __END__
    @list = 1 2 3 4
    @mult = 2 4 6 8

Think of it as syntactic sugar for

    for (my @mult = @list) { $_ *= 2 }
after BLOCK LIST

Returns a list of the values of LIST after (and not including) the point where BLOCK returns a true value. Sets $_ for each element in LIST in turn.

    @x = after { $_ % 5 == 0 } (1..9);    # returns 6, 7, 8, 9
after_incl BLOCK LIST

Same as after but also inclues the element for which BLOCK is true.

before BLOCK LIST

Returns a list of values of LIST upto (and not including) the point where BLOCK returns a true value. Sets $_ for each element in LIST in turn.

before_incl BLOCK LIST

Same as before but also includes the element for which BLOCK is true.

indexes BLOCK LIST

Evaluates BLOCK for each element in LIST (assigned to $_) and returns a list of the indices of those elements for which BLOCK returned a true value. This is just like grep only that it returns indices instead of values:

    @x = indexes { $_ % 2 == 0 } (1..10);   # returns 1, 3, 5, 7, 9
firstval BLOCK LIST
first_value BLOCK LIST

Returns the first element in LIST for which BLOCK evaluates to true. Each element of LIST is set to $_ in turn. Returns undef if no such element has been found.

first_val is an alias for firstval.

lastval BLOCK LIST
last_value BLOCK LIST

Returns the last value in LIST for which BLOCK evaluates to true. Each element of LIST is set to $_ in turn. Returns undef if no such element has been found.

last_val is an alias for lastval.

pairwise BLOCK ARRAY1 ARRAY2

Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and returns a new list consisting of BLOCK's return values. The two elements are set to $a and $b. Note that those two are aliases to the original value so changing them will modify the input arrays.

    @a = (1 .. 5);
    @b = (11 .. 15);
    @x = pairwise { $a + $b } @a, @b;   # returns 12, 14, 16, 18, 20

    # mesh with pairwise
    @a = qw/a b c/;
    @b = qw/1 2 3/;
    @x = pairwise { ($a, $b) } @a, @b;  # returns a, 1, b, 2, c, 3
each_array ARRAY1 ARRAY2 ...

Creates an array iterator to return the elements of the list of arrays ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the first time it is called, it returns the first element of each array. The next time, it returns the second elements. And so on, until all elements are exhausted.

This is useful for looping over more than one array at once:

    my $ea = each_array(@a, @b, @c);
    while ( my ($a, $b, $c) = $ea->() )   { .... }

The iterator returns the empty list when it reached the end of all arrays.

If the iterator is passed an argument of 'index', then it retuns the index of the last fetched set of values, as a scalar.

each_arrayref LIST

Like each_array, but the arguments are references to arrays, not the plain arrays.

natatime BLOCK LIST

Creates an array iterator, for looping over an array in chunks of $n items at a time. (n at a time, get it?). An example is probably a better explanation than I could give in words.

Example:

    my @x = ('a' .. 'g');
    my $it = natatime 3, @x;
    while (my @vals = $it->())
    {
        print "@vals\n";
    }

This prints

    a b c
    d e f
    g
mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
zip ARRAY1 ARRAY2 [ ARRAY3 ... ]

Returns a list consisting of the first elements of each array, then the second, then the third, etc, until all arrays are exhausted.

Examples:

    @x = qw/a b c d/;
    @y = qw/1 2 3 4/;
    @z = mesh @x, @y;       # returns a, 1, b, 2, c, 3, d, 4

    @a = ('x');
    @b = ('1', '2');
    @c = qw/zip zap zot/;
    @d = mesh @a, @b, @c;   # x, 1, zip, undef, 2, zap, undef, undef, zot

zip is an alias for mesh.

uniq LIST

Returns a new list by stripping duplicate values in LIST. The order of elements in the returned list is the same as in LIST. In scalar context, returns the number of unique elements in LIST.

    my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
    my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
minmax LIST

Calculates the minimum and maximum of LIST and returns a two element list with the first element being the minimum and the second the maximum. Returns the empty list if LIST was empty.

The minmax algorithm differs from a naive iteration over the list where each element is compared to two values being the so far calculated min and max value in that it only requires 3n/2 - 2 comparisons. Thus it is the most efficient possible algorithm.

However, the Perl implementation of it has some overhead simply due to the fact that there are more lines of Perl code involved. Therefore, LIST needs to be fairly big in order for minmax to win over a naive implementation. This limitation does not apply to the XS version.

part BLOCK LIST

Partitions LIST based on the return value of BLOCK which denotes into which partition the current value is put.

Returns a list of the partitions thusly created. Each partition created is a reference to an array.

    my $i = 0;
    my @part = part { $i++ % 2 } 1 .. 8;   # returns [1, 3, 5, 7], [2, 4, 6, 8]

You can have a sparse list of partitions as well where non-set partitions will be undef:

    my @part = part { 2 } 1 .. 10;          # returns undef, undef, [ 1 .. 10 ]

Be careful with negative values, though:

    my @part = part { -1 } 1 .. 10;
    __END__
    Modification of non-creatable array value attempted, subscript -1 ...

Negative values are only ok when they refer to a partition previously created:

    my @idx = (0, 1, -1);
    my $i = 0;
    my @part = part { $idx[$++ % 3] } 1 .. 8;   # [1, 4, 7], [2, 3, 5, 6, 8]

EXPORTS

Nothing by default. To import all of this module's symbols, do the conventional

    use List::MoreUtils qw/:all/;

It may make more sense though to only import the stuff your program actually needs:

    use List::MoreUtils qw/any firstidx/;

ENVIRONMENT

When LIST_MOREUTILS_PP is set, the module will always use the pure-Perl implementation and not the XS one. This environment variable is really just there for the test-suite to force testing the Perl implementation, and possibly for reporting of bugs. I don't see any reason to use it in a production environment.

VERSION

This is version 0.21.

BUGS

There is a problem with a bug in 5.6.x perls. It is a syntax error to write things like:

    my @x = apply { s/foo/bar/ } qw/foo bar baz/;

It has to be written as either

    my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';

or

    my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;

Perl5.5.x and perl5.8.x don't suffer from this limitation.

If you have a functionality that you could imagine being in this module, please drop me a line. This module's policy will be less strict than List::Util's when it comes to additions as it isn't a core module.

When you report bugs, it would be nice if you could additionally give me the output of your program with the environment variable LIST_MOREUTILS_PP set to a true value. That way I know where to look for the problem (in XS, pure-Perl or possibly both).

THANKS

Credits go to a number of people: Steve Purkis for giving me namespace advice and James Keenan and Terrence Branno for their effort of keeping the CPAN tidier by making List::Utils obsolete.

Brian McCauley suggested the inclusion of apply() and provided the pure-Perl implementation for it.

Eric J. Roode asked me to add all functions from his module List::MoreUtil into this one. With minor modifications, the pure-Perl implementations of those are by him.

The bunch of people who almost immediately pointed out the many problems with the glitchy 0.07 release (Slaven Rezic, Ron Savage, CPAN testers).

A particularly nasty memory leak was spotted by Thomas A. Lowery.

Lars Thegler made me aware of problems with older Perl versions.

Anno Siegel de-orphaned each_arrayref().

David Filmer made me aware of a problem in each_arrayref that could ultimately lead to a segfault.

Ricardo Signes suggested the inclusion of part() and provided the Perl-implementation.

Robin Huston kindly fixed a bug in perl's MULTICALL API to make the XS-implementation of part() work.

TODO

A pile of requests from other people is still pending further processing in my mailbox. This includes:

  • uniq_by(&@)

    Use code-reference to extract a key based on which the uniqueness is determined. Suggested by Aaron Crane.

  • delete_index
  • random_item
  • random_item_delete_index
  • list_diff_hash
  • list_diff_inboth
  • list_diff_infirst
  • list_diff_insecond

    These were all suggested by Dan Muey.

  • listify

    Always return a flat list when either a simple scalar value was passed or an array-reference. Suggested by Mark Summersault.

SEE ALSO

the List::Util manpage

AUTHOR

Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>

COPYRIGHT AND LICENSE

Copyright (C) 2004-2006 by Tassilo von Parseval

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.


List::Util - A selection of general-utility list subroutines

  • KNOWN BUGS
  • SUGGESTED ADDITIONS
  • COPYRIGHT

NAME

List::Util - A selection of general-utility list subroutines

SYNOPSIS

    use List::Util qw(first max maxstr min minstr reduce shuffle sum);

DESCRIPTION

List::Util contains a selection of subroutines that people have expressed would be nice to have in the perl core, but the usage would not really be high enough to warrant the use of a keyword, and the size so small such that being individual extensions would be wasteful.

By default List::Util does not export any subroutines. The subroutines defined are

first BLOCK LIST

Similar to grep in that it evaluates BLOCK setting $_ to each element of LIST in turn. first returns the first element where the result from BLOCK is a true value. If BLOCK never returns true or LIST was empty then undef is returned.

    $foo = first { defined($_) } @list    # first defined value in @list
    $foo = first { $_ > $value } @list    # first value in @list which
                                          # is greater than $value

This function could be implemented using reduce like this

    $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list

for example wanted() could be defined() which would return the first defined value in @list

max LIST

Returns the entry in the list with the highest numerical value. If the list is empty then undef is returned.

    $foo = max 1..10                # 10
    $foo = max 3,9,12               # 12
    $foo = max @bar, @baz           # whatever

This function could be implemented using reduce like this

    $foo = reduce { $a > $b ? $a : $b } 1..10
maxstr LIST

Similar to max, but treats all the entries in the list as strings and returns the highest string as defined by the gt operator. If the list is empty then undef is returned.

    $foo = maxstr 'A'..'Z'          # 'Z'
    $foo = maxstr "hello","world"   # "world"
    $foo = maxstr @bar, @baz        # whatever

This function could be implemented using reduce like this

    $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
min LIST

Similar to max but returns the entry in the list with the lowest numerical value. If the list is empty then undef is returned.

    $foo = min 1..10                # 1
    $foo = min 3,9,12               # 3
    $foo = min @bar, @baz           # whatever

This function could be implemented using reduce like this

    $foo = reduce { $a < $b ? $a : $b } 1..10
minstr LIST

Similar to min, but treats all the entries in the list as strings and returns the lowest string as defined by the lt operator. If the list is empty then undef is returned.

    $foo = minstr 'A'..'Z'          # 'A'
    $foo = minstr "hello","world"   # "hello"
    $foo = minstr @bar, @baz        # whatever

This function could be implemented using reduce like this

    $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
reduce BLOCK LIST

Reduces LIST by calling BLOCK multiple times, setting $a and $b each time. The first call will be with $a and $b set to the first two elements of the list, subsequent calls will be done by setting $a to the result of the previous call and $b to the next element in the list.

Returns the result of the last call to BLOCK. If LIST is empty then undef is returned. If LIST only contains one element then that element is returned and BLOCK is not executed.

    $foo = reduce { $a < $b ? $a : $b } 1..10       # min
    $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
    $foo = reduce { $a + $b } 1 .. 10               # sum
    $foo = reduce { $a . $b } @bar                  # concat
shuffle LIST

Returns the elements of LIST in a random order

    @cards = shuffle 0..51      # 0..51 in a random order
sum LIST

Returns the sum of all the elements in LIST. If LIST is empty then undef is returned.

    $foo = sum 1..10                # 55
    $foo = sum 3,9,12               # 24
    $foo = sum @bar, @baz           # whatever

This function could be implemented using reduce like this

    $foo = reduce { $a + $b } 1..10

KNOWN BUGS

With perl versions prior to 5.005 there are some cases where reduce will return an incorrect result. This will show up as test 7 of reduce.t failing.

SUGGESTED ADDITIONS

The following are additions that have been requested, but I have been reluctant to add due to them being very simple to implement in perl

  # One argument is true

  sub any { $_ && return 1 for @_; 0 }

  # All arguments are true

  sub all { $_ || return 0 for @_; 1 }

  # All arguments are false

  sub none { $_ && return 0 for @_; 1 }

  # One argument is false

  sub notall { $_ || return 1 for @_; 0 }

  # How many elements are true

  sub true { scalar grep { $_ } @_ }

  # How many elements are false

  sub false { scalar grep { !$_ } @_ }

COPYRIGHT

Copyright (c) 1997-2005 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Locale::Constants - constants for Locale codes

  • KNOWN BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Locale::Constants - constants for Locale codes

SYNOPSIS

    use Locale::Constants;

    $codeset = LOCALE_CODE_ALPHA_2;

DESCRIPTION

Locale::Constants defines symbols which are used in the four modules from the Locale-Codes distribution:

        Locale::Language
        Locale::Country
        Locale::Currency
        Locale::Script

Note: at the moment only Locale::Country and Locale::Script support more than one code set.

The symbols defined are used to specify which codes you want to be used:

        LOCALE_CODE_ALPHA_2
        LOCALE_CODE_ALPHA_3
        LOCALE_CODE_NUMERIC

You shouldn't have to use this module directly yourself - it is used by the three Locale modules, which in turn export the symbols.

KNOWN BUGS AND LIMITATIONS

None at the moment.

SEE ALSO

Locale::Language

Codes for identification of languages.

Locale::Country

Codes for identification of countries.

Locale::Script

Codes for identification of scripts.

Locale::Currency

Codes for identification of currencies and funds.

AUTHOR

Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (C) 2002-2004, Neil Bowers.

Copyright (C) 2001, Canon Research Centre Europe (CRE).

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Locale::Country - ISO codes for country identification

  • CONVERSION ROUTINES
  • QUERY ROUTINES
  • SEMI-PRIVATE ROUTINES
    • alias_code
    • rename_country
  • EXAMPLES
  • DOMAIN NAMES
  • KNOWN BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Locale::Country - ISO codes for country identification (ISO 3166)

SYNOPSIS

    use Locale::Country;

    $country = code2country('jp');        # $country gets 'Japan'
    $code    = country2code('Norway');    # $code gets 'no'

    @codes   = all_country_codes();
    @names   = all_country_names();

    # semi-private routines
    Locale::Country::alias_code('uk' => 'gb');
    Locale::Country::rename_country('gb' => 'Great Britain');

DESCRIPTION

The Locale::Country module provides access to the ISO codes for identifying countries, as defined in ISO 3166-1. You can either access the codes via the conversion routines (described below), or with the two functions which return lists of all country codes or all country names.

There are three different code sets you can use for identifying countries:

alpha-2

Two letter codes, such as 'tv' for Tuvalu. This code set is identified with the symbol LOCALE_CODE_ALPHA_2.

alpha-3

Three letter codes, such as 'brb' for Barbados. This code set is identified with the symbol LOCALE_CODE_ALPHA_3.

numeric

Numeric codes, such as 064 for Bhutan. This code set is identified with the symbol LOCALE_CODE_NUMERIC.

All of the routines take an optional additional argument which specifies the code set to use. If not specified, it defaults to the two-letter codes. This is partly for backwards compatibility (previous versions of this module only supported the alpha-2 codes), and partly because they are the most widely used codes.

The alpha-2 and alpha-3 codes are not case-dependent, so you can use 'BO', 'Bo', 'bO' or 'bo' for Bolivia. When a code is returned by one of the functions in this module, it will always be lower-case.

As of version 2.00, Locale::Country supports variant names for countries. So, for example, the country code for "United States" is "us", so country2code('United States') returns 'us'. Now the following will also return 'us':

    country2code('United States of America')
    country2code('USA')

CONVERSION ROUTINES

There are three conversion routines: code2country(), country2code(), and country_code2code().

code2country( CODE, [ CODESET ] )

This function takes a country code and returns a string which contains the name of the country identified. If the code is not a valid country code, as defined by ISO 3166, then undef will be returned:

    $country = code2country('fi');
country2code( STRING, [ CODESET ] )

This function takes a country name and returns the corresponding country code, if such exists. If the argument could not be identified as a country name, then undef will be returned:

    $code = country2code('Norway', LOCALE_CODE_ALPHA_3);
    # $code will now be 'nor'

The case of the country name is not important. See the section KNOWN BUGS AND LIMITATIONS below.

country_code2code( CODE, CODESET, CODESET )

This function takes a country code from one code set, and returns the corresponding code from another code set.

    $alpha2 = country_code2code('fin',
                 LOCALE_CODE_ALPHA_3, LOCALE_CODE_ALPHA_2);
    # $alpha2 will now be 'fi'

If the code passed is not a valid country code in the first code set, or if there isn't a code for the corresponding country in the second code set, then undef will be returned.

QUERY ROUTINES

There are two function which can be used to obtain a list of all codes, or all country names:

all_country_codes( [ CODESET ] )

Returns a list of all two-letter country codes. The codes are guaranteed to be all lower-case, and not in any particular order.

all_country_names( [ CODESET ] )

Returns a list of all country names for which there is a corresponding country code in the specified code set. The names are capitalised, and not returned in any particular order.

Not all countries have alpha-3 and numeric codes - some just have an alpha-2 code, so you'll get a different number of countries depending on which code set you specify.

SEMI-PRIVATE ROUTINES

Locale::Country provides two semi-private routines for modifying the internal data. Given their status, they aren't exported by default, and so need to be called by prefixing the function name with the package name.

alias_code

Define a new code as an alias for an existing code:

    Locale::Country::alias_code( ALIAS => CODE [, CODESET ] )

This feature was added as a mechanism for handling a "uk" code. The ISO standard says that the two-letter code for "United Kingdom" is "gb", whereas domain names are all .uk.

By default the module does not understand "uk", since it is implementing an ISO standard. If you would like 'uk' to work as the two-letter code for United Kingdom, use the following:

    Locale::Country::alias_code('uk' => 'gb');

With this code, both "uk" and "gb" are valid codes for United Kingdom, with the reverse lookup returning "uk" rather than the usual "gb".

Note: this function was previously called _alias_code, but the leading underscore has been dropped. The old name will be supported for all 2.X releases for backwards compatibility.

rename_country

If the official country name just isn't good enough for you, you can rename a country. For example, the official country name for code 'gb' is 'United Kingdom'. If you want to change that, you might call:

    Locale::Country::rename_country('gb' => 'Great Britain');

This means that calling code2country('gb') will now return 'Great Britain' instead of 'United Kingdom'. The original country name is retained as an alias, so for the above example, country2code('United Kingdom') will still return 'gb'.

EXAMPLES

The following example illustrates use of the code2country() function. The user is prompted for a country code, and then told the corresponding country name:

    $| = 1;   # turn off buffering

    print "Enter country code: ";
    chop($code = <STDIN>);
    $country = code2country($code, LOCALE_CODE_ALPHA_2);
    if (defined $country)
    {
        print "$code = $country\n";
    }
    else
    {
        print "'$code' is not a valid country code!\n";
    }

DOMAIN NAMES

Most top-level domain names are based on these codes, but there are certain codes which aren't. If you are using this module to identify country from hostname, your best bet is to preprocess the country code.

For example, edu, com, gov and friends would map to us; uk would map to gb. Any others?

KNOWN BUGS AND LIMITATIONS

  • When using country2code(), the country name must currently appear exactly as it does in the source of the module. The module now supports a small number of variants.

    Possible extensions to this are: an interface for getting at the list of variant names, and regular expression matches.

  • In the current implementation, all data is read in when the module is loaded, and then held in memory. A lazy implementation would be more memory friendly.

  • Support for country names in different languages.

SEE ALSO

Locale::Language

ISO two letter codes for identification of language (ISO 639).

Locale::Script

ISO codes for identification of scripts (ISO 15924).

Locale::Currency

ISO three letter codes for identification of currencies and funds (ISO 4217).

Locale::SubCountry

ISO codes for country sub-divisions (states, counties, provinces, etc), as defined in ISO 3166-2. This module is not part of the Locale-Codes distribution, but is available from CPAN in CPAN/modules/by-module/Locale/

ISO 3166-1

The ISO standard which defines these codes.

http://www.iso.org/iso/en/prods-services/iso3166ma/index.html

Official home page for the ISO 3166 maintenance agency.

http://www.egt.ie/standards/iso3166/iso3166-1-en.html

Another useful, but not official, home page.

http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html

An appendix in the CIA world fact book which lists country codes as defined by ISO 3166, FIPS 10-4, and internet domain names.

AUTHOR

Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (C) 2002-2004, Neil Bowers.

Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Locale::Currency - ISO three letter codes for currency identification

  • CONVERSION ROUTINES
  • QUERY ROUTINES
  • EXAMPLES
  • KNOWN BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Locale::Currency - ISO three letter codes for currency identification (ISO 4217)

SYNOPSIS

    use Locale::Currency;

    $curr = code2currency('usd');     # $curr gets 'US Dollar'
    $code = currency2code('Euro');    # $code gets 'eur'

    @codes   = all_currency_codes();
    @names   = all_currency_names();

DESCRIPTION

The Locale::Currency module provides access to the ISO three-letter codes for identifying currencies and funds, as defined in ISO 4217. You can either access the codes via the conversion routines (described below), or with the two functions which return lists of all currency codes or all currency names.

There are two special codes defined by the standard which aren't understood by this module:

XTS

Specifically reserved for testing purposes.

XXX

For transactions where no currency is involved.

CONVERSION ROUTINES

There are two conversion routines: code2currency() and currency2code().

code2currency()

This function takes a three letter currency code and returns a string which contains the name of the currency identified. If the code is not a valid currency code, as defined by ISO 4217, then undef will be returned.

    $curr = code2currency($code);
currency2code()

This function takes a currency name and returns the corresponding three letter currency code, if such exists. If the argument could not be identified as a currency name, then undef will be returned.

    $code = currency2code('French Franc');

The case of the currency name is not important. See the section KNOWN BUGS AND LIMITATIONS below.

QUERY ROUTINES

There are two function which can be used to obtain a list of all currency codes, or all currency names:

all_currency_codes()

Returns a list of all three-letter currency codes. The codes are guaranteed to be all lower-case, and not in any particular order.

all_currency_names()

Returns a list of all currency names for which there is a corresponding three-letter currency code. The names are capitalised, and not returned in any particular order.

EXAMPLES

The following example illustrates use of the code2currency() function. The user is prompted for a currency code, and then told the corresponding currency name:

    $| = 1;    # turn off buffering

    print "Enter currency code: ";
    chop($code = <STDIN>);
    $curr = code2currency($code);
    if (defined $curr)
    {
        print "$code = $curr\n";
    }
    else
    {
        print "'$code' is not a valid currency code!\n";
    }

KNOWN BUGS AND LIMITATIONS

  • In the current implementation, all data is read in when the module is loaded, and then held in memory. A lazy implementation would be more memory friendly.

  • This module also includes the special codes which are not for a currency, such as Gold, Platinum, etc. This might cause a problem if you're using this module to display a list of currencies. Let Neil know if this does cause a problem, and we can do something about it.

  • ISO 4217 also defines a numeric code for each currency. Currency codes are not currently supported by this module, in the same way Locale::Country supports multiple codesets.

  • There are three cases where there is more than one code for the same currency name. Kwacha has two codes: mwk for Malawi, and zmk for Zambia. The Russian Ruble has two codes: rub and rur. The Belarussian Ruble has two codes: byr and byb. The currency2code() function only returns one code, so you might not get back the code you expected.

SEE ALSO

Locale::Country

ISO codes for identification of country (ISO 3166).

Locale::Script

ISO codes for identification of written scripts (ISO 15924).

ISO 4217:1995

Code for the representation of currencies and funds.

http://www.bsi-global.com/iso4217currency

Official web page for the ISO 4217 maintenance agency. This has the latest list of codes, in MS Word format. Boo.

AUTHOR

Michael Hennecke <hennecke@rz.uni-karlsruhe.de> and Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (C) 2002-2004, Neil Bowers.

Copyright (c) 2001 Michael Hennecke and Canon Research Centre Europe (CRE).

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Locale::Language - ISO two letter codes for language identification

  • CONVERSION ROUTINES
  • QUERY ROUTINES
  • EXAMPLES
  • KNOWN BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Locale::Language - ISO two letter codes for language identification (ISO 639)

SYNOPSIS

    use Locale::Language;

    $lang = code2language('en');        # $lang gets 'English'
    $code = language2code('French');    # $code gets 'fr'

    @codes   = all_language_codes();
    @names   = all_language_names();

DESCRIPTION

The Locale::Language module provides access to the ISO two-letter codes for identifying languages, as defined in ISO 639. You can either access the codes via the conversion routines (described below), or via the two functions which return lists of all language codes or all language names.

CONVERSION ROUTINES

There are two conversion routines: code2language() and language2code().

code2language()

This function takes a two letter language code and returns a string which contains the name of the language identified. If the code is not a valid language code, as defined by ISO 639, then undef will be returned.

    $lang = code2language($code);
language2code()

This function takes a language name and returns the corresponding two letter language code, if such exists. If the argument could not be identified as a language name, then undef will be returned.

    $code = language2code('French');

The case of the language name is not important. See the section KNOWN BUGS AND LIMITATIONS below.

QUERY ROUTINES

There are two function which can be used to obtain a list of all language codes, or all language names:

all_language_codes()

Returns a list of all two-letter language codes. The codes are guaranteed to be all lower-case, and not in any particular order.

all_language_names()

Returns a list of all language names for which there is a corresponding two-letter language code. The names are capitalised, and not returned in any particular order.

EXAMPLES

The following example illustrates use of the code2language() function. The user is prompted for a language code, and then told the corresponding language name:

    $| = 1;    # turn off buffering

    print "Enter language code: ";
    chop($code = <STDIN>);
    $lang = code2language($code);
    if (defined $lang)
    {
        print "$code = $lang\n";
    }
    else
    {
        print "'$code' is not a valid language code!\n";
    }

KNOWN BUGS AND LIMITATIONS

  • In the current implementation, all data is read in when the module is loaded, and then held in memory. A lazy implementation would be more memory friendly.

  • Currently just supports the two letter language codes - there are also three-letter codes, and numbers. Would these be of any use to anyone?

SEE ALSO

Locale::Country

ISO codes for identification of country (ISO 3166). Supports 2-letter, 3-letter, and numeric country codes.

Locale::Script

ISO codes for identification of written scripts (ISO 15924).

Locale::Currency

ISO three letter codes for identification of currencies and funds (ISO 4217).

ISO 639:1988 (E/F)

Code for the representation of names of languages.

http://lcweb.loc.gov/standards/iso639-2/langhome.html

Home page for ISO 639-2.

AUTHOR

Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (C) 2002-2004, Neil Bowers.

Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Locale::Maketext - framework for localization

  • QUICK OVERVIEW
  • METHODS
    • Construction Methods
    • The "maketext" Method
    • Utility Methods
    • Language Handle Attributes and Internals
  • LANGUAGE CLASS HIERARCHIES
  • ENTRIES IN EACH LEXICON
  • BRACKET NOTATION
  • AUTO LEXICONS
  • CONTROLLING LOOKUP FAILURE
  • HOW TO USE MAKETEXT
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMER
  • AUTHOR

NAME

Locale::Maketext - framework for localization

SYNOPSIS

  package MyProgram;
  use strict;
  use MyProgram::L10N;
   # ...which inherits from Locale::Maketext
  my $lh = MyProgram::L10N->get_handle() || die "What language?";
  ...
  # And then any messages your program emits, like:
  warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );
  ...

DESCRIPTION

It is a common feature of applications (whether run directly, or via the Web) for them to be "localized" -- i.e., for them to a present an English interface to an English-speaker, a German interface to a German-speaker, and so on for all languages it's programmed with. Locale::Maketext is a framework for software localization; it provides you with the tools for organizing and accessing the bits of text and text-processing code that you need for producing localized applications.

In order to make sense of Maketext and how all its components fit together, you should probably go read Locale::Maketext::TPJ13, and then read the following documentation.

You may also want to read over the source for File::Findgrep and its constituent modules -- they are a complete (if small) example application that uses Maketext.

QUICK OVERVIEW

The basic design of Locale::Maketext is object-oriented, and Locale::Maketext is an abstract base class, from which you derive a "project class". The project class (with a name like "TkBocciBall::Localize", which you then use in your module) is in turn the base class for all the "language classes" for your project (with names "TkBocciBall::Localize::it", "TkBocciBall::Localize::en", "TkBocciBall::Localize::fr", etc.).

A language class is a class containing a lexicon of phrases as class data, and possibly also some methods that are of use in interpreting phrases in the lexicon, or otherwise dealing with text in that language.

An object belonging to a language class is called a "language handle"; it's typically a flyweight object.

The normal course of action is to call:

  use TkBocciBall::Localize;  # the localization project class
  $lh = TkBocciBall::Localize->get_handle();
   # Depending on the user's locale, etc., this will
   # make a language handle from among the classes available,
   # and any defaults that you declare.
  die "Couldn't make a language handle??" unless $lh;

From then on, you use the maketext function to access entries in whatever lexicon(s) belong to the language handle you got. So, this:

  print $lh->maketext("You won!"), "\n";

...emits the right text for this language. If the object in $lh belongs to class "TkBocciBall::Localize::fr" and %TkBocciBall::Localize::fr::Lexicon contains ("You won!" =E<gt> "Tu as gagnE<eacute>!"), then the above code happily tells the user "Tu as gagné!".

METHODS

Locale::Maketext offers a variety of methods, which fall into three categories:

  • Methods to do with constructing language handles.

  • maketext and other methods to do with accessing %Lexicon data for a given language handle.

  • Methods that you may find it handy to use, from routines of yours that you put in %Lexicon entries.

These are covered in the following section.

Construction Methods

These are to do with constructing a language handle:

  • $lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";

    This tries loading classes based on the language-tags you give (like ("en-US", "sk", "kon", "es-MX", "ja", "i-klingon"), and for the first class that succeeds, returns YourProjClass::language->new().

    It runs thru the entire given list of language-tags, and finds no classes for those exact terms, it then tries "superordinate" language classes. So if no "en-US" class (i.e., YourProjClass::en_us) was found, nor classes for anything else in that list, we then try its superordinate, "en" (i.e., YourProjClass::en), and so on thru the other language-tags in the given list: "es". (The other language-tags in our example list: happen to have no superordinates.)

    If none of those language-tags leads to loadable classes, we then try classes derived from YourProjClass->fallback_languages() and then if nothing comes of that, we use classes named by YourProjClass->fallback_language_classes(). Then in the (probably quite unlikely) event that that fails, we just return undef.

  • $lh = YourProjClass->get_handle() || die "lg-handle?";

    When get_handle is called with an empty parameter list, magic happens:

    If get_handle senses that it's running in program that was invoked as a CGI, then it tries to get language-tags out of the environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that those were the languages passed as parameters to get_handle.

    Otherwise (i.e., if not a CGI), this tries various OS-specific ways to get the language-tags for the current locale/language, and then pretends that those were the value(s) passed to get_handle.

    Currently this OS-specific stuff consists of looking in the environment variables "LANG" and "LANGUAGE"; and on MSWin machines (where those variables are typically unused), this also tries using the module Win32::Locale to get a language-tag for whatever language/locale is currently selected in the "Regional Settings" (or "International"?) Control Panel. I welcome further suggestions for making this do the Right Thing under other operating systems that support localization.

    If you're using localization in an application that keeps a configuration file, you might consider something like this in your project class:

      sub get_handle_via_config {
    my $class = $_[0];
    my $preferred_language = $Config_settings{'language'};
    my $lh;
    if($preferred_language) {
      $lh = $class->get_handle($chosen_language)
       || die "No language handle for \"$chosen_language\" or the like";
    } else {
      # Config file missing, maybe?
      $lh = $class->get_handle()
       || die "Can't get a language handle";
    }
    return $lh;
  }

  • $lh = YourProjClass::langname->new();

    This constructs a language handle. You usually don't call this directly, but instead let get_handle find a language class to use and to then call ->new on.

  • $lh->init();

    This is called by ->new to initialize newly-constructed language handles. If you define an init method in your class, remember that it's usually considered a good idea to call $lh->SUPER::init in it (presumably at the beginning), so that all classes get a chance to initialize a new object however they see fit.

  • YourProjClass->fallback_languages()

    get_handle appends the return value of this to the end of whatever list of languages you pass get_handle. Unless you override this method, your project class will inherit Locale::Maketext's fallback_languages, which currently returns ('i-default', 'en', 'en-US'). ("i-default" is defined in RFC 2277).

    This method (by having it return the name of a language-tag that has an existing language class) can be used for making sure that get_handle will always manage to construct a language handle (assuming your language classes are in an appropriate @INC directory). Or you can use the next method:

  • YourProjClass->fallback_language_classes()

    get_handle appends the return value of this to the end of the list of classes it will try using. Unless you override this method, your project class will inherit Locale::Maketext's fallback_language_classes, which currently returns an empty list, (). By setting this to some value (namely, the name of a loadable language class), you can be sure that get_handle will always manage to construct a language handle.

The "maketext" Method

This is the most important method in Locale::Maketext:

$text = $lh->maketext(key, ...parameters for this phrase...);

This looks in the %Lexicon of the language handle $lh and all its superclasses, looking for an entry whose key is the string key. Assuming such an entry is found, various things then happen, depending on the value found:

If the value is a scalarref, the scalar is dereferenced and returned (and any parameters are ignored). If the value is a coderef, we return &$value($lh, ...parameters...). If the value is a string that doesn't look like it's in Bracket Notation, we return it (after replacing it with a scalarref, in its %Lexicon). If the value does look like it's in Bracket Notation, then we compile it into a sub, replace the string in the %Lexicon with the new coderef, and then we return &$new_sub($lh, ...parameters...).

Bracket Notation is discussed in a later section. Note that trying to compile a string into Bracket Notation can throw an exception if the string is not syntactically valid (say, by not balancing brackets right.)

Also, calling &$coderef($lh, ...parameters...) can throw any sort of exception (if, say, code in that sub tries to divide by zero). But a very common exception occurs when you have Bracket Notation text that says to call a method "foo", but there is no such method. (E.g., "You have [quatn,_1,ball]." will throw an exception on trying to call $lh->quatn($_[1],'ball') -- you presumably meant "quant".) maketext catches these exceptions, but only to make the error message more readable, at which point it rethrows the exception.

An exception may be thrown if key is not found in any of $lh's %Lexicon hashes. What happens if a key is not found, is discussed in a later section, "Controlling Lookup Failure".

Note that you might find it useful in some cases to override the maketext method with an "after method", if you want to translate encodings, or even scripts:

    package YrProj::zh_cn; # Chinese with PRC-style glyphs
    use base ('YrProj::zh_tw');  # Taiwan-style
    sub maketext {
      my $self = shift(@_);
      my $value = $self->maketext(@_);
      return Chineeze::taiwan2mainland($value);
    }

Or you may want to override it with something that traps any exceptions, if that's critical to your program:

  sub maketext {
    my($lh, @stuff) = @_;
    my $out;
    eval { $out = $lh->SUPER::maketext(@stuff) };
    return $out unless $@;
    ...otherwise deal with the exception...
  }

Other than those two situations, I don't imagine that it's useful to override the maketext method. (If you run into a situation where it is useful, I'd be interested in hearing about it.)

$lh->fail_with or $lh->fail_with(PARAM)
$lh->failure_handler_auto

These two methods are discussed in the section "Controlling Lookup Failure".

Utility Methods

These are methods that you may find it handy to use, generally from %Lexicon routines of yours (whether expressed as Bracket Notation or not).

$language->quant($number, $singular)
$language->quant($number, $singular, $plural)
$language->quant($number, $singular, $plural, $negative)

This is generally meant to be called from inside Bracket Notation (which is discussed later), as in

     "Your search matched [quant,_1,document]!"

It's for quantifying a noun (i.e., saying how much of it there is, while giving the correct form of it). The behavior of this method is handy for English and a few other Western European languages, and you should override it for languages where it's not suitable. You can feel free to read the source, but the current implementation is basically as this pseudocode describes:

     if $number is 0 and there's a $negative,
        return $negative;
     elsif $number is 1,
        return "1 $singular";
     elsif there's a $plural,
        return "$number $plural";
     else
        return "$number " . $singular . "s";
     #
     # ...except that we actually call numf to
     #  stringify $number before returning it.

So for English (with Bracket Notation) "...[quant,_1,file]..." is fine (for 0 it returns "0 files", for 1 it returns "1 file", and for more it returns "2 files", etc.)

But for "directory", you'd want "[quant,_1,directory,directories]" so that our elementary quant method doesn't think that the plural of "directory" is "directorys". And you might find that the output may sound better if you specify a negative form, as in:

     "[quant,_1,file,files,No files] matched your query.\n"

Remember to keep in mind verb agreement (or adjectives too, in other languages), as in:

     "[quant,_1,document] were matched.\n"

Because if _1 is one, you get "1 document were matched". An acceptable hack here is to do something like this:

     "[quant,_1,document was, documents were] matched.\n"
$language->numf($number)

This returns the given number formatted nicely according to this language's conventions. Maketext's default method is mostly to just take the normal string form of the number (applying sprintf "%G" for only very large numbers), and then to add commas as necessary. (Except that we apply tr/,./.,/ if $language->{'numf_comma'} is true; that's a bit of a hack that's useful for languages that express two million as "2.000.000" and not as "2,000,000").

If you want anything fancier, consider overriding this with something that uses Number::Format, or does something else entirely.

Note that numf is called by quant for stringifying all quantifying numbers.

$language->sprintf($format, @items)

This is just a wrapper around Perl's normal sprintf function. It's provided so that you can use "sprintf" in Bracket Notation:

     "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"

returning...

     Couldn't access datanode      Stuff=[thangamabob]!
$language->language_tag()

Currently this just takes the last bit of ref($language), turns underscores to dashes, and returns it. So if $language is an object of class Hee::HOO::Haw::en_us, $language->language_tag() returns "en-us". (Yes, the usual representation for that language tag is "en-US", but case is never considered meaningful in language-tag comparison.)

You may override this as you like; Maketext doesn't use it for anything.

$language->encoding()

Currently this isn't used for anything, but it's provided (with default value of (ref($language) && $language->{'encoding'})) or "iso-8859-1" ) as a sort of suggestion that it may be useful/necessary to associate encodings with your language handles (whether on a per-class or even per-handle basis.)

Language Handle Attributes and Internals

A language handle is a flyweight object -- i.e., it doesn't (necessarily) carry any data of interest, other than just being a member of whatever class it belongs to.

A language handle is implemented as a blessed hash. Subclasses of yours can store whatever data you want in the hash. Currently the only hash entry used by any crucial Maketext method is "fail", so feel free to use anything else as you like.

Remember: Don't be afraid to read the Maketext source if there's any point on which this documentation is unclear. This documentation is vastly longer than the module source itself.

LANGUAGE CLASS HIERARCHIES

These are Locale::Maketext's assumptions about the class hierarchy formed by all your language classes:

  • You must have a project base class, which you load, and which you then use as the first argument in the call to YourProjClass->get_handle(...). It should derive (whether directly or indirectly) from Locale::Maketext. It doesn't matter how you name this class, altho assuming this is the localization component of your Super Mega Program, good names for your project class might be SuperMegaProgram::Localization, SuperMegaProgram::L10N, SuperMegaProgram::I18N, SuperMegaProgram::International, or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.

  • Language classes are what YourProjClass->get_handle will try to load. It will look for them by taking each language-tag (skipping it if it doesn't look like a language-tag or locale-tag!), turning it to all lowercase, turning and dashes to underscores, and appending it to YourProjClass . "::". So this:

      $lh = YourProjClass->get_handle(
    'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'
  );

    will try loading the classes YourProjClass::en_us (note lowercase!), YourProjClass::fr, YourProjClass::kon, YourProjClass::i_klingon and YourProjClass::i_klingon_romanized. (And it'll stop at the first one that actually loads.)

  • I assume that each language class derives (directly or indirectly) from your project class, and also defines its @ISA, its %Lexicon, or both. But I anticipate no dire consequences if these assumptions do not hold.

  • Language classes may derive from other language classes (altho they should have "use Thatclassname" or "use base qw(...classes...)"). They may derive from the project class. They may derive from some other class altogether. Or via multiple inheritance, it may derive from any mixture of these.

  • I foresee no problems with having multiple inheritance in your hierarchy of language classes. (As usual, however, Perl will complain bitterly if you have a cycle in the hierarchy: i.e., if any class is its own ancestor.)

ENTRIES IN EACH LEXICON

A typical %Lexicon entry is meant to signify a phrase, taking some number (0 or more) of parameters. An entry is meant to be accessed by via a string key in $lh->maketext(key, ...parameters...), which should return a string that is generally meant for be used for "output" to the user -- regardless of whether this actually means printing to STDOUT, writing to a file, or putting into a GUI widget.

While the key must be a string value (since that's a basic restriction that Perl places on hash keys), the value in the lexicon can currently be of several types: a defined scalar, scalarref, or coderef. The use of these is explained above, in the section 'The "maketext" Method', and Bracket Notation for strings is discussed in the next section.

While you can use arbitrary unique IDs for lexicon keys (like "_min_larger_max_error"), it is often useful for if an entry's key is itself a valid value, like this example error message:

  "Minimum ([_1]) is larger than maximum ([_2])!\n",

Compare this code that uses an arbitrary ID...

  die $lh->maketext( "_min_larger_max_error", $min, $max )
   if $min > $max;

...to this code that uses a key-as-value:

  die $lh->maketext(
   "Minimum ([_1]) is larger than maximum ([_2])!\n",
   $min, $max
  ) if $min > $max;

The second is, in short, more readable. In particular, it's obvious that the number of parameters you're feeding to that phrase (two) is the number of parameters that it wants to be fed. (Since you see _1 and a _2 being used in the key there.)

Also, once a project is otherwise complete and you start to localize it, you can scrape together all the various keys you use, and pass it to a translator; and then the translator's work will go faster if what he's presented is this:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",
  => "",   # fill in something here, Jacques!

rather than this more cryptic mess:

 "_min_larger_max_error"
  => "",   # fill in something here, Jacques

I think that keys as lexicon values makes the completed lexicon entries more readable:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",
  => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",

Also, having valid values as keys becomes very useful if you set up an _AUTO lexicon. _AUTO lexicons are discussed in a later section.

I almost always use keys that are themselves valid lexicon values. One notable exception is when the value is quite long. For example, to get the screenful of data that a command-line program might returns when given an unknown switch, I often just use a key "_USAGE_MESSAGE". At that point I then go and immediately to define that lexicon entry in the ProjectClass::L10N::en lexicon (since English is always my "project language"):

  '_USAGE_MESSAGE' => <<'EOSTUFF',
  ...long long message...
  EOSTUFF

and then I can use it as:

  getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');

Incidentally, note that each class's %Lexicon inherits-and-extends the lexicons in its superclasses. This is not because these are special hashes per se, but because you access them via the maketext method, which looks for entries across all the %Lexicon's in a language class and all its ancestor classes. (This is because the idea of "class data" isn't directly implemented in Perl, but is instead left to individual class-systems to implement as they see fit..)

Note that you may have things stored in a lexicon besides just phrases for output: for example, if your program takes input from the keyboard, asking a "(Y/N)" question, you probably need to know what equivalent of "Y[es]/N[o]" is in whatever language. You probably also need to know what the equivalents of the answers "y" and "n" are. You can store that information in the lexicon (say, under the keys "~answer_y" and "~answer_n", and the long forms as "~answer_yes" and "~answer_no", where "~" is just an ad-hoc character meant to indicate to programmers/translators that these are not phrases for output).

Or instead of storing this in the language class's lexicon, you can (and, in some cases, really should) represent the same bit of knowledge as code is a method in the language class. (That leaves a tidy distinction between the lexicon as the things we know how to say, and the rest of the things in the lexicon class as things that we know how to do.) Consider this example of a processor for responses to French "oui/non" questions:

  sub y_or_n {
    return undef unless defined $_[1] and length $_[1];
    my $answer = lc $_[1];  # smash case
    return 1 if $answer eq 'o' or $answer eq 'oui';
    return 0 if $answer eq 'n' or $answer eq 'non';
    return undef;
  }

...which you'd then call in a construct like this:

  my $response;
  until(defined $response) {
    print $lh->maketext("Open the pod bay door (y/n)? ");
    $response = $lh->y_or_n( get_input_from_keyboard_somehow() );
  }
  if($response) { $pod_bay_door->open()         }
  else          { $pod_bay_door->leave_closed() }

Other data worth storing in a lexicon might be things like filenames for language-targetted resources:

  ...
  "_main_splash_png"
    => "/styles/en_us/main_splash.png",
  "_main_splash_imagemap"
    => "/styles/en_us/main_splash.incl",
  "_general_graphics_path"
    => "/styles/en_us/",
  "_alert_sound"
    => "/styles/en_us/hey_there.wav",
  "_forward_icon"
   => "left_arrow.png",
  "_backward_icon"
   => "right_arrow.png",
  # In some other languages, left equals
  #  BACKwards, and right is FOREwards.
  ...

You might want to do the same thing for expressing key bindings or the like (since hardwiring "q" as the binding for the function that quits a screen/menu/program is useful only if your language happens to associate "q" with "quit"!)

BRACKET NOTATION

Bracket Notation is a crucial feature of Locale::Maketext. I mean Bracket Notation to provide a replacement for sprintf formatting. Everything you do with Bracket Notation could be done with a sub block, but bracket notation is meant to be much more concise.

Bracket Notation is a like a miniature "template" system (in the sense of Text::Template, not in the sense of C++ templates), where normal text is passed thru basically as is, but text is special regions is specially interpreted. In Bracket Notation, you use brackets ("[...]" -- not "{...}"!) to note sections that are specially interpreted.

For example, here all the areas that are taken literally are underlined with a "^", and all the in-bracket special regions are underlined with an X:

  "Minimum ([_1]) is larger than maximum ([_2])!\n",
   ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^

When that string is compiled from bracket notation into a real Perl sub, it's basically turned into:

  sub {
    my $lh = $_[0];
    my @params = @_;
    return join '',
      "Minimum (",
      ...some code here...
      ") is larger than maximum (",
      ...some code here...
      ")!\n",
  }
  # to be called by $lh->maketext(KEY, params...)

  In other words, text outside bracket groups is turned into string
  literals.  Text in brackets is rather more complex, and currently follows
  these rules:

  • Bracket groups that are empty, or which consist only of whitespace, are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns and/or tabs and/or spaces between them.

    Otherwise, each group is taken to be a comma-separated group of items, and each item is interpreted as follows:

  • An item that is "_digits" or "_-digits" is interpreted as $_[value]. I.e., "_1" is becomes with $_[1], and "_-3" is interpreted as $_[-3] (in which case @_ should have at least three elements in it). Note that $_[0] is the language handle, and is typically not named directly.

  • An item "_*" is interpreted to mean "all of @_ except $_[0]". I.e., @_[1..$#_]. Note that this is an empty list in the case of calls like $lh->maketext(key) where there are no parameters (except $_[0], the language handle).

  • Otherwise, each item is interpreted as a string literal.

The group as a whole is interpreted as follows:

  • If the first item in a bracket group looks like a method name, then that group is interpreted like this:

      $lh->that_method_name(
    ...rest of items in this group...
  ),

  • If the first item in a bracket group is "*", it's taken as shorthand for the so commonly called "quant" method. Similarly, if the first item in a bracket group is "#", it's taken to be shorthand for "numf".

  • If the first item in a bracket group is empty-string, or "_*" or "_digits" or "_-digits", then that group is interpreted as just the interpolation of all its items:

      join('',
    ...rest of items in this group...
  ),

    Examples: "[_1]" and "[,_1]", which are synonymous; and "[,ID-(,_4,-,_2,)]", which compiles as join "", "ID-(", $_[4], "-", $_[2], ")".

  • Otherwise this bracket group is invalid. For example, in the group "[!@#,whatever]", the first item "!@#" is neither empty-string, "_number", "_-number", "_*", nor a valid method name; and so Locale::Maketext will throw an exception of you try compiling an expression containing this bracket group.

Note, incidentally, that items in each group are comma-separated, not /\s*,\s*/-separated. That is, you might expect that this bracket group:

  "Hoohah [foo, _1 , bar ,baz]!"

would compile to this:

  sub {
    my $lh = $_[0];
    return join '',
      "Hoohah ",
      $lh->foo( $_[1], "bar", "baz"),
      "!",
  }

But it actually compiles as this:

  sub {
    my $lh = $_[0];
    return join '',
      "Hoohah ",
      $lh->foo(" _1 ", " bar ", "baz"),  #!!!
      "!",
  }

In the notation discussed so far, the characters "[" and "]" are given special meaning, for opening and closing bracket groups, and "," has a special meaning inside bracket groups, where it separates items in the group. This begs the question of how you'd express a literal "[" or "]" in a Bracket Notation string, and how you'd express a literal comma inside a bracket group. For this purpose I've adopted "~" (tilde) as an escape character: "~[" means a literal '[' character anywhere in Bracket Notation (i.e., regardless of whether you're in a bracket group or not), and ditto for "~]" meaning a literal ']', and "~," meaning a literal comma. (Altho "," means a literal comma outside of bracket groups -- it's only inside bracket groups that commas are special.)

And on the off chance you need a literal tilde in a bracket expression, you get it with "~~".

Currently, an unescaped "~" before a character other than a bracket or a comma is taken to mean just a "~" and that character. I.e., "~X" means the same as "~~X" -- i.e., one literal tilde, and then one literal "X". However, by using "~X", you are assuming that no future version of Maketext will use "~X" as a magic escape sequence. In practice this is not a great problem, since first off you can just write "~~X" and not worry about it; second off, I doubt I'll add lots of new magic characters to bracket notation; and third off, you aren't likely to want literal "~" characters in your messages anyway, since it's not a character with wide use in natural language text.

Brackets must be balanced -- every openbracket must have one matching closebracket, and vice versa. So these are all invalid:

  "I ate [quant,_1,rhubarb pie."
  "I ate [quant,_1,rhubarb pie[."
  "I ate quant,_1,rhubarb pie]."
  "I ate quant,_1,rhubarb pie[."

Currently, bracket groups do not nest. That is, you cannot say:

  "Foo [bar,baz,[quux,quuux]]\n";

If you need a notation that's that powerful, use normal Perl:

  %Lexicon = (
    ...
    "some_key" => sub {
      my $lh = $_[0];
      join '',
        "Foo ",
        $lh->bar('baz', $lh->quux('quuux')),
        "\n",
    },
    ...
  );

Or write the "bar" method so you don't need to pass it the output from calling quux.

I do not anticipate that you will need (or particularly want) to nest bracket groups, but you are welcome to email me with convincing (real-life) arguments to the contrary.

AUTO LEXICONS

If maketext goes to look in an individual %Lexicon for an entry for key (where key does not start with an underscore), and sees none, but does see an entry of "_AUTO" => some_true_value, then we actually define $Lexicon{key} = key right then and there, and then use that value as if it had been there all along. This happens before we even look in any superclass %Lexicons!

(This is meant to be somewhat like the AUTOLOAD mechanism in Perl's function call system -- or, looked at another way, like the AutoLoader module.)

I can picture all sorts of circumstances where you just do not want lookup to be able to fail (since failing normally means that maketext throws a die, altho see the next section for greater control over that). But here's one circumstance where _AUTO lexicons are meant to be especially useful:

As you're writing an application, you decide as you go what messages you need to emit. Normally you'd go to write this:

  if(-e $filename) {
    go_process_file($filename)
  } else {
    print "Couldn't find file \"$filename\"!\n";
  }

but since you anticipate localizing this, you write:

  use ThisProject::I18N;
  my $lh = ThisProject::I18N->get_handle();
   # For the moment, assume that things are set up so
   # that we load class ThisProject::I18N::en
   # and that that's the class that $lh belongs to.
  ...
  if(-e $filename) {
    go_process_file($filename)
  } else {
    print $lh->maketext(
      "Couldn't find file \"[_1]\"!\n", $filename
    );
  }

Now, right after you've just written the above lines, you'd normally have to go open the file ThisProject/I18N/en.pm, and immediately add an entry:

  "Couldn't find file \"[_1]\"!\n"
  => "Couldn't find file \"[_1]\"!\n",

But I consider that somewhat of a distraction from the work of getting the main code working -- to say nothing of the fact that I often have to play with the program a few times before I can decide exactly what wording I want in the messages (which in this case would require me to go changing three lines of code: the call to maketext with that key, and then the two lines in ThisProject/I18N/en.pm).

However, if you set "_AUTO => 1" in the %Lexicon in, ThisProject/I18N/en.pm (assuming that English (en) is the language that all your programmers will be using for this project's internal message keys), then you don't ever have to go adding lines like this

  "Couldn't find file \"[_1]\"!\n"
  => "Couldn't find file \"[_1]\"!\n",

to ThisProject/I18N/en.pm, because if _AUTO is true there, then just looking for an entry with the key "Couldn't find file \"[_1]\"!\n" in that lexicon will cause it to be added, with that value!

Note that the reason that keys that start with "_" are immune to _AUTO isn't anything generally magical about the underscore character -- I just wanted a way to have most lexicon keys be autoable, except for possibly a few, and I arbitrarily decided to use a leading underscore as a signal to distinguish those few.

CONTROLLING LOOKUP FAILURE

If you call $lh->maketext(key, ...parameters...), and there's no entry key in $lh's class's %Lexicon, nor in the superclass %Lexicon hash, and if we can't auto-make key (because either it starts with a "_", or because none of its lexicons have _AUTO => 1,), then we have failed to find a normal way to maketext key. What then happens in these failure conditions, depends on the $lh object "fail" attribute.

If the language handle has no "fail" attribute, maketext will simply throw an exception (i.e., it calls die, mentioning the key whose lookup failed, and naming the line number where the calling $lh->maketext(key,...) was.

If the language handle has a "fail" attribute whose value is a coderef, then $lh->maketext(key,...params...) gives up and calls:

  return &{$that_subref}($lh, $key, @params);

Otherwise, the "fail" attribute's value should be a string denoting a method name, so that $lh->maketext(key,...params...) can give up with:

  return $lh->$that_method_name($phrase, @params);

The "fail" attribute can be accessed with the fail_with method:

  # Set to a coderef:
  $lh->fail_with( \&failure_handler );

  # Set to a method name:
  $lh->fail_with( 'failure_method' );

  # Set to nothing (i.e., so failure throws a plain exception)
  $lh->fail_with( undef );

  # Simply read:
  $handler = $lh->fail_with();

Now, as to what you may want to do with these handlers: Maybe you'd want to log what key failed for what class, and then die. Maybe you don't like die and instead you want to send the error message to STDOUT (or wherever) and then merely exit().

Or maybe you don't want to die at all! Maybe you could use a handler like this:

  # Make all lookups fall back onto an English value,
  #  but after we log it for later fingerpointing.
  my $lh_backup = ThisProject->get_handle('en');
  open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!";
  sub lex_fail {
    my($failing_lh, $key, $params) = @_;
    print LEX_FAIL_LOG scalar(localtime), "\t",
       ref($failing_lh), "\t", $key, "\n";
    return $lh_backup->maketext($key,@params);
  }

Some users have expressed that they think this whole mechanism of having a "fail" attribute at all, seems a rather pointless complication. But I want Locale::Maketext to be usable for software projects of any scale and type; and different software projects have different ideas of what the right thing is to do in failure conditions. I could simply say that failure always throws an exception, and that if you want to be careful, you'll just have to wrap every call to $lh->maketext in an eval { }. However, I want programmers to reserve the right (via the "fail" attribute) to treat lookup failure as something other than an exception of the same level of severity as a config file being unreadable, or some essential resource being inaccessible.

One possibly useful value for the "fail" attribute is the method name "failure_handler_auto". This is a method defined in class Locale::Maketext itself. You set it with:

  $lh->fail_with('failure_handler_auto');

Then when you call $lh->maketext(key, ...parameters...) and there's no key in any of those lexicons, maketext gives up with

  return $lh->failure_handler_auto($key, @params);

But failure_handler_auto, instead of dying or anything, compiles $key, caching it in $lh->{'failure_lex'}{$key} = $complied, and then calls the compiled value, and returns that. (I.e., if $key looks like bracket notation, $compiled is a sub, and we return &{$compiled}(@params); but if $key is just a plain string, we just return that.)

The effect of using "failure_auto_handler" is like an AUTO lexicon, except that it 1) compiles $key even if it starts with "_", and 2) you have a record in the new hashref $lh->{'failure_lex'} of all the keys that have failed for this object. This should avoid your program dying -- as long as your keys aren't actually invalid as bracket code, and as long as they don't try calling methods that don't exist.

"failure_auto_handler" may not be exactly what you want, but I hope it at least shows you that maketext failure can be mitigated in any number of very flexible ways. If you can formalize exactly what you want, you should be able to express that as a failure handler. You can even make it default for every object of a given class, by setting it in that class's init:

  sub init {
    my $lh = $_[0];  # a newborn handle
    $lh->SUPER::init();
    $lh->fail_with('my_clever_failure_handler');
    return;
  }
  sub my_clever_failure_handler {
    ...you clever things here...
  }

HOW TO USE MAKETEXT

Here is a brief checklist on how to use Maketext to localize applications:

  • Decide what system you'll use for lexicon keys. If you insist, you can use opaque IDs (if you're nostalgic for catgets), but I have better suggestions in the section "Entries in Each Lexicon", above. Assuming you opt for meaningful keys that double as values (like "Minimum ([_1]) is larger than maximum ([_2])!\n"), you'll have to settle on what language those should be in. For the sake of argument, I'll call this English, specifically American English, "en-US".

  • Create a class for your localization project. This is the name of the class that you'll use in the idiom:

      use Projname::L10N;
  my $lh = Projname::L10N->get_handle(...) || die "Language?";

    Assuming your call your class Projname::L10N, create a class consisting minimally of:

      package Projname::L10N;
  use base qw(Locale::Maketext);
  ...any methods you might want all your languages to share...

  # And, assuming you want the base class to be an _AUTO lexicon,
  # as is discussed a few sections up:

  1;

  • Create a class for the language your internal keys are in. Name the class after the language-tag for that language, in lowercase, with dashes changed to underscores. Assuming your project's first language is US English, you should call this Projname::L10N::en_us. It should consist minimally of:

      package Projname::L10N::en_us;
  use base qw(Projname::L10N);
  %Lexicon = (
    '_AUTO' => 1,
  );
  1;

    (For the rest of this section, I'll assume that this "first language class" of Projname::L10N::en_us has _AUTO lexicon.)

  • Go and write your program. Everywhere in your program where you would say:

      print "Foobar $thing stuff\n";

    instead do it thru maketext, using no variable interpolation in the key:

      print $lh->maketext("Foobar [_1] stuff\n", $thing);

    If you get tired of constantly saying print $lh->maketext, consider making a functional wrapper for it, like so:

      use Projname::L10N;
  use vars qw($lh);
  $lh = Projname::L10N->get_handle(...) || die "Language?";
  sub pmt (@) { print( $lh->maketext(@_)) }
   # "pmt" is short for "Print MakeText"
  $Carp::Verbose = 1;
   # so if maketext fails, we see made the call to pmt

    Besides whole phrases meant for output, anything language-dependent should be put into the class Projname::L10N::en_us, whether as methods, or as lexicon entries -- this is discussed in the section "Entries in Each Lexicon", above.

  • Once the program is otherwise done, and once its localization for the first language works right (via the data and methods in Projname::L10N::en_us), you can get together the data for translation. If your first language lexicon isn't an _AUTO lexicon, then you already have all the messages explicitly in the lexicon (or else you'd be getting exceptions thrown when you call $lh->maketext to get messages that aren't in there). But if you were (advisedly) lazy and are using an _AUTO lexicon, then you've got to make a list of all the phrases that you've so far been letting _AUTO generate for you. There are very many ways to assemble such a list. The most straightforward is to simply grep the source for every occurrence of "maketext" (or calls to wrappers around it, like the above pmt function), and to log the following phrase.

  • You may at this point want to consider whether the your base class (Projname::L10N) that all lexicons inherit from (Projname::L10N::en, Projname::L10N::es, etc.) should be an _AUTO lexicon. It may be true that in theory, all needed messages will be in each language class; but in the presumably unlikely or "impossible" case of lookup failure, you should consider whether your program should throw an exception, emit text in English (or whatever your project's first language is), or some more complex solution as described in the section "Controlling Lookup Failure", above.

  • Submit all messages/phrases/etc. to translators.

    (You may, in fact, want to start with localizing to one other language at first, if you're not sure that you've property abstracted the language-dependent parts of your code.)

    Translators may request clarification of the situation in which a particular phrase is found. For example, in English we are entirely happy saying "n files found", regardless of whether we mean "I looked for files, and found n of them" or the rather distinct situation of "I looked for something else (like lines in files), and along the way I saw n files." This may involve rethinking things that you thought quite clear: should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is there already a conventionalized way to express that menu option, separate from the target language's normal word for "to edit"?

    In all cases where the very common phenomenon of quantification (saying "N files", for any value of N) is involved, each translator should make clear what dependencies the number causes in the sentence. In many cases, dependency is limited to words adjacent to the number, in places where you might expect them ("I found the-?PLURAL N empty-?PLURAL directory-?PLURAL"), but in some cases there are unexpected dependencies ("I found-?PLURAL ..."!) as well as long-distance dependencies "The N directory-?PLURAL could not be deleted-?PLURAL"!).

    Remind the translators to consider the case where N is 0: "0 files found" isn't exactly natural-sounding in any language, but it may be unacceptable in many -- or it may condition special kinds of agreement (similar to English "I didN'T find ANY files").

    Remember to ask your translators about numeral formatting in their language, so that you can override the numf method as appropriate. Typical variables in number formatting are: what to use as a decimal point (comma? period?); what to use as a thousands separator (space? nonbreaking space? comma? period? small middot? prime? apostrophe?); and even whether the so-called "thousands separator" is actually for every third digit -- I've heard reports of two hundred thousand being expressible as "2,00,000" for some Indian (Subcontinental) languages, besides the less surprising "200 000", "200.000", "200,000", and "200'000". Also, using a set of numeral glyphs other than the usual ASCII "0"-"9" might be appreciated, as via tr/0-9/\x{0966}-\x{096F}/ for getting digits in Devanagari script (for Hindi, Konkani, others).

    The basic quant method that Locale::Maketext provides should be good for many languages. For some languages, it might be useful to modify it (or its constituent numerate method) to take a plural form in the two-argument call to quant (as in "[quant,_1,files]") if it's all-around easier to infer the singular form from the plural, than to infer the plural form from the singular.

    But for other languages (as is discussed at length in Locale::Maketext::TPJ13), simple quant/numerify is not enough. For the particularly problematic Slavic languages, what you may need is a method which you provide with the number, the citation form of the noun to quantify, and the case and gender that the sentence's syntax projects onto that noun slot. The method would then be responsible for determining what grammatical number that numeral projects onto its noun phrase, and what case and gender it may override the normal case and gender with; and then it would look up the noun in a lexicon providing all needed inflected forms.

  • You may also wish to discuss with the translators the question of how to relate different subforms of the same language tag, considering how this reacts with get_handle's treatment of these. For example, if a user accepts interfaces in "en, fr", and you have interfaces available in "en-US" and "fr", what should they get? You may wish to resolve this by establishing that "en" and "en-US" are effectively synonymous, by having one class zero-derive from the other.

    For some languages this issue may never come up (Danish is rarely expressed as "da-DK", but instead is just "da"). And for other languages, the whole concept of a "generic" form may verge on being uselessly vague, particularly for interfaces involving voice media in forms of Arabic or Chinese.

  • Once you've localized your program/site/etc. for all desired languages, be sure to show the result (whether live, or via screenshots) to the translators. Once they approve, make every effort to have it then checked by at least one other speaker of that language. This holds true even when (or especially when) the translation is done by one of your own programmers. Some kinds of systems may be harder to find testers for than others, depending on the amount of domain-specific jargon and concepts involved -- it's easier to find people who can tell you whether they approve of your translation for "delete this message" in an email-via-Web interface, than to find people who can give you an informed opinion on your translation for "attribute value" in an XML query tool's interface.

SEE ALSO

I recommend reading all of these:

Locale::Maketext::TPJ13 -- my The Perl Journal article about Maketext. It explains many important concepts underlying Locale::Maketext's design, and some insight into why Maketext is better than the plain old approach of just having message catalogs that are just databases of sprintf formats.

File::Findgrep is a sample application/module that uses Locale::Maketext to localize its messages. For a larger internationalized system, see also the Apache::MP3 manpage.

I18N::LangTags.

Win32::Locale.

RFC 3066, Tags for the Identification of Languages, as at http://sunsite.dk/RFC/rfc/rfc3066.html

RFC 2277, IETF Policy on Character Sets and Languages is at http://sunsite.dk/RFC/rfc/rfc2277.html -- much of it is just things of interest to protocol designers, but it explains some basic concepts, like the distinction between locales and language-tags.

The manual for GNU gettext. The gettext dist is available in ftp://prep.ai.mit.edu/pub/gnu/ -- get a recent gettext tarball and look in its "doc/" directory, there's an easily browsable HTML version in there. The gettext documentation asks lots of questions worth thinking about, even if some of their answers are sometimes wonky, particularly where they start talking about pluralization.

The Locale/Maketext.pm source. Obverse that the module is much shorter than its documentation!

COPYRIGHT AND DISCLAIMER

Copyright (c) 1999-2004 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Locale::Maketext::TPJ13 -- article about software localization

  • Localization and Perl: gettext breaks, Maketext fixes
    • A Localization Horror Story: It Could Happen To You
    • The Linguistic View
    • Breaking gettext
    • Replacing gettext
    • Buzzwords: Abstraction and Encapsulation
    • Buzzword: Isomorphism
    • Buzzword: Inheritance
    • Buzzword: Concision
    • The Devil in the Details
    • The Proof in the Pudding: Localizing Web Sites
    • References

NAME

Locale::Maketext::TPJ13 -- article about software localization

SYNOPSIS

  # This an article, not a module.

DESCRIPTION

The following article by Sean M. Burke and Jordan Lachler first appeared in The Perl Journal #13 and is copyright 1999 The Perl Journal. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.

Localization and Perl: gettext breaks, Maketext fixes

by Sean M. Burke and Jordan Lachler

This article points out cases where gettext (a common system for localizing software interfaces -- i.e., making them work in the user's language of choice) fails because of basic differences between human languages. This article then describes Maketext, a new system capable of correctly treating these differences.

A Localization Horror Story: It Could Happen To You

"There are a number of languages spoken by human beings in this world."

-- Harald Tveit Alvestrand, in RFC 1766, "Tags for the Identification of Languages"

Imagine that your task for the day is to localize a piece of software -- and luckily for you, the only output the program emits is two messages, like this:

  I scanned 12 directories.
  Your query matched 10 files in 4 directories.

So how hard could that be? You look at the code that produces the first item, and it reads:

  printf("I scanned %g directories.",
         $directory_count);

You think about that, and realize that it doesn't even work right for English, as it can produce this output:

  I scanned 1 directories.

So you rewrite it to read:

  printf("I scanned %g %s.",
         $directory_count,
         $directory_count == 1 ?
           "directory" : "directories",
  );

...which does the Right Thing. (In case you don't recall, "%g" is for locale-specific number interpolation, and "%s" is for string interpolation.)

But you still have to localize it for all the languages you're producing this software for, so you pull Locale::gettext off of CPAN so you can access the gettext C functions you've heard are standard for localization tasks.

And you write:

  printf(gettext("I scanned %g %s."),
         $dir_scan_count,
         $dir_scan_count == 1 ?
           gettext("directory") : gettext("directories"),
  );

But you then read in the gettext manual (Drepper, Miller, and Pinard 1995) that this is not a good idea, since how a single word like "directory" or "directories" is translated may depend on context -- and this is true, since in a case language like German or Russian, you'd may need these words with a different case ending in the first instance (where the word is the object of a verb) than in the second instance, which you haven't even gotten to yet (where the word is the object of a preposition, "in %g directories") -- assuming these keep the same syntax when translated into those languages.

So, on the advice of the gettext manual, you rewrite:

  printf( $dir_scan_count == 1 ?
           gettext("I scanned %g directory.") :
           gettext("I scanned %g directories."),
         $dir_scan_count );

So, you email your various translators (the boss decides that the languages du jour are Chinese, Arabic, Russian, and Italian, so you have one translator for each), asking for translations for "I scanned %g directory." and "I scanned %g directories.". When they reply, you'll put that in the lexicons for gettext to use when it localizes your software, so that when the user is running under the "zh" (Chinese) locale, gettext("I scanned %g directory.") will return the appropriate Chinese text, with a "%g" in there where printf can then interpolate $dir_scan.

Your Chinese translator emails right back -- he says both of these phrases translate to the same thing in Chinese, because, in linguistic jargon, Chinese "doesn't have number as a grammatical category" -- whereas English does. That is, English has grammatical rules that refer to "number", i.e., whether something is grammatically singular or plural; and one of these rules is the one that forces nouns to take a plural suffix (generally "s") when in a plural context, as they are when they follow a number other than "one" (including, oddly enough, "zero"). Chinese has no such rules, and so has just the one phrase where English has two. But, no problem, you can have this one Chinese phrase appear as the translation for the two English phrases in the "zh" gettext lexicon for your program.

Emboldened by this, you dive into the second phrase that your software needs to output: "Your query matched 10 files in 4 directories.". You notice that if you want to treat phrases as indivisible, as the gettext manual wisely advises, you need four cases now, instead of two, to cover the permutations of singular and plural on the two items, $dir_count and $file_count. So you try this:

  printf( $file_count == 1 ?
    ( $directory_count == 1 ?
     gettext("Your query matched %g file in %g directory.") :
     gettext("Your query matched %g file in %g directories.") ) :
    ( $directory_count == 1 ?
     gettext("Your query matched %g files in %g directory.") :
     gettext("Your query matched %g files in %g directories.") ),
   $file_count, $directory_count,
  );

(The case of "1 file in 2 [or more] directories" could, I suppose, occur in the case of symlinking or something of the sort.)

It occurs to you that this is not the prettiest code you've ever written, but this seems the way to go. You mail off to the translators asking for translations for these four cases. The Chinese guy replies with the one phrase that these all translate to in Chinese, and that phrase has two "%g"s in it, as it should -- but there's a problem. He translates it word-for-word back: "In %g directories contains %g files match your query." The %g slots are in an order reverse to what they are in English. You wonder how you'll get gettext to handle that.

But you put it aside for the moment, and optimistically hope that the other translators won't have this problem, and that their languages will be better behaved -- i.e., that they will be just like English.

But the Arabic translator is the next to write back. First off, your code for "I scanned %g directory." or "I scanned %g directories." assumes there's only singular or plural. But, to use linguistic jargon again, Arabic has grammatical number, like English (but unlike Chinese), but it's a three-term category: singular, dual, and plural. In other words, the way you say "directory" depends on whether there's one directory, or two of them, or more than two of them. Your test of ($directory == 1) no longer does the job. And it means that where English's grammatical category of number necessitates only the two permutations of the first sentence based on "directory [singular]" and "directories [plural]", Arabic has three -- and, worse, in the second sentence ("Your query matched %g file in %g directory."), where English has four, Arabic has nine. You sense an unwelcome, exponential trend taking shape.

Your Italian translator emails you back and says that "I searched 0 directories" (a possible English output of your program) is stilted, and if you think that's fine English, that's your problem, but that just will not do in the language of Dante. He insists that where $directory_count is 0, your program should produce the Italian text for "I didn't scan any directories.". And ditto for "I didn't match any files in any directories", although he says the last part about "in any directories" should probably just be left off.

You wonder how you'll get gettext to handle this; to accomodate the ways Arabic, Chinese, and Italian deal with numbers in just these few very simple phrases, you need to write code that will ask gettext for different queries depending on whether the numerical values in question are 1, 2, more than 2, or in some cases 0, and you still haven't figured out the problem with the different word order in Chinese.

Then your Russian translator calls on the phone, to personally tell you the bad news about how really unpleasant your life is about to become:

Russian, like German or Latin, is an inflectional language; that is, nouns and adjectives have to take endings that depend on their case (i.e., nominative, accusative, genitive, etc...) -- which is roughly a matter of what role they have in syntax of the sentence -- as well as on the grammatical gender (i.e., masculine, feminine, neuter) and number (i.e., singular or plural) of the noun, as well as on the declension class of the noun. But unlike with most other inflected languages, putting a number-phrase (like "ten" or "forty-three", or their Arabic numeral equivalents) in front of noun in Russian can change the case and number that noun is, and therefore the endings you have to put on it.

He elaborates: In "I scanned %g directories", you'd expect "directories" to be in the accusative case (since it is the direct object in the sentnce) and the plural number, except where $directory_count is 1, then you'd expect the singular, of course. Just like Latin or German. But! Where $directory_count % 10 is 1 ("%" for modulo, remember), assuming $directory count is an integer, and except where $directory_count % 100 is 11, "directories" is forced to become grammatically singular, which means it gets the ending for the accusative singular... You begin to visualize the code it'd take to test for the problem so far, and still work for Chinese and Arabic and Italian, and how many gettext items that'd take, but he keeps going... But where $directory_count % 10 is 2, 3, or 4 (except where $directory_count % 100 is 12, 13, or 14), the word for "directories" is forced to be genitive singular -- which means another ending... The room begins to spin around you, slowly at first... But with all other integer values, since "directory" is an inanimate noun, when preceded by a number and in the nominative or accusative cases (as it is here, just your luck!), it does stay plural, but it is forced into the genitive case -- yet another ending... And you never hear him get to the part about how you're going to run into similar (but maybe subtly different) problems with other Slavic languages like Polish, because the floor comes up to meet you, and you fade into unconsciousness.

The above cautionary tale relates how an attempt at localization can lead from programmer consternation, to program obfuscation, to a need for sedation. But careful evaluation shows that your choice of tools merely needed further consideration.

The Linguistic View

"It is more complicated than you think."

-- The Eighth Networking Truth, from RFC 1925

The field of Linguistics has expended a great deal of effort over the past century trying to find grammatical patterns which hold across languages; it's been a constant process of people making generalizations that should apply to all languages, only to find out that, all too often, these generalizations fail -- sometimes failing for just a few languages, sometimes whole classes of languages, and sometimes nearly every language in the world except English. Broad statistical trends are evident in what the "average language" is like as far as what its rules can look like, must look like, and cannot look like. But the "average language" is just as unreal a concept as the "average person" -- it runs up against the fact no language (or person) is, in fact, average. The wisdom of past experience leads us to believe that any given language can do whatever it wants, in any order, with appeal to any kind of grammatical categories wants -- case, number, tense, real or metaphoric characteristics of the things that words refer to, arbitrary or predictable classifications of words based on what endings or prefixes they can take, degree or means of certainty about the truth of statements expressed, and so on, ad infinitum.

Mercifully, most localization tasks are a matter of finding ways to translate whole phrases, generally sentences, where the context is relatively set, and where the only variation in content is usually in a number being expressed -- as in the example sentences above. Translating specific, fully-formed sentences is, in practice, fairly foolproof -- which is good, because that's what's in the phrasebooks that so many tourists rely on. Now, a given phrase (whether in a phrasebook or in a gettext lexicon) in one language might have a greater or lesser applicability than that phrase's translation into another language -- for example, strictly speaking, in Arabic, the "your" in "Your query matched..." would take a different form depending on whether the user is male or female; so the Arabic translation "your[feminine] query" is applicable in fewer cases than the corresponding English phrase, which doesn't distinguish the user's gender. (In practice, it's not feasable to have a program know the user's gender, so the masculine "you" in Arabic is usually used, by default.)

But in general, such surprises are rare when entire sentences are being translated, especially when the functional context is restricted to that of a computer interacting with a user either to convey a fact or to prompt for a piece of information. So, for purposes of localization, translation by phrase (generally by sentence) is both the simplest and the least problematic.

Breaking gettext

"It Has To Work."

-- First Networking Truth, RFC 1925

Consider that sentences in a tourist phrasebook are of two types: ones like "How do I get to the marketplace?" that don't have any blanks to fill in, and ones like "How much do these ___ cost?", where there's one or more blanks to fill in (and these are usually linked to a list of words that you can put in that blank: "fish", "potatoes", "tomatoes", etc.) The ones with no blanks are no problem, but the fill-in-the-blank ones may not be really straightforward. If it's a Swahili phrasebook, for example, the authors probably didn't bother to tell you the complicated ways that the verb "cost" changes its inflectional prefix depending on the noun you're putting in the blank. The trader in the marketplace will still understand what you're saying if you say "how much do these potatoes cost?" with the wrong inflectional prefix on "cost". After all, you can't speak proper Swahili, you're just a tourist. But while tourists can be stupid, computers are supposed to be smart; the computer should be able to fill in the blank, and still have the results be grammatical.

In other words, a phrasebook entry takes some values as parameters (the things that you fill in the blank or blanks), and provides a value based on these parameters, where the way you get that final value from the given values can, properly speaking, involve an arbitrarily complex series of operations. (In the case of Chinese, it'd be not at all complex, at least in cases like the examples at the beginning of this article; whereas in the case of Russian it'd be a rather complex series of operations. And in some languages, the complexity could be spread around differently: while the act of putting a number-expression in front of a noun phrase might not be complex by itself, it may change how you have to, for example, inflect a verb elsewhere in the sentence. This is what in syntax is called "long-distance dependencies".)

This talk of parameters and arbitrary complexity is just another way to say that an entry in a phrasebook is what in a programming language would be called a "function". Just so you don't miss it, this is the crux of this article: A phrase is a function; a phrasebook is a bunch of functions.

The reason that using gettext runs into walls (as in the above second-person horror story) is that you're trying to use a string (or worse, a choice among a bunch of strings) to do what you really need a function for -- which is futile. Preforming (s)printf interpolation on the strings which you get back from gettext does allow you to do some common things passably well... sometimes... sort of; but, to paraphrase what some people say about csh script programming, "it fools you into thinking you can use it for real things, but you can't, and you don't discover this until you've already spent too much time trying, and by then it's too late."

Replacing gettext

So, what needs to replace gettext is a system that supports lexicons of functions instead of lexicons of strings. An entry in a lexicon from such a system should not look like this:

  "J'ai trouv\xE9 %g fichiers dans %g r\xE9pertoires"

[\xE9 is e-acute in Latin-1. Some pod renderers would scream if I used the actual character here. -- SB]

but instead like this, bearing in mind that this is just a first stab:

  sub I_found_X1_files_in_X2_directories {
    my( $files, $dirs ) = @_[0,1];
    $files = sprintf("%g %s", $files,
      $files == 1 ? 'fichier' : 'fichiers');
    $dirs = sprintf("%g %s", $dirs,
      $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires");
    return "J'ai trouv\xE9 $files dans $dirs.";
  }

Now, there's no particularly obvious way to store anything but strings in a gettext lexicon; so it looks like we just have to start over and make something better, from scratch. I call my shot at a gettext-replacement system "Maketext", or, in CPAN terms, Locale::Maketext.

When designing Maketext, I chose to plan its main features in terms of "buzzword compliance". And here are the buzzwords:

Buzzwords: Abstraction and Encapsulation

The complexity of the language you're trying to output a phrase in is entirely abstracted inside (and encapsulated within) the Maketext module for that interface. When you call:

  print $lang->maketext("You have [quant,_1,piece] of new mail.",
                       scalar(@messages));

you don't know (and in fact can't easily find out) whether this will involve lots of figuring, as in Russian (if $lang is a handle to the Russian module), or relatively little, as in Chinese. That kind of abstraction and encapsulation may encourage other pleasant buzzwords like modularization and stratification, depending on what design decisions you make.

Buzzword: Isomorphism

"Isomorphism" means "having the same structure or form"; in discussions of program design, the word takes on the special, specific meaning that your implementation of a solution to a problem has the same structure as, say, an informal verbal description of the solution, or maybe of the problem itself. Isomorphism is, all things considered, a good thing -- it's what problem-solving (and solution-implementing) should look like.

What's wrong the with gettext-using code like this...

  printf( $file_count == 1 ?
    ( $directory_count == 1 ?
     "Your query matched %g file in %g directory." :
     "Your query matched %g file in %g directories." ) :
    ( $directory_count == 1 ?
     "Your query matched %g files in %g directory." :
     "Your query matched %g files in %g directories." ),
   $file_count, $directory_count,
  );

is first off that it's not well abstracted -- these ways of testing for grammatical number (as in the expressions like foo == 1 ? singular_form : plural_form) should be abstracted to each language module, since how you get grammatical number is language-specific.

But second off, it's not isomorphic -- the "solution" (i.e., the phrasebook entries) for Chinese maps from these four English phrases to the one Chinese phrase that fits for all of them. In other words, the informal solution would be "The way to say what you want in Chinese is with the one phrase 'For your question, in Y directories you would find X files'" -- and so the implemented solution should be, isomorphically, just a straightforward way to spit out that one phrase, with numerals properly interpolated. It shouldn't have to map from the complexity of other languages to the simplicity of this one.

Buzzword: Inheritance

There's a great deal of reuse possible for sharing of phrases between modules for related dialects, or for sharing of auxiliary functions between related languages. (By "auxiliary functions", I mean functions that don't produce phrase-text, but which, say, return an answer to "does this number require a plural noun after it?". Such auxiliary functions would be used in the internal logic of functions that actually do produce phrase-text.)

In the case of sharing phrases, consider that you have an interface already localized for American English (probably by having been written with that as the native locale, but that's incidental). Localizing it for UK English should, in practical terms, be just a matter of running it past a British person with the instructions to indicate what few phrases would benefit from a change in spelling or possibly minor rewording. In that case, you should be able to put in the UK English localization module only those phrases that are UK-specific, and for all the rest, inherit from the American English module. (And I expect this same situation would apply with Brazilian and Continental Portugese, possbily with some very closely related languages like Czech and Slovak, and possibly with the slightly different "versions" of written Mandarin Chinese, as I hear exist in Taiwan and mainland China.)

As to sharing of auxiliary functions, consider the problem of Russian numbers from the beginning of this article; obviously, you'd want to write only once the hairy code that, given a numeric value, would return some specification of which case and number a given quanitified noun should use. But suppose that you discover, while localizing an interface for, say, Ukranian (a Slavic language related to Russian, spoken by several million people, many of whom would be relieved to find that your Web site's or software's interface is available in their language), that the rules in Ukranian are the same as in Russian for quantification, and probably for many other grammatical functions. While there may well be no phrases in common between Russian and Ukranian, you could still choose to have the Ukranian module inherit from the Russian module, just for the sake of inheriting all the various grammatical methods. Or, probably better organizationally, you could move those functions to a module called _E_Slavic or something, which Russian and Ukranian could inherit useful functions from, but which would (presumably) provide no lexicon.

Buzzword: Concision

Okay, concision isn't a buzzword. But it should be, so I decree that as a new buzzword, "concision" means that simple common things should be expressible in very few lines (or maybe even just a few characters) of code -- call it a special case of "making simple things easy and hard things possible", and see also the role it played in the MIDI::Simple language, discussed elsewhere in this issue [TPJ#13].

Consider our first stab at an entry in our "phrasebook of functions":

  sub I_found_X1_files_in_X2_directories {
    my( $files, $dirs ) = @_[0,1];
    $files = sprintf("%g %s", $files,
      $files == 1 ? 'fichier' : 'fichiers');
    $dirs = sprintf("%g %s", $dirs,
      $dirs == 1 ? "r\xE9pertoire" : "r\xE9pertoires");
    return "J'ai trouv\xE9 $files dans $dirs.";
  }

You may sense that a lexicon (to use a non-committal catch-all term for a collection of things you know how to say, regardless of whether they're phrases or words) consisting of functions expressed as above would make for rather long-winded and repetitive code -- even if you wisely rewrote this to have quantification (as we call adding a number expression to a noun phrase) be a function called like:

  sub I_found_X1_files_in_X2_directories {
    my( $files, $dirs ) = @_[0,1];
    $files = quant($files, "fichier");
    $dirs =  quant($dirs,  "r\xE9pertoire");
    return "J'ai trouv\xE9 $files dans $dirs.";
  }

And you may also sense that you do not want to bother your translators with having to write Perl code -- you'd much rather that they spend their very costly time on just translation. And this is to say nothing of the near impossibility of finding a commercial translator who would know even simple Perl.

In a first-hack implementation of Maketext, each language-module's lexicon looked like this:

 %Lexicon = (
   "I found %g files in %g directories"
   => sub {
      my( $files, $dirs ) = @_[0,1];
      $files = quant($files, "fichier");
      $dirs =  quant($dirs,  "r\xE9pertoire");
      return "J'ai trouv\xE9 $files dans $dirs.";
    },
  ... and so on with other phrase => sub mappings ...
 );

but I immediately went looking for some more concise way to basically denote the same phrase-function -- a way that would also serve to concisely denote most phrase-functions in the lexicon for most languages. After much time and even some actual thought, I decided on this system:

* Where a value in a %Lexicon hash is a contentful string instead of an anonymous sub (or, conceivably, a coderef), it would be interpreted as a sort of shorthand expression of what the sub does. When accessed for the first time in a session, it is parsed, turned into Perl code, and then eval'd into an anonymous sub; then that sub replaces the original string in that lexicon. (That way, the work of parsing and evaling the shorthand form for a given phrase is done no more than once per session.)

* Calls to maketext (as Maketext's main function is called) happen thru a "language session handle", notionally very much like an IO handle, in that you open one at the start of the session, and use it for "sending signals" to an object in order to have it return the text you want.

So, this:

  $lang->maketext("You have [quant,_1,piece] of new mail.",
                 scalar(@messages));

basically means this: look in the lexicon for $lang (which may inherit from any number of other lexicons), and find the function that we happen to associate with the string "You have [quant,_1,piece] of new mail" (which is, and should be, a functioning "shorthand" for this function in the native locale -- English in this case). If you find such a function, call it with $lang as its first parameter (as if it were a method), and then a copy of scalar(@messages) as its second, and then return that value. If that function was found, but was in string shorthand instead of being a fully specified function, parse it and make it into a function before calling it the first time.

* The shorthand uses code in brackets to indicate method calls that should be performed. A full explanation is not in order here, but a few examples will suffice:

  "You have [quant,_1,piece] of new mail."

The above code is shorthand for, and will be interpreted as, this:

  sub {
    my $handle = $_[0];
    my(@params) = @_;
    return join '',
      "You have ",
      $handle->quant($params[1], 'piece'),
      "of new mail.";
  }

where "quant" is the name of a method you're using to quantify the noun "piece" with the number $params[0].

A string with no brackety calls, like this:

  "Your search expression was malformed."

is somewhat of a degerate case, and just gets turned into:

  sub { return "Your search expression was malformed." }

However, not everything you can write in Perl code can be written in the above shorthand system -- not by a long shot. For example, consider the Italian translator from the beginning of this article, who wanted the Italian for "I didn't find any files" as a special case, instead of "I found 0 files". That couldn't be specified (at least not easily or simply) in our shorthand system, and it would have to be written out in full, like this:

  sub {  # pretend the English strings are in Italian
    my($handle, $files, $dirs) = @_[0,1,2];
    return "I didn't find any files" unless $files;
    return join '',
      "I found ",
      $handle->quant($files, 'file'),
      " in ",
      $handle->quant($dirs,  'directory'),
      ".";
  }

Next to a lexicon full of shorthand code, that sort of sticks out like a sore thumb -- but this is a special case, after all; and at least it's possible, if not as concise as usual.

As to how you'd implement the Russian example from the beginning of the article, well, There's More Than One Way To Do It, but it could be something like this (using English words for Russian, just so you know what's going on):

  "I [quant,_1,directory,accusative] scanned."

This shifts the burden of complexity off to the quant method. That method's parameters are: the numeric value it's going to use to quantify something; the Russian word it's going to quantify; and the parameter "accusative", which you're using to mean that this sentence's syntax wants a noun in the accusative case there, although that quantification method may have to overrule, for grammatical reasons you may recall from the beginning of this article.

Now, the Russian quant method here is responsible not only for implementing the strange logic necessary for figuring out how Russian number-phrases impose case and number on their noun-phrases, but also for inflecting the Russian word for "directory". How that inflection is to be carried out is no small issue, and among the solutions I've seen, some (like variations on a simple lookup in a hash where all possible forms are provided for all necessary words) are straightforward but can become cumbersome when you need to inflect more than a few dozen words; and other solutions (like using algorithms to model the inflections, storing only root forms and irregularities) can involve more overhead than is justifiable for all but the largest lexicons.

Mercifully, this design decision becomes crucial only in the hairiest of inflected languages, of which Russian is by no means the worst case scenario, but is worse than most. Most languages have simpler inflection systems; for example, in English or Swahili, there are generally no more than two possible inflected forms for a given noun ("error/errors"; "kosa/makosa"), and the rules for producing these forms are fairly simple -- or at least, simple rules can be formulated that work for most words, and you can then treat the exceptions as just "irregular", at least relative to your ad hoc rules. A simpler inflection system (simpler rules, fewer forms) means that design decisions are less crucial to maintaining sanity, whereas the same decisions could incur overhead-versus-scalability problems in languages like Russian. It may also be likely that code (possibly in Perl, as with Lingua::EN::Inflect, for English nouns) has already been written for the language in question, whether simple or complex.

Moreover, a third possibility may even be simpler than anything discussed above: "Just require that all possible (or at least applicable) forms be provided in the call to the given language's quant method, as in:"

  "I found [quant,_1,file,files]."

That way, quant just has to chose which form it needs, without having to look up or generate anything. While possibly not optimal for Russian, this should work well for most other languages, where quantification is not as complicated an operation.

The Devil in the Details

There's plenty more to Maketext than described above -- for example, there's the details of how language tags ("en-US", "i-pwn", "fi", etc.) or locale IDs ("en_US") interact with actual module naming ("BogoQuery/Locale/en_us.pm"), and what magic can ensue; there's the details of how to record (and possibly negotiate) what character encoding Maketext will return text in (UTF8? Latin-1? KOI8?). There's the interesting fact that Maketext is for localization, but nowhere actually has a "use locale;" anywhere in it. For the curious, there's the somewhat frightening details of how I actually implement something like data inheritance so that searches across modules' %Lexicon hashes can parallel how Perl implements method inheritance.

And, most importantly, there's all the practical details of how to actually go about deriving from Maketext so you can use it for your interfaces, and the various tools and conventions for starting out and maintaining individual language modules.

That is all covered in the documentation for Locale::Maketext and the modules that come with it, available in CPAN. After having read this article, which covers the why's of Maketext, the documentation, which covers the how's of it, should be quite straightfoward.

The Proof in the Pudding: Localizing Web Sites

Maketext and gettext have a notable difference: gettext is in C, accessible thru C library calls, whereas Maketext is in Perl, and really can't work without a Perl interpreter (although I suppose something like it could be written for C). Accidents of history (and not necessarily lucky ones) have made C++ the most common language for the implementation of applications like word processors, Web browsers, and even many in-house applications like custom query systems. Current conditions make it somewhat unlikely that the next one of any of these kinds of applications will be written in Perl, albeit clearly more for reasons of custom and inertia than out of consideration of what is the right tool for the job.

However, other accidents of history have made Perl a well-accepted language for design of server-side programs (generally in CGI form) for Web site interfaces. Localization of static pages in Web sites is trivial, feasable either with simple language-negotiation features in servers like Apache, or with some kind of server-side inclusions of language-appropriate text into layout templates. However, I think that the localization of Perl-based search systems (or other kinds of dynamic content) in Web sites, be they public or access-restricted, is where Maketext will see the greatest use.

I presume that it would be only the exceptional Web site that gets localized for English and Chinese and Italian and Arabic and Russian, to recall the languages from the beginning of this article -- to say nothing of German, Spanish, French, Japanese, Finnish, and Hindi, to name a few languages that benefit from large numbers of programmers or Web viewers or both.

However, the ever-increasing internationalization of the Web (whether measured in terms of amount of content, of numbers of content writers or programmers, or of size of content audiences) makes it increasingly likely that the interface to the average Web-based dynamic content service will be localized for two or maybe three languages. It is my hope that Maketext will make that task as simple as possible, and will remove previous barriers to localization for languages dissimilar to English.

 __END__

Sean M. Burke (sburke@cpan.org) has a Master's in linguistics from Northwestern University; he specializes in language technology. Jordan Lachler (lachler@unm.edu) is a PhD student in the Department of Linguistics at the University of New Mexico; he specializes in morphology and pedagogy of North American native languages.

References

Alvestrand, Harald Tveit. 1995. RFC 1766: Tags for the Identification of Languages. ftp://ftp.isi.edu/in-notes/rfc1766.txt [Now see RFC 3066.]

Callon, Ross, editor. 1996. RFC 1925: The Twelve Networking Truths. ftp://ftp.isi.edu/in-notes/rfc1925.txt

Drepper, Ulrich, Peter Miller, and François Pinard. 1995-2001. GNU gettext. Available in ftp://prep.ai.mit.edu/pub/gnu/, with extensive docs in the distribution tarball. [Since I wrote this article in 1998, I now see that the gettext docs are now trying more to come to terms with plurality. Whether useful conclusions have come from it is another question altogether. -- SMB, May 2001]

Forbes, Nevill. 1964. Russian Grammar. Third Edition, revised by J. C. Dumbreck. Oxford University Press.


Locale::Script - ISO codes for script identification

    • SPECIAL CODES
  • CONVERSION ROUTINES
  • QUERY ROUTINES
  • EXAMPLES
  • KNOWN BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Locale::Script - ISO codes for script identification (ISO 15924)

SYNOPSIS

    use Locale::Script;
    use Locale::Constants;

    $script  = code2script('ph');                       # 'Phoenician'
    $code    = script2code('Tibetan');                  # 'bo'
    $code3   = script2code('Tibetan',
                           LOCALE_CODE_ALPHA_3);        # 'bod'
    $codeN   = script2code('Tibetan',
                           LOCALE_CODE_ALPHA_NUMERIC);  # 330

    @codes   = all_script_codes();
    @scripts = all_script_names();

DESCRIPTION

The Locale::Script module provides access to the ISO codes for identifying scripts, as defined in ISO 15924. For example, Egyptian hieroglyphs are denoted by the two-letter code 'eg', the three-letter code 'egy', and the numeric code 050.

You can either access the codes via the conversion routines (described below), or with the two functions which return lists of all script codes or all script names.

There are three different code sets you can use for identifying scripts:

alpha-2

Two letter codes, such as 'bo' for Tibetan. This code set is identified with the symbol LOCALE_CODE_ALPHA_2.

alpha-3

Three letter codes, such as 'ell' for Greek. This code set is identified with the symbol LOCALE_CODE_ALPHA_3.

numeric

Numeric codes, such as 410 for Hiragana. This code set is identified with the symbol LOCALE_CODE_NUMERIC.

All of the routines take an optional additional argument which specifies the code set to use. If not specified, it defaults to the two-letter codes. This is partly for backwards compatibility (previous versions of Locale modules only supported the alpha-2 codes), and partly because they are the most widely used codes.

The alpha-2 and alpha-3 codes are not case-dependent, so you can use 'BO', 'Bo', 'bO' or 'bo' for Tibetan. When a code is returned by one of the functions in this module, it will always be lower-case.

SPECIAL CODES

The standard defines various special codes.

  • The standard reserves codes in the ranges qa - qt, qaa - qat, and 900 - 919, for private use.

  • zx, zxx, and 997, are the codes for unwritten languages.

  • zy, zyy, and 998, are the codes for an undetermined script.

  • zz, zzz, and 999, are the codes for an uncoded script.

The private codes are not recognised by Locale::Script, but the others are.

CONVERSION ROUTINES

There are three conversion routines: code2script(), script2code(), and script_code2code().

code2script( CODE, [ CODESET ] )

This function takes a script code and returns a string which contains the name of the script identified. If the code is not a valid script code, as defined by ISO 15924, then undef will be returned:

    $script = code2script('cy');   # Cyrillic
script2code( STRING, [ CODESET ] )

This function takes a script name and returns the corresponding script code, if such exists. If the argument could not be identified as a script name, then undef will be returned:

    $code = script2code('Gothic', LOCALE_CODE_ALPHA_3);
    # $code will now be 'gth'

The case of the script name is not important. See the section KNOWN BUGS AND LIMITATIONS below.

script_code2code( CODE, CODESET, CODESET )

This function takes a script code from one code set, and returns the corresponding code from another code set.

    $alpha2 = script_code2code('jwi',
                 LOCALE_CODE_ALPHA_3 => LOCALE_CODE_ALPHA_2);
    # $alpha2 will now be 'jw' (Javanese)

If the code passed is not a valid script code in the first code set, or if there isn't a code for the corresponding script in the second code set, then undef will be returned.

QUERY ROUTINES

There are two function which can be used to obtain a list of all codes, or all script names:

all_script_codes ( [ CODESET ] )

Returns a list of all two-letter script codes. The codes are guaranteed to be all lower-case, and not in any particular order.

all_script_names ( [ CODESET ] )

Returns a list of all script names for which there is a corresponding script code in the specified code set. The names are capitalised, and not returned in any particular order.

EXAMPLES

The following example illustrates use of the code2script() function. The user is prompted for a script code, and then told the corresponding script name:

    $| = 1;   # turn off buffering

    print "Enter script code: ";
    chop($code = <STDIN>);
    $script = code2script($code, LOCALE_CODE_ALPHA_2);
    if (defined $script)
    {
        print "$code = $script\n";
    }
    else
    {
        print "'$code' is not a valid script code!\n";
    }

KNOWN BUGS AND LIMITATIONS

  • When using script2code(), the script name must currently appear exactly as it does in the source of the module. For example,

        script2code('Egyptian hieroglyphs')

    will return eg, as expected. But the following will all return undef:

        script2code('hieroglyphs')
    script2code('Egyptian Hieroglypics')

    If there's need for it, a future version could have variants for script names.

  • In the current implementation, all data is read in when the module is loaded, and then held in memory. A lazy implementation would be more memory friendly.

SEE ALSO

Locale::Language

ISO two letter codes for identification of language (ISO 639).

Locale::Currency

ISO three letter codes for identification of currencies and funds (ISO 4217).

Locale::Country

ISO three letter codes for identification of countries (ISO 3166)

ISO 15924

The ISO standard which defines these codes.

http://www.evertype.com/standards/iso15924/

Home page for ISO 15924.

AUTHOR

Neil Bowers <neil@bowers.com>

COPYRIGHT

Copyright (c) 2002-2004 Neil Bowers.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


MD5 - Perl interface to the MD5 Message-Digest Algorithm

  • SEE ALSO

NAME

MD5 - Perl interface to the MD5 Message-Digest Algorithm

SYNOPSIS

 use MD5;

 $context = new MD5;
 $context->reset();

 $context->add(LIST);
 $context->addfile(HANDLE);

 $digest = $context->digest();
 $string = $context->hexdigest();

 $digest = MD5->hash(SCALAR);
 $string = MD5->hexhash(SCALAR);

DESCRIPTION

The MD5 module is depreciated. Use Digest::MD5 instead.

The current MD5 module is just a wrapper around the Digest::MD5 module. It is provided so that legacy code that rely on the old interface still work and get the speed benefit of the new module.

In addition to the methods provided for Digest::MD5 objects, this module provide the class methods MD5->hash() and MD5->hexhash() that do the same as the md5() and md5_hex() functions provided by Digest::MD5.

SEE ALSO

the Digest::MD5 manpage


MIME::Base64 - Encoding and decoding of base64 strings

  • DIAGNOSTICS
  • EXAMPLES
  • COPYRIGHT
  • SEE ALSO

NAME

MIME::Base64 - Encoding and decoding of base64 strings

SYNOPSIS

 use MIME::Base64;

 $encoded = encode_base64('Aladdin:open sesame');
 $decoded = decode_base64($encoded);

DESCRIPTION

This module provides functions to encode and decode strings into and from the base64 encoding specified in RFC 2045 - MIME (Multipurpose Internet Mail Extensions). The base64 encoding is designed to represent arbitrary sequences of octets in a form that need not be humanly readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used, enabling 6 bits to be represented per printable character.

The following functions are provided:

encode_base64($str)
encode_base64($str, $eol);

Encode data by calling the encode_base64() function. The first argument is the string to encode. The second argument is the line-ending sequence to use. It is optional and defaults to "\n". The returned encoded string is broken into lines of no more than 76 characters each and it will end with $eol unless it is empty. Pass an empty string as second argument if you do not want the encoded string to be broken into lines.

decode_base64($str)

Decode a base64 string by calling the decode_base64() function. This function takes a single argument which is the string to decode and returns the decoded data.

Any character not part of the 65-character base64 subset is silently ignored. Characters occurring after a '=' padding character are never decoded.

If the length of the string to decode, after ignoring non-base64 chars, is not a multiple of 4 or if padding occurs too early, then a warning is generated if perl is running under -w.

If you prefer not to import these routines into your namespace, you can call them as:

    use MIME::Base64 ();
    $encoded = MIME::Base64::encode($decoded);
    $decoded = MIME::Base64::decode($encoded);

DIAGNOSTICS

The following warnings can be generated if perl is invoked with the -w switch:

Premature end of base64 data

The number of characters to decode is not a multiple of 4. Legal base64 data should be padded with one or two "=" characters to make its length a multiple of 4. The decoded result will be the same whether the padding is present or not.

Premature padding of base64 data

The '=' padding character occurs as the first or second character in a base64 quartet.

The following exception can be raised:

Wide character in subroutine entry

The string passed to encode_base64() contains characters with code above 255. The base64 encoding is only defined for single-byte characters. Use the Encode module to select the byte encoding you want.

EXAMPLES

If you want to encode a large file, you should encode it in chunks that are a multiple of 57 bytes. This ensures that the base64 lines line up and that you do not end up with padding in the middle. 57 bytes of data fills one complete base64 line (76 == 57*4/3):

   use MIME::Base64 qw(encode_base64);

   open(FILE, "/var/log/wtmp") or die "$!";
   while (read(FILE, $buf, 60*57)) {
       print encode_base64($buf);
   }

or if you know you have enough memory

   use MIME::Base64 qw(encode_base64);
   local($/) = undef;  # slurp
   print encode_base64(<STDIN>);

The same approach as a command line:

   perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file

Decoding does not need slurp mode if every line contains a multiple of four base64 chars:

   perl -MMIME::Base64 -ne 'print decode_base64($_)' <file

Perl v5.8 and better allow extended Unicode characters in strings. Such strings cannot be encoded directly, as the base64 encoding is only defined for single-byte characters. The solution is to use the Encode module to select the byte encoding you want. For example:

    use MIME::Base64 qw(encode_base64);
    use Encode qw(encode);

    $encoded = encode_base64(encode("UTF-8", "\x{FFFF}\n"));
    print $encoded;

COPYRIGHT

Copyright 1995-1999, 2001-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Distantly based on LWP::Base64 written by Martijn Koster <m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans Mulder <hansm@wsinti07.win.tue.nl>

The XS implementation uses code from metamail. Copyright 1991 Bell Communications Research, Inc. (Bellcore)

SEE ALSO

the MIME::QuotedPrint manpage


MIME::QuotedPrint - Encoding and decoding of quoted-printable strings

  • COPYRIGHT
  • SEE ALSO

NAME

MIME::QuotedPrint - Encoding and decoding of quoted-printable strings

SYNOPSIS

 use MIME::QuotedPrint;

 $encoded = encode_qp($decoded);
 $decoded = decode_qp($encoded);

DESCRIPTION

This module provides functions to encode and decode strings into and from the quoted-printable encoding specified in RFC 2045 - MIME (Multipurpose Internet Mail Extensions). The quoted-printable encoding is intended to represent data that largely consists of bytes that correspond to printable characters in the ASCII character set. Each non-printable character (as defined by English Americans) is represented by a triplet consisting of the character "=" followed by two hexadecimal digits.

The following functions are provided:

encode_qp($str)
encode_qp($str, $eol)
encode_qp($str, $eol, $binmode)

This function returns an encoded version of the string ($str) given as argument.

The second argument ($eol) is the line-ending sequence to use. It is optional and defaults to "\n". Every occurrence of "\n" is replaced with this string, and it is also used for additional "soft line breaks" to ensure that no line end up longer than 76 characters. Pass it as "\015\012" to produce data suitable for external consumption. The string "\r\n" produces the same result on many platforms, but not all.

The third argument ($binmode) will select binary mode if passed as a TRUE value. In binary mode "\n" will be encoded in the same way as any other non-printable character. This ensures that a decoder will end up with exactly the same string whatever line ending sequence it uses. In general it is preferable to use the base64 encoding for binary data; see the MIME::Base64 manpage.

An $eol of "" (the empty string) is special. In this case, no "soft line breaks" are introduced and binary mode is effectively enabled so that any "\n" in the original data is encoded as well.

decode_qp($str);

This function returns the plain text version of the string given as argument. The lines of the result are "\n" terminated, even if the $str argument contains "\r\n" terminated lines.

If you prefer not to import these routines into your namespace, you can call them as:

  use MIME::QuotedPrint ();
  $encoded = MIME::QuotedPrint::encode($decoded);
  $decoded = MIME::QuotedPrint::decode($encoded);

Perl v5.8 and better allow extended Unicode characters in strings. Such strings cannot be encoded directly, as the quoted-printable encoding is only defined for single-byte characters. The solution is to use the Encode module to select the byte encoding you want. For example:

    use MIME::QuotedPrint qw(encode_qp);
    use Encode qw(encode);

    $encoded = encode_qp(encode("UTF-8", "\x{FFFF}\n"));
    print $encoded;

COPYRIGHT

Copyright 1995-1997,2002-2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the MIME::Base64 manpage


Math::BigFloat - Arbitrary size floating point math package

    • Canonical notation
    • Output
    • mantissa(), exponent() and parts()
    • Accuracy vs. Precision
    • Rounding
  • METHODS
    • accuracy
    • precision()
  • Autocreating constants
    • Math library
    • Using Math::BigInt::Lite
  • BUGS
  • CAVEATS
  • SEE ALSO
  • LICENSE
  • AUTHORS

NAME

Math::BigFloat - Arbitrary size floating point math package

SYNOPSIS

  use Math::BigFloat;

  # Number creation
  $x = Math::BigFloat->new($str);       # defaults to 0
  $nan  = Math::BigFloat->bnan();       # create a NotANumber
  $zero = Math::BigFloat->bzero();      # create a +0
  $inf = Math::BigFloat->binf();        # create a +inf
  $inf = Math::BigFloat->binf('-');     # create a -inf
  $one = Math::BigFloat->bone();        # create a +1
  $one = Math::BigFloat->bone('-');     # create a -1

  # Testing
  $x->is_zero();                # true if arg is +0
  $x->is_nan();                 # true if arg is NaN
  $x->is_one();                 # true if arg is +1
  $x->is_one('-');              # true if arg is -1
  $x->is_odd();                 # true if odd, false for even
  $x->is_even();                # true if even, false for odd
  $x->is_pos();                 # true if >= 0
  $x->is_neg();                 # true if <  0
  $x->is_inf(sign);             # true if +inf, or -inf (default is '+')

  $x->bcmp($y);                 # compare numbers (undef,<0,=0,>0)
  $x->bacmp($y);                # compare absolutely (undef,<0,=0,>0)
  $x->sign();                   # return the sign, either +,- or NaN
  $x->digit($n);                # return the nth digit, counting from right
  $x->digit(-$n);               # return the nth digit, counting from left

  # The following all modify their first argument. If you want to preserve
  # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
  # neccessary when mixing $a = $b assigments with non-overloaded math.

  # set
  $x->bzero();                  # set $i to 0
  $x->bnan();                   # set $i to NaN
  $x->bone();                   # set $x to +1
  $x->bone('-');                # set $x to -1
  $x->binf();                   # set $x to inf
  $x->binf('-');                # set $x to -inf

  $x->bneg();                   # negation
  $x->babs();                   # absolute value
  $x->bnorm();                  # normalize (no-op)
  $x->bnot();                   # two's complement (bit wise not)
  $x->binc();                   # increment x by 1
  $x->bdec();                   # decrement x by 1

  $x->badd($y);                 # addition (add $y to $x)
  $x->bsub($y);                 # subtraction (subtract $y from $x)
  $x->bmul($y);                 # multiplication (multiply $x by $y)
  $x->bdiv($y);                 # divide, set $x to quotient
                                # return (quo,rem) or quo if scalar

  $x->bmod($y);                 # modulus ($x % $y)
  $x->bpow($y);                 # power of arguments ($x ** $y)
  $x->blsft($y);                # left shift
  $x->brsft($y);                # right shift
                                # return (quo,rem) or quo if scalar

  $x->blog();                   # logarithm of $x to base e (Euler's number)
  $x->blog($base);              # logarithm of $x to base $base (f.i. 2)

  $x->band($y);                 # bit-wise and
  $x->bior($y);                 # bit-wise inclusive or
  $x->bxor($y);                 # bit-wise exclusive or
  $x->bnot();                   # bit-wise not (two's complement)

  $x->bsqrt();                  # calculate square-root
  $x->broot($y);                # $y'th root of $x (e.g. $y == 3 => cubic root)
  $x->bfac();                   # factorial of $x (1*2*3*4*..$x)

  $x->bround($N);               # accuracy: preserve $N digits
  $x->bfround($N);              # precision: round to the $Nth digit

  $x->bfloor();                 # return integer less or equal than $x
  $x->bceil();                  # return integer greater or equal than $x

  # The following do not modify their arguments:

  bgcd(@values);                # greatest common divisor
  blcm(@values);                # lowest common multiplicator

  $x->bstr();                   # return string
  $x->bsstr();                  # return string in scientific notation

  $x->as_int();                 # return $x as BigInt
  $x->exponent();               # return exponent as BigInt
  $x->mantissa();               # return mantissa as BigInt
  $x->parts();                  # return (mantissa,exponent) as BigInt

  $x->length();                 # number of digits (w/o sign and '.')
  ($l,$f) = $x->length();       # number of digits, and length of fraction

  $x->precision();              # return P of $x (or global, if P of $x undef)
  $x->precision($n);            # set P of $x to $n
  $x->accuracy();               # return A of $x (or global, if A of $x undef)
  $x->accuracy($n);             # set A $x to $n

  # these get/set the appropriate global value for all BigFloat objects
  Math::BigFloat->precision();  # Precision
  Math::BigFloat->accuracy();   # Accuracy
  Math::BigFloat->round_mode(); # rounding mode

DESCRIPTION

All operators (inlcuding basic math operations) are overloaded if you declare your big floating point numbers as

  $i = new Math::BigFloat '12_3.456_789_123_456_789E-2';

Operations with overloaded operators preserve the arguments, which is exactly what you expect.

Canonical notation

Input to these routines are either BigFloat objects, or strings of the following four forms:

  • /^[+-]\d+$/

  • /^[+-]\d+\.\d*$/

  • /^[+-]\d+E[+-]?\d+$/

  • /^[+-]\d*\.\d+E[+-]?\d+$/

all with optional leading and trailing zeros and/or spaces. Additonally, numbers are allowed to have an underscore between any two digits.

Empty strings as well as other illegal numbers results in 'NaN'.

bnorm() on a BigFloat object is now effectively a no-op, since the numbers are always stored in normalized form. On a string, it creates a BigFloat object.

Output

Output values are BigFloat objects (normalized), except for bstr() and bsstr().

The string output will always have leading and trailing zeros stripped and drop a plus sign. bstr() will give you always the form with a decimal point, while bsstr() (s for scientific) gives you the scientific notation.

        Input                   bstr()          bsstr()
        '-0'                    '0'             '0E1'
        '  -123 123 123'        '-123123123'    '-123123123E0'
        '00.0123'               '0.0123'        '123E-4'
        '123.45E-2'             '1.2345'        '12345E-4'
        '10E+3'                 '10000'         '1E4'

Some routines (is_odd(), is_even(), is_zero(), is_one(), is_nan()) return true or false, while others (bcmp(), bacmp()) return either undef, <0, 0 or >0 and are suited for sort.

Actual math is done by using the class defined with with = Class;> (which defaults to BigInts) to represent the mantissa and exponent.

The sign /^[+-]$/ is stored separately. The string 'NaN' is used to represent the result when input arguments are not numbers, as well as the result of dividing by zero.

mantissa(), exponent() and parts()

mantissa() and exponent() return the said parts of the BigFloat as BigInts such that:

        $m = $x->mantissa();
        $e = $x->exponent();
        $y = $m * ( 10 ** $e );
        print "ok\n" if $x == $y;

($m,$e) = $x->parts(); is just a shortcut giving you both of them.

A zero is represented and returned as 0E1, not 0E0 (after Knuth).

Currently the mantissa is reduced as much as possible, favouring higher exponents over lower ones (e.g. returning 1e7 instead of 10e6 or 10000000e0). This might change in the future, so do not depend on it.

Accuracy vs. Precision

See also: Rounding.

Math::BigFloat supports both precision (rounding to a certain place before or after the dot) and accuracy (rounding to a certain number of digits). For a full documentation, examples and tips on these topics please see the large section about rounding in the Math::BigInt manpage.

Since things like sqrt(2) or 1 / 3 must presented with a limited accuracy lest a operation consumes all resources, each operation produces no more than the requested number of digits.

If there is no gloabl precision or accuracy set, and the operation in question was not called with a requested precision or accuracy, and the input $x has no accuracy or precision set, then a fallback parameter will be used. For historical reasons, it is called div_scale and can be accessed via:

        $d = Math::BigFloat->div_scale();               # query
        Math::BigFloat->div_scale($n);                  # set to $n digits

The default value for div_scale is 40.

In case the result of one operation has more digits than specified, it is rounded. The rounding mode taken is either the default mode, or the one supplied to the operation after the scale:

        $x = Math::BigFloat->new(2);
        Math::BigFloat->accuracy(5);            # 5 digits max
        $y = $x->copy()->bdiv(3);               # will give 0.66667
        $y = $x->copy()->bdiv(3,6);             # will give 0.666667
        $y = $x->copy()->bdiv(3,6,undef,'odd'); # will give 0.666667
        Math::BigFloat->round_mode('zero');
        $y = $x->copy()->bdiv(3,6);             # will also give 0.666667

Note that Math::BigFloat->accuracy() and Math::BigFloat->precision() set the global variables, and thus any newly created number will be subject to the global rounding immidiately. This means that in the examples above, the 3 as argument to bdiv() will also get an accuracy of 5.

It is less confusing to either calculate the result fully, and afterwards round it explicitely, or use the additional parameters to the math functions like so:

        use Math::BigFloat;
        $x = Math::BigFloat->new(2);
        $y = $x->copy()->bdiv(3);
        print $y->bround(5),"\n";               # will give 0.66667

        or
        use Math::BigFloat;
        $x = Math::BigFloat->new(2);
        $y = $x->copy()->bdiv(3,5);             # will give 0.66667
        print "$y\n";

Rounding

ffround ( +$scale )

Rounds to the $scale'th place left from the '.', counting from the dot. The first digit is numbered 1.

ffround ( -$scale )

Rounds to the $scale'th place right from the '.', counting from the dot.

ffround ( 0 )

Rounds to an integer.

fround ( +$scale )

Preserves accuracy to $scale digits from the left (aka significant digits) and pads the rest with zeros. If the number is between 1 and -1, the significant digits count from the first non-zero after the '.'

fround ( -$scale ) and fround ( 0 )

These are effectively no-ops.

All rounding functions take as a second parameter a rounding mode from one of the following: 'even', 'odd', '+inf', '-inf', 'zero' or 'trunc'.

The default rounding mode is 'even'. By using Math::BigFloat->round_mode($round_mode); you can get and set the default mode for subsequent rounding. The usage of $Math::BigFloat::$round_mode is no longer supported. The second parameter to the round functions then overrides the default temporarily.

The as_number() function returns a BigInt from a Math::BigFloat. It uses 'trunc' as rounding mode to make it equivalent to:

        $x = 2.5;
        $y = int($x) + 2;

You can override this by passing the desired rounding mode as parameter to as_number():

        $x = Math::BigFloat->new(2.5);
        $y = $x->as_number('odd');      # $y = 3

METHODS

accuracy

        $x->accuracy(5);                # local for $x
        CLASS->accuracy(5);             # global for all members of CLASS
                                        # Note: This also applies to new()!

        $A = $x->accuracy();            # read out accuracy that affects $x
        $A = CLASS->accuracy();         # read out global accuracy

Set or get the global or local accuracy, aka how many significant digits the results have. If you set a global accuracy, then this also applies to new()!

Warning! The accuracy sticks, e.g. once you created a number under the influence of CLASS->accuracy($A), all results from math operations with that number will also be rounded.

In most cases, you should probably round the results explicitely using one of round(), bround() or bfround() or by passing the desired accuracy to the math operation as additional parameter:

        my $x = Math::BigInt->new(30000);
        my $y = Math::BigInt->new(7);
        print scalar $x->copy()->bdiv($y, 2);           # print 4300
        print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300

precision()

        $x->precision(-2);      # local for $x, round at the second digit right of the dot
        $x->precision(2);       # ditto, round at the second digit left of the dot

        CLASS->precision(5);    # Global for all members of CLASS
                                # This also applies to new()!
        CLASS->precision(-5);   # ditto

        $P = CLASS->precision();        # read out global precision
        $P = $x->precision();           # read out precision that affects $x

Note: You probably want to use accuracy() instead. With the accuracy manpage you set the number of digits each result should have, with precision you set the place where to round!

Autocreating constants

After use Math::BigFloat ':constant' all the floating point constants in the given scope are converted to Math::BigFloat. This conversion happens at compile time.

In particular

  perl -MMath::BigFloat=:constant -e 'print 2E-100,"\n"'

prints the value of 2E-100. Note that without conversion of constants the expression 2E-100 will be calculated as normal floating point number.

Please note that ':constant' does not affect integer constants, nor binary nor hexadecimal constants. Use the bignum manpage or the Math::BigInt manpage to get this to work.

Math library

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use Math::BigFloat lib => 'Calc';

You can change this by using:

        use Math::BigFloat lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use Math::BigFloat lib => 'Foo,Math::BigInt::Bar';

Calc.pm uses as internal format an array of elements of some decimal base (usually 1e7, but this might be differen for some systems) with the least significant digit first, while BitVect.pm uses a bit vector of base 2, most significant bit first. Other modules might use even different means of representing the numbers. See the respective module documentation for further details.

Please note that Math::BigFloat does not use the denoted library itself, but it merely passes the lib argument to Math::BigInt. So, instead of the need to do:

        use Math::BigInt lib => 'GMP';
        use Math::BigFloat;

you can roll it all into one line:

        use Math::BigFloat lib => 'GMP';

It is also possible to just require Math::BigFloat:

        require Math::BigFloat;

This will load the neccessary things (like BigInt) when they are needed, and automatically.

Use the lib, Luke! And see Using Math::BigInt::Lite for more details than you ever wanted to know about loading a different library.

Using Math::BigInt::Lite

It is possible to use the Math::BigInt::Lite manpage with Math::BigFloat:

        # 1
        use Math::BigFloat with => 'Math::BigInt::Lite';

There is no need to "use Math::BigInt" or "use Math::BigInt::Lite", but you can combine these if you want. For instance, you may want to use Math::BigInt objects in your main script, too.

        # 2
        use Math::BigInt;
        use Math::BigFloat with => 'Math::BigInt::Lite';

Of course, you can combine this with the lib parameter.

        # 3
        use Math::BigFloat with => 'Math::BigInt::Lite', lib => 'GMP,Pari';

There is no need for a "use Math::BigInt;" statement, even if you want to use Math::BigInt's, since Math::BigFloat will needs Math::BigInt and thus always loads it. But if you add it, add it before:

        # 4
        use Math::BigInt;
        use Math::BigFloat with => 'Math::BigInt::Lite', lib => 'GMP,Pari';

Notice that the module with the last lib will "win" and thus it's lib will be used if the lib is available:

        # 5
        use Math::BigInt lib => 'Bar,Baz';
        use Math::BigFloat with => 'Math::BigInt::Lite', lib => 'Foo';

That would try to load Foo, Bar, Baz and Calc (in that order). Or in other words, Math::BigFloat will try to retain previously loaded libs when you don't specify it onem but if you specify one, it will try to load them.

Actually, the lib loading order would be "Bar,Baz,Calc", and then "Foo,Bar,Baz,Calc", but independend of which lib exists, the result is the same as trying the latter load alone, except for the fact that one of Bar or Baz might be loaded needlessly in an intermidiate step (and thus hang around and waste memory). If neither Bar nor Baz exist (or don't work/compile), they will still be tried to be loaded, but this is not as time/memory consuming as actually loading one of them. Still, this type of usage is not recommended due to these issues.

The old way (loading the lib only in BigInt) still works though:

        # 6
        use Math::BigInt lib => 'Bar,Baz';
        use Math::BigFloat;

You can even load Math::BigInt afterwards:

        # 7
        use Math::BigFloat;
        use Math::BigInt lib => 'Bar,Baz';

But this has the same problems like #5, it will first load Calc (Math::BigFloat needs Math::BigInt and thus loads it) and then later Bar or Baz, depending on which of them works and is usable/loadable. Since this loads Calc unnecc., it is not recommended.

Since it also possible to just require Math::BigFloat, this poses the question about what libary this will use:

        require Math::BigFloat;
        my $x = Math::BigFloat->new(123); $x += 123;

It will use Calc. Please note that the call to import() is still done, but only when you use for the first time some Math::BigFloat math (it is triggered via any constructor, so the first time you create a Math::BigFloat, the load will happen in the background). This means:

        require Math::BigFloat;
        Math::BigFloat->import ( lib => 'Foo,Bar' );

would be the same as:

        use Math::BigFloat lib => 'Foo, Bar';

But don't try to be clever to insert some operations in between:

        require Math::BigFloat;
        my $x = Math::BigFloat->bone() + 4;             # load BigInt and Calc
        Math::BigFloat->import( lib => 'Pari' );        # load Pari, too
        $x = Math::BigFloat->bone()+4;                  # now use Pari

While this works, it loads Calc needlessly. But maybe you just wanted that?

Examples #3 is highly recommended for daily usage.

BUGS

Please see the file BUGS in the CPAN distribution Math::BigInt for known bugs.

CAVEATS

stringify, bstr()

Both stringify and bstr() now drop the leading '+'. The old code would return '+1.23', the new returns '1.23'. See the documentation in the Math::BigInt manpage for reasoning and details.

bdiv

The following will probably not do what you expect:

        print $c->bdiv(123.456),"\n";

It prints both quotient and reminder since print works in list context. Also, bdiv() will modify $c, so be carefull. You probably want to use

        print $c / 123.456,"\n";
        print scalar $c->bdiv(123.456),"\n";  # or if you want to modify $c

instead.

Modifying and =

Beware of:

        $x = Math::BigFloat->new(5);
        $y = $x;

It will not do what you think, e.g. making a copy of $x. Instead it just makes a second reference to the same object and stores it in $y. Thus anything that modifies $x will modify $y (except overloaded math operators), and vice versa. See the Math::BigInt manpage for details and how to avoid that.

bpow

bpow() now modifies the first argument, unlike the old code which left it alone and only returned the result. This is to be consistent with badd() etc. The first will modify $x, the second one won't:

        print bpow($x,$i),"\n";         # modify $x
        print $x->bpow($i),"\n";        # ditto
        print $x ** $i,"\n";            # leave $x alone
precision() vs. accuracy()

A common pitfall is to use precision() when you want to round a result to a certain number of digits:

        use Math::BigFloat;

        Math::BigFloat->precision(4);           # does not do what you think it does
        my $x = Math::BigFloat->new(12345);     # rounds $x to "12000"!
        print "$x\n";                           # print "12000"
        my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
        print "$y\n";                           # print "0"
        $z = $x / $y;                           # 12000 / 0 => NaN!
        print "$z\n";
        print $z->precision(),"\n";             # 4

Replacing precision with the accuracy manpage is probably not what you want, either:

        use Math::BigFloat;

        Math::BigFloat->accuracy(4);            # enables global rounding:
        my $x = Math::BigFloat->new(123456);    # rounded immidiately to "12350"
        print "$x\n";                           # print "123500"
        my $y = Math::BigFloat->new(3);         # rounded to "3
        print "$y\n";                           # print "3"
        print $z = $x->copy()->bdiv($y),"\n";   # 41170
        print $z->accuracy(),"\n";              # 4

What you want to use instead is:

        use Math::BigFloat;

        my $x = Math::BigFloat->new(123456);    # no rounding
        print "$x\n";                           # print "123456"
        my $y = Math::BigFloat->new(3);         # no rounding
        print "$y\n";                           # print "3"
        print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
        print $z->accuracy(),"\n";              # undef

In addition to computing what you expected, the last example also does not "taint" the result with an accuracy or precision setting, which would influence any further operation.

SEE ALSO

the Math::BigInt manpage, the Math::BigRat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

The pragmas the bignum manpage, the bigint manpage and the bigrat manpage might also be of interest because they solve the autoupgrading/downgrading issue, at least partly.

The package at http://search.cpan.org/search contains more documentation including a full version history, testcases, empty subclass files and benchmarks.

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Mark Biggar, overloaded interface by Ilya Zakharevich. Completely rewritten by Tels http://bloodgate.com in 2001 - 2004, and still at it in 2005.


Math::BigInt - Arbitrary size integer/float math package

  • METHODS
    • config
    • accuracy
    • precision
    • brsft
    • new
    • bnan
    • bzero
    • binf
    • bone
    • is_one()/is_zero()/is_nan()/is_inf()
    • is_pos()/is_neg()
    • is_odd()/is_even()/is_int()
    • bcmp
    • bacmp
    • sign
    • digit
    • bneg
    • babs
    • bnorm
    • bnot
    • binc
    • bdec
    • badd
    • bsub
    • bmul
    • bdiv
    • bmod
    • bmodinv
    • bmodpow
    • bpow
    • blsft
    • brsft
    • band
    • bior
    • bxor
    • bnot
    • bsqrt
    • bfac
    • round
    • bround
    • bfround
    • bfloor
    • bceil
    • bgcd
    • blcm
    • exponent
    • mantissa
    • parts
    • copy
    • as_int
    • bsstr
    • as_hex
    • as_bin
  • ACCURACY and PRECISION
    • Precision P
    • Accuracy A
    • Fallback F
    • Rounding mode R
  • Infinity and Not a Number
  • INTERNALS
    • MATH LIBRARY
    • SIGN
    • mantissa(), exponent() and parts()
  • EXAMPLES
  • Autocreating constants
  • PERFORMANCE
    • Alternative math libraries
    • SUBCLASSING
  • Subclassing Math::BigInt
  • UPGRADING
    • Auto-upgrade
  • BUGS
  • CAVEATS
  • LICENSE
  • SEE ALSO
  • AUTHORS

NAME

Math::BigInt - Arbitrary size integer/float math package

SYNOPSIS

  use Math::BigInt;

  # or make it faster: install (optional) Math::BigInt::GMP
  # and always use (it will fall back to pure Perl if the
  # GMP library is not installed):

  use Math::BigInt lib => 'GMP';

  my $str = '1234567890';
  my @values = (64,74,18);
  my $n = 1; my $sign = '-';

  # Number creation
  $x = Math::BigInt->new($str);         # defaults to 0
  $y = $x->copy();                      # make a true copy
  $nan  = Math::BigInt->bnan();         # create a NotANumber
  $zero = Math::BigInt->bzero();        # create a +0
  $inf = Math::BigInt->binf();          # create a +inf
  $inf = Math::BigInt->binf('-');       # create a -inf
  $one = Math::BigInt->bone();          # create a +1
  $one = Math::BigInt->bone('-');       # create a -1

  # Testing (don't modify their arguments)
  # (return true if the condition is met, otherwise false)

  $x->is_zero();        # if $x is +0
  $x->is_nan();         # if $x is NaN
  $x->is_one();         # if $x is +1
  $x->is_one('-');      # if $x is -1
  $x->is_odd();         # if $x is odd
  $x->is_even();        # if $x is even
  $x->is_pos();         # if $x >= 0
  $x->is_neg();         # if $x <  0
  $x->is_inf($sign);    # if $x is +inf, or -inf (sign is default '+')
  $x->is_int();         # if $x is an integer (not a float)

  # comparing and digit/sign extration
  $x->bcmp($y);         # compare numbers (undef,<0,=0,>0)
  $x->bacmp($y);        # compare absolutely (undef,<0,=0,>0)
  $x->sign();           # return the sign, either +,- or NaN
  $x->digit($n);        # return the nth digit, counting from right
  $x->digit(-$n);       # return the nth digit, counting from left

  # The following all modify their first argument. If you want to preserve
  # $x, use $z = $x->copy()->bXXX($y); See under L<CAVEATS> for why this is
  # neccessary when mixing $a = $b assigments with non-overloaded math.

  $x->bzero();          # set $x to 0
  $x->bnan();           # set $x to NaN
  $x->bone();           # set $x to +1
  $x->bone('-');        # set $x to -1
  $x->binf();           # set $x to inf
  $x->binf('-');        # set $x to -inf

  $x->bneg();           # negation
  $x->babs();           # absolute value
  $x->bnorm();          # normalize (no-op in BigInt)
  $x->bnot();           # two's complement (bit wise not)
  $x->binc();           # increment $x by 1
  $x->bdec();           # decrement $x by 1

  $x->badd($y);         # addition (add $y to $x)
  $x->bsub($y);         # subtraction (subtract $y from $x)
  $x->bmul($y);         # multiplication (multiply $x by $y)
  $x->bdiv($y);         # divide, set $x to quotient
                        # return (quo,rem) or quo if scalar

  $x->bmod($y);            # modulus (x % y)
  $x->bmodpow($exp,$mod);  # modular exponentation (($num**$exp) % $mod))
  $x->bmodinv($mod);       # the inverse of $x in the given modulus $mod

  $x->bpow($y);            # power of arguments (x ** y)
  $x->blsft($y);           # left shift
  $x->brsft($y);           # right shift
  $x->blsft($y,$n);        # left shift, by base $n (like 10)
  $x->brsft($y,$n);        # right shift, by base $n (like 10)

  $x->band($y);            # bitwise and
  $x->bior($y);            # bitwise inclusive or
  $x->bxor($y);            # bitwise exclusive or
  $x->bnot();              # bitwise not (two's complement)

  $x->bsqrt();             # calculate square-root
  $x->broot($y);           # $y'th root of $x (e.g. $y == 3 => cubic root)
  $x->bfac();              # factorial of $x (1*2*3*4*..$x)

  $x->round($A,$P,$mode);  # round to accuracy or precision using mode $mode
  $x->bround($n);          # accuracy: preserve $n digits
  $x->bfround($n);         # round to $nth digit, no-op for BigInts

  # The following do not modify their arguments in BigInt (are no-ops),
  # but do so in BigFloat:

  $x->bfloor();            # return integer less or equal than $x
  $x->bceil();             # return integer greater or equal than $x

  # The following do not modify their arguments:

  # greatest common divisor (no OO style)
  my $gcd = Math::BigInt::bgcd(@values);
  # lowest common multiplicator (no OO style)
  my $lcm = Math::BigInt::blcm(@values);

  $x->length();            # return number of digits in number
  ($xl,$f) = $x->length(); # length of number and length of fraction part,
                           # latter is always 0 digits long for BigInts

  $x->exponent();          # return exponent as BigInt
  $x->mantissa();          # return (signed) mantissa as BigInt
  $x->parts();             # return (mantissa,exponent) as BigInt
  $x->copy();              # make a true copy of $x (unlike $y = $x;)
  $x->as_int();            # return as BigInt (in BigInt: same as copy())
  $x->numify();            # return as scalar (might overflow!)

  # conversation to string (do not modify their argument)
  $x->bstr();              # normalized string (e.g. '3')
  $x->bsstr();             # norm. string in scientific notation (e.g. '3E0')
  $x->as_hex();            # as signed hexadecimal string with prefixed 0x
  $x->as_bin();            # as signed binary string with prefixed 0b

  # precision and accuracy (see section about rounding for more)
  $x->precision();         # return P of $x (or global, if P of $x undef)
  $x->precision($n);       # set P of $x to $n
  $x->accuracy();          # return A of $x (or global, if A of $x undef)
  $x->accuracy($n);        # set A $x to $n

  # Global methods
  Math::BigInt->precision();    # get/set global P for all BigInt objects
  Math::BigInt->accuracy();     # get/set global A for all BigInt objects
  Math::BigInt->round_mode();   # get/set global round mode, one of
                                # 'even', 'odd', '+inf', '-inf', 'zero' or 'trunc'
  Math::BigInt->config();       # return hash containing configuration

DESCRIPTION

All operators (inlcuding basic math operations) are overloaded if you declare your big integers as

  $i = new Math::BigInt '123_456_789_123_456_789';

Operations with overloaded operators preserve the arguments which is exactly what you expect.

Input

Input values to these routines may be any string, that looks like a number and results in an integer, including hexadecimal and binary numbers.

Scalars holding numbers may also be passed, but note that non-integer numbers may already have lost precision due to the conversation to float. Quote your input if you want BigInt to see all the digits:

        $x = Math::BigInt->new(12345678890123456789);   # bad
        $x = Math::BigInt->new('12345678901234567890'); # good

You can include one underscore between any two digits.

This means integer values like 1.01E2 or even 1000E-2 are also accepted. Non-integer values result in NaN.

Currently, Math::BigInt::new() defaults to 0, while Math::BigInt::new('') results in 'NaN'. This might change in the future, so use always the following explicit forms to get a zero or NaN:

        $zero = Math::BigInt->bzero();
        $nan = Math::BigInt->bnan();

bnorm() on a BigInt object is now effectively a no-op, since the numbers are always stored in normalized form. If passed a string, creates a BigInt object from the input.

Output

Output values are BigInt objects (normalized), except for the methods which return a string (see SYNOPSIS).

Some routines (is_odd(), is_even(), is_zero(), is_one(), is_nan(), etc.) return true or false, while others (bcmp(), bacmp()) return either undef (if NaN is involved), <0, 0 or >0 and are suited for sort.

METHODS

Each of the methods below (except config(), accuracy() and precision()) accepts three additional parameters. These arguments $A, $P and $R are accuracy, precision and round_mode. Please see the section about ACCURACY and PRECISION for more information.

config

        use Data::Dumper;

        print Dumper ( Math::BigInt->config() );
        print Math::BigInt->config()->{lib},"\n";

Returns a hash containing the configuration, e.g. the version number, lib loaded etc. The following hash keys are currently filled in with the appropriate information.

        key             Description
                        Example
        ============================================================
        lib             Name of the low-level math library
                        Math::BigInt::Calc
        lib_version     Version of low-level math library (see 'lib')
                        0.30
        class           The class name of config() you just called
                        Math::BigInt
        upgrade         To which class math operations might be upgraded
                        Math::BigFloat
        downgrade       To which class math operations might be downgraded
                        undef
        precision       Global precision
                        undef
        accuracy        Global accuracy
                        undef
        round_mode      Global round mode
                        even
        version         version number of the class you used
                        1.61
        div_scale       Fallback acccuracy for div
                        40
        trap_nan        If true, traps creation of NaN via croak()
                        1
        trap_inf        If true, traps creation of +inf/-inf via croak()
                        1

The following values can be set by passing config() a reference to a hash:

        trap_inf trap_nan
        upgrade downgrade precision accuracy round_mode div_scale

Example:

        $new_cfg = Math::BigInt->config( { trap_inf => 1, precision => 5 } );

accuracy

        $x->accuracy(5);                # local for $x
        CLASS->accuracy(5);             # global for all members of CLASS
                                        # Note: This also applies to new()!

        $A = $x->accuracy();            # read out accuracy that affects $x
        $A = CLASS->accuracy();         # read out global accuracy

Set or get the global or local accuracy, aka how many significant digits the results have. If you set a global accuracy, then this also applies to new()!

Warning! The accuracy sticks, e.g. once you created a number under the influence of CLASS->accuracy($A), all results from math operations with that number will also be rounded.

In most cases, you should probably round the results explicitely using one of round(), bround() or bfround() or by passing the desired accuracy to the math operation as additional parameter:

        my $x = Math::BigInt->new(30000);
        my $y = Math::BigInt->new(7);
        print scalar $x->copy()->bdiv($y, 2);           # print 4300
        print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300

Please see the section about ACCURACY AND PRECISION for further details.

Value must be greater than zero. Pass an undef value to disable it:

        $x->accuracy(undef);
        Math::BigInt->accuracy(undef);

Returns the current accuracy. For $x-accuracy()> it will return either the local accuracy, or if not defined, the global. This means the return value represents the accuracy that will be in effect for $x:

        $y = Math::BigInt->new(1234567);        # unrounded
        print Math::BigInt->accuracy(4),"\n";   # set 4, print 4
        $x = Math::BigInt->new(123456);         # $x will be automatically rounded!
        print "$x $y\n";                        # '123500 1234567'
        print $x->accuracy(),"\n";              # will be 4
        print $y->accuracy(),"\n";              # also 4, since global is 4
        print Math::BigInt->accuracy(5),"\n";   # set to 5, print 5
        print $x->accuracy(),"\n";              # still 4
        print $y->accuracy(),"\n";              # 5, since global is 5

Note: Works also for subclasses like Math::BigFloat. Each class has it's own globals separated from Math::BigInt, but it is possible to subclass Math::BigInt and make the globals of the subclass aliases to the ones from Math::BigInt.

precision

        $x->precision(-2);      # local for $x, round at the second digit right of the dot
        $x->precision(2);       # ditto, round at the second digit left of the dot

        CLASS->precision(5);    # Global for all members of CLASS
                                # This also applies to new()!
        CLASS->precision(-5);   # ditto

        $P = CLASS->precision();        # read out global precision
        $P = $x->precision();           # read out precision that affects $x

Note: You probably want to use accuracy() instead. With the accuracy manpage you set the number of digits each result should have, with the precision manpage you set the place where to round!

precision() sets or gets the global or local precision, aka at which digit before or after the dot to round all results. A set global precision also applies to all newly created numbers!

In Math::BigInt, passing a negative number precision has no effect since no numbers have digits after the dot. In the Math::BigFloat manpage, it will round all results to P digits after the dot.

Please see the section about ACCURACY AND PRECISION for further details.

Pass an undef value to disable it:

        $x->precision(undef);
        Math::BigInt->precision(undef);

Returns the current precision. For $x-precision()> it will return either the local precision of $x, or if not defined, the global. This means the return value represents the prevision that will be in effect for $x:

        $y = Math::BigInt->new(1234567);        # unrounded
        print Math::BigInt->precision(4),"\n";  # set 4, print 4
        $x = Math::BigInt->new(123456);         # will be automatically rounded
        print $x;                               # print "120000"!

Note: Works also for subclasses like the Math::BigFloat manpage. Each class has its own globals separated from Math::BigInt, but it is possible to subclass Math::BigInt and make the globals of the subclass aliases to the ones from Math::BigInt.

brsft

        $x->brsft($y,$n);

Shifts $x right by $y in base $n. Default is base 2, used are usually 10 and 2, but others work, too.

Right shifting usually amounts to dividing $x by $n ** $y and truncating the result:

        $x = Math::BigInt->new(10);
        $x->brsft(1);                   # same as $x >> 1: 5
        $x = Math::BigInt->new(1234);
        $x->brsft(2,10);                # result 12

There is one exception, and that is base 2 with negative $x:

        $x = Math::BigInt->new(-5);
        print $x->brsft(1);

This will print -3, not -2 (as it would if you divide -5 by 2 and truncate the result).

new

        $x = Math::BigInt->new($str,$A,$P,$R);

Creates a new BigInt object from a scalar or another BigInt object. The input is accepted as decimal, hex (with leading '0x') or binary (with leading '0b').

See Input for more info on accepted input formats.

bnan

        $x = Math::BigInt->bnan();

Creates a new BigInt object representing NaN (Not A Number). If used on an object, it will set it to NaN:

        $x->bnan();

bzero

        $x = Math::BigInt->bzero();

Creates a new BigInt object representing zero. If used on an object, it will set it to zero:

        $x->bzero();

binf

        $x = Math::BigInt->binf($sign);

Creates a new BigInt object representing infinity. The optional argument is either '-' or '+', indicating whether you want infinity or minus infinity. If used on an object, it will set it to infinity:

        $x->binf();
        $x->binf('-');

bone

        $x = Math::BigInt->binf($sign);

Creates a new BigInt object representing one. The optional argument is either '-' or '+', indicating whether you want one or minus one. If used on an object, it will set it to one:

        $x->bone();             # +1
        $x->bone('-');          # -1

is_one()/is_zero()/is_nan()/is_inf()

        $x->is_zero();                  # true if arg is +0
        $x->is_nan();                   # true if arg is NaN
        $x->is_one();                   # true if arg is +1
        $x->is_one('-');                # true if arg is -1
        $x->is_inf();                   # true if +inf
        $x->is_inf('-');                # true if -inf (sign is default '+')

These methods all test the BigInt for beeing one specific value and return true or false depending on the input. These are faster than doing something like:

        if ($x == 0)

is_pos()/is_neg()

        $x->is_pos();                   # true if > 0
        $x->is_neg();                   # true if < 0

The methods return true if the argument is positive or negative, respectively. NaN is neither positive nor negative, while +inf counts as positive, and -inf is negative. A zero is neither positive nor negative.

These methods are only testing the sign, and not the value.

is_positive() and is_negative() are aliase to is_pos() and is_neg(), respectively. is_positive() and is_negative() were introduced in v1.36, while is_pos() and is_neg() were only introduced in v1.68.

is_odd()/is_even()/is_int()

        $x->is_odd();                   # true if odd, false for even
        $x->is_even();                  # true if even, false for odd
        $x->is_int();                   # true if $x is an integer

The return true when the argument satisfies the condition. NaN, +inf, -inf are not integers and are neither odd nor even.

In BigInt, all numbers except NaN, +inf and -inf are integers.

bcmp

        $x->bcmp($y);

Compares $x with $y and takes the sign into account. Returns -1, 0, 1 or undef.

bacmp

        $x->bacmp($y);

Compares $x with $y while ignoring their. Returns -1, 0, 1 or undef.

sign

        $x->sign();

Return the sign, of $x, meaning either +, -, -inf, +inf or NaN.

If you want $x to have a certain sign, use one of the following methods:

        $x->babs();             # '+'
        $x->babs()->bneg();     # '-'
        $x->bnan();             # 'NaN'
        $x->binf();             # '+inf'
        $x->binf('-');          # '-inf'

digit

        $x->digit($n);          # return the nth digit, counting from right

If $n is negative, returns the digit counting from left.

bneg

        $x->bneg();

Negate the number, e.g. change the sign between '+' and '-', or between '+inf' and '-inf', respectively. Does nothing for NaN or zero.

babs

        $x->babs();

Set the number to it's absolute value, e.g. change the sign from '-' to '+' and from '-inf' to '+inf', respectively. Does nothing for NaN or positive numbers.

bnorm

        $x->bnorm();                    # normalize (no-op)

bnot

        $x->bnot();

Two's complement (bit wise not). This is equivalent to

        $x->binc()->bneg();

but faster.

binc

        $x->binc();                     # increment x by 1

bdec

        $x->bdec();                     # decrement x by 1

badd

        $x->badd($y);                   # addition (add $y to $x)

bsub

        $x->bsub($y);                   # subtraction (subtract $y from $x)

bmul

        $x->bmul($y);                   # multiplication (multiply $x by $y)

bdiv

        $x->bdiv($y);                   # divide, set $x to quotient
                                        # return (quo,rem) or quo if scalar

bmod

        $x->bmod($y);                   # modulus (x % y)

bmodinv

        num->bmodinv($mod);             # modular inverse

Returns the inverse of $num in the given modulus $mod. 'NaN' is returned unless $num is relatively prime to $mod, i.e. unless bgcd($num, $mod)==1.

bmodpow

        $num->bmodpow($exp,$mod);       # modular exponentation
                                        # ($num**$exp % $mod)

Returns the value of $num taken to the power $exp in the modulus $mod using binary exponentation. bmodpow is far superior to writing

        $num ** $exp % $mod

because it is much faster - it reduces internal variables into the modulus whenever possible, so it operates on smaller numbers.

bmodpow also supports negative exponents.

        bmodpow($num, -1, $mod)

is exactly equivalent to

        bmodinv($num, $mod)

bpow

        $x->bpow($y);                   # power of arguments (x ** y)

blsft

        $x->blsft($y);          # left shift
        $x->blsft($y,$n);       # left shift, in base $n (like 10)

brsft

        $x->brsft($y);          # right shift
        $x->brsft($y,$n);       # right shift, in base $n (like 10)

band

        $x->band($y);                   # bitwise and

bior

        $x->bior($y);                   # bitwise inclusive or

bxor

        $x->bxor($y);                   # bitwise exclusive or

bnot

        $x->bnot();                     # bitwise not (two's complement)

bsqrt

        $x->bsqrt();                    # calculate square-root

bfac

        $x->bfac();                     # factorial of $x (1*2*3*4*..$x)

round

        $x->round($A,$P,$round_mode);

        Round $x to accuracy C<$A> or precision C<$P> using the round mode
        C<$round_mode>.

bround

        $x->bround($N);               # accuracy: preserve $N digits

bfround

        $x->bfround($N);              # round to $Nth digit, no-op for BigInts

bfloor

        $x->bfloor();

Set $x to the integer less or equal than $x. This is a no-op in BigInt, but does change $x in BigFloat.

bceil

        $x->bceil();

Set $x to the integer greater or equal than $x. This is a no-op in BigInt, but does change $x in BigFloat.

bgcd

        bgcd(@values);          # greatest common divisor (no OO style)

blcm

        blcm(@values);          # lowest common multiplicator (no OO style)

        head2 length

        $x->length();
        ($xl,$fl) = $x->length();

Returns the number of digits in the decimal representation of the number. In list context, returns the length of the integer and fraction part. For BigInt's, the length of the fraction part will always be 0.

exponent

        $x->exponent();

Return the exponent of $x as BigInt.

mantissa

        $x->mantissa();

Return the signed mantissa of $x as BigInt.

parts

        $x->parts();            # return (mantissa,exponent) as BigInt

copy

        $x->copy();             # make a true copy of $x (unlike $y = $x;)

as_int

        $x->as_int();

Returns $x as a BigInt (truncated towards zero). In BigInt this is the same as copy().

as_number() is an alias to this method. as_number was introduced in v1.22, while as_int() was only introduced in v1.68.

=head2 bstr
        $x->bstr();

Returns a normalized string represantation of $x.

bsstr

        $x->bsstr();            # normalized string in scientific notation

as_hex

        $x->as_hex();           # as signed hexadecimal string with prefixed 0x

as_bin

        $x->as_bin();           # as signed binary string with prefixed 0b

ACCURACY and PRECISION

Since version v1.33, Math::BigInt and Math::BigFloat have full support for accuracy and precision based rounding, both automatically after every operation, as well as manually.

This section describes the accuracy/precision handling in Math::Big* as it used to be and as it is now, complete with an explanation of all terms and abbreviations.

Not yet implemented things (but with correct description) are marked with '!', things that need to be answered are marked with '?'.

In the next paragraph follows a short description of terms used here (because these may differ from terms used by others people or documentation).

During the rest of this document, the shortcuts A (for accuracy), P (for precision), F (fallback) and R (rounding mode) will be used.

Precision P

A fixed number of digits before (positive) or after (negative) the decimal point. For example, 123.45 has a precision of -2. 0 means an integer like 123 (or 120). A precision of 2 means two digits to the left of the decimal point are zero, so 123 with P = 1 becomes 120. Note that numbers with zeros before the decimal point may have different precisions, because 1200 can have p = 0, 1 or 2 (depending on what the inital value was). It could also have p < 0, when the digits after the decimal point are zero.

The string output (of floating point numbers) will be padded with zeros:

        Initial value   P       A       Result          String
        ------------------------------------------------------------
        1234.01         -3              1000            1000
        1234            -2              1200            1200
        1234.5          -1              1230            1230
        1234.001        1               1234            1234.0
        1234.01         0               1234            1234
        1234.01         2               1234.01         1234.01
        1234.01         5               1234.01         1234.01000

For BigInts, no padding occurs.

Accuracy A

Number of significant digits. Leading zeros are not counted. A number may have an accuracy greater than the non-zero digits when there are zeros in it or trailing zeros. For example, 123.456 has A of 6, 10203 has 5, 123.0506 has 7, 123.450000 has 8 and 0.000123 has 3.

The string output (of floating point numbers) will be padded with zeros:

        Initial value   P       A       Result          String
        ------------------------------------------------------------
        1234.01                 3       1230            1230
        1234.01                 6       1234.01         1234.01
        1234.1                  8       1234.1          1234.1000

For BigInts, no padding occurs.

Fallback F

When both A and P are undefined, this is used as a fallback accuracy when dividing numbers.

Rounding mode R

When rounding a number, different 'styles' or 'kinds' of rounding are possible. (Note that random rounding, as in Math::Round, is not implemented.)

'trunc'

truncation invariably removes all digits following the rounding place, replacing them with zeros. Thus, 987.65 rounded to tens (P=1) becomes 980, and rounded to the fourth sigdig becomes 987.6 (A=4). 123.456 rounded to the second place after the decimal point (P=-2) becomes 123.46.

All other implemented styles of rounding attempt to round to the "nearest digit." If the digit D immediately to the right of the rounding place (skipping the decimal point) is greater than 5, the number is incremented at the rounding place (possibly causing a cascade of incrementation): e.g. when rounding to units, 0.9 rounds to 1, and -19.9 rounds to -20. If D < 5, the number is similarly truncated at the rounding place: e.g. when rounding to units, 0.4 rounds to 0, and -19.4 rounds to -19.

However the results of other styles of rounding differ if the digit immediately to the right of the rounding place (skipping the decimal point) is 5 and if there are no digits, or no digits other than 0, after that 5. In such cases:

'even'

rounds the digit at the rounding place to 0, 2, 4, 6, or 8 if it is not already. E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.

'odd'

rounds the digit at the rounding place to 1, 3, 5, 7, or 9 if it is not already. E.g., when rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5, but 0.5501 becomes 0.6.

'+inf'

round to plus infinity, i.e. always round up. E.g., when rounding to the first sigdig, 0.45 becomes 0.5, -0.55 becomes -0.5, and 0.4501 also becomes 0.5.

'-inf'

round to minus infinity, i.e. always round down. E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.6, but 0.4501 becomes 0.5.

'zero'

round to zero, i.e. positive numbers down, negative ones up. E.g., when rounding to the first sigdig, 0.45 becomes 0.4, -0.55 becomes -0.5, but 0.4501 becomes 0.5.

The handling of A & P in MBI/MBF (the old core code shipped with Perl versions <= 5.7.2) is like this:

Precision
  * ffround($p) is able to round to $p number of digits after the decimal
    point
  * otherwise P is unused
Accuracy (significant digits)
  * fround($a) rounds to $a significant digits
  * only fdiv() and fsqrt() take A as (optional) paramater
    + other operations simply create the same number (fneg etc), or more (fmul)
      of digits
    + rounding/truncating is only done when explicitly calling one of fround
      or ffround, and never for BigInt (not implemented)
  * fsqrt() simply hands its accuracy argument over to fdiv.
  * the documentation and the comment in the code indicate two different ways
    on how fdiv() determines the maximum number of digits it should calculate,
    and the actual code does yet another thing
    POD:
      max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
    Comment:
      result has at most max(scale, length(dividend), length(divisor)) digits
    Actual code:
      scale = max(scale, length(dividend)-1,length(divisor)-1);
      scale += length(divisior) - length(dividend);
    So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10+9-3).
    Actually, the 'difference' added to the scale is calculated from the
    number of "significant digits" in dividend and divisor, which is derived
    by looking at the length of the mantissa. Which is wrong, since it includes
    the + sign (oops) and actually gets 2 for '+100' and 4 for '+101'. Oops
    again. Thus 124/3 with div_scale=1 will get you '41.3' based on the strange
    assumption that 124 has 3 significant digits, while 120/7 will get you
    '17', not '17.1' since 120 is thought to have 2 significant digits.
    The rounding after the division then uses the remainder and $y to determine
    wether it must round up or down.
   ?  I have no idea which is the right way. That's why I used a slightly more
   ?  simple scheme and tweaked the few failing testcases to match it.

This is how it works now:

Setting/Accessing
  * You can set the A global via C<< Math::BigInt->accuracy() >> or
    C<< Math::BigFloat->accuracy() >> or whatever class you are using.
  * You can also set P globally by using C<< Math::SomeClass->precision() >>
    likewise.
  * Globals are classwide, and not inherited by subclasses.
  * to undefine A, use C<< Math::SomeCLass->accuracy(undef); >>
  * to undefine P, use C<< Math::SomeClass->precision(undef); >>
  * Setting C<< Math::SomeClass->accuracy() >> clears automatically
    C<< Math::SomeClass->precision() >>, and vice versa.
  * To be valid, A must be > 0, P can have any value.
  * If P is negative, this means round to the P'th place to the right of the
    decimal point; positive values mean to the left of the decimal point.
    P of 0 means round to integer.
  * to find out the current global A, use C<< Math::SomeClass->accuracy() >>
  * to find out the current global P, use C<< Math::SomeClass->precision() >>
  * use C<< $x->accuracy() >> respective C<< $x->precision() >> for the local
    setting of C<< $x >>.
  * Please note that C<< $x->accuracy() >> respecive C<< $x->precision() >>
    return eventually defined global A or P, when C<< $x >>'s A or P is not
    set.
Creating numbers
  * When you create a number, you can give it's desired A or P via:
    $x = Math::BigInt->new($number,$A,$P);
  * Only one of A or P can be defined, otherwise the result is NaN
  * If no A or P is give ($x = Math::BigInt->new($number) form), then the
    globals (if set) will be used. Thus changing the global defaults later on
    will not change the A or P of previously created numbers (i.e., A and P of
    $x will be what was in effect when $x was created)
  * If given undef for A and P, B<no> rounding will occur, and the globals will
    B<not> be used. This is used by subclasses to create numbers without
    suffering rounding in the parent. Thus a subclass is able to have it's own
    globals enforced upon creation of a number by using
    C<< $x = Math::BigInt->new($number,undef,undef) >>:

        use Math::BigInt::SomeSubclass;
        use Math::BigInt;

        Math::BigInt->accuracy(2);
        Math::BigInt::SomeSubClass->accuracy(3);
        $x = Math::BigInt::SomeSubClass->new(1234);

    $x is now 1230, and not 1200. A subclass might choose to implement
    this otherwise, e.g. falling back to the parent's A and P.
Usage
  * If A or P are enabled/defined, they are used to round the result of each
    operation according to the rules below
  * Negative P is ignored in Math::BigInt, since BigInts never have digits
    after the decimal point
  * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
    Math::BigInt as globals does not tamper with the parts of a BigFloat.
    A flag is used to mark all Math::BigFloat numbers as 'never round'.
Precedence
  * It only makes sense that a number has only one of A or P at a time.
    If you set either A or P on one object, or globally, the other one will
    be automatically cleared.
  * If two objects are involved in an operation, and one of them has A in
    effect, and the other P, this results in an error (NaN).
  * A takes precendence over P (Hint: A comes before P).
    If neither of them is defined, nothing is used, i.e. the result will have
    as many digits as it can (with an exception for fdiv/fsqrt) and will not
    be rounded.
  * There is another setting for fdiv() (and thus for fsqrt()). If neither of
    A or P is defined, fdiv() will use a fallback (F) of $div_scale digits.
    If either the dividend's or the divisor's mantissa has more digits than
    the value of F, the higher value will be used instead of F.
    This is to limit the digits (A) of the result (just consider what would
    happen with unlimited A and P in the case of 1/3 :-)
  * fdiv will calculate (at least) 4 more digits than required (determined by
    A, P or F), and, if F is not used, round the result
    (this will still fail in the case of a result like 0.12345000000001 with A
    or P of 5, but this can not be helped - or can it?)
  * Thus you can have the math done by on Math::Big* class in two modi:
    + never round (this is the default):
      This is done by setting A and P to undef. No math operation
      will round the result, with fdiv() and fsqrt() as exceptions to guard
      against overflows. You must explicitely call bround(), bfround() or
      round() (the latter with parameters).
      Note: Once you have rounded a number, the settings will 'stick' on it
      and 'infect' all other numbers engaged in math operations with it, since
      local settings have the highest precedence. So, to get SaferRound[tm],
      use a copy() before rounding like this:
        $x = Math::BigFloat->new(12.34);
        $y = Math::BigFloat->new(98.76);
        $z = $x * $y;                           # 1218.6984
        print $x->copy()->fround(3);            # 12.3 (but A is now 3!)
        $z = $x * $y;                           # still 1218.6984, without
                                                # copy would have been 1210!

    + round after each op:
      After each single operation (except for testing like is_zero()), the
      method round() is called and the result is rounded appropriately. By
      setting proper values for A and P, you can have all-the-same-A or
      all-the-same-P modes. For example, Math::Currency might set A to undef,
      and P to -2, globally.
 ?Maybe an extra option that forbids local A & P settings would be in order,
 ?so that intermediate rounding does not 'poison' further math?
Overriding globals
  * you will be able to give A, P and R as an argument to all the calculation
    routines; the second parameter is A, the third one is P, and the fourth is
    R (shift right by one for binary operations like badd). P is used only if
    the first parameter (A) is undefined. These three parameters override the
    globals in the order detailed as follows, i.e. the first defined value
    wins:
    (local: per object, global: global default, parameter: argument to sub)
      + parameter A
      + parameter P
      + local A (if defined on both of the operands: smaller one is taken)
      + local P (if defined on both of the operands: bigger one is taken)
      + global A
      + global P
      + global F
  * fsqrt() will hand its arguments to fdiv(), as it used to, only now for two
    arguments (A and P) instead of one
Local settings
  * You can set A or P locally by using C<< $x->accuracy() >> or
    C<< $x->precision() >>
    and thus force different A and P for different objects/numbers.
  * Setting A or P this way immediately rounds $x to the new value.
  * C<< $x->accuracy() >> clears C<< $x->precision() >>, and vice versa.
Rounding
  * the rounding routines will use the respective global or local settings.
    fround()/bround() is for accuracy rounding, while ffround()/bfround()
    is for precision
  * the two rounding functions take as the second parameter one of the
    following rounding modes (R):
    'even', 'odd', '+inf', '-inf', 'zero', 'trunc'
  * you can set/get the global R by using C<< Math::SomeClass->round_mode() >>
    or by setting C<< $Math::SomeClass::round_mode >>
  * after each operation, C<< $result->round() >> is called, and the result may
    eventually be rounded (that is, if A or P were set either locally,
    globally or as parameter to the operation)
  * to manually round a number, call C<< $x->round($A,$P,$round_mode); >>
    this will round the number by using the appropriate rounding function
    and then normalize it.
  * rounding modifies the local settings of the number:

        $x = Math::BigFloat->new(123.456);
        $x->accuracy(5);
        $x->bround(4);

    Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
    will be 4 from now on.
Default values
  * R: 'even'
  * F: 40
  * A: undef
  * P: undef
Remarks
  * The defaults are set up so that the new code gives the same results as
    the old code (except in a few cases on fdiv):
    + Both A and P are undefined and thus will not be used for rounding
      after each operation.
    + round() is thus a no-op, unless given extra parameters A and P

Infinity and Not a Number

While BigInt has extensive handling of inf and NaN, certain quirks remain.

oct()/hex()

These perl routines currently (as of Perl v.5.8.6) cannot handle passed inf.

        te@linux:~> perl -wle 'print 2 ** 3333'
        inf
        te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
        1
        te@linux:~> perl -wle 'print oct(2 ** 3333)'
        0
        te@linux:~> perl -wle 'print hex(2 ** 3333)'
        Illegal hexadecimal digit 'i' ignored at -e line 1.
        0

The same problems occur if you pass them Math::BigInt->binf() objects. Since overloading these routines is not possible, this cannot be fixed from BigInt.

==, !=, <, >, <=, >= with NaNs

BigInt's bcmp() routine currently returns undef to signal that a NaN was involved in a comparisation. However, the overload code turns that into either 1 or '' and thus operations like NaN != NaN might return wrong values.

log(-inf)

log(-inf) is highly weird. Since log(-x)=pi*i+log(x), then log(-inf)=pi*i+inf. However, since the imaginary part is finite, the real infinity "overshadows" it, so the number might as well just be infinity. However, the result is a complex number, and since BigInt/BigFloat can only have real numbers as results, the result is NaN.

exp(), cos(), sin(), atan2()

These all might have problems handling infinity right.

=back

INTERNALS

The actual numbers are stored as unsigned big integers (with seperate sign).

You should neither care about nor depend on the internal representation; it might change without notice. Use ONLY method calls like $x->sign(); instead relying on the internal representation.

MATH LIBRARY

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use Math::BigInt lib => 'Calc';

You can change this by using:

        use Math::BigInt lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use Math::BigInt lib => 'Foo,Math::BigInt::Bar';

Since Math::BigInt::GMP is in almost all cases faster than Calc (especially in math involving really big numbers, where it is much faster), and there is no penalty if Math::BigInt::GMP is not installed, it is a good idea to always use the following:

        use Math::BigInt lib => 'GMP';

Different low-level libraries use different formats to store the numbers. You should NOT depend on the number having a specific format internally.

See the respective math library module documentation for further details.

SIGN

The sign is either '+', '-', 'NaN', '+inf' or '-inf'.

A sign of 'NaN' is used to represent the result when input arguments are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively minus infinity. You will get '+inf' when dividing a positive number by 0, and '-inf' when dividing any negative number by 0.

mantissa(), exponent() and parts()

mantissa() and exponent() return the said parts of the BigInt such that:

        $m = $x->mantissa();
        $e = $x->exponent();
        $y = $m * ( 10 ** $e );
        print "ok\n" if $x == $y;

($m,$e) = $x->parts() is just a shortcut that gives you both of them in one go. Both the returned mantissa and exponent have a sign.

Currently, for BigInts $e is always 0, except for NaN, +inf and -inf, where it is NaN; and for $x == 0, where it is 1 (to be compatible with Math::BigFloat's internal representation of a zero as 0E1).

$m is currently just a copy of the original number. The relation between $e and $m will stay always the same, though their real values might change.

EXAMPLES

  use Math::BigInt;

  sub bint { Math::BigInt->new(shift); }

  $x = Math::BigInt->bstr("1234")       # string "1234"
  $x = "$x";                            # same as bstr()
  $x = Math::BigInt->bneg("1234");      # BigInt "-1234"
  $x = Math::BigInt->babs("-12345");    # BigInt "12345"
  $x = Math::BigInt->bnorm("-0 00");    # BigInt "0"
  $x = bint(1) + bint(2);               # BigInt "3"
  $x = bint(1) + "2";                   # ditto (auto-BigIntify of "2")
  $x = bint(1);                         # BigInt "1"
  $x = $x + 5 / 2;                      # BigInt "3"
  $x = $x ** 3;                         # BigInt "27"
  $x *= 2;                              # BigInt "54"
  $x = Math::BigInt->new(0);            # BigInt "0"
  $x--;                                 # BigInt "-1"
  $x = Math::BigInt->badd(4,5)          # BigInt "9"
  print $x->bsstr();                    # 9e+0

Examples for rounding:

  use Math::BigFloat;
  use Test;

  $x = Math::BigFloat->new(123.4567);
  $y = Math::BigFloat->new(123.456789);
  Math::BigFloat->accuracy(4);          # no more A than 4

  ok ($x->copy()->fround(),123.4);      # even rounding
  print $x->copy()->fround(),"\n";      # 123.4
  Math::BigFloat->round_mode('odd');    # round to odd
  print $x->copy()->fround(),"\n";      # 123.5
  Math::BigFloat->accuracy(5);          # no more A than 5
  Math::BigFloat->round_mode('odd');    # round to odd
  print $x->copy()->fround(),"\n";      # 123.46
  $y = $x->copy()->fround(4),"\n";      # A = 4: 123.4
  print "$y, ",$y->accuracy(),"\n";     # 123.4, 4

  Math::BigFloat->accuracy(undef);      # A not important now
  Math::BigFloat->precision(2);         # P important
  print $x->copy()->bnorm(),"\n";       # 123.46
  print $x->copy()->fround(),"\n";      # 123.46

Examples for converting:

  my $x = Math::BigInt->new('0b1'.'01' x 123);
  print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";

Autocreating constants

After use Math::BigInt ':constant' all the integer decimal, hexadecimal and binary constants in the given scope are converted to Math::BigInt. This conversion happens at compile time.

In particular,

  perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'

prints the integer value of 2**100. Note that without conversion of constants the expression 2**100 will be calculated as perl scalar.

Please note that strings and floating point constants are not affected, so that

        use Math::BigInt qw/:constant/;

        $x = 1234567890123456789012345678901234567890
                + 123456789123456789;
        $y = '1234567890123456789012345678901234567890'
                + '123456789123456789';

do not work. You need an explicit Math::BigInt->new() around one of the operands. You should also quote large constants to protect loss of precision:

        use Math::BigInt;

        $x = Math::BigInt->new('1234567889123456789123456789123456789');

Without the quotes Perl would convert the large number to a floating point constant at compile time and then hand the result to BigInt, which results in an truncated result or a NaN.

This also applies to integers that look like floating point constants:

        use Math::BigInt ':constant';

        print ref(123e2),"\n";
        print ref(123.2e2),"\n";

will print nothing but newlines. Use either the bignum manpage or the Math::BigFloat manpage to get this to work.

PERFORMANCE

Using the form $x += $y; etc over $x = $x + $y is faster, since a copy of $x must be made in the second case. For long numbers, the copy can eat up to 20% of the work (in the case of addition/subtraction, less for multiplication/division). If $y is very small compared to $x, the form $x += $y is MUCH faster than $x = $x + $y since making the copy of $x takes more time then the actual addition.

With a technique called copy-on-write, the cost of copying with overload could be minimized or even completely avoided. A test implementation of COW did show performance gains for overloaded math, but introduced a performance loss due to a constant overhead for all other operatons. So Math::BigInt does currently not COW.

The rewritten version of this module (vs. v0.01) is slower on certain operations, like new(), bstr() and numify(). The reason are that it does now more work and handles much more cases. The time spent in these operations is usually gained in the other math operations so that code on the average should get (much) faster. If they don't, please contact the author.

Some operations may be slower for small numbers, but are significantly faster for big numbers. Other operations are now constant (O(1), like bneg(), babs() etc), instead of O(N) and thus nearly always take much less time. These optimizations were done on purpose.

If you find the Calc module to slow, try to install any of the replacement modules and see if they help you.

Alternative math libraries

You can use an alternative library to drive Math::BigInt via:

        use Math::BigInt lib => 'Module';

See MATH LIBRARY for more information.

For more benchmark results see http://bloodgate.com/perl/benchmarks.html.

SUBCLASSING

Subclassing Math::BigInt

The basic design of Math::BigInt allows simple subclasses with very little work, as long as a few simple rules are followed:

  • The public API must remain consistent, i.e. if a sub-class is overloading addition, the sub-class must use the same name, in this case badd(). The reason for this is that Math::BigInt is optimized to call the object methods directly.

  • The private object hash keys like $x-{sign}> may not be changed, but additional keys can be added, like $x-{_custom}>.

  • Accessor functions are available for all existing object hash keys and should be used instead of directly accessing the internal hash keys. The reason for this is that Math::BigInt itself has a pluggable interface which permits it to support different storage methods.

More complex sub-classes may have to replicate more of the logic internal of Math::BigInt if they need to change more basic behaviors. A subclass that needs to merely change the output only needs to overload bstr().

All other object methods and overloaded functions can be directly inherited from the parent class.

At the very minimum, any subclass will need to provide it's own new() and can store additional hash keys in the object. There are also some package globals that must be defined, e.g.:

  # Globals
  $accuracy = undef;
  $precision = -2;       # round to 2 decimal places
  $round_mode = 'even';
  $div_scale = 40;

Additionally, you might want to provide the following two globals to allow auto-upgrading and auto-downgrading to work correctly:

  $upgrade = undef;
  $downgrade = undef;

This allows Math::BigInt to correctly retrieve package globals from the subclass, like $SubClass::precision. See t/Math/BigInt/Subclass.pm or t/Math/BigFloat/SubClass.pm completely functional subclass examples.

Don't forget to

        use overload;

in your subclass to automatically inherit the overloading from the parent. If you like, you can change part of the overloading, look at Math::String for an example.

UPGRADING

When used like this:

        use Math::BigInt upgrade => 'Foo::Bar';

certain operations will 'upgrade' their calculation and thus the result to the class Foo::Bar. Usually this is used in conjunction with Math::BigFloat:

        use Math::BigInt upgrade => 'Math::BigFloat';

As a shortcut, you can use the module bignum:

        use bignum;

Also good for oneliners:

        perl -Mbignum -le 'print 2 ** 255'

This makes it possible to mix arguments of different classes (as in 2.5 + 2) as well es preserve accuracy (as in sqrt(3)).

Beware: This feature is not fully implemented yet.

Auto-upgrade

The following methods upgrade themselves unconditionally; that is if upgrade is in effect, they will always hand up their work:

bsqrt()
div()
blog()

Beware: This list is not complete.

All other methods upgrade themselves only when one (or all) of their arguments are of the class mentioned in $upgrade (This might change in later versions to a more sophisticated scheme):

BUGS

broot() does not work

The broot() function in BigInt may only work for small values. This will be fixed in a later version.

Out of Memory!

Under Perl prior to 5.6.0 having an use Math::BigInt ':constant'; and eval() in your code will crash with "Out of memory". This is probably an overload/exporter bug. You can workaround by not having eval() and ':constant' at the same time or upgrade your Perl to a newer version.

Fails to load Calc on Perl prior 5.6.0

Since eval(' use ...') can not be used in conjunction with ':constant', BigInt will fall back to eval { require ... } when loading the math lib on Perls prior to 5.6.0. This simple replaces '::' with '/' and thus might fail on filesystems using a different seperator.

CAVEATS

Some things might not work as you expect them. Below is documented what is known to be troublesome:

bstr(), bsstr() and 'cmp'

Both bstr() and bsstr() as well as automated stringify via overload now drop the leading '+'. The old code would return '+3', the new returns '3'. This is to be consistent with Perl and to make cmp (especially with overloading) to work as you expect. It also solves problems with Test.pm, because it's ok() uses 'eq' internally.

Mark Biggar said, when asked about to drop the '+' altogether, or make only cmp work:

        I agree (with the first alternative), don't add the '+' on positive
        numbers.  It's not as important anymore with the new internal
        form for numbers.  It made doing things like abs and neg easier,
        but those have to be done differently now anyway.

So, the following examples will now work all as expected:

        use Test;
        BEGIN { plan tests => 1 }
        use Math::BigInt;

        my $x = new Math::BigInt 3*3;
        my $y = new Math::BigInt 3*3;

        ok ($x,3*3);
        print "$x eq 9" if $x eq $y;
        print "$x eq 9" if $x eq '9';
        print "$x eq 9" if $x eq 3*3;

Additionally, the following still works:

        print "$x == 9" if $x == $y;
        print "$x == 9" if $x == 9;
        print "$x == 9" if $x == 3*3;

There is now a bsstr() method to get the string in scientific notation aka 1e+2 instead of 100. Be advised that overloaded 'eq' always uses bstr() for comparisation, but Perl will represent some numbers as 100 and others as 1e+308. If in doubt, convert both arguments to Math::BigInt before comparing them as strings:

        use Test;
        BEGIN { plan tests => 3 }
        use Math::BigInt;

        $x = Math::BigInt->new('1e56'); $y = 1e56;
        ok ($x,$y);                     # will fail
        ok ($x->bsstr(),$y);            # okay
        $y = Math::BigInt->new($y);
        ok ($x,$y);                     # okay

Alternatively, simple use <=> for comparisations, this will get it always right. There is not yet a way to get a number automatically represented as a string that matches exactly the way Perl represents it.

See also the section about Infinity and Not a Number for problems in comparing NaNs.

int()

int() will return (at least for Perl v5.7.1 and up) another BigInt, not a Perl scalar:

        $x = Math::BigInt->new(123);
        $y = int($x);                           # BigInt 123
        $x = Math::BigFloat->new(123.45);
        $y = int($x);                           # BigInt 123

In all Perl versions you can use as_number() or as_int for the same effect:

        $x = Math::BigFloat->new(123.45);
        $y = $x->as_number();                   # BigInt 123
        $y = $x->as_int();                      # ditto

This also works for other subclasses, like Math::String.

It is yet unlcear whether overloaded int() should return a scalar or a BigInt.

If you want a real Perl scalar, use numify():

        $y = $x->numify();                      # 123 as scalar

This is seldom necessary, though, because this is done automatically, like when you access an array:

        $z = $array[$x];                        # does work automatically
length

The following will probably not do what you expect:

        $c = Math::BigInt->new(123);
        print $c->length(),"\n";                # prints 30

It prints both the number of digits in the number and in the fraction part since print calls length() in list context. Use something like:

        print scalar $c->length(),"\n";         # prints 3
bdiv

The following will probably not do what you expect:

        print $c->bdiv(10000),"\n";

It prints both quotient and remainder since print calls bdiv() in list context. Also, bdiv() will modify $c, so be carefull. You probably want to use

        print $c / 10000,"\n";
        print scalar $c->bdiv(10000),"\n";  # or if you want to modify $c

instead.

The quotient is always the greatest integer less than or equal to the real-valued quotient of the two operands, and the remainder (when it is nonzero) always has the same sign as the second operand; so, for example,

          1 / 4  => ( 0, 1)
          1 / -4 => (-1,-3)
         -3 / 4  => (-1, 1)
         -3 / -4 => ( 0,-3)
        -11 / 2  => (-5,1)
         11 /-2  => (-5,-1)

As a consequence, the behavior of the operator % agrees with the behavior of Perl's built-in % operator (as documented in the perlop manpage), and the equation

        $x == ($x / $y) * $y + ($x % $y)

holds true for any $x and $y, which justifies calling the two return values of bdiv() the quotient and remainder. The only exception to this rule are when $y == 0 and $x is negative, then the remainder will also be negative. See below under "infinity handling" for the reasoning behing this.

Perl's 'use integer;' changes the behaviour of % and / for scalars, but will not change BigInt's way to do things. This is because under 'use integer' Perl will do what the underlying C thinks is right and this is different for each system. If you need BigInt's behaving exactly like Perl's 'use integer', bug the author to implement it ;)

infinity handling

Here are some examples that explain the reasons why certain results occur while handling infinity:

The following table shows the result of the division and the remainder, so that the equation above holds true. Some "ordinary" cases are strewn in to show more clearly the reasoning:

        A /  B  =   C,     R so that C *    B +    R =    A
     =========================================================
        5 /   8 =   0,     5         0 *    8 +    5 =    5
        0 /   8 =   0,     0         0 *    8 +    0 =    0
        0 / inf =   0,     0         0 *  inf +    0 =    0
        0 /-inf =   0,     0         0 * -inf +    0 =    0
        5 / inf =   0,     5         0 *  inf +    5 =    5
        5 /-inf =   0,     5         0 * -inf +    5 =    5
        -5/ inf =   0,    -5         0 *  inf +   -5 =   -5
        -5/-inf =   0,    -5         0 * -inf +   -5 =   -5
       inf/   5 =  inf,    0       inf *    5 +    0 =  inf
      -inf/   5 = -inf,    0      -inf *    5 +    0 = -inf
       inf/  -5 = -inf,    0      -inf *   -5 +    0 =  inf
      -inf/  -5 =  inf,    0       inf *   -5 +    0 = -inf
         5/   5 =    1,    0         1 *    5 +    0 =    5
        -5/  -5 =    1,    0         1 *   -5 +    0 =   -5
       inf/ inf =    1,    0         1 *  inf +    0 =  inf
      -inf/-inf =    1,    0         1 * -inf +    0 = -inf
       inf/-inf =   -1,    0        -1 * -inf +    0 =  inf
      -inf/ inf =   -1,    0         1 * -inf +    0 = -inf
         8/   0 =  inf,    8       inf *    0 +    8 =    8
       inf/   0 =  inf,  inf       inf *    0 +  inf =  inf
         0/   0 =  NaN

These cases below violate the "remainder has the sign of the second of the two arguments", since they wouldn't match up otherwise.

        A /  B  =   C,     R so that C *    B +    R =    A
     ========================================================
      -inf/   0 = -inf, -inf      -inf *    0 +  inf = -inf
        -8/   0 = -inf,   -8      -inf *    0 +    8 = -8
Modifying and =

Beware of:

        $x = Math::BigFloat->new(5);
        $y = $x;

It will not do what you think, e.g. making a copy of $x. Instead it just makes a second reference to the same object and stores it in $y. Thus anything that modifies $x (except overloaded operators) will modify $y, and vice versa. Or in other words, = is only safe if you modify your BigInts only via overloaded math. As soon as you use a method call it breaks:

        $x->bmul(2);
        print "$x, $y\n";       # prints '10, 10'

If you want a true copy of $x, use:

        $y = $x->copy();

You can also chain the calls like this, this will make first a copy and then multiply it by 2:

        $y = $x->copy()->bmul(2);

See also the documentation for overload.pm regarding =.

bpow

bpow() (and the rounding functions) now modifies the first argument and returns it, unlike the old code which left it alone and only returned the result. This is to be consistent with badd() etc. The first three will modify $x, the last one won't:

        print bpow($x,$i),"\n";         # modify $x
        print $x->bpow($i),"\n";        # ditto
        print $x **= $i,"\n";           # the same
        print $x ** $i,"\n";            # leave $x alone

The form $x **= $y is faster than $x = $x ** $y;, though.

Overloading -$x

The following:

        $x = -$x;

is slower than

        $x->bneg();

since overload calls sub($x,0,1); instead of neg($x). The first variant needs to preserve $x since it does not know that it later will get overwritten. This makes a copy of $x and takes O(N), but $x->bneg() is O(1).

Mixing different object types

In Perl you will get a floating point value if you do one of the following:

        $float = 5.0 + 2;
        $float = 2 + 5.0;
        $float = 5 / 2;

With overloaded math, only the first two variants will result in a BigFloat:

        use Math::BigInt;
        use Math::BigFloat;

        $mbf = Math::BigFloat->new(5);
        $mbi2 = Math::BigInteger->new(5);
        $mbi = Math::BigInteger->new(2);

                                        # what actually gets called:
                                                $float = $mbf + $mbi;           # $mbf->badd()
                                                $float = $mbf / $mbi;           # $mbf->bdiv()
                                                $integer = $mbi + $mbf;         # $mbi->badd()
                                                $integer = $mbi2 / $mbi;        # $mbi2->bdiv()
                                                $integer = $mbi2 / $mbf;        # $mbi2->bdiv()

This is because math with overloaded operators follows the first (dominating) operand, and the operation of that is called and returns thus the result. So, Math::BigInt::bdiv() will always return a Math::BigInt, regardless whether the result should be a Math::BigFloat or the second operant is one.

To get a Math::BigFloat you either need to call the operation manually, make sure the operands are already of the proper type or casted to that type via Math::BigFloat->new(): $float = Math::BigFloat->new($mbi2) / $mbi; # = 2.5

Beware of simple "casting" the entire expression, this would only convert the already computed result:

        $float = Math::BigFloat->new($mbi2 / $mbi);     # = 2.0 thus wrong!

Beware also of the order of more complicated expressions like:

        $integer = ($mbi2 + $mbi) / $mbf;               # int / float => int
        $integer = $mbi2 / Math::BigFloat->new($mbi);   # ditto

If in doubt, break the expression into simpler terms, or cast all operands to the desired resulting type.

Scalar values are a bit different, since:
$float = 2 + $mbf;
$float = $mbf + 2;

will both result in the proper type due to the way the overloaded math works.

This section also applies to other overloaded math packages, like Math::String.

One solution to you problem might be autoupgrading|upgrading. See the pragmas the bignum manpage, the bigint manpage and the bigrat manpage for an easy way to do this.

bsqrt()

bsqrt() works only good if the result is a big integer, e.g. the square root of 144 is 12, but from 12 the square root is 3, regardless of rounding mode. The reason is that the result is always truncated to an integer.

If you want a better approximation of the square root, then use:

        $x = Math::BigFloat->new(12);
        Math::BigFloat->precision(0);
        Math::BigFloat->round_mode('even');
        print $x->copy->bsqrt(),"\n";           # 4

        Math::BigFloat->precision(2);
        print $x->bsqrt(),"\n";                 # 3.46
        print $x->bsqrt(3),"\n";                # 3.464
brsft()

For negative numbers in base see also brsft.

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the Math::BigFloat manpage, the Math::BigRat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

The pragmas the bignum manpage, the bigint manpage and the bigrat manpage also might be of interest because they solve the autoupgrading/downgrading issue, at least partly.

The package at http://search.cpan.org/search contains more documentation including a full version history, testcases, empty subclass files and benchmarks.

AUTHORS

Original code by Mark Biggar, overloaded interface by Ilya Zakharevich. Completely rewritten by Tels http://bloodgate.com in late 2000, 2001 - 2004 and still at it in 2005.

Many people contributed in one or more ways to the final beast, see the file CREDITS for an (uncomplete) list. If you miss your name, please drop me a mail. Thank you!


Math::BigInt::Calc - Pure Perl module to support Math::BigInt

  • STORAGE
  • METHODS
  • WRAP YOUR OWN
  • LICENSE
  • AUTHORS
  • SEE ALSO

NAME

Math::BigInt::Calc - Pure Perl module to support Math::BigInt

SYNOPSIS

Provides support for big integer calculations. Not intended to be used by other modules. Other modules which sport the same functions can also be used to support Math::BigInt, like Math::BigInt::GMP or Math::BigInt::Pari.

DESCRIPTION

In order to allow for multiple big integer libraries, Math::BigInt was rewritten to use library modules for core math routines. Any module which follows the same API as this can be used instead by using the following:

        use Math::BigInt lib => 'libname';

'libname' is either the long name ('Math::BigInt::Pari'), or only the short version like 'Pari'.

STORAGE

METHODS

The following functions MUST be defined in order to support the use by Math::BigInt v1.70 or later:

        api_version()   return API version, minimum 1 for v1.70
        _new(string)    return ref to new object from ref to decimal string
        _zero()         return a new object with value 0
        _one()          return a new object with value 1
        _two()          return a new object with value 2
        _ten()          return a new object with value 10
        _str(obj)       return ref to a string representing the object
        _num(obj)       returns a Perl integer/floating point number
                        NOTE: because of Perl numeric notation defaults,
                        the _num'ified obj may lose accuracy due to
                        machine-dependend floating point size limitations

        _add(obj,obj)   Simple addition of two objects
        _mul(obj,obj)   Multiplication of two objects
        _div(obj,obj)   Division of the 1st object by the 2nd
                        In list context, returns (result,remainder).
                        NOTE: this is integer math, so no
                        fractional part will be returned.
                        The second operand will be not be 0, so no need to
                        check for that.
        _sub(obj,obj)   Simple subtraction of 1 object from another
                        a third, optional parameter indicates that the params
                        are swapped. In this case, the first param needs to
                        be preserved, while you can destroy the second.
                        sub (x,y,1) => return x - y and keep x intact!
        _dec(obj)       decrement object by one (input is garant. to be > 0)
        _inc(obj)       increment object by one
        _acmp(obj,obj)  <=> operator for objects (return -1, 0 or 1)
        _len(obj)       returns count of the decimal digits of the object
        _digit(obj,n)   returns the n'th decimal digit of object
        _is_one(obj)    return true if argument is 1
        _is_two(obj)    return true if argument is 2
        _is_ten(obj)    return true if argument is 10
        _is_zero(obj)   return true if argument is 0
        _is_even(obj)   return true if argument is even (0,2,4,6..)
        _is_odd(obj)    return true if argument is odd (1,3,5,7..)
        _copy           return a ref to a true copy of the object
        _check(obj)     check whether internal representation is still intact
                        return 0 for ok, otherwise error message as string
        _from_hex(str)  return ref to new object from ref to hexadecimal string
        _from_bin(str)  return ref to new object from ref to binary string

        _as_hex(str)    return string containing the value as
                        unsigned hex string, with the '0x' prepended.
                        Leading zeros must be stripped.
        _as_bin(str)    Like as_hex, only as binary string containing only
                        zeros and ones. Leading zeros must be stripped and a
                        '0b' must be prepended.

        _rsft(obj,N,B)  shift object in base B by N 'digits' right
        _lsft(obj,N,B)  shift object in base B by N 'digits' left

        _xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
                        Note: XOR, AND and OR pad with zeros if size mismatches
        _and(obj1,obj2) AND (bit-wise) object 1 with object 2
        _or(obj1,obj2)  OR (bit-wise) object 1 with object 2
        _mod(obj,obj)   Return remainder of div of the 1st by the 2nd object
        _sqrt(obj)      return the square root of object (truncated to int)
        _root(obj)      return the n'th (n >= 3) root of obj (truncated to int)
        _fac(obj)       return factorial of object 1 (1*2*3*4..)
        _pow(obj,obj)   return object 1 to the power of object 2
                        return undef for NaN
        _zeros(obj)     return number of trailing decimal zeros
        _modinv         return inverse modulus
        _modpow         return modulus of power ($x ** $y) % $z
        _log_int(X,N)   calculate integer log() of X in base N
                        X >= 0, N >= 0 (return undef for NaN)
                        returns (RESULT, EXACT) where EXACT is:
                         1     : result is exactly RESULT
                         0     : result was truncated to RESULT
                         undef : unknown whether result is exactly RESULT
        _gcd(obj,obj)   return Greatest Common Divisor of two objects

The following functions are optional, and can be defined if the underlying lib has a fast way to do them. If undefined, Math::BigInt will use pure Perl (hence slow) fallback routines to emulate these:

        _signed_or
        _signed_and
        _signed_xor

Input strings come in as unsigned but with prefix (i.e. as '123', '0xabc' or '0b1101').

So the library needs only to deal with unsigned big integers. Testing of input parameter validity is done by the caller, so you need not worry about underflow (f.i. in _sub(), _dec()) nor about division by zero or similar cases.

The first parameter can be modified, that includes the possibility that you return a reference to a completely different object instead. Although keeping the reference and just changing it's contents is prefered over creating and returning a different reference.

Return values are always references to objects, strings, or true/false for comparisation routines.

WRAP YOUR OWN

If you want to port your own favourite c-lib for big numbers to the Math::BigInt interface, you can take any of the already existing modules as a rough guideline. You should really wrap up the latest BigInt and BigFloat testsuites with your module, and replace in them any of the following:

        use Math::BigInt;

by this:

        use Math::BigInt lib => 'yourlib';

This way you ensure that your library really works 100% within Math::BigInt.

LICENSE This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Original math code by Mark Biggar, rewritten by Tels http://bloodgate.com/ in late 2000. Seperated from BigInt and shaped API with the help of John Peacock.

Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2005.

SEE ALSO

the Math::BigInt manpage, the Math::BigFloat manpage, the Math::BigInt::BitVect manpage, the Math::BigInt::GMP manpage, the Math::BigInt::FastCalc manpage and the Math::BigInt::Pari manpage.


Math::BigInt::CalcEmu - Emulate low-level math with BigInt code

  • METHODS
    • __emu_bxor
    • __emu_band
    • __emu_bior
  • LICENSE
  • AUTHORS
  • SEE ALSO

NAME

Math::BigInt::CalcEmu - Emulate low-level math with BigInt code

SYNOPSIS

        use Math::BigInt::CalcEmu;

DESCRIPTION

Contains routines that emulate low-level math functions in BigInt, e.g. optional routines the low-level math package does not provide on it's own.

Will be loaded on demand and called automatically by BigInt.

Stuff here is really low-priority to optimize, since it is far better to implement the operation in the low-level math libary directly, possible even using a call to the native lib.

METHODS

__emu_bxor

__emu_band

__emu_bior

LICENSE

This program is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.

AUTHORS

(c) Tels http://bloodgate.com 2003, 2004 - based on BigInt code by Tels from 2001-2003.

SEE ALSO

the Math::BigInt manpage, the Math::BigFloat manpage, the Math::BigInt::BitVect manpage, the Math::BigInt::GMP manpage and the Math::BigInt::Pari manpage.


Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more speed

  • STORAGE
  • METHODS
  • LICENSE
  • AUTHORS
  • SEE ALSO

NAME

Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more speed

SYNOPSIS

Provides support for big integer calculations. Not intended to be used by other modules. Other modules which sport the same functions can also be used to support Math::BigInt, like the Math::BigInt::GMP manpage or the Math::BigInt::Pari manpage.

DESCRIPTION

In order to allow for multiple big integer libraries, Math::BigInt was rewritten to use library modules for core math routines. Any module which follows the same API as this can be used instead by using the following:

        use Math::BigInt lib => 'libname';

'libname' is either the long name ('Math::BigInt::Pari'), or only the short version like 'Pari'. To use this library:

        use Math::BigInt lib => 'FastCalc';

Note that from the Math::BigInt manpage v1.76 onwards, FastCalc will be loaded automatically, if possible.

STORAGE

FastCalc works exactly like Calc, in stores the numbers in decimal form, chopped into parts.

METHODS

The following functions are now implemented in FastCalc.xs:

        _is_odd         _is_even        _is_one         _is_zero
        _is_two         _is_ten
        _zero           _one            _two            _ten
        _acmp           _len            _num
        _inc            _dec
        __strip_zeros   _copy

LICENSE

This program is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.

AUTHORS

Original math code by Mark Biggar, rewritten by Tels http://bloodgate.com/ in late 2000. Seperated from BigInt and shaped API with the help of John Peacock. Fixed, sped-up and enhanced by Tels http://bloodgate.com 2001-2003. Further streamlining (api_version 1 etc) by Tels 2004-2005.

SEE ALSO

the Math::BigInt manpage, the Math::BigFloat manpage, the Math::BigInt::BitVect manpage, the Math::BigInt::GMP manpage, the Math::BigInt::FastCalc manpage and the Math::BigInt::Pari manpage.


Math::BigRat - Arbitrary big rational numbers

    • MATH LIBRARY
  • METHODS
    • new()
    • numerator()
    • denominator()
    • parts()
    • as_int()
    • as_hex()
    • as_bin()
    • bfac()
    • blog()
    • bround()/round()/bfround()
    • bmod()
    • is_one()
    • is_zero()
    • is_pos()
    • is_neg()
    • is_int()
    • is_odd()
    • is_even()
    • bceil()
    • bfloor()
    • bsqrt()
    • config
  • BUGS
  • LICENSE
  • SEE ALSO
  • AUTHORS

NAME

Math::BigRat - Arbitrary big rational numbers

SYNOPSIS

        use Math::BigRat;

        my $x = Math::BigRat->new('3/7'); $x += '5/9';

        print $x->bstr(),"\n";
        print $x ** 2,"\n";

        my $y = Math::BigRat->new('inf');
        print "$y ", ($y->is_inf ? 'is' : 'is not') , " infinity\n";

        my $z = Math::BigRat->new(144); $z->bsqrt();

DESCRIPTION

Math::BigRat complements Math::BigInt and Math::BigFloat by providing support for arbitrary big rational numbers.

MATH LIBRARY

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use Math::BigRat lib => 'Calc';

You can change this by using:

        use Math::BigRat lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use Math::BigRat lib => 'Foo,Math::BigInt::Bar';

Calc.pm uses as internal format an array of elements of some decimal base (usually 1e7, but this might be different for some systems) with the least significant digit first, while BitVect.pm uses a bit vector of base 2, most significant bit first. Other modules might use even different means of representing the numbers. See the respective module documentation for further details.

Currently the following replacement libraries exist, search for them at CPAN:

        Math::BigInt::BitVect
        Math::BigInt::GMP
        Math::BigInt::Pari
        Math::BigInt::FastCalc

METHODS

Any methods not listed here are dervied from Math::BigFloat (or Math::BigInt), so make sure you check these two modules for further information.

new()

        $x = Math::BigRat->new('1/3');

Create a new Math::BigRat object. Input can come in various forms:

        $x = Math::BigRat->new(123);                            # scalars
        $x = Math::BigRat->new('inf');                          # infinity
        $x = Math::BigRat->new('123.3');                        # float
        $x = Math::BigRat->new('1/3');                          # simple string
        $x = Math::BigRat->new('1 / 3');                        # spaced
        $x = Math::BigRat->new('1 / 0.1');                      # w/ floats
        $x = Math::BigRat->new(Math::BigInt->new(3));           # BigInt
        $x = Math::BigRat->new(Math::BigFloat->new('3.1'));     # BigFloat
        $x = Math::BigRat->new(Math::BigInt::Lite->new('2'));   # BigLite

        # You can also give D and N as different objects:
        $x = Math::BigRat->new(
                Math::BigInt->new(-123),
                Math::BigInt->new(7),
                );                      # => -123/7

numerator()

        $n = $x->numerator();

Returns a copy of the numerator (the part above the line) as signed BigInt.

denominator()

        $d = $x->denominator();

Returns a copy of the denominator (the part under the line) as positive BigInt.

parts()

        ($n,$d) = $x->parts();

Return a list consisting of (signed) numerator and (unsigned) denominator as BigInts.

as_int()

        $x = Math::BigRat->new('13/7');
        print $x->as_int(),"\n";                # '1'

Returns a copy of the object as BigInt, truncated to an integer.

as_number() is an alias for as_int().

as_hex()

        $x = Math::BigRat->new('13');
        print $x->as_hex(),"\n";                # '0xd'

Returns the BigRat as hexadecimal string. Works only for integers.

as_bin()

        $x = Math::BigRat->new('13');
        print $x->as_bin(),"\n";                # '0x1101'

Returns the BigRat as binary string. Works only for integers.

bfac()

        $x->bfac();

Calculates the factorial of $x. For instance:

        print Math::BigRat->new('3/1')->bfac(),"\n";    # 1*2*3
        print Math::BigRat->new('5/1')->bfac(),"\n";    # 1*2*3*4*5

Works currently only for integers.

blog()

Is not yet implemented.

bround()/round()/bfround()

Are not yet implemented.

bmod()

        use Math::BigRat;
        my $x = Math::BigRat->new('7/4');
        my $y = Math::BigRat->new('4/3');
        print $x->bmod($y);

Set $x to the remainder of the division of $x by $y.

is_one()

        print "$x is 1\n" if $x->is_one();

Return true if $x is exactly one, otherwise false.

is_zero()

        print "$x is 0\n" if $x->is_zero();

Return true if $x is exactly zero, otherwise false.

is_pos()

        print "$x is >= 0\n" if $x->is_positive();

Return true if $x is positive (greater than or equal to zero), otherwise false. Please note that '+inf' is also positive, while 'NaN' and '-inf' aren't.

is_positive() is an alias for is_pos().

is_neg()

        print "$x is < 0\n" if $x->is_negative();

Return true if $x is negative (smaller than zero), otherwise false. Please note that '-inf' is also negative, while 'NaN' and '+inf' aren't.

is_negative() is an alias for is_neg().

is_int()

        print "$x is an integer\n" if $x->is_int();

Return true if $x has a denominator of 1 (e.g. no fraction parts), otherwise false. Please note that '-inf', 'inf' and 'NaN' aren't integer.

is_odd()

        print "$x is odd\n" if $x->is_odd();

Return true if $x is odd, otherwise false.

is_even()

        print "$x is even\n" if $x->is_even();

Return true if $x is even, otherwise false.

bceil()

        $x->bceil();

Set $x to the next bigger integer value (e.g. truncate the number to integer and then increment it by one).

bfloor()

        $x->bfloor();

Truncate $x to an integer value.

bsqrt()

        $x->bsqrt();

Calculate the square root of $x.

config

        use Data::Dumper;

        print Dumper ( Math::BigRat->config() );
        print Math::BigRat->config()->{lib},"\n";

Returns a hash containing the configuration, e.g. the version number, lib loaded etc. The following hash keys are currently filled in with the appropriate information.

        key             RO/RW   Description
                                Example
        ============================================================
        lib             RO      Name of the Math library
                                Math::BigInt::Calc
        lib_version     RO      Version of 'lib'
                                0.30
        class           RO      The class of config you just called
                                Math::BigRat
        version         RO      version number of the class you used
                                0.10
        upgrade         RW      To which class numbers are upgraded
                                undef
        downgrade       RW      To which class numbers are downgraded
                                undef
        precision       RW      Global precision
                                undef
        accuracy        RW      Global accuracy
                                undef
        round_mode      RW      Global round mode
                                even
        div_scale       RW      Fallback acccuracy for div
                                40
        trap_nan        RW      Trap creation of NaN (undef = no)
                                undef
        trap_inf        RW      Trap creation of +inf/-inf (undef = no)
                                undef

By passing a reference to a hash you may set the configuration values. This works only for values that a marked with a RW above, anything else is read-only.

BUGS

Some things are not yet implemented, or only implemented half-way:

inf handling (partial)
NaN handling (partial)
rounding (not implemented except for bceil/bfloor)
$x ** $y where $y is not an integer
bmod(), blog(), bmodinv() and bmodpow() (partial)

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the Math::BigFloat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

See http://search.cpan.org/search for a way to use Math::BigRat.

The package at http://search.cpan.org/search may contain more documentation and examples as well as testcases.

AUTHORS

(C) by Tels http://bloodgate.com/ 2001 - 2005.


Math::Complex - complex numbers and associated mathematical functions

  • OPERATIONS
  • CREATION
  • DISPLAYING
    • CHANGED IN PERL 5.6
  • USAGE
  • ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO
  • ERRORS DUE TO INDIGESTIBLE ARGUMENTS
  • BUGS
  • AUTHORS

NAME

Math::Complex - complex numbers and associated mathematical functions

SYNOPSIS

        use Math::Complex;

        $z = Math::Complex->make(5, 6);
        $t = 4 - 3*i + $z;
        $j = cplxe(1, 2*pi/3);

DESCRIPTION

This package lets you create and manipulate complex numbers. By default, Perl limits itself to real numbers, but an extra use statement brings full complex support, along with a full set of mathematical functions typically associated with and/or extended to complex numbers.

If you wonder what complex numbers are, they were invented to be able to solve the following equation:

        x*x = -1

and by definition, the solution is noted i (engineers use j instead since i usually denotes an intensity, but the name does not matter). The number i is a pure imaginary number.

The arithmetics with pure imaginary numbers works just like you would expect it with real numbers... you just have to remember that

        i*i = -1

so you have:

        5i + 7i = i * (5 + 7) = 12i
        4i - 3i = i * (4 - 3) = i
        4i * 2i = -8
        6i / 2i = 3
        1 / i = -i

Complex numbers are numbers that have both a real part and an imaginary part, and are usually noted:

        a + bi

where a is the real part and b is the imaginary part. The arithmetic with complex numbers is straightforward. You have to keep track of the real and the imaginary parts, but otherwise the rules used for real numbers just apply:

        (4 + 3i) + (5 - 2i) = (4 + 5) + i(3 - 2) = 9 + i
        (2 + i) * (4 - i) = 2*4 + 4i -2i -i*i = 8 + 2i + 1 = 9 + 2i

A graphical representation of complex numbers is possible in a plane (also called the complex plane, but it's really a 2D plane). The number

        z = a + bi

is the point whose coordinates are (a, b). Actually, it would be the vector originating from (0, 0) to (a, b). It follows that the addition of two complex numbers is a vectorial addition.

Since there is a bijection between a point in the 2D plane and a complex number (i.e. the mapping is unique and reciprocal), a complex number can also be uniquely identified with polar coordinates:

        [rho, theta]

where rho is the distance to the origin, and theta the angle between the vector and the x axis. There is a notation for this using the exponential form, which is:

        rho * exp(i * theta)

where i is the famous imaginary number introduced above. Conversion between this form and the cartesian form a + bi is immediate:

        a = rho * cos(theta)
        b = rho * sin(theta)

which is also expressed by this formula:

        z = rho * exp(i * theta) = rho * (cos theta + i * sin theta)

In other words, it's the projection of the vector onto the x and y axes. Mathematicians call rho the norm or modulus and theta the argument of the complex number. The norm of z will be noted abs(z).

The polar notation (also known as the trigonometric representation) is much more handy for performing multiplications and divisions of complex numbers, whilst the cartesian notation is better suited for additions and subtractions. Real numbers are on the x axis, and therefore theta is zero or pi.

All the common operations that can be performed on a real number have been defined to work on complex numbers as well, and are merely extensions of the operations defined on real numbers. This means they keep their natural meaning when there is no imaginary part, provided the number is within their definition set.

For instance, the sqrt routine which computes the square root of its argument is only defined for non-negative real numbers and yields a non-negative real number (it is an application from R+ to R+). If we allow it to return a complex number, then it can be extended to negative real numbers to become an application from R to C (the set of complex numbers):

        sqrt(x) = x >= 0 ? sqrt(x) : sqrt(-x)*i

It can also be extended to be an application from C to C, whilst its restriction to R behaves as defined above by using the following definition:

        sqrt(z = [r,t]) = sqrt(r) * exp(i * t/2)

Indeed, a negative real number can be noted [x,pi] (the modulus x is always non-negative, so [x,pi] is really -x, a negative number) and the above definition states that

        sqrt([x,pi]) = sqrt(x) * exp(i*pi/2) = [sqrt(x),pi/2] = sqrt(x)*i

which is exactly what we had defined for negative real numbers above. The sqrt returns only one of the solutions: if you want the both, use the root function.

All the common mathematical functions defined on real numbers that are extended to complex numbers share that same property of working as usual when the imaginary part is zero (otherwise, it would not be called an extension, would it?).

A new operation possible on a complex number that is the identity for real numbers is called the conjugate, and is noted with a horizontal bar above the number, or ~z here.

         z = a + bi
        ~z = a - bi

Simple... Now look:

        z * ~z = (a + bi) * (a - bi) = a*a + b*b

We saw that the norm of z was noted abs(z) and was defined as the distance to the origin, also known as:

        rho = abs(z) = sqrt(a*a + b*b)

so

        z * ~z = abs(z) ** 2

If z is a pure real number (i.e. b == 0), then the above yields:

        a * a = abs(a) ** 2

which is true (abs has the regular meaning for real number, i.e. stands for the absolute value). This example explains why the norm of z is noted abs(z): it extends the abs function to complex numbers, yet is the regular abs we know when the complex number actually has no imaginary part... This justifies a posteriori our use of the abs notation for the norm.

OPERATIONS

Given the following notations:

        z1 = a + bi = r1 * exp(i * t1)
        z2 = c + di = r2 * exp(i * t2)
        z = <any complex or real number>

the following (overloaded) operations are supported on complex numbers:

        z1 + z2 = (a + c) + i(b + d)
        z1 - z2 = (a - c) + i(b - d)
        z1 * z2 = (r1 * r2) * exp(i * (t1 + t2))
        z1 / z2 = (r1 / r2) * exp(i * (t1 - t2))
        z1 ** z2 = exp(z2 * log z1)
        ~z = a - bi
        abs(z) = r1 = sqrt(a*a + b*b)
        sqrt(z) = sqrt(r1) * exp(i * t/2)
        exp(z) = exp(a) * exp(i * b)
        log(z) = log(r1) + i*t
        sin(z) = 1/2i (exp(i * z1) - exp(-i * z))
        cos(z) = 1/2 (exp(i * z1) + exp(-i * z))
        atan2(y, x) = atan(y / x) # Minding the right quadrant, note the order.

The definition used for complex arguments of atan2() is

       -i log((x + iy)/sqrt(x*x+y*y))

The following extra operations are supported on both real and complex numbers:

        Re(z) = a
        Im(z) = b
        arg(z) = t
        abs(z) = r
        cbrt(z) = z ** (1/3)
        log10(z) = log(z) / log(10)
        logn(z, n) = log(z) / log(n)
        tan(z) = sin(z) / cos(z)
        csc(z) = 1 / sin(z)
        sec(z) = 1 / cos(z)
        cot(z) = 1 / tan(z)
        asin(z) = -i * log(i*z + sqrt(1-z*z))
        acos(z) = -i * log(z + i*sqrt(1-z*z))
        atan(z) = i/2 * log((i+z) / (i-z))
        acsc(z) = asin(1 / z)
        asec(z) = acos(1 / z)
        acot(z) = atan(1 / z) = -i/2 * log((i+z) / (z-i))
        sinh(z) = 1/2 (exp(z) - exp(-z))
        cosh(z) = 1/2 (exp(z) + exp(-z))
        tanh(z) = sinh(z) / cosh(z) = (exp(z) - exp(-z)) / (exp(z) + exp(-z))
        csch(z) = 1 / sinh(z)
        sech(z) = 1 / cosh(z)
        coth(z) = 1 / tanh(z)
        asinh(z) = log(z + sqrt(z*z+1))
        acosh(z) = log(z + sqrt(z*z-1))
        atanh(z) = 1/2 * log((1+z) / (1-z))
        acsch(z) = asinh(1 / z)
        asech(z) = acosh(1 / z)
        acoth(z) = atanh(1 / z) = 1/2 * log((1+z) / (z-1))

arg, abs, log, csc, cot, acsc, acot, csch, coth, acosech, acotanh, have aliases rho, theta, ln, cosec, cotan, acosec, acotan, cosech, cotanh, acosech, acotanh, respectively. Re, Im, arg, abs, rho, and theta can be used also as mutators. The cbrt returns only one of the solutions: if you want all three, use the root function.

The root function is available to compute all the n roots of some complex, where n is a strictly positive integer. There are exactly n such roots, returned as a list. Getting the number mathematicians call j such that:

        1 + j + j*j = 0;

is a simple matter of writing:

        $j = ((root(1, 3))[1];

The kth root for z = [r,t] is given by:

        (root(z, n))[k] = r**(1/n) * exp(i * (t + 2*k*pi)/n)

You can return the kth root directly by root(z, n, k), indexing starting from zero and ending at n - 1.

The spaceship comparison operator, <=>, is also defined. In order to ensure its restriction to real numbers is conform to what you would expect, the comparison is run on the real part of the complex number first, and imaginary parts are compared only when the real parts match.

CREATION

To create a complex number, use either:

        $z = Math::Complex->make(3, 4);
        $z = cplx(3, 4);

if you know the cartesian form of the number, or

        $z = 3 + 4*i;

if you like. To create a number using the polar form, use either:

        $z = Math::Complex->emake(5, pi/3);
        $x = cplxe(5, pi/3);

instead. The first argument is the modulus, the second is the angle (in radians, the full circle is 2*pi). (Mnemonic: e is used as a notation for complex numbers in the polar form).

It is possible to write:

        $x = cplxe(-3, pi/4);

but that will be silently converted into [3,-3pi/4], since the modulus must be non-negative (it represents the distance to the origin in the complex plane).

It is also possible to have a complex number as either argument of the make, emake, cplx, and cplxe: the appropriate component of the argument will be used.

        $z1 = cplx(-2,  1);
        $z2 = cplx($z1, 4);

The new, make, emake, cplx, and cplxe will also understand a single (string) argument of the forms

        2-3i
        -3i
        [2,3]
        [2,-3pi/4]
        [2]

in which case the appropriate cartesian and exponential components will be parsed from the string and used to create new complex numbers. The imaginary component and the theta, respectively, will default to zero.

The new, make, emake, cplx, and cplxe will also understand the case of no arguments: this means plain zero or (0, 0).

DISPLAYING

When printed, a complex number is usually shown under its cartesian style a+bi, but there are legitimate cases where the polar style [r,t] is more appropriate. The process of converting the complex number into a string that can be displayed is known as stringification.

By calling the class method Math::Complex::display_format and supplying either "polar" or "cartesian" as an argument, you override the default display style, which is "cartesian". Not supplying any argument returns the current settings.

This default can be overridden on a per-number basis by calling the display_format method instead. As before, not supplying any argument returns the current display style for this number. Otherwise whatever you specify will be the new display style for this particular number.

For instance:

        use Math::Complex;

        Math::Complex::display_format('polar');
        $j = (root(1, 3))[1];
        print "j = $j\n";               # Prints "j = [1,2pi/3]"
        $j->display_format('cartesian');
        print "j = $j\n";               # Prints "j = -0.5+0.866025403784439i"

The polar style attempts to emphasize arguments like k*pi/n (where n is a positive integer and k an integer within [-9, +9]), this is called polar pretty-printing.

For the reverse of stringifying, see the make and emake.

CHANGED IN PERL 5.6

The display_format class method and the corresponding display_format object method can now be called using a parameter hash instead of just a one parameter.

The old display format style, which can have values "cartesian" or "polar", can be changed using the "style" parameter.

        $j->display_format(style => "polar");

The one parameter calling convention also still works.

        $j->display_format("polar");

There are two new display parameters.

The first one is "format", which is a sprintf()-style format string to be used for both numeric parts of the complex number(s). The is somewhat system-dependent but most often it corresponds to "%.15g". You can revert to the default by setting the format to undef.

        # the $j from the above example

        $j->display_format('format' => '%.5f');
        print "j = $j\n";               # Prints "j = -0.50000+0.86603i"
        $j->display_format('format' => undef);
        print "j = $j\n";               # Prints "j = -0.5+0.86603i"

Notice that this affects also the return values of the display_format methods: in list context the whole parameter hash will be returned, as opposed to only the style parameter value. This is a potential incompatibility with earlier versions if you have been calling the display_format method in list context.

The second new display parameter is "polar_pretty_print", which can be set to true or false, the default being true. See the previous section for what this means.

USAGE

Thanks to overloading, the handling of arithmetics with complex numbers is simple and almost transparent.

Here are some examples:

        use Math::Complex;

        $j = cplxe(1, 2*pi/3);  # $j ** 3 == 1
        print "j = $j, j**3 = ", $j ** 3, "\n";
        print "1 + j + j**2 = ", 1 + $j + $j**2, "\n";

        $z = -16 + 0*i;                 # Force it to be a complex
        print "sqrt($z) = ", sqrt($z), "\n";

        $k = exp(i * 2*pi/3);
        print "$j - $k = ", $j - $k, "\n";

        $z->Re(3);                      # Re, Im, arg, abs,
        $j->arg(2);                     # (the last two aka rho, theta)
                                        # can be used also as mutators.

ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO

The division (/) and the following functions

        log     ln      log10   logn
        tan     sec     csc     cot
        atan    asec    acsc    acot
        tanh    sech    csch    coth
        atanh   asech   acsch   acoth

cannot be computed for all arguments because that would mean dividing by zero or taking logarithm of zero. These situations cause fatal runtime errors looking like this

        cot(0): Division by zero.
        (Because in the definition of cot(0), the divisor sin(0) is 0)
        Died at ...

or

        atanh(-1): Logarithm of zero.
        Died at...

For the csc, cot, asec, acsc, acot, csch, coth, asech, acsch, the argument cannot be 0 (zero). For the logarithmic functions and the atanh, acoth, the argument cannot be 1 (one). For the atanh, acoth, the argument cannot be -1 (minus one). For the atan, acot, the argument cannot be i (the imaginary unit). For the atan, acoth, the argument cannot be -i (the negative imaginary unit). For the tan, sec, tanh, the argument cannot be pi/2 + k * pi, where k is any integer. atan2(0, 0) is undefined, and if the complex arguments are used for atan2(), a division by zero will happen if z1**2+z2**2 == 0.

Note that because we are operating on approximations of real numbers, these errors can happen when merely `too close' to the singularities listed above.

ERRORS DUE TO INDIGESTIBLE ARGUMENTS

The make and emake accept both real and complex arguments. When they cannot recognize the arguments they will die with error messages like the following

    Math::Complex::make: Cannot take real part of ...
    Math::Complex::make: Cannot take real part of ...
    Math::Complex::emake: Cannot take rho of ...
    Math::Complex::emake: Cannot take theta of ...

BUGS

Saying use Math::Complex; exports many mathematical routines in the caller environment and even overrides some (sqrt, log, atan2). This is construed as a feature by the Authors, actually... ;-)

All routines expect to be given real or complex numbers. Don't attempt to use BigFloat, since Perl has currently no rule to disambiguate a '+' operation (for instance) between two overloaded entities.

In Cray UNICOS there is some strange numerical instability that results in root(), cos(), sin(), cosh(), sinh(), losing accuracy fast. Beware. The bug may be in UNICOS math libs, in UNICOS C compiler, in Math::Complex. Whatever it is, it does not manifest itself anywhere else where Perl runs.

AUTHORS

Daniel S. Lewart <d-lewart@uiuc.edu>

Original authors Raphael Manfredi <Raphael_Manfredi@pobox.com> and Jarkko Hietaniemi <jhi@iki.fi>


Math::Trig - trigonometric functions

  • TRIGONOMETRIC FUNCTIONS
    • ERRORS DUE TO DIVISION BY ZERO
    • SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
  • PLANE ANGLE CONVERSIONS
  • RADIAL COORDINATE CONVERSIONS
    • COORDINATE SYSTEMS
    • 3-D ANGLE CONVERSIONS
  • GREAT CIRCLE DISTANCES AND DIRECTIONS
  • EXAMPLES
    • CAVEAT FOR GREAT CIRCLE FORMULAS
  • BUGS
  • AUTHORS

NAME

Math::Trig - trigonometric functions

SYNOPSIS

        use Math::Trig;

        $x = tan(0.9);
        $y = acos(3.7);
        $z = asin(2.4);

        $halfpi = pi/2;

        $rad = deg2rad(120);

        # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
        use Math::Trig ':pi';

        # Import the conversions between cartesian/spherical/cylindrical.
        use Math::Trig ':radial';

        # Import the great circle formulas.
        use Math::Trig ':great_circle';

DESCRIPTION

Math::Trig defines many trigonometric functions not defined by the core Perl which defines only the sin() and cos(). The constant pi is also defined as are a few convenience functions for angle conversions, and great circle formulas for spherical movement.

TRIGONOMETRIC FUNCTIONS

The tangent

tan

The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot are aliases)

csc, cosec, sec, sec, cot, cotan

The arcus (also known as the inverse) functions of the sine, cosine, and tangent

asin, acos, atan

The principal value of the arc tangent of y/x

atan2(y, x)

The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc and acotan/acot are aliases)

acsc, acosec, asec, acot, acotan

The hyperbolic sine, cosine, and tangent

sinh, cosh, tanh

The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch and cotanh/coth are aliases)

csch, cosech, sech, coth, cotanh

The arcus (also known as the inverse) functions of the hyperbolic sine, cosine, and tangent

asinh, acosh, atanh

The arcus cofunctions of the hyperbolic sine, cosine, and tangent (acsch/acosech and acoth/acotanh are aliases)

acsch, acosech, asech, acoth, acotanh

The trigonometric constant pi is also defined.

$pi2 = 2 * pi;

ERRORS DUE TO DIVISION BY ZERO

The following functions

        acoth
        acsc
        acsch
        asec
        asech
        atanh
        cot
        coth
        csc
        csch
        sec
        sech
        tan
        tanh

cannot be computed for all arguments because that would mean dividing by zero or taking logarithm of zero. These situations cause fatal runtime errors looking like this

        cot(0): Division by zero.
        (Because in the definition of cot(0), the divisor sin(0) is 0)
        Died at ...

or

        atanh(-1): Logarithm of zero.
        Died at...

For the csc, cot, asec, acsc, acot, csch, coth, asech, acsch, the argument cannot be 0 (zero). For the atanh, acoth, the argument cannot be 1 (one). For the atanh, acoth, the argument cannot be -1 (minus one). For the tan, sec, tanh, sech, the argument cannot be pi/2 + k * pi, where k is any integer. atan2(0, 0) is undefined.

SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS

Please note that some of the trigonometric functions can break out from the real axis into the complex plane. For example asin(2) has no definition for plain real numbers but it has definition for complex numbers.

In Perl terms this means that supplying the usual Perl numbers (also known as scalars, please see the perldata manpage) as input for the trigonometric functions might produce as output results that no more are simple real numbers: instead they are complex numbers.

The Math::Trig handles this by using the Math::Complex package which knows how to handle complex numbers, please see the Math::Complex manpage for more information. In practice you need not to worry about getting complex numbers as results because the Math::Complex takes care of details like for example how to display complex numbers. For example:

        print asin(2), "\n";

should produce something like this (take or leave few last decimals):

        1.5707963267949-1.31695789692482i

That is, a complex number with the real part of approximately 1.571 and the imaginary part of approximately -1.317.

PLANE ANGLE CONVERSIONS

(Plane, 2-dimensional) angles may be converted with the following functions.

        $radians  = deg2rad($degrees);
        $radians  = grad2rad($gradians);

        $degrees  = rad2deg($radians);
        $degrees  = grad2deg($gradians);

        $gradians = deg2grad($degrees);
        $gradians = rad2grad($radians);

The full circle is 2 pi radians or 360 degrees or 400 gradians. The result is by default wrapped to be inside the [0, {2pi,360,400}[ circle. If you don't want this, supply a true second argument:

        $zillions_of_radians  = deg2rad($zillions_of_degrees, 1);
        $negative_degrees     = rad2deg($negative_radians, 1);

You can also do the wrapping explicitly by rad2rad(), deg2deg(), and grad2grad().

RADIAL COORDINATE CONVERSIONS

Radial coordinate systems are the spherical and the cylindrical systems, explained shortly in more detail.

You can import radial coordinate conversion functions by using the :radial tag:

    use Math::Trig ':radial';

    ($rho, $theta, $z)     = cartesian_to_cylindrical($x, $y, $z);
    ($rho, $theta, $phi)   = cartesian_to_spherical($x, $y, $z);
    ($x, $y, $z)           = cylindrical_to_cartesian($rho, $theta, $z);
    ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
    ($x, $y, $z)           = spherical_to_cartesian($rho, $theta, $phi);
    ($rho_c, $theta, $z)   = spherical_to_cylindrical($rho_s, $theta, $phi);

All angles are in radians.

COORDINATE SYSTEMS

Cartesian coordinates are the usual rectangular (x, y, z)-coordinates.

Spherical coordinates, (rho, theta, pi), are three-dimensional coordinates which define a point in three-dimensional space. They are based on a sphere surface. The radius of the sphere is rho, also known as the radial coordinate. The angle in the xy-plane (around the z-axis) is theta, also known as the azimuthal coordinate. The angle from the z-axis is phi, also known as the polar coordinate. The North Pole is therefore 0, 0, rho, and the Gulf of Guinea (think of the missing big chunk of Africa) 0, pi/2, rho. In geographical terms phi is latitude (northward positive, southward negative) and theta is longitude (eastward positive, westward negative).

BEWARE: some texts define theta and phi the other way round, some texts define the phi to start from the horizontal plane, some texts use r in place of rho.

Cylindrical coordinates, (rho, theta, z), are three-dimensional coordinates which define a point in three-dimensional space. They are based on a cylinder surface. The radius of the cylinder is rho, also known as the radial coordinate. The angle in the xy-plane (around the z-axis) is theta, also known as the azimuthal coordinate. The third coordinate is the z, pointing up from the theta-plane.

3-D ANGLE CONVERSIONS

Conversions to and from spherical and cylindrical coordinates are available. Please notice that the conversions are not necessarily reversible because of the equalities like pi angles being equal to -pi angles.

cartesian_to_cylindrical
        ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
cartesian_to_spherical
        ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
cylindrical_to_cartesian
        ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
cylindrical_to_spherical
        ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);

Notice that when $z is not 0 $rho_s is not equal to $rho_c.

spherical_to_cartesian
        ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
spherical_to_cylindrical
        ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);

Notice that when $z is not 0 $rho_c is not equal to $rho_s.

GREAT CIRCLE DISTANCES AND DIRECTIONS

You can compute spherical distances, called great circle distances, by importing the great_circle_distance() function:

  use Math::Trig 'great_circle_distance';

  $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);

The great circle distance is the shortest distance between two points on a sphere. The distance is in $rho units. The $rho is optional, it defaults to 1 (the unit sphere), therefore the distance defaults to radians.

If you think geographically the theta are longitudes: zero at the Greenwhich meridian, eastward positive, westward negative--and the phi are latitudes: zero at the North Pole, northward positive, southward negative. NOTE: this formula thinks in mathematics, not geographically: the phi zero is at the North Pole, not at the Equator on the west coast of Africa (Bay of Guinea). You need to subtract your geographical coordinates from pi/2 (also known as 90 degrees).

  $distance = great_circle_distance($lon0, pi/2 - $lat0,
                                    $lon1, pi/2 - $lat1, $rho);

The direction you must follow the great circle (also known as bearing) can be computed by the great_circle_direction() function:

  use Math::Trig 'great_circle_direction';

  $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);

(Alias 'great_circle_bearing' is also available.) The result is in radians, zero indicating straight north, pi or -pi straight south, pi/2 straight west, and -pi/2 straight east.

You can inversely compute the destination if you know the starting point, direction, and distance:

  use Math::Trig 'great_circle_destination';

  # thetad and phid are the destination coordinates,
  # dird is the final direction at the destination.

  ($thetad, $phid, $dird) =
    great_circle_destination($theta, $phi, $direction, $distance);

or the midpoint if you know the end points:

  use Math::Trig 'great_circle_midpoint';

  ($thetam, $phim) =
    great_circle_midpoint($theta0, $phi0, $theta1, $phi1);

The great_circle_midpoint() is just a special case of

  use Math::Trig 'great_circle_waypoint';

  ($thetai, $phii) =
    great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);

Where the $way is a value from zero ($theta0, $phi0) to one ($theta1, $phi1). Note that antipodal points (where their distance is pi radians) do not have waypoints between them (they would have an an "equator" between them), and therefore undef is returned for antipodal points. If the points are the same and the distance therefore zero and all waypoints therefore identical, the first point (either point) is returned.

The thetas, phis, direction, and distance in the above are all in radians.

You can import all the great circle formulas by

  use Math::Trig ':great_circle';

Notice that the resulting directions might be somewhat surprising if you are looking at a flat worldmap: in such map projections the great circles quite often do not look like the shortest routes-- but for example the shortest possible routes from Europe or North America to Asia do often cross the polar regions.

EXAMPLES

To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N 139.8E) in kilometers:

        use Math::Trig qw(great_circle_distance deg2rad);

        # Notice the 90 - latitude: phi zero is at the North Pole.
        sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
        my @L = NESW( -0.5, 51.3);
        my @T = NESW(139.8, 35.7);
        my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.

The direction you would have to go from London to Tokyo (in radians, straight north being zero, straight east being pi/2).

        use Math::Trig qw(great_circle_direction);

        my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.

The midpoint between London and Tokyo being

        use Math::Trig qw(great_circle_midpoint);

        my @M = great_circle_midpoint(@L, @T);

or about 68.11N 24.74E, in the Finnish Lapland.

CAVEAT FOR GREAT CIRCLE FORMULAS

The answers may be off by few percentages because of the irregular (slightly aspherical) form of the Earth. The errors are at worst about 0.55%, but generally below 0.3%.

BUGS

Saying use Math::Trig; exports many mathematical routines in the caller environment and even overrides some (sin, cos). This is construed as a feature by the Authors, actually... ;-)

The code is not optimized for speed, especially because we use Math::Complex and thus go quite near complex numbers while doing the computations even when the arguments are not. This, however, cannot be completely avoided if we want things like asin(2) to give an answer instead of giving a fatal runtime error.

Do not attempt navigation using these formulas.

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi> and Raphael Manfredi <Raphael_Manfredi@pobox.com>.


Memoize - Make functions faster by trading space for time

  • DETAILS
  • OPTIONS
    • INSTALL
    • NORMALIZER
    • SCALAR_CACHE, LIST_CACHE
  • OTHER FACILITIES
    • unmemoize
    • flush_cache
  • CAVEATS
  • PERSISTENT CACHE SUPPORT
  • EXPIRATION SUPPORT
  • BUGS
  • MAILING LIST
  • AUTHOR
  • COPYRIGHT AND LICENSE
  • THANK YOU

NAME

Memoize - Make functions faster by trading space for time

SYNOPSIS

        # This is the documentation for Memoize 1.01
        use Memoize;
        memoize('slow_function');
        slow_function(arguments);    # Is faster than it was before

This is normally all you need to know. However, many options are available:

        memoize(function, options...);

Options include:

        NORMALIZER => function
        INSTALL => new_name
        SCALAR_CACHE => 'MEMORY'
        SCALAR_CACHE => ['HASH', \%cache_hash ]
        SCALAR_CACHE => 'FAULT'
        SCALAR_CACHE => 'MERGE'
        LIST_CACHE => 'MEMORY'
        LIST_CACHE => ['HASH', \%cache_hash ]
        LIST_CACHE => 'FAULT'
        LIST_CACHE => 'MERGE'

DESCRIPTION

`Memoizing' a function makes it faster by trading space for time. It does this by caching the return values of the function in a table. If you call the function again with the same arguments, memoize jumps in and gives you the value out of the table, instead of letting the function compute the value all over again.

Here is an extreme example. Consider the Fibonacci sequence, defined by the following function:

        # Compute Fibonacci numbers
        sub fib {
          my $n = shift;
          return $n if $n < 2;
          fib($n-1) + fib($n-2);
        }

This function is very slow. Why? To compute fib(14), it first wants to compute fib(13) and fib(12), and add the results. But to compute fib(13), it first has to compute fib(12) and fib(11), and then it comes back and computes fib(12) all over again even though the answer is the same. And both of the times that it wants to compute fib(12), it has to compute fib(11) from scratch, and then it has to do it again each time it wants to compute fib(13). This function does so much recomputing of old results that it takes a really long time to run---fib(14) makes 1,200 extra recursive calls to itself, to compute and recompute things that it already computed.

This function is a good candidate for memoization. If you memoize the `fib' function above, it will compute fib(14) exactly once, the first time it needs to, and then save the result in a table. Then if you ask for fib(14) again, it gives you the result out of the table. While computing fib(14), instead of computing fib(12) twice, it does it once; the second time it needs the value it gets it from the table. It doesn't compute fib(11) four times; it computes it once, getting it from the table the next three times. Instead of making 1,200 recursive calls to `fib', it makes 15. This makes the function about 150 times faster.

You could do the memoization yourself, by rewriting the function, like this:

        # Compute Fibonacci numbers, memoized version
        { my @fib;
          sub fib {
            my $n = shift;
            return $fib[$n] if defined $fib[$n];
            return $fib[$n] = $n if $n < 2;
            $fib[$n] = fib($n-1) + fib($n-2);
          }
        }

Or you could use this module, like this:

        use Memoize;
        memoize('fib');

        # Rest of the fib function just like the original version.

This makes it easy to turn memoizing on and off.

Here's an even simpler example: I wrote a simple ray tracer; the program would look in a certain direction, figure out what it was looking at, and then convert the `color' value (typically a string like `red') of that object to a red, green, and blue pixel value, like this:

    for ($direction = 0; $direction < 300; $direction++) {
      # Figure out which object is in direction $direction
      $color = $object->{color};
      ($r, $g, $b) = @{&ColorToRGB($color)};
      ...
    }

Since there are relatively few objects in a picture, there are only a few colors, which get looked up over and over again. Memoizing ColorToRGB sped up the program by several percent.

DETAILS

This module exports exactly one function, memoize. The rest of the functions in this package are None of Your Business.

You should say

        memoize(function)

where function is the name of the function you want to memoize, or a reference to it. memoize returns a reference to the new, memoized version of the function, or undef on a non-fatal error. At present, there are no non-fatal errors, but there might be some in the future.

If function was the name of a function, then memoize hides the old version and installs the new memoized version under the old name, so that &function(...) actually invokes the memoized version.

OPTIONS

There are some optional options you can pass to memoize to change the way it behaves a little. To supply options, invoke memoize like this:

        memoize(function, NORMALIZER => function,
                          INSTALL => newname,
                          SCALAR_CACHE => option,
                          LIST_CACHE => option
                         );

Each of these options is optional; you can include some, all, or none of them.

INSTALL

If you supply a function name with INSTALL, memoize will install the new, memoized version of the function under the name you give. For example,

        memoize('fib', INSTALL => 'fastfib')

installs the memoized version of fib as fastfib; without the INSTALL option it would have replaced the old fib with the memoized version.

To prevent memoize from installing the memoized version anywhere, use INSTALL => undef.

NORMALIZER

Suppose your function looks like this:

        # Typical call: f('aha!', A => 11, B => 12);
        sub f {
          my $a = shift;
          my %hash = @_;
          $hash{B} ||= 2;  # B defaults to 2
          $hash{C} ||= 7;  # C defaults to 7

          # Do something with $a, %hash
        }

Now, the following calls to your function are all completely equivalent:

        f(OUCH);
        f(OUCH, B => 2);
        f(OUCH, C => 7);
        f(OUCH, B => 2, C => 7);
        f(OUCH, C => 7, B => 2);
        (etc.)

However, unless you tell Memoize that these calls are equivalent, it will not know that, and it will compute the values for these invocations of your function separately, and store them separately.

To prevent this, supply a NORMALIZER function that turns the program arguments into a string in a way that equivalent arguments turn into the same string. A NORMALIZER function for f above might look like this:

        sub normalize_f {
          my $a = shift;
          my %hash = @_;
          $hash{B} ||= 2;
          $hash{C} ||= 7;

          join(',', $a, map ($_ => $hash{$_}) sort keys %hash);
                  }

Each of the argument lists above comes out of the normalize_f function looking exactly the same, like this:

        OUCH,B,2,C,7

You would tell Memoize to use this normalizer this way:

        memoize('f', NORMALIZER => 'normalize_f');

memoize knows that if the normalized version of the arguments is the same for two argument lists, then it can safely look up the value that it computed for one argument list and return it as the result of calling the function with the other argument list, even if the argument lists look different.

The default normalizer just concatenates the arguments with character 28 in between. (In ASCII, this is called FS or control-\.) This always works correctly for functions with only one string argument, and also when the arguments never contain character 28. However, it can confuse certain argument lists:

        normalizer("a\034", "b")
        normalizer("a", "\034b")
        normalizer("a\034\034b")

for example.

Since hash keys are strings, the default normalizer will not distinguish between undef and the empty string. It also won't work when the function's arguments are references. For example, consider a function g which gets two arguments: A number, and a reference to an array of numbers:

        g(13, [1,2,3,4,5,6,7]);

The default normalizer will turn this into something like "13\034ARRAY(0x436c1f)". That would be all right, except that a subsequent array of numbers might be stored at a different location even though it contains the same data. If this happens, Memoize will think that the arguments are different, even though they are equivalent. In this case, a normalizer like this is appropriate:

        sub normalize { join ' ', $_[0], @{$_[1]} }

For the example above, this produces the key "13 1 2 3 4 5 6 7".

Another use for normalizers is when the function depends on data other than those in its arguments. Suppose you have a function which returns a value which depends on the current hour of the day:

        sub on_duty {
          my ($problem_type) = @_;
          my $hour = (localtime)[2];
          open my $fh, "$DIR/$problem_type" or die...;
          my $line;
          while ($hour-- > 0)
            $line = <$fh>;
          }
          return $line;
        }

At 10:23, this function generates the 10th line of a data file; at 3:45 PM it generates the 15th line instead. By default, Memoize will only see the $problem_type argument. To fix this, include the current hour in the normalizer:

        sub normalize { join ' ', (localtime)[2], @_ }

The calling context of the function (scalar or list context) is propagated to the normalizer. This means that if the memoized function will treat its arguments differently in list context than it would in scalar context, you can have the normalizer function select its behavior based on the results of wantarray. Even if called in a list context, a normalizer should still return a single string.

SCALAR_CACHE, LIST_CACHE

Normally, Memoize caches your function's return values into an ordinary Perl hash variable. However, you might like to have the values cached on the disk, so that they persist from one run of your program to the next, or you might like to associate some other interesting semantics with the cached values.

There's a slight complication under the hood of Memoize: There are actually two caches, one for scalar values and one for list values. When your function is called in scalar context, its return value is cached in one hash, and when your function is called in list context, its value is cached in the other hash. You can control the caching behavior of both contexts independently with these options.

The argument to LIST_CACHE or SCALAR_CACHE must either be one of the following four strings:

        MEMORY
        FAULT
        MERGE
        HASH

or else it must be a reference to a list whose first element is one of these four strings, such as [HASH, arguments...].

MEMORY

MEMORY means that return values from the function will be cached in an ordinary Perl hash variable. The hash variable will not persist after the program exits. This is the default.

HASH

HASH allows you to specify that a particular hash that you supply will be used as the cache. You can tie this hash beforehand to give it any behavior you want.

A tied hash can have any semantics at all. It is typically tied to an on-disk database, so that cached values are stored in the database and retrieved from it again when needed, and the disk file typically persists after your program has exited. See perltie for more complete details about tie.

A typical example is:

        use DB_File;
        tie my %cache => 'DB_File', $filename, O_RDWR|O_CREAT, 0666;
        memoize 'function', SCALAR_CACHE => [HASH => \%cache];

This has the effect of storing the cache in a DB_File database whose name is in $filename. The cache will persist after the program has exited. Next time the program runs, it will find the cache already populated from the previous run of the program. Or you can forcibly populate the cache by constructing a batch program that runs in the background and populates the cache file. Then when you come to run your real program the memoized function will be fast because all its results have been precomputed.

TIE

This option is no longer supported. It is still documented only to aid in the debugging of old programs that use it. Old programs should be converted to use the HASH option instead.

        memoize ... [TIE, PACKAGE, ARGS...]

is merely a shortcut for

        require PACKAGE;
        { my %cache;
          tie %cache, PACKAGE, ARGS...;
        }
        memoize ... [HASH => \%cache];
FAULT

FAULT means that you never expect to call the function in scalar (or list) context, and that if Memoize detects such a call, it should abort the program. The error message is one of

        `foo' function called in forbidden list context at line ...
        `foo' function called in forbidden scalar context at line ...
MERGE

MERGE normally means the function does not distinguish between list and sclar context, and that return values in both contexts should be stored together. LIST_CACHE => MERGE means that list context return values should be stored in the same hash that is used for scalar context returns, and SCALAR_CACHE => MERGE means the same, mutatis mutandis. It is an error to specify MERGE for both, but it probably does something useful.

Consider this function:

        sub pi { 3; }

Normally, the following code will result in two calls to pi:

    $x = pi();
    ($y) = pi();
    $z = pi();

The first call caches the value 3 in the scalar cache; the second caches the list (3) in the list cache. The third call doesn't call the real pi function; it gets the value from the scalar cache.

Obviously, the second call to pi is a waste of time, and storing its return value is a waste of space. Specifying LIST_CACHE => MERGE will make memoize use the same cache for scalar and list context return values, so that the second call uses the scalar cache that was populated by the first call. pi ends up being called only once, and both subsequent calls return 3 from the cache, regardless of the calling context.

Another use for MERGE is when you want both kinds of return values stored in the same disk file; this saves you from having to deal with two disk files instead of one. You can use a normalizer function to keep the two sets of return values separate. For example:

        tie my %cache => 'MLDBM', 'DB_File', $filename, ...;

        memoize 'myfunc',
          NORMALIZER => 'n',
          SCALAR_CACHE => [HASH => \%cache],
          LIST_CACHE => MERGE,
        ;

        sub n {
          my $context = wantarray() ? 'L' : 'S';
          # ... now compute the hash key from the arguments ...
          $hashkey = "$context:$hashkey";
        }

This normalizer function will store scalar context return values in the disk file under keys that begin with S:, and list context return values under keys that begin with L:.

OTHER FACILITIES

unmemoize

There's an unmemoize function that you can import if you want to. Why would you want to? Here's an example: Suppose you have your cache tied to a DBM file, and you want to make sure that the cache is written out to disk if someone interrupts the program. If the program exits normally, this will happen anyway, but if someone types control-C or something then the program will terminate immediately without synchronizing the database. So what you can do instead is

    $SIG{INT} = sub { unmemoize 'function' };

unmemoize accepts a reference to, or the name of a previously memoized function, and undoes whatever it did to provide the memoized version in the first place, including making the name refer to the unmemoized version if appropriate. It returns a reference to the unmemoized version of the function.

If you ask it to unmemoize a function that was never memoized, it croaks.

flush_cache

flush_cache(function) will flush out the caches, discarding all the cached data. The argument may be a function name or a reference to a function. For finer control over when data is discarded or expired, see the documentation for Memoize::Expire, included in this package.

Note that if the cache is a tied hash, flush_cache will attempt to invoke the CLEAR method on the hash. If there is no CLEAR method, this will cause a run-time error.

An alternative approach to cache flushing is to use the HASH option (see above) to request that Memoize use a particular hash variable as its cache. Then you can examine or modify the hash at any time in any way you desire. You may flush the cache by using %hash = ().

CAVEATS

Memoization is not a cure-all:

  • Do not memoize a function whose behavior depends on program state other than its own arguments, such as global variables, the time of day, or file input. These functions will not produce correct results when memoized. For a particularly easy example:

            sub f {
          time;
        }

    This function takes no arguments, and as far as Memoize is concerned, it always returns the same result. Memoize is wrong, of course, and the memoized version of this function will call time once to get the current time, and it will return that same time every time you call it after that.

  • Do not memoize a function with side effects.

            sub f {
          my ($a, $b) = @_;
          my $s = $a + $b;
          print "$a + $b = $s.\n";
        }

    This function accepts two arguments, adds them, and prints their sum. Its return value is the numuber of characters it printed, but you probably didn't care about that. But Memoize doesn't understand that. If you memoize this function, you will get the result you expect the first time you ask it to print the sum of 2 and 3, but subsequent calls will return 1 (the return value of print) without actually printing anything.

  • Do not memoize a function that returns a data structure that is modified by its caller.

    Consider these functions: getusers returns a list of users somehow, and then main throws away the first user on the list and prints the rest:

            sub main {
          my $userlist = getusers();
          shift @$userlist;
          foreach $u (@$userlist) {
            print "User $u\n";
          }
        }

            sub getusers {
          my @users;
          # Do something to get a list of users;
          \@users;  # Return reference to list.
        }

    If you memoize getusers here, it will work right exactly once. The reference to the users list will be stored in the memo table. main will discard the first element from the referenced list. The next time you invoke main, Memoize will not call getusers; it will just return the same reference to the same list it got last time. But this time the list has already had its head removed; main will erroneously remove another element from it. The list will get shorter and shorter every time you call main.

    Similarly, this:

            $u1 = getusers();
        $u2 = getusers();
        pop @$u1;

    will modify $u2 as well as $u1, because both variables are references to the same array. Had getusers not been memoized, $u1 and $u2 would have referred to different arrays.

  • Do not memoize a very simple function.

    Recently someone mentioned to me that the Memoize module made his program run slower instead of faster. It turned out that he was memoizing the following function:

        sub square {
      $_[0] * $_[0];
    }

    I pointed out that Memoize uses a hash, and that looking up a number in the hash is necessarily going to take a lot longer than a single multiplication. There really is no way to speed up the square function.

    Memoization is not magical.

PERSISTENT CACHE SUPPORT

You can tie the cache tables to any sort of tied hash that you want to, as long as it supports TIEHASH, FETCH, STORE, and EXISTS. For example,

        tie my %cache => 'GDBM_File', $filename, O_RDWR|O_CREAT, 0666;
        memoize 'function', SCALAR_CACHE => [HASH => \%cache];

works just fine. For some storage methods, you need a little glue.

SDBM_File doesn't supply an EXISTS method, so included in this package is a glue module called Memoize::SDBM_File which does provide one. Use this instead of plain SDBM_File to store your cache table on disk in an SDBM_File database:

        tie my %cache => 'Memoize::SDBM_File', $filename, O_RDWR|O_CREAT, 0666;
        memoize 'function', SCALAR_CACHE => [HASH => \%cache];

NDBM_File has the same problem and the same solution. (Use Memoize::NDBM_File instead of plain NDBM_File.)

Storable isn't a tied hash class at all. You can use it to store a hash to disk and retrieve it again, but you can't modify the hash while it's on the disk. So if you want to store your cache table in a Storable database, use Memoize::Storable, which puts a hashlike front-end onto Storable. The hash table is actually kept in memory, and is loaded from your Storable file at the time you memoize the function, and stored back at the time you unmemoize the function (or when your program exits):

        tie my %cache => 'Memoize::Storable', $filename;
        memoize 'function', SCALAR_CACHE => [HASH => \%cache];

        tie my %cache => 'Memoize::Storable', $filename, 'nstore';
        memoize 'function', SCALAR_CACHE => [HASH => \%cache];

Include the `nstore' option to have the Storable database written in `network order'. (See the Storable manpage for more details about this.)

The flush_cache() function will raise a run-time error unless the tied package provides a CLEAR method.

EXPIRATION SUPPORT

See Memoize::Expire, which is a plug-in module that adds expiration functionality to Memoize. If you don't like the kinds of policies that Memoize::Expire implements, it is easy to write your own plug-in module to implement whatever policy you desire. Memoize comes with several examples. An expiration manager that implements a LRU policy is available on CPAN as Memoize::ExpireLRU.

BUGS

The test suite is much better, but always needs improvement.

There is some problem with the way goto &f works under threaded Perl, perhaps because of the lexical scoping of @_. This is a bug in Perl, and until it is resolved, memoized functions will see a slightly different caller() and will perform a little more slowly on threaded perls than unthreaded perls.

Some versions of DB_File won't let you store data under a key of length 0. That means that if you have a function f which you memoized and the cache is in a DB_File database, then the value of f() (f called with no arguments) will not be memoized. If this is a big problem, you can supply a normalizer function that prepends "x" to every key.

MAILING LIST

To join a very low-traffic mailing list for announcements about Memoize, send an empty note to mjd-perl-memoize-request@plover.com.

AUTHOR

Mark-Jason Dominus (mjd-perl-memoize+@plover.com), Plover Systems co.

See the Memoize.pm Page at http://www.plover.com/~mjd/perl/Memoize/ for news and upgrades. Near this page, at http://www.plover.com/~mjd/perl/MiniMemoize/ there is an article about memoization and about the internals of Memoize that appeared in The Perl Journal, issue #13. (This article is also included in the Memoize distribution as `article.html'.)

My upcoming book will discuss memoization (and many other fascinating topics) in tremendous detail. It will be published by Morgan Kaufmann in 2002, possibly under the title Perl Advanced Techniques Handbook. It will also be available on-line for free. For more information, visit http://perl.plover.com/book/ .

To join a mailing list for announcements about Memoize, send an empty message to mjd-perl-memoize-request@plover.com. This mailing list is for announcements only and has extremely low traffic---about two messages per year.

COPYRIGHT AND LICENSE

Copyright 1998, 1999, 2000, 2001 by Mark Jason Dominus

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

THANK YOU

Many thanks to Jonathan Roy for bug reports and suggestions, to Michael Schwern for other bug reports and patches, to Mike Cariaso for helping me to figure out the Right Thing to Do About Expiration, to Joshua Gerth, Joshua Chamas, Jonathan Roy (again), Mark D. Anderson, and Andrew Johnson for more suggestions about expiration, to Brent Powers for the Memoize::ExpireLRU module, to Ariel Scolnicov for delightful messages about the Fibonacci function, to Dion Almaer for thought-provoking suggestions about the default normalizer, to Walt Mankowski and Kurt Starsinic for much help investigating problems under threaded Perl, to Alex Dudkevich for reporting the bug in prototyped functions and for checking my patch, to Tony Bass for many helpful suggestions, to Jonathan Roy (again) for finding a use for unmemoize(), to Philippe Verdret for enlightening discussion of Hook::PrePostCall, to Nat Torkington for advice I ignored, to Chris Nandor for portability advice, to Randal Schwartz for suggesting the 'flush_cache function, and to Jenda Krynicky for being a light in the world.

Special thanks to Jarkko Hietaniemi, the 5.8.0 pumpking, for including this module in the core and for his patient and helpful guidance during the integration process.


Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for Storable use

NAME

Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for Storable use

DESCRIPTION

See the Memoize manpage.


Memoize::Expire - Plug-in module for automatic expiration of memoized values

  • INTERFACE
  • ALTERNATIVES
  • CAVEATS
  • AUTHOR
  • SEE ALSO

NAME

Memoize::Expire - Plug-in module for automatic expiration of memoized values

SYNOPSIS

  use Memoize;
  use Memoize::Expire;
  tie my %cache => 'Memoize::Expire',
                     LIFETIME => $lifetime,    # In seconds
                     NUM_USES => $n_uses;

  memoize 'function', SCALAR_CACHE => [HASH => \%cache ];

DESCRIPTION

Memoize::Expire is a plug-in module for Memoize. It allows the cached values for memoized functions to expire automatically. This manual assumes you are already familiar with the Memoize module. If not, you should study that manual carefully first, paying particular attention to the HASH feature.

Memoize::Expire is a layer of software that you can insert in between Memoize itself and whatever underlying package implements the cache. The layer presents a hash variable whose values expire whenever they get too old, have been used too often, or both. You tell Memoize to use this forgetful hash as its cache instead of the default, which is an ordinary hash.

To specify a real-time timeout, supply the LIFETIME option with a numeric value. Cached data will expire after this many seconds, and will be looked up afresh when it expires. When a data item is looked up afresh, its lifetime is reset.

If you specify NUM_USES with an argument of n, then each cached data item will be discarded and looked up afresh after the nth time you access it. When a data item is looked up afresh, its number of uses is reset.

If you specify both arguments, data will be discarded from the cache when either expiration condition holds.

Memoize::Expire uses a real hash internally to store the cached data. You can use the HASH option to Memoize::Expire to supply a tied hash in place of the ordinary hash that Memoize::Expire will normally use. You can use this feature to add Memoize::Expire as a layer in between a persistent disk hash and Memoize. If you do this, you get a persistent disk cache whose entries expire automatically. For example:

  #   Memoize
  #      |
  #   Memoize::Expire  enforces data expiration policy
  #      |
  #   DB_File  implements persistence of data in a disk file
  #      |
  #   Disk file

  use Memoize;
  use Memoize::Expire;
  use DB_File;

  # Set up persistence
  tie my %disk_cache => 'DB_File', $filename, O_CREAT|O_RDWR, 0666];

  # Set up expiration policy, supplying persistent hash as a target
  tie my %cache => 'Memoize::Expire',
                     LIFETIME => $lifetime,    # In seconds
                     NUM_USES => $n_uses,
                     HASH => \%disk_cache;

  # Set up memoization, supplying expiring persistent hash for cache
  memoize 'function', SCALAR_CACHE => [ HASH => \%cache ];

INTERFACE

There is nothing special about Memoize::Expire. It is just an example. If you don't like the policy that it implements, you are free to write your own expiration policy module that implements whatever policy you desire. Here is how to do that. Let us suppose that your module will be named MyExpirePolicy.

Short summary: You need to create a package that defines four methods:

TIEHASH

Construct and return cache object.

EXISTS

Given a function argument, is the corresponding function value in the cache, and if so, is it fresh enough to use?

FETCH

Given a function argument, look up the corresponding function value in the cache and return it.

STORE

Given a function argument and the corresponding function value, store them into the cache.

CLEAR

(Optional.) Flush the cache completely.

The user who wants the memoization cache to be expired according to your policy will say so by writing

  tie my %cache => 'MyExpirePolicy', args...;
  memoize 'function', SCALAR_CACHE => [HASH => \%cache];

This will invoke MyExpirePolicy->TIEHASH(args). MyExpirePolicy::TIEHASH should do whatever is appropriate to set up the cache, and it should return the cache object to the caller.

For example, MyExpirePolicy::TIEHASH might create an object that contains a regular Perl hash (which it will to store the cached values) and some extra information about the arguments and how old the data is and things like that. Let us call this object `C'.

When Memoize needs to check to see if an entry is in the cache already, it will invoke C->EXISTS(key). key is the normalized function argument. MyExpirePolicy::EXISTS should return 0 if the key is not in the cache, or if it has expired, and 1 if an unexpired value is in the cache. It should not return undef, because there is a bug in some versions of Perl that will cause a spurious FETCH if the EXISTS method returns undef.

If your EXISTS function returns true, Memoize will try to fetch the cached value by invoking C->FETCH(key). MyExpirePolicy::FETCH should return the cached value. Otherwise, Memoize will call the memoized function to compute the appropriate value, and will store it into the cache by calling C->STORE(key, value).

Here is a very brief example of a policy module that expires each cache item after ten seconds.

        package Memoize::TenSecondExpire;

        sub TIEHASH {
          my ($package, %args) = @_;
          my $cache = $args{HASH} || {};
          bless $cache => $package;
        }

        sub EXISTS {
          my ($cache, $key) = @_;
          if (exists $cache->{$key} &&
              $cache->{$key}{EXPIRE_TIME} > time) {
            return 1
          } else {
            return 0;  # Do NOT return `undef' here.
          }
        }

        sub FETCH {
          my ($cache, $key) = @_;
          return $cache->{$key}{VALUE};
        }

        sub STORE {
          my ($cache, $key, $newvalue) = @_;
          $cache->{$key}{VALUE} = $newvalue;
          $cache->{$key}{EXPIRE_TIME} = time + 10;
        }

To use this expiration policy, the user would say

        use Memoize;
        tie my %cache10sec => 'Memoize::TenSecondExpire';
        memoize 'function', SCALAR_CACHE => [HASH => \%cache10sec];

Memoize would then call function whenever a cached value was entirely absent or was older than ten seconds.

You should always support a HASH argument to TIEHASH that ties the underlying cache so that the user can specify that the cache is also persistent or that it has some other interesting semantics. The example above demonstrates how to do this, as does Memoize::Expire.

ALTERNATIVES

Brent Powers has a Memoize::ExpireLRU module that was designed to work with Memoize and provides expiration of least-recently-used data. The cache is held at a fixed number of entries, and when new data comes in, the least-recently used data is expired. See http://search.cpan.org/search.

Joshua Chamas's Tie::Cache module may be useful as an expiration manager. (If you try this, let me know how it works out.)

If you develop any useful expiration managers that you think should be distributed with Memoize, please let me know.

CAVEATS

This module is experimental, and may contain bugs. Please report bugs to the address below.

Number-of-uses is stored as a 16-bit unsigned integer, so can't exceed 65535.

Because of clock granularity, expiration times may occur up to one second sooner than you expect. For example, suppose you store a value with a lifetime of ten seconds, and you store it at 12:00:00.998 on a certain day. Memoize will look at the clock and see 12:00:00. Then 9.01 seconds later, at 12:00:10.008 you try to read it back. Memoize will look at the clock and see 12:00:10 and conclude that the value has expired. This will probably not occur if you have Time::HiRes installed.

AUTHOR

Mark-Jason Dominus (mjd-perl-memoize+@plover.com)

Mike Cariaso provided valuable insight into the best way to solve this problem.

SEE ALSO

perl(1)

The Memoize man page.

http://www.plover.com/~mjd/perl/Memoize/ (for news and updates)

I maintain a mailing list on which I occasionally announce new versions of Memoize. The list is for announcements only, not discussion. To join, send an empty message to mjd-perl-memoize-request@Plover.com.


Memoize::ExpireFile - test for Memoize expiration semantics

NAME

Memoize::ExpireFile - test for Memoize expiration semantics

DESCRIPTION

See the Memoize::Expire manpage.


Memoize::ExpireTest - test for Memoize expiration semantics

NAME

Memoize::ExpireTest - test for Memoize expiration semantics

DESCRIPTION

This module is just for testing expiration semantics. It's not a very good example of how to write an expiration module.

If you are looking for an example, I recommend that you look at the simple example in the Memoize::Expire documentation, or at the code for Memoize::Expire itself.

If you have questions, I will be happy to answer them if you send them to mjd-perl-memoize+@plover.com.


Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for Storable use

NAME

Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for Storable use

DESCRIPTION

See the Memoize manpage.


Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for Storable use

NAME

Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for Storable use

DESCRIPTION

See the Memoize manpage.


Memoize::Storable - store Memoized data in Storable database

NAME

Memoize::Storable - store Memoized data in Storable database

DESCRIPTION

See the Memoize manpage.


ModPerl::BuildMM -- A "subclass" of ModPerl::MM used for building mod_perl 2.0

  • OVERRIDEN METHODS
    • ModPerl::BuildMM::MY::constants
    • ModPerl::BuildMM::MY::top_targets
    • ModPerl::BuildMM::MY::postamble
    • ModPerl::BuildMM::MY::post_initialize
    • ModPerl::BuildMM::MY::libscan

NAME

ModPerl::BuildMM -- A "subclass" of ModPerl::MM used for building mod_perl 2.0

SYNOPSIS

  use ModPerl::BuildMM;

  # ModPerl::BuildMM takes care of doing all the dirty job of overriding
  ModPerl::BuildMM::WriteMakefile(...);

  # if there is a need to extend the methods
  sub MY::postamble {
      my $self = shift;

      my $string = $self->ModPerl::BuildMM::MY::postamble;

      $string .= "\nmydist : manifest tardist\n";

      return $string;
  }

DESCRIPTION

ModPerl::BuildMM is a "subclass" of ModPerl::MM used for building mod_perl 2.0. Refer to ModPerl::MM|docs::2.0::api::ModPerl::MM manpage.

OVERRIDEN METHODS

ModPerl::BuildMM overrides the following methods:

ModPerl::BuildMM::MY::constants

ModPerl::BuildMM::MY::top_targets

ModPerl::BuildMM::MY::postamble

ModPerl::BuildMM::MY::post_initialize

ModPerl::BuildMM::MY::libscan


ModPerl::CScan - scan C language files for easily recognized constructs.

NAME

ModPerl::CScan - scan C language files for easily recognized constructs.

SYNOPSIS

DESCRIPTION

See the C::Scan manpage. This package is just a fork to fix certain things that didn't work in the original C::Scan, which is not maintained any longer. These fixes required to make it work with the Apache 2 source code.


$class\::Const - Perl Interface for $class Constants

  • CONSTANTS
    • :$group
  • NAME
  • SYNOPSIS
  • DESCRIPTION
  • AUTHOR

SYNOPSIS

CONSTANTS

EOF

        my $groups = $data{$class};
        for my $group (sort keys %$groups) {
            print $fh <<"EOF";

:$group

  use $class\::Const -compile qw(:$group);

The :$group group is for XXX constants.

EOF

            for my $const (sort @{ $groups->{$group} }) {
                print $fh "=head3 C<$class\::$const>\n\n\n";
            }
                    }

        print $fh "=cut\n";
            }
        }

sub generate_constants_lookup_doc { my ($data) = @_;

    while (my ($class, $groups) = each %$Apache2::ConstantsTable) {
        my $constants = [map { @$_ } values %$groups];

        constants_lookup_code_doc($constants, $class, $data);
            }
        }

sub generate_constants_group_lookup_doc { my ($data) = @_;

    while (my ($class, $groups) = each %$Apache2::ConstantsTable) {
        constants_group_lookup_code_doc($class, $groups, $data);
    }
    }

sub constants_group_lookup_code_doc {
    my ($class, $groups, $data) = @_;
    my @tags;
    my @code;

    while (my ($group, $constants) = each %$groups) {
        $data->{$class}{$group} = [
            map {
                my @ifdef = constants_ifdef($_);
                s/^($constant_prefixes)_?//o;
                $seen_const{$class}{$_}++;
                $_;
            } @$constants
        ];
    }
    }

sub constants_lookup_code_doc { my ($constants, $class, $data) = @_;

    my (%switch, %alias);

    %alias = %shortcuts;

    my $postfix = lc $class;
    my $package = $class . '::';
    my $package_len = length $package;

    my $func = canon_func(qw(constants lookup), $postfix);

    for (@$constants) {
        if (s/^($constant_prefixes)(_)?//o) {
            $alias{$_} = join $2 || "", $1, $_;
        }
        else {
            $alias{$_} ||= $_;
        }
        next unless /^([A-Z])/;
        push @{ $switch{$1} }, $_;
    }

    for my $key (sort keys %switch) {
        my $names = $switch{$key};
        for my $name (@$names) {
            my @ifdef = constants_ifdef($alias{$name});
            push @{ $data->{$class}{other} }, $name
                unless $seen_const{$class}{$name}
        }
    }
    }

sub generate_exports {
    my ($self, $c_fh) = @_;
    require ModPerl::WrapXS;
    ModPerl::WrapXS->generate_exports($c_fh);
}

# src/modules/perl/*.c files needed to build APR/APR::* outside # of mod_perl.so sub src_apr_ext { return map { "modperl_$_" } (qw(error bucket), map { "common_$_" } qw(util log)); }

1; __END__

NAME

ModPerl::Code - Generate mod_perl glue code

SYNOPSIS

  use ModPerl::Code ();
  my $code = ModPerl::Code->new;
  $code->generate;

DESCRIPTION

This module provides functionality for generating mod_perl glue code. Reason this code is generated rather than written by hand include:

consistency
thin and clean glue code
enable/disable features (without #ifdefs)
adapt to changes in Apache
experiment with different approaches to gluing

AUTHOR

Doug MacEachern


ModPerl::Config - Functions to retrieve mod_perl specific env information.

NAME

ModPerl::Config - Functions to retrieve mod_perl specific env information.

DESCRIPTION


ModPerl::Const -- ModPerl Constants

  • Synopsis
  • Description
  • Constants
    • Other Constants
      • ModPerl::EXIT
  • See Also
  • Copyright
  • Authors

NAME

ModPerl::Const -- ModPerl Constants

Synopsis

  # make the constants available but don't import them
  use ModPerl::Const -compile => qw(constant names ...);

  # w/o the => syntax sugar
  use ModPerl::Const ("-compile", qw(constant names ...));

  # compile and import the constants
  use ModPerl::Const qw(constant names ...);

Description

This package contains constants specific to mod_perl features.

Refer to the Apache2::Const description section|docs::2.0::api::Apache2::Const/Description for more information.

Constants

Other Constants

ModPerl::EXIT

since: 2.0.00

See ModPerl::Util::exit|docs::2.0::api::ModPerl::Util/C_exit_.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


ModPerl::Global -- Perl API for manipulating special Perl lists

  • Synopsis
  • Description
  • API
    • special_list_call
    • special_list_clear
    • special_list_register
  • See Also
  • Copyright
  • Authors

NAME

ModPerl::Global -- Perl API for manipulating special Perl lists

Synopsis

  use ModPerl::Global ();
  my $package = 'MyApache2::Package';

  # make the END blocks of this package special
  ModPerl::Global::special_list_register(END => $package);

  # Execute all encoutered END blocks from this package now
  ModPerl::Global::special_list_call(    END => $package);

  # delete the list of END blocks
  ModPerl::Global::special_list_clear(   END => $package);

Description

ModPerl::Global provides an API to manipulate special perl lists. At the moment only the END blocks list is supported.

This API allows you to change the normal Perl behavior, and execute special lists when you need to.

For example ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker uses it to run END blocks in the scripts at the end of each request.

Before loading a module containing package $package, you need to register it, so the special blocks will be intercepted by mod_perl and not given to Perl. special_list_register|/C_special_list_register_ does that. Later on when you want to execute the special blocks, special_list_call|/C_special_list_call_ should be called. Unless you want to call the list more than once, clear the list with special_list_clear|/C_special_list_clear_.

API

ModPerl::Global provides the following methods:

special_list_call

Call the special list

  $ok = special_list_call($key => $package);
arg1: $key ( string )

The name of the special list. At the moment only 'END' is supported.

arg2: $package ( string )

what package to special list is for

ret: $ok ( boolean )

true value if $key is known, false otherwise.

since: 2.0.00

special_list_clear

Clear the special list

  $ok = special_list_clear($key => $package);
arg1: $key ( string )

The name of the special list. At the moment only 'END' is supported.

arg2: $package ( string )

what package to special list is for

ret: $ok ( boolean )

true value if $key is known, false otherwise.

since: 2.0.00

special_list_register

Register the special list

  $ok = special_list_call($key => $package);
arg1: $key ( string )

The name of the special list. At the moment only 'END' is supported.

arg2: $package ( string )

what package to special list is for

ret: $ok ( boolean )

true value if $key is known, false otherwise.

since: 2.0.00

Notice that you need to register the package before it is loaded. If you register it after, Perl has already compiled the END blocks and there are no longer under your control.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


ModPerl::MM -- A "subclass" of ExtUtils::MakeMaker for mod_perl 2.0

  • Synopsis
  • Description
  • MY:: Default Methods
    • ModPerl::MM::MY::post_initialize
  • WriteMakefile() Default Arguments
    • CCFLAGS
    • LIBS
    • INC
    • OPTIMIZE
    • LDDLFLAGS
    • TYPEMAPS
    • dynamic_lib
      • OTHERLDFLAGS
    • macro
      • MOD_INSTALL
  • Public API
    • WriteMakefile()
    • get_def_opt()

NAME

ModPerl::MM -- A "subclass" of ExtUtils::MakeMaker for mod_perl 2.0

Synopsis

  use ModPerl::MM;

  # ModPerl::MM takes care of doing all the dirty job of overriding
  ModPerl::MM::WriteMakefile(...);

  # if there is a need to extend the default methods
  sub MY::constants {
      my $self = shift;
      $self->ModPerl::MM::MY::constants;
      # do something else;
  }

  # or prevent overriding completely
  sub MY::constants { shift->MM::constants(@_); }";

  # override the default value of WriteMakefile's attribute
  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => $extra_inc,
      ...
  );

  # extend the default value of WriteMakefile's attribute
  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt('INC'),
      ...
  );

Description

ModPerl::MM is a "subclass" of ExtUtils::MakeMaker for mod_perl 2.0, to a degree of sub-classability of ExtUtils::MakeMaker.

When ModPerl::MM::WriteMakefile() is used instead of ExtUtils::MakeMaker::WriteMakefile(), ModPerl::MM overrides several ExtUtils::MakeMaker methods behind the scenes and supplies default WriteMakefile() arguments adjusted for mod_perl 2.0 build. It's written in such a way so that normally 3rd party module developers for mod_perl 2.0, don't need to mess with Makefile.PL at all.

MY:: Default Methods

ModPerl::MM overrides method foo as long as Makefile.PL hasn't already specified a method MY::foo. If the latter happens, ModPerl::MM will DWIM and do nothing.

In case the functionality of ModPerl::MM methods needs to be extended, rather than completely overriden, the ModPerl::MM methods can be called internally. For example if you need to modify constants in addition to the modifications applied by ModPerl::MM::MY::constants, call the ModPerl::MM::MY::constants method (notice that it resides in the package ModPerl::MM::MY and not ModPerl::MM), then do your extra manipulations on constants:

  # if there is a need to extend the methods
  sub MY::constants {
      my $self = shift;
      $self->ModPerl::MM::MY::constants;
      # do something else;
  }

In certain cases a developers may want to prevent from ModPerl::MM to override certain methods. In that case an explicit override in Makefile.PL will do the job. For example if you don't want the constants() method to be overriden by ModPerl::MM, add to your Makefile.PL:

  sub MY::constants { shift->MM::constants(@_); }";

ModPerl::MM overrides the following methods:

ModPerl::MM::MY::post_initialize

This method is deprecated.

WriteMakefile() Default Arguments

ModPerl::MM::WriteMakefile supplies default arguments such as INC and TYPEMAPS unless they weren't passed to ModPerl::MM::WriteMakefile from Makefile.PL.

If the default values aren't satisfying these should be overriden in Makefile.PL. For example to supply an empty INC, explicitly set the argument in Makefile.PL.

  ModPerl::MM::WriteMakefile(
      ...
      INC => '',
      ...
  );

If instead of fully overriding the default arguments, you want to extend or modify them, they can be retrieved using the ModPerl::MM::get_def_opt() function. The following example appends an extra value to the default INC attribute:

  my $extra_inc = "/foo/include";
  ModPerl::MM::WriteMakefile(
      ...
      INC => join " ", $extra_inc, ModPerl::MM::get_def_opt('INC'),
      ...
  );

ModPerl::MM supplies default values for the following ModPerl::MM::WriteMakefile attributes:

CCFLAGS

LIBS

INC

OPTIMIZE

LDDLFLAGS

TYPEMAPS

dynamic_lib

OTHERLDFLAGS

  dynamic_lib => { OTHERLDFLAGS => ... }

macro

MOD_INSTALL

  macro => { MOD_INSTALL => ... }

makes sure that Apache-Test/ is added to @INC.

Public API

The following functions are a part of the public API. They are described elsewhere in this document.

WriteMakefile()

  ModPerl::MM::WriteMakefile(...);

get_def_opt()

  my $def_val = ModPerl::MM::get_def_opt($key);


ModPerl::MethodLookup -- Lookup mod_perl modules, objects and methods

  • Synopsis
  • Description
  • API
    • lookup_method()
    • lookup_module()
    • lookup_object()
    • preload_all_modules()
    • print_method()
    • print_module()
    • print_object()
  • Applications
    • AUTOLOAD
    • Command Line Lookups
  • Todo
  • See Also
  • Copyright
  • Authors

NAME

ModPerl::MethodLookup -- Lookup mod_perl modules, objects and methods

Synopsis

  use ModPerl::MethodLookup;

  # return all module names containing XS method 'print'
  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print');

  # return only module names containing method 'print' which
  # expects the first argument to be of type 'Apache2::Filter'
  # (here $filter is an Apache2::Filter object)
  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print', $filter);
  # or
  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');

  # what XS methods defined by module 'Apache2::Filter'
  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_module('Apache2::Filter');

  # what XS methods can be invoked on the object $r (or a ref)
  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_object($r);
  # or
  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');

  # preload all mp2 modules in startup.pl
  ModPerl::MethodLookup::preload_all_modules();

  # command line shortcuts
  % perl -MModPerl::MethodLookup -e print_module \
    Apache2::RequestRec Apache2::Filter
  % perl -MModPerl::MethodLookup -e print_object Apache2
  % perl -MModPerl::MethodLookup -e print_method \
    get_server_built request
  % perl -MModPerl::MethodLookup -e print_method read
  % perl -MModPerl::MethodLookup -e print_method read APR::Bucket

Description

mod_perl 2.0 provides many methods, which reside in various modules. One has to load each of the modules before using the desired methods. ModPerl::MethodLookup provides the Perl API for finding module names which contain methods in question and other helper functions, to find out out what methods defined by some module, what methods can be called on a given object, etc.

API

lookup_method()

Find modules (packages) containing a certain method

  ($hint, @modules) = lookup_method($method_name);
  ($hint, @modules) = lookup_method($method_name, $object);
  ($hint, @modules) = lookup_method($method_name, $class));
arg1: $method_name ( string )

the method name to look up

opt arg2: $object or $class

a blessed object or the name of the class it's blessed into. If there is more than one match, this extra information is used to return only modules containing methods operating on the objects of the same kind.

If a sub-classed object is passed it'll be handled correctly, by checking its super-class(es). This usage is useful when the AUTOLOAD|/C_AUTOLOAD_ is used to find a not yet loaded module which include the called method.

ret1: $hint

a string containing a human readable lookup result, suggesting which modules should be loaded, ready for copy-n-paste or explaining the failure if the lookup didn't succeed.

ret2: @modules

an array of modules which have matched the query, i.e. the names of the modules which contain the requested method.

since: 2.0.00

Examples:

Return all module names containing XS method print:

  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print');

Return only module names containing method print which expects the first argument to be of type Apache2::Filter:

  my $filter = bless {}, 'Apache2::Filter';
  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print', $filter);

or:

  my ($hint, @modules) =
      ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');

lookup_module()

Find methods contained in a certain module (package)

  ($hint, @methods) = lookup_module($module_name);
arg1: $module_name ( string )

the module name

ret1: $hint

a string containing a human readable lookup result, suggesting, which methods the module $module_name implements, or explaining the failure if the lookup failed.

ret2: @methods

an array of methods which have matched the query, i.e. the names of the methods defined in the requested module.

since: 2.0.00

Example:

What XS methods defined by module Apache2::Filter:

  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_module('Apache2::Filter');

lookup_object()

  ($hint, @methods) = lookup_object($object);
  ($hint, @methods) = lookup_object($class);
arg1: $object or $class

an object or a name of a class an object is blessed into

If a sub-classed object is passed it'll be handled correctly, by including methods provided by its super-class(es).

ret1: $hint

a string containing a human readable lookup result, suggesting, which methods the given object can invoke (including module names that need to be loaded to use those methods), or explaining the failure if the lookup failed.

ret2: @methods

an array of methods which have matched the query, i.e. the names of the methods that can be invoked on the given object (or its class name).

since: 2.0.00

META: As of this writing this function may miss some of the functions/methods that can be invoked on the given object. Currently we can't programmatically deduct the objects they are invoked on, because these methods are written in pure XS and manipulate the arguments stack themselves. Currently these are mainly XS functions, not methods, which of course aren't invoked on objects. There are also logging function wrappers (Apache2::Log).

Examples:

What XS methods can be invoked on the object $r:

  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_object($r);

or $r's class -- Apache2::RequestRec:

  my ($hint, @methods) =
      ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');

preload_all_modules()

The function preload_all_modules() preloads all mod_perl 2.0 modules, which implement their API in XS. This is similar to the mod_perl 1.0 behavior which has most of its methods loaded at the startup.

CPAN modules developers should make sure their distribution loads each of the used mod_perl 2.0 modules explicitly, and not use this function, as it takes the fine control away from the users. One should avoid doing this the production server (unless all modules are used indeed) in order to save memory.

since: 2.0.00

print_method()

print_method() is a convenience wrapper for lookup_method()|/C_lookup_method___, mainly designed to be used from the command line. For example to print all the modules which define method read execute:

  % perl -MModPerl::MethodLookup -e print_method read

Since this will return more than one module, we can narrow the query to only those methods which expect the first argument to be blessed into class APR::Bucket:

  % perl -MModPerl::MethodLookup -e print_method read APR::Bucket

You can pass more than one method and it'll perform a lookup on each of the methods. For example to lookup methods get_server_built and request you can do:

  % perl -MModPerl::MethodLookup -e print_method \
    get_server_built request

The function print_method() is exported by default.

since: 2.0.00

print_module()

print_module() is a convenience wrapper for lookup_module()|/C_lookup_module___, mainly designed to be used from the command line. For example to print all the methods defined in the module Apache2::RequestRec, followed by methods defined in the module Apache2::Filter you can run:

  % perl -MModPerl::MethodLookup -e print_module \
    Apache2::RequestRec Apache2::Filter

The function print_module() is exported by default.

since: 2.0.00

print_object()

print_object() is a convenience wrapper for lookup_object()|/C_lookup_object___, mainly designed to be used from the command line. For example to print all the methods that can be invoked on object blessed into a class Apache2::RequestRec run:

  % perl -MModPerl::MethodLookup -e print_object \
    Apache2::RequestRec

Similar to print_object()|/C_print_object___, more than one class can be passed to this function.

The function print_object() is exported by default.

since: 2.0.00

Applications

AUTOLOAD

When Perl fails to locate a method it checks whether the package the object belongs to has an AUTOLOAD function defined and if so, calls it with the same arguments as the missing method while setting a global variable $AUTOLOAD (in that package) to the name of the originally called method. We can use this facility to lookup the modules to be loaded when such a failure occurs. Though since we have many packages to take care of we will use a special UNIVERSAL::AUTOLOAD function which Perl calls if can't find the AUTOLOAD function in the given package.

In that function you can query ModPerl::MethodLookup, require() the module that includes the called method and call that method again using the goto() trick:

  use ModPerl::MethodLookup;
  sub UNIVERSAL::AUTOLOAD {
      my ($hint, @modules) =
          ModPerl::MethodLookup::lookup_method($UNIVERSAL::AUTOLOAD, @_);
      if (@modules) {
          eval "require $_" for @modules;
          goto &$UNIVERSAL::AUTOLOAD;
      }
      else {
          die $hint;
      }
  }

However we don't endorse this approach. It's a better approach to always abort the execution which printing the $hintand use fix the code to load the missing module. Moreover installing UNIVERSAL::AUTOLOAD may cause a lot of problems, since once it's installed Perl will call it every time some method is missing (e.g. undefined DESTROY methods). The following approach seems to somewhat work for me. It installs UNIVERSAL::AUTOLOAD only when the the child process starts.

  httpd.conf:
  -----------
  PerlChildInitHandler ModPerl::MethodLookupAuto
  startup.pl:
  -----------
  {
      package ModPerl::MethodLookupAuto;
      use ModPerl::MethodLookup;

      use Carp;
      sub handler {

          *UNIVERSAL::AUTOLOAD = sub {
              my $method = $AUTOLOAD;
              return if $method =~ /DESTROY/; # exclude DESTROY resolving

              my ($hint, @modules) =
                  ModPerl::MethodLookup::lookup_method($method, @_);
              $hint ||= "Can't find method $AUTOLOAD";
              croak $hint;
          };
          return 0;
      }
  }

This example doesn't load the modules for you. It'll print to STDERR what module should be loaded, when a method from the not-yet-loaded module is called.

A similar technique is used by Apache2::porting|docs::2.0::api::Apache2::porting.

META: there is a better version of AUTOLOAD discussed on the dev list. Replace the current one with it. (search the archive for EazyLife)

Command Line Lookups

When a method is used and mod_perl has reported a failure to find it, it's often useful to use the command line query to figure out which module needs to be loaded. For example if when executing:

  $r->construct_url();

mod_perl complains:

  Can't locate object method "construct_url" via package
  "Apache2::RequestRec" at ...

you can ask ModPerl::MethodLookup for help:

  % perl -MModPerl::MethodLookup -e print_method construct_url
  To use method 'construct_url' add:
          use Apache2::URI ();

and after copy-n-pasting the use statement in our code, the problem goes away.

One can create a handy alias for this technique. For example, C-style shell users can do:

   % alias lookup "perl -MModPerl::MethodLookup -e print_method"

For Bash-style shell users:

   % alias lookup="perl -MModPerl::MethodLookup -e print_method"

Now the lookup is even easier:

  % lookup construct_url
  to use method 'construct_url' add:
          use Apache2::URI;

Similar aliases can be provided for print_object()|/C_print_object___ and print_module()|/C_print_module___.

Todo

These methods aren't yet picked by this module (the extract from the map file):

 modperl_filter_attributes     | MODIFY_CODE_ATTRIBUTES
 modperl_spawn_proc_prog       | spawn_proc_prog
 apr_ipsubnet_create           | new

Please report to the mod_perl development mailing list if you find any other missing methods. But remember that as of this moment the module reports only XS functions. In the future we may add support for pure perl functions/methods as well.

See Also

  • the mod_perl 1.0 backward compatibility document

  • porting Perl modules

  • porting XS modules

  • Apache2::porting|docs::2.0::api::Apache2::porting

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


ModPerl::PerlRun - Run unaltered CGI scripts under mod_perl

  • Synopsis
  • Description
  • Special Blocks
    • BEGIN Blocks
    • CHECK and INIT Blocks
    • END Blocks
  • Authors
  • See Also

NAME

ModPerl::PerlRun - Run unaltered CGI scripts under mod_perl

Synopsis

  # httpd.conf
  PerlModule ModPerl::PerlRun
  Alias /perl-run/ /home/httpd/perl/
  <Location /perl-run>
      SetHandler perl-script
      PerlResponseHandler ModPerl::PerlRun
      PerlOptions +ParseHeaders
      Options +ExecCGI
  </Location>

Description

META: document that for now we don't chdir() into the script's dir, because it affects the whole process under threads. ModPerl::PerlRunPrefork|docs::2.0::api::ModPerl::PerlRunPrefork should be used by those who run only under prefork MPM.

Special Blocks

BEGIN Blocks

When running under the ModPerl::PerlRun handler BEGIN blocks behave as follows:

  • BEGIN blocks defined in scripts running under the ModPerl::PerlRun handler are executed on each and every request.

  • BEGIN blocks defined in modules loaded from scripts running under ModPerl::PerlRun (and which weren't already loaded prior to the request) are executed on each and every request only if those modules declare no package. If a package is declared BEGIN blocks will be run only the first time each module is loaded, since those modules don't get reloaded on subsequent requests.

See also BEGIN blocks in mod_perl handlers.

CHECK and INIT Blocks

Same as normal mod_perl handlers.

END Blocks

Same as ModPerl::Registry|docs::2.0::api::ModPerl::Registry/C_BEGIN__Blocks.

Authors

Doug MacEachern

Stas Bekman

See Also

ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker and ModPerl::Registry|docs::2.0::api::ModPerl::Registry.


ModPerl::PerlRunPrefork - Run unaltered CGI scripts under mod_perl

  • Synopsis
  • Description
  • Copyright
  • Authors
  • See Also

NAME

ModPerl::PerlRunPrefork - Run unaltered CGI scripts under mod_perl

Synopsis

  # httpd.conf
  PerlModule ModPerl::PerlRunPrefork
  Alias /perl-run/ /home/httpd/perl/
  <Location /perl-run>
      SetHandler perl-script
      PerlResponseHandler ModPerl::PerlRunPrefork
      PerlOptions +ParseHeaders
      Options +ExecCGI
  </Location>

Description

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.

See Also

ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker and ModPerl::Registry|docs::2.0::api::ModPerl::Registry.


ModPerl::Registry - Run unaltered CGI scripts persistently under mod_perl

  • Synopsis
  • Description
  • DirectoryIndex
  • Special Blocks
    • BEGIN Blocks
    • CHECK and INIT Blocks
    • END Blocks
  • Security
  • Environment
  • Commandline Switches In First Line
  • Debugging
  • Caveats
  • Authors
  • See Also

NAME

ModPerl::Registry - Run unaltered CGI scripts persistently under mod_perl

Synopsis

  # httpd.conf
  PerlModule ModPerl::Registry
  Alias /perl/ /home/httpd/perl/
  <Location /perl>
      SetHandler perl-script
      PerlResponseHandler ModPerl::Registry
      #PerlOptions +ParseHeaders
      #PerlOptions -GlobalRequest
      Options +ExecCGI
  </Location>

Description

URIs in the form of http://example.com/perl/test.pl will be compiled as the body of a Perl subroutine and executed. Each child process will compile the subroutine once and store it in memory. It will recompile it whenever the file (e.g. test.pl in our example) is updated on disk. Think of it as an object oriented server with each script implementing a class loaded at runtime.

The file looks much like a "normal" script, but it is compiled into a subroutine.

For example:

  my $r = Apache2::RequestUtil->request;
  $r->content_type("text/html");
  $r->send_http_header;
  $r->print("mod_perl rules!");

XXX: STOPPED here. Below is the old Apache::Registry document which I haven't worked through yet.

META: document that for now we don't chdir() into the script's dir, because it affects the whole process under threads. ModPerl::RegistryPrefork|docs::2.0::api::ModPerl::RegistryPrefork should be used by those who run only under prefork MPM.

This module emulates the CGI environment, allowing programmers to write scripts that run under CGI or mod_perl without change. Existing CGI scripts may require some changes, simply because a CGI script has a very short lifetime of one HTTP request, allowing you to get away with "quick and dirty" scripting. Using mod_perl and ModPerl::Registry requires you to be more careful, but it also gives new meaning to the word "quick"!

Be sure to read all mod_perl related documentation for more details, including instructions for setting up an environment that looks exactly like CGI:

 print "Content-type: text/html\n\n";
 print "Hi There!";

Note that each httpd process or "child" must compile each script once, so the first request to one server may seem slow, but each request there after will be faster. If your scripts are large and/or make use of many Perl modules, this difference should be noticeable to the human eye.

DirectoryIndex

If you are trying setup a DirectoryIndex under a Location covered by ModPerl::Registry* you might run into some trouble.

META: if this gets added to core, replace with real documenation. See http://marc.theaimsgroup.com/?l=apache-modperl&m=112805393100758&w=2

Special Blocks

BEGIN Blocks

BEGIN blocks defined in scripts running under the ModPerl::Registry handler behave similarly to the normal mod_perl handlers plus:

  • Only once, if pulled in by the parent process via Apache2::RegistryLoader.

  • An additional time, once per child process or Perl interpreter, each time the script file changes on disk.

BEGIN blocks defined in modules loaded from ModPerl::Registry scripts behave identically to the normal mod_perl handlers, regardless of whether they define a package or not.

CHECK and INIT Blocks

Same as normal mod_perl handlers.

END Blocks

END blocks encountered during compilation of a script, are called after the script has completed its run, including subsequent invocations when the script is cached in memory. This is assuming that the script itself doesn't define a package on its own. If the script defines its own package, the END blocks in the scope of that package will be executed at the end of the interpretor's life.

END blocks residing in modules loaded by registry script will be executed only once, when the interpreter exits.

Security

ModPerl::Registry::handler performs the same sanity checks as mod_cgi does, before running the script.

Environment

The Apache function `exit' overrides the Perl core built-in function.

Commandline Switches In First Line

Normally when a Perl script is run from the command line or under CGI, arguments on the `#!' line are passed to the perl interpreter for processing.

ModPerl::Registry currently only honors the -w switch and will enable the warnings pragma in such case.

Another common switch used with CGI scripts is -T to turn on taint checking. This can only be enabled when the server starts with the configuration directive:

 PerlSwitches -T

However, if taint checking is not enabled, but the -T switch is seen, ModPerl::Registry will write a warning to the error_log file.

Debugging

You may set the debug level with the $ModPerl::Registry::Debug bitmask

 1 => log recompile in errorlog
 2 => ModPerl::Debug::dump in case of $@
 4 => trace pedantically

Caveats

ModPerl::Registry makes things look just the CGI environment, however, you must understand that this *is not CGI*. Each httpd child will compile your script into memory and keep it there, whereas CGI will run it once, cleaning out the entire process space. Many times you have heard "always use -w, always use -w and 'use strict'". This is more important here than anywhere else!

Authors

Andreas J. Koenig, Doug MacEachern and Stas Bekman.

See Also

ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker,
ModPerl::RegistryBB|docs::2.0::api::ModPerl::RegistryBB and
ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun.


ModPerl::RegistryBB - Run unaltered CGI scripts persistently under mod_perl

  • Synopsis
  • Description
  • Authors
  • See Also

NAME

ModPerl::RegistryBB - Run unaltered CGI scripts persistently under mod_perl

Synopsis

  # httpd.conf
  PerlModule ModPerl::RegistryBB
  Alias /perl/ /home/httpd/perl/
  <Location /perl>
      SetHandler perl-script
      PerlResponseHandler ModPerl::RegistryBB
      #PerlOptions +ParseHeaders
      #PerlOptions -GlobalRequest
      Options +ExecCGI
  </Location>

Description

ModPerl::RegistryBB is similar to ModPerl::Registry, but does the bare minimum (mnemonic: BB = Bare Bones) to compile a script file once and run it many times, in order to get the maximum performance. Whereas ModPerl::Registry does various checks, which add a slight overhead to response times.

Authors

Doug MacEachern

Stas Bekman

See Also

ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker,
ModPerl::Registry|docs::2.0::api::ModPerl::Registry and
ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun.


ModPerl::RegistryCooker - Cook mod_perl 2.0 Registry Modules

  • Synopsis
  • Description
    • Special Predefined Functions
  • Sub-classing Techniques
  • Examples
  • Authors
  • See Also

NAME

ModPerl::RegistryCooker - Cook mod_perl 2.0 Registry Modules

Synopsis

  # shouldn't be used as-is but sub-classed first
  # see ModPerl::Registry for an example

Description

ModPerl::RegistryCooker is used to create flexible and overridable registry modules which emulate mod_cgi for Perl scripts. The concepts are discussed in the manpage of the following modules: ModPerl::Registry, ModPerl::Registry and ModPerl::RegistryBB.

ModPerl::RegistryCooker has two purposes:

  • Provide ingredients that can be used by registry sub-classes

  • Provide a default behavior, which can be overriden in sub-classed

    META: in the future this functionality may move into a separate class.

Here are the current overridable methods:

META: these are all documented in RegistryCooker.pm, though not using pod. please help to port these to pod and move the descriptions here.

  • new()

    create the class's object, bless it and return it

      my $obj = $class->new($r);

    $class -- the registry class, usually __PACKAGE__ can be used.

    $r -- Apache2::Request object.

    default: new()

  • init()

    initializes the data object's fields: REQ, FILENAME, URI. Called from the new().

    default: init()

  • default_handler()

    default: default_handler()

  • run()

    default: run()

  • can_compile()

    default: can_compile()

  • make_namespace()

    default: make_namespace()

  • namespace_root()

    default: namespace_root()

  • namespace_from()

    If namespace_from_uri is used and the script is called from the virtual host, by default the virtual host name is prepended to the uri when package name for the compiled script is created. Sometimes this behavior is undesirable, e.g., when the same (physical) script is accessed using the same path_info but different virtual hosts. In that case you can make the script compiled only once for all vhosts, by specifying:

      $ModPerl::RegistryCooker::NameWithVirtualHost = 0;

    The drawback is that it affects the global environment and all other scripts will be compiled ignoring virtual hosts.

    default: namespace_from()

  • is_cached()

    default: is_cached()

  • should_compile()

    default: should_compile()

  • flush_namespace()

    default: flush_namespace()

  • cache_table()

    default: cache_table()

  • cache_it()

    default: cache_it()

  • read_script()

    default: read_script()

  • shebang_to_perl()

    default: shebang_to_perl()

  • get_script_name()

    default: get_script_name()

  • chdir_file()

    default: chdir_file()

  • get_mark_line()

    default: get_mark_line()

  • compile()

    default: compile()

  • error_check()

    default: error_check()

  • strip_end_data_segment()

    default: strip_end_data_segment()

  • convert_script_to_compiled_handler()

    default: convert_script_to_compiled_handler()

Special Predefined Functions

The following functions are implemented as constants.

  • NOP()

    Use when the function shouldn't do anything.

  • TRUE()

    Use when a function should always return a true value.

  • FALSE()

    Use when a function should always return a false value.

Sub-classing Techniques

To override the default ModPerl::RegistryCooker methods, first, sub-class ModPerl::RegistryCooker or one of its existing sub-classes, using use base. Second, override the methods.

Those methods that weren't overridden will be resolved at run time when used for the first time and cached for the future requests. One way to to shortcut this first run resolution is to use the symbol aliasing feature. For example to alias ModPerl::MyRegistry::flush_namespace as ModPerl::RegistryCooker::flush_namespace, you can do:

  package ModPerl::MyRegistry;
  use base qw(ModPerl::RegistryCooker);
  *ModPerl::MyRegistry::flush_namespace =
      \&ModPerl::RegistryCooker::flush_namespace;
  1;

In fact, it's a good idea to explicitly alias all the methods so you know exactly what functions are used, rather then relying on the defaults. For that purpose ModPerl::RegistryCooker class method install_aliases() can be used. Simply prepare a hash with method names in the current package as keys and corresponding fully qualified methods to be aliased for as values and pass it to install_aliases(). Continuing our example we could do:

  package ModPerl::MyRegistry;
  use base qw(ModPerl::RegistryCooker);
  my %aliases = (
      flush_namespace => 'ModPerl::RegistryCooker::flush_namespace',
  );
  __PACKAGE__->install_aliases(\%aliases);
  1;

The values use fully qualified packages so you can mix methods from different classes.

Examples

The best examples are existing core registry modules: ModPerl::Registry, ModPerl::Registry and ModPerl::RegistryBB. Look at the source code and their manpages to see how they subclass ModPerl::RegistryCooker.

For example by default ModPerl::Registry uses the script's path when creating a package's namespace. If for example you want to use a uri instead you can override it with:

  *ModPerl::MyRegistry::namespace_from =
      \&ModPerl::RegistryCooker::namespace_from_uri;
  1;

Since the namespace_from_uri component already exists in ModPerl::RegistryCooker. If you want to write your own method, e.g., that creates a namespace based on the inode, you can do:

  sub namespace_from_inode {
      my $self = shift;
      return (stat $self->[FILENAME])[1];
  }

META: when $r->finfo will be ported it'll be more effecient. (stat $r->finfo)[1]

Authors

Doug MacEachern

Stas Bekman

See Also

ModPerl::Registry|docs::2.0::api::ModPerl::Registry,
ModPerl::RegistryBB|docs::2.0::api::ModPerl::RegistryBB and
ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun.


ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at server startup

  • Synopsis
  • Description
  • Methods
  • Implementation Notes
  • Authors
  • SEE ALSO

NAME

ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at server startup

Synopsis

  # in startup.pl
  use ModPerl::RegistryLoader ();
  use File::Spec ();

  # explicit uri => filename mapping
  my $rlbb = ModPerl::RegistryLoader->new(
      package => 'ModPerl::RegistryBB',
      debug   => 1, # default 0
  );

  $rlbb->handler($uri, $filename);

  ###
  # uri => filename mapping using a helper function
  sub trans {
      my $uri = shift;
      $uri =~ s|^/registry/|cgi-bin/|;
      return File::Spec->catfile(Apache2::ServerUtil::server_root, $uri);
  }
  my $rl = ModPerl::RegistryLoader->new(
      package => 'ModPerl::Registry',
      trans   => \&trans,
  );
  $rl->handler($uri);

  ###
  $rlbb->handler($uri, $filename, $virtual_hostname);

Description

This modules allows compilation of scripts, running under packages derived from ModPerl::RegistryCooker, at server startup. The script's handler routine is compiled by the parent server, of which children get a copy and thus saves some memory by initially sharing the compiled copy with the parent and saving the overhead of script's compilation on the first request in every httpd instance.

This module is of course useless for those running the ModPerl::PerlRun handler, because the scripts get recompiled on each request under this handler.

Methods

new()

When creating a new ModPerl::RegistryLoader object, one has to specify which of the ModPerl::RegistryCooker derived modules to use. For example if a script is going to run under ModPerl::RegistryBB the object is initialized as:

  my $rlbb = ModPerl::RegistryLoader->new(
      package => 'ModPerl::RegistryBB',
  );

If the package is not specified ModPerl::Registry is assumed:

  my $rlbb = ModPerl::RegistryLoader->new();

To turn the debugging on, set the debug attribute to a true value:

  my $rlbb = ModPerl::RegistryLoader->new(
      package => 'ModPerl::RegistryBB',
      debug   => 1,
  );

Instead of specifying explicitly a filename for each uri passed to handler(), a special attribute trans can be set to a subroutine to perform automatic remapping.

  my $rlbb = ModPerl::RegistryLoader->new(
      package => 'ModPerl::RegistryBB',
      trans   => \&trans,
  );

See the handler() item for an example of using the trans attribute.

handler()
  $rl->handler($uri, [$filename, [$virtual_hostname]]);

The handler() method takes argument of uri and optionally of filename and of virtual_hostname.

URI to filename translation normally doesn't happen until HTTP request time, so we're forced to roll our own translation. If the filename is supplied it's used in translation.

If the filename is omitted and a trans subroutine was not set in new(), the loader will try using the uri relative to the ServerRoot configuration directive. For example:

  httpd.conf:
  -----------
  ServerRoot /usr/local/apache
  Alias /registry/ /usr/local/apache/cgi-bin/
  startup.pl:
  -----------
  use ModPerl::RegistryLoader ();
  my $rl = ModPerl::RegistryLoader->new(
      package => 'ModPerl::Registry',
  );
  # preload /usr/local/apache/cgi-bin/test.pl
  $rl->handler(/registry/test.pl);

To make the loader smarter about the URI->filename translation, you may provide the new() method with a trans() function to translate the uri to filename.

The following example will pre-load all files ending with .pl in the cgi-bin directory relative to ServerRoot.

  httpd.conf:
  -----------
  ServerRoot /usr/local/apache
  Alias /registry/ /usr/local/apache/cgi-bin/
  startup.pl:
  -----------
  {
      # test the scripts pre-loading by using trans sub
      use ModPerl::RegistryLoader ();
      use File::Spec ();
      use DirHandle ();
      use strict;

      my $dir = File::Spec->catdir(Apache2::ServerUtil::server_root,
                                  "cgi-bin");

      sub trans {
          my $uri = shift;
          $uri =~ s|^/registry/|cgi-bin/|;
          return File::Spec->catfile(Apache2::ServerUtil::server_root,
                                     $uri);
      }

      my $rl = ModPerl::RegistryLoader->new(
          package => "ModPerl::Registry",
          trans   => \&trans,
      );
      my $dh = DirHandle->new($dir) or die $!;

      for my $file ($dh->read) {
          next unless $file =~ /\.pl$/;
          $rl->handler("/registry/$file");
      }
  }

If $virtual_hostname argument is passed it'll be used in the creation of the package name the script will be compiled into for those registry handlers that use namespace_from_uri() method. See also the notes on $ModPerl::RegistryCooker::NameWithVirtualHost in the ModPerl::RegistryCooker documentation.

Also explained in the ModPerl::RegistryLoader documentation, this only has an effect at run time if $ModPerl::RegistryCooker::NameWithVirtualHost is set to true, otherwise the $virtual_hostname argument is ignored.

Implementation Notes

ModPerl::RegistryLoader performs a very simple job, at run time it loads and sub-classes the module passed via the package attribute and overrides some of its functions, to emulate the run-time environment. This allows to preload the same script into different registry environments.

Authors

The original Apache2::RegistryLoader implemented by Doug MacEachern.

Stas Bekman did the porting to the new registry framework based on ModPerl::RegistryLoader.

SEE ALSO

ModPerl::RegistryCooker, ModPerl::Registry,
ModPerl::RegistryBB, ModPerl::PerlRun, Apache(3),
mod_perl(3)


ModPerl::RegistryPrefork - Run unaltered CGI scripts under mod_perl

  • Synopsis
  • Description
  • Copyright
  • Authors
  • See Also

NAME

ModPerl::RegistryPrefork - Run unaltered CGI scripts under mod_perl

Synopsis

  # httpd.conf
  PerlModule ModPerl::RegistryPrefork
  Alias /perl-run/ /home/httpd/perl/
  <Location /perl-run>
      SetHandler perl-script
      PerlResponseHandler ModPerl::RegistryPrefork
      PerlOptions +ParseHeaders
      Options +ExecCGI
  </Location>

Description

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.

See Also

ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker and ModPerl::Registry|docs::2.0::api::ModPerl::Registry.


ModPerl::Util - Helper mod_perl Functions

  • Synopsis
  • Description
  • API
    • current_callback
    • current_perl_id
    • exit
    • unload_package
    • untaint
  • See Also
  • Copyright
  • Authors

NAME

ModPerl::Util - Helper mod_perl Functions

Synopsis

  use ModPerl::Util;

  # e.g. PerlResponseHandler
  $callback = ModPerl::Util::current_callback;

  # exit w/o killing the interpreter
  ModPerl::Util::exit();

  # untaint a string (do not use it! see the doc)
  ModPerl::Util::untaint($string);

  # removes a stash (.so, %INC{$stash}, etc.) as best as it can
  ModPerl::Util::unload_package($stash);

  # current perl's address (0x92ac760 or 0x0 under non-threaded perl)
  ModPerl::Util::current_perl_id();

Description

ModPerl::Util provides mod_perl utilities API.

API

ModPerl::Util provides the following functions and/or methods:

current_callback

Returns the currently running callback name, e.g. 'PerlResponseHandler'.

  $callback = ModPerl::Util::current_callback();
ret: $callback ( string )
since: 2.0.00

current_perl_id

Return the memory address of the perl interpreter

  $perl_id = ModPerl::Util::current_perl_id();
ret: $perl_id ( string )

Under threaded perl returns something like: 0x92ac760

Under non-thread perl returns 0x0

since: 2.0.00

Mainly useful for debugging applications running under threaded-perl.

exit

Terminate the request, but not the current process (or not the current Perl interpreter with threaded mpms).

  ModPerl::Util::exit($status);
opt arg1: $status ( integer )

The exit status, which as of this writing is ignored. (it's accepted to be compatible with the core exit function.)

ret: no return value
since: 2.0.00

Normally you will use the plain exit() in your code. You don't need to use ModPerl::Util::exit explicitly, since mod_perl overrides exit() by setting CORE::GLOBAL::exit to ModPerl::Util::exit. Only if you redefine CORE::GLOBAL::exit once mod_perl is running, you may want to use this function.

The original exit() is still available via CORE::exit().

ModPerl::Util::exit is implemented as a special die() call, therefore if you call it inside eval BLOCK or eval "STRING", while an exception is being thrown, it is caught by eval. For example:

  exit;
  print "Still running";

will not print anything. But:

  eval {
     exit;
  }
  print "Still running";

will print Still running. So you either need to check whether the exception is specific to exit and call exit() again:

  use ModPerl::Const -compile => 'EXIT';
  eval {
     exit;
  }
  exit if $@ && ref $@ eq 'APR::Error' && $@ == ModPerl::EXIT;
  print "Still running";

or use CORE::exit():

  eval {
     CORE::exit;
  }
  print "Still running";

and nothing will be printed. The problem with the latter is the current process (or a Perl Interpreter) will be killed; something that you really want to avoid under mod_perl.

unload_package

Unloads a stash from the current Perl interpreter in the safest way possible.

  ModPerl::Util::unload_package($stash);
arg1: $stash ( string )

The Perl stash to unload. e.g. MyApache2::MyData.

ret: no return value
since: 2.0.00

Unloading a Perl stash (package) is a complicated business. This function tries very hard to do the right thing. After calling this function, it should be safe to use() a new version of the module that loads the wiped package.

References to stash elements (functions, variables, etc.) taken from outside the unloaded package will still be valid.

This function may wipe off things loaded by other modules, if the latter have inserted things into the $stash it was told to unload.

If a stash had a corresponding XS shared object (.so) loaded it will be unloaded as well.

If the stash had a corresponding entry in %INC, it will be removed from there.

unload_package() takes care to leave sub-stashes intact while deleting the requested stash. So for example if CGI and CGI::Carp are loaded, calling unload_package('CGI') won't affect CGI::Carp.

untaint

Untaint the variable, by turning its tainted SV flag off (used internally).

  ModPerl::Util::untaint($tainted_var);
arg1: $tainted_var (scalar)
ret: no return value

$tainted_var is untainted.

since: 2.0.00

Do not use this function unless you know what you are doing. To learn how to properly untaint variables refer to the perlsec manpage.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.


Module::Pluggable - automatically give your module the ability to have plugins

  • EXAMPLE
  • DESCRIPTION
  • ADVANCED USAGE
  • INNER PACKAGES
  • OPTIONS
    • sub_name
    • search_path
    • search_dirs
    • instantiate
    • require
    • inner
    • only
    • except
    • package
    • file_regex
  • METHODs
    • search_path
  • FUTURE PLANS
  • AUTHOR
  • COPYING
  • BUGS
  • SEE ALSO

NAME

Module::Pluggable - automatically give your module the ability to have plugins

SYNOPSIS

Simple use Module::Pluggable -

    package MyClass;
    use Module::Pluggable;

and then later ...

    use MyClass;
    my $mc = MyClass->new();
    # returns the names of all plugins installed under MyClass::Plugin::*
    my @plugins = $mc->plugins();

EXAMPLE

Why would you want to do this? Say you have something that wants to pass an object to a number of different plugins in turn. For example you may want to extract meta-data from every email you get sent and do something with it. Plugins make sense here because then you can keep adding new meta data parsers and all the logic and docs for each one will be self contained and new handlers are easy to add without changing the core code. For that, you might do something like ...

    package Email::Examiner;

    use strict;
    use Email::Simple;
    use Module::Pluggable require => 1;

    sub handle_email {
        my $self  = shift;
        my $email = shift;

        foreach my $plugin ($self->plugins) {
            $plugin->examine($email);
        }

        return 1;
            }

.. and all the plugins will get a chance in turn to look at it.

This can be trivally extended so that plugins could save the email somewhere and then no other plugin should try and do that. Simply have it so that the examine method returns 1 if it has saved the email somewhere. You might also wnat to be paranoid and check to see if the plugin has an examine method.

        foreach my $plugin ($self->plugins) {
            next unless $plugin->can('examine');
            last if     $plugin->examine($email);
        }

And so on. The sky's the limit.

DESCRIPTION

Provides a simple but, hopefully, extensible way of having 'plugins' for your module. Obviously this isn't going to be the be all and end all of solutions but it works for me.

Essentially all it does is export a method into your namespace that looks through a search path for .pm files and turn those into class names.

Optionally it instantiates those classes for you.

ADVANCED USAGE

    Alternatively, if you don't want to use 'plugins' as the method ...

    package MyClass;
    use Module::Pluggable sub_name => 'foo';

and then later ...

    my @plugins = $mc->foo();

Or if you want to look in another namespace

    package MyClass;
    use Module::Pluggable search_path => ['Acme::MyClass::Plugin', 'MyClass::Extend'];

or directory

    use Module::Pluggable search_dirs => ['mylibs/Foo'];

Or if you want to instantiate each plugin rather than just return the name

    package MyClass;
    use Module::Pluggable instantiate => 'new';

and then

    # whatever is passed to 'plugins' will be passed
    # to 'new' for each plugin
    my @plugins = $mc->plugins(@options);

alternatively you can just require the module without instantiating it

    package MyClass;
    use Module::Pluggable require => 1;

since requiring automatically searches inner packages, which may not be desirable, you can turn this off

    package MyClass;
    use Module::Pluggable require => 1, inner => 0;

You can limit the plugins loaded using the except option, either as a string, array ref or regex

    package MyClass;
    use Module::Pluggable except => 'MyClass::Plugin::Foo';

or

    package MyClass;
    use Module::Pluggable except => ['MyClass::Plugin::Foo', 'MyClass::Plugin::Bar'];

or

    package MyClass;
    use Module::Pluggable except => qr/^MyClass::Plugin::(Foo|Bar)$/;

and similarly for only which will only load plugins which match.

Remember you can use the module more than once

    package MyClass;
    use Module::Pluggable search_path => 'MyClass::Filters' sub_name => 'filters';
    use Module::Pluggable search_path => 'MyClass::Plugins' sub_name => 'plugins';

and then later ...

    my @filters = $self->filters;
    my @plugins = $self->plugins;

INNER PACKAGES

If you have, for example, a file lib/Something/Plugin/Foo.pm that contains package definitions for both Something::Plugin::Foo and Something::Plugin::Bar then as long as you either have either the require or instantiate option set then we'll also find Something::Plugin::Bar. Nifty!

OPTIONS

You can pass a hash of options when importing this module.

The options can be ...

sub_name

The name of the subroutine to create in your namespace.

By default this is 'plugins'

search_path

An array ref of namespaces to look in.

search_dirs

An array ref of directorys to look in before @INC.

instantiate

Call this method on the class. In general this will probably be 'new' but it can be whatever you want. Whatever arguments are passed to 'plugins' will be passed to the method.

The default is 'undef' i.e just return the class name.

require

Just require the class, don't instantiate (overrides 'instantiate');

inner

If set to 0 will not search inner packages. If set to 1 will override require.

only

Takes a string, array ref or regex describing the names of the only plugins to return. Whilst this may seem perverse ... well, it is. But it also makes sense. Trust me.

except

Similar to only it takes a description of plugins to exclude from returning. This is slightly less perverse.

package

This is for use by extension modules which build on Module::Pluggable: passing a package option allows you to place the plugin method in a different package other than your own.

file_regex

By default Module::Pluggable only looks for .pm files.

By supplying a new file_regex then you can change this behaviour e.g

    file_regex => qr/\.plugin$/

METHODs

search_path

The method search_path is exported into you namespace as well. You can call that at any time to change or replace the search_path.

    $self->search_path( add => "New::Path" ); # add
    $self->search_path( new => "New::Path" ); # replace

FUTURE PLANS

This does everything I need and I can't really think of any other features I want to add. Famous last words of course

Recently tried fixed to find inner packages and to make it 'just work' with PAR but there are still some issues.

However suggestions (and patches) are welcome.

AUTHOR

Simon Wistow <simon@thegestalt.org>

COPYING

Copyright, 2006 Simon Wistow

Distributed under the same terms as Perl itself.

BUGS

None known.

SEE ALSO

the File::Spec manpage, the File::Find manpage, the File::Basename manpage, the Class::Factory::Util manpage, the Module::Pluggable::Ordered manpage


Module::Pluggable::Object - automatically give your module the ability to have plugins

  • AUTHOR
  • COPYING
  • BUGS
  • SEE ALSO

NAME

Module::Pluggable::Object - automatically give your module the ability to have plugins

SYNOPSIS

Simple use Module::Pluggable -

    package MyClass;
    use Module::Pluggable::Object;

    my $finder = Module::Pluggable::Object->new(%opts);
    print "My plugins are: ".join(", ", $finder->plugins)."\n";

DESCRIPTION

Provides a simple but, hopefully, extensible way of having 'plugins' for your module. Obviously this isn't going to be the be all and end all of solutions but it works for me.

Essentially all it does is export a method into your namespace that looks through a search path for .pm files and turn those into class names.

Optionally it instantiates those classes for you.

AUTHOR

Simon Wistow <simon@thegestalt.org>

COPYING

Copyright, 2006 Simon Wistow

Distributed under the same terms as Perl itself.

BUGS

None known.

SEE ALSO

the Module::Pluggable manpage


NEXT.pm - Provide a pseudo-class NEXT that allows method redispatch

    • Enforcing redispatch
    • Avoiding repetitions
    • Invoking all versions of a method with a single call
    • Using EVERY methods
  • AUTHOR
  • BUGS AND IRRITATIONS
  • COPYRIGHT

NAME

NEXT.pm - Provide a pseudo-class NEXT (et al) that allows method redispatch

SYNOPSIS

    use NEXT;

    package A;
    sub A::method   { print "$_[0]: A method\n";   $_[0]->NEXT::method() }
    sub A::DESTROY  { print "$_[0]: A dtor\n";     $_[0]->NEXT::DESTROY() }

    package B;
    use base qw( A );
    sub B::AUTOLOAD { print "$_[0]: B AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
    sub B::DESTROY  { print "$_[0]: B dtor\n";     $_[0]->NEXT::DESTROY() }

    package C;
    sub C::method   { print "$_[0]: C method\n";   $_[0]->NEXT::method() }
    sub C::AUTOLOAD { print "$_[0]: C AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
    sub C::DESTROY  { print "$_[0]: C dtor\n";     $_[0]->NEXT::DESTROY() }

    package D;
    use base qw( B C );
    sub D::method   { print "$_[0]: D method\n";   $_[0]->NEXT::method() }
    sub D::AUTOLOAD { print "$_[0]: D AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
    sub D::DESTROY  { print "$_[0]: D dtor\n";     $_[0]->NEXT::DESTROY() }

    package main;

    my $obj = bless {}, "D";

    $obj->method();             # Calls D::method, A::method, C::method
    $obj->missing_method(); # Calls D::AUTOLOAD, B::AUTOLOAD, C::AUTOLOAD

    # Clean-up calls D::DESTROY, B::DESTROY, A::DESTROY, C::DESTROY

DESCRIPTION

NEXT.pm adds a pseudoclass named NEXT to any program that uses it. If a method m calls $self->NEXT::m(), the call to m is redispatched as if the calling method had not originally been found.

In other words, a call to $self->NEXT::m() resumes the depth-first, left-to-right search of $self's class hierarchy that resulted in the original call to m.

Note that this is not the same thing as $self->SUPER::m(), which begins a new dispatch that is restricted to searching the ancestors of the current class. $self->NEXT::m() can backtrack past the current class -- to look for a suitable method in other ancestors of $self -- whereas $self->SUPER::m() cannot.

A typical use would be in the destructors of a class hierarchy, as illustrated in the synopsis above. Each class in the hierarchy has a DESTROY method that performs some class-specific action and then redispatches the call up the hierarchy. As a result, when an object of class D is destroyed, the destructors of all its parent classes are called (in depth-first, left-to-right order).

Another typical use of redispatch would be in AUTOLOAD'ed methods. If such a method determined that it was not able to handle a particular call, it might choose to redispatch that call, in the hope that some other AUTOLOAD (above it, or to its left) might do better.

By default, if a redispatch attempt fails to find another method elsewhere in the objects class hierarchy, it quietly gives up and does nothing (but see Enforcing redispatch). This gracious acquiesence is also unlike the (generally annoying) behaviour of SUPER, which throws an exception if it cannot redispatch.

Note that it is a fatal error for any method (including AUTOLOAD) to attempt to redispatch any method that does not have the same name. For example:

        sub D::oops { print "oops!\n"; $_[0]->NEXT::other_method() }

Enforcing redispatch

It is possible to make NEXT redispatch more demandingly (i.e. like SUPER does), so that the redispatch throws an exception if it cannot find a "next" method to call.

To do this, simple invoke the redispatch as:

        $self->NEXT::ACTUAL::method();

rather than:

        $self->NEXT::method();

The ACTUAL tells NEXT that there must actually be a next method to call, or it should throw an exception.

NEXT::ACTUAL is most commonly used in AUTOLOAD methods, as a means to decline an AUTOLOAD request, but preserve the normal exception-on-failure semantics:

        sub AUTOLOAD {
                if ($AUTOLOAD =~ /foo|bar/) {
                        # handle here
                }
                else {  # try elsewhere
                        shift()->NEXT::ACTUAL::AUTOLOAD(@_);
                }
        }

By using NEXT::ACTUAL, if there is no other AUTOLOAD to handle the method call, an exception will be thrown (as usually happens in the absence of a suitable AUTOLOAD).

Avoiding repetitions

If NEXT redispatching is used in the methods of a "diamond" class hierarchy:

        #     A   B
        #    / \ /
        #   C   D
        #    \ /
        #     E

        use NEXT;

        package A;
        sub foo { print "called A::foo\n"; shift->NEXT::foo() }

        package B;
        sub foo { print "called B::foo\n"; shift->NEXT::foo() }

        package C; @ISA = qw( A );
        sub foo { print "called C::foo\n"; shift->NEXT::foo() }

        package D; @ISA = qw(A B);
        sub foo { print "called D::foo\n"; shift->NEXT::foo() }

        package E; @ISA = qw(C D);
        sub foo { print "called E::foo\n"; shift->NEXT::foo() }

        E->foo();

then derived classes may (re-)inherit base-class methods through two or more distinct paths (e.g. in the way E inherits A::foo twice -- through C and D). In such cases, a sequence of NEXT redispatches will invoke the multiply inherited method as many times as it is inherited. For example, the above code prints:

        called E::foo
        called C::foo
        called A::foo
        called D::foo
        called A::foo
        called B::foo

(i.e. A::foo is called twice).

In some cases this may be the desired effect within a diamond hierarchy, but in others (e.g. for destructors) it may be more appropriate to call each method only once during a sequence of redispatches.

To cover such cases, you can redispatch methods via:

        $self->NEXT::DISTINCT::method();

rather than:

        $self->NEXT::method();

This causes the redispatcher to only visit each distinct method method once. That is, to skip any classes in the hierarchy that it has already visited during redispatch. So, for example, if the previous example were rewritten:

        package A;
        sub foo { print "called A::foo\n"; shift->NEXT::DISTINCT::foo() }

        package B;
        sub foo { print "called B::foo\n"; shift->NEXT::DISTINCT::foo() }

        package C; @ISA = qw( A );
        sub foo { print "called C::foo\n"; shift->NEXT::DISTINCT::foo() }

        package D; @ISA = qw(A B);
        sub foo { print "called D::foo\n"; shift->NEXT::DISTINCT::foo() }

        package E; @ISA = qw(C D);
        sub foo { print "called E::foo\n"; shift->NEXT::DISTINCT::foo() }

        E->foo();

then it would print:

        called E::foo
        called C::foo
        called A::foo
        called D::foo
        called B::foo

and omit the second call to A::foo (since it would not be distinct from the first call to A::foo).

Note that you can also use:

        $self->NEXT::DISTINCT::ACTUAL::method();

or:

        $self->NEXT::ACTUAL::DISTINCT::method();

to get both unique invocation and exception-on-failure.

Note that, for historical compatibility, you can also use NEXT::UNSEEN instead of NEXT::DISTINCT.

Invoking all versions of a method with a single call

Yet another pseudo-class that NEXT.pm provides is EVERY. Its behaviour is considerably simpler than that of the NEXT family. A call to:

        $obj->EVERY::foo();

calls every method named foo that the object in $obj has inherited. That is:

        use NEXT;

        package A; @ISA = qw(B D X);
        sub foo { print "A::foo " }

        package B; @ISA = qw(D X);
        sub foo { print "B::foo " }

        package X; @ISA = qw(D);
        sub foo { print "X::foo " }

        package D;
        sub foo { print "D::foo " }

        package main;

        my $obj = bless {}, 'A';
        $obj->EVERY::foo();        # prints" A::foo B::foo X::foo D::foo

Prefixing a method call with EVERY:: causes every method in the object's hierarchy with that name to be invoked. As the above example illustrates, they are not called in Perl's usual "left-most-depth-first" order. Instead, they are called "breadth-first-dependency-wise".

That means that the inheritance tree of the object is traversed breadth-first and the resulting order of classes is used as the sequence in which methods are called. However, that sequence is modified by imposing a rule that the appropritae method of a derived class must be called before the same method of any ancestral class. That's why, in the above example, X::foo is called before D::foo, even though D comes before X in @B::ISA.

In general, there's no need to worry about the order of calls. They will be left-to-right, breadth-first, most-derived-first. This works perfectly for most inherited methods (including destructors), but is inappropriate for some kinds of methods (such as constructors, cloners, debuggers, and initializers) where it's more appropriate that the least-derived methods be called first (as more-derived methods may rely on the behaviour of their "ancestors"). In that case, instead of using the EVERY pseudo-class:

        $obj->EVERY::foo();        # prints" A::foo B::foo X::foo D::foo

you can use the EVERY::LAST pseudo-class:

        $obj->EVERY::LAST::foo();  # prints" D::foo X::foo B::foo A::foo

which reverses the order of method call.

Whichever version is used, the actual methods are called in the same context (list, scalar, or void) as the original call via EVERY, and return:

  • A hash of array references in list context. Each entry of the hash has the fully qualified method name as its key and a reference to an array containing the method's list-context return values as its value.

  • A reference to a hash of scalar values in scalar context. Each entry of the hash has the fully qualified method name as its key and the method's scalar-context return values as its value.

  • Nothing in void context (obviously).

Using EVERY methods

The typical way to use an EVERY call is to wrap it in another base method, that all classes inherit. For example, to ensure that every destructor an object inherits is actually called (as opposed to just the left-most-depth-first-est one):

        package Base;
        sub DESTROY { $_[0]->EVERY::Destroy }

        package Derived1;
        use base 'Base';
        sub Destroy {...}

        package Derived2;
        use base 'Base', 'Derived1';
        sub Destroy {...}

et cetera. Every derived class than needs its own clean-up behaviour simply adds its own Destroy method (not a DESTROY method), which the call to EVERY::LAST::Destroy in the inherited destructor then correctly picks up.

Likewise, to create a class hierarchy in which every initializer inherited by a new object is invoked:

        package Base;
        sub new {
                my ($class, %args) = @_;
                my $obj = bless {}, $class;
                $obj->EVERY::LAST::Init(\%args);
        }

        package Derived1;
        use base 'Base';
        sub Init {
                my ($argsref) = @_;
                ...
        }

        package Derived2;
        use base 'Base', 'Derived1';
        sub Init {
                my ($argsref) = @_;
                ...
        }

et cetera. Every derived class than needs some additional initialization behaviour simply adds its own Init method (not a new method), which the call to EVERY::LAST::Init in the inherited constructor then correctly picks up.

AUTHOR

Damian Conway (damian@conway.org)

BUGS AND IRRITATIONS

Because it's a module, not an integral part of the interpreter, NEXT.pm has to guess where the surrounding call was found in the method look-up sequence. In the presence of diamond inheritance patterns it occasionally guesses wrong.

It's also too slow (despite caching).

Comment, suggestions, and patches welcome.

COPYRIGHT

 Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
 This module is free software. It may be used, redistributed
    and/or modified under the same terms as Perl itself.


Net::Cmd - Network Command class

  • USER METHODS
  • CLASS METHODS
  • EXPORTS
  • AUTHOR
  • COPYRIGHT

NAME

Net::Cmd - Network Command class (as used by FTP, SMTP etc)

SYNOPSIS

    use Net::Cmd;

    @ISA = qw(Net::Cmd);

DESCRIPTION

Net::Cmd is a collection of methods that can be inherited by a sub class of IO::Handle. These methods implement the functionality required for a command based protocol, for example FTP and SMTP.

USER METHODS

These methods provide a user interface to the Net::Cmd object.

debug ( VALUE )

Set the level of debug information for this object. If VALUE is not given then the current state is returned. Otherwise the state is changed to VALUE and the previous state returned.

Different packages may implement different levels of debug but a non-zero value results in copies of all commands and responses also being sent to STDERR.

If VALUE is undef then the debug level will be set to the default debug level for the class.

This method can also be called as a static method to set/get the default debug level for a given class.

message ()

Returns the text message returned from the last command

code ()

Returns the 3-digit code from the last command. If a command is pending then the value 0 is returned

ok ()

Returns non-zero if the last code value was greater than zero and less than 400. This holds true for most command servers. Servers where this does not hold may override this method.

status ()

Returns the most significant digit of the current status code. If a command is pending then CMD_PENDING is returned.

datasend ( DATA )

Send data to the remote server, converting LF to CRLF. Any line starting with a '.' will be prefixed with another '.'. DATA may be an array or a reference to an array.

dataend ()

End the sending of data to the remote server. This is done by ensuring that the data already sent ends with CRLF then sending '.CRLF' to end the transmission. Once this data has been sent dataend calls response and returns true if response returns CMD_OK.

CLASS METHODS

These methods are not intended to be called by the user, but used or over-ridden by a sub-class of Net::Cmd

debug_print ( DIR, TEXT )

Print debugging information. DIR denotes the direction true being data being sent to the server. Calls debug_text before printing to STDERR.

debug_text ( TEXT )

This method is called to print debugging information. TEXT is the text being sent. The method should return the text to be printed

This is primarily meant for the use of modules such as FTP where passwords are sent, but we do not want to display them in the debugging information.

command ( CMD [, ARGS, ... ])

Send a command to the command server. All arguments a first joined with a space character and CRLF is appended, this string is then sent to the command server.

Returns undef upon failure

unsupported ()

Sets the status code to 580 and the response text to 'Unsupported command'. Returns zero.

response ()

Obtain a response from the server. Upon success the most significant digit of the status code is returned. Upon failure, timeout etc., undef is returned.

parse_response ( TEXT )

This method is called by response as a method with one argument. It should return an array of 2 values, the 3-digit status code and a flag which is true when this is part of a multi-line response and this line is not the list.

getline ()

Retrieve one line, delimited by CRLF, from the remote server. Returns undef upon failure.

NOTE: If you do use this method for any reason, please remember to add some debug_print calls into your method.

ungetline ( TEXT )

Unget a line of text from the server.

rawdatasend ( DATA )

Send data to the remote server without performing any conversions. DATA is a scalar.

read_until_dot ()

Read data from the remote server until a line consisting of a single '.'. Any lines starting with '..' will have one of the '.'s removed.

Returns a reference to a list containing the lines, or undef upon failure.

tied_fh ()

Returns a filehandle tied to the Net::Cmd object. After issuing a command, you may read from this filehandle using read() or <>. The filehandle will return EOF when the final dot is encountered. Similarly, you may write to the filehandle in order to send data to the server after issuing a commmand that expects data to be written.

See the Net::POP3 and Net::SMTP modules for examples of this.

EXPORTS

Net::Cmd exports six subroutines, five of these, CMD_INFO, CMD_OK, CMD_MORE, CMD_REJECT and CMD_ERROR, correspond to possible results of response and status. The sixth is CMD_PENDING.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id: //depot/libnet/Net/Cmd.pm#34 $


Net::Config - Local configuration data for libnet

  • SYNOPSYS
  • DESCRIPTION
  • METHODS
  • NetConfig VALUES

NAME

Net::Config - Local configuration data for libnet

SYNOPSYS

    use Net::Config qw(%NetConfig);

DESCRIPTION

Net::Config holds configuration data for the modules in the libnet distribuion. During installation you will be asked for these values.

The configuration data is held globally in a file in the perl installation tree, but a user may override any of these values by providing their own. This can be done by having a .libnetrc file in their home directory. This file should return a reference to a HASH containing the keys described below. For example

    # .libnetrc
    {
        nntp_hosts => [ "my_prefered_host" ],
        ph_hosts   => [ "my_ph_server" ],
    }
    __END__

METHODS

Net::Config defines the following methods. They are methods as they are invoked as class methods. This is because Net::Config inherits from Net::LocalCfg so you can override these methods if you want.

requires_firewall HOST

Attempts to determine if a given host is outside your firewall. Possible return values are.

  -1  Cannot lookup hostname
   0  Host is inside firewall (or there is no ftp_firewall entry)
   1  Host is outside the firewall

This is done by using hostname lookup and the local_netmask entry in the configuration data.

NetConfig VALUES

nntp_hosts
snpp_hosts
pop3_hosts
smtp_hosts
ph_hosts
daytime_hosts
time_hosts

Each is a reference to an array of hostnames (in order of preference), which should be used for the given protocol

inet_domain

Your internet domain name

ftp_firewall

If you have an FTP proxy firewall (NOT an HTTP or SOCKS firewall) then this value should be set to the firewall hostname. If your firewall does not listen to port 21, then this value should be set to "hostname:port" (eg "hostname:99")

ftp_firewall_type

There are many different ftp firewall products available. But unfortunately there is no standard for how to traverse a firewall. The list below shows the sequence of commands that Net::FTP will use

  user        Username for remote host
  pass        Password for remote host
  fwuser      Username for firewall
  fwpass      Password for firewall
  remote.host The hostname of the remote ftp server

  1. There is no firewall

  2.      USER user@remote.host
     PASS pass
  3.      USER fwuser
     PASS fwpass
     USER user@remote.host
     PASS pass
  4.      USER fwuser
     PASS fwpass
     SITE remote.site
     USER user
     PASS pass
  5.      USER fwuser
     PASS fwpass
     OPEN remote.site
     USER user
     PASS pass
  6.      USER user@fwuser@remote.site
     PASS pass@fwpass
  7.      USER fwuser@remote.site
     PASS fwpass
     USER user
     PASS pass
  8.      USER user@remote.host
     PASS pass
     AUTH fwuser
     RESP fwpass
ftp_ext_passive
ftp_int_pasive

FTP servers can work in passive or active mode. Active mode is when you want to transfer data you have to tell the server the address and port to connect to. Passive mode is when the server provide the address and port and you establish the connection.

With some firewalls active mode does not work as the server cannot connect to your machine (because you are behind a firewall) and the firewall does not re-write the command. In this case you should set ftp_ext_passive to a true value.

Some servers are configured to only work in passive mode. If you have one of these you can force Net::FTP to always transfer in passive mode; when not going via a firewall, by setting ftp_int_passive to a true value.

local_netmask

A reference to a list of netmask strings in the form "134.99.4.0/24". These are used by the requires_firewall function to determine if a given host is inside or outside your firewall.

The following entries are used during installation & testing on the libnet package

test_hosts

If true then make test may attempt to connect to hosts given in the configuration.

test_exists

If true then Configure will check each hostname given that it exists

$Id: //depot/libnet/Net/Config.pm#17 $


Net::Domain - Attempt to evaluate the current host's internet name and domain

  • AUTHOR
  • COPYRIGHT

NAME

Net::Domain - Attempt to evaluate the current host's internet name and domain

SYNOPSIS

    use Net::Domain qw(hostname hostfqdn hostdomain);

DESCRIPTION

Using various methods attempt to find the Fully Qualified Domain Name (FQDN) of the current host. From this determine the host-name and the host-domain.

Each of the functions will return undef if the FQDN cannot be determined.

hostfqdn ()

Identify and return the FQDN of the current host.

hostname ()

Returns the smallest part of the FQDN which can be used to identify the host.

hostdomain ()

Returns the remainder of the FQDN after the hostname has been removed.

AUTHOR

Graham Barr <gbarr@pobox.com>. Adapted from Sys::Hostname by David Sundstrom <sunds@asictest.sc.ti.com>

COPYRIGHT

Copyright (c) 1995-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id: //depot/libnet/Net/Domain.pm#21 $


Net::FTP - FTP Client class

  • OVERVIEW
  • CONSTRUCTOR
  • METHODS
    • Methods for the adventurous
  • THE dataconn CLASS
  • UNIMPLEMENTED
  • REPORTING BUGS
  • AUTHOR
  • SEE ALSO
  • USE EXAMPLES
  • CREDITS
  • COPYRIGHT

NAME

Net::FTP - FTP Client class

SYNOPSIS

    use Net::FTP;

    $ftp = Net::FTP->new("some.host.name", Debug => 0)
      or die "Cannot connect to some.host.name: $@";

    $ftp->login("anonymous",'-anonymous@')
      or die "Cannot login ", $ftp->message;

    $ftp->cwd("/pub")
      or die "Cannot change working directory ", $ftp->message;

    $ftp->get("that.file")
      or die "get failed ", $ftp->message;

    $ftp->quit;

DESCRIPTION

Net::FTP is a class implementing a simple FTP client in Perl as described in RFC959. It provides wrappers for a subset of the RFC959 commands.

OVERVIEW

FTP stands for File Transfer Protocol. It is a way of transferring files between networked machines. The protocol defines a client (whose commands are provided by this module) and a server (not implemented in this module). Communication is always initiated by the client, and the server responds with a message and a status code (and sometimes with data).

The FTP protocol allows files to be sent to or fetched from the server. Each transfer involves a local file (on the client) and a remote file (on the server). In this module, the same file name will be used for both local and remote if only one is specified. This means that transferring remote file /path/to/file will try to put that file in /path/to/file locally, unless you specify a local file name.

The protocol also defines several standard translations which the file can undergo during transfer. These are ASCII, EBCDIC, binary, and byte. ASCII is the default type, and indicates that the sender of files will translate the ends of lines to a standard representation which the receiver will then translate back into their local representation. EBCDIC indicates the file being transferred is in EBCDIC format. Binary (also known as image) format sends the data as a contiguous bit stream. Byte format transfers the data as bytes, the values of which remain the same regardless of differences in byte size between the two machines (in theory - in practice you should only use this if you really know what you're doing).

CONSTRUCTOR

new ([ HOST ] [, OPTIONS ])

This is the constructor for a new Net::FTP object. HOST is the name of the remote host to which an FTP connection is required.

HOST is optional. If HOST is not given then it may instead be passed as the Host option described below.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - FTP host to connect to. It may be a single scalar, as defined for the PeerAddr option in the IO::Socket::INET manpage, or a reference to an array with hosts to try in turn. The host method will return the value which was used to connect to the host.

Firewall - The name of a machine which acts as an FTP firewall. This can be overridden by an environment variable FTP_FIREWALL. If specified, and the given host cannot be directly connected to, then the connection is made to the firewall machine and the string @hostname is appended to the login identifier. This kind of setup is also refered to as an ftp proxy.

FirewallType - The type of firewall running on the machine indicated by Firewall. This can be overridden by an environment variable FTP_FIREWALL_TYPE. For a list of permissible types, see the description of ftp_firewall_type in the Net::Config manpage.

BlockSize - This is the block size that Net::FTP will use when doing transfers. (defaults to 10240)

Port - The port number to connect to on the remote machine for the FTP connection

Timeout - Set a timeout value (defaults to 120)

Debug - debug level (see the debug method in the Net::Cmd manpage)

Passive - If set to a non-zero value then all data transfers will be done using passive mode. If set to zero then data transfers will be done using active mode. If the machine is connected to the Internet directly, both passive and active mode should work equally well. Behind most firewall and NAT configurations passive mode has a better chance of working. However, in some rare firewall configurations, active mode actually works when passive mode doesn't. Some really old FTP servers might not implement passive transfers. If not specified, then the transfer mode is set by the environment variable FTP_PASSIVE or if that one is not set by the settings done by the libnetcfg utility. If none of these apply then passive mode is used.

Hash - If given a reference to a file handle (e.g., \*STDERR), print hash marks (#) on that filehandle every 1024 bytes. This simply invokes the hash() method for you, so that hash marks are displayed for all transfers. You can, of course, call hash() explicitly whenever you'd like.

LocalAddr - Local address to use for all socket connections, this argument will be passed to the IO::Socket::INET manpage

If the constructor fails undef will be returned and an error message will be in $@

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])

Log into the remote FTP server with the given login information. If no arguments are given then the Net::FTP uses the Net::Netrc package to lookup the login information for the connected host. If no information is found then a login of anonymous is used. If no password is given and the login is anonymous then anonymous@ will be used for password.

If the connection is via a firewall then the authorize method will be called with no arguments.

authorize ( [AUTH [, RESP]])

This is a protocol used by some firewall ftp proxies. It is used to authorise the user to send data out. If both arguments are not specified then authorize uses Net::Netrc to do a lookup.

site (ARGS)

Send a SITE command to the remote server and wait for a response.

Returns most significant digit of the response code.

ascii

Transfer file in ASCII. CRLF translation will be done if required

binary

Transfer file in binary mode. No transformation will be done.

Hint: If both server and client machines use the same line ending for text files, then it will be faster to transfer all files in binary mode.

rename ( OLDNAME, NEWNAME )

Rename a file on the remote FTP server from OLDNAME to NEWNAME. This is done by sending the RNFR and RNTO commands.

delete ( FILENAME )

Send a request to the server to delete FILENAME.

cwd ( [ DIR ] )

Attempt to change directory to the directory given in $dir. If $dir is "..", the FTP CDUP command is used to attempt to move up one directory. If no directory is given then an attempt is made to change the directory to the root directory.

cdup ()

Change directory to the parent of the current directory.

pwd ()

Returns the full pathname of the current directory.

restart ( WHERE )

Set the byte offset at which to begin the next data transfer. Net::FTP simply records this value and uses it when during the next data transfer. For this reason this method will not return an error, but setting it may cause a subsequent data transfer to fail.

rmdir ( DIR [, RECURSE ])

Remove the directory with the name DIR. If RECURSE is true then rmdir will attempt to delete everything inside the directory.

mkdir ( DIR [, RECURSE ])

Create a new directory with the name DIR. If RECURSE is true then mkdir will attempt to create all the directories in the given path.

Returns the full pathname to the new directory.

alloc ( SIZE [, RECORD_SIZE] )

The alloc command allows you to give the ftp server a hint about the size of the file about to be transfered using the ALLO ftp command. Some storage systems use this to make intelligent decisions about how to store the file. The SIZE argument represents the size of the file in bytes. The RECORD_SIZE argument indicates a mazimum record or page size for files sent with a record or page structure.

The size of the file will be determined, and sent to the server automatically for normal files so that this method need only be called if you are transfering data from a socket, named pipe, or other stream not associated with a normal file.

ls ( [ DIR ] )

Get a directory listing of DIR, or the current directory.

In an array context, returns a list of lines returned from the server. In a scalar context, returns a reference to a list.

dir ( [ DIR ] )

Get a directory listing of DIR, or the current directory in long format.

In an array context, returns a list of lines returned from the server. In a scalar context, returns a reference to a list.

get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )

Get REMOTE_FILE from the server and store locally. LOCAL_FILE may be a filename or a filehandle. If not specified, the file will be stored in the current directory with the same leafname as the remote file.

If WHERE is given then the first WHERE bytes of the file will not be transfered, and the remaining bytes will be appended to the local file if it already exists.

Returns LOCAL_FILE, or the generated local file name if LOCAL_FILE is not given. If an error was encountered undef is returned.

put ( LOCAL_FILE [, REMOTE_FILE ] )

Put a file on the remote server. LOCAL_FILE may be a name or a filehandle. If LOCAL_FILE is a filehandle then REMOTE_FILE must be specified. If REMOTE_FILE is not specified then the file will be stored in the current directory with the same leafname as LOCAL_FILE.

Returns REMOTE_FILE, or the generated remote filename if REMOTE_FILE is not given.

NOTE: If for some reason the transfer does not complete and an error is returned then the contents that had been transfered will not be remove automatically.

put_unique ( LOCAL_FILE [, REMOTE_FILE ] )

Same as put but uses the STOU command.

Returns the name of the file on the server.

append ( LOCAL_FILE [, REMOTE_FILE ] )

Same as put but appends to the file on the remote server.

Returns REMOTE_FILE, or the generated remote filename if REMOTE_FILE is not given.

unique_name ()

Returns the name of the last file stored on the server using the STOU command.

mdtm ( FILE )

Returns the modification time of the given file

size ( FILE )

Returns the size in bytes for the given file as stored on the remote server.

NOTE: The size reported is the size of the stored file on the remote server. If the file is subsequently transfered from the server in ASCII mode and the remote server and local machine have different ideas about "End Of Line" then the size of file on the local machine after transfer may be different.

supported ( CMD )

Returns TRUE if the remote server supports the given command.

hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )

Called without parameters, or with the first argument false, hash marks are suppressed. If the first argument is true but not a reference to a file handle glob, then \*STDERR is used. The second argument is the number of bytes per hash mark printed, and defaults to 1024. In all cases the return value is a reference to an array of two: the filehandle glob reference and the bytes per hash mark.

The following methods can return different results depending on how they are called. If the user explicitly calls either of the pasv or port methods then these methods will return a true or false value. If the user does not call either of these methods then the result will be a reference to a Net::FTP::dataconn based object.

nlst ( [ DIR ] )

Send an NLST command to the server, with an optional parameter.

list ( [ DIR ] )

Same as nlst but using the LIST command

retr ( FILE )

Begin the retrieval of a file called FILE from the remote server.

stor ( FILE )

Tell the server that you wish to store a file. FILE is the name of the new file that should be created.

stou ( FILE )

Same as stor but using the STOU command. The name of the unique file which was created on the server will be available via the unique_name method after the data connection has been closed.

appe ( FILE )

Tell the server that we want to append some data to the end of a file called FILE. If this file does not exist then create it.

If for some reason you want to have complete control over the data connection, this includes generating it and calling the response method when required, then the user can use these methods to do so.

However calling these methods only affects the use of the methods above that can return a data connection. They have no effect on methods get, put, put_unique and those that do not require data connections.

port ( [ PORT ] )

Send a PORT command to the server. If PORT is specified then it is sent to the server. If not, then a listen socket is created and the correct information sent to the server.

pasv ()

Tell the server to go into passive mode. Returns the text that represents the port on which the server is listening, this text is in a suitable form to sent to another ftp server using the port method.

The following methods can be used to transfer files between two remote servers, providing that these two servers can connect directly to each other.

pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )

This method will do a file transfer between two remote ftp servers. If DEST_FILE is omitted then the leaf name of SRC_FILE will be used.

pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )

Like pasv_xfer but the file is stored on the remote server using the STOU command.

pasv_wait ( NON_PASV_SERVER )

This method can be used to wait for a transfer to complete between a passive server and a non-passive server. The method should be called on the passive server with the Net::FTP object for the non-passive server passed as an argument.

abort ()

Abort the current data transfer.

quit ()

Send the QUIT command to the remote FTP server and close the socket connection.

Methods for the adventurous

Net::FTP inherits from Net::Cmd so methods defined in Net::Cmd may be used to send commands to the remote FTP server.

quot (CMD [,ARGS])

Send a command, that Net::FTP does not directly support, to the remote server and wait for a response.

Returns most significant digit of the response code.

WARNING This call should only be used on commands that do not require data connections. Misuse of this method can hang the connection.

THE dataconn CLASS

Some of the methods defined in Net::FTP return an object which will be derived from this class.The dataconn class itself is derived from the IO::Socket::INET class, so any normal IO operations can be performed. However the following methods are defined in the dataconn class and IO should be performed using these.

read ( BUFFER, SIZE [, TIMEOUT ] )

Read SIZE bytes of data from the server and place it into BUFFER, also performing any <CRLF> translation necessary. TIMEOUT is optional, if not given, the timeout value from the command connection will be used.

Returns the number of bytes read before any <CRLF> translation.

write ( BUFFER, SIZE [, TIMEOUT ] )

Write SIZE bytes of data from BUFFER to the server, also performing any <CRLF> translation necessary. TIMEOUT is optional, if not given, the timeout value from the command connection will be used.

Returns the number of bytes written before any <CRLF> translation.

bytes_read ()

Returns the number of bytes read so far.

abort ()

Abort the current data transfer.

close ()

Close the data connection and get a response from the FTP server. Returns true if the connection was closed successfully and the first digit of the response from the server was a '2'.

UNIMPLEMENTED

The following RFC959 commands have not been implemented:

SMNT

Mount a different file system structure without changing login or accounting information.

HELP

Ask the server for "helpful information" (that's what the RFC says) on the commands it accepts.

MODE

Specifies transfer mode (stream, block or compressed) for file to be transferred.

SYST

Request remote server system identification.

STAT

Request remote server status.

STRU

Specifies file structure for file to be transferred.

REIN

Reinitialize the connection, flushing all I/O and account information.

REPORTING BUGS

When reporting bugs/problems please include as much information as possible. It may be difficult for me to reproduce the problem as almost every setup is different.

A small script which yields the problem will probably be of help. It would also be useful if this script was run with the extra options Debug = 1> passed to the constructor, and the output sent with the bug report. If you cannot include a small script then please include a Debug trace from a run of your program which does yield the problem.

AUTHOR

Graham Barr <gbarr@pobox.com>

SEE ALSO

the Net::Netrc manpage the Net::Cmd manpage

ftp(1), ftpd(8), RFC 959 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html

USE EXAMPLES

For an example of the use of Net::FTP see

http://www.csh.rit.edu/~adam/Progs/

autoftp is a program that can retrieve, send, or list files via the FTP protocol in a non-interactive manner.

CREDITS

Henry Gabryjelski <henryg@WPI.EDU> - for the suggestion of creating directories recursively.

Nathan Torkington <gnat@frii.com> - for some input on the documentation.

Roderick Schertler <roderick@gate.net> - for various inputs

COPYRIGHT

Copyright (c) 1995-2004 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::HTTP - Low-level HTTP connection

  • SUBCLASSING
  • SEE ALSO
  • COPYRIGHT

NAME

Net::HTTP - Low-level HTTP connection (client)

SYNOPSIS

 use Net::HTTP;
 my $s = Net::HTTP->new(Host => "www.perl.com") || die $@;
 $s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
 my($code, $mess, %h) = $s->read_response_headers;

 while (1) {
    my $buf;
    my $n = $s->read_entity_body($buf, 1024);
    die "read failed: $!" unless defined $n;
    last unless $n;
    print $buf;
 }

DESCRIPTION

The Net::HTTP class is a low-level HTTP client. An instance of the Net::HTTP class represents a connection to an HTTP server. The HTTP protocol is described in RFC 2616. The Net::HTTP class support HTTP/1.0 and HTTP/1.1.

Net::HTTP is a sub-class of IO::Socket::INET. You can mix the methods described below with reading and writing from the socket directly. This is not necessary a good idea, unless you know what you are doing.

The following methods are provided (in addition to those of IO::Socket::INET):

$s = Net::HTTP->new( %options )

The Net::HTTP constructor method takes the same options as IO::Socket::INET's as well as these:

  Host:            Initial host attribute value
  KeepAlive:       Initial keep_alive attribute value
  SendTE:          Initial send_te attribute_value
  HTTPVersion:     Initial http_version attribute value
  PeerHTTPVersion: Initial peer_http_version attribute value
  MaxLineLength:   Initial max_line_length attribute value
  MaxHeaderLines:  Initial max_header_lines attribute value

The Host option is also the default for IO::Socket::INET's PeerAddr. The PeerPort defaults to 80 if not provided.

The Listen option provided by IO::Socket::INET's constructor method is not allowed.

If unable to connect to the given HTTP server then the constructor returns undef and $@ contains the reason. After a successful connect, a Net:HTTP object is returned.

$s->host

Get/set the default value of the Host header to send. The $host must not be set to an empty string (or undef) for HTTP/1.1.

$s->keep_alive

Get/set the keep-alive value. If this value is TRUE then the request will be sent with headers indicating that the server should try to keep the connection open so that multiple requests can be sent.

The actual headers set will depend on the value of the http_version and peer_http_version attributes.

$s->send_te

Get/set the a value indicating if the request will be sent with a "TE" header to indicate the transfer encodings that the server can choose to use. If the Compress::Zlib module is installed then this will announce that this client accept both the deflate and gzip encodings.

$s->http_version

Get/set the HTTP version number that this client should announce. This value can only be set to "1.0" or "1.1". The default is "1.1".

$s->peer_http_version

Get/set the protocol version number of our peer. This value will initially be "1.0", but will be updated by a successful read_response_headers() method call.

$s->max_line_length

Get/set a limit on the length of response line and response header lines. The default is 4096. A value of 0 means no limit.

$s->max_header_length

Get/set a limit on the number of headers lines that a response can have. The default is 128. A value of 0 means no limit.

$s->format_request($method, $uri, %headers, [$content])

Format a request message and return it as a string. If the headers do not include a Host header, then a header is inserted with the value of the host attribute. Headers like Connection and Keep-Alive might also be added depending on the status of the keep_alive attribute.

If $content is given (and it is non-empty), then a Content-Length header is automatically added unless it was already present.

$s->write_request($method, $uri, %headers, [$content])

Format and send a request message. Arguments are the same as for format_request(). Returns true if successful.

$s->format_chunk( $data )

Returns the string to be written for the given chunk of data.

$s->write_chunk($data)

Will write a new chunk of request entity body data. This method should only be used if the Transfer-Encoding header with a value of chunked was sent in the request. Note, writing zero-length data is a no-op. Use the write_chunk_eof() method to signal end of entity body data.

Returns true if successful.

$s->format_chunk_eof( %trailers )

Returns the string to be written for signaling EOF when a Transfer-Encoding of chunked is used.

$s->write_chunk_eof( %trailers )

Will write eof marker for chunked data and optional trailers. Note that trailers should not really be used unless is was signaled with a Trailer header.

Returns true if successful.

($code, $mess, %headers) = $s->read_response_headers( %opts )

Read response headers from server and return it. The $code is the 3 digit HTTP status code (see the HTTP::Status manpage) and $mess is the textual message that came with it. Headers are then returned as key/value pairs. Since key letter casing is not normalized and the same key can even occur multiple times, assigning these values directly to a hash is not wise. Only the $code is returned if this method is called in scalar context.

As a side effect this method updates the 'peer_http_version' attribute.

Options might be passed in as key/value pairs. There are currently only two options supported; laxed and junk_out.

The laxed option will make read_response_headers() more forgiving towards servers that have not learned how to speak HTTP properly. The laxed option is a boolean flag, and is enabled by passing in a TRUE value. The junk_out option can be used to capture bad header lines when laxed is enabled. The value should be an array reference. Bad header lines will be pushed onto the array.

The laxed option must be specified in order to communicate with pre-HTTP/1.0 servers that don't describe the response outcome or the data they send back with a header block. For these servers peer_http_version is set to "0.9" and this method returns (200, "Assumed OK").

The method will raise an exception (die) if the server does not speak proper HTTP or if the max_line_length or max_header_length limits are reached. If the laxed option is turned on and max_line_length and max_header_length checks are turned off, then no exception will be raised and this method will always return a response code.

$n = $s->read_entity_body($buf, $size);

Reads chunks of the entity body content. Basically the same interface as for read() and sysread(), but the buffer offset argument is not supported yet. This method should only be called after a successful read_response_headers() call.

The return value will be undef on read errors, 0 on EOF, -1 if no data could be returned this time, otherwise the number of bytes assigned to $buf. The $buf set to "" when the return value is -1.

This method will raise exceptions (die) if the server does not speak proper HTTP. This can only happen when reading chunked data.

%headers = $s->get_trailers

After read_entity_body() has returned 0 to indicate end of the entity body, you might call this method to pick up any trailers.

$s->_rbuf

Get/set the read buffer content. The read_response_headers() and read_entity_body() methods use an internal buffer which they will look for data before they actually sysread more from the socket itself. If they read too much, the remaining data will be left in this buffer.

$s->_rbuf_length

Returns the number of bytes in the read buffer. This should always be the same as:

    length($s->_rbuf)

but might be more efficient.

SUBCLASSING

The read_response_headers() and read_entity_body() will invoke the sysread() method when they need more data. Subclasses might want to override this method to control how reading takes place.

The object itself is a glob. Subclasses should avoid using hash key names prefixed with http_ and io_.

SEE ALSO

the LWP manpage, the IO::Socket::INET manpage, the Net::HTTP::NB manpage

COPYRIGHT

Copyright 2001-2003 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::HTTP::NB - Non-blocking HTTP client

  • SEE ALSO
  • COPYRIGHT

NAME

Net::HTTP::NB - Non-blocking HTTP client

SYNOPSIS

 use Net::HTTP::NB;
 my $s = Net::HTTP::NB->new(Host => "www.perl.com") || die $@;
 $s->write_request(GET => "/");

 use IO::Select;
 my $sel = IO::Select->new($s);

 READ_HEADER: {
    die "Header timeout" unless $sel->can_read(10);
    my($code, $mess, %h) = $s->read_response_headers;
    redo READ_HEADER unless $code;
 }

 while (1) {
    die "Body timeout" unless $sel->can_read(10);
    my $buf;
    my $n = $s->read_entity_body($buf, 1024);
    last unless $n;
    print $buf;
 }

DESCRIPTION

Same interface as Net::HTTP but it will never try multiple reads when the read_response_headers() or read_entity_body() methods are invoked. This make it possible to multiplex multiple Net::HTTP::NB using select without risk blocking.

If read_response_headers() did not see enough data to complete the headers an empty list is returned.

If read_entity_body() did not see new entity data in its read the value -1 is returned.

SEE ALSO

the Net::HTTP manpage

COPYRIGHT

Copyright 2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::NNTP - NNTP Client class

  • CONSTRUCTOR
  • METHODS
    • Extension methods
  • UNSUPPORTED
  • DEFINITIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Net::NNTP - NNTP Client class

SYNOPSIS

    use Net::NNTP;

    $nntp = Net::NNTP->new("some.host.name");
    $nntp->quit;

DESCRIPTION

Net::NNTP is a class implementing a simple NNTP client in Perl as described in RFC977. Net::NNTP inherits its communication methods from Net::Cmd

CONSTRUCTOR

new ( [ HOST ] [, OPTIONS ])

This is the constructor for a new Net::NNTP object. HOST is the name of the remote host to which a NNTP connection is required. If not given then it may be passed as the Host option described below. If no host is passed then two environment variables are checked, first NNTPSERVER then NEWSHOST, then Net::Config is checked, and if a host is not found then news is used.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - NNTP host to connect to. It may be a single scalar, as defined for the PeerAddr option in the IO::Socket::INET manpage, or a reference to an array with hosts to try in turn. The host method will return the value which was used to connect to the host.

Timeout - Maximum time, in seconds, to wait for a response from the NNTP server, a value of zero will cause all IO operations to block. (default: 120)

Debug - Enable the printing of debugging information to STDERR

Reader - If the remote server is INN then initially the connection will be to nnrpd, by default Net::NNTP will issue a MODE READER command so that the remote server becomes innd. If the Reader option is given with a value of zero, then this command will not be sent and the connection will be left talking to nnrpd.

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

article ( [ MSGID|MSGNUM ], [FH] )

Retrieve the header, a blank line, then the body (text) of the specified article.

If FH is specified then it is expected to be a valid filehandle and the result will be printed to it, on success a true value will be returned. If FH is not specified then the return value, on success, will be a reference to an array containg the article requested, each entry in the array will contain one line of the article.

If no arguments are passed then the current article in the currently selected newsgroup is fetched.

MSGNUM is a numeric id of an article in the current newsgroup, and will change the current article pointer. MSGID is the message id of an article as shown in that article's header. It is anticipated that the client will obtain the MSGID from a list provided by the newnews command, from references contained within another article, or from the message-id provided in the response to some other commands.

If there is an error then undef will be returned.

body ( [ MSGID|MSGNUM ], [FH] )

Like article but only fetches the body of the article.

head ( [ MSGID|MSGNUM ], [FH] )

Like article but only fetches the headers for the article.

articlefh ( [ MSGID|MSGNUM ] )
bodyfh ( [ MSGID|MSGNUM ] )
headfh ( [ MSGID|MSGNUM ] )

These are similar to article(), body() and head(), but rather than returning the requested data directly, they return a tied filehandle from which to read the article.

nntpstat ( [ MSGID|MSGNUM ] )

The nntpstat command is similar to the article command except that no text is returned. When selecting by message number within a group, the nntpstat command serves to set the "current article pointer" without sending text.

Using the nntpstat command to select by message-id is valid but of questionable value, since a selection by message-id does not alter the "current article pointer".

Returns the message-id of the "current article".

group ( [ GROUP ] )

Set and/or get the current group. If GROUP is not given then information is returned on the current group.

In a scalar context it returns the group name.

In an array context the return value is a list containing, the number of articles in the group, the number of the first article, the number of the last article and the group name.

ihave ( MSGID [, MESSAGE ])

The ihave command informs the server that the client has an article whose id is MSGID. If the server desires a copy of that article, and MESSAGE has been given the it will be sent.

Returns true if the server desires the article and MESSAGE was successfully sent,if specified.

If MESSAGE is not specified then the message must be sent using the datasend and dataend methods from the Net::Cmd manpage

MESSAGE can be either an array of lines or a reference to an array.

last ()

Set the "current article pointer" to the previous article in the current newsgroup.

Returns the message-id of the article.

date ()

Returns the date on the remote server. This date will be in a UNIX time format (seconds since 1970)

postok ()

postok will return true if the servers initial response indicated that it will allow posting.

authinfo ( USER, PASS )

Authenticates to the server (using AUTHINFO USER / AUTHINFO PASS) using the supplied username and password. Please note that the password is sent in clear text to the server. This command should not be used with valuable passwords unless the connection to the server is somehow protected.

list ()

Obtain information about all the active newsgroups. The results is a reference to a hash where the key is a group name and each value is a reference to an array. The elements in this array are:- the last article number in the group, the first article number in the group and any information flags about the group.

newgroups ( SINCE [, DISTRIBUTIONS ])

SINCE is a time value and DISTRIBUTIONS is either a distribution pattern or a reference to a list of distribution patterns. The result is the same as list, but the groups return will be limited to those created after SINCE and, if specified, in one of the distribution areas in DISTRIBUTIONS.

newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])

SINCE is a time value. GROUPS is either a group pattern or a reference to a list of group patterns. DISTRIBUTIONS is either a distribution pattern or a reference to a list of distribution patterns.

Returns a reference to a list which contains the message-ids of all news posted after SINCE, that are in a groups which matched GROUPS and a distribution which matches DISTRIBUTIONS.

next ()

Set the "current article pointer" to the next article in the current newsgroup.

Returns the message-id of the article.

post ( [ MESSAGE ] )

Post a new article to the news server. If MESSAGE is specified and posting is allowed then the message will be sent.

If MESSAGE is not specified then the message must be sent using the datasend and dataend methods from the Net::Cmd manpage

MESSAGE can be either an array of lines or a reference to an array.

The message, either sent via datasend or as the MESSAGE parameter, must be in the format as described by RFC822 and must contain From:, Newsgroups: and Subject: headers.

postfh ()

Post a new article to the news server using a tied filehandle. If posting is allowed, this method will return a tied filehandle that you can print() the contents of the article to be posted. You must explicitly close() the filehandle when you are finished posting the article, and the return value from the close() call will indicate whether the message was successfully posted.

slave ()

Tell the remote server that I am not a user client, but probably another news server.

quit ()

Quit the remote server and close the socket connection.

Extension methods

These methods use commands that are not part of the RFC977 documentation. Some servers may not support all of them.

newsgroups ( [ PATTERN ] )

Returns a reference to a hash where the keys are all the group names which match PATTERN, or all of the groups if no pattern is specified, and each value contains the description text for the group.

distributions ()

Returns a reference to a hash where the keys are all the possible distribution names and the values are the distribution descriptions.

subscriptions ()

Returns a reference to a list which contains a list of groups which are recommended for a new user to subscribe to.

overview_fmt ()

Returns a reference to an array which contain the names of the fields returned by xover.

active_times ()

Returns a reference to a hash where the keys are the group names and each value is a reference to an array containing the time the groups was created and an identifier, possibly an Email address, of the creator.

active ( [ PATTERN ] )

Similar to list but only active groups that match the pattern are returned. PATTERN can be a group pattern.

xgtitle ( PATTERN )

Returns a reference to a hash where the keys are all the group names which match PATTERN and each value is the description text for the group.

xhdr ( HEADER, MESSAGE-SPEC )

Obtain the header field HEADER for all the messages specified.

The return value will be a reference to a hash where the keys are the message numbers and each value contains the text of the requested header for that message.

xover ( MESSAGE-SPEC )

The return value will be a reference to a hash where the keys are the message numbers and each value contains a reference to an array which contains the overview fields for that message.

The names of the fields can be obtained by calling overview_fmt.

xpath ( MESSAGE-ID )

Returns the path name to the file on the server which contains the specified message.

xpat ( HEADER, PATTERN, MESSAGE-SPEC)

The result is the same as xhdr except the is will be restricted to headers where the text of the header matches PATTERN

xrover

The XROVER command returns reference information for the article(s) specified.

Returns a reference to a HASH where the keys are the message numbers and the values are the References: lines from the articles

listgroup ( [ GROUP ] )

Returns a reference to a list of all the active messages in GROUP, or the current group if GROUP is not specified.

reader

Tell the server that you are a reader and not another server.

This is required by some servers. For example if you are connecting to an INN server and you have transfer permission your connection will be connected to the transfer daemon, not the NNTP daemon. Issuing this command will cause the transfer daemon to hand over control to the NNTP daemon.

Some servers do not understand this command, but issuing it and ignoring the response is harmless.

UNSUPPORTED

The following NNTP command are unsupported by the package, and there are no plans to do so.

    AUTHINFO GENERIC
    XTHREAD
    XSEARCH
    XINDEX

DEFINITIONS

MESSAGE-SPEC

MESSAGE-SPEC is either a single message-id, a single message number, or a reference to a list of two message numbers.

If MESSAGE-SPEC is a reference to a list of two message numbers and the second number in a range is less than or equal to the first then the range represents all messages in the group after the first message number.

NOTE For compatibility reasons only with earlier versions of Net::NNTP a message spec can be passed as a list of two numbers, this is deprecated and a reference to the list should now be passed

PATTERN

The NNTP protocol uses the WILDMAT format for patterns. The WILDMAT format was first developed by Rich Salz based on the format used in the UNIX "find" command to articulate file names. It was developed to provide a uniform mechanism for matching patterns in the same manner that the UNIX shell matches filenames.

Patterns are implicitly anchored at the beginning and end of each string when testing for a match.

There are five pattern matching operations other than a strict one-to-one match between the pattern and the source to be checked for a match.

The first is an asterisk * to match any sequence of zero or more characters.

The second is a question mark ? to match any single character. The third specifies a specific set of characters.

The set is specified as a list of characters, or as a range of characters where the beginning and end of the range are separated by a minus (or dash) character, or as any combination of lists and ranges. The dash can also be included in the set as a character it if is the beginning or end of the set. This set is enclosed in square brackets. The close square bracket ] may be used in a set if it is the first character in the set.

The fourth operation is the same as the logical not of the third operation and is specified the same way as the third with the addition of a caret character ^ at the beginning of the test string just inside the open square bracket.

The final operation uses the backslash character to invalidate the special meaning of an open square bracket [, the asterisk, backslash or the question mark. Two backslashes in sequence will result in the evaluation of the backslash as a character with no special meaning.

Examples
[^]-]

matches any single character other than a close square bracket or a minus sign/dash.

  • matches any string that ends with the string "bdc" including the string "bdc" (without quotes).

    • [0-9a-zA-Z]

    matches any single printable alphanumeric ASCII character.

    a??d

    matches any four character string which begins with a and ends with d.

    SEE ALSO

    the Net::Cmd manpage

    AUTHOR

    Graham Barr <gbarr@pobox.com>

    COPYRIGHT

    Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

    $Id: //depot/libnet/Net/NNTP.pm#18 $


Net::Netrc - OO interface to users netrc file

  • THE .netrc FILE
  • CONSTRUCTOR
  • METHODS
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

Net::Netrc - OO interface to users netrc file

SYNOPSIS

    use Net::Netrc;

    $mach = Net::Netrc->lookup('some.machine');
    $login = $mach->login;
    ($login, $password, $account) = $mach->lpa;

DESCRIPTION

Net::Netrc is a class implementing a simple interface to the .netrc file used as by the ftp program.

Net::Netrc also implements security checks just like the ftp program, these checks are, first that the .netrc file must be owned by the user and second the ownership permissions should be such that only the owner has read and write access. If these conditions are not met then a warning is output and the .netrc file is not read.

THE .netrc FILE

The .netrc file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines:

machine name

Identify a remote machine name. The auto-login process searches the .netrc file for a machine token that matches the remote machine specified. Once a match is made, the subsequent .netrc tokens are processed, stopping when the end of file is reached or an- other machine or a default token is encountered.

default

This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. This is normally used as:

    default login anonymous password user@site

thereby giving the user automatic anonymous login to machines not specified in .netrc.

login name

Identify a user on the remote machine. If this token is present, the auto-login process will initiate a login using the specified name.

password string

Supply a password. If this token is present, the auto-login process will supply the specified string if the remote server requires a password as part of the login process.

account string

Supply an additional account password. If this token is present, the auto-login process will supply the specified string if the remote server requires an additional account password.

macdef name

Define a macro. Net::Netrc only parses this field to be compatible with ftp.

CONSTRUCTOR

The constructor for a Net::Netrc object is not called new as it does not really create a new object. But instead is called lookup as this is essentially what it does.

lookup ( MACHINE [, LOGIN ])

Lookup and return a reference to the entry for MACHINE. If LOGIN is given then the entry returned will have the given login. If LOGIN is not given then the first entry in the .netrc file for MACHINE will be returned.

If a matching entry cannot be found, and a default entry exists, then a reference to the default entry is returned.

If there is no matching entry found and there is no default defined, or no .netrc file is found, then undef is returned.

METHODS

login ()

Return the login id for the netrc entry

password ()

Return the password for the netrc entry

account ()

Return the account information for the netrc entry

lpa ()

Return a list of login, password and account information fir the netrc entry

AUTHOR

Graham Barr <gbarr@pobox.com>

SEE ALSO

the Net::Netrc manpage the Net::Cmd manpage

COPYRIGHT

Copyright (c) 1995-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id: //depot/libnet/Net/Netrc.pm#13 $


Net::POP3 - Post Office Protocol 3 Client class

  • CONSTRUCTOR
  • METHODS
  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Net::POP3 - Post Office Protocol 3 Client class (RFC1939)

SYNOPSIS

    use Net::POP3;

    # Constructors
    $pop = Net::POP3->new('pop3host');
    $pop = Net::POP3->new('pop3host', Timeout => 60);

    if ($pop->login($username, $password) > 0) {
      my $msgnums = $pop->list; # hashref of msgnum => size
      foreach my $msgnum (keys %$msgnums) {
        my $msg = $pop->get($msgnum);
        print @$msg;
        $pop->delete($msgnum);
      }
    }

    $pop->quit;

DESCRIPTION

This module implements a client interface to the POP3 protocol, enabling a perl5 application to talk to POP3 servers. This documentation assumes that you are familiar with the POP3 protocol described in RFC1939.

A new Net::POP3 object must be created with the new method. Once this has been done, all POP3 commands are accessed via method calls on the object.

CONSTRUCTOR

new ( [ HOST ] [, OPTIONS ] 0

This is the constructor for a new Net::POP3 object. HOST is the name of the remote host to which an POP3 connection is required.

HOST is optional. If HOST is not given then it may instead be passed as the Host option described below. If neither is given then the POP3_Hosts specified in Net::Config will be used.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - POP3 host to connect to. It may be a single scalar, as defined for the PeerAddr option in the IO::Socket::INET manpage, or a reference to an array with hosts to try in turn. The host method will return the value which was used to connect to the host.

ResvPort - If given then the socket for the Net::POP3 object will be bound to the local port given using bind when the socket is created.

Timeout - Maximum time, in seconds, to wait for a response from the POP3 server (default: 120)

Debug - Enable debugging information

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

auth ( USERNAME, PASSWORD )

Attempt SASL authentication.

user ( USER )

Send the USER command.

pass ( PASS )

Send the PASS command. Returns the number of messages in the mailbox.

login ( [ USER [, PASS ]] )

Send both the USER and PASS commands. If PASS is not given the Net::POP3 uses Net::Netrc to lookup the password using the host and username. If the username is not specified then the current user name will be used.

Returns the number of messages in the mailbox. However if there are no messages on the server the string "0E0" will be returned. This is will give a true value in a boolean context, but zero in a numeric context.

If there was an error authenticating the user then undef will be returned.

apop ( [ USER [, PASS ]] )

Authenticate with the server identifying as USER with password PASS. Similar to login, but the password is not sent in clear text.

To use this method you must have the Digest::MD5 or the MD5 module installed, otherwise this method will return undef.

banner ()

Return the sever's connection banner

capa ()

Return a reference to a hash of the capabilties of the server. APOP is added as a pseudo capability. Note that I've been unable to find a list of the standard capability values, and some appear to be multi-word and some are not. We make an attempt at intelligently parsing them, but it may not be correct.

capabilities ()

Just like capa, but only uses a cache from the last time we asked the server, so as to avoid asking more than once.

top ( MSGNUM [, NUMLINES ] )

Get the header and the first NUMLINES of the body for the message MSGNUM. Returns a reference to an array which contains the lines of text read from the server.

list ( [ MSGNUM ] )

If called with an argument the list returns the size of the message in octets.

If called without arguments a reference to a hash is returned. The keys will be the MSGNUM's of all undeleted messages and the values will be their size in octets.

get ( MSGNUM [, FH ] )

Get the message MSGNUM from the remote mailbox. If FH is not given then get returns a reference to an array which contains the lines of text read from the server. If FH is given then the lines returned from the server are printed to the filehandle FH.

getfh ( MSGNUM )

As per get(), but returns a tied filehandle. Reading from this filehandle returns the requested message. The filehandle will return EOF at the end of the message and should not be reused.

last ()

Returns the highest MSGNUM of all the messages accessed.

popstat ()

Returns a list of two elements. These are the number of undeleted elements and the size of the mbox in octets.

ping ( USER )

Returns a list of two elements. These are the number of new messages and the total number of messages for USER.

uidl ( [ MSGNUM ] )

Returns a unique identifier for MSGNUM if given. If MSGNUM is not given uidl returns a reference to a hash where the keys are the message numbers and the values are the unique identifiers.

delete ( MSGNUM )

Mark message MSGNUM to be deleted from the remote mailbox. All messages that are marked to be deleted will be removed from the remote mailbox when the server connection closed.

reset ()

Reset the status of the remote POP3 server. This includes reseting the status of all messages to not be deleted.

quit ()

Quit and close the connection to the remote POP3 server. Any messages marked as deleted will be deleted from the remote mailbox.

NOTES

If a Net::POP3 object goes out of scope before quit method is called then the reset method will called before the connection is closed. This means that any messages marked to be deleted will not be.

SEE ALSO

the Net::Netrc manpage, the Net::Cmd manpage

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995-2003 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::Ping - check a remote host for reachability

    • Functions
  • NOTES
  • INSTALL
  • BUGS
  • AUTHORS
  • COPYRIGHT

NAME

Net::Ping - check a remote host for reachability

SYNOPSIS

    use Net::Ping;

    $p = Net::Ping->new();
    print "$host is alive.\n" if $p->ping($host);
    $p->close();

    $p = Net::Ping->new("icmp");
    $p->bind($my_addr); # Specify source interface of pings
    foreach $host (@host_array)
    {
        print "$host is ";
        print "NOT " unless $p->ping($host, 2);
        print "reachable.\n";
        sleep(1);
    }
    $p->close();

    $p = Net::Ping->new("tcp", 2);
    # Try connecting to the www port instead of the echo port
    $p->{port_num} = getservbyname("http", "tcp");
    while ($stop_time > time())
    {
        print "$host not reachable ", scalar(localtime()), "\n"
            unless $p->ping($host);
        sleep(300);
    }
    undef($p);

    # Like tcp protocol, but with many hosts
    $p = Net::Ping->new("syn");
    $p->{port_num} = getservbyname("http", "tcp");
    foreach $host (@host_array) {
      $p->ping($host);
    }
    while (($host,$rtt,$ip) = $p->ack) {
      print "HOST: $host [$ip] ACKed in $rtt seconds.\n";
    }

    # High precision syntax (requires Time::HiRes)
    $p = Net::Ping->new();
    $p->hires();
    ($ret, $duration, $ip) = $p->ping($host, 5.5);
    printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n", 1000 * $duration)
      if $ret;
    $p->close();

    # For backward compatibility
    print "$host is alive.\n" if pingecho($host);

DESCRIPTION

This module contains methods to test the reachability of remote hosts on a network. A ping object is first created with optional parameters, a variable number of hosts may be pinged multiple times and then the connection is closed.

You may choose one of six different protocols to use for the ping. The "tcp" protocol is the default. Note that a live remote host may still fail to be pingable by one or more of these protocols. For example, www.microsoft.com is generally alive but not "icmp" pingable.

With the "tcp" protocol the ping() method attempts to establish a connection to the remote host's echo port. If the connection is successfully established, the remote host is considered reachable. No data is actually echoed. This protocol does not require any special privileges but has higher overhead than the "udp" and "icmp" protocols.

Specifying the "udp" protocol causes the ping() method to send a udp packet to the remote host's echo port. If the echoed packet is received from the remote host and the received packet contains the same data as the packet that was sent, the remote host is considered reachable. This protocol does not require any special privileges. It should be borne in mind that, for a udp ping, a host will be reported as unreachable if it is not running the appropriate echo service. For Unix-like systems see inetd(8) for more information.

If the "icmp" protocol is specified, the ping() method sends an icmp echo message to the remote host, which is what the UNIX ping program does. If the echoed message is received from the remote host and the echoed information is correct, the remote host is considered reachable. Specifying the "icmp" protocol requires that the program be run as root or that the program be setuid to root.

If the "external" protocol is specified, the ping() method attempts to use the Net::Ping::External module to ping the remote host. Net::Ping::External interfaces with your system's default ping utility to perform the ping, and generally produces relatively accurate results. If Net::Ping::External if not installed on your system, specifying the "external" protocol will result in an error.

If the "syn" protocol is specified, the ping() method will only send a TCP SYN packet to the remote host then immediately return. If the syn packet was sent successfully, it will return a true value, otherwise it will return false. NOTE: Unlike the other protocols, the return value does NOT determine if the remote host is alive or not since the full TCP three-way handshake may not have completed yet. The remote host is only considered reachable if it receives a TCP ACK within the timeout specifed. To begin waiting for the ACK packets, use the ack() method as explained below. Use the "syn" protocol instead the "tcp" protocol to determine reachability of multiple destinations simultaneously by sending parallel TCP SYN packets. It will not block while testing each remote host. demo/fping is provided in this distribution to demonstrate the "syn" protocol as an example. This protocol does not require any special privileges.

Functions

Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device [, $tos ]]]]]);

Create a new ping object. All of the parameters are optional. $proto specifies the protocol to use when doing a ping. The current choices are "tcp", "udp", "icmp", "stream", "syn", or "external". The default is "tcp".

If a default timeout ($def_timeout) in seconds is provided, it is used when a timeout is not given to the ping() method (below). The timeout must be greater than 0 and the default, if not specified, is 5 seconds.

If the number of data bytes ($bytes) is given, that many data bytes are included in the ping packet sent to the remote host. The number of data bytes is ignored if the protocol is "tcp". The minimum (and default) number of data bytes is 1 if the protocol is "udp" and 0 otherwise. The maximum number of data bytes that can be specified is 1024.

If $device is given, this device is used to bind the source endpoint before sending the ping packet. I beleive this only works with superuser privileges and with udp and icmp protocols at this time.

If $tos is given, this ToS is configured into the soscket.

$p->ping($host [, $timeout]);

Ping the remote host and wait for a response. $host can be either the hostname or the IP number of the remote host. The optional timeout must be greater than 0 seconds and defaults to whatever was specified when the ping object was created. Returns a success flag. If the hostname cannot be found or there is a problem with the IP number, the success flag returned will be undef. Otherwise, the success flag will be 1 if the host is reachable and 0 if it is not. For most practical purposes, undef and 0 and can be treated as the same case. In array context, the elapsed time as well as the string form of the ip the host resolved to are also returned. The elapsed time value will be a float, as retuned by the Time::HiRes::time() function, if hires() has been previously called, otherwise it is returned as an integer.

$p->source_verify( { 0 | 1 } );

Allows source endpoint verification to be enabled or disabled. This is useful for those remote destinations with multiples interfaces where the response may not originate from the same endpoint that the original destination endpoint was sent to. This only affects udp and icmp protocol pings.

This is enabled by default.

$p->service_check( { 0 | 1 } );

Set whether or not the connect behavior should enforce remote service availability as well as reachability. Normally, if the remote server reported ECONNREFUSED, it must have been reachable because of the status packet that it reported. With this option enabled, the full three-way tcp handshake must have been established successfully before it will claim it is reachable. NOTE: It still does nothing more than connect and disconnect. It does not speak any protocol (i.e., HTTP or FTP) to ensure the remote server is sane in any way. The remote server CPU could be grinding to a halt and unresponsive to any clients connecting, but if the kernel throws the ACK packet, it is considered alive anyway. To really determine if the server is responding well would be application specific and is beyond the scope of Net::Ping. For udp protocol, enabling this option demands that the remote server replies with the same udp data that it was sent as defined by the udp echo service.

This affects the "udp", "tcp", and "syn" protocols.

This is disabled by default.

$p->tcp_service_check( { 0 | 1 } );

Depricated method, but does the same as service_check() method.

$p->hires( { 0 | 1 } );

Causes this module to use Time::HiRes module, allowing milliseconds to be returned by subsequent calls to ping().

This is disabled by default.

$p->bind($local_addr);

Sets the source address from which pings will be sent. This must be the address of one of the interfaces on the local host. $local_addr may be specified as a hostname or as a text IP address such as "192.168.1.1".

If the protocol is set to "tcp", this method may be called any number of times, and each call to the ping() method (below) will use the most recent $local_addr. If the protocol is "icmp" or "udp", then bind() must be called at most once per object, and (if it is called at all) must be called before the first call to ping() for that object.

$p->open($host);

When you are using the "stream" protocol, this call pre-opens the tcp socket. It's only necessary to do this if you want to provide a different timeout when creating the connection, or remove the overhead of establishing the connection from the first ping. If you don't call open(), the connection is automatically opened the first time ping() is called. This call simply does nothing if you are using any protocol other than stream.

$p->ack( [ $host ] );

When using the "syn" protocol, use this method to determine the reachability of the remote host. This method is meant to be called up to as many times as ping() was called. Each call returns the host (as passed to ping()) that came back with the TCP ACK. The order in which the hosts are returned may not necessarily be the same order in which they were SYN queued using the ping() method. If the timeout is reached before the TCP ACK is received, or if the remote host is not listening on the port attempted, then the TCP connection will not be established and ack() will return undef. In list context, the host, the ack time, and the dotted ip string will be returned instead of just the host. If the optional $host argument is specified, the return value will be partaining to that host only. This call simply does nothing if you are using any protocol other than syn.

$p->nack( $failed_ack_host );

The reason that host $failed_ack_host did not receive a valid ACK. Useful to find out why when ack( $fail_ack_host ) returns a false value.

$p->close();

Close the network connection for this ping object. The network connection is also closed by "undef $p". The network connection is automatically closed if the ping object goes out of scope (e.g. $p is local to a subroutine and you leave the subroutine).

pingecho($host [, $timeout]);

To provide backward compatibility with the previous version of Net::Ping, a pingecho() subroutine is available with the same functionality as before. pingecho() uses the tcp protocol. The return values and parameters are the same as described for the ping() method. This subroutine is obsolete and may be removed in a future version of Net::Ping.

NOTES

There will be less network overhead (and some efficiency in your program) if you specify either the udp or the icmp protocol. The tcp protocol will generate 2.5 times or more traffic for each ping than either udp or icmp. If many hosts are pinged frequently, you may wish to implement a small wait (e.g. 25ms or more) between each ping to avoid flooding your network with packets.

The icmp protocol requires that the program be run as root or that it be setuid to root. The other protocols do not require special privileges, but not all network devices implement tcp or udp echo.

Local hosts should normally respond to pings within milliseconds. However, on a very congested network it may take up to 3 seconds or longer to receive an echo packet from the remote host. If the timeout is set too low under these conditions, it will appear that the remote host is not reachable (which is almost the truth).

Reachability doesn't necessarily mean that the remote host is actually functioning beyond its ability to echo packets. tcp is slightly better at indicating the health of a system than icmp because it uses more of the networking stack to respond.

Because of a lack of anything better, this module uses its own routines to pack and unpack ICMP packets. It would be better for a separate module to be written which understands all of the different kinds of ICMP packets.

INSTALL

The latest source tree is available via cvs:

  cvs -z3 -q -d :pserver:anonymous@cvs.roobik.com.:/usr/local/cvsroot/freeware checkout Net-Ping
  cd Net-Ping

The tarball can be created as follows:

  perl Makefile.PL ; make ; make dist

The latest Net::Ping release can be found at CPAN:

  $CPAN/modules/by-module/Net/

1) Extract the tarball

  gtar -zxvf Net-Ping-xxxx.tar.gz
  cd Net-Ping-xxxx

2) Build:

  make realclean
  perl Makefile.PL
  make
  make test

3) Install

  make install

Or install it RPM Style:

  rpm -ta SOURCES/Net-Ping-xxxx.tar.gz
  rpm -ih RPMS/noarch/perl-Net-Ping-xxxx.rpm

BUGS

For a list of known issues, visit:

https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping

To report a new bug, visit:

https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Ping

AUTHORS

  Current maintainer:
    bbb@cpan.org (Rob Brown)
  External protocol:
    colinm@cpan.org (Colin McMillen)
  Stream protocol:
    bronson@trestle.com (Scott Bronson)
  Original pingecho():
    karrer@bernina.ethz.ch (Andreas Karrer)
    pmarquess@bfsec.bt.co.uk (Paul Marquess)
  Original Net::Ping author:
    mose@ns.ccsn.edu (Russell Mosemann)

COPYRIGHT

Copyright (c) 2002-2003, Rob Brown. All rights reserved.

Copyright (c) 2001, Colin McMillen. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

$Id: Ping.pm,v 1.86 2003/06/27 21:31:07 rob Exp $


Net::SMTP - Simple Mail Transfer Protocol Client

  • EXAMPLES
  • CONSTRUCTOR
  • METHODS
  • ADDRESSES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Net::SMTP - Simple Mail Transfer Protocol Client

SYNOPSIS

    use Net::SMTP;

    # Constructors
    $smtp = Net::SMTP->new('mailhost');
    $smtp = Net::SMTP->new('mailhost', Timeout => 60);

DESCRIPTION

This module implements a client interface to the SMTP and ESMTP protocol, enabling a perl5 application to talk to SMTP servers. This documentation assumes that you are familiar with the concepts of the SMTP protocol described in RFC821.

A new Net::SMTP object must be created with the new method. Once this has been done, all SMTP commands are accessed through this object.

The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.

EXAMPLES

This example prints the mail domain name of the SMTP server known as mailhost:

    #!/usr/local/bin/perl -w

    use Net::SMTP;

    $smtp = Net::SMTP->new('mailhost');
    print $smtp->domain,"\n";
    $smtp->quit;

This example sends a small message to the postmaster at the SMTP server known as mailhost:

    #!/usr/local/bin/perl -w

    use Net::SMTP;

    $smtp = Net::SMTP->new('mailhost');

    $smtp->mail($ENV{USER});
    $smtp->to('postmaster');

    $smtp->data();
    $smtp->datasend("To: postmaster\n");
    $smtp->datasend("\n");
    $smtp->datasend("A simple test message\n");
    $smtp->dataend();

    $smtp->quit;

CONSTRUCTOR

new ( [ HOST ] [, OPTIONS ] )

This is the constructor for a new Net::SMTP object. HOST is the name of the remote host to which an SMTP connection is required.

HOST is optional. If HOST is not given then it may instead be passed as the Host option described below. If neither is given then the SMTP_Hosts specified in Net::Config will be used.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Hello - SMTP requires that you identify yourself. This option specifies a string to pass as your mail domain. If not given localhost.localdomain will be used.

Host - SMTP host to connect to. It may be a single scalar, as defined for the PeerAddr option in the IO::Socket::INET manpage, or a reference to an array with hosts to try in turn. The host method will return the value which was used to connect to the host.

LocalAddr and LocalPort - These parameters are passed directly to IO::Socket to allow binding the socket to a local port.

Timeout - Maximum time, in seconds, to wait for a response from the SMTP server (default: 120)

ExactAddresses - If true the all ADDRESS arguments must be as defined by addr-spec in RFC2822. If not given, or false, then Net::SMTP will attempt to extract the address from the value passed.

Debug - Enable debugging information

Example:

    $smtp = Net::SMTP->new('mailhost',
                           Hello => 'my.mail.domain'
                           Timeout => 30,
                           Debug   => 1,
                          );

    # the same
    $smtp = Net::SMTP->new(
                           Host => 'mailhost',
                           Hello => 'my.mail.domain'
                           Timeout => 30,
                           Debug   => 1,
                          );

    # Connect to the default server from Net::config
    $smtp = Net::SMTP->new(
                           Hello => 'my.mail.domain'
                           Timeout => 30,
                          );

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

banner ()

Returns the banner message which the server replied with when the initial connection was made.

domain ()

Returns the domain that the remote SMTP server identified itself as during connection.

hello ( DOMAIN )

Tell the remote server the mail domain which you are in using the EHLO command (or HELO if EHLO fails). Since this method is invoked automatically when the Net::SMTP object is constructed the user should normally not have to call it manually.

host ()

Returns the value used by the constructor, and passed to IO::Socket::INET, to connect to the host.

etrn ( DOMAIN )

Request a queue run for the DOMAIN given.

auth ( USERNAME, PASSWORD )

Attempt SASL authentication.

mail ( ADDRESS [, OPTIONS] )
send ( ADDRESS )
send_or_mail ( ADDRESS )
send_and_mail ( ADDRESS )

Send the appropriate command to the server MAIL, SEND, SOML or SAML. ADDRESS is the address of the sender. This initiates the sending of a message. The method recipient should be called for each address that the message is to be sent to.

The mail method can some additional ESMTP OPTIONS which is passed in hash like fashion, using key and value pairs. Possible options are:

 Size        => <bytes>
 Return      => "FULL" | "HDRS"
 Bits        => "7" | "8" | "binary"
 Transaction => <ADDRESS>
 Envelope    => <ENVID>
 XVERP       => 1

The Return and Envelope parameters are used for DSN (Delivery Status Notification).

reset ()

Reset the status of the server. This may be called after a message has been initiated, but before any data has been sent, to cancel the sending of the message.

recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )

Notify the server that the current message should be sent to all of the addresses given. Each address is sent as a separate command to the server. Should the sending of any address result in a failure then the process is aborted and a false value is returned. It is up to the user to call reset if they so desire.

The recipient method can also pass additional case-sensitive OPTIONS as an anonymous hash using key and value pairs. Possible options are:

  Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
  SkipBad => 1        (to ignore bad addresses)

If SkipBad is true the recipient will not return an error when a bad address is encountered and it will return an array of addresses that did succeed.

  $smtp->recipient($recipient1,$recipient2);  # Good
  $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
  $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
  @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
  $smtp->recipient("$recipient,$recipient2"); # BAD

Notify is used to request Delivery Status Notifications (DSNs), but your SMTP/ESMTP service may not respect this request depending upon its version and your site's SMTP configuration.

Leaving out the Notify option usually defaults an SMTP service to its default behavior equivalent to ['FAILURE'] notifications only, but again this may be dependent upon your site's SMTP configuration.

The NEVER keyword must appear by itself if used within the Notify option and "requests that a DSN not be returned to the sender under any conditions."

  {Notify => ['NEVER']}

  $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good

You may use any combination of these three values 'SUCCESS','FAILURE','DELAY' in the anonymous array reference as defined by RFC3461 (see http://rfc.net/rfc3461.html for more information. Note: quotations in this topic from same.).

A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on successful delivery or delivery failure, respectively."

A Notify parameter of 'DELAY' "indicates the sender's willingness to receive delayed DSNs. Delayed DSNs may be issued if delivery of a message has been delayed for an unusual amount of time (as determined by the Message Transfer Agent (MTA) at which the message is delayed), but the final delivery status (whether successful or failure) cannot be determined. The absence of the DELAY keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under any conditions."

  {Notify => ['SUCCESS','FAILURE','DELAY']}

  $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
to ( ADDRESS [, ADDRESS [...]] )
cc ( ADDRESS [, ADDRESS [...]] )
bcc ( ADDRESS [, ADDRESS [...]] )

Synonyms for recipient.

data ( [ DATA ] )

Initiate the sending of the data from the current message.

DATA may be a reference to a list or a list. If specified the contents of DATA and a termination string ".\r\n" is sent to the server. And the result will be true if the data was accepted.

If DATA is not specified then the result will indicate that the server wishes the data to be sent. The data must then be sent using the datasend and dataend methods described in the Net::Cmd manpage.

expand ( ADDRESS )

Request the server to expand the given address Returns an array which contains the text read from the server.

verify ( ADDRESS )

Verify that ADDRESS is a legitimate mailing address.

Most sites usually disable this feature in their SMTP service configuration. Use "Debug => 1" option under new() to see if disabled.

help ( [ $subject ] )

Request help text from the server. Returns the text or undef upon failure

quit ()

Send the QUIT command to the remote SMTP server and close the socket connection.

ADDRESSES

Net::SMTP attempts to DWIM with addresses that are passed. For example an application might extract The From: line from an email and pass that to mail(). While this may work, it is not reccomended. The application should really use a module like the Mail::Address manpage to extract the mail address and pass that.

If ExactAddresses is passed to the contructor, then addresses should be a valid rfc2821-quoted address, although Net::SMTP will accept accept the address surrounded by angle brackets.

 funny user@domain      WRONG
 "funny user"@domain    RIGHT, recommended
 <"funny user"@domain>  OK

SEE ALSO

the Net::Cmd manpage

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995-2004 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::Time - time and daytime network client interface

  • AUTHOR
  • COPYRIGHT

NAME

Net::Time - time and daytime network client interface

SYNOPSIS

    use Net::Time qw(inet_time inet_daytime);

    print inet_time();          # use default host from Net::Config
    print inet_time('localhost');
    print inet_time('localhost', 'tcp');

    print inet_daytime();       # use default host from Net::Config
    print inet_daytime('localhost');
    print inet_daytime('localhost', 'tcp');

DESCRIPTION

Net::Time provides subroutines that obtain the time on a remote machine.

inet_time ( [HOST [, PROTOCOL [, TIMEOUT]]])

Obtain the time on HOST, or some default host if HOST is not given or not defined, using the protocol as defined in RFC868. The optional argument PROTOCOL should define the protocol to use, either tcp or udp. The result will be a time value in the same units as returned by time() or undef upon failure.

inet_daytime ( [HOST [, PROTOCOL [, TIMEOUT]]])

Obtain the time on HOST, or some default host if HOST is not given or not defined, using the protocol as defined in RFC867. The optional argument PROTOCOL should define the protocol to use, either tcp or udp. The result will be an ASCII string or undef upon failure.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1995-2004 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::hostent - by-name interface to Perl's built-in gethost* functions

  • EXAMPLES
  • NOTE
  • AUTHOR

NAME

Net::hostent - by-name interface to Perl's built-in gethost*() functions

SYNOPSIS

 use Net::hostent;

DESCRIPTION

This module's default exports override the core gethostbyname() and gethostbyaddr() functions, replacing them with versions that return "Net::hostent" objects. This object has methods that return the similarly named structure field name from the C's hostent structure from netdb.h; namely name, aliases, addrtype, length, and addr_list. The aliases and addr_list methods return array reference, the rest scalars. The addr method is equivalent to the zeroth element in the addr_list array reference.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding h_. Thus, $host_obj->name() corresponds to $h_name if you import the fields. Array references are available as regular array variables, so for example @{ $host_obj->aliases() } would be simply @h_aliases.

The gethost() function is a simple front-end that forwards a numeric argument to gethostbyaddr() by way of Socket::inet_aton, and the rest to gethostbyname().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

EXAMPLES

 use Net::hostent;
 use Socket;

 @ARGV = ('netscape.com') unless @ARGV;

 for $host ( @ARGV ) {

    unless ($h = gethost($host)) {
        warn "$0: no such host: $host\n";
        next;
    }

    printf "\n%s is %s%s\n",
            $host,
            lc($h->name) eq lc($host) ? "" : "*really* ",
            $h->name;

    print "\taliases are ", join(", ", @{$h->aliases}), "\n"
                if @{$h->aliases};

    if ( @{$h->addr_list} > 1 ) {
        my $i;
        for $addr ( @{$h->addr_list} ) {
            printf "\taddr #%d is [%s]\n", $i++, inet_ntoa($addr);
        }
    } else {
        printf "\taddress is [%s]\n", inet_ntoa($h->addr);
    }

    if ($h = gethostbyaddr($h->addr)) {
        if (lc($h->name) ne lc($host)) {
            printf "\tThat addr reverses to host %s!\n", $h->name;
            $host = $h->name;
            redo;
        }
    }
     }

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


libnetFAQ - libnet Frequently Asked Questions

    • Where to get this document
    • How to contribute to this document
  • Author and Copyright Information
    • Disclaimer
  • Obtaining and installing libnet
    • What is libnet ?
    • Which version of perl do I need ?
    • What other modules do I need ?
    • What machines support libnet ?
    • Where can I get the latest libnet release
  • Using Net::FTP
    • How do I download files from an FTP server ?
    • How do I transfer files in binary mode ?
    • How can I get the size of a file on a remote FTP server ?
    • How can I get the modification time of a file on a remote FTP server ?
    • How can I change the permissions of a file on a remote server ?
    • Can I do a reget operation like the ftp command ?
    • How do I get a directory listing from an FTP server ?
    • Changing directory to "" does not fail ?
    • I am behind a SOCKS firewall, but the Firewall option does not work ?
    • I am behind an FTP proxy firewall, but cannot access machines outside ?
    • My ftp proxy firewall does not listen on port 21
    • Is it possible to change the file permissions of a file on an FTP server ?
    • I have seen scripts call a method message, but cannot find it documented ?
    • Why does Net::FTP not implement mput and mget methods
  • Using Net::SMTP
    • Why can't the part of an Email address after the @ be used as the hostname ?
    • Why does Net::SMTP not do DNS MX lookups ?
    • The verify method always returns true ?
  • Debugging scripts
    • How can I debug my scripts that use Net::* modules ?
  • AUTHOR AND COPYRIGHT

NAME

libnetFAQ - libnet Frequently Asked Questions

DESCRIPTION

Where to get this document

This document is distributed with the libnet distribution, and is also available on the libnet web page at

    http://search.cpan.org/~gbarr/libnet/

How to contribute to this document

You may mail corrections, additions, and suggestions to me gbarr@pobox.com.

Author and Copyright Information

Copyright (c) 1997-1998 Graham Barr. All rights reserved. This document is free; you can redistribute it and/or modify it under the terms of the Artistic License.

Disclaimer

This information is offered in good faith and in the hope that it may be of use, but is not guaranteed to be correct, up to date, or suitable for any particular purpose whatsoever. The authors accept no liability in respect of this information or its use.

Obtaining and installing libnet

What is libnet ?

libnet is a collection of perl5 modules which all related to network programming. The majority of the modules available provided the client side of popular server-client protocols that are used in the internet community.

Which version of perl do I need ?

libnet has been know to work with versions of perl from 5.002 onwards. However if your release of perl is prior to perl5.004 then you will need to obtain and install the IO distribution from CPAN. If you have perl5.004 or later then you will have the IO modules in your installation already, but CPAN may contain updates.

What other modules do I need ?

The only modules you will need installed are the modules from the IO distribution. If you have perl5.004 or later you will already have these modules.

What machines support libnet ?

libnet itself is an entirely perl-code distribution so it should work on any machine that perl runs on. However IO may not work with some machines and earlier releases of perl. But this should not be the case with perl version 5.004 or later.

Where can I get the latest libnet release

The latest libnet release is always on CPAN, you will find it in

 http://www.cpan.org/modules/by-module/Net/

The latest release and information is also available on the libnet web page at

 http://search.cpan.org/~gbarr/libnet/

Using Net::FTP

How do I download files from an FTP server ?

An example taken from an article posted to comp.lang.perl.misc

    #!/your/path/to/perl

    # a module making life easier

    use Net::FTP;

    # for debuging: $ftp = Net::FTP->new('site','Debug',10);
    # open a connection and log in!

    $ftp = Net::FTP->new('target_site.somewhere.xxx');
    $ftp->login('username','password');

    # set transfer mode to binary

    $ftp->binary();

    # change the directory on the ftp site

    $ftp->cwd('/some/path/to/somewhere/');

    foreach $name ('file1', 'file2', 'file3') {

    # get's arguments are in the following order:
    # ftp server's filename
    # filename to save the transfer to on the local machine
    # can be simply used as get($name) if you want the same name

      $ftp->get($name,$name);
          }

    # ftp done!

    $ftp->quit;

How do I transfer files in binary mode ?

To transfer files without <LF><CR> translation Net::FTP provides the binary method

    $ftp->binary;

How can I get the size of a file on a remote FTP server ?

How can I get the modification time of a file on a remote FTP server ?

How can I change the permissions of a file on a remote server ?

The FTP protocol does not have a command for changing the permissions of a file on the remote server. But some ftp servers may allow a chmod command to be issued via a SITE command, eg

    $ftp->quot('site chmod 0777',$filename);

But this is not guaranteed to work.

Can I do a reget operation like the ftp command ?

How do I get a directory listing from an FTP server ?

Changing directory to "" does not fail ?

Passing an argument of "" to ->cwd() has the same affect of calling ->cwd() without any arguments. Turn on Debug (See below) and you will see what is happening

    $ftp = Net::FTP->new($host, Debug => 1);
    $ftp->login;
    $ftp->cwd("");

gives

    Net::FTP=GLOB(0x82196d8)>>> CWD /
    Net::FTP=GLOB(0x82196d8)<<< 250 CWD command successful.

I am behind a SOCKS firewall, but the Firewall option does not work ?

The Firewall option is only for support of one type of firewall. The type supported is an ftp proxy.

To use Net::FTP, or any other module in the libnet distribution, through a SOCKS firewall you must create a socks-ified perl executable by compiling perl with the socks library.

I am behind an FTP proxy firewall, but cannot access machines outside ?

Net::FTP implements the most popular ftp proxy firewall approach. The scheme implemented is that where you log in to the firewall with user@hostname

I have heard of one other type of firewall which requires a login to the firewall with an account, then a second login with user@hostname. You can still use Net::FTP to traverse these firewalls, but a more manual approach must be taken, eg

    $ftp = Net::FTP->new($firewall) or die $@;
    $ftp->login($firewall_user, $firewall_passwd) or die $ftp->message;
    $ftp->login($ext_user . '@' . $ext_host, $ext_passwd) or die $ftp->message.

My ftp proxy firewall does not listen on port 21

FTP servers usually listen on the same port number, port 21, as any other FTP server. But there is no reason why this has to be the case.

If you pass a port number to Net::FTP then it assumes this is the port number of the final destination. By default Net::FTP will always try to connect to the firewall on port 21.

Net::FTP uses IO::Socket to open the connection and IO::Socket allows the port number to be specified as part of the hostname. So this problem can be resolved by either passing a Firewall option like "hostname:1234" or by setting the ftp_firewall option in Net::Config to be a string in in the same form.

Is it possible to change the file permissions of a file on an FTP server ?

The answer to this is "maybe". The FTP protocol does not specify a command to change file permissions on a remote host. However many servers do allow you to run the chmod command via the SITE command. This can be done with

  $ftp->site('chmod','0775',$file);

I have seen scripts call a method message, but cannot find it documented ?

Net::FTP, like several other packages in libnet, inherits from Net::Cmd, so all the methods described in Net::Cmd are also available on Net::FTP objects.

Why does Net::FTP not implement mput and mget methods

The quick answer is because they are easy to implement yourself. The long answer is that to write these in such a way that multiple platforms are supported correctly would just require too much code. Below are some examples how you can implement these yourself.

sub mput {
  my($ftp,$pattern) = @_;
  foreach my $file (glob($pattern)) {
    $ftp->put($file) or warn $ftp->message;
  }
}

sub mget {
  my($ftp,$pattern) = @_;
  foreach my $file ($ftp->ls($pattern)) {
    $ftp->get($file) or warn $ftp->message;
  }
}

Using Net::SMTP

Why can't the part of an Email address after the @ be used as the hostname ?

The part of an Email address which follows the @ is not necessarily a hostname, it is a mail domain. To find the name of a host to connect for a mail domain you need to do a DNS MX lookup

Why does Net::SMTP not do DNS MX lookups ?

Net::SMTP implements the SMTP protocol. The DNS MX lookup is not part of this protocol.

The verify method always returns true ?

Well it may seem that way, but it does not. The verify method returns true if the command succeeded. If you pass verify an address which the server would normally have to forward to another machine, the command will succeed with something like

    252 Couldn't verify <someone@there> but will attempt delivery anyway

This command will fail only if you pass it an address in a domain the server directly delivers for, and that address does not exist.

Debugging scripts

How can I debug my scripts that use Net::* modules ?

Most of the libnet client classes allow options to be passed to the constructor, in most cases one option is called Debug. Passing this option with a non-zero value will turn on a protocol trace, which will be sent to STDERR. This trace can be useful to see what commands are being sent to the remote server and what responses are being received back.

    #!/your/path/to/perl

    use Net::FTP;

    my $ftp = new Net::FTP($host, Debug => 1);
    $ftp->login('gbarr','password');
    $ftp->quit;

this script would output something like

 Net::FTP: Net::FTP(2.22)
 Net::FTP:   Exporter
 Net::FTP:   Net::Cmd(2.0801)
 Net::FTP:   IO::Socket::INET
 Net::FTP:     IO::Socket(1.1603)
 Net::FTP:       IO::Handle(1.1504)
 Net::FTP=GLOB(0x8152974)<<< 220 imagine FTP server (Version wu-2.4(5) Tue Jul 29 11:17:18 CDT 1997) ready.
 Net::FTP=GLOB(0x8152974)>>> user gbarr
 Net::FTP=GLOB(0x8152974)<<< 331 Password required for gbarr.
 Net::FTP=GLOB(0x8152974)>>> PASS ....
 Net::FTP=GLOB(0x8152974)<<< 230 User gbarr logged in.  Access restrictions apply.
 Net::FTP=GLOB(0x8152974)>>> QUIT
 Net::FTP=GLOB(0x8152974)<<< 221 Goodbye.

The first few lines tell you the modules that Net::FTP uses and their versions, this is useful data to me when a user reports a bug. The last seven lines show the communication with the server. Each line has three parts. The first part is the object itself, this is useful for separating the output if you are using multiple objects. The second part is either <<<< to show data coming from the server or &gt&gt&gt&gt to show data going to the server. The remainder of the line is the command being sent or response being received.

AUTHOR AND COPYRIGHT

Copyright (c) 1997 Graham Barr. All rights reserved.

$Id: //depot/libnet/Net/libnetFAQ.pod#6 $


Net::netent - by-name interface to Perl's built-in getnet* functions

  • EXAMPLES
  • NOTE
  • AUTHOR

NAME

Net::netent - by-name interface to Perl's built-in getnet*() functions

SYNOPSIS

 use Net::netent qw(:FIELDS);
 getnetbyname("loopback")               or die "bad net";
 printf "%s is %08X\n", $n_name, $n_net;

 use Net::netent;

 $n = getnetbyname("loopback")          or die "bad net";
 { # there's gotta be a better way, eh?
     @bytes = unpack("C4", pack("N", $n->net));
     shift @bytes while @bytes && $bytes[0] == 0;
 }
 printf "%s is %08X [%d.%d.%d.%d]\n", $n->name, $n->net, @bytes;

DESCRIPTION

This module's default exports override the core getnetbyname() and getnetbyaddr() functions, replacing them with versions that return "Net::netent" objects. This object has methods that return the similarly named structure field name from the C's netent structure from netdb.h; namely name, aliases, addrtype, and net. The aliases method returns an array reference, the rest scalars.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding n_. Thus, $net_obj->name() corresponds to $n_name if you import the fields. Array references are available as regular array variables, so for example @{ $net_obj->aliases() } would be simply @n_aliases.

The getnet() function is a simple front-end that forwards a numeric argument to getnetbyaddr(), and the rest to getnetbyname().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

EXAMPLES

The getnet() functions do this in the Perl core:

    sv_setiv(sv, (I32)nent->n_net);

The gethost() functions do this in the Perl core:

    sv_setpvn(sv, hent->h_addr, len);

That means that the address comes back in binary for the host functions, and as a regular perl integer for the net ones. This seems a bug, but here's how to deal with it:

 use strict;
 use Socket;
 use Net::netent;

 @ARGV = ('loopback') unless @ARGV;

 my($n, $net);

 for $net ( @ARGV ) {

     unless ($n = getnetbyname($net)) {
        warn "$0: no such net: $net\n";
        next;
     }

     printf "\n%s is %s%s\n",
            $net,
            lc($n->name) eq lc($net) ? "" : "*really* ",
            $n->name;

     print "\taliases are ", join(", ", @{$n->aliases}), "\n"
                if @{$n->aliases};

     # this is stupid; first, why is this not in binary?
     # second, why am i going through these convolutions
     # to make it looks right
     {
        my @a = unpack("C4", pack("N", $n->net));
        shift @a while @a && $a[0] == 0;
        printf "\taddr is %s [%d.%d.%d.%d]\n", $n->net, @a;
     }

     if ($n = getnetbyaddr($n->net)) {
        if (lc($n->name) ne lc($net)) {
            printf "\tThat addr reverses to net %s!\n", $n->name;
            $net = $n->name;
            redo;
        }
     }
      }

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


Net::protoent - by-name interface to Perl's built-in getproto* functions

  • NOTE
  • AUTHOR

NAME

Net::protoent - by-name interface to Perl's built-in getproto*() functions

SYNOPSIS

 use Net::protoent;
 $p = getprotobyname(shift || 'tcp') || die "no proto";
 printf "proto for %s is %d, aliases are %s\n",
    $p->name, $p->proto, "@{$p->aliases}";

 use Net::protoent qw(:FIELDS);
 getprotobyname(shift || 'tcp') || die "no proto";
 print "proto for $p_name is $p_proto, aliases are @p_aliases\n";

DESCRIPTION

This module's default exports override the core getprotoent(), getprotobyname(), and getnetbyport() functions, replacing them with versions that return "Net::protoent" objects. They take default second arguments of "tcp". This object has methods that return the similarly named structure field name from the C's protoent structure from netdb.h; namely name, aliases, and proto. The aliases method returns an array reference, the rest scalars.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding p_. Thus, $proto_obj->name() corresponds to $p_name if you import the fields. Array references are available as regular array variables, so for example @{ $proto_obj->aliases() } would be simply @p_aliases.

The getproto() function is a simple front-end that forwards a numeric argument to getprotobyport(), and the rest to getprotobyname().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


Net::servent - by-name interface to Perl's built-in getserv* functions

  • EXAMPLES
  • NOTE
  • AUTHOR

NAME

Net::servent - by-name interface to Perl's built-in getserv*() functions

SYNOPSIS

 use Net::servent;
 $s = getservbyname(shift || 'ftp') || die "no service";
 printf "port for %s is %s, aliases are %s\n",
    $s->name, $s->port, "@{$s->aliases}";

 use Net::servent qw(:FIELDS);
 getservbyname(shift || 'ftp') || die "no service";
 print "port for $s_name is $s_port, aliases are @s_aliases\n";

DESCRIPTION

This module's default exports override the core getservent(), getservbyname(), and getnetbyport() functions, replacing them with versions that return "Net::servent" objects. They take default second arguments of "tcp". This object has methods that return the similarly named structure field name from the C's servent structure from netdb.h; namely name, aliases, port, and proto. The aliases method returns an array reference, the rest scalars.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding s_. Thus, $serv_obj->name() corresponds to $s_name if you import the fields. Array references are available as regular array variables, so for example @{ $serv_obj->aliases()} would be simply @s_aliases.

The getserv() function is a simple front-end that forwards a numeric argument to getservbyport(), and the rest to getservbyname().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

EXAMPLES

 use Net::servent qw(:FIELDS);

 while (@ARGV) {
     my ($service, $proto) = ((split m!/!, shift), 'tcp');
     my $valet = getserv($service, $proto);
     unless ($valet) {
         warn "$0: No service: $service/$proto\n"
         next;
     }
     printf "service $service/$proto is port %d\n", $valet->port;
     print "alias are @s_aliases\n" if @s_aliases;
 }

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


O - Generic interface to Perl Compiler backends

  • CONVENTIONS
  • IMPLEMENTATION
  • BUGS
  • AUTHOR

NAME

O - Generic interface to Perl Compiler backends

SYNOPSIS

        perl -MO=[-q,]Backend[,OPTIONS] foo.pl

DESCRIPTION

This is the module that is used as a frontend to the Perl Compiler.

If you pass the -q option to the module, then the STDOUT filehandle will be redirected into the variable $O::BEGIN_output during compilation. This has the effect that any output printed to STDOUT by BEGIN blocks or use'd modules will be stored in this variable rather than printed. It's useful with those backends which produce output themselves (Deparse, Concise etc), so that their output is not confused with that generated by the code being compiled.

The -qq option behaves like -q, except that it also closes STDERR after deparsing has finished. This suppresses the "Syntax OK" message normally produced by perl.

CONVENTIONS

Most compiler backends use the following conventions: OPTIONS consists of a comma-separated list of words (no white-space). The -v option usually puts the backend into verbose mode. The -ofile option generates output to file instead of stdout. The -D option followed by various letters turns on various internal debugging flags. See the documentation for the desired backend (named B::Backend for the example above) to find out about that backend.

IMPLEMENTATION

This section is only necessary for those who want to write a compiler backend module that can be used via this module.

The command-line mentioned in the SYNOPSIS section corresponds to the Perl code

    use O ("Backend", OPTIONS);

The import function which that calls loads in the appropriate B::Backend module and calls the compile function in that package, passing it OPTIONS. That function is expected to return a sub reference which we'll call CALLBACK. Next, the "compile-only" flag is switched on (equivalent to the command-line option -c) and a CHECK block is registered which calls CALLBACK. Thus the main Perl program mentioned on the command-line is read in, parsed and compiled into internal syntax tree form. Since the -c flag is set, the program does not start running (excepting BEGIN blocks of course) but the CALLBACK function registered by the compiler backend is called.

In summary, a compiler backend module should be called "B::Foo" for some foo and live in the appropriate directory for that name. It should define a function called compile. When the user types

    perl -MO=Foo,OPTIONS foo.pl

that function is called and is passed those OPTIONS (split on commas). It should return a sub ref to the main compilation function. After the user's program is loaded and parsed, that returned sub ref is invoked which can then go ahead and do the compilation, usually by making use of the B module's functionality.

BUGS

The -q and -qq options don't work correctly if perl isn't compiled with PerlIO support : STDOUT will be closed instead of being redirected to $O::BEGIN_output.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk


Opcode - Disable named opcodes when compiling perl code

  • NOTE
  • WARNING
  • Operator Names and Operator Lists
  • Opcode Functions
  • Manipulating Opsets
  • TO DO (maybe)
  • Predefined Opcode Tags
  • SEE ALSO
  • AUTHORS

NAME

Opcode - Disable named opcodes when compiling perl code

SYNOPSIS

  use Opcode;

DESCRIPTION

Perl code is always compiled into an internal format before execution.

Evaluating perl code (e.g. via "eval" or "do 'file'") causes the code to be compiled into an internal format and then, provided there was no error in the compilation, executed. The internal format is based on many distinct opcodes.

By default no opmask is in effect and any code can be compiled.

The Opcode module allow you to define an operator mask to be in effect when perl next compiles any code. Attempting to compile code which contains a masked opcode will cause the compilation to fail with an error. The code will not be executed.

NOTE

The Opcode module is not usually used directly. See the ops pragma and Safe modules for more typical uses.

WARNING

The authors make no warranty, implied or otherwise, about the suitability of this software for safety or security purposes.

The authors shall not in any case be liable for special, incidental, consequential, indirect or other similar damages arising from the use of this software.

Your mileage will vary. If in any doubt do not use it.

Operator Names and Operator Lists

The canonical list of operator names is the contents of the array PL_op_name defined and initialised in file opcode.h of the Perl source distribution (and installed into the perl library).

Each operator has both a terse name (its opname) and a more verbose or recognisable descriptive name. The opdesc function can be used to return a list of descriptions for a list of operators.

Many of the functions and methods listed below take a list of operators as parameters. Most operator lists can be made up of several types of element. Each element can be one of

an operator name (opname)

Operator names are typically small lowercase words like enterloop, leaveloop, last, next, redo etc. Sometimes they are rather cryptic like gv2cv, i_ncmp and ftsvtx.

an operator tag name (optag)

Operator tags can be used to refer to groups (or sets) of operators. Tag names always begin with a colon. The Opcode module defines several optags and the user can define others using the define_optag function.

a negated opname or optag

An opname or optag can be prefixed with an exclamation mark, e.g., !mkdir. Negating an opname or optag means remove the corresponding ops from the accumulated set of ops at that point.

an operator set (opset)

An opset as a binary string of approximately 44 bytes which holds a set or zero or more operators.

The opset and opset_to_ops functions can be used to convert from a list of operators to an opset and vice versa.

Wherever a list of operators can be given you can use one or more opsets. See also Manipulating Opsets below.

Opcode Functions

The Opcode package contains functions for manipulating operator names tags and sets. All are available for export by the package.

opcodes

In a scalar context opcodes returns the number of opcodes in this version of perl (around 350 for perl-5.7.0).

In a list context it returns a list of all the operator names. (Not yet implemented, use @names = opset_to_ops(full_opset).)

opset (OP, ...)

Returns an opset containing the listed operators.

opset_to_ops (OPSET)

Returns a list of operator names corresponding to those operators in the set.

opset_to_hex (OPSET)

Returns a string representation of an opset. Can be handy for debugging.

full_opset

Returns an opset which includes all operators.

empty_opset

Returns an opset which contains no operators.

invert_opset (OPSET)

Returns an opset which is the inverse set of the one supplied.

verify_opset (OPSET, ...)

Returns true if the supplied opset looks like a valid opset (is the right length etc) otherwise it returns false. If an optional second parameter is true then verify_opset will croak on an invalid opset instead of returning false.

Most of the other Opcode functions call verify_opset automatically and will croak if given an invalid opset.

define_optag (OPTAG, OPSET)

Define OPTAG as a symbolic name for OPSET. Optag names always start with a colon :.

The optag name used must not be defined already (define_optag will croak if it is already defined). Optag names are global to the perl process and optag definitions cannot be altered or deleted once defined.

It is strongly recommended that applications using Opcode should use a leading capital letter on their tag names since lowercase names are reserved for use by the Opcode module. If using Opcode within a module you should prefix your tags names with the name of your module to ensure uniqueness and thus avoid clashes with other modules.

opmask_add (OPSET)

Adds the supplied opset to the current opmask. Note that there is currently no mechanism for unmasking ops once they have been masked. This is intentional.

opmask

Returns an opset corresponding to the current opmask.

opdesc (OP, ...)

This takes a list of operator names and returns the corresponding list of operator descriptions.

opdump (PAT)

Dumps to STDOUT a two column list of op names and op descriptions. If an optional pattern is given then only lines which match the (case insensitive) pattern will be output.

It's designed to be used as a handy command line utility:

        perl -MOpcode=opdump -e opdump
        perl -MOpcode=opdump -e 'opdump Eval'

Manipulating Opsets

Opsets may be manipulated using the perl bit vector operators & (and), | (or), ^ (xor) and ~ (negate/invert).

However you should never rely on the numerical position of any opcode within the opset. In other words both sides of a bit vector operator should be opsets returned from Opcode functions.

Also, since the number of opcodes in your current version of perl might not be an exact multiple of eight, there may be unused bits in the last byte of an upset. This should not cause any problems (Opcode functions ignore those extra bits) but it does mean that using the ~ operator will typically not produce the same 'physical' opset 'string' as the invert_opset function.

TO DO (maybe)

    $bool = opset_eq($opset1, $opset2)  true if opsets are logically eqiv
    $yes = opset_can($opset, @ops)      true if $opset has all @ops set
    @diff = opset_diff($opset1, $opset2) => ('foo', '!bar', ...)

Predefined Opcode Tags

:base_core
    null stub scalar pushmark wantarray const defined undef
    rv2sv sassign
    rv2av aassign aelem aelemfast aslice av2arylen
    rv2hv helem hslice each values keys exists delete
    preinc i_preinc predec i_predec postinc i_postinc postdec i_postdec
    int hex oct abs pow multiply i_multiply divide i_divide
    modulo i_modulo add i_add subtract i_subtract
    left_shift right_shift bit_and bit_xor bit_or negate i_negate
    not complement
    lt i_lt gt i_gt le i_le ge i_ge eq i_eq ne i_ne ncmp i_ncmp
    slt sgt sle sge seq sne scmp
    substr vec stringify study pos length index rindex ord chr
    ucfirst lcfirst uc lc quotemeta trans chop schop chomp schomp
    match split qr
    list lslice splice push pop shift unshift reverse
    cond_expr flip flop andassign orassign and or xor
    warn die lineseq nextstate scope enter leave setstate
    rv2cv anoncode prototype
    entersub leavesub leavesublv return method method_named -- XXX loops via recursion?
    leaveeval -- needed for Safe to operate, is safe without entereval
:base_mem

These memory related ops are not included in :base_core because they can easily be used to implement a resource attack (e.g., consume all available memory).

    concat repeat join range
    anonlist anonhash

Note that despite the existence of this optag a memory resource attack may still be possible using only :base_core ops.

Disabling these ops is a very heavy handed way to attempt to prevent a memory resource attack. It's probable that a specific memory limit mechanism will be added to perl in the near future.

:base_loop

These loop ops are not included in :base_core because they can easily be used to implement a resource attack (e.g., consume all available CPU time).

    grepstart grepwhile
    mapstart mapwhile
    enteriter iter
    enterloop leaveloop unstack
    last next redo
    goto
:base_io

These ops enable filehandle (rather than filename) based input and output. These are safe on the assumption that only pre-existing filehandles are available for use. To create new filehandles other ops such as open would need to be enabled.

    readline rcatline getc read
    formline enterwrite leavewrite
    print sysread syswrite send recv
    eof tell seek sysseek
    readdir telldir seekdir rewinddir
:base_orig

These are a hotchpotch of opcodes still waiting to be considered

    gvsv gv gelem
    padsv padav padhv padany
    rv2gv refgen srefgen ref
    bless -- could be used to change ownership of objects (reblessing)
    pushre regcmaybe regcreset regcomp subst substcont
    sprintf prtf -- can core dump
    crypt
    tie untie
    dbmopen dbmclose
    sselect select
    pipe_op sockpair
    getppid getpgrp setpgrp getpriority setpriority localtime gmtime
    entertry leavetry -- can be used to 'hide' fatal errors
    custom -- where should this go
:base_math

These ops are not included in :base_core because of the risk of them being used to generate floating point exceptions (which would have to be caught using a $SIG{FPE} handler).

    atan2 sin cos exp log sqrt

These ops are not included in :base_core because they have an effect beyond the scope of the compartment.

    rand srand
:base_thread

These ops are related to multi-threading.

    lock threadsv
:default

A handy tag name for a reasonable default set of ops. (The current ops allowed are unstable while development continues. It will change.)

    :base_core :base_mem :base_loop :base_io :base_orig :base_thread

If safety matters to you (and why else would you be using the Opcode module?) then you should not rely on the definition of this, or indeed any other, optag!

:filesys_read
    stat lstat readlink
    ftatime ftblk ftchr ftctime ftdir fteexec fteowned fteread
    ftewrite ftfile ftis ftlink ftmtime ftpipe ftrexec ftrowned
    ftrread ftsgid ftsize ftsock ftsuid fttty ftzero ftrwrite ftsvtx
    fttext ftbinary
    fileno
:sys_db
    ghbyname ghbyaddr ghostent shostent ehostent      -- hosts
    gnbyname gnbyaddr gnetent snetent enetent         -- networks
    gpbyname gpbynumber gprotoent sprotoent eprotoent -- protocols
    gsbyname gsbyport gservent sservent eservent      -- services
    gpwnam gpwuid gpwent spwent epwent getlogin       -- users
    ggrnam ggrgid ggrent sgrent egrent                -- groups
:browse

A handy tag name for a reasonable default set of ops beyond the :default optag. Like :default (and indeed all the other optags) its current definition is unstable while development continues. It will change.

The :browse tag represents the next step beyond :default. It it a superset of the :default ops and adds :filesys_read the :sys_db. The intent being that scripts can access more (possibly sensitive) information about your system but not be able to change it.

    :default :filesys_read :sys_db
:filesys_open
    sysopen open close
    umask binmode
    open_dir closedir -- other dir ops are in :base_io
:filesys_write
    link unlink rename symlink truncate
    mkdir rmdir
    utime chmod chown
    fcntl -- not strictly filesys related, but possibly as dangerous?
:subprocess
    backtick system
    fork
    wait waitpid
    glob -- access to Cshell via <`rm *`>
:ownprocess
    exec exit kill
    time tms -- could be used for timing attacks (paranoid?)
:others

This tag holds groups of assorted specialist opcodes that don't warrant having optags defined for them.

SystemV Interprocess Communications:

    msgctl msgget msgrcv msgsnd
    semctl semget semop
    shmctl shmget shmread shmwrite
:still_to_be_decided
    chdir
    flock ioctl
    socket getpeername ssockopt
    bind connect listen accept shutdown gsockopt getsockname
    sleep alarm -- changes global timer state and signal handling
    sort -- assorted problems including core dumps
    tied -- can be used to access object implementing a tie
    pack unpack -- can be used to create/use memory pointers
    entereval -- can be used to hide code from initial compile
    require dofile
    caller -- get info about calling environment and args
    reset
    dbstate -- perl -d version of nextstate(ment) opcode
:dangerous

This tag is simply a bucket for opcodes that are unlikely to be used via a tag name but need to be tagged for completeness and documentation.

    syscall dump chroot

SEE ALSO

ops(3) -- perl pragma interface to Opcode module.

Safe(3) -- Opcode and namespace limited execution compartments

AUTHORS

Originally designed and implemented by Malcolm Beattie, mbeattie@sable.ox.ac.uk as part of Safe version 1.

Split out from Safe module version 1, named opcode tags and other changes added by Tim Bunce.


Oraperl - Perl access to Oracle databases for old oraperl scripts

    • Principal Functions
    • Ancillary Functions
  • VARIABLES
    • Customisation Variables
    • Status Variables
  • SUBSTITUTION VARIABLES
  • DEBUGGING
  • EXAMPLE
  • NOTES
  • WARNINGS
  • SEE ALSO
  • AUTHOR
  • MAINTAINER
  • COPYRIGHT

NAME

Oraperl - Perl access to Oracle databases for old oraperl scripts

SYNOPSIS

  eval 'use Oraperl; 1;' || die $@ if $] >= 5;  # ADD THIS LINE TO OLD SCRIPTS

  $lda = &ora_login($system_id, $name, $password)
  $csr = &ora_open($lda, $stmt [, $cache])
  &ora_bind($csr, $var, ...)
  &ora_fetch($csr [, $trunc])
  &ora_close($csr)
  &ora_logoff($lda)
  &ora_do($lda, $stmt)
  &ora_titles($csr)
  &ora_lengths($csr)
  &ora_types($csr)
  &ora_commit($lda)
  &ora_rollback($lda)
  &ora_autocommit($lda, $on_off)
  &ora_version()
  $ora_cache
  $ora_long
  $ora_trunc
  $ora_errno
  $ora_errstr
  $ora_verno
  $ora_debug

DESCRIPTION

Oraperl is an extension to Perl which allows access to Oracle databases.

The original oraperl was a Perl 4 binary with Oracle OCI compiled into it. The Perl 5 Oraperl module described here is distributed with the DBD::Oracle manpage (a database driver what operates within the DBI manpage) and adds an extra layer over the DBI manpage method calls. The Oraperl module should only be used to allow existing Perl 4 oraperl scripts to run with minimal changes; any new development should use the DBI manpage directly.

The functions which make up this extension are described in the following sections. All functions return a false or undefined (in the Perl sense) value to indicate failure. You do not need to understand the references to OCI in these descriptions. They are here to help those who wish to extend the routines or to port them to new machines.

The text in this document is largely unchanged from the original Perl4 oraperl manual written by Kevin Stock <kstock@auspex.fr>. Any comments specific to the DBD::Oracle Oraperl emulation are prefixed by DBD:. See the DBD::Oracle and DBI manuals for more information.

DBD: In order to make the oraperl function definitions available in perl5 you need to arrange to 'use' the Oraperl.pm module in each file or package which uses them. You can do this by simply adding use Oraperl; in each file or package. If you need to make the scripts work with both the perl4 oraperl and perl5 you should add add the following text instead:

  eval 'use Oraperl; 1;' || die $@ if $] >= 5;

Principal Functions

The main functions for database access are &ora_login(), &ora_open(), &ora_bind(), &ora_fetch(), &ora_close(), &ora_do() and &ora_logoff().

  • ora_login
      $lda = &ora_login($system_id, $username, $password)

    In order to access information held within an Oracle database, a program must first log in to it by calling the &ora_login() function. This function is called with three parameters, the system ID (see below) of the Oracle database to be used, and the Oracle username and password. The value returned is a login identifier (actually an Oracle Login Data Area) referred to below as $lda.

    Multiple logins may be active simultaneously. This allows a simple mechanism for correlating or transferring data between databases.

    Most Oracle programs (for example, SQL*Plus or SQL*Forms) examine the environment variable ORACLE_SID or TWO_TASK to determine which database to connect to. In an environment which uses several different databases, it is easy to make a mistake, and attempt to run a program on the wrong one. Also, it is cumbersome to create a program which works with more than one database simultaneously. Therefore, Oraperl requires the system ID to be passed as a parameter. However, if the system ID parameter is an empty string then oracle will use the existing value of ORACLE_SID or TWO_TASK in the usual manner.

    Example:

      $lda = &ora_login('personnel', 'scott', 'tiger') || die $ora_errstr;

    This function is equivalent to the OCI olon and orlon functions.

    DBD: note that a name is assumed to be a TNS alias if it does not appear as the name of a SID in /etc/oratab or /var/opt/oracle/oratab. See the code in Oracle.pm for the full logic of database name handling.

    DBD: Since the returned $lda is a Perl5 reference the database login identifier is now automatically released if $lda is overwritten or goes out of scope.

  • ora_open
      $csr = &ora_open($lda, $statement [, $cache])

    To specify an SQL statement to be executed, the program must call the &ora_open() function. This function takes at least two parameters: a login identifier (obtained from &ora_login()) and the SQL statement to be executed. An optional third parameter specifies the size of the row cache to be used for a SELECT statement. The value returned from &ora_open() is a statement identifier (actually an ORACLE Cursor) referred to below as $csr.

    If the row cache size is not specified, a default size is used. As distributed, the default is five rows, but this may have been changed at your installation (see the &ora_version() function and $ora_cache variable below).

    Examples:

     $csr = &ora_open($lda, 'select ename, sal from emp order by ename', 10);

     $csr = &ora_open($lda, 'insert into dept values(:1, :2, :3)');

    This function is equivalent to the OCI oopen and oparse functions. For statements which do not contain substitution variables (see the section Substitution Variables below), it also uses of the oexec function. For SELECT statements, it also makes use of the odescr and odefin functions to allocate memory for the values to be returned from the database.

  • ora_bind
      &ora_bind($csr, $var, ...)

    If an SQL statement contains substitution variables (see the section Substitution Variables below), &ora_bind() is used to assign actual values to them. This function takes a statement identifier (obtained from &ora_open()) as its first parameter, followed by as many parameters as are required by the statement.

    Example:

     &ora_bind($csr, 50, 'management', 'Paris');

    This function is equivalent to the OCI obndrn and oexec statements.

    The OCI obndrn function does not allow empty strings to be bound. As distributed, $ora_bind therefore replaces empty strings with a single space. However, a compilation option allows this substitution to be suppressed, causing &ora_bind() to fail. The output from the &ora_version() function specifies which is the case at your installation.

  • ora_fetch
     $nfields = &ora_fetch($csr)
     @data = &ora_fetch($csr [, $trunc])

    The &ora_fetch() function is used in conjunction with a SQL SELECT statement to retrieve information from a database. This function takes one mandatory parameter, a statement identifier (obtained from &ora_open()).

    Used in a scalar context, the function returns the number of fields returned by the query but no data is actually fetched. This may be useful in a program which allows a user to enter a statement interactively.

    Example:

     $nfields = &ora_fetch($csr);

    Used in an array context, the value returned is an array containing the data, one element per field. Note that this will not work as expected:

     @data = &ora_fetch($csr) || die "...";    # WRONG

    The || forces a scalar context so ora_fetch returns the number of fields.

    An optional second parameter may be supplied to indicate whether the truncation of a LONG or LONG RAW field is to be permitted (non-zero) or considered an error (zero). If this parameter is not specified, the value of the global variable $ora_trunc is used instead. Truncation of other datatypes is always considered a error.

    DBD: The optional second parameter to ora_fetch is not supported. A DBI usage error will be generated if a second parameter is supplied. Use the global variable $ora_trunc instead. Also note that the experimental DBI blob_read method can be used to retrieve a long:

      $csr->blob_read($field, $offset, $len [, \$dest, $destoffset]);

    If truncation occurs, $ora_errno will be set to 1406. &ora_fetch() will complete successfully if truncation is permitted, otherwise it will fail.

    &ora_fetch() will fail at the end of the data or if an error occurs. It is possible to distinguish between these cases by testing the value of the variable $ora_errno. This will be zero for end of data, non-zero if an error has occurred.

    Example:

     while (($deptno, $dname, $loc) = &ora_fetch($csr))
 {
   warn "Truncated!!!" if $ora_errno == 1406;
   # do something with the data
 }
 warn $ora_errstr if $ora_errno;

    This function is equivalent to the OCI ofetch function.

  • ora_close
     &ora_close($csr)

    If an SQL statement is no longer required (for example, all the data selected has been processed, or no more rows are to be inserted) then the statement identifier should be released. This is done by calling the &ora_close() function with the statement identifier as its only parameter.

    This function is equivalent to the OCI oclose function.

    DBD: Since $csr is a Perl5 reference the statement/cursor is now automatically closed if $csr is overwritten or goes out of scope.

  • ora_do
      &ora_do($lda, $statement)

    Not all SQL statements return data or contain substitution variables. In these cases the &ora_do() function may be used as an alternative to &ora_open() and &ora_close(). This function takes two parameters, a login identifier and the statement to be executed.

    Example:

     &ora_do($lda, 'drop table employee');

    This function is roughly equivalent to

     &ora_close( &ora_open($lda, $statement) )

    DBD: oraperl v2 used to return the string 'OK' to indicate success with a zero numeric value. The Oraperl emulation now uses the string '0E0' to achieve the same effect since it does not cause any -w warnings when used in a numeric context.

  • ora_logoff
      &ora_logoff($lda)

    When the program no longer needs to access a given database, the login identifier should be released using the &ora_logoff() function.

    This function is equivalent to the OCI ologoff function.

    DBD: Since $lda is a Perl5 reference the database login identifier is now automatically released if $lda is overwritten or goes out of scope.

Ancillary Functions

Additional functions available are: &ora_titles(),
&ora_lengths(), &ora_types(), &ora_autocommit(),
&ora_commit(), &ora_rollback() and &ora_version().

The first three are of most use within a program which allows statements to be entered interactively. See, for example, the sample program sql which is supplied with Oraperl and may have been installed at your site.

  • ora_titles
      @titles = &ora_titles($csr)

    A program may determine the field titles of an executed query by calling &ora_titles(). This function takes a single parameter, a statement identifier (obtained from &ora_open()) indicating the query for which the titles are required. The titles are returned as an array of strings, one for each column.

    Titles are truncated to the length of the field, as reported by the &ora_lengths() function.

    DBD: oraperl v2.2 actually changed the behaviour such that the titles were not truncated unless an optional second parameter was true. This was not reflected in the oraperl manual. The Oraperl emulation adopts the non truncating behaviour and doesn't support the truncate parameter.

  • ora_lengths
      @lengths = &ora_lengths($csr)

    A program may determine the length of each of the fields returned by a query by calling the &ora_lengths() function. This function takes a single parameter, a statement identifier (obtained from &ora_open()) indicating the query for which the lengths are required. The lengths are returned as an array of integers, one for each column.

  • ora_types
      @types = &ora_types($csr)

    A program may determine the type of each of the fields returned by a query by calling the &ora_types() function. This function takes a single parameter, a statement identifier (obtained from &ora_open()) indicating the query for which the lengths are required. The types are returned as an array of integers, one for each field.

    These types are defined in your OCI documentation. The correct interpretation for Oracle v6 is given in the file oraperl.ph.

  • ora_autocommit
      &ora_autocommit($lda, $on_or_off)

    Autocommit mode (in which each transaction is committed immediately, without waiting for an explicit commit) may be enabled or disabled using &ora_autocommit(). This function takes two parameters, a login identifier (obtained from &ora_login()) and a true/false value indicating whether autocommit is to be enabled (non-zero) or disabled (zero). By default, autocommit is off.

    Note that autocommit can only be set per login, not per statement. If you need to control autocommit by statement (for example, to allow deletions to be rolled back, but insertions to be committed immediately) you should make multiple calls to &ora_login() and use a separate login identifier for each statement.

  • ora_commit, ora_rollback
      &ora_commit($lda)
  &ora_rollback($lda)

    Modifications to a database may be committed or rolled back using the &ora_commit() and &ora_rollback() functions. These functions take a single parameter, a login identifier obtained from &ora_login().

    Transactions which have been committed (either explicitly by a call to &ora_commit() or implicitly through the use of &ora_autocommit()) cannot be subsequently rolled back.

    Note that commit and rollback can only be used per login, not per statement. If you need to commit or rollback by statement you should make multiple calls to &ora_login() and use a separate login identifier for each statement.

  • ora_version
      &ora_version()

    The &ora_version() function prints the version number and copyright information concerning Oraperl. It also prints the values of various compilation time options. It does not return any value, and should not normally be used in a program.

    Example:

      perl -MOraperl -e 'ora_version()'
      This is Oraperl, version 2, patch level 0.
      Debugging is available, including the -D flag.
  Default fetch row cache size is 5.
  Empty bind values are replaced by a space.
      Perl is copyright by Larry Wall; type oraperl -v for details.
  Additions for oraperl: Copyright 1991, 1992, Kevin Stock.

      Oraperl may be distributed under the same conditions as Perl.

    This function is the equivalent of Perl's -v flag.

    DBD: The Oraperl emulation printout is similar but not identical.

VARIABLES

Six special variables are provided, $ora_cache, $ora_long, $ora_trunc, $ora_errno, $ora_errstr and $ora_verno.

Customisation Variables

These variables are used to dictate the behaviour of Oraperl under certain conditions.

  • $ora_cache

    The $ora_cache variable determines the default cache size used by the &ora_open() function for SELECT statements if an explicit cache size is not given.

    It is initialised to the default value reported by &ora_version() but may be set within a program to apply to all subsequent calls to &ora_open(). Cursors which are already open are not affected. As distributed, the default value is five, but may have been altered at your installation.

    As a special case, assigning zero to $ora_cache resets it to the default value. Attempting to set $ora_cache to a negative value results in a warning.

  • $ora_long

    Normally, Oraperl interrogates the database to determine the length of each field and allocates buffer space accordingly. This is not possible for fields of type LONG or LONGRAW. To allocate space according to the maximum possible length (65535 bytes) would obviously be extremely wasteful of memory.

    Therefore, when &ora_open() determines that a field is a LONG type, it allocates the amount of space indicated by the $ora_long variable. This is initially set to 80 (for compatibility with Oracle products) but may be set within a program to whatever size is required.

    $ora_long is only used when fetching data, not when inserting it.

  • $ora_trunc

    Since Oraperl cannot determine exactly the maximum length of a LONG field, it is possible that the length indicated by $ora_long is not sufficient to store the data fetched. In such a case, the optional second parameter to &ora_fetch() indicates whether the truncation should be allowed or should provoke an error.

    If this second parameter is not specified, the value of $ora_trunc is used as a default. This only applies to LONG and LONGRAW data types. Truncation of a field of any other type is always considered an error (principally because it indicates a bug in Oraperl).

Status Variables

These variables report information about error conditions or about Oraperl itself. They may only be read; a fatal error occurs if a program attempts to change them.

  • $ora_errno

    $ora_errno contains the Oracle error code provoked by the last function call.

    There are two cases of particular interest concerning &ora_fetch(). If a LONG or LONGRAW field is truncated (and truncation is allowed) then &ora_fetch() will complete successfully but $ora_errno will be set to 1406 to indicate the truncation. When &ora_fetch() fails, $ora_errno will be set to zero if this was due to the end of data or an error code if it was due to an actual error.

  • $ora_errstr

    The $ora_errstr variable contains the Oracle error message corresponding to the current value of $ora_errno.

  • $ora_verno

    The $ora_verno variable contains the version number of Oraperl in the form v.ppp where v is the major version number and ppp is the patchlevel. For example, in Oraperl version 3, patch level 142, $ora_verno would contain the value 3.142 (more or less, allowing for floating point error).

SUBSTITUTION VARIABLES

Oraperl allows an SQL statement to contain substitution variables. These consist of a colon followed by a number. For example, a program which added records to a telephone list might use the following call to &ora_open():

  $csr = &ora_open($csr, "insert into telno values(:1, :2)");

The two names :1 and :2 are called substitution variables. The function &ora_bind() is used to assign values to these variables. For example, the following statements would add two new people to the list:

  &ora_bind($csr, "Annette", "472-8836");
  &ora_bind($csr, "Brian", "937-1823");

Note that the substitution variables must be assigned consecutively beginning from 1 for each SQL statement, as &ora_bind() assigns its parameters in this order. Named substitution variables (for example, :NAME, :TELNO) are not permitted.

DBD: Substitution variables are now bound as type 1 (VARCHAR2) and not type 5 (STRING) by default. This can alter the behaviour of SQL code which compares a char field with a substitution variable. See the String Comparison section in the Datatypes chapter of the Oracle OCI manual for more details.

You can work around this by using DBD::Oracle's ability to specify the Oracle type to be used on a per field basis:

  $char_attrib = { ora_type => 5 }; # 5 = STRING (ala oraperl2.4)
  $csr = ora_open($dbh, "select foo from bar where x=:1 and y=:2");
  $csr->bind_param(1, $value_x, $char_attrib);
  $csr->bind_param(2, $value_y, $char_attrib);
  ora_bind($csr);  # bind with no parameters since we've done bind_param()'s

DEBUGGING

DBD: The Oraperl $ora_debug variable is not supported. However detailed debugging can be enabled at any time by executing

  $h->debug(2);

where $h is either a $lda or a $csr. If debugging is enabled on an $lda then it is automatically passed on to any cursors returned by &ora_open().

EXAMPLE

  format STDOUT_TOP =
  Name Phone
  ==== =====
  .
  format STDOUT =
  @<<<<<<<<<< @>>>>>>>>>>
  $name, $phone
  .
  die "You should use oraperl, not perl\n" unless defined &ora_login;
  $ora_debug = shift if $ARGV[0] =~ /^\-#/;

  $lda = &ora_login('t', 'kstock', 'kstock')
            || die $ora_errstr;
  $csr = &ora_open($lda, 'select * from telno order by name')
            || die $ora_errstr;

  $nfields = &ora_fetch($csr);
  print "Query will return $nfields fields\n\n";

  while (($name, $phone) = &ora_fetch($csr)) { write; }
  warn $ora_errstr if $ora_errno;

  die "fetch error: $ora_errstr" if $ora_errno;

  do ora_close($csr) || die "can't close cursor";
  do ora_logoff($lda) || die "can't log off Oracle";

NOTES

In keeping with the philosophy of Perl, there is no pre-defined limit to the number of simultaneous logins or SQL statements which may be active, nor to the number of data fields which may be returned by a query. The only limits are those imposed by the amount of memory available, or by Oracle.

WARNINGS

The Oraperl emulation software shares no code with the original oraperl. It is built on top of the new Perl5 DBI and DBD::Oracle modules. These modules are still evolving. (One of the goals of the Oraperl emulation software is to allow useful work to be done with the DBI and DBD::Oracle modules whilst insulating users from the ongoing changes in their interfaces.)

It is quite possible, indeed probable, that some differences in behaviour will exist. These are probably confined to error handling.

All differences in behaviour which are not documented here should be reported to to dbi-users@perl.org.

SEE ALSO

Oracle Documentation

SQL Language Reference Manual. Programmer's Guide to the Oracle Call Interfaces.

Books

Programming Perl by Larry Wall and Randal Schwartz. Learning Perl by Randal Schwartz.

Manual Pages

perl(1)

AUTHOR

Original Oraperl 2.4 code and documentation by Kevin Stock <kstock@auspex.fr>.

DBI and Oraperl emulation using DBD::Oracle by Tim Bunce.

MAINTAINER

As of DBD::Oracle release 1.17 in February 2006 The Pythian Group, Inc.
(L<http://www.pythian.com>;) are taking the lead in maintaining DBD::Oracle with
my assistance and gratitude.

COPYRIGHT

Copyright (c) 1994-2006 Tim Bunce. Ireland.

The DBD::Oracle module is free open source software; you can redistribute it and/or modify it under the same terms as Perl 5.


POSIX - Perl interface to IEEE Std 1003.1

  • NOTE
  • CAVEATS
  • FUNCTIONS
  • CLASSES
    • POSIX::SigAction
    • POSIX::SigSet
    • POSIX::Termios
  • PATHNAME CONSTANTS
  • POSIX CONSTANTS
  • SYSTEM CONFIGURATION
  • ERRNO
  • FCNTL
  • FLOAT
  • LIMITS
  • LOCALE
  • MATH
  • SIGNAL
  • STAT
  • STDLIB
  • STDIO
  • TIME
  • UNISTD
  • WAIT

NAME

POSIX - Perl interface to IEEE Std 1003.1

SYNOPSIS

    use POSIX;
    use POSIX qw(setsid);
    use POSIX qw(:errno_h :fcntl_h);

    printf "EINTR is %d\n", EINTR;

    $sess_id = POSIX::setsid();

    $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
        # note: that's a filedescriptor, *NOT* a filehandle

DESCRIPTION

The POSIX module permits you to access all (or nearly all) the standard POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish interfaces.

Everything is exported by default with the exception of any POSIX functions with the same name as a built-in Perl function, such as abs, alarm, rmdir, write, etc.., which will be exported only if you ask for them explicitly. This is an unfortunate backwards compatibility feature. You can stop the exporting by saying use POSIX () and then use the fully qualified names (ie. POSIX::SEEK_END).

This document gives a condensed list of the features available in the POSIX module. Consult your operating system's manpages for general information on most features. Consult the perlfunc manpage for functions which are noted as being identical to Perl's builtin functions.

The first section describes POSIX functions from the 1003.1 specification. The second section describes some classes for signal objects, TTY objects, and other miscellaneous objects. The remaining sections list various constants and macros in an organization which roughly follows IEEE Std 1003.1b-1993.

NOTE

The POSIX module is probably the most complex Perl module supplied with the standard distribution. It incorporates autoloading, namespace games, and dynamic loading of code that's in Perl, C, or both. It's a great source of wisdom.

CAVEATS

A few functions are not implemented because they are C specific. If you attempt to call these, they will print a message telling you that they aren't implemented, and suggest using the Perl equivalent should one exist. For example, trying to access the setjmp() call will elicit the message "setjmp() is C-specific: use eval {} instead".

Furthermore, some evil vendors will claim 1003.1 compliance, but in fact are not so: they will not pass the PCTS (POSIX Compliance Test Suites). For example, one vendor may not define EDEADLK, or the semantics of the errno values set by open(2) might not be quite right. Perl does not attempt to verify POSIX compliance. That means you can currently successfully say "use POSIX", and then later in your program you find that your vendor has been lax and there's no usable ICANON macro after all. This could be construed to be a bug.

FUNCTIONS

_exit

This is identical to the C function _exit(). It exits the program immediately which means among other things buffered I/O is not flushed.

Note that when using threads and in Linux this is not a good way to exit a thread because in Linux processes and threads are kind of the same thing (Note: while this is the situation in early 2003 there are projects under way to have threads with more POSIXly semantics in Linux). If you want not to return from a thread, detach the thread.

abort

This is identical to the C function abort(). It terminates the process with a SIGABRT signal unless caught by a signal handler or if the handler does not return normally (it e.g. does a longjmp).

abs

This is identical to Perl's builtin abs() function, returning the absolute value of its numerical argument.

access

Determines the accessibility of a file.

        if( POSIX::access( "/", &POSIX::R_OK ) ){
                print "have read permission\n";
        }

Returns undef on failure. Note: do not use access() for security purposes. Between the access() call and the operation you are preparing for the permissions might change: a classic race condition.

acos

This is identical to the C function acos(), returning the arcus cosine of its numerical argument. See also the Math::Trig manpage.

alarm

This is identical to Perl's builtin alarm() function, either for arming or disarming the SIGARLM timer.

asctime

This is identical to the C function asctime(). It returns a string of the form

        "Fri Jun  2 18:22:13 2000\n\0"

and it is called thusly

        $asctime = asctime($sec, $min, $hour, $mday, $mon, $year,
                           $wday, $yday, $isdst);

The $mon is zero-based: January equals 0. The $year is 1900-based: 2001 equals 101. The $wday, $yday, and $isdst default to zero (and the first two are usually ignored anyway).

asin

This is identical to the C function asin(), returning the arcus sine of its numerical argument. See also the Math::Trig manpage.

assert

Unimplemented, but you can use die in the perlfunc manpage and the the Carp manpage module to achieve similar things.

atan

This is identical to the C function atan(), returning the arcus tangent of its numerical argument. See also the Math::Trig manpage.

atan2

This is identical to Perl's builtin atan2() function, returning the arcus tangent defined by its two numerical arguments, the y coordinate and the x coordinate. See also the Math::Trig manpage.

atexit

atexit() is C-specific: use END {} instead, see the perlsub manpage.

atof

atof() is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it.

atoi

atoi() is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it. If you need to have just the integer part, see int in the perlfunc manpage.

atol

atol() is C-specific. Perl converts strings to numbers transparently. If you need to force a scalar to a number, add a zero to it. If you need to have just the integer part, see int in the perlfunc manpage.

bsearch

bsearch() not supplied. For doing binary search on wordlists, see the Search::Dict manpage.

calloc

calloc() is C-specific. Perl does memory management transparently.

ceil

This is identical to the C function ceil(), returning the smallest integer value greater than or equal to the given numerical argument.

chdir

This is identical to Perl's builtin chdir() function, allowing one to change the working (default) directory, see chdir in the perlfunc manpage.

chmod

This is identical to Perl's builtin chmod() function, allowing one to change file and directory permissions, see chmod in the perlfunc manpage.

chown

This is identical to Perl's builtin chown() function, allowing one to change file and directory owners and groups, see chown in the perlfunc manpage.

clearerr

Use the method IO::Handle::clearerr() instead, to reset the error state (if any) and EOF state (if any) of the given stream.

clock

This is identical to the C function clock(), returning the amount of spent processor time in microseconds.

close

Close the file. This uses file descriptors such as those obtained by calling POSIX::open.

        $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
        POSIX::close( $fd );

Returns undef on failure.

See also close in the perlfunc manpage.

closedir

This is identical to Perl's builtin closedir() function for closing a directory handle, see closedir in the perlfunc manpage.

cos

This is identical to Perl's builtin cos() function, for returning the cosine of its numerical argument, see cos in the perlfunc manpage. See also the Math::Trig manpage.

cosh

This is identical to the C function cosh(), for returning the hyperbolic cosine of its numeric argument. See also the Math::Trig manpage.

creat

Create a new file. This returns a file descriptor like the ones returned by POSIX::open. Use POSIX::close to close the file.

        $fd = POSIX::creat( "foo", 0611 );
        POSIX::close( $fd );

See also sysopen in the perlfunc manpage and its O_CREAT flag.

ctermid

Generates the path name for the controlling terminal.

        $path = POSIX::ctermid();
ctime

This is identical to the C function ctime() and equivalent to asctime(localtime(...)), see asctime and localtime.

cuserid

Get the login name of the owner of the current process.

        $name = POSIX::cuserid();
difftime

This is identical to the C function difftime(), for returning the time difference (in seconds) between two times (as returned by time()), see time.

div

div() is C-specific, use int in the perlfunc manpage on the usual / division and the modulus %.

dup

This is similar to the C function dup(), for duplicating a file descriptor.

This uses file descriptors such as those obtained by calling POSIX::open.

Returns undef on failure.

dup2

This is similar to the C function dup2(), for duplicating a file descriptor to an another known file descriptor.

This uses file descriptors such as those obtained by calling POSIX::open.

Returns undef on failure.

errno

Returns the value of errno.

        $errno = POSIX::errno();

This identical to the numerical values of the $!, see $ERRNO in the perlvar manpage.

execl

execl() is C-specific, see exec in the perlfunc manpage.

execle

execle() is C-specific, see exec in the perlfunc manpage.

execlp

execlp() is C-specific, see exec in the perlfunc manpage.

execv

execv() is C-specific, see exec in the perlfunc manpage.

execve

execve() is C-specific, see exec in the perlfunc manpage.

execvp

execvp() is C-specific, see exec in the perlfunc manpage.

exit

This is identical to Perl's builtin exit() function for exiting the program, see exit in the perlfunc manpage.

exp

This is identical to Perl's builtin exp() function for returning the exponent (e-based) of the numerical argument, see exp in the perlfunc manpage.

fabs

This is identical to Perl's builtin abs() function for returning the absolute value of the numerical argument, see abs in the perlfunc manpage.

fclose

Use method IO::Handle::close() instead, or see close in the perlfunc manpage.

fcntl

This is identical to Perl's builtin fcntl() function, see fcntl in the perlfunc manpage.

fdopen

Use method IO::Handle::new_from_fd() instead, or see open in the perlfunc manpage.

feof

Use method IO::Handle::eof() instead, or see eof in the perlfunc manpage.

ferror

Use method IO::Handle::error() instead.

fflush

Use method IO::Handle::flush() instead. See also $OUTPUT_AUTOFLUSH in the perlvar manpage.

fgetc

Use method IO::Handle::getc() instead, or see read in the perlfunc manpage.

fgetpos

Use method IO::Seekable::getpos() instead, or see seek in the L manpage.

fgets

Use method IO::Handle::gets() instead. Similar to <>, also known as readline in the perlfunc manpage.

fileno

Use method IO::Handle::fileno() instead, or see fileno in the perlfunc manpage.

floor

This is identical to the C function floor(), returning the largest integer value less than or equal to the numerical argument.

fmod

This is identical to the C function fmod().

        $r = fmod($x, $y);

It returns the remainder $r = $x - $n*$y, where $n = trunc($x/$y). The $r has the same sign as $x and magnitude (absolute value) less than the magnitude of $y.

fopen

Use method IO::File::open() instead, or see open in the perlfunc manpage.

fork

This is identical to Perl's builtin fork() function for duplicating the current process, see fork in the perlfunc manpage and the perlfork manpage if you are in Windows.

fpathconf

Retrieves the value of a configurable limit on a file or directory. This uses file descriptors such as those obtained by calling POSIX::open.

The following will determine the maximum length of the longest allowable pathname on the filesystem which holds /var/foo.

        $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
        $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX );

Returns undef on failure.

fprintf

fprintf() is C-specific, see printf in the perlfunc manpage instead.

fputc

fputc() is C-specific, see print in the perlfunc manpage instead.

fputs

fputs() is C-specific, see print in the perlfunc manpage instead.

fread

fread() is C-specific, see read in the perlfunc manpage instead.

free

free() is C-specific. Perl does memory management transparently.

freopen

freopen() is C-specific, see open in the perlfunc manpage instead.

frexp

Return the mantissa and exponent of a floating-point number.

        ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
fscanf

fscanf() is C-specific, use <> and regular expressions instead.

fseek

Use method IO::Seekable::seek() instead, or see seek in the perlfunc manpage.

fsetpos

Use method IO::Seekable::setpos() instead, or seek seek in the perlfunc manpage.

fstat

Get file status. This uses file descriptors such as those obtained by calling POSIX::open. The data returned is identical to the data from Perl's builtin stat function.

        $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
        @stats = POSIX::fstat( $fd );
fsync

Use method IO::Handle::sync() instead.

ftell

Use method IO::Seekable::tell() instead, or see tell in the perlfunc manpage.

fwrite

fwrite() is C-specific, see print in the perlfunc manpage instead.

getc

This is identical to Perl's builtin getc() function, see getc in the perlfunc manpage.

getchar

Returns one character from STDIN. Identical to Perl's getc(), see getc in the perlfunc manpage.

getcwd

Returns the name of the current working directory. See also the Cwd manpage.

getegid

Returns the effective group identifier. Similar to Perl' s builtin variable $(, see $EGID in the perlvar manpage.

getenv

Returns the value of the specified environment variable. The same information is available through the %ENV array.

geteuid

Returns the effective user identifier. Identical to Perl's builtin $> variable, see $EUID in the perlvar manpage.

getgid

Returns the user's real group identifier. Similar to Perl's builtin variable $), see $GID in the perlvar manpage.

getgrgid

This is identical to Perl's builtin getgrgid() function for returning group entries by group identifiers, see getgrgid in the perlfunc manpage.

getgrnam

This is identical to Perl's builtin getgrnam() function for returning group entries by group names, see getgrnam in the perlfunc manpage.

getgroups

Returns the ids of the user's supplementary groups. Similar to Perl's builtin variable $), see $GID in the perlvar manpage.

getlogin

This is identical to Perl's builtin getlogin() function for returning the user name associated with the current session, see getlogin in the perlfunc manpage.

getpgrp

This is identical to Perl's builtin getpgrp() function for returning the process group identifier of the current process, see getpgrp in the perlfunc manpage.

getpid

Returns the process identifier. Identical to Perl's builtin variable $$, see $PID in the perlvar manpage.

getppid

This is identical to Perl's builtin getppid() function for returning the process identifier of the parent process of the current process , see getppid in the perlfunc manpage.

getpwnam

This is identical to Perl's builtin getpwnam() function for returning user entries by user names, see getpwnam in the perlfunc manpage.

getpwuid

This is identical to Perl's builtin getpwuid() function for returning user entries by user identifiers, see getpwuid in the perlfunc manpage.

gets

Returns one line from STDIN, similar to <>, also known as the readline() function, see readline in the perlfunc manpage.

NOTE: if you have C programs that still use gets(), be very afraid. The gets() function is a source of endless grief because it has no buffer overrun checks. It should never be used. The fgets() function should be preferred instead.

getuid

Returns the user's identifier. Identical to Perl's builtin $< variable, see $UID in the perlvar manpage.

gmtime

This is identical to Perl's builtin gmtime() function for converting seconds since the epoch to a date in Greenwich Mean Time, see gmtime in the perlfunc manpage.

isalnum

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isalnum. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:alnum:]]/ construct instead, or possibly the /\w/ construct.

isalpha

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isalpha. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:alpha:]]/ construct instead.

isatty

Returns a boolean indicating whether the specified filehandle is connected to a tty. Similar to the -t operator, see -X in the perlfunc manpage.

iscntrl

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered iscntrl. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:cntrl:]]/ construct instead.

isdigit

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isdigit (unlikely, but still possible). Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:digit:]]/ construct instead, or the /\d/ construct.

isgraph

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isgraph. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:graph:]]/ construct instead.

islower

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered islower. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:lower:]]/ construct instead. Do not use /[a-z]/.

isprint

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isprint. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:print:]]/ construct instead.

ispunct

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered ispunct. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:punct:]]/ construct instead.

isspace

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isspace. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:space:]]/ construct instead, or the /\s/ construct. (Note that /\s/ and /[[:space:]]/ are slightly different in that /[[:space:]]/ can normally match a vertical tab, while /\s/ does not.)

isupper

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isupper. Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:upper:]]/ construct instead. Do not use /[A-Z]/.

isxdigit

This is identical to the C function, except that it can apply to a single character or to a whole string. Note that locale settings may affect what characters are considered isxdigit (unlikely, but still possible). Does not work on Unicode characters code point 256 or higher. Consider using regular expressions and the /[[:xdigit:]]/ construct instead, or simply /[0-9a-f]/i.

kill

This is identical to Perl's builtin kill() function for sending signals to processes (often to terminate them), see kill in the perlfunc manpage.

labs

(For returning absolute values of long integers.) labs() is C-specific, see abs in the perlfunc manpage instead.

ldexp

This is identical to the C function ldexp() for multiplying floating point numbers with powers of two.

        $x_quadrupled = POSIX::ldexp($x, 2);
ldiv

(For computing dividends of long integers.) ldiv() is C-specific, use / and int() instead.

link

This is identical to Perl's builtin link() function for creating hard links into files, see link in the perlfunc manpage.

localeconv

Get numeric formatting information. Returns a reference to a hash containing the current locale formatting values.

Here is how to query the database for the de (Deutsch or German) locale.

        $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
        print "Locale = $loc\n";
        $lconv = POSIX::localeconv();
        print "decimal_point    = ", $lconv->{decimal_point},   "\n";
        print "thousands_sep    = ", $lconv->{thousands_sep},   "\n";
        print "grouping = ", $lconv->{grouping},        "\n";
        print "int_curr_symbol  = ", $lconv->{int_curr_symbol}, "\n";
        print "currency_symbol  = ", $lconv->{currency_symbol}, "\n";
        print "mon_decimal_point = ", $lconv->{mon_decimal_point}, "\n";
        print "mon_thousands_sep = ", $lconv->{mon_thousands_sep}, "\n";
        print "mon_grouping     = ", $lconv->{mon_grouping},    "\n";
        print "positive_sign    = ", $lconv->{positive_sign},   "\n";
        print "negative_sign    = ", $lconv->{negative_sign},   "\n";
        print "int_frac_digits  = ", $lconv->{int_frac_digits}, "\n";
        print "frac_digits      = ", $lconv->{frac_digits},     "\n";
        print "p_cs_precedes    = ", $lconv->{p_cs_precedes},   "\n";
        print "p_sep_by_space   = ", $lconv->{p_sep_by_space},  "\n";
        print "n_cs_precedes    = ", $lconv->{n_cs_precedes},   "\n";
        print "n_sep_by_space   = ", $lconv->{n_sep_by_space},  "\n";
        print "p_sign_posn      = ", $lconv->{p_sign_posn},     "\n";
        print "n_sign_posn      = ", $lconv->{n_sign_posn},     "\n";
localtime

This is identical to Perl's builtin localtime() function for converting seconds since the epoch to a date see localtime in the perlfunc manpage.

log

This is identical to Perl's builtin log() function, returning the natural (e-based) logarithm of the numerical argument, see log in the perlfunc manpage.

log10

This is identical to the C function log10(), returning the 10-base logarithm of the numerical argument. You can also use

    sub log10 { log($_[0]) / log(10) }

or

    sub log10 { log($_[0]) / 2.30258509299405 }

or

    sub log10 { log($_[0]) * 0.434294481903252 }
longjmp

longjmp() is C-specific: use die in the perlfunc manpage instead.

lseek

Move the file's read/write position. This uses file descriptors such as those obtained by calling POSIX::open.

        $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
        $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );

Returns undef on failure.

malloc

malloc() is C-specific. Perl does memory management transparently.

mblen

This is identical to the C function mblen(). Perl does not have any support for the wide and multibyte characters of the C standards, so this might be a rather useless function.

mbstowcs

This is identical to the C function mbstowcs(). Perl does not have any support for the wide and multibyte characters of the C standards, so this might be a rather useless function.

mbtowc

This is identical to the C function mbtowc(). Perl does not have any support for the wide and multibyte characters of the C standards, so this might be a rather useless function.

memchr

memchr() is C-specific, see index in the perlfunc manpage instead.

memcmp

memcmp() is C-specific, use eq instead, see the perlop manpage.

memcpy

memcpy() is C-specific, use =, see the perlop manpage, or see substr in the perlfunc manpage.

memmove

memmove() is C-specific, use =, see the perlop manpage, or see substr in the perlfunc manpage.

memset

memset() is C-specific, use x instead, see the perlop manpage.

mkdir

This is identical to Perl's builtin mkdir() function for creating directories, see mkdir in the perlfunc manpage.

mkfifo

This is similar to the C function mkfifo() for creating FIFO special files.

        if (mkfifo($path, $mode)) { ....

Returns undef on failure. The $mode is similar to the mode of mkdir(), see mkdir in the perlfunc manpage.

mktime

Convert date/time info to a calendar time.

Synopsis:

        mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0)

The month (mon), weekday (wday), and yearday (yday) begin at zero. I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The year (year) is given in years since 1900. I.e. The year 1995 is 95; the year 2001 is 101. Consult your system's mktime() manpage for details about these and the other arguments.

Calendar time for December 12, 1995, at 10:30 am.

        $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
        print "Date = ", POSIX::ctime($time_t);

Returns undef on failure.

modf

Return the integral and fractional parts of a floating-point number.

        ($fractional, $integral) = POSIX::modf( 3.14 );
nice

This is similar to the C function nice(), for changing the scheduling preference of the current process. Positive arguments mean more polite process, negative values more needy process. Normal user processes can only be more polite.

Returns undef on failure.

offsetof

offsetof() is C-specific, you probably want to see pack in the perlfunc manpage instead.

open

Open a file for reading for writing. This returns file descriptors, not Perl filehandles. Use POSIX::close to close the file.

Open a file read-only with mode 0666.

        $fd = POSIX::open( "foo" );

Open a file for read and write.

        $fd = POSIX::open( "foo", &POSIX::O_RDWR );

Open a file for write, with truncation.

        $fd = POSIX::open( "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC );

Create a new file with mode 0640. Set up the file for writing.

        $fd = POSIX::open( "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640 );

Returns undef on failure.

See also sysopen in the perlfunc manpage.

opendir

Open a directory for reading.

        $dir = POSIX::opendir( "/var" );
        @files = POSIX::readdir( $dir );
        POSIX::closedir( $dir );

Returns undef on failure.

pathconf

Retrieves the value of a configurable limit on a file or directory.

The following will determine the maximum length of the longest allowable pathname on the filesystem which holds /var.

        $path_max = POSIX::pathconf( "/var", &POSIX::_PC_PATH_MAX );

Returns undef on failure.

pause

This is similar to the C function pause(), which suspends the execution of the current process until a signal is received.

Returns undef on failure.

perror

This is identical to the C function perror(), which outputs to the standard error stream the specified message followed by ": " and the current error string. Use the warn() function and the $! variable instead, see warn in the perlfunc manpage and $ERRNO in the perlvar manpage.

pipe

Create an interprocess channel. This returns file descriptors like those returned by POSIX::open.

        my ($read, $write) = POSIX::pipe();
        POSIX::write( $write, "hello", 5 );
        POSIX::read( $read, $buf, 5 );

See also pipe in the perlfunc manpage.

pow

Computes $x raised to the power $exponent.

        $ret = POSIX::pow( $x, $exponent );

You can also use the ** operator, see the perlop manpage.

printf

Formats and prints the specified arguments to STDOUT. See also printf in the perlfunc manpage.

putc

putc() is C-specific, see print in the perlfunc manpage instead.

putchar

putchar() is C-specific, see print in the perlfunc manpage instead.

puts

puts() is C-specific, see print in the perlfunc manpage instead.

qsort

qsort() is C-specific, see sort in the perlfunc manpage instead.

raise

Sends the specified signal to the current process. See also kill in the perlfunc manpage and the $$ in $PID in the perlvar manpage.

rand

rand() is non-portable, see rand in the perlfunc manpage instead.

read

Read from a file. This uses file descriptors such as those obtained by calling POSIX::open. If the buffer $buf is not large enough for the read then Perl will extend it to make room for the request.

        $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
        $bytes = POSIX::read( $fd, $buf, 3 );

Returns undef on failure.

See also sysread in the perlfunc manpage.

readdir

This is identical to Perl's builtin readdir() function for reading directory entries, see readdir in the perlfunc manpage.

realloc

realloc() is C-specific. Perl does memory management transparently.

remove

This is identical to Perl's builtin unlink() function for removing files, see unlink in the perlfunc manpage.

rename

This is identical to Perl's builtin rename() function for renaming files, see rename in the perlfunc manpage.

rewind

Seeks to the beginning of the file.

rewinddir

This is identical to Perl's builtin rewinddir() function for rewinding directory entry streams, see rewinddir in the perlfunc manpage.

rmdir

This is identical to Perl's builtin rmdir() function for removing (empty) directories, see rmdir in the perlfunc manpage.

scanf

scanf() is C-specific, use <> and regular expressions instead, see the perlre manpage.

setgid

Sets the real group identifier and the effective group identifier for this process. Similar to assigning a value to the Perl's builtin $) variable, see $GID in the perlvar manpage, except that the latter will change only the real user identifier, and that the setgid() uses only a single numeric argument, as opposed to a space-separated list of numbers.

setjmp

setjmp() is C-specific: use eval {} instead, see eval in the perlfunc manpage.

setlocale

Modifies and queries program's locale. The following examples assume

        use POSIX qw(setlocale LC_ALL LC_CTYPE);

has been issued.

The following will set the traditional UNIX system locale behavior (the second argument "C").

        $loc = setlocale( LC_ALL, "C" );

The following will query the current LC_CTYPE category. (No second argument means 'query'.)

        $loc = setlocale( LC_CTYPE );

The following will set the LC_CTYPE behaviour according to the locale environment variables (the second argument ""). Please see your systems setlocale(3) documentation for the locale environment variables' meaning or consult the perllocale manpage.

        $loc = setlocale( LC_CTYPE, "" );

The following will set the LC_COLLATE behaviour to Argentinian Spanish. NOTE: The naming and availability of locales depends on your operating system. Please consult the perllocale manpage for how to find out which locales are available in your system.

        $loc = setlocale( LC_ALL, "es_AR.ISO8859-1" );
setpgid

This is similar to the C function setpgid() for setting the process group identifier of the current process.

Returns undef on failure.

setsid

This is identical to the C function setsid() for setting the session identifier of the current process.

setuid

Sets the real user identifier and the effective user identifier for this process. Similar to assigning a value to the Perl's builtin $< variable, see $UID in the perlvar manpage, except that the latter will change only the real user identifier.

sigaction

Detailed signal management. This uses POSIX::SigAction objects for the action and oldaction arguments. Consult your system's sigaction manpage for details.

Synopsis:

        sigaction(signal, action, oldaction = 0)

Returns undef on failure. The signal must be a number (like SIGHUP), not a string (like "SIGHUP"), though Perl does try hard to understand you.

siglongjmp

siglongjmp() is C-specific: use die in the perlfunc manpage instead.

sigpending

Examine signals that are blocked and pending. This uses POSIX::SigSet objects for the sigset argument. Consult your system's sigpending manpage for details.

Synopsis:

        sigpending(sigset)

Returns undef on failure.

sigprocmask

Change and/or examine calling process's signal mask. This uses POSIX::SigSet objects for the sigset and oldsigset arguments. Consult your system's sigprocmask manpage for details.

Synopsis:

        sigprocmask(how, sigset, oldsigset = 0)

Returns undef on failure.

sigsetjmp

sigsetjmp() is C-specific: use eval {} instead, see eval in the perlfunc manpage.

sigsuspend

Install a signal mask and suspend process until signal arrives. This uses POSIX::SigSet objects for the signal_mask argument. Consult your system's sigsuspend manpage for details.

Synopsis:

        sigsuspend(signal_mask)

Returns undef on failure.

sin

This is identical to Perl's builtin sin() function for returning the sine of the numerical argument, see sin in the perlfunc manpage. See also the Math::Trig manpage.

sinh

This is identical to the C function sinh() for returning the hyperbolic sine of the numerical argument. See also the Math::Trig manpage.

sleep

This is functionally identical to Perl's builtin sleep() function for suspending the execution of the current for process for certain number of seconds, see sleep in the perlfunc manpage. There is one significant difference, however: POSIX::sleep() returns the number of unslept seconds, while the CORE::sleep() returns the number of slept seconds.

sprintf

This is similar to Perl's builtin sprintf() function for returning a string that has the arguments formatted as requested, see sprintf in the perlfunc manpage.

sqrt

This is identical to Perl's builtin sqrt() function. for returning the square root of the numerical argument, see sqrt in the perlfunc manpage.

srand

Give a seed the pseudorandom number generator, see srand in the perlfunc manpage.

sscanf

sscanf() is C-specific, use regular expressions instead, see the perlre manpage.

stat

This is identical to Perl's builtin stat() function for returning information about files and directories.

strcat

strcat() is C-specific, use .= instead, see the perlop manpage.

strchr

strchr() is C-specific, see index in the perlfunc manpage instead.

strcmp

strcmp() is C-specific, use eq or cmp instead, see the perlop manpage.

strcoll

This is identical to the C function strcoll() for collating (comparing) strings transformed using the strxfrm() function. Not really needed since Perl can do this transparently, see the perllocale manpage.

strcpy

strcpy() is C-specific, use = instead, see the perlop manpage.

strcspn

strcspn() is C-specific, use regular expressions instead, see the perlre manpage.

strerror

Returns the error string for the specified errno. Identical to the string form of the $!, see $ERRNO in the perlvar manpage.

strftime

Convert date and time information to string. Returns the string.

Synopsis:

        strftime(fmt, sec, min, hour, mday, mon, year, wday = -1, yday = -1, isdst = -1)

The month (mon), weekday (wday), and yearday (yday) begin at zero. I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The year (year) is given in years since 1900. I.e., the year 1995 is 95; the year 2001 is 101. Consult your system's strftime() manpage for details about these and the other arguments.

If you want your code to be portable, your format (fmt) argument should use only the conversion specifiers defined by the ANSI C standard (C89, to play safe). These are aAbBcdHIjmMpSUwWxXyYZ%. But even then, the results of some of the conversion specifiers are non-portable. For example, the specifiers aAbBcpZ change according to the locale settings of the user, and both how to set locales (the locale names) and what output to expect are non-standard. The specifier c changes according to the timezone settings of the user and the timezone computation rules of the operating system. The Z specifier is notoriously unportable since the names of timezones are non-standard. Sticking to the numeric specifiers is the safest route.

The given arguments are made consistent as though by calling mktime() before calling your system's strftime() function, except that the isdst value is not affected.

The string for Tuesday, December 12, 1995.

        $str = POSIX::strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 2 );
        print "$str\n";
strlen

strlen() is C-specific, use length() instead, see length in the perlfunc manpage.

strncat

strncat() is C-specific, use .= instead, see the perlop manpage.

strncmp

strncmp() is C-specific, use eq instead, see the perlop manpage.

strncpy

strncpy() is C-specific, use = instead, see the perlop manpage.

strpbrk

strpbrk() is C-specific, use regular expressions instead, see the perlre manpage.

strrchr

strrchr() is C-specific, see rindex in the perlfunc manpage instead.

strspn

strspn() is C-specific, use regular expressions instead, see the perlre manpage.

strstr

This is identical to Perl's builtin index() function, see index in the perlfunc manpage.

strtod

String to double translation. Returns the parsed number and the number of characters in the unparsed portion of the string. Truly POSIX-compliant systems set $! ($ERRNO) to indicate a translation error, so clear $! before calling strtod. However, non-POSIX systems may not check for overflow, and therefore will never set $!.

strtod should respect any POSIX setlocale() settings.

To parse a string $str as a floating point number use

    $! = 0;
    ($num, $n_unparsed) = POSIX::strtod($str);

The second returned item and $! can be used to check for valid input:

    if (($str eq '') || ($n_unparsed != 0) || $!) {
        die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
    }

When called in a scalar context strtod returns the parsed number.

strtok

strtok() is C-specific, use regular expressions instead, see the perlre manpage, or split in the perlfunc manpage.

strtol

String to (long) integer translation. Returns the parsed number and the number of characters in the unparsed portion of the string. Truly POSIX-compliant systems set $! ($ERRNO) to indicate a translation error, so clear $! before calling strtol. However, non-POSIX systems may not check for overflow, and therefore will never set $!.

strtol should respect any POSIX setlocale() settings.

To parse a string $str as a number in some base $base use

    $! = 0;
    ($num, $n_unparsed) = POSIX::strtol($str, $base);

The base should be zero or between 2 and 36, inclusive. When the base is zero or omitted strtol will use the string itself to determine the base: a leading "0x" or "0X" means hexadecimal; a leading "0" means octal; any other leading characters mean decimal. Thus, "1234" is parsed as a decimal number, "01234" as an octal number, and "0x1234" as a hexadecimal number.

The second returned item and $! can be used to check for valid input:

    if (($str eq '') || ($n_unparsed != 0) || !$!) {
        die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
    }

When called in a scalar context strtol returns the parsed number.

strtoul

String to unsigned (long) integer translation. strtoul() is identical to strtol() except that strtoul() only parses unsigned integers. See strtol for details.

Note: Some vendors supply strtod() and strtol() but not strtoul(). Other vendors that do supply strtoul() parse "-1" as a valid value.

strxfrm

String transformation. Returns the transformed string.

        $dst = POSIX::strxfrm( $src );

Used in conjunction with the strcoll() function, see strcoll.

Not really needed since Perl can do this transparently, see the perllocale manpage.

sysconf

Retrieves values of system configurable variables.

The following will get the machine's clock speed.

        $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );

Returns undef on failure.

system

This is identical to Perl's builtin system() function, see system in the perlfunc manpage.

tan

This is identical to the C function tan(), returning the tangent of the numerical argument. See also the Math::Trig manpage.

tanh

This is identical to the C function tanh(), returning the hyperbolic tangent of the numerical argument. See also the Math::Trig manpage.

tcdrain

This is similar to the C function tcdrain() for draining the output queue of its argument stream.

Returns undef on failure.

tcflow

This is similar to the C function tcflow() for controlling the flow of its argument stream.

Returns undef on failure.

tcflush

This is similar to the C function tcflush() for flushing the I/O buffers of its argument stream.

Returns undef on failure.

tcgetpgrp

This is identical to the C function tcgetpgrp() for returning the process group identifier of the foreground process group of the controlling terminal.

tcsendbreak

This is similar to the C function tcsendbreak() for sending a break on its argument stream.

Returns undef on failure.

tcsetpgrp

This is similar to the C function tcsetpgrp() for setting the process group identifier of the foreground process group of the controlling terminal.

Returns undef on failure.

time

This is identical to Perl's builtin time() function for returning the number of seconds since the epoch (whatever it is for the system), see time in the perlfunc manpage.

times

The times() function returns elapsed realtime since some point in the past (such as system startup), user and system times for this process, and user and system times used by child processes. All times are returned in clock ticks.

    ($realtime, $user, $system, $cuser, $csystem) = POSIX::times();

Note: Perl's builtin times() function returns four values, measured in seconds.

tmpfile

Use method IO::File::new_tmpfile() instead, or see the File::Temp manpage.

tmpnam

Returns a name for a temporary file.

        $tmpfile = POSIX::tmpnam();

For security reasons, which are probably detailed in your system's documentation for the C library tmpnam() function, this interface should not be used; instead see the File::Temp manpage.

tolower

This is identical to the C function, except that it can apply to a single character or to a whole string. Consider using the lc() function, see lc in the perlfunc manpage, or the equivalent \L operator inside doublequotish strings.

toupper

This is identical to the C function, except that it can apply to a single character or to a whole string. Consider using the uc() function, see uc in the perlfunc manpage, or the equivalent \U operator inside doublequotish strings.

ttyname

This is identical to the C function ttyname() for returning the name of the current terminal.

tzname

Retrieves the time conversion information from the tzname variable.

        POSIX::tzset();
        ($std, $dst) = POSIX::tzname();
tzset

This is identical to the C function tzset() for setting the current timezone based on the environment variable TZ, to be used by ctime(), localtime(), mktime(), and strftime() functions.

umask

This is identical to Perl's builtin umask() function for setting (and querying) the file creation permission mask, see umask in the perlfunc manpage.

uname

Get name of current operating system.

        ($sysname, $nodename, $release, $version, $machine) = POSIX::uname();

Note that the actual meanings of the various fields are not that well standardized, do not expect any great portability. The $sysname might be the name of the operating system, the $nodename might be the name of the host, the $release might be the (major) release number of the operating system, the $version might be the (minor) release number of the operating system, and the $machine might be a hardware identifier. Maybe.

ungetc

Use method IO::Handle::ungetc() instead.

unlink

This is identical to Perl's builtin unlink() function for removing files, see unlink in the perlfunc manpage.

utime

This is identical to Perl's builtin utime() function for changing the time stamps of files and directories, see utime in the perlfunc manpage.

vfprintf

vfprintf() is C-specific, see printf in the perlfunc manpage instead.

vprintf

vprintf() is C-specific, see printf in the perlfunc manpage instead.

vsprintf

vsprintf() is C-specific, see sprintf in the perlfunc manpage instead.

wait

This is identical to Perl's builtin wait() function, see wait in the perlfunc manpage.

waitpid

Wait for a child process to change state. This is identical to Perl's builtin waitpid() function, see waitpid in the perlfunc manpage.

        $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
        print "status = ", ($? / 256), "\n";
wcstombs

This is identical to the C function wcstombs(). Perl does not have any support for the wide and multibyte characters of the C standards, so this might be a rather useless function.

wctomb

This is identical to the C function wctomb(). Perl does not have any support for the wide and multibyte characters of the C standards, so this might be a rather useless function.

write

Write to a file. This uses file descriptors such as those obtained by calling POSIX::open.

        $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
        $buf = "hello";
        $bytes = POSIX::write( $b, $buf, 5 );

Returns undef on failure.

See also syswrite in the perlfunc manpage.

CLASSES

POSIX::SigAction

new

Creates a new POSIX::SigAction object which corresponds to the C struct sigaction. This object will be destroyed automatically when it is no longer needed. The first parameter is the fully-qualified name of a sub which is a signal-handler. The second parameter is a POSIX::SigSet object, it defaults to the empty set. The third parameter contains the sa_flags, it defaults to 0.

        $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
        $sigaction = POSIX::SigAction->new( \&main::handler, $sigset, &POSIX::SA_NOCLDSTOP );

This POSIX::SigAction object is intended for use with the POSIX::sigaction() function.

handler
mask
flags

accessor functions to get/set the values of a SigAction object.

        $sigset = $sigaction->mask;
        $sigaction->flags(&POSIX::SA_RESTART);
safe

accessor function for the "safe signals" flag of a SigAction object; see the perlipc manpage for general information on safe (a.k.a. "deferred") signals. If you wish to handle a signal safely, use this accessor to set the "safe" flag in the POSIX::SigAction object:

        $sigaction->safe(1);

You may also examine the "safe" flag on the output action object which is filled in when given as the third parameter to POSIX::sigaction():

        sigaction(SIGINT, $new_action, $old_action);
        if ($old_action->safe) {
            # previous SIGINT handler used safe signals
        }

POSIX::SigSet

new

Create a new SigSet object. This object will be destroyed automatically when it is no longer needed. Arguments may be supplied to initialize the set.

Create an empty set.

        $sigset = POSIX::SigSet->new;

Create a set with SIGUSR1.

        $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
addset

Add a signal to a SigSet object.

        $sigset->addset( &POSIX::SIGUSR2 );

Returns undef on failure.

delset

Remove a signal from the SigSet object.

        $sigset->delset( &POSIX::SIGUSR2 );

Returns undef on failure.

emptyset

Initialize the SigSet object to be empty.

        $sigset->emptyset();

Returns undef on failure.

fillset

Initialize the SigSet object to include all signals.

        $sigset->fillset();

Returns undef on failure.

ismember

Tests the SigSet object to see if it contains a specific signal.

        if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
                print "contains SIGUSR1\n";
        }

POSIX::Termios

new

Create a new Termios object. This object will be destroyed automatically when it is no longer needed. A Termios object corresponds to the termios C struct. new() mallocs a new one, getattr() fills it from a file descriptor, and setattr() sets a file descriptor's parameters to match Termios' contents.

        $termios = POSIX::Termios->new;
getattr

Get terminal control attributes.

Obtain the attributes for stdin.

        $termios->getattr()

Obtain the attributes for stdout.

        $termios->getattr( 1 )

Returns undef on failure.

getcc

Retrieve a value from the c_cc field of a termios object. The c_cc field is an array so an index must be specified.

        $c_cc[1] = $termios->getcc(1);
getcflag

Retrieve the c_cflag field of a termios object.

        $c_cflag = $termios->getcflag;
getiflag

Retrieve the c_iflag field of a termios object.

        $c_iflag = $termios->getiflag;
getispeed

Retrieve the input baud rate.

        $ispeed = $termios->getispeed;
getlflag

Retrieve the c_lflag field of a termios object.

        $c_lflag = $termios->getlflag;
getoflag

Retrieve the c_oflag field of a termios object.

        $c_oflag = $termios->getoflag;
getospeed

Retrieve the output baud rate.

        $ospeed = $termios->getospeed;
setattr

Set terminal control attributes.

Set attributes immediately for stdout.

        $termios->setattr( 1, &POSIX::TCSANOW );

Returns undef on failure.

setcc

Set a value in the c_cc field of a termios object. The c_cc field is an array so an index must be specified.

        $termios->setcc( &POSIX::VEOF, 1 );
setcflag

Set the c_cflag field of a termios object.

        $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
setiflag

Set the c_iflag field of a termios object.

        $termios->setiflag( $c_iflag | &POSIX::BRKINT );
setispeed

Set the input baud rate.

        $termios->setispeed( &POSIX::B9600 );

Returns undef on failure.

setlflag

Set the c_lflag field of a termios object.

        $termios->setlflag( $c_lflag | &POSIX::ECHO );
setoflag

Set the c_oflag field of a termios object.

        $termios->setoflag( $c_oflag | &POSIX::OPOST );
setospeed

Set the output baud rate.

        $termios->setospeed( &POSIX::B9600 );

Returns undef on failure.

Baud rate values

B38400 B75 B200 B134 B300 B1800 B150 B0 B19200 B1200 B9600 B600 B4800 B50 B2400 B110

Terminal interface values

TCSADRAIN TCSANOW TCOON TCIOFLUSH TCOFLUSH TCION TCIFLUSH TCSAFLUSH TCIOFF TCOOFF

c_cc field values

VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN VTIME NCCS

c_cflag field values

CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD

c_iflag field values

BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF IXON PARMRK

c_lflag field values

ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP

c_oflag field values

OPOST

PATHNAME CONSTANTS

Constants

_PC_CHOWN_RESTRICTED _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX _PC_NO_TRUNC _PC_PATH_MAX _PC_PIPE_BUF _PC_VDISABLE

POSIX CONSTANTS

Constants

_POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL _POSIX_LINK_MAX _POSIX_MAX_CANON _POSIX_MAX_INPUT _POSIX_NAME_MAX _POSIX_NGROUPS_MAX _POSIX_NO_TRUNC _POSIX_OPEN_MAX _POSIX_PATH_MAX _POSIX_PIPE_BUF _POSIX_SAVED_IDS _POSIX_SSIZE_MAX _POSIX_STREAM_MAX _POSIX_TZNAME_MAX _POSIX_VDISABLE _POSIX_VERSION

SYSTEM CONFIGURATION

Constants

_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION

ERRNO

Constants

E2BIG EACCES EADDRINUSE EADDRNOTAVAIL EAFNOSUPPORT EAGAIN EALREADY EBADF EBUSY ECHILD ECONNABORTED ECONNREFUSED ECONNRESET EDEADLK EDESTADDRREQ EDOM EDQUOT EEXIST EFAULT EFBIG EHOSTDOWN EHOSTUNREACH EINPROGRESS EINTR EINVAL EIO EISCONN EISDIR ELOOP EMFILE EMLINK EMSGSIZE ENAMETOOLONG ENETDOWN ENETRESET ENETUNREACH ENFILE ENOBUFS ENODEV ENOENT ENOEXEC ENOLCK ENOMEM ENOPROTOOPT ENOSPC ENOSYS ENOTBLK ENOTCONN ENOTDIR ENOTEMPTY ENOTSOCK ENOTTY ENXIO EOPNOTSUPP EPERM EPFNOSUPPORT EPIPE EPROCLIM EPROTONOSUPPORT EPROTOTYPE ERANGE EREMOTE ERESTART EROFS ESHUTDOWN ESOCKTNOSUPPORT ESPIPE ESRCH ESTALE ETIMEDOUT ETOOMANYREFS ETXTBSY EUSERS EWOULDBLOCK EXDEV

FCNTL

Constants

FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_OK F_RDLCK F_SETFD F_SETFL F_SETLK F_SETLKW F_UNLCK F_WRLCK O_ACCMODE O_APPEND O_CREAT O_EXCL O_NOCTTY O_NONBLOCK O_RDONLY O_RDWR O_TRUNC O_WRONLY

FLOAT

Constants

DBL_DIG DBL_EPSILON DBL_MANT_DIG DBL_MAX DBL_MAX_10_EXP DBL_MAX_EXP DBL_MIN DBL_MIN_10_EXP DBL_MIN_EXP FLT_DIG FLT_EPSILON FLT_MANT_DIG FLT_MAX FLT_MAX_10_EXP FLT_MAX_EXP FLT_MIN FLT_MIN_10_EXP FLT_MIN_EXP FLT_RADIX FLT_ROUNDS LDBL_DIG LDBL_EPSILON LDBL_MANT_DIG LDBL_MAX LDBL_MAX_10_EXP LDBL_MAX_EXP LDBL_MIN LDBL_MIN_10_EXP LDBL_MIN_EXP

LIMITS

Constants

ARG_MAX CHAR_BIT CHAR_MAX CHAR_MIN CHILD_MAX INT_MAX INT_MIN LINK_MAX LONG_MAX LONG_MIN MAX_CANON MAX_INPUT MB_LEN_MAX NAME_MAX NGROUPS_MAX OPEN_MAX PATH_MAX PIPE_BUF SCHAR_MAX SCHAR_MIN SHRT_MAX SHRT_MIN SSIZE_MAX STREAM_MAX TZNAME_MAX UCHAR_MAX UINT_MAX ULONG_MAX USHRT_MAX

LOCALE

Constants

LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME

MATH

Constants

HUGE_VAL

SIGNAL

Constants

SA_NOCLDSTOP SA_NOCLDWAIT SA_NODEFER SA_ONSTACK SA_RESETHAND SA_RESTART SA_SIGINFO SIGABRT SIGALRM SIGCHLD SIGCONT SIGFPE SIGHUP SIGILL SIGINT SIGKILL SIGPIPE SIGQUIT SIGSEGV SIGSTOP SIGTERM SIGTSTP SIGTTIN SIGTTOU SIGUSR1 SIGUSR2 SIG_BLOCK SIG_DFL SIG_ERR SIG_IGN SIG_SETMASK SIG_UNBLOCK

STAT

Constants

S_IRGRP S_IROTH S_IRUSR S_IRWXG S_IRWXO S_IRWXU S_ISGID S_ISUID S_IWGRP S_IWOTH S_IWUSR S_IXGRP S_IXOTH S_IXUSR

Macros

S_ISBLK S_ISCHR S_ISDIR S_ISFIFO S_ISREG

STDLIB

Constants

EXIT_FAILURE EXIT_SUCCESS MB_CUR_MAX RAND_MAX

STDIO

Constants

BUFSIZ EOF FILENAME_MAX L_ctermid L_cuserid L_tmpname TMP_MAX

TIME

Constants

CLK_TCK CLOCKS_PER_SEC

UNISTD

Constants

R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_OK

WAIT

Constants

WNOHANG WUNTRACED

WNOHANG

Do not suspend the calling process until a child process changes state but instead return immediately.

WUNTRACED

Catch stopped child processes.

Macros

WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG

WIFEXITED

WIFEXITED($?) returns true if the child process exited normally (exit() or by falling off the end of main())

WEXITSTATUS

WEXITSTATUS($?) returns the normal exit status of the child process (only meaningful if WIFEXITED($?) is true)

WIFSIGNALED

WIFSIGNALED($?) returns true if the child process terminated because of a signal

WTERMSIG

WTERMSIG($?) returns the signal the child process terminated for (only meaningful if WIFSIGNALED($?) is true)

WIFSTOPPED

WIFSTOPPED($?) returns true if the child process is currently stopped (can happen only if you specified the WUNTRACED flag to waitpid())

WSTOPSIG

WSTOPSIG($?) returns the signal the child process was stopped for (only meaningful if WIFSTOPPED($?) is true)


PPI - Parse, Analyze and Manipulate Perl

    • About this Document
    • Background
    • What Does PPI Stand For?
    • Why Parse Perl?
    • How good is Good Enough(TM)
    • Internationalisation
    • Round Trip Safe
  • IMPLEMENTATION
    • General Layout
    • The Tokenizer
    • The Lexer
    • The Perl Document Object Model
    • The PDOM Class Tree
    • The Document, Statement and Structure
    • The PDOM at Work
    • Overview of the Primary Classes
  • INSTALLING
  • EXTENDING
  • TO DO
  • SUPPORT
  • AUTHOR
  • ACKNOWLEDGMENTS
  • COPYRIGHT

NAME

PPI - Parse, Analyze and Manipulate Perl (without perl)

SYNOPSIS

  use PPI;

  # Create a new empty document
  my $Document = PPI::Document->new;

  # Create a document from source
  $Document = PPI::Document->new(\'print "Hello World!\n"');

  # Load a Document from a file
  $Document = PPI::Document->new('Module.pm');

  # Does it contain any POD?
  if ( $Document->find_any('PPI::Token::Pod') ) {
      print "Module contains POD\n";
  }

  # Get the name of the main package
  $pkg = $Document->find_first('PPI::Statement::Package')->namespace;

  # Remove all that nasty documentation
  $Document->prune('PPI::Token::Pod');
  $Document->prune('PPI::Token::Comment');

  # Save the file
  $Document->save('Module.pm.stripped');

DESCRIPTION

About this Document

This is the PPI manual. It describes its reason for existing, its general structure, its use, an overview of the API, and provides a few implementation samples.

Background

The ability to read, and manipulate Perl (the language) programmatically other than with perl (the application) was one that caused difficulty for a long time.

The cause of this problem was Perl's complex and dynamic grammar. Although there is typically not a huge diversity in the grammar of most Perl code, certain issues cause large problems when it comes to parsing.

Indeed, quite early in Perl's history Tom Christenson introduced the Perl community to the quote "Nothing but perl can parse Perl", or as it is more often stated now as a truism:

"Only perl can parse Perl"

One example of the sorts of things the prevent Perl being easily parsed are function signatures, as demonstrated by the following.

  @result = (dothis $foo, $bar);

  # Which of the following is it equivalent to?
  @result = (dothis($foo), $bar);
  @result = dothis($foo, $bar);

The first line above can be interpreted in two different ways, depending on whether the &dothis function is expecting one argument, or two, or several.

A "code parser" (something that parses for the purpose of execution) such as perl needs information that is not found in the immediate vicinity of the statement being parsed.

The information might not just be elsewhere in the file, it might not even be in the same file at all. It might also not be able to determine this information without the prior execution of a BEGIN {} block, or the loading and execution of one or more external modules. Or worse the &dothis function may not even have been written yet.

When parsing Perl as code, you must also execute it

Even perl itself never really fully understands the structure of the source code after and indeed as it processes it, and in that sense doesn't "parse" Perl source into anything remotely like a structured document. This makes it of no real use for any task that needs to treat the source code as a document, and do so reliably and robustly.

For more information on why it is impossible to parse perl, see Randal Schwartz's seminal response to the question of "Why can't you parse Perl".

http://www.perlmonks.org/index.pl

The purpose of PPI is not to parse Perl Code, but to parse Perl Documents. By treating the problem this way, we are able to parse a single file containing Perl source code "isolated" from any other resources, such as libraries upon which the code may depend, and without needing to run an instance of perl alongside or inside the parser.

Historically, using an embedded perl parser was widely considered to be the most likely avenue for finding a solution to Parse::Perl. It was investigated from time to time and attempts have generally failed or suffered from sufficiently bad corner cases that they were abandoned.

What Does PPI Stand For?

PPI is an acronym for the longer original module name Parse::Perl::Isolated. And in the spirit or the silly acronym games played by certain unnamed Open Source projects you may have hurd of, it also a reverse backronym of "I Parse Perl".

Of course, I could just be lying and have just made that second bit up 10 minutes before the release of PPI 1.000. Besides, all the cool Perl packages have TLAs (Three Letter Acronyms). It's a rule or something.

Why don't you just think of it as the Perl Parsing Interface for simplicity.

The original name was shortened to prevent the author (and you the users) from contracting RSI by having to type crazy things like Parse::Perl::Isolated::Token::QuoteLike::Backtick 100 times a day.

In acknowledgment that someone may some day come up with a valid solution for the grammar problem it was decided at the commencement of the project to leave the Parse::Perl namespace free for any such effort.

Since that time I've been able to prove to my own satisfaction that it is truly impossible to accurately parse Perl as both code and document at once. For the academics, parsing Perl suffers from the "Halting Problem".

With this in mind Parse::Perl has now been co-opted as the title for the SourceForge project that publishes PPI and a large collection of other applications and modules related to the (document) parsing of Perl source code.

You can find this project at http://sf.net/projects/parseperl, however we no longer use the SourceForge CVS server. Instead, the current development version of PPI is available via SVN at http://svn.phase-n.com/svn/cpan/trunk/PPI/.

Why Parse Perl?

Once you can accept that we will never be able to parse Perl well enough to meet the standards of things that treat Perl as code, it is worth re-examining why we want to "parse" Perl at all.

What are the things that people might want a "Perl parser" for.

Documentation

Analyzing the contents of a Perl document to automatically generate documentation, in parallel to, or as a replacement for, POD documentation.

Allow an indexer to to locate and process all the comments and documentation from code for "full text search" applications.

Structural and Quality Analysis

Determine quality or other metrics across a body of code, and identify situations relating to particular phrases, techniques or locations.

Index functions, variables and packages within Perl code, and doing search and graph (in the node/edge sense) analysis of large code bases.

Refactoring

Make structural, syntax, or other changes to code in an automated manner, either independently or in assistance to an editor. This sort of task list includes backporting, forward porting, partial evaluation, "improving" code, or whatever. All the sort of things you'd want from a the Perl::Editor manpage.

Layout

Change the layout of code without changing its meaning. This includes techniques such as tidying (like perltidy), obfuscation, compressing and "squishing", or to implement formatting preferences or policies.

Presentation

This includes methods of improving the presentation of code, without changing the content of the code. Modify, improve, syntax colour etc the presentation of a Perl document. Generating "IntelliText"-like functions.

If we treat this as a baseline for the sort of things we are going to have to build on top of Perl, then it becomes possible to identify a standard for how good a Perl parser needs to be.

How good is Good Enough(TM)

PPI seeks to be good enough to achieve all of the above tasks, or to provide a sufficiently good API on which to allow others to implement modules in these and related areas.

However, there are going to be limits to this process. Because PPI cannot adapt to changing grammars, any code written using source filters should not be assumed to be parsable.

At one extreme, this includes anything munged by the Acme::Bleach manpage, as well as (arguably) more common cases like the Switch manpage. We do not pretend to be able to always parse code using these modules, although as long as it still follows a format that looks like Perl syntax, it may be possible to extend the lexer to handle them.

The ability to extend PPI to handle lexical additions to the language is on the drawing board to be done some time post-1.0

The goal for success was originally to be able to successfully parse 99% of all Perl documents contained in CPAN. This means the entire file in each case.

PPI has succeeded in this goal far beyond the expectations of even the author. At time of writing there are only 28 non-Acme Perl modules in CPAN that PPI is incapable of parsing. Most of these are so badly broken they do not compile as Perl code anyway.

So unless you are actively going out of your way to break PPI, you should expect that it will handle your code just fine.

Internationalisation

PPI provides partial support for internationalisation and localisation.

Specifically, it allows the use characters from the Latin-1 character set to be used in quotes, comments, and POD. Primarily, this covers languages from Europe and South America.

PPI does not currently provide support for Unicode, although there is an initial implementation available in a development branch from CVS.

If you need Unicode support, and would like to help stress test the Unicode support so we can move it to the main branch and enable it in the main release should contact the author. (contact details below)

Round Trip Safe

When PPI parses a file it builds everything into the model, including whitespace. This is needed in order to make the Document fully "Round Trip" safe.

The general concept behind a "Round Trip" parser is that it knows what it is parsing is somewhat uncertain, and so expects to get things wrong from time to time. In the cases where it parses code wrongly the tree will serialize back out to the same string of code that was read in, repairing the parser's mistake as it heads back out to the file.

The end result is that if you parse in a file and serialize it back out without changing the tree, you are guaranteed to get the same file you started with. PPI does this correctly and reliably for 100% of all known cases.

What goes in, will come out. Every time.

The one minor exception at this time is that if the newlines for your file are wrong (meaning not matching the platform newline format), PPI will localisation of them for you. (It isn't to be convenient, supporting arbitrary newlines would make some of the code more complicated)

Better control of the newline type is on the wish list though, and anyone wanting to help out is encouraged to contact the author.

IMPLEMENTATION

General Layout

PPI is built upon two primary "parsing" components, the PPI::Tokenizer manpage and the PPI::Lexer manpage, and a large tree of about 50 classes which implement the various the Perl Document Object Model (PDOM).

The PDOM is conceptually similar in style and intent to the regular DOM or other code Abstract Syntax Trees (ASTs), but contains some differences to handle perl-specific cases, and to assist in treating the code as a document. Please note that it is not an implementation of the official Document Object Model specification, only somewhat similar to it.

On top of the Tokenizer, Lexer and the classes of the PDOM, sit a number of classes intended to make life a little easier when dealing with PDOM trees.

Both the major parsing components were hand-coded from scratch with only plain Perl code and a few small utility modules. There are no grammar or patterns mini-languages, no YACC or LEX style tools and only a small number of regular expressions.

This is primarily because of the sheer volume of accumulated cruft that exists in Perl. Not even perl itself is capable of parsing Perl documents (remember, it just parses and executes it as code).

As a result, PPI needed to be cruftier than perl itself. Feel free to shudder at this point, and hope you never have to understand the Tokenizer codebase. Speaking of which...

The Tokenizer

The Tokenizer takes source code and converts it into a series of tokens. It does this using a slow but thorough character by character manual process, rather than using a pattern system or complex regexes.

Or at least it does so conceptually. If you were to actually trace the code you would find it's not truly character by character due to a number of regexps and optimisations throughout the code. This lets the Tokenizer "skip ahead" when it can find shortcuts, so it tends to jump around a line a bit wildly at times.

In practice, the number of times the Tokenizer will actually move the character cursor itself is only about 5% - 10% higher than the number of tokens contained in the file. This makes it about as optimal as it can be made without implementing it in something other than Perl.

In 2001 when PPI was started, this structure made PPI quite slow, and not really suitable for interactive tasks. This situation has improved greatly with multi-gigahertz processors, but can still be painful when working with very large files.

The target parsing rate for PPI is about 5000 lines per gigacycle. It is currently believed to be at about 1500, and main avenue for making it to the target speed has now become the PPI::XS manpage, a drop-in XS accelerator for PPI.

Since the PPI::XS manpage has only just gotten off the ground and is currently only at proof-of-concept stage, this may take a little while. Anyone interested in helping out with the PPI::XS manpage is highly encouraged to contact the author. In fact, the design of the PPI::XS manpage means it's possible to port one function at a time safely and reliably. So every little bit will help.

The Lexer

The Lexer takes a token stream, and converts it to a lexical tree. Because we are parsing Perl documents this includes whitespace, comments, and all number of weird things that have no relevance when code is actually executed.

An instantiated the PPI::Lexer manpage consumes the PPI::Tokenizer manpage objects and produces the PPI::Document manpage objects. However you should probably never be working with the Lexer directly. You should just be able to create the PPI::Document manpage objects and work with them directly.

The Perl Document Object Model

The PDOM is a structured collection of data classes that together provide a correct and scalable model for documents that follow the standard Perl syntax.

The PDOM Class Tree

The following lists all of the 62 current PDOM classes, listing with indentation based on inheritance.

   PPI::Element
      PPI::Node
         PPI::Document
            PPI::Document::Fragment
         PPI::Statement
            PPI::Statement::Package
            PPI::Statement::Include
            PPI::Statement::Sub
               PPI::Statement::Scheduled
            PPI::Statement::Compound
            PPI::Statement::Break
            PPI::Statement::Data
            PPI::Statement::End
            PPI::Statement::Expression
               PPI::Statement::Variable
            PPI::Statement::Null
            PPI::Statement::UnmatchedBrace
            PPI::Statement::Unknown
         PPI::Structure
            PPI::Structure::Block
            PPI::Structure::Subscript
            PPI::Structure::Constructor
            PPI::Structure::Condition
            PPI::Structure::List
            PPI::Structure::ForLoop
            PPI::Structure::Unknown
      PPI::Token
         PPI::Token::Whitespace
         PPI::Token::Comment
         PPI::Token::Pod
         PPI::Token::Number
         PPI::Token::Word
         PPI::Token::DashedWord
         PPI::Token::Symbol
            PPI::Token::Magic
         PPI::Token::ArrayIndex
         PPI::Token::Operator
         PPI::Token::Quote
            PPI::Token::Quote::Single
            PPI::Token::Quote::Double
            PPI::Token::Quote::Literal
            PPI::Token::Quote::Interpolate
         PPI::Token::QuoteLike
            PPI::Token::QuoteLike::Backtick
            PPI::Token::QuoteLike::Command
            PPI::Token::QuoteLike::Regexp
            PPI::Token::QuoteLike::Words
            PPI::Token::QuoteLike::Readline
         PPI::Token::Regexp
            PPI::Token::Regexp::Match
            PPI::Token::Regexp::Substitute
            PPI::Token::Regexp::Transliterate
         PPI::Token::HereDoc
         PPI::Token::Cast
         PPI::Token::Structure
         PPI::Token::Label
         PPI::Token::Separator
         PPI::Token::Data
         PPI::Token::End
         PPI::Token::Prototype
         PPI::Token::Attribute
         PPI::Token::Unknown

To summarize the above layout, all PDOM objects inherit from the the PPI::Element manpage class.

Under this are the PPI::Token manpage, strings of content with a known type, and the PPI::Node manpage, syntactically significant containers that hold other Elements.

The three most important of these are the the PPI::Document manpage, the the PPI::Statement manpage and the the PPI::Structure manpage classes.

The Document, Statement and Structure

At the top of all complete PDOM trees is a the PPI::Document manpage object. It represents a complete file of Perl source code as you might find it on disk.

Each Document will contain a number of Statements, Structures and Tokens.

A the PPI::Statement manpage is any series of Tokens and Structures that are treated as a single contiguous statement by perl itself. You should note that a Statement is as close as PPI can get to "parsing" the code in the sense that perl-itself parses Perl code when it is building the op-tree. Because of the assumed isolation, PPI cannot accurately determine precedence of operators or which tokens are implicit arguments to a sub call.

So rather than lead you on with a bad guess, PPI does not attempt to determine precedence or sub parameters at all.

At a fundamental level, it only knows that this series of elements represents a single Statement as perl sees it, and does so with reasonable certainty.

However for specific Statement types the PDOM is able to derive additional useful information about their meaning. For the best and most heavily used example, see the PPI::Statement::Include manpage.

A the PPI::Structure manpage is any series of tokens contained within matching braces. This includes code blocks, conditions, function argument braces, anonymous array constructors, lists, scoping braces and all other syntactic structures represented by a matching pair of braces, including <READLINE> braces.

Each Structure contains none, one, or many Tokens and Structures (the rules for which vary for the different Structure subclasses)

In the PDOM structure rules, a Statement can never directly contain another child Statement, a Structure can never directly contain another child Structure, and a Document can never contain another Document anywhere in the tree.

Aside from these three rules, the PDOM tree is extremely flexible.

The PDOM at Work

To demonstrate the PDOM in use lets start with an example showing how the PDOM tree might look for the following chunk of simple Perl code.

  #!/usr/bin/perl

  print( "Hello World!" );

  exit();

Translated into a PDOM tree it would have the following structure.

  PPI::Document
    PPI::Token::Comment                '#!/usr/bin/perl\n'
    PPI::Token::Whitespace             '\n'
    PPI::Statement
      PPI::Token::Bareword             'print'
      PPI::Structure::List             ( ... )
        PPI::Token::Whitespace         ' '
        PPI::Statement::Expression
          PPI::Token::Quote::Double    '"Hello World!"'
        PPI::Token::Whitespace         ' '
      PPI::Token::Structure            ';'
    PPI::Token::Whitespace             '\n'
    PPI::Token::Whitespace             '\n'
    PPI::Statement
      PPI::Token::Bareword             'exit'
      PPI::Structure::List             ( ... )
      PPI::Token::Structure            ';'
    PPI::Token::Whitespace             '\n'

Please note that in this this example, strings are only listed for the actual the PPI::Token manpage that contains that string. Structures are listed with the type of brace characters it represents noted.

The the PPI::Dumper manpage module can be used to generate similar trees yourself.

We can make that PDOM dump a little easier to read if we strip out all the whitespace. Here it is again, sans the distracting whitespace tokens.

  PPI::Document
    PPI::Token::Comment                '#!/usr/bin/perl\n'
    PPI::Statement
      PPI::Token::Bareword             'print'
      PPI::Structure::List             ( ... )
        PPI::Statement::Expression
          PPI::Token::Quote::Double    '"Hello World!"'
      PPI::Token::Structure            ';'
    PPI::Statement
      PPI::Token::Bareword             'exit'
      PPI::Structure::List             ( ... )
      PPI::Token::Structure            ';'

As you can see, the tree can get fairly deep at time, especially when every isolated token in a bracket becomes its own statement. This is needed to allow anything inside the tree the ability to grow. It also makes the search and analysis algorithms much more flexible.

Because of the depth and complexity of PDOM trees, a vast number of very easy to use methods have been added wherever possible to help people working with PDOM trees do normal tasks relatively quickly and efficiently.

Overview of the Primary Classes

The main PPI classes, and links to their own documentation, are listed here in alphabetical order.

the PPI::Document manpage

The Document object, the root of the PDOM.

the PPI::Document::Fragment manpage

A cohesive fragment of a larger Document. Although not of any real current use, it is planned for use in certain internal tree manipulation algorithms.

For example, doing things like cut/copy/paste etc. Very similar to a the PPI::Document manpage, but has some additional methods and does not represent a lexical scope boundary.

the PPI::Dumper manpage

A simple class for dumping readable debugging version of PDOM structures, such as in the demonstration above.

the PPI::Element manpage

The Element class is the abstract base class for all objects within the PDOM

the PPI::Find manpage

Implements an instantiable object form of a PDOM tree search.

the PPI::Lexer manpage

The PPI Lexer. Converts Token streams into PDOM trees.

the PPI::Node manpage

The Node object, the abstract base class for all PDOM objects that can contain other Elements, such as the Document, Statement and Structure objects.

the PPI::Statement manpage

The base class for all Perl statements. Generic "evaluate for side-effects" statements are of this actual type. Other more interesting statement types belong to one of its children.

See it's own documentation for a longer description and list of all of the different statement types and sub-classes.

the PPI::Structure manpage

The abstract base class for all structures. A Structure is a language construct consisting of matching braces containing a set of other elements.

See the the PPI::Structure manpage documentation for a description and list of all of the different structure types and sub-classes.

the PPI::Token manpage

A token is the basic unit of content. At its most basic, a Token is just a string tagged with metadata (its class, and some additional flags in some cases).

the PPI::Token::_QuoteEngine manpage

The the PPI::Token::Quote manpage and the PPI::Token::QuoteLike manpage classes provide abstract base classes for the many and varied types of quote and quote-like things in Perl. However, much of the actual quote login is implemented in a separate quote engine, based at the PPI::Token::_QuoteEngine manpage.

Classes that inherit from the PPI::Token::Quote manpage, the PPI::Token::QuoteLike manpage and the PPI::Token::Regexp manpage are generally parsed only by the Quote Engine.

the PPI::Tokenizer manpage

The PPI Tokenizer. One Tokenizer consumes a chunk of text and provides access to a stream of the PPI::Token manpage objects.

The Tokenizer is very very complicated, to the point where even the author treads carefully when working with it.

Most of the complication is the result of optimizations which have tripled the tokenization speed, at the expense of maintainability. We cope with the spaghetti by heavily commenting everything.

the PPI::Transform manpage

The Perl Document Transformation API. Provides a standard interface and abstract base class for objects and classes that manipulate Documents.

INSTALLING

The core PPI distribution is pure Perl and has been kept as tight as possible and with as few dependencies as possible.

It should download and install normally on any platform from within the CPAN and CPANPLUS applications, or directly using the distribution tarball. If installing by hand, you may need to install a few small utility modules first. The exact ones will depend on your version of perl.

There are no special install instructions for PPI, and the normal Perl Makefile.PL, make, make test, make install instructions apply.

EXTENDING

The PPI namespace itself is reserved for the sole use of the modules under the umbrella of the Parse::Perl SourceForge project.

http://sf.net/projects/parseperl

You are recommended to use the PPIx:: namespace for PPI-specific modifications or prototypes thereof, or Perl:: for modules which provide a general Perl language-related functions.

If what you wish to implement looks like it fits into PPIx:: namespace, you should consider contacting the Parse::Perl mailing list (detailed on the SourceForge site) first, as what you want may already be in progress, or you may wish to consider joining the team and doing it within the Parse::Perl project itself.

TO DO

- Many more analysis and utility methods for PDOM classes

- Creation of a PPI::Tutorial document

- Add many more key functions to PPI::XS

- We can always write more and better unit tests

- Refactor PPI::Token::Number into multiple subclasses (1.200)

- Complete the full implementation of ->literal (1.200)

- Full understanding of scoping (due 1.300)

SUPPORT

This module is stored in an Open Repository at the following address.

http://svn.phase-n.com/svn/cpan/trunk/PPI

Write access to the repository is made available automatically to any published CPAN author, and to most other volunteers on request.

If you are able to submit your bug report in the form of new (failing) unit tests, or can apply your fix directly instead of submitting a patch, you are strongly encouraged to do so, as the author currently maintains over 100 modules and it can take some time to deal with non-"Critical" bug reports or patches.

This will also guarentee that your issue will be addressed in the next release of the module.

For large changes though, please consider creating a branch so that they can be properly reviewed and trialed before being applied to the trunk.

If you cannot provide a direct test or fix, or don't have time to do so, then regular bug reports are still accepted and appreciated via the CPAN bug tracker.

http://rt.cpan.org/NoAuth/ReportBug.html

For other issues or questions, contact the Parse::Perl project mailing list.

For commercial or media-related enquiries, or to have your SVN commit bit enabled, contact the author.

AUTHOR

Adam Kennedy adamk@cpan.org

ACKNOWLEDGMENTS

A huge thank you to Phase N Australia (http://phase-n.com/) for permitting the original open sourcing and release of this distribution from what was originally several thousand hours of commercial work.

Another big thank you to The Perl Foundation (http://www.perlfoundation.org/) for funding for the final big refactoring and completion run.

Also, to the various co-maintainers that have contributed both large and small with tests and patches and the especially those rare few who have deep-dived into the guts to (gasp) add a feature.

  - Dan Brook       : PPIx::XPath, Acme::PerlML
  - Audrey Tang     : "Line Noise" Testing
  - Arjen Laarhoven : Three-element -E<gt>location

Most of all, thanks to those brave soles willing to dive in and use, test drive and provide feedback on PPI before version 1.000, in some cases before it made it to beta quality, and still did extremely distasteful things (like eating 50 meg of RAM a second).

I owe you all a beer. Corner me somewhere and collect at your convenience. If I missed someone who wasn't in my email history, thank you too :)

  # In approximate order of appearance
  - Claes Jacobsson
  - Michael Schwern
  - Jeff T. Parsons
  - CPAN Author "CHOCOLATEBOY"
  - Robert Rotherberg
  - CPAN Author "PODMASTER"
  - Richard Soderberg
  - Nadim ibn Hamouda el Khemir
  - Graciliano M. P.
  - Leon Brocard
  - Jody Belka
  - Curtis Ovid
  - Yuval Kogman
  - Michael Schilli
  - Slaven Rezic
  - Lars Thegler
  - Tony Stubblebine
  - Tatsuhiko Miyagawa
  - CPAN Author "CHROMATIC"
  - Matisse Enzer
  - Roy Fulbright
  - Dan Brook
  - Johnny Lee
  - Johan Lindstrom

And to single one person out, thanks go to Randal Schwartz who (mostly) spent a great number of hours in IRC over a critical 6 month period explaining why Perl is impossibly unparsable and constantly shoving evil and ugly corner cases in my face. He remained a tireless devil's advocate and without his support this project genuinely could never have been completed.

So for my schooling in the Deep Magik, you have my deepest gratitude Randal.

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Cache - The PPI Document Caching Layer

    • Using PPI::Cache
  • METHODS
    • new param => $value, ...
    • path
    • readonly
    • get_document $md5sum | \$source
    • store_document $Document
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Cache - The PPI Document Caching Layer

SYNOPSIS

  # Set the cache
  use PPI::Cache path => '/var/cache/ppi-cache';

  # Manually create a cache
  my $Cache = PPI::Cache->new(
        path     => '/var/cache/perl/class-PPI',
        readonly => 1,
        );

DESCRIPTION

PPI::Cache provides the default caching functionality for the PPI manpage.

It integrates automatically with the PPI manpage itself. Once enabled, any attempt to load a document from the filesystem will be cached via cache.

Please note that creating a the PPI::Document manpage from raw source or something other object will not be cached.

Using PPI::Cache

The most common way of using PPI::Cache is to provide parameters to the use statement at the beginning of your program.

  # Load the class but do not set a cache
  use PPI::Cache;

  # Use a fairly normal cache location
  use PPI::Cache path => '/var/cache/ppi-cache';

Any of the arguments that can be provided to the new constructor can also be provided to use.

METHODS

new param => $value, ...

The new constructor creates a new standalone cache object.

It takes a number of parameters to control the cache.

path

The path param sets the base directory for the cache. It must already exist, and must be writable.

readonly

The readonly param is a true/false flag that allows the use of an existing cache by a less-privileged user (such as the web user).

Existing documents will be retrieved from the cache, but new documents will not be written to it.

Returns a new PPI::Cache object, or dies on error.

path

The path accessor returns the path on the local filesystem that is the root of the cache.

readonly

The readonly accessor returns true if documents should not be written to the cache.

get_document $md5sum | \$source

The get_document method checks to see if a Document is stored in the cache and retrieves it if so.

store_document $Document

The store_document method takes a the PPI::Document manpage as argument and explicitly adds it to the cache.

Returns true if saved, or undef (or dies) on error.

FIXME (make this return either one or the other, not both)

TO DO

- Finish the basic functionality

- Add support for use PPI::Cache auto-setting $PPI::Document::CACHE

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright (c) 2005 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Document - Object representation of a Perl document

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
    • Storable Support
  • METHODS
    • new
    • set_cache $cache
    • get_cache
    • readonly
    • tab_width [ $width ]
    • save
    • serialize
    • hex_id
    • index_locations
    • flush_locations
    • normalized
    • errstr
  • TO DO
  • SUPPORT
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

PPI::Document - Object representation of a Perl document

INHERITANCE

  PPI::Document
  isa PPI::Node
      isa PPI::Element

SYNOPSIS

  use PPI;

  # Load a document from a file
  my $Document = PPI::Document->new('My/Module.pm');

  # Strip out comments
  $Document->prune('PPI::Token::Comment');

  # Find all the named subroutines
  my @subs = $Document->find(
        sub { $_[1]->isa('PPI::Statement::Sub') and $_[1]->name }
        );

  # Save the file
  $Document->save('My/Module.pm.stripped');

DESCRIPTION

The PPI::Document class represents a single Perl "document". A PPI::Document object acts as a root the PPI::Node manpage, with some additional methods for loading and saving, and working with the line/column locations of Elements within a file.

The exemption to its the PPI::Node manpage-like behavior this is that a PPI::Document object can NEVER have a parent node, and is always the root node in a tree.

Storable Support

PPI::Document implements the necessary STORABLE_freeze and STORABLE_thaw hooks to provide native support for the Storable manpage, if you have it installed.

However if you want to clone clone a Document, you are highly recommended to use the internal $Document->clone method rather than Storable's dclone function (although dclone should still work).

METHODS

Most of the things you are likely to want to do with a Document are probably going to involve the methods from the PPI::Node manpage class, of which this is a subclass.

The methods listed here are the remaining few methods that are truly Document-specific.

new

  # Simple construction
  $doc = PPI::Document->new( $filename );
  $doc = PPI::Document->new( \$source  );

  # With the readonly attribute set
  $doc = PPI::Document->new( $filename,
          readonly => 1,
          );

The new constructor takes as argument a variety of different sources of Perl code, and creates a single cohesive Perl PPI::Document for it.

If passed a file name as a normal string, it will attempt to load the document from the file.

If passed a reference to a SCALAR, this is taken to be source code and parsed directly to create the document.

If passed zero arguments, a "blank" document will be created that contains no content at all.

In all cases, the document is considered to be "anonymous" and not tied back to where it was created from. Specifically, if you create a PPI::Document from a filename, the document will not remember where it was created from.

The constructor also takes attribute flags.

At this time, the only available attribute is the readonly flag.

Setting readonly to true will allow various systems to provide additional optimisations and caching. Note that because readonly is an optimisation flag, it is off by default and you will need to explicitly enable it.

Returns a PPI::Document object, or undef if parsing fails.

set_cache $cache

As of the PPI manpage 1.100, PPI::Document supports parser caching.

The default cache class the PPI::Cache manpage provides a the Storable manpage-based caching or the parsed document based on the MD5 hash of the document as a string.

The static set_cache method is used to set the cache object for PPI::Document to use when loading documents. It takes as argument a the PPI::Cache manpage object (or something that isa the same).

If passed undef, this method will stop using the current cache, if any.

For more information on caching, see the PPI::Cache manpage.

Returns true on success, or undef if not passed a valid param.

get_cache

If a document cache is currently set, the get_cache method will return it.

Returns a the PPI::Cache manpage object, or undef if there is no cache currently set for PPI::Document.

readonly

The readonly attribute indicates if the document is intended to be read-only, and will never be modified. This is an advisory flag, that writers of the PPI manpage-related systems may or may not use to enable optimisations and caches for your document.

Returns true if the document is read-only or false if not.

tab_width [ $width ]

In order to handle support for location correctly, Documents need to understand the concept of tabs and tab width. The tab_width method is used to get and set the size of the tab width.

At the present time, PPI only supports "naive" (width 1) tabs, but we do plan on supporting arbitrary, default and auto-sensing tab widths later.

Returns the tab width as an integer, or dies if you attempt to set the tab width.

save

  $document->save( $file )

The C<save> method serializes the C<PPI::Document> object and saves the
resulting Perl document to a file. Returns C<undef> on failure to open
or write to the file.

serialize

Unlike the content method, which shows only the immediate content within an element, Document objects also have to be able to be written out to a file again.

When doing this we need to take into account some additional factors.

Primarily, we need to handle here-docs correctly, so that are written to the file in the expected place.

The serialize method generates the actual file content for a given Document object. The resulting string can be written straight to a file.

Returns the serialized document as a string.

hex_id

The hex_id method generates an unique identifier for the Perl document.

This identifier is basically just the serialized document, with Unix-specific newlines, passed through MD5 to produce a hexadecimal string.

This identifier is used by a variety of systems (such as the PPI::Cache manpage and the Perl::Metrics manpage) as a unique key against which to store or cache information about a document (or indeed, to cache the document itself).

Returns a 32 character hexadecimal string.

index_locations

Within a document, all the PPI::Element manpage objects can be considered to have a "location", a line/column position within the document when considered as a file. This position is primarily useful for debugging type activities.

The method for finding the position of a single Element is a bit laborious, and very slow if you need to do it a lot. So the index_locations method will index and save the locations of every Element within the Document in advance, making future calls to <PPI::Element::location> virtually free.

Please note that this is index should always be cleared using flush_locations once you are finished with the locations. If content is added to or removed from the file, these indexed locations will be wrong.

flush_locations

When no longer needed, the flush_locations method clears all location data from the tokens.

normalized

The normalized method is used to generate a "Layer 1" the PPI::Document::Normalized manpage object for the current Document.

A "normalized" Perl Document is an arbitrary structure that removes any irrelevant parts of the document and refactors out variations in style, to attempt to approach something that is closer to the "true meaning" of the Document.

See the PPI::Normal manpage for more information on document normalization and the tasks for which it is useful.

Returns a the PPI::Document::Normalized manpage object, or undef on error.

errstr

For error that occur when loading and saving documents, you can use errstr, as either a static or object method, to access the error message.

If a Document loads or saves without error, errstr will return false.

TO DO

- May need to overload some methods to forcefully prevent Document objects becoming children of another Node.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

the PPI manpage, http://ali.as/

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Document::File - A Perl Document located in a specific file

  • METHODS
    • new
    • filename
    • save
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Document::File - A Perl Document located in a specific file

DESCRIPTION

WARNING: This class is experimental, and may change without notice

PPI::Document::File provides a the PPI::Document manpage subclass that represents a Perl document stored in a specific named file.

METHODS

new

  my $file = PPI::Document::File->new( 'Module.pm' );

The new constructor works the same as for the regular one, except that the only params allowed is a file name. You cannot create an "anonymous" PPI::Document::File object, not can you create an empty one.

Returns a new PPI::Document::File object, or undef on error.

filename

The filename accessor returns the name of the file in which the document is stored.

save

  # Save to the file we were loaded from
  $file->save;

  # Save a copy to somewhere else
  $file->save( 'Module2.pm' );

The save method works similarly to the one in the parent the PPI::Document manpage class, saving a copy of the document to a file.

The difference with this subclass is that if save is not passed any filename, it will save it back to the file it was loaded from.

Note: When saving to a different file, it is considered to be saving a copy and so the value returned by the filename accessor will stay the same, and not change to the new filename.

TO DO

- May need to overload some methods to forcefully prevent Document objects becoming children of another Node.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Document::Fragment - A fragment of a Perl Document

  • METHODS
    • index_locations
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Document::Fragment - A fragment of a Perl Document

DESCRIPTION

In some situations you might want to work with a fragment of a larger document. PPI::Document::Fragment is a class intended for this purpose. It is functionally almost identical to a normal the PPI::Document manpage, except that it is not possible to get line/column positions for the elements within it, and it does not represent a scope.

METHODS

index_locations

Unlike when called on a PPI::Document object, you should not be attempting to find locations of things within a PPI::Document::Fragment, and thus any call to the index_locations will print a warning and return undef instead of attempting to index the locations of the Elements.

TO DO

Integrate this into the rest of PPI so it has actual practical uses. The most obvious would be to implement arbitrary cut/copy/paste more easily.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Document::Normalized - A normalized Perl Document

  • METHODS
    • new
    • version
    • functions
    • equal $Normalized
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Document::Normalized - A normalized Perl Document

DESCRIPTION

A Normalized Document object is the result of the normalization process contained in the the PPI::Normal manpage class. See the documentation for the PPI::Normal manpage for more information.

The object contains a version stamp and function list for the version of the PPI::Normal manpage used to create it, and a processed and delinked the PPI::Document manpage object.

Typically, the Document object will have been mangled by the normalization process in a way that would make it fatal to try to actually DO anything with it.

Put simply, never use the Document object after normalization. YOU HAVE BEEN WARNED!

The object is designed the way it is to provide a bias towards false negatives. A comparison between two ::Normalized object will only return true if they were produced by the same version of PPI::Normal, with the same set of normalization functions (in the same order).

You may get false negatives if you are caching objects across an upgrade.

Please note that this is done for security purposes, as there are many cases in which low layer normalization is likely to be done as part of a code security process, and false positives could be highly dangerous.

METHODS

new

The new method is intended for use only by the the PPI::Normal manpage class, and to get ::Normalized objects, you are highly recommended to use either that module, or the normalized method of the the PPI::Document manpage object itself.

version

The version accessor returns the the PPI::Normal manpage version used to create the object.

functions

The functions accessor returns a reference to an array of the normalization functions (in order) that were called when creating the object.

equal $Normalized

The equal method is the primary comparison method, taking another PPI::Document::Normalized object, and checking for equivalence to it.

The == operator is also overload to this method, so that you can do something like the following:

  my $first  = PPI::Document->load('first.pl');
  my $second = PPI::Document->load('second.pl');

  if ( $first->normalized == $second->normalized ) {
        print "The two documents are equivalent";
  }

Returns true if the normalized documents are equivalent, false if not, or undef if there is an error.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright (c) 2005 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Dumper - Dumping of PDOM trees

  • METHODS
    • new $Element, param => value, ...
    • print
    • string
    • list
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Dumper - Dumping of PDOM trees

SYNOPSIS

  # Load a document
  my $Module = PPI::Document->new( 'MyModule.pm' );

  # Create the dumper
  my $Dumper = PPI::Dumper->new( $Module );

  # Dump the document
  $Dumper->print;

DESCRIPTION

The PDOM trees in PPI are quite complex, and getting a dump of their structure for development and debugging purposes is important.

This module provides that functionality.

The process is relatively simple. Create a dumper object with a particular set of options, and then call one of the dump methods to generate the dump content itself.

METHODS

new $Element, param => value, ...

The new constructor creates a dumper, and takes as argument a single the PPI::Element manpage object of any type to serve as the root of the tree to be dumped, and a number of key->value parameters to control the output format of the Dumper. Details of the parameters are listed below.

Returns a new PPI::Dumper object, or undef if the constructor is not passed a correct the PPI::Element manpage root object.

memaddr

Should the dumper print the memory addresses of each PDOM element. True/false value, off by default.

indent

Should the structures being dumped be indented. This value is numeric, with the number representing the number of spaces to use when indenting the dumper output. Set to '2' by default.

class

Should the dumper print the full class for each element. True/false value, on by default.

content

Should the dumper show the content of each element. True/false value, on by default.

whitespace

Should the dumper show whitespace tokens. By not showing the copious numbers of whitespace tokens the structure of the code can often be made much clearer. True/false value, on by default.

comments

Should the dumper show comment tokens. In situations where you have a lot of comments, the code can often be made clearer by ignoring comment tokens. True/value value, on by default.

locations

Should the dumper show the location of each token. The values shown are [ line, rowchar, column ]. See location in the PPI::Element manpage for a description of what these values really are. True/false value, off by default.

print

The print method generates the dump and prints it to STDOUT.

Returns as for the internal print function.

string

The string method generates the dump and provides it as a single string.

Returns a string or undef if there is an error while generating the dump.

list

The list method generates the dump and provides it as a raw list, without trailing newlines.

Returns a list or the null list if there is an error while generation the dump.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Element - The abstract Element class, a base for all source objects

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • significant
    • class
    • tokens
    • content
    • parent
    • statement
    • top
    • next_sibling
    • snext_sibling
    • previous_sibling
    • sprevious_sibling
    • first_token
    • last_token
    • next_token
    • previous_token
    • clone
    • insert_before @Elements
    • insert_after @Elements
    • remove
    • delete
    • replace $Element
    • location
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Element - The abstract Element class, a base for all source objects

INHERITANCE

  PPI::Element is the root of the PDOM tree

DESCRIPTION

The abstract PPI::Element serves as a base class for all source-related objects, from a single whitespace token to an entire document. It provides a basic set of methods to provide a common interface and basic implementations.

METHODS

significant

Because we treat whitespace and other non-code items as Tokens (in order to be able to "round trip" the the PPI::Document manpage back to a file) the significant method allows us to distinguish between tokens that form a part of the code, and tokens that aren't significant, such as whitespace, POD, or the portion of a file after (and including) the __END__ token.

Returns true if the Element is significant, or false it not.

class

The class method is provided as a convenience, and really does nothing more than returning ref($self). However, some people have found that they appreciate the laziness of $Foo->class eq 'whatever', so I have caved to popular demand and included it.

Returns the class of the Element as a string

tokens

The tokens method returns a list of the PPI::Token manpage objects for the Element, essentially getting back that part of the document as if it had not been lexed.

This also means there are no Statements and no Structures in the list, just the Token classes.

content

For any PPI::Element, the content method will reconstitute the base code for it as a single string. This method is also the method used for overloading stringification. When an Element is used in a double-quoted string for example, this is the method that is called.

WARNING:

You should be aware that because of the way that here-docs are handled, any here-doc content is not included in content, and as such you should not eval or execute the result if it contains any the PPI::Token::HereDoc manpage.

The the PPI::Document manpage method serialize should be used to stringify a PDOM document into something that can be executed as expected.

Returns the basic code as a string (excluding here-doc content).

parent

Elements themselves are not intended to contain other Elements, that is left to the the PPI::Node manpage abstract class, a subclass of PPI::Element. However, all Elements can be contained within a parent Node.

If an Element is within a parent Node, the parent method returns the Node.

statement

For a PPI::Element that is contained (at some depth) within a the PPI::Statment manpage, the statement method will return the first parent Statement object lexically 'above' the Element.

Returns a the PPI::Statement manpage object, which may be the same Element if the Element is itself a the PPI::Statement manpage object.

Returns false if the Element is not within a Statement and is not itself a Statement.

top

For a PPI::Element that is contained within a PDOM tree, the top method will return the top-level Node in the tree. Most of the time this should be a the PPI::Document manpage object, however this will not always be so. For example, if a subroutine has been removed from its Document, to be moved to another Document.

Returns the top-most PDOM object, which may be the same Element, if it is not within any parent PDOM object.

For an Element that is contained within a the PPI::Document manpage object, the document method will return the top-level Document for the Element.

Returns the the PPI::Document manpage for this Element, or false if the Element is not contained within a Document.

next_sibling

All the PPI::Node manpage objects (specifically, our parent Node) contain a number of PPI::Element objects. The next_sibling method returns the PPI::Element immediately after the current one, or false if there is no next sibling.

snext_sibling

As per the other 's' methods, the snext_sibling method returns the next significant sibling of the PPI::Element object.

Returns a PPI::Element object, or false if there is no 'next' significant sibling.

previous_sibling

All the PPI::Node manpage objects (specifically, our parent Node) contain a number of PPI::Element objects. The previous_sibling method returns the Element immediately before the current one, or false if there is no 'previous' PPI::Element object.

sprevious_sibling

As per the other 's' methods, the sprevious_sibling method returns the previous significant sibling of the PPI::Element object.

Returns a PPI::Element object, or false if there is no 'previous' significant sibling.

first_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the first_token method finds the first PPI::Token object within or equal to this one.

That is, if called on a the PPI::Node manpage subclass, it will descend until it finds a the PPI::Token manpage. If called on a the PPI::Token manpage object, it will return the same object.

Returns a the PPI::Token manpage object, or dies on error (which should be extremely rare and only occur if an illegal empty the PPI::Statement manpage exists below the current Element somewhere.

last_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the last_token method finds the last PPI::Token object within or equal to this one.

That is, if called on a the PPI::Node manpage subclass, it will descend until it finds a the PPI::Token manpage. If called on a the PPI::Token manpage object, it will return the itself.

Returns a the PPI::Token manpage object, or dies on error (which should be extremely rare and only occur if an illegal empty the PPI::Statement manpage exists below the current Element somewhere.

next_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the next_token method finds the the PPI::Token manpage object that is immediately after the current Element, even if it is not within the same parent the PPI::Node manpage as the one for which the method is being called.

Note that this is not defined as a the PPI::Token manpage-specific method, because it can be useful to find the next token that is after, say, a the PPI::Statement manpage, although obviously it would be useless to want the next token after a the PPI::Document manpage.

Returns a the PPI::Token manpage object, or false if there are no more tokens after the Element.

previous_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the previous_token method finds the the PPI::Token manpage object that is immediately before the current Element, even if it is not within the same parent the PPI::Node manpage as this one.

Note that this is not defined as a the PPI::Token manpage-only method, because it can be useful to find the token is before, say, a the PPI::Statement manpage, although obviously it would be useless to want the next token before a the PPI::Document manpage.

Returns a the PPI::Token manpage object, or false if there are no more tokens before the Element.

clone

As per the Clone module, the clone method makes a perfect copy of an Element object. In the generic case, the implementation is done using the Clone module's mechanism itself. In higher-order cases, such as for Nodes, there is more work involved to keep the parent-child links intact.

insert_before @Elements

The insert_before method allows you to insert lexical perl content, in the form of PPI::Element objects, before the calling Element. You need to be very careful when modifying perl code, as it's easy to break things.

In its initial incarnation, this method allows you to insert a single Element, and will perform some basic checking to prevent you inserting something that would be structurally wrong (in PDOM terms).

In future, this method may be enhanced to allow the insertion of multiple Elements, inline-parsed code strings or the PPI::Document::Fragment manpage objects.

Returns true if the Element was inserted, false if it can not be inserted, or undef if you do not provide a the PPI::Element manpage object as a parameter.

insert_after @Elements

The insert_after method allows you to insert lexical perl content, in the form of PPI::Element objects, after the calling Element. You need to be very careful when modifying perl code, as it's easy to break things.

In its initial incarnation, this method allows you to insert a single Element, and will perform some basic checking to prevent you inserting something that would be structurally wrong (in PDOM terms).

In future, this method may be enhanced to allow the insertion of multiple Elements, inline-parsed code strings or the PPI::Document::Fragment manpage objects.

Returns true if the Element was inserted, false if it can not be inserted, or undef if you do not provide a the PPI::Element manpage object as a parameter.

remove

For a given PPI::Element, the remove method will remove it from its parent intact, along with all of its children.

Returns the Element itself as a convenience, or undef if an error occurs while trying to remove the Element.

delete

For a given PPI::Element, the remove method will remove it from its parent, immediately deleting the Element and all of its children (if it has any).

Returns true if the Element was successfully deleted, or undef if an error occurs while trying to remove the Element.

replace $Element

Although some higher level class support more exotic forms of replace, at the basic level the replace method takes a single Element as an argument and replaces the current Element with it.

To prevent accidental damage to code, in this initial implementation the replacement element must be of the same class (or a subclass) as the one being replaced.

location

If the Element exists within a the PPI::Document manpage that has indexed the Element locations using PPI::Document::index_locations, the location method will return the location of the first character of the Element within the Document.

Returns the location as a reference to a three-element array in the form [ $line, $rowchar, $col ]. The values are in a human format, with the first character of the file located at [ 1, 1, 1 ].

The second and third numbers are similar, except that the second is the literal horizontal character, and the third is the visual column, taking into account tabbing.

Returns undef on error, or if the the PPI::Document manpage object has not been indexed.

TO DO

It would be nice if location could be used in an ad-hoc manner. That is, if called on an Element within a Document that has not been indexed, it will do a one-off calculation to find the location. It might be very painful if someone started using it a lot, without remembering to index the document, but it would be handy for things that are only likely to use it once, such as error handlers.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Find - Object version of the Element->find method

    • History
    • Structure and Style
    • The &wanted function
  • METHODS
    • new &wanted
    • clone
    • in $Document [, array_ref => 1 ]
    • start $Element
    • match
    • finish
    • errstr
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Find - Object version of the Element->find method

SYNOPSIS

  # Create the Find object
  my $Find = PPI::Find->new( \&wanted );

  # Return all matching Elements as a list
  my @found = $Find->in( $Document );

  # Can we find any matching Elements
  if ( $Find->any_matches($Document) ) {
        print "Found at least one matching Element";
  }

  # Use the object as an iterator
  $Find->start($Document) or die "Failed to execute search";
  while ( my $token = $Find->match ) {
        ...
  }

DESCRIPTION

PPI::Find is the primary PDOM searching class in the core PPI package.

History

It became quite obvious during the development of PPI that many of the modules that would be built on top of it were going to need large numbers of saved, storable or easily creatable search objects that could be reused a number of times.

Although the internal ->find method provides a basic ability to search, it is by no means thorough. PPI::Find attempts to resolve this problem.

Structure and Style

PPI::Find provides a similar API to the popular the File::Find::Rule manpage module for file searching, but without the ability to assemble queries.

The implementation of a separate PPI::Find::Rule sub-class that does provide this ability is left as an exercise for the reader.

The &wanted function

At the core of each PPI::Find object is a "wanted" function that is passed a number of arguments and returns a value which controls the flow of the search.

As the search executes, each Element will be passed to the wanted function in depth-first order.

It will be provided with two arguments. The current Element to test as $_[0], and the top-level Element of the search as $_[1].

The &wanted function is expected to return 1 (positive) if the Element matches the condition, 0 (false) if it does not, and undef (undefined) if the condition does not match, and the Find search should not descend to any of the current Element's children.

Errors should be reported from the &wanted function via die, which will be caught by the Find object and returned as an error.

METHODS

new &wanted

The new constructor takes a single argument of the &wanted function, as described above and creates a new search.

Returns a new PPI::Find object, or undef if not passed a CODE reference.

clone

The clone method creates another instance of the same Find object.

The cloning is done safely, so if your existing Find object is in the middle of an iteration, the cloned Find object will not also be in the iteration and can be safely used independently.

Returns a duplicate PPI::Find object.

in $Document [, array_ref => 1 ]

The in method starts and completes a full run of the search.

It takes as argument a single the PPI::Element manpage object which will serve as the top of the search process.

Returns a list of PPI::Element objects that match the condition described by the &wanted function, or the null list on error.

You should check the ->errstr method for any errors if you are returned the null list, which may also mean simply that no Elements were found that matched the condition.

Because of this need to explicitly check for errors, an alternative return value mechanism is provide. If you pass the array_ref = 1> parameter to the method, it will return the list of matched Elements as a reference to an ARRAY. The method will return false if no elements were matched, or undef on error.

The ->errstr method can still be used to get the error message as normal.

start $Element

The start method lets the Find object act as an iterator. The method is passed the parent PPI::Element object as for the in method, but does not accept any parameters.

To simplify error handling, the entire search is done at once, with the results cached and provided as-requested.

Returns true if the search completes, and false on error.

match

The match method returns the next matching Element in the iteration.

Returns a PPI::Element object, or undef if there are no remaining Elements to be returned.

finish

The finish method provides a mechanism to end iteration if you wish to stop the iteration prematurely. It resets the Find object and allows it to be safely reused.

A Find object will be automatically finished when match returns false. This means you should only need to call finnish when you stop iterating early.

You may safely call this method even when not iterating and it will return without failure.

Always returns true

errstr

The errstr method returns the error messages when a given PPI::Find object fails any action.

Returns a string, or undef if there is no error.

TO DO

- Implement the the PPI::Find::Rule manpage class

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Lexer - The PPI Lexer

  • METHODS
    • new
    • lex_file $filename
    • lex_source $string
    • lex_tokenizer $Tokenizer
    • errstr
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Lexer - The PPI Lexer

SYNOPSIS

  use PPI;

  # Create a new Lexer
  my $Lexer = PPI::Lexer->new;

  # Build a PPI::Document object from a Token stream
  my $Tokenizer = PPI::Tokenizer->load( 'My/Module.pm' );
  my $Document = $Lexer->lex_tokenizer( $Tokenizer );

  # Build a PPI::Document object for some raw source
  my $source = "print 'Hello World!'; kill(Humans->all);";
  $Document = $Lexer->lex_source( $source );

  # Build a PPI::Document object for a particular file name
  $Document = $Lexer->lex_file( 'My/Module.pm' );

DESCRIPTION

The is the PPI Lexer. In the larger scheme of things, its job is to take token streams, in a variety of forms, and "lex" them into nested structures.

Pretty much everything in this module happens behind the scenes at this point. In fact, at the moment you don't really need to instantiate the lexer at all, the three main methods will auto-instantiate themselves a PPI::Lexer object as needed.

All methods do a one-shot "lex this and give me a the PPI::Document manpage object".

In fact, if you are reading this, what you probably want to do is to just "load a document", in which case you can do this in a much more direct and concise manner with one of the following.

  use PPI;

  $Document = PPI::Document->load( $filename );
  $Document = PPI::Document->new( $string );

See the PPI::Document manpage for more details.

For more unusual tasks, by all means forge onwards.

METHODS

new

The new constructor creates a new PPI::Lexer object. The object itself is merely used to hold various buffers and state data during the lexing process, and holds no significant data between ->lex_xxxxx calls.

Returns a new PPI::Lexer object

lex_file $filename

The lex_file method takes a filename as argument. It then loads the file, creates a the PPI::Tokenizer manpage for the content and lexes the token stream produced by the tokenizer. Basically, a sort of all-in-one method for getting a the PPI::Document manpage object from a file name.

Returns a the PPI::Document manpage object, or undef on error.

lex_source $string

The lex_source method takes a normal scalar string as argument. It creates a the PPI::Tokenizer manpage object for the string, and then lexes the resulting token stream.

Returns a the PPI::Document manpage object, or undef on error.

lex_tokenizer $Tokenizer

The lex_tokenizer takes as argument a the PPI::Tokenizer manpage object. It lexes the token stream from the tokenizer into a the PPI::Document manpage object.

Returns a the PPI::Document manpage object, or undef on error.

errstr

For any error that occurs, you can use the errstr, as either a static or object method, to access the error message.

If no error occurs for any particular action, errstr will return false.

TO DO

- Add optional support for some of the more common source filters

- Some additional checks for blessing things into various Statement and Structure subclasses.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Node - Abstract PPI Node class, an Element that can contain other Elements

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
    • scope
    • add_element $Element
    • elements
    • first_element
    • last_element
    • children
    • schildren
    • child $index
    • schild $index
    • contains $Element
    • find $class | \&wanted
    • find_first $class | \&wanted
    • find_any $class | \&wanted
    • remove_child $Element
    • prune $class | \&wanted
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Node - Abstract PPI Node class, an Element that can contain other Elements

INHERITANCE

  PPI::Node
  isa PPI::Element

SYNOPSIS

  # Create a typical node (a Document in this case)
  my $Node = PPI::Document->new;

  # Add an element to the node( in this case, a token )
  my $Token = PPI::Token::Word->new('my');
  $Node->add_element( $Token );

  # Get the elements for the Node
  my @elements = $Node->children;

  # Find all the barewords within a Node
  my $barewords = $Node->find( 'PPI::Token::Word' );

  # Find by more complex criteria
  my $my_tokens = $Node->find( sub { $_[1]->content eq 'my' } );

  # Remove all the whitespace
  $Node->prune( 'PPI::Token::Whitespace' );

  # Remove by more complex criteria
  $Node->prune( sub { $_[1]->content eq 'my' } );

DESCRIPTION

The PPI::Node class provides an abstract base class for the Element classes that are able to contain other elements the PPI::Document manpage, the PPI::Statement manpage, and the PPI::Structure manpage.

As well as those listed below, all of the methods that apply to the PPI::Element manpage objects also apply to PPI::Node objects.

METHODS

scope

The scope method returns true if the node represents a lexical scope boundary, or false if it does not.

add_element $Element

The add_element method adds a the PPI::Element manpage object to the end of a PPI::Node. Because Elements maintain links to their parent, an Element can only be added to a single Node.

Returns true if the the PPI::Element manpage was added. Returns undef if the Element was already within another Node, or the method is not passed a the PPI::Element manpage object.

elements

The elements method accesses all child elements structurally within the PPI::Node object. Note that in the base of the the PPI::Structure manpage classes, this DOES include the brace tokens at either end of the structure.

Returns a list of zero or more the PPI::Element manpage objects.

Alternatively, if called in the scalar context, the elements method returns a count of the number of elements.

first_element

The first_element method accesses the first element structurally within the PPI::Node object. As for the elements method, this does include the brace tokens for the PPI::Structure manpage objects.

Returns a the PPI::Element manpage object, or undef if for some reason the PPI::Node object does not contain any elements.

last_element

The last_element method accesses the last element structurally within the PPI::Node object. As for the elements method, this does include the brace tokens for the PPI::Structure manpage objects.

Returns a the PPI::Element manpage object, or undef if for some reason the PPI::Node object does not contain any elements.

children

The children method accesses all child elements lexically within the PPI::Node object. Note that in the case of the the PPI::Structure manpage classes, this does NOT include the brace tokens at either end of the structure.

Returns a list of zero of more the PPI::Element manpage objects.

Alternatively, if called in the scalar context, the children method returns a count of the number of lexical children.

schildren

The schildren method is really just a convenience, the significant-only variation of the normal children method.

In list context, returns a list of significant children. In scalar context, returns the number of significant children.

child $index

The child method accesses a child the PPI::Element manpage object by its position within the Node.

Returns a the PPI::Element manpage object, or undef if there is no child element at that node.

schild $index

The lexical structure of the Perl language ignores 'insignificant' items, such as whitespace and comments, while the PPI manpage treats these items as valid tokens so that it can reassemble the file at any time. Because of this, in many situations there is a need to find an Element within a Node by index, only counting lexically significant Elements.

The schild method returns a child Element by index, ignoring insignificant Elements. The index of a child Element is specified in the same way as for a normal array, with the first Element at index 0, and negative indexes used to identify a "from the end" position.

contains $Element

The contains method is used to determine if another the PPI::Element manpage object is logically "within" a PPI::Node. For the special case of the brace tokens at either side of a the PPI::Structure manpage object, they are generally considered "within" a the PPI::Structure manpage object, even if they are not actually in the elements for the the PPI::Structure manpage.

Returns true if the the PPI::Element manpage is within us, false if not, or undef on error.

find $class | \&wanted

The find method is used to search within a code tree for the PPI::Element manpage objects that meet a particular condition.

To specify the condition, the method can be provided with either a simple class name (full or shortened), or a CODE/function reference.

  # Find all single quotes in a Document (which is a Node)
  $Document->find('PPI::Quote::Single');

  # The same thing with a shortened class name
  $Document->find('Quote::Single');

  # Anything more elaborate, we so with the sub
  $Document->find( sub {
        # At the top level of the file...
        $_[1]->parent == $_[0]
        and (
                # ...find all comments and POD
                $_[1]->isa('PPI::Token::Pod')
                or
                $_[1]->isa('PPI::Token::Comment')
        )
  } );

The function will be passed two arguments, the top-level PPI::Node you are searching in and the current the PPI::Element manpage that the condition is testing.

The anonymous function should return one of three values. Returning true indicates a condition match, defined-false (0 or '') indicates no-match, and undef indicates no-match and no-descend.

In the last case, the tree walker will skip over anything below the undef-returning element and move on to the next element at the same level.

To halt the entire search and return undef immediately, a condition function should throw an exception (i.e. die).

Note that this same wanted logic is used for all methods documented to have a \&wanted parameter, as this one does.

The find method returns a reference to an array of the PPI::Element manpage objects that match the condition, false (but defined) if no Elements match the condition, or undef if you provide a bad condition, or an error occurs during the search process.

In the case of a bad condition, a warning will be emitted as well.

find_first $class | \&wanted

If the normal find method is like a grep, then find_first is equivalent to the the Scalar::Util manpage first function.

Given an element class or a wanted function, it will search depth-first through a tree until it finds something that matches the condition, returning the first Element that it encounters.

See the find method for details on the format of the search condition.

Returns the first the PPI::Element manpage object that matches the condition, false if nothing matches the condition, or undef if given an invalid condition, or an error occurs.

find_any $class | \&wanted

The find_any method is a short-circuiting true/false method that behaves like the normal find method, but returns true as soon as it finds any Elements that match the search condition.

See the find method for details on the format of the search condition.

Returns true if any Elements that match the condition can be found, false if not, or undef if given an invalid condition, or an error occurs.

remove_child $Element

If passed a the PPI::Element manpage object that is a direct child of the Node, the remove_element method will remove the Element intact, along with any of its children. As such, this method acts essentially as a 'cut' function.

prune $class | \&wanted

The prune method is used to strip the PPI::Element manpage objects out of a code tree. The argument is the same as for the find method, either a class name, or an anonymous subroutine which returns true/false. Any Element that matches the class|wanted will be deleted from the code tree, along with any of its children.

The prune method returns the number of Element objects that matched and were removed, non-recursively. This might also be zero, so avoid a simple true/false test on the return false of the prune method. It returns undef on error, which you probably should test for.

TO DO

- Move as much as possible to the PPI::XS manpage

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Normal - Normalize Perl Documents

  • METHODS
    • register $function => $layer, ...
    • new
  • layer
    • process
  • NOTES
    • Layer 1 - Insignificant Data Removal
    • Layer 2 - Significant Element Removal
    • Layer 3 - TO BE COMPLETED
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Normal - Normalize Perl Documents

DESCRIPTION

Perl Documents, as created by PPI, are typically filled with all sorts of mess such as whitespace and comments and other things that don't effect the actual meaning of the code.

In addition, because there is more than one way to do most things, and the syntax of Perl itself is quite flexible, there are many ways in which the "same" code can look quite different.

PPI::Normal attempts to resolve this by providing a variety of mechanisms and algorithms to "normalize" Perl Documents, and determine a sort of base form for them (although this base form will be a memory structure, and not something that can be turned back into Perl source code).

The process itself is quite complex, and so for convenience and extensibility it has been separated into a number of layers. At a later point, it will be possible to write Plugin classes to insert additional normalization steps into the various different layers.

In addition, you can choose to do the normalization only as deep as a particular layer, depending on aggressively you want the normalization process to be.

METHODS

register $function => $layer, ...

The register method is used by normalization method providers to tell the normalization engines which functions need to be run, and in which layer they apply.

Provide a set of key/value pairs, where the key is the full name of the function (in string form), and the value is the layer (see description of the layers above) in which it should be run.

Returns true if all functions are registered, or undef on error.

new

  my $level_1 = PPI::Normal->new();
  my $level_2 = PPI::Normal->new(2);

Creates a new normalization object, to which Document objects can be passed to be normalized.

Of course, what you probably REALLY want is just to call the PPI::Document manpage's normalize method.

Takes an optional single parameter of the normalisation layer to use, which at this time can be either "1" or "2".

Returns a new PPI::Normal object, or undef on error.

layer

The layer accessor returns the normalisation layer of the object.

process

The process method takes anything that can be converted to a the PPI::Document manpage (object, SCALAR ref, filename), loads it and applies the normalisation process to the document.

Returns a the PPI::Document::Normalized manpage object, or undef on error.

NOTES

The following normalisation layers are implemented. When writing plugins, you should register each transformation function with the appropriate layer.

Layer 1 - Insignificant Data Removal

The basic step common to all normalization, layer 1 scans through the Document and removes all whitespace, comments, POD, and anything else that returns false for its significant method.

It also checks each Element and removes known-useless sub-element metadata such as the Element's physical position in the file.

Layer 2 - Significant Element Removal

After the removal of the insignificant data, Layer 2 removed larger, more complex, and superficially "significant" elements, that can be removed for the purposes of normalisation.

Examples from this layer include pragmas, now-useless statement separators (since the PDOM tree is holding statement elements), and several other minor bits and pieces.

Layer 3 - TO BE COMPLETED

This version of the forward-port of the Perl::Compare functionality to the 0.900+ API of PPI only implements Layer 1 and 2 at this time.

TO DO

- Write the other 4-5 layers :)

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright (c) 2005 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Normal::Standard - Provides standard document normalization functions

  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Normal::Standard - Provides standard document normalization functions

DESCRIPTION

This module provides the default normalization methods for the PPI::Normal manpage.

There is no reason for you to need to load this yourself.

Move along, nothing to see here.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright (c) 2005 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement - The base class for Perl statements

  • INHERITANCE
  • DESCRIPTION
  • STATEMENT CLASSES
    • the PPI::Statement::Scheduled manpage
    • the PPI::Statement::Package manpage
    • the PPI::Statement::Include manpage
    • the PPI::Statement::Sub manpage
    • the PPI::Statement::Variable manpage
    • the PPI::Statement::Compound manpage
    • the PPI::Statement::Break manpage
    • the PPI::Statement::Data manpage
    • the PPI::Statement::End manpage
    • the PPI::Statement::Expression manpage
    • the PPI::Statement::Null manpage
    • the PPI::Statement::UnmatchedBrace manpage
    • the PPI::Statement::Unknown manpage
  • METHODS
    • label
    • stable
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement - The base class for Perl statements

INHERITANCE

  PPI::Statement
  isa PPI::Node
      isa PPI::Element

DESCRIPTION

PPI::Statement is the root class for all Perl statements. This includes (from the perlsyn manpage) "Declarations", "Simple Statements" and "Compound Statements".

The class PPI::Statement itself represents a "Simple Statement" as defined in the the perlsyn manpage manpage.

STATEMENT CLASSES

Please note that unless documented themselves, these classes are yet to be frozen/finalised. Names may change slightly or be added or removed.

the PPI::Statement::Scheduled manpage

This covers all "scheduled" blocks, chunks of code that are executed separately from the main body of the code, at a particular time. This includes all BEGIN, CHECK, INIT and END blocks.

the PPI::Statement::Package manpage

A package declaration, as defined in perlfunc.

the PPI::Statement::Include manpage

A statement that loads or unloads another module.

This includes 'use', 'no', and 'require' statements.

the PPI::Statement::Sub manpage

A named subroutine declaration, or forward declaration

the PPI::Statement::Variable manpage

A variable declaration statement. This could be either a straight declaration or also be an expression.

This includes all 'my', 'local' and 'out' statements.

the PPI::Statement::Compound manpage

This covers the whole family of 'compound' statements, as described in perlsyn.

This includes all statements starting with 'if', 'unless', 'for', 'foreach' and 'while'. Note that this does NOT include 'do', as it is treated differently.

All compound statements have implicit ends. That is, they do not end with a ';' statement terminator.

the PPI::Statement::Break manpage

A statement that breaks out of a structure.

This includes all of 'redo', 'next', 'last' and 'return' statements.

the PPI::Statement::Data manpage

A special statement which encompasses an entire __DATA__ block, including the initial '__DATA__' token itself and the entire contents.

the PPI::Statement::End manpage

A special statement which encompasses an entire __END__ block, including the initial '__END__' token itself and the entire contents, including any parsed PPI::Token::POD that may occur in it.

the PPI::Statement::Expression manpage

the PPI::Statement::Expression manpage is a little more speculative, and is intended to help represent the special rules relating to "expressions" such as in:

  # Several examples of expression statements

  # Boolean conditions
  if ( expression ) { ... }

  # Lists, such as for arguments
  Foo->bar( expression )

the PPI::Statement::Null manpage

A null statement is a special case for where we encounter two consecutive statement terminators. ( ;; )

The second terminator is given an entire statement of its own, but one that serves no purpose. Hence a 'null' statement.

Theoretically, assuming a correct parsing of a perl file, all null statements are superfluous and should be able to be removed without damage to the file.

But don't do that, in case PPI has parsed something wrong.

the PPI::Statement::UnmatchedBrace manpage

Because the PPI manpage is intended for use when parsing incorrect or incomplete code, the problem arises of what to do with a stray closing brace.

Rather than die, it is allocated its own "unmatched brace" statement, which really means "unmatched closing brace". An unmatched open brace at the end of a file would become a structure with no contents and no closing brace.

If the document loaded is intended to be correct and valid, finding a the PPI::Statement::UnmatchedBrace manpage in the PDOM is generally indicative of a misparse.

the PPI::Statement::Unknown manpage

This is used temporarily mid-parsing to hold statements for which the lexer cannot yet determine what class it should be, usually because there are insufficient clues, or it might be more than one thing.

You should never encounter these in a fully parsed PDOM tree.

METHODS

PPI::Statement itself has very few methods. Most of the time, you will be working with the more generic the PPI::Element manpage or the PPI::Node manpage methods, or one of the methods that are subclass-specific.

label

One factor common to most statements is their ability to be labeled.

The label method returns the label for a statement, if one has been defined, but without the trailing colon. Take the following example

  MYLABEL: while ( 1 .. 10 ) { last MYLABEL if $_ > 5 }

For the above statement, the label method would return 'MYLABEL'.

Returns false if the statement does not have a label.

stable

Much like the the PPI::Document manpage method of the same name, the ->stable method converts a statement to source and back again, to determine if a modified statement is still legal, and won't be interpreted in a different way.

Returns true if the statement is stable, false if not, or undef on error.

TO DO

- Complete, freeze and document the remaining classes

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Break - Statements which break out of normal statement flow

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Break - Statements which break out of normal statement flow

SYNOPSIS

  last;
  goto FOO;
  next if condition();
  return $foo;
  redo;

INHERITANCE

  PPI::Statement::Compound
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Statement::Break is intended to represent statements that break out of the normal statement flow control. This covers the basic types 'redo', 'goto', 'next', 'last' and 'return'.

METHODS

PPI::Statement::Break has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

However, it is expected to gain methods for identifying the line to break to, or the structure to break out of.

TO DO

- Add the methods to identify the break target

- Add some proper unit testing

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Compound - Describes all compound statements

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • type
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Compound - Describes all compound statements

SYNOPSIS

  # A compound if statement
  if ( foo ) {
      bar();
  } else {
      baz();
  }

  # A compound loop statement
  foreach ( @list ) {
      bar($_);
  }

INHERITANCE

  PPI::Statement::Compound
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Statement::Compound objects are used to describe all current forms of compound statements, as described in the perlsyn manpage.

This covers blocks using if, unless, for, foreach, while, and continue. Please note this does not cover "simple" statements with trailing conditions. Please note also that "do" is also not part of a compound statement.

  # This is NOT a compound statement
  my $foo = 1 if $condition;

  # This is also not a compound statement
  do { ... } until $condition;

METHODS

PPI::Statement::Compound has a number of methods in addition to the standard the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage methods.

type

The type method returns the fundamental type of the compound statement.

There are three basic compound statement types.

The 'if' type includes all variations of the if and unless statements, including any 'elsif' or 'else' parts of the compound statement.

The 'while' type describes the standard while statement, but again does not describes simple statements with a trailing while.

The 'for' type covers both of 'for' and 'foreach' statements.

All of the compounds are a variation on one of these three.

Returns the simple string 'if', 'for' or 'while', or undef if the type cannot be determined.

TO DO

- Write unit tests for this package

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Data - The __DATA__ section of a file

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Data - The __DATA__ section of a file

SYNOPSIS

  # Normal content

  __DATA__
  This: data
  is: part
  of: the
  PPI::Statement::Data: object

INHERITANCE

  PPI::Statement::Compound
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Statement::Data is a utility class designed to hold content in the __DATA__ section of a file. It provides a single statement to hold all of the data.

METHODS

PPI::Statement::Data has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

However, it is expected to gain methods for accessing the data directly, (as a filehandle for example) just as you would access the data in the Perl code itself.

TO DO

- Add the methods to read in the data

- Add some proper unit testing

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::End - Content after the __END__ of a module

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::End - Content after the __END__ of a module

SYNOPSIS

  # This is normal content

  __END__

  This is part of an PPI::Statement::End statement

  =pod

  This is not part of the ::End statement, it's POD

  =cut

  This is another PPI::Statement::End statement

INHERITANCE

  PPI::Statement::End
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Statement::End is a utility class designed to serve as a contained for all of the content after the __END__ tag in a file.

It doesn't cover the ENTIRE of the __END__ section, and can be interspersed with the PPI::Token::Pod manpage tokens.

METHODS

PPI::Statement::End has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Expression - A generic and non-specialised statement

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Expression - A generic and non-specialised statement

SYNOPSIS

  $foo = bar;
  ("Hello World!");
  do_this();

INHERITANCE

  PPI::Statement::Expression
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

A PPI::Statement::Expression is a normal statement that is evaluated, may or may not assign, may or may not have side effects, and has no special or redeeming features whatsoever.

It provides a default for all statements that don't fit into any other classes.

METHODS

PPI::Statement::Expression has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Include - Statements that include other code

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • type
    • module
    • pragma
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Include - Statements that include other code

SYNOPSIS

  # The following are all includes
  use 5.006;
  use strict;
  use My::Module;
  use constant FOO => 'Foo';
  require Foo::Bar;
  require "Foo/Bar.pm";
  require $foo if 1;
  no strict 'refs';

INHERITANCE

  PPI::Statement::Include
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

Despite its name, the PPI::Statement::Include class covers a number of different types of statement that cover all statements starting with use, no and require.

But basically, they cover three situations.

Firstly, a dependency on a particular version of perl (for which the version method returns true), a pragma (for which the pragma method returns true, or the loading (and unloading via no) of modules.

METHODS

PPI::Statement::Include has a number of methods in addition to the standard the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage methods.

type

The type method returns the general type of statement ('use', 'no' or 'require').

Returns the type as a string, or undef if the type cannot be detected.

module

The module method returns the module name specified in any include statement. This includes pragma names, because pragma are implemented as modules. (And lets face it, the definition of a pragma can be fuzzy at the best of times in any case)

This covers all of these...

  use strict;
  use My::Module;
  no strict;
  require My::Module;

...but does not cover any of these...

  use 5.006;
  require 5.005;
  require "explicit/file/name.pl";

Returns the module name as a string, or undef if the include does not specify a module name.

pragma

The pragma method checks for an include statement's use as a pragma, and returns it if so.

Or at least, it claims to. In practice it's a lot harder to say exactly what is or isn't a pragma, because the definition is fuzzy.

The intent of a pragma is to modify the way in which the parser works. This is done though the use of modules that do various types of internals magic.

For now, PPI assumes that any "module name" that is only a set of lowercase letters. This behaviour is expected to change, most likely to something that knows the specific names of the various "pragmas".

Returns the name of the pragma, or false ('') if the include is not a pragma.

The version method checks for an include statement that introduces a dependency on the version of perl the code is compatible with.

This covers two specific statements.

  use 5.006;
  require 5.006;

Currently the version is returned as a string, although in future the version may be returned as a numeric literal, or more likely as a the version manpage object. Returns false if the statement is not a version dependency.

TO DO

- Write specific unit tests for this package

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Null - A useless null statement

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Null - A useless null statement

SYNOPSIS

  my $foo = 1;

  ; # <-- Null statement

  my $bar = 1;

INHERITANCE

  PPI::Statement::Null
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Statement::Null is a utility class designed to handle situations where PPI encounters a naked statement separator.

Although strictly speaking, the semicolon is a statement separator and not a statement terminator, PPI considers a semicolon to be a statement terminator under most circumstances.

In any case, the null statement has no purpose, and can be safely deleted with no ill effect.

METHODS

PPI::Statement::Null has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Package - A package statement

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • namespace
    • file_scoped
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Package - A package statement

INHERITANCE

  PPI::Statement::Package
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

Most the PPI::Statement manpage subclasses are assigned based on the value of the first token or word found in the statement. When PPI encounters a statement starting with 'package', it converts it to a PPI::Statement::Package object.

When working with package statements, please remember that packages only exist within their scope, and proper support for scoping has yet to be completed in PPI.

However, if the immediate parent of the package statement is the top level the PPI::Document manpage object, then it can be considered to define everything found until the next top-level "file scoped" package statement.

A file may, however, contain nested temporary package, in which case you are mostly on your own :)

METHODS

PPI::Statement::Package has a number of methods in addition to the standard the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage methods.

namespace

Most package declarations are simple, and just look something like

  package Foo::Bar;

The namespace method returns the name of the declared package, in the above case 'Foo::Bar'. It returns this exactly as written and does not attempt to clean up or resolve things like ::Foo to main::Foo.

If the package statement is done any different way, it returns false.

file_scoped

Regardless of whether it is named or not, the file_scoped method will test to see if the package declaration is a top level "file scoped" statement or not, based on its location.

In general, returns true if it is a "file scoped" package declaration with an immediate parent of the top level Document, or false if not.

Note that if the PPI DOM tree does not have a PPI::Document object at as the root element, this will return false. Likewise, it will also return false if the root element is a the PPI::Document::Fragment manpage, as a fragment of a file does not represent a scope.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Scheduled - A scheduled code block

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • type
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Scheduled - A scheduled code block

INHERITANCE

  PPI::Statement::Scheduled
  isa PPI::Statement::Sub
      isa PPI::Statement
          isa PPI::Node
              isa PPI::Element

DESCRIPTION

A scheduled code block is one that is intended to be run at a specific time during the loading process.

There are four types of scheduled block:

  BEGIN {
        # Executes as soon as this block is fully defined
        ...
  }

  CHECK {
        # Executes after compile-phase in reverse order
        ...
  }

  INIT {
        # Executes just before run-time
        ...
  }

  END {
        # Executes as late as possible in reverse order
        ...
  }

Technically these scheduled blocks are actually subroutines, and in fact may have 'sub' in front of them.

METHODS

type

The type method returns the type of scheduled block, which should always be one of 'BEGIN', 'CHECK', 'INIT' or 'END'.

TO DO

- Write unit tests for this package

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Sub - Subroutine declaration

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • name
    • prototype
    • block
    • forward
    • reserved
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Sub - Subroutine declaration

INHERITANCE

  PPI::Statement::Sub
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

Except for the special BEGIN, CHECK, INIT, and END subroutines (which are part of the PPI::Statement::Scheduled manpage) all subroutine declarations are lexed as a PPI::Statement::Sub object.

Primarily, this means all of the various sub foo {} statements, but also forward declarations such as sub foo; or sub foo($);. It does not include anonymous subroutines, as these are merely part of a normal statement.

METHODS

PPI::Statement::Sub has a number of methods in addition to the standard the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage methods.

name

The name method returns the name of the subroutine being declared.

In some rare cases such as a naked sub at the end of the file, this may return false.

prototype

If it has one, the prototype method returns the subroutine's prototype. It is returned in the same format as prototype in the PPI::Token::Prototype manpage, cleaned and removed from its brackets.

Returns false if the subroutine does not define a prototype

block

With its name and implementation shared with the PPI::Statement::Scheduled manpage, the block method finds and returns the actual Structure object of the code block for this subroutine.

Returns false if this is a forward declaration, or otherwise does not have a code block.

forward

The forward method returns true if the subroutine declaration is a forward declaration.

That is, it returns false if the subroutine has a code block, or true if it does not.

reserved

The reserved method provides a convenience method for checking to see if this is a special reserved subroutine. It does not check against any particular list of reserved sub names, but just returns true if the name is all uppercase, as defined in the perlsub manpage.

Note that in the case of BEGIN, CHECK, INIT and END, these will be defined as the PPI::Statement::Scheduled manpage objects, not subroutines.

Returns true if it is a special reserved subroutine, or false if not.

TO DO

- Write unit tests for this package

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Unknown - An unknown or transient statement

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Unknown - An unknown or transient statement

INHERITANCE

  PPI::Statement::Unknown
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

The PPI::Statement::Unknown class is used primarily during the lexing process to hold elements that are known to be statement, but for which the exact type of statement is as yet unknown, and requires further tokens in order to resolve the correct type.

They should not exist in a fully parse valid document, and if any exists they indicate either a problem in Document, or possibly (by allowing it to get through unresolved) a bug in the PPI::Lexer manpage.

METHODS

PPI::Statement::Unknown has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::UnmatchedBrace - Isolated unmatched brace

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::UnmatchedBrace - Isolated unmatched brace

SYNOPSIS

  sub foo {
      1;
  }

  } # <--- This is an unmatched brace

INHERITANCE

  PPI::Statement::UnmatchedBrace
  isa PPI::Statement
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

The PPI::Statement::UnmatchedBrace class is a miscellaneous utility class. Objects of this type should be rare, or not exist at all in normal valid the PPI::Document manpage objects.

It can be either a round ')', square ']' or curly '}' brace, this class does not distinguish. Objects of this type are only allocated at a structural level, not a lexical level (as they are lexically invalid anyway).

The presence of a PPI::Statement::UnmatchedBrace indicated a broken or invalid document. Or maybe a bug in PPI, but far more likely a broken Document. :)

METHODS

PPI::Statement::UnmatchedBrace has no additional methods beyond the default ones provided by the PPI::Statement manpage, the PPI::Node manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Statement::Variable - Variable declaration statements

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • type
    • variables
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Statement::Variable - Variable declaration statements

SYNOPSIS

  # All of the following are variable declarations
  my $foo = 1;
  my ($foo, $bar) = (1, 2);
  our $foo = 1;
  local $foo;
  local $foo = 1;
  LABEL: my $foo = 1;

INHERITANCE

  PPI::Statement::Variable
  isa PPI::Statement::Expression
      isa PPI::Statement
          isa PPI::Node
              isa PPI::Element

DESCRIPTION

The main intent of the PPI::Statement::Variable class is to describe simple statements that explicitly declare new local or global variables.

Note that this does not make it exclusively the only place where variables are defined, and later on you should expect that the variables method will migrate deeper down the tree to either the PPI::Statement manpage or the PPI::Node manpage to recognise this fact, but for now it stays here.

METHODS

type

The type method checks and returns the declaration type of the statement, which will be one of either 'my', 'local' or 'our'.

Returns a string of the type, or undef if the type cannot be detected (which is probably a bug).

variables

As for several other PDOM Element types that can declare variables, the variables method returns a list of the canonical forms of the variables defined by the statement.

Returns a list of the canonical string forms of variables, or the null list if it is unable to find any variables.

TO DO

- Write unit tests for this

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure - The base class for Perl braced structures

  • INHERITANCE
  • DESCRIPTION
    • Elements vs Children
  • STRUCTURE CLASSES
    • the PPI::Structure::List manpage
    • the PPI::Structure::ForLoop manpage
    • the PPI::Structure::Condition manpage
    • the PPI::Structure::Block manpage
    • the PPI::Structure::Constructor manpage
    • the PPI::Structure::Subscript manpage
  • METHODS
    • start
    • finish
    • braces
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure - The base class for Perl braced structures

INHERITANCE

  PPI::Structure
  isa PPI::Node
      isa PPI::Element

DESCRIPTION

PPI::Structure is the root class for all Perl bracing structures. This covers all forms of [ ... ] , { ... } , and ( ... ) brace types, and includes cases where only one half of the pair exist.

The class PPI::Structure itself is full abstract and no objects of that type should actually exist in the tree.

Elements vs Children

A PPI::Structure has an unusual existance. Unlike a the PPI::Document manpage or the PPI::Statement manpage, which both simply contain other elements, a structure both contains and consists of content.

That is, the brace tokens are not considered to be "children" of the structure, but are part of it.

In practice, this will mean that while the ->elements and ->tokens methods (and related) will return a list with the brace tokens at either end, the ->children method explicitly will not return the brace.

STRUCTURE CLASSES

Excluding the transient the PPI::Structure::Unknown manpage that exists briefly inside the parser, there are six types of structure.

the PPI::Structure::List manpage

This covers all round braces used for function arguments, in foreach loops, literal lists, and braces used for precedence-ordering purposes.

the PPI::Structure::ForLoop manpage

Although not used for the foreach loop list, this is used for the special case of the round-brace three-part semicolon-seperated for loop expression (the traditional C style for loop).

the PPI::Structure::Condition manpage

This round-brace structure covers boolean conditional braces, such as for if and while blocks.

the PPI::Structure::Block manpage

This curly-brace and common structure is used for all form of code blocks. This includes those for if, do and similar, as well as grep, map, sort, sub and (labelled or anonymous) scoping blocks.

the PPI::Structure::Constructor manpage

This class covers brace structures used for the construction of anonymous ARRAY and HASH references.

the PPI::Structure::Subscript manpage

This class covers square-braces and curly-braces used after a -> pointer to access the subscript of an ARRAY or HASH.

METHODS

PPI::Structure itself has very few methods. Most of the time, you will be working with the more generic the PPI::Element manpage or the PPI::Node manpage methods, or one of the methods that are subclass-specific.

start

For lack of better terminology (like "open" and "close") that has not already in use for some other more important purpose, the two individual braces for the structure are known within PPI as the "start" and "finish" braces (at least for method purposes).

The start method returns the start brace for the structure (i.e. the opening brace).

Returns the brace as a the PPI::Token::Structure manpage or undef if the structure does not have a starting brace.

Under normal parsing circumstances this should never occur, but may happen due to manipulation of the PDOM tree.

finish

The finish method returns the finish brace for the structure (i.e. the closing brace).

Returns the brace as a the PPI::Token::Structure manpage or undef if the structure does not have a starting brace. This can be quite common if the document is not complete (for example, from an editor where the user may be halfway through typeing a subroutine).

braces

The braces method is a utility method which returns the brace type.

Returns on of the three strings '[]', '{}', or '()', or undef on error (primarily not having a start brace, as mentioned above).

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::Block - Curly braces representing a code block

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::Block - Curly braces representing a code block

SYNOPSIS

  sub foo { ... }

  grep { ... } @list;

  if ( condition ) {
      ...
  }

  LABEL: {
      ...
  }

INHERITANCE

  PPI::Structure::Block
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::Block is the class used for all curly braces that represent code blocks. This includes subroutines, compound statements and any other block braces.

METHODS

PPI::Structure::Block has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::Condition - Round braces for boolean context conditions

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::Condition - Round braces for boolean context conditions

SYNOPSIS

  if ( condition ) {
      ...
  }

  while ( condition ) {
      ...
  }

INHERITANCE

  PPI::Structure::Condition
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::Condition is the class used for all round braces that represent boolean contexts used in various conditions.

METHODS

PPI::Structure::Condition has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::Constructor - Anonymous hash or array constructor

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::Constructor - Anonymous hash or array constructor

SYNOPSIS

  my $array = [ 'foo', 'bar' ];
  my $hash  = { foo => 'bar' };

INHERITANCE

  PPI::Structure::Constructor
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::Constructor is the class used for anonymous ARRAY reference of HASH reference constructors.

METHODS

PPI::Structure::Constructor has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::ForLoop - Circular braces for a for expression

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::ForLoop - Circular braces for a for expression

SYNOPSIS

  for ( var $i = 0; $i < $max; $i++ ) {
      ...
  }

INHERITANCE

  PPI::Structure::ForLoop
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::ForLoop is the class used for circular braces that contain the three part for expression.

METHODS

PPI::Structure::ForLoop has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::List - Explicit list or precedence ordering braces

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::List - Explicit list or precedence ordering braces

SYNOPSIS

  # A list used for params
  function( 'param', 'param' );

  # Explicit list
  return ( 'foo', 'bar' );

INHERITANCE

  PPI::Structure::List
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::List is the class used for circular braces that represent lists, and related.

METHODS

PPI::Structure::List has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::Subscript - Braces that represent an array or hash subscript

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::Subscript - Braces that represent an array or hash subscript

SYNOPSIS

  # The end braces for all of the following are subscripts
  $foo->[...]
  $foo[...]
  $foo{...}[...]
  $foo->{...}
  $foo{...}
  $foo[]{...}

INHERITANCE

  PPI::Structure::Subscript
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::Subscript is the class used for square and curly braces that specify one element of an array or hash (or a slice/subset of an array or hash)

METHODS

PPI::Structure::Subscript has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Structure::Unknown - An unknown or unresolved brace structure

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Structure::Unknown - An unknown or unresolved brace structure

INHERITANCE

  PPI::Structure::Unknown
  isa PPI::Structure
      isa PPI::Node
          isa PPI::Element

DESCRIPTION

PPI::Structure::Unknown is class for braces whose type is unknown, or temporarily unknown.

It primarily exists temporarily inside the lexer. Although some types of braces can be determined immediately at opening, there are a number of different brace types that can only be correctly identified after the braces are closed.

A structure is typed as unknown during this period it is indeterminate.

A PPI::Structure::Unknown object should not ever make it out of the lexer without being converted to it's final type. Any time you encounter this class in a PDOM tree it should be considered a bug and reported accordingly.

METHODS

PPI::Structure::Unknown has no methods beyond those provided by the standard the PPI::Structure manpage, the PPI::Node manpage and the PPI::Element manpage methods.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token - A single token of Perl source code

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • set_content $string
    • add_content $string
    • length

NAME

PPI::Token - A single token of Perl source code

INHERITANCE

  PPI::Token
  isa PPI::Element

DESCRIPTION

PPI::Token is the abstract base class for all Tokens. In PPI terms, a "Token" is a the PPI::Element manpage that directly represents bytes of source code.

METHODS

set_content $string

The set_content method allows to set/change the string that the PPI::Token object represents.

Returns the string you set the Token to

add_content $string

The add_content method allows you to add additional bytes of code to the end of the Token.

Returns the new full string after the bytes have been added.

length

The length method returns the length of the string in a Token.


PPI::Token::ArrayIndex - Token getting the last index for an array

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::ArrayIndex - Token getting the last index for an array

INHERITANCE

  PPI::Token::ArrayIndex
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::ArrayIndex token represents an attempt to get the last index of an array, such as $#array.

METHODS

There are no additional methods beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Attribute - A token for a subroutine attribute

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • identifier
    • parameters
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Attribute - A token for a subroutine attribute

INHERITANCE

  PPI::Token::Attribute
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

In Perl, attributes are a relatively recent addition to the language.

Given the code sub foo : bar(something) {} , the bar(something) part is the attribute.

A PPI::Token::Attribute token represents the entire of the attribute, as the braces and its contents are not parsed into the tree, and are treated by Perl (and thus by us) as a single string.

METHODS

This class provides some additional methods beyond those provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

identifier

The identifier attribute returns the identifier part of the attribute.

That is, for the attribute foo(bar), the identifier method would return "foo".

parameters

The parameters method returns the parameter strong for the attribute.

That is, for the attribute foo(bar), the parameters method would return "bar".

Returns the parameters as a string (including the null string '' for the case of an attribute such as foo().

Returns undef if the attribute does not have parameters.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Cast - A prefix which forces a value into a different context

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Cast - A prefix which forces a value into a different context

INHERITANCE

  PPI::Token::Cast
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

A "cast" in PPI terms is one of more characters used as a prefix which force a value into a different class or context.

This includes referencing, dereferencing, and a few other minor cases.

For expressions such as @$foo or @{ $foo{bar} } the @ in both cases represents a cast. In this case, an array dereference.

METHODS

There are no additional methods beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Comment - A comment in Perl source code

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
    • line
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Comment - A comment in Perl source code

INHERITANCE

  PPI::Token::Comment
  isa PPI::Token
      isa PPI::Element

SYNOPSIS

  # This is a PPI::Token::Comment

  print "Hello World!"; # So it this

  $string =~ s/ foo  # This, unfortunately, is not :(
        bar
        /w;

DESCRIPTION

In PPI, comments are represented by PPI::Token::Comment objects.

These come in two flavours, line comment and inline comments.

A line comment is a comment that stands on its own line. These comments hold their own newline and whitespace (both leading and trailing) as part of the one PPI::Token::Comment object.

An inline comment is a comment that appears after some code, and continues to the end of the line. This does not include whitespace, and the terminating newlines is considered a separate the PPI::Token::Whitespace manpage token.

This is largely a convenience, simplifying a lot of normal code relating to the common things people do with comments.

Most commonly, it means when you prune or delete a comment, a line comment disappears taking the entire line with it, and an inline comment is removed from the inside of the line, allowing the newline to drop back onto the end of the code, as you would expect.

It also means you can move comments around in blocks much more easily.

For now, this is a suitably handy way to do things. However, I do reserve the right to change my mind on this one if it gets dangerously anachronistic somewhere down the line.

METHODS

Only very limited methods are available, beyond those provided by our parent the PPI::Token manpage and the PPI::Element manpage classes.

line

The line accessor returns true if the PPI::Token::Comment is a line comment, or false if it is an inline comment.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::DashedWord - A dashed bareword token

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::DashedWord - A dashed bareword token

INHERITANCE

  PPI::Token::DashedWord
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The "dashed bareword" token represents literal values like -foo.

METHODS

There are no additional methods beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Data - The actual data in the __DATA__ section of a file

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • handle
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Data - The actual data in the __DATA__ section of a file

INHERITANCE

  PPI::Token::Data
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Data class is used to represent the actual data inside a file's __DATA__ section.

One PPI::Token::Data object is used to represent the entire of the data, primarily so that it can provide a convenient handle directly to the data.

METHODS

PPI::Token::Data provides one method in addition to those provided by our parent the PPI::Token manpage and the PPI::Element manpage classes.

handle

The handle method returns a the IO::String manpage handle that allows you to do all the normal handle-y things to the contents of the __DATA__ section of the file.

Unlike in perl itself, this means you can also do things like print new data onto the end of the __DATA__ section, or modify it with any other process that can accept an the IO::Handle manpage as input or output.

Returns an the IO::String manpage object.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::End - Completely useless content after the __END__ tag

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::End - Completely useless content after the __END__ tag

INHERITANCE

  PPI::Token::End
  isa PPI::Token
          isa PPI::Element

DESCRIPTION

If you've read the PPI::Token::Whitespace manpage, you should understand by now the concept of documents "floating in a sea of PPI::Token::Whitespace".

Well it doesn't after the __END__ tag.

Once you __END__, it's all over. Anything after that tag isn't even fit to be called whitespace. It just simply doesn't exist as far as perl (the interpreter) is concerned.

That's not to say there isn't useful content. Most often people use the __END__ tag to hide POD content, so that perl never has to see it, and presumably providing some small speed up.

That's fine. PPI likes POD. Any POD after the __END__ tag is parsed into valid the PPI::Token::Pod manpage tags as normal. This class, on the other hand, is for "what's after __END__ when it isn't POD".

Basically, the completely worthless bits of the file :)

METHODS

This class has no method beyond what is provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::HereDoc - Token class for the here-doc

  • INHERITANCE
  • DESCRIPTION
    • Comparison to other string types
  • METHODS
    • heredoc
    • terminator
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::HereDoc - Token class for the here-doc

INHERITANCE

  PPI::Token::HereDoc
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

Here-docs are incredibly handy when writing Perl, but incredibly tricky when parsing it, primarily because they don't follow the general flow of input.

They jump ahead and nab lines directly off the input buffer. Whitespace and newlines may not matter in most Perl code, but they matter in here-docs.

They are also tricky to store as an object. They look sort of like an operator and a string, but they don't act like it. And they have a second section that should be something like a separate token, but isn't because a strong can span from above the here-doc content to below it.

So when parsing, this is what we do.

Firstly, the PPI::Token::HereDoc object, does not represent the << operator, or the "END_FLAG", or the content, or even the terminator.

It represents all of them at once.

The token itself has only the declaration part as its "content".

  # This is what the content of a HereDoc token is
  <<FOO

  # Or this
  <<"FOO"

  # Or even this
  <<      'FOO'

That is, the "operator", any whitespace separator, and the quoted or bare terminator. So when you call the content method on a HereDoc token, you get '<< "FOO"'.

As for the content and the terminator, when treated purely in "content" terms they do not exist.

The content is made available with the heredoc method, and the name of the terminator with the terminator method.

To make things work in the way you expect, PPI has to play some games when doing line/column location calculation for tokens, and also during the content parsing and generation processes.

Documents cannot simply by recreated by stitching together the token contents, and involve a somewhat more expensive procedure, but the extra expense should be relatively negligible unless you are doing huge quantities of them.

Please note that due to the immature nature of PPI in general, we expect HereDocs to be a rich (bad) source of corner-case bugs for quite a while, but for the most part they should more or less DWYM.

Comparison to other string types

Although technically it can be considered a quote, for the time being HereDocs are being treated as a completely separate Token subclass, and will not be found in a search for the PPI::Token::Quote manpage or PPI::Token::QuoteLike objects.

This may change in the future, with it most likely to end up under QuoteLike.

METHODS

Although it has the standard set of Token methods, HereDoc objects have a relatively large number of unique methods all of their own.

heredoc

The heredoc method is the authoritative method for accessing the contents of the HereDoc object.

It returns the contents of the here-doc as a list of newline-terminated strings. If called in scalar context, it returns the number of lines in the here-doc, excluding the terminator line.

terminator

The terminator method returns the name of the terminating string for the here-doc.

Returns the terminating string as an unescaped string (in the rare case the terminator has an escaped quote in it).

TO DO

- Implement PPI::Token::Quote interface compatibility

- Check CPAN for any use of the null here-doc or here-doc-in-s///e

- Add support for the null here-doc

- Add support for here-doc in s///e

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Label - Token class for a statement label

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Label - Token class for a statement label

INHERITANCE

  PPI::Token::Label
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

A label is an identifier attached to a line or statements, to allow for various types of flow control. For example, a loop might have a label attached so that a last or next flow control statement can be used from multiple levels below to reference the loop directly.

METHODS

There are no additional methods beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Magic - Tokens representing magic variables

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Magic - Tokens representing magic variables

INHERITANCE

  PPI::Token::Magic
  isa PPI::Token::Symbol
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  # When we say magic variables, we mean these...
  $1   $2   $3   $4   $5   $6   $7   $8   $9
  $_   $&   $`   $'   $+   @+   $*   $.   $/    $|
  $\\  $"   $;   $%   $=   $-   @-   $)   $#
  $~   $^   $:   $?   $!   %!   $@   $$   $<    $>
  $(   $0   $[   $]   @_   @*   $}   $,   $#+   $#-
  $^L  $^A  $^E  $^C  $^D  $^F  $^H
  $^I  $^M  $^N  $^O  $^P  $^R  $^S
  $^T  $^V  $^W  $^X

DESCRIPTION

PPI::Token::Magic is a sub-class of the PPI::Token::Symbol manpage which identifies the token as "magic variable", one of the strange and unusual variables that are connected to "things" behind the scenes.

Some are extremely common, like $_, and others you will quite probably never encounter in your Perl career.

METHODS

The class provides no additional methods, beyond those provided by it's the PPI::Token::Symbol manpage, the PPI::Token manpage and the PPI::Element manpage.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Number - Token class for a number

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • base
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Number - Token class for a number

SYNOPSIS

  $n = 1234;       # decimal integer
  $n = 0b1110011;  # binary integer
  $n = 01234;      # octal integer
  $n = 0x1234;     # hexadecimal integer
  $n = 12.34e-56;  # exponential notation ( currently not working )

INHERITANCE

  PPI::Token::Number
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Number class is used for tokens that represent numbers, in the various types that Perl supports.

METHODS

base

Returns the base for the number. This is 10 for decimal, 16 for hexadecimal, etc.

TO DO

- Add proper unit testing to this

- Add support for exponential notation

- What the hell is a base256 number and why did I use it. Surely it should be something more like "base1000" or "version".

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Operator - Token class for operators

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Operator - Token class for operators

INHERITANCE

  PPI::Token::Operator
  isa PPI::Token::Symbol
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  # This is the list of valid operators
  ++   --   **   !    ~    +    -
  =~   !~   *    /    %    x
  <<   >>   lt   gt   le   ge   cmp
  ==   !=   <=>  .    ..   ...  ,
  &    |    ^    &&   ||   //
  ?    :    =    +=   -=   *=   .=   //=
  <    >    <=   >=   <>   =>   ->
  and  or   dor  not  eq   ne

DESCRIPTION

All operators in PPI are created as PPI::Token::Operator objects, including the ones that may superficially look like a the PPI::Token::Word manpage object.

METHODS

There are no additional methods beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Pod - Sections of POD in Perl documents

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • merge @podtokens
    • lines
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Pod - Sections of POD in Perl documents

INHERITANCE

  PPI::Token::Pod
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

A single PPI::Token::Pod object represents a complete section of POD documentation within a Perl document.

METHODS

This class provides some additional methods beyond those provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

Got any ideas for more methods? Submit a report to rt.cpan.org!

merge @podtokens

The merge constructor takes a number of PPI::Token::Pod objects, and returns a new object that represents one combined POD block with the content of all of them.

Returns a new PPI::Token::Pod object, or undef on error.

lines

The lines method takes the string of POD and breaks it into lines, returning them as a list.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Prototype - A subroutine prototype descriptor

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
    • prototype
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Prototype - A subroutine prototype descriptor

INHERITANCE

  PPI::Token::End
  isa PPI::Token
      isa PPI::Element

SYNOPSIS

  sub ($@) prototype;

DESCRIPTION

Although it sort of looks like a list or condition, a subroutine prototype is a lot more like a string. Its job is to provide hints to the perl compiler on what type of arguments a particular subroutine expects, which the compiler uses to validate parameters at compile-time, and allows programmers to use the functions without explicit parameter braces.

Due to the rise of OO Perl coding, which ignores these prototypes, they are most often used to allow for constant-like things, and to "extend" the language and create things that act like keywords and core functions.

  # Create something that acts like a constant
  sub MYCONSTANT () { 10 }

  # Create the "any" core-looking function
  sub any (&@) { ... }

  if ( any { $_->sexy } @chicks ) {
        ...
  }

METHODS

This class provides one additional method beyond those defined by the the PPI::Token manpage and the PPI::Element manpage parent classes.

prototype

The prototype accessor returns the actual prototype pattern, stripped of braces and any whitespace inside the pattern.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Quote - String quote abstract base class

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • string
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Quote - String quote abstract base class

INHERITANCE

  PPI::Token::Quote
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Quote class is never instantiated, and simply provides a common abstract base class for the four quote classes. In PPI, a "quote" is limited to only the quote-like things that themselves directly represent a string. (although this includes double quotes with interpolated elements inside them).

The subclasses of PPI::Token::Quote are:

'' - the PPI::Token::Quote::Single manpage
q{} - the PPI::Token::Quote::Literal manpage
"" - the PPI::Token::Quote::Double manpage
qq{} - the PPI::Token::Quote::Interpolate manpage

The names are hopefully obvious enough not to have to explain what each class is here. See their respective pages for more details.

Please note that although the here-doc does represent a literal string, it is such a nasty piece of work that in the PPI manpage it is given the honor of its own token class (the PPI::Token::HereDoc manpage).

METHODS

string

The string method is provided by all four ::Quote classes. It won't get you the actual literal Perl value, but it will strip off the wrapping of the quotes.

  # The following all return foo from the ->string method
  'foo'
  "foo"
  q{foo}
  qq <foo>

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Quote::Double - A standard "double quote" token

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • interpolations
    • simplify
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Quote::Double - A standard "double quote" token

INHERITANCE

  PPI::Token::Quote::Double
  isa PPI::Token::Quote
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

A PPI::Token::Quote::Double object represents a double-quoted interpolating string.

The string is treated as a single entity, the PPI manpage will not try to understand what is in the string during the parsing process.

METHODS

There are several methods available for PPI::Token::Quote::Double, beyond those provided by the parent the PPI::Token::Quote manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

interpolations

The interpolations method checks to see if the double quote actually contains any interpolated variables.

Returns true if the string contains interpolations, or false if not.

simplify

For various reasons, some people find themselves compelled to have their code in the simplest form possible.

The simply method will turn a simple double-quoted string into the equivalent single-quoted string.

If the double can be simplified, it will be modified in place and returned as a convenience, or returns false if the string cannot be simplified.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Quote::Interpolate - The interpolation quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Quote::Interpolate - The interpolation quote-like operator

INHERITANCE

  PPI::Token::Quote::Interpolate
  isa PPI::Token::Quote
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

A PPI::Token::Quote::Interpolate object represents a single interpolation quote-like operator, such as qq{$foo bar $baz}.

METHODS

There are no methods available for PPI::Token::Quote::Interpolate beyond those provided by the parent the PPI::Token::Quote manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Quote::Literal - The literal quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Quote::Literal - The literal quote-like operator

INHERITANCE

  PPI::Token::Quote::Literal
  isa PPI::Token::Quote
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

A PPI::Token::Quote::Literal object represents a single literal quote-like operator, such as q{foo bar}.

METHODS

There are no methods available for PPI::Token::Quote::Literal beyond those provided by the parent the PPI::Token::Quote manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Quote::Single - A 'single quote' token

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Quote::Single - A 'single quote' token

INHERITANCE

  PPI::Token::Quote::Single
  isa PPI::Token::Quote
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  'This is a single quote'

  q{This is a literal, but NOT a single quote}

DESCRIPTION

A PPI::Token::Quote::Single object represents a single quoted string literal.

METHODS

There are no methods available for PPI::Token::Quote::Single beyond those provided by the parent the PPI::Token::Quote manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike - Quote-like operator abstract base class

  • INHERITANCE
  • DESCRIPTION
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike - Quote-like operator abstract base class

INHERITANCE

  PPI::Token::QuoteLike
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::QuoteLike class is never instantiated, and simply provides a common abstract base class for the five quote-like operator classes. In PPI, a "quote-like" is the set of quote-like things that exclude the string quotes and regular expressions.

The subclasses of PPI::Token::QuoteLike are:

qw{} - the PPI::Token::QuoteLike::Words manpage
`` - the PPI::Token::QuoteLike::Backtick manpage
qx{} - the PPI::Token::QuoteLike::Command manpage
qr// - the PPI::Token::QuoteLike::Regexp manpage
<FOO> - the PPI::Token::QuoteLike::Readline manpage

The names are hopefully obvious enough not to have to explain what each class is. See their pages for more details.

You may note that the backtick and command quote-like are treated separately, even though they do the same thing. This is intentional, as the inherit from and are processed by two different parts of the PPI's quote engine.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike::Backtick - A `backticks` command token

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike::Backtick - A `backticks` command token

INHERITANCE

  PPI::Token::QuoteLike::Backtick
  isa PPI::Token::QuoteLike
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

A PPI::Token::QuoteLike::Backtick object represents a command output capturing quote.

METHODS

There are no methods available for PPI::Token::QuoteLike::Backtick beyond those provided by the parent the PPI::Token::QuoteLike manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike::Command - The command quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike::Command - The command quote-like operator

INHERITANCE

  PPI::Token::QuoteLike::Command
  isa PPI::Token::QuoteLike
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

A PPI::Token::QuoteLike::Command object represents a command output capturing quote-like operator.

METHODS

There are no methods available for PPI::Token::QuoteLike::Command beyond those provided by the parent the PPI::Token::QuoteLike manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike::Readline - The readline quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike::Readline - The readline quote-like operator

INHERITANCE

  PPI::Token::QuoteLike::Readline
  isa PPI::Token::QuoteLike
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

The readline quote-like operator is used to read either a single line from a file, or all the lines from a file, as follows.

  # Read in a single line
  $line = <FILE>;

  # From a scalar handle
  $line = <$filehandle>;

  # Read all the lines
  @lines = <FILE>;

METHODS

There are no methods available for PPI::Token::QuoteLike::Readline beyond those provided by the parent the PPI::Token::QuoteLike manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike::Regexp - Regexp constructor quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike::Regexp - Regexp constructor quote-like operator

INHERITANCE

PPI::Token::QuoteLike::Regexp
isa PPI::Token::QuoteLike
    isa PPI::Token
        isa PPI::Element

DESCRIPTION

A PPI::Token::QuoteLike::Regexp object represents the quote-like operator used to construct anonymous the Regexp manpage objects, as follows.

  # Create a Regexp object for a module filename
  my $module = qr/\.pm$/;

METHODS

There are no methods available for PPI::Token::QuoteLike::Regexp beyond those provided by the parent the PPI::Token::QuoteLike manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::QuoteLike::Words - Word list constructor quote-like operator

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::QuoteLike::Words - Word list constructor quote-like operator

INHERITANCE

PPI::Token::QuoteLike::Words
isa PPI::Token::QuoteLike
    isa PPI::Token
        isa PPI::Element

DESCRIPTION

A PPI::Token::QuoteLike::Words object represents a quote-like operator that acts as a constructor for a list of words.

  # Create a list for a significant chunk of the alphabet
  my @list = qw{a b c d e f g h i j k l};

METHODS

There are no methods available for PPI::Token::QuoteLike::Words beyond those provided by the parent the PPI::Token::QuoteLike manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Regexp - Regular expression abstract base class

  • INHERITANCE
  • DESCRIPTION
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Regexp - Regular expression abstract base class

INHERITANCE

  PPI::Token::Regexp
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Regexp class is never instantiated, and simply provides a common abstract base class for the three regular expression classes. These being:

m// - the PPI::Token::Regexp::Match manpage
s/// - the PPI::Token::Regexp::Substitute manpage
tr/// - the PPI::Token::Regexp::Transliterate manpage

The names are hopefully obvious enough not to have to explain what each class is. See their pages for more details.

To save some confusion, it's worth pointing out here that qr// is not a regular expression (which PPI takes to mean something that will actually examine or modify a string), but rather a quote-like operator that acts as a constructor for compiled the Regexp manpage objects.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Regexp::Match - A standard pattern match regex

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Regexp::Match - A standard pattern match regex

INHERITANCE

  PPI::Token::Regexp::Match
  isa PPI::Token::Regexp
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  $text =~ m/match regexp/;
  $text =~ /match regexp/;

DESCRIPTION

A PPI::Token::Regexp::Match object represents a single match regular expression. Just to be doubly clear, here are things that are and aren't considered a match regexp.

  # Is a match regexp
  /This is a match regexp/;
  m/Old McDonald had a farm/eieio;

  # These are NOT match regexp
  qr/This is a regexp quote-like operator/;
  s/This is a/replace regexp/;

METHODS

There are no methods available for PPI::Token::Regexp::Match beyond those provided by the parent the PPI::Token::Regexp manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Regexp::Substitute - A match and replace regular expression token

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Regexp::Substitute - A match and replace regular expression token

INHERITANCE

  PPI::Token::Regexp::Substitute
  isa PPI::Token::Regexp
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  $text =~ s/find/$replace/;

DESCRIPTION

A PPI::Token::Regexp::Substitute object represents a single substitution regular expression.

METHODS

There are no methods available for PPI::Token::Regexp::Substitute beyond those provided by the parent the PPI::Token::Regexp manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Regexp::Transliterate - A transliteration regular expression token

  • INHERITANCE
  • SYNOPSIS
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Regexp::Transliterate - A transliteration regular expression token

INHERITANCE

  PPI::Token::Regexp::Transliterate
  isa PPI::Token::Regexp
      isa PPI::Token
          isa PPI::Element

SYNOPSIS

  $text =~ tr/abc/xyz/;

DESCRIPTION

A PPI::Token::Regexp::Transliterate object represents a single transliteration regular expression.

I'm afraid you'll have to excuse the ridiculously long class name, but when push came to shove I ended up going for pedantically correct names for things (practically cut and paste from the various docs).

METHODS

There are no methods available for PPI::Token::Regexp::Transliterate beyond those provided by the parent the PPI::Token::Regexp manpage, the PPI::Token manpage and the PPI::Element manpage classes.

Got any ideas for methods? Submit a report to rt.cpan.org!

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Separator - The __DATA__ and __END__ tags

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Separator - The __DATA__ and __END__ tags

INHERITANCE

  PPI::Token::Separator
  isa PPI::Token::Word
      isa PPI::Token
          isa PPI::Element

DESCRIPTION

Although superficially looking like a normal the PPI::Token::Word manpage object, when the __DATA__ and __END__ compiler tags appear at the beginning of a line (on supposedly) their own line, these tags become file section separators.

The indicate that the time for Perl code is over, and the rest of the file is dedicated to something else (data in the case of __DATA__) or to nothing at all (in the case of __END__).

METHODS

This class has no methods beyond what is provided by its the PPI::Token::Word manpage, the PPI::Token manpage and the PPI::Element manpage parent classes.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Structure - Token class for characters that define code structure

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Structure - Token class for characters that define code structure

INHERITANCE

  PPI::Token::Structure
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Structure class is used for tokens that control the generally tree structure or code.

This consists of seven characters. These are the six brace characters from the "round", "curly" and "square" pairs, plus the semi-colon statement separator ;.

METHODS

This class has no methods beyond what is provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Symbol - A token class for variables and other symbols

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • canonical
    • symbol
    • raw_type
    • symbol_type
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Symbol - A token class for variables and other symbols

INHERITANCE

  PPI::Token::Symbol
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

The PPI::Token::Symbol class is used to cover all tokens that represent variables and other things that start with a sigil.

METHODS

This class has several methods beyond what is provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

Most methods are provided to help work out what the object is actually pointing at, rather than what it might appear to be pointing at.

canonical

The canonical method returns a normalized, canonical version of the symbol.

For example, it converts $ ::foo'bar::baz to $main::foo::bar::baz.

This does not fully resolve the symbol, but merely removes syntax variations.

symbol

The symbol method returns the ACTUAL symbol this token refers to.

A token of $foo might actually be referring to @foo, if it is found in the form $foo[1].

This method attempts to resolve these issues to determine the actual symbol.

Returns the symbol as a string.

raw_type

The raw_type method returns the apparent type of the symbol in the form of its sigil.

Returns the sigil as a string.

symbol_type

The symbol_type method returns the actual type of the symbol in the form of its sigil.

Returns the sigil as a string.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Unknown - Token of unknown or as-yet undetermined type

  • INHERITANCE
  • DESCRIPTION
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Unknown - Token of unknown or as-yet undetermined type

INHERITANCE

  PPI::Token::Unknown
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

Object of the type PPI::Token::Unknown exist primarily inside the tokenizer, where they are temporarily brought into existing for a very short time to represent a token that could be one of a number of types.

Generally, they only exist for a character or two, after which they are resolved and converted into the correct type. For an object of this type to survive the parsing process is considered a major bug.

Please report any PPI::Token::Unknown you encounter in a the PPI::Document manpage object as a bug.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Whitespace - Tokens representing ordinary white space

  • INHERITANCE
  • DESCRIPTION
  • METHODS
    • null
    • tidy
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Whitespace - Tokens representing ordinary white space

INHERITANCE

  PPI::Token::Whitespace
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

As a full "round-trip" parser, PPI records every last byte in a file and ensure that it is included in the the PPI::Document manpage object.

This even includes whitespace. In fact, Perl documents are seen as "floating in a sea of whitespace", and thus any document will contain vast quantities of PPI::Token::Whitespace objects.

For the most part, you shouldn't notice them. Or at least, you shouldn't have to notice them.

This means doing things like consistently using the "S for significant" series of the PPI::Node manpage and the PPI::Element manpage methods to do things.

If you want the nth child element, you should be using schild rather than child, and likewise snext_sibling, sprevious_sibling, and so on and so forth.

METHODS

Again, for the most part you should really not need to do anything very significant with whitespace.

But there are a couple of convenience methods provided, beyond those provided by the parent the PPI::Token manpage and the PPI::Element manpage classes.

null

Because PPI sees documents as sitting on a sort of substrate made of whitespace, there are a couple of corner cases that get particularly nasty if they don't find whitespace in certain places.

Imagine walking down the beach to go into the ocean, and then quite unexpectedly falling off the side of the planet. Well it's somewhat equivalent to that, including the whole screaming death bit.

The null method is a convenience provided to get some internals out of some of these corner cases.

Specifically it create a whitespace token that represents nothing, or at least the null string ''. It's a handy way to have some "whitespace" right where you need it, without having to have any actual characters.

tidy

tidy is a convenience method for removing unneeded whitespace.

Specifically, it removes any whitespace from the end of a line.

Note that this doesn't include POD, where you may well need to keep certain types of whitespace. The entire POD chunk lives in its own the PPI::Token::Pod manpage object.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::Word - The generic "word" Token

  • INHERITANCE
  • DESCRIPTION
  • METHODS
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::Word - The generic "word" Token

INHERITANCE

  PPI::Token::Word
  isa PPI::Token
      isa PPI::Element

DESCRIPTION

A PPI::Token::Word object is a PPI-specific representation of several different types of word-like things, and is one of the most common Token classes found in typical documents.

Specifically, it includes not only barewords, but also any other valid Perl identifier including non-operator keywords and core functions, and any include :: separators inside it, as long as it fits the format of a class, function, etc.

METHODS

There are no methods available for PPI::Token::Word beyond those provided by its the PPI::Token manpage and the PPI::Element manpage parent classes.

We expect to add additional methods to help further resolve a Word as a function, method, etc over time.

TO DO

- Add function, method etc detector methods

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Token::_QuoteEngine - The PPI Quote Engine

    • Using this class
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Token::_QuoteEngine - The PPI Quote Engine

DESCRIPTION

The PPI::Token::_QuoteEngine package is designed hold functionality for processing quotes and quote like operators, including regexes. These have special requirements in parsing.

The PPI::Token::_QuoteEngine package itself provides various parsing methods, which the the PPI::Token::Quote manpage, the PPI::Token::QuoteLike manpage and the PPI::Token::Regexp manpage can inherit from. In this sense, it serves as a base class.

Using this class

(Refers only to internal uses. This class does not provide a public interface)

To use these, you should initialize them as normal '$Class->new', and then call the 'fill' method, which will cause the specialised parser to scan forwards and parse the quote to its end point.

If ->fill returns true, finalise the token.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


site/lib/PPI/Token/_QuoteEngine/Full.pm

  • SUPPORT
  • AUTHOR
  • COPYRIGHT

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


site/lib/PPI/Token/_QuoteEngine/Simple.pm

  • SUPPORT
  • AUTHOR
  • COPYRIGHT

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Tokenizer - The Perl Document Tokenizer

  • METHODS
    • new $source | \@lines | \$source
    • get_token
    • all_tokens
    • increment_cursor
    • decrement_cursor
    • errstr
  • NOTES
    • How the Tokenizer Works
    • Source Input and Clean Up
    • Doing Things the Old Fashioned Way
    • State Variables
    • Making It Faster
    • Making It Faster - Whole Line Classification
    • Making It Faster - Inlining
    • Making It Faster - Quote Engine
    • Making It Faster - The "Complete" Mechanism
    • Making It Faster - Porting To C (In Progress)
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Tokenizer - The Perl Document Tokenizer

SYNOPSIS

  # Create a tokenizer for a file, array or string
  $Tokenizer = PPI::Tokenizer->new( 'filename.pl' );
  $Tokenizer = PPI::Tokenizer->new( \@lines       );
  $Tokenizer = PPI::Tokenizer->new( \$source      );

  # Return all the tokens for the document
  my $tokens = $Tokenizer->all_tokens;

  # Or we can use it as an iterator
  while ( my $Token = $Tokenizer->get_token ) {
        print "Found token '$Token'\n";
  }

  # If we REALLY need to manually nudge the cursor, you
  # can do that to (The lexer needs this ability to do rollbacks)
  $is_incremented = $Tokenizer->increment_cursor;
  $is_decremented = $Tokenizer->decrement_cursor;

DESCRIPTION

PPI::Tokenizer is the class that provides Tokenizer objects for use in breaking strings of Perl source code into Tokens.

By the time you are reading this, you probably need to know a little about the difference between how perl parses Perl "code" and how PPI parsers Perl "documents".

"perl" itself (the interpreter) uses a heavily modified lex specification to specify it's parsing logic, maintains several types of state as it goes, and both tokenizes and lexes AND EXECUTES at the same time. In fact, it's provably impossible to use perl's parsing method without BEING perl.

This is where the truism "Only perl can parse Perl" comes from.

PPI uses a completely different approach by abandoning the ability to provably parse perl, and instead to parse the source as a document, but get so close to being perfect that unless you do insanely silly things, it can handle it.

It was touch and go for a long time whether we could get it close enough, but in the end it turned out that it could be done.

In this approach, the tokenizer PPI::Tokenizer is separate from the lexer the PPI::Lexer manpage. The job of PPI::Tokenizer is to take pure source as a string and break it up into a stream/set of tokens.

The Tokenizer uses a hell of a lot of heuristics, guessing, and cruft, supported by a very VERY flexible internal API, but fortunately there's not a lot that gets exposed to people using the PPI::Tokenizer itself.

METHODS

Despite the incredible complexity, the Tokenizer itself only exposes a relatively small number of methods, with most of the complexity implemented in private methods.

new $source | \@lines | \$source

The main new constructor creates a new Tokenizer object. These objects have no configuration parameters, and can only be used once, to tokenize a single perl source file.

It takes as argument either a normal scalar containing source code, a reference to a scalar containing source code, or a reference to an ARRAY containing newline-terminated lines of source code.

Returns a new PPI::Tokenizer object on success, or undef on error.

get_token

When using the PPI::Tokenizer object as an iterator, the get_token method is the primary method that is used. It increments the cursor and returns the next Token in the output array.

The actual parsing of the file is done only as-needed, and a line at a time. When get_token hits the end of the token array, it will cause the parser to pull in the next line and parse it, continuing as needed until there are more tokens on the output array that get_token can then return.

This means that a number of Tokenizer objects can be created, and won't consume significant CPU until you actually begin to pull tokens from it.

Return a the PPI::Token manpage object on success, 0 if the Tokenizer had reached the end of the file, or undef on error.

all_tokens

When not being used as an iterator, the all_tokens method tells the Tokenizer to parse the entire file and return all of the tokens in a single ARRAY reference.

It should be noted that all_tokens does NOT interfere with the use of the Tokenizer object as an iterator (does not modify the token cursor) and use of the two different mechanisms can be mixed safely.

Returns a reference to an ARRAY of the PPI::Token manpage objects on success, 0 in the special case that the file/string contains NO tokens at all, or undef on error.

increment_cursor

Although exposed as a public method, increment_method is implemented for expert use only, when writing lexers or other components that work directly on token streams.

It manually increments the token cursor forward through the file, in effect "skipping" the next token.

Return true if the cursor is incremented, 0 if already at the end of the file, or undef on error.

decrement_cursor

Although exposed as a public method, decrement_method is implemented for expert use only, when writing lexers or other components that work directly on token streams.

It manually decrements the token cursor backwards through the file, in effect "rolling back" the token stream. And indeed that is what it is primarily intended for, when the component that is consuming the token stream needs to implement some sort of "roll back" feature in its use of the token stream.

Return true if the cursor is decremented, 0 if already at the beginning of the file, or undef on error.

errstr

For any error that occurs, you can use the errstr, as either a static or object method, to access the error message.

If no error occurs for any particular action, errstr will return false.

NOTES

How the Tokenizer Works

Understanding the Tokenizer is not for the feint-hearted. It is by far the most complex and twisty piece of perl I've ever written that is actually still built properly and isn't a terrible spaghetti-like mess. In fact, you probably want to skip this section.

But if you really want to understand, well then here goes.

Source Input and Clean Up

The Tokenizer starts by taking source in a variety of forms, sucking it all in and merging into one big string, and doing our own internal line split, using a "universal line separator" which allows the Tokenizer to take source for any platform (and even supports a few known types of broken newlines caused by mixed mac/pc/*nix editor screw ups).

The resulting array of lines is used to feed the tokenizer, and is also accessed directly by the heredoc-logic to do the line-oriented part of here-doc support.

Doing Things the Old Fashioned Way

Due to the complexity of perl, and after 2 previously aborted parser attempts, in the end the tokenizer was fashioned around a line-buffered character-by-character method.

That is, the Tokenizer pulls and holds a line at a time into a line buffer, and then iterates a cursor along it. At each cursor position, a method is called in whatever token class we are currently in, which will examine the character at the current position, and handle it.

As the handler methods in the various token classes are called, they build up a output token array for the source code.

Various parts of the Tokenizer use look-ahead, arbitrary-distance look-behind (although currently the maximum is three significant tokens), or both, and various other heuristic guesses.

I've been told it is officially termed a "backtracking parser with infinite lookaheads".

State Variables

Aside from the current line and the character cursor, the Tokenizer maintains a number of different state variables.

Current Class

The Tokenizer maintains the current token class at all times. Much of the time is just going to be the "Whitespace" class, which is what the base of a document is. As the tokenizer executes the various character handlers, the class changes a lot as it moves a long. In fact, in some instances, the character handler may not handle the character directly itself, but rather change the "current class" and then hand off to the character handler for the new class.

Because of this, and some other things I'll deal with later, the number of times the character handlers are called does not in fact have a direct relationship to the number of actual characters in the document.

Current Zone

Rather than create a class stack to allow for infinitely nested layers of classes, the Tokenizer recognises just a single layer.

To put it a different way, in various parts of the file, the Tokenizer will recognise different "base" or "substrate" classes. When a Token such as a comment or a number is finalised by the tokenizer, it "falls back" to the base state.

This allows proper tokenization of special areas such as __DATA__ and __END__ blocks, which also contain things like comments and POD, without allowing the creation of any significant Tokens inside these areas.

For the main part of a document we use the PPI::Token::Whitespace manpage for this, with the idea being that code is "floating in a sea of whitespace".

Current Token

The final main state variable is the "current token". This is the Token that is currently being built by the Tokenizer. For certain types, it can be manipulated and morphed and change class quite a bit while being assembled, as the Tokenizer's understanding of the token content changes.

When the Tokenizer is confident that it has seen the end of the Token, it will be "finalized", which adds it to the output token array and resets the current class to that of the zone that we are currently in.

I should also note at this point that the "current token" variable is optional. The Tokenizer is capable of knowing what class it is currently set to, without actually having accumulated any characters in the Token.

Making It Faster

As I'm sure you can imagine, calling several different methods for each character and running regexes and other complex heuristics made the first fully working version of the tokenizer extremely slow.

During testing, I created a metric to measure parsing speed called LPGC, or "lines per gigacycle" . A gigacycle is simple a billion CPU cycles on a typical single-core CPU, and so a Tokenizer running at "1000 lines per gigacycle" should generate around 1200 lines of tokenized code when running on a 1200 MHz processor.

The first working version of the tokenizer ran at only 350 LPGC, so to tokenize a typical large module such as the ExtUtils::MakeMaker manpage took 10-15 seconds. This sluggishness made it unpractical for many uses.

So in the current parser, there are multiple layers of optimisation very carefully built in to the basic. This has brought the tokenizer up to a more reasonable 1000 LPGC, at the expense of making the code quite a bit twistier.

Making It Faster - Whole Line Classification

The first step in the optimisation process was to add a hew handler to enable several of the more basic classes (whitespace, comments) to be able to be parsed a line at a time. At the start of each line, a special optional handler (only supported by a few classes) is called to check and see if the entire line can be parsed in one go.

This is used mainly to handle things like POD, comments, empty lines, and a few other minor special cases.

Making It Faster - Inlining

The second stage of the optimisation involved inlining a small number of critical methods that were repeated an extremely high number of times. Profiling suggested that there were about 1,000,000 individual method calls per gigacycle, and by cutting these by two thirds a significant speed improvement was gained, in the order of about 50%.

You may notice that many methods in the PPI::Tokenizer code look very nested and long hand. This is primarily due to this inlining.

At around this time, some statistics code that existed in the early versions of the parser was also removed, as it was determined that it was consuming around 15% of the CPU for the entire parser, while making the core more complicated.

A judgment call was made that with the difficulties likely to be encountered with future planned enhancements, and given the relatively high cost involved, the statistics features would be removed from the Tokenizer.

Making It Faster - Quote Engine

Once inlining had reached diminishing returns, it became obvious from the profiling results that a huge amount of time was being spent stepping a char at a time though long, simple and "syntactically boring" code such as comments and strings.

The existing regex engine was expanded to also encompass quotes and other quote-like things, and a special abstract base class was added that provided a number of specialised parsing methods that would "scan ahead", looking out ahead to find the end of a string, and updating the cursor to leave it in a valid position for the next call.

This is also the point at which the number of character handler calls began to greatly differ from the number of characters. But it has been done in a way that allows the parser to retain the power of the original version at the critical points, while skipping through the "boring bits" as needed for additional speed.

The addition of this feature allowed the tokenizer to exceed 1000 LPGC for the first time.

Making It Faster - The "Complete" Mechanism

As it became evident that great speed increases were available by using this "skipping ahead" mechanism, a new handler method was added that explicitly handles the parsing of an entire token, where the structure of the token is relatively simple. Tokens such as symbols fit this case, as once we are passed the initial sigil and word char, we know that we can skip ahead and "complete" the rest of the token much more easily.

A number of these have been added for most or possibly all of the common cases, with most of these "complete" handlers implemented using regular expressions.

In fact, so many have been added that at this point, you could arguably reclassify the tokenizer as a "hybrid regex, char-by=char heuristic tokenizer". More tokens are now consumed in "complete" methods in a typical program than are handled by the normal char-by-char methods.

Many of the these complete-handlers were implemented during the writing of the Lexer, and this has allowed the full parser to maintain around 1000 LPGC despite the increasing weight of the Lexer.

Making It Faster - Porting To C (In Progress)

While it would be extraordinarily difficult to port all of the Tokenizer to C, work has started on a the PPI::XS manpage "accelerator" package which acts as a separate and automatically-detected add-on to the main PPI package.

the PPI::XS manpage implements faster versions of a variety of functions scattered over the entire PPI codebase, from the Tokenizer Core, Quote Engine, and various other places, and implements them identically in XS/C.

In particular, the skip-ahead methods from the Quote Engine would appear to be extremely amenable to being done in C, and a number of other functions could be cherry-picked one at a time and implemented in C.

Each method is heavily tested to ensure that the functionality is identical, and a versioning mechanism is included to ensure that if a function gets out of sync, the PPI::XS manpage will degrade gracefully and just not replace that single method.

TO DO

- Add an option to reset or seek the token stream...

- Implement more Tokenizer functions in the PPI::XS manpage

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


PPI::Transform - Abstract base class for document transformation classes

  • METHODS
    • new [ param1 => $value, param2 => $value ]
    • document
    • apply
    • file $filename [, $output ]
  • TO DO
  • SUPPORT
  • AUTHOR
  • COPYRIGHT

NAME

PPI::Transform - Abstract base class for document transformation classes

DESCRIPTION

PPI::Transform provides an API for the creation of classes and objects that modify or transform PPI documents.

METHODS

new [ param1 => $value, param2 => $value ]

The new constructor creates a new object for your PPI::Transform subclass. A default constructor is provided for you which takes no params and creates a basic, empty, object.

If you wish to have your transform constructor take params, these must be in the form of a list of key/value pairs.

Returns a new PPI::Transform-compatible object, or undef if provided bad constructor params.

document

The document method should be implemented by each subclass, and takes a single argument of a the PPI::Document manpage object, modifying it in place as appropriate for the particular transform class.

That's right, this method will not clone and should not clone the document object. If you do not want the original to be modified, you need to clone it yourself before passing it in.

Returns the document anyway, as a convenience, or undef if an error occurs. By default this error should just be that you passed in something that wasn't a the PPI::Document manpage, but may include additional errors depending on the subclass.

apply

The apply method is used to apply the transform to something. The argument must be a the PPI::Document manpage, or something which can be turned into a one and then be written back to again.

Currently, this list is limited to a SCALAR reference, although a handler registration process is available for you to add support for additional types of object should you wish (see the source for this module).

Returns true if the transform was applied, false if there is an error in the transform process, or may die if there is a critical error in the apply handler.

file $filename [, $output ]

The file method modifies a Perl document by filename. If passed a single parameter, it modifies the file in-place. If provided a second parameter, it will attempt to save the modified file to the alternative filename.

Returns true on success, or undef on error.

TO DO

- May need to overload some methods to forcefully prevent Document objects becoming children of another Node.

SUPPORT

See the support section in the main module.

AUTHOR

Adam Kennedy <adamk@cpan.org>

COPYRIGHT

Copyright 2001 - 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Params::Util - Simple, compact and correct param-checking functions

  • FUNCTIONS
    • _STRING $string
    • _IDENTIFIER $string
    • _CLASS $string
    • _POSINT $integer
    • _SCALAR \$scalar
    • _SCALAR0 \$scalar
    • _ARRAY $value
    • _ARRAY0 $value
    • _ARRAYLIKE $value
    • _HASH $value
    • _HASH0 $value
    • _HASHLIKE $value
    • _CODE $value
    • _CODELIKE $value
    • _INVOCANT $value
    • _INSTANCE $object, $class
    • _SET \@array, $class
    • _SET0 \@array, $class
    • _HANDLE
  • TO DO
  • SUPPORT
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

Params::Util - Simple, compact and correct param-checking functions

SYNOPSIS

  # Import some functions
  use Params::Util qw{_SCALAR _HASH _INSTANCE};

  # If you are lazy, or need a lot of them...
  use Params::Util ':ALL';

  sub foo {
      my $object  = _INSTANCE(shift, 'Foo') or return undef;
      my $image   = _SCALAR(shift)          or return undef;
      my $options = _HASH(shift)            or return undef;
      # etc...
  }

DESCRIPTION

Params::Util provides a basic set of importable functions that makes checking parameters a hell of a lot easier

While they can be (and are) used in other contexts, the main point behind this module is that the functions both Do What You Mean, and Do The Right Thing, so they are most useful when you are getting params passed into your code from someone and/or somewhere else and you can't really trust the quality.

Thus, Params::Util is of most use at the edges of your API, where params and data are coming in from outside your code.

The functions provided by Params::Util check in the most strictly correct manner known, are documented as thoroughly as possible so their exact behaviour is clear, and heavily tested so make sure they are not fooled by weird data and Really Bad Things.

To use, simply load the module providing the functions you want to use as arguments (as shown in the SYNOPSIS).

To aid in maintainability, Params::Util will never export by default.

You must explicitly name the functions you want to export, or use the :ALL param to just have it export everything (although this is not recommended if you have any _FOO functions yourself with which future additions to Params::Util may clash)

FUNCTIONS

_STRING $string

The _STRING function is intended to be imported into your package, and provides a convenient way to test to see if a value is a normal non-false string of non-zero length.

Note that this will NOT do anything magic to deal with the special '0' false negative case, but will return it.

  # '0' not considered valid data
  my $name = _STRING(shift) or die "Bad name";

  # '0' is considered valid data
  my $string = _STRING($_[0]) ? shift : die "Bad string";

Please also note that this function expects a normal string. It does not support overloading or other magic techniques to get a string.

Returns the string as a conveince if it is a valid string, or undef if not.

_IDENTIFIER $string

The _IDENTIFIER function is intended to be imported into your package, and provides a convenient way to test to see if a value is a string that is a valid Perl identifier.

Returns the string as a convenience if it is a valid identifier, or undef if not.

_CLASS $string

The _CLASS function is intended to be imported into your package, and provides a convenient way to test to see if a value is a string that is a valid Perl class.

This function only checks that the format is valid, not that the class is actually loaded. It also assumes "normalised" form, and does not accept class names such as ::Foo or D'Oh.

Returns the string as a convenience if it is a valid class name, or undef if not.

_POSINT $integer

The _POSINT function is intended to be imported into your package, and provides a convenient way to test to see if a value is a positive integer (of any length).

Returns the value as a convience, or undef if the value is not a positive integer.

_SCALAR \$scalar

The _SCALAR function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed SCALAR reference, with content of non-zero length.

For a version that allows zero length SCALAR references, see the _SCALAR0 function.

Returns the SCALAR reference itself as a convenience, or undef if the value provided is not a SCALAR reference.

_SCALAR0 \$scalar

The _SCALAR0 function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed SCALAR0 reference, allowing content of zero-length.

For a simpler "give me some content" version that requires non-zero length, _SCALAR function.

Returns the SCALAR reference itself as a convenience, or undef if the value provided is not a SCALAR reference.

_ARRAY $value

The _ARRAY function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed ARRAY reference containing at least one element of any kind.

For a more basic form that allows zero length ARRAY references, see the _ARRAY0 function.

Returns the ARRAY reference itself as a convenience, or undef if the value provided is not an ARRAY reference.

_ARRAY0 $value

The _ARRAY0 function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed ARRAY reference, allowing ARRAY references that contain no elements.

For a more basic "An array of something" form that also requires at least one element, see the _ARRAY function.

Returns the ARRAY reference itself as a convenience, or undef if the value provided is not an ARRAY reference.

_ARRAYLIKE $value

The _ARRAYLIKE function tests whether a given scalar value can respond to array dereferencing. If it can, the value is returned. If it cannot, _ARRAYLIKE returns undef.

_HASH $value

The _HASH function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed HASH reference with at least one entry.

For a version of this function that allows the HASH to be empty, see the _HASH0 function.

Returns the HASH reference itself as a convenience, or undef if the value provided is not an HASH reference.

_HASH0 $value

The _HASH0 function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed HASH reference, regardless of the HASH content.

For a simpler "A hash of something" version that requires at least one element, see the _HASH function.

Returns the HASH reference itself as a convenience, or undef if the value provided is not an HASH reference.

_HASHLIKE $value

The _HASHLIKE function tests whether a given scalar value can respond to hash dereferencing. If it can, the value is returned. If it cannot, _HASHLIKE returns undef.

_CODE $value

The _CODE function is intended to be imported into your package, and provides a convenient way to test for a raw and unblessed CODE reference.

Returns the CODE reference itself as a convenience, or undef if the value provided is not an CODE reference.

_CODELIKE $value

The _CODELIKE is the more generic version of _CODE. Unlike _CODE, which checks for an explicit CODE reference, the _CODELIKE function also includes things that act like them, such as blessed objects that overload '&{}'.

Note that in the case of objects overloaded with '&{}', you will almost always end up also testing it in 'bool' context. As such, you will most often want to make sure your class has the following to allow it to evaluate to true in boolean context.

  # Always evaluate to true in boolean context
  use overload 'bool' => sub () { 1 };

Returns the callable value as a convenience, or undef if the value provided is not callable.

Note - This function was formerly known as _CODELIKE but has been renamed for greater symmetry with the other _XXXXLIKE functions.

It will continue to work silently until end-May 2006, then with a warning until end-August 2006, then will be deprecated.

I apologise for any inconvenience caused.

_INVOCANT $value

This routine tests whether the given value is a valid method invocant. If so, the value itself is returned. Otherwise, _INVOCANT returns undef.

_INSTANCE $object, $class

The _INSTANCE function is intended to be imported into your package, and provides a convenient way to test for an object of a particular class in a strictly correct manner.

Returns the object itself as a convenience, or undef if the value provided is not an object of that type.

_SET \@array, $class

The _SET function is intended to be imported into your package, and provides a convenient way to test for set of at least one object of a particular class in a strictly correct manner.

The set is provided as a reference to an ARRAY of objects of the class provided.

For an alternative function that allows zero-length sets, see the _SET0 function.

Returns the ARRAY reference itself as a convenience, or undef if the value provided is not a set of that class.

_SET0 \@array, $class

The _SET0 function is intended to be imported into your package, and provides a convenient way to test for a set of objects of a particular class in a strictly correct manner, allowing for zero objects.

The set is provided as a reference to an ARRAY of objects of the class provided.

For an alternative function that requires at least one object, see the _SET function.

Returns the ARRAY reference itself as a convenience, or undef if the value provided is not a set of that class.

_HANDLE

EXPERIMENTAL: SUBJECT TO CHANGE OR POSSIBLE REMOVAL

The _HANDLE function is intended to be imported into your package, and provides a convenient way to test whether or not a single scalar value is a file handle.

Unfortunately, in Perl the definition of a file handle can be a little bit fuzzy, so this function is likely to be somewhat imperfect (at first anyway).

That said, it is implement as well or better than the other file handle detectors in existance (and we stole from the best of them).

TO DO

- Add _CAN to help resolve the UNIVERSAL::can debacle

- More comprehensive tests for _SET and _SET0

- Would be nice if someone would re-implement in XS for me? (done'ish)

- Would be even nicer if someone would demonstrate how the hell to build a Module::Install dist of the ::Util dual Perl/XS type. :/

- Implement an assertion-like version of this module, that dies on error.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html

For other issues, contact the author.

AUTHOR

Adam Kennedy <cpan@ali.as>

SEE ALSO

http://ali.as/

COPYRIGHT

Copyright 2005, 2006 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Params::Validate - Validate method/function parameters

    • EXPORT
  • PARAMETER VALIDATION
    • Mandatory/Optional Parameters
    • Type Validation
    • Interface Validation
    • Class Validation
    • Regex Validation
    • Callback Validation
    • Untainting
    • Mandatory/Optional Revisited
    • Dependencies
    • Specifying defaults
  • USAGE NOTES
    • Validation failure
    • Method calls
  • "GLOBAL" OPTIONS
    • Options
  • PER-INVOCATION OPTIONS
  • DISABLING VALIDATION
  • LIMITATIONS
  • SUPPORT
  • AUTHORS
  • COPYRIGHT

NAME

Params::Validate - Validate method/function parameters

SYNOPSIS

  use Params::Validate qw(:all);

  # takes named params (hash or hashref)
  sub foo
  {
      validate( @_, { foo => 1, # mandatory
                      bar => 0, # optional
                    }
              );
  }

  # takes positional params
  sub bar
  {
      # first two are mandatory, third is optional
      validate_pos( @_, 1, 1, 0 );
  }

  sub foo2
  {
      validate( @_,
                { foo =>
                  # specify a type
                  { type => ARRAYREF },

                  bar =>
                  # specify an interface
                  { can => [ 'print', 'flush', 'frobnicate' ] },

                  baz =>
                  { type => SCALAR,   # a scalar ...
                    # ... that is a plain integer ...
                    regex => qr/^\d+$/,
                    callbacks =>
                    { # ... and smaller than 90
                      'less than 90' => sub { shift() < 90 },
                    },
                  }
                                  }
                                );
                    }

  sub with_defaults
  {
       my %p = validate( @_, { foo => 1, # required
                               # $p{bar} will be 99 if bar is not
                               # given.  bar is now optional.
                               bar => { default => 99 } } );
  }

  sub pos_with_defaults
  {
       my @p = validate_pos( @_, 1, { default => 99 } );
  }

  sub sets_options_on_call
  {
       my %p = validate_with
                   ( params => \@_,
                     spec   => { foo => { type SCALAR, default => 2 } },
                     normalize_keys => sub { $_[0] =~ s/^-//; lc $_[0] },
                   );
  }

DESCRIPTION

The Params::Validate module allows you to validate method or function call parameters to an arbitrary level of specificity. At the simplest level, it is capable of validating the required parameters were given and that no unspecified additional parameters were passed in.

It is also capable of determining that a parameter is of a specific type, that it is an object of a certain class hierarchy, that it possesses certain methods, or applying validation callbacks to arguments.

EXPORT

The module always exports the validate() and validate_pos() functions.

It also has an additional function available for export, validate_with, which can be used to validate any type of parameters, and set various options on a per-invocation basis.

In addition, it can export the following constants, which are used as part of the type checking. These are SCALAR, ARRAYREF, HASHREF, CODEREF, GLOB, GLOBREF, and SCALARREF, UNDEF, OBJECT, BOOLEAN, and HANDLE. These are explained in the section on Type Validation.

The constants are available via the export tag :types. There is also an :all tag which includes all of the constants as well as the validation_options() function.

PARAMETER VALIDATION

The validation mechanisms provided by this module can handle both named or positional parameters. For the most part, the same features are available for each. The biggest difference is the way that the validation specification is given to the relevant subroutine. The other difference is in the error messages produced when validation checks fail.

When handling named parameters, the module is capable of handling either a hash or a hash reference transparently.

Subroutines expecting named parameters should call the validate() subroutine like this:

 validate( @_, { parameter1 => validation spec,
                 parameter2 => validation spec,
                 ...
               } );

Subroutines expecting positional parameters should call the validate_pos() subroutine like this:

 validate_pos( @_, { validation spec }, { validation spec } );

Mandatory/Optional Parameters

If you just want to specify that some parameters are mandatory and others are optional, this can be done very simply.

For a subroutine expecting named parameters, you would do this:

 validate( @_, { foo => 1, bar => 1, baz => 0 } );

This says that the "foo" and "bar" parameters are mandatory and that the "baz" parameter is optional. The presence of any other parameters will cause an error.

For a subroutine expecting positional parameters, you would do this:

 validate_pos( @_, 1, 1, 0, 0 );

This says that you expect at least 2 and no more than 4 parameters. If you have a subroutine that has a minimum number of parameters but can take any maximum number, you can do this:

 validate_pos( @_, 1, 1, (0) x (@_ - 2) );

This will always be valid as long as at least two parameters are given. A similar construct could be used for the more complex validation parameters described further on.

Please note that this:

 validate_pos( @_, 1, 1, 0, 1, 1 );

makes absolutely no sense, so don't do it. Any zeros must come at the end of the validation specification.

In addition, if you specify that a parameter can have a default, then it is considered optional.

Type Validation

This module supports the following simple types, which can be exported as constants:

  • SCALAR

    A scalar which is not a reference, such as 10 or 'hello'. A parameter that is undefined is not treated as a scalar. If you want to allow undefined values, you will have to specify SCALAR | UNDEF.

  • ARRAYREF

    An array reference such as [1, 2, 3] or \@foo.

  • HASHREF

    A hash reference such as { a => 1, b => 2 } or \%bar.

  • CODEREF

    A subroutine reference such as \&foo_sub or sub { print "hello" }.

  • GLOB

    This one is a bit tricky. A glob would be something like *FOO, but not \*FOO, which is a glob reference. It should be noted that this trick:

     my $fh = do { local *FH; };

    makes $fh a glob, not a glob reference. On the other hand, the return value from Symbol::gensym is a glob reference. Either can be used as a file or directory handle.

  • GLOBREF

    A glob reference such as \*FOO. See the GLOB entry above for more details.

  • SCALARREF

    A reference to a scalar such as \$x.

  • UNDEF

    An undefined value

  • OBJECT

    A blessed reference.

  • BOOLEAN

    This is a special option, and is just a shortcut for UNDEF | SCALAR.

  • HANDLE

    This option is also special, and is just a shortcut for GLOB | GLOBREF. However, it seems likely that most people interested in either globs or glob references are likely to really be interested in whether the parameter in question could be a valid file or directory handle.

To specify that a parameter must be of a given type when using named parameters, do this:

 validate( @_, { foo => { type => SCALAR },
                 bar => { type => HASHREF } } );

If a parameter can be of more than one type, just use the bitwise or (|) operator to combine them.

 validate( @_, { foo => { type => GLOB | GLOBREF } );

For positional parameters, this can be specified as follows:

 validate_pos( @_, { type => SCALAR | ARRAYREF }, { type => CODEREF } );

Interface Validation

To specify that a parameter is expected to have a certain set of methods, we can do the following:

 validate( @_,
           { foo =>
             # just has to be able to ->bar
             { can => 'bar' } } );

 ... or ...
 validate( @_,
           { foo =>
             # must be able to ->bar and ->print
             { can => [ qw( bar print ) ] } } );

Class Validation

A word of warning. When constructing your external interfaces, it is probably better to specify what methods you expect an object to have rather than what class it should be of (or a child of). This will make your API much more flexible.

With that said, if you want to validate that an incoming parameter belongs to a class (or child class) or classes, do:

 validate( @_,
           { foo =>
             { isa => 'My::Frobnicator' } } );

 ... or ...
 validate( @_,
           { foo =>
             { isa => [ qw( My::Frobnicator IO::Handle ) ] } } );
 # must be both, not either!

Regex Validation

If you want to specify that a given parameter must match a specific regular expression, this can be done with "regex" spec key. For example:

 validate( @_,
           { foo =>
             { regex => qr/^\d+$/ } } );

The value of the "regex" key may be either a string or a pre-compiled regex created via qr.

If the value being checked against a regex is undefined, the regex is explicitly checked against the empty string ('') instead, in order to avoid "Use of uninitialized value" warnings.

The Regexp::Common module on CPAN is an excellent source of regular expressions suitable for validating input.

Callback Validation

If none of the above are enough, it is possible to pass in one or more callbacks to validate the parameter. The callback will be given the value of the parameter as its first argument. Its second argument will be all the parameters, as a reference to either a hash or array. Callbacks are specified as hash reference. The key is an id for the callback (used in error messages) and the value is a subroutine reference, such as:

 validate( @_,
           { foo =>
             { callbacks =>
               { 'smaller than a breadbox' => sub { shift() < $breadbox },
                 'green or blue' =>
                  sub { $_[0] eq 'green' || $_[0] eq 'blue' } } } );

 validate( @_,
           { foo =>
             { callbacks =>
               { 'bigger than baz' => sub { $_[0] > $_[1]->{baz} } } } } );

Untainting

If you want values untainted, set the "untaint" key in a spec hashref to a true value, like this:

 my %p =
   validate( @_, { foo =>
                   { type => SCALAR, untaint => 1 },
                   bar =>
                   { type => ARRAYREF } } );

This will untaint the "foo" parameter if the parameters are valid.

Note that untainting is only done if all parameters are valid. Also, only the return values are untainted, not the original values passed into the validation function.

Asking for untainting of a reference value will not do anything, as Params::Validate will only attempt to untaint the reference itself.

Mandatory/Optional Revisited

If you want to specify something such as type or interface, plus the fact that a parameter can be optional, do this:

 validate( @_, { foo =>
                 { type => SCALAR },
                 bar =>
                 { type => ARRAYREF, optional => 1 } } );

or this for positional parameters:

 validate_pos( @_, { type => SCALAR }, { type => ARRAYREF, optional => 1 } );

By default, parameters are assumed to be mandatory unless specified as optional.

Dependencies

It also possible to specify that a given optional parameter depends on the presence of one or more other optional parameters.

 validate( @_, { cc_number =>
                 { type => SCALAR, optional => 1,
                   depends => [ 'cc_expiration', 'cc_holder_name' ],
                 },
                 cc_expiration
                 { type => SCALAR, optional => 1 },
                 cc_holder_name
                 { type => SCALAR, optional => 1 },
               } );

In this case, "cc_number", "cc_expiration", and "cc_holder_name" are all optional. However, if "cc_number" is provided, then "cc_expiration" and "cc_holder_name" must be provided as well.

This allows you to group together sets of parameters that all must be provided together.

The validate_pos() version of dependencies is slightly different, in that you can only depend on one other parameter. Also, if for example, the second parameter 2 depends on the fourth parameter, then it implies a dependency on the third parameter as well. This is because if the fourth parameter is required, then the user must also provide a third parameter so that there can be four parameters in total.

Params::Validate will die if you try to depend on a parameter not declared as part of your parameter specification.

Specifying defaults

If the validate() or validate_pos() functions are called in a list context, they will return an array or hash containing the original parameters plus defaults as indicated by the validation spec.

If the function is not called in a list context, providing a default in the validation spec still indicates that the parameter is optional.

The hash or array returned from the function will always be a copy of the original parameters, in order to leave @_ untouched for the calling function.

Simple examples of defaults would be:

 my %p = validate( @_, { foo => 1, bar => { default => 99 } } );

 my @p = validate( @_, 1, { default => 99 } );

In scalar context, a hash reference or array reference will be returned, as appropriate.

USAGE NOTES

Validation failure

By default, when validation fails Params::Validate calls Carp::confess(). This can be overridden by setting the on_fail option, which is described in the "GLOBAL" OPTIONS section.

Method calls

When using this module to validate the parameters passed to a method call, you will probably want to remove the class/object from the parameter list before calling validate() or validate_pos(). If your method expects named parameters, then this is necessary for the validate() function to actually work, otherwise @_ will not be useable as a hash, because it will first have your object (or class) followed by a set of keys and values.

Thus the idiomatic usage of validate() in a method call will look something like this:

 sub method
 {
     my $self = shift;

     my %params = validate( @_, { foo => 1, bar => { type => ARRAYREF } } );
      }

"GLOBAL" OPTIONS

Because the calling syntax for the validate() and validate_pos() functions does not make it possible to specify any options other than the the validation spec, it is possible to set some options as pseudo-'globals'. These allow you to specify such things as whether or not the validation of named parameters should be case sensitive, for one example.

These options are called pseudo-'globals' because these settings are only applied to calls originating from the package that set the options.

In other words, if I am in package Foo and I call Params::Validate::validation_options(), those options are only in effect when I call validate() from package Foo.

While this is quite different from how most other modules operate, I feel that this is necessary in able to make it possible for one module/application to use Params::Validate while still using other modules that also use Params::Validate, perhaps with different options set.

The downside to this is that if you are writing an app with a standard calling style for all functions, and your app has ten modules, each module must include a call to Params::Validate::validation_options().

Options

  • normalize_keys => $callback

    This option is only relevant when dealing with named parameters.

    This callback will be used to transform the hash keys of both the parameters and the parameter spec when validate() or validate_with() are called.

    Any alterations made by this callback will be reflected in the parameter hash that is returned by the validation function. For example:

      sub foo {
      return
        validate_with( params => \@_,
                       spec   => { foo => { type => SCALAR } },
                       normalize_keys =>
                       sub { my $k = shift; $k =~ s/^-//; return uc $k },
                     );

      }
      %p = foo( foo => 20 );

      # $p{FOO} is now 20

      %p = foo( -fOo => 50 );

      # $p{FOO} is now 50

    The callback must return a defined value.

    If a callback is given than the deprecated "ignore_case" and "strip_leading" options are ignored.

  • allow_extra => $boolean

    If true, then the validation routine will allow extra parameters not named in the validation specification. In the case of positional parameters, this allows an unlimited number of maximum parameters (though a minimum may still be set). Defaults to false.

  • on_fail => $callback

    If given, this callback will be called whenever a validation check fails. It will be called with a single parameter, which will be a string describing the failure. This is useful if you wish to have this module throw exceptions as objects rather than as strings, for example.

    This callback is expected to die() internally. If it does not, the validation will proceed onwards, with unpredictable results.

    The default is to simply use the Carp module's confess() function.

  • stack_skip => $number

    This tells Params::Validate how many stack frames to skip when finding a subroutine name to use in error messages. By default, it looks one frame back, at the immediate caller to validate() or validate_pos(). If this option is set, then the given number of frames are skipped instead.

  • ignore_case => $boolean

    DEPRECATED

    This is only relevant when dealing with named parameters. If it is true, then the validation code will ignore the case of parameter names. Defaults to false.

  • strip_leading => $characters

    DEPRECATED

    This too is only relevant when dealing with named parameters. If this is given then any parameters starting with these characters will be considered equivalent to parameters without them entirely. For example, if this is specified as '-', then -foo and foo would be considered identical.

PER-INVOCATION OPTIONS

The validate_with() function can be used to set the options listed above on a per-invocation basis. For example:

  my %p =
      validate_with
          ( params => \@_,
            spec   => { foo => { type => SCALAR },
                        bar => { default => 10 } },
            allow_extra => 1,
          );

In addition to the options listed above, it is also possible to set the option "called", which should be a string. This string will be used in any error messages caused by a failure to meet the validation spec.

This subroutine will validate named parameters as a hash if the "spec" parameter is a hash reference. If it is an array reference, the parameters are assumed to be positional.

  my %p =
      validate_with
          ( params => \@_,
            spec   => { foo => { type => SCALAR },
                        bar => { default => 10 } },
            allow_extra => 1,
            called => 'The Quux::Baz class constructor',
          );

  my @p =
      validate_with
          ( params => \@_,
            spec   => [ { type => SCALAR },
                        { default => 10 } ],
            allow_extra => 1,
            called => 'The Quux::Baz class constructor',
          );

DISABLING VALIDATION

If the environment variable PERL_NO_VALIDATION is set to something true, then validation is turned off. This may be useful if you only want to use this module during development but don't want the speed hit during production.

The only error that will be caught will be when an odd number of parameters are passed into a function/method that expects a hash.

If you want to selectively turn validation on and off at runtime, you can directly set the $Params::Validate::NO_VALIDATION global variable. It is strongly recommended that you localize any changes to this variable, because other modules you are using may expect validation to be on when they execute. For example:

  {
      local $Params::Validate::NO_VALIDATION = 1;
      # no error
      foo( bar => 2 );
  }

  # error
  foo( bar => 2 );

  sub foo
  {
      my %p = validate( @_, { foo => 1 } );
      ...
  }

But if you want to shoot yourself in the foot and just turn it off, go ahead!

LIMITATIONS

Right now there is no way (short of a callback) to specify that something must be of one of a list of classes, or that it must possess one of a list of methods. If this is desired, it can be added in the future.

Ideally, there would be only one validation function. If someone figures out how to do this, please let me know.

SUPPORT

Please submit bugs and patches to the CPAN RT system at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params%3A%3AValidate or via email at bug-params-validate@rt.cpan.org.

Support questions can be sent to Dave at autarch@urth.org.

The code repository is at https://svn.urth.org/svn/Params-Validate/

AUTHORS

Dave Rolsky, <autarch@urth.org> and Ilya Martynov <ilya@martynov.org>

COPYRIGHT

Copyright (c) 2004-2006 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Params::ValidatePP - pure Perl implementation of Params::Validate

  • COPYRIGHT

NAME

Params::ValidatePP - pure Perl implementation of Params::Validate

SYNOPSIS

  See Params::Validate

DESCRIPTION

This is a pure Perl implementation of Params::Validate. See the Params::Validate documentation for details.

COPYRIGHT

Copyright (c) 2004 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Params::ValidateXS - XS implementation of Params::Validate

  • COPYRIGHT

NAME

Params::ValidateXS - XS implementation of Params::Validate

SYNOPSIS

  See Params::Validate

DESCRIPTION

This is an XS implementation of Params::Validate. See the Params::Validate documentation for details.

COPYRIGHT

Copyright (c) 2004 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Parse::RecDescent - Generate Recursive-Descent Parsers

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • Overview
    • Using Parse::RecDescent
    • Rules
    • Subrules
    • Tokens
    • Terminal Separators
    • Actions
    • Start-up Actions
    • Autoactions
    • Autotrees
    • Autostubbing
    • Look-ahead
    • Directives
    • Subrule argument lists
    • Alternations
    • Incremental Parsing
    • Precompiling parsers
    • A Metagrammar for Parse::RecDescent
  • GOTCHAS
    • 1. Expecting an error to always invalidate a parse
  • DIAGNOSTICS
  • AUTHOR
  • BUGS AND IRRITATIONS
  • ON-GOING ISSUES AND FUTURE DIRECTIONS
  • COPYRIGHT

NAME

Parse::RecDescent - Generate Recursive-Descent Parsers

VERSION

This document describes version 1.94 of Parse::RecDescent, released April 9, 2003.

SYNOPSIS

 use Parse::RecDescent;

 # Generate a parser from the specification in $grammar:

         $parser = new Parse::RecDescent ($grammar);

 # Generate a parser from the specification in $othergrammar

         $anotherparser = new Parse::RecDescent ($othergrammar);

 # Parse $text using rule 'startrule' (which must be
 # defined in $grammar):

        $parser->startrule($text);

 # Parse $text using rule 'otherrule' (which must also
 # be defined in $grammar):

         $parser->otherrule($text);

 # Change the universal token prefix pattern
 # (the default is: '\s*'):

        $Parse::RecDescent::skip = '[ \t]+';

 # Replace productions of existing rules (or create new ones)
 # with the productions defined in $newgrammar:

        $parser->Replace($newgrammar);

 # Extend existing rules (or create new ones)
 # by adding extra productions defined in $moregrammar:

        $parser->Extend($moregrammar);

 # Global flags (useful as command line arguments under -s):

        $::RD_ERRORS       # unless undefined, report fatal errors
        $::RD_WARN         # unless undefined, also report non-fatal problems
        $::RD_HINT         # if defined, also suggestion remedies
        $::RD_TRACE        # if defined, also trace parsers' behaviour
        $::RD_AUTOSTUB     # if defined, generates "stubs" for undefined rules
        $::RD_AUTOACTION   # if defined, appends specified action to productions

DESCRIPTION

Overview

Parse::RecDescent incrementally generates top-down recursive-descent text parsers from simple yacc-like grammar specifications. It provides:

  • Regular expressions or literal strings as terminals (tokens),

  • Multiple (non-contiguous) productions for any rule,

  • Repeated and optional subrules within productions,

  • Full access to Perl within actions specified as part of the grammar,

  • Simple automated error reporting during parser generation and parsing,

  • The ability to commit to, uncommit to, or reject particular productions during a parse,

  • The ability to pass data up and down the parse tree ("down" via subrule argument lists, "up" via subrule return values)

  • Incremental extension of the parsing grammar (even during a parse),

  • Precompilation of parser objects,

  • User-definable reduce-reduce conflict resolution via "scoring" of matching productions.

Using Parse::RecDescent

Parser objects are created by calling Parse::RecDescent::new, passing in a grammar specification (see the following subsections). If the grammar is correct, new returns a blessed reference which can then be used to initiate parsing through any rule specified in the original grammar. A typical sequence looks like this:

        $grammar = q {
                        # GRAMMAR SPECIFICATION HERE
                     };

        $parser = new Parse::RecDescent ($grammar) or die "Bad grammar!\n";

        # acquire $text

        defined $parser->startrule($text) or print "Bad text!\n";

The rule through which parsing is initiated must be explicitly defined in the grammar (i.e. for the above example, the grammar must include a rule of the form: "startrule: <subrules>".

If the starting rule succeeds, its value (see below) is returned. Failure to generate the original parser or failure to match a text is indicated by returning undef. Note that it's easy to set up grammars that can succeed, but which return a value of 0, "0", or "". So don't be tempted to write:

        $parser->startrule($text) or print "Bad text!\n";

Normally, the parser has no effect on the original text. So in the previous example the value of $text would be unchanged after having been parsed.

If, however, the text to be matched is passed by reference:

        $parser->startrule(\$text)

then any text which was consumed during the match will be removed from the start of $text.

Rules

In the grammar from which the parser is built, rules are specified by giving an identifier (which must satisfy /[A-Za-z]\w*/), followed by a colon on the same line, followed by one or more productions, separated by single vertical bars. The layout of the productions is entirely free-format:

        rule1:  production1
             |  production2 |
                production3 | production4

At any point in the grammar previously defined rules may be extended with additional productions. This is achieved by redeclaring the rule with the new productions. Thus:

        rule1: a | b | c
        rule2: d | e | f
        rule1: g | h

is exactly equivalent to:

        rule1: a | b | c | g | h
        rule2: d | e | f

Each production in a rule consists of zero or more items, each of which may be either: the name of another rule to be matched (a "subrule"), a pattern or string literal to be matched directly (a "token"), a block of Perl code to be executed (an "action"), a special instruction to the parser (a "directive"), or a standard Perl comment (which is ignored).

A rule matches a text if one of its productions matches. A production matches if each of its items match consecutive substrings of the text. The productions of a rule being matched are tried in the same order that they appear in the original grammar, and the first matching production terminates the match attempt (successfully). If all productions are tried and none matches, the match attempt fails.

Note that this behaviour is quite different from the "prefer the longer match" behaviour of yacc. For example, if yacc were parsing the rule:

        seq : 'A' 'B'
            | 'A' 'B' 'C'

upon matching "AB" it would look ahead to see if a 'C' is next and, if so, will match the second production in preference to the first. In other words, yacc effectively tries all the productions of a rule breadth-first in parallel, and selects the "best" match, where "best" means longest (note that this is a gross simplification of the true behaviour of yacc but it will do for our purposes).

In contrast, Parse::RecDescent tries each production depth-first in sequence, and selects the "best" match, where "best" means first. This is the fundamental difference between "bottom-up" and "recursive descent" parsing.

Each successfully matched item in a production is assigned a value, which can be accessed in subsequent actions within the same production (or, in some cases, as the return value of a successful subrule call). Unsuccessful items don't have an associated value, since the failure of an item causes the entire surrounding production to immediately fail. The following sections describe the various types of items and their success values.

Subrules

A subrule which appears in a production is an instruction to the parser to attempt to match the named rule at that point in the text being parsed. If the named subrule is not defined when requested the production containing it immediately fails (unless it was "autostubbed" - see Autostubbing).

A rule may (recursively) call itself as a subrule, but not as the left-most item in any of its productions (since such recursions are usually non-terminating).

The value associated with a subrule is the value associated with its $return variable (see Actions below), or with the last successfully matched item in the subrule match.

Subrules may also be specified with a trailing repetition specifier, indicating that they are to be (greedily) matched the specified number of times. The available specifiers are:

                subrule(?)      # Match one-or-zero times
                subrule(s)      # Match one-or-more times
                subrule(s?)     # Match zero-or-more times
                subrule(N)      # Match exactly N times for integer N > 0
                subrule(N..M)   # Match between N and M times
                subrule(..M)    # Match between 1 and M times
                subrule(N..)    # Match at least N times

Repeated subrules keep matching until either the subrule fails to match, or it has matched the minimal number of times but fails to consume any of the parsed text (this second condition prevents the subrule matching forever in some cases).

Since a repeated subrule may match many instances of the subrule itself, the value associated with it is not a simple scalar, but rather a reference to a list of scalars, each of which is the value associated with one of the individual subrule matches. In other words in the rule:

                program: statement(s)

the value associated with the repeated subrule "statement(s)" is a reference to an array containing the values matched by each call to the individual subrule "statement".

Repetition modifieres may include a separator pattern:

                program: statement(s /;/)

specifying some sequence of characters to be skipped between each repetition. This is really just a shorthand for the <leftop:...> directive (see below).

Tokens

If a quote-delimited string or a Perl regex appears in a production, the parser attempts to match that string or pattern at that point in the text. For example:

                typedef: "typedef" typename identifier ';'

                identifier: /[A-Za-z_][A-Za-z0-9_]*/

As in regular Perl, a single quoted string is uninterpolated, whilst a double-quoted string or a pattern is interpolated (at the time of matching, not when the parser is constructed). Hence, it is possible to define rules in which tokens can be set at run-time:

                typedef: "$::typedefkeyword" typename identifier ';'

                identifier: /$::identpat/

Note that, since each rule is implemented inside a special namespace belonging to its parser, it is necessary to explicitly quantify variables from the main package.

Regex tokens can be specified using just slashes as delimiters or with the explicit m<delimiter>......<delimiter> syntax:

                typedef: "typedef" typename identifier ';'

                typename: /[A-Za-z_][A-Za-z0-9_]*/
                identifier: m{[A-Za-z_][A-Za-z0-9_]*}

A regex of either type can also have any valid trailing parameter(s) (that is, any of [cgimsox]):

                typedef: "typedef" typename identifier ';'

                identifier: / [a-z_]            # LEADING ALPHA OR UNDERSCORE
                              [a-z0-9_]*        # THEN DIGITS ALSO ALLOWED
                            /ix                 # CASE/SPACE/COMMENT INSENSITIVE

The value associated with any successfully matched token is a string containing the actual text which was matched by the token.

It is important to remember that, since each grammar is specified in a Perl string, all instances of the universal escape character '\' within a grammar must be "doubled", so that they interpolate to single '\'s when the string is compiled. For example, to use the grammar:

                word:       /\S+/ | backslash
                line:       prefix word(s) "\n"
                backslash:  '\\'

the following code is required:

                $parser = new Parse::RecDescent (q{

                        word:       /\\S+/ | backslash
                        line:       prefix word(s) "\\n"
                        backslash:  '\\\\'
                });

Terminal Separators

For the purpose of matching, each terminal in a production is considered to be preceded by a "prefix" - a pattern which must be matched before a token match is attempted. By default, the prefix is optional whitespace (which always matches, at least trivially), but this default may be reset in any production.

The variable $Parse::RecDescent::skip stores the universal prefix, which is the default for all terminal matches in all parsers built with Parse::RecDescent.

The prefix for an individual production can be altered by using the <skip:...> directive (see below).

Actions

An action is a block of Perl code which is to be executed (as the block of a do statement) when the parser reaches that point in a production. The action executes within a special namespace belonging to the active parser, so care must be taken in correctly qualifying variable names (see also Start-up Actions below).

The action is considered to succeed if the final value of the block is defined (that is, if the implied do statement evaluates to a defined value - even one which would be treated as "false"). Note that the value associated with a successful action is also the final value in the block.

An action will fail if its last evaluated value is undef. This is surprisingly easy to accomplish by accident. For instance, here's an infuriating case of an action that makes its production fail, but only when debugging isn't activated:

        description: name rank serial_number
                        { print "Got $item[2] $item[1] ($item[3])\n"
                                if $::debugging
                        }

If $debugging is false, no statement in the block is executed, so the final value is undef, and the entire production fails. The solution is:

        description: name rank serial_number
                        { print "Got $item[2] $item[1] ($item[3])\n"
                                if $::debugging;
                          1;
                        }

Within an action, a number of useful parse-time variables are available in the special parser namespace (there are other variables also accessible, but meddling with them will probably just break your parser. As a general rule, if you avoid referring to unqualified variables - especially those starting with an underscore - inside an action, things should be okay):

@item and %item

The array slice @item[1..$#item] stores the value associated with each item (that is, each subrule, token, or action) in the current production. The analogy is to $1, $2, etc. in a yacc grammar. Note that, for obvious reasons, @item only contains the values of items before the current point in the production.

The first element ($item[0]) stores the name of the current rule being matched.

@item is a standard Perl array, so it can also be indexed with negative numbers, representing the number of items back from the current position in the parse:

        stuff: /various/ bits 'and' pieces "then" data 'end'
                        { print $item[-2] }  # PRINTS data
                                             # (EASIER THAN: $item[6])

The %item hash complements the <@item> array, providing named access to the same item values:

        stuff: /various/ bits 'and' pieces "then" data 'end'
                        { print $item{data}  # PRINTS data
                                             # (EVEN EASIER THAN USING @item)

The results of named subrules are stored in the hash under each subrule's name (including the repetition specifier, if any), whilst all other items are stored under a "named positional" key that indictates their ordinal position within their item type: __STRINGn__, __PATTERNn__, __DIRECTIVEn__, __ACTIONn__:

        stuff: /various/ bits 'and' pieces "then" data 'end' { save }
                        { print $item{__PATTERN1__}, # PRINTS 'various'
                                $item{__STRING2__},  # PRINTS 'then'
                                $item{__ACTION1__},  # PRINTS RETURN
                                                     # VALUE OF save
                        }

If you want proper named access to patterns or literals, you need to turn them into separate rules:

        stuff: various bits 'and' pieces "then" data 'end'
                        { print $item{various}  # PRINTS various
                        }

        various: /various/

The special entry $item{__RULE__} stores the name of the current rule (i.e. the same value as $item[0].

The advantage of using %item, instead of @items is that it removes the need to track items positions that may change as a grammar evolves. For example, adding an interim <skip> directive of action can silently ruin a trailing action, by moving an @item element "down" the array one place. In contrast, the named entry of %item is unaffected by such an insertion.

A limitation of the %item hash is that it only records the last value of a particular subrule. For example:

        range: '(' number '..' number )'
                        { $return = $item{number} }

will return only the value corresponding to the second match of the number subrule. In other words, successive calls to a subrule overwrite the corresponding entry in %item. Once again, the solution is to rename each subrule in its own rule:

        range: '(' from_num '..' to_num )'
                        { $return = $item{from_num} }
        from_num: number
        to_num:   number
@arg and %arg

The array @arg and the hash %arg store any arguments passed to the rule from some other rule (see Subrule argument lists). Changes to the elements of either variable do not propagate back to the calling rule (data can be passed back from a subrule via the $return variable - see next item).

$return

If a value is assigned to $return within an action, that value is returned if the production containing the action eventually matches successfully. Note that setting $return doesn't cause the current production to succeed. It merely tells it what to return if it does succeed. Hence $return is analogous to $$ in a yacc grammar.

If $return is not assigned within a production, the value of the last component of the production (namely: $item[$#item]) is returned if the production succeeds.

$commit

The current state of commitment to the current production (see Directives below).

$skip

The current terminal prefix (see Directives below).

$text

The remaining (unparsed) text. Changes to $text do not propagate out of unsuccessful productions, but do survive successful productions. Hence it is possible to dynamically alter the text being parsed - for example, to provide a #include-like facility:

        hash_include: '#include' filename
                                { $text = ::loadfile($item[2]) . $text }

        filename: '<' /[a-z0-9._-]+/i '>'  { $return = $item[2] }
                | '"' /[a-z0-9._-]+/i '"'  { $return = $item[2] }
$thisline and $prevline

$thisline stores the current line number within the current parse (starting from 1). $prevline stores the line number for the last character which was already successfully parsed (this will be different from $thisline at the end of each line).

For efficiency, $thisline and $prevline are actually tied hashes, and only recompute the required line number when the variable's value is used.

Assignment to $thisline adjusts the line number calculator, so that it believes that the current line number is the value being assigned. Note that this adjustment will be reflected in all subsequent line numbers calculations.

Modifying the value of the variable $text (as in the previous hash_include example, for instance) will confuse the line counting mechanism. To prevent this, you should call Parse::RecDescent::LineCounter::resync($thisline) immediately after any assignment to the variable $text (or, at least, before the next attempt to use $thisline).

Note that if a production fails after assigning to or resync'ing $thisline, the parser's line counter mechanism will usually be corrupted.

Also see the entry for @itempos.

The line number can be set to values other than 1, by calling the start rule with a second argument. For example:

        $parser = new Parse::RecDescent ($grammar);

        $parser->input($text, 10);      # START LINE NUMBERS AT 10
$thiscolumn and $prevcolumn

$thiscolumn stores the current column number within the current line being parsed (starting from 1). $prevcolumn stores the column number of the last character which was actually successfully parsed. Usually $prevcolumn == $thiscolumn-1, but not at the end of lines.

For efficiency, $thiscolumn and $prevcolumn are actually tied hashes, and only recompute the required column number when the variable's value is used.

Assignment to $thiscolumn or $prevcolumn is a fatal error.

Modifying the value of the variable $text (as in the previous hash_include example, for instance) may confuse the column counting mechanism.

Note that $thiscolumn reports the column number before any whitespace that might be skipped before reading a token. Hence if you wish to know where a token started (and ended) use something like this:

        rule: token1 token2 startcol token3 endcol token4
                        { print "token3: columns $item[3] to $item[5]"; }

        startcol: '' { $thiscolumn }    # NEED THE '' TO STEP PAST TOKEN SEP
        endcol:      { $prevcolumn }

Also see the entry for @itempos.

$thisoffset and $prevoffset

$thisoffset stores the offset of the current parsing position within the complete text being parsed (starting from 0). $prevoffset stores the offset of the last character which was actually successfully parsed. In all cases $prevoffset == $thisoffset-1.

For efficiency, $thisoffset and $prevoffset are actually tied hashes, and only recompute the required offset when the variable's value is used.

Assignment to $thisoffset or <$prevoffset> is a fatal error.

Modifying the value of the variable $text will not affect the offset counting mechanism.

Also see the entry for @itempos.

@itempos

The array @itempos stores a hash reference corresponding to each element of @item. The elements of the hash provide the following:

        $itempos[$n]{offset}{from}      # VALUE OF $thisoffset BEFORE $item[$n]
        $itempos[$n]{offset}{to}        # VALUE OF $prevoffset AFTER $item[$n]
        $itempos[$n]{line}{from}        # VALUE OF $thisline BEFORE $item[$n]
        $itempos[$n]{line}{to}          # VALUE OF $prevline AFTER $item[$n]
        $itempos[$n]{column}{from}      # VALUE OF $thiscolumn BEFORE $item[$n]
        $itempos[$n]{column}{to}        # VALUE OF $prevcolumn AFTER $item[$n]

Note that the various $itempos[$n]...{from} values record the appropriate value after any token prefix has been skipped.

Hence, instead of the somewhat tedious and error-prone:

        rule: startcol token1 endcol
              startcol token2 endcol
              startcol token3 endcol
                        { print "token1: columns $item[1]
                                              to $item[3]
                                 token2: columns $item[4]
                                              to $item[6]
                                 token3: columns $item[7]
                                              to $item[9]" }

        startcol: '' { $thiscolumn }    # NEED THE '' TO STEP PAST TOKEN SEP
        endcol:      { $prevcolumn }

it is possible to write:

        rule: token1 token2 token3
                        { print "token1: columns $itempos[1]{column}{from}
                                              to $itempos[1]{column}{to}
                                 token2: columns $itempos[2]{column}{from}
                                              to $itempos[2]{column}{to}
                                 token3: columns $itempos[3]{column}{from}
                                              to $itempos[3]{column}{to}" }

Note however that (in the current implementation) the use of @itempos anywhere in a grammar implies that item positioning information is collected everywhere during the parse. Depending on the grammar and the size of the text to be parsed, this may be prohibitively expensive and the explicit use of $thisline, $thiscolumn, etc. may be a better choice.

$thisparser

A reference to the Parse::RecDescent object through which parsing was initiated.

The value of $thisparser propagates down the subrules of a parse but not back up. Hence, you can invoke subrules from another parser for the scope of the current rule as follows:

        rule: subrule1 subrule2
            | { $thisparser = $::otherparser } <reject>
            | subrule3 subrule4
            | subrule5

The result is that the production calls "subrule1" and "subrule2" of the current parser, and the remaining productions call the named subrules from $::otherparser. Note, however that "Bad Things" will happen if ::otherparser isn't a blessed reference and/or doesn't have methods with the same names as the required subrules!

$thisrule

A reference to the Parse::RecDescent::Rule object corresponding to the rule currently being matched.

$thisprod

A reference to the Parse::RecDescent::Production object corresponding to the production currently being matched.

$score and $score_return

$score stores the best production score to date, as specified by an earlier <score:...> directive. $score_return stores the corresponding return value for the successful production.

See Scored productions.

Warning: the parser relies on the information in the various this... objects in some non-obvious ways. Tinkering with the other members of these objects will probably cause Bad Things to happen, unless you really know what you're doing. The only exception to this advice is that the use of $this...->{local} is always safe.

Start-up Actions

Any actions which appear before the first rule definition in a grammar are treated as "start-up" actions. Each such action is stripped of its outermost brackets and then evaluated (in the parser's special namespace) just before the rules of the grammar are first compiled.

The main use of start-up actions is to declare local variables within the parser's special namespace:

        { my $lastitem = '???'; }

        list: item(s)   { $return = $lastitem }
        item: book      { $lastitem = 'book'; }
              bell      { $lastitem = 'bell'; }
              candle    { $lastitem = 'candle'; }

but start-up actions can be used to execute any valid Perl code within a parser's special namespace.

Start-up actions can appear within a grammar extension or replacement (that is, a partial grammar installed via Parse::RecDescent::Extend() or Parse::RecDescent::Replace() - see Incremental Parsing), and will be executed before the new grammar is installed. Note, however, that a particular start-up action is only ever executed once.

Autoactions

It is sometimes desirable to be able to specify a default action to be taken at the end of every production (for example, in order to easily build a parse tree). If the variable $::RD_AUTOACTION is defined when Parse::RecDescent::new() is called, the contents of that variable are treated as a specification of an action which is to appended to each production in the corresponding grammar. So, for example, to construct a simple parse tree:

    $::RD_AUTOACTION = q { [@item] };

    parser = new Parse::RecDescent (q{
        expression: and_expr '||' expression | and_expr
        and_expr:   not_expr '&&' and_expr   | not_expr
        not_expr:   '!' brack_expr           | brack_expr
        brack_expr: '(' expression ')'       | identifier
        identifier: /[a-z]+/i
        });

which is equivalent to:

    parser = new Parse::RecDescent (q{
        expression: and_expr '||' expression
                        { [@item] }
                  | and_expr
                        { [@item] }
        and_expr:   not_expr '&&' and_expr
                        { [@item] }
                |   not_expr
                        { [@item] }

        not_expr:   '!' brack_expr
                        { [@item] }
                |   brack_expr
                        { [@item] }

        brack_expr: '(' expression ')'
                        { [@item] }
                  | identifier
                        { [@item] }

        identifier: /[a-z]+/i
                        { [@item] }
        });

Alternatively, we could take an object-oriented approach, use different classes for each node (and also eliminating redundant intermediate nodes):

    $::RD_AUTOACTION = q
      { $#item==1 ? $item[1] : new ${"$item[0]_node"} (@item[1..$#item]) };

    parser = new Parse::RecDescent (q{
        expression: and_expr '||' expression | and_expr
        and_expr:   not_expr '&&' and_expr   | not_expr
        not_expr:   '!' brack_expr           | brack_expr
        brack_expr: '(' expression ')'       | identifier
        identifier: /[a-z]+/i
        });

which is equivalent to:

    parser = new Parse::RecDescent (q{
        expression: and_expr '||' expression
                        { new expression_node (@item[1..3]) }
                  | and_expr
        and_expr:   not_expr '&&' and_expr
                        { new and_expr_node (@item[1..3]) }
                |   not_expr

        not_expr:   '!' brack_expr
                        { new not_expr_node (@item[1..2]) }
                |   brack_expr

        brack_expr: '(' expression ')'
                        { new brack_expr_node (@item[1..3]) }
                  | identifier

        identifier: /[a-z]+/i
                        { new identifer_node (@item[1]) }
        });

Note that, if a production already ends in an action, no autoaction is appended to it. For example, in this version:

    $::RD_AUTOACTION = q
      { $#item==1 ? $item[1] : new ${"$item[0]_node"} (@item[1..$#item]) };

    parser = new Parse::RecDescent (q{
        expression: and_expr '&&' expression | and_expr
        and_expr:   not_expr '&&' and_expr   | not_expr
        not_expr:   '!' brack_expr           | brack_expr
        brack_expr: '(' expression ')'       | identifier
        identifier: /[a-z]+/i
                        { new terminal_node($item[1]) }
        });

each identifier match produces a terminal_node object, not an identifier_node object.

A level 1 warning is issued each time an "autoaction" is added to some production.

Autotrees

A commonly needed autoaction is one that builds a parse-tree. It is moderately tricky to set up such an action (which must treat terminals differently from non-terminals), so Parse::RecDescent simplifies the process by providing the <autotree> directive.

If this directive appears at the start of grammar, it causes Parse::RecDescent to insert autoactions at the end of any rule except those which already end in an action. The action inserted depends on whether the production is an intermediate rule (two or more items), or a terminal of the grammar (i.e. a single pattern or string item).

So, for example, the following grammar:

        <autotree>
        file    : command(s)
        command : get | set | vet
        get     : 'get' ident ';'
        set     : 'set' ident 'to' value ';'
        vet     : 'check' ident 'is' value ';'
        ident   : /\w+/
        value   : /\d+/

is equivalent to:

        file    : command(s)                    { bless \%item, $item[0] }
        command : get                           { bless \%item, $item[0] }
                | set                           { bless \%item, $item[0] }
                | vet                           { bless \%item, $item[0] }
        get     : 'get' ident ';'               { bless \%item, $item[0] }
        set     : 'set' ident 'to' value ';'    { bless \%item, $item[0] }
        vet     : 'check' ident 'is' value ';'  { bless \%item, $item[0] }
        ident   : /\w+/          { bless {__VALUE__=>$item[1]}, $item[0] }
        value   : /\d+/          { bless {__VALUE__=>$item[1]}, $item[0] }

Note that each node in the tree is blessed into a class of the same name as the rule itself. This makes it easy to build object-oriented processors for the parse-trees that the grammar produces. Note too that the last two rules produce special objects with the single attribute '__VALUE__'. This is because they consist solely of a single terminal.

This autoaction-ed grammar would then produce a parse tree in a data structure like this:

        {
          file => {
                    command => {
                                 [ get => {
                                            identifier => { __VALUE__ => 'a' },
                                          },
                                   set => {
                                            identifier => { __VALUE__ => 'b' },
                                            value      => { __VALUE__ => '7' },
                                          },
                                   vet => {
                                            identifier => { __VALUE__ => 'b' },
                                            value      => { __VALUE__ => '7' },
                                          },
                                  ],
                               },
                  }
        }

(except, of course, that each nested hash would also be blessed into the appropriate class).

Autostubbing

Normally, if a subrule appears in some production, but no rule of that name is ever defined in the grammar, the production which refers to the non-existent subrule fails immediately. This typically occurs as a result of misspellings, and is a sufficiently common occurance that a warning is generated for such situations.

However, when prototyping a grammar it is sometimes useful to be able to use subrules before a proper specification of them is really possible. For example, a grammar might include a section like:

        function_call: identifier '(' arg(s?) ')'
        identifier: /[a-z]\w*/i

where the possible format of an argument is sufficiently complex that it is not worth specifying in full until the general function call syntax has been debugged. In this situation it is convenient to leave the real rule arg undefined and just slip in a placeholder (or "stub"):

        arg: 'arg'

so that the function call syntax can be tested with dummy input such as:

        f0()
        f1(arg)
        f2(arg arg)
        f3(arg arg arg)

et cetera.

Early in prototyping, many such "stubs" may be required, so Parse::RecDescent provides a means of automating their definition. If the variable $::RD_AUTOSTUB is defined when a parser is built, a subrule reference to any non-existent rule (say, sr), causes a "stub" rule of the form:

        sr: 'sr'

to be automatically defined in the generated parser. A level 1 warning is issued for each such "autostubbed" rule.

Hence, with $::AUTOSTUB defined, it is possible to only partially specify a grammar, and then "fake" matches of the unspecified (sub)rules by just typing in their name.

Look-ahead

If a subrule, token, or action is prefixed by "...", then it is treated as a "look-ahead" request. That means that the current production can (as usual) only succeed if the specified item is matched, but that the matching does not consume any of the text being parsed. This is very similar to the /(?=...)/ look-ahead construct in Perl patterns. Thus, the rule:

        inner_word: word ...word

will match whatever the subrule "word" matches, provided that match is followed by some more text which subrule "word" would also match (although this second substring is not actually consumed by "inner_word")

Likewise, a "...!" prefix, causes the following item to succeed (without consuming any text) if and only if it would normally fail. Hence, a rule such as:

        identifier: ...!keyword ...!'_' /[A-Za-z_]\w*/

matches a string of characters which satisfies the pattern /[A-Za-z_]\w*/, but only if the same sequence of characters would not match either subrule "keyword" or the literal token '_'.

Sequences of look-ahead prefixes accumulate, multiplying their positive and/or negative senses. Hence:

        inner_word: word ...!......!word

is exactly equivalent the the original example above (a warning is issued in cases like these, since they often indicate something left out, or misunderstood).

Note that actions can also be treated as look-aheads. In such cases, the state of the parser text (in the local variable $text) after the look-ahead action is guaranteed to be identical to its state before the action, regardless of how it's changed within the action (unless you actually undefine $text, in which case you get the disaster you deserve :-).

Directives

Directives are special pre-defined actions which may be used to alter the behaviour of the parser. There are currently eighteen directives: <commit>, <uncommit>, <reject>, <score>, <autoscore>, <skip>, <resync>, <error>, <rulevar>, <matchrule>, <leftop>, <rightop>, <defer>, <nocheck>, <perl_quotelike>, <perl_codeblock>, <perl_variable>, and <token>.

Committing and uncommitting

The <commit> and <uncommit> directives permit the recursive descent of the parse tree to be pruned (or "cut") for efficiency. Within a rule, a <commit> directive instructs the rule to ignore subsequent productions if the current production fails. For example:

        command: 'find' <commit> filename
               | 'open' <commit> filename
               | 'move' filename filename

Clearly, if the leading token 'find' is matched in the first production but that production fails for some other reason, then the remaining productions cannot possibly match. The presence of the <commit> causes the "command" rule to fail immediately if an invalid "find" command is found, and likewise if an invalid "open" command is encountered.

It is also possible to revoke a previous commitment. For example:

        if_statement: 'if' <commit> condition
                                'then' block <uncommit>
                                'else' block
                    | 'if' <commit> condition
                                'then' block

In this case, a failure to find an "else" block in the first production shouldn't preclude trying the second production, but a failure to find a "condition" certainly should.

As a special case, any production in which the first item is an <uncommit> immediately revokes a preceding <commit> (even though the production would not otherwise have been tried). For example, in the rule:

        request: 'explain' expression
               | 'explain' <commit> keyword
               | 'save'
               | 'quit'
               | <uncommit> term '?'

if the text being matched was "explain?", and the first two productions failed, then the <commit> in production two would cause productions three and four to be skipped, but the leading <uncommit> in the production five would allow that production to attempt a match.

Note in the preceding example, that the <commit> was only placed in production two. If production one had been:

        request: 'explain' <commit> expression

then production two would be (inappropriately) skipped if a leading "explain..." was encountered.

Both <commit> and <uncommit> directives always succeed, and their value is always 1.

Rejecting a production

The <reject> directive immediately causes the current production to fail (it is exactly equivalent to, but more obvious than, the action {undef}). A <reject> is useful when it is desirable to get the side effects of the actions in one production, without prejudicing a match by some other production later in the rule. For example, to insert tracing code into the parse:

        complex_rule: { print "In complex rule...\n"; } <reject>

        complex_rule: simple_rule '+' 'i' '*' simple_rule
                    | 'i' '*' simple_rule
                    | simple_rule

It is also possible to specify a conditional rejection, using the form <reject:condition>, which only rejects if the specified condition is true. This form of rejection is exactly equivalent to the action {(condition)?undef:1}>. For example:

        command: save_command
               | restore_command
               | <reject: defined $::tolerant> { exit }
               | <error: Unknown command. Ignored.>

A <reject> directive never succeeds (and hence has no associated value). A conditional rejection may succeed (if its condition is not satisfied), in which case its value is 1.

As an extra optimization, Parse::RecDescent ignores any production which begins with an unconditional <reject> directive, since any such production can never successfully match or have any useful side-effects. A level 1 warning is issued in all such cases.

Note that productions beginning with conditional <reject:...> directives are never "optimized away" in this manner, even if they are always guaranteed to fail (for example: <reject:1>)

Due to the way grammars are parsed, there is a minor restriction on the condition of a conditional <reject:...>: it cannot contain any raw '<' or '>' characters. For example:

        line: cmd <reject: $thiscolumn > max> data

results in an error when a parser is built from this grammar (since the grammar parser has no way of knowing whether the first > is a "less than" or the end of the <reject:...>.

To overcome this problem, put the condition inside a do{} block:

        line: cmd <reject: do{$thiscolumn > max}> data

Note that the same problem may occur in other directives that take arguments. The same solution will work in all cases.

Skipping between terminals

The <skip> directive enables the terminal prefix used in a production to be changed. For example:

        OneLiner: Command <skip:'[ \t]*'> Arg(s) /;/

causes only blanks and tabs to be skipped before terminals in the Arg subrule (and any of its subrules>, and also before the final /;/ terminal. Once the production is complete, the previous terminal prefix is reinstated. Note that this implies that distinct productions of a rule must reset their terminal prefixes individually.

The <skip> directive evaluates to the previous terminal prefix, so it's easy to reinstate a prefix later in a production:

        Command: <skip:","> CSV(s) <skip:$item[1]> Modifier

The value specified after the colon is interpolated into a pattern, so all of the following are equivalent (though their efficiency increases down the list):

        <skip: "$colon|$comma">   # ASSUMING THE VARS HOLD THE OBVIOUS VALUES
        <skip: ':|,'>
        <skip: q{[:,]}>

        <skip: qr/[:,]/>

There is no way of directly setting the prefix for an entire rule, except as follows:

        Rule: <skip: '[ \t]*'> Prod1
            | <skip: '[ \t]*'> Prod2a Prod2b
            | <skip: '[ \t]*'> Prod3

or, better:

        Rule: <skip: '[ \t]*'>
            (
                Prod1
              | Prod2a Prod2b
              | Prod3
            )

Note: Up to release 1.51 of Parse::RecDescent, an entirely different mechanism was used for specifying terminal prefixes. The current method is not backwards-compatible with that early approach. The current approach is stable and will not to change again.

Resynchronization

The <resync> directive provides a visually distinctive means of consuming some of the text being parsed, usually to skip an erroneous input. In its simplest form <resync> simply consumes text up to and including the next newline ("\n") character, succeeding only if the newline is found, in which case it causes its surrounding rule to return zero on success.

In other words, a <resync> is exactly equivalent to the token /[^\n]*\n/ followed by the action { $return = 0 } (except that productions beginning with a <resync> are ignored when generating error messages). A typical use might be:

        script : command(s)
        command: save_command
               | restore_command
               | <resync> # TRY NEXT LINE, IF POSSIBLE

It is also possible to explicitly specify a resynchronization pattern, using the <resync:pattern> variant. This version succeeds only if the specified pattern matches (and consumes) the parsed text. In other words, <resync:pattern> is exactly equivalent to the token /pattern/ (followed by a { $return = 0 } action). For example, if commands were terminated by newlines or semi-colons:

        command: save_command
               | restore_command
               | <resync:[^;\n]*[;\n]>

The value of a successfully matched <resync> directive (of either type) is the text that it consumed. Note, however, that since the directive also sets $return, a production consisting of a lone <resync> succeeds but returns the value zero (which a calling rule may find useful to distinguish between "true" matches and "tolerant" matches). Remember that returning a zero value indicates that the rule succeeded (since only an undef denotes failure within Parse::RecDescent parsers.

Error handling

The <error> directive provides automatic or user-defined generation of error messages during a parse. In its simplest form <error> prepares an error message based on the mismatch between the last item expected and the text which cause it to fail. For example, given the rule:

        McCoy: curse ',' name ', I'm a doctor, not a' a_profession '!'
             | pronoun 'dead,' name '!'
             | <error>

the following strings would produce the following messages:

"Amen, Jim!"
       ERROR (line 1): Invalid McCoy: Expected curse or pronoun
                       not found
"Dammit, Jim, I'm a doctor!"
       ERROR (line 1): Invalid McCoy: Expected ", I'm a doctor, not a"
                       but found ", I'm a doctor!" instead
"He's dead,\n"
       ERROR (line 2): Invalid McCoy: Expected name not found
"He's alive!"
       ERROR (line 1): Invalid McCoy: Expected 'dead,' but found
                       "alive!" instead
"Dammit, Jim, I'm a doctor, not a pointy-eared Vulcan!"
       ERROR (line 1): Invalid McCoy: Expected a profession but found
                       "pointy-eared Vulcan!" instead

Note that, when autogenerating error messages, all underscores in any rule name used in a message are replaced by single spaces (for example "a_production" becomes "a production"). Judicious choice of rule names can therefore considerably improve the readability of automatic error messages (as well as the maintainability of the original grammar).

If the automatically generated error is not sufficient, it is possible to provide an explicit message as part of the error directive. For example:

        Spock: "Fascinating ',' (name | 'Captain') '.'
             | "Highly illogical, doctor."
             | <error: He never said that!>

which would result in all failures to parse a "Spock" subrule printing the following message:

       ERROR (line <N>): Invalid Spock:  He never said that!

The error message is treated as a "qq{...}" string and interpolated when the error is generated (not when the directive is specified!). Hence:

        <error: Mystical error near "$text">

would correctly insert the ambient text string which caused the error.

There are two other forms of error directive: <error?> and <error?: msg>. These behave just like <error> and <error: msg> respectively, except that they are only triggered if the rule is "committed" at the time they are encountered. For example:

        Scotty: "Ya kenna change the Laws of Phusics," <commit> name
              | name <commit> ',' 'she's goanta blaw!'
              | <error?>

will only generate an error for a string beginning with "Ya kenna change the Laws o' Phusics," or a valid name, but which still fails to match the corresponding production. That is, $parser->Scotty("Aye, Cap'ain") will fail silently (since neither production will "commit" the rule on that input), whereas $parser->Scotty("Mr Spock, ah jest kenna do'ut!") will fail with the error message:

       ERROR (line 1): Invalid Scotty: expected 'she's goanta blaw!'
                       but found 'I jest kenna do'ut!' instead.

since in that case the second production would commit after matching the leading name.

Note that to allow this behaviour, all <error> directives which are the first item in a production automatically uncommit the rule just long enough to allow their production to be attempted (that is, when their production fails, the commitment is reinstated so that subsequent productions are skipped).

In order to permanently uncommit the rule before an error message, it is necessary to put an explicit <uncommit> before the <error>. For example:

        line: 'Kirk:'  <commit> Kirk
            | 'Spock:' <commit> Spock
            | 'McCoy:' <commit> McCoy
            | <uncommit> <error?> <reject>
            | <resync>

Error messages generated by the various <error...> directives are not displayed immediately. Instead, they are "queued" in a buffer and are only displayed once parsing ultimately fails. Moreover, <error...> directives that cause one production of a rule to fail are automatically removed from the message queue if another production subsequently causes the entire rule to succeed. This means that you can put <error...> directives wherever useful diagnosis can be done, and only those associated with actual parser failure will ever be displayed. Also see Gotchas.

As a general rule, the most useful diagnostics are usually generated either at the very lowest level within the grammar, or at the very highest. A good rule of thumb is to identify those subrules which consist mainly (or entirely) of terminals, and then put an <error...> directive at the end of any other rule which calls one or more of those subrules.

There is one other situation in which the output of the various types of error directive is suppressed; namely, when the rule containing them is being parsed as part of a "look-ahead" (see Look-ahead). In this case, the error directive will still cause the rule to fail, but will do so silently.

An unconditional <error> directive always fails (and hence has no associated value). This means that encountering such a directive always causes the production containing it to fail. Hence an <error> directive will inevitably be the last (useful) item of a rule (a level 3 warning is issued if a production contains items after an unconditional <error> directive).

An <error?> directive will succeed (that is: fail to fail :-), if the current rule is uncommitted when the directive is encountered. In that case the directive's associated value is zero. Hence, this type of error directive can be used before the end of a production. For example:

        command: 'do' <commit> something
               | 'report' <commit> something
               | <error?: Syntax error> <error: Unknown command>

Warning: The <error?> directive does not mean "always fail (but do so silently unless committed)". It actually means "only fail (and report) if committed, otherwise succeed". To achieve the "fail silently if uncommitted" semantics, it is necessary to use:

        rule: item <commit> item(s)
            | <error?> <reject>      # FAIL SILENTLY UNLESS COMMITTED

However, because people seem to expect a lone <error?> directive to work like this:

        rule: item <commit> item(s)
            | <error?: Error message if committed>
            | <error:  Error message if uncommitted>

Parse::RecDescent automatically appends a <reject> directive if the <error?> directive is the only item in a production. A level 2 warning (see below) is issued when this happens.

The level of error reporting during both parser construction and parsing is controlled by the presence or absence of four global variables: $::RD_ERRORS, $::RD_WARN, $::RD_HINT, and <$::RD_TRACE>. If $::RD_ERRORS is defined (and, by default, it is) then fatal errors are reported.

Whenever $::RD_WARN is defined, certain non-fatal problems are also reported. Warnings have an associated "level": 1, 2, or 3. The higher the level, the more serious the warning. The value of the corresponding global variable ($::RD_WARN) determines the lowest level of warning to be displayed. Hence, to see all warnings, set $::RD_WARN to 1. To see only the most serious warnings set $::RD_WARN to 3. By default $::RD_WARN is initialized to 3, ensuring that serious but non-fatal errors are automatically reported.

See "DIAGNOSTICS" for a list of the varous error and warning messages that Parse::RecDescent generates when these two variables are defined.

Defining any of the remaining variables (which are not defined by default) further increases the amount of information reported. Defining $::RD_HINT causes the parser generator to offer more detailed analyses and hints on both errors and warnings. Note that setting $::RD_HINT at any point automagically sets $::RD_WARN to 1.

Defining $::RD_TRACE causes the parser generator and the parser to report their progress to STDERR in excruciating detail (although, without hints unless $::RD_HINT is separately defined). This detail can be moderated in only one respect: if $::RD_TRACE has an integer value (N) greater than 1, only the N characters of the "current parsing context" (that is, where in the input string we are at any point in the parse) is reported at any time. > $::RD_TRACE is mainly useful for debugging a grammar that isn't behaving as you expected it to. To this end, if $::RD_TRACE is defined when a parser is built, any actual parser code which is generated is also written to a file named "RD_TRACE" in the local directory.

Note that the four variables belong to the "main" package, which makes them easier to refer to in the code controlling the parser, and also makes it easy to turn them into command line flags ("-RD_ERRORS", "-RD_WARN", "-RD_HINT", "-RD_TRACE") under perl -s.

Specifying local variables

It is occasionally convenient to specify variables which are local to a single rule. This may be achieved by including a <rulevar:...> directive anywhere in the rule. For example:

        markup: <rulevar: $tag>
        markup: tag {($tag=$item[1]) =~ s/^<|>$//g} body[$tag]

The example <rulevar: $tag> directive causes a "my" variable named $tag to be declared at the start of the subroutine implementing the markup rule (that is, before the first production, regardless of where in the rule it is specified).

Specifically, any directive of the form: <rulevar:text> causes a line of the form my text; to be added at the beginning of the rule subroutine, immediately after the definitions of the following local variables:

        $thisparser     $commit
        $thisrule       @item
        $thisline       @arg
        $text           %arg

This means that the following <rulevar> directives work as expected:

        <rulevar: $count = 0 >
        <rulevar: $firstarg = $arg[0] || '' >
        <rulevar: $myItems = \@item >
        <rulevar: @context = ( $thisline, $text, @arg ) >
        <rulevar: ($name,$age) = $arg{"name","age"} >

If a variable that is also visible to subrules is required, it needs to be local'd, not my'd. rulevar defaults to my, but if local is explicitly specified:

        <rulevar: local $count = 0 >

then a local-ized variable is declared instead, and will be available within subrules.

Note however that, because all such variables are "my" variables, their values do not persist between match attempts on a given rule. To preserve values between match attempts, values can be stored within the "local" member of the $thisrule object:

        countedrule: { $thisrule->{"local"}{"count"}++ }
                     <reject>
                   | subrule1
                   | subrule2
                   | <reject: $thisrule->{"local"}{"count"} == 1>
                     subrule3

When matching a rule, each <rulevar> directive is matched as if it were an unconditional <reject> directive (that is, it causes any production in which it appears to immediately fail to match). For this reason (and to improve readability) it is usual to specify any <rulevar> directive in a separate production at the start of the rule (this has the added advantage that it enables Parse::RecDescent to optimize away such productions, just as it does for the <reject> directive).

Dynamically matched rules

Because regexes and double-quoted strings are interpolated, it is relatively easy to specify productions with "context sensitive" tokens. For example:

        command:  keyword  body  "end $item[1]"

which ensures that a command block is bounded by a "<keyword>...end <same keyword>" pair.

Building productions in which subrules are context sensitive is also possible, via the <matchrule:...> directive. This directive behaves identically to a subrule item, except that the rule which is invoked to match it is determined by the string specified after the colon. For example, we could rewrite the command rule like this:

        command:  keyword  <matchrule:body>  "end $item[1]"

Whatever appears after the colon in the directive is treated as an interpolated string (that is, as if it appeared in qq{...} operator) and the value of that interpolated string is the name of the subrule to be matched.

Of course, just putting a constant string like body in a <matchrule:...> directive is of little interest or benefit. The power of directive is seen when we use a string that interpolates to something interesting. For example:

        command:        keyword <matchrule:$item[1]_body> "end $item[1]"
        keyword:        'while' | 'if' | 'function'
        while_body:     condition block
        if_body:        condition block ('else' block)(?)
        function_body:  arglist block

Now the command rule selects how to proceed on the basis of the keyword that is found. It is as if command were declared:

        command:        'while'    while_body    "end while"
               |        'if'       if_body       "end if"
               |        'function' function_body "end function"

When a <matchrule:...> directive is used as a repeated subrule, the rule name expression is "late-bound". That is, the name of the rule to be called is re-evaluated each time a match attempt is made. Hence, the following grammar:

        { $::species = 'dogs' }

        pair:   'two' <matchrule:$::species>(s)
        dogs:   /dogs/ { $::species = 'cats' }

        cats:   /cats/

will match the string "two dogs cats cats" completely, whereas it will only match the string "two dogs dogs dogs" up to the eighth letter. If the rule name were "early bound" (that is, evaluated only the first time the directive is encountered in a production), the reverse behaviour would be expected.

Note that the matchrule directive takes a string that is to be treated as a rule name, not as a rule invocation. That is, it's like a Perl symbolic reference, not an eval. Just as you can say:

        $subname = 'foo';

        # and later...

        &{$foo}(@args);

but not:

        $subname = 'foo(@args)';

        # and later...

        &{$foo};

likewise you can say:

        $rulename = 'foo';

        # and in the grammar...

        <matchrule:$rulename>[@args]

but not:

        $rulename = 'foo[@args]';

        # and in the grammar...

        <matchrule:$rulename>
Deferred actions

The <defer:...> directive is used to specify an action to be performed when (and only if!) the current production ultimately succeeds.

Whenever a <defer:...> directive appears, the code it specifies is converted to a closure (an anonymous subroutine reference) which is queued within the active parser object. Note that, because the deferred code is converted to a closure, the values of any "local" variable (such as $text, <@item>, etc.) are preserved until the deferred code is actually executed.

If the parse ultimately succeeds and the production in which the <defer:...> directive was evaluated formed part of the successful parse, then the deferred code is executed immediately before the parse returns. If however the production which queued a deferred action fails, or one of the higher-level rules which called that production fails, then the deferred action is removed from the queue, and hence is never executed.

For example, given the grammar:

        sentence: noun trans noun
                | noun intrans
        noun:     'the dog'
                        { print "$item[1]\t(noun)\n" }
            |     'the meat'
                        { print "$item[1]\t(noun)\n" }

        trans:    'ate'
                        { print "$item[1]\t(transitive)\n" }

        intrans:  'ate'
                        { print "$item[1]\t(intransitive)\n" }
               |  'barked'
                        { print "$item[1]\t(intransitive)\n" }

then parsing the sentence "the dog ate" would produce the output:

        the dog  (noun)
        ate      (transitive)
        the dog  (noun)
        ate      (intransitive)

This is because, even though the first production of sentence ultimately fails, its initial subrules noun and trans do match, and hence they execute their associated actions. Then the second production of sentence succeeds, causing the actions of the subrules noun and intrans to be executed as well.

On the other hand, if the actions were replaced by <defer:...> directives:

        sentence: noun trans noun
                | noun intrans
        noun:     'the dog'
                        <defer: print "$item[1]\t(noun)\n" >
            |     'the meat'
                        <defer: print "$item[1]\t(noun)\n" >
        trans:    'ate'
                        <defer: print "$item[1]\t(transitive)\n" >
        intrans:  'ate'
                        <defer: print "$item[1]\t(intransitive)\n" >
               |  'barked'
                        <defer: print "$item[1]\t(intransitive)\n" >

the output would be:

        the dog  (noun)
        ate      (intransitive)

since deferred actions are only executed if they were evaluated in a production which ultimately contributes to the successful parse.

In this case, even though the first production of sentence caused the subrules noun and trans to match, that production ultimately failed and so the deferred actions queued by those subrules were subsequently disgarded. The second production then succeeded, causing the entire parse to succeed, and so the deferred actions queued by the (second) match of the noun subrule and the subsequent match of intrans are preserved and eventually executed.

Deferred actions provide a means of improving the performance of a parser, by only executing those actions which are part of the final parse-tree for the input data.

Alternatively, deferred actions can be viewed as a mechanism for building (and executing) a customized subroutine corresponding to the given input data, much in the same way that autoactions (see Autoactions) can be used to build a customized data structure for specific input.

Whether or not the action it specifies is ever executed, a <defer:...> directive always succeeds, returning the number of deferred actions currently queued at that point.

Parsing Perl

Parse::RecDescent provides limited support for parsing subsets of Perl, namely: quote-like operators, Perl variables, and complete code blocks.

The <perl_quotelike> directive can be used to parse any Perl quote-like operator: 'a string', m/a pattern/, tr{ans}{lation}, etc. It does this by calling Text::Balanced::quotelike().

If a quote-like operator is found, a reference to an array of eight elements is returned. Those elements are identical to the last eight elements returned by Text::Balanced::extract_quotelike() in an array context, namely:

[0]

the name of the quotelike operator -- 'q', 'qq', 'm', 's', 'tr' -- if the operator was named; otherwise undef,

[1]

the left delimiter of the first block of the operation,

[2]

the text of the first block of the operation (that is, the contents of a quote, the regex of a match, or substitution or the target list of a translation),

[3]

the right delimiter of the first block of the operation,

[4]

the left delimiter of the second block of the operation if there is one (that is, if it is a s, tr, or y); otherwise undef,

[5]

the text of the second block of the operation if there is one (that is, the replacement of a substitution or the translation list of a translation); otherwise undef,

[6]

the right delimiter of the second block of the operation (if any); otherwise undef,

[7]

the trailing modifiers on the operation (if any); otherwise undef.

If a quote-like expression is not found, the directive fails with the usual undef value.

The <perl_variable> directive can be used to parse any Perl variable: $scalar, @array, %hash, $ref->{field}[$index], etc. It does this by calling Text::Balanced::extract_variable().

If the directive matches text representing a valid Perl variable specification, it returns that text. Otherwise it fails with the usual undef value.

The <perl_codeblock> directive can be used to parse curly-brace-delimited block of Perl code, such as: { $a = 1; f() =~ m/pat/; }. It does this by calling Text::Balanced::extract_codeblock().

If the directive matches text representing a valid Perl code block, it returns that text. Otherwise it fails with the usual undef value.

You can also tell it what kind of brackets to use as the outermost delimiters. For example:

        arglist: <perl_codeblock ()>

causes an arglist to match a perl code block whose outermost delimiters are (...) (rather than the default {...}).

Constructing tokens

Eventually, Parse::RecDescent will be able to parse tokenized input, as well as ordinary strings. In preparation for this joyous day, the <token:...> directive has been provided. This directive creates a token which will be suitable for input to a Parse::RecDescent parser (when it eventually supports tokenized input).

The text of the token is the value of the immediately preceding item in the production. A <token:...> directive always succeeds with a return value which is the hash reference that is the new token. It also sets the return value for the production to that hash ref.

The <token:...> directive makes it easy to build a Parse::RecDescent-compatible lexer in Parse::RecDescent:

        my $lexer = new Parse::RecDescent q
        {
                lex:    token(s)

                token:  /a\b/                      <token:INDEF>
                     |  /the\b/                    <token:DEF>
                     |  /fly\b/                    <token:NOUN,VERB>
                     |  /[a-z]+/i { lc $item[1] }  <token:ALPHA>
                     |  <error: Unknown token>

        };

which will eventually be able to be used with a regular Parse::RecDescent grammar:

        my $parser = new Parse::RecDescent q
        {
                startrule: subrule1 subrule 2

                # ETC...
                        };

either with a pre-lexing phase:

        $parser->startrule( $lexer->lex($data) );

or with a lex-on-demand approach:

        $parser->startrule( sub{$lexer->token(\$data)} );

But at present, only the <token:...> directive is actually implemented. The rest is vapourware.

Specifying operations

One of the commonest requirements when building a parser is to specify binary operators. Unfortunately, in a normal grammar, the rules for such things are awkward:

        disjunction:    conjunction ('or' conjunction)(s?)
                                { $return = [ $item[1], @{$item[2]} ] }
        conjunction:    atom ('and' atom)(s?)
                                { $return = [ $item[1], @{$item[2]} ] }

or inefficient:

        disjunction:    conjunction 'or' disjunction
                                { $return = [ $item[1], @{$item[2]} ] }
                   |    conjunction
                                { $return = [ $item[1] ] }

        conjunction:    atom 'and' conjunction
                                { $return = [ $item[1], @{$item[2]} ] }
                   |    atom
                                { $return = [ $item[1] ] }

and either way is ugly and hard to get right.

The <leftop:...> and <rightop:...> directives provide an easier way of specifying such operations. Using <leftop:...> the above examples become:

        disjunction:    <leftop: conjunction 'or' conjunction>
        conjunction:    <leftop: atom 'and' atom>

The <leftop:...> directive specifies a left-associative binary operator. It is specified around three other grammar elements (typically subrules or terminals), which match the left operand, the operator itself, and the right operand respectively.

A <leftop:...> directive such as:

        disjunction:    <leftop: conjunction 'or' conjunction>

is converted to the following:

        disjunction:    ( conjunction ('or' conjunction)(s?)
                                { $return = [ $item[1], @{$item[2]} ] } )

In other words, a <leftop:...> directive matches the left operand followed by zero or more repetitions of both the operator and the right operand. It then flattens the matched items into an anonymous array which becomes the (single) value of the entire <leftop:...> directive.

For example, an <leftop:...> directive such as:

        output:  <leftop: ident '<<' expr >

when given a string such as:

        cout << var << "str" << 3

would match, and $item[1] would be set to:

        [ 'cout', 'var', '"str"', '3' ]

In other words:

        output:  <leftop: ident '<<' expr >

is equivalent to a left-associative operator:

        output:  ident                                  { $return = [$item[1]]       }
              |  ident '<<' expr                        { $return = [@item[1,3]]     }
              |  ident '<<' expr '<<' expr              { $return = [@item[1,3,5]]   }
              |  ident '<<' expr '<<' expr '<<' expr    { $return = [@item[1,3,5,7]] }
              #  ...etc...

Similarly, the <rightop:...> directive takes a left operand, an operator, and a right operand:

        assign:  <rightop: var '=' expr >

and converts them to:

        assign:  ( (var '=' {$return=$item[1]})(s?) expr
                                { $return = [ @{$item[1]}, $item[2] ] } )

which is equivalent to a right-associative operator:

        assign:  var                            { $return = [$item[1]]       }
              |  var '=' expr                   { $return = [@item[1,3]]     }
              |  var '=' var '=' expr           { $return = [@item[1,3,5]]   }
              |  var '=' var '=' var '=' expr   { $return = [@item[1,3,5,7]] }
              #  ...etc...

Note that for both the <leftop:...> and <rightop:...> directives, the directive does not normally return the operator itself, just a list of the operands involved. This is particularly handy for specifying lists:

        list: '(' <leftop: list_item ',' list_item> ')'
                        { $return = $item[2] }

There is, however, a problem: sometimes the operator is itself significant. For example, in a Perl list a comma and a => are both valid separators, but the => has additional stringification semantics. Hence it's important to know which was used in each case.

To solve this problem the <leftop:...> and <rightop:...> directives do return the operator(s) as well, under two circumstances. The first case is where the operator is specified as a subrule. In that instance, whatever the operator matches is returned (on the assumption that if the operator is important enough to have its own subrule, then it's important enough to return).

The second case is where the operator is specified as a regular expression. In that case, if the first bracketed subpattern of the regular expression matches, that matching value is returned (this is analogous to the behaviour of the Perl split function, except that only the first subpattern is returned).

In other words, given the input:

        ( a=>1, b=>2 )

the specifications:

        list:      '('  <leftop: list_item separator list_item>  ')'
        separator: ',' | '=>'

or:

        list:      '('  <leftop: list_item /(,|=>)/ list_item>  ')'

cause the list separators to be interleaved with the operands in the anonymous array in $item[2]:

        [ 'a', '=>', '1', ',', 'b', '=>', '2' ]

But the following version:

        list:      '('  <leftop: list_item /,|=>/ list_item>  ')'

returns only the operators:

        [ 'a', '1', 'b', '2' ]

Of course, none of the above specifications handle the case of an empty list, since the <leftop:...> and <rightop:...> directives require at least a single right or left operand to match. To specify that the operator can match "trivially", it's necessary to add a (?) qualifier to the directive:

        list:      '('  <leftop: list_item /(,|=>)/ list_item>(?)  ')'

Note that in almost all the above examples, the first and third arguments of the <leftop:...> directive were the same subrule. That is because <leftop:...>'s are frequently used to specify "separated" lists of the same type of item. To make such lists easier to specify, the following syntax:

        list:   element(s /,/)

is exactly equivalent to:

        list:   <leftop: element /,/ element>

Note that the separator must be specified as a raw pattern (i.e. not a string or subrule).

Scored productions

By default, Parse::RecDescent grammar rules always accept the first production that matches the input. But if two or more productions may potentially match the same input, choosing the first that does so may not be optimal.

For example, if you were parsing the sentence "time flies like an arrow", you might use a rule like this:

        sentence: verb noun preposition article noun { [@item] }
                | adjective noun verb article noun   { [@item] }
                | noun verb preposition article noun { [@item] }

Each of these productions matches the sentence, but the third one is the most likely interpretation. However, if the sentence had been "fruit flies like a banana", then the second production is probably the right match.

To cater for such situtations, the <score:...> can be used. The directive is equivalent to an unconditional <reject>, except that it allows you to specify a "score" for the current production. If that score is numerically greater than the best score of any preceding production, the current production is cached for later consideration. If no later production matches, then the cached production is treated as having matched, and the value of the item immediately before its <score:...> directive is returned as the result.

In other words, by putting a <score:...> directive at the end of each production, you can select which production matches using criteria other than specification order. For example:

        sentence: verb noun preposition article noun { [@item] } <score: sensible(@item)>
                | adjective noun verb article noun   { [@item] } <score: sensible(@item)>
                | noun verb preposition article noun { [@item] } <score: sensible(@item)>

Now, when each production reaches its respective <score:...> directive, the subroutine sensible will be called to evaluate the matched items (somehow). Once all productions have been tried, the one which sensible scored most highly will be the one that is accepted as a match for the rule.

The variable $score always holds the current best score of any production, and the variable $score_return holds the corresponding return value.

As another example, the following grammar matches lines that may be separated by commas, colons, or semi-colons. This can be tricky if a colon-separated line also contains commas, or vice versa. The grammar resolves the ambiguity by selecting the rule that results in the fewest fields:

        line: seplist[sep=>',']  <score: -@{$item[1]}>
            | seplist[sep=>':']  <score: -@{$item[1]}>
            | seplist[sep=>" "]  <score: -@{$item[1]}>

        seplist: <skip:""> <leftop: /[^$arg{sep}]*/ "$arg{sep}" /[^$arg{sep}]*/>

Note the use of negation within the <score:...> directive to ensure that the seplist with the most items gets the lowest score.

As the above examples indicate, it is often the case that all productions in a rule use exactly the same <score:...> directive. It is tedious to have to repeat this identical directive in every production, so Parse::RecDescent also provides the <autoscore:...> directive.

If an <autoscore:...> directive appears in any production of a rule, the code it specifies is used as the scoring code for every production of that rule, except productions that already end with an explicit <score:...> directive. Thus the rules above could be rewritten:

        line: <autoscore: -@{$item[1]}>
        line: seplist[sep=>',']
            | seplist[sep=>':']
            | seplist[sep=>" "]

        sentence: <autoscore: sensible(@item)>
                | verb noun preposition article noun { [@item] }
                | adjective noun verb article noun   { [@item] }
                | noun verb preposition article noun { [@item] }

Note that the <autoscore:...> directive itself acts as an unconditional <reject>, and (like the <rulevar:...> directive) is pruned at compile-time wherever possible.

Dispensing with grammar checks

During the compilation phase of parser construction, Parse::RecDescent performs a small number of checks on the grammar it's given. Specifically it checks that the grammar is not left-recursive, that there are no "insatiable" constructs of the form:

        rule: subrule(s) subrule

and that there are no rules missing (i.e. referred to, but never defined).

These checks are important during development, but can slow down parser construction in stable code. So Parse::RecDescent provides the <nocheck> directive to turn them off. The directive can only appear before the first rule definition, and switches off checking throughout the rest of the current grammar.

Typically, this directive would be added when a parser has been thoroughly tested and is ready for release.

Subrule argument lists

It is occasionally useful to pass data to a subrule which is being invoked. For example, consider the following grammar fragment:

        classdecl: keyword decl
        keyword:   'struct' | 'class';

        decl:      # WHATEVER

The decl rule might wish to know which of the two keywords was used (since it may affect some aspect of the way the subsequent declaration is interpreted). Parse::RecDescent allows the grammar designer to pass data into a rule, by placing that data in an argument list (that is, in square brackets) immediately after any subrule item in a production. Hence, we could pass the keyword to decl as follows:

        classdecl: keyword decl[ $item[1] ]
        keyword:   'struct' | 'class';

        decl:      # WHATEVER

The argument list can consist of any number (including zero!) of comma-separated Perl expressions. In other words, it looks exactly like a Perl anonymous array reference. For example, we could pass the keyword, the name of the surrounding rule, and the literal 'keyword' to decl like so:

        classdecl: keyword decl[$item[1],$item[0],'keyword']
        keyword:   'struct' | 'class';

        decl:      # WHATEVER

Within the rule to which the data is passed (decl in the above examples) that data is available as the elements of a local variable @arg. Hence decl might report its intentions as follows:

        classdecl: keyword decl[$item[1],$item[0],'keyword']
        keyword:   'struct' | 'class';

        decl:      { print "Declaring $arg[0] (a $arg[2])\n";
                     print "(this rule called by $arg[1])" }

Subrule argument lists can also be interpreted as hashes, simply by using the local variable %arg instead of @arg. Hence we could rewrite the previous example:

        classdecl: keyword decl[keyword => $item[1],
                                caller  => $item[0],
                                type    => 'keyword']
        keyword:   'struct' | 'class';

        decl:      { print "Declaring $arg{keyword} (a $arg{type})\n";
                     print "(this rule called by $arg{caller})" }

Both @arg and %arg are always available, so the grammar designer may choose whichever convention (or combination of conventions) suits best.

Subrule argument lists are also useful for creating "rule templates" (especially when used in conjunction with the <matchrule:...> directive). For example, the subrule:

        list:     <matchrule:$arg{rule}> /$arg{sep}/ list[%arg]
                        { $return = [ $item[1], @{$item[3]} ] }
            |     <matchrule:$arg{rule}>
                        { $return = [ $item[1]] }

is a handy template for the common problem of matching a separated list. For example:

        function: 'func' name '(' list[rule=>'param',sep=>';'] ')'

        param:    list[rule=>'name',sep=>','] ':' typename
        name:     /\w+/
        typename: name

When a subrule argument list is used with a repeated subrule, the argument list goes before the repetition specifier:

        list:   /some|many/ thing[ $item[1] ](s)

The argument list is "late bound". That is, it is re-evaluated for every repetition of the repeated subrule. This means that each repeated attempt to match the subrule may be passed a completely different set of arguments if the value of the expression in the argument list changes between attempts. So, for example, the grammar:

        { $::species = 'dogs' }

        pair:   'two' animal[$::species](s)
        animal: /$arg[0]/ { $::species = 'cats' }

will match the string "two dogs cats cats" completely, whereas it will only match the string "two dogs dogs dogs" up to the eighth letter. If the value of the argument list were "early bound" (that is, evaluated only the first time a repeated subrule match is attempted), one would expect the matching behaviours to be reversed.

Of course, it is possible to effectively "early bind" such argument lists by passing them a value which does not change on each repetition. For example:

        { $::species = 'dogs' }

        pair:   'two' { $::species } animal[$item[2]](s)

        animal: /$arg[0]/ { $::species = 'cats' }

Arguments can also be passed to the start rule, simply by appending them to the argument list with which the start rule is called (after the "line number" parameter). For example, given:

        $parser = new Parse::RecDescent ( $grammar );

        $parser->data($text, 1, "str", 2, \@arr);

        #             ^^^^^  ^  ^^^^^^^^^^^^^^^
        #               |    |         |
        # TEXT TO BE PARSED  |         |
        # STARTING LINE NUMBER         |
        # ELEMENTS OF @arg WHICH IS PASSED TO RULE data

then within the productions of the rule data, the array @arg will contain ("str", 2, \@arr).

Alternations

Alternations are implicit (unnamed) rules defined as part of a production. An alternation is defined as a series of '|'-separated productions inside a pair of round brackets. For example:

        character: 'the' ( good | bad | ugly ) /dude/

Every alternation implicitly defines a new subrule, whose automatically-generated name indicates its origin: "_alternation_<I>_of_production_<P>_of_rule<R>" for the appropriate values of <I>, <P>, and <R>. A call to this implicit subrule is then inserted in place of the brackets. Hence the above example is merely a convenient short-hand for:

        character: 'the'
                   _alternation_1_of_production_1_of_rule_character
                   /dude/
        _alternation_1_of_production_1_of_rule_character:
                   good | bad | ugly

Since alternations are parsed by recursively calling the parser generator, any type(s) of item can appear in an alternation. For example:

        character: 'the' ( 'high' "plains"      # Silent, with poncho
                         | /no[- ]name/         # Silent, no poncho
                         | vengeance_seeking    # Poncho-optional
                         | <error>
                         ) drifter

In this case, if an error occurred, the automatically generated message would be:

        ERROR (line <N>): Invalid implicit subrule: Expected
                          'high' or /no[- ]name/ or generic,
                          but found "pacifist" instead

Since every alternation actually has a name, it's even possible to extend or replace them:

        parser->Replace(
                "_alternation_1_of_production_1_of_rule_character:
                        'generic Eastwood'"
                        );

More importantly, since alternations are a form of subrule, they can be given repetition specifiers:

        character: 'the' ( good | bad | ugly )(?) /dude/

Incremental Parsing

Parse::RecDescent provides two methods - Extend and Replace - which can be used to alter the grammar matched by a parser. Both methods take the same argument as Parse::RecDescent::new, namely a grammar specification string

Parse::RecDescent::Extend interprets the grammar specification and adds any productions it finds to the end of the rules for which they are specified. For example:

        $add = "name: 'Jimmy-Bob' | 'Bobby-Jim'\ndesc: colour /necks?/";
        parser->Extend($add);

adds two productions to the rule "name" (creating it if necessary) and one production to the rule "desc".

Parse::RecDescent::Replace is identical, except that it first resets are rule specified in the additional grammar, removing any existing productions. Hence after:

        $add = "name: 'Jimmy-Bob' | 'Bobby-Jim'\ndesc: colour /necks?/";
        parser->Replace($add);

are are only valid "name"s and the one possible description.

A more interesting use of the Extend and Replace methods is to call them inside the action of an executing parser. For example:

        typedef: 'typedef' type_name identifier ';'
                       { $thisparser->Extend("type_name: '$item[3]'") }
               | <error>

        identifier: ...!type_name /[A-Za-z_]w*/

which automatically prevents type names from being typedef'd, or:

        command: 'map' key_name 'to' abort_key
                       { $thisparser->Replace("abort_key: '$item[2]'") }
               | 'map' key_name 'to' key_name
                       { map_key($item[2],$item[4]) }
               | abort_key
                       { exit if confirm("abort?") }

        abort_key: 'q'
        key_name: ...!abort_key /[A-Za-z]/

which allows the user to change the abort key binding, but not to unbind it.

The careful use of such constructs makes it possible to reconfigure a a running parser, eliminating the need for semantic feedback by providing syntactic feedback instead. However, as currently implemented, Replace() and Extend() have to regenerate and re-eval the entire parser whenever they are called. This makes them quite slow for large grammars.

In such cases, the judicious use of an interpolated regex is likely to be far more efficient:

        typedef: 'typedef' type_name/ identifier ';'
                       { $thisparser->{local}{type_name} .= "|$item[3]" }
               | <error>

        identifier: ...!type_name /[A-Za-z_]w*/
        type_name: /$thisparser->{local}{type_name}/

Precompiling parsers

Normally Parse::RecDescent builds a parser from a grammar at run-time. That approach simplifies the design and implementation of parsing code, but has the disadvantage that it slows the parsing process down - you have to wait for Parse::RecDescent to build the parser every time the program runs. Long or complex grammars can be particularly slow to build, leading to unacceptable delays at start-up.

To overcome this, the module provides a way of "pre-building" a parser object and saving it in a separate module. That module can then be used to create clones of the original parser.

A grammar may be precompiled using the Precompile class method. For example, to precompile a grammar stored in the scalar $grammar, and produce a class named PreGrammar in a module file named PreGrammar.pm, you could use:

        use Parse::RecDescent;

        Parse::RecDescent->Precompile($grammar, "PreGrammar");

The first argument is the grammar string, the second is the name of the class to be built. The name of the module file is generated automatically by appending ".pm" to the last element of the class name. Thus

        Parse::RecDescent->Precompile($grammar, "My::New::Parser");

would produce a module file named Parser.pm.

It is somewhat tedious to have to write a small Perl program just to generate a precompiled grammar class, so Parse::RecDescent has some special magic that allows you to do the job directly from the command-line.

If your grammar is specified in a file named grammar, you can generate a class named Yet::Another::Grammar like so:

        > perl -MParse::RecDescent - grammar Yet::Another::Grammar

This would produce a file named Grammar.pm containing the full definition of a class called Yet::Another::Grammar. Of course, to use that class, you would need to put the Grammar.pm file in a directory named Yet/Another, somewhere in your Perl include path.

Having created the new class, it's very easy to use it to build a parser. You simply use the new module, and then call its new method to create a parser object. For example:

        use Yet::Another::Grammar;
        my $parser = Yet::Another::Grammar->new();

The effect of these two lines is exactly the same as:

        use Parse::RecDescent;

        open GRAMMAR_FILE, "grammar" or die;
        local $/;
        my $grammar = <GRAMMAR_FILE>;

        my $parser = Parse::RecDescent->new($grammar);

only considerably faster.

Note however that the parsers produced by either approach are exactly the same, so whilst precompilation has an effect on set-up speed, it has no effect on parsing speed. RecDescent 2.0 will address that problem.

A Metagrammar for Parse::RecDescent

The following is a specification of grammar format accepted by Parse::RecDescent::new (specified in the Parse::RecDescent grammar format!):

 grammar    : components(s)
 component  : rule | comment
 rule       : "\n" identifier ":" production(s?)
 production : items(s)
 item       : lookahead(?) simpleitem
            | directive
            | comment
 lookahead  : '...' | '...!'                   # +'ve or -'ve lookahead
 simpleitem : subrule args(?)                  # match another rule
            | repetition                       # match repeated subrules
            | terminal                         # match the next input
            | bracket args(?)                  # match alternative items
            | action                           # do something
 subrule    : identifier                       # the name of the rule
 args       : {extract_codeblock($text,'[]')}  # just like a [...] array ref

 repetition : subrule args(?) howoften
 howoften   : '(?)'                            # 0 or 1 times
            | '(s?)'                           # 0 or more times
            | '(s)'                            # 1 or more times
            | /(\d+)[.][.](/\d+)/              # $1 to $2 times
            | /[.][.](/\d*)/                   # at most $1 times
            | /(\d*)[.][.])/                   # at least $1 times
 terminal   : /[/]([\][/]|[^/])*[/]/           # interpolated pattern
            | /"([\]"|[^"])*"/                 # interpolated literal
            | /'([\]'|[^'])*'/                 # uninterpolated literal
 action     : { extract_codeblock($text) }     # embedded Perl code

 bracket    : '(' Item(s) production(s?) ')'   # alternative subrules
 directive  : '<commit>'                       # commit to production
            | '<uncommit>'                     # cancel commitment
            | '<resync>'                       # skip to newline
            | '<resync:' pattern '>'           # skip <pattern>
            | '<reject>'                       # fail this production
            | '<reject:' condition '>'         # fail if <condition>
            | '<error>'                        # report an error
            | '<error:' string '>'             # report error as "<string>"
            | '<error?>'                       # error only if committed
            | '<error?:' string '>'            #   "    "    "    "
            | '<rulevar:' /[^>]+/ '>'          # define rule-local variable
            | '<matchrule:' string '>'         # invoke rule named in string
 identifier : /[a-z]\w*/i                      # must start with alpha
 comment    : /#[^\n]*/                        # same as Perl
 pattern    : {extract_bracketed($text,'<')}   # allow embedded "<..>"

 condition  : {extract_codeblock($text,'{<')}  # full Perl expression

 string     : {extract_variable($text)}        # any Perl variable
            | {extract_quotelike($text)}       #   or quotelike string
            | {extract_bracketed($text,'<')}   #   or balanced brackets

GOTCHAS

This section describes common mistakes that grammar writers seem to make on a regular basis.

1. Expecting an error to always invalidate a parse

A common mistake when using error messages is to write the grammar like this:

        file: line(s)
        line: line_type_1
            | line_type_2
            | line_type_3
            | <error>

The expectation seems to be that any line that is not of type 1, 2 or 3 will invoke the <error> directive and thereby cause the parse to fail.

Unfortunately, that only happens if the error occurs in the very first line. The first rule states that a file is matched by one or more lines, so if even a single line succeeds, the first rule is completely satisfied and the parse as a whole succeeds. That means that any error messages generated by subsequent failures in the line rule are quietly ignored.

Typically what's really needed is this:

        file: line(s) eofile    { $return = $item[1] }
        line: line_type_1
            | line_type_2
            | line_type_3
            | <error>
        eofile: /^\Z/

The addition of the eofile subrule to the first production means that a file only matches a series of successful line matches that consume the complete input text. If any input text remains after the lines are matched, there must have been an error in the last line. In that case the eofile rule will fail, causing the entire file rule to fail too.

Note too that eofile must match /^\Z/ (end-of-text), not /^\cZ/ or /^\cD/ (end-of-file).

And don't forget the action at the end of the production. If you just write:

        file: line(s) eofile

then the value returned by the file rule will be the value of its last item: eofile. Since eofile always returns an empty string on success, that will cause the file rule to return that empty string. Apart from returning the wrong value, returning an empty string will trip up code such as:

        $parser->file($filetext) || die;

(since "" is false).

Remember that Parse::RecDescent returns undef on failure, so the only safe test for failure is:

        defined($parser->file($filetext)) || die;

DIAGNOSTICS

Diagnostics are intended to be self-explanatory (particularly if you use -RD_HINT (under perl -s) or define $::RD_HINT inside the program).

Parse::RecDescent currently diagnoses the following:

  • Invalid regular expressions used as pattern terminals (fatal error).

  • Invalid Perl code in code blocks (fatal error).

  • Lookahead used in the wrong place or in a nonsensical way (fatal error).

  • "Obvious" cases of left-recursion (fatal error).

  • Missing or extra components in a <leftop> or <rightop> directive.

  • Unrecognisable components in the grammar specification (fatal error).

  • "Orphaned" rule components specified before the first rule (fatal error) or after an <error> directive (level 3 warning).

  • Missing rule definitions (this only generates a level 3 warning, since you may be providing them later via Parse::RecDescent::Extend()).

  • Instances where greedy repetition behaviour will almost certainly cause the failure of a production (a level 3 warning - see ON-GOING ISSUES AND FUTURE DIRECTIONS below).

  • Attempts to define rules named 'Replace' or 'Extend', which cannot be called directly through the parser object because of the predefined meaning of Parse::RecDescent::Replace and Parse::RecDescent::Extend. (Only a level 2 warning is generated, since such rules can still be used as subrules).

  • Productions which consist of a single <error?> directive, and which therefore may succeed unexpectedly (a level 2 warning, since this might conceivably be the desired effect).

  • Multiple consecutive lookahead specifiers (a level 1 warning only, since their effects simply accumulate).

  • Productions which start with a <reject> or <rulevar:...> directive. Such productions are optimized away (a level 1 warning).

  • Rules which are autogenerated under $::AUTOSTUB (a level 1 warning).

AUTHOR

Damian Conway (damian@conway.org)

BUGS AND IRRITATIONS

There are undoubtedly serious bugs lurking somewhere in this much code :-) Bug reports and other feedback are most welcome.

Ongoing annoyances include:

  • There's no support for parsing directly from an input stream. If and when the Perl Gods give us regular expressions on streams, this should be trivial (ahem!) to implement.

  • The parser generator can get confused if actions aren't properly closed or if they contain particularly nasty Perl syntax errors (especially unmatched curly brackets).

  • The generator only detects the most obvious form of left recursion (potential recursion on the first subrule in a rule). More subtle forms of left recursion (for example, through the second item in a rule after a "zero" match of a preceding "zero-or-more" repetition, or after a match of a subrule with an empty production) are not found.

  • Instead of complaining about left-recursion, the generator should silently transform the grammar to remove it. Don't expect this feature any time soon as it would require a more sophisticated approach to parser generation than is currently used.

  • The generated parsers don't always run as fast as might be wished.

  • The meta-parser should be bootstrapped using Parse::RecDescent :-)

ON-GOING ISSUES AND FUTURE DIRECTIONS

  1. Repetitions are "incorrigibly greedy" in that they will eat everything they can and won't backtrack if that behaviour causes a production to fail needlessly. So, for example:

            rule: subrule(s) subrule

    will never succeed, because the repetition will eat all the subrules it finds, leaving none to match the second item. Such constructions are relatively rare (and Parse::RecDescent::new generates a warning whenever they occur) so this may not be a problem, especially since the insatiable behaviour can be overcome "manually" by writing:

            rule: penultimate_subrule(s) subrule
            penultimate_subrule: subrule ...subrule

    The issue is that this construction is exactly twice as expensive as the original, whereas backtracking would add only 1/N to the cost (for matching N repetitions of subrule). I would welcome feedback on the need for backtracking; particularly on cases where the lack of it makes parsing performance problematical.

  2. Having opened that can of worms, it's also necessary to consider whether there is a need for non-greedy repetition specifiers. Again, it's possible (at some cost) to manually provide the required functionality:

            rule: nongreedy_subrule(s) othersubrule
            nongreedy_subrule: subrule ...!othersubrule

    Overall, the issue is whether the benefit of this extra functionality outweighs the drawbacks of further complicating the (currently minimalist) grammar specification syntax, and (worse) introducing more overhead into the generated parsers.

  3. An <autocommit> directive would be nice. That is, it would be useful to be able to say:

            command: <autocommit>
        command: 'find' name
               | 'find' address
               | 'do' command 'at' time 'if' condition
               | 'do' command 'at' time
               | 'do' command
               | unusual_command

    and have the generator work out that this should be "pruned" thus:

            command: 'find' name
               | 'find' <commit> address
               | 'do' <commit> command <uncommit>
                        'at' time
                        'if' <commit> condition
               | 'do' <commit> command <uncommit>
                        'at' <commit> time
               | 'do' <commit> command
               | unusual_command

    There are several issues here. Firstly, should the <autocommit> automatically install an <uncommit> at the start of the last production (on the grounds that the "command" rule doesn't know whether an "unusual_command" might start with "find" or "do") or should the "unusual_command" subgraph be analysed (to see if it might be viable after a "find" or "do")?

    The second issue is how regular expressions should be treated. The simplest approach would be simply to uncommit before them (on the grounds that they might match). Better efficiency would be obtained by analyzing all preceding literal tokens to determine whether the pattern would match them.

    Overall, the issues are: can such automated "pruning" approach a hand-tuned version sufficiently closely to warrant the extra set-up expense, and (more importantly) is the problem important enough to even warrant the non-trivial effort of building an automated solution?

COPYRIGHT

Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)


Perl::Critic - Critique Perl source code for best-practices

  • CONSTRUCTOR
  • METHODS
  • FUNCTIONAL INTERFACE
  • CONFIGURATION
  • THE POLICIES
  • BENDING THE RULES
  • IMPORTANT CHANGES
    • VERSION 0.16
    • VERSION 0.14
    • VERSION 0.11
  • THE the Perl::Critic manpage PHILOSOPHY
  • EXTENDING THE CRITIC
  • PREREQUISITES
  • BUGS
  • CREDITS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic - Critique Perl source code for best-practices

SYNOPSIS

  use Perl::Critic;
  my $file = shift;
  my $critic = Perl::Critic->new();
  my @violations = $critic->critique($file);
  print @violations;

DESCRIPTION

Perl::Critic is an extensible framework for creating and applying coding standards to Perl source code. Essentially, it is a static source code analysis engine. Perl::Critic is distributed with a number of the Perl::Critic::Policy manpage modules that attempt to enforce various coding guidelines. Most Policy modules are based on Damian Conway's book Perl Best Practices. However, Perl::Critic is not limited to PBP and will even support Policies that contradict Conway. You can enable, disable, and customize those Polices through the Perl::Critic interface. You can also create new Policy modules that suit your own tastes.

For a convenient command-line interface to Perl::Critic, see the documentation for perlcritic. If you want to integrate Perl::Critic with your build process, the Test::Perl::Critic manpage provides an interface that is suitable for test scripts. For the ultimate convenience (at the expense of some flexibility) see the criticism pragma.

Win32 and ActivePerl users can find PPM distributions of Perl::Critic at http://theoryx5.uwinnipeg.ca/ppms/.

If you'd like to try the Perl::Critic manpage before you install it, there is a web-service available at http://perlcritic.com. The web-service does not yet support all the configuration features that are available in the native Perl::Critic API, but it should give you a good idea of what it does.

CONSTRUCTOR

new( -profile => $FILE, -severity => $N, -include => \@PATTERNS, -exclude => \@PATTERNS, -top => N, -force => 1 )

Returns a reference to a new Perl::Critic object. Most arguments are just passed directly into the Perl::Critic::Config manpage, but I have described them here as well. All arguments are optional key-value pairs as follows:

-profile is a path to a configuration file. If $FILE is not defined, Perl::Critic::Config attempts to find a .perlcriticrc configuration file in the current directory, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to point to a file in another location. If a configuration file can't be found, or if $FILE is an empty string, then all Policies will be loaded with their default configuration. See CONFIGURATION for more information.

-severity is the minimum severity level. Only Policy modules that have a severity greater than $N will be loaded. Severity values are integers ranging from 1 (least severe) to 5 (most severe). The default is 5. For a given -profile, decreasing the -severity will usually result in more Policy violations. Users can redefine the severity level for any Policy in their .perlcriticrc file. See CONFIGURATION for more information.

-include is a reference to a list of string @PATTERNS. Policy modules that match at least one m/$PATTERN/imx will always be loaded, irrespective of the severity settings. For example:

  my $critic = Perl::Critic->new(-include => ['layout'] -severity => 4);

This would cause Perl::Critic to load all the CodeLayout::* Policy modules even though they have a severity level that is less than 4. You can use -include in conjunction with the -exclude option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

-exclude is a reference to a list of string @PATTERNS. Policy modules that match at least one m/$PATTERN/imx will not be loaded, irrespective of the severity settings. For example:

  my $critic = Perl::Critic->new(-exclude => ['strict'] -severity => 1);

This would cause Perl::Critic to not load the RequireUseStrict and ProhibitNoStrict Policy modules even though they have a severity level that is greater than 1. You can use -exclude in conjunction with the -include option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

-top is the maximum number of Violations to return when ranked by their severity levels. Violations are still returned in the order that they occur within the file. This must be a positive integer

-force controls whether Perl::Critic observes the magical "## no critic" pseudo-pragmas in your code. If set to a true value, Perl::Critic will analyze all code. If set to a false value (which is the default) Perl::Critic will ignore code that is tagged with these comments. See BENDING THE RULES for more information.

-config is a reference to a the Perl::Critic::Config manpage object. If you have created your own Config object for some reason, you can pass it in here instead of having Perl::Critic create one for you. Using the -config option causes all the other options to be silently ignored.

METHODS

critique( $source_code )

Runs the $source_code through the Perl::Critic engine using all the Policies that have been loaded into this engine. If $source_code is a scalar reference, then it is treated as string of actual Perl code. If $source_code is a reference to an instance of the PPI::Document manpage, then that instance is used directly. Otherwise, it is treated as a path to a local file containing Perl code. This method Returns a list of the Perl::Critic::Violation manpage objects for each violation of the loaded Policies. The list is sorted in the order that the Violations appear in the code. If there are no violations, this method returns an empty list.

add_policy( -policy => $policy_name, -config => \%config_hash )

Creates a Policy object and loads it into this Critic. If the object cannot be instantiated, it will throw a warning and return a false value. Otherwise, it returns a reference to this Critic.

-policy is the name of a the Perl::Critic::Policy manpage subclass module. The 'Perl::Critic::Policy' portion of the name can be omitted for brevity. This argument is required.

-config is an optional reference to a hash of Policy configuration parameters. Note that this is not the same thing as a the Perl::Critic::Config manpage object. The contents of this hash reference will be passed into to the constructor of the Policy module. See the documentation in the relevant Policy module for a description of the arguments it supports.

policies()

Returns a list containing references to all the Policy objects that have been loaded into this engine. Objects will be in the order that they were loaded.

config()

Returns the the Perl::Critic::Config manpage object that was created for or given to this Critic.

FUNCTIONAL INTERFACE

For those folks who prefer to have a functional interface, The critique method can be exported on request and called as a static function. If the first argument is a hashref, its contents are used to construct a new Perl::Critic object internally. The keys of that hash should be the same as those supported by the Perl::Critic::new method. Here are some examples:

  use Perl::Critic qw(critique);

  # Use default parameters...
  @violations = critique( $some_file );

  # Use custom parameters...
  @violations = critique( {-severity => 2}, $some_file );

  # As a one-liner
  %> perl -MPerl::Critic=critique -e 'print critique(shift)' some_file.pm

None of the other object-methods are currently supported as static functions. Sorry.

CONFIGURATION

The default configuration file is called .perlcriticrc. Perl::Critic will look for this file in the current directory first, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to explicitly point to a different file in another location. If none of these files exist, and the -profile option is not given to the constructor, then all the modules that are found in the Perl::Critic::Policy namespace will be loaded with their default configuration.

The format of the configuration file is a series of INI-style sections that contain key-value pairs separated by '='. Comments should start with '#' and can be placed on a separate line or after the name-value pairs if you desire. The general recipe is a series of blocks like this:

  [Perl::Critic::Policy::Category::PolicyName]
  severity = 1
  arg1 = value1
  arg2 = value2

Perl::Critic::Policy::Category::PolicyName is the full name of a module that implements the policy. The Policy modules distributed with Perl::Critic have been grouped into categories according to the table of contents in Damian Conway's book Perl Best Practices. For brevity, you can omit the 'Perl::Critic::Policy' part of the module name.

severity is the level of importance you wish to assign to the Policy. All Policy modules are defined with a default severity value ranging from 1 (least severe) to 5 (most severe). However, you may disagree with the default severity and choose to give it a higher or lower severity, based on your own coding philosophy.

The remaining key-value pairs are configuration parameters that will be passed into the constructor for that Policy. The constructors for most Policy objects do not support arguments, and those that do should have reasonable defaults. See the documentation on the appropriate Policy module for more details.

Instead of redefining the severity for a given Policy, you can completely disable a Policy by prepending a '-' to the name of the module in your configuration file. In this manner, the Policy will never be loaded, regardless of the -severity given to the Perl::Critic constructor.

A simple configuration might look like this:

  #--------------------------------------------------------------
  # I think these are really important, so always load them

  [TestingAndDebugging::RequireUseStrict]
  severity = 5
  [TestingAndDebugging::RequireUseWarnings]
  severity = 5
  #--------------------------------------------------------------
  # I think these are less important, so only load when asked

  [Variables::ProhibitPackageVars]
  severity = 2
  [ControlStructures::ProhibitPostfixControls]
  allow = if unless  #My custom configuration
  severity = 2
  #--------------------------------------------------------------
  # I do not agree with these at all, so never load them

  [-NamingConventions::ProhibitMixedCaseVars]
  [-NamingConventions::ProhibitMixedCaseSubs]
  #--------------------------------------------------------------
  # For all other Policies, I accept the default severity,
  # so no additional configuration is required for them.

A few sample configuration files are included in this distribution under the t/samples directory. The perlcriticrc.none file demonstrates how to disable Policy modules. The perlcriticrc.levels file demonstrates how to redefine the severity level for any given Policy module. The perlcriticrc.pbp file configures Perl::Critic to load only Policies described in Damian Conway's book "Perl Best Practice."

THE POLICIES

A large number of Policy modules are distributed with Perl::Critic. They are described briefly in the companion document the Perl::Critic::PolicySummary manpage and in more detail in the individual modules themselves.

BENDING THE RULES

Perl::Critic takes a hard-line approach to your code: either you comply or you don't. In the real world, it is not always practical (nor even possible) to fully comply with coding standards. In such cases, it is wise to show that you are knowingly violating the standards and that you have a Damn Good Reason (DGR) for doing so.

To help with those situations, you can direct Perl::Critic to ignore certain lines or blocks of code by using pseudo-pragmas:

    require 'LegacyLibaray1.pl';  ## no critic
    require 'LegacyLibrary2.pl';  ## no critic

    for my $element (@list) {

        ## no critic

        $foo = "";               #Violates 'ProhibitEmptyQuotes'
        $barf = bar() if $foo;   #Violates 'ProhibitPostfixControls'
        #Some more evil code...

        ## use critic

        #Some good code...
        do_something($_);
            }

The "## no critic" comments direct Perl::Critic to ignore the remaining lines of code until the end of the current block, or until a "## use critic" comment is found (whichever comes first). If the "## no critic" comment is on the same line as a code statement, then only that line of code is overlooked. To direct perlcritic to ignore the "## no critic" comments, use the -force option.

A bare "## no critic" comment disables all the active Policies. If you wish to disable only specific Policies, add a list of Policy names as arguments, just as you would for the "no strict" or "no warnings" pragmas. For example, this would disable the ProhibitEmptyQuotes and ProhibitPostfixControls policies until the end of the block or until the next "## use critic" comment (whichever comes first):

  ## no critic (EmptyQuotes, PostfixControls)

  $foo = "";                  #Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
  $barf = bar() if $foo;      #Now exempt ControlStructures::ProhibitPostfixControls
  $long_int = 10000000000;    #Still subjected to ValuesAndExpression::RequireNumberSeparators

Since the Policy names are matched against the arguments as regular expressions, you can abbreviate the Policy names or disable an entire family of Policies in one shot like this:

  ## no critic (NamingConventions)

  my $camelHumpVar = 'foo';  #Now exempt from NamingConventions::ProhibitMixedCaseVars
  sub camelHumpSub {}        #Now exempt from NamingConventions::ProhibitMixedCaseSubs

The argument list must be enclosed in parens and must contain one or more comma-separated barewords (e.g. don't use quotes). The "## no critic" pragmas can be nested, and Policies named by an inner pragma will be disabled along with those already disabled an outer pragma.

Use this feature wisely. "## no critic" should be used in the smallest possible scope, or only on individual lines of code. And you should always be as specific as possible about which policies you want to disable (i.e. never use a bare "## no critic"). If Perl::Critic complains about your code, try and find a compliant solution before resorting to this feature.

IMPORTANT CHANGES

Perl-Critic is evolving rapidly, so some of the interfaces have changed in ways that are not backward-compatible. If you have been using an older version of Perl-Critic and/or you have been developing custom Policy modules, please read this section carefully.

VERSION 0.16

Starting in version 0.16, you can add a list Policy names as arguments to the "## no critic" pseudo-pragma. This feature allows you to disable specific policies. So if you have been in the habit of adding additional words after "no critic", then those words might cause unexpected results. If you want to append other stuff to the "## no critic" comment, then terminate the pseudo-pragma with a semi-colon, and then start another comment. For example:

  #This may not work as expected.
  $email = 'foo@bar.com';  ## no critic for literal '@'

  #This will work.
  $email = 'foo@bar.com';  ## no critic; #for literal '@'

  #This is even better.
  $email = 'foo@bar.com'; ## no critic (RequireInterpolation);

VERSION 0.14

Starting in version 0.14, the interface to the Perl::Critic::Violation manpage changed. This will also break any custom Policy modules that you might have written for earlier modules. See the Perl::Critic::DEVELOPER manpage for an up-to-date guide on creating Policy modules.

The notion of "priority" was also replaced with "severity" in version 0.14. Consequently, the default behavior of Perl::Critic is to only load the most "severe" Policy modules, rather than loading all of them. This decision was based on user-feedback suggesting that Perl-Critic should be less critical for new users, and should steer them toward gradually increasing the strictness as they progressively adopt better coding practices.

VERSION 0.11

Starting in version 0.11, the internal mechanics of Perl-Critic were rewritten so that only one traversal of the PPI document tree is required. Unfortunately, this will break any custom Policy modules that you might have written for earlier versions. Converting your policies to work with the new version is pretty easy and actually results in cleaner code. See the Perl::Critic::DEVELOPER manpage for an up-to-date guide on creating Policy modules.

THE the Perl::Critic manpage PHILOSOPHY

  Coding standards are deeply personal and highly subjective.  The
  goal of Perl::Critic is to help you write code that conforms with a
  set of best practices.  Our primary goal is not to dictate what
  those practices are, but rather, to implement the practices
  discovered by others.  Ultimately, you make the rules --
  Perl::Critic is merely a tool for encouraging consistency.  If there
  is a policy that you think is important or that we have overlooked,
  we would be very grateful for contributions, or you can simply load
  your own private set of policies into Perl::Critic.

EXTENDING THE CRITIC

The modular design of Perl::Critic is intended to facilitate the addition of new Policies. You'll need to have some understanding of the PPI manpage, but most Policy modules are pretty straightforward and only require about 20 lines of code. Please see the the Perl::Critic::DEVELOPER manpage file included in this distribution for a step-by-step demonstration of how to create new Policy modules.

If you develop any new Policy modules, feel free to send them to thaljef@cpan.org and I'll be happy to put them into the Perl::Critic distribution. Or if you'd like to work on the Perl::Critic project directly, check out our repository at http://perlcritic.tigris.org. To subscribe to our mailing list, send a message to dev-subscribe@perlcritic.tigris.org.

PREREQUISITES

Perl::Critic requires the following modules:

the Config::Tiny manpage

the File::Spec manpage

the IO::String manpage

the List::Util manpage

the List::MoreUtils manpage

the Module::Pluggable manpage

the PPI manpage

the Pod::Usage manpage

the Pod::PlainText manpage

the Scalar::Util manpage

the String::Format manpage

The following modules are optional, but recommended for complete testing:

the Test::Pod manpage

the Test::Pod::Coverage manpage

BUGS

Scrutinizing Perl code is hard for humans, let alone machines. If you find any bugs, particularly false-positives or false-negatives from a Perl::Critic::Policy, please submit them to http://rt.cpan.org/NoAuth/Bugs.html. Thanks.

CREDITS

Adam Kennedy - For creating the PPI manpage, the heart and soul of the Perl::Critic manpage.

Damian Conway - For writing Perl Best Practices, finally :)

Chris Dolan - For contributing the best features and Policy modules.

Giuseppe Maxia - For all the great ideas and positive encouragement.

and Sharon, my wife - For putting up with my all-night code sessions.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::Config - Find and load Perl::Critic user-preferences

  • CONSTRUCTOR
  • METHODS
  • SUBROUTINES
  • ADVANCED USAGE
  • CONFIGURATION
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Config - Find and load Perl::Critic user-preferences

DESCRIPTION

Perl::Critic::Config takes care of finding and processing user-preferences for the Perl::Critic manpage. The Config object defines which Policy modules will be loaded into the Perl::Critic engine and how they should be configured. You should never really need to instantiate Perl::Critic::Config directly because the Perl::Critic constructor will do it for you.

CONSTRUCTOR

new( [ -profile => $FILE, -severity => $N, -include => \@PATTERNS, -exclude => \@PATTERNS ] )

Returns a reference to a new Perl::Critic::Config object, which is basically just a blessed hash of configuration parameters. There aren't any special methods for getting and setting individual values, so just treat it like an ordinary hash. All arguments are optional key-value pairs as follows:

-profile is a path to a configuration file. If $FILE is not defined, Perl::Critic::Config attempts to find a .perlcriticrc configuration file in the current directory, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to point to a file in another location. If a configuration file can't be found, or if $FILE is an empty string, then all Policies will be loaded with their default configuration. See CONFIGURATION for more information.

-severity is the minimum severity level. Only Policy modules that have a severity greater than $N will be loaded into this Config. Severity values are integers ranging from 1 (least severe) to 5 (most severe). The default is 5. For a given -profile, decreasing the -severity will usually result in more Policy violations. Users can redefine the severity level for any Policy in their .perlcriticrc file. See CONFIGURATION for more information.

-include is a reference to a list of string @PATTERNS. Policies that match at least one m/$PATTERN/imx will be loaded into this Config, irrespective of the severity settings. You can use it in conjunction with the -exclude option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

-exclude is a reference to a list of string @PATTERNS. Polices that match at least one m/$PATTERN/imx will not be loaded into this Config, irrespective of the severity settings. You can use it in conjunction with the -include option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

METHODS

add_policy( -policy => $policy_name, -config => \%config_hash )

Loads a Policy object and adds into this Config. If the object cannot be instantiated, it will throw a warning and return a false value. Otherwise, it returns a reference to this Config. Arguments are key-value pairs as follows:

-policy is the name of a the Perl::Critic::Policy manpage subclass module. The 'Perl::Critic::Policy' portion of the name can be omitted for brevity. This argument is required.

-config is an optional reference to a hash of Policy configuration parameters (Note that this is not a Perl::Critic::Config object). The contents of this hash reference will be passed into to the constructor of the Policy module. See the documentation in the relevant Policy module for a description of the arguments it supports.

policies()

Returns a list containing references to all the Policy objects that have been loaded into this Config. Objects will be in the order that they were loaded.

SUBROUTINES

Perl::Critic::Config has a few static subroutines that are used internally, but may be useful to you in some way.

find_profile_path()

Searches the PERLCRITIC environment variable, the current directory, and you home directory (in that order) for a .perlcriticrc file. If the file is found, the full path is returned. Otherwise, returns undef;

site_policies()

Returns a list of all the Policy modules that are currently installed in the Perl::Critic:Policy namespace. These will include modules that are distributed with Perl::Critic plus any third-party modules that have been installed.

native_policies()

Returns a list of all the Policy modules that have been distributed with Perl::Critic. Does not include any third-party modules.

ADVANCED USAGE

All the Policy modules that ship with Perl::Critic are in the "Perl::Critic::Policy" namespace. To load modules from an alternate namespace, import Perl::Critic::Config using the -namespace option like this:

  use Perl::Critic::Config -namespace => 'Foo::Bar'; #Loads from Foo::Bar::*

At the moment, only one alternate namespace may be specified. Unless Policy module names are fully qualified, Perl::Critic::Config assumes that all Policies are in the specified namespace. So if you want to use Policies from multiple namespaces, you will need to use the full module name in your .perlcriticrc file.

CONFIGURATION

The default configuration file is called .perlcriticrc. Perl::Critic::Config will look for this file in the current directory first, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to explicitly point to a different file in another location. If none of these files exist, and the -profile option is not given to the constructor, then all the modules that are found in the Perl::Critic::Policy namespace will be loaded with their default configuration.

The format of the configuration file is a series of named sections that contain key-value pairs separated by '='. Comments should start with '#' and can be placed on a separate line or after the name-value pairs if you desire. The general recipe is a series of blocks like this:

    [Perl::Critic::Policy::Category::PolicyName]
    severity = 1
    arg1 = value1
    arg2 = value2

Perl::Critic::Policy::Category::PolicyName is the full name of a module that implements the policy. The Policy modules distributed with Perl::Critic have been grouped into categories according to the table of contents in Damian Conway's book Perl Best Practices. For brevity, you can omit the 'Perl::Critic::Policy' part of the module name.

severity is the level of importance you wish to assign to the Policy. All Policy modules are defined with a default severity value ranging from 1 (least severe) to 5 (most severe). However, you may disagree with the default severity and choose to give it a higher or lower severity, based on your own coding philosophy.

The remaining key-value pairs are configuration parameters that will be passed into the constructor of that Policy. The constructors for most Policy modules do not support arguments, and those that do should have reasonable defaults. See the documentation on the appropriate Policy module for more details.

Instead of redefining the severity for a given Policy, you can completely disable a Policy by prepending a '-' to the name of the module in your configuration file. In this manner, the Policy will never be loaded, regardless of the -severity given to the Perl::Critic::Config constructor.

A simple configuration might look like this:

    #--------------------------------------------------------------
    # I think these are really important, so always load them

    [TestingAndDebugging::RequireUseStrict]
    severity = 5
    [TestingAndDebugging::RequireUseWarnings]
    severity = 5
    #--------------------------------------------------------------
    # I think these are less important, so only load when asked

    [Variables::ProhibitPackageVars]
    severity = 2
    [ControlStructures::ProhibitPostfixControls]
    allow = if unless  #A policy-specific configuration
    severity = 2
    #--------------------------------------------------------------
    # I do not agree with these at all, so never load them

    [-NamingConventions::ProhibitMixedCaseVars]
    [-NamingConventions::ProhibitMixedCaseSubs]
    #--------------------------------------------------------------
    # For all other Policies, I accept the default severity,
    # so no additional configuration is required for them.

A few sample configuration files are included in this distribution under the t/samples directory. The perlcriticrc.none file demonstrates how to disable Policy modules. The perlcriticrc.levels file demonstrates how to redefine the severity level for any given Policy module. The perlcriticrc.pbp file configures Perl::Critic to load only Policies described in Damian Conway's book "Perl Best Practices."

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules

  • BACKGROUND
  • EXAMPLE POLICY
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules

DESCRIPTION

This document describes how to create a new Policy module for the Perl::Critic manpage. It is intended for developers who wish to extend Perl::Critic to enforce their own custom coding standards. Although the Perl::Critic distribution already includes a number of Policies based on Damian Conway's book "Perl Best Practices", Perl::Critic is not limited to his guidelines and can be used to enforce any practice, preference, or style that you want to follow. In fact, you can even write Policies to enforce contradictory guidelines. All you need to do is write a corresponding the Perl::Critic::Policy manpage subclass, which may require as little as 10 lines of code..

BACKGROUND

The heart of Perl::Critic is the PPI manpage, which is a parser and lexer for Perl. PPI transforms a file of Perl source code into a Document Object Model (DOM). Each token in the document is represented by one of the various PPI classes (for example: the PPI::Token::Operator manpage, the PPI::Token::Word manpage). The tokens are then organized into a hierarchy of structural classes (for example: the PPI::Statement::Expression manpage, the PPI::Structure::Subroutine manpage). The root node of the hierarchy is the the PPI::Document manpage.

The the Perl::Critic manpage engine traverses each node in the the PPI::Document manpage tree and invokes each of the the Perl::Critic::Policy manpage subclasses at the appropriate node. The Policy can inspect the node, look at the surrounding nodes, and do whatever else it wants. If the Policy decides that that a coding standard has been violated, it returns one or more the Perl::Critic::Violation manpage objects. If there are no violations, then the Policy returns nothing.

So now that we understand the basic organization of PPI and Perl::Critic, lets examine one the existing Policy modules so we can see how this all works. We will pick the RequireBlockGrep.pm policy because it is relatively simple but demonstrates most of the important issues. The goal of this Policy is to enforce that every call to grep uses a block for the first argument and not an expression. The reasons for this Policy are discussed in detail in "Perl Best Practices."

EXAMPLE POLICY

First, the Policy module needs to have a name. Perl::Critic uses the Module::Pluggable manpage to automatically discover all modules that are in the Perl::Critic::Policy namespace. Also, we've adopted the convention of grouping Policies into directories according to the table of contents in Conway's book "Perl Best Practices." Since the goal of this policy is to enforce the use of block arguments to grep and it comes from the "Builtin Functions" chapter of PBP, we call it "Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep".

  package Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep;

Next, we set some pragmas and load the modules that we'll need. All Policy modules inherit from the the Perl::Critic::Policy manpage class, which provides no-op implementations of the basic methods. Our job is to override these methods to make them do something useful.

Technically, use strict and use warnings are optional, but they are necessary to make Perl::Critic self-compliant. And we don't want Perl::Critic to be a hypocrite, now do we?

  use strict;
  use warnings;
  use Perl::Critic::Utils;
  use Perl::Critic::Violation;
  use base 'Perl::Critic::Policy';

This following is a pretty standard way to declare a version number for your module, and it's also required for self-compliance. But the ProhibitStringyEval policy doesn't approve of using eval in this manner, so we attach the "## no critic" comments to tell Perl::Critic to overlook this line of code.

  our $VERSION = '0.13_01';
  $VERSION = eval $VERSION;    ## no critic

Next, we'll declare a description and explanation for this Policy. The description is always just a string that basically says "this is what's wrong." The explanation can be either a string with further details, or a reference to an array of integers that correspond to page numbers in the "Perl Best Practices" book.

  my $desc = q{Expression form of "grep"};
  my $expl = [169];

Most policies don't need to override the new() method provided by the Perl::Critic::Policy manpage. However, if your policy is configurable via .perlcriticrc you will need to override the constructor to examine the %args values. See the Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse manpage for a simple example and the Perl::Critic::Policy::Documentation::RequirePodSections manpage for a more complex example.

Next we define the default_severity() method, which should return a scalar value indicating the severity of violating this Policy. Severity values range from 1 to 5, where 5 is the "most severe." In general, level 5 is reserved for things that are frequently misused and/or cause bugs. Level 1 is for things that are highly subjective or purely cosmetic. The the Perl::Critic::Utils manpage package exports several severity constants that you can use here.

  sub default_severity  { return $SEVERITY_HIGH }

Next we indicate what parts of the code this policy will analyze, like statements or variables or conditionals or POD. These parts are specified as PPI classes like the PPI::Statement manpage, the PPI::Token::Symbol manpage, the PPI::Structure::Conditional manpage or the PPI::Token::Pod manpage respectively. The applies_to() method returns a list of PPI package names. (You can get that list of package names via perldoc PPI.) As Perl::Critic traverses the document, it will call the violates() method from this module whenever it encounters one of the PPI types that are given here. In this case, we just want to test calls to grep. Since the token "grep" is a the PPI::Token::Word manpage, we return that name from the applies_to() method.

  sub applies_to { return 'PPI::Token::Word' }

Note that applies_to() is purely a performance enhancement -- if you want your policy to analyze every the PPI::Element manpage, that's just fine.

Now comes the interesting part. The violates() method does all the work. It is always called with 2 arguments: a reference to the current PPI element instance that Perl::Critic is traversing, and a reference to the entire PPI document. [And since this is an instance method, there will be an additional argument that is a reference to this object ($self), but you already knew that!]

  sub violates {
      my ( $self, $elem, $doc ) = @_;

The violates() method then often performs some tests to make sure we have the right "type" of element. In our example, we know that the element will be a the PPI::Token::Word manpage because that's what we declared back in the applies_to() method. However, we didn't specify exactly which "word" we were looking for. Evaluating a PPI element in a string context returns the literal form of the code. So we make sure that this PPI::Token::Word is, in fact, "grep". If it's not, then we don't' need to bother examining it.

    return if !($elem eq 'grep');

The PPI::Token::Word class is also used for barewords and methods called on object references. It is possible for someone to declare a bareword hash key as <%hash = ( grep = 'foo' )>>. We don't want to test those types of elements because they don't represent function calls to grep. So we use some handy utility functions from the Perl::Critic::Utils manpage to make sure that this "grep" is actually in the right context.

    return if is_method_call($elem);
    return if is_hash_key($elem);
    return if is_subroutine_name($elem);

Now that we know this element is a call to the grep function, we can look at the nearby elements to see what kind of arguments are being passed to it. Every PPI element is linked to its siblings, parent, and children (if it has any). Since those siblings could just be whitespace, we use the snext_sibling() to get the next code-sibling (the 's' in snext_sibling stands for 'significant').

    my $sib = $elem->snext_sibling() || return;

In Perl, the parenthesis around argument lists are usually optional, and PPI packs the elements into a the PPI::Structure::List manpage object when parens are used. So if the sibling is a PPI::Structure::List, we pull out the first (significant) child of that list. This child will be the first argument to grep. If parens were not used, then the sibling itself is the first argument.

    my $arg = $sib->isa('PPI::Structure::List') ? $sib->schild(0) : $sib;

Finally, we now have a reference to the first argument to grep. If that argument is a block (i.e. something in curly braces), then it will be a the PPI::Structure::Block manpage, in which case our Policy is satisfied and we just return nothing.

    return if !$arg || $arg->isa('PPI::Structure::Block');

But if it is not a the PPI::Structure::Block manpage, then we know that this call to grep must be using the expression form, and that violates our Policy. So we create and return a new the Perl::Critic::Violation manpage object, passing in the description, explanation, and severity of the violation, as well as a reference to the PPI element that caused the violation. And that's all there is to it!

    my $sev = $self->get_severity();
    return Perl::Critic::Violation->new( $desc, $expl, $elem, $sev );
      }

  1;

One last thing -- When you import the Perl::Critic::Violation manpage, it extracts the DESCRIPTION section from the POD in your Policy module. That text can displayed in the diagnostic output when the Violations objects are stringified. So please include a DESCRIPTION section in the POD for your Policy. It should succinctly describe the behavior and motivation for your Policy and include a few examples of both good and bad code. Here's an example:

  =pod
  =head1 NAME
  Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep
  =head1 DESCRIPTION
  The expression form of C<grep> and C<map> is awkward and hard to read.
  Use the block forms instead.
    @matches = grep   /pattern/,   @list;        #not ok
    @matches = grep { /pattern/ }  @list;        #ok

    @mapped = map   transform($_),   @list;      #not ok
    @mapped = map { transform($_) }  @list;      #ok

  =cut

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::Document - Caching wrapper around PPI::Document

  • CAVEATS
  • METHODS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Document - Caching wrapper around PPI::Document

SYNOPSIS

    use PPI::Document;
    use Perl::Critic::Document;
    my $doc = PPI::Document->new('Foo.pm');
    $doc = Perl::Critic::Document->new($doc);
    ## Then use the instance just like a PPI::Document

DESCRIPTION

Perl::Critic does a lot of iterations over the PPI document tree via the PPI::Document::find() method. To save some time, this class pre-caches a lot of the common find() calls in a single traversal. Then, on subsequent requests we return the cached data.

This is implemented as a facade, where method calls are handed to the stored PPI::Document instance.

CAVEATS

This facade does not implement the overloaded operators from the PPI::Document manpage (that is, the use overload ... work). Therefore, users of this facade must not rely on that syntactic sugar. So, for example, instead of my $source = "$doc"; you should write my $source = $doc-content();>

Perhaps there is a CPAN module out there which implements a facade better than we do here?

METHODS

$pkg->new($doc)

Create a new instance referencing a PPI::Document instance.

$self->find($wanted)
$self->find_first($wanted)
$self->find_any($wanted)

If $wanted is a simple PPI class name, then the cache is employed. Otherwise we forward the call to the corresponding method of the PPI::Document instance.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::Policy - Base class for all Policy modules

  • METHODS
  • DOCUMENTATION
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy - Base class for all Policy modules

DESCRIPTION

Perl::Critic::Policy is the abstract base class for all Policy objects. If you're developing your own Policies, your job is to implement and override its methods in a subclass. To work with the the Perl::Critic manpage engine, your implementation must behave as described below. For a detailed explanation on how to make new Policy modules, please see the the Perl::Critic::DEVELOPER manpage document included in this distribution.

METHODS

new(key1 = value1, key2 => value2 ... )>

Returns a reference to a new subclass of Perl::Critic::Policy. If your Policy requires any special arguments, they should be passed in here as key-value pairs. Users of perlcritic can specify these in their config file. Unless you override the new method, the default method simply returns a reference to an empty hash that has been blessed into your subclass.

violates( $element, $document )

Given a the PPI::Element manpage and a the PPI::Document manpage, returns one or more the Perl::Critic::Violation manpage objects if the $element violates this Policy. If there are no violations, then it returns an empty list. If the Policy encounters an exception, then it should croak with an error message and let the caller decide how to handle it.

violates() is an abstract method and it will abort if you attempt to invoke it directly. It is the heart of all Policy modules, and your subclass must override this method.

violation( $description, $explanation, $element )

Returns a reference to a new Perl::Critic::Violation object. The arguments are a description of the violation (as string), an explanation for the policy (as string) or a series of page numbers in PBP (as an ARRAY ref), a reference to the the PPI manpage element that caused the violation.

These are the same as the constructor to the Perl::Critic::Violation manpage, but without the severity. The Policy itself knows the severity.

applies_to()

Returns a list of the names of PPI classes that this Policy cares about. By default, the result is PPI::Element. Overriding this method in Policy subclasses should lead to significant performance increases.

default_severity()

Returns the default severity for violating this Policy. See the $SEVERITY constants in the Perl::Critic::Utils manpage for an enumeration of possible severity values. By default, this method returns $SEVERITY_LOWEST. Authors of Perl::Critic::Policy subclasses should override this method to return a value that they feel is appropriate for their Policy. In general, Polices that are widely accepted or tend to prevent bugs should have a higher severity than those that are more subjective or cosmetic in nature.

get_severity()

Returns the severity of violating this Policy. If the severity has not been explicitly defined by calling set_severity, then the default_severity is returned. See the $SEVERITY constants in the Perl::Critic::Utils manpage for an enumeration of possible severity values.

set_severity( $N )

Sets the severity for violating this Policy. Clients of Perl::Critic::Policy objects can call this method to assign a different severity to the Policy if they don't agree with the default_severity. See the $SEVERITY constants in the Perl::Critic::Utils manpage for an enumeration of possible values.

DOCUMENTATION

When your Policy module first uses the Perl::Critic::Violation manpage, it will try and extract the DESCRIPTION section of your Policy module's POD. This information is displayed by Perl::Critic if the verbosity level is set accordingly. Therefore, please include a DESCRIPTION section in the POD for any Policy modules that you author. Thanks.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitLvalueSubstr.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr

DESCRIPTION

Conway discourages the use of substr() as an lvalue, instead recommending that the 4-argument version of substr() be used instead.

  substr($something, 1, 2) = $newvalue;     # not ok
  substr($something, 1, 2, $newvalue);      # ok

AUTHOR

Graham TerMarsch <graham@howlingfrog.com>

COPYRIGHT

Copyright (C) 2005-2006 Graham TerMarsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitSleepViaSelect.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect

DESCRIPTION

Conway discourages the use of select() for performing non-integer sleeps. Although documented in the perlfunc manpage, it's something that generally requires the reader to read perldoc -f select to figure out what it should be doing. Instead, Conway recommends that you use the Time::HiRes module when you want to sleep.

  select undef, undef, undef, 0.25;         # not ok

  use Time::HiRes;
  sleep( 0.25 );                            # ok

SEE ALSO

the Time::HiRes manpage.

AUTHOR

Graham TerMarsch <graham@howlingfrog.com>

COPYRIGHT

Copyright (C) 2005-2006 Graham TerMarsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringyEval.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval

DESCRIPTION

The string form of eval is recompiled every time it is executed, whereas the block form is only compiled once. Also, the string form doesn't give compile-time warnings.

  eval "print $foo";        #not ok
  eval {print $foo};        #ok

SEE ALSO

the Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep manpage

the Perl::Critic::Policy::ControlStrucutres::RequireBlockMap manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringySplit.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitStringySplit

DESCRIPTION

The split function always interprets the PATTERN argument as a regular expression, even if you specify it as a string. This causes much confusion if the string contains regex metacharacters. So for clarity, always express the PATTERN argument as a regex.

  $string = 'Fred|Barney';
  @names = split '|', $string; #not ok, is ('F', 'r', 'e', 'd', '|', 'B', 'a' ...)
  @names = split m/[|]/, $string; #ok, is ('Fred', Barney')

When the PATTERN is a single space the split function has special behavior, so Perl::Critic forgives that usage. See "perldoc -f split" for more information.

SEE ALSO

the Perl::Critic::Policy::ControlStrucutres::RequireBlockGrep manpage

the Perl::Critic::Policy::ControlStrucutres::RequireBlockMap manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitUniversalCan.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan

DESCRIPTION

  print UNIVERSAL::can($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
  print eval { $obj->can('Foo::Bar') } ? 'yes' : 'no';    #ok

As of Perl 5.9.3, the use of UNIVERSAL::can as a function has been deprecated and the method form is preferred instead. Formerly, the functional form was recommended because it gave valid results even when the object was undef or an unblessed scalar. However, the functional form makes it impossible for packages to override can(), a technique which is crucial for implementing mock objects and some facades.

See the CPAN module the UNIVERSAL::can manpage for a more thorough discussion of this topic.

SEE ALSO

the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa manpage

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitUniversalIsa.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa

DESCRIPTION

  print UNIVERSAL::isa($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
  print eval { $obj->isa('Foo::Bar') } ? 'yes' : 'no';    #ok

As of Perl 5.9.3, the use of UNIVERSAL::isa as a function has been deprecated and the method form is preferred instead. Formerly, the functional form was recommended because it gave valid results even when the object was undef or an unblessed scalar. However, the functional form makes it impossible for packages to override isa(), a technique which is crucial for implementing mock objects and some facades.

Another alternative to UNIVERSAL::isa is the _INSTANCE method of Param::Util, which is faster.

See the CPAN module the UNIVERSAL::isa manpage for an incendiary discussion of this topic.

SEE ALSO

the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan manpage

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockGrep.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep

DESCRIPTION

The expression forms of grep and map are awkward and hard to read. Use the block forms instead.

  @matches = grep  /pattern/,    @list;        #not ok
  @matches = grep { /pattern/ }  @list;        #ok

  @mapped = map  transform($_),    @list;      #not ok
  @mapped = map { transform($_) }  @list;      #ok

SEE ALSO

the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval manpage

the Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockMap.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap

DESCRIPTION

The expression forms of grep and map are awkward and hard to read. Use the block forms instead.

  @matches = grep   /pattern/,   @list;        #not ok
  @matches = grep { /pattern/ }  @list;        #ok

  @mapped = map   transform($_),   @list;      #not ok
  @mapped = map { transform($_) }  @list;      #ok

SEE ALSO

the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval manpage

the Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/BuiltinFunctions/RequireGlobFunction.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction

DESCRIPTION

Conway discourages the use of the <.. > construct for globbing, as it is easily confused with the angle bracket file input operator. Instead, he recommends the use of the glob() function as it makes it much more obvious what you're attempting to do.

  @files = <*.pl>;              # not ok
  @files = glob( "*.pl" );      # ok

AUTHOR

Graham TerMarsch <graham@howlingfrog.com>

COPYRIGHT

Copyright (C) 2005-2006 Graham TerMarsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/BuiltinFunctions/RequireSimpleSortBlock.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock

DESCRIPTION

Conway advises that sort functions should be simple. Any complicated operations on list elements should be computed and cached (perhaps via a Schwartzian Transform) before the sort, rather than computed inside the sort block, because the sort block is called N log N times instead of just N times.

This policy prohibits the most blatant case of complicated sort blocks: multiple statements. Future policies may wish to examine the sort block in more detail -- looking for subroutine calls or large numbers of operations.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (C) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/ClassHierarchies/ProhibitAutoloading.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ClassHierarchies::ProhibitAutoloading

DESCRIPTION

Declaring a subroutine with the name "AUTOLOAD" will violate this Policy. The AUTOLOAD mechanism is an easy way to generate methods for your classes, but unless they are carefully written, those classes are difficult to inherit from. And over time, the AUTOLOAD method will become more and more complex as it becomes responsible for dispatching more and more functions. You're better off writing explicit accessor methods. Editor macros can help make this a little easier.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (C) 2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/ClassHierarchies/ProhibitExplicitISA.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ClassHierarchies::ProhibitExplicitISA

DESCRIPTION

Conway recommends employing use base qw(Foo) instead of the usual our @ISA = qw(Foo) because the former happens at compile time and the latter at runtime. The base pragma also automatically loads Foo for you so you save a line of easily-forgotten code.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (C) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/ClassHierarchies/ProhibitOneArgBless.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ClassHierarchies::ProhibitOneArgBless

DESCRIPTION

Always use the two-argument form of bless because it allows subclasses to inherit your constructor.

  sub new {
      my $class = shift;
      my $self = bless {};          # not ok
      my $self = bless {}, $class;  # ok
      return $self;
  }

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (C) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/CodeLayout/ProhibitHardTabs.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::CodeLayout::ProhibitHardTabs

DESCRIPTION

Putting hard tabs in your source code (or POD) is one of the worst things you can do to your co-workers and colleagues, especially if those tabs are anywhere other than a leading position. Because various applications and devices represent tabs differently, they can cause you code to look vastly different to other people. Any decent editor can be configured to expand tabs into spaces. the Perl::Tidy manpage also does this for you.

This Policy catches all tabs in your source code, including POD, quotes, and HEREDOCS. The contents of the __DATA__ section are not examined. Tabs in a leading position are allowed, but if you want to forbid all tabs everywhere, put this to your .perlcriticrc file:

  [CodeLayout::ProhibitHardTabs]
  allow_leading_tabs = 0

Beware that Perl::Critic may report the location of the string that contains the tab, not the actual location of the tab, so you may need to do some hunting. I'll try and fix this in the future.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/CodeLayout/ProhibitParensWithBuiltins.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins

DESCRIPTION

Conway suggests that all built-in functions be called without parentheses around the argument list. This reduces visual clutter and disambiguates built-in functions from user functions. Exceptions are made for my, local, and our which require parentheses when called with multiple arguments.

  open($handle, '>', $filename); #not ok
  open $handle, '>', $filename;  #ok

  split(/$pattern/, @list); #not ok
  split /$pattern/, @list;  #ok

NOTES

Coding with parens can sometimes lead to verbose and awkward constructs, so I think the intent of Conway's guideline is to remove only the unnecessary parens. This policy makes exceptions for some common situations where parens are usually required. However, you may find other situations where the parens are necessary to enforce precedence, but they cause still violations. In those cases, consider using the '## no critic' comments to silence Perl::Critic.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/CodeLayout/ProhibitQuotedWordLists.pm

  • CONSTRUCTOR
  • NOTES
  • IMPORTANT CHANGES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists

DESCRIPTION

Conway doesn't mention this, but I think qw() is an underused feature of Perl. Whenever you need to declare a list of one-word literals, the qw() operator is wonderfully concise, and makes it easy to add to the list in the future.

  @list = ('foo', 'bar', 'baz');  #not ok
  @list = qw(foo bar baz);        #ok

CONSTRUCTOR

This Policy accepts an additional key-value pair in the constructor. The key must be min_elements and the value is the minimum number of elements in the list. Lists with fewer elements will be overlooked by this Policy. The default is 2. Users of Perl::Critic can configure this in their .perlcriticrc file like this:

  [CodeLayout::ProhibitQuotedWordLists]
  min_elements = 4

NOTES

In the PPI parlance, a "list" is almost anything with parens. I've tried to make this Policy smart by targeting only "lists" that could be sensibly expressed with qw(). However, there may be some edge cases that I haven't covered. If you find one, send me a note.

IMPORTANT CHANGES

This policy was formerly called RequireQuotedWords which seemed a little counterintuitive. If you get lots of "Cannot load policy module" errors, then you probably need to change RequireQuotedWords to ProhibitQuotedWordLists in your .perlcriticrc file.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm

  • CONSTRUCTOR
  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::CodeLayout::RequireTidyCode

DESCRIPTION

Conway does make specific recommendations for whitespace and curly-braces in your code, but the most important thing is to adopt a consistent layout, regardless of the specifics. And the easiest way to do that is to use the Perl::Tidy manpage. This policy will complain if you're code hasn't been run through Perl::Tidy.

CONSTRUCTOR

This Policy accepts an additional key-value pair in the constructor. The key must be perltidyrc and the value is the filename of a Perl::Tidy configuration file. The default is undef, which tells Perl::Tidy to look in it's default location. Users of Perl::Critic can configure this in their .perlcriticrc file like this:

  [CodeLayout::RequireTidyCode]
  perltidyrc = /usr/share/perltidy.conf

As a special case, setting perltidyrc to the empty string tells Perl::Tidy not to load any configuration file at all and just use Perl::Tidy's own default style.

  [CodeLayout::RequireTidyCode]
  perltidyrc =

NOTES

the Perl::Tidy manpage is not included in the Perl::Critic distribution. The latest version of Perl::Tidy can be downloaded from CPAN. If Perl::Tidy is not installed, this policy is silently ignored.

SEE ALSO

the Perl::Tidy manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/CodeLayout/RequireTrailingCommas.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::CodeLayout::RequireTrailingCommas

DESCRIPTION

Conway suggests that all elements in a multi-line list should be separated by commas, including the last element. This makes it a little easier to re-order the list by cutting and pasting.

  my @list = ($foo,
              $bar,
              $baz);  #not ok

  my @list = ($foo,
              $bar,
              $baz,); #ok

NOTES

In the PPI parlance, a "list" is almost anything with parens. I've tried to make this Policy smart by targeting only "lists" that have at least one element and are being assigned to something. However, there may be some edge cases that I haven't covered. If you find one, send me a note.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitCStyleForLoops.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitCStyleForLoops

DESCRIPTION

The 3-part for loop that Perl inherits from C is butt-ugly, and only really necessary if you need irregular counting. The very Perlish .. operator is much more elegant and readable.

  for($i=0; $i<=$max; $i++){      #ick!
      do_something($i);
  }

  for(0..$max){                   #very nice
    do_something($_);
  }

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitCascadingIfElse.pm

  • CONSTRUCTOR
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse

DESCRIPTION

Long if-elsif chains are hard to digest, especially if they are longer than a single page or screen. If testing for equality, use a hash lookup instead. See the Switch manpage for another approach.

  if ($condition1) {         #ok
      $foo = 1;
  }
  elseif ($condition2) {     #ok
      $foo = 2;
  }
  elsif ($condition3) {      #ok
      $foo = 3;
  }
  elsif ($condition4) {      #too many!
      $foo = 4;
  }
  else{                      #ok
      $foo = $default;
  }

CONSTRUCTOR

This policy accepts an additional key-value pair in the new method. The key should be max_elsif and the value should be an integer indicating the maximum number of elsif alternatives to allow. The default is 2. When using the the Perl::Critic manpage engine, these can be configured in the .perlcriticrc file like this:

 [ControlStructures::ProhibitCascadingIfElse]
 max_elsif = 3

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitDeepNests.pm

  • CONSTRUCTOR
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitDeepNests

DESCRIPTION

Deeply nested code is often hard to understand and may be a sign that it needs to be refactored. There are several good books on how to refactor code. I like Martin Fowler's "Refactoring: Improving The Design of Existing Code".

CONSTRUCTOR

This policy accepts an additional key-value pair in the new method. The key should be max_nests and the value should be an integer indicating the maximum number nested structures to allow. Each for-loop, if-else, while, and until block is counted as one nest. Postfix forms of these constructs are not counted. The default maximum is 5. When using the the Perl::Critic manpage engine, these can be configured in the .perlcriticrc file like this:

 [ControlStructures::ProhibitDeepNests]
 max_nests = 3

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitPostfixControls.pm

  • CONSTRUCTOR
  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls

DESCRIPTION

Conway discourages using postfix control structures (if, for, unless, until, while). The unless and until controls are particularly evil because they lead to double-negatives that are hard to comprehend. The only tolerable usage of a postfix if is when it follows a loop break such as last, next, redo, or continue.

  do_something() if $condition;         #not ok
  if($condition){ do_something() }      #ok

  do_something() while $condition;      #not ok
  while($condition){ do_something() }   #ok

  do_something() unless $condition;     #not ok
  do_something() unless ! $condition;   #really bad
  if(! $condition){ do_something() }    #ok

  do_something() until $condition;      #not ok
  do_something() until ! $condition;    #really bad
  while(! $condition){ do_something() } #ok

  do_something($_) for @list;           #not ok

 LOOP:
  for my $n (0..100){
      next if $condition;               #ok
      last LOOP if $other_condition;    #also ok
  }

CONSTRUCTOR

This policy accepts an additional key-value pair in the new method. The key should be 'allow' and the value is a string of space-delimited keywords. Choose from if, for, unless, until,and while. When using the the Perl::Critic manpage engine, these can be configured in the .perlcriticrc file like this:

 [ControlStructures::ProhibitPostfixControls]
 allow = for if until

By default, all postfix control keywords are prohibited.

NOTES

The die, croak, and confess functions are frequently used as flow-controls just like next or last. So this Policy does permit you to use a postfix if when the statement begins with one of those functions. It is also pretty common to use warn, carp, and cluck with a postfix if, so those are allowed too.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitUnlessBlocks.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks

DESCRIPTION

Conway discourages using unless because it leads to double-negatives that are hard to understand. Instead, reverse the logic and use if.

  unless($condition) { do_something() } #not ok
  unless(! $no_flag) { do_something() } #really bad
  if( ! $condition)  { do_something() } #ok

This Policy only covers the block-form of unless. For the postfix variety, see ProhibitPostfixControls.

SEE ALSO

the Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitUnreachableCode.pm

  • EXAMPLES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitUnreachableCode

DESCRIPTION

This policy prohibits code following a statement which unconditionally alters the program flow. This includes calls to exit, die, return, next, last and goto. Due to common usage, croak and confess from the Carp manpage are also included.

Code is reachable if any of the following conditions are true:

  • Flow-altering statement has a conditional attached to it
  • Statement is on the right side of an operator &&, ||, and, or or.
  • Code is prefixed with a label (can potentially be reached via goto)
  • Code is a subroutine

EXAMPLES

  # not ok

  exit;
  print "123\n";

  # ok

  exit if !$xyz;
  print "123\n";

  # not ok

  for ( 1 .. 10 ) {
      next;
      print 1;
  }

  # ok

  for ( 1 .. 10 ) {
      next if $_ == 5;
      print 1;
  }

  # not ok

  sub foo {
      my $bar = shift;
      return;
      print 1;
  }

  # ok

  sub foo {
      my $bar = shift;
      return if $bar->baz();
      print 1;
  }

  # not ok

  die;
  print "123\n";

  # ok

  die;
  LABEL: print "123\n";

  # not ok

  croak;
  do_something();

  # ok

  croak;
  sub do_something {}

SEE ALSO

the Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls manpage

AUTHOR

Peter Guzis <pguzis@cpan.org>

COPYRIGHT

Copyright (c) 2006 Peter Guzis. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ControlStructures/ProhibitUntilBlocks.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ControlStructures::ProhibitUntilBlocks

DESCRIPTION

Conway discourages using until because it leads to double-negatives that are hard to understand. Instead, reverse the logic and use while.

  until($condition)     { do_something() } #not ok
  until(! $no_flag)     { do_something() } #really bad
  while( ! $condition)  { do_something() } #ok

This Policy only covers the block-form of until. For the postfix variety, see ProhibitPostfixControls.

SEE ALSO

the Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Documentation/RequirePodAtEnd.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Documentation::RequirePodAtEnd

DESCRIPTION

Perl stops processing code when it sees an __END__ statement. So, to save processing time, it's faster to put documentation after the __END__. Also, writing all the POD in one place usually leads to a more cohesive document, rather than being forced to follow the layout of your code. This policy issues violations if any POD is found before an __END__.

NOTES

Some folks like to use =for, and =begin, and =end tags to create block comments in-line with their code. Since those tags aren't usually part of the documentation, this Policy does allows them to appear before the __END__ statement.

  =begin comments
  frobulate()
  Accepts:  A list of things to frobulate
  Returns:  True if succesful
  =end comments
  sub frobulate { ... }

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/Documentation/RequirePodSections.pm

  • DEFAULTS
  • CONSTRUCTOR
  • LIMITATIONS
  • SUBROUTINES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Documentation::RequirePodSections

DESCRIPTION

This Policy requires your POD to contain certain =head1 sections. If the file doesn't contain any POD at all, then this Policy does not apply. Tools like the Module::Starter manpage make it really easy to ensure that every module has the same documentation framework, and they can save you lots of keystrokes.

DEFAULTS

Different POD sections are required, depending on whether the file is a library or script (which is determined by the presence or absence of a perl shebang line).

             Default Required POD Sections
   Perl Libraries                     Perl Scripts
   ------------------------------------------------------
   NAME                               NAME
   VERSION                            VERSION
   SYNOPSIS                           USAGE
   DESCRIPTION                        DESCRIPTION
   SUBROUNTES/METHODS                 REQUIRED ARGUMENTS
                                      OPTIONS
   DIAGNOSTICS                        DIAGNOSTICS
                                      EXIT STATUS
   CONFIGURATION                      CONFIGURATION
   DEPENDENCIES                       DEPENDENCIES
   INCOMPATIBILITIES                  INCOMPATIBILITIES
   BUGS AND LIMITATIONS               BUGS AND LIMITATIONS
   AUTHOR                             AUTHOR
   LICENSE AND COPYRIGHT              LICENSE AND COPYRIGHT

CONSTRUCTOR

This policy accepts two additional key-value pairs in the new method. The keys can be either 'script_sections' or 'lib_sections', and the value is always a string of pipe-delimited POD section names. These can be configured in the .perlcriticrc file like this:

 [Documentation::RequirePodSections]
 lib_sections    = NAME | SYNOPSIS | BUGS AND LIMITATIONS | AUTHOR
 script_sections = NAME | USAGE | OPTIONS | EXIT STATUS | AUTHOR

LIMITATIONS

Currently, this Policy does not look for the required POD sections below the =head1 level. Also, it does not require the sections to appear in any particular order.

SUBROUTINES

default_script_sections()

Returns a list of the default POD section that are required for Perl scripts. A Perl script is anything that contains a shebang line that looks like /perl/.

default_lib_sections()

Returns a list of the default POD section that are required for Perl libraries and modules.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/ErrorHandling/RequireCarping.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ErrorHandling::RequireCarping

DESCRIPTION

The die and warn functions both report the file and line number where the exception occurred. But if someone else is using your subroutine, they usually don't care where your code blew up. Instead, they want to know where their code invoked the subroutine. The the Carp manpage module provides alternative methods that report the exception from the caller's file and line number.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitBacktickOperators.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitBacktickOperators

DESCRIPTION

Backticks are super-convenient, especially for CGI programs, but I find that they make a lot of noise by filling up STDERR with messages when they fail. I think its better to use IPC::Open3 to trap all the output and let the application decide what to do with it.

  use IPC::Open3 'open3';
  $SIG{CHLD} = 'IGNORE';

  @output = `some_command`;                      #not ok

  my ($writer, $reader, $err);
  open3($writer, $reader, $err, 'some_command'); #ok;
  @output = <$reader>;  #Output here
  @errors = <$err>;     #Errors here, instead of the console

NOTES

This policy also prohibits the generalized form of backticks seen as qx{}.

See the perlipc manpage for more discussion on using wait() instead of $SIG{CHLD} = 'IGNORE'.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitBarewordFileHandles.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitBarewordFileHandles

DESCRIPTION

Using bareword symbols to refer to file handles is particularly evil because they are global, and you have no idea if that symbol already points to some other file handle. You can mitigate some of that risk by localizing the symbol first, but that's pretty ugly. Since Perl 5.6, you can use an undefined scalar variable as a lexical reference to an anonymous filehandle. Alternatively, see the the IO::Handle manpage or the IO::File manpage or the FileHandle manpage modules for an object-oriented approach.

  open FH, '<', $some_file;           #not ok
  open my $fh, '<', $some_file;       #ok
  my $fh = IO::File->new($some_file); #ok

SEE ALSO

the IO::Handle manpage

the IO::File manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (C) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitInteractiveTest.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitInteractiveTest

DESCRIPTION

The -t operator is fragile and complicated. When you are testing whether STDIN is interactive, It's much more robust to use well-tested CPAN modules like the IO::Interactive manpage.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (C) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitOneArgSelect.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitOneArgSelect

DESCRIPTION

Conway discourages the use of a raw select() when setting autoflushes. We'll extend that further by simply prohibiting the one-argument form of select() entirely; if you really need it you should know when/where/why that is. For performing autoflushes, Conway recommends the use of IO::Handle instead.

  select((select($fh), $|=1)[0]);     # not ok
  select $fh;                         # not ok

   use IO::Handle;
   $fh->autoflush();                   # ok
   *STDOUT->autoflush();               # ok

SEE ALSO

the IO::Handle manpage.

AUTHOR

Graham TerMarsch <graham@howlingfrog.com>

COPYRIGHT

Copyright (C) 2005-2006 Graham TerMarsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitReadlineInForLoop.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop

DESCRIPTION

Using the readline operator in a for or foreach loop is very slow. The iteration list of the loop creates a list context, which causes the readline operator to read the entire input stream before iteration even starts. Instead, just use a while loop, which only reads one line at a time.

  for my $line ( <$file_handle> ){ do_something($line) }      #not ok
  while ( my $line = <$file_handle> ){ do_something($line) }  #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/InputOutput/ProhibitTwoArgOpen.pm

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::ProhibitTwoArgOpen

DESCRIPTION

The three-argument form of open (introduced in Perl 5.6) prevents subtle bugs that occur when the filename starts with funny characters like '>' or '<'. The the IO::File manpage module provides a nice object-oriented interface to filehandles, which I think is more elegant anyway.

  open( $fh, '>output.txt' );          # not ok
  open( $fh, q{>}, 'output.txt );      # ok

  use IO::File;
  my $fh = IO::File->new( 'output.txt', q{>} ); # even better!

NOTES

The only time you should use the two-argument form is when you re-open STDIN, STDOUT, or STDERR. But for now, this Policy doesn't provide that loophole.

SEE ALSO

the IO::Handle manpage

the IO::File manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (C) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/InputOutput/RequireBracedFileHandleWithPrint.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint

DESCRIPTION

The print function has a unique syntax that supports an optional file handle argument. Conway suggests wrapping this argument in braces to make it visually stand out from the other arguments. When you put braces around any of the special package-level file handles like STDOUT, STDERR, and DATA, you must the '*' sigil or else it won't compile under use strict 'subs'.

  print $FH   "Mary had a little lamb\n";  #not ok
  print {$FH} "Mary had a little lamb\n";  #ok

  print   STDERR   $foo, $bar, $baz;  #not ok
  print  {STDERR}  $foo, $bar, $baz;  #won't compile under 'strict'
  print {*STDERR}  $foo, $bar, $baz;  #perfect!

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Miscellanea/ProhibitFormats.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Miscellanea::ProhibitFormats

DESCRIPTION

Formats are one of the oldest features of Perl. Unfortunately, they suffer from several limitations. Formats are static and cannot be easily defined at run time. Also, formats depend on several obscure global variables.

For more modern reporting tools, consider using one of the template frameworks like Template or try the the Perl6::Form manpage module.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Miscellanea/ProhibitTies.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Miscellanea::ProhibitTies

DESCRIPTION

Conway discourages using tie to bind Perl primitive variables to user-defined objects. Unless the tie is done close to where the object is used, other developers probably won't know that the variable has special behavior. If you want to encapsulate complex behavior, just use a proper object or subroutine.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Miscellanea/RequireRcsKeywords.pm

  • CONSTRUCTOR
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Miscellanea::RequireRcsKeywords

DESCRIPTION

Every code file, no matter how small, should be kept in a source-control repository. Adding the magical RCS keywords to your file helps the reader know where the file comes from, in case he or she needs to modify it. This Policy scans your file for comments that look like this:

  # $Revision: 663 $
  # $Source: /myproject/lib/foo.pm $

A common practice is to use the Revision keyword to automatically define the $VERSION variable like this:

  our ($VERSION) = '$Revision: 663 $' =~ m{ \$Revision: \s+ (\S+) }x;

CONSTRUCTOR

By default, this policy only requires the Revision, Source, and Date keywords. To specify alternate keywords, pass them into the constructor as a key-value pair, where the key is 'keywords' and the value is a whitespace delimited series of keywords (without the dollar-signs). Or specify them in your .perlcriticrc file like this:

  [Miscellanea::RequireRcsKeywords]
  keywords = Revision Source Date Author Id

See the documentation on RCS for a list of supported keywords. Many source control systems are descended from RCS, so the keywords supported by CVS and Subversion are probably the same.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/ProhibitAutomaticExportation.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::ProhibitAutomaticExportation

DESCRIPTION

When using the Exporter manpage, symbols placed in the @EXPORT variable are automatically exported into the caller's namespace. Although convenient, this practice is not polite, and may cause serious problems if the caller declares the same symbols. The best practice is to place your symbols in @EXPORT_OK or %EXPORT_TAGS and let the caller choose exactly which symbols to export.

  package Foo;

  use base qw(Exporter);
  our @EXPORT      = qw(&foo &bar);                  # not ok
  our @EXPORT_OK   = qw(&foo &bar);                  # ok
  our %EXPORT_TAGS = ( all => [ qw(&foo &bar) ] );   # ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/ProhibitEvilModules.pm

  • CONSTRUCTOR
  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::ProhibitEvilModules

DESCRIPTION

Use this policy if you wish to prohibit the use of specific modules. These may be modules that you feel are deprecated, buggy, unsupported, insecure, or just don't like.

CONSTRUCTOR

This policy accepts an additional key-value pair in the new method. The key should be 'modules' and the value is a string of space-delimited fully qualified module names. These can be configured in the .perlcriticrc file like this:

 [Modules::ProhibitEvilModules]
 modules = Getopt::Std  Autoload

If any module name in your configuration is braced with slashes, it is interpreted as a regular expression. So any module that matches m/$module_name/ will be forbidden. For example:

  [Modules::ProhibitEvilModules]
  modules = /Acme::/

would cause all modules that match m/Acme::/ to be forbidden. You can add any of the imxs switches to the end of the pattern, but beware that your pattern should not contain spaces, lest the parser get confused.

By default, there are no prohibited modules (although I can think of a few that should be).

NOTES

Note that this policy doesn't apply to pragmas. Future versions may allow you to specify an alternative for each prohibited module, which can be suggested by the Perl::Critic manpage.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/ProhibitMultiplePackages.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::ProhibitMultiplePackages

DESCRIPTION

Conway doesn't specifically mention this, but I find it annoying when there are multiple packages in the same file. When searching for methods or keywords in your editor, it makes it hard to find the right chunk of code, especially if each package is a subclass of the same base.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/RequireBarewordIncludes.pm

  • NOTES
  • CREDITS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::RequireBarewordIncludes

DESCRIPTION

When including another module (or library) via the require or use statements, it is best to identify the module (or library) using a bareword rather than an explicit path. This is because paths are usually not portable from one machine to another. Also, Perl automatically assumes that the filename ends in '.pm' when the library is expressed as a bareword. So as a side-effect, this Policy encourages people to write '*.pm' modules instead of the old-school '*.pl' libraries.

  use 'My/Perl/Module.pm';  #not ok
  use My::Perl::Module;     #ok

NOTES

This Policy is a replacement for ProhibitRequireStatements, which completely banned the use of require for the sake of eliminating the old '*.pl' libraries from Perl4. Upon further consideration, I realized that require is quite useful and necessary to enable run-time loading. Thus, RequireBarewordIncludes does allow you to use require, but still encourages you to write '*.pm' modules.

Sometimes, you may want to load modules at run-time, but you don't know at design-time exactly which module you will need to load (the Perl::Critic manpage is an example of this). In that case, just attach the '## no critic' pseudo-pragma like so:

  require $module_name;  ## no critic

CREDITS

Chris Dolan <cdolan@cpan.org> was instrumental in identifying the correct motivation for and behavior of this Policy. Thanks Chris.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/RequireEndWithOne.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::RequireEndWithOne

DESCRIPTION

All files included via use or require must end with a true value to indicate to the caller that the include was successful. The standard practice is to conclude your .pm files with 1;, but some authors like to get clever and return some other true value like return "Club sandwich";. We cannot tolerate such frivolity! OK, we can, but we don't recommend it since it confuses the newcomers.

AUTHOR

Chris Dolan cdolan@cpan.org

Some portions cribbed from the Perl::Critic::Policy::Modules::RequireExplicitPackage manpage.

COPYRIGHT

Copyright (c) 2005-2006 Chris Dolan and Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm

  • IMPORTANT CHANGES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::RequireExplicitPackage

DESCRIPTION

In general, the first statement of any Perl module or library should be a package statement. Otherwise, all the code that comes before the package statement is getting executed in the caller's package, and you have no idea who that is. Good encapsulation and common decency require your module to keep its innards to itself.

As for scripts, most people understand that the default package is main, so this Policy doesn't apply to files that begin with a perl shebang. If you want to require an explicit package declaration in all files, including programs, then add the following to your .perlcriticrc file

  [Modules::RequireExplicitPackage]
  exempt_scripts = 0

There are some valid reasons for not having a package statement at all. But make sure you understand them before assuming that you should do it too.

IMPORTANT CHANGES

This policy was formerly called ProhibitUnpackagedCode which sounded a bit odd. If you get lots of "Cannot load policy module" errors, then you probably need to change ProhibitUnpackagedCode to RequireExplicitPackage in your .perlcriticrc file.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Modules/RequireVersionVar.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Modules::RequireVersionVar

DESCRIPTION

Every Perl file (modules, libraries, and programs) should have a $VERSION variable. The $VERSION allows clients to insist on a particular revision of your file like this:

  use SomeModule 2.4;  #Only loads version 2.4

This Policy scans your file for any package variable named $VERSION. I'm assuming that you are using strict, so you'll have to declare it like one of these:

  our $VERSION = 1.01;
  $MyPackage::VERSION = 1.01;
  use vars qw($VERSION);

A common practice is to use the $Revision: 663 $ keyword to automatically define the $VERSION variable like this:

  our ($VERSION) = '$Revision: 663 $' =~ m{ \$Revision: \s+ (\S+) }x;

NOTES

Conway recommends using the version pragma instead of raw numbers or 'v-strings.' However, this Policy only insists that the $VERSION be defined somehow. I may try to extend this in the future.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/NamingConventions/ProhibitAmbiguousNames.pm

  • CONSTRUCTOR
  • METHODS
  • BUGS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::NamingConventions::ProhibitAmbiguousNames

DESCRIPTION

Conway lists a collection of English words which are highly ambiguous as variable or subroutine names. For example, $last can mean previous or final.

This policy tests against a list of ambiguous words for variable names.

CONSTRUCTOR

This Policy accepts an additional key-value pair in the constructor, The key is 'forbid' and the value is a string of forbidden words separated by spaces. Any specified list replaces the default list.

The default list is:

    last set left right no abstract contract record second close bases

For example, to override the default list:

    my $pkg = 'Perl::Critic::Policy::NamingConventions::ProhibitAmbiguousNames';
    my $policy = $pkg->new(forbid => 'last set');

METHODS

default_forbidden_words()

This can be called as a class or instance method. It returns the list of words that are forbidden by default. This list can be overridden via a perlcriticrc file.

For example, if you decide that bases is an OK name for variables (e.g. in bioinformatics), then put something like the following in $HOME/.perlcriticrc:

    [NamingConventions::ProhibitAmbiguousNames]
    forbid = last set left right no abstract contract record second close

BUGS

Currently this policy checks the entire variable and subroutine name, not parts of the name. For example, it catches $last but not $last_record. Hopefully future versions will catch both cases.

Some variable statements will be false positives if they have assignments where the right hand side uses forbidden names. For example, in this case the last incorrectly triggers a violation.

    my $previous_record = $Foo::last;

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/NamingConventions/ProhibitMixedCaseSubs.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs

DESCRIPTION

Conway's recommended naming convention is to use lower-case words separated by underscores. Well-recognized acronyms can be in ALL CAPS, but must be separated by underscores from other parts of the name.

  sub foo_bar{}   #ok
  sub foo_BAR{}   #ok
  sub FOO_bar{}   #ok
  sub FOO_BAR{}   #ok

  sub FooBar {}   #not ok
  sub FOObar {}   #not ok
  sub fooBAR {}   #not ok
  sub fooBar {}   #Not ok

SEE ALSO

the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseVars manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/NamingConventions/ProhibitMixedCaseVars.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseVars

DESCRIPTION

Conway's recommended naming convention is to use lower-case words separated by underscores. Well-recognized acronyms can be in ALL CAPS, but must be separated by underscores from other parts of the name.

  my $foo_bar   #ok
  my $foo_BAR   #ok
  my @FOO_bar   #ok
  my %FOO_BAR   #ok
  my $FooBar   #not ok
  my $FOObar   #not ok
  my @fooBAR   #not ok
  my %fooBar   #not ok

SEE ALSO

the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/References/ProhibitDoubleSigils.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::References::ProhibitDoubleSigils

DESCRIPTION

When dereferencing a reference, put braces around the reference to separate the sigils. Especially for newbies, the braces eliminate any potential confusion about the relative precedence of the sigils.

  push @$array_ref, 'foo', 'bar', 'baz';      #not ok
  push @{ $array_ref }, 'foo', 'bar', 'baz';  #ok

  foreach ( keys %$hash_ref ){}               #not ok
  foreach ( keys %{ $hash_ref } ){}           #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/RegularExpressions/ProhibitCaptureWithoutTest.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::RegularExpressions::ProhibitCaptureWithoutTest

DESCRIPTION

If a regexp match fails, then any capture variables ($1, $2, ...) will be undefined. Therefore it's important to check the return value of a match before using those variables.

This policy checks that capture variables are inside a conditional and do not follow an regexps.

This policy does not check whether that conditional is actually testing a regexp result, nor does it check whether a regexp actually has a capture in it. Those checks are too hard.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (C) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


site/lib/Perl/Critic/Policy/RegularExpressions/RequireExtendedFormatting.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::RegularExpressions::RequireExtendedFormatting

DESCRIPTION

Extended regular expression formatting allows you mix whitespace and comments into the pattern, thus making them much more readable.

    # Match a single-quoted string efficiently...

    m{'[^\\']*(?:\\.[^\\']*)*'};  #Huh?

    #Same thing with extended format...

    m{ '           #an opening single quote
       [^\\']      #any non-special chars (i.e. not backslash or single quote)
       (?:         #then all of...
          \\ .     #   any explicitly backslashed char
          [^\\']*  #   followed by an non-special chars
       )*          #...repeated zero or more times
       '           # a closing single quote
     }x;

NOTES

For common regular expressions like e-mail addresses, phone numbers, dates, etc., have a look at the the Regex::Common manpage module. Also, be cautions about slapping modifier flags onto existing regular expressions, as they can drastically alter their meaning. See http://www.perlmonks.org/ for an interesting discussion on the effects of blindly modifying regular expression flags.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/RegularExpressions/RequireLineBoundaryMatching.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::RegularExpressions::RequireLineBoundaryMatching

DESCRIPTION

Folks coming from a sed or awk background tend to assume that '$' and '^' match the beginning and and of the line, rather than then beginning and ed of the string. Adding the '/m' flag to your regex makes it behave as most people expect it should.

  my $match = m{ ^ $pattern $ }x;  #not ok
  my $match = m{ ^ $pattern $ }xm; #ok

NOTES

For common regular expressions like e-mail addresses, phone numbers, dates, etc., have a look at the the Regex::Common manpage module. Also, be cautions about slapping modifier flags onto existing regular expressions, as they can drastically alter their meaning. See http://www.perlmonks.org/ for an interesting discussion on the effects of blindly modifying regular expression flags.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProhibitAmpersandSigils.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProhibitAmpersandSigils

DESCRIPTION

Since Perl 5, the ampersand sigil is completely optional when invoking subroutines. And it's easily confused with the bitwise 'and' operator.

  @result = &some_function(); #Not ok
  @result = some_function();  #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProhibitBuiltinHomonyms.pm

  • CAVEATS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProhibitBuiltinHomonyms

DESCRIPTION

Common sense dictates that you shouldn't declare subroutines with the same name as one of Perl's built-in functions. See `perldoc perlfunc` for a list of built-ins.

  sub open {}  #not ok
  sub exit {}  #not ok
  sub print {} #not ok

  #You get the idea...

Exceptions are made for BEGIN, END, INIT and CHECK blocks, as well as AUTOLOAD, DESTROY, and import subroutines.

CAVEATS

It is reasonable to declare an object method with the same name as a Perl built-in function, since they are easily distinguished from each other. However, at this time, Perl::Critic cannot tell whether a subroutine is static or an object method.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProhibitExcessComplexity.pm

  • CONSTRUCTOR
  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity

DESCRIPTION

All else being equal, complicated code is more error-prone and more expensive to maintain than simpler code. The first step towards managing complexity is to establish formal complexity metrics. One such metric is the McCabe score, which describes the number of possible paths through a subroutine. This Policy approximates the McCabe score by summing the number of conditional statements and operators within a subroutine. Research has shown that a McCabe score higher than 20 is a sign of high-risk, potentially untestable code. See http://www.sei.cmu.edu/str/descriptions/cyclomatic_body.html for some discussion about the McCabe number and other complexity metrics.

The usual prescription for reducing complexity is to refactor code into smaller subroutines. Mark Dominus book "Higher Order Perl" also describes callbacks, recursion, memoization, iterators, and other techniques that help create simple and extensible Perl code.

CONSTRUCTOR

This Policy accepts an additional key-value pair in the new method. The key is 'max_mccabe' and the value is the maximum acceptable McCabe score. Any subroutine with a McCabe score higher than this number will generate a policy violation. The default is 20. Users of the Perl::Critic engine can configure this in their .perlcriticrc like this:

  [Subroutines::ProhibitExcessComplexity]
  max_mccabe = 30

NOTES

  "Everything should be made as simple as possible, but no simpler."
                                                  -- Albert Einstein

Complexity is subjective, but formal complexity metrics are still incredibly valuable. Every problem has an inherent level of complexity, so it is not necessarily optimal to minimize the McCabe number. So don't get offended if your code triggers this Policy. Just consider if there might be a simpler way to get the job done.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProhibitExplicitReturnUndef.pm

  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProhibitExplicitReturnUndef

DESCRIPTION

Returning undef upon failure from a subroutine is pretty common. But if the subroutine is called in list context, an explicit return undef; statement will return a one-element list containing (undef). Now if that list is subsequently put in a boolean context to test for failure, then it evaluates to true. But you probably wanted it to be false.

  sub read_file {
      my $file = shift;
      -f $file || return undef;  #file doesn't exist!

      #Continue reading file...
  }
  #and later...

  if ( my @data = read_file($filename) ){

      # if $filename doesn't exist,
      # @data will be (undef),
      # but I'll still be in here!

      process(@data);
        }
        else{

      # This is my error handling code.
      # I probably want to be in here
      # if $filname doesn't exist.

      die "$filename not found";
        }

The solution is to just use a bare return statement whenever you want to return failure. In list context, Perl will then give you an empty list (which is false), and undef in scalar context (which is also false).

  sub read_file {
      my $file = shift;
      -f $file || return;  #DWIM!

      #Continue reading file...
  }

NOTES

You can fool this policy pretty easily by hiding undef in a boolean expression. But don't bother trying. In fact, using return values to indicate failure is pretty poor technique anyway. Consider using die or croak with eval, or the the Error manpage module for a much more robust exception-handling model. Conway has a real nice discussion on error handling in chapter 13 of PBP.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProhibitSubroutinePrototypes.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProhibitSubroutinePrototypes

DESCRIPTION

Contrary to common belief, subroutine prototypes do not enable compile-time checks for proper arguments. Don't use them.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/ProtectPrivateSubs.pm

  • HISTORY
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::ProtectPrivateSubs

DESCRIPTION

By convention Perl authors (like authors in many other languages) indicate private methods and variables by inserting a leading underscore before the identifier. This policy catches attempts to access private variables from outside the package itself.

HISTORY

This policy is inspired by a similar test in the B::Lint manpage

SEE ALSO

the Perl::Critic::Policy::Subroutines::ProtectPrivateSubs manpage

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Subroutines/RequireFinalReturn.pm

  • LIMITATIONS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Subroutines::RequireFinalReturn

DESCRIPTION

Require all subroutines to terminate with a return (or a goto).

Subroutines without explicit return statements at their ends can be confusing. It can be challenging to deduce what the return value will be.

Furthermore, if the programmer did not mean for there to be a significant return value, and omits a return statement, some of the subroutine's inner data can leak to the outside. Consider this case:

   package Password;
   # every time the user guesses the password wrong, it's value
   # is rotated by one character
   my $password;
   sub set_password {
      $password = shift;
   }
   sub check_password {
      my $guess = shift;
      if ($guess eq $password) {
         unlock_secrets();
      } else {
         $password = (substr $password, 1).(substr $password, 0, 1);
      }
   }
   1;

In this case, the last statement in check_password() is the assignment. The result of that assignment is the implicit return value, so a wrong guess returns the right password! Adding a return; at the end of that subroutine solves the problem.

The only exception allowed is an empty subroutine.

LIMITATIONS

We do not look for returns inside ternary operators. That construction is too complicated to analyze right now. Besides, a better form is the return outside of the ternary like this: return foo ? 1 : bar ? 2 : 3

Also, this policy doesn't allow you to terminate a subroutine with die, exit, croak, or confess. We'll try and fix that in the future.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/TestingAndDebugging/ProhibitNoStrict.pm

  • CONSTRUCTOR
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::TestingAndDebugging::ProhibitNoStrict

DESCRIPTION

There are good reasons for disabling certain kinds of strictures, But if you were wise enough to use strict in the first place, then it doesn't make sense to disable it completely. By default, any no strict statement will violate this policy. However, you can configure this Policy to allow certain types of strictures to be disabled (See Configuration). A bare no strict statement will always raise a violation.

CONSTRUCTOR

This policy accepts one key-value pair in the constructor. The key is 'allow' and the value is a string of whitespace delimited stricture types that you want to permit. These can be 'vars', 'subs' and/or 'refs'. Users of the Perl::Critic engine can configure this in their .perlcriticrc file like this:

  [TestingAndDebugging::ProhibitStrictureDisabling]
  allow = vars subs refs

SEE ALSO

the Perl::Critic::Policy::TestingAndDebugging::RequirePackageStricture manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/TestingAndDebugging/ProhibitNoWarnings.pm

  • CONSTRUCTOR
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::TestingAndDebugging::ProhibitNoWarnings

DESCRIPTION

There are good reasons for disabling certain kinds of warnings. But if you were wise enough to use warnings in the first place, then it doesn't make sense to disable them completely. By default, any no warnings statement will violate this policy. However, you can configure this Policy to allow certain types of warnings to be disabled (See Configuration). A bare no warnings statement will always raise a violation.

CONSTRUCTOR

This policy accepts one key-value pair in the constructor. The key is 'allow' and the value is a string of whitespace delimited warning types that you are willing to disable. See the perllexwarn manpage for a list of possible warning types. Users of the Perl::Critic engine can configure this in their .perlcriticrc file like this:

  [TestingAndDebugging::ProhibitWarningsDisabling]
  allow = uninitialized once

SEE ALSO

the Perl::Critic::Policy::TestingAndDebugging::RequirePackageWarnings manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/TestingAndDebugging/RequireUseStrict.pm

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict

DESCRIPTION

Using strictures is probably the single most effective way to improve the quality of your code. This policy requires that the 'use strict' statement must come before any other statements except package, require, and other use statements. Thus, all the code in the entire package will be affected.

NOTES

Up through version 0.15, this Policy only reported a violation for the first offending statement. Starting in version 0.15_03, this Policy was modified to report a violation for every offending statement. This change closes a loophole with the "## no critic" pseudo-pragmas. But for old legacy code that isn't strict, it produces a lot of violations. The best way to alleviate the problem is to organize your code like this.

  ## no critic 'RequireUseStrict';
  ## Legacy code goes here...

  use strict;
  ## New code goes here...

In this manner, you can develop new code that is strict, but allow the strictures to be disabled for all your legacy code. Perl::Critic will only report violations of this policy that occur on lines after the "## use critic" pseudo-pragma.

SEE ALSO

the Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/TestingAndDebugging/RequireUseWarnings.pm

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings

DESCRIPTION

Using warnings is probably the single most effective way to improve the quality of your code. This policy requires that the 'use warnings' statement must come before any other statements except package, require, and other use statements. Thus, all the code in the entire package will be affected.

NOTES

Up through version 0.15, this Policy only reported a violation for the first offending statement. Starting in version 0.15_03, this Policy was modified to report a violation for every offending statement. This change closes a loophole with the "## no critic" pseudo-pragmas. But for old legacy code that doesn't use warnings, it produces a lot of violations. The best way to alleviate the problem is to organize your code like this.

  ## no critic 'RequireUseWarnings';

  ## Legacy code goes here...

  ## use critic;
  use warnings;

  ## New code goes here...

In this manner, you can develop new code with warnings enabled, but still allow the warnings to be disabled for all your legacy code. Perl::Critic will only report violations of this policy that occur on lines after the "## use critic" pseudo-pragma.

SEE ALSO

the Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitConstantPragma.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma

DESCRIPTION

Named constants are a good thing. But don't use the constant pragma because barewords don't interpolate. Instead use the Readonly module.

  use constant FOOBAR => 42;  #not ok

  use Readonly;
  Readonly  my $FOOBAR => 42;  #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitEmptyQuotes.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitEmptyQuotes

DESCRIPTION

Don't use quotes for an empty string or any string that is pure whitespace. Instead, use q{} to improve legibility. Better still, created named values like this. Use the x operator to repeat characters.

  $message = '';      #not ok
  $message = "";      #not ok
  $message = "     "; #not ok

  $message = q{};     #better
  $message = q{     } #better

  $EMPTY = q{};
  $message = $EMPTY;      #best

  $SPACE = q{ };
  $message = $SPACE x 5;  #best

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitNoisyStrings manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitEscapedCharacters.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitEscapedCharacters

DESCRIPTION

Escaped numeric values are hard to read and debug. Instead, use named values. The syntax is less compact, but dramatically more readable.

  $str = "\X7F\x06\x22Z";                         # not ok

  use charnames ':full';
  $str = "\N{DELETE}\N{ACKNOWLEDGE}\N{CANCEL}Z";  # ok

SEE ALSO

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitInterpolationOfLiterals.pm

  • CONSTRUCTOR
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitInterpolationOfLiterals

DESCRIPTION

Don't use double-quotes or qq// if your string doesn't require interpolation. This saves the interpreter a bit of work and it lets the reader know that you really did intend the string to be literal.

  print "foobar";     #not ok
  print 'foobar';     #ok
  print qq/foobar/;   #not ok
  print q/foobar/;    #ok

  print "$foobar";    #ok
  print "foobar\n";   #ok
  print qq/$foobar/;  #ok
  print qq/foobar\n/; #ok

  print qq{$foobar};  #preferred
  print qq{foobar\n}; #preferred

CONSTRUCTOR

This Policy accepts an additional key-value pair in the constructor, The key is 'allow' and the value is a string of quote styles that are exempt from this policy. Valid styles are qq{}, qq(), qq[], and qq//. Multiple styles should be separated by whitespace. This is useful because some folks have configured their editor to apply special syntax highlighting within certain styles of quotes. For example, you can tweak vim to use SQL highlighting for everything that appears within qq{} or qq[] quotes. But if those strings are literal, Perl::Critic will complain. To prevent this, put the following in your .perlcriticrc file:

  [ValuesAndExpressions::ProhibitInterpolationOfLiterals]
  allow = qq{} qq[]

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::RequireInterpolationOfMetachars manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitLeadingZeros.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitLeadingZeros

DESCRIPTION

Perl interprets numbers with leading zeros as octal. If that's what you really want, its better to use oct and make it obvious.

  $var = 041;     #not ok, actually 33
  $var = oct(41); #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitMixedBooleanOperators.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitMixedBooleanOperators

DESCRIPTION

Conway advises against combining the low-precedence booleans ( and or not ) with the high-precedence boolean operators ( && || ! ) in the same expression. Unless you fully understand the differences between the high and low-precedence operators, it is easy to misinterpret expressions that use both. And even if you do understand them, it is not always clear if the author actually intended it.

  next if not $foo || $bar;  #not ok
  next if !$foo || $bar;     #ok
  next if !( $foo || $bar ); #ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitNoisyQuotes.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitNoisyQuotes

DESCRIPTION

Don't use quotes for one or two-character strings of non-alphanumeric characters (i.e. noise). These tend to be hard to read. For legibility, use q{} or a named value. However, braces, parens, and brackets tend do to look better in quotes, so those are allowed.

  $str = join ',', @list;     #not ok
  $str = join ",", @list;     #not ok
  $str = join q{,}, @list;    #better

  $COMMA = q{,};
  $str = join $COMMA, @list;  #best

  $lbrace = '(';          #ok
  $rbrace = ')';          #ok
  print '(', @list, ')';  #ok

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitEmptyQuotes manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitVersionStrings.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings

DESCRIPTION

Whenever you use or require a module, you can specify a minimum version requirement. To ensure compatibility with older Perls, this version number should be expressed as a floating-point number. Do not use v-strings or three-part numbers. The Perl convention for expressing version numbers as floats is: version + (patch level / 1000).

  use Foo v1.2    qw(foo bar);  # not ok
  use Foo 1.2.03  qw(foo bar);  # not ok
  use Foo 1.00203 qw(foo bar);  # ok

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/RequireInterpolationOfMetachars.pm

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::RequireInterpolationOfMetachars

DESCRIPTION

This policy warns you if you use single-quotes or q// with a string that has unescaped metacharacters that may need interpolation. Its hard to know for sure if a string really should be interpolated without looking into the symbol table. This policy just makes an educated guess by looking for metacharacters and sigils which usually indicate that the string should be interpolated.

NOTES

Perl's own warnings pragma also warns you about this.

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitInterpolationOfLiterals manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/RequireNumberSeparators.pm

  • CONSTRUCTOR
  • NOTES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::RequireNumberSeparators

DESCRIPTION

Long numbers can be difficult to read. To improve legibility, Perl allows numbers to be split into groups of digits separated by underscores. This policy requires number sequences of more than three digits to be separated.

 $long_int = 123456789;   #not ok
 $long_int = 123_456_789; #ok

 $long_float = 12345678.001;   #not ok
 $long_float = 12_345_678.001; #ok

CONSTRUCTOR

This Policy accepts an additional key-value pair in the new method. The key is 'min_value' and the value is the minimum absolute value of numbers that must be separated. The default is 10,000. Thus, all numbers >= 10,000 and <= -10,000 must be separated. Users of the Perl::Critic engine can configure this in their .perlcriticrc like this:

  [ValuesAndExpressions::RequireNumberSeparators]
  min_value = 100000    #That's one-hundred-thousand!

NOTES

As it is currently written, this policy only works properly with decimal (base 10) numbers. And it is obviously biased toward Western notation. I'll try and address those issues in the future.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/RequireQuotedHeredocTerminator.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::RequireQuotedHeredocTerminator

DESCRIPTION

Putting single or double-quotes around your HEREDOC terminator make it obvious to the reader whether the content is going to be interpolated or not.

  print <<END_MESSAGE;    #not ok
  Hello World
  END_MESSAGE

  print <<'END_MESSAGE';  #ok
  Hello World
  END_MESSAGE

  print <<"END_MESSAGE";  #ok
  $greeting
  END_MESSAGE

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/ValuesAndExpressions/RequireUpperCaseHeredocTerminator.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator

DESCRIPTION

For legibility, HEREDOC terminators should be all UPPER CASE letters (and numbers), without any whitespace. Conway also recommends using a standard prefix like "END_" but this policy doesn't enforce that.

  print <<'the End';  #not ok
  Hello World
  the End

  print <<'THE_END';  #ok
  Hello World
  THE_END

SEE ALSO

the Perl::Critic::Policy::ValuesAndExpressions::RequireQuotedHeredocTerminator manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProhibitConditionalDeclarations.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProhibitConditionalDeclarations

DESCRIPTION

Declaring a variable with a postfix conditional is really confusing. If the conditional is false, its not clear if the variable will be false, undefined, undeclared, or what. It's much more straightforward to make variable declarations separately.

  my $foo = $baz if $bar;          #not ok
  my $foo = $baz unless $bar;      #not ok
  our $foo = $baz for @list;       #not ok
  local $foo = $baz foreach @list; #not ok

AUTHOR

Jeffrey R. Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProhibitLocalVars.pm

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProhibitLocalVars

DESCRIPTION

Since Perl 5, there are very few reasons to declare local variables. The most common exceptions are Perl's magical global variables. If you do need to modify one of those global variables, you should localize it first. You should also use the the English manpage module to give those variables more meaningful names.

  local $foo;   #not ok
  my $foo;      #ok

  use English qw(-no_match_vars);
  local $INPUT_RECORD_SEPARATOR    #ok
  local $RS                        #ok
  local $/;                        #not ok

NOTES

If an external module uses package variables as its interface, then using local is actually a pretty sensible thing to do. So Perl::Critic will not complain if you local-ize variables with a fully qualified name such as $Some::Package::foo. However, if you're in a position to dictate the module's interface, I strongly suggest using accessor methods instead.

SEE ALSO

the Perl::Critic::Policy::Variables::ProhibitPunctuationVars manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProhibitMatchVars.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProhibitMatchVars

DESCRIPTION

Using the "match variables" $`, $&, and/or $' can significantly degrade the performance of a program. This policy forbids using them or their English equivalents. It also forbids plain use English; so you should instead employ use English '-no_match_vars'; which avoids the match variables. See perldoc English or PBP page 82 for more information.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProhibitPackageVars.pm

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProhibitPackageVars

DESCRIPTION

Conway suggests avoiding package variables completely, because they expose your internals to other packages. Never use a package variable when a lexical variable will suffice. If your package needs to keep some dynamic state, consider using an object or closures to keep the state private.

This policy assumes that you're using strict vars so that naked variable declarations are not package variables by default. Thus, it complains you declare a variable with our or use vars, or if you make reference to variable with a fully-qualified package name.

  $Some::Package::foo = 1;    #not ok
  our $foo            = 1;    #not ok
  use vars '$foo';            #not ok
  $foo = 1;                   #not allowed by 'strict'
  local $foo = 1;             #bad taste, but technically ok.
  use vars '$FOO';            #ok, because it's ALL CAPS
  my $foo = 1;                #ok

In practice though, its not really practical to prohibit all package variables. Common variables like $VERSION and @EXPORT need to be global, as do any variables that you want to Export. To work around this, the Policy overlooks any variables that are in ALL_CAPS. This forces you to put all your exported variables in ALL_CAPS too, which seems to be the usual practice anyway.

SEE ALSO

the Perl::Critic::Policy::Variables::ProhibitPunctuationVars manpage

the Perl::Critic::Policy::Variables::ProhibitLocalVars manpage

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProhibitPunctuationVars.pm

  • EXCEPTIONS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProhibitPunctuationVars

DESCRIPTION

Perl's vocabulary of punctuation variables such as $!, $., and $^ are perhaps the leading cause of its reputation as inscrutable line noise. The simple alternative is to use the the English manpage module to give them clear names.

  $| = undef;                      #not ok

  use English qw(-no_match_vars);
  local $OUTPUT_AUTOFLUSH = undef;        #ok

EXCEPTIONS

The scratch variables $_ and @_ are very common and have no equivalent name in the English manpage, so they are exempt from this policy. The same goes for the less-frequently-used default filehandle _ used by stat(). All the regexp capture variables ($1, $2, ...) are exempt too.

You can add more exceptions to your configuration. In your perlcriticrc file, add a block like this:

  [Variables::ProhibitPunctuationVars]
  allow = $@ $!

The allow property should be a whitespace-delimited list of punctuation variables.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/ProtectPrivateVars.pm

  • HISTORY
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::ProtectPrivateVars

DESCRIPTION

By convention Perl authors (like authors in many other languages) indicate private methods and variables by inserting a leading underscore before the identifier. This policy catches attempts to access private variables from outside the package itself.

HISTORY

This policy is inspired by a similar test in the B::Lint manpage

SEE ALSO

the Perl::Critic::Policy::Subroutines::ProtectPrivateSubs manpage

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/RequireInitializationForLocalVars.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::RequireInitializationForLocalVars

DESCRIPTION

Most people don't realize that a localized copy of a variable does not retain its original value. Unless you initialize the variable when you local-ize it, it defaults to undef. If you want the variable to retain its original value, just initialize it to itself. If you really do want the localized copy to be undef, then make it explicit.

  package Foo;
  $Bar = '42';

  package Baz;

  sub frobulate {

      local $Foo::Bar;              #not ok, local $Foo::Bar is 'undef'
      local $Foo::Bar = undef;      #ok, local $Foo::Bar is obviously 'undef'
      local $Foo::Bar = $Foo::Bar;  #ok, local $Foo::Bar still equals '42'

  }

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/RequireLexicalLoopIterators.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::RequireLexicalLoopIterators

DESCRIPTION

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


site/lib/Perl/Critic/Policy/Variables/RequireNegativeIndices.pm

  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Policy::Variables::RequireNegativeIndices

DESCRIPTION

Conway points out that

  $arr[$#arr];
  $arr[$#arr-1];
  $arr[@arr-1];
  $arr[@arr-2];

are equivalent to

  $arr[-1];
  $arr[-2];
  $arr[-1];
  $arr[-2];

and the latter are more readable, performant and maintainable. The latter is because the programmer no longer needs to keep two variable names matched.

This policy notices all of the simple forms of the above problem, but does not recognize any of these more complex examples:

   $some->[$data_structure]->[$#{$some->[$data_structure]} -1];
   my $ref = \@arr;
   $ref->[$#arr];

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (C) 2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Perl::Critic::PolicySummary - Description of the bundled Policy modules

  • POLICIES
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr manpage
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect manpage
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval manpage
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringySplit manpage
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan manpage
    • the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa manpage
    • the Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep manpage
    • the Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap manpage
    • the Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction manpage
    • the Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock manpage
    • the Perl::Critic::Policy::ClassHierarchies::ProhibitExplicitISA manpage
    • the Perl::Critic::Policy::ClassHierarchies::ProhibitOneArgBless manpage
    • the Perl::Critic::Policy::CodeLayout::ProhibitHardTabs manpage
    • the Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins manpage
    • the Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists manpage
    • the Perl::Critic::Policy::CodeLayout::RequireTidyCode manpage
    • the Perl::Critic::Policy::CodeLayout::RequireTrailingCommas manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitCStyleForLoops manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitDeepNests manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitUnreachableCode manpage
    • the Perl::Critic::Policy::ControlStructures::ProhibitUntilBlocks manpage
    • the Perl::Critic::Policy::Documentation::RequirePodAtEnd manpage
    • the Perl::Critic::Policy::Documentation::RequirePodSections manpage
    • the Perl::Critic::Policy::ErrorHandling::RequireCarping manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitBacktickOperators manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitBarewordFileHandles manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitInteractiveTest manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitOneArgSelect manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop manpage
    • the Perl::Critic::Policy::InputOutput::ProhibitTwoArgOpen manpage
    • the Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint manpage
    • the Perl::Critic::Policy::Miscellanea::ProhibitFormats manpage
    • the Perl::Critic::Policy::Miscellanea::ProhibitTies manpage
    • the Perl::Critic::Policy::Miscellanea::RequireRcsKeywords manpage
    • the Perl::Critic::Policy::Modules::ProhibitAutomaticExportation manpage
    • the Perl::Critic::Policy::Modules::ProhibitEvilModules manpage
    • the Perl::Critic::Policy::Modules::ProhibitMultiplePackages manpage
    • the Perl::Critic::Policy::Modules::RequireBarewordIncludes manpage
    • the Perl::Critic::Policy::Modules::RequireEndWithOne manpage
    • the Perl::Critic::Policy::Modules::RequireExplicitPackage manpage
    • the Perl::Critic::Policy::Modules::RequireVersionVar manpage
    • the Perl::Critic::Policy::NamingConventions::ProhibitAmbiguousNames manpage
    • the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs manpage
    • the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseVars manpage
    • the Perl::Critic::Policy::References::ProhibitDoubleSigils manpage
    • the Perl::Critic::Policy::RegularExpressions::ProhibitCaptureWithoutTest manpage
    • the Perl::Critic::Policy::RegularExpressions::RequireExtendedFormatting manpage
    • the Perl::Critic::Policy::RegularExpressions::RequireLineBoundaryMatching manpage
    • the Perl::Critic::Policy::Subroutines::ProhibitAmpersandSigils manpage
    • the Perl::Critic::Policy::Subroutines::ProhibitBuiltinHomonyms manpage
    • the Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity manpage
    • the Perl::Critic::Policy::Subroutines::ProhibitExplicitReturnUndef manpage
    • the Perl::Critic::Policy::Subroutines::ProhibitSubroutinePrototypes manpage
    • the Perl::Critic::Policy::Subroutines::ProtectPrivateSubs manpage
    • the Perl::Critic::Policy::Subroutines::RequireFinalReturn manpage
    • the Perl::Critic::Policy::TestingAndDebugging::ProhibitNoStrict manpage
    • the Perl::Critic::Policy::TestingAndDebugging::ProhibitNoWarnings manpage
    • the Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict manpage
    • the Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitEmptyQuotes manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitEscapedCharacters manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitInterpolationOfLiterals manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitLeadingZeros manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitMixedBooleanOperators manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitNoisyQuotes manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::RequireInterpolationOfMetachars manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::RequireNumberSeparators manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::RequireQuotedHeredocTerminator manpage
    • the Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator manpage
    • the Perl::Critic::Policy::Variables::ProhibitConditionalDeclarations manpage
    • the Perl::Critic::Policy::Variables::ProhibitLocalVars manpage
    • the Perl::Critic::Policy::Variables::ProhibitMatchVars manpage
    • the Perl::Critic::Policy::Variables::ProhibitPackageVars manpage
    • the Perl::Critic::Policy::Variables::ProhibitPunctuationVars manpage
    • the Perl::Critic::Policy::Variables::ProtectPrivateVars manpage
    • the Perl::Critic::Policy::Variables::RequireInitializationForLocalVars manpage
    • the Perl::Critic::Policy::Variables::RequireLexicalLoopIterators manpage
    • the Perl::Critic::Policy::Variables::RequireNegativeIndices manpage
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::PolicySummary - Description of the bundled Policy modules

DESCRIPTION

The following Policy modules are distributed with Perl::Critic. The Policy modules have been categorized according to the table of contents in Damian Conway's book Perl Best Practices. Since most coding standards take the form "do this..." or "don't do that...", I have adopted the convention of naming each module RequireSomething or ProhibitSomething. Each Policy is listed here with it's default severity. If you don't agree with the default severity, you can change it in your .perlcriticrc file. See the documentation of each module for it's specific details.

POLICIES

the Perl::Critic::Policy::BuiltinFunctions::ProhibitLvalueSubstr manpage

Use 4-argument substr instead of writing substr($foo, 2, 6) = $bar [Severity 3]

the Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect manpage

Use the Time::HiRes manpage instead of something like select(undef, undef, undef, .05) [Severity 5]

the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval manpage

Write eval { my $foo; bar($foo) } instead of eval "my $foo; bar($foo);" [Severity 5]

the Perl::Critic::Policy::BuiltinFunctions::ProhibitStringySplit manpage

Write split /-/, $string instead of split '-', $string [Severity 3]

the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalCan manpage

Write eval { $foo->can($name) } instead of UNIVERSAL::can($foo, $name) [Severity 3]

the Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa manpage

Write eval { $foo->isa($pkg) } instead of UNIVERSAL::isa($foo, $pkg) [Severity 3]

the Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep manpage

Write grep { $_ =~ /$pattern/ } @list instead of grep /$pattern/, @list [Severity 4]

the Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap manpage

Write map { $_ =~ /$pattern/ } @list instead of map /$pattern/, @list [Severity 4]

the Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction manpage

Use glob q{*} instead of <*> [Severity 5]

the Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock manpage

Sort blocks should have a single statement [Severity 3]

the Perl::Critic::Policy::ClassHierarchies::ProhibitExplicitISA manpage

Employ use base instead of @ISA [Severity 3]

the Perl::Critic::Policy::ClassHierarchies::ProhibitOneArgBless manpage

Write bless {}, $class; instead of just bless {}; [Severity 5]

the Perl::Critic::Policy::CodeLayout::ProhibitHardTabs manpage

Use spaces instead of tabs. [Severity 3]

the Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins manpage

Write open $handle, $path instead of open($handle, $path) [Severity 1]

the Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists manpage

Write qw(foo bar baz) instead of ('foo', 'bar', 'baz') [Severity 2]

the Perl::Critic::Policy::CodeLayout::RequireTidyCode manpage

Must run code through perltidy. [Severity 1]

the Perl::Critic::Policy::CodeLayout::RequireTrailingCommas manpage

Put a comma at the end of every multi-line list declaration, including the last one. [Severity 1]

the Perl::Critic::Policy::ControlStructures::ProhibitCStyleForLoops manpage

Write for(0..20) instead of for($i=0; $i<=20; $i++) [Severity 2]

the Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse manpage

Don't write long "if-elsif-elsif-elsif-elsif...else" chains. [Severity 3]

the Perl::Critic::Policy::ControlStructures::ProhibitDeepNests manpage

[Severity 2]

Don't write deeply nested loops and conditionals.

the Perl::Critic::Policy::ControlStructures::ProhibitPostfixControls manpage

Write if($condition){ do_something() } instead of do_something() if $condition [Severity 2]

the Perl::Critic::Policy::ControlStructures::ProhibitUnlessBlocks manpage

Write if(! $condition) instead of unless($condition) [Severity 2]

the Perl::Critic::Policy::ControlStructures::ProhibitUnreachableCode manpage

Don't write code after an unconditional die, exit, or next. [Severity 4]

the Perl::Critic::Policy::ControlStructures::ProhibitUntilBlocks manpage

Write while(! $condition) instead of until($condition) [Severity 2]

the Perl::Critic::Policy::Documentation::RequirePodAtEnd manpage

All POD should be after __END__ [Severity 1]

the Perl::Critic::Policy::Documentation::RequirePodSections manpage

Organize your POD into the customary sections. [Severity 2]

the Perl::Critic::Policy::ErrorHandling::RequireCarping manpage

Use functions from the Carp manpage instead of warn or die. [Severity 3]

the Perl::Critic::Policy::InputOutput::ProhibitBacktickOperators manpage

Discourage stuff like @files = `ls $directory` [Severity 3]

the Perl::Critic::Policy::InputOutput::ProhibitBarewordFileHandles manpage

Write open my $fh, q{<}, $filename; instead of open FH, q{<}, $filename; [Severity 5]

the Perl::Critic::Policy::InputOutput::ProhibitInteractiveTest manpage

Use prompt() instead of -t [Severity 5]

the Perl::Critic::Policy::InputOutput::ProhibitOneArgSelect manpage

Never write select($fh) [Severity 4]

the Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop manpage

Write while( $line = <> ){...} instead of for(<>){...} [Severity 4]

the Perl::Critic::Policy::InputOutput::ProhibitTwoArgOpen manpage

Write open $fh, q{<}, $filename; instead of open $fh, "<$filename"; [Severity 5]

the Perl::Critic::Policy::InputOutput::RequireBracedFileHandleWithPrint manpage

Write print {$FH} $foo, $bar; instead of print $FH $foo, $bar; [Severity 1]

the Perl::Critic::Policy::Miscellanea::ProhibitFormats manpage

Do not use format. [Severity 3]

the Perl::Critic::Policy::Miscellanea::ProhibitTies manpage

Do not use tie. [Severity 2]

the Perl::Critic::Policy::Miscellanea::RequireRcsKeywords manpage

Put source-control keywords in every file. [Severity 2]

the Perl::Critic::Policy::Modules::ProhibitAutomaticExportation manpage

Export symbols via @EXPORT_OK or %EXPORT_TAGS instead of @EXPORT. [Severity 3]

the Perl::Critic::Policy::Modules::ProhibitEvilModules manpage

Ban modules that aren't blessed by your shop. [Severity 5]

the Perl::Critic::Policy::Modules::ProhibitMultiplePackages manpage

Put packages (especially subclasses) in separate files. [Severity 4]

the Perl::Critic::Policy::Modules::RequireBarewordIncludes manpage

Write require Module instead of require 'Module.pm' [Severity 5]

the Perl::Critic::Policy::Modules::RequireEndWithOne manpage

End each module with an explicitly 1; instead of some funky expression. [Severity 4]

the Perl::Critic::Policy::Modules::RequireExplicitPackage manpage

Always make the package explicit. [Severity 4]

the Perl::Critic::Policy::Modules::RequireVersionVar manpage

Give every module a $VERSION number. [Severity 2]

the Perl::Critic::Policy::NamingConventions::ProhibitAmbiguousNames manpage

Don't use vague variable or subroutine names like 'last' or 'record'. [Severity 3]

the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseSubs manpage

Write sub my_function{} instead of sub MyFunction{} [Severity 1]

the Perl::Critic::Policy::NamingConventions::ProhibitMixedCaseVars manpage

Write $my_variable = 42 instead of $MyVariable = 42 [Severity 1]

the Perl::Critic::Policy::References::ProhibitDoubleSigils manpage

Write @{ $array_ref } instead of @$array_ref [Severity 2]

the Perl::Critic::Policy::RegularExpressions::ProhibitCaptureWithoutTest manpage

Capture variable used outside conditional [Severity 3]

the Perl::Critic::Policy::RegularExpressions::RequireExtendedFormatting manpage

Always use the /x modifier with regular expressions. [Severity 2]

the Perl::Critic::Policy::RegularExpressions::RequireLineBoundaryMatching manpage

Always use the /m modifier with regular expressions. [Severity 3]

the Perl::Critic::Policy::Subroutines::ProhibitAmpersandSigils manpage

Don't call functions with a leading ampersand sigil. [Severity 2]

the Perl::Critic::Policy::Subroutines::ProhibitBuiltinHomonyms manpage

Don't declare your own open function. [Severity 4]

the Perl::Critic::Policy::Subroutines::ProhibitExcessComplexity manpage

Minimize complexity by factoring code into smaller subroutines. [Severity 3]

the Perl::Critic::Policy::Subroutines::ProhibitExplicitReturnUndef manpage

Return failure with bare return instead of return undef [Severity 5]

the Perl::Critic::Policy::Subroutines::ProhibitSubroutinePrototypes manpage

Don't write sub my_function (@@) {} [Severity 5]

the Perl::Critic::Policy::Subroutines::ProtectPrivateSubs manpage

Prevent access to private subs in other packages [Severity 3]

the Perl::Critic::Policy::Subroutines::RequireFinalReturn manpage

End every path through a subroutine with an explicit return statement. [Severity 4]

the Perl::Critic::Policy::TestingAndDebugging::ProhibitNoStrict manpage

Prohibit various flavors of no strict [Severity 5]

the Perl::Critic::Policy::TestingAndDebugging::ProhibitNoWarnings manpage

Prohibit various flavors of no warnings [Severity 4]

the Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict manpage

Always use strict [Severity 5]

the Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings manpage

Always use warnings [Severity 4]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma manpage

Don't use constant $FOO => 15 [Severity 4]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitEmptyQuotes manpage

Write q{} instead of '' [Severity 2]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitEscapedCharacters manpage

Write "\N{DELETE}" instead of "\x7F", etc. [Severity 2]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitInterpolationOfLiterals manpage

Always use single quotes for literal strings. [Severity 1]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitLeadingZeros manpage

Write oct(755) instead of 0755 [Severity 5]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitMixedBooleanOperators manpage

Write !$foo && $bar || $baz instead of not $foo && $bar or $baz [Severity 4]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitNoisyQuotes manpage

Use q{} or qq{} instead of quotes for awkward-looking strings. [Severity 2]

the Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings manpage

Don't use strings like v1.4 or 1.4.5 when including other modules. [Severity 3]

the Perl::Critic::Policy::ValuesAndExpressions::RequireInterpolationOfMetachars manpage

Warns that you might have used single quotes when you really wanted double-quotes. [Severity 1]

the Perl::Critic::Policy::ValuesAndExpressions::RequireNumberSeparators manpage

Write 141_234_397.0145 instead of 141234397.0145 [Severity 2]

the Perl::Critic::Policy::ValuesAndExpressions::RequireQuotedHeredocTerminator manpage

Write print <<'THE_END' or print <<"THE_END" [Severity 3]

the Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator manpage

Write <<'THE_END'; instead of <<'theEnd'; [Severity 1]

the Perl::Critic::Policy::Variables::ProhibitConditionalDeclarations manpage

Do not write my $foo = $bar if $baz; [Severity 5]

the Perl::Critic::Policy::Variables::ProhibitLocalVars manpage

Use my instead of local, except when you have to. [Severity 2]

the Perl::Critic::Policy::Variables::ProhibitMatchVars manpage

Avoid $`, $&, $' and their English equivalents. [Severity 4]

the Perl::Critic::Policy::Variables::ProhibitPackageVars manpage

Eliminate globals declared with our or use vars [Severity 3]

the Perl::Critic::Policy::Variables::ProhibitPunctuationVars manpage

Write $EVAL_ERROR instead of $@ [Severity 2]

the Perl::Critic::Policy::Variables::ProtectPrivateVars manpage

Prevent access to private vars in other packages [Severity 3]

the Perl::Critic::Policy::Variables::RequireInitializationForLocalVars manpage

Write local $foo = $bar; instead of just local $foo; [Severity 3]

the Perl::Critic::Policy::Variables::RequireLexicalLoopIterators manpage

Write for my $element (@list) {...} instead of for $element (@list) {...}

the Perl::Critic::Policy::Variables::RequireNegativeIndices manpage

Negative array index should be used [Severity 4]

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::TestUtils - Utility functions for testing new Policies

  • EXPORTS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::TestUtils - Utility functions for testing new Policies

SYNOPSIS

  use Perl::Critic::TestUtils qw(critique pcritique);

  my $code = '<<END_CODE';
  $foo = frobulator();
  $baz = $foo ** 2;
  END_CODE

  # Critique code against all loaded policies...
  my $perl_critic_config = { -severity => 2 };
  my $violation_count = critique( $code, $perl_critic_config);

  # Critique code against one policy...
  my $custom_policy = 'Miscellanea::ProhibitFrobulation'
  my $violation_count = pcritique( $code, $custom_policy );

DESCRIPTION

This module is not used directly by the Perl::Critic manpage but it provides a few handy subroutines for testing new Perl::Critic::Policy modules. Look at the test scripts that ship with Perl::Critic for more examples of how to use these subroutines.

EXPORTS

critique( $policy_name, $code_string_ref )
pcritique( $policy_name, $string_ref, $config_ref )
block_perlcriticrc()

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Chris Dolan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::Utils - Utility subs and vars for Perl::Critic

  • EXPORTED SUBS
  • EXPORTED VARIABLES
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Utils - Utility subs and vars for Perl::Critic

DESCRIPTION

This module exports several static subs and variables that are useful for developing the Perl::Critic::Policy manpage subclasses. Unless you are writing Policy modules, you probably don't care about this package.

EXPORTED SUBS

find_keywords( $doc, $keyword )

DEPRECATED: Since version 0.11, every Policy is evaluated at each element of the document. So you shouldn't need to go looking for a particular keyword.

Given a the PPI::Document manpage as $doc, returns a reference to an array containing all the the PPI::Token::Word manpage elements that match $keyword. This can be used to find any built-in function, method call, bareword, or reserved keyword. It will not match variables, subroutine names, literal strings, numbers, or symbols. If the document doesn't contain any matches, returns undef.

is_perl_global( $element )

Given a the PPI::Token::Symbol manpage or a string, returns true if that token represents one of the global variables provided by the the English manpage module, or one of the builtin global variables like %SIG, %ENV, or @ARGV. The sigil on the symbol is ignored, so things like $ARGV or $ENV will still return true.

is_perl_builtin( $element )

Given a the PPI::Token::Word manpage or a string, returns true if that token represents a call to any of the builtin functions defined in Perl 5.8.8

precedence_of( $element )

Given a the PPI::Token::Operator manpage or a string, returns the precedence of the operator, where 1 is the highest precedence. Returns undef if the precedence can't be determined (which is usually because it is not an operator).

is_hash_key( $element )

Given a the PPI::Element manpage, returns true if the element is a hash key. PPI doesn't distinguish between regular barewords (like keywords or subroutine calls) and barewords in hash subscripts (which are considered literal). So this subroutine is useful if your Policy is searching for the PPI::Token::Word manpage elements and you want to filter out the hash subscript variety. In both of the following examples, 'foo' is considered a hash key:

  $hash1{foo} = 1;
  %hash2 = (foo => 1);
is_method_call( $element )

Given a the PPI::Element manpage that is presumed to be a function call (which is usually a the PPI::Token::Word manpage), returns true if the function is a method being called on some reference. Basically, it just looks to see if the preceding operator is "->". This is useful for distinguishing static function calls from object method calls.

is_subroutine_name( $element )

Given a the PPI::Token::Word manpage, returns true if the element is the name of a subroutine declaration. This is useful for distinguishing barewords and from function calls from subroutine declarations.

is_function_call( $element )

Given a the PPI::Token::Word manpage returns true if the element appears to be call to a static function. Specifically, this function returns true if is_hash_key, is_method_call, and is_subroutine_name all return false for the given element.

parse_arg_list( $element )

Given a the PPI::Element manpage that is presumed to be a function call (which is usually a the PPI::Token::Word manpage), splits the argument expressions into arrays of tokens. Returns a list containing references to each of those arrays. This is useful because parens are optional when calling a function, and PPI parses them very differently. So this method is a poor-man's parse tree of PPI nodes. It's not bullet-proof because it doesn't respect precedence. In general, I don't like the way this function works, so don't count on it to be stable (or even present).

is_script( $document )

Given a the PPI::Document manpage, test if it starts with /#!.*perl/. If so, it is judged to be a script instead of a module.

all_perl_files( @directories )

Given a list of directories, recursively searches through all the directories (depth first) and returns a list of paths for all the files that are Perl code files. Any administrative files for CVS or Subversion are skipped, as are things that look like temporary or backup files.

A Perl code file is:

  • Any file that ends in .PL, .pl, .pm, or .t
  • Any file that has a first line with a shebang containing 'perl'
verbosity_to_format( $verbosity_level )

Given a verbosity level between 1 and 10, returns the corresponding predefined format string. These formats are suitable for passing to the set_format method in the Perl::Critic::Violation manpage. See the perlcritic documentation for a listing of the predefined formats.

hashify( @list )

Given @list, return a hash where @list is in the keys and each value is 1.

EXPORTED VARIABLES

@BUILTINS

DEPRECATED: Use is_perl_builtin() instead.

This is a list of all the built-in functions provided by Perl 5.8. I imagine this is useful for distinguishing native and non-native function calls.

@GLOBALS

DEPRECATED: Use is_perl_global() instead.

This is a list of all the magic global variables provided by the the English manpage module. Also includes commonly-used global like %SIG, %ENV, and @ARGV. The list contains only the variable name, without the sigil.

$COMMA
$FATCOMMA
$COLON
$SCOLON
$QUOTE
$DQUOTE
$PERIOD
$PIPE
$EMPTY
$SPACE

These character constants give clear names to commonly-used strings that can be hard to read when surrounded by quotes.

$SEVERITY_HIGHEST
$SEVERITY_HIGH
$SEVERITY_MEDIUM
$SEVERITY_LOW
$SEVERITY_LOWEST

These numeric constants define the relative severity of violating each the Perl::Critic::Policy manpage. The get_severity and default_severity methods of every Policy subclass must return one of these values.

$TRUE
$FALSE

These are simple booleans. 1 and 0 respectively. Be mindful of using these with string equality. $FALSE ne $EMPTY.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


Perl::Critic::Violation - Represents policy violations

  • CONSTRUCTOR
  • METHODS
  • FIELDS
  • OVERLOADS
  • AUTHOR
  • COPYRIGHT

NAME

Perl::Critic::Violation - Represents policy violations

SYNOPSIS

  use PPI;
  use Perl::Critic::Violation;

  my $elem = $doc->child(0);      #$doc is a PPI::Document object
  my $desc = 'Offending code';    #Describe the violation
  my $expl = [1,45,67];           #Page numbers from PBP
  my $sev  = 5;                   #Severity level of this violation

  my $vio  = Perl::Critic::Violation->new($desc, $expl, $node, $sev);

DESCRIPTION

Perl::Critic::Violation is the generic representation of an individual Policy violation. Its primary purpose is to provide an abstraction layer so that clients of the Perl::Critic manpage don't have to know anything about the PPI manpage. The violations method of all the Perl::Critic::Policy manpage subclasses must return a list of these Perl::Critic::Violation objects.

CONSTRUCTOR

new( $description, $explanation, $element, $severity )

Returns a reference to a new Perl::Critic::Violation object. The arguments are a description of the violation (as string), an explanation for the policy (as string) or a series of page numbers in PBP (as an ARRAY ref), a reference to the the PPI manpage element that caused the violation, and the severity of the violation (as an integer).

METHODS

description()

Returns a brief description of the policy that has been violated as a string.

explanation()

Returns an explanation of the policy as a string or as reference to an array of page numbers in PBP.

location()

Returns a two-element list containing the line and column number where this Violation occurred.

severity()

Returns the severity of this Violation as an integer ranging from 1 to 5, where 5 is the "most" severe.

sort_by_severity( @violation_objects )

If you need to sort Violations by severity, use this handy routine:

   @sorted = Perl::Critic::Violation::sort_by_severity(@violations);
sort_by_location( @violation_objects )

If you need to sort Violations by location, use this handy routine:

   @sorted = Perl::Critic::Violation::sort_by_location(@violations);
diagnostics()

Returns a formatted string containing a full discussion of the motivation for and details of the Policy module that created this Violation. This information is automatically extracted from the DESCRIPTION section of the Policy module's POD.

policy()

Returns the name of the the Perl::Critic::Policy manpage that created this Violation.

source()

Returns the string of source code that caused this exception. If the code spans multiple lines (e.g. multi-line statements, subroutines or other blocks), then only the first line will be returned.

set_format( $FORMAT )

Class method. Sets the format for all Violation objects when they are evaluated in string context. The default is '%d at line %l, column %c. %e'. See OVERLOADS for formatting options.

get_format()

Class method. Returns the current format for all Violation objects when they are evaluated in string context.

to_string()

Returns a string representation of this violation. The content of the string depends on the current value of the $FORMAT package variable. See OVERLOADS for the details.

FIELDS

$Perl::Critic::Violation::FORMAT

This variable is deprecated. Use the set_format and get_format class methods instead.

Sets the format for all Violation objects when they are evaluated in string context. The default is '%d at line %l, column %c. %e'. See OVERLOADS for formatting options. If you want to change $FORMAT, you should probably localize it first.

OVERLOADS

Perl::Critic::Violation overloads the "" operator to produce neat little messages when evaluated in string context. The format depends on the current value of the $FORMAT package variable.

Formats are a combination of literal and escape characters similar to the way sprintf works. If you want to know the specific formatting capabilities, look at the String::Format manpage. Valid escape characters are:

  Escape    Meaning
  -------   -----------------------------------------------------------------
  %m        Brief description of the violation
  %f        Name of the file where the violation occurred.
  %l        Line number where the violation occurred
  %c        Column number where the violation occurred
  %e        Explanation of violation or page numbers in PBP
  %d        Full diagnostic discussion of the violation
  %r        The string of source code that caused the violation
  %P        Name of the Policy module that created the violation
  %p        Name of the Policy without the Perl::Critic::Policy:: prefix
  %s        The severity level of the violation

Here are some examples:

  $Perl::Critic::Violation::FORMAT = "%m at line %l, column %c.\n";
  #looks like "Mixed case variable name at line 6, column 23."

  $Perl::Critic::Violation::FORMAT = "%m near '%r'\n";
  #looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'"

  $Perl::Critic::Violation::FORMAT = "%l:%c:%p\n";
  #looks like "6:23:NamingConventions::ProhibitMixedCaseVars"

  $Perl::Critic::Violation::FORMAT = "%m at line %l. %e. \n%d\n";
  #looks like "Mixed case variable name at line 6.  See page 44 of PBP.
                    Conway's recommended naming convention is to use lower-case words
                    separated by underscores.  Well-recognized acronyms can be in ALL
                    CAPS, but must be separated by underscores from other parts of the
                    name."

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.


TODO - Things for Perl::Critic developers to do

  • SOURCE
  • NEW FEATURES
  • BUGS/LIMITATIONS
  • OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT
  • NON-PBP POLICIES WANTED
  • REFACTORINGS and ENHANCEMENTS
  • PPI BUGS

NAME

TODO - Things for Perl::Critic developers to do

SOURCE

    #######################################################################
    #      $URL: http://perlcritic.tigris.org/svn/perlcritic/tags/Perl-Critic-0.20/TODO.pod $
    #     $Date: 2006-09-10 21:18:18 -0700 (Sun, 10 Sep 2006) $
    #   $Author: thaljef $
    # $Revision: 663 $
    #######################################################################

NEW FEATURES

  • Report Safari sections in addition to book page numbers.
  • Report some statistics on the violations and the source code.

    e.g. Number of violations of each policy/severity. Total lines of code, number of subroutines, average number of statements/operators per sub.

BUGS/LIMITATIONS

  • Errors in .perlcriticrc are silent
  • Modules::RequireVersionVar

    Doesn't enforce three-part versions

  • NamingConventions::ProhibitAmbiguousNames

    Don't allow compound names with forbidden words, like "last_record". Allow forbidden words in RHS of variable declarations

  • Subroutines::ProtectPrivateSubs

    Doesn't forbid $pkg->_foo() because it can't tell the difference between that and $self->_foo()

  • ErrorHandling::RequireCarping

    This should not complain about using warn or die if it's not in a function.

    Also, if the error string ends with a "\n", then the line number and package information is not shown, so it doesn't matter if you use carp/confess or not. For example:

        my $fh;
    if ( !open( $fh, '<', $filename ) ) {
        warn "ack: $filename: $!\n";
        return;
    }

    I just want to print a warning and move on. The location is irrelevant.

OTHER PBP POLICIES THAT SEEM FEASIBLE TO IMPLEMENT

  • ValuesAndExpressions::ProhibitCommaSeparatedStatements (p68)
  • ValuesAndExpressions::RequireListParens (p71)
  • ValuesAndExpressions::ProhibitScalarGrep (p71)

    Look for grep in a scalar context and recommend any() instead. Perhaps we need to distinguish cases like: $count += grep {qr/foo/} @list;

  • Variables::RequireLocalizedPunctuationVars (p81)
  • Variables::ProhibitTopicChangeInListFunction (p114)
  • Documentation::PodSpelling (p148)

    Base it on Pod::Spell or Test::Spelling. Add a "=for stopwords" section for words to skip, as per Pod::Spell.

  • BuiltinFunctions::ProhibitReverseSortBlock (p152)

    Don't allow first instance of $b to be before first instance of $a.

    [Note: already implemented by Chris Dolan, but not committed yet due to PPI bugs. Ask Chris for the patch.]

  • Subroutines::RequireArgUnpacking (p178)

    Ensure that the first child of a sub is PPI::Statement::Variable (unless the sub has N or fewer statements, where N defaults to 1.

  • Subroutines::ProhibitManyArgs (p182)

    If first the PPI::Statement::Variable manpage is a list my, and @_ is used, make sure it's fewer than N elements. Otherwise make sure there are less than N the PPI::Statement::Variable manpages in a row at begin which shift.

  • InputOutput::RequireErrorChecking (p208)

    Forbid open, print, close in void context, unless "use Fatal" is in effect.

  • InputOutput::RequireBriefOpen (p209)

    Make sure there's a close within N statements of an open, both with same lexical FH

  • InputOutput::ProhibitJoinedReadline (p213)
  • InputOutput::ProhibitExplicitStdin (p216)
  • Miscellanea::ProhibitObnoxiousComments

    Forbid excessive hash marks e.g. "#### This is a loud comment ####". Make the obnoxious pattern configurable

  • RegularExpressions::RequireBracesForMultiline (p242)
  • RegularExpressions::ProhibitUnusualDelimiters (p246)
  • RegularExpressions::ProhibitEscapedMetacharacters (p247)
  • RegularExpressions::ProhibitEnumeratedClasses (p248)

    This will be avoided for ASCII-only code

  • RegularExpressions::ProhibitUnusedCapture (p252)

    Look for LHS of regexp or use of $1, $2, ... before next regexp

  • RegularExpressions::ProhibitComplexRegexps (p261)

    If regexp is longer than N characters/lines, require it be split into qr// pieces.

  • RegularExpressions::ProhibitSingleCharAlternation (p265)

    Not sure if this is easy or hard. Need to look at what PPI emits for regexps. Make an exception for qr/ [ ] /x.

  • RegularExpressions::ProhibitFixedStringMatches (p271)

    Can't be qr/\s*\\A\s*\((?:\?:)?(?:\s*\w+\s*\|)*\s*\w+\s*\)\s*\\z/ or qr/\s*\\A\s*\w+\s*\\z/

  • TestingAndDebugging::ProhibitProlongedStrictureOverride (p443)

    This conflicts with TestingAndDebugging::ProhibitNoStrict

NON-PBP POLICIES WANTED

  • BuiltInFunctions::RequireConstantSprintfFormat
  • BuiltInFunctions::RequireConstantUnpackFormat

    http://home.earthlink.net/~josh.jore/new-warnings/slides/slide1.html

  • ControlStructures::ProhibitIncludeViaDo

    Forbid do "foo.pl". Not sure about this policy name.

  • CodingStyle::ProhibitNonASCII

    Definitely low severity! Only looks at code, not comments or POD

  • CodingStyle::RequireUTF8

    All characters must be valid UTF-8. Note that typical ASCII Perl code is a valid UTF8 subset.

  • Miscellanea::RequireMinimumPerlVersion

    Every module should have something like use 5.6.0

  • Miscellanea::Prohibit5006isms

    Keep the code 5.005 compatible Low severity

  • Variables::ProhibitUseVars

    Require our $foo instead. This contradicts Miscellanea::Prohibit5006isms. Maybe verify use 5.6 before applying this policy. Low severity.

  • VariablesAndExpressions::ProhibitQuotedHashKeys

    Forbid quotes around hash keys, unless they are really needed. This is against what Damian says. Suggested by Adam Kennedy. Low severity.

  • Miscellanea::B::Lint

    Create a compatibility layer for the the B::Lint manpage code analyzer. Make it very clear that this runs code and thus is a security hole.

  • CodingStyle::ProhibitFunctionalNew

    Good: Foo::Bar->new, Bad: new Foo::Bar

  • VariablesAndExpressions::RequireConstantVersion (low severity)

    VariablesAndExpressions::ProhibitComplexVersion (medium severity) http://rt.cpan.org/Ticket/Display.html

  • Tests::RequireTestDescriptions

    If Test::More is detected:

       ok $foo;                        # not ok
   ok $foo, 'foo got populated';   # ok
   is $foo, 'bar';                 # not ok
   is $foo, 'bar', 'foo value';    # ok
  • ValuesAndExpressions::ProhibitUselessQuotingOfVariables

    I've seen a lot of beginners do things like this:

        open( my $fh, "$filename" );

    There's no reason for $filename to be quoted. (except stringifying overloaded instances)

  • Variables::ProhibitPerl4PackageNames

    Forbid old-schoole package names like Foo'Bar'Baz. This should also apply to any variables or subroutines that get declared/called.

  • CodingStyle::RequireEditorSettings

    Files must have something like the following in them for Emacs and Vi:

      # Local Variables:
  #   mode: cperl
  #   cperl-indent-level: 4
  #   fill-column: 100
  # End:
  # vim: expandtab shiftwidth=4:
  • Documentation::RequireSynopsis
  • Documentation::RequireLicense

    These are simplified versions of Documentation::RequirePodSections.

  • CodingStyle::RequireConsistentNewlines

    Mixing any two of \r\n, \r and \n in the same file causes problems with GnuPG (and thus Module::Signature). This applies to the whole file, including strings, heredocs, POD, __DATA__, etc.

  • Miscellaneous::ProhibitBoilerplate

    Complain about copy-and-paste code or docs from h2xs, Module::Starter, etc.

REFACTORINGS and ENHANCEMENTS

  • Alias -verbose to -format option in Test::P::C.

    Give it same functionality as the -verbose option in `perlcritic`

  • Enhance P::C::critique() to accept file names, directories, or code strings (as refs)

    Just like bin/perlcritic does now.

  • Add -cache flag to bin/perlcritic

    If enabled, this turns on the PPI::Cache manpage:

        require PPI::Cache;
    my $cache_path = "/tmp/test-perl-critic-cache-$ENV{USER}";
    mkdir $cache_path, oct 700 if (! -d $cache_path);
    PPI::Cache->import(path => $cache_path);

    (see t/40_criticize.t for a more robust implementation)

  • Use the PPI::Document::File features

    This gives us access to the filename. New possible policies:

    • File::RequirePortableName

      No spaces, punctuation, etc.

    • File::RequireNameMatchesPackage

      If the file has package Foo::Bar; then the file path must end with File::Spec-catfile('Foo', 'Bar.$ext');> where $ext is one of pm, pl, PL, pod, etc.

PPI BUGS

We're waiting on the following bugs to get fixed in a CPAN release of PPI:

  • goto as a PPI::Statement::Break instance

    Broken through PPI v1.115, fixed in PPI 1.117, needed to remove workaround from Subroutines::RequireFinalReturn

  • RT #19629: End of list mistakenly seen as end of statement

    Broken through PPI v1.115, fixed in PPI 1.117, needed for BuiltinFunctions::ProhibitReverseSortBlock


Perl::Tidy - Parses and beautifies perl source

  • EXAMPLE
  • Using the formatter Callback Object
  • EXPORT
  • CREDITS
  • VERSION
  • AUTHOR
  • SEE ALSO

NAME

Perl::Tidy - Parses and beautifies perl source

SYNOPSIS

    use Perl::Tidy;

    Perl::Tidy::perltidy(
        source            => $source,
        destination       => $destination,
        stderr            => $stderr,
        argv              => $argv,
        perltidyrc        => $perltidyrc,
        logfile           => $logfile,
        errorfile         => $errorfile,
        formatter         => $formatter,           # callback object (see below)
        dump_options      => $dump_options,
        dump_options_type => $dump_options_type,
    );

DESCRIPTION

This module makes the functionality of the perltidy utility available to perl scripts. Any or all of the input parameters may be omitted, in which case the @ARGV array will be used to provide input parameters as described in the perltidy(1) man page.

For example, the perltidy script is basically just this:

    use Perl::Tidy;
    Perl::Tidy::perltidy();

The module accepts input and output streams by a variety of methods. The following list of parameters may be any of a the following: a filename, an ARRAY reference, a SCALAR reference, or an object with either a getline or print method, as appropriate.

        source            - the source of the script to be formatted
        destination       - the destination of the formatted output
        stderr            - standard error output
        perltidyrc        - the .perltidyrc file
        logfile           - the .LOG file stream, if any
        errorfile         - the .ERR file stream, if any
        dump_options      - ref to a hash to receive parameters (see below),
        dump_options_type - controls contents of dump_options
        dump_getopt_flags - ref to a hash to receive Getopt flags
        dump_options_category - ref to a hash giving category of options
        dump_abbreviations    - ref to a hash giving all abbreviations

The following chart illustrates the logic used to decide how to treat a parameter.

   ref($param)  $param is assumed to be:
   -----------  ---------------------
   undef        a filename
   SCALAR       ref to string
   ARRAY        ref to array
   (other)      object with getline (if source) or print method

If the parameter is an object, and the object has a close method, that close method will be called at the end of the stream.

source

If the source parameter is given, it defines the source of the input stream.

destination

If the destination parameter is given, it will be used to define the file or memory location to receive output of perltidy.

stderr

The stderr parameter allows the calling program to capture the output to what would otherwise go to the standard error output device.

perltidyrc

If the perltidyrc file is given, it will be used instead of any .perltidyrc configuration file that would otherwise be used.

argv

If the argv parameter is given, it will be used instead of the @ARGV array. The argv parameter may be a string, a reference to a string, or a reference to an array. If it is a string or reference to a string, it will be parsed into an array of items just as if it were a command line string.

dump_options

If the dump_options parameter is given, it must be the reference to a hash. In this case, the parameters contained in any perltidyrc configuration file will be placed in this hash and perltidy will return immediately. This is equivalent to running perltidy with --dump-options, except that the perameters are returned in a hash rather than dumped to standard output. Also, by default only the parameters in the perltidyrc file are returned, but this can be changed (see the next parameter). This parameter provides a convenient method for external programs to read a perltidyrc file. An example program using this feature, perltidyrc_dump.pl, is included in the distribution.

Any combination of the dump_ parameters may be used together.

dump_options_type

This parameter is a string which can be used to control the parameters placed in the hash reference supplied by dump_options. The possible values are 'perltidyrc' (default) and 'full'. The 'full' parameter causes both the default options plus any options found in a perltidyrc file to be returned.

dump_getopt_flags

If the dump_getopt_flags parameter is given, it must be the reference to a hash. This hash will receive all of the parameters that perltidy understands and flags that are passed to Getopt::Long. This parameter may be used alone or with the dump_options flag. Perltidy will exit immediately after filling this hash. See the demo program perltidyrc_dump.pl for example usage.

dump_options_category

If the dump_options_category parameter is given, it must be the reference to a hash. This hash will receive a hash with keys equal to all long parameter names and values equal to the title of the corresponding section of the perltidy manual. See the demo program perltidyrc_dump.pl for example usage.

dump_abbreviations

If the dump_abbreviations parameter is given, it must be the reference to a hash. This hash will receive all abbreviations used by Perl::Tidy. See the demo program perltidyrc_dump.pl for example usage.

EXAMPLE

The following example passes perltidy a snippet as a reference to a string and receives the result back in a reference to an array.

 use Perl::Tidy;

 # some messy source code to format
 my $source = <<'EOM';
 use strict;
 my @editors=('Emacs', 'Vi   '); my $rand = rand();
 print "A poll of 10 random programmers gave these results:\n";
 foreach(0..10) {
 my $i=int ($rand+rand());
 print " $editors[$i] users are from Venus" . ", " .
 "$editors[1-$i] users are from Mars" .
 "\n";
 }
 EOM

 # We'll pass it as ref to SCALAR and receive it in a ref to ARRAY
 my @dest;
 perltidy( source => \$source, destination => \@dest );
 foreach (@dest) {print}

Using the formatter Callback Object

The formatter parameter is an optional callback object which allows the calling program to receive tokenized lines directly from perltidy for further specialized processing. When this parameter is used, the two formatting options which are built into perltidy (beautification or html) are ignored. The following diagram illustrates the logical flow:

                    |-- (normal route)   -> code beautification
  caller->perltidy->|-- (-html flag )    -> create html
                    |-- (formatter given)-> callback to write_line

This can be useful for processing perl scripts in some way. The parameter $formatter in the perltidy call,

        formatter   => $formatter,

is an object created by the caller with a write_line method which will accept and process tokenized lines, one line per call. Here is a simple example of a write_line which merely prints the line number, the line type (as determined by perltidy), and the text of the line:

 sub write_line {

     # This is called from perltidy line-by-line
     my $self              = shift;
     my $line_of_tokens    = shift;
     my $line_type         = $line_of_tokens->{_line_type};
     my $input_line_number = $line_of_tokens->{_line_number};
     my $input_line        = $line_of_tokens->{_line_text};
     print "$input_line_number:$line_type:$input_line";
 }

The complete program, perllinetype, is contained in the examples section of the source distribution. As this example shows, the callback method receives a parameter $line_of_tokens, which is a reference to a hash of other useful information. This example uses these hash entries:

 $line_of_tokens->{_line_number} - the line number (1,2,...)
 $line_of_tokens->{_line_text}   - the text of the line
 $line_of_tokens->{_line_type}   - the type of the line, one of:

    SYSTEM         - system-specific code before hash-bang line
    CODE           - line of perl code (including comments)
    POD_START      - line starting pod, such as '=head'
    POD            - pod documentation text
    POD_END        - last line of pod section, '=cut'
    HERE           - text of here-document
    HERE_END       - last line of here-doc (target word)
    FORMAT         - format section
    FORMAT_END     - last line of format section, '.'
    DATA_START     - __DATA__ line
    DATA           - unidentified text following __DATA__
    END_START      - __END__ line
    END            - unidentified text following __END__
    ERROR          - we are in big trouble, probably not a perl script

Most applications will be only interested in lines of type CODE. For another example, let's write a program which checks for one of the so-called naughty matching variables &`, $&, and $', which can slow down processing. Here is a write_line, from the example program find_naughty.pl, which does that:

 sub write_line {

     # This is called back from perltidy line-by-line
     # We're looking for $`, $&, and $'
     my ( $self, $line_of_tokens ) = @_;

     # pull out some stuff we might need
     my $line_type         = $line_of_tokens->{_line_type};
     my $input_line_number = $line_of_tokens->{_line_number};
     my $input_line        = $line_of_tokens->{_line_text};
     my $rtoken_type       = $line_of_tokens->{_rtoken_type};
     my $rtokens           = $line_of_tokens->{_rtokens};
     chomp $input_line;

     # skip comments, pod, etc
     return if ( $line_type ne 'CODE' );

     # loop over tokens looking for $`, $&, and $'
     for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) {

         # we only want to examine token types 'i' (identifier)
         next unless $$rtoken_type[$j] eq 'i';

         # pull out the actual token text
         my $token = $$rtokens[$j];

         # and check it
         if ( $token =~ /^\$[\`\&\']$/ ) {
             print STDERR
               "$input_line_number: $token\n";
         }
     }
 }

This example pulls out these tokenization variables from the $line_of_tokens hash reference:

     $rtoken_type = $line_of_tokens->{_rtoken_type};
     $rtokens     = $line_of_tokens->{_rtokens};

The variable $rtoken_type is a reference to an array of token type codes, and $rtokens is a reference to a corresponding array of token text. These are obviously only defined for lines of type CODE. Perltidy classifies tokens into types, and has a brief code for each type. You can get a complete list at any time by running perltidy from the command line with

     perltidy --dump-token-types

In the present example, we are only looking for tokens of type i (identifiers), so the for loop skips past all other types. When an identifier is found, its actual text is checked to see if it is one being sought. If so, the above write_line prints the token and its line number.

The formatter feature is relatively new in perltidy, and further documentation needs to be written to complete its description. However, several example programs have been written and can be found in the examples section of the source distribution. Probably the best way to get started is to find one of the examples which most closely matches your application and start modifying it.

For help with perltidy's pecular way of breaking lines into tokens, you might run, from the command line,

 perltidy -D filename

where filename is a short script of interest. This will produce filename.DEBUG with interleaved lines of text and their token types. The -D flag has been in perltidy from the beginning for this purpose. If you want to see the code which creates this file, it is write_debug_entry in Tidy.pm.

EXPORT

  &perltidy

CREDITS

Thanks to Hugh Myers who developed the initial modular interface to perltidy.

VERSION

This man page documents Perl::Tidy version 20070508.

AUTHOR

 Steve Hancock
 perltidy at users.sourceforge.net

SEE ALSO

The perltidy(1) man page describes all of the features of perltidy. It can be found at http://perltidy.sourceforge.net.


PerlEx::DBI - Initiate a persistent database connection

  • CONFIGURATION
  • PREREQUISITES
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

PerlEx::DBI - Initiate a persistent database connection

SYNOPSIS

    # add this switch to CommandLineOptions setting in Interpreter Class
    -mPerlEx::DBI
    # or add next line to StartupCode setting in the Interpreter Class
    use PerlEx::DBI ();  # this comes before all other modules using DBI

Note to Apache users: PerlEx::DBI is based on Apache::DBI. Except for the configuration noted above, PerlEx::DBI is functionally identical to Apache::DBI.

You do NOT need to change anything in your scripts. The usage of this module is absolutely transparent!

DESCRIPTION

This module transparently initiates persistent database connections.

The database access must be via the DBI module. For supported DBI drivers see:

    http://www.symbolstone.org/technology/perl/DBI/

When the DBI module is loaded by your script (do not confuse this with the loading of the PerlEx::DBI module itself) DBI looks at the environment variable GATEWAY_INTERFACE and checks to see if it starts with 'CGI-Perl', and whether an Apache::DBI compatible module (in this case PerlEx::DBI) has been loaded. If that is the case, every connect request will be forwarded to the Apache::DBI compatible module.

PerlEx::DBI then looks at whether a database handle from a previous connect request is already cached and whether the cached handle is still valid, using the ping method. If these two conditions are fulfilled it just returns the cached database handle. The parameters defining the connection have to be exactly the same for a cached handle to be selected, including the connect attributes. If there is no appropriate database handle or if the ping method fails, a new connection is established and the handle is cached for later re-use. There is no need to remove any disconnect() calls from your code. They won't do anything because the PerlEx::DBI module overloads the disconnect method.

The PerlEx::DBI module still has a potential limitation: it keeps database connections persistent on a per-interpreter basis. This means that if a user accesses a database several times, the http requests may end up being handled by different PerlEx interpreters, even though PerlEx tries to use as few interpreters as possible. In this case, every interpreter needs to do its own connect. It would be nice if all interpreters could share the database handles, but currently this is not possible because of strict isolation of the data space of interpreters, for scalability and security reasons. Also, it is currently not possible to create a database handle upon PerlEx startup and later inheriting this handle in every subsequent interpreter.

With these limitations in mind, there may be some scenarios where the usage of PerlEx::DBI may not be worthwhile. Consider a heavily loaded web site where every user connects to the database with a unique userid. This could cause many database handles to be initialized and kept persistent, hogging database resources.

If you find that PerlEx::DBI results in consumption of excess database resources, you should investigate enabling the native connection pooling features of your database instead of enabling PerlEx::DBI for your scripts.

Another potential problem are timeouts: some databases disconnect the client after a certain period of inactivity. PerlEx::DBI normally tries to validate the database handle using the ping-method of the DBI-module. This method returns true as default. If the database handle is not valid and the driver has no implementation for the ping method, you will get an error when accessing the database. To work around this, you can try to replace the ping method by any database command, which is cheap and safe, or you may deactivate the usage of the ping method (see CONFIGURATION below).

Here is a generalized ping method, which can be added to the driver module:

{ package DBD::xxx::db; # ====== DATABASE ====== use strict;

    sub ping {
        my($dbh) = @_;
        my $ret = 0;
        eval {
            local $SIG{__DIE__}  = sub { return (0); };
            local $SIG{__WARN__} = sub { return (0); };
            # adapt the select statement to your database:
            $ret = $dbh->do('select 1');
        };
        return ($@) ? 0 : $ret;
    }
    }

Transactions: a standard DBI script will automatically perform a rollback whenever the script exits. In the case of persistent database connections, the database handle will not be destroyed and hence no automatic rollback occurs. While at first glance it might seem practical to handle a transaction over multiple requests, this will not really work because different requests may be handled by different interpreters. One interpreter will not know the state of a specific transaction which has been started by another interpreter.

In general it is good practice to perform an explicit commit or rollback at the end of every script. In order to avoid inconsistencies in the database in case AutoCommit is off and the script finishes without an explicit rollback, the PerlEx::DBI module uses a cleanup handler to issue a rollback at the end of every request. Note that this cleanup handler will only be used if the initial data_source sets AutoCommit = 0. It will not be used if AutoCommit is turned off after the connect has been done.

CONFIGURATION

PerlEx::DBI should be loaded upon startup of a PerlEx Interpreter Class. This can be done either by adding the following switch to the CommandLineOptions registry setting:

    -mPerlEx::DBI

or by adding the following line to the StartupCode setting such that it executes before anything else that loads the DBI module:

    use PerlEx::DBI ();

Either of the above can be set within an Interpreter Class to restrict the setting to a single script or a set of scripts under a given location. See the PerlEx documentation for more information on these registry settings.

Note that it is important to load PerlEx::DBI before any other modules using DBI!

There is one configuration which is server-specific and which can be done within the script after $data_source has been initialized:

    PerlEx::DBI->setPingTimeOut($data_source, $timeout);

This configures the usage of the ping method, to validate a connection. Setting the timeout to 0 will always validate the database connection using the ping method (default). Setting the timeout < 0 will de-activate the validation of the database handle. This can be used for drivers which do not implement the ping-method. Setting the timeout > 0 will ping the database only if the last access was more than timeout seconds before.

To enable logging, set the Trace value for your Interpreter Class to 1 or higher. Setting the variable to 1 simply reports every new connect. Setting Trace to 2 enables full debug output.

PREREQUISITES

Note that this module needs PerlEx 2.2 or higher and DBI 1.14 or higher.

SEE ALSO

the DBI manpage

AUTHORS

  • PerlEx::DBI is a modified version of Apache::DBI. PerlEx::DBI by Shane Caraveo <ShaneC@ActiveState.com>

  • Apache::DBI by Edmund Mergl <E.Mergl@bawue.de>

  • DBI by Tim Bunce <dbi-users@isc.org>

COPYRIGHT

The PerlEx::DBI module is based on Apache::DBI and is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space

    • Custom Layers
    • Alternatives to raw
    • Defaults and how to override them
    • Querying the layers of filehandles
  • AUTHOR
  • SEE ALSO

NAME

PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space

SYNOPSIS

  open($fh,"<:crlf", "my.txt"); # support platform-native and CRLF text files

  open($fh,"<","his.jpg");      # portably open a binary file for reading
  binmode($fh);

  Shell:
    PERLIO=perlio perl ....

DESCRIPTION

When an undefined layer 'foo' is encountered in an open or binmode layer specification then C code performs the equivalent of:

  use PerlIO 'foo';

The perl code in PerlIO.pm then attempts to locate a layer by doing

  require PerlIO::foo;

Otherwise the PerlIO package is a place holder for additional PerlIO related functions.

The following layers are currently defined:

:unix

Lowest level layer which provides basic PerlIO operations in terms of UNIX/POSIX numeric file descriptor calls (open(), read(), write(), lseek(), close()).

:stdio

Layer which calls fread, fwrite and fseek/ftell etc. Note that as this is "real" stdio it will ignore any layers beneath it and got straight to the operating system via the C library as usual.

:perlio

A from scratch implementation of buffering for PerlIO. Provides fast access to the buffer for sv_gets which implements perl's readline/<> and in general attempts to minimize data copying.

:perlio will insert a :unix layer below itself to do low level IO.

:crlf

A layer that implements DOS/Windows like CRLF line endings. On read converts pairs of CR,LF to a single "\n" newline character. On write converts each "\n" to a CR,LF pair. Note that this layer likes to be one of its kind: it silently ignores attempts to be pushed into the layer stack more than once.

It currently does not mimic MS-DOS as far as treating of Control-Z as being an end-of-file marker.

(Gory details follow) To be more exact what happens is this: after pushing itself to the stack, the :crlf layer checks all the layers below itself to find the first layer that is capable of being a CRLF layer but is not yet enabled to be a CRLF layer. If it finds such a layer, it enables the CRLFness of that other deeper layer, and then pops itself off the stack. If not, fine, use the one we just pushed.

The end result is that a :crlf means "please enable the first CRLF layer you can find, and if you can't find one, here would be a good spot to place a new one."

Based on the :perlio layer.

:mmap

A layer which implements "reading" of files by using mmap() to make (whole) file appear in the process's address space, and then using that as PerlIO's "buffer". This may be faster in certain circumstances for large files, and may result in less physical memory use when multiple processes are reading the same file.

Files which are not mmap()-able revert to behaving like the :perlio layer. Writes also behave like :perlio layer as mmap() for write needs extra house-keeping (to extend the file) which negates any advantage.

The :mmap layer will not exist if platform does not support mmap().

:utf8

Declares that the stream accepts perl's internal encoding of characters. (Which really is UTF-8 on ASCII machines, but is UTF-EBCDIC on EBCDIC machines.) This allows any character perl can represent to be read from or written to the stream. The UTF-X encoding is chosen to render simple text parts (i.e. non-accented letters, digits and common punctuation) human readable in the encoded file.

Here is how to write your native data out using UTF-8 (or UTF-EBCDIC) and then read it back in.

        open(F, ">:utf8", "data.utf");
        print F $out;
        close(F);

        open(F, "<:utf8", "data.utf");
        $in = <F>;
        close(F);
:bytes

This is the inverse of :utf8 layer. It turns off the flag on the layer below so that data read from it is considered to be "octets" i.e. characters in range 0..255 only. Likewise on output perl will warn if a "wide" character is written to a such a stream.

:raw

The :raw layer is defined as being identical to calling binmode($fh) - the stream is made suitable for passing binary data i.e. each byte is passed as-is. The stream will still be buffered.

In Perl 5.6 and some books the :raw layer (previously sometimes also referred to as a "discipline") is documented as the inverse of the :crlf layer. That is no longer the case - other layers which would alter binary nature of the stream are also disabled. If you want UNIX line endings on a platform that normally does CRLF translation, but still want UTF-8 or encoding defaults the appropriate thing to do is to add :perlio to PERLIO environment variable.

The implementation of :raw is as a pseudo-layer which when "pushed" pops itself and then any layers which do not declare themselves as suitable for binary data. (Undoing :utf8 and :crlf are implemented by clearing flags rather than popping layers but that is an implementation detail.)

As a consequence of the fact that :raw normally pops layers it usually only makes sense to have it as the only or first element in a layer specification. When used as the first element it provides a known base on which to build e.g.

    open($fh,":raw:utf8",...)

will construct a "binary" stream, but then enable UTF-8 translation.

:pop

A pseudo layer that removes the top-most layer. Gives perl code a way to manipulate the layer stack. Should be considered as experimental. Note that :pop only works on real layers and will not undo the effects of pseudo layers like :utf8. An example of a possible use might be:

    open($fh,...)
    ...
    binmode($fh,":encoding(...)");  # next chunk is encoded
    ...
    binmode($fh,":pop");            # back to un-encoded

A more elegant (and safer) interface is needed.

:win32

On Win32 platforms this experimental layer uses native "handle" IO rather than unix-like numeric file descriptor layer. Known to be buggy as of perl 5.8.2.

Custom Layers

It is possible to write custom layers in addition to the above builtin ones, both in C/XS and Perl. Two such layers (and one example written in Perl using the latter) come with the Perl distribution.

:encoding

Use :encoding(ENCODING) either in open() or binmode() to install a layer that does transparently character set and encoding transformations, for example from Shift-JIS to Unicode. Note that under stdio an :encoding also enables :utf8. See the PerlIO::encoding manpage for more information.

:via

Use :via(MODULE) either in open() or binmode() to install a layer that does whatever transformation (for example compression / decompression, encryption / decryption) to the filehandle. See the PerlIO::via manpage for more information.

Alternatives to raw

To get a binary stream an alternate method is to use:

    open($fh,"whatever")
    binmode($fh);

this has advantage of being backward compatible with how such things have had to be coded on some platforms for years.

To get an un-buffered stream specify an unbuffered layer (e.g. :unix) in the open call:

    open($fh,"<:unix",$path)

Defaults and how to override them

If the platform is MS-DOS like and normally does CRLF to "\n" translation for text files then the default layers are :

  unix crlf

(The low level "unix" layer may be replaced by a platform specific low level layer.)

Otherwise if Configure found out how to do "fast" IO using system's stdio, then the default layers are:

  unix stdio

Otherwise the default layers are

  unix perlio

These defaults may change once perlio has been better tested and tuned.

The default can be overridden by setting the environment variable PERLIO to a space separated list of layers (unix or platform low level layer is always pushed first).

This can be used to see the effect of/bugs in the various layers e.g.

  cd .../perl/t
  PERLIO=stdio  ./perl harness
  PERLIO=perlio ./perl harness

For the various value of PERLIO see PERLIO in the perlrun manpage.

Querying the layers of filehandles

The following returns the names of the PerlIO layers on a filehandle.

   my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".

The layers are returned in the order an open() or binmode() call would use them. Note that the "default stack" depends on the operating system and on the Perl version, and both the compile-time and runtime configurations of Perl.

The following table summarizes the default layers on UNIX-like and DOS-like platforms and depending on the setting of the $ENV{PERLIO}:

 PERLIO     UNIX-like                   DOS-like
 ------     ---------                   --------
 unset / "" unix perlio / stdio [1]     unix crlf
 stdio      unix perlio / stdio [1]     stdio
 perlio     unix perlio                 unix perlio
 mmap       unix mmap                   unix mmap
 # [1] "stdio" if Configure found out how to do "fast stdio" (depends
 # on the stdio implementation) and in Perl 5.8, otherwise "unix perlio"

By default the layers from the input side of the filehandle is returned, to get the output side use the optional output argument:

   my @layers = PerlIO::get_layers($fh, output => 1);

(Usually the layers are identical on either side of a filehandle but for example with sockets there may be differences, or if you have been using the open pragma.)

There is no set_layers(), nor does get_layers() return a tied array mirroring the stack, or anything fancy like that. This is not accidental or unintentional. The PerlIO layer stack is a bit more complicated than just a stack (see for example the behaviour of :raw). You are supposed to use open() and binmode() to manipulate the stack.

Implementation details follow, please close your eyes.

The arguments to layers are by default returned in parenthesis after the name of the layer, and certain layers (like utf8) are not real layers but instead flags on real layers: to get all of these returned separately use the optional details argument:

   my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);

The result will be up to be three times the number of layers: the first element will be a name, the second element the arguments (unspecified arguments will be undef), the third element the flags, the fourth element a name again, and so forth.

You may open your eyes now.

AUTHOR

Nick Ing-Simmons <nick@ing-simmons.net>

SEE ALSO

binmode in the perlfunc manpage, open in the perlfunc manpage, the perlunicode manpage, the perliol manpage, the Encode manpage


PerlIO::encoding - encoding layer

  • SEE ALSO

NAME

PerlIO::encoding - encoding layer

SYNOPSIS

  open($f, "<:encoding(foo)", "infoo");
  open($f, ">:encoding(bar)", "outbar");

  use Encode qw(:fallbacks);
  $PerlIO::encoding::fallback = FB_PERLQQ;

DESCRIPTION

Open a filehandle with a transparent encoding filter.

On input, convert the bytes expected to be in the specified character set and encoding to Perl string data (Unicode and Perl's internal Unicode encoding, UTF-8). On output, convert Perl string data into the specified character set and encoding.

When the layer is pushed the current value of $PerlIO::encoding::fallback is saved and used as the CHECK argument when calling the Encode methods encode() and decode().

SEE ALSO

the open manpage, the Encode manpage, binmode in the perlfunc manpage, the perluniintro manpage


PerlIO::scalar - in-memory IO, scalar IO

  • IMPLEMENTATION NOTE

NAME

PerlIO::scalar - in-memory IO, scalar IO

SYNOPSIS

   my $scalar = '';
   ...
   open my $fh, "<",  \$scalar or die;
   open my $fh, ">",  \$scalar or die;
   open my $fh, ">>", \$scalar or die;

or

   my $scalar = '';
   ...
   open my $fh, "<:scalar",  \$scalar or die;
   open my $fh, ">:scalar",  \$scalar or die;
   open my $fh, ">>:scalar", \$scalar or die;

DESCRIPTION

A filehandle is opened but the file operations are performed "in-memory" on a scalar variable. All the normal file operations can be performed on the handle. The scalar is considered a stream of bytes. Currently fileno($fh) returns undef.

IMPLEMENTATION NOTE

PerlIO::scalar only exists to use XSLoader to load C code that provides support for treating a scalar as an "in memory" file. One does not need to explicitly use PerlIO::scalar.


PerlIO::via - Helper class for PerlIO layers implemented in perl

  • EXPECTED METHODS
  • EXAMPLES
    • Example - a Hexadecimal Handle

NAME

PerlIO::via - Helper class for PerlIO layers implemented in perl

SYNOPSIS

   use PerlIO::via::Layer;
   open($fh,"<:via(Layer)",...);

   use Some::Other::Package;
   open($fh,">:via(Some::Other::Package)",...);

DESCRIPTION

The PerlIO::via module allows you to develop PerlIO layers in Perl, without having to go into the nitty gritty of programming C with XS as the interface to Perl.

One example module, the PerlIO::via::QuotedPrint manpage, is included with Perl 5.8.0, and more example modules are available from CPAN, such as the PerlIO::via::StripHTML manpage and the PerlIO::via::Base64 manpage. The PerlIO::via::StripHTML module for instance, allows you to say:

        use PerlIO::via::StripHTML;
        open( my $fh, "<:via(StripHTML)", "index.html" );
        my @line = <$fh>;

to obtain the text of an HTML-file in an array with all the HTML-tags automagically removed.

Please note that if the layer is created in the PerlIO::via:: namespace, it does not have to be fully qualified. The PerlIO::via module will prefix the PerlIO::via:: namespace if the specified modulename does not exist as a fully qualified module name.

EXPECTED METHODS

To create a Perl module that implements a PerlIO layer in Perl (as opposed to in C using XS as the interface to Perl), you need to supply some of the following subroutines. It is recommended to create these Perl modules in the PerlIO::via:: namespace, so that they can easily be located on CPAN and use the default namespace feature of the PerlIO::via module itself.

Please note that this is an area of recent development in Perl and that the interface described here is therefore still subject to change (and hopefully will have better documentation and more examples).

In the method descriptions below $fh will be a reference to a glob which can be treated as a perl file handle. It refers to the layer below. $fh is not passed if the layer is at the bottom of the stack, for this reason and to maintain some level of "compatibility" with TIEHANDLE classes it is passed last.

$class->PUSHED([$mode[,$fh]])

Should return an object or the class, or -1 on failure. (Compare TIEHANDLE.) The arguments are an optional mode string ("r", "w", "w+", ...) and a filehandle for the PerlIO layer below. Mandatory.

When layer is pushed as part of an open call, PUSHED will be called before the actual open occurs whether than be via OPEN, SYSOPEN, FDOPEN or by letting lower layer do the open.

$obj->POPPED([$fh])

Optional - layer is about to be removed.

$obj->UTF8($bellowFlag,[$fh])

Optional - if present it will be called immediately after PUSHED has returned. It should return true value if the layer expects data to be UTF-8 encoded. If it returns true result is as if caller had done

   ":via(YourClass):utf8"

If not present of it it returns false, then stream is left with flag clear. The $bellowFlag argument will be true if there is a layer below and that layer was expecting UTF-8.

$obj->OPEN($path,$mode[,$fh])

Optional - if not present lower layer does open. If present called for normal opens after layer is pushed. This function is subject to change as there is no easy way to get lower layer to do open and then regain control.

$obj->BINMODE([,$fh])

Optional - if not available layer is popped on binmode($fh) or when :raw is pushed. If present it should return 0 on success -1 on error and undef to pop the layer.

$obj->FDOPEN($fd[,$fh])

Optional - if not present lower layer does open. If present called for opens which pass a numeric file descriptor after layer is pushed. This function is subject to change as there is no easy way to get lower layer to do open and then regain control.

$obj->SYSOPEN($path,$imode,$perm,[,$fh])

Optional - if not present lower layer does open. If present called for sysopen style opens which pass a numeric mode and permissions after layer is pushed. This function is subject to change as there is no easy way to get lower layer to do open and then regain control.

$obj->FILENO($fh)

Returns a numeric value for Unix-like file descriptor. Return -1 if there isn't one. Optional. Default is fileno($fh).

$obj->READ($buffer,$len,$fh)

Returns the number of octets placed in $buffer (must be less than or equal to $len). Optional. Default is to use FILL instead.

$obj->WRITE($buffer,$fh)

Returns the number of octets from buffer that have been successfully written.

$obj->FILL($fh)

Should return a string to be placed in the buffer. Optional. If not provided must provide READ or reject handles open for reading in PUSHED.

$obj->CLOSE($fh)

Should return 0 on success, -1 on error. Optional.

$obj->SEEK($posn,$whence,$fh)

Should return 0 on success, -1 on error. Optional. Default is to fail, but that is likely to be changed in future.

$obj->TELL($fh)

Returns file postion. Optional. Default to be determined.

$obj->UNREAD($buffer,$fh)

Returns the number of octets from buffer that have been successfully saved to be returned on future FILL/READ calls. Optional. Default is to push data into a temporary layer above this one.

$obj->FLUSH($fh)

Flush any buffered write data. May possibly be called on readable handles too. Should return 0 on success, -1 on error.

$obj->SETLINEBUF($fh)

Optional. No return.

$obj->CLEARERR($fh)

Optional. No return.

$obj->ERROR($fh)

Optional. Returns error state. Default is no error until a mechanism to signal error (die?) is worked out.

$obj->EOF($fh)

Optional. Returns end-of-file state. Default is function of return value of FILL or READ.

EXAMPLES

Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers implemented in Perl. To give you an idea how simple the implementation of a PerlIO layer can look, as simple example is included here.

Example - a Hexadecimal Handle

Given the following module, PerlIO::via::Hex :

    package PerlIO::via::Hex;

    sub PUSHED
    {
     my ($class,$mode,$fh) = @_;
     # When writing we buffer the data
     my $buf = '';
     return bless \$buf,$class;
    }

    sub FILL
    {
     my ($obj,$fh) = @_;
     my $line = <$fh>;
     return (defined $line) ? pack("H*", $line) : undef;
    }

    sub WRITE
    {
     my ($obj,$buf,$fh) = @_;
     $$obj .= unpack("H*", $buf);
     return length($buf);
    }

    sub FLUSH
    {
     my ($obj,$fh) = @_;
     print $fh $$obj or return -1;
     $$obj = '';
     return 0;
    }

    1;

the following code opens up an output handle that will convert any output to hexadecimal dump of the output bytes: for example "A" will be converted to "41" (on ASCII-based machines, on EBCDIC platforms the "A" will become "c1")

    use PerlIO::via::Hex;
    open(my $fh, ">:via(Hex)", "foo.hex");

and the following code will read the hexdump in and convert it on the fly back into bytes:

    open(my $fh, "<:via(Hex)", "foo.hex");


PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings

  • REQUIRED MODULES
  • SEE ALSO
  • ACKNOWLEDGEMENTS
  • COPYRIGHT

NAME

PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings

SYNOPSIS

 use PerlIO::via::QuotedPrint;

 open( my $in,'<:via(QuotedPrint)','file.qp' )
  or die "Can't open file.qp for reading: $!\n";

 open( my $out,'>:via(QuotedPrint)','file.qp' )
  or die "Can't open file.qp for writing: $!\n";

DESCRIPTION

This module implements a PerlIO layer that works on files encoded in the quoted-printable format. It will decode from quoted-printable while reading from a handle, and it will encode as quoted-printable while writing to a handle.

REQUIRED MODULES

 MIME::QuotedPrint (any)

SEE ALSO

the PerlIO::via manpage, the MIME::QuotedPrint manpage, the PerlIO::via::Base64 manpage, the PerlIO::via::MD5 manpage, the PerlIO::via::StripHTML manpage, the PerlIO::via::Rotate manpage.

ACKNOWLEDGEMENTS

Based on example that was initially added to MIME::QuotedPrint.pm for the 5.8.0 distribution of Perl.

COPYRIGHT

Copyright (c) 2002-2003 Elizabeth Mattijsen. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


podchecker - check pod documents for syntax errors

  • OPTIONS/ARGUMENTS
    • podchecker()
  • DESCRIPTION
  • DIAGNOSTICS
    • Errors
    • Warnings
    • Hyperlinks
  • RETURN VALUE
  • EXAMPLES
  • INTERFACE
  • AUTHOR

NAME

Pod::Checker, podchecker() - check pod documents for syntax errors

SYNOPSIS

  use Pod::Checker;

  $syntax_okay = podchecker($filepath, $outputpath, %options);

  my $checker = new Pod::Checker %options;
  $checker->parse_from_file($filepath, \*STDERR);

OPTIONS/ARGUMENTS

$filepath is the input POD to read and $outputpath is where to write POD syntax error messages. Either argument may be a scalar indicating a file-path, or else a reference to an open filehandle. If unspecified, the input-file it defaults to \*STDIN, and the output-file defaults to \*STDERR.

podchecker()

This function can take a hash of options:

-warnings => val

Turn warnings on/off. val is usually 1 for on, but higher values trigger additional warnings. See Warnings.

DESCRIPTION

podchecker will perform syntax checking of Perl5 POD format documentation.

Curious/ambitious users are welcome to propose additional features they wish to see in Pod::Checker and podchecker and verify that the checks are consistent with the perlpod manpage.

The following checks are currently performed:

  • Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and unterminated interior sequences.

  • Check for proper balancing of =begin and =end. The contents of such a block are generally ignored, i.e. no syntax checks are performed.

  • Check for proper nesting and balancing of =over, =item and =back.

  • Check for same nested interior-sequences (e.g. L<...L<...>...>).

  • Check for malformed or nonexisting entities E<...>.

  • Check for correct syntax of hyperlinks L<...>. See the perlpod manpage for details.

  • Check for unresolved document-internal links. This check may also reveal misspelled links that seem to be internal links but should be links to something else.

DIAGNOSTICS

Errors

  • empty =headn

    A heading (=head1 or =head2) without any text? That ain't no heading!

  • =over on line N without closing =back

    The =over command does not have a corresponding =back before the next heading (=head1 or =head2) or the end of the file.

  • =item without previous =over
  • =back without previous =over

    An =item or =back command has been found outside a =over/=back block.

  • No argument for =begin

    A =begin command was found that is not followed by the formatter specification.

  • =end without =begin

    A standalone =end command was found.

  • Nested =begin's

    There were at least two consecutive =begin commands without the corresponding =end. Only one =begin may be active at a time.

  • =for without formatter specification

    There is no specification of the formatter after the =for command.

  • unresolved internal link NAME

    The given link to NAME does not have a matching node in the current POD. This also happend when a single word node name is not enclosed in "".

  • Unknown command "CMD"

    An invalid POD command has been found. Valid are =head1, =head2, =head3, =head4, =over, =item, =back, =begin, =end, =for, =pod, =cut

  • Unknown interior-sequence "SEQ"

    An invalid markup command has been encountered. Valid are: B<>, C<>, E<>, F<>, I<>, L<>, S<>, X<>, Z<>

  • nested commands CMD<...CMD<...>...>

    Two nested identical markup commands have been found. Generally this does not make sense.

  • garbled entity STRING

    The STRING found cannot be interpreted as a character entity.

  • Entity number out of range

    An entity specified by number (dec, hex, oct) is out of range (1-255).

  • malformed link L<>

    The link found cannot be parsed because it does not conform to the syntax described in the perlpod manpage.

  • nonempty Z<>

    The Z<> sequence is supposed to be empty.

  • empty X<>

    The index entry specified contains nothing but whitespace.

  • Spurious text after =pod / =cut

    The commands =pod and =cut do not take any arguments.

  • Spurious character(s) after =back

    The =back command does not take any arguments.

Warnings

These may not necessarily cause trouble, but indicate mediocre style.

  • multiple occurrence of link target name

    The POD file has some =item and/or =head commands that have the same text. Potential hyperlinks to such a text cannot be unique then. This warning is printed only with warning level greater than one.

  • line containing nothing but whitespace in paragraph

    There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. vi users switch on the list option to avoid this problem.

  • previous =item has no contents

    There is a list =item right above the flagged line that has no text contents. You probably want to delete empty items.

  • preceding non-item paragraph(s)

    A list introduced by =over starts with a text or verbatim paragraph, but continues with =items. Move the non-item paragraph out of the =over/=back block.

  • =item type mismatch (one vs. two)

    A list started with e.g. a bulletted =item and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first =item determines the type of the list.

  • N unescaped <> in paragraph

    Angle brackets not written as <lt> and <gt> can potentially cause errors as they could be misinterpreted as markup commands. This is only printed when the -warnings level is greater than 1.

  • Unknown entity

    A character entity was found that does not belong to the standard ISO set or the POD specials verbar and sol.

  • No items in =over

    The list opened with =over does not contain any items.

  • No argument for =item

    =item without any parameters is deprecated. It should either be followed by * to indicate an unordered list, by a number (optionally followed by a dot) to indicate an ordered (numbered) list or simple text for a definition list.

  • empty section in previous paragraph

    The previous section (introduced by a =head command) does not contain any text. This usually indicates that something is missing. Note: A =head1 followed immediately by =head2 does not trigger this warning.

  • Verbatim paragraph in NAME section

    The NAME section (=head1 NAME) should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for.

  • =headn without preceding higher level

    For example if there is a =head2 in the POD file prior to a =head1.

Hyperlinks

There are some warnings wrt. malformed hyperlinks.

  • ignoring leading/trailing whitespace in link

    There is whitespace at the beginning or the end of the contents of L<...>.

  • (section) in '$page' deprecated

    There is a section detected in the page name of L<...>, e.g. L<passwd(2)>. POD hyperlinks may point to POD documents only. Please write C<passwd(2)> instead. Some formatters are able to expand this to appropriate code. For links to (builtin) functions, please say L<perlfunc/mkdir>, without ().

  • alternative text/node '%s' contains non-escaped | or /

    The characters | and / are special in the L<...> context. Although the hyperlink parser does its best to determine which "/" is text and which is a delimiter in case of doubt, one ought to escape these literal characters like this:

      /     E<sol>
  |     E<verbar>

RETURN VALUE

podchecker returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file.

EXAMPLES

See SYNOPSIS

INTERFACE

While checking, this module collects document properties, e.g. the nodes for hyperlinks (=headX, =item) and index entries (X<>). POD translators can use this feature to syntax-check and get the nodes in a first pass before actually starting to convert. This is expensive in terms of execution time, but allows for very robust conversions.

Since PodParser-1.24 the Pod::Checker module uses only the poderror method to print errors and warnings. The summary output (e.g. "Pod syntax OK") has been dropped from the module and has been included in podchecker (the script). This allows users of Pod::Checker to control completely the output behaviour. Users of podchecker (the script) get the well-known behaviour.

Pod::Checker->new( %options )

Return a reference to a new Pod::Checker object that inherits from Pod::Parser and is used for calling the required methods later. The following options are recognized:

-warnings => num Print warnings if num is true. The higher the value of num, the more warnings are printed. Currently there are only levels 1 and 2.

-quiet => num If num is true, do not print any errors/warnings. This is useful when Pod::Checker is used to munge POD code into plain text from within POD formatters.

$checker->poderror( @args )
$checker->poderror( {%opts}, @args )

Internal method for printing errors and warnings. If no options are given, simply prints "@_". The following options are recognized and used to form the output:

  -msg

A message to print prior to @args.

  -line

The line number the error occurred in.

  -file

The file (name) the error occurred in.

  -severity

The error level, should be 'WARNING' or 'ERROR'.

$checker->num_errors()

Set (if argument specified) and retrieve the number of errors found.

$checker->num_warnings()

Set (if argument specified) and retrieve the number of warnings found.

$checker->name()

Set (if argument specified) and retrieve the canonical name of POD as found in the =head1 NAME section.

$checker->node()

Add (if argument specified) and retrieve the nodes (as defined by =headX and =item) of the current POD. The nodes are returned in the order of their occurrence. They consist of plain text, each piece of whitespace is collapsed to a single blank.

$checker->idx()

Add (if argument specified) and retrieve the index entries (as defined by X<>) of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank.

$checker->hyperlink()

Add (if argument specified) and retrieve the hyperlinks (as defined by L<>) of the current POD. They consist of a 2-item array: line number and Pod::Hyperlink object.

AUTHOR

Please report bugs using http://rt.cpan.org.

Brad Appleton <bradapp@enteract.com> (initial version), Marek Rouchal <marekr@cpan.org>

Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>


Pod::Find - find POD documents in directory trees

    • pod_find( { %opts } , @directories )
    • simplify_name( $str )
    • pod_where( { %opts }, $pod )
    • contains_pod( $file , $verbose )
  • AUTHOR
  • SEE ALSO

NAME

Pod::Find - find POD documents in directory trees

SYNOPSIS

  use Pod::Find qw(pod_find simplify_name);
  my %pods = pod_find({ -verbose => 1, -inc => 1 });
  foreach(keys %pods) {
     print "found library POD `$pods{$_}' in $_\n";
  }

  print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n";

  $location = pod_where( { -inc => 1 }, "Pod::Find" );

DESCRIPTION

Pod::Find provides a set of functions to locate POD files. Note that no function is exported by default to avoid pollution of your namespace, so be sure to specify them in the use statement if you need them:

  use Pod::Find qw(pod_find);

From this version on the typical SCM (software configuration management) files/directories like RCS, CVS, SCCS, .svn are ignored.

pod_find( { %opts } , @directories )

The function pod_find searches for POD documents in a given set of files and/or directories. It returns a hash with the file names as keys and the POD name as value. The POD name is derived from the file name and its position in the directory tree.

E.g. when searching in $HOME/perl5lib, the file $HOME/perl5lib/MyModule.pm would get the POD name MyModule, whereas $HOME/perl5lib/Myclass/Subclass.pm would be Myclass::Subclass. The name information can be used for POD translators.

Only text files containing at least one valid POD command are found.

A warning is printed if more than one POD file with the same POD name is found, e.g. CPAN.pm in different directories. This usually indicates duplicate occurrences of modules in the @INC search path.

OPTIONS The first argument for pod_find may be a hash reference with options. The rest are either directories that are searched recursively or files. The POD names of files are the plain basenames with any Perl-like extension (.pm, .pl, .pod) stripped.

-verbose => 1

Print progress information while scanning.

-perl => 1

Apply Perl-specific heuristics to find the correct PODs. This includes stripping Perl-like extensions, omitting subdirectories that are numeric but do not match the current Perl interpreter's version id, suppressing site_perl as a module hierarchy name etc.

-script => 1

Search for PODs in the current Perl interpreter's installation scriptdir. This is taken from the local Config module.

-inc => 1

Search for PODs in the current Perl interpreter's @INC paths. This automatically considers paths specified in the PERL5LIB environment as this is prepended to @INC by the Perl interpreter itself.

simplify_name( $str )

The function simplify_name is equivalent to basename, but also strips Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on Win32 and OS/2, or .com on VMS, respectively.

pod_where( { %opts }, $pod )

Returns the location of a pod document given a search directory and a module (e.g. File::Find) or script (e.g. perldoc) name.

Options:

-inc => 1

Search @INC for the pod and also the scriptdir defined in the Config module.

-dirs => [ $dir1, $dir2, ... ]

Reference to an array of search directories. These are searched in order before looking in @INC (if -inc). Current directory is used if none are specified.

-verbose => 1

List directories as they are searched

Returns the full path of the first occurrence to the file. Package names (eg 'A::B') are automatically converted to directory names in the selected directory. (eg on unix 'A::B' is converted to 'A/B'). Additionally, '.pm', '.pl' and '.pod' are appended to the search automatically if required.

A subdirectory pod/ is also checked if it exists in any of the given search directories. This ensures that e.g. perlfunc is found.

It is assumed that if a module name is supplied, that that name matches the file name. Pods are not opened to check for the 'NAME' entry.

A check is made to make sure that the file that is found does contain some pod documentation.

contains_pod( $file , $verbose )

Returns true if the supplied filename (not POD module) contains some pod information.

AUTHOR

Please report bugs using http://rt.cpan.org.

Marek Rouchal <marekr@cpan.org>, heavily borrowing code from Nick Ing-Simmons' PodToHtml.

Tim Jenness <t.jenness@jach.hawaii.edu> provided pod_where and contains_pod.

SEE ALSO

the Pod::Parser manpage, the Pod::Checker manpage, the perldoc manpage


Pod::Functions - Group Perl's functions a la perlfunc.pod

  • CHANGES

NAME

Pod::Functions - Group Perl's functions a la perlfunc.pod

SYNOPSIS

    use Pod::Functions;

    my @misc_ops = @{ $Kinds{ 'Misc' } };
    my $misc_dsc = $Type_Description{ 'Misc' };

or

    perl /path/to/lib/Pod/Functions.pm

This will print a grouped list of Perl's functions, like the Perl Functions by Category in the perlfunc manpage section.

DESCRIPTION

It exports the following variables:

%Kinds

This holds a hash-of-lists. Each list contains the functions in the category the key denotes.

%Type

In this hash each key represents a function and the value is the category. The category can be a comma separated list.

%Flavor

In this hash each key represents a function and the value is a short description of that function.

%Type_Description

In this hash each key represents a category of functions and the value is a short description of that category.

@Type_Order

This list of categories is used to produce the same order as the Perl Functions by Category in the perlfunc manpage section.

CHANGES

1.02 20020813 <abe@ztreet.demon.nl> de-typo in the SYNOPSIS section (thanks Mike Castle for noticing)

1.01 20011229 <abe@ztreet.demon.nl> fixed some bugs that slipped in after 5.6.1 added the pod finished making it strict safe

1.00 ?? first numbered version


Pod::Html - module to convert pod files to HTML

  • ARGUMENTS
  • EXAMPLE
  • ENVIRONMENT
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

Pod::Html - module to convert pod files to HTML

SYNOPSIS

    use Pod::Html;
    pod2html([options]);

DESCRIPTION

Converts files from pod format (see the perlpod manpage) to HTML format. It can automatically generate indexes and cross-references, and it keeps a cache of things it knows how to cross-reference.

ARGUMENTS

Pod::Html takes the following arguments:

backlink
    --backlink="Back to Top"

Adds "Back to Top" links in front of every head1 heading (except for the first). By default, no backlinks are generated.

cachedir
    --cachedir=name

Creates the item and directory caches in the given directory.

css
    --css=stylesheet

Specify the URL of a cascading style sheet. Also disables all HTML/CSS style attributes that are output by default (to avoid conflicts).

flush
    --flush

Flushes the item and directory caches.

header
    --header
    --noheader

Creates header and footer blocks containing the text of the NAME section. By default, no headers are generated.

help
    --help

Displays the usage message.

hiddendirs
    --hiddendirs
    --nohiddendirs

Include hidden directories in the search for POD's in podpath if recurse is set. The default is not to traverse any directory whose name begins with .. See podpath and recurse.

[This option is for backward compatibility only. It's hard to imagine that one would usefully create a module with a name component beginning with ..]

htmldir
    --htmldir=name

Sets the directory in which the resulting HTML file is placed. This is used to generate relative links to other files. Not passing this causes all links to be absolute, since this is the value that tells Pod::Html the root of the documentation tree.

htmlroot
    --htmlroot=name

Sets the base URL for the HTML files. When cross-references are made, the HTML root is prepended to the URL.

index
    --index
    --noindex

Generate an index at the top of the HTML file. This is the default behaviour.

infile
    --infile=name

Specify the pod file to convert. Input is taken from STDIN if no infile is specified.

libpods
    --libpods=name:...:name

List of page names (eg, "perlfunc") which contain linkable =items.

netscape
    --netscape
    --nonetscape

Deprecated, has no effect. For backwards compatibility only.

outfile
    --outfile=name

Specify the HTML file to create. Output goes to STDOUT if no outfile is specified.

podpath
    --podpath=name:...:name

Specify which subdirectories of the podroot contain pod files whose HTML converted forms can be linked to in cross references.

podroot
    --podroot=name

Specify the base directory for finding library pods.

quiet
    --quiet
    --noquiet

Don't display mostly harmless warning messages. These messages will be displayed by default. But this is not the same as verbose mode.

recurse
    --recurse
    --norecurse

Recurse into subdirectories specified in podpath (default behaviour).

title
    --title=title

Specify the title of the resulting HTML file.

verbose
    --verbose
    --noverbose

Display progress messages. By default, they won't be displayed.

EXAMPLE

    pod2html("pod2html",
             "--podpath=lib:ext:pod:vms",
             "--podroot=/usr/src/perl",
             "--htmlroot=/perl/nmanual",
             "--libpods=perlfunc:perlguts:perlvar:perlrun:perlop",
             "--recurse",
             "--infile=foo.pod",
             "--outfile=/perl/nmanual/foo.html");

ENVIRONMENT

Uses $Config{pod2html} to setup default options.

AUTHOR

Tom Christiansen, <tchrist@perl.com>.

SEE ALSO

the perlpod manpage

COPYRIGHT

This program is distributed under the Artistic License.


Pod::InputObjects - objects representing POD input paragraphs, commands, etc.

  • REQUIRES
  • EXPORTS
  • DESCRIPTION
  • Pod::InputSource
    • new()
    • name()
    • handle()
    • was_cutting()
  • Pod::Paragraph
    • Pod::Paragraph->new()
    • $pod_para->cmd_name()
    • $pod_para->text()
    • $pod_para->raw_text()
    • $pod_para->cmd_prefix()
    • $pod_para->cmd_separator()
    • $pod_para->parse_tree()
    • $pod_para->file_line()
  • Pod::InteriorSequence
    • Pod::InteriorSequence->new()
    • $pod_seq->cmd_name()
    • $pod_seq->prepend()
    • $pod_seq->append()
    • $pod_seq->nested()
    • $pod_seq->raw_text()
    • $pod_seq->left_delimiter()
    • $pod_seq->right_delimiter()
    • $pod_seq->parse_tree()
    • $pod_seq->file_line()
    • Pod::InteriorSequence::DESTROY()
  • Pod::ParseTree
    • Pod::ParseTree->new()
    • $ptree->top()
    • $ptree->children()
    • $ptree->prepend()
    • $ptree->append()
    • $ptree->raw_text()
    • Pod::ParseTree::DESTROY()
  • SEE ALSO
  • AUTHOR

NAME

Pod::InputObjects - objects representing POD input paragraphs, commands, etc.

SYNOPSIS

    use Pod::InputObjects;

REQUIRES

perl5.004, Carp

EXPORTS

Nothing.

DESCRIPTION

This module defines some basic input objects used by Pod::Parser when reading and parsing POD text from an input source. The following objects are defined:

package Pod::Paragraph

An object corresponding to a paragraph of POD input text. It may be a plain paragraph, a verbatim paragraph, or a command paragraph (see the perlpod manpage).

package Pod::InteriorSequence

An object corresponding to an interior sequence command from the POD input text (see the perlpod manpage).

package Pod::ParseTree

An object corresponding to a tree of parsed POD text. Each "node" in a parse-tree (or ptree) is either a text-string or a reference to a Pod::InteriorSequence object. The nodes appear in the parse-tree in the order in which they were parsed from left-to-right.

Each of these input objects are described in further detail in the sections which follow.

Pod::Paragraph

An object representing a paragraph of POD input text. It has the following methods/attributes:

Pod::Paragraph->new()

        my $pod_para1 = Pod::Paragraph->new(-text => $text);
        my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
                                            -text => $text);
        my $pod_para3 = new Pod::Paragraph(-text => $text);
        my $pod_para4 = new Pod::Paragraph(-name => $cmd,
                                           -text => $text);
        my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
                                            -text => $text,
                                            -file => $filename,
                                            -line => $line_number);

This is a class method that constructs a Pod::Paragraph object and returns a reference to the new paragraph object. It may be given one or two keyword arguments. The -text keyword indicates the corresponding text of the POD paragraph. The -name keyword indicates the name of the corresponding POD command, such as head1 or item (it should not contain the = prefix); this is needed only if the POD paragraph corresponds to a command paragraph. The -file and -line keywords indicate the filename and line number corresponding to the beginning of the paragraph

$pod_para->cmd_name()

        my $para_cmd = $pod_para->cmd_name();

If this paragraph is a command paragraph, then this method will return the name of the command (without any leading = prefix).

$pod_para->text()

        my $para_text = $pod_para->text();

This method will return the corresponding text of the paragraph.

$pod_para->raw_text()

        my $raw_pod_para = $pod_para->raw_text();

This method will return the raw text of the POD paragraph, exactly as it appeared in the input.

$pod_para->cmd_prefix()

        my $prefix = $pod_para->cmd_prefix();

If this paragraph is a command paragraph, then this method will return the prefix used to denote the command (which should be the string "=" or "==").

$pod_para->cmd_separator()

        my $separator = $pod_para->cmd_separator();

If this paragraph is a command paragraph, then this method will return the text used to separate the command name from the rest of the paragraph (if any).

$pod_para->parse_tree()

        my $ptree = $pod_parser->parse_text( $pod_para->text() );
        $pod_para->parse_tree( $ptree );
        $ptree = $pod_para->parse_tree();

This method will get/set the corresponding parse-tree of the paragraph's text.

$pod_para->file_line()

        my ($filename, $line_number) = $pod_para->file_line();
        my $position = $pod_para->file_line();

Returns the current filename and line number for the paragraph object. If called in a list context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number.

Pod::InteriorSequence

An object representing a POD interior sequence command. It has the following methods/attributes:

Pod::InteriorSequence->new()

        my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
                                                  -ldelim => $delimiter);
        my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
                                                 -ldelim => $delimiter);
        my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,
                                                 -ldelim => $delimiter,
                                                 -file => $filename,
                                                 -line => $line_number);

        my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);
        my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);

This is a class method that constructs a Pod::InteriorSequence object and returns a reference to the new interior sequence object. It should be given two keyword arguments. The -ldelim keyword indicates the corresponding left-delimiter of the interior sequence (e.g. '<'). The -name keyword indicates the name of the corresponding interior sequence command, such as I or B or C. The -file and -line keywords indicate the filename and line number corresponding to the beginning of the interior sequence. If the $ptree argument is given, it must be the last argument, and it must be either string, or else an array-ref suitable for passing to Pod::ParseTree::new (or it may be a reference to a Pod::ParseTree object).

$pod_seq->cmd_name()

        my $seq_cmd = $pod_seq->cmd_name();

The name of the interior sequence command.

$pod_seq->prepend()

        $pod_seq->prepend($text);
        $pod_seq1->prepend($pod_seq2);

Prepends the given string or parse-tree or sequence object to the parse-tree of this interior sequence.

$pod_seq->append()

        $pod_seq->append($text);
        $pod_seq1->append($pod_seq2);

Appends the given string or parse-tree or sequence object to the parse-tree of this interior sequence.

$pod_seq->nested()

        $outer_seq = $pod_seq->nested || print "not nested";

If this interior sequence is nested inside of another interior sequence, then the outer/parent sequence that contains it is returned. Otherwise undef is returned.

$pod_seq->raw_text()

        my $seq_raw_text = $pod_seq->raw_text();

This method will return the raw text of the POD interior sequence, exactly as it appeared in the input.

$pod_seq->left_delimiter()

        my $ldelim = $pod_seq->left_delimiter();

The leftmost delimiter beginning the argument text to the interior sequence (should be "<").

$pod_seq->right_delimiter()

The rightmost delimiter beginning the argument text to the interior sequence (should be ">").

$pod_seq->parse_tree()

        my $ptree = $pod_parser->parse_text($paragraph_text);
        $pod_seq->parse_tree( $ptree );
        $ptree = $pod_seq->parse_tree();

This method will get/set the corresponding parse-tree of the interior sequence's text.

$pod_seq->file_line()

        my ($filename, $line_number) = $pod_seq->file_line();
        my $position = $pod_seq->file_line();

Returns the current filename and line number for the interior sequence object. If called in a list context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number.

Pod::InteriorSequence::DESTROY()

This method performs any necessary cleanup for the interior-sequence. If you override this method then it is imperative that you invoke the parent method from within your own method, otherwise interior-sequence storage will not be reclaimed upon destruction!

Pod::ParseTree

This object corresponds to a tree of parsed POD text. As POD text is scanned from left to right, it is parsed into an ordered list of text-strings and Pod::InteriorSequence objects (in order of appearance). A Pod::ParseTree object corresponds to this list of strings and sequences. Each interior sequence in the parse-tree may itself contain a parse-tree (since interior sequences may be nested).

Pod::ParseTree->new()

        my $ptree1 = Pod::ParseTree->new;
        my $ptree2 = new Pod::ParseTree;
        my $ptree4 = Pod::ParseTree->new($array_ref);
        my $ptree3 = new Pod::ParseTree($array_ref);

This is a class method that constructs a Pod::Parse_tree object and returns a reference to the new parse-tree. If a single-argument is given, it must be a reference to an array, and is used to initialize the root (top) of the parse tree.

$ptree->top()

        my $top_node = $ptree->top();
        $ptree->top( $top_node );
        $ptree->top( @children );

This method gets/sets the top node of the parse-tree. If no arguments are given, it returns the topmost node in the tree (the root), which is also a Pod::ParseTree. If it is given a single argument that is a reference, then the reference is assumed to a parse-tree and becomes the new top node. Otherwise, if arguments are given, they are treated as the new list of children for the top node.

$ptree->children()

This method gets/sets the children of the top node in the parse-tree. If no arguments are given, it returns the list (array) of children (each of which should be either a string or a Pod::InteriorSequence. Otherwise, if arguments are given, they are treated as the new list of children for the top node.

$ptree->prepend()

This method prepends the given text or parse-tree to the current parse-tree. If the first item on the parse-tree is text and the argument is also text, then the text is prepended to the first item (not added as a separate string). Otherwise the argument is added as a new string or parse-tree before the current one.

$ptree->append()

This method appends the given text or parse-tree to the current parse-tree. If the last item on the parse-tree is text and the argument is also text, then the text is appended to the last item (not added as a separate string). Otherwise the argument is added as a new string or parse-tree after the current one.

$ptree->raw_text()

        my $ptree_raw_text = $ptree->raw_text();

This method will return the raw text of the POD parse-tree exactly as it appeared in the input.

Pod::ParseTree::DESTROY()

This method performs any necessary cleanup for the parse-tree. If you override this method then it is imperative that you invoke the parent method from within your own method, otherwise parse-tree storage will not be reclaimed upon destruction!

SEE ALSO

See the Pod::Parser manpage, the Pod::Select manpage

AUTHOR

Please report bugs using http://rt.cpan.org.

Brad Appleton <bradapp@enteract.com>


Pod::LaTeX - Convert Pod data to formatted Latex

  • OBJECT METHODS
    • Data Accessors
    • Subclassed methods
    • List Methods
    • Methods for headings
    • Internal methods
  • NOTES
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT
  • REVISION

NAME

Pod::LaTeX - Convert Pod data to formatted Latex

SYNOPSIS

  use Pod::LaTeX;
  my $parser = Pod::LaTeX->new ( );

  $parser->parse_from_filehandle;

  $parser->parse_from_file ('file.pod', 'file.tex');

DESCRIPTION

Pod::LaTeX is a module to convert documentation in the Pod format into Latex. The pod2latex command uses this module for translation.

Pod::LaTeX is a derived class from Pod::Select.

OBJECT METHODS

The following methods are provided in this module. Methods inherited from Pod::Select are not described in the public interface.

Data Accessors

The following methods are provided for accessing instance data. These methods should be used for accessing configuration parameters rather than assuming the object is a hash.

Default values can be supplied by using these names as keys to a hash of arguments when using the new() constructor.

AddPreamble

Logical to control whether a latex preamble is to be written. If true, a valid latex preamble is written before the pod data is written. This is similar to:

  \documentclass{article}
  \usepackage[T1]{fontenc}
  \usepackage{textcomp}
  \begin{document}

but will be more complicated if table of contents and indexing are required. Can be used to set or retrieve the current value.

  $add = $parser->AddPreamble();
  $parser->AddPreamble(1);

If used in conjunction with AddPostamble a full latex document will be written that could be immediately processed by latex.

For some pod escapes it may be necessary to include the amsmath package. This is not yet added to the preamble automaatically.

AddPostamble

Logical to control whether a standard latex ending is written to the output file after the document has been processed. In its simplest form this is simply:

  \end{document}

but can be more complicated if a index is required. Can be used to set or retrieve the current value.

  $add = $parser->AddPostamble();
  $parser->AddPostamble(1);

If used in conjunction with AddPreaamble a full latex document will be written that could be immediately processed by latex.

Head1Level

The latex sectioning level that should be used to correspond to a pod =head1 directive. This can be used, for example, to turn a =head1 into a latex subsection. This should hold a number corresponding to the required position in an array containing the following elements:

 [0] chapter
 [1] section
 [2] subsection
 [3] subsubsection
 [4] paragraph
 [5] subparagraph

Can be used to set or retrieve the current value:

  $parser->Head1Level(2);
  $sect = $parser->Head1Level;

Setting this number too high can result in sections that may not be reproducible in the expected way. For example, setting this to 4 would imply that =head3 do not have a corresponding latex section (=head1 would correspond to a paragraph).

A check is made to ensure that the supplied value is an integer in the range 0 to 5.

Default is for a value of 1 (i.e. a section).

Label

This is the label that is prefixed to all latex label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a latex label will be multiply defined if more than one pod document is to be included in a single latex file. To overcome this, this label is prefixed to a label whenever a label is required (joined with an underscore) or to an index entry (joined by an exclamation mark which is the normal index separator). For example, \label{text} becomes \label{Label_text}.

Can be used to set or retrieve the current value:

  $label = $parser->Label;
  $parser->Label($label);

This label is only used if UniqueLabels is true. Its value is set automatically from the NAME field if ReplaceNAMEwithSection is true. If this is not the case it must be set manually before starting the parse.

Default value is undef.

LevelNoNum

Control the point at which latex section numbering is turned off. For example, this can be used to make sure that latex sections are numbered but subsections are not.

Can be used to set or retrieve the current value:

  $lev = $parser->LevelNoNum;
  $parser->LevelNoNum(2);

The argument must be an integer between 0 and 5 and is the same as the number described in Head1Level method description. The number has nothing to do with the pod heading number, only the latex sectioning.

Default is 2. (i.e. latex subsections are written as subsection* but sections are numbered).

MakeIndex

Controls whether latex commands for creating an index are to be inserted into the preamble and postamble

  $makeindex = $parser->MakeIndex;
  $parser->MakeIndex(0);

Irrelevant if both AddPreamble and AddPostamble are false (or equivalently, UserPreamble and UserPostamble are set).

Default is for an index to be created.

ReplaceNAMEwithSection

This controls whether the NAME section in the pod is to be translated literally or converted to a slightly modified output where the section name is the pod name rather than "NAME".

If true, the pod segment

  =head1 NAME
  pod::name - purpose
  =head1 SYNOPSIS

is converted to the latex

  \section{pod::name\label{pod_name}\index{pod::name}}

  Purpose
  \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
               \index{pod::name!SYNOPSIS}}

(dependent on the value of Head1Level and LevelNoNum). Note that subsequent head1 directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of UniqueLabels).

The Label is set from the pod name regardless of any current value of Label.

  $mod = $parser->ReplaceNAMEwithSection;
  $parser->ReplaceNAMEwithSection(0);

Default is to translate the pod literally.

StartWithNewPage

If true, each pod translation will begin with a latex \clearpage.

  $parser->StartWithNewPage(1);
  $newpage = $parser->StartWithNewPage;

Default is false.

TableOfContents

If true, a table of contents will be created. Irrelevant if AddPreamble is false or UserPreamble is set.

  $toc = $parser->TableOfContents;
  $parser->TableOfContents(1);

Default is false.

UniqueLabels

If true, the translator will attempt to make sure that each latex label or index entry will be uniquely identified by prefixing the contents of Label. This allows multiple documents to be combined without clashing common labels such as DESCRIPTION and SYNOPSIS

  $parser->UniqueLabels(1);
  $unq = $parser->UniqueLabels;

Default is true.

UserPreamble

User supplied latex preamble. Added before the pod translation data.

If set, the contents will be prepended to the output file before the translated data regardless of the value of AddPreamble. MakeIndex and TableOfContents will also be ignored.

UserPostamble

User supplied latex postamble. Added after the pod translation data.

If set, the contents will be prepended to the output file after the translated data regardless of the value of AddPostamble. MakeIndex will also be ignored.

NOTES

Compatible with latex2e only. Can not be used with latex v2.09 or earlier.

A subclass of Pod::Select so that specific pod sections can be converted to latex by using the select method.

Some HTML escapes are missing and many have not been tested.

SEE ALSO

the Pod::Parser manpage, the Pod::Select manpage, pod2latex

AUTHORS

Tim Jenness <tjenness@cpan.org>

Bug fixes and improvements have been received from: Simon Cozens <simon@cozens.net>, Mark A. Hershberger <mah@everybody.org>, Marcel Grunauer <marcel@codewerk.com>, Hugh S Myers <hsmyers@sdragons.com>, Peter J Acklam <jacklam@math.uio.no>, Sudhi Herle <sudhi@herle.net>, Ariel Scolnicov <ariels@compugen.co.il>, Adriano Rodrigues Ferreira <ferreira@triang.com.br> and R. de Vries <r.de.vries@dutchspace.nl>.

COPYRIGHT

Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Pod::Man - Convert POD data to formatted *roff input

  • DIAGNOSTICS
  • BUGS
  • CAVEATS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::Man - Convert POD data to formatted *roff input

SYNOPSIS

    use Pod::Man;
    my $parser = Pod::Man->new (release => $VERSION, section => 8);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.1.
    $parser->parse_from_file ('file.pod', 'file.1');

DESCRIPTION

Pod::Man is a module to convert documentation in the POD format (the preferred language for documenting Perl) into *roff input using the man macro set. The resulting *roff code is suitable for display on a terminal using nroff(1), normally via man(1), or printing using troff(1). It is conventionally invoked using the driver script pod2man, but it can also be used directly.

As a derived class from Pod::Parser, Pod::Man supports the same methods and interfaces. See the Pod::Parser manpage for all the details; briefly, one creates a new parser with Pod::Man->new() and then calls either parse_from_filehandle() or parse_from_file().

new() can take options, in the form of key/value pairs that control the behavior of the parser. See below for details.

If no options are given, Pod::Man uses the name of the input file with any trailing .pod, .pm, or .pl stripped as the man page title, to section 1 unless the file ended in .pm in which case it defaults to section 3, to a centered title of "User Contributed Perl Documentation", to a centered footer of the Perl version it is run with, and to a left-hand footer of the modification date of its input (or the current date if given STDIN for input).

Pod::Man assumes that your *roff formatters have a fixed-width font named CW. If yours is called something else (like CR), use the fixed option to specify it. This generally only matters for troff output for printing. Similarly, you can set the fonts used for bold, italic, and bold italic fixed-width output.

Besides the obvious pod conversions, Pod::Man also takes care of formatting func(), func(3), and simple variable references like $foo or @bar so you don't have to use code escapes for them; complex expressions like $fred{'stuff'} will still need to be escaped, though. It also translates dashes that aren't used as hyphens into en dashes, makes long dashes--like this--into proper em dashes, fixes "paired quotes," makes C++ look right, puts a little space between double underbars, makes ALLCAPS a teeny bit smaller in troff, and escapes stuff that *roff treats as special so that you don't have to.

The recognized options to new() are as follows. All options take a single argument.

center

Sets the centered page header to use instead of "User Contributed Perl Documentation".

date

Sets the left-hand footer. By default, the modification date of the input file will be used, or the current date if stat() can't find that file (the case if the input is from STDIN), and the date will be formatted as YYYY-MM-DD.

fixed

The fixed-width font to use for vertabim text and code. Defaults to CW. Some systems may want CR instead. Only matters for troff output.

fixedbold

Bold version of the fixed-width font. Defaults to CB. Only matters for troff output.

fixeditalic

Italic version of the fixed-width font (actually, something of a misnomer, since most fixed-width fonts only have an oblique version, not an italic version). Defaults to CI. Only matters for troff output.

fixedbolditalic

Bold italic (probably actually oblique) version of the fixed-width font. Pod::Man doesn't assume you have this, and defaults to CB. Some systems (such as Solaris) have this font available as CX. Only matters for troff output.

name

Set the name of the manual page. Without this option, the manual name is set to the uppercased base name of the file being converted unless the manual section is 3, in which case the path is parsed to see if it is a Perl module path. If it is, a path like .../lib/Pod/Man.pm is converted into a name like Pod::Man. This option, if given, overrides any automatic determination of the name.

quotes

Sets the quote marks used to surround C<> text. If the value is a single character, it is used as both the left and right quote; if it is two characters, the first character is used as the left quote and the second as the right quoted; and if it is four characters, the first two are used as the left quote and the second two as the right quote.

This may also be set to the special value none, in which case no quote marks are added around C<> text (but the font is still changed for troff output).

release

Set the centered footer. By default, this is the version of Perl you run Pod::Man under. Note that some system an macro sets assume that the centered footer will be a modification date and will prepend something like "Last modified: "; if this is the case, you may want to set release to the last modified date and date to the version number.

section

Set the section for the .TH macro. The standard section numbering convention is to use 1 for user commands, 2 for system calls, 3 for functions, 4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous information, and 8 for administrator commands. There is a lot of variation here, however; some systems (like Solaris) use 4 for file formats, 5 for miscellaneous information, and 7 for devices. Still others use 1m instead of 8, or some mix of both. About the only section numbers that are reliably consistent are 1, 2, and 3.

By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected.

The standard Pod::Parser method parse_from_filehandle() takes up to two arguments, the first being the file handle to read POD from and the second being the file handle to write the formatted output to. The first defaults to STDIN if not given, and the second defaults to STDOUT. The method parse_from_file() is almost identical, except that its two arguments are the input and output disk files instead. See the Pod::Parser manpage for the specific details.

DIAGNOSTICS

roff font should be 1 or 2 chars, not "%s"

(F) You specified a *roff font (using fixed, fixedbold, etc.) that wasn't either one or two characters. Pod::Man doesn't support *roff fonts longer than two characters, although some *roff extensions do (the canonical versions of nroff and troff don't either).

Invalid link %s

(W) The POD source contained a L<> formatting code that Pod::Man was unable to parse. You should never see this error message; it probably indicates a bug in Pod::Man.

Invalid quote specification "%s"

(F) The quote specification given (the quotes option to the constructor) was invalid. A quote specification must be one, two, or four characters long.

%s:%d: Unknown command paragraph "%s".

(W) The POD source contained a non-standard command paragraph (something of the form =command args) that Pod::Man didn't know about. It was ignored.

%s:%d: Unknown escape E<%s>

(W) The POD source contained an E<> escape that Pod::Man didn't know about. E<%s> was printed verbatim in the output.

%s:%d: Unknown formatting code %s

(W) The POD source contained a non-standard formatting code (something of the form X<>) that Pod::Man didn't know about. It was ignored.

%s:%d: Unmatched =back

(W) Pod::Man encountered a =back command that didn't correspond to an =over command.

BUGS

Eight-bit input data isn't handled at all well at present. The correct approach would be to map E<> escapes to the appropriate UTF-8 characters and then do a translation pass on the output according to the user-specified output character set. Unfortunately, we can't send eight-bit data directly to the output unless the user says this is okay, since some vendor *roff implementations can't handle eight-bit data. If the *roff implementation can, however, that's far superior to the current hacked characters that only work under troff.

There is currently no way to turn off the guesswork that tries to format unmarked text appropriately, and sometimes it isn't wanted (particularly when using POD to document something other than Perl).

The NAME section should be recognized specially and index entries emitted for everything in that section. This would have to be deferred until the next section, since extraneous things in NAME tends to confuse various man page processors.

Pod::Man doesn't handle font names longer than two characters. Neither do most troff implementations, but GNU troff does as an extension. It would be nice to support as an option for those who want to use it.

The preamble added to each output file is rather verbose, and most of it is only necessary in the presence of E<> escapes for non-ASCII characters. It would ideally be nice if all of those definitions were only output if needed, perhaps on the fly as the characters are used.

Pod::Man is excessively slow.

CAVEATS

The handling of hyphens and em dashes is somewhat fragile, and one may get the wrong one under some circumstances. This should only matter for troff output.

When and whether to use small caps is somewhat tricky, and Pod::Man doesn't necessarily get it right.

SEE ALSO

the Pod::Parser manpage, perlpod(1), pod2man(1), nroff(1), troff(1), man(1), man(7)

Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual," Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is the best documentation of standard nroff and troff. At the time of this writing, it's available at http://www.cs.bell-labs.com/cm/cs/cstr.html.

The man page documenting the man macro set may be man(5) instead of man(7) on your system. Also, please see pod2man(1) for extensive documentation on writing manual pages if you've not done it before and aren't familiar with the conventions.

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0.

AUTHOR

Russ Allbery <rra@stanford.edu>, based very heavily on the original pod2man by Tom Christiansen <tchrist@mox.perl.com>.

COPYRIGHT AND LICENSE

Copyright 1999, 2000, 2001, 2002, 2003 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text

  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::ParseLink - Parse an L<> formatting code in POD text

SYNOPSIS

    use Pod::ParseLink;
    my ($text, $inferred, $name, $section, $type) = parselink ($link);

DESCRIPTION

This module only provides a single function, parselink(), which takes the text of an L<> formatting code and parses it. It returns the anchor text for the link (if any was given), the anchor text possibly inferred from the name and section, the name or URL, the section if any, and the type of link. The type will be one of 'url', 'pod', or 'man', indicating a URL, a link to a POD page, or a link to a Unix manual page.

Parsing is implemented per the perlpodspec manpage. For backward compatibility, links where there is no section and name contains spaces, or links where the entirety of the link (except for the anchor text if given) is enclosed in double-quotes are interpreted as links to a section (L</section>).

The inferred anchor text is implemented per the perlpodspec manpage:

    L<name>         =>  L<name|name>
    L</section>     =>  L<"section"|/section>
    L<name/section> =>  L<"section" in name|name/section>

The name may contain embedded E<> and Z<> formatting codes, and the section, anchor text, and inferred anchor text may contain any formatting codes. Any double quotes around the section are removed as part of the parsing, as is any leading or trailing whitespace.

If the text of the L<> escape is entirely enclosed in double quotes, it's interpreted as a link to a section for backwards compatibility.

No attempt is made to resolve formatting codes. This must be done after calling parselink (since E<> formatting codes can be used to escape characters that would otherwise be significant to the parser and resolving them before parsing would result in an incorrect parse of a formatting code like:

    L<verticalE<verbar>barE<sol>slash>

which should be interpreted as a link to the vertical|bar/slash POD page and not as a link to the slash section of the bar POD page with an anchor text of vertical. Note that not only the anchor text will need to have formatting codes expanded, but so will the target of the link (to deal with E<> and Z<> formatting codes), and special handling of the section may be necessary depending on whether the translator wants to consider markup in sections to be significant when resolving links. See the perlpodspec manpage for more information.

SEE ALSO

the Pod::Parser manpage

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/.

AUTHOR

Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 2001 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Pod::ParseUtils - helpers for POD parsing and conversion

    • Pod::List
    • Pod::Hyperlink
    • Pod::Cache
    • Pod::Cache::Item
  • AUTHOR
  • SEE ALSO

NAME

Pod::ParseUtils - helpers for POD parsing and conversion

SYNOPSIS

  use Pod::ParseUtils;

  my $list = new Pod::List;
  my $link = Pod::Hyperlink->new('Pod::Parser');

DESCRIPTION

Pod::ParseUtils contains a few object-oriented helper packages for POD parsing and processing (i.e. in POD formatters and translators).

Pod::List

Pod::List can be used to hold information about POD lists (written as =over ... =item ... =back) for further processing. The following methods are available:

Pod::List->new()

Create a new list object. Properties may be specified through a hash reference like this:

  my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.

$list->file()

Without argument, retrieves the file name the list is in. This must have been set before by either specifying -file in the new() method or by calling the file() method with a scalar argument.

$list->start()

Without argument, retrieves the line number where the list started. This must have been set before by either specifying -start in the new() method or by calling the start() method with a scalar argument.

$list->indent()

Without argument, retrieves the indent level of the list as specified in =over n. This must have been set before by either specifying -indent in the new() method or by calling the indent() method with a scalar argument.

$list->type()

Without argument, retrieves the list type, which can be an arbitrary value, e.g. OL, UL, ... when thinking the HTML way. This must have been set before by either specifying -type in the new() method or by calling the type() method with a scalar argument.

$list->rx()

Without argument, retrieves a regular expression for simplifying the individual item strings once the list type has been determined. Usage: E.g. when converting to HTML, one might strip the leading number in an ordered list as <OL> already prints numbers itself. This must have been set before by either specifying -rx in the new() method or by calling the rx() method with a scalar argument.

$list->item()

Without argument, retrieves the array of the items in this list. The items may be represented by any scalar. If an argument has been given, it is pushed on the list of items.

$list->parent()

Without argument, retrieves information about the parent holding this list, which is represented as an arbitrary scalar. This must have been set before by either specifying -parent in the new() method or by calling the parent() method with a scalar argument.

$list->tag()

Without argument, retrieves information about the list tag, which can be any scalar. This must have been set before by either specifying -tag in the new() method or by calling the tag() method with a scalar argument.

Pod::Hyperlink

Pod::Hyperlink is a class for manipulation of POD hyperlinks. Usage:

  my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');

The Pod::Hyperlink class is mainly designed to parse the contents of the L<...> sequence, providing a simple interface for accessing the different parts of a POD hyperlink for further processing. It can also be used to construct hyperlinks.

Pod::Hyperlink->new()

The new() method can either be passed a set of key/value pairs or a single scalar value, namely the contents of a L<...> sequence. An object of the class Pod::Hyperlink is returned. The value undef indicates a failure, the error message is stored in $@.

$link->parse($string)

This method can be used to (re)parse a (new) hyperlink, i.e. the contents of a L<...> sequence. The result is stored in the current object. Warnings are stored in the warnings property. E.g. sections like L<open(2)> are deprecated, as they do not point to Perl documents. L<DBI::foo(3p)> is wrong as well, the manpage section can simply be dropped.

$link->markup($string)

Set/retrieve the textual value of the link. This string contains special markers P<> and Q<> that should be expanded by the translator's interior sequence expansion engine to the formatter-specific code to highlight/activate the hyperlink. The details have to be implemented in the translator.

$link->text()

This method returns the textual representation of the hyperlink as above, but without markers (read only). Depending on the link type this is one of the following alternatives (the + and * denote the portions of the text that are marked up):

  +perl+                    L<perl>
  *$|* in +perlvar+         L<perlvar/$|>
  *OPTIONS* in +perldoc+    L<perldoc/"OPTIONS">
  *DESCRIPTION*             L<"DESCRIPTION">
$link->warning()

After parsing, this method returns any warnings encountered during the parsing process.

$link->file()
$link->line()

Just simple slots for storing information about the line and the file the link was encountered in. Has to be filled in manually.

$link->page()

This method sets or returns the POD page this link points to.

$link->node()

As above, but the destination node text of the link.

$link->alttext()

Sets or returns an alternative text specified in the link.

$link->type()

The node type, either section or item. As an unofficial type, there is also hyperlink, derived from e.g. L<http://perl.com>

$link->link()

Returns the link as contents of L<>. Reciprocal to parse().

Pod::Cache

Pod::Cache holds information about a set of POD documents, especially the nodes for hyperlinks. The following methods are available:

Pod::Cache->new()

Create a new cache object. This object can hold an arbitrary number of POD documents of class Pod::Cache::Item.

$cache->item()

Add a new item to the cache. Without arguments, this method returns a list of all cache elements.

$cache->find_page($name)

Look for a POD document named $name in the cache. Returns the reference to the corresponding Pod::Cache::Item object or undef if not found.

Pod::Cache::Item

Pod::Cache::Item holds information about individual POD documents, that can be grouped in a Pod::Cache object. It is intended to hold information about the hyperlink nodes of POD documents. The following methods are available:

Pod::Cache::Item->new()

Create a new object.

$cacheitem->page()

Set/retrieve the POD document name (e.g. "Pod::Parser").

$cacheitem->description()

Set/retrieve the POD short description as found in the =head1 NAME section.

$cacheitem->path()

Set/retrieve the POD file storage path.

$cacheitem->file()

Set/retrieve the POD file name.

$cacheitem->nodes()

Add a node (or a list of nodes) to the document's node list. Note that the order is kept, i.e. start with the first node and end with the last. If no argument is given, the current list of nodes is returned in the same order the nodes have been added. A node can be any scalar, but usually is a pair of node string and unique id for the find_node method to work correctly.

$cacheitem->find_node($name)

Look for a node or index entry named $name in the object. Returns the unique id of the node (i.e. the second element of the array stored in the node arry) or undef if not found.

$cacheitem->idx()

Add an index entry (or a list of them) to the document's index list. Note that the order is kept, i.e. start with the first node and end with the last. If no argument is given, the current list of index entries is returned in the same order the entries have been added. An index entry can be any scalar, but usually is a pair of string and unique id.

AUTHOR

Please report bugs using http://rt.cpan.org.

Marek Rouchal <marekr@cpan.org>, borrowing a lot of things from pod2man and pod2roff as well as other POD processing tools by Tom Christiansen, Brad Appleton and Russ Allbery.

SEE ALSO

pod2man, pod2roff, the Pod::Parser manpage, the Pod::Checker manpage, pod2html


Pod::Parser - base class for creating POD filters and translators

  • REQUIRES
  • EXPORTS
  • DESCRIPTION
  • QUICK OVERVIEW
  • PARSING OPTIONS
  • RECOMMENDED SUBROUTINE/METHOD OVERRIDES
  • command()
  • verbatim()
  • textblock()
  • interior_sequence()
  • OPTIONAL SUBROUTINE/METHOD OVERRIDES
  • new()
  • initialize()
  • begin_pod()
  • begin_input()
  • end_input()
  • end_pod()
  • preprocess_line()
  • preprocess_paragraph()
  • METHODS FOR PARSING AND PROCESSING
  • parse_text()
  • interpolate()
  • parse_paragraph()
  • parse_from_filehandle()
  • parse_from_file()
  • ACCESSOR METHODS
  • errorsub()
  • cutting()
  • parseopts()
  • output_file()
  • output_handle()
  • input_file()
  • input_handle()
  • input_streams()
  • top_stream()
  • PRIVATE METHODS AND DATA
  • _push_input_stream()
  • _pop_input_stream()
  • TREE-BASED PARSING
  • SEE ALSO
  • AUTHOR

NAME

Pod::Parser - base class for creating POD filters and translators

SYNOPSIS

    use Pod::Parser;

    package MyParser;
    @ISA = qw(Pod::Parser);

    sub command {
        my ($parser, $command, $paragraph, $line_num) = @_;
        ## Interpret the command and its text; sample actions might be:
        if ($command eq 'head1') { ... }
        elsif ($command eq 'head2') { ... }
        ## ... other commands and their actions
        my $out_fh = $parser->output_handle();
        my $expansion = $parser->interpolate($paragraph, $line_num);
        print $out_fh $expansion;
    }

    sub verbatim {
        my ($parser, $paragraph, $line_num) = @_;
        ## Format verbatim paragraph; sample actions might be:
        my $out_fh = $parser->output_handle();
        print $out_fh $paragraph;
    }

    sub textblock {
        my ($parser, $paragraph, $line_num) = @_;
        ## Translate/Format this block of text; sample actions might be:
        my $out_fh = $parser->output_handle();
        my $expansion = $parser->interpolate($paragraph, $line_num);
        print $out_fh $expansion;
    }

    sub interior_sequence {
        my ($parser, $seq_command, $seq_argument) = @_;
        ## Expand an interior sequence; sample actions might be:
        return "*$seq_argument*"     if ($seq_command eq 'B');
        return "`$seq_argument'"     if ($seq_command eq 'C');
        return "_${seq_argument}_'"  if ($seq_command eq 'I');
        ## ... other sequence commands and their resulting text
    }

    package main;

    ## Create a parser object and have it parse file whose name was
    ## given on the command-line (use STDIN if no files were given).
    $parser = new MyParser();
    $parser->parse_from_filehandle(\*STDIN)  if (@ARGV == 0);
    for (@ARGV) { $parser->parse_from_file($_); }

REQUIRES

perl5.005, Pod::InputObjects, Exporter, Symbol, Carp

EXPORTS

Nothing.

DESCRIPTION

Pod::Parser is a base class for creating POD filters and translators. It handles most of the effort involved with parsing the POD sections from an input stream, leaving subclasses free to be concerned only with performing the actual translation of text.

Pod::Parser parses PODs, and makes method calls to handle the various components of the POD. Subclasses of Pod::Parser override these methods to translate the POD into whatever output format they desire.

QUICK OVERVIEW

To create a POD filter for translating POD documentation into some other format, you create a subclass of Pod::Parser which typically overrides just the base class implementation for the following methods:

  • command()

  • verbatim()

  • textblock()

  • interior_sequence()

You may also want to override the begin_input() and end_input() methods for your subclass (to perform any needed per-file and/or per-document initialization or cleanup).

If you need to perform any preprocesssing of input before it is parsed you may want to override one or more of preprocess_line() and/or preprocess_paragraph().

Sometimes it may be necessary to make more than one pass over the input files. If this is the case you have several options. You can make the first pass using Pod::Parser and override your methods to store the intermediate results in memory somewhere for the end_pod() method to process. You could use Pod::Parser for several passes with an appropriate state variable to control the operation for each pass. If your input source can't be reset to start at the beginning, you can store it in some other structure as a string or an array and have that structure implement a getline() method (which is all that parse_from_filehandle() uses to read input).

Feel free to add any member data fields you need to keep track of things like current font, indentation, horizontal or vertical position, or whatever else you like. Be sure to read PRIVATE METHODS AND DATA to avoid name collisions.

For the most part, the Pod::Parser base class should be able to do most of the input parsing for you and leave you free to worry about how to intepret the commands and translate the result.

Note that all we have described here in this quick overview is the simplest most straightforward use of Pod::Parser to do stream-based parsing. It is also possible to use the Pod::Parser::parse_text function to do more sophisticated tree-based parsing. See TREE-BASED PARSING.

PARSING OPTIONS

A parse-option is simply a named option of Pod::Parser with a value that corresponds to a certain specified behavior. These various behaviors of Pod::Parser may be enabled/disabled by setting or unsetting one or more parse-options using the parseopts() method. The set of currently accepted parse-options is as follows:

-want_nonPODs (default: unset)

Normally (by default) Pod::Parser will only provide access to the POD sections of the input. Input paragraphs that are not part of the POD-format documentation are not made available to the caller (not even using preprocess_paragraph()). Setting this option to a non-empty, non-zero value will allow preprocess_paragraph() to see non-POD sections of the input as well as POD sections. The cutting() method can be used to determine if the corresponding paragraph is a POD paragraph, or some other input paragraph.

-process_cut_cmd (default: unset)

Normally (by default) Pod::Parser handles the =cut POD directive by itself and does not pass it on to the caller for processing. Setting this option to a non-empty, non-zero value will cause Pod::Parser to pass the =cut directive to the caller just like any other POD command (and hence it may be processed by the command() method).

Pod::Parser will still interpret the =cut directive to mean that "cutting mode" has been (re)entered, but the caller will get a chance to capture the actual =cut paragraph itself for whatever purpose it desires.

-warnings (default: unset)

Normally (by default) Pod::Parser recognizes a bare minimum of pod syntax errors and warnings and issues diagnostic messages for errors, but not for warnings. (Use Pod::Checker to do more thorough checking of POD syntax.) Setting this option to a non-empty, non-zero value will cause Pod::Parser to issue diagnostics for the few warnings it recognizes as well as the errors.

Please see parseopts() for a complete description of the interface for the setting and unsetting of parse-options.

RECOMMENDED SUBROUTINE/METHOD OVERRIDES

Pod::Parser provides several methods which most subclasses will probably want to override. These methods are as follows:

command()

            $parser->command($cmd,$text,$line_num,$pod_para);

This method should be overridden by subclasses to take the appropriate action when a POD command paragraph (denoted by a line beginning with "=") is encountered. When such a POD directive is seen in the input, this method is called and is passed:

$cmd

the name of the command for this POD paragraph

$text

the paragraph text for the given POD paragraph command.

$line_num

the line-number of the beginning of the paragraph

$pod_para

a reference to a Pod::Paragraph object which contains further information about the paragraph command (see the Pod::InputObjects manpage for details).

Note that this method is called for =pod paragraphs.

The base class implementation of this method simply treats the raw POD command as normal block of paragraph text (invoking the textblock() method with the command paragraph).

verbatim()

            $parser->verbatim($text,$line_num,$pod_para);

This method may be overridden by subclasses to take the appropriate action when a block of verbatim text is encountered. It is passed the following parameters:

$text

the block of text for the verbatim paragraph

$line_num

the line-number of the beginning of the paragraph

$pod_para

a reference to a Pod::Paragraph object which contains further information about the paragraph (see the Pod::InputObjects manpage for details).

The base class implementation of this method simply prints the textblock (unmodified) to the output filehandle.

textblock()

            $parser->textblock($text,$line_num,$pod_para);

This method may be overridden by subclasses to take the appropriate action when a normal block of POD text is encountered (although the base class method will usually do what you want). It is passed the following parameters:

$text

the block of text for the a POD paragraph

$line_num

the line-number of the beginning of the paragraph

$pod_para

a reference to a Pod::Paragraph object which contains further information about the paragraph (see the Pod::InputObjects manpage for details).

In order to process interior sequences, subclasses implementations of this method will probably want to invoke either interpolate() or parse_text(), passing it the text block $text, and the corresponding line number in $line_num, and then perform any desired processing upon the returned result.

The base class implementation of this method simply prints the text block as it occurred in the input stream).

interior_sequence()

            $parser->interior_sequence($seq_cmd,$seq_arg,$pod_seq);

This method should be overridden by subclasses to take the appropriate action when an interior sequence is encountered. An interior sequence is an embedded command within a block of text which appears as a command name (usually a single uppercase character) followed immediately by a string of text which is enclosed in angle brackets. This method is passed the sequence command $seq_cmd and the corresponding text $seq_arg. It is invoked by the interpolate() method for each interior sequence that occurs in the string that it is passed. It should return the desired text string to be used in place of the interior sequence. The $pod_seq argument is a reference to a Pod::InteriorSequence object which contains further information about the interior sequence. Please see the Pod::InputObjects manpage for details if you need to access this additional information.

Subclass implementations of this method may wish to invoke the nested() method of $pod_seq to see if it is nested inside some other interior-sequence (and if so, which kind).

The base class implementation of the interior_sequence() method simply returns the raw text of the interior sequence (as it occurred in the input) to the caller.

OPTIONAL SUBROUTINE/METHOD OVERRIDES

Pod::Parser provides several methods which subclasses may want to override to perform any special pre/post-processing. These methods do not have to be overridden, but it may be useful for subclasses to take advantage of them.

new()

            my $parser = Pod::Parser->new();

This is the constructor for Pod::Parser and its subclasses. You do not need to override this method! It is capable of constructing subclass objects as well as base class objects, provided you use any of the following constructor invocation styles:

    my $parser1 = MyParser->new();
    my $parser2 = new MyParser();
    my $parser3 = $parser2->new();

where MyParser is some subclass of Pod::Parser.

Using the syntax MyParser::new() to invoke the constructor is not recommended, but if you insist on being able to do this, then the subclass will need to override the new() constructor method. If you do override the constructor, you must be sure to invoke the initialize() method of the newly blessed object.

Using any of the above invocations, the first argument to the constructor is always the corresponding package name (or object reference). No other arguments are required, but if desired, an associative array (or hash-table) my be passed to the new() constructor, as in:

    my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );
    my $parser2 = new MyParser( -myflag => 1 );

All arguments passed to the new() constructor will be treated as key/value pairs in a hash-table. The newly constructed object will be initialized by copying the contents of the given hash-table (which may have been empty). The new() constructor for this class and all of its subclasses returns a blessed reference to the initialized object (hash-table).

initialize()

            $parser->initialize();

This method performs any necessary object initialization. It takes no arguments (other than the object instance of course, which is typically copied to a local variable named $self). If subclasses override this method then they must be sure to invoke $self->SUPER::initialize().

begin_pod()

            $parser->begin_pod();

This method is invoked at the beginning of processing for each POD document that is encountered in the input. Subclasses should override this method to perform any per-document initialization.

begin_input()

            $parser->begin_input();

This method is invoked by parse_from_filehandle() immediately before processing input from a filehandle. The base class implementation does nothing, however, subclasses may override it to perform any per-file initializations.

Note that if multiple files are parsed for a single POD document (perhaps the result of some future =include directive) this method is invoked for every file that is parsed. If you wish to perform certain initializations once per document, then you should use begin_pod().

end_input()

            $parser->end_input();

This method is invoked by parse_from_filehandle() immediately after processing input from a filehandle. The base class implementation does nothing, however, subclasses may override it to perform any per-file cleanup actions.

Please note that if multiple files are parsed for a single POD document (perhaps the result of some kind of =include directive) this method is invoked for every file that is parsed. If you wish to perform certain cleanup actions once per document, then you should use end_pod().

end_pod()

            $parser->end_pod();

This method is invoked at the end of processing for each POD document that is encountered in the input. Subclasses should override this method to perform any per-document finalization.

preprocess_line()

          $textline = $parser->preprocess_line($text, $line_num);

This method should be overridden by subclasses that wish to perform any kind of preprocessing for each line of input (before it has been determined whether or not it is part of a POD paragraph). The parameter $text is the input line; and the parameter $line_num is the line number of the corresponding text line.

The value returned should correspond to the new text to use in its place. If the empty string or an undefined value is returned then no further processing will be performed for this line.

Please note that the preprocess_line() method is invoked before the preprocess_paragraph() method. After all (possibly preprocessed) lines in a paragraph have been assembled together and it has been determined that the paragraph is part of the POD documentation from one of the selected sections, then preprocess_paragraph() is invoked.

The base class implementation of this method returns the given text.

preprocess_paragraph()

            $textblock = $parser->preprocess_paragraph($text, $line_num);

This method should be overridden by subclasses that wish to perform any kind of preprocessing for each block (paragraph) of POD documentation that appears in the input stream. The parameter $text is the POD paragraph from the input file; and the parameter $line_num is the line number for the beginning of the corresponding paragraph.

The value returned should correspond to the new text to use in its place If the empty string is returned or an undefined value is returned, then the given $text is ignored (not processed).

This method is invoked after gathering up all the lines in a paragraph and after determining the cutting state of the paragraph, but before trying to further parse or interpret them. After preprocess_paragraph() returns, the current cutting state (which is returned by $self->cutting()) is examined. If it evaluates to true then input text (including the given $text) is cut (not processed) until the next POD directive is encountered.

Please note that the preprocess_line() method is invoked before the preprocess_paragraph() method. After all (possibly preprocessed) lines in a paragraph have been assembled together and either it has been determined that the paragraph is part of the POD documentation from one of the selected sections or the -want_nonPODs option is true, then preprocess_paragraph() is invoked.

The base class implementation of this method returns the given text.

METHODS FOR PARSING AND PROCESSING

Pod::Parser provides several methods to process input text. These methods typically won't need to be overridden (and in some cases they can't be overridden), but subclasses may want to invoke them to exploit their functionality.

parse_text()

            $ptree1 = $parser->parse_text($text, $line_num);
            $ptree2 = $parser->parse_text({%opts}, $text, $line_num);
            $ptree3 = $parser->parse_text(\%opts, $text, $line_num);

This method is useful if you need to perform your own interpolation of interior sequences and can't rely upon interpolate to expand them in simple bottom-up order.

The parameter $text is a string or block of text to be parsed for interior sequences; and the parameter $line_num is the line number curresponding to the beginning of $text.

parse_text() will parse the given text into a parse-tree of "nodes." and interior-sequences. Each "node" in the parse tree is either a text-string, or a Pod::InteriorSequence. The result returned is a parse-tree of type Pod::ParseTree. Please see the Pod::InputObjects manpage for more information about Pod::InteriorSequence and Pod::ParseTree.

If desired, an optional hash-ref may be specified as the first argument to customize certain aspects of the parse-tree that is created and returned. The set of recognized option keywords are:

-expand_seq => code-ref|method-name

Normally, the parse-tree returned by parse_text() will contain an unexpanded Pod::InteriorSequence object for each interior-sequence encountered. Specifying -expand_seq tells parse_text() to "expand" every interior-sequence it sees by invoking the referenced function (or named method of the parser object) and using the return value as the expanded result.

If a subroutine reference was given, it is invoked as:

  &$code_ref( $parser, $sequence )

and if a method-name was given, it is invoked as:

  $parser->method_name( $sequence )

where $parser is a reference to the parser object, and $sequence is a reference to the interior-sequence object. [NOTE: If the interior_sequence() method is specified, then it is invoked according to the interface specified in interior_sequence()].

-expand_text => code-ref|method-name

Normally, the parse-tree returned by parse_text() will contain a text-string for each contiguous sequence of characters outside of an interior-sequence. Specifying -expand_text tells parse_text() to "preprocess" every such text-string it sees by invoking the referenced function (or named method of the parser object) and using the return value as the preprocessed (or "expanded") result. [Note that if the result is an interior-sequence, then it will not be expanded as specified by the -expand_seq option; Any such recursive expansion needs to be handled by the specified callback routine.]

If a subroutine reference was given, it is invoked as:

  &$code_ref( $parser, $text, $ptree_node )

and if a method-name was given, it is invoked as:

  $parser->method_name( $text, $ptree_node )

where $parser is a reference to the parser object, $text is the text-string encountered, and $ptree_node is a reference to the current node in the parse-tree (usually an interior-sequence object or else the top-level node of the parse-tree).

-expand_ptree => code-ref|method-name

Rather than returning a Pod::ParseTree, pass the parse-tree as an argument to the referenced subroutine (or named method of the parser object) and return the result instead of the parse-tree object.

If a subroutine reference was given, it is invoked as:

  &$code_ref( $parser, $ptree )

and if a method-name was given, it is invoked as:

  $parser->method_name( $ptree )

where $parser is a reference to the parser object, and $ptree is a reference to the parse-tree object.

interpolate()

            $textblock = $parser->interpolate($text, $line_num);

This method translates all text (including any embedded interior sequences) in the given text string $text and returns the interpolated result. The parameter $line_num is the line number corresponding to the beginning of $text.

interpolate() merely invokes a private method to recursively expand nested interior sequences in bottom-up order (innermost sequences are expanded first). If there is a need to expand nested sequences in some alternate order, use parse_text instead.

parse_from_filehandle()

            $parser->parse_from_filehandle($in_fh,$out_fh);

This method takes an input filehandle (which is assumed to already be opened for reading) and reads the entire input stream looking for blocks (paragraphs) of POD documentation to be processed. If no first argument is given the default input filehandle STDIN is used.

The $in_fh parameter may be any object that provides a getline() method to retrieve a single line of input text (hence, an appropriate wrapper object could be used to parse PODs from a single string or an array of strings).

Using $in_fh->getline(), input is read line-by-line and assembled into paragraphs or "blocks" (which are separated by lines containing nothing but whitespace). For each block of POD documentation encountered it will invoke a method to parse the given paragraph.

If a second argument is given then it should correspond to a filehandle where output should be sent (otherwise the default output filehandle is STDOUT if no output filehandle is currently in use).

NOTE: For performance reasons, this method caches the input stream at the top of the stack in a local variable. Any attempts by clients to change the stack contents during processing when in the midst executing of this method will not affect the input stream used by the current invocation of this method.

This method does not usually need to be overridden by subclasses.

parse_from_file()

            $parser->parse_from_file($filename,$outfile);

This method takes a filename and does the following:

  • opens the input and output files for reading (creating the appropriate filehandles)

  • invokes the parse_from_filehandle() method passing it the corresponding input and output filehandles.

  • closes the input and output files.

If the special input filename "-" or "<&STDIN" is given then the STDIN filehandle is used for input (and no open or close is performed). If no input filename is specified then "-" is implied.

If a second argument is given then it should be the name of the desired output file. If the special output filename "-" or ">&STDOUT" is given then the STDOUT filehandle is used for output (and no open or close is performed). If the special output filename ">&STDERR" is given then the STDERR filehandle is used for output (and no open or close is performed). If no output filehandle is currently in use and no output filename is specified, then "-" is implied. Alternatively, an the IO::String manpage object is also accepted as an output file handle.

This method does not usually need to be overridden by subclasses.

ACCESSOR METHODS

Clients of Pod::Parser should use the following methods to access instance data fields:

errorsub()

            $parser->errorsub("method_name");
            $parser->errorsub(\&warn_user);
            $parser->errorsub(sub { print STDERR, @_ });

Specifies the method or subroutine to use when printing error messages about POD syntax. The supplied method/subroutine must return TRUE upon successful printing of the message. If undef is given, then the warn builtin is used to issue error messages (this is the default behavior).

            my $errorsub = $parser->errorsub()
            my $errmsg = "This is an error message!\n"
            (ref $errorsub) and &{$errorsub}($errmsg)
                or (defined $errorsub) and $parser->$errorsub($errmsg)
                    or  warn($errmsg);

Returns a method name, or else a reference to the user-supplied subroutine used to print error messages. Returns undef if the warn builtin is used to issue error messages (this is the default behavior).

cutting()

            $boolean = $parser->cutting();

Returns the current cutting state: a boolean-valued scalar which evaluates to true if text from the input file is currently being "cut" (meaning it is not considered part of the POD document).

            $parser->cutting($boolean);

Sets the current cutting state to the given value and returns the result.

parseopts()

When invoked with no additional arguments, parseopts returns a hashtable of all the current parsing options.

            ## See if we are parsing non-POD sections as well as POD ones
            my %opts = $parser->parseopts();
            $opts{'-want_nonPODs}' and print "-want_nonPODs\n";

When invoked using a single string, parseopts treats the string as the name of a parse-option and returns its corresponding value if it exists (returns undef if it doesn't).

            ## Did we ask to see '=cut' paragraphs?
            my $want_cut = $parser->parseopts('-process_cut_cmd');
            $want_cut and print "-process_cut_cmd\n";

When invoked with multiple arguments, parseopts treats them as key/value pairs and the specified parse-option names are set to the given values. Any unspecified parse-options are unaffected.

            ## Set them back to the default
            $parser->parseopts(-warnings => 0);

When passed a single hash-ref, parseopts uses that hash to completely reset the existing parse-options, all previous parse-option values are lost.

            ## Reset all options to default
            $parser->parseopts( { } );

See PARSING OPTIONS for more information on the name and meaning of each parse-option currently recognized.

output_file()

            $fname = $parser->output_file();

Returns the name of the output file being written.

output_handle()

            $fhandle = $parser->output_handle();

Returns the output filehandle object.

input_file()

            $fname = $parser->input_file();

Returns the name of the input file being read.

input_handle()

            $fhandle = $parser->input_handle();

Returns the current input filehandle object.

PRIVATE METHODS AND DATA

Pod::Parser makes use of several internal methods and data fields which clients should not need to see or use. For the sake of avoiding name collisions for client data and methods, these methods and fields are briefly discussed here. Determined hackers may obtain further information about them by reading the Pod::Parser source code.

Private data fields are stored in the hash-object whose reference is returned by the new() constructor for this class. The names of all private methods and data-fields used by Pod::Parser begin with a prefix of "_" and match the regular expression /^_\w+$/.

TREE-BASED PARSING

If straightforward stream-based parsing wont meet your needs (as is likely the case for tasks such as translating PODs into structured markup languages like HTML and XML) then you may need to take the tree-based approach. Rather than doing everything in one pass and calling the interpolate() method to expand sequences into text, it may be desirable to instead create a parse-tree using the parse_text() method to return a tree-like structure which may contain an ordered list of children (each of which may be a text-string, or a similar tree-like structure).

Pay special attention to METHODS FOR PARSING AND PROCESSING and to the objects described in the Pod::InputObjects manpage. The former describes the gory details and parameters for how to customize and extend the parsing behavior of Pod::Parser. Pod::InputObjects provides several objects that may all be used interchangeably as parse-trees. The most obvious one is the Pod::ParseTree object. It defines the basic interface and functionality that all things trying to be a POD parse-tree should do. A Pod::ParseTree is defined such that each "node" may be a text-string, or a reference to another parse-tree. Each Pod::Paragraph object and each Pod::InteriorSequence object also supports the basic parse-tree interface.

The parse_text() method takes a given paragraph of text, and returns a parse-tree that contains one or more children, each of which may be a text-string, or an InteriorSequence object. There are also callback-options that may be passed to parse_text() to customize the way it expands or transforms interior-sequences, as well as the returned result. These callbacks can be used to create a parse-tree with custom-made objects (which may or may not support the parse-tree interface, depending on how you choose to do it).

If you wish to turn an entire POD document into a parse-tree, that process is fairly straightforward. The parse_text() method is the key to doing this successfully. Every paragraph-callback (i.e. the polymorphic methods for command(), verbatim(), and textblock() paragraphs) takes a Pod::Paragraph object as an argument. Each paragraph object has a parse_tree() method that can be used to get or set a corresponding parse-tree. So for each of those paragraph-callback methods, simply call parse_text() with the options you desire, and then use the returned parse-tree to assign to the given paragraph object.

That gives you a parse-tree for each paragraph - so now all you need is an ordered list of paragraphs. You can maintain that yourself as a data element in the object/hash. The most straightforward way would be simply to use an array-ref, with the desired set of custom "options" for each invocation of parse_text. Let's assume the desired option-set is given by the hash %options. Then we might do something like the following:

    package MyPodParserTree;

    @ISA = qw( Pod::Parser );

    ...
    sub begin_pod {
        my $self = shift;
        $self->{'-paragraphs'} = [];  ## initialize paragraph list
    }

    sub command {
        my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
        my $ptree = $parser->parse_text({%options}, $paragraph, ...);
        $pod_para->parse_tree( $ptree );
        push @{ $self->{'-paragraphs'} }, $pod_para;
    }

    sub verbatim {
        my ($parser, $paragraph, $line_num, $pod_para) = @_;
        push @{ $self->{'-paragraphs'} }, $pod_para;
    }

    sub textblock {
        my ($parser, $paragraph, $line_num, $pod_para) = @_;
        my $ptree = $parser->parse_text({%options}, $paragraph, ...);
        $pod_para->parse_tree( $ptree );
        push @{ $self->{'-paragraphs'} }, $pod_para;
    }

    ...
    package main;
    ...
    my $parser = new MyPodParserTree(...);
    $parser->parse_from_file(...);
    my $paragraphs_ref = $parser->{'-paragraphs'};

Of course, in this module-author's humble opinion, I'd be more inclined to use the existing Pod::ParseTree object than a simple array. That way everything in it, paragraphs and sequences, all respond to the same core interface for all parse-tree nodes. The result would look something like:

    package MyPodParserTree2;

    ...
    sub begin_pod {
        my $self = shift;
        $self->{'-ptree'} = new Pod::ParseTree;  ## initialize parse-tree
    }

    sub parse_tree {
        ## convenience method to get/set the parse-tree for the entire POD
        (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
        return $_[0]->{'-ptree'};
    }

    sub command {
        my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
        my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
        $pod_para->parse_tree( $ptree );
        $parser->parse_tree()->append( $pod_para );
    }

    sub verbatim {
        my ($parser, $paragraph, $line_num, $pod_para) = @_;
        $parser->parse_tree()->append( $pod_para );
    }

    sub textblock {
        my ($parser, $paragraph, $line_num, $pod_para) = @_;
        my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
        $pod_para->parse_tree( $ptree );
        $parser->parse_tree()->append( $pod_para );
    }

    ...
    package main;
    ...
    my $parser = new MyPodParserTree2(...);
    $parser->parse_from_file(...);
    my $ptree = $parser->parse_tree;
    ...

Now you have the entire POD document as one great big parse-tree. You can even use the -expand_seq option to parse_text to insert whole different kinds of objects. Just don't expect Pod::Parser to know what to do with them after that. That will need to be in your code. Or, alternatively, you can insert any object you like so long as it conforms to the Pod::ParseTree interface.

One could use this to create subclasses of Pod::Paragraphs and Pod::InteriorSequences for specific commands (or to create your own custom node-types in the parse-tree) and add some kind of emit() method to each custom node/subclass object in the tree. Then all you'd need to do is recursively walk the tree in the desired order, processing the children (most likely from left to right) by formatting them if they are text-strings, or by calling their emit() method if they are objects/references.

SEE ALSO

the Pod::InputObjects manpage, the Pod::Select manpage

Pod::InputObjects defines POD input objects corresponding to command paragraphs, parse-trees, and interior-sequences.

Pod::Select is a subclass of Pod::Parser which provides the ability to selectively include and/or exclude sections of a POD document from being translated based upon the current heading, subheading, subsubheading, etc.

AUTHOR

Please report bugs using http://rt.cpan.org.

Brad Appleton <bradapp@enteract.com>

Based on code for Pod::Text written by Tom Christiansen <tchrist@mox.perl.com>


PerlEz - PerlEz host DLL

    • Datatypes
    • PerlEzCreate
    • PerlEzCreateOpt
    • PerlEzDelete
    • PerlEzEvalString
    • PerlEzCall1
    • PerlEzCall2
    • PerlEzCall4
    • PerlEzCall8
    • PerlEzCall
    • PerlEzCallContext
    • PerlEzSetMagicScalarFunctions
    • PerlEzSetMagicScalarName
    • Format String
    • Error Codes
  • AUTHORS

NAME

PerlEz - PerlEz host DLL

DESCRIPTION

This document attempts to describe the functions of the PerlEz host Dynamically Linked Library (DLL). Please refer any questions or comments to the author below.

Datatypes

PerlEz has one specific data type, PERLEZHANDLE; this is a non-zero handle to a Perl interpreter that is created and can be accessed by the routines described below.

PerlEzCreate

 PERLEZHANDLE PerlEzCreate(LPCSTR lpFileName, LPCSTR lpOptions);
DESCRIPTION:

  • Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls. Multiple interpreters can be created, but only one will be executing at a time.

    • PARAMS:

  • lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL

  • lpOptions a pointer to a ASCIIZ string that are the command line options that will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.

    • RETURNS:

  • A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

    See also PerlEzDelete PerlEzCreateOpt

    • PerlEzCreateOpt

     PERLEZHANDLE PerlEzCreateOpt(LPCSTR lpFileName, LPCSTR lpOptions, LPCSTR lpScriptOpts);
    DESCRIPTION:

  • Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls. Multiple interpreters can be created, but only one will be executing at a time.

    • PARAMS:

  • lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL

  • lpOptions a pointer to a ASCIIZ string that are the command line options that will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.

  • lpScriptOpts a pointer to a ASCIIZ string that are the command line options that will be provided as parameters to the script; can be NULL.

    • RETURNS:

  • A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

    See also PerlEzDelete PerlEzCreate

    • PerlEzDelete

     BOOL PerlEzDelete(PERLEZHANDLE hHandle);
    DESCRIPTION:

  • Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate or PerlEzCreateOpt.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

    • RETURNS:

  • True if no error false otherwise.

    • PerlEzEvalString

     int PerlEzEvalString(PERLEZHANDLE hHandle, LPCSTR lpString, LPSTR lpBuffer, DWORD dwBufSize);
    DESCRIPTION:

  • Evaluates the string a returns the result in lpBuffer. If there is an error $! is returned in lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpString a pointer to the ASCIIZ string to evaluate

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall1

     int PerlEzCall1(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, LPVOID lpVoid);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid a pointer to a parameter will be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall2

     int PerlEzCall2(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
  LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...2 pointers to parameters that will be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall4

     int PerlEzCall4(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...4 pointers to parameters that will be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall8

     int PerlEzCall8(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4, LPVOID lpVoid5,
   LPVOID lpVoid6, LPVOID lpVoid7, LPVOID lpVoid8);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...8 pointers to parameters that will be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall

     int PerlEzCall(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, ...);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCallContext

     int PerlEzCallContext(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPVOID lpContextInfo,
   LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, ...);
    DESCRIPTION:

  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpContextInfo context info for magic fetch and store functions

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzSetMagicScalarFunctions

     int PerlEzSetMagicScalarFunctions(PERLEZHANDLE hHandle, LPFETCHVALUEFUNCTION lpfFetch,
                LPSTOREVALUEFUNCTION lpfStore);
    DESCRIPTION:

  • Sets the call back function pointers for magic scalar variables.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpfFetch a pointer to the call back function for fetching a string. if lpfFetch is NULL, then the scalar is write only.

  • lpfStore a pointer to the call back function for storinging a string. if lpfStore is NULL, then the scalar is read only.

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes NOTE: if lpfFetch and lpfStore are both NULL, then it is an error.

    See also PerlEzSetMagicScalarName

    • PerlEzSetMagicScalarName

     int PerlEzSetMagicScalarName(PERLEZHANDLE hHandle, LPCSTR pVariableName);
    DESCRIPTION:

  • Creates the variable if it does not exists and sets it to be tied to the call back function pointer for magic variables.

    • PARAMS:

  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • pVariableName a pointer to the name of the variable.

    • RETURNS:

  • A zero if no error; otherwise error code. See Error Codes

    See also PerlEzSetMagicScalarFunctions

    • Format String

    The format string is a series of characters that represents the type of parameters being supplied.

    s

  • this parameter is a pointer to a null terminated string.

    • i

  • this parameter is to be considered an integer.

    • d

  • this parameter is to be considered a double.

    • l[s | i | d]x

  • the next 'x' parameters will be put into an anonymous list of the type specifed. Either 's', 'i', or 'd'

    • Error Codes

    1. More space is needed to return a result

    2. Error string returned in the buffer

    3. More space needed to return the error message

    4. Format string is invalid

    5. Function call caused an exception

    6. Handle is invalid

    7. The second call to PerlEzSetMagicFunction failed

    8. Invalid parameter was passed to the routine

    9. Cannot allocate more memory

    AUTHORS

    Copyright (c) 1998-2003 ActiveState Corp. All rights reserved.


Pod::Perldoc::ToChecker - let Perldoc check Pod for errors

  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToChecker - let Perldoc check Pod for errors

SYNOPSIS

  % perldoc -o checker SomeFile.pod
  No Pod errors in SomeFile.pod
  (or an error report)

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Simple::Checker as a "formatter" class (or if that is not available, then Pod::Checker), to check for errors in a given Pod file.

This is actually a Pod::Simple::Checker (or Pod::Checker) subclass, and inherits all its options.

SEE ALSO

the Pod::Simple::Checker manpage, the Pod::Simple manpage, the Pod::Checker manpage, the Pod::Perldoc manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToMan - let Perldoc render Pod as man pages

  • CAVEAT
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToMan - let Perldoc render Pod as man pages

SYNOPSIS

  perldoc -o man Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Man and nroff for reading Pod pages.

The following options are supported: center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, quotes, release, section

(Those options are explained in the Pod::Man manpage.)

For example:

  perldoc -o man -w center:Pod Some::Modulename

CAVEAT

This module may change to use a different pod-to-nroff formatter class in the future, and this may change what options are supported.

SEE ALSO

the Pod::Man manpage, the Pod::Perldoc manpage, the Pod::Perldoc::ToNroff manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002,3,4 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff

  • CAVEAT
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff

SYNOPSIS

  perldoc -o nroff -d something.3 Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Man as a formatter class.

The following options are supported: center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, quotes, release, section

Those options are explained in the Pod::Man manpage.

For example:

  perldoc -o nroff -w center:Pod -d something.3 Some::Modulename

CAVEAT

This module may change to use a different pod-to-nroff formatter class in the future, and this may change what options are supported.

SEE ALSO

the Pod::Man manpage, the Pod::Perldoc manpage, the Pod::Perldoc::ToMan manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!

  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!

SYNOPSIS

  perldoc -opod Some::Modulename

(That's currently the same as the following:)

  perldoc -u Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to display Pod source as itself! Pretty Zen, huh?

Currently this class works by just filtering out the non-Pod stuff from a given input file.

SEE ALSO

the Pod::Perldoc manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF

  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF

SYNOPSIS

  perldoc -o rtf Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Simple::RTF as a formatter class.

This is actually a Pod::Simple::RTF subclass, and inherits all its options.

You have to have Pod::Simple::RTF installed (from the Pod::Simple dist), or this module won't work.

If Perldoc is running under MSWin and uses this class as a formatter, the output will be opened with write.exe or whatever program is specified in the environment variable RTFREADER. For example, to specify that RTF files should be opened the same as they are when you double-click them, you would do set RTFREADER=start.exe in your autoexec.bat.

Handy tip: put set PERLDOC=-ortf in your autoexec.bat and that will set this class as the default formatter to run when you do perldoc whatever.

SEE ALSO

the Pod::Simple::RTF manpage, the Pod::Simple manpage, the Pod::Perldoc manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToText - let Perldoc render Pod as plaintext

  • CAVEAT
  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToText - let Perldoc render Pod as plaintext

SYNOPSIS

  perldoc -o text Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Text as a formatter class.

It supports the following options, which are explained in the Pod::Text manpage: alt, indent, loose, quotes, sentence, width

For example:

  perldoc -o text -w indent:5 Some::Modulename

CAVEAT

This module may change to use a different text formatter class in the future, and this may change what options are supported.

SEE ALSO

the Pod::Text manpage, the Pod::Perldoc manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod

  • SEE ALSO
  • AUTHOR

NAME

Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod

SYNOPSIS

  perldoc -o tk Some::Modulename &

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Tk::Pod as a formatter class.

You have to have installed Tk::Pod first, or this class won't load.

SEE ALSO

the Tk::Pod manpage, the Pod::Perldoc manpage

AUTHOR

Sean M. Burke sburke@cpan.org, with significant portions copied from tkpod in the Tk::Pod dist, by Nick Ing-Simmons, Slaven Rezic, et al.


Pod::Perldoc::ToXml - let Perldoc render Pod as XML

  • SEE ALSO
  • COPYRIGHT AND DISCLAIMERS
  • AUTHOR

NAME

Pod::Perldoc::ToXml - let Perldoc render Pod as XML

SYNOPSIS

  perldoc -o xml -d out.xml Some::Modulename

DESCRIPTION

This is a "plug-in" class that allows Perldoc to use Pod::Simple::XMLOutStream as a formatter class.

This is actually a Pod::Simple::XMLOutStream subclass, and inherits all its options.

You have to have installed Pod::Simple::XMLOutStream (from the Pod::Simple dist), or this class won't work.

SEE ALSO

the Pod::Simple::XMLOutStream manpage, the Pod::Simple manpage, the Pod::Perldoc manpage

COPYRIGHT AND DISCLAIMERS

Copyright (c) 2002 Sean M. Burke. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke sburke@cpan.org


Pod::PlainText - Convert POD data to formatted ASCII text

  • DIAGNOSTICS
  • RESTRICTIONS
  • NOTES
  • SEE ALSO
  • AUTHOR

NAME

Pod::PlainText - Convert POD data to formatted ASCII text

SYNOPSIS

    use Pod::PlainText;
    my $parser = Pod::PlainText->new (sentence => 0, width => 78);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.txt.
    $parser->parse_from_file ('file.pod', 'file.txt');

DESCRIPTION

Pod::PlainText is a module that can convert documentation in the POD format (the preferred language for documenting Perl) into formatted ASCII. It uses no special formatting controls or codes whatsoever, and its output is therefore suitable for nearly any device.

As a derived class from Pod::Parser, Pod::PlainText supports the same methods and interfaces. See the Pod::Parser manpage for all the details; briefly, one creates a new parser with Pod::PlainText->new() and then calls either parse_from_filehandle() or parse_from_file().

new() can take options, in the form of key/value pairs, that control the behavior of the parser. The currently recognized options are:

alt

If set to a true value, selects an alternate output format that, among other things, uses a different heading style and marks =item entries with a colon in the left margin. Defaults to false.

indent

The number of spaces to indent regular text, and the default indentation for =over blocks. Defaults to 4.

loose

If set to a true value, a blank line is printed after a =head1 heading. If set to false (the default), no blank line is printed after =head1, although one is still printed after =head2. This is the default because it's the expected formatting for manual pages; if you're formatting arbitrary text documents, setting this to true may result in more pleasing output.

sentence

If set to a true value, Pod::PlainText will assume that each sentence ends in two spaces, and will try to preserve that spacing. If set to false, all consecutive whitespace in non-verbatim paragraphs is compressed into a single space. Defaults to true.

width

The column at which to wrap text on the right-hand side. Defaults to 76.

The standard Pod::Parser method parse_from_filehandle() takes up to two arguments, the first being the file handle to read POD from and the second being the file handle to write the formatted output to. The first defaults to STDIN if not given, and the second defaults to STDOUT. The method parse_from_file() is almost identical, except that its two arguments are the input and output disk files instead. See the Pod::Parser manpage for the specific details.

DIAGNOSTICS

Bizarre space in item

(W) Something has gone wrong in internal =item processing. This message indicates a bug in Pod::PlainText; you should never see it.

Can't open %s for reading: %s

(F) Pod::PlainText was invoked via the compatibility mode pod2text() interface and the input file it was given could not be opened.

Unknown escape: %s

(W) The POD source contained an E<> escape that Pod::PlainText didn't know about.

Unknown sequence: %s

(W) The POD source contained a non-standard internal sequence (something of the form X<>) that Pod::PlainText didn't know about.

Unmatched =back

(W) Pod::PlainText encountered a =back command that didn't correspond to an =over command.

RESTRICTIONS

Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on output, due to an internal implementation detail.

NOTES

This is a replacement for an earlier Pod::Text module written by Tom Christiansen. It has a revamped interface, since it now uses Pod::Parser, but an interface roughly compatible with the old Pod::Text::pod2text() function is still available. Please change to the new calling convention, though.

The original Pod::Text contained code to do formatting via termcap sequences, although it wasn't turned on by default and it was problematic to get it to work at all. This rewrite doesn't even try to do that, but a subclass of it does. Look for Pod::Text::Termcap.

SEE ALSO

Pod::Parser, Pod::Text::Termcap, pod2text(1)

AUTHOR

Please report bugs using http://rt.cpan.org.

Russ Allbery <rra@stanford.edu>, based very heavily on the original Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to Pod::Parser by Brad Appleton <bradapp@enteract.com>.


Pod::Plainer - Perl extension for converting Pod to old style Pod.

    • EXPORT
  • AUTHOR
  • SEE ALSO

NAME

Pod::Plainer - Perl extension for converting Pod to old style Pod.

SYNOPSIS

  use Pod::Plainer;

  my $parser = Pod::Plainer -> new ();
  $parser -> parse_from_filehandle(\*STDIN);

DESCRIPTION

Pod::Plainer uses Pod::Parser which takes Pod with the (new) 'C<< .. >>' constructs and returns the old(er) style with just 'C<>'; '<' and '>' are replaced by 'E<lt>' and 'E<gt>'.

This can be used to pre-process Pod before using tools which do not recognise the new style Pods.

EXPORT

None by default.

AUTHOR

Robin Barker, rmb1@cise.npl.co.uk

SEE ALSO

See the Pod::Parser manpage.


podselect - extract selected sections of POD from input

  • REQUIRES
  • EXPORTS
  • DESCRIPTION
  • SECTION SPECIFICATIONS
  • RANGE SPECIFICATIONS
  • OBJECT METHODS
  • curr_headings()
  • select()
  • add_selection()
  • clear_selections()
  • match_section()
  • is_selected()
  • EXPORTED FUNCTIONS
  • podselect()
  • PRIVATE METHODS AND DATA
  • _compile_section_spec()
    • $self->{_SECTION_HEADINGS}
    • $self->{_SELECTED_SECTIONS}
  • SEE ALSO
  • AUTHOR

NAME

Pod::Select, podselect() - extract selected sections of POD from input

SYNOPSIS

    use Pod::Select;

    ## Select all the POD sections for each file in @filelist
    ## and print the result on standard output.
    podselect(@filelist);

    ## Same as above, but write to tmp.out
    podselect({-output => "tmp.out"}, @filelist):

    ## Select from the given filelist, only those POD sections that are
    ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
    podselect({-sections => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist):

    ## Select the "DESCRIPTION" section of the PODs from STDIN and write
    ## the result to STDERR.
    podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN);

or

    use Pod::Select;

    ## Create a parser object for selecting POD sections from the input
    $parser = new Pod::Select();

    ## Select all the POD sections for each file in @filelist
    ## and print the result to tmp.out.
    $parser->parse_from_file("<&STDIN", "tmp.out");

    ## Select from the given filelist, only those POD sections that are
    ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
    $parser->select("NAME|SYNOPSIS", "OPTIONS");
    for (@filelist) { $parser->parse_from_file($_); }

    ## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from
    ## STDIN and write the result to STDERR.
    $parser->select("DESCRIPTION");
    $parser->add_selection("SEE ALSO");
    $parser->parse_from_filehandle(\*STDIN, \*STDERR);

REQUIRES

perl5.005, Pod::Parser, Exporter, Carp

EXPORTS

podselect()

DESCRIPTION

podselect() is a function which will extract specified sections of pod documentation from an input stream. This ability is provided by the Pod::Select module which is a subclass of Pod::Parser. Pod::Select provides a method named select() to specify the set of POD sections to select for processing/printing. podselect() merely creates a Pod::Select object and then invokes the podselect() followed by parse_from_file().

SECTION SPECIFICATIONS

podselect() and Pod::Select::select() may be given one or more "section specifications" to restrict the text processed to only the desired set of sections and their corresponding subsections. A section specification is a string containing one or more Perl-style regular expressions separated by forward slashes ("/"). If you need to use a forward slash literally within a section title you can escape it with a backslash ("\/").

The formal syntax of a section specification is:

  • head1-title-regex/head2-title-regex/...

Any omitted or empty regular expressions will default to ".*". Please note that each regular expression given is implicitly anchored by adding "^" and "$" to the beginning and end. Also, if a given regular expression starts with a "!" character, then the expression is negated (so !foo would match anything except foo).

Some example section specifications follow.

  • Match the NAME and SYNOPSIS sections and all of their subsections:

    NAME|SYNOPSIS

  • Match only the Question and Answer subsections of the DESCRIPTION section:

    DESCRIPTION/Question|Answer

  • Match the Comments subsection of all sections:

    /Comments

  • Match all subsections of DESCRIPTION except for Comments:

    DESCRIPTION/!Comments

  • Match the DESCRIPTION section but do not match any of its subsections:

    DESCRIPTION/!.+

  • Match all top level sections but none of their subsections:

    /!.+

OBJECT METHODS

The following methods are provided in this module. Each one takes a reference to the object itself as an implicit first parameter.

curr_headings()

            ($head1, $head2, $head3, ...) = $parser->curr_headings();
            $head1 = $parser->curr_headings(1);

This method returns a list of the currently active section headings and subheadings in the document being parsed. The list of headings returned corresponds to the most recently parsed paragraph of the input.

If an argument is given, it must correspond to the desired section heading number, in which case only the specified section heading is returned. If there is no current section heading at the specified level, then undef is returned.

select()

            $parser->select($section_spec1,$section_spec2,...);

This method is used to select the particular sections and subsections of POD documentation that are to be printed and/or processed. The existing set of selected sections is replaced with the given set of sections. See add_selection() for adding to the current set of selected sections.

Each of the $section_spec arguments should be a section specification as described in SECTION SPECIFICATIONS. The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object.

If no $section_spec arguments are given, then the existing set of selected sections is cleared out (which means all sections will be processed).

This method should not normally be overridden by subclasses.

add_selection()

            $parser->add_selection($section_spec1,$section_spec2,...);

This method is used to add to the currently selected sections and subsections of POD documentation that are to be printed and/or processed. See <select()> for replacing the currently selected sections.

Each of the $section_spec arguments should be a section specification as described in SECTION SPECIFICATIONS. The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object.

This method should not normally be overridden by subclasses.

clear_selections()

            $parser->clear_selections();

This method takes no arguments, it has the exact same effect as invoking <select()> with no arguments.

match_section()

            $boolean = $parser->match_section($heading1,$heading2,...);

Returns a value of true if the given section and subsection heading titles match any of the currently selected section specifications in effect from prior calls to select() and add_selection() (or if there are no explictly selected/deselected sections).

The arguments $heading1, $heading2, etc. are the heading titles of the corresponding sections, subsections, etc. to try and match. If $headingN is omitted then it defaults to the current corresponding section heading title in the input.

This method should not normally be overridden by subclasses.

is_selected()

            $boolean = $parser->is_selected($paragraph);

This method is used to determine if the block of text given in $paragraph falls within the currently selected set of POD sections and subsections to be printed or processed. This method is also responsible for keeping track of the current input section and subsections. It is assumed that $paragraph is the most recently read (but not yet processed) input paragraph.

The value returned will be true if the $paragraph and the rest of the text in the same section as $paragraph should be selected (included) for processing; otherwise a false value is returned.

EXPORTED FUNCTIONS

The following functions are exported by this module. Please note that these are functions (not methods) and therefore do not take an implicit first argument.

podselect()

            podselect(\%options,@filelist);

podselect will print the raw (untranslated) POD paragraphs of all POD sections in the given input files specified by @filelist according to the given options.

If any argument to podselect is a reference to a hash (associative array) then the values with the following keys are processed as follows:

-output

A string corresponding to the desired output file (or ">&STDOUT" or ">&STDERR"). The default is to use standard output.

-sections

A reference to an array of sections specifications (as described in SECTION SPECIFICATIONS) which indicate the desired set of POD sections and subsections to be selected from input. If no section specifications are given, then all sections of the PODs are used.

All other arguments should correspond to the names of input files containing POD sections. A file name of "-" or "<&STDIN" will be interpeted to mean standard input (which is the default if no filenames are given).

PRIVATE METHODS AND DATA

Pod::Select makes uses a number of internal methods and data fields which clients should not need to see or use. For the sake of avoiding name collisions with client data and methods, these methods and fields are briefly discussed here. Determined hackers may obtain further information about them by reading the Pod::Select source code.

Private data fields are stored in the hash-object whose reference is returned by the new() constructor for this class. The names of all private methods and data-fields used by Pod::Select begin with a prefix of "_" and match the regular expression /^_\w+$/.

SEE ALSO

the Pod::Parser manpage

AUTHOR

Please report bugs using http://rt.cpan.org.

Brad Appleton <bradapp@enteract.com>

Based on code for pod2text written by Tom Christiansen <tchrist@mox.perl.com>


Pod::Text - Convert POD data to formatted ASCII text

  • DIAGNOSTICS
  • RESTRICTIONS
  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::Text - Convert POD data to formatted ASCII text

SYNOPSIS

    use Pod::Text;
    my $parser = Pod::Text->new (sentence => 0, width => 78);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.txt.
    $parser->parse_from_file ('file.pod', 'file.txt');

DESCRIPTION

Pod::Text is a module that can convert documentation in the POD format (the preferred language for documenting Perl) into formatted ASCII. It uses no special formatting controls or codes whatsoever, and its output is therefore suitable for nearly any device.

As a derived class from Pod::Parser, Pod::Text supports the same methods and interfaces. See the Pod::Parser manpage for all the details; briefly, one creates a new parser with Pod::Text->new() and then calls either parse_from_filehandle() or parse_from_file().

new() can take options, in the form of key/value pairs, that control the behavior of the parser. The currently recognized options are:

alt

If set to a true value, selects an alternate output format that, among other things, uses a different heading style and marks =item entries with a colon in the left margin. Defaults to false.

code

If set to a true value, the non-POD parts of the input file will be included in the output. Useful for viewing code documented with POD blocks with the POD rendered and the code left intact.

indent

The number of spaces to indent regular text, and the default indentation for =over blocks. Defaults to 4.

loose

If set to a true value, a blank line is printed after a =head1 heading. If set to false (the default), no blank line is printed after =head1, although one is still printed after =head2. This is the default because it's the expected formatting for manual pages; if you're formatting arbitrary text documents, setting this to true may result in more pleasing output.

margin

The width of the left margin in spaces. Defaults to 0. This is the margin for all text, including headings, not the amount by which regular text is indented; for the latter, see the indent option. To set the right margin, see the width option.

quotes

Sets the quote marks used to surround C<> text. If the value is a single character, it is used as both the left and right quote; if it is two characters, the first character is used as the left quote and the second as the right quoted; and if it is four characters, the first two are used as the left quote and the second two as the right quote.

This may also be set to the special value none, in which case no quote marks are added around C<> text.

sentence

If set to a true value, Pod::Text will assume that each sentence ends in two spaces, and will try to preserve that spacing. If set to false, all consecutive whitespace in non-verbatim paragraphs is compressed into a single space. Defaults to true.

width

The column at which to wrap text on the right-hand side. Defaults to 76.

The standard Pod::Parser method parse_from_filehandle() takes up to two arguments, the first being the file handle to read POD from and the second being the file handle to write the formatted output to. The first defaults to STDIN if not given, and the second defaults to STDOUT. The method parse_from_file() is almost identical, except that its two arguments are the input and output disk files instead. See the Pod::Parser manpage for the specific details.

DIAGNOSTICS

Bizarre space in item
Item called without tag

(W) Something has gone wrong in internal =item processing. These messages indicate a bug in Pod::Text; you should never see them.

Can't open %s for reading: %s

(F) Pod::Text was invoked via the compatibility mode pod2text() interface and the input file it was given could not be opened.

Invalid quote specification "%s"

(F) The quote specification given (the quotes option to the constructor) was invalid. A quote specification must be one, two, or four characters long.

%s:%d: Unknown command paragraph: %s

(W) The POD source contained a non-standard command paragraph (something of the form =command args) that Pod::Man didn't know about. It was ignored.

%s:%d: Unknown escape: %s

(W) The POD source contained an E<> escape that Pod::Text didn't know about.

%s:%d: Unknown formatting code: %s

(W) The POD source contained a non-standard formatting code (something of the form X<>) that Pod::Text didn't know about.

%s:%d: Unmatched =back

(W) Pod::Text encountered a =back command that didn't correspond to an =over command.

RESTRICTIONS

Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on output, due to an internal implementation detail.

NOTES

This is a replacement for an earlier Pod::Text module written by Tom Christiansen. It has a revamped interface, since it now uses Pod::Parser, but an interface roughly compatible with the old Pod::Text::pod2text() function is still available. Please change to the new calling convention, though.

The original Pod::Text contained code to do formatting via termcap sequences, although it wasn't turned on by default and it was problematic to get it to work at all. This rewrite doesn't even try to do that, but a subclass of it does. Look for the Pod::Text::Termcap manpage.

SEE ALSO

the Pod::Parser manpage, the Pod::Text::Termcap manpage, pod2text(1)

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0.

AUTHOR

Russ Allbery <rra@stanford.edu>, based very heavily on the original Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to Pod::Parser by Brad Appleton <bradapp@enteract.com>.

COPYRIGHT AND LICENSE

Copyright 1999, 2000, 2001, 2002 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Pod::Text::Color - Convert POD data to formatted color ASCII text

  • BUGS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::Text::Color - Convert POD data to formatted color ASCII text

SYNOPSIS

    use Pod::Text::Color;
    my $parser = Pod::Text::Color->new (sentence => 0, width => 78);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.txt.
    $parser->parse_from_file ('file.pod', 'file.txt');

DESCRIPTION

Pod::Text::Color is a simple subclass of Pod::Text that highlights output text using ANSI color escape sequences. Apart from the color, it in all ways functions like Pod::Text. See the Pod::Text manpage for details and available options.

Term::ANSIColor is used to get colors and therefore must be installed to use this module.

BUGS

This is just a basic proof of concept. It should be seriously expanded to support configurable coloration via options passed to the constructor, and pod2text should be taught about those.

SEE ALSO

the Pod::Text manpage, the Pod::Parser manpage

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0.

AUTHOR

Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 1999, 2001 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Pod::Text::Overstrike - Convert POD data to formatted overstrike text

  • BUGS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::Text::Overstrike - Convert POD data to formatted overstrike text

SYNOPSIS

    use Pod::Text::Overstrike;
    my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.txt.
    $parser->parse_from_file ('file.pod', 'file.txt');

DESCRIPTION

Pod::Text::Overstrike is a simple subclass of Pod::Text that highlights output text using overstrike sequences, in a manner similar to nroff. Characters in bold text are overstruck (character, backspace, character) and characters in underlined text are converted to overstruck underscores (underscore, backspace, character). This format was originally designed for hardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT) terminals.

Overstruck text is best viewed by page-at-a-time programs that take advantage of the terminal's stand-out and underline capabilities, such as the less program on Unix.

Apart from the overstrike, it in all ways functions like Pod::Text. See the Pod::Text manpage for details and available options.

BUGS

Currently, the outermost formatting instruction wins, so for example underlined text inside a region of bold text is displayed as simply bold. There may be some better approach possible.

SEE ALSO

the Pod::Text manpage, the Pod::Parser manpage

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0.

AUTHOR

Joe Smith <Joe.Smith@inwap.com>, using the framework created by Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 2000 by Joe Smith <Joe.Smith@inwap.com>. Copyright 2001 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Pod::Text::Termcap - Convert POD data to ASCII text with format escapes

  • NOTES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

Pod::Text::Termcap - Convert POD data to ASCII text with format escapes

SYNOPSIS

    use Pod::Text::Termcap;
    my $parser = Pod::Text::Termcap->new (sentence => 0, width => 78);

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.txt.
    $parser->parse_from_file ('file.pod', 'file.txt');

DESCRIPTION

Pod::Text::Termcap is a simple subclass of Pod::Text that highlights output text using the correct termcap escape sequences for the current terminal. Apart from the format codes, it in all ways functions like Pod::Text. See the Pod::Text manpage for details and available options.

NOTES

This module uses Term::Cap to retrieve the formatting escape sequences for the current terminal, and falls back on the ECMA-48 (the same in this regard as ANSI X3.64 and ISO 6429, the escape codes also used by DEC VT100 terminals) if the bold, underline, and reset codes aren't set in the termcap information.

SEE ALSO

the Pod::Text manpage, the Pod::Parser manpage, the Term::Cap manpage

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0.

AUTHOR

Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 1999, 2001, 2002 by Russ Allbery <rra@stanford.edu>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


pod2usage - print a usage message from embedded pod documentation

  • ARGUMENTS
  • DESCRIPTION
  • EXAMPLES
    • Recommended Use
  • CAVEATS
  • AUTHOR
  • ACKNOWLEDGEMENTS

NAME

Pod::Usage, pod2usage() - print a usage message from embedded pod documentation

SYNOPSIS

  use Pod::Usage
  my $message_text  = "This text precedes the usage message.";
  my $exit_status   = 2;          ## The exit status to use
  my $verbose_level = 0;          ## The verbose level to use
  my $filehandle    = \*STDERR;   ## The filehandle to write to

  pod2usage($message_text);

  pod2usage($exit_status);

  pod2usage( { -message => $message_text ,
               -exitval => $exit_status  ,
               -verbose => $verbose_level,
               -output  => $filehandle } );

  pod2usage(   -msg     => $message_text ,
               -exitval => $exit_status  ,
               -verbose => $verbose_level,
               -output  => $filehandle   );

  pod2usage(   -verbose => 2,
               -noperldoc => 1  )

ARGUMENTS

pod2usage should be given either a single argument, or a list of arguments corresponding to an associative array (a "hash"). When a single argument is given, it should correspond to exactly one of the following:

  • A string containing the text of a message to print before printing the usage message

  • A numeric value corresponding to the desired exit status

  • A reference to a hash

If more than one argument is given then the entire argument list is assumed to be a hash. If a hash is supplied (either as a reference or as a list) it should contain one or more elements with the following keys:

-message
-msg

The text of a message to print immediately prior to printing the program's usage message.

-exitval

The desired exit status to pass to the exit() function. This should be an integer, or else the string "NOEXIT" to indicate that control should simply be returned without terminating the invoking process.

-verbose

The desired level of "verboseness" to use when printing the usage message. If the corresponding value is 0, then only the "SYNOPSIS" section of the pod documentation is printed. If the corresponding value is 1, then the "SYNOPSIS" section, along with any section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more then the entire manpage is printed.

The special verbosity level 99 requires to also specify the -section parameter; then these sections are extracted (see the Pod::Select manpage) and printed.

-section

A string representing a selection list for sections to be printed when -verbose is set to 99, e.g. "NAME|SYNOPSIS|DESCRIPTION|VERSION".

-output

A reference to a filehandle, or the pathname of a file to which the usage message should be written. The default is \*STDERR unless the exit value is less than 2 (in which case the default is \*STDOUT).

-input

A reference to a filehandle, or the pathname of a file from which the invoking script's pod documentation should be read. It defaults to the file indicated by $0 ($PROGRAM_NAME for users of English.pm).

-pathlist

A list of directory paths. If the input file does not exist, then it will be searched for in the given directory list (in the order the directories appear in the list). It defaults to the list of directories implied by $ENV{PATH}. The list may be specified either by a reference to an array, or by a string of directory paths which use the same path separator as $ENV{PATH} on your system (e.g., : for Unix, ; for MSWin32 and DOS).

-noperldoc

By default, Pod::Usage will call the perldoc manpage when -verbose >= 2 is specified. This does not work well e.g. if the script was packed with PAR. The -noperldoc option suppresses the external call to the perldoc manpage and uses the simple text formatter (the Pod::Text manpage) to output the POD.

DESCRIPTION

pod2usage will print a usage message for the invoking script (using its embedded pod documentation) and then exit the script with the desired exit status. The usage message printed may have any one of three levels of "verboseness": If the verbose level is 0, then only a synopsis is printed. If the verbose level is 1, then the synopsis is printed along with a description (if present) of the command line options and arguments. If the verbose level is 2, then the entire manual page is printed.

Unless they are explicitly specified, the default values for the exit status, verbose level, and output stream to use are determined as follows:

  • If neither the exit status nor the verbose level is specified, then the default is to use an exit status of 2 with a verbose level of 0.

  • If an exit status is specified but the verbose level is not, then the verbose level will default to 1 if the exit status is less than 2 and will default to 0 otherwise.

  • If an exit status is not specified but verbose level is given, then the exit status will default to 2 if the verbose level is 0 and will default to 1 otherwise.

  • If the exit status used is less than 2, then output is printed on STDOUT. Otherwise output is printed on STDERR.

Although the above may seem a bit confusing at first, it generally does "the right thing" in most situations. This determination of the default values to use is based upon the following typical Unix conventions:

  • An exit status of 0 implies "success". For example, diff(1) exits with a status of 0 if the two files have the same contents.

  • An exit status of 1 implies possibly abnormal, but non-defective, program termination. For example, grep(1) exits with a status of 1 if it did not find a matching line for the given regular expression.

  • An exit status of 2 or more implies a fatal error. For example, ls(1) exits with a status of 2 if you specify an illegal (unknown) option on the command line.

  • Usage messages issued as a result of bad command-line syntax should go to STDERR. However, usage messages issued due to an explicit request to print usage (like specifying -help on the command line) should go to STDOUT, just in case the user wants to pipe the output to a pager (such as more(1)).

  • If program usage has been explicitly requested by the user, it is often desireable to exit with a status of 1 (as opposed to 0) after issuing the user-requested usage message. It is also desireable to give a more verbose description of program usage in this case.

pod2usage doesn't force the above conventions upon you, but it will use them by default if you don't expressly tell it to do otherwise. The ability of pod2usage() to accept a single number or a string makes it convenient to use as an innocent looking error message handling function:

    use Pod::Usage;
    use Getopt::Long;

    ## Parse options
    GetOptions("help", "man", "flag1")  ||  pod2usage(2);
    pod2usage(1)  if ($opt_help);
    pod2usage(-verbose => 2)  if ($opt_man);

    ## Check for too many filenames
    pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);

Some user's however may feel that the above "economy of expression" is not particularly readable nor consistent and may instead choose to do something more like the following:

    use Pod::Usage;
    use Getopt::Long;

    ## Parse options
    GetOptions("help", "man", "flag1")  ||  pod2usage(-verbose => 0);
    pod2usage(-verbose => 1)  if ($opt_help);
    pod2usage(-verbose => 2)  if ($opt_man);

    ## Check for too many filenames
    pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
        if (@ARGV > 1);

As with all things in Perl, there's more than one way to do it, and pod2usage() adheres to this philosophy. If you are interested in seeing a number of different ways to invoke pod2usage (although by no means exhaustive), please refer to EXAMPLES.

EXAMPLES

Each of the following invocations of pod2usage() will print just the "SYNOPSIS" section to STDERR and will exit with a status of 2:

    pod2usage();

    pod2usage(2);

    pod2usage(-verbose => 0);

    pod2usage(-exitval => 2);

    pod2usage({-exitval => 2, -output => \*STDERR});

    pod2usage({-verbose => 0, -output  => \*STDERR});

    pod2usage(-exitval => 2, -verbose => 0);

    pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);

Each of the following invocations of pod2usage() will print a message of "Syntax error." (followed by a newline) to STDERR, immediately followed by just the "SYNOPSIS" section (also printed to STDERR) and will exit with a status of 2:

    pod2usage("Syntax error.");

    pod2usage(-message => "Syntax error.", -verbose => 0);

    pod2usage(-msg  => "Syntax error.", -exitval => 2);

    pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});

    pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});

    pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);

    pod2usage(-message => "Syntax error.",
              -exitval => 2,
              -verbose => 0,
              -output  => \*STDERR);

Each of the following invocations of pod2usage() will print the "SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to STDOUT and will exit with a status of 1:

    pod2usage(1);

    pod2usage(-verbose => 1);

    pod2usage(-exitval => 1);

    pod2usage({-exitval => 1, -output => \*STDOUT});

    pod2usage({-verbose => 1, -output => \*STDOUT});

    pod2usage(-exitval => 1, -verbose => 1);

    pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});

Each of the following invocations of pod2usage() will print the entire manual page to STDOUT and will exit with a status of 1:

    pod2usage(-verbose  => 2);

    pod2usage({-verbose => 2, -output => \*STDOUT});

    pod2usage(-exitval  => 1, -verbose => 2);

    pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});

Recommended Use

Most scripts should print some type of usage message to STDERR when a command line syntax error is detected. They should also provide an option (usually -H or -help) to print a (possibly more verbose) usage message to STDOUT. Some scripts may even wish to go so far as to provide a means of printing their complete documentation to STDOUT (perhaps by allowing a -man option). The following complete example uses Pod::Usage in combination with Getopt::Long to do all of these things:

    use Getopt::Long;
    use Pod::Usage;

    my $man = 0;
    my $help = 0;
    ## Parse options and print usage if there is a syntax error,
    ## or if usage was explicitly requested.
    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
    pod2usage(1) if $help;
    pod2usage(-verbose => 2) if $man;

    ## If no arguments were given, then allow STDIN to be used only
    ## if it's not connected to a terminal (otherwise print usage)
    pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));
    __END__

    =head1 NAME
    sample - Using GetOpt::Long and Pod::Usage
    =head1 SYNOPSIS
    sample [options] [file ...]
     Options:
       -help            brief help message
       -man             full documentation
    =head1 OPTIONS
    =over 8
    =item B<-help>
    Print a brief help message and exits.
    =item B<-man>
    Prints the manual page and exits.
    =back
    =head1 DESCRIPTION
    B<This program> will read the given input file(s) and do something
    useful with the contents thereof.
    =cut

CAVEATS

By default, pod2usage() will use $0 as the path to the pod input file. Unfortunately, not all systems on which Perl runs will set $0 properly (although if $0 isn't found, pod2usage() will search $ENV{PATH} or else the list specified by the -pathlist option). If this is the case for your system, you may need to explicitly specify the path to the pod docs for the invoking script using something similar to the following:

    pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");

In the pathological case that a script is called via a relative path and the script itself changes the current working directory (see chdir in the perlfunc manpage) before calling pod2usage, Pod::Usage will fail even on robust platforms. Don't do that.

AUTHOR

Please report bugs using http://rt.cpan.org.

Brad Appleton <bradapp@enteract.com>

Based on code for Pod::Text::pod2text() written by Tom Christiansen <tchrist@mox.perl.com>

ACKNOWLEDGEMENTS

Steven McDougall <swmcd@world.std.com> for his help and patience with re-writing this manpage.


a2p - Awk to Perl translator

    • OPTIONS
    • "Considerations"
  • ENVIRONMENT
  • AUTHOR
  • FILES
  • SEE ALSO
  • DIAGNOSTICS
  • BUGS

NAME

a2p - Awk to Perl translator

SYNOPSIS

a2p [options] [filename]

DESCRIPTION

A2p takes an awk script specified on the command line (or from standard input) and produces a comparable perl script on the standard output.

OPTIONS

Options include:

-D<number>

sets debugging flags.

-F<character>

tells a2p that this awk script is always invoked with this -F switch.

-n<fieldlist>

specifies the names of the input fields if input does not have to be split into an array. If you were translating an awk script that processes the password file, you might say:

        a2p -7 -nlogin.password.uid.gid.gcos.shell.home

Any delimiter can be used to separate the field names.

-<number>

causes a2p to assume that input will always have that many fields.

-o

tells a2p to use old awk behavior. The only current differences are:

  • Old awk always has a line loop, even if there are no line actions, whereas new awk does not.

  • In old awk, sprintf is extremely greedy about its arguments. For example, given the statement

            print sprintf(some_args), extra_args;

    old awk considers extra_args to be arguments to sprintf; new awk considers them arguments to print.

"Considerations"

A2p cannot do as good a job translating as a human would, but it usually does pretty well. There are some areas where you may want to examine the perl script produced and tweak it some. Here are some of them, in no particular order.

There is an awk idiom of putting int() around a string expression to force numeric interpretation, even though the argument is always integer anyway. This is generally unneeded in perl, but a2p can't tell if the argument is always going to be integer, so it leaves it in. You may wish to remove it.

Perl differentiates numeric comparison from string comparison. Awk has one operator for both that decides at run time which comparison to do. A2p does not try to do a complete job of awk emulation at this point. Instead it guesses which one you want. It's almost always right, but it can be spoofed. All such guesses are marked with the comment "#???". You should go through and check them. You might want to run at least once with the -w switch to perl, which will warn you if you use == where you should have used eq.

Perl does not attempt to emulate the behavior of awk in which nonexistent array elements spring into existence simply by being referenced. If somehow you are relying on this mechanism to create null entries for a subsequent for...in, they won't be there in perl.

If a2p makes a split line that assigns to a list of variables that looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the -n option mentioned above. This will let you name the fields throughout the script. If it splits to an array instead, the script is probably referring to the number of fields somewhere.

The exit statement in awk doesn't necessarily exit; it goes to the END block if there is one. Awk scripts that do contortions within the END block to bypass the block under such circumstances can be simplified by removing the conditional in the END block and just exiting directly from the perl script.

Perl has two kinds of array, numerically-indexed and associative. Perl associative arrays are called "hashes". Awk arrays are usually translated to hashes, but if you happen to know that the index is always going to be numeric you could change the {...} to [...]. Iteration over a hash is done using the keys() function, but iteration over an array is NOT. You might need to modify any loop that iterates over such an array.

Awk starts by assuming OFMT has the value %.6g. Perl starts by assuming its equivalent, $#, to have the value %.20g. You'll want to set $# explicitly if you use the default value of OFMT.

Near the top of the line loop will be the split operation that is implicit in the awk script. There are times when you can move this down past some conditionals that test the entire record so that the split is not done as often.

For aesthetic reasons you may wish to change the array base $[ from 1 back to perl's default of 0, but remember to change all array subscripts AND all substr() and index() operations to match.

Cute comments that say "# Here is a workaround because awk is dumb" are passed through unmodified.

Awk scripts are often embedded in a shell script that pipes stuff into and out of awk. Often the shell script wrapper can be incorporated into the perl script, since perl can start up pipes into and out of itself, and can do other things that awk can't do by itself.

Scripts that refer to the special variables RSTART and RLENGTH can often be simplified by referring to the variables $`, $& and $', as long as they are within the scope of the pattern match that sets them.

The produced perl script may have subroutines defined to deal with awk's semantics regarding getline and print. Since a2p usually picks correctness over efficiency. it is almost always possible to rewrite such code to be more efficient by discarding the semantic sugar.

For efficiency, you may wish to remove the keyword from any return statement that is the last statement executed in a subroutine. A2p catches the most common case, but doesn't analyze embedded blocks for subtler cases.

ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. A loop that tries to iterate over ARGV[0] won't find it.

ENVIRONMENT

A2p uses no environment variables.

AUTHOR

Larry Wall <larry@wall.org>

FILES

SEE ALSO

 perl   The perl compiler/interpreter

 s2p    sed to perl translator

DIAGNOSTICS

BUGS

It would be possible to emulate awk's behavior in selecting string versus numeric operations at run time by inspection of the operands, but it would be gross and inefficient. Besides, a2p almost always guesses right.

Storage for the awk syntax tree is currently static, and can run out.


SDBM_File - Tied access to sdbm files

  • DIAGNOSTICS
    • sdbm store returned -1, errno 22, key "..." at ...
  • BUGS AND WARNINGS

NAME

SDBM_File - Tied access to sdbm files

SYNOPSIS

 use Fcntl;   # For O_RDWR, O_CREAT, etc.
 use SDBM_File;

 tie(%h, 'SDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
   or die "Couldn't tie SDBM file 'filename': $!; aborting";

 # Now read and change the hash
 $h{newkey} = newvalue;
 print $h{oldkey};
 ...

 untie %h;

DESCRIPTION

SDBM_File establishes a connection between a Perl hash variable and a file in SDBM_File format;. You can manipulate the data in the file just as if it were in a Perl hash, but when your program exits, the data will remain in the file, to be used the next time your program runs.

Use SDBM_File with the Perl built-in tie function to establish the connection between the variable and the file. The arguments to tie should be:

  1. The hash variable you want to tie.

  2. The string "SDBM_File". (Ths tells Perl to use the SDBM_File package to perform the functions of the hash.)

  3. The name of the file you want to tie to the hash.

  4. Flags. Use one of:

    O_RDONLY

    Read-only access to the data in the file.

    5. O_WRONLY

    Write-only access to the data in the file.

    O_RDWR

    Both read and write access.

    If you want to create the file if it does not exist, add O_CREAT to any of these, as in the example. If you omit O_CREAT and the file does not already exist, the tie call will fail.

  5. The default permissions to use if a new file is created. The actual permissions will be modified by the user's umask, so you should probably use 0666 here. (See umask in the perlfunc manpage.)

DIAGNOSTICS

On failure, the tie call returns an undefined value and probably sets $! to contain the reason the file could not be tied.

sdbm store returned -1, errno 22, key "..." at ...

This warning is emitted when you try to store a key or a value that is too long. It means that the change was not recorded in the database. See BUGS AND WARNINGS below.

BUGS AND WARNINGS

There are a number of limits on the size of the data that you can store in the SDBM file. The most important is that the length of a key, plus the length of its associated value, may not exceed 1008 bytes.

See tie in the perlfunc manpage, the perldbmfilter manpage, the Fcntl manpage


SOAP::Lite - Client and server side SOAP implementation

    • WHERE TO FIND EXAMPLES
  • OVERVIEW OF CLASSES AND PACKAGES
    • SOAP::Lite
    • SOAP::Data
    • SOAP::Serializer
    • SOAP::SOM
    • SOAP::Schema
    • SOAP::Trace
    • SOAP::Fault
    • SOAP::Constants
  • FEATURES AND OPTIONS
    • DEFAULT SETTINGS
    • IN/OUT, OUT PARAMETERS AND AUTOBINDING
    • AUTODISPATCHING AND SOAP:: PREFIX
    • ACCESSING HEADERS AND ENVELOPE ON SERVER SIDE
    • SERVICE DEPLOYMENT. STATIC AND DYNAMIC
    • SECURITY
    • COMPRESSION
    • OBJECTS-BY-REFERENCE
    • INTEROPERABILITY
    • TROUBLESHOOTING
    • PERFORMANCE
    • WEBHOSTING INSTALLATION
  • BUGS AND LIMITATIONS
  • PLATFORMS
  • AVAILABILITY
  • SEE ALSO
  • ACKNOWLEDGMENTS
  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Lite - Client and server side SOAP implementation

SYNOPSIS

  use SOAP::Lite;
  print SOAP::Lite
    -> uri('http://www.soaplite.com/Temperatures')
    -> proxy('http://services.soaplite.com/temper.cgi')
    -> f2c(32)
    -> result;

The same code with autodispatch:

  use SOAP::Lite +autodispatch =>
    uri => 'http://www.soaplite.com/Temperatures',
    proxy => 'http://services.soaplite.com/temper.cgi';

  print f2c(32);

Code in OO-style:

  use SOAP::Lite +autodispatch =>
    uri => 'http://www.soaplite.com/Temperatures',
    proxy => 'http://services.soaplite.com/temper.cgi';

  my $temperatures = Temperatures->new(32); # get object
  print $temperatures->as_celsius;          # invoke method

Code with service description:

  use SOAP::Lite;
  print SOAP::Lite
    -> service('http://www.xmethods.net/sd/StockQuoteService.wsdl')
    -> getQuote('MSFT');

Code for SOAP server (CGI):

  use SOAP::Transport::HTTP;
  SOAP::Transport::HTTP::CGI
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
    -> handle;

Visual Basic client (through COM interface):

  MsgBox CreateObject("SOAP.Lite").new( _
    "proxy", "http://services.xmethods.net/soap";, _
    "uri",   "urn:xmethods-delayed-quotes" _
  ).getQuote("MSFT").result

mod_soap enabled SOAP server:

  .htaccess
  SetHandler perl-script
  PerlHandler Apache::SOAP
  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name"

ASP/VB SOAP server:

  <%
    Response.ContentType = "text/xml"
    Response.Write(Server.CreateObject("SOAP.Lite") _
      .server("SOAP::Server") _
      .dispatch_to("/Your/Path/To/Deployed/Modules") _
      .handle(Request.BinaryRead(Request.TotalBytes)) _
    )
  %>

DESCRIPTION

SOAP::Lite is a collection of Perl modules which provides a simple and lightweight interface to the Simple Object Access Protocol (SOAP) both on client and server side.

This version of SOAP::Lite supports the SOAP 1.1 specification ( http://www.w3.org/TR/SOAP ).

The main features of the library are:

  • Supports SOAP 1.1 spec.

  • Interoperability tests with different implementations: Apache SOAP, Frontier, Microsoft SOAP, Microsoft .NET, DevelopMentor, XMethods, 4s4c, Phalanx, Kafka, SQLData, Lucin (in Java, Perl, C++, Python, VB, COM, XSLT).

  • Provides COM interface. Single dll (standalone [2.5MB] or minimal [32kB]). Works on Windows 9x/Me/NT/2K. Doesn't require ROPE or MSXML. Examples in VB, Excel/VBA, C#, ASP, JavaScript, PerlScript and Perl.

  • Provides transparent compression support for HTTP transport.

  • Provides mod_soap module. Make SOAP server with a few lines in .htaccess or .conf file.

  • Includes XML::Parser::Lite (regexp-based XML parser) which runs instead of XML::Parser where Perl 5.6 runs (even on WinCE) with some limitations.

  • Includes XMLRPC::Lite, implementation of XML-RPC protocol on client and server side. All transports and features of SOAP::Lite are available.

  • Supports multipart/form-data MIME attachments.

  • Supports circular linked lists and multiple references.

  • Supports Map datatype (encoding of maps/hashes with arbitrary keys).

  • Supports HTTPS protocol.

  • Provides proxy support.

  • Provides CGI/daemon/mod_perl/Apache::Registry server implementations.

  • Provides TCP server implementation.

  • Provides IO (STDIN/STDOUT/File) server implementation.

  • Provides FTP client implementation.

  • Supports single/multipart MIME attachment (parsing side only).

  • Supports SMTP protocol.

  • Provides POP3 server implementation.

  • Supports M-POST and redirects in HTTP transport.

  • Supports Basic/Digest server authentication.

  • Works with CGI accelerators, like VelociGen and PerlEx.

  • Supports UDDI interface on client side. See UDDI::Lite for details.

  • Supports UDDI publishing API. Examples and documentation provided.

  • Supports WSDL schema with stub and run-time access.

  • Supports blessed object references.

  • Supports arrays (both serialization and deserialization with autotyping).

  • Supports custom serialization.

  • Provides exception transport with custom exceptions

  • Supports Base64 encoding.

  • Supports XML entity encoding.

  • Supports header attributes.

  • Supports dynamic and static class/method binding.

  • Supports objects-by-reference with simple garbage collection and activation.

  • Provides shell for interactive SOAP sessions.

  • Supports out parameters binding.

  • Supports transparent SOAP calls with autodispatch feature.

  • Provides easy services deployment. Put module in specified directory and it'll be accessible.

  • Has tests, examples and documentation to let you be up and running in no time.

WHERE TO FIND EXAMPLES

See t/*.t, examples/*.pl and the module documentation for a client-side examples that demonstrate the serialization of a SOAP request, sending it via HTTP to the server and receiving the response, and the deserialization of the response. See examples/server/* for server-side implementations.

OVERVIEW OF CLASSES AND PACKAGES

This table should give you a quick overview of the classes provided by the library.

 SOAP::Lite.pm
 -- SOAP::Lite           -- Main class provides all logic
 -- SOAP::Transport      -- Supports transport architecture
 -- SOAP::Data           -- Provides extensions for serialization architecture
 -- SOAP::Header         -- Provides extensions for header serialization
 -- SOAP::Parser         -- Parses XML file into object tree
 -- SOAP::Serializer     -- Serializes data structures to SOAP package
 -- SOAP::Deserializer   -- Deserializes results of SOAP::Parser into objects
 -- SOAP::SOM            -- Provides access to deserialized object tree
 -- SOAP::Constants      -- Provides access to common constants
 -- SOAP::Trace          -- Provides tracing facilities
 -- SOAP::Schema         -- Provides access and stub(s) for schema(s)
 -- SOAP::Schema::WSDL   -- WSDL implementation for SOAP::Schema
 -- SOAP::Server         -- Handles requests on server side
 -- SOAP::Server::Object -- Handles objects-by-reference
 -- SOAP::Fault          -- Provides support for Faults on server side
 SOAP::Transport::HTTP.pm
 -- SOAP::Transport::HTTP::Client  -- Client interface to HTTP transport
 -- SOAP::Transport::HTTP::Server  -- Server interface to HTTP transport
 -- SOAP::Transport::HTTP::CGI     -- CGI implementation of server interface
 -- SOAP::Transport::HTTP::Daemon  -- Daemon implementation of server interface
 -- SOAP::Transport::HTTP::Apache  -- mod_perl implementation of server interface
 SOAP::Transport::POP3.pm
 -- SOAP::Transport::POP3::Server  -- Server interface to POP3 protocol
 SOAP::Transport::MAILTO.pm
 -- SOAP::Transport::MAILTO::Client -- Client interface to SMTP/sendmail
 SOAP::Transport::LOCAL.pm
 -- SOAP::Transport::LOCAL::Client -- Client interface to local transport
 SOAP::Transport::TCP.pm
 -- SOAP::Transport::TCP::Server -- Server interface to TCP protocol
 -- SOAP::Transport::TCP::Client -- Client interface to TCP protocol
 SOAP::Transport::IO.pm
 -- SOAP::Transport::IO::Server -- Server interface to IO transport

SOAP::Lite

All methods that SOAP::Lite provides can be used for both setting and retrieving values. If you provide no parameters, you will get current value, and if parameters are provided, a new value will be assigned to the object and the method in question will return the current object (if not stated otherwise). This is suitable for stacking these calls like:

  $lite = SOAP::Lite
    -> uri('http://simon.fell.com/calc')
    -> proxy('http://soap.4s4c.com/ssss4c/soap.asp')
  ;

The order is insignificant and you may call the new() method first. If you don't do it, SOAP::Lite will do it for you. However, the new() method gives you an additional syntax:

  $lite = new SOAP::Lite
    uri => 'http://simon.fell.com/calc',
    proxy => 'http://soap.4s4c.com/ssss4c/soap.asp'
  ;
new()

new() accepts a hash with method names as keys. It will call the appropriate methods together with the passed values. Since new() is optional it won't be mentioned anymore.

transport()

Provides access to the SOAP::Transport object. The object will be created for you. You can reassign it (but generally you should not).

serializer()

Provides access to the SOAP::Serialization object. The object will be created for you. You can reassign it (but generally you should not).

proxy()

Shortcut for transport->proxy(). This lets you specify an endpoint (service address) and also loads the required module at the same time. It is required for dispatching SOAP calls. The name of the module will be defined depending on the protocol specific for the endpoint. The prefix SOAP::Transport will be prepended, the module will be loaded and object of class (with appended ::Client) will be created.

For example, for http://localhost/, the class for creating objects will look for SOAP::Transport:HTTP::Client;

In addition to endpoint parameter, proxy() can accept any transport specific parameters that could be passed as name => value pairs. For example, to specify proxy settings for HTTP protocol you may do:

  $soap->proxy('http://endpoint.server/',
               proxy => ['http' => 'http://my.proxy.server/']);

Notice that since proxy (second one) expects to get more than one parameter you should wrap them in array.

Another useful example can be the client that is sensitive to cookie-based authentication. You can provide this with:

  $soap->proxy('http://localhost/',
               cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

You may specify timeout for HTTP transport with following code:

  $soap->proxy('http://localhost/', timeout => 5);
endpoint()

Lets you specify an endpoint without changing/loading the protocol module. This is useful for switching endpoints without switching protocols. You should call proxy() first. No checks for protocol equivalence will be made.

outputxml()

Lets you specify the kind of output from all method calls. If true, all methods will return unprocessed, raw XML code. You can parse it with XML::Parser, SOAP::Deserializer or any other appropriate module.

autotype()

Shortcut for serializer->autotype(). This lets you specify whether the serializer will try to make autotyping for you or not. Default setting is true.

readable()

Shortcut for serializer->readable(). This lets you specify the format for the generated XML code. Carriage returns <CR> and indentation will be added for readability. Useful in the case you want to see the generated code in a debugger. By default, there are no additional characters in generated XML code.

namespace()

Shortcut for serializer->namespace(). This lets you specify the default namespace for generated envelopes ('SOAP-ENV' by default).

encodingspace()

Shortcut for serializer->encodingspace(). This lets you specify the default encoding namespace for generated envelopes ('SOAP-ENC' by default).

encoding()

Shortcut for serializer->encoding(). This lets you specify the encoding for generated envelopes. It does not actually change envelope encoding, it will just modify the XML declaration ('UTF-8' by default). Use undef value to not generate XML declaration.

typelookup()

Shortcut for serializer->typelookup(). This gives you access to the typelookup table that is used for autotyping. For more information see SOAP::Serializer.

uri()

Shortcut for serializer->uri(). This lets you specify the uri for SOAP methods. Nothing is specified by default and your call will definitely fail if you don't specify the required uri.

WARNING: URIs are just identifiers. They may look like URLs, but they are not guaranteed to point to anywhere and shouldn't be used as such pointers. URIs assume to be unique within the space of all XML documents, so consider them as unique identifiers and nothing else.

multirefinplace()

Shortcut for serializer->multirefinplace(). If true, the serializer will put values for multireferences in the first occurrence of the reference. Otherwise it will be encoded as top independent element, right after method element inside Body. Default value is false.

header()

DEPRECATED: Use SOAP::Header instead.

Shortcut for serializer->header(). This lets you specify the header for generated envelopes. You can specify root, mustUnderstand or any other header using SOAP::Data class:

  $serializer = SOAP::Serializer->envelope('method' => 'mymethod', 1,
    SOAP::Header->name(t1 => 5)->mustUnderstand(1),
    SOAP::Header->name(t2 => 7)->mustUnderstand(2),
  );

will be serialized into:

  <SOAP-ENV:Envelope ...attributes skipped>
    <SOAP-ENV:Header>
      <t1 xsi:type="xsd:int" SOAP-ENV:mustUnderstand="1">5</t1>
      <t2 xsi:type="xsd:int" SOAP-ENV:mustUnderstand="1">7</t2>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
      <namesp1:mymethod xmlns:namesp1="urn:SOAP__Serializer">
        <c-gensym6 xsi:type="xsd:int">1</c-gensym6>
      </namesp1:mymethod>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

You can mix SOAP::Header parameters with other parameters and you can also return SOAP::Header parameters as a result of a remote call. They will be placed into the header. See My::Parameters::addheader as an example.

on_action()

This lets you specify a handler for on_action event. It is triggered when creating SOAPAction. The default handler will set SOAPAction to "uri#method". You can change this behavior globally (see DEFAULT SETTINGS) or locally, for a particular object.

on_fault()

This lets you specify a handler for on_fault event. The default behavior is to die on an transport error and to do nothing on other error conditions. You may change this behavior globally (see DEFAULT SETTINGS) or locally, for a particular object.

on_debug()

This lets you specify a handler for on_debug event. Default behavior is to do nothing. Use +trace/+debug option for SOAP::Lite instead. If you use if be warned that since this method is just interface to +trace/+debug it has global effect, so if you install it for one object it'll be in effect for all subsequent calls (even for other objects).

on_nonserialized()

This lets you specify a handler for on_nonserialized event. The default behavior is to produce a warning if warnings are on for everything that cannot be properly serialized (like CODE references or GLOBs).

call()

Provides alternative interface for remote method calls. You can always run SOAP::Lite->new(...)->method(@parameters), but call() gives you several additional options:

prefixed method

If you want to specify prefix for generated method's element one of the available options is do it with call() interface:

  print SOAP::Lite
    -> new(....)
    -> call('myprefix:method' => @parameters)
    -> result;

This example will work on client side only. If you want to change prefix on server side you should override default serializer. See examples/server/soap.* for examples.

access to any method

If for some reason you want to get access to remote procedures that have the same name as methods of SOAP::Lite object these calls (obviously) won't be dispatched. In that case you can originate your call trough call():

  print SOAP::Lite
    -> new(....)
    -> call(new => @parameters)
    -> result;
implementation of OO interface

With autodispatch you can make CLASS/OBJECT calls like:

  my $obj = CLASS->new(@parameters);
  print $obj->method;

However, because of side effects autodispatch has, it's not always possible to use this syntax. call() provides you with alternative:

  # you should specify uri()
  my $soap = SOAP::Lite
    -> uri('http://my.own.site/CLASS') # <<< CLASS goes here
    # ..... other parameters
  ;

  my $obj = $soap->call(new => @parameters)->result;
  print $soap->call(method => $obj)->result;
  # $obj object will be updated here if necessary,
  # as if you call $obj->method() and method() updates $obj

  # Update of modified object MAY not work if server on another side
  # is not SOAP::Lite
ability to set method's attributes

Additionally this syntax lets you specify attributes for method element:

  print SOAP::Lite
    -> new(....)
    -> call(SOAP::Data->name('method')->attr({xmlns => 'mynamespace'})
            => @parameters)
    -> result;

You can specify any attibutes and name of SOAP::Data element becomes name of method. Everything else except attributes is ignored and parameters should be provided as usual.

Be warned, that though you have more control using this method, you should specify namespace attribute for method explicitely, even if you made uri() call earlier. So, if you have to have namespace on method element, instead of:

  print SOAP::Lite
    -> new(....)
    -> uri('mynamespace') # will be ignored
    -> call(SOAP::Data->name('method') => @parameters)
    -> result;

do

  print SOAP::Lite
    -> new(....)
    -> call(SOAP::Data->name('method')->attr({xmlns => 'mynamespace'})
            => @parameters)
    -> result;

because in the former call uri() will be ignored and namespace won't be specified. If you run script with -w option (as recommended) SOAP::Lite gives you a warning:

  URI is not provided as attribute for method (method)

Moreover, it'll become fatal error if you try to call it with prefixed name:

  print SOAP::Lite
    -> new(....)
    -> uri('mynamespace') # will be ignored
    -> call(SOAP::Data->name('a:method') => @parameters)
    -> result;

gives you:

  Can't find namespace for method (a:method)

because nothing is associated with prefix 'a'.

One more comment. One case when SOAP::Lite will change something that you specified is when you specified prefixed name and empty namespace name:

  print SOAP::Lite
    -> new(....)
    -> uri('')
    -> call('a:method' => @parameters)
    -> result;

This code will generate:

  <method xmlns="">....</method>

instead of

  <a:method xmlns:a="">....</method>

because later is not allowed according to XML Namespace specification.

In all other aspects ->call(mymethod => @parameters) is just a synonim for ->mymethod(@parameters).

self()

Returns object reference to global defaul object specified with use SOAP::Lite ... interface. Both class method and object method return reference to global object, so:

  use SOAP::Lite
    proxy => 'http://my.global.server'
  ;

  my $soap = SOAP::Lite->proxy('http://my.local.server');

  print $soap->self->proxy;

prints 'http://my.global.server' (the same as SOAP::Lite->self->proxy). See DEFAULT SETTINGS for more information.

dispatch_from()

Does exactly the same as autodispatch does, but doesn't install UNIVERSAL::AUTOLOAD handler and only install AUTOLOAD handlers in specified classes. Can be used only with use SOAP::Lite ... clause and should be specified first:

  use SOAP::Lite
    dispatch_from => ['A', 'B'], # use "dispatch_from => 'A'" for one class
    uri => ....,
    proxy => ....,
  ;

  A->a;
  B->b;

SOAP::Data

You can use this class if you want to specify a value, a name, atype, a uri or attributes for SOAP elements (use value(), name(), type(), uri() and attr() methods correspondingly). For example, SOAP::Data->name('abc')->value(123) will be serialized into <abc>123</abc>, as well as will SOAP::Data->name(abc => 123). Each of them (except the value() method) can accept a value as the second parameter. All methods return the current value if you call them without parameters. The return the object otherwise, so you can stack them. See tests for more examples. You can import these methods with:

  SOAP::Data->import('name');

or

  import SOAP::Data 'name';

and then use name(abc => 123) for brevity.

An interface for specific attributes is also provided. You can use the actor(), mustUnderstand(), encodingStyle() and root() methods to set/get values of the correspondent attributes.

  SOAP::Data
    ->name(c => 3)
    ->encodingStyle('http://xml.apache.org/xml-soap/literalxml')

will be serialized into:

  <c SOAP-ENV:encodingStyle="http://xml.apache.org/xml-soap/literalxml";
     xsi:type="xsd:int">3</c>

SOAP::Serializer

Usually you don't need to interact directly with this module. The only case when you need it, it when using autotyping. This feature lets you specify types for your data according to your needs as well as to introduce new data types (like ordered hash for example).

You can specify a type with SOAP::Data->type(float => 123). During the serialization stage the module will try to serialize your data with the as_float method. It then calls the typecast method (you can override it or inherit your own class from SOAP::Data) and only then it will try to serialize it according to data type (SCALAR, ARRAY or HASH). For example:

  SOAP::Data->type('ordered_hash' => [a => 1, b => 2])

will be serialized as an ordered hash, using the as_ordered_hash method.

If you do not specify a type directly, the serialization module will try to autodefine the type for you according to the typelookup hash. It contains the type name as key and the following 3-element array as value:

  priority,
  check_function (CODE reference),
  typecast function (METHOD name or CODE reference)

For example, if you want to add uriReference to autodefined types, you should add something like this:

  $s->typelookup->{uriReference} =
    [11, sub { $_[0] =~ m!^http://! }, 'as_uriReference'];

and add the as_uriReference method to the SOAP::Serializer class:

  sub SOAP::Serializer::as_uriReference {
    my $self = shift;
    my($value, $name, $type, $attr) = @_;
    return [$name, {'xsi:type' => 'xsd:uriReference', %$attr}, $value];
  }

The specified methods will work for both autotyping and direct typing, so you can use either

  SOAP::Data->type(uriReference => 'http://yahoo.com')>

or just

  'http://yahoo.com'

and it will be serialized into the same type. For more examples see as_* methods in SOAP::Serializer.

The SOAP::Serializer provides you with autotype(), readable(), namespace(), encodingspace(), encoding(), typelookup(), uri(), multirefinplace() and envelope() methods. All methods (except envelope()) are described in the SOAP::Lite section.

envelope()

This method allows you to build three kind of envelopes depending on the first parameter:

method
  envelope(method => 'methodname', @parameters);

or

  method('methodname', @parameters);

Lets you build a request/response envelope.

fault
  envelope(fault => 'faultcode', 'faultstring', $details);

or

  fault('faultcode', 'faultstring', $details);

Lets you build a fault envelope. Faultcode will be properly qualified and details could be string or object.

freeform
  envelope(freeform => 'something that I want to serialize');

or

  freeform('something that I want to serialize');

Reserved for nonRPC calls. Lets you build your own payload inside a SOAP envelope. All SOAP 1.1 specification rules are enforced, except method specific ones. See UDDI::Lite as example.

For more examples see tests and SOAP::Transport::HTTP.pm

SOAP::SOM

All calls you are making through object oriented interface will return SOAP::SOM object, and you can access actual values with it. Next example gives you brief overview of the class:

  my $soap = SOAP::Lite .....;
  my $som = $soap->method(@parameters);

  if ($som->fault) { # will be defined if Fault element is in the message
    print $som->faultdetail; # returns value of 'detail' element as
                             # string or object
    $som->faultcode;   #
    $som->faultstring; # also available
    $som->faultactor;  #
  } else {
    $som->result; # gives you access to result of call
                  # it could be any data structure, for example reference
                  # to array if server didi something like: return [1,2];

    $som->paramsout; # gives you access to out parameters if any
                     # for example, you'll get array (1,2) if
                     # server returns ([1,2], 1, 2);
                     # [1,2] will be returned as $som->result
                     # and $som->paramsall will return ([1,2], 1, 2)
                     # see section IN/OUT, OUT PARAMETERS AND AUTOBINDING
                     # for more information

    $som->paramsall; # gives access to result AND out parameters (if any)
                     # and returns them as one array

    $som->valueof('//myelement'); # returns value(s) (as perl data) of
                                  # 'myelement' if any. All elements in array
                                  # context and only first one in scalar

    $h = $som->headerof('//myheader'); # returns element as SOAP::Header, so
                                       # you can access attributes and values
                                       # with $h->mustUnderstand, $h->actor
                                       # or $h->attr (for all attributes)
      }

SOAP::SOM object gives you access to the deserialized envelope via several methods. All methods accept a node path (similar to XPath notations). SOM interprets '/' as the root node, '//' as relative location path ('//Body' will find all bodies in document, as well as '/Envelope//nums' will find all 'nums' nodes under Envelope node), '[num]' as node number and '[op num]' with op being a comparison operator ('<', '>', '<=', '>=', '!', '=').

All nodes in nodeset will be returned in document order.

match()

Accepts a path to a node and returns true/false in a boolean context and a SOM object otherwise. valueof() and dataof() can be used to get value(s) of matched node(s).

valueof()

Returns the value of a (previously) matched node. It accepts a node path. In this case, it returns the value of matched node, but does not change the current node. Suitable when you want to match a node and then navigate through node children:

  $som->match('/Envelope/Body/[1]'); # match method
  $som->valueof('[1]');              # result
  $som->valueof('[2]');              # first out parameter (if present)

The returned value depends on the context. In a scalar context it will return the first element from matched nodeset. In an array context it will return all matched elements.

dataof()

Same as valueof(), but it returns a SOAP::Data object, so you can get access to the name, the type and attributes of an element.

headerof()

Same as dataof(), but it returns SOAP::Header object, so you can get access to the name, the type and attributes of an element. Can be used for modifying headers (if you want to see updated header inside Header element, it's better to use this method instead of dataof() method).

namespaceuriof()

Returns the uri associated with the matched element. This uri can also be inherited, for example, if you have

  <a xmlns='http://my.namespace'>
    <b>
       value
    </b>
  </a>

this method will return same value for 'b' element as for 'a'.

SOAP::SOM also provides methods for direct access to the envelope, the body, methods and parameters (both in and out). All these methods return real values (in most cases it will be a hash reference), if called as object method. Returned values also depend on context: in an array context it will return an array of values and in scalar context it will return the first element. So, if you want to access the first output parameter, you can call $param = $som->paramsout; and you will get it regardless of the actual number of output parameters. If you call it as class function (for example, SOAP::SOM::method) it returns an XPath string that matches the current element ('/Envelope/Body/[1]' in case of 'method'). The method will return undef if not present OR if you try to access an undefined element. To distinguish between these two cases you can first access the match() method that will return true/false in a boolean context and then get the real value:

  if ($som->match('//myparameter')) {
    $value = $som->valueof; # can be undef too
  } else {
    # doesn't exist
  }
root()

Returns the value (as hash) of the root element. Do exactly the same as $som->valueof('/') does.

envelope()

Returns the value (as hash) of the Envelope element. Keys in this hash will be 'Header' (if present), 'Body' and any other (optional) elements. Values will be the deserialized header, body, and elements, respectively. If called as function (SOAP::SOM::envelope) it will return a Xpath string that matches the envelope content. Useful when you want just match it and then iterate over the content by yourself. Example:

  if ($som->match(SOAP::SOM::envelope)) {
    $som->valueof('Header'); # should give access to header if present
    $som->valueof('Body');   # should give access to body
  } else {
    # hm, are we doing SOAP or what?
  }
header()

Returns the value (as hash) of the Header element. If you want to access all attributes in the header use:

  # get element as SOAP::Data object
  $transaction = $som->match(join '/', SOAP::SOM::header, 'transaction')->dataof;
  # then you can access all attributes of 'transaction' element
  $transaction->attr;
headers()

Returns a node set of values with deserialized headers. The difference between the header() and headers() methods is that the first gives you access to the whole header and second to the headers inside the 'Header' tag:

  $som->headerof(join '/', SOAP::SOM::header, '[1]');
  # gives you first header as SOAP::Header object

  ($som->headers)[0];
  # gives you value of the first header, same as
  $som->valueof(join '/', SOAP::SOM::header, '[1]');

  $som->header->{name_of_your_header_here}
  # gives you value of name_of_your_header_here
body()

Returns the value (as hash) of the Body element.

fault()

Returns the value (as hash) of Fault element: faultcode, faultstring and detail. If Fault element is present, result(), paramsin(), paramsout() and method() will return an undef.

faultcode()

Returns the value of the faultcode element if present and undef otherwise.

faultstring()

Returns the value of the faultstring element if present and undef otherwise.

faultactor()

Returns the value of the faultactor element if present and undef otherwise.

faultdetail()

Returns the value of the detail element if present and undef otherwise.

method()

Returns the value of the method element (all input parameters if you call it on a deserialized request envelope, and result/output parameters if you call it on a deserialized response envelope). Returns undef if the 'Fault' element is present.

result()

Returns the value of the result of the method call. In fact, it will return the first child element (in document order) of the method element.

paramsin()

Returns the value(s) of all passed parameters.

paramsout()

Returns value(s) of the output parameters.

paramsall()

Returns value(s) of the result AND output parameters as one array.

SOAP::Schema

SOAP::Schema gives you ability to load schemas and create stubs according to these schemas. Different syntaxes are provided:

  •   use SOAP::Lite
    service => 'http://www.xmethods.net/sd/StockQuoteService.wsdl',
    # service => 'file:/your/local/path/StockQuoteService.wsdl',
    # service => 'file:./StockQuoteService.wsdl',
  ;
  print getQuote('MSFT'), "\n";

  •   use SOAP::Lite;
  print SOAP::Lite
    -> service('http://www.xmethods.net/sd/StockQuoteService.wsdl')
    -> getQuote('MSFT'), "\n";

  •   use SOAP::Lite;
  my $service = SOAP::Lite
    -> service('http://www.xmethods.net/sd/StockQuoteService.wsdl');
  print $service->getQuote('MSFT'), "\n";

You can create stub with stubmaker script:

  perl stubmaker.pl http://www.xmethods.net/sd/StockQuoteService.wsdl

and you'll be able to access SOAP services in one line:

  perl "-MStockQuoteService qw(:all)" -le "print getQuote('MSFT')"

or dynamically:

  perl "-MSOAP::Lite service=>'file:./quote.wsdl'" -le "print getQuote('MSFT')"

Other supported syntaxes with stub(s) are:

  •   use StockQuoteService ':all';
  print getQuote('MSFT'), "\n";

  •   use StockQuoteService;
  print StockQuoteService->getQuote('MSFT'), "\n";

  •   use StockQuoteService;
  my $service = StockQuoteService->new;
  print $service->getQuote('MSFT'), "\n";

Support for schemas is limited for now. Though module was tested with dozen different schemas it won't understand complex objects and will work only with WSDL.

SOAP::Trace

SOAP::Trace provides you with a trace/debug facility for the SOAP::Lite library. To activate it you need to specify a list of traceable events/parts of SOAP::Lite:

  use SOAP::Lite +trace =>
    qw(list of available traces here);

Available events are:

 transport  -- (client) access to request/response for transport layer
 dispatch   -- (server) shows full name of dispatched call
 result     -- (server) result of method call
 parameters -- (server) parameters for method call
 headers    -- (server) headers of received message
 objects    -- (both)   new/DESTROY calls
 method     -- (both)   parameters for '->envelope(method =>' call
 fault      -- (both)   parameters for '->envelope(fault =>' call
 freeform   -- (both)   parameters for '->envelope(freeform =>' call
 trace      -- (both)   trace enters into some important functions
 debug      -- (both)   details about transport

For example:

  use SOAP::Lite +trace =>
    qw(method fault);

lets you output the parameter values for all your fault/normal envelopes onto STDERR. If you want to log it you can either redirect STDERR to some file

  BEGIN { open(STDERR, '>>....'); }

or (preferably) define your own function for a particular event:

  use SOAP::Lite +trace =>
    method => sub {'log messages here'}, fault => \&log_faults;

You can share the same function for several events:

  use SOAP::Lite +trace =>
    method, fault => \&log_methods_and_faults;

Also you can use 'all' to get all available tracing and use '-' in front of an event to disable particular event:

  use SOAP::Lite +trace =>
    all, -transport; # to get all logging without transport messages

Finally,

  use SOAP::Lite +trace;

will switch all debugging on.

You can use 'debug' instead of 'trace'. I prefer 'trace', others 'debug'. Also on_debug is available for backward compatibility, as in

  use SOAP::Lite;

  my $s = SOAP::Lite
    -> uri('http://tempuri.org/')
    -> proxy('http://beta.search.microsoft.com/search/MSComSearchService.asmx')
    -> on_debug(sub{print@_}) # show you request/response with headers
  ;
  print $s->GetVocabulary(SOAP::Data->name(Query => 'something')->uri('http://tempuri.org/'))
          ->valueof('//FOUND');

or switch it on individually, with

  use SOAP::Lite +trace => debug;

or

  use SOAP::Lite +trace => debug => sub {'do_what_I_want_here'};

Compare this with:

  use SOAP::Lite +trace => transport;

which gives you access to actual request/response objects, so you can even set/read cookies or do whatever you want there.

The difference between debug and transport is that transport will get a HTTP::Request/HTTP::Response object and debug will get a stringified request (NOT OBJECT!). It can also be called in other places too.

SOAP::Fault

This class gives you access to Fault generated on server side. To make a Fault message you might simply die on server side and SOAP processor will wrap you message as faultstring element and will transfer Fault on client side. But in some cases you need to have more control over this process and SOAP::Fault class gives it to you. To use it, simply die with SOAP::Fault object as a parameter:

  die SOAP::Fault->faultcode('Server.Custom') # will be qualified
                 ->faultstring('Died in server method')
                 ->faultdetail(bless {code => 1} => 'BadError')
                 ->faultactor('http://www.soaplite.com/custom');

faultdetail() and faultactor() methods are optional and since faultcode and faultstring are required to represent fault message SOAP::Lite will use default values ('Server' and 'Application error') if not specified.

SOAP::Constants

This class gives you access to number of options that may affect behavior of SOAP::Lite objects. They are not true contstants, aren't they?

$DO_NOT_USE_XML_PARSER

By default SOAP::Lite tries to load XML::Parser and if it fails, then to load XML::Parser::Lite. You may skip the first step and use XML::Parser::Lite even if XML::Parser is presented in your system if assign true value like this:

  $SOAP::Constants::DO_NOT_USE_XML_PARSER = 1;
$DO_NOT_USE_CHARSET

By default SOAP::Lite specifies charset in content-type. Since not every toolkit likes it you have an option to switch it off if you set $DO_NOT_USE_CHARSET to true.

$DO_NOT_CHECK_CONTENT_TYPE

By default SOAP::Lite verifies that content-type in successful response has value 'multipart/related' or 'multipart/form-data' for MIME-encoded messages and 'text/xml' for all other ocassions. SOAP::Lite will raise exception for all other values. $DO_NOT_CHECK_CONTENT_TYPE when set to true will allow you to accept those values as valid.

FEATURES AND OPTIONS

DEFAULT SETTINGS

Though this feature looks similar to autodispatch they have (almost) nothing in common. It lets you create default object and all objects created after that will be cloned from default object and hence get its properties. If you want to provide common proxy() or uri() settings for all SOAP::Lite objects in your application you may do:

  use SOAP::Lite
    proxy => 'http://localhost/cgi-bin/soap.cgi',
    uri => 'http://my.own.com/My/Examples'
  ;

  my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
  print $soap1->getStateName(1)->result;

  my $soap2 = SOAP::Lite->new; # same thing as above
  print $soap2->getStateName(2)->result;

  # or you may override any settings you want
  my $soap3 = SOAP::Lite->proxy('http://localhost/');
  print $soap3->getStateName(1)->result;

Any SOAP::Lite properties can be propagated this way. Changes in object copies will not affect global settings and you may still change global settings with SOAP::Lite->self call which returns reference to global object. Provided parameter will update this object and you can even set it to undef:

  SOAP::Lite->self(undef);

The use SOAP::Lite syntax also lets you specify default event handlers for your code. If you have different SOAP objects and want to share the same on_action() (or on_fault() for that matter) handler. You can specify on_action() during initialization for every object, but you may also do:

  use SOAP::Lite
    on_action => sub {sprintf '%s#%s', @_}
  ;

and this handler will be the default handler for all your SOAP objects. You can override it if you specify a handler for a particular object. See t/*.t for example of on_fault() handler.

Be warned, that since use ... is executed at compile time all use statements will be executed before script execution that can make unexpected results. Consider code:

  use SOAP::Lite proxy => 'http://localhost/';

  print SOAP::Lite->getStateName(1)->result;

  use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';

  print SOAP::Lite->getStateName(1)->result;

BOTH SOAP calls will go to 'http://localhost/cgi-bin/soap.cgi'. If you want to execute use at run-time, put it in eval:

  eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;

or use

  SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');

IN/OUT, OUT PARAMETERS AND AUTOBINDING

SOAP::Lite gives you access to all parameters (both in/out and out) and also does some additional work for you. Lets consider following example:

  <mehodResponse>
    <res1>name1</res1>
    <res2>name2</res2>
    <res3>name3</res3>
  </mehodResponse>

In that case:

  $result = $r->result; # gives you 'name1'
  $paramout1 = $r->paramsout;      # gives you 'name2', because of scalar context
  $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
  $paramout2 = ($r->paramsout)[1]; # gives you 'name3'

or

  @paramsout = $r->paramsout; # gives you ARRAY of out parameters
  $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
  $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]

Generally, if server returns return (1,2,3) you will get 1 as the result and 2 and 3 as out parameters.

If the server returns return [1,2,3] you will get an ARRAY from result() and undef from paramsout() . Results can be arbitrary complex: they can be an array of something, they can be objects, they can be anything and still be returned by result() . If only one parameter is returned, paramsout() will return undef.

But there is more. If you have in your output parameters a parameter with the same signature (name+type) as in the input parameters this parameter will be mapped into your input automatically. Example:

server:

  sub mymethod {
    shift; # object/class reference
    my $param1 = shift;
    my $param2 = SOAP::Data->name('myparam' => shift() * 2);
    return $param1, $param2;
  }

client:

  $a = 10;
  $b = SOAP::Data->name('myparam' => 12);
  $result = $soap->mymethod($a, $b);

After that, $result == 10 and $b->value == 24! Magic? Sort of. Autobinding gives it to you. That will work with objects also with one difference: you do not need to worry about the name and the type of object parameter. Consider the PingPong example (examples/My/PingPong.pm and examples/pingpong.pl):

server:

  package My::PingPong;

  sub new {
    my $self = shift;
    my $class = ref($self) || $self;
    bless {_num=>shift} => $class;
  }

  sub next {
    my $self = shift;
    $self->{_num}++;
  }

client:

  use SOAP::Lite +autodispatch =>
    uri => 'urn:',
    proxy => 'http://localhost/'
  ;

  my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned
  print $p->next, "\n";          # $p->{_num} is 11 now!, object autobinded

AUTODISPATCHING AND SOAP:: PREFIX

WARNING: autodispatch feature can have side effects for your application and can affect functionality of other modules/libraries because of overloading UNIVERSAL::AUTOLOAD. All unresolved calls will be dispatched as SOAP calls, however it could be not what you want in some cases. If so, consider using object interface (see implementation of OO interface).

SOAP::Lite provides an autodispatching feature that lets you create code which looks the same for local and remote access.

For example:

  use SOAP::Lite +autodispatch =>
    uri => 'urn:/My/Examples',
    proxy => 'http://localhost/'
  ;

tells SOAP to 'autodispatch' all calls to the 'http://localhost/' endpoint with the 'urn:/My/Examples' uri. All consequent method calls can look like:

  print getStateName(1), "\n";
  print getStateNames(12,24,26,13), "\n";
  print getStateList([11,12,13,42])->[0], "\n";
  print getStateStruct({item1 => 10, item2 => 4})->{item2}, "\n";

As you can see, there is no SOAP specific coding at all.

The same logic will work for objects as well:

  print "Session iterator\n";
  my $p = My::SessionIterator->new(10);
  print $p->next, "\n";
  print $p->next, "\n";

This will access the remote My::SessionIterator module, gets an object, and then calls remote methods again. The object will be transferred to the server, the method is executed there and the result (and the modified object!) will be transferred back to the client.

Autodispatch will work only if you do not have the same method in your code. For example, if you have use My::SessionIterator somewhere in your code of our previous example, all methods will be resolved locally and no SOAP calls will be done. If you want to get access to remote objects/methods even in that case, use SOAP:: prefix to your methods, like:

  print $p->SOAP::next, "\n";

See pingpong.pl for example of a script, that works with the same object locally and remotely.

SOAP:: prefix also gives you ability to access methods that have the same name as methods of SOAP::Lite itself. For example, you want to call method new() for your class My::PingPong through OO interface. First attempt could be:

  my $s = SOAP::Lite
    -> uri('http://www.soaplite.com/My/PingPong')
    -> proxy('http://localhost/cgi-bin/soap.cgi')
  ;
  my $obj = $s->new(10);

but it won't work, because SOAP::Lite has method new() itself. To provide a hint, you should use SOAP:: prefix and call will be dispatched remotely:

  my $obj = $s->SOAP::new(10);

You can mix autodispatch and usual SOAP calls in the same code if you need it. Keep in mind, that calls with SOAP:: prefix should always be a method call, so if you want to call functions, use SOAP->myfunction() instead of SOAP::myfunction().

Be warned though Perl has very flexible syntax some versions will complain

  Bareword "autodispatch" not allowed while "strict subs" in use ...

if you try to put 'autodispatch' and '=>' on separate lines. So, keep them on the same line, or put 'autodispatch' in quotes:

  use SOAP::Lite 'autodispatch' # DON'T use plus in this case
    => ....
  ;

ACCESSING HEADERS AND ENVELOPE ON SERVER SIDE

SOAP::Lite gives you direct access to all headers and the whole envelope on the server side. Consider the following code from My::Parameters.pm:

  sub byname {
    my($a, $b, $c) = @{pop->method}{qw(a b c)};
    return "a=$a, b=$b, c=$c";
  }

You will get this functionality ONLY if you inherit your class from the SOAP::Server::Parameters class. This should keep existing code working and provides this feature only when you need it.

Every method on server side will be called as class/object method, so it will get an object reference or a class name as the first parameter, then the method parameters, and then an envelope as SOAP::SOM object. Shortly:

  $self [, @parameters] , $envelope

If you have a fixed number of parameters, you can do:

  my $self = shift;
  my($param1, $param2) = @_;

and ignore the envelope. If you need access to the envelope you can do:

  my $envelope = pop;

since the envelope is always the last element in the parameters list. The byname() method pop->method will return a hash with parameter names as hash keys and parameter values as hash values:

  my($a, $b, $c) = @{pop->method}{qw(a b c)};

gives you by-name access to your parameters.

SERVICE DEPLOYMENT. STATIC AND DYNAMIC

Let us scrutinize the deployment process. When designing your SOAP server you can consider two kind of deployment: static and dynamic. For both, static and dynamic, you should specify MODULE, MODULE::method, method or PATH/ when creating useing the SOAP::Lite module. The difference between static and dynamic deployment is that in case of 'dynamic', any module which is not present will be loaded on demand. See the SECURITY section for detailed description.

Example for static deployment:

  use SOAP::Transport::HTTP;
  use My::Examples;           # module is preloaded

  SOAP::Transport::HTTP::CGI
    # deployed module should be present here or client will get 'access denied'
    -> dispatch_to('My::Examples')
    -> handle;

Example for dynamic deployment:

  use SOAP::Transport::HTTP;
  # name is unknown, module will be loaded on demand

  SOAP::Transport::HTTP::CGI
    # deployed module should be present here or client will get 'access denied'
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
    -> handle;

For static deployment you should specify the MODULE name directly. For dynamic deployment you can specify the name either directly (in that case it will be required without any restriction) or indirectly, with a PATH In that case, the ONLY path that will be available will be the PATH given to the dispatch_to() method). For information how to handle this situation see SECURITY section.

You should also use static binding when you have several different classes in one file and want to make them available for SOAP calls.

SUMMARY:

  dispatch_to(
    # dynamic dispatch that allows access to ALL modules in specified directory
    PATH/TO/MODULES
    # 1. specifies directory
    # -- AND --
    # 2. gives access to ALL modules in this directory without limits
    # static dispatch that allows access to ALL methods in particular MODULE
    MODULE
    #  1. gives access to particular module (all available methods)
    #  PREREQUISITES:
    #    module should be loaded manually (for example with 'use ...')
    #    -- OR --
    #    you can still specify it in PATH/TO/MODULES
    # static dispatch that allows access to particular method ONLY
    MODULE::method
    # same as MODULE, but gives access to ONLY particular method,
    # so there is not much sense to use both MODULE and MODULE::method
    # for the same MODULE
  )

In addition to this SOAP::Lite also supports experimental syntax that allows you bind specific URL or SOAPAction to CLASS/MODULE or object:

  dispatch_with({
    URI => MODULE,        # 'http://www.soaplite.com/' => 'My::Class',
    SOAPAction => MODULE, # 'http://www.soaplite.com/method' => 'Another::Class',
    URI => object,        # 'http://www.soaplite.com/obj' => My::Class->new,
  })

URI is checked before SOAPAction. You may use both dispatch_to() and dispatch_with() syntax and dispatch_with() has more priority, so first checked URI, then SOAPAction and only then will be checked dispatch_to(). See t/03-server.t for more information and examples.

SECURITY

Due to security reasons, the current path for perl modules (@INC) will be disabled once you have chosen dynamic deployment and specified your own PATH/. If you want to access other modules in your included package you have several options:

  1. Switch to static linking:

       use MODULE;
   $server->dispatch_to('MODULE');

    It can be useful also when you want to import something specific from the deployed modules:

       use MODULE qw(import_list);

  2. Change use to require. The path is unavailable only during the initialization part, and it is available again during execution. So, if you do require somewhere in your package, it will work.

  3. Same thing, but you can do:

       eval 'use MODULE qw(import_list)'; die if $@;

  4. Assign a @INC directory in your package and then make use. Don't forget to put @INC in BEGIN{} block or it won't work:

       BEGIN { @INC = qw(my_directory); use MODULE }

COMPRESSION

SOAP::Lite provides you option for enabling compression on wire (for HTTP transport only). Both server and client should support this capability, but this logic should be absolutely transparent for your application.

Compression can be enabled by specifying threshold for compression on client or server side:

Client
  print SOAP::Lite
    -> uri('http://localhost/My/Parameters')
    -> proxy('http://localhost/', options => {compress_threshold => 10000})
    -> echo(1 x 10000)
    -> result
  ;
Server
  my $server = SOAP::Transport::HTTP::CGI
    -> dispatch_to('My::Parameters')
    -> options({compress_threshold => 10000})
    -> handle;

For more information see COMPRESSION section in HTTP transport documentation.

OBJECTS-BY-REFERENCE

SOAP::Lite implements an experimental (yet functional) support for objects-by-reference. You should not see any difference on the client side when using this. On the server side you should specify the names of the classes you want to be returned by reference (instead of by value) in the objects_by_reference() method for your server implementation (see soap.pop3, soap.daemon and Apache.pm).

Garbage collection is done on the server side (not earlier than after 600 seconds of inactivity time), and you can overload the default behavior with specific functions for any particular class.

Binding does not have any special syntax and is implemented on server side (see the differences between My::SessionIterator and My::PersistentIterator). On the client side, objects will have same type/class as before (My::SessionIterator->new() will return an object of class My::SessionIterator). However, this object is just a stub with an object ID inside.

INTEROPERABILITY

Microsoft's .NET

To use .NET client and SOAP::Lite server

qualify all elements

use fully qualified names for your return values, e.g.:

  return SOAP::Data->name('myname')
                   ->type('string')
                   ->uri('http://tempuri.org/')
                   ->value($output);

Use namespace that you specify for URI instead of 'http://tempuri.org/'.

In addition see comment about default incoding in .NET Web Services below.

To use SOAP::Lite client and .NET server

declare proper soapAction (uri/method) in your call

For example, use on_action(sub{join '', @_}).

disable charset in content-type

Specify $SOAP::Constants::DO_NOT_USE_CHARSET = 1 somewhere in your code after use SOAP::Lite if you are getting error:

  Server found request content type to be 'text/xml; charset=utf-8',
  but expected 'text/xml'
qualify all elements

Any of following actions should work:

use fully qualified name for method parameters

Use SOAP::Data->name(Query => 'biztalk')->uri('http://tempuri.org/') instead of SOAP::Data->name('Query' => 'biztalk').

Example of SOAPsh call (all parameters should be in one line):

  > perl SOAPsh.pl
    "http://beta.search.microsoft.com/search/mscomsearchservice.asmx"
    "http://tempuri.org/"
    "on_action(sub{join '', @_})"
    "GetVocabulary(SOAP::Data->name(Query  => 'biztalk')->uri('http://tempuri.org/'))"
make method in default namespace

instead of

  my @rc = $soap->call(add => @parms)->result;
  # -- OR --
  my @rc = $soap->add(@parms)->result;

use

  my $method = SOAP::Data->name('add')
                         ->attr({xmlns => 'http://tempuri.org/'});
  my @rc = $soap->call($method => @parms)->result;
modify .NET server if you are in charge for that

Stefan Pharies <stefanph@microsoft.com>:

SOAP::Lite uses the SOAP encoding (section 5 of the soap 1.1 spec), and the default for .NET Web Services is to use a literal encoding. So elements in the request are unqualified, but your service expects them to be qualified. .Net Web Services has a way for you to change the expected message format, which should allow you to get your interop working. At the top of your class in the asmx, add this attribute (for Beta 1):

  [SoapService(Style=SoapServiceStyle.RPC)]

Another source said it might be this attribute (for Beta 2):

  [SoapRpcService]

Full Web Service text may look like:

  <%@ WebService Language="C#" Class="Test" %>
  using System;
  using System.Web.Services;
  using System.Xml.Serialization;

  [SoapService(Style=SoapServiceStyle.RPC)]
  public class Test : WebService {
    [WebMethod]
    public int add(int a, int b) {
      return a + b;
    }
  }

Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:

"You can insert [SoapRpcService()] attribute either on your class or on operation level".

  <%@ WebService Language=CS class="DataType.StringTest"%>
  namespace DataType {

    using System;
    using System.Web.Services;
    using System.Web.Services.Protocols;
    using System.Web.Services.Description;

   [SoapRpcService()]
   public class StringTest: WebService {
     [WebMethod]
     [SoapRpcMethod()]
     public string RetString(string x) {
       return(x);
     }
   }
    }

Example from Yann Christensen <yannc@microsoft.com>:

  using System;
  using System.Web.Services;
  using System.Web.Services.Protocols;

  namespace Currency {
    [WebService(Namespace="http://www.yourdomain.com/example")]
    [SoapRpcService]
    public class Exchange {
      [WebMethod]
      public double getRate(String country, String country2) {
        return 122.69;
      }
    }
  }

Thanks to Petr Janata <petr.janata@i.cz>, Stefan Pharies <stefanph@microsoft.com>, Brian Jepson <bjepson@jepstone.net>, and others for description and examples.

TROUBLESHOOTING

HTTP transport

See TROUBLESHOOTING section in documentation for HTTP transport.

COM interface
Can't call method "server" on undefined value

Probably you didn't register Lite.dll with 'regsvr32 Lite.dll'

Failed to load PerlCtrl runtime

Probably you have two Perl installations in different places and ActiveState's Perl isn't the first Perl specified in PATH. Rename the directory with another Perl (at least during the DLL's startup) or put ActiveState's Perl on the first place in PATH.

XML Parsers
SAX parsers

SAX 2.0 has a known bug in org.xml.sax.helpers.ParserAdapter rejects Namespace prefix used before declaration

(http://www.megginson.com/SAX/index.html).

That means that in some cases SOAP messages created by SOAP::Lite may not be parsed properly by SAX2/Java parser, because Envelope element contains namespace declarations and attributes that depends on this declarations. According to XML specification order of these attributes is not significant. SOAP::Lite does NOT have a problem parsing such messages.

Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.

PERFORMANCE

Processing of XML encoded fragments

SOAP::Lite is based on XML::Parser which is basically wrapper around James Clark's expat parser. Expat's behavior for parsing XML encoded string can affect processing messages that have lot of encoded entities, like XML fragments, encoded as strings. Providing low-level details, parser will call char() callback for every portion of processed stream, but individually for every processed entity or newline. It can lead to lot of calls and additional memory manager expenses even for small messages. By contrast, XML messages which are encoded as base64, don't have this problem and difference in processing time can be significant. For XML encoded string that has about 20 lines and 30 tags, number of call could be about 100 instead of one for the same string encoded as base64.

Since it is parser's feature there is NO fix for this behavior (let me know if you find one), especially because you need to parse message you already got (and you cannot control content of this message), however, if your are in charge for both ends of processing you can switch encoding to base64 on sender's side. It will definitely work with SOAP::Lite and it may work with other toolkits/implementations also, but obviously I cannot guarantee that.

If you want to encode specific string as base64, just do SOAP::Data->type(base64 => $string) either on client or on server side. If you want change behavior for specific instance of SOAP::Lite, you may subclass SOAP::Serializer, override as_string() method that is responsible for string encoding (take a look into as_base64()) and specify new serializer class for your SOAP::Lite object with:

  my $soap = new SOAP::Lite
    serializer => My::Serializer->new,
    ..... other parameters

or on server side:

  my $server = new SOAP::Transport::HTTP::Daemon # or any other server
    serializer => My::Serializer->new,
    ..... other parameters

If you want to change this behavior for all instances of SOAP::Lite, just substitute as_string() method with as_base64() somewhere in your code after use SOAP::Lite and before actual processing/sending:

  *SOAP::Serializer::as_string = \&SOAP::Serializer::as_base64;

Be warned that last two methods will affect all strings and convert them into base64 encoded. It doesn't make any difference for SOAP::Lite, but it may make a difference for other toolkits.

WEBHOSTING INSTALLATION

As soon as you have telnet access to the box and XML::Parser is already installed there (or you have Perl 5.6 and can use XML::Parser::Lite) you may install your own copy of SOAP::Lite even if hosting provider doesn't want to do it.

Setup PERL5LIB environment variable. Depending on your shell it may look like:

  PERL5LIB=/you/home/directory/lib; export PERL5LIB

lib here is the name of directory where all libraries will be installed under your home directory.

Run CPAN module with

  perl -MCPAN -e shell

and run three commands from CPAN shell

  > o conf make_arg -I~/lib
  > o conf make_install_arg -I~/lib
  > o conf makepl_arg LIB=~/lib PREFIX=~ INSTALLMAN1DIR=~/man/man1 INSTALLMAN3DIR=~/man/man3

LIB will specify directory where all libraries will reside.

PREFIX will specify prefix for all directories (like lib, bin, man, though it doesn't work in all cases for some reason).

INSTALLMAN1DIR and INSTALLMAN3DIR specify directories for manuals (if you don't specify them, install will fail because it'll try to setup it in default directory and you don't have permissions for that).

Then run:

  > install SOAP::Lite

Now in your scripts you need to specify:

  use lib '/your/home/directory/lib';

somewhere before 'use SOAP::Lite;'

BUGS AND LIMITATIONS

  • No support for multidimensional, partially transmitted and sparse arrays (however arrays of arrays are supported, as well as any other data structures, and you can add your own implementation with SOAP::Data).

  • Limited support for WSDL schema.

  • XML::Parser::Lite relies on Unicode support in Perl and doesn't do entity decoding.

  • Limited support for mustUnderstand and Actor attributes.

PLATFORMS

MacOS

Information about XML::Parser for MacPerl could be found here: http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html

Compiled XML::Parser for MacOS could be found here: http://www.perl.com/CPAN-local/authors/id/A/AS/ASANDSTRM/XML-Parser-2.27-bin-1-MacOS.tgz

AVAILABILITY

You can download the latest version SOAP::Lite for Unix or SOAP::Lite for Win32 from http://soaplite.com/ . SOAP::Lite is available also from CPAN ( http://search.cpan.org/search?dist=SOAP-Lite ). You are very welcome to write mail to the author (paulclinger@yahoo.com) with your comments, suggestions, bug reports and complaints.

SEE ALSO

the SOAP manpage SOAP/Perl library from Keith Brown ( http://www.develop.com/soap/ ) or ( http://search.cpan.org/search?dist=SOAP )

ACKNOWLEDGMENTS

A lot of thanks to Tony Hong <thong@xmethods.net>, Petr Janata <petr.janata@i.cz>, Murray Nesbitt <murray@ActiveState.com>, Robert Barta <rho@bigpond.net.au>, Gisle Aas <gisle@ActiveState.com>, Carl K. Cunningham <cc@roberts.de>, Graham Glass <graham-glass@mindspring.com>, Chris Radcliff <chris@velocigen.com>, Arun Kumar <u_arunkumar@yahoo.com>, and many many others for provided help, feedback, support, patches and comments.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Test - Test framework for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Test - Test framework for SOAP::Lite

SYNOPSIS

  use SOAP::Test;

  SOAP::Test::Server::run_for('http://localhost/cgi-bin/soap.cgi');

DESCRIPTION

SOAP::Test provides simple framework for testing server implementations. Specify your address (endpoint) and run provided tests against your server. See t/1*.t for examples.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::FTP - Client side FTP support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::FTP - Client side FTP support for SOAP::Lite

SYNOPSIS

  use SOAP::Lite
    uri => 'http://my.own.site.com/My/Examples',
    proxy => 'ftp://login:password@ftp.somewhere.com/relative/path/to/file.xml', # ftp server
    # proxy => 'ftp://login:password@ftp.somewhere.com//absolute/path/to/file.xml', # ftp server
  ;

  print getStateName(1);

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::HTTP - Server/Client side HTTP support for SOAP::Lite

    • PROXY SETTINGS
    • COOKIE-BASED AUTHENTICATION
    • SSL CERTIFICATE AUTHENTICATION
    • COMPRESSION
  • EXAMPLES
  • TROUBLESHOOTING
  • DEPENDENCIES
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::HTTP - Server/Client side HTTP support for SOAP::Lite

SYNOPSIS

Client
  use SOAP::Lite
    uri => 'http://my.own.site.com/My/Examples',
    proxy => 'http://localhost/',
  # proxy => 'http://localhost/cgi-bin/soap.cgi', # local CGI server
  # proxy => 'http://localhost/',                 # local daemon server
  # proxy => 'http://localhost/soap',             # local mod_perl server
  # proxy => 'https://localhost/soap',            # local mod_perl SECURE server
  # proxy => 'http://login:password@localhost/cgi-bin/soap.cgi', # local CGI server with authentication
  ;

  print getStateName(1);
CGI server
  use SOAP::Transport::HTTP;

  SOAP::Transport::HTTP::CGI
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
    -> handle
  ;
Daemon server
  use SOAP::Transport::HTTP;

  # change LocalPort to 81 if you want to test it with soapmark.pl

  my $daemon = SOAP::Transport::HTTP::Daemon
    -> new (LocalAddr => 'localhost', LocalPort => 80)
    # specify list of objects-by-reference here
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  print "Contact to SOAP server at ", $daemon->url, "\n";
  $daemon->handle;
Apache mod_perl server

See examples/server/Apache.pm and EXAMPLES section for more information.

mod_soap server (.htaccess, directory-based access)
  SetHandler perl-script
  PerlHandler Apache::SOAP
  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
  PerlSetVar options "compress_threshold => 10000"

See the Apache::SOAP manpage for more information.

DESCRIPTION

This class encapsulates all HTTP related logic for a SOAP server, independent of what web server it's attached to. If you want to use this class you should follow simple guideline mentioned above.

Following methods are available:

on_action()

on_action method lets you specify SOAPAction understanding. It accepts reference to subroutine that takes three parameters:

  SOAPAction, method_uri and method_name.

SOAPAction is taken from HTTP header and method_uri and method_name are extracted from request's body. Default behavior is match SOAPAction if present and ignore it otherwise. You can specify you own, for example die if SOAPAction doesn't match with following code:

  $server->on_action(sub {
    (my $action = shift) =~ s/^("?)(.+)\1$/$2/;
    die "SOAPAction shall match 'uri#method'\n" if $action ne join '#', @_;
  });
dispatch_to()

dispatch_to lets you specify where you want to dispatch your services to. More precisely, you can specify PATH, MODULE, method or combination MODULE::method. Example:

  dispatch_to(
    'PATH/',          # dynamic: load anything from there, any module, any method
    'MODULE',         # static: any method from this module
    'MODULE::method', # static: specified method from this module
    'method',         # static: specified method from main::
  );

If you specify PATH/ name of module/classes will be taken from uri as path component and converted to Perl module name with substitution '::' for '/'. Example:

  urn:My/Examples              => My::Examples
  urn://localhost/My/Examples  => My::Examples
  http://localhost/My/Examples => My::Examples

For consistency first '/' in the path will be ignored.

According to this scheme to deploy new class you should put this class in one of the specified directories and enjoy its services. Easy, eh?

handle()

handle method will handle your request. You should provide parameters with request() method, call handle() and get it back with response() .

request()

request method gives you access to HTTP::Request object which you can provide for Server component to handle request.

response()

response method gives you access to HTTP::Response object which you can access to get results from Server component after request was handled.

PROXY SETTINGS

You can use any proxy setting you use with LWP::UserAgent modules:

 SOAP::Lite->proxy('http://endpoint.server/',
                   proxy => ['http' => 'http://my.proxy.server']);

or

 $soap->transport->proxy('http' => 'http://my.proxy.server');

should specify proxy server for you. And if you use HTTP_proxy_user and HTTP_proxy_pass for proxy authorization SOAP::Lite should know how to handle it properly.

COOKIE-BASED AUTHENTICATION

  use HTTP::Cookies;

  my $cookies = HTTP::Cookies->new(ignore_discard => 1);
    # you may also add 'file' if you want to keep them between sessions

  my $soap = SOAP::Lite->proxy('http://localhost/');
  $soap->transport->cookie_jar($cookies);

Cookies will be taken from response and provided for request. You may always add another cookie (or extract what you need after response) with HTTP::Cookies interface.

You may also do it in one line:

  $soap->proxy('http://localhost/',
               cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

SSL CERTIFICATE AUTHENTICATION

To get certificate authentication working you need to specify three environment variables: HTTPS_CERT_FILE, HTTPS_KEY_FILE, and (optionally) HTTPS_CERT_PASS:

  $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
  $ENV{HTTPS_KEY_FILE}  = 'client-key.pem';

Crypt::SSLeay (which is used for https support) will take care about everything else. Other options (like CA peer verification) can be specified in a similar way. See Crypt::SSLeay documentation for more details.

Those who would like to use encrypted keys may check http://groups.yahoo.com/group/soaplite/message/729 for details.

COMPRESSION

SOAP::Lite provides you with the option for enabling compression on the wire (for HTTP transport only). Both server and client should support this capability, but this should be absolutely transparent to your application. The Server will respond with an encoded message only if the client can accept it (indicated by client sending an Accept-Encoding header with 'deflate' or '*' values) and client has fallback logic, so if server doesn't understand specified encoding (Content-Encoding: deflate) and returns proper error code (415 NOT ACCEPTABLE) client will repeat the same request without encoding and will store this server in a per-session cache, so all other requests will go there without encoding.

Having options on client and server side that let you specify threshold for compression you can safely enable this feature on both client and server side.

Client
  print SOAP::Lite
    -> uri('http://localhost/My/Parameters')
    -> proxy('http://localhost/', options => {compress_threshold => 10000})
    -> echo(1 x 10000)
    -> result
  ;
Server
  my $server = SOAP::Transport::HTTP::CGI
    -> dispatch_to('My::Parameters')
    -> options({compress_threshold => 10000})
    -> handle;

Compression will be enabled on the client side if the threshold is specified and the size of current message is bigger than the threshold and the module Compress::Zlib is available.

The Client will send the header 'Accept-Encoding' with value 'deflate' if the threshold is specified and the module Compress::Zlib is available.

Server will accept the compressed message if the module Compress::Zlib is available, and will respond with the compressed message only if the threshold is specified and the size of the current message is bigger than the threshold and the module Compress::Zlib is available and the header 'Accept-Encoding' is presented in the request.

EXAMPLES

Consider following examples of SOAP servers:

CGI:
  use SOAP::Transport::HTTP;

  SOAP::Transport::HTTP::CGI
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
    -> handle
  ;
daemon:
  use SOAP::Transport::HTTP;

  my $daemon = SOAP::Transport::HTTP::Daemon
    -> new (LocalAddr => 'localhost', LocalPort => 80)
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  print "Contact to SOAP server at ", $daemon->url, "\n";
  $daemon->handle;
mod_perl:

httpd.conf:

  <Location /soap>
    SetHandler perl-script
    PerlHandler SOAP::Apache
  </Location>

Apache.pm:

  package SOAP::Apache;

  use SOAP::Transport::HTTP;

  my $server = SOAP::Transport::HTTP::Apache
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method');

  sub handler { $server->handler(@_) }

  1;
Apache::Registry:

httpd.conf:

  Alias /mod_perl/ "/Apache/mod_perl/"
  <Location /mod_perl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader On
    Options +ExecCGI
  </Location>

soap.mod_cgi (put it in /Apache/mod_perl/ directory mentioned above)

  use SOAP::Transport::HTTP;

  SOAP::Transport::HTTP::CGI
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
    -> handle
  ;

WARNING: dynamic deployment with Apache::Registry will fail, because module will be loaded dynamically only for the first time. After that it is already in the memory, that will bypass dynamic deployment and produces error about denied access. Specify both PATH/ and MODULE name in dispatch_to() and module will be loaded dynamically and then will work as under static deployment. See examples/server/soap.mod_cgi for example.

TROUBLESHOOTING

Dynamic libraries are not found

If you see in webserver's log file something like this:

Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so' for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl: libexpat.so.0 is NEEDED, but object does not exist at /usr/local/lib/perl5/.../DynaLoader.pm line 200.

and you are using Apache web server, try to put into your httpd.conf

 <IfModule mod_env.c>
     PassEnv LD_LIBRARY_PATH
 </IfModule>
Apache is crashing with segfaults (it may looks like "500 unexpected EOF before status line seen" on client side)

If using SOAP::Lite (or XML::Parser::Expat) in combination with mod_perl causes random segmentation faults in httpd processes try to configure Apache with:

 RULE_EXPAT=no

-- OR (for Apache 1.3.20 and later) --

 ./configure --disable-rule=EXPAT

See http://archive.covalent.net/modperl/2000/04/0185.xml for more details and lot of thanks to Robert Barta <rho@bigpond.net.au> for explaining this weird behavior.

If it doesn't help, you may also try -Uusemymalloc (or something like that) to get perl to use the system's own malloc. Thanks to Tim Bunce <Tim.Bunce@pobox.com>.

CGI scripts are not running under Microsoft Internet Information Server (IIS)

CGI scripts may not work under IIS unless scripts are .pl, not .cgi.

DEPENDENCIES

 Crypt::SSLeay             for HTTPS/SSL
 SOAP::Lite, URI           for SOAP::Transport::HTTP::Server
 LWP::UserAgent, URI       for SOAP::Transport::HTTP::Client
 HTTP::Daemon              for SOAP::Transport::HTTP::Daemon
 Apache, Apache::Constants for SOAP::Transport::HTTP::Apache

SEE ALSO

 See ::CGI, ::Daemon and ::Apache for implementation details.
 See examples/server/soap.cgi as SOAP::Transport::HTTP::CGI example.
 See examples/server/soap.daemon as SOAP::Transport::HTTP::Daemon example.
 See examples/My/Apache.pm as SOAP::Transport::HTTP::Apache example.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::IO - Server side IO support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::IO - Server side IO support for SOAP::Lite

SYNOPSIS

  use SOAP::Transport::IO;

  SOAP::Transport::IO::Server
    # you may specify as parameters for new():
    # -> new( in => 'in_file_name' [, out => 'out_file_name'] )
    # -> new( in => IN_HANDLE      [, out => OUT_HANDLE] )
    # -> new( in => *IN_HANDLE     [, out => *OUT_HANDLE] )
    # -> new( in => \*IN_HANDLE    [, out => \*OUT_HANDLE] )

    # -- OR --
    # any combinations
    # -> new( in => *STDIN, out => 'out_file_name' )
    # -> new( in => 'in_file_name', => \*OUT_HANDLE )

    # -- OR --
    # use in() and/or out() methods
    # -> in( *STDIN ) -> out( *STDOUT )

    # -- OR --
    # use default (when nothing specified):
    #      in => *STDIN, out => *STDOUT

    # don't forget, if you want to accept parameters from command line
    # \*HANDLER will be understood literally, so this syntax won't work
    # and server will complain

    -> new(@ARGV)
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
    -> handle
      ;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::JABBER - Server/Client side JABBER support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::JABBER - Server/Client side JABBER support for SOAP::Lite

SYNOPSIS

Client
  use SOAP::Lite
    uri => 'http://my.own.site.com/My/Examples',
    proxy => 'jabber://username:password@jabber.org:5222/soaplite_server@jabber.org/',
    #         proto    username passwd   server     port destination                resource (optional)
  ;

  print getStateName(1);
Server
  use SOAP::Transport::JABBER;

  my $server = SOAP::Transport::JABBER::Server
    -> new('jabber://username:password@jabber.org:5222')
    # specify list of objects-by-reference here
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;

  print "Contact to SOAP server\n";
  do { $server->handle } while sleep 10;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::LOCAL - Client side no-transport support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::LOCAL - Client side no-transport support for SOAP::Lite

SYNOPSIS

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::MAILTO - Client side SMTP/sendmail support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::MAILTO - Client side SMTP/sendmail support for SOAP::Lite

SYNOPSIS

  use SOAP::Lite;

  SOAP::Lite
    -> uri('http://soaplite.com/My/Examples')
    -> proxy('mailto:destination.email@address', smtp => 'smtp.server', From => 'your.email', Subject => 'SOAP message')
    # or
    # -> proxy('mailto:destination.email@address?From=your.email&Subject=SOAP%20message', smtp => 'smtp.server')

    # or if you want to send with sendmail
    # -> proxy('mailto:destination.email@address?From=your.email&Subject=SOAP%20message')

    # or if your sendmail is in undiscoverable place
    # -> proxy('mailto:destination.email@address?From=your.email&Subject=SOAP%20message', sendmail => 'command to run your sendmail')

    -> getStateName(12)
      ;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::MQ - Server/Client side MQ support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::MQ - Server/Client side MQ support for SOAP::Lite

SYNOPSIS

Client
  use SOAP::Lite
    uri => 'http://my.own.site.com/My/Examples',
    proxy => 'mq://server:port?Channel=CHAN1;QueueManager=QM_SOAP;RequestQueue=SOAPREQ1;ReplyQueue=SOAPRESP1',
  ;

  print getStateName(1);
Server
  use SOAP::Transport::MQ;

  my $server = SOAP::Transport::MQ::Server
    ->new('mq://server:port?Channel=CHAN1;QueueManager=QM_SOAP;RequestQueue=SOAPREQ1;ReplyQueue=SOAPRESP1')
    # specify list of objects-by-reference here
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;

  print "Contact to SOAP server\n";
  do { $server->handle } while sleep 1;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::POP3 - Server side POP3 support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::POP3 - Server side POP3 support for SOAP::Lite

SYNOPSIS

  use SOAP::Transport::POP3;

  my $server = SOAP::Transport::POP3::Server
    -> new('pop://pop.mail.server')
    # if you want to have all in one place
    # -> new('pop://user:password@pop.mail.server')
    # or, if you have server that supports MD5 protected passwords
    # -> new('pop://user:password;AUTH=+APOP@pop.mail.server')
    # specify list of objects-by-reference here
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  # you don't need to use next line if you specified your password in new()
  $server->login('user' => 'password') or die "Can't authenticate to POP3 server\n";

  # handle will return number of processed mails
  # you can organize loop if you want
  do { $server->handle } while sleep 10;

  # you may also call $server->quit explicitly to purge deleted messages

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


SOAP::Transport::TCP - Server/Client side TCP support for SOAP::Lite

  • COPYRIGHT
  • AUTHOR

NAME

SOAP::Transport::TCP - Server/Client side TCP support for SOAP::Lite

SYNOPSIS

  use SOAP::Transport::TCP;

  my $daemon = SOAP::Transport::TCP::Server
    -> new (LocalAddr => 'localhost', LocalPort => 82, Listen => 5, Reuse => 1)
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  print "Contact to SOAP server at ", join(':', $daemon->sockhost, $daemon->sockport), "\n";
  $daemon->handle;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


Safe - Compile and execute code in restricted compartments

  • WARNING
    • RECENT CHANGES
    • Methods in class Safe
    • Some Safety Issues
    • AUTHOR

NAME

Safe - Compile and execute code in restricted compartments

SYNOPSIS

  use Safe;

  $compartment = new Safe;

  $compartment->permit(qw(time sort :browse));

  $result = $compartment->reval($unsafe_code);

DESCRIPTION

The Safe extension module allows the creation of compartments in which perl code can be evaluated. Each compartment has

a new namespace

The "root" of the namespace (i.e. "main::") is changed to a different package and code evaluated in the compartment cannot refer to variables outside this namespace, even with run-time glob lookups and other tricks.

Code which is compiled outside the compartment can choose to place variables into (or share variables with) the compartment's namespace and only that data will be visible to code evaluated in the compartment.

By default, the only variables shared with compartments are the "underscore" variables $_ and @_ (and, technically, the less frequently used %_, the _ filehandle and so on). This is because otherwise perl operators which default to $_ will not work and neither will the assignment of arguments to @_ on subroutine entry.

an operator mask

Each compartment has an associated "operator mask". Recall that perl code is compiled into an internal format before execution. Evaluating perl code (e.g. via "eval" or "do 'file'") causes the code to be compiled into an internal format and then, provided there was no error in the compilation, executed. Code evaluated in a compartment compiles subject to the compartment's operator mask. Attempting to evaluate code in a compartment which contains a masked operator will cause the compilation to fail with an error. The code will not be executed.

The default operator mask for a newly created compartment is the ':default' optag.

It is important that you read the Opcode(3) module documentation for more information, especially for detailed definitions of opnames, optags and opsets.

Since it is only at the compilation stage that the operator mask applies, controlled access to potentially unsafe operations can be achieved by having a handle to a wrapper subroutine (written outside the compartment) placed into the compartment. For example,

    $cpt = new Safe;
    sub wrapper {
        # vet arguments and perform potentially unsafe operations
    }
    $cpt->share('&wrapper');

WARNING

The authors make no warranty, implied or otherwise, about the suitability of this software for safety or security purposes.

The authors shall not in any case be liable for special, incidental, consequential, indirect or other similar damages arising from the use of this software.

Your mileage will vary. If in any doubt do not use it.

RECENT CHANGES

The interface to the Safe module has changed quite dramatically since version 1 (as supplied with Perl5.002). Study these pages carefully if you have code written to use Safe version 1 because you will need to makes changes.

Methods in class Safe

To create a new compartment, use

    $cpt = new Safe;

Optional argument is (NAMESPACE), where NAMESPACE is the root namespace to use for the compartment (defaults to "Safe::Root0", incremented for each new compartment).

Note that version 1.00 of the Safe module supported a second optional parameter, MASK. That functionality has been withdrawn pending deeper consideration. Use the permit and deny methods described below.

The following methods can then be used on the compartment object returned by the above constructor. The object argument is implicit in each case.

permit (OP, ...)

Permit the listed operators to be used when compiling code in the compartment (in addition to any operators already permitted).

You can list opcodes by names, or use a tag name; see Predefined Opcode Tags in the Opcode manpage.

permit_only (OP, ...)

Permit only the listed operators to be used when compiling code in the compartment (no other operators are permitted).

deny (OP, ...)

Deny the listed operators from being used when compiling code in the compartment (other operators may still be permitted).

deny_only (OP, ...)

Deny only the listed operators from being used when compiling code in the compartment (all other operators will be permitted).

trap (OP, ...)
untrap (OP, ...)

The trap and untrap methods are synonyms for deny and permit respectfully.

share (NAME, ...)

This shares the variable(s) in the argument list with the compartment. This is almost identical to exporting variables using the the Exporter manpage module.

Each NAME must be the name of a non-lexical variable, typically with the leading type identifier included. A bareword is treated as a function name.

Examples of legal names are '$foo' for a scalar, '@foo' for an array, '%foo' for a hash, '&foo' or 'foo' for a subroutine and '*foo' for a glob (i.e. all symbol table entries associated with "foo", including scalar, array, hash, sub and filehandle).

Each NAME is assumed to be in the calling package. See share_from for an alternative method (which share uses).

share_from (PACKAGE, ARRAYREF)

This method is similar to share() but allows you to explicitly name the package that symbols should be shared from. The symbol names (including type characters) are supplied as an array reference.

    $safe->share_from('main', [ '$foo', '%bar', 'func' ]);
varglob (VARNAME)

This returns a glob reference for the symbol table entry of VARNAME in the package of the compartment. VARNAME must be the name of a variable without any leading type marker. For example,

    $cpt = new Safe 'Root';
    $Root::foo = "Hello world";
    # Equivalent version which doesn't need to know $cpt's package name:
    ${$cpt->varglob('foo')} = "Hello world";
reval (STRING)

This evaluates STRING as perl code inside the compartment.

The code can only see the compartment's namespace (as returned by the root method). The compartment's root package appears to be the main:: package to the code inside the compartment.

Any attempt by the code in STRING to use an operator which is not permitted by the compartment will cause an error (at run-time of the main program but at compile-time for the code in STRING). The error is of the form "'%s' trapped by operation mask...".

If an operation is trapped in this way, then the code in STRING will not be executed. If such a trapped operation occurs or any other compile-time or return error, then $@ is set to the error message, just as with an eval().

If there is no error, then the method returns the value of the last expression evaluated, or a return statement may be used, just as with subroutines and eval(). The context (list or scalar) is determined by the caller as usual.

This behaviour differs from the beta distribution of the Safe extension where earlier versions of perl made it hard to mimic the return behaviour of the eval() command and the context was always scalar.

Some points to note:

If the entereval op is permitted then the code can use eval "..." to 'hide' code which might use denied ops. This is not a major problem since when the code tries to execute the eval it will fail because the opmask is still in effect. However this technique would allow clever, and possibly harmful, code to 'probe' the boundaries of what is possible.

Any string eval which is executed by code executing in a compartment, or by code called from code executing in a compartment, will be eval'd in the namespace of the compartment. This is potentially a serious problem.

Consider a function foo() in package pkg compiled outside a compartment but shared with it. Assume the compartment has a root package called 'Root'. If foo() contains an eval statement like eval '$foo = 1' then, normally, $pkg::foo will be set to 1. If foo() is called from the compartment (by whatever means) then instead of setting $pkg::foo, the eval will actually set $Root::pkg::foo.

This can easily be demonstrated by using a module, such as the Socket module, which uses eval "..." as part of an AUTOLOAD function. You can 'use' the module outside the compartment and share an (autoloaded) function with the compartment. If an autoload is triggered by code in the compartment, or by any code anywhere that is called by any means from the compartment, then the eval in the Socket module's AUTOLOAD function happens in the namespace of the compartment. Any variables created or used by the eval'd code are now under the control of the code in the compartment.

A similar effect applies to all runtime symbol lookups in code called from a compartment but not compiled within it.

rdo (FILENAME)

This evaluates the contents of file FILENAME inside the compartment. See above documentation on the reval method for further details.

root (NAMESPACE)

This method returns the name of the package that is the root of the compartment's namespace.

Note that this behaviour differs from version 1.00 of the Safe module where the root module could be used to change the namespace. That functionality has been withdrawn pending deeper consideration.

mask (MASK)

This is a get-or-set method for the compartment's operator mask.

With no MASK argument present, it returns the current operator mask of the compartment.

With the MASK argument present, it sets the operator mask for the compartment (equivalent to calling the deny_only method).

Some Safety Issues

This section is currently just an outline of some of the things code in a compartment might do (intentionally or unintentionally) which can have an effect outside the compartment.

Memory

Consuming all (or nearly all) available memory.

CPU

Causing infinite loops etc.

Snooping

Copying private information out of your system. Even something as simple as your user name is of value to others. Much useful information could be gleaned from your environment variables for example.

Signals

Causing signals (especially SIGFPE and SIGALARM) to affect your process.

Setting up a signal handler will need to be carefully considered and controlled. What mask is in effect when a signal handler gets called? If a user can get an imported function to get an exception and call the user's signal handler, does that user's restricted mask get re-instated before the handler is called? Does an imported handler get called with its original mask or the user's one?

State Changes

Ops such as chdir obviously effect the process as a whole and not just the code in the compartment. Ops such as rand and srand have a similar but more subtle effect.

AUTHOR

Originally designed and implemented by Malcolm Beattie, mbeattie@sable.ox.ac.uk.

Reworked to use the Opcode module and other changes added by Tim Bunce <Tim.Bunce@ig.co.uk>.


Scalar::Util - A selection of general-utility scalar subroutines

  • KNOWN BUGS
  • COPYRIGHT
  • BLATANT PLUG

NAME

Scalar::Util - A selection of general-utility scalar subroutines

SYNOPSIS

    use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
                        weaken isvstring looks_like_number set_prototype);

DESCRIPTION

Scalar::Util contains a selection of subroutines that people have expressed would be nice to have in the perl core, but the usage would not really be high enough to warrant the use of a keyword, and the size so small such that being individual extensions would be wasteful.

By default Scalar::Util does not export any subroutines. The subroutines defined are

blessed EXPR

If EXPR evaluates to a blessed reference the name of the package that it is blessed into is returned. Otherwise undef is returned.

   $scalar = "foo";
   $class  = blessed $scalar;           # undef

   $ref    = [];
   $class  = blessed $ref;              # undef

   $obj    = bless [], "Foo";
   $class  = blessed $obj;              # "Foo"
dualvar NUM, STRING

Returns a scalar that has the value NUM in a numeric context and the value STRING in a string context.

    $foo = dualvar 10, "Hello";
    $num = $foo + 2;                    # 12
    $str = $foo . " world";             # Hello world
isvstring EXPR

If EXPR is a scalar which was coded as a vstring the result is true.

    $vs   = v49.46.48;
    $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
    printf($fmt,$vs);
isweak EXPR

If EXPR is a scalar which is a weak reference the result is true.

    $ref  = \$foo;
    $weak = isweak($ref);               # false
    weaken($ref);
    $weak = isweak($ref);               # true

NOTE: Copying a weak reference creates a normal, strong, reference.

    $copy = $ref;
    $weak = isweak($ref);               # false
looks_like_number EXPR

Returns true if perl thinks EXPR is a number. See looks_like_number in the perlapi manpage.

openhandle FH

Returns FH if FH may be used as a filehandle and is open, or FH is a tied handle. Otherwise undef is returned.

    $fh = openhandle(*STDIN);           # \*STDIN
    $fh = openhandle(\*STDIN);          # \*STDIN
    $fh = openhandle(*NOTOPEN);         # undef
    $fh = openhandle("scalar");         # undef

    =item readonly SCALAR

Returns true if SCALAR is readonly.

    sub foo { readonly($_[0]) }

    $readonly = foo($bar);              # false
    $readonly = foo(0);                 # true
refaddr EXPR

If EXPR evaluates to a reference the internal memory address of the referenced value is returned. Otherwise undef is returned.

    $addr = refaddr "string";           # undef
    $addr = refaddr \$var;              # eg 12345678
    $addr = refaddr [];                 # eg 23456784

    $obj  = bless {}, "Foo";
    $addr = refaddr $obj;               # eg 88123488
reftype EXPR

If EXPR evaluates to a reference the type of the variable referenced is returned. Otherwise undef is returned.

    $type = reftype "string";           # undef
    $type = reftype \$var;              # SCALAR
    $type = reftype [];                 # ARRAY

    $obj  = bless {}, "Foo";
    $type = reftype $obj;               # HASH
set_prototype CODEREF, PROTOTYPE

Sets the prototype of the given function, or deletes it if PROTOTYPE is undef. Returns the CODEREF.

    set_prototype \&foo, '$$';
tainted EXPR

Return true if the result of EXPR is tainted

    $taint = tainted("constant");       # false
    $taint = tainted($ENV{PWD});        # true if running under -T
weaken REF

REF will be turned into a weak reference. This means that it will not hold a reference count on the object it references. Also when the reference count on that object reaches zero, REF will be set to undef.

This is useful for keeping copies of references , but you don't want to prevent the object being DESTROY-ed at its usual time.

    {
      my $var;
      $ref = \$var;
      weaken($ref);                     # Make $ref a weak reference
    }
    # $ref is now undef

Note that if you take a copy of a scalar with a weakened reference, the copy will be a strong reference.

    my $var;
    my $foo = \$var;
    weaken($foo);                       # Make $foo a weak reference
    my $bar = $foo;                     # $bar is now a strong reference

This may be less obvious in other situations, such as grep(), for instance when grepping through a list of weakened references to objects that may have been destroyed already:

    @object = grep { defined } @object;

This will indeed remove all references to destroyed objects, but the remaining references to objects will be strong, causing the remaining objects to never be destroyed because there is now always a strong reference to them in the @object array.

KNOWN BUGS

There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show up as tests 8 and 9 of dualvar.t failing

COPYRIGHT

Copyright (c) 1997-2005 Graham Barr <gbarr@pobox.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Except weaken and isweak which are

Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as perl itself.

BLATANT PLUG

The weaken and isweak subroutines in this module and the patch to the core Perl were written in connection with the APress book `Tuomas J. Lukka's Definitive Guide to Object-Oriented Programming in Perl', to avoid explaining why certain things would have to be done in cumbersome ways.


look - search for key in dictionary file

NAME

Search::Dict, look - search for key in dictionary file

SYNOPSIS

    use Search::Dict;
    look *FILEHANDLE, $key, $dict, $fold;

    use Search::Dict;
    look *FILEHANDLE, $params;

DESCRIPTION

Sets file position in FILEHANDLE to be first line greater than or equal (stringwise) to $key. Returns the new file position, or -1 if an error occurs.

The flags specify dictionary order and case folding:

If $dict is true, search by dictionary order (ignore anything but word characters and whitespace). The default is honour all characters.

If $fold is true, ignore case. The default is to honour case.

If there are only three arguments and the third argument is a hash reference, the keys of that hash can have values dict, fold, and comp or xfrm (see below), and their correponding values will be used as the parameters.

If a comparison subroutine (comp) is defined, it must return less than zero, zero, or greater than zero, if the first comparand is less than, equal, or greater than the second comparand.

If a transformation subroutine (xfrm) is defined, its value is used to transform the lines read from the filehandle before their comparison.


SelectSaver - save and restore selected file handle

NAME

SelectSaver - save and restore selected file handle

SYNOPSIS

    use SelectSaver;

    {
       my $saver = new SelectSaver(FILEHANDLE);
       # FILEHANDLE is selected
    }
    # previous handle is selected

    {
       my $saver = new SelectSaver;
       # new handle may be selected, or not
    }
    # previous handle is selected

DESCRIPTION

A SelectSaver object contains a reference to the file handle that was selected when it was created. If its new method gets an extra parameter, then that parameter is selected; otherwise, the selected file handle remains unchanged.

When a SelectSaver is destroyed, it re-selects the file handle that was selected when it was created.


SelfLoader - load functions only on demand

    • The __DATA__ token
    • SelfLoader autoloading
    • Autoloading and package lexicals
    • SelfLoader and AutoLoader
    • __DATA__, __END__, and the FOOBAR::DATA filehandle.
    • Classes and inherited methods.
  • Multiple packages and fully qualified subroutine names

NAME

SelfLoader - load functions only on demand

SYNOPSIS

    package FOOBAR;
    use SelfLoader;

    ... (initializing code)
    __DATA__
    sub {....

DESCRIPTION

This module tells its users that functions in the FOOBAR package are to be autoloaded from after the __DATA__ token. See also Autoloading in the perlsub manpage.

The __DATA__ token

The __DATA__ token tells the perl compiler that the perl code for compilation is finished. Everything after the __DATA__ token is available for reading via the filehandle FOOBAR::DATA, where FOOBAR is the name of the current package when the __DATA__ token is reached. This works just the same as __END__ does in package 'main', but for other modules data after __END__ is not automatically retrievable, whereas data after __DATA__ is. The __DATA__ token is not recognized in versions of perl prior to 5.001m.

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. This also applies to __END__ and main, i.e. if the 'main' program has an __END__, but a module 'require'd (_not_ 'use'd) by that program has a 'package main;' declaration followed by an '__DATA__', then the DATA filehandle is set to access the data after the __DATA__ in the module, _not_ the data after the __END__ token in the 'main' program, since the compiler encounters the 'require'd file later.

SelfLoader autoloading

The SelfLoader works by the user placing the __DATA__ token after perl code which needs to be compiled and run at 'require' time, but before subroutine declarations that can be loaded in later - usually because they may never be called.

The SelfLoader will read from the FOOBAR::DATA filehandle to load in the data after __DATA__, and load in any subroutine when it is 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 (hopefully) are a speeded up compilation phase, with no need to load functions which are never used.

The SelfLoader will stop reading from __DATA__ if it encounters the __END__ token - just as you would expect. If the __END__ token is present, and is followed by the token DATA, then the SelfLoader leaves the FOOBAR::DATA filehandle open on the line after that token.

The SelfLoader exports the AUTOLOAD subroutine to the package using the SelfLoader, and this loads the called subroutine when it is first called.

There is no advantage to putting subroutines which will _always_ be called after the __DATA__ token.

Autoloading and package lexicals

A 'my $pack_lexical' statement makes the variable $pack_lexical local _only_ to the file up to the __DATA__ token. Subroutines declared elsewhere _cannot_ see these types of variables, just as if you declared subroutines in the package but in another file, they cannot see these variables.

So specifically, autoloaded functions cannot see package lexicals (this applies to both the SelfLoader and the Autoloader). The vars pragma provides an alternative to defining package-level globals that will be visible to autoloaded routines. See the documentation on vars in the pragma section of the perlmod manpage.

SelfLoader and AutoLoader

The SelfLoader can replace the AutoLoader - just change 'use AutoLoader' to 'use SelfLoader' (though note that the SelfLoader exports the AUTOLOAD function - but if you have your own AUTOLOAD and are using the AutoLoader too, you probably know what you're doing), and the __END__ token to __DATA__. You will need perl version 5.001m or later to use this (version 5.001 with all patches up to patch m).

There is no need to inherit from the SelfLoader.

The SelfLoader works similarly to the AutoLoader, but picks up the subs from after the __DATA__ instead of in the 'lib/auto' directory. There is a maintenance gain in not needing to run AutoSplit on the module at installation, and a runtime gain in not needing to keep opening and closing files to load subs. There is a runtime loss in needing 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.

__DATA__, __END__, and the FOOBAR::DATA filehandle.

This section is only relevant if you want to use the FOOBAR::DATA together with the SelfLoader.

Data after the __DATA__ token in a module is read using the FOOBAR::DATA filehandle. __END__ can still be used to denote the end of the __DATA__ section if followed by the token DATA - this is supported by the SelfLoader. The FOOBAR::DATA filehandle is left open if an __END__ followed by a DATA is found, with the filehandle positioned at the start of the line after the __END__ token. If no __END__ token is present, or an __END__ token with no DATA token on the same line, then the filehandle is closed.

The SelfLoader reads from wherever the current position of the FOOBAR::DATA filehandle is, until the EOF or __END__. This means that if you want to use that filehandle (and ONLY if you want to), you should either

1. Put all your subroutine declarations immediately after the __DATA__ token and put your own data after those declarations, using the __END__ token to mark the end of subroutine declarations. You must also ensure that the SelfLoader reads first by calling 'SelfLoader->load_stubs();', or by using a function which is selfloaded;

or

2. You should read the FOOBAR::DATA filehandle first, leaving the handle open and positioned at the first line of subroutine declarations.

You could conceivably do both.

Classes and inherited methods.

For modules which are not classes, this section is not relevant. This section is only relevant if you have methods which could be inherited.

A subroutine stub (or forward declaration) looks like

  sub stub;

i.e. it is a subroutine declaration without the body of the subroutine. For modules which are not classes, there is no real need for stubs as far as autoloading is concerned.

For modules which 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 'SelfLoader->load_stubs();' to the module to do this.

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 this is done I strongly recommend that this is done BEFORE releasing the module - it should NOT be done at install time in general.

Multiple packages and fully qualified subroutine names

Subroutines in multiple packages within the same file are supported - but you should note that this requires exporting the 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 the __DATA__ by putting a 'use SelfLoader' statement in each package.

Fully qualified subroutine names are also supported. For example,

   __DATA__
   sub foo::bar {23}
   package baz;
   sub dob {32}

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.


Shell - run shell commands transparently within perl

    • Caveats
    • Escaping Magic Characters
    • Configuration
  • BUGS
  • AUTHOR

NAME

Shell - run shell commands transparently within perl

SYNOPSIS

   use Shell qw(cat ps cp);
   $passwd = cat('</etc/passwd');
   @pslines = ps('-ww'),
   cp("/etc/passwd", "/tmp/passwd");

   # object oriented
   my $sh = Shell->new;
   print $sh->ls('-l');

DESCRIPTION

Caveats

This package is included as a show case, illustrating a few Perl features. It shouldn't be used for production programs. Although it does provide a simple interface for obtaining the standard output of arbitrary commands, there may be better ways of achieving what you need.

Running shell commands while obtaining standard output can be done with the qx/STRING/ operator, or by calling open with a filename expression that ends with |, giving you the option to process one line at a time. If you don't need to process standard output at all, you might use system (in preference of doing a print with the collected standard output).

Since Shell.pm and all of the aforementioned techniques use your system's shell to call some local command, none of them is portable across different systems. Note, however, that there are several built in functions and library packages providing portable implementations of functions operating on files, such as: glob, link and unlink, mkdir and rmdir, rename, File::Compare, File::Copy, File::Find etc.

Using Shell.pm while importing foo creates a subroutine foo in the namespace of the importing package. Calling foo with arguments arg1, arg2,... results in a shell command foo arg1 arg2..., where the function name and the arguments are joined with a blank. (See the subsection on Escaping magic characters.) Since the result is essentially a command line to be passed to the shell, your notion of arguments to the Perl function is not necessarily identical to what the shell treats as a command line token, to be passed as an individual argument to the program. Furthermore, note that this implies that foo is callable by file name only, which frequently depends on the setting of the program's environment.

Creating a Shell object gives you the opportunity to call any command in the usual OO notation without requiring you to announce it in the use Shell statement. Don't assume any additional semantics being associated with a Shell object: in no way is it similar to a shell process with its environment or current working directory or any other setting.

Escaping Magic Characters

It is, in general, impossible to take care of quoting the shell's magic characters. For some obscure reason, however, Shell.pm quotes apostrophes (') and backslashes (\) on UNIX, and spaces and quotes (") on Windows.

Configuration

If you set $Shell::capture_stderr to true, the module will attempt to capture the standard error output of the process as well. This is done by adding 2>&1 to the command line, so don't try this on a system not supporting this redirection.

If you set $Shell::raw to true no quoting whatsoever is done.

BUGS

Quoting should be off by default.

It isn't possible to call shell built in commands, but it can be done by using a workaround, e.g. shell( '-c', 'set' ).

Capturing standard error does not work on some systems (e.g. VMS).

AUTHOR

  Date: Thu, 22 Sep 94 16:18:16 -0700
  Message-Id: <9409222318.AA17072@scalpel.netlabs.com>
  To: perl5-porters@isu.edu
  From: Larry Wall <lwall@scalpel.netlabs.com>
  Subject: a new module I just wrote

Here's one that'll whack your mind a little out.

    #!/usr/bin/perl

    use Shell;

    $foo = echo("howdy", "<funny>", "world");
    print $foo;

    $passwd = cat("</etc/passwd");
    print $passwd;

    sub ps;
    print ps -ww;

    cp("/etc/passwd", "/etc/passwd.orig");

That's maybe too gonzo. It actually exports an AUTOLOAD to the current package (and uncovered a bug in Beta 3, by the way). Maybe the usual usage should be

    use Shell qw(echo cat ps cp);

Larry Wall

Changes by Jenda@Krynicky.cz and Dave Cottle <d.cottle@csc.canterbury.ac.nz>.

Changes for OO syntax and bug fixes by Casey West <casey@geeknest.com>.

$Shell::raw and pod rewrite by Wolfgang Laun.


Smart::Comments - Comments that do more than just sit there

  • VERSION
  • SYNOPSIS
  • INTERFACE
    • Using the Module
    • Debugging via Comments
    • Checks and Assertions via Comments
    • Progress Bars
    • Time-Remaining Estimates
  • DIAGNOSTICS
  • CONFIGURATION AND ENVIRONMENT
  • DEPENDENCIES
  • INCOMPATIBILITIES
  • BUGS AND LIMITATIONS
  • AUTHOR
  • LICENCE AND COPYRIGHT
  • DISCLAIMER OF WARRANTY

NAME

Smart::Comments - Comments that do more than just sit there

VERSION

This document describes Smart::Comments version 1.0.2

SYNOPSIS

    use Smart::Comments;

    my $var = suspect_value();

    ### $var

    ### got: $var

    ### Now computing value...

    # and when looping:

    for my $big_num (@big_nums) {  ### Factoring...      done
        factor($big_num);
    }

    while ($error > $tolerance) {  ### Refining--->      done
        refine_approximation()
    }

    for (my $i=0; $i<$MAX_INT; $i++) {   ### Working===[%]     done
        do_something_expensive_with($i);
    }

=head1 DESCRIPTION

Smart comments provide an easy way to insert debugging and tracking code into a program. They can report the value of a variable, track the progress of a loop, and verify that particular assertions are true.

Best of all, when you're finished debugging, you don't have to remove them. Simply commenting out the use Smart::Comments line turns them back into regular comments. Leaving smart comments in your code is smart because if you needed them once, you'll almost certainly need them again later.

INTERFACE

All smart comments start with three (or more) # characters. That is, they are regular #-introduced comments whose first two (or more) characters are also #'s.

Using the Module

The module is loaded like any other:

    use Smart::Comments;

When loaded it filters the remaining code up to the next:

    no Smart::Comments;

directive, replacing any smart comments with smart code that implements the comments behaviour.

You can also specify particular levels of smartness, by including one or more markers as arguments to the use:

    use Smart::Comments '###', '####';

These arguments tell the module to filter only those comments that start with the same number of #'s. So the above use statement would "activate" any smart comments of the form:

    ###   Smart...

    ####  Smarter...

but not those of the form:

    ##### Smartest...

This facility is useful for differentiating progress bars (see Progress Bars), which should always be active, from debugging comments (see Debugging via Comments), which should not:

    #### Debugging here...

    for (@values) {         ### Progress: 0...  100
        do_stuff();
    }

Note that, for simplicity, all smart comments described below will be written with three #'s; in all such cases, any number of #'s greater than three could be used instead.

Debugging via Comments

The simplest way to use smart comments is for debugging. The module supports the following forms, all of which print to STDERR:

### LABEL : EXPRESSION

The LABEL is any sequence of characters up to the first colon. The EXPRESSION is any valid Perl expression, including a simple variable. When active, the comment prints the label, followed by the value of the expression. For example:

    ### Expected: 2 * $prediction
    ###      Got: $result

prints:

    ### Expected: 42
    ###      Got: 13
### EXPRESSION

The EXPRESSION is any valid Perl expression, including a simple variable. When active, the comment prints the expression, followed by the value of the expression. For example:

    ### 2 * $prediction
    ### $result

prints:

    ### 2 * $prediction: 42
    ### $result: 13
### TEXT...

The TEXT is any sequence of characters that end in three dots. When active, the comment just prints the text, including the dots. For example:

    ### Acquiring data...

    $data = get_data();

    ### Verifying data...

    verify_data($data);

    ### Assimilating data...

    assimilate_data($data);

    ### Tired now, having a little lie down...

    sleep 900;

would print:

    ### Acquiring data...

    ### Verifying data...

    ### Assimilating data...

    ### Tired now, having a little lie down...

as each phase commenced. This is particularly useful for tracking down precisely where a bug is occurring. It is also useful in non-debugging situations, especially when batch processing, as a simple progress feedback mechanism.

Within a textual smart comment you can use the special sequence < <now >> (or <time> or <when>) which is replaced with a timestamp. For example:

    ### [<now>] Acquiring data...

would produce something like:

    ### [Fri Nov 18 15:11:15 EST 2005] Acquiring data...

There are also "spacestamps": <here> (or <line> or < <loc >> or <place> or <where>):

    ### Acquiring data at <loc>...

to produce something like:

    ### Acquiring data at "demo.pl", line 7...

You can, of course, use both in the same comment as well.

Checks and Assertions via Comments

### require: BOOLEAN_EXPR
### assert: BOOLEAN_EXPR
### ensure: BOOLEAN_EXPR
### insist: BOOLEAN_EXPR

These four are synonyms for the same behaviour. The comment evaluates the expression in a boolean context. If the result is true, nothing more is done. If the result is false, the comment throws an exception listing the expression, the fact that it failed, and the values of any variables used in the expression.

For example, given the following assertion:

    ### require: $min < $result && $result < $max

if the expression evaluated false, the comment would die with the following message:

    ### $min < $result && $result < $max was not true at demo.pl line 86.
    ###     $min was: 7
    ###     $result was: 1000004
    ###     $max was: 99
### check: BOOLEAN_EXPR
### confirm: BOOLEAN_EXPR
### verify: BOOLEAN_EXPR

These three are synonyms for the same behaviour. The comment evaluates the expression in a boolean context. If the result is true, nothing more is done. If the result is false, the comment prints a warning message listing the expression, the fact that it failed, and the values of any variables used in the expression.

The effect is identical to that of the four assertions listed earlier, except that warn is used instead of die.

Progress Bars

You can put a smart comment on the same line as any of the following types of Perl loop:

    foreach my VAR ( LIST ) {       ### Progressing...   done

    for my VAR ( LIST ) {           ### Progressing...   done

    foreach ( LIST ) {              ### Progressing...   done

    for ( LIST ) {                  ### Progressing...   done

    while (CONDITION) {             ### Progressing...   done

    until (CONDITION) {             ### Progressing...   done

    for (INIT; CONDITION; INCR) {   ### Progressing...   done

In each case, the module animates the comment, causing the dots to extend from the left text, reaching the right text on the last iteration. For "open ended" loops (like while and C-style for loops), the dots will never reach the right text and their progress slows down as the number of iterations increases.

For example, a smart comment like:

    for (@candidates) {       ### Evaluating...     done

would be animated is the following sequence (which would appear sequentially on a single line, rather than on consecutive lines):

    Evaluating                          done
    Evaluating......                    done
    Evaluating.............             done
    Evaluating...................       done
    Evaluating..........................done

The module animates the first sequence of three identical characters in the comment, provided those characters are followed by a gap of at least two whitespace characters. So you can specify different types of progress bars. For example:

    for (@candidates) {       ### Evaluating:::     done

or:

    for (@candidates) {       ### Evaluating===     done

or:

    for (@candidates) {       ### Evaluating|||     done

If the characters to be animated are immediately followed by other non-whitespace characters before the gap, then those other non-whitespace characters are used as an "arrow head" or "leader" and are pushed right by the growing progress bar. For example:

    for (@candidates) {       ### Evaluating===|    done

would animate like so:

    Evaluating|                         done
    Evaluating=====|                    done
    Evaluating============|             done
    Evaluating==================|       done
    Evaluating==========================done

If a percentage character (%) appears anywhere in the comment, it is replaced by the percentage completion. For example:

    for (@candidates) {       ### Evaluating [===|    ] % done

animates like so:

    Evaluating [|                ]   0% done
    Evaluating [===|             ]  25% done
    Evaluating [========|        ]  50% done
    Evaluating [============|    ]  75% done
    Evaluating [=================] 100% done

If the % is in the "arrow head" it moves with the progress bar. For example:

    for (@candidates) {       ### Evaluating |===[%]    |

would be aninated like so:

    Evaluating |[0%]                       |
    Evaluating |=[25%]                     |
    Evaluating |========[50%]              |
    Evaluating |===============[75%]       |
    Evaluating |===========================|

For "open-ended" loops, the percentage completion is unknown, so the module replaces each % with the current iteration count. For example:

    while ($next ne $target) {       ### Evaluating |===[%]    |

would animate like so:

    Evaluating |[0]                        |
    Evaluating |=[2]                       |
    Evaluating |==[3]                      |
    Evaluating |===[5]                     |
    Evaluating |====[7]                    |
    Evaluating |=====[8]                   |
    Evaluating |======[11]                 |

Note that the non-sequential numbering in the above example is a result of the "hurry up and slow down" algorithm that prevents open-ended loops from ever reaching the right-hand side.

As a special case, if the progress bar is drawn as two pairs of identical brackets:

    for (@candidates) {       ### Evaluating: [][]

    for (@candidates) {       ### Evaluating: {}{}

    for (@candidates) {       ### Evaluating: ()()

    for (@candidates) {       ### Evaluating: <><>

Then the bar grows by repeating bracket pairs:

    Evaluating: [
    Evaluating: []
    Evaluating: [][
    Evaluating: [][]
    Evaluating: [][][

etc.

Finally, progress bars don't have to have an animated component. They can just report the loop's progress numerically:

    for (@candidates) {       ### Evaluating (% done)

which would animate (all of the same line):

    Evaluating (0% done)
    Evaluating (25% done)
    Evaluating (50% done)
    Evaluating (75% done)
    Evaluating (100% done)

Time-Remaining Estimates

When a progress bar is used with a for loop, the module tracks how long each iteration is taking and makes an estimate of how much time will be required to complete the entire loop.

Normally this estimate is not shown, unless the estimate becomes large enough to warrant informing the user. Specifically, the estimate will be shown if, after five seconds, the time remaining exceeds ten seconds. In other words, a time-remaining estimate is shown if the module detects a for loop that is likely to take more than 15 seconds in total. For example:

    for (@seven_samurai) {      ### Fighting: [|||    ]
        fight();
        sleep 5;
    }

would be animated like so:

    Fighting: [                           ]
    Fighting: [||||                       ]
    Fighting: [|||||||||                  ]  (about 20 seconds remaining)
    Fighting: [||||||||||||||             ]  (about 20 seconds remaining)
    Fighting: [||||||||||||||||||         ]  (about 10 seconds remaining)
    Fighting: [|||||||||||||||||||||||    ]  (less than 10 seconds remaining)
    Fighting: [|||||||||||||||||||||||||||]

The precision of the reported time-remaining estimate is deliberately vague, mainly to prevent it being annoyingly wrong.

DIAGNOSTICS

In a sense, everything this module does is a diagnostic. All comments that print anything, print it to STDERR.

However, the module itself has only one diagnostic:

Incomprehensible arguments: %s in call to 'use Smart::Comments

You loaded the module and passed it an argument that wasn't three-or- more #'s. Arguments like '###', '####', '#####', etc. are the only ones that the module accepts.

CONFIGURATION AND ENVIRONMENT

Smart::Comments requires no configuration files or environment variables.

DEPENDENCIES

The module requires the following modules:

  • Filter::Simple

  • version.pm

  • List::Util

  • Data::Dumper

  • Text::Balanced

INCOMPATIBILITIES

None reported. This module is probably even relatively safe with other Filter::Simple modules since it is very specific and limited in what it filters.

BUGS AND LIMITATIONS

No bugs have been reported.

This module has the usual limitations of source filters (i.e. it looks smarter than it is).

Please report any bugs or feature requests to bug-smart-comments@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Damian Conway <DCONWAY@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2005, Damian Conway <DCONWAY@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


inet_ntoa - load the C socket.h defines and structure manipulators

NAME

Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators

SYNOPSIS

    use Socket;

    $proto = getprotobyname('udp');
    socket(Socket_Handle, PF_INET, SOCK_DGRAM, $proto);
    $iaddr = gethostbyname('hishost.com');
    $port = getservbyname('time', 'udp');
    $sin = sockaddr_in($port, $iaddr);
    send(Socket_Handle, 0, 0, $sin);

    $proto = getprotobyname('tcp');
    socket(Socket_Handle, PF_INET, SOCK_STREAM, $proto);
    $port = getservbyname('smtp', 'tcp');
    $sin = sockaddr_in($port,inet_aton("127.1"));
    $sin = sockaddr_in(7,inet_aton("localhost"));
    $sin = sockaddr_in(7,INADDR_LOOPBACK);
    connect(Socket_Handle,$sin);

    ($port, $iaddr) = sockaddr_in(getpeername(Socket_Handle));
    $peer_host = gethostbyaddr($iaddr, AF_INET);
    $peer_addr = inet_ntoa($iaddr);

    $proto = getprotobyname('tcp');
    socket(Socket_Handle, PF_UNIX, SOCK_STREAM, $proto);
    unlink('/var/run/usock');
    $sun = sockaddr_un('/var/run/usock');
    connect(Socket_Handle,$sun);

DESCRIPTION

This module is just a translation of the C socket.h file. Unlike the old mechanism of requiring a translated socket.ph file, this uses the h2xs program (see the Perl source distribution) and your native C compiler. This means that it has a far more likely chance of getting the numbers right. This includes all of the commonly used pound-defines like AF_INET, SOCK_STREAM, etc.

Also, some common socket "newline" constants are provided: the constants CR, LF, and CRLF, as well as $CR, $LF, and $CRLF, which map to \015, \012, and \015\012. If you do not want to use the literal characters in your programs, then use the constants provided here. They are not exported by default, but can be imported individually, and with the :crlf export tag:

    use Socket qw(:DEFAULT :crlf);

In addition, some structure manipulation functions are available:

inet_aton HOSTNAME

Takes a string giving the name of a host, and translates that to an opaque string (if programming in C, struct in_addr). Takes arguments of both the 'rtfm.mit.edu' type and '18.181.0.24'. If the host name cannot be resolved, returns undef. For multi-homed hosts (hosts with more than one address), the first address found is returned.

For portability do not assume that the result of inet_aton() is 32 bits wide, in other words, that it would contain only the IPv4 address in network order.

inet_ntoa IP_ADDRESS

Takes a string (an opaque string as returned by inet_aton(), or a v-string representing the four octets of the IPv4 address in network order) and translates it into a string of the form 'd.d.d.d' where the 'd's are numbers less than 256 (the normal human-readable four dotted number notation for Internet addresses).

INADDR_ANY

Note: does not return a number, but a packed string.

Returns the 4-byte wildcard ip address which specifies any of the hosts ip addresses. (A particular machine can have more than one ip address, each address corresponding to a particular network interface. This wildcard address allows you to bind to all of them simultaneously.) Normally equivalent to inet_aton('0.0.0.0').

INADDR_BROADCAST

Note: does not return a number, but a packed string.

Returns the 4-byte 'this-lan' ip broadcast address. This can be useful for some protocols to solicit information from all servers on the same LAN cable. Normally equivalent to inet_aton('255.255.255.255').

INADDR_LOOPBACK

Note - does not return a number.

Returns the 4-byte loopback address. Normally equivalent to inet_aton('localhost').

INADDR_NONE

Note - does not return a number.

Returns the 4-byte 'invalid' ip address. Normally equivalent to inet_aton('255.255.255.255').

sockaddr_family SOCKADDR

Takes a sockaddr structure (as returned by pack_sockaddr_in(), pack_sockaddr_un() or the perl builtin functions getsockname() and getpeername()) and returns the address family tag. It will match the constant AF_INET for a sockaddr_in and AF_UNIX for a sockaddr_un. It can be used to figure out what unpacker to use for a sockaddr of unknown type.

sockaddr_in PORT, ADDRESS
sockaddr_in SOCKADDR_IN

In a list context, unpacks its SOCKADDR_IN argument and returns an array consisting of (PORT, ADDRESS). In a scalar context, packs its (PORT, ADDRESS) arguments as a SOCKADDR_IN and returns it. If this is confusing, use pack_sockaddr_in() and unpack_sockaddr_in() explicitly.

pack_sockaddr_in PORT, IP_ADDRESS

Takes two arguments, a port number and an opaque string, IP_ADDRESS (as returned by inet_aton(), or a v-string). Returns the sockaddr_in structure with those arguments packed in with AF_INET filled in. For Internet domain sockets, this structure is normally what you need for the arguments in bind(), connect(), and send(), and is also returned by getpeername(), getsockname() and recv().

unpack_sockaddr_in SOCKADDR_IN

Takes a sockaddr_in structure (as returned by pack_sockaddr_in()) and returns an array of two elements: the port and an opaque string representing the IP address (you can use inet_ntoa() to convert the address to the four-dotted numeric format). Will croak if the structure does not have AF_INET in the right place.

sockaddr_un PATHNAME
sockaddr_un SOCKADDR_UN

In a list context, unpacks its SOCKADDR_UN argument and returns an array consisting of (PATHNAME). In a scalar context, packs its PATHNAME arguments as a SOCKADDR_UN and returns it. If this is confusing, use pack_sockaddr_un() and unpack_sockaddr_un() explicitly. These are only supported if your system has <sys/un.h>.

pack_sockaddr_un PATH

Takes one argument, a pathname. Returns the sockaddr_un structure with that path packed in with AF_UNIX filled in. For unix domain sockets, this structure is normally what you need for the arguments in bind(), connect(), and send(), and is also returned by getpeername(), getsockname() and recv().

unpack_sockaddr_un SOCKADDR_UN

Takes a sockaddr_un structure (as returned by pack_sockaddr_un()) and returns the pathname. Will croak if the structure does not have AF_UNIX in the right place.


Storable - persistence for Perl data structures

  • MEMORY STORE
  • ADVISORY LOCKING
  • SPEED
  • CANONICAL REPRESENTATION
  • CODE REFERENCES
  • FORWARD COMPATIBILITY
  • ERROR REPORTING
  • WIZARDS ONLY
    • Hooks
    • Predicates
    • Recursion
    • Deep Cloning
  • Storable magic
  • EXAMPLES
  • WARNING
  • BUGS
    • 64 bit data in perl 5.6.0 and 5.6.1
  • CREDITS
  • AUTHOR
  • SEE ALSO

NAME

Storable - persistence for Perl data structures

SYNOPSIS

 use Storable;
 store \%table, 'file';
 $hashref = retrieve('file');

 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);

 # Network order
 nstore \%table, 'file';
 $hashref = retrieve('file');   # There is NO nretrieve()

 # Storing to and retrieving from an already opened file
 store_fd \@array, \*STDOUT;
 nstore_fd \%table, \*STDOUT;
 $aryref = fd_retrieve(\*SOCKET);
 $hashref = fd_retrieve(\*SOCKET);

 # Serializing to memory
 $serialized = freeze \%table;
 %table_clone = %{ thaw($serialized) };

 # Deep (recursive) cloning
 $cloneref = dclone($ref);

 # Advisory locking
 use Storable qw(lock_store lock_nstore lock_retrieve)
 lock_store \%table, 'file';
 lock_nstore \%table, 'file';
 $hashref = lock_retrieve('file');

DESCRIPTION

The Storable package brings persistence to your Perl data structures containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be conveniently stored to disk and retrieved at a later time.

It can be used in the regular procedural way by calling store with a reference to the object to be stored, along with the file name where the image should be written.

The routine returns undef for I/O problems or other internal error, a true value otherwise. Serious errors are propagated as a die exception.

To retrieve data stored to disk, use retrieve with a file name. The objects stored into that file are recreated into memory for you, and a reference to the root object is returned. In case an I/O error occurs while reading, undef is returned instead. Other serious errors are propagated via die.

Since storage is performed recursively, you might want to stuff references to objects that share a lot of common data into a single array or hash table, and then store that object. That way, when you retrieve back the whole thing, the objects will continue to share what they originally shared.

At the cost of a slight header overhead, you may store to an already opened file descriptor using the store_fd routine, and retrieve from a file via fd_retrieve. Those names aren't imported by default, so you will have to do that explicitly if you need those routines. The file descriptor you supply must be already opened, for read if you're going to retrieve and for write if you wish to store.

        store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
        $hashref = fd_retrieve(*STDIN);

You can also store data in network order to allow easy sharing across multiple platforms, or when storing on a socket known to be remotely connected. The routines to call have an initial n prefix for network, as in nstore and nstore_fd. At retrieval time, your data will be correctly restored so you don't have to know whether you're restoring from native or network ordered data. Double values are stored stringified to ensure portability as well, at the slight risk of loosing some precision in the last decimals.

When using fd_retrieve, objects are retrieved in sequence, one object (i.e. one recursive tree) per associated store_fd.

If you're more from the object-oriented camp, you can inherit from Storable and directly store your objects by invoking store as a method. The fact that the root of the to-be-stored tree is a blessed reference (i.e. an object) is special-cased so that the retrieve does not provide a reference to that object but rather the blessed object reference itself. (Otherwise, you'd get a reference to that blessed object).

MEMORY STORE

The Storable engine can also store data into a Perl scalar instead, to later retrieve them. This is mainly used to freeze a complex structure in some safe compact memory place (where it can possibly be sent to another process via some IPC, since freezing the structure also serializes it in effect). Later on, and maybe somewhere else, you can thaw the Perl scalar out and recreate the original complex structure in memory.

Surprisingly, the routines to be called are named freeze and thaw. If you wish to send out the frozen scalar to another machine, use nfreeze instead to get a portable image.

Note that freezing an object structure and immediately thawing it actually achieves a deep cloning of that structure:

    dclone(.) = thaw(freeze(.))

Storable provides you with a dclone interface which does not create that intermediary scalar but instead freezes the structure in some internal memory space and then immediately thaws it out.

ADVISORY LOCKING

The lock_store and lock_nstore routine are equivalent to store and nstore, except that they get an exclusive lock on the file before writing. Likewise, lock_retrieve does the same as retrieve, but also gets a shared lock on the file before reading.

As with any advisory locking scheme, the protection only works if you systematically use lock_store and lock_retrieve. If one side of your application uses store whilst the other uses lock_retrieve, you will get no protection at all.

The internal advisory locking is implemented using Perl's flock() routine. If your system does not support any form of flock(), or if you share your files across NFS, you might wish to use other forms of locking by using modules such as LockFile::Simple which lock a file using a filesystem entry, instead of locking the file descriptor.

SPEED

The heart of Storable is written in C for decent speed. Extra low-level optimizations have been made when manipulating perl internals, to sacrifice encapsulation for the benefit of greater speed.

CANONICAL REPRESENTATION

Normally, Storable stores elements of hashes in the order they are stored internally by Perl, i.e. pseudo-randomly. If you set $Storable::canonical to some TRUE value, Storable will store hashes with the elements sorted by their key. This allows you to compare data structures by comparing their frozen representations (or even the compressed frozen representations), which can be useful for creating lookup tables for complicated queries.

Canonical order does not imply network order; those are two orthogonal settings.

CODE REFERENCES

Since Storable version 2.05, CODE references may be serialized with the help of the B::Deparse manpage. To enable this feature, set $Storable::Deparse to a true value. To enable deserializazion, $Storable::Eval should be set to a true value. Be aware that deserialization is done through eval, which is dangerous if the Storable file contains malicious data. You can set $Storable::Eval to a subroutine reference which would be used instead of eval. See below for an example using a the Safe manpage compartment for deserialization of CODE references.

If $Storable::Deparse and/or $Storable::Eval are set to false values, then the value of $Storable::forgive_me (see below) is respected while serializing and deserializing.

FORWARD COMPATIBILITY

This release of Storable can be used on a newer version of Perl to serialize data which is not supported by earlier Perls. By default, Storable will attempt to do the right thing, by croak()ing if it encounters data that it cannot deserialize. However, the defaults can be changed as follows:

utf8 data

Perl 5.6 added support for Unicode characters with code points > 255, and Perl 5.8 has full support for Unicode characters in hash keys. Perl internally encodes strings with these characters using utf8, and Storable serializes them as utf8. By default, if an older version of Perl encounters a utf8 value it cannot represent, it will croak(). To change this behaviour so that Storable deserializes utf8 encoded values as the string of bytes (effectively dropping the is_utf8 flag) set $Storable::drop_utf8 to some TRUE value. This is a form of data loss, because with $drop_utf8 true, it becomes impossible to tell whether the original data was the Unicode string, or a series of bytes that happen to be valid utf8.

restricted hashes

Perl 5.8 adds support for restricted hashes, which have keys restricted to a given set, and can have values locked to be read only. By default, when Storable encounters a restricted hash on a perl that doesn't support them, it will deserialize it as a normal hash, silently discarding any placeholder keys and leaving the keys and all values unlocked. To make Storable croak() instead, set $Storable::downgrade_restricted to a FALSE value. To restore the default set it back to some TRUE value.

files from future versions of Storable

Earlier versions of Storable would immediately croak if they encountered a file with a higher internal version number than the reading Storable knew about. Internal version numbers are increased each time new data types (such as restricted hashes) are added to the vocabulary of the file format. This meant that a newer Storable module had no way of writing a file readable by an older Storable, even if the writer didn't store newer data types.

This version of Storable will defer croaking until it encounters a data type in the file that it does not recognize. This means that it will continue to read files generated by newer Storable modules which are careful in what they write out, making it easier to upgrade Storable modules in a mixed environment.

The old behaviour of immediate croaking can be re-instated by setting $Storable::accept_future_minor to some FALSE value.

All these variables have no effect on a newer Perl which supports the relevant feature.

ERROR REPORTING

Storable uses the "exception" paradigm, in that it does not try to workaround failures: if something bad happens, an exception is generated from the caller's perspective (see the Carp manpage and croak()). Use eval {} to trap those exceptions.

When Storable croaks, it tries to report the error via the logcroak() routine from the Log::Agent package, if it is available.

Normal errors are reported by having store() or retrieve() return undef. Such errors are usually I/O errors (or truncated stream errors at retrieval).

WIZARDS ONLY

Hooks

Any class may define hooks that will be called during the serialization and deserialization process on objects that are instances of that class. Those hooks can redefine the way serialization is performed (and therefore, how the symmetrical deserialization should be conducted).

Since we said earlier:

    dclone(.) = thaw(freeze(.))

everything we say about hooks should also hold for deep cloning. However, hooks get to know whether the operation is a mere serialization, or a cloning.

Therefore, when serializing hooks are involved,

    dclone(.) <> thaw(freeze(.))

Well, you could keep them in sync, but there's no guarantee it will always hold on classes somebody else wrote. Besides, there is little to gain in doing so: a serializing hook could keep only one attribute of an object, which is probably not what should happen during a deep cloning of that same object.

Here is the hooking interface:

STORABLE_freeze obj, cloning

The serializing hook, called on the object during serialization. It can be inherited, or defined in the class itself, like any other method.

Arguments: obj is the object to serialize, cloning is a flag indicating whether we're in a dclone() or a regular serialization via store() or freeze().

Returned value: A LIST ($serialized, $ref1, $ref2, ...) where $serialized is the serialized form to be used, and the optional $ref1, $ref2, etc... are extra references that you wish to let the Storable engine serialize.

At deserialization time, you will be given back the same LIST, but all the extra references will be pointing into the deserialized structure.

The first time the hook is hit in a serialization flow, you may have it return an empty list. That will signal the Storable engine to further discard that hook for this class and to therefore revert to the default serialization of the underlying Perl data. The hook will again be normally processed in the next serialization.

Unless you know better, serializing hook should always say:

    sub STORABLE_freeze {
        my ($self, $cloning) = @_;
        return if $cloning;         # Regular default serialization
        ....
    }

in order to keep reasonable dclone() semantics.

STORABLE_thaw obj, cloning, serialized, ...

The deserializing hook called on the object during deserialization. But wait: if we're deserializing, there's no object yet... right?

Wrong: the Storable engine creates an empty one for you. If you know Eiffel, you can view STORABLE_thaw as an alternate creation routine.

This means the hook can be inherited like any other method, and that obj is your blessed reference for this particular instance.

The other arguments should look familiar if you know STORABLE_freeze: cloning is true when we're part of a deep clone operation, serialized is the serialized string you returned to the engine in STORABLE_freeze, and there may be an optional list of references, in the same order you gave them at serialization time, pointing to the deserialized objects (which have been processed courtesy of the Storable engine).

When the Storable engine does not find any STORABLE_thaw hook routine, it tries to load the class by requiring the package dynamically (using the blessed package name), and then re-attempts the lookup. If at that time the hook cannot be located, the engine croaks. Note that this mechanism will fail if you define several classes in the same file, but the perlmod manpage warned you.

It is up to you to use this information to populate obj the way you want.

Returned value: none.

STORABLE_attach class, cloning, serialized

While STORABLE_freeze and STORABLE_thaw are useful for classes where each instance is independant, this mechanism has difficulty (or is incompatible) with objects that exist as common process-level or system-level resources, such as singleton objects, database pools, caches or memoized objects.

The alternative STORABLE_attach method provides a solution for these shared objects. Instead of STORABLE_freeze --> STORABLE_thaw, you implement STORABLE_freeze --> STORABLE_attach instead.

Arguments: class is the class we are attaching to, cloning is a flag indicating whether we're in a dclone() or a regular de-serialization via thaw(), and serialized is the stored string for the resource object.

Because these resource objects are considered to be owned by the entire process/system, and not the "property" of whatever is being serialized, no references underneath the object should be included in the serialized string. Thus, in any class that implements STORABLE_attach, the STORABLE_freeze method cannot return any references, and Storable will throw an error if STORABLE_freeze tries to return references.

All information required to "attach" back to the shared resource object must be contained only in the STORABLE_freeze return string. Otherwise, STORABLE_freeze behaves as normal for STORABLE_attach classes.

Because STORABLE_attach is passed the class (rather than an object), it also returns the object directly, rather than modifying the passed object.

Returned value: object of type class

Predicates

Predicates are not exportable. They must be called by explicitly prefixing them with the Storable package name.

Storable::last_op_in_netorder

The Storable::last_op_in_netorder() predicate will tell you whether network order was used in the last store or retrieve operation. If you don't know how to use this, just forget about it.

Storable::is_storing

Returns true if within a store operation (via STORABLE_freeze hook).

Storable::is_retrieving

Returns true if within a retrieve operation (via STORABLE_thaw hook).

Recursion

With hooks comes the ability to recurse back to the Storable engine. Indeed, hooks are regular Perl code, and Storable is convenient when it comes to serializing and deserializing things, so why not use it to handle the serialization string?

There are a few things you need to know, however:

  • You can create endless loops if the things you serialize via freeze() (for instance) point back to the object we're trying to serialize in the hook.

  • Shared references among objects will not stay shared: if we're serializing the list of object [A, C] where both object A and C refer to the SAME object B, and if there is a serializing hook in A that says freeze(B), then when deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D, a deep clone of B'. The topology was not preserved.

That's why STORABLE_freeze lets you provide a list of references to serialize. The engine guarantees that those will be serialized in the same context as the other objects, and therefore that shared objects will stay shared.

In the above [A, C] example, the STORABLE_freeze hook could return:

        ("something", $self->{B})

and the B part would be serialized by the engine. In STORABLE_thaw, you would get back the reference to the B' object, deserialized for you.

Therefore, recursion should normally be avoided, but is nonetheless supported.

Deep Cloning

There is a Clone module available on CPAN which implements deep cloning natively, i.e. without freezing to memory and thawing the result. It is aimed to replace Storable's dclone() some day. However, it does not currently support Storable hooks to redefine the way deep cloning is performed.

Storable magic

Yes, there's a lot of that :-) But more precisely, in UNIX systems there's a utility called file, which recognizes data files based on their contents (usually their first few bytes). For this to work, a certain file called magic needs to taught about the signature of the data. Where that configuration file lives depends on the UNIX flavour; often it's something like /usr/share/misc/magic or /etc/magic. Your system administrator needs to do the updating of the magic file. The necessary signature information is output to STDOUT by invoking Storable::show_file_magic(). Note that the GNU implementation of the file utility, version 3.38 or later, is expected to contain support for recognising Storable files out-of-the-box, in addition to other kinds of Perl files.

EXAMPLES

Here are some code samples showing a possible usage of Storable:

        use Storable qw(store retrieve freeze thaw dclone);

        %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);

        store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n";

        $colref = retrieve('mycolors');
        die "Unable to retrieve from mycolors!\n" unless defined $colref;
        printf "Blue is still %lf\n", $colref->{'Blue'};

        $colref2 = dclone(\%color);

        $str = freeze(\%color);
        printf "Serialization of %%color is %d bytes long.\n", length($str);
        $colref3 = thaw($str);

which prints (on my machine):

        Blue is still 0.100000
        Serialization of %color is 102 bytes long.

Serialization of CODE references and deserialization in a safe compartment:

        use Storable qw(freeze thaw);
        use Safe;
        use strict;
        my $safe = new Safe;
        # because of opcodes used in "use strict":
        $safe->permit(qw(:default require));
        local $Storable::Deparse = 1;
        local $Storable::Eval = sub { $safe->reval($_[0]) };
        my $serialized = freeze(sub { 42 });
        my $code = thaw($serialized);
        $code->() == 42;

WARNING

If you're using references as keys within your hash tables, you're bound to be disappointed when retrieving your data. Indeed, Perl stringifies references used as hash table keys. If you later wish to access the items via another reference stringification (i.e. using the same reference that was used for the key originally to record the value into the hash table), it will work because both references stringify to the same string.

It won't work across a sequence of store and retrieve operations, however, because the addresses in the retrieved objects, which are part of the stringified references, will probably differ from the original addresses. The topology of your structure is preserved, but not hidden semantics like those.

On platforms where it matters, be sure to call binmode() on the descriptors that you pass to Storable functions.

Storing data canonically that contains large hashes can be significantly slower than storing the same data normally, as temporary arrays to hold the keys for each hash have to be allocated, populated, sorted and freed. Some tests have shown a halving of the speed of storing -- the exact penalty will depend on the complexity of your data. There is no slowdown on retrieval.

BUGS

You can't store GLOB, FORMLINE, etc.... If you can define semantics for those operations, feel free to enhance Storable so that it can deal with them.

The store functions will croak if they run into such references unless you set $Storable::forgive_me to some TRUE value. In that case, the fatal message is turned in a warning and some meaningless string is stored instead.

Setting $Storable::canonical may not yield frozen strings that compare equal due to possible stringification of numbers. When the string version of a scalar exists, it is the form stored; therefore, if you happen to use your numbers as strings between two freezing operations on the same data structures, you will get different results.

When storing doubles in network order, their value is stored as text. However, you should also not expect non-numeric floating-point values such as infinity and "not a number" to pass successfully through a nstore()/retrieve() pair.

As Storable neither knows nor cares about character sets (although it does know that characters may be more than eight bits wide), any difference in the interpretation of character codes between a host and a target system is your problem. In particular, if host and target use different code points to represent the characters used in the text representation of floating-point numbers, you will not be able be able to exchange floating-point data, even with nstore().

Storable::drop_utf8 is a blunt tool. There is no facility either to return all strings as utf8 sequences, or to attempt to convert utf8 data back to 8 bit and croak() if the conversion fails.

Prior to Storable 2.01, no distinction was made between signed and unsigned integers on storing. By default Storable prefers to store a scalars string representation (if it has one) so this would only cause problems when storing large unsigned integers that had never been coverted to string or floating point. In other words values that had been generated by integer operations such as logic ops and then not used in any string or arithmetic context before storing.

64 bit data in perl 5.6.0 and 5.6.1

This section only applies to you if you have existing data written out by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which has been configured with 64 bit integer support (not the default) If you got a precompiled perl, rather than running Configure to build your own perl from source, then it almost certainly does not affect you, and you can stop reading now (unless you're curious). If you're using perl on Windows it does not affect you.

Storable writes a file header which contains the sizes of various C language types for the C compiler that built Storable (when not writing in network order), and will refuse to load files written by a Storable not on the same (or compatible) architecture. This check and a check on machine byteorder is needed because the size of various fields in the file are given by the sizes of the C language types, and so files written on different architectures are incompatible. This is done for increased speed. (When writing in network order, all fields are written out as standard lengths, which allows full interworking, but takes longer to read and write)

Perl 5.6.x introduced the ability to optional configure the perl interpreter to use C's long long type to allow scalars to store 64 bit integers on 32 bit systems. However, due to the way the Perl configuration system generated the C configuration files on non-Windows platforms, and the way Storable generates its header, nothing in the Storable file header reflected whether the perl writing was using 32 or 64 bit integers, despite the fact that Storable was storing some data differently in the file. Hence Storable running on perl with 64 bit integers will read the header from a file written by a 32 bit perl, not realise that the data is actually in a subtly incompatible format, and then go horribly wrong (possibly crashing) if it encountered a stored integer. This is a design failure.

Storable has now been changed to write out and read in a file header with information about the size of integers. It's impossible to detect whether an old file being read in was written with 32 or 64 bit integers (they have the same header) so it's impossible to automatically switch to a correct backwards compatibility mode. Hence this Storable defaults to the new, correct behaviour.

What this means is that if you have data written by Storable 1.x running on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux then by default this Storable will refuse to read it, giving the error Byte order is not compatible. If you have such data then you you should set $Storable::interwork_56_64bit to a true value to make this Storable read and write files with the old header. You should also migrate your data, or any older perl you are communicating with, to this current version of Storable.

If you don't have data written with specific configuration of perl described above, then you do not and should not do anything. Don't set the flag - not only will Storable on an identically configured perl refuse to load them, but Storable a differently configured perl will load them believing them to be correct for it, and then may well fail or crash part way through reading them.

CREDITS

Thank you to (in chronological order):

        Jarkko Hietaniemi <jhi@iki.fi>
        Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
        Benjamin A. Holzman <bah@ecnvantage.com>
        Andrew Ford <A.Ford@ford-mason.co.uk>
        Gisle Aas <gisle@aas.no>
        Jeff Gresham <gresham_jeffrey@jpmorgan.com>
        Murray Nesbitt <murray@activestate.com>
        Marc Lehmann <pcg@opengroup.org>
        Justin Banks <justinb@wamnet.com>
        Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
        Salvador Ortiz Garcia <sog@msg.com.mx>
        Dominic Dunlop <domo@computer.org>
        Erik Haugan <erik@solbors.no>

for their bug reports, suggestions and contributions.

Benjamin Holzman contributed the tied variable support, Andrew Ford contributed the canonical order for hashes, and Gisle Aas fixed a few misunderstandings of mine regarding the perl internals, and optimized the emission of "tags" in the output streams by simply counting the objects instead of tagging them (leading to a binary incompatibility for the Storable image starting at version 0.6--older images are, of course, still properly understood). Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading and references to tied items support.

AUTHOR

Storable was written by Raphael Manfredi <Raphael_Manfredi@pobox.com> Maintenance is now done by the perl5-porters <perl5-porters@perl.org>

Please e-mail us with problems, bug fixes, comments and complaints, although if you have complements you should send them to Raphael. Please don't e-mail Raphael with problems, as he no longer works on Storable, and your message will be delayed while he forwards it to us.

SEE ALSO

Clone.


String::Format - sprintf-like string formatting capabilities with arbitrary format definitions

  • ABSTRACT
  • SYNOPSIS
  • DESCRIPTION
  • FUNCTIONS
    • stringf
  • FORMAT STRINGS
  • FACTORY METHOD
  • AUTHOR

NAME

String::Format - sprintf-like string formatting capabilities with arbitrary format definitions

ABSTRACT

String::Format allows for sprintf-style formatting capabilities with arbitrary format definitions

SYNOPSIS

  # In a script invoked as:
  # script.pl -f "I like %a, %b, and %g, but not %m or %w."

  use String::Format;
  use Getopt::Std;

  my %fruit = (
        'a' => "apples",
        'b' => "bannanas",
        'g' => "grapefruits",
        'm' => "melons",
        'w' => "watermelons",
  );

  use vars qw($opt_f);
  getopt("f");

  print stringf($opt_f, %fruit);

  # prints:
  # I like apples, bannanas, and grapefruits, but not melons or watermelons.

DESCRIPTION

String::Format lets you define arbitrary printf-like format sequences to be expanded. This module would be most useful in configuration files and reporting tools, where the results of a query need to be formatted in a particular way. It was inspired by mutt's index_format and related directives (see <URL:http://www.mutt.org/doc/manual/manual-6.html#index_format>).

FUNCTIONS

stringf

String::Format exports a single function called stringf. stringf takes two arguments: a format string (see FORMAT STRINGS, below) and a reference to a hash of name => value pairs. These name => value pairs are what will be expanded in the format string.

FORMAT STRINGS

Format strings must match the following regular expression:

  qr/
     (%             # leading '%'
      (-)?          # left-align, rather than right
      (\d*)?        # (optional) minimum field width
      (?:\.(\d*))?  # (optional) maximum field width
      ({.*?})?      # (optional) stuff inside
      (\S)          # actual format character
     )/x;

If the escape character specified does not exist in %args, then the original string is used. The alignment, minimum width, and maximum width options function identically to how they are defined in sprintf(3) (any variation is a bug, and should be reported).

Note that Perl's sprintf definition is a little more liberal than the above regex; the deviations were intentional, and all deal with numeric formatting (the #, 0, and + leaders were specifically left out).

The value attached to the key can be a scalar value or a subroutine reference; if it is a subroutine reference, then anything between the '{' and '}' ($5 in the above regex) will be passed as $_[0] to the subroutine reference. This allows for entries such as this:

  %args = (
      d => sub { POSIX::strftime($_[0], localtime) },
  );

Which can be invoked with this format string:

  "It is %{%M:%S}d right now, on %{%A, %B %e}d."

And result in (for example):

  It is 17:45 right now, on Monday, February 4.

Note that since the string is passed unmolested to the subroutine reference, and strftime would Do The Right Thing with this data, the above format string could be written as:

  "It is %{%M:%S right now, on %A, %B %e}d."

By default, the formats 'n', 't', and '%' are defined to be a newline, tab, and '%', respectively, if they are not already defined in the hashref of arguments that gets passed it. So we can add carriage returns simply:

  "It is %{%M:%S right now, on %A, %B %e}d.%n"

Because of how the string is parsed, the normal "\n" and "\t" are turned into two characters each, and are not treated as a newline and tab. This is a bug.

FACTORY METHOD

String::Format also supports a class method, named stringfactory, which will return reference to a "primed" subroutine. stringfatory should be passed a reference to a hash of value; the returned subroutine will use these values as the %args hash.

  my $self = Some::Groovy::Package->new($$, $<, $^T);
  my %formats = (
        'i' => sub { $self->id      },
        'd' => sub { $self->date    },
        's' => sub { $self->subject },
        'b' => sub { $self->body    },
  );
  my $index_format = String::Format->stringfactory(\%formats);

  print $index_format->($format1);
  print $index_format->($format2);

This subroutine reference can be assigned to a local symbol table entry, and called normally, of course:

  *reformat = String::Format->stringfactory(\%formats);

  my $reformed = reformat($format_string);

AUTHOR

darren chamberlain <darren@cpan.org>


Switch - A switch statement for Perl

  • VERSION
  • SYNOPSIS
  • BACKGROUND
  • DESCRIPTION
    • Allowing fall-through
    • Automating fall-through
    • Alternative syntax
    • Higher-order Operations
  • DEPENDENCIES
  • AUTHOR
  • BUGS
  • LIMITATIONS
  • COPYRIGHT

NAME

Switch - A switch statement for Perl

VERSION

This document describes version 2.10 of Switch, released Dec 29, 2003.

SYNOPSIS

        use Switch;

        switch ($val) {

                case 1          { print "number 1" }
                case "a"        { print "string a" }
                case [1..10,42] { print "number in list" }
                case (@array)   { print "number in list" }
                case /\w+/      { print "pattern" }
                case qr/\w+/    { print "pattern" }
                case (%hash)    { print "entry in hash" }
                case (\%hash)   { print "entry in hash" }
                case (\&sub)    { print "arg to subroutine" }
                else            { print "previous case not true" }
                        }

BACKGROUND

[Skip ahead to DESCRIPTION if you don't care about the whys and wherefores of this control structure]

In seeking to devise a "Swiss Army" case mechanism suitable for Perl, it is useful to generalize this notion of distributed conditional testing as far as possible. Specifically, the concept of "matching" between the switch value and the various case values need not be restricted to numeric (or string or referential) equality, as it is in other languages. Indeed, as Table 1 illustrates, Perl offers at least eighteen different ways in which two values could generate a match.

        Table 1: Matching a switch value ($s) with a case value ($c)
        Switch  Case    Type of Match Implied   Matching Code
        Value   Value
        ======  =====   =====================   =============
        number  same    numeric or referential  match if $s == $c;
        or ref          equality

        object  method  result of method call   match if $s->$c();
        ref     name                            match if defined $s->$c();
                or ref

        other   other   string equality         match if $s eq $c;
        non-ref non-ref
        scalar  scalar

        string  regexp  pattern match           match if $s =~ /$c/;

        array   scalar  array entry existence   match if 0<=$c && $c<@$s;
        ref             array entry definition  match if defined $s->[$c];
                        array entry truth       match if $s->[$c];

        array   array   array intersection      match if intersects(@$s, @$c);
        ref     ref     (apply this table to
                         all pairs of elements
                         $s->[$i] and
                         $c->[$j])

        array   regexp  array grep              match if grep /$c/, @$s;
        ref

        hash    scalar  hash entry existence    match if exists $s->{$c};
        ref             hash entry definition   match if defined $s->{$c};
                        hash entry truth        match if $s->{$c};

        hash    regexp  hash grep               match if grep /$c/, keys %$s;
        ref

        sub     scalar  return value defn       match if defined $s->($c);
        ref             return value truth      match if $s->($c);

        sub     array   return value defn       match if defined $s->(@$c);
        ref     ref     return value truth      match if $s->(@$c);

In reality, Table 1 covers 31 alternatives, because only the equality and intersection tests are commutative; in all other cases, the roles of the $s and $c variables could be reversed to produce a different test. For example, instead of testing a single hash for the existence of a series of keys (match if exists $s->{$c}), one could test for the existence of a single key in a series of hashes (match if exists $c->{$s}).

As the perltodo manpage observes, a Perl case mechanism must support all these "ways to do it".

DESCRIPTION

The Switch.pm module implements a generalized case mechanism that covers the numerous possible combinations of switch and case values described above.

The module augments the standard Perl syntax with two new control statements: switch and case. The switch statement takes a single scalar argument of any type, specified in parentheses. switch stores this value as the current switch value in a (localized) control variable. The value is followed by a block which may contain one or more Perl statements (including the case statement described below). The block is unconditionally executed once the switch value has been cached.

A case statement takes a single scalar argument (in mandatory parentheses if it's a variable; otherwise the parens are optional) and selects the appropriate type of matching between that argument and the current switch value. The type of matching used is determined by the respective types of the switch value and the case argument, as specified in Table 1. If the match is successful, the mandatory block associated with the case statement is executed.

In most other respects, the case statement is semantically identical to an if statement. For example, it can be followed by an else clause, and can be used as a postfix statement qualifier.

However, when a case block has been executed control is automatically transferred to the statement after the immediately enclosing switch block, rather than to the next statement within the block. In other words, the success of any case statement prevents other cases in the same scope from executing. But see Allowing fall-through below.

Together these two new statements provide a fully generalized case mechanism:

        use Switch;

        # AND LATER...

        %special = ( woohoo => 1,  d'oh => 1 );

        while (<>) {
            switch ($_) {

                case (%special) { print "homer\n"; }      # if $special{$_}
                case /a-z/i     { print "alpha\n"; }      # if $_ =~ /a-z/i
                case [1..9]     { print "small num\n"; }  # if $_ in [1..9]

                case { $_[0] >= 10 } {                    # if $_ >= 10
                    my $age = <>;
                    switch (sub{ $_[0] < $age } ) {

                        case 20  { print "teens\n"; }     # if 20 < $age
                        case 30  { print "twenties\n"; }  # if 30 < $age
                        else     { print "history\n"; }
                                            }
                                        }

                print "must be punctuation\n" case /\W/;  # if $_ ~= /\W/
                        }

Note that switches can be nested within case (or any other) blocks, and a series of case statements can try different types of matches -- hash membership, pattern match, array intersection, simple equality, etc. -- against the same switch value.

The use of intersection tests against an array reference is particularly useful for aggregating integral cases:

        sub classify_digit
        {
                switch ($_[0]) { case 0            { return 'zero' }
                                 case [2,4,6,8]    { return 'even' }
                                 case [1,3,4,7,9]  { return 'odd' }
                                 case /[A-F]/i     { return 'hex' }
                               }
        }

Allowing fall-through

Fall-though (trying another case after one has already succeeded) is usually a Bad Idea in a switch statement. However, this is Perl, not a police state, so there is a way to do it, if you must.

If a case block executes an untargeted next, control is immediately transferred to the statement after the case statement (i.e. usually another case), rather than out of the surrounding switch block.

For example:

        switch ($val) {
                case 1      { handle_num_1(); next }    # and try next case...
                case "1"    { handle_str_1(); next }    # and try next case...
                case [0..9] { handle_num_any(); }       # and we're done
                case /\d/   { handle_dig_any(); next }  # and try next case...
                case /.*/   { handle_str_any(); next }  # and try next case...
        }

If $val held the number 1, the above switch block would call the first three handle_... subroutines, jumping to the next case test each time it encountered a next. After the thrid case block was executed, control would jump to the end of the enclosing switch block.

On the other hand, if $val held 10, then only the last two handle_... subroutines would be called.

Note that this mechanism allows the notion of conditional fall-through. For example:

        switch ($val) {
                case [0..9] { handle_num_any(); next if $val < 7; }
                case /\d/   { handle_dig_any(); }
        }

If an untargeted last statement is executed in a case block, this immediately transfers control out of the enclosing switch block (in other words, there is an implicit last at the end of each normal case block). Thus the previous example could also have been written:

        switch ($val) {
                case [0..9] { handle_num_any(); last if $val >= 7; next; }
                case /\d/   { handle_dig_any(); }
        }

Automating fall-through

In situations where case fall-through should be the norm, rather than an exception, an endless succession of terminal nexts is tedious and ugly. Hence, it is possible to reverse the default behaviour by specifying the string "fallthrough" when importing the module. For example, the following code is equivalent to the first example in Allowing fall-through:

        use Switch 'fallthrough';

        switch ($val) {
                case 1      { handle_num_1(); }
                case "1"    { handle_str_1(); }
                case [0..9] { handle_num_any(); last }
                case /\d/   { handle_dig_any(); }
                case /.*/   { handle_str_any(); }
        }

Note the explicit use of a last to preserve the non-fall-through behaviour of the third case.

Alternative syntax

Perl 6 will provide a built-in switch statement with essentially the same semantics as those offered by Switch.pm, but with a different pair of keywords. In Perl 6 switch will be spelled given, and case will be pronounced when. In addition, the when statement will not require switch or case values to be parenthesized.

This future syntax is also (largely) available via the Switch.pm module, by importing it with the argument "Perl6". For example:

        use Switch 'Perl6';

        given ($val) {
                when 1       { handle_num_1(); }
                when ($str1) { handle_str_1(); }
                when [0..9]  { handle_num_any(); last }
                when /\d/    { handle_dig_any(); }
                when /.*/    { handle_str_any(); }
                default      { handle anything else; }
        }

Note that scalars still need to be parenthesized, since they would be ambiguous in Perl 5.

Note too that you can mix and match both syntaxes by importing the module with:

        use Switch 'Perl5', 'Perl6';

Higher-order Operations

One situation in which switch and case do not provide a good substitute for a cascaded if, is where a switch value needs to be tested against a series of conditions. For example:

        sub beverage {
            switch (shift) {

                case sub { $_[0] < 10 }  { return 'milk' }
                case sub { $_[0] < 20 }  { return 'coke' }
                case sub { $_[0] < 30 }  { return 'beer' }
                case sub { $_[0] < 40 }  { return 'wine' }
                case sub { $_[0] < 50 }  { return 'malt' }
                case sub { $_[0] < 60 }  { return 'Moet' }
                else                     { return 'milk' }
                            }
                        }

The need to specify each condition as a subroutine block is tiresome. To overcome this, when importing Switch.pm, a special "placeholder" subroutine named __ [sic] may also be imported. This subroutine converts (almost) any expression in which it appears to a reference to a higher-order function. That is, the expression:

        use Switch '__';

        __ < 2 + __

is equivalent to:

        sub { $_[0] < 2 + $_[1] }

With __, the previous ugly case statements can be rewritten:

        case  __ < 10  { return 'milk' }
        case  __ < 20  { return 'coke' }
        case  __ < 30  { return 'beer' }
        case  __ < 40  { return 'wine' }
        case  __ < 50  { return 'malt' }
        case  __ < 60  { return 'Moet' }
        else           { return 'milk' }

The __ subroutine makes extensive use of operator overloading to perform its magic. All operations involving __ are overloaded to produce an anonymous subroutine that implements a lazy version of the original operation.

The only problem is that operator overloading does not allow the boolean operators && and || to be overloaded. So a case statement like this:

        case  0 <= __ && __ < 10  { return 'digit' }

doesn't act as expected, because when it is executed, it constructs two higher order subroutines and then treats the two resulting references as arguments to &&:

        sub { 0 <= $_[0] } && sub { $_[0] < 10 }

This boolean expression is inevitably true, since both references are non-false. Fortunately, the overloaded 'bool' operator catches this situation and flags it as a error.

DEPENDENCIES

The module is implemented using Filter::Util::Call and Text::Balanced and requires both these modules to be installed.

AUTHOR

Damian Conway (damian@conway.org) The maintainer of this module is now Rafael Garcia-Suarez (rgarciasuarez@free.fr)

BUGS

There are undoubtedly serious bugs lurking somewhere in code this funky :-) Bug reports and other feedback are most welcome.

LIMITATIONS

Due to the heuristic nature of Switch.pm's source parsing, the presence of regexes specified with raw ?...? delimiters may cause mysterious errors. The workaround is to use m?...? instead.

Due to the way source filters work in Perl, you can't use Switch inside an string eval.

If your source file is longer then 1 million characters and you have a switch statement that crosses the 1 million (or 2 million, etc.) character boundary you will get mysterious errors. The workaround is to use smaller source files.

COPYRIGHT

    Copyright (c) 1997-2003, Damian Conway. All Rights Reserved.
    This module is free software. It may be used, redistributed
        and/or modified under the same terms as Perl itself.


Symbol - manipulate Perl symbols and their names

  • BUGS

NAME

Symbol - manipulate Perl symbols and their names

SYNOPSIS

    use Symbol;

    $sym = gensym;
    open($sym, "filename");
    $_ = <$sym>;
    # etc.

    ungensym $sym;      # no effect

    # replace *FOO{IO} handle but not $FOO, %FOO, etc.
    *FOO = geniosym;

    print qualify("x"), "\n";              # "Test::x"
    print qualify("x", "FOO"), "\n"        # "FOO::x"
    print qualify("BAR::x"), "\n";         # "BAR::x"
    print qualify("BAR::x", "FOO"), "\n";  # "BAR::x"
    print qualify("STDOUT", "FOO"), "\n";  # "main::STDOUT" (global)
    print qualify(\*x), "\n";              # returns \*x
    print qualify(\*x, "FOO"), "\n";       # returns \*x

    use strict refs;
    print { qualify_to_ref $fh } "foo!\n";
    $ref = qualify_to_ref $name, $pkg;

    use Symbol qw(delete_package);
    delete_package('Foo::Bar');
    print "deleted\n" unless exists $Foo::{'Bar::'};

DESCRIPTION

Symbol::gensym creates an anonymous glob and returns a reference to it. Such a glob reference can be used as a file or directory handle.

For backward compatibility with older implementations that didn't support anonymous globs, Symbol::ungensym is also provided. But it doesn't do anything.

Symbol::geniosym creates an anonymous IO handle. This can be assigned into an existing glob without affecting the non-IO portions of the glob.

Symbol::qualify turns unqualified symbol names into qualified variable names (e.g. "myvar" -> "MyPackage::myvar"). If it is given a second parameter, qualify uses it as the default package; otherwise, it uses the package of its caller. Regardless, global variable names (e.g. "STDOUT", "ENV", "SIG") are always qualified with "main::".

Qualification applies only to symbol names (strings). References are left unchanged under the assumption that they are glob references, which are qualified by their nature.

Symbol::qualify_to_ref is just like Symbol::qualify except that it returns a glob ref rather than a symbol name, so you can use the result even if use strict 'refs' is in effect.

Symbol::delete_package wipes out a whole package namespace. Note this routine is not exported by default--you may want to import it explicitly.

BUGS

Symbol::delete_package is a bit too powerful. It undefines every symbol that lives in the specified package. Since perl, for performance reasons, does not perform a symbol table lookup each time a function is called or a global variable is accessed, some code that has already been loaded and that makes use of symbols in package Foo may stop working after you delete Foo, even if you reload the Foo module afterwards.


Sys::Hostname - Try every conceivable way to get hostname

  • AUTHOR

NAME

Sys::Hostname - Try every conceivable way to get hostname

SYNOPSIS

    use Sys::Hostname;
    $host = hostname;

DESCRIPTION

Attempts several methods of getting the system hostname and then caches the result. It tries the first available of the C library's gethostname(), `$Config{aphostname}`, uname(2), syscall(SYS_gethostname), `hostname`, `uname -n`, and the file /com/host. If all that fails it croaks.

All NULs, returns, and newlines are removed from the result.

AUTHOR

David Sundstrom <sunds@asictest.sc.ti.com>

Texas Instruments

XS code added by Greg Bacon <gbacon@cs.uah.edu>


TASKS - Want to help? These things need doing...

    • Increase test coverage
    • Test the proxy
    • Fixing bugs

NAME

TASKS - Want to help? These things need doing...

Increase test coverage

More tests need to be added to test the codes that not urrently being tested.

It's pretty poor right now:

   http://pjcj.sytes.net/cover/latest/DBI-1.52/coverage.html

Start with improving the subroutine coverage

   http://pjcj.sytes.net/cover/latest/DBI-1.52/blib-lib-DBI-pm--subroutine.html

Test the proxy

The current t/80proxy.t is isolated from the rest of the test suite so actually tests very little, and what it does test is duplicating other tests.

Ideally the proxy should be tested in the same way as DBI::PurePerl. In other words, by creating wrappers test files for each test file that set $ENV{DBI_AUTOPROXY} and run the original test. They'll also need to start and stop a proxy server.

Fixing bugs

The official bug list is here:

   http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBI

Naturally I'll offer direction and guidance on any you want to tackle. I've also got a few that could be entered into rt.cpan.org.


Task::Weaken - Ensure that a platform has weaken support

    • How this Task works
  • AUTHOR
  • SEE ALSO
  • COPYRIGHT

NAME

Task::Weaken - Ensure that a platform has weaken support

DESCRIPTION

One recurring problem in modules that use the Scalar::Util manpage's weaken function is that it is not present in the pure-perl variant.

While this isn't necesarily always a problem in a straight CPAN-based Perl environment, some operating system distributions only include the pure-Perl versions, don't include the XS version, and so weaken is then "missing" from the platform, despite passing a dependency on the Scalar::Util manpage successfully.

Most notably this is RedHat Linux at time of writing, but other come and go and do the same thing, hence "recurring problem".

The normal solution is to manually write tests in each distribution to ensure that weaken is available.

This restores the functionality testing to a dependency you do once in your Makefile.PL, rather than something you have to write extra tests for each time you write a module.

It should also help make the package auto-generators for the various operating systems play more nicely, because it introduces a dependency that they have to have a proper weaken in order to work.

How this Task works

Part of the problem seems to stem from the fact that some distributions continue to include modules even if they fail some of their tests.

To get around that for this module, it will do a few dirty tricks.

If the Scalar::Util manpage is not available at all, it will issue a normal dependency on the module. However, if the Scalar::Util manpage is relatively new ( it is >= 1.14 ) and the module does not have weaken, the install will bail out altogether with a "platform does not support this module" error.

This means that a distributor cannot just force the install, as there will be no Makefile at all to do the installation phase.

This is to some degree lying, so it is somewhat debatable if this strategy should continue, and may be removed later.

This distribution also contains tests to ensure that weaken is available using more normal methods.

So if your module uses weaken, you can just add the following to your the Module::Install manpage-based Makefile.PL (or equivalent).

  requires 'Task::Weaken';

AUTHOR

Adam Kennedy <cpan@ali.as>, http://ali.as/

SEE ALSO

Task, the Scalar::Util manpage, http://ali.as/

COPYRIGHT

Copyright 2006 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.


Tcl - Tcl extension module for Perl

    • Methods in class Tcl
    • Linking Perl and Tcl variables
    • Accessing Perl from within Tcl
    • Moving Tcl/Tk around with Tcl.pm
  • AUTHORS
  • COPYRIGHT

NAME

Tcl - Tcl extension module for Perl

SYNOPSIS

    use Tcl;

    $interp = new Tcl;
    $interp->Eval('puts "Hello world"');

DESCRIPTION

The Tcl extension module gives access to the Tcl library with functionality and interface similar to the C functions of Tcl. In other words, you can

create Tcl interpreters

The Tcl interpreters so created are Perl objects whose destructors delete the interpreters cleanly when appropriate.

execute Tcl code in an interpreter

The code can come from strings, files or Perl filehandles.

bind in new Tcl procedures

The new procedures can be either C code (with addresses presumably obtained using dl_open and dl_find_symbol) or Perl subroutines (by name, reference or as anonymous subs). The (optional) deleteProc callback in the latter case is another perl subroutine which is called when the command is explicitly deleted by name or else when the destructor for the interpreter object is explicitly or implicitly called.

Manipulate the result field of a Tcl interpreter
Set and get values of variables in a Tcl interpreter
Tie perl variables to variables in a Tcl interpreter

The variables can be either scalars or hashes.

Methods in class Tcl

To create a new Tcl interpreter, use

    $i = new Tcl;

The following methods and routines can then be used on the Perl object returned (the object argument omitted in each case).

Init ()

Invoke Tcl_Init on the interpeter.

Eval (STRING, FLAGS)

Evaluate script STRING in the interpreter. If the script returns successfully (TCL_OK) then the Perl return value corresponds to Tcl interpreter's result otherwise a die exception is raised with the $@ variable corresponding to Tcl's interpreter result object. In each case, corresponds means that if the method is called in scalar context then the string result is returned but if the method is called in list context then the result is split as a Tcl list and returned as a Perl list. The FLAGS field is optional and can be a bitwise OR of the constants Tcl::EVAL_GLOBAL or Tcl::EVAL_DIRECT.

GlobalEval (STRING)

REMOVED. Evalulate script STRING at global level. Call Eval(STRING, Tcl::EVAL_GLOBAL) instead.

EvalFile (FILENAME)

Evaluate the contents of the file with name FILENAME. Otherwise, the same as Eval() above.

EvalFileHandle (FILEHANDLE)

Evaluate the contents of the Perl filehandle FILEHANDLE. Otherwise, the same as Eval() above. Useful when using the filehandle DATA to tack on a Tcl script following an __END__ token.

call (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it using Tcl's eval semantics that does command tracing and will use the ::unknown (AUTOLOAD) mechanism. The arguments (ARG, ...) are not passed through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC.

Before invoking procedure PROC special processing is performed on ARG list:

1. All subroutine references within ARG will be substituted with Tcl name which is responsible to invoke this subroutine. This Tcl name will be created using CreateCommand subroutine (see below).

2. All references to scalars will be substituted with names of Tcl variables transformed appropriately.

These first two items allows to write and expect it to work properly such code as:

  my $r = 'aaaa';
  button(".d", -textvariable => \$r, -command=>sub {$r++});

3. As a special case, there is a mechanism to deal with Tk's special event variables (they are mentioned as '%x', '%y' and so on throughout Tcl). When creating a subroutine reference that uses such variables, you must declare the desired variables using Tcl::Ev as the first argument to the subroutine. Example:

  sub textPaste {
      my ($x,$y,$w) = @_;
      widget($w)->insert("\@$x,$y", $interp->Eval('selection get'));
  }
  $widget->bind('<2>', [\&textPaste, Tcl::Ev('%x', '%y'), $widget] );
return_ref (NAME)

returns a reference corresponding to NAME, which was associated during previously called $int->call(...) preprocessing. As a typical example this could be variable associated with a widget.

delete_ref (NAME)

deletes and returns a reference corresponding to NAME, which was associated during previously called $int->call(...) preprocessing.

icall (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it using Tcl's eval semantics that does command tracing and will use the ::unknown (AUTOLOAD) mechanism. The arguments (ARG, ...) are not passed through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC.

This is the lower-level procedure that the 'call' method uses. Arguments are converted efficiently from Perl SVs to Tcl_Objs. A Perl AV array becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc. The reverse conversion is done to the result.

invoke (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it directly with arguments (ARG, ...) without passing through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC. This differs from icall/call in that it directly invokes the command name without allowing for command tracing or making use of Tcl's unknown (AUTOLOAD) mechanism. If the command does not already exist in the interpreter, and error will be thrown.

Arguments are converted efficiently from Perl SVs to Tcl_Objs. A Perl AV array becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc. The reverse conversion is done to the result.

Tcl::Ev (FIELD, ...)

Used to declare %-substitution variables of interest to a subroutine callback. FIELD is expected to be of the form "%#" where # is a single character, and multiple fields may be specified. Returns a blessed object that the 'call' method will recognize when it is passed as the first argument to a subroutine in a callback. See description of 'call' method for details.

result ()

Returns the current Tcl interpreter result. List v. scalar context is handled as in Eval() above.

CreateCommand (CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC)

Binds a new procedure named CMDNAME into the interpreter. The CLIENTDATA and DELETEPROC arguments are optional. There are two cases:

(1) CMDPROC is the address of a C function

(presumably obtained using dl_open and dl_find_symbol. In this case CLIENTDATA and DELETEPROC are taken to be raw data of the ClientData and deleteProc field presumably obtained in a similar way.

(2) CMDPROC is a Perl subroutine

(either a sub name, a sub reference or an anonymous sub). In this case CLIENTDATA can be any perl scalar (e.g. a ref to some other data) and DELETEPROC must be a perl sub too. When CMDNAME is invoked in the Tcl interpeter, the arguments passed to the Perl sub CMDPROC are

    (CLIENTDATA, INTERP, LIST)

where INTERP is a Perl object for the Tcl interpreter which called out and LIST is a Perl list of the arguments CMDNAME was called with. As usual in Tcl, the first element of the list is CMDNAME itself. When CMDNAME is deleted from the interpreter (either explicitly with DeleteCommand or because the destructor for the interpeter object is called), it is passed the single argument CLIENTDATA.

DeleteCommand (CMDNAME)

Deletes command CMDNAME from the interpreter. If the command was created with a DELETEPROC (see CreateCommand above), then it is invoked at this point. When a Tcl interpreter object is destroyed either explicitly or implicitly, an implicit DeleteCommand happens on all its currently registered commands.

SetResult (STRING)

Sets Tcl interpreter result to STRING.

AppendResult (LIST)

Appends each element of LIST to Tcl's interpreter result object.

AppendElement (STRING)

Appends STRING to Tcl interpreter result object as an extra Tcl list element.

ResetResult ()

Resets Tcl interpreter result.

SplitList (STRING)

Splits STRING as a Tcl list. Returns a Perl list or the empty list if there was an error (i.e. STRING was not a properly formed Tcl list). In the latter case, the error message is left in Tcl's interpreter result object.

SetVar (VARNAME, VALUE, FLAGS)

The FLAGS field is optional. Sets Tcl variable VARNAME in the interpreter to VALUE. The FLAGS argument is the usual Tcl one and can be a bitwise OR of the constants Tcl::GLOBAL_ONLY, Tcl::LEAVE_ERR_MSG, Tcl::APPEND_VALUE, Tcl::LIST_ELEMENT.

SetVar2 (VARNAME1, VARNAME2, VALUE, FLAGS)

Sets the element VARNAME1(VARNAME2) of a Tcl array to VALUE. The optional argument FLAGS behaves as in SetVar above.

GetVar (VARNAME, FLAGS)

Returns the value of Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

GetVar2 (VARNAME1, VARNAME2, FLAGS)

Returns the value of the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

UnsetVar (VARNAME, FLAGS)

Unsets Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

UnsetVar2 (VARNAME1, VARNAME2, FLAGS)

Unsets the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

Linking Perl and Tcl variables

You can tie a Perl variable (scalar or hash) into class Tcl::Var so that changes to a Tcl variable automatically "change" the value of the Perl variable. In fact, as usual with Perl tied variables, its current value is just fetched from the Tcl variable when needed and setting the Perl variable triggers the setting of the Tcl variable.

To tie a Perl scalar $scalar to the Tcl variable tclscalar in interpreter $interp with optional flags $flags (see SetVar above), use

        tie $scalar, Tcl::Var, $interp, "tclscalar", $flags;

Omit the $flags argument if not wanted.

To tie a Perl hash %hash to the Tcl array variable array in interpreter $interp with optional flags $flags (see SetVar above), use

        tie %hash, Tcl::Var, $interp, "array", $flags;

Omit the $flags argument if not wanted. Any alteration to Perl variable $hash{"key"} affects the Tcl variable array(key) and vice versa.

Accessing Perl from within Tcl

After creation of Tcl interpreter, in addition to evaluation of Tcl/Tk commands within Perl, other way round also instantiated. Within a special namespace ::perl following objects are created:

   ::perl::Eval

So it is possible to use Perl objects from within Tcl.

Moving Tcl/Tk around with Tcl.pm

NOTE: explanations below is for developers managing Tcl/Tk installations itself, users should skip this section.

In order to create Tcl/Tk application with this module, you need to make sure that Tcl/Tk is available within visibility of this module. There are many ways to achieve this, varying on ease of starting things up and providing flexible moveable archived files.

Following list enumerates them, in order of increased possibility to change location.

  • First method

    Install Tcl/Tk first, then install Perl module Tcl, so installed Tcl/Tk will be used. This is most normal approach, and no care of Tcl/Tk distribution is taken on Perl side (this is done on Tcl/Tk side)

  • Second method

    Copy installed Tcl/Tk binaries to some location, then install Perl module Tcl with a special action to make Tcl.pm know of this location. This approach makes sure that only chosen Tcl installation is used.

  • Third method

    During compiling Tcl Perl module, Tcl/Tk could be statically linked into module's shared library and all other files zipped into a single archive, so each file extracted when needed.

    To link Tcl/Tk binaries, prepare their libraries and then instruct Makefile.PL to use these libraries in a link stage. (TODO provide better detailed description)

AUTHORS

Malcolm Beattie, mbeattie@sable.ox.ac.uk, 23 Oct 1994. Vadim Konovalov, vkon@cpan.org, 19 May 2003. Jeff Hobbs, jeff (a) activestate . com, 22 Mar 2004. Gisle Aas, gisle (a) activestate . com, 14 Apr 2004.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


tkkit - Single-file dynamic library bundle for Tcl/Tk functionality

    • Packages
  • LICENSE
  • SEE ALSO

NAME

tkkit - Single-file dynamic library bundle for Tcl/Tk functionality

DESCRIPTION

tkkit is a single-file dynamic library that bundles Tcl, Tk and several related extensions together for use by the Tcl module.

Tk is a toolkit for creating applications with graphical interfaces on Windows, Mac OS X and X11. The Tk toolkit is native to the Tcl programming language, but its ease of use and cross-platform availability has made it the GUI toolkit of choice for many other dynamic languages.

Tcl::Tk and Tkx are Perl modules that makes the Tk toolkit available to Perl programs. By loading one of these modules, Perl programs can create windows and fill them with text, images, buttons and other controls that make up the user interface of the application. See the Tkx::Tutorial docs for an example.

Packages

tkkit includes the following packages from the ActiveTcl http://aspn.activestate.com/ASPN/docs/ActiveTcl/at.pkg_index.html distribution:

Tcl 8.4 (core)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tcl/tcl_contents.htm

Tk 8.4 (core)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tcl/tk_contents.htm

TclX 8.4 (eXtended command set for Tcl)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tclx/TclX.n.html

vfs 1.3 (script level virtual file system access)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tclvfs/toc.html

tile 0.7 (themed widgets)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tile/index.html

bwidget 1.8 (extra megawidgets)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/bwidget/contents.html

Tktable 2.9 (2D table widget)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tktable/tkTable.html

treectrl 2.1 (multi-column hierarchical tree/list widget)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tktreectrl/toc.html

img::png (PNG image format)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/img/doc/img-png.html

img::ico (ICO image format)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/img/doc/img-ico.html

img::xpm (XPM image format)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/img/doc/img-xpm.html

ico (Windows ICO manipulation)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tklib/ico/ico.html

ctext (enhanced text widget)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tklib/ctext/ctext.html

tooltip (balloon help)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tklib/tooltip/tooltip.html

widget (megawidgets)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tklib/widget/widget.html

comm (remote interpreter communication)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tcllib/comm/comm.html

snit (object-oriented framework)

http://aspn.activestate.com/ASPN/docs/ActiveTcl/tcllib/snit/snit.html

LICENSE

This library is a component of ActivePerl and is covered under the same terms as ActivePerl.

Copyright 2007 ActiveState. All rights reserved.

SEE ALSO

the Tkx manpage the Tcl manpage


Term::ANSIColor - Color screen output using ANSI escape sequences

  • DIAGNOSTICS
  • ENVIRONMENT
  • RESTRICTIONS
  • NOTES
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT AND LICENSE

NAME

Term::ANSIColor - Color screen output using ANSI escape sequences

SYNOPSIS

    use Term::ANSIColor;
    print color 'bold blue';
    print "This text is bold blue.\n";
    print color 'reset';
    print "This text is normal.\n";
    print colored ("Yellow on magenta.\n", 'yellow on_magenta');
    print "This text is normal.\n";
    print colored ['yellow on_magenta'], "Yellow on magenta.\n";

    use Term::ANSIColor qw(uncolor);
    print uncolor '01;31', "\n";

    use Term::ANSIColor qw(:constants);
    print BOLD, BLUE, "This text is in bold blue.\n", RESET;

    use Term::ANSIColor qw(:constants);
    $Term::ANSIColor::AUTORESET = 1;
    print BOLD BLUE "This text is in bold blue.\n";
    print "This text is normal.\n";

DESCRIPTION

This module has two interfaces, one through color() and colored() and the other through constants. It also offers the utility function uncolor(), which has to be explicitly imported to be used (see SYNOPSIS).

color() takes any number of strings as arguments and considers them to be space-separated lists of attributes. It then forms and returns the escape sequence to set those attributes. It doesn't print it out, just returns it, so you'll have to print it yourself if you want to (this is so that you can save it as a string, pass it to something else, send it to a file handle, or do anything else with it that you might care to).

uncolor() performs the opposite translation, turning escape sequences into a list of strings.

The recognized attributes (all of which should be fairly intuitive) are clear, reset, dark, bold, underline, underscore, blink, reverse, concealed, black, red, green, yellow, blue, magenta, on_black, on_red, on_green, on_yellow, on_blue, on_magenta, on_cyan, and on_white. Case is not significant. Underline and underscore are equivalent, as are clear and reset, so use whichever is the most intuitive to you. The color alone sets the foreground color, and on_color sets the background color.

Note that not all attributes are supported by all terminal types, and some terminals may not support any of these sequences. Dark, blink, and concealed in particular are frequently not implemented.

Attributes, once set, last until they are unset (by sending the attribute "reset"). Be careful to do this, or otherwise your attribute will last after your script is done running, and people get very annoyed at having their prompt and typing changed to weird colors.

As an aid to help with this, colored() takes a scalar as the first argument and any number of attribute strings as the second argument and returns the scalar wrapped in escape codes so that the attributes will be set as requested before the string and reset to normal after the string. Alternately, you can pass a reference to an array as the first argument, and then the contents of that array will be taken as attributes and color codes and the remainder of the arguments as text to colorize.

Normally, colored() just puts attribute codes at the beginning and end of the string, but if you set $Term::ANSIColor::EACHLINE to some string, that string will be considered the line delimiter and the attribute will be set at the beginning of each line of the passed string and reset at the end of each line. This is often desirable if the output is being sent to a program like a pager that can be confused by attributes that span lines. Normally you'll want to set $Term::ANSIColor::EACHLINE to "\n" to use this feature.

Alternately, if you import :constants, you can use the constants CLEAR, RESET, BOLD, DARK, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN, and ON_WHITE directly. These are the same as color('attribute') and can be used if you prefer typing:

    print BOLD BLUE ON_WHITE "Text\n", RESET;

to

    print colored ("Text\n", 'bold blue on_white');

When using the constants, if you don't want to have to remember to add the , RESET at the end of each print line, you can set $Term::ANSIColor::AUTORESET to a true value. Then, the display mode will automatically be reset if there is no comma after the constant. In other words, with that variable set:

    print BOLD BLUE "Text\n";

will reset the display mode afterwards, whereas:

    print BOLD, BLUE, "Text\n";

will not.

The subroutine interface has the advantage over the constants interface in that only two subroutines are exported into your namespace, versus twenty-two in the constants interface. On the flip side, the constants interface has the advantage of better compile time error checking, since misspelled names of colors or attributes in calls to color() and colored() won't be caught until runtime whereas misspelled names of constants will be caught at compile time. So, polute your namespace with almost two dozen subroutines that you may not even use that often, or risk a silly bug by mistyping an attribute. Your choice, TMTOWTDI after all.

DIAGNOSTICS

Bad escape sequence %s

(F) You passed an invalid ANSI escape sequence to uncolor().

Bareword "%s" not allowed while "strict subs" in use

(F) You probably mistyped a constant color name such as:

    $Foobar = FOOBAR . "This line should be blue\n";

or:

    @Foobar = FOOBAR, "This line should be blue\n";

This will only show up under use strict (another good reason to run under use strict).

Invalid attribute name %s

(F) You passed an invalid attribute name to either color() or colored().

Name "%s" used only once: possible typo

(W) You probably mistyped a constant color name such as:

    print FOOBAR "This text is color FOOBAR\n";

It's probably better to always use commas after constant names in order to force the next error.

No comma allowed after filehandle

(F) You probably mistyped a constant color name such as:

    print FOOBAR, "This text is color FOOBAR\n";

Generating this fatal compile error is one of the main advantages of using the constants interface, since you'll immediately know if you mistype a color name.

No name for escape sequence %s

(F) The ANSI escape sequence passed to uncolor() contains escapes which aren't recognized and can't be translated to names.

ENVIRONMENT

ANSI_COLORS_DISABLED

If this environment variable is set, all of the functions defined by this module (color(), colored(), and all of the constants not previously used in the program) will not output any escape sequences and instead will just return the empty string or pass through the original text as appropriate. This is intended to support easy use of scripts using this module on platforms that don't support ANSI escape sequences.

For it to have its proper effect, this environment variable must be set before any color constants are used in the program.

RESTRICTIONS

It would be nice if one could leave off the commas around the constants entirely and just say:

    print BOLD BLUE ON_WHITE "Text\n" RESET;

but the syntax of Perl doesn't allow this. You need a comma after the string. (Of course, you may consider it a bug that commas between all the constants aren't required, in which case you may feel free to insert commas unless you're using $Term::ANSIColor::AUTORESET.)

For easier debuging, you may prefer to always use the commas when not setting $Term::ANSIColor::AUTORESET so that you'll get a fatal compile error rather than a warning.

NOTES

The codes generated by this module are standard terminal control codes, complying with ECMA-48 and ISO 6429 (generally referred to as "ANSI color" for the color codes). The non-color control codes (bold, dark, italic, underline, and reverse) are part of the earlier ANSI X3.64 standard for control sequences for video terminals and peripherals.

Note that not all displays are ISO 6429-compliant, or even X3.64-compliant (or are even attempting to be so). This module will not work as expected on displays that do not honor these escape sequences, such as cmd.exe, 4nt.exe, and command.com under either Windows NT or Windows 2000. They may just be ignored, or they may display as an ESC character followed by some apparent garbage.

Jean Delvare provided the following table of different common terminal emulators and their support for the various attributes and others have helped me flesh it out:

              clear    bold     dark    under    blink   reverse  conceal
 ------------------------------------------------------------------------
 xterm         yes      yes      no      yes     bold      yes      yes
 linux         yes      yes      yes    bold      yes      yes      no
 rxvt          yes      yes      no      yes  bold/black   yes      no
 dtterm        yes      yes      yes     yes    reverse    yes      yes
 teraterm      yes    reverse    no      yes    rev/red    yes      no
 aixterm      kinda   normal     no      yes      no       yes      yes
 PuTTY         yes     color     no      yes      no       yes      no
 Windows       yes      no       no      no       no       yes      no
 Cygwin SSH    yes      yes      no     color    color    color     yes
 Mac Terminal  yes      yes      no      yes      yes      yes      yes

Windows is Windows telnet, Cygwin SSH is the OpenSSH implementation under Cygwin on Windows NT, and Mac Terminal is the Terminal application in Mac OS X. Where the entry is other than yes or no, that emulator displays the given attribute as something else instead. Note that on an aixterm, clear doesn't reset colors; you have to explicitly set the colors back to what you want. More entries in this table are welcome.

Note that codes 3 (italic), 6 (rapid blink), and 9 (strikethrough) are specified in ANSI X3.64 and ECMA-048 but are not commonly supported by most displays and emulators and therefore aren't supported by this module at the present time. ECMA-048 also specifies a large number of other attributes, including a sequence of attributes for font changes, Fraktur characters, double-underlining, framing, circling, and overlining. As none of these attributes are widely supported or useful, they also aren't currently supported by this module.

SEE ALSO

ECMA-048 is available on-line (at least at the time of this writing) at http://www.ecma-international.org/publications/standards/ECMA-048.HTM.

ISO 6429 is available from ISO for a charge; the author of this module does not own a copy of it. Since the source material for ISO 6429 was ECMA-048 and the latter is available for free, there seems little reason to obtain the ISO standard.

The current version of this module is always available from its web site at http://www.eyrie.org/~eagle/software/ansicolor/. It is also part of the Perl core distribution as of 5.6.0.

AUTHORS

Original idea (using constants) by Zenin, reimplemented using subs by Russ Allbery <rra@stanford.edu>, and then combined with the original idea by Russ with input from Zenin. Russ Allbery now maintains this module.

COPYRIGHT AND LICENSE

Copyright 1996, 1997, 1998, 2000, 2001, 2002 Russ Allbery <rra@stanford.edu> and Zenin. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


Term::ANSIScreen - Terminal control using ANSI escape sequences

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • NOTES
  • FUNCTIONS
    • Win32::Console emulation mode
    • The :color function set (exported by default)
    • The :constants function set
    • The :cursor function set
    • The :screen function set
    • The :keyboard function set
  • DIAGNOSTICS
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

Term::ANSIScreen - Terminal control using ANSI escape sequences

VERSION

This document describes version 1.41 of Term::ANSIScreen, released March 22, 2004.

SYNOPSIS

    # qw/:color/ is exported by default, i.e. color() & colored()

    use Term::ANSIScreen qw/:color :cursor :screen :keyboard/;

    print setmode(1), setkey('a','b');
    print "40x25 mode now, with 'a' mapped to 'b'.";
    <STDIN>; resetkey; setmode 3; cls;

    locate 1, 1; print "@ This is (1,1)", savepos;
    print locate(24,60), "@ This is (24,60)"; loadpos;
    print down(2), clline, "@ This is (3,15)\n";

    setscroll 1, 20;

    color 'black on white'; clline;
    print "This line is black on white.\n";
    print color 'reset'; print "This text is normal.\n";

    print colored ("This text is bold blue.\n", 'bold blue');
    print "This text is normal.\n";
    print colored ['bold blue'], "This text is bold blue.\n";
    print "This text is normal.\n";

    use Term::ANSIScreen qw/:constants/; # constants mode
    print BLUE ON GREEN . "Blue on green.\n";

    $Term::ANSIScreen::AUTORESET = 1;
    print BOLD GREEN . ON_BLUE "Bold green on blue.", CLEAR;
    print "\nThis text is normal.\n";

    # Win32::Console emulation mode
    # this returns a Win32::Console object on a Win32 platform
    my $console = Term::ANSIScreen->new;
    $console->Cls;      # also works on non-Win32 platform

DESCRIPTION

Term::ANSIScreen is a superset of Term::ANSIColor (as of version 1.04 of that module). In addition to color-sequence generating subroutines exported by :color and :constants, this module also features :cursor for cursor positioning, :screen for screen control, as well as :keyboard for key mapping.

NOTES

  • All subroutines in Term::ANSIScreen will print its return value if called under a void context.

  • The cursor position, current color, screen mode and keyboard mappings affected by Term::ANSIScreen will last after the program terminates. You might want to reset them before the end of your program.

FUNCTIONS

Win32::Console emulation mode

When used in a object-oriented fashion, Term::ANSIScreen acts as a Win32::Console clone:

    use Term::ANSIScreen;
    my $console = Term::ANSIScreen->new;
    $console->Cls();            # unbuffered
    $console->Cursor(0, 0);     # same as locate(1, 1)
    $console->Display();        # really a no-op

On the Win32 platform, the new constructor simply returns a geniune Win32::Console object, if that module exists in the system.

This feature is intended for people who has to port Win32 console applications to other platforms, or to write cross-platform application that needs terminal controls.

The :color function set (exported by default)

Term::ANSIScreen recognizes (case-insensitively) following color attributes: clear, reset, bold, underline, underscore, blink, reverse, concealed, black, red, green, yellow, blue, magenta, on_black, on_red, on_green, on_yellow, on_blue, on_magenta, on_cyan, and on_white.

The color alone sets the foreground color, and on_color sets the background color. You may also use on_color without the underscore, e.g. "black on white".

color LIST

Takes any number of strings as arguments and considers them to be space-separated lists of attributes. It then forms and returns the escape sequence to set those attributes.

colored EXPR, LIST

Takes a scalar as the first argument and any number of attribute strings as the second argument, then returns the scalar wrapped in escape codes so that the attributes will be set as requested before the string and reset to normal after the string.

Alternately, you can pass a reference to an array as the first argument, and then the contents of that array will be taken as attributes and color codes and the remainder of the arguments as text to colorize.

Normally, this function just puts attribute codes at the beginning and end of the string, but if you set $Term::ANSIScreen::EACHLINE to some string, that string will be considered the line delimiter and the attribute will be set at the beginning of each line of the passed string and reset at the end of each line. This is often desirable if the output is being sent to a program like a pager, which can be confused by attributes that span lines.

Normally you'll want to set $Term::ANSIScreen::EACHLINE to "\n" to use this feature.

The :constants function set

If you import :constants you can use the constants CLEAR, RESET, BOLD, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW, ON_BLUE, ON_MAGENTA, ON_CYAN, and ON_WHITE directly. These are the same as color('attribute') and can be used if you prefer typing:

    print BOLD BLUE ON_WHITE "Text\n", RESET;
    print BOLD BLUE ON WHITE "Text\n", RESET; # _ is optional

to print colored ("Text\n", 'bold blue on_white');

When using the constants, if you don't want to have to remember to add the , RESET at the end of each print line, you can set $Term::ANSIScreen::AUTORESET to a true value. Then, the display mode will automatically be reset if there is no comma after the constant. In other words, with that variable set:

    print BOLD BLUE "Text\n";

will reset the display mode afterwards, whereas:

    print BOLD, BLUE, "Text\n";

will not.

The :cursor function set

locate [EXPR, EXPR]

Sets the cursor position. The first argument is its row number, and the second one its column number. If omitted, the cursor will be located at (1,1).

up [EXPR]
down [EXPR]
left [EXPR]
right [EXPR]

Moves the cursor toward any direction for EXPR characters. If omitted, EXPR is 1.

savepos
loadpos

Saves/restores the current cursor position.

The :screen function set

cls

Clears the screen with the current background color, and set cursor to (1,1).

clline

Clears the current row with the current background color, and set cursor to the 1st column.

clup

Clears everything above the cursor.

cldown

Clears everything below the cursor.

setmode EXPR

Sets the screen mode to EXPR. Under DOS, ANSI.SYS recognizes following values:

     0:  40 x  25 x   2 (text)   1:  40 x  25 x 16 (text)
     2:  80 x  25 x   2 (text)   3:  80 x  25 x 16 (text)
     4: 320 x 200 x   4          5: 320 x 200 x  2
     6: 640 x 200 x   2          7: Enables line wrapping
    13: 320 x 200 x   4         14: 640 x 200 x 16
    15: 640 x 350 x   2         16: 640 x 350 x 16
    17: 640 x 480 x   2         18: 640 x 480 x 16
    19: 320 x 200 x 256
wrapon
wrapoff

Enables/disables the line-wraping mode.

setscroll EXPR, EXPR

Causes scrolling to occur only on the lines numbered between the first and second arguments, inclusive.

The :keyboard function set

setkey EXPR, EXPR

Takes a scalar representing a single keystroke as the first argument (either a character or an escape sequence in the form of "num1;num2"), and maps it to a string defined by the second argument. Afterwards, when the user presses the mapped key, the string will get outputed instead.

resetkey [LIST]

Resets each keys in the argument list to its original mapping. If called without an argument, resets all previously mapped keys.

DIAGNOSTICS

Invalid attribute name %s

You passed an invalid attribute name to either color() or colored().

Identifier %s used only once: possible typo

You probably mistyped a constant color name such as:

    print FOOBAR "This text is color FOOBAR\n";

It's probably better to always use commas after constant names in order to force the next error.

No comma allowed after filehandle

You probably mistyped a constant color name such as:

    print FOOBAR, "This text is color FOOBAR\n";

Generating this fatal compile error is one of the main advantages of using the constants interface, since you'll immediately know if you mistype a color name.

Bareword %s not allowed while "strict subs" in use

You probably mistyped a constant color name such as:

    $Foobar = FOOBAR . "This line should be blue\n";

or:

    @Foobar = FOOBAR, "This line should be blue\n";

This will only show up under use strict (another good reason to run under use strict).

SEE ALSO

the Term::ANSIColor manpage, the Win32::Console manpage

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

Copyright 2001, 2003, 2003, 2004 by Autrijus Tang <autrijus@autrijus.org>.

Based on works of Zenin (zenin@bawdycaste.com), Russ Allbery (rra@stanford.edu)

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Term::Cap - Perl termcap interface

    • METHODS
  • EXAMPLES
  • COPYRIGHT AND LICENSE
  • AUTHOR
  • SEE ALSO

NAME

Term::Cap - Perl termcap interface

SYNOPSIS

    require Term::Cap;
    $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
    $terminal->Trequire(qw/ce ku kd/);
    $terminal->Tgoto('cm', $col, $row, $FH);
    $terminal->Tputs('dl', $count, $FH);
    $terminal->Tpad($string, $count, $FH);

DESCRIPTION

These are low-level functions to extract and use capabilities from a terminal capability (termcap) database.

More information on the terminal capabilities will be found in the termcap manpage on most Unix-like systems.

METHODS

The output strings for Tputs are cached for counts of 1 for performance. Tgoto and Tpad do not cache. $self->{_xx} is the raw termcap data and $self->{xx} is the cached version.

    print $terminal->Tpad($self->{_xx}, 1);

Tgoto, Tputs, and Tpad return the string and will also output the string to $FH if specified.

Tgetent

Returns a blessed object reference which the user can then use to send the control strings to the terminal using Tputs and Tgoto.

The function extracts the entry of the specified terminal type TERM (defaults to the environment variable TERM) from the database.

It will look in the environment for a TERMCAP variable. If found, and the value does not begin with a slash, and the terminal type name is the same as the environment string TERM, the TERMCAP string is used instead of reading a termcap file. If it does begin with a slash, the string is used as a path name of the termcap file to search. If TERMCAP does not begin with a slash and name is different from TERM, Tgetent searches the files $HOME/.termcap, /etc/termcap, and /usr/share/misc/termcap, in that order, unless the environment variable TERMPATH exists, in which case it specifies a list of file pathnames (separated by spaces or colons) to be searched instead. Whenever multiple files are searched and a tc field occurs in the requested entry, the entry it names must be found in the same file or one of the succeeding files. If there is a :tc=...: in the TERMCAP environment variable string it will continue the search in the files as above.

The extracted termcap entry is available in the object as $self->{TERMCAP}.

It takes a hash reference as an argument with two optional keys:

OSPEED

The terminal output bit rate (often mistakenly called the baud rate) for this terminal - if not set a warning will be generated and it will be defaulted to 9600. OSPEED can be be specified as either a POSIX termios/SYSV termio speeds (where 9600 equals 9600) or an old DSD-style speed ( where 13 equals 9600).

TERM

The terminal type whose termcap entry will be used - if not supplied it will default to $ENV{TERM}: if that is not set then Tgetent will croak.

It calls croak on failure.

Tpad

Outputs a literal string with appropriate padding for the current terminal.

It takes three arguments:

$string

The literal string to be output. If it starts with a number and an optional '*' then the padding will be increased by an amount relative to this number, if the '*' is present then this amount will me multiplied by $cnt. This part of $string is removed before output/

$cnt

Will be used to modify the padding applied to string as described above.

$FH

An optional filehandle (or IO::Handle ) that output will be printed to.

The padded $string is returned.

Tputs

Output the string for the given capability padded as appropriate without any parameter substitution.

It takes three arguments:

$cap

The capability whose string is to be output.

$cnt

A count passed to Tpad to modify the padding applied to the output string. If $cnt is zero or one then the resulting string will be cached.

$FH

An optional filehandle (or IO::Handle ) that output will be printed to.

The appropriate string for the capability will be returned.

Tgoto

Tgoto decodes a cursor addressing string with the given parameters.

There are four arguments:

$cap

The name of the capability to be output.

$col

The first value to be substituted in the output string ( usually the column in a cursor addressing capability )

$row

The second value to be substituted in the output string (usually the row in cursor addressing capabilities)

$FH

An optional filehandle (or IO::Handle ) to which the output string will be printed.

Substitutions are made with $col and $row in the output string with the following sprintf() line formats:

 %%   output `%'
 %d   output value as in printf %d
 %2   output value as in printf %2d
 %3   output value as in printf %3d
 %.   output value as in printf %c
 %+x  add x to value, then do %.
 %>xy if value > x then add y, no output
 %r   reverse order of two parameters, no output
 %i   increment by one, no output
 %B   BCD (16*(value/10)) + (value%10), no output
 %n   exclusive-or all parameters with 0140 (Datamedia 2500)
 %D   Reverse coding (value - 2*(value%16)), no output (Delta Data)

The output string will be returned.

Trequire

Takes a list of capabilities as an argument and will croak if one is not found.

EXAMPLES

    use Term::Cap;

    # Get terminal output speed
    require POSIX;
    my $termios = new POSIX::Termios;
    $termios->getattr;
    my $ospeed = $termios->getospeed;

    # Old-style ioctl code to get ospeed:
    #     require 'ioctl.pl';
    #     ioctl(TTY,$TIOCGETP,$sgtty);
    #     ($ispeed,$ospeed) = unpack('cc',$sgtty);

    # allocate and initialize a terminal structure
    $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };

    # require certain capabilities to be available
    $terminal->Trequire(qw/ce ku kd/);

    # Output Routines, if $FH is undefined these just return the string

    # Tgoto does the % expansion stuff with the given args
    $terminal->Tgoto('cm', $col, $row, $FH);

    # Tputs doesn't do any % expansion.
    $terminal->Tputs('dl', $count = 1, $FH);

COPYRIGHT AND LICENSE

Please see the README file in distribution.

AUTHOR

This module is part of the core Perl distribution and is also maintained for CPAN by Jonathan Stowe <jns@gellyfish.com>.

SEE ALSO

termcap(5)


Term::Complete - Perl word completion module

  • DIAGNOSTICS
  • BUGS
  • AUTHOR

NAME

Term::Complete - Perl word completion module

SYNOPSIS

    $input = Complete('prompt_string', \@completion_list);
    $input = Complete('prompt_string', @completion_list);

DESCRIPTION

This routine provides word completion on the list of words in the array (or array ref).

The tty driver is put into raw mode and restored using an operating system specific command, in UNIX-like environments stty.

The following command characters are defined:

<tab>

Attempts word completion. Cannot be changed.

^D

Prints completion list. Defined by $Term::Complete::complete.

^U

Erases the current input. Defined by $Term::Complete::kill.

<del>, <bs>

Erases one character. Defined by $Term::Complete::erase1 and $Term::Complete::erase2.

DIAGNOSTICS

Bell sounds when word completion fails.

BUGS

The completion character <tab> cannot be changed.

AUTHOR

Wayne Thompson


Term::Pager - Page through text, a screenful at a time, like more or less

  • USAGE
    • Create the Pager
    • Adding Text
  • FEATURES
  • SEE ALSO
  • AUTHOR

NAME

Term::Pager - Page through text, a screenful at a time, like more or less

SYNOPSIS

    use Term::Pager;

    my $t = Term::Pager->new( rows => 25, cols => 80 );
    $t->add_text( $text );
    $t->more();

DESCRIPTION

This is a module for paging through text one screenful at a time. It supports the features you expect, including backwards movement and searching. It uses the keys you expect.

USAGE

Create the Pager

    $t = Term::Pager->new( option => value, ... );

If no options are specified, sensible default values will be used. The following options are recognized:

rows

The number of rows on your terminal. This defaults to 25.

=item C<cols>

The number of columns on your terminal. This defaults to 80.

speed

The speed (baud rate) of your terminal. Will default to a sensible value.

=back

Adding Text

You will need some text to page through. You can specify text as
as a parameter to the constructor:
    text => $text

Or add text later:

    $t->add_text( $text );

FEATURES

This code uses termcap. If the termcap entry for your ancient esoteric terminal is wrong or incomplete, this module may either fill your screen with unintelligible gibberish, or drop back to a feature-free mode.

SEE ALSO

    Term::Cap, termcap(5), more(1), less(1)
    Yellowstone National Park

AUTHOR

    Jeff Weisberg - http://www.tcp4me.com


Term::ReadKey - A perl module for simple terminal control

  • AUTHOR

NAME

Term::ReadKey - A perl module for simple terminal control

SYNOPSIS

        use Term::ReadKey;
        ReadMode 4; # Turn off controls keys
        while (not defined ($key = ReadKey(-1))) {
                # No key yet
        }
        print "Get key $key\n";
        ReadMode 0; # Reset tty mode before exiting

DESCRIPTION

Term::ReadKey is a compiled perl module dedicated to providing simple control over terminal driver modes (cbreak, raw, cooked, etc.,) support for non-blocking reads, if the architecture allows, and some generalized handy functions for working with terminals. One of the main goals is to have the functions as portable as possible, so you can just plug in "use Term::ReadKey" on any architecture and have a good likelyhood of it working.

ReadMode MODE [, Filehandle]

Takes an integer argument, which can currently be one of the following values:

    0    Restore original settings.
    1    Change to cooked mode.
    2    Change to cooked mode with echo off.
          (Good for passwords)
    3    Change to cbreak mode.
    4    Change to raw mode.
    5    Change to ultra-raw mode.
          (LF to CR/LF translation turned off)
    Or, you may use the synonyms:
    restore
    normal
    noecho
    cbreak
    raw
    ultra-raw

These functions are automatically applied to the STDIN handle if no other handle is supplied. Modes 0 and 5 have some special properties worth mentioning: not only will mode 0 restore original settings, but it cause the next ReadMode call to save a new set of default settings. Mode 5 is similar to mode 4, except no CR/LF translation is performed, and if possible, parity will be disabled (only if not being used by the terminal, however. It is no different from mode 4 under Windows.)

If you are executing another program that may be changing the terminal mode, you will either want to say

    ReadMode 1
    system('someprogram');
    ReadMode 1;

which resets the settings after the program has run, or:

    $somemode=1;
    ReadMode 0;
    system('someprogram');
    ReadMode 1;

which records any changes the program may have made, before resetting the mode.

ReadKey MODE [, Filehandle]

Takes an integer argument, which can currently be one of the following values:

    0    Perform a normal read using getc
    -1   Perform a non-blocked read
    >0   Perform a timed read

(If the filehandle is not supplied, it will default to STDIN.) If there is nothing waiting in the buffer during a non-blocked read, then undef will be returned. Note that if the OS does not provide any known mechanism for non-blocking reads, then a ReadKey -1 can die with a fatal error. This will hopefully not be common.

If MODE is greater then zero, then ReadKey will use it as a timeout value in seconds (fractional seconds are allowed), and won't return undef until that time expires. (Note, again, that some OS's may not support this timeout behaviour.) If MODE is less then zero, then this is treated as a timeout of zero, and thus will return immediately if no character is waiting. A MODE of zero, however, will act like a normal getc.

There are currently some limitations with this call under Windows. It may be possible that non-blocking reads will fail when reading repeating keys from more then one console.

ReadLine MODE [, Filehandle]

Takes an integer argument, which can currently be one of the following values:

    0    Perform a normal read using scalar(<FileHandle>)
    -1   Perform a non-blocked read
    >0   Perform a timed read

If there is nothing waiting in the buffer during a non-blocked read, then undef will be returned. Note that if the OS does not provide any known mechanism for non-blocking reads, then a ReadLine 1 can die with a fatal error. This will hopefully not be common. Note that a non-blocking test is only performed for the first character in the line, not the entire line. This call will probably not do what you assume, especially with ReadMode's higher then 1. For example, pressing Space and then Backspace would appear to leave you where you started, but any timeouts would now be suspended.

This call is currently not available under Windows.

GetTerminalSize [Filehandle]

Returns either an empty array if this operation is unsupported, or a four element array containing: the width of the terminal in characters, the height of the terminal in character, the width in pixels, and the height in pixels. (The pixel size will only be valid in some environments.)

Under Windows, this function must be called with an "output" filehandle, such as STDOUT, or a handle opened to CONOUT$.

SetTerminalSize WIDTH,HEIGHT,XPIX,YPIX [, Filehandle]

Return -1 on failure, 0 otherwise. Note that this terminal size is only for informative value, and changing the size via this mechanism will not change the size of the screen. For example, XTerm uses a call like this when it resizes the screen. If any of the new measurements vary from the old, the OS will probably send a SIGWINCH signal to anything reading that tty or pty.

This call does not work under Windows.

GetSpeeds [, Filehandle]

Returns either an empty array if the operation is unsupported, or a two value array containing the terminal in and out speeds, in decimal. E.g, an in speed of 9600 baud and an out speed of 4800 baud would be returned as (9600,4800). Note that currently the in and out speeds will always be identical in some OS's. No speeds are reported under Windows.

GetControlChars [, Filehandle]

Returns an array containing key/value pairs suitable for a hash. The pairs consist of a key, the name of the control character/signal, and the value of that character, as a single character. This call does nothing under Windows.

Each key will be an entry from the following list:

        DISCARD
        DSUSPEND
        EOF
        EOL
        EOL2
        ERASE
        ERASEWORD
        INTERRUPT
        KILL
        MIN
        QUIT
        QUOTENEXT
        REPRINT
        START
        STATUS
        STOP
        SUSPEND
        SWITCH
        TIME

Thus, the following will always return the current interrupt character, regardless of platform.

        %keys = GetControlChars;
        $int = $keys{INTERRUPT};
SetControlChars [, Filehandle]

Takes an array containing key/value pairs, as a hash will produce. The pairs should consist of a key that is the name of a legal control character/signal, and the value should be either a single character, or a number in the range 0-255. SetControlChars will die with a runtime error if an invalid character name is passed or there is an error changing the settings. The list of valid names is easily available via

        %cchars = GetControlChars();
        @cnames = keys %cchars;

This call does nothing under Windows.

AUTHOR

Kenneth Albanowski <kjahds@kjahds.com>

Currently maintained by Jonathan Stowe <jns@gellyfish.com>


Term::ReadLine - Perl interface to various C<readline> packages. If no real package is found, substitutes stubs instead of basic functions.

  • Minimal set of supported functions
  • Additional supported functions
  • EXPORTS
  • ENVIRONMENT
  • CAVEATS

NAME

Term::ReadLine - Perl interface to various readline packages. If no real package is found, substitutes stubs instead of basic functions.

SYNOPSIS

  use Term::ReadLine;
  my $term = new Term::ReadLine 'Simple Perl calc';
  my $prompt = "Enter your arithmetic expression: ";
  my $OUT = $term->OUT || \*STDOUT;
  while ( defined ($_ = $term->readline($prompt)) ) {
    my $res = eval($_);
    warn $@ if $@;
    print $OUT $res, "\n" unless $@;
    $term->addhistory($_) if /\S/;
  }

DESCRIPTION

This package is just a front end to some other packages. It's a stub to set up a common interface to the various ReadLine implementations found on CPAN (under the Term::ReadLine::* namespace).

Minimal set of supported functions

All the supported functions should be called as methods, i.e., either as

  $term = new Term::ReadLine 'name';

or as

  $term->addhistory('row');

where $term is a return value of Term::ReadLine->new().

ReadLine

returns the actual package that executes the commands. Among possible values are Term::ReadLine::Gnu, Term::ReadLine::Perl, Term::ReadLine::Stub.

new

returns the handle for subsequent calls to following functions. Argument is the name of the application. Optionally can be followed by two arguments for IN and OUT filehandles. These arguments should be globs.

readline

gets an input line, possibly with actual readline support. Trailing newline is removed. Returns undef on EOF.

addhistory

adds the line to the history of input, from where it can be used if the actual readline is present.

IN, OUT

return the filehandles for input and output or undef if readline input and output cannot be used for Perl.

MinLine

If argument is specified, it is an advice on minimal size of line to be included into history. undef means do not include anything into history. Returns the old value.

findConsole

returns an array with two strings that give most appropriate names for files for input and output using conventions "<$in", ">out".

Attribs

returns a reference to a hash which describes internal configuration of the package. Names of keys in this hash conform to standard conventions with the leading rl_ stripped.

Features

Returns a reference to a hash with keys being features present in current implementation. Several optional features are used in the minimal interface: appname should be present if the first argument to new is recognized, and minline should be present if MinLine method is not dummy. autohistory should be present if lines are put into history automatically (maybe subject to MinLine), and addhistory if addhistory method is not dummy.

If Features method reports a feature attribs as present, the method Attribs is not dummy.

Additional supported functions

Actually Term::ReadLine can use some other package, that will support a richer set of commands.

All these commands are callable via method interface and have names which conform to standard conventions with the leading rl_ stripped.

The stub package included with the perl distribution allows some additional methods:

tkRunning

makes Tk event loop run when waiting for user input (i.e., during readline method).

ornaments

makes the command line stand out by using termcap data. The argument to ornaments should be 0, 1, or a string of a form "aa,bb,cc,dd". Four components of this string should be names of terminal capacities, first two will be issued to make the prompt standout, last two to make the input line standout.

newTTY

takes two arguments which are input filehandle and output filehandle. Switches to use these filehandles.

One can check whether the currently loaded ReadLine package supports these methods by checking for corresponding Features.

EXPORTS

None

ENVIRONMENT

The environment variable PERL_RL governs which ReadLine clone is loaded. If the value is false, a dummy interface is used. If the value is true, it should be tail of the name of the package to use, such as Perl or Gnu.

As a special case, if the value of this variable is space-separated, the tail might be used to disable the ornaments by setting the tail to be o=0 or ornaments=0. The head should be as described above, say

If the variable is not set, or if the head of space-separated list is empty, the best available package is loaded.

  export "PERL_RL=Perl o=0"     # Use Perl ReadLine without ornaments
  export "PERL_RL= o=0"         # Use best available ReadLine without ornaments

(Note that processing of PERL_RL for ornaments is in the discretion of the particular used Term::ReadLine::* package).

CAVEATS

It seems that using Term::ReadLine from Emacs minibuffer doesn't work quite right and one will get an error message like

    Cannot open /dev/tty for read at ...

One possible workaround for this is to explicitly open /dev/tty like this

    open (FH, "/dev/tty" )
      or eval 'sub Term::ReadLine::findConsole { ("&STDIN", "&STDERR") }';
    die $@ if $@;
    close (FH);

or you can try using the 4-argument form of Term::ReadLine->new().


Test - provides a simple framework for writing test scripts

  • QUICK START GUIDE
    • Functions
  • TEST TYPES
  • ONFAIL
  • BUGS and CAVEATS
  • ENVIRONMENT
  • NOTE
  • SEE ALSO
  • AUTHOR

NAME

Test - provides a simple framework for writing test scripts

SYNOPSIS

  use strict;
  use Test;

  # use a BEGIN block so we print our plan before MyModule is loaded
  BEGIN { plan tests => 14, todo => [3,4] }

  # load your module...
  use MyModule;

  # Helpful notes.  All note-lines must start with a "#".
  print "# I'm testing MyModule version $MyModule::VERSION\n";

  ok(0); # failure
  ok(1); # success

  ok(0); # ok, expected failure (see todo list, above)
  ok(1); # surprise success!

  ok(0,1);             # failure: '0' ne '1'
  ok('broke','fixed'); # failure: 'broke' ne 'fixed'
  ok('fixed','fixed'); # success: 'fixed' eq 'fixed'
  ok('fixed',qr/x/);   # success: 'fixed' =~ qr/x/

  ok(sub { 1+1 }, 2);  # success: '2' eq '2'
  ok(sub { 1+1 }, 3);  # failure: '2' ne '3'

  my @list = (0,0);
  ok @list, 3, "\@list=".join(',',@list);      #extra notes
  ok 'segmentation fault', '/(?i)success/';    #regex match

  skip(
    $^O =~ m/MSWin/ ? "Skip if MSWin" : 0,  # whether to skip
    $foo, $bar  # arguments just like for ok(...)
  );
  skip(
    $^O =~ m/MSWin/ ? 0 : "Skip unless MSWin",  # whether to skip
    $foo, $bar  # arguments just like for ok(...)
  );

DESCRIPTION

This module simplifies the task of writing test files for Perl modules, such that their output is in the format that Test::Harness expects to see.

QUICK START GUIDE

To write a test for your new (and probably not even done) module, create a new file called t/test.t (in a new t directory). If you have multiple test files, to test the "foo", "bar", and "baz" feature sets, then feel free to call your files t/foo.t, t/bar.t, and t/baz.t

Functions

This module defines three public functions, plan(...), ok(...), and skip(...). By default, all three are exported by the use Test; statement.

plan(...)
     BEGIN { plan %theplan; }

This should be the first thing you call in your test script. It declares your testing plan, how many there will be, if any of them should be allowed to fail, and so on.

Typical usage is just:

     use Test;
     BEGIN { plan tests => 23 }

These are the things that you can put in the parameters to plan:

tests => number

The number of tests in your script. This means all ok() and skip() calls.

todo => [1,5,14]

A reference to a list of tests which are allowed to fail. See TODO TESTS.

onfail => sub { ... }
onfail => \&some_sub

A subroutine reference to be run at the end of the test script, if any of the tests fail. See ONFAIL.

You must call plan(...) once and only once. You should call it in a BEGIN {...} block, like so:

     BEGIN { plan tests => 23 }
ok(...)
  ok(1 + 1 == 2);
  ok($have, $expect);
  ok($have, $expect, $diagnostics);

This function is the reason for Test's existence. It's the basic function that handles printing "ok" or "not ok", along with the current test number. (That's what Test::Harness wants to see.)

In its most basic usage, ok(...) simply takes a single scalar expression. If its value is true, the test passes; if false, the test fails. Examples:

    # Examples of ok(scalar)

    ok( 1 + 1 == 2 );           # ok if 1 + 1 == 2
    ok( $foo =~ /bar/ );        # ok if $foo contains 'bar'
    ok( baz($x + $y) eq 'Armondo' );    # ok if baz($x + $y) returns
                                        # 'Armondo'
    ok( @a == @b );             # ok if @a and @b are the same length

The expression is evaluated in scalar context. So the following will work:

    ok( @stuff );                       # ok if @stuff has any elements
    ok( !grep !defined $_, @stuff );    # ok if everything in @stuff is
                                        # defined.

A special case is if the expression is a subroutine reference (in either sub {...} syntax or \&foo syntax). In that case, it is executed and its value (true or false) determines if the test passes or fails. For example,

    ok( sub {   # See whether sleep works at least passably
      my $start_time = time;
      sleep 5;
      time() - $start_time  >= 4
    });

In its two-argument form, ok(arg1, arg2) compares the two scalar values to see if they match. They match if both are undefined, or if arg2 is a regex that matches arg1, or if they compare equal with eq.

    # Example of ok(scalar, scalar)

    ok( "this", "that" );               # not ok, 'this' ne 'that'
    ok( "", undef );                    # not ok, "" is defined

The second argument is considered a regex if it is either a regex object or a string that looks like a regex. Regex objects are constructed with the qr// operator in recent versions of perl. A string is considered to look like a regex if its first and last characters are "/", or if the first character is "m" and its second and last characters are both the same non-alphanumeric non-whitespace character. These regexp

Regex examples:

    ok( 'JaffO', '/Jaff/' );    # ok, 'JaffO' =~ /Jaff/
    ok( 'JaffO', 'm|Jaff|' );   # ok, 'JaffO' =~ m|Jaff|
    ok( 'JaffO', qr/Jaff/ );    # ok, 'JaffO' =~ qr/Jaff/;
    ok( 'JaffO', '/(?i)jaff/ ); # ok, 'JaffO' =~ /jaff/i;

If either (or both!) is a subroutine reference, it is run and used as the value for comparing. For example:

    ok sub {
        open(OUT, ">x.dat") || die $!;
        print OUT "\x{e000}";
        close OUT;
        my $bytecount = -s 'x.dat';
        unlink 'x.dat' or warn "Can't unlink : $!";
        return $bytecount;
      },
      4
    ;

The above test passes two values to ok(arg1, arg2) -- the first a coderef, and the second is the number 4. Before ok compares them, it calls the coderef, and uses its return value as the real value of this parameter. Assuming that $bytecount returns 4, ok ends up testing 4 eq 4. Since that's true, this test passes.

Finally, you can append an optional third argument, in ok(arg1,arg2, note), where note is a string value that will be printed if the test fails. This should be some useful information about the test, pertaining to why it failed, and/or a description of the test. For example:

    ok( grep($_ eq 'something unique', @stuff), 1,
        "Something that should be unique isn't!\n".
        '@stuff = '.join ', ', @stuff
      );

Unfortunately, a note cannot be used with the single argument style of ok(). That is, if you try ok(arg1, note), then Test will interpret this as ok(arg1, arg2), and probably end up testing arg1 eq arg2 -- and that's not what you want!

All of the above special cases can occasionally cause some problems. See BUGS and CAVEATS.

skip(skip_if_true, args...)

This is used for tests that under some conditions can be skipped. It's basically equivalent to:

  if( $skip_if_true ) {
    ok(1);
  } else {
    ok( args... );
  }

...except that the ok(1) emits not just "ok testnum" but actually "ok testnum # skip_if_true_value".

The arguments after the skip_if_true are what is fed to ok(...) if this test isn't skipped.

Example usage:

  my $if_MSWin =
    $^O =~ m/MSWin/ ? 'Skip if under MSWin' : '';

  # A test to be skipped if under MSWin (i.e., run except under MSWin)
  skip($if_MSWin, thing($foo), thing($bar) );

Or, going the other way:

  my $unless_MSWin =
    $^O =~ m/MSWin/ ? '' : 'Skip unless under MSWin';

  # A test to be skipped unless under MSWin (i.e., run only under MSWin)
  skip($unless_MSWin, thing($foo), thing($bar) );

The tricky thing to remember is that the first parameter is true if you want to skip the test, not run it; and it also doubles as a note about why it's being skipped. So in the first codeblock above, read the code as "skip if MSWin -- (otherwise) test whether thing($foo) is thing($bar)" or for the second case, "skip unless MSWin...".

Also, when your skip_if_reason string is true, it really should (for backwards compatibility with older Test.pm versions) start with the string "Skip", as shown in the above examples.

Note that in the above cases, thing($foo) and thing($bar) are evaluated -- but as long as the skip_if_true is true, then we skip(...) just tosses out their value (i.e., not bothering to treat them like values to ok(...). But if you need to not eval the arguments when skipping the test, use this format:

  skip( $unless_MSWin,
    sub {
      # This code returns true if the test passes.
      # (But it doesn't even get called if the test is skipped.)
      thing($foo) eq thing($bar)
    }
  );

or even this, which is basically equivalent:

  skip( $unless_MSWin,
    sub { thing($foo) }, sub { thing($bar) }
  );

That is, both are like this:

  if( $unless_MSWin ) {
    ok(1);  # but it actually appends "# $unless_MSWin"
            #  so that Test::Harness can tell it's a skip
  } else {
    # Not skipping, so actually call and evaluate...
    ok( sub { thing($foo) }, sub { thing($bar) } );
  }

TEST TYPES

  • NORMAL TESTS

    These tests are expected to succeed. Usually, most or all of your tests are in this category. If a normal test doesn't succeed, then that means that something is wrong.

  • SKIPPED TESTS

    The skip(...) function is for tests that might or might not be possible to run, depending on the availability of platform-specific features. The first argument should evaluate to true (think "yes, please skip") if the required feature is not available. After the first argument, skip(...) works exactly the same way as ok(...) does.

  • TODO TESTS

    TODO tests are designed for maintaining an executable TODO list. These tests are expected to fail. If a TODO test does succeed, then the feature in question shouldn't be on the TODO list, now should it?

    Packages should NOT be released with succeeding TODO tests. As soon as a TODO test starts working, it should be promoted to a normal test, and the newly working feature should be documented in the release notes or in the change log.

ONFAIL

  BEGIN { plan test => 4, onfail => sub { warn "CALL 911!" } }

Although test failures should be enough, extra diagnostics can be triggered at the end of a test run. onfail is passed an array ref of hash refs that describe each test failure. Each hash will contain at least the following fields: package, repetition, and result. (You shouldn't rely on any other fields being present.) If the test had an expected value or a diagnostic (or "note") string, these will also be included.

The optional onfail hook might be used simply to print out the version of your package and/or how to report problems. It might also be used to generate extremely sophisticated diagnostics for a particularly bizarre test failure. However it's not a panacea. Core dumps or other unrecoverable errors prevent the onfail hook from running. (It is run inside an END block.) Besides, onfail is probably over-kill in most cases. (Your test code should be simpler than the code it is testing, yes?)

BUGS and CAVEATS

  • ok(...)'s special handing of strings which look like they might be regexes can also cause unexpected behavior. An innocent:

        ok( $fileglob, '/path/to/some/*stuff/' );

    will fail, since Test.pm considers the second argument to be a regex! The best bet is to use the one-argument form:

        ok( $fileglob eq '/path/to/some/*stuff/' );

  • ok(...)'s use of string eq can sometimes cause odd problems when comparing numbers, especially if you're casting a string to a number:

        $foo = "1.0";
    ok( $foo, 1 );      # not ok, "1.0" ne 1

    Your best bet is to use the single argument form:

        ok( $foo == 1 );    # ok "1.0" == 1

  • As you may have inferred from the above documentation and examples, ok's prototype is ($;$$) (and, incidentally, skip's is ($;$$$)). This means, for example, that you can do ok @foo, @bar to compare the size of the two arrays. But don't be fooled into thinking that ok @foo, @bar means a comparison of the contents of two arrays -- you're comparing just the number of elements of each. It's so easy to make that mistake in reading ok @foo, @bar that you might want to be very explicit about it, and instead write ok scalar(@foo), scalar(@bar).

  • This almost definitely doesn't do what you expect:

         ok $thingy->can('some_method');

    Why? Because can returns a coderef to mean "yes it can (and the method is this...)", and then ok sees a coderef and thinks you're passing a function that you want it to call and consider the truth of the result of! I.e., just like:

         ok $thingy->can('some_method')->();

    What you probably want instead is this:

         ok $thingy->can('some_method') && 1;

    If the can returns false, then that is passed to ok. If it returns true, then the larger expression < $thingy-can('some_method') && 1 > >> returns 1, which ok sees as a simple signal of success, as you would expect.

  • The syntax for skip is about the only way it can be, but it's still quite confusing. Just start with the above examples and you'll be okay.

    Moreover, users may expect this:

      skip $unless_mswin, foo($bar), baz($quux);

    to not evaluate foo($bar) and baz($quux) when the test is being skipped. But in reality, they are evaluated, but skip just won't bother comparing them if $unless_mswin is true.

    You could do this:

      skip $unless_mswin, sub{foo($bar)}, sub{baz($quux)};

    But that's not terribly pretty. You may find it simpler or clearer in the long run to just do things like this:

      if( $^O =~ m/MSWin/ ) {
    print "# Yay, we're under $^O\n";
    ok foo($bar), baz($quux);
    ok thing($whatever), baz($stuff);
    ok blorp($quux, $whatever);
    ok foo($barzbarz), thang($quux);
  } else {
    print "# Feh, we're under $^O.  Watch me skip some tests...\n";
    for(1 .. 4) { skip "Skip unless under MSWin" }
  }

    But be quite sure that ok is called exactly as many times in the first block as skip is called in the second block.

ENVIRONMENT

If PERL_TEST_DIFF environment variable is set, it will be used as a command for comparing unexpected multiline results. If you have GNU diff installed, you might want to set PERL_TEST_DIFF to diff -u. If you don't have a suitable program, you might install the Text::Diff module and then set PERL_TEST_DIFF to be perl -MText::Diff -e 'print diff(@ARGV)'. If PERL_TEST_DIFF isn't set but the Algorithm::Diff module is available, then it will be used to show the differences in multiline results.

NOTE

A past developer of this module once said that it was no longer being actively developed. However, rumors of its demise were greatly exaggerated. Feedback and suggestions are quite welcome.

Be aware that the main value of this module is its simplicity. Note that there are already more ambitious modules out there, such as the Test::More manpage and the Test::Unit manpage.

Some earlier versions of this module had docs with some confusing typoes in the description of skip(...).

SEE ALSO

the Test::Harness manpage

the Test::Simple manpage, the Test::More manpage, the Devel::Cover manpage

the Test::Builder manpage for building your own testing library.

the Test::Unit manpage is an interesting XUnit-style testing library.

the Test::Inline manpage and SelfTest let you embed tests in code.

AUTHOR

Copyright (c) 1998-2000 Joshua Nathaniel Pritikin. All rights reserved.

Copyright (c) 2001-2002 Michael G. Schwern.

Copyright (c) 2002-2004 and counting Sean M. Burke.

Current maintainer: Sean M. Burke. <sburke@cpan.org>

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the same terms as Perl itself.


Test::Builder - Backend for building test libraries

    • Construction
    • Setting up tests
    • Running tests
    • Test style
    • Output
    • Test Status and Info
  • EXIT CODES
  • THREADS
  • EXAMPLES
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

Test::Builder - Backend for building test libraries

SYNOPSIS

  package My::Test::Module;
  use Test::Builder;
  require Exporter;
  @ISA = qw(Exporter);
  @EXPORT = qw(ok);

  my $Test = Test::Builder->new;
  $Test->output('my_logfile');

  sub import {
      my($self) = shift;
      my $pack = caller;

      $Test->exported_to($pack);
      $Test->plan(@_);

      $self->export_to_level(1, $self, 'ok');
        }

  sub ok {
      my($test, $name) = @_;

      $Test->ok($test, $name);
        }

DESCRIPTION

Test::Simple and Test::More have proven to be popular testing modules, but they're not always flexible enough. Test::Builder provides the a building block upon which to write your own test libraries which can work together.

Construction

new
  my $Test = Test::Builder->new;

Returns a Test::Builder object representing the current state of the test.

Since you only run one test per program new always returns the same Test::Builder object. No matter how many times you call new(), you're getting the same object. This is called a singleton. This is done so that multiple modules share such global information as the test counter and where test output is going.

If you want a completely new Test::Builder object different from the singleton, use create.

create
  my $Test = Test::Builder->create;

Ok, so there can be more than one Test::Builder object and this is how you get it. You might use this instead of new() if you're testing a Test::Builder based module, but otherwise you probably want new.

NOTE: the implementation is not complete. level, for example, is still shared amongst all Test::Builder objects, even ones created using this method. Also, the method name may change in the future.

reset
  $Test->reset;

Reinitializes the Test::Builder singleton to its original state. Mostly useful for tests run in persistent environments where the same test might be run multiple times in the same process.

Setting up tests

These methods are for setting up tests and declaring how many there are. You usually only want to call one of these methods.

exported_to
  my $pack = $Test->exported_to;
  $Test->exported_to($pack);

Tells Test::Builder what package you exported your functions to. This is important for getting TODO tests right.

plan
  $Test->plan('no_plan');
  $Test->plan( skip_all => $reason );
  $Test->plan( tests => $num_tests );

A convenient way to set up your tests. Call this and Test::Builder will print the appropriate headers and take the appropriate actions.

If you call plan(), don't call any of the other methods below.

expected_tests
    my $max = $Test->expected_tests;
    $Test->expected_tests($max);

Gets/sets the # of tests we expect this test to run and prints out the appropriate headers.

no_plan
  $Test->no_plan;

Declares that this test will run an indeterminate # of tests.

has_plan
  $plan = $Test->has_plan

Find out whether a plan has been defined. $plan is either undef (no plan has been set), no_plan (indeterminate # of tests) or an integer (the number of expected tests).

skip_all
  $Test->skip_all;
  $Test->skip_all($reason);

Skips all the tests, using the given $reason. Exits immediately with 0.

Running tests

These actually run the tests, analogous to the functions in Test::More.

$name is always optional.

ok
  $Test->ok($test, $name);

Your basic test. Pass if $test is true, fail if $test is false. Just like Test::Simple's ok().

is_eq
  $Test->is_eq($got, $expected, $name);

Like Test::More's is(). Checks if $got eq $expected. This is the string version.

is_num
  $Test->is_num($got, $expected, $name);

Like Test::More's is(). Checks if $got == $expected. This is the numeric version.

isnt_eq
  $Test->isnt_eq($got, $dont_expect, $name);

Like Test::More's isnt(). Checks if $got ne $dont_expect. This is the string version.

isnt_num
  $Test->is_num($got, $dont_expect, $name);

Like Test::More's isnt(). Checks if $got ne $dont_expect. This is the numeric version.

like
  $Test->like($this, qr/$regex/, $name);
  $Test->like($this, '/$regex/', $name);

Like Test::More's like(). Checks if $this matches the given $regex.

You'll want to avoid qr// if you want your tests to work before 5.005.

unlike
  $Test->unlike($this, qr/$regex/, $name);
  $Test->unlike($this, '/$regex/', $name);

Like Test::More's unlike(). Checks if $this does not match the given $regex.

maybe_regex
  $Test->maybe_regex(qr/$regex/);
  $Test->maybe_regex('/$regex/');

Convenience method for building testing functions that take regular expressions as arguments, but need to work before perl 5.005.

Takes a quoted regular expression produced by qr//, or a string representing a regular expression.

Returns a Perl value which may be used instead of the corresponding regular expression, or undef if it's argument is not recognised.

For example, a version of like(), sans the useful diagnostic messages, could be written as:

  sub laconic_like {
      my ($self, $this, $regex, $name) = @_;
      my $usable_regex = $self->maybe_regex($regex);
      die "expecting regex, found '$regex'\n"
          unless $usable_regex;
      $self->ok($this =~ m/$usable_regex/, $name);
  }
cmp_ok
  $Test->cmp_ok($this, $type, $that, $name);

Works just like Test::More's cmp_ok().

    $Test->cmp_ok($big_num, '!=', $other_big_num);
BAIL_OUT
    $Test->BAIL_OUT($reason);

Indicates to the Test::Harness that things are going so badly all testing should terminate. This includes running any additional test scripts.

It will exit with 255.

skip
    $Test->skip;
    $Test->skip($why);

Skips the current test, reporting $why.

todo_skip
  $Test->todo_skip;
  $Test->todo_skip($why);

Like skip(), only it will declare the test as failing and TODO. Similar to

    print "not ok $tnum # TODO $why\n";

Test style

level
    $Test->level($how_high);

How far up the call stack should $Test look when reporting where the test failed.

Defaults to 1.

Setting $Test::Builder::Level overrides. This is typically useful localized:

    {
        local $Test::Builder::Level = 2;
        $Test->ok($test);
    }
use_numbers
    $Test->use_numbers($on_or_off);

Whether or not the test should output numbers. That is, this if true:

  ok 1
  ok 2
  ok 3

or this if false

  ok
  ok
  ok

Most useful when you can't depend on the test output order, such as when threads or forking is involved.

Test::Harness will accept either, but avoid mixing the two styles.

Defaults to on.

no_diag
    $Test->no_diag($no_diag);

If set true no diagnostics will be printed. This includes calls to diag().

no_ending
    $Test->no_ending($no_ending);

Normally, Test::Builder does some extra diagnostics when the test ends. It also changes the exit code as described below.

If this is true, none of that will be done.

no_header
    $Test->no_header($no_header);

If set to true, no "1..N" header will be printed.

Output

Controlling where the test output goes.

It's ok for your test to change where STDOUT and STDERR point to, Test::Builder's default output settings will not be affected.

diag
    $Test->diag(@msgs);

Prints out the given @msgs. Like print, arguments are simply appended together.

Normally, it uses the failure_output() handle, but if this is for a TODO test, the todo_output() handle is used.

Output will be indented and marked with a # so as not to interfere with test output. A newline will be put on the end if there isn't one already.

We encourage using this rather than calling print directly.

Returns false. Why? Because diag() is often used in conjunction with a failing test (ok() || diag()) it "passes through" the failure.

    return ok(...) || diag(...);
_print_diag
    $Test->_print_diag(@msg);

Like _print, but prints to the current diagnostic filehandle.

output
    $Test->output($fh);
    $Test->output($file);

Where normal "ok/not ok" test output should go.

Defaults to STDOUT.

failure_output
    $Test->failure_output($fh);
    $Test->failure_output($file);

Where diagnostic output on test failures and diag() should go.

Defaults to STDERR.

todo_output
    $Test->todo_output($fh);
    $Test->todo_output($file);

Where diagnostics about todo test failures and diag() should go.

Defaults to STDOUT.

Test Status and Info

current_test
    my $curr_test = $Test->current_test;
    $Test->current_test($num);

Gets/sets the current test number we're on. You usually shouldn't have to set this.

If set forward, the details of the missing tests are filled in as 'unknown'. if set backward, the details of the intervening tests are deleted. You can erase history if you really want to.

summary
    my @tests = $Test->summary;

A simple summary of the tests so far. True for pass, false for fail. This is a logical pass/fail, so todos are passes.

Of course, test #1 is $tests[0], etc...

details
    my @tests = $Test->details;

Like summary(), but with a lot more detail.

    $tests[$test_num - 1] =
            { 'ok'       => is the test considered a pass?
              actual_ok  => did it literally say 'ok'?
              name       => name of the test (if any)
              type       => type of test (if any, see below).
              reason     => reason for the above (if any)
            };

'ok' is true if Test::Harness will consider the test to be a pass.

'actual_ok' is a reflection of whether or not the test literally printed 'ok' or 'not ok'. This is for examining the result of 'todo' tests.

'name' is the name of the test.

'type' indicates if it was a special test. Normal tests have a type of ''. Type can be one of the following:

    skip        see skip()
    todo        see todo()
    todo_skip   see todo_skip()
    unknown     see below

Sometimes the Test::Builder test counter is incremented without it printing any test output, for example, when current_test() is changed. In these cases, Test::Builder doesn't know the result of the test, so it's type is 'unkown'. These details for these tests are filled in. They are considered ok, but the name and actual_ok is left undef.

For example "not ok 23 - hole count # TODO insufficient donuts" would result in this structure:

    $tests[22] =    # 23 - 1, since arrays start from 0.
      { ok        => 1,   # logically, the test passed since it's todo
        actual_ok => 0,   # in absolute terms, it failed
        name      => 'hole count',
        type      => 'todo',
        reason    => 'insufficient donuts'
      };
todo
    my $todo_reason = $Test->todo;
    my $todo_reason = $Test->todo($pack);

todo() looks for a $TODO variable in your tests. If set, all tests will be considered 'todo' (see Test::More and Test::Harness for details). Returns the reason (ie. the value of $TODO) if running as todo tests, false otherwise.

todo() is about finding the right package to look for $TODO in. It uses the exported_to() package to find it. If that's not set, it's pretty good at guessing the right package to look at based on $Level.

Sometimes there is some confusion about where todo() should be looking for the $TODO variable. If you want to be sure, tell it explicitly what $pack to use.

caller
    my $package = $Test->caller;
    my($pack, $file, $line) = $Test->caller;
    my($pack, $file, $line) = $Test->caller($height);

Like the normal caller(), except it reports according to your level().

EXIT CODES

If all your tests passed, Test::Builder will exit with zero (which is normal). If anything failed it will exit with how many failed. If you run less (or more) tests than you planned, the missing (or extras) will be considered failures. If no tests were ever run Test::Builder will throw a warning and exit with 255. If the test died, even after having successfully completed all its tests, it will still be considered a failure and will exit with 255.

So the exit codes are...

    0                   all tests successful
    255                 test died or all passed but wrong # of tests run
    any other number    how many failed (including missing or extras)

If you fail more than 254 tests, it will be reported as 254.

THREADS

In perl 5.8.0 and later, Test::Builder is thread-safe. The test number is shared amongst all threads. This means if one thread sets the test number using current_test() they will all be effected.

Test::Builder is only thread-aware if threads.pm is loaded before Test::Builder.

EXAMPLES

CPAN can provide the best examples. Test::Simple, Test::More, Test::Exception and Test::Differences all use Test::Builder.

SEE ALSO

Test::Simple, Test::More, Test::Harness

AUTHORS

Original code by chromatic, maintained by Michael G Schwern <schwern@pobox.com>

COPYRIGHT

Copyright 2002, 2004 by chromatic <chromatic@wgz.org> and Michael G Schwern <schwern@pobox.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Test::Builder::Module - Base class for test modules

    • Importing
      • import
      • import_extra
    • Builder
      • builder

NAME

Test::Builder::Module - Base class for test modules

SYNOPSIS

  # Emulates Test::Simple
  package Your::Module;

  my $CLASS = __PACKAGE__;

  use base 'Test::Builder::Module';
  @EXPORT = qw(ok);

  sub ok ($;$) {
      my $tb = $CLASS->builder;
      return $tb->ok(@_);
  }

  1;

DESCRIPTION

This is a superclass for Test::Builder-based modules. It provides a handful of common functionality and a method of getting at the underlying Test::Builder object.

Importing

Test::Builder::Module is a subclass of Exporter which means your module is also a subclass of Exporter. @EXPORT, @EXPORT_OK, etc... all act normally.

A few methods are provided to do the use Your::Module tests = 23> part for you.

import

Test::Builder::Module provides an import() method which acts in the same basic way as Test::More's, setting the plan and controling exporting of functions and variables. This allows your module to set the plan independent of Test::More.

All arguments passed to import() are passed onto Your::Module->builder->plan() with the exception of import =[qw(things to import)]>.

    use Your::Module import => [qw(this that)], tests => 23;

says to import the functions this() and that() as well as set the plan to be 23 tests.

import() also sets the exported_to() attribute of your builder to be the caller of the import() function.

Additional behaviors can be added to your import() method by overriding import_extra().

import_extra

    Your::Module->import_extra(\@import_args);

import_extra() is called by import(). It provides an opportunity for you to add behaviors to your module based on its import list.

Any extra arguments which shouldn't be passed on to plan() should be stripped off by this method.

See Test::More for an example of its use.

NOTE This mechanism is VERY ALPHA AND LIKELY TO CHANGE as it feels like a bit of an ugly hack in its current form.

Builder

Test::Builder::Module provides some methods of getting at the underlying Test::Builder object.

builder

  my $builder = Your::Class->builder;

This method returns the Test::Builder object associated with Your::Class. It is not a constructor so you can call it as often as you like.

This is the preferred way to get the Test::Builder object. You should not get it via Test::Builder->new as was previously recommended.

The object returned by builder() may change at runtime so you should call builder() inside each function rather than store it in a global.

  sub ok {
      my $builder = Your::Class->builder;

      return $builder->ok(@_);
        }


Test::Builder::Tester - test testsuites that have been built with Test::Builder

    • Methods
  • BUGS
  • AUTHOR
  • NOTES
  • SEE ALSO

NAME

Test::Builder::Tester - test testsuites that have been built with Test::Builder

SYNOPSIS

    use Test::Builder::Tester tests => 1;
    use Test::More;

    test_out("not ok 1 - foo");
    test_fail(+1);
    fail("foo");
    test_test("fail works");

DESCRIPTION

A module that helps you test testing modules that are built with Test::Builder.

The testing system is designed to be used by performing a three step process for each test you wish to test. This process starts with using test_out and test_err in advance to declare what the testsuite you are testing will output with Test::Builder to stdout and stderr.

You then can run the test(s) from your test suite that call Test::Builder. At this point the output of Test::Builder is safely captured by Test::Builder::Tester rather than being interpreted as real test output.

The final stage is to call test_test that will simply compare what you predeclared to what Test::Builder actually outputted, and report the results back with a "ok" or "not ok" (with debugging) to the normal output.

Methods

These are the six methods that are exported as default.

test_out
test_err

Procedures for predeclaring the output that your test suite is expected to produce until test_test is called. These procedures automatically assume that each line terminates with "\n". So

   test_out("ok 1","ok 2");

is the same as

   test_out("ok 1\nok 2");

which is even the same as

   test_out("ok 1");
   test_out("ok 2");

Once test_out or test_err (or test_fail or test_diag) have been called once all further output from Test::Builder will be captured by Test::Builder::Tester. This means that your will not be able perform further tests to the normal output in the normal way until you call test_test (well, unless you manually meddle with the output filehandles)

test_fail

Because the standard failure message that Test::Builder produces whenever a test fails will be a common occurrence in your test error output, and because has changed between Test::Builder versions, rather than forcing you to call test_err with the string all the time like so

    test_err("# Failed test ($0 at line ".line_num(+1).")");

test_fail exists as a convenience method that can be called instead. It takes one argument, the offset from the current line that the line that causes the fail is on.

    test_fail(+1);

This means that the example in the synopsis could be rewritten more simply as:

   test_out("not ok 1 - foo");
   test_fail(+1);
   fail("foo");
   test_test("fail works");
test_diag

As most of the remaining expected output to the error stream will be created by Test::Builder's diag function, Test::Builder::Tester provides a convience function test_diag that you can use instead of test_err.

The test_diag function prepends comment hashes and spacing to the start and newlines to the end of the expected output passed to it and adds it to the list of expected error output. So, instead of writing

   test_err("# Couldn't open file");

you can write

   test_diag("Couldn't open file");

Remember that Test::Builder's diag function will not add newlines to the end of output and test_diag will. So to check

   Test::Builder->new->diag("foo\n","bar\n");

You would do

  test_diag("foo","bar")

without the newlines.

test_test

Actually performs the output check testing the tests, comparing the data (with eq) that we have captured from Test::Builder against that that was declared with test_out and test_err.

This takes name/value pairs that effect how the test is run.

title (synonym 'name', 'label')

The name of the test that will be displayed after the ok or not ok.

skip_out

Setting this to a true value will cause the test to ignore if the output sent by the test to the output stream does not match that declared with test_out.

skip_err

Setting this to a true value will cause the test to ignore if the output sent by the test to the error stream does not match that declared with test_err.

As a convience, if only one argument is passed then this argument is assumed to be the name of the test (as in the above examples.)

Once test_test has been run test output will be redirected back to the original filehandles that Test::Builder was connected to (probably STDOUT and STDERR,) meaning any further tests you run will function normally and cause success/errors for Test::Harness.

line_num

A utility function that returns the line number that the function was called on. You can pass it an offset which will be added to the result. This is very useful for working out the correct text of diagnostic methods that contain line numbers.

Essentially this is the same as the __LINE__ macro, but the line_num(+3) idiom is arguably nicer.

In addition to the six exported functions there there exists one function that can only be accessed with a fully qualified function call.

color

When test_test is called and the output that your tests generate does not match that which you declared, test_test will print out debug information showing the two conflicting versions. As this output itself is debug information it can be confusing which part of the output is from test_test and which was the original output from your original tests. Also, it may be hard to spot things like extraneous whitespace at the end of lines that may cause your test to fail even though the output looks similar.

To assist you, if you have the Term::ANSIColor module installed (which you should do by default from perl 5.005 onwards), test_test can colour the background of the debug information to disambiguate the different types of output. The debug output will have it's background coloured green and red. The green part represents the text which is the same between the executed and actual output, the red shows which part differs.

The color function determines if colouring should occur or not. Passing it a true or false value will enable or disable colouring respectively, and the function called with no argument will return the current setting.

To enable colouring from the command line, you can use the Text::Builder::Tester::Color module like so:

   perl -Mlib=Text::Builder::Tester::Color test.t

Or by including the Test::Builder::Tester::Color module directly in the PERL5LIB.

BUGS

Calls Test::Builder's no_ending method turning off the ending tests. This is needed as otherwise it will trip out because we've run more tests than we strictly should have and it'll register any failures we had that we were testing for as real failures.

The color function doesn't work unless Term::ANSIColor is installed and is compatible with your terminal.

Bugs (and requests for new features) can be reported to the author though the CPAN RT system: http://rt.cpan.org/NoAuth/ReportBug.html

AUTHOR

Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.

Some code taken from Test::More and Test::Catch, written by by Michael G Schwern <schwern@pobox.com>. Hence, those parts Copyright Micheal G Schwern 2001. Used and distributed with permission.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

NOTES

This code has been tested explicitly on the following versions of perl: 5.7.3, 5.6.1, 5.6.0, 5.005_03, 5.004_05 and 5.004.

Thanks to Richard Clamp <richardc@unixbeard.net> for letting me use his testing system to try this module out on.

SEE ALSO

the Test::Builder manpage, the Test::Builder::Tester::Color manpage, the Test::More manpage.


Test::Builder::Tester::Color - turn on colour in Test::Builder::Tester

  • AUTHOR
  • BUGS
  • SEE ALSO

NAME

Test::Builder::Tester::Color - turn on colour in Test::Builder::Tester

SYNOPSIS

   When running a test script
     perl -MTest::Builder::Tester::Color test.t

DESCRIPTION

Importing this module causes the subroutine color in Test::Builder::Tester to be called with a true value causing colour highlighting to be turned on in debug output.

The sole purpose of this module is to enable colour highlighting from the command line.

AUTHOR

Copyright Mark Fowler <mark@twoshortplanks.com> 2002.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

This module will have no effect unless Term::ANSIColor is installed.

SEE ALSO

the Test::Builder::Tester manpage, the Term::ANSIColor manpage


Test::Harness - Run Perl standard test scripts with statistics

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • Taint mode
    • Configuration variables.
    • Failure
    • Functions
  • EXPORT
  • DIAGNOSTICS
  • ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS
  • ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS
  • EXAMPLE
  • SEE ALSO
  • TODO
  • BUGS
  • AUTHORS
  • COPYRIGHT

NAME

Test::Harness - Run Perl standard test scripts with statistics

VERSION

Version 2.56

SYNOPSIS

  use Test::Harness;

  runtests(@test_files);

DESCRIPTION

STOP! If all you want to do is write a test script, consider using Test::Simple. Test::Harness is the module that reads the output from Test::Simple, Test::More and other modules based on Test::Builder. You don't need to know about Test::Harness to use those modules.

Test::Harness runs tests and expects output from the test in a certain format. That format is called TAP, the Test Anything Protocol. It is defined in the Test::Harness::TAP manpage.

Test::Harness::runtests(@tests) runs all the testscripts named as arguments and checks standard output for the expected strings in TAP format.

The prove utility is a thin wrapper around Test::Harness.

Taint mode

Test::Harness will honor the -T or -t in the #! line on your test files. So if you begin a test with:

    #!perl -T

the test will be run with taint mode on.

Configuration variables.

These variables can be used to configure the behavior of Test::Harness. They are exported on request.

$Test::Harness::Verbose

The package variable $Test::Harness::Verbose is exportable and can be used to let runtests() display the standard output of the script without altering the behavior otherwise. The prove utility's -v flag will set this.

$Test::Harness::switches

The package variable $Test::Harness::switches is exportable and can be used to set perl command line options used for running the test script(s). The default value is -w. It overrides HARNESS_SWITCHES.

$Test::Harness::Timer

If set to true, and Time::HiRes is available, print elapsed seconds after each test file.

Failure

When tests fail, analyze the summary report:

  t/base..............ok
  t/nonumbers.........ok
  t/ok................ok
  t/test-harness......ok
  t/waterloo..........dubious
          Test returned status 3 (wstat 768, 0x300)
  DIED. FAILED tests 1, 3, 5, 7, 9, 11, 13, 15, 17, 19
          Failed 10/20 tests, 50.00% okay
  Failed Test  Stat Wstat Total Fail  Failed  List of Failed
  -----------------------------------------------------------------------
  t/waterloo.t    3   768    20   10  50.00%  1 3 5 7 9 11 13 15 17 19
  Failed 1/5 test scripts, 80.00% okay. 10/44 subtests failed, 77.27% okay.

Everything passed but t/waterloo.t. It failed 10 of 20 tests and exited with non-zero status indicating something dubious happened.

The columns in the summary report mean:

Failed Test

The test file which failed.

Stat

If the test exited with non-zero, this is its exit status.

Wstat

The wait status of the test.

Total

Total number of tests expected to run.

Fail

Number which failed, either from "not ok" or because they never ran.

Failed

Percentage of the total tests which failed.

List of Failed

A list of the tests which failed. Successive failures may be abbreviated (ie. 15-20 to indicate that tests 15, 16, 17, 18, 19 and 20 failed).

Functions

Test::Harness currently only has one function, here it is.

runtests
  my $allok = runtests(@test_files);

This runs all the given @test_files and divines whether they passed or failed based on their output to STDOUT (details above). It prints out each individual test which failed along with a summary report and a how long it all took.

It returns true if everything was ok. Otherwise it will die() with one of the messages in the DIAGNOSTICS section.

EXPORT

&runtests is exported by Test::Harness by default.

$verbose, $switches and $debug are exported upon request.

DIAGNOSTICS

All tests successful.\nFiles=%d, Tests=%d, %s

If all tests are successful some statistics about the performance are printed.

FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay.

For any single script that has failing subtests statistics like the above are printed.

Test returned status %d (wstat %d)

Scripts that return a non-zero exit status, both $? >> 8 and $? are printed in a message similar to the above.

Failed 1 test, %.2f%% okay. %s
Failed %d/%d tests, %.2f%% okay. %s

If not all tests were successful, the script dies with one of the above messages.

FAILED--Further testing stopped: %s

If a single subtest decides that further testing will not make sense, the script dies with this message.

ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS

Test::Harness sets these before executing the individual tests.

HARNESS_ACTIVE

This is set to a true value. It allows the tests to determine if they are being executed through the harness or by any other means.

HARNESS_VERSION

This is the version of Test::Harness.

ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS

HARNESS_COLUMNS

This value will be used for the width of the terminal. If it is not set then it will default to COLUMNS. If this is not set, it will default to 80. Note that users of Bourne-sh based shells will need to export COLUMNS for this module to use that variable.

HARNESS_COMPILE_TEST

When true it will make harness attempt to compile the test using perlcc before running it.

NOTE This currently only works when sitting in the perl source directory!

HARNESS_DEBUG

If true, Test::Harness will print debugging information about itself as it runs the tests. This is different from HARNESS_VERBOSE, which prints the output from the test being run. Setting $Test::Harness::Debug will override this, or you can use the -d switch in the prove utility.

HARNESS_FILELEAK_IN_DIR

When set to the name of a directory, harness will check after each test whether new files appeared in that directory, and report them as

  LEAKED FILES: scr.tmp 0 my.db

If relative, directory name is with respect to the current directory at the moment runtests() was called. Putting absolute path into HARNESS_FILELEAK_IN_DIR may give more predictable results.

HARNESS_IGNORE_EXITCODE

Makes harness ignore the exit status of child processes when defined.

HARNESS_NOTTY

When set to a true value, forces it to behave as though STDOUT were not a console. You may need to set this if you don't want harness to output more frequent progress messages using carriage returns. Some consoles may not handle carriage returns properly (which results in a somewhat messy output).

HARNESS_PERL

Usually your tests will be run by $^X, the currently-executing Perl. However, you may want to have it run by a different executable, such as a threading perl, or a different version.

If you're using the prove utility, you can use the --perl switch.

HARNESS_PERL_SWITCHES

Its value will be prepended to the switches used to invoke perl on each test. For example, setting HARNESS_PERL_SWITCHES to -W will run all tests with all warnings enabled.

HARNESS_VERBOSE

If true, Test::Harness will output the verbose results of running its tests. Setting $Test::Harness::verbose will override this, or you can use the -v switch in the prove utility.

EXAMPLE

Here's how Test::Harness tests itself

  $ cd ~/src/devel/Test-Harness
  $ perl -Mblib -e 'use Test::Harness qw(&runtests $verbose);
    $verbose=0; runtests @ARGV;' t/*.t
  Using /home/schwern/src/devel/Test-Harness/blib
  t/base..............ok
  t/nonumbers.........ok
  t/ok................ok
  t/test-harness......ok
  All tests successful.
  Files=4, Tests=24, 2 wallclock secs ( 0.61 cusr + 0.41 csys = 1.02 CPU)

SEE ALSO

The included prove utility for running test scripts from the command line, the Test manpage and the Test::Simple manpage for writing test scripts, the Benchmark manpage for the underlying timing routines, and the Devel::Cover manpage for test coverage analysis.

TODO

Provide a way of running tests quietly (ie. no printing) for automated validation of tests. This will probably take the form of a version of runtests() which rather than printing its output returns raw data on the state of the tests. (Partially done in Test::Harness::Straps)

Document the format.

Fix HARNESS_COMPILE_TEST without breaking its core usage.

Figure a way to report test names in the failure summary.

Rework the test summary so long test names are not truncated as badly. (Partially done with new skip test styles)

Add option for coverage analysis.

Trap STDERR.

Implement Straps total_results()

Remember exit code

Completely redo the print summary code.

Implement Straps callbacks. (experimentally implemented)

Straps->analyze_file() not taint clean, don't know if it can be

Fix that damned VMS nit.

HARNESS_TODOFAIL to display TODO failures

Add a test for verbose.

Change internal list of test results to a hash.

Fix stats display when there's an overrun.

Fix so perls with spaces in the filename work.

Keeping whittling away at _run_all_tests()

Clean up how the summary is printed. Get rid of those damned formats.

BUGS

HARNESS_COMPILE_TEST currently assumes it's run from the Perl source directory.

Please use the CPAN bug ticketing system at http://rt.cpan.org/. You can also mail bugs, fixes and enhancements to <bug-test-harness at rt.cpan.org>.

AUTHORS

Either Tim Bunce or Andreas Koenig, we don't know. What we know for sure is, that it was inspired by Larry Wall's TEST script that came with perl distributions for ages. Numerous anonymous contributors exist. Andreas Koenig held the torch for many years, and then Michael G Schwern.

Current maintainer is Andy Lester <andy at petdance.com>.

COPYRIGHT

Copyright 2002-2005 by Michael G Schwern <schwern at pobox.com>, Andy Lester <andy at petdance.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html.


Test::Harness::Assert - simple assert

  • FUNCTIONS
    • assert()
  • AUTHOR
  • SEE ALSO

NAME

Test::Harness::Assert - simple assert

SYNOPSIS

  ### FOR INTERNAL USE ONLY ###

  use Test::Harness::Assert;

  assert( EXPR, $name );

DESCRIPTION

A simple assert routine since we don't have Carp::Assert handy.

For internal use by Test::Harness ONLY!

FUNCTIONS

assert()

  assert( EXPR, $name );

If the expression is false the program aborts.

AUTHOR

Michael G Schwern <schwern@pobox.com>

SEE ALSO

the Carp::Assert manpage


Test::Harness::Iterator - Internal Test::Harness Iterator

    • new()
    • next()

NAME

Test::Harness::Iterator - Internal Test::Harness Iterator

SYNOPSIS

  use Test::Harness::Iterator;
  my $it = Test::Harness::Iterator->new(\*TEST);
  my $it = Test::Harness::Iterator->new(\@array);

  my $line = $it->next;

DESCRIPTION

FOR INTERNAL USE ONLY!

This is a simple iterator wrapper for arrays and filehandles.

new()

Create an iterator.

next()

Iterate through it, of course.


Test::Harness::Point - object for tracking a single test point

  • CONSTRUCTION
    • new()
  • from_test_line( $line )
  • ACCESSORS

NAME

Test::Harness::Point - object for tracking a single test point

SYNOPSIS

One Test::Harness::Point object represents a single test point.

CONSTRUCTION

new()

    my $point = new Test::Harness::Point;

Create a test point object.

from_test_line( $line )

Constructor from a TAP test line, or empty return if the test line is not a test line.

ACCESSORS

Each of the following fields has a getter and setter method.

  • ok
  • number


Test::Harness::Straps - detailed analysis of test results

  • CONSTRUCTION
    • new()
    • $strap->_init
  • ANALYSIS
    • $strap->analyze( $name, \@output_lines )
    • $strap->analyze_fh( $name, $test_filehandle )
    • $strap->analyze_file( $test_file )
    • $strap->_command_line( $file )
    • $strap->_command()
    • $strap->_switches( $file )
    • $strap->_cleaned_switches( @switches_from_user )
    • $strap->_INC2PERL5LIB
    • $strap->_filtered_INC()
    • $strap->_restore_PERL5LIB()
  • Parsing
    • _is_diagnostic
    • _is_header
    • _is_bail_out
    • _reset_file_state
  • Results
  • EXAMPLES
  • AUTHOR
  • SEE ALSO

NAME

Test::Harness::Straps - detailed analysis of test results

SYNOPSIS

  use Test::Harness::Straps;

  my $strap = Test::Harness::Straps->new;

  # Various ways to interpret a test
  my %results = $strap->analyze($name, \@test_output);
  my %results = $strap->analyze_fh($name, $test_filehandle);
  my %results = $strap->analyze_file($test_file);

  # UNIMPLEMENTED
  my %total = $strap->total_results;

  # Altering the behavior of the strap  UNIMPLEMENTED
  my $verbose_output = $strap->dump_verbose();
  $strap->dump_verbose_fh($output_filehandle);

DESCRIPTION

THIS IS ALPHA SOFTWARE in that the interface is subject to change in incompatible ways. It is otherwise stable.

Test::Harness is limited to printing out its results. This makes analysis of the test results difficult for anything but a human. To make it easier for programs to work with test results, we provide Test::Harness::Straps. Instead of printing the results, straps provide them as raw data. You can also configure how the tests are to be run.

The interface is currently incomplete. Please contact the author if you'd like a feature added or something change or just have comments.

CONSTRUCTION

new()

  my $strap = Test::Harness::Straps->new;

Initialize a new strap.

$strap->_init

  $strap->_init;

Initialize the internal state of a strap to make it ready for parsing.

ANALYSIS

$strap->analyze( $name, \@output_lines )

    my %results = $strap->analyze($name, \@test_output);

Analyzes the output of a single test, assigning it the given $name for use in the total report. Returns the %results of the test. See Results.

@test_output should be the raw output from the test, including newlines.

$strap->analyze_fh( $name, $test_filehandle )

    my %results = $strap->analyze_fh($name, $test_filehandle);

Like analyze, but it reads from the given filehandle.

$strap->analyze_file( $test_file )

    my %results = $strap->analyze_file($test_file);

Like analyze, but it runs the given $test_file and parses its results. It will also use that name for the total report.

$strap->_command_line( $file )

Returns the full command line that will be run to test $file.

$strap->_command()

Returns the command that runs the test. Combine this with _switches() to build a command line.

Typically this is $^X, but you can set $ENV{HARNESS_PERL} to use a different Perl than what you're running the harness under. This might be to run a threaded Perl, for example.

You can also overload this method if you've built your own strap subclass, such as a PHP interpreter for a PHP-based strap.

$strap->_switches( $file )

Formats and returns the switches necessary to run the test.

$strap->_cleaned_switches( @switches_from_user )

Returns only defined, non-blank, trimmed switches from the parms passed.

$strap->_INC2PERL5LIB

  local $ENV{PERL5LIB} = $self->_INC2PERL5LIB;

Takes the current value of @INC and turns it into something suitable for putting onto PERL5LIB.

$strap->_filtered_INC()

  my @filtered_inc = $self->_filtered_INC;

Shortens @INC by removing redundant and unnecessary entries. Necessary for OSes with limited command line lengths, like VMS.

$strap->_restore_PERL5LIB()

  $self->_restore_PERL5LIB;

This restores the original value of the PERL5LIB environment variable. Necessary on VMS, otherwise a no-op.

Parsing

Methods for identifying what sort of line you're looking at.

_is_diagnostic

    my $is_diagnostic = $strap->_is_diagnostic($line, \$comment);

Checks if the given line is a comment. If so, it will place it into $comment (sans #).

_is_header

  my $is_header = $strap->_is_header($line);

Checks if the given line is a header (1..M) line. If so, it places how many tests there will be in $strap->{max}, a list of which tests are todo in $strap->{todo} and if the whole test was skipped $strap->{skip_all} contains the reason.

_is_bail_out

  my $is_bail_out = $strap->_is_bail_out($line, \$reason);

Checks if the line is a "Bail out!". Places the reason for bailing (if any) in $reason.

_reset_file_state

  $strap->_reset_file_state;

Resets things like $strap->{max} , $strap->{skip_all}, etc. so it's ready to parse the next file.

Results

The %results returned from analyze() contain the following information:

  passing           true if the whole test is considered a pass
                    (or skipped), false if its a failure
  exit              the exit code of the test run, if from a file
  wait              the wait code of the test run, if from a file
  max               total tests which should have been run
  seen              total tests actually seen
  skip_all          if the whole test was skipped, this will
                      contain the reason.
  ok                number of tests which passed
                      (including todo and skips)
  todo              number of todo tests seen
  bonus             number of todo tests which
                      unexpectedly passed
  skip              number of tests skipped

So a successful test should have max == seen == ok.

There is one final item, the details.

  details           an array ref reporting the result of
                    each test looks like this:
    $results{details}[$test_num - 1] =
            { ok          => is the test considered ok?
              actual_ok   => did it literally say 'ok'?
              name        => name of the test (if any)
              diagnostics => test diagnostics (if any)
              type        => 'skip' or 'todo' (if any)
              reason      => reason for the above (if any)
            };

Element 0 of the details is test #1. I tried it with element 1 being #1 and 0 being empty, this is less awkward.

EXAMPLES

See examples/mini_harness.plx for an example of use.

AUTHOR

Michael G Schwern <schwern@pobox.com>, currently maintained by Andy Lester <andy@petdance.com>.

SEE ALSO

the Test::Harness manpage


Test::Harness::TAP - Documentation for the TAP format

  • TODO
  • THE TAP FORMAT
  • HARNESS BEHAVIOR
  • TESTS LINES AND THE PLAN
    • The plan
    • The test line
  • DIRECTIVES
    • TODO tests
    • Skipping tests
  • OTHER LINES
    • Bail out!
    • Diagnostics
    • Anything else
  • EXAMPLES
    • Common with explanation
    • Unknown amount and failures
    • Giving up
    • Skipping a few
    • Skipping everything
    • Got spare tuits?
    • Creative liberties
  • AUTHORS
  • ACKNOWLEDGEMENTS
  • COPYRIGHT

NAME

Test::Harness::TAP - Documentation for the TAP format

SYNOPSIS

TAP, the Test Anything Protocol, is Perl's simple text-based interface between testing modules such as Test::More and the test harness Test::Harness.

TODO

Exit code of the process.

THE TAP FORMAT

TAP's general format is:

    1..N
    ok 1 Description # Directive
    # Diagnostic
    ....
    ok 47 Description
    ok 48 Description
    more tests....

For example, a test file's output might look like:

    1..4
    ok 1 - Input file opened
    not ok 2 - First line of the input valid
    ok 3 - Read the rest of the file
    not ok 4 - Summarized correctly # TODO Not written yet

HARNESS BEHAVIOR

In this document, the "harness" is any program analyzing TAP output. Typically this will be Perl's prove program, or the underlying Test::Harness::runtests subroutine.

A harness must only read TAP output from standard output and not from standard error. Lines written to standard output matching /^(not )?ok\b/ must be interpreted as test lines. All other lines must not be considered test output.

TESTS LINES AND THE PLAN

The plan

The plan tells how many tests will be run, or how many tests have run. It's a check that the test file hasn't stopped prematurely. It must appear once, whether at the beginning or end of the output.

The plan is usually the first line of TAP output and it specifies how many test points are to follow. For example,

    1..10

means you plan on running 10 tests. This is a safeguard in case your test file dies silently in the middle of its run. The plan is optional but if there is a plan before the test points it must be the first non-diagnostic line output by the test file.

In certain instances a test file may not know how many test points it will ultimately be running. In this case the plan can be the last non-diagnostic line in the output.

The plan cannot appear in the middle of the output, nor can it appear more than once.

The test line

The core of TAP is the test line. A test file prints one test line test point executed. There must be at least one test line in TAP output. Each test line comprises the following elements:

  • ok or not ok

    This tells whether the test point passed or failed. It must be at the beginning of the line. /^not ok/ indicates a failed test point. /^ok/ is a successful test point. This is the only mandatory part of the line.

    Note that unlike the Directives below, ok and not ok are case-sensitive.

  • Test number

    TAP expects the ok or not ok to be followed by a test point number. If there is no number the harness must maintain its own counter until the script supplies test numbers again. So the following test output

        1..6
    not ok
    ok
    not ok
    ok
    ok

    has five tests. The sixth is missing. Test::Harness will generate

        FAILED tests 1, 3, 6
    Failed 3/6 tests, 50.00% okay
  • Description

    Any text after the test number but before a # is the description of the test point.

        ok 42 this is the description of the test

    Descriptions should not begin with a digit so that they are not confused with the test point number.

    The harness may do whatever it wants with the description.

  • Directive

    The test point may include a directive, following a hash on the test line. There are currently two directives allowed: TODO and SKIP. These are discussed below.

To summarize:

  • ok/not ok (required)
  • Test number (recommended)
  • Description (recommended)
  • Directive (only when necessary)

DIRECTIVES

Directives are special notes that follow a # on the test line. Only two are currently defined: TODO and SKIP. Note that these two keywords are not case-sensitive.

TODO tests

If the directive starts with # TODO, the test is counted as a todo test, and the text after TODO is the explanation.

    not ok 13 # TODO bend space and time

Note that if the TODO has an explanation it must be separated from TODO by a space.

These tests represent a feature to be implemented or a bug to be fixed and act as something of an executable "things to do" list. They are not expected to succeed. Should a todo test point begin succeeding, the harness should report it as a bonus. This indicates that whatever you were supposed to do has been done and you should promote this to a normal test point.

Skipping tests

If the directive starts with # SKIP, the test is counted as having been skipped. If the whole test file succeeds, the count of skipped tests is included in the generated output. The harness should report the text after # SKIP\S*\s+ as a reason for skipping.

    ok 23 # skip Insufficient flogiston pressure.

Similarly, one can include an explanation in a plan line, emitted if the test file is skipped completely:

    1..0 # Skipped: WWW::Mechanize not installed

OTHER LINES

Bail out!

As an emergency measure a test script can decide that further tests are useless (e.g. missing dependencies) and testing should stop immediately. In that case the test script prints the magic words

    Bail out!

to standard output. Any message after these words must be displayed by the interpreter as the reason why testing must be stopped, as in

    Bail out! MySQL is not running.

Diagnostics

Additional information may be put into the testing output on separate lines. Diagnostic lines should begin with a #, which the harness must ignore, at least as far as analyzing the test results. The harness is free, however, to display the diagnostics. Typically diagnostics are used to provide information about the environment in which test file is running, or to delineate a group of tests.

    ...
    ok 18 - Closed database connection
    # End of database section.
    # This starts the network part of the test.
    # Daemon started on port 2112
    ok 19 - Opened socket
    ...
    ok 47 - Closed socket
    # End of network tests

Anything else

Any output line that is not a plan, a test line or a diagnostic is incorrect. How a harness handles the incorrect line is undefined. Test::Harness silently ignores incorrect lines, but will become more stringent in the future.

EXAMPLES

All names, places, and events depicted in any example are wholly fictitious and bear no resemblance to, connection with, or relation to any real entity. Any such similarity is purely coincidental, unintentional, and unintended.

Common with explanation

The following TAP listing declares that six tests follow as well as provides handy feedback as to what the test is about to do. All six tests pass.

    1..6
    #
    # Create a new Board and Tile, then place
    # the Tile onto the board.
    #
    ok 1 - The object isa Board
    ok 2 - Board size is zero
    ok 3 - The object isa Tile
    ok 4 - Get possible places to put the Tile
    ok 5 - Placing the tile produces no error
    ok 6 - Board size is 1

Unknown amount and failures

This hypothetical test program ensures that a handful of servers are online and network-accessible. Because it retrieves the hypothetical servers from a database, it doesn't know exactly how many servers it will need to ping. Thus, the test count is declared at the bottom after all the test points have run. Also, two of the tests fail.

    ok 1 - retrieving servers from the database
    # need to ping 6 servers
    ok 2 - pinged diamond
    ok 3 - pinged ruby
    not ok 4 - pinged saphire
    ok 5 - pinged onyx
    not ok 6 - pinged quartz
    ok 7 - pinged gold
    1..7

Giving up

This listing reports that a pile of tests are going to be run. However, the first test fails, reportedly because a connection to the database could not be established. The program decided that continuing was pointless and exited.

    1..573
    not ok 1 - database handle
    Bail out! Couldn't connect to database.

Skipping a few

The following listing plans on running 5 tests. However, our program decided to not run tests 2 thru 5 at all. To properly report this, the tests are marked as being skipped.

    1..5
    ok 1 - approved operating system
    # $^0 is solaris
    ok 2 - # SKIP no /sys directory
    ok 3 - # SKIP no /sys directory
    ok 4 - # SKIP no /sys directory
    ok 5 - # SKIP no /sys directory

Skipping everything

This listing shows that the entire listing is a skip. No tests were run.

    1..0 # skip because English-to-French translator isn't installed

Got spare tuits?

The following example reports that four tests are run and the last two tests failed. However, because the failing tests are marked as things to do later, they are considered successes. Thus, a harness should report this entire listing as a success.

    1..4
    ok 1 - Creating test program
    ok 2 - Test program runs, no error
    not ok 3 - infinite loop # TODO halting problem unsolved
    not ok 4 - infinite loop 2 # TODO halting problem unsolved

Creative liberties

This listing shows an alternate output where the test numbers aren't provided. The test also reports the state of a ficticious board game in diagnostic form. Finally, the test count is reported at the end.

    ok - created Board
    ok
    ok
    ok
    ok
    ok
    ok
    ok
    # +------+------+------+------+
    # |      |16G   |      |05C   |
    # |      |G N C |      |C C G |
    # |      |  G   |      |  C  +|
    # +------+------+------+------+
    # |10C   |01G   |      |03C   |
    # |R N G |G A G |      |C C C |
    # |  R   |  G   |      |  C  +|
    # +------+------+------+------+
    # |      |01G   |17C   |00C   |
    # |      |G A G |G N R |R N R |
    # |      |  G   |  R   |  G   |
    # +------+------+------+------+
    ok - board has 7 tiles + starter tile
    1..9

AUTHORS

Andy Lester, based on the original Test::Harness documentation by Michael Schwern.

ACKNOWLEDGEMENTS

Thanks to Pete Krawczyk, Paul Johnson, Ian Langworth and Nik Clayton for help and contributions on this document.

The basis for the TAP format was created by Larry Wall in the original test script for Perl 1. Tim Bunce and Andreas Koenig developed it further with their modifications to Test::Harness.

COPYRIGHT

Copyright 2003-2005 by Michael G Schwern <schwern@pobox.com>, Andy Lester <andy@petdance.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html.


Test::More - yet another framework for writing test scripts

    • I love it when a plan comes together
    • Test names
    • I'm ok, you're not ok.
    • Module tests
    • Complex data structures
    • Diagnostics
    • Conditional tests
    • Test control
    • Discouraged comparison functions
    • Extending and Embedding Test::More
  • EXIT CODES
  • CAVEATS and NOTES
  • HISTORY
  • SEE ALSO
  • AUTHORS
  • BUGS
  • COPYRIGHT

NAME

Test::More - yet another framework for writing test scripts

SYNOPSIS

  use Test::More tests => $Num_Tests;
  # or
  use Test::More qw(no_plan);
  # or
  use Test::More skip_all => $reason;

  BEGIN { use_ok( 'Some::Module' ); }
  require_ok( 'Some::Module' );

  # Various ways to say "ok"
  ok($this eq $that, $test_name);

  is  ($this, $that,    $test_name);
  isnt($this, $that,    $test_name);

  # Rather than print STDERR "# here's what went wrong\n"
  diag("here's what went wrong");

  like  ($this, qr/that/, $test_name);
  unlike($this, qr/that/, $test_name);

  cmp_ok($this, '==', $that, $test_name);

  is_deeply($complex_structure1, $complex_structure2, $test_name);

  SKIP: {
      skip $why, $how_many unless $have_some_feature;

      ok( foo(),       $test_name );
      is( foo(42), 23, $test_name );
        };

  TODO: {
      local $TODO = $why;

      ok( foo(),       $test_name );
      is( foo(42), 23, $test_name );
        };

  can_ok($module, @methods);
  isa_ok($object, $class);

  pass($test_name);
  fail($test_name);

  BAIL_OUT($why);

  # UNIMPLEMENTED!!!
  my @status = Test::More::status;

DESCRIPTION

STOP! If you're just getting started writing tests, have a look at Test::Simple first. This is a drop in replacement for Test::Simple which you can switch to once you get the hang of basic testing.

The purpose of this module is to provide a wide range of testing utilities. Various ways to say "ok" with better diagnostics, facilities to skip tests, test future features and compare complicated data structures. While you can do almost anything with a simple ok() function, it doesn't provide good diagnostic output.

I love it when a plan comes together

Before anything else, you need a testing plan. This basically declares how many tests your script is going to run to protect against premature failure.

The preferred way to do this is to declare a plan when you use Test::More.

  use Test::More tests => $Num_Tests;

There are rare cases when you will not know beforehand how many tests your script is going to run. In this case, you can declare that you have no plan. (Try to avoid using this as it weakens your test.)

  use Test::More qw(no_plan);

NOTE: using no_plan requires a Test::Harness upgrade else it will think everything has failed. See CAVEATS and NOTES).

In some cases, you'll want to completely skip an entire testing script.

  use Test::More skip_all => $skip_reason;

Your script will declare a skip with the reason why you skipped and exit immediately with a zero (success). See the Test::Harness manpage for details.

If you want to control what functions Test::More will export, you have to use the 'import' option. For example, to import everything but 'fail', you'd do:

  use Test::More tests => 23, import => ['!fail'];

Alternatively, you can use the plan() function. Useful for when you have to calculate the number of tests.

  use Test::More;
  plan tests => keys %Stuff * 3;

or for deciding between running the tests at all:

  use Test::More;
  if( $^O eq 'MacOS' ) {
      plan skip_all => 'Test irrelevant on MacOS';
  }
  else {
      plan tests => 42;
  }

Test names

By convention, each test is assigned a number in order. This is largely done automatically for you. However, it's often very useful to assign a name to each test. Which would you rather see:

  ok 4
  not ok 5
  ok 6

or

  ok 4 - basic multi-variable
  not ok 5 - simple exponential
  ok 6 - force == mass * acceleration

The later gives you some idea of what failed. It also makes it easier to find the test in your script, simply search for "simple exponential".

All test functions take a name argument. It's optional, but highly suggested that you use it.

I'm ok, you're not ok.

The basic purpose of this module is to print out either "ok #" or "not ok #" depending on if a given test succeeded or failed. Everything else is just gravy.

All of the following print "ok" or "not ok" depending on if the test succeeded or failed. They all also return true or false, respectively.

ok
  ok($this eq $that, $test_name);

This simply evaluates any expression ($this eq $that is just a simple example) and uses that to determine if the test succeeded or failed. A true expression passes, a false one fails. Very simple.

For example:

    ok( $exp{9} == 81,                   'simple exponential' );
    ok( Film->can('db_Main'),            'set_db()' );
    ok( $p->tests == 4,                  'saw tests' );
    ok( !grep !defined $_, @items,       'items populated' );

(Mnemonic: "This is ok.")

$test_name is a very short description of the test that will be printed out. It makes it very easy to find a test in your script when it fails and gives others an idea of your intentions. $test_name is optional, but we very strongly encourage its use.

Should an ok() fail, it will produce some diagnostics:

    not ok 18 - sufficient mucus
    #   Failed test 'sufficient mucus'
    #   in foo.t at line 42.

This is actually Test::Simple's ok() routine.

is
isnt
  is  ( $this, $that, $test_name );
  isnt( $this, $that, $test_name );

Similar to ok(), is() and isnt() compare their two arguments with eq and ne respectively and use the result of that to determine if the test succeeded or failed. So these:

    # Is the ultimate answer 42?
    is( ultimate_answer(), 42,          "Meaning of Life" );

    # $foo isn't empty
    isnt( $foo, '',     "Got some foo" );

are similar to these:

    ok( ultimate_answer() eq 42,        "Meaning of Life" );
    ok( $foo ne '',     "Got some foo" );

(Mnemonic: "This is that." "This isn't that.")

So why use these? They produce better diagnostics on failure. ok() cannot know what you are testing for (beyond the name), but is() and isnt() know what the test was and why it failed. For example this test:

    my $foo = 'waffle';  my $bar = 'yarblokos';
    is( $foo, $bar,   'Is foo the same as bar?' );

Will produce something like this:

    not ok 17 - Is foo the same as bar?
    #   Failed test 'Is foo the same as bar?'
    #   in foo.t at line 139.
    #          got: 'waffle'
    #     expected: 'yarblokos'

So you can figure out what went wrong without rerunning the test.

You are encouraged to use is() and isnt() over ok() where possible, however do not be tempted to use them to find out if something is true or false!

  # XXX BAD!
  is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );

This does not check if exists $brooklyn{tree} is true, it checks if it returns 1. Very different. Similar caveats exist for false and 0. In these cases, use ok().

  ok( exists $brooklyn{tree},    'A tree grows in Brooklyn' );

For those grammatical pedants out there, there's an isn't() function which is an alias of isnt().

like
  like( $this, qr/that/, $test_name );

Similar to ok(), like() matches $this against the regex qr/that/.

So this:

    like($this, qr/that/, 'this is like that');

is similar to:

    ok( $this =~ /that/, 'this is like that');

(Mnemonic "This is like that".)

The second argument is a regular expression. It may be given as a regex reference (i.e. qr//) or (for better compatibility with older perls) as a string that looks like a regex (alternative delimiters are currently not supported):

    like( $this, '/that/', 'this is like that' );

Regex options may be placed on the end ('/that/i').

Its advantages over ok() are similar to that of is() and isnt(). Better diagnostics on failure.

unlike
  unlike( $this, qr/that/, $test_name );

Works exactly as like(), only it checks if $this does not match the given pattern.

cmp_ok
  cmp_ok( $this, $op, $that, $test_name );

Halfway between ok() and is() lies cmp_ok(). This allows you to compare two arguments using any binary perl operator.

    # ok( $this eq $that );
    cmp_ok( $this, 'eq', $that, 'this eq that' );

    # ok( $this == $that );
    cmp_ok( $this, '==', $that, 'this == that' );

    # ok( $this && $that );
    cmp_ok( $this, '&&', $that, 'this && that' );
    ...etc...

Its advantage over ok() is when the test fails you'll know what $this and $that were:

    not ok 1
    #   Failed test in foo.t at line 12.
    #     '23'
    #         &&
    #     undef

It's also useful in those cases where you are comparing numbers and is()'s use of eq will interfere:

    cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
can_ok
  can_ok($module, @methods);
  can_ok($object, @methods);

Checks to make sure the $module or $object can do these @methods (works with functions, too).

    can_ok('Foo', qw(this that whatever));

is almost exactly like saying:

    ok( Foo->can('this') &&
        Foo->can('that') &&
        Foo->can('whatever')
      );

only without all the typing and with a better interface. Handy for quickly testing an interface.

No matter how many @methods you check, a single can_ok() call counts as one test. If you desire otherwise, use:

    foreach my $meth (@methods) {
        can_ok('Foo', $meth);
    }
isa_ok
  isa_ok($object, $class, $object_name);
  isa_ok($ref,    $type,  $ref_name);

Checks to see if the given $object->isa($class). Also checks to make sure the object was defined in the first place. Handy for this sort of thing:

    my $obj = Some::Module->new;
    isa_ok( $obj, 'Some::Module' );

where you'd otherwise have to write

    my $obj = Some::Module->new;
    ok( defined $obj && $obj->isa('Some::Module') );

to safeguard against your test script blowing up.

It works on references, too:

    isa_ok( $array_ref, 'ARRAY' );

The diagnostics of this test normally just refer to 'the object'. If you'd like them to be more specific, you can supply an $object_name (for example 'Test customer').

pass
fail
  pass($test_name);
  fail($test_name);

Sometimes you just want to say that the tests have passed. Usually the case is you've got some complicated condition that is difficult to wedge into an ok(). In this case, you can simply use pass() (to declare the test ok) or fail (for not ok). They are synonyms for ok(1) and ok(0).

Use these very, very, very sparingly.

Module tests

You usually want to test if the module you're testing loads ok, rather than just vomiting if its load fails. For such purposes we have use_ok and require_ok.

use_ok
   BEGIN { use_ok($module); }
   BEGIN { use_ok($module, @imports); }

These simply use the given $module and test to make sure the load happened ok. It's recommended that you run use_ok() inside a BEGIN block so its functions are exported at compile-time and prototypes are properly honored.

If @imports are given, they are passed through to the use. So this:

   BEGIN { use_ok('Some::Module', qw(foo bar)) }

is like doing this:

   use Some::Module qw(foo bar);

Version numbers can be checked like so:

   # Just like "use Some::Module 1.02"
   BEGIN { use_ok('Some::Module', 1.02) }

Don't try to do this:

   BEGIN {
       use_ok('Some::Module');

       ...some code that depends on the use...
       ...happening at compile time...
   }

because the notion of "compile-time" is relative. Instead, you want:

  BEGIN { use_ok('Some::Module') }
  BEGIN { ...some code that depends on the use... }
require_ok
   require_ok($module);
   require_ok($file);

Like use_ok(), except it requires the $module or $file.

Complex data structures

Not everything is a simple eq check or regex. There are times you need to see if two data structures are equivalent. For these instances Test::More provides a handful of useful functions.

NOTE I'm not quite sure what will happen with filehandles.

is_deeply
  is_deeply( $this, $that, $test_name );

Similar to is(), except that if $this and $that are references, it does a deep comparison walking each data structure to see if they are equivalent. If the two structures are different, it will display the place where they start differing.

is_deeply() compares the dereferenced values of references, the references themselves (except for their type) are ignored. This means aspects such as blessing and ties are not considered "different".

is_deeply() current has very limited handling of function reference and globs. It merely checks if they have the same referent. This may improve in the future.

Test::Differences and Test::Deep provide more in-depth functionality along these lines.

Diagnostics

If you pick the right test function, you'll usually get a good idea of what went wrong when it failed. But sometimes it doesn't work out that way. So here we have ways for you to write your own diagnostic messages which are safer than just print STDERR.

diag
  diag(@diagnostic_message);

Prints a diagnostic message which is guaranteed not to interfere with test output. Like print @diagnostic_message is simply concatenated together.

Handy for this sort of thing:

    ok( grep(/foo/, @users), "There's a foo user" ) or
        diag("Since there's no foo, check that /etc/bar is set up right");

which would produce:

    not ok 42 - There's a foo user
    #   Failed test 'There's a foo user'
    #   in foo.t at line 52.
    # Since there's no foo, check that /etc/bar is set up right.

You might remember ok() or diag() with the mnemonic open() or die().

NOTE The exact formatting of the diagnostic output is still changing, but it is guaranteed that whatever you throw at it it won't interfere with the test.

Conditional tests

Sometimes running a test under certain conditions will cause the test script to die. A certain function or method isn't implemented (such as fork() on MacOS), some resource isn't available (like a net connection) or a module isn't available. In these cases it's necessary to skip tests, or declare that they are supposed to fail but will work in the future (a todo test).

For more details on the mechanics of skip and todo tests see the Test::Harness manpage.

The way Test::More handles this is with a named block. Basically, a block of tests which can be skipped over or made todo. It's best if I just show you...

SKIP: BLOCK
  SKIP: {
      skip $why, $how_many if $condition;

      ...normal testing code goes here...
  }

This declares a block of tests that might be skipped, $how_many tests there are, $why and under what $condition to skip them. An example is the easiest way to illustrate:

    SKIP: {
        eval { require HTML::Lint };

        skip "HTML::Lint not installed", 2 if $@;

        my $lint = new HTML::Lint;
        isa_ok( $lint, "HTML::Lint" );

        $lint->parse( $html );
        is( $lint->errors, 0, "No errors found in HTML" );
            }

If the user does not have HTML::Lint installed, the whole block of code won't be run at all. Test::More will output special ok's which Test::Harness interprets as skipped, but passing, tests.

It's important that $how_many accurately reflects the number of tests in the SKIP block so the # of tests run will match up with your plan. If your plan is no_plan $how_many is optional and will default to 1.

It's perfectly safe to nest SKIP blocks. Each SKIP block must have the label SKIP, or Test::More can't work its magic.

You don't skip tests which are failing because there's a bug in your program, or for which you don't yet have code written. For that you use TODO. Read on.

TODO: BLOCK
    TODO: {
        local $TODO = $why if $condition;

        ...normal testing code goes here...
    }

Declares a block of tests you expect to fail and $why. Perhaps it's because you haven't fixed a bug or haven't finished a new feature:

    TODO: {
        local $TODO = "URI::Geller not finished";

        my $card = "Eight of clubs";
        is( URI::Geller->your_card, $card, 'Is THIS your card?' );

        my $spoon;
        URI::Geller->bend_spoon;
        is( $spoon, 'bent',    "Spoon bending, that's original" );
            }

With a todo block, the tests inside are expected to fail. Test::More will run the tests normally, but print out special flags indicating they are "todo". Test::Harness will interpret failures as being ok. Should anything succeed, it will report it as an unexpected success. You then know the thing you had todo is done and can remove the TODO flag.

The nice part about todo tests, as opposed to simply commenting out a block of tests, is it's like having a programmatic todo list. You know how much work is left to be done, you're aware of what bugs there are, and you'll know immediately when they're fixed.

Once a todo test starts succeeding, simply move it outside the block. When the block is empty, delete it.

NOTE: TODO tests require a Test::Harness upgrade else it will treat it as a normal failure. See CAVEATS and NOTES).

todo_skip
    TODO: {
        todo_skip $why, $how_many if $condition;

        ...normal testing code...
    }

With todo tests, it's best to have the tests actually run. That way you'll know when they start passing. Sometimes this isn't possible. Often a failing test will cause the whole program to die or hang, even inside an eval BLOCK with and using alarm. In these extreme cases you have no choice but to skip over the broken tests entirely.

The syntax and behavior is similar to a SKIP: BLOCK except the tests will be marked as failing but todo. Test::Harness will interpret them as passing.

When do I use SKIP vs. TODO?

If it's something the user might not be able to do, use SKIP. This includes optional modules that aren't installed, running under an OS that doesn't have some feature (like fork() or symlinks), or maybe you need an Internet connection and one isn't available.

If it's something the programmer hasn't done yet, use TODO. This is for any code you haven't written yet, or bugs you have yet to fix, but want to put tests in your testing script (always a good idea).

Test control

BAIL_OUT
    BAIL_OUT($reason);

Incidates to the harness that things are going so badly all testing should terminate. This includes the running any additional test scripts.

This is typically used when testing cannot continue such as a critical module failing to compile or a necessary external utility not being available such as a database connection failing.

The test will exit with 255.

Discouraged comparison functions

The use of the following functions is discouraged as they are not actually testing functions and produce no diagnostics to help figure out what went wrong. They were written before is_deeply() existed because I couldn't figure out how to display a useful diff of two arbitrary data structures.

These functions are usually used inside an ok().

    ok( eq_array(\@this, \@that) );

is_deeply() can do that better and with diagnostics.

    is_deeply( \@this, \@that );

They may be deprecated in future versions.

eq_array
  my $is_eq = eq_array(\@this, \@that);

Checks if two arrays are equivalent. This is a deep check, so multi-level structures are handled correctly.

eq_hash
  my $is_eq = eq_hash(\%this, \%that);

Determines if the two hashes contain the same keys and values. This is a deep check.

eq_set
  my $is_eq = eq_set(\@this, \@that);

Similar to eq_array(), except the order of the elements is not important. This is a deep check, but the irrelevancy of order only applies to the top level.

    ok( eq_set(\@this, \@that) );

Is better written:

    is_deeply( [sort @this], [sort @that] );

NOTE By historical accident, this is not a true set comparison. While the order of elements does not matter, duplicate elements do.

NOTE eq_set() does not know how to deal with references at the top level. The following is an example of a comparison which might not work:

    eq_set([\1, \2], [\2, \1]);

Test::Deep contains much better set comparison functions.

Extending and Embedding Test::More

Sometimes the Test::More interface isn't quite enough. Fortunately, Test::More is built on top of Test::Builder which provides a single, unified backend for any test library to use. This means two test libraries which both use Test::Builder can be used together in the same program.

If you simply want to do a little tweaking of how the tests behave, you can access the underlying Test::Builder object like so:

builder
    my $test_builder = Test::More->builder;

Returns the Test::Builder object underlying Test::More for you to play with.

EXIT CODES

If all your tests passed, Test::Builder will exit with zero (which is normal). If anything failed it will exit with how many failed. If you run less (or more) tests than you planned, the missing (or extras) will be considered failures. If no tests were ever run Test::Builder will throw a warning and exit with 255. If the test died, even after having successfully completed all its tests, it will still be considered a failure and will exit with 255.

So the exit codes are...

    0                   all tests successful
    255                 test died or all passed but wrong # of tests run
    any other number    how many failed (including missing or extras)

If you fail more than 254 tests, it will be reported as 254.

NOTE This behavior may go away in future versions.

CAVEATS and NOTES

Backwards compatibility

Test::More works with Perls as old as 5.004_05.

Overloaded objects

String overloaded objects are compared as strings (or in cmp_ok()'s case, strings or numbers as appropriate to the comparison op). This prevents Test::More from piercing an object's interface allowing better blackbox testing. So if a function starts returning overloaded objects instead of bare strings your tests won't notice the difference. This is good.

However, it does mean that functions like is_deeply() cannot be used to test the internals of string overloaded objects. In this case I would suggest Test::Deep which contains more flexible testing functions for complex data structures.

Threads

Test::More will only be aware of threads if "use threads" has been done before Test::More is loaded. This is ok:

    use threads;
    use Test::More;

This may cause problems:

    use Test::More
    use threads;
Test::Harness upgrade

no_plan and todo depend on new Test::Harness features and fixes. If you're going to distribute tests that use no_plan or todo your end-users will have to upgrade Test::Harness to the latest one on CPAN. If you avoid no_plan and TODO tests, the stock Test::Harness will work fine.

Installing Test::More should also upgrade Test::Harness.

HISTORY

This is a case of convergent evolution with Joshua Pritikin's Test module. I was largely unaware of its existence when I'd first written my own ok() routines. This module exists because I can't figure out how to easily wedge test names into Test's interface (along with a few other problems).

The goal here is to have a testing utility that's simple to learn, quick to use and difficult to trip yourself up with while still providing more flexibility than the existing Test.pm. As such, the names of the most common routines are kept tiny, special cases and magic side-effects are kept to a minimum. WYSIWYG.

SEE ALSO

the Test::Simple manpage if all this confuses you and you just want to write some tests. You can upgrade to Test::More later (it's forward compatible).

the Test manpage is the old testing module. Its main benefit is that it has been distributed with Perl since 5.004_05.

the Test::Harness manpage for details on how your test results are interpreted by Perl.

the Test::Differences manpage for more ways to test complex data structures. And it plays well with Test::More.

the Test::Class manpage is like XUnit but more perlish.

the Test::Deep manpage gives you more powerful complex data structure testing.

the Test::Unit manpage is XUnit style testing.

the Test::Inline manpage shows the idea of embedded testing.

the Bundle::Test manpage installs a whole bunch of useful test modules.

AUTHORS

Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.

BUGS

See http://rt.cpan.org to report and view bugs.

COPYRIGHT

Copyright 2001, 2002, 2004 by Michael G Schwern <schwern@pobox.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Test::Simple - Basic utilities for writing tests.

  • EXAMPLE
  • CAVEATS
  • NOTES
  • HISTORY
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

Test::Simple - Basic utilities for writing tests.

SYNOPSIS

  use Test::Simple tests => 1;

  ok( $foo eq $bar, 'foo is bar' );

DESCRIPTION

** If you are unfamiliar with testing read Test::Tutorial first! **

This is an extremely simple, extremely basic module for writing tests suitable for CPAN modules and other pursuits. If you wish to do more complicated testing, use the Test::More module (a drop-in replacement for this one).

The basic unit of Perl testing is the ok. For each thing you want to test your program will print out an "ok" or "not ok" to indicate pass or fail. You do this with the ok() function (see below).

The only other constraint is you must pre-declare how many tests you plan to run. This is in case something goes horribly wrong during the test and your test program aborts, or skips a test or whatever. You do this like so:

    use Test::Simple tests => 23;

You must have a plan.

ok
  ok( $foo eq $bar, $name );
  ok( $foo eq $bar );

ok() is given an expression (in this case $foo eq $bar). If it's true, the test passed. If it's false, it didn't. That's about it.

ok() prints out either "ok" or "not ok" along with a test number (it keeps track of that for you).

  # This produces "ok 1 - Hell not yet frozen over" (or not ok)
  ok( get_temperature($hell) > 0, 'Hell not yet frozen over' );

If you provide a $name, that will be printed along with the "ok/not ok" to make it easier to find your test when if fails (just search for the name). It also makes it easier for the next guy to understand what your test is for. It's highly recommended you use test names.

All tests are run in scalar context. So this:

    ok( @stuff, 'I have some stuff' );

will do what you mean (fail if stuff is empty)

Test::Simple will start by printing number of tests run in the form "1..M" (so "1..5" means you're going to run 5 tests). This strange format lets Test::Harness know how many tests you plan on running in case something goes horribly wrong.

If all your tests passed, Test::Simple will exit with zero (which is normal). If anything failed it will exit with how many failed. If you run less (or more) tests than you planned, the missing (or extras) will be considered failures. If no tests were ever run Test::Simple will throw a warning and exit with 255. If the test died, even after having successfully completed all its tests, it will still be considered a failure and will exit with 255.

So the exit codes are...

    0                   all tests successful
    255                 test died or all passed but wrong # of tests run
    any other number    how many failed (including missing or extras)

If you fail more than 254 tests, it will be reported as 254.

This module is by no means trying to be a complete testing system. It's just to get you started. Once you're off the ground its recommended you look at the Test::More manpage.

EXAMPLE

Here's an example of a simple .t file for the fictional Film module.

    use Test::Simple tests => 5;

    use Film;  # What you're testing.

    my $btaste = Film->new({ Title    => 'Bad Taste',
                             Director => 'Peter Jackson',
                             Rating   => 'R',
                             NumExplodingSheep => 1
                           });
    ok( defined($btaste) && ref $btaste eq 'Film,     'new() works' );

    ok( $btaste->Title      eq 'Bad Taste',     'Title() get'    );
    ok( $btaste->Director   eq 'Peter Jackson', 'Director() get' );
    ok( $btaste->Rating     eq 'R',             'Rating() get'   );
    ok( $btaste->NumExplodingSheep == 1,        'NumExplodingSheep() get' );

It will produce output like this:

    1..5
    ok 1 - new() works
    ok 2 - Title() get
    ok 3 - Director() get
    not ok 4 - Rating() get
    #   Failed test 'Rating() get'
    #   in t/film.t at line 14.
    ok 5 - NumExplodingSheep() get
    # Looks like you failed 1 tests of 5

Indicating the Film::Rating() method is broken.

CAVEATS

Test::Simple will only report a maximum of 254 failures in its exit code. If this is a problem, you probably have a huge test script. Split it into multiple files. (Otherwise blame the Unix folks for using an unsigned short integer as the exit status).

Because VMS's exit codes are much, much different than the rest of the universe, and perl does horrible mangling to them that gets in my way, it works like this on VMS.

    0     SS$_NORMAL        all tests successful
    4     SS$_ABORT         something went wrong

Unfortunately, I can't differentiate any further.

NOTES

Test::Simple is explicitly tested all the way back to perl 5.004.

Test::Simple is thread-safe in perl 5.8.0 and up.

HISTORY

This module was conceived while talking with Tony Bowden in his kitchen one night about the problems I was having writing some really complicated feature into the new Testing module. He observed that the main problem is not dealing with these edge cases but that people hate to write tests at all. What was needed was a dead simple module that took all the hard work out of testing and was really, really easy to learn. Paul Johnson simultaneously had this idea (unfortunately, he wasn't in Tony's kitchen). This is it.

SEE ALSO

the Test::More manpage

More testing functions! Once you outgrow Test::Simple, look at Test::More. Test::Simple is 100% forward compatible with Test::More (i.e. you can just use Test::More instead of Test::Simple in your programs and things will still work).

the Test manpage

The original Perl testing module.

the Test::Unit manpage

Elaborate unit testing.

the Test::Inline manpage, SelfTest

Embed tests in your code!

the Test::Harness manpage

Interprets the output of your test program.

AUTHORS

Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern <schwern@pobox.com>, wardrobe by Calvin Klein.

COPYRIGHT

Copyright 2001, 2002, 2004 by Michael G Schwern <schwern@pobox.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


Test::Tutorial - A tutorial about writing really basic tests

    • Nuts and bolts of testing.
    • Where to start?
    • Names
    • Test the manual
    • Sometimes the tests are wrong
    • Testing lots of values
    • Informative names
    • Skipping tests
    • Todo tests
    • Testing with taint mode.
  • FOOTNOTES
  • AUTHORS
  • COPYRIGHT

NAME

Test::Tutorial - A tutorial about writing really basic tests

DESCRIPTION

AHHHHHHH!!!! NOT TESTING! Anything but testing! Beat me, whip me, send me to Detroit, but don't make me write tests!

*sob*

Besides, I don't know how to write the damned things.

Is this you? Is writing tests right up there with writing documentation and having your fingernails pulled out? Did you open up a test and read

    ######## We start with some black magic

and decide that's quite enough for you?

It's ok. That's all gone now. We've done all the black magic for you. And here are the tricks...

Nuts and bolts of testing.

Here's the most basic test program.

    #!/usr/bin/perl -w

    print "1..1\n";

    print 1 + 1 == 2 ? "ok 1\n" : "not ok 1\n";

since 1 + 1 is 2, it prints:

    1..1
    ok 1

What this says is: 1..1 "I'm going to run one test." [1] ok 1 "The first test passed". And that's about all magic there is to testing. Your basic unit of testing is the ok. For each thing you test, an ok is printed. Simple. Test::Harness interprets your test results to determine if you succeeded or failed (more on that later).

Writing all these print statements rapidly gets tedious. Fortunately, there's Test::Simple. It has one function, ok().

    #!/usr/bin/perl -w

    use Test::Simple tests => 1;

    ok( 1 + 1 == 2 );

and that does the same thing as the code above. ok() is the backbone of Perl testing, and we'll be using it instead of roll-your-own from here on. If ok() gets a true value, the test passes. False, it fails.

    #!/usr/bin/perl -w

    use Test::Simple tests => 2;
    ok( 1 + 1 == 2 );
    ok( 2 + 2 == 5 );

from that comes

    1..2
    ok 1
    not ok 2
    #     Failed test (test.pl at line 5)
    # Looks like you failed 1 tests of 2.

1..2 "I'm going to run two tests." This number is used to ensure your test program ran all the way through and didn't die or skip some tests. ok 1 "The first test passed." not ok 2 "The second test failed". Test::Simple helpfully prints out some extra commentary about your tests.

It's not scary. Come, hold my hand. We're going to give an example of testing a module. For our example, we'll be testing a date library, Date::ICal. It's on CPAN, so download a copy and follow along. [2]

Where to start?

This is the hardest part of testing, where do you start? People often get overwhelmed at the apparent enormity of the task of testing a whole module. Best place to start is at the beginning. Date::ICal is an object-oriented module, and that means you start by making an object. So we test new().

    #!/usr/bin/perl -w

    use Test::Simple tests => 2;

    use Date::ICal;

    my $ical = Date::ICal->new;         # create an object
    ok( defined $ical );                # check that we got something
    ok( $ical->isa('Date::ICal') );     # and it's the right class

run that and you should get:

    1..2
    ok 1
    ok 2

congratulations, you've written your first useful test.

Names

That output isn't terribly descriptive, is it? When you have two tests you can figure out which one is #2, but what if you have 102?

Each test can be given a little descriptive name as the second argument to ok().

    use Test::Simple tests => 2;

    ok( defined $ical,              'new() returned something' );
    ok( $ical->isa('Date::ICal'),   "  and it's the right class" );

So now you'd see...

    1..2
    ok 1 - new() returned something
    ok 2 -   and it's the right class

Test the manual

Simplest way to build up a decent testing suite is to just test what the manual says it does. [3] Let's pull something out of the SYNOPSIS in the Date::ICal manpage and test that all its bits work.

    #!/usr/bin/perl -w

    use Test::Simple tests => 8;

    use Date::ICal;

    $ical = Date::ICal->new( year => 1964, month => 10, day => 16,
                             hour => 16, min => 12, sec => 47,
                             tz => '0530' );

    ok( defined $ical,            'new() returned something' );
    ok( $ical->isa('Date::ICal'), "  and it's the right class" );
    ok( $ical->sec   == 47,       '  sec()'   );
    ok( $ical->min   == 12,       '  min()'   );
    ok( $ical->hour  == 16,       '  hour()'  );
    ok( $ical->day   == 17,       '  day()'   );
    ok( $ical->month == 10,       '  month()' );
    ok( $ical->year  == 1964,     '  year()'  );

run that and you get:

    1..8
    ok 1 - new() returned something
    ok 2 -   and it's the right class
    ok 3 -   sec()
    ok 4 -   min()
    ok 5 -   hour()
    not ok 6 -   day()
    #     Failed test (- at line 16)
    ok 7 -   month()
    ok 8 -   year()
    # Looks like you failed 1 tests of 8.

Whoops, a failure! [4] Test::Simple helpfully lets us know on what line the failure occurred, but not much else. We were supposed to get 17, but we didn't. What did we get?? Dunno. We'll have to re-run the test in the debugger or throw in some print statements to find out.

Instead, we'll switch from Test::Simple to Test::More. Test::More does everything Test::Simple does, and more! In fact, Test::More does things exactly the way Test::Simple does. You can literally swap Test::Simple out and put Test::More in its place. That's just what we're going to do.

Test::More does more than Test::Simple. The most important difference at this point is it provides more informative ways to say "ok". Although you can write almost any test with a generic ok(), it can't tell you what went wrong. Instead, we'll use the is() function, which lets us declare that something is supposed to be the same as something else:

    #!/usr/bin/perl -w

    use Test::More tests => 8;

    use Date::ICal;

    $ical = Date::ICal->new( year => 1964, month => 10, day => 16,
                             hour => 16, min => 12, sec => 47,
                             tz => '0530' );

    ok( defined $ical,            'new() returned something' );
    ok( $ical->isa('Date::ICal'), "  and it's the right class" );
    is( $ical->sec,     47,       '  sec()'   );
    is( $ical->min,     12,       '  min()'   );
    is( $ical->hour,    16,       '  hour()'  );
    is( $ical->day,     17,       '  day()'   );
    is( $ical->month,   10,       '  month()' );
    is( $ical->year,    1964,     '  year()'  );

"Is $ical->sec 47?" "Is $ical->min 12?" With is() in place, you get some more information

    1..8
    ok 1 - new() returned something
    ok 2 -   and it's the right class
    ok 3 -   sec()
    ok 4 -   min()
    ok 5 -   hour()
    not ok 6 -   day()
    #     Failed test (- at line 16)
    #          got: '16'
    #     expected: '17'
    ok 7 -   month()
    ok 8 -   year()
    # Looks like you failed 1 tests of 8.

letting us know that $ical->day returned 16, but we expected 17. A quick check shows that the code is working fine, we made a mistake when writing up the tests. Just change it to:

    is( $ical->day,     16,       '  day()'   );

and everything works.

So any time you're doing a "this equals that" sort of test, use is(). It even works on arrays. The test is always in scalar context, so you can test how many elements are in a list this way. [5]

    is( @foo, 5, 'foo has 5 elements' );

Sometimes the tests are wrong

Which brings us to a very important lesson. Code has bugs. Tests are code. Ergo, tests have bugs. A failing test could mean a bug in the code, but don't discount the possibility that the test is wrong.

On the flip side, don't be tempted to prematurely declare a test incorrect just because you're having trouble finding the bug. Invalidating a test isn't something to be taken lightly, and don't use it as a cop out to avoid work.

Testing lots of values

We're going to be wanting to test a lot of dates here, trying to trick the code with lots of different edge cases. Does it work before 1970? After 2038? Before 1904? Do years after 10,000 give it trouble? Does it get leap years right? We could keep repeating the code above, or we could set up a little try/expect loop.

    use Test::More tests => 32;
    use Date::ICal;

    my %ICal_Dates = (
            # An ICal string     And the year, month, date
            #                    hour, minute and second we expect.
            '19971024T120000' =>    # from the docs.
                                [ 1997, 10, 24, 12,  0,  0 ],
            '20390123T232832' =>    # after the Unix epoch
                                [ 2039,  1, 23, 23, 28, 32 ],
            '19671225T000000' =>    # before the Unix epoch
                                [ 1967, 12, 25,  0,  0,  0 ],
            '18990505T232323' =>    # before the MacOS epoch
                                [ 1899,  5,  5, 23, 23, 23 ],
    );

    while( my($ical_str, $expect) = each %ICal_Dates ) {
        my $ical = Date::ICal->new( ical => $ical_str );

        ok( defined $ical,            "new(ical => '$ical_str')" );
        ok( $ical->isa('Date::ICal'), "  and it's the right class" );

        is( $ical->year,    $expect->[0],     '  year()'  );
        is( $ical->month,   $expect->[1],     '  month()' );
        is( $ical->day,     $expect->[2],     '  day()'   );
        is( $ical->hour,    $expect->[3],     '  hour()'  );
        is( $ical->min,     $expect->[4],     '  min()'   );
        is( $ical->sec,     $expect->[5],     '  sec()'   );
            }

So now we can test bunches of dates by just adding them to %ICal_Dates. Now that it's less work to test with more dates, you'll be inclined to just throw more in as you think of them. Only problem is, every time we add to that we have to keep adjusting the use Test::More tests => ## line. That can rapidly get annoying. There's two ways to make this work better.

First, we can calculate the plan dynamically using the plan() function.

    use Test::More;
    use Date::ICal;

    my %ICal_Dates = (
        ...same as before...
    );

    # For each key in the hash we're running 8 tests.
    plan tests => keys %ICal_Dates * 8;

Or to be even more flexible, we use no_plan. This means we're just running some tests, don't know how many. [6]

    use Test::More 'no_plan';   # instead of tests => 32

now we can just add tests and not have to do all sorts of math to figure out how many we're running.

Informative names

Take a look at this line here

    ok( defined $ical,            "new(ical => '$ical_str')" );

we've added more detail about what we're testing and the ICal string itself we're trying out to the name. So you get results like:

    ok 25 - new(ical => '19971024T120000')
    ok 26 -   and it's the right class
    ok 27 -   year()
    ok 28 -   month()
    ok 29 -   day()
    ok 30 -   hour()
    ok 31 -   min()
    ok 32 -   sec()

if something in there fails, you'll know which one it was and that will make tracking down the problem easier. So try to put a bit of debugging information into the test names.

Describe what the tests test, to make debugging a failed test easier for you or for the next person who runs your test.

Skipping tests

Poking around in the existing Date::ICal tests, I found this in t/01sanity.t [7]

    #!/usr/bin/perl -w

    use Test::More tests => 7;
    use Date::ICal;

    # Make sure epoch time is being handled sanely.
    my $t1 = Date::ICal->new( epoch => 0 );
    is( $t1->epoch, 0,          "Epoch time of 0" );

    # XXX This will only work on unix systems.
    is( $t1->ical, '19700101Z', "  epoch to ical" );

    is( $t1->year,  1970,       "  year()"  );
    is( $t1->month, 1,          "  month()" );
    is( $t1->day,   1,          "  day()"   );

    # like the tests above, but starting with ical instead of epoch
    my $t2 = Date::ICal->new( ical => '19700101Z' );
    is( $t2->ical, '19700101Z', "Start of epoch in ICal notation" );

    is( $t2->epoch, 0,          "  and back to ICal" );

The beginning of the epoch is different on most non-Unix operating systems [8]. Even though Perl smooths out the differences for the most part, certain ports do it differently. MacPerl is one off the top of my head. [9] We know this will never work on MacOS. So rather than just putting a comment in the test, we can explicitly say it's never going to work and skip the test.

    use Test::More tests => 7;
    use Date::ICal;

    # Make sure epoch time is being handled sanely.
    my $t1 = Date::ICal->new( epoch => 0 );
    is( $t1->epoch, 0,          "Epoch time of 0" );

    SKIP: {
        skip('epoch to ICal not working on MacOS', 6)
            if $^O eq 'MacOS';

        is( $t1->ical, '19700101Z', "  epoch to ical" );

        is( $t1->year,  1970,       "  year()"  );
        is( $t1->month, 1,          "  month()" );
        is( $t1->day,   1,          "  day()"   );

        # like the tests above, but starting with ical instead of epoch
        my $t2 = Date::ICal->new( ical => '19700101Z' );
        is( $t2->ical, '19700101Z', "Start of epoch in ICal notation" );

        is( $t2->epoch, 0,          "  and back to ICal" );
            }

A little bit of magic happens here. When running on anything but MacOS, all the tests run normally. But when on MacOS, skip() causes the entire contents of the SKIP block to be jumped over. It's never run. Instead, it prints special output that tells Test::Harness that the tests have been skipped.

    1..7
    ok 1 - Epoch time of 0
    ok 2 # skip epoch to ICal not working on MacOS
    ok 3 # skip epoch to ICal not working on MacOS
    ok 4 # skip epoch to ICal not working on MacOS
    ok 5 # skip epoch to ICal not working on MacOS
    ok 6 # skip epoch to ICal not working on MacOS
    ok 7 # skip epoch to ICal not working on MacOS

This means your tests won't fail on MacOS. This means less emails from MacPerl users telling you about failing tests that you know will never work. You've got to be careful with skip tests. These are for tests which don't work and never will. It is not for skipping genuine bugs (we'll get to that in a moment).

The tests are wholly and completely skipped. [10] This will work.

    SKIP: {
        skip("I don't wanna die!");

        die, die, die, die, die;
            }

Todo tests

Thumbing through the Date::ICal man page, I came across this:

   ical
       $ical_string = $ical->ical;

   Retrieves, or sets, the date on the object, using any
   valid ICal date/time string.

"Retrieves or sets". Hmmm, didn't see a test for using ical() to set the date in the Date::ICal test suite. So I'll write one.

    use Test::More tests => 1;
    use Date::ICal;

    my $ical = Date::ICal->new;
    $ical->ical('20201231Z');
    is( $ical->ical, '20201231Z',   'Setting via ical()' );

run that and I get

    1..1
    not ok 1 - Setting via ical()
    #     Failed test (- at line 6)
    #          got: '20010814T233649Z'
    #     expected: '20201231Z'
    # Looks like you failed 1 tests of 1.

Whoops! Looks like it's unimplemented. Let's assume we don't have the time to fix this. [11] Normally, you'd just comment out the test and put a note in a todo list somewhere. Instead, we're going to explicitly state "this test will fail" by wrapping it in a TODO block.

    use Test::More tests => 1;

    TODO: {
        local $TODO = 'ical($ical) not yet implemented';

        my $ical = Date::ICal->new;
        $ical->ical('20201231Z');

        is( $ical->ical, '20201231Z',   'Setting via ical()' );
            }

Now when you run, it's a little different:

    1..1
    not ok 1 - Setting via ical() # TODO ical($ical) not yet implemented
    #          got: '20010822T201551Z'
    #     expected: '20201231Z'

Test::More doesn't say "Looks like you failed 1 tests of 1". That '# TODO' tells Test::Harness "this is supposed to fail" and it treats a failure as a successful test. So you can write tests even before you've fixed the underlying code.

If a TODO test passes, Test::Harness will report it "UNEXPECTEDLY SUCCEEDED". When that happens, you simply remove the TODO block with local $TODO and turn it into a real test.

Testing with taint mode.

Taint mode is a funny thing. It's the globalest of all global features. Once you turn it on, it affects all code in your program and all modules used (and all the modules they use). If a single piece of code isn't taint clean, the whole thing explodes. With that in mind, it's very important to ensure your module works under taint mode.

It's very simple to have your tests run under taint mode. Just throw a -T into the #! line. Test::Harness will read the switches in #! and use them to run your tests.

    #!/usr/bin/perl -Tw

    ...test normally here...

So when you say make test it will be run with taint mode and warnings on.

FOOTNOTES

  1. The first number doesn't really mean anything, but it has to be 1. It's the second number that's important.

  2. For those following along at home, I'm using version 1.31. It has some bugs, which is good -- we'll uncover them with our tests.

  3. You can actually take this one step further and test the manual itself. Have a look at Test::Inline (formerly Pod::Tests).

  4. Yes, there's a mistake in the test suite. What! Me, contrived?

  5. We'll get to testing the contents of lists later.

  6. But what happens if your test program dies halfway through?! Since we didn't say how many tests we're going to run, how can we know it failed? No problem, Test::More employs some magic to catch that death and turn the test into a failure, even if every test passed up to that point.

  7. I cleaned it up a little.

  8. Most Operating Systems record time as the number of seconds since a certain date. This date is the beginning of the epoch. Unix's starts at midnight January 1st, 1970 GMT.

  9. MacOS's epoch is midnight January 1st, 1904. VMS's is midnight, November 17th, 1858, but vmsperl emulates the Unix epoch so it's not a problem.

  10. As long as the code inside the SKIP block at least compiles. Please don't ask how. No, it's not a filter.

  11. Do NOT be tempted to use TODO tests as a way to avoid fixing simple bugs!

AUTHORS

Michael G Schwern <schwern@pobox.com> and the perl-qa dancers!

COPYRIGHT

Copyright 2001 by Michael G Schwern <schwern@pobox.com>.

This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.

Irrespective of its distribution, all code examples in these files are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.


Test::YAML - Testing Module for YAML Implementations

  • AUTHOR
  • COPYRIGHT

NAME

Test::YAML - Testing Module for YAML Implementations

SYNOPSIS

    use Test::YAML tests => 1;

    pass;

DESCRIPTION

Test::YAML is a subclass of Test::Base with YAML specific support.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


abbrev - create an abbreviation table from a list

  • EXAMPLE

NAME

abbrev - create an abbreviation table from a list

SYNOPSIS

    use Text::Abbrev;
    abbrev $hashref, LIST

DESCRIPTION

Stores all unambiguous truncations of each element of LIST as keys in the associative array referenced by $hashref. The values are the original list elements.

EXAMPLE

    $hashref = abbrev qw(list edit send abort gripe);

    %hash = abbrev qw(list edit send abort gripe);

    abbrev $hashref, qw(list edit send abort gripe);

    abbrev(*hash, qw(list edit send abort gripe));


Text::Autoformat - Automatic text wrapping and reformatting

  • VERSION
  • SYNOPSIS
  • BACKGROUND
    • The problem
    • The solution
  • DESCRIPTION
    • Paragraphs
    • Bulleting and (re-)numbering
    • Quoting
    • Widow control
    • Justification
    • Implicit centring
    • Case transformations
    • Selective reformatting
  • SEE ALSO
  • AUTHOR
  • BUGS
  • COPYRIGHT

NAME

Text::Autoformat - Automatic text wrapping and reformatting

VERSION

This document describes version 1.13 of Text::Autoformat, released May 4, 2005.

SYNOPSIS

 # Minimal use: read from STDIN, format to STDOUT...

        use Text::Autoformat;
        autoformat;

 # In-memory formatting...

        $formatted = autoformat $rawtext;

 # Configuration...

        $formatted = autoformat $rawtext, { %options };

 # Margins (1..72 by default)...

        $formatted = autoformat $rawtext, { left=>8, right=>70 };

 # Justification (left by default)...

        $formatted = autoformat $rawtext, { justify => 'left' };
        $formatted = autoformat $rawtext, { justify => 'right' };
        $formatted = autoformat $rawtext, { justify => 'full' };
        $formatted = autoformat $rawtext, { justify => 'centre' };

 # Filling (does so by default)...

        $formatted = autoformat $rawtext, { fill=>0 };

 # Squeezing whitespace (does so by default)...

        $formatted = autoformat $rawtext, { squeeze=>0 };

 # Case conversions...

        $formatted = autoformat $rawtext, { case => 'lower' };
        $formatted = autoformat $rawtext, { case => 'upper' };
        $formatted = autoformat $rawtext, { case => 'sentence' };
        $formatted = autoformat $rawtext, { case => 'title' };
        $formatted = autoformat $rawtext, { case => 'highlight' };

 # Selective reformatting

        $formatted = autoformat $rawtext, { ignore=>qr/^\t/ };

BACKGROUND

The problem

Perl plaintext formatters just aren't smart enough. Given a typical piece of plaintext in need of formatting:

        In comp.lang.perl.misc you wrote:
        : > <CN = Clooless Noobie> writes:
        : > CN> PERL sux because:
        : > CN>    * It doesn't have a switch statement and you have to put $
        : > CN>signs in front of everything
        : > CN>    * There are too many OR operators: having |, || and 'or'
        : > CN>operators is confusing
        : > CN>    * VB rools, yeah!!!!!!!!!
        : > CN> So anyway, how can I stop reloads on a web page?
        : > CN> Email replies only, thanks - I don't read this newsgroup.
        : >
        : > Begone, sirrah! You are a pathetic, Bill-loving, microcephalic
        : > script-infant.
        : Sheesh, what's with this group - ask a question, get toasted! And how
        : *dare* you accuse me of Ianuphilia!

both the venerable Unix fmt tool and Perl's standard Text::Wrap module produce:

        In comp.lang.perl.misc you wrote:  : > <CN = Clooless Noobie>
        writes:  : > CN> PERL sux because:  : > CN>    * It doesn't
        have a switch statement and you have to put $ : > CN>signs in
        front of everything : > CN>    * There are too many OR
        operators: having |, || and 'or' : > CN>operators is confusing
        : > CN>    * VB rools, yeah!!!!!!!!!  : > CN> So anyway, how
        can I stop reloads on a web page?  : > CN> Email replies only,
        thanks - I don't read this newsgroup.  : > : > Begone, sirrah!
        You are a pathetic, Bill-loving, microcephalic : >
        script-infant.  : Sheesh, what's with this group - ask a
        question, get toasted! And how : *dare* you accuse me of
        Ianuphilia!

Other formatting modules -- such as Text::Correct and Text::Format -- provide more control over their output, but produce equally poor results when applied to arbitrary input. They simply don't understand the structural conventions of the text they're reformatting.

The solution

The Text::Autoformat module provides a subroutine named autoformat that wraps text to specified margins. However, autoformat reformats its input by analysing the text's structure, so it wraps the above example like so:

        In comp.lang.perl.misc you wrote:
        : > <CN = Clooless Noobie> writes:
        : > CN> PERL sux because:
        : > CN>    * It doesn't have a switch statement and you
        : > CN>      have to put $ signs in front of everything
        : > CN>    * There are too many OR operators: having |, ||
        : > CN>      and 'or' operators is confusing
        : > CN>    * VB rools, yeah!!!!!!!!! So anyway, how can I
        : > CN>      stop reloads on a web page? Email replies
        : > CN>      only, thanks - I don't read this newsgroup.
        : >
        : > Begone, sirrah! You are a pathetic, Bill-loving,
        : > microcephalic script-infant.
        : Sheesh, what's with this group - ask a question, get toasted!
        : And how *dare* you accuse me of Ianuphilia!

Note that the various quoting conventions have been observed. In fact, their structure has been used to determine where some paragraphs begin. Furthermore autoformat correctly distinguished between the leading '*' bullets of the nested list (which were outdented) and the leading emphatic '*' of "*dare*" (which was inlined).

DESCRIPTION

Paragraphs

The fundamental task of the autoformat subroutine is to identify and rearrange independent paragraphs in a text. Paragraphs typically consist of a series of lines containing at least one non-whitespace character, followed by one or more lines containing only optional whitespace. This is a more liberal definition than many other formatters use: most require an empty line to terminate a paragraph. Paragraphs may also be denoted by bulleting, numbering, or quoting (see the following sections).

Once a paragraph has been isolated, autoformat fills and re-wraps its lines according to the margins that are specified in its argument list. These are placed after the text to be formatted, in a hash reference:

        $tidied = autoformat($messy, {left=>20, right=>60});

By default, autoformat uses a left margin of 1 (first column) and a right margin of 72.

You can also control whether (and how) autoformat breaks words at the end of a line, using the 'break' option:

        # Turn off all hyphenation
        use Text::Autoformat qw(autoformat break_wrap);
        $tidied = autoformat($messy, {break=>break_wrap});

        # Default hyphenation
        use Text::Autoformat qw(autoformat break_at);
        $tidied = autoformat($messy, {break=>break_at('-')});

        # Use TeX::Hyphen module's hyphenation (module must be installed)
        use Text::Autoformat qw(autoformat break_TeX);
        $tidied = autoformat($messy, {break=>break_TeX});

Normally, autoformat only reformats the first paragraph it encounters, and leaves the remainder of the text unaltered. This behaviour is useful because it allows a one-liner invoking the subroutine to be mapped onto a convenient keystroke in a text editor, to provide one-paragraph-at-a-time reformatting:

        % cat .exrc
        map f !Gperl -MText::Autoformat -e'autoformat'

(Note that to facilitate such one-liners, if autoformat is called in a void context without any text data, it takes its text from STDIN and writes its result to STDOUT).

To enable autoformat to rearrange the entire input text at once, the all argument is used:

        $tidied_all = autoformat($messy, {left=>20, right=>60, all=>1});

autoformat can also be directed to selectively reformat paragraphs, using the ignore argument:

        $tidied_some = autoformat($messy, {ignore=>qr/^[ \t]/});

The value for ignore may be a qr'd regex, a subroutine reference, or the special string 'indented'.

If a regex is specified, any paragraph whose original text matches that regex will not be reformatted (i.e. it will be printed verbatim).

If a subroutine is specified, that subroutine will be called once for each paragraph (with $_ set to the paragraph's text). The subroutine is expected to return a true or false value. If it returns true, the paragraph will not be reformatted.

If the value of the ignore option is the string 'indented', autoformat will ignore any paragraph in which every line begins with a whitespace.

One other special case of ignorance is ignoring mail headers and signature. This option is specified using the mail argument:

        $tidied_mesg = autoformat($messy_mesg, {mail=>1});

Note that the mail option automatically implies all.

Bulleting and (re-)numbering

Often plaintext will include lists that are either:

        * bulleted,
        * simply numbered (i.e. 1., 2., 3., etc.), or
        * hierarchically numbered (1, 1.1, 1.2, 1.3, 2, 2.1. and so forth).

In such lists, each bulleted item is implicitly a separate paragraph, and is formatted individually, with the appropriate indentation:

        * bulleted,
        * simply numbered (i.e. 1., 2., 3.,
          etc.), or
        * hierarchically numbered (1, 1.1,
          1.2, 1.3, 2, 2.1. and so forth).

More importantly, if the points are numbered, the numbering is checked and reordered. For example, a list whose points have been rearranged:

        2. Analyze problem
        3. Design algorithm
        1. Code solution
        5. Test
        4. Ship

would be renumbered automatically by autoformat:

        1. Analyze problem
        2. Design algorithm
        3. Code solution
        4. Ship
        5. Test

The same reordering would be performed if the "numbering" was by letters (a. b. c. etc.) or Roman numerals (i. ii. iii.) or by some combination of these (1a. 1b. 2a. 2b. etc.) Handling disordered lists of letters and Roman numerals presents an interesting challenge. A list such as:

        C. Put cat in box.
        D. Close lid.
        E. Activate Geiger counter.

should be reordered as A. B. C., whereas:

        C. Put cat in box.
        D. Close lid.
        XLI. Activate Geiger counter.

should be reordered I. II. III.

The autoformat subroutine solves this problem by always interpreting alphabetic bullets as being letters, unless the full list consists only of valid Roman numerals, at least one of which is two or more characters long.

If automatic renumbering isn't wanted, just specify the 'renumber' option with a false value.

Note that numbers above 1000 at the start of a line are no longer considered to be paragraph numbering. Numbered paragraphs running that high are exceptionally rare, and much rarer than paragraphs that look like this:

        Although it has long been popular (especially in the year
        2001) to point out that we now live in the Future, many
        of the promised miracles of Future Life have failed to
        eventuate. This is a new phenomenon (it didn't happen in
        1001) because the idea that the future might be different
        is a new phenomenon.

which the former numbering rules caused to be formatted like this:

        Although it has long been popular (especially in the year
        2001) to point out that we now live in the Future, many of the
              promised miracles of Future Life have failed to eventuate.
              This is a new phenomenon (it didn't happen in
        2002) because the idea that the future might be different is a
              new phenomenon.

but which are now formatted:

        Although it has long been popular (especially in the year 2001)
        to point out that we now live in the Future, many of the
        promised miracles of Future Life have failed to eventuate. This
        is a new phenomenon (it didn't happen in 1001) because the idea
        that the future might be different is a new phenomenon.

If you want numbers less than 1000 (or other characters strings currently treated as bullets) to be ignored in this way, you can turn of list formatting entirely by setting the 'lists' option to a false value.

Quoting

Another case in which contiguous lines may be interpreted as belonging to different paragraphs, is where they are quoted with distinct quoters. For example:

        : > CN> So anyway, how can I stop reloads on a web page? Email
        : > CN> replies only, thanks - I don't read this newsgroup.
        : > Begone, sirrah! You are a pathetic, Bill-loving,
        : > microcephalic script-infant.
        : Sheesh, what's with this group - ask a question, get toasted!
        : And how *dare* you accuse me of Ianuphilia!

autoformat recognizes the various quoting conventions used in this example and treats it as three paragraphs to be independently reformatted.

Block quotations present a different challenge. A typical formatter would render the following quotation:

        "We are all of us in the gutter, but some of us are looking at
         the stars"
                                -- Oscar Wilde

like so:

        "We are all of us in the gutter, but some of us are looking at
        the stars" -- Oscar Wilde

autoformat recognizes the quotation structure by matching the following regular expression against the text component of each paragraph:

        / \A(\s*) # leading whitespace for quotation (["']|``) # opening
        quotemark (.*) # quotation (''|\2) # closing quotemark \s*?\n #
        trailing whitespace after quotation (\1[ ]+) # leading
        whitespace for attribution
                                #   (must be indented more than
                                #   quotation)
          (--|-) # attribution introducer ([^\n]*?\n) # first
          attribution line ((\5[^\n]*?$)*) # other attribution lines
                                #   (indented no less than first line)
          \s*\Z # optional whitespace to end of paragraph /xsm

When reformatted (see below), the indentation and the attribution structure will be preserved:

        "We are all of us in the gutter, but some of us are looking at
         the stars"
                                -- Oscar Wilde

Widow control

Note that in the last example, autoformat broke the line at column 68, four characters earlier than it should have. It did so because, if the full margin width had been used, the formatting would have left the last two words by themselves on an oddly short last line:

        "We are all of us in the gutter, but some of us are looking at
        the stars"

This phenomenon is known as "widowing" and is heavily frowned upon in typesetting circles. It looks ugly in plaintext too, so autoformat avoids it by stealing extra words from earlier lines in a paragraph, so as to leave enough for a reasonable last line. The heuristic used is that final lines must be at least 10 characters long (though this number may be adjusted by passing a widow => minlength argument to autoformat).

If the last line is too short, the paragraph's right margin is reduced by one column, and the paragraph is reformatted. This process iterates until either the last line exceeds nine characters or the margins have been narrowed by 10% of their original separation. In the latter case, the reformatter gives up and uses its original formatting.

Justification

The autoformat subroutine also takes a named argument: {justify =E<gt> I<type>}, which specifies how each paragraph is to be justified. The options are: 'left' (the default), 'right', 'centre' (or 'center'), and 'full'. These act on the complete paragraph text (but not on any quoters before that text). For example, with 'right' justification:

         R3>     Now is the Winter of our discontent made
         R4> glorious Summer by this son of York. And all
         R5> the clouds that lour'd upon our house In the
         R6>              deep bosom of the ocean buried.

Full justification is interesting in a fixed-width medium like plaintext because it usually results in uneven spacing between words. Typically, formatters provide this by distributing the extra spaces into the first available gaps of each line:

         R7> Now is the Winter of our discontent made
         R8> glorious Summer by this son of York. And all
         R9> the clouds that lour'd upon our house In
        R10> the deep bosom of the ocean buried.

This produces a rather jarring visual effect, so autoformat reverses the strategy and inserts extra spaces at the end of lines:

        R11> Now is the Winter of our discontent made
        R12> glorious Summer by this son of York. And all
        R13> the clouds that lour'd upon our house In
        R14> the deep bosom of the ocean buried.

Most readers find this less disconcerting.

Implicit centring

Even if explicit centring is not specified, autoformat will attempt to automatically detect centred paragraphs and preserve their justification. It does this by examining each line of the paragraph and asking: "if this line were part of a centred paragraph, where would the centre line have been?"

The answer can be determined by adding the length of leading whitespace before the first word, plus half the length of the full set of words on the line. That is, for a single line:

        $line =~ /^(\s*)(.*?)(\s*)$/ $centre =
        length($1)+0.5*length($2);

By making the same estimate for every line, and then comparing the estimates, it is possible to deduce whether all the lines are centred with respect to the same axis of symmetry (with an allowance of ±1 to cater for the inevitable rounding when the centre positions of even-length rows were originally computed). If a common axis of symmetry is detected, autoformat assumes that the lines are supposed to be centred, and switches to centre-justification mode for that paragraph.

Note that this behaviour can to switched off entirely by setting the "autocentre" argument false.

Case transformations

The autoformat subroutine can also optionally perform case conversions on the text it processes. The {case => type} argument allows the user to specify five different conversions:

'upper'

This mode unconditionally converts every letter in the reformatted text to upper-case;

'lower'

This mode unconditionally converts every letter in the reformatted text to lower-case;

'sentence'

This mode attempts to generate correctly-cased sentences from the input text. That is, the first letter after a sentence-terminating punctuator is converted to upper-case. Then, each subsequent word in the sentence is converted to lower-case, unless that word is originally mixed-case or contains punctuation. For example, under {case => 'sentence'}:

        'POVERTY, MISERY, ETC. are the lot of the PhD candidate. alas!'

becomes:

        'Poverty, misery, etc. are the lot of the PhD candidate. Alas!'

Note that autoformat is clever enough to recognize that the period after abbreviations such as etc. is not a sentence terminator.

If the argument is specified as 'sentence ' (with one or more trailing whitespace characters) those characters are used to replace the single space that appears at the end of the sentence. For example, autoformat($text, {case=>'sentence '}) would produce:

        'Poverty, misery, etc. are the lot of the PhD candidate. Alas!'
'title'

This mode behaves like 'sentence' except that the first letter of every word is capitalized:

        'What I Did On My Summer Vacation In Monterey'
'highlight'

This mode behaves like 'title' except that trivial words are not capitalized:

        'What I Did on my Summer Vacation in Monterey'

Selective reformatting

You can select which paragraphs autoformat actually reformats (or, rather, those it doesn't reformat) using the "ignore" flag.

For example:

        # Reformat all paras except those containing "verbatim"...
        print autoformat { all => 1, ignore => qr/verbatim/i }, $text;

        # Reformat all paras except those less that 3 lines long...
        print autoformat { all => 1, ignore => sub { tr/\n/\n/ < 3
        } }, $text;

        # Reformat all paras except those that are indented...
        print autoformat { all => 1, ignore => qr/^\s/m }, $text;

        # Reformat all paras except those that are indented (easier)...
        print autoformat { all => 1, ignore => 'indented' }, $text;

SEE ALSO

The Text::Reform module

AUTHOR

Damian Conway (damian@conway.org)

BUGS

There are undoubtedly serious bugs lurking somewhere in code this funky :-) Bug reports and other feedback are most welcome.

COPYRIGHT

Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)


Text::Balanced - Extract delimited text sequences from strings.

    • General behaviour in list contexts
    • General behaviour in scalar and void contexts
    • A note about prefixes
    • extract_delimited
    • extract_bracketed
    • extract_variable
    • extract_tagged
    • gen_extract_tagged
    • extract_quotelike
    • extract_quotelike and "here documents"
    • extract_codeblock
    • extract_multiple
    • gen_delimited_pat
  • DIAGNOSTICS
  • AUTHOR
  • BUGS AND IRRITATIONS
  • COPYRIGHT

NAME

Text::Balanced - Extract delimited text sequences from strings.

SYNOPSIS

 use Text::Balanced qw (
                        extract_delimited
                        extract_bracketed
                        extract_quotelike
                        extract_codeblock
                        extract_variable
                        extract_tagged
                        extract_multiple
                        gen_delimited_pat
                        gen_extract_tagged
                                               );

 # Extract the initial substring of $text that is delimited by
 # two (unescaped) instances of the first character in $delim.

        ($extracted, $remainder) = extract_delimited($text,$delim);

 # Extract the initial substring of $text that is bracketed
 # with a delimiter(s) specified by $delim (where the string
 # in $delim contains one or more of '(){}[]<>').

        ($extracted, $remainder) = extract_bracketed($text,$delim);

 # Extract the initial substring of $text that is bounded by
 # an XML tag.

        ($extracted, $remainder) = extract_tagged($text);

 # Extract the initial substring of $text that is bounded by
 # a C<BEGIN>...C<END> pair. Don't allow nested C<BEGIN> tags

        ($extracted, $remainder) =
                extract_tagged($text,"BEGIN","END",undef,{bad=>["BEGIN"]});

 # Extract the initial substring of $text that represents a
 # Perl "quote or quote-like operation"

        ($extracted, $remainder) = extract_quotelike($text);

 # Extract the initial substring of $text that represents a block
 # of Perl code, bracketed by any of character(s) specified by $delim
 # (where the string $delim contains one or more of '(){}[]<>').

        ($extracted, $remainder) = extract_codeblock($text,$delim);

 # Extract the initial substrings of $text that would be extracted by
 # one or more sequential applications of the specified functions
 # or regular expressions

        @extracted = extract_multiple($text,
                                      [ \&extract_bracketed,
                                        \&extract_quotelike,
                                        \&some_other_extractor_sub,
                                        qr/[xyz]*/,
                                        'literal',
                                      ]);

# Create a string representing an optimized pattern (a la Friedl) # that matches a substring delimited by any of the specified characters # (in this case: any type of quote or a slash)

        $patstring = gen_delimited_pat(q{'"`/});

# Generate a reference to an anonymous sub that is just like extract_tagged # but pre-compiled and optimized for a specific pair of tags, and consequently # much faster (i.e. 3 times faster). It uses qr// for better performance on # repeated calls, so it only works under Perl 5.005 or later.

        $extract_head = gen_extract_tagged('<HEAD>','</HEAD>');

        ($extracted, $remainder) = $extract_head->($text);

DESCRIPTION

The various extract_... subroutines may be used to extract a delimited substring, possibly after skipping a specified prefix string. By default, that prefix is optional whitespace (/\s*/), but you can change it to whatever you wish (see below).

The substring to be extracted must appear at the current pos location of the string's variable (or at index zero, if no pos position is defined). In other words, the extract_... subroutines don't extract the first occurance of a substring anywhere in a string (like an unanchored regex would). Rather, they extract an occurance of the substring appearing immediately at the current matching position in the string (like a \G-anchored regex would).

General behaviour in list contexts

In a list context, all the subroutines return a list, the first three elements of which are always:

[0]

The extracted string, including the specified delimiters. If the extraction fails an empty string is returned.

[1]

The remainder of the input string (i.e. the characters after the extracted string). On failure, the entire string is returned.

[2]

The skipped prefix (i.e. the characters before the extracted string). On failure, the empty string is returned.

Note that in a list context, the contents of the original input text (the first argument) are not modified in any way.

However, if the input text was passed in a variable, that variable's pos value is updated to point at the first character after the extracted text. That means that in a list context the various subroutines can be used much like regular expressions. For example:

        while ( $next = (extract_quotelike($text))[0] )
        {
                # process next quote-like (in $next)
        }

General behaviour in scalar and void contexts

In a scalar context, the extracted string is returned, having first been removed from the input text. Thus, the following code also processes each quote-like operation, but actually removes them from $text:

        while ( $next = extract_quotelike($text) )
        {
                # process next quote-like (in $next)
        }

Note that if the input text is a read-only string (i.e. a literal), no attempt is made to remove the extracted text.

In a void context the behaviour of the extraction subroutines is exactly the same as in a scalar context, except (of course) that the extracted substring is not returned.

A note about prefixes

Prefix patterns are matched without any trailing modifiers (/gimsox etc.) This can bite you if you're expecting a prefix specification like '.*?(?=<H1>)' to skip everything up to the first <H1> tag. Such a prefix pattern will only succeed if the <H1> tag is on the current line, since . normally doesn't match newlines.

To overcome this limitation, you need to turn on /s matching within the prefix pattern, using the (?s) directive: '(?s).*?(?=<H1>)'

extract_delimited

The extract_delimited function formalizes the common idiom of extracting a single-character-delimited substring from the start of a string. For example, to extract a single-quote delimited string, the following code is typically used:

        ($remainder = $text) =~ s/\A('(\\.|[^'])*')//s;
        $extracted = $1;

but with extract_delimited it can be simplified to:

        ($extracted,$remainder) = extract_delimited($text, "'");

extract_delimited takes up to four scalars (the input text, the delimiters, a prefix pattern to be skipped, and any escape characters) and extracts the initial substring of the text that is appropriately delimited. If the delimiter string has multiple characters, the first one encountered in the text is taken to delimit the substring. The third argument specifies a prefix pattern that is to be skipped (but must be present!) before the substring is extracted. The final argument specifies the escape character to be used for each delimiter.

All arguments are optional. If the escape characters are not specified, every delimiter is escaped with a backslash (\). If the prefix is not specified, the pattern '\s*' - optional whitespace - is used. If the delimiter set is also not specified, the set /["'`]/ is used. If the text to be processed is not specified either, $_ is used.

In list context, extract_delimited returns a array of three elements, the extracted substring (including the surrounding delimiters), the remainder of the text, and the skipped prefix (if any). If a suitable delimited substring is not found, the first element of the array is the empty string, the second is the complete original text, and the prefix returned in the third element is an empty string.

In a scalar context, just the extracted substring is returned. In a void context, the extracted substring (and any prefix) are simply removed from the beginning of the first argument.

Examples:

        # Remove a single-quoted substring from the very beginning of $text:

                $substring = extract_delimited($text, "'", '');

        # Remove a single-quoted Pascalish substring (i.e. one in which
        # doubling the quote character escapes it) from the very
        # beginning of $text:

                $substring = extract_delimited($text, "'", '', "'");

        # Extract a single- or double- quoted substring from the
        # beginning of $text, optionally after some whitespace
        # (note the list context to protect $text from modification):

                ($substring) = extract_delimited $text, q{"'};

        # Delete the substring delimited by the first '/' in $text:

                $text = join '', (extract_delimited($text,'/','[^/]*')[2,1];

Note that this last example is not the same as deleting the first quote-like pattern. For instance, if $text contained the string:

        "if ('./cmd' =~ m/$UNIXCMD/s) { $cmd = $1; }"

        then after the deletion it would contain:

        "if ('.$UNIXCMD/s) { $cmd = $1; }"

not:

        "if ('./cmd' =~ ms) { $cmd = $1; }"

See extract_quotelike for a (partial) solution to this problem.

extract_bracketed

Like "extract_delimited", the extract_bracketed function takes up to three optional scalar arguments: a string to extract from, a delimiter specifier, and a prefix pattern. As before, a missing prefix defaults to optional whitespace and a missing text defaults to $_. However, a missing delimiter specifier defaults to '{}()[]<>' (see below).

extract_bracketed extracts a balanced-bracket-delimited substring (using any one (or more) of the user-specified delimiter brackets: '(..)', '{..}', '[..]', or '<..>'). Optionally it will also respect quoted unbalanced brackets (see below).

A "delimiter bracket" is a bracket in list of delimiters passed as extract_bracketed's second argument. Delimiter brackets are specified by giving either the left or right (or both!) versions of the required bracket(s). Note that the order in which two or more delimiter brackets are specified is not significant.

A "balanced-bracket-delimited substring" is a substring bounded by matched brackets, such that any other (left or right) delimiter bracket within the substring is also matched by an opposite (right or left) delimiter bracket at the same level of nesting. Any type of bracket not in the delimiter list is treated as an ordinary character.

In other words, each type of bracket specified as a delimiter must be balanced and correctly nested within the substring, and any other kind of ("non-delimiter") bracket in the substring is ignored.

For example, given the string:

        $text = "{ an '[irregularly :-(] {} parenthesized >:-)' string }";

then a call to extract_bracketed in a list context:

        @result = extract_bracketed( $text, '{}' );

would return:

        ( "{ an '[irregularly :-(] {} parenthesized >:-)' string }" , "" , "" )

since both sets of '{..}' brackets are properly nested and evenly balanced. (In a scalar context just the first element of the array would be returned. In a void context, $text would be replaced by an empty string.)

Likewise the call in:

        @result = extract_bracketed( $text, '{[' );

would return the same result, since all sets of both types of specified delimiter brackets are correctly nested and balanced.

However, the call in:

        @result = extract_bracketed( $text, '{([<' );

would fail, returning:

        ( undef , "{ an '[irregularly :-(] {} parenthesized >:-)' string }"  );

because the embedded pairs of '(..)'s and '[..]'s are "cross-nested" and the embedded '>' is unbalanced. (In a scalar context, this call would return an empty string. In a void context, $text would be unchanged.)

Note that the embedded single-quotes in the string don't help in this case, since they have not been specified as acceptable delimiters and are therefore treated as non-delimiter characters (and ignored).

However, if a particular species of quote character is included in the delimiter specification, then that type of quote will be correctly handled. for example, if $text is:

        $text = '<A HREF=">>>>">link</A>';

then

        @result = extract_bracketed( $text, '<">' );

returns:

        ( '<A HREF=">>>>">', 'link</A>', "" )

as expected. Without the specification of " as an embedded quoter:

        @result = extract_bracketed( $text, '<>' );

the result would be:

        ( '<A HREF=">', '>>>">link</A>', "" )

In addition to the quote delimiters ', ", and `, full Perl quote-like quoting (i.e. q{string}, qq{string}, etc) can be specified by including the letter 'q' as a delimiter. Hence:

        @result = extract_bracketed( $text, '<q>' );

would correctly match something like this:

        $text = '<leftop: conj /and/ conj>';

See also: "extract_quotelike" and "extract_codeblock".

extract_variable

extract_variable extracts any valid Perl variable or variable-involved expression, including scalars, arrays, hashes, array accesses, hash look-ups, method calls through objects, subroutine calles through subroutine references, etc.

The subroutine takes up to two optional arguments:

  1. A string to be processed ($_ if the string is omitted or undef)

  2. A string specifying a pattern to be matched as a prefix (which is to be skipped). If omitted, optional whitespace is skipped.

On success in a list context, an array of 3 elements is returned. The elements are:

[0]

the extracted variable, or variablish expression

[1]

the remainder of the input text,

[2]

the prefix substring (if any),

On failure, all of these values (except the remaining text) are undef.

In a scalar context, extract_variable returns just the complete substring that matched a variablish expression. undef is returned on failure. In addition, the original input text has the returned substring (and any prefix) removed from it.

In a void context, the input text just has the matched substring (and any specified prefix) removed.

extract_tagged

extract_tagged extracts and segments text between (balanced) specified tags.

The subroutine takes up to five optional arguments:

  1. A string to be processed ($_ if the string is omitted or undef)

  2. A string specifying a pattern to be matched as the opening tag. If the pattern string is omitted (or undef) then a pattern that matches any standard XML tag is used.

  3. A string specifying a pattern to be matched at the closing tag. If the pattern string is omitted (or undef) then the closing tag is constructed by inserting a / after any leading bracket characters in the actual opening tag that was matched (not the pattern that matched the tag). For example, if the opening tag pattern is specified as '{{\w+}}' and actually matched the opening tag "{{DATA}}", then the constructed closing tag would be "{{/DATA}}".

  4. A string specifying a pattern to be matched as a prefix (which is to be skipped). If omitted, optional whitespace is skipped.

  5. A hash reference containing various parsing options (see below)

The various options that can be specified are:

reject => $listref

The list reference contains one or more strings specifying patterns that must not appear within the tagged text.

For example, to extract an HTML link (which should not contain nested links) use:

        extract_tagged($text, '<A>', '</A>', undef, {reject => ['<A>']} );
ignore => $listref

The list reference contains one or more strings specifying patterns that are not be be treated as nested tags within the tagged text (even if they would match the start tag pattern).

For example, to extract an arbitrary XML tag, but ignore "empty" elements:

        extract_tagged($text, undef, undef, undef, {ignore => ['<[^>]*/>']} );

(also see gen_delimited_pat below).

fail => $str

The fail option indicates the action to be taken if a matching end tag is not encountered (i.e. before the end of the string or some reject pattern matches). By default, a failure to match a closing tag causes extract_tagged to immediately fail.

However, if the string value associated with <reject> is "MAX", then extract_tagged returns the complete text up to the point of failure. If the string is "PARA", extract_tagged returns only the first paragraph after the tag (up to the first line that is either empty or contains only whitespace characters). If the string is "", the the default behaviour (i.e. failure) is reinstated.

For example, suppose the start tag "/para" introduces a paragraph, which then continues until the next "/endpara" tag or until another "/para" tag is encountered:

        $text = "/para line 1\n\nline 3\n/para line 4";

        extract_tagged($text, '/para', '/endpara', undef,
                                {reject => '/para', fail => MAX );

        # EXTRACTED: "/para line 1\n\nline 3\n"

Suppose instead, that if no matching "/endpara" tag is found, the "/para" tag refers only to the immediately following paragraph:

        $text = "/para line 1\n\nline 3\n/para line 4";

        extract_tagged($text, '/para', '/endpara', undef,
                        {reject => '/para', fail => MAX );

        # EXTRACTED: "/para line 1\n"

Note that the specified fail behaviour applies to nested tags as well.

On success in a list context, an array of 6 elements is returned. The elements are:

[0]

the extracted tagged substring (including the outermost tags),

[1]

the remainder of the input text,

[2]

the prefix substring (if any),

[3]

the opening tag

[4]

the text between the opening and closing tags

[5]

the closing tag (or "" if no closing tag was found)

On failure, all of these values (except the remaining text) are undef.

In a scalar context, extract_tagged returns just the complete substring that matched a tagged text (including the start and end tags). undef is returned on failure. In addition, the original input text has the returned substring (and any prefix) removed from it.

In a void context, the input text just has the matched substring (and any specified prefix) removed.

gen_extract_tagged

(Note: This subroutine is only available under Perl5.005)

gen_extract_tagged generates a new anonymous subroutine which extracts text between (balanced) specified tags. In other words, it generates a function identical in function to extract_tagged.

The difference between extract_tagged and the anonymous subroutines generated by gen_extract_tagged, is that those generated subroutines:

  • do not have to reparse tag specification or parsing options every time they are called (whereas extract_tagged has to effectively rebuild its tag parser on every call);

  • make use of the new qr// construct to pre-compile the regexes they use (whereas extract_tagged uses standard string variable interpolation to create tag-matching patterns).

The subroutine takes up to four optional arguments (the same set as extract_tagged except for the string to be processed). It returns a reference to a subroutine which in turn takes a single argument (the text to be extracted from).

In other words, the implementation of extract_tagged is exactly equivalent to:

        sub extract_tagged
        {
                my $text = shift;
                $extractor = gen_extract_tagged(@_);
                return $extractor->($text);
        }

(although extract_tagged is not currently implemented that way, in order to preserve pre-5.005 compatibility).

Using gen_extract_tagged to create extraction functions for specific tags is a good idea if those functions are going to be called more than once, since their performance is typically twice as good as the more general-purpose extract_tagged.

extract_quotelike

extract_quotelike attempts to recognize, extract, and segment any one of the various Perl quotes and quotelike operators (see perlop(3)) Nested backslashed delimiters, embedded balanced bracket delimiters (for the quotelike operators), and trailing modifiers are all caught. For example, in:

        extract_quotelike 'q # an octothorpe: \# (not the end of the q!) #'

        extract_quotelike '  "You said, \"Use sed\"."  '
        extract_quotelike ' s{([A-Z]{1,8}\.[A-Z]{3})} /\L$1\E/; '

        extract_quotelike ' tr/\\\/\\\\/\\\//ds; '

the full Perl quotelike operations are all extracted correctly.

Note too that, when using the /x modifier on a regex, any comment containing the current pattern delimiter will cause the regex to be immediately terminated. In other words:

        'm /
                (?i)            # CASE INSENSITIVE
                [a-z_]          # LEADING ALPHABETIC/UNDERSCORE
                [a-z0-9]*       # FOLLOWED BY ANY NUMBER OF ALPHANUMERICS
           /x'

will be extracted as if it were:

        'm /
                (?i)            # CASE INSENSITIVE
                [a-z_]          # LEADING ALPHABETIC/'

This behaviour is identical to that of the actual compiler.

extract_quotelike takes two arguments: the text to be processed and a prefix to be matched at the very beginning of the text. If no prefix is specified, optional whitespace is the default. If no text is given, $_ is used.

In a list context, an array of 11 elements is returned. The elements are:

[0]

the extracted quotelike substring (including trailing modifiers),

[1]

the remainder of the input text,

[2]

the prefix substring (if any),

[3]

the name of the quotelike operator (if any),

[4]

the left delimiter of the first block of the operation,

[5]

the text of the first block of the operation (that is, the contents of a quote, the regex of a match or substitution or the target list of a translation),

[6]

the right delimiter of the first block of the operation,

[7]

the left delimiter of the second block of the operation (that is, if it is a s, tr, or y),

[8]

the text of the second block of the operation (that is, the replacement of a substitution or the translation list of a translation),

[9]

the right delimiter of the second block of the operation (if any),

[10]

the trailing modifiers on the operation (if any).

For each of the fields marked "(if any)" the default value on success is an empty string. On failure, all of these values (except the remaining text) are undef.

In a scalar context, extract_quotelike returns just the complete substring that matched a quotelike operation (or undef on failure). In a scalar or void context, the input text has the same substring (and any specified prefix) removed.

Examples:

        # Remove the first quotelike literal that appears in text

                $quotelike = extract_quotelike($text,'.*?');

        # Replace one or more leading whitespace-separated quotelike
        # literals in $_ with "<QLL>"

                do { $_ = join '<QLL>', (extract_quotelike)[2,1] } until $@;

        # Isolate the search pattern in a quotelike operation from $text

                ($op,$pat) = (extract_quotelike $text)[3,5];
                if ($op =~ /[ms]/)
                {
                        print "search pattern: $pat\n";
                }
                else
                {
                        print "$op is not a pattern matching operation\n";
                }

extract_quotelike and "here documents"

extract_quotelike can successfully extract "here documents" from an input string, but with an important caveat in list contexts.

Unlike other types of quote-like literals, a here document is rarely a contiguous substring. For example, a typical piece of code using here document might look like this:

        <<'EOMSG' || die;
        This is the message.
        EOMSG
        exit;

Given this as an input string in a scalar context, extract_quotelike would correctly return the string "<<'EOMSG'\nThis is the message.\nEOMSG", leaving the string " || die;\nexit;" in the original variable. In other words, the two separate pieces of the here document are successfully extracted and concatenated.

In a list context, extract_quotelike would return the list

[0]

"<<'EOMSG'\nThis is the message.\nEOMSG\n" (i.e. the full extracted here document, including fore and aft delimiters),

[1]

" || die;\nexit;" (i.e. the remainder of the input text, concatenated),

[2]

"" (i.e. the prefix substring -- trivial in this case),

[3]

"<<" (i.e. the "name" of the quotelike operator)

[4]

"'EOMSG'" (i.e. the left delimiter of the here document, including any quotes),

[5]

"This is the message.\n" (i.e. the text of the here document),

[6]

"EOMSG" (i.e. the right delimiter of the here document),

[7..10]

"" (a here document has no second left delimiter, second text, second right delimiter, or trailing modifiers).

However, the matching position of the input variable would be set to "exit;" (i.e. after the closing delimiter of the here document), which would cause the earlier " || die;\nexit;" to be skipped in any sequence of code fragment extractions.

To avoid this problem, when it encounters a here document whilst extracting from a modifiable string, extract_quotelike silently rearranges the string to an equivalent piece of Perl:

        <<'EOMSG'
        This is the message.
        EOMSG
        || die;
        exit;

in which the here document is contiguous. It still leaves the matching position after the here document, but now the rest of the line on which the here document starts is not skipped.

To prevent <extract_quotelike> from mucking about with the input in this way (this is the only case where a list-context extract_quotelike does so), you can pass the input variable as an interpolated literal:

        $quotelike = extract_quotelike("$var");

extract_codeblock

extract_codeblock attempts to recognize and extract a balanced bracket delimited substring that may contain unbalanced brackets inside Perl quotes or quotelike operations. That is, extract_codeblock is like a combination of "extract_bracketed" and "extract_quotelike".

extract_codeblock takes the same initial three parameters as extract_bracketed: a text to process, a set of delimiter brackets to look for, and a prefix to match first. It also takes an optional fourth parameter, which allows the outermost delimiter brackets to be specified separately (see below).

Omitting the first argument (input text) means process $_ instead. Omitting the second argument (delimiter brackets) indicates that only '{' is to be used. Omitting the third argument (prefix argument) implies optional whitespace at the start. Omitting the fourth argument (outermost delimiter brackets) indicates that the value of the second argument is to be used for the outermost delimiters.

Once the prefix an dthe outermost opening delimiter bracket have been recognized, code blocks are extracted by stepping through the input text and trying the following alternatives in sequence:

  1. Try and match a closing delimiter bracket. If the bracket was the same species as the last opening bracket, return the substring to that point. If the bracket was mismatched, return an error.

  2. Try to match a quote or quotelike operator. If found, call extract_quotelike to eat it. If extract_quotelike fails, return the error it returned. Otherwise go back to step 1.

  3. Try to match an opening delimiter bracket. If found, call extract_codeblock recursively to eat the embedded block. If the recursive call fails, return an error. Otherwise, go back to step 1.

  4. Unconditionally match a bareword or any other single character, and then go back to step 1.

Examples:

        # Find a while loop in the text

                if ($text =~ s/.*?while\s*\{/{/)
                {
                        $loop = "while " . extract_codeblock($text);
                }

        # Remove the first round-bracketed list (which may include
        # round- or curly-bracketed code blocks or quotelike operators)

                extract_codeblock $text, "(){}", '[^(]*';

The ability to specify a different outermost delimiter bracket is useful in some circumstances. For example, in the Parse::RecDescent module, parser actions which are to be performed only on a successful parse are specified using a <defer:...> directive. For example:

        sentence: subject verb object
                        <defer: {$::theVerb = $item{verb}} >

Parse::RecDescent uses extract_codeblock($text, '{}<>') to extract the code within the <defer:...> directive, but there's a problem.

A deferred action like this:

                        <defer: {if ($count>10) {$count--}} >

will be incorrectly parsed as:

                        <defer: {if ($count>

because the "less than" operator is interpreted as a closing delimiter.

But, by extracting the directive using extract_codeblock($text, '{}', undef, '<>') the '>' character is only treated as a delimited at the outermost level of the code block, so the directive is parsed correctly.

extract_multiple

The extract_multiple subroutine takes a string to be processed and a list of extractors (subroutines or regular expressions) to apply to that string.

In an array context extract_multiple returns an array of substrings of the original string, as extracted by the specified extractors. In a scalar context, extract_multiple returns the first substring successfully extracted from the original string. In both scalar and void contexts the original string has the first successfully extracted substring removed from it. In all contexts extract_multiple starts at the current pos of the string, and sets that pos appropriately after it matches.

Hence, the aim of of a call to extract_multiple in a list context is to split the processed string into as many non-overlapping fields as possible, by repeatedly applying each of the specified extractors to the remainder of the string. Thus extract_multiple is a generalized form of Perl's split subroutine.

The subroutine takes up to four optional arguments:

  1. A string to be processed ($_ if the string is omitted or undef)

  2. A reference to a list of subroutine references and/or qr// objects and/or literal strings and/or hash references, specifying the extractors to be used to split the string. If this argument is omitted (or undef) the list:

            [
                sub { extract_variable($_[0], '') },
                sub { extract_quotelike($_[0],'') },
                sub { extract_codeblock($_[0],'{}','') },
        ]

    is used.

  3. An number specifying the maximum number of fields to return. If this argument is omitted (or undef), split continues as long as possible.

    If the third argument is N, then extraction continues until N fields have been successfully extracted, or until the string has been completely processed.

    Note that in scalar and void contexts the value of this argument is automatically reset to 1 (under -w, a warning is issued if the argument has to be reset).

  4. A value indicating whether unmatched substrings (see below) within the text should be skipped or returned as fields. If the value is true, such substrings are skipped. Otherwise, they are returned.

The extraction process works by applying each extractor in sequence to the text string.

If the extractor is a subroutine it is called in a list context and is expected to return a list of a single element, namely the extracted text. It may optionally also return two further arguments: a string representing the text left after extraction (like $' for a pattern match), and a string representing any prefix skipped before the extraction (like $` in a pattern match). Note that this is designed to facilitate the use of other Text::Balanced subroutines with extract_multiple. Note too that the value returned by an extractor subroutine need not bear any relationship to the corresponding substring of the original text (see examples below).

If the extractor is a precompiled regular expression or a string, it is matched against the text in a scalar context with a leading '\G' and the gc modifiers enabled. The extracted value is either $1 if that variable is defined after the match, or else the complete match (i.e. $&).

If the extractor is a hash reference, it must contain exactly one element. The value of that element is one of the above extractor types (subroutine reference, regular expression, or string). The key of that element is the name of a class into which the successful return value of the extractor will be blessed.

If an extractor returns a defined value, that value is immediately treated as the next extracted field and pushed onto the list of fields. If the extractor was specified in a hash reference, the field is also blessed into the appropriate class,

If the extractor fails to match (in the case of a regex extractor), or returns an empty list or an undefined value (in the case of a subroutine extractor), it is assumed to have failed to extract. If none of the extractor subroutines succeeds, then one character is extracted from the start of the text and the extraction subroutines reapplied. Characters which are thus removed are accumulated and eventually become the next field (unless the fourth argument is true, in which case they are disgarded).

For example, the following extracts substrings that are valid Perl variables:

        @fields = extract_multiple($text,
                                   [ sub { extract_variable($_[0]) } ],
                                   undef, 1);

This example separates a text into fields which are quote delimited, curly bracketed, and anything else. The delimited and bracketed parts are also blessed to identify them (the "anything else" is unblessed):

        @fields = extract_multiple($text,
                   [
                        { Delim => sub { extract_delimited($_[0],q{'"}) } },
                        { Brack => sub { extract_bracketed($_[0],'{}') } },
                   ]);

This call extracts the next single substring that is a valid Perl quotelike operator (and removes it from $text):

        $quotelike = extract_multiple($text,
                                      [
                                        sub { extract_quotelike($_[0]) },
                                      ], undef, 1);

Finally, here is yet another way to do comma-separated value parsing:

        @fields = extract_multiple($csv_text,
                                  [
                                        sub { extract_delimited($_[0],q{'"}) },
                                        qr/([^,]+)(.*)/,
                                  ],
                                  undef,1);

The list in the second argument means: "Try and extract a ' or " delimited string, otherwise extract anything up to a comma...". The undef third argument means: "...as many times as possible...", and the true value in the fourth argument means "...discarding anything else that appears (i.e. the commas)".

If you wanted the commas preserved as separate fields (i.e. like split does if your split pattern has capturing parentheses), you would just make the last parameter undefined (or remove it).

gen_delimited_pat

The gen_delimited_pat subroutine takes a single (string) argument and > builds a Friedl-style optimized regex that matches a string delimited by any one of the characters in the single argument. For example:

        gen_delimited_pat(q{'"})

returns the regex:

        (?:\"(?:\\\"|(?!\").)*\"|\'(?:\\\'|(?!\').)*\')

Note that the specified delimiters are automatically quotemeta'd.

A typical use of gen_delimited_pat would be to build special purpose tags for extract_tagged. For example, to properly ignore "empty" XML elements (which might contain quoted strings):

        my $empty_tag = '<(' . gen_delimited_pat(q{'"}) . '|.)+/>';

        extract_tagged($text, undef, undef, undef, {ignore => [$empty_tag]} );

gen_delimited_pat may also be called with an optional second argument, which specifies the "escape" character(s) to be used for each delimiter. For example to match a Pascal-style string (where ' is the delimiter and '' is a literal ' within the string):

        gen_delimited_pat(q{'},q{'});

Different escape characters can be specified for different delimiters. For example, to specify that '/' is the escape for single quotes and '%' is the escape for double quotes:

        gen_delimited_pat(q{'"},q{/%});

If more delimiters than escape chars are specified, the last escape char is used for the remaining delimiters. If no escape char is specified for a given specified delimiter, '\' is used.

Note that gen_delimited_pat was previously called delimited_pat. That name may still be used, but is now deprecated.

DIAGNOSTICS

In a list context, all the functions return (undef,$original_text) on failure. In a scalar context, failure is indicated by returning undef (in this case the input text is not modified in any way).

In addition, on failure in any context, the $@ variable is set. Accessing $@->{error} returns one of the error diagnostics listed below. Accessing $@->{pos} returns the offset into the original string at which the error was detected (although not necessarily where it occurred!) Printing $@ directly produces the error message, with the offset appended. On success, the $@ variable is guaranteed to be undef.

The available diagnostics are:

Did not find a suitable bracket: "%s"

The delimiter provided to extract_bracketed was not one of '()[]<>{}'.

Did not find prefix: /%s/

A non-optional prefix was specified but wasn't found at the start of the text.

Did not find opening bracket after prefix: "%s"

extract_bracketed or extract_codeblock was expecting a particular kind of bracket at the start of the text, and didn't find it.

No quotelike operator found after prefix: "%s"

extract_quotelike didn't find one of the quotelike operators q, qq, qw, qx, s, tr or y at the start of the substring it was extracting.

Unmatched closing bracket: "%c"

extract_bracketed, extract_quotelike or extract_codeblock encountered a closing bracket where none was expected.

Unmatched opening bracket(s): "%s"

extract_bracketed, extract_quotelike or extract_codeblock ran out of characters in the text before closing one or more levels of nested brackets.

Unmatched embedded quote (%s)

extract_bracketed attempted to match an embedded quoted substring, but failed to find a closing quote to match it.

Did not find closing delimiter to match '%s'

extract_quotelike was unable to find a closing delimiter to match the one that opened the quote-like operation.

Mismatched closing bracket: expected "%c" but found "%s"

extract_bracketed, extract_quotelike or extract_codeblock found a valid bracket delimiter, but it was the wrong species. This usually indicates a nesting error, but may indicate incorrect quoting or escaping.

No block delimiter found after quotelike "%s"

extract_quotelike or extract_codeblock found one of the quotelike operators q, qq, qw, qx, s, tr or y without a suitable block after it.

Did not find leading dereferencer

extract_variable was expecting one of '$', '@', or '%' at the start of a variable, but didn't find any of them.

Bad identifier after dereferencer

extract_variable found a '$', '@', or '%' indicating a variable, but that character was not followed by a legal Perl identifier.

Did not find expected opening bracket at %s

extract_codeblock failed to find any of the outermost opening brackets that were specified.

Improperly nested codeblock at %s

A nested code block was found that started with a delimiter that was specified as being only to be used as an outermost bracket.

Missing second block for quotelike "%s"

extract_codeblock or extract_quotelike found one of the quotelike operators s, tr or y followed by only one block.

No match found for opening bracket

extract_codeblock failed to find a closing bracket to match the outermost opening bracket.

Did not find opening tag: /%s/

extract_tagged did not find a suitable opening tag (after any specified prefix was removed).

Unable to construct closing tag to match: /%s/

extract_tagged matched the specified opening tag and tried to modify the matched text to produce a matching closing tag (because none was specified). It failed to generate the closing tag, almost certainly because the opening tag did not start with a bracket of some kind.

Found invalid nested tag: %s

extract_tagged found a nested tag that appeared in the "reject" list (and the failure mode was not "MAX" or "PARA").

Found unbalanced nested tag: %s

extract_tagged found a nested opening tag that was not matched by a corresponding nested closing tag (and the failure mode was not "MAX" or "PARA").

Did not find closing tag

extract_tagged reached the end of the text without finding a closing tag to match the original opening tag (and the failure mode was not "MAX" or "PARA").

AUTHOR

Damian Conway (damian@conway.org)

BUGS AND IRRITATIONS

There are undoubtedly serious bugs lurking somewhere in this code, if only because parts of it give the impression of understanding a great deal more about Perl than they really do.

Bug reports and other feedback are most welcome.

COPYRIGHT

 Copyright (c) 1997-2001, Damian Conway. All Rights Reserved.
 This module is free software. It may be used, redistributed
     and/or modified under the same terms as Perl itself.


Text::Diff - Perform diffs on files and record sets

  • OPTIONS
  • Formatting Classes
    • Text::Diff::Base
    • Text::Diff::Unified
    • Text::Diff::Table
    • Text::Diff::Context
    • Text::Diff::OldStyle
  • LIMITATIONS
  • AUTHOR
  • COPYRIGHT & LICENSE

NAME

Text::Diff - Perform diffs on files and record sets

SYNOPSIS

    use Text::Diff;

    ## Mix and match filenames, strings, file handles, producer subs,
    ## or arrays of records; returns diff in a string.
    ## WARNING: can return B<large> diffs for large files.
    my $diff = diff "file1.txt", "file2.txt", { STYLE => "Context" };
    my $diff = diff \$string1,   \$string2,   \%options;
    my $diff = diff \*FH1,       \*FH2;
    my $diff = diff \&reader1,   \&reader2;
    my $diff = diff \@records1,  \@records2;

    ## May also mix input types:
    my $diff = diff \@records1,  "file_B.txt";

DESCRIPTION

diff() provides a basic set of services akin to the GNU diff utility. It is not anywhere near as feature complete as GNU diff, but it is better integrated with Perl and available on all platforms. It is often faster than shelling out to a system's diff executable for small files, and generally slower on larger files.

Relies on the Algorithm::Diff manpage for, well, the algorithm. This may not produce the same exact diff as a system's local diff executable, but it will be a valid diff and comprehensible by patch. We haven't seen any differences between Algorithm::Diff's logic and GNU diff's, but we have not examined them to make sure they are indeed identical.

Note: If you don't want to import the diff function, do one of the following:

   use Text::Diff ();

   require Text::Diff;

That's a pretty rare occurence, so diff() is exported by default.

OPTIONS

diff() takes two parameters from which to draw input and a set of options to control it's output. The options are:

FILENAME_A, MTIME_A, FILENAME_B, MTIME_B

The name of the file and the modification time "files"

These are filled in automatically for each file when diff() is passed a filename, unless a defined value is passed in.

If a filename is not passed in and FILENAME_A and FILENAME_B are not provided or undef, the header will not be printed.

Unused on OldStyle diffs.

OFFSET_A, OFFSET_B

The index of the first line / element. These default to 1 for all parameter types except ARRAY references, for which the default is 0. This is because ARRAY references are presumed to be data structures, while the others are line oriented text.

STYLE

"Unified", "Context", "OldStyle", or an object or class reference for a class providing file_header(), hunk_header(), hunk(), hunk_footer() and file_footer() methods. The two footer() methods are provided for overloading only; none of the formats provide them.

Defaults to "Unified" (unlike standard diff, but Unified is what's most often used in submitting patches and is the most human readable of the three.

If the package indicated by the STYLE has no hunk() method, c<diff()> will load it automatically (lazy loading). Since all such packages should inherit from Text::Diff::Base, this should be marvy.

Styles may be specified as class names (STYLE = "Foo"), in which case they will be new()ed with no parameters, or as objects (STYLE = Foo->new>).

CONTEXT

How many lines before and after each diff to display. Ignored on old-style diffs. Defaults to 3.

OUTPUT

Examples and their equivalent subroutines:

    OUTPUT   => \*FOOHANDLE,   # like: sub { print FOOHANDLE shift() }
    OUTPUT   => \$output,      # like: sub { $output .= shift }
    OUTPUT   => \@output,      # like: sub { push @output, shift }
    OUTPUT   => sub { $output .= shift },

If no OUTPUT is supplied, returns the diffs in a string. If OUTPUT is a CODE ref, it will be called once with the (optional) file header, and once for each hunk body with the text to emit. If OUTPUT is an the IO::Handle manpage, output will be emitted to that handle.

FILENAME_PREFIX_A, FILENAME_PREFIX_B

The string to print before the filename in the header. Unused on OldStyle diffs. Defaults are "---", "+++" for Unified and "***", "+++" for Context.

KEYGEN, KEYGEN_ARGS

These are passed to traverse_sequences in the Algorithm::Diff manpage.

Note: if neither FILENAME_ option is defined, the header will not be printed. If at one is present, the other and both MTIME_ options must be present or "Use of undefined variable" warnings will be generated (except on OldStyle diffs, which ignores these options).

Formatting Classes

These functions implement the output formats. They are grouped in to classes so diff() can use class names to call the correct set of output routines and so that you may inherit from them easily. There are no constructors or instance methods for these classes, though subclasses may provide them if need be.

Each class has file_header(), hunk_header(), hunk(), and footer() methods identical to those documented in the Text::Diff::Unified section. header() is called before the hunk() is first called, footer() afterwards. The default footer function is an empty method provided for overloading:

    sub footer { return "End of patch\n" }

Some output formats are provided by external modules (which are loaded automatically), such as the Text::Diff::Table manpage. These are are documented here to keep the documentation simple.

Text::Diff::Base

Returns "" for all methods (other than new()).

Text::Diff::Unified

    --- A   Mon Nov 12 23:49:30 2001
    +++ B   Mon Nov 12 23:49:30 2001
    @@ -2,13 +2,13 @@
     2
     3
     4
    -5d
    +5a
     6
     7
     8
     9
    +9a
     10
     11
    -11d
     12
     13
file_header
    $s = Text::Diff::Unified->file_header( $options );

Returns a string containing a unified header. The sole parameter is the options hash passed in to diff(), containing at least:

    FILENAME_A  => $fn1,
    MTIME_A     => $mtime1,
    FILENAME_B  => $fn2,
    MTIME_B     => $mtime2

May also contain

    FILENAME_PREFIX_A    => "---",
    FILENAME_PREFIX_B    => "+++",

to override the default prefixes (default values shown).

hunk_header
    Text::Diff::Unified->hunk_header( \@ops, $options );

Returns a string containing the output of one hunk of unified diff.

Text::Diff::Unified::hunk
    Text::Diff::Unified->hunk( \@seq_a, \@seq_b, \@ops, $options );

Returns a string containing the output of one hunk of unified diff.

Text::Diff::Table

 +--+----------------------------------+--+------------------------------+
 |  |../Test-Differences-0.2/MANIFEST  |  |../Test-Differences/MANIFEST  |
 |  |Thu Dec 13 15:38:49 2001          |  |Sat Dec 15 02:09:44 2001      |
 +--+----------------------------------+--+------------------------------+
 |  |                                  * 1|Changes                       *
 | 1|Differences.pm                    | 2|Differences.pm                |
 | 2|MANIFEST                          | 3|MANIFEST                      |
 |  |                                  * 4|MANIFEST.SKIP                 *
 | 3|Makefile.PL                       | 5|Makefile.PL                   |
 |  |                                  * 6|t/00escape.t                  *
 | 4|t/00flatten.t                     | 7|t/00flatten.t                 |
 | 5|t/01text_vs_data.t                | 8|t/01text_vs_data.t            |
 | 6|t/10test.t                        | 9|t/10test.t                    |
 +--+----------------------------------+--+------------------------------+

This format also goes to some pains to highlight "invisible" characters on differing elements by selectively escaping whitespace:

 +--+--------------------------+--------------------------+
 |  |demo_ws_A.txt             |demo_ws_B.txt             |
 |  |Fri Dec 21 08:36:32 2001  |Fri Dec 21 08:36:50 2001  |
 +--+--------------------------+--------------------------+
 | 1|identical                 |identical                 |
 * 2|        spaced in         |        also spaced in    *
 * 3|embedded space            |embedded        tab       *
 | 4|identical                 |identical                 |
 * 5|        spaced in         |\ttabbed in               *
 * 6|trailing spaces\s\s\n     |trailing tabs\t\t\n       *
 | 7|identical                 |identical                 |
 * 8|lf line\n                 |crlf line\r\n             *
 * 9|embedded ws               |embedded\tws              *
 +--+--------------------------+--------------------------+

See Text::Diff::Table for more details, including how the whitespace escaping works.

Text::Diff::Context

    *** A   Mon Nov 12 23:49:30 2001
    --- B   Mon Nov 12 23:49:30 2001
    ***************
    *** 2,14 ****
      2
      3
      4
    ! 5d
      6
      7
      8
      9
      10
      11
    - 11d
      12
      13
    --- 2,14 ----
      2
      3
      4
    ! 5a
      6
      7
      8
      9
    + 9a
      10
      11
      12
      13

Note: hunk_header() returns only "***************\n".

Text::Diff::OldStyle

    5c5
    < 5d
    ---
    > 5a
    9a10
    > 9a
    12d12
    < 11d

Note: no file_header().

LIMITATIONS

Must suck both input files entirely in to memory and store them with a normal amount of Perlish overhead (one array location) per record. This is implied by the implementation of Algorithm::Diff, which takes two arrays. If Algorithm::Diff ever offers an incremental mode, this can be changed (contact the maintainers of Algorithm::Diff and Text::Diff if you need this; it shouldn't be too terribly hard to tie arrays in this fashion).

Does not provide most of the more refined GNU diff options: recursive directory tree scanning, ignoring blank lines / whitespace, etc., etc. These can all be added as time permits and need arises, many are rather easy; patches quite welcome.

Uses closures internally, this may lead to leaks on perl versions 5.6.1 and prior if used many times over a process' life time.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>.

COPYRIGHT & LICENSE

Copyright 2001, Barrie Slaymaker. All Rights Reserved.

You may use this under the terms of either the Artistic License or GNU Public License v 2.0 or greater.


Text::Diff::Table - Text::Diff plugin to generate "table" format output

  • LIMITATIONS
  • AUTHOR
  • LICENSE

NAME

    Text::Diff::Table - Text::Diff plugin to generate "table" format output

SYNOPSIS

    use Text::Diff;

    diff \@a, $b { STYLE => "Table" };

DESCRIPTION

This is a plugin output formatter for Text::Diff that generates "table" style diffs:

 +--+----------------------------------+--+------------------------------+
 |  |../Test-Differences-0.2/MANIFEST  |  |../Test-Differences/MANIFEST  |
 |  |Thu Dec 13 15:38:49 2001          |  |Sat Dec 15 02:09:44 2001      |
 +--+----------------------------------+--+------------------------------+
 |  |                                  * 1|Changes                       *
 | 1|Differences.pm                    | 2|Differences.pm                |
 | 2|MANIFEST                          | 3|MANIFEST                      |
 |  |                                  * 4|MANIFEST.SKIP                 *
 | 3|Makefile.PL                       | 5|Makefile.PL                   |
 |  |                                  * 6|t/00escape.t                  *
 | 4|t/00flatten.t                     | 7|t/00flatten.t                 |
 | 5|t/01text_vs_data.t                | 8|t/01text_vs_data.t            |
 | 6|t/10test.t                        | 9|t/10test.t                    |
 +--+----------------------------------+--+------------------------------+

This format also goes to some pains to highlight "invisible" characters on differing elements by selectively escaping whitespace. Each element is split in to three segments (leading whitespace, body, trailing whitespace). If whitespace differs in a segement, that segment is whitespace escaped.

Here is an example of the selective whitespace.

 +--+--------------------------+--------------------------+
 |  |demo_ws_A.txt             |demo_ws_B.txt             |
 |  |Fri Dec 21 08:36:32 2001  |Fri Dec 21 08:36:50 2001  |
 +--+--------------------------+--------------------------+
 | 1|identical                 |identical                 |
 * 2|        spaced in         |        also spaced in    *
 * 3|embedded space            |embedded        tab       *
 | 4|identical                 |identical                 |
 * 5|        spaced in         |\ttabbed in               *
 * 6|trailing spaces\s\s\n     |trailing tabs\t\t\n       *
 | 7|identical                 |identical                 |
 * 8|lf line\n                 |crlf line\r\n             *
 * 9|embedded ws               |embedded\tws              *
 +--+--------------------------+--------------------------+

Here's why the lines do or do not have whitespace escaped:

lines 1, 4, 7 don't differ, no need.
lines 2, 3 differ in non-whitespace, no need.
lines 5, 6, 8, 9 all have subtle ws changes.

Whether or not line 3 should have that tab character escaped is a judgement call; so far I'm choosing not to.

LIMITATIONS

Table formatting requires buffering the entire diff in memory in order to calculate column widths. This format should only be used for smaller diffs.

Assumes tab stops every 8 characters, as $DIETY intended.

Assumes all character codes >= 127 need to be escaped as hex codes, ie that the user's terminal is ASCII, and not even "high bit ASCII", capable. This can be made an option when the need arises.

Assumes that control codes (character codes 0..31) that don't have slash-letter escapes ("\n", "\r", etc) in Perl are best presented as hex escapes ("\x01") instead of octal ("\001") or control-code ("\cA") escapes.

AUTHOR

    Barrie Slaymaker <barries@slaysys.com>

LICENSE

Copyright 2001 Barrie Slaymaker, All Rights Reserved.

You may use this software under the terms of the GNU public license, any version, or the Artistic license.


Text::ParseWords - parse text into an array of tokens or array of arrays

  • EXAMPLES
  • AUTHORS

NAME

Text::ParseWords - parse text into an array of tokens or array of arrays

SYNOPSIS

  use Text::ParseWords;
  @lists = &nested_quotewords($delim, $keep, @lines);
  @words = &quotewords($delim, $keep, @lines);
  @words = &shellwords(@lines);
  @words = &parse_line($delim, $keep, $line);
  @words = &old_shellwords(@lines); # DEPRECATED!

DESCRIPTION

The &nested_quotewords() and &quotewords() functions accept a delimiter (which can be a regular expression) and a list of lines and then breaks those lines up into a list of words ignoring delimiters that appear inside quotes. &quotewords() returns all of the tokens in a single long list, while &nested_quotewords() returns a list of token lists corresponding to the elements of @lines. &parse_line() does tokenizing on a single string. The &*quotewords() functions simply call &parse_line(), so if you're only splitting one line you can call &parse_line() directly and save a function call.

The $keep argument is a boolean flag. If true, then the tokens are split on the specified delimiter, but all other characters (quotes, backslashes, etc.) are kept in the tokens. If $keep is false then the &*quotewords() functions remove all quotes and backslashes that are not themselves backslash-escaped or inside of single quotes (i.e., &quotewords() tries to interpret these characters just like the Bourne shell). NB: these semantics are significantly different from the original version of this module shipped with Perl 5.000 through 5.004. As an additional feature, $keep may be the keyword "delimiters" which causes the functions to preserve the delimiters in each string as tokens in the token lists, in addition to preserving quote and backslash characters.

&shellwords() is written as a special case of &quotewords(), and it does token parsing with whitespace as a delimiter-- similar to most Unix shells.

EXAMPLES

The sample program:

  use Text::ParseWords;
  @words = &quotewords('\s+', 0, q{this   is "a test" of\ quotewords \"for you});
  $i = 0;
  foreach (@words) {
      print "$i: <$_>\n";
      $i++;
  }

produces:

  0: <this>
  1: <is>
  2: <a test>
  3: <of quotewords>
  4: <"for>
  5: <you>

demonstrating:

  1. a simple word

  2. multiple spaces are skipped because of our $delim

  3. use of quotes to include a space in a word

  4. use of a backslash to include a space in a word

  5. use of a backslash to remove the special meaning of a double-quote

  6. another simple word (note the lack of effect of the backslashed double-quote)

Replacing &quotewords('\s+', 0, q{this is...}) with &shellwords(q{this is...}) is a simpler way to accomplish the same thing.

AUTHORS

Maintainer is Hal Pomeranz <pomeranz@netcom.com>, 1994-1997 (Original author unknown). Much of the code for &parse_line() (including the primary regexp) from Joerk Behrends <jbehrends@multimediaproduzenten.de>.

Examples section another documentation provided by John Heidemann <johnh@ISI.EDU>

Bug reports, patches, and nagging provided by lots of folks-- thanks everybody! Special thanks to Michael Schwern <schwern@envirolink.org> for assuring me that a &nested_quotewords() would be useful, and to Jeff Friedl <jfriedl@yahoo-inc.com> for telling me not to worry about error-checking (sort of-- you had to be there).


Text::Reform - Manual text wrapping and reformatting

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • The form sub
    • Controlling line filling.
    • Temporary and permanent default options
    • Multi-line format specifiers and interleaving
    • How form hyphenates
    • The form formatting algorithm
    • form examples
    • How form consumes strings
    • Numerical formatting
    • Filling block fields with lists of values
    • Headers, footers, and pages
    • The cols option
    • The tag sub
  • AUTHOR
  • BUGS
  • COPYRIGHT

NAME

Text::Reform - Manual text wrapping and reformatting

VERSION

This document describes version 1.11 of Text::Reform, released May 7, 2003.

SYNOPSIS

        use Text::Reform;

        print form $template,
                   $data, $to, $fill, $it, $with;

        use Text::Reform qw( tag );

        print tag 'B', $enboldened_text;

DESCRIPTION

The form sub

The form() subroutine may be exported from the module. It takes a series of format (or "picture") strings followed by replacement values, interpolates those values into each picture string, and returns the result. The effect is similar to the inbuilt perl format mechanism, although the field specification syntax is simpler and some of the formatting behaviour is more sophisticated.

A picture string consists of sequences of the following characters:

<

Left-justified field indicator. A series of two or more sequential <'s specify a left-justified field to be filled by a subsequent value. A single < is formatted as the literal character '<'

>

Right-justified field indicator. A series of two or more sequential >'s specify a right-justified field to be filled by a subsequent value. A single < is formatted as the literal character '<'

<<<>>>

Fully-justified field indicator. Field may be of any width, and brackets need not balance, but there must be at least 2 '<' and 2 '>'.

^

Centre-justified field indicator. A series of two or more sequential ^'s specify a centred field to be filled by a subsequent value. A single ^ is formatted as the literal character '<'

>>>.<<<<

A numerically formatted field with the specified number of digits to either side of the decimal place. See Numerical formatting below.

[

Left-justified block field indicator. Just like a < field, except it repeats as required on subsequent lines. See below. A single [ is formatted as the literal character '['

]

Right-justified block field indicator. Just like a > field, except it repeats as required on subsequent lines. See below. A single ] is formatted as the literal character ']'

[[[]]]

Fully-justified block field indicator. Just like a <<<>>> field, except it repeats as required on subsequent lines. See below. Field may be of any width, and brackets need not balance, but there must be at least 2 '[' and 2 ']'.

|

Centre-justified block field indicator. Just like a ^ field, except it repeats as required on subsequent lines. See below. A single | is formatted as the literal character '|'

]]].[[[[

A numerically formatted block field with the specified number of digits to either side of the decimal place. Just like a >>>.<<<< field, except it repeats as required on subsequent lines. See below.

~

A one-character wide block field.

\

Literal escape of next character (e.g. \~ is formatted as '~', not a one character wide block field).

Any other character

That literal character.

Any substitution value which is undef (either explicitly so, or because it is missing) is replaced by an empty string.

Controlling line filling.

Note that, unlike the a perl format, form preserves whitespace (including newlines) unless called with certain options.

The "squeeze" option (when specified with a true value) causes any sequence of spaces and/or tabs (but not newlines) in an interpolated string to be replaced with a single space.

A true value for the "fill" option causes (only) newlines to be squeezed.

To minimize all whitespace, you need to specify both options. Hence:

        $format = "EG> [[[[[[[[[[[[[[[[[[[[[";
        $data   = "h  e\t l lo\nworld\t\t\t\t\t";

        print form $format, $data;              # all whitespace preserved:
                                                #
                                                # EG> h  e            l lo
                                                # EG> world

        print form {squeeze=>1},                # only newlines preserved:
                   $format, $data;              #
                                                # EG> h e l lo
                                                # EG> world

        print form {fill=>1},                   # only spaces/tabs preserved:
                    $format, $data;             #
                                                # EG> h  e        l lo world

        print form {squeeze=>1, fill=>1},       # no whitespace preserved:
                   $format, $data;              #
                                                # EG> h e l lo world

Whether or not filling or squeezing is in effect, form can also be directed to trim any extra whitespace from the end of each line it formats, using the "trim" option. If this option is specified with a true value, every line returned by form will automatically have the substitution s/[ \t]+$//gm applied to it.

Hence:

        print length form "[[[[[[[[[[", "short";
        # 11

        print length form {trim=>1}, "[[[[[[[[[[", "short";
        # 6

It is also possible to control the character used to fill lines that are too short, using the 'filler' option. If this option is specified the value of the 'filler' flag is used as the fill string, rather than the default " ".

For example:

        print form { filler=>'*' },
                "Pay bearer: ^^^^^^^^^^^^^^^^^^^",
                '$123.45';

prints:

        Pay bearer: ******$123.45******

If the filler string is longer than one character, it is truncated to the appropriate length. So:

        print form { filler=>'-->' },
                "Pay bearer: ]]]]]]]]]]]]]]]]]]]",
                ['$1234.50', '$123.45', '$12.34'];

prints:

        Pay bearer: ->-->-->-->$1234.50
        Pay bearer: -->-->-->-->$123.45
        Pay bearer: >-->-->-->-->$12.34

If the value of the 'filler' option is a hash, then it's 'left' and 'right' entries specify separate filler strings for each side of an interpolated value. So:

        print form { filler=>{left=>'->', right=>'*'} },
                "Pay bearer: <<<<<<<<<<<<<<<<<<",
                '$123.45',
                "Pay bearer: >>>>>>>>>>>>>>>>>>",
                '$123.45',
                "Pay bearer: ^^^^^^^^^^^^^^^^^^",
                '$123.45';

prints:

        Pay bearer: $123.45***********
        Pay bearer: >->->->->->$123.45
        Pay bearer: >->->$123.45******

Temporary and permanent default options

If form is called with options, but no template string or data, it resets it's defaults to the options specified. If called in a void context:

        form { squeeze => 1, trim => 1 };

the options become permanent defaults.

However, when called with only options in non-void context, form resets its defaults to those options and returns an object. The reset default values persist only until that returned object is destroyed. Hence to temporarily reset form's defaults within a single subroutine:

        sub single {
                my $tmp = form { squeeze => 1, trim => 1 };

                # do formatting with the obove defaults

        } # form's defaults revert to previous values as $tmp object destroyed

Multi-line format specifiers and interleaving

By default, if a format specifier contains two or more lines (i.e. one or more newline characters), the entire format specifier is repeatedly filled as a unit, until all block fields have consumed their corresponding arguments. For example, to build a simple look-up table:

        my @values   = (1..12);

        my @squares  = map { sprintf "%.6g", $_**2    } @values;
        my @roots    = map { sprintf "%.6g", sqrt($_) } @values;
        my @logs     = map { sprintf "%.6g", log($_)  } @values;
        my @inverses = map { sprintf "%.6g", 1/$_     } @values;

        print form
        "  N      N**2    sqrt(N)      log(N)      1/N",
        "=====================================================",
        "| [[  |  [[[  |  [[[[[[[[[[ | [[[[[[[[[ | [[[[[[[[[ |
        -----------------------------------------------------",
        \@values, \@squares, \@roots, \@logs, \@inverses;

The multiline format specifier:

        "| [[  |  [[[  |  [[[[[[[[[[ | [[[[[[[[[ | [[[[[[[[[ |
        -----------------------------------------------------",

is treated as a single logical line. So form alternately fills the first physical line (interpolating one value from each of the arrays) and the second physical line (which puts a line of dashes between each row of the table) producing:

          N      N**2    sqrt(N)      log(N)      1/N
        =====================================================
        | 1   |  1    |  1          | 0         | 1         |
        -----------------------------------------------------
        | 2   |  4    |  1.41421    | 0.693147  | 0.5       |
        -----------------------------------------------------
        | 3   |  9    |  1.73205    | 1.09861   | 0.333333  |
        -----------------------------------------------------
        | 4   |  16   |  2          | 1.38629   | 0.25      |
        -----------------------------------------------------
        | 5   |  25   |  2.23607    | 1.60944   | 0.2       |
        -----------------------------------------------------
        | 6   |  36   |  2.44949    | 1.79176   | 0.166667  |
        -----------------------------------------------------
        | 7   |  49   |  2.64575    | 1.94591   | 0.142857  |
        -----------------------------------------------------
        | 8   |  64   |  2.82843    | 2.07944   | 0.125     |
        -----------------------------------------------------
        | 9   |  81   |  3          | 2.19722   | 0.111111  |
        -----------------------------------------------------
        | 10  |  100  |  3.16228    | 2.30259   | 0.1       |
        -----------------------------------------------------
        | 11  |  121  |  3.31662    | 2.3979    | 0.0909091 |
        -----------------------------------------------------
        | 12  |  144  |  3.4641     | 2.48491   | 0.0833333 |
        -----------------------------------------------------

This implies that formats and the variables from which they're filled need to be interleaved. That is, a multi-line specification like this:

        print form
        "Passed:                      ##
           [[[[[[[[[[[[[[[             # single format specification
        Failed:                        # (needs two sets of data)
           [[[[[[[[[[[[[[[",          ##
        \@passes, \@fails;            ##  data for previous format

would print:

        Passed:
           <pass 1>
        Failed:
           <fail 1>
        Passed:
           <pass 2>
        Failed:
           <fail 2>
        Passed:
           <pass 3>
        Failed:
           <fail 3>

because the four-line format specifier is treated as a single unit, to be repeatedly filled until all the data in @passes and @fails has been consumed.

Unlike the table example, where this unit filling correctly put a line of dashes between lines of data, in this case the alternation of passes and fails is probably not the desired effect.

Judging by the labels, it is far more likely that the user wanted:

        Passed:
           <pass 1>
           <pass 2>
           <pass 3>
        Failed:
           <fail 4>
           <fail 5>
           <fail 6>

To achieve that, either explicitly interleave the formats and their data sources:

        print form
        "Passed:",               ## single format (no data required)
        "   [[[[[[[[[[[[[[[",    ## single format (needs one set of data)
            \@passes,            ## data for previous format
        "Failed:",               ## single format (no data required)
        "   [[[[[[[[[[[[[[[",    ## single format (needs one set of data)
            \@fails;             ## data for previous format

or instruct form to do it for you automagically, by setting the 'interleave' flag true:

        print form {interleave=>1}
        "Passed:                 ##
           [[[[[[[[[[[[[[[        # single format
        Failed:                   # (needs two sets of data)
           [[[[[[[[[[[[[[[",     ##

                                 ## data to be automagically interleaved
                                         \@passes, \@fails;        # as necessary between lines of previous
                                 ## format

How form hyphenates

Any line with a block field repeats on subsequent lines until all block fields on that line have consumed all their data. Non-block fields on these lines are replaced by the appropriate number of spaces.

Words are wrapped whole, unless they will not fit into the field at all, in which case they are broken and (by default) hyphenated. Simple hyphenation is used (i.e. break at the N-1th character and insert a '-'), unless a suitable alternative subroutine is specified instead.

Words will not be broken if the break would leave less than 2 characters on the current line. This minimum can be varied by setting the 'minbreak' option to a numeric value indicating the minumum total broken characters (including hyphens) required on the current line. Note that, for very narrow fields, words will still be broken (but unhyphenated). For example:

        print form '~', 'split';

would print:

        s
        p
        l
        i
        t

whilst:

        print form {minbreak=>1}, '~', 'split';

would print:

        s-
        p-
        l-
        i-
        t

Alternative breaking subroutines can be specified using the "break" option in a configuration hash. For example:

        form { break => \&my_line_breaker }
             $format_str,
             @data;

form expects any user-defined line-breaking subroutine to take three arguments (the string to be broken, the maximum permissible length of the initial section, and the total width of the field being filled). The hypenate sub must return a list of two strings: the initial (broken) section of the word, and the remainder of the string respectively).

For example:

        sub tilde_break = sub($$$)
        {
                (substr($_[0],0,$_[1]-1).'~', substr($_[0],$_[1]-1));
        }

        form { break => \&tilde_break }
             $format_str,
             @data;

makes '~' the hyphenation character, whilst:

        sub wrap_and_slop = sub($$$)
        {
                my ($text, $reqlen, $fldlen) = @_;
                if ($reqlen==$fldlen) { $text =~ m/\A(\s*\S*)(.*)/s }
                else                  { ("", $text) }
        }

        form { break => \&wrap_and_slop }
             $format_str,
             @data;

wraps excessively long words to the next line and "slops" them over the right margin if necessary.

The Text::Reform package provides three functions to simplify the use of variant hyphenation schemes. The exportable subroutine Text::Reform::break_wrap generates a reference to a subroutine implementing the "wrap-and-slop" algorithm shown in the last example, which could therefore be rewritten:

        use Text::Reform qw( form break_wrap );

        form { break => break_wrap }
             $format_str,
             @data;

The subroutine Text::Reform::break_with takes a single string argument and returns a reference to a sub which hyphenates by cutting off the text at the right margin and appending the string argument. Hence the first of the two examples could be rewritten:

        use Text::Reform qw( form break_with );

        form { break => break_with('~') }
             $format_str,
             @data;

The subroutine Text::Reform::break_at takes a single string argument and returns a reference to a sub which hyphenates by breaking immediately after that string. For example:

        use Text::Reform qw( form break_at );

        form { break => break_at('-') }
               "[[[[[[[[[[[[[[",
               "The Newton-Raphson methodology";

        # returns:
        #
        #       "The Newton-
        #        Raphson
        #        methodology"

Note that this differs from the behaviour of break_with, which would be:

        form { break => break_with('-') }
               "[[[[[[[[[[[[[[",
               "The Newton-Raphson methodology";

        # returns:
        #
        #       "The Newton-R-
        #        aphson metho-
        #        dology"

Hence break_at is generally a better choice.

The subroutine Text::Reform::break_TeX returns a reference to a sub which hyphenates using Jan Pazdziora's TeX::Hyphen module. For example:

        use Text::Reform qw( form break_wrap );

        form { break => break_TeX }
             $format_str,
             @data;

Note that in the previous examples there is no leading '\&' before break_wrap, break_with, or break_TeX, since each is being directly called (and returns a reference to some other suitable subroutine);

The form formatting algorithm

The algorithm form uses is:

        1. If interleaving is specified, split the first string in the
           argument list into individual format lines and add a
           terminating newline (unless one is already present).
           Otherwise, treat the entire string as a single "line" (like
           /s does in regexes)
        2. For each format line...
                2.1. determine the number of fields and shift
                     that many values off the argument list and
                     into the filling list. If insufficient
                     arguments are available, generate as many
                     empty strings as are required.
                2.2. generate a text line by filling each field
                     in the format line with the initial contents
                     of the corresponding arg in the filling list
                     (and remove those initial contents from the arg).
                2.3. replace any <,>, or ^ fields by an equivalent
                     number of spaces. Splice out the corresponding
                     args from the filling list.
                2.4. Repeat from step 2.2 until all args in the
                     filling list are empty.
        3. concatenate the text lines generated in step 2
        4. repeat from step 1 until the argument list is empty

form examples

As an example of the use of form, the following:

        $count = 1;
        $text = "A big long piece of text to be formatted exquisitely";

        print form q
        q{       ||||  <<<<<<<<<<   },
        $count, $text,
        q{       ----------------   },
        q{       ^^^^  ]]]]]]]]]]|  },
        $count+11, $text,
        q{                       =
                 ]]].[[[            },
        "123 123.4\n123.456789";

produces the following output:

                 1    A big long
                ----------------
                 12     piece of|
                      text to be|
                       formatted|
                      exquisite-|
                              ly|
                                =
                123.0
                                =
                123.4
                                =
                123.456

Note that block fields in a multi-line format string, cause the entire multi-line format to be repeated as often as necessary.

Picture strings and replacement values are interleaved in the traditional format format, but care is needed to ensure that the correct number of substitution values are provided. Another example:

        $report = form
                'Name           Rank    Serial Number',
                '====           ====    =============',
                '<<<<<<<<<<<<<  ^^^^    <<<<<<<<<<<<<',
                 $name,         $rank,  $serial_number,
                ''
                'Age    Sex     Description',
                '===    ===     ===========',
                '^^^    ^^^     [[[[[[[[[[[',
                 $age,  $sex,   $description;

How form consumes strings

Unlike format, within form non-block fields do consume the text they format, so the following:

        $text = "a line of text to be formatted over three lines";
        print form "<<<<<<<<<<\n  <<<<<<<<\n    <<<<<<\n",
                    $text,        $text,        $text;

produces:

        a line of
          text to
            be fo-

not:

        a line of
          a line
            a line

To achieve the latter effect, convert the variable arguments to independent literals (by double-quoted interpolation):

        $text = "a line of text to be formatted over three lines";
        print form "<<<<<<<<<<\n  <<<<<<<<\n    <<<<<<\n",
                   "$text",      "$text",      "$text";

Although values passed from variable arguments are progressively consumed within form, the values of the original variables passed to form are not altered. Hence:

        $text = "a line of text to be formatted over three lines";
        print form "<<<<<<<<<<\n  <<<<<<<<\n    <<<<<<\n",
                    $text,        $text,        $text;
        print $text, "\n";

will print:

        a line of
          text to
            be fo-
        a line of text to be formatted over three lines

To cause form to consume the values of the original variables passed to it, pass them as references. Thus:

        $text = "a line of text to be formatted over three lines";
        print form "<<<<<<<<<<\n  <<<<<<<<\n    <<<<<<\n",
                    \$text,       \$text,       \$text;
        print $text, "\n";

will print:

        a line of
          text to
            be fo-
        rmatted over three lines

Note that, for safety, the "non-consuming" behaviour takes precedence, so if a variable is passed to form both by reference and by value, its final value will be unchanged.

Numerical formatting

The ">>>.<<<" and "]]].[[[" field specifiers may be used to format numeric values about a fixed decimal place marker. For example:

        print form '(]]]]].[[)', <<EONUMS;
                   1
                   1.0
                   1.001
                   1.009
                   123.456
                   1234567
                   one two
        EONUMS

would print:

        (    1.0 )
        (    1.0 )
        (    1.00)
        (    1.01)
        (  123.46)
        (#####.##)
        (?????.??)
        (?????.??)

Fractions are rounded to the specified number of places after the decimal, but only significant digits are shown. That's why, in the above example, 1 and 1.0 are formatted as "1.0", whilst 1.001 is formatted as "1.00".

You can specify that the maximal number of decimal places always be used by giving the configuration option 'numeric' a value that matches /\bAllPlaces\b/i. For example:

        print form { numeric => AllPlaces },
                   '(]]]]].[[)', <<'EONUMS';
                   1
                   1.0
        EONUMS

would print:

        (    1.00)
        (    1.00)

Note that although decimal digits are rounded to fit the specified width, the integral part of a number is never modified. If there are not enough places before the decimal place to represent the number, the entire number is replaced with hashes.

If a non-numeric sequence is passed as data for a numeric field, it is formatted as a series of question marks. This querulous behaviour can be changed by giving the configuration option 'numeric' a value that matches /\bSkipNaN\b/i in which case, any invalid numeric data is simply ignored. For example:

        print form { numeric => 'SkipNaN' }
                   '(]]]]].[[)',
                   <<EONUMS;
                   1
                   two three
                   4
        EONUMS

would print:

        (    1.0 )
        (    4.0 )

Filling block fields with lists of values

If an argument corresponding to a field is an array reference, then form automatically joins the elements of the array into a single string, separating each element with a newline character. As a result, a call like this:

        @values = qw( 1 10 100 1000 );
        print form "(]]]].[[)", \@values;

will print out

         (   1.00)
         (  10.00)
         ( 100.00)
         (1000.00)

as might be expected.

Note however that arrays must be passed by reference (so that form knows that the entire array holds data for a single field). If the previous example had not passed @values by reference:

        @values = qw( 1 10 100 1000 );
        print form "(]]]].[[)", @values;

the output would have been:

         (   1.00)
         10
         100
         1000

This is because @values would have been interpolated into form's argument list, so only $value[0] would have been used as the data for the initial format string. The remaining elements of @value would have been treated as separate format strings, and printed out "verbatim".

Note too that, because arrays must be passed using a reference, their original contents are consumed by form, just like the contents of scalars passed by reference.

To avoid having an array consumed by form, pass it as an anonymous array:

        print form "(]]]].[[)", [@values];

Headers, footers, and pages

The form subroutine can also insert headers, footers, and page-feeds as it formats. These features are controlled by the "header", "footer", "pagefeed", "pagelen", and "pagenum" options.

The "pagenum" option takes a scalar value or a reference to a scalar variable and starts page numbering at that value. If a reference to a scalar variable is specified, the value of that variable is updated as the formatting proceeds, so that the final page number is available in it after formatting. This can be useful for multi-part reports.

The "pagelen" option specifies the total number of lines in a page (including headers, footers, and page-feeds).

The "pagewidth" option specifies the total number of columns in a page.

If the "header" option is specified with a string value, that string is used as the header of every page generated. If it is specified as a reference to a subroutine, that subroutine is called at the start of every page and its return value used as the header string. When called, the subroutine is passed the current page number.

Likewise, if the "footer" option is specified with a string value, that string is used as the footer of every page generated. If it is specified as a reference to a subroutine, that subroutine is called at the start of every page and its return value used as the footer string. When called, the footer subroutine is passed the current page number.

Both the header and footer options can also be specified as hash references. In this case the hash entries for keys "left", "centre" (or "center"), and "right" specify what is to appear on the left, centre, and right of the header/footer. The entry for the key "width" specifies how wide the footer is to be. If the "width" key is omitted, the "pagewidth" configuration option (which defaults to 72 characters) is used.

The "left", "centre", and "right" values may be literal strings, or subroutines (just as a normal header/footer specification may be.) See the second example, below.

Another alternative for header and footer options is to specify them as a subroutine that returns a hash reference. The subroutine is called for each page, then the resulting hash is treated like the hashes described in the preceding paragraph. See the third example, below.

The "pagefeed" option acts in exactly the same way, to produce a pagefeed which is appended after the footer. But note that the pagefeed is not counted as part of the page length.

All three of these page components are recomputed at the start of each new page, before the page contents are formatted (recomputing the header and footer first makes it possible to determine how many lines of data to format so as to adhere to the specified page length).

When the call to form is complete and the data has been fully formatted, the footer subroutine is called one last time, with an extra argument of 1. The string returned by this final call is used as the final footer.

So for example, a 60-line per page report, starting at page 7, with appropriate headers and footers might be set up like so:

        $page = 7;

        form { header => sub { "Page $_[0]\n\n" },
               footer => sub { my ($pagenum, $lastpage) = @_;
                               return "" if $lastpage;
                               return "-"x50 . "\n"
                                             .form ">"x50, "...".($pagenum+1);
                              },
               pagefeed => "\n\n",
               pagelen  => 60
               pagenum => \$page,
             },
             $template,
             @data;

Note the recursive use of form within the "footer" option!

Alternatively, to set up headers and footers such that the running head is right justified in the header and the page number is centred in the footer:

        form { header => { right => "Running head" },
               footer => { centre => sub { "Page $_[0]" } },
               pagelen  => 60
             },
             $template,
             @data;

The footer in the previous example could also have been specified the other way around, as a subroutine that returns a hash (rather than a hash containing a subroutine):

        form { header => { right => "Running head" },
               footer => sub { return {centre => "Page $_[0]"} },
               pagelen  => 60
             },
             $template,
             @data;

The cols option

Sometimes data to be used in a form call needs to be extracted from a nested data structure. For example, whilst it's easy to print a table if you already have the data in columns:

        @name  = qw(Tom Dick Harry);
        @score = qw( 88   54    99);
        @time  = qw( 15   13    18);

        print form
        '-------------------------------',
        'Name             Score     Time',
        '-------------------------------',
        '[[[[[[[[[[[[[[   |||||     ||||',
         \@name,          \@score,  \@time;

if the data is aggregrated by rows:

        @data = (
            { name=>'Tom',   score=>88, time=>15 },
            { name=>'Dick',  score=>54, time=>13 },
            { name=>'Harry', score=>99, time=>18 },
        );

you need to do some fancy mapping before it can be fed to form:

        print form
        '-------------------------------',
        'Name             Score     Time',
        '-------------------------------',
        '[[[[[[[[[[[[[[   |||||     ||||',
        [map $$_{name},  @data],
        [map $$_{score}, @data],
        [map $$_{time} , @data];

Or you could just use the 'cols' option:

        use Text::Reform qw(form columns);

        print form
        '-------------------------------',
        'Name             Score     Time',
        '-------------------------------',
        '[[[[[[[[[[[[[[   |||||     ||||',
        { cols => [qw(name score time)],
          from => \@data
        };

This option takes an array of strings that specifies the keys of the hash entries to be extracted into columns. The 'from' entry (which must be present) also takes an array, which is expected to contain a list of references to hashes. For each key specified, this option inserts into form's argument list a reference to an array containing the entries for that key, extracted from each of the hash references supplied by 'from'. So, for example, the option:

        { cols => [qw(name score time)],
          from => \@data
        }

is replaced by three array references, the first containing the 'name' entries for each hash inside @data, the second containing the 'score' entries for each hash inside @data, and the third containing the 'time' entries for each hash inside @data.

If, instead, you have a list of arrays containing the data:

        @data = (
                # Time  Name     Score
                [ 15,   'Tom',   88 ],
                [ 13,   'Dick',  54 ],
                [ 18,   'Harry', 99 ],
        );

the 'cols' option can extract the appropriate columns for that too. You just specify the required indices, rather than keys:

        print form
        '-----------------------------',
        'Name             Score   Time',
        '-----------------------------',
        '[[[[[[[[[[[[[[   |||||   ||||',
        { cols => [1,2,0],
          from => \@data
        }

Note that the indices can be in any order, and the resulting arrays are returned in the same order.

If you need to merge columns extracted from two hierarchical data structures, just concatenate the data structures first, like so:

        print form
        '---------------------------------------',
        'Name             Score   Time   Ranking
        '---------------------------------------',
        '[[[[[[[[[[[[[[   |||||   ||||   |||||||',
        { cols => [1,2,0],
          from => [@data, @olddata],
        }

Of course, this only works if the columns are in the same positions in both data sets (and both datasets are stored in arrays) or if the columns have the same keys (and both datasets are in hashes). If not, you would need to format each dataset separately, like so:

        print form
        '-----------------------------',
        'Name             Score   Time'
        '-----------------------------',
        '[[[[[[[[[[[[[[   |||||   ||||',
        { cols=>[1,2,0],  from=>\@data },
        '[[[[[[[[[[[[[[   |||||   ||||',
        { cols=>[3,8,1],  from=>\@olddata },
        '[[[[[[[[[[[[[[   |||||   ||||',
        { cols=>[qw(name score time)],  from=>\@otherdata };

The tag sub

The tag subroutine may be exported from the module. It takes two arguments: a tag specifier and a text to be entagged. The tag specifier indicates the indenting of the tag, and of the text. The sub generates an end-tag (using the usual "/tag" variant), unless an explicit end-tag is provided as the third argument.

The tag specifier consists of the following components (in order):

An optional vertical spacer (zero or more whitespace-separated newlines)

One or more whitespace characters up to a final mandatory newline. This vertical space is inserted before the tag and after the end-tag

An optional tag indent

Zero or more whitespace characters. Both the tag and the end-tag are indented by this whitespace.

An optional left (opening) tag delimiter

Zero or more non-"word" characters (not alphanumeric or '_'). If the opening delimiter is omitted, the character '<' is used.

A tag

One or more "word" characters (alphanumeric or '_').

Optional tag arguments

Any number of any characters

An optional right (closing) tag delimiter

Zero or more non-"word" characters which balance some sequential portion of the opening tag delimiter. For example, if the opening delimiter is "<-(" then any of the following are acceptible closing delimiters: ")->", "->", or ">". If the closing delimiter is omitted, the "inverse" of the opening delimiter is used (for example, ")->"),

An optional vertical spacer (zero or more newlines)

One or more whitespace characters up to a mandatory newline. This vertical space is inserted before and after the complete text.

An optional text indent

Zero or more space of tab characters. Each line of text is indented by this whitespace (in addition to the tag indent).

For example:

        $text = "three lines\nof tagged\ntext";

        print tag "A HREF=#nextsection", $text;

prints:

        <A HREF=#nextsection>three lines
        of tagged
        text</A>

whereas:

        print tag "[-:GRIN>>>\n", $text;

prints:

        [-:GRIN>>>:-]
        three lines
        of tagged
        text
        [-:/GRIN>>>:-]

and:

        print tag "\n\n   <BOLD>\n\n   ", $text, "<END BOLD>";

prints:

           <BOLD>
              three lines
              of tagged
              text
           <END BOLD>

(with the indicated spacing fore and aft).

AUTHOR

Damian Conway (damian@conway.org)

BUGS

There are undoubtedly serious bugs lurking somewhere in code this funky :-) Bug reports and other feedback are most welcome.

COPYRIGHT

Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)


Text::Soundex - Implementation of the Soundex Algorithm as Described by Knuth

  • EXAMPLES
  • LIMITATIONS
  • AUTHOR

NAME

Text::Soundex - Implementation of the Soundex Algorithm as Described by Knuth

SYNOPSIS

  use Text::Soundex;

  $code = soundex $string;            # get soundex code for a string
  @codes = soundex @list;             # get list of codes for list of strings

  # set value to be returned for strings without soundex code

  $soundex_nocode = 'Z000';

DESCRIPTION

This module implements the soundex algorithm as described by Donald Knuth in Volume 3 of The Art of Computer Programming. The algorithm is intended to hash words (in particular surnames) into a small space using a simple model which approximates the sound of the word when spoken by an English speaker. Each word is reduced to a four character string, the first character being an upper case letter and the remaining three being digits.

If there is no soundex code representation for a string then the value of $soundex_nocode is returned. This is initially set to undef, but many people seem to prefer an unlikely value like Z000 (how unlikely this is depends on the data set being dealt with.) Any value can be assigned to $soundex_nocode.

In scalar context soundex returns the soundex code of its first argument, and in list context a list is returned in which each element is the soundex code for the corresponding argument passed to soundex e.g.

  @codes = soundex qw(Mike Stok);

leaves @codes containing ('M200', 'S320').

EXAMPLES

Knuth's examples of various names and the soundex codes they map to are listed below:

  Euler, Ellery -> E460
  Gauss, Ghosh -> G200
  Hilbert, Heilbronn -> H416
  Knuth, Kant -> K530
  Lloyd, Ladd -> L300
  Lukasiewicz, Lissajous -> L222

so:

  $code = soundex 'Knuth';              # $code contains 'K530'
  @list = soundex qw(Lloyd Gauss);      # @list contains 'L300', 'G200'

LIMITATIONS

As the soundex algorithm was originally used a long time ago in the US it considers only the English alphabet and pronunciation.

As it is mapping a large space (arbitrary length strings) onto a small space (single letter plus 3 digits) no inference can be made about the similarity of two strings which end up with the same soundex code. For example, both Hilbert and Heilbronn end up with a soundex code of H416.

AUTHOR

This code was implemented by Mike Stok (stok@cybercom.net) from the description given by Knuth. Ian Phillipps (ian@pipex.net) and Rich Pinder (rpinder@hsc.usc.edu) supplied ideas and spotted mistakes.


Text::Tabs -- expand and unexpand tabs per the unix expand

  • BUGS
  • LICENSE

NAME

Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)

SYNOPSIS

  use Text::Tabs;

  $tabstop = 4;
  @lines_without_tabs = expand(@lines_with_tabs);
  @lines_with_tabs = unexpand(@lines_without_tabs);

DESCRIPTION

Text::Tabs does about what the unix utilities expand(1) and unexpand(1) do. Given a line with tabs in it, expand will replace the tabs with the appropriate number of spaces. Given a line with or without tabs in it, unexpand will add tabs when it can save bytes by doing so. Invisible compression with plain ascii!

BUGS

expand doesn't handle newlines very quickly -- do not feed it an entire document in one string. Instead feed it an array of lines.

LICENSE

Copyright (C) 1996-2002,2005 David Muir Sharnoff. Copyright (C) 2005 Aristotle Pagaltzis This module may be modified, used, copied, and redistributed at your own risk. Publicly redistributed modified versions must use a different name.


Text::Wrap - line wrapping to form simple paragraphs

  • OVERRIDES
  • EXAMPLE
  • LICENSE

NAME

Text::Wrap - line wrapping to form simple paragraphs

SYNOPSIS

Example 1

        use Text::Wrap
        $initial_tab = "\t";    # Tab before first line
        $subsequent_tab = "";   # All other lines flush left

        print wrap($initial_tab, $subsequent_tab, @text);
        print fill($initial_tab, $subsequent_tab, @text);

        $lines = wrap($initial_tab, $subsequent_tab, @text);

        @paragraphs = fill($initial_tab, $subsequent_tab, @text);

Example 2

        use Text::Wrap qw(wrap $columns $huge);

        $columns = 132;         # Wrap at 132 characters
        $huge = 'die';
        $huge = 'wrap';
        $huge = 'overflow';

Example 3

        use Text::Wrap
        $Text::Wrap::columns = 72;
        print wrap('', '', @text);

DESCRIPTION

Text::Wrap::wrap() is a very simple paragraph formatter. It formats a single paragraph at a time by breaking lines at word boundries. Indentation is controlled for the first line ($initial_tab) and all subsequent lines ($subsequent_tab) independently. Please note: $initial_tab and $subsequent_tab are the literal strings that will be used: it is unlikley you would want to pass in a number.

Text::Wrap::fill() is a simple multi-paragraph formatter. It formats each paragraph separately and then joins them together when it's done. It will destroy any whitespace in the original text. It breaks text into paragraphs by looking for whitespace after a newline. In other respects it acts like wrap().

OVERRIDES

Text::Wrap::wrap() has a number of variables that control its behavior. Because other modules might be using Text::Wrap::wrap() it is suggested that you leave these variables alone! If you can't do that, then use local($Text::Wrap::VARIABLE) = YOURVALUE when you change the values so that the original value is restored. This local() trick will not work if you import the variable into your own namespace.

Lines are wrapped at $Text::Wrap::columns columns. $Text::Wrap::columns should be set to the full width of your output device. In fact, every resulting line will have length of no more than $columns - 1.

It is possible to control which characters terminate words by modifying $Text::Wrap::break. Set this to a string such as '[\s:]' (to break before spaces or colons) or a pre-compiled regexp such as qr/[\s']/ (to break before spaces or apostrophes). The default is simply '\s'; that is, words are terminated by spaces. (This means, among other things, that trailing punctuation such as full stops or commas stay with the word they are "attached" to.)

Beginner note: In example 2, above $columns is imported into the local namespace, and set locally. In example 3, $Text::Wrap::columns is set in its own namespace without importing it.

Text::Wrap::wrap() starts its work by expanding all the tabs in its input into spaces. The last thing it does it to turn spaces back into tabs. If you do not want tabs in your results, set $Text::Wrap::unexpand to a false value. Likewise if you do not want to use 8-character tabstops, set $Text::Wrap::tabstop to the number of characters you do want for your tabstops.

If you want to separate your lines with something other than \n then set $Text::Wrap::separator to your preference. This replaces all newlines with $Text::Wrap::separator. If you just to preserve existing newlines but add new breaks with something else, set $Text::Wrap::separator2 instead.

When words that are longer than $columns are encountered, they are broken up. wrap() adds a "\n" at column $columns. This behavior can be overridden by setting $huge to 'die' or to 'overflow'. When set to 'die', large words will cause die() to be called. When set to 'overflow', large words will be left intact.

Historical notes: 'die' used to be the default value of $huge. Now, 'wrap' is the default value.

EXAMPLE

        print wrap("\t","","This is a bit of text that forms
                a normal book-style paragraph");

LICENSE

David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and many many others. Copyright (C) 1996-2002 David Muir Sharnoff. This module may be modified, used, copied, and redistributed at your own risk. Publicly redistributed modified versions must use a different name.


Thread - manipulate threads in Perl

  • CAVEAT
  • SYNOPSIS
  • DESCRIPTION
  • FUNCTIONS
  • METHODS
  • LIMITATIONS
  • SEE ALSO

NAME

Thread - manipulate threads in Perl (for old code only)

CAVEAT

Perl has two thread models.

In Perl 5.005 the thread model was that all data is implicitly shared and shared access to data has to be explicitly synchronized. This model is called "5005threads".

In Perl 5.6 a new model was introduced in which all is was thread local and shared access to data has to be explicitly declared. This model is called "ithreads", for "interpreter threads".

In Perl 5.6 the ithreads model was not available as a public API, only as an internal API that was available for extension writers, and to implement fork() emulation on Win32 platforms.

In Perl 5.8 the ithreads model became available through the threads module.

Neither model is configured by default into Perl (except, as mentioned above, in Win32 ithreads are always available.) You can see your Perl's threading configuration by running perl -V and looking for the use...threads variables, or inside script by use Config; and testing for $Config{use5005threads} and $Config{useithreads}.

For old code and interim backwards compatibility, the Thread module has been reworked to function as a frontend for both 5005threads and ithreads.

Note that the compatibility is not complete: because the data sharing models are directly opposed, anything to do with data sharing has to be thought differently. With the ithreads you must explicitly share() variables between the threads.

For new code the use of the Thread module is discouraged and the direct use of the threads and threads::shared modules is encouraged instead.

Finally, note that there are many known serious problems with the 5005threads, one of the least of which is that regular expression match variables like $1 are not threadsafe, that is, they easily get corrupted by competing threads. Other problems include more insidious data corruption and mysterious crashes. You are seriously urged to use ithreads instead.

SYNOPSIS

    use Thread;

    my $t = Thread->new(\&start_sub, @start_args);

    $result = $t->join;
    $result = $t->eval;
    $t->detach;

    if ($t->done) {
        $t->join;
    }

    if($t->equal($another_thread)) {
        # ...
    }

    yield();

    my $tid = Thread->self->tid;

    lock($scalar);
    lock(@array);
    lock(%hash);

    lock(\&sub);        # not available with ithreads

    $flags = $t->flags; # not available with ithreads

    my @list = Thread->list;    # not available with ithreads

    use Thread 'async';

DESCRIPTION

The Thread module provides multithreading support for perl.

FUNCTIONS

$thread = Thread->new(\&start_sub)
$thread = Thread->new(\&start_sub, LIST)

new starts a new thread of execution in the referenced subroutine. The optional list is passed as parameters to the subroutine. Execution continues in both the subroutine and the code after the new call.

Thread-&gt;new returns a thread object representing the newly created thread.

lock VARIABLE

lock places a lock on a variable until the lock goes out of scope.

If the variable is locked by another thread, the lock call will block until it's available. lock is recursive, so multiple calls to lock are safe--the variable will remain locked until the outermost lock on the variable goes out of scope.

Locks on variables only affect lock calls--they do not affect normal access to a variable. (Locks on subs are different, and covered in a bit.) If you really, really want locks to block access, then go ahead and tie them to something and manage this yourself. This is done on purpose. While managing access to variables is a good thing, Perl doesn't force you out of its living room...

If a container object, such as a hash or array, is locked, all the elements of that container are not locked. For example, if a thread does a lock @a, any other thread doing a lock($a[12]) won't block.

With 5005threads you may also lock a sub, using lock &sub. Any calls to that sub from another thread will block until the lock is released. This behaviour is not equivalent to declaring the sub with the locked attribute. The locked attribute serializes access to a subroutine, but allows different threads non-simultaneous access. lock &sub, on the other hand, will not allow any other thread access for the duration of the lock.

Finally, lock will traverse up references exactly one level. lock(\$a) is equivalent to lock($a), while lock(\\$a) is not.

async BLOCK;

async creates a thread to execute the block immediately following it. This block is treated as an anonymous sub, and so must have a semi-colon after the closing brace. Like Thread-&gt;new, async returns a thread object.

Thread->self

The Thread->self function returns a thread object that represents the thread making the Thread->self call.

cond_wait VARIABLE

The cond_wait function takes a locked variable as a parameter, unlocks the variable, and blocks until another thread does a cond_signal or cond_broadcast for that same locked variable. The variable that cond_wait blocked on is relocked after the cond_wait is satisfied. If there are multiple threads cond_waiting on the same variable, all but one will reblock waiting to reaquire the lock on the variable. (So if you're only using cond_wait for synchronization, give up the lock as soon as possible.)

cond_signal VARIABLE

The cond_signal function takes a locked variable as a parameter and unblocks one thread that's cond_waiting on that variable. If more than one thread is blocked in a cond_wait on that variable, only one (and which one is indeterminate) will be unblocked.

If there are no threads blocked in a cond_wait on the variable, the signal is discarded.

cond_broadcast VARIABLE

The cond_broadcast function works similarly to cond_signal. cond_broadcast, though, will unblock all the threads that are blocked in a cond_wait on the locked variable, rather than only one.

yield

The yield function allows another thread to take control of the CPU. The exact results are implementation-dependent.

METHODS

join

join waits for a thread to end and returns any values the thread exited with. join will block until the thread has ended, though it won't block if the thread has already terminated.

If the thread being joined died, the error it died with will be returned at this time. If you don't want the thread performing the join to die as well, you should either wrap the join in an eval or use the eval thread method instead of join.

eval

The eval method wraps an eval around a join, and so waits for a thread to exit, passing along any values the thread might have returned. Errors, of course, get placed into $@. (Not available with ithreads.)

detach

detach tells a thread that it is never going to be joined i.e. that all traces of its existence can be removed once it stops running. Errors in detached threads will not be visible anywhere - if you want to catch them, you should use $SIG{__DIE__} or something like that.

equal

equal tests whether two thread objects represent the same thread and returns true if they do.

tid

The tid method returns the tid of a thread. The tid is a monotonically increasing integer assigned when a thread is created. The main thread of a program will have a tid of zero, while subsequent threads will have tids assigned starting with one.

flags

The flags method returns the flags for the thread. This is the integer value corresponding to the internal flags for the thread, and the value may not be all that meaningful to you. (Not available with ithreads.)

done

The done method returns true if the thread you're checking has finished, and false otherwise. (Not available with ithreads.)

LIMITATIONS

The sequence number used to assign tids is a simple integer, and no checking is done to make sure the tid isn't currently in use. If a program creates more than 2**32 - 1 threads in a single run, threads may be assigned duplicate tids. This limitation may be lifted in a future version of Perl.

SEE ALSO

the threads::shared manpage (not available with 5005threads)

the attributes manpage, the Thread::Queue manpage, the Thread::Semaphore manpage, the Thread::Specific manpage (not available with ithreads)


Thread::Queue - thread-safe queues

  • FUNCTIONS AND METHODS
  • SEE ALSO

NAME

Thread::Queue - thread-safe queues

SYNOPSIS

    use Thread::Queue;
    my $q = new Thread::Queue;
    $q->enqueue("foo", "bar");
    my $foo = $q->dequeue;    # The "bar" is still in the queue.
    my $foo = $q->dequeue_nb; # returns "bar", or undef if the queue was empty
    my $left = $q->pending;   # returns the number of items still in the queue

DESCRIPTION

A queue, as implemented by Thread::Queue is a thread-safe data structure much like a list. Any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. (Queues don't permit adding or removing elements from the middle of the list).

FUNCTIONS AND METHODS

new

The new function creates a new empty queue.

enqueue LIST

The enqueue method adds a list of scalars on to the end of the queue. The queue will grow as needed to accommodate the list.

dequeue

The dequeue method removes a scalar from the head of the queue and returns it. If the queue is currently empty, dequeue will block the thread until another thread enqueues a scalar.

dequeue_nb

The dequeue_nb method, like the dequeue method, removes a scalar from the head of the queue and returns it. Unlike dequeue, though, dequeue_nb won't block if the queue is empty, instead returning undef.

pending

The pending method returns the number of items still in the queue.

SEE ALSO

the threads manpage, the threads::shared manpage


Thread::Semaphore - thread-safe semaphores

  • FUNCTIONS AND METHODS

NAME

Thread::Semaphore - thread-safe semaphores

SYNOPSIS

    use Thread::Semaphore;
    my $s = new Thread::Semaphore;
    $s->down;   # Also known as the semaphore P operation.
    # The guarded section is here
    $s->up;     # Also known as the semaphore V operation.

    # The default semaphore value is 1.
    my $s = new Thread::Semaphore($initial_value);
    $s->down($down_value);
    $s->up($up_value);

DESCRIPTION

Semaphores provide a mechanism to regulate access to resources. Semaphores, unlike locks, aren't tied to particular scalars, and so may be used to control access to anything you care to use them for.

Semaphores don't limit their values to zero or one, so they can be used to control access to some resource that there may be more than one of. (For example, filehandles.) Increment and decrement amounts aren't fixed at one either, so threads can reserve or return multiple resources at once.

FUNCTIONS AND METHODS

new
new NUMBER

new creates a new semaphore, and initializes its count to the passed number. If no number is passed, the semaphore's count is set to one.

down
down NUMBER

The down method decreases the semaphore's count by the specified number, or by one if no number has been specified. If the semaphore's count would drop below zero, this method will block until such time that the semaphore's count is equal to or larger than the amount you're downing the semaphore's count by.

This is the semaphore "P operation" (the name derives from the Dutch word "pak", which means "capture" -- the semaphore operations were named by the late Dijkstra, who was Dutch).

up
up NUMBER

The up method increases the semaphore's count by the number specified, or by one if no number has been specified. This will unblock any thread blocked trying to down the semaphore if the up raises the semaphore count above the amount that the downs are trying to decrement it by.

This is the semaphore "V operation" (the name derives from the Dutch word "vrij", which means "release").


Thread::Signal - Start a thread which runs signal handlers reliably

  • CAVEAT
  • SYNOPSIS
  • DESCRIPTION
  • BUGS

NAME

Thread::Signal - Start a thread which runs signal handlers reliably (for old code)

CAVEAT

For new code the use of the Thread::Signal module is discouraged and the direct use of the threads and associated modules is encouraged instead.

However, there is no direct equivalent of the Thread::Signal module in the new implementation of threads. On the bright side: signals are now delivered reliably to Perl programs that do not use threads. The handling of signals with the new threading features is up to the underlying thread implementation that is being used and may therefor be less reliable.

If you want to specify a thread-specific signal, you can alter the %SIG hash in the thread where you want to handle a signal differently from other threads. This at least seems to work under Linux. But there are no guarantees and your mileage may vary.

For the whole story about the development of threads in Perl, and why you should not be using this module unless you know what you're doing, see the CAVEAT of the Thread module.

SYNOPSIS

    use Thread::Signal;

    $SIG{HUP} = \&some_handler;

DESCRIPTION

The Thread::Signal module starts up a special signal handler thread. All signals to the process are delivered to it and it runs the associated $SIG{FOO} handlers for them. Without this module, signals arriving at inopportune moments (such as when perl's internals are in the middle of updating critical structures) cause the perl code of the handler to be run unsafely which can cause memory corruption or worse.

BUGS

This module changes the semantics of signal handling slightly in that the signal handler is run separately from the main thread (and in parallel with it). This means that tricks such as calling die from a signal handler behave differently (and, in particular, can't be used to exit directly from a system call).


Thread::Specific - thread-specific keys

NAME

Thread::Specific - thread-specific keys

SYNOPSIS

    use Thread::Specific;
    my $k = key_create Thread::Specific;

DESCRIPTION

key_create returns a unique thread-specific key.


Tie::Array - base class for tied arrays

  • CAVEATS
  • AUTHOR

NAME

Tie::Array - base class for tied arrays

SYNOPSIS

    package Tie::NewArray;
    use Tie::Array;
    @ISA = ('Tie::Array');

    # mandatory methods
    sub TIEARRAY { ... }
    sub FETCH { ... }
    sub FETCHSIZE { ... }

    sub STORE { ... }        # mandatory if elements writeable
    sub STORESIZE { ... }    # mandatory if elements can be added/deleted
    sub EXISTS { ... }       # mandatory if exists() expected to work
    sub DELETE { ... }       # mandatory if delete() expected to work

    # optional methods - for efficiency
    sub CLEAR { ... }
    sub PUSH { ... }
    sub POP { ... }
    sub SHIFT { ... }
    sub UNSHIFT { ... }
    sub SPLICE { ... }
    sub EXTEND { ... }
    sub DESTROY { ... }

    package Tie::NewStdArray;
    use Tie::Array;

    @ISA = ('Tie::StdArray');

    # all methods provided by default

    package main;

    $object = tie @somearray,Tie::NewArray;
    $object = tie @somearray,Tie::StdArray;
    $object = tie @somearray,Tie::NewStdArray;

DESCRIPTION

This module provides methods for array-tying classes. See the perltie manpage for a list of the functions required in order to tie an array to a package. The basic Tie::Array package provides stub DESTROY, and EXTEND methods that do nothing, stub DELETE and EXISTS methods that croak() if the delete() or exists() builtins are ever called on the tied array, and implementations of PUSH, POP, SHIFT, UNSHIFT, SPLICE and CLEAR in terms of basic FETCH, STORE, FETCHSIZE, STORESIZE.

The Tie::StdArray package provides efficient methods required for tied arrays which are implemented as blessed references to an "inner" perl array. It inherits from Tie::Array, and should cause tied arrays to behave exactly like standard arrays, allowing for selective overloading of methods.

For developers wishing to write their own tied arrays, the required methods are briefly defined below. See the the perltie manpage section for more detailed descriptive, as well as example code:

TIEARRAY classname, LIST

The class method is invoked by the command tie @array, classname. Associates an array instance with the specified class. LIST would represent additional arguments (along the lines of the AnyDBM_File manpage and compatriots) needed to complete the association. The method should return an object of a class which provides the methods below.

STORE this, index, value

Store datum value into index for the tied array associated with object this. If this makes the array larger then class's mapping of undef should be returned for new positions.

FETCH this, index

Retrieve the datum in index for the tied array associated with object this.

FETCHSIZE this

Returns the total number of items in the tied array associated with object this. (Equivalent to scalar(@array)).

STORESIZE this, count

Sets the total number of items in the tied array associated with object this to be count. If this makes the array larger then class's mapping of undef should be returned for new positions. If the array becomes smaller then entries beyond count should be deleted.

EXTEND this, count

Informative call that array is likely to grow to have count entries. Can be used to optimize allocation. This method need do nothing.

EXISTS this, key

Verify that the element at index key exists in the tied array this.

The Tie::Array implementation is a stub that simply croaks.

DELETE this, key

Delete the element at index key from the tied array this.

The Tie::Array implementation is a stub that simply croaks.

CLEAR this

Clear (remove, delete, ...) all values from the tied array associated with object this.

DESTROY this

Normal object destructor method.

PUSH this, LIST

Append elements of LIST to the array.

POP this

Remove last element of the array and return it.

SHIFT this

Remove the first element of the array (shifting other elements down) and return it.

UNSHIFT this, LIST

Insert LIST elements at the beginning of the array, moving existing elements up to make room.

SPLICE this, offset, length, LIST

Perform the equivalent of splice on the array.

offset is optional and defaults to zero, negative values count back from the end of the array.

length is optional and defaults to rest of the array.

LIST may be empty.

Returns a list of the original length elements at offset.

CAVEATS

There is no support at present for tied @ISA. There is a potential conflict between magic entries needed to notice setting of @ISA, and those needed to implement 'tie'.

Very little consideration has been given to the behaviour of tied arrays when $[ is not default value of zero.

AUTHOR

Nick Ing-Simmons <nik@tiuk.ti.com>


Tie::File - Access the lines of a disk file via a Perl array

    • recsep
    • autochomp
    • mode
    • memory
    • dw_size
    • Option Format
  • Public Methods
    • flock
    • autochomp
    • defer, flush, discard, and autodefer
    • offset
  • Tying to an already-opened filehandle
  • Deferred Writing
    • Autodeferring
  • CONCURRENT ACCESS TO FILES
  • CAVEATS
  • SUBCLASSING
  • WHAT ABOUT DB_File?
  • AUTHOR
  • LICENSE
  • WARRANTY
  • THANKS
  • TODO

NAME

Tie::File - Access the lines of a disk file via a Perl array

SYNOPSIS

        # This file documents Tie::File version 0.97
        use Tie::File;

        tie @array, 'Tie::File', filename or die ...;

        $array[13] = 'blah';     # line 13 of the file is now 'blah'
        print $array[42];        # display line 42 of the file

        $n_recs = @array;        # how many records are in the file?
        $#array -= 2;            # chop two records off the end

        for (@array) {
          s/PERL/Perl/g;         # Replace PERL with Perl everywhere in the file
        }

        # These are just like regular push, pop, unshift, shift, and splice
        # Except that they modify the file in the way you would expect

        push @array, new recs...;
        my $r1 = pop @array;
        unshift @array, new recs...;
        my $r2 = shift @array;
        @old_recs = splice @array, 3, 7, new recs...;

        untie @array;            # all finished

DESCRIPTION

Tie::File represents a regular text file as a Perl array. Each element in the array corresponds to a record in the file. The first line of the file is element 0 of the array; the second line is element 1, and so on.

The file is not loaded into memory, so this will work even for gigantic files.

Changes to the array are reflected in the file immediately.

Lazy people and beginners may now stop reading the manual.

recsep

What is a 'record'? By default, the meaning is the same as for the <...> operator: It's a string terminated by $/, which is probably "\n". (Minor exception: on DOS and Win32 systems, a 'record' is a string terminated by "\r\n".) You may change the definition of "record" by supplying the recsep option in the tie call:

        tie @array, 'Tie::File', $file, recsep => 'es';

This says that records are delimited by the string es. If the file contained the following data:

        Curse these pesky flies!\n

then the @array would appear to have four elements:

        "Curse th"
        "e p"
        "ky fli"
        "!\n"

An undefined value is not permitted as a record separator. Perl's special "paragraph mode" semantics (à la $/ = "") are not emulated.

Records read from the tied array do not have the record separator string on the end; this is to allow

        $array[17] .= "extra";

to work as expected.

(See autochomp, below.) Records stored into the array will have the record separator string appended before they are written to the file, if they don't have one already. For example, if the record separator string is "\n", then the following two lines do exactly the same thing:

        $array[17] = "Cherry pie";
        $array[17] = "Cherry pie\n";

The result is that the contents of line 17 of the file will be replaced with "Cherry pie"; a newline character will separate line 17 from line 18. This means that this code will do nothing:

        chomp $array[17];

Because the chomped value will have the separator reattached when it is written back to the file. There is no way to create a file whose trailing record separator string is missing.

Inserting records that contain the record separator string is not supported by this module. It will probably produce a reasonable result, but what this result will be may change in a future version. Use 'splice' to insert records or to replace one record with several.

autochomp

Normally, array elements have the record separator removed, so that if the file contains the text

        Gold
        Frankincense
        Myrrh

the tied array will appear to contain ("Gold", "Frankincense", "Myrrh"). If you set autochomp to a false value, the record separator will not be removed. If the file above was tied with

        tie @gifts, "Tie::File", $gifts, autochomp => 0;

then the array @gifts would appear to contain ("Gold\n", "Frankincense\n", "Myrrh\n"), or (on Win32 systems) ("Gold\r\n", "Frankincense\r\n", "Myrrh\r\n").

mode

Normally, the specified file will be opened for read and write access, and will be created if it does not exist. (That is, the flags O_RDWR | O_CREAT are supplied in the open call.) If you want to change this, you may supply alternative flags in the mode option. See the Fcntl manpage for a listing of available flags. For example:

        # open the file if it exists, but fail if it does not exist
        use Fcntl 'O_RDWR';
        tie @array, 'Tie::File', $file, mode => O_RDWR;

        # create the file if it does not exist
        use Fcntl 'O_RDWR', 'O_CREAT';
        tie @array, 'Tie::File', $file, mode => O_RDWR | O_CREAT;

        # open an existing file in read-only mode
        use Fcntl 'O_RDONLY';
        tie @array, 'Tie::File', $file, mode => O_RDONLY;

Opening the data file in write-only or append mode is not supported.

memory

This is an upper limit on the amount of memory that Tie::File will consume at any time while managing the file. This is used for two things: managing the read cache and managing the deferred write buffer.

Records read in from the file are cached, to avoid having to re-read them repeatedly. If you read the same record twice, the first time it will be stored in memory, and the second time it will be fetched from the read cache. The amount of data in the read cache will not exceed the value you specified for memory. If Tie::File wants to cache a new record, but the read cache is full, it will make room by expiring the least-recently visited records from the read cache.

The default memory limit is 2Mib. You can adjust the maximum read cache size by supplying the memory option. The argument is the desired cache size, in bytes.

        # I have a lot of memory, so use a large cache to speed up access
        tie @array, 'Tie::File', $file, memory => 20_000_000;

Setting the memory limit to 0 will inhibit caching; records will be fetched from disk every time you examine them.

The memory value is not an absolute or exact limit on the memory used. Tie::File objects contains some structures besides the read cache and the deferred write buffer, whose sizes are not charged against memory.

The cache itself consumes about 310 bytes per cached record, so if your file has many short records, you may want to decrease the cache memory limit, or else the cache overhead may exceed the size of the cached data.

dw_size

(This is an advanced feature. Skip this section on first reading.)

If you use deferred writing (See Deferred Writing, below) then data you write into the array will not be written directly to the file; instead, it will be saved in the deferred write buffer to be written out later. Data in the deferred write buffer is also charged against the memory limit you set with the memory option.

You may set the dw_size option to limit the amount of data that can be saved in the deferred write buffer. This limit may not exceed the total memory limit. For example, if you set dw_size to 1000 and memory to 2500, that means that no more than 1000 bytes of deferred writes will be saved up. The space available for the read cache will vary, but it will always be at least 1500 bytes (if the deferred write buffer is full) and it could grow as large as 2500 bytes (if the deferred write buffer is empty.)

If you don't specify a dw_size, it defaults to the entire memory limit.

Option Format

-mode is a synonym for mode. -recsep is a synonym for recsep. -memory is a synonym for memory. You get the idea.

Public Methods

The tie call returns an object, say $o. You may call

        $rec = $o->FETCH($n);
        $o->STORE($n, $rec);

to fetch or store the record at line $n, respectively; similarly the other tied array methods. (See the perltie manpage for details.) You may also call the following methods on this object:

flock

        $o->flock(MODE)

will lock the tied file. MODE has the same meaning as the second argument to the Perl built-in flock function; for example LOCK_SH or LOCK_EX | LOCK_NB. (These constants are provided by the use Fcntl ':flock' declaration.)

MODE is optional; the default is LOCK_EX.

Tie::File maintains an internal table of the byte offset of each record it has seen in the file.

When you use flock to lock the file, Tie::File assumes that the read cache is no longer trustworthy, because another process might have modified the file since the last time it was read. Therefore, a successful call to flock discards the contents of the read cache and the internal record offset table.

Tie::File promises that the following sequence of operations will be safe:

        my $o = tie @array, "Tie::File", $filename;
        $o->flock;

In particular, Tie::File will not read or write the file during the tie call. (Exception: Using mode => O_TRUNC will, of course, erase the file during the tie call. If you want to do this safely, then open the file without O_TRUNC, lock the file, and use @array = ().)

The best way to unlock a file is to discard the object and untie the array. It is probably unsafe to unlock the file without also untying it, because if you do, changes may remain unwritten inside the object. That is why there is no shortcut for unlocking. If you really want to unlock the file prematurely, you know what to do; if you don't know what to do, then don't do it.

All the usual warnings about file locking apply here. In particular, note that file locking in Perl is advisory, which means that holding a lock will not prevent anyone else from reading, writing, or erasing the file; it only prevents them from getting another lock at the same time. Locks are analogous to green traffic lights: If you have a green light, that does not prevent the idiot coming the other way from plowing into you sideways; it merely guarantees to you that the idiot does not also have a green light at the same time.

autochomp

        my $old_value = $o->autochomp(0);    # disable autochomp option
        my $old_value = $o->autochomp(1);    #  enable autochomp option

        my $ac = $o->autochomp();   # recover current value

See autochomp, above.

defer, flush, discard, and autodefer

See Deferred Writing, below.

offset

        $off = $o->offset($n);

This method returns the byte offset of the start of the $nth record in the file. If there is no such record, it returns an undefined value.

Tying to an already-opened filehandle

If $fh is a filehandle, such as is returned by IO::File or one of the other IO modules, you may use:

        tie @array, 'Tie::File', $fh, ...;

Similarly if you opened that handle FH with regular open or sysopen, you may use:

        tie @array, 'Tie::File', \*FH, ...;

Handles that were opened write-only won't work. Handles that were opened read-only will work as long as you don't try to modify the array. Handles must be attached to seekable sources of data---that means no pipes or sockets. If Tie::File can detect that you supplied a non-seekable handle, the tie call will throw an exception. (On Unix systems, it can detect this.)

Note that Tie::File will only close any filehandles that it opened internally. If you passed it a filehandle as above, you "own" the filehandle, and are responsible for closing it after you have untied the @array.

Deferred Writing

(This is an advanced feature. Skip this section on first reading.)

Normally, modifying a Tie::File array writes to the underlying file immediately. Every assignment like $a[3] = ... rewrites as much of the file as is necessary; typically, everything from line 3 through the end will need to be rewritten. This is the simplest and most transparent behavior. Performance even for large files is reasonably good.

However, under some circumstances, this behavior may be excessively slow. For example, suppose you have a million-record file, and you want to do:

        for (@FILE) {
          $_ = "> $_";
        }

The first time through the loop, you will rewrite the entire file, from line 0 through the end. The second time through the loop, you will rewrite the entire file from line 1 through the end. The third time through the loop, you will rewrite the entire file from line 2 to the end. And so on.

If the performance in such cases is unacceptable, you may defer the actual writing, and then have it done all at once. The following loop will perform much better for large files:

        (tied @a)->defer;
        for (@a) {
          $_ = "> $_";
        }
        (tied @a)->flush;

If Tie::File's memory limit is large enough, all the writing will done in memory. Then, when you call ->flush, the entire file will be rewritten in a single pass.

(Actually, the preceding discussion is something of a fib. You don't need to enable deferred writing to get good performance for this common case, because Tie::File will do it for you automatically unless you specifically tell it not to. See autodeferring, below.)

Calling ->flush returns the array to immediate-write mode. If you wish to discard the deferred writes, you may call ->discard instead of ->flush. Note that in some cases, some of the data will have been written already, and it will be too late for ->discard to discard all the changes. Support for ->discard may be withdrawn in a future version of Tie::File.

Deferred writes are cached in memory up to the limit specified by the dw_size option (see above). If the deferred-write buffer is full and you try to write still more deferred data, the buffer will be flushed. All buffered data will be written immediately, the buffer will be emptied, and the now-empty space will be used for future deferred writes.

If the deferred-write buffer isn't yet full, but the total size of the buffer and the read cache would exceed the memory limit, the oldest records will be expired from the read cache until the total size is under the limit.

push, pop, shift, unshift, and splice cannot be deferred. When you perform one of these operations, any deferred data is written to the file and the operation is performed immediately. This may change in a future version.

If you resize the array with deferred writing enabled, the file will be resized immediately, but deferred records will not be written. This has a surprising consequence: @a = (...) erases the file immediately, but the writing of the actual data is deferred. This might be a bug. If it is a bug, it will be fixed in a future version.

Autodeferring

Tie::File tries to guess when deferred writing might be helpful, and to turn it on and off automatically.

        for (@a) {
          $_ = "> $_";
        }

In this example, only the first two assignments will be done immediately; after this, all the changes to the file will be deferred up to the user-specified memory limit.

You should usually be able to ignore this and just use the module without thinking about deferring. However, special applications may require fine control over which writes are deferred, or may require that all writes be immediate. To disable the autodeferment feature, use

        (tied @o)->autodefer(0);

or

        tie @array, 'Tie::File', $file, autodefer => 0;

Similarly, ->autodefer(1) re-enables autodeferment, and ->autodefer() recovers the current value of the autodefer setting.

CONCURRENT ACCESS TO FILES

Caching and deferred writing are inappropriate if you want the same file to be accessed simultaneously from more than one process. Other optimizations performed internally by this module are also incompatible with concurrent access. A future version of this module will support a concurrent => 1 option that enables safe concurrent access.

Previous versions of this documentation suggested using memory =E<gt> 0 for safe concurrent access. This was mistaken. Tie::File will not support safe concurrent access before version 0.98.

CAVEATS

(That's Latin for 'warnings'.)

  • Reasonable effort was made to make this module efficient. Nevertheless, changing the size of a record in the middle of a large file will always be fairly slow, because everything after the new record must be moved.

  • The behavior of tied arrays is not precisely the same as for regular arrays. For example:

            # This DOES print "How unusual!"
        undef $a[10];  print "How unusual!\n" if defined $a[10];

    undef-ing a Tie::File array element just blanks out the corresponding record in the file. When you read it back again, you'll get the empty string, so the supposedly-undef'ed value will be defined. Similarly, if you have autochomp disabled, then

            # This DOES print "How unusual!" if 'autochomp' is disabled
        undef $a[10];
        print "How unusual!\n" if $a[10];

    Because when autochomp is disabled, $a[10] will read back as "\n" (or whatever the record separator string is.)

    There are other minor differences, particularly regarding exists and delete, but in general, the correspondence is extremely close.

  • I have supposed that since this module is concerned with file I/O, almost all normal use of it will be heavily I/O bound. This means that the time to maintain complicated data structures inside the module will be dominated by the time to actually perform the I/O. When there was an opportunity to spend CPU time to avoid doing I/O, I usually tried to take it.

  • You might be tempted to think that deferred writing is like transactions, with flush as commit and discard as rollback, but it isn't, so don't.

  • There is a large memory overhead for each record offset and for each cache entry: about 310 bytes per cached data record, and about 21 bytes per offset table entry.

    The per-record overhead will limit the maximum number of records you can access per file. Note that accessing the length of the array via $x = scalar @tied_file accesses all records and stores their offsets. The same for foreach (@tied_file), even if you exit the loop early.

SUBCLASSING

This version promises absolutely nothing about the internals, which may change without notice. A future version of the module will have a well-defined and stable subclassing API.

WHAT ABOUT DB_File?

People sometimes point out that DB_File will do something similar, and ask why Tie::File module is necessary.

There are a number of reasons that you might prefer Tie::File. A list is available at http://perl.plover.com/TieFile/why-not-DB_File.

AUTHOR

Mark Jason Dominus

To contact the author, send email to: mjd-perl-tiefile+@plover.com

To receive an announcement whenever a new version of this module is released, send a blank email message to mjd-perl-tiefile-subscribe@plover.com.

The most recent version of this module, including documentation and any news of importance, will be available at

        http://perl.plover.com/TieFile/

LICENSE

Tie::File version 0.97 is copyright (C) 2003 Mark Jason Dominus.

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

These terms are your choice of any of (1) the Perl Artistic Licence, or (2) version 2 of the GNU General Public License as published by the Free Software Foundation, or (3) any later version of the GNU General Public License.

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

You should have received a copy of the GNU General Public License along with this library program; it should be in the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA

For licensing inquiries, contact the author at:

        Mark Jason Dominus
        255 S. Warnock St.
        Philadelphia, PA 19107

WARRANTY

Tie::File version 0.97 comes with ABSOLUTELY NO WARRANTY. For details, see the license.

THANKS

Gigantic thanks to Jarkko Hietaniemi, for agreeing to put this in the core when I hadn't written it yet, and for generally being helpful, supportive, and competent. (Usually the rule is "choose any one.") Also big thanks to Abhijit Menon-Sen for all of the same things.

Special thanks to Craig Berry and Peter Prymmer (for VMS portability help), Randy Kobes (for Win32 portability help), Clinton Pierce and Autrijus Tang (for heroic eleventh-hour Win32 testing above and beyond the call of duty), Michael G Schwern (for testing advice), and the rest of the CPAN testers (for testing generally).

Special thanks to Tels for suggesting several speed and memory optimizations.

Additional thanks to: Edward Avis / Mattia Barbon / Tom Christiansen / Gerrit Haase / Gurusamy Sarathy / Jarkko Hietaniemi (again) / Nikola Knezevic / John Kominetz / Nick Ing-Simmons / Tassilo von Parseval / H. Dieter Pearcey / Slaven Rezic / Eric Roode / Peter Scott / Peter Somu / Autrijus Tang (again) / Tels (again) / Juerd Waalboer

TODO

More tests. (Stuff I didn't think of yet.)

Paragraph mode?

Fixed-length mode. Leave-blanks mode.

Maybe an autolocking mode?

For many common uses of the module, the read cache is a liability. For example, a program that inserts a single record, or that scans the file once, will have a cache hit rate of zero. This suggests a major optimization: The cache should be initially disabled. Here's a hybrid approach: Initially, the cache is disabled, but the cache code maintains statistics about how high the hit rate would be *if* it were enabled. When it sees the hit rate get high enough, it enables itself. The STAT comments in this code are the beginning of an implementation of this.

Record locking with fcntl()? Then the module might support an undo log and get real transactions. What a tour de force that would be.

Keeping track of the highest cached record. This would allow reads-in-a-row to skip the cache lookup faster (if reading from 1..N with empty cache at start, the last cached value will be always N-1).

More tests.


Tie::StdHandle - base class definitions for tied handles

  • MORE INFORMATION
  • COMPATIBILITY

NAME

Tie::Handle, Tie::StdHandle - base class definitions for tied handles

SYNOPSIS

    package NewHandle;
    require Tie::Handle;

    @ISA = qw(Tie::Handle);

    sub READ { ... }            # Provide a needed method
    sub TIEHANDLE { ... }       # Overrides inherited method

    package main;

    tie *FH, 'NewHandle';

DESCRIPTION

This module provides some skeletal methods for handle-tying classes. See the perltie manpage for a list of the functions required in tying a handle to a package. The basic Tie::Handle package provides a new method, as well as methods TIEHANDLE, PRINT, PRINTF and GETC.

For developers wishing to write their own tied-handle classes, the methods are summarized below. The the perltie manpage section not only documents these, but has sample code as well:

TIEHANDLE classname, LIST

The method invoked by the command tie *glob, classname. Associates a new glob instance with the specified class. LIST would represent additional arguments (along the lines of the AnyDBM_File manpage and compatriots) needed to complete the association.

WRITE this, scalar, length, offset

Write length bytes of data from scalar starting at offset.

PRINT this, LIST

Print the values in LIST

PRINTF this, format, LIST

Print the values in LIST using format

READ this, scalar, length, offset

Read length bytes of data into scalar starting at offset.

READLINE this

Read a single line

GETC this

Get a single character

CLOSE this

Close the handle

OPEN this, filename

(Re-)open the handle

BINMODE this

Specify content is binary

EOF this

Test for end of file.

TELL this

Return position in the file.

SEEK this, offset, whence

Position the file.

Test for end of file.

DESTROY this

Free the storage associated with the tied handle referenced by this. This is rarely needed, as Perl manages its memory quite well. But the option exists, should a class wish to perform specific actions upon the destruction of an instance.

MORE INFORMATION

The the perltie manpage section contains an example of tying handles.

COMPATIBILITY

This version of Tie::Handle is neither related to nor compatible with the Tie::Handle (3.0) module available on CPAN. It was due to an accident that two modules with the same name appeared. The namespace clash has been cleared in favor of this module that comes with the perl core in September 2000 and accordingly the version number has been bumped up to 4.0.


Tie::ExtraHash - base class definitions for tied hashes

  • Inheriting from Tie::StdHash
  • Inheriting from Tie::ExtraHash
  • SCALAR, UNTIE and DESTROY
  • MORE INFORMATION

NAME

Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for tied hashes

SYNOPSIS

    package NewHash;
    require Tie::Hash;

    @ISA = (Tie::Hash);

    sub DELETE { ... }          # Provides needed method
    sub CLEAR { ... }           # Overrides inherited method

    package NewStdHash;
    require Tie::Hash;

    @ISA = (Tie::StdHash);

    # All methods provided by default, define only those needing overrides
    # Accessors access the storage in %{$_[0]};
    # TIEHASH should return a reference to the actual storage
    sub DELETE { ... }

    package NewExtraHash;
    require Tie::Hash;

    @ISA = (Tie::ExtraHash);

    # All methods provided by default, define only those needing overrides
    # Accessors access the storage in %{$_[0][0]};
    # TIEHASH should return an array reference with the first element being
    # the reference to the actual storage
    sub DELETE {
      $_[0][1]->('del', $_[0][0], $_[1]); # Call the report writer
      delete $_[0][0]->{$_[1]};           #  $_[0]->SUPER::DELETE($_[1])
    }

    package main;

    tie %new_hash, 'NewHash';
    tie %new_std_hash, 'NewStdHash';
    tie %new_extra_hash, 'NewExtraHash',
        sub {warn "Doing \U$_[1]\E of $_[2].\n"};

DESCRIPTION

This module provides some skeletal methods for hash-tying classes. See the perltie manpage for a list of the functions required in order to tie a hash to a package. The basic Tie::Hash package provides a new method, as well as methods TIEHASH, EXISTS and CLEAR. The Tie::StdHash and Tie::ExtraHash packages provide most methods for hashes described in the perltie manpage (the exceptions are UNTIE and DESTROY). They cause tied hashes to behave exactly like standard hashes, and allow for selective overwriting of methods. Tie::Hash grandfathers the new method: it is used if TIEHASH is not defined in the case a class forgets to include a TIEHASH method.

For developers wishing to write their own tied hashes, the required methods are briefly defined below. See the the perltie manpage section for more detailed descriptive, as well as example code:

TIEHASH classname, LIST

The method invoked by the command tie %hash, classname. Associates a new hash instance with the specified class. LIST would represent additional arguments (along the lines of the AnyDBM_File manpage and compatriots) needed to complete the association.

STORE this, key, value

Store datum value into key for the tied hash this.

FETCH this, key

Retrieve the datum in key for the tied hash this.

FIRSTKEY this

Return the first key in the hash.

NEXTKEY this, lastkey

Return the next key in the hash.

EXISTS this, key

Verify that key exists with the tied hash this.

The Tie::Hash implementation is a stub that simply croaks.

DELETE this, key

Delete the key key from the tied hash this.

CLEAR this

Clear all values from the tied hash this.

SCALAR this

Returns what evaluating the hash in scalar context yields.

Tie::Hash does not implement this method (but Tie::StdHash and Tie::ExtraHash do).

Inheriting from Tie::StdHash

The accessor methods assume that the actual storage for the data in the tied hash is in the hash referenced by tied(%tiedhash). Thus overwritten TIEHASH method should return a hash reference, and the remaining methods should operate on the hash referenced by the first argument:

  package ReportHash;
  our @ISA = 'Tie::StdHash';

  sub TIEHASH  {
    my $storage = bless {}, shift;
    warn "New ReportHash created, stored in $storage.\n";
    $storage
  }
  sub STORE    {
    warn "Storing data with key $_[1] at $_[0].\n";
    $_[0]{$_[1]} = $_[2]
  }

Inheriting from Tie::ExtraHash

The accessor methods assume that the actual storage for the data in the tied hash is in the hash referenced by (tied(%tiedhash))->[0]. Thus overwritten TIEHASH method should return an array reference with the first element being a hash reference, and the remaining methods should operate on the hash %{ $_[0]->[0] }:

  package ReportHash;
  our @ISA = 'Tie::ExtraHash';

  sub TIEHASH  {
    my $class = shift;
    my $storage = bless [{}, @_], $class;
    warn "New ReportHash created, stored in $storage.\n";
    $storage;
  }
  sub STORE    {
    warn "Storing data with key $_[1] at $_[0].\n";
    $_[0][0]{$_[1]} = $_[2]
  }

The default TIEHASH method stores "extra" arguments to tie() starting from offset 1 in the array referenced by tied(%tiedhash); this is the same storage algorithm as in TIEHASH subroutine above. Hence, a typical package inheriting from Tie::ExtraHash does not need to overwrite this method.

SCALAR, UNTIE and DESTROY

The methods UNTIE and DESTROY are not defined in Tie::Hash, Tie::StdHash, or Tie::ExtraHash. Tied hashes do not require presence of these methods, but if defined, the methods will be called in proper time, see the perltie manpage.

SCALAR is only defined in Tie::StdHash and Tie::ExtraHash.

If needed, these methods should be defined by the package inheriting from Tie::Hash, Tie::StdHash, or Tie::ExtraHash. See pertie/"SCALAR" to find out what happens when SCALAR does not exist.

MORE INFORMATION

The packages relating to various DBM-related implementations (DB_File, NDBM_File, etc.) show examples of general tied hashes, as does the the Config manpage module. While these do not utilize Tie::Hash, they serve as good working examples.


Tie::Memoize - add data to hash when needed

  • Inheriting from Tie::Memoize
  • EXAMPLE
  • BUGS
  • AUTHOR

NAME

Tie::Memoize - add data to hash when needed

SYNOPSIS

  require Tie::Memoize;
  tie %hash, 'Tie::Memoize',
      \&fetch,                  # The rest is optional
      $DATA, \&exists,
      {%ini_value}, {%ini_existence};

DESCRIPTION

This package allows a tied hash to autoload its values on the first access, and to use the cached value on the following accesses.

Only read-accesses (via fetching the value or exists) result in calls to the functions; the modify-accesses are performed as on a normal hash.

The required arguments during tie are the hash, the package, and the reference to the FETCHing function. The optional arguments are an arbitrary scalar $data, the reference to the EXISTS function, and initial values of the hash and of the existence cache.

Both the FETCHing function and the EXISTS functions have the same signature: the arguments are $key, $data; $data is the same value as given as argument during tie()ing. Both functions should return an empty list if the value does not exist. If EXISTS function is different from the FETCHing function, it should return a TRUE value on success. The FETCHing function should return the intended value if the key is valid.

Inheriting from Tie::Memoize

The structure of the tied() data is an array reference with elements

  0:  cache of known values
  1:  cache of known existence of keys
  2:  FETCH  function
  3:  EXISTS function
  4:  $data

The rest is for internal usage of this package. In particular, if TIEHASH is overwritten, it should call SUPER::TIEHASH.

EXAMPLE

  sub slurp {
    my ($key, $dir) = shift;
    open my $h, '<', "$dir/$key" or return;
    local $/; <$h>                      # slurp it all
  }
  sub exists { my ($key, $dir) = shift; return -f "$dir/$key" }

  tie %hash, 'Tie::Memoize', \&slurp, $directory, \&exists,
      { fake_file1 => $content1, fake_file2 => $content2 },
      { pretend_does_not_exists => 0, known_to_exist => 1 };

This example treats the slightly modified contents of $directory as a hash. The modifications are that the keys fake_file1 and fake_file2 fetch values $content1 and $content2, and pretend_does_not_exists will never be accessed. Additionally, the existence of known_to_exist is never checked (so if it does not exists when its content is needed, the user of %hash may be confused).

BUGS

FIRSTKEY and NEXTKEY methods go through the keys which were already read, not all the possible keys of the hash.

AUTHOR

Ilya Zakharevich mailto:perl-module-hash-memoize@ilyaz.org.


Tie::RefHash - use references as hash keys

  • EXAMPLE
  • AUTHOR
  • VERSION
  • SEE ALSO

NAME

Tie::RefHash - use references as hash keys

SYNOPSIS

    require 5.004;
    use Tie::RefHash;
    tie HASHVARIABLE, 'Tie::RefHash', LIST;
    tie HASHVARIABLE, 'Tie::RefHash::Nestable', LIST;

    untie HASHVARIABLE;

DESCRIPTION

This module provides the ability to use references as hash keys if you first tie the hash variable to this module. Normally, only the keys of the tied hash itself are preserved as references; to use references as keys in hashes-of-hashes, use Tie::RefHash::Nestable, included as part of Tie::RefHash.

It is implemented using the standard perl TIEHASH interface. Please see the tie entry in perlfunc(1) and perltie(1) for more information.

The Nestable version works by looking for hash references being stored and converting them to tied hashes so that they too can have references as keys. This will happen without warning whenever you store a reference to one of your own hashes in the tied hash.

EXAMPLE

    use Tie::RefHash;
    tie %h, 'Tie::RefHash';
    $a = [];
    $b = {};
    $c = \*main;
    $d = \"gunk";
    $e = sub { 'foo' };
    %h = ($a => 1, $b => 2, $c => 3, $d => 4, $e => 5);
    $a->[0] = 'foo';
    $b->{foo} = 'bar';
    for (keys %h) {
       print ref($_), "\n";
    }

    tie %h, 'Tie::RefHash::Nestable';
    $h{$a}->{$b} = 1;
    for (keys %h, keys %{$h{$a}}) {
       print ref($_), "\n";
    }

AUTHOR

Gurusamy Sarathy gsar@activestate.com

'Nestable' by Ed Avis ed@membled.com

VERSION

Version 1.32

SEE ALSO

perl(1), perlfunc(1), perltie(1)


Tie::StdScalar - base class definitions for tied scalars

  • MORE INFORMATION

NAME

Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars

SYNOPSIS

    package NewScalar;
    require Tie::Scalar;

    @ISA = (Tie::Scalar);

    sub FETCH { ... }           # Provide a needed method
    sub TIESCALAR { ... }       # Overrides inherited method

    package NewStdScalar;
    require Tie::Scalar;

    @ISA = (Tie::StdScalar);

    # All methods provided by default, so define only what needs be overridden
    sub FETCH { ... }

    package main;

    tie $new_scalar, 'NewScalar';
    tie $new_std_scalar, 'NewStdScalar';

DESCRIPTION

This module provides some skeletal methods for scalar-tying classes. See the perltie manpage for a list of the functions required in tying a scalar to a package. The basic Tie::Scalar package provides a new method, as well as methods TIESCALAR, FETCH and STORE. The Tie::StdScalar package provides all the methods specified in the perltie manpage. It inherits from Tie::Scalar and causes scalars tied to it to behave exactly like the built-in scalars, allowing for selective overloading of methods. The new method is provided as a means of grandfathering, for classes that forget to provide their own TIESCALAR method.

For developers wishing to write their own tied-scalar classes, the methods are summarized below. The the perltie manpage section not only documents these, but has sample code as well:

TIESCALAR classname, LIST

The method invoked by the command tie $scalar, classname. Associates a new scalar instance with the specified class. LIST would represent additional arguments (along the lines of the AnyDBM_File manpage and compatriots) needed to complete the association.

FETCH this

Retrieve the value of the tied scalar referenced by this.

STORE this, value

Store data value in the tied scalar referenced by this.

DESTROY this

Free the storage associated with the tied scalar referenced by this. This is rarely needed, as Perl manages its memory quite well. But the option exists, should a class wish to perform specific actions upon the destruction of an instance.

MORE INFORMATION

The the perltie manpage section uses a good example of tying scalars by associating process IDs with priority.


Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing

  • CAVEATS

NAME

Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing

SYNOPSIS

    require Tie::SubstrHash;

    tie %myhash, 'Tie::SubstrHash', $key_len, $value_len, $table_size;

DESCRIPTION

The Tie::SubstrHash package provides a hash-table-like interface to an array of determinate size, with constant key size and record size.

Upon tying a new hash to this package, the developer must specify the size of the keys that will be used, the size of the value fields that the keys will index, and the size of the overall table (in terms of key-value pairs, not size in hard memory). These values will not change for the duration of the tied hash. The newly-allocated hash table may now have data stored and retrieved. Efforts to store more than $table_size elements will result in a fatal error, as will efforts to store a value not exactly $value_len characters in length, or reference through a key not exactly $key_len characters in length. While these constraints may seem excessive, the result is a hash table using much less internal memory than an equivalent freely-allocated hash table.

CAVEATS

Because the current implementation uses the table and key sizes for the hashing algorithm, there is no means by which to dynamically change the value of any of the initialization parameters.

The hash does not support exists().


Tie::Watch - place watchpoints on Perl variables.

  • METHODS
  • EFFICIENCY CONSIDERATIONS
  • AUTHOR
  • HISTORY
  • COPYRIGHT

NAME

 Tie::Watch - place watchpoints on Perl variables.

SYNOPSIS

 use Tie::Watch;

 $watch = Tie::Watch->new(
     -variable => \$frog,
     -debug    => 1,
     -shadow   => 0,
     -fetch    => [\&fetch, 'arg1', 'arg2', ..., 'argn'],
     -store    => \&store,
     -destroy  => sub {print "Final value=$frog.\n"},
 }
 %vinfo = $watch->Info;
 $args  = $watch->Args(-fetch);
 $val   = $watch->Fetch;
 print "val=", $watch->Say($val), ".\n";
 $watch->Store('Hello');
 $watch->Unwatch;

DESCRIPTION

This class module binds one or more subroutines of your devising to a Perl variable. All variables can have FETCH, STORE and DESTROY callbacks. Additionally, arrays can define CLEAR, EXTEND, FETCHSIZE, POP, PUSH, SHIFT, SPLICE, STORESIZE and UNSHIFT callbacks, and hashes can define CLEAR, DELETE, EXISTS, FIRSTKEY and NEXTKEY callbacks. If these term are unfamiliar to you, I really suggest you read the perltie manpage.

With Tie::Watch you can:

 . alter a variable's value
 . prevent a variable's value from being changed
 . invoke a Perl/Tk callback when a variable changes
 . trace references to a variable

Callback format is patterned after the Perl/Tk scheme: supply either a code reference, or, supply an array reference and pass the callback code reference in the first element of the array, followed by callback arguments. (See examples in the Synopsis, above.)

Tie::Watch provides default callbacks for any that you fail to specify. Other than negatively impacting performance, they perform the standard action that you'd expect, so the variable behaves "normally". Once you override a default callback, perhaps to insert debug code like print statements, your callback normally finishes by calling the underlying (overridden) method. But you don't have to!

To map a tied method name to a default callback name simply lowercase the tied method name and uppercase its first character. So FETCH becomes Fetch, NEXTKEY becomes Nextkey, etcetera.

Here are two callbacks for a scalar. The FETCH (read) callback does nothing other than illustrate the fact that it returns the value to assign the variable. The STORE (write) callback uppercases the variable and returns it. In all cases the callback must return the correct read or write value - typically, it does this by invoking the underlying method.

 my $fetch_scalar = sub {
     my($self) = @_;
     $self->Fetch;
 };

 my $store_scalar = sub {
     my($self, $new_val) = @_;
     $self->Store(uc $new_val);
 };

Here are FETCH and STORE callbacks for either an array or hash. They do essentially the same thing as the scalar callbacks, but provide a little more information.

 my $fetch = sub {
     my($self, $key) = @_;
     my $val = $self->Fetch($key);
     print "In fetch callback, key=$key, val=", $self->Say($val);
     my $args = $self->Args(-fetch);
     print ", args=('", join("', '",  @$args), "')" if $args;
     print ".\n";
     $val;
 };

 my $store = sub {
     my($self, $key, $new_val) = @_;
     my $val = $self->Fetch($key);
     $new_val = uc $new_val;
     $self->Store($key, $new_val);
     print "In store callback, key=$key, val=", $self->Say($val),
       ", new_val=", $self->Say($new_val);
     my $args = $self->Args(-store);
     print ", args=('", join("', '",  @$args), "')" if $args;
     print ".\n";
     $new_val;
 };

In all cases, the first parameter is a reference to the Watch object, used to invoke the following class methods.

METHODS

$watch = Tie::Watch->new(-options => values);

The watchpoint constructor method that accepts option/value pairs to create and configure the Watch object. The only required option is -variable.

-variable is a reference to a scalar, array or hash variable.

-debug (default 0) is 1 to activate debug print statements internal to Tie::Watch.

-shadow (default 1) is 0 to disable array and hash shadowing. To prevent infinite recursion Tie::Watch maintains parallel variables for arrays and hashes. When the watchpoint is created the parallel shadow variable is initialized with the watched variable's contents, and when the watchpoint is deleted the shadow variable is copied to the original variable. Thus, changes made during the watch process are not lost. Shadowing is on my default. If you disable shadowing any changes made to an array or hash are lost when the watchpoint is deleted.

Specify any of the following relevant callback parameters, in the format described above: -fetch, -store, -destroy. Additionally for arrays: -clear, -extend, -fetchsize, -pop, -push, -shift, -splice, -storesize and -unshift. Additionally for hashes: -clear, -delete, -exists, -firstkey and -nextkey.

$args = $watch->Args(-fetch);

Returns a reference to a list of arguments for the specified callback, or undefined if none.

$watch->Fetch(); $watch->Fetch($key);

Returns a variable's current value. $key is required for an array or hash.

%vinfo = $watch->Info();

Returns a hash detailing the internals of the Watch object, with these keys:

 %vinfo = {
     -variable =>  SCALAR(0x200737f8)
     -debug    =>  '0'
     -shadow   =>  '1'
     -value    =>  'HELLO SCALAR'
     -destroy  =>  ARRAY(0x200f86cc)
     -fetch    =>  ARRAY(0x200f8558)
     -store    =>  ARRAY(0x200f85a0)
     -legible  =>  above data formatted as a list of string, for printing
 }

For array and hash Watch objects, the -value key is replaced with a -ptr key which is a reference to the parallel array or hash. Additionally, for an array or hash, there are key/value pairs for all the variable specific callbacks.

$watch->Say($val);

Used mainly for debugging, it returns $val in quotes if required, or the string "undefined" for undefined values.

$watch->Store($new_val); $watch->Store($key, $new_val);

Store a variable's new value. $key is required for an array or hash.

$watch->Unwatch();

Stop watching the variable.

EFFICIENCY CONSIDERATIONS

If you can live using the class methods provided, please do so. You can meddle with the object hash directly and improved watch performance, at the risk of your code breaking in the future.

AUTHOR

Stephen.O.Lidie@Lehigh.EDU

HISTORY

 lusol@Lehigh.EDU, LUCC, 96/05/30
 . Original version 0.92 release, based on the Trace module from Hans Mulder,
   and ideas from Tim Bunce.
 lusol@Lehigh.EDU, LUCC, 96/12/25
 . Version 0.96, release two inner references detected by Perl 5.004.
 lusol@Lehigh.EDU, LUCC, 97/01/11
 . Version 0.97, fix Makefile.PL and MANIFEST (thanks Andreas Koenig).
   Make sure test.pl doesn't fail if Tk isn't installed.
 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 97/10/03
 . Version 0.98, implement -shadow option for arrays and hashes.
 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 98/02/11
 . Version 0.99, finally, with Perl 5.004_57, we can completely watch arrays.
   With tied array support this module is essentially complete, so its been
   optimized for speed at the expense of clarity - sorry about that. The
   Delete() method has been renamed Unwatch() because it conflicts with the
   builtin delete().
 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 99/04/04
 . Version 1.0, for Perl 5.005_03, update Makefile.PL for ActiveState, and
   add two examples (one for Perl/Tk).

COPYRIGHT

Copyright (C) 1996 - 1999 Stephen O. Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers

  • EXAMPLES
  • C API
  • DIAGNOSTICS
    • negative time not invented yet
    • internal error: useconds < 0 (unsigned ... signed ...)
  • CAVEATS
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT AND LICENSE

NAME

Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers

SYNOPSIS

  use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
                      clock_gettime clock_getres clock_nanosleep clock );

  usleep ($microseconds);
  nanosleep ($nanoseconds);

  ualarm ($microseconds);
  ualarm ($microseconds, $interval_microseconds);

  $t0 = [gettimeofday];
  ($seconds, $microseconds) = gettimeofday;

  $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  $elapsed = tv_interval ( $t0, [gettimeofday]);
  $elapsed = tv_interval ( $t0 );

  use Time::HiRes qw ( time alarm sleep );

  $now_fractions = time;
  sleep ($floating_seconds);
  alarm ($floating_seconds);
  alarm ($floating_seconds, $floating_interval);

  use Time::HiRes qw( setitimer getitimer
                      ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );

  setitimer ($which, $floating_seconds, $floating_interval );
  getitimer ($which);

  $realtime   = clock_gettime(CLOCK_REALTIME);
  $resolution = clock_getres(CLOCK_REALTIME);

  clock_nanosleep(CLOCK_REALTIME, 1.5);
  clock_nanosleep(CLOCK_REALTIME, time() + 10, TIMER_ABSTIME);

  my $ticktock = clock();

DESCRIPTION

The Time::HiRes module implements a Perl interface to the usleep, nanosleep, ualarm, gettimeofday, and setitimer/getitimer system calls, in other words, high resolution time and timers. See the EXAMPLES section below and the test scripts for usage; see your system documentation for the description of the underlying nanosleep or usleep, ualarm, gettimeofday, and setitimer/getitimer calls.

If your system lacks gettimeofday() or an emulation of it you don't get gettimeofday() or the one-argument form of tv_interval(). If your system lacks all of nanosleep(), usleep(), select(), and poll, you don't get Time::HiRes::usleep(), Time::HiRes::nanosleep(), or Time::HiRes::sleep(). If your system lacks both ualarm() and setitimer() you don't get Time::HiRes::ualarm() or Time::HiRes::alarm().

If you try to import an unimplemented function in the use statement it will fail at compile time.

If your subsecond sleeping is implemented with nanosleep() instead of usleep(), you can mix subsecond sleeping with signals since nanosleep() does not use signals. This, however, is not portable, and you should first check for the truth value of &Time::HiRes::d_nanosleep to see whether you have nanosleep, and then carefully read your nanosleep() C API documentation for any peculiarities.

If you are using nanosleep for something else than mixing sleeping with signals, give some thought to whether Perl is the tool you should be using for work requiring nanosecond accuracies.

The following functions can be imported from this module. No functions are exported by default.

gettimeofday ()

In array context returns a two-element array with the seconds and microseconds since the epoch. In scalar context returns floating seconds like Time::HiRes::time() (see below).

usleep ( $useconds )

Sleeps for the number of microseconds (millionths of a second) specified. Returns the number of microseconds actually slept. Can sleep for more than one second, unlike the usleep system call. Can also sleep for zero seconds, which often works like a thread yield. See also Time::HiRes::usleep(), Time::HiRes::sleep(), and Time::HiRes::clock_nanosleep().

Do not expect usleep() to be exact down to one microsecond.

nanosleep ( $nanoseconds )

Sleeps for the number of nanoseconds (1e9ths of a second) specified. Returns the number of nanoseconds actually slept (accurate only to microseconds, the nearest thousand of them). Can sleep for more than one second. Can also sleep for zero seconds, which often works like a thread yield. See also Time::HiRes::sleep(), Time::HiRes::usleep(), and Time::HiRes::clock_nanosleep().

Do not expect nanosleep() to be exact down to one nanosecond. Getting even accuracy of one thousand nanoseconds is good.

ualarm ( $useconds [, $interval_useconds ] )

Issues a ualarm call; the $interval_useconds is optional and will be zero if unspecified, resulting in alarm-like behaviour.

Note that the interaction between alarms and sleeps is unspecified.

tv_interval

tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )

Returns the floating seconds between the two times, which should have been returned by gettimeofday(). If the second argument is omitted, then the current time is used.

time ()

Returns a floating seconds since the epoch. This function can be imported, resulting in a nice drop-in replacement for the time provided with core Perl; see the EXAMPLES below.

NOTE 1: This higher resolution timer can return values either less or more than the core time(), depending on whether your platform rounds the higher resolution timer values up, down, or to the nearest second to get the core time(), but naturally the difference should be never more than half a second. See also clock_getres, if available in your system.

NOTE 2: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when the time() seconds since epoch rolled over to 1_000_000_000, the default floating point format of Perl and the seconds since epoch have conspired to produce an apparent bug: if you print the value of Time::HiRes::time() you seem to be getting only five decimals, not six as promised (microseconds). Not to worry, the microseconds are there (assuming your platform supports such granularity in the first place). What is going on is that the default floating point format of Perl only outputs 15 digits. In this case that means ten digits before the decimal separator and five after. To see the microseconds you can use either printf/sprintf with "%.6f", or the gettimeofday() function in list context, which will give you the seconds and microseconds as two separate values.

sleep ( $floating_seconds )

Sleeps for the specified amount of seconds. Returns the number of seconds actually slept (a floating point value). This function can be imported, resulting in a nice drop-in replacement for the sleep provided with perl, see the EXAMPLES below.

Note that the interaction between alarms and sleeps is unspecified.

alarm ( $floating_seconds [, $interval_floating_seconds ] )

The SIGALRM signal is sent after the specified number of seconds. Implemented using ualarm(). The $interval_floating_seconds argument is optional and will be zero if unspecified, resulting in alarm()-like behaviour. This function can be imported, resulting in a nice drop-in replacement for the alarm provided with perl, see the EXAMPLES below.

NOTE 1: With some combinations of operating systems and Perl releases SIGALRM restarts select(), instead of interrupting it. This means that an alarm() followed by a select() may together take the sum of the times specified for the the alarm() and the select(), not just the time of the alarm().

Note that the interaction between alarms and sleeps is unspecified.

setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )

Start up an interval timer: after a certain time, a signal arrives, and more signals may keep arriving at certain intervals. To disable an "itimer", use $floating_seconds of zero. If the $interval_floating_seconds is set to zero (or unspecified), the timer is disabled after the next delivered signal.

Use of interval timers may interfere with alarm(), sleep(), and usleep(). In standard-speak the "interaction is unspecified", which means that anything may happen: it may work, it may not.

In scalar context, the remaining time in the timer is returned.

In list context, both the remaining time and the interval are returned.

There are usually three or four interval timers available: the $which can be ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF, or ITIMER_REALPROF. Note that which ones are available depends: true UNIX platforms usually have the first three, but (for example) Win32 and Cygwin have only ITIMER_REAL, and only Solaris seems to have ITIMER_REALPROF (which is used to profile multithreaded programs).

ITIMER_REAL results in alarm()-like behaviour. Time is counted in real time; that is, wallclock time. SIGALRM is delivered when the timer expires.

ITIMER_VIRTUAL counts time in (process) virtual time; that is, only when the process is running. In multiprocessor/user/CPU systems this may be more or less than real or wallclock time. (This time is also known as the user time.) SIGVTALRM is delivered when the timer expires.

ITIMER_PROF counts time when either the process virtual time or when the operating system is running on behalf of the process (such as I/O). (This time is also known as the system time.) (The sum of user time and system time is known as the CPU time.) SIGPROF is delivered when the timer expires. SIGPROF can interrupt system calls.

The semantics of interval timers for multithreaded programs are system-specific, and some systems may support additional interval timers. See your setitimer() documentation.

getitimer ( $which )

Return the remaining time in the interval timer specified by $which.

In scalar context, the remaining time is returned.

In list context, both the remaining time and the interval are returned. The interval is always what you put in using setitimer().

clock_gettime ( $which )

Return as seconds the current value of the POSIX high resolution timer specified by $which. All implementations that support POSIX high resolution timers are supposed to support at least the $which value of CLOCK_REALTIME, which is supposed to return results close to the results of gettimeofday, or the number of seconds since 00:00:00:00 January 1, 1970 Greenwich Mean Time (GMT). Do not assume that CLOCK_REALTIME is zero, it might be one, or something else. Another potentially useful (but not available everywhere) value is CLOCK_MONOTONIC, which guarantees a monotonically increasing time value (unlike time(), which can be adjusted). See your system documentation for other possibly supported values.

clock_getres ( $which )

Return as seconds the resolution of the POSIX high resolution timer specified by $which. All implementations that support POSIX high resolution timers are supposed to support at least the $which value of CLOCK_REALTIME, see clock_gettime.

clock_nanosleep ( $which, $seconds, $flags = 0)

Sleeps for the number of seconds (1e9ths of a second) specified. Returns the number of seconds actually slept. The $which is the "clock id", as with clock_gettime() and clock_getres(). The flags default to zero but TIMER_ABSTIME can specified (must be exported explicitly) which means that $nanoseconds is not a time interval (as is the default) but instead an absolute time. Can sleep for more than one second. Can also sleep for zero seconds, which often works like a thread yield. See also Time::HiRes::sleep(), Time::HiRes::usleep(), and Time::HiRes::nanosleep().

Do not expect clock_nanosleep() to be exact down to one nanosecond. Getting even accuracy of one thousand nanoseconds is good.

clock()

Return as seconds the process time (user + system time) spent by the process since the first call to clock() (the definition is not "since the start of the process", though if you are lucky these times may be quite close to each other, depending on the system). What this means is that you probably need to store the result of your first call to clock(), and subtract that value from the following results of clock().

The time returned also includes the process times of the terminated child processes for which wait() has been executed. This value is somewhat like the second value returned by the times() of core Perl, but not necessarily identical. Note that due to backward compatibility limitations the returned value may wrap around at about 2147 seconds or at about 36 minutes.

EXAMPLES

  use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);

  $microseconds = 750_000;
  usleep($microseconds);

  # signal alarm in 2.5s & every .1s thereafter
  ualarm(2_500_000, 100_000);

  # get seconds and microseconds since the epoch
  ($s, $usec) = gettimeofday();

  # measure elapsed time
  # (could also do by subtracting 2 gettimeofday return values)
  $t0 = [gettimeofday];
  # do bunch of stuff here
  $t1 = [gettimeofday];
  # do more stuff here
  $t0_t1 = tv_interval $t0, $t1;

  $elapsed = tv_interval ($t0, [gettimeofday]);
  $elapsed = tv_interval ($t0); # equivalent code

  #
  # replacements for time, alarm and sleep that know about
  # floating seconds
  #
  use Time::HiRes;
  $now_fractions = Time::HiRes::time;
  Time::HiRes::sleep (2.5);
  Time::HiRes::alarm (10.6666666);

  use Time::HiRes qw ( time alarm sleep );
  $now_fractions = time;
  sleep (2.5);
  alarm (10.6666666);

  # Arm an interval timer to go off first at 10 seconds and
  # after that every 2.5 seconds, in process virtual time

  use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );

  $SIG{VTALRM} = sub { print time, "\n" };
  setitimer(ITIMER_VIRTUAL, 10, 2.5);

  use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
  # Read the POSIX high resolution timer.
  my $high = clock_getres(CLOCK_REALTIME);
  # But how accurate we can be, really?
  my $reso = clock_getres(CLOCK_REALTIME);

  use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
  clock_nanosleep(CLOCK_REALTIME, 1e6);
  clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);

  use Time::HiRes qw( clock );
  my $clock0 = clock();
  ... # Do something.
  my $clock1 = clock();
  my $clockd = $clock1 - $clock0;

C API

In addition to the perl API described above, a C API is available for extension writers. The following C functions are available in the modglobal hash:

  name             C prototype
  ---------------  ----------------------
  Time::NVtime     double (*)()
  Time::U2time     void (*)(pTHX_ UV ret[2])

Both functions return equivalent information (like gettimeofday) but with different representations. The names NVtime and U2time were selected mainly because they are operating system independent. (gettimeofday is Unix-centric, though some platforms like Win32 and VMS have emulations for it.)

Here is an example of using NVtime from C:

  double (*myNVtime)(); /* Returns -1 on failure. */
  SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
  if (!svp)         croak("Time::HiRes is required");
  if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
  myNVtime = INT2PTR(double(*)(), SvIV(*svp));
  printf("The current time is: %f\n", (*myNVtime)());

DIAGNOSTICS

negative time not invented yet

You tried to use a negative time argument.

internal error: useconds < 0 (unsigned ... signed ...)

Something went horribly wrong-- the number of microseconds that cannot become negative just became negative. Maybe your compiler is broken?

CAVEATS

Notice that the core time() maybe rounding rather than truncating. What this means is that the core time() may be reporting the time as one second later than gettimeofday() and Time::HiRes::time().

Adjusting the system clock (either manually or by services like ntp) may cause problems, especially for long running programs that assume a monotonously increasing time (note that all platforms do not adjust time as gracefully as UNIX ntp does). For example in Win32 (and derived platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily drift off from the system clock (and the original time()) by up to 0.5 seconds. Time::HiRes will notice this eventually and recalibrate. Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC) might help in this (in case your system supports CLOCK_MONOTONIC).

SEE ALSO

Perl modules the BSD::Resource manpage, the Time::TAI64 manpage.

Your system documentation for clock_gettime, clock_settime, gettimeofday, getitimer, setitimer, ualarm.

AUTHORS

D. Wegscheid <wegscd@whirlpool.com> R. Schertler <roderick@argon.org> J. Hietaniemi <jhi@iki.fi> G. Aas <gisle@aas.no>

COPYRIGHT AND LICENSE

Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.

Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Time::Local - efficiently compute time from local and GMT time

    • Ambiguous Local Times (DST)
    • Non-Existent Local Times (DST)
    • Negative Epoch Values
  • IMPLEMENTATION
  • BUGS
  • SUPPORT
  • AUTHOR

NAME

Time::Local - efficiently compute time from local and GMT time

SYNOPSIS

    $time = timelocal($sec,$min,$hour,$mday,$mon,$year);
    $time = timegm($sec,$min,$hour,$mday,$mon,$year);

DESCRIPTION

These routines are the inverse of built-in perl functions localtime() and gmtime(). They accept a date as a six-element array, and return the corresponding time(2) value in seconds since the system epoch (Midnight, January 1, 1970 GMT on Unix, for example). This value can be positive or negative, though POSIX only requires support for positive values, so dates before the system's epoch may not work on all operating systems.

It is worth drawing particular attention to the expected ranges for the values provided. The value for the day of the month is the actual day (ie 1..31), while the month is the number of months since January (0..11). This is consistent with the values returned from localtime() and gmtime().

The timelocal() and timegm() functions perform range checking on the input $sec, $min, $hour, $mday, and $mon values by default. If you'd rather they didn't, you can explicitly import the timelocal_nocheck() and timegm_nocheck() functions.

        use Time::Local 'timelocal_nocheck';

        {
            # The 365th day of 1999
            print scalar localtime timelocal_nocheck 0,0,0,365,0,99;

            # The twenty thousandth day since 1970
            print scalar localtime timelocal_nocheck 0,0,0,20000,0,70;

            # And even the 10,000,000th second since 1999!
            print scalar localtime timelocal_nocheck 10000000,0,0,1,0,99;
                    }

Your mileage may vary when trying these with minutes and hours, and it doesn't work at all for months.

Strictly speaking, the year should also be specified in a form consistent with localtime(), i.e. the offset from 1900. In order to make the interpretation of the year easier for humans, however, who are more accustomed to seeing years as two-digit or four-digit values, the following conventions are followed:

  • Years greater than 999 are interpreted as being the actual year, rather than the offset from 1900. Thus, 1964 would indicate the year Martin Luther King won the Nobel prize, not the year 3864.

  • Years in the range 100..999 are interpreted as offset from 1900, so that 112 indicates 2012. This rule also applies to years less than zero (but see note below regarding date range).

  • Years in the range 0..99 are interpreted as shorthand for years in the rolling "current century," defined as 50 years on either side of the current year. Thus, today, in 1999, 0 would refer to 2000, and 45 to 2045, but 55 would refer to 1955. Twenty years from now, 55 would instead refer to 2055. This is messy, but matches the way people currently think about two digit dates. Whenever possible, use an absolute four digit year instead.

The scheme above allows interpretation of a wide range of dates, particularly if 4-digit years are used.

Please note, however, that the range of dates that can be actually be handled depends on the size of an integer (time_t) on a given platform. Currently, this is 32 bits for most systems, yielding an approximate range from Dec 1901 to Jan 2038.

Both timelocal() and timegm() croak if given dates outside the supported range.

Ambiguous Local Times (DST)

Because of DST changes, there are many time zones where the same local time occurs for two different GMT times on the same day. For example, in the "Europe/Paris" time zone, the local time of 2001-10-28 02:30:00 can represent either 2001-10-28 00:30:00 GMT, or 2001-10-28 01:30:00 GMT.

When given an ambiguous local time, the timelocal() function should always return the epoch for the earlier of the two possible GMT times.

Non-Existent Local Times (DST)

When a DST change causes a locale clock to skip one hour forward, there will be an hour's worth of local times that don't exist. Again, for the "Europe/Paris" time zone, the local clock jumped from 2001-03-25 01:59:59 to 2001-03-25 03:00:00.

If the timelocal() function is given a non-existent local time, it will simply return an epoch value for the time one hour later.

Negative Epoch Values

Negative epoch (time_t) values are not officially supported by the POSIX standards, so this module's tests do not test them. On some systems, they are known not to work. These include MacOS (pre-OSX) and Win32.

On systems which do support negative epoch values, this module should be able to cope with dates before the start of the epoch, down the minimum value of time_t for the system.

IMPLEMENTATION

These routines are quite efficient and yet are always guaranteed to agree with localtime() and gmtime(). We manage this by caching the start times of any months we've seen before. If we know the start time of the month, we can always calculate any time within the month. The start times are calculated using a mathematical formula. Unlike other algorithms that do multiple calls to gmtime().

timelocal() is implemented using the same cache. We just assume that we're translating a GMT time, and then fudge it when we're done for the timezone and daylight savings arguments. Note that the timezone is evaluated for each date because countries occasionally change their official timezones. Assuming that localtime() corrects for these changes, this routine will also be correct.

BUGS

The whole scheme for interpreting two-digit years can be considered a bug.

SUPPORT

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

Please submit bugs using the RT system at rt.cpan.org, or as a last resort, to the datetime@perl.org list.

AUTHOR

This module is based on a Perl 4 library, timelocal.pl, that was included with Perl 4.036, and was most likely written by Tom Christiansen.

The current version was written by Graham Barr.

It is now being maintained separately from the Perl core by Dave Rolsky, <autarch@urth.org>.


Time::Zone -- miscellaneous timezone manipulations routines

  • AUTHORS

NAME

Time::Zone -- miscellaneous timezone manipulations routines

SYNOPSIS

        use Time::Zone;
        print tz2zone();
        print tz2zone($ENV{'TZ'});
        print tz2zone($ENV{'TZ'}, time());
        print tz2zone($ENV{'TZ'}, undef, $isdst);
        $offset = tz_local_offset();
        $offset = tz_offset($TZ);

DESCRIPTION

This is a collection of miscellaneous timezone manipulation routines.

tz2zone() parses the TZ environment variable and returns a timezone string suitable for inclusion in date-like output. It opionally takes a timezone string, a time, and a is-dst flag.

tz_local_offset() determins the offset from GMT time in seconds. It only does the calculation once.

tz_offset() determines the offset from GMT in seconds of a specified timezone.

tz_name() determines the name of the timezone based on its offset

AUTHORS

Graham Barr <gbarr@pobox.com> David Muir Sharnoff <muir@idiom.com> Paul Foley <paul@ascent.com>


Time::gmtime - by-name interface to Perl's built-in gmtime function

  • NOTE
  • AUTHOR

NAME

Time::gmtime - by-name interface to Perl's built-in gmtime() function

SYNOPSIS

 use Time::gmtime;
 $gm = gmtime();
 printf "The day in Greenwich is %s\n",
    (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm->wday() ];

 use Time::gmtime w(:FIELDS;
 printf "The day in Greenwich is %s\n",
    (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm_wday() ];

 $now = gmctime();

 use Time::gmtime;
 use File::stat;
 $date_string = gmctime(stat($file)->mtime);

DESCRIPTION

This module's default exports override the core gmtime() function, replacing it with a version that returns "Time::tm" objects. This object has methods that return the similarly named structure field name from the C's tm structure from time.h; namely sec, min, hour, mday, mon, year, wday, yday, and isdst.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding tm_ in front their method names. Thus, $tm_obj->mday() corresponds to $tm_mday if you import the fields.

The gmctime() function provides a way of getting at the scalar sense of the original CORE::gmtime() function.

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


Time::localtime - by-name interface to Perl's built-in localtime function

  • NOTE
  • AUTHOR

NAME

Time::localtime - by-name interface to Perl's built-in localtime() function

SYNOPSIS

 use Time::localtime;
 printf "Year is %d\n", localtime->year() + 1900;

 $now = ctime();

 use Time::localtime;
 use File::stat;
 $date_string = ctime(stat($file)->mtime);

DESCRIPTION

This module's default exports override the core localtime() function, replacing it with a version that returns "Time::tm" objects. This object has methods that return the similarly named structure field name from the C's tm structure from time.h; namely sec, min, hour, mday, mon, year, wday, yday, and isdst.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding tm_ in front their method names. Thus, $tm_obj->mday() corresponds to $tm_mday if you import the fields.

The ctime() function provides a way of getting at the scalar sense of the original CORE::localtime() function.

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


Time::tm - internal object used by Time::gmtime and Time::localtime

  • AUTHOR

NAME

Time::tm - internal object used by Time::gmtime and Time::localtime

SYNOPSIS

Don't use this module directly.

DESCRIPTION

This module is used internally as a base class by Time::localtime And Time::gmtime functions. It creates a Time::tm struct object which is addressable just like's C's tm structure from time.h; namely with sec, min, hour, mday, mon, year, wday, yday, and isdst.

This class is an internal interface only.

AUTHOR

Tom Christiansen


Tk - a graphical user interface toolkit for Perl

    • Introduction
    • Tk Geometry Management
    • Binding Events and Callbacks
    • Tk Image Classes
    • Tix Extensions
    • Tk Widget Classes
    • Tk Generic Methods
    • User Interaction
    • Creating and Configuring Widgets
    • Popups and Dialogs
    • Derived Widgets
    • C Programming
    • Implementation
    • Experimental Modules
    • Other Modules and Languages
  • AUTHOR
  • SEE ALSO

NAME

Tk - a graphical user interface toolkit for Perl

SYNOPSIS

    use Tk;
    $top = new MainWindow;
    MainLoop;

DESCRIPTION

The Perl/Tk manual is split up into a number of sections:

Introduction

  • Tk::overview

  • Tk::UserGuide

Tk Geometry Management

  • Tk::Adjuster

  • Tk::form

  • Tk::grid

  • Tk::pack

  • Tk::place

  • Tk::Table

  • Tk::Tiler

  • Tk::Wm

Binding Events and Callbacks

  • Tk::After

  • Tk::bind

  • Tk::bindtags

  • Tk::callbacks

  • Tk::Error

  • Tk::event

  • Tk::exit

  • Tk::fileevent

  • Tk::IO

Tk Image Classes

  • Tk::Animation

  • Tk::Bitmap

  • Tk::Compound

  • Tk::Image

  • Tk::Photo

  • Tk::Pixmap

Tix Extensions

  • Tk::Balloon

  • Tk::BrowseEntry

  • Tk::DialogBox

  • Tk::DirTree

  • Tk::DItem

  • Tk::InputO

  • Tk::LabFrame

  • Tk::Mwm

  • Tk::NoteBook

  • Tk::TixGrid

  • Tk::tixWm

  • Tk::TList

  • Tk::Tree

Tk Widget Classes

  • Tk::Button

  • Tk::Canvas

  • Tk::Checkbutton

  • Tk::Entry

  • Tk::Frame

  • Tk::HList

  • Tk::Label

  • Tk::Listbox

  • Tk::Menu

  • Tk::Menubutton

  • Tk::Message

  • Tk::Optionmenu

  • Tk::Radiobutton

  • Tk::Scale

  • Tk::Scrollbar

  • Tk::Text

  • Tk::Toplevel

Tk Generic Methods

  • Tk::Font

  • Tk::send

  • Tk::tkvars

  • Tk::Widget

  • Tk::X11Font

User Interaction

  • Tk::DropSite

  • Tk::Clipboard

  • Tk::focus

  • Tk::grab

  • Tk::selection

Creating and Configuring Widgets

  • Tk::CmdLine

  • Tk::MainWindow

  • Tk::option

  • Tk::options

  • Tk::palette

  • Tk::Xrm

Popups and Dialogs

  • Tk::chooseColor

  • Tk::ColorEditor

  • Tk::Dialog

  • Tk::Dialog

  • Tk::FileSelect

  • Tk::getOpenFile

  • Tk::messageBox

Derived Widgets

  • Tk::composite

  • Tk::configspec

  • Tk::Derived

  • Tk::mega

  • Tk::ROText

  • Tk::Scrolled

  • Tk::TextUndo

  • Tk::Reindex

  • Tk::Pane

  • Tk::ProgressBar

C Programming

  • Internals

  • pTk

  • 3DBorder

  • BackgdErr

  • BindTable

  • CanvPsY

  • CanvTkwin

  • CanvTxtInfo

  • Clipboard

  • ClrSelect

  • ConfigWidg

  • ConfigWind

  • CoordToWin

  • CrtErrHdlr

  • CrtGenHdlr

  • CrtImgType

  • CrtItemType

  • CrtMainWin

  • CrtPhImgFmt

  • CrtSelHdlr

  • CrtWindow

  • DeleteImg

  • DoOneEvent

  • DoWhenIdle

  • DrawFocHlt

  • EventHndlr

  • EventInit

  • FileHndlr

  • FindPhoto

  • FontId

  • FreeXId

  • GeomReq

  • GetAnchor

  • GetBitmap

  • GetCapStyl

  • GetClrmap

  • GetColor

  • GetCursor

  • GetFont

  • GetFontStr

  • GetGC

  • GetImage

  • GetJoinStl

  • GetJustify

  • GetOption

  • GetPixels

  • GetPixmap

  • GetRelief

  • GetRootCrd

  • GetScroll

  • GetSelect

  • GetUid

  • GetVisual

  • GetVRoot

  • HandleEvent

  • IdToWindow

  • ImgChanged

  • InternAtom

  • MainLoop

  • MaintGeom

  • MainWin

  • ManageGeom

  • MapWindow

  • MeasureChar

  • MoveToplev

  • Name

  • NameOfImg

  • OwnSelect

  • ParseArgv

  • Preserve

  • QWinEvent

  • Restack

  • RestrictEv

  • SetAppName

  • SetClass

  • SetGrid

  • SetVisual

  • Sleep

  • StrictMotif

  • TextLayout

  • TimerHndlr

  • Tk_Init

  • WindowId

Implementation

  • Tk::Eventloop

  • Tk::Item

  • Tk::Submethods

  • Tk::WidgetDemo

  • Tk::widgets

Experimental Modules

  • Tk::Common

  • Tk::SunConst

  • Tk::WinPhoto

Other Modules and Languages

  • Tk::Compile

  • Tk::Tcl-perl

  • Tk::X

AUTHOR

Nick Ing-Simmons

SEE ALSO

perl(1), wish(1).


Tk::804delta - what is new for perl/Tk 804

  • Incompatible Changes
  • Enhancements
  • New Widgets
  • Selected Bug Fixes
  • Changed Internals
  • Platform Specific Problems
  • Future Directions
  • Reporting Bugs
  • SEE ALSO

NAME

Tk::804delta - what is new for perl/Tk 804

DESCRIPTION

This document describes differences between the Tk800 series and the Tk804 series.

Incompatible Changes

Tk804 will only work with perl 5.8.0 and above. For older perl versions look for Tk800.025.

curselection of Tk::Listbox now returns an array reference in scalar context. This means you have to write

        my(@selected) = $listbox->curselection

or

        my(@selected) = @{ $listbox->curselection }

now.

The fontActual method now returns the pixel value instead of the point value for -size. Pixel values are expressed as negative numbers.

Some enhancements from the "dash" patches are lost for now (i.e. -tile, -troughtile ...).

The -state option is not available anymore for Tk::Text tags. Use -elide instead.

Enhancements

Tk804 is Unicode-aware.

It is possible to build Tk with Xft support on X11. This is strongly recommened if you are planning to make use of Unicode rendering capabilities of Tk. It also gives anti-aliased fonts for regular text (if you have TrueType or Type1 fonts and they are in your fontconfig config file).

The new method chooseDirectory is available as a standard directory selector.

Tk::PNG and Tk::JPEG are bundled now with the perl/Tk distribution, providing support for the image formats png and jpeg.

Improvements to Tk::Listbox: new option -activestyle, new methods itemconfigure and itemcget, new virtual event << <<ListboxSelect> >>>.

More tests.

New Widgets

Tk::Labelframe

An alternative to Tk::LabFrame.

Tk::Panedwindow

An alternative to Tk::Adjuster.

Tk::Spinbox

An alternative to the CPAN module Tk::NumEntry.

Selected Bug Fixes

Changed Internals

Platform Specific Problems

Future Directions

Reporting Bugs

If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.tk newsgroup.

If you believe you have an unreported bug, please send a mail to <ptk@lists.stanford.edu> and/or <nick@ing-simmons.net>. Be sure to trim your bug down to a tiny but sufficient test case.

SEE ALSO

the Tk manpage.


Tk::Adjuster - Allow size of packed widgets to be adjusted by user

  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • EXAMPLES
  • BUGS

NAME

Tk::Adjuster - Allow size of packed widgets to be adjusted by user

SYNOPSIS

use Tk::Adjuster;

$adjuster = $widget->Adjuster(?options?);

WIDGET-SPECIFIC OPTIONS

Name: restore
Class: Restore
Switch: -restore

Specifies a boolean value that determines whether the Adjuster should forcibly attempt to make room for itself (by reducing the size of its managed widget) when it is unmapped (for example, due to a size change in a top level window). The default value is 1.

Name: side
Class: Side
Switch: -side

Specifies the side on which the managed widget lies relative to the Adjuster. In conjunction with the pack geometry manager, this relates to the side of the master against which the managed widget and the Adjuster are packed. Must be left, right, top, or bottom. Defaults to top.

Name: widget
Class: Widget
Switch: -widget

Specifies the widget which is to be managed by the Adjuster.

DESCRIPTION

Tk::Adjuster is a Frame containing a "line" and a "blob".

Dragging with Mouse Button-1 results in a line being dragged to indicate new size. Releasing Button-1 submits GeometryRequests on behalf of the managed widget which will cause the packer to change the widget's size.

If Drag is done with Shift button down, then GeometryRequests are made in "real time" so that text-flow effects can be seen, but as a lot more work is done behaviour may be sluggish.

If widget is packed with -side => left or -side => right then width is adjusted. If packed -side => top or -side => bottom then height is adjusted.

packPropagate is turned off for the master window to prevent adjustment changing overall window size. Similarly packPropagate is turned off for the managed widget if it has things packed inside it. This is so that the GeometryRequests made by Tk::Adjuster are not overridden by pack.

In addition, the managed widget is made non-expandable to prevent the geometry manager reallocating freed space in the master back to the managed widget. Note however that expansion is turned off only after the Adjuster is mapped, which allows the managed widget to expand naturally on window creation.

The Tk::Widget method, packAdjust, calls pack on the widget, then creates an instance of Tk::Adjuster, and packs that "after" the widget. Its use has two disadvantages however: the Adjuster widget is not made available to the caller, and options cannot be set on the Adjuster. For these reasons, the Tk::Adjuster method, packAfter is preferred, but packAdjust is retained for backwards compatibility.

WIDGET METHODS

$adjuster->packAfter(managed_widget, ?pack_options?)

This command configures the Adjuster's -widget and -side options respectively to managed_widget and the -side value specified in pack_options (top if not specified). It then packs the Adjuster after managed_widget, with -fill set to x or y as appropriate.

$adjuster->packForget?(boolean)?

This command calls Tk::Widget::packForget on the Adjuster. If a parameter is provided and it has a true boolean value, then packForget is also called on the managed widget.

$adjuster->slave

This command returns the value $adjuster->cget('-widget'), ie. the reference to the managed widget.

EXAMPLES

Using an Adjuster to separate two widgets, whereby the left widget is managed, and right widget expands to fill space on a window resize

a) Using packAfter (preferred interface)

  use Tk;
  use Tk::Adjuster;

  my $f = MainWindow->new;
  my $lst1 = $f->Listbox();
  my $adj1 = $f->Adjuster();
  my $lst2 = $f->Listbox();

  my $side = 'left';
  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  $adj1->packAfter($lst1, -side => $side);
  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
  MainLoop;

b) Using packAdjust

  use Tk;
  use Tk::Adjuster;

  my $f = MainWindow->new;
  my $lst1 = $f->Listbox();
  my $lst2 = $f->Listbox();

  my $side = 'left';
  $lst1->packAdjust(-side => $side, -fill => 'both');
  $lst2->pack      (-side => $side, -fill => 'both', -expand => 1);
  MainLoop;

c) Using the standard Tk::Widget::pack

  use Tk;
  use Tk::Adjuster;

  my $f = MainWindow->new;
  my $side = 'left';
  my $lst1 = $f->Listbox();
  my $adj  = $f->Adjuster(-widget => $lst1, -side => $side);
  my $lst2 = $f->Listbox();

  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  $adj->pack (-side => $side, -fill => 'y');
  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);

  MainLoop;

Changing the above examples so that $side has the value 'right' means the left widget expands to fill space on a window resize.

Changing the above examples so that $side has the value 'top' produces a testcase with a horizontal Adjuster. Here the bottom widget expands to fill space on a window resize. Packing to the 'bottom' makes the top widget expand to fill space on window resize.

Using -restore => 0 for multiple columns

In the case of multiple columns (or rows) the "restore" functionality of the Adjuster can be inconvenient. When the user adjusts the width of one column and thereby pushes the Adjuster of another column off the window, this adjuster tries to restore itself by reducing the size of its managed widget. This has the effect that column widths shrink; and the original size is not restored when the user reverses the originating change. The -restore option can be used to turn off this functionality. (It makes some sense, however, to leave -restore turned on for the first-packed Adjuster, so that at least one Adjuster always remains visible.)

  use Tk;
  use Tk::Adjuster;
  my $f = MainWindow->new;
  my $lst1 = $f->Listbox();
  my $adj1 = $f->Adjuster();
  my $lst2 = $f->Listbox();
  my $adj2 = $f->Adjuster(-restore => 0);
  my $lst3 = $f->Listbox();

  my $side = 'left';
  $lst1->pack(-side => $side, -fill => 'both', -expand => 1);
  $adj1->packAfter($lst1, -side => $side);
  $lst2->pack(-side => $side, -fill => 'both', -expand => 1);
  $adj2->packAfter($lst2, -side => $side);
  $lst3->pack(-side => $side, -fill => 'both', -expand => 1);

  MainLoop;

BUGS

It is currently not possible to configure the appearance of the Adjuster. It would be nice to be able to set the width and relief of the Adjuster "line" and the presence/absence of the "blob" on the Adjuster.

Tk::Adjuster works theoretically with the grid geometry manager but there are currently some problems which seem to be due to bugs in grid:

  a) There's never an Unmap event for the adjuster, so the "restore"
     functionality has no effect.
  b) After adjusting, widgets protrude into the border of the master.
  c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows
     when widgets are adjusted.
  d) Widgets shuffle to correct position on startup


Tk::Animation - Display sequence of Tk::Photo images

  • BUGS

NAME

Tk::Animation - Display sequence of Tk::Photo images

SYNOPSIS

  use Tk::Animation
  my $img = $widget->Animation('-format' => 'gif', -file => 'somefile.gif');

  $img->add_frame(@images);

  $img->start_animation( $period );

  $img->next_image;
  $img->prev_image;
  $img->set_image( 0 .. $#frames );

  $img->pause_animation;
  $img->resume_animation( $period );

  $img->fast_forward( $multiplier );
  $img->fast_reverse( $multiplier );

  $img->stop_animation;

  $img->blank( $boolean );

DESCRIPTION

In the simple case when Animation is passed a GIF89 style GIF with multiple 'frames', it will build an internal array of Photo images.

The add_frame method adds images to the sequence. It is provided to allow animations to be constructed from separate images. All images must be Photos and should all be the same size.

start_animation($period) then initiates a repeat with specified $period to sequence through these images. As for raw repeat $period is in milliseconds, for a 50Hz monitor it should be at least 20mS. If $period is omitted it defaults to 100 milliseconds.

stop_animation cancels the repeat and resets the image to the first image in the sequence.

For fine-grained control next_image and prev_image move one frame forward or backward. set_image randomly positions the animation to a particular frame.

pause_animation pauses the movie and resume_animation continues from the pause point.

fast_forward and fast_reverse speed through the movie either forwards or backwards. $multiplier specifies how much faster the animation moves.

By default Animation leaves the previous movie frame in the animation photo. Many times overlaying subsequent frames produces a composite that looks blurred. The blank method is used to blank the animation photo before displaying new frames. The default is 0 for backward compatibility.

BUGS

The 'period' should probably be a property of the Animation object rather than specified at 'start' time. It may even be embedded in the GIF.


Tk::Balloon - pop up help balloons.

    • Balloons and Menus or Listboxes
    • Balloons and Canvases
    • Balloon Position
  • OPTIONS
  • METHODS
    • attach(widget, options)
    • detach(widget)
    • destroy
  • ADVERTISED SUBWIDGETS
  • EXAMPLES
  • NOTES
  • CAVEATS
  • BUGS
  • AUTHORS
  • HISTORY

NAME

Tk::Balloon - pop up help balloons.

SYNOPSIS

    use Tk::Balloon;
    ...
    $b = $top->Balloon(-statusbar => $status_bar_widget);

    # Normal Balloon:
    $b->attach($widget,
               -balloonmsg => "Balloon help message",
               -statusmsg => "Status bar message");

    # Balloon attached to entries in a menu widget:
    $b->attach($menu, -state => 'status',
                      -msg => ['first menu entry',
                               'second menu entry',
                               ...
                              ],
              );

    # Balloon attached to individual items in a canvas widget:
    $b->attach($canvas, -balloonposition => 'mouse',
                        -msg => {'item1' => 'msg1',
                                 'tag2'  => 'msg2',
                                  ...
                                },
              );

    # Balloon attached to items in a listbox widget:
    $b->attach($listbox, -balloonposition => 'mouse',
                         -msg => ['first listbox element',
                                  '2nd listbox element',
                                  ...
                                 ],
              );

DESCRIPTION

Balloon provides the framework to create and attach help balloons to various widgets so that when the mouse pauses over the widget for more than a specified amount of time, a help balloon is popped up.

Balloons and Menus or Listboxes

If the balloon is attached to a Menu or Listbox widget and the message arguments are array references, then each element in the array will be the message corresponding to a menu entry or listbox element. The balloon message will then be shown for the entry which the mouse pauses over. Otherwise it is assumed that the balloon is to be attached to the Menu or Listbox as a whole. You can have separate status and balloon messages just like normal balloons.

Balloons and Canvases

If the balloon is attached to a Canvas widget and the message arguments are hash references, then each hash key should correspond to a canvas item ID or tag and the associated value will correspond to the message for that canvas item. The balloon message will then be shown for the current item (the one at the position of the mouse). Otherwise it is assumed that the balloon is to be attached to the Canvas as a whole. You can have separate status and balloon messages just like normal balloons.

Balloon Position

By default, the balloon pops up at the lower right side of the client. If it would extend outside the lower screen border, its positioned at the upper right side. If it would extend outside the right screen border it's shown on the lower left side of the client. If it would extend outside both the lower and the right screen border, it's positioned at the upper left side of the client. Thus, the little arrow always points to the attached client.

OPTIONS

Balloon accepts all of the options that the Frame widget accepts. In addition, the following options are also recognized.

-initwait

Specifies the amount of time to wait without activity before popping up a help balloon. Specified in milliseconds. Defaults to 350 milliseconds. This applies to both the popped up balloon and the status bar message.

-state

Can be one of 'balloon', 'status', 'both' or 'none' indicating that the help balloon, status bar help, both or none respectively should be activated when the mouse pauses over the client widget. Default is 'both'.

-statusbar

Specifies the widget used to display the status message. This widget should accept the -text option and is typically a Label. If the widget accepts the -textvariable option and that option is defined then it is used instead of the -text option.

-balloonposition

Can be one of 'widget' or 'mouse'. It controls where the balloon will popup. 'widget' makes the balloon appear at the lower right corner of the widget it is attached to (default), and 'mouse' makes the balloon appear below and to the right of the current mouse position.

-postcommand

This option takes a CODE reference which will be executed before the balloon and statusbar messages are displayed and should return a true or false value to indicate whether you want the balloon to be displayed or not. This also lets you control where the balloon is positioned by returning a true value that looks like X,Y (matches this regular expression: /^(\d+),(\d+)$/). If the postcommand returns a value that matches that re then those coordinates will be used as the position to post the balloon. Warning: this subroutine should return quickly or the balloon response will appear slow.

-cancelcommand

This option takes a CODE reference which will be executed before the balloon and statusbar messages are canceled and should return a true or false value to indicate whether you want the balloon to be canceled or not. Warning: this subroutine should return quickly or the balloon response will appear slow.

-motioncommand

This option takes a CODE reference which will be executed for any motion event and should return a true or false value to indicate whether the currently displayed balloon should be canceled (deactivated). If it returns true then the balloon will definitely be canceled, if it returns false then it may still be canceled depending the internal rules. Note: a new balloon may be posted after the -initwait time interval, use the -postcommand option to control that behavior. Warning: the subroutine should be extremely fast or the balloon response will appear slow and consume a lot of CPU time (it is executed every time the mouse moves over the widgets the balloon is attached to).

-numscreens

This option accepts an integer 1 or greater. This option should be used to avoid disjointed balloons across multiple screens in single logical sceen (SLS) mode. This only currently works in the horizontal direction. Example: If you are running dual screens in SLS mode then you would set this value to 2. Default value is 1.

METHODS

The Balloon widget supports only three non-standard methods:

attach(widget, options)

Attaches the widget indicated by widget to the help system. The allowed options are:

-statusmsg

The argument is the message to be shown on the status bar when the mouse pauses over this client. If this is not specified, but -msg is specified then the message displayed on the status bar is the same as the argument for -msg. If you give it a scalar reference then it is dereferenced before being displayed. Useful if the postcommand is used to change the message.

-balloonmsg

The argument is the message to be displayed in the balloon that will be popped up when the mouse pauses over this client. As with -statusmsg if this is not specified, then it takes its value from the -msg specification if any. If neither -balloonmsg nor -msg are specified, or they are the empty string then no balloon is popped up instead of an empty balloon. If you give it a scalar reference then it is dereferenced before being displayed. Useful if the postcommand is used to change the message.

-msg

The catch-all for -statusmsg and -balloonmsg. This is a convenient way of specifying the same message to be displayed in both the balloon and the status bar for the client.

-initwait
-state
-statusbar
-balloonposition
-postcommand
-cancelcommand
-motioncommand

These options allow you to override the balloon's default value for those option for some of the widgets it is attached to. It accepts the same values as above and will default to the Balloon's value.

detach(widget)

Detaches the specified widget from the help system.

destroy

Destroys the specified balloon.

ADVERTISED SUBWIDGETS

The balloon label is advertised as message.

EXAMPLES

See the balloon demo included with the widget demo script that came with the distribution for examples on various ways to use balloons.

NOTES

Because of the overhead associated with each balloon you create (from tracking the mouse movement to know when to activate and deactivate them) you will see the best performance (low CPU consumption) if you create as few balloons as possible and attach them to as many widgets as you can. In other words, don't create a balloon for each widget you want to attach one to.

CAVEATS

Pressing any button will deactivate (cancel) the current balloon, if one exists. You can usually make the balloon reappear by moving the mouse a little. Creative use of the 3 command options can help you out also. If the mouse is over the balloon when a menu is unposted then the balloon will remain until you move off of it.

BUGS

If using balloons attached to listbox entries or canvas items in a scrolled widget, then the subwidget have to be used:

    $balloon->attach($w->Subwidget("scrolled"), -msg => ...);

AUTHORS

Rajappa Iyer rsi@earthling.net did the original coding.

Jason A. Smith <smithj4@rpi.edu> added support for menus and made some other enhancements.

Slaven Rezic <eserte@cs.tu-berlin.de> added support for canvas items.

Gerhard Petrowitsch <gerhard@petrowitsch.de> added intelligent positioning

Jack Dunnigan <dunniganj@cpan.org> Made positioning more intelligent and added support for multiple monitors under single logical screen.

HISTORY

The code and documentation was derived from Balloon.tcl from the Tix4.0 distribution by Ioi Lam and modified by the above mentioned authors. This code may be redistributed under the same terms as Perl.


Tk::Bitmap - Images that display two colors

  • CREATING BITMAPS
  • IMAGE METHODS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Bitmap - Images that display two colors

SYNOPSIS

$image = $widget->Bitmap?(name??,options?)

DESCRIPTION

A bitmap is an image whose pixels can display either of two colors or be transparent. A bitmap image is defined by four things: a background color, a foreground color, and two bitmaps, called the source and the mask. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero.

CREATING BITMAPS

Bitmaps are created using $widget->Bitmap. Bitmaps support the following options:

-background => color

Specifies a background color for the image in any of the standard ways accepted by Tk. If this option is set to an empty string then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any -maskdata or -maskfile options.

-data => string

Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program). If both the -data and -file options are specified, the -data option takes precedence.

-file => name

name gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

-foreground => color

Specifies a foreground color for the image in any of the standard ways accepted by Tk.

-maskdata => string

Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program). If both the -maskdata and -maskfile options are specified, the -maskdata option takes precedence.

-maskfile => name

name gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

IMAGE METHODS

When a bitmap image is created, Tk also creates a new object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above.

SEE ALSO

Tk::Image
Tk::Pixmap
Tk::Photo

KEYWORDS

bitmap, image


Tk::BrowseEntry - entry widget with popup choices.

  • SUPER-CLASS
  • DESCRIPTION
  • METHODS
  • ADVERTISED WIDGETS
  • SUBCLASSING
  • BUGS
  • AUTHOR

NAME

Tk::BrowseEntry - entry widget with popup choices.

SYNOPSIS

    use Tk::BrowseEntry;

    $b = $frame->BrowseEntry(-label => "Label", -variable => \$var);
    $b->insert("end", "opt1");
    $b->insert("end", "opt2");
    $b->insert("end", "opt3");
    ...
    $b->pack;

SUPER-CLASS

The BrowseEntry class is derived from the Frame class and inherits all the methods, options and subwidgets of its super-class. By default, options and methods are delegated to the entry subwidget.

DESCRIPTION

BrowseEntry is a poor man's ComboBox. It may be considered an enhanced version of LabEntry which provides a button to popup the choices of the possible values that the Entry may take. BrowseEntry supports all the options LabEntry supports except -textvariable. This is replaced by -variable. Other options that BrowseEntry supports:

-arrowimage

Specifies the image to be used in the arrow button beside the entry widget. The default is an downward arrow image in the file cbxarrow.xbm

-autolimitheight

If set to a true value, then the height of the listbox will be at most the number of entries in the list. The overall maximum of -listheight still applies.

-autolistwidth

If set to a true value, then the width of the listbox will match the width of the largest entry.

-browsecmd

Specifies a function to call when a selection is made in the popped up listbox. It is passed the widget and the text of the entry selected. This function is called after the entry variable has been assigned the value.

-browse2cmd

Like -browsecmd, but the callback is called with the listbox index instead of the selected value.

-buttontakefocus

Set the -takefocus option of the button subwidget.

-choices

Specifies the list of choices to pop up. This is a reference to an array of strings specifying the choices.

-colorstate

The state of the widget is reflected by color. A non-editable entry widget will get a light gray background, while an editable entry will be almost white. [This may change]

-listcmd

Specifies the function to call when the button next to the entry is pressed to popup the choices in the listbox. This is called before popping up the listbox, so can be used to populate the entries in the listbox.

-listheight

Set the height of the listbox. See also -autolimitheight.

-listwidth

Specifies the width of the popup listbox.

-state

Specifies one of three states for the widget: normal, readonly, or disabled. If the widget is disabled then the value may not be changed and the arrow button won't activate. If the widget is readonly, the entry may not be edited, but it may be changed by choosing a value from the popup listbox. normal is the default.

-style

Set the "style" of the widget. Permitted values are MSWin32 and unix. By default -style is set to the current platform. Widgets with the unix style will look like a normal BrowseEntry widget, whereas with the MSWin32 style the arrow will look close to the Windows' standard combobox widget, while moving the mouse the entries will be highlighted, and probably includes other changes.

-variable

Specifies the variable in which the entered value is to be stored.

METHODS

insert(index, string)

Inserts the text of string at the specified index. This string then becomes available as one of the choices.

delete(index1, index2)

Deletes items from index1 to index2.

get

The get method is delegated to the choices listbox.

ADVERTISED WIDGETS

The following widgets are advertised:

entry

The entry widget.

arrow

The button with the arrow image.

choices

The toplevel widget containing the choice listbox.

slistbox

The scrolled listbox with the choices.

SUBCLASSING

To make subclassing easier, the following methods may be overridden to use other standard widgets in composing the mega widget:

LabEntryWidget

A widget class compatible with Tk::LabEntry used for the entry.

ButtonWidget

A widget class compatible with Tk::Button used for the arrow button.

ListboxWidget

A widget class compatible with Tk::Listbox used for the choices listbox.

For example to use a NumEntry widget (from the Tk-GBARR CPAN distribution) instead of the normal Entry widget:

    package Tk::NumBrowseEntry;
    use base qw(Tk::BrowseEntry);
    use Tk::NumEntry;
    Construct Tk::Widget 'NumBrowseEntry';
    sub LabEntryWidget { "NumEntry" }

BUGS

BrowseEntry should really provide more of the ComboBox options.

AUTHOR

Rajappa Iyer rsi@earthling.net

Chris Dean ctdean@cogit.com made additions.

More additions by Slaven Rezic slaven@rezic.de

This code was inspired by ComboBox.tcl in Tix4.0 by Ioi Lam and bears more than a passing resemblance to ComboBox code. This may be distributed under the same conditions as Perl.


Tk::Button - Create and manipulate Button widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • KEYWORDS

NAME

Tk::Button - Create and manipulate Button widgets

SYNOPSIS

$button = $parent->Button(?options?);

STANDARD OPTIONS

-activebackground | -cursor | -highlightthickness | -takefocus
-activeforeground | -disabledforeground | -image | -text
-anchor | -font | -justify | -textvariable
-background | -foreground | -padx | -underline
-bitmap | -highlightbackground | -pady | -wraplength
-borderwidth | -highlightcolor | -relief

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: command
Class: Command
Switch: -command

Specifies a Perl/Tk callback to associate with the button. This command is typically invoked when mouse button 1 is released over the button window.

Command-Line Name: -compound
Database Name: compound
Database Class: Compound

Specifies whether the button should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are bottom, center, left, none, right and top. The default value is none, meaning that the button will display either an image or text, depending on the values of the -image and -bitmap options.

Name: default
Class: Default
Switch: -default

Specifies one of three states for the default ring: normal, active, or disabled. In active state, the button is drawn with the platform specific appearance for a default button. In normal state, the button is drawn with the platform specific appearance for a non-default button, leaving enough space to draw the default button appearance. The normal and active states will result in buttons of the same size. In disabled state, the button is drawn with the non-default button appearance without leaving space for the default appearance. The disabled state may result in a smaller button than the active state. ring.

Name: height
Class: Height
Switch: -height

Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in lines of text. If this option isn't specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it.

Command-Line Name: -overrelief
Database Name: overRelief
Database Class: OverRelief

Specifies an alternative relief for the button, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring -relief flat -overrelief raised. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the button. The empty string is the default value.

Name: state
Class: State
Switch: -state

Specifies one of three states for the button: normal, active, or disabled. In normal state the button is displayed using the foreground and background options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the activeForeground and activeBackground options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledForeground and background options determine how the button is displayed.

Name: width
Class: Width
Switch: -width

Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in characters. If this option isn't specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it.

DESCRIPTION

The Button method creates a new window (given by the $widget argument) and makes it into a button widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the button such as its colors, font, text, and initial relief. The button command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A button is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the -wraplength option) and one of the characters may optionally be underlined using the -underline option. It can display itself in either of three different ways, according to the -state option; it can be made to appear raised, sunken, or flat; and it can be made to flash. When a user invokes the button (by pressing mouse button 1 with the cursor over the button), then the perl/Tk callback specified in the -command option is invoked.

WIDGET METHODS

The Button method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for button widgets:

$button->flash

Flash the button. This is accomplished by redisplaying the button several times, alternating between active and normal colors. At the end of the flash the button is left in the same normal/active state as when the command was invoked. This command is ignored if the button's state is disabled.

$button->invoke

Invoke the callback associated with the buttons -command option, if there is one. The return value is the return value from the callback, or the undefined value if there is no callback associated with the button. This command is ignored if the button's state is disabled.

DEFAULT BINDINGS

Tk automatically creates class bindings for buttons that give them default behavior:

[1]

A button activates whenever the mouse passes over it and deactivates whenever the mouse leaves the button. Under Windows, this binding is only active when mouse button 1 has been pressed over the button.

[2]

A button's relief is changed to sunken whenever mouse button 1 is pressed over the button, and the relief is restored to its original value when button 1 is later released.

[3]

If mouse button 1 is pressed over a button and later released over the button, the button is invoked. However, if the mouse is not over the button when button 1 is released, then no invocation occurs.

[4]

When a button has the input focus, the space key causes the button to be invoked.

If the button's state is disabled then none of the above actions occur: the button is completely non-responsive.

The behavior of buttons can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

button, widget


Tk::Canvas - Create and manipulate Canvas widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • DISPLAY LIST
  • ITEM IDS AND TAGS
  • COORDINATES
  • TRANSFORMATIONS
  • INDICES
  • DASH PATTERNS
  • WIDGET METHODS
  • OVERVIEW OF ITEM TYPES
  • ARC ITEMS
  • BITMAP ITEMS
  • GRID ITEMS
  • IMAGE ITEMS
  • LINE ITEMS
  • OVAL ITEMS
  • POLYGON ITEMS
  • RECTANGLE ITEMS
  • TEXT ITEMS
  • WINDOW ITEMS
  • APPLICATION-DEFINED ITEM TYPES
  • BINDINGS
  • Perl/Tk Methods
  • CREDITS
  • KEYWORDS

NAME

Tk::Canvas - Create and manipulate Canvas widgets

SYNOPSIS

$canvas = $parent->Canvas(?options?);

STANDARD OPTIONS

-background | -highlightthickness | -insertwidth | -state
-borderwidth | -insertbackground | -relief | -tile
-cursor | -insertborderwidth | -selectbackground | -takefocus
-highlightbackground | -insertofftime | -selectborderwidth | -xscrollcommand
-highlightcolor | -insertontime | -selectforeground | -yscrollcommand

WIDGET-SPECIFIC OPTIONS

Name: closeEnough
Class: CloseEnough
Switch: -closeenough

Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be ``inside'' the item. Defaults to 1.0.

Name: confine
Class: Confine
Switch: -confine

Specifies a boolean value that indicates whether or not it should be allowable to set the canvas's view outside the region defined by the scrollRegion argument. Defaults to true, which means that the view will be constrained within the scroll region.

Name: height
Class: Height
Switch: -height

Specifies a desired window height that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATES section below.

Name: scrollRegion
Class: ScrollRegion
Switch: -scrollregion

Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the canvas. Each of the coordinates may be specified in any of the forms given in the COORDINATES section below.

Name: state
Class: State
Switch: -state

Modifies the default state of the canvas where state may be set to one of: normal, disabled, or hidden. Individual canvas objects all have their own state option, which overrides the default state. Many options can take separate specifications such that the appearance of the item can be different in different situations. The options that start with "active" control the appearence when the mouse pointer is over it, while the option starting with "disabled" controls the appearence when the state is disabled.

Name: width
Class: width
Switch: -width

Specifies a desired window width that the canvas widget should request from its geometry manager. The value may be specified in any of the forms described in the COORDINATES section below.

Name: xScrollIncrement
Class: ScrollIncrement
Switch: -xscrollincrement

Specifies an increment for horizontal scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the canvas x coordinate at the left edge of the window is always an even multiple of xScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be xScrollIncrement. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained.

Name: yScrollIncrement
Class: ScrollIncrement
Switch: -yscrollincrement

Specifies an increment for vertical scrolling, in any of the usual forms permitted for screen distances. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the canvas y coordinate at the top edge of the window is always an even multiple of yScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be yScrollIncrement. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained.

DESCRIPTION

The Canvas method creates a new window (given by the $canvas argument) and makes it into a canvas widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the canvas such as its colors and 3-D relief. The canvas command returns its $canvas argument. At the time this command is invoked, there must not exist a window named $canvas, but $canvas's parent must exist.

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be things like rectangles, circles, lines, and text. Items may be manipulated (e.g. moved or re-colored) and callbacks may be associated with items in much the same way that the bind method allows callbacks to be bound to widgets. For example, a particular callback may be associated with the <Button-1> event so that the callback is invoked whenever button 1 is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Callbacks bound to them.

DISPLAY LIST

The items in a canvas are ordered for purposes of display, with the first item in the display list being displayed first, followed by the next item in the list, and so on. Items later in the display list obscure those that are earlier in the display list and are sometimes referred to as being ``on top'' of earlier items. When a new item is created it is placed at the end of the display list, on top of everything else. Widget methods may be used to re-arrange the order of the display list.

Window items are an exception to the above rules. The underlying window systems require them always to be drawn on top of other items. In addition, the stacking order of window items is not affected by any of the canvas methods; you must use the raise and lower Tk widget methods instead.

ITEM IDS AND TAGS

Items in a canvas widget may be named in either of two ways: by id or by tag. Each item has a unique identifying number which is assigned to that item when it is created. The id of an item never changes and id numbers are never re-used within the lifetime of a canvas widget.

Each item may also have any number of tags associated with it. A tag is just a string of characters, and it may take any form except that of an integer. For example, ``x123'' is OK but ``123'' isn't. The same tag may be associated with many different items. This is commonly done to group items in various interesting ways; for example, all selected items might be given the tag ``selected''.

The tag all is implicitly associated with every item in the canvas; it may be used to invoke operations on all the items in the canvas.

The tag current is managed automatically by Tk; it applies to the current item, which is the topmost item whose drawn area covers the position of the mouse cursor. If the mouse is not in the canvas widget or is not over an item, then no item has the current tag.

When specifying items in canvas methods, if the specifier is an integer then it is assumed to refer to the single item with that id. If the specifier is not an integer, then it is assumed to refer to all of the items in the canvas that have a tag matching the specifier. The symbol tagOrId is used below to indicate that an argument specifies either an id that selects a single item or a tag that selects zero or more items.

tagOrId may contain a logical expressions of tags by using operators: '&&', '||', '^' '!', and parenthezised subexpressions. For example:

$c->find('withtag', '(a&&!b)|(!a&&b)');

or equivalently:

$c->find('withtag', 'a^b');

will find only those items with either "a" or "b" tags, but not both.

Some methods only operate on a single item at a time; if tagOrId is specified in a way that names multiple items, then the normal behavior is for the methods is to use the first (lowest) of these items in the display list that is suitable for the method. Exceptions are noted in the method descriptions below.

COORDINATES

All coordinates related to canvases are stored as floating-point numbers. Coordinates and distances are specified in screen units, which are floating-point numbers optionally followed by one of several letters. If no letter is supplied then the distance is in pixels. If the letter is m then the distance is in millimeters on the screen; if it is c then the distance is in centimeters; i means inches, and p means printers points (1/72 inch). Larger y-coordinates refer to points lower on the screen; larger x-coordinates refer to points farther to the right.

TRANSFORMATIONS

Normally the origin of the canvas coordinate system is at the upper-left corner of the window containing the canvas. It is possible to adjust the origin of the canvas coordinate system relative to the origin of the window using the xview and yview methods; this is typically used for scrolling. Canvases do not support scaling or rotation of the canvas coordinate system relative to the window coordinate system.

Individual items may be moved or scaled using methods described below, but they may not be rotated.

INDICES

Text items support the notion of an index for identifying particular positions within the item.

Indices are used for methods such as inserting text, deleting a range of characters, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices.

In a similar fashion, line and polygon items support index for identifying, inserting and deleting subsets of their coordinates. Indices are used for commands such as inserting or deleting a range of characters or coordinates, and setting the insertion cursor position. An index may be specified in any of a number of ways, and different types of items may support different forms for specifying indices.

Text items support the following forms for an index; if you define new types of text-like items, it would be advisable to support as many of these forms as practical. Note that it is possible to refer to the character just after the last one in the text item; this is necessary for such tasks as inserting new text at the end of the item. Lines and Polygons don't support the insertion cursor and the selection. Their indices are supposed to be even always, because coordinates always appear in pairs.

number

A decimal number giving the position of the desired character within the text item. 0 refers to the first character, 1 to the next character, and so on. If indexes are odd for lines and polygons, they will be automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For polygons, numbers less than 0 or greater then the length of the coordinate list will be adjusted by adding or substracting the length until the result is between zero and the length, inclusive.

end

Refers to the character or coordinate just after the last one in the item (same as the number of characters or coordinates in the item).

insert

Refers to the character just before which the insertion cursor is drawn in this item. Not valid for lines and polygons.

sel.first

Refers to the first selected character in the item. If the selection isn't in this item then this form is illegal.

sel.last

Refers to the last selected character in the item. If the selection isn't in this item then this form is illegal.

[x,y]

Refers to the character or coordinate at the point given by x and y, where x and y are specified in the coordinate system of the canvas. If x and y lie outside the coordinates covered by the text item, then they refer to the first or last character in the line that is closest to the given point. The Tcl string form "@x,y" is also allowed.

DASH PATTERNS

Many items support the notion of an dash pattern for outlines.

The first possible syntax is a list of integers. Each element represents the number of pixels of a line segment. Only the odd segments are drawn using the "outline" color. The other segments are drawn transparant.

The second possible syntax is a character list containing only 5 possible characters [.,-_ ]. The space can be used to enlarge the space between other line elements, and can not occur as the first position in the string. Some examples:

 -dash .     = -dash [2,4]
 -dash -     = -dash [6,4]
 -dash -.    = -dash [6,4,2,4]
 -dash -..   = -dash [6,4,2,4,2,4]
 -dash '. '  = -dash [2,8]
 -dash ','   = -dash [4,4]

The main difference of this syntax with the previous is that it it shape-conserving. This means that all values in the dash list will be multiplied by the line width before display. This assures that "." will always be displayed as a dot and "-" always as a dash regardless of the line width.

On systems where only a limited set of dash patterns, the dash pattern will be displayed as the most close dash pattern that is available. For example, on Windows only the first 4 of the above examples are available. The last 2 examples will be displayed identically as the first one.

WIDGET METHODS

The Canvas method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for canvas widgets:

$canvas->addtag(tag, searchSpec, ?arg, arg, ...?)

For each item that meets the constraints specified by searchSpec and the args, add tag to the list of tags associated with the item if it isn't already present on that list. It is possible that no items will satisfy the constraints given by searchSpec and args, in which case the method has no effect. This command returns an empty string as result. SearchSpec and arg's may take any of the following forms:

above tagOrId

Selects the item just after (above) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the last (topmost) of these items in the display list is used.

all

Selects all the items in the canvas.

below tagOrId

Selects the item just before (below) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the first (lowest) of these items in the display list is used.

closest x y ?halo? ?start?

Selects the item closest to the point given by x and y. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If halo is specified, then it must be a non-negative value. Any item closer than halo to the point is considered to overlap it. The start argument may be used to step circularly through all the closest items. If start is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below start in the display list; if no such item exists, then the selection behaves as if the start argument had not been specified.

enclosed x1 y1 x2 y2

Selects all the items completely enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.

overlapping x1 y1 x2 y2

Selects all the items that overlap or are enclosed within the rectangular region given by x1, y1, x2, and y2. X1 must be no greater then x2 and y1 must be no greater than y2.

withtag tagOrId

Selects all the items given by tagOrId.

$canvas->bbox(tagOrId, ?tagOrId, tagOrId, ...?)

Returns a list with four elements giving an approximate bounding box for all the items named by the tagOrId arguments. The list has the form ``x1 y1 x2 y2'' such that the drawn areas of all the named elements are within the region bounded by x1 on the left, x2 on the right, y1 on the top, and y2 on the bottom. The return value may overestimate the actual bounding box by a few pixels. If no items match any of the tagOrId arguments or if the matching items have empty bounding boxes (i.e. they have nothing to display) then an empty string is returned.

$canvas->bind(tagOrId?, sequence? ?,callback?)

This method associates callback with all the items given by tagOrId such that whenever the event sequence given by sequence occurs for one of the items the callback will be invoked. This method is similar to the bind method except that it operates on items in a canvas rather than entire widgets. See the Tk::bind manpage for complete details on the syntax of sequence and the substitutions performed on callback before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagOrId (if the first character of command is ``+'' then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If callback is omitted then the method returns the callback associated with tagOrId and sequence (an error occurs if there is no such binding). If both callback and sequence are omitted then the method returns a list of all the sequences for which bindings have been defined for tagOrId.

The only events for which bindings may be specified are those related to the mouse and keyboard (such as Enter, Leave, ButtonPress, Motion, and KeyPress) or virtual events. The handling of events in canvases uses the current item defined in ITEM IDS AND TAGS above. Enter and Leave events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than Enter and Leave events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the focus method below for more on this). If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event.

It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the item's id and another is associated with one of the item's tags. When this occurs, all of the matching bindings are invoked. A binding associated with the all tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. A continue in a callback terminates that subroutine, and a break method terminates that subroutine and skips any remaining callbacks for the event, just as for the bind method.

If bindings have been created for a canvas window using the CanvasBind method, then they are invoked in addition to bindings created for the canvas's items using the bind method. The bindings for items will be invoked before any of the bindings for the window as a whole.

$canvas->canvasx(screenx?, gridspacing?)

Given a window x-coordinate in the canvas screenx, this method returns the canvas x-coordinate that is displayed at that location. If gridspacing is specified, then the canvas coordinate is rounded to the nearest multiple of gridspacing units.

$canvas->canvasy(screeny, ?gridspacing?)

Given a window y-coordinate in the canvas screeny this method returns the canvas y-coordinate that is displayed at that location. If gridspacing is specified, then the canvas coordinate is rounded to the nearest multiple of gridspacing units.

$canvas->coords(tagOrId ?x0,y0 ...?)

Query or modify the coordinates that define an item. If no coordinates are specified, this method returns a list whose elements are the coordinates of the item named by tagOrId. If coordinates are specified, then they replace the current coordinates for the named item. If tagOrId refers to multiple items, then the first one in the display list is used.

$canvas->create(type, x, y, ?x, y, ...?, ?option, value, ...?)

Create a new item in $canvas of type type. The exact format of the arguments after type depends on type, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the subsections on individual item types below for more on the syntax of this method. This method returns the id for the new item.

$canvas->dchars(tagOrId, first, ?last?)

For each item given by tagOrId, delete the characters, or coordinates, in the range given by first and last, inclusive. If some of the items given by tagOrId don't support Text items interpret first and last as indices to a character, line and polygon items interpret them indices to a coordinate (an x,y pair). within the item(s) as described in INDICES above. If last is omitted, it defaults to first. This method returns an empty string.

$canvas->delete(?tagOrId, tagOrId, ...?)

Delete each of the items given by each tagOrId, and return an empty string.

$canvas->dtag(tagOrId, ?tagToDelete?)

For each of the items given by tagOrId, delete the tag given by tagToDelete from the list of those associated with the item. If an item doesn't have the tag tagToDelete then the item is unaffected by the method. If tagToDelete is omitted then it defaults to tagOrId. This method returns an empty string.

$canvas->find(searchCommand, ?arg, arg, ...?)

This method returns a list consisting of all the items that meet the constraints specified by searchCommand and arg's. SearchCommand and args have any of the forms accepted by the addtag method. The items are returned in stacking order, with the lowest item first.

focus
$canvas->focus(?tagOrId?)

Set the keyboard focus for the canvas widget to the item given by tagOrId. If tagOrId refers to several items, then the focus is set to the first such item in the display list that supports the insertion cursor. If tagOrId doesn't refer to any items, or if none of them support the insertion cursor, then the focus isn't changed. If tagOrId is an empty string, then the focus item is reset so that no item has the focus. If tagOrId is not specified then the method returns the id for the item that currently has the focus, or an empty string if no item has the focus.

Once the focus has been set to an item, the item will display the insertion cursor and all keyboard events will be directed to that item. The focus item within a canvas and the focus window on the screen (set with the focus method) are totally independent: a given item doesn't actually have the input focus unless (a) its canvas is the focus window and (b) the item is the focus item within the canvas. In most cases it is advisable to follow the focus widget method with the CanvasFocus method to set the focus window to the canvas (if it wasn't there already).

$canvas->gettags(tagOrId)

Return a list whose elements are the tags associated with the item given by tagOrId. If tagOrId refers to more than one item, then the tags are returned from the first such item in the display list. If tagOrId doesn't refer to any items, or if the item contains no tags, then an empty string is returned.

$canvas->icursor(tagOrId, index)

Set the position of the insertion cursor for the item(s) given by tagOrId to just before the character whose position is given by index. If some or all of the items given by tagOrId don't support an insertion cursor then this method has no effect on them. See INDICES above for a description of the legal forms for index. Note: the insertion cursor is only displayed in an item if that item currently has the keyboard focus (see the widget method focus, below), but the cursor position may be set even when the item doesn't have the focus. This method returns an empty string.

$canvas->index(tagOrId, index)

This method returns a decimal string giving the numerical index within tagOrId corresponding to index. Index gives a textual description of the desired position as described in INDICES above. Text items interpret index as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). The return value is guaranteed to lie between 0 and the number of characters, or coordinates, within the item, inclusive. If tagOrId refers to multiple items, then the index is processed in the first of these items that supports indexing operations (in display list order).

$canvas->insert(tagOrId, beforeThis, string)

For each of the items given by tagOrId, if the item supports text or coordinate, insertion then string is inserted into the item's text just before the character, or coordinate, whose index is beforeThis. Text items interpret beforethis as an index to a character, line and polygon items interpret it as an index to a coordinate (an x,y pair). For lines and polygons the string must be a valid coordinate sequence. See INDICES above for information about the forms allowed for beforeThis. This method returns an empty string.

$canvas->itemcget(tagOrId, option)

Returns the current value of the configuration option for the item given by tagOrId whose name is option. This method is similar to the cget method except that it applies to a particular item rather than the widget as a whole. Option may have any of the values accepted by the create method when the item was created. If tagOrId is a tag that refers to more than one item, the first (lowest) such item is used.

$canvas->itemconfigure(tagOrId, ?option?, ?value?, ?option, value, ...?)

This method is similar to the configure method except that it modifies item-specific options for the items given by tagOrId instead of modifying options for the overall canvas widget. If no option is specified, returns a list describing all of the available options for the first item given by tagOrId (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the method modifies the given widget option(s) to have the given value(s) in each of the items given by tagOrId; in this case the method returns an empty string. The options and values are the same as those permissible in the create method when the item(s) were created; see the sections describing individual item types below for details on the legal options.

$canvas->lower(tagOrId, ?belowThis?)

Move all of the items given by tagOrId to a new position in the display list just before the item given by belowThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. BelowThis is a tag or id; if it refers to more than one item then the first (lowest) of these items in the display list is used as the destination location for the moved items. Note: this method has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the raise and lower methods of the widget, not the raise and lower methods for canvases. This method returns an empty string.

$canvas->move(tagOrId, xAmount, yAmount)

Move each of the items given by tagOrId in the canvas coordinate space by adding xAmount to the x-coordinate of each point associated with the item and yAmount to the y-coordinate of each point associated with the item. This method returns an empty string.

$canvas->postscript(?option, value, option, value, ...?)

Generate a Postscript representation for part or all of the canvas. If the -file option is specified then the Postscript is written to a file and an empty string is returned; otherwise the Postscript is returned as the result of the method. If the interpreter that owns the canvas is marked as safe, the operation will fail because safe interpreters are not allowed to write files. If the -channel option is specified, the argument denotes the name of a channel already opened for writing. The Postscript is written to that channel, and the channel is left open for further writing at the end of the operation. The Postscript is created in Encapsulated Postscript form using version 3.0 of the Document Structuring Conventions. Note: by default Postscript is only generated for information that appears in the canvas's window on the screen. If the canvas is freshly created it may still have its initial size of 1x1 pixel so nothing will appear in the Postscript. To get around this problem either invoke the update method to wait for the canvas window to reach its final size, or else use the -width and -height options to specify the area of the canvas to print. The option-value argument pairs provide additional information to control the generation of Postscript. The following options are supported:

-colormap => hashRef

HashRef must be a reference to a hash variable or an anonymous hash that specifies a color mapping to use in the Postscript. Each value of the hash must consist of Postscript code to set a particular color value (e.g. ``1.0 1.0 0.0 setrgbcolor''). When outputting color information in the Postscript, Tk checks to see if there is a key in the hash with the same name as the color. If so, Tk uses the value of the element as the Postscript method to set the color. If this option hasn't been specified, or if there isn't a key in hashRef for a given color, then Tk uses the red, green, and blue intensities from the X color.

-colormode => mode

Specifies how to output color information. Mode must be either color (for full color output), gray (convert all colors to their gray-scale equivalents) or mono (convert all colors to black or white).

-file => fileName

Specifies the name of the file in which to write the Postscript. If this option isn't specified then the Postscript is returned as the result of the method instead of being written to a file.

-fontmap => hashRef

HashRef must be a reference to a hash variable or an anonymous hash that specifies a font mapping to use in the Postscript. Each value of the hash must consist of an array reference with two elements, which are the name and point size of a Postscript font. When outputting Postscript commands for a particular font, Tk checks to see if hashRef contains a value with the same name as the font. If there is such an element, then the font information contained in that element is used in the Postscript. Otherwise Tk attempts to guess what Postscript font to use. Tk's guesses generally only work for well-known fonts such as Times and Helvetica and Courier, and only if the X font name does not omit any dashes up through the point size. For example, -*-Courier-Bold-R-Normal--*-120-* will work but *Courier-Bold-R-Normal*120* will not; Tk needs the dashes to parse the font name).

-height => size

Specifies the height of the area of the canvas to print. Defaults to the height of the canvas window.

-pageanchor => anchor

Specifies which point of the printed area of the canvas should appear over the positioning point on the page (which is given by the -pagex and -pagey options). For example, -pageanchor=>n means that the top center of the area of the canvas being printed (as it appears in the canvas window) should be over the positioning point. Defaults to center.

-pageheight => size

Specifies that the Postscript should be scaled in both x and y so that the printed area is size high on the Postscript page. Size consists of a floating-point number followed by c for centimeters, i for inches, m for millimeters, or p or nothing for printer's points (1/72 inch). Defaults to the height of the printed area on the screen. If both -pageheight and -pagewidth are specified then the scale factor from -pagewidth is used (non-uniform scaling is not implemented).

-pagewidth => size

Specifies that the Postscript should be scaled in both x and y so that the printed area is size wide on the Postscript page. Size has the same form as for -pageheight. Defaults to the width of the printed area on the screen. If both -pageheight and -pagewidth are specified then the scale factor from -pagewidth is used (non-uniform scaling is not implemented).

-pagex => position

Position gives the x-coordinate of the positioning point on the Postscript page, using any of the forms allowed for -pageheight. Used in conjunction with the -pagey and -pageanchor options to determine where the printed area appears on the Postscript page. Defaults to the center of the page.

-pagey => position

Position gives the y-coordinate of the positioning point on the Postscript page, using any of the forms allowed for -pageheight. Used in conjunction with the -pagex and -pageanchor options to determine where the printed area appears on the Postscript page. Defaults to the center of the page.

-rotate => boolean

Boolean specifies whether the printed area is to be rotated 90 degrees. In non-rotated output the x-axis of the printed area runs along the short dimension of the page (``portrait'' orientation); in rotated output the x-axis runs along the long dimension of the page (``landscape'' orientation). Defaults to non-rotated.

-width => size

Specifies the width of the area of the canvas to print. Defaults to the width of the canvas window.

-x => position

Specifies the x-coordinate of the left edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the left edge of the window.

-y => position

Specifies the y-coordinate of the top edge of the area of the canvas that is to be printed, in canvas coordinates, not window coordinates. Defaults to the coordinate of the top edge of the window.

$canvas->raise(tagOrId, ?aboveThis?)

Move all of the items given by tagOrId to a new position in the display list just after the item given by aboveThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. AboveThis is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. Note: this method has no effect on window items. Window items always obscure other item types, and the stacking order of window items is determined by the raise and lower widget commands, not the raise and lower methods for canvases. This method returns an empty string.

$canvas->scale(tagOrId, xOrigin, yOrigin, xScale, yScale)

Rescale all of the items given by tagOrId in canvas coordinate space. XOrigin and yOrigin identify the origin for the scaling operation and xScale and yScale identify the scale factors for x- and y-coordinates, respectively (a scale factor of 1.0 implies no change to that coordinate). For each of the points defining each item, the x-coordinate is adjusted to change the distance from xOrigin by a factor of xScale. Similarly, each y-coordinate is adjusted to change the distance from yOrigin by a factor of yScale. This method returns an empty string.

$canvas->scan(option, args)

This method is used to implement scanning on canvases. It has two forms, depending on option:

$canvas->scanMark(x, y)

Records x and y and the canvas's current view; used in conjunction with later scanDragto method. Typically this method is associated with a mouse button press in the widget and x and y are the coordinates of the mouse. It returns an empty string.

$canvas->scanDragto(x, y, ?gain?.)

This method computes the difference between its x and y arguments (which are typically mouse coordinates) and the x and y arguments to the last scanMark method for the widget. It then adjusts the view by 10 times the difference in coordinates. This method is typically associated It then adjusts the view by gain times the difference in coordinates, where gain defaults to 10. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the canvas at high speed through its window. The return value is an empty string.

$canvas->select(option, ?tagOrId, arg?)

Manipulates the selection in one of several ways, depending on option. The method may take any of the forms described below. In all of the descriptions below, tagOrId must refer to an item that supports indexing and selection; if it refers to multiple items then the first of these that supports indexing and the selection is used. Index gives a textual description of a position within tagOrId, as described in INDICES above.

$canvas->selectAdjust(tagOrId, index)

Locate the end of the selection in tagOrId nearest to the character given by index, and adjust that end of the selection to be at index (i.e. including but not going beyond index). The other end of the selection is made the anchor point for future selectTo method calls. If the selection isn't currently in tagOrId then this method behaves the same as the selectTo widget method. Returns an empty string.

$canvas->selectClear

Clear the selection if it is in this widget. If the selection isn't in this widget then the method has no effect. Returns an empty string.

$canvas->selectFrom(tagOrId, index)

Set the selection anchor point for the widget to be just before the character given by index in the item given by tagOrId. This method doesn't change the selection; it just sets the fixed end of the selection for future selectTo method calls. Returns an empty string.

$canvas->selectItem

Returns the id of the selected item, if the selection is in an item in this canvas. If the selection is not in this canvas then an empty string is returned.

$canvas->selectTo(tagOrId, index)

Set the selection to consist of those characters of tagOrId between the selection anchor point and index. The new selection will include the character given by index; it will include the character given by the anchor point only if index is greater than or equal to the anchor point. The anchor point is determined by the most recent selectAdjust or selectFrom method calls for this widget. If the selection anchor point for the widget isn't currently in tagOrId, then it is set to the same character given by index. Returns an empty string.

$canvas->type(tagOrId)

Returns the type of the item given by tagOrId, such as rectangle or text. If tagOrId refers to more than one item, then the type of the first item in the display list is returned. If tagOrId doesn't refer to any items at all then an empty string is returned.

$canvas->xview(?args?)

This method is used to query and change the horizontal position of the information displayed in the canvas's window. It can take any of the following forms:

$canvas->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the canvas's area (as defined by the -scrollregion option) is off-screen to the left, the middle 40% is visible in the window, and 40% of the canvas is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$canvas->xviewMoveto(fraction)

Adjusts the view in the window so that fraction of the total width of the canvas is off-screen to the left. Fraction must be a fraction between 0 and 1.

$canvas->xviewScroll(number, what)

This method shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right in units of the xScrollIncrement option, if it is greater than zero, or in units of one-tenth the window's width otherwise. If what is pages then the view adjusts in units of nine-tenths the window's width. If number is negative then information farther to the left becomes visible; if it is positive then information farther to the right becomes visible.

$canvas->yview(?args?)

This method is used to query and change the vertical position of the information displayed in the canvas's window. It can take any of the following forms:

$canvas->yview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the vertical span that is visible in the window. For example, if the first element is .6 and the second element is 1.0, the lowest 40% of the canvas's area (as defined by the -scrollregion option) is visible in the window. These are the same values passed to scrollbars via the -yscrollcommand option.

$canvas->yviewMoveto(fraction)

Adjusts the view in the window so that fraction of the canvas's area is off-screen to the top. Fraction is a fraction between 0 and 1.

$canvas->yviewScroll(number, what)

This method adjusts the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down in units of the yScrollIncrement option, if it is greater than zero, or in units of one-tenth the window's height otherwise. If what is pages then the view adjusts in units of nine-tenths the window's height. If number is negative then higher information becomes visible; if it is positive then lower information becomes visible.

OVERVIEW OF ITEM TYPES

The sections below describe the various types of items supported by canvas widgets. Each item type is characterized by two things: first, the form of the create method used to create instances of the type; and second, a set of configuration options for items of that type, which may be used in the create and itemconfigure methods. Most items don't support indexing or selection or the methods related to them, such as index and insert. Where items do support these facilities, it is noted explicitly in the descriptions below. At present, text, line and polygon items provide this support. For lines and polygons the indexing facility is used to manipulate the coordinates of the item.

ARC ITEMS

Items of type arc appear on the display as arc-shaped regions. An arc is a section of an oval delimited by two angles (specified by the -start and -extent options) and displayed in one of several ways (specified by the -style option). Arcs are created with methods of the following form:

 $canvas->createArc(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval that defines the arc. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for arcs:

-dash => pattern
-activedash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, the active state, and the disabled state of an arc item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-extent => degrees

Specifies the size of the angular range occupied by the arc. The arc's range extends for degrees degrees counter-clockwise from the starting angle given by the -start option. Degrees may be negative. If it is greater than 360 or less than -360, then degrees modulo 360 is used as the extent.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the arc region in its normal, active, and disabled states, Color may have any of the forms accepted by Tk_GetColor. If color is an empty string (the default), then then the arc will not be filled.

-outline => color
-activeoutline => color
-disabledoutline => color

This option specifies the color that should be used to draw the outline of the arc in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is specified as undef then no outline is drawn for the arc.

-outlinestipple => bitmap
-activeoutlinestipple => bitmap
-disabledoutlinestipple => bitmap

This option specifies stipple patterns that should be used to draw the outline of the arc in its normal, active and disabled states. Indicates that the outline for the arc should be drawn with a stipple pattern; bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.

-start => degrees

Specifies the beginning of the angular range occupied by the arc. Degrees is given in units of degrees measured counter-clockwise from the 3-o'clock position; it may be either positive or negative.

-state => state

Modifies the state of the arc item where state may be set to one of: normal, disabled, hidden or "". If set to empty, the state of the canvas itself is used. An arc item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the arc in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

-style => type

Specifies how to draw the arc. If type is pieslice (the default) then the arc's region is defined by a section of the oval's perimeter plus two line segments, one between the center of the oval and each end of the perimeter section. If type is chord then the arc's region is defined by a section of the oval's perimeter plus a single line segment connecting the two end points of the perimeter section. If type is arc then the arc's region consists of a section of the perimeter alone. In this last case the -fill option is ignored.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the arc item is updated on the screen.

-width => outlineWidth
-activewidth => outlineWidth
-disabledwidth => outlineWidth

Specifies the width of the outline to be drawn around the arc's region, in its normal, active and disabled states. outlineWidth may be in any of the forms described in the COORDINATES section above. If the -outline option has been specified as undef then this option has no effect. Wide outlines will be drawn centered on the edges of the arc's region. This option defaults to 1.0.

BITMAP ITEMS

Items of type bitmap appear on the display as images with two colors, foreground and background. Bitmaps are created with methods of the following form:

 $canvas->createBitmap(x, y, ?option, value, option, value, ...?)

The arguments x and y specify the coordinates of a point used to position the bitmap on the display (see the -anchor option below for more information on how bitmaps are displayed). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for bitmaps:

-anchor => anchorPos

AnchorPos tells how to position the bitmap relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the bitmap is centered on the point; if anchorPos is n then the bitmap will be drawn so that its top center point is at the positioning point. This option defaults to center.

-background => color
-activebackground => color
-disabledbackground => color

Specifies the color to use for each of the bitmap's '0' valued pixels in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. If this option isn't specified, or if it is specified as undef, then nothing is displayed where the bitmap pixels are 0; this produces a transparent effect.

-bitmap => bitmap
-activebitmap => bitmap
-disabledbitmap => bitmap

Specifies the bitmaps to display in the item in its normal, active and disabled states. Bitmap may have any of the forms accepted by Tk_GetBitmap.

-foreground => color
-activeforeground => bitmap
-disabledforeground => bitmap

Specifies the color to use for each of the bitmap's '1' valued pixels in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor and defaults to black.

-state => state

Modifies the state of the bitmap item where state may be set to one of: normal, disabled, or hidden. An bitmap item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the bitmap item is updated on the screen.

GRID ITEMS

Items of type grid are intended for producing a visual reference for interpreting other items. They can be drawn as either lines (with dash style) or as rectangular "dots" at each grid point.

Items of type grid are unlike other items they always cover the whole of the canvas, but are never enclosed by nor overlap any area and are not near any point. That is they are intended to be always visible but not "pickable", as such they do support the "active" state. They are like other items in that: multiple grids are permitted, they can be raised and lowered relative to other items, they can be moved and scaled. As yet grids do not apear in PostScript output.

Grids have outline like configure options. Grids are created with methods of the following form:

 $canvas->createGrid(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1 give the origin of the grid. x2, and y2 give the coordinates of the next grid point in their respective directions. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for grids:

-lines => boolean

If -lines is set to a true value then lines are drawn for both X and Y grids in the style determined by -dash. Otherwise retangular "dots" are drawn at each grid point.

-dash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, and the disabled state of a grid item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-color => color
-disabledcolor => color

This option specifies the color that should be used to draw the outline of the grid in its normal and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is undef then no grid will be drawn.

-stipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to draw the outline of the rectangle in its normal and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.

-state => state

Modifies the state of the rectangle item where state may be set to one of: normal, disabled, or hidden. Many options can take separate specifications in normal and disabled states such that the appearance of the item can be different in each state.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the grid item is updated on the screen.

-width => outlineWidth
-disabledwidth => outlineWidth

Specifies the width of the lines drawn by the grid or the size (in both X and Y) of the dots, in its normal and disabled states. This option defaults to 1.0.

IMAGE ITEMS

Items of type image are used to display images on a canvas. Images are created with methods of the following form:

 $canvas->createImage(x, y, ?option, value, option, value, ...?)

The arguments x and y specify the coordinates of a point used to position the image on the display (see the -anchor option below for more information). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for images:

-anchor => anchorPos

AnchorPos tells how to position the image relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the image is centered on the point; if anchorPos is n then the image will be drawn so that its top center point is at the positioning point. This option defaults to center.

-image => name
-activeimage => name
-disabledimage => name

Specifies the name of the images to display in the item in is normal, active and disabled states. This image must have been created previously with the imageCreate method.

-state => state

Modifies the state of the image item where state may be set to one of: normal, disabled, or hidden. An image item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item; it may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the image item is updated on the screen.

LINE ITEMS

Items of type line appear on the display as one or more connected line segments or curves. Line items support coordinate indexing operations using the canvas methods: dchars, index, insert. Lines are created with methods of the following form:

 $canvas->createLine(x1, y1..., xn, yn, ?option, value, option, value, ...?)

The arguments x1 through yn give the coordinates for a series of two or more points that describe a series of connected line segments. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for lines:

-arrow => where

Indicates whether or not arrowheads are to be drawn at one or both ends of the line. Where must have one of the values none (for no arrowheads), first (for an arrowhead at the first point of the line), last (for an arrowhead at the last point of the line), or both (for arrowheads at both ends). This option defaults to none.

-arrowshape => shape

This option indicates how to draw arrowheads. The shape argument must be a list with three elements, each specifying a distance in any of the forms described in the COORDINATES section above. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option isn't specified then Tk picks a ``reasonable'' shape.

-capstyle => style

Specifies the ways in which caps are to be drawn at the endpoints of the line. Style may have any of the forms accepted by Tk_GetCapStyle (butt, projecting, or round). If this option isn't specified then it defaults to butt. Where arrowheads are drawn the cap style is ignored.

-dash => pattern
-activedash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, the active state, and the disabled state of a line item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the line in its normal, active, and disabled states. Color may have any of the forms acceptable to Tk_GetColor. It may also be undef, in which case the line will be transparent. This option defaults to black.

-joinstyle => style

Specifies the ways in which joints are to be drawn at the vertices of the line. Style may have any of the forms accepted by Tk_GetCapStyle (bevel, miter, or round). If this option isn't specified then it defaults to miter. If the line only contains two points then this option is irrelevant.

-smooth => boolean

Boolean must have one of the forms accepted by Tk_GetBoolean. It indicates whether or not the line should be drawn as a curve. If so, the line is rendered as a set of parabolic splines: one spline is drawn for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated within a curve by duplicating the end-points of the desired line segment.

-splinesteps => number

Specifies the degree of smoothness desired for curves: each spline will be approximated with number line segments. This option is ignored unless the -smooth option is true.

-state => state

Modifies the state of the line item where state may be set to one of: normal, disabled, or hidden. A line item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the line in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the line item is updated on the screen.

-width => lineWidth
-activewidth => lineWidth
-disabledwidth => lineWidth

Specifies the width of the line in its normal, active and disabled states. lineWidth may be in any of the forms described in the COORDINATES section above.

Wide lines will be drawn centered on the path specified by the points. If this option isn't specified then it defaults to 1.0.

OVAL ITEMS

Items of type oval appear as circular or oval regions on the display. Each oval may have an outline, a fill, or both. Ovals are created with methods of the following form:

 $canvas->createOval(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of a rectangular region enclosing the oval. The oval will include the top and left edges of the rectangle not the lower or right edges. If the region is square then the resulting oval is circular; otherwise it is elongated in shape. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for ovals:

-dash => pattern
-activedash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, the active state, and the disabled state of an oval item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the oval in its normal, active, and disabled states. Color may have any of the forms accepted by Tk_GetColor. If color is undef (the default), then then the oval will not be filled.

-outline => color
-activeoutline => color
-disabledoutline => color

This option specifies the color that should be used to draw the outline of the oval in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is undef then no outline will be drawn for the oval.

-outlinestipple => bitmap
-activeoutlinestipple => bitmap
-disabledoutlinestipple => bitmap

This option specifies stipple patterns that should be used to draw the outline of the oval in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.

-state => state

Modifies the state of the oval item where state may be set to one of: normal, disabled, or hidden. An oval item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the oval in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the oval item is updated on the screen.

-width => outlineWidth
-activewidth => outlineWidth
-disabledwidth => outlineWidth

Specifies the width of the outline to be drawn around the oval, in its normal, active and disabled states. outlineWidth specifies the width of the outline to be drawn around the oval, in any of the forms described in the COORDINATES section above.

If the -outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the oval path defined by x1, y1, x2, and y2. This option defaults to 1.0.

POLYGON ITEMS

Items of type polygon appear as polygonal or curved filled regions on the display. Polygon items support coordinate indexing operations using the canvas methods: dchars, index, insert. Polygons are created with methods of the following form:

 $canvas->createPolygon(x1, y1, ..., xn, yn, ?option, value, option, value, ...?)

The arguments x1 through yn specify the coordinates for three or more points that define a closed polygon. The first and last points may be the same; whether they are or not, Tk will draw the polygon as a closed polygon. After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for polygons:

-dash => pattern
-activedash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, the active state, and the disabled state of an polygon item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the polygon in its normal, active, and disabled states. Color may have any of the forms acceptable to Tk_GetColor. If color is undef then the polygon will be transparent. This option defaults to black.

-joinstyle => style

Specifies the ways in which joints are to be drawn at the vertices of the outline. Style may have any of the forms accepted by Tk_GetCapStyle (bevel, miter, or round). If this option isn't specified then it defaults to miter.

-outline => color
-activeoutline => color
-disabledoutline => color

This option specifies the color that should be used to draw the outline of the polygon in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. If color is undef then no outline will be drawn for the polygon. This option defaults to undef (no outline).

-outlinestipple => bitmap
-activeoutlinestipple => bitmap
-disabledoutlinestipple => bitmap

This option specifies stipple patterns that should be used to draw the outline of the polygon in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.

-smooth => boolean

Boolean must have one of the forms accepted by Tk_GetBoolean It indicates whether or not the polygon should be drawn with a curved perimeter. If so, the outline of the polygon becomes a set of parabolic splines, one spline for the first and second line segments, one for the second and third, and so on. Straight-line segments can be generated in a smoothed polygon by duplicating the end-points of the desired line segment.

-splinesteps => number

Specifies the degree of smoothness desired for curves: each spline will be approximated with number line segments. This option is ignored unless the -smooth option is true.

-state => state

Modifies the state of the polygon item where state may be set to one of: normal, disabled, or hidden. A polygon item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the polygon in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default), then filling is done in a solid fashion.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the polygon item is updated on the screen.

-width => outlineWidth
-activewidth => outlineWidth
-disabledwidth => outlineWidth
Specifies the width of the outline to be drawn around

the polygon, in its normal, active and disabled states. outlineWidth may be in any of the forms described in the COORDINATES section above. OutlineWidth specifies the width of the outline to be drawn around the polygon, in any of the forms described in the COORDINATES section above. If the -outline option hasn't been specified then this option has no effect. This option defaults to 1.0.

Polygon items are different from other items such as rectangles, ovals and arcs in that interior points are considered to be ``inside'' a polygon (e.g. for purposes of the find closest and find overlapping methods) even if it is not filled. For most other item types, an interior point is considered to be inside the item only if the item is filled or if it has neither a fill nor an outline. If you would like an unfilled polygon whose interior points are not considered to be inside the polygon, use a line item instead.

RECTANGLE ITEMS

Items of type rectangle appear as rectangular regions on the display. Each rectangle may have an outline, a fill, or both. Rectangles are created with methods of the following form:

 $canvas->createRectangle(x1, y1, x2, y2, ?option, value, option, value, ...?)

The arguments x1, y1, x2, and y2 give the coordinates of two diagonally opposite corners of the rectangle (the rectangle will include its upper and left edges but not its lower or right edges). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for rectangles:

-dash => pattern
-activedash => pattern
-disableddash => pattern

This option specifies dash patterns for the normal state, the active state, and the disabled state of a rectangle item. pattern may have any of the forms accepted by Tk_GetDash. If the dash options are omitted then the default is a solid outline.

-dashoffset => offset

The starting offset into the pattern provided by the -dash option. -dashoffset is ignored if there is no -dash pattern.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the rectangle in its normal, active, and disabled states. Color may be specified in any of the forms accepted by Tk_GetColor. If color is undef (the default), then the rectangle will not be filled.

-outline => color
-activeoutline => color
-disabledoutline => color

This option specifies the color that should be used to draw the outline of the rectangle in its normal, active and disabled states. Color may have any of the forms accepted by Tk_GetColor. This option defaults to black. If color is undef then no outline will be drawn for the rectangle.

-outlinestipple => bitmap
-activeoutlinestipple => bitmap
-disabledoutlinestipple => bitmap

This option specifies stipple patterns that should be used to draw the outline of the rectangle in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -outline option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then the outline is drawn in a solid fashion.

-state => state

Modifies the state of the rectangle item where state may be set to one of: normal, disabled, or hidden. A rectangle item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the rectangle in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If the -fill option hasn't been specified then this option has no effect. If bitmap is an empty string (the default), then filling is done in a solid fashion.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the rectangle item is updated on the screen.

-width => outlineWidth
-activewidth => outlineWidth
-disabledwidth => outlineWidth

Specifies the width of the outline to be drawn around the rectangle, in its normal, active and disabled states. OutlineWidth specifies the width of the outline to be drawn around the rectangle, in any of the forms described in the COORDINATES section above.

If the -outline option hasn't been specified then this option has no effect. Wide outlines are drawn centered on the rectangular path defined by x1, y1, x2, and y2. This option defaults to 1.0.

TEXT ITEMS

A text item displays a string of characters on the screen in one or more lines. Text items support indexing and selection, along with the following text-related canvas methods: dchars, focus, icursor, index, insert, select. Text items are created with methods of the following form:

 $canvas->createText(x, y, ?option, value, option, value, ...?)

The arguments x and y specify the coordinates of a point used to position the text on the display (see the options below for more information on how text is displayed). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure methods to change the item's configuration. The following options are supported for text items:

-anchor => anchorPos

AnchorPos tells how to position the text relative to the positioning point for the text; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the text is centered on the point; if anchorPos is n then the text will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. This option defaults to center.

-fill => color
-activefill => color
-disabledfill => color

Specifies the color to be used to fill the text in its normal, active, and disabled states. Color may have any of the forms accepted by Tk_GetColor. If color is undef then the text will be transparent. If this option isn't specified then it defaults to black.

-font => fontName

Specifies the font to use for the text item. FontName may be any string acceptable to Tk_GetFontStruct. If this option isn't specified, it defaults to a system-dependent font.

-justify => how

Specifies how to justify the text within its bounding region. How must be one of the values left, right, or center. This option will only matter if the text is displayed as multiple lines. If the option is omitted, it defaults to left.

-state => state

Modifies the state of the text item where state may be set to one of: normal, disabled, or hidden. A text item may also be in the "active" state if the mouse is currently over it. Many options can take separate specifications in normal, active and disabled states such that the appearance of the item can be different in each state.

-stipple => bitmap
-activestipple => bitmap
-disabledstipple => bitmap

This option specifies stipple patterns that should be used to fill the the text in its normal, active and disabled states. bitmap specifies the stipple pattern to use, in any of the forms accepted by Tk_GetBitmap. If bitmap is an empty string (the default) then the text is drawn in a solid fashion.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-text => string

String specifies the characters to be displayed in the text item. Newline characters cause line breaks. The characters in the item may also be changed with the insert and delete methods. This option defaults to an empty string.

-updatecommand => command

Specifies a callback that is to be executed every time the text item is updated on the screen.

-width => lineLength

Specifies a maximum line length for the text, in any of the forms described in the COORDINATES section above. If this option is zero (the default) the text is broken into lines only at newline characters. However, if this option is non-zero then any line that would be longer than lineLength is broken just before a space character to make the line shorter than lineLength; the space character is treated as if it were a newline character.

WINDOW ITEMS

Items of type window cause a particular window to be displayed at a given position on the canvas. Window items are created with methods of the following form:

$canvas->createWindow(x, y?, -option=>value, -option=>value, ...?)

The arguments x and y specify the coordinates of a point used to position the window on the display (see the -anchor option below for more information on how bitmaps are displayed). After the coordinates there may be any number of option-value pairs, each of which sets one of the configuration options for the item. These same option-value pairs may be used in itemconfigure method to change the item's configuration. The following options are supported for window items:

-anchor => anchorPos

AnchorPos tells how to position the window relative to the positioning point for the item; it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is center then the window is centered on the point; if anchorPos is n then the window will be drawn so that its top center point is at the positioning point. This option defaults to center.

-height => pixels

Specifies the height to assign to the item's window. Pixels may have any of the forms described in the COORDINATES section above. If this option isn't specified, or if it is specified as an empty string, then the window is given whatever height it requests internally.

-state => state

Modifies the state of the window item where state may be set to one of: normal, disabled, or hidden.

-tags => tagList

Specifies a set of tags to apply to the item. TagList consists of a list of tag names, which replace any existing tags for the item. TagList may be an empty list.

-updatecommand => command

Specifies a callback that is to be executed every time the window item is updated on the screen.

-width => pixels

Specifies the width to assign to the item's window. Pixels may have any of the forms described in the COORDINATES section above. If this option isn't specified, or if it is specified as an empty string, then the window is given whatever width it requests internally.

-window => $widget

Specifies the window to associate with this item. The window specified by $widget must either be a child of the canvas widget or a child of some ancestor of the canvas widget. PathName may not refer to a top-level window.

Note: due to restrictions in the ways that windows are managed, it is not possible to draw other graphical items (such as lines and images) on top of window items. A window item always obscures any graphics that overlap it, regardless of their order in the display list.

APPLICATION-DEFINED ITEM TYPES

It is possible for individual applications to define new item types for canvas widgets using C code. See the documentation for Tk_CreateItemType.

BINDINGS

Canvas has default bindings to allow scrolling if necessary: <Up>, <Down>, <Left> and <Right> (and their <Control-*> counter parts). Further <Proir>, <Next>, <Home> and <End>. These bindings allow you to navigate the same way as in other widgets that can scroll.

Perl/Tk Methods

The following methods are added as perl code:

$canvas->get_corners

Returns the bounding box in Canvas coordinates of the visible portion of the Canvas. (Written by Slaven Rezic.)

CREDITS

Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's ezd program. Ezd provides structured graphics in a Scheme environment and preceded canvases by a year or two. Its simple mechanisms for placing and animating graphical objects inspired the functions of canvases.

KEYWORDS

canvas, widget


Tk::Checkbutton - Create and manipulate Checkbutton widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS

NAME

Tk::Checkbutton - Create and manipulate Checkbutton widgets

SYNOPSIS

$checkbutton = $parent->Checkbutton(?options?);

STANDARD OPTIONS

-activebackground | -cursor | -highlightthickness | -takefocus
-activeforeground | -disabledforeground | -image | -text
-anchor | -font | -justify | -textvariable
-background | -foreground | -padx | -underline
-bitmap | -highlightbackground | -pady | -wraplength
-borderwidth | -highlightcolor | -relief

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: command
Class: Command
Switch: -command

Specifies a perl/Tk callback to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (-variable option) will be updated before the command is invoked.

Name: height
Class: Height
Switch: -height

Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in lines of text. If this option isn't specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it.

Name: indicatorOn
Class: IndicatorOn
Switch: -indicatoron

Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the relief option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise.

Command-Line Name: -offrelief
Database Name: offRelief
Database Class: OffRelief

Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is raised. By setting this option to flat and setting -indicatoron false -overrelief raised, the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Bold, Italic, and Underline checkbuttons on the toolbar of a word-processor, for example.

Name: offValue
Class: Value
Switch: -offvalue

Specifies value to store in the button's associated variable whenever this button is deselected. Defaults to ``0''.

Name: onValue
Class: Value
Switch: -onvalue

Specifies value to store in the button's associated variable whenever this button is selected. Defaults to ``1''.

Command-Line Name: -overrelief
Database Name: overRelief
Database Class: OverRelief

Specifies an alternative relief for the button, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring -relief flat -overrelief raised. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the button. The empty string is the default value.

Name: selectColor
Class: Background
Switch: -selectcolor

Specifies a background color to use when the button is selected. If indicatorOn is true then the color applies to the indicator. Under Windows, this color is used as the background for the indicator regardless of the select state. If indicatorOn is false, this color is used as the background for the entire widget, in place of background or activeBackground, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected.

Name: selectImage
Class: SelectImage
Switch: -selectimage

Specifies an image to display (in place of the image option) when the checkbutton is selected. This option is ignored unless the image option has been specified.

Name: state
Class: State
Switch: -state

Specifies one of three states for the checkbutton: normal, active, or disabled. In normal state the checkbutton is displayed using the foreground and background options. The active state is typically used when the pointer is over the checkbutton. In active state the checkbutton is displayed using the activeForeground and activeBackground options. Disabled state means that the checkbutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledForeground and background options determine how the checkbutton is displayed.

Name: variable
Class: Variable
Switch: -variable

Specifies reference to a variable to set to indicate whether or not this button is selected. Defaults to \$widget->{'Value'} member of the widget's hash. In general perl variables are undef unless specifically initialized which will not match either default -onvalue or default -offvalue.

Name: width
Class: Width
Switch: -width

Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in characters. If this option isn't specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it.

DESCRIPTION

The Checkbutton method creates a new window (given by the $widget argument) and makes it into a checkbutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the checkbutton such as its colors, font, text, and initial relief. The checkbutton command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A checkbutton is a widget that displays a textual string, bitmap or image and a square called an indicator. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the wrapLength option) and one of the characters may optionally be underlined using the underline option. A checkbutton has all of the behavior of a simple button, including the following: it can display itself in either of three different ways, according to the state option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a perl/Tk callback whenever mouse button 1 is clicked over the checkbutton.

In addition, checkbuttons can be selected. If a checkbutton is selected then the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the checkbutton is set to a particular value (normally 1). Under Unix, the indicator is drawn with a sunken relief and a special color. Under Windows, the indicator is drawn with a check mark inside. If the checkbutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). Under Unix, the indicator is drawn with a raised relief and no special color. Under Windows, the indicator is drawn without a check mark inside. By default, the name of the variable associated with a checkbutton is the same as the name used to create the checkbutton. The variable name, and the ``on'' and ``off'' values stored in it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a checkbutton is configured to select and deselect itself on alternate button clicks. In addition, each checkbutton monitors its associated variable and automatically selects and deselects itself when the variables value changes to and from the button's ``on'' value.

WIDGET METHODS

The Checkbutton method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for checkbutton widgets:

$checkbutton->deselect

Deselects the checkbutton and sets the associated variable to its ``off'' value.

$checkbutton->flash

Flashes the checkbutton. This is accomplished by redisplaying the checkbutton several times, alternating between active and normal colors. At the end of the flash the checkbutton is left in the same normal/active state as when the command was invoked. This command is ignored if the checkbutton's state is disabled.

$checkbutton->invoke

Does just what would have happened if the user invoked the checkbutton with the mouse: toggle the selection state of the button and invoke the perl/Tk callback associated with the checkbutton, if there is one. The return value is the return value from the perl/Tk callback, or an empty string if there is no command associated with the checkbutton. This command is ignored if the checkbutton's state is disabled.

$checkbutton->select

Selects the checkbutton and sets the associated variable to its ``on'' value.

$checkbutton->toggle

Toggles the selection state of the button, redisplaying it and modifying its associated variable to reflect the new state.

BINDINGS

Tk automatically creates class bindings for checkbuttons that give them the following default behavior:

[1]

On Unix systems, a checkbutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the checkbutton. On Mac and Windows systems, when mouse button 1 is pressed over a checkbutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button.

[2]

When mouse button 1 is pressed over a checkbutton, it is invoked (its selection state toggles and the command associated with the button is invoked, if there is one).

[3]

When a checkbutton has the input focus, the space key causes the checkbutton to be invoked. Under Windows, there are additional key bindings; plus (+) and equal (=) select the button, and minus (-) deselects the button.

If the checkbutton's state is disabled then none of the above actions occur: the checkbutton is completely non-responsive.

The behavior of checkbuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

checkbutton, widget


Tk::clipboard - Manipulate Tk clipboard

  • KEYWORDS

NAME

Tk::clipboard - Manipulate Tk clipboard

SYNOPSIS

$widget->clipboard Option?(args)?

DESCRIPTION

This command provides an interface to the Tk clipboard, which stores data for later retrieval using the selection mechanism. In order to copy data into the clipboard, clipboardClear must be called, followed by a sequence of one or more calls to clipboardAppend. To ensure that the clipboard is updated atomically, all appends should be completed before returning to the event loop.

The following methods are currently supported:

$widget->clipboardClear

Claims ownership of the clipboard on $widget's display and removes any previous contents. Returns an empty string.

$widget->clipboardAppend(?-format=>format?,?-type=>type?,?--?,data)

Appends data to the clipboard on $widget's display in the form given by type with the representation given by format and claims ownership of the clipboard on $widget's display.

Type specifies the form in which the selection is to be returned (the desired ``target'' for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME; see the Inter-Client Communication Conventions Manual for complete details. Type defaults to STRING.

The format argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to STRING. If format is STRING, the selection is transmitted as 8-bit ASCII characters. See the the Tk::Selection manpage documentation for explanation of what happens if format is not STRING. Note that arguments passed to clipboardAppend are concatenated before conversion, so the caller must take care to ensure appropriate spacing across string boundaries. All items appended to the clipboard with the same type must have the same format.

A -- argument may be specified to mark the end of options: the next argument will always be used as data. This feature may be convenient if, for example, data starts with a -.

$widget->clipboardGet( ?-type? );

Retrieve data from the clipboard on widget's display. -type specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING. This command is equivalent to selectionGet( -selection => 'CLIPBOARD' ).

KEYWORDS

clear, format, clipboard, append, selection, type


Tk::CmdLine - Process standard X11 command line options and set initial resources

    • Command Line Options
    • Initial Resources
  • METHODS
  • NOTES
  • EXAMPLES
  • ENVIRONMENT
  • SEE ALSO
  • HISTORY

NAME

Tk::CmdLine - Process standard X11 command line options and set initial resources

SYNOPSIS

  Tk::CmdLine::SetArguments([@argument]);

  my $value = Tk::CmdLine::cget([$option]);

  Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]);

  Tk::CmdLine::LoadResources(
      [ -symbol   => $symbol     ]
      [ -file     => $fileSpec   ]
      [ -priority => $priority   ]
      [ -echo     => $fileHandle ] );

DESCRIPTION

Process standard X11 command line options and set initial resources.

The X11R5 man page for X11 says: "Most X programs attempt to use the same names for command line options and arguments. All applications written with the X Toolkit Intrinsics automatically accept the following options: ...". This module processes these command line options for perl/Tk applications using the SetArguments() function.

This module can optionally be used to load initial resources explicitly via function SetResources(), or from specified files (default: the standard X11 application-specific resource files) via function LoadResources().

Command Line Options

-background Color | -bg Color

Specifies the color to be used for the window background.

-class Class

Specifies the class under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable file name.

-display Display | -screen Display

Specifies the name of the X server to be used.

-font Font | -fn Font

Specifies the font to be used for displaying text.

-foreground Color | -fg Color

Specifies the color to be used for text or graphics.

-geometry Geometry

Specifies the initial size and location of the first MainWindow.

-iconic

Indicates that the user would prefer that the application's windows initially not be visible as if the windows had been immediately iconified by the user. Window managers may choose not to honor the application's request.

-motif

Specifies that the application should adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them.

-name Name

Specifies the name under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable file name.

-synchronous

Indicates that requests to the X server should be sent synchronously, instead of asynchronously. Since Xlib normally buffers requests to the server, errors do do not necessarily get reported immediately after they occur. This option turns off the buffering so that the application can be debugged. It should never be used with a working program.

-title TitleString

This option specifies the title to be used for this window. This information is sometimes used by a window manager to provide some sort of header identifying the window.

-xrm ResourceString

Specifies a resource pattern and value to override any defaults. It is also very useful for setting resources that do not have explicit command line arguments.

The ResourceString is of the form <pattern>:<value>, that is (the first) ':' is used to determine which part is pattern and which part is value. The (<pattern>, <value>) pair is entered into the options database with optionAdd (for each MainWindow configured), with interactive priority.

Initial Resources

There are several mechanism for initializing the resource database to be used by an X11 application. Resources may be defined in a $HOME/.Xdefaults file, a system application defaults file (e.g. /usr/lib/X11/app-defaults/<CLASS>), or a user application defaults file (e.g. $HOME/<CLASS>). The Tk::CmdLine functionality for setting initial resources concerns itself with the latter two.

Resource files contain data lines of the form <pattern>:<value>. They may also contain blank lines and comment lines (denoted by a ! character as the first non-blank character). Refer to option for a description of <pattern>:<value>.

System Application Defaults Files

System application defaults files may be specified via environment variable $XFILESEARCHPATH which, if set, contains a list of file patterns (joined using the OS-dependent path delimiter, e.g. colon on UNIX).

User Application Defaults Files

User application defaults files may be specified via environment variables $XUSERFILESEARCHPATH, $XAPPLRESDIR or $HOME.

METHODS

SetArguments - Tk::CmdLine::SetArguments([@argument])

Extract the X11 options contained in a specified array (@ARGV by default).

  Tk::CmdLine::SetArguments([@argument])

The X11 options may be specified using a single dash - as per the X11 convention, or using two dashes -- as per the POSIX standard (e.g. -geometry 100x100, -geometry 100x100 or -geometry=100x100). The options may be interspersed with other options or arguments. A -- by itself terminates option processing.

By default, command line options are extracted from @ARGV the first time a MainWindow is created. The Tk::MainWindow constructor indirectly invokes SetArguments() to do this.

GetArguments - Tk::CmdLine::GetArguments()

Get a list of the X11 options that have been processed by SetArguments(). (GetArguments() first invokes SetArguments() if it has not already been invoked.)

cget - Tk::CmdLine::cget([$option])

Get the value of a configuration option specified via SetArguments(). (cget() first invokes SetArguments() if it has not already been invoked.)

  Tk::CmdLine::cget([$option])

The valid options are: -class, -name, -screen and -title. If no option is specified, -class is implied.

A typical use of cget() might be to obtain the application class in order to define the name of a resource file to be loaded in via LoadResources().

  my $class = Tk::CmdLine::cget(); # process command line and return class
SetResources - Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])

Set the initial resources.

  Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])

A single resource may be specified using a string of the form '<pattern>:<value>'. Multiple resources may be specified by passing an array reference whose elements are either strings of the above form, and/or anonymous arrays of the form [ <pattern>, <value> ]. The optional second argument specifies the priority, as defined in option, to be associated with the resources (default: userDefault).

Note that SetResources() first invokes SetArguments() if it has not already been invoked.

LoadResources - Tk::CmdLine::LoadResources([%options])

Load initial resources from one or more files.

  Tk::CmdLine::LoadResources(
      [ -symbol   => $symbol     ]
      [ -file     => $fileSpec   ]
      [ -priority => $priority   ]
      [ -echo     => $fileHandle ] );

[ -symbol => $symbol ] specifies the name of an environment variable that, if set, defines a list of one or more directories and/or file patterns (joined using the OS-dependent path delimiter, e.g. colon on UNIX). $XUSERFILESEARCHPATH is a special case. If $XUSERFILESEARCHPATH is not set, $XAPPLRESDIR is checked instead. If $XAPPLRESDIR is not set, $HOME is checked instead.

An item is identified as a file pattern if it contains one or more /%[A-Za-z]/ patterns. Only patterns %L, %T and %N are currently recognized. All others are replaced with the null string. Pattern %L is translated into $LANG. Pattern %T is translated into app-defaults. Pattern %N is translated into the application class name.

Each file pattern, after substitutions are applied, is assumed to define a FileSpec to be examined.

When a directory is specified, FileSpecs <DIRECTORY>/<LANG>/<CLASS> and <DIRECTORY>/<CLASS> are defined, in that order.

[ -file => $fileSpec ] specifies a resource file to be loaded in. The file is silently skipped if if does not exist, or if it is not readable.

[ -priority => $priority ] specifies the priority, as defined in option, to be associated with the resources (default: userDefault).

[ -echo => $fileHandle ] may be used to specify that a line should be printed to the corresponding FileHandle (default: \*STDOUT) everytime a file is examined / loaded.

If no -symbol or -file options are specified, LoadResources() processes symbol $XFILESEARCHPATH with priority startupFile and $XUSERFILESEARCHPATH with priority userDefault. (Note that $XFILESEARCHPATH and $XUSERFILESEARCHPATH are supposed to contain only patterns. $XAPPLRESDIR and $HOME are supposed to be a single directory. LoadResources() does not check/care whether this is the case.)

For each set of FileSpecs, LoadResources() examines each FileSpec to determine if the file exists and is readable. The first file that meets this criteria is read in and SetResources() is invoked.

Note that LoadResources() first invokes SetArguments() if it has not already been invoked.

NOTES

This module is an object-oriented module whose methods can be invoked as object methods, class methods or regular functions. This is accomplished via an internally-maintained object reference which is created as necessary, and which always points to the last object used. SetArguments(), SetResources() and LoadResources() return the object reference.

EXAMPLES

  1. @ARGV is processed by Tk::CmdLine at MainWindow creation.

      use Tk;

      # <Process @ARGV - ignoring all X11-specific options>

      my $mw = MainWindow->new();

      MainLoop();

  2. @ARGV is processed by Tk::CmdLine before MainWindow creation. An @ARGV of (--geometry=100x100 -opt1 a b c -bg red) is equal to (-opt1 a b c) after SetArguments() is invoked.

      use Tk;

      Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too

      # <Process @ARGV - not worrying about X11-specific options>

      my $mw = MainWindow->new();

      MainLoop();

  3. Just like 2) except that default arguments are loaded first.

      use Tk;

      Tk::CmdLine::SetArguments(qw(-name test -iconic));
  Tk::CmdLine::SetArguments();

      # <Process @ARGV - not worrying about X11-specific options>

      my $mw = MainWindow->new();

      MainLoop();

  4. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation.

      use Tk;

      Tk::CmdLine::SetArguments();

      # <Process @ARGV - not worrying about X11-specific options>

      Tk::CmdLine::LoadResources();

      my $mw = MainWindow->new();

      MainLoop();

  5. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation using non-default priorities.

      use Tk;

      Tk::CmdLine::SetArguments();

      # <Process @ARGV - not worrying about X11-specific options>

      Tk::CmdLine::LoadResources(-echo => \*STDOUT,
      -priority => 65, -symbol => 'XFILESEARCHPATH' );
  Tk::CmdLine::LoadResources(-echo => \*STDOUT,
      -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );

      my $mw = MainWindow->new();

      MainLoop();

  6. @ARGV is processed by Tk::CmdLine before MainWindow creation. Standard resource files are loaded in before MainWindow creation. Individual resources are also loaded in before MainWindow creation.

      use Tk;

      Tk::CmdLine::SetArguments();

      # <Process @ARGV - not worrying about X11-specific options>

      Tk::CmdLine::LoadResources();

      Tk::CmdLine::SetResources( # set a single resource
      '*Button*background: red',
      'widgetDefault' );

      Tk::CmdLine::SetResources( # set multiple resources
      [ '*Button*background: red', '*Button*foreground: blue' ],
      'widgetDefault' );

      my $mw = MainWindow->new();

      MainLoop();

ENVIRONMENT

HOME (optional)

Home directory which may contain user application defaults files as $HOME/$LANG/<CLASS> or $HOME/<CLASS>.

LANG (optional)

The current language (default: C).

XFILESEARCHPATH (optional)

List of FileSpec patterns (joined using the OS-dependent path delimiter, e.g. colon on UNIX) used in defining system application defaults files.

XUSERFILESEARCHPATH (optional)

List of FileSpec patterns (joined using the OS-dependent path delimiter, e.g. colon on UNIX) used in defining user application defaults files.

XAPPLRESDIR (optional)

Directory containing user application defaults files as $XAPPLRESDIR/$LANG/<CLASS> or $XAPPLRESDIR/<CLASS>.

SEE ALSO

MainWindow option

HISTORY

  • 1999.03.04 Ben Pavon <ben.pavon@hsc.hac.com>

    Rewritten as an object-oriented module.

    Allow one to process command line options in a specified array (@ARGV by default). Eliminate restrictions on the format and location of the options within the array (previously the X11 options could not be specified in POSIX format and had to be at the beginning of the array).

    Added the SetResources() and LoadResources() functions to allow the definition of resources prior to MainWindow creation.

  • 2000.08.31 Ben Pavon <ben.pavon@hsc.hac.com>

    Added the GetArguments() method which returns the list of arguments that have been processed by SetArguments().

    Modified LoadResources() to split the symbols using the OS-dependent path delimiter defined in the Config module.

    Modified LoadResources() to eliminate a warning message when processing patterns %l, %C, %S.


Tk::ColorEditor - a general purpose Tk widget Color Editor

  • AUTHORS

NAME

Tk::ColorEditor - a general purpose Tk widget Color Editor

SYNOPSIS

   use Tk::ColorEditor;

   $cref = $mw->ColorEditor(-title => $title, -cursor => @cursor);

   $cref->Show;

DESCRIPTION

ColorEditor is implemented as an object with various methods, described below. First, create your ColorEditor object during program initialization (one should be sufficient), and then configure it by specifying a list of Tk widgets to colorize. When it's time to use the editor, invoke the Show() method.

ColorEditor allows some customization: you may alter the color attribute menu by adding and/or deleting menu items and/or separators, turn the status window on or off, alter the configurator's list of color widgets, or even supply your own custom color configurator callback.

  1. Call the constructor to create the editor object, which in turn returns a blessed reference to the new object:

       use Tk::ColorEditor;

       $cref = $mw->ColorEditor(
       -title  => $title,
       -cursor => @cursor,
   );

          mw     - a window reference, usually the result of a MainWindow->new
               call.  As the default root of a widget tree, $mw and all
               descendant widgets at object-creation-time are configured
               by the default color configurator procedure.  (You probably
               want to change this though or you might end up colorizing
               ColorEditor!)
      title  - Toplevel title, default = ' '.
      cursor - a valid Tk '-cursor' specification (default is
               'top_left_arrow').  This cursor is used over all ColorEditor
               "hot spots".

  2. Invoke the configure() method to change editor characteristics:

       $cref->configure(-option => value, ..., -option-n => value-n);

          options:
        -command             : a callback to a  `set_colors' replacement.
        -widgets             : a reference to a list of widget references
                               for the color configurator.
        -display_status      : TRUE IFF display the ColorEditor status
                               window when applying colors.
        -add_menu_item       : 'SEP', or a color attribute menu item.
        -delete_menu_item    : 'SEP', a color attribute menu item, or color
                               attribute menu ordinal.
       For example:
          $cref->configure(-delete_menu_item   => 3,
          -delete_menu_item   => 'disabledforeground',
          -add_menu_item      => 'SEP',
          -add_menu_item      => 'New color attribute',
          -widgets            => [$ce, $qu, $f2b2],
          -widgets            => [$f2->Descendants],
          -command            => [\&my_special_configurator, some, args ]
      );

  3. Invoke the Show() method on the editor object, say, by a button or menu press:

       $cref->Show;

  4. The cget(-widgets) method returns a reference to a list of widgets that are colorized by the configurator. Typically, you add new widgets to this list and then use it in a subsequent configure() call to expand your color list.

       $cref->configure(
       -widgets => [
           @{$Filesystem_ref->cget(-widgets)}, @{$cref->cget(-widgets)},
       ]
   );

  5. The delete_widgets() method expects a reference to a list of widgets which are then removed from the current color list.

       $cref->delete_widgets($OBJTABLE{$objname}->{'-widgets'})

AUTHORS

Stephen O. Lidie, Lehigh University Computing Center. 95/03/05 lusol@Lehigh.EDU

Many thanks to Guy Decoux (decoux@moulon.inra.fr) for doing the initial translation of tcolor.tcl to TkPerl, from which this code has been derived.


Tk::DragDrop::Common - private class used by Drag&Drop

NAME

Tk::DragDrop::Common - private class used by Drag&Drop

DESCRIPTION

This class provides methods to automate the the loading and declaring of Drop and Site 'types'.


Tk::Compound - Create multi-line compound images.

  • CREATING COMPOUND IMAGES
  • IMAGE COMMAND
  • EXAMPLE
  • KEYWORDS

NAME

Tk::Compound - Create multi-line compound images.

use Tk::Compound;
$image = $widget->Compound?(name??,options?)
$image->Line?(options?)
$image->Text?(options?)
$image->Bitmap?(options?)
$image->Image?(options?)
$image->Space?(options?)

DESCRIPTION

Compound image types can be used to create images that consists of multiple horizontal lines; each line is composed of a series of items (texts, bitmaps, images or spaces) arranged from left to right. Compound images are mainly used to embed complex drawings into widgets that support the -image option. As shown in the EXAMPLE section below, a compound image can be used to display a bitmap and a text string simutaneously in a Tk Button widget.

Compound images can only be used on windows on the same display as, and with the same pixel depth and visual as the $widget used to create them.

CREATING COMPOUND IMAGES

Compounds are created using $widget->Compound. Compounds support the following options:

-background => color

Specifies the background color of the compound image. This color is also used as the default background color for the bitmap items in the compound image.

-borderwidth => pixels

Specifies a non-negative value indicating the width of the 3-D border drawn around the compound image.

-font => font

Specifies the default font for the text items in the compound image.

-foreground => color

Specifies the default foreground color for the bitmap and text items in the compound image.

-padx => value

Specifies a non-negative value indicating how much extra space to request for the compound image in the X-direction. The value may have any of the forms acceptable to Tk_GetPixels(3).

-pady => value

Specifies a non-negative value indicating how much extra space to request for the compound image in the Y-direction.

-relief => value

Specifies the 3-D effect desired for the background of the compound image. Acceptable values are raised, sunken, flat, ridge, and groove.

-showbackground => value

Specifies whether the background and the 3D borders should be drawn. Must be a valid boolean value. By default the background is not drawn and the compound image appears to have a transparent background.

IMAGE COMMAND

When a compound image is created, Tk also creates a new object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above.

The object also supports the following methods:

$compound->Line?(option = value ...>)?

Creates a new line at the bottom of the compound image. Lines support the following options:

-anchor value

Specifies how the line should be aligned along the horizontal axis. When the values are w, sw or nw, the line is aligned to the left. When the values are c, s or n, the line is aligned to the middle. When the values are e, se or ne, the line is aligned to the right.

-padx => value

Specifies a non-negative value indicating how much extra space to request for this line in the X-direction.

$compound->Itemtype?(option = value ...>)?

Creates a new item of the type Itemtype at the end of the last line of the compound image. All types of items support these following common options:

-anchor value

Specifies how the item should be aligned along the vertical axis. When the values are n, nw or ne, the item is aligned to the top of the line. When the values are c, w or e, the item is aligned to the middle of the line. When the values are s, se or sw, the item is aligned to the bottom of the line.

-padx => value

Specifies a non-negative value indicating how much extra space to request for this item in the X-direction.

-pady => value

Specifies a non-negative value indicating how much extra space to request for this item in the Y-direction.

item-type can be any of the following:
$compound->Bitmap?(option = value ...>)?

Creates a new bitmap item of at the end of the last line of the compound image. Additional options accepted by the bitmap type are:

-background => color

Specifies the background color of the bitmap item.

-bitmap => name

Specifies a bitmap to display in this item, in any of the forms acceptable to Tk_GetBitmap(3).

-foreground => color

Specifies the foreground color of the bitmap item.

$compound->Image?(option = value ...>)?

Creates a new image item of at the end of the last line of the compound image. Additional options accepted by the image type are:

-image => name

Specifies an image to display in this item. name must have been created with the image create command.

$compound->Space?(option = value ...>)?

Creates a new space item of at the end of the last line of the compound image. Space items do not display anything. They just acts as space holders that add additional spaces between items inside a compound image. Additional options accepted by the image type are:

-width => value

Specifies the width of this space. The value may have any of the forms acceptable to Tk_GetPixels(3).

-height => value

Specifies the height of this space. The value may have any of the forms acceptable to Tk_GetPixels(3).

$compound->Text?(option = value ...>)?

Creates a new text item of at the end of the last line of the compound image. Additional options accepted by the text type are:

-background => color

Specifies the background color of the text item.

-font => name

Specifies the font to be used for this text item.

-foreground => color

Specifies the foreground color of the text item.

-justify value

When there are multiple lines of text displayed in a text item, this option determines how the lines line up with each other. value must be one of left, center, or right. Left means that the lines' left edges all line up, center means that the lines' centers are aligned, and right means that the lines' right edges line up.

-text => string

Specifies a text string to display in this text item.

-underline value

Specifies the integer index of a character to underline in the text item. 0 corresponds to the first character of the text displayed in the text item, 1 to the next character, and so on.

-wraplength value

This option specifies the maximum line length of the label string on this text item. If the line length of the label string exceeds this length, it is wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. If this value is less than or equal to 0 then no wrapping is done: lines will break only at newline characters in the text.

EXAMPLE

The following example creates a compound image with a bitmap and a text string and places this image into a Button(n) widget. Notice that the image must be created using the widget that it resides in.

  my $b = $parent->Button;
  my $c = $b->Compound;
  $b->configure(-image => $c);
  $c->Line;
  $c->Bitmap(-bitmap => 'warning');
  $c->Space(-width => 8);
  $c->Text(-text => "Warning", -underline => 0);
  $b->pack;

KEYWORDS

image(n), Tix(n)


Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.

    • Defining the ConfigSpecs for a class.
    • Delegating all options of a widget class to a subwidget
    • Default values
    • New()-time configure
    • Configuring composites
    • Inquiring attributes of composites
  • CAVEATS
  • SEE ALSO

NAME

Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.

SYNOPSIS

    sub Populate
    {
     my ($composite,$args) = @_;
     ...
     $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
     $composite->ConfigSpecs('-alias' => '-otherattribute');
     $composite->ConfigSpecs('DEFAULT' => [ where ]);
     $composite->ConfigSpecs($subwidget->ConfigSpecs);
     ...
    }

    $composite->configure(-attribute => value);

DESCRIPTION

The aim is to make the composite widget configure method look as much like a regular Tk widget's configure as possible. (See the Tk::options manpage for a description of this behaviour.) To enable this the attributes that the composite as a whole accepts needs to be defined.

Defining the ConfigSpecs for a class.

Typically a widget will have one or more calls like the following

    $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);

in its Populate method. When ConfigSpecs is called this way (with arguments) the arguments are used to construct or augment/replace a hash table for the widget. (More than one -option=>value pair can be specified to a single call.)

dbName, dbClass and default are only used by ConfigDefault described below, or to respond to 'inquiry' configure commands.

It may be either one of the values below, or a list of such values enclosed in [].

The currently permitted values of where are:

'ADVERTISED'

Apply configure to advertised subwidgets.

'DESCENDANTS'

Apply configure recursively to all descendants.

'CALLBACK'

Setting the attribute does Tk::Callback->new($value) before storing in $composite->{Configure}{-attribute}. This is appropriate for -command => ... attributes that are handled by the composite and not forwarded to a subwidget. (E.g. Tk::Tiler has -yscrollcommand to allow it to have scrollbar attached.)

This may be the first of several 'validating' keywords (e.g. font, cursor, anchor etc.) that core Tk makes special for C code.

'CHILDREN'

Apply configure to all children. (Children are the immediate descendants of a widget.)

'METHOD'

Call $cw->attribute(value)

This is the most general case. Simply have a method of the composite class with the same name as the attribute. The method may do any validation and have whatever side-effects you like. (It is probably worth 'queueing' using afterIdle for more complex side-effects.)

'PASSIVE'

Simply store value in $composite->{Configure}{-attribute}.

This form is also a useful placeholder for attributes which you currently only handle at create time.

'SELF'

Apply configure to the core widget (e.g. Frame) that is the basis of the composite. (This is the default behaviour for most attributes which makes a simple Frame behave the way you would expect.) Note that once you have specified ConfigSpecs for an attribute you must explicitly include 'SELF' in the list if you want the attribute to apply to the composite itself (this avoids nasty infinite recursion problems).

$reference (blessed)

Call $reference->configure(-attribute => value)

A common case is where $reference is a subwidget.

$reference may also be result of

     Tk::Config->new(setmethod,getmethod,args,...);

Tk::Config class is used to implement all the above keyword types. The class has configure and cget methods so allows higher level code to always just call one of those methods on an object of some kind.

hash reference

Defining:

        $cw->ConfigSpecs(
                ...
                -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
                                dbname dbclass default ],
                ...
                );

So $cw->configure(-option => value) actually does

        $w1->configure(-optionX => value);
        $w2->configure(-optionY => value);
        $w3->configure(-optionY => value);
'otherstring'

Call

    $composite->Subwidget('otherstring')->configure( -attribute => value );

While this is here for backward compatibility with Tk-b5, it is probably better just to use the subwidget reference directly. The only case for retaining this form is to allow an additional layer of abstraction - perhaps having a 'current' subwidget - this is unproven.

Aliases

ConfigSpecs( -alias => '-otherattribute' ) is used to make -alias equivalent to -otherattribute. For example the aliases

    -fg => '-foreground',
    -bg => '-background'

are provided automatically (if not already specified).

Delegating all options of a widget class to a subwidget

    $composite->ConfigSpecs($subwidget->ConfigSpecs);

The above generates a list of composite ConfigSpecs arguments, one for each valid option in $subwidget's class, and delegates said option to $subwidget. See the Tk::Widget manpage and the widget method ConfigSpecs. Duplicating composite ConfigSpecs and widget ConfigSpecs keys will yield undefined results.

Default values

When the Populate method returns ConfigDefault is called. This calls

    $composite->ConfigSpecs;

(with no arguments) to return a reference to a hash. Entries in the hash take the form:

    '-attribute' => [ where, dbName, dbClass, default ]

ConfigDefault ignores 'where' completely (and also the DEFAULT entry) and checks the 'options' database on the widget's behalf, and if an entry is present matching dbName/dbClass

    -attribute => value

is added to the list of options that new will eventually apply to the widget. Likewise if there is not a match and default is defined this default value will be added.

Alias entries in the hash are used to convert user-specified values for the alias into values for the real attribute.

New()-time configure

Once control returns to new, the list of user-supplied options augmented by those from ConfigDefault are applied to the widget using the configure method below.

Widgets are most flexible and most Tk-like if they handle the majority of their attributes this way.

Configuring composites

Once the above have occurred calls of the form:

    $composite->configure( -attribute => value );

should behave like any other widget as far as end-user code is concerned. configure will be handled by Tk::Derived::configure as follows:

    $composite->ConfigSpecs;

is called (with no arguments) to return a reference to a hash -attribute is looked up in this hash, if -attribute is not present in the hash then 'DEFAULT' is looked for instead. (Aliases are tried as well and cause redirection to the aliased attribute). The result should be a reference to a list like:

  [ where, dbName, dbClass, default ]

at this stage only where is of interest, it maps to a list of object references (maybe only one) foreach one

   $object->configure( -attribute => value );

is evaled.

Inquiring attributes of composites

   $composite->cget( '-attribute' );

This is handled by Tk::Derived::cget in a similar manner to configure. At present if where is a list of more than one object it is ignored completely and the "cached" value in

   $composite->{Configure}{-attribute}.

is returned.

CAVEATS

It is the author's intention to port as many of the "Tix" composite widgets as make sense. The mechanism described above may have to evolve in order to make this possible, although now aliases are handled I think the above is sufficient.

SEE ALSO

Tk::composite,
Tk::options,
the Tk::Widget manpage


Tk::DItem - Tix Display Items

  • DISPLAY ITEM TYPES AND OPTIONS
  • IMAGETEXT ITEMS
    • Imagetext Item Options
    • Imagetext Style Options
  • TEXT ITEMS
    • Text Item Options
    • Text Style Options
  • WINDOW ITEMS
    • Window Item Options
    • Window Style Options
  • CREATING DISPLAY ITEMS
  • CREATING AND MANIPULATING ITEM STYLES
  • SYNOPSIS
  • STYLE METHODS
  • EXAMPLE
  • SEE ALSO
  • KEYWORDS

NAME

Tk::DItem - Tix Display Items

SYNOPSIS

DESCRIPTION

The Tix Display Items and Display Types are devised to solve a general problem: many Tix widgets (both existing and planned ones) display many items of many types simultaneously.

For example, a hierarchical listbox widget (see the Tk::HList manpage) can display items of images, plain text and subwindows in the form of a hierarchy. Another widget, the tabular listbox widget (see the Tk::TList manpage) also displays items of the same types, although it arranges the items in a tabular form. Yet another widget, the spreadsheet widget (see the Tk::TixGrid manpage), also displays similar types items, but in yet another format.

In these examples, the display items in different widgets are only different in how they are arranged by the host widget. In Tix, display items are clearly separated from the host widgets. The advantage is two-fold: first, the creation and configuration of display items become uniform across different host widgets. Second, new display item types can be added without the need to modify the existing host widgets.

In a way, Tix display items are similar to the items inside Tk the canvas widget. However, unlike the Tix display items, the canvas items are not independent of the canvas widget; this makes it impossible to use the canvas items inside other types of TK widgets.

The appearance of a display item is controlled by a set of attributes. It is observed that each the attributes usually fall into one of two categroies: ``individual'' or ``collective''. For example, the text items inside a HList widget may all display a different text string; however, in most cases, the text items share the same color, font and spacing. Instead of keeping a duplicated version of the same attributes inside each display item, it will be advantageous to put the collective attributes in a special object called a display style. First, there is the space concern: a host widget may have many thousands of items; keeping dupilcated attributes will be very wasteful. Second, when it becomes necessary to change a collective attribute, such as changing all the text items' foreground color to red, it will be more efficient to change only the display style object than to modify all the text items one by one.

The attributes of the a display item are thus stored in two places: it has a set of item options to store its individual attributes. Each display item is also associated with a display style, which specifies the collective attributes of all items associated with itself.

The division between the individual and collective attributes are fixed and cannot be changed. Thus, when it becomes necessary for some items to differ in their collective attributes, two or more display styles can be used. For example, suppose you want to display two columns of text items inside an HList widget, one column in red and the other in blue. You can create a TextStyle object called ``$red'' which defines a red foreground, and another called ``$blue'', which defines a blue foreground. You can then associate all text items of the first column to ``$red'' and the second column to ``$blue''

DISPLAY ITEM TYPES AND OPTIONS

Currently there are three types of display items: text, imagetext and window.

IMAGETEXT ITEMS

Display items of the type imagetext are used to display an image together with a text string. Imagetext items support the following options:

Imagetext Item Options

Name: bitmap
Class: Bitmap
Switch: -bitmap

Specifies the bitmap to display in the item.

Name: image
Class: Image
Switch: -image

Specifies the image to display in the item. When both the -bitmap and -image options are specified, only the image will be displayed.

Name: imageTextStyle
Class: ImageTextStyle
Switch: -style

Specifies the display style to use for this item. Must be the name of a imagetext display style that has already be created with ItemStyle.

Name: showImage
Class: ShowImage
Switch: -showimage

A Boolean value that specifies whether the image/bitmap should be displayed.

Name: showText
Class: ShowText
Switch: -showtext

A Boolean value that specifies whether the text string should be displayed.

Name: text
Class: Text
Switch: -text

Specifies the text string to display in the item.

Name: underline
Class: Underline
Switch: -underline

Specifies the integer index of a character to underline in the text string in the item. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.

Imagetext Style Options

The style information of imagetext items are stored in the imagetext display style. The following options are supported:

STANDARD OPTIONS

-activebackground | -activeforeground
-anchor | -background
-disabledbackground | -disabledforeground
-foreground | -font
-justify | -padx
-pady | -selectbackground
-selectforeground | -wraplength

See the Tk::options manpage for details of the standard options.

STYLE-SPECIFIC OPTIONS

Name: gap
Class: Gap
Switch: -gap

Specifies the distance between the bitmap/image and the text string, in number of pixels.

Name: textAnchor
Class: TextAnchor
Switch: -textanchor

The anchor position on the image to which text part is attached. This is a perl/Tk addition. Defaults to e for compatibility with standard Tix. The interesting cases are

n

Text is centred above the image.

s

Text is centred below the image

e

Text is centred to right of the image.

w

Text is centred to left of the image.

c

Text is centred over the image.

The sw, se, ne, and b<nw> cases look rather odd.

To get items to line up correctly it will usually be necessary to specify -anchor as well. e.g. with default e then anchoring item as a whole w lines images up down left with text stuck to right side.

TEXT ITEMS

Display items of the type text are used to display a text string in a widget. Text items support the following options:

Text Item Options

Name: textStyle
Class: TextStyle
Switch: -style

Specifies the display style to use for this text item. Must be the name of a text display style that has already be created with ItemStyle.

Name: text
Class: Text
Switch: -text

Specifies the text string to display in the item.

Name: underline
Class: Underline
Switch: -underline

Specifies the integer index of a character to underline in the item. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.

Text Style Options

STANDARD OPTIONS

-activebackground | -activeforeground
-anchor | -background
-disabledbackground | -disabledforeground
-foreground | -font
-justify | -padx
-pady | -selectbackground
-selectforeground | -wraplength

See the Tk::options manpage for details of the standard options.

WINDOW ITEMS

Display items of the type window are used to display a sub-window in a widget. Window items support the following options:

Window Item Options

Name: windowStyle
Class: WindowStyle
Switch: -style

Specifies the display style to use for this window item. Must be the name of a window display style that has already be created with the ItemStyle method.

Name: window
Class: Window
Switch: -window
Alias: -widget

Specifies the sub-window to display in the item.

Window Style Options

STYLE STANDARD OPTIONS

-anchor -padx -pady

See the Tk::options manpage for details of the standard options.

CREATING DISPLAY ITEMS

Display items do not exist on their and thus they cannot be created independently of the widgets they reside in. As a rule, display items are created by special methods of their ``host'' widgets. For example, the HList widgets has a method item which can be used to create new display items. The following code creates a new text item at the third column of the entry foo inside an HList widget:

 my $hlist = $parent->HList(-columns=>3);
 $hlist->add('foo');
 $hlist->itemCreate('foo', 2, -itemtype=>'text', -text=>'Hello');

The itemCreate method of the HList widget accepts a variable number of arguments. The special argument -itemtype specifies which type of display item to create. Options that are valid for this type of display items can then be specified by one or more option-value pairs.

After the display item is created, they can then be configured or destroyed using the methods provided by the host widget. For example, the HList widget has the methods itemConfigure, itemCget and itemDelete for accessing the display items.

CREATING AND MANIPULATING ITEM STYLES

Item styles are created with ItemStyle:

SYNOPSIS

$widget->ItemStyle(itemType ?,-stylename=>name? ?,-refwindow=>pathName? ?,option=>value, ...>?);

itemType must be one of the existing display items types such as text, imagetext, window or any new types added by the user. Additional arguments can be given in one or more option-value pairs. option can be any of the valid option for this display style or any of the following:

-stylename => name

Specifies a name for this style. If unspecified, then a default name will be chosen for this style.

-refwindow => $otherwidget

Specifies a window to use for determine the default values of the display type. If unspecified, the $widget will be used. Default values for the display types can be set via the options database. The following example sets the -disablebackground and -disabledforeground options of a text display style via the option database:

  $widget->optionAdd('*table.list*disabledForeground' => 'blue');
  $widget->optionAdd('*table.list*disabledBackground' => 'darkgray');
  $widget->ItemStyle('text', -refwindow => $table_list, -fg => 'red');

By using the option database to set the options of the display styles, we can advoid hard-coding the option values and give the user more flexibility in customization. See the Tk::option manpage for a detailed description of the option database.

STYLE METHODS

The ItemStyle method creates an object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above.

The following additional methods are available for item styles:

$style->delete

Destroy this display style object.

EXAMPLE

The following example creates two columns of data in a HList widget. The first column is in red and the second column in blue. The colors of the columns are controlled by two different text styles. Also, the anchor and font of the second column is chosen so that the income data is aligned properly.

   use strict;
   use Tk;
   use Tk::HList;
   use Tk::ItemStyle;

   my $mw = MainWindow->new();

   my $hlist = $mw->HList(-columns=>2)->pack;

   my $red  = $hlist->ItemStyle('text', -foreground=>'#800000');
   my $blue = $hlist->ItemStyle('text', -foreground=>'#000080', -anchor=>'e');

   my $e;
   foreach ([Joe => '$10,000'], [Peter => '$20,000'],
            [Raj => '$90,000'],  [Zinh => '$0']) {
       $e = $hlist->addchild("");
       $hlist->itemCreate($e, 0, -itemtype=>'text',
                -text=>$_->[0], -style=>$red );
       $hlist->itemCreate($e, 1, -itemtype=>'text',
                -text=>$_->[1], -style=>$blue);
   }

   Tk::MainLoop;

SEE ALSO

Tk::HList
Tk::TixGrid
Tk::TList

KEYWORDS

display item, display style, item style


Tk::Derived - Base class for widgets derived from others

  • SEE ALSO

NAME

Tk::Derived - Base class for widgets derived from others

SYNOPSIS

    package Tk::MyNewWidget;

    use Tk::widgets qw/ BaseWidget, list of Tk widgets /;
    use base qw/ Tk::Derived Tk::BaseWidget /;

    Construct Tk::Widget 'MyNewWidget';

    sub ClassInit {
        my( $class, $mw ) = @_;
        #... e.g., class bindings here ...
        $class->SUPER::ClassInit( $mw );
    }

    sub Populate {
        my( $self, $args ) = @_;

        my $flag = delete $args->{-flag};
        if( defined $flag ) {
            # handle -flag => xxx which can only be done at create
            # time the delete above ensures that new() does not try
            # and do  $self->configure( -flag => xxx );
        }

        $self->SUPER::Populate( $args );

        $self = $self->Component( ... );

        $self->Delegates( ... );

        $self->ConfigSpecs(
            '-cursor'    => [ SELF, 'cursor', 'Cursor',   undef ],
            '-something' => [ METHOD, dbName,  dbClass, default ],
            '-text'      => [ $label, dbName,  dbClass, default ],
            '-heading'   => [ {-text => $head},
                                heading, Heading,  'My Heading' ],
               );
           }

   sub something {
       my( $self, $value) = @_;
       if ( @_ > 1 ) {
          # set it
       }
       return # current value
   }

DESCRIPTION

Tk::Derived is used with Perl's multiple inheritance to override some methods normally inherited from Tk::Widget.

Tk::Derived should precede any Tk widgets in the class's base class definition.

Tk::Derived's main purpose is to apply wrappers to configure and cget methods of widgets to allow the derived widget to add to or modify behaviour of the configure options supported by the base widget.

The derived class should normally override the Populate method provided by Tk::Derived and call ConfigSpecs to declare configure options.

The public methods provided by Tk::Derived are as follows:

->ConfigSpecs(-key => [kind, name, Class, default], ...)

SEE ALSO

Tk::ConfigSpecs
Tk::mega
Tk::composite


Tk::Dialog - Create modal dialog and wait for a response.

  • OPTIONS
  • METHODS
  • ADVERTISED WIDGETS
  • EXAMPLE
  • KEYWORDS

NAME

Tk::Dialog - Create modal dialog and wait for a response.

SYNOPSIS

$dialog = $parent->Dialog(-option => value, ... );

DESCRIPTION

This procedure is part of the Tk script library - its arguments describe a dialog box. After creating a dialog box, Dialog waits for the user to select one of the Buttons either by clicking on the Button with the mouse or by typing return to invoke the default Button (if any). Then it returns the text string of the selected Button.

While waiting for the user to respond, Dialog sets a local grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. See the Show() method.

OPTIONS

The following option/value pairs are supported:

-title

Text to appear in the window manager's title bar for the dialog.

-text

Message to appear in the top portion of the Dialog.

-bitmap

If non-empty, specifies a bitmap to display in the top portion of the Dialog, to the left of the text. If this is an empty string then no bitmap is displayed in the Dialog.

-default_button

Text label string of the Button that displays the default ring.

-buttons

A reference to a list of Button label strings. Each string specifies text to display in a Button, in order from left to right.

METHODS

$answer = $dialog->Show(?-global?);

This method displays the Dialog, waits for the user's response, and stores the text string of the selected Button in $answer. If -global is specified a global (rather than local) grab is performed.

The actual Dialog is shown using the Popup method. Any other options supplied to Show are passed to Popup, and can be used to position the Dialog on the screen. Please read Tk::Popup for details.

ADVERTISED WIDGETS

Because Tk::Dialog is a subclass of Tk::DialogBox it inherits all the advertised subwidgets of its superclass: e.g. "B_button-text", where 'button-text' is a Button's -text value. Additionally, Tk::Dialog advertises:

message

The dialog's Label widget containing the message text.

bitmap

The dialog's Label widget containing the bitmap image.

EXAMPLE

$dialog = $mw->Dialog(-text => 'Save File?', -bitmap => 'question', -title => 'Save File Dialog', -default_button => 'Yes', -buttons => [qw/Yes No Cancel/);

KEYWORDS

bitmap, dialog, modal, messageBox


Tk::DialogBox - create and manipulate a dialog screen.

  • OPTIONS
  • METHODS
  • ADVERTISED WIDGETS
  • ADVERTISED WIDGETS
  • BUGS
  • AUTHOR

NAME

Tk::DialogBox - create and manipulate a dialog screen.

SYNOPSIS

    use Tk::DialogBox
    ...
    $d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]);
    $w = $d->add(Widget, args);
    ...
    $button = $d->Show;

DESCRIPTION

DialogBox is very similar to Dialog except that it allows any widget in the top Frame. DialogBox creates two Frames, top and bottom. The bottom Frame shows all the specified Buttons, lined up from left to right. The top Frame acts as a container for all other widgets that can be added with the add() method.

OPTIONS

The options recognized by DialogBox are as follows:

-title

Specify the title of the DialogBox. If this is not set, then the name of the program is used.

-buttons

The button names to display in the bottom Frame. This is a reference to an array of strings containing the text to put on each Button. There is no default value for this. If you do not specify any button names, no Buttons are displayed.

-default_button

Specifies the default Button that is considered invoked when user presses <Return> on the DialogBox. This Button is highlighted. If no default Button is specified, then the first element of the array whose reference is passed to the -buttons option is used as the default.

-command

A callback which is executed after invoking an action to close the DialogBox, but before restoring focus and grab information. The selected button is passed as the first argument.

-focus

Specify the widget to receive the initial focus after popping up the DialogBox. By default the -default_button widget receives the initial focus.

-showcommand

A callback which is executed before displaying the DialogBox and waiting for user input. The DialogBox itself is passed as the first argument.

METHODS

DialogBox supports only two methods as of now:

add(widget, options)

Add the widget indicated by widget. Widget can be the name of any Tk widget (standard or contributed). options are the options that the widget accepts. The widget is advertized as a subwidget of DialogBox. The first character of widget is lower-cased and used as the advertised name.

Show(?-global?)

Displays the Dialog until the user invokes one of the Buttons in the bottom Frame. If the grab type -global is specified, then Show uses that grab; otherwise it defaults to a local grab. Returns the name of the Button invoked.

The actual Dialog is shown using the Popup method. Any other options supplied to Show are passed to Popup, and can be used to position the Dialog on the screen. Please read Tk::Popup for details.

ADVERTISED WIDGETS

top

The subwidget reference to the top half of the DialogBox widget, the Frame containing widgets added by the add method.

bottom

The subwidget reference to the bottom half of the DialogBox widget, the Frame containing the Button widgets.

B_"button-text"

Individual subwidget references to the Buttons in the DialogBox widget. The subwidget name is the string B_ concatenated with the Button's -text value.

ADVERTISED WIDGETS

top

The subwidget reference to the top half of the DialogBox widget, the Frame containing widgets added by the add method.

bottom

The subwidget reference to the bottom half of the DialogBox widget, the Frame containing the Button widgets.

B_"button-text"

Individual subwidget references to the Buttons in the DialogBox widget. The subwidget name is the string B_ concatenated with the Button's -text value.

BUGS

There is no way of removing a widget once it has been added to the top Frame, unless you access the top subwidget and go through the child widgets.

There is no control over the appearance of the Buttons in the bottom Frame nor is there any way to control the placement of the two Frames with respect to each other.

AUTHOR

Rajappa Iyer rsi@earthling.net

This code is distributed under the same terms as Perl.


Tk::DirTree - Create and manipulate DirTree widgets

  • SUPER-CLASS
  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS
  • SEE ALSO
  • AUTHOR

NAME

Tk::DirTree - Create and manipulate DirTree widgets

SYNOPSIS

use Tk::DirTree;

$dirtree = $parent->DirTree(?options?);

SUPER-CLASS

The DirTree class is derived from the Tree class and inherits all the methods, options and subwidgets of its super-class.

STANDARD OPTIONS

Tree supports all the standard options of a Tree widget. See the Tk::options manpage for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name: browseCmd
Class: BrowseCmd
Switch: -browsecmd

Specifies a callback to call whenever the user browses on a directory (usually by single-clicking on the name of the directory). The callback is called with one argument, the complete pathname of the directory.

Name: command
Class: Command
Switch: -command

Specifies the callback to be called when the user activates on a directory (usually by double-clicking on the name of the directory). The callback is called with one argument, the complete pathname of the directory.

Name: dircmd
Class: DirCmd
Switch: -dircmd

Specifies the callback to be called when a directory listing is needed for a particular directory. If this option is not specified, by default the DirTree widget will attempt to read the directory as a Unix directory. On special occasions, the application programmer may want to supply a special method for reading directories: for example, when he needs to list remote directories. In this case, the -dircmd option can be used. The specified callback accepts two arguments: the first is the name of the directory to be listed; the second is a Boolean value indicating whether hidden sub-directories should be listed. This callback returns a list of names of the sub-directories of this directory. For example:

    sub read_dir {
        my( $dir, $showhidden ) = @_;
        return( qw/DOS NORTON WINDOWS/ ) if $dir eq "C:\\";
        return();
    }
Name: showHidden
Class: ShowHidden
Switch: -showhidden

Specifies whether hidden directories should be shown. By default, a directory name starting with a period "." is considered as a hidden directory. This rule can be overridden by supplying an alternative -dircmd option.

Name: directory
Class: Directory
Switch: -directory
Alias: -value

Specifies the name of the current directory to be displayed in the DirTree widget.

DESCRIPTION

The DirTree constructor method creates a new window (given by the $dirtree argument) and makes it into a DirTree widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the DirTree such as its cursor and relief. The DirTree widget displays a list view of a directory, its previous directories and its sub-directories. The user can choose one of the directories displayed in the list or change to another directory.

WIDGET METHODS

The DirTree method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for DirTree widgets:

$dirtree->chdir(dir)

Change the current directory to dir.

BINDINGS

The mouse and keyboard bindings of the DirTree widget are the same as the bindings of the Tree widget.

KEYWORDS

directory, tree, tix

SEE ALSO

Tk::Tree Tk::HList

AUTHOR

Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix version by Ioi Kim Lam.


Tk::DropSite - Receive side of Drag & Drop abstraction

NAME

Tk::DropSite - Receive side of Drag & Drop abstraction

SYNOPSIS

 use Tk::DropSite qw(...);
 $widget->DropSite(-entercommand => ...,
                   -dropcommand  => ...,
                   -motioncommand  => ...,
                   -dropcommand  => ...,
                  );

DESCRIPTION

DropSite creates an object which represents a site on which things may be "Dropped".

A DropSite provides the following methods:

$site->Enter($token,$event)
$site->Leave($token,$event)
$site->Motion($token,$event)
$site->Drop($token,$event)


Tk::Entry - Create and manipulate Entry widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • VALIDATION
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • KEYWORDS

NAME

Tk::Entry - Create and manipulate Entry widgets

SYNOPSIS

$entry = $parent->Entry(?options?);

STANDARD OPTIONS

-background | -highlightbackground | -insertontime | -selectforeground
-borderwidth | -highlightcolor | -insertwidth | -takefocus
-cursor | -highlightthickness | -justify | -textvariable
-exportselection | -insertbackground | -relief | -xscrollcommand
-font | -insertborderwidth | -selectbackground
-foreground | -insertofftime | -selectborderwidth

WIDGET-SPECIFIC OPTIONS

Command-Line Name: -disabledbackground
Database Name: disabledBackground
Database Class: DisabledBackground

Specifies the background color to use when the entry is disabled. If this option is the empty string, the normal background color is used.

Command-Line Name: -disabledforeground
Database Name: disabledForeground
Database Class: DisabledForeground

Specifies the foreground color to use when the entry is disabled. If this option is the empty string, the normal foreground color is used.

Name: invalidCommand
Class: InvalidCommand
Switch: -invalidcommand
Alias: -invcmd

Specifies a script to eval when validateCommand returns 0. Setting it to <undef> disables this feature (the default). The best use of this option is to set it to bell. See Validation below for more information.

Command-Line Name: -readonlybackground
Database Name: readonlyBackground
Database Class: ReadonlyBackground

Specifies the background color to use when the entry is read-only. If this option is the empty string, the normal background color is used.

Name: show
Class: Show
Switch: -show

If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as ``*''. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry.

Name: state
Class: State
Switch: -state

Specifies one of three states for the entry: normal, disabled, or readonly. If the entry is readonly, then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the entry is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the entry may be displayed in a different color, depending on the values of the -disabledforeground and -disabledbackground options.

Name: validate
Class: Validate
Switch: -validate

Specifies the mode in which validation should operate: none, focus, focusin, focusout, key, or all. It defaults to none. When you want validation, you must explicitly state which mode you wish to use. See Validation below for more.

Name: validateCommand
Class: ValidateCommand
Switch: -validatecommand
Alias: -vcmd

Specifies a script to eval when you want to validate the input into the entry widget. Setting it to undef disables this feature (the default). This command must return a valid boolean value. If it returns 0 (or the valid boolean equivalent) then it means you reject the new edition and it will not occur and the invalidCommand will be evaluated if it is set. If it returns 1, then the new edition occurs. See Validation below for more information.

Name: width
Class: Width
Switch: -width

Specifies an integer value indicating the desired width of the entry window, in average-size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text.

DESCRIPTION

The Entry method creates a new window (given by the $entry argument) and makes it into an entry widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the entry such as its colors, font, and relief. The entry command returns its $entry argument. At the time this command is invoked, there must not exist a window named $entry, but $entry's parent must exist.

An entry is a widget that displays a one-line text string and allows that string to be edited using methods described below, which are typically bound to keystrokes and mouse actions. When first created, an entry's string is empty. A portion of the entry may be selected as described below. If an entry is exporting its selection (see the exportSelection option), then it will observe the standard X11 protocols for handling the selection; entry selections are available as type STRING. Entries also observe the standard Tk rules for dealing with the input focus. When an entry has the input focus it displays an insertion cursor to indicate where new characters will be inserted.

Entries are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; methods described below may be used to change the view in the window. Entries use the standard xScrollCommand mechanism for interacting with scrollbars (see the description of the -xscrollcommand option for details). They also support scanning, as described below.

VALIDATION

Validation of entry widgets is derived from part of the patch written by jhobbs@cs.uoregon.edu. This works by setting the validateCommand option to a callback which will be evaluated according to the validate option as follows:

none

Default. This means no validation will occur.

focus

validateCommand will be called when the entry receives or loses focus.

focusin

validateCommand will be called when the entry receives focus.

focusout

validateCommand will be called when the entry loses focus.

key

validateCommand will be called when the entry is edited.

all

validateCommand will be called for all above conditions.

The validateCommand and invalidCommand are called with the following arguments:

  • The proposed value of the entry. If you are configuring the entry widget to have a new textvariable, this will be the value of that textvariable.
  • The characters to be added (or deleted). This will be undef if validation is due to focus, explcit call to validate or if change is due to -textvariable changing.
  • The current value of entry i.e. before the proposed change.
  • index of char string to be added/deleted, if any. -1 otherwise
  • type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced validation or textvariable validation

In general, the textVariable and validateCommand can be dangerous to mix. If you try set the textVariable to something that the validateCommand will not accept it will be set back to the value of the entry widget. Using the textVariable for read-only purposes will never cause problems.

The validateCommand will turn itself off by setting validate to none when an error occurs, for example when the validateCommand or invalidCommand encounters an error in its script while evaluating, or validateCommand does not return a valid boolean value.

With the perl/Tk version validate option is supposed to be "suspended" while executing the validateCommand or the invalidCommand. This is experimental but in theory either callback can "correct" the value of the widget, and override the proposed change. (validateCommand should still return false to inhibit the change from happening when it returns.)

WIDGET METHODS

The Entry method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

Many of the additional methods for entries take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways:

number

Specifies the character as a numerical index, where 0 corresponds to the first character in the string.

anchor

Indicates the anchor point for the selection, which is set with the selectionFrom and selectionAdjust methods.

end

Indicates the character just after the last one in the entry's string. This is equivalent to specifying a numerical index equal to the length of the entry's string.

insert

Indicates the character adjacent to and immediately following the insertion cursor.

sel.first

Indicates the first character in the selection. It is an error to use this form if the selection isn't in the entry window.

sel.last

Indicates the character just after the last one in the selection. It is an error to use this form if the selection isn't in the entry window.

@number

In this form, number is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, ``@0'' indicates the left-most character in the window.

Abbreviations may be used for any of the forms above, e.g. ``e'' or ``sel.f''. In general, out-of-range indices are automatically rounded to the nearest legal value.

The following additional methods are available for entry widgets:

$entry->bbox(index)

Returns a list of four numbers describing the bounding box of the character given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window.

$entry->delete(first, ?last?)

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the entry command.

$entry->configure(?option?, ?value, option, value, ...?)

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for $entry (see the Tk::configure manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the entry command.

$entry->delete(first, ?last?)

Delete one or more elements of the entry. First is the index of the first character to delete, and last is the index of the character just after the last one to delete. If last isn't specified it defaults to first+1, i.e. a single character is deleted. This method returns an empty string.

$entry->get

Returns the entry's string.

$entry->icursor(index)

Arrange for the insertion cursor to be displayed just before the character given by index. Returns an empty string.

$entry->index(index)

Returns the numerical index corresponding to index.

$entry->insert(index, string)

Insert the characters of string just before the character indicated by index. Returns an empty string.

$entry->scan(option, args)
$entry->scan Option(args)

This method is used to implement scanning on entries. It has two forms, depending on Option:

$entry->scanMark(x)

Records x and the current view in the entry widget; used in conjunction with later scanDragto methods. Typically this method is associated with a mouse button press in the widget. It returns an empty string.

$entry->scanDragto(x)

This method computes the difference between its x argument and the x argument to the last scanMark method for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This method is typically associated with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the widget. The return value is an empty string.

$entry->selection(option, arg)
$entry->selection Option(arg)

This method is used to adjust the selection within an entry. It has several forms, depending on Option:

$entry->selectionAdjust(index)

Locate the end of the selection nearest to the character given by index, and adjust that end of the selection to be at index (i.e including but not going beyond index). The other end of the selection is made the anchor point for future selectionTo methods. If the selection isn't currently in the entry, then a new selection is created to include the characters between index and the most recent selection anchor point, inclusive. Returns an empty string.

$entry->selectionClear

Clear the selection if it is currently in this widget. If the selection isn't in this widget then the method has no effect. Returns an empty string.

$entry->selectionFrom(index)

Set the selection anchor point to just before the character given by index. Doesn't change the selection. Returns an empty string.

$entry->selectionPresent

Returns 1 if there is are characters selected in the entry, 0 if nothing is selected.

$entry->selectionRange(start, end)

Sets the selection to include the characters starting with the one indexed by start and ending with the one just before end. If end refers to the same character as start or an earlier one, then the entry's selection is cleared.

$entry->selectionTo(index)

If index is before the anchor point, set the selection to the characters from index up to but not including the anchor point. If index is the same as the anchor point, do nothing. If index is after the anchor point, set the selection to the characters from the anchor point up to but not including index. The anchor point is determined by the most recent selectionFrom or selectionAdjust method in this widget. If the selection isn't in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string.

$entry->validate

This command is used to force an evaluation of the validateCommand independent of the conditions specified by the validate option. It returns 0 or 1.

$entry->xview(args)

This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms:

$entry->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .7, 20% of the entry's text is off-screen to the left, the middle 50% is visible in the window, and 30% of the text is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$entry->xview(index)

Adjusts the view in the window so that the character given by index is displayed at the left edge of the window.

$entry->xviewMoveto(fraction)

Adjusts the view in the window so that the character fraction of the way through the text appears at the left edge of the window. Fraction must be a fraction between 0 and 1.

$entry->xviewScroll(number, what)

This method shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number average-width characters on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

DEFAULT BINDINGS

Tk automatically creates class bindings for entries that give them the following default behavior. In the descriptions below, ``word'' refers to a contiguous group of letters, digits, or ``_'' characters, or any single character other than these.

[1]

Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.

[2]

Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word. Dragging after a double click will stroke out a selection consisting of whole words.

[3]

Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insertion cursor before the first character.

[4]

The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words.

[5]

Clicking mouse button 1 with the Control key down will position the insertion cursor in the entry without affecting the selection.

[6]

If any normal printing characters are typed in an entry, they are inserted at the point of the insertion cursor.

[7]

The view in the entry can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor.

[8]

If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).

[9]

The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the entry and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.

[10]

The Home key, or Control-a, will move the insertion cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insertion cursor to the beginning of the entry and also extends the selection to that point.

[11]

The End key, or Control-e, will move the insertion cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point.

[12]

The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They don't affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.

[13]

Control-/ selects all the text in the entry.

[14]

Control-\ clears any selection in the entry.

[15]

The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

[16]

The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect.

[17]

The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor.

[18]

The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insertion cursor.

[19]

The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insertion cursor.

[20]

Control-d deletes the character to the right of the insertion cursor.

[21]

Meta-d deletes the word to the right of the insertion cursor.

[22]

Control-k deletes all the characters to the right of the insertion cursor.

[23]

Control-t reverses the order of the two characters to the right of the insertion cursor.

If the entry is disabled using the -state option, then the entry's view can still be adjusted and text in the entry can still be selected, but no insertion cursor will be displayed and no text modifications will take place.

The behavior of entries can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

entry, widget


Tk::Error - Method invoked to process background errors

  • Tk::ErrorDialog
    • Advertised ErrorDialog widgets
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Error - Method invoked to process background errors

SYNOPSIS

Customization:

    require Tk::ErrorDialog;

or

    sub Tk::Error
    {
      my ($widget,$error,@locations) = @_;
      ...

    }

DESCRIPTION

The Tk::Error method is invoked by perl/Tk when a background error occurs. Two possible implementations are provided in the distribution and individual applications or users can (re)define a Tk::Error method (e.g. as a perl sub) if they wish to handle background errors in some other manner.

A background error is one that occurs in a command that didn't originate with the application. For example, if an error occurs while executing a callback specified with a bind or a after command, then it is a background error. For a non-background error, the error can simply be returned up through nested subroutines until it reaches the top-level code in the application; then the application can report the error in whatever way it wishes. When a background error occurs, the unwinding ends in the Tk library and there is no obvious way for Tk to report the error.

When Tk detects a background error, it saves information about the error and invokes the Tk::Error method later when Tk is idle.

Tk::Error is invoked by perl/Tk as if by the perl code:

$mainwindow->Tk::Error("error message", location ...);

$mainwindow is the MainWindow associated with widget which detected the error, "error message" is a string describing the error that has been detected, location is a list of one or more "locations" which describe the call sequence at the point the error was detected.

The locations are a typically a mixture of perl location reports giving script name and line number, and simple strings describing locations in core Tk or perl/Tk C code.

Tk will ignore any result returned by the Tk::Error method. If another error occurs within the Tk::Error method (for example if it calls die) then Tk reports this error itself by writing a message to stderr (this is to avoid infinite loops due to any bugs in Tk::Error).

If several background errors accumulate before Tk::Error is invoked to process them, Tk::Error will be invoked once for each error, in the order they occurred. However, if Tk::Error calls Tk->break, then any remaining errors are skipped without calling Tk::Error.

The Tk module includes a default Tk::Error subroutine that simply reports the error on stderr.

Tk::ErrorDialog

An alternate definition is provided via:

require Tk::ErrorDialog;

that posts a dialog box containing the error message and offers the user a chance to see a stack trace showing where the error occurred.

This is an OO implementation of the Tcl/Tk command bgerror, with a twist: since there is only one ErrorDialog widget, you aren't required to invoke the constructor to create it; it will be created automatically when the first background error occurs. However, in order to configure the -cleanupcode and -appendtraceback ErrorDialog options you must call the constructor and create it manually.

The ErrorDialog object essentially consists of two subwidgets: a Dialog widget to display the background error and a Text widget for the traceback information. If required, you can invoke various widget methods to customize these subwidgets - their advertised names are described below.

$mw->ErrorDialog(-cleanupcode => code, -appendtraceback => bool);

$mw is a window reference.

code is a CODE reference if special post-background error processing is required (default is undefined). The callback subroutine is called with @_ having the same arguments that Tk::Error was invoked with.

bool is a boolean indicating whether or not to append successive tracebacks (default is 1, do append).

Advertised ErrorDialog widgets

error_dialog is the Dialog widget reference.

text is the Text widget reference containing the traceback information.

BUGS

If after or fileevent are not invoked as methods of a widget then perl/Tk is unable to provide a $mainwindow argument. To support such code from earlier versions of perl/Tk perl/Tk therefore calls Tk::Error with string 'Tk' instead: Tk->Tk::Error\(...\). In this case the Tk::Error in Tk::ErrorDialog and similar implementations cannot "popup" a window as they don't know which display to use. A mechanism to supply the MainWindow in applications which only have one (a very common case) should be provided.

SEE ALSO

Tk::bind
Tk::after
Tk::fileevent

KEYWORDS

background error, reporting


Tk::Event - ToolKit for Events

NAME

Tk::Event - ToolKit for Events

SYNOPSIS

 use Tk::Event;

 Tk::Event->fileevent(\*FH, 'readable' => callback);

 Tk::Event->lineavail(\*FH, callback);

 use Tk::Event::Signal qw(INT);

 $SIG{'INT'} = callback;

 use Tk::Event::process;

 Tk::Event->proc($pid, callback);

 QueueEvent(callback [, position])

DESCRIPTION

That is better than nothing but still hard to use. Most scripts want higher level result (a line, a "block" of data etc.)

So it has occured to me that we could use new-ish TIEHANDLE thus:

my $obj = tie SOMEHANDLE,Tk::Event::IO;

while (<SOMEHANDLE>)
 {
 }

Then the READLINE routine registers a callback and looks something like:

sub READLINE
 {
  my $obj = shift;
  Event->io(*$obj,'readable',sub { sysread(*$obj,${*$obj},1,length(${*$obj}) });
  my $pos;
  while (($pos = index(${*$obj},$/) < 0)
   {
    DoOneEvent();
   }
  Event->io(*$obj,'readable',''); # unregister
  $pos += length($/);
  my $result = substr(${*$obj},0,$pos);
  substr(${*$obj},0,$pos) = '';
  return $result;
 }

This is using the scalar part of the glob representing the _inner_ IO as a buffer in which to accumulate chars.


Tk::FBox - a file dialog

  • COPYRIGHT
  • SEE ALSO

NAME

Tk::FBox - a file dialog

SYNOPSIS

    use Tk::FBox;
    $file = $mw->FBox(...)->Show;

DESCRIPTION

Tk::FBox is the dialog implementation behind the getOpenFile and getSaveFile method calls in the Unix/X11 world. As such, it supports all options for these methods and additionally:

-sortcmd => sub { $_[0] cmp $_[1] }

Specified a callback for changing the sorting of the icons in the IconList widget. By default, perl's cmp operator will be used.

From the source code:

  # Using -sortcmd is really strange :-(
  # $top->getOpenFile(-sortcmd => sub { package Tk::FBox; uc $b cmp uc $a});
  # or, un-perlish, but useable (now activated in code):
  # $top->getOpenFile(-sortcmd => sub { uc $_[1] cmp uc $_[0]});

This is an experimental option!

-type => $type

Type should be "open" (default) or "save".

-filter => $glob

To be documented...

-force => $bool

If true, then there will be no dialog if a file already exists.

COPYRIGHT

The original tkfbox.tcl from Tcl/Tk is:

Copyright (c) 1994-1996 Sun Microsystems, Inc.

See the file "license.terms" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.

Translated to Perl/Tk by Slaven Rezic <slaven.rezic@berlin.de>.

SEE ALSO

Tk::getOpenFile, Tk::IconList.


Tk::FileSelect - a widget for choosing files

  • AUTHORS
  • HISTORY
    • 950621 - The following changes were made:
    • 95/10/17, SOL, LUCC. lusol@Lehigh.EDU
    • 961008 - derf@ti.com :

NAME

Tk::FileSelect - a widget for choosing files

SYNOPSIS

 use Tk::FileSelect;

 $FSref = $top->FileSelect(-directory => $start_dir);
               $top            - a window reference, e.g. MainWindow->new
               $start_dir      - the starting point for the FileSelect
 $file = $FSref->Show;
               Executes the fileselector until either a filename is
               accepted or the user hits Cancel. Returns the filename
               or the empty string, respectively, and unmaps the
               FileSelect.
 $FSref->configure(option => value[, ...])
               Please see the Populate subroutine as the configuration
               list changes rapidly.

DESCRIPTION

This Module pops up a Fileselector box, with a directory entry on top, a list of directories in the current directory, a list of files in the current directory, an entry for entering/modifying a file name, an accept button and a cancel button.

You can enter a starting directory in the directory entry. After hitting Return, the listboxes get updated. Double clicking on any directory shows you the respective contents. Single clicking on a file brings it into the file entry for further consideration, double clocking on a file pops down the file selector and calls the optional command with the complete path for the selected file. Hitting return in the file selector box or pressing the accept button will also work. *NOTE* the file selector box will only then get destroyed if the file name is not zero length. If you want yourself take care of it, change the if(length(.. in sub accept_file.

AUTHORS

Based on original FileSelect by Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich, April 22, 1995 adapted by Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas, 21Jun95

HISTORY

950621 -- The following changes were made:

  • Rewrote Tk stuff to take advantage of new Compound widget module, so FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2 subwidgets.

  • Moved entry labels (from to the left of) to above the entry fields.

  • Caller is now able to control these aspects of widget, in both FileSelect (new) and configure :

    (Please see subroutine Populate for details, as these options change rapidly!)

  • I changed from Double-Button-1 to Button-1 in the Files listbox, to work with multiple mode in addition to browse mode. I also made some name changes (LastPath --> saved_path, ...).

  • The show method is not yet updated.

  • The topLevel stuff is not done yet. I took it out while I toy with the idea of FileSelect as a subwidget. Then the 'normal' topLevel thing with Buttons along the bottom could be build on top of it.

  • By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality of using the Directory entry as a filter. So, if you want to only see the *.c files, you add a .c (the *'s already there :) and hit return.

95/10/17, SOL, LUCC. lusol@Lehigh.EDU

  •  Allow either file or directory names to be accepted.

  • Require double click to move into a new directory rather than a single click. This allows a single click to select a directory name so it can be accepted.

  • Add -verify list option so that standard Perl file test operators (like -d and -x) can be specified for further name validation. The default value is the special value '!-d' (not a directory), so any name can be selected as long as it's not a directory - after all, this IS FileSelect!

    For example:

        $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]);

    ensures that the selected name is a directory. Further, if an element of the list is an array reference, the first element is a code reference to a subroutine and the remaining optional elements are it's parameters. The subroutine is called like this:

        &verify_code($cd, $leaf, $P1, $P2, ... $Pn);

    where $cd is the current directory, $leaf is a directory or file name, and $P1 .. $Pn are your optional parameters. The subroutine should return TRUE if success or FALSE if failure.

961008 -- derf@ti.com :

By request of Jim Stern <js@world.northgrum.com> and Brad Vance <bvance@ti.com>, I updated the Accept and Show functions to support selection of multiple files. I also corrected a typo in the -verify code.


font - Create and inspect fonts.

  • FONT DESCRIPTION
  • FONT METRICS
  • FONT OPTIONS
  • PLATFORM-SPECIFIC ISSUES
  • COMPATIBILITY WITH PREVIOUS VERSIONS
  • SEE ALSO
  • KEYWORDS

NAME

font - Create and inspect fonts.

SYNOPSIS

$widget->Font(option?, arg, arg, ...?)

$font->Option?(arg, arg, ...)?

DESCRIPTION

The Font method provides several facilities for dealing with fonts, such as defining named fonts and inspecting the actual attributes of a font. The command has several different forms, determined by the first argument. The following forms are currently supported:

$font->actual(-option?)
$widget->fontActual(font?, -option?)

Returns information about the actual attributes that are obtained when font is used on $font's display; the actual attributes obtained may differ from the attributes requested due to platform-dependant limitations, such as the availability of font families and pointsizes. font is a font description; see FONT DESCRIPTION below. If option is specified, returns the value of that attribute; if it is omitted, the return value is a list of all the attributes and their values. See FONT OPTIONS below for a list of the possible attributes.

$font->configure(-option??=>value, -option=>value, ...?)

Query or modify the desired attributes for $font. If no -option is specified, returns a list describing all the options and their values for fontname. If a single -option is specified with no value, then returns the current value of that attribute. If one or more option-value pairs are specified, then the method modifies the given named font to have the given values; in this case, all widgets using that font will redisplay themselves using the new attributes for the font. See FONT OPTIONS below for a list of the possible attributes.

Note: the above behaviour differs in detail to configure on widgets, images etc.

$font = $widget->Font(-option=>value, ...>?)
$font = $widget->fontCreate(?fontname??, -option=>value, ...>?)

Creates a new font object and returns a reference to it. fontname specifies the name for the font; if it is omitted, then Tk generates a new name of the form font x, where x is an integer. There may be any number of option-value pairs, which provide the desired attributes for the new named font. See FONT OPTIONS below for a list of the possible attributes.

Note: the created font is not shared between widgets of different MainWindows.

$font->delete
$widget->fontDelete(fontname?, fontname, ...?)

Delete the specified named fonts. If there are widgets using the named font, the named font won't actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the named font. If a deleted named font is subsequently recreated with another call to fontCreate, the widgets will use the new named font and redisplay themselves using the new attributes of that font.

$widget->fontFamilies

The return value is a list of the case-insensitive names of all font families that exist on $widget's display.

$font->measure(text)
$widget->fontMeasure(font, text)

Measures the amount of space the string text would use in the given font when displayed in $widget. font is a font description; see FONT DESCRIPTION below. The return value is the total width in pixels of text, not including the extra pixels used by highly exagerrated characters such as cursive ``f''. If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string.

$font->metrics(-option?)
$widget->fontMetrics(font?, -option?)

Returns information about the metrics (the font-specific data), for font when it is used on $widget's display. font is a font description; see FONT DESCRIPTION below. If option is specified, returns the value of that metric; if it is omitted, the return value is a list of all the metrics and their values. See FONT METRICS below for a list of the possible metrics.

$widget->fontNames

The return value is a list of all font objects that are currently defined for $widget's MainWindow.

FONT DESCRIPTION

The following formats are accepted as a font description anywhere font is specified as an argument above; these same forms are also permitted when specifying the -font option for widgets.

[1] fontname

The name of a named font, created using the fontCreate method. When a widget uses a named font, it is guaranteed that this will never cause an error, as long as the named font exists, no matter what potentially invalid or meaningless set of attributes the named font has. If the named font cannot be displayed with exactly the specified attributes, some other close font will be substituted automatically.

[1a] $font

A font object created using the Font method. This is essentially the same as using a named font. The object is a reference to the name, and carries additional information e.g. which MainWindow it relates to in an manner peculiar to perl/Tk.

[3] systemfont

The platform-specific name of a font, interpreted by the graphics server. This also includes, under X, an XLFD (see [4]) for which a single ``*'' character was used to elide more than one field in the middle of the name. See PLATFORM-SPECIFIC ISSUES for a list of the system fonts.

[3] [family,?size,??style,??style ...?]

A properly formed list whose first element is the desired font family and whose optional second element is the desired size. The interpretation of the size attribute follows the same rules described for -size in FONT OPTIONS below. Any additional optional arguments following the size are font styles. Possible values for the style arguments are as follows:

    normal      bold    roman   italic
    underline   overstrike
[4] X-font names (XLFD)

A Unix-centric font name of the form -foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding. The ``*'' character may be used to skip individual fields that the user does not care about. There must be exactly one ``*'' for each field skipped, except that a ``*'' at the end of the XLFD skips any remaining fields; the shortest valid XLFD is simply ``*'', signifying all fields as defaults. Any fields that were skipped are given default values. For compatibility, an XLFD always chooses a font of the specified pixel size (not point size); although this interpretation is not strictly correct, all existing applications using XLFDs assumed that one ``point'' was in fact one pixel and would display incorrectly (generally larger) if the correct size font were actually used.

[5] option value ?option value ...?

A properly formed list of option-value pairs that specify the desired attributes of the font, in the same format used when defining a named font; see FONT OPTIONS below.

When font description font is used, the system attempts to parse the description according to each of the above five rules, in the order specified. Cases [1] and [2] must match the name of an existing named font or of a system font. Cases [3], [4], and [5] are accepted on all platforms and the closest available font will be used. In some situations it may not be possible to find any close font (e.g., the font family was a garbage value); in that case, some system-dependant default font is chosen. If the font description does not match any of the above patterns, an error is generated.

FONT METRICS

The following options are used by the metrics/fontMetrics method to query font-specific data determined when the font was created. These properties are for the whole font itself and not for individual characters drawn in that font. In the following definitions, the ``baseline'' of a font is the horizontal line where the bottom of most letters line up; certain letters, such as lower-case ``g'' stick below the baseline.

-ascent

The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. ($font-<gt>ascent is provided for compatibility.)

-descent

The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. ($font-<gt>descent is provided for compatibility.)

-linespace

Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline.

-fixed

Returns a boolean flag that is ``1'' if this is a fixed-width font, where each normal character is the the same width as all the other characters, or is ``0'' if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value.

FONT OPTIONS

The following options are supported on all platforms, and are used when constructing a named font or when specifying a font using style [5] as above:

-family => name

The case-insensitive font family name. Tk guarantees to support the font families named Courier (a monospaced ``typewriter'' font), Times (a serifed ``newspaper'' font), and Helvetica (a sans-serif ``European'' font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The name may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen.

-size => size

The desired size of the font. If the size argument is a positive number, it is interpreted as a size in points. If size is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If size is unspecified or zero, a platform-dependent default size will be chosen.

The original Tcl/Tk authors believe sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. While this is an admirable goal it does not work as well in practice as they hoped. The mapping between points and pixels is set when the application starts, based on alleged properties of the installed monitor, but it can be overridden by calling the scaling command. However this can be problematic when system has no way of telling if (say) an 11" or 22" monitor is attached, also if it can tell then some monitor sizes may result in poorer quality scaled fonts being used rather than a "tuned" bitmap font. In addition specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap.

At present the Tcl/Tk scheme is used unchanged, with "point" size being returned by actual (as an integer), and used internally. Suggestions for work-rounds to undesirable behaviour welcome.

-weight => weight

The nominal thickness of the characters in the font. The value normal specifies a normal weight font, while bold specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is normal.

-slant => slant

The amount the characters in the font are slanted away from the vertical. Valid values for slant are roman and italic. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is roman.

-underline => boolean

The value is a boolean flag that specifies whether characters in this font should be underlined. The default value for underline is false.

-overstrike => boolean

The value is a boolean flag that specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for overstrike is false.

PLATFORM-SPECIFIC ISSUES

The following named system fonts are supported:

X Windows:

All valid X font names, including those listed by xlsfonts(1), are available.

MS Windows:
 system       ansi       device
 systemfixed  ansifixed  oemfixed
Macintosh:
 system       application

COMPATIBILITY WITH PREVIOUS VERSIONS

In prior versions of perl/Tk the $widget->Font method was a perl wrapper on the original "[4] X-font names (XLFD)" style as described above (which was the only form supported by versions of core tk prior to version tk8.0). This module is provided in its original form (it has just been renamed) via:

 use Tk::X11Font;
 I<$widget>-E<gt>B<X11Font>(...)

However the methods of the old scheme have been mimiced as closely as possible with the new scheme. It is intended that code should work without modification, except for the case of using :

  @names = $font->Name;

i.e. the Name method in an array/list context. This now returns one element on all platforms (as it did on Win32), while previously on X systems it returned a list of fonts that matched an under-specified pattern.

Briefly the methods supported for compatibilty are as follows:

$newfont = $font->Clone(-option=>value, ...>?)

Returns a new font object $newfont related to the original $font by changing the values of the specified -options.

$font->Family - maps to -family
$font->Weight - maps to -weight
$font->Slant - maps to -slant
$font->Pixel and Point - map to -size

New code should use $font->configure to achieve same effect as last four items above.

Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding

Are all ignored if set, and return '*' if queried.

$font->Name

Returns the name of a named font, or a string representation of an unnamed font. Using $font in a scalar context does the same. Note this is distinctly different from behaviour of X11Font's Name in a list context.

$font->Pattern

Returns a XLFD string for the font based on actual values, and some heuristics to map Tk's forms to the "standard" X conventions.

SEE ALSO

Tk::options

Tk::X11Font

KEYWORDS

font


Tk::Frame - Create and manipulate Frame widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS

NAME

Tk::Frame - Create and manipulate Frame widgets

SYNOPSIS

$frame = $parent->Frame(?options?);

STANDARD OPTIONS

-borderwidth | -highlightbackground | -highlightthickness | -takefocus
-class | -highlightcolor | -relief
-cursor

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: background
Class: Background
Switch: -background

This option is the same as the standard background option except that its value may also be specified as an undefined value. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border.

Name: colormap
Class: Colormap
Switch: -colormap

Specifies a colormap to use for the window. The value may be either new, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as $widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the configure method.

Name: container
Class: Container
Switch: -container

The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the -use option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure method.

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

Name: visual
Class: Visual
Switch: -visual

Specifies visual information for the new window in any of the forms accepted by Tk_GetVisual. If this option is not specified, the new window will use the same visual as its parent. The visual option may not be modified with the configure method.

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

DESCRIPTION

The Frame method creates a new window (given by the $widget argument) and makes it into a frame widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the frame such as its background color and relief. The frame command returns the path name of the new window.

A frame is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. The only features of a frame are its background color and an optional 3-D border to make the frame appear raised or sunken.

WIDGET METHODS

The Frame method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

BINDINGS

When a new frame is created, it has no default event bindings: frames are not intended to be interactive.

KEYWORDS

frame, widget


Tk::HList - Create and manipulate Tix Hierarchial List widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • DISPLAY ITEMS
  • WIDGET METHODS
  • BINDINGS
  • EXAMPLE
  • BUGS
  • KEYWORDS
  • SEE ALSO

NAME

Tk::HList - Create and manipulate Tix Hierarchial List widgets

SYNOPSIS

$hlist = $parent->HList(?options?);

STANDARD OPTIONS

-background | -borderwidth | -cursor | -exportselection
-foreground | -font | -height | -highlightcolor
-highlightthickness | -relief | -selectbackground
-selectforeground | -xscrollcommand | -yscrollcommand
-width

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: browsecmd
Class: BrowseCmd
Switch: -browsecmd

Specifies a perl/Tk callback to be executed when the user browses through the entries in the HList widget.

Name: columns
Class: Columns
Switch: -columns

Specifies the number of columns in this HList widget. This option can only be set during the creation of the HList widget and cannot be changed subsequently.

Name: command
Class: Command
Switch: -command

Specifies the perl/Tk callback to be executed when the user invokes a list entry in the HList widget. Normally the user invokes a list entry by double-clicking it or pressing the Return key.

Name: drawBranch
Class: DrawBranch
Switch: -drawbranch

A Boolean value to specify whether branch line should be drawn to connect list entries to their parents.

Name: foreground
Class: Foreground
Switch: -foreground
Alias: -fg

[OBSOLETE] Specifies the default foreground color for the list entries.

Name: gap
Class: Gap
Switch: -gap

[OBSOLETE] The default distance between the bitmap/image and the text in list entries.

Name: header
Class: Header
Switch: -header

A Boolean value specifying whether headers should be displayed for this HList widget (see the header method below).

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window in number of characters.

Name: indent
Class: Indent
Switch: -indent

Specifies the amount of horizontal indentation between a list entry and its children. Must be a valid screen distance value.

Name: indicator
Class: Indicator
Switch: -indicator

Specifies whether the indicators should be displayed inside the HList widget. See the indicator method below.

Name: indicatorCmd
Class: IndicatorCmd
Switch: -indicatorcmd

Specifies a perl/Tk callback to be executed when the user manipulates the indicator of an HList entry. The -indicatorcmd is triggered when the user press or releases the mouse button over the indicator in an HList entry. By default the perl/Tk callback specified by -indicatorcmd is executed with two additional arguments, the entryPath of the entry whose indicator has been triggered and additional information about the event. The additional information is one of the following strings: <Arm>, <Disarm>, and <Activate>.

Name: itemType
Class: ItemType
Switch: -itemtype

Specifies the default type of display item for this HList widget. When you call the itemCreate, add and addchild methods, display items of this type will be created if the -itemtype option is not specified .

Name: padX
Class: Pad
Switch: -padx

[OBSOLETE] The default horizontal padding for list entries.

Name: padY
Class: Pad
Switch: -padx

[OBSOLETE] The default vertical padding for list entries.

Name: selectBackground
Class: SelectBackground
Switch: -selectbackground

Specifies the background color for the selected list entries.

Name: selectBorderWidth
Class: BorderWidth
Switch: -selectborderwidth

Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to Tk_GetPixels.

Name: selectForeground
Class: SelectForeground
Switch: -selectforeground

Specifies the foreground color for the selected list entries.

Name: selectMode
Class: SelectMode
Switch: -selectmode

Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, browse, multiple, or extended; the default value is single.

Name: sizeCmd
Class: SizeCmd
Switch: -sizecmd

Specifies a perl/Tk callback to be called whenever the HList widget changes its size. This method can be useful to implement ``user scroll bars when needed'' features.

Name: separator
Class: Separator
Switch: -separator

Specifies the character to used as the separator character when intepreting the path-names of list entries. By default the character "." is used.

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in characters.

DESCRIPTION

The HList method creates a new window (given by the $widget argument) and makes it into a HList widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the HList widget such as its cursor and relief.

The HList widget can be used to display any data that have a hierarchical structure, for example, file system directory trees. The list entries are indented and connected by branch lines according to their places in the hierachy.

Each list entry is identified by an entryPath. The entryPath is a sequence of entry names separated by the separator charactor (specified by the -separator option). An entry name can be any string that does not contain the separator charactor, or it can be the a string that contains only one separator charactor.

For example, when "." is used as the separator charactor, "one.two.three" is the entryPath for a list entry whose parent is "one.two", whose parent is "one", which is a toplevel entry (has no parents).

Another examples: ".two.three" is the entryPath for a list entry whose parent is ".two", whose parent is ".", which is a toplevel entry.

DISPLAY ITEMS

Each list entry in an HList widget is associated with a display item. The display item determines what visual information should be displayed for this list entry. Please see the Tk::DItem manpage for a list of all display items. When a list entry is created by the itemCreate, add or addchild widget methods, the type of its display item is determined by the -itemtype option passed to these methods. If the -itemtype is omitted, then by default the type specified by this HList widget's -itemtype option is used.

WIDGET METHODS

The HList method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available HList widgets:

$hlist->add($entryPath ?,option=>value, ...?)

Creates a new list entry with the pathname $entryPath. A list entry must be created after its parent is created (unless this entry is a top-level entry, which has no parent). See also BUGS below. This method returns the entryPath of the newly created list entry. The following configuration options can be given to configure the list entry:

-at => position

Insert the new list at the position given by position. position must be a valid integer. The position 0 indicates the first position, 1 indicates the second position, and so on.

-after => afterWhich

Insert the new list entry after the entry identified by afterWhich. afterWhich must be a valid list entry and it mush have the same parent as the new list entry

-before => beforeWhich

Insert the new list entry before the entry identified by beforeWhich. beforeWhich must be a valid list entry and it mush have the same parent as the new list entry

-data => string

Specifies a string to associate with this list entry. This string can be queried by the info method. The application programmer can use the -data option to associate the list entry with the data it represents.

-itemtype => type

Specifies the type of display item to be display for the new list entry. type must be a valid display item type. Currently the available display item types are imagetext, text, and $widget. If this option is not specified, then by default the type specified by this HList widget's -itemtype option is used.

-state => state

Specifies whether this entry can be selected or invoked by the user. Must be either normal or disabled.

The add method accepts additional configuration options to configure the display item associated with this list entry. The set of additional configuration options depends on the type of the display item given by the -itemtype option. Please see the Tk::DItem manpage for a list of the configuration options for each of the display item types.

$hlist->addchild($parentPath, ?option, value, ..., ?)

Adds a new child entry to the children list of the list entry identified by $parentPath. Or, if $parentPath is set to be the empty string, then creates a new toplevel entry. The name of the new list entry will be a unique name automatically generated by the HList widget. Usually if $parentPath is foo, then the entryPath of the new entry will be foo.0, foo.1, ... etc. This method returns the entryPath of the newly created list entry. option can be any option for the add method. See also BUGS below.

$hlist->anchorSet($entryPath)

Sets the anchor to the list entry identified by $entryPath. The anchor is the end of the selection that is fixed while the user is dragging out a selection with the mouse.

$hlist->anchorClear

Removes the anchor, if any, from this HList widget. This only removes the surrounding highlights of the anchor entry and does not affect its selection status.

$hlist->columnWidth($col?, -char?, ?width?)

Querys or sets the width of a the column $col in the HList widget. The value of $col is zero-based: 0 stands for the first column, 1 stands for the second, and so on. If no further parameters are given, returns the current width of this column (in number of pixels). Additional parameters can be given to set the width of this column:

$hlist->columnWidth($col, '')

An empty string indicates that the width of the column should be just wide enough to display the widest element in this column. In this case, the width of this column may change as a result of the elements in this column changing their sizes.

$hlist->columnWidth($col, width)

width must be in a form accepted by Tk_GetPixels.

$hlist->columnWidth($col, -char, nChars)

The width is set to be the average width occupied by nChars number of characters of the font specified by the -font option of this HList widget.

$hlist->delete(option, $entryPath)

Delete one or more list entries. option may be one of the following:

all

Delete all entries in the HList. In this case the $entryPath does not need to be specified.

entry

Delete the entry specified by $entryPath and all its offsprings, if any.

offsprings

Delete all the offsprings, if any, of the entry specified by $entryPath. However, $entryPath itself is not deleted.

siblings

Delete all the list entries that share the same parent with the entry specified by $entryPath. However, $entryPath itself is not deleted.

$hlist->dragsiteSet($entryPath)

Sets the dragsite to the list entry identified by $entryPath. The dragsite is used to indicate the source of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.

$hlist->dragsiteClear

Remove the dragsite, if any, from the this HList widget. This only removes the surrounding highlights of the dragsite entry and does not affect its selection status.

$hlist->dropsiteSet($entryPath)

Sets the dropsite to the list entry identified by $entryPath. The dropsite is used to indicate the target of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.

$hlist->dropsiteClear

Remove the dropsite, if any, from the this HList widget. This only removes the surrounding highlights of the dropsite entry and does not affect its selection status.

$hlist->entrycget($entryPath, option)

Returns the current value of the configuration option given by option for the entry indentfied by $entryPath. Option may have any of the values accepted by the add method.

$hlist->entryconfigure($entryPath ?,option?, ?value=>option, ...?)

Query or modify the configuration options of the list entry indentfied by $entryPath. If no option is specified, returns a list describing all of the available options for $entryPath (see the Tk::options manpage for information on the format of this list.) If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the add or addchild method. The exact set of options depends on the value of the -itemtype option passed to the the add or addchild method when this list entry is created.

$hlist->header(option, $col ?,args, ...?)

Manipulates the header items of this HList widget. If the -header option of this HList widget is set to true, then a header item is displayed at the top of each column. The $col argument for this method must be a valid integer. 0 indicates the first column, 1 the second column, ... and so on. This method supports the following options:

$hlist->header(cget, $col, option)

If the $col-th column has a header display item, returns the value of the specified option of the header item. If the header doesn't exist, returns an error.

$hlist->header(configure, $col, ?option?, ?value, option, value, ...?)

Query or modify the configuration options of the header display item of the $col-th column. The header item must exist, or an error will result. If no option is specified, returns a list describing all of the available options for the header display item (see the Tk::options manpage for information on the format of this list.) If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the header create method. The exact set of options depends on the value of the -itemtype option passed to the the header create method when this display item was created.

$hlist->header(create, $col, ?-itemtype type? ?option value ...?

Creates a new display item as the header for the $col-th column. See also BUGS below. If an header display item already exists for this column, it will be replaced by the new item. An optional parameter -itemtype can be used to specify what type of display item should be created. If the -itemtype is not given, then by default the type specified by this HList widget's -itemtype option is used. Additional parameters, in option-value pairs, can be passed to configure the appearance of the display item. Each option-value pair must be a valid option for this type of display item or one of the following:

-borderwidth => color

Specifies the border width of this header item.

-headerbackground => color

Specifies the background color of this header item.

-relief => type

Specifies the relief type of the border of this header item.

$hlist->header(delete, $col)

Deletes the header display item for the $col-th column.

$hlist->header(exists, $col)

Return true if an header display item exists for the $col-th column; return false otherwise.

$hlist->header(size, $entryPath)

If an header display item exists for the $col-th column , returns its size in pixels in a two element list (width, height); returns an error if the header display item does not exist.

$hlist->hide(option ?,$entryPath?)

Makes some of entries invisible without deleting them. Option can be one of the following:

entry

Hides the list entry identified by $entryPath.

Currently only the entry option is supported. Other options will be added in the next release.

$hlist->indicator(option, $entryPath, ?args, ...?)

Manipulates the indicator on the list entries. An indicator is usually a small display item (such as an image) that is displayed to the left to an entry to indicate the status of the entry. For example, it may be used to indicate whether a directory is opened or closed. Option can be one of the following:

$hlist->indicator(cget, $entryPath, option)

If the list entry given by $entryPath has an indicator, returns the value of the specified option of the indicator. If the indicator doesn't exist, returns an error.

$hlist->indicator(configure, $entryPath, ?option?, ?value, option, value, ...?)

Query or modify the configuration options of the indicator display item of the entry specified by $entryPath. The indicator item must exist, or an error will result. If no option is specified, returns a list describing all of the available options for the indicator display item (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the indicator create method. The exact set of options depends on the value of the -itemtype option passed to the the indicator create method when this display item was created.

$hlist->indicator(create, $entryPath, ?, -itemtype type? ?option value ...?)

Creates a new display item as the indicator for the entry specified by $entryPath. If an indicator display item already exists for this entry, it will be replaced by the new item. An optional parameter -itemtype can be used to specify what type of display item should be created. If the -itemtype is not given, then by default the type specified by this HList widget's -itemtype option is used. Additional parameters, in option-value pairs, can be passed to configure the appearance of the display item. Each option-value pair must be a valid option for this type of display item.

$hlist->indicator(delete, $entryPath)

Deletes the indicator display item for the entry given by $entryPath.

$hlist->indicator(exists, $entryPath)

Return true if an indicator display item exists for the entry given by $entryPath; return false otherwise.

$hlist->indicator(size, $entryPath)

If an indicator display item exists for the entry given by $entryPath, returns its size in a two element list of the form {width height}; returns an error if the indicator display item does not exist.

$hlist->info(option, arg, ...)

Query information about the HList widget. option can be one of the following:

$hlist->info(anchor)

Returns the entryPath of the current anchor, if any, of the HList widget. If the anchor is not set, returns the empty string.

$hlist->infoBbox($entryPath)

Returns a list of four numbers describing the visible bounding box of the entry given $entryPath. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the entry (specified in pixels relative to the widget) and the last two elements give the lower-right corner of the area, in pixels. If no part of the entry given by index is visible on the screen then the result is an empty string; if the entry is partially visible, the result gives the only the visible area of the entry.

$hlist->info(children ?,$entryPath?)

If $entryPath is given, returns a list of the entryPath's of its children entries. Otherwise returns a list of the toplevel entryPath's.

$hlist->info(data ?,$entryPath?)

Returns the data associated with $entryPath.

$hlist->info(dragsite)

Returns the entryPath of the current dragsite, if any, of the HList widget. If the dragsite is not set, returns the empty string.

$hlist->info(dropsite)

Returns the entryPath of the current dropsite, if any, of the HList widget. If the dropsite is not set, returns the empty string.

$hlist->info(exists, $entryPath)

Returns a boolean value indicating whether the list entry $entryPath exists.

$hlist->info(hidden, $entryPath)

Returns a boolean value indicating whether the list entry $entryPath is hidden or not.

$hlist->info(next, $entryPath)

Returns the entryPath of the list entry, if any, immediately below this list entry. If this entry is already at the bottom of the HList widget, returns an empty string.

$hlist->info(parent, $entryPath)

Returns the name of the parent of the list entry identified by $entryPath. If entryPath is a toplevel list entry, returns the empty string.

$hlist->info(prev, $entryPath)

Returns the entryPath of the list entry, if any, immediately above this list entry. If this entry is already at the top of the HList widget, returns an empty string.

$hlist->info(selection)

Returns a list of selected entries in the HList widget. In scalar context, returns an anonymous list of the selected entries. If no entries are selected, undef is returned in scalar context, and an empty list otherwise.

$hlist->item(option, ?args, ...?)

Creates and configures the display items at individual columns the entries. The form of additional of arguments depends on the choice of option:

$hlist->itemCget($entryPath, $col, option)

Returns the current value of the configure option of the display item at the column designated by $col of the entry specified by $entryPath.

$hlist->itemConfigure($entryPath, $col ?,option?, ?value, option, value, ...?)

Query or modify the configuration options of the display item at the column designated by $col of the entry specified by $entryPath. If no option is specified, returns a list describing all of the available options for $entryPath (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the method modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the item create method. The exact set of options depends on the value of the -itemtype option passed to the the item create method when this display item was created.

$hlist->itemCreate($entryPath, $col ?,-itemtype=>type? ?,option value ...?)

Creates a new display item at the column designated by $col of the entry specified by $entryPath. An optional parameter -itemtype can be used to specify what type of display items should be created. If the -itemtype is not specified, then by default the type specified by this HList widget's -itemtype option is used. Additional parameters, in option-value pairs, can be passed to configure the appearance of the display item. Each option- value pair must be a valid option for this type of display item.

$hlist->itemDelete($entryPath, $col)

Deletes the display item at the column designated by $col of the entry specified by $entryPath.

$hlist->itemExists($entryPath, $col)

Returns true if there is a display item at the column designated by $col of the entry specified by $entryPath; returns false otherwise.

$hlist->nearest(y)

$hlist->nearest(y) Given a y-coordinate within the HList window, this method returns the entryPath of the (visible) HList element nearest to that y-coordinate.

$hlist->see($entryPath)

Adjust the view in the HList so that the entry given by $entryPath is visible. If the entry is already visible then the method has no effect; if the entry is near one edge of the window then the HList scrolls to bring the element into view at the edge; otherwise the HList widget scrolls to center the entry.

$hlist->selection(option, arg, ...)
$hlist->selection Option(arg, ...)

This method is used to adjust the selection within a HList widget. It has several forms, depending on option:

$hlist->selectionClear(?from?, ?to?)

When no extra arguments are given, deselects all of the list entrie(s) in this HList widget. When only from is given, only the list entry identified by from is deselected. When both from and to are given, deselects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of elements outside that range.

$hlist->selectionGet

This is an alias for the infoSelection method.

$hlist->selectionIncludes($entryPath)

Returns 1 if the list entry indicated by $entryPath is currently selected; returns 0 otherwise.

$hlist->selectionSet(from?, to?)

Selects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of entries outside that range. When only from is given, only the list entry identified by from is selected.

$hlist->show(option ?,$entryPath?)

Show the entries that are hidden by the hide method, option can be one of the following:

entry

Shows the list entry identified by $entryPath.

Currently only the entry option is supported. Other options will be added in future releases.

$hlist->xview(args)

This method is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms:

$hlist->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the HList entry is off-screen to the left, the middle 40% is visible in the window, and 40% of the entry is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$hlist->xview($entryPath)

Adjusts the view in the window so that the list entry identified by $entryPath is aligned to the left edge of the window.

$hlist->xview(moveto => fraction)

Adjusts the view in the window so that fraction of the total width of the HList is off-screen to the left. fraction must be a fraction between 0 and 1.

$hlist->xview(scroll => number, what)

This method shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

$hlist->yview(?args?)

This method is used to query and change the vertical position of the entries in the widget's window. It can take any of the following forms:

$hlist->yview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the list element at the top of the window, relative to the HList as a whole (0.5 means it is halfway through the HList, for example). The second element gives the position of the list entry just after the last one in the window, relative to the HList as a whole. These are the same values passed to scrollbars via the -yscrollcommand option.

$hlist->yview($entryPath)

Adjusts the view in the window so that the list entry given by $entryPath is displayed at the top of the window.

$hlist->yview(moveto => fraction)

Adjusts the view in the window so that the list entry given by fraction appears at the top of the window. Fraction is a fraction between 0 and 1; 0 indicates the first entry in the HList, 0.33 indicates the entry one-third the way through the HList, and so on.

$hlist->yview(scroll => number, what)

This method adjust the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down by number lines; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier entries become visible; if it is positive then later entries become visible.

BINDINGS

[1]

If the -selectmode is "browse", when the user drags the mouse pointer over the list entries, the entry under the pointer will be highlighted and the -browsecmd callback will be called with one parameter, the entryPath of the highlighted entry. Only one entry can be highlighted at a time. The -command callback will be called when the user double-clicks on a list entry.

[2]

If the -selectmode is "single", the entries will only be highlighted by mouse <ButtonRelease-1> events. When a new list entry is highlighted, the -browsecmd callback will be called with one parameter indicating the highlighted list entry. The -command callback will be called when the user double-clicks on a list entry.

[3]

If the -selectmode is "multiple", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. However, only a contiguous region of list entries can be selected. When the highlighted area is changed, the -browsecmd callback will be called with an undefined parameter. It is the responsibility of the -browsecmd callback to find out the exact highlighted selection in the HList. The -command callback will be called when the user double-clicks on a list entry.

[4]

If the -selectmode is "extended", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. The user can also make disjointed selections using <Control-ButtonPress-1>. When the highlighted area is changed, the -browsecmd callback will be called with an undefined parameter. It is the responsibility of the -browsecmd callback to find out the exact highlighted selection in the HList. The -command callback will be called when the user double-clicks on a list entry.

[5]

Arrow key bindings: <Up> arrow key moves the anchor point to the item right on top of the current anchor item. <Down> arrow key moves the anchor point to the item right below the current anchor item. <Left> arrow key moves the anchor to the parent item of the current anchor item. <Right> moves the anchor to the first child of the current anchor item. If the current anchor item does not have any children, moves the anchor to the item right below the current anchor item.

EXAMPLE

This example demonstrates how to use an HList to store a file directory structure and respond to the user's browse events:

   use strict;
   use Tk;
   use Tk::Label;
   use Tk::HList;

   my $mw = MainWindow->new();
   my $label = $mw->Label(-width=>15);
   my $hlist = $mw->HList(
                       -itemtype   => 'text',
                       -separator  => '/',
                       -selectmode => 'single',
                       -browsecmd  => sub {
                                 my $file = shift;
                                 $label->configure(-text=>$file);
                              }
                       );

   foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
       $hlist->add($_, -text=>$_);
   }

   $hlist->pack;
   $label->pack;

   MainLoop;

BUGS

The fact that the display item at column 0 is implicitly associated with the whole entry is probably a design bug. This was done for backward compatibility purposes. The result is that there is a large overlap between the item method and the add, addchild, entrycget and entryconfigure methods. Whenever multiple columns exist, the programmer should use ONLY the item method to create and configure the display items in each column; the add, addchild, entrycget and entryconfigure should be used ONLY to create and configure entries.

KEYWORDS

Hierarchical Listbox

SEE ALSO

Tk::DItem


Tk::IO - high level interface to Tk's 'fileevent' mechanism

  • WARNING
  • DESCRIPTION
  • BUGS

NAME

Tk::IO - high level interface to Tk's 'fileevent' mechanism

SYNOPSIS

  my $fh = Tk::IO->new(-linecommand => callback, -childcommand => callback);
  $fh->exec("command")
  $fh->wait
  $fh->kill

WARNING

INTERFACES TO THIS MODULE MAY CHANGE AS PERL'S IO EVOLVES AND WITH PORT OF TK4.1

DESCRIPTION

Tk::IO is now layered on perl's IO::Handle class. Interfaces have changed, and are still evolving.

In theory C methods which enable non-blocking IO as in earlier Tk-b* release(s) are still there. I have not changed them to use perl's additional Configure information, or tested them much.

Assumption is that exec is used to fork a child process and a callback is called each time a complete line arrives up the implied pipe.

"line" should probably be defined in terms of perl's input record separator but is not yet.

The -childcommand callback is called when end-of-file occurs.

$fh->wait can be used to wait for child process while processing other Tk events.

$fh->kill can be used to send signal to child process.

BUGS

Still not finished. Idea is to use "exec" to emulate "system" in a non-blocking manner.


Tk::IconList - an icon list widget

    • OPTIONS
    • METHODS
  • COPYRIGHT
  • SEE ALSO

NAME

Tk::IconList - an icon list widget

SYNOPSIS

    use Tk::IconList;
    $il = $mw->IconList(-browsecmd => sub { ... },
                        -command   => sub { ... })->pack;
    $il->Add($icon1, $text1);
    $il->Add($icon2, $text2);
    $il->Arrange;
    ...
    $il->DeleteAll;

DESCRIPTION

OPTIONS

-browsecmd
-command
-font

-item -foreground|-fg

METHODS

DeleteAll

Deletes all the items inside the canvas subwidget and reset the IconList's state.

Add($image, $text)

Adds an icon into the IconList with the designated image and text.

Arrange

Places the icons in a column-major arrangement.

Get

Return the selected item.

Invoke

Gets called when the user invokes the IconList (usually by double-clicking or pressing the Return key) (internal method).

See($tag)

If the item is not (completely) visible, scroll the canvas so that it becomes visible (internal method).

COPYRIGHT

The original tkfbox.tcl from Tcl/Tk is:

Copyright (c) 1994-1996 Sun Microsystems, Inc.

See the file "license.terms" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.

Translated to Perl/Tk by Slaven Rezic <slaven.rezic@berlin.de>.

SEE ALSO

Tk::FBox.


Tk::Image - Create and manipulate images

  • BUILT-IN IMAGE TYPES
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Image - Create and manipulate images

SYNOPSIS

$image = $widget->type(?arg arg ...?)

$image->method(?arg arg ...?)

DESCRIPTION

The image constructors and methods are used to create, delete, and query images. It can take several different forms, depending on the type.

The constructors require a $widget to invoke them, this is used to locate a MainWindow. (This is because the underlying Tk code registers the images in the data structure for the MainWindow.)

The legal forms are:

$widget->type?(?name?,?option=>value ...)?

Creates a new image and returns an object. type specifies the type of the image, which must be one of the types currently defined (e.g., Bitmap). name specifies the name for the image; if it is omitted then Tk picks a name of the form image x, where x is an integer. There may be any number of option=>value pairs, which provide configuration options for the new image. The legal set of options is defined separately for each image type; see below for details on the options for built-in image types. If an image already exists by the given name then it is replaced with the new image and any instances of that image will redisplay with the new contents.

$image->delete

Deletes the image $image and returns an empty string. If there are instances of the image displayed in widgets, the image won't actually be deleted until all of the instances are released. However, the association between the instances and the image manager will be dropped. Existing instances will retain their sizes but redisplay as empty areas. If a deleted image is recreated (with the same name) the existing instances will use the new image.

$image->height

Returns a decimal string giving the height of image name in pixels.

$widget->imageInuse( 'name' );

Returns a boolean value indicating whether or not the image given by name is in use by any widgets.

$widget->imageNames

Returns a list containing all existing images for $widget's MainWindow.

$image->type

Returns the type of $image (the value of the type method when the image was created).

$widget->imageTypes

Returns a list whose elements are all of the valid image types (i.e., all of the values that may be supplied for the type to create an image).

$image->width

Returns a decimal string giving the width of image name in pixels.

BUILT-IN IMAGE TYPES

The following image types are defined by Tk so they will be available in any Tk application. Individual applications or extensions may define additional types.

Bitmap

Each pixel in the image displays a foreground color, a background color, or nothing. See the Tk::Bitmap manpage for more information.

Pixmap

Pixmap is slightly more general than Bitmap, each pixel can be any available color or "transparent" (rendered as background color of the widget image is displayed in). Pixmap is best used for icons and other simple graphics with only a few colors.

Pixmap is derived from Tix. See the Tk::Pixmap manpage for more information.

Photo

Displays a variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. See the Tk::Photo manpage documentation for more information.

SEE ALSO

Tk::Bitmap
Tk::Pixmap
Tk::Photo

KEYWORDS

height, image, types of images, width


Tk::InputO - Create and manipulate TIX InputO widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS

NAME

Tk::InputO - Create and manipulate TIX InputO widgets

SYNOPSIS

$inputonly = $parent->InputO(?options?);

STANDARD OPTIONS

Only the following three standard options are supported by InputO:

cursor width height

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

InputO does not have any widget specific options.

DESCRIPTION

The InputO method creates a new window (given by the $widget argument) and makes it into a InputO widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the InputO such as its cursor or width.

InputO widgets are not visible to the user. The only purpose of InputO widgets are to accept inputs from the user, which can be done with the bind method.

WIDGET METHODS

The InputO method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

BINDINGS

InputO widgets have no default bindings.


CallingTk - what is Perl Tk interface doing when you call Tk functions.

NAME

CallingTk - what is Perl Tk interface doing when you call Tk functions.

This information is worse than useless for perlTk users, but can of some help for people interested in using modified Tk source with perlTk.

This document is under construction. The information is believed to be pertinent to the version of portableTk available when it was created. All the details are subject to change.

DESCRIPTION

PreCompiling

Before the actual compilation stage a script scans the source and extracts the subcommands of different commands. This information resides in the file pTk/Methods.def.

Compilation

During compilation the above file is included in the source of booting routine of dynamic (or static) library. More precisely, the booting code of module Tk calls the subroutine Boot_Glue() from the module tkGlue.c, and this subroutine includes the file (with appropriate macro definitions).

Inside use Tk;

The module bootstraps the C code, then loads the Perl libraries. The heart of the Perl code is contained in the Tk::Widget library, all the widgets inherit from this module. Code for toplevels is loaded from Tk::MainWindow.

During bootstrap of the C glue code the Xevent::? codes and a handful of Tk::Widget and Tk::Image routines are defined. (Much more XSUBs are created from Tk.xs code.) The widget subcommands are glued to Perl basing on the list included from pTk/Methods.def. In fact all the subcommands are glued to XSUBs that are related to the same C subroutine XStoWidget(), but have different data parts.

During the Perl code bootstrap the method Tk::Widget::import is called. This call requires all the code from particular widget packages.

Code from the widget packages calls an obscure command like

  (bless \"Text")->WidgetClass;

This command (actually Tk::Widget::WidgetClass()) creates three routines: Tk::Widget::Text(), Tk::Widget::isText(), and Tk::Text::isText(). The first one is basically new of Tk::Text, the other two return constants. It also puts the class into depository.

Inside $top = MainWindow->new;

This is quite intuitive. This call goes direct to Tk::MainWindow::new, that calls XSUB Tk::MainWindow::CreateMainWindow, that calls C subroutine Tk_CreateMainWindow(). It is a Tk subroutine, so here black magic ends (almost).

The only remaining black magic is that the Tk initialization routine creates a lot of commands, but the subroutine for creation is usurped by portableTk and the commands are created in the package Tk. They are associated to XSUBs that are related to one of three C subroutines XStoSubCmd(), XStoBind(), or XStoTk(), but have different data parts.

The result of the call is blessed into Tk::MainWindow, as it should.

Inside $top->title('Text demo');

The package Tk::Toplevel defines a lot of subroutines on the fly on some list. All the commands from the list are converted to the corresponding subcommands of wm method of the widget. Here subcommand is a command with some particular second argument (in this case "title"). Recall that the first argument is $self.

Now Tk::Toplevel @ISA Tk::Widget, that in turn @ISA Tk. So a call to $top->wm('title','Text demo') calls Tk::wm, that is defined during call to Tk_CreateMainWindow(). As it is described above, the XSUB associated to XStoSubCmd() is called.

This C routine is defined in tkGlue.c. It gets the data part of XSUB, creates a SV with the name of the command, and calls Call_Tk() with the XSUB data as the first argument, and with the name of XSUB stuffed into the Perl stack in the place there tk expects it. (In fact it can also reorder the arguments if it thinks it is what you want).

The latter procedure extracts name of tk procedure and clientData from the first argument and makes a call, using Perl stack as argv for the procedure. A lot of black magic is performed afterwards to convert result of the procedure to a Perl array return.

Inside $text = $top->Text(background => $txtBg);

Above we discussed how the command Tk::Widget::Text is created. The above command calls it via inheritance. It is translated to

  Tk::Text::new($top, background => $txtBg);

The package Tk::Text has no method new, so the Tk::Widget::new is called. In turn it calls Tk::Text->DoInit($top), that is Tk::Widget::DoInit(Tk::Text,$top), that initializes the bindings if necessary. Then it creates the name for the widget of the form .text0, and calls Tk::text('.text0', background => $txtBg) (note lowercase). The result of the call is blessed into Tk::Text, and the method bindtags for this object is called.

Now the only thing to discuss is who defines the methods text and bindtags. The answer is that they are defined in tkWindow.c, and these commands are created in the package Tk in the same sweep that created the command Tk::wm discussed above.

So the the same C code that corresponds to the processing of corresponding TCL commands is called here as well (this time via XStoTk interface).

Inside $text->insert('insert','Hello, world!');

As we discussed above, the subcommands of widget procedures correspond to XSUB XStoWidget. This XSUB substitutes the first argument $text (that is a hash reference) to an appropriate value from this hash, adds the additional argument after the first one that contains the name of the subcommand extracted from the data part of XSUB, and calls the corresponding Tk C subroutine via Call_Tk.

Ilya Zakharevich <ilya@math.ohio-state.edu>


Tk::Menu::Item - Base class for Menu items

  • BUGS

NAME

Tk::Menu::Item - Base class for Menu items

SYNOPSIS

   require Tk::Menu::Item;

   my $but = $menu->Button(...);
   $but->configure(...);
   my $what = $but->cget();

   package Whatever;
   require Tk::Menu::Item;
   @ISA = qw(Tk::Menu::Item);

   sub PreInit
   {
    my ($class,$menu,$info) = @_;
    $info->{'-xxxxx'} = ...
    my $y = delete $info->{'-yyyy'};
   }

DESCRIPTION

Tk::Menu::Item is the base class from which Tk::Menu::Button, Tk::Menu::Cascade, Tk::Menu::Radiobutton and Tk::Menu::Checkbutton are derived. There is also a Tk::Menu::Separator.

Constructors are declared so that $menu->Button(...) etc. do what you would expect.

The -label option is pre-processed allowing ~ to be prefixed to the character to derive a -underline value. Thus

    $menu->Button(-label => 'Goto ~Home',...)
    is equivalent to
    $menu->Button(-label => 'Goto Home', -underline => 6, ...)

The Cascade menu item creates a sub-menu and accepts these options:

-menuitems

A list of items for the sub-menu. Within this list (which is also accepted by Menu and Menubutton) the first two elements of each item should be the "constructor" name and the label:

    -menuitems => [
                   [Button      => '~Quit', -command => [destroy => $mw]],
                   [Checkbutton => '~Oil',  -variable => \$oil],
                  ]
-postcommand

A callback to be invoked before posting the menu.

-tearoff

Specifies whether sub-menu can be torn-off or not.

-menuvar

Scalar reference that will be set to the newly-created sub-menu.

The returned object is currently a blessed reference to an array of two items: the containing Menu and the 'label'. Methods configure and cget are mapped onto underlying entryconfigure and entrycget.

The main purpose of the OO interface is to allow derived item classes to be defined which pre-set the options used to create a more basic item.

BUGS

This OO interface is very new. Using the label as the "key" is a problem for separaror items which don't have one. The alternative would be to use an index into the menu but that is a problem if items are deleted (or inserted other than at the end).

There should probably be a PostInit entry point too, or a more widget like defered 'configure'.


Tk::JPEG - JPEG loader for Tk::Photo

  • AUTHOR

NAME

Tk::JPEG - JPEG loader for Tk::Photo

SYNOPSIS

  use Tk;
  use Tk::JPEG;

  my $image = $widget->Photo('-format' => 'jpeg', -file => 'something.jpg');

DESCRIPTION

This is an extension for Tk800.015 and later which supplies JPEG format loader for Photo image type.

This version also works with Tk804 series.

JPEG access is via release 5 of the The Independent JPEG Group's (IJG) free JPEG software.

AUTHOR

Nick Ing-Simmons <nick@ing-simmons.net>


Tk::LabFrame - labeled frame.

  • WIDGET-OPTIONS
  • ADVERTISED SUBWIDGETS
  • EXAMPLE
  • BUGS
  • AUTHOR

NAME

Tk::LabFrame - labeled frame.

SYNOPSIS

use Tk::LabFrame;

$f = $parent->LabFrame(?-label=>text, -labelside=>where, ...?);

DESCRIPTION

LabFrame is exactly like Frame and additionaly allows to add a label to the frame.

WIDGET-OPTIONS

LabFrame supports the same options as the Frame widget.

Additional options of LabFrame are:

-font => font

Specifies the label's font

-foreground => color

Specifies the label's foreground color

-label => text

The text of the label to be placed with the Frame.

-labelside => where

Where can be one of left, right, top, bottom or acrosstop. The first four work as might be expected and place the label to the left, right, above or below the frame respectively. The acrosstop creates a grooved frame around the central frame and puts the label near the northwest corner such that it appears to "overwrite" the groove.

-labelvariable => scalar_ref

Specifies a reference to a variable and used as an alternative to -label. If the value of the variable changes, then the widget will be updated automatically to reflect the change. Used like -textvariable.

ADVERTISED SUBWIDGETS

See Subwidget in the Tk::mega manpage how to use advertised widgets.

border
  Frame used to display the border
frame
  Frame used to create new LabFrame children.
label
  Label used for displaying text

EXAMPLE

Run the following test program to see this in action:

    use strict;
    use Tk;
    require Tk::LabFrame;
    require Tk::LabEntry;

    my $test = 'Test this';
    my $mw = Tk::MainWindow->new;
    my $f = $mw->LabFrame(-label => "This is a label",
                           -labelside => "acrosstop");
    $f->LabEntry(-label => "Testing", -textvariable => \$test)->pack;
    $f->pack;
    Tk::MainLoop;

BUGS

Perhaps LabFrame should be subsumed within the generic pTk labeled widget mechanism.

AUTHOR

Rajappa Iyer rsi@earthling.net

This code is derived from LabFrame.tcl and LabWidg.tcl in the Tix4.0 distribution by Ioi Lam. The code may be redistributed under the same terms as Perl.


Tk::Label - Create and manipulate Label widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS

NAME

Tk::Label - Create and manipulate Label widgets

SYNOPSIS

$label = $parent->Label(?options?);

STANDARD OPTIONS

-anchor | -font | -image | -takefocus
-background | -foreground | -justify | -text
-bitmap | -highlightbackground | -padx | -textvariable
-borderwidth | -highlightcolor | -pady | -underline
-cursor | -highlightthickness | -relief | -wraplength

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: height
Class: Height
Switch: -height

Specifies a desired height for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in lines of text. If this option isn't specified, the label's desired height is computed from the size of the image or bitmap or text being displayed in it.

Name: width
Class: Width
Switch: -width

Specifies a desired width for the label. If an image or bitmap is being displayed in the label then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in characters. If this option isn't specified, the label's desired width is computed from the size of the image or bitmap or text being displayed in it.

DESCRIPTION

The Label method creates a new window (given by the $widget argument) and makes it into a label widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the label such as its colors, font, text, and initial relief. The label command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A label is a widget that displays a textual string, bitmap or image. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the wrapLength option) and one of the characters may optionally be underlined using the underline option. The label can be manipulated in a few simple ways, such as changing its relief or text, using the commands described below.

WIDGET METHODS

The Label method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

BINDINGS

When a new label is created, it has no default event bindings: labels are not intended to be interactive.

KEYWORDS

label, widget


Tk::Labelframe - Create and manipulate Labelframe widgets

  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Labelframe - Create and manipulate Labelframe widgets

SYNOPSIS

$labelframe = $parent->Labelframe(?options?);

 -borderwidth -highlightbackground -pady
 -cursor      -highlightcolor      -relief
 -font        -highlightthickness  -takefocus
 -foreground  -padx                -text

WIDGET-SPECIFIC OPTIONS

Option: -background
Name: background
Class: Background

This option is the same as the standard background option except that its value may also be specified as an empty string. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border.

Option: -class
Name: class
Class: Class

Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. The class option may not be changed with the configure method.

Option: -colormap
Name: colormap
Class: Colormap

Specifies a colormap to use for the window. The value may be either new, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as $widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the same colormap as its parent. This option may not be changed with the configure method.

Option: -container
Name: container
Class: Container

The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the -use option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure method.

Option: -height
Name: height
Class: Height

Specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

Option: -labelanchor
Name: labelAnchor
Class: LabelAnchor

Specifies where to place the label. A label is only displayed if the -text option is not the empty string. Valid values for this option are (listing them clockwise) nw, n, ne, en, e, es, se, s,sw, ws, w and wn. The default value is nw.

Option: -labelwidget
Name: labelWidget
Class: LabelWidget

Specifies a widget to use as label. This overrides any -text option. The widget must exist before being used as -labelwidget and if it is not a descendant of this window, it will be raised above it in the stacking order.

Option: -visual
Name: visual
Class: Visual

Specifies visual information for the new window in any of the forms accepted by Tk_GetVisual. If this option is not specified, the new window will use the same visual as its parent. The visual option may not be modified with the configure method.

Option: -width
Name: width
Class: Width

Specifies the desired width for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

DESCRIPTION

The Labelframe method creates a new window (given by the $labelframe argument) and makes it into a Labelframe widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the Labelframe such as its background color and relief.

A Labelframe is a simple widget. Its primary purpose is to act as a spacer or container for complex window layouts. It has the features of a Frame plus the ability to display a label.

WIDGET METHODS

The Labelframe method may be used to invoke various operations on the widget. It has the following general form:

 $widget->method(?arg arg ...?);

The following methods are possible for Labelframe widgets:

$widget->cget(option);

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the Labelframe command.

$widget->configure(?option?, ?value, option, value, ...?);

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for $widget (see the Tk::configure manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the Labelframe command.

BINDINGS

When a new Labelframe is created, it has no default event bindings: Labelframes are not intended to be interactive.

SEE ALSO

Tk::Frame, Tk::Label

KEYWORDS

Labelframe, widget


Tk::Listbox - Create and manipulate Listbox widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • INDICES
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • TIED INTERFACE
  • KEYWORDS
  • SEE ALSO

NAME

Tk::Listbox - Create and manipulate Listbox widgets

SYNOPSIS

$listbox = $parent->Listbox(?options?);

STANDARD OPTIONS

-background -borderwidth -cursor -disabledforeground -exportselection -font -foreground -height -highlightbackground -highlightcolor -highlightthickness -offset -relief -selectbackground -selectborderwidth -selectforeground -setgrid -state -takefocus -tile -width -xscrollcommand -yscrollcommand

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: activeStyle
Class: ActiveStyle
Switch: -activestyle

Specifies the style in which to draw the active element. This must be one of dotbox (show a focus ring around the active element), none (no special indication of active element) or underline (underline the active element). The default is underline.

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window, in lines. If zero or less, then the desired height for the window is made just large enough to hold all the elements in the listbox.

Name: listVariable
Class: Variable
Switch: -listvariable

The following is only partially implemented in Perl/Tk:

Specifies the reference of a variable. The value of the variable is an array to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. Attempts to assign a variable with an invalid list value to -listvariable will cause an error. Attempts to unset a variable in use as a -listvariable will fail but will not generate an error.

Name: selectMode
Class: SelectMode
Switch: -selectmode

Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, browse, multiple, or extended; the default value is browse.

Name: state
Class: State
Switch: -state

Specifies one of two states for the listbox: normal or disabled. If the listbox is disabled then items may not be inserted or deleted, items are drawn in the -disabledforeground color, and selection cannot be modified and is not shown (though selection information is retained).

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in characters. If the font doesn't have a uniform width then the width of the character ``0'' is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox.

DESCRIPTION

The Listbox method creates a new window (given by the $widget argument) and makes it into a listbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the listbox such as its colors, font, text, and relief. The listbox command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A listbox is a widget that displays a list of strings, one per line. When first created, a new listbox has no elements. Elements may be added or deleted using methods described below. In addition, one or more elements may be selected as described below. If a listbox is exporting its selection (see exportSelection option), then it will observe the standard X11 protocols for handling the selection. Listbox selections are available as type STRING; the value of the selection will be the text of the selected elements, with newlines separating the elements.

It is not necessary for all the elements to be displayed in the listbox window at once; commands described below may be used to change the view in the window. Listboxes allow scrolling in both directions using the standard xScrollCommand and yScrollCommand options. They also support scanning, as described below.

INDICES

Many of the methods for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways:

number

Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox.

active

Indicates the element that has the location cursor. This element will be displayed with an underline when the listbox has the keyboard focus, and it is specified with the activate method.

anchor

Indicates the anchor point for the selection, which is set with the selection anchor method.

end

Indicates the end of the listbox. For most commands this refers to the last element in the listbox, but for a few commands such as index and insert it refers to the element just after the last one.

@x,y

Indicates the element that covers the point in the listbox window specified by x and y (in pixel coordinates). If no element covers that point, then the closest element to that point is used.

In the method descriptions below, arguments named index, first, and last always contain text indices in one of the above forms.

WIDGET METHODS

The Listbox method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for listbox widgets:

$listbox->activate(index)

Sets the active element to the one indicated by index. If index is outside the range of elements in the listbox then the closest element is activated. The active element is drawn with an underline when the widget has the input focus, and its index may be retrieved with the index active.

$listbox->bbox(index)

Returns a list of four numbers describing the bounding box of the text in the element given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by index is visible on the screen, or if index refers to a non-existent element, then the result is an empty string; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible.

$listbox->curselection

Returns a list containing the numerical indices of all of the elements in the listbox that are currently selected. If there are no elements selected in the listbox then an empty string is returned.

$listbox->delete(first, ?last?)

Deletes one or more elements of the listbox. First and last are indices specifying the first and last elements in the range to delete. If last isn't specified it defaults to first, i.e. a single element is deleted.

$listbox->get(first, ?last?)

If last is omitted, returns the contents of the listbox element indicated by first, or an empty string if first refers to a non-existent element. If last is specified, the command returns a list whose elements are all of the listbox elements between first and last, inclusive. Both first and last may have any of the standard forms for indices.

$listbox->index(index)

Returns the integer index value that corresponds to index. If index is end the return value is a count of the number of elements in the listbox (not the index of the last element).

$listbox->insert(index, ?element, element, ...?)

Inserts zero or more new elements in the list just before the element given by index. If index is specified as end then the new elements are added to the end of the list. Returns an empty string.

$listbox->itemcget(index, option)

Returns the current value of the item configuration option given by option. Option may have any of the values accepted by the listbox itemconfigure command.

$listbox->itemconfigure(index, ?option, value, option, value, ...?)

Query or modify the configuration options of an item in the listbox. If no option is specified, returns a list describing all of the available options for the item (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are currently supported for items:

-background => color

Color specifies the background color to use when displaying the item. It may have any of the forms accepted by Tk_GetColor.

-foreground => color

Color specifies the foreground color to use when displaying the item. It may have any of the forms accepted by Tk_GetColor.

-selectbackground => color

Color specifies the background color to use when displaying the item while it is selected. It may have any of the forms accepted by Tk_GetColor.

-selectforeground => color

Color specifies the foreground color to use when displaying the item while it is selected. It may have any of the forms accepted by Tk_GetColor.

$listbox->nearest(y)

Given a y-coordinate within the listbox window, this command returns the index of the (visible) listbox element nearest to that y-coordinate.

$listbox->scan(option, args)

This command is used to implement scanning on listboxes. It has two forms, depending on option:

$listbox->scanMark(x, y)

Records x and y and the current view in the listbox window; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string.

$listbox->scanDragto(x, y.)

This command computes the difference between its x and y arguments and the x and y arguments to the last scan mark command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string.

$listbox->see(index)

Adjust the view in the listbox so that the element given by index is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element.

$listbox->selection(option, arg)

This command is used to adjust the selection within a listbox. It has several forms, depending on option:

$listbox->selectionAnchor(index)

Sets the selection anchor to the element given by index. If index refers to a non-existent element, then the closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index anchor may be used to refer to the anchor element.

$listbox->selectionClear(first, ?last?)

If any of the elements between first and last (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range.

$listbox->selectionIncludes(index)

Returns 1 if the element indicated by index is currently selected, 0 if it isn't.

$listbox->selectionSet(first, ?last?)

Selects all of the elements in the range between first and last, inclusive, without affecting the selection state of elements outside that range.

$listbox->size

Returns a decimal string indicating the total number of elements in the listbox.

$listbox->xview(args)

This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms:

$listbox->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the listbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$listbox->xview(index)

Adjusts the view in the window so that the character position given by index is displayed at the left edge of the window. Character positions are defined by the width of the character 0.

$listbox->xviewMoveto( fraction );

Adjusts the view in the window so that fraction of the total width of the listbox text is off-screen to the left. fraction must be a fraction between 0 and 1.

$listbox->xviewScroll( number, what );

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

$listbox->yview(?args?)

This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms:

$listbox->yview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the listbox element at the top of the window, relative to the listbox as a whole (0.5 means it is halfway through the listbox, for example). The second element gives the position of the listbox element just after the last one in the window, relative to the listbox as a whole. These are the same values passed to scrollbars via the -yscrollcommand option.

$listbox->yview(index)

Adjusts the view in the window so that the element given by index is displayed at the top of the window.

$listbox->yviewMoveto( fraction );

Adjusts the view in the window so that the element given by fraction appears at the top of the window. Fraction is a fraction between 0 and 1; 0 indicates the first element in the listbox, 0.33 indicates the element one-third the way through the listbox, and so on.

$listbox->yviewScroll( number, what );

This command adjusts the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down by number lines; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier elements become visible; if it is positive then later elements become visible.

DEFAULT BINDINGS

Tk automatically creates class bindings for listboxes that give them Motif-like behavior. Much of the behavior of a listbox is determined by its selectMode option, which selects one of four ways of dealing with the selection.

If the selection mode is single or browse, at most one element can be selected in the listbox at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In browse mode it is also possible to drag the selection with button 1.

If the selection mode is multiple or extended, any number of elements may be selected at once, including discontiguous ranges. In multiple mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In extended mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive.

Most people will probably want to use browse mode for single selections and extended mode for multiple selections; the other modes appear to be useful only in special situations.

Any time the selection changes in the listbox, the virtual event <<ListboxSelect> >>> will be generated. It is easiest to bind to this event to be made aware of any changes to listbox selection.

In addition to the above behavior, the following additional behavior is defined by the default bindings:

[1]

In extended mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down.

[2]

In extended mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements isn't changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began.

[3]

If the mouse leaves the listbox window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the listbox is reached.

[4]

Mouse button 2 may be used for scanning. If it is pressed and dragged over the listbox, the contents of the listbox drag at high speed in the direction the mouse moves.

[5]

If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is browse or extended then the new active element is also selected and all other elements are deselected. In extended mode the new active element becomes the selection anchor.

[6]

In extended mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1.

[7]

The Left and Right keys scroll the listbox view left and right by the width of the character 0. Control-Left and Control-Right scroll the listbox view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window.

[8]

The Prior and Next keys scroll the listbox view up and down by one page (the height of the window).

[9]

The Home and End keys scroll the listbox horizontally to the left and right edges, respectively.

[10]

Control-Home sets the location cursor to the the first element in the listbox, selects that element, and deselects everything else in the listbox.

[11]

Control-End sets the location cursor to the the last element in the listbox, selects that element, and deselects everything else in the listbox.

[12]

In extended mode, Control-Shift-Home extends the selection to the first element in the listbox and Control-Shift-End extends the selection to the last element.

[13]

In multiple mode, Control-Shift-Home moves the location cursor to the first element in the listbox and Control-Shift-End moves the location cursor to the last element.

[14]

The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element.

[15]

In extended mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down.

[16]

In extended mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state.

[17]

Control-slash selects everything in the widget, except in single and browse modes, in which case it selects the active element and deselects everything else.

[18]

Control-backslash deselects everything in the widget, except in browse mode where it has no effect.

[19]

The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

The behavior of listboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings.

TIED INTERFACE

The Tk::Listbox widget can also be tied to a scalar or array variable, with different behaviour depending on the variable type, with the following tie commands:

   use Tk;

   my ( @array, $scalar, $other );
   my %options = ( ReturnType => "index" );

   my $MW = MainWindow->new();
   my $lbox = $MW->Listbox()->pack();

   my @list = ( "a", "b", "c", "d", "e", "f" );
   $lbox->insert('end', @list );

   tie @array, "Tk::Listbox", $lbox
   tie $scalar, "Tk::Listbox", $lbox;
   tie $other, "Tk::Listbox", $lbox, %options;

currently only one modifier is implemented, a 3 way flag for tied scalars "ReturnType" which can have values "element", "index" or "both". The default is "element".

Tied Arrays

If you tie an array to the Listbox you can manipulate the items currently contained by the box in the same manner as a normal array, e.g.

    print @array;
    push(@array, @list);
    my $popped = pop(@array);
    my $shifted = shift(@array);
    unshift(@array, @list);
    delete $array[$index];
    print $string if exists $array[$i];
    @array = ();
    splice @array, $offset, $length, @list

The delete function is implemented slightly differently from the standard array implementation. Instead of setting the element at that index to undef it instead physically removes it from the Listbox. This has the effect of changing the array indices, so for instance if you had a list on non-continuous indices you wish to remove from the Listbox you should reverse sort the list and then apply the delete function, e.g.

     my @list = ( 1, 2, 4, 12, 20 );
     my @remove = reverse sort { $a <=> $b } @list;
     delete @array[@remove];

would safely remove indices 20, 12, 4, 2 and 1 from the Listbox without problems. It should also be noted that a similar warning applies to the splice function (which would normally be used in this context to perform the same job).

Tied Scalars

Unlike tied arrays, if you tie a scalar to the Listbox you can retrieve the currently selected elements in the box as an array referenced by the scalar, for instance

    my @list = ( "a", "b", "c", "d", "e", "f" );
    $lbox->insert('end', sort @list );
    $lbox->selectionSet(1);

inserts @list as elements in an already existing listbox and selects the element at index 1, which is "b". If we then

     print @$selected;

this will return the currently selected elements, in this case "b".

However, if the "ReturnType" arguement is passed when tying the Listbox to the scalar with value "index" then the indices of the selected elements will be returned instead of the elements themselves, ie in this case "1". This can be useful when manipulating both contents and selected elements in the Listbox at the same time.

Importantly, if a value "both" is given the scalar will not be tied to an array, but instead to a hash, with keys being the indices and values being the elements at those indices

You can also manipulate the selected items using the scalar. Equating the scalar to an array reference will select any elements that match elements in the Listbox, non-matching array items are ignored, e.g.

    my @list = ( "a", "b", "c", "d", "e", "f" );
    $lbox->insert('end', sort @list );
    $lbox->selectionSet(1);

would insert the array @list into an already existing Listbox and select element at index 1, i.e. "b"

    @array = ( "a", "b", "f" );
    $selected = \@array;

would select elements "a", "b" and "f" in the Listbox.

Again, if the "index" we indicate we want to use indices in the options hash then the indices are use instead of elements, e.g.

    @array = ( 0, 1, 5 );
    $selected = \@array;

would have the same effect, selecting elements "a", "b" and "f" if the $selected variable was tied with %options = ( ReturnType => "index" ).

If we are returning "both", i.e. the tied scalar points to a hash, both key and value must match, e.g.

    %hash = ( 0 => "a", 1 => "b", 5 => "f" );
    $selected = \%hash;

would have the same effect as the previous examples.

It should be noted that, despite being a reference to an array (or possibly a has), you still can not copy the tied variable without it being untied, instead you must pass a reference to the tied scalar between subroutines.

KEYWORDS

listbox, widget, tied

SEE ALSO

the Tk::HList manpage, the Tk::TextList manpage.


Tk::MainWindow - Root widget of a widget tree

  • METHODS
  • MISSING
  • SEE ALSO

NAME

Tk::MainWindow - Root widget of a widget tree

SYNOPSIS

    use Tk;

    my $mw = MainWindow->new( ... options ... );

    my $this = $mw->ThisWidget -> pack ;
    my $that = $mw->ThatWidget;
    ...

    MainLoop;

DESCRIPTION

Perl/Tk applications (which have windows associated with them) create one or more MainWindows which act as the containers and parents of the other widgets.

Tk::MainWindow is a special kind of Toplevel widget. It is the root of a widget tree. Therefore $mw->Parent returns undef.

The default title of a MainWindow is the basename of the script (actually the Class name used for options lookup, i.e. with basename with inital caps) or 'Ptk' as the fallback value. If more than one MainWindow is created or several instances of the script are running at the same time the string " #n" is appended where the number n is set to get a unique value.

Unlike the standard Tcl/Tk's wish, perl/Tk allows you to create several MainWindows. When the last MainWindow is destroyed the Tk eventloop exits (the eventloop is entered with the call of MainLoop). Various resources (bindings, fonts, images, colors) are maintained or cached for each MainWindow, so each MainWindow consumes more resources than a Toplevel. However multiple MainWindows can make sense when the user can destroy them independently.

METHODS

You can apply all methods that a Toplevel widget accepts.

The method $w->MainWindow applied to any widget will return the MainWindow to which the widget belongs (the MainWindow belongs to itself).

MISSING

Documentation is incomplete. Here are some missing items that should be explained in more detail:

  • The new mechanism for MainWindows is slightly different to other widgets.

  • There no explanation about what resources are bound to a MainWindow (e.g., ClassInit done per MainWindow)

  • Passing of command line options to override or augment arguments of the new method (see the Tk::CmdLine manpage).

SEE ALSO

Tk::Toplevel Tk::CmdLine


Tk::Menu - Create and manipulate Menu widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
    • COMMAND ENTRIES
    • SEPARATOR ENTRIES
    • CHECKBUTTON ENTRIES
    • RADIOBUTTON ENTRIES
    • CASCADE ENTRIES
    • TEAR-OFF ENTRIES
    • MENUBARS
    • SPECIAL MENUS IN MENUBARS
    • CLONES
    • WIDGET METHODS
  • MENU CONFIGURATIONS
  • DEFAULT BINDINGS
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Menu - Create and manipulate Menu widgets

SYNOPSIS

$menu = $parent->Menu(?options?);

STANDARD OPTIONS

-activebackground | -background | -disabledforeground | -relief
-activeborderwidth | -borderwidth | -font | -takefocus
-activeforeground | -cursor | -foreground

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: postCommand
Class: Command
Switch: -postcommand

If this option is specified then it provides a callback to execute each time the menu is posted. The callback is invoked by the post method before posting the menu. Note that in 8.0 on Macintosh and Windows, all commands in a menu systems are executed before any are posted. This is due to the limitations in the individual platforms' menu managers.

Name: selectColor
Class: Background
Switch: -selectcolor

For menu entries that are check buttons or radio buttons, this option specifies the color to display in the indicator when the check button or radio button is selected.

Name: tearOff
Class: TearOff
Switch: -tearoff

This option must have a proper boolean value, which specifies whether or not the menu should include a tear-off entry at the top. If so, it will exist as entry 0 of the menu and the other entries will number starting at 1. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked.

Name: tearOffCommand
Class: TearOffCommand
Switch: -tearoffcommand

If this option has a non-empty value, then it specifies a perl/Tk callback to invoke whenever the menu is torn off. The actual command will consist of the value of this option, followed by a space, followed by the name of the menu window, followed by a space, followed by the name of the name of the torn off menu window. For example, if the option's is ``a b'' and menu .x.y is torn off to create a new menu .x.tearoff1, then the command ``a b .x.y .x.tearoff1'' will be invoked.

Name: title
Class: Title
Switch: -title

The string will be used to title the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked.

Name: type
Class: Type
Switch: -type

This option can be one of menubar, tearoff, or normal, and is set when the menu is created. While the string returned by the configuration database will change if this option is changed, this does not affect the menu widget's behavior. This is used by the cloning mechanism and is not normally set outside of the Tk library.

DESCRIPTION

The Menu method creates a new top-level window (given by the $widget argument) and makes it into a menu widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menu such as its colors and font. The menu command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget.

Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the -label, -bitmap, and -image options for the entry. If the -accelerator option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an indicator. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string.

In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is invoked. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries.

Entries may be disabled, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again.

Whenever a menu's active entry is changed, a <<MenuSelect>> virtual event is sent to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry.

COMMAND ENTRIES

The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, a callback is executed. The callback is specified with the -command option.

SEPARATOR ENTRIES

A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance.

CHECKBUTTON ENTRIES

A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. When the entry is selected, a particular value is stored in a particular global variable (as determined by the -onvalue and -variable options for the entry); when the entry is deselected another value (determined by the -offvalue option) is stored in the global variable. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the -selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a -command option is specified for a checkbutton entry, then its value is evaluated each time the entry is invoked; this happens after toggling the entry's selected state.

RADIOBUTTON ENTRIES

A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups of which only one entry may be selected at a time. Whenever a particular entry becomes selected it stores a particular value into a particular global variable (as determined by the -value and -variable options for the entry). This action causes any previously-selected entry in the same group to deselect itself. Once an entry has become selected, any change to the entry's associated variable will cause the entry to deselect itself. Grouping of radiobutton entries is determined by their associated variables: if two entries have the same associated variable then they are in the same group. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the -selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a -command option is specified for a radiobutton entry, then its value is evaluated each time the entry is invoked; this happens after selecting the entry.

CASCADE ENTRIES

A cascade entry is one with an associated menu (determined by the -menu option). Cascade entries allow the construction of cascading menus. The postcascade method can be used to post and unpost the associated menu just next to of the cascade entry. The associated menu must be a child of the menu containing the cascade entry (this is needed in order for menu traversal to work correctly).

A cascade entry posts its associated menu by invoking

$menu->post(x,y)

where menu is the path name of the associated menu, and x and y are the root-window coordinates of the upper-right corner of the cascade entry. On Unix, the lower-level menu is unposted by executing

$menu->unpost

where menu is the name of the associated menu. On other platforms, the platform's native code takes care of unposting the menu.

If a -command option is specified for a cascade entry then it is evaluated whenever the entry is invoked. This is not supported on Windows.

TEAR-OFF ENTRIES

A tear-off entry appears at the top of the menu if enabled with the tearOff option. It is not like other menu entries in that it cannot be created with the add method and cannot be deleted with the delete method. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus.

MENUBARS

Any menu can be set as a menubar for a toplevel window (see the Toplevel constructor for syntax). On the Macintosh, whenever the toplevel is in front, this menu's cascade items will appear in the menubar across the top of the main monitor. On Windows and Unix, this menu's items will be displayed in a menubar accross the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made. See CLONES for more information.

As noted, menubars may behave differently on different platforms. One example of this concerns the handling of checkbuttons and radiobuttons within the menu. While it is permitted to put these menu elements on menubars, they may not be drawn with indicators on some platforms, due to system restrictions.

SPECIAL MENUS IN MENUBARS

Certain menus in a menubar will be treated specially. On the Macintosh, access to the special Apple and Help menus is provided. On Windows, access to the Windows System menu in each window is provided. On X Windows, a special right-justified help menu is provided. In all cases, these menus must be created with the command name of the menubar menu concatenated with the special name. So for a menubar named .menubar, on the Macintosh, the special menus would be .menubar.apple and .menubar.help; on Windows, the special menu would be .menubar.system; on X Windows, the help menu would be .menubar.help.

When Tk sees an Apple menu on the Macintosh, that menu's contents make up the first items of the Apple menu on the screen whenever the window containing the menubar is in front. The menu is the first one that the user sees and has a title which is an Apple logo. After all of the Tk-defined items, the menu will have a separator, followed by all of the items in the user's Apple Menu Items folder. Since the System uses a different menu definition procedure for the Apple menu than Tk uses for its menus, and the system APIs do not fully support everything Tk tries to do, the menu item will only have its text displayed. No font attributes, images, bitmaps, or colors will be displayed. In addition, a menu with a tearoff item will have the tearoff item displayed as "(TearOff)".

When Tk see a Help menu on the Macintosh, the menu's contents are appended to the standard help menu on the right of the user's menubar whenever the user's menubar is in front. The first items in the menu are provided by Apple. Similar to the Apple Menu, cusomization in this menu is limited to what the system provides.

When Tk sees a System menu on Windows, its items are appended to the system menu that the menubar is attached to. This menu has an icon representing a spacebar, and can be invoked with the mouse or by typing Alt+Spacebar. Due to limitations in the Windows API, any font changes, colors, images, bitmaps, or tearoff images will not appear in the system menu.

When Tk see a Help menu on X Windows, the menu is moved to be last in the menubar and is right justified.

CLONES

When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed.

WIDGET METHODS

The Menu method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class, and the Tk::Wm class.

Many of the methods for a menu take as one argument an indicator of which entry of the menu to operate on. These indicators are called indexes and may be specified in any of the following forms:

number

Specifies the entry numerically, where 0 corresponds to the top-most entry of the menu, 1 to the entry below it, and so on.

active

Indicates the entry that is currently active. If no entry is active then this form is equivalent to none. This form may not be abbreviated.

end

Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to none. This form may not be abbreviated.

last

Same as end.

none

Indicates ``no entry at all''; this is used most commonly with the activate option to deactivate all the entries in the menu. In most cases the specification of none causes nothing to happen in the method. This form may not be abbreviated.

@number

In this form, number is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used. For example, ``@0'' indicates the top-most entry in the window.

pattern

If the index doesn't satisfy one of the above forms then this form is used. Pattern is pattern-matched against the label of each entry in the menu, in order from the top down, until a matching entry is found. (In perl/Tk the matching is under review, but exact match should work.)

The following methods are possible for menu widgets:

$menu->activate(index)

Change the state of the entry indicated by index to active and redisplay it using its active colors. Any previously-active entry is deactivated. If index is specified as none, or if the specified entry is disabled, then the menu ends up with no active entry. Returns an empty string.

$menu->add(type, ?option, value, option, value, ...?)

Add a new entry to the bottom of the menu. The new entry's type is given by type and must be one of cascade, checkbutton, command, radiobutton, or separator, or a unique abbreviation of one of the above. If additional arguments are present, they specify any of the following options:

-activebackground => value

Specifies a background color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the activeBackground option for the overall menu is used. If the $Tk::strictMotif variable has been set to request strict Motif compliance, then this option is ignored and the -background option is used in its place. This option is not available for separator or tear-off entries.

-activeforeground => value

Specifies a foreground color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the activeForeground option for the overall menu is used. This option is not available for separator or tear-off entries.

-accelerator => value

Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be typed to invoke the same function as the menu entry. This option is not available for separator or tear-off entries.

-background => value

Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the background option for the overall menu is used. This option is not available for separator or tear-off entries.

-bitmap => value

Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by Tk_GetBitmap. This option overrides the -label option but may be reset to an empty string to enable a textual label to be displayed. If a -image option has been specified, it overrides -bitmap. This option is not available for separator or tear-off entries.

-columnbreak => value

When this option is zero, the appears below the previous entry. When this option is one, the menu appears at the top of a new column in the menu.

-compound => value

Specifies whether the button should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are bottom, center, left, none, right and top. The default value is none, meaning that the button will display either an image or text, depending on the values of the -image and -bitmap options.

-command => value

For command, checkbutton, and radiobutton entries, specifies a callback to execute when the menu entry is invoked. For cascade entries, specifies a callback to execute when the entry is activated (i.e. just before its submenu is posted). Not available for separator or tear-off entries.

-font => value

Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the font option for the overall menu is used. This option is not available for separator or tear-off entries.

-foreground => value

Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the foreground option for the overall menu is used. This option is not available for separator or tear-off entries.

-hidemargin => value

Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used.

-image => value

Specifies an image to display in the menu instead of a text string or bitmap The image must have been created by some previous invocation of image create. This option overrides the -label and -bitmap options but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries.

-indicatoron => value

Available only for checkbutton and radiobutton entries. Value is a boolean that determines whether or not the indicator should be displayed.

-label => value

Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries.

-menu => value

Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu.

-offvalue => value

Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is deselected.

-onvalue => value

Available only for checkbutton entries. Specifies the value to store in the entry's associated variable when the entry is selected.

-selectcolor => value

Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the selectColor option for the menu determines the indicator color.

-selectimage => value

Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the -image option) when it is selected. Value is the name of an image, which must have been created by some previous invocation of image create. This option is ignored unless the -image option has been specified.

-state => value

Specifies one of three states for the entry: normal, active, or disabled. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the activeForeground option for the menu along with the activebackground option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the disabledForeground option for the menu and the background option from the entry. This option is not available for separator entries.

-underline => value

Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. 0 corresponds to the first character of the text displayed in the entry, 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries.

-value => value

Available only for radiobutton entries. Specifies the value to store in the entry's associated variable when the entry is selected. If an empty string is specified, then the -label option for the entry as the value to store in the variable.

-variable => value

Available only for checkbutton and radiobutton entries. Specifies the name of a global value to set when the entry is selected. For checkbutton entries the variable is also set when the entry is deselected. For radiobutton entries, changing the variable causes the currently-selected entry to deselect itself.

The add method returns an empty string.

$menu->clone($parent ?, cloneType?)

Makes a clone of the current menu as a child of $parent. This clone is a menu in its own right, but any changes to the clone are propogated to the original menu and vice versa. cloneType can be normal, menubar, or tearoff. Should not normally be called outside of the Tk library. See CLONES for more information.

$menu->delete(index1?, index2?)

Delete all of the menu entries between index1 and index2 inclusive. If index2 is omitted then it defaults to index1. Attempts to delete a tear-off menu entry are ignored (instead, you should change the tearOff option to remove the tear-off entry).

$menu->entrycget(index, option)

Returns the current value of a configuration option for the entry given by index. Option may have any of the values accepted by the add method.

$menu->entryconfigure(index ?,options?)

This method is similar to the configure method, except that it applies to the options for an individual entry, whereas configure applies to the options for the menu as a whole. Options may have any of the values accepted by the add method. If options are specified, options are modified as indicated in the method call and the method returns an empty string. If no options are specified, returns a list describing the current options for entry index (see the Tk::options manpage for information on the format of this list).

$menu->index(index)

Returns the numerical index corresponding to index, or none if index was specified as none.

$menu->insert(index, type?, -option=>value, ...?)

Same as the add method except that it inserts the new entry just before the entry given by index, instead of appending to the end of the menu. The type, -option, and value arguments have the same interpretation as for the add widget method. It is not possible to insert new menu entries before the tear-off entry, if the menu has one.

$menu->invoke(index)

Invoke the action of the menu entry. See the sections on the individual entries above for details on what happens. If the menu entry is disabled then nothing happens. If the entry has a callback associated with it then the result of that callback is returned as the result of the invoke widget method. Otherwise the result is an empty string. Note: invoking a menu entry does not automatically unpost the menu; the default bindings normally take care of this before invoking the invoke method.

$menu->post(x, y)

Arrange for the menu to be displayed on the screen at the root-window coordinates given by x and y. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen. This method normally returns an empty string. If the postCommand option has been specified, then its value is executed before posting the menu and the result of that callback is returned as the result of the post widget method. If an error returns while executing the method, then the error is returned without posting the menu.

$menu->postcascade(index)

Posts the submenu associated with the cascade entry given by index, and unposts any previously posted submenu. If index doesn't correspond to a cascade entry, or if $menu isn't posted, the method has no effect except to unpost any currently posted submenu.

$menu->type(index)

Returns the type of the menu entry given by index. This is the type argument passed to the add widget method when the entry was created, such as command or separator, or tearoff for a tear-off entry.

$menu->unpost

Unmap the window so that it is no longer displayed. If a lower-level cascaded menu is posted, unpost that menu. Returns an empty string. This method does not work on Windows and the Macintosh, as those platforms have their own way of unposting menus.

$menu->yposition(index)

Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by index.

MENU CONFIGURATIONS

The default bindings support four different ways of using menus:

Pulldown Menus in Menubar

This is the most command case. You create a menu widget that will become the menu bar. You then add cascade entries to this menu, specifying the pull down menus you wish to use in your menu bar. You then create all of the pulldowns. Once you have done this, specify the menu using the -menu option of the toplevel's method. See the toplevel manual entry for details.

Pulldown Menus in Menu Buttons

This is the compatable way to do menu bars. You create one menubutton widget for each top-level menu, and typically you arrange a series of menubuttons in a row in a menubar window. You also create the top-level menus and any cascaded submenus, and tie them together with -menu options in menubuttons and cascade menu entries. The top-level menu must be a child of the menubutton, and each submenu must be a child of the menu that refers to it. Once you have done this, the default bindings will allow users to traverse and invoke the tree of menus via its menubutton; see the menubutton documentation for details.

Popup Menus

Popup menus typically post in response to a mouse button press or keystroke. You create the popup menus and any cascaded submenus, then you call the Post method at the appropriate time to post the top-level menu.

$menu->Post($x,$y?,$entry?)

$x and $y are the root window coordinates at which the $menu will be displayed. If $entry is specified then that entry is centred on that point, otherwise the top-left corner of the $menu is placed at that point.

Menu also inherits methods from the Tk::Wm manpage and so the method Popup can be used to position menu relative to other windows, the mouse cursor or the screen.

Option Menus

An option menu consists of a menubutton with an associated menu that allows you to select one of several values. The current value is displayed in the menubutton and is also stored in a global variable. Use the the Tk::Optionmenu manpage class to create option menubuttons and their menus.

Torn-off Menus

You create a torn-off menu by invoking the tear-off entry at the top of an existing menu. The default bindings will create a new menu that is a copy of the original menu and leave it permanently posted as a top-level window. The torn-off menu behaves just the same as the original menu.

DEFAULT BINDINGS

Tk automatically creates class bindings for menus that give them the following default behavior:

[1]

When the mouse enters a menu, the entry underneath the mouse cursor activates; as the mouse moves around the menu, the active entry changes to track the mouse.

[2]

When the mouse leaves a menu all of the entries in the menu deactivate, except in the special case where the mouse moves from a menu to a cascaded submenu.

[3]

When a button is released over a menu, the active entry (if any) is invoked. The menu also unposts unless it is a torn-off menu.

[4]

The Space and Return keys invoke the active entry and unpost the menu.

[5]

If any of the entries in a menu have letters underlined with with -underline option, then pressing one of the underlined letters (or its upper-case or lower-case equivalent) invokes that entry and unposts the menu.

[6]

The Escape key aborts a menu selection in progress without invoking any entry. It also unposts the menu unless it is a torn-off menu.

[7]

The Up and Down keys activate the next higher or lower entry in the menu. When one end of the menu is reached, the active entry wraps around to the other end.

[8]

The Left key moves to the next menu to the left. If the current menu is a cascaded submenu, then the submenu is unposted and the current menu entry becomes the cascade entry in the parent. If the current menu is a top-level menu posted from a menubutton, then the current menubutton is unposted and the next menubutton to the left is posted. Otherwise the key has no effect. The left-right order of menubuttons is determined by their stacking order: Tk assumes that the lowest menubutton (which by default is the first one created) is on the left.

[9]

The Right key moves to the next menu to the right. If the current entry is a cascade entry, then the submenu is posted and the current menu entry becomes the first entry in the submenu. Otherwise, if the current menu was posted from a menubutton, then the current menubutton is unposted and the next menubutton to the right is posted.

Disabled menu entries are non-responsive: they don't activate and they ignore mouse button presses and releases.

The behavior of menus can be changed by defining new bindings for individual widgets or by redefining the class bindings.

BUGS

At present it isn't possible to use the option database to specify values for the options to individual entries.

SEE ALSO

Tk::callbacks

KEYWORDS

menu, widget


Tk::Menubutton - Create and manipulate Menubutton widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • KEYWORDS

NAME

Tk::Menubutton - Create and manipulate Menubutton widgets

SYNOPSIS

$menubutton = $parent->Menubutton(?options?);

STANDARD OPTIONS

-activebackground | -cursor | -highlightthickness | -takefocus
-activeforeground | -disabledforeground | -image | -text
-anchor | -font | -justify | -textvariable
-background | -foreground | -padx | -underline
-bitmap | -highlightbackground | -pady | -wraplength
-borderwidth | -highlightcolor | -relief

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Command-Line Name: -compound
Database Name: compound
Database Class: Compound

Specifies whether the button should display both an image and text, and if so, where the image should be placed relative to the text. Valid values for this option are bottom, center, left, none, right and top. The default value is none, meaning that the button will display either an image or text, depending on the values of the -image and -bitmap options.

Name: direction
Class: Height
Switch: -direction

Specifies where the menu is going to be popup up. above tries to pop the menu above the menubutton. below tries to pop the menu below the menubutton. left tries to pop the menu to the left of the menubutton. right tries to pop the menu to the right of the menu button. flush pops the menu directly over the menubutton.

Name: height
Class: Height
Switch: -height

Specifies a desired height for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in lines of text. If this option isn't specified, the menubutton's desired height is computed from the size of the image or bitmap or text being displayed in it.

Name: indicatorOn
Class: IndicatorOn
Switch: -indicatoron

The value must be a proper boolean value. If it is true then a small indicator rectangle will be displayed on the right side of the menubutton and the default menu bindings will treat this as an option menubutton. If false then no indicator will be displayed.

Name: menu
Class: MenuName
Switch: -menu

Specifies the path name of the menu associated with this menubutton. The menu must be a child of the menubutton.

Name: state
Class: State
Switch: -state

Specifies one of three states for the menubutton: normal, active, or disabled. In normal state the menubutton is displayed using the foreground and background options. The active state is typically used when the pointer is over the menubutton. In active state the menubutton is displayed using the activeForeground and activeBackground options. Disabled state means that the menubutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledForeground and background options determine how the button is displayed.

Name: width
Class: Width
Switch: -width

Specifies a desired width for the menubutton. If an image or bitmap is being displayed in the menubutton then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in characters. If this option isn't specified, the menubutton's desired width is computed from the size of the image or bitmap or text being displayed in it.

DESCRIPTION

The Menubutton method creates a new window (given by the $widget argument) and makes it into a menubutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menubutton such as its colors, font, text, and initial relief. The menubutton command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A menubutton is a widget that displays a textual string, bitmap, or image and is associated with a menu widget. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the wrapLength option) and one of the characters may optionally be underlined using the underline option. In normal usage, pressing mouse button 1 over the menubutton causes the associated menu to be posted just underneath the menubutton. If the mouse is moved over the menu before releasing the mouse button, the button release causes the underlying menu entry to be invoked. When the button is released, the menu is unposted.

Menubuttons are typically organized into groups called menu bars that allow scanning: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead.

There are several interactions between menubuttons and menus; see the menu manual entry for information on various menu configurations, such as pulldown menus and option menus.

WIDGET METHODS

The Menubutton method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The menu method returns the menu associated with the widget. The widget also inherits all the methods provided by the generic Tk::Widget class.

DEFAULT BINDINGS

Tk automatically creates class bindings for menubuttons that give them the following default behavior:

[1]

A menubutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves it.

[2]

Pressing mouse button 1 over a menubutton posts the menubutton: its relief changes to raised and its associated menu is posted under the menubutton. If the mouse is dragged down into the menu with the button still down, and if the mouse button is then released over an entry in the menu, the menubutton is unposted and the menu entry is invoked.

[3]

If button 1 is pressed over a menubutton and then released over that menubutton, the menubutton stays posted: you can still move the mouse over the menu and click button 1 on an entry to invoke it. Once a menu entry has been invoked, the menubutton unposts itself.

[4]

If button 1 is pressed over a menubutton and then dragged over some other menubutton, the original menubutton unposts itself and the new menubutton posts.

[5]

If button 1 is pressed over a menubutton and released outside any menubutton or menu, the menubutton unposts without invoking any menu entry.

[6]

When a menubutton is posted, its associated menu claims the input focus to allow keyboard traversal of the menu and its submenus. See the menu documentation for details on these bindings.

[7]

If the underline option has been specified for a menubutton then keyboard traversal may be used to post the menubutton: Alt+x, where x is the underlined character (or its lower-case or upper-case equivalent), may be typed in any window under the menubutton's toplevel to post the menubutton.

[8]

The F10 key may be typed in any window to post the first menubutton under its toplevel window that isn't disabled.

[9]

If a menubutton has the input focus, the space and return keys post the menubutton.

If the menubutton's state is disabled then none of the above actions occur: the menubutton is completely non-responsive.

The behavior of menubuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

menubutton, widget


Tk::Message - Create and manipulate Message widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • BUGS
  • KEYWORDS

NAME

Tk::Message - Create and manipulate Message widgets

SYNOPSIS

$message = $parent->Message(?options?);

STANDARD OPTIONS

-anchor | -font | -highlightthickness | -takefocus
-background | -foreground | -padx | -text
-borderwidth | -highlightbackground | -pady | -textvariable
-cursor | -highlightcolor | -relief | -width

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: aspect
Class: Aspect
Switch: -aspect

Specifies a non-negative integer value indicating desired aspect ratio for the text. The aspect ratio is specified as 100*width/height. 100 means the text should be as wide as it is tall, 200 means the text should be twice as wide as it is tall, 50 means the text should be twice as tall as it is wide, and so on. Used to choose line length for text if width option isn't specified. Defaults to 150.

Name: justify
Class: Justify
Switch: -justify

Specifies how to justify lines of text. Must be one of left, center, or right. Defaults to left. This option works together with the anchor, aspect, padX, padY, and width options to provide a variety of arrangements of the text within the window. The aspect and width options determine the amount of screen space needed to display the text. The anchor, padX, and padY options determine where this rectangular area is displayed within the widget's window, and the justify option determines how each line is displayed within that rectangular region. For example, suppose anchor is e and justify is left, and that the message window is much larger than needed for the text. The the text will displayed so that the left edges of all the lines line up and the right edge of the longest line is padX from the right side of the window; the entire text block will be centered in the vertical span of the window.

Name: width
Class: Width
Switch: -width

Specifies the length of lines in the window. The value may have any of the forms acceptable to Tk_GetPixels. If this option has a value greater than zero then the aspect option is ignored and the width option determines the line length. If this option has a value less than or equal to zero, then the aspect option determines the line length.

DESCRIPTION

The Message method creates a new window (given by the $widget argument) and makes it into a message widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the message such as its colors, font, text, and initial relief. The message command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A message is a widget that displays a textual string. A message widget has three special features. First, it breaks up its string into lines in order to produce a given aspect ratio for the window. The line breaks are chosen at word boundaries wherever possible (if not even a single word would fit on a line, then the word will be split across lines). Newline characters in the string will force line breaks; they can be used, for example, to leave blank lines in the display.

The second feature of a message widget is justification. The text may be displayed left-justified (each line starts at the left side of the window), centered on a line-by-line basis, or right-justified (each line ends at the right side of the window).

The third feature of a message widget is that it handles control characters and non-printing characters specially. Tab characters are replaced with enough blank space to line up on the next 8-character boundary. Newlines cause line breaks. Other control characters (ASCII code less than 0x20) and characters not defined in the font are displayed as a four-character sequence \x hh where hh is the two-digit hexadecimal number corresponding to the character. In the unusual case where the font doesn't contain all of the characters in ``0123456789abcdef\x'' then control characters and undefined characters are not displayed at all.

WIDGET METHODS

The Message method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

DEFAULT BINDINGS

When a new message is created, it has no default event bindings: messages are intended for output purposes only.

BUGS

Tabs don't work very well with text that is centered or right-justified. The most common result is that the line is justified wrong.

KEYWORDS

message, widget


Tk::Mwm - Communicate with the Motif window manager.

  • METHODS
  • BUGS
  • SEE ALSO
  • KEYWORDS
  • AUTHOR

NAME

Tk::Mwm - Communicate with the Motif(tm) window manager.

SYNOPSIS

use Tk::Mwm;

$toplevel->mwm Option?(args)?

$toplevel->mwm(option ?,args?)

DESCRIPTION

Interface to special extentions supported by mwm.

METHODS

$toplevel->mwmDecoration?(?option??=>value? ?,...?)?

When no options are given, this method returns the values of all the decorations options for the toplevel window with the $toplevel. When only one option is given without specifying the value, the current value of that option is returned. When more than one "option-value" pairs are passed to this method, the specified values will be assigned to the corresponding options. As a result, the appearance of the Motif decorations around the toplevel window will be changed. Possible options are: -border, -menu, -maximize, -minimize, -resizeh and -title. The value must be a Boolean value. The values returned by this command are undefined when the window is not managed by mwm.

$toplevel->mwmIsmwmrunning

This returns value is true if mwm is running on the screen where the specified window is located, false otherwise.

$toplevel->mwmProtocol

When no additional options are given, this method returns all protocols associated with this toplevel window.

$toplevel->mwmProtocol(activate => protocol_name)

Activate the mwm protocol message in mwm's menu.

$toplevel->MwmProtocol(add => protocol_name, menu_message)

Add a new mwm protocol message for this toplevel window. The message is identified by the string name specified in protocol_name. A menu item will be added into mwm's menu as specified by menu_message. Once a new mwm protocol message is added to a toplevel, it can be caught by the TK protocol method. Here is an example:

$toplevel->mwmProtocol('add' => 'MY_PRINT_HELLO', '"Print Hello" _H Ctrl<Key>H');

$toplevel->protocol('MY_PRINT_HELLO' => sub {print "Hello"});

$toplevel->mwmProtocol('deactivate' => protocol_name)

Deactivate the mwm protocol message in mwm's menu.

$toplevel->mwmProtocol('delete' => protocol_name)

Delete the mwm protocol message from mwm's menu. Please note that the window manager protocol handler associated with this protocol (by the protocol method) is not deleted automatically. You have to delete the protocol handle explicitly. E.g.:

$mw->mwmProtocol('delete' => 'MY_PRINT_HELLO');

$mw->protocol('MY_PRINT_HELLO' => '');

BUGS

This is a Tix extension which perl/Tk has adopted. It has not been tested as perl/Tk's author has not got round to installing a Motif Window Manager.

On some versions of mwm, the -border will not disappear unless -resizeh is turned off. Also, the -title will not disappear unless all of -title, -menu, -maximize and -minimize are turned off.

SEE ALSO

Tk::Wm
Tk::tixWm
Tk::Toplevel

KEYWORDS

window manager, mwm, TIX

AUTHOR

Ioi Kim Lam - ioi@graphics.cis.upenn.edu


Tk::NoteBook - display several windows in limited space with notebook metaphor.

  • METHODS
  • AUTHORS

NAME

Tk::NoteBook - display several windows in limited space with notebook metaphor.

SYNOPSIS

  use Tk::NoteBook;
  ...
  $w = $frame->NoteBook();
  $page1 = $w->add("page1", options);
  $page2 = $w->add("page2", options);
  ...
  $page2 = $w->add("page2", options);

DESCRIPTION

The NoteBook widget provides a notebook metaphor to display several windows in limited space. The notebook is divided into a stack of pages of which only one is displayed at any time. The other pages can be selected by means of choosing the visual "tabs" at the top of the widget. Additionally, the <Tab> key may be used to traverse the pages. If -underline is used, Alt- bindings will also work.

The widget takes all the options that a Frame does. In addition, it supports the following options:

-dynamicgeometry

If set to false (default and recommended), the size of the NoteBook will match the size of the largest page. Otherwise the size will match the size of the current page causing the NoteBook to change size when different pages of different sizes are selected.

-ipadx

The amount of internal horizontal padding around the pages.

-ipady

The amount of internal vertical padding around the pages.

-backpagecolor

The background color of the tabs and back page.

-disabledforeground

XXX

-focuscolor

The color of the focus border around the tabs.

-font

The font of the tab labels.

-inactivebackground

XXX

-tabpadx

Horizonzal padding around the tab label.

-tabpady

Vertical padding around the tab label.

METHODS

The following methods may be used with a NoteBook object in addition to standard methods.

add(pageName, options)

Adds a page with name pageName to the notebook. Returns an object of type Frame. The recognized options are:

-anchor

Specifies how the information in a tab is to be displayed. Must be one of n, ne, e, se, s, sw, w, nw or center.

-bitmap

Specifies a bitmap to display on the tab of this page. The bitmap is displayed only if none of the -label or -image options are specified.

-image

Specifies an image to display on the tab of this page. The image is displayed only if the -label option is not specified.

-label

Specifies the text string to display on the tab of this page.

-justify

When there are multiple lines of text displayed in a tab, this option determines the justification of the lines.

-createcmd

Specifies a callback to be called the first time the page is shown on the screen. This option can be used to delay the creation of the contents of a page until necessary. It can be useful in situations where there are a large number of pages in a NoteBook widget; with -createcmd you do not have to make the user wait until all pages are constructed before displaying the first page.

-raisecmd

Specifies a callback to be called whenever this page is raised by the user.

-state

Specifies whether this page can be raised by the user. Must be either normal or disabled.

-underline

Specifies the integer index of a character to underline in the tab. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of text displayed on the widget, 1 to the next character and so on.

-wraplength

This option specifies the maximum line length of the label string on this tab. If the line length of the label string exceeds this length, then it is wrapped onto the next line so that no line is longer than the specified length. The value may be specified in any standard forms for screen distances. If this value is less than or equal to 0, then no wrapping is done: lines will break only at newline characters in the text.

delete(pageName)

Deletes the page identified by pageName.

pagecget(pageName, -option)

Returns the current value of the configuration option given by -option in the page given by pageName. Option may have any of the values accepted in the add method.

pageconfigure(pageName, options)

Like configure for the page indicated by pageName. Options may be any of the options accepted by the add method.

pages

Returns a list consisting of the names of all currently defined pages, i.e., those created with the add method.

raise(pageName)

Raise the page identified by pageName.

raised()

Returns the name of the currently raised page.

geometryinfo

Return the dimensions of the tab area.

identify(x,y)

Identify the tab's page name under the specified coordinates. Return an empty string if there's no tab.

info("pages")

Return a list of all pages.

info("focus")

Return the page name of the tab with the current focus.

info("focusnext")

Return the page name of the tab which would receive the next focus.

info("focusprev")

Return the page name of the tab which had the previous focus.

info("active")

Return the page name of the active tab.

AUTHORS

Rajappa Iyer <rsi@earthling.net> Nick Ing-Simmons <nick@ni-s.u-net.com>

This code and documentation was derived from NoteBook.tcl in Tix4.0 written by Ioi Lam. It may be distributed under the same conditions as Perl itself.


Tk::Optionmenu - Let the user select one of some predefined options values

  • OPTIONS
  • METHODS
  • EXAMPLE
  • SEE ALSO

NAME

Tk::Optionmenu - Let the user select one of some predefined options values

SYNOPSIS

    use Optionmenu;

    $opt = $w->Optionmenu(
                        -options => REFERENCE_to_OPTIONLIST,
                        -command => CALLBACK,
                        -variable => SCALAR_REF,
                        );

    $opt->addOptions( OPTIONLIST );

    # OPTION LIST is
    #   a)  $val1, $val2, $val3,...
    #   b)  [ $lab1=>$val1], [$lab2=>val2], ... ]
    #   c)  combination of a) and b), e.g.,
    #       val1, [$lab2=>val2], val3, val4, [...], ...

DESCRIPTION

The Optionmenu widget allows the user chose between a given set of options.

If the user should be able to change the available option have a look at the Tk::BrowseEntry manpage.

OPTIONS

-options

(Re)sets the list of options presented.

-command

Defines the callback that is invokes when a new option is selected.

-variable

Reference to a scalar that contains the current value of the selected option.

-textvariable

Reference to a scalar that contains the text label of the current value of the selected option.

METHODS

addOptions

Adds OPTION_LIST to the already available options.

EXAMPLE

 use Tk;
 my $mw = MainWindow->new();

 my ($var, $tvar);
 my $opt = $mw->Optionmenu(
        -options => [[jan=>1], [feb=>2], [mar=>3], [apr=>4]],
        -command => sub { print "got: ", shift, "\n" },
        -variable => \$var,
        -textvariable => \$tvar
       )->pack;

 $opt->addOptions([may=>5],[jun=>6],[jul=>7],[aug=>8]);

 my $f = $mw->Frame(-relief=>'groove', -borderwidth => 2)->pack;
 $f->Label(-textvariable=>\$tvar)->pack(-side => 'left');
 $f->Label(-text => " -> ")->pack(-side => 'left');
 $f->Label(-textvariable=>\$var)->pack(-side => 'left');

 $mw->Button(-text=>'Exit', -command=>sub{$mw->destroy})->pack;

 MainLoop;

SEE ALSO

the Tk::Menubutton manpage, the Tk::BrowseEntry manpage


Tk::PNG - PNG loader for Tk::Photo

  • AUTHOR

NAME

Tk::PNG - PNG loader for Tk::Photo

SYNOPSIS

  use Tk;
  use Tk::PNG;

  my $image = $widget->Photo('-format' => 'png', -file => 'something.png');

DESCRIPTION

This is an extension for Tk800.* which supplies PNG format loader for Photo image type.

AUTHOR

Nick Ing-Simmons <nick@ing-simmons.net>


Tk::Pane - A window panner

  • OPTIONS
  • METHODS
  • AUTHOR
  • COPYRIGHT

NAME

Tk::Pane - A window panner

SYNOPSIS

    use Tk::Pane;

    $pane = $mw->Scrolled(Pane, Name => 'fred',
        -scrollbars => 'soe',
        -sticky => 'we',
        -gridded => 'y'
    );

    $pane->Frame;

    $pane->pack;

DESCRIPTION

Tk::Pane provides a scrollable frame widget. Once created it can be treated as a frame, except it is scrollable.

OPTIONS

-gridded => direction

Specifies if the top and left edges of the pane should snap to a grid column. This option is only useful if the widgets in the pane are managed by the grid geometry manager. Possible values are x, y and xy.

-sticky => style

If Pane is larger than its requested dimensions, this option may be used to position (or stretch) the slave within its cavity. Style is a string that contains zero or more of the characters n, s, e or w. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the slave will "stick" to. If both n and s (or e and w) are specified, the slave will be stretched to fill the entire height (or width) of its cavity.

METHODS

$pane->see($widget ?,options?)

Adjusts the view so that $widget is visable. Aditional parameters in options-value pairs can be passed, each option-value pair must be one of the following

-anchor => anchor

Specifies how to make the widget visable. If not given then as much of the widget as possible is made visable.

Possible values are n, s, w, e, nw, ne, sw and se. This will cause an edge on the widget to be aligned with the corresponding edge on the pane. for example nw will cause the top left of the widget to be placed at the top left of the pane. s will cause the bottom of the widget to be placed at the bottom of the pane, and as much of the widget as possible made visable in the x direction.

$pane->xview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the left of the window, relative to the Pane as a whole (0.5 means it is halfway through the Pane, for example). The second element gives the position of the right of the window, relative to the Pane as a whole.

$pane->xview($widget)

Adjusts the view in the window so that widget is displayed at the left of the window.

$pane->xview(moveto => fraction)

Adjusts the view in the window so that fraction of the total width of the Pane is off-screen to the left. fraction must be a fraction between 0 and 1.

$pane->xview(scroll => number, what)

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number*10 screen units on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then widgets farther to the left become visible; if it is positive then widgets farther to the right become visible.

$pane->yview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the top of the window, relative to the Pane as a whole (0.5 means it is halfway through the Pane, for example). The second element gives the position of the bottom of the window, relative to the Pane as a whole.

$pane->yview($widget)

Adjusts the view in the window so that widget is displayed at the top of the window.

$pane->yview(moveto => fraction)

Adjusts the view in the window so that fraction of the total width of the Pane is off-screen to the top. fraction must be a fraction between 0 and 1.

$pane->yview(scroll => number, what)

This command shifts the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts up or down by number*10 screen units on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then widgets farther up become visible; if it is positive then widgets farther down become visible.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1997-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Tk::Panedwindow - Create and manipulate Panedwindow widgets

  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • RESIZING PANES
  • KEYWORDS

NAME

Tk::Panedwindow - Create and manipulate Panedwindow widgets

SYNOPSIS

$panedwindow = $parent->Panedwindow(?options?);

 -background    -height  -width
 -borderwidth   -orient
 -cursor        -relief

WIDGET-SPECIFIC OPTIONS

Option: -handlepad
Name: handlePad
Class: HandlePad

When sash handles are drawn, specifies the distance from the top or left end of the sash (depending on the orientation of the widget) at which to draw the handle. May be any value accepted by Tk_GetPixels.

Option: -handlesize
Name: handleSize
Class: HandleSize

Specifies the side length of a sash handle. Handles are always drawn as squares. May be any value accepted by Tk_GetPixels.

Option: -opaqueresize
Name: opaqueResize
Class: OpaqueResize

Specifies whether panes should be resized as a sash is moved (true), or if resizing should be deferred until the sash is placed (false).

Option: -sashcursor
Name: sashCursor
Class: SashCursor

Mouse cursor to use when over a sash. If null, sb_h_double_arrow will be used for horizontal Panedwindows, and sb_v_double_arrow will be used for vertical Panedwindows.

Option: -sashpad
Name: sashPad
Class: SashPad

Specifies the amount of padding to leave of each side of a sash. May be any value accepted by Tk_GetPixels.

Option: -sashrelief
Name: sashRelief
Class: SashRelief

Relief to use when drawing a sash. May be any of the standard Tk relief values.

Option: -sashwidth
Name: sashWidth
Class: SashWidth

Specifies the width of each sash. May be any value accepted by Tk_GetPixels.

Option: -showhandle
Name: showHandle
Class: ShowHandle

Specifies whether sash handles should be shown. May be any valid boolean value.

DESCRIPTION

The Panedwindow method creates a new window (given by the $panedwindow argument) and makes it into a Panedwindow widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the Panedwindow such as its default background color and relief.

A Panedwindow widget contains any number of panes, arranged horizontally or vertically, according to the value of the -orient option. Each pane contains one widget, and each pair of panes is separated by a moveable (via mouse movements) sash. Moving a sash causes the widgets on either side of the sash to be resized.

WIDGET METHODS

The Panedwindow method may be used to invoke various operations on the widget. It has the following general form:

 $widget->method(?arg arg ...?);

The following commands are possible for Panedwindow widgets:

$widget->add(?window ...? ?option value ...?);

Add one or more windows to the Panedwindow, each in a separate pane. The arguments consist of the names of one or more windows followed by pairs of arguments that specify how to manage the windows. Option may have any of the values accepted by the configure subcommand.

$widget->cget(option);

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the Panedwindow command.

$widget->configure(?option?, ?value, option, value, ...?);

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for $widget (see the Tk::configure manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the Panedwindow command.

$widget->forget(?window ...?);

Remove the pane containing $widget from the Panedwindow. All geometry management options for $widget will be forgotten.

$widget->identify(x, y);

Identify the Panedwindow component underneath the point given by x and y, in window coordinates. If the point is over a sash or a sash handle, the result is a two element list containing the index of the sash or handle, and a word indicating whether it is over a sash or a handle, such as [0, 'sash'] or [2, 'handle']. If the point is over any other part of the Panedwindow, the result is an empty list.

$widget->proxy(?args?);

This command is used to query and change the position of the sash proxy, used for rubberband-style pane resizing. It can take any of the following forms:

$widget->proxyCoord;

Return a list containing the x and y coordinates of the most recent proxy location.

$widget->proxyForget;

Remove the proxy from the display.

$widget->proxyPlace(x, y);

Place the proxy at the given x and y coordinates.

$widget->sash(?args?);

This command is used to query and change the position of sashes in the Panedwindow. It can take any of the following forms:

$widget->sashCoord(index);

Return the current x and y coordinate pair for the sash given by index. Index must be an integer between 0 and 1 less than the number of panes in the Panedwindow. The coordinates given are those of the top left corner of the region containing the sash. $widget->sashDragto(index, x, y) This command computes the difference between the given coordinates and the coordinates given to the last sash coord command for the given sash. It then moves that sash the computed difference. The return value is the empty string.

$widget->sashMark(index, x, y);

Records x and y for the sash given by index; used in conjunction with later dragto commands to move the sash.

$widget->sashPlace(index, x, y);

Place the sash given by index at the given coordinates.

$widget $widget->panecget(option);

Query a management option for $widget. Option may be any value allowed by the paneconfigure subcommand.

$widget $widget->paneconfigure(?option? ?value option value ...?);

Query or modify the management options for $widget. If no option is specified, returns a list describing all of the available options for $widget (see the Tk::configure manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. The following options are supported:

-after => $widget

Insert the window after the window specified. $widget should be the name of a window already managed by $widget.

-before => $widget

Insert the window before the window specified. $widget should be the name of a window already managed by $widget.

-height => size

Specify a height for the window. The height will be the outer dimension of the window including its border, if any. If size is an empty string, or if -height is not specified, then the height requested internally by the window will be used initially; the height may later be adjusted by the movement of sashes in the Panedwindow. Size may be any value accepted by Tk_GetPixels.

-minsize => n

Specifies that the size of the window cannot be made less than n. This constraint only affects the size of the widget in the paned dimension -- the x dimension for horizontal Panedwindows, the y dimension for vertical Panedwindows. May be any value accepted by Tk_GetPixels.

-padx => n

Specifies a non-negative value indicating how much extra space to leave on each side of the window in the X-direction. The value may have any of the forms accepted by Tk_GetPixels.

-pady => n

Specifies a non-negative value indicating how much extra space to leave on each side of the window in the Y-direction. The value may have any of the forms accepted by Tk_GetPixels.

-sticky => style

If a window's pane is larger than the requested dimensions of the window, this option may be used to position (or stretch) the window within its pane. Style is a string that contains zero or more of the characters n, s, e or w. The string can optionally contains spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the window will "stick" to. If both n and s (or e and w) are specified, the window will be stretched to fill the entire height (or width) of its cavity.

-width => size

Specify a width for the window. The width will be the outer dimension of the window including its border, if any. If size is an empty string, or if -width is not specified, then the width requested internally by the window will be used initially; the width may later be adjusted by the movement of sashes in the Panedwindow. Size may be any value accepted by Tk_GetPixels.

$widget->panes;

Returns an ordered list of the widgets managed by $widget.

RESIZING PANES

A pane is resized by grabbing the sash (or sash handle if present) and dragging with the mouse. This is accomplished via mouse motion bindings on the widget. When a sash is moved, the sizes of the panes on each side of the sash, and thus the widgets in those panes, are adjusted.

When a pane is resized from outside (eg, it is packed to expand and fill, and the containing toplevel is resized), space is added to the final (rightmost or bottommost) pane in the window.

KEYWORDS

Panedwindow, widget, geometry management


Tk::Photo - Full-color images

  • CREATING PHOTOS
  • IMAGE METHODS
  • IMAGE FORMATS
  • COLOR ALLOCATION
  • CREDITS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Photo - Full-color images

SYNOPSIS

$widget->Photo(?name??, options?)

DESCRIPTION

A photo is an image whose pixels can display any color or be transparent. A photo image is stored internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string, or it can be supplied from C code through a procedural interface. At present, only GIF, XBM, XPM, BMP, JPEG, PNG and PPM/PGM formats are supported, but an interface exists to allow additional image file formats to be added easily. A photo image is transparent in regions where no image data has been supplied or where it has been set transparent by the transparencySet subcommand.

CREATING PHOTOS

Photos are created using the Photo method. Photo supports the following options:

-data => string

Specifies the contents of the image as a string. The string can contain base64 encoded data or binary data. The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the -data and -file options are specified, the -file option takes precedence.

-format => format-name

Specifies the name of the file format for the data specified with the -data or -file option.

-file => name

name gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data.

-gamma => value

Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker.

-height => number

Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it.

-palette => palette-spec

Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The palette-spec string may be either a single decimal number, specifying the number of shades of gray to use, or three decimal numbers separated by slashes (/), specifying the number of shades of red, green and blue to use, respectively. If the first form (a single number) is used, the image will be displayed in monochrome (i.e., grayscale).

-width => number

Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it.

IMAGE METHODS

When a photo image is created, Tk also creates a new object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above.

Those options that write data to the image generally expand the size of the image, if necessary, to accommodate the data written to the image, unless the user has specified non-zero values for the -width and/or -height configuration options, in which case the width and/or height, respectively, of the image will not be changed.

The following addition methods are available for photo images:

$image->blank

Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through.

$image->copy(sourceImage ?,option value(s) ...?)

Copies a region from the image called $sourceImage (which must be a photo image) to the image called $image, possibly with pixel zooming and/or subsampling. If no options are specified, this method copies the whole of $sourceImage into $image, starting at coordinates (0,0) in $image. The following options may be specified:

-from => x1, y1, ? ,x2, y2?

Specifies a rectangular sub-region of the source image to be copied. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the -from option is not given, the default is the whole source image.

-to => x1, y1, ?, x2, y2?

Specifies a rectangular sub-region of the destination image to be affected. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. If x2 and y2 are not specified, the default value is (x1,y1) plus the size of the source region (after subsampling and zooming, if specified). If x2 and y2 are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion.

-shrink

Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the -width or -height configuration option, respectively.

-zoom => x, y

Specifies that the source region should be magnified by a factor of x in the X direction and y in the Y direction. If y is not given, the default value is the same as x. With this option, each pixel in the source image will be expanded into a block of x x y pixels in the destination image, all the same color. x and y must be greater than 0.

-subsample => x, y

Specifies that the source image should be reduced in size by using only every xth pixel in the X direction and yth pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If y is not given, the default value is the same as x.

-compositingrule => rule

Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of overlay is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of set is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is overlay.

$image->data(?option value(s), ...?)

Returns image data in the form of a string. The following options may be specified:

-background => color

If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color.

-format => format-name

Specifies the name of the image file format handler to be used. Specifically, this method searches for the first handler whose name matches a initial substring of format-name and which has the capability to read this image data. If this option is not given, this method uses the first handler that has the capability to read the image data.

-from => x1, y1, ?, x2, y2?

Specifies a rectangular region of $image to be returned. If only x1 and y1 are specified, the region extends from (x1,y1) to the bottom-right corner of $image. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region, including x1,y1 and excluding x2,y2. The default, if this option is not given, is the whole image.

-grayscale

If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale.

$image->get(x, y)

Returns the color of the pixel at coordinates (x,y) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively.

$image->put(data ?,-format=>format-name? ?,-to=> x1 y1 ?x2 y2??)

Sets pixels in $image to the data specified in data. This command first searches the list of image file format handlers for a handler that can interpret the data in data, and then reads the image encoded within into $image (the destination image). If data does not match any known format, an attempt to interpret it as a (top-to-bottom) list of scan-lines is made, with each scan-line being a (left-to-right) list of pixel colors (see Tk_GetColor for a description of valid colors.) Every scan-line must be of the same length. Note that when data is a single color name, you are instructing Tk to fill a rectangular region with that color. The following options may be specified:

-format =>format-name

Specifies the format of the image data in data. Specifically, only image file format handlers whose names begin with format-name will be used while searching for an image data format handler to read the data.

-to =>x, y ?, x2, y2?

Specifies the coordinates of the top-left corner (x1,y1) of the region of $image into which data from filename are to be read. The default is (0,0). If x2,y2 is given and data is not large enough to cover the rectangle specified by this option, the image data extracted will be tiled so it covers the entire destination rectangle. Note that if data specifies a single color value, then a region extending to the bottom-right corner represented by (x2,y2) will be filled with that color.

$image->read(filename ?,option value(s), ...?)

Reads image data from the file named filename into the image. This method first searches the list of image file format handlers for a handler that can interpret the data in filename, and then reads the image in filename into $image (the destination image). The following options may be specified:

-format => format-name

Specifies the format of the image data in filename. Specifically, only image file format handlers whose names begin with format-name will be used while searching for an image data format handler to read the data.

-from => x1, y1, x2, y2

Specifies a rectangular sub-region of the image file data to be copied to the destination image. If only x1 and y1 are specified, the region extends from (x1,y1) to the bottom-right corner of the image in the image file. If all four coordinates are specified, they specify diagonally opposite corners or the region. The default, if this option is not specified, is the whole of the image in the image file.

-shrink

If this option is specified, the size of $image will be reduced, if necessary, so that the region into which the image file data are read is at the bottom-right corner of the $image. This option will not affect the width or height of the image if the user has specified a non-zero value for the -width or -height configuration option, respectively.

-to => x, y

Specifies the coordinates of the top-left corner of the region of $image into which data from filename are to be read. The default is (0,0).

$image->redither

The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data for $image is supplied in pieces, the dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this method can be used to recalculate the dithered image in each window where the image is displayed.

$image->transparency(subcommand, ?arg, arg ...?);

Allows examination and manipulation of the transparency information in the photo image. Several subcommands are available:

$image->transparencyGet(x, y);

Returns a boolean indicating if the pixel at (x,y) is transparent.

$image->transparencySet(x, y, boolean);

Makes the pixel at (x,y) transparent if boolean is true, and makes that pixel opaque otherwise.

$image->write(filename ?,option value(s), ...?)

Writes image data from $image to a file named filename. The following options may be specified:

-background => color

If the color is specified, the data will not contain any transparency information. In all transparent pixels the color will be replaced by the specified color.

-format => format-name

Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches for the first handler whose name matches a initial substring of format-name and which has the capability to write an image file. If this option is not given, this subcommand uses the first handler that has the capability to write an image file.

-from => x1, y1, ?, x2, y2?

Specifies a rectangular region of $image to be written to the image file. If only x1 and y1 are specified, the region extends from (x1,y1) to the bottom-right corner of $image. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image.

-grayscale

If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale.

IMAGE FORMATS

The photo image code is structured to allow handlers for additional image file formats to be added easily. The photo image code maintains a list of these handlers. Handlers are added to the list by registering them with a call to Tk_CreatePhotoImageFormat. The standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG, PNG and PPM/PGM formats, which are automatically registered on initialization.

When reading an image file or processing string data specified with the -data configuration option, the photo image code invokes each handler in turn until one is found that claims to be able to read the data in the file or string. Usually this will find the correct handler, but if it doesn't, the user may give a format name with the -format option to specify which handler to use. In fact the photo image code will try those handlers whose names begin with the string specified for the -format option (the comparison is case-insensitive). For example, if the user specifies -format => gif, then a handler named GIF87 or GIF89 may be invoked, but a handler named JPEG may not (assuming that such handlers had been registered).

When writing image data to a file, the processing of the -format option is slightly different: the string value given for the -format option must begin with the complete name of the requested handler, and may contain additional information following that, which the handler can use, for example, to specify which variant to use of the formats supported by the handler. Note that not all image handlers may support writing transparency data to a file, even where the target image format does.

COLOR ALLOCATION

When a photo image is displayed in a window, the photo image code allocates colors to use to display the image and dithers the image, if necessary, to display a reasonable approximation to the image using the colors that are available. The colors are allocated as a color cube, that is, the number of colors allocated is the product of the number of shades of red, green and blue.

Normally, the number of colors allocated is chosen based on the depth of the window. For example, in an 8-bit PseudoColor window, the photo image code will attempt to allocate seven shades of red, seven shades of green and four shades of blue, for a total of 198 colors. In a 1-bit StaticGray (monochrome) window, it will allocate two colors, black and white. In a 24-bit DirectColor or TrueColor window, it will allocate 256 shades each of red, green and blue. Fortunately, because of the way that pixel values can be combined in DirectColor and TrueColor windows, this only requires 256 colors to be allocated. If not all of the colors can be allocated, the photo image code reduces the number of shades of each primary color and tries again.

The user can exercise some control over the number of colors that a photo image uses with the -palette configuration option. If this option is used, it specifies the maximum number of shades of each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes.

CREDITS

The photo image type was designed and implemented by Paul Mackerras, based on his earlier photo widget and some suggestions from John Ousterhout.

SEE ALSO

Tk::Bitmap
Tk::Image
Tk::Pixmap

KEYWORDS

photo, image, color


Tk::Pixmap - Create color images from XPM files.

  • IMAGE METHODS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Pixmap - Create color images from XPM files.

SYNOPSIS

$widget->Pixmap?(name?,options?)?

DESCRIPTION

XPM is a popular X Window image file format for storing color icons. The Pixmap image type can be used to create color images using XPM files.

Pixmaps support the following options:

-data => string

Specifies the contents of the source pixmap as a string. The string must adhere to the XPM file format (e.g., as generated by the pixmap(1) program). If both the -data and -file options are specified, the -data option takes precedence. Please note that the XPM file parsing code in the xpm library is somewhat fragile. The first line of the string must be "/* XPM */" or otherwise a segmatation fault will be caused.

-file => name

name gives the name of a file whose contents define the source pixmap. The file must adhere to the XPM file format (e.g., as generated by the pixmap(1) program).

IMAGE METHODS

When a pixmap image is created, Tk also creates a new object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above.

SEE ALSO

Tk::Image

KEYWORDS

pixmap, image, tix


Tk::Wm::Popup - popup dialog windows.

  • OPTIONS
  • AUTHOR

NAME

Tk::Wm::Popup - popup dialog windows.

SYNOPSIS

 $dialog->Popup(qw/
     -popover    => 'cursor' | $widget | undef,
     -overanchor => c | n | ne | e | se | s | sw | w | nw,
     -popanchor  => c | n | ne | e | se | s | sw | w | nw,
 /);

DESCRIPTION

You've probably had occasion to use a Dialog (or DialogBox) widget. These widgets are derived from a Toplevel (which is a subclass of Tk::Wm, the window manager) and spend most of their time in a withdrawn state. It's also common to use Toplevels as containers for custom built popup windows. Menus, too, are dialogs derived from the window manager class. For this discussion, we'll use the simple term dialog to refer any widget that pops up and awaits user interaction, whether it be a Menu, a special purpose Toplevel, or any of the dialog-type widgets, including, but not limited to, ColorEditor, Dialog, DialogBox, ErrorDialog, FileSelect, FBox, getOpenFile and getSaveFile.

When it's time to display these dialogs, we call the Perl/Tk window manager Popup method. Popup accepts three special purpose options that specify placement information in high-level terms rather than numerical coordinates. It is Popup's responsibility to take our human specifications and turn them into actual screen coordinates before displaying the dialog.

We can direct the dialog to appear in two general locations, either over another window (e.g. the root window (screen) or a particular widget), or over the cursor. This is called the popover location. Once we've made this decision we can further refine the exact placement of the dialog relative to the popover location by specifying the intersection of two anchor points. The popanchor point is associated with the dialog and the overanchor point is associated with the popover location (whether it be a window or the cursor). The point where the two anchor points coincide is the popup locus. Anchor points are string values and can be c (for center), or any of the eight cardinal compass points: n, ne, e, se, s, sw, w or nw.

For example, if -popover specifies a widget, -popanchor is sw, and -overanchor is ne, the the dialog's southwest corner pops up at the widget's northeast corner.

OPTIONS

The options recognized by Popup are as follows:

-popover

Specifies whether the dialog "pops over" a window or the cursor. It may be the string cursor, a widget reference, or undef for the root window.

-popanchor

Specifies the anchor point of the dialog. For instance, if e is specified, the right side of the dialog is the anchor.

-overanchor

Specifies where the dialog should anchor relative to the popover location. For instance, if e is specified the dialog appears over the right side of the popover location and if it's ne the the dialog is positioned at the upper-right corner of the popover location.

AUTHOR

Nick Ing-Simmons, Steve Lidie

This code is distributed under the same terms as Perl.


Tk::ProgressBar - A graphical progress bar

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • WIDGET METHODS
  • AUTHOR
  • COPYRIGHT

NAME

Tk::ProgressBar - A graphical progress bar

SYNOPSIS

    use Tk::ProgressBar;

    $progress = $parent->ProgressBar(
        -width => 200,
        -length => 20,
        -anchor => 's',
        -from => 0,
        -to => 100,
        -blocks => 10,
        -colors => [0, 'green', 50, 'yellow' , 80, 'red'],
        -variable => \$percent_done
    );

    $progress->value($position);

DESCRIPTION

Tk::ProgressBar provides a widget which will show a graphical representation of a value, given maximum and minimum reference values.

STANDARD OPTIONS

The following standard widget options are supported:

-borderwidth
-highlightthickness

Defaults to 0.

-padx

Defaults to 0.

-pady

Defaults to 0.

-relief

Defaults to sunken

-troughcolor

The color to be used for the background (trough) of the progress bar. Default is to use grey55.

WIDGET-SPECIFIC OPTIONS

-anchor

This can be used to position the start point of the bar. Default is 'w' (horizontal bar starting from the left). A vertical bar can be configured by using either 's' or 'n'.

-blocks

This controls the number of blocks to be used to construct the progress bar. The default is to break the bar into 10 blocks.

-colors

Controls the colors to be used for different positions of the progress bar. The colors should be supplied as a reference to an array containing pairs of positions and colors.

  -colors => [ 0, 'green', 50, 'red' ]

means that for the range 0 to 50 the progress bar should be green and for higher values it should be red.

-from

This sets the lower limit of the progress bar. If the bar is set to a value below the lower limt no bar will be displayed. Defaults to 0. See the -to description for more information.

-gap

This is the spacing (in pixels) between each block. Defaults to 1. Use 0 to get a continuous bar.

-length

Specifies the desired long dimension of the ProgressBar in screen units (i.e. any of the forms acceptable to Tk_GetPixels). For vertical ProgressBars this is the ProgressBars height; for horizontal scales it is the ProgressBars width. The default length is calculated from the values of -padx, -borderwidth, -highlightthickness and the difference between -from and -to.

-resolution

A real value specifying the resolution for the scale. If this value is greater than zero then the scale's value will always be rounded to an even multiple of this value, as will tick marks and the endpoints of the scale. If the value is less than zero then no rounding occurs. Defaults to 1 (i.e., the value will be integral).

-to

This sets the upper limit of the progress bar. If a value is specified (for example, using the value method) that lies above this value the full progress bar will be displayed. Defaults to 100.

-variable

Specifies the reference to a scalar variable to link to the ProgressBar. Whenever the value of the variable changes, the ProgressBar will upate to reflect this value. (See also the value method below.)

-value

The can be used to set the current position of the progress bar when used in conjunction with the standard configure. It is usually recommended to use the value method instead.

-width

Specifies the desired narrow dimension of the ProgressBar in screen units (i.e. any of the forms acceptable to Tk_GetPixels). For vertical ProgressBars this is the ProgressBars width; for horizontal bars this is the ProgressBars height. The default width is derived from the values of -borderwidth and -pady and -highlightthickness.

WIDGET METHODS

$ProgressBar->value(?value?)

If value is omitted, returns the current value of the ProgressBar. If value is given, the value of the ProgressBar is set. If $value is given but undefined the value of the option -from is used.

AUTHOR

Graham Barr <gbarr@pobox.com>

COPYRIGHT

Copyright (c) 1997-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Tk::ROText - 'readonly' perl/Tk Text widget

  • KEYS
  • SEE ALSO

NAME

Tk::ROText - 'readonly' perl/Tk Text widget

SYNOPSIS

    use Tk::ROText;
    ...
    $ro = $mw->ROText(?options,...?);

DESCRIPTION

This "IS A" text widget with all bindings removed that would alter the contents of the text widget. The contents can still be modified via method calls.

KEYS

widget, text, readonly

SEE ALSO

the Tk::Text manpage


Tk::Radiobutton - Create and manipulate Radiobutton widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS

NAME

Tk::Radiobutton - Create and manipulate Radiobutton widgets

SYNOPSIS

$radiobutton = $parent->Radiobutton(?options?);

STANDARD OPTIONS

-activebackground | -cursor | -highlightthickness | -takefocus
-activeforeground | -disabledforeground | -image | -text
-anchor | -font | -justify | -textvariable
-background | -foreground | -padx | -underline
-bitmap | -highlightbackground | -pady | -wraplength
-borderwidth | -highlightcolor | -relief

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: command
Class: Command
Switch: -command

Specifies a perl/Tk callback to associate with the button. This command is typically invoked when mouse button 1 is released over the button window. The button's global variable (-variable option) will be updated before the command is invoked.

Name: height
Class: Height
Switch: -height

Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in lines of text. If this option isn't specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it.

Name: indicatorOn
Class: IndicatorOn
Switch: -indicatoron

Specifies whether or not the indicator should be drawn. Must be a proper boolean value. If false, the relief option is ignored and the widget's relief is always sunken if the widget is selected and raised otherwise.

Command-Line Name: -offrelief
Database Name: offRelief
Database Class: OffRelief

Specifies the relief for the checkbutton when the indicator is not drawn and the checkbutton is off. The default value is raised. By setting this option to flat and setting -indicatoron false -overrelief raised, the effect is achieved of having a flat button that raises on mouse-over and which is depressed when activated. This is the behavior typically exhibited by the Bold, Italic, and Underline checkbuttons on the toolbar of a word-processor, for example.

Command-Line Name: -overrelief
Database Name: overRelief
Database Class: OverRelief

Specifies an alternative relief for the button, to be used when the mouse cursor is over the widget. This option can be used to make toolbar buttons, by configuring -relief flat -overrelief raised. If the value of this option is the empty string, then no alternative relief is used when the mouse cursor is over the button. The empty string is the default value.

Name: selectColor
Class: Background
Switch: -selectcolor

Specifies a background color to use when the button is selected. If indicatorOn is true then the color applies to the indicator. Under Windows, this color is used as the background for the indicator regardless of the select state. If indicatorOn is false, this color is used as the background for the entire widget, in place of background or activeBackground, whenever the widget is selected. If specified as an empty string then no special color is used for displaying when the widget is selected.

Name: selectImage
Class: SelectImage
Switch: -selectimage

Specifies an image to display (in place of the image option) when the radiobutton is selected. This option is ignored unless the image option has been specified.

Name: state
Class: State
Switch: -state

Specifies one of three states for the radiobutton: normal, active, or disabled. In normal state the radiobutton is displayed using the foreground and background options. The active state is typically used when the pointer is over the radiobutton. In active state the radiobutton is displayed using the activeForeground and activeBackground options. Disabled state means that the radiobutton should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledForeground and background options determine how the radiobutton is displayed.

Name: value
Class: Value
Switch: -value

Specifies value to store in the button's associated variable whenever this button is selected.

Name: variable
Class: Variable
Switch: -variable

Specifies reference to a variable to set whenever this button is selected. Changes in this variable also cause the button to select or deselect itself. Defaults to the value \$Tk::selectedButton.

Name: width
Class: Width
Switch: -width

Specifies a desired width for the button. If an image or bitmap is being displayed in the button, the value is in screen units (i.e. any of the forms acceptable to Tk_GetPixels); for text it is in characters. If this option isn't specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it.

DESCRIPTION

The Radiobutton method creates a new window (given by the $widget argument) and makes it into a radiobutton widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the radiobutton such as its colors, font, text, and initial relief. The radiobutton command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A radiobutton is a widget that displays a textual string, bitmap or image and a diamond or circle called an indicator. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the wrapLength option) and one of the characters may optionally be underlined using the underline option. A radiobutton has all of the behavior of a simple button: it can display itself in either of three different ways, according to the state option; it can be made to appear raised, sunken, or flat; it can be made to flash; and it invokes a perl/Tk callback whenever mouse button 1 is clicked over the check button.

In addition, radiobuttons can be selected. If a radiobutton is selected, the indicator is normally drawn with a selected appearance, and a Tcl variable associated with the radiobutton is set to a particular value (normally 1). Under Unix, the indicator is drawn with a sunken relief and a special color. Under Windows, the indicator is drawn with a round mark inside. If the radiobutton is not selected, then the indicator is drawn with a deselected appearance, and the associated variable is set to a different value (typically 0). Under Unix, the indicator is drawn with a raised relief and no special color. Under Windows, the indicator is drawn without a round mark inside. Typically, several radiobuttons share a single variable and the value of the variable indicates which radiobutton is to be selected. When a radiobutton is selected it sets the value of the variable to indicate that fact; each radiobutton also monitors the value of the variable and automatically selects and deselects itself when the variable's value changes. By default the variable selectedButton is used; its contents give the name of the button that is selected, or the empty string if no button associated with that variable is selected. The name of the variable for a radiobutton, plus the variable to be stored into it, may be modified with options on the command line or in the option database. Configuration options may also be used to modify the way the indicator is displayed (or whether it is displayed at all). By default a radiobutton is configured to select itself on button clicks.

WIDGET METHODS

The Radiobutton method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for radiobutton widgets:

$radiobutton->deselect

Deselects the radiobutton and sets the associated variable to an empty string. If this radiobutton was not currently selected, the command has no effect.

$radiobutton->flash

Flashes the radiobutton. This is accomplished by redisplaying the radiobutton several times, alternating between active and normal colors. At the end of the flash the radiobutton is left in the same normal/active state as when the command was invoked. This command is ignored if the radiobutton's state is disabled.

$radiobutton->invoke

Does just what would have happened if the user invoked the radiobutton with the mouse: selects the button and invokes its associated Tcl command, if there is one. The return value is the return value from the Tcl command, or an empty string if there is no command associated with the radiobutton. This command is ignored if the radiobutton's state is disabled.

$radiobutton->select

Selects the radiobutton and sets the associated variable to the value corresponding to this widget.

BINDINGS

Tk automatically creates class bindings for radiobuttons that give them the following default behavior:

[1]

On Unix systems, a radiobutton activates whenever the mouse passes over it and deactivates whenever the mouse leaves the radiobutton. On Mac and Windows systems, when mouse button 1 is pressed over a radiobutton, the button activates whenever the mouse pointer is inside the button, and deactivates whenever the mouse pointer leaves the button.

[2]

When mouse button 1 is pressed over a radiobutton it is invoked (it becomes selected and the command associated with the button is invoked, if there is one).

[3]

When a radiobutton has the input focus, the space key causes the radiobutton to be invoked.

If the radiobutton's state is disabled then none of the above actions occur: the radiobutton is completely non-responsive.

The behavior of radiobuttons can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

radiobutton, widget


Tk::Reindex - change the base index of Text-like widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • CLASS METHODS
  • BUGS
  • AUTHOR

NAME

Tk::Reindex - change the base index of Text-like widgets

SYNOPSIS

    use Tk::ReindexedText;
    $t1=$w->ReindexedText(-linestart => 2);

    use Tk::ReindexedROText;
    $t2=$w->ReindexedROText(-linestart => 0);

DESCRIPTION

Creates a new widget class based on Text-like widgets that can redefine the line number base (normally Text widgets start line numbers at 1), or possibly other manipulations on indexes.

STANDARD OPTIONS

The newly-defined widget takes all the same options as the base widget, which defaults to Text.

WIDGET-SPECIFIC OPTIONS

Name: lineStart
Class: LineStart
Switch: -linestart

Sets the line number of the first line in the Text widget. The default -toindexcmd and -fromindexcmd use this configuration option.

-item Name: toIndexCmd fromIndexCmd

-item Class: ToIndexCmd FromIndexCmd

-item Switch: -toindexcmd -fromindexcmd

These two options specify callbacks that are called with a list of indexes and are responsible for translating them to/from indexes that the base Text widget can understand. The callback is passed the widget followed by a list of indexes, and should return a list of translated indexes. -toindexcmd should translate from 'user' indexes to 'native' Text-compatible indexes, and -fromindexcmd should translate from 'native' indexes to 'user' indexes.

The default callbacks simply add/subtract the offset given by the -linestart option for all indexes in 'line.character' format.

It would probably be prudent to make these functions inverses of each other.

CLASS METHODS

import

To make new Reindex widgets, this function should be called via use with the name of the Text-like base class that you are extending with "Reindex" capability. 'use base(Tk::Reindex Tk::nameofbasewidget)' should also be specified for that widget.

BUGS

I've used the word "indexes" instead of "indices" throughout the documentation.

All the built-in perl code for widget bindings & methods will use the new 'user' indexes. Which means all this index manipulation might might break code that is trying to parse/manipulate indexes. Or even assume that '1.0' is the beginning index. Tk::Text::Contents comes to mind.

AUTHOR

Andrew Allen <ada@fc.hp.com>

This code may be distributed under the same conditions as Perl.


Tk::Scale - Create and manipulate Scale widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • KEYWORDS

NAME

Tk::Scale - Create and manipulate Scale widgets

SYNOPSIS

$scale = $parent->Scale(?options?);

STANDARD OPTIONS

-activebackground | -font | -highlightthickness | -repeatinterval
-background | -foreground | -orient | -takefocus
-borderwidth | -highlightbackground | -relief | -troughcolor
-cursor | -highlightcolor | -repeatdelay

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: bigIncrement
Class: BigIncrement
Switch: -bigincrement

Some interactions with the scale cause its value to change by ``large'' increments; this option specifies the size of the large increments. If specified as 0, the large increments default to 1/10 the range of the scale.

Name: command
Class: Command
Switch: -command

Specifies the prefix of a perl/Tk callback to invoke whenever the scale's value is changed via a method. The actual command consists of this option followed by a space and a real number indicating the new value of the scale.

Name: digits
Class: Digits
Switch: -digits

An integer specifying how many significant digits should be retained when converting the value of the scale to a string. If the number is less than or equal to zero, then the scale picks the smallest value that guarantees that every possible slider position prints as a different string.

Name: from
Class: From
Switch: -from

A real value corresponding to the left or top end of the scale.

Name: label
Class: Label
Switch: -label

A string to display as a label for the scale. For vertical scales the label is displayed just to the right of the top end of the scale. For horizontal scales the label is displayed just above the left end of the scale. If the option is specified as an empty string, no label is displayed.

Name: length
Class: Length
Switch: -length

Specifies the desired long dimension of the scale in screen units (i.e. any of the forms acceptable to Tk_GetPixels). For vertical scales this is the scale's height; for horizontal scales it is the scale's width.

Name: resolution
Class: Resolution
Switch: -resolution

A real value specifying the resolution for the scale. If this value is greater than zero then the scale's value will always be rounded to an even multiple of this value, as will tick marks and the endpoints of the scale. If the value is less than zero then no rounding occurs. Defaults to 1 (i.e., the value will be integral).

Name: showValue
Class: ShowValue
Switch: -showvalue

Specifies a boolean value indicating whether or not the current value of the scale is to be displayed.

Name: sliderLength
Class: SliderLength
Switch: -sliderlength

Specfies the size of the slider, measured in screen units along the slider's long dimension. The value may be specified in any of the forms acceptable to Tk_GetPixels.

Name: sliderRelief
Class: SliderRelief
Switch: -sliderrelief

Specifies the relief to use when drawing the slider, such as raised or sunken.

Name: state
Class: State
Switch: -state

Specifies one of three states for the scale: normal, active, or disabled. If the scale is disabled then the value may not be changed and the scale won't activate. If the scale is active, the slider is displayed using the color specified by the activeBackground option.

Name: tickInterval
Class: TickInterval
Switch: -tickinterval

Must be a real value. Determines the spacing between numerical tick marks displayed below or to the left of the slider. If 0, no tick marks will be displayed.

Name: to
Class: To
Switch: -to

Specifies a real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the from option.

Name: variable
Class: Variable
Switch: -variable

Specifies the name of a global variable to link to the scale. Whenever the value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value.

Name: width
Class: Width
Switch: -width

Specifies the desired narrow dimension of the trough in screen units (i.e. any of the forms acceptable to Tk_GetPixels). For vertical scales this is the trough's width; for horizontal scales this is the trough's height.

DESCRIPTION

The Scale method creates a new window (given by the $widget argument) and makes it into a scale widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scale such as its colors, orientation, and relief. The scale command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A scale is a widget that displays a rectangular trough and a small slider. The trough corresponds to a range of real values (determined by the from, to, and resolution options), and the position of the slider selects a particular real value. The slider's position (and hence the scale's value) may be adjusted with the mouse or keyboard as described in the BINDINGS section below. Whenever the scale's value is changed, a Tcl command is invoked (using the command option) to notify other interested widgets of the change. In addition, the value of the scale can be linked to a Tcl variable (using the variable option), so that changes in either are reflected in the other.

Three annotations may be displayed in a scale widget: a label appearing at the top right of the widget (top left for horizontal scales), a number displayed just to the left of the slider (just above the slider for horizontal scales), and a collection of numerical tick marks just to the left of the current value (just below the trough for horizontal scales). Each of these three annotations may be enabled or disabled using the configuration options.

WIDGET METHODS

The Scale method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for scale widgets:

$scale->coords(?value?)

Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to value. If value is omitted then the scale's current value is used.

$scale->get(?x, y?)

If x and y are omitted, returns the current value of the scale. If x and y are specified, they give pixel coordinates within the widget; the command returns the scale value corresponding to the given pixel. Only one of x or y is used: for horizontal scales y is ignored, and for vertical scales x is ignored.

$scale->identify(x, y)

Returns a string indicating what part of the scale lies under the coordinates given by x and y. A return value of slider means that the point is over the slider; trough1 means that the point is over the portion of the slider above or to the left of the slider; and trough2 means that the point is over the portion of the slider below or to the right of the slider. If the point isn't over one of these elements, an empty string is returned.

$scale->set(value)

This command is invoked to change the current value of the scale, and hence the position at which the slider is displayed. Value gives the new value for the scale. The command has no effect if the scale is disabled.

BINDINGS

Tk automatically creates class bindings for scales that give them the following default behavior. Where the behavior is different for vertical and horizontal scales, the horizontal behavior is described in parentheses.

[1]

If button 1 is pressed in the trough, the scale's value will be incremented or decremented by the value of the resolution option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats.

[2]

If button 1 is pressed over the slider, the slider can be dragged with the mouse.

[3]

If button 1 is pressed in the trough with the Control key down, the slider moves all the way to the end of its range, in the direction towards the mouse cursor.

[4]

If button 2 is pressed, the scale's value is set to the mouse position. If the mouse is dragged with button 2 down, the scale's value changes with the drag.

[5]

The Up and Left keys move the slider up (left) by the value of the resolution option.

[6]

The Down and Right keys move the slider down (right) by the value of the resolution option.

[7]

Control-Up and Control-Left move the slider up (left) by the value of the bigIncrement option.

[8]

Control-Down and Control-Right move the slider down (right) by the value of the bigIncrement option.

[9]

Home moves the slider to the top (left) end of its range.

[10]

End moves the slider to the bottom (right) end of its range.

If the scale is disabled using the state option then none of the above bindings have any effect.

The behavior of scales can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

scale, slider, trough, widget


Tk::Scrollbar - Create and manipulate Scrollbar widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • ELEMENTS
  • WIDGET METHODS
  • SCROLLING COMMANDS
  • OLD COMMAND SYNTAX
  • BINDINGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Scrollbar - Create and manipulate Scrollbar widgets

SYNOPSIS

$scrollbar = $parent->Scrollbar(?options?);

STANDARD OPTIONS

-activebackground | -highlightbackground | -orient | -takefocus
-background | -highlightcolor | -relief | -troughcolor
-borderwidth | -highlightthickness | -repeatdelay
-cursor | -jump | -repeatinterval

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: activeRelief
Class: ActiveRelief
Switch: -activerelief

Specifies the relief to use when displaying the element that is active, if any. Elements other than the active element are always displayed with a raised relief.

Name: command
Class: Command
Switch: -command

Specifies a callback to invoke to change the view in the widget associated with the scrollbar. When a user requests a view change by manipulating the scrollbar, the callback is invoked. The callback is passed additional arguments as described later. This option almost always has a value such as [xview => $widget] or [yview => $widget], consisting of the a widget object and either xview (if the scrollbar is for horizontal scrolling) or yview (for vertical scrolling). All scrollable widgets have xview and yview methods that take exactly the additional arguments appended by the scrollbar as described in SCROLLING COMMANDS below.

Name: elementBorderWidth
Class: BorderWidth
Switch: -elementborderwidth

Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider). The value may have any of the forms acceptable to Tk_GetPixels. If this value is less than zero, the value of the borderWidth option is used in its place.

Name: width
Class: Width
Switch: -width

Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. The value may have any of the forms acceptable to Tk_GetPixels.

DESCRIPTION

The Scrollbar method creates a new window (given by the $widget argument) and makes it into a scrollbar widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scrollbar such as its colors, orientation, and relief. The scrollbar command returns its $widget argument. At the time this command is invoked, there must not exist a window named $widget, but $widget's parent must exist.

A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a slider in the middle portion of the scrollbar. It provides information about what is visible in an associated window that displays an document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its document.

Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See BINDINGS below for details.

ELEMENTS

A scrollbar displays five elements, which are referred to in the methods for the scrollbar:

arrow1

The top or left arrow in the scrollbar.

trough1

The region between the slider and arrow1.

slider

The rectangle that indicates what is visible in the associated widget.

trough2

The region between the slider and arrow2.

arrow2

The bottom or right arrow in the scrollbar.

WIDGET METHODS

The Scrollbar method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for scrollbar widgets:

$scrollbar->activate(?element?)

Marks the element indicated by element as active, which causes it to be displayed as specified by the activeBackground and activeRelief options. The only element values understood by this command are arrow1, slider, or arrow2. If any other value is specified then no element of the scrollbar will be active. If element is not specified, the command returns the name of the element that is currently active, or an empty string if no element is active.

$scrollbar->delta(deltaX, deltaY)

Returns a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider deltaX pixels to the right (deltaY is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider deltaY pixels down. The arguments and the result may be zero or negative.

$scrollbar->fraction(x, y)

Returns a real number between 0 and 1 indicating where the point given by x and y lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. X and y must be pixel coordinates relative to the scrollbar widget. If x and y refer to a point outside the trough, the closest point in the trough is used.

$scrollbar->get

Returns the scrollbar settings in the form of a list whose elements are the arguments to the most recent set method.

$scrollbar->identify(x, y)

Returns the name of the element under the point given by x and y (such as arrow1), or an empty string if the point does not lie in any element of the scrollbar. X and y must be pixel coordinates relative to the scrollbar widget.

$scrollbar->set(first, last)

This command is invoked by the scrollbar's associated widget to tell the scrollbar about the current view in the widget. The command takes two arguments, each of which is a real fraction between 0 and 1. The fractions describe the range of the document that is visible in the associated widget. For example, if first is 0.2 and last is 0.4, it means that the first part of the document visible in the window is 20% of the way through the document, and the last visible part is 40% of the way through.

SCROLLING COMMANDS

When the user interacts with the scrollbar, for example by dragging the slider, the scrollbar notifies the associated widget that it must change its view. The scrollbar makes the notification by evaluating a callback specified as the scrollbar's -command option. The callback may take several forms. In each case, the intial arguments passed are those specified in the -command callback itself, which usually has a form like [yview => $widget]. (Which will invoke $widget->yview(...) where the ... part is as below. See the Tk::callbacks manpage for details.) The callback is passed additional arguments as follows:

moveto,fraction

Fraction is a real number between 0 and 1. The widget should adjust its view so that the point given by fraction appears at the beginning of the widget. If fraction is 0 it refers to the beginning of the document. 1.0 refers to the end of the document, 0.333 refers to a point one-third of the way through the document, and so on.

scroll,number,units

The widget should adjust its view by number units. The units are defined in whatever way makes sense for the widget, such as characters or lines in a text widget. Number is either 1, which means one unit should scroll off the top or left of the window, or -1, which means that one unit should scroll off the bottom or right of the window.

scroll,number,page

The widget should adjust its view by number pages. It is up to the widget to define the meaning of a page; typically it is slightly less than what fits in the window, so that there is a slight overlap between the old and new views. Number is either 1, which means the next page should become visible, or -1, which means that the previous page should become visible.

OLD COMMAND SYNTAX

In versions of Tk before 4.0, the set and get widget commands used a different form. This form is still supported for backward compatibility, but it is deprecated. In the old command syntax, the set method has the following form:

$scrollbar->set(totalUnits, windowUnits, firstUnit, lastUnit)

In this form the arguments are all integers. TotalUnits gives the total size of the object being displayed in the associated widget. The meaning of one unit depends on the associated widget; for example, in a text editor widget units might correspond to lines of text. WindowUnits indicates the total number of units that can fit in the associated window at one time. FirstUnit and lastUnit give the indices of the first and last units currently visible in the associated window (zero corresponds to the first unit of the object).

Under the old syntax the get method returns a list of four integers, consisting of the totalUnits, windowUnits, firstUnit, and lastUnit values from the last set method.

The callbacks generated by scrollbars also have a different form when the old syntax is being used, the callback is passed a single argument:

unit

Unit is an integer that indicates what should appear at the top or left of the associated widget's window. It has the same meaning as the firstUnit and lastUnit arguments to the set method.

The most recent set method determines whether or not to use the old syntax. If it is given two real arguments then the new syntax will be used in the future, and if it is given four integer arguments then the old syntax will be used.

BINDINGS

Tk automatically creates class bindings for scrollbars that give them the following default behavior. If the behavior is different for vertical and horizontal scrollbars, the horizontal behavior is described in parentheses.

[1]

Pressing button 1 over arrow1 causes the view in the associated widget to shift up (left) by one unit so that the document appears to move down (right) one unit. If the button is held down, the action auto-repeats.

[2]

Pressing button 1 over trough1 causes the view in the associated widget to shift up (left) by one screenful so that the document appears to move down (right) one screenful. If the button is held down, the action auto-repeats.

[3]

Pressing button 1 over the slider and dragging causes the view to drag with the slider. If the jump option is true, then the view doesn't drag along with the slider; it changes only when the mouse button is released.

[4]

Pressing button 1 over trough2 causes the view in the associated widget to shift down (right) by one screenful so that the document appears to move up (left) one screenful. If the button is held down, the action auto-repeats.

[5]

Pressing button 1 over arrow2 causes the view in the associated widget to shift down (right) by one unit so that the document appears to move up (left) one unit. If the button is held down, the action auto-repeats.

[6]

If button 2 is pressed over the trough or the slider, it sets the view to correspond to the mouse position; dragging the mouse with button 2 down causes the view to drag with the mouse. If button 2 is pressed over one of the arrows, it causes the same behavior as pressing button 1.

[7]

If button 1 is pressed with the Control key down, then if the mouse is over arrow1 or trough1 the view changes to the very top (left) of the document; if the mouse is over arrow2 or trough2 the view changes to the very bottom (right) of the document; if the mouse is anywhere else then the button press has no effect.

[8]

In vertical scrollbars the Up and Down keys have the same behavior as mouse clicks over arrow1 and arrow2, respectively. In horizontal scrollbars these keys have no effect.

[9]

In vertical scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over trough1 and trough2, respectively. In horizontal scrollbars these keys have no effect.

[10]

In horizontal scrollbars the Up and Down keys have the same behavior as mouse clicks over arrow1 and arrow2, respectively. In vertical scrollbars these keys have no effect.

[11]

In horizontal scrollbars Control-Up and Control-Down have the same behavior as mouse clicks over trough1 and trough2, respectively. In vertical scrollbars these keys have no effect.

[12]

The Prior and Next keys have the same behavior as mouse clicks over trough1 and trough2, respectively.

[13]

The Home key adjusts the view to the top (left edge) of the document.

[14]

The End key adjusts the view to the bottom (right edge) of the document.

SEE ALSO

Tk::callbacks Tk::Scrolled

KEYWORDS

scrollbar, widget


Tk::Scrolled - Create a widget with attached scrollbar

  • OPTIONS
  • ADVERTISED SUBWIDGETS
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Scrolled - Create a widget with attached scrollbar(s)

SYNOPSIS

$whatever = $parent->Scrolled(Whatever ?,-scrollbars=>where? ?,...?);

DESCRIPTION

To stop a flood of ScrlWhatever widgets Perl/Tk introcuded the special constructor Scrolled. Scrolled creates a widget of the given Class Whatever with attached scrollbar(s).

OPTIONS

All options beside -scrollbars explained below are passed to the Whatever widget constructor.

-scrollbars

Expects as argument the position where the scrollbars should be created: w, e or n, s or a combination of them. If the one or both positions are prefixed with o the scrollbar will only show up if there is a 'real' need to scroll.

ADVERTISED SUBWIDGETS

See Subwidget in the Tk::mega manpage how to use advertised widgets.

scrolled

the scrolled widget

widget

same as scrolled above. widget is the kind of widget passed to scrolled as first argument in all lowercase.

xscrollbar

the Scrollbar widget used for horizontal scrolling (if it exists)

yscrollbar

the Scrollbar widget used for vertical scrolling (if it exists)

corner

a frame in the corner between the vertical and horizontal scrolbar

BUGS

If a widget does not support -{x,y}scrollcommand options, Scrolled does not complain if the specified widget class does not support them. E.g.,

$parent->Scrolled('Button', ...)

One does not get an error message or warning when one tries to configure scrollbars after the widget construction:

$ascrolled->configure(-scrollbars => 'e');

SEE ALSO

Tk::Scrollbar

KEYWORDS

scrolled, scrollbar


Tk::Spinbox - Create and manipulate Spinbox widgets

  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • VALIDATION
  • WIDGET METHODS
  • DEFAULT BINDINGS
  • KEYWORDS

NAME

Tk::Spinbox - Create and manipulate Spinbox widgets

SYNOPSIS

$spinbox = $parent->Spinbox(?options?);

 -activebackground    -highlightthickness -repeatinterval
 -background          -insertbackground   -selectbackground
 -borderwidth         -insertborderwidth  -selectborderwidth
 -cursor              -insertontime       -selectforeground
 -exportselection     -insertwidth        -takefocus
 -font                -insertofftime      -textvariable
 -foreground          -justify            -xscrollcommand
 -highlightbackground -relief
 -highlightcolor      -repeatdelay

WIDGET-SPECIFIC OPTIONS

Option: -buttonbackground
Name: buttonBackground
Class: Background

The background color to be used for the spin buttons.

Option: -buttoncursor
Name: buttonCursor
Class: Cursor

The cursor to be used when over the spin buttons. If this is empty (the default), a default cursor will be used.

Option: -buttondownrelief
Name: buttonDownRelief
Class: Relief

The relief to be used for the upper spin button.

Option: -buttonuprelief
Name: buttonUpRelief
Class: Relief

The relief to be used for the lower spin button.

Option: -command
Name: command
Class: Command

Specifies a Perl/Tk callback to invoke whenever a Spinbutton is invoked. The callback has these two arguments appended to any existing callback arguments: the current value of the widget and the direction of the button press (up or down).

Option: -disabledbackground
Name: disabledBackground
Class: DisabledBackground

Specifies the background color to use when the Spinbox is disabled. If this option is the empty string, the normal background color is used.

Option: -disabledforeground
Name: disabledForeground
Class: DisabledForeground

Specifies the foreground color to use when the Spinbox is disabled. If this option is the empty string, the normal foreground color is used.

Option: -format
Name: format
Class: Format

Specifies an alternate format to use when setting the string value when using the -from and -to range. This must be a format specifier of the form %<pad>.<pad>f, as it will format a floating-point number.

Option: -from
Name: from
Class: From

A floating-point value corresponding to the lowest value for a Spinbox, to be used in conjunction with -to and -increment. When all are specified correctly, the Spinbox will use these values to control its contents. This value must be less than the -to option. If -values is specified, it supercedes this option.

Option: -invalidcommand
Alias: -invcmd
Name: invalidCommand
Class: InvalidCommand

Specifies a script to eval when validateCommand returns 0. Setting it to an empty string disables this feature (the default). The best use of this option is to set it to bell. See Validation below for more information.

Option: -increment
Name: increment
Class: Increment

A floating-point value specifying the increment. When used with -from and -to, the value in the widget will be adjusted by -increment when a spin button is pressed (up adds the value, down subtracts the value).

Option: -readonlybackground
Name: readonlyBackground
Class: ReadonlyBackground

Specifies the background color to use when the Spinbox is readonly. If this option is the empty string, the normal background color is used.

Option: -state
Name: state
Class: State

Specifies one of three states for the Spinbox: normal, disabled, or readonly. If the Spinbox is readonly, then the value may not be changed using methods and no insertion cursor will be displayed, even if the input focus is in the widget; the contents of the widget may still be selected. If the Spinbox is disabled, the value may not be changed, no insertion cursor will be displayed, the contents will not be selectable, and the Spinbox may be displayed in a different color, depending on the values of the -disabledforeground and -disabledbackground options.

Option: -to
Name: to
Class: To

A floating-point value corresponding to the highest value for the Spinbox, to be used in conjunction with -from and -increment. When all are specified correctly, the Spinbox will use these values to control its contents. This value must be greater than the -from option. If -values is specified, it supercedes this option.

Option: -validate
Name: validate
Class: Validate

Specifies the mode in which validation should operate: none, focus, focusin, focusout, key, or all. It defaults to none. When you want validation, you must explicitly state which mode you wish to use. See Validation below for more.

Option: -validatecommand
Alias: -vcmd
Name: validateCommand
Class: ValidateCommand

Specifies a script to evaluate when you want to validate the input in the widget. Setting it to an empty string disables this feature (the default). Validation occurs according to the value of -validate. This command must return a valid boolean value. If it returns 0 (or the valid boolean equivalent) then the value of the widget will not change and the invalidCommand will be evaluated if it is set. If it returns 1, then value will be changed. See Validation below for more information.

Option: -values
Name: values
Class: Values

Must be a proper list value. If specified, the Spinbox will use these values as to control its contents, starting with the first value. This option has precedence over the -from and -to range.

Option: -width
Name: width
Class: Width

Specifies an integer value indicating the desired width of the Spinbox window, in average-size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text.

Option: -wrap
Name: wrap
Class: Wrap

Must be a proper boolean value. If on, the Spinbox will wrap around the values of data in the widget.

DESCRIPTION

The Spinbox method creates a new window (given by the $spinbox argument) and makes it into a Spinbox widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the Spinbox such as its colors, font, and relief.

A Spinbox is an extended Entry widget that allows he user to move, or spin, through a fixed set of ascending or descending values such as times or dates in addition to editing the value as in an entry. When first created, a Spinbox's string is empty. A portion of the Spinbox may be selected as described below. If a Spinbox is exporting its selection (see the exportSelection option), then it will observe the standard protocols for handling the selection; Spinbox selections are available as type STRING. Spinboxes also observe the standard Tk rules for dealing with the input focus. When a Spinbox has the input focus it displays an insertion cursor to indicate where new characters will be inserted.

Spinboxes are capable of displaying strings that are too long to fit entirely within the widget's window. In this case, only a portion of the string will be displayed; commands described below may be used to change the view in the window. Spinboxes use the standard -xscrollcommand mechanism for interacting with scrollbars (see the description of the -xscrollcommand option for details). They also support scanning, as described below.

VALIDATION

Validation works by setting the validateCommand option to a callback which will be evaluated according to the validate option as follows:

none

Default. This means no validation will occur.

focus

validateCommand will be called when the Spinbox receives or loses focus.

focusin

validateCommand will be called when the Spinbox receives focus.

focusout

validateCommand will be called when the Spinbox loses focus.

key

validateCommand will be called when the Spinbox is edited.

all

validateCommand will be called for all above conditions.

The validateCommand and invalidCommand callbacks are invoked with at least 5 positional arguments, which are appended to any already existing callback arguments:

  • 1

    The proposed value of the entry. If you are configuring the entry widget to have a new textVariable, this will be the value of that textVariable.

  • 2

    The characters to be added (or deleted). This will be undef if validation is due to focus, explcit call to validate or if change is due to -textvariable changing.

  • 3

    The current value of entry i.e. before the proposed change.

  • 4

    The index of character string to be added/deleted, if any. Otherwise -1.

  • 5

    Type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced validation or textVariable validation.

In general, the textVariable and validateCommand can be dangerous to mix. Any problems have been overcome so that using the validateCommand will not interfere with the traditional behavior of the Spinbox widget. Using the textVariable for read-only purposes will never cause problems. The danger comes when you try set the textVariable to something that the validateCommand would not accept, which causes validate to become none (the invalidCommand will not be triggered). The same happens when an error occurs evaluating the validateCommand.

Primarily, an error will occur when the validateCommand or invalidCommand encounters an error in its script while evaluating or validateCommand does not return a valid boolean value. The validate option will also set itself to none when you edit the Spinbox widget from within either the validateCommand or the invalidCommand. Such editions will override the one that was being validated. If you wish to edit the value of the widget during validation and still have the validate option set, you should include the command

 my $val = $spinbox->cget(-validate);
 $spinbox->configure(-validate => $val);

in the validateCommand or invalidCommand (whichever one you were editing the Spinbox widget from). It is also recommended to not set an associated textVariable during validation, as that can cause the Spinbox widget to become out of sync with the textVariable.

WIDGET METHODS

The Spinbox command creates a widget object whose name is $widget. This command may be used to invoke various operations on the widget. It has the following general form:

 $widget->method(?arg arg ...?);

Many of the methods for Spinboxes take one or more indices as arguments. An index specifies a particular character in the Spinbox's string, in any of the following ways:

number

Specifies the character as a numerical index, where 0 corresponds to the first character in the string.

anchor

Indicates the anchor point for the selection, which is set with the select from and select adjust methods.

end

Indicates the character just after the last one in the Spinbox's string. This is equivalent to specifying a numerical index equal to the length of the Spinbox's string.

insert

Indicates the character adjacent to and immediately following the insertion cursor.

sel.first

Indicates the first character in the selection. It is an error to use this form if the selection isn't in the Spinbox window.

sel.last

Indicates the character just after the last one in the selection. It is an error to use this form if the selection isn't in the Spinbox window.

@number

In this form, number is treated as an x-coordinate in the Spinbox's window; the character spanning that x-coordinate is used. For example, ``@0'' indicates the left-most character in the window.

Abbreviations may be used for any of the forms above, e.g. ``e'' or ``sel.f''. In general, out-of-range indices are automatically rounded to the nearest legal value.

The following commands are possible for Spinbox widgets:

$widget->bbox(index);

Returns a list of four numbers describing the bounding box of the character given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window.

$widget->cget(option);

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the Spinbox command.

$widget->configure(?option?, ?value, option, value, ...?);

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for $widget (see the Tk::configure manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the Spinbox command.

$widget->delete(first, ?last?);

Delete one or more elements of the Spinbox. First is the index of the first character to delete, and last is the index of the character just after the last one to delete. If last isn't specified it defaults to first+1, i.e. a single character is deleted. This command returns an empty string.

$widget->get;

Returns the Spinbox's string.

$widget->icursor(index);

Arrange for the insertion cursor to be displayed just before the character given by index. Returns an empty string.

$widget->identify(x, y);

Returns the name of the window element corresponding to coordinates x and y in the Spinbox. Return value is one of: none, buttondown, buttonup, entry.

$widget->index(index);

Returns the numerical index corresponding to index.

$widget->insert(index, string);

Insert the characters of string just before the character indicated by index. Returns an empty string.

$widget->invoke(element);

Causes the specified element, either buttondown or buttonup, to be invoked, triggering the action associated with it.

$widget->scan(option, args);

This command is used to implement scanning on Spinboxes. It has two forms, depending on option:

$widget->scanMark(x);

Records x and the current view in the Spinbox window; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string.

$widget->scanDragto(x);

This command computes the difference between its x argument and the x argument to the last scan mark command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the Spinbox at high speed through the window. The return value is an empty string.

$widget->selection(option, arg);

This command is used to adjust the selection within a Spinbox. It has several forms, depending on option:

$widget->selectionAdjust(index);

Locate the end of the selection nearest to the character given by index, and adjust that end of the selection to be at index (i.e including but not going beyond index). The other end of the selection is made the anchor point for future select to commands. If the selection isn't currently in the Spinbox, then a new selection is created to include the characters between index and the most recent selection anchor point, inclusive. Returns an empty string.

$widget->selectionClear;

Clear the selection if it is currently in this widget. If the selection isn't in this widget then the command has no effect. Returns an empty string.

$widget->selectionElement(?element?);

Sets or gets the currently selected element. If a spinbutton element is specified, it will be displayed depressed.

$widget->selectionFrom(index);

Set the selection anchor point to just before the character given by index. Doesn't change the selection. Returns an empty string.

$widget->selectionPresent;

Returns 1 if there is are characters selected in the Spinbox, 0 if nothing is selected.

$widget->selectionRange(start, end);

Sets the selection to include the characters starting with the one indexed by start and ending with the one just before end. If end refers to the same character as start or an earlier one, then the Spinbox's selection is cleared.

$widget->selectionTo(index);

If index is before the anchor point, set the selection to the characters from index up to but not including the anchor point. If index is the same as the anchor point, do nothing. If index is after the anchor point, set the selection to the characters from the anchor point up to but not including index. The anchor point is determined by the most recent select from or select adjust command in this widget. If the selection isn't in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string.

$widget->set(?string?);

If string is specified, the Spinbox will try and set it to this value, otherwise it just returns the Spinbox's string. If validation is on, it will occur when setting the string.

$widget->validate;

This command is used to force an evaluation of the validateCommand independent of the conditions specified by the validate option. This is done by temporarily setting the validate option to all. It returns 0 or 1.

$widget->xview(args);

This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms:

$widget->xview;

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the Spinbox's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$widget->xview(index);

Adjusts the view in the window so that the character given by index is displayed at the left edge of the window.

$widget->xviewMoveto(fraction);

Adjusts the view in the window so that the character fraction of the way through the text appears at the left edge of the window. Fraction must be a fraction between 0 and 1.

$widget->xviewScroll(number, what);

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number average-width characters on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

DEFAULT BINDINGS

Tk automatically creates class bindings for Spinboxes that give them the following default behavior. In the descriptions below, ``word'' refers to a contiguous group of letters, digits, or ``_'' characters, or any single character other than these.

[1]

Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.

[2]

Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word. Dragging after a double click will stroke out a selection consisting of whole words.

[3]

Triple-clicking with mouse button 1 selects all of the text in the Spinbox and positions the insertion cursor before the first character.

[4]

The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words.

[5]

Clicking mouse button 1 with the Control key down will position the insertion cursor in the Spinbox without affecting the selection.

[6]

If any normal printing characters are typed in a Spinbox, they are inserted at the point of the insertion cursor.

[7]

The view in the Spinbox can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the Spinbox at the position of the mouse cursor.

[8]

If the mouse is dragged out of the Spinbox on the left or right sides while button 1 is pressed, the Spinbox will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).

[9]

The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the Spinbox and set the selection anchor. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.

[10]

The Home key, or Control-a, will move the insertion cursor to the beginning of the Spinbox and clear any selection in the Spinbox. Shift-Home moves the insertion cursor to the beginning of the Spinbox and also extends the selection to that point.

[11]

The End key, or Control-e, will move the insertion cursor to the end of the Spinbox and clear any selection in the Spinbox. Shift-End moves the cursor to the end and extends the selection to that point.

[12]

The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They don't affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.

[13]

Control-/ selects all the text in the Spinbox.

[14]

Control-\ clears any selection in the Spinbox.

[15]

The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

[16]

The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect.

[17]

The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor.

[18]

The Delete key deletes the selection, if there is one in the Spinbox. If there is no selection, it deletes the character to the right of the insertion cursor.

[19]

The BackSpace key and Control-h delete the selection, if there is one in the Spinbox. If there is no selection, it deletes the character to the left of the insertion cursor.

[20]

Control-d deletes the character to the right of the insertion cursor.

[21]

Meta-d deletes the word to the right of the insertion cursor.

[22]

Control-k deletes all the characters to the right of the insertion cursor.

[23]

Control-t reverses the order of the two characters to the right of the insertion cursor.

If the Spinbox is disabled using the -state option, then the Spinbox's view can still be adjusted and text in the Spinbox can still be selected, but no insertion cursor will be displayed and no text modifications will take place.

The behavior of Spinboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings.

KEYWORDS

Spinbox, Entry, widget


Tk::Submethods - add aliases for tk sub-commands

NAME

Tk::Submethods - add aliases for tk sub-commands

SYNOPSIS

  use Tk::Submethods ( 'command1' => [qw(sub1 sub2 sub3)],
                       'command2' => [qw(sub1 sub2 sub3)]);

DESCRIPTION

Creates ->commandSub(...) as an alias for ->command('sub',...) e.g. ->grabRelease for ->grab('release').

For each command/subcommand pair this creates a closure with command and subcommand as bound lexical variables and assigns a reference to this to a 'glob' in the callers package.

Someday the sub-commands may be created directly in the C code.


Tk::DragDrop::SunConst - Constants for Sun's Drag&Drop protocol

NAME

Tk::DragDrop::SunConst - Constants for Sun's Drag&Drop protocol

DESCRIPTION

This module defines symbolic name subs for the numeric constants that make up Sun's Drag&Drop protocol. They are in this module with Exporter as they are shared between the two halves (Dropper and Receiver) of the protocol.


Tk::TList - Create and manipulate Tix Tabular List widgets

  • SUPER-CLASS
  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • DISPLAY ITEMS
  • WIDGET METHODS
  • BINDINGS
  • EXAMPLE
  • SEE ALSO
  • KEYWORDS

NAME

Tk::TList - Create and manipulate Tix Tabular List widgets

SYNOPSIS

$tlist = $parent->TList(?options?);

SUPER-CLASS

None.

STANDARD OPTIONS

-background | -borderwidth | -class | -cursor | -foreground
-font | -height | -highlightcolor | -highlightthickness
-relief | -selectbackground | -selectforeground
-xscrollcommand | -yscrollcommand | -width

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: browsecmd
Class: BrowseCmd
Switch: -browsecmd

Specifies a perl/Tk callback to be executed when the user browses through the entries in the TList widget.

Name: command
Class: Command
Switch: -command

Specifies the perl/Tk callback to be executed when the user invokes a list entry in the TList widget. Normally the user invokes a list entry by double-clicking it or pressing the Return key.

Name: foreground
Class: Foreground
Switch: -foreground
Alias: -fg

Specifies the default foreground color for the list entries.

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window in number of characters.

Name: itemType
Class: ItemType
Switch: -itemtype

Specifies the default type of display item for this TList widget. When you call the insert methods, display items of this type will be created if the -itemtype option is not specified.

Name: orient
Class: Orient
Switch: -orient

Specifies the order of tabularizing the list entries. When set to "vertical", the entries are arranged in a column, from top to bottom. If the entries cannot be contained in one column, the remaining entries will go to the next column, and so on. When set to "horizontal", the entries are arranged in a row, from left to right. If the entries cannot be contained in one row, the remaining entries will go to the next row, and so on.

Name: padX
Class: Pad
Switch: -padx

The default horizontal padding for list entries.

Name: padY
Class: Pad
Switch: -padx

The default vertical padding for list entries.

Name: selectBackground
Class: SelectBackground
Switch: -selectbackground

Specifies the background color for the selected list entries.

Name: selectBorderWidth
Class: BorderWidth
Switch: -selectborderwidth

Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to Tk_GetPixels.

Name: selectForeground
Class: SelectForeground
Switch: -selectforeground

Specifies the foreground color for the selected list entries.

Name: selectMode
Class: SelectMode
Switch: -selectmode

Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, browse, multiple, or extended; the default value is single.

Name: sizeCmd
Class: SizeCmd
Switch: -sizecmd

Specifies a perl/Tk callback to be called whenever the TList widget changes its size. This command can be useful to implement "user scroll bars when needed" features.

Name: state
Class: State
Switch: -state

Specifies whether the TList command should react to user actions. When set to "normal", the TList reacts to user actions in the normal way. When set to "disabled", the TList can only be scrolled, but its entries cannot be selected or activated.

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in characters.

DESCRIPTION

The TList method creates a new window (given by the $widget argument) and makes it into a TList widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the TList widget such as its cursor and relief.

The TList widget can be used to display data in a tabular format. The list entries of a TList widget are similar to the entries in the Tk listbox widget. The main differences are (1) the TList widget can display the list entries in a two dimensional format and (2) you can use graphical images as well as multiple colors and fonts for the list entries.

Each list entry is identified by an index, which can be in the following forms:

number

An integer that indicates the position of the entry in the list. 0 means the first position, 1 means the second position, and so on.

end

Indicates the end of the listbox. For some commands this means just after the last entry; for other commands it means the last entry.

@x,y

Indicates the element that covers the point in the listbox window specified by x and y (in pixel coordinates). If no element covers that point, then the closest element to that point is used.

DISPLAY ITEMS

Each list entry in an TList widget is associated with a display item. The display item determines what visual information should be displayed for this list entry. Please see the Tk::DItem manpage for a list of all display items.

When a list entry is created by the insert command, the type of its display item is determined by the -itemtype option passed to these commands. If the -itemtype is omitted, then by default the type specified by this TList widget's -itemtype option is used.

WIDGET METHODS

The TList method creates a widget object.

This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for TList widgets:

$tlist->anchorSet(index)

Sets the anchor to the list entry identified by index. The anchor is the end of the selection that is fixed while dragging out a selection with the mouse.

$tlist->anchorClear

Removes the anchor, if any, from this TList widget. This only removes the surrounding highlights of the anchor entry and does not affect its selection status.

$tlist->delete(from, ?to?)

Deletes one or more list entries between the two entries specified by the indices from and to. If to is not specified, deletes the single entry specified by from.

$tlist->dragsiteSet(index)

Sets the dragsite to the list entry identified by index. The dragsite is used to indicate the source of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.

$tlist->dragsiteClear

Remove the dragsite, if any, from the this TList widget. This only removes the surrounding highlights of the dragsite entry and does not affect its selection status.

$tlist->dropsiteSet(index)

Sets the dropsite to the list entry identified by index. The dropsite is used to indicate the target of a drag-and-drop action. Currently drag-and-drop functionality has not been implemented in Tix yet.

$tlist->dropsiteClear

Remove the dropsite, if any, from the this TList widget. This only removes the surrounding highlights of the dropsite entry and does not affect its selection status.

$tlist->entrycget(index, option)

Returns the current value of the configuration option given by option for the entry indentfied by index. Option may have any of the values accepted by the insert method.

$tlist->entryconfigure(index, ?option?, ?value, option, value, ...?)

Query or modify the configuration options of the list entry identified by index. If no option is specified, returns a list describing all of the available options for index (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the method returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the method returns an empty string. Option may have any of the values accepted by the insert method. The exact set of options depends on the value of the -itemtype option passed to the the insert method when this list entry is created.

$tlist->insert(index, ?option, value, ...?)

Creates a new list entry at the position indicated by index. The following configuration options can be given to configure the list entry:

-itemtype => type

Specifies the type of display item to be display for the new list entry. type must be a valid display item type. Currently the available display item types are image, imagetext, text, and $widget. If this option is not specified, then by default the type specified by this TList widget's -itemtype option is used.

-state => state

Specifies whether this entry can be selected or invoked by the user. Must be either normal or disabled.

-data => data

Arbitrary data to be associated with the entry (a perl scalar value).

The insert method accepts additional configuration options to configure the display item associated with this list entry. The set of additional configuration options depends on the type of the display item given by the -itemtype option. Please see the Tk::DItem manpage for a list of the configuration options for each of the display item types.

$tlist->info(option, arg, ...)

Query information about the TList widget. option can be one of the following:

$tlist->info(anchor, index)

Returns the index of the current anchor, if any, of the TList widget. If the anchor is not set, returns the empty string.

$tlist->info(dragsite, index)

Returns the index of the current dragsite, if any, of the TList widget. If the dragsite is not set, returns the empty string.

$tlist->info(dropsite, index)

Returns the index of the current dropsite, if any, of the TList widget. If the dropsite is not set, returns the empty string.

$tlist->info(selection)

Returns a list of selected elements in the TList widget. If no entries are selected, returns an empty string.

$tlist->nearest(x, y)

Given an (x,y) coordinate within the TList window, this command returns the index of the TList element nearest to that coordinate.

$tlist->see(index)

Adjust the view in the TList so that the entry given by index is visible. If the entry is already visible then the command has no effect; otherwise TList scrolls to bring the element into view at the edge to which it is nearest.

$tlist->selection(option, arg, ...)

This command is used to adjust the selection within a TList widget. It has several forms, depending on option:

$tlist->selectionClear(?from?, ?to?)

When no extra arguments are given, deselects all of the list entrie(s) in this TList widget. When only from is given, only the list entry identified by from is deselected. When both from and to are given, deselects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of entries outside that range.

$tlist->selectionIncludes(index)

Returns 1 if the list entry indicated by index is currently selected; returns 0 otherwise.

$tlist->selectionSet(from, ?to?)

Selects all of the list entrie(s) between between from and to, inclusive, without affecting the selection state of entries outside that range. When only from is given, only the list entry identified by from is selected.

$tlist->xview(args)

This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms:

$tlist->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is 0.2 and the second element is 0.6, 20% of the TList entry is off-screen to the left, the middle 40% is visible in the window, and 40% of the entry is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.

$tlist->xview(index)

Adjusts the view in the window so that the list entry identified by index is aligned to the left edge of the window.

$tlist->xviewMoveto(fraction)

Adjusts the view in the window so that fraction of the total width of the TList is off-screen to the left. fraction must be a fraction between 0 and 1.

$tlist->xviewScroll(number, what)

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

$tlist->yview(?args?)

This command is used to query and change the vertical position of the entries in the widget's window. It can take any of the following forms:

$tlist->yview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the list element at the top of the window, relative to the TList as a whole (0.5 means it is halfway through the TList, for example). The second element gives the position of the list entry just after the last one in the window, relative to the TList as a whole. These are the same values passed to scrollbars via the -yscrollcommand option.

$tlist->yview(index)

Adjusts the view in the window so that the list entry given by index is displayed at the top of the window.

$tlist->yviewMoveto(fraction)

Adjusts the view in the window so that the list entry given by fraction appears at the top of the window. Fraction is a fraction between 0 and 1; 0 indicates the first entry in the TList, 0.33 indicates the entry one-third the way through the TList, and so on.

$tlist->yviewScroll(number, what)

This command adjust the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down by number lines; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier entries become visible; if it is positive then later entries become visible.

BINDINGS

[1]

If the -selectmode is "browse", when the user drags the mouse pointer over the list entries, the entry under the pointer will be highlighted and the -browsecmd procedure will be called with one parameter, the index of the highlighted entry. Only one entry can be highlighted at a time. The -command procedure will be called when the user double-clicks on a list entry.

[2]

If the -selectmode is "single", the entries will only be highlighted by mouse <ButtonRelease-1> events. When a new list entry is highlighted, the -browsecmd procedure will be called with one parameter indicating the highlighted list entry. The -command procedure will be called when the user double-clicks on a list entry.

[3]

If the -selectmode is "multiple", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. However, only a contiguous region of list entries can be selected. When the highlighted area is changed, the -browsecmd procedure will be called with an undefined parameter. It is the responsibility of the -browsecmd procedure to find out the exact highlighted selection in the TList. The -command procedure will be called when the user double-clicks on a list entry.

[4]

If the -selectmode is "extended", when the user drags the mouse pointer over the list entries, all the entries under the pointer will be highlighted. The user can also make disjointed selections using <Control-ButtonPress-1>. When the highlighted area is changed, the -browsecmd procedure will be called with an undefined parameter. It is the responsibility of the -browsecmd procedure to find out the exact highlighted selection in the TList. The -command procedure will be called when the user double-clicks on a list entry.

EXAMPLE

This example demonstrates how to use an TList to store a list of numbers:

    use strict;
    use Tk ();
    use Tk::TList;

    my $mw = Tk::MainWindow->new();
    my $image = $mw->Getimage('folder');
    my $tlist = $mw->TList(-orient => 'vertical');
    for my $text ( qw/one two three four five six seven eight nine/ ) {
        $tlist->insert('end',
                 -itemtype=>'imagetext', -image=>$image, -text=>$text);
    }

    $tlist->pack(-expand=>'yes', -fill=>'both');

    Tk::MainLoop;

SEE ALSO

Tk::options
Tk::Widget
Tk::DItem
Tk::HList
Tk::TixGrid

KEYWORDS

Tix(n), Tabular Listbox, Display Items


Tk::Table - Scrollable 2 dimensional table of Tk widgets

  • BUGS / Snags / Possible enhancements

NAME

Tk::Table - Scrollable 2 dimensional table of Tk widgets

SYNOPSIS

  use Tk::Table;

  $table = $parent->Table(-rows => number,
                          -columns => number,
                          -scrollbars => anchor,
                          -fixedrows => number,
                          -fixedcolumns => number,
                          -takefocus => boolean);

  $widget = $table->Button(...);

  $old = $table->put($row,$col,$widget);
  $old = $table->put($row,$col,"Text");  # simple Label
  $widget = $table->get($row,$col);

  $cols = $table->totalColumns;
  $rows = $table->totalRows;

  $table->see($widget);
  $table->see($row,$col);

  ($row,$col) = $table->Posn($widget);

DESCRIPTION

Tk::Table is an all-perl widget/geometry manager which allows a two dimensional table of arbitary perl/Tk widgets to be displayed.

Entries in the Table are simply ordinary perl/Tk widgets. They should be created with the Table as their parent. Widgets are positioned in the table using:

 $table->put($row,$col,$widget)

If $widget is not a reference it is treated as a string, and a Lable widget is created with the string as its text.

All the widgets in each column are set to the same width - the requested width of the widest widget in the column. Likewise, all the widgets in each row are set to the same height - the requested height of the tallest widget in the column.

A number of rows and/or columns can be marked as 'fixed' - and so can serve as 'headings' for the remainder the rows which are scrollable.

The requested size of the table as a whole is such that the number of rows specified by -rows (default 10), and number of columns specified by -columns (default 10) can be displayed.

If the Table is told it can take the keyboard focus then cursor and scroll keys scroll the displayed widgets.

The Table will create and manage its own scrollbars if requested via -scrollbars.

The table can be emptied using

 $table->clear

the widgets which were in the table are destroyed.

The Tk::Table widget is derived from a Tk::Frame, so inherits all its configure options.

BUGS / Snags / Possible enhancements

  • Very large Tables consume a lot of X windows.

  • No equivalent of pack's -anchor/-pad etc. options


perl - very old suspect documentation on porting.

NAME

Tcl vs perl - very old suspect documentation on porting.

DESCRIPTION

This isn't really a .pod yet, nor is it Tcl vs perl it is a copy of John's comparison of Malcolm's original perl/Tk port with the current one. It is also out-of-date in places.

  From: john@WPI.EDU (John Stoffel )
  Here are some thoughts on the new Tk extension and how I think the
  organization of the commands looks.  Mostly, I'm happy with it, it
  makes some things more organized and more consistent with tcl/tk, but
  since the overlying language is so different, I don't think we need to
  follow exactly the tcl/tk model for how to call the language.
  The basic structure of the Tk program is:
      require Tk;

      $top = MainWindow->new();

      #
      # create widgets
      #

      Tk::MainLoop;

      sub method1 {
      }

      sub methodN {
      }

  This is pretty much the same as tkperl5a5, with some cosmetic naming
  changes, and some more useful command name and usage changes.  A quick
  comparison in no particular order follows:
  tkperl5a5                             Tk
  -------------------------------       -----------------------------------
  $top=tkinit(name,display,sync);       $top=MainWindow->new();

  tkpack $w, ... ;              $w->pack(...)

  $w = Class::new($top, ...);   $w = $top->Class(...);

  tkmainloop;                   Tk::MainLoop;

  tkbind($w,"<key>",sub);               $w->bind("<key>",sub);

  tkdelete($w, ...);            $w->delete(...);

  $w->scanmark(...);            $w->scan("mark", ...);

  $w->scandragto(...);          $w->scan("dragto", ...);

  $w->tkselect();                       $w->Select();

  $w->selectadjust(...);                $w->selection("adjust", ...);

  $w->selectto(...);            $w->selection("to", ...);

  $w->selectfrom(...);          $w->selection("from", ...);

  $w->tkindex(...);             $w->index(...);

  tclcmd("xxx",...);              &Tk::xxx(...)    # all Tk commands, but no Tcl at all

  tclcmd("winfo", xxx, $w, ...);  $w->xxx(...);

                                $w->mark(...);

                                $w->tag(...);

  $w->grabstatus();             $w->grab("status");

  $w->grabrelease(...);         $w->grab("release", ...);

  focus($w);                    $w->focus;

  update();                     Tk->update();

  idletasks();                  Tk->update("idletasks");

  wm("cmd",$w, ...);            $w->cmd(...);

  destroy($w);                  $w->destroy();

                                Tk::option(...);
                                  $w->OptionGet(name,Class)

                                $w->place(...)
                                Tk::property(...);

  $w = Entry::new($parent,...)
  is now
  $w = $parent->Entry(...)
  As this allows new to be inherited from a Window class.
    -method=>x,-slave=>y
   is now
    -command => [x,y]
  1st element of list is treated as "method" if y is an object reference.
  (You can have -command => [a,b,c,d,e] too; b..e get passed as args).
  Object references are now hashes rather than scalars and there
  is only ever one such per window.  The Tcl_CmdInfo and PathName
  are entries in the hash.
  (This allows derived classes to
  re-bless the hash and keep their on stuff in it too.)
  Tk's "Tcl_Interp" is in fact a ref to "." window.
  You can find all the Tk windows descended from it as their object
  references get added (by PathName) into this hash.
  $w->MainWindow returns this hash from any window.
  I think that it should extend to multiple tkinits / Tk->news
  with different Display's - if Tk code does.
  Finally "bind" passes window as "extra" (or only)
  argument. Thus
  Tk::Button->bind(<Any-Enter>,"Enter");

  Binds Enter events to Tk::Button::Enter by default
  but gets called as $w->Enter so derived class of Button can just
  define its own Enter method. &EvWref and associated globals and race
  conditions are no longer needed.
  One thing to beware of : commands bound to events with $widget->bind
  follow same pattern, but get passed extra args :
  $widget->bind(<Any-1>,[sub {print shift}, $one, $two ]);

  When sub gets called it has :
     $widget $one $two
  passed.
  1st extra arg is reference to the per-widget hash that serves as the
  perl object for the widget.
  Every time an XEvent a reference to a special class is placed
  in the widget hash. It can be retrieved by $w->XEvent method.
  The methods of the XEvent class are the
  Tcl/Tk % special characters.
  Thus:
  $widget->bind(<Any-KeyPress>,
                sub {
                 my $w = shift;
                 my $e = $w->XEvent;
                 print $w->PathName," ",$e->A," pressed ,$e->xy,"\n");
                });

  XEvent->xy is a special case which returns "@" . $e->x . "," . $e->y
  which is common in Text package.
  Because of passing a blessed widget hash to "bound" subs they can be
  bound to (possibly inherited) methods of the widget's class:
  Class->bind(<Any-Down>,Down);

  sub Class::Down
  {
   my $w = shift;
   # handle down arrow
  }

  Also:
  -command and friends can take a list the 1st element can be a ref to
  as sub or a method name. Remaining elements are passed as args to the
  sub at "invoke" time. Thus :
  $b= $w->Button(blah blah, '-command' => [sub{print shift} , $fred ]);

  Should do the trick, provided $fred is defined at time of button creation.
  Thus 1st element of list is equivalent to Malcolm's -method and second
  would be his -slave.  Any further elements are a bonus and avoid
  having to pass ref to an array/hash as a slave.


Tk::Text - Create and manipulate Text widgets

  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • INDICES
  • TAGS
  • MARKS
  • EMBEDDED WINDOWS
  • EMBEDDED IMAGES
  • THE SELECTION
  • THE INSERTION CURSOR
  • THE MODIFIED FLAG
  • WIDGET METHODS
  • BINDINGS
  • TIED INTERFACE
  • PERFORMANCE ISSUES
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Text - Create and manipulate Text widgets

SYNOPSIS

text $text ?options?

-background | -highlightbackground | -insertontime | -selectborderwidth
-borderwidth | -highlightcolor | -insertwidth | -selectforeground
-cursor | -highlightthickness | -padx | -setgrid
-exportselection | -insertbackground | -pady | -takefocus
-font | -insertborderwidth | -relief | -xscrollcommand
-foreground | -insertofftime | -selectbackground | -yscrollcommand

WIDGET-SPECIFIC OPTIONS

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window, in units of characters in the font given by the -font option. Must be at least one.

Name: spacing1
Class: Spacing1
Switch: -spacing1

Requests additional space above each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display. This option may be overriden with -spacing1 options in tags.

Name: spacing2
Class: Spacing2
Switch: -spacing2

For lines that wrap (so that they cover more than one line on the display) this option specifies additional space to provide between the display lines that represent a single line of text. The value may have any of the standard forms for screen distances. This option may be overriden with -spacing2 options in tags.

Name: spacing3
Class: Spacing3
Switch: -spacing3

Requests additional space below each text line in the widget, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display. This option may be overriden with -spacing3 options in tags.

Name: state
Class: State
Switch: -state

Specifies one of two states for the text: normal or disabled. If the text is disabled then characters may not be inserted or deleted and no insertion cursor will be displayed, even if the input focus is in the widget.

Name: tabs
Class: Tabs
Switch: -tabs

Specifies a set of tab stops for the window. The option's value consists of a list of screen distances giving the positions of the tab stops. Each position may optionally be followed in the next list element by one of the keywords left, right, center, or numeric, which specifies how to justify text relative to the tab stop. Left is the default; it causes the text following the tab character to be positioned with its left edge at the tab position. Right means that the right edge of the text following the tab character is positioned at the tab position, and center means that the text is centered at the tab position. Numeric means that the decimal point in the text is positioned at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is right-justified at the tab position. For example, -tabs => [qw/2c left 4c 6c center/] creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using the spacing and alignment from the last tab stop in the list. The value of the tabs option may be overridden by -tabs options in tags. If no -tabs option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters.

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in units of characters in the font given by the -font option. If the font doesn't have a uniform width then the width of the character ``0'' is used in translating from character units to screen units.

Name: wrap
Class: Wrap
Switch: -wrap

Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. The value must be none or char or word. A wrap mode of none means that each line of text appears as exactly one line on the screen; extra characters that don't fit on the screen are not displayed. In the other modes each line of text will be broken up into several screen lines if necessary to keep all the characters visible. In char mode a screen line break may occur after any character; in word mode a line break will only be made at word boundaries.

DESCRIPTION

The Text method creates a new window (given by the $text argument) and makes it into a text widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the text such as its default background color and relief. The text command returns the path name of the new window.

A text widget displays one or more lines of text and allows that text to be edited. Text widgets support four different kinds of annotations on the text, called tags, marks, embedded windows or embedded images. Tags allow different portions of the text to be displayed with different fonts and colors. In addition, perl\/Tk callbacks can be associated with tags so that scripts are invoked when particular actions such as keystrokes and mouse button presses occur in particular ranges of the text. See TAGS below for more details.

The second form of annotation consists of marks, which are floating markers in the text. Marks are used to keep track of various interesting positions in the text as it is edited. See MARKS below for more details.

The third form of annotation allows arbitrary windows to be embedded in a text widget. See EMBEDDED WINDOWS below for more details.

The fourth form of annotation allows Tk images to be embedded in a text widget. See EMBEDDED IMAGES below for more details.

The Perl/Tk Text widget does not support undo/redo, use the TextUndo widget instead.

INDICES

Many of the methods for texts take one or more indices as arguments. An index is a string used to indicate a particular place within a text, such as a place to insert characters or one endpoint of a range of characters to delete. Indices have the syntax

 base modifier modifier modifier ...

Where base gives a starting point and the modifiers adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a base, but the modifiers are optional.

The base for an index must have one of the following forms:

line.char

Indicates char'th character on line line. Lines are numbered from 1 for consistency with other UNIX programs that use this numbering scheme. Within a line, characters are numbered from 0. If char is end then it refers to the newline character that ends the line.

@x,y

Indicates the character that covers the pixel whose x and y coordinates within the text's window are x and y.

end

Indicates the end of the text (the character just after the last newline).

mark

Indicates the character just after the mark whose name is mark.

tag.first

Indicates the first character in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.

tag.last

Indicates the character just after the last one in the text that has been tagged with tag. This form generates an error if no characters are currently tagged with tag.

$widget

Indicates the position of the embedded window referenced by $widget. This form generates an error if $widget does not reference to an embedded window.

imageName

Indicates the position of the embedded image whose name is imageName. This form generates an error if there is no embedded image by the given name.

If the base could match more than one of the above forms, such as a mark and imageName both having the same value, then the form earlier in the above list takes precedence. If modifiers follow the base index, each one of them must have one of the forms listed below. Keywords such as chars and wordend may be abbreviated as long as the abbreviation is unambiguous.

+ count chars

Adjust the index forward by count characters, moving to later lines in the text if necessary. If there are fewer than count characters in the text after the current index, then set the index to the last character in the text. Spaces on either side of count are optional.

- count chars

Adjust the index backward by count characters, moving to earlier lines in the text if necessary. If there are fewer than count characters in the text before the current index, then set the index to the first character in the text. Spaces on either side of count are optional.

+ count lines

Adjust the index forward by count lines, retaining the same character position within the line. If there are fewer than count lines after the line containing the current index, then set the index to refer to the same character position on the last line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.

- count lines

Adjust the index backward by count lines, retaining the same character position within the line. If there are fewer than count lines before the line containing the current index, then set the index to refer to the same character position on the first line of the text. Then, if the line is not long enough to contain a character at the indicated character position, adjust the character position to refer to the last character of the line (the newline). Spaces on either side of count are optional.

linestart

Adjust the index to refer to the first character on the line.

lineend

Adjust the index to refer to the last character on the line (the newline).

wordstart

Adjust the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these.

wordend

Adjust the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text then it is not modified.

If more than one modifier is present then they are applied in left-to-right order. For example, the index ``end - 1 chars'' refers to the next-to-last character in the text and ``insert wordstart - 1 c'' refers to the character just before the first one in the word containing the insertion cursor.

TAGS

The first form of annotation in text widgets is a tag. A tag is a textual string that is associated with some of the characters in a text. Tags may contain arbitrary characters, but it is probably best to avoid using the the characters `` '' (space), +, or -: these characters have special meaning in indices, so tags containing them can't be used as indices. There may be any number of tags associated with characters in a text. Each tag may refer to a single character, a range of characters, or several ranges of characters. An individual character may have any number of tags associated with it.

A priority order is defined among tags, and this order is used in implementing some of the tag-related functions described below. When a tag is defined (by associating it with characters or setting its display options or binding callbacks to it), it is given a priority higher than any existing tag. The priority order of tags may be redefined using the ``$text->tagRaise'' and ``$text->tagLower'' methods.

Tags serve three purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the background, font, and foreground options for the text widget. However, display options may be associated with individual tags using the ``$text->tagConfigure'' method. If a character has been tagged, then the display options associated with the tag override the default display style. The following options are currently supported for tags:

-background => color

Color specifies the background color to use for characters associated with the tag. It may have any of the forms accepted by Tk_GetColor.

-bgstipple => bitmap

Bitmap specifies a bitmap that is used as a stipple pattern for the background. It may have any of the forms accepted by Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used for the background.

-borderwidth => pixels

Pixels specifies the width of a 3-D border to draw around the background. It may have any of the forms accepted by Tk_GetPixels. This option is used in conjunction with the -relief option to give a 3-D appearance to the background for characters; it is ignored unless the -background option has been set for the tag.

-elide => boolean

Elide specifies whether the data should be elided. Elided data is not displayed and takes no space on screen, but further on behaves just as normal data.

-data => value

Allows an arbitrary perl scalar value to be associated with the tag.

-fgstipple => bitmap

Bitmap specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. It may have any of the forms accepted by Tk_GetBitmap. If bitmap hasn't been specified, or if it is specified as an empty string, then a solid fill will be used.

-font => fontName

FontName is the name of a font to use for drawing characters. It may have any of the forms accepted by Tk_GetFontStruct.

-foreground => color

Color specifies the color to use when drawing text and other foreground information such as underlines. It may have any of the forms accepted by Tk_GetColor.

-justify => justify

If the first character of a display line has a tag for which this option has been specified, then justify determines how to justify the line. It must be one of left, right, or center. If a line wraps, then the justification for each line on the display is determined by the first character of that display line.

-lmargin1 => pixels

If the first character of a text line has a tag for which this option has been specified, then pixels specifies how much the line should be indented from the left edge of the window. Pixels may have any of the standard forms for screen distances. If a line of text wraps, this option only applies to the first line on the display; the -lmargin2 option controls the indentation for subsequent lines.

-lmargin2 => pixels

If the first character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then pixels specifies how much the line should be indented from the left edge of the window. Pixels may have any of the standard forms for screen distances. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line.

-offset => pixels

Pixels specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line, in pixels. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. Pixels may have any of the standard forms for screen distances.

-overstrike => boolean

Specifies whether or not to draw a horizontal rule through the middle of characters. Boolean may have any of the forms accepted by Tk_GetBoolean.

-relief => relief

Relief specifies the 3-D relief to use for drawing backgrounds, in any of the forms accepted by Tk_GetRelief. This option is used in conjunction with the -borderwidth option to give a 3-D appearance to the background for characters; it is ignored unless the -background option has been set for the tag.

-rmargin => pixels

If the first character of a display line has a tag for which this option has been specified, then pixels specifies how wide a margin to leave between the end of the line and the right edge of the window. Pixels may have any of the standard forms for screen distances. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first character of that display line.

-spacing1 => pixels

Pixels specifies how much additional space should be left above each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the first line on the display.

-spacing2 => pixels

For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. Pixels may have any of the standard forms for screen distances.

-spacing3 => pixels

Pixels specifies how much additional space should be left below each text line, using any of the standard forms for screen distances. If a line wraps, this option only applies to the last line on the display.

-tabs => tabList

TabList specifies a set of tab stops in the same form as for the -tabs option for the text widget. This option only applies to a display line if it applies to the first character on that display line. If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as -tabs = " ">, then it requests default 8-character tabs as described for the tabs widget option.

-underline => boolean

Boolean specifies whether or not to draw an underline underneath characters. It may have any of the forms accepted by Tk_GetBoolean.

-wrap => mode

Mode specifies how to handle lines that are wider than the text's window. It has the same legal values as the -wrap option for the text widget: none, char, or word. If this tag option is specified, it overrides the -wrap option for the text widget.

If a character has several tags associated with it, and if their display options conflict, then the options of the highest priority tag are used. If a particular display option hasn't been specified for a particular tag, or if it is specified as an empty string, then that option will never be used; the next-highest-priority tag's option will used instead. If no tag specifies a particular display option, then the default style for the widget will be used.

The second purpose for tags is event bindings. You can associate bindings with a tag in much the same way you can associate bindings with a widget class: whenever particular X events occur on characters with the given tag, a given <perl/Tk callback|Tk::callbacks> will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. For details, see the description of the tagBind widget method below.

The third use for tags is in managing the selection. See THE SELECTION below.

MARKS

The second form of annotation in text widgets is a mark. Marks are used for remembering particular places in a text. They are something like tags, in that they have names and they refer to places in the file, but a mark isn't associated with particular characters. Instead, a mark is associated with the gap between two characters. Only a single position may be associated with a mark at any given time. If the characters around a mark are deleted the mark will still remain; it will just have new neighbor characters. In contrast, if the characters containing a tag are deleted then the tag will no longer have an association with characters in the file. Marks may be manipulated with the ``$text->mark'' text widget method, and their current locations may be determined by using the mark name as an index in methods.

Each mark also has a gravity, which is either left or right. The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. If a mark has left gravity, then the mark is treated as if it were attached to the character on its left, so the mark will remain to the left of any text inserted at the mark position. If the mark has right gravity, new text inserted at the mark position will appear to the right of the mark. The gravity for a mark defaults to right.

The name space for marks is different from that for tags: the same name may be used for both a mark and a tag, but they will refer to different things.

Two marks have special significance. First, the mark insert is associated with the insertion cursor, as described under THE INSERTION CURSOR below. Second, the mark current is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one exception: current is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released). Neither of these special marks may be deleted.

EMBEDDED WINDOWS

The third form of annotation in text widgets is an embedded window. Each embedded window annotation causes a window to be displayed at a particular point in the text. There may be any number of embedded windows in a text widget, and any widget may be used as an embedded window (subject to the usual rules for geometry management, which require the text window to be the parent of the embedded window or a descendant of its parent). The embedded window's position on the screen will be updated as the text is modified or scrolled, and it will be mapped and unmapped as it moves into and out of the visible area of the text widget. Each embedded window occupies one character's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed.

When an embedded window is added to a text widget with the widgetCreate method, several configuration options may be associated with it. These options may be modified later with the widgetConfigure method. The following options are currently supported:

-align => where

If the window is not as tall as the line in which it is displayed, this option determines where the window is displayed in the line. Where must have one of the values top (align the top of the window with the top of the line), center (center the window within the range of the line), bottom (align the bottom of the window with the bottom of the line's area), or baseline (align the bottom of the window with the baseline of the line).

-create => callback

Specifies a callback that may be evaluated to create the window for the annotation. If no -window option has been specified for the annotation this callback will be evaluated when the annotation is about to be displayed on the screen. Callback must create a window for the annotation and return the name of that window as its result. If the annotation's window should ever be deleted, callback will be evaluated again the next time the annotation is displayed.

-padx => pixels

Pixels specifies the amount of extra space to leave on each side of the embedded window. It may have any of the usual forms defined for a screen distance (see Tk_GetPixels).

-pady => pixels

Pixels specifies the amount of extra space to leave on the top and on the bottom of the embedded window. It may have any of the usual forms defined for a screen distance (see Tk_GetPixels).

-stretch => boolean

If the requested height of the embedded window is less than the height of the line in which it is displayed, this option can be used to specify whether the window should be stretched vertically to fill its line. If the -pady option has been specified as well, then the requested padding will be retained even if the window is stretched.

-window => $widget

Specifies the name of a window to display in the annotation.

EMBEDDED IMAGES

The final form of annotation in text widgets is an embedded image. Each embedded image annotation causes an image to be displayed at a particular point in the text. There may be any number of embedded images in a text widget, and a particular image may be embedded in multiple places in the same text widget. The embedded image's position on the screen will be updated as the text is modified or scrolled. Each embedded image occupies one character's worth of index space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget with imageCreate. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen.

When an embedded image is added to a text widget with the image create method, a name unique to this instance of the image is returned. This name may then be used to refer to this image instance. The name is taken to be the value of the -name option (described below). If the -name option is not provided, the -image name is used instead. If the imageName is already in use in the text widget, then #nn is added to the end of the imageName, where nn is an arbitrary integer. This insures the imageName is unique. Once this name is assigned to this instance of the image, it does not change, even though the -image or -name values can be changed with image configure.

When an embedded image is added to a text widget with the imageCreate method, several configuration options may be associated with it. These options may be modified later with the image configure method. The following options are currently supported:

-align => where

If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. Where must have one of the values top (align the top of the image with the top of the line), center (center the image within the range of the line), bottom (align the bottom of the image with the bottom of the line's area), or baseline (align the bottom of the image with the baseline of the line).

-image => image

Specifies the name of the Tk image to display in the annotation. If image is not a valid Tk image, then an error is returned.

-name => ImageName

Specifies the name by which this image instance may be referenced in the text widget. If ImageName is not supplied, then the name of the Tk image is used instead. If the imageName is already in use, #nn is appended to the end of the name as described above.

-padx => pixels

Pixels specifies the amount of extra space to leave on each side of the embedded image. It may have any of the usual forms defined for a screen distance.

-pady => pixels

Pixels specifies the amount of extra space to leave on the top and on the bottom of the embedded image. It may have any of the usual forms defined for a screen distance.

THE SELECTION

Selection support is implemented via tags. If the exportSelection option for the text widget is true then the sel tag will be associated with the selection:

[1]

Whenever characters are tagged with sel the text widget will claim ownership of the selection.

[2]

Attempts to retrieve the selection will be serviced by the text widget, returning all the characters with the sel tag.

[3]

If the selection is claimed away by another application or by another window within this application, then the sel tag will be removed from all characters in the text.

[4]

Whenever the sel tag range changes a virtual event <<Selection>> is generated.

The sel tag is automatically defined when a text widget is created, and it may not be deleted with the ``$text->tagDelete'' method. Furthermore, the selectBackground, selectBorderWidth, and selectForeground options for the text widget are tied to the -background, -borderwidth, and -foreground options for the sel tag: changes in either will automatically be reflected in the other.

THE INSERTION CURSOR

The mark named insert has special significance in text widgets. It is defined automatically when a text widget is created and it may not be unset with the ``$text->markUnset'' widget command. The insert mark represents the position of the insertion cursor, and the insertion cursor will automatically be drawn at this point whenever the text widget has the input focus.

THE MODIFIED FLAG

The text widget can keep track of changes to the content of the widget by means of the modified flag. Inserting or deleting text will set this flag. The flag can be queried, set and cleared programatically as well. Whenever the flag changes state a <<Modified>> virtual event is gener- ated. See the edit modified widget command for more details.

WIDGET METHODS

The Text method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for text widgets. In addition, the extended text widget methods as documented in "Mastering Perl/Tk" are included in this pod (with permission from the publisher, O'Reilly and Associates Inc.).

$text->adjustSelect

Moves the end point of the selection and anchor point to the mouse pointer location.

$text->bbox(index)

Returns a list of four elements describing the screen area of the character given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list.

$text->clipboardColumnCopy

Performs a rectangular copy of the currently selected text with basic compensation for tab characters.

$text->clipboardColumnCut

Performs a rectangular cut of the currently selected text with basic compensation for tab characters.

$text->clipboardColumnPaste

Performs a rectangular paste of the text in the clipboard. The upper-left corner is specified by the current position of the insert mark with basic compensation for tab characters.

$text->compare(index1, op, index2)

Compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators <, <=, ==, >=, >, or !=. If op is == then 1 is returned if the two indices refer to the same character, if op is < then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.

$text->Contents(?args?)

Query or change the entire contents of the text widget. If no arguments are given, the entire contents of the text widget are returned. If any arguments are given, the entire contents of the text widget are deleted and replaced by the argument list.

$text->debug(?boolean?)

If boolean is specified, then it must have one of the true or false values accepted by Tcl_GetBoolean. If the value is a true one then internal consistency checks will be turned on in the B-tree code associated with text widgets. If boolean has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If boolean is not specified then the command returns on or off to indicate whether or not debugging is turned on. There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down.

$text->delete(index1, ?index2?)

Delete a range of characters from the text. If both index1 and index2 are specified, then delete all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at index1 is deleted. It is not allowable to delete characters in a way that would leave the text without a newline as the last character. The command returns an empty string. If more indices are given, multiple ranges of text will be deleted. All indices are first checked for validity before any deletions are made. They are sorted and the text is removed from the last range to the first range to deleted text does not cause a undesired index shifting side-effects. If multiple ranges with the same start index are given, then the longest range is used. If overlapping ranges are given, then they will be merged into spans that do not cause deletion of text outside the given ranges due to text shifted during deletion.

$text->deleteSelected

Delete the currently selected text.

$text->deleteTextTaggedWith(tag)

Delete the text tagged with the tag parameter.

$text->deleteToEndofLine

Delete from the insert mark location to the end of line.

$text->dlineinfo(index)

Returns a list with five elements describing the area occupied by the display line containing index. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is none and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing index is not visible on the screen then the return value is an empty list.

$text->dump(?switches?, index1, ?index2?)

Return the contents of the text widget from index1 up to, but not including index2, including the text and information about marks, tags, and embedded windows. If index2 is not specified, then it defaults to one character past index1. The information is returned in the following format:

key1 value1 index1 key2 value2 index2 ...

The possible key values are text, mark, tagon, tagoff, and $text. The corresponding value is the text, mark name, tag name, or window name. The index information is the index of the start of the text, the mark, the tag transition, or the window. One or more of the following switches (or abbreviations thereof) may be specified to control the dump:

-all

Return information about all elements: text, marks, tags, and windows. This is the default.

-command => callback

Instead of returning the information as the result of the dump operation, invoke the callback on each element of the text widget within the range. The callback has three arguments appended to it before it is evaluated: the key, value, and index.

-mark

Include information about marks in the dump results.

-tag

Include information about tag transitions in the dump results. Tag information is returned as tagon and tagoff elements that indicate the begin and end of each range of each tag, respectively.

-text

Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by index2. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text seqments that each end with a newline. The newline is part of the value.

-window

Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. (It must have a create script.) In this case an empty string is returned, and you must query the window by its index position to get more information.

$text->edit( option, ?arg, arg ...? );

This command controls the undo mechanism and the modified flag. The exact behavior of the command depends on the option argument that follows the edit argument. The following forms of the command are currently supported:

$text->editModified( ?boolean? );

If boolean is not specified, returns the modified flag of the widget. The insert, delete, edit undo and edit redo commands or the user can set or clear the modified flag. If boolean is specified, sets the modified flag of the widget to boolean.

$text->editRedo;

(Not implemented, use TextUndo.) When the -undo option is true, reapplies the last undone edits provided no other edits were done since then. Generates an error when the redo stack is empty. Does nothing when the -undo option is false.

$text->editReset;

(Not implemented, use TextUndo.) Clears the undo and redo stacks.

$text->editSeparator;

(Not implemented, use TextUndo.) Inserts a separator (boundary) on the undo stack. Does nothing when the -undo option is false.

$text->editUndo;

(Not implemented, use TextUndo.) Undoes the last edit action when the -undo option is true. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the -undo option is false.

$text->FindAll(mode, case, pattern)

Removes any current selections and then performs a global text search. All matches are tagged with the sel tag.

mode can be be -exact or -regexp. See the search command for more information

case can be -nocase or -case. See the search command for more information

pattern is an exact string to match if mode is -exact or a regular expression if the match mode is -regexp.

$text->FindAndReplaceAll(mode, case, find, replace)

Same as the FindAll method, however additionally substitutes the matched text with the characters replace.

$text->FindAndReplacePopUp

Creates a find-and-replace popup window if one does not already exist. If there is currently selected text, then the 'find' field will be 'pre-filled' with the selection.

$text->FindNext(direction, mode, case, pattern)

Removes any current selections and then performs a forward or reverse text search. All matches are tagged with the sel tag. direction can be -forward or -reverse. mode, case and pattern are as for the FindAll method.

$text->FindPopUp

Creates a find popup, if one does not yet exist. If there is currently selected text, then the 'find' field will be 'pre-filled' with the selection.

$text->FindSelectionNext

Gets the currently selected text and removes all selections. It then finds the next exact, case-sensitive string that matches in a forward direction and selects the text and makes the new selection visible.

$text->FindSelectionPrevious

Gets the currently selected text and removes all selections. It then finds the next exact, case-sensitive string that matches in a reverse direction and selects the text and makes the new selection visible.

$text->get(index1, ?index2?)

Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is index1 and ending just before the one whose index is index2 (the character at index2 will not be returned). If index2 is omitted then the single character at index1 is returned. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in the list. The ranges are returned in the order passed to get.

$text->getSelected

Return the currently selected text.

$text->GetTextTaggedWith(tag)

Return the text tagged with the tag parameter.

$text->GotoLineNumber(line_number)

Set the insert mark to line_number and ensures the line is visible.

$text->GotoLineNumberPopUp(line_number)

Displays a popup, pre-filling it with selected numeric text (if any), or the line number from GotoLineNumber (if any).

$text->image(option, ?arg, arg, ...?)
$text->image Option(?arg, arg, ...?)

This method is used to manipulate embedded images. The behavior of the method depends on the option argument that follows the image prefix. The following forms of the methods are currently supported:

$text->imageCget(index, option)

Returns the value of a configuration option for an embedded image. Index identifies the embedded image, and option specifies a particular configuration option, which must be one of the ones listed in EMBEDDED IMAGES.

$text->imageConfigure(index, ?option, value, ...?)

Query or modify the configuration options for an embedded image. If no option is specified, returns a list describing all of the available options for the embedded image at index (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See EMBEDDED IMAGES for information on the options that are supported.

$text->imageCreate(index, ?option, value, ...?)

This command creates a new image annotation, which will appear in the text at the position given by index. Any number of option-value pairs may be specified to configure the annotation. Returns a unique identifier that may be used as an index to refer to this image. See EMBEDDED IMAGES for information on the options that are supported, and a description of the identifier returned.

$text->imageNames

Returns a list whose elements are the names of all image instances currently embedded in $text.

$text->index(index)

Returns the position corresponding to index in the form line.char where line is the line number and char is the character number. Index may have any of the forms described under INDICES above.

$text->insert(index, chars, ?tagList, chars, tagList, ...?)

Inserts all of the chars arguments just before the character at index. If index refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single chars argument and no tagList, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If tagList is specified then it consists of a list of tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple chars-tagList argument pairs are present, they produce the same effect as if a separate insert widget command had been issued for each pair, in order. The last tagList argument may be omitted.

$text->Insert(string)

Do NOT confuse this with the lower-case insert method. Insert string at the point of the insertion cursor. If there is a selection in the text, and it covers the point of the insertion cursor, then it deletes the selection before inserting.

$text->InsertKeypress(character)

Inserts character at the insert mark. If in overstrike mode, it firsts deletes the character at the insert mark.

$text->InsertSelection

Inserts the current selection at the insert mark.

$text->insertTab

Inserts a tab (\t) character at the insert mark.

$text->mark(option, ?arg, arg, ...?)

This command is used to manipulate marks. The exact behavior of the command depends on the option argument that follows the mark argument. The following forms of the command are currently supported:

$text->markGravity(markName, ?direction?)

If direction is not specified, returns left or right to indicate which of its adjacent characters markName is attached to. If direction is specified, it must be left or right; the gravity of markName is set to the given value.

$text->markNames

Returns a list whose elements are the names of all the marks that are currently set.

$text->markNext(index)

Returns the name of the next mark at or after index. If index is specified in numerical form, then the search for the next mark begins at that index. If index is the name of a mark, then the search for the next mark begins immediately after that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the mark next operation can be used to step through all the marks in a text widget in the same order as the mark information returned by the dump operation. If a mark has been set to the special end index, then it appears to be after end with respect to the mark next operation. An empty string is returned if there are no marks after index.

$text->markPrevious(index)

Returns the name of the mark at or before index. If index is specified in numerical form, then the search for the previous mark begins with the character just before that index. If index is the name of a mark, then the search for the next mark begins immediately before that mark. This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the mark previous operation can be used to step through all the marks in a text widget in the reverse order as the mark information returned by the dump operation. An empty string is returned if there are no marks before index.

$text->markSet(markName, index)

Sets the mark named markName to a position just before the character at index. If markName already exists, it is moved from its old position; if it doesn't exist, a new mark is created. This command returns an empty string.

$text->markUnset(markName?, markName, markName, ...?)

Remove the mark corresponding to each of the markName arguments. The removed marks will not be usable in indices and will not be returned by future calls to ``$text->markNames''. This command returns an empty string.

$text->markExists(markname)

Returns true if markname exists - false otherwise.

$text->menu(?menu?)

If menu reference is given as an argument, then the text widget menu is adjusted to use this new menu. If the menu argument is undef, then this command disables the current text widget menu. If the menu argument is omitted altogether, then the current text widget menu reference is returned.

$text->openLine

Inserts a newline (\n) at the insert mark.

$text->OverstrikeMode(?boolean?)

Returns the overstrike mode if boolean is omitted or sets the overstrike mode to boolean. True means overstrike mode is enabled.

$text->PostPopupMenu(x,y)

Creates a popup menu at the specified (x,y) pixel coordinates. The default menu has File, Edit, Search and View menu items which cascade to sub-menus for further commands. There is an implicit <Button-3> binding to this method that posts the menu over the cursor.

$text->ResetAnchor

Sets the selection anchor to whichever end is farthest from the index argument.

$text->scan(option, args) or
$text->scan option(args)

This method is used to implement scanning on texts. It has two forms, depending on option:

$text->scanMark(x, y)

Records x and y and the current view in the text window, for use in conjunction with later scanDragto method. Typically this method is associated with a mouse button press in the widget. It returns an empty string.

$text->scanDragto(x, y)

This command computes the difference between its x and y arguments and the x and y arguments to the last scanMark method for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string.

$text->search(?switches,? pattern, index, ?stopIndex?)

Searches the text in $text starting at index for a range of characters that matches pattern. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search:

-forwards

The search will proceed forward through the text, finding the first matching range starting at or after the position given by index. This is the default.

-backwards

The search will proceed backward through the text, finding the matching range closest to index whose first character is before index.

-exact

Use exact matching: the characters in the matching range must be identical to those in pattern. This is the default.

-regexp

Treat pattern as a regular expression and match it against the text using the rules for regular expressions (see the regexp command for details).

-nocase

Ignore case differences between the pattern and the text.

-count varName

The argument following -count gives the name of a variable; if a match is found, the number of characters in the matching range will be stored in the variable.

-hidden

Find hidden text as well. By default only displayed text is found.

--

This switch has no effect except to terminate the list of switches: the next argument will be treated as pattern even if it starts with -.

The matching range must be entirely within a single line of text. For regular expression matching the newlines are removed from the ends of the lines before matching: use the $ feature in regular expressions to match the end of a line. For exact matching the newlines are retained. If stopIndex is specified, the search stops at that index: for forward searches, no match at or after stopIndex will be considered; for backward searches, no match earlier in the text than stopIndex will be considered. If stopIndex is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if stopIndex is specified, no wrap-around will occur.

$text->see(index)

Adjusts the view in the window so that the character given by index is completely visible. If index is already visible then the command does nothing. If index is a short distance out of view, the command adjusts the view just enough to make index visible at the edge of the window. If index is far out of view, then the command centers index in the window.

$text->selectAll

Selects all the text in the widget.

$text->selectLine

Selects the line with the insert mark.

$text->selectWord

Selects the word with the insert mark.

$text->SetCursor(position)

Moves the insert mark to position.

$text->tag(option, ?arg, arg, ...?)

This command is used to manipulate tags. The exact behavior of the command depends on the option argument that follows the tag argument. The following forms of the command are currently supported:

$text->tagAdd(tagName, index1, ?index2, index1, index2, ...?)

Associate the tag tagName with all of the characters starting with index1 and ending just before index2 (the character at index2 isn't tagged). A single command may contain any number of index1-index2 pairs. If the last index2 is omitted then the single character at index1 is tagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect.

$text->tagBind(tagName, ?sequence?, ?script?)

This command associates script with the tag given by tagName. Whenever the event sequence given by sequence occurs for a character that has been tagged with tagName, the script will be invoked. This method is similar to the bind command except that it operates on characters in a text rather than entire widgets. See the the Tk::bind manpage documentation for complete details on the syntax of sequence and the substitutions performed on script before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName (if the first character of script is ``+'' then script augments an existing binding rather than replacing it). In this case the return value is an empty string. If script is omitted then the command returns the script associated with tagName and sequence (an error occurs if there is no such binding). If both script and sequence are omitted then the command returns a list of all the sequences for which bindings have been defined for tagName.

The only events for which bindings may be specified are those related to the mouse and keyboard (such as Enter, Leave, ButtonPress, Motion, and KeyPress) or virtual events. Event bindings for a text widget use the current mark described under MARKS above. An Enter event triggers for a tag when the tag first becomes present on the current character, and a Leave event triggers for a tag when it ceases to be present on the current character. Enter and Leave events can happen either because the current mark moved or because the character at that position changed. Note that these events are different than Enter and Leave events for windows. Mouse and keyboard events are directed to the current character. If a virtual event is used in a binding, that binding can trigger only if the virtual event is defined by an underlying mouse-related or keyboard-related event.

It is possible for the current character to have multiple tags, and for each of them to have a binding for a particular event sequence. When this occurs, one binding is invoked for each tag, in order from lowest-priority to highest priority. If there are multiple matching bindings for a single tag, then the most specific binding is chosen (see the the documentation for the bind command for details). continue and break commands within binding scripts are processed in the same way as for bindings created with the bind command.

If bindings are created for the widget as a whole using the bind command, then those bindings will supplement the tag bindings. The tag bindings will be invoked first, followed by bindings for the window as a whole.

$text->tagCget(tagName, option)

This command returns the current value of the option named option associated with the tag given by tagName. Option may have any of the values accepted by the tag configure method.

$text->tagConfigure(tagName, ?option?, ?value?, ?option, value, ...?)

This command is similar to the configure method except that it modifies options associated with the tag given by tagName instead of modifying options for the overall text widget. If no option is specified, the command returns a list describing all of the available options for tagName (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s) in tagName; in this case the command returns an empty string. See TAGS above for details on the options available for tags.

$text->tagDelete(tagName, ?tagName, ...?)

Deletes all tag information for each of the tagName arguments. The command removes the tags from all characters in the file and also deletes any other information associated with the tags, such as bindings and display information. The command returns an empty string.

$text->tagLower(tagName?, belowThis?)

Changes the priority of tag tagName so that it is just lower in priority than the tag whose name is belowThis. If belowThis is omitted, then tagName's priority is changed to make it lowest priority of all tags.

$text->tagNames(?index?)

Returns a list whose elements are the names of all the tags that are active at the character position given by index. If index is omitted, then the return value will describe all of the tags that exist for the text (this includes all tags that have been named in a ``$text->tag'' widget command but haven't been deleted by a ``$text->tagDelete'' method, even if no characters are currently marked with the tag). The list will be sorted in order from lowest priority to highest priority.

$text->tagNextrange(tagName, index1, ?index2?)

This command searches the text for a range of characters tagged with tagName where the first character of the range is no earlier than the character at index1 and no later than the character just before index2 (a range starting at index2 will not be considered). If several matching ranges exist, the first one is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If index2 is not given then it defaults to the end of the text.

$text->tagPrevrange(tagName, index1, ?index2?)

This command searches the text for a range of characters tagged with tagName where the first character of the range is before the character at index1 and no earlier than the character at index2 (a range starting at index2 will be considered). If several matching ranges exist, the one closest to index1 is chosen. The command's return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If index2 is not given then it defaults to the beginning of the text.

$text->tagRaise(tagName, ?aboveThis?)

Changes the priority of tag tagName so that it is just higher in priority than the tag whose name is aboveThis. If aboveThis is omitted, then tagName's priority is changed to make it highest priority of all tags.

$text->tagRanges(tagName)

Returns a list describing all of the ranges of text that have been tagged with tagName. The first two elements of the list describe the first tagged range in the text, the next two elements describe the second range, and so on. The first element of each pair contains the index of the first character of the range, and the second element of the pair contains the index of the character just after the last one in the range. If there are no characters tagged with tag then an empty string is returned.

$text->tagRemove(tagName, index1, ?index2, index1, index2, ...?)

Remove the tag tagName from all of the characters starting at index1 and ending just before index2 (the character at index2 isn't affected). A single command may contain any number of index1-index2 pairs. If the last index2 is omitted then the single character at index1 is tagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect. This command returns an empty string.

$text->ToggleInsertMode

Toggles the current overstrike mode.

$text->unselectAll

Unselects all the text in the widget.

$text->WhatLineNumberPopup

Creates a popup that displays the current line number of the insert mark.

$text->widget(option?, arg, arg, ...?)
$text->widget Option(?arg, arg, ...?)

This method is used to manipulate embedded windows. The behavior of the method depends on the option argument that follows the window argument. The following forms of the method are currently supported:

$text->windowCget(index, option)

Returns the value of a configuration option for an embedded window. Index identifies the embedded window, and option specifies a particular configuration option, which must be one of the ones listed in EMBEDDED WINDOWS above.

$text->windowConfigure(index?, option, value, ...?)

Query or modify the configuration options for an embedded window. If no option is specified, returns a list describing all of the available options for the embedded window at index (see the Tk::options manpage for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. See EMBEDDED WINDOWS above for information on the options that are supported.

$text->windowCreate(index?, option, value, ...?)

This command creates a new window annotation, which will appear in the text at the position given by index. Any number of option-value pairs may be specified to configure the annotation. See EMBEDDED WINDOWS above for information on the options that are supported. Returns an empty string.

$text->windowNames

Returns a list whose elements are the names of all windows currently embedded in $text.

$text->xview(option, args)

This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms:

$text->xview

Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the portion of the document's horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. The fractions refer only to the lines that are actually visible in the window: if the lines in the window are all very short, so that they are entirely visible, the returned fractions will be 0 and 1, even if there are other lines in the text that are much wider than the window. These are the same values passed to scrollbars via the -xscrollcommand option.

$text->xviewMoveto(fraction)

Adjusts the view in the window so that fraction of the horizontal span of the text is off-screen to the left. Fraction is a fraction between 0 and 1.

$text->xviewScroll(number, what)

This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number average-width characters on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.

$text->yview(?args?)

This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms:

$text->yview

Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the first character in the top line in the window, relative to the text as a whole (0.5 means it is halfway through the text, for example). The second element gives the position of the character just after the last one in the bottom line of the window, relative to the text as a whole. These are the same values passed to scrollbars via the -yscrollcommand option.

$text->yviewMoveto(fraction)

Adjusts the view in the window so that the character given by fraction appears on the top line of the window. Fraction is a fraction between 0 and 1; 0 indicates the first character in the text, 0.33 indicates the character one-third the way through the text, and so on.

$text->yviewScroll(number, what)

This command adjust the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down by number lines on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier positions in the text become visible; if it is positive then later positions in the text become visible.

$text->yview(?-pickplace,? index)

Changes the view in the $text's window to make index visible. If the -pickplace option isn't specified then index will appear at the top of the window. If -pickplace is specified then the widget chooses where index appears in the window:

[1]

If index is already visible somewhere in the window then the command does nothing.

[2]

If index is only a few lines off-screen above the window then it will be positioned at the top of the window.

[3]

If index is only a few lines off-screen below the window then it will be positioned at the bottom of the window.

[4]

Otherwise, index will be centered in the window.

The -pickplace option has been obsoleted by the see widget command (see handles both x- and y-motion to make a location visible, whereas -pickplace only handles motion in y).

$text->yview(number)

This command makes the first character on the line after the one given by number visible at the top of the window. Number must be an integer. This command used to be used for scrolling, but now it is obsolete.

BINDINGS

Tk automatically creates class bindings for texts that give them the following default behavior. In the descriptions below, ``word'' refers to a contiguous group of letters, digits, or ``_'' characters, or any single character other than these.

[1]

Clicking mouse button 1 positions the insertion cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 strokes out a selection between the insertion cursor and the character under the mouse.

[2]

Double-clicking with mouse button 1 selects the word under the mouse and positions the insertion cursor at the beginning of the word. Dragging after a double click will stroke out a selection consisting of whole words.

[3]

Triple-clicking with mouse button 1 selects the line under the mouse and positions the insertion cursor at the beginning of the line. Dragging after a triple click will stroke out a selection consisting of whole lines.

[4]

The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down; this will adjust the end of the selection that was nearest to the mouse cursor when button 1 was pressed. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words; if it is triple-clicked then the selection will be adjusted in units of whole lines.

[5]

Clicking mouse button 1 with the Control key down will reposition the insertion cursor without affecting the selection.

[6]

If any normal printing characters are typed, they are inserted at the point of the insertion cursor.

[7]

The view in the widget can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the text at the position of the mouse cursor. The Insert key also inserts the selection, but at the position of the insertion cursor.

[8]

If the mouse is dragged out of the widget while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window).

[9]

The Left and Right keys move the insertion cursor one character to the left or right; they also clear any selection in the text. If Left or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Left and Control-Right move the insertion cursor by words, and Control-Shift-Left and Control-Shift-Right move the insertion cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. Meta-b and Meta-f behave the same as Control-Left and Control-Right, respectively.

[10]

The Up and Down keys move the insertion cursor one line up or down and clear any selection in the text. If Up or Right is typed with the Shift key down, then the insertion cursor moves and the selection is extended to include the new character. Control-Up and Control-Down move the insertion cursor by paragraphs (groups of lines separated by blank lines), and Control-Shift-Up and Control-Shift-Down move the insertion cursor by paragraphs and also extend the selection. Control-p and Control-n behave the same as Up and Down, respectively.

[11]

The Next and Prior keys move the insertion cursor forward or backwards by one screenful and clear any selection in the text. If the Shift key is held down while Next or Prior is typed, then the selection is extended to include the new character. Control-v moves the view down one screenful without moving the insertion cursor or adjusting the selection.

[12]

Control-Next and Control-Prior scroll the view right or left by one page without moving the insertion cursor or affecting the selection.

[13]

Home and Control-a move the insertion cursor to the beginning of its line and clear any selection in the widget. Shift-Home moves the insertion cursor to the beginning of the line and also extends the selection to that point.

[14]

End and Control-e move the insertion cursor to the end of the line and clear any selection in the widget. Shift-End moves the cursor to the end of the line and extends the selection to that point.

[15]

Control-Home and Meta-< move the insertion cursor to the beginning of the text and clear any selection in the widget. Control-Shift-Home moves the insertion cursor to the beginning of the text and also extends the selection to that point.

[16]

Control-End and Meta-> move the insertion cursor to the end of the text and clear any selection in the widget. Control-Shift-End moves the cursor to the end of the text and extends the selection to that point.

[17]

The Select key and Control-Space set the selection anchor to the position of the insertion cursor. They don't affect the current selection. Shift-Select and Control-Shift-Space adjust the selection to the current position of the insertion cursor, selecting from the anchor to the insertion cursor if there was not any selection previously.

[18]

Control-/ selects the entire contents of the widget.

[19]

Control-\ clears any selection in the widget.

[20]

The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

[21]

The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. If there is no selection in the widget then these keys have no effect.

[22]

The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor.

[23]

The Delete key deletes the selection, if there is one in the widget. If there is no selection, it deletes the character to the right of the insertion cursor.

[24]

Backspace and Control-h delete the selection, if there is one in the widget. If there is no selection, they delete the character to the left of the insertion cursor.

[25]

Control-d deletes the character to the right of the insertion cursor.

[26]

Meta-d deletes the word to the right of the insertion cursor.

[27]

Control-k deletes from the insertion cursor to the end of its line; if the insertion cursor is already at the end of a line, then Control-k deletes the newline character.

[28]

Control-o opens a new line by inserting a newline character in front of the insertion cursor without moving the insertion cursor.

[29]

Meta-backspace and Meta-Delete delete the word to the left of the insertion cursor.

[30]

Control-x deletes whatever is selected in the text widget.

[31]

Control-t reverses the order of the two characters to the right of the insertion cursor.

[32]

Control-z (and Control-underscore on UNIX when tk_strictMotif is true) undoes the last edit action if the -undo option is true. Does nothing otherwise.

[33]

Control-Z (or Control-y on Windows) reapplies the last undone edit action if the -undo option is true. Does nothing otherwise.

If the widget is disabled using the -state option, then its view can still be adjusted and text can still be selected, but no insertion cursor will be displayed and no text modifications will take place.

The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings.

TIED INTERFACE

The Perl/Tk Text widget also has built-in TIEHANDLE methods for print and printf statements. This means you can print to file handles tied to a Text widget, and the tied methods automatically insert the print statement's arguments into the Text widget.

For example:

 #!/usr/local/bin/perl -w
 use POSIX 'acos';
 use Tk;
 use strict;

 my $mw = MainWindow->new;
 my $text = $mw->Text(qw/-width 40 -height 10/)->pack;

 tie *STDOUT, ref $text, $text;

 print "Hello Text World!\n";
 printf "pi ~= %1.5f", acos(-1.0);

 MainLoop;

PERFORMANCE ISSUES

Text widgets should run efficiently under a variety of conditions. The text widget uses about 2-3 bytes of main memory for each byte of text, so texts containing a megabyte or more should be practical on most workstations. Text is represented internally with a modified B-tree structure that makes operations relatively efficient even with large texts. Tags are included in the B-tree structure in a way that allows tags to span large ranges or have many disjoint smaller ranges without loss of efficiency. Marks are also implemented in a way that allows large numbers of marks. In most cases it is fine to have large numbers of unique tags, or a tag that has many distinct ranges.

One performance problem can arise if you have hundreds or thousands of different tags that all have the following characteristics: the first and last ranges of each tag are near the beginning and end of the text, respectively, or a single tag range covers most of the text widget. The cost of adding and deleting tags like this is proportional to the number of other tags with the same properties. In contrast, there is no problem with having thousands of distinct tags if their overall ranges are localized and spread uniformly throughout the text.

Very long text lines can be expensive, especially if they have many marks and tags within them.

The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the -insertofftime option to 0 avoid this.

SEE ALSO

Tk::ROText Tk::TextUndo

KEYWORDS

text, widget


Tk::TextUndo - perl/tk text widget with bindings to undo changes.

    • Bindings
    • Methods
  • KEYS
  • SEE ALSO

NAME

Tk::TextUndo - perl/tk text widget with bindings to undo changes.

SYNOPSIS

use Tk::TextUndo;

$testundo = $parent->TextUndo(?-option=>value, ...?);

DESCRIPTION

This IS-A text widget with an unlimited 'undo' history but without a re'undo' capability.

Bindings

The TextUndo widget has the same bindings as the Text widget. In addition there are the following bindings:

Event <L4> <<Undo>>

undo the last change. Pressing <L4> several times undo step by step the changes made to the text widget.

Methods

The TextUndo widget has the same methods as Text widget. Additional methods for the TextUndo widget are:

$text->Load($filename);

Loads the contents of the $filename into the text widget. Load() delete the previous contents of the text widget as well as it's undo history of the previous file.

$text->Save(?$otherfilename?)

Save contents of the text widget to a file. If the $otherfilename is not specified, the text widget contents writes the file of $filename used in the last Load() call. If no file was previously Load()'ed an error message pops up. The default filename of the last Load() call is not overwriten by $otherfilename.

$text->FileName(?$otherfilename?)

If passed an argument sets the file name associated with the loaded document. Returns the current file name associated with the document.

KEYS

widget, text, undo

SEE ALSO

the Tk::Text manpage, the Tk::ROText manpage


Tk::Tiler - Scrollable frame with sub-widgets arranged into rows

NAME

Tk::Tiler - Scrollable frame with sub-widgets arranged into rows

SYNOPSIS

  use Tk::Tiler;

  my $tl = $parent->Scrolled('Tiler', -columns => n, -rows => n);

  my $a  = $tl->Xxxxx(...);
  my $b  = $tl->Xxxxx(...);
  my $c  = $tl->Xxxxx(...);

  $tl->Manage($a,$b,$c);

DESCRIPTION

Tiler is derived form Tk::Frame. It is a geometry managing widget which accepts widgets to manage. It places the widgets in a grid with as many widgets as possible in a row. All the "slots" in the grid are the same size, which is determined by the largest managed widget.

The grid may be scrolled vertically.


Tk::TixGrid - Create and manipulate Tix Grid widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • WIDGET METHODS
  • BINDINGS
  • SEE ALSO
  • BUGS
  • KEYWORDS

NAME

Tk::TixGrid - Create and manipulate Tix Grid widgets

SYNOPSIS

$tixgrid = $parent->TixGrid?(options)?;

DESCRIPTION

This widget is intended as the basis of "spread sheet" like interfaces. The widget displays its contents in a two dimensional "grid" of cells. Each cell may contain one Tix display item, which may be in text, graphics or other formats. See the Tk::DItem manpage for more information about Tix display items. Because these "items" need not be "windows" large grids can be handled without consuming excessive display system resources.

Individual cells, or groups of cells, can be formatted with a wide range of attributes, such as its color, relief and border. However because the widget is intended to handle large grids the mechanisms to achieve these are lower level, and more callback oriented than for other widgets. The assumption is that to avoid storing display details of a large number of cells, the data will be re-computed as needed.

The port of Tix C code and some of the bindings to perl/Tk is done but still need further work. In several places the intent of the Tix code is not yet understood. For example the 'edit' interface is clearly intended for spread-sheet like cell content editing in an auxillary "entry" widget or similar, but how that should work is not yet clear.

The TixGrid method creates a new TixGrid window and returns a blessed reference of this TixGrid widget. Additional options, described below, may be specified on the command line or in the option database to configure aspects of the TixGrid widget.

STANDARD OPTIONS

-background
 | -borderwidth
 | -cursor
 | -font
 | -foreground
 | -height
 | -highlightbackground
 | -highlightcolor
 | -highlightthickness
 | -padx
 | -pady
 | -relief
 | -selectbackground
 | -selectborderwidth
 | -selectforeground
 | -state
 | -takefocus
 | -width
 | -xscrollcommand
 | -yscrollcommand

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: browseCmd
Class: BrowseCmd
Switch: -browsecmd

If defined, gives a perl/Tk callback to be executed when the user browses a grid cell (This is normally the case when the user clicks on an entry). When this callback is called, it is passed with two additional parameters: x y, where (x,y) is the location of the cell that has just been clicked.

Name: Command
Class: Command
Switch: -command

If defined, gives a perl/Tk callback to be executed when the user double-clicks a grid cell. When this callback is called, it is passed with two additional parameters: x y, where (x,y) is the location of the cell that has just been clicked.

Name: editDoneCmd
Class: EditDoneCmd
Switch: -editdonecmd

If defined, gives a perl/Tk callback to be executed when the user has edited grid cell. When this callback is called, it is passed with two additional parameters: x y, where (x,y) is the location of the cell that has just been edited.

Name: editNotifyCmd
Class: EditNotifyCmd
Switch: -editnotifycmd

If defined gives a perl/Tk callback to be executed when the user tries to edit a grid cell. When this callback is called, it is passed with two additional parameters: x y, where (x,y,) is the location of the cell. This callback should return a boolean value: true indicates that the cell is editable and false otherwise.

Name: FloatingCols
Class: floatingCols
Switch: -floatingcols

Defines the number of extra columns beyond the existing grid that can be brought into view by scrolling.

Name: FloatingRows
Class: floatingRows
Switch: -floatingrows

Defines the number of extra rows beyond the the existing grid that can be brought into view by scrolling.

Name: formatCmd
Class: FormatCmd
Switch: -formatcmd

If defined, gives a perl/Tk callback to be executed when the grid cells need to be displayed on the screen. Its primary purpose is to draw the background of the region before the cells are rendered on top. This is normally achieved by calling formatGrid or formatBorder (see below). However other uses can be made of this low-level callback. For example it can be used to "lazily" populate the grid by calling the set method only as cells come into view.

When this callback is called, it is passed with five additional parameters: type x1 y1 x2 y2.

x1 y1 x2 y2 gives the extent of the region that needs formatting.

type gives the logical type of the region in the grid. It may be one of the following.

x_region

The horizontal margin.

y_region

The vertical margin.

s_region

The area in the top left corner where the horizontal and vertical margins are joined.

main

The main body i.e. all the cells that do not fall into the above three types.

Name: leftMargin
Class: LeftMargin
Switch: -leftmargin

Gives the width of vertical margin in cells (columns). A zero indicates that no vertical margin exists. A positive value N indicates that first N columns are "labels" and are always displayed and not scrolled.

Name: itemType
Class: ItemType
Switch: -itemtype

Default item type for cells.

Name: selectMode
Class: SelectMode
Switch: -selectmode

Specifies one of several styles for manipulating the selection. The value of the option may be arbitrary, but the default bindings expect it to be either single, browse, multiple, or extended; the default value is single.

Name: selectUnit
Class: SelectUnit
Switch: -selectunit

Specifies the selection unit. Valid values are cell, column or row.

Name: sizeCmd
Class: SizeCmd
Switch: -sizecmd

Callback is called (with no extra arguments) when grid sizes are re-computed. For example if window changes size, a different font is specified etc.

It is called just after scrollbars (if present) are updated.

Name: topMargin
Class: TopMargin
Switch: -topmargin

Gives the width of horizontal margin in cells (rows). A zero indicates that no horizontal margin exists. A positive value N indicates that first N rows are "labels" and are always displayed and not scrolled.

WIDGET METHODS

The TixGrid method creates a TixGrid widget and returns a blessed reference of this TixGrid widget. This reference may be used to invoke various operations on the widget. It has the following general form:

$tixgrid->method?(arg, arg, ...)?

args determine the exact behavior of the method.

This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are possible for TixGrid widgets:

$tixgrid->anchorGet(x, y)
$tixgrid->anchorSet(x, y)
$tixgrid->anchorClear

Manipulates the anchor cell of the TixGrid widget. The anchor cell is the end of the selection that is fixed while the user is dragging out a selection with the mouse.

($bd,$col,$row) = $tixgrid->bdtype(x,y ?,xDelta,yDelta?)

Determines if the the screen (pixel) position x,y is in a border. This is useful for changing the mouse cursor when the user points at a border - e.g. to indicate that the border can be adjusted interactively.

If in a border returns a list of three elements. First element is 'xy', 'x' or 'y', second two elements are integers. (Value of these are not understood, seem to indicate which column and row of the border the screen position corresponds to?)

If not in a border returns an empty list.

$tixgrid->delete(dim, from?, to?)
$tixgrid->deleteColumn(from?, to?)
$tixgrid->deleteRow(from?, to?)

Dim may be row or column. If to is not given, deletes a single row (or column) at the position from. If to is given, deletes the range of rows (or columns) from position from through to.

$tixgrid->dragsite(option, x, y)
$tixgrid->dropsite(option, x, y)

Tcl/Tix has (or was going to have) Drag&Drop support. Meaning for perl/Tk is not clear yet.

$tixgrid->editApply

If any cell is being edited, de-highlight the cell and applies the changes.

$tixgrid->editSet(x, y)

Highlights the cell at (x,y) for editing, if the -editnotify callback returns true for this cell.

$tixgrid->entrycget(x, y, '-option')
$tixgrid->entryconfigure(x, y?, -option??=>value, -option=>value, ...?)

Provide a configue interface to cells in the grid. The -options depend on the item type of the cell.

$tixgrid->formatBorder(x1,y1, x2,y2, options);
$tixgrid->formatGrid(x1,y1, x2,y2, options);

The formatBorder and formatBorder methods can only be called by the -formatcmd callback of the tixGrid widget. They draw the background of the region described by x1,y1, x2,y2 according the the supplied options. One call to -formatcmd callback can make multiple calls to formatBorder and/or formatBorder for different sub-regions.

formatBorder draws the background using Tk relief style, formatGrid also draws grid lines between the cells. It only makes sense to call one or the other for a particular sub-region as one will over-write the other.

The options allowed are:

-background / -bg
-borderwidth / -bd
-filled
-relief
-selectbackground
-xoff
-xon
-yoff
-yon

The -xon/-xoff and -yon/-yoff options are obscure. If anyone can figure out how to do something interesting given what pTk/tixGrFmt.c is doing with them please let Nick know!.

$tixgrid->geometryinfo(?width, height?)

Returns list of four values - two sets of two floating point numbers. First set is the scrollbar fractions for x direction, second set is scrollbar fractions for y direction. If width and height are specified then fractions are based on as if window size was of specified size (in pixels, but not allowing normal GetPixels units). Otherwise fractions are based on current size of the window.

Usage obscure.

$tixgrid->index(xcoord, ycoord)

Retuns (x, y) of entry at position ($coordx, $coordy). Either coordinate may be 'max' which is largest existing entry in that direction, 'end' which is one beyond largest existing entry, or a number. (This is how you find out how big the grid is.)

$tixgrid->infoBbox(x,y)

Return the pixel bounding box of the cell at x,y.

$tixgrid->infoExists(x,y)

Returns true if there is an item in the cell at x,y. Throws an exception (dies) if x,y is outside the grid - this may change (Nick doesn't like it).

$tixgrid->move(dim, from, to, offset)
$tixgrid->moveColumn(from, to, offset)
$tixgrid->moveRow(from, to, offset)

Dim may be row or column. Moves the range of rows (or columns) from position from through to by the distance indicated by offset. For example, $tixgrid->moveRow(2, 4, 1) moves the rows 2,3,4 to rows 3,4,5.

$tixgrid->nearest(x, y)

Screen pos (pixels) to entry (nx,ny) translation.

$tixgrid->selectionAdjust(x1, y1 ?,x2, y2?)
$tixgrid->selectionClear(x1, y1 ?,x2, y2?)
$tixgrid->selectionIncludes(x1, y1 ?,x2, y2?)
$tixgrid->selectionSet(x1, y1 ?,x2, y2?)
$tixgrid->selectionToggle(x1, y1 ?,x2, y2?)

Selection support methods - probably buggy.

x1 (y1) has not to be greater than x2 (y2), but only x2 and y2 can be 'max'.

BUG: selectionIncludes: has no visible effect (as in Tix). Eh???

BUG: selectionClear: only works for 0, 0, max, max (as in Tix). Eh???

When x2, y2 are not given they default to x1, y1, respectively.

$tixgrid->set(x, y?, -itemtype=>type??, -option=>value, ...?)

Creates a new display item at the cell at (x,y). The optional -itemtype parameter gives the type of the display item. An additional list of option-value pairs specify options of the display item. If a display item already exists at this cell, the old item will be deleted automatically.

$tixgrid->size(dim, index?, -option??=>value, ...?)
$tixgrid->sizeColumn(index?, -option??=>value, ...?)
$tixgrid->sizeRow(index?, -option??=>value, ...?)

Queries or sets the size of the row or column given by dim and index. Dim may be row or column. Index may be any non-negative integer that gives the position of a given row (or column). Index can also be the string default; in this case, this method queries or sets the default size of all rows (or columns). When no option-value pair is given, this method returns a list containing the current size setting of the given row (or column). When option-value pairs are given, the corresponding options of the size setting of the given row are changed. -option may be one of the following:

-pad0 => pixels

Specifies the paddings to the left of a column or the top of a row.

-pad1 => pixels

Specifies the paddings to the right of a column or the bottom of a row.

-size => val

Specifies the width of a column or the height of a row. Val may be: auto -- the width of the column is set the widest cell in the column; a valid Tk screen distance unit (see Tk_GetPixels); or a real number following by the word chars (e.g. 3.4chars) that sets the width of the column to the given number of characters.

$tixgrid->sort(dimension, start, end, ?args ...?)

?docu here? (not supported on Win* OSs up to now)

$tixgrid->unset(x, y)

Clears the cell at (x,y) by removing its display item.

$tixgrid->xview

Normal horizontal scrollbar method.

$tixgrid->yview

Normal vertical scrollbar method.

BINDINGS

To be done - only most obvious basic bindings work. The Tcl/Tix code was coded as a "state machine" which is not easy to follow.

SEE ALSO

Tk::DItem
Tk::callbacks
Tk::FloatEntry

BUGS

Tcl/Tix was/is not finished and both C code and bindings of TixGrid have some bugs.

KEYWORDS

tix, tixgrid, table, display item, spreadsheet


Tk::Toplevel - Create and manipulate Toplevel widgets

  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Toplevel - Create and manipulate Toplevel widgets

SYNOPSIS

$toplevel = $parent->Toplevel(?options?);

STANDARD OPTIONS

-borderwidth | -highlightbackground | -highlightthickness | -takefocus
-class | -highlightcolor | -relief
-cursor

See the Tk::options manpage for details of the standard options.

WIDGET-SPECIFIC OPTIONS

Name: background
Class: Background
Switch: -background

This option is the same as the standard background option except that its value may also be specified as an undefined value. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border.

Name: colormap
Class: Colormap
Switch: -colormap

Specifies a colormap to use for the window. The value may be either new, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as $widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the default colormap of its screen. This option may not be changed with the configure method.

Name: container
Class: Container
Switch: -container

The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the -use option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure method.

Name: height
Class: Height
Switch: -height

Specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

Name: menu
Class: Menu
Switch: -menu

Specifies a menu widget to be used as a menubar. On the Macintosh, the menubar will be displayed accross the top of the main monitor. On Microsoft Windows and all UNIX platforms, the menu will appear accross the toplevel window as part of the window dressing maintained by the window manager.

Name: ""
Class: ""
Switch: -screen

Specifies the screen on which to place the new window. Any valid screen name may be used, even one associated with a different display. Defaults to the same screen as its parent. This option is special in that it may not be specified via the option database, and it may not be modified with the configure method.

Switch: -title

Specifies the title of the toplevel window.

Name: use
Class: Use
Switch: -use

This option is used for embedding. If the value isn't an empty string, it must be the the window identifier of a container window, specified as a hexadecimal string like the ones returned by the winfo id command. The toplevel widget will be created as a child of the given container instead of the root window for the screen. If the container window is in a Tk application, it must be a frame or toplevel widget for which the -container option was specified. This option may not be changed with the configure method.

Name: visual
Class: Visual
Switch: -visual

Specifies visual information for the new window in any of the forms accepted by Tk_GetVisual. If this option is not specified, the new window will use the default visual for its screen. The visual option may not be modified with the configure method.

Name: width
Class: Width
Switch: -width

Specifies the desired width for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

DESCRIPTION

The Toplevel method creates a new toplevel widget (given by the $widget argument). Additional options, described above, may be specified on the command line or in the option database to configure aspects of the toplevel such as its background color and relief. The toplevel command returns the path name of the new window.

A toplevel is similar to a frame except that it is created as a top-level window: its X parent is the root window of a screen rather than the logical parent from its path name. The primary purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only visible features of a toplevel are its background color and an optional 3-D border to make the toplevel appear raised or sunken.

WIDGET METHODS

The Toplevel method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class, and the Tk::Wm class.

BINDINGS

When a new toplevel is created, it has no default event bindings: toplevels are not intended to be interactive.

SEE ALSO

Tk::Widget Tk::Wm

KEYWORDS

toplevel, widget


Tk::Trace - emulate Tcl/Tk B<trace> functions.

  • METHODS
  • EXAMPLES
  • HISTORY
  • COPYRIGHT

NAME

Tk::Trace - emulate Tcl/Tk trace functions.

SYNOPSIS

 use Tk::Trace
 $mw->traceVariable(\$v, 'wru' => [\&update_meter, $scale]);
 %vinfo = $mw->traceVinfo(\$v);
 print "Trace info  :\n  ", join("\n  ", @{$vinfo{-legible}}), "\n";
 $mw->traceVdelete(\$v);

DESCRIPTION

This class module emulates the Tcl/Tk trace family of commands by binding subroutines of your devising to Perl variables using simple Tie::Watch features.

Callback format is patterned after the Perl/Tk scheme: supply either a code reference, or, supply an array reference and pass the callback code reference in the first element of the array, followed by callback arguments.

User callbacks are passed these arguments:

 $_[0]        = undef for a scalar, index/key for array/hash
 $_[1]        = variable's current (read), new (write), final (undef) value
 $_[2]        = operation (r, w, or u)
 $_[3 .. $#_] = optional user callback arguments

As a Trace user, you have an important responsibility when writing your callback, since you control the final value assigned to the variable. A typical callback might look like:

 sub callback {
    my($index, $value, $op, @args) = @_;
    return if $op eq 'u';
    # .... code which uses $value ...
    return $value;     # variable's final value
 }

Note that the callback's return value becomes the variable's final value, for either read or write traces.

For write operations, the variable is updated with its new value before the callback is invoked.

Multiple read, write and undef callbacks can be attached to a variable, which are invoked in reverse order of creation.

METHODS

$mw->traceVariable(varRef, op => callback);

varRef is a reference to the scalar, array or hash variable you wish to trace. op is the trace operation, and can be any combination of r for read, w for write, and u for undef. callback is a standard Perl/Tk callback, and is invoked, depending upon the value of op, whenever the variable is read, written, or destroyed.

%vinfo = $mw->traceVinfo(varRef);

Returns a hash detailing the internals of the Trace object, with these keys:

 %vinfo = (
     -variable =>  varRef
     -debug    =>  '0'
     -shadow   =>  '1'
     -value    =>  'HELLO SCALAR'
     -destroy  =>  callback
     -fetch    =>  callback
     -store    =>  callback
     -legible  =>  above data formatted as a list of string, for printing
 );

For array and hash Trace objects, the -value key is replaced with a -ptr key which is a reference to the parallel array or hash. Additionally, for an array or hash, there are key/value pairs for all the variable specific callbacks.

$mw->traceVdelete(\$v);

Stop tracing the variable.

EXAMPLES

 # Trace a Scale's variable and move a meter in unison.

 use Tk;
 use Tk::widgets qw/Trace/;

 $pi = 3.1415926;
 $mw = MainWindow->new;
 $c = $mw->Canvas( qw/-width 200 -height 110 -bd 2 -relief sunken/ )->grid;
 $c->createLine( qw/100 100 10 100 -tag meter -arrow last -width 5/ );
 $s = $mw->Scale( qw/-orient h -from 0 -to 100 -variable/ => \$v )->grid;
 $mw->Label( -text => 'Slide Me for 5 Seconds' )->grid;

 $mw->traceVariable( \$v, 'w' => [ \&update_meter, $s ] );

 $mw->after( 5000 => sub {
     print "Untrace time ...\n";
     %vinfo = $s->traceVinfo( \$v );
     print "Watch info  :\n  ", join("\n  ", @{$vinfo{-legible}}), "\n";
     $c->traceVdelete( \$v );
 });

 MainLoop;

 sub update_meter {
     my( $index, $value, $op, @args ) = @_;
     return if $op eq 'u';
     $min = $s->cget( -from );
     $max = $s->cget( -to );
     $pos = $value / abs( $max - $min );
     $x = 100.0 - 90.0 * ( cos( $pos * $pi ) );
     $y = 100.0 - 90.0 * ( sin( $pos * $pi ) );
     $c->coords( qw/meter 100 100/, $x, $y );
     return $value;
 }

 # Predictive text entry.

 use Tk;
 use Tk::widgets qw/ LabEntry Trace /;
 use strict;

 my @words =  qw/radio television telephone turntable microphone/;

 my $mw = MainWindow->new;

 my $e = $mw->LabEntry(
     qw/ -label Thing -width 40 /,
     -labelPack    => [ qw/ -side left / ],
     -textvariable => \my $thing,
 );
 my $t = $mw->Text( qw/ -height 10 -width 50 / );;

 $t->pack( $e, qw/ -side top / );

 $e->focus;
 $e->traceVariable( \$thing, 'w', [ \&trace_thing, $e, $t ] );

 foreach my $k ( 1 .. 12 ) {
     $e->bind( "<F${k}>" => [ \&ins, $t, Ev('K') ] );
 }
 $e->bind( '<Return>' =>
           sub {
               print "$thing\n";
               $_[0]->delete( 0, 'end' );
           }
 );

 MainLoop;

 sub trace_thing {

     my( $index, $value, $op, $e, $t ) = @_;

     return unless $value;

     $t->delete( qw/ 1.0 end / );
     foreach my $w ( @words ) {
         if ( $w =~ /^$value/ ) {
             $t->insert( 'end', "$w\n" );
         }
     }

     return $value;

 } # end trace_thing
 sub ins {

     my( $e, $t, $K ) = @_;

     my( $index ) = $K =~ /^F(\d+)$/;

     $e->delete( 0, 'end' );
     $e->insert( 'end', $t->get( "$index.0", "$index.0 lineend" ) );
     $t->delete( qw/ 1.0 end / );

 } # end ins

HISTORY

 Stephen.O.Lidie@Lehigh.EDU, Lehigh University Computing Center, 2000/08/01
 . Version 1.0, for Tk800.022.
 sol0@Lehigh.EDU, Lehigh University Computing Center, 2003/09/22
 . Version 1.1, for Tk804.025, add support for multiple traces of the same
   type on the same variable.

COPYRIGHT

Copyright (C) 2000 - 2003 Stephen O. Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Tk::Tree - Create and manipulate Tree widgets

  • SUPER-CLASS
  • STANDARD OPTIONS
  • WIDGET-SPECIFIC OPTIONS
  • DESCRIPTION
  • WIDGET METHODS
  • BINDINGS
  • SEE ALSO
  • AUTHOR
  • ACKNOWLEDGEMENTS

NAME

Tk::Tree - Create and manipulate Tree widgets

SYNOPSIS

use Tk::Tree;

$tree = $parent->Tree(?options?);

SUPER-CLASS

The Tree class is derived from the HList class and inherits all the methods, options and subwidgets of its super-class. A Tree widget is not scrolled by default.

STANDARD OPTIONS

Tree supports all the standard options of an HList widget. See the Tk::options manpage for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name: browseCmd
Class: BrowseCmd
Switch: -browsecmd

Specifies a callback to call whenever the user browses on an entry (usually by single-clicking on the entry). The callback is called with one argument, the pathname of the entry.

Name: closeCmd
Class: CloseCmd
Switch: -closecmd

Specifies a callback to call whenever an entry needs to be closed (See BINDINGS below). This method is called with one argument, the pathname of the entry. This method should perform appropriate actions to close the specified entry. If the -closecmd option is not specified, the default closing action is to hide all child entries of the specified entry.

Name: command
Class: Command
Switch: -command

Specifies a callback to call whenever the user activates an entry (usually by double-clicking on the entry). The callback is called with one argument, the pathname of the entry.

Name: ignoreInvoke
Class: IgnoreInvoke
Switch: -ignoreinvoke

A Boolean value that specifies when a branch should be opened or closed. A branch will always be opened or closed when the user presses the (+) and (-) indicators. However, when the user invokes a branch (by doublc-clicking or pressing <Return>), the branch will be opened or closed only if -ignoreinvoke is set to false (the default setting).

Name: openCmd
Class: OpenCmd
Switch: -opencmd

Specifies a callback to call whenever an entry needs to be opened (See BINDINGS below). This method is called with one argument, the pathname of the entry. This method should perform appropriate actions to open the specified entry. If the -opencmd option is not specified, the default opening action is to show all the child entries of the specified entry.

DESCRIPTION

The Tree method creates a new window and makes it into a Tree widget and return a reference to it. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the Tree widget such as its cursor and relief.

The Tree widget can be used to display hierarchical data in a tree form. The user can adjust the view of the tree by opening or closing parts of the tree.

To display a static tree structure, you can add the entries into the Tree widget and hide any entries as desired. Then you can call the autosetmode method. This will set up the Tree widget so that it handles all the open and close events automatically. the demonstration program Tixish/examples/perl-tix-tree).

The above method is not applicable if you want to maintain a dynamic tree structure, i.e, you do not know all the entries in the tree and you need to add or delete entries subsequently. To do this, you should first create the entries in the Tree widget. Then, use the setmode method to indicate the entries that can be opened or closed, and use the -opencmd and -closecmd options to handle the opening and closing events. (Please see the demonstration program Tixish/examples/perl-tix-dyntree).

Use either

$parent->Scrolled('Tree', ... );

or

$parent->ScrlTree( ... );

to create a scrolled Tree. See the Tk::Scrolled manpage for details.

WIDGET METHODS

The Tree method creates a widget object. This object supports the configure and cget methods described in the Tk::options manpage which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

The following additional methods are available for Tree widgets:

$tree->autosetmode

This method calls the setmode method for all the entries in this Tree widget: if an entry has no child entries, its mode is set to none. Otherwise, if the entry has any hidden child entries, its mode is set to open; otherwise its mode is set to close.

$tree->close(entryPath)

Close the entry given by entryPath if its mode is close.

$tree->getmode(entryPath)

Returns the current mode of the entry given by entryPath.

$tree->open(entryPath)

Open the entry given by entryPath if its mode is open.

$tree->setmode(entryPath, mode)

This method is used to indicate whether the entry given by entryPath has children entries and whether the children are visible. mode must be one of open, close or none. If mode is set to open, a (+) indicator is drawn next the the entry. If mode is set to close, a (-) indicator is drawn next the the entry. If mode is set to none, no indicators will be drawn for this entry. The default mode is none. The open mode indicates the entry has hidden children and this entry can be opened by the user. The close mode indicates that all the children of the entry are now visible and the entry can be closed by the user.

BINDINGS

The basic mouse and keyboard bindings of the Tree widget are the same as the bindings of the HList widget. In addition, the entries can be opened or closed under the following conditions:

[1]

If the mode of the entry is open, it can be opened by clicking on its (+) indicator.

[2]

If the mode of the entry is close, it can be closed by clicking on its (-) indicator.

SEE ALSO

Tk::HList

AUTHOR

Perl/TK version by Chris Dean <ctdean@cogit.com>. Original Tcl/Tix version by Ioi Kim Lam.

ACKNOWLEDGEMENTS

Thanks to Achim Bohnet <ach@mpe.mpg.de> for all his help.


Perl/Tk - Writing Tk applications in Perl 5

  • Some Background
  • First Requirements
  • Widget creation
  • Standard Tk widgets
  • Variables and callback routines
  • The packer - grouping with Frame widgets
  • More than one window
  • More callbacks
  • Canvases and tags

NAME

Perl/Tk - Writing Tk applications in Perl 5

DESCRIPTION

This document is for beginners. It assumes you know some Perl, and have it and Tk running. If you are not currently reading this document courtesy of the widget demonstration program, please be sure to run widget, as it will show you the various widget types supported by Tk and how to use them. widget should be installed in your default path, so type widget at a command prompt.

Here are links to other novice tutorials:

http://www.lehigh.edu/~sol0/ptk/tpj1.html http://www.lehigh.edu/~sol0/ptk/perlmonth01/pm1.html

Mastering Perl/Tk is the definitive book on Perl/Tk:

http://www.oreilly.com/catalog/mastperltk

Some Background

Tk GUI programming is event-driven. (This may already be familiar to you.) In event-driven programs, the main GUI loop is outside of the user program and inside the GUI library. This loop - initiated by calling MainLoop - watches all events of interest and activates the correct handler procedures to handle these events. Some of these handler procedures may be user-supplied; others will be part of the library.

For a programmer, this means that you're not watching what is happening; instead, you are requested by the toolkit to perform actions whenever necessary. So, you're not watching for 'raise window / close window / redraw window' requests, but you tell the toolkit which routine will handle such cases, and the toolkit will call the procedures when required. These procedures are known as callbacks, and some of them you write yourself.

First Requirements

Perl programs that use Tk need to include use Tk. A program should also use use strict and the -w switch to ensure the program is working without common errors.

Any Perl/Tk application starts by creating the Tk MainWindow. You then create items inside the MainWindow, and/or create new windows called Toplevels that also contain child items, before starting the MainLoop, which is the last logical statment in your program. You can also create more items and windows while you're running, using callbacks. Items are only shown on the display after they have been arranged by a geometry manager like pack; more information on this later. MainLoop starts the GUI and handle all events. That's all there is to it!. A trivial one-window example is shown below:

    #!/usr/bin/perl -w
    use Tk;
    use strict;

    my $mw = MainWindow->new;
    $mw->Label(-text => 'Hello, world!')->pack;
    $mw->Button(
        -text    => 'Quit',
        -command => sub { exit },
    )->pack;
    MainLoop;

Please run this example. It shows you two widget types, a Label and a Button, and how they are packed. When clicked, the <Button> widget invokes the callback specified by the -command option. Finally, note the typical Tk style using -option => value pairs.

Widget creation

Tk windows and widgets are hierarchical, i.e. one window includes one or more other windows. You create the first Tk window using MainWindow->new. This returns a window handle, assigned to $mw in the example above. Keep track of the main handle, commonly called a widget reference.

You can use any Tk handle to create child widgets within the window (or widget). This is done by calling the Tk constructor method on the variable. In the example above, the Label method called from $mw creates a Label widget inside the MainWindow. In the constructor call, you can specify various options; you can later add or change options for any widget using the configure method, which takes the same parameters as the constructor. The one exception to the hierarchical structure is the Toplevel constructor, which creates a new outermost window.

After you create any widget (other than the MainWindow or Toplevels, you must render it by calling pack. (This is not entirely true; more later). If you do not need to refer to the widget after construction and packing, call pack off the constructor results, as shown for the Label and utton in the example above. Note that the result of the compound call is the result of pack, which is a valid Tk handle.

Windows and widgets are deleted by calling destroy on them; this will delete and un-draw the widget and all its children.

Standard Tk widgets

Here is an itemize of the standard Tk widget set.

Button
Canvas
Checkbutton
Entry
Frame
Label
Labelframe
Listbox
Menu
Menubutton
Message
Panedwindow
Radiobutton
Scale
Scrollbar
Spinbox
Text
Toplevel

Perl/Tk provides an equal number of new widgets, above and beyond this core set.

Adjuster
Ballon
BrowseEntry
ColorEditor
DirTree
ErrorDialog
FileSelect
HList
LabEntry
LabFrame
NoteBook
Optionmenu
Pane
ProgressBar
ROText
Table
TextUndo
Tiler
TList
Tree

Variables and callback routines

Most graphical interfaces are used to set up a set of values and conditions, and then perform the appropriate action. The Tk toolkit is different from your average text-based prompting or menu driven system in that you do not collect settings yourself, and decide on an action based on an input code; instead, you leave these values to your toolkit and only get them when the action is performed.

So, where a traditional text-based system would look like this:

    #!/usr/bin/perl -w
    use strict;

    print "Please type a font name\n";
    my $font = <>; chomp $font;
    # Validate font

    print "Please type a file name\n";
    my $filename = <>; chomp $filename;
    # Validate filename

    print "Type <1> to fax, <2> to print\n";
    my $option = <>; chomp $option;
    if ($option eq 1) {
        print "Faxing $filename in font $font\n";
    } elsif ($option eq 2) {
        print "Now sending $filename to printer in font $font\n";
    }

The slightly larger example below shows how to do this in Tk. Note the use of callbacks. Note, also, that Tk handles the values, and the subroutine uses the method get to get at the values. If a user changes his mind and wants to change the font again, the application never notices; it's all handled by Tk.

    #!/usr/bin/perl -w
    use Tk;
    use strict;

    my $mw = MainWindow->new;

    $mw->Label(-text => 'File Name')->pack;
    my $filename = $mw->Entry(-width => 20);
    $filename->pack;

    $mw->Label(-text => 'Font Name')->pack;
    my $font = $mw->Entry(-width => 10);
    $font->pack;

    $mw->Button(
        -text => 'Fax',
        -command => sub{do_fax($filename, $font)}
    )->pack;

    $mw->Button(
        -text => 'Print',
        -command => sub{do_print($filename, $font)}
    )->pack;

    MainLoop;

    sub do_fax {
        my ($file, $font) = @_;
        my $file_val = $file->get;
        my $font_val = $font->get;
        print "Now faxing $file_val in font $font_val\n";
    }

    sub do_print {
        my ($file, $font) = @_;
        my $file_val = $file->get;
        my $font_val = $font->get;
        print "Sending file $file_val to printer in font $font_val\n";
    }

The packer - grouping with Frame widgets

In the examples above, you must have noticed the pack calls. This is one of the more complicated parts of Tk. The basic idea is that any window or widget should be subject to a Tk geometry manager; the packer is one of the placement managers, and Bgrid> is another.

The actions of the packer are rather simple: when applied to a widget, the packer positions that widget on the indicated position within the remaining space in its parent. By default, the position is on top; this means the next items will be put below. You can also specify the left, right, or bottom positions. Specify position using -side => 'right'.

Additional packing parameters specify the behavior of the widget when there is some space left in the Frame or when the window size is increased. If widgets should maintain a fixed size, specify nothing; this is the default. For widgets that you want to fill up the current horizontal and/or vertical space, specify -fill => 'x', y, or both; for widgets that should grow, specify -expand => 1. These parameters are not shown in the example below; see the widget demonstration.

If you want to group some items within a window that have a different packing order than others, you can include them in a Frame. This is a do-nothing window type that is meant for packing or filling (and to play games with borders and colors).

The example below shows the use of pack and Frames:

    #!/usr/bin/perl -w
    use Tk;
    use strict;

    # Take top and the bottom - now implicit top is in the middle
    my $mw = MainWindow->new;
    $mw->title( 'The MainWindow' );
    $mw->Label(-text => 'At the top (default)')->pack;
    $mw->Label(-text => 'At the bottom')->pack(-side => 'bottom');
    $mw->Label(-text => 'The middle remains')->pack;

    # Since left and right are taken, bottom will not work...
    my $top1 = $mw->Toplevel;
    $top1->title( 'Toplevel 1' );
    $top1->Label(-text => 'Left')->pack(-side => 'left');
    $top1->Label(-text => 'Right')->pack(-side => 'right');
    $top1->Label(-text => '?Bottom?')->pack(-side => 'bottom');

    # But when you use Frames, things work quite alright
    my $top2 = $mw->Toplevel;
    $top2->title( 'Toplevel 2' );
    my $frame = $top2->Frame;
    $frame->pack;
    $frame->Label(-text => 'Left2')->pack(-side => 'left');
    $frame->Label(-text => 'Right2')->pack(-side => 'right');
    $top2->Label(-text => 'Bottom2')->pack(-side => 'bottom');

    MainLoop;

More than one window

Most real applications require more than one window. As you just saw, you can create more outermost windows by using a Toplevel widget. Each window is independent; destroying a Toplevel window does not affect the others as long as they are not a child of the closed Toplevel. However, exiting the MainWindow will destroy all remaining Toplevel widgets and end the application. The example below shows a trivial three-window application:

    #!/usr/bin/perl -w
    use Tk;
    use strict;

    my $mw = MainWindow->new;
    fill_window($mw, 'Main');
    my $top1 = $mw->Toplevel;
    fill_window($top1, 'First top-level');
    my $top2 = $mw->Toplevel;
    fill_window($top2, 'Second top-level');
    MainLoop;

    sub fill_window {
        my ($window, $header) = @_;
        $window->Label(-text => $header)->pack;
        $window->Button(
            -text    => 'close',
            -command => [$window => 'destroy']
        )->pack(-side => 'left');
        $window->Button(
            -text    => 'exit',
            -command => [$mw => 'destroy']
        )->pack(-side => 'right');
    }

More callbacks

So far, all callback routines shown called a user procedure. You can also have a callback routine call another Tk routine. This is the way that scroll bars are implemented: scroll-bars can call a Tk item or a user procedure, whenever their position has changed. The Tk item that has a scrollbar attached calls the scrollbar when its size or offset has changed. In this way, the items are linked. You can still ask a scrollbar's position, or set it by hand - but the defaults will be taken care of.

The example below shows a listbox with a scroll bar. Moving the scrollbar moves the listbox. Scanning a listbox (dragging an item with the left mouse button) moves the scrollbar.

     #!/usr/bin/perl -w
     use Tk;
     use strict;

     my $mw = MainWindow->new;
     my $box = $mw->Listbox(
         -relief => 'sunken',
         -height  => 5,
         -setgrid => 1,
         );
         my @items = qw(One Two Three Four Five Six Seven
                   Eight Nine Ten Eleven Twelve);
         foreach (@items) {
       $box->insert('end', $_);
         }
         my $scroll = $mw->Scrollbar(-command => ['yview', $box]);
         $box->configure(-yscrollcommand => ['set', $scroll]);
         $box->pack(-side => 'left', -fill => 'both', -expand => 1);
         $scroll->pack(-side => 'right', -fill => 'y');

    MainLoop;

Canvases and tags

One of the most powerful widgets in Tk is the Canvas window. In a <Canvas> window, you can draw simple graphics and include other widgets. The <Canvas> area may be larger than the visible window, and may then be scrolled. Any item you draw on the canvas has its own id, and may optionally have one or more tags. You may refer to any item by its id, and may refer to any group of items by a common tag; you can move, delete, or change groups of items using these tags, and you can bind actions to tags. For a properly designed (often structured) Canvas, you can specify powerful actions quite simply.

In the example below, actions are bound to circles (single click) and blue items (double-click); obviously, this can be extended to any tag or group of tags.

    #!/usr/bin/perl -w
    use Tk;
    use strict;

    # Create B<MainWindow> and canvas
    my $mw = MainWindow->new;
    my $canvas = $mw->Canvas;
    $canvas->pack(-expand => 1, -fill => 'both');

    # Create various items
    create_item($canvas, 1, 1, 'circle', 'blue', 'Jane');
    create_item($canvas, 4, 4, 'circle', 'red', 'Peter');
    create_item($canvas, 4, 1, 'square', 'blue', 'James');
    create_item($canvas, 1, 4, 'square', 'red', 'Patricia');

    # Single-clicking with left on a 'circle' item invokes a procedure
    $canvas->bind('circle', '<1>' => sub {handle_circle($canvas)});
    # Double-clicking with left on a 'blue' item invokes a procedure
    $canvas->bind('blue', '<Double-1>' => sub {handle_blue($canvas)});
    MainLoop;

    # Create an item; use parameters as tags (this is not a default!)
    sub create_item {
        my ($can, $x, $y, $form, $color, $name) = @_;

        my $x2 = $x + 1;
        my $y2 = $y + 1;
        my $kind;
        $kind = 'oval' if ($form eq 'circle');
        $kind = 'rectangle' if ($form eq 'square');
        $can->create(
            ($kind, "$x" . 'c', "$y" . 'c',
            "$x2" . 'c', "$y2" . 'c'),
            -tags => [$form, $color, $name],
            -fill => $color);
            }

    # This gets the real name (not current, blue/red, square/circle)
    # Note: you'll want to return a list in realistic situations...
    sub get_name {
        my ($can) = @_;
        my $item = $can->find('withtag', 'current');
        my @taglist = $can->gettags($item);
        my $name;
        foreach (@taglist) {
            next if ($_ eq 'current');
            next if ($_ eq 'red' or $_ eq 'blue');
            next if ($_ eq 'square' or $_ eq 'circle');
            $name = $_;
            last;
        }
        return $name;
    }

    sub handle_circle {
        my ($can) = @_;
        my $name = get_name($can);
        print "Action on circle $name...\n";
    }

    sub handle_blue {
        my ($can) = @_;
        my $name = get_name($can);
        print "Action on blue item $name...\n";
    }


Tk::Widget - Base class of all widgets

  • CAVEATS
  • KEYWORDS

NAME

Tk::Widget - Base class of all widgets

SYNOPSIS

   package Tk::Whatever;
   require Tk::Widget;
   @ISA = qw(Tk::Widget);
   Construct Tk::Widget 'Whatever';

   sub Tk_cmd { \&Tk::whatever }

$widget->method(?arg, arg, ...?)

DESCRIPTION

The Tk::Widget is an abstract base class for all Tk widgets.

Generic methods available to all widgets include the methods based on core winfo mechanism and are used to retrieve information about windows managed by Tk. They can take any of a number of different forms, depending on the method. The legal forms are:

$widget->appname?(newName)?

If newName isn't specified, this method returns the name of the application (the name that may be used in send commands to communicate with the application). If newName is specified, then the name of the application is changed to newName. If the given name is already in use, then a suffix of the form `` #2'' or `` #3'' is appended in order to make the name unique. The method's result is the name actually chosen. newName should not start with a capital letter. This will interfere with option processing, since names starting with capitals are assumed to be classes; as a result, Tk may not be able to find some options for the application. If sends have been disabled by deleting the send command, this command will reenable them and recreate the send command.

$widget->atom(name)

Returns a decimal string giving the integer identifier for the atom whose name is name. If no atom exists with the name name then a new one is created.

$widget->atomname(id)

Returns the textual name for the atom whose integer identifier is id. This command is the inverse of the $widget->atom command. It generates an error if no such atom exists.

$widget->bell( ?-nice? );

This command rings the bell on the display for $widget and returns an empty string. The command uses the current bell-related settings for the display, which may be modified with programs such as xset.

If -nice is not specified, this command also resets the screen saver for the screen. Some screen savers will ignore this, but others will reset so that the screen becomes visible again.

$widget->bindDump

This command returns a list of strings suitable for printing detailing binding information for a widget. It prints a widget's bindtags. For each binding tag it prints all the bindings, comprised of the event descriptor and the callback. Callback arguments are printed, and Tk::Ev objects are expanded.

$widget->Busy?(?-recurse => 1?-option = value>?)?

This method configures a -cursor option for $widget and (if -recurse = 1> is specified) all its descendants. The cursor to be set may be passed as -cursor = cursor> or defaults to 'watch'. Additional configure options are applied to $widget only. It also adds a special tag 'Busy' to the bindtags of the widgets so configured so that KeyPress, KeyRelease, ButtonPress and ButtonRelease events are ignored (with press events generating a call to bell). It then acquires a local grab for $widget. The state of the widgets and the grab is restored by a call to $widget->Unbusy.

$widget->caret( ?-x x?, ?-y y?, ?-height height? );

Sets and queries the caret location for the display of the specified Tk window window. The caret is the per-display cursor location used for indicating global focus (e.g. to comply with Microsoft Accessibility guidelines), as well as for location of the over-the-spot XIM (X Input Methods) or Windows IME windows. If no options are specified, the last values used for setting the caret are return in option-value pair format. -x and -y represent window-relative coordinates, and -height is the height of the current cursor location, or the height of the specified window if none is given.

$widget->cells

Returns a decimal string giving the number of cells in the color map for $widget.

$widget->children

$widget->children Returns a list containing all the children of $widget. The list is in stacking order, with the lowest window first. Top-level windows are returned as children of their logical parents.

$widget->class

Returns the class name for $widget.

$widget->colormapfull

Returns 1 if the colormap for $widget is known to be full, 0 otherwise. The colormap for a window is ``known'' to be full if the last attempt to allocate a new color on that window failed and this application hasn't freed any colors in the colormap since the failed allocation.

$widget->ConfigSpecs

Used to perform delegated option configuration for a mega-widget. Returns, in Tk::Derived::ConfigSpecs notation (see the Tk::ConfigSpecs manpage), all possible options for a widget. For example,

 $s = $self->Scale;
 $self->ConfigSpecs(
     $s->ConfigSpecs,
     .... more ConfigSpecs specifications
 );

returns a hash of all Tk::Scale options, delegated to $s - e.g. some representative examples:

 -bigincrement => [$s, bigIncrement, BigIncrement, 0, 0]
 -digits       => [$s, digits, Digits, 0, 0]
 -sliderlength => [$s, sliderLength, SliderLength, 10m, 30]
 -troughcolor  => [$s, troughColor, Background, #c3c3c3, #c3c3c3]

This provides an easy means of populating a mega-widget's ConfigSpecs with initializers.

$widget->containing(rootX,rootY)

Returns the window containing the point given by rootX and rootY. RootX and rootY are specified in screen units (i.e. any form acceptable to Tk_GetPixels) in the coordinate system of the root window (if a virtual-root window manager is in use then the coordinate system of the virtual root window is used). If no window in this application contains the point then an empty string is returned. In selecting the containing window, children are given higher priority than parents and among siblings the highest one in the stacking order is chosen.

$widget->depth

Returns a decimal string giving the depth of $widget (number of bits per pixel).

$widget->destroy

This command deletes the window related to $widget, plus all its descendants. If all the MainWindows are deleted then the entire application will be destroyed.

The perl object $widget continues to exist while references to it still exist, e.g. until variable goes out of scope. However any attempt to use Tk methods on the object will fail. Exists($widget) will return false on such objects.

Note however that while a window exists for $widget the perl object is maintained (due to "references" in perl/Tk internals) even though original variables may have gone out of scope. (Normally this is intuitive.)

Exists($widget)

Returns 1 if there exists a window for $widget, 0 if no such window exists.

$widget->font(option?, arg, arg, ...?)

Create and inspect fonts. See the Tk::Font manpage for further details.

$widget->fpixels(number)

Returns a floating-point value giving the number of pixels in $widget corresponding to the distance given by number. Number may be specified in any of the forms acceptable to Tk_GetScreenMM, such as ``2.0c'' or ``1i''. The return value may be fractional; for an integer value, use $widget->pixels.

$widget->Getimage(name)

Given name, look for an image file with that base name and return a the Tk::Image manpage. File extensions are tried in this order: xpm, gif, ppm, xbm until a valid iamge is found. If no image is found, try a builtin image with that name.

$widget->geometry

Returns the geometry for $widget, in the form width x height+x+y. All dimensions are in pixels.

$widget->height

Returns a decimal string giving $widget's height in pixels. When a window is first created its height will be 1 pixel; the height will eventually be changed by a geometry manager to fulfill the window's needs. If you need the true height immediately after creating a widget, invoke update to force the geometry manager to arrange it, or use $widget->reqheight to get the window's requested height instead of its actual height.

$widget->id

Returns a hexadecimal string giving a low-level platform-specific identifier for $widget. On Unix platforms, this is the X window identifier. Under Windows, this is the Windows HWND. On the Macintosh the value has no meaning outside Tk.

$widget->idletasks

One of two methods which are used to bring the application ``up to date'' by entering the event loop repeated until all pending events (including idle callbacks) have been processed.

If the idletasks method is specified, then no new events or errors are processed; only idle callbacks are invoked. This causes operations that are normally deferred, such as display updates and window layout calculations, to be performed immediately.

The idletasks command is useful in scripts where changes have been made to the application's state and you want those changes to appear on the display immediately, rather than waiting for the script to complete. Most display updates are performed as idle callbacks, so idletasks will cause them to run. However, there are some kinds of updates that only happen in response to events, such as those triggered by window size changes; these updates will not occur in idletasks.

$widget->interps

Returns a list whose members are the names of all Tcl interpreters (e.g. all Tk-based applications) currently registered for a particular display. The return value refers to the display of $widget.

$widget->ismapped

Returns 1 if $widget is currently mapped, 0 otherwise.

$widget->lower(?belowThis?)

If the belowThis argument is omitted then the command lowers $widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings that overlap it and will not obscure any siblings). If belowThis is specified then it must be the path name of a window that is either a sibling of $widget or the descendant of a sibling of $widget. In this case the lower command will insert $widget into the stacking order just below belowThis (or the ancestor of belowThis that is a sibling of $widget); this could end up either raising or lowering $widget.

$widget->MapWindow

Cause $widget to be "mapped" i.e. made visible on the display. May confuse the geometry manager (pack, grid, place, ...) that thinks it is managing the widget.

$widget->manager

Returns the name of the geometry manager currently responsible for $widget, or an empty string if $widget isn't managed by any geometry manager. The name is usually the name of the method for the geometry manager, such as pack or place. If the geometry manager is a widget, such as canvases or text, the name is the widget's class command, such as canvas.

$widget->name

Returns $widget's name (i.e. its name within its parent, as opposed to its full path name). The command $mainwin->name will return the name of the application.

$widget->OnDestroy(callback);

OnDestroy accepts a standard perl/Tk callback. When the window associated with $widget is destroyed then the callback is invoked. Unlike $widget->bind('<Destroy>',...) the widgets methods are still available when callback is executed, so (for example) a Text widget can save its contents to a file.

OnDestroy was required for new after mechanism.

$widget->parent

Returns $widget's parent, or an empty string if $widget is the main window of the application.

$widget->PathName

Returns the tk path name of $widget. (This is an import from the C interface.)

$widget->pathname(id)

Returns an object whose X identifier is id. The identifier is looked up on the display of $widget. Id must be a decimal, hexadecimal, or octal integer and must correspond to a window in the invoking application, or an error occurs which can be trapped with eval { } or Tk::catch { }. If the window belongs to the application, but is not an object (for example wrapper windows, HList header, etc.) then undef is returned.

$widget->pixels(number)

Returns the number of pixels in $widget corresponding to the distance given by number. Number may be specified in any of the forms acceptable to Tk_GetPixels, such as ``2.0c'' or ``1i''. The result is rounded to the nearest integer value; for a fractional result, use $widget->fpixels.

$widget->pointerx

If the mouse pointer is on the same screen as $widget, returns the pointer's x coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer isn't on the same screen as $widget then -1 is returned.

$widget->pointerxy

If the mouse pointer is on the same screen as $widget, returns a list with two elements, which are the pointer's x and y coordinates measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer isn't on the same screen as $widget then both of the returned coordinates are -1.

$widget->pointery

If the mouse pointer is on the same screen as $widget, returns the pointer's y coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is computed in the virtual root. If the mouse pointer isn't on the same screen as $widget then -1 is returned.

$widget->raise(?aboveThis?)

If the aboveThis argument is omitted then the command raises $widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If aboveThis is specified then it must be the path name of a window that is either a sibling of $widget or the descendant of a sibling of $widget. In this case the raise command will insert $widget into the stacking order just above aboveThis (or the ancestor of aboveThis that is a sibling of $widget); this could end up either raising or lowering $widget.

$widget->reqheight

Returns a decimal string giving $widget's requested height, in pixels. This is the value used by $widget's geometry manager to compute its geometry.

$widget->reqwidth

Returns a decimal string giving $widget's requested width, in pixels. This is the value used by $widget's geometry manager to compute its geometry.

$widget->rgb(color)

Returns a list containing three decimal values, which are the red, green, and blue intensities that correspond to color in the window given by $widget. Color may be specified in any of the forms acceptable for a color option.

$widget->rootx

Returns a decimal string giving the x-coordinate, in the root window of the screen, of the upper-left corner of $widget's border (or $widget if it has no border).

$widget->rooty

Returns a decimal string giving the y-coordinate, in the root window of the screen, of the upper-left corner of $widget's border (or $widget if it has no border).

scaling
$widget->scaling?(number)?

Sets and queries the current scaling factor used by Tk to convert between physical units (for example, points, inches, or millimeters) and pixels. The number argument is a floating point number that specifies the number of pixels per point on $widget's display. If the number argument is omitted, the current value of the scaling factor is returned.

A ``point'' is a unit of measurement equal to 1/72 inch. A scaling factor of 1.0 corresponds to 1 pixel per point, which is equivalent to a standard 72 dpi monitor. A scaling factor of 1.25 would mean 1.25 pixels per point, which is the setting for a 90 dpi monitor; setting the scaling factor to 1.25 on a 72 dpi monitor would cause everything in the application to be displayed 1.25 times as large as normal. The initial value for the scaling factor is set when the application starts, based on properties of the installed monitor (as reported via the window system), but it can be changed at any time. Measurements made after the scaling factor is changed will use the new scaling factor, but it is undefined whether existing widgets will resize themselves dynamically to accomodate the new scaling factor.

$widget->screen

Returns the name of the screen associated with $widget, in the form displayName.screenIndex.

$widget->screencells

Returns a decimal string giving the number of cells in the default color map for $widget's screen.

$widget->screendepth

Returns a decimal string giving the depth of the root window of $widget's screen (number of bits per pixel).

$widget->screenheight

Returns a decimal string giving the height of $widget's screen, in pixels.

$widget->screenmmheight

Returns a decimal string giving the height of $widget's screen, in millimeters.

$widget->screenmmwidth

Returns a decimal string giving the width of $widget's screen, in millimeters.

$widget->screenvisual

Returns one of the following strings to indicate the default visual class for $widget's screen: directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor.

$widget->screenwidth

Returns a decimal string giving the width of $widget's screen, in pixels.

$widget->server

Returns a string containing information about the server for $widget's display. The exact format of this string may vary from platform to platform. For X servers the string has the form ``X major R minor vendor vendorVersion'' where major and minor are the version and revision numbers provided by the server (e.g., X11R5), vendor is the name of the vendor for the server, and vendorRelease is an integer release number provided by the server.

$widget->toplevel

Returns the reference of the top-level window containing $widget.

$widget->UnmapWindow

Cause $widget to be "unmapped" i.e. removed from the display. This does for any widget what $widget->withdraw does for toplevel widgets. May confuse the geometry manager (pack, grid, place, ...) that thinks it is managing the widget.

$widget->update

One of two methods which are used to bring the application ``up to date'' by entering the event loop repeated until all pending events (including idle callbacks) have been processed.

The update method is useful in scripts where you are performing a long-running computation but you still want the application to respond to events such as user interactions; if you occasionally call update then user input will be processed during the next call to update.

$widget->Unbusy

Restores widget state after a call to $widget->Busy.

$widget->viewable

Returns 1 if $widget and all of its ancestors up through the nearest toplevel window are mapped. Returns 0 if any of these windows are not mapped.

$widget->visual

Returns one of the following strings to indicate the visual class for $widget: directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor.

$widget->visualid

Returns the X identifier for the visual for $widget.

$widget->visualsavailable(?includeids?)

Returns a list whose elements describe the visuals available for $widget's screen. Each element consists of a visual class followed by an integer depth. The class has the same form as returned by $widget->visual. The depth gives the number of bits per pixel in the visual. In addition, if the includeids argument is provided, then the depth is followed by the X identifier for the visual.

$widget->vrootheight

Returns the height of the virtual root window associated with $widget if there is one; otherwise returns the height of $widget's screen.

$widget->vrootwidth

Returns the width of the virtual root window associated with $widget if there is one; otherwise returns the width of $widget's screen.

$widget->vrootx

Returns the x-offset of the virtual root window associated with $widget, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for $widget.

$widget->vrooty

Returns the y-offset of the virtual root window associated with $widget, relative to the root window of its screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for $widget.

$widget->waitVariable(\$name)
$widget->waitVisibility
$widget->waitWindow

The tk wait methods wait for one of several things to happen, then it returns without taking any other actions. The return value is always an empty string. waitVariable expects a reference to a perl variable and the command waits for that variable to be modified. This form is typically used to wait for a user to finish interacting with a dialog which sets the variable as part (possibly final) part of the interaction. waitVisibility waits for a change in $widget's visibility state (as indicated by the arrival of a VisibilityNotify event). This form is typically used to wait for a newly-created window to appear on the screen before taking some action. waitWindow waits for $widget to be destroyed. This form is typically used to wait for a user to finish interacting with a dialog box before using the result of that interaction. Note that creating and destroying the window each time a dialog is required makes code modular but imposes overhead which can be avoided by withdrawing the window instead and using waitVisibility.

While the tk wait methods are waiting they processes events in the normal fashion, so the application will continue to respond to user interactions. If an event handler invokes tkwait again, the nested call to tkwait must complete before the outer call can complete.

$widget->width

Returns a decimal string giving $widget's width in pixels. When a window is first created its width will be 1 pixel; the width will eventually be changed by a geometry manager to fulfill the window's needs. If you need the true width immediately after creating a widget, invoke update to force the geometry manager to arrange it, or use $widget->reqwidth to get the window's requested width instead of its actual width.

$widget->useinputmethods( ?boolean? );

Sets and queries the state of whether Tk should use XIM (X Input Methods) for filtering events. The resulting state is returned. XIM is used in some locales (ie: Japanese, Korean), to handle special input devices. This feature is only significant on X. If XIM support is not available, this will always return 0. If the boolean argument is omitted, the current state is returned. This is turned on by default for the main display.

$widget->windowingsystem;

Returns the current Tk windowing system, one of x11 (X11-based), win32 (MS Windows), classic (Mac OS Classic), or aqua (Mac OS X Aqua).

$widget->x

Returns a decimal string giving the x-coordinate, in $widget's parent, of the upper-left corner of $widget's border (or $widget if it has no border).

$widget->y

Returns a decimal string giving the y-coordinate, in $widget's parent, of the upper-left corner of $widget's border (or $widget if it has no border).

CAVEATS

The above documentaion on generic methods is incomplete.

KEYWORDS

atom, children, class, geometry, height, identifier, information, interpreters, mapped, parent, path name, screen, virtual root, width, window


WidgetDemo - create a standard widget demonstration window.

  • AUTHOR
  • HISTORY
  • COPYRIGHT

NAME

WidgetDemo() - create a standard widget demonstration window.

SYNOPSIS

 use WidgetDemo;
 my $TOP = $MW->WidgetDemo(
     -name             => $demo,
     -text             => 'Learn how to write a widget demonstration!',
     -title            => 'WidgetDemo Demonstration',
     -iconname         => 'WidgetDemo',
     -geometry_manager => 'grid',
     -font             => $FONT,
 );

DESCRIPTION

This constructor builds a standard widget demonstration window, composed of three frames. The top frame contains descriptive demonstration text. The bottom frame contains the "Dismiss" and "See Code" buttons. The middle frame is demonstration container, which came be managed by either the pack or grid geometry manager.

The -text attribute is supplied to a Label widget, which is left-adjusted with -wraplength set to 4 inches. If you require different specifications then pass an array to -text; the first element is the text string and the remaining array elements are standard Label widget attributes - WidgetDemo will rearrange things as required..

    -text => ['Hello World!', qw/-wraplength 6i/],

AUTHOR

Steve Lidie <Stephen.O.Lidie@Lehigh.EDU>

HISTORY

lusol@Lehigh.EDU, LUCC, 97/02/11 lusol@Lehigh.EDU, LUCC, 97/06/07 Stephen.O.Lidie@Lehigh.EDU, LUCC, 97/06/07 . Add Delegates() call that obviates the need for Top(). Many thanks to Achim Bohnet for this patch. . Fix -title so that it works.

COPYRIGHT

Copyright (C) 1997 - 1998 Stephen O. Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Tk::Wm - Communicate with window manager

  • ICON SIZES
  • GEOMETRY MANAGEMENT
  • GRIDDED GEOMETRY MANAGEMENT
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Wm - Communicate with window manager

SYNOPSIS

$toplevel->method(?args?)

DESCRIPTION

The wm methods are used to interact with window managers in order to control such things as the title for a window, its geometry, or the increments in terms of which it may be resized. The wm methods can take any of a number of different forms, depending on the particular method argument. All of the forms expect $toplevel, which must be a top-level window object.

The legal forms for the wm methods are:

$toplevel->aspect(?minNumer minDenom maxNumer maxDenom?)

If minNumer, minDenom, maxNumer, and maxDenom are all specified, then they will be passed to the window manager and the window manager should use them to enforce a range of acceptable aspect ratios for $toplevel. The aspect ratio of $toplevel (width/length) will be constrained to lie between minNumer/minDenom and maxNumer/maxDenom. If minNumer etc. are all specified as empty strings, then any existing aspect ratio restrictions are removed. If minNumer etc. are specified, then the method returns an empty string. Otherwise, it returns a array containing four elements, which are the current values of minNumer, minDenom, maxNumer, and maxDenom (if no aspect restrictions are in effect, then an empty string is returned).

$widget->attributes( ?args? );

This subcommand returns or sets platform specific attributes associated with a window.

$widget->attributes;

Returns a list of the platform specific flags and their values.

$widget->attributes( ?option? );

Returns the value for the specific option.

$widget->attributes( ?option value option value...? );

Sets one or more of the values. The values are as follows:

On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other win- dows).

On Macintosh, there are currently no special attribute values.

On Unix, there are currently no special attribute values.

$toplevel->client(?name?)

If name is specified, this method stores name (which should be the name of the host on which the application is executing) in $toplevel's WM_CLIENT_MACHINE property for use by the window manager or session manager. The method returns an empty string in this case. If name isn't specified, the method returns the last name set in a client method for $toplevel. If name is specified as an empty string, the method deletes the WM_CLIENT_MACHINE property from $toplevel.

$toplevel->colormapwindows(?windowList?)

This method is used to manipulate the WM_COLORMAP_WINDOWS property, which provides information to the window managers about windows that have private colormaps. If windowList isn't specified, the method returns a list whose elements are the names of the windows in the WM_COLORMAP_WINDOWS property. If windowList is specified, it consists of a list of widgets; the method overwrites the WM_COLORMAP_WINDOWS property with the given windows and returns an empty string. The WM_COLORMAP_WINDOWS property should normally contain a list of the internal windows within $toplevel whose colormaps differ from their parents. The order of the windows in the property indicates a priority order: the window manager will attempt to install as many colormaps as possible from the head of this list when $widget gets the colormap focus. If $widget is not included among the windows in windowList, Tk implicitly adds it at the end of the WM_COLORMAP_WINDOWS property, so that its colormap is lowest in priority. If $widget->colormapwindows is not invoked, Tk will automatically set the property for each top-level window to all the internal windows whose colormaps differ from their parents, followed by the top-level itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the WM_COLORMAP_WINDOWS property.

$toplevel->command(?value?)

If value is specified, this method stores value in $toplevel's WM_COMMAND property for use by the window manager or session manager and returns an empty string. Value must have proper list structure; the elements should contain the words of the command used to invoke the application. If value isn't specified then the method returns the last value set in a command method for $toplevel. If value is specified as an empty string, the method deletes the WM_COMMAND property from $toplevel.

$toplevel->deiconify

Arrange for $toplevel to be displayed in normal (non-iconified) form. This is done by mapping the window. If the window has never been mapped then this method will not map the window, but it will ensure that when the window is first mapped it will be displayed in de-iconified form. Returns an empty string.

$toplevel->focusmodel(?active|passive?)

If active or passive is supplied as an optional argument to the method, then it specifies the focus model for $toplevel. In this case the method returns an empty string. If no additional argument is supplied, then the method returns the current focus model for $toplevel. An active focus model means that $toplevel will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. Passive means that $toplevel will never claim the focus for itself: the window manager should give the focus to $toplevel at appropriate times. However, once the focus has been given to $toplevel or one of its descendants, the application may re-assign the focus among $toplevel's descendants. The focus model defaults to passive, and Tk's focus method assumes a passive model of focusing.

$toplevel->frame

If $widget has been reparented by the window manager into a decorative frame, the method returns the platform specific window identifier for the outermost frame that contains $toplevel (the window whose parent is the root or virtual root). If $toplevel hasn't been reparented by the window manager then the method returns the platform specific window identifier for $toplevel.

$toplevel->geometry(?newGeometry?)

If newGeometry is specified, then the geometry of $toplevel is changed and an empty string is returned. Otherwise the current geometry for $toplevel is returned (this is the most recent geometry specified either by manual resizing or in a geometry method). NewGeometry has the form =width x height+-x+-y, where any of =, width x height, or +-x+-y may be omitted. Width and height are positive integers specifying the desired dimensions of $toplevel. If $toplevel is gridded (see GRIDDED GEOMETRY MANAGEMENT below) then the dimensions are specified in grid units; otherwise they are specified in pixel units. X and y specify the desired location of $toplevel on the screen, in pixels. If x is preceded by +, it specifies the number of pixels between the left edge of the screen and the left edge of $toplevel's border; if preceded by - then x specifies the number of pixels between the right edge of the screen and the right edge of $toplevel's border. If y is preceded by + then it specifies the number of pixels between the top of the screen and the top of $toplevel's border; if y is preceded by - then it specifies the number of pixels between the bottom of $toplevel's border and the bottom of the screen. If newGeometry is specified as an empty string then any existing user-specified geometry for $toplevel is cancelled, and the window will revert to the size requested internally by its widgets.

$toplevel->wmGrid(?baseWidth,baseHeight,widthInc,heightInc?)

This method indicates that $toplevel is to be managed as a gridded window. It also specifies the relationship between grid units and pixel units. BaseWidth and baseHeight specify the number of grid units corresponding to the pixel dimensions requested internally by $toplevel using Tk_GeometryRequest. WidthInc and heightInc specify the number of pixels in each horizontal and vertical grid unit. These four values determine a range of acceptable sizes for $toplevel, corresponding to grid-based widths and heights that are non-negative integers. Tk will pass this information to the window manager; during manual resizing, the window manager will restrict the window's size to one of these acceptable sizes. Furthermore, during manual resizing the window manager will display the window's current size in terms of grid units rather than pixels. If baseWidth etc. are all specified as empty strings, then $toplevel will no longer be managed as a gridded window. If baseWidth etc. are specified then the return value is an empty string. Otherwise the return value is a array containing four elements corresponding to the current baseWidth, baseHeight, widthInc, and heightInc; if $toplevel is not currently gridded, then an empty string is returned. Note: this command should not be needed very often, since the Tk_SetGrid library procedure and the -setgrid option provide easier access to the same functionality.

$toplevel->group(?$widget?)

If $widget is specified, it is the the leader of a group of related windows. The window manager may use this information, for example, to unmap all of the windows in a group when the group's leader is iconified. $widget may be specified as an empty string to remove $toplevel from any group association. If $widget is specified then the method returns an empty string; otherwise it returns the $toplevel's current group leader, or an empty string if $toplevel isn't part of any group.

$toplevel->iconbitmap(?bitmap?)

If bitmap is specified, then it names a bitmap in the standard forms accepted by Tk (see the Tk_GetBitmap documentation for details). This black and white bitmap is passed to the window manager to be displayed in $toplevel's icon, and the method returns an empty string. If an empty string is specified for bitmap, then any current icon bitmap or image is cancelled for $toplevel. If bitmap is specified then the method returns an empty string. Otherwise it returns the name of the current icon bitmap associated with $toplevel, or an empty string if $toplevel has no icon bitmap.

$toplevel->iconify

Arrange for $toplevel to be iconified. It $toplevel hasn't yet been mapped for the first time, this method will arrange for it to appear in the iconified state when it is eventually mapped.

$toplevel->iconimage(?image?)

If image is specified, then it names a normal Tk image. This image is rendered into a private coloured bitmap which is passed to the window manager to be displayed in $toplevel's icon, and the method returns an empty string. If an empty string is specified for image, then any current icon bitmap or image is cancelled for $toplevel. If image is specified then the method returns an empty string. Otherwise it returns the name of the current icon image associated with $toplevel, or an empty string if $toplevel has no icon image. The private pixmap is not pre-cleared so images which are partly "transparent" display rubbish in their transparent parts.

The sizes of images that can be used as icons in this manner are platform dependant. On Win32 this sets the "large" icon, which should be 32x32, it will automatically be scaled down to 16x16 for use as a small icon.

$toplevel->iconmask(?bitmap?)

If bitmap is specified, then it names a bitmap in the standard forms accepted by Tk (see the Tk_GetBitmap documentation for details). This bitmap is passed to the window manager to be used as a mask in conjunction with the iconbitmap option: where the mask has zeroes no icon will be displayed; where it has ones, the bits from the icon bitmap will be displayed. If an empty string is specified for bitmap then any current icon mask is cancelled for $toplevel (this is equivalent to specifying a bitmap of all ones). If bitmap is specified then the method returns an empty string. Otherwise it returns the name of the current icon mask associated with $toplevel, or an empty string if no mask is in effect.

$toplevel->iconname(?newName?)

If newName is specified, then it is passed to the window manager; the window manager should display newName inside the icon associated with $toplevel. In this case an empty string is returned as result. If newName isn't specified then the method returns the current icon name for $toplevel, or an empty string if no icon name has been specified (in this case the window manager will normally display the window's title, as specified with the title method).

$toplevel->iconposition(?x y?)

If x and y are specified, they are passed to the window manager as a hint about where to position the icon for $toplevel. In this case an empty string is returned. If x and y are specified as empty strings then any existing icon position hint is cancelled. If neither x nor y is specified, then the method returns a array containing two values, which are the current icon position hints (if no hints are in effect then an empty string is returned).

$toplevel->iconwindow(?$widget?)

If $widget is specified, it is a window to use as icon for $toplevel: when $toplevel is iconified then $widget will be mapped to serve as icon, and when $toplevel is de-iconified then $widget will be unmapped again. If $widget is specified as an empty string then any existing icon window association for $toplevel will be cancelled. If the $widget argument is specified then an empty string is returned. Otherwise the method returns the current icon window for $toplevel, or an empty string if there is no icon window currently specified for $toplevel. Button press events are disabled for $toplevel as long as it is an icon window; this is needed in order to allow window managers to ``own'' those events. Note: not all window managers support the notion of an icon window.

$toplevel->maxsize(?width,height?)

If width and height are specified, they give the maximum permissible dimensions for $toplevel. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be less than or equal to width and height. If width and height are specified, then the method returns an empty string. Otherwise it returns a array with two elements, which are the maximum width and height currently in effect. The maximum size defaults to the size of the screen. If resizing has been disabled with the resizable method, then this method has no effect. See the sections on geometry management below for more information.

$toplevel->minsize(?width,height?)

If width and height are specified, they give the minimum permissible dimensions for $toplevel. For gridded windows the dimensions are specified in grid units; otherwise they are specified in pixel units. The window manager will restrict the window's dimensions to be greater than or equal to width and height. If width and height are specified, then the method returns an empty string. Otherwise it returns a array with two elements, which are the minimum width and height currently in effect. The minimum size defaults to one pixel in each dimension. If resizing has been disabled with the resizable method, then this method has no effect. See the sections on geometry management below for more information.

$toplevel->overrideredirect(?boolean?)

If boolean is specified, it must have a proper boolean form and the override-redirect flag for $toplevel is set to that value. If boolean is not specified then 1 or 0 is returned to indicate whether or not the override-redirect flag is currently set for $toplevel. Setting the override-redirect flag for a window causes it to be ignored by the window manager; among other things, this means that the window will not be reparented from the root window into a decorative frame and the user will not be able to manipulate the window using the normal window manager mechanisms.

$toplevel->positionfrom(?who?)

If who is specified, it must be either program or user, or an abbreviation of one of these two. It indicates whether $toplevel's current position was requested by the program or by the user. Many window managers ignore program-requested initial positions and ask the user to manually position the window; if user is specified then the window manager should position the window at the given place without asking the user for assistance. If who is specified as an empty string, then the current position source is cancelled. If who is specified, then the method returns an empty string. Otherwise it returns user or $widget to indicate the source of the window's current position, or an empty string if no source has been specified yet. Most window managers interpret ``no source'' as equivalent to program. Tk will automatically set the position source to user when a geometry method is invoked, unless the source has been set explicitly to program.

$toplevel->protocol(?name?,?callback?)

This method is used to manage window manager protocols such as WM_DELETE_WINDOW. Name is the name of an atom corresponding to a window manager protocol, such as WM_DELETE_WINDOW or WM_SAVE_YOURSELF or WM_TAKE_FOCUS. If both name and callback are specified, then callback is associated with the protocol specified by name. Name will be added to $toplevel's WM_PROTOCOLS property to tell the window manager that the application has a protocol handler for name, and callback will be invoked in the future whenever the window manager sends a message to the client for that protocol. In this case the method returns an empty string. If name is specified but callback isn't, then the current callback for name is returned, or an empty string if there is no handler defined for name. If callback is specified as an empty string then the current handler for name is deleted and it is removed from the WM_PROTOCOLS property on $toplevel; an empty string is returned. Lastly, if neither name nor callback is specified, the method returns a list of all the protocols for which handlers are currently defined for $toplevel.

Tk always defines a protocol handler for WM_DELETE_WINDOW, even if you haven't asked for one with protocol. If a WM_DELETE_WINDOW message arrives when you haven't defined a handler, then Tk handles the message by destroying the window for which it was received.

$toplevel->resizable(?width,height?)

This method controls whether or not the user may interactively resize a top-level window. If width and height are specified, they are boolean values that determine whether the width and height of $toplevel may be modified by the user. In this case the method returns an empty string. If width and height are omitted then the method returns a list with two 0/1 elements that indicate whether the width and height of $toplevel are currently resizable. By default, windows are resizable in both dimensions. If resizing is disabled, then the window's size will be the size from the most recent interactive resize or geometry method. If there has been no such operation then the window's natural size will be used.

$toplevel->sizefrom(?who?)

If who is specified, it must be either program or user, or an abbreviation of one of these two. It indicates whether $toplevel's current size was requested by the program or by the user. Some window managers ignore program-requested sizes and ask the user to manually size the window; if user is specified then the window manager should give the window its specified size without asking the user for assistance. If who is specified as an empty string, then the current size source is cancelled. If who is specified, then the method returns an empty string. Otherwise it returns user or $widget to indicate the source of the window's current size, or an empty string if no source has been specified yet. Most window managers interpret ``no source'' as equivalent to program.

$toplevel->stackorder( ?isabove|isbelow $toplevel? );

The stackorder command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the window's children that are toplevels. Only those toplevels that are currently mapped to the screen are returned. The stackorder command can also be used to determine if one toplevel is positioned above or below a second toplevel. When two window arguments separated by either isabove or isbelow are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order.

$toplevel->state(?newstate?)

If newstate is specified, the window will be set to the new state, otherwise it returns the current state of $toplevel: either normal, iconic, withdrawn, icon, or (Windows only) zoomed. The difference between iconic and icon is that iconic refers to a window that has been iconified (e.g., with the iconify method) while icon refers to a window whose only purpose is to serve as the icon for some other window (via the iconwindow method). The icon state cannot be set.

$toplevel->title(?string?)

If string is specified, then it will be passed to the window manager for use as the title for $toplevel (the window manager should display this string in $toplevel's title bar). In this case the method returns an empty string. If string isn't specified then the method returns the current title for the $toplevel. The title for a window defaults to its name.

$toplevel->transient(?master?)

If master is specified, then the window manager is informed that $toplevel is a transient window (e.g. pull-down menu) working on behalf of master (where master is a top-level window). Some window managers will use this information to manage $toplevel specially. If master is specified as an empty string then $toplevel is marked as not being a transient window any more. If master is specified, then the method returns an empty string. Otherwise the method returns the path name of $toplevel's current master, or an empty string if $toplevel isn't currently a transient window.

$toplevel->withdraw

Arranges for $toplevel to be withdrawn from the screen. This causes the window to be unmapped and forgotten about by the window manager. If the window has never been mapped, then this method causes the window to be mapped in the withdrawn state. Not all window managers appear to know how to handle windows that are mapped in the withdrawn state. Note: it sometimes seems to be necessary to withdraw a window and then re-map it (e.g. with deiconify) to get some window managers to pay attention to changes in window attributes such as group.

$toplevel->wrapper

Returns the window id of the wrapper window in which Tk has placed $toplevel. This is the id by which window manager will know $toplevel, and so is appropriate place to add X properties.

ICON SIZES

The sizes of bitmaps/images that can be used as icons in this manner are platform and window manager dependant. Unix window managers are typically more tolerant than Win32. It is possible that coloured iconimage icons may cause problems on some X window managers.

  • Win32

    iconimage and iconbitmap set the "large" icon, which should be 32x32, it will automatically be scaled down to 16x16 for use as a small icon. Win32 ignores iconwin requests.

  • KDE's "kwm"

    Accepts coloured iconimage and black and white iconbitmap but will scale either to a small (14x14?) icon. Kwm ignores iconwin.

  • Sun's "olwm" or "olvwm"

    Honours iconwin which will override iconimage or iconbitmap. Coloured images work.

  • Sun's CDE window manager

    Coloured images work. ...

GEOMETRY MANAGEMENT

By default a top-level window appears on the screen in its natural size, which is the one determined internally by its widgets and geometry managers. If the natural size of a top-level window changes, then the window's size changes to match. A top-level window can be given a size other than its natural size in two ways. First, the user can resize the window manually using the facilities of the window manager, such as resize handles. Second, the application can request a particular size for a top-level window using the geometry method. These two cases are handled identically by Tk; in either case, the requested size overrides the natural size. You can return the window to its natural by invoking geometry with an empty geometry string.

Normally a top-level window can have any size from one pixel in each dimension up to the size of its screen. However, you can use the minsize and maxsize methods to limit the range of allowable sizes. The range set by minsize and maxsize applies to all forms of resizing, including the window's natural size as well as manual resizes and the geometry method. You can also use the method resizable to completely disable interactive resizing in one or both dimensions.

GRIDDED GEOMETRY MANAGEMENT

Gridded geometry management occurs when one of the widgets of an application supports a range of useful sizes. This occurs, for example, in a text editor where the scrollbars, menus, and other adornments are fixed in size but the edit widget can support any number of lines of text or characters per line. In this case, it is usually desirable to let the user specify the number of lines or characters-per-line, either with the geometry method or by interactively resizing the window. In the case of text, and in other interesting cases also, only discrete sizes of the window make sense, such as integral numbers of lines and characters-per-line; arbitrary pixel sizes are not useful.

Gridded geometry management provides support for this kind of application. Tk (and the window manager) assume that there is a grid of some sort within the application and that the application should be resized in terms of grid units rather than pixels. Gridded geometry management is typically invoked by turning on the setGrid option for a widget; it can also be invoked with the wmGrid method or by calling Tk_SetGrid. In each of these approaches the particular widget (or sometimes code in the application as a whole) specifies the relationship between integral grid sizes for the window and pixel sizes. To return to non-gridded geometry management, invoke grid with empty argument strings.

When gridded geometry management is enabled then all the dimensions specified in minsize, maxsize, and geometry methods are treated as grid units rather than pixel units. Interactive resizing is also carried out in even numbers of grid units rather than pixels.

BUGS

Most existing window managers appear to have bugs that affect the operation of the wm methods. For example, some changes won't take effect if the window is already active: the window will have to be withdrawn and de-iconified in order to make the change happen.

SEE ALSO

Tk::Widget
Tk::tixWm
Tk::Mwm

KEYWORDS

aspect ratio, deiconify, focus model, geometry, grid, group, icon, iconify, increments, position, size, title, top-level window, units, window manager


Tk::X - Perl extension for Xlib constants.

  • Exported constants
  • AUTHOR

NAME

Tk::X - Perl extension for Xlib constants.

SYNOPSIS

  use Tk::X;

DESCRIPTION

A module generated by h2xs. It exists to export Xlib #define type constants for possible use with Tk::Xlib.

Exported constants

  Above
  AllTemporary
  AllocAll
  AllocNone
  AllowExposures
  AlreadyGrabbed
  Always
  AnyButton
  AnyKey
  AnyModifier
  AnyPropertyType
  ArcChord
  ArcPieSlice
  AsyncBoth
  AsyncKeyboard
  AsyncPointer
  AutoRepeatModeDefault
  AutoRepeatModeOff
  AutoRepeatModeOn
  BadAccess
  BadAlloc
  BadAtom
  BadColor
  BadCursor
  BadDrawable
  BadFont
  BadGC
  BadIDChoice
  BadImplementation
  BadLength
  BadMatch
  BadName
  BadPixmap
  BadRequest
  BadValue
  BadWindow
  Below
  BottomIf
  Button1
  Button1Mask
  Button1MotionMask
  Button2
  Button2Mask
  Button2MotionMask
  Button3
  Button3Mask
  Button3MotionMask
  Button4
  Button4Mask
  Button4MotionMask
  Button5
  Button5Mask
  Button5MotionMask
  ButtonMotionMask
  ButtonPress
  ButtonPressMask
  ButtonRelease
  ButtonReleaseMask
  CWBackPixel
  CWBackPixmap
  CWBackingPixel
  CWBackingPlanes
  CWBackingStore
  CWBitGravity
  CWBorderPixel
  CWBorderPixmap
  CWBorderWidth
  CWColormap
  CWCursor
  CWDontPropagate
  CWEventMask
  CWHeight
  CWOverrideRedirect
  CWSaveUnder
  CWSibling
  CWStackMode
  CWWidth
  CWWinGravity
  CWX
  CWY
  CapButt
  CapNotLast
  CapProjecting
  CapRound
  CenterGravity
  CirculateNotify
  CirculateRequest
  ClientMessage
  ClipByChildren
  ColormapChangeMask
  ColormapInstalled
  ColormapNotify
  ColormapUninstalled
  Complex
  ConfigureNotify
  ConfigureRequest
  ControlMapIndex
  ControlMask
  Convex
  CoordModeOrigin
  CoordModePrevious
  CopyFromParent
  CreateNotify
  CurrentTime
  CursorShape
  DefaultBlanking
  DefaultExposures
  DestroyAll
  DestroyNotify
  DirectColor
  DisableAccess
  DisableScreenInterval
  DisableScreenSaver
  DoBlue
  DoGreen
  DoRed
  DontAllowExposures
  DontPreferBlanking
  EastGravity
  EnableAccess
  EnterNotify
  EnterWindowMask
  EvenOddRule
  Expose
  ExposureMask
  FamilyChaos
  FamilyDECnet
  FamilyInternet
  FillOpaqueStippled
  FillSolid
  FillStippled
  FillTiled
  FirstExtensionError
  FocusChangeMask
  FocusIn
  FocusOut
  FontChange
  FontLeftToRight
  FontRightToLeft
  ForgetGravity
  GCArcMode
  GCBackground
  GCCapStyle
  GCClipMask
  GCClipXOrigin
  GCClipYOrigin
  GCDashList
  GCDashOffset
  GCFillRule
  GCFillStyle
  GCFont
  GCForeground
  GCFunction
  GCGraphicsExposures
  GCJoinStyle
  GCLastBit
  GCLineStyle
  GCLineWidth
  GCPlaneMask
  GCStipple
  GCSubwindowMode
  GCTile
  GCTileStipXOrigin
  GCTileStipYOrigin
  GXand
  GXandInverted
  GXandReverse
  GXclear
  GXcopy
  GXcopyInverted
  GXequiv
  GXinvert
  GXnand
  GXnoop
  GXnor
  GXor
  GXorInverted
  GXorReverse
  GXset
  GXxor
  GrabFrozen
  GrabInvalidTime
  GrabModeAsync
  GrabModeSync
  GrabNotViewable
  GrabSuccess
  GraphicsExpose
  GravityNotify
  GrayScale
  HostDelete
  HostInsert
  IncludeInferiors
  InputFocus
  InputOnly
  InputOutput
  IsUnmapped
  IsUnviewable
  IsViewable
  JoinBevel
  JoinMiter
  JoinRound
  KBAutoRepeatMode
  KBBellDuration
  KBBellPercent
  KBBellPitch
  KBKey
  KBKeyClickPercent
  KBLed
  KBLedMode
  KeyPress
  KeyPressMask
  KeyRelease
  KeyReleaseMask
  KeymapNotify
  KeymapStateMask
  LASTEvent
  LSBFirst
  LastExtensionError
  LeaveNotify
  LeaveWindowMask
  LedModeOff
  LedModeOn
  LineDoubleDash
  LineOnOffDash
  LineSolid
  LockMapIndex
  LockMask
  LowerHighest
  MSBFirst
  MapNotify
  MapRequest
  MappingBusy
  MappingFailed
  MappingKeyboard
  MappingModifier
  MappingNotify
  MappingPointer
  MappingSuccess
  Mod1MapIndex
  Mod1Mask
  Mod2MapIndex
  Mod2Mask
  Mod3MapIndex
  Mod3Mask
  Mod4MapIndex
  Mod4Mask
  Mod5MapIndex
  Mod5Mask
  MotionNotify
  NoEventMask
  NoExpose
  NoSymbol
  Nonconvex
  None
  NorthEastGravity
  NorthGravity
  NorthWestGravity
  NotUseful
  NotifyAncestor
  NotifyDetailNone
  NotifyGrab
  NotifyHint
  NotifyInferior
  NotifyNonlinear
  NotifyNonlinearVirtual
  NotifyNormal
  NotifyPointer
  NotifyPointerRoot
  NotifyUngrab
  NotifyVirtual
  NotifyWhileGrabbed
  Opposite
  OwnerGrabButtonMask
  ParentRelative
  PlaceOnBottom
  PlaceOnTop
  PointerMotionHintMask
  PointerMotionMask
  PointerRoot
  PointerWindow
  PreferBlanking
  PropModeAppend
  PropModePrepend
  PropModeReplace
  PropertyChangeMask
  PropertyDelete
  PropertyNewValue
  PropertyNotify
  PseudoColor
  RaiseLowest
  ReparentNotify
  ReplayKeyboard
  ReplayPointer
  ResizeRedirectMask
  ResizeRequest
  RetainPermanent
  RetainTemporary
  RevertToNone
  RevertToParent
  RevertToPointerRoot
  ScreenSaverActive
  ScreenSaverReset
  SelectionClear
  SelectionNotify
  SelectionRequest
  SetModeDelete
  SetModeInsert
  ShiftMapIndex
  ShiftMask
  SouthEastGravity
  SouthGravity
  SouthWestGravity
  StaticColor
  StaticGravity
  StaticGray
  StippleShape
  StructureNotifyMask
  SubstructureNotifyMask
  SubstructureRedirectMask
  Success
  SyncBoth
  SyncKeyboard
  SyncPointer
  TileShape
  TopIf
  TrueColor
  UnmapGravity
  UnmapNotify
  Unsorted
  VisibilityChangeMask
  VisibilityFullyObscured
  VisibilityNotify
  VisibilityPartiallyObscured
  VisibilityUnobscured
  WestGravity
  WhenMapped
  WindingRule
  XYBitmap
  XYPixmap
  X_H
  X_PROTOCOL
  X_PROTOCOL_REVISION
  YSorted
  YXBanded
  YXSorted
  ZPixmap

AUTHOR

Nick Ing-Simmons ran h2xs ...


Tk::X11Font - a class for finding X Fonts

  • METHODS
    • Foundry( [ $val ] )
    • Family( [ $val ] )
    • Weight( [ $val ] )
    • Slant( [ $val ] )
    • Swidth( [ $val ] )
    • Adstyle( [ $val ] )
    • Pixel( [ $val ] )
    • Point( [ $val ] )
    • Xres( [ $val ] )
    • Yres( [ $val ] )
    • Space( [ $val ] )
    • Avgwidth( [ $val ] )
    • Registry( [ $val ] )
    • Encoding( [ $val ] )
    • Name( [ $max ] )
    • Clone( [ key => value, [ ...]] )
  • AUTHOR
  • HISTORY
  • COPYRIGHT

NAME

Tk::X11Font - a class for finding X Fonts

SYNOPSIS

 use Tk::X11Font;

 $font = $widget->X11Font(foundry => 'adobe',
                       family  => 'times',
                       point   => 120
                      );

 $font = $widget->X11Font('*-courier-medium-r-normal-*-*');

DESCRIPTION

   This module can be use to interrogate the X server what fonts are
   avaliable.

METHODS

Foundry( [ $val ] )

Family( [ $val ] )

Weight( [ $val ] )

Slant( [ $val ] )

Swidth( [ $val ] )

Adstyle( [ $val ] )

Pixel( [ $val ] )

Point( [ $val ] )

Xres( [ $val ] )

Yres( [ $val ] )

Space( [ $val ] )

Avgwidth( [ $val ] )

Registry( [ $val ] )

Encoding( [ $val ] )

Set the given field in the font name to $val if given and return the current or previous value

Name( [ $max ] )

In a list context it returns a list of all font names that match the fields given. It will return a maximum of $max names, or 128 if $max is not given.

In a scalar contex it returns the first matching name or undef

Clone( [ key => value, [ ...]] )

Create a duplicate of the curent font object and modify the given fields

AUTHOR

Graham Barr <Graham.Barr@tiuk.ti.com>

HISTORY

11-Jan-96 Initial version

08-Nov-98 Renamed for Tk800.012

COPYRIGHT

Copyright (c) 1995-1996 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Tk::Xrm - X Resource/Defaults/Options routines that obey the rules.

  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::Xrm - X Resource/Defaults/Options routines that obey the rules.

SYNOPSIS

   use Tk;
   use Tk::Xrm;

DESCRIPTION

Using this modules causes Tk's Option code to be replaced by versions which use routines from <X11/Xresource.h> - i.e. same ones every other X toolkit uses.

Result is that "matching" of name/Class with the options database follows the same rules as other X toolkits. This makes it more predictable, and makes it easier to have a single ~/.Xdefaults file which gives sensible results for both Tk and (say) Motif applications.

BUGS

Currently optionAdd(key => value?, priority?) ignores optional priority completely and just does XrmPutStringResource(). Perhaps it should be more subtle and do XrmMergeDatabases() or XrmCombineDatabase().

This version is a little slower than Tk's re-invention but there is more optimization that can be done.

SEE ALSO

Tk::option

KEYWORDS

database, option, priority, retrieve


Tk::after - Execute a command after a time delay

    • Internal Details
  • Changing a repeat timer interval
  • The after() method has several forms as follows:
  • SEE ALSO
  • KEYWORDS

NAME

Tk::after - Execute a command after a time delay

SYNOPSIS

$widget->after(ms)

$id = $widget->after(ms?,callback?)

$id = $widget->repeat(ms?,callback?)

$widget->afterCancel($id)

$id = $widget->afterIdle(callback)

$widget->afterInfo?($id)?

$id->time(?delay?)

DESCRIPTION

This method is used to delay execution of the program or to execute a callback in background sometime in the future.

In perl/Tk $widget->after is implemented via the class Tk::After, and callbacks are associated with $widget, and are automatically cancelled when the widget is destroyed. An almost identical interface, but without automatic cancel, and without repeat is provided via Tk::after method.

Internal Details

The internal Tk::After class has the following synopsis:

  $id = Tk::After->new($widget, tid, $time, 'once',   callback);
  $id = Tk::After->new($widget, tid, $time, 'repeat', callback);
  $id->cancel;
  $id->time(?delay?);

$id is a Tk::After object, an array of 5 elements:

$widget is the parent widget reference.

tid is the internal timer id, a unique string.

$time is the string 'idle', representing an idle queue timer, or a integer millisecond value.

I<once> or I<repeat> specifies whether the timer is a one-time B<after>
event, or a repeating B<repeat> event.

callback specifies a Perl/Tk Tk::Callback object.

Changing a repeat timer interval

It's posible to change a repeat timer's delay value, or even cancel any timer, using the time method. If delay is specified and non-zero, a new timer delay is established. If delay is zero the timer event is canceled just as if $id->cancel were invoked. In all cases the current millisecond timer delay is returned.

Note: the new timer delay will take effect on the subsequent timer event - this command will not cancel the pending timer event and re-issue it with the new delay time.

The after() method has several forms as follows:

$widget->after(ms)

The value ms must be an integer giving a time in milliseconds. The command sleeps for ms milliseconds and then returns. While the command is sleeping the application does not respond to events.

$widget->after(ms,callback)

In this form the command returns immediately, but it arranges for callback be executed ms milliseconds later as an event handler. The callback will be executed exactly once, at the given time. The command will be executed in context of $widget. If an error occurs while executing the delayed command then the Tk::Error mechanism is used to report the error. The after command returns an identifier (an object in the perl/Tk case) that can be used to cancel the delayed command using afterCancel.

$widget->repeat(ms,callback)

In this form the command returns immediately, but it arranges for callback be executed ms milliseconds later as an event handler. After callback has executed it is re-scheduled, to be executed in a futher ms, and so on until it is cancelled.

$widget->afterCancel($id)
$id->cancel

Cancels the execution of a delayed command that was previously scheduled. $id indicates which command should be canceled; it must have been the return value from a previous after command. If the command given by $id has already been executed (and is not scheduled to be executed again) then afterCancel has no effect.

$widget->afterCancel(callback)

This form is not robust in perl/Tk - its use is deprecated. This command should also cancel the execution of a delayed command. The callback argument is compared with pending callbacks, if a match is found, that callback is cancelled and will never be executed; if no such callback is currently pending then the afterCancel has no effect.

$widget->afterIdle(callback)

Arranges for callback to be evaluated later as an idle callback. The script will be run exactly once, the next time the event loop is entered and there are no events to process. The command returns an identifier that can be used to cancel the delayed command using afterCancel. If an error occurs while executing the script then the Tk::Error mechanism is used to report the error.

$widget->afterInfo?($id)?

This command returns information about existing event handlers. If no $id argument is supplied, the command returns a list of the identifiers for all existing event handlers created by the after and repeat commands for $widget. If $id is supplied, it specifies an existing handler; $id must have been the return value from some previous call to after or repeat and it must not have triggered yet or been cancelled. In this case the command returns a list with three elements. The first element of the list is the callback associated with $id, the second element is either idle or the integer timer millisecond value to indicate what kind of event handler it is, and the third is a string once or repeat to differentiate an after from a repeat event.

The after(ms) and afterIdle forms of the command assume that the application is event driven: the delayed commands will not be executed unless the application enters the event loop. In applications that are not normally event-driven, the event loop can be entered with the vwait and update commands.

SEE ALSO

Tk::Error Tk::callbacks

KEYWORDS

cancel, delay, idle callback, sleep, time


Tk::bind - Arrange for X events to invoke callbacks

  • EVENT PATTERNS
  • MODIFIERS
  • EVENT TYPES
  • BINDING CALLBACKS AND SUBSTITUTIONS
  • MULTIPLE MATCHES
  • MULTI-EVENT SEQUENCES AND IGNORED EVENTS
  • ERRORS
  • CAVEATS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::bind - Arrange for X events to invoke callbacks

SYNOPSIS

Retrieve bindings:

$widget->bind

$widget->bind(tag)

$widget->bind(sequence)

$widget->bind(tag,sequence)

Associate and destroy bindings:

$widget->bind(sequence,callback)

$widget->bind(tag,sequence,callback)

DESCRIPTION

The bind method associates callbacks with X events. If callback is specified, bind will arrange for callback to be evaluated whenever the event(s) given by sequence occur in the window(s) identified by $widget or tag. If callback is an empty string then the current binding for sequence is destroyed, leaving sequence unbound. In all of the cases where a callback argument is provided, bind returns an empty string.

If sequence is specified without a callback, then the callback currently bound to sequence is returned, or undef is returned if there is no binding for sequence. If neither sequence nor callback is specified, then the return value is a list whose elements are all the sequences for which there exist bindings for tag.

If no tag is specified then the bind refers to $widget. If tag is specified then it is typically a class name and the bind refers to all instances of the class on the MainWindow associated with $widget. (It is possible for tag to be another "widget object" but this practice is deprecated.) Perl's ref($object) can be used to get the class name of any object. Each window has an associated list of tags, and a binding applies to a particular window if its tag is among those specified for the window. Although the bindtags method may be used to assign an arbitrary set of binding tags to a window, the default binding tags provide the following behavior:

If a tag is the name of an internal window the binding applies to that window.

If the tag is the name of a toplevel window the binding applies to the toplevel window and all its internal windows.

If the tag is the name of a class of widgets, such as Tk::Button, the binding applies to all widgets in that class;

If tag has the value all, the binding applies to all windows descended from the MainWindow of the application.

EVENT PATTERNS

The sequence argument specifies a sequence of one or more event patterns, with optional white space between the patterns. Each event pat may take one of three forms. In the simplest case it is a single printing ASCII character, such as a or [. The character may not be a space character or the character <. This form of pattern matches a KeyPress event for the particular character. The second form of pattern is longer but more general. It has the following syntax:

'<modifier-modifier-type-detail>'

The entire event pattern is surrounded by angle brackets, and normally needs to be quoted, as angle brackets are special to perl. Inside the angle brackets are zero or more modifiers, an event type, and an extra piece of information (detail) identifying a particular button or keysym. Any of the fields may be omitted, as long as at least one of type and detail is present. The fields must be separated by white space or dashes.

The third form of pattern is used to specify a user-defined, named virtual event; see the Tk::event manpage for details. It has the following syntax:

'<<name>>'

The entire virtual event pattern is surrounded by double angle brackets. Inside the angle brackets is the user-defined name of the virtual event. Modifiers, such as Shift or Control, may not be combined with a virtual event to modify it. Bindings on a virtual event may be created before the virtual event is defined, and if the definition of a virtual event changes dynamically, all windows bound to that virtual event will respond immediately to the new definition.

MODIFIERS

Modifiers consist of any of the following values:

 Control        Mod2, M2
 Shift          Mod3, M3
 Lock           Mod4, M4
 Button1, B1    Mod5, M5
 Button2, B2    Meta, M
 Button3, B3    Alt
 Button4, B4    Double
 Button5, B5    Triple
 Mod1,    M1    Quadruple

Where more than one value is listed, separated by commas, the values are equivalent. Most of the modifiers have the obvious X meanings. For example, Button1 requires that button 1 be depressed when the event occurs. For a binding to match a given event, the modifiers in the event must include all of those specified in the event pattern. An event may also contain additional modifiers not specified in the binding. For example, if button 1 is pressed while the shift and control keys are down, the pattern <Control-Button-1> will match the event, but <Mod1-Button-1> will not. If no modifiers are specified, then any combination of modifiers may be present in the event.

Meta and M refer to whichever of the M1 through M5 modifiers is associated with the meta key(s) on the keyboard (keysyms Meta_R and Meta_L). If there are no meta keys, or if they are not associated with any modifiers, then Meta and M will not match any events. Similarly, the Alt modifier refers to whichever modifier is associated with the alt key(s) on the keyboard (keysyms Alt_L and Alt_R).

The Double, Triple and Quadruple modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2, 3 or 4 times, and also place a time and space requirement on the sequence: for a sequence of events to match a Double, Triple or Quadruple pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, <Double-Button-1> is equivalent to <Button-1><Button-1> with the extra time and space requirement.

EVENT TYPES

The type field may be any of the standard X event types, with a few extra abbreviations. Below is a list of all the valid types; where two names appear together, they are synonyms.

    Activate            Destroy            Map
    ButtonPress, Button Enter              MapRequest
    ButtonRelease       Expose             Motion
    Circulate           FocusIn            MouseWheel
    CirculateRequest    FocusOut           Property
    Colormap            Gravity            Reparent
    Configure           KeyPress, Key      ResizeRequest
    ConfigureRequest    KeyRelease         Unmap
    Create              Leave              Visibility
    Deactivate

Most of the above events have the same fields and behaviors as events in the X Windowing system. You can find more detailed descriptions of these events in any X window programming book. A couple of the events are extensions to the X event system to support features unique to the Macintosh and Windows platforms. We provide a little more detail on these events here. These include:

    Activate
    Deactivate

These two events are sent to every sub-window of a toplevel when they change state. In addition to the focus Window, the Macintosh platform and Windows platforms have a notion of an active window (which often has but is not required to have the focus). On the Macintosh, widgets in the active window have a different appearance than widgets in deactive windows. The Activate event is sent to all the sub-windows in a toplevel when it changes from being deactive to active. Likewise, the Deactive event is sent when the window's state changes from active to deactive. There are no use- ful percent substitutions you would make when binding to these events.

    MouseWheel

Some mice on the Windows platform support a mouse wheel which is used for scrolling documents without using the scrollbars. By rolling the wheel, the system will generate MouseWheel events that the application can use to scroll. Like Key events the event is always routed to the window that currently has focus. When the event is received you can use the %D substitution to get the delta field for the event which is a integer value of motion that the mouse wheel has moved. The smallest value for which the system will report is defined by the OS. On Windows 95 & 98 machines this value is at least 120 before it is reported. However, higher resolution devices may be available in the future. The sign of the value determines which direction your widget should scroll. Positive values should scroll up and negative values should scroll down.

The last part of a long event specification is I<detail>.  In the
case of a B<ButtonPress> or B<ButtonRelease> event, it is the
number of a button (1-5).  If a button number is given, then only an
event on that particular button will match;  if no button number is
given, then an event on any button will match.  Note:  giving a
specific button number is different than specifying a button modifier;
in the first case, it refers to a button being pressed or released,
while in the second it refers to some other button that is already
depressed when the matching event occurs.  If a button
number is given then I<type> may be omitted:  if will default
to B<ButtonPress>.  For example, the specifier B<E<lt>1E<gt>>
is equivalent to B<E<lt>ButtonPress-1E<gt>>.

If the event type is KeyPress or KeyRelease, then detail may be specified in the form of an X keysym. Keysyms are textual specifications for particular keys on the keyboard; they include all the alphanumeric ASCII characters (e.g. ``a'' is the keysym for the ASCII character ``a''), plus descriptions for non-alphanumeric characters (``comma'' is the keysym for the comma character), plus descriptions for all the non-ASCII keys on the keyboard (``Shift_L'' is the keysm for the left shift key, and ``F1'' is the keysym for the F1 function key, if it exists). The complete list of keysyms is not presented here; it is available in other X documentation and may vary from system to system. If necessary, you can use the 'K' notation described below to print out the keysym name for a particular key. If a keysym detail is given, then the type field may be omitted; it will default to KeyPress. For example, <Control-comma> is equivalent to <Control-KeyPress-comma>.

BINDING CALLBACKS AND SUBSTITUTIONS

The callback argument to bind is a perl/Tk callback. which will be executed whenever the given event sequence occurs. (See the Tk::callbacks manpage for description of the possible forms.) Callback will be associated with the same MainWindow that is associated with the $widget that was used to invoke the bind method, and it will run as though called from MainLoop. If callback contains any Ev(%) calls, then each "nested" Ev(%) "callback" will be evaluated when the event occurs to form arguments to be passed to the main callback. The replacement depends on the character %, as defined in the list below. Unless otherwise indicated, the replacement string is the numeric (decimal) value of the given field from the current event. Perl/Tk has enhanced this mechanism slightly compared to the comparable Tcl/Tk mechanism. The enhancements are not yet all reflected in the list below. Some of the substitutions are only valid for certain types of events; if they are used for other types of events the value substituted is undefined (not the same as undef!).

'#'

The number of the last client request processed by the server (the serial field from the event). Valid for all event types.

'a'

The above field from the event, formatted as a hexadecimal number. Valid only for Configure events.

'b'

The number of the button that was pressed or released. Valid only for ButtonPress and ButtonRelease events.

'c'

The count field from the event. Valid only for Expose events.

'd'

The detail field from the event. The 'd' is replaced by a string identifying the detail. For Enter, Leave, FocusIn, and FocusOut events, the string will be one of the following:

 NotifyAncestor          NotifyNonlinearVirtual
 NotifyDetailNone        NotifyPointer
 NotifyInferior          NotifyPointerRoot
 NotifyNonlinear         NotifyVirtual

For ConfigureRequest events, the string will be one of:

 Above                   Opposite
 Below                   None
 BottomIf                TopIf

For events other than these, the substituted string is undefined. (Note that this is not the same as Detail part of sequence use to specify the event.)

'f'

The focus field from the event (0 or 1). Valid only for Enter and Leave events.

'h'

The height field from the event. Valid only for Configure, ConfigureRequest, Create, Expose, and ResizeRequest events.

'i'

The window field from the event, represented as a hexadecimal integer.

'k'

The keycode field from the event. Valid only for KeyPress and KeyRelease events.

'm'

The mode field from the event. The substituted string is one of NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed. Valid only for Enter, FocusIn, FocusOut, and Leave events.

'o'

The override_redirect field from the event. Valid only for Map, Reparent, and Configure events.

'p'

The place field from the event, substituted as one of the strings PlaceOnTop or PlaceOnBottom. Valid only for Circulate and CirculateRequest events.

's'

The state field from the event. For ButtonPress, ButtonRelease, Enter, KeyPress, KeyRelease, Leave, and Motion events, a decimal string is substituted. For Visibility, one of the strings VisibilityUnobscured, VisibilityPartiallyObscured, and VisibilityFullyObscured is substituted.

't'

The time field from the event. Valid only for events that contain a time field.

'w'

The width field from the event. Valid only for Configure, ConfigueRequest, Create, Expose, and ResizeREquest events.

'x'

The x field from the event. Valid only for events containing an x field.

'y'

The y field from the event. Valid only for events containing a y field.

'@'

The string "@x,y" where x and y are as above. Valid only for events containing x and y fields. This format is used my methods of Tk::Text and similar widgets.

'A'

Substitutes the UNICODE character corresponding to the event, or the empty string if the event doesn't correspond to a UNICODE character (e.g. the shift key was pressed). XmbLookupString does all the work of translating from the event to a UNICODE character. Valid only for KeyPress and KeyRelease events.

'B'

The border_width field from the event. Valid only for Configure, ConfigureRequest and Create events.

'D'

This reports the delta value of a MouseWheel event. The delta value represents the rotation units the mouse wheel has been moved. On Windows 95 & 98 systems the smallest value for the delta is 120. Future systems may support higher resolution values for the delta. The sign of the value represents the direction the mouse wheel was scrolled.

'E'

The send_event field from the event. Valid for all event types.

'K'

The keysym corresponding to the event, substituted as a textual string. Valid only for KeyPress and KeyRelease events.

'N'

The keysym corresponding to the event, substituted as a decimal number. Valid only for KeyPress and KeyRelease events.

'R'

The root window identifier from the event. Valid only for events containing a root field.

'S'

The subwindow window identifier from the event, as an object if it is one otherwise as a hexadecimal number. Valid only for events containing a subwindow field.

'T'

The type field from the event. Valid for all event types.

'W'

The window to which the event was reported (the $widget field from the event) - as an perl/Tk object. Valid for all event types.

'X'

The x_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding x-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion events.

'Y'

The y_root field from the event. If a virtual-root window manager is being used then the substituted value is the corresponding y-coordinate in the virtual root. Valid only for ButtonPress, ButtonRelease, KeyPress, KeyRelease, and Motion events.

MULTIPLE MATCHES

It is possible for several bindings to match a given X event. If the bindings are associated with different tag's, then each of the bindings will be executed, in order. By default, a class binding will be executed first, followed by a binding for the widget, a binding for its toplevel, and an all binding. The bindtags method may be used to change this order for a particular window or to associate additional binding tags with the window.

return and Tk->break may be used inside a callback to control the processing of matching callbacks. If return is invoked, then the current callback is terminated but Tk will continue processing callbacks associated with other tag's. If Tk->break is invoked within a callback, then that callback terminates and no other callbacks will be invoked for the event. (Tk->break is implemented via perl's die with a special value which is "caught" by the perl/Tk "glue" code.)

If more than one binding matches a particular event and they have the same tag, then the most specific binding is chosen and its callback is evaluated. The following tests are applied, in order, to determine which of several matching sequences is more specific: (a) an event pattern that specifies a specific button or key is more specific than one that doesn't; (b) a longer sequence (in terms of number of events matched) is more specific than a shorter sequence; (c) if the modifiers specified in one pattern are a subset of the modifiers in another pattern, then the pattern with more modifiers is more specific. (d) a virtual event whose physical pattern matches the sequence is less specific than the same physical pattern that is not associated with a virtual event. (e) given a sequence that matches two or more virtual events, one of the virtual events will be chosen, but the order is undefined.

If the matching sequences contain more than one event, then tests (c)-(e) are applied in order from the most recent event to the least recent event in the sequences. If these tests fail to determine a winner, then the most recently registered sequence is the winner.

If there are two (or more) virtual events that are both triggered by the same sequence, and both of those virtual events are bound to the same window tag, then only one of the virtual events will be triggered, and it will be picked at random:

 $widget->eventAdd('<<Paste>>' => '<Control-y>');
 $widget->eventAdd('<<Paste>>' => '<Button-2>');
 $widget->eventAdd <<Scroll>>' => '<Button-2>');
 $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'});
 $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'});

If the user types Control-y, the <<Paste>> binding will be invoked, but if the user presses button 2 then one of either the <<Paste>> or the <<Scroll>> bindings will be invoked, but exactly which one gets invoked is undefined.

If an X event does not match any of the existing bindings, then the event is ignored. An unbound event is not considered to be an error.

MULTI-EVENT SEQUENCES AND IGNORED EVENTS

When a sequence specified in a bind method contains more than one event pattern, then its callback is executed whenever the recent events (leading up to and including the current event) match the given sequence. This means, for example, that if button 1 is clicked repeatedly the sequence <Double-ButtonPress-1> will match each button press but the first. If extraneous events that would prevent a match occur in the middle of an event sequence then the extraneous events are ignored unless they are KeyPress or ButtonPress events. For example, <Double-ButtonPress-1> will match a sequence of presses of button 1, even though there will be ButtonRelease events (and possibly Motion events) between the ButtonPress events. Furthermore, a KeyPress event may be preceded by any number of other KeyPress events for modifier keys without the modifier keys preventing a match. For example, the event sequence aB will match a press of the a key, a release of the a key, a press of the Shift key, and a press of the b key: the press of Shift is ignored because it is a modifier key. Finally, if several Motion events occur in a row, only the last one is used for purposes of matching binding sequences.

ERRORS

If an error occurs in executing the callback for a binding then the Tk::Error mechanism is used to report the error. The Tk::Error mechanism will be executed at same call level, and associated with the same MainWindow as as the callback was invoked.

CAVEATS

Note that for the Canvas widget, the call to bind has to be fully qualified. This is because there is already a bind method for the Canvas widget, which binds individual canvas tags.

$canvas->Tk::bind

SEE ALSO

Tk::Error
Tk::callbacks
Tk::bindtags

KEYWORDS

Event, binding


Tk::bindtags - Determine which bindings apply to a window, and order of evaluation

  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::bindtags - Determine which bindings apply to a window, and order of evaluation

SYNOPSIS

$widget->bindtags([tagList]); @tags = $widget->bindtags;

DESCRIPTION

When a binding is created with the bind command, it is associated either with a particular window such as $widget, a class name such as Tk::Button, the keyword all, or any other string. All of these forms are called binding tags. Each window has a list of binding tags that determine how events are processed for the window. When an event occurs in a window, it is applied to each of the window's tags in order: for each tag, the most specific binding that matches the given tag and event is executed. See the the Tk::bind manpage documentation for more information on the matching process.

By default, each window has four binding tags consisting of the the window's class name, name of the window, the name of the window's nearest toplevel ancestor, and all, in that order. Toplevel windows have only three tags by default, since the toplevel name is the same as that of the window.

Note that this order is different from order used by Tcl/Tk. Tcl/Tk has the window ahead of the class name in the binding order. This is because Tcl is procedural rather than object oriented and the normal way for Tcl/Tk applications to override class bindings is with an instance binding. However, with perl/Tk the normal way to override a class binding is to derive a class. The perl/Tk order causes instance bindings to execute after the class binding, and so instance bind callbacks can make use of state changes (e.g. changes to the selection) than the class bindings have made.

The bindtags command allows the binding tags for a window to be read and modified.

If $widget->bindtags is invoked without an argument, then the current set of binding tags for $widget is returned as a list. If the tagList argument is specified to bindtags, then it must be a reference to and array; the tags for $widget are changed to the elements of the array. (A reference to an anonymous array can be created by enclosin the elements in [ ].) The elements of tagList may be arbitrary strings or widget objects, if no window exists for an object at the time an event is processed, then the tag is ignored for that event. The order of the elements in tagList determines the order in which binding callbacks are executed in response to events. For example, the command

 $b->bindtags([$b,ref($b),$b->toplevel,'all'])

applies the Tcl/Tk binding order which binding callbacks will be evaluated for a button (say) $b so that $b's instance bindings are invoked first, following by bindings for $b's class, followed by bindings for $b's toplevel, followed by 'all' bindings.

If tagList is an empty list i.e. [], then the binding tags for $widget are returned to the perl/Tk default state described above.

The bindtags command may be used to introduce arbitrary additional binding tags for a window, or to remove standard tags. For example, the command

 $b->bindtags(['TrickyButton',$b->toplevel,'all'])

replaces the (say) Tk::Button tag for $b with TrickyButton. This means that the default widget bindings for buttons, which are associated with the Tk::Button tag, will no longer apply to $b, but any bindings associated with TrickyButton (perhaps some new button behavior) will apply.

BUGS

The current mapping of the 'native' Tk behaviour of this method i.e. returning a list but only accepting a reference to an array is counter intuitive. The perl/Tk interface may be tidied up, returning a list is sensible so, most likely fix will be to allow a list to be passed to /fIset/fR the bindtags.

SEE ALSO

Tk::bind Tk::callbacks

KEYWORDS

binding, event, tag


Tk::callbacks - Specifying code for Tk to call.

  • EXAMPLES
  • SEE ALSO
  • KEYWORDS

NAME

Tk::callbacks - Specifying code for Tk to call.

SYNOPSIS

One can specify a callback in one of the following ways:

Without arguments:

    ... => \&subname, ...
    ... => sub { ... }, ...
    ... => 'methodname', ...

or with arguments:

    ... => [ \&subname ?, args ...? ], ...
    ... => [ sub { ... } ?, args...? ], ...
    ... => [ 'methodname' ?, args...?], ...

DESCRIPTION

Perl/Tk has a callback, where Tcl/Tk has a command string (i.e. a fragment of Tcl to be executed). A perl/Tk callback can take one of the following basic forms:

  • Reference to a subroutine \&subname
  • Anonymous subroutine (closure) sub { ... }
  • A method name 'methodname'

Any of these can be provided with arguments by enclosing them and the arguments in []. Here are some examples:

$mw->bind($class, "<Delete>" => 'Delete');

This will call $widget->Delete, the $widget being provided (by bind) as the one where the Delete key was pressed.

While having bind provide a widget object for you is ideal in many cases it can be irritating in others. Using the list form this behaviour can be modified:

$a->bind("<Delete>",[$b => 'Delete']);

because the first element $b is an object bind will call $b->Delete.

Note that method/object ordering only matters for bind callbacks, the auto-quoting in perl5.001 makes the first of these a little more readable:

$w->configure(-yscrollcommand => [ set => $ysb]);

$w->configure(-yscrollcommand => [ $ysb => 'set' ]);

but both will call $ysb->set(args provided by Tk)

Another use of arguments allows you to write generalized methods which are easier to re-use:

$a->bind("<Next>",['Next','Page']);

$a->bind("<Down>",['Next','Line']);

This will call $a->Next('Page') or $a->Next('Line') respectively.

Note that the contents of the [] are evaluated by perl when the callback is created. It is often desirable for the arguments provided to the callback to depend on the details of the event which caused it to be executed. To allow for this callbacks can be nested using the Ev(...) "constructor". Ev(...) inserts callback objects into the argument list. When perl/Tk glue code is preparing the argument list for the callback it is about to call it spots these special objects and recursively applies the callback process to them.

EXAMPLES

    $entry->bind('<Return>' => [$w , 'validate', Ev(['get'])]);

    $toplevel->bind('all', '<Visibility>', [\&unobscure, Ev('s')]);

    $mw->bind($class, '<Down>', ['SetCursor', Ev('UpDownLine',1)]);

SEE ALSO

Tk::bind
Tk::after
Tk::options
Tk::fileevent

KEYWORDS

callback, closure, anonymous subroutine, bind


chooseColor - pops up a dialog box for the user to select a color.

  • EXAMPLE
  • KEYWORDS

NAME

chooseColor - pops up a dialog box for the user to select a color.

SYNOPSIS

$color = $widget->chooseColor?(-option=>value, ...)?;

DESCRIPTION

The method chooseColor is implemented as a perl wrapper on the core tk "command" tk_chooseColor, and $widget is passed as the argument to the hidden -parent option. The implementation of internal tk_chooseColor is platform specific, on Win32 it is a native dialog, and on UNIX/X it is implemented in terms of Tk::ColorEditor.

The chooseColor method pops up a dialog box for the user to select a color. The following option-value pairs are possible as command line arguments:

-initialcolor=>color

Specifies the color to display in the color dialog when it pops up. color must be in a form acceptable to the Tk_GetColor function.

-parent=>$widget

Makes $widget the logical parent of the color dialog. The color dialog is displayed on top of its parent window.

-title=>titleString

Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed.

If the user selects a color, tk_chooseColor will return the name of the color in a form acceptable to Tk_GetColor. If the user cancels the operation, the command will return undef.

EXAMPLE

 $widget->configure(-fg => $parent->chooseColor(-initialcolor => 'gray',
                 -title => "Choose color"));

KEYWORDS

color selection dialog


chooseDirectory - pops up a dialog box for the user to select a directory.

  • SEE ALSO
  • KEYWORDS

NAME

chooseDirectory - pops up a dialog box for the user to select a directory.

SYNOPSIS

$widget->chooseDirectory( ?option value ...? );

DESCRIPTION

The method chooseDirectory is implemented as a perl wrapper on the core tk "command" tk_chooseDirectory, and $widget is passed as the argument to the hidden -parent option.

The chooseDirectory method pops up a dialog box for the user to select a directory. The following option-value pairs are possible as command line arguments:

-initialdir dirname

Specifies that the directories in directory should be displayed when the dialog pops up. If this parameter is not specified, then the directories in the current working directory are displayed. If the parameter specifies a relative path, the return value will convert the relative path to an absolute path. This option may not always work on the Macintosh. This is not a bug. Rather, the General Controls control panel on the Mac allows the end user to override the application default directory.

-parent $widget

Makes $widget the logical parent of the dialog. The dialog is displayed on top of its parent window.

-title titleString

Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed.

-mustexist boolean

Specifies whether the user may specify non-existant directories. If this parameter is true, then the user may only select directories that already exist. The default value is false.

SEE ALSO

the Tk::getOpenFile manpage, the Tk::getOpenFile manpage

KEYWORDS

directory selection dialog


Tk::composite - Defining a new composite widget class

  • GLORY DETAILS
    • Composite Widget
    • Creating Subwidgets
    • Defining mega-widget options
  • SEE ALSO

NAME

Tk::composite - Defining a new composite widget class

SYNOPSIS

    package Tk::MyNewWidget;

    use Tk:widgets qw/ list of Tk widgets /;
    use base qw/ Tk::Frame /;    # or Tk::Toplevel

    Construct Tk::Widget 'MyNewWidget';

    sub ClassInit {
        my( $class, $mw ) = @_;
        #... e.g., class bindings here ...
        $class->SUPER::ClassInit( $mw );
    }

    sub Populate {
        my( $self, $args ) = @_;

        my $flag = delete $args->{-flag};
        if( defined $flag ) {
            # handle -flag => xxx which can only be done at create
            # time the delete above ensures that new() does not try
            # and do  $self->configure( -flag => xxx );
        }

        $self->SUPER::Populate( $args );

        $self = $self->Component( ... );

        $self->Delegates( ... );

        $self->ConfigSpecs(
            '-cursor'    => [ SELF, 'cursor', 'Cursor',   undef ],
            '-something' => [ METHOD, dbName,  dbClass, default ],
            '-text'      => [ $label, dbName,  dbClass, default ],
            '-heading'   => [ {-text => $head},
                                heading, Heading,  'My Heading' ],
               );
           }

   sub something {
       my( $self, $value) = @_;
       if ( @_ > 1 ) {
          # set it
       }
       return # current value
   }

   1;

   __END__
   =head1 NAME
   Tk::Whatever - a whatever widget
   =head1 SYNOPSIS
     use Tk::Whatever;

     $widget = $parent->Whatever(...);

   =head1 DESCRIPTION
   ...

DESCRIPTION

The intention behind a composite is to create a higher-level widget, sometimes called a "super-widget" or "mega-widget". Most often, a composite will be built upon other widgets by using them, as opposed to specializing on them. For example, the supplied composite widget LabEntry is made of an Entry and a Label; it is neither a kind-of Label nor is it a kind-of Entry.

Most of the work of a composite widget consistd in creating subwidgets, arranging to dispatch configure options to the proper subwidgets and manage composite-specific configure options.

GLORY DETAILS

Depending on your Perl/Tk knowledge this section may be enlighting or confusing.

Composite Widget

Since Perl/Tk is heavilly using an object-oriented approach, it is no suprise that creating a composite goes through a new() method. However, the composite does not normally define a new() method itself: it is usually sufficient to simply inherit it from Tk::Widget.

This is what happens when the composite uses

    use base qw/ Tk::Frame /;  # or Tk::Toplevel

to specify its inheritance chain. To complete the initialisation of the widget, it must call the Construct method from class Widget. That method accepts the name of the new class to create, i.e. the package name of your composite widget:

    Construct Tk::Widget 'MyNewWidget';

Here, MyNewWidget is the package name (aka the widget's class). This will define a constructor method for MyNewWidget, normally named after the widget's class. Instanciating that composite in client code would the look like:

    $mw = MainWindow->new;       # creates a top-level MainWindow

    $self = $mw->MyNewWidget();  # creates an instance of the
                                 # composite widget MyNewWidget

Whenever a composite is instanciated in client code, Tk::Widget::new() will be invoked via the widget's class constructor. That new method will call

    $self->Populate(\%args);

where %args is the arguments passed to the widget's constructor. Note that Populate receives a reference to the hash array containing all arguments.

Populate is typically defined in the composite class (package), which creates the characteristic subwidgets of the class.

Creating Subwidgets

Subwidget creation happens usually in Populate(). The composite usually calls the subwidget's constructor method either directly, for "private" subwidgets, or indirectly through the Component method for subwidgets that should be advertised to clients.

Populate may call Delegates to direct calls to methods of chosen subwidgets. For simple composites, typically most if not all methods are directed to a single subwidget - e.g. ScrListbox directs all methods to the core Listbox so that $composite->get(...) calls $listbox->get(...).

Defining mega-widget options

Populate should also call ConfigSpecs() to specify the way that configure-like options should be handled in the composite. Once Populate returns, method Tk::Frame::ConfigDefault walks through the ConfigSpecs entries and populates %$args hash with defaults for options from X resources (.Xdefaults, etc).

When Populate returns to Tk::Widget::new(), a call to $self->configure(%$args) is made which sets *all* the options.

SEE ALSO

Tk::ConfigSpecs
Tk::mega
Tk::Derived


Tk::SlideSwitch - a 2 position horizontal or vertical switch.

  • OPTIONS
  • METHODS
  • ADVERTISED WIDGETS
  • EXAMPLE
  • BUGS
  • AUTHOR
  • KEYWORDS

NAME

Tk::SlideSwitch - a 2 position horizontal or vertical switch.

SYNOPSIS

 use Tk::SlideSwitch;

 my $sl = $frame1->SlideSwitch(
     -bg          => 'gray',
     -orient      => 'horizontal',
     -command     => [$self => 'on'],
     -llabel      => [-text => 'OFF', -foreground => 'blue'],
     -rlabel      => [-text => 'ON',  -foreground => 'blue'],
     -troughcolor => 'tan',
 )->pack(qw/-side left -expand 1/);

DESCRIPTION

Tk::SlideSwitch is a Frame based composite mega-widget featuring a binary Scale widget surrounded by two Label widgets. The Scale's value can be either 0 or 1. The Labels are positioned to the left and right of the Scale if its orientation is horizontal, else on the top and bottom of the Scale.

OPTIONS

In addition to all Scale options, the following option/value pairs are also supported:

-llabel

A reference to an array of left (or top) Label configuration options.

-rlabel

A reference to an array of right (or bottom) Label configuration options.

METHODS

There are no special methods.

ADVERTISED WIDGETS

Component subwidgets can be accessed via the Subwidget method. This mega widget has no advertised subwidgets.

EXAMPLE

See Synopsis.

BUGS

This widget uses only the pack geometry manager.

AUTHOR

sol0@Lehigh.EDU

Copyright (C) 2002 - 2003, Steve Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

KEYWORDS

SlideSwitch, Scale


Tk::TraceText - Text contents defined by a traced variable.

  • METHODS
  • ADVERTISED SUBWIDGETS
  • EXAMPLE
  • AUTHOR
  • KEYWORDS

NAME

Tk::TraceText - Text contents defined by a traced variable.

SYNOPSIS

 $tt = $parent->TraceText(-option => value, ... );

DESCRIPTION

Create a new TraceText widget that is derived from the standard Text widget. Because it inherits all the base options and methods it behaves just like a Text widget. Additionally, TraceText adds a -textvariable option, which is a reference to a Perl scalar that defines the contents of the widget.

Based on the Tcl/Tk TracedText "overridden widget" by Kevin Kenny.

-textvariable

A scalar reference. The value of the variable defines the contents of the TraceText widget. Using the keyboard to insert or delete text changes the value of the variable, and changing the variable alters the contents of the TraceText widget.

METHODS

Standard Text widget methods.

ADVERTISED SUBWIDGETS

None.

EXAMPLE

 my $tt = $mw->TraceText( -textvariable => \$scalar );

AUTHOR

Stephen.O.Lidie@Lehigh.EDU

Copyright (C) 2003 - 2004, Steve Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

KEYWORDS

text, trace


Tk::event - Miscellaneous event facilities: define virtual events and generate events

  • EVENT FIELDS
  • VIRTUAL EVENT EXAMPLES
  • SEE ALSO
  • KEYWORDS

NAME

Tk::event - Miscellaneous event facilities: define virtual events and generate events

SYNOPSIS

$widget->event Action(?arg, arg, ...?);

DESCRIPTION

The event Action methods provides several facilities for dealing with window system events, such as defining virtual events and synthesizing events. Virtual events are shared by all widgets of the same MainWindow. Different MainWindows can have different virtual event.

The following methods are currently supported:

$widget->eventAdd('<<virtual>>', sequence ?,sequence, ...?)

Associates the virtual event virtual with the physical event sequence(s) given by the sequence arguments, so that the virtual event will trigger whenever any one of the sequences occurs. Virtual may be any string value and sequence may have any of the values allowed for the sequence argument to the bind method. If virtual is already defined, the new physical event sequences add to the existing sequences for the event.

$widget->eventDelete('<<virtual>>' ?,sequence, sequence, ...?)

Deletes each of the sequences from those associated with the virtual event given by virtual. Virtual may be any string value and sequence may have any of the values allowed for the sequence argument to the bind method. Any sequences not currently associated with virtual are ignored. If no sequence argument is provided, all physical event sequences are removed for virtual, so that the virtual event will not trigger anymore.

$widget->eventGenerate(event ?,option => value, option => value, ...?)

Generates a window event and arranges for it to be processed just as if it had come from the window system. $window is a reference to the window for which the event will be generated. Event provides a basic description of the event, such as <Shift-Button-2> or <<Paste>>. If Window is empty the whole screen is meant, and coordinates are relative to the screen. Event may have any of the forms allowed for the sequence argument of the bind method except that it must consist of a single event pattern, not a sequence. Option-value pairs may be used to specify additional attributes of the event, such as the x and y mouse position; see EVENT FIELDS below. If the -when option is not specified, the event is processed immediately: all of the handlers for the event will complete before the eventGenerate method returns. If the -when option is specified then it determines when the event is processed.

$widget->eventInfo(?'<<virtual>>'?)

Returns information about virtual events. If the <<virtual>> argument is omitted, the return value is a list of all the virtual events that are currently defined. If <<virtual>> is specified then the return value is a list whose elements are the physical event sequences currently defined for the given virtual event; if the virtual event is not defined then undef is returned.

EVENT FIELDS

The following options are supported for the eventGenerate method. These correspond to the ``%'' expansions allowed in binding callback for the bind method.

-above => window

Window specifies the above field for the event, either as a window path name or as an integer window id. Valid for Configure events. Corresponds to the %a substitution for binding scripts.

-borderwidth => size

Size must be a screen distance; it specifies the border_width field for the event. Valid for Configure events. Corresponds to the %B substitution for binding scripts.

-button => number

Number must be an integer; it specifies the detail field for a ButtonPress or ButtonRelease event, overriding any button number provided in the base event argument. Corresponds to the %b substitution for binding scripts.

-count => number

Number must be an integer; it specifies the count field for the event. Valid for Expose events. Corresponds to the %c substitution for binding scripts.

-delta => number

number must be an integer; it specifies the delta field for the MouseWheel event. The delta refers to the direction and magnitude the mouse wheel was rotated. Note the value is not a screen distance but are units of motion in the mouse wheel. Typically these values are multiples of 120. For example, 120 should scroll the text widget up 4 lines and -240 would scroll the text widget down 8 lines. Of course, other widgets may define different behaviors for mouse wheel motion. This field corresponds to the %D substitution for binding scripts.

-detail => detail

Detail specifies the detail field for the event and must be one of the following:

 NotifyAncestor         NotifyNonlinearVirtual
 NotifyDetailNone       NotifyPointer
 NotifyInferior         NotifyPointerRoot
 NotifyNonlinear        NotifyVirtual

Valid for Enter, Leave, FocusIn and FocusOut events. Corresponds to the %d substitution for binding scripts.

-focus boolean

Boolean must be a boolean value; it specifies the focus field for the event. Valid for Enter and Leave events. Corresponds to the %f substitution for binding scripts.

-height size

Size must be a screen distance; it specifies the height field for the event. Valid for Configure events. Corresponds to the %h substitution for binding scripts.

-keycode number

Number must be an integer; it specifies the keycode field for the event. Valid for KeyPress and KeyRelease events. Corresponds to the %k substitution for binding scripts.

-keysym name

Name must be the name of a valid keysym, such as g, space, or Return; its corresponding keycode value is used as the keycode field for event, overriding any detail specified in the base event argument. Valid for KeyPress and KeyRelease events. Corresponds to the %K substitution for binding scripts.

-mode notify

Notify specifies the mode field for the event and must be one of NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed. Valid for Enter, Leave, FocusIn, and FocusOut events. Corresponds to the %m substitution for binding scripts.

-override boolean

Boolean must be a boolean value; it specifies the override_redirect field for the event. Valid for Map, Reparent, and Configure events. Corresponds to the %o substitution for binding scripts.

-place where

Where specifies the place field for the event; it must be either PlaceOnTop or PlaceOnBottom. Valid for Circulate events. Corresponds to the %p substitution for binding scripts.

-root window

Window must be either a window path name or an integer window identifier; it specifies the root field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion events. Corresponds to the %R substitution for binding scripts.

-rootx coord

Coord must be a screen distance; it specifies the x_root field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion events. Corresponds to the %X substitution for binding scripts.

-rooty coord

Coord must be a screen distance; it specifies the y_root field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion events. Corresponds to the %Y substitution for binding scripts.

-sendevent boolean

Boolean must be a boolean value; it specifies the send_event field for the event. Valid for all events. Corresponds to the %E substitution for binding scripts.

-serial number

Number must be an integer; it specifies the serial field for the event. Valid for all events. Corresponds to the %# substitution for binding scripts.

-state state

State specifies the state field for the event. For KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion events it must be an integer value. For Visibility events it must be one of VisibilityUnobscured, VisibilityPartiallyObscured, or VisibilityFullyObscured. This option overrides any modifiers such as Meta or Control specified in the base event. Corresponds to the %s substitution for binding scripts.

-subwindow window

Window specifies the subwindow field for the event, either as a path name for a Tk widget or as an integer window identifier. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and Motion events. Similar to %S substitution for binding scripts.

-time integer

Integer must be an integer value; it specifies the time field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, Motion, and Property events. Corresponds to the %t substitution for binding scripts.

-warp boolean

boolean must be a boolean value; it specifies whether the screen pointer should be warped as well. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, and Motion events.

-width size

Size must be a screen distance; it specifies the width field for the event. Valid for Configure events. Corresponds to the %w substitution for binding scripts.

-when when

When determines when the event will be processed; it must have one of the following values:

now

Process the event immediately, before the command returns. This also happens if the -when option is omitted.

tail

Place the event on perl/Tk's event queue behind any events already queued for this application.

head

Place the event at the front of perl/Tk's event queue, so that it will be handled before any other events already queued.

mark

Place the event at the front of perl/Tk's event queue but behind any other events already queued with -when mark. This option is useful when generating a series of events that should be processed in order but at the front of the queue.

-x coord

Coord must be a screen distance; it specifies the x field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Motion, Enter, Leave, Expose, Configure, Gravity, and Reparent events. Corresponds to the the %x substitution for binding scripts. If Window is empty the coordinate is relative to the screen, and this option corresponds to the %X substitution for binding scripts.

-y coord

Coord must be a screen distance; it specifies the y field for the event. Valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, Motion, Enter, Leave, Expose, Configure, Gravity, and Reparent events. Corresponds to the the %y substitution for binding scripts. If Window is empty the coordinate is relative to the screen, and this option corresponds to the %Y substitution for binding scripts.

Any options that are not specified when generating an event are filled with the value 0, except for serial, which is filled with the next X event serial number.

VIRTUAL EVENT EXAMPLES

In order for a virtual event binding to trigger, two things must happen. First, the virtual event must be defined with the eventAdd method. Second, a binding must be created for the virtual event with the bind method. Consider the following virtual event definitions:

 $widget->eventAdd('<<Paste>>' => '<Control-y>');
 $widget->eventAdd('<<Paste>>' => '<Button-2>');
 $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>');
 $widget->eventAdd('<<Save>>' => '<Shift-F12>');

In the bind method, a virtual event can be bound like any other builtin event type as follows:

 $entry->bind('Tk::Entry', '<<Paste>>' => sub {
                $entry->Insert($entry->selectionGet) });

The double angle brackets are used to specify that a virtual event is being bound. If the user types Control-y or presses button 2, or if a <<Paste>> virtual event is synthesized with eventGenerate, then the <<Paste>> binding will be invoked.

If a virtual binding has the exact same sequence as a separate physical binding, then the physical binding will take precedence. Consider the following example:

 $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>');
 $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'});
 $mw->bind('Tk::Entry', '<<Paste>>'   => sub{print 'Paste'});

When the user types Control-y the <Control-y> binding will be invoked, because a physical event is considered more specific than a virtual event, all other things being equal. However, when the user types Meta-Control-y the <<Paste>> binding will be invoked, because the Meta modifier in the physical pattern associated with the virtual binding is more specific than the <Control-y> sequence for the physical event.

Bindings on a virtual event may be created before the virtual event exists. Indeed, the virtual event never actually needs to be defined, for instance, on platforms where the specific virtual event would meaningless or ungeneratable.

When a definition of a virtual event changes at run time, all windows will respond immediately to the new definition. Starting from the preceding example, if the following code is executed:

 $entry->bind(ref($entry), '<Control-y>' => undef);
 $entry->eventAdd('<<Paste>>' => '<Key-F6>');

the behavior will change such in two ways. First, the shadowed <<Paste>> binding will emerge. Typing Control-y will no longer invoke the <Control-y> binding, but instead invoke the virtual event <<Paste>>. Second, pressing the F6 key will now also invoke the <<Paste>> binding.

SEE ALSO

Tk::bind Tk::callbacks

KEYWORDS

event, binding, define, handle, virtual event


Tk::exit - End the application

  • KEYWORDS

NAME

Tk::exit - End the application

SYNOPSIS

    use Tk qw(exit);
    ...
    B<exit>?(I<returnCode>)?;

DESCRIPTION

Terminate the process, returning returnCode to the system as the exit status. If returnCode isn't specified then it defaults to 0.

If calling exit from code invoked via a Tk callback then this Tk version of exit cleans up more reliably than using the perl exit.

KEYWORDS

exit, process


Tk::fileevent - Execute a callback when a filehandle becomes readable or writable

  • BUGS
  • CREDITS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::fileevent - Execute a callback when a filehandle becomes readable or writable

SYNOPSIS

$widget->fileevent(fileHandle,readable?,callback?)

$widget->fileevent(fileHandle,writable?,callback?)

DESCRIPTION

This command is used to create file event handlers. A file event handler is a binding between a filehandle and a callback, such that the callback is evaluated whenever the filehandle becomes readable or writable. File event handlers are most commonly used to allow data to be received from another process on an event-driven basis, so that the receiver can continue to interact with the user while waiting for the data to arrive. If an application invokes <>, sysread or read on a blocking filehandle when there is no input data available, the process will block; until the input data arrives, it will not be able to service other events, so it will appear to the user to ``freeze up''. With fileevent, the process can tell when data is present and only invoke gets or read when they won't block.

The fileHandle argument to fileevent refers to an open filehandle, such as the return value from a previous open or socket command. If the callback argument is specified, then fileevent creates a new event handler: callback will be evaluated whenever the filehandle becomes readable or writable (depending on the argument to fileevent). In this case fileevent returns an empty string. The readable and writable event handlers for a file are independent, and may be created and deleted separately. However, there may be at most one readable and one writable handler for a file at a given time in a given interpreter. If fileevent is called when the specified handler already exists in the invoking interpreter, the new callback replaces the old one.

If the callback argument is not specified, fileevent returns the current callback for fileHandle, or an empty string if there is none. If the callback argument is specified as an empty string then the event handler is deleted, so that no callback will be invoked. A file event handler is also deleted automatically whenever its filehandle is closed or its interpreter is deleted.

A filehandle is considered to be readable if there is unread data available on the underlying device. A filehandle is also considered to be readable if an end of file or error condition is present on the underlying file or device. It is important for callback to check for these conditions and handle them appropriately; for example, if there is no special check for end of file, an infinite loop may occur where callback reads no data, returns, and is immediately invoked again.

A filehandle is considered to be writable if at least one byte of data can be written to the underlying file or device without blocking, or if an error condition is present on the underlying file or device.

Event-driven I/O works best for filehandles that have been placed into nonblocking mode. In blocking mode, a print command may block if you give it more data than the underlying file or device can accept, and a <>, sysread or read command will block if you attempt to read more data than is ready; no events will be processed while the commands block. In nonblocking mode print, <>, sysread and read never block. See the documentation for the individual commands for information on how they handle blocking and nonblocking filehandles.

The callback for a file event is executed in the context of $widget with which fileevent was invoked. If an error occurs while executing the callback then the the Tk::Error manpage mechanism is used to report the error. In addition, the file event handler is deleted if it ever returns an error; this is done in order to prevent infinite loops due to buggy handlers.

BUGS

On windows platforms fileevent is limited in the types of filehandles that behave correctly. Making filefhandles non-blocking is only implemented on a subset of UNIX platforms (see the Tk::IO manpage).

CREDITS

fileevent is based on the addinput command created by Mark Diekhans.

SEE ALSO

Tk::IO Tk::callbacks

KEYWORDS

asynchronous I/O, blocking, filehandle, event handler, nonblocking, readable, callback, writable.


focus - Manage the input focus

  • QUIRKS
  • CAVEATS
  • KEYWORDS

NAME

focus - Manage the input focus

SYNOPSIS

$widget->focus

$widget->focus Option

$widget->focusNext

$widget->focusPrev

$widget->focusFollowsMouse

DESCRIPTION

The focus methods are used to manage the Tk input focus. At any given time, one window on each display is designated as the focus window; any key press or key release events for the display are sent to that window. It is normally up to the window manager to redirect the focus among the top-level windows of a display. For example, some window managers automatically set the input focus to a top-level window whenever the mouse enters it; others redirect the input focus only when the user clicks on a window. Usually the window manager will set the focus only to top-level windows, leaving it up to the application to redirect the focus among the children of the top-level.

Tk remembers one focus window for each top-level (the most recent descendant of that top-level to receive the focus); when the window manager gives the focus to a top-level, Tk automatically redirects it to the remembered window. Within a top-level Tk uses an explicit focus model by default. Moving the mouse within a top-level does not normally change the focus; the focus changes only when a widget decides explicitly to claim the focus (e.g., because of a button click), or when the user types a key such as Tab that moves the focus.

The method focusFollowsMouse may be invoked to create an implicit focus model: it reconfigures Tk so that the focus is set to a window whenever the mouse enters it. The methods focusNext and focusPrev implement a focus order among the windows of a top-level; they are used in the default bindings for Tab and Shift-Tab, among other things.

The focus methods can take any of the following forms:

$widget->focusCurrent

Returns the focus window on the display containing the $widget, or an empty string if no window in this application has the focus on that display.

$widget->focus

If the application currently has the input focus on $widget's display, this command resets the input focus for $widget's display to $widget and returns an empty string. If the application doesn't currently have the input focus on $widget's display, $widget will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, Tk will redirect it to $widget.

$widget->focusForce

Sets the focus of $widget's display to $widget, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus.

$widget->focusLast

Returns the name of the most recent window to have the input focus among all the windows in the same top-level as $widget. If no window in that top-level has ever had the input focus, or if the most recent focus window has been deleted, then the top-level is returned. The return value is the window that will receive the input focus the next time the window manager gives the focus to the top-level.

$widget->focusNext
$widget->focusPrev

focusNext is a utility method used for keyboard traversal, but can be useful in other contexts. It sets the focus to the ``next'' window after $widget in focus order. The focus order is determined by the stacking order of windows and the structure of the window hierarchy. Among siblings, the focus order is the same as the stacking order, with the lowest window being first. If a window has children, the window is visited first, followed by its children (recursively), followed by its next sibling. Top-level windows other than $widget are skipped, so that focusNext never returns a window in a different top-level from $widget.

After computing the next window, focusNext examines the window's -takefocus option to see whether it should be skipped. If so, focusNext continues on to the next window in the focus order, until it eventually finds a window that will accept the focus or returns back to $widget.

focusPrev is similar to focusNext except that it sets the focus to the window just before $widget in the focus order.

$widget->focusFollowsMouse

focusFollowsMouse changes the focus model for the application to an implicit one where the window under the mouse gets the focus. After this procedure is called, whenever the mouse enters a window Tk will automatically give it the input focus. The focus command may be used to move the focus to a window other than the one under the mouse, but as soon as the mouse moves into a new window the focus will jump to that window. Note: at present there is no built-in support for returning the application to an explicit focus model; to do this you'll have to write a script that deletes the bindings created by focusFollowsMouse.

QUIRKS

When an internal window receives the input focus, Tk doesn't actually set the X focus to that window; as far as X is concerned, the focus will stay on the top-level window containing the window with the focus. However, Tk generates FocusIn and FocusOut events just as if the X focus were on the internal window. This approach gets around a number of problems that would occur if the X focus were actually moved; the fact that the X focus is on the top-level is invisible unless you use C code to query the X server directly.

CAVEATS

Note that for the Canvas widget, the call to focus has to be fully qualified. This is because there is already a focus method for the Canvas widget, which sets the focus on individual canvas tags.

$canvas->Tk::focus

KEYWORDS

events, focus, keyboard, top-level, window manager


Tk::form - Geometry manager based on attachment rules

  • SPECIFYING ATTACHMENTS
    • ABBREVIATIONS:
  • USING SPRINGS
  • ALGORITHM OF FORM
  • CIRCULAR DEPENDENCY
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::form - Geometry manager based on attachment rules

SYNOPSIS

$widget->form?(args)?

$widget->form Option?(args)?

DESCRIPTION

The form method is used to communicate with the form Geometry Manager, a geometry manager that arranges the geometry of the children in a parent window according to attachment rules. The form geometry manager is very flexible and powerful; it can be used to emulate all the existing features of the Tk packer and placer geometry managers (see pack, place). The form method can have any of several forms, depending on Option:

$slave->form?(options)?

Sets or adjusts the attachment values of the slave window according to the -option=>value argument pairs.

-b => attachment

Abbreviation for the -bottom option.

-bottom => attachment

Specifies an attachment for the bottom edge of the slave window. The attachment must specified according to SPECIFYING ATTACHMENTS below.

-bottomspring => weight

Specifies the weight of the spring at the bottom edge of the slave window. See USING SPRINGS below.

-bp => value

Abbreviation for the -padbottom option.

-bs => weight

Abbreviation for the -bottomspring option.

-fill => style

Specifies the fillings when springs are used for this widget. The value must be x, y, both or none.

-in => $master

Places the slave window into the specified $master window. If the slave was originally in another master window, all attachment values with respect to the original master window are discarded. Even if the attachment values are the same as in the original master window, they need to be specified again. The -in flag, when needed, must appear as the first flag of options. Otherwise an error is generated.

-l => attachment

Abbreviation for the -left option.

-left => attachment

Specifies an attachment for the left edge of the slave window. The attachment must specified according to SPECIFYING ATTACHMENTS below.

-leftspring => weight

Specifies the weight of the spring at the left edge of the slave window. See USING SPRINGS below.

-lp => value

Abbreviation for the -padleft option.

-ls => weight

Abbreviation for the -leftspring option.

-padbottom => value

Specifies the amount of external padding to leave on the bottom side of the slave. The value may have any of the forms acceptable to Tk_GetPixels.

-padleft => value

Specifies the amount of external padding to leave on the left side of the slave.

-padright => value

Specifies the amount of external padding to leave on the right side of the slave.

-padtop => value

Specifies the amount of external padding to leave on the top side of the slave.

-padx => value

Specifies the amount of external padding to leave on both the left and the right sides of the slave.

-pady => value

Specifies the amount of external padding to leave on both the top and the bottom sides of the slave.

-r => attachment

Abbreviation for the -right option.

-right => attachment

Specifies an attachment for the right edge of the slave window. The attachment must specified according to SPECIFYING ATTACHMENTS below.

-rightspring => weight

Specifies the weight of the spring at the right edge of the slave window. See USING SPRINGS below.

-rp => value

Abbreviation for the -padright option.

-rs => weight

Abbreviation for the -rightspring option.

-t => attachment

Abbreviation for the -top option.

-top => attachment

Specifies an attachment for the top edge of the slave window. The attachment must specified according to SPECIFYING ATTACHMENTS below.

-topspring => weight

Specifies the weight of the spring at the top edge of the slave window. See USING SPRINGS below.

-tp => value

Abbreviation for the -padtop option.

-ts => weight

Abbreviation for the -topspring option.

$master->formCheck

This method checks whether there is circular dependency in the attachments of the master's slaves (see CIRCULAR DEPENDENCY below). It returns the Boolean value TRUE if it discover circular dependency and FALSE otherwise.

$slave->formForget

Removes the slave from its master and unmaps its window. The slave will no longer be managed by form. All attachment values with respect to its master window are discarded. If another slave is attached to this slave, then the attachment of the other slave will be changed to grid attachment based on its geometry.

$master->formGrid?(x_size, y_size)?

When x_size and y_size are given, this method returns the number of grids of the $master window in a pair of integers of the form (x_size, y_size). When both x_size and y_size are given, this method changes the number of horizontal and vertical grids on the master window.

$slave->formInfo?(-option)?

Queries the attachment options of a slave window. -option can be any of the options accepted by the form method. If -option is given, only the value of that option is returned. Otherwise, this method returns a list whose elements are the current configuration state of the slave given in the same option-value form that might be specified to form. The first two elements in this list list are "-in=>$master" where $master is the slave's master window.

$master->formSlaves

Returns a list of all of the slaves for the master window. The order of the slaves in the list is the same as their order in the packing order. If master has no slaves then an empty string is returned.

SPECIFYING ATTACHMENTS

One can specify an attachment for each side of a slave window managed by form. An attachment is specified in the the form "-side => [anchor_point, offset]". -side can be one of -top, -bottom, -left or -right.

Offset is given in screen units (i.e. any of the forms acceptable to Tk_GetPixels). A positive offset indicates shifting to a position to the right or bottom of an anchor point. A negative offset indicates shifting to a position to the left or top of an anchor point.

Anchor_point can be given in one of the following forms:

Grid Attachment

The master window is divided into a number of horizontal and vertical grids. By default the master window is divided into 100x100 grids; the number of grids can be adjusted by the formGrid method. A grid attachment anchor point is given by a % sign followed by an integer value. For example, '%0' specifies the first grid line (the top or left edge of the master window). '%100' specifies the last grid line (the bottom or right edge of the master window).

Opposite Side Attachment

Opposite attachment specifies an anchor point located on the opposite side of another slave widget, which must be managed by form in the same master window. An opposite attachment anchor point is given by the name of another widget. For example, "$b->form(-top=>[$a,0])" attaches the top side of the widget $b to the bottom of the widget $a.

Parallel Side Attachment

Opposite attachment specifies an anchor point located on the same side of another slave widget, which must be managed by form in the same master window. An parallel attachment anchor point is given by the sign & follwed by the name of another widget. For example, "$b->form(-top=>['&',$a,0])" attaches the top side of the widget $b to the top of the widget $a, making the top sides of these two widgets at the same vertical position in their parent window.

No Attachment

Specifies a side of the slave to be attached to nothing, indicated by the keyword none. When the none anchor point is given, the offset must be zero (or not present). When a side of a slave is attached to ['none', 0], the position of this side is calculated by the position of the other side and the natural size of the slave. For example, if a the left side of a widget is attached to ['%0', 100], its right side attached to ['none', 0], and the natural size of the widget is 50 pixels, the right side of the widget will be positioned at pixel ['%0', 149]. When both -top and -bottom are attached to none, then by default -top will be attached to ['%0', 0]. When both -left and -right are attached to none, then by default -left will be attached to ['%0', 0].

Shifting effects can be achieved by specifying a non-zero offset with an anchor point. In the following example, the top side of widget \$b is attached to the bottom of \$a; hence \$b always appears below \$a. Also, the left edge of \$b is attached to the left side of \$a with a 10 pixel offest. Therefore, the left edge of \$b is always shifted 10 pixels to the right of \$a's left edge:

$b->form(-left=>[$a,10], -top=>[$a,0]);

ABBREVIATIONS:

Certain abbreviations can be made on the attachment specifications: First an offset of zero can be omitted. Thus, the following two lines are equivalent:

$b->form(-top=>[$a,0], -right=>['%100',0]);

$b->form(-top=>[$a], -right=>'%100');

In the second case, when the anchor point is omitted, the offset must be given. A default anchor point is chosen according to the value of the offset. If the anchor point is 0 or positive, the default anchor point %0 is used; thus, "$b->form(-top=>15)" attaches the top edge of $b to a position 15 pixels below the top edge of the master window. If the anchor point is "-0" or negative, the default anchor point %100 is used; thus, "$a->form(-right=>-2)" attaches the right edge of \$a to a position 2 pixels to the left of the master window's right edge. An further example below shows a method with its equivalent abbreviation.

$b->form(-top=>['%0',10], -bottom=>['%100',0]);

$b->form(-top=>10, -bottom=>-0);

USING SPRINGS

To be written.

ALGORITHM OF FORM

form starts with any slave in the list of slaves of the master window. Then it tries to determine the position of each side of the slave.

If the attachment of a side of the slave is grid attachment, the position of the side is readily determined.

If the attachment of this side is none, then form tries to determine the position of the opposite side first, and then use the position of the opposite side and the natural size of the slave to determine the position of this side.

If the attachment is opposite or parallel widget attachments, then form tries to determine the positions of the other widget first, and then use the positions of the other widget and the natural size of the slave determine the position of this side. This recursive algorithmis carried on until the positions of all slaves are determined.

CIRCULAR DEPENDENCY

The algorithm of form will fail if a circular dependency exists in the attachments of the slaves. For example:

$c->form(-left=>$b);

$b->form(-right=>$c);

In this example, the position of the left side of $b depends on the right side of $c, which in turn depends on the left side of $b.

When a circular dependency is discovered during the execution of the form algorithm, form will generate a background error and the geometry of the slaves are undefined (and will be arbitrary). Notice that form only executes the algorithm when the specification of the slaves' attachments is complete. Therefore, it allows intermediate states of circular dependency during the specification of the slaves' attachments. Also, unlike the Motif Form manager widget, form defines circular dependency as ``dependency in the same dimension''. Therefore, the following code fragment will does not have circular dependency because the two widgets do not depend on each other in the same dimension ($b depends $c in the horizontal dimension and $c depends on $b in the vertical dimension):

$b->form(-left=>$c);

$c->form(-top=>$b);

BUGS

Springs have not been fully implemented yet.

SEE ALSO

Tk::grid
Tk::pack
Tk::place

KEYWORDS

geometry manager, form, attachment, spring, propagation, size, pack, tix, master, slave


getSaveFile - pop up a dialog box for the user to select a file to open or save.

  • SPECIFYING FILE PATTERNS
  • SPECIFYING EXTENSIONS
  • EXAMPLE
  • SEE ALSO
  • KEYWORDS

NAME

getOpenFile, getSaveFile - pop up a dialog box for the user to select a file to open or save.

SYNOPSIS

$widget->getOpenFile(?-option=>value, ...>?)

$widget->getSaveFile(?-option=>value, ...>?)

DESCRIPTION

The methods getOpenFile and getSaveFile pop up a dialog box for the user to select a file to open or save.

The getOpenFile method is usually associated with the Open command in the File menu. Its purpose is for the user to select an existing file only. If the user enters an non-existent file, the dialog box gives the user an error prompt and requires the user to give an alternative selection. If an application allows the user to create new files, it should do so by providing a separate New menu command.

The getSaveFile method is usually associated with the Save as command in the File menu. If the user enters a file that already exists, the dialog box prompts the user for confirmation whether the existing file should be overwritten or not.

If the user selects a file, both getOpenFile and getSaveFile return the full pathname of this file. If the user cancels the operation, both commands return an undefined value.

The following option-value pairs are possible as command line arguments to these two commands:

-defaultextension => extension

Specifies a string that will be appended to the filename if the user enters a filename without an extension. The default value is the empty string, which means no extension will be appended to the filename in any case. This option is ignored on the Macintosh platform, which does not require extensions to filenames, and the UNIX implementation guesses reasonable values for this from the -filetypes option when this is not supplied.

-filetypes => [filePattern ?, ...?]

If a File types listbox exists in the file dialog on the particular platform, this option gives the filetypes in this listbox. When the user choose a filetype in the listbox, only the files of that type are listed. If this option is unspecified, or if it is set to the empty list, or if the File types listbox is not supported by the particular platform then all files are listed regardless of their types. See SPECIFYING FILE PATTERNS below for a discussion on the contents of filePatterns.

-initialdir => directory

Specifies that the files in directory should be displayed when the dialog pops up. If this parameter is not specified, then the files in the current working directory are displayed. This option may not always work on the Macintosh. This is not a bug. Rather, the General Controls control panel on the Mac allows the end user to override the application default directory.

-initialfile => filename

Specifies a filename to be displayed in the dialog when it pops up. This option is ignored by the getOpenFile method.

-multiple

Allows the user to choose multiple files from the Open dialog. On the Macintosh, this is only available when Navigation Services are installed.

-message => string

Specifies a message to include in the client area of the dialog. This is only available on the Macintosh, and only when Navigation Services are installed.

-title => titleString

Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title is displayed. This option is ignored on the Macintosh platform.

SPECIFYING FILE PATTERNS

The filePatterns given by the -filetypes option are a list of file patterns. Each file pattern is a list of the form

 typeName [extension ?extension ...?] ?[macType ?macType ...?]?

typeName is the name of the file type described by this file pattern and is the text string that appears in the File types listbox. extension is a file extension for this file pattern. macType is a four-character Macintosh file type. The list of macTypes is optional and may be omitted for applications that do not need to execute on the Macintosh platform.

Several file patterns may have the same typeName, in which case they refer to the same file type and share the same entry in the listbox. When the user selects an entry in the listbox, all the files that match at least one of the file patterns corresponding to that entry are listed. Usually, each file pattern corresponds to a distinct type of file. The use of more than one file patterns for one type of file is necessary on the Macintosh platform only.

On the Macintosh platform, a file matches a file pattern if its name matches at least one of the extension(s) AND it belongs to at least one of the macType(s) of the file pattern. For example, the C Source Files file pattern in the sample code matches with files that have a \.c extension AND belong to the macType TEXT. To use the OR rule instead, you can use two file patterns, one with the extensions only and the other with the macType only. The GIF Files file type in the sample code matches files that EITHER have a \.gif extension OR belong to the macType GIFF.

On the Unix and Windows platforms, a file matches a file pattern if its name matches at at least one of the extension(s) of the file pattern. The macTypes are ignored.

SPECIFYING EXTENSIONS

On the Unix and Macintosh platforms, extensions are matched using glob-style pattern matching. On the Windows platforms, extensions are matched by the underlying operating system. The types of possible extensions are: (1) the special extension * matches any file; (2) the special extension "" matches any files that do not have an extension (i.e., the filename contains no full stop character); (3) any character string that does not contain any wild card characters (* and ?).

Due to the different pattern matching rules on the various platforms, to ensure portability, wild card characters are not allowed in the extensions, except as in the special extension *. Extensions without a full stop character (e.g, ~) are allowed but may not work on all platforms.

EXAMPLE

 my $types = [
     ['Text Files',       ['.txt', '.text']],
     ['TCL Scripts',      '.tcl'           ],
     ['C Source Files',   '.c',      'TEXT'],
     ['GIF Files',        '.gif',          ],
     ['GIF Files',        '',        'GIFF'],
     ['All Files',        '*',             ],
 ];
 my $filename = $widget->getOpenFile(-filetypes=>$types);

 if ($filename ne "") {
     # Open the file ...
 }

SEE ALSO

Tk::FBox, Tk::FileSelect

KEYWORDS

file selection dialog


grab - Confine pointer and keyboard events to a window sub-tree

  • BUGS
  • KEYWORDS

NAME

grab - Confine pointer and keyboard events to a window sub-tree

SYNOPSIS

$widget->grab

$widget->grab Option

DESCRIPTION

This set of methods implement simple pointer and keyboard grabs for Tk. Tk's grabs are different than the grabs described in the Xlib documentation. When a grab is set for a particular window, Tk restricts all pointer events to the grab window and its descendants in Tk's window hierarchy. Whenever the pointer is within the grab window's subtree, the pointer will behave exactly the same as if there had been no grab at all and all events will be reported in the normal fashion. When the pointer is outside $widget's tree, button presses and releases and mouse motion events are reported to $widget, and window entry and window exit events are ignored. The grab subtree ``owns'' the pointer: windows outside the grab subtree will be visible on the screen but they will be insensitive until the grab is released. The tree of windows underneath the grab window can include top-level windows, in which case all of those top-level windows and their descendants will continue to receive mouse events during the grab.

Two forms of grabs are possible: local and global. A local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. Grabs are local by default. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either.

During local grabs, keyboard events (key presses and key releases) are delivered as usual: the window manager controls which application receives keyboard events, and if they are sent to any window in the grabbing application then they are redirected to the focus window. During a global grab Tk grabs the keyboard so that all keyboard events are always sent to the grabbing application. The focus method is still used to determine which window in the application receives the keyboard events. The keyboard grab is released when the grab is released.

Grabs apply to particular displays. If an application has windows on multiple displays then it can establish a separate grab on each display. The grab on a particular display affects only the windows on that display. It is possible for different applications on a single display to have simultaneous local grabs, but only one application can have a global grab on a given display at once.

The grab methods take any of the following forms:

$widget->grabCurrent

Returns the current grab window in this application for $widget's display, or an empty string if there is no such window.

$widget->grabs

Returns a list whose elements are all of the windows grabbed by this application for all displays, or an empty string if the application has no grabs.

Not implemented yet!

$widget->grabRelease

Releases the grab on $widget if there is one, otherwise does nothing. Returns an empty string.

$widget->grab

Sets a local grab on $widget. If a grab was already in effect for this application on $widget's display then it is automatically released. If there is already a local grab on $widget, then the command does nothing. Returns an empty string.

$widget->grabGlobal

Sets a global grab on $widget. If a grab was already in effect for this application on $widget's display then it is automatically released. If there is already a global grab on $widget, then the command does nothing. Returns an empty string.

$widget->grabStatus

Returns none if no grab is currently set on $widget, local if a local grab is set on $widget, and global if a global grab is set.

BUGS

It took an incredibly complex and gross implementation to produce the simple grab effect described above. Given the current implementation, it isn't safe for applications to use the Xlib grab facilities at all except through the Tk grab procedures. If applications try to manipulate X's grab mechanisms directly, things will probably break.

If a single process is managing several different Tk applications, only one of those applications can have a local grab for a given display at any given time. If the applications are in different processes, this restriction doesn't exist.

KEYWORDS

grab, keyboard events, pointer events, window


Tk::grid - Geometry manager that arranges widgets in a grid

  • RELATIVE PLACEMENT
  • THE GRID ALGORITHM
  • GEOMETRY PROPAGATION
  • RESTRICTIONS ON MASTER WINDOWS
  • STACKING ORDER
  • CREDITS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::grid - Geometry manager that arranges widgets in a grid

SYNOPSIS

$widget->grid?(?widget ...,? ?arg ?...>?)?

$widget->grid Option?(arg ?,arg ...?)?

DESCRIPTION

The grid method is used to communicate with the grid geometry manager that arranges widgets in rows and columns inside of another window, called the geometry master (or master window). The grid method can have any of several forms, depending on the option argument:

$slave->grid(?$slave, ...??, options?)

The arguments consist of the optional references to more slave windows followed by pairs of arguments that specify how to manage the slaves. The characters -, x and ^, can be specified instead of a window reference to alter the default location of a $slave, as described in RELATIVE PLACEMENT, below.

If any of the slaves are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values.

The following options are supported:

-column => n

Insert the $slave so that it occupies the nth column in the grid. Column numbers start with 0. If this option is not supplied, then the $slave is arranged just to the right of previous slave specified on this call to grid, or column "0" if it is the first slave. For each x that immediately precedes the $slave, the column position is incremented by one. Thus the x represents a blank column for this row in the grid.

-columnspan => n

Insert the slave so that it occupies n columns in the grid. The default is one column, unless the window name is followed by a -, in which case the columnspan is incremented once for each immediately following -.

-in => $other

Insert the slave(s) in the master window given by $other. The default is the first slave's parent window.

-ipadx => amount

The amount specifies how much horizontal internal padding to leave on each side of the slave(s). This is space is added inside the slave(s) border. The amount must be a valid screen distance, such as 2 or '.5c'. It defaults to 0.

-ipady => amount

The amount specifies how much vertical internal padding to leave on on the top and bottom of the slave(s). This space is added inside the slave(s) border. The amount defaults to 0.

-padx => amount

The amount specifies how much horizontal external padding to leave on each side of the slave(s), in screen units. The amount defaults to 0. This space is added outside the slave(s) border.

-pady => amount

The amount specifies how much vertical external padding to leave on the top and bottom of the slave(s), in screen units. The amount defaults to 0. This space is added outside the slave(s) border.

-row => n

Insert the slave so that it occupies the nth row in the grid. Row numbers start with 0. If this option is not supplied, then the slave is arranged on the same row as the previous slave specified on this call to grid, or the first unoccupied row if this is the first slave.

-rowspan => n

Insert the slave so that it occupies n rows in the grid. The default is one row. If the next grid method contains ^ characters instead of $slaves that line up with the columns of this $slave, then the rowspan of this $slave is extended by one.

-sticky => style

If a slave's cell is larger than its requested dimensions, this option may be used to position (or stretch) the slave within its cell. Style is a string that contains zero or more of the characters n, s, e or w. The string can optionally contain spaces or commas, but they are ignored. Each letter refers to a side (north, south, east, or west) that the slave will "stick" to. If both n and s (or e and w) are specified, the slave will be stretched to fill the entire height (or width) of its cavity. The sticky option subsumes the combination of -anchor and -fill that is used by pack. The default is '', which causes the slave to be centered in its cavity, at its requested size.

$master->gridBbox(?column, row,? ?column2, row2?)

With no arguments, the bounding box (in pixels) of the grid is returned. The return value consists of 4 integers. The first two are the pixel offset from the master window (x then y) of the top-left corner of the grid, and the second two integers are the width and height of the grid, also in pixels. If a single column and row is specified on the command line, then the bounding box for that cell is returned, where the top left cell is numbered from zero. If both column and row arguments are specified, then the bounding box spanning the rows and columns indicated is returned.

$master->gridColumnconfigure(index?, -option=>value, ...?)

Query or set the column properties of the index column of the geometry master, $master. The valid options are -minsize, -weight and -pad. If one or more options are provided, then index may be given as a list of column indices to which the configuration options will operate on. The -minsize option sets the minimum size, in screen units, that will be permitted for this column. The -weight option (an integer value) sets the relative weight for apportioning any extra spaces among columns. A weight of zero (0) indicates the column will not deviate from its requested size. A column whose weight is two will grow at twice the rate as a column of weight one when extra space is allocated to the layout. The -uniform option, when a non-empty value is supplied, places the column in a uniform group with other columns that have the same value for -uniform. The space for columns belonging to a uniform group is allocated so that their sizes are always in strict proportion to their -weight values. See THE GRID ALGORITHM below for further details. The -pad option specifies the number of screen units that will be added to the largest window contained completely in that column when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings are returned in an list of "-option value" pairs.

$slave->gridConfigure(?$slave, ...?, options?)

The same as grid method.

$slave->gridForget?($slave, ...)?

Removes each of the $slaves from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. The configuration options for that window are forgotten, so that if the slave is managed once more by the grid geometry manager, the initial default settings are used.

$slave->gridInfo

Returns a list whose elements are the current configuration state of the slave given by $slave in the same option-value form that might be specified to gridConfigure. The first two elements of the list are ``-in=>$master'' where $master is the slave's master.

$master->gridLocation(x, y)

Given x and y values in screen units relative to the master window, the column and row number at that x and y location is returned. For locations that are above or to the left of the grid, -1 is returned.

$master->gridPropagate?(boolean)?

If boolean has a true boolean value such as 1 or on then propagation is enabled for $master, which must be a window name (see GEOMETRY PROPAGATION below). If boolean has a false boolean value then propagation is disabled for $master. In either of these cases an empty string is returned. If boolean is omitted then the method returns 0 or 1 to indicate whether propagation is currently enabled for $master. Propagation is enabled by default.

$master->gridRowconfigure(index?, -option=>value, ...?)

Query or set the row properties of the index row of the geometry master, $master. The valid options are -minsize, -weight and -pad. If one or more options are provided, then index may be given as a list of row indeces to which the configuration options will operate on. The -minsize option sets the minimum size, in screen units, that will be permitted for this row. The -weight option (an integer value) sets the relative weight for apportioning any extra spaces among rows. A weight of zero (0) indicates the row will not deviate from its requested size. A row whose weight is two will grow at twice the rate as a row of weight one when extra space is allocated to the layout. The -uniform option, when a non-empty value is supplied, places the row in a uniform group with other rows that have the same value for -uniform. The space for rows belonging to a uniform group is allocated so that their sizes are always in strict proportion to their -weight values. See THE GRID ALGORITHM below for further details. The -pad option specifies the number of screen units that will be added to the largest window contained completely in that row when the grid geometry manager requests a size from the containing window. If only an option is specified, with no value, the current value of that option is returned. If only the master window and index is specified, all the current settings are returned in an list of "option-value" pairs.

$slave->gridRemove?($slave, ...)?

Removes each of the $slaves from grid for its master and unmaps their windows. The slaves will no longer be managed by the grid geometry manager. However, the configuration options for that window are remembered, so that if the slave is managed once more by the grid geometry manager, the previous values are retained.

$master->gridSize

Returns the size of the grid (in columns then rows) for $master. The size is determined either by the $slave occupying the largest row or column, or the largest column or row with a -minsize, -weight, or -pad that is non-zero.

$master->gridSlaves?(-option=>value)?

If no options are supplied, a list of all of the slaves in $master are returned, most recently manages first. -option can be either -row or -column which causes only the slaves in the row (or column) specified by value to be returned.

RELATIVE PLACEMENT

The grid method contains a limited set of capabilities that permit layouts to be created without specifying the row and column information for each slave. This permits slaves to be rearranged, added, or removed without the need to explicitly specify row and column information. When no column or row information is specified for a $slave, default values are chosen for -column, -row, -columnspan and -rowspan at the time the $slave is managed. The values are chosen based upon the current layout of the grid, the position of the $slave relative to other $slaves in the same grid method, and the presence of the characters -, ^, and ^ in grid method where $slave names are normally expected.

-

This increases the columnspan of the $slave to the left. Several -'s in a row will successively increase the columnspan. A - may not follow a ^ or a x.

x

This leaves an empty column between the $slave on the left and the $slave on the right.

^

This extends the -rowspan of the $slave above the ^'s in the grid. The number of ^'s in a row must match the number of columns spanned by the $slave above it.

THE GRID ALGORITHM

The grid geometry manager lays out its slaves in three steps. In the first step, the minimum size needed to fit all of the slaves is computed, then (if propagation is turned on), a request is made of the master window to become that size. In the second step, the requested size is compared against the actual size of the master. If the sizes are different, then space is added to or taken away from the layout as needed. For the final step, each slave is positioned in its row(s) and column(s) based on the setting of its sticky flag.

To compute the minimum size of a layout, the grid geometry manager first looks at all slaves whose columnspan and rowspan values are one, and computes the nominal size of each row or column to be either the minsize for that row or column, or the sum of the padding plus the size of the largest slave, whichever is greater. Then the slaves whose rowspans or columnspans are greater than one are examined. If a group of rows or columns need to be increased in size in order to accommodate these slaves, then extra space is added to each row or column in the group according to its weight. For each group whose weights are all zero, the additional space is apportioned equally.

When multiple rows or columns belong to a uniform group, the space allocated to them is always in proportion to their weights. (A weight of zero is considered to be 1.) In other words, a row or column configured with -weight 1 -uniform a will have exactly the same size as any other row or column configured with -weight 1 -uniform a. A row or column configured with -weight 2 -uniform b will be exactly twice as large as one that is configured with -weight 1 -uniform b.

More technically, each row or column in the group will have a size equal to k*weight for some constant k. The constant k is chosen so that no row or column becomes smaller than its minimum size. For example, if all rows or columns in a group have the same weight, then each row or column will have the same size as the largest row or column in the group.

For masters whose size is larger than the requested layout, the additional space is apportioned according to the row and column weights. If all of the weights are zero, the layout is centered within its master. For masters whose size is smaller than the requested layout, space is taken away from columns and rows according to their weights. However, once a column or row shrinks to its minsize, its weight is taken to be zero. If more space needs to be removed from a layout than would be permitted, as when all the rows or columns are at there minimum sizes, the layout is clipped on the bottom and right.

GEOMETRY PROPAGATION

The grid geometry manager normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the gridPropagate method may be used to turn off propagation for one or more masters. If propagation is disabled then grid will not set the requested width and height of the master window. This may be useful if, for example, you wish for a master window to have a fixed size that you specify.

RESTRICTIONS ON MASTER WINDOWS

The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent. In addition, all slaves in one call to grid must have the same master.

STACKING ORDER

If the master for a slave is not its parent then you must make sure that the slave is higher in the stacking order than the master. Otherwise the master will obscure the slave and it will appear as if the slave hasn't been managed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first: the most recently created window will be highest in the stacking order.

CREDITS

The grid method is based on ideas taken from the GridBag geometry manager written by Doug. Stein, and the blt_table geometry manager, written by George Howlett.

SEE ALSO

Tk::form
Tk::pack
Tk::place

KEYWORDS

geometry manager, location, grid, cell, propagation, size, pack, master, slave


Tk::mega - Perl/Tk support for writing widgets in pure Perl

  • MEGA-WIDGET SUPPORT
    • Advertise
    • Callback
    • ClassInit
    • Component
    • ConfigSpecs
    • Construct
    • CreateArgs
    • Delegates
    • InitObject
    • OnDestroy
    • Populate
    • privateData
    • Subwidget
  • PITFALLS
  • MISSING
  • KEYWORDS
  • SEE ALSO

NAME

Tk::mega - Perl/Tk support for writing widgets in pure Perl

SYNOPSIS

Define the widget's new class name:

package Tk::MyNewWidget;

For composite widget classes:

use base qw/ Tk::container /; # where container is Frame or Toplevel

For derived widget classes:

use base qw/ Tk::Derived Tk::DerivedWidget /;

Install the new widget in Tk's namespace and establish class and instance constructors.

Construct Tk::Widget 'MyNewWidget';

sub ClassInit { my ($self, $args) = @_; ... }

sub Populate { my ($self, $args) = @_; ... }

DESCRIPTION

The goal of the mega-widget support of Perl/Tk is to make it easy to write mega-widgets that obey the same protocol and interface that the Tk core widgets support. For mega-widget sample code please run the widget demonstration program and go to the section Sample Perl Mega-Widgets.

There are two kinds of mega-widgets:

  • Composite Widgets

    A composite widget is composed with one or more existing widgets. The composite widget looks to the user like a simple single widget. A well known example is the file selection box.

  • Derived Widgets

    A derived widget adds/modifies/removes properties and methods from a single widget (this widget may itself be a mega-widget).

MEGA-WIDGET SUPPORT

Advertise

Give a subwidget a symbolic name.

Usage:

$self->Advertise(name=>$widget);

Gives a subwidget $widget of the mega-widget $self the name name. One can retrieve the reference of an advertised subwidget with the Subwidget method.

Comment: Mega-Widget Writers: Please make sure to document the advertised widgets that are intended for public use. If there are none, document this fact, e.g.:

        =head1 ADVERTISED WIDGETS
        None.

Callback

Invoke a callback specified with an option.

Usage:

$self->Callback(-option ?,args ...?);

Callback executes the callback defined with $self->ConfigSpecs(-option, [CALLBACK, ...]); If args are given they are passed to the callback. If -option is not defined it does nothing.

ClassInit

Initialization of the mega-widget class.

Usage:

sub ClassInit { my ($class, $mw) = @_; ... }

ClassInit is called once for each MainWindow just before the first widget instance of a class is created in the widget tree of MainWindow.

ClassInit is often used to define bindings and/or other resources shared by all instances, e.g., images.

Examples:

 $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
 $mw->bind($class,"<Return>", ['Insert',"\n"]);
 $mw->bind($class,"<Delete>",'Delete');

Notice that $class is the class name (e.g. Tk::MyText) and $mw is the mainwindow.

Don't forget to call $class->SUPER::ClassInit($mw) in ClassInit.

Component

Convenience function to create subwidgets.

Usage:

    $cw->Component('Whatever', 'AdvertisedName',
        -delegate => ['method1', 'method2', ...],
        ... more widget options ...,
    );

Component does several things for you with one call:

o Creates the widget

o Advertises it with a given name (overridden by 'Name' option)

o Delegates a set of methods to this widget (optional)

Example:

    $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});

ConfigSpecs

Defines options and their treatment

Usage:

    $cw->ConfigSpecs(
        -option => [ where, dbname, dbclass, default],
        ...,
        DEFAULT => [where],
    );

Defines the options of a mega-widget and what actions are triggered by configure/cget of an option (see the Tk::ConfigSpecs manpage and the Tk::Derived manpage for details).

Construct

Make the new mega-widget known to Tk.

Usage:

Construct baseclass 'Name';

Construct declares the new widget class so that your mega-widget works like normal Perl/Tk widgets.

Examples:

Construct Tk::Widget 'Whatever'; Construct Tk::Menu 'MyItem';

First example lets one use $widget->Whatever to create new Whatever widget.

The second example restricts the usage of the MyItem constructor method to widgets that are derived from Menu: $isamenu->MyItem.

CreateArgs

Process options before any widget is created:

sub CreateArgs { my ($package, $parent, $args) = @_; ...; return @newargs; }

$package is the package of the mega-widget (e.g., Tk::MyText, $parent the parent of the widget to be created and $args the hash reference to the options specified in the widget constructor call.

Don't forget to call $package->SUPER::CreateArgs($parent, $args) in CreateArgs.

Delegates

Redirect a method of the mega-widget to a subwidget of the composite widget

Usage:

    $cw->Delegates(
        'method1' => $subwidget1,
        'method2' => 'advertived_name',
        ...,
        'Construct' => $subwidget2,
        'DEFAULT'   => $subwidget3,
    );

The 'Construct' delegation has a special meaning. After 'Construct' is delegated all Widget constructors are redirected. E.g. after

$self->Delegates('Construct'=>$subframe);

a $self->Button does really a $subframe->Button so the created button is a child of $subframe and not $self.

Comment: Delegates works only with methods that $cw does not have itself.

InitObject

Note: this method should not, in general, be used, as it has been superceeded by Populate and specifying Tk::Derived as one of the base classes.

Defines construction and interface of derived widgets.

Usage:

    sub InitObject {
        my ($derived, $args) = @_;
        ...
    }

where $derived is the widget reference of the already created baseclass widget and $args is the reference to a hash of -option-value pairs.

InitObject is almost identical to Populate method. Populate does some more 'magic' things useful for mega-widgets with several widgets.

Don't forget to call $derived->SUPER::InitObject($args) in InitObject.

OnDestroy

Define a callback invoked when the mega-widget is destroyed.

Usage:

$widget->OnDestroy(callback);

OnDestroy installs a callback that's called when a widget is going to to be destroyed. Useful for special cleanup actions. It differs from a normal destroy in that all the widget's data structures are still intact.

Comment: This method could be used with any widgets not just for mega-widgets. It's listed here because of it's usefulness.

Populate

Defines construction and interface of the composite widget.

Usage:

    sub Populate {
        my ($self, $args) = @_;
        ...
    }

where $self is the widget reference of the already created baseclass widget and $args is the reference to a hash of -option-value pairs.

Most the other support function are normally used inside the Populate subroutine.

Don't forget to call $cw->SUPER::Populate($args) in Populate.

privateData

Set/get a private hash of a widget to storage composite internal data

Usage:

$hashref = $self->privateData();

$another = $self->privateData(unique_key|package);

Subwidget

Get the widget reference of an advertised subwidget.

@subwidget = $cw->Subwidget();

$subwidget = $cw->Subwidget(name);

@subwidget = $cw->Subwidget(name ?,...?);

Returns the widget reference(s) of the subwidget known under the given name(s). Without arguments, return all known subwidgets of $cw. See Advertise method how to define name for a subwidget.

Comment: Mega-Widget Users: Use Subwidget to get only documented subwidgets.

PITFALLS

  • Resource DB class name

    Some of the standard options use a resource date base class that is not equal to the resource database name. E.g.,

      Switch:            Name:             Class:
      -padx              padX              Pad
  -activerelief      activeRelief      Relief
  -activebackground  activeBackground  Foreground
  -status            undef             undef

    One should do the same when one defines one of these options via ConfigSpecs.

  • Method delegation

    Redirecting methods to a subwidget with Delegate can only work if the base widget itself does have a method with this name. Therefore one can't ``delegate'' any of the methods listed in Tk::Widget. A common problematic method is bind. In this case one as to explicitely redirect the method.

      sub bind {
      my $self = shift;
      my $to = $self->privateData->{'my_bind_target'};
      $to->bind(@_);
  }
  • privateData

    Graham Barr wrote: ... It is probably more private than most people think. Not all calls to privateData will return that same HASH reference. The HASH reference that is returned depends on the package it was called from, a different HASH is returned for each package. This allows a widget to hold private data, but then if it is sub-classed the sub-class will get a different HASH and so not cause duplicate name clashes.

    But privateData does take an optional argument if you want to force which HASH is returned.

  • Scrolled and Composite

    Scrolled(Kind,...) constructor can not be used with Composite. One has to use $cw->Composite(Scrl Kind => 'name', ...);

MISSING

Of course Perl/Tk does not define support function for all necessities. Here's a short list of things you have to handle yourself:

  • No support to define construction-time only options.

  • No support to remove an option that is known to the base widget.

  • It's hard to define undef as fallback for an widget option that is not already undef.

  • Frame in Perl/Tk carries magic and overhead not needed for composite widget class definition.

  • No support methods for bindings that are shared between all widgets of a composite widget (makes sense at all?)

KEYWORDS

mega, composite, derived, widget

SEE ALSO

Tk::composite
Tk::ConfigSpecs
Tk::option
Tk::callbacks
Tk::bind


messageBox - pop up a message window and wait for user response.

  • EXAMPLE
  • AUTHOR

NAME

messageBox - pop up a message window and wait for user response.

SYNOPSIS

$response = $widget->messageBox(-option => value, ... );

DESCRIPTION

This method uses Tk::Dialog to quickly create several common dialog boxes. A dialog widget consists of a message, an icon and a set of buttons (see the -type option). After the message window is popped up, messageBox waits for the user to select one of the buttons and return the button text (note that it's best to check the returned value in a case insensitive manner). NOTE: unlike Tk::Dialog which creates its widget once and can be used many times, the messageBox window is created every time it's used.

The following option/value pairs are supported:

-default

The case-sensitive symbolic name of the default button for this message window ('Ok', 'Cancel' and so on). See -type for a list of the symbolic names. If the message box has just one button it will automatically be made the default, otherwise if this option is not specified, there won't be any default button.

-icon

Specifies an icon to display. On X11 any of the builtin Tk bitmaps can specified. On Windows only error, info, question or warning are supported.

-message

Specifies the message to display.

-title

Specifies a string to display as the title.

-type

Specifies a predefined set of buttons to be displayed. The following values are possible: 'AbortRetryIgnore', 'Ok', 'OkCancel', 'RetryCancel', 'YesNo' or 'YesNoCancel'.

EXAMPLE

$response = $mw->messageBox(-icon => 'question', -message => 'Hello World!', -title => 'My title', -type => 'AbortRetryIgnore', -default => 'Retry');

AUTHOR

Stephen.O.Lidie@Lehigh.EDU. 98/05/25


option - Using the option database in Perl/Tk

    • Being a good citizen
    • Option rules and widget identification
  • METHODS
  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

option - Using the option database in Perl/Tk

SYNOPSIS

$widget->widgetClass(Name=>name, -class=>class);

$widget->PathName;

$widget->optionAdd(pattern=>value ?,priority?);

$widget->optionClear;

$widget->optionGet(name, class);

$widget->optionReadfile(fileName ?,priority?);

DESCRIPTION

The option database (also known as the resource database or the application defaults database) is a set of rules for applying default options to widgets. Users and system administrators can set up these rules to customize the appearance of applications without changing any application code; for example, a user might set up personal foreground and background colors, or a site might use fonts associated with visual or language preferences. Different window managers (and implementations of them) have implemented the database differently, but most Xt-based window managers use the .Xdefaults file or the xrdb utility to manage user preferences; some use both, and/or implement a more complex set of site, user and application databases. Check your site documentation for these topics or your window manager's RESOURCE_MANAGER property.

Being a good citizen

For most applications, the option database "just works." The option... methods are for applications that need to do something unusual, such as add new rules or test an option's default. Even in such cases, the application should provide for user preferences. Do not hardcode widget options without a very good reason. All users have their own tastes and they are all different. They choose a special font in a special size and have often spend a lot of time working out a color scheme that they will love until death. When you respect their choices they will enjoy working with your applications much more. Don't destroy the common look and feel of a personal desktop.

Option rules and widget identification

All widgets in an application are identified hierarchically by pathname, starting from the MainWindow and passing through each widget used to create the endpoint. The path elements are widget names, much like the elements of a file path from the root directory to a file. The rules in the option database are patterns that are matched against a widget's pathname to determine which defaults apply. When a widget is created, the Name option can be used to assign the widget's name and thus create a distinctive path for widgets in an application. If the Name option isn't given, Perl/Tk assigns a default name based on the type of widget; a MainWindow's default name is the appname. These defaults are fine for most widgets, so don't feel you need to find a meaningful name for every widget you create. A widget must have a distinctive name to allow users to tailor its options independently of other widgets in an application. For instance, to create a Text widget that will have special options assigned to it, give it a name such as:

  $text = $mw->Text(Name => 'importantText');

You can then tailor the widget's attributes with a rule in the option database such as:

  *importantText*foreground: red

The class attribute identifies groups of widgets, usually within an application but also to group similar widgets among different applications. One typically assigns a class to a TopLevel or Frame so that the class will apply to all of that widget's children. To extend the example, we could be more specific about the importantText widget by giving its frame a class:

  $frame = $mw->Frame(-class => 'Urgent');
  $text = $frame->Text(Name => 'importantText');

Then the resource pattern can be specified as so:

  *Urgent*importantText*foreground: red

Similarly, the pattern *Urgent*background: cyan would apply to all widgets in the frame.

METHODS

$widget->widgetClass(Name=>name, -class=>class);

Identify a new widget with name and/or class. Name specifies the path element for the widget; names generally begin with a lowercase letter. -class specifies the class for the widget and its children; classes generally begin with an uppercase letter. If not specified, Perl/Tk will assign a unique default name to each widget. Only MainWindow widgets have a default class, made by uppercasing the first letter of the application name.

$widget->PathName;

The PathName method returns the widget's pathname, which uniquely identifies the widget within the application.

$widget->optionAdd(pattern=>value ?, priority?);

The optionAdd method adds a new option to the database. Pattern contains the option being specified, and consists of names and/or classes separated by asterisks or dots, in the usual X format. Value contains a text string to associate with pattern; this is the value that will be returned in calls to the optionGet method. If priority is specified, it indicates the priority level for this option (see below for legal values); it defaults to interactive. This method always returns an empty string.

$widget->optionClear;

The optionClear method clears the option database. Default options (from the RESOURCE_MANAGER property or the .Xdefaults file) will be reloaded automatically the next time an option is added to the database or removed from it. This method always returns an empty string.

$widget->optionGet(name,class);

The optionGet method returns the value of the option specified for $widget under name and class. To look up the option, optionGet matches the patterns in the resource database against $widget's pathname along with the class of $widget (or its parent if $widget has no class specified). The widget's class and name are options set when the widget is created (not related to class in the sense of bless); the MainWindow's name is the appname and its class is (by default) derived from the name of the script.

If several entries in the option database match $widget's pathname, name, and class, then the method returns whichever was created with highest priority level. If there are several matching entries at the same priority level, then it returns whichever entry was most recently entered into the option database. If there are no matching entries, then the empty string is returned.

$widget->optionReadfile(fileName?,priority?);

The optionReadfile method reads fileName, which should have the standard format for an X resource database such as .Xdefaults, and adds all the options specified in that file to the option database. If priority is specified, it indicates the priority level at which to enter the options; priority defaults to interactive.

The priority arguments to the option methods are normally specified symbolically using one of the following values:

widgetDefault

Level 20. Used for default values hard-coded into widgets.

startupFile

Level 40. Used for options specified in application-specific startup files.

userDefault

Level 60. Used for options specified in user-specific defaults files, such as .Xdefaults, resource databases loaded into the X server, or user-specific startup files.

interactive

Level 80. Used for options specified interactively after the application starts running. If priority isn't specified, it defaults to this level.

Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above.

BUGS

The priority scheme used by core Tk is not the same as used by normal Xlib routines. In particular is assumes that the order of the entries is defined, but user commands like xrdb -merge can change the order.

SEE ALSO

Tk::Xrm

KEYWORDS

database, option, priority, retrieve


Tk::options - Standard options supported by widgets and their manipulation

    • Creation options: Widget Name and Class
    • Reconfigurable options
  • SEE ALSO
  • KEYWORDS

NAME

Tk::options - Standard options supported by widgets and their manipulation

SYNOPSIS

$value = $widget->cget('-option');

$widget->configure(-option=>value ?,-option=>value ...?);

@list = $widget->configure('-option');

@lol = $widget->configure;

DESCRIPTION

All widgets, and images have a standard mechanism for setting and querying attibutes or options. The mechanism is based on two methods configure and cget. The behaviour of these methods is as follows:

$widget->configure(-option=>value ?,-option=>value ...?);

Sets the values of -option to value for each -option=>value pair. The internal new method does an implicit configure in this form with options passed in at widget create time.

$widget->configure('-option')

In array context returns a list of five or two elements. If -option is an alias for another options it return a list consisting of the alias option and the name for the option is is an alias for, e.g., ('-bg', 'background'). If -option is not an alias the returned list has the following five elements:

Option Name

The value of -option, e.g., -background.

Name

The option's name in the option database, e.g., background.

Class

The option's class value in the option database, e.g., Background.

Default

The default value for the option if not specified or in the option database, e.g., grey.

Value

The current value (as returned by cget), e.g., white.

$widget->configure

Returns a list of lists for all the options supported by $widget. Each sub-list is in the form returned by configure('-option'). (This mechanism is used by the Tk::Derived class to determine the options available from base class.)

$widget->cget('-option')

Returns the current value of -option for $widget.

cget('-option') is clumsy with the need for '' due to perl's parsing rules. Something more subtle using tie might look better.

The following paragraphs describe the common configuration options supported by widgets in the Tk toolkit. Every widget does not necessarily support every option (see the the documentation entries for individual widgets for a list of the standard options supported by that widget), but if a widget does support an option with one of the names listed below, then the option has exactly the effect described below.

In the descriptions below, ``Name'' refers to the option's name in the option database. ``Class'' refers to the option's class value in the option database. ``Switch'' refers to the switch used in widget-creation and configure widget methods to set this value. For example, if an option's configure option is -foreground and there exists a widget $widget, then the call:

$widget->configure(-foreground=>'black')

may be used to specify the value black for the option in the widget $widget. Configure options may be abbreviated, as long as the abbreviation is unambiguous (abbreviation is deprecated in perl/Tk).

Creation options: Widget Name and Class

The Name and -class options can only be specified when a widget is created, and cannot be changed with configure. These options determine the widget's identity and how Tk applies resource values from the option database (see the Tk::option manpage) and so they cannot be assigned by the options database.

Name: name
Switch: Name

Specifies the path element for the widget. Names generally begin with a lowercase letter.

Each widget has a unique pathname that follows the hierarchy from the MainWindow to the widget itself. Since the widget's PathName is used to assign options from the options database, it is important to specify a distinctive Name for any widget that will have non-default options. See the Tk::option manpage for details.

Name: class
Switch: -class

Specifies a class for the window. Classes generally begin with an uppercase letter.

This class will be used when querying the option database for the window's other options (see Tk::options), and it will also be used later for other purposes such as bindings. One typically assigns a class to a TopLevel or Frame so that the class will apply to all of that widget's children.

Reconfigurable options

These options can be set at widget creation or changed later via configure.

Name: activeBackground
Class: Foreground
Switch: -activebackground

Specifies background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. If strict Motif compliance has been requested by setting the $Tk::strictMotif variable, this option will normally be ignored; the normal background color will be used instead. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element.

Name: activeBorderWidth
Class: BorderWidth
Switch: -activeborderwidth

Specifies a non-negative value indicating the width of the 3-D border drawn around active elements. See above for definition of active elements. The value may have any of the forms acceptable to Tk_GetPixels. This option is typically only available in widgets displaying more than one element at a time (e.g. menus but not buttons).

Name: activeForeground
Class: Background
Switch: -activeforeground

Specifies foreground color to use when drawing active elements. See above for definition of active elements.

Name: activetile
Class: Tile
Switch: -activetile

Specifies image used to display inside active elements of the widget. See above for definition of active elements.

Name: anchor
Class: Anchor
Switch: -anchor

Specifies how the information in a widget (e.g. text or a bitmap) is to be displayed in the widget. Must be one of the values n, ne, e, se, s, sw, w, nw, or center. For example, nw means display the information such that its top-left corner is at the top-left corner of the widget.

Name: background
Class: Background
Switch: -background
Alias: -bg

Specifies the normal background color to use when displaying the widget.

Name: bitmap
Class: Bitmap
Switch: -bitmap

Specifies a bitmap to display in the widget, in any of the forms acceptable to Tk_GetBitmap. The exact way in which the bitmap is displayed may be affected by other options such as -anchor or -justify. Typically, if this option is specified then it overrides other options that specify a textual value to display in the widget; the -bitmap option may be reset to an empty string to re-enable a text display. In widgets that support both -bitmap and -image options, -image will usually override -bitmap.

Name: borderWidth
Class: BorderWidth
Switch: -borderwidth
Alias: -bd

Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. The value may have any of the forms acceptable to Tk_GetPixels.

Name: cursor
Class: Cursor
Switch: -cursor

Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor.

Name: dash
Class: Dash
Switch: -dash

The value may have any of the forms accepted by Tk_GetDash, such as 4, [6,4], ., -, -., or -...

Name: dashoffset
Class: Dashoffset
Switch: -dashoffset

Specifies the offset in the dash list where the drawing starts.

Name: disabledForeground
Class: DisabledForeground
Switch: -disabledforeground

Specifies foreground color to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern.

Name: disabledtile
Class: Tile
Switch: -disabledtile

Specifies image to use when drawing a disabled element.

Name: exportSelection
Class: ExportSelection
Switch: -exportselection

Specifies whether or not a selection in the widget should also be the X selection. The value may have any of the forms accepted by Tcl_GetBoolean, such as true, false, 0, 1, yes, or no. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections.

Name: font
Class: Font
Switch: -font

Specifies the font to use when drawing text inside the widget.

Name: foreground
Class: Foreground
Switch: -foreground
Alias: -fg

Specifies the normal foreground color to use when displaying the widget.

Name: highlightBackground
Class: HighlightBackground
Switch: -highlightbackground

Specifies the color to display in the traversal highlight region when the widget does not have the input focus.

Name: highlightColor
Class: HighlightColor
Switch: -highlightcolor

Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus.

Name: highlightThickness
Class: HighlightThickness
Switch: -highlightthickness

Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to Tk_GetPixels. If the value is zero, no focus highlight is drawn around the widget.

Name: image
Class: Image
Switch: -image

Specifies an image to display in the widget, which must have been created with an image create. (See the Tk::Image manpage for details of image creation.) Typically, if the -image option is specified then it overrides other options that specify a bitmap or textual value to display in the widget; the -image option may be reset to an empty string to re-enable a bitmap or text display.

Name: insertBackground
Class: Foreground
Switch: -insertbackground

Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection).

Name: insertBorderWidth
Class: BorderWidth
Switch: -insertborderwidth

Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels.

Name: insertOffTime
Class: OffTime
Switch: -insertofftime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``off'' in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time.

Name: insertOnTime
Class: OnTime
Switch: -insertontime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain ``on'' in each blink cycle.

Name: insertWidth
Class: InsertWidth
Switch: -insertwidth

Specifies a value indicating the total width of the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. If a border has been specified for the insertion cursor (using the insertBorderWidth option), the border will be drawn inside the width specified by the insertWidth option.

Name: jump
Class: Jump
Switch: -jump

For widgets with a slider that can be dragged to adjust a value, such as scrollbars, this option determines when notifications are made about changes in the value. The option's value must be a boolean of the form accepted by Tcl_GetBoolean. If the value is false, updates are made continuously as the slider is dragged. If the value is true, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value ``jumps'' rather than changing smoothly).

Name: justify
Class: Justify
Switch: -justify

When there are multiple lines of text displayed in a widget, this option determines how the lines line up with each other. Must be one of left, center, or right. Left means that the lines' left edges all line up, center means that the lines' centers are aligned, and right means that the lines' right edges line up.

Name: offset
Class: Offset
Switch: -offset

Specifies the offset of tiles (see also -tile option). It can have two different formats -offset x,y or -offset side, where side can be n, ne, e, se, s, sw, w, nw, or center. In the first case the origin is the origin of the toplevel of the current window. For the canvas itself and canvas objects the origin is the canvas origin, but putting # in front of the coordinate pair indicates using the toplevel origin in stead. For canvas objects, the -offset option is used for stippling as well. For the line and polygon canvas items you can also specify an index as argument, which connects the stipple or tile origin to one of the coordinate points of the line/polygon.

Name: orient
Class: Orient
Switch: -orient

For widgets that can lay themselves out with either a horizontal or vertical orientation, such as scrollbars, this option specifies which orientation should be used. Must be either horizontal or vertical or an abbreviation of one of these.

Name: padX
Class: Pad
Switch: -padx

Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. The value may have any of the forms acceptable to Tk_GetPixels. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options.

Name: padY
Class: Pad
Switch: -pady

Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. The value may have any of the forms acceptable to Tk_GetPixels. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options.

Name: relief
Class: Relief
Switch: -relief

Specifies the 3-D effect desired for the widget. Acceptable values are raised, sunken, flat, ridge, solid, and groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

Name: repeatDelay
Class: RepeatDelay
Switch: -repeatdelay

Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars.

Name: repeatInterval
Class: RepeatInterval
Switch: -repeatinterval

Used in conjunction with repeatDelay: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats.

Name: selectBackground
Class: Foreground
Switch: -selectbackground

Specifies the background color to use when displaying selected items.

Name: selectBorderWidth
Class: BorderWidth
Switch: -selectborderwidth

Specifies a non-negative value indicating the width of the 3-D border to draw around selected items. The value may have any of the forms acceptable to Tk_GetPixels.

Name: selectForeground
Class: Background
Switch: -selectforeground

Specifies the foreground color to use when displaying selected items.

Name: setGrid
Class: SetGrid
Switch: -setgrid

Specifies a boolean value that determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the setGrid option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. See GRIDDED GEOMETRY MANAGEMENT in the Tk::Wm manpage for more details.

Name: takeFocus
Class: TakeFocus
Switch: -takefocus

Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the takeFocus option. A value of 0 means that the window should be skipped entirely during keyboard traversal. 1 means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a Callback. The script must return 0, 1, or an empty string: a 0 or 1 value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note: this interpretation of the option is defined entirely by the Callbacks that implement traversal: the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts.

Name: text
Class: Text
Switch: -text

Specifies a string to be displayed inside the widget. The way in which the string is displayed depends on the particular widget and may be determined by other options, such as anchor or justify.

Name: textVariable
Class: Variable
Switch: -textvariable

Specifies the name of a variable. The value of the variable is a text string to be displayed inside the widget; if the variable value changes then the widget will automatically update itself to reflect the new value. The way in which the string is displayed in the widget depends on the particular widget and may be determined by other options, such as anchor or justify.

Name: tile
Class: Tile
Switch: -tile

Specifies image used to display the widget. If image is the empty string, then the normal background color is displayed.

Name: troughColor
Class: Background
Switch: -troughcolor

Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales.

Name: troughTile
Class: Tile
Switch: -troughtile

Specifies image used to display in the rectangular trough areas in widgets such as scrollbars and scales.

Name: underline
Class: Underline
Switch: -underline

Specifies the integer index of a character to underline in the widget. This option is used by the default bindings to implement keyboard traversal for menu buttons and menu entries. 0 corresponds to the first character of the text displayed in the widget, 1 to the next character, and so on.

Name: wrapLength
Class: WrapLength
Switch: -wraplength

For widgets that can perform word-wrapping, this option specifies the maximum line length. Lines that would exceed this length are wrapped onto the next line, so that no line is longer than the specified length. The value may be specified in any of the standard forms for screen distances. If this value is less than or equal to 0 then no wrapping is done: lines will break only at newline characters in the text.

Name: xScrollCommand
Class: ScrollCommand
Switch: -xscrollcommand

Specifies a callback used to communicate with horizontal scrollbars. When the view in the widget's window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget's contents), the widget will make a callback passing two numeric arguments in addition to any specified in the callback. Each of the numbers is a fraction between 0 and 1, which indicates a position in the document. 0 indicates the beginning of the document, 1 indicates the end, .333 indicates a position one third the way through the document, and so on. The first fraction indicates the first information in the document that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. Typically the xScrollCommand option consists of the scrollbar widget object and the method ``set'' i.e. [set => $sb]: this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed.

Name: yScrollCommand
Class: ScrollCommand
Switch: -yscrollcommand

Specifies a calback used to communicate with vertical scrollbars. This option is treated in the same way as the xScrollCommand option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. See the description of xScrollCommand for details on how this option is used.

SEE ALSO

the Tk::option manpage
the Tk::callbacks manpage
the Tk::ConfigSpecs manpage
Tk_GetPixels

KEYWORDS

class, name, standard option, switch


B<Tk> - An overview of an Object Oriented Tk8.0 extension for perl5

  • CONTENTS
  • CLASS HIERARCHY

NAME

Tk - An overview of an Object Oriented Tk8.0 extension for perl5

SYNOPSIS

use Tk;

$main = MainWindow->new();

$widget = $main->Widget(...);

$widget->pack(...);

...

MainLoop;

DESCRIPTION

In writing the perl Tk extension, the goals were to provide a complete interface to the latest production version of John Ousterhout's Tk, while providing an Object Oriented interface to perl code.

CONTENTS

The package is composed of three loosely connected parts:

pTk - Converted Tk source

The pTk sub-directory is a copy of the C code of Tk4.0, modified to allow use by languages other than the original Tcl. (The pTk can be read as 'perl' Tk or 'portable' Tk, depending on your sensibilities.)

Tk to Perl 'Glue'

The top level directory provides Tk.xs and tkGlue.c which provide the perl-callable interfaces to pTk

Perl code for 'Widget' Classes

The Tk/Tk sub-directory contains the various perl modules that comprise the "Classes" that are visible to Tk applications.

The "major" widgets such as Tk::Text are actually in separate directories at the top level (e.g. Text/* for Tk::Text) and are dynamically loaded as needed on platforms which support perl5's DynaLoader.

CLASS HIERARCHY

package Tk; - the 'base class'

All the "command names" documented in Tcl/Tk are made to look like perl sub's and reside in the Tk package. Their names are all lower case. Typically there are very few commands at this level which are called directly by applications.

package Tk::Widget; - the 'Widget class'

There are no actual objects of the Tk::Widget class; however all the various Tk window "widgets" inherit from it, and it in turn inherits all the core Tk functions from Tk.

Tk::Widget provides various functions and interfaces which are common to all Widgets.

A widget is represented to perl as a blessed reference to a hash. There are some members of the hash which are private to Tk and its tkGlue code. Keys starting with '.' and of the form /_[A-Z][A-Za-z_]+_/ (i.e. starting and ending in _ and with first char after _ being upper case) should be considered reserved to Tk.

Tk::Button, Tk::Entry, Tk::Text ...

There is one class for each of the "Tk" widget item types. Some of them like Tk::Frame do very little indeed, and really only exist so that they can be derived from or so that focus or menu traversal can discover the "kind" of window being processed.

Other classes, Tk::Text for example, provide a lot of methods used with Tk's "bind" to provide a rich keyboard/mouse interface to the widgets' data.

These widget classes also include conversions of the Tcl code for event bindings, keyboard focus traversal, menu bars, and menu keyboard traversal. All the Tcl functions have been converted, but the names have changed (systematically) and they have been split up between the various classes in what I hope is an appropriate manner. Name changes are normally: dropping initial tk_ as the Tk-ness is implicit in the Tk:: prefix, and similarly dropping say Menu from the name if it has been moved the Tk::Menu class. Thus 'proc tkMenuNextEntry' becomes 'sub NextEntry' in the Tk::Menu package.

Tk::Image

This does for Tk4.0's "images" what Tk::Widget does for widgets. Images are new to Tk4.0 and the class structure is not mature either.

There are three sub-classes Tk::Bitmap, Tk::Pixmap and Tk::Photo.

It is expected that Tk::Image hierarchy will evolve during the "beta" phase of Tk to allow dynamic or auto-loaded image types or photo formats (e.g. support for JPEG format for photos).

Composite Widgets

A composite is some kind of 'frame' with subwidgets which give it useful behaviour. Tk::Dialog is an example of a composite widget classes built from the basic Tk ones. It is intended that user code should not need to be aware that a particular class is a composite, and create and configure such widgets in the same manner as any other kind. The configure mechanism and the methods of the class manipulate the subwidgets as required.

Composite widgets are implemented via Tk::Frame and multiple inheritance. The two 'frame' base classes Tk::Frame and Tk::Toplevel include the additional class Tk::Derived in their inheritance. Tk::Derived provides methods to allow additional configure options to be defined for a widget.

A Composite widget is typically defined as derived from Tk::Frame or Tk::Toplevel (e.g. Tk::Dialog).


Tk2portableTk - how to make your B<Tk> source portable to other interpreted languages.

  • Author
  • DESCRIPTION
  • Structure of pTk, porting your code
  • PortableTk API
    • Checking what you are running under
    • New types of configuration options
    • Language data
    • Conversion
    • Callbacks
    • Setting variables
    • Language functions
    • Translation of some TCL functions
  • Translation back to TCL
    • New types of events ????
  • Checking for trouble
  • Additional API
    • ListFactory
    • DStrings
    • Accessing Tcl_Obj *s
    • Assigning numbers to Tcl_Obj *s
    • Creating new Tcl_Obj *s
    • Evaluating a list
    • Getting result as Tcl_Obj *

NAME

Tk2portableTk - how to make your Tk source portable to other interpreted languages.

Author

Ilya Zakharevich <ilya@math.ohio-state.edu> has contributed most of this document. Many thanks.

DESCRIPTION

PortableTk is an attempt to make Tk useful from other languages. Currently tk4.0 runs under Perl using this approach. Below, Lang is the notation for an external language to which PortableTk glues Tk code.

The main problem with using the code developed for TCL with different languages is the absence of data types: almost anything is char*. It makes automatic translation hopeless. However, if you typedef several new symbols to be char*, you can still use your code in TCL, and it will make the automatic translation possible.

Another problem with the approach that "everything is a string" is impossibility to have a result that says "NotApplicable" without setting an error. Thus different Tk command return different string values that mean "error happened", like "", " " or "??". Other languages can be more flexible, so in portableTk you should inform the compiler that what you want to return means "error" (see Setting variables).

Currently PortableTk uses several different approachs to simplify translation: several TCL functions that are especially dangerous to use are undefined, so you can easily find places that need to be updated to use Language-independent functions based on compiler warnings. Eventually a way to use these Language-independent functions under proper TCL will be also provided. The end of this document provides a starting point for such a project.

Structure of pTk, porting your code

pTk, that is a port of Tk, is very special with respect to porting of other code to portableTk. The problem is that currently there is very little hope to merge the modifications back into Tk, so a special strategy is needed to maintain this port. Do not use this strategy to port your own code.

pTk is produced from Tk via a two-step process: first, some manual editing (the result is in the subdirectory mTk), and second, automatic conversion by the munge script (written in Perl). Thus the subdirectory pTk/mTk contains code with minimal possible difference from the virgin Tk code, so it is easier to merge(1) the differences between Tk versions into modified code.

It looks like the strategy for a portable code should be exactly opposite: starting from TCL-based code, apply munge, and then hand-edit the resulting code. Probably it is also possible to target your code to portableTk from scratch, since this will make it possible to run it under a lot of Languages.

The only reason anyone would like to look into contents of pTk/mTk directory is to find out which constructs are not supported by munge. On the other hand, pTk directory contains code that is conformant to portableTk, so you can look there to find example code.

munge is the script that converts most common Tk constructs to their portableTk equivalent. For your code to qualify, you should follow Tk conventions on indentation and names of variables, in particular, the array of arguments for the ...CmdProc should be called argv.

For details on what munge can do, see Translation of some TCL functions.

PortableTk API

Checking what you are running under

PortableTk provides a symbol ????. If this symbol is defined, your source is compiled with it.

New types of configuration options

PortableTk defines several new types of configuration options:

 TK_CONFIG_CALLBACK
 TK_CONFIG_LANGARG
 TK_CONFIG_SCALARVAR
 TK_CONFIG_HASHVAR
 TK_CONFIG_ARRAYVAR
 TK_CONFIG_IMAGE

You should use them instead of TK_CONFIG_STRING whenever appropriate. This allows your application to receive a direct representation of the corresponding resource instead of the string representation, if this is possible under given language.

???? It looks like TK_CONFIG_IMAGE and TK_CONFIG_SCALARVAR set variables of type char*.

Language data

The following data types are defined:

Tcl_Obj *

is the main datatype of the language. This is a type that your C function gets pointers to for arguments when the corresponding Lang function is called. The corresponding config type is TK_CONFIG_LANGARG.

This is also a type that keeps information about contents of Lang variable.

Var

Is a substitute for a char * that contains name of variable. In Lang it is an object that contains reference to another Lang variable.

LangResultSave

????

LangCallback

LangCallback* a substitute for a char * that contains command to call. The corresponding config type is TK_CONFIG_CALLBACK.

LangFreeProc

It is the type that the Lang_SplitList sets. Before you call it, declare

    Args *args;
    LangFreeProc *freeProc = NULL;
    ...
    code = Lang_SplitList(interp, value,
        &argc, &args, &freeProc);

After you use the split values, call

    if (args != NULL && freeProc) (*freeProc)(argc,args);

It is not guaranteed that the args can survive deletion of value.

Conversion

The following macros and functions are used for conversion between strings and the additional types:

 LangCallback * LangMakeCallback(Tcl_Obj *)
 Tcl_Obj * LangCallbackArg(LangCallback *)
 char * LangString(Tcl_Obj *)

After you use the result of LangCallbackArg(), you should free it with freeProc LANG_DYNAMIC (it is not guaranteed that any change of Tcl_Obj * will not be reflected in <LangCallback>, so you cannot do LangSet...() in between, and you should reset it to NULL if you want to do any further assignments to this Tcl_Obj *).

The following function returns the Tcl_Obj * that is a reference to Var:

 Tcl_Obj * LangVarArg(Var)

???? It is very anti-intuitive, I hope the name is changed.

 int LangCmpCallback(LangCallback *a,Tcl_Obj * b)

(currently only a stub), and, at last,

 LangCallback * LangCopyCallback(LangCallback *)

Callbacks

Above we have seen the new datatype LangCallback and the corresponding Config option TK_CONFIG_CALLBACK. The following functions are provided for manipulation of LangCallbacks:

 void LangFreeCallback(LangCallback *)
 int LangDoCallback(Tcl_Interp *,LangCallback *,
        int result,int argc, char *format,...)

The argument format of LangDoCallback should contain a string that is suitable for sprintf with optional arguments of LangDoCallback. result should be false if result of callback is not needed.

 int LangMethodCall(Tcl_Interp *,Tcl_Obj *,char *method,
        int result,int argc,...)

????

Conceptually, LangCallback* is a substitute for ubiquitous char * in TCL. So you should use LangFreeCallback instead of ckfree or free if appropriate.

Setting variables

 void LangFreeArg (Tcl_Obj *, Tcl_FreeProc *freeProc)
 Tcl_Obj *  LangCopyArg (Tcl_Obj *);
 void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)
 void LangSetString(Tcl_Obj * *, char *s)
 void LangSetDefault(Tcl_Obj * *, char *s)

These two are equivalent unless s is an empty string. In this case LangSetDefault behaves like LangSetString with s==NULL, i.e., it sets the current value of the Lang variable to be false.

 void LangSetInt(Tcl_Obj * *,int)
 void LangSetDouble(Tcl_Obj * *,double)

The Lang functions separate uninitialized and initialized data comparing data with NULL. So the declaration for an Tcl_Obj * should look like

 Tcl_Obj * arg = NULL;

if you want to use this arg with the above functions. After you are done, you should use LangFreeArg with TCL_DYNAMIC as freeProc.

Language functions

Use

int LangNull(Tcl_Obj *)

to check that an object is false;

int LangStringMatch(char *string, Tcl_Obj * match)

????

void LangExit(int)

to make a proper shutdown;

int LangEval(Tcl_Interp *interp, char *cmd, int global)

to call Lang eval;

void Lang_SetErrorCode(Tcl_Interp *interp,char *code)
char *Lang_GetErrorCode(Tcl_Interp *interp)
char *Lang_GetErrorInfo(Tcl_Interp *interp)
void LangCloseHandler(Tcl_Interp *interp,Tcl_Obj * arg,FILE *f,Lang_FileCloseProc *proc)

currently stubs only;

int LangSaveVar(Tcl_Interp *,Tcl_Obj * arg,Var *varPtr,int type)

to save the structure arg into Lang variable *varPtr;

void LangFreeVar(Var var)

to free the result;

int LangEventCallback(Tcl_Interp *,LangCallback *,XEvent *,KeySym)

????

int LangEventHook(int flags)
void LangBadFile(int fd)
int LangCmpConfig(char *spec, char *arg, size_t length)

unsupported????;

void Tcl_AppendArg (Tcl_Interp *interp, Tcl_Obj *)

Another useful construction is

 Tcl_Obj * variable = LangFindVar(interp, Tk_Window tkwin, char *name);

After using the above function, you should call

 LangFreeVar(Var variable);

???? Note discrepancy in types!

If you want to find the value of a variable (of type Tcl_Obj *) given the variable name, use Tcl_GetVar(interp, varName, flags). If you are interested in the string value of this variable, use LangString(Tcl_GetVar(...)).

To get a C array of Tcl_Obj * of length n, use

    Tcl_Obj * *args = LangAllocVec(n);
    ...
    LangFreeVec(n,args);

You can set the values of the Tcl_Obj *s using LangSet... functions, and get string value using LangString.

If you want to merge an array of Tcl_Obj *s into one Tcl_Obj * (that will be an array variable), use

    result = Tcl_Merge(listLength, list);

Translation of some TCL functions

We mark items that can be dealt with by munge by Autoconverted.

Tcl_AppendResult

does not take (char*)NULL, but NULL as delimiter. Autoconverted.

Tcl_CreateCommand, Tcl_DeleteCommand

Tk_CreateWidget, Tk_DeleteWidget, the second argument is the window itself, not the pathname. Autoconverted.

sprintf(interp->result, "%d %d %d %d",...)

Tcl_IntResults(interp,4,0,...). Autoconverted.

interp->result = "1";

Tcl_SetResult(interp,"1", TCL_STATIC). Autoconverted.

Reading interp->result

Tcl_GetResult(interp). Autoconverted.

interp->result = Tk_PathName(textPtr->tkwin);

Tk_WidgetResult(interp,textPtr->tkwin). Autoconverted.

Sequence Tcl_PrintDouble, Tcl_PrintDouble, ..., Tcl_AppendResult

Use a single command

 void Tcl_DoubleResults(Tcl_Interp *interp, int append,
        int argc,...);

append governs whether it is required to clear the result first.

A similar command for int arguments is Tcl_IntResults.

Tcl_SplitList

Use Lang_SplitList (see the description above).

Translation back to TCL

To use your portableTk program with TCL, put

 #include "ptcl.h"

before inclusion of tk.h, and link the resulting code with ptclGlue.c.

These files currently implement the following:

Additional config types:
 TK_CONFIG_CALLBACK
 TK_CONFIG_LANGARG
 TK_CONFIG_SCALARVAR
 TK_CONFIG_HASHVAR
 TK_CONFIG_ARRAYVAR
 TK_CONFIG_IMAGE
Types:
 Var, Tcl_Obj *, LangCallback, LangFreeProc.
Functions and macros:
 Lang_SplitList, LangString, LangSetString, LangSetDefault,
 LangSetInt, LangSetDouble Tcl_ArgResult, LangCallbackArg,
 LangSaveVar, LangFreeVar,
 LangFreeSplitProc, LangFreeArg, Tcl_DoubleResults, Tcl_IntResults,
 LangDoCallback, Tk_WidgetResult, Tcl_CreateCommand,
 Tcl_DeleteCommand, Tcl_GetResult.

Current implementation contains enough to make it possible to compile mTk/tkText*.[ch] with the virgin Tk.

New types of events ????

PortableTk defines following new types of events:

 TK_EVENTTYPE_NONE
 TK_EVENTTYPE_STRING
 TK_EVENTTYPE_NUMBER
 TK_EVENTTYPE_WINDOW
 TK_EVENTTYPE_ATOM
 TK_EVENTTYPE_DISPLAY
 TK_EVENTTYPE_DATA

and a function

 char * Tk_EventInfo(int letter,
            Tk_Window tkwin, XEvent *eventPtr,
            KeySym keySym, int *numPtr, int *isNum, int *type,
            int num_size, char *numStorage)

Checking for trouble

If you start with working TCL code, you can start convertion using the above hints. Good indication that you are doing is OK is absence of sprintf and sscanf in your code (at least in the part that is working with interpreter).

Additional API

What is described here is not included into base portableTk distribution. Currently it is coded in TCL and as Perl macros (core is coded as functions, so theoretically you can use the same object files with different interpreted languages).

ListFactory

Dynamic arrays in TCL are used for two different purposes: to construct strings, and to construct lists. These two usages will have separate interfaces in other languages (since list is a different type from a string), so you should use a different interface in your code.

The type for construction of dynamic lists is ListFactory. The API below is a counterpart of the API for construction of dynamic lists in TCL:

 void ListFactoryInit(ListFactory *)
 void ListFactoryFinish(ListFactory *)
 void ListFactoryFree(ListFactory *)
 Tcl_Obj * * ListFactoryArg(ListFactory *)
 void ListFactoryAppend(ListFactory *, Tcl_Obj * *arg)
 void ListFactoryAppendCopy(ListFactory *, Tcl_Obj * *arg)
 ListFactory * ListFactoryNewLevel(ListFactory *)
 ListFactory * ListFactoryEndLevel(ListFactory *)
 void ListFactoryResult(Tcl_Interp *, ListFactory *)

The difference is that a call to ListFactoryFinish should precede the actual usage of the value of ListFactory, and there are two different ways to append an Tcl_Obj * to a ListFactory: ListFactoryAppendCopy() guarantees that the value of arg is copied to the list, but ListFactoryAppend() may append to the list a reference to the current value of arg. If you are not going to change the value of arg after appending, the call to ListFactoryAppend may be quicker.

As in TCL, the call to ListFactoryFree() does not free the ListFactory, only the objects it references.

The functions ListFactoryNewLevel() and ListFactoryEndLevel() return a pointer to a ListFactory to fill. The argument of ListFactoryEndLevel() cannot be used after a call to this function.

DStrings

Production of strings are still supported in portableTk.

Accessing Tcl_Obj *s

The following functions for getting a value of an Tcl_Obj * may be provided:

 double LangDouble(Tcl_Obj *)
 int LangInt(Tcl_Obj *)
 long LangLong(Tcl_Obj *)
 int LangIsList(Tcl_Obj * arg)

The function LangIsList() is supported only partially under TCL, since there is no data types. It checks whether there is a space inside the string arg.

Assigning numbers to Tcl_Obj *s

While LangSetDouble() and LangSetInt() are supported ways to assign numbers to assign an integer value to a variable, for the sake of efficiency under TCL it is supposed that the destination of these commands was massaged before the call so it contains a long enough string to sprintf() the numbers inside it. If you are going to immediately use the resulting Tcl_Obj *, the best way to do this is to declare a buffer in the beginning of a block by

   dArgBuffer;

and assign this buffer to the Tcl_Obj * by

   void LangSetDefaultBuffer(Tcl_Obj * *)

You can also create the buffer(s) manually and assign them using

   void LangSetBuffer(Tcl_Obj * *, char *)

This is the only choice if you need to assign numeric values to several Tcl_Obj *s simultaneously. The advantage of the first approach is that the above declarations can be made nops in different languages.

Note that if you apply LangSetDefaultBuffer to an Tcl_Obj * that contains some value, you can create a leak if you do not free that Tcl_Obj * first. This is a non-problem in real languages, but can be a trouble in TCL, unless you use only the above API.

Creating new Tcl_Obj *s

The API for creating a new Tcl_Obj * is

 void LangNewArg(Tcl_Obj * *, LangFreeProc *)

The API for creating a new Tcl_Obj * is absent. Just initialize Tcl_Obj * to be NULL, and apply one of LangSet... methods.

After you use this Tcl_Obj *, it should be freed thusly:

LangFreeArg(arg, freeProc).

Evaluating a list

Use

 int LangArgEval(Tcl_Interp *, Tcl_Obj * arg)

Here arg should be a list to evaluate, in particular, the first element should be a LangCallback massaged to be an Tcl_Obj *. The arguments can be send to the subroutine by reference or by value in different languages.

Getting result as Tcl_Obj *

Use Tcl_ArgResult. It is not guaranteed that result survives this operation, so the Tcl_Obj * you get should be the only mean to access the data from this moment on. After you use this Tcl_Obj *, you should free it with freeProc LANG_DYNAMIC (you can do LangSet...() in between).


Tk::pack - Geometry manager that packs around edges of cavity

  • THE PACKER ALGORITHM
  • EXPANSION
  • GEOMETRY PROPAGATION
  • RESTRICTIONS ON MASTER WINDOWS
  • PACKING ORDER
  • SEE ALSO
  • KEYWORDS

NAME

Tk::pack - Geometry manager that packs around edges of cavity

SYNOPSIS

$widget->pack?(args)?

$widget->pack Option?(args)?

DESCRIPTION

The pack method is used to communicate with the packer, a geometry manager that arranges the children of a parent by packing them in order around the edges of the parent.

In this perl port of Tk it is normal to pack widgets one-at-a-time using the widget object to be packed to invoke a method call. This is a slight distortion of underlying Tk interface (which can handle lists of windows to one pack method call) but has proven effective in practice.

The pack method can have any of several forms, depending on Option:

$slave->pack?(options)?

The options consist of pairs of arguments that specify how to manage the slave. See THE PACKER ALGORITHM below for details on how the options are used by the packer. The following options are supported:

-after => $other

$other must be another window. Use its master as the master for the slave, and insert the slave just after $other in the packing order.

-anchor => anchor

Anchor must be a valid anchor position such as n or sw; it specifies where to position each slave in its parcel. Defaults to center.

-before => $other

$other must be another window. Use its master as the master for the slave, and insert the slave just before $other in the packing order.

-expand => boolean

Specifies whether the slave should be expanded to consume extra space in their master. Boolean may have any proper boolean value, such as 1 or no. Defaults to 0.

-fill => style

If a slave's parcel is larger than its requested dimensions, this option may be used to stretch the slave. Style must have one of the following values:

none

Give the slave its requested dimensions plus any internal padding requested with -ipadx or -ipady. This is the default.

x

Stretch the slave horizontally to fill the entire width of its parcel (except leave external padding as specified by -padx).

y

Stretch the slave vertically to fill the entire height of its parcel (except leave external padding as specified by -pady).

both

Stretch the slave both horizontally and vertically.

-in => $master

Insert the slave(s) at the end of the packing order for the master window given by $master.

-ipadx => amount

Amount specifies how much horizontal internal padding to leave on each side of the slave(s). Amount must be a valid screen distance, such as 2 or .5c. It defaults to 0.

-ipady => amount

Amount specifies how much vertical internal padding to leave on each side of the slave(s). Amount defaults to 0.

-padx => amount

Amount specifies how much horizontal external padding to leave on each side of the slave(s). Amount defaults to 0.

-pady => amount

Amount specifies how much vertical external padding to leave on each side of the slave(s). Amount defaults to 0.

-side => side

Specifies which side of the master the slave(s) will be packed against. Must be left, right, top, or bottom. Defaults to top.

If no -in, -after or -before option is specified then slave will be inserted at the end of the packing list for its parent unless it is already managed by the packer (in which case it will be left where it is). If one of these options is specified then slave will be inserted at the specified point. If the slave are already managed by the geometry manager then any unspecified options for them retain their previous values rather than receiving default values.

$slave->packConfigure?(options)?

Same as pack.

$slave->packForget

Removes slave from the packing order for its master and unmaps its window. The slave will no longer be managed by the packer.

$slave->packInfo

Returns a list whose elements are the current configuration state of the slave given by $slave in the same option-value form that might be specified to packConfigure. The first two elements of the list are ``-in=>$master'' where $master is the slave's master.

$master->packPropagate?(boolean)?

If boolean has a true boolean value such as 1 or on then propagation is enabled for $master, (see GEOMETRY PROPAGATION below). If boolean has a false boolean value then propagation is disabled for $master. In either of these cases an empty string is returned. If boolean is omitted then the method returns 0 or 1 to indicate whether propagation is currently enabled for $master. Propagation is enabled by default.

$master->packSlaves

Returns a list of all of the slaves in the packing order for $master. The order of the slaves in the list is the same as their order in the packing order. If $master has no slaves then an empty list/string is returned in array/scalar context, respectively

THE PACKER ALGORITHM

For each master the packer maintains an ordered list of slaves called the packing list. The -in, -after, and -before configuration options are used to specify the master for each slave and the slave's position in the packing list. If none of these options is given for a slave then the slave is added to the end of the packing list for its parent.

The packer arranges the slaves for a master by scanning the packing list in order. At the time it processes each slave, a rectangular area within the master is still unallocated. This area is called the cavity; for the first slave it is the entire area of the master.

For each slave the packer carries out the following steps:

[1]

The packer allocates a rectangular parcel for the slave along the side of the cavity given by the slave's -side option. If the side is top or bottom then the width of the parcel is the width of the cavity and its height is the requested height of the slave plus the -ipady and -pady options. For the left or right side the height of the parcel is the height of the cavity and the width is the requested width of the slave plus the -ipadx and -padx options. The parcel may be enlarged further because of the -expand option (see EXPANSION below)

[2]

The packer chooses the dimensions of the slave. The width will normally be the slave's requested width plus twice its -ipadx option and the height will normally be the slave's requested height plus twice its -ipady option. However, if the -fill option is x or both then the width of the slave is expanded to fill the width of the parcel, minus twice the -padx option. If the -fill option is y or both then the height of the slave is expanded to fill the width of the parcel, minus twice the -pady option.

[3]

The packer positions the slave over its parcel. If the slave is smaller than the parcel then the -anchor option determines where in the parcel the slave will be placed. If -padx or -pady is non-zero, then the given amount of external padding will always be left between the slave and the edges of the parcel.

Once a given slave has been packed, the area of its parcel is subtracted from the cavity, leaving a smaller rectangular cavity for the next slave. If a slave doesn't use all of its parcel, the unused space in the parcel will not be used by subsequent slaves. If the cavity should become too small to meet the needs of a slave then the slave will be given whatever space is left in the cavity. If the cavity shrinks to zero size, then all remaining slaves on the packing list will be unmapped from the screen until the master window becomes large enough to hold them again.

EXPANSION

If a master window is so large that there will be extra space left over after all of its slaves have been packed, then the extra space is distributed uniformly among all of the slaves for which the -expand option is set. Extra horizontal space is distributed among the expandable slaves whose -side is left or right, and extra vertical space is distributed among the expandable slaves whose -side is top or bottom.

GEOMETRY PROPAGATION

The packer normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the packPropagate method may be used to turn off propagation for one or more masters. If propagation is disabled then the packer will not set the requested width and height of the packer. This may be useful if, for example, you wish for a master window to have a fixed size that you specify.

RESTRICTIONS ON MASTER WINDOWS

The master for each slave must either be the slave's parent (the default) or a descendant of the slave's parent. This restriction is necessary to guarantee that the slave can be placed over any part of its master that is visible without danger of the slave being clipped by its parent.

PACKING ORDER

If the master for a slave is not its parent then you must make sure that the slave is higher in the stacking order than the master. Otherwise the master will obscure the slave and it will appear as if the slave hasn't been packed correctly. The easiest way to make sure the slave is higher than the master is to create the master window first: the most recently created window will be highest in the stacking order. Or, you can use the raise and lower methods to change the stacking order of either the master or the slave.

SEE ALSO

Tk::form
Tk::grid
Tk::place

KEYWORDS

geometry manager, location, packer, parcel, propagation, size


bisque - Modify the Tk color palette

  • BUGS
  • SEE ALSO
  • KEYWORDS

NAME

setPalette, bisque - Modify the Tk color palette

SYNOPSIS

$widget->setPalette(background)

$widget->setPalette(name=>value?,name=>value ...?)

$widget->bisque

DESCRIPTION

The setPalette method changes the color scheme for Tk. It does this by modifying the colors of existing widgets and by changing the option database so that future widgets will use the new color scheme. If setPalette is invoked with a single argument, the argument is the name of a color to use as the normal background color; setPalette will compute a complete color palette from this background color. Alternatively, the arguments to setPalette may consist of any number of name-value pairs, where the first argument of the pair is the name of an option in the Tk option database and the second argument is the new value to use for that option. The following database names are currently supported:

 activeBackground       foreground      selectColor
 activeForeground       highlightBackground     selectBackground
 background     highlightColor  selectForeground
 disabledForeground     insertBackground        troughColor

setPalette tries to compute reasonable defaults for any options that you don't specify. You can specify options other than the above ones and Tk will change those options on widgets as well. This feature may be useful if you are using custom widgets with additional color options.

Once it has computed the new value to use for each of the color options, setPalette scans the widget hierarchy to modify the options of all existing widgets. For each widget, it checks to see if any of the above options is defined for the widget. If so, and if the option's current value is the default, then the value is changed; if the option has a value other than the default, setPalette will not change it. The default for an option is the one provided by the widget (($w->configure('option'))[3]) unless setPalette has been run previously, in which case it is the value specified in the previous invocation of setPalette.

After modifying all the widgets in the application, setPalette adds options to the option database to change the defaults for widgets created in the future. The new options are added at priority widgetDefault, so they will be overridden by options from the .Xdefaults file or options specified on the command-line that creates a widget.

The method bisque is provided for backward compatibility: it restores the application's colors to the light brown (``bisque'') color scheme used in Tk 3.6 and earlier versions.

BUGS

The use of option database names rather than the configure names is understandable given the mechanism (copied from Tcl/Tk), but is potentially confusing.

The interpolation of different 'shades' of color used for 3D effects in 'RGB' space can lead to undesirable changes in 'hue'. Interpolation in 'HSV' (as used in Tk::ColorEditor) would be more robust and X11R5's color support probably even more so.

SEE ALSO

Tk::options

KEYWORDS

bisque, color, palette


Tk::place - Geometry manager for fixed or rubber-sheet placement

  • FINE POINTS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::place - Geometry manager for fixed or rubber-sheet placement

SYNOPSIS

$widget->place?(-option=>value?, -option=>value, ...)?

$widget->placeForget

$widget->placeInfo

$master->placeSlaves

DESCRIPTION

The placer is a geometry manager for Tk. It provides simple fixed placement of windows, where you specify the exact size and location of one window, called the slave, within another window, called the $master. The placer also provides rubber-sheet placement, where you specify the size and location of the slave in terms of the dimensions of the master, so that the slave changes size and location in response to changes in the size of the master. Lastly, the placer allows you to mix these styles of placement so that, for example, the slave has a fixed width and height but is centered inside the master.

$slave->place?(-option=>value?, -option=>value, ...?)?

The place method arranges for the placer to manage the geometry of $slave. The remaining arguments consist of one or more -option=>value pairs that specify the way in which $slave's geometry is managed. If the placer is already managing $slave, then the -option=>value pairs modify the configuration for $slave. The place method returns an empty string as result. The following -option=>value pairs are supported:

-in => $master

$master is the reference to the window relative to which $slave is to be placed. $master must either be $slave's parent or a descendant of $slave's parent. In addition, $master and $slave must both be descendants of the same top-level window. These restrictions are necessary to guarantee that $slave is visible whenever $master is visible. If this option isn't specified then the master defaults to $slave's parent.

-x => location

Location specifies the x-coordinate within the master window of the anchor point for $slave widget. The location is specified in screen units (i.e. any of the forms accepted by Tk_GetPixels) and need not lie within the bounds of the master window.

-relx => location

Location specifies the x-coordinate within the master window of the anchor point for $slave widget. In this case the location is specified in a relative fashion as a floating-point number: 0.0 corresponds to the left edge of the master and 1.0 corresponds to the right edge of the master. Location need not be in the range 0.0-1.0. If both -x and -relx are specified for a slave then their values are summed. For example, "-relx=>0.5, -x=-2" positions the left edge of the slave 2 pixels to the left of the center of its master.

-y => location

Location specifies the y-coordinate within the master window of the anchor point for $slave widget. The location is specified in screen units (i.e. any of the forms accepted by Tk_GetPixels) and need not lie within the bounds of the master window.

-rely => location

Location specifies the y-coordinate within the master window of the anchor point for $slave widget. In this case the value is specified in a relative fashion as a floating-point number: 0.0 corresponds to the top edge of the master and 1.0 corresponds to the bottom edge of the master. Location need not be in the range 0.0-1.0. If both -y and -rely are specified for a slave then their values are summed. For example, -rely=>0.5, -x=>3 positions the top edge of the slave 3 pixels below the center of its master.

-anchor => where

Where specifies which point of $slave is to be positioned at the (x,y) location selected by the -x, -y, -relx, and -rely options. The anchor point is in terms of the outer area of $slave including its border, if any. Thus if where is se then the lower-right corner of $slave's border will appear at the given (x,y) location in the master. The anchor position defaults to nw.

-width => size

Size specifies the width for $slave in screen units (i.e. any of the forms accepted by Tk_GetPixels). The width will be the outer width of $slave including its border, if any. If size is an empty string, or if no -width or -relwidth option is specified, then the width requested internally by the window will be used.

-relwidth => size

Size specifies the width for $slave. In this case the width is specified as a floating-point number relative to the width of the master: 0.5 means $slave will be half as wide as the master, 1.0 means $slave will have the same width as the master, and so on. If both -width and -relwidth are specified for a slave, their values are summed. For example, -relwidth=>1.0, -width=>5 makes the slave 5 pixels wider than the master.

-height => size

Size specifies the height for $slave in screen units (i.e. any of the forms accepted by Tk_GetPixels). The height will be the outer dimension of $slave including its border, if any. If size is an empty string, or if no -height or -relheight option is specified, then the height requested internally by the window will be used.

-relheight => size

Size specifies the height for $slave. In this case the height is specified as a floating-point number relative to the height of the master: 0.5 means $slave will be half as high as the master, 1.0 means $slave will have the same height as the master, and so on. If both -height and -relheight are specified for a slave, their values are summed. For example, -relheight=>1.0, -height=>-2 makes the slave 2 pixels shorter than the master.

-bordermode => mode

Mode determines the degree to which borders within the master are used in determining the placement of the slave. The default and most common value is inside. In this case the placer considers the area of the master to be the innermost area of the master, inside any border: an option of -x=>0 corresponds to an x-coordinate just inside the border and an option of -relwidth=>1.0 means $slave will fill the area inside the master's border. If mode is outside then the placer considers the area of the master to include its border; this mode is typically used when placing $slave outside its master, as with the options -x=>0, -y=>0, -anchor=>ne. Lastly, mode may be specified as ignore, in which case borders are ignored: the area of the master is considered to be its official X area, which includes any internal border but no external border. A bordermode of ignore is probably not very useful.

If the same value is specified separately with two different options, such as -x and -relx, then the most recent option is used and the older one is ignored.

$slave->placeSlaves

The placeSlaves method returns a list of all the slave windows for which $master is the master. If there are no slaves for $master then an empty list is returned.

$slave->placeForget

The placeForget method causes the placer to stop managing the geometry of $slave. As a side effect of this method call $slave will be unmapped so that it doesn't appear on the screen. If $slave isn't currently managed by the placer then the method call has no effect. placeForget returns an empty string as result.

$slave->placeInfo

The placeInfo method returns a list giving the current configuration of $slave. The list consists of -option=>value pairs in exactly the same form as might be specified to the place method. If the configuration of a window has been retrieved with placeInfo, that configuration can be restored later by first using placeForget to erase any existing information for the window and then invoking place with the saved information.

FINE POINTS

It is not necessary for the master window to be the parent of the slave window. This feature is useful in at least two situations. First, for complex window layouts it means you can create a hierarchy of subwindows whose only purpose is to assist in the layout of the parent. The ``real children'' of the parent (i.e. the windows that are significant for the application's user interface) can be children of the parent yet be placed inside the windows of the geometry-management hierarchy. This means that the path names of the ``real children'' don't reflect the geometry-management hierarchy and users can specify options for the real children without being aware of the structure of the geometry-management hierarchy.

A second reason for having a master different than the slave's parent is to tie two siblings together. For example, the placer can be used to force a window always to be positioned centered just below one of its siblings by specifying the configuration

-in=>$sibling, -relx=>0.5, -rely=>1.0, -anchor=>'n', -bordermode=>'outside'

Whenever the $sibling widget is repositioned in the future, the slave will be repositioned as well.

Unlike many other geometry managers (such as the packer) the placer does not make any attempt to manipulate the geometry of the master windows or the parents of slave windows (i.e. it doesn't set their requested sizes). To control the sizes of these windows, make them windows like frames and canvases that provide configuration options for this purpose.

SEE ALSO

Tk::form
Tk::grid
Tk::pack

KEYWORDS

geometry manager, height, location, master, place, rubber sheet, slave, width


Tk::Selection - Manipulate the X selection

  • KEYWORDS

NAME

Tk::Selection - Manipulate the X selection

SYNOPSIS

$widget->Selection Option?(args)?

DESCRIPTION

This command provides an interface to the X selection mechanism and implements the full selection functionality described in the X Inter-Client Communication Conventions Manual (ICCCM).

The widget object used to invoke the methods below determines which display is used to access the selection. In order to avoid conflicts with selection methods of widget classes (e.g. Text) this set of methods uses the prefix Selection. The following methods are currently supported:

$widget->SelectionClear?(-selection=>selection)?

If selection exists anywhere on $widget's display, clear it so that no window owns the selection anymore. Selection specifies the X selection that should be cleared, and should be an atom name such as PRIMARY or CLIPBOARD; see the Inter-Client Communication Conventions Manual for complete details. Selection defaults to PRIMARY. Returns an empty string.

$widget->SelectionGet?(?-selection=>selection?,?-type=>type?)?

Retrieves the value of selection from $widget's display and returns it as a result. Selection defaults to PRIMARY.

Type specifies the form in which the selection is to be returned (the desired ``target'' for conversion, in ICCCM terminology), and should be an atom name such as STRING or FILE_NAME; see the Inter-Client Communication Conventions Manual for complete details. Type defaults to STRING. The selection owner may choose to return the selection in any of several different representation formats, such as STRING, ATOM, INTEGER, etc. (this format is different than the selection type; see the ICCCM for all the confusing details).

If format is not STRING then things get messy, the following description is from the Tcl/Tk man page as yet incompetely translated for the perl version - it is misleading at best.

If the selection is returned in a non-string format, such as INTEGER or ATOM, the SelectionGet converts it to a list of perl values: atoms are converted to their textual names, and anything else is converted integers.

A goal of the perl port is to provide better handling of different formats than Tcl/Tk does, which should be possible given perl's wider range of ``types''. Although some thought went into this in very early days of perl/Tk what exactly happens is still "not quite right" and subject to change.

$widget->SelectionHandle(?-selection=>selection?,?-type=>type?,?-format=>format? callback)

Creates a handler for selection requests, such that callback will be executed whenever selection is owned by $widget and someone attempts to retrieve it in the form given by type (e.g. type is specified in the selection get command). Selection defaults to PRIMARY, type defaults to STRING, and format defaults to STRING. If callback is an empty string then any existing handler for $widget, type, and selection is removed.

When selection is requested, $widget is the selection owner, and type is the requested type, callback will be executed with two additional arguments. The two additional arguments are offset and maxBytes: offset specifies a starting character position in the selection and maxBytes gives the maximum number of bytes to retrieve. The command should return a value consisting of at most maxBytes of the selection, starting at position offset. For very large selections (larger than maxBytes) the selection will be retrieved using several invocations of callback with increasing offset values. If callback returns a string whose length is less than maxBytes, the return value is assumed to include all of the remainder of the selection; if the length of callback's result is equal to maxBytes then callback will be invoked again, until it eventually returns a result shorter than maxBytes. The value of maxBytes will always be relatively large (thousands of bytes).

If callback returns an error (e.g. via die) then the selection retrieval is rejected just as if the selection didn't exist at all.

The format argument specifies the representation that should be used to transmit the selection to the requester (the second column of Table 2 of the ICCCM), and defaults to STRING. If format is STRING, the selection is transmitted as 8-bit ASCII characters (i.e. just in the form returned by command).

If format is not STRING then things get messy, the following description is from the Tcl/Tk man page as yet untranslated for the perl version - it is misleading at best.

If format is ATOM, then the return value from command is divided into fields separated by white space; each field is converted to its atom value, and the 32-bit atom value is transmitted instead of the atom name. For any other format, the return value from command is divided into fields separated by white space and each field is converted to a 32-bit integer; an array of integers is transmitted to the selection requester.

The format argument is needed only for compatibility with many selection requesters, except Tcl/Tk. If Tcl/Tk is being used to retrieve the selection then the value is converted back to a string at the requesting end, so format is irrelevant.

A goal of the perl port is to provide better handling of different formats than Tcl/Tk does, which should be possible given perl's wider range of ``types''. Although some thought went into this in very early days of perl/Tk what exactly happens is still "not quite right" and subject to change.

$widget->SelectionOwner?(-selection=>selection)?

SelectionOwner returns the window in this application that owns selection on the display containing $widget, or an empty string if no window in this application owns the selection. Selection defaults to PRIMARY.

$widget->SelectionOwn?(?-command=>callback?,?-selection=>selection?)?

SelectionOwn causes $widget to become the new owner of selection on $widget's display, returning an empty string as result. The existing owner, if any, is notified that it has lost the selection. If callback is specified, it will be executed when some other window claims ownership of the selection away from $widget. Selection defaults to PRIMARY.

KEYWORDS

clear, format, handler, ICCCM, own, selection, target, type


send - Execute a command in a different application

  • APPLICATION NAMES
  • WHAT IS A SEND
  • SECURITY
  • SEE ALSO
  • KEYWORDS

NAME

send - Execute a command in a different application

SYNOPSIS

$result = $widget->send(?options,?app=>cmd?arg arg ...?)

DESCRIPTION

This method arranges for cmd (and args) to be 'sent' to the application named by app. It returns the result or an error (hence above should probably be 'wrapped' in eval{} and $@ tested). App may be the name of any application whose main window is on the display containing the sender's main window; it need not be within the same process. If no arg arguments are present, then the string to be sent is contained entirely within the cmd argument. If one or more args are present, they are concatenated separated by white space to form the string to be sent.

If the initial arguments of the call begin with ``-'' they are treated as options. The following options are currently defined:

-async

Requests asynchronous invocation. In this case the send command will complete immediately without waiting for cmd to complete in the target application; no result will be available and errors in the sent command will be ignored. If the target application is in the same process as the sending application then the -async option is ignored.

--

Serves no purpose except to terminate the list of options. This option is needed only if app could contain a leading ``-'' character.

APPLICATION NAMES

The name of an application is set initially from the name of the program or script that created the application. You can query and change the name of an application with the appname method.

WHAT IS A SEND

The send mechanism was designed to allow Tcl/Tk applications to send Tcl Scripts to each other. This does not map very well onto perl/Tk. Perl/Tk "sends" a string to app, what happens as a result of this depends on the receiving application. If the other application is a Tcl/Tk4.* application it will be treated as a Tcl Script. If the "other" application is perl/Tk application (including sends to self) then the string is passed as an argument to a method call of the following form:

$mainwindow->Receive(string);

There is a default (AutoLoaded) Tk::Receive which returns an error to the sending application. A particular application may define its own Receive method in any class in MainWindow's inheritance tree to do whatever it sees fit. For example it could eval the string, possibly in a Safe "compartment".

If a Tcl/Tk application "sends" anything to a perl/Tk application then the perl/Tk application would have to attempt to interpret the incoming string as a Tcl Script. Simple cases are should not be too hard to emulate (split on white space and treat first element as "command" and other elements as arguments).

SECURITY

The send command is potentially a serious security loophole, since any application that can connect to your X server can send scripts to your applications. Hence the default behaviour outlined above. (With the availability of Safe it may make sense to relax default behaviour a little.)

Unmonitored eval'ing of these incoming "scripts" can cause perl to read and write files and invoke subprocesses under your name. Host-based access control such as that provided by xhost is particularly insecure, since it allows anyone with an account on particular hosts to connect to your server, and if disabled it allows anyone anywhere to connect to your server. In order to provide at least a small amount of security, core Tk checks the access control being used by the server and rejects incoming sends unless (a) xhost-style access control is enabled (i.e. only certain hosts can establish connections) and (b) the list of enabled hosts is empty. This means that applications cannot connect to your server unless they use some other form of authorization such as that provide by xauth.

SEE ALSO

Perl's eval perl's Safe Module system's administrator/corporate security guidelines etc.

KEYWORDS

application, name, remote execution, security, send


Tk::tixWm - Tix's addition to the standard TK wm command.

  • METHODS
  • BUGS
  • AUTHORS
  • SEE ALSO
  • KEYWORDS

NAME

Tk::tixWm - Tix's addition to the standard TK wm command.

SYNOPSIS

$widget->wmCapture

$widget->wmRelease

DESCRIPTION

The wmCapture and the wmRelease methods change the toplevel attribute of Tk widgets.

METHODS

$widget->wmCapture

Converts the toplevel window specified by $widget into a non-toplevel widget. Normally this command is called to convert a Toplevel widget into a Frame widget. The newly-converted frame widget is un-mapped from the screen. To make it appear inside its parent, you must call a geometry manager (e.g. grid or pack) explictly.

$widget->wmRelease

Makes the non-toplevel window specified by $widget into a toplevel widget. Normally this command is called to convert a Frame widget into a Toplevel widget, but it can also be used on any non-toplevel widget (e.g, label). The newly-converted toplevel window is in a withdrawn state. To make it appear on the screen, you must call deiconify after calling wmRelease.

Any data associated with $widget via wm methods (icon, protocol, command etc.) are released, and must be re-established if window is later re-captured.

BUGS

wmCapture does not exist in the Win32 window manager code.

How these methods interact with perl/Tk's class hierarchy is not yet clear. In particular a wmReleased window will not automatically ``inherit'' the Tk::Wm methods, however a wmCaptured window still will. (A released Label might make a good candidate for an Icon.)

AUTHORS

Ioi Kim Lam - ioi@graphics.cis.upenn.edu wrote original Tix version. Updated for tk8.0, Win32 and perl by Nick Ing-Simmons.

SEE ALSO

Tk::Wm
Tk::Mwm
Tk::Frame
Tk::Toplevel

KEYWORDS

window manager, wm, TIX


tkvars - Variables used or set by Tk

  • KEYWORDS

NAME

tkvars - Variables used or set by Tk

DESCRIPTION

The following perl variables are either set or used by Tk at various times in its execution. (For a list of variables used by perl see the perlvar manpage.)

$Tk::library

This variable holds the file name for a directory containing the modules related to Tk. These modules include an initialization file that is normally processed whenever a Tk application starts up, plus other files containing procedures that implement default behaviors for widgets. The initial value of $Tk::library is set when Tk is added to an interpreter; this is done by searching searching for a directory named Tk in the directory where the file Tk.pm, or the first directory Tk in @INC.

The TK_LIBRARY environment variable used by Tcl/Tk is not supported by perl/Tk. Please use @INC to change where modules are searched.

Note: This is Tcl remnant. With perl it makes more sense to use @INC and %INC).

$Tk::patchLevel

Contains a decimal integer giving the current patch level for Tk. The patch level is incremented for each new release or patch, and it uniquely identifies an official version of Tk.

Note: this is Tcl remnant. With perl it makes more sense to use $Tk::VERSION described below.

$Tk::strictMotif

This variable is set to zero by default. If an application sets it to one, then Tk attempts to adhere as closely as possible to Motif look-and-feel standards. For example, active elements such as buttons and scrollbar sliders will not change color when the pointer passes over them.

$Tk::VERSION

The variable holds the current version number of the perl/Tk release in the form major.minor. Major and minor are integers.

The major version number shows on which Tcl/Tk release perl/Tk is based. E.g., 402 means based on Tcls Tk 4.2. (Patchlevel of Tcls Tk are not incorporated because perl/Tk tended to be ``ahead'' of them on some fixes and behind on others. The first digest of the major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing perl/Tk applications and scripts may have to change to work with the new release).

The minor version depends on perl/Tk only. It uses the 'even'='stable', 'odd'='experimental' scheme that linux uses:

 .0xx  - inherently 'alpha'
 .1xx  - experimental 'beta'
 .2xx  - stable
 .3xx  - experimental
 .4xx  - stable
 ...

The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes.

$Tk::version

The variable holds the current version number of the Tk library in the form major.minor. Major and minor are integers. The major version number increases in any Tk release that includes changes that are not backward compatible (i.e. whenever existing Tk applications and scripts may have to change to work with the new release). The minor version number increases with each new release of Tk, except that it resets to zero whenever the major version number changes.

Note: this is Tcl remnant. With perl it makes more sense to use $Tk::VERSION described above.

KEYWORDS

variables, version


Tk::widgets - preload widget classes

NAME

Tk::widgets - preload widget classes

SYNOPSIS

  use Tk::widgets qw(Button Label Frame);

DESCRIPTION

Does a 'require Tk::Foo' for each 'Foo' in the list. May speed startup by avoiding AUTOLOADs.


Tkx - Yet another Tk interface

    • Widget handles
    • Megawidgets
  • ENVIRONMENT
  • SUPPORT
  • LICENSE
  • SEE ALSO

NAME

Tkx - Yet another Tk interface

SYNOPSIS

  use Tkx;
  my $mw = Tkx::widget->new(".");
  $mw->new_button(
       -text => "Hello, world",
       -command => sub { $mw->g_destroy; },
  )->g_pack;
  Tkx::MainLoop();

DESCRIPTION

The Tkx module provides yet another Tk interface for Perl. Tk is a GUI toolkit tied to the Tcl language, and Tkx provides a bridge to Tcl that allows Tk based applications to be written in Perl.

The main idea behind Tkx is that it is a very thin wrapper on top of Tcl, i.e. that what you get is exactly the behaviour you read about in the Tcl/Tk documentation with no surprises added by the Perl layer.

The following functions are provided:

Tkx::MainLoop( )

This will enter the Tk mainloop and start processing events. The function returns when the main window has been destroyed. There is no return value.

Tkx::Ev( $field, ... )

This creates an object that if passed as the first argument to a callback will expand the corresponding Tcl template substitutions in the context of that callback. The description of Tkx::foo below explain how callback arguments are provided.

The $field should be a string like "%A" or "%x". The available substitutions are described in the Tcl documentation for the bind command.

Tkx::SplitList( $list )

This will split up a Tcl list into Perl list. The individual elements of the list are returned as separate elements:

    @a = Tkx::SplitList(Tkx::set("a"));

This function will croak if the argument is not a well formed list or if called in scalar context.

Tkx::foo( @args )

Any other function will invoke the foo Tcl function with the given arguments. The name foo first undergo the following substitutions of embedded underlines:

    foo_bar   --> "foo", "bar"   # break into words
    foo__bar  --> "foo::bar"     # access namespaces
    foo___bar --> "foo_bar"      # when you actually need a '_'

This allow us conveniently to map most of the Tcl namespace to Perl. If this mapping does not suit you, use Tkx::i::call($func, @args) >>. This will invoke the function named by $func with no name substitutions or magic.

Examples:

    Tkx::expr("3 + 3");
    Tkx::package_require("BWidget");
    Tkx::DynamicHelp__add(".", -text => "Hi there");
    if (Tkx::tk_windowingsystem() eq "x11") { ... }
    if (Tkx::tk___messageBox( ... ) eq "yes") { ... }

The arguments passed can be plain scalars, array references, code references, or scalar references.

Array references are converted to Tcl lists. The arrays can contain other plain scalars or array references to form nested lists.

For Tcl APIs that require callbacks you can pass a reference to a Perl function. Alternatively an array reference with a code reference as the first element, will allow the callback to receive the rest of the elements as arguments when invoked. If the second element of the array is an Tkx::Ev() object, then the templates it contain will be expanded at the time of the calllback. Some callback examples:

    Tkx::after(3000, sub { print "Hi" });
    Tkx::button(".b", -command [\&Tkx::destroy, "."]);
    Tkx::bind(".", "<Key>", [sub { print "$_[0]\n"; }, Tkx::Ev("%A")]);
    Tkx::bind(".", "<Button-1>", [
       sub {
           my($x, $y) = @_;
           print "Clicked at $x $y\n";
       },
       Tkx::Ev("%x", "%y"),
    ]);

For Tcl APIs that require variables to be passed, you might pass a reference to a Perl scalar. The scalar will be watched and updated in the same way as the Tcl variable would.

The Tcl string result is returned in both scalar and array context. Tcl errors are propagated as Perl exceptions.

If the boolean variable $Tkx::TRACE is set to a true value, then a trace of all commands passed to Tcl will be printed on STDERR. This variable is initialized from the PERL_TKX_TRACE environment variable. The trace is useful for debugging and if you need to report errors to the Tcl maintainers in terms of Tcl statements. The trace lines are prefixed with:

    Tkx-$seq-$ts-$file-$line:

where $seq is a sequence number, $ts is a timestamp in seconds since the first command was issued, and $file and $line indicate on which source line this call was triggered.

All these functions can be exported by Tkx if you grow tired of typing the Tkx:: prefix. Example:

    use strict;
    use Tkx qw(MainLoop button pack destroy);

    pack(button(".b", -text => "Press me!", -command => [\&destroy, "."]));
    MainLoop;

No functions are exported by default.

Widget handles

The class Tkx::widget is used to wrap Tk widget paths or names. These objects stringify as the path they wrap.

The following methods are provided:

Tkx::widget->_Mega( $widget, $class )

This register $class as the one implementing $widget widgets. See Megawidgets.

$w = Tkx::widget->new( $path )

This constructs a new widget handle for a given path. It is not a problem to have multiple handle objects to the same path or to create handles for paths that does not exist yet.

$w->_data

Returns a hash that can be used to keep instance specific data. This is useful for holding instance data for megawidgets. The data is attached to the underlying widget, so if you create another handle to the same widget it will return the same hash via its _data() method.

The data hash is automatically destroyed when the corresponding widget is destroyed.

$w->_parent

Returns a handle for the parent widget. Returns undef if there is no parent, which will only happen if $w is ".", the main window.

$w->_kid( $name )

Returns a handle for a kid widget with the given name. The $name can contain dots to access grandkids. There is no check that a kid with the given name actually exists, so this method can't fail. This is a feature. It can for instance be used to construct names of widgets to be created later.

$w->_class( $class )

Sets the widget handle class for the current path. This will both change the class of the current handle and make sure later handles created for the path belong to the given class. The class should normally be a subclass of Tkx::widget. Overriding the class for a path is useful for implementing megawidgets. Kids of $w are not affected by this, unless the class overrides the _nclass method.

$w->_nclass

This returns the default widget handle class that will be used for kids and parent. Subclasses might want to override this method. The default implementation always returns Tkx::widget.

$w->_mpath( $method )

This returns a Tcl widget path that will be used to forward any m_foo method calls. Megawidget classes might want to override this method. The default implementation returns $w.

$new_w = $w->new_foo( @args )

This creates a new foo widget as a child of the current widget. It will call the foo Tcl command and pass it a new unique subpath of the current path. The handle to the new widget is returned. Any double underscores in the name foo is expanded as described for Tkx::foo() above.

Example:

    $w->new_label(-text => "Hello", -relief => "sunken");

The name selected for the child will be the first letter in the widget. If that name is not unique a number is appended to ensure uniqueness among the children. If a -name argument is passed it is used to form the name and then removed from the arglist passed to Tcl. Example:

    $w->new_iwidgets__calendar(-name => "cal");

If a megawidget implementation class has be registered for foo, then its _Populate method is called instead of passing widget creation to Tcl.

$w->m_foo( @args )

This will invoke the foo subcommand for the current widget. This is the same as:

    $func = "Tkx::$w";
    &$func(expand("foo"), @args);

where the expand() function expands underscores as described for Tkx::foo() above. Note that methods that do not start with a prefix of the form /^_/ or /^[a-zA-Z]_/ are also treated as the m_ methods.

Example:

    $w->m_configure(-background => "red");

Subclasses might override the _mpath() method to have m_foo forward the subcommand somewhere else than the current widget.

$w->g_foo( @args )

This will invoke the foo Tcl command with the current widget as first argument. This is the same as:

    $func = "Tkx::foo";
    &$func($w, @args);

Any underscores in the name foo are expanded as described for Tkx::foo() above.

Example:

    $w->g_pack_forget;
$w->foo( @args )

If the method does not start with "new_" or have a prefix of the form /^_/ or /^[a-zA-Z]_/, then it is treated as if it had the "m_" prefix, i.e. the foo subcommand for the current widget is invoked.

The method names with prefix /^_/ and /^[a-zA-Z]_/ are reserved for future extensions to this API.

Megawidgets

Megawidgets can be implemented in Perl and used by Tkx. To declare a megawidget make a Perl class like this one:

    package Foo;
    use base 'Tkx::widget';
    Foo->_Mega("foo");

    sub _Populate {
        my($class, $widget, $path, %opt) = @_;
        ...
    }

The megawidget class should inherit from Tkx::widget and will register itself by calling the _Mega() class method. In the example above we tell Tkx that any "foo" widgets should be handled by the Perl class "Foo" instead of Tcl. When a new "foo" widget is instantiated with:

    $w->new_foo(-text => "Hi", -foo => 1);

then the _Populate() class method of Foo is called. It will be passed the widget type to create, the full path to use as widget name and any options passed in. The widget name is passed in so that a single Perl class can implement multiple widget types.

The _Populate() class should create a root object with the given $path as name and populate it with the internal widgets. Normally the root object will be forced to belong to the implementation class so that it can trap various method calls on it. By using the _class() method to set class _Populate() can ensure that new handles to this megawidget also use this class.

The implementation class can define an _ipath() method to delegate any m_foo method calls to one of its subwidgets and it might want to override the m_configure() and m_cget() methods if it implements additional options or want more control over delegation. The class Tkx::MegaConfig provide implementations of m_configure() and m_cget() that can be useful for controlling delegation of configuration options.

See the Tkx::LabEntry manpage for a trivial example megawidget.

ENVIRONMENT

The PERL_TKX_TRACE environment variable initialize the $Tkx::TRACE setting.

SUPPORT

If you have questions about this code or want to report bugs send a message to the <tcltk@perl.org> mailing list. To subscribe to this list send an empty message to <tcltk-subscribe@perl.org>.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 2005 ActiveState. All rights reserved.

SEE ALSO

the Tkx::Tutorial manpage, the Tkx::MegaConfig manpage, the Tcl manpage

Alternative Tk bindings for Perl are described in the Tcl::Tk manpage and the Tk manpage.

More information about Tcl/Tk can be found at http://www.tcl.tk/. Tk documentation is also available at http://aspn.activestate.com/ASPN/docs/ActiveTcl/at.pkg_index.html.


Tkx::LabEntry - Labeled entry widget

  • LICENSE
  • SEE ALSO

NAME

Tkx::LabEntry - Labeled entry widget

SYNOPSIS

  use Tkx;
  use Tkx::LabEntry;

  my $mw = Tkx::widget->new(".");

  my $e = $mw->new_tkx_LabEntry(-label => "Name");
  $e->g_pack;

  my $b = $mw->new_button(
      -text => "Done",
      -command => sub {
          print $e->get, "\n";
          $mw->g_destroy;
      },
  );
  $b->g_pack;

  Tkx::MainLoop();

DESCRIPTION

The Tkx::LabEntry module implements a trivial megawidget. Its main purpose is to demonstrate how to use the Tkx::MegaConfig baseclass.

Once the Tkx::LabEntry module has been loaded, then its widgets can be constructed in the normal way using the tkx_LabEntry name. Besides having a label (whose text can be accessed with the -label configuration option), these widgets behave exactly like an entry would.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 2005 ActiveState. All rights reserved.

SEE ALSO

The source code of Tkx::LabEntry.

the Tkx::MegaConfig manpage, the Tkx manpage


Tkx::MegaConfig - handle configuration options for megawidgets

  • LICENSE
  • SEE ALSO

NAME

Tkx::MegaConfig - handle configuration options for megawidgets

SYNOPSIS

  package Foo;
  use base qw(Tkx::widget Tkx::MegaConfig);

  __PACKAGE__->_Mega("foo");
  __PACKAGE__->_Config(
      -option  => [$where, $dbName, $dbClass, $default],
  );

DESCRIPTION

The Tkx::MegaConfig class provide implementations of m_configure() and m_cget() that can handle configuration options for megawidgets. How these methods behave is set up by calling the _Config() class method. The _Config() method takes a set option/option spec pairs as argument.

An option argument is either the name of an option with leading '-' or the string 'DEFAULT' if this spec applies to all option with no explict spec.

The spec should be an array reference. The first element of the array ($where) describe how this option is handled. Some $where specs take arguments. If you need to provide argument replace $where with an array reference containg [$where, @args]. The rest specify names and default for the options database, but is currently ignored.

The following $where specs are understood:

.foo

Delegate the given configuration option to the "foo" kid of the mega widget. The name "." can be used to deletegate to the megawidget root itself. An argument can be given to delegate using a different name on the "foo" widget.

METHOD

Call the _config_opt method. For m_cget() no arguments are given, while for m_configure() the new value is passed. An argument can be given to forward to that method instead of _config_opt.

PASSIVE

Store or retrieve option from $self->_data.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 2005 ActiveState. All rights reserved.

SEE ALSO

the Tkx manpage, the Tkx::LabEntry manpage

Inspiration for this module comes from the Tk::ConfigSpecs manpage.


Tkx::Tutorial - How to use Tkx

    • Hello World
    • Hello World with objects
    • Hello World expanded
    • Setting up a menu line
    • Using Tcl packages
    • Subclassing Tkx::widget
  • LICENSE
  • SEE ALSO

NAME

Tkx::Tutorial - How to use Tkx

DESCRIPTION

Tk is a toolkit that allows you to create applications with graphical interfaces for Windows, Mac OS X and X11. The Tk toolkit is native to the Tcl programming language, but its ease of use and cross-platform availability has made it the GUI toolkit of choice for many other dynamic languages as well.

Tkx is a Perl module that makes the Tk toolkit available to Perl programs. By loading the Tkx module Perl programs can create windows and fill them with text, images, buttons and other controls that make up the user interface of the application.

Hello World

Let's start with the mandatory exercise of creating an application that greats the world. Here we make the application window contain a single button which will shut down the application if clicked. The code to make this happen is:

    use Tkx;

    Tkx::button(".b",
        -text => "Hello, world",
        -command => sub { Tkx::destroy("."); },
    );
    Tkx::pack(".b");

    Tkx::MainLoop()

Save this to a file called hello.pl and then run perl hello.pl to start up the application. A window with the text "Hello, world" should appear on your screen.

After the Tkx module has been loaded by the use Tkx statement the application will show an empty window called ".". We create a button with the name ".b" and tell the window to display the button with the call to Tkx::pack(). After the layout of the window has been set up we need to pass control back to Tk so that it can draw the window and invoke our callback if the button is clicked. This is achieved by the Tkx::MainLoop() call at the end. Clicking the button will invoke the subroutine registered with the -command option of the button. In this case the callback simply destroys the window, which in turn will terminate the application.

For reference this is how the same program would look in Tcl:

    package require Tk

    button .b \
        -text "Hello, world" \
        -command { destroy . }
    pack .b

This program can be executed by the tclsh binary that comes with Tcl/Tk. As you can see the code is mostly identical, but with a slightly different syntax. The only real difference is that the call to MainLoop() is implicit in Tcl and does not have to be spelled out.

Tkx does not come with documentation that explain all the widgets (like "button" above) that are available for use. Instead you will need to read the mostly excellent documentation that comes with Tcl/Tk and then figure out how this translates to Tkx yourself. As you can see this translation is straight forward. You basically only have add the prefix "Tkx::" to all the functions and use the Perl way of passing arguments. Tcl is a very simple language, so it should not take long to understand enough of it to be able to read its documentation with ease.

A great place to look up the Tk documentation is http://aspn.activestate.com/ASPN/docs/ActiveTcl/at.pkg_index.html. This documents core Tk as well as all the useful add-on packages that are part of ActiveTcl. The ActiveTcl HTML documentation can also be downloaded from http://downloads.activestate.com/ActiveTcl/html/ and installed locally. The official Tcl/Tk docs are found at http://www.tcl.tk/doc/.

Hello World with objects

The windows and controls that make up a Tk interface are called widgets. The widgets are identified by path names of the form .foo.bar.baz. These names are hierarchical in the same way as file system names are, but "." is used instead of "/" to separate levels. The name .foo.bar.baz is the name of a widget that is child of widget .foo.bar which in turn is a child of .foo. At the top of this hierarchy we have a widget called ., which is the main window of the application.

The Tkx module provide a class called Tkx::widget, that can be used to hide the details of Tk path names from Tkx applications. This provide a more "perlish" way to create and manipulate Tk widgets.

Our "Hello, world" program can be rewritten like this using the Tkx::widget class:

    use Tkx;

    my $mw = Tkx::widget->new(".");
    my $b = $mw->new_button(
        -text => "Hello, world",
        -command => sub { $mw->g_destroy; },
    );
    $b->g_pack;

    Tkx::MainLoop()

By loading the Tkx module we make the Tkx::widget class available and create the main window (the widget called .). Next we instantiate a new Tkx::widget object wrapping the main window. It is customary to name this object $mw.

To create a new button child widget we call $mw->new_button method. Constructor methods are always prefixed with new_. The rest of the method name is the name of the Tk widget to create; i.e. "button" in this case. Arguments are passed as before.

Calling a "g_" method will invoke the corresponding Tk command with the widget path as argument. In the code above we destroy the main window by calling $mw->g_destroy and we pack the button in the main window by invoking $b->g_pack.

In the end we need to invoke the MainLoop as before.

For trivial programs like the one above using Tkx::widget wrappers does not appear to be a win, but as the application grows and the Tk path names get longer it surely is.

Hello World expanded

In order to introduce a few more Tkx features, we now present a slightly expanded version of the previous Hello World program. This time we added line numbers to the program so that it is easier to reference back to its statements:

     1  use strict;
     2  use Tkx;
     3
     4  my $mw = Tkx::widget->new(".");
     5  $mw->g_wm_title("Hello, world");
     6  $mw->g_wm_minsize(300, 200);
     7
     8  my $b;
     9  $b = $mw->new_button(
         10      -text => "Hello, world",
         11      -command => sub {
         12          $b->m_configure(
         13              -text => "Goodbye, cruel world",
         14          );
         15          Tkx::after(1500, sub { $mw->g_destroy });
         16      },
         17  );
         18  $b->g_pack(
         19      -padx => 10,
         20      -pady => 10,
         21  );
         22
         23  Tkx::tk___messageBox(
         24     -parent => $mw,
         25     -icon => "info",
         26     -title => "Tip of the Day",
         27     -message => "Please be nice!",
         28  );
         29
         30  Tkx::MainLoop()

The first thing we added is the use strict statement, simply because that's a good idea in general.

In line 5 and 6 we set up some window manager attributes of the main application window. What is noteworthy here is that we use underscore in the g_ method names where Tcl would use space between words. Same rules apply to the function names in the Tkx:: namespace directly. We could alternatively have modified the window attributes with:

    Tkx::wm_title($mw, "Hello, world");
    Tkx::wm_minsize($mw, 300, 200);

which in Tcl would have been:

    wm title . "Hello, world"
    wm minsize . 300 200

The rule is: A single underscore on the Perl side turns into space on the Tcl side.

In line 11 to 16 we have expanded the button callback to change the text of button and then wait 1.5 seconds before we shut down the application. In addition to the "g_" methods described in the previous section, Tkx::widget also provide "m_" methods which are forwarded as Tcl subcommands of the current widget. The most commonly used subcommand is "configure" that is used to change the attributes of a widget as we do in line 12. Since we now reference $b from the callback, we had to declare the variable upfront in line 8 instead of declaring it together with the assignment as we did previously. In line 15 we schedule for the window to be destroyed after a delay of 1500 ms. The delay is needed so that the new button text is actually show before the window goes away.

Btw, the "m_" method prefix is actually optional, so you might prefer just to leave it out.

Padding around buttons is usually a good idea as we now do in line 18.

In line 23 we invoke the messageBox command to pop up a useful reminder to our user. But what's up with the "tk___" prefix? In the Tcl docs you will find that the name of this command is actually "tk_messageBox". Remember the previous rule that an underscore in Tkx:: names turn into a space on the Tcl side? If you try to call Tkx::tk_messageBox() you will get an error telling you:

    bad option "messageBox": must be appname, caret, scaling,
    useinputmethods, or windowingsystem

What happens is that Tkx invoked the "tk messageBox" command, but the Tcl "tk" command only take the subcommands listed in the error message above and refuse to do anything about "messageBox". In order to invoke Tcl commands with underscore their name, you need to triple the underscore on the Perl side, which gives us Tkx::tk___messageBox(). Double underscores in names have yet another meaning that we will tell you about in the next section.

Setting up a menu line

Most real GUI application will need a menu line at the top of the application window or screen. The following runnable program shows how a minimal menu can be set up with Tkx:

     1  #!/usr/bin/perl -w
     2
     3  use strict;
     4  use Tkx;
     5
     6  our $VERSION = "1.00";
     7
     8  (my $progname = $0) =~ s,.*[\\/],,;
     9  my $IS_AQUA = Tkx::tk_windowingsystem() eq "aqua";
         10
         11  Tkx::package_require("style");
         12  Tkx::style__use("as", -priority => 70);
         13
         14  my $mw = Tkx::widget->new(".");
         15  $mw->configure(-menu => mk_menu($mw));
         16
         17  Tkx::MainLoop();
         18  exit;
         19
         20  sub mk_menu {
         21      my $mw = shift;
         22      my $menu = $mw->new_menu;
         23
         24      my $file = $menu->new_menu(
         25          -tearoff => 0,
         26      );
         27      $menu->add_cascade(
         28          -label => "File",
         29          -underline => 0,
         30          -menu => $file,
         31      );
         32      $file->add_command(
         33          -label => "New",
         34          -underline => 0,
         35          -accelerator => "Ctrl+N",
         36          -command => \&new,
         37      );
         38      $mw->g_bind("<Control-n>", \&new);
         39      $file->add_command(
         40          -label   => "Exit",
         41          -underline => 1,
         42          -command => [\&Tkx::destroy, $mw],
         43      ) unless $IS_AQUA;
         44
         45      my $help = $menu->new_menu(
         46          -name => "help",
         47          -tearoff => 0,
         48      );
         49      $menu->add_cascade(
         50          -label => "Help",
         51          -underline => 0,
         52          -menu => $help,
         53      );
         54      $help->add_command(
         55          -label => "\u$progname Manual",
         56          -command => \&show_manual,
         57      );
         58
         59      my $about_menu = $help;
         60      if ($IS_AQUA) {
         61          # On Mac OS we want about box to appear in the application
         62          # menu.  Anything added to a menu with the name "apple" will
         63          # appear in this menu.
         64          $about_menu = $menu->new_menu(
         65              -name => "apple",
         66          );
         67          $menu->add_cascade(
         68              -menu => $about_menu,
         69          );
         70      }
         71      $about_menu->add_command(
         72          -label => "About \u$progname",
         73          -command => \&about,
         74      );
         75
         76      return $menu;
         77  }
         78
         79
         80  sub about {
         81      Tkx::tk___messageBox(
         82          -parent => $mw,
         83          -title => "About \u$progname",
         84          -type => "ok",
         85          -icon => "info",
         86          -message => "$progname v$VERSION\n" .
         87                      "Copyright 2005 ActiveState. " .
         88                      "All rights reserved.",
         89      );
         90  }

We start out as all proper Perl programs should by enabling warnings and stricture at line 1 and 3. Then we load Tkx which will create our main application window at line 4.

In line 9 we initialize $IS_AQUA constant. Aqua is the native interface of Mac OS X. We need this constant because the menu layout on Aqua is not the same as for the other windowing systems. Note that Tk on Mac OS X can be compiled against either Aqua or X11. When our application runs under X11 we want to use the standard Unix menu layout, so it would not be correct to just make our code conditional on what operating system it runs under ($^O eq 'darwin' for Mac OS X).

In line 11 and 12 we override the default look&feel style of Tk to a more modern variant. Tcl packages can be loaded with the Tkx::package_require() function and we can access the Tcl command style::use as Tkx::style__use in Perl, i.e. we need to turn the double colon into a double underscore. More about Tcl packages and namespaces in the next section.

In line 14 we obtain a Tkx::widget reference to the main window as before and then we simply set up the application menu by setting up the -menu option of the main window in line 15.

In a real application there would be additional code between line 15 and 17 to set up the rest of the application window, but for this demonstration we just leave the window empty.

In line 17 we ask Tk to start processing events, by invoking Tkx::MainLoop(). This function will return when the application window has been destroyed and when that happens we are done at line 18.

The application menu itself is set up and returned by the mk_menu() function in line 20 to 77. This code should be easy enough to follow. Note how we make File | New and Help | Foo Manual both reference functions that are not yet written. The application will still run, but when you try to invoke these menu entries you get an "Application Error Dialog" from Tk. It is handy to be able to leave stubs like this around during the development. Just remember to add the new and show_manual functions before the application ships. :-)

The -underline options are provided to make it possible to select menu entries with the keyboard. The corresponding character of the -label will be underlined and you will be able to select this entry by pressing the key when the menu is active.

It is also possible to set up direct keyboard shortcuts like we done for the File | New function at line 32. Note that the -accelerator option only adds the text to the menu item, so we need to use an explicit call to set up this binding as done in line 38.

For Aqua we don't want to add the "File | Exit" entry to the menu because the OS itself always provide a Quit action in the application menu. Proper Aqua applications will also need to add the "About" function on the application menu instead of the "Help" menu as is common on other platforms.

The menu names "apple" and "help" provided in line 46 and 65 has special significance to Tk. Menu items added to the "apple" menu will show up in the application menu. The name is historic from the time when this stuff would actually show in the menu with the picture of the Apple logo. In Mac OS X these entries show up at the top of the menu just right of the apple. If not provided Tk will provide its own "About" entry that will tell you about what version of Tcl/Tk you are using. A menu called "help" menu will be flushed right on Unix even though this style seems to be out of fashion in modern Unix applications.

The Tkx distribution contain a script called menu which is a runnable version of the program shown here. You might want to use this as a starting point for your own Tkx applications.

Using Tcl packages

When the Perl application starts up and load Tkx, the only functions available in the Tkx:: namespace are those commands provided by core Tcl/Tk. These commands are described in the "Tcl" and "Tk" sections at http://aspn.activestate.com/ASPN/docs/ActiveTcl/at.pkg_index.html.

Additional commands can be loaded from Tcl packages. Once loaded new commands show up in the Tkx:: namespace. This example loads the "Tktable" package in order to make the table command to create table widgets available:

    use Tkx;
    Tkx::package_require("Tktable");

    my $mw = Tkx::widget->new(".");
    my $t = $mw->new_table(
        -rows => 5,
        -cols => 3,
    );
    $t->g_pack;

    Tkx::MainLoop()

Packages are loaded by calling the Tkx::package_require() function taking the package name as argument. An optional version number can be provided as the second argument if you want to make sure a certain version or newer is loaded.

One source of confusion here is what the proper spelling of the package name to provide to Tkx::package_require() is. The Tcl/Tk documentation will call the package in the example above TkTable (with two upper case "T"s) and not really mention the exact spelling of the package name (only one upper case "T"). In some cases the "synopsis" section describing the package will spell out the package name, but in cases like this we have found no better way than to peek into the pkgIndex.tcl files in the Tcl lib/ area if loading the package fails. The package documented as "BWidgets" should be loaded as "BWidget" (without the "s") and the package documented as "IWidgets" should be loaded as "Iwidgets" (with a lower case "w"). Somebody ought to be spanked.

Most modern Tcl packages will not create names at the top level like TkTable did above. Instead they will create functions in a Tcl namespace with a name matching the package name. In the menu example of the previous section we loaded the "style" package which created a command called "use" in the "style" namespace. This command can be referenced as "::style::use" or "style::use" from Tcl. From Perl this maps to a function called Tkx::style__use, i.e. we replace the double colon with double underscore and ignore the colon in the front. Read the Tkx manpage for details about how sequences of "_" in Tkx:: names are mapped to Tcl names.

Subclassing Tkx::widget

In Tkx applications it is often convenient to use your own subclass of Tkx::widget where you can introduce shortcuts and adapters for the raw Tcl commands. This shows an example class, that should be saved to the file MyWidget.pm:

     1  package MyWidget;
     2
     3  use strict;
     4  use base qw(Tkx::widget);
     5  use Carp qw(croak);
     6
     7  sub messageBox {
     8      my $self = shift;
     9      return Tkx::tk___messageBox(-parent => $self, @_);
         10  }
         11
         12  sub getOpenFile {
         13      my $self = shift;
         14      return Tkx::tk___getOpenFile(-parent => $self, @_);
         15  }
         16
         17  sub bell {
         18      my $self = shift;
         19      Tkx::bell(-displayof => $self, @_);
         20  }
         21
         22  sub children {
         23      my $self = shift;
         24      croak("children must be called in list context")
         25          unless wantarray;
         26      return map { $self->_nclass->new($_) }
         27             Tkx::SplitList($self->g_winfo_children);
         28  }
         29
         30  sub pack {
         31      my $self = shift;
         32      $self->g_pack(@_);
         33      return $self;
         34  }
         35
         36  sub _nclass {
         37      return __PACKAGE__;
         38  }
         39
         40  1;

In the main program you would use it like this:

    use Tkx;
    use MyWidget;
    my $mw = MyWidget->new(".");
    $mw->messageBox(...);

    ...

    for my $kid ($mw->children) {
        ...
    }

    Tkx::MainLoop();

The MyWidget class above provide shortcuts for the "messageBox" and "getOpenFile" in order to hide the triple underscore ugliness and propegate the -parent attribute. Similar reasoning exists for the "bell".

The children method is provided since calling $w->g_winfo_children just return a Tcl-list of widget path names. What we usually want to get back is a list of widget objects, so that we can call further methods on them.

The pack method is provided so that we can initialize and pack a widget in the same statement and avoid repeated typing of "g_" method prefix:

    my $b = $mw->new_button(...)->pack;

The _nclass method need to be overridden so that any new widget kids created also ends up as MyWidget objects. This method is called internally by methods like $mw->new_button(...) to determine which kind of object will get a chance to wrap the newly created widget path.

Having you own application specific widget class provide a place to add methods discovered by refactoring of repeated code in your application.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 2005 ActiveState. All rights reserved.

SEE ALSO

the Tkx manpage

The bundled sample programs; the tkx-ed manpage, tkx-prove.


UDDI::Lite - Library for UDDI clients in Perl

  • OVERVIEW OF CLASSES AND PACKAGES
    • UDDI::Lite
    • UDDI::Data
    • AUTODISPATCHING
  • BUGS AND LIMITATIONS
  • AVAILABILITY
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

UDDI::Lite - Library for UDDI clients in Perl

SYNOPSIS

  use UDDI::Lite;
  print UDDI::Lite
    -> proxy('http://uddi.microsoft.com/inquire')
    -> find_business(name => 'old')
    -> result
    -> businessInfos->businessInfo->serviceInfos->serviceInfo->name;

The same code with autodispatch:

  use UDDI::Lite +autodispatch =>
    proxy => 'http://uddi.microsoft.com/inquire'
  ;

  print find_business(name => 'old')
    -> businessInfos->businessInfo->serviceInfos->serviceInfo->name;

Or with importing:

  use UDDI::Lite
    'UDDI::Lite' => [':inquiry'],
    proxy => 'http://uddi.microsoft.com/inquire'
  ;

  print find_business(name => 'old')
    -> businessInfos->businessInfo->serviceInfos->serviceInfo->name;

Publishing API:

  use UDDI::Lite
    import => ['UDDI::Data'],
    import => ['UDDI::Lite'],
    proxy => "https://some.server.com/endpoint_fot_publishing_API";

  my $auth = get_authToken({userID => 'USERID', cred => 'CRED'})->authInfo;
  my $busent = with businessEntity =>
    name("Contoso Manufacturing"),
    description("We make components for business"),
    businessKey(''),
    businessServices with businessService =>
      name("Buy components"),
      description("Bindings for buying our components"),
      serviceKey(''),
      bindingTemplates with bindingTemplate =>
        description("BASDA invoices over HTTP post"),
        accessPoint('http://www.contoso.com/buy.asp'),
        bindingKey(''),
        tModelInstanceDetails with tModelInstanceInfo =>
          description('some tModel'),
          tModelKey('UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4')
  ;
  print save_business($auth, $busent)->businessEntity->businessKey;

DESCRIPTION

UDDI::Lite for Perl is a collection of Perl modules which provides a simple and lightweight interface to the Universal Description, Discovery and Integration (UDDI) server.

To learn more about UDDI, visit http://www.uddi.org/.

The main features of the library are:

  • Supports both inquiry and publishing API

  • Builded on top of SOAP::Lite module, hence inherited syntax and features

  • Supports easy-to-use interface with convinient access to (sub)elements and attributes

  • Supports HTTPS protocol

  • Supports SMTP protocol

  • Supports Basic/Digest server authentication

OVERVIEW OF CLASSES AND PACKAGES

This table should give you a quick overview of the classes provided by the library.

 UDDI::Lite.pm
 -- UDDI::Lite         -- Main class provides all logic
 -- UDDI::Data         -- Provides extensions for serialization architecture
 -- UDDI::Serializer   -- Serializes data structures to UDDI/SOAP package
 -- UDDI::Deserializer -- Deserializes result into objects
 -- UDDI::SOM          -- Provides access to deserialized object tree

UDDI::Lite

All methods that UDDI::Lite gives you access to can be used for both setting and retrieving values. If you provide no parameters, you'll get current value, and if you'll provide parameter(s), new value will be assigned and method will return object (if not stated something else). This is suitable for stacking these calls like:

  $uddi = UDDI::Lite
    -> on_debug(sub{print@_})
    -> proxy('http://uddi.microsoft.com/inquire')
  ;

Order is insignificant and you may call new() method first. If you don't do it, UDDI::Lite will do it for you. However, new() method gives you additional syntax:

  $uddi = new UDDI::Lite
    on_debug => sub {print@_},
    proxy => 'http://uddi.microsoft.com/inquire'
  ;

new() accepts hash with method names and values, and will call appropriate method with passed value.

Since new() is optional it won't be mentioned anymore.

Other available methods inherited from SOAP::Lite and most usable are:

proxy()

Shortcut for transport->proxy(). This lets you specify an endpoint and also loads the required module at the same time. It is required for dispatching SOAP calls. The name of the module will be defined depending on the protocol specific for the endpoint. SOAP::Lite will do the rest work.

on_fault()

Lets you specify handler for on_fault event. Default behavior is die on transport error and does nothing on others. You can change this behavior globally or locally, for particular object.

on_debug()

Lets you specify handler for on_debug event. Default behavior is do nothing. Use +trace/+debug option for UDDI::Lite instead.

UDDI::Data

You can use this class if you want to specify value and name for UDDI elements. For example, UDDI::Data->name('businessInfo')->value(123) will be serialized to <businessInfo>123</businessInfo>, as well as UDDI::Data-name(businessInfo => 123)>.

If you want to provide names for your parameters you can either specify

  find_business(name => 'old')

or do it with UDDI::Data:

  find_business(UDDI::Data->name(name => 'old'))

Later has some advantages: it'll work on any level, so you can do:

  find_business(UDDI::Data->name(name => UDDI::Data->name(subname => 'old')))

and also you can create arrays with this syntax:

  find_business(UDDI::Data->name(name =>
    [UDDI::Data->name(subname1 => 'name1'),
     UDDI::Data->name(subname2 => 'name2')]))

will be serialized into:

  <find_business xmlns="urn:uddi-org:api" generic="1.0">
    <name>
      <subname1>name1</subname1>
      <subname2>name2</subname2>
    </name>
  </find_business>

For standard elements more convinient syntax is available:

  find_business(
    findQualifiers(findQualifier('sortByNameAsc',
                                 'caseSensitiveMatch')),
    name('M')
  )

and

  find_business(
    findQualifiers([findQualifier('sortByNameAsc'),
                    findQualifier('caseSensitiveMatch')]),
    name('M')
  )

both will generate:

  <SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
      <find_business xmlns="urn:uddi-org:api" generic="1.0">
        <findQualifiers>
          <findQualifier>sortByNameAsc</findQualifier>
          <findQualifier>caseSensitiveMatch</findQualifier>
        </findQualifiers>
        <name>M</name>
      </find_business>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

You can use ANY valid combinations (according to "UDDI Programmer's API Specification"). If you try to generate something unusual, like name(name('myname')), you'll get:

  Don't know what to do with 'name' and 'name' elements ....

If you REALLY need to do it, use UDDI::Data syntax described above.

As special case you can pass hash as the first parameter of method call and values of this hash will be added as attributes to top element:

  find_business({maxRows => 10}, UDDI::Data->name(name => old))

gives you

  <find_business xmlns="urn:uddi-org:api" generic="1.0" maxRows="10">
    ....
  </find_business>

You can also pass back parameters exactly as you get it from method call (like you probably want to do with authInfo).

You can get access to attributes and elements through the same interface:

  my $list = find_business(name => old);
  my $bis = $list->businessInfos;
  for ($bis->businessInfo) {
    my $s = $_->serviceInfos->serviceInfo;
    print $s->name,        # element
          $s->businessKey, # attribute
          "\n";
  }

To match advantages provided by with operator available in other languages (like VB) we provide similar functionality that adds you flexibility:

    with findQualifiers =>
      findQualifier => 'sortByNameAsc',
      findQualifier => 'caseSensitiveMatch'

is the same as:

    with(findQualifiers =>
      findQualifier('sortByNameAsc'),
      findQualifier('caseSensitiveMatch'),
    )

and:

    findQualifiers->with(
      findQualifier('sortByNameAsc'),
      findQualifier('caseSensitiveMatch'),
    )

will all generate the same code as mentioned above:

    findQualifiers(findQualifier('sortByNameAsc',
                                 'caseSensitiveMatch')),

Advantage of with syntax is the you can specify both attributes and elements through the same interface. First argument is element where all other elements and attributes will be attached. Provided examples and tests cover different syntaxes.

AUTODISPATCHING

UDDI::Lite provides autodispatching feature that lets you create code that looks similar for local and remote access.

For example:

  use UDDI::Lite +autodispatch =>
    proxy => 'http://uddi.microsoft.com/inquire';

tells autodispatch all UDDI calls to 'http://uddi.microsoft.com/inquire'. All subsequent calls can look like:

  find_business(name => 'old');
  find_business(UDDI::Data->name(name => 'old'));
  find_business(name('old'));

BUGS AND LIMITATIONS

  • Interface is still subject to change.

  • Though HTTPS/SSL is supported you should specify it yourself (with proxy or endpoint) for publishing API calls.

AVAILABILITY

For now UDDI::Lite is distributed as part of SOAP::Lite package. You can download it from ( http://soaplite.com/ ) or from CPAN ( http://search.cpan.org/search?dist=SOAP-Lite ).

SEE ALSO

the SOAP::Lite manpage ( http://search.cpan.org/search?dist=SOAP-Lite ) UDDI ( http://search.cpan.org/search?dist=UDDI )

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


UNIVERSAL - base class for ALL classes

  • EXPORTS

NAME

UNIVERSAL - base class for ALL classes (blessed references)

SYNOPSIS

    $is_io = $fd->isa("IO::Handle");
    $is_io = Class->isa("IO::Handle");

    $sub = $obj->can("print");
    $sub = Class->can("print");

    use UNIVERSAL qw( isa can VERSION );
    $yes = isa $ref, "HASH" ;
    $sub = can $ref, "fandango" ;
    $ver = VERSION $obj ;

DESCRIPTION

UNIVERSAL is the base class which all bless references will inherit from, see the perlobj manpage.

UNIVERSAL provides the following methods and functions:

$obj->isa( TYPE )
CLASS->isa( TYPE )
isa( VAL, TYPE )

Where

TYPE

is a package name

$obj

is a blessed reference or a string containing a package name

CLASS

is a package name

VAL

is any of the above or an unblessed reference

When used as an instance or class method ($obj->isa( TYPE )), isa returns true if $obj is blessed into package TYPE or inherits from package TYPE.

When used as a class method (CLASS->isa( TYPE ): sometimes referred to as a static method), isa returns true if CLASS inherits from (or is itself) the name of the package TYPE or inherits from package TYPE.

When used as a function, like

   use UNIVERSAL qw( isa ) ;
   $yes = isa $h, "HASH";
   $yes = isa "Foo", "Bar";

or

   require UNIVERSAL ;
   $yes = UNIVERSAL::isa $a, "ARRAY";

isa returns true in the same cases as above and also if VAL is an unblessed reference to a perl variable of type TYPE, such as "HASH", "ARRAY", or "Regexp".

$obj->can( METHOD )
CLASS->can( METHOD )
can( VAL, METHOD )

can checks if the object or class has a method called METHOD. If it does then a reference to the sub is returned. If it does not then undef is returned. This includes methods inherited or imported by $obj, CLASS, or VAL.

can cannot know whether an object will be able to provide a method through AUTOLOAD, so a return value of undef does not necessarily mean the object will not be able to handle the method call. To get around this some module authors use a forward declaration (see the perlsub manpage) for methods they will handle via AUTOLOAD. For such 'dummy' subs, can will still return a code reference, which, when called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef will cause an error.

can can be called as a class (static) method, an object method, or a function.

When used as a function, if VAL is a blessed reference or package name which has a method called METHOD, can returns a reference to the subroutine. If VAL is not a blessed reference, or if it does not have a method METHOD, undef is returned.

VERSION ( [ REQUIRE ] )

VERSION will return the value of the variable $VERSION in the package the object is blessed into. If REQUIRE is given then it will do a comparison and die if the package version is not greater than or equal to REQUIRE.

VERSION can be called as either a class (static) method, an object method or a function.

EXPORTS

None by default.

You may request the import of all three functions (isa, can, and VERSION), however it isn't usually necessary to do so. Perl magically makes these functions act as methods on all objects. The one exception is isa, which is useful as a function when operating on non-blessed references.


URI - Uniform Resource Identifiers

  • CONSTRUCTORS
  • COMMON METHODS
  • GENERIC METHODS
  • SERVER METHODS
  • SCHEME-SPECIFIC SUPPORT
  • CONFIGURATION VARIABLES
  • BUGS
  • PARSING URIs WITH REGEXP
  • SEE ALSO
  • COPYRIGHT
  • AUTHORS / ACKNOWLEDGMENTS

NAME

URI - Uniform Resource Identifiers (absolute and relative)

SYNOPSIS

 $u1 = URI->new("http://www.perl.com");
 $u2 = URI->new("foo", "http");
 $u3 = $u2->abs($u1);
 $u4 = $u3->clone;
 $u5 = URI->new("HTTP://WWW.perl.com:80")->canonical;

 $str = $u->as_string;
 $str = "$u";

 $scheme = $u->scheme;
 $opaque = $u->opaque;
 $path   = $u->path;
 $frag   = $u->fragment;

 $u->scheme("ftp");
 $u->host("ftp.perl.com");
 $u->path("cpan/");

DESCRIPTION

This module implements the URI class. Objects of this class represent "Uniform Resource Identifier references" as specified in RFC 2396 (and updated by RFC 2732).

A Uniform Resource Identifier is a compact string of characters that identifies an abstract or physical resource. A Uniform Resource Identifier can be further classified as either a Uniform Resource Locator (URL) or a Uniform Resource Name (URN). The distinction between URL and URN does not matter to the URI class interface. A "URI-reference" is a URI that may have additional information attached in the form of a fragment identifier.

An absolute URI reference consists of three parts: a scheme, a scheme-specific part and a fragment identifier. A subset of URI references share a common syntax for hierarchical namespaces. For these, the scheme-specific part is further broken down into authority, path and query components. These URIs can also take the form of relative URI references, where the scheme (and usually also the authority) component is missing, but implied by the context of the URI reference. The three forms of URI reference syntax are summarized as follows:

  <scheme>:<scheme-specific-part>#<fragment>
  <scheme>://<authority><path>?<query>#<fragment>
  <path>?<query>#<fragment>

The components into which a URI reference can be divided depend on the scheme. The URI class provides methods to get and set the individual components. The methods available for a specific URI object depend on the scheme.

CONSTRUCTORS

The following methods construct new URI objects:

$uri = URI->new( $str )
$uri = URI->new( $str, $scheme )

Constructs a new URI object. The string representation of a URI is given as argument, together with an optional scheme specification. Common URI wrappers like "" and <>, as well as leading and trailing white space, are automatically removed from the $str argument before it is processed further.

The constructor determines the scheme, maps this to an appropriate URI subclass, constructs a new object of that class and returns it.

The $scheme argument is only used when $str is a relative URI. It can be either a simple string that denotes the scheme, a string containing an absolute URI reference, or an absolute URI object. If no $scheme is specified for a relative URI $str, then $str is simply treated as a generic URI (no scheme-specific methods available).

The set of characters available for building URI references is restricted (see the URI::Escape manpage). Characters outside this set are automatically escaped by the URI constructor.

$uri = URI->new_abs( $str, $base_uri )

Constructs a new absolute URI object. The $str argument can denote a relative or absolute URI. If relative, then it is absolutized using $base_uri as base. The $base_uri must be an absolute URI.

$uri = URI::file->new( $filename )
$uri = URI::file->new( $filename, $os )

Constructs a new file URI from a file name. See the URI::file manpage.

$uri = URI::file->new_abs( $filename )
$uri = URI::file->new_abs( $filename, $os )

Constructs a new absolute file URI from a file name. See the URI::file manpage.

$uri = URI::file->cwd

Returns the current working directory as a file URI. See the URI::file manpage.

$uri->clone

Returns a copy of the $uri.

COMMON METHODS

The methods described in this section are available for all URI objects.

Methods that give access to components of a URI always return the old value of the component. The value returned is undef if the component was not present. There is generally a difference between a component that is empty (represented as "") and a component that is missing (represented as undef). If an accessor method is given an argument, it updates the corresponding component in addition to returning the old value of the component. Passing an undefined argument removes the component (if possible). The description of each accessor method indicates whether the component is passed as an escaped or an unescaped string. A component that can be further divided into sub-parts are usually passed escaped, as unescaping might change its semantics.

The common methods available for all URI are:

$uri->scheme
$uri->scheme( $new_scheme )

Sets and returns the scheme part of the $uri. If the $uri is relative, then $uri->scheme returns undef. If called with an argument, it updates the scheme of $uri, possibly changing the class of $uri, and returns the old scheme value. The method croaks if the new scheme name is illegal; a scheme name must begin with a letter and must consist of only US-ASCII letters, numbers, and a few special marks: ".", "+", "-". This restriction effectively means that the scheme must be passed unescaped. Passing an undefined argument to the scheme method makes the URI relative (if possible).

Letter case does not matter for scheme names. The string returned by $uri->scheme is always lowercase. If you want the scheme just as it was written in the URI in its original case, you can use the $uri->_scheme method instead.

$uri->opaque
$uri->opaque( $new_opaque )

Sets and returns the scheme-specific part of the $uri (everything between the scheme and the fragment) as an escaped string.

$uri->path
$uri->path( $new_path )

Sets and returns the same value as $uri->opaque unless the URI supports the generic syntax for hierarchical namespaces. In that case the generic method is overridden to set and return the part of the URI between the host name and the fragment.

$uri->fragment
$uri->fragment( $new_frag )

Returns the fragment identifier of a URI reference as an escaped string.

$uri->as_string

Returns a URI object to a plain string. URI objects are also converted to plain strings automatically by overloading. This means that $uri objects can be used as plain strings in most Perl constructs.

$uri->canonical

Returns a normalized version of the URI. The rules for normalization are scheme-dependent. They usually involve lowercasing the scheme and Internet host name components, removing the explicit port specification if it matches the default port, uppercasing all escape sequences, and unescaping octets that can be better represented as plain characters.

For efficiency reasons, if the $uri is already in normalized form, then a reference to it is returned instead of a copy.

$uri->eq( $other_uri )
URI::eq( $first_uri, $other_uri )

Tests whether two URI references are equal. URI references that normalize to the same string are considered equal. The method can also be used as a plain function which can also test two string arguments.

If you need to test whether two URI object references denote the same object, use the '==' operator.

$uri->abs( $base_uri )

Returns an absolute URI reference. If $uri is already absolute, then a reference to it is simply returned. If the $uri is relative, then a new absolute URI is constructed by combining the $uri and the $base_uri, and returned.

$uri->rel( $base_uri )

Returns a relative URI reference if it is possible to make one that denotes the same resource relative to $base_uri. If not, then $uri is simply returned.

GENERIC METHODS

The following methods are available to schemes that use the common/generic syntax for hierarchical namespaces. The descriptions of schemes below indicate which these are. Unknown schemes are assumed to support the generic syntax, and therefore the following methods:

$uri->authority
$uri->authority( $new_authority )

Sets and returns the escaped authority component of the $uri.

$uri->path
$uri->path( $new_path )

Sets and returns the escaped path component of the $uri (the part between the host name and the query or fragment). The path can never be undefined, but it can be the empty string.

$uri->path_query
$uri->path_query( $new_path_query )

Sets and returns the escaped path and query components as a single entity. The path and the query are separated by a "?" character, but the query can itself contain "?".

$uri->path_segments
$uri->path_segments( $segment, ... )

Sets and returns the path. In a scalar context, it returns the same value as $uri->path. In a list context, it returns the unescaped path segments that make up the path. Path segments that have parameters are returned as an anonymous array. The first element is the unescaped path segment proper; subsequent elements are escaped parameter strings. Such an anonymous array uses overloading so it can be treated as a string too, but this string does not include the parameters.

Note that absolute paths have the empty string as their first path_segment, i.e. the path /foo/bar have 3 path_segments; "", "foo" and "bar".

$uri->query
$uri->query( $new_query )

Sets and returns the escaped query component of the $uri.

$uri->query_form
$uri->query_form( $key1 => $val1, $key2 => $val2, ... )
$uri->query_form( \@key_value_pairs )
$uri->query_form( \%hash )

Sets and returns query components that use the application/x-www-form-urlencoded format. Key/value pairs are separated by "&", and the key is separated from the value by a "=" character.

The form can be set either by passing separate key/value pairs, or via an array or hash reference. Passing an empty array or an empty hash removes the query component, whereas passing no arguments at all leaves the component unchanged. The order of keys is undefined if a hash reference is passed. The old value is always returned as a list of separate key/value pairs. Assigning this list to a hash is unwise as the keys returned might repeat.

The values passed when setting the form can be plain strings or references to arrays of strings. Passing an array of values has the same effect as passing the key repeatedly with one value at a time. All the following statements have the same effect:

    $uri->query_form(foo => 1, foo => 2);
    $uri->query_form(foo => [1, 2]);
    $uri->query_form([ foo => 1, foo => 2 ]);
    $uri->query_form([ foo => [1, 2] ]);
    $uri->query_form({ foo => [1, 2] });

The URI::QueryParam module can be loaded to add further methods to manipulate the form of a URI. See the URI::QueryParam manpage for details.

$uri->query_keywords
$uri->query_keywords( $keywords, ... )
$uri->query_keywords( \@keywords )

Sets and returns query components that use the keywords separated by "+" format.

The keywords can be set either by passing separate keywords directly or by passing a reference to an array of keywords. Passing an empty array removes the query component, whereas passing no arguments at all leaves the component unchanged. The old value is always returned as a list of separate words.

SERVER METHODS

For schemes where the authority component denotes an Internet host, the following methods are available in addition to the generic methods.

$uri->userinfo
$uri->userinfo( $new_userinfo )

Sets and returns the escaped userinfo part of the authority component.

For some schemes this is a user name and a password separated by a colon. This practice is not recommended. Embedding passwords in clear text (such as URI) has proven to be a security risk in almost every case where it has been used.

$uri->host
$uri->host( $new_host )

Sets and returns the unescaped hostname.

If the $new_host string ends with a colon and a number, then this number also sets the port.

$uri->port
$uri->port( $new_port )

Sets and returns the port. The port is a simple integer that should be greater than 0.

If a port is not specified explicitly in the URI, then the URI scheme's default port is returned. If you don't want the default port substituted, then you can use the $uri->_port method instead.

$uri->host_port
$uri->host_port( $new_host_port )

Sets and returns the host and port as a single unit. The returned value includes a port, even if it matches the default port. The host part and the port part are separated by a colon: ":".

$uri->default_port

Returns the default port of the URI scheme to which $uri belongs. For http this is the number 80, for ftp this is the number 21, etc. The default port for a scheme can not be changed.

SCHEME-SPECIFIC SUPPORT

Scheme-specific support is provided for the following URI schemes. For URI objects that do not belong to one of these, you can only use the common and generic methods.

data:

The data URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally.

URI objects belonging to the data scheme support the common methods and two new methods to access their scheme-specific components: $uri->media_type and $uri->data. See the URI::data manpage for details.

file:

An old specification of the file URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but file URI references are in common use.

URI objects belonging to the file scheme support the common and generic methods. In addition, they provide two methods for mapping file URIs back to local file names; $uri->file and $uri->dir. See the URI::file manpage for details.

ftp:

An old specification of the ftp URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but ftp URI references are in common use.

URI objects belonging to the ftp scheme support the common, generic and server methods. In addition, they provide two methods for accessing the userinfo sub-components: $uri->user and $uri->password.

gopher:

The gopher URI scheme is specified in <draft-murali-url-gopher-1996-12-04> and will hopefully be available as a RFC 2396 based specification.

URI objects belonging to the gopher scheme support the common, generic and server methods. In addition, they support some methods for accessing gopher-specific path components: $uri->gopher_type, $uri->selector, $uri->search, $uri->string.

http:

The http URI scheme is specified in RFC 2616. The scheme is used to reference resources hosted by HTTP servers.

URI objects belonging to the http scheme support the common, generic and server methods.

https:

The https URI scheme is a Netscape invention which is commonly implemented. The scheme is used to reference HTTP servers through SSL connections. Its syntax is the same as http, but the default port is different.

ldap:

The ldap URI scheme is specified in RFC 2255. LDAP is the Lightweight Directory Access Protocol. An ldap URI describes an LDAP search operation to perform to retrieve information from an LDAP directory.

URI objects belonging to the ldap scheme support the common, generic and server methods as well as ldap-specific methods: $uri->dn, $uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See the URI::ldap manpage for details.

ldapi:

Like the ldap URI scheme, but uses a UNIX domain socket. The server methods are not supported, and the local socket path is available as $uri->un_path. The ldapi scheme is used by the OpenLDAP package. There is no real specification for it, but it is mentioned in various OpenLDAP manual pages.

ldaps:

Like the ldap URI scheme, but uses an SSL connection. This scheme is deprecated, as the preferred way is to use the start_tls mechanism.

mailto:

The mailto URI scheme is specified in RFC 2368. The scheme was originally used to designate the Internet mailing address of an individual or service. It has (in RFC 2368) been extended to allow setting of other mail header fields and the message body.

URI objects belonging to the mailto scheme support the common methods and the generic query methods. In addition, they support the following mailto-specific methods: $uri->to, $uri->headers.

mms:

The mms URL specification can be found at http://sdp.ppona.com/ URI objects belonging to the mms scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components.

news:

The news, nntp and snews URI schemes are specified in <draft-gilman-news-url-01> and will hopefully be available as an RFC 2396 based specification soon.

URI objects belonging to the news scheme support the common, generic and server methods. In addition, they provide some methods to access the path: $uri->group and $uri->message.

nntp:

See news scheme.

pop:

The pop URI scheme is specified in RFC 2384. The scheme is used to reference a POP3 mailbox.

URI objects belonging to the pop scheme support the common, generic and server methods. In addition, they provide two methods to access the userinfo components: $uri->user and $uri->auth

rlogin:

An old specification of the rlogin URI scheme is found in RFC 1738. URI objects belonging to the rlogin scheme support the common, generic and server methods.

rtsp:

The rtsp URL specification can be found in section 3.2 of RFC 2326. URI objects belonging to the rtsp scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components.

rtspu:

The rtspu URI scheme is used to talk to RTSP servers over UDP instead of TCP. The syntax is the same as rtsp.

rsync:

Information about rsync is available from http://rsync.samba.org. URI objects belonging to the rsync scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password.

sip:

The sip URI specification is described in sections 19.1 and 25 of RFC 3261. URI objects belonging to the sip scheme support the common, generic, and server methods with the exception of path related sub-components. In addition, they provide two methods to get and set sip parameters: $uri->params_form and $uri->params.

sips:

See sip scheme. Its syntax is the same as sip, but the default port is different.

snews:

See news scheme. Its syntax is the same as news, but the default port is different.

telnet:

An old specification of the telnet URI scheme is found in RFC 1738. URI objects belonging to the telnet scheme support the common, generic and server methods.

tn3270:

These URIs are used like telnet URIs but for connections to IBM mainframes. URI objects belonging to the tn3270 scheme support the common, generic and server methods.

ssh:

Information about ssh is available at http://www.openssh.com/. URI objects belonging to the ssh scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password.

urn:

The syntax of Uniform Resource Names is specified in RFC 2141. URI objects belonging to the urn scheme provide the common methods, and also the methods $uri->nid and $uri->nss, which return the Namespace Identifier and the Namespace-Specific String respectively.

The Namespace Identifier basically works like the Scheme identifier of URIs, and further divides the URN namespace. Namespace Identifier assignments are maintained at <http://www.iana.org/assignments/urn-namespaces>.

Letter case is not significant for the Namespace Identifier. It is always returned in lower case by the $uri->nid method. The $uri->_nid method can be used if you want it in its original case.

urn:isbn:

The urn:isbn: namespace contains International Standard Book Numbers (ISBNs) and is described in RFC 3187. A URI object belonging to this namespace has the following extra methods (if the Business::ISBN module is available): $uri->isbn, $uri->isbn_publisher_code, $uri->isbn_country_code, $uri->isbn_as_ean.

urn:oid:

The urn:oid: namespace contains Object Identifiers (OIDs) and is described in RFC 3061. An object identifier consists of sequences of digits separated by dots. A URI object belonging to this namespace has an additional method called $uri->oid that can be used to get/set the oid value. In a list context, oid numbers are returned as separate elements.

CONFIGURATION VARIABLES

The following configuration variables influence how the class and its methods behave:

$URI::ABS_ALLOW_RELATIVE_SCHEME

Some older parsers used to allow the scheme name to be present in the relative URL if it was the same as the base URL scheme. RFC 2396 says that this should be avoided, but you can enable this old behaviour by setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value. The difference is demonstrated by the following examples:

  URI->new("http:foo";)->abs("http://host/a/b";)
      ==>  "http:foo";
  local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1;
  URI->new("http:foo")->abs("http://host/a/b")
      ==>  "http:/host/a/foo"
$URI::ABS_REMOTE_LEADING_DOTS

You can also have the abs() method ignore excess ".." segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS to a TRUE value. The difference is demonstrated by the following examples:

  URI->new("../../../foo")->abs("http://host/a/b";)
      ==> "http://host/../../foo";
  local $URI::ABS_REMOTE_LEADING_DOTS = 1;
  URI->new("../../../foo")->abs("http://host/a/b")
      ==> "http://host/foo"

BUGS

Using regexp variables like $1 directly as arguments to the URI methods does not work too well with current perl implementations. I would argue that this is actually a bug in perl. The workaround is to quote them. Example:

   /(...)/ || die;
   $u->query("$1");

PARSING URIs WITH REGEXP

As an alternative to this module, the following (official) regular expression can be used to decode a URI:

  my($scheme, $authority, $path, $query, $fragment) =
  $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?|;

The URI::Split module provides the function uri_split() as a readable alternative.

SEE ALSO

the URI::file manpage, the URI::WithBase manpage, the URI::QueryParam manpage, the URI::Escape manpage, the URI::Split manpage, the URI::Heuristic manpage

RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax", Berners-Lee, Fielding, Masinter, August 1998.

http://www.iana.org/assignments/uri-schemes

http://www.iana.org/assignments/urn-namespaces

http://www.w3.org/Addressing/

COPYRIGHT

Copyright 1995-2003 Gisle Aas.

Copyright 1995 Martijn Koster.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS / ACKNOWLEDGMENTS

This module is based on the URI::URL module, which in turn was (distantly) based on the wwwurl.pl code in the libwww-perl for perl4 developed by Roy Fielding, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter.

URI::URL was developed by Gisle Aas, Tim Bunce, Roy Fielding and Martijn Koster with input from other people on the libwww-perl mailing list.

URI and related subclasses was developed by Gisle Aas.


URI::Escape - Escape and unescape unsafe characters

  • SEE ALSO
  • COPYRIGHT

NAME

URI::Escape - Escape and unescape unsafe characters

SYNOPSIS

 use URI::Escape;
 $safe = uri_escape("10% is enough\n");
 $verysafe = uri_escape("foo", "\0-\377");
 $str  = uri_unescape($safe);

DESCRIPTION

This module provides functions to escape and unescape URI strings as defined by RFC 2396 (and updated by RFC 2732). A URI consists of a restricted set of characters, denoted as uric in RFC 2396. The restricted set of characters consists of digits, letters, and a few graphic symbols chosen from those common to most of the character encodings and input facilities available to Internet users:

  "A" .. "Z", "a" .. "z", "0" .. "9",
  ";", "/", "?", ":", "@", "&", "=", "+", "$", ",", "[", "]",   # reserved
  "-", "_", ".", "!", "~", "*", "'", "(", ")"

In addition, any byte (octet) can be represented in a URI by an escape sequence: a triplet consisting of the character "%" followed by two hexadecimal digits. A byte can also be represented directly by a character, using the US-ASCII character for that octet (iff the character is part of uric).

Some of the uric characters are reserved for use as delimiters or as part of certain URI components. These must be escaped if they are to be treated as ordinary data. Read RFC 2396 for further details.

The functions provided (and exported by default) from this module are:

uri_escape( $string )
uri_escape( $string, $unsafe )

Replaces each unsafe character in the $string with the corresponding escape sequence and returns the result. The $string argument should be a string of bytes. The uri_escape() function will croak if given a characters with code above 255. Use uri_escape_utf8() if you know you have such chars or/and want chars in the 128 .. 255 range treated as UTF-8.

The uri_escape() function takes an optional second argument that overrides the set of characters that are to be escaped. The set is specified as a string that can be used in a regular expression character class (between [ ]). E.g.:

  "\x00-\x1f\x7f-\xff"          # all control and hi-bit characters
  "a-z"                         # all lower case characters
  "^A-Za-z"                     # everything not a letter

The default set of characters to be escaped is all those which are not part of the uric character class shown above as well as the reserved characters. I.e. the default is:

  "^A-Za-z0-9\-_.!~*'()"
uri_escape_utf8( $string )
uri_escape_utf8( $string, $unsafe )

Works like uri_escape(), but will encode chars as UTF-8 before escaping them. This makes this function able do deal with characters with code above 255 in $string. Note that chars in the 128 .. 255 range will be escaped differently by this function compared to what uri_escape() would. For chars in the 0 .. 127 range there is no difference.

The call:

    $uri = uri_escape_utf8($string);

will be the same as:

    use Encode qw(encode);
    $uri = uri_escape(encode("UTF-8", $string));

but will even work for perl-5.6 for chars in the 128 .. 255 range.

Note: Javascript has a function called escape() that produce the sequence "%uXXXX" for chars in the 256 .. 65535 range. This function has really nothing to do with URI escaping but some folks got confused since it "does the right thing" in the 0 .. 255 range. Because of this you sometimes see "URIs" with these kind of escapes. The JavaScript encodeURI() function is similar to uri_escape_utf8().

uri_unescape($string,...)

Returns a string with each %XX sequence replaced with the actual byte (octet).

This does the same as:

   $string =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;

but does not modify the string in-place as this RE would. Using the uri_unescape() function instead of the RE might make the code look cleaner and is a few characters less to type.

In a simple benchmark test I did, calling the function (instead of the inline RE above) if a few chars were unescaped was something like 40% slower, and something like 700% slower if none were. If you are going to unescape a lot of times it might be a good idea to inline the RE.

If the uri_unescape() function is passed multiple strings, then each one is returned unescaped.

The module can also export the %escapes hash, which contains the mapping from all 256 bytes to the corresponding escape codes. Lookup in this hash is faster than evaluating sprintf("%%%02X", ord($byte)) each time.

SEE ALSO

the URI manpage

COPYRIGHT

Copyright 1995-2004 Gisle Aas.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


URI::Heuristic - Expand URI using heuristics

  • ENVIRONMENT
  • COPYRIGHT

NAME

URI::Heuristic - Expand URI using heuristics

SYNOPSIS

 use URI::Heuristic qw(uf_uristr);
 $u = uf_uristr("perl");             # http://www.perl.com
 $u = uf_uristr("www.sol.no/sol");   # http://www.sol.no/sol
 $u = uf_uristr("aas");              # http://www.aas.no
 $u = uf_uristr("ftp.funet.fi");     # ftp://ftp.funet.fi
 $u = uf_uristr("/etc/passwd");      # file:/etc/passwd

DESCRIPTION

This module provides functions that expand strings into real absolute URIs using some built-in heuristics. Strings that already represent absolute URIs (i.e. that start with a scheme: part) are never modified and are returned unchanged. The main use of these functions is to allow abbreviated URIs similar to what many web browsers allow for URIs typed in by the user.

The following functions are provided:

uf_uristr($str)

Tries to make the argument string into a proper absolute URI string. The "uf_" prefix stands for "User Friendly". Under MacOS, it assumes that any string with a common URL scheme (http, ftp, etc.) is a URL rather than a local path. So don't name your volumes after common URL schemes and expect uf_uristr() to construct valid file: URL's on those volumes for you, because it won't.

uf_uri($str)

Works the same way as uf_uristr() but returns a URI object.

ENVIRONMENT

If the hostname portion of a URI does not contain any dots, then certain qualified guesses are made. These guesses are governed by the following two environment variables:

COUNTRY

The two-letter country code (ISO 3166) for your location. If the domain name of your host ends with two letters, then it is taken to be the default country. See also the Locale::Country manpage.

URL_GUESS_PATTERN

Contains a space-separated list of URL patterns to try. The string "ACME" is for some reason used as a placeholder for the host name in the URL provided. Example:

 URL_GUESS_PATTERN="www.ACME.no www.ACME.se www.ACME.com"
 export URL_GUESS_PATTERN

Specifying URL_GUESS_PATTERN disables any guessing rules based on country. An empty URL_GUESS_PATTERN disables any guessing that involves host name lookups.

COPYRIGHT

Copyright 1997-1998, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


URI::QueryParam - Additional query methods for URIs

  • SEE ALSO
  • COPYRIGHT

NAME

URI::QueryParam - Additional query methods for URIs

SYNOPSIS

  use URI;
  use URI::QueryParam;

  $u = URI->new("", "http");
  $u->query_param(foo => 1, 2, 3);
  print $u->query;    # prints foo=1&foo=2&foo=3

  for my $key ($u->query_param) {
      print "$key: ", join(", ", $u->query_param($key)), "\n";
  }

DESCRIPTION

Loading the URI::QueryParam module adds some extra methods to URIs that support query methods. These methods provide an alternative interface to the $u->query_form data.

The query_param_* methods have deliberately been made identical to the interface of the corresponding CGI.pm methods.

The following additional methods are made available:

@keys = $u->query_param
@values = $u->query_param( $key )
$first_value = $u->query_param( $key )
$u->query_param( $key, $value,... )

If $u->query_param is called with no arguments, it returns all the distinct parameter keys of the URI. In a scalar context it returns the number of distinct keys.

When a $key argument is given, the method returns the parameter values with the given key. In a scalar context, only the first parameter value is returned.

If additional arguments are given, they are used to update successive parameters with the given key. If any of the values provided are array references, then the array is dereferenced to get the actual values.

$u->query_param_append($key, $value,...)

Adds new parameters with the given key without touching any old parameters with the same key. It can be explained as a more efficient version of:

   $u->query_param($key,
                   $u->query_param($key),
                   $value,...);

One difference is that this expression would return the old values of $key, whereas the query_param_append() method does not.

@values = $u->query_param_delete($key)
$first_value = $u->query_param_delete($key)

Deletes all key/value pairs with the given key. The old values are returned. In a scalar context, only the first value is returned.

Using the query_param_delete() method is slightly more efficient than the equivalent:

   $u->query_param($key, []);
$hashref = $u->query_form_hash
$u->query_form_hash( \%new_form )

Returns a reference to a hash that represents the query form's key/value pairs. If a key occurs multiple times, then the hash value becomes an array reference.

Note that sequence information is lost. This means that:

   $u->query_form_hash($u->query_form_hash);

is not necessarily a no-op, as it may reorder the key/value pairs. The values returned by the query_param() method should stay the same though.

SEE ALSO

the URI manpage, the CGI manpage

COPYRIGHT

Copyright 2002 Gisle Aas.


URI::Split - Parse and compose URI strings

  • SEE ALSO
  • COPYRIGHT

NAME

URI::Split - Parse and compose URI strings

SYNOPSIS

 use URI::Split qw(uri_split uri_join);
 ($scheme, $auth, $path, $query, $frag) = uri_split($uri);
 $uri = uri_join($scheme, $auth, $path, $query, $frag);

DESCRIPTION

Provides functions to parse and compose URI strings. The following functions are provided:

($scheme, $auth, $path, $query, $frag) = uri_split($uri)

Breaks up a URI string into its component parts. An undef value is returned for those parts that are not present. The $path part is always present (but can be the empty string) and is thus never returned as undef.

No sensible value is returned if this function is called in a scalar context.

$uri = uri_join($scheme, $auth, $path, $query, $frag)

Puts together a URI string from its parts. Missing parts are signaled by passing undef for the corresponding argument.

Minimal escaping is applied to parts that contain reserved chars that would confuse a parser. For instance, any occurrence of '?' or '#' in $path is always escaped, as it would otherwise be parsed back as a query or fragment.

SEE ALSO

the URI manpage, the URI::Escape manpage

COPYRIGHT

Copyright 2003, Gisle Aas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


URI::URL - Uniform Resource Locators

  • SEE ALSO
  • COPYRIGHT

NAME

URI::URL - Uniform Resource Locators

SYNOPSIS

 $u1 = URI::URL->new($str, $base);
 $u2 = $u1->abs;

DESCRIPTION

This module is provided for backwards compatibility with modules that depend on the interface provided by the URI::URL class that used to be distributed with the libwww-perl library.

The following differences exist compared to the URI class interface:

  • The URI::URL module exports the url() function as an alternate constructor interface.

  • The constructor takes an optional $base argument. The URI::URL class is a subclass of URI::WithBase.

  • The URI::URL->newlocal class method is the same as URI::file->new_abs.

  • URI::URL::strict(1)

  • $url->print_on method

  • $url->crack method

  • $url->full_path: same as ($uri->abs_path || "/")

  • $url->netloc: same as $uri->authority

  • $url->epath, $url->equery: same as $uri->path, $uri->query

  • $url->path and $url->query pass unescaped strings.

  • $url->path_components: same as $uri->path_segments (if you don't consider path segment parameters)

  • $url->params and $url->eparams methods

  • $url->base method. See the URI::WithBase manpage.

  • $url->abs and $url->rel have an optional $base argument. See the URI::WithBase manpage.

  • $url->frag: same as $uri->fragment

  • $url->keywords: same as $uri->query_keywords

  • $url->localpath and friends map to $uri->file.

  • $url->address and $url->encoded822addr: same as $uri->to for mailto URI

  • $url->groupart method for news URI

  • $url->article: same as $uri->message

SEE ALSO

the URI manpage, the URI::WithBase manpage

COPYRIGHT

Copyright 1998-2000 Gisle Aas.


URI::WithBase - URIs which remember their base

  • SEE ALSO
  • COPYRIGHT

NAME

URI::WithBase - URIs which remember their base

SYNOPSIS

 $u1 = URI::WithBase->new($str, $base);
 $u2 = $u1->abs;

 $base = $u1->base;
 $u1->base( $new_base )

DESCRIPTION

This module provides the URI::WithBase class. Objects of this class are like URI objects, but can keep their base too. The base represents the context where this URI was found and can be used to absolutize or relativize the URI. All the methods described in the URI manpage are supported for URI::WithBase objects.

The methods provided in addition to or modified from those of URI are:

$uri = URI::WithBase->new($str, [$base])

The constructor takes an optional base URI as the second argument. If provided, this argument initializes the base attribute.

$uri->base( [$new_base] )

Can be used to get or set the value of the base attribute. The return value, which is the old value, is a URI object or undef.

$uri->abs( [$base_uri] )

The $base_uri argument is now made optional as the object carries its base with it. A new object is returned even if $uri is already absolute (while plain URI objects simply return themselves in that case).

$uri->rel( [$base_uri] )

The $base_uri argument is now made optional as the object carries its base with it. A new object is always returned.

SEE ALSO

the URI manpage

COPYRIGHT

Copyright 1998-2002 Gisle Aas.


URI::data - URI that contains immediate data

  • SEE ALSO
  • COPYRIGHT

NAME

URI::data - URI that contains immediate data

SYNOPSIS

 use URI;

 $u = URI->new("data:");
 $u->media_type("image/gif");
 $u->data(scalar(`cat camel.gif`));
 print "$u\n";
 open(XV, "|xv -") and print XV $u->data;

DESCRIPTION

The URI::data class supports URI objects belonging to the data URI scheme. The data URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally. Examples:

  data:,Perl%20is%20good
  data:image/gif;base64,R0lGODdhIAAgAIAAAAAAAPj8+CwAAAAAI
    AAgAAAClYyPqcu9AJyCjtIKc5w5xP14xgeO2tlY3nWcajmZZdeJcG
    Kxrmimms1KMTa1Wg8UROx4MNUq1HrycMjHT9b6xKxaFLM6VRKzI+p
    KS9XtXpcbdun6uWVxJXA8pNPkdkkxhxc21LZHFOgD2KMoQXa2KMWI
    JtnE2KizVUkYJVZZ1nczBxXlFopZBtoJ2diXGdNUymmJdFMAADs=

URI objects belonging to the data scheme support the common methods (described in the URI manpage) and the following two scheme-specific methods:

$uri->media_type( [$new_media_type] )

Can be used to get or set the media type specified in the URI. If no media type is specified, then the default "text/plain;charset=US-ASCII" is returned.

$uri->data( [$new_data] )

Can be used to get or set the data contained in the URI. The data is passed unescaped (in binary form). The decision about whether to base64 encode the data in the URI is taken automatically, based on the encoding that produces the shorter URI string.

SEE ALSO

the URI manpage

COPYRIGHT

Copyright 1995-1998 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


URI::file - URI that maps to local file names

  • MAPPING NOTES
  • CONFIGURATION VARIABLES
  • SEE ALSO
  • COPYRIGHT

NAME

URI::file - URI that maps to local file names

SYNOPSIS

 use URI::file;

 $u1 = URI->new("file:/foo/bar");
 $u2 = URI->new("foo/bar", "file");

 $u3 = URI::file->new($path);
 $u4 = URI::file->new("c:\\windows\\", "win32");

 $u1->file;
 $u1->file("mac");

DESCRIPTION

The URI::file class supports URI objects belonging to the file URI scheme. This scheme allows us to map the conventional file names found on various computer systems to the URI name space. An old specification of the file URI scheme is found in RFC 1738. Some older background information is also in RFC 1630. There are no newer specifications as far as I know.

If you simply want to construct file URI objects from URI strings, use the normal URI constructor. If you want to construct file URI objects from the actual file names used by various systems, then use one of the following URI::file constructors:

$u = URI::file->new( $filename, [$os] )

Maps a file name to the file: URI name space, creates a URI object and returns it. The $filename is interpreted as belonging to the indicated operating system ($os), which defaults to the value of the $^O variable. The $filename can be either absolute or relative, and the corresponding type of URI object for $os is returned.

$u = URI::file->new_abs( $filename, [$os] )

Same as URI::file->new, but makes sure that the URI returned represents an absolute file name. If the $filename argument is relative, then the name is resolved relative to the current directory, i.e. this constructor is really the same as:

  URI::file->new($filename)->abs(URI::file->cwd);
$u = URI::file->cwd

Returns a file URI that represents the current working directory. See the Cwd manpage.

The following methods are supported for file URI (in addition to the common and generic methods described in the URI manpage):

$u->file( [$os] )

Returns a file name. It maps from the URI name space to the file name space of the indicated operating system.

It might return undef if the name can not be represented in the indicated file system.

$u->dir( [$os] )

Some systems use a different form for names of directories than for plain files. Use this method if you know you want to use the name for a directory.

The URI::file module can be used to map generic file names to names suitable for the current system. As such, it can work as a nice replacement for the File::Spec module. For instance, the following code translates the UNIX-style file name Foo/Bar.pm to a name suitable for the local system:

  $file = URI::file->new("Foo/Bar.pm", "unix")->file;
  die "Can't map filename Foo/Bar.pm for $^O" unless defined $file;
  open(FILE, $file) || die "Can't open '$file': $!";
  # do something with FILE

MAPPING NOTES

Most computer systems today have hierarchically organized file systems. Mapping the names used in these systems to the generic URI syntax allows us to work with relative file URIs that behave as they should when resolved using the generic algorithm for URIs (specified in RFC 2396). Mapping a file name to the generic URI syntax involves mapping the path separator character to "/" and encoding any reserved characters that appear in the path segments of the file name. If path segments consisting of the strings "." or ".." have a different meaning than what is specified for generic URIs, then these must be encoded as well.

If the file system has device, volume or drive specifications as the root of the name space, then it makes sense to map them to the authority field of the generic URI syntax. This makes sure that relative URIs can not be resolved "above" them, i.e. generally how relative file names work in those systems.

Another common use of the authority field is to encode the host on which this file name is valid. The host name "localhost" is special and generally has the same meaning as a missing or empty authority field. This use is in conflict with using it as a device specification, but can often be resolved for device specifications having characters not legal in plain host names.

File name to URI mapping in normally not one-to-one. There are usually many URIs that map to any given file name. For instance, an authority of "localhost" maps the same as a URI with a missing or empty authority.

Example 1: The Mac uses ":" as path separator, but not in the same way as a generic URI. ":foo" is a relative name. "foo:bar" is an absolute name. Also, path segments can contain the "/" character as well as the literal "." or "..". So the mapping looks like this:

  Mac                   URI
  ----------            -------------------
  :foo:bar     <==>     foo/bar
  :            <==>     ./
  ::foo:bar    <==>     ../foo/bar
  :::          <==>     ../../
  foo:bar      <==>     file:/foo/bar
  foo:bar:     <==>     file:/foo/bar/
  ..           <==>     %2E%2E
  <undef>      <==      /
  foo/         <==      file:/foo%2F
  ./foo.txt    <==      file:/.%2Ffoo.txt

Note that if you want a relative URL, you *must* begin the path with a :. Any path that begins with [^:] is treated as absolute.

Example 2: The UNIX file system is easy to map, as it uses the same path separator as URIs, has a single root, and segments of "." and ".." have the same meaning. URIs that have the character "\0" or "/" as part of any path segment can not be turned into valid UNIX file names.

  UNIX                  URI
  ----------            ------------------
  foo/bar      <==>     foo/bar
  /foo/bar     <==>     file:/foo/bar
  /foo/bar     <==      file://localhost/foo/bar
  file:         ==>     ./file:
  <undef>      <==      file:/fo%00/bar
  /            <==>     file:/

CONFIGURATION VARIABLES

The following configuration variables influence how the class and its methods behave:

%URI::file::OS_CLASS

This hash maps OS identifiers to implementation classes. You might want to add or modify this if you want to plug in your own file handler class. Normally the keys should match the $^O values in use.

If there is no mapping then the "Unix" implementation is used.

$URI::file::DEFAULT_AUTHORITY

This determine what "authority" string to include in absolute file URIs. It defaults to "". If you prefer verbose URIs you might set it to be "localhost".

Setting this value to undef force behaviour compatible to URI v1.31 and earlier. In this mode host names in UNC paths and drive letters are mapped to the authority component on Windows, while we produce authority-less URIs on Unix.

SEE ALSO

the URI manpage, the File::Spec manpage, the perlport manpage

COPYRIGHT

Copyright 1995-1998,2004 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


URI::ldap - LDAP Uniform Resource Locators

  • METHODS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

URI::ldap - LDAP Uniform Resource Locators

SYNOPSIS

  use URI;

  $uri = URI->new("ldap:$uri_string");
  $dn     = $uri->dn;
  $filter = $uri->filter;
  @attr   = $uri->attributes;
  $scope  = $uri->scope;
  %extn   = $uri->extensions;

  $uri = URI->new("ldap:");  # start empty
  $uri->host("ldap.itd.umich.edu");
  $uri->dn("o=University of Michigan,c=US");
  $uri->attributes(qw(postalAddress));
  $uri->scope('sub');
  $uri->filter('(cn=Babs Jensen)');
  print $uri->as_string,"\n";

DESCRIPTION

URI::ldap provides an interface to parse an LDAP URI into its constituent parts and also to build a URI as described in RFC 2255.

METHODS

URI::ldap supports all the generic and server methods defined by the URI manpage, plus the following.

Each of the following methods can be used to set or get the value in the URI. The values are passed in unescaped form. None of these return undefined values, but elements without a default can be empty. If arguments are given, then a new value is set for the given part of the URI.

$uri->dn( [$new_dn] )

Sets or gets the Distinguished Name part of the URI. The DN identifies the base object of the LDAP search.

$uri->attributes( [@new_attrs] )

Sets or gets the list of attribute names which are returned by the search.

$uri->scope( [$new_scope] )

Sets or gets the scope to be used by the search. The value can be one of "base", "one" or "sub". If none is given in the URI then the return value defaults to "base".

$uri->_scope( [$new_scope] )

Same as scope(), but does not default to anything.

$uri->filter( [$new_filter] )

Sets or gets the filter to be used by the search. If none is given in the URI then the return value defaults to "(objectClass=*)".

$uri->_filter( [$new_filter] )

Same as filter(), but does not default to anything.

$uri->extensions( [$etype => $evalue,...] )

Sets or gets the extensions used for the search. The list passed should be in the form etype1 => evalue1, etype2 => evalue2,... This is also the form of list that is returned.

SEE ALSO

RFC-2255

AUTHOR

Graham Barr <gbarr@pobox.com>

Slightly modified by Gisle Aas to fit into the URI distribution.

COPYRIGHT

Copyright (c) 1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Unicode::CharName - Look up Unicode character names

  • SEE ALSO
  • COPYRIGHT

NAME

Unicode::CharName - Look up Unicode character names

SYNOPSIS

 use Unicode::CharName qw(uname ublock);
 print uname(ord('%')), "\n";
 print ublock(0x0300), "\n";

DESCRIPTION

This module provide a two functions named uname() and ublock(). The uname() function will return the Unicode character name for the given code (a number between 0 and 0x10FFFF). Unicode character names are written in upper-case ASCII letters, and are strings like:

  LATIN CAPITAL LETTER A
  LATIN SMALL LETTER A WITH RING ABOVE
  CJK UNIFIED IDEOGRAPH 7C80
  HANGUL SYLLABLE PWILH

The ublock() will return the name of the Unicode character block that the given character belongs to.

SEE ALSO

the Unicode::String manpage

COPYRIGHT

Copyright 1997,2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Name table extracted from the Unicode 4.1 Character Database. Copyright (c) 1991-2005 Unicode, Inc. All Rights reserved.


Unicode::Collate - Unicode Collation Algorithm

    • Constructor and Tailoring
    • Methods for Collation
    • Methods for Searching
    • Other Methods
  • EXPORT
  • INSTALL
  • CAVEATS
  • AUTHOR, COPYRIGHT AND LICENSE
  • SEE ALSO

NAME

Unicode::Collate - Unicode Collation Algorithm

SYNOPSIS

  use Unicode::Collate;

  #construct
  $Collator = Unicode::Collate->new(%tailoring);

  #sort
  @sorted = $Collator->sort(@not_sorted);

  #compare
  $result = $Collator->cmp($a, $b); # returns 1, 0, or -1.

  # If %tailoring is false (i.e. empty),
  # $Collator should do the default collation.

DESCRIPTION

This module is an implementation of Unicode Technical Standard #10 (a.k.a. UTS #10) - Unicode Collation Algorithm (a.k.a. UCA).

Constructor and Tailoring

The new method returns a collator object.

   $Collator = Unicode::Collate->new(
      UCA_Version => $UCA_Version,
      alternate => $alternate, # deprecated: use of 'variable' is recommended.
      backwards => $levelNumber, # or \@levelNumbers
      entry => $element,
      hangul_terminator => $term_primary_weight,
      ignoreName => qr/$ignoreName/,
      ignoreChar => qr/$ignoreChar/,
      katakana_before_hiragana => $bool,
      level => $collationLevel,
      normalization  => $normalization_form,
      overrideCJK => \&overrideCJK,
      overrideHangul => \&overrideHangul,
      preprocess => \&preprocess,
      rearrange => \@charList,
      table => $filename,
      undefName => qr/$undefName/,
      undefChar => qr/$undefChar/,
      upper_before_lower => $bool,
      variable => $variable,
   );
UCA_Version

If the tracking version number of UCA is given, behavior of that tracking version is emulated on collating. If omitted, the return value of UCA_Version() is used. UCA_Version() should return the latest tracking version supported.

The supported tracking version: 8, 9, 11, or 14.

     UCA       Unicode Standard         DUCET (@version)
     ---------------------------------------------------
      8              3.1                3.0.1 (3.0.1d9)
      9     3.1 with Corrigendum 3      3.1.1 (3.1.1)
     11              4.0                4.0.0 (4.0.0)
     14             4.1.0               4.1.0 (4.1.0)

Note: Recent UTS #10 renames "Tracking Version" to "Revision."

alternate

-- see 3.2.2 Alternate Weighting, version 8 of UTS #10

For backward compatibility, alternate (old name) can be used as an alias for variable.

backwards

-- see 3.1.2 French Accents, UTS #10.

     backwards => $levelNumber or \@levelNumbers

Weights in reverse order; ex. level 2 (diacritic ordering) in French. If omitted, forwards at all the levels.

entry

-- see 3.1 Linguistic Features; 3.2.1 File Format, UTS #10.

If the same character (or a sequence of characters) exists in the collation element table through table, mapping to collation elements is overrided. If it does not exist, the mapping is defined additionally.

    entry => <<'ENTRY', # for DUCET v4.0.0 (allkeys-4.0.0.txt)
    0063 0068 ; [.0E6A.0020.0002.0063] # ch
    0043 0068 ; [.0E6A.0020.0007.0043] # Ch
    0043 0048 ; [.0E6A.0020.0008.0043] # CH
    006C 006C ; [.0F4C.0020.0002.006C] # ll
    004C 006C ; [.0F4C.0020.0007.004C] # Ll
    004C 004C ; [.0F4C.0020.0008.004C] # LL
    00F1      ; [.0F7B.0020.0002.00F1] # n-tilde
    006E 0303 ; [.0F7B.0020.0002.00F1] # n-tilde
    00D1      ; [.0F7B.0020.0008.00D1] # N-tilde
    004E 0303 ; [.0F7B.0020.0008.00D1] # N-tilde
    ENTRY

    entry => <<'ENTRY', # for DUCET v4.0.0 (allkeys-4.0.0.txt)
    00E6 ; [.0E33.0020.0002.00E6][.0E8B.0020.0002.00E6] # ae ligature as <a><e>
    00C6 ; [.0E33.0020.0008.00C6][.0E8B.0020.0008.00C6] # AE ligature as <A><E>
    ENTRY

NOTE: The code point in the UCA file format (before ';') must be a Unicode code point (defined as hexadecimal), but not a native code point. So 0063 must always denote U+0063, but not a character of "\x63".

Weighting may vary depending on collation element table. So ensure the weights defined in entry will be consistent with those in the collation element table loaded via table.

In DUCET v4.0.0, primary weight of C is 0E60 and that of D is 0E6D. So setting primary weight of CH to 0E6A (as a value between 0E60 and 0E6D) makes ordering as C < CH < D. Exactly speaking DUCET already has some characters between C and D: small capital C (U+1D04) with primary weight 0E64, c-hook/C-hook (U+0188/U+0187) with 0E65, and c-curl (U+0255) with 0E69. Then primary weight 0E6A for CH makes CH ordered between c-curl and D.

hangul_terminator

-- see 7.1.4 Trailing Weights, UTS #10.

If a true value is given (non-zero but should be positive), it will be added as a terminator primary weight to the end of every standard Hangul syllable. Secondary and any higher weights for terminator are set to zero. If the value is false or hangul_terminator key does not exist, insertion of terminator weights will not be performed.

Boundaries of Hangul syllables are determined according to conjoining Jamo behavior in the Unicode Standard and HangulSyllableType.txt.

Implementation Note: (1) For expansion mapping (Unicode character mapped to a sequence of collation elements), a terminator will not be added between collation elements, even if Hangul syllable boundary exists there. Addition of terminator is restricted to the next position to the last collation element.

(2) Non-conjoining Hangul letters (Compatibility Jamo, halfwidth Jamo, and enclosed letters) are not automatically terminated with a terminator primary weight. These characters may need terminator included in a collation element table beforehand.

ignoreChar
ignoreName

-- see 3.2.2 Variable Weighting, UTS #10.

Makes the entry in the table completely ignorable; i.e. as if the weights were zero at all level.

Through ignoreChar, any character matching qr/$ignoreChar/ will be ignored. Through ignoreName, any character whose name (given in the table file as a comment) matches qr/$ignoreName/ will be ignored.

E.g. when 'a' and 'e' are ignorable, 'element' is equal to 'lament' (or 'lmnt').

katakana_before_hiragana

-- see 7.3.1 Tertiary Weight Table, UTS #10.

By default, hiragana is before katakana. If the parameter is made true, this is reversed.

NOTE: This parameter simplemindedly assumes that any hiragana/katakana distinctions must occur in level 3, and their weights at level 3 must be same as those mentioned in 7.3.1, UTS #10. If you define your collation elements which violate this requirement, this parameter does not work validly.

level

-- see 4.3 Form Sort Key, UTS #10.

Set the maximum level. Any higher levels than the specified one are ignored.

  Level 1: alphabetic ordering
  Level 2: diacritic ordering
  Level 3: case ordering
  Level 4: tie-breaking (e.g. in the case when variable is 'shifted')
  ex.level => 2,

If omitted, the maximum is the 4th.

normalization

-- see 4.1 Normalize, UTS #10.

If specified, strings are normalized before preparation of sort keys (the normalization is executed after preprocess).

A form name Unicode::Normalize::normalize() accepts will be applied as $normalization_form. Acceptable names include 'NFD', 'NFC', 'NFKD', and 'NFKC'. See Unicode::Normalize::normalize() for detail. If omitted, 'NFD' is used.

normalization is performed after preprocess (if defined).

Furthermore, special values, undef and "prenormalized", can be used, though they are not concerned with Unicode::Normalize::normalize().

If undef (not a string "undef") is passed explicitly as the value for this key, any normalization is not carried out (this may make tailoring easier if any normalization is not desired). Under (normalization => undef), only contiguous contractions are resolved; e.g. even if A-ring (and A-ring-cedilla) is ordered after Z, A-cedilla-ring would be primary equal to A. In this point, (normalization => undef, preprocess => sub { NFD(shift) }) is not equivalent to (normalization => 'NFD').

In the case of (normalization => "prenormalized"), any normalization is not performed, but non-contiguous contractions with combining characters are performed. Therefore (normalization => 'prenormalized', preprocess => sub { NFD(shift) }) is equivalent to (normalization => 'NFD'). If source strings are finely prenormalized, (normalization => 'prenormalized') may save time for normalization.

Except (normalization => undef), Unicode::Normalize is required (see also CAVEAT).

overrideCJK

-- see 7.1 Derived Collation Elements, UTS #10.

By default, CJK Unified Ideographs are ordered in Unicode codepoint order but CJK Unified Ideographs (if UCA_Version is 8 to 11, its range is U+4E00..U+9FA5; if UCA_Version is 14, its range is U+4E00..U+9FBB) are lesser than CJK Unified Ideographs Extension (its range is U+3400..U+4DB5 and U+20000..U+2A6D6).

Through overrideCJK, ordering of CJK Unified Ideographs can be overrided.

ex. CJK Unified Ideographs in the JIS code point order.

  overrideCJK => sub {
      my $u = shift;             # get a Unicode codepoint
      my $b = pack('n', $u);     # to UTF-16BE
      my $s = your_unicode_to_sjis_converter($b); # convert
      my $n = unpack('n', $s);   # convert sjis to short
      [ $n, 0x20, 0x2, $u ];     # return the collation element
  },

ex. ignores all CJK Unified Ideographs.

  overrideCJK => sub {()}, # CODEREF returning empty list

   # where ->eq("Pe\x{4E00}rl", "Perl") is true
   # as U+4E00 is a CJK Unified Ideograph and to be ignorable.

If undef is passed explicitly as the value for this key, weights for CJK Unified Ideographs are treated as undefined. But assignment of weight for CJK Unified Ideographs in table or entry is still valid.

overrideHangul

-- see 7.1 Derived Collation Elements, UTS #10.

By default, Hangul Syllables are decomposed into Hangul Jamo, even if (normalization => undef). But the mapping of Hangul Syllables may be overrided.

This parameter works like overrideCJK, so see there for examples.

If you want to override the mapping of Hangul Syllables, NFD, NFKD, and FCD are not appropriate, since they will decompose Hangul Syllables before overriding.

If undef is passed explicitly as the value for this key, weight for Hangul Syllables is treated as undefined without decomposition into Hangul Jamo. But definition of weight for Hangul Syllables in table or entry is still valid.

preprocess

-- see 5.1 Preprocessing, UTS #10.

If specified, the coderef is used to preprocess before the formation of sort keys.

ex. dropping English articles, such as "a" or "the". Then, "the pen" is before "a pencil".

     preprocess => sub {
           my $str = shift;
           $str =~ s/\b(?:an?|the)\s+//gi;
           return $str;
        },

preprocess is performed before normalization (if defined).

rearrange

-- see 3.1.3 Rearrangement, UTS #10.

Characters that are not coded in logical order and to be rearranged. If UCA_Version is equal to or lesser than 11, default is:

    rearrange => [ 0x0E40..0x0E44, 0x0EC0..0x0EC4 ],

If you want to disallow any rearrangement, pass undef or [] (a reference to empty list) as the value for this key.

If UCA_Version is equal to 14, default is [] (i.e. no rearrangement).

According to the version 9 of UCA, this parameter shall not be used; but it is not warned at present.

table

-- see 3.2 Default Unicode Collation Element Table, UTS #10.

You can use another collation element table if desired.

The table file should locate in the Unicode/Collate directory on @INC. Say, if the filename is Foo.txt, the table file is searched as Unicode/Collate/Foo.txt in @INC.

By default, allkeys.txt (as the filename of DUCET) is used. If you will prepare your own table file, any name other than allkeys.txt may be better to avoid namespace conflict.

If undef is passed explicitly as the value for this key, no file is read (but you can define collation elements via entry).

A typical way to define a collation element table without any file of table:

   $onlyABC = Unicode::Collate->new(
       table => undef,
       entry => << 'ENTRIES',
   0061 ; [.0101.0020.0002.0061] # LATIN SMALL LETTER A
   0041 ; [.0101.0020.0008.0041] # LATIN CAPITAL LETTER A
   0062 ; [.0102.0020.0002.0062] # LATIN SMALL LETTER B
   0042 ; [.0102.0020.0008.0042] # LATIN CAPITAL LETTER B
   0063 ; [.0103.0020.0002.0063] # LATIN SMALL LETTER C
   0043 ; [.0103.0020.0008.0043] # LATIN CAPITAL LETTER C
   ENTRIES
    );

If ignoreName or undefName is used, character names should be specified as a comment (following #) on each line.

undefChar
undefName

-- see 6.3.4 Reducing the Repertoire, UTS #10.

Undefines the collation element as if it were unassigned in the table. This reduces the size of the table. If an unassigned character appears in the string to be collated, the sort key is made from its codepoint as a single-character collation element, as it is greater than any other assigned collation elements (in the codepoint order among the unassigned characters). But, it'd be better to ignore characters unfamiliar to you and maybe never used.

Through undefChar, any character matching qr/$undefChar/ will be undefined. Through undefName, any character whose name (given in the table file as a comment) matches qr/$undefName/ will be undefined.

ex. Collation weights for beyond-BMP characters are not stored in object:

    undefChar => qr/[^\0-\x{fffd}]/,
upper_before_lower

-- see 6.6 Case Comparisons, UTS #10.

By default, lowercase is before uppercase. If the parameter is made true, this is reversed.

NOTE: This parameter simplemindedly assumes that any lowercase/uppercase distinctions must occur in level 3, and their weights at level 3 must be same as those mentioned in 7.3.1, UTS #10. If you define your collation elements which differs from this requirement, this parameter doesn't work validly.

variable

-- see 3.2.2 Variable Weighting, UTS #10.

This key allows to variable weighting for variable collation elements, which are marked with an ASTERISK in the table (NOTE: Many punction marks and symbols are variable in allkeys.txt).

   variable => 'blanked', 'non-ignorable', 'shifted', or 'shift-trimmed'.

These names are case-insensitive. By default (if specification is omitted), 'shifted' is adopted.

   'Blanked'        Variable elements are made ignorable at levels 1 through 3;
                    considered at the 4th level.

   'Non-Ignorable'  Variable elements are not reset to ignorable.
   'Shifted'        Variable elements are made ignorable at levels 1 through 3
                    their level 4 weight is replaced by the old level 1 weight.
                    Level 4 weight for Non-Variable elements is 0xFFFF.
   'Shift-Trimmed'  Same as 'shifted', but all FFFF's at the 4th level
                    are trimmed.

Methods for Collation

@sorted = $Collator->sort(@not_sorted)

Sorts a list of strings.

$result = $Collator->cmp($a, $b)

Returns 1 (when $a is greater than $b) or 0 (when $a is equal to $b) or -1 (when $a is lesser than $b).

$result = $Collator->eq($a, $b)
$result = $Collator->ne($a, $b)
$result = $Collator->lt($a, $b)
$result = $Collator->le($a, $b)
$result = $Collator->gt($a, $b)
$result = $Collator->ge($a, $b)

They works like the same name operators as theirs.

   eq : whether $a is equal to $b.
   ne : whether $a is not equal to $b.
   lt : whether $a is lesser than $b.
   le : whether $a is lesser than $b or equal to $b.
   gt : whether $a is greater than $b.
   ge : whether $a is greater than $b or equal to $b.
$sortKey = $Collator->getSortKey($string)

-- see 4.3 Form Sort Key, UTS #10.

Returns a sort key.

You compare the sort keys using a binary comparison and get the result of the comparison of the strings using UCA.

   $Collator->getSortKey($a) cmp $Collator->getSortKey($b)
      is equivalent to
   $Collator->cmp($a, $b)
$sortKeyForm = $Collator->viewSortKey($string)

Converts a sorting key into its representation form. If UCA_Version is 8, the output is slightly different.

   use Unicode::Collate;
   my $c = Unicode::Collate->new();
   print $c->viewSortKey("Perl"),"\n";

   # output:
   # [0B67 0A65 0B7F 0B03 | 0020 0020 0020 0020 | 0008 0002 0002 0002 | FFFF FFFF FFFF FFFF]
   #  Level 1               Level 2               Level 3               Level 4

Methods for Searching

DISCLAIMER: If preprocess or normalization parameter is true for $Collator, calling these methods (index, match, gmatch, subst, gsubst) is croaked, as the position and the length might differ from those on the specified string. (And rearrange and hangul_terminator parameters are neglected.)

The match, gmatch, subst, gsubst methods work like m//, m//g, s///, s///g, respectively, but they are not aware of any pattern, but only a literal substring.

$position = $Collator->index($string, $substring[, $position])
($position, $length) = $Collator->index($string, $substring[, $position])

If $substring matches a part of $string, returns the position of the first occurrence of the matching part in scalar context; in list context, returns a two-element list of the position and the length of the matching part.

If $substring does not match any part of $string, returns -1 in scalar context and an empty list in list context.

e.g. you say

  my $Collator = Unicode::Collate->new( normalization => undef, level => 1 );
                                     # (normalization => undef) is REQUIRED.
  my $str = "Ich muß studieren Perl.";
  my $sub = "MÜSS";
  my $match;
  if (my($pos,$len) = $Collator->index($str, $sub)) {
      $match = substr($str, $pos, $len);
  }

and get "muß" in $match since "muß" is primary equal to "MÜSS".

$match_ref = $Collator->match($string, $substring)
($match) = $Collator->match($string, $substring)

If $substring matches a part of $string, in scalar context, returns a reference to the first occurrence of the matching part ($match_ref is always true if matches, since every reference is true); in list context, returns the first occurrence of the matching part.

If $substring does not match any part of $string, returns undef in scalar context and an empty list in list context.

e.g.

    if ($match_ref = $Collator->match($str, $sub)) { # scalar context
        print "matches [$$match_ref].\n";
    } else {
        print "doesn't match.\n";
    }

     or
    if (($match) = $Collator->match($str, $sub)) { # list context
        print "matches [$match].\n";
    } else {
        print "doesn't match.\n";
    }
@match = $Collator->gmatch($string, $substring)

If $substring matches a part of $string, returns all the matching parts (or matching count in scalar context).

If $substring does not match any part of $string, returns an empty list.

$count = $Collator->subst($string, $substring, $replacement)

If $substring matches a part of $string, the first occurrence of the matching part is replaced by $replacement ($string is modified) and return $count (always equals to 1).

$replacement can be a CODEREF, taking the matching part as an argument, and returning a string to replace the matching part (a bit similar to s/(..)/$coderef->($1)/e).

$count = $Collator->gsubst($string, $substring, $replacement)

If $substring matches a part of $string, all the occurrences of the matching part is replaced by $replacement ($string is modified) and return $count.

$replacement can be a CODEREF, taking the matching part as an argument, and returning a string to replace the matching part (a bit similar to s/(..)/$coderef->($1)/eg).

e.g.

  my $Collator = Unicode::Collate->new( normalization => undef, level => 1 );
                                     # (normalization => undef) is REQUIRED.
  my $str = "Camel donkey zebra came\x{301}l CAMEL horse cAm\0E\0L...";
  $Collator->gsubst($str, "camel", sub { "<b>$_[0]</b>" });

  # now $str is "<b>Camel</b> donkey zebra <b>came\x{301}l</b> <b>CAMEL</b> horse <b>cAm\0E\0L</b>...";
  # i.e., all the camels are made bold-faced.

Other Methods

%old_tailoring = $Collator->change(%new_tailoring)

Change the value of specified keys and returns the changed part.

    $Collator = Unicode::Collate->new(level => 4);

    $Collator->eq("perl", "PERL"); # false

    %old = $Collator->change(level => 2); # returns (level => 4).

    $Collator->eq("perl", "PERL"); # true

    $Collator->change(%old); # returns (level => 2).

    $Collator->eq("perl", "PERL"); # false

Not all (key,value)s are allowed to be changed. See also @Unicode::Collate::ChangeOK and @Unicode::Collate::ChangeNG.

In the scalar context, returns the modified collator (but it is not a clone from the original).

    $Collator->change(level => 2)->eq("perl", "PERL"); # true

    $Collator->eq("perl", "PERL"); # true; now max level is 2nd.

    $Collator->change(level => 4)->eq("perl", "PERL"); # false
$version = $Collator->version()

Returns the version number (a string) of the Unicode Standard which the table file used by the collator object is based on. If the table does not include a version line (starting with @version), returns "unknown".

UCA_Version()

Returns the tracking version number of UTS #10 this module consults.

Base_Unicode_Version()

Returns the version number of UTS #10 this module consults.

EXPORT

No method will be exported.

INSTALL

Though this module can be used without any table file, to use this module easily, it is recommended to install a table file in the UCA format, by copying it under the directory <a place in @INC>/Unicode/Collate.

The most preferable one is "The Default Unicode Collation Element Table" (aka DUCET), available from the Unicode Consortium's website:

   http://www.unicode.org/Public/UCA/
   http://www.unicode.org/Public/UCA/latest/allkeys.txt (latest version)

If DUCET is not installed, it is recommended to copy the file from http://www.unicode.org/Public/UCA/latest/allkeys.txt to <a place in @INC>/Unicode/Collate/allkeys.txt manually.

CAVEATS

Normalization

Use of the normalization parameter requires the Unicode::Normalize module (see the Unicode::Normalize manpage).

If you need not it (say, in the case when you need not handle any combining characters), assign normalization => undef explicitly.

-- see 6.5 Avoiding Normalization, UTS #10.

Conformance Test

The Conformance Test for the UCA is available under http://www.unicode.org/Public/UCA/.

For CollationTest_SHIFTED.txt, a collator via Unicode::Collate->new( ) should be used; for CollationTest_NON_IGNORABLE.txt, a collator via Unicode::Collate->new(variable => "non-ignorable", level => 3).

Unicode::Normalize is required to try The Conformance Test.

AUTHOR, COPYRIGHT AND LICENSE

The Unicode::Collate module for perl was written by SADAHIRO Tomoyuki, <SADAHIRO@cpan.org>. This module is Copyright(C) 2001-2005, SADAHIRO Tomoyuki. Japan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The file Unicode/Collate/allkeys.txt was copied directly from http://www.unicode.org/Public/UCA/4.1.0/allkeys.txt. This file is Copyright (c) 1991-2005 Unicode, Inc. All rights reserved. Distributed under the Terms of Use in http://www.unicode.org/copyright.html.

SEE ALSO

Unicode Collation Algorithm - UTS #10

http://www.unicode.org/reports/tr10/

The Default Unicode Collation Element Table (DUCET)

http://www.unicode.org/Public/UCA/latest/allkeys.txt

The conformance test for the UCA

http://www.unicode.org/Public/UCA/latest/CollationTest.html

http://www.unicode.org/Public/UCA/latest/CollationTest.zip

Hangul Syllable Type

http://www.unicode.org/Public/UNIDATA/HangulSyllableType.txt

Unicode Normalization Forms - UAX #15

http://www.unicode.org/reports/tr15/


Unicode::Normalize - Unicode Normalization Forms

    • Normalization Forms
    • Decomposition and Composition
    • Quick Check
    • Character Data
  • EXPORT
  • CAVEATS
  • AUTHOR
  • SEE ALSO

NAME

Unicode::Normalize - Unicode Normalization Forms

SYNOPSIS

(1) using function names exported by default:

  use Unicode::Normalize;

  $NFD_string  = NFD($string);  # Normalization Form D
  $NFC_string  = NFC($string);  # Normalization Form C
  $NFKD_string = NFKD($string); # Normalization Form KD
  $NFKC_string = NFKC($string); # Normalization Form KC

(2) using function names exported on request:

  use Unicode::Normalize 'normalize';

  $NFD_string  = normalize('D',  $string);  # Normalization Form D
  $NFC_string  = normalize('C',  $string);  # Normalization Form C
  $NFKD_string = normalize('KD', $string);  # Normalization Form KD
  $NFKC_string = normalize('KC', $string);  # Normalization Form KC

DESCRIPTION

Parameters:

$string is used as a string under character semantics (see perlunicode).

$codepoint should be an unsigned integer representing a Unicode code point.

Note: Between XSUB and pure Perl, there is an incompatibility about the interpretation of $codepoint as a decimal number. XSUB converts $codepoint to an unsigned integer, but pure Perl does not. Do not use a floating point nor a negative sign in $codepoint.

Normalization Forms

$NFD_string = NFD($string)

returns the Normalization Form D (formed by canonical decomposition).

$NFC_string = NFC($string)

returns the Normalization Form C (formed by canonical decomposition followed by canonical composition).

$NFKD_string = NFKD($string)

returns the Normalization Form KD (formed by compatibility decomposition).

$NFKC_string = NFKC($string)

returns the Normalization Form KC (formed by compatibility decomposition followed by canonical composition).

$FCD_string = FCD($string)

If the given string is in FCD ("Fast C or D" form; cf. UTN #5), returns it without modification; otherwise returns an FCD string.

Note: FCD is not always unique, then plural forms may be equivalent each other. FCD() will return one of these equivalent forms.

$FCC_string = FCC($string)

returns the FCC form ("Fast C Contiguous"; cf. UTN #5).

Note: FCC is unique, as well as four normalization forms (NF*).

$normalized_string = normalize($form_name, $string)

As $form_name, one of the following names must be given.

  'C'  or 'NFC'  for Normalization Form C  (UAX #15)
  'D'  or 'NFD'  for Normalization Form D  (UAX #15)
  'KC' or 'NFKC' for Normalization Form KC (UAX #15)
  'KD' or 'NFKD' for Normalization Form KD (UAX #15)
  'FCD'          for "Fast C or D" Form  (UTN #5)
  'FCC'          for "Fast C Contiguous" (UTN #5)

Decomposition and Composition

$decomposed_string = decompose($string)
$decomposed_string = decompose($string, $useCompatMapping)

Decomposes the specified string and returns the result.

If the second parameter (a boolean) is omitted or false, decomposes it using the Canonical Decomposition Mapping. If true, decomposes it using the Compatibility Decomposition Mapping.

The string returned is not always in NFD/NFKD. Reordering may be required.

    $NFD_string  = reorder(decompose($string));       # eq. to NFD()
    $NFKD_string = reorder(decompose($string, TRUE)); # eq. to NFKD()
$reordered_string = reorder($string)

Reorders the combining characters and the like in the canonical ordering and returns the result.

E.g., when you have a list of NFD/NFKD strings, you can get the concatenated NFD/NFKD string from them, saying

    $concat_NFD  = reorder(join '', @NFD_strings);
    $concat_NFKD = reorder(join '', @NFKD_strings);
$composed_string = compose($string)

Returns the string where composable pairs are composed.

E.g., when you have a NFD/NFKD string, you can get its NFC/NFKC string, saying

    $NFC_string  = compose($NFD_string);
    $NFKC_string = compose($NFKD_string);

Quick Check

(see Annex 8, UAX #15; and DerivedNormalizationProps.txt)

The following functions check whether the string is in that normalization form.

The result returned will be:

    YES     The string is in that normalization form.
    NO      The string is not in that normalization form.
    MAYBE   Dubious. Maybe yes, maybe no.
$result = checkNFD($string)

returns true (1) if YES; false (empty string) if NO.

$result = checkNFC($string)

returns true (1) if YES; false (empty string) if NO; undef if MAYBE.

$result = checkNFKD($string)

returns true (1) if YES; false (empty string) if NO.

$result = checkNFKC($string)

returns true (1) if YES; false (empty string) if NO; undef if MAYBE.

$result = checkFCD($string)

returns true (1) if YES; false (empty string) if NO.

$result = checkFCC($string)

returns true (1) if YES; false (empty string) if NO; undef if MAYBE.

If a string is not in FCD, it must not be in FCC. So checkFCC($not_FCD_string) should return NO.

$result = check($form_name, $string)

returns true (1) if YES; false (empty string) if NO; undef if MAYBE.

As $form_name, one of the following names must be given.

  'C'  or 'NFC'  for Normalization Form C  (UAX #15)
  'D'  or 'NFD'  for Normalization Form D  (UAX #15)
  'KC' or 'NFKC' for Normalization Form KC (UAX #15)
  'KD' or 'NFKD' for Normalization Form KD (UAX #15)
  'FCD'          for "Fast C or D" Form  (UTN #5)
  'FCC'          for "Fast C Contiguous" (UTN #5)

Note

In the cases of NFD, NFKD, and FCD, the answer must be either YES or NO. The answer MAYBE may be returned in the cases of NFC, NFKC, and FCC.

A MAYBE string should contain at least one combining character or the like. For example, COMBINING ACUTE ACCENT has the MAYBE_NFC/MAYBE_NFKC property.

Both checkNFC("A\N{COMBINING ACUTE ACCENT}") and checkNFC("B\N{COMBINING ACUTE ACCENT}") will return MAYBE. "A\N{COMBINING ACUTE ACCENT}" is not in NFC (its NFC is "\N{LATIN CAPITAL LETTER A WITH ACUTE}"), while "B\N{COMBINING ACUTE ACCENT}" is in NFC.

If you want to check exactly, compare the string with its NFC/NFKC/FCC.

    if ($string eq NFC($string)) {
        # $string is exactly normalized in NFC;
    } else {
        # $string is not normalized in NFC;
    }

    if ($string eq NFKC($string)) {
        # $string is exactly normalized in NFKC;
    } else {
        # $string is not normalized in NFKC;
    }

Character Data

These functions are interface of character data used internally. If you want only to get Unicode normalization forms, you don't need call them yourself.

$canonical_decomposed = getCanon($codepoint)

If the character of the specified codepoint is canonically decomposable (including Hangul Syllables), returns the completely decomposed string canonically equivalent to it.

If it is not decomposable, returns undef.

$compatibility_decomposed = getCompat($codepoint)

If the character of the specified codepoint is compatibility decomposable (including Hangul Syllables), returns the completely decomposed string compatibility equivalent to it.

If it is not decomposable, returns undef.

$codepoint_composite = getComposite($codepoint_here, $codepoint_next)

If two characters here and next (as codepoints) are composable (including Hangul Jamo/Syllables and Composition Exclusions), returns the codepoint of the composite.

If they are not composable, returns undef.

$combining_class = getCombinClass($codepoint)

Returns the combining class of the character as an integer.

$is_exclusion = isExclusion($codepoint)

Returns a boolean whether the character of the specified codepoint is a composition exclusion.

$is_singleton = isSingleton($codepoint)

Returns a boolean whether the character of the specified codepoint is a singleton.

$is_non_starter_decomposition = isNonStDecomp($codepoint)

Returns a boolean whether the canonical decomposition of the character of the specified codepoint is a Non-Starter Decomposition.

$may_be_composed_with_prev_char = isComp2nd($codepoint)

Returns a boolean whether the character of the specified codepoint may be composed with the previous one in a certain composition (including Hangul Compositions, but excluding Composition Exclusions and Non-Starter Decompositions).

EXPORT

NFC, NFD, NFKC, NFKD: by default.

normalize and other some functions: on request.

CAVEATS

Perl's version vs. Unicode version

Since this module refers to perl core's Unicode database in the directory /lib/unicore (or formerly /lib/unicode), the Unicode version of normalization implemented by this module depends on your perl's version.

    perl's version         implemented Unicode version
       5.6.1                  3.0.1
       5.7.2                  3.1.0
       5.7.3                  3.1.1 (same normalized form as that of 3.1.0)
       5.8.0                  3.2.0
     5.8.1-5.8.3              4.0.0
     5.8.4-5.8.6 (latest)     4.0.1 (same normalized form as that of 4.0.0)
Correction of decomposition mapping

In older Unicode versions, a small number of characters (all of which are CJK compatibility ideographs as far as they have been found) may have an erroneous decomposition mapping (see NormalizationCorrections.txt). Anyhow, this module will neither refer to NormalizationCorrections.txt nor provide any specific version of normalization. Therefore this module running on an older perl with an older Unicode database may use the erroneous decomposition mapping blindly conforming to the Unicode database.

Revised definition of canonical composition

In Unicode 4.1.0, the definition D2 of canonical composition (which affects NFC and NFKC) has been changed (see Public Review Issue #29 and recent UAX #15). This module has used the newer definition since the version 0.07 (Oct 31, 2001). This module does not support normalization according to the older definition, even if the Unicode version implemented by perl is lower than 4.1.0.

AUTHOR

SADAHIRO Tomoyuki <SADAHIRO@cpan.org>

Copyright(C) 2001-2005, SADAHIRO Tomoyuki. Japan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

http://www.unicode.org/reports/tr15/

Unicode Normalization Forms - UAX #15

http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt

Derived Normalization Properties

http://www.unicode.org/Public/UNIDATA/NormalizationCorrections.txt

Normalization Corrections

http://www.unicode.org/review/pr-29.html

Public Review Issue #29: Normalization Issue

http://www.unicode.org/notes/tn5/

Canonical Equivalence in Applications - UTN #5


Unicode::String - String of Unicode characters

    • METHODS
    • Class methods
    • Encoding methods
    • String Operations
  • FUNCTIONS
  • SEE ALSO
  • COPYRIGHT

NAME

Unicode::String - String of Unicode characters (UTF-16BE)

SYNOPSIS

 use Unicode::String qw(utf8 latin1 utf16be);

 $u = utf8("string");
 $u = latin1("string");
 $u = utf16be("\0s\0t\0r\0i\0n\0g");

 print $u->utf32be;   # 4 byte characters
 print $u->utf16le;   # 2 byte characters + surrogates
 print $u->utf8;      # 1-4 byte characters

DESCRIPTION

A Unicode::String object represents a sequence of Unicode characters. Methods are provided to convert between various external formats (encodings) and Unicode::String objects, and methods are provided for common string manipulations.

The functions utf32be(), utf32le(), utf16be(), utf16le(), utf8(), utf7(), latin1(), uhex(), uchr() can be imported from the Unicode::String module and will work as constructors initializing strings of the corresponding encoding.

The Unicode::String objects overload various operators, which means that they in most cases can be treated like plain strings.

Internally a Unicode::String object is represented by a string of 2 byte numbers in network byte order (big-endian). This representation is not visible by the API provided, but it might be useful to know in order to predict the efficiency of the provided methods.

METHODS

Class methods

The following class methods are available:

Unicode::String->stringify_as
Unicode::String->stringify_as( $enc )

This method is used to specify which encoding will be used when Unicode::String objects are implicitly converted to and from plain strings.

If an argument is provided it sets the current encoding. The argument should have one of the following: "ucs4", "utf32", "utf32be", "utf32le", "ucs2", "utf16", "utf16be", "utf16le", "utf8", "utf7", "latin1" or "hex". The default is "utf8".

The stringify_as() method returns a reference to the current encoding function.

$us = Unicode::String->new
$us = Unicode::String->new( $initial_value )

This is the object constructor. Without argument, it creates an empty Unicode::String object. If an $initial_value argument is given, it is decoded according to the specified stringify_as() encoding, UTF-8 by default.

In general it is recommended to import and use one of the encoding specific constructor functions instead of invoking this method.

Encoding methods

These methods get or set the value of the Unicode::String object by passing strings in the corresponding encoding. If a new value is passed as argument it will set the value of the Unicode::String, and the previous value is returned. If no argument is passed then the current value is returned.

To illustrate the encodings we show how the 2 character sample string of "µm" (micro meter) is encoded for each one.

$us->utf32be
$us->utf32be( $newval )

The string passed should be in the UTF-32 encoding with bytes in big endian order. The sample "µm" is "\0\0\0\xB5\0\0\0m" in this encoding.

Alternative names for this method are utf32() and ucs4().

$us->utf32le
$us->utf32le( $newval )

The string passed should be in the UTF-32 encoding with bytes in little endian order. The sample "µm" is is "\xB5\0\0\0m\0\0\0" in this encoding.

$us->utf16be
$us->utf16be( $newval )

The string passed should be in the UTF-16 encoding with bytes in big endian order. The sample "µm" is "\0\xB5\0m" in this encoding.

Alternative names for this method are utf16() and ucs2().

If the string passed to utf16be() starts with the Unicode byte order mark in little endian order, the result is as if utf16le() was called instead.

$us->utf16le
$us->utf16le( $newval )

The string passed should be in the UTF-16 encoding with bytes in little endian order. The sample "µm" is is "\xB5\0m\0" in this encoding. This is the encoding used by the Microsoft Windows API.

If the string passed to utf16le() starts with the Unicode byte order mark in big endian order, the result is as if utf16le() was called instead.

$us->utf8
$us->utf8( $newval )

The string passed should be in the UTF-8 encoding. The sample "µm" is "\xC2\xB5m" in this encoding.

$us->utf7
$us->utf7( $newval )

The string passed should be in the UTF-7 encoding. The sample "µm" is "+ALU-m" in this encoding.

The UTF-7 encoding only use plain US-ASCII characters for the encoding. This makes it safe for transport through 8-bit stripping protocols. Characters outside the US-ASCII range are base64-encoded and '+' is used as an escape character. The UTF-7 encoding is described in RFC 1642.

If the (global) variable $Unicode::String::UTF7_OPTIONAL_DIRECT_CHARS is TRUE, then a wider range of characters are encoded as themselves. It is even TRUE by default. The characters affected by this are:

   ! " # $ % & * ; < = > @ [ ] ^ _ ` { | }
$us->latin1
$us->latin1( $newval )

The string passed should be in the ISO-8859-1 encoding. The sample "µm" is "\xB5m" in this encoding.

Characters outside the "\x00" .. "\xFF" range are simply removed from the return value of the latin1() method. If you want more control over the mapping from Unicode to ISO-8859-1, use the Unicode::Map8 class. This is also the way to deal with other 8-bit character sets.

$us->hex
$us->hex( $newval )

The string passed should be plain ASCII where each Unicode character is represented by the "U+XXXX" string and separated by a single space character. The "U+" prefix is optional when setting the value. The sample "µm" is "U+00b5 U+006d" in this encoding.

String Operations

The following methods are available:

$us->as_string

Converts a Unicode::String to a plain string according to the setting of stringify_as(). The default stringify_as() encoding is "utf8".

$us->as_num

Converts a Unicode::String to a number. Currently only the digits in the range 0x30 .. 0x39 are recognized. The plan is to eventually support all Unicode digit characters.

$us->as_bool

Converts a Unicode::String to a boolean value. Only the empty string is FALSE. A string consisting of only the character U+0030 is considered TRUE, even if Perl consider "0" to be FALSE.

$us->repeat( $count )

Returns a new Unicode::String where the content of $us is repeated $count times. This operation is also overloaded as:

  $us x $count
$us->concat( $other_string )

Concatenates the string $us and the string $other_string. If $other_string is not an Unicode::String object, then it is first passed to the Unicode::String->new constructor function. This operation is also overloaded as:

  $us . $other_string
$us->append( $other_string )

Appends the string $other_string to the value of $us. If $other_string is not an Unicode::String object, then it is first passed to the Unicode::String->new constructor function. This operation is also overloaded as:

  $us .= $other_string
$us->copy

Returns a copy of the current Unicode::String object. This operation is overloaded as the assignment operator.

$us->length

Returns the length of the Unicode::String. Surrogate pairs are still counted as 2.

$us->byteswap

This method will swap the bytes in the internal representation of the Unicode::String object.

Unicode reserve the character U+FEFF character as a byte order mark. This works because the swapped character, U+FFFE, is reserved to not be valid. For strings that have the byte order mark as the first character, we can guaranty to get the byte order right with the following code:

   $ustr->byteswap if $ustr->ord == 0xFFFE;
$us->unpack

Returns a list of integers each representing an UCS-2 character code.

$us->pack( @uchr )

Sets the value of $us as a sequence of UCS-2 characters with the characters codes given as parameter.

$us->ord

Returns the character code of the first character in $us. The ord() method deals with surrogate pairs, which gives us a result-range of 0x0 .. 0x10FFFF. If the $us string is empty, undef is returned.

$us->chr( $code )

Sets the value of $us to be a string containing the character assigned code $code. The argument $code must be an integer in the range 0x0 .. 0x10FFFF. If the code is greater than 0xFFFF then a surrogate pair created.

$us->name

In scalar context returns the official Unicode name of the first character in $us. In array context returns the name of all characters in $us. Also see the Unicode::CharName manpage.

$us->substr( $offset )
$us->substr( $offset, $length )
$us->substr( $offset, $length, $subst )

Returns a sub-string of $us. Works similar to the builtin substr() function.

$us->index( $other )
$us->index( $other, $pos )

Locates the position of $other within $us, possibly starting the search at position $pos.

$us->chop

Chops off the last character of $us and returns it (as a Unicode::String object).

FUNCTIONS

The following functions are provided. None of these are exported by default.

byteswap2( $str, ... )

This function will swap 2 and 2 bytes in the strings passed as arguments. If this function is called in void context, then it will modify its arguments in-place. Otherwise, the swapped strings are returned.

byteswap4( $str, ... )

The byteswap4 function works similar to byteswap2, but will reverse the order of 4 and 4 bytes.

latin1( $str )
utf7( $str )
utf8( $str )
utf16le( $str )
utf16be( $str )
utf32le( $str )
utf32be( $str )

Constructor functions for the various Unicode encodings. These return new Unicode::String objects. The provided argument should be encoded correspondingly.

uhex( $str )

Constructs a new Unicode::String object from a string of hex values. See hex() method above for description of the format.

uchar( $num )

Constructs a new one character Unicode::String object from a Unicode character code. This works similar to perl's builtin chr() function.

SEE ALSO

the Unicode::CharName manpage, the Unicode::Map8 manpage

http://www.unicode.org/

the perlunicode manpage

COPYRIGHT

Copyright 1997-2000,2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Unicode::UCD - Unicode character database

    • charinfo
    • charblock
    • charscript
    • charblocks
    • charscripts
    • Blocks versus Scripts
    • Matching Scripts and Blocks
    • Code Point Arguments
    • charinrange
    • compexcl
    • casefold
    • casespec
    • namedseq()
    • Unicode::UCD::UnicodeVersion
    • Implementation Note
  • BUGS
  • AUTHOR

NAME

Unicode::UCD - Unicode character database

SYNOPSIS

    use Unicode::UCD 'charinfo';
    my $charinfo   = charinfo($codepoint);

    use Unicode::UCD 'charblock';
    my $charblock  = charblock($codepoint);

    use Unicode::UCD 'charscript';
    my $charscript = charscript($codepoint);

    use Unicode::UCD 'charblocks';
    my $charblocks = charblocks();

    use Unicode::UCD 'charscripts';
    my %charscripts = charscripts();

    use Unicode::UCD qw(charscript charinrange);
    my $range = charscript($script);
    print "looks like $script\n" if charinrange($range, $codepoint);

    use Unicode::UCD 'compexcl';
    my $compexcl = compexcl($codepoint);

    use Unicode::UCD 'namedseq';
    my $namedseq = namedseq($named_sequence_name);

    my $unicode_version = Unicode::UCD::UnicodeVersion();

DESCRIPTION

The Unicode::UCD module offers a simple interface to the Unicode Character Database.

charinfo

    use Unicode::UCD 'charinfo';

    my $charinfo = charinfo(0x41);

charinfo() returns a reference to a hash that has the following fields as defined by the Unicode standard:

    key
    code             code point with at least four hexdigits
    name             name of the character IN UPPER CASE
    category         general category of the character
    combining        classes used in the Canonical Ordering Algorithm
    bidi             bidirectional category
    decomposition    character decomposition mapping
    decimal          if decimal digit this is the integer numeric value
    digit            if digit this is the numeric value
    numeric          if numeric is the integer or rational numeric value
    mirrored         if mirrored in bidirectional text
    unicode10        Unicode 1.0 name if existed and different
    comment          ISO 10646 comment field
    upper            uppercase equivalent mapping
    lower            lowercase equivalent mapping
    title            titlecase equivalent mapping
    block            block the character belongs to (used in \p{In...})
    script           script the character belongs to

If no match is found, a reference to an empty hash is returned.

The block property is the same as returned by charinfo(). It is not defined in the Unicode Character Database proper (Chapter 4 of the Unicode 3.0 Standard, aka TUS3) but instead in an auxiliary database (Chapter 14 of TUS3). Similarly for the script property.

Note that you cannot do (de)composition and casing based solely on the above decomposition and lower, upper, title, properties, you will need also the compexcl(), casefold(), and casespec() functions.

charblock

    use Unicode::UCD 'charblock';

    my $charblock = charblock(0x41);
    my $charblock = charblock(1234);
    my $charblock = charblock("0x263a");
    my $charblock = charblock("U+263a");

    my $range     = charblock('Armenian');

With a code point argument charblock() returns the block the character belongs to, e.g. Basic Latin. Note that not all the character positions within all blocks are defined.

See also Blocks versus Scripts.

If supplied with an argument that can't be a code point, charblock() tries to do the opposite and interpret the argument as a character block. The return value is a range: an anonymous list of lists that contain start-of-range, end-of-range code point pairs. You can test whether a code point is in a range using the charinrange function. If the argument is not a known character block, undef is returned.

charscript

    use Unicode::UCD 'charscript';

    my $charscript = charscript(0x41);
    my $charscript = charscript(1234);
    my $charscript = charscript("U+263a");

    my $range      = charscript('Thai');

With a code point argument charscript() returns the script the character belongs to, e.g. Latin, Greek, Han.

See also Blocks versus Scripts.

If supplied with an argument that can't be a code point, charscript() tries to do the opposite and interpret the argument as a character script. The return value is a range: an anonymous list of lists that contain start-of-range, end-of-range code point pairs. You can test whether a code point is in a range using the charinrange function. If the argument is not a known character script, undef is returned.

charblocks

    use Unicode::UCD 'charblocks';

    my $charblocks = charblocks();

charblocks() returns a reference to a hash with the known block names as the keys, and the code point ranges (see charblock) as the values.

See also Blocks versus Scripts.

charscripts

    use Unicode::UCD 'charscripts';

    my %charscripts = charscripts();

charscripts() returns a hash with the known script names as the keys, and the code point ranges (see charscript) as the values.

See also Blocks versus Scripts.

Blocks versus Scripts

The difference between a block and a script is that scripts are closer to the linguistic notion of a set of characters required to present languages, while block is more of an artifact of the Unicode character numbering and separation into blocks of (mostly) 256 characters.

For example the Latin script is spread over several blocks, such as Basic Latin, Latin 1 Supplement, Latin Extended-A, and Latin Extended-B. On the other hand, the Latin script does not contain all the characters of the Basic Latin block (also known as the ASCII): it includes only the letters, and not, for example, the digits or the punctuation.

For blocks see http://www.unicode.org/Public/UNIDATA/Blocks.txt

For scripts see UTR #24: http://www.unicode.org/unicode/reports/tr24/

Matching Scripts and Blocks

Scripts are matched with the regular-expression construct \p{...} (e.g. \p{Tibetan} matches characters of the Tibetan script), while \p{In...} is used for blocks (e.g. \p{InTibetan} matches any of the 256 code points in the Tibetan block).

Code Point Arguments

A code point argument is either a decimal or a hexadecimal scalar designating a Unicode character, or U+ followed by hexadecimals designating a Unicode character. In other words, if you want a code point to be interpreted as a hexadecimal number, you must prefix it with either 0x or U+, because a string like e.g. 123 will be interpreted as a decimal code point. Also note that Unicode is not limited to 16 bits (the number of Unicode characters is open-ended, in theory unlimited): you may have more than 4 hexdigits.

charinrange

In addition to using the \p{In...} and \P{In...} constructs, you can also test whether a code point is in the range as returned by charblock and charscript or as the values of the hash returned by charblocks and charscripts by using charinrange():

    use Unicode::UCD qw(charscript charinrange);

    $range = charscript('Hiragana');
    print "looks like hiragana\n" if charinrange($range, $codepoint);

compexcl

    use Unicode::UCD 'compexcl';

    my $compexcl = compexcl("09dc");

The compexcl() returns the composition exclusion (that is, if the character should not be produced during a precomposition) of the character specified by a code point argument.

If there is a composition exclusion for the character, true is returned. Otherwise, false is returned.

casefold

    use Unicode::UCD 'casefold';

    my $casefold = casefold("00DF");

The casefold() returns the locale-independent case folding of the character specified by a code point argument.

If there is a case folding for that character, a reference to a hash with the following fields is returned:

    key
    code             code point with at least four hexdigits
    status           "C", "F", "S", or "I"
    mapping          one or more codes separated by spaces

The meaning of the status is as follows:

   C                 common case folding, common mappings shared
                     by both simple and full mappings
   F                 full case folding, mappings that cause strings
                     to grow in length. Multiple characters are separated
                     by spaces
   S                 simple case folding, mappings to single characters
                     where different from F
   I                 special case for dotted uppercase I and
                     dotless lowercase i
                     - If this mapping is included, the result is
                       case-insensitive, but dotless and dotted I's
                       are not distinguished
                     - If this mapping is excluded, the result is not
                       fully case-insensitive, but dotless and dotted
                       I's are distinguished

If there is no case folding for that character, undef is returned.

For more information about case mappings see http://www.unicode.org/unicode/reports/tr21/

casespec

    use Unicode::UCD 'casespec';

    my $casespec = casespec("FB00");

The casespec() returns the potentially locale-dependent case mapping of the character specified by a code point argument. The mapping may change the length of the string (which the basic Unicode case mappings as returned by charinfo() never do).

If there is a case folding for that character, a reference to a hash with the following fields is returned:

    key
    code             code point with at least four hexdigits
    lower            lowercase
    title            titlecase
    upper            uppercase
    condition        condition list (may be undef)

The condition is optional. Where present, it consists of one or more locales or contexts, separated by spaces (other than as used to separate elements, spaces are to be ignored). A condition list overrides the normal behavior if all of the listed conditions are true. Case distinctions in the condition list are not significant. Conditions preceded by "NON_" represent the negation of the condition.

Note that when there are multiple case folding definitions for a single code point because of different locales, the value returned by casespec() is a hash reference which has the locales as the keys and hash references as described above as the values.

A locale is defined as a 2-letter ISO 3166 country code, possibly followed by a "_" and a 2-letter ISO language code (possibly followed by a "_" and a variant code). You can find the lists of those codes, see the Locale::Country manpage and the Locale::Language manpage.

A context is one of the following choices:

    FINAL            The letter is not followed by a letter of
                     general category L (e.g. Ll, Lt, Lu, Lm, or Lo)
    MODERN           The mapping is only used for modern text
    AFTER_i          The last base character was "i" (U+0069)

For more information about case mappings see http://www.unicode.org/unicode/reports/tr21/

namedseq()

    use Unicode::UCD 'namedseq';

    my $namedseq = namedseq("KATAKANA LETTER AINU P");
    my @namedseq = namedseq("KATAKANA LETTER AINU P");
    my %namedseq = namedseq();

If used with a single argument in a scalar context, returns the string consisting of the code points of the named sequence, or undef if no named sequence by that name exists. If used with a single argument in a list context, returns list of the code points. If used with no arguments in a list context, returns a hash with the names of the named sequences as the keys and the named sequences as strings as the values. Otherwise, returns undef or empty list depending on the context.

(New from Unicode 4.1.0)

Unicode::UCD::UnicodeVersion

Unicode::UCD::UnicodeVersion() returns the version of the Unicode Character Database, in other words, the version of the Unicode standard the database implements. The version is a string of numbers delimited by dots ('.').

Implementation Note

The first use of charinfo() opens a read-only filehandle to the Unicode Character Database (the database is included in the Perl distribution). The filehandle is then kept open for further queries. In other words, if you are wondering where one of your filehandles went, that's where.

BUGS

Does not yet support EBCDIC platforms.

AUTHOR

Jarkko Hietaniemi


User::grent - by-name interface to Perl's built-in getgr* functions

  • NOTE
  • AUTHOR

NAME

User::grent - by-name interface to Perl's built-in getgr*() functions

SYNOPSIS

 use User::grent;
 $gr = getgrgid(0) or die "No group zero";
 if ( $gr->name eq 'wheel' && @{$gr->members} > 1 ) {
     print "gid zero name wheel, with other members";
 }

 use User::grent qw(:FIELDS);
 getgrgid(0) or die "No group zero";
 if ( $gr_name eq 'wheel' && @gr_members > 1 ) {
     print "gid zero name wheel, with other members";
 }

 $gr = getgr($whoever);

DESCRIPTION

This module's default exports override the core getgrent(), getgruid(), and getgrnam() functions, replacing them with versions that return "User::grent" objects. This object has methods that return the similarly named structure field name from the C's passwd structure from grp.h; namely name, passwd, gid, and members (not mem). The first three return scalars, the last an array reference.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding gr_. Thus, $group_obj->gid() corresponds to $gr_gid if you import the fields. Array references are available as regular array variables, so @{ $group_obj->members() } would be simply @gr_members.

The getpw() function is a simple front-end that forwards a numeric argument to getpwuid() and the rest to getpwnam().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. On the other hand, the built-ins are still available via the CORE:: pseudo-package.

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen


User::pwent - by-name interface to Perl's built-in getpw* functions

    • System Specifics
  • NOTE
  • AUTHOR
  • HISTORY

NAME

User::pwent - by-name interface to Perl's built-in getpw*() functions

SYNOPSIS

 use User::pwent;
 $pw = getpwnam('daemon')       || die "No daemon user";
 if ( $pw->uid == 1 && $pw->dir =~ m#^/(bin|tmp)?\z#s ) {
     print "gid 1 on root dir";
 }

 $real_shell = $pw->shell || '/bin/sh';

 for (($fullname, $office, $workphone, $homephone) =
        split /\s*,\s*/, $pw->gecos)
 {
    s/&/ucfirst(lc($pw->name))/ge;
 }

 use User::pwent qw(:FIELDS);
 getpwnam('daemon')             || die "No daemon user";
 if ( $pw_uid == 1 && $pw_dir =~ m#^/(bin|tmp)?\z#s ) {
     print "gid 1 on root dir";
 }

 $pw = getpw($whoever);

 use User::pwent qw/:DEFAULT pw_has/;
 if (pw_has(qw[gecos expire quota])) { .... }
 if (pw_has("name uid gid passwd"))  { .... }
 print "Your struct pwd has: ", scalar pw_has(), "\n";

DESCRIPTION

This module's default exports override the core getpwent(), getpwuid(), and getpwnam() functions, replacing them with versions that return User::pwent objects. This object has methods that return the similarly named structure field name from the C's passwd structure from pwd.h, stripped of their leading "pw_" parts, namely name, passwd, uid, gid, change, age, quota, comment, class, gecos, dir, shell, and expire. The passwd, gecos, and shell fields are tainted when running in taint mode.

You may also import all the structure fields directly into your namespace as regular variables using the :FIELDS import tag. (Note that this still overrides your core functions.) Access these fields as variables named with a preceding pw_ in front their method names. Thus, $passwd_obj->shell corresponds to $pw_shell if you import the fields.

The getpw() function is a simple front-end that forwards a numeric argument to getpwuid() and the rest to getpwnam().

To access this functionality without the core overrides, pass the use an empty import list, and then access function functions with their full qualified names. The built-ins are always still available via the CORE:: pseudo-package.

System Specifics

Perl believes that no machine ever has more than one of change, age, or quota implemented, nor more than one of either comment or class. Some machines do not support expire, gecos, or allegedly, passwd. You may call these methods no matter what machine you're on, but they return undef if unimplemented.

You may ask whether one of these was implemented on the system Perl was built on by asking the importable pw_has function about them. This function returns true if all parameters are supported fields on the build platform, false if one or more were not, and raises an exception if you asked about a field that Perl never knows how to provide. Parameters may be in a space-separated string, or as separate arguments. If you pass no parameters, the function returns the list of struct pwd fields supported by your build platform's C library, as a list in list context, or a space-separated string in scalar context. Note that just because your C library had a field doesn't necessarily mean that it's fully implemented on that system.

Interpretation of the gecos field varies between systems, but traditionally holds 4 comma-separated fields containing the user's full name, office location, work phone number, and home phone number. An & in the gecos field should be replaced by the user's properly capitalized login name. The shell field, if blank, must be assumed to be /bin/sh. Perl does not do this for you. The passwd is one-way hashed garble, not clear text, and may not be unhashed save by brute-force guessing. Secure systems use more a more secure hashing than DES. On systems supporting shadow password systems, Perl automatically returns the shadow password entry when called by a suitably empowered user, even if your underlying vendor-provided C library was too short-sighted to realize it should do this.

See passwd(5) and getpwent(3) for details.

NOTE

While this class is currently implemented using the Class::Struct module to build a struct-like class, you shouldn't rely upon this.

AUTHOR

Tom Christiansen

HISTORY

March 18th, 2000

Reworked internals to support better interface to dodgey fields than normal Perl function provides. Added pw_has() field. Improved documentation.


WWW::RobotRules - database of robots.txt-derived permissions

  • ROBOTS.TXT
  • ROBOTS.TXT EXAMPLES
  • SEE ALSO

NAME

WWW::RobotRules - database of robots.txt-derived permissions

SYNOPSIS

 use WWW::RobotRules;
 my $rules = WWW::RobotRules->new('MOMspider/1.0');

 use LWP::Simple qw(get);

 {
   my $url = "http://some.place/robots.txt";
   my $robots_txt = get $url;
   $rules->parse($url, $robots_txt) if defined $robots_txt;
 }

 {
   my $url = "http://some.other.place/robots.txt";
   my $robots_txt = get $url;
   $rules->parse($url, $robots_txt) if defined $robots_txt;
 }

 # Now we can check if a URL is valid for those servers
 # whose "robots.txt" files we've gotten and parsed:
 if($rules->allowed($url)) {
     $c = get $url;
     ...
 }

DESCRIPTION

This module parses /robots.txt files as specified in "A Standard for Robot Exclusion", at <http://www.robotstxt.org/wc/norobots.html> Webmasters can use the /robots.txt file to forbid conforming robots from accessing parts of their web site.

The parsed files are kept in a WWW::RobotRules object, and this object provides methods to check if access to a given URL is prohibited. The same WWW::RobotRules object can be used for one or more parsed /robots.txt files on any number of hosts.

The following methods are provided:

$rules = WWW::RobotRules->new($robot_name)

This is the constructor for WWW::RobotRules objects. The first argument given to new() is the name of the robot.

$rules->parse($robot_txt_url, $content, $fresh_until)

The parse() method takes as arguments the URL that was used to retrieve the /robots.txt file, and the contents of the file.

$rules->allowed($uri)

Returns TRUE if this robot is allowed to retrieve this URL.

$rules->agent([$name])

Get/set the agent name. NOTE: Changing the agent name will clear the robots.txt rules and expire times out of the cache.

ROBOTS.TXT

The format and semantics of the "/robots.txt" file are as follows (this is an edited abstract of <http://www.robotstxt.org/wc/norobots.html> ):

The file consists of one or more records separated by one or more blank lines. Each record contains lines of the form

  <field-name>: <value>

The field name is case insensitive. Text after the '#' character on a line is ignored during parsing. This is used for comments. The following <field-names> can be used:

User-Agent

The value of this field is the name of the robot the record is describing access policy for. If more than one User-Agent field is present the record describes an identical access policy for more than one robot. At least one field needs to be present per record. If the value is '*', the record describes the default access policy for any robot that has not not matched any of the other records.

The User-Agent fields must occur before the Disallow fields. If a record contains a User-Agent field after a Disallow field, that constitutes a malformed record. This parser will assume that a blank line should have been placed before that User-Agent field, and will break the record into two. All the fields before the User-Agent field will constitute a record, and the User-Agent field will be the first field in a new record.

Disallow

The value of this field specifies a partial URL that is not to be visited. This can be a full path, or a partial path; any URL that starts with this value will not be retrieved

ROBOTS.TXT EXAMPLES

The following example "/robots.txt" file specifies that no robots should visit any URL starting with "/cyberworld/map/" or "/tmp/":

  User-agent: *
  Disallow: /cyberworld/map/ # This is an infinite virtual URL space
  Disallow: /tmp/ # these will soon disappear

This example "/robots.txt" file specifies that no robots should visit any URL starting with "/cyberworld/map/", except the robot called "cybermapper":

  User-agent: *
  Disallow: /cyberworld/map/ # This is an infinite virtual URL space
  # Cybermapper knows where to go.
  User-agent: cybermapper
  Disallow:

This example indicates that no robots should visit this site further:

  # go away
  User-agent: *
  Disallow: /

This is an example of a malformed robots.txt file.

  # robots.txt for ancientcastle.example.com
  # I've locked myself away.
  User-agent: *
  Disallow: /
  # The castle is your home now, so you can go anywhere you like.
  User-agent: Belle
  Disallow: /west-wing/ # except the west wing!
  # It's good to be the Prince...
  User-agent: Beast
  Disallow:

This file is missing the required blank lines between records. However, the intention is clear.

SEE ALSO

the LWP::RobotUA manpage, the WWW::RobotRules::AnyDBM_File manpage


WWW::RobotRules::AnyDBM_File - Persistent RobotRules

  • SEE ALSO
  • AUTHORS

NAME

WWW::RobotRules::AnyDBM_File - Persistent RobotRules

SYNOPSIS

 require WWW::RobotRules::AnyDBM_File;
 require LWP::RobotUA;

 # Create a robot useragent that uses a diskcaching RobotRules
 my $rules = new WWW::RobotRules::AnyDBM_File 'my-robot/1.0', 'cachefile';
 my $ua = new WWW::RobotUA 'my-robot/1.0', 'me@foo.com', $rules;

 # Then just use $ua as usual
 $res = $ua->request($req);

DESCRIPTION

This is a subclass of WWW::RobotRules that uses the AnyDBM_File package to implement persistent diskcaching of robots.txt and host visit information.

The constructor (the new() method) takes an extra argument specifying the name of the DBM file to use. If the DBM file already exists, then you can specify undef as agent name as the name can be obtained from the DBM database.

SEE ALSO

the WWW::RobotRules manpage, the LWP::RobotUA manpage

AUTHORS

Hakan Ardo <hakan@munin.ub2.lu.se>, Gisle Aas <aas@sn.no>


Win32 - Interfaces to some Win32 API Functions

    • Alphabetical Listing of Win32 Functions

NAME

Win32 - Interfaces to some Win32 API Functions

DESCRIPTION

Perl on Win32 contains several functions to access Win32 APIs. Some are included in Perl itself (on Win32) and some are only available after explicitly requesting the Win32 module with:

        use Win32;

The builtin functions are marked as [CORE] and the other ones as [EXT] in the following alphabetical listing.

Alphabetical Listing of Win32 Functions

Win32::AbortSystemShutdown(MACHINE)

[EXT] Aborts a system shutdown (started by the InitiateSystemShutdown function) on the specified MACHINE.

Win32::BuildNumber()

[CORE] Returns the ActivePerl build number. This function is only available in the ActivePerl binary distribution.

Win32::CopyFile(FROM, TO, OVERWRITE)

[CORE] The Win32::CopyFile() function copies an existing file to a new file. All file information like creation time and file attributes will be copied to the new file. However it will not copy the security information. If the destination file already exists it will only be overwritten when the OVERWRITE parameter is true. But even this will not overwrite a read-only file; you have to unlink() it first yourself.

Win32::DomainName()

[CORE] Returns the name of the Microsoft Network domain that the owner of the current perl process is logged into. This function does not work on Windows 9x.

Win32::ExpandEnvironmentStrings(STRING)

[EXT] Takes STRING and replaces all referenced environment variable names with their defined values. References to environment variables take the form %VariableName%. Case is ignored when looking up the VariableName in the environment. If the variable is not found then the original %VariableName% text is retained. Has the same effect as the following:

        $string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg

This function may return a Unicode string if the environment variable being expanded hasn't been assigned to via %ENV. Access to %ENV is currently always using byte semantics.

Win32::FormatMessage(ERRORCODE)

[CORE] Converts the supplied Win32 error number (e.g. returned by Win32::GetLastError()) to a descriptive string. Analogous to the perror() standard-C library function. Note that $^E used in a string context has much the same effect.

        C:\> perl -e "$^E = 26; print $^E;"
        The specified disk or diskette cannot be accessed
Win32::FsType()

[CORE] Returns the name of the filesystem of the currently active drive (like 'FAT' or 'NTFS'). In list context it returns three values: (FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as before. FLAGS is a combination of values of the following table:

        0x00000001  supports case-sensitive filenames
        0x00000002  preserves the case of filenames
        0x00000004  supports Unicode in filenames
        0x00000008  preserves and enforces ACLs
        0x00000010  supports file-based compression
        0x00000020  supports disk quotas
        0x00000040  supports sparse files
        0x00000080  supports reparse points
        0x00000100  supports remote storage
        0x00008000  is a compressed volume (e.g. DoubleSpace)
        0x00010000  supports object identifiers
        0x00020000  supports the Encrypted File System (EFS)

MAXCOMPLEN is the maximum length of a filename component (the part between two backslashes) on this file system.

Win32::FreeLibrary(HANDLE)

[EXT] Unloads a previously loaded dynamic-link library. The HANDLE is no longer valid after this call. See LoadLibrary for information on dynamically loading a library.

Win32::GetANSIPathName(FILENAME)

[EXT] Returns an ANSI version of FILENAME. This may be the short name if the long name cannot be represented in the system codepage.

While not currently implemented, it is possible that in the future this function will convert only parts of the path to FILENAME to a short form.

If FILENAME doesn't exist on the filesystem, or if the filesystem doesn't support short ANSI filenames, then this function will translate the Unicode name into the system codepage using replacement characters.

Win32::GetArchName()

[EXT] Use of this function is deprecated. It is equivalent with $ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X.

Win32::GetChipName()

[EXT] Returns the processor type: 386, 486 or 586 for Intel processors, 21064 for the Alpha chip.

Win32::GetCwd()

[CORE] Returns the current active drive and directory. This function does not return a UNC path, since the functionality required for such a feature is not available under Windows 95.

If supported by the core Perl version, this function will return an ANSI path name for the current directory if the long pathname cannot be represented in the system codepage.

Win32::GetFileVersion(FILENAME)

[EXT] Returns the file version number from the VERSIONINFO resource of the executable file or DLL. This is a tuple of four 16 bit numbers. In list context these four numbers will be returned. In scalar context they are concatenated into a string, separated by dots.

Win32::GetFolderPath(FOLDER [, CREATE])

[EXT] Returns the full pathname of one of the Windows special folders. The folder will be created if it doesn't exist and the optional CREATE argument is true. The following FOLDER constants are defined by the Win32 module, but only exported on demand:

        CSIDL_ADMINTOOLS
        CSIDL_APPDATA
        CSIDL_CDBURN_AREA
        CSIDL_COMMON_ADMINTOOLS
        CSIDL_COMMON_APPDATA
        CSIDL_COMMON_DESKTOPDIRECTORY
        CSIDL_COMMON_DOCUMENTS
        CSIDL_COMMON_FAVORITES
        CSIDL_COMMON_MUSIC
        CSIDL_COMMON_PICTURES
        CSIDL_COMMON_PROGRAMS
        CSIDL_COMMON_STARTMENU
        CSIDL_COMMON_STARTUP
        CSIDL_COMMON_TEMPLATES
        CSIDL_COMMON_VIDEO
        CSIDL_COOKIES
        CSIDL_DESKTOP
        CSIDL_DESKTOPDIRECTORY
        CSIDL_FAVORITES
        CSIDL_FONTS
        CSIDL_HISTORY
        CSIDL_INTERNET_CACHE
        CSIDL_LOCAL_APPDATA
        CSIDL_MYMUSIC
        CSIDL_MYPICTURES
        CSIDL_MYVIDEO
        CSIDL_NETHOOD
        CSIDL_PERSONAL
        CSIDL_PRINTHOOD
        CSIDL_PROFILE
        CSIDL_PROGRAMS
        CSIDL_PROGRAM_FILES
        CSIDL_PROGRAM_FILES_COMMON
        CSIDL_RECENT
        CSIDL_RESOURCES
        CSIDL_RESOURCES_LOCALIZED
        CSIDL_SENDTO
        CSIDL_STARTMENU
        CSIDL_STARTUP
        CSIDL_SYSTEM
        CSIDL_TEMPLATES
        CSIDL_WINDOWS

Note that not all folders are defined on all versions of Windows.

Please refer to the MSDN documentation of the CSIDL constants, currently available at:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp

This function will return an ANSI folder path if the long name cannot be represented in the system codepage. Use Win32::GetLongPathName() on the result of Win32::GetFolderPath() if you want the Unicode version of the folder name.

Win32::GetFullPathName(FILENAME)

[CORE] GetFullPathName combines the FILENAME with the current drive and directory name and returns a fully qualified (aka, absolute) path name. In list context it returns two elements: (PATH, FILE) where PATH is the complete pathname component (including trailing backslash) and FILE is just the filename part. Note that no attempt is made to convert 8.3 components in the supplied FILENAME to longnames or vice-versa. Compare with Win32::GetShortPathName() and Win32::GetLongPathName().

If supported by the core Perl version, this function will return an ANSI path name if the full pathname cannot be represented in the system codepage.

Win32::GetLastError()

[CORE] Returns the last error value generated by a call to a Win32 API function. Note that $^E used in a numeric context amounts to the same value.

Win32::GetLongPathName(PATHNAME)

[CORE] Returns a representation of PATHNAME composed of longname components (if any). The result may not necessarily be longer than PATHNAME. No attempt is made to convert PATHNAME to the absolute path. Compare with Win32::GetShortPathName() and Win32::GetFullPathName().

This function may return the pathname in Unicode if it cannot be represented in the system codepage. Use Win32::GetANSIPathName() before passing the path to a system call or another program.

Win32::GetNextAvailDrive()

[CORE] Returns a string in the form of "<d>:" where <d> is the first available drive letter.

Win32::GetOSVersion()

[CORE] Returns the list (STRING, MAJOR, MINOR, BUILD, ID), where the elements are, respectively: An arbitrary descriptive string, the major version number of the operating system, the minor version number, the build number, and a digit indicating the actual operating system. For the ID, the values are 0 for Win32s, 1 for Windows 9X/Me and 2 for Windows NT/2000/XP/2003. In scalar context it returns just the ID.

Currently known values for ID MAJOR and MINOR are as follows:

    OS                    ID    MAJOR   MINOR
    Win32s                 0      -       -
    Windows 95             1      4       0
    Windows 98             1      4      10
    Windows Me             1      4      90
    Windows NT 3.51        2      3      51
    Windows NT 4           2      4       0
    Windows 2000           2      5       0
    Windows XP             2      5       1
    Windows Server 2003    2      5       2
    Windows Vista          2      6       0

On Windows NT 4 SP6 and later this function returns the following additional values: SPMAJOR, SPMINOR, SUITEMASK, PRODUCTTYPE.

SPMAJOR and SPMINOR are are the version numbers of the latest installed service pack.

SUITEMASK is a bitfield identifying the product suites available on the system. Known bits are:

    VER_SUITE_SMALLBUSINESS             0x00000001
    VER_SUITE_ENTERPRISE                0x00000002
    VER_SUITE_BACKOFFICE                0x00000004
    VER_SUITE_COMMUNICATIONS            0x00000008
    VER_SUITE_TERMINAL                  0x00000010
    VER_SUITE_SMALLBUSINESS_RESTRICTED  0x00000020
    VER_SUITE_EMBEDDEDNT                0x00000040
    VER_SUITE_DATACENTER                0x00000080
    VER_SUITE_SINGLEUSERTS              0x00000100
    VER_SUITE_PERSONAL                  0x00000200
    VER_SUITE_BLADE                     0x00000400
    VER_SUITE_EMBEDDED_RESTRICTED       0x00000800
    VER_SUITE_SECURITY_APPLIANCE        0x00001000

The VER_SUITE_xxx names are listed here to crossreference the Microsoft documentation. The Win32 module does not provide symbolic names for these constants.

PRODUCTTYPE provides additional information about the system. It should be one of the following integer values:

    1 - Workstation (NT 4, 2000 Pro, XP Home, XP Pro)
    2 - Domaincontroller
    3 - Server
Win32::GetOSName()

[EXT] In scalar context returns the name of the Win32 operating system being used. In list context returns a two element list of the OS name and whatever edition information is known about the particular build (for Win9X boxes) and whatever service packs have been installed. The latter is roughly equivalent to the first item returned by GetOSVersion() in list context.

Currently the possible values for the OS name are

 Win32s Win95 Win98 WinMe WinNT3.51 WinNT4 Win2000 WinXP/.Net Win2003

This routine is just a simple interface into GetOSVersion(). More specific or demanding situations should use that instead. Another option would be to use POSIX::uname(), however the latter appears to report only the OS family name and not the specific OS. In scalar context it returns just the ID.

The name "WinXP/.Net" is used for historical reasons only, to maintain backwards compatibility of the Win32 module. Windows .NET Server has been renamed as Windows 2003 Server before final release and uses a different major/minor version number than Windows XP.

Win32::GetShortPathName(PATHNAME)

[CORE] Returns a representation of PATHNAME that is composed of short (8.3) path components where available. For path components where the file system has not generated the short form the returned path will use the long form, so this function might still for instance return a path containing spaces. Compare with Win32::GetFullPathName() and Win32::GetLongPathName().

Win32::GetProcAddress(INSTANCE, PROCNAME)

[EXT] Returns the address of a function inside a loaded library. The information about what you can do with this address has been lost in the mist of time. Use the Win32::API module instead of this deprecated function.

Win32::GetTickCount()

[CORE] Returns the number of milliseconds elapsed since the last system boot. Resolution is limited to system timer ticks (about 10ms on WinNT and 55ms on Win9X).

Win32::GuidGen()

[EXT] Creates a globally unique 128 bit integer that can be used as a persistent identifier in a distributed setting. To a very high degree of certainty this function returns a unique value. No other invocation, on the same or any other system (networked or not), should return the same value.

The return value is formatted according to OLE conventions, as groups of hex digits with surrounding braces. For example:

    {09531CF1-D0C7-4860-840C-1C8C8735E2AD}

    =item Win32::InitiateSystemShutdown

(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)

[EXT] Shutsdown the specified MACHINE, notifying users with the supplied MESSAGE, within the specified TIMEOUT interval. Forces closing of all documents without prompting the user if FORCECLOSE is true, and reboots the machine if REBOOT is true. This function works only on WinNT.

Win32::IsAdminUser()

[EXT] Returns non zero if the account in whose security context the current process/thread is running belongs to the local group of Administrators in the built-in system domain; returns 0 if not. On Windows Vista it will only return non-zero if the process is actually running with elevated privileges. Returns the undefined value and prints a warning if an error occurred. This function always returns 1 on Win9X.

Win32::IsWinNT()

[CORE] Returns non zero if the Win32 subsystem is Windows NT.

Win32::IsWin95()

[CORE] Returns non zero if the Win32 subsystem is Windows 95.

Win32::LoadLibrary(LIBNAME)

[EXT] Loads a dynamic link library into memory and returns its module handle. This handle can be used with Win32::GetProcAddress() and Win32::FreeLibrary(). This function is deprecated. Use the Win32::API module instead.

Win32::LoginName()

[CORE] Returns the username of the owner of the current perl process. The return value may be a Unicode string.

Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)

[EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and the SID type.

Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)

[EXT] Looks up SID on SYSTEM and returns the account name, domain name, and the SID type.

Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])

[EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the required icon and buttons according to the following table:

        0 = OK
        1 = OK and Cancel
        2 = Abort, Retry, and Ignore
        3 = Yes, No and Cancel
        4 = Yes and No
        5 = Retry and Cancel
        MB_ICONSTOP          "X" in a red circle
        MB_ICONQUESTION      question mark in a bubble
        MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
        MB_ICONINFORMATION   "i" in a bubble

TITLE specifies an optional window title. The default is "Perl".

The function returns the menu id of the selected push button:

        0  Error
        1  OK
        2  Cancel
        3  Abort
        4  Retry
        5  Ignore
        6  Yes
        7  No
Win32::NodeName()

[CORE] Returns the Microsoft Network node-name of the current machine.

Win32::RegisterServer(LIBRARYNAME)

[EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.

Win32::SetChildShowWindow(SHOWWINDOW)

[CORE] Sets the ShowMode of child processes started by system(). By default system() will create a new console window for child processes if Perl itself is not running from a console. Calling SetChildShowWindow(0) will make these new console windows invisible. Calling SetChildShowWindow() without arguments reverts system() to the default behavior. The return value of SetChildShowWindow() is the previous setting or undef.

[EXT] The following symbolic constants for SHOWWINDOW are available (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL, SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE.

Win32::SetCwd(NEWDIRECTORY)

[CORE] Sets the current active drive and directory. This function does not work with UNC paths, since the functionality required to required for such a feature is not available under Windows 95.

Win32::SetLastError(ERROR)

[CORE] Sets the value of the last error encountered to ERROR. This is that value that will be returned by the Win32::GetLastError() function.

Win32::Sleep(TIME)

[CORE] Pauses for TIME milliseconds. The timeslices are made available to other processes and threads.

Win32::Spawn(COMMAND, ARGS, PID)

[CORE] Spawns a new process using the supplied COMMAND, passing in arguments in the string ARGS. The pid of the new process is stored in PID. This function is deprecated. Please use the Win32::Process module instead.

Win32::UnregisterServer(LIBRARYNAME)

[EXT] Loads the DLL LIBRARYNAME and calls the function DllUnregisterServer.


Win32::AuthenticateUser - Win32 User authentication for domains

  • SUPPORTED PLATFORMS
  • SYNOPSIS
  • DESCRIPTION
  • STATUS
  • AUTHOR

NAME

Win32::AuthenticateUser - Win32 User authentication for domains

SUPPORTED PLATFORMS

none

SYNOPSIS

  use Win32::AuthenticateUser;

  AuthenticateUser("domain", "user", "passwd");

DESCRIPTION

Performs Win32 user authentication using domains

STATUS

This module is incomplete and is not being actively developed. No documentation exists (yet), and there may be bugs in the code.

AUTHOR

Murray Nesbitt, ActiveState Tool Corp.


Win32::ChangeNotify - Monitor events related to files and directories

    • Methods
    • Deprecated Functions and Methods
  • AUTHOR

NAME

Win32::ChangeNotify - Monitor events related to files and directories

SYNOPSIS

        require Win32::ChangeNotify;

        $notify = Win32::ChangeNotify->new($Path,$WatchSubTree,$Events);
        $notify->wait or warn "Something failed: $!\n";
        # There has been a change.

DESCRIPTION

This module allows the user to use a Win32 change notification event object from Perl. This allows the Perl program to monitor events relating to files and directory trees.

Unfortunately, the Win32 API which implements this feature does not provide any indication of what triggered the notification (as far as I know). If you're monitoring a directory for file changes, and you need to know which file changed, you'll have to find some other way of determining that. Depending on exactly what you're trying to do, you may be able to check file timestamps to find recently changed files. Or, you may need to cache the directory contents somewhere and compare the current contents to your cached copy when you receive a change notification.

The wait method and wait_all & wait_any functions are inherited from the Win32::IPC module.

Methods

$notify = Win32::ChangeNotify->new($path, $subtree, $filter)

Constructor for a new ChangeNotification object. $path is the directory to monitor. If $subtree is true, then all directories under $path will be monitored. $filter indicates what events should trigger a notification. It should be a string containing any of the following flags (separated by whitespace and/or |).

   ATTRIBUTES   Any attribute change
   DIR_NAME     Any directory name change
   FILE_NAME    Any file name change (creating/deleting/renaming)
   LAST_WRITE   Any change to a file's last write time
   SECURITY     Any security descriptor change
   SIZE         Any change in a file's size

($filter can also be an integer composed from the FILE_NOTIFY_CHANGE_* constants.)

$notify->close

Shut down monitoring. You could just undef $notify instead (but close works even if there are other copies of the object). This happens automatically when your program exits.

$notify->reset

Resets the ChangeNotification object after a change has been detected. The object will become signalled again after the next change. (It is OK to call this immediately after new, but it is not required.)

$notify->wait

See Win32::IPC. Remember to call reset afterwards if you want to continue monitoring.

Deprecated Functions and Methods

Win32::ChangeNotify still supports the ActiveWare syntax, but its use is deprecated.

FindFirst($Obj,$PathName,$WatchSubTree,$Filter)

Use

  $Obj = Win32::ChangeNotify->new($PathName,$WatchSubTree,$Filter)

instead.

$obj->FindNext()

Use $obj->reset instead.

$obj->Close()

Use $obj->close instead.

AUTHOR

Christopher J. Madsen <cjm@pobox.com>

Loosely based on the original module by ActiveWare Internet Corp., http://www.ActiveWare.com


Win32::Clipboard - Interaction with the Windows clipboard

    • REFERENCE
    • CONSTANTS
  • AUTHOR

NAME

Win32::Clipboard - Interaction with the Windows clipboard

SYNOPSIS

    use Win32::Clipboard;

    $CLIP = Win32::Clipboard();

    print "Clipboard contains: ", $CLIP->Get(), "\n";

    $CLIP->Set("some text to copy into the clipboard");

    $CLIP->Empty();

    $CLIP->WaitForChange();
    print "Clipboard has changed!\n";

DESCRIPTION

This module lets you interact with the Windows clipboard: you can get its content, set it, empty it, or let your script sleep until it changes. This version supports 3 formats for clipboard data:

  • text (CF_TEXT)

    The clipboard contains some text; this is the only format you can use to set clipboard data; you get it as a single string.

    Example:

        $text = Win32::Clipboard::GetText();
    print $text;
  • bitmap (CF_DIB)

    The clipboard contains an image, either a bitmap or a picture copied in the clipboard from a graphic application. The data you get is a binary buffer ready to be written to a bitmap (BMP format) file.

    Example:

        $image = Win32::Clipboard::GetBitmap();
    open    BITMAP, ">some.bmp";
    binmode BITMAP;
    print   BITMAP $image;
    close   BITMAP;
  • list of files (CF_HDROP)

    The clipboard contains files copied or cutted from an Explorer-like application; you get a list of filenames.

    Example:

        @files = Win32::Clipboard::GetFiles();
    print join("\n", @files);

REFERENCE

All the functions can be used either with their full name (eg. Win32::Clipboard::Get) or as methods of a Win32::Clipboard object. For the syntax, refer to SYNOPSIS above. Note also that you can create a clipboard object and set its content at the same time with:

    $CLIP = Win32::Clipboard("blah blah blah");

or with the more common form:

    $CLIP = new Win32::Clipboard("blah blah blah");

If you prefer, you can even tie the Clipboard to a variable like this:

        tie $CLIP, 'Win32::Clipboard';

        print "Clipboard content: $CLIP\n";

        $CLIP = "some text to copy to the clipboard...";

In this case, you can still access other methods using the tied() function:

        tied($CLIP)->Empty;
        print "got the picture" if tied($CLIP)->IsBitmap;
Empty()

Empty the clipboard.

EnumFormats()

Returns an array of identifiers describing the format for the data currently in the clipboard. Formats can be standard ones (described in the CONSTANTS section) or application-defined custom ones. See also IsFormatAvailable().

Get()

Returns the clipboard content; note that the result depends on the nature of clipboard data; to ensure that you get only the desired format, you should use GetText(), GetBitmap() or GetFiles() instead. Get() is in fact implemented as:

        if(    IsBitmap() ) { return GetBitmap(); }
        elsif( IsFiles()  ) { return GetFiles();  }
        else                { return GetText();   }

See also IsBitmap(), IsFiles(), IsText(), EnumFormats() and IsFormatAvailable() to check the clipboard format before getting data.

GetAs(FORMAT)

Returns the clipboard content in the desired FORMAT (can be one of the constants defined in the CONSTANTS section or a custom format). Note that the only meaningful identifiers are CF_TEXT, CF_DIB and CF_HDROP; any other format is treated as a string.

GetBitmap()

Returns the clipboard content as an image, or undef on errors.

GetFiles()

Returns the clipboard content as a list of filenames, or undef on errors.

GetFormatName(FORMAT)

Returns the name of the specified custom clipboard format, or undef on errors; note that you cannot get the name of the standard formats (described in the CONSTANTS section).

GetText()

Returns the clipboard content as a string, or undef on errors.

IsBitmap()

Returns a boolean value indicating if the clipboard contains an image. See also GetBitmap().

IsFiles()

Returns a boolean value indicating if the clipboard contains a list of files. See also GetFiles().

IsFormatAvailable(FORMAT)

Checks if the clipboard data matches the specified FORMAT (one of the constants described in the CONSTANTS section); returns zero if the data does not match, a nonzero value if it matches.

IsText()

Returns a boolean value indicating if the clipboard contains text. See also GetText().

Set(VALUE)

Set the clipboard content to the specified string.

WaitForChange([TIMEOUT])

This function halts the script until the clipboard content changes. If you specify a TIMEOUT value (in milliseconds), the function will return when this timeout expires, even if the clipboard hasn't changed. If no value is given, it will wait indefinitely. Returns 1 if the clipboard has changed, undef on errors.

CONSTANTS

These constants are the standard clipboard formats recognized by Win32::Clipboard:

        CF_TEXT             1
        CF_DIB              8
        CF_HDROP            15

The following formats are not recognized by Win32::Clipboard; they are, however, exported constants and can eventually be used with the EnumFormats(), IsFormatAvailable() and GetAs() functions:

        CF_BITMAP           2
        CF_METAFILEPICT     3
        CF_SYLK             4
        CF_DIF              5
        CF_TIFF             6
        CF_OEMTEXT          7
        CF_PALETTE          9
        CF_PENDATA          10
        CF_RIFF             11
        CF_WAVE             12
        CF_UNICODETEXT      13
        CF_ENHMETAFILE      14
        CF_LOCALE           16

AUTHOR

This version was released by Hideyo Imazu <himazu@gmail.com>.

Aldo Calpini <dada@perl.it> was the former maintainer.

Original XS porting by Gurusamy Sarathy <gsar@activestate.com>.


Win32::Console - Win32 Console and Character Mode Functions

  • REFERENCE
    • Methods
    • Constants
    • Microsoft's Documentation
  • AUTHOR
  • CREDITS
  • DISCLAIMER

NAME

Win32::Console - Win32 Console and Character Mode Functions

DESCRIPTION

This module implements the Win32 console and character mode functions. They give you full control on the console input and output, including: support of off-screen console buffers (eg. multiple screen pages)

  • reading and writing of characters, attributes and whole portions of the screen

  • complete processing of keyboard and mouse events

  • some very funny additional features :)

Those functions should also make possible a port of the Unix's curses library; if there is anyone interested (and/or willing to contribute) to this project, e-mail me. Thank you.

REFERENCE

Methods

Alloc

Allocates a new console for the process. Returns undef on errors, a nonzero value on success. A process cannot be associated with more than one console, so this method will fail if there is already an allocated console. Use Free to detach the process from the console, and then call Alloc to create a new console. See also: Free

Example:

    $CONSOLE->Alloc();
Attr [attr]

Gets or sets the current console attribute. This attribute is used by the Write method.

Example:

    $attr = $CONSOLE->Attr();
    $CONSOLE->Attr($FG_YELLOW | $BG_BLUE);
Close

Closes a shortcut object. Note that it is not "strictly" required to close the objects you created, since the Win32::Shortcut objects are automatically closed when the program ends (or when you elsehow destroy such an object).

Example:

    $LINK->Close();
Cls [attr]

Clear the console, with the specified attr if given, or using ATTR_NORMAL otherwise.

Example:

    $CONSOLE->Cls();
    $CONSOLE->Cls($FG_WHITE | $BG_GREEN);
Cursor [x, y, size, visible]

Gets or sets cursor position and appearance. Returns undef on errors, or a 4-element list containing: x, y, size, visible. x and y are the current cursor position; ...

Example:

    ($x, $y, $size, $visible) = $CONSOLE->Cursor();

    # Get position only
    ($x, $y) = $CONSOLE->Cursor();

    $CONSOLE->Cursor(40, 13, 50, 1);

    # Set position only
    $CONSOLE->Cursor(40, 13);

    # Set size and visibility without affecting position
    $CONSOLE->Cursor(-1, -1, 50, 1);
Display

Displays the specified console on the screen. Returns undef on errors, a nonzero value on success.

Example:

    $CONSOLE->Display();
FillAttr [attribute, number, col, row]

Fills the specified number of consecutive attributes, beginning at col, row, with the value specified in attribute. Returns the number of attributes filled, or undef on errors. See also: FillChar.

Example:

    $CONSOLE->FillAttr($FG_BLACK | $BG_BLACK, 80*25, 0, 0);
FillChar char, number, col, row

Fills the specified number of consecutive characters, beginning at col, row, with the character specified in char. Returns the number of characters filled, or undef on errors. See also: FillAttr.

Example:

    $CONSOLE->FillChar("X", 80*25, 0, 0);
Flush

Flushes the console input buffer. All the events in the buffer are discarded. Returns undef on errors, a nonzero value on success.

Example:

    $CONSOLE->Flush();
Free

Detaches the process from the console. Returns undef on errors, a nonzero value on success. See also: Alloc.

Example:

    $CONSOLE->Free();
GenerateCtrlEvent [type, processgroup]

Sends a break signal of the specified type to the specified processgroup. type can be one of the following constants:

    CTRL_BREAK_EVENT
    CTRL_C_EVENT

they signal, respectively, the pressing of Control + Break and of Control + C; if not specified, it defaults to CTRL_C_EVENT. processgroup is the pid of a process sharing the same console. If omitted, it defaults to 0 (the current process), which is also the only meaningful value that you can pass to this function. Returns undef on errors, a nonzero value on success.

Example:

    # break this script now
    $CONSOLE->GenerateCtrlEvent();
GetEvents

Returns the number of unread input events in the console's input buffer, or undef on errors. See also: Input, InputChar, PeekInput, WriteInput.

Example:

    $events = $CONSOLE->GetEvents();
Info

Returns an array of informations about the console (or undef on errors), which contains:

  • columns (X size) of the console buffer.

  • rows (Y size) of the console buffer.

  • current column (X position) of the cursor.

  • current row (Y position) of the cursor.

  • current attribute used for Write.

  • left column (X of the starting point) of the current console window.

  • top row (Y of the starting point) of the current console window.

  • right column (X of the final point) of the current console window.

  • bottom row (Y of the final point) of the current console window.

  • maximum number of columns for the console window, given the current buffer size, font and the screen size.

  • maximum number of rows for the console window, given the current buffer size, font and the screen size.

See also: Attr, Cursor, Size, Window, MaxWindow.

Example:

    @info = $CONSOLE->Info();
    print "Cursor at $info[3], $info[4].\n";
Input

Reads an event from the input buffer. Returns a list of values, which depending on the event's nature are:

keyboard event

The list will contain:

  • event type: 1 for keyboard

  • key down: TRUE if the key is being pressed, FALSE if the key is being released

  • repeat count: the number of times the key is being held down

  • virtual keycode: the virtual key code of the key

  • virtual scancode: the virtual scan code of the key

  • char: the ASCII code of the character (if the key is a character key, 0 otherwise)

  • control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)

mouse event

The list will contain:

  • event type: 2 for mouse

  • mouse pos. X: X coordinate (column) of the mouse location

  • mouse pos. Y: Y coordinate (row) of the mouse location

  • button state: the mouse button(s) which are pressed

  • control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)

  • event flags: the type of the mouse event

This method will return undef on errors. Note that the events returned are depending on the input Mode of the console; for example, mouse events are not intercepted unless ENABLE_MOUSE_INPUT is specified. See also: GetEvents, InputChar, Mode, PeekInput, WriteInput.

Example:

    @event = $CONSOLE->Input();
InputChar number

Reads and returns number characters from the console input buffer, or undef on errors. See also: Input, Mode.

Example:

    $key = $CONSOLE->InputChar(1);
InputCP [codepage]

Gets or sets the input code page used by the console. Note that this doesn't apply to a console object, but to the standard input console. This attribute is used by the Write method. See also: OutputCP.

Example:

    $codepage = $CONSOLE->InputCP();
    $CONSOLE->InputCP(437);

    # you may want to use the non-instanciated form to avoid confuzion :)
    $codepage = Win32::Console::InputCP();
    Win32::Console::InputCP(437);
MaxWindow

Returns the size of the largest possible console window, based on the current font and the size of the display. The result is undef on errors, otherwise a 2-element list containing col, row.

Example:

    ($maxCol, $maxRow) = $CONSOLE->MaxWindow();
Mode [flags]

Gets or sets the input or output mode of a console. flags can be a combination of the following constants:

    ENABLE_LINE_INPUT
    ENABLE_ECHO_INPUT
    ENABLE_PROCESSED_INPUT
    ENABLE_WINDOW_INPUT
    ENABLE_MOUSE_INPUT
    ENABLE_PROCESSED_OUTPUT
    ENABLE_WRAP_AT_EOL_OUTPUT

For more informations on the meaning of those flags, please refer to the Microsoft's Documentation.

Example:

    $mode = $CONSOLE->Mode();
    $CONSOLE->Mode(ENABLE_MOUSE_INPUT | ENABLE_PROCESSED_INPUT);
MouseButtons

Returns the number of the buttons on your mouse, or undef on errors.

Example:

    print "Your mouse has ", $CONSOLE->MouseButtons(), " buttons.\n";
new Win32::Console standard_handle
new Win32::Console [accessmode, sharemode]

Creates a new console object. The first form creates a handle to a standard channel, standard_handle can be one of the following:

    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE
    STD_INPUT_HANDLE

The second form, instead, creates a console screen buffer in memory, which you can access for reading and writing as a normal console, and then redirect on the standard output (the screen) with Display. In this case, you can specify one or both of the following values for accessmode:

    GENERIC_READ
    GENERIC_WRITE

which are the permissions you will have on the created buffer, and one or both of the following values for sharemode:

    FILE_SHARE_READ
    FILE_SHARE_WRITE

which affect the way the console can be shared. If you don't specify any of those parameters, all 4 flags will be used.

Example:

    $STDOUT = new Win32::Console(STD_OUTPUT_HANDLE);
    $STDERR = new Win32::Console(STD_ERROR_HANDLE);
    $STDIN  = new Win32::Console(STD_INPUT_HANDLE);

    $BUFFER = new Win32::Console();
    $BUFFER = new Win32::Console(GENERIC_READ | GENERIC_WRITE);
OutputCP [codepage]

Gets or sets the output code page used by the console. Note that this doesn't apply to a console object, but to the standard output console. See also: InputCP.

Example:

    $codepage = $CONSOLE->OutputCP();
    $CONSOLE->OutputCP(437);

    # you may want to use the non-instanciated form to avoid confuzion :)
    $codepage = Win32::Console::OutputCP();
    Win32::Console::OutputCP(437);
PeekInput

Does exactly the same as Input, except that the event read is not removed from the input buffer. See also: GetEvents, Input, InputChar, Mode, WriteInput.

Example:

    @event = $CONSOLE->PeekInput();
ReadAttr [number, col, row]

Reads the specified number of consecutive attributes, beginning at col, row, from the console. Returns the attributes read (a variable containing one character for each attribute), or undef on errors. You can then pass the returned variable to WriteAttr to restore the saved attributes on screen. See also: ReadChar, ReadRect.

Example:

    $colors = $CONSOLE->ReadAttr(80*25, 0, 0);
ReadChar [number, col, row]

Reads the specified number of consecutive characters, beginning at col, row, from the console. Returns a string containing the characters read, or undef on errors. You can then pass the returned variable to WriteChar to restore the saved characters on screen. See also: ReadAttr, ReadRect.

Example:

    $chars = $CONSOLE->ReadChar(80*25, 0, 0);
ReadRect left, top, right, bottom

Reads the content (characters and attributes) of the rectangle specified by left, top, right, bottom from the console. Returns a string containing the rectangle read, or undef on errors. You can then pass the returned variable to WriteRect to restore the saved rectangle on screen (or on another console). See also: ReadAttr, ReadChar.

Example:

     $rect = $CONSOLE->ReadRect(0, 0, 80, 25);
Scroll left, top, right, bottom, col, row, char, attr, [cleft, ctop, cright, cbottom]

Moves a block of data in a console buffer; the block is identified by left, top, right, bottom, while row, col identify the new location of the block. The cells left empty as a result of the move are filled with the character char and attribute attr. Optionally you can specify a clipping region with cleft, ctop, cright, cbottom, so that the content of the console outside this rectangle are unchanged. Returns undef on errors, a nonzero value on success.

Example:

    # scrolls the screen 10 lines down, filling with black spaces
    $CONSOLE->Scroll(0, 0, 80, 25, 0, 10, " ", $FG_BLACK | $BG_BLACK);
Select standard_handle

Redirects a standard handle to the specified console. standard_handle can have one of the following values:

    STD_INPUT_HANDLE
    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE

Returns undef on errors, a nonzero value on success.

Example:

    $CONSOLE->Select(STD_OUTPUT_HANDLE);
SetIcon icon_file

Sets the icon in the title bar of the current console window.

Example:

    $CONSOLE->SetIcon("C:/My/Path/To/Custom.ico");
Size [col, row]

Gets or sets the console buffer size.

Example:

    ($x, $y) = $CONSOLE->Size();
    $CONSOLE->Size(80, 25);
Title [title]

Gets or sets the title of the current console window.

Example:

    $title = $CONSOLE->Title();
    $CONSOLE->Title("This is a title");
Window [flag, left, top, right, bottom]

Gets or sets the current console window size. If called without arguments, returns a 4-element list containing the current window coordinates in the form of left, top, right, bottom. To set the window size, you have to specify an additional flag parameter: if it is 0 (zero), coordinates are considered relative to the current coordinates; if it is non-zero, coordinates are absolute.

Example:

    ($left, $top, $right, $bottom) = $CONSOLE->Window();
    $CONSOLE->Window(1, 0, 0, 80, 50);
Write string

Writes string on the console, using the current attribute, that you can set with Attr, and advancing the cursor as needed. This isn't so different from Perl's "print" statement. Returns the number of characters written or undef on errors. See also: WriteAttr, WriteChar, WriteRect.

Example:

    $CONSOLE->Write("Hello, world!");
WriteAttr attrs, col, row

Writes the attributes in the string attrs, beginning at col, row, without affecting the characters that are on screen. The string attrs can be the result of a ReadAttr function, or you can build your own attribute string; in this case, keep in mind that every attribute is treated as a character, not a number (see example). Returns the number of attributes written or undef on errors. See also: Write, WriteChar, WriteRect.

Example:

    $CONSOLE->WriteAttr($attrs, 0, 0);

    # note the use of chr()...
    $attrs = chr($FG_BLACK | $BG_WHITE) x 80;
    $CONSOLE->WriteAttr($attrs, 0, 0);
WriteChar chars, col, row

Writes the characters in the string attr, beginning at col, row, without affecting the attributes that are on screen. The string chars can be the result of a ReadChar function, or a normal string. Returns the number of characters written or undef on errors. See also: Write, WriteAttr, WriteRect.

Example:

    $CONSOLE->WriteChar("Hello, worlds!", 0, 0);
WriteInput (event)

Pushes data in the console input buffer. (event) is a list of values, for more information see Input. The string chars can be the result of a ReadChar function, or a normal string. Returns the number of characters written or undef on errors. See also: Write, WriteAttr, WriteRect.

Example:

    $CONSOLE->WriteInput(@event);
WriteRect rect, left, top, right, bottom

Writes a rectangle of characters and attributes (contained in rect) on the console at the coordinates specified by left, top, right, bottom. rect can be the result of a ReadRect function. Returns undef on errors, otherwise a 4-element list containing the coordinates of the affected rectangle, in the format left, top, right, bottom. See also: Write, WriteAttr, WriteChar.

Example:

    $CONSOLE->WriteRect($rect, 0, 0, 80, 25);

Constants

The following constants are exported in the main namespace of your script using Win32::Console:

    BACKGROUND_BLUE
    BACKGROUND_GREEN
    BACKGROUND_INTENSITY
    BACKGROUND_RED
    CAPSLOCK_ON
    CONSOLE_TEXTMODE_BUFFER
    ENABLE_ECHO_INPUT
    ENABLE_LINE_INPUT
    ENABLE_MOUSE_INPUT
    ENABLE_PROCESSED_INPUT
    ENABLE_PROCESSED_OUTPUT
    ENABLE_WINDOW_INPUT
    ENABLE_WRAP_AT_EOL_OUTPUT
    ENHANCED_KEY
    FILE_SHARE_READ
    FILE_SHARE_WRITE
    FOREGROUND_BLUE
    FOREGROUND_GREEN
    FOREGROUND_INTENSITY
    FOREGROUND_RED
    LEFT_ALT_PRESSED
    LEFT_CTRL_PRESSED
    NUMLOCK_ON
    GENERIC_READ
    GENERIC_WRITE
    RIGHT_ALT_PRESSED
    RIGHT_CTRL_PRESSED
    SCROLLLOCK_ON
    SHIFT_PRESSED
    STD_INPUT_HANDLE
    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE

Additionally, the following variables can be used:

    $FG_BLACK
    $FG_GRAY
    $FG_BLUE
    $FG_LIGHTBLUE
    $FG_RED
    $FG_LIGHTRED
    $FG_GREEN
    $FG_LIGHTGREEN
    $FG_MAGENTA
    $FG_LIGHTMAGENTA
    $FG_CYAN
    $FG_LIGHTCYAN
    $FG_BROWN
    $FG_YELLOW
    $FG_LIGHTGRAY
    $FG_WHITE
    $BG_BLACK
    $BG_GRAY
    $BG_BLUE
    $BG_LIGHTBLUE
    $BG_RED
    $BG_LIGHTRED
    $BG_GREEN
    $BG_LIGHTGREEN
    $BG_MAGENTA
    $BG_LIGHTMAGENTA
    $BG_CYAN
    $BG_LIGHTCYAN
    $BG_BROWN
    $BG_YELLOW
    $BG_LIGHTGRAY
    $BG_WHITE
    $ATTR_NORMAL
    $ATTR_INVERSE

ATTR_NORMAL is set to gray foreground on black background (DOS's standard colors).

Microsoft's Documentation

Documentation for the Win32 Console and Character mode Functions can be found on Microsoft's site at this URL:

http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar.htm

A reference of the available functions is at:

http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar_34.htm

AUTHOR

Aldo Calpini <a.calpini@romagiubileo.it>

CREDITS

Thanks to: Jesse Dougherty, Dave Roth, ActiveWare, and the Perl-Win32-Users community.

DISCLAIMER

This program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsibility for any damage, loss of money and/or health that may arise from the use of this program!

This is distributed under the terms of Larry Wall's Artistic License.


Win32::Console::ANSI - Perl extension to emulate ANSI console on Win32 system.

    • Escape sequences for Cursor Movement
    • Escape sequences for Display Edition
    • Escape sequences for Set Graphics Rendition
    • Escape sequences for Select Character Set
  • AUXILIARY FUNCTIONS
  • LIMITATIONS
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Win32::Console::ANSI - Perl extension to emulate ANSI console on Win32 system.

SYNOPSIS

  use Win32::Console::ANSI;

  print "\e[1;34mThis text is bold blue.\e[0m\n";
  print "This text is normal.\n";
  print "\e[33;45;1mBold yellow on magenta.\e[0m\n";
  print "This text is normal.\n";

With the Term::ANSIColor module one increases the readability:

  use Win32::Console::ANSI;
  use Term::ANSIColor;

  print color 'bold blue';
  print "This text is bold blue.\n";
  print color 'reset';
  print "This text is normal.\n";
  print colored ("Bold yellow on magenta.\n", 'bold yellow on_magenta');
  print "This text is normal.\n";

And even more with Term::ANSIScreen:

  use Win32::Console::ANSI;
  use Term::ANSIScreen qw/:color :cursor :screen/;

  locate 1, 1; print "@ This is (1,1)", savepos;
  print locate(24,60), "@ This is (24,60)"; loadpos;
  print down(2), clline, "@ This is (3,16)\n";
  color 'black on white'; clline;
  print "This line is black on white.\n";
  print color 'reset'; print "This text is normal.\n";
  print colored ("This text is bold blue.\n", 'bold blue');
  print "This text is normal.\n";
  print colored ['bold blue'], "This text is bold blue.\n";
  print "This text is normal.\n";

DESCRIPTION

Windows NT/2000/XP does not support ANSI escape sequences in Win32 Console applications. This module emulates an ANSI console for the script that uses it and also converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM conversion). This conversion permits the display of the accented characters in the console like in the Windows- based editor used to type the script.

Escape sequences for Cursor Movement

  • \e[#A

    CUU: CUrsor Up: Moves the cursor up by the specified number of lines without changing columns. If the cursor is already on the top line, this sequence is ignored. \e[A is equivalent to \e[1A.

  • \e[#B

    CUD: CUrsor Down: Moves the cursor down by the specified number of lines without changing columns. If the cursor is already on the bottom line, this sequence is ignored. \e[B is equivalent to \e[1B.

  • \e[#C

    CUF: CUrsor Forward: Moves the cursor forward by the specified number of columns without changing lines. If the cursor is already in the rightmost column, this sequence is ignored. \e[C is equivalent to \e[1C.

  • \e[#D

    CUB: CUrsor Backward: Moves the cursor back by the specified number of columns without changing lines. If the cursor is already in the leftmost column, this sequence is ignored. \e[D is equivalent to \e[1D.

  • \e[#E

    CNL: Cursor Next Line: Moves the cursor down the indicated # of rows, to column 1. \e[E is equivalent to \e[1E.

  • \e[#F

    CPL: Cursor Preceding Line: Moves the cursor up the indicated # of rows, to column 1. \e[F is equivalent to \e[1F.

  • \e[#G

    CHA: Cursor Horizontal Absolute: Moves the cursor to indicated column in current row. \e[G is equivalent to \e[1G.

  • \e[#;#H

    CUP: CUrsor Position: Moves the cursor to the specified position. The first # specifies the line number, the second # specifies the column. If you do not specify a position, the cursor moves to the home position: the upper-left corner of the screen (line 1, column 1).

  • \e[#;#f

    HVP: Horizontal and Vertical Position. Works in the same way as the preceding escape sequence.

  • \e[s

    SCP: Save Cursor Position: Saves the current cursor position. You can move the cursor to the saved cursor position by using the Restore Cursor Position sequence.

  • \e[u

    RCP: Restore Cursor Position: Returns the cursor to the position stored by the Save Cursor Position sequence.

Escape sequences for Display Edition

  • \e[#J

    ED: Erase Display:

    • \e[0J

      Clears the screen from cursor to end of display. The cursor position is unchanged.

    • \e[1J

      Clears the screen from start to cursor. The cursor position is unchanged.

    • \e[2J

      Clears the screen and moves the cursor to the home position (line 1, column 1).

    \e[J is equivalent to \e[0J. (Some terminal/emulators respond to \e[J as if it were \e[2J. Here, the default is 0; it's the norm)

  • \e[#K

    EL: Erase Line:

    • \e[0K

      Clears all characters from the cursor position to the end of the line (including the character at the cursor position). The cursor position is unchanged.

    • \e[1K

      Clears all characters from start of line to the cursor position. (including the character at the cursor position). The cursor position is unchanged.

    • \e[2K

      Clears all characters of the whole line. The cursor position is unchanged.

    \e[K is equivalent to \e[0K. (Some terminal/emulators respond to \e[K as if it were \e[2K. Here, the default is 0; it's the norm)

  • \e[#L

    IL: Insert Lines: The cursor line and all lines below it move down # lines, leaving blank space. The cursor position is unchanged. The bottommost # lines are lost. \e[L is equivalent to \e[1L.

  • \e[#M

    DL: Delete Line: The block of # lines at and below the cursor are deleted; all lines below them move up # lines to fill in the gap, leaving # blank lines at the bottom of the screen. The cursor position is unchanged. \e[M is equivalent to \e[1M.

  • \e[#\@

    ICH: Insert CHaracter: The cursor character and all characters to the right of it move right # columns, leaving behind blank space. The cursor position is unchanged. The rightmost # characters on the line are lost. \e[\@ is equivalent to \e[1\@.

  • \e[#P

    DCH: Delete CHaracter: The block of # characters at and to the right of the cursor are deleted; all characters to the right of it move left # columns, leaving behind blank space. The cursor position is unchanged. \e[P is equivalent to \e[1P.

Escape sequences for Set Graphics Rendition

  • \e[#;...;#m

    SGM: Set Graphics Mode: Calls the graphics functions specified by the following values. These specified functions remain active until the next occurrence of this escape sequence. Graphics mode changes the colors and attributes of text (such as bold and underline) displayed on the screen.

    • Text attributes
             0    All attributes off
       1    Bold on
       4    Underscore on
       7    Reverse video on
       8    Concealed on
             21   Bold off
       24   Underscore off
       27   Reverse video off
       28   Concealed off
    • Foreground colors
             30    Black
       31    Red
       32    Green
       33    Yellow
       34    Blue
       35    Magenta
       36    Cyan
       37    White
    • Background colors
             40    Black
       41    Red
       42    Green
       43    Yellow
       44    Blue
       45    Magenta
       46    Cyan
       47    White

    \e[m is equivalent to \e[0m.

Escape sequences for Select Character Set

  • \e(U

    Selects null mapping - straight to character from the codepage of the console.

  • \e(K

    Selects Windows to DOS mapping. This is the default mapping. It's useful because one types the script with a Windows-based editor (using a Windows codepage) and the script prints its messages on the console using another codepage: without translation, the characters with a code greatest than 127 are different and the printed messages may be not readable.

    The conversion is done by the Windows internal functions. If a character cannot be represented in the console code page it is replaced by a question mark character.

  • \e(#X

    This escape sequence is not standard! It's an experimental one, just for fun :-)

    If (and only if) the console uses an Unicode police, it is possible to change its codepage with this escape sequence. No effect with an ordinary "Raster Font". (For Windows NT/2000/XP the currently available Unicode console font is the Lucida Console TrueType font.) # is the number of the codepage needed, 855 for cp855 for instance.

AUXILIARY FUNCTIONS

Because the module exports no symbols into the callers namespace, it's necessary to import the names of the functions before using them.

  • Cls( );

    Clears the screen with the current background color, and set cursor to (1,1).

  • $old_title = Title( [$new_title] );

    Gets and sets the title bar of the current console window. With no argument the title is not modified.

      use Win32::Console::ANSI qw/ Title /;
  for (reverse 0..5) {
    Title "Count down ... $_";
    sleep 1;
  }
  • ($old_x, $old_y) = Cursor( [$new_x, $new_y] );

    Gets and sets the cursor position (the upper-left corner of the screen is at (1, 1)). With no arguments the cursor position is not modified. If one of the two coordinates $new_x or $new_y is 0, the corresponding coordinate doesn't change.

      use Win32::Console::ANSI qw/ Cursor /;
  ($x, $y) = Cursor();     # reads cursor position
  Cursor(5, 8);            # puts the cursor at column 5, line 8
  Cursor(5, 0);            # puts the cursor at column 5, line doesn't change
  Cursor(0, 8);            # puts the cursor at line 8, column doesn't change
  Cursor(0, 0);            # the cursor doesn't change a position (useless!)
  ($x, $y) = Cursor(5, 8); # reads cursor position AND puts cursor at (5, 8)
  • ($Xmax, $Ymax) = XYMax( );

    Gets the maximum cursor position. If ($x, $y) = Cursor() we have always 1 <= $x <= $Xmax and 1 <= $y <= $Ymax.

  • $success = SetConsoleSize( $width, $height );

    Sets the new size, in columns and rows, of the screen buffer. The specified $width and $height cannot be less than the width and height of the screen buffer's window. The specified dimensions also cannot be less than the minimum size allowed by the system.

    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero and the extended error message is in $^E.

  • $old_ACP = ScriptCP( [$new_ACP] );

    Set the codepage of the script and return the old value.

LIMITATIONS

  • Due to DOS-console limitations, the blink mode (text attributes 5 and 25) is not implemented.

SEE ALSO

the Win32::Console manpage, the Term::ANSIColor manpage, the Term::ANSIScreen manpage.

AUTHOR

J-L Morel <jl_morel@bribes.org>

Home page: http://www.bribes.org/perl/wANSIConsole.html

COPYRIGHT

Copyright (c) 2003-2005 J-L Morel. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Win32::DBIODBC - Win32::ODBC emulation layer for the DBI

  • TO DO
  • AUTHOR

NAME

Win32::DBIODBC - Win32::ODBC emulation layer for the DBI

SYNOPSIS

  use Win32::DBIODBC;     # instead of use Win32::ODBC

DESCRIPTION

This is a very basic very alpha quality Win32::ODBC emulation for the DBI. To use it just replace

        use Win32::ODBC;

in your scripts with

        use Win32::DBIODBC;

or, while experimenting, you can pre-load this module without changing your scripts by doing

        perl -MWin32::DBIODBC your_script_name

TO DO

Error handling is virtually non-existant.

AUTHOR

Tom Horen <tho@melexis.com>


Win32::Event - Use Win32 event objects from Perl

    • Methods
  • AUTHOR

NAME

Win32::Event - Use Win32 event objects from Perl

SYNOPSIS

        use Win32::Event;

        $event = Win32::Event->new($manual,$initial,$name);
        $event->wait();

DESCRIPTION

This module allows access to the Win32 event objects. The wait method and wait_all & wait_any functions are inherited from the Win32::IPC module.

Methods

$event = Win32::Event->new([$manual, [$initial, [$name]]])

Constructor for a new event object. If $manual is true, you must manually reset the event after it is signalled (the default is false). If $initial is true, the initial state of the object is signalled (default false). If $name is omitted, creates an unnamed event object.

If $name signifies an existing event object, then $manual and $initial are ignored and the object is opened. If this happens, $^E will be set to 183 (ERROR_ALREADY_EXISTS).

$event = Win32::Event->open($name)

Constructor for opening an existing event object.

$event->pulse

Signal the $event and then immediately reset it. If $event is a manual-reset event, releases all threads currently blocking on it. If it's an auto-reset event, releases just one thread.

If no threads are waiting, just resets the event.

$event->reset

Reset the $event to nonsignalled.

$event->set

Set the $event to signalled.

$event->wait([$timeout])

Wait for $event to be signalled. See Win32::IPC.

AUTHOR

Christopher J. Madsen <cjm@pobox.com>


Win32::EventLog - Process Win32 Event Logs from Perl

  • The EventLog Object and its Methods
  • Other Win32::EventLog functions.
  • Example 1
  • Example 2
  • BUGS
  • AUTHOR

NAME

Win32::EventLog - Process Win32 Event Logs from Perl

SYNOPSIS

        use Win32::EventLog
        $handle=Win32::EventLog->new("Application");

DESCRIPTION

This module implements most of the functionality available from the Win32 API for accessing and manipulating Win32 Event Logs. The access to the EventLog routines is divided into those that relate to an EventLog object and its associated methods and those that relate other EventLog tasks (like adding an EventLog record).

The EventLog Object and its Methods

The following methods are available to open, read, close and backup EventLogs.

Win32::EventLog->new(SOURCENAME [,SERVERNAME]);

The new() method creates a new EventLog object and returns a handle to it. This hande is then used to call the methods below.

The method is overloaded in that if the supplied SOURCENAME argument contains one or more literal '\' characters (an illegal character in a SOURCENAME), it assumes that you are trying to open a backup eventlog and uses SOURCENAME as the backup eventlog to open. Note that when opening a backup eventlog, the SERVERNAME argument is ignored (as it is in the underlying Win32 API). For EventLogs on remote machines, the SOURCENAME parameter must therefore be specified as a UNC path.

$handle->Backup(FILENAME);

The Backup() method backs up the EventLog represented by $handle. It takes a single arguemt, FILENAME. When $handle represents an EventLog on a remote machine, FILENAME is filename on the remote machine and cannot be a UNC path (i.e you must use C:\TEMP\App.EVT). The method will fail if the log file already exists.

$handle->Read(FLAGS, OFFSET, HASHREF);

The Read() method read an EventLog entry from the EventLog represented by $handle.

$handle->Close();

The Close() method closes the EventLog represented by $handle. After Close() has been called, any further attempt to use the EventLog represented by $handle will fail.

$handle->GetOldest(SCALARREF);

The GetOldest() method number of the the oldest EventLog record in the EventLog represented by $handle. This is required to correctly compute the OFFSET required by the Read() method.

$handle->GetNumber(SCALARREF);

The GetNumber() method returns the number of EventLog records in the EventLog represented by $handle. The number of the most recent record in the EventLog is therefore computed by

        $handle->GetOldest($oldest);
        $handle->GetNumber($lastRec);
        $lastRecOffset=$oldest+$lastRec;
$handle->Clear(FILENAME);

The Clear() method clears the EventLog represented by $handle. If you provide a non-null FILENAME, the EventLog will be backed up into FILENAME before the EventLog is cleared. The method will fail if FILENAME is specified and the file refered to exists. Note also that FILENAME specifies a file local to the machine on which the EventLog resides and cannot be specified as a UNC name.

$handle->Report(HASHREF);

The Report() method generates an EventLog entry. The HASHREF should contain the following keys:

Computer

The Computer field specfies which computer you want the EventLog entry recorded. If this key doesn't exist, the server name used to create the $handle is used.

Source

The Source field specifies the source that generated the EventLog entry. If this key doesn't exist, the source name used to create the $handle is used.

EventType

The EventType field should be one of the constants

EVENTLOG_ERROR_TYPE

An Error event is being logged.

EVENTLOG_WARNING_TYPE

A Warning event is being logged.

EVENTLOG_INFORMATION_TYPE

An Information event is being logged.

EVENTLOG_AUDIT_SUCCESS

A Success Audit event is being logged (typically in the Security EventLog).

EVENTLOG_AUDIT_FAILURE

A Failure Audit event is being logged (typically in the Security EventLog).

These constants are exported into the main namespace by default.

Category

The Category field can have any value you want. It is specific to the particular Source.

EventID

The EventID field should contain the ID of the message that this event pertains too. This assumes that you have an associated message file (indirectly referenced by the field Source).

Data

The Data field contains raw data associated with this event.

Strings

The Strings field contains the single string that itself contains NUL terminated sub-strings. This are used with the EventID to generate the message as seen from (for example) the Event Viewer application.

Other Win32::EventLog functions.

The following functions are part of the Win32::EventLog package but are not callable from an EventLog object.

GetMessageText(HASHREF);

The GetMessageText() function assumes that HASHREF was obtained by a call to $handle->Read(). It returns the formatted string that represents the fully resolved text of the EventLog message (such as would be seen in the Windows NT Event Viewer). For convenience, the key 'Message' in the supplied HASHREF is also set to the return value of this function.

If you set the variable $Win32::EventLog::GetMessageText to 1 then each call to $handle->Read() will call this function automatically.

Example 1

The following example illustrates the way in which the EventLog module can be used. It opens the System EventLog and reads through it from oldest to newest records. For each record from the Source EventLog it extracts the full text of the Entry and prints the EventLog message text out.

 use Win32::EventLog;

 $handle=Win32::EventLog->new("System", $ENV{ComputerName})
        or die "Can't open Application EventLog\n";
 $handle->GetNumber($recs)
        or die "Can't get number of EventLog records\n";
 $handle->GetOldest($base)
        or die "Can't get number of oldest EventLog record\n";

 while ($x < $recs) {
        $handle->Read(EVENTLOG_FORWARDS_READ|EVENTLOG_SEEK_READ,
                                  $base+$x,
                                  $hashRef)
                or die "Can't read EventLog entry #$x\n";
        if ($hashRef->{Source} eq "EventLog") {
                Win32::EventLog::GetMessageText($hashRef);
                print "Entry $x: $hashRef->{Message}\n";
        }
        $x++;
 }

Example 2

To backup and clear the EventLogs on a remote machine, do the following :-

 use Win32::EventLog;

 $myServer="\\\\my-server";     # your servername here.
 my($date)=join("-", ((split(/\s+/, scalar(localtime)))[0,1,2,4]));
 my($dest);

 for my $eventLog ("Application", "System", "Security") {
        $handle=Win32::EventLog->new($eventLog, $myServer)
                or die "Can't open Application EventLog on $myServer\n";

        $dest="C:\\BackupEventLogs\\$eventLog\\$date.evt";
        $handle->Backup($dest)
                or warn "Could not backup and clear the $eventLog EventLog on $myServer ($^E)\n";

        $handle->Close;
         }

Note that only the Clear method is required. Note also that if the file $dest exists, the function will fail.

BUGS

None currently known.

The test script for 'make test' should be re-written to use the EventLog object.

AUTHOR

Original code by Jesse Dougherty for HiP Communications. Additional fixes and updates attributed to Martin Pauley <martin.pauley@ulsterbank.ltd.uk>) and Bret Giddings (bret@essex.ac.uk)


Win32::File - manage file attributes in perl

  • Functions
    • NOTE
  • Constants

NAME

Win32::File - manage file attributes in perl

SYNOPSIS

        use Win32::File;

DESCRIPTION

This module offers the retrieval and setting of file attributes.

Functions

NOTE

All of the functions return FALSE (0) if they fail, unless otherwise noted. The function names are exported into the caller's namespace by request.

GetAttributes(filename, returnedAttributes)

Gets the attributes of a file or directory. returnedAttributes will be set to the OR-ed combination of the filename attributes.

SetAttributes(filename, newAttributes)

Sets the attributes of a file or directory. newAttributes must be an OR-ed combination of the attributes.

Constants

The following constants are exported by default.

ARCHIVE
COMPRESSED
DIRECTORY
HIDDEN
NORMAL
OFFLINE
READONLY
SYSTEM
TEMPORARY


Win32::FileSecurity - manage FileSecurity Discretionary Access Control Lists in perl

  • CONSTANTS
  • FUNCTIONS
    • NOTE:
    • %permisshash
  • EXAMPLE1
  • EXAMPLE2
  • COMMON MASKS FROM CACLS AND WINFILE
    • READ
    • CHANGE
    • ADD & READ
    • FULL
  • RESOURCES
  • VERSION
  • REVISION NOTES
  • KNOWN ISSUES / BUGS

NAME

Win32::FileSecurity - manage FileSecurity Discretionary Access Control Lists in perl

SYNOPSIS

        use Win32::FileSecurity;

DESCRIPTION

This module offers control over the administration of system FileSecurity DACLs. You may want to use Get and EnumerateRights to get an idea of what mask values correspond to what rights as viewed from File Manager.

CONSTANTS

  DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER,
  SYNCHRONIZE, STANDARD_RIGHTS_REQUIRED,
  STANDARD_RIGHTS_READ, STANDARD_RIGHTS_WRITE,
  STANDARD_RIGHTS_EXECUTE, STANDARD_RIGHTS_ALL,
  SPECIFIC_RIGHTS_ALL, ACCESS_SYSTEM_SECURITY,
  MAXIMUM_ALLOWED, GENERIC_READ, GENERIC_WRITE,
  GENERIC_EXECUTE, GENERIC_ALL, F, FULL, R, READ,
  C, CHANGE

FUNCTIONS

NOTE:

All of the functions return false if they fail, unless otherwise noted. Errors returned via $! containing both Win32 GetLastError() and a text message indicating Win32 function that failed.

constant( $name, $set )

Stores the value of named constant $name into $set. Same as $set = Win32::FileSecurity::NAME_OF_CONSTANT();.

Get( $filename, \%permisshash )

Gets the DACLs of a file or directory.

Set( $filename, \%permisshash )

Sets the DACL for a file or directory.

EnumerateRights( $mask, \@rightslist )

Turns the bitmask in $mask into a list of strings in @rightslist.

MakeMask( qw( DELETE READ_CONTROL ) )

Takes a list of strings representing constants and returns a bitmasked integer value.

%permisshash

Entries take the form $permisshash{USERNAME} = $mask ;

EXAMPLE1

    # Gets the rights for all files listed on the command line.
    use Win32::FileSecurity qw(Get EnumerateRights);

    foreach( @ARGV ) {
        next unless -e $_ ;
        if ( Get( $_, \%hash ) ) {
            while( ($name, $mask) = each %hash ) {
                print "$name:\n\t";
                EnumerateRights( $mask, \@happy ) ;
                print join( "\n\t", @happy ), "\n";
            }
        }
        else {
            print( "Error #", int( $! ), ": $!" ) ;
        }
    }

EXAMPLE2

    # Gets existing DACL and modifies Administrator rights
    use Win32::FileSecurity qw(MakeMask Get Set);

    # These masks show up as Full Control in File Manager
    $file = MakeMask( qw( FULL ) );

    $dir = MakeMask( qw(
            FULL
        GENERIC_ALL
    ) );

    foreach( @ARGV ) {
        s/\\$//;
        next unless -e;
        Get( $_, \%hash ) ;
        $hash{Administrator} = ( -d ) ? $dir : $file ;
        Set( $_, \%hash ) ;
    }

COMMON MASKS FROM CACLS AND WINFILE

READ

        MakeMask( qw( FULL ) ); # for files
        MakeMask( qw( READ GENERIC_READ GENERIC_EXECUTE ) ); # for directories

CHANGE

        MakeMask( qw( CHANGE ) ); # for files
        MakeMask( qw( CHANGE GENERIC_WRITE GENERIC_READ GENERIC_EXECUTE ) ); # for directories

ADD & READ

        MakeMask( qw( ADD GENERIC_READ GENERIC_EXECUTE ) ); # for directories only!

FULL

        MakeMask( qw( FULL ) ); # for files
        MakeMask( qw( FULL  GENERIC_ALL ) ); # for directories

RESOURCES

From Microsoft: check_sd
http://premium.microsoft.com/download/msdn/samples/2760.exe

(thanks to Guert Schimmel at Sybase for turning me on to this one)

VERSION

1.03 ALPHA 97-12-14

REVISION NOTES

  1. 03 ALPHA 1998.01.11

    Imported diffs from 0.67 (parent) version

  2. 02 ALPHA 1997.12.14

    Pod fixes, @EXPORT list additions <gsar@activestate.com>

    Fix unitialized vars on unknown ACLs <jmk@exc.bybyte.de>

  3. 01 ALPHA 1997.04.25

    CORE Win32 version imported from 0.66 <gsar@activestate.com>

  4. 67 ALPHA 1997.07.07

    Kludged bug in mapping bits to separate ACE's. Notably, this screwed up CHANGE access by leaving out a delete bit in the INHERIT_ONLY_ACE | OBJECT_INHERIT_ACE Access Control Entry.

    May need to rethink...

  5. 66 ALPHA 1997.03.13

    Fixed bug in memory allocation check

  6. 65 ALPHA 1997.02.25

    Tested with 5.003 build 303

    Added ISA exporter, and @EXPORT_OK

    Added F, FULL, R, READ, C, CHANGE as composite pre-built mask names.

    Added server\ to keys returned in hash from Get

    Made constants and MakeMask case insensitive (I don't know why I did that)

    Fixed mask comparison in ListDacl and Enumerate Rights from simple & mask to exact bit match ! ( ( x & y ) ^ x ) makes sure all bits in x are set in y

    Fixed some "wild" pointers

  7. 60 ALPHA 1996.07.31

    Now suitable for file and directory permissions

    Included ListDacl.exe in bundle for debugging

    Added "intuitive" inheritance for directories, basically functions like FM triggered by presence of GENERIC_ rights this may need to change

    see EXAMPLE2

    Changed from AddAccessAllowedAce to AddAce for control over inheritance

  8. 51 ALPHA 1996.07.20

    Fixed memory allocation bug

  9. 50 ALPHA 1996.07.29

    Base functionality

    Using AddAccessAllowedAce

    Suitable for file permissions

KNOWN ISSUES / BUGS

  1. May not work on remote drives.

  2. Errors croak, don't return via $! as documented.


Win32::IPC - Base class for Win32 synchronization objects

    • Methods
    • Functions
    • Deprecated Functions and Methods
  • INTERNALS
  • AUTHOR

NAME

Win32::IPC - Base class for Win32 synchronization objects

SYNOPSIS

    use Win32::Event 1.00 qw(wait_any);
    #Create objects.

    wait_any(@ListOfObjects,$timeout);

DESCRIPTION

This module is loaded by the other Win32 synchronization modules. You shouldn't need to load it yourself. It supplies the wait functions to those modules.

The synchronization modules are Win32::ChangeNotify, Win32::Event, Win32::Mutex, & Win32::Semaphore.

In addition, you can use wait_any and wait_all with Win32::Console and Win32::Process objects. (However, those modules do not export the wait functions; you must load one of the synchronization modules (or just Win32::IPC)).

Methods

Win32::IPC supplies one method to all synchronization objects.

$obj->wait([$timeout])

Waits for $obj to become signalled. $timeout is the maximum time to wait (in milliseconds). If $timeout is omitted, waits forever. If $timeout is 0, returns immediately.

Returns:

   +1    The object is signalled
   -1    The object is an abandoned mutex
    0    Timed out
  undef  An error occurred

Functions

wait_any(@objects, [$timeout])

Waits for at least one of the @objects to become signalled. $timeout is the maximum time to wait (in milliseconds). If $timeout is omitted, waits forever. If $timeout is 0, returns immediately.

The return value indicates which object ended the wait:

   +N    $object[N-1] is signalled
   -N    $object[N-1] is an abandoned mutex
    0    Timed out
  undef  An error occurred

If more than one object became signalled, the one with the lowest index is used.

wait_all(@objects, [$timeout])

This is the same as wait_any, but it waits for all the @objects to become signalled. The return value indicates the last object to become signalled, and is negative if at least one of the @objects is an abandoned mutex.

Deprecated Functions and Methods

Win32::IPC still supports the ActiveWare syntax, but its use is deprecated.

INFINITE

Constant value for an infinite timeout. Omit the $timeout argument instead.

WaitForMultipleObjects(\@objects, $wait_all, $timeout)

Warning: WaitForMultipleObjects erases @objects! Use wait_all or wait_any instead.

$obj->Wait($timeout)

Similar to not $obj->wait($timeout).

INTERNALS

The wait_any and wait_all functions support two kinds of objects. Objects derived from Win32::IPC are expected to consist of a reference to a scalar containing the Win32 HANDLE as an IV.

Other objects (for which UNIVERSAL::isa($object, "Win32::IPC") is false), are expected to implement a get_Win32_IPC_HANDLE method. When called in scalar context with no arguments, this method should return a Win32 HANDLE (as an IV) suitable for passing to the Win32 WaitForMultipleObjects API function.

AUTHOR

Christopher J. Madsen <cjm@pobox.com>

Loosely based on the original module by ActiveWare Internet Corp., http://www.ActiveWare.com


Win32::Internet - Access to WININET.DLL functions

  • INTRODUCTION
  • REFERENCE
    • General Internet Functions
    • FTP Functions
    • HTTP Functions
  • APPENDIX
    • Microsoft Win32 Internet Functions
    • Functions Table
    • Constants
  • VERSION HISTORY
  • AUTHOR
  • CREDITS
  • DISCLAIMER

NAME

Win32::Internet - Access to WININET.DLL functions

INTRODUCTION

This extension to Perl implements the Win32 Internet APIs (found in WININET.DLL). They give a complete support for HTTP, FTP and GOPHER connections.

See the Version History and the Functions Table for a list of the currently supported features. You should also get a copy of the Microsoft Win32 Internet Functions documentation.

REFERENCE

To use this module, first add the following line at the beginning of your script:

    use Win32::Internet;

Then you have to open an Internet connection with this command:

    $Connection = new Win32::Internet();

This is required to use any of the function of this module. It will create an Internet object in Perl on which you can act upon with the General Internet Functions explained later.

The objects available are:

  • Internet connections (the main object, see new)

  • URLs (see OpenURL)

  • FTP sessions (see FTP)

  • HTTP sessions (see HTTP)

  • HTTP requests (see OpenRequest)

As in the good Perl tradition, there are in this extension different ways to do the same thing; there are, in fact, different levels of implementation of the Win32 Internet Functions. Some routines use several Win32 API functions to perform a complex task in a single call; they are simpler to use, but of course less powerful.

There are then other functions that implement nothing more and nothing less than the corresponding API function, so you can use all of their power, but with some additional programming steps.

To make an example, there is a function called FetchURL that you can use to fetch the content of any HTTP, FTP or GOPHER URL with this simple commands:

    $INET = new Win32::Internet();
    $file = $INET->FetchURL("http://www.yahoo.com");

You can have the same result (and this is actually what is done by FetchURL) this way:

    $INET = new Win32::Internet();
    $URL = $INET->OpenURL("http://www.yahoo.com");
    $file = $URL->ReadFile();
    $URL->Close();

Or, you can open a complete HTTP session:

    $INET = new Win32::Internet();
    $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
    ($statuscode, $headers, $file) = $HTTP->Request("/");
    $HTTP->Close();

Finally, you can choose to manage even the HTTP request:

    $INET = new Win32::Internet();
    $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
    $HTTP->OpenRequest($REQ, "/");
    $REQ->AddHeader("If-Modified-Since: Saturday, 16-Nov-96 15:58:50 GMT");
    $REQ->SendRequest();
    $statuscode = $REQ->QueryInfo("",HTTP_QUERY_STATUS_CODE);
    $lastmodified = $REQ->QueryInfo("Last-Modified");
    $file = $REQ->ReadEntireFile();
    $REQ->Close();
    $HTTP->Close();

To open and control a complete FTP session, type:

    $Connection->FTP($Session, "ftp://ftp.activeware.com", "anonymous", "dada\@divinf.it");

This will create an FTP object in Perl to which you can apply the FTP functions provided by the package:

    $Session->Cd("/ntperl/perl5.001m/CurrentBuild");
    $Session->Ascii();
    $Session->Get("110-i86.zip");
    $Session->Close();

For a more complete example, see the TEST.PL file that comes with the package.

General Internet Functions

General Note

All methods assume that you have the line:

    use Win32::Internet;

somewhere before the method calls, and that you have an Internet object called $INET which was created using this call:

    $INET = new Win32::Internet();

See new for more information.

Methods

CanonicalizeURL URL, [flags]

Converts a URL to a canonical format, which includes converting unsafe characters to escape sequences. Returns the canonicalized URL or undef on errors. For the possible values of flags, refer to the Microsoft Win32 Internet Functions document. See also CombineURL and OpenURL.

Example:

    $cURL = $INET->CanonicalizeURL($URL);
    $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);
Close
Close object

Closes an Internet connection. This can be applied to any Win32::Internet object (Internet connections, URLs, FTP sessions, etc.). Note that it is not "strictly" required to close the connections you create, since the Win32::Internet objects are automatically closed when the program ends (or when you elsehow destroy such an object).

Example:

    $INET->Close();
    $FTP->Close();
    $INET->Close($FTP); # same as above...
CombineURL baseURL, relativeURL, [flags]

Combines a base and relative URL into a single URL. Returns the (canonicalized) combined URL or undef on errors. For the possible values of flags, refer to the Microsoft Win32 Internet Functions document. See also CombineURL and OpenURL.

Example:

    $URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", "..");
ConnectBackoff [value]

Reads or sets the delay value, in milliseconds, to wait between connection retries. If no value parameter is specified, the current value is returned; otherwise, the delay between retries is set to value. See also ConnectTimeout, ConnectRetries, QueryOption and SetOption.

Example:

    $HTTP->ConnectBackoff(2000);
    $backoff = $HTTP->ConnectBackoff();
ConnectRetries [value]

Reads or sets the number of times a connection is retried before considering it failed. If no value parameter is specified, the current value is returned; otherwise, the number of retries is set to value. The default value for ConnectRetries is 5. See also ConnectBackoff, ConnectTimeout, QueryOption and SetOption.

Example:

    $HTTP->ConnectRetries(20);
    $retries = $HTTP->ConnectRetries();
ConnectTimeout [value]

Reads or sets the timeout value (in milliseconds) before a connection is considered failed. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ConnectTimeout is infinite. See also ConnectBackoff, ConnectRetries, QueryOption and SetOption.

Example:

    $HTTP->ConnectTimeout(10000);
    $timeout = $HTTP->ConnectTimeout();
ControlReceiveTimeout [value]

Reads or sets the timeout value (in milliseconds) to use for non-data (control) receive requests before they are canceled. Currently, this value has meaning only for FTP sessions. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ControlReceiveTimeout is infinite. See also ControlSendTimeout, QueryOption and SetOption.

Example:

    $HTTP->ControlReceiveTimeout(10000);
    $timeout = $HTTP->ControlReceiveTimeout();
ControlSendTimeout [value]

Reads or sets the timeout value (in milliseconds) to use for non-data (control) send requests before they are canceled. Currently, this value has meaning only for FTP sessions. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ControlSendTimeout is infinite. See also ControlReceiveTimeout, QueryOption and SetOption.

Example:

    $HTTP->ControlSendTimeout(10000);
    $timeout = $HTTP->ControlSendTimeout();
CrackURL URL, [flags]

Splits an URL into its component parts and returns them in an array. Returns undef on errors, otherwise the array will contain the following values: scheme, host, port, username, password, path, extrainfo.

For example, the URL "http://www.divinf.it/index.html#top" can be splitted in:

    http, www.divinf.it, 80, anonymous, dada@divinf.it, /index.html, #top

If you don't specify a flags parameter, ICU_ESCAPE will be used by default; for the possible values of flags refer to the Microsoft Win32 Internet Functions documentation. See also CreateURL.

Example:

    @parts=$INET->CrackURL("http://www.activeware.com");
    ($scheme, $host, $port, $user, $pass, $path, $extra) =
         $INET->CrackURL("http://www.divinf.it:80/perl-win32/index.sht#feedback");
CreateURL scheme, hostname, port, username, password, path, extrainfo, [flags]
CreateURL hashref, [flags]

Creates a URL from its component parts. Returns undef on errors, otherwise the created URL.

If you pass hashref (a reference to an hash array), the following values are taken from the array:

    %hash=(
      "scheme"    => "scheme",
      "hostname"  => "hostname",
      "port"      => port,
      "username"  => "username",
      "password"  => "password",
      "path"      => "path",
      "extrainfo" => "extrainfo",
    );

If you don't specify a flags parameter, ICU_ESCAPE will be used by default; for the other possible values of flags refer to the Microsoft Win32 Internet Functions documentation. See also CrackURL.

Example:

    $URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback");
    $URL=$I->CreateURL(\%params);
DataReceiveTimeout [value]

Reads or sets the timeout value (in milliseconds) to use for data receive requests before they are canceled. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for DataReceiveTimeout is infinite. See also DataSendTimeout, QueryOption and SetOption.

Example:

    $HTTP->DataReceiveTimeout(10000);
    $timeout = $HTTP->DataReceiveTimeout();
DataSendTimeout [value]

Reads or sets the timeout value (in milliseconds) to use for data send requests before they are canceled. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for DataSendTimeout is infinite. See also DataReceiveTimeout, QueryOption and SetOption.

Example:

    $HTTP->DataSendTimeout(10000);
    $timeout = $HTTP->DataSendTimeout();
Error

Returns the last recorded error in the form of an array or string (depending upon the context) containing the error number and an error description. Can be applied on any Win32::Internet object (FTP sessions, etc.). There are 3 types of error you can encounter; they are recognizable by the error number returned:

  • -1

    A "trivial" error has occurred in the package. For example, you tried to use a method on the wrong type of object.

  • 1 .. 11999

    A generic error has occurred and the Win32::GetLastError error message is returned.

  • 12000 and higher

    An Internet error has occurred; the extended Win32 Internet API error message is returned.

See also GetResponse.

Example:

    die $INET->Error(), qq(\n);
    ($ErrNum, $ErrText) = $INET->Error();
FetchURL URL

Fetch the content of an HTTP, FTP or GOPHER URL. Returns the content of the file read (or undef if there was an error and nothing was read). See also OpenURL and ReadFile.

Example:

    $file = $INET->FetchURL("http://www.yahoo.com/");
    $file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip");
FTP ftpobject, server, username, password, [port, pasv, context]
FTP ftpobject, hashref

Opens an FTP connection to server logging in with the given username and password.

The parameters and their values are:

  • server

    The server to connect to. Default: none.

  • username

    The username used to login to the server. Default: anonymous.

  • password

    The password used to login to the server. Default: none.

  • port

    The port of the FTP service on the server. Default: 21.

  • pasv

    If it is a value other than 0, use passive transfer mode. Default is taken from the parent Internet connection object; you can set this value with the Pasv method.

  • context

    A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none.

If you pass hashref (a reference to an hash array), the following values are taken from the array:

    %hash=(
      "server"   => "server",
      "username" => "username",
      "password" => "password",
      "port"     => port,
      "pasv"     => pasv,
      "context"  => context,
    );

This method returns undef if the connection failed, a number otherwise. You can then call any of the FTP functions as methods of the newly created ftpobject.

Example:

    $result = $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
    # and then for example...
    $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");

    $params{"server"} = "ftp.activeware.com";
    $params{"password"} = "dada\@divinf.it";
    $params{"pasv"} = 0;
    $result = $INET->FTP($FTP,\%params);
GetResponse

Returns the text sent by a remote server in response to the last function executed. It applies on any Win32::Internet object, particularly of course on FTP sessions. See also the Error function.

Example:

    print $INET->GetResponse();
    $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
    print $FTP->GetResponse();
GetStatusCallback context

Returns information about the progress of the asynchronous operation identified by context; those informations consist of two values: a status code (one of the INTERNET_STATUS_* Constants) and an additional value depending on the status code; for example, if the status code returned is INTERNET_STATUS_HANDLE_CREATED, the second value will hold the handle just created. For more informations on those values, please refer to the Microsoft Win32 Internet Functions documentation. See also SetStatusCallback.

Example:

    ($status, $info) = $INET->GetStatusCallback(1);
HTTP httpobject, server, username, password, [port, flags, context]
HTTP httpobject, hashref

Opens an HTTP connection to server logging in with the given username and password.

The parameters and their values are:

  • server

    The server to connect to. Default: none.

  • username

    The username used to login to the server. Default: anonymous.

  • password

    The password used to login to the server. Default: none.

  • port

    The port of the HTTP service on the server. Default: 80.

  • flags

    Additional flags affecting the behavior of the function. Default: none.

  • context

    A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none.

Refer to the Microsoft Win32 Internet Functions documentation for more details on those parameters.

If you pass hashref (a reference to an hash array), the following values are taken from the array:

    %hash=(
      "server"   => "server",
      "username" => "username",
      "password" => "password",
      "port"     => port,
      "flags"    => flags,
      "context"  => context,
    );

This method returns undef if the connection failed, a number otherwise. You can then call any of the HTTP functions as methods of the newly created httpobject.

Example:

    $result = $INET->HTTP($HTTP,"www.activeware.com","anonymous","dada\@divinf.it");
    # and then for example...
    ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");

    $params{"server"} = "www.activeware.com";
    $params{"password"} = "dada\@divinf.it";
    $params{"flags"} = INTERNET_FLAG_RELOAD;
    $result = $INET->HTTP($HTTP,\%params);
new Win32::Internet [useragent, opentype, proxy, proxybypass, flags]
new Win32::Internet [hashref]

Creates a new Internet object and initializes the use of the Internet functions; this is required before any of the functions of this package can be used. Returns undef if the connection fails, a number otherwise. The parameters and their values are:

  • useragent

    The user agent passed to HTTP requests. See OpenRequest. Default: Perl-Win32::Internet/version.

  • opentype

    How to access to the Internet (eg. directly or using a proxy). Default: INTERNET_OPEN_TYPE_DIRECT.

  • proxy

    Name of the proxy server (or servers) to use. Default: none.

  • proxybypass

    Optional list of host names or IP addresses, or both, that are known locally. Default: none.

  • flags

    Additional flags affecting the behavior of the function. Default: none.

Refer to the Microsoft Win32 Internet Functions documentation for more details on those parameters. If you pass hashref (a reference to an hash array), the following values are taken from the array:

    %hash=(
      "useragent"   => "useragent",
      "opentype"    => "opentype",
      "proxy"       => "proxy",
      "proxybypass" => "proxybypass",
      "flags"       => flags,
    );

Example:

    $INET = new Win32::Internet();
    die qq(Cannot connect to Internet...\n) if ! $INET;

    $INET = new Win32::Internet("Mozilla/3.0", INTERNET_OPEN_TYPE_PROXY, "www.microsoft.com", "");

    $params{"flags"} = INTERNET_FLAG_ASYNC;
    $INET = new Win32::Internet(\%params);
OpenURL urlobject, URL

Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location (URL). Returns undef on errors or a number if the connection was succesful. You can then retrieve the URL content by applying the methods QueryDataAvailable and ReadFile on the newly created urlobject. See also FetchURL.

Example:

    $INET->OpenURL($URL, "http://www.yahoo.com/");
    $bytes = $URL->QueryDataAvailable();
    $file = $URL->ReadEntireFile();
    $URL->Close();
Password [password]

Reads or sets the password used for an FTP or HTTP connection. If no password parameter is specified, the current value is returned; otherwise, the password is set to password. See also Username, QueryOption and SetOption.

Example:

    $HTTP->Password("splurfgnagbxam");
    $password = $HTTP->Password();
QueryDataAvailable

Returns the number of bytes of data that are available to be read immediately by a subsequent call to ReadFile (or undef on errors). Can be applied to URL or HTTP request objects. See OpenURL or OpenRequest.

Example:

    $INET->OpenURL($URL, "http://www.yahoo.com/");
    $bytes = $URL->QueryDataAvailable();
QueryOption option

Queries an Internet option. For the possible values of option, refer to the Microsoft Win32 Internet Functions document. See also SetOption.

Example:

    $value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT);
    $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);
ReadEntireFile

Reads all the data available from an opened URL or HTTP request object. Returns what have been read or undef on errors. See also OpenURL, OpenRequest and ReadFile.

Example:

    $INET->OpenURL($URL, "http://www.yahoo.com/");
    $file = $URL->ReadEntireFile();
ReadFile bytes

Reads bytes bytes of data from an opened URL or HTTP request object. Returns what have been read or undef on errors. See also OpenURL, OpenRequest, QueryDataAvailable and ReadEntireFile.

Note: be careful to keep bytes to an acceptable value (eg. don't tell him to swallow megabytes at once...). ReadEntireFile in fact uses QueryDataAvailable and ReadFile in a loop to read no more than 16k at a time.

Example:

    $INET->OpenURL($URL, "http://www.yahoo.com/");
    $chunk = $URL->ReadFile(16000);
SetOption option, value

Sets an Internet option. For the possible values of option, refer to the Microsoft Win32 Internet Functions document. See also QueryOption.

Example:

    $INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000);
    $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");
SetStatusCallback

Initializes the callback routine used to return data about the progress of an asynchronous operation.

Example:

    $INET->SetStatusCallback();

This is one of the step required to perform asynchronous operations; the complete procedure is:

    # use the INTERNET_FLAG_ASYNC when initializing
    $params{'flags'}=INTERNET_FLAG_ASYNC;
    $INET = new Win32::Internet(\%params);

    # initialize the callback routine
    $INET->SetStatusCallback();

    # specify the context parameter (the last 1 in this case)
    $INET->HTTP($HTTP, "www.yahoo.com", "anonymous", "dada\@divinf.it", 80, 0, 1);

At this point, control returns immediately to Perl and $INET->Error() will return 997, which means an asynchronous I/O operation is pending. Now, you can call

    $HTTP->GetStatusCallback(1);

in a loop to verify what's happening; see also GetStatusCallback.

TimeConvert time
TimeConvert seconds, minute, hours, day, month, year, day_of_week, RFC

The first form takes a HTTP date/time string and returns the date/time converted in the following array: seconds, minute, hours, day, month, year, day_of_week.

The second form does the opposite (or at least it should, because actually seems to be malfunctioning): it takes the values and returns an HTTP date/time string, in the RFC format specified by the RFC parameter (OK, I didn't find yet any accepted value in the range 0..2000, let me know if you have more luck with it).

Example:

    ($sec, $min, $hour, $day, $mday, $year, $wday) =
       $INET->TimeConvert("Sun, 26 Jan 1997 20:01:52 GMT");

    # the opposite DOESN'T WORK! which value should $RFC have???
    $time = $INET->TimeConvert(52, 1, 20, 26, 1, 1997, 0, $RFC);
UserAgent [name]

Reads or sets the user agent used for HTTP requests. If no name parameter is specified, the current value is returned; otherwise, the user agent is set to name. See also QueryOption and SetOption.

Example:

    $INET->UserAgent("Mozilla/3.0");
    $useragent = $INET->UserAgent();
Username [name]

Reads or sets the username used for an FTP or HTTP connection. If no name parameter is specified, the current value is returned; otherwise, the username is set to name. See also Password, QueryOption and SetOption.

Example:

    $HTTP->Username("dada");
    $username = $HTTP->Username();
Version

Returns the version numbers for the Win32::Internet package and the WININET.DLL version, as an array or string, depending on the context. The string returned will contain "package_version/DLL_version", while the array will contain: "package_version", "DLL_version".

Example:

    $version = $INET->Version(); # should return "0.06/4.70.1215"
    @version = $INET->Version(); # should return ("0.06", "4.70.1215")

FTP Functions

General Note

All methods assume that you have the following lines:

    use Win32::Internet;
    $INET = new Win32::Internet();
    $INET->FTP($FTP, "hostname", "username", "password");

somewhere before the method calls; in other words, we assume that you have an Internet object called $INET and an open FTP session called $FTP.

See new and FTP for more information.

Methods

Ascii
Asc

Sets the ASCII transfer mode for this FTP session. It will be applied to the subsequent Get functions. See also the Binary and Mode function.

Example:

    $FTP->Ascii();
Binary
Bin

Sets the binary transfer mode for this FTP session. It will be applied to the subsequent Get functions. See also the Ascii and Mode function.

Example:

    $FTP->Binary();
Cd path
Cwd path
Chdir path

Changes the current directory on the FTP remote host. Returns path or undef on error.

Example:

    $FTP->Cd("/pub");
Delete file
Del file

Deletes a file on the FTP remote host. Returns undef on error.

Example:

    $FTP->Delete("110-i86.zip");
Get remote, [local, overwrite, flags, context]

Gets the remote FTP file and saves it locally in local. If local is not specified, it will be the same name as remote. Returns undef on error. The parameters and their values are:

  • remote

    The name of the remote file on the FTP server. Default: none.

  • local

    The name of the local file to create. Default: remote.

  • overwrite

    If 0, overwrites local if it exists; with any other value, the function fails if the local file already exists. Default: 0.

  • flags

    Additional flags affecting the behavior of the function. Default: none.

  • context

    A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none.

Refer to the Microsoft Win32 Internet Functions documentation for more details on those parameters.

Example:

    $FTP->Get("110-i86.zip");
    $FTP->Get("/pub/perl/languages/CPAN/00index.html", "CPAN_index.html");
List [pattern, listmode]
Ls [pattern, listmode]
Dir [pattern, listmode]

Returns a list containing the files found in this directory, eventually matching the given pattern (which, if omitted, is considered "*.*"). The content of the returned list depends on the listmode parameter, which can have the following values:

  • listmode=1 (or omitted)

    the list contains the names of the files found. Example:

        @files = $FTP->List();
    @textfiles = $FTP->List("*.txt");
    foreach $file (@textfiles) {
      print "Name: ", $file, "\n";
    }
  • listmode=2

    the list contains 7 values for each file, which respectively are:

    • the file name
    • the DOS short file name, aka 8.3
    • the size
    • the attributes
    • the creation time
    • the last access time
    • the last modified time

    Example:

        @files = $FTP->List("*.*", 2);
    for($i=0; $i<=$#files; $i+=7) {
      print "Name: ", @files[$i], "\n";
      print "Size: ", @files[$i+2], "\n";
      print "Attr: ", @files[$i+3], "\n";
    }
  • listmode=3

    the list contains a reference to an hash array for each found file; each hash contains:

    • name => the file name
    • altname => the DOS short file name, aka 8.3
    • size => the size
    • attr => the attributes
    • ctime => the creation time
    • atime => the last access time
    • mtime => the last modified time

    Example:

        @files = $FTP->List("*.*", 3);
    foreach $file (@files) {
      print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n";
    }

    Note: all times are reported as strings of the following format: second, hour, minute, day, month, year.

    Example:

        $file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00
Mkdir name
Md name

Creates a directory on the FTP remote host. Returns undef on error.

Example:

    $FTP->Mkdir("NextBuild");
Mode [mode]

If called with no arguments, returns the current transfer mode for this FTP session ("asc" for ASCII or "bin" for binary). The mode argument can be "asc" or "bin", in which case the appropriate transfer mode is selected. See also the Ascii and Binary functions. Returns undef on errors.

Example:

    print "Current mode is: ", $FTP->Mode();
    $FTP->Mode("asc"); # ...  same as $FTP->Ascii();
Pasv [mode]

If called with no arguments, returns 1 if the current FTP session has passive transfer mode enabled, 0 if not.

You can call it with a mode parameter (0/1) only as a method of a Internet object (see new), in which case it will set the default value for the next FTP objects you create (read: set it before, because you can't change this value once you opened the FTP session).

Example:

    print "Pasv is: ", $FTP->Pasv();

    $INET->Pasv(1);
    $INET->FTP($FTP,"ftp.activeware.com", "anonymous", "dada\@divinf.it");
    $FTP->Pasv(0); # this will be ignored...
Put local, [remote, context]

Upload the local file to the FTP server saving it under the name remote, which if if omitted is the same name as local. Returns undef on error.

context is a number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations.

Example:

    $FTP->Put("internet.zip");
    $FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip");
Pwd

Returns the current directory on the FTP server or undef on errors.

Example:

    $path = $FTP->Pwd();
Rename oldfile, newfile
Ren oldfile, newfile

Renames a file on the FTP remote host. Returns undef on error.

Example:

    $FTP->Rename("110-i86.zip", "68i-011.zip");
Rmdir name
Rd name

Removes a directory on the FTP remote host. Returns undef on error.

Example:

    $FTP->Rmdir("CurrentBuild");

HTTP Functions

General Note

All methods assume that you have the following lines:

    use Win32::Internet;
    $INET = new Win32::Internet();
    $INET->HTTP($HTTP, "hostname", "username", "password");

somewhere before the method calls; in other words, we assume that you have an Internet object called $INET and an open HTTP session called $HTTP.

See new and HTTP for more information.

Methods

AddHeader header, [flags]

Adds HTTP request headers to an HTTP request object created with OpenRequest. For the possible values of flags refer to the Microsoft Win32 Internet Functions document.

Example:

    $HTTP->OpenRequest($REQUEST,"/index.html");
    $REQUEST->AddHeader("If-Modified-Since:  Sunday, 17-Nov-96 11:40:03 GMT");
    $REQUEST->AddHeader("Accept: text/html\r\n", HTTP_ADDREQ_FLAG_REPLACE);
OpenRequest requestobject, [path, method, version, referer, accept, flags, context]
OpenRequest requestobject, hashref

Opens an HTTP request. Returns undef on errors or a number if the connection was succesful. You can then use one of the AddHeader, SendRequest, QueryInfo, QueryDataAvailable and ReadFile methods on the newly created requestobject. The parameters and their values are:

  • path

    The object to request. This is generally a file name, an executable module, etc. Default: /

  • method

    The method to use; can actually be GET, POST, HEAD or PUT. Default: GET

  • version

    The HTTP version. Default: HTTP/1.0

  • referer

    The URL of the document from which the URL in the request was obtained. Default: none

  • accept

    A single string with "\0" (ASCII zero) delimited list of content types accepted. The string must be terminated by "\0\0". Default: "text/*\0image/gif\0image/jpeg\0\0"

  • flags

    Additional flags affecting the behavior of the function. Default: none

  • context

    A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none

Refer to the Microsoft Win32 Internet Functions documentation for more details on those parameters. If you pass hashref (a reference to an hash array), the following values are taken from the array:

    %hash=(
      "path"        => "path",
      "method"      => "method",
      "version"     => "version",
      "referer"     => "referer",
      "accept"      => "accept",
      "flags"       => flags,
      "context"     => context,
    );

See also Request.

Example:

    $HTTP->OpenRequest($REQUEST, "/index.html");
    $HTTP->OpenRequest($REQUEST, "/index.html", "GET", "HTTP/0.9");

    $params{"path"} = "/index.html";
    $params{"flags"} = "
    $HTTP->OpenRequest($REQUEST, \%params);
QueryInfo header, [flags]

Queries information about an HTTP request object created with OpenRequest. You can specify an header (for example, "Content-type") and/or one or more flags. If you don't specify flags, HTTP_QUERY_CUSTOM will be used by default; this means that header should contain a valid HTTP header name. For the possible values of flags refer to the Microsoft Win32 Internet Functions document.

Example:

    $HTTP->OpenRequest($REQUEST,"/index.html");
    $statuscode = $REQUEST->QueryInfo("", HTTP_QUERY_STATUS_CODE);
    $headers = $REQUEST->QueryInfo("", HTTP_QUERY_RAW_HEADERS_CRLF); # will get all the headers
    $length = $REQUEST->QueryInfo("Content-length");
Request [path, method, version, referer, accept, flags]
Request hashref

Performs an HTTP request and returns an array containing the status code, the headers and the content of the file. It is a one-step procedure that makes an OpenRequest, a SendRequest, some QueryInfo, ReadFile and finally Close. For a description of the parameters, see OpenRequest.

Example:

    ($statuscode, $headers, $file) = $HTTP->Request("/index.html");
    ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");
SendRequest [postdata]

Send an HTTP request to the destination server. postdata are any optional data to send immediately after the request header; this is generally used for POST or PUT requests. See also OpenRequest.

Example:

    $HTTP->OpenRequest($REQUEST, "/index.html");
    $REQUEST->SendRequest();

    # A POST request...
    $HTTP->OpenRequest($REQUEST, "/cgi-bin/somescript.pl", "POST");

    #This line is a must -> (thanks Philip :)
    $REQUEST->AddHeader("Content-Type: application/x-www-form-urlencoded");

    $REQUEST->SendRequest("key1=value1&key2=value2&key3=value3");

APPENDIX

Microsoft Win32 Internet Functions

Complete documentation for the Microsoft Win32 Internet Functions can be found, in both HTML and zipped Word format, at this address:

    http://www.microsoft.com/intdev/sdk/docs/wininet/

Functions Table

This table reports the correspondence between the functions offered by WININET.DLL and their implementation in the Win32::Internet extension. Functions showing a "---" are not currently implemented. Functions enclosed in parens ( ) aren't implemented straightforwardly, but in a higher-level routine, eg. together with other functions.

    WININET.DLL                     Win32::Internet
    InternetOpen                    new Win32::Internet
    InternetConnect                 FTP / HTTP
    InternetCloseHandle             Close
    InternetQueryOption             QueryOption
    InternetSetOption               SetOption
    InternetSetOptionEx             ---
    InternetSetStatusCallback       SetStatusCallback
    InternetStatusCallback          GetStatusCallback
    InternetConfirmZoneCrossing     ---
    InternetTimeFromSystemTime      TimeConvert
    InternetTimeToSystemTime        TimeConvert
    InternetAttemptConnect          ---
    InternetReadFile                ReadFile
    InternetSetFilePointer          ---
    InternetFindNextFile            (List)
    InternetQueryDataAvailable      QueryDataAvailable
    InternetGetLastResponseInfo     GetResponse
    InternetWriteFile               ---
    InternetCrackUrl                CrackURL
    InternetCreateUrl               CreateURL
    InternetCanonicalizeUrl         CanonicalizeURL
    InternetCombineUrl              CombineURL
    InternetOpenUrl                 OpenURL
    FtpFindFirstFile                (List)
    FtpGetFile                      Get
    FtpPutFile                      Put
    FtpDeleteFile                   Delete
    FtpRenameFile                   Rename
    FtpOpenFile                     ---
    FtpCreateDirectory              Mkdir
    FtpRemoveDirectory              Rmdir
    FtpSetCurrentDirectory          Cd
    FtpGetCurrentDirectory          Pwd
    HttpOpenRequest                 OpenRequest
    HttpAddRequestHeaders           AddHeader
    HttpSendRequest                 SendRequest
    HttpQueryInfo                   QueryInfo
    InternetErrorDlg                ---

Actually, I don't plan to add support for Gopher, Cookie and Cache functions. I will if there will be consistent requests to do so.

There are a number of higher-level functions in the Win32::Internet that simplify some usual procedures, calling more that one WININET API function. This table reports those functions and the relative WININET functions they use.

    Win32::Internet                 WININET.DLL
    FetchURL                        InternetOpenUrl
                                    InternetQueryDataAvailable
                                    InternetReadFile
                                    InternetCloseHandle
    ReadEntireFile                  InternetQueryDataAvailable
                                    InternetReadFile
    Request                         HttpOpenRequest
                                    HttpSendRequest
                                    HttpQueryInfo
                                    InternetQueryDataAvailable
                                    InternetReadFile
                                    InternetCloseHandle
    List                            FtpFindFirstFile
                                    InternetFindNextFile

Constants

Those are the constants exported by the package in the main namespace (eg. you can use them in your scripts); for their meaning and proper use, refer to the Microsoft Win32 Internet Functions document.

    HTTP_ADDREQ_FLAG_ADD
    HTTP_ADDREQ_FLAG_REPLACE
    HTTP_QUERY_ALLOW
    HTTP_QUERY_CONTENT_DESCRIPTION
    HTTP_QUERY_CONTENT_ID
    HTTP_QUERY_CONTENT_LENGTH
    HTTP_QUERY_CONTENT_TRANSFER_ENCODING
    HTTP_QUERY_CONTENT_TYPE
    HTTP_QUERY_COST
    HTTP_QUERY_CUSTOM
    HTTP_QUERY_DATE
    HTTP_QUERY_DERIVED_FROM
    HTTP_QUERY_EXPIRES
    HTTP_QUERY_FLAG_REQUEST_HEADERS
    HTTP_QUERY_FLAG_SYSTEMTIME
    HTTP_QUERY_LANGUAGE
    HTTP_QUERY_LAST_MODIFIED
    HTTP_QUERY_MESSAGE_ID
    HTTP_QUERY_MIME_VERSION
    HTTP_QUERY_PRAGMA
    HTTP_QUERY_PUBLIC
    HTTP_QUERY_RAW_HEADERS
    HTTP_QUERY_RAW_HEADERS_CRLF
    HTTP_QUERY_REQUEST_METHOD
    HTTP_QUERY_SERVER
    HTTP_QUERY_STATUS_CODE
    HTTP_QUERY_STATUS_TEXT
    HTTP_QUERY_URI
    HTTP_QUERY_USER_AGENT
    HTTP_QUERY_VERSION
    HTTP_QUERY_WWW_LINK
    ICU_BROWSER_MODE
    ICU_DECODE
    ICU_ENCODE_SPACES_ONLY
    ICU_ESCAPE
    ICU_NO_ENCODE
    ICU_NO_META
    ICU_USERNAME
    INTERNET_FLAG_PASSIVE
    INTERNET_FLAG_ASYNC
    INTERNET_FLAG_HYPERLINK
    INTERNET_FLAG_KEEP_CONNECTION
    INTERNET_FLAG_MAKE_PERSISTENT
    INTERNET_FLAG_NO_AUTH
    INTERNET_FLAG_NO_AUTO_REDIRECT
    INTERNET_FLAG_NO_CACHE_WRITE
    INTERNET_FLAG_NO_COOKIES
    INTERNET_FLAG_READ_PREFETCH
    INTERNET_FLAG_RELOAD
    INTERNET_FLAG_RESYNCHRONIZE
    INTERNET_FLAG_TRANSFER_ASCII
    INTERNET_FLAG_TRANSFER_BINARY
    INTERNET_INVALID_PORT_NUMBER
    INTERNET_INVALID_STATUS_CALLBACK
    INTERNET_OPEN_TYPE_DIRECT
    INTERNET_OPEN_TYPE_PROXY
    INTERNET_OPEN_TYPE_PROXY_PRECONFIG
    INTERNET_OPTION_CONNECT_BACKOFF
    INTERNET_OPTION_CONNECT_RETRIES
    INTERNET_OPTION_CONNECT_TIMEOUT
    INTERNET_OPTION_CONTROL_SEND_TIMEOUT
    INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
    INTERNET_OPTION_DATA_SEND_TIMEOUT
    INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
    INTERNET_OPTION_HANDLE_TYPE
    INTERNET_OPTION_LISTEN_TIMEOUT
    INTERNET_OPTION_PASSWORD
    INTERNET_OPTION_READ_BUFFER_SIZE
    INTERNET_OPTION_USER_AGENT
    INTERNET_OPTION_USERNAME
    INTERNET_OPTION_VERSION
    INTERNET_OPTION_WRITE_BUFFER_SIZE
    INTERNET_SERVICE_FTP
    INTERNET_SERVICE_GOPHER
    INTERNET_SERVICE_HTTP
    INTERNET_STATUS_CLOSING_CONNECTION
    INTERNET_STATUS_CONNECTED_TO_SERVER
    INTERNET_STATUS_CONNECTING_TO_SERVER
    INTERNET_STATUS_CONNECTION_CLOSED
    INTERNET_STATUS_HANDLE_CLOSING
    INTERNET_STATUS_HANDLE_CREATED
    INTERNET_STATUS_NAME_RESOLVED
    INTERNET_STATUS_RECEIVING_RESPONSE
    INTERNET_STATUS_REDIRECT
    INTERNET_STATUS_REQUEST_COMPLETE
    INTERNET_STATUS_REQUEST_SENT
    INTERNET_STATUS_RESOLVING_NAME
    INTERNET_STATUS_RESPONSE_RECEIVED
    INTERNET_STATUS_SENDING_REQUEST

VERSION HISTORY

  • 0.082 (4 Sep 2001)

    • Fix passive FTP mode. INTERNET_FLAG_PASSIVE was misspelled in earlier versions (as INTERNET_CONNECT_FLAG_PASSIVE) and wouldn't work. Found by Steve Raynesford <stever@evolvecomm.com>.

  • 0.081 (25 Sep 1999)

    • Documentation converted to pod format by Jan Dubois <JanD@ActiveState.com>.

    • Minor changes from Perl 5.005xx compatibility.

  • 0.08 (14 Feb 1997)

    • fixed 2 more bugs in Option(s) related subs (thanks to Brian Helterline!).

    • Error() now gets error messages directly from WININET.DLL.

    • The PLL file now comes in 2 versions, one for Perl version 5.001 (build 100) and one for Perl version 5.003 (build 300 and higher). Everybody should be happy now :)

    • added an installation program.

  • 0.07 (10 Feb 1997)

    • fixed a bug in Version() introduced with 0.06...

    • completely reworked PM file, fixed *lots* of minor bugs, and removed almost all the warnings with "perl -w".

  • 0.06 (26 Jan 1997)

    • fixed another hideous bug in "new" (the 'class' parameter was still missing).

    • added support for asynchronous operations (work still in embryo).

    • removed the ending \0 (ASCII zero) from the DLL version returned by "Version".

    • added a lot of constants.

    • added safefree() after every safemalloc() in C... wonder why I didn't it before :)

    • added TimeConvert, which actually works one way only.

  • 0.05f (29 Nov 1996)

    • fixed a bug in "new" (parameters passed were simply ignored).

    • fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR instead of CD..

  • 0.05 (29 Nov 1996)

    • added "CrackURL" and "CreateURL".

    • corrected an error in TEST.PL (there was a GetUserAgent instead of UserAgent).

  • 0.04 (25 Nov 1996)

    • added "Version" to retrieve package and DLL versions.

    • added proxies and other options to "new".

    • changed "OpenRequest" and "Request" to read parameters from a hash.

    • added "SetOption/QueryOption" and a lot of relative functions (connect, username, password, useragent, etc.).

    • added "CanonicalizeURL" and "CombineURL".

    • "Error" covers a wider spectrum of errors.

  • 0.02 (18 Nov 1996)

    • added support for HTTP sessions and requests.

  • 0.01 (11 Nov 1996)

    • fetching of HTTP, FTP and GOPHER URLs.

    • complete set of commands to manage an FTP session.

AUTHOR

Version 0.08 (14 Feb 1997) by Aldo Calpini <a.calpini@romagiubileo.it>

CREDITS

Win32::Internet is based on the Win32::Registry code written by Jesse Dougherty.

Additional thanks to: Carl Tichler for his help in the initial development; Tore Haraldsen, Brian Helterline for the bugfixes; Dave Roth for his great source code examples.

DISCLAIMER

This program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsability for any damage, loss of money and/or health that may arise from the use of this program!

This is distributed under the terms of Larry Wall's Artistic License.


Win32::Job - Run sub-processes in a "job" environment

  • PLATFORMS
  • DESCRIPTION
  • Using Win32::Job
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

Win32::Job - Run sub-processes in a "job" environment

SYNOPSIS

   use Win32::Job;

   my $job = Win32::Job->new;

   # Run 'perl Makefile.PL' for 10 seconds
   $job->spawn($Config{perlpath}, "perl Makefile.PL");
   $job->run(10);

PLATFORMS

Win32::Job requires Windows 2000 or later. Windows 95, 98, NT, and Me are not supported.

DESCRIPTION

Windows 2000 introduced the concept of a "job": a collection of processes which can be controlled as a single unit. For example, you can reliably kill a process and all of its children by launching the process in a job, then telling Windows to kill all processes in the job. Win32::Job makes this feature available to Perl.

For example, imagine you want to allow 2 minutes for a process to complete. If you have control over the child process, you can probably just run it in the background, then poll every second to see if it has finished.

That's fine as long as the child process doesn't spawn any child processes. What if it does? If you wrote the child process yourself and made an effort to clean up your child processes before terminating, you don't have to worry. If not, you will leave hanging processes (called "zombie" processes in Unix).

With Win32::Job, just create a new Job, then use the job to spawn the child process. All its children will also be created in the new Job. When you time out, just call the job's kill() method and the entire process tree will be terminated.

Using Win32::Job

The following methods are available:

  1. new()

       new();

    Creates a new Job object using the Win32 API call CreateJobObject(). The job is created with a default security context, and is unnamed.

    Note: this method returns undef if CreateJobObject() fails. Look at $^E for more detailed error information.

  2. spawn()

       spawn($exe, $args, \%opts);

    Creates a new process and associates it with the Job. The process is initially suspended, and can be resumed with one of the other methods. Uses the Win32 API call CreateProcess(). Returns the PID of the newly created process.

    Note: this method returns undef if CreateProcess() fails. See $^E for more detailed error information. One reason this will fail is if the calling process is itself part of a job, and the job's security context does not allow child processes to be created in a different job context than the parent.

    The arguments are described here:

    1. $exe

      The executable program to run. This may be undef, in which case the first argument in $args is the program to run.

      If this has path information in it, it is used "as is" and passed to CreateProcess(), which interprets it as either an absolute path, or a path relative to the current drive and directory. If you did not specify an extension, ".exe" is assumed.

      If there are no path separators (either backslashes or forward slashes), then Win32::Job will search the current directory and your PATH, looking for the file. In addition, if you did not specify an extension, then Win32::Job checks ".exe", ".com", and ".bat" in order. If it finds a ".bat" file, Win32::Job will actually call cmd.exe and prepend "cmd.exe" to the $args.

      For example, assuming a fairly normal PATH:

         spawn(q{c:\winnt\system\cmd.exe}, q{cmd /C "echo %PATH%"})
   exefile: c:\winnt\system\cmd.exe
   cmdline: cmd /C "echo %PATH%"

         spawn("cmd.exe", q{cmd /C "echo %PATH%"})
   exefile: c:\winnt\system\cmd.exe
   cmdline: cmd /C "echo %PATH%"

    2. $args

      The commandline to pass to the executable program. The first word will be argv[0] to an EXE file, so you should repeat the command name in $args.

      For example:

         $job->spawn($Config{perlpath}, "perl foo.pl");

      In this case, the "perl" is ignored, since perl.exe doesn't use it.

    3. %opts

      A hash reference for advanced options. This parameter is optional. the following keys are recognized:

      cwd

      A string specifying the current directory of the new process.

      By default, the process shares the parent's current directory, ..

      4. new_console

      A boolean; if true, the process is started in a new console window.

      By default, the process shares the parent's console. This has no effect on GUI programs which do not interact with the console.

      window_attr

      Either minimized, which displays the new window minimized; maximimzed, which shows the new window maximized; or hidden, which does not display the new window.

      By default, the window is displayed using its application's defaults.

      new_group

      A boolean; if true, the process is the root of a new process group. This process group includes all descendents of the child.

      By default, the process is in the parent's process group (but in a new job).

      no_window

      A boolean; if true, the process is run without a console window. This flag is only valid when starting a console application, otherwise it is ignored. If you are launching a GUI application, use the window_attr tag instead.

      By default, the process shares its parent's console.

      stdin

      An open input filehandle, or the name of an existing file. The resulting filehandle will be used for the child's standard input handle.

      By default, the child process shares the parent's standard input.

      stdout

      An open output filehandle or filename (will be opened for append). The resulting filehandle will be used for the child's standard output handle.

      By default, the child process shares the parent's standard output.

      stderr

      An open output filehandle or filename (will be opened for append). The resulting filehandle will be used for the child's standard error handle.

      By default, the child process shares the parent's standard error.

      Unrecognized keys are ignored.

  3. run()

       run($timeout, $which);

    Provides a simple way to run the programs with a time limit. The $timeout is in seconds with millisecond accuracy. This call blocks for up to $timeout seconds, or until the processes finish.

    The $which parameter specifies whether to wait for all processes to complete within the $timeout, or whether to wait for any process to complete. You should set this to a boolean, where a true value means to wait for all the processes to complete, and a false value to wait for any. If you do not specify $which, it defaults to true (all).

    Returns a boolean indicating whether the processes exited by themselves, or whether the time expired. A true return value means the processes exited normally; a false value means one or more processes was killed will $timeout.

    You can get extended information on process exit codes using the status() method.

    For example, this is how to build two perl modules at the same time, with a 5 minute timeout:

       use Win32::Job;
   $job = Win32::Job->new;
   $job->spawn("cmd", q{cmd /C "cd Mod1 && nmake"});
   $job->spawn("cmd", q{cmd /C "cd Mod2 && nmake"});
   $ok = $job->run(5 * 60);
   print "Mod1 and Mod2 built ok!\n" if $ok;

  4. watch()

       watch(\&handler, $interval, $which);

       handler($job);

    Provides more fine-grained control over how to stop the programs. You specify a callback and an interval in seconds, and Win32::Job will call the "watchdog" function at this interval, either until the processes finish or your watchdog tells Win32::Job to stop. You must return a value indicating whether to stop: a true value means to terminate the processes immediately.

    The $which parameter has the same meaning as run()'s.

    Returns a boolean with the same meaning as run()'s.

    The handler may do anything it wants. One useful application of the watch() method is to check the filesize of the output file, and terminate the Job if the file becomes larger than a certain limit:

       use Win32::Job;
   $job = Win32::Job->new;
   $job->spawn("cmd", q{cmd /C "cd Mod1 && nmake"}, {
       stdin  => 'NUL', # the NUL device
       stdout => 'stdout.log',
       stderr => 'stdout.log',
   });
   $ok = $job->watch(sub {
       return 1 if -s "stdout.log" > 1_000_000;
   }, 1);
   print "Mod1 built ok!\n" if $ok;

  5. status()

       status()

    Returns a hash containing information about the processes in the job. Only returns valid information after calling either run() or watch(); returns an empty hash if you have not yet called them. May be called from a watch() callback, in which case the exitcode field should be ignored.

    The keys of the hash are the process IDs; the values are a subhash containing the following keys:

    exitcode

    The exit code returned by the process. If the process was killed because of a timeout, the value is 293.

    6. time

    The time accumulated by the process. This is yet another subhash containing the subkeys (i) user, the amount of time the process spent in user space; (ii) kernel, the amount of time the process spent in kernel space; and (iii) elapsed, the total time the process was running.

  6. kill()

       kill();

    Kills all processes and subprocesses in the Job. Has no return value. Sets the exit code to all processes killed to 293, which you can check for in the status() return value.

SEE ALSO

For more information about jobs, see Microsoft's online help at

   http://msdn.microsoft.com/

For other modules which do similar things (but not as well), see:

  1. Win32::Process

    Low-level access to creating processes in Win32. See the Win32::Process manpage.

  2. Win32::Console

    Low-level access to consoles in Win32. See the Win32::Console manpage.

  3. Win32::ProcFarm

    Manage pools of threads to perform CPU-intensive tasks on Windows. See the Win32::ProcFarm manpage.

AUTHOR

ActiveState (support@ActiveState.com)

COPYRIGHT

Copyright (c) 2002, ActiveState Corporation. All Rights Reserved.


Win32::Mutex - Use Win32 mutex objects from Perl

    • Methods
    • Deprecated Functions and Methods
  • AUTHOR

NAME

Win32::Mutex - Use Win32 mutex objects from Perl

SYNOPSIS

        require Win32::Mutex;

        $mutex = Win32::Mutex->new($initial,$name);
        $mutex->wait;

DESCRIPTION

This module allows access to the Win32 mutex objects. The wait method and wait_all & wait_any functions are inherited from the Win32::IPC module.

Methods

$mutex = Win32::Mutex->new([$initial, [$name]])

Constructor for a new mutex object. If $initial is true, requests immediate ownership of the mutex (default false). If $name is omitted, creates an unnamed mutex object.

If $name signifies an existing mutex object, then $initial is ignored and the object is opened. If this happens, $^E will be set to 183 (ERROR_ALREADY_EXISTS).

$mutex = Win32::Mutex->open($name)

Constructor for opening an existing mutex object.

$mutex->release

Release ownership of a $mutex. You should have obtained ownership of the mutex through new or one of the wait functions. Returns true if successful.

$mutex->wait([$timeout])

Wait for ownership of $mutex. See Win32::IPC.

Deprecated Functions and Methods

Win32::Mutex still supports the ActiveWare syntax, but its use is deprecated.

Create($MutObj,$Initial,$Name)

Use $MutObj = Win32::Mutex->new($Initial,$Name) instead.

Open($MutObj,$Name)

Use $MutObj = Win32::Mutex->open($Name) instead.

$MutObj->Release()

Use $MutObj->release instead.

AUTHOR

Christopher J. Madsen <cjm@pobox.com>

Loosely based on the original module by ActiveWare Internet Corp., http://www.ActiveWare.com


Win32::NetAdmin - manage network groups and users in perl

  • FUNCTIONS
    • NOTE
  • EXAMPLE

NAME

Win32::NetAdmin - manage network groups and users in perl

SYNOPSIS

        use Win32::NetAdmin;

DESCRIPTION

This module offers control over the administration of groups and users over a network.

FUNCTIONS

NOTE

All of the functions return false if they fail, unless otherwise noted. When a function fails call Win32::NetAdmin::GetError() rather than GetLastError() or $^E to retrieve the error code.

server is optional for all the calls below. If not given the local machine is assumed.

GetError()

Returns the error code of the last call to this module.

GetDomainController(server, domain, returnedName)

Returns the name of the domain controller for server.

GetAnyDomainController(server, domain, returnedName)

Returns the name of any domain controller for a domain that is directly trusted by the server.

UserCreate(server, userName, password, passwordAge, privilege, homeDir, comment, flags, scriptPath)

Creates a user on server with password, passwordAge, privilege, homeDir, comment, flags, and scriptPath.

UserDelete(server, user)

Deletes a user from server.

UserGetAttributes(server, userName, password, passwordAge, privilege, homeDir, comment, flags, scriptPath)

Gets password, passwordAge, privilege, homeDir, comment, flags, and scriptPath for user.

UserSetAttributes(server, userName, password, passwordAge, privilege, homeDir, comment, flags, scriptPath)

Sets password, passwordAge, privilege, homeDir, comment, flags, and scriptPath for user.

UserChangePassword(domainname, username, oldpassword, newpassword)

Changes a users password. Can be run under any account.

UsersExist(server, userName)

Checks if a user exists.

GetUsers(server, filter, userRef)

Fills userRef with user names if it is an array reference and with the user names and the full names if it is a hash reference.

GroupCreate(server, group, comment)

Creates a group.

GroupDelete(server, group)

Deletes a group.

GroupGetAttributes(server, groupName, comment)

Gets the comment.

GroupSetAttributes(server, groupName, comment)

Sets the comment.

GroupAddUsers(server, groupName, users)

Adds a user to a group.

GroupDeleteUsers(server, groupName, users)

Deletes a users from a group.

GroupIsMember(server, groupName, user)

Returns TRUE if user is a member of groupName.

GroupGetMembers(server, groupName, userArrayRef)

Fills userArrayRef with the members of groupName.

LocalGroupCreate(server, group, comment)

Creates a local group.

LocalGroupDelete(server, group)

Deletes a local group.

LocalGroupGetAttributes(server, groupName, comment)

Gets the comment.

LocalGroupSetAttributes(server, groupName, comment)

Sets the comment.

LocalGroupIsMember(server, groupName, user)

Returns TRUE if user is a member of groupName.

LocalGroupGetMembers(server, groupName, userArrayRef)

Fills userArrayRef with the members of groupName.

LocalGroupGetMembersWithDomain(server, groupName, userRef)

This function is similar LocalGroupGetMembers but accepts an array or a hash reference. Unlike LocalGroupGetMembers it returns each user name as DOMAIN\USERNAME. If a hash reference is given, the function returns to each user or group name the type (group, user, alias etc.). The possible types are as follows:

  $SidTypeUser = 1;
  $SidTypeGroup = 2;
  $SidTypeDomain = 3;
  $SidTypeAlias = 4;
  $SidTypeWellKnownGroup = 5;
  $SidTypeDeletedAccount = 6;
  $SidTypeInvalid = 7;
  $SidTypeUnknown = 8;
LocalGroupAddUsers(server, groupName, users)

Adds a user to a group.

LocalGroupDeleteUsers(server, groupName, users)

Deletes a users from a group.

GetServers(server, domain, flags, serverRef)

Gets an array of server names or an hash with the server names and the comments as seen in the Network Neighborhood or the server manager. For flags, see SV_TYPE_* constants.

GetTransports(server, transportRef)

Enumerates the network transports of a computer. If transportRef is an array reference, it is filled with the transport names. If transportRef is a hash reference then a hash of hashes is filled with the data for the transports.

LoggedOnUsers(server, userRef)

Gets an array or hash with the users logged on at the specified computer. If userRef is a hash reference, the value is a semikolon separated string of username, logon domain and logon server.

GetAliasFromRID(server, RID, returnedName)
GetUserGroupFromRID(server, RID, returnedName)

Retrieves the name of an alias (i.e local group) or a user group for a RID from the specified server. These functions can be used for example to get the account name for the administrator account if it is renamed or localized.

Possible values for RID:

  DOMAIN_ALIAS_RID_ACCOUNT_OPS
  DOMAIN_ALIAS_RID_ADMINS
  DOMAIN_ALIAS_RID_BACKUP_OPS
  DOMAIN_ALIAS_RID_GUESTS
  DOMAIN_ALIAS_RID_POWER_USERS
  DOMAIN_ALIAS_RID_PRINT_OPS
  DOMAIN_ALIAS_RID_REPLICATOR
  DOMAIN_ALIAS_RID_SYSTEM_OPS
  DOMAIN_ALIAS_RID_USERS
  DOMAIN_GROUP_RID_ADMINS
  DOMAIN_GROUP_RID_GUESTS
  DOMAIN_GROUP_RID_USERS
  DOMAIN_USER_RID_ADMIN
  DOMAIN_USER_RID_GUEST
GetServerDisks(server, arrayRef)

Returns an array with the disk drives of the specified server. The array contains two-character strings (drive letter followed by a colon).

EXAMPLE

    # Simple script using Win32::NetAdmin to set the login script for
    # all members of the NT group "Domain Users".  Only works if you
    # run it on the PDC. (From Robert Spier <rspier@seas.upenn.edu>)
    #
    # FILTER_TEMP_DUPLICATE_ACCOUNTS
    #   Enumerates local user account data on a domain controller.
    #
    # FILTER_NORMAL_ACCOUNT
    #   Enumerates global user account data on a computer.
    #
    # FILTER_INTERDOMAIN_TRUST_ACCOUNT
    #   Enumerates domain trust account data on a domain controller.
    #
    # FILTER_WORKSTATION_TRUST_ACCOUNT
    #   Enumerates workstation or member server account data on a domain
    #   controller.
    #
    # FILTER_SERVER_TRUST_ACCOUNT
    #   Enumerates domain controller account data on a domain controller.

    use Win32::NetAdmin qw(GetUsers GroupIsMember
                           UserGetAttributes UserSetAttributes);

    my %hash;
    GetUsers("", FILTER_NORMAL_ACCOUNT , \%hash)
        or die "GetUsers() failed: $^E";

    foreach (keys %hash) {
        my ($password, $passwordAge, $privilege,
            $homeDir, $comment, $flags, $scriptPath);
        if (GroupIsMember("", "Domain Users", $_)) {
            print "Updating $_ ($hash{$_})\n";
            UserGetAttributes("", $_, $password, $passwordAge, $privilege,
                              $homeDir, $comment, $flags, $scriptPath)
                or die "UserGetAttributes() failed: $^E";
            $scriptPath = "dnx_login.bat"; # this is the new login script
            UserSetAttributes("", $_, $password, $passwordAge, $privilege,
                              $homeDir, $comment, $flags, $scriptPath)
                or die "UserSetAttributes() failed: $^E";
        }
    }


Win32::NetResource - manage network resources in perl

  • DATA TYPES
  • FUNCTIONS
    • NOTE
    • NOTE
  • EXAMPLE
  • AUTHOR

NAME

Win32::NetResource - manage network resources in perl

SYNOPSIS

    use Win32::NetResource;

    $ShareInfo = {
                    'path' => "C:\\MyShareDir",
                    'netname' => "MyShare",
                    'remark' => "It is good to share",
                    'passwd' => "",
                    'current-users' =>0,
                    'permissions' => 0,
                    'maxusers' => -1,
                    'type'  => 0,
                    };

    Win32::NetResource::NetShareAdd( $ShareInfo,$parm )
        or die "unable to add share";

DESCRIPTION

This module offers control over the network resources of Win32.Disks, printers etc can be shared over a network.

DATA TYPES

There are two main data types required to control network resources. In Perl these are represented by hash types.

%NETRESOURCE
    KEY                    VALUE

    'Scope'         =>  Scope of an Enumeration
                        RESOURCE_CONNECTED,
                        RESOURCE_GLOBALNET,
                        RESOURCE_REMEMBERED.

    'Type'          =>  The type of resource to Enum
                        RESOURCETYPE_ANY    All resources
                        RESOURCETYPE_DISK    Disk resources
                        RESOURCETYPE_PRINT    Print resources

    'DisplayType'   =>  The way the resource should be displayed.
                        RESOURCEDISPLAYTYPE_DOMAIN
                        The object should be displayed as a domain.
                        RESOURCEDISPLAYTYPE_GENERIC
                        The method used to display the object does not matter.
                        RESOURCEDISPLAYTYPE_SERVER
                        The object should be displayed as a server.
                        RESOURCEDISPLAYTYPE_SHARE
                        The object should be displayed as a sharepoint.

    'Usage'         =>  Specifies the Resources usage:
                        RESOURCEUSAGE_CONNECTABLE
                        RESOURCEUSAGE_CONTAINER.

    'LocalName'     =>  Name of the local device the resource is
                        connected to.

    'RemoteName'    =>  The network name of the resource.

    'Comment'       =>  A string comment.

    'Provider'      =>  Name of the provider of the resource.
%SHARE_INFO

This hash represents the SHARE_INFO_502 struct.

    KEY                    VALUE
    'netname'        =>    Name of the share.
    'type'           =>    type of share.
    'remark'         =>    A string comment.
    'permissions'    =>    Permissions value
    'maxusers'       =>    the max # of users.
    'current-users'  =>    the current # of users.
    'path'           =>    The path of the share.
    'passwd'         =>    A password if one is req'd

FUNCTIONS

NOTE

All of the functions return false if they fail.

GetSharedResources(\@Resources,dwType,\%NetResource = NULL)

Creates a list in @Resources of %NETRESOURCE hash references.

The return value indicates whether there was an error in accessing any of the shared resources. All the shared resources that were encountered (until the point of an error, if any) are pushed into @Resources as references to %NETRESOURCE hashes. See example below. The \%NetResource argument is optional. If it is not supplied, the root (that is, the topmost container) of the network is assumed, and all network resources available from the toplevel container will be enumerated.

AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)

Makes a connection to a network resource specified by %NETRESOURCE

CancelConnection($Name,$Connection,$Force)

Cancels a connection to a network resource connected to local device $name.$Connection is either 1 - persistent connection or 0, non-persistent.

WNetGetLastError($ErrorCode,$Description,$Name)

Gets the Extended Network Error.

GetError( $ErrorCode )

Gets the last Error for a Win32::NetResource call.

GetUNCName( $UNCName, $LocalPath );

Returns the UNC name of the disk share connected to $LocalPath in $UNCName. $LocalPath should be a drive based path. e.g. "C:\\share\\subdir"

NOTE

$servername is optional for all the calls below. (if not given the local machine is assumed.)

NetShareAdd(\%SHARE,$parm_err,$servername = NULL )

Add a share for sharing.

NetShareCheck($device,$type,$servername = NULL )

Check if a directory or a device is available for connection from the network through a share. This includes all directories that are reachable through a shared directory or device, meaning that if C:\foo is shared, C:\foo\bar is also available for sharing. This means that this function is pretty useless, given that by default every disk volume has an administrative share such as "C$" associated with its root directory.

$device must be a drive name, directory, or a device. For example, "C:", "C:\dir", "LPT1", "D$", "IPC$" are all valid as the $device argument. $type is an output argument that will be set to one of the following constants that describe the type of share:

    STYPE_DISKTREE     Disk drive
    STYPE_PRINTQ       Print queue
    STYPE_DEVICE       Communication device
    STYPE_IPC          Interprocess communication (IPC)
    STYPE_SPECIAL      Special share reserved for interprocess
                         communication (IPC$) or remote administration
                         of the server (ADMIN$). Can also refer to
                         administrative shares such as C$, D$, etc.
NetShareDel( $netname, $servername = NULL )

Remove a share from a machines list of shares.

NetShareGetInfo( $netname, \%SHARE,$servername=NULL )

Get the %SHARE_INFO information about the share $netname on the server $servername.

NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)

Set the information for share $netname.

EXAMPLE

Enumerating all resources on the network
    #
    # This example displays all the share points in the entire
    # visible part of the network.
    #

    use strict;
    use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
    my $resources = [];
    unless(GetSharedResources($resources, RESOURCETYPE_ANY)) {
        my $err;
        GetError($err);
        warn Win32::FormatMessage($err);
    }

    foreach my $href (@$resources) {
        next if ($$href{DisplayType} != RESOURCEDISPLAYTYPE_SHARE);
        print "-----\n";
        foreach( keys %$href){
            print "$_: $href->{$_}\n";
        }
    }
Enumerating all resources on a particular host
    #
    # This example displays all the share points exported by the local
    # host.
    #

    use strict;
    use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
    if (GetSharedResources(my $resources, RESOURCETYPE_ANY,
                           { RemoteName => "\\\\" . Win32::NodeName() }))
    {
        foreach my $href (@$resources) {
            print "-----\n";
            foreach(keys %$href) { print "$_: $href->{$_}\n"; }
        }
    }

AUTHOR

Jesse Dougherty for Hip Communications.

Additional general cleanups and bug fixes by Gurusamy Sarathy <gsar@activestate.com>.


Win32::ODBC - ODBC Extension for Win32

    • Background
    • Benefits
  • CONSTANTS
  • SPECIAL NOTATION
  • CONSTRUCTOR
  • METHODS
  • LIMITATIONS
  • INSTALLATION NOTES
  • OTHER DOCUMENTATION
  • AUTHOR
  • CREDITS
  • DISCLAIMER
  • HISTORY
  • COPYRIGHT

NAME

Win32::ODBC - ODBC Extension for Win32

SYNOPSIS

To use this module, include the following statement at the top of your script:

    use Win32::ODBC;

Next, create a data connection to your DSN:

    $Data = new Win32::ODBC("MyDSN");

NOTE: MyDSN can be either the DSN as defined in the ODBC Administrator, or it can be an honest-to-God DSN Connect String.

    Example: "DSN=My Database;UID=Brown Cow;PWD=Moo;"

You should check to see if $Data is indeed defined, otherwise there has been an error.

You can now send SQL queries and retrieve info to your heart's content! See the description of the methods provided by this module below and also the file TEST.PL as referred to in INSTALLATION NOTES to see how it all works.

Finally, MAKE SURE that you close your connection when you are finished:

    $Data->Close();

DESCRIPTION

Background

This is a hack of Dan DeMaggio's <dmag@umich.edu> NTXS.C ODBC implementation. I have recoded and restructured most of it including most of the ODBC.PM package, but its very core is still based on Dan's code (thanks Dan!).

The history of this extension is found in the file HISTORY.TXT that comes with the original archive (see INSTALLATION NOTES below).

Benefits

And what are the benefits of this module?

  • The number of ODBC connections is limited by memory and ODBC itself (have as many as you want!).

  • The working limit for the size of a field is 10,240 bytes, but you can increase that limit (if needed) to a max of 2,147,483,647 bytes. (You can always recompile to increase the max limit.)

  • You can open a connection by either specifing a DSN or a connection string!

  • You can open and close the connections in any order!

  • Other things that I can not think of right now... :)

CONSTANTS

This package defines a number of constants. You may refer to each of these constants using the notation ODBC::xxxxx, where xxxxx is the constant.

Example:

   print ODBC::SQL_SQL_COLUMN_NAME, "\n";

SPECIAL NOTATION

For the method documentation that follows, an * following the method parameters indicates that that method is new or has been modified for this version.

CONSTRUCTOR

new ( ODBC_OBJECT | DSN [, (OPTION1, VALUE1), (OPTION2, VALUE2) ...] ) *

Creates a new ODBC connection based on DSN, or, if you specify an already existing ODBC object, then a new ODBC object will be created but using the ODBC Connection specified by ODBC_OBJECT. (The new object will be a new hstmt using the hdbc connection in ODBC_OBJECT.)

DSN is Data Source Name or a proper ODBCDriverConnect string.

You can specify SQL Connect Options that are implemented before the actual connection to the DSN takes place. These option/values are the same as specified in GetConnectOption/SetConnectOption (see below) and are defined in the ODBC API specs.

Returns a handle to the database on success, or undef on failure.

METHODS

Catalog ( QUALIFIER, OWNER, NAME, TYPE )

Tells ODBC to create a data set that contains table information about the DSN. Use Fetch and Data or DataHash to retrieve the data. The returned format is:

    [Qualifier] [Owner] [Name] [Type]

Returns true on error.

ColAttributes ( ATTRIBUTE [, FIELD_NAMES ] )

Returns the attribute ATTRIBUTE on each of the fields in the list FIELD_NAMES in the current record set. If FIELD_NAMES is empty, then all fields are assumed. The attributes are returned as an associative array.

ConfigDSN ( OPTION, DRIVER, ATTRIBUTE1 [, ATTRIBUTE2, ATTRIBUTE3, ... ] )

Configures a DSN. OPTION takes on one of the following values:

    ODBC_ADD_DSN.......Adds a new DSN.
    ODBC_MODIFY_DSN....Modifies an existing DSN.
    ODBC_REMOVE_DSN....Removes an existing DSN.
    ODBC_ADD_SYS_DSN.......Adds a new System DSN.
    ODBC_MODIFY_SYS_DSN....Modifies an existing System DSN.
    ODBC_REMOVE_SYS_DSN....Removes an existing System DSN.

You must specify the driver DRIVER (which can be retrieved by using DataSources or Drivers).

ATTRIBUTE1 should be "DSN=xxx" where xxx is the name of the DSN. Other attributes can be any DSN attribute such as:

    "UID=Cow"
    "PWD=Moo"
    "Description=My little bitty Data Source Name"

Returns true on success, false on failure.

NOTE 1: If you use ODBC_ADD_DSN, then you must include at least "DSN=xxx" and the location of the database.

Example: For MS Access databases, you must specify the DatabaseQualifier:

    "DBQ=c:\\...\\MyDatabase.mdb"

NOTE 2: If you use ODBC_MODIFY_DSN, then you need only specify the "DNS=xxx" attribute. Any other attribute you include will be changed to what you specify.

NOTE 3: If you use ODBC_REMOVE_DSN, then you need only specify the "DSN=xxx" attribute.

Connection ()

Returns the connection number associated with the ODBC connection.

Close ()

Closes the ODBC connection. No return value.

Data ( [ FIELD_NAME ] )

Returns the contents of column name FIELD_NAME or the current row (if nothing is specified).

DataHash ( [ FIELD1, FIELD2, ... ] )

Returns the contents for FIELD1, FIELD2, ... or the entire row (if nothing is specified) as an associative array consisting of:

    {Field Name} => Field Data
DataSources ()

Returns an associative array of Data Sources and ODBC remarks about them. They are returned in the form of:

    $ArrayName{'DSN'}=Driver

where DSN is the Data Source Name and ODBC Driver used.

Debug ( [ 1 | 0 ] )

Sets the debug option to on or off. If nothing is specified, then nothing is changed.

Returns the debugging value (1 or 0).

Drivers ()

Returns an associative array of ODBC Drivers and their attributes. They are returned in the form of:

    $ArrayName{'DRIVER'}=Attrib1;Attrib2;Attrib3;...

where DRIVER is the ODBC Driver Name and AttribX are the driver-defined attributes.

DropCursor ( [ CLOSE_TYPE ] )

Drops the cursor associated with the ODBC object. This forces the cursor to be deallocated. This overrides SetStmtCloseType, but the ODBC object does not lose the StmtCloseType setting. CLOSE_TYPE can be any valid SmtpCloseType and will perform a close on the stmt using the specified close type.

Returns true on success, false on failure.

DumpData ()

Dumps to the screen the fieldnames and all records of the current data set. Used primarily for debugging. No return value.

Error ()

Returns the last encountered error. The returned value is context dependent:

If called in a scalar context, then a 3-element array is returned:

    ( ERROR_NUMBER, ERROR_TEXT, CONNECTION_NUMBER )

If called in a string context, then a string is returned:

    "[ERROR_NUMBER] [CONNECTION_NUMBER] [ERROR_TEXT]"

If debugging is on then two more variables are returned:

    ( ..., FUNCTION, LEVEL )

where FUNCTION is the name of the function in which the error occurred, and LEVEL represents extra information about the error (usually the location of the error).

FetchRow ( [ ROW [, TYPE ] ] )

Retrieves the next record from the keyset. When ROW and/or TYPE are specified, the call is made using SQLExtendedFetch instead of SQLFetch.

NOTE 1: If you are unaware of SQLExtendedFetch and its implications, stay with just regular FetchRow with no parameters.

NOTE 2: The ODBC API explicitly warns against mixing calls to SQLFetch and SQLExtendedFetch; use one or the other but not both.

If ROW is specified, it moves the keyset RELATIVE ROW number of rows.

If ROW is specified and TYPE is not, then the type used is RELATIVE.

Returns true when another record is available to read, and false when there are no more records.

FieldNames ()

Returns an array of fieldnames found in the current data set. There is no guarantee on order.

GetConnections ()

Returns an array of connection numbers showing what connections are currently open.

GetConnectOption ( OPTION )

Returns the value of the specified connect option OPTION. Refer to ODBC documentation for more information on the options and values.

Returns a string or scalar depending upon the option specified.

GetCursorName ()

Returns the name of the current cursor as a string or undef.

GetData ()

Retrieves the current row from the dataset. This is not generally used by users; it is used internally.

Returns an array of field data where the first element is either false (if successful) and true (if not successful).

getDSN ( [ DSN ] )

Returns an associative array indicating the configuration for the specified DSN.

If no DSN is specified then the current connection is used.

The returned associative array consists of:

    keys=DSN keyword; values=Keyword value. $Data{$Keyword}=Value
GetFunctions ( [ FUNCTION1, FUNCTION2, ... ] )

Returns an associative array indicating the ability of the ODBC Driver to support the specified functions. If no functions are specified, then a 100 element associative array is returned containing all possible functions and their values.

FUNCTION must be in the form of an ODBC API constant like SQL_API_SQLTRANSACT.

The returned array will contain the results like:

    $Results{SQL_API_SQLTRANSACT}=Value

Example:

    $Results = $O->GetFunctions(
                                $O->SQL_API_SQLTRANSACT,
                                SQL_API_SQLSETCONNECTOPTION
                               );
    $ConnectOption = $Results{SQL_API_SQLSETCONNECTOPTION};
    $Transact = $Results{SQL_API_SQLTRANSACT};
GetInfo ( OPTION )

Returns a string indicating the value of the particular option specified.

GetMaxBufSize ()

Returns the current allocated limit for MaxBufSize. For more info, see SetMaxBufSize.

GetSQLState () *

Returns a string indicating the SQL state as reported by ODBC. The SQL state is a code that the ODBC Manager or ODBC Driver returns after the execution of a SQL function. This is helpful for debugging purposes.

GetStmtCloseType ( [ CONNECTION ] )

Returns a string indicating the type of closure that will be used everytime the hstmt is freed. See SetStmtCloseType for details.

By default, the connection of the current object will be used. If CONNECTION is a valid connection number, then it will be used.

GetStmtOption ( OPTION )

Returns the value of the specified statement option OPTION. Refer to ODBC documentation for more information on the options and values.

Returns a string or scalar depending upon the option specified.

MoreResults ()

This will report whether there is data yet to be retrieved from the query. This can happen if the query was a multiple select.

Example:

    "SELECT * FROM [foo] SELECT * FROM [bar]"

NOTE: Not all drivers support this.

Returns 1 if there is more data, undef otherwise.

RowCount ( CONNECTION )

For UPDATE, INSERT and DELETE statements, the returned value is the number of rows affected by the request or -1 if the number of affected rows is not available.

NOTE 1: This function is not supported by all ODBC drivers! Some drivers do support this but not for all statements (e.g., it is supported for UPDATE, INSERT and DELETE commands but not for the SELECT command).

NOTE 2: Many data sources cannot return the number of rows in a result set before fetching them; for maximum interoperability, applications should not rely on this behavior.

Returns the number of affected rows, or -1 if not supported by the driver in the current context.

Run ( SQL )

Executes the SQL command SQL and dumps to the screen info about it. Used primarily for debugging.

No return value.

SetConnectOption ( OPTION ) *

Sets the value of the specified connect option OPTION. Refer to ODBC documentation for more information on the options and values.

Returns true on success, false otherwise.

SetCursorName ( NAME ) *

Sets the name of the current cursor.

Returns true on success, false otherwise.

SetPos ( ROW [, OPTION, LOCK ] ) *

Moves the cursor to the row ROW within the current keyset (not the current data/result set).

Returns true on success, false otherwise.

SetMaxBufSize ( SIZE )

This sets the MaxBufSize for a particular connection. This will most likely never be needed but...

The amount of memory that is allocated to retrieve the field data of a record is dynamic and changes when it need to be larger. I found that a memo field in an MS Access database ended up requesting 4 Gig of space. This was a bit much so there is an imposed limit (2,147,483,647 bytes) that can be allocated for data retrieval.

Since it is possible that someone has a database with field data greater than 10,240, you can use this function to increase the limit up to a ceiling of 2,147,483,647 (recompile if you need more).

Returns the max number of bytes.

SetStmtCloseType ( TYPE [, CONNECTION ] )

Sets a particular hstmt close type for the connection. This is the same as ODBCFreeStmt(hstmt, TYPE). By default, the connection of the current object will be used. If CONNECTION is a valid connection number, then it will be used.

TYPE may be one of:

    SQL_CLOSE
    SQL_DROP
    SQL_UNBIND
    SQL_RESET_PARAMS

Returns a string indicating the newly set type.

SetStmtOption ( OPTION ) *

Sets the value of the specified statement option OPTION. Refer to ODBC documentation for more information on the options and values.

Returns true on success, false otherwise.

ShutDown ()

Closes the ODBC connection and dumps to the screen info about it. Used primarily for debugging.

No return value.

Sql ( SQL_STRING )

Executes the SQL command SQL_STRING on the current connection.

Returns ? on success, or an error number on failure.

TableList ( QUALIFIER, OWNER, NAME, TYPE )

Returns the catalog of tables that are available in the DSN. For an unknown parameter, just specify the empty string "".

Returns an array of table names.

Transact ( TYPE ) *

Forces the ODBC connection to perform a rollback or commit transaction.

TYPE may be one of:

    SQL_COMMIT
    SQL_ROLLBACK

NOTE: This only works with ODBC drivers that support transactions. Your driver supports it if true is returned from:

    $O->GetFunctions($O->SQL_API_SQLTRANSACT)[1]

(See GetFunctions for more details.)

Returns true on success, false otherwise.

Version ( PACKAGES )

Returns an array of version numbers for the requested packages (ODBC.pm or ODBC.PLL). If the list PACKAGES is empty, then all version numbers are returned.

LIMITATIONS

What known problems does this thing have?

  • If the account under which the process runs does not have write permission on the default directory (for the process, not the ODBC DSN), you will probably get a runtime error during a SQLConnection. I don't think that this is a problem with the code, but more like a problem with ODBC. This happens because some ODBC drivers need to write a temporary file. I noticed this using the MS Jet Engine (Access Driver).

  • This module has been neither optimized for speed nor optimized for memory consumption.

INSTALLATION NOTES

If you wish to use this module with a build of Perl other than ActivePerl, you may wish to fetch the original source distribution for this module at:

  ftp://ftp.roth.net:/pub/ntperl/ODBC/970208/Bin/Win32_ODBC_Build_CORE.zip

or one of the other archives at that same location. See the included README for hints on installing this module manually, what to do if you get a parse exception, and a pointer to a test script for this module.

OTHER DOCUMENTATION

Find a FAQ for Win32::ODBC at:

  http://www.roth.net/odbc/odbcfaq.htm

AUTHOR

Dave Roth <rothd@roth.net>

CREDITS

Based on original code by Dan DeMaggio <dmag@umich.edu>

DISCLAIMER

I do not guarantee ANYTHING with this package. If you use it you are doing so AT YOUR OWN RISK! I may or may not support this depending on my time schedule.

HISTORY

Last Modified 1999.09.25.

COPYRIGHT

Copyright (c) 1996-1998 Dave Roth. All rights reserved.

Courtesy of Roth Consulting: http://www.roth.net/consult/

Use under GNU General Public License. Details can be found at: http://www.gnu.org/copyleft/gpl.html


Win32::OLE - OLE Automation extensions

    • Methods
    • Object methods and properties
    • Functions
    • Overloading
    • Events
    • Module Options
  • EXAMPLES
  • NOTES
    • Hints for Microsoft Office automation
    • Incompatibilities
    • Bugs and Limitations
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT
  • VERSION

NAME

Win32::OLE - OLE Automation extensions

SYNOPSIS

    $ex = Win32::OLE->new('Excel.Application') or die "oops\n";
    $ex->Amethod("arg")->Bmethod->{'Property'} = "foo";
    $ex->Cmethod(undef,undef,$Arg3);
    $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2});

    $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc");
    $xl = Win32::OLE->GetActiveObject("Excel.Application");

DESCRIPTION

This module provides an interface to OLE Automation from Perl. OLE Automation brings VisualBasic like scripting capabilities and offers powerful extensibility and the ability to control many Win32 applications from Perl scripts.

The Win32::OLE module uses the IDispatch interface exclusively. It is not possible to access a custom OLE interface. OLE events and OCX's are currently not supported.

Actually, that's no longer strictly true. This module now contains ALPHA level support for OLE events. This is largely untested and the specific interface might still change in the future.

Methods

Win32::OLE->new(PROGID[, DESTRUCTOR])

The new() class method starts a new instance of an OLE Automation object. It returns a reference to this object or undef if the creation failed.

The PROGID argument must be either the OLE program id or the class id of the required application. The optional DESTRUCTOR specifies a DESTROY-like method. This can be either a CODE reference or a string containing an OLE method name. It can be used to cleanly terminate OLE applications in case the Perl program dies.

To create an object via DCOM on a remote server you can use an array reference in place of PROGID. The referenced array must contain the machine name and the program id or class id. For example:

        my $obj = Win32::OLE->new(['my.machine.com', 'Program.Id']);

If the PROGID is a program id then Win32::OLE will try to resolve the corresponding class id locally. If the program id is not registered locally then the remote registry is queried. This will only succeed if the local process has read access to the remote registry. The safest (and fastest) method is to specify the class id directly.

Win32::OLE->EnumAllObjects([CALLBACK])

This class method returns the number Win32::OLE objects currently in existance. It will call the optional CALLBACK function for each of these objects:

        $Count = Win32::OLE->EnumAllObjects(sub {
            my $Object = shift;
            my $Class = Win32::OLE->QueryObjectType($Object);
            printf "# Object=%s Class=%s\n", $Object, $Class;
        });

The EnumAllObjects() method is primarily a debugging tool. It can be used e.g. in an END block to check if all external connections have been properly destroyed.

Win32::OLE->FreeUnusedLibraries()

The FreeUnusedLibraries() class method unloads all unused OLE resources. These are the libraries of those classes of which all existing objects have been destroyed. The unloading of object libraries is really only important for long running processes that might instantiate a huge number of different objects over time.

Be aware that objects implemented in Visual Basic have a buggy implementation of this functionality: They pretend to be unloadable while they are actually still running their cleanup code. Unloading the DLL at that moment typically produces an access violation. The probability for this problem can be reduced by calling the SpinMessageLoop() method and sleep()ing for a few seconds.

Win32::OLE->GetActiveObject(CLASS[, DESTRUCTOR])

The GetActiveObject() class method returns an OLE reference to a running instance of the specified OLE automation server. It returns undef if the server is not currently active. It will croak if the class is not even registered. The optional DESTRUCTOR method takes either a method name or a code reference. It is executed when the last reference to this object goes away. It is generally considered impolite to stop applications that you did not start yourself.

Win32::OLE->GetObject(MONIKER[, DESTRUCTOR])

The GetObject() class method returns an OLE reference to the specified object. The object is specified by a pathname optionally followed by additional item subcomponent separated by exclamation marks '!'. The optional DESTRUCTOR argument has the same semantics as the DESTRUCTOR in new() or GetActiveObject().

Win32::OLE->Initialize([COINIT])

The Initialize() class method can be used to specify an alternative apartment model for the Perl thread. It must be called before the first OLE object is created. If the Win32::OLE::Const module is used then the call to the Initialize() method must be made from a BEGIN block before the first use statement for the Win32::OLE::Const module.

Valid values for COINIT are:

  Win32::OLE::COINIT_APARTMENTTHREADED  - single threaded
  Win32::OLE::COINIT_MULTITHREADED      - the default
  Win32::OLE::COINIT_OLEINITIALIZE      - single threaded, additional OLE stuff

COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses additional OLE compound document technologies not available from the normal COM subsystem (for example MAPI.Session seems to require it). Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden top level window and a message queue for the Perl process. This may create problems with other application, because Perl normally doesn't process its message queue. This means programs using synchronous communication between applications (such as DDE initiation), may hang until Perl makes another OLE method call/property access or terminates. This applies to InstallShield setups and many things started to shell associations. Please try to utilize the Win32::OLE->SpinMessageLoop and Win32::OLE->Uninitialize methods if you can not use the default COINIT_MULTITHREADED model.

OBJECT->Invoke(METHOD[, ARGS])

The Invoke() object method is an alternate way to invoke OLE methods. It is normally equivalent to $OBJECT-METHOD(@ARGS)>. This function must be used if the METHOD name contains characters not valid in a Perl variable name (like foreign language characters). It can also be used to invoke the default method of an object even if the default method has not been given a name in the type library. In this case use <undef> or '' as the method name. To invoke an OLE objects native Invoke() method (if such a thing exists), please use:

        $Object->Invoke('Invoke', @Args);
Win32::OLE->LastError()

The LastError() class method returns the last recorded OLE error. This is a dual value like the $! variable: in a numeric context it returns the error number and in a string context it returns the error message. The error number is a signed HRESULT value. Please use the HRESULT(ERROR) function to convert an unsigned hexadecimal constant to a signed HRESULT.

The last OLE error is automatically reset by a successful OLE call. The numeric value can also explicitly be set by a call (which will discard the string value):

        Win32::OLE->LastError(0);
OBJECT->LetProperty(NAME,ARGS,VALUE)

In Win32::OLE property assignment using the hash syntax is equivalent to the Visual Basic Set syntax (by reference assignment):

        $Object->{Property} = $OtherObject;

corresponds to this Visual Basic statement:

        Set Object.Property = OtherObject

To get the by value treatment of the Visual Basic Let statement

        Object.Property = OtherObject

you have to use the LetProperty() object method in Perl:

        $Object->LetProperty($Property, $OtherObject);

LetProperty() also supports optional arguments for the property assignment. See OBJECT-SetProperty(NAME,ARGS,VALUE)> for details.

Win32::OLE->MessageLoop()

The MessageLoop() class method will run a standard Windows message loop, dispatching messages until the QuitMessageLoop() class method is called. It is used to wait for OLE events.

Win32::OLE->Option(OPTION)

The Option() class method can be used to inspect and modify Module Options. The single argument form retrieves the value of an option:

        my $CP = Win32::OLE->Option('CP');

A single call can be used to set multiple options simultaneously:

        Win32::OLE->Option(CP => CP_ACP, Warn => 3);
Win32::OLE->QueryObjectType(OBJECT)

The QueryObjectType() class method returns a list of the type library name and the objects class name. In a scalar context it returns the class name only. It returns undef when the type information is not available.

Win32::OLE->QuitMessageLoop()

The QuitMessageLoop() class method posts a (user-level) "Quit" message to the current threads message loop. QuitMessageLoop() is typically called from an event handler. The MessageLoop() class method will return when it receives this "Quit" method.

OBJECT->SetProperty(NAME,ARGS,VALUE)

The SetProperty() method allows to modify properties with arguments, which is not supported by the hash syntax. The hash form

        $Object->{Property} = $Value;

is equivalent to

        $Object->SetProperty('Property', $Value);

Arguments must be specified between the property name and the new value:

        $Object->SetProperty('Property', @Args, $Value);

It is not possible to use "named argument" syntax with this function because the new value must be the last argument to SetProperty().

This method hides any native OLE object method called SetProperty(). The native method will still be available through the Invoke() method:

        $Object->Invoke('SetProperty', @Args);
Win32::OLE->SpinMessageLoop

This class method retrieves all pending messages from the message queue and dispatches them to their respective window procedures. Calling this method is only necessary when not using the COINIT_MULTITHREADED model. All OLE method calls and property accesses automatically process the message queue.

Win32::OLE->Uninitialize

The Uninitialize() class method uninitializes the OLE subsystem. It also destroys the hidden top level window created by OLE for single threaded apartments. All OLE objects will become invalid after this call! It is possible to call the Initialize() class method again with a different apartment model after shutting down OLE with Uninitialize().

Win32::OLE->WithEvents(OBJECT[, HANDLER[, INTERFACE]])

This class method enables and disables the firing of events by the specified OBJECT. If no HANDLER is specified, then events are disconnected. For some objects Win32::OLE is not able to automatically determine the correct event interface. In this case the INTERFACE argument must contain either the COCLASS name of the OBJECT or the name of the event DISPATCH interface. Please read the Events section below for detailed explanation of the Win32::OLE event support.

Whenever Perl does not find a method name in the Win32::OLE package it is automatically used as the name of an OLE method and this method call is dispatched to the OLE server.

There is one special hack built into the module: If a method or property name could not be resolved with the OLE object, then the default method of the object is called with the method name as its first parameter. So

        my $Sheet = $Worksheets->Table1;
        or
        my $Sheet = $Worksheets->{Table1};

is resolved as

        my $Sheet = $Worksheet->Item('Table1');

provided that the $Worksheets object doesnot have a Table1 method or property. This hack has been introduced to call the default method of collections which did not name the method in their type library. The recommended way to call the "unnamed" default method is:

        my $Sheet = $Worksheets->Invoke('', 'Table1');

This special hack is disabled under use strict 'subs';.

Object methods and properties

The object returned by the new() method can be used to invoke methods or retrieve properties in the same fashion as described in the documentation for the particular OLE class (eg. Microsoft Excel documentation describes the object hierarchy along with the properties and methods exposed for OLE access).

Optional parameters on method calls can be omitted by using undef as a placeholder. A better way is to use named arguments, as the order of optional parameters may change in later versions of the OLE server application. Named parameters can be specified in a reference to a hash as the last parameter to a method call.

Properties can be retrieved or set using hash syntax, while methods can be invoked with the usual perl method call syntax. The keys and each functions can be used to enumerate an object's properties. Beware that a property is not always writable or even readable (sometimes raising exceptions when read while being undefined).

If a method or property returns an embedded OLE object, method and property access can be chained as shown in the examples below.

Functions

The following functions are not exported by default.

HRESULT(ERROR)

The HRESULT() function converts an unsigned number into a signed HRESULT error value as used by OLE internally. This is necessary because Perl treats all hexadecimal constants as unsigned. To check if the last OLE function returned "Member not found" (0x80020003) you can write:

        if (Win32::OLE->LastError == HRESULT(0x80020003)) {
            # your error recovery here
        }
in(COLLECTION)

If COLLECTION is an OLE collection object then in $COLLECTION returns a list of all members of the collection. This is a shortcut for Win32::OLE::Enum-All($COLLECTION)>. It is most commonly used in a foreach loop:

        foreach my $value (in $collection) {
            # do something with $value here
        }
valof(OBJECT)

Normal assignment of Perl OLE objects creates just another reference to the OLE object. The valof() function explictly dereferences the object (through the default method) and returns the value of the object.

        my $RefOf = $Object;
        my $ValOf = valof $Object;
        $Object->{Value} = $NewValue;

Now $ValOf still contains the old value wheras $RefOf would resolve to the $NewValue because it is still a reference to $Object.

The valof() function can also be used to convert Win32::OLE::Variant objects to Perl values.

with(OBJECT, PROPERTYNAME => VALUE, ...)

This function provides a concise way to set the values of multiple properties of an object. It iterates over its arguments doing $OBJECT-{PROPERTYNAME} = $VALUE> on each trailing pair.

Overloading

The Win32::OLE objects can be overloaded to automatically convert to their values whenever they are used in a bool, numeric or string context. This is not enabled by default. You have to request it through the OVERLOAD pseudoexport:

        use Win32::OLE qw(in valof with OVERLOAD);

You can still get the original string representation of an object (Win32::OLE=0xDEADBEEF), e.g. for debugging, by using the overload::StrVal() method:

        print overload::StrVal($object), "\n";

Please note that OVERLOAD is a global setting. If any module enables Win32::OLE overloading then it's active everywhere.

Events

The Win32::OLE module now contains ALPHA level event support. This support is only available when Perl is running in a single threaded apartment. This can most easily be assured by using the EVENTS pseudo-import:

        use Win32::OLE qw(EVENTS);

which implicitly does something like:

        use Win32::OLE;
        Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);

The current interface to OLE events should be considered experimental and is subject to change. It works as expected for normal OLE applications, but OLE control events often don't seem to work yet.

Events must be enabled explicitly for an OLE object through the Win32::OLE->WithEvents() class method. The Win32::OLE module uses the IProvideClassInfo2 interface to determine the default event source of the object. If this interface is not supported, then the user must specify the name of the event source explicitly in the WithEvents() method call. It is also possible to specify the class name of the object as the third parameter. In this case Win32::OLE will try to look up the default source interface for this COCLASS.

The HANDLER argument to Win32::OLE->WithEvents() can either be a CODE reference or a package name. In the first case, all events will invoke this particular function. The first two arguments to this function will be the OBJECT itself and the name of the event. The remaining arguments will be event specific.

        sub Event {
            my ($Obj,$Event,@Args) = @_;
            print "Event triggered: '$Event'\n";
        }
        Win32::OLE->WithEvents($Obj, \&Event);

Alternatively the HANDLER argument can specify a package name. When the OBJECT fires an event, Win32::OLE will try to find a function of the same name as the event in this package. This function will be called with the OBJECT as the first argument followed again by the event specific parameters:

        package MyEvents;
        sub EventName1 {
            my ($Obj,@Args) = @_;
            print "EventName1 event triggered\n";
        }

        package main;
        Win32::OLE->WithEvents($Obj, 'MyEvents', 'IEventInterface');

If Win32::OLE doesn't find a function with the name of the event then nothing happens.

Event parameters passed by reference are handled specially. They are not converted to the corresponding Perl datatype but passed as Win32::OLE::Variant objects. You can assign a new value to these objects with the help of the Put() method. This value will be passed back to the object when the event function returns:

        package MyEvents;
        sub BeforeClose {
            my ($self,$Cancel) = @_;
            $Cancel->Put(1) unless $MayClose;
        }

Direct assignment to $Cancel would have no effect on the original value and would therefore not command the object to abort the closing action.

Module Options

The following module options can be accessed and modified with the Win32::OLE-Option> class method. In earlier versions of the Win32::OLE module these options were manipulated directly as class variables. This practice is now deprecated.

CP

This variable is used to determine the codepage used by all translations between Perl strings and Unicode strings used by the OLE interface. The default value is CP_ACP, which is the default ANSI codepage. Other possible values are CP_OEMCP, CP_MACCP, CP_UTF7 and CP_UTF8. These constants are not exported by default.

LCID

This variable controls the locale idnetifier used for all OLE calls. It is set to LOCALE_NEUTRAL by default. Please check the the Win32::OLE::NLS manpage module for other locale related information.

Variant

This options controls how method calls and property accessors return values of type VT_CY and VT_DECIMAL are being returned. By default VT_CY values are turned into strings and VT_DECIMAL values into floating point numbers. If the Variant option is enabled, these values are returned as Win32::OLE::Variant objects, just like VT_DATE and VT_ERROR values. If the Win32::OLE::Variant module is also loaded, then all values should still behave as before in string and in numeric context.

The only reason that the Variant behavior is not the default is that this is an incompatible change that might break existing programs.

Warn

This variable determines the behavior of the Win32::OLE module when an error happens. Valid values are:

        0       Ignore error, return undef
        1       Carp::carp if $^W is set (-w option)
        2       always Carp::carp
        3       Carp::croak

The error number and message (without Carp line/module info) are available through the Win32::OLE-LastError> class method.

Alternatively the Warn option can be set to a CODE reference. E.g.

    Win32::OLE->Option(Warn => 3);

is equivalent to

    Win32::OLE->Option(Warn => \&Carp::croak);

This can even be used to emulate the VisualBasic On Error Goto Label construct:

    Win32::OLE->Option(Warn =>  sub {goto CheckError});
    # ... your normal OLE code here ...

  CheckError:
    # ... your error handling code here ...
_NewEnum

This option enables additional enumeration support for collection objects. When the _NewEnum option is set, all collections will receive one additional property: _NewEnum. The value of this property will be a reference to an array containing all the elements of the collection. This option can be useful when used in conjunction with an automatic tree traversal program, like Data::Dumper or an object tree browser. The value of this option should be either 1 (enabled) or 0 (disabled, default).

    Win32::OLE->Option(_NewEnum => 1);
    # ...
    my @sheets = @{$Excel->Worksheets->{_NewEnum}};

In normal application code, this would be better written as:

    use Win32::OLE qw(in);
    # ...
    my @sheets = in $Excel->Worksheets;
_Unique

The _Unique options guarantees that Win32::OLE will maintain a one-to-one mapping between Win32::OLE objects and the native COM/OLE objects. Without this option, you can query the same property twice and get two different Win32::OLE objects for the same underlying COM object.

Using a unique proxy makes life easier for tree traversal algorithms to recognize they already visited a particular node. This option comes at a price: Win32::OLE has to maintain a global hash of all outstanding objects and their corresponding proxies. Identity checks on COM objects can also be expensive if the objects reside out-of-process or even on a different computer. Therefore this option is off by default unless the program is being run in the debugger.

Unfortunately, this option doesn't always help. Some programs will return new COM objects for even the same property when asked for it multiple times (especially for collections). In this case, there is nothing Win32::OLE can do to detect that these objects are in fact identical (because they aren't at the COM level).

The _Unique option can be set to either 1 (enabled) or 0 (disabled, default).

EXAMPLES

Here is a simple Microsoft Excel application.

        use Win32::OLE;

        # use existing instance if Excel is already running
        eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')};
        die "Excel not installed" if $@;
        unless (defined $ex) {
            $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;})
                    or die "Oops, cannot start Excel";
        }

        # get a new workbook
        $book = $ex->Workbooks->Add;

        # write to a particular cell
        $sheet = $book->Worksheets(1);
        $sheet->Cells(1,1)->{Value} = "foo";

        # write a 2 rows by 3 columns range
        $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ],
                                           [ 42,    'Perl',  3.1415  ]];

        # print "XyzzyPerl"
        $array = $sheet->Range("A8:C9")->{Value};
        for (@$array) {
            for (@$_) {
                print defined($_) ? "$_|" : "<undef>|";
            }
            print "\n";
        }

        # save and exit
        $book->SaveAs( 'test.xls' );
        undef $book;
        undef $ex;

Please note the destructor specified on the Win32::OLE->new method. It ensures that Excel will shutdown properly even if the Perl program dies. Otherwise there could be a process leak if your application dies after having opened an OLE instance of Excel. It is the responsibility of the module user to make sure that all OLE objects are cleaned up properly!

Here is an example of using Variant data types.

        use Win32::OLE;
        use Win32::OLE::Variant;
        $ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n";
        $ex->{Visible} = 1;
        $ex->Workbooks->Add;
        # should generate a warning under -w
        $ovR8 = Variant(VT_R8, "3 is a good number");
        $ex->Range("A1")->{Value} = $ovR8;
        $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');

        sub OleQuit {
            my $self = shift;
            $self->Quit;
        }

The above will put value "3" in cell A1 rather than the string "3 is a good number". Cell A2 will contain the date.

Similarly, to invoke a method with some binary data, you can do the following:

        $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );

Here is a wrapper class that basically delegates everything but new() and DESTROY(). The wrapper class shown here is another way to properly shut down connections if your application is liable to die without proper cleanup. Your own wrappers will probably do something more specific to the particular OLE object you may be dealing with, like overriding the methods that you may wish to enhance with your own.

        package Excel;
        use Win32::OLE;

        sub new {
            my $s = {};
            if ($s->{Ex} = Win32::OLE->new('Excel.Application')) {
                return bless $s, shift;
            }
            return undef;
        }

        sub DESTROY {
            my $s = shift;
            if (exists $s->{Ex}) {
                print "# closing connection\n";
                $s->{Ex}->Quit;
                return undef;
            }
        }

        sub AUTOLOAD {
            my $s = shift;
            $AUTOLOAD =~ s/^.*:://;
            $s->{Ex}->$AUTOLOAD(@_);
        }

        1;

The above module can be used just like Win32::OLE, except that it takes care of closing connections in case of abnormal exits. Note that the effect of this specific example can be easier accomplished using the optional destructor argument of Win32::OLE::new:

        my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;});

Note that the delegation shown in the earlier example is not the same as true subclassing with respect to further inheritance of method calls in your specialized object. See the perlobj manpage, the perltoot manpage and the perlbot manpage for details. True subclassing (available by setting @ISA) is also feasible, as the following example demonstrates:

        #
        # Add error reporting to Win32::OLE
        #

        package Win32::OLE::Strict;
        use Carp;
        use Win32::OLE;

        use strict qw(vars);
        use vars qw($AUTOLOAD @ISA);
        @ISA = qw(Win32::OLE);

        sub AUTOLOAD {
            my $obj = shift;
            $AUTOLOAD =~ s/^.*:://;
            my $meth = $AUTOLOAD;
            $AUTOLOAD = "SUPER::" . $AUTOLOAD;
            my $retval = $obj->$AUTOLOAD(@_);
            unless (defined($retval) || $AUTOLOAD eq 'DESTROY') {
                my $err = Win32::OLE::LastError();
                croak(sprintf("$meth returned OLE error 0x%08x",$err))
                  if $err;
            }
            return $retval;
        }

        1;

This package inherits the constructor new() from the Win32::OLE package. It is important to note that you cannot later rebless a Win32::OLE object as some information about the package is cached by the object. Always invoke the new() constructor through the right package!

Here's how the above class will be used:

        use Win32::OLE::Strict;
        my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit');
        my $Books = $Excel->Workbooks;
        $Books->UnknownMethod(42);

In the sample above the call to UnknownMethod() will be caught with

        UnknownMethod returned OLE error 0x80020009 at test.pl line 5

because the Workbooks object inherits the class Win32::OLE::Strict from the $Excel object.

NOTES

Hints for Microsoft Office automation

Documentation

The object model for the Office applications is defined in the Visual Basic reference guides for the various applications. These are typically not installed by default during the standard installation. They can be added later by rerunning the setup program with the custom install option.

Class, Method and Property names

The names have been changed between different versions of Office. For example Application was a method in Office 95 and is a property in Office97. Therefore it will not show up in the list of property names keys %$object when querying an Office 95 object.

The class names are not always identical to the method/property names producing the object. E.g. the Workbook method returns an object of type Workbook in Office 95 and _Workbook in Office 97.

Moniker (GetObject support)

Office applications seem to implement file monikers only. For example it seems to be impossible to retrieve a specific worksheet object through GetObject("File.XLS!Sheet"). Furthermore, in Excel 95 the moniker starts a Worksheet object and in Excel 97 it returns a Workbook object. You can use either the Win32::OLE::QueryObjectType class method or the $object->{Version} property to write portable code.

Enumeration of collection objects

Enumerations seem to be incompletely implemented. Office 95 application don't seem to support neither the Reset() nor the Clone() methods. The Clone() method is still unimplemented in Office 97. A single walk through the collection similar to Visual Basics for each construct does work however.

Localization

Starting with Office 97 Microsoft has changed the localized class, method and property names back into English. Note that string, date and currency arguments are still subject to locale specific interpretation. Perl uses the system default locale for all OLE transaction whereas Visual Basic uses a type library specific locale. A Visual Basic script would use "R1C1" in string arguments to specify relative references. A Perl script running on a German language Windows would have to use "Z1S1". Set the LCID module option to an English locale to write portable scripts. This variable should not be changed after creating the OLE objects; some methods seem to randomly fail if the locale is changed on the fly.

SaveAs method in Word 97 doesn't work

This is an known bug in Word 97. Search the MS knowledge base for Word / Foxpro incompatibility. That problem applies to the Perl OLE interface as well. A workaround is to use the WordBasic compatibility object. It doesn't support all the options of the native method though.

    $Word->WordBasic->FileSaveAs($file);

The problem seems to be fixed by applying the Office 97 Service Release 1.

Randomly failing method calls

It seems like modifying objects that are not selected/activated is sometimes fragile. Most of these problems go away if the chart/sheet/document is selected or activated before being manipulated (just like an interactive user would automatically do it).

Incompatibilities

There are some incompatibilities with the version distributed by Activeware (as of build 306).

  1. The package name has changed from "OLE" to "Win32::OLE".

  2. All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo", though the old names are temporarily accomodated. Win32::OLECreateObject() was changed to Win32::OLE::CreateObject(), and is now called Win32::OLE::new() bowing to established convention for naming constructors. The old names should be considered deprecated, and will be removed in the next version.

  3. Package "OLE::Variant" is now "Win32::OLE::Variant".

  4. The Variant function is new, and is exported by default. So are all the VT_XXX type constants.

  5. The support for collection objects has been moved into the package Win32::OLE::Enum. The keys %$object method is now used to enumerate the properties of the object.

Bugs and Limitations

  • To invoke a native OLE method with the same name as one of the Win32::OLE methods (Dispatch, Invoke, SetProperty, DESTROY, etc.), you have to use the Invoke method:

            $Object->Invoke('Dispatch', @AdditionalArgs);

    The same is true for names exported by the Exporter or the Dynaloader modules, e.g.: export, export_to_level, import, _push_tags, export_tags, export_ok_tags, export_fail, require_version, dl_load_flags, croak, bootstrap, dl_findfile, dl_expandspec, dl_find_symbol_anywhere, dl_load_file, dl_find_symbol, dl_undef_symbols, dl_install_xsub and dl_error.

SEE ALSO

The documentation for the Win32::OLE::Const manpage, the Win32::OLE::Enum manpage, the Win32::OLE::NLS manpage and the Win32::OLE::Variant manpage contains additional information about OLE support for Perl on Win32.

AUTHORS

Originally put together by the kind people at Hip and Activeware.

Gurusamy Sarathy <gsar@activestate.com> subsequently fixed several major bugs, memory leaks, and reliability problems, along with some redesign of the code.

Jan Dubois <jand@activestate.com> pitched in with yet more massive redesign, added support for named parameters, and other significant enhancements. He's been hacking on it ever since.

Please send questions about problems with this module to the Perl-Win32-Users mailinglist at ActiveState.com. The mailinglist charter requests that you put an [OLE] tag somewhere on the subject line (for OLE related questions only, of course).

COPYRIGHT

    (c) 1995 Microsoft Corporation. All rights reserved.
    Developed by ActiveWare Internet Corp., now known as
    ActiveState Tool Corp., http://www.ActiveState.com
    Other modifications Copyright (c) 1997-2006 by Gurusamy Sarathy
    <gsar@activestate.com> and Jan Dubois <jand@activestate.com>
    You may distribute under the terms of either the GNU General Public
    License or the Artistic License, as specified in the README file.

VERSION

Version 0.1707 7 August 2006


Win32::OLE - Type Library Browser

Sorry

this application only works with Internet Explorer.


Win32::OLE::Const - Extract constant definitions from TypeLib

    • Functions/Methods
  • EXAMPLES
  • AUTHORS/COPYRIGHT

NAME

Win32::OLE::Const - Extract constant definitions from TypeLib

SYNOPSIS

    use Win32::OLE::Const 'Microsoft Excel';
    printf "xlMarkerStyleDot = %d\n", xlMarkerStyleDot;

    my $wd = Win32::OLE::Const->Load("Microsoft Word 8\\.0 Object Library");
    foreach my $key (keys %$wd) {
        printf "$key = %s\n", $wd->{$key};
    }

DESCRIPTION

This modules makes all constants from a registered OLE type library available to the Perl program. The constant definitions can be imported as functions, providing compile time name checking. Alternatively the constants can be returned in a hash reference which avoids defining lots of functions of unknown names.

Functions/Methods

use Win32::OLE::Const

The use statement can be used to directly import the constant names and values into the users namespace.

    use Win32::OLE::Const (TYPELIB,MAJOR,MINOR,LANGUAGE);

The TYPELIB argument specifies a regular expression for searching through the registry for the type library. Note that this argument is implicitly prefixed with ^ to speed up matches in the most common cases. Use a typelib name like ".*Excel" to match anywhere within the description. TYPELIB is the only required argument.

The MAJOR and MINOR arguments specify the requested version of the type specification. If the MAJOR argument is used then only typelibs with exactly this major version number will be matched. The MINOR argument however specifies the minimum acceptable minor version. MINOR is ignored if MAJOR is undefined.

If the LANGUAGE argument is used then only typelibs with exactly this language id will be matched.

The module will select the typelib with the highest version number satisfying the request. If no language id is specified then a the default language (0) will be preferred over the others.

Note that only constants with valid Perl variable names will be exported, i.e. names matching this regexp: /^[a-zA-Z_][a-zA-Z0-9_]*$/.

Win32::OLE::Const->Load

The Win32::OLE::Const->Load method returns a reference to a hash of constant definitions.

    my $const = Win32::OLE::Const->Load(TYPELIB,MAJOR,MINOR,LANGUAGE);

The parameters are the same as for the use case.

This method is generally preferrable when the typelib uses a non-english language and the constant names contain locale specific characters not allowed in Perl variable names.

Another advantage is that all available constants can now be enumerated.

The load method also accepts an OLE object as a parameter. In this case the OLE object is queried about its containing type library and no registry search is done at all. Interestingly this seems to be slower.

EXAMPLES

The first example imports all Excel constants names into the main namespace and prints the value of xlMarkerStyleDot (-4118).

    use Win32::OLE::Const ('Microsoft Excel 8.0 Object Library');
    print "xlMarkerStyleDot = %d\n", xlMarkerStyleDot;

The second example returns all Word constants in a hash ref.

    use Win32::OLE::Const;
    my $wd = Win32::OLE::Const->Load("Microsoft Word 8.0 Object Library");
    foreach my $key (keys %$wd) {
        printf "$key = %s\n", $wd->{$key};
    }
    printf "wdGreen = %s\n", $wd->{wdGreen};

The last example uses an OLE object to specify the type library:

    use Win32::OLE;
    use Win32::OLE::Const;
    my $Excel = Win32::OLE->new('Excel.Application', 'Quit');
    my $xl = Win32::OLE::Const->Load($Excel);

AUTHORS/COPYRIGHT

This module is part of the Win32::OLE distribution.


Win32::OLE::Enum - OLE Automation Collection Objects

    • Functions/Methods
  • AUTHORS/COPYRIGHT

NAME

Win32::OLE::Enum - OLE Automation Collection Objects

SYNOPSIS

    my $Sheets = $Excel->Workbooks(1)->Worksheets;
    my $Enum = Win32::OLE::Enum->new($Sheets);
    my @Sheets = $Enum->All;

    while (defined(my $Sheet = $Enum->Next)) { ... }

DESCRIPTION

This module provides an interface to OLE collection objects from Perl. It defines an enumerator object closely mirroring the functionality of the IEnumVARIANT interface.

Please note that the Reset() method is not available in all implementations of OLE collections (like Excel 7). In that case the Enum object is good only for a single walk through of the collection.

Functions/Methods

Win32::OLE::Enum->new($object)

Creates an enumerator for $object, which must be a valid OLE collection object. Note that correctly implemented collection objects must support the Count and Item methods, so creating an enumerator is not always necessary.

$Enum->All()

Returns a list of all objects in the collection. You have to call $Enum->Reset() before the enumerator can be used again. The previous position in the collection is lost.

This method can also be called as a class method:

        my @list = Win32::OLE::Enum->All($Collection);
$Enum->Clone()

Returns a clone of the enumerator maintaining the current position within the collection (if possible). Note that the Clone method is often not implemented. Use $Enum->Clone() in an eval block to avoid dying if you are not sure that Clone is supported.

$Enum->Next( [$count] )

Returns the next element of the collection. In a list context the optional $count argument specifies the number of objects to be returned. In a scalar context only the last of at most $count retrieved objects is returned. The default for $count is 1.

$Enum->Reset()

Resets the enumeration sequence to the beginning. There is no guarantee that the exact same set of objects will be enumerated again (e.g. when enumerating files in a directory). The methods return value indicates the success of the operation. (Note that the Reset() method seems to be unimplemented in some applications like Excel 7. Use it in an eval block to avoid dying.)

$Enum->Skip( [$count] )

Skip the next $count elements of the enumeration. The default for $count is 1. The functions returns TRUE if at least $count elements could be skipped. It returns FALSE if not enough elements were left.

AUTHORS/COPYRIGHT

This module is part of the Win32::OLE distribution.


Win32::OLE::NEWS - What's new in Win32::OLE

  • Version 0.18
    • VT_CY and VT_DECIMAL return values handled differently
  • Version 0.17
    • New nullstring() function in Win32::OLE::Variant
  • Version 0.16
    • Improved Unicode support
  • Version 0.13
    • New nothing() function in Win32::OLE::Variant
    • New _NewEnum and _Unique options
  • Version 0.12
    • Additional error handling functionality
    • Builtin event loop
    • Free unused OLE libraries
    • The "Win32::OLE" article from "The Perl Journal #10"
    • VARIANT->Put() bug fixes
    • Error message fixes
    • VT_DATE and VT_ERROR return values handled differently
  • Version 0.11 (changes since 0.1008)
    • new DHTML typelib browser
    • VT_DECIMAL support
  • Version 0.1008
    • new LetProperty() object method
    • new HRESULT() function
  • Version 0.1007 (changes since 0.1005)
    • OLE Event support
    • GetObject() and GetActiveObject() now support optional DESTRUCTOR argument
    • Remote object instantiation via DCOM
    • Enumerate all Win32::OLE objects
    • The VARIANT->Put() method now returns the VARIANT object itself
    • The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY
    • New Variant formatting methods
    • new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()
    • Win32::OLE::Const now correctly treats version numbers as hex
    • more robust global destruction of Win32::OLE objects
  • Version 0.1005 (changes since 0.1003)
    • optional DESTRUCTOR for GetActiveObject() GetObject() class methods
    • new Variant object method: $object->Copy()
    • new Win32::OLE->Option() class method

NAME

Win32::OLE::NEWS - What's new in Win32::OLE

This file contains a history of user visible changes to the Win32::OLE::* modules. Only new features and major bug fixes that might affect backwards compatibility are included.

Version 0.18

VT_CY and VT_DECIMAL return values handled differently

The new Variant option enables values of VT_CY or VT_DECIMAL type to be returned as Win32::OLE::Variant objects instead of being converted into strings and numbers respectively. This is similar to the change in Win32::OLE version 0.12 to VT_DATE and VT_ERROR values. The Win32::OLE::Variant module must be included to make sure that VT_CY and VT_DECIMAL values behave as before in numeric or string contexts.

Because the new behavior is potentially incompatible, it must be explicitly enabled:

    Win32::OLE->Option(Variant => 1);

Version 0.17

New nullstring() function in Win32::OLE::Variant

The nullstring() function returns a VT_BSTR variant containing a NULL string pointer. Note that this is not the same as a VT_BSTR variant containing the empty string "".

The nullstring() return value is equivalent to the Visual Basic vbNullString constant.

Version 0.16

Improved Unicode support

Passing Unicode strings to methods and properties as well as returning Unicode strings back to Perl works now with both Perl 5.6 and 5.8. Note that the Unicode support in 5.8 is much more complete than in 5.6 or 5.6.1.

Unicode::String objects can now be passed to methods or assigned to properties.

You must enable Unicode support by switching Win32::OLE to the UTF8 codepage:

    Win32::OLE->Option(CP => Win32::OLE::CP_UTF8());

Version 0.13

New nothing() function in Win32::OLE::Variant

The nothing() function returns an empty VT_DISPATCH variant. It can be used to clear an object reference stored in a property

        use Win32::OLE::Variant qw(:DEFAULT nothing);
        # ...
        $object->{Property} = nothing;

This has the same effect as the Visual Basic statement

        Set object.Property = Nothing

New _NewEnum and _Unique options

There are two new options available for the Win32::OLE->Option class method: _NewEnum provides the elements of a collection object directly as the value of a _NewEnum property. The _Unique option guarantees that Win32::OLE will not create multiple proxy objects for the same underlying COM/OLE object.

Both options are only really useful to tree traversal programs or during debugging.

Version 0.12

Additional error handling functionality

The Warn option can now be set to a CODE reference too. For example,

    Win32::OLE->Option(Warn => 3);

could now be written as

    Win32::OLE->Option(Warn => \&Carp::croak);

This can even be used to emulate the VisualBasic On Error Goto Label construct:

    Win32::OLE->Option(Warn =>  sub {goto CheckError});
    # ... your normal OLE code here ...

  CheckError:
    # ... your error handling code here ...

Builtin event loop

Processing OLE events required a polling loop before, e.g.

    my $Quit;
    #...
    until ($Quit) {
        Win32::OLE->SpinMessageLoop;
        Win32::Sleep(100);
    }
    package BrowserEvents;
    sub OnQuit { $Quit = 1 }

This is inefficient and a bit odd. This version of Win32::OLE now supports a standard messageloop:

    Win32::OLE->MessageLoop();

    package BrowserEvents;
    sub OnQuit { Win32::OLE->QuitMessageLoop }

Free unused OLE libraries

Previous versions of Win32::OLE would call the CoFreeUnusedLibraries() API whenever an OLE object was destroyed. This made sure that OLE libraries would be unloaded as soon as they were no longer needed. Unfortunately, objects implemented in Visual Basic tend to crash during this call, as they pretend to be ready for unloading, when in fact, they aren't.

The unloading of object libraries is really only important for long running processes that might instantiate a huge number of different objects over time. Therefore this API is no longer called automatically. The functionality is now available explicitly to those who want or need it by calling a Win32::OLE class method:

    Win32::OLE->FreeUnusedLibraries();

The "Win32::OLE" article from "The Perl Journal #10"

The article is Copyright 1998 by The Perl Journal. http://www.tpj.com

It originally appeared in The Perl Journal # 10 and appears here courtesy of Jon Orwant and The Perl Journal. The sample code from the article is in the eg/tpj.pl file.

VARIANT->Put() bug fixes

The Put() method didn't work correctly for arrays of type VT_BSTR, VT_DISPATH or VT_UNKNOWN. This has been fixed.

Error message fixes

Previous versions of Win32::OLE gave a wrong argument index for some OLE error messages (the number was too large by 1). This should be fixed now.

VT_DATE and VT_ERROR return values handled differently

Method calls and property accesses returning a VT_DATE or VT_ERROR value would previously translate the value to string or integer format. This has been changed to return a Win32::OLE::Variant object. The return values will behave as before if the Win32::OLE::Variant module is being used. This module overloads the conversion of the objects to strings and numbers.

Version 0.11 (changes since 0.1008)

new DHTML typelib browser

The Win32::OLE distribution now contains a type library browser. It is written in PerlScript, generating dynamic HTML. It requires Internet Explorer 4.0 or later. You'll find it in browser/Browser.html. It should be available in the ActivePerl HTML help under Win32::OLE::Browser.

After selecting a library, type or member you can press F1 to call up the corresponding help file at the appropriate location.

VT_DECIMAL support

The Win32::OLE::Variant module now supports VT_DECIMAL variants too. They are not "officially" allowed in OLE Automation calls, but even Microsoft's "ActiveX Data Objects" sometimes returns VT_DECIMAL values.

VT_DECIMAL variables are stored as 96-bit integers scaled by a variable power of 10. The power of 10 scaling factor specifies the number of digits to the right of the decimal point, and ranges from 0 to 28. With a scale of 0 (no decimal places), the largest possible value is +/-79,228,162,514,264,337,593,543,950,335. With a 28 decimal places, the largest value is +/-7.9228162514264337593543950335 and the smallest, non-zero value is +/-0.0000000000000000000000000001.

Version 0.1008

new LetProperty() object method

In Win32::OLE property assignment using the hash syntax is equivalent to the Visual Basic Set syntax (by reference assignment):

  $Object->{Property} = $OtherObject;

corresponds to this Visual Basic statement:

  Set Object.Property = OtherObject

To get the by value treatment of the Visual Basic Let statement

  Object.Property = OtherObject

you have to use the LetProperty() object method in Perl:

  $Object->LetProperty($Property, $OtherObject);

new HRESULT() function

The HRESULT() function converts an unsigned number into a signed HRESULT error value as used by OLE internally. This is necessary because Perl treats all hexadecimal constants as unsigned. To check if the last OLE function returned "Member not found" (0x80020003) you can write:

  if (Win32::OLE->LastError == HRESULT(0x80020003)) {
      # your error recovery here
  }

Version 0.1007 (changes since 0.1005)

OLE Event support

This version of Win32::OLE contains ALPHA level support for OLE events. The userinterface is still subject to change. There are ActiveX objects / controls that don't fire events under the current implementation.

Events are enabled for a specific object with the Win32::OLE->WithEvents() class method:

  Win32::OLE->WithEvents(OBJECT, HANDLER, INTERFACE)

Please read further documentation in Win32::OLE.

GetObject() and GetActiveObject() now support optional DESTRUCTOR argument

It is now possible to specify a DESTRUCTOR argument to the GetObject() and GetActiveObject() class methods. They work identical to the new() DESTRUCTOR argument.

Remote object instantiation via DCOM

This has actually been in Win32::OLE since 0.0608, but somehow never got documented. You can provide an array reference in place of the usual PROGID parameter to Win32::OLE->new():

  OBJ = Win32::OLE->new([MACHINE, PRODID]);

The array must contain two elements: the name of the MACHINE and the PROGID. This will try to create the object on the remote MACHINE.

Enumerate all Win32::OLE objects

This class method returns the number Win32::OLE objects currently in existance. It will call the optional CALLBACK function for each of these objects:

  $Count = Win32::OLE->EnumAllObjects(sub {
      my $Object = shift;
      my $Class = Win32::OLE->QueryObjectType($Object);
      printf "# Object=%s Class=%s\n", $Object, $Class;
  });

The EnumAllObjects() method is primarily a debugging tool. It can be used e.g. in an END block to check if all external connections have been properly destroyed.

The VARIANT->Put() method now returns the VARIANT object itself

This allows chaining of Put() method calls to set multiple values in an array variant:

  $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);

The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY

This allows automatic conversion from a list of lists to a SAFEARRAY. You can now write:

  my $Array = Variant(VT_ARRAY|VT_R8, [1,2], 2);
  $Array->Put([[1,2], [3,4]]);

instead of the tedious:

  $Array->Put(1,0,1);
  $Array->Put(1,1,2);
  $Array->Put(2,0,3);
  $Array->Put(2,1,4);

New Variant formatting methods

There are four new methods for formatting variant values: Currency(), Date(), Number() and Time(). For example:

  my $v = Variant(VT_DATE, "April 1 99");
  print $v->Date(DATE_LONGDATE), "\n";
  print $v->Date("ddd',' MMM dd yy"), "\n";

will print:

  Thursday, April 01, 1999
  Thu, Apr 01 99

new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()

SendSettingChange() sends a WM_SETTINGCHANGE message to all top level windows.

SetLocaleInfo() allows changing elements in the user override section of the locale database. Unfortunately these changes are not automatically available to further Variant formatting; you have to call SendSettingChange() first.

Win32::OLE::Const now correctly treats version numbers as hex

The minor and major version numbers of type libraries have been treated as decimal. This was wrong. They are now correctly decoded as hex.

more robust global destruction of Win32::OLE objects

The final destruction of Win32::OLE objects has always been somewhat fragile. The reason for this is that Perl doesn't honour reference counts during global destruction but destroys objects in seemingly random order. This can lead to leaked database connections or unterminated external objects. The only solution was to make all objects lexical and hope that no object would be trapped in a closure. Alternatively all objects could be explicitly set to undef, which doesn't work very well with exception handling.

With version 0.1007 of Win32::OLE this problem should be gone: The module keeps a list of active Win32::OLE objects. It uses an END block to destroy all objects at program termination before the Perl's global destruction starts. Objects still existing at program termination are now destroyed in reverse order of creation. The effect is similar to explicitly calling Win32::OLE->Uninitialize() just prior to termination.

Version 0.1005 (changes since 0.1003)

Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also included in the Perl Resource Kit for Win32 Update.

optional DESTRUCTOR for GetActiveObject() GetObject() class methods

The GetActiveObject() and GetObject() class method now also support an optional DESTRUCTOR parameter just like Win32::OLE->new(). The DESTRUCTOR is executed when the last reference to this object goes away. It is generally considered impolite to stop applications that you did not start yourself.

new Variant object method: $object->Copy()

See Copy([DIM]) in the Win32::OLE::Variant manpage.

new Win32::OLE->Option() class method

The Option() class method can be used to inspect and modify Module Options in the Win32::OLE manpage. The single argument form retrieves the value of an option:

  my $CP = Win32::OLE->Option('CP');

A single call can be used to set multiple options simultaneously:

  Win32::OLE->Option(CP => CP_ACP, Warn => 3);

Currently the following options exist: CP, LCID and Warn.


Win32::OLE::NLS - OLE National Language Support

    • Functions
    • Locale Types
  • AUTHORS/COPYRIGHT

NAME

Win32::OLE::NLS - OLE National Language Support

SYNOPSIS

        missing

DESCRIPTION

This module provides access to the national language support features in the OLENLS.DLL.

Functions

CompareString(LCID,FLAGS,STR1,STR2)

Compare STR1 and STR2 in the LCID locale. FLAGS indicate the character traits to be used or ignored when comparing the two strings.

        NORM_IGNORECASE         Ignore case
        NORM_IGNOREKANATYPE     Ignore hiragana/katakana character differences
        NORM_IGNORENONSPACE     Ignore accents, diacritics, and vowel marks
        NORM_IGNORESYMBOLS      Ignore symbols
        NORM_IGNOREWIDTH        Ignore character width

Possible return values are:

        0       Function failed
        1       STR1 is less than STR2
        2       STR1 is equal to STR2
        3       STR1 is greater than STR2

Note that you can subtract 2 from the return code to get values comparable to the cmp operator.

LCMapString(LCID,FLAGS,STR)

LCMapString translates STR using LCID dependent translation. Flags contains a combination of the following options:

        LCMAP_LOWERCASE         Lowercase
        LCMAP_UPPERCASE         Uppercase
        LCMAP_HALFWIDTH         Narrow characters
        LCMAP_FULLWIDTH         Wide characters
        LCMAP_HIRAGANA          Hiragana
        LCMAP_KATAKANA          Katakana
        LCMAP_SORTKEY           Character sort key

The following normalization options can be combined with LCMAP_SORTKEY:

        NORM_IGNORECASE         Ignore case
        NORM_IGNOREKANATYPE     Ignore hiragana/katakana character differences
        NORM_IGNORENONSPACE     Ignore accents, diacritics, and vowel marks
        NORM_IGNORESYMBOLS      Ignore symbols
        NORM_IGNOREWIDTH        Ignore character width

The return value is the translated string.

GetLocaleInfo(LCID,LCTYPE)

Retrieve locale setting LCTYPE from the locale specified by LCID. Use LOCALE_NOUSEROVERRIDE | LCTYPE to always query the locale database. Otherwise user changes to win.ini through the windows control panel take precedence when retrieving values for the system default locale. See the documentation below for a list of valid LCTYPE values.

The return value is the contents of the requested locale setting.

GetStringType(LCID,TYPE,STR)

Retrieve type information from locale LCID about each character in STR. The requested TYPE can be one of the following 3 levels:

        CT_CTYPE1               ANSI C and POSIX type information
        CT_CTYPE2               Text layout type information
        CT_CTYPE3               Text processing type information

The return value is a list of values, each of wich is a bitwise OR of the applicable type bits from the corresponding table below:

        @ct = GetStringType(LOCALE_SYSTEM_DEFAULT, CT_CTYPE1, "String");

ANSI C and POSIX character type information:

        C1_UPPER                Uppercase
        C1_LOWER                Lowercase
        C1_DIGIT                Decimal digits
        C1_SPACE                Space characters
        C1_PUNCT                Punctuation
        C1_CNTRL                Control characters
        C1_BLANK                Blank characters
        C1_XDIGIT               Hexadecimal digits
        C1_ALPHA                Any letter

Text layout type information:

        C2_LEFTTORIGHT          Left to right
        C2_RIGHTTOLEFT          Right to left
        C2_EUROPENUMBER         European number, European digit
        C2_EUROPESEPARATOR      European numeric separator
        C2_EUROPETERMINATOR     European numeric terminator
        C2_ARABICNUMBER         Arabic number
        C2_COMMONSEPARATOR      Common numeric separator
        C2_BLOCKSEPARATOR       Block separator
        C2_SEGMENTSEPARATOR     Segment separator
        C2_WHITESPACE           White space
        C2_OTHERNEUTRAL         Other neutrals
        C2_NOTAPPLICABLE        No implicit direction (e.g. ctrl codes)

Text precessing type information:

        C3_NONSPACING           Nonspacing mark
        C3_DIACRITIC            Diacritic nonspacing mark
        C3_VOWELMARK            Vowel nonspacing mark
        C3_SYMBOL               Symbol
        C3_KATAKANA             Katakana character
        C3_HIRAGANA             Hiragana character
        C3_HALFWIDTH            Narrow character
        C3_FULLWIDTH            Wide character
        C3_IDEOGRAPH            Ideograph
        C3_ALPHA                Any letter
        C3_NOTAPPLICABLE        Not applicable
GetSystemDefaultLangID()

Returns the system default language identifier.

GetSystemDefaultLCID()

Returns the system default locale identifier.

GetUserDefaultLangID()

Returns the user default language identifier.

GetUserDefaultLCID()

Returns the user default locale identifier.

SendSettingChange()

Sends a WM_SETTINGCHANGE message to all top level windows.

SetLocaleInfo(LCID, LCTYPE, LCDATA)

Changes an item in the user override part of the locale setting LCID. It doesn't change the system default database. The following LCTYPEs are changeable:

        LOCALE_ICALENDARTYPE    LOCALE_SDATE
        LOCALE_ICURRDIGITS      LOCALE_SDECIMAL
        LOCALE_ICURRENCY        LOCALE_SGROUPING
        LOCALE_IDIGITS          LOCALE_SLIST
        LOCALE_IFIRSTDAYOFWEEK  LOCALE_SLONGDATE
        LOCALE_IFIRSTWEEKOFYEAR LOCALE_SMONDECIMALSEP
        LOCALE_ILZERO           LOCALE_SMONGROUPING
        LOCALE_IMEASURE         LOCALE_SMONTHOUSANDSEP
        LOCALE_INEGCURR         LOCALE_SNEGATIVESIGN
        LOCALE_INEGNUMBER       LOCALE_SPOSITIVESIGN
        LOCALE_IPAPERSIZE       LOCALE_SSHORTDATE
        LOCALE_ITIME            LOCALE_STHOUSAND
        LOCALE_S1159            LOCALE_STIME
        LOCALE_S2359            LOCALE_STIMEFORMAT
        LOCALE_SCURRENCY        LOCALE_SYEARMONTH

You have to call SendSettingChange() to activate these changes for subsequent Win32::OLE::Variant object formatting because the OLE subsystem seems to cache locale information.

MAKELANGID(LANG,SUBLANG)

Creates a lnguage identifier from a primary language and a sublanguage.

PRIMARYLANGID(LANGID)

Retrieves the primary language from a language identifier.

SUBLANGID(LANGID)

Retrieves the sublanguage from a language identifier.

MAKELCID(LANGID)

Creates a locale identifies from a language identifier.

LANGIDFROMLCID(LCID)

Retrieves a language identifier from a locale identifier.

Locale Types

LOCALE_ILANGUAGE

The language identifier (in hex).

LOCALE_SLANGUAGE

The localized name of the language.

LOCALE_SENGLANGUAGE

The ISO Standard 639 English name of the language.

LOCALE_SABBREVLANGNAME

The three-letter abbreviated name of the language. The first two letters are from the ISO Standard 639 language name abbreviation. The third letter indicates the sublanguage type.

LOCALE_SNATIVELANGNAME

The native name of the language.

LOCALE_ICOUNTRY

The country code, which is based on international phone codes.

LOCALE_SCOUNTRY

The localized name of the country.

LOCALE_SENGCOUNTRY

The English name of the country.

LOCALE_SABBREVCTRYNAME

The ISO Standard 3166 abbreviated name of the country.

LOCALE_SNATIVECTRYNAME

The native name of the country.

LOCALE_IDEFAULTLANGUAGE

Language identifier for the principal language spoken in this locale.

LOCALE_IDEFAULTCOUNTRY

Country code for the principal country in this locale.

LOCALE_IDEFAULTANSICODEPAGE

The ANSI code page associated with this locale. Format: 4 Unicode decimal digits plus a Unicode null terminator.

XXX This should be translated by GetLocaleInfo. XXX

LOCALE_IDEFAULTCODEPAGE

The OEM code page associated with the country.

LOCALE_SLIST

Characters used to separate list items (often a comma).

LOCALE_IMEASURE

Default measurement system:

        0       metric system (S.I.)
        1       U.S. system
LOCALE_SDECIMAL

Characters used for the decimal separator (often a dot).

LOCALE_STHOUSAND

Characters used as the separator between groups of digits left of the decimal.

LOCALE_SGROUPING

Sizes for each group of digits to the left of the decimal. An explicit size is required for each group. Sizes are separated by semicolons. If the last value is 0, the preceding value is repeated. To group thousands, specify 3;0.

LOCALE_IDIGITS

The number of fractional digits.

LOCALE_ILZERO

Whether to use leading zeros in decimal fields. A setting of 0 means use no leading zeros; 1 means use leading zeros.

LOCALE_SNATIVEDIGITS

The ten characters that are the native equivalent of the ASCII 0-9.

LOCALE_INEGNUMBER

Negative number mode.

        0       (1.1)
        1       -1.1
        2       -1.1
        3       1.1
        4       1.1
LOCALE_SCURRENCY

The string used as the local monetary symbol.

LOCALE_SINTLSYMBOL

Three characters of the International monetary symbol specified in ISO 4217, Codes for the Representation of Currencies and Funds, followed by the character separating this string from the amount.

LOCALE_SMONDECIMALSEP

Characters used for the monetary decimal separators.

LOCALE_SMONTHOUSANDSEP

Characters used as monetary separator between groups of digits left of the decimal.

LOCALE_SMONGROUPING

Sizes for each group of monetary digits to the left of the decimal. An explicit size is needed for each group. Sizes are separated by semicolons. If the last value is 0, the preceding value is repeated. To group thousands, specify 3;0.

LOCALE_ICURRDIGITS

Number of fractional digits for the local monetary format.

LOCALE_IINTLCURRDIGITS

Number of fractional digits for the international monetary format.

LOCALE_ICURRENCY

Positive currency mode.

        0       Prefix, no separation.
        1       Suffix, no separation.
        2       Prefix, 1-character separation.
        3       Suffix, 1-character separation.
LOCALE_INEGCURR

Negative currency mode.

        0       ($1.1)
        1       -$1.1
        2       $-1.1
        3       $1.1-
        4       $(1.1$)
        5       -1.1$
        6       1.1-$
        7       1.1$-
        8       -1.1 $ (space before $)
        9       -$ 1.1 (space after $)
        10      1.1 $- (space before $)
LOCALE_ICALENDARTYPE

The type of calendar currently in use.

        1       Gregorian (as in U.S.)
        2       Gregorian (always English strings)
        3       Era: Year of the Emperor (Japan)
        4       Era: Year of the Republic of China
        5       Tangun Era (Korea)
LOCALE_IOPTIONALCALENDAR

The additional calendar types available for this LCID. Can be a null-separated list of all valid optional calendars. Value is 0 for "None available" or any of the LOCALE_ICALENDARTYPE settings.

XXX null separated list should be translated by GetLocaleInfo XXX

LOCALE_SDATE

Characters used for the date separator.

LOCALE_STIME

Characters used for the time separator.

LOCALE_STIMEFORMAT

Time-formatting string.

LOCALE_SSHORTDATE

Short Date_Time formatting strings for this locale.

LOCALE_SLONGDATE

Long Date_Time formatting strings for this locale.

LOCALE_IDATE

Short Date format-ordering specifier.

        0       Month - Day - Year
        1       Day - Month - Year
        2       Year - Month - Day
LOCALE_ILDATE

Long Date format ordering specifier. Value can be any of the valid LOCALE_IDATE settings.

LOCALE_ITIME

Time format specifier.

        0       AM/PM 12-hour format.
        1       24-hour format.
LOCALE_ITIMEMARKPOSN

Whether the time marker string (AM|PM) precedes or follows the time string. 0 Suffix (9:15 AM). 1 Prefix (AM 9:15).

LOCALE_ICENTURY

Whether to use full 4-digit century.

        0       Two digit.
        1       Full century.
LOCALE_ITLZERO

Whether to use leading zeros in time fields.

        0       No leading zeros.
        1       Leading zeros for hours.
LOCALE_IDAYLZERO

Whether to use leading zeros in day fields. Values as for LOCALE_ITLZERO.

LOCALE_IMONLZERO

Whether to use leading zeros in month fields. Values as for LOCALE_ITLZERO.

LOCALE_S1159

String for the AM designator.

LOCALE_S2359

String for the PM designator.

LOCALE_IFIRSTWEEKOFYEAR

Specifies which week of the year is considered first.

        0       Week containing 1/1 is the first week of the year.
        1       First full week following 1/1is the first week of the year.
        2       First week with at least 4 days is the first week of the year.
LOCALE_IFIRSTDAYOFWEEK

Specifies the day considered first in the week. Value "0" means SDAYNAME1 and value "6" means SDAYNAME7.

LOCALE_SDAYNAME1 .. LOCALE_SDAYNAME7

Long name for Monday .. Sunday.

LOCALE_SABBREVDAYNAME1 .. LOCALE_SABBREVDAYNAME7

Abbreviated name for Monday .. Sunday.

LOCALE_SMONTHNAME1 .. LOCALE_SMONTHNAME12

Long name for January .. December.

LOCALE_SMONTHNAME13

Native name for 13th month, if it exists.

LOCALE_SABBREVMONTHNAME1 .. LOCALE_SABBREVMONTHNAME12

Abbreviated name for January .. December.

LOCALE_SABBREVMONTHNAME13

Native abbreviated name for 13th month, if it exists.

LOCALE_SPOSITIVESIGN

String value for the positive sign.

LOCALE_SNEGATIVESIGN

String value for the negative sign.

LOCALE_IPOSSIGNPOSN

Formatting index for positive values.

        0 Parentheses surround the amount and the monetary symbol.
        1 The sign string precedes the amount and the monetary symbol.
        2 The sign string precedes the amount and the monetary symbol.
        3 The sign string precedes the amount and the monetary symbol.
        4 The sign string precedes the amount and the monetary symbol.
LOCALE_INEGSIGNPOSN

Formatting index for negative values. Values as for LOCALE_IPOSSIGNPOSN.

LOCALE_IPOSSYMPRECEDES

If the monetary symbol precedes, 1. If it succeeds a positive amount, 0.

LOCALE_IPOSSEPBYSPACE

If the monetary symbol is separated by a space from a positive amount, 1. Otherwise, 0.

LOCALE_INEGSYMPRECEDES

If the monetary symbol precedes, 1. If it succeeds a negative amount, 0.

LOCALE_INEGSEPBYSPACE

If the monetary symbol is separated by a space from a negative amount, 1. Otherwise, 0.

AUTHORS/COPYRIGHT

This module is part of the Win32::OLE distribution.


#10 - Win32::OLE by Jan Dubois

  • INTRODUCTION
  • THE OLE MINDSET
  • WORKING WITH WIN32::OLE
    • THE FIRST STEP: CREATING AN OLE SERVER OBJECT
    • METHOD CALLS
    • PROPERTIES
    • SAMPLE APPLICATION
    • DOWNLOADING A WEB PAGE WITH LWP
    • MICROSOFT ACCESS
    • MICROSOFT EXCEL
    • ACTIVEX DATA OBJECTS
    • LOTUS NOTES
  • VARIANTS
  • FURTHER INFORMATION
    • DOCUMENTATION AND EXAMPLE CODE
    • OLE AUTOMATION ON OTHER PLATFORMS
  • COPYRIGHT

NAME

The Perl Journal #10 - Win32::OLE by Jan Dubois

INTRODUCTION

Suppose you're composing a document with Microsoft Word. You want to include an Excel spreadsheet. You could save the spreadsheet in some image format that Word can understand, and import it into your document. But if the spreadsheet changes, your document will be out of date.

Microsoft's OLE (Object Linking and Embedding, pronounced "olay") lets one program use objects from another. In the above scenario, the spreadsheet is the object. As long as Excel makes that spreadsheet available as an OLE object, and Word knows to treat it like one, your document will always be current.

You can control OLE objects from Perl with the Win32::OLE module, and that's what this article is about. First, I'll show you how to "think OLE," which mostly involves a lot of jargon. Next, I'll show you the mechanics involved in using Win32::OLE. Then we'll go through a Perl program that uses OLE to manipulate Microsoft Excel, Microsoft Access, and Lotus Notes. Finally, I'll talk about Variants, an internal OLE data type.

THE OLE MINDSET

When an application makes an OLE object available for other applications to use, that's called OLE automation. The program using the object is called the controller, and the application providing the object is called the server. OLE automation is guided by the OLE Component Object Model (COM) which specifies how those objects must behave if they are to be used by other processes and machines.

There are two different types of OLE automation servers. In-process servers are implemented as dynamic link libraries (DLLs) and run in the same process space as the controller. Out-of-process servers are more interesting; they are standalone executables that exist as separate processes - possibly on a different computer.

The Win32::OLE module lets your Perl program act as an OLE controller. It allows Perl to be used in place of other languages like Visual Basic or Java to control OLE objects. This makes all OLE automation servers immediately available as Perl modules.

Don't confuse ActiveState OLE with Win32::OLE. ActiveState OLE is completely different, although future builds of ActiveState Perl (500 and up) will work with Win32::OLE.

Objects can expose OLE methods, properties, and events to the outside world. Methods are functions that the controller can call to make the object do something; properties describe the state of the object; and events let the controller know about external events affecting the object, such as the user clicking on a button. Since events involve asynchronous communication with their objects, they require either threads or an event loop. They are not yet supported by the Win32::OLE module, and for the same reason ActiveX controls (OCXs) are currently unsupported as well.

WORKING WITH WIN32::OLE

The Win32::OLE module doesn't let your Perl program create OLE objects. What it does do is let your Perl program act like a remote control for other applications-it lets your program be an OLE controller. You can take an OLE object from another application (Access, Notes, Excel, or anything else that speaks OLE) and invoke its methods or manipulate its properties.

THE FIRST STEP: CREATING AN OLE SERVER OBJECT

First, we need to create a Perl object to represent the OLE server. This is a weird idea; what it amounts to is that if we want to control OLE objects produced by, say, Excel, we have to create a Perl object that represents Excel. So even though our program is an OLE controller, it'll contain objects that represent OLE servers.

You can create a new OLE server object with Win32::OLE->new. This takes a program ID (a human readable string like 'Speech.VoiceText') and returns a server object:

  my $server = Win32::OLE->new('Excel.Application', 'Quit');

Some server objects (particularly those for Microsoft Office applications) don't automatically terminate when your program no longer needs them. They need some kind of Quit method, and that's just what our second argument is. It can be either a code reference or a method name to be invoked when the object is destroyed. This lets you ensure that objects will be properly cleaned up even when the Perl program dies abnormally.

To access a server object on a different computer, replace the first argument with a reference to a list of the server name and program ID:

  my $server = Win32::OLE->new(['foo.bar.com',
                                'Excel.Application']);

(To get the requisite permissions, you'll need to configure your security settings with DCOMCNFG.EXE.)

You can also directly attach your program to an already running OLE server:

  my $server = Win32::OLE->GetActiveObject('Excel.Application');

This fails (returning undef) if no server exists, or if the server refuses the connection for some reason. It is also possible to use a persistent object moniker (usually a filename) to start the associated server and load the object into memory:

  my $doc = Win32::OLE->GetObject("MyDocument.Doc");

METHOD CALLS

Once you've created one of these server objects, you need to call its methods to make the OLE objects sing and dance. OLE methods are invoked just like normal Perl object methods:

  $server->Foo(@Arguments);

This is a Perl method call - but it also triggers an OLE method call in the object. After your program executes this statement, the $server object will execute its Foo() method. The available methods are typically documented in the application's object model.

Parameters. By default, all parameters are positional (e.g. foo($first, $second, $third)) rather than named (e.g. foo(-name => "Yogi", -title => "Coach")). The required parameters come first, followed by the optional parameters; if you need to provide a dummy value for an optional parameter, use undef.

Positional parameters get cumbersome if a method takes a lot of them. You can use named arguments instead if you go to a little extra trouble - when the last argument is a reference to a hash, the key/value pairs of the hash are treated as named parameters:

  $server->Foo($Pos1, $Pos2, {Name1 => $Value1,
                              Name2 => $Value2});

Foreign Languages and Default Methods. Sometimes OLE servers use method and property names that are specific to a non-English locale. That means they might have non-ASCII characters, which aren't allowed in Perl variable names. In German, you might see Öffnen used instead of Open. In these cases, you can use the Invoke() method:

  $server->Invoke('Öffnen', @Arguments);

This is necessary because $Server->Öffnen(@Arguments) is a syntax error in current versions of Perl.

PROPERTIES

As I said earlier, objects can expose three things to the outside world: methods, properties, and events. We've covered methods, and Win32::OLE can't handle events. That leaves properties. But as it turns out, properties and events are largely interchangeable. Most methods have corresponding properties, and vice versa.

An object's properties can be accessed with a hash reference:

  $server->{Bar} = $value;
  $value = $server->{Bar};

This example sets and queries the value of the property named Bar. You could also have called the object's Bar() method to achieve the same effect:

  $value = $server->Bar;

However, you can't write the first line as $server->Bar = $value, because you can't assign to the return value of a method call. In Visual Basic, OLE automation distinguishes between assigning the name of an object and assigning its value:

  Set Object = OtherObject
  Let Value = Object

The Set statement shown here makes Object refer to the same object as OtherObject. The Let statement copies the value instead. (The value of an OLE object is what you get when you call the object's default method.

In Perl, saying $server1 = $server2 always creates another reference, just like the Set in Visual Basic. If you want to assign the value instead, use the valof() function:

  my $value = valof $server;

This is equivalent to

  my $value = $server->Invoke('');

SAMPLE APPLICATION

Let's look at how all of this might be used. In Listing: 1 you'll see T-Bond.pl, a program that uses Win32::OLE for an almost-real world application.

The developer of this application, Mary Lynch, is a financial futures broker. Every afternoon, she connects to the Chicago Board of Trade (CBoT) web site at http://www.cbot.com and collects the time and sales information for U.S. T-bond futures. She wants her program to create a chart that depicts the data in 15-minute intervals, and then she wants to record the data in a database for later analysis. Then she wants her program to send mail to her clients.

Mary's program will use Microsoft Access as a database, Microsoft Excel to produce the chart, and Lotus Notes to send the mail. It will all be controlled from a single Perl program using OLE automation. In this section, we'll go through T-Bond. pl step by step so you can see how Win32::OLE lets you control these applications.

DOWNLOADING A WEB PAGE WITH LWP

However, Mary first needs to amass the raw T-bond data by having her Perl program automatically download and parse a web page. That's the perfect job for LWP, the libwww-perl bundle available on the CPAN. LWP has nothing to do with OLE. But this is a real-world application, and it's just what Mary needs to download her data from the Chicago Board of Trade.

  use LWP::Simple;
  my $URL = 'http://www.cbot.com/mplex/quotes/tsfut';
  my $text = get("$URL/tsf$Contract.htm");

She could also have used the Win32::Internet module:

  use Win32::Internet;
  my $URL = 'http://www.cbot.com/mplex/quotes/tsfut';
  my $text = $Win32::Internet->new->FetchURL("$URL/tsf$Contract.htm");

Mary wants to condense the ticker data into 15 minute bars. She's interested only in lines that look like this:

  03/12/1998 US 98Mar 12116 15:28:34 Open

A regular expression can be used to determine whether a line looks like this. If it does, the regex can split it up into individual fields. The price quoted above, 12116, really means 121 16/32, and needs to be converted to 121.5. The data is then condensed into 15 minute intervals and only the first, last, highest, and lowest price during each interval are kept. The time series is stored in the array @Bars. Each entry in @Bars is a reference to a list of 5 elements: Time, Open, High, Low, and Close.

  foreach (split "\n", $text) {
      # 03/12/1998 US 98Mar 12116 15:28:34 Open
      my ($Date,$Price,$Hour,$Min,$Sec,$Ind) =
           m|^\s*(\d+/\d+/\d+) # " 03/12/1998"
              \s+US\s+\S+\s+(\d+) # " US 98Mar 12116"
              \s+(\d+):(\d+):(\d+) # " 12:42:40"
              \s*(.*)$|x; # " Ask"
      next unless defined $Date;
      $Day = $Date;

      # Convert from fractional to decimal format
      $Price = int($Price/100) + ($Price%100)/32;

      # Round up time to next multiple of 15 minutes
      my $NewTime = int(($Sec+$Min*60+$Hour*3600)/900+1)*900;
      unless (defined $Time && $NewTime == $Time) {
          push @Bars, [$hhmm, $Open, $High, $Low, $Close]
                                            if defined $Time;
          $Open = $High = $Low = $Close = undef;
          $Time = $NewTime;
          my $Hour = int($Time/3600);
          $hhmm = sprintf "%02d:%02d", $Hour, $Time/60-$Hour*60;
      }

      # Update 15 minute bar values
      $Close = $Price;
      $Open = $Price unless defined $Open;
      $High = $Price unless defined $High && $High > $Price;
      $Low = $Price unless defined $Low && $Low > $Price;
        }

  die "No data found" unless defined $Time;
  push @Bars, [$hhmm, $Open, $High, $Low, $Close];

MICROSOFT ACCESS

Now that Mary has her T-bond quotes, she's ready to use Win32::OLE to store them into a Microsoft Access database. This has the advantage that she can copy the database to her lap-top and work with it on her long New York commute. She's able to create an Access database as follows:

  use Win32::ODBC;
  use Win32::OLE;

  # Include the constants for the Microsoft Access
  # "Data Access Object".

  use Win32::OLE::Const 'Microsoft DAO';

  my $DSN      = 'T-Bonds';
  my $Driver   = 'Microsoft Access Driver (*.mdb)';
  my $Desc     = 'US T-Bond Quotes';
  my $Dir      = 'i:\tmp\tpj';
  my $File     = 'T-Bonds.mdb';
  my $Fullname = "$Dir\\$File";

  # Remove old database and dataset name
  unlink $Fullname if -f $Fullname;
  Win32::ODBC::ConfigDSN(ODBC_REMOVE_DSN, $Driver, "DSN=$DSN")
                         if Win32::ODBC::DataSources($DSN);

  # Create new database
  my $Access = Win32::OLE->new('Access.Application', 'Quit');
  my $Workspace = $Access->DBEngine->CreateWorkspace('', 'Admin', '');
  my $Database = $Workspace->CreateDatabase($Fullname, dbLangGeneral);

  # Add new database name
  Win32::ODBC::ConfigDSN(ODBC_ADD_DSN, $Driver,
          "DSN=$DSN", "Description=$Desc", "DBQ=$Fullname",
          "DEFAULTDIR=$Dir", "UID=", "PWD=");

This uses Win32::ODBC (described in TPJ #9) to remove and create T-Bonds.mdb. This lets Mary use the same script on her workstation and on her laptop even when the database is stored in different locations on each. The program also uses Win32::OLE to make Microsoft Access create an empty database.

Every OLE server has some constants that your Perl program will need to use, made accessible by the Win32::OLE::Const module. For instance, to grab the Excel constants, say use Win32::OLE::Const 'Microsoft Excel'.

In the above example, we imported the Data Access Object con-stants just so we could use dbLangGeneral.

MICROSOFT EXCEL

Now Mary uses Win32::OLE a second time, to have Microsoft Excel create the chart shown below.

  Figure 1: T-Bond data generated by MicroSoft Excel via Win32::OLE
  # Start Excel and create new workbook with a single sheet
  use Win32::OLE qw(in valof with);
  use Win32::OLE::Const 'Microsoft Excel';
  use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG);

  my $lgid = MAKELANGID(LANG_ENGLISH, SUBLANG_DEFAULT);
  $Win32::OLE::LCID = MAKELCID($lgid);

  $Win32::OLE::Warn = 3;

Here, Mary sets the locale to American English, which lets her do things like use American date formats (e.g. "12-30-98" rather than "30-12-98") in her program. It will continue to work even when she's visiting one of her international customers and has to run this program on their computers.

The value of $Win32::OLE::Warn determines what happens when an OLE error occurs. If it's 0, the error is ignored. If it's 2, or if it's 1 and the script is running under -w, the Win32::OLE module invokes Carp::carp(). If $Win32::OLE::Warn is set to 3, Carp::croak() is invoked and the program dies immediately.

Now the data can be put into an Excel spreadsheet to produce the chart. The following section of the program launches Excel and creates a new workbook with a single worksheet. It puts the column titles ('Time', 'Open', 'High', 'Low', and 'Close') in a bold font on the first row of the sheet. The first column displays the timestamp in hh:mm format; the next four display prices.

  my $Excel = Win32::OLE->new('Excel.Application', 'Quit');
  $Excel->{SheetsInNewWorkbook} = 1;
  my $Book = $Excel->Workbooks->Add;
  my $Sheet = $Book->Worksheets(1);
  $Sheet->{Name} = 'Candle';

  # Insert column titles
  my $Range = $Sheet->Range("A1:E1");
  $Range->{Value} = [qw(Time Open High Low Close)];
  $Range->Font->{Bold} = 1;

  $Sheet->Columns("A:A")->{NumberFormat} = "h:mm";
  # Open/High/Low/Close to be displayed in 32nds
  $Sheet->Columns("B:E")->{NumberFormat} = "# ?/32";

  # Add 15 minute data to spreadsheet
  print "Add data\n";
  $Range = $Sheet->Range(sprintf "A2:E%d", 2+$#Bars);
  $Range->{Value} = \@Bars;

The last statement shows how to pass arrays to OLE objects. The Win32::OLE module automatically translates each array reference to a SAFEARRAY, the internal OLE array data type. This translation first determines the maximum nesting level used by the Perl array, and then creates a SAFEARRAY of the same dimension. The @Bars array already contains the data in the correct form for the spreadsheet:

  ([Time1, Open1, High1, Low1, Close1],
  ...
  [TimeN, OpenN, HighN, LowN, CloseN])

Now the table in the spreadsheet can be used to create a candle stick chart from our bars. Excel automatically chooses the time axis labels if they are selected before the chart is created:

  # Create candle stick chart as new object on worksheet
  $Sheet->Range("A:E")->Select;

  my $Chart = $Book->Charts->Add;
  $Chart->{ChartType} = xlStockOHLC;
  $Chart->Location(xlLocationAsObject, $Sheet->{Name});
  # Excel bug: the old $Chart is now invalid!
  $Chart = $Excel->ActiveChart;

We can change the type of the chart from a separate sheet to a chart object on the spreadsheet page with the $Chart->Location method. (This invalidates the chart object handle, which might be considered a bug in Excel.) Fortunately, this new chart is still the 'active' chart, so an object handle to it can be reclaimed simply by asking Excel.

At this point, our chart still needs a title, the legend is meaningless, and the axis has decimals instead of fractions. We can fix those with the following code:

  # Add title, remove legend
  with($Chart, HasLegend => 0, HasTitle => 1);
  $Chart->ChartTitle->Characters->{Text} = "US T-Bond";

  # Set up daily statistics
  $Open  = $Bars[0][1];
  $High  = $Sheet->Evaluate("MAX(C:C)");
  $Low   = $Sheet->Evaluate("MIN(D:D)");
  $Close = $Bars[$#Bars][4];

The with() function partially mimics the Visual Basic With statement, but allows only property assignments. It's a convenient shortcut for this:

  { # open new scope
    my $Axis = $Chart->Axes(xlValue);
    $Axis->{HasMajorGridlines} = 1;
    $Axis->{HasMinorGridlines} = 1;
    # etc ...
  }

The $High and $Low for the day are needed to determine the minimum and maximum scaling levels. MIN and MAX are spreadsheet functions, and aren't automatically available as methods. However, Excel provides an Evaluate() method to calculate arbitrary spreadsheet functions, so we can use that.

We want the chart to show major gridlines at every fourth tick and minor gridlines at every second tick. The minimum and maximum are chosen to be whatever multiples of 1/16 we need to do that.

  # Change tickmark spacing from decimal to fractional
  with($Chart->Axes(xlValue),
      HasMajorGridlines => 1,
      HasMinorGridlines => 1,
      MajorUnit => 1/8,
      MinorUnit => 1/16,
      MinimumScale => int($Low*16)/16,
      MaximumScale => int($High*16+1)/16
  );

  # Fat candles with only 5% gaps
  $Chart->ChartGroups(1)->{GapWidth} = 5;

  sub RGB { $_[0] | ($_[1] >> 8) | ($_[2] >> 16) }

  # White background with a solid border

  $Chart->PlotArea->Border->{LineStyle} = xlContinuous;
  $Chart->PlotArea->Border->{Color} = RGB(0,0,0);
  $Chart->PlotArea->Interior->{Color} = RGB(255,255,255);

  # Add 1 hour moving average of the Close series
  my $MovAvg = $Chart->SeriesCollection(4)->Trendlines
        ->Add({Type => xlMovingAvg, Period => 4});
  $MovAvg->Border->{Color} = RGB(255,0,0);

Now the finished workbook can be saved to disk as i:\tmp\tpj\data.xls. That file most likely still exists from when the program ran yesterday, so we'll remove it. (Otherwise, Excel would pop up a dialog with a warning, because the SaveAs() method doesn't like to overwrite files.)

  # Save workbook to file my $Filename = 'i:\tmp\tpj\data.xls';
  unlink $Filename if -f $Filename;
  $Book->SaveAs($Filename);
  $Book->Close;

ACTIVEX DATA OBJECTS

Mary stores the daily prices in her T-bonds database, keeping the data for the different contracts in separate tables. After creating an ADO (ActiveX Data Object) connection to the database, she tries to connect a record set to the table for the current contract. If this fails, she assumes that the table doesn't exists yet and tries to create it:

  use Win32::OLE::Const 'Microsoft ActiveX Data Objects';

  my $Connection = Win32::OLE->new('ADODB.Connection');
  my $Recordset = Win32::OLE->new('ADODB.Recordset');
  $Connection->Open('T-Bonds');

  # Open a record set for the table of this contract
  {
    local $Win32::OLE::Warn = 0;
    $Recordset->Open($Contract, $Connection, adOpenKeyset,
                         adLockOptimistic, adCmdTable);
  }

  # Create table and index if it doesn't exist yet
  if (Win32::OLE->LastError) {
      $Connection->Execute(<<"SQL");
        CREATE TABLE $Contract
        (
          Day DATETIME,
          Open DOUBLE, High DOUBLE, Low DOUBLE, Close DOUBLE
        )
  SQL
      $Connection->Execute(<<"SQL");
        CREATE INDEX $Contract
        ON $Contract (Day) WITH PRIMARY
  SQL
      $Recordset->Open($Contract, $Connection, adOpenKeyset,
                                adLockOptimistic, adCmdTable);
  }

$Win32::OLE::Warn is temporarily set to zero, so that if $Recordset-Open> fails, the failure will be recorded silently without terminating the program. Win32::OLE-LastError> shows whether the Open failed or not. LastError returns the OLE error code in a numeric context and the OLE error message in a string context, just like Perl's $! variable.

Now Mary can add today's data:

  # Add new record to table
  use Win32::OLE::Variant;
  $Win32::OLE::Variant::LCID = $Win32::OLE::LCID;

  my $Fields = [qw(Day Open High Low Close)];
  my $Values = [Variant(VT_DATE, $Day),
                $Open, $High, $Low, $Close];

Mary uses the Win32::OLE::Variant module to store $Day as a date instead of a mere string. She wants to make sure that it's stored as an American-style date, so in the third line shown here she sets the locale ID of the Win32::OLE::Variant module to match the Win32::OLE module. ($Win32::OLE::LCID had been set earlier to English, since that's what the Chicago Board of Trade uses.)

  {
      local $Win32::OLE::Warn = 0;
      $Recordset->AddNew($Fields, $Values);
  }

  # Replace existing record
  if (Win32::OLE->LastError) {
      $Recordset->CancelUpdate;
      $Recordset->Close;
      $Recordset->Open(<<"SQL", $Connection, adOpenDynamic);
          SELECT * FROM $Contract
          WHERE Day = #$Day#
  SQL
      $Recordset->Update($Fields, $Values);
  }

  $Recordset->Close;
  $Connection->Close;

The program expects to be able to add a new record to the table. It fails if a record for this date already exists, because the Day field is the primary index and therefore must be unique. If an error occurs, the update operation started by AddNew() must first be cancelled with $Recordset->CancelUpdate; otherwise the record set won't close.

LOTUS NOTES

Now Mary can use Lotus Notes to mail updates to all her customers interested in the T-bond data. (Lotus Notes doesn't provide its constants in the OLE type library, so Mary had to determine them by playing around with LotusScript.) The actual task is quite simple: A Notes session must be started, the mail database must be opened and the mail message must be created. The body of the message is created as a rich text field, which lets her mix formatted text with object attachments.

In her program, Mary extracts the email addresses from her customer database and sends separate message to each. Here, we've simplified it somewhat.

  sub EMBED_ATTACHMENT {1454;}     # from LotusScript

  my $Notes = Win32::OLE->new('Notes.NotesSession');
  my $Database = $Notes->GetDatabase('', '');
  $Database->OpenMail;
  my $Document = $Database->CreateDocument;

  $Document->{Form} = 'Memo';
  $Document->{SendTo} = ['Jon Orwant >orwant@tpj.com>',
                         'Jan Dubois >jan.dubois@ibm.net>'];
  $Document->{Subject} = "US T-Bonds Chart for $Day";

  my $Body = $Document->CreateRichtextItem('Body');
  $Body->AppendText(<<"EOT");
  I\'ve attached the latest US T-Bond data and chart for $Day.
  The daily statistics were:

  \tOpen\t$Open
  \tHigh\t$High
  \tLow\t$Low
  \tClose\t$Close
  Kind regards,
  Mary
  EOT
  $Body->EmbedObject(EMBED_ATTACHMENT, '', $Filename);

  $Document->Send(0);

VARIANTS

In this final section, I'll talk about Variants, which are the data types that you use to talk to OLE objects. We talked about this line earlier:

  my $Values = [Variant(VT_DATE, $Day),
                $Open, $High, $Low, $Close];

Here, the Variant() function creates a Variant object, of type VT_DATE and with the value $Day. Variants are similar in many ways to Perl scalars. Arguments to OLE methods are transparently converted from their internal Perl representation to Variants and back again by the Win32::OLE module.

OLE automation uses a generic VARIANT data type to pass parameters. This data type contains type information in addition to the actual data value. Only the following data types are valid for OLE automation:

  B<Data Type     Meaning>
  VT_EMPTY      Not specified
  VT_NULL       Null
  VT_I2         2 byte signed integer
  VT_I4         4 byte signed integer
  VT_R4         4 byte real
  VT_R8         8 byte real
  VT_CY         Currency
  VT_DATE       Date
  VT_BSTR       Unicode string
  VT_DISPATCH   OLE automation interface
  VT_ERROR      Error
  VT_BOOL       Boolean
  VT_VARIANT    (only valid with VT_BYREF)
  VT_UNKNOWN    Generic COM interface
  VT_UI1        Unsigned character

The following two flags can also be used:

  VT_ARRAY      Array of values
  VT_BYREF      Pass by reference (instead of by value)

The Perl to Variant transformation. The following conversions are performed automatically whenever a Perl value must be translated into a Variant:

  Perl value                  Variant
  Integer values              VT_I4
  Real values                 VT_R8
  Strings                     VT_BSTR
  undef                       VT_ERROR (DISP_E_PARAMNOTFOUND)
  Array reference             VT_VARIANT | VT_ARRAY
  Win32::OLE object           VT_DISPATCH
  Win32::OLE::Variant object  Type of the Variant object

What if your Perl value is a list of lists? Those can be irregularly shaped in Perl; that is, the subsidiary lists needn't have the same number of elements. In this case, the structure will be converted to a "rectangular" SAFEARRAY of Variants, with unused slots set to VT_EMPTY. Consider this Perl 2-D array:

  [ ["Perl" ],            # one element
    [1, 3.1215, undef]    # three elements
  ]

This will be translated to a 2 by 3 SAFEARRAY that looks like this:

  VT_BSTR("Perl") VT_EMPTY      VT_EMPTY
  VT_I4(1) VT_R8(3.1415)        VT_ERROR(DISP_E_PARAMNOTFOUND)

The Variant To Perl Transformation. Automatic conversion from Variants to Perl values happens as follows:

  Variant                Perl value
  VT_BOOL, VT_ERROR      Integer
  VT_UI1, VT_I2, VT_I4   Integer
  VT_R4, VT_R8           Float value
  VT_BSTR                String
  VT_DISPATCH            Win32::OLE object

The Win32::OLE::Variant module. This module provides access to the Variant data type, which gives you more control over how these arguments to OLE methods are encoded. (This is rarely necessary if you have a good grasp of the default conversion rules.) A Variant object can be created with the Win32::OLE::Variant->new method or the equivalent Variant() function:

  use Win32::OLE::Variant;
  my $var1 = Win32::OLE::Variant->new(VT_DATE, 'Jan 1,1970');
  my $var2 = Variant(VT_BSTR, 'This is an Unicode string');

Several methods let you inspect and manipulate Variant objects: The Type() and Value() methods return the variant type and value; the As() method returns the value after converting it to a different variant type; ChangeType() coerces the Variant into a different type; and Unicode() returns the value of a Variant object as an object of the Unicode::String class.

These conversions are more interesting if they can be applied directly to the return value of an OLE method call without first mutilating the value with default conversions. This is possible with the following trick:

  my $RetVal = Variant(VT_EMPTY, undef);
  $Object->Dispatch($Method, $RetVal, @Arguments);

Normally, you wouldn't call Dispatch() directly; it's executed implicitly by either AUTOLOAD() or Invoke(). If Dispatch() realizes that the return value is already a Win32::OLE::Variant object, the return value is not translated into a Perl representation but rather copied verbatim into the Variant object.

Whenever a Win32::OLE::Variant object is used in a numeric or string context it is automatically converted into the corresponding format.

  printf "Number: %f and String: %s\n",
         $Var, $Var;

This is equivalent to:

  printf "Number: %f and String: %s\n",
         $Var->As(VT_R8), $Var->As(VT_BSTR);

For methods that modify their arguments, you need to use the VT_BYREF flag. This lets you create number and string Variants that can be modified by OLE methods. Here, Corel's GetSize() method takes two integers and stores the x and y dimensions in them:

  my $x = Variant( VT_I4 | VT_BYREF, 0);
  my $y = Variant( VT_I4 | VT_BYREF, 0);
  $Corel->GetSize($x, $y);

VT_BYREF support for other Variant types might appear in future releases of Win32::OLE.

FURTHER INFORMATION

DOCUMENTATION AND EXAMPLE CODE

More information about the OLE modules can be found in the documentation bundled with Win32::OLE. The distribution also contains other code samples.

The object model for Microsoft Office applications can be found in the Visual Basic Reference for Microsoft Access, Excel, Word, or PowerPoint. These help files are not installed by default, but they can be added later by rerunning setup.exe and choosing custom setup. The object model for Microsoft Outlook can be found on the Microsoft Office Developer Forum at: http://www.microsoft.com/OutlookDev/.

Information about the LotusScript object model can be found at: http://www.lotus.com/products/lotusscript.nsf.

OLE AUTOMATION ON OTHER PLATFORMS

Microsoft also makes OLE technology available for the Mac. DCOM is already included in Windows NT 4.0 and can be downloaded for Windows 95. MVS and some Unix systems can use EntireX to get OLE functionality; see http://www.softwareag.com/corporat/solutions/entirex/entirex.htm.

COPYRIGHT

Copyright 1998 The Perl Journal. http://www.tpj.com

This article originally appeared in The Perl Journal #10. It appears courtesy of Jon Orwant and The Perl Journal. This document may be distributed under the same terms as Perl itself.


Win32::OLE::Variant - Create and modify OLE VARIANT variables

    • Functions
    • Methods
    • Overloading
    • Class Variables
    • Constants
    • Variants
    • Variant arrays
    • Variants by reference
  • AUTHORS/COPYRIGHT

NAME

Win32::OLE::Variant - Create and modify OLE VARIANT variables

SYNOPSIS

        use Win32::OLE::Variant;
        my $var = Variant(VT_DATE, 'Jan 1,1970');
        $OleObject->{value} = $var;
        $OleObject->Method($var);

DESCRIPTION

The IDispatch interface used by the Perl OLE module uses a universal argument type called VARIANT. This is basically an object containing a data type and the actual data value. The data type is specified by the VT_xxx constants.

Functions

nothing()

The nothing() function returns an empty VT_DISPATCH variant. It can be used to clear an object reference stored in a property

        use Win32::OLE::Variant qw(:DEFAULT nothing);
        # ...
        $object->{Property} = nothing;

This has the same effect as the Visual Basic statement

        Set object.Property = Nothing

The nothing() function is not exported by default.

nullstring()

The nullstring() function returns a VT_BSTR variant with a NULL string pointer. This is not the same as a VT_BSTR variant with an empty string "". The nullstring() value is the same as the vbNullString constant in Visual Basic.

The nullstring() function is not exported by default.

Variant(TYPE, DATA)

This is just a function alias of the Win32::OLE::Variant-new()> method (see below). This function is exported by default.

Methods

new(TYPE, DATA)

This method returns a Win32::OLE::Variant object of the specified TYPE that contains the given DATA. The Win32::OLE::Variant object can be used to specify data types other than IV, NV or PV (which are supported transparently). See Variants below for details.

For VT_EMPTY and VT_NULL variants, the DATA argument may be omitted. For all non-VT_ARRAY variants DATA specifies the initial value.

To create a SAFEARRAY variant, you have to specify the VT_ARRAY flag in addition to the variant base type of the array elemnts. In this cases DATA must be a list specifying the dimensions of the array. Each element can be either an element count (indices 0 to count-1) or an array reference pointing to the lower and upper array bounds of this dimension:

        my $Array = Win32::OLE::Variant->new(VT_ARRAY|VT_R8, [1,2], 2);

This creates a 2-dimensional SAFEARRAY of doubles with 4 elements: (1,0), (1,1), (2,0) and (2,1).

A special case is the the creation of one-dimensional VT_UI1 arrays with a string DATA argument:

        my $String = Variant(VT_ARRAY|VT_UI1, "String");

This creates a 6 element character array initialized to "String". For backward compatibility VT_UI1 with a string initializer automatically implies VT_ARRAY. The next line is equivalent to the previous example:

        my $String = Variant(VT_UI1, "String");

If you really need a single character VT_UI1 variant, you have to create it using a numeric intializer:

        my $Char = Variant(VT_UI1, ord('A'));
As(TYPE)

As converts the VARIANT to the new type before converting to a Perl value. This take the current LCID setting into account. For example a string might contain a ',' as the decimal point character. Using $variant-As(VT_R8)> will correctly return the floating point value.

The underlying variant object is NOT changed by this method.

ChangeType(TYPE)

This method changes the type of the contained VARIANT in place. It returns the object itself, not the converted value.

Copy([DIM])

This method creates a copy of the object. If the original variant had the VT_BYREF bit set then the new object will contain a copy of the referenced data and not a reference to the same old data. The new object will not have the VT_BYREF bit set.

        my $Var = Variant(VT_I4|VT_ARRAY|VT_BYREF, [1,5], 3);
        my $Copy = $Var->Copy;

The type of $Copy is now VT_I4|VT_ARRAY and the value is a copy of the other SAFEARRAY. Changes to elements of $Var will not be reflected in $Copy and vice versa.

The Copy method can also be used to extract a single element of a VT_ARRAY | VT_VARIANT object. In this case the array indices must be specified as a list DIM:

        my $Int = $Var->Copy(1, 2);

$Int is now a VT_I4 Variant object containing the value of element (1,2).

Currency([FORMAT[, LCID]])

This method converts the VARIANT value into a formatted curency string. The FORMAT can be either an integer constant or a hash reference. Valid constants are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE from the Win32::OLE::NLS module:

        use Win32::OLE::NLS qw(:LOCALE);

LOCALE_NOUSEROVERRIDE tells the method to use the system default currency format for the specified locale, disregarding any changes that might have been made through the control panel application.

The hash reference could contain the following keys:

        NumDigits       number of fractional digits
        LeadingZero     whether to use leading zeroes in decimal fields
        Grouping        size of each group of digits to the left of the decimal
        DecimalSep      decimal separator string
        ThousandSep     thousand separator string
        NegativeOrder   see L<Win32::OLE::NLS/LOCALE_ICURRENCY>
        PositiveOrder   see L<Win32::OLE::NLS/LOCALE_INEGCURR>
        CurrencySymbol  currency symbol string

For example:

        use Win32::OLE::Variant;
        use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG :DATE :TIME);
        my $lcidGerman = MAKELCID(MAKELANGID(LANG_GERMAN, SUBLANG_NEUTRAL));
        my $v = Variant(VT_CY, "-922337203685477.5808");
        print $v->Currency({CurrencySymbol => "Tuits"}, $lcidGerman), "\n";

will print:

        -922.337.203.685.477,58 Tuits
Date([FORMAT[, LCID]])

Converts the VARIANT into a formatted date string. FORMAT can be either one of the following integer constants or a format string:

        LOCALE_NOUSEROVERRIDE   system default date format for this locale
        DATE_SHORTDATE          use the short date format (default)
        DATE_LONGDATE           use the long date format
        DATE_YEARMONTH          use the year/month format
        DATE_USE_ALT_CALENDAR   use the alternate calendar, if one exists
        DATE_LTRREADING         left-to-right reading order layout
        DATE_RTLREADING         right-to left reading order layout

The constants are available from the Win32::OLE::NLS module:

        use Win32::OLE::NLS qw(:LOCALE :DATE);

The following elements can be used to construct a date format string. Characters must be specified exactly as given below (e.g. "dd" not "DD"). Spaces can be inserted anywhere between formating codes, other verbatim text should be included in single quotes.

        d       day of month
        dd      day of month with leading zero for single-digit days
        ddd     day of week: three-letter abbreviation (LOCALE_SABBREVDAYNAME)
        dddd    day of week: full name (LOCALE_SDAYNAME)
        M       month
        MM      month with leading zero for single-digit months
        MMM     month: three-letter abbreviation (LOCALE_SABBREVMONTHNAME)
        MMMM    month: full name (LOCALE_SMONTHNAME)
        y       year as last two digits
        yy      year as last two digits with leading zero for years less than 10
        yyyy    year represented by full four digits
        gg      period/era string

For example:

        my $v = Variant(VT_DATE, "April 1 99");
        print $v->Date(DATE_LONGDATE), "\n";
        print $v->Date("ddd',' MMM dd yy"), "\n";

will print:

        Thursday, April 01, 1999
        Thu, Apr 01 99
Dim()

Returns a list of array bounds for a VT_ARRAY variant. The list contains an array reference for each dimension of the variant's SAFEARRAY. This reference points to an array containing the lower and upper bounds for this dimension. For example:

        my @Dim = $Var->Dim;

Now @Dim contains the following list: ([1,5], [0,2]).

Get(DIM)

For normal variants Get returns the value of the variant, just like the Value method. For VT_ARRAY variants Get retrieves the value of a single array element. In this case DIM must be a list of array indices. E.g.

        my $Val = $Var->Get(2,0);

As a special case for one dimensional VT_UI1|VT_ARRAY variants the Get method without arguments returns the character array as a Perl string.

        print $String->Get, "\n";
IsNothing()

Tests if the object is an empty VT_DISPATCH variant. See also nothing().

IsNullString()

Tests if the object is an empty VT_BSTR variant. See also nullstring().

LastError()

The use of the Win32::OLE::Variant-LastError()> method is deprecated. Please use the Win32::OLE-LastError()> class method instead.

Number([FORMAT[, LCID]])

This method converts the VARIANT value into a formatted number string. The FORMAT can be either an integer constant or a hash reference. Valid constants are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE from the Win32::OLE::NLS module:

        use Win32::OLE::NLS qw(:LOCALE);

LOCALE_NOUSEROVERRIDE tells the method to use the system default number format for the specified locale, disregarding any changes that might have been made through the control panel application.

The hash reference could contain the following keys:

        NumDigits       number of fractional digits
        LeadingZero     whether to use leading zeroes in decimal fields
        Grouping        size of each group of digits to the left of the decimal
        DecimalSep      decimal separator string
        ThousandSep     thousand separator string
        NegativeOrder   see L<Win32::OLE::NLS/LOCALE_INEGNUMBER>
Put(DIM, VALUE)

The Put method is used to assign a new value to a variant. The value will be coerced into the current type of the variant. E.g.:

        my $Var = Variant(VT_I4, 42);
        $Var->Put(3.1415);

This changes the value of the variant to 3 because the type is VT_I4.

For VT_ARRAY type variants the indices for each dimension of the contained SAFEARRAY must be specified in front of the new value:

        $Array->Put(1, 1, 2.7);

It is also possible to assign values to *every* element of the SAFEARRAY at once using a single Put() method call:

        $Array->Put([[1,2], [3,4]]);

In this case the argument to Put() must be an array reference and the dimensions of the Perl list-of-lists must match the dimensions of the SAFEARRAY exactly.

The are a few special cases for one-dimensional VT_UI1 arrays: The VALUE can be specified as a string instead of a number. This will set the selected character to the first character of the string or to '\0' if the string was empty:

        my $String = Variant(VT_UI1|VT_ARRAY, "ABCDE");
        $String->Put(1, "123");
        $String->Put(3, ord('Z'));
        $String->Put(4, '');

This will set the value of $String to "A1CZ\0". If the index is omitted then the string is copied to the value completely. The string is truncated if it is longer than the size of the VT_UI1 array. The result will be padded with '\0's if the string is shorter:

        $String->Put("String");

Now $String contains the value "Strin".

Put returns the Variant object itself so that multiple Put calls can be chained together:

        $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
Time([FORMAT[, LCID]])

Converts the VARIANT into a formatted time string. FORMAT can be either one of the following integer constants or a format string:

        LOCALE_NOUSEROVERRIDE   system default time format for this locale
        TIME_NOMINUTESORSECONDS don't use minutes or seconds
        TIME_NOSECONDS          don't use seconds
        TIME_NOTIMEMARKER       don't use a time marker
        TIME_FORCE24HOURFORMAT  always use a 24-hour time format

The constants are available from the Win32::OLE::NLS module:

        use Win32::OLE::NLS qw(:LOCALE :TIME);

The following elements can be used to construct a time format string. Characters must be specified exactly as given below (e.g. "dd" not "DD"). Spaces can be inserted anywhere between formating codes, other verbatim text should be included in single quotes.

        h       hours; 12-hour clock
        hh      hours with leading zero for single-digit hours; 12-hour clock
        H       hours; 24-hour clock
        HH      hours with leading zero for single-digit hours; 24-hour clock
        m       minutes
        mm      minutes with leading zero for single-digit minutes
        s       seconds
        ss      seconds with leading zero for single-digit seconds
        t       one character time marker string, such as A or P
        tt      multicharacter time marker string, such as AM or PM

For example:

        my $v = Variant(VT_DATE, "April 1 99 2:23 pm");
        print $v->Time, "\n";
        print $v->Time(TIME_FORCE24HOURFORMAT|TIME_NOTIMEMARKER), "\n";
        print $v->Time("hh.mm.ss tt"), "\n";

will print:

        2:23:00 PM
        14:23:00
        02.23.00 PM
Type()

The Type method returns the variant type of the contained VARIANT.

Unicode()

The Unicode method returns a Unicode::String object. This contains the BSTR value of the variant in network byte order. If the variant is not currently in VT_BSTR format then a VT_BSTR copy will be produced first.

Value()

The Value method returns the value of the VARIANT as a Perl value. The conversion is performed in the same manner as all return values of Win32::OLE method calls are converted.

Overloading

The Win32::OLE::Variant package has overloaded the conversion to string and number formats. Therefore variant objects can be used in arithmetic and string operations without applying the Value method first.

Class Variables

The Win32::OLE::Variant class used to have its own set of class variables like $CP, $LCID and $Warn. In version 0.1003 and later of the Win32::OLE module these variables have been eleminated. Now the settings of Win32::OLE are used by the Win32::OLE::Variant module too. Please read the documentation of the Win32::OLE-&gt;Option class method.

Constants

These constants are exported by default:

        VT_EMPTY
        VT_NULL
        VT_I2
        VT_I4
        VT_R4
        VT_R8
        VT_CY
        VT_DATE
        VT_BSTR
        VT_DISPATCH
        VT_ERROR
        VT_BOOL
        VT_VARIANT
        VT_UNKNOWN
        VT_DECIMAL
        VT_UI1
        VT_ARRAY
        VT_BYREF

VT_DECIMAL is not on the official list of allowable OLE Automation datatypes. But even Microsoft ADO seems to sometimes return values of Recordset fields in VT_DECIMAL format.

Variants

A Variant is a data type that is used to pass data between OLE connections.

The default behavior is to convert each perl scalar variable into an OLE Variant according to the internal perl representation. The following type correspondence holds:

        C type          Perl type       OLE type
        ------          ---------       --------
          int              IV            VT_I4
        double             NV            VT_R8
        char *             PV            VT_BSTR
        void *           ref to AV       VT_ARRAY
           ?              undef          VT_ERROR
           ?        Win32::OLE object    VT_DISPATCH

Note that VT_BSTR is a wide character or Unicode string. This presents a problem if you want to pass in binary data as a parameter as 0x00 is inserted between all the bytes in your data. The Variant() method provides a solution to this. With Variants the script writer can specify the OLE variant type that the parameter should be converted to. Currently supported types are:

        VT_UI1     unsigned char
        VT_I2      signed int (2 bytes)
        VT_I4      signed int (4 bytes)
        VT_R4      float      (4 bytes)
        VT_R8      float      (8 bytes)
        VT_DATE    OLE Date
        VT_BSTR    OLE String
        VT_CY      OLE Currency
        VT_BOOL    OLE Boolean

When VT_DATE and VT_CY objects are created, the input parameter is treated as a Perl string type, which is then converted to VT_BSTR, and finally to VT_DATE of VT_CY using the VariantChangeType() OLE API function. See EXAMPLES in the Win32::OLE manpage for how these types can be used.

Variant arrays

A variant can not only contain a single value but also a multi-dimensional array of values (called a SAFEARRAY). In this case the VT_ARRAY flag must be added to the base variant type, e.g. VT_I4 | VT_ARRAY for an array of integers. The VT_EMPTY and VT_NULL types are invalid for SAFEARRAYs. It is possible to create an array of variants: VT_VARIANT | VT_ARRAY. In this case each element of the array can have a different type (including VT_EMPTY and VT_NULL). The elements of a VT_VARIANT SAFEARRAY cannot have either of the VT_ARRAY or VT_BYREF flags set.

The lower and upper bounds for each dimension can be specified separately. They do not have to have all the same lower bound (unlike Perl's arrays).

Variants by reference

Some OLE servers expect parameters passed by reference so that they can be changed in the method call. This allows methods to easily return multiple values. There is preliminary support for this in the Win32::OLE::Variant module:

        my $x = Variant(VT_I4|VT_BYREF, 0);
        my $y = Variant(VT_I4|VT_BYREF, 0);
        $Corel->GetSize($x, $y);
        print "Size is $x by $y\n";

After the GetSize method call $x and $y will be set to the respective sizes. They will still be variants. In the print statement the overloading converts them to string representation automatically.

VT_BYREF is now supported for all variant types (including SAFEARRAYs). It can also be used to pass an OLE object by reference:

        my $Results = $App->CreateResultsObject;
        $Object->Method(Variant(VT_DISPATCH|VT_BYREF, $Results));

AUTHORS/COPYRIGHT

This module is part of the Win32::OLE distribution.


Win32::PerfLib - accessing the Windows NT Performance Counter

  • FUNCTIONS
    • NOTE
  • Datastructures
  • AUTHOR
  • SEE ALSO

NAME

Win32::PerfLib - accessing the Windows NT Performance Counter

SYNOPSIS

  use Win32::PerfLib;
  my $server = "";
  Win32::PerfLib::GetCounterNames($server, \%counter);
  %r_counter = map { $counter{$_} => $_ } keys %counter;
  # retrieve the id for process object
  $process_obj = $r_counter{Process};
  # retrieve the id for the process ID counter
  $process_id = $r_counter{'ID Process'};

  # create connection to $server
  $perflib = new Win32::PerfLib($server);
  $proc_ref = {};
  # get the performance data for the process object
  $perflib->GetObjectList($process_obj, $proc_ref);
  $perflib->Close();
  $instance_ref = $proc_ref->{Objects}->{$process_obj}->{Instances};
  foreach $p (sort keys %{$instance_ref})
  {
      $counter_ref = $instance_ref->{$p}->{Counters};
      foreach $i (keys %{$counter_ref})
      {
          if($counter_ref->{$i}->{CounterNameTitleIndex} == $process_id)
          {
              printf( "% 6d %s\n", $counter_ref->{$i}->{Counter},
                      $instance_ref->{$p}->{Name}
                    );
          }
      }
  }

DESCRIPTION

This module allows to retrieve the performance counter of any computer (running Windows NT) in the network.

FUNCTIONS

NOTE

All of the functions return false if they fail, unless otherwise noted. If the $server argument is undef the local machine is assumed.

Win32::PerfLib::GetCounterNames($server,$hashref)

Retrieves the counter names and their indices from the registry and stores them in the hash reference

Win32::PerfLib::GetCounterHelp($server,$hashref)

Retrieves the counter help strings and their indices from the registry and stores them in the hash reference

$perflib = Win32::PerfLib->new ($server)

Creates a connection to the performance counters of the given server

$perflib->GetObjectList($objectid,$hashref)

retrieves the object and counter list of the given performance object.

$perflib->Close($hashref)

closes the connection to the performance counters

Win32::PerfLib::GetCounterType(countertype)

converts the counter type to readable string as referenced in calc.html so that it is easier to find the appropriate formula to calculate the raw counter data.

Datastructures

The performance data is returned in the following data structure:

Level 1
  $hashref = {
      'NumObjectTypes'   => VALUE
      'Objects'          => HASHREF
      'PerfFreq'         => VALUE
      'PerfTime'         => VALUE
      'PerfTime100nSec'  => VALUE
      'SystemName'       => STRING
      'SystemTime'       => VALUE
  }
Level 2

The hash reference $hashref->{Objects} has the returned object ID(s) as keys and a hash reference to the object counter data as value. Even there is only one object requested in the call to GetObjectList there may be more than one object in the result.

  $hashref->{Objects} = {
      <object1>  => HASHREF
      <object2>  => HASHREF
      ...
  }
Level 3

Each returned object ID has object-specific performance information. If an object has instances like the process object there is also a reference to the instance information.

  $hashref->{Objects}->{<object1>} = {
      'DetailLevel'           => VALUE
      'Instances'             => HASHREF
      'Counters'              => HASHREF
      'NumCounters'           => VALUE
      'NumInstances'          => VALUE
      'ObjectHelpTitleIndex'  => VALUE
      'ObjectNameTitleIndex'  => VALUE
      'PerfFreq'              => VALUE
      'PerfTime'              => VALUE
  }
Level 4

If there are instance information for the object available they are stored in the 'Instances' hashref. If the object has no instances there is an 'Counters' key instead. The instances or counters are numbered.

  $hashref->{Objects}->{<object1>}->{Instances} = {
      <1>     => HASHREF
      <2>     => HASHREF
      ...
      <n>     => HASHREF
  }
  or
  $hashref->{Objects}->{<object1>}->{Counters} = {
      <1>     => HASHREF
      <2>     => HASHREF
      ...
      <n>     => HASHREF
  }
Level 5
  $hashref->{Objects}->{<object1>}->{Instances}->{<1>} = {
      Counters               => HASHREF
      Name                   => STRING
      ParentObjectInstance   => VALUE
      ParentObjectTitleIndex => VALUE
  }
  or
  $hashref->{Objects}->{<object1>}->{Counters}->{<1>} = {
      Counter               => VALUE
      CounterHelpTitleIndex => VALUE
      CounterNameTitleIndex => VALUE
      CounterSize           => VALUE
      CounterType           => VALUE
      DefaultScale          => VALUE
      DetailLevel           => VALUE
      Display               => STRING
  }
Level 6
  $hashref->{Objects}->{<object1>}->{Instances}->{<1>}->{Counters} = {
      <1>     => HASHREF
      <2>     => HASHREF
      ...
      <n>     => HASHREF
  }
Level 7
  $hashref->{Objects}->{<object1>}->{Instances}->{<1>}->{Counters}->{<1>} = {
      Counter               => VALUE
      CounterHelpTitleIndex => VALUE
      CounterNameTitleIndex => VALUE
      CounterSize           => VALUE
      CounterType           => VALUE
      DefaultScale          => VALUE
      DetailLevel           => VALUE
      Display               => STRING
  }

Depending on the CounterType there are calculations to do (see calc.html).

AUTHOR

Jutta M. Klebe, jmk@bybyte.de

SEE ALSO

perl(1).


Win32::Pipe - Win32 Named Pipe

    • General Use
    • Benefits
  • CONSTRUCTOR
  • METHODS
  • LIMITATIONS
  • INSTALLATION NOTES
  • AUTHOR
  • DISCLAIMER
  • COPYRIGHT

NAME

Win32::Pipe - Win32 Named Pipe

SYNOPSIS

To use this extension, follow these basic steps. First, you need to 'use' the pipe extension:

    use Win32::Pipe;

Then you need to create a server side of a named pipe:

    $Pipe = new Win32::Pipe("My Pipe Name");

or if you are going to connect to pipe that has already been created:

    $Pipe = new Win32::Pipe("\\\\server\\pipe\\My Pipe Name");

    NOTE: The "\\\\server\\pipe\\" is necessary when connecting
          to an existing pipe! If you are accessing the same
          machine you could use "\\\\.\\pipe\\" but either way
          works fine.

You should check to see if $Pipe is indeed defined otherwise there has been an error.

Whichever end is the server, it must now wait for a connection...

    $Result = $Pipe->Connect();

    NOTE: The client end does not do this! When the client creates
          the pipe it has already connected!

Now you can read and write data from either end of the pipe:

    $Data = $Pipe->Read();

    $Result = $Pipe->Write("Howdy! This is cool!");

When the server is finished it must disconnect:

    $Pipe->Disconnect();

Now the server could Connect again (and wait for another client) or it could destroy the named pipe...

    $Data->Close();

The client should Close in order to properly end the session.

DESCRIPTION

General Use

This extension gives Win32 Perl the ability to use Named Pipes. Why? Well considering that Win32 Perl does not (yet) have the ability to fork I could not see what good the pipe(X,Y) was. Besides, where I am as an admin I must have several perl daemons running on several NT Servers. It dawned on me one day that if I could pipe all these daemons' output to my workstation (across the net) then it would be much easier to monitor. This was the impetus for an extension using Named Pipes. I think that it is kinda cool. :)

Benefits

And what are the benefits of this module?

  • You may create as many named pipes as you want (uh, well, as many as your resources will allow).

  • Currently there is a limit of 256 instances of a named pipe (once a pipe is created you can have 256 client/server connections to that name).

  • The default buffer size is 512 bytes; this can be altered by the ResizeBuffer method.

  • All named pipes are byte streams. There is currently no way to alter a pipe to be message based.

  • Other things that I cannot think of right now... :)

CONSTRUCTOR

new ( NAME )

Creates a named pipe if used in server context or a connection to the specified named pipe if used in client context. Client context is determined by prepending $Name with "\\\\".

Returns true on success, false on failure.

METHODS

BufferSize ()

Returns the size of the instance of the buffer of the named pipe.

Connect ()

Tells the named pipe to create an instance of the named pipe and wait until a client connects. Returns true on success, false on failure.

Close ()

Closes the named pipe.

Disconnect ()

Disconnects (and destroys) the instance of the named pipe from the client. Returns true on success, false on failure.

Error ()

Returns the last error messages pertaining to the named pipe. If used in context to the package. Returns a list containing ERROR_NUMBER and ERROR_TEXT.

Read ()

Reads from the named pipe. Returns data read from the pipe on success, undef on failure.

ResizeBuffer ( SIZE )

Sets the size of the buffer of the instance of the named pipe to SIZE. Returns the size of the buffer on success, false on failure.

Write ( DATA )

Writes DATA to the named pipe. Returns true on success, false on failure.

LIMITATIONS

What known problems does this thing have?

  • If someone is waiting on a Read and the other end terminates then you will wait for one REALLY long time! (If anyone has an idea on how I can detect the termination of the other end let me know!)

  • All pipes are blocking. I am considering using threads and callbacks into Perl to perform async IO but this may be too much for my time stress. ;)

  • There is no security placed on these pipes.

  • This module has neither been optimized for speed nor optimized for memory consumption. This may run into memory bloat.

INSTALLATION NOTES

If you wish to use this module with a build of Perl other than ActivePerl, you may wish to fetch the source distribution for this module. The source is included as part of the libwin32 bundle, which you can find in any CPAN mirror here:

  modules/by-authors/Gurusamy_Sarathy/libwin32-0.151.tar.gz

The source distribution also contains a pair of sample client/server test scripts. For the latest information on this module, consult the following web site:

  http://www.roth.net/perl

AUTHOR

Dave Roth <rothd@roth.net>

DISCLAIMER

I do not guarantee ANYTHING with this package. If you use it you are doing so AT YOUR OWN RISK! I may or may not support this depending on my time schedule.

COPYRIGHT

Copyright (c) 1996 Dave Roth. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Win32::Process - Create and manipulate processes.

  • METHODS
  • EXPORTS

NAME

Win32::Process - Create and manipulate processes.

SYNOPSIS

    use Win32::Process;
    use Win32;

    sub ErrorReport{
        print Win32::FormatMessage( Win32::GetLastError() );
    }

    Win32::Process::Create($ProcessObj,
                                "C:\\winnt\\system32\\notepad.exe",
                                "notepad temp.txt",
                                0,
                                NORMAL_PRIORITY_CLASS,
                                ".")|| die ErrorReport();

    $ProcessObj->Suspend();
    $ProcessObj->Resume();
    $ProcessObj->Wait(INFINITE);

DESCRIPTION

This module provides access to the process control functions in the Win32 API.

METHODS

Win32::Process::Create($obj,$appname,$cmdline,$iflags,$cflags,$curdir)

Creates a new process.

    Args:
        $obj            container for process object
        $appname        full path name of executable module
        $cmdline        command line args
        $iflags         flag: inherit calling processes handles or not
        $cflags         flags for creation (see exported vars below)
        $curdir         working dir of new process

Returns non-zero on success, 0 on failure.

Win32::Process::Open($obj,$pid,$iflags)

Creates a handle Perl can use to an existing process as identified by $pid. The $iflags is the inherit flag that is passed to OpenProcess. Currently Win32::Process objects created using Win32::Process::Open cannot Suspend or Resume the process. All other calls should work.

Win32::Process::Open returns non-zero on success, 0 on failure.

Win32::Process::KillProcess($pid, $exitcode)

Terminates any process identified by $pid. $exitcode will be set to the exit code of the process.

$ProcessObj->Suspend()

Suspend the process associated with the $ProcessObj.

$ProcessObj->Resume()

Resume a suspended process.

$ProcessObj->Kill($exitcode)

Kill the associated process, have it terminate with exit code $ExitCode.

$ProcessObj->GetPriorityClass($class)

Get the priority class of the process.

$ProcessObj->SetPriorityClass($class)

Set the priority class of the process (see exported values below for options).

$ProcessObj->GetProcessAffinityMask($processAffinityMask, $systemAffinityMask)

Get the process affinity mask. This is a bitvector in which each bit represents the processors that a process is allowed to run on.

$ProcessObj->SetProcessAffinityMask($processAffinityMask)

Set the process affinity mask. Only available on Windows NT.

$ProcessObj->GetExitCode($exitcode)

Retrieve the exitcode of the process. Will return STILL_ACTIVE if the process is still running. The STILL_ACTIVE constant is only exported by explicit request.

$ProcessObj->Wait($timeout)

Wait for the process to die. $timeout should be specified in milliseconds. To wait forever, specify the constant INFINITE.

$ProcessObj->GetProcessID()

Returns the Process ID.

Win32::Process::GetCurrentProcessID()

Returns the current process ID, which is the same as $$. But not on cygwin, where $$ is the cygwin-internal PID and not the windows PID. On cygwin GetCurrentProcessID() returns the windows PID as needed for all the Win32::Process functions.

EXPORTS

The following constants are exported by default:

        CREATE_DEFAULT_ERROR_MODE
        CREATE_NEW_CONSOLE
        CREATE_NEW_PROCESS_GROUP
        CREATE_NO_WINDOW
        CREATE_SEPARATE_WOW_VDM
        CREATE_SUSPENDED
        CREATE_UNICODE_ENVIRONMENT
        DEBUG_ONLY_THIS_PROCESS
        DEBUG_PROCESS
        DETACHED_PROCESS
        HIGH_PRIORITY_CLASS
        IDLE_PRIORITY_CLASS
        INFINITE
        NORMAL_PRIORITY_CLASS
        REALTIME_PRIORITY_CLASS
        THREAD_PRIORITY_ABOVE_NORMAL
        THREAD_PRIORITY_BELOW_NORMAL
        THREAD_PRIORITY_ERROR_RETURN
        THREAD_PRIORITY_HIGHEST
        THREAD_PRIORITY_IDLE
        THREAD_PRIORITY_LOWEST
        THREAD_PRIORITY_NORMAL
        THREAD_PRIORITY_TIME_CRITICAL

The following additional constants are exported by request only:

        STILL_ACTIVE


Win32::Registry - accessing the Windows registry [obsolete, use Win32::TieRegistry]

    • Methods

NAME

Win32::Registry - accessing the Windows registry [obsolete, use Win32::TieRegistry]

SYNOPSIS

    use Win32::Registry;
    my $tips;
    $::HKEY_LOCAL_MACHINE->Open("SOFTWARE\\Microsoft\\Windows"
                               ."\\CurrentVersion\\Explorer\\Tips", $tips)
        or die "Can't open tips: $^E";
    my ($type, $value);
    $tips->QueryValueEx("18", $type, $value) or die "No tip #18: $^E";
    print "Here's a tip: $value\n";

DESCRIPTION

    NOTE: This module provides a very klunky interface to access the
    Windows registry, and is not currently being developed actively.  It
    only exists for backward compatibility with old code that uses it.
    For more powerful and flexible ways to access the registry, use
    Win32::TieRegistry.

Win32::Registry provides an object oriented interface to the Windows Registry.

The following "root" registry objects are exported to the main:: name space. Additional keys must be opened by calling the provided methods on one of these.

    $HKEY_CLASSES_ROOT
    $HKEY_CURRENT_USER
    $HKEY_LOCAL_MACHINE
    $HKEY_USERS
    $HKEY_PERFORMANCE_DATA
    $HKEY_CURRENT_CONFIG
    $HKEY_DYN_DATA

Methods

The following methods are supported. Note that subkeys can be specified as a path name, separated by backslashes (which may need to be doubled if you put them in double quotes).

Open
    $reg_obj->Open($sub_key_name, $sub_reg_obj);

Opens a subkey of a registry object, returning the new registry object in $sub_reg_obj.

Close
    $reg_obj->Close();

Closes an open registry key.

Connect
    $reg_obj->Connect($node_name, $new_reg_obj);

Connects to a remote Registry on the node specified by $node_name, returning it in $new_reg_obj. Returns false if it fails.

Create
    $reg_obj->Create($sub_key_name, $new_reg_obj);

Opens the subkey specified by $sub_key_name, returning the new registry object in $new_reg_obj. If the specified subkey doesn't exist, it is created.

SetValue
    $reg_obj->SetValue($sub_key_name, $type, $value);

Sets the default value for a subkey specified by $sub_key_name.

SetValueEx
    $reg_obj->SetValueEx($value_name, $reserved, $type, $value);

Sets the value for the value name identified by $value_name in the key specified by $reg_obj.

QueryValue
    $reg_obj->QueryValue($sub_key_name, $value);

Gets the default value of the subkey specified by $sub_key_name.

QueryKey
    $reg_obj->QueryKey($classref, $number_of_subkeys, $number_of_values);

Gets information on a key specified by $reg_obj.

QueryValueEx
    $reg_obj->QueryValueEx($value_name, $type, $value);

Gets the value for the value name identified by $value_name in the key specified by $reg_obj.

GetKeys
    my @keys;
    $reg_obj->GetKeys(\@keys);

Populates the supplied array reference with the names of all the keys within the registry object $reg_obj.

GetValues
    my %values;
    $reg_obj->GetValues(\%values);

Populates the supplied hash reference with entries of the form

    $value_name => [ $value_name, $type, $data ]

for each value in the registry object $reg_obj.

DeleteKey
    $reg_obj->DeleteKey($sub_key_name);

Deletes a subkey specified by $sub_key_name from the registry.

DeleteValue
    $reg_obj->DeleteValue($value_name);

Deletes a value identified by $value_name from the registry.

Save
    $reg_obj->Save($filename);

Saves the hive specified by $reg_obj to a file.

Load
    $reg_obj->Load($sub_key_name, $file_name);

Loads a key specified by $sub_key_name from a file.

UnLoad
    $reg_obj->Unload($sub_key_name);

Unloads a registry hive.


Win32::Semaphore - Use Win32 semaphore objects from Perl

    • Methods
    • Deprecated Functions and Methods
  • AUTHOR

NAME

Win32::Semaphore - Use Win32 semaphore objects from Perl

SYNOPSIS require Win32::Semaphore;

        $sem = Win32::Semaphore->new($initial,$maximum,$name);
        $sem->wait;

DESCRIPTION

This module allows access to Win32 semaphore objects. The wait method and wait_all & wait_any functions are inherited from the Win32::IPC module.

Methods

$semaphore = Win32::Semaphore->new($initial, $maximum, [$name])

Constructor for a new semaphore object. $initial is the initial count, and $maximum is the maximum count for the semaphore. If $name is omitted, creates an unnamed semaphore object.

If $name signifies an existing semaphore object, then $initial and $maximum are ignored and the object is opened. If this happens, $^E will be set to 183 (ERROR_ALREADY_EXISTS).

$semaphore = Win32::Semaphore->open($name)

Constructor for opening an existing semaphore object.

$semaphore->release([$increment, [$previous]])

Increment the count of $semaphore by $increment (default 1). If $increment plus the semaphore's current count is more than its maximum count, the count is not changed. Returns true if the increment is successful.

The semaphore's count (before incrementing) is stored in the second argument (if any).

It is not necessary to wait on a semaphore before calling release, but you'd better know what you're doing.

$semaphore->wait([$timeout])

Wait for $semaphore's count to be nonzero, then decrement it by 1. See Win32::IPC.

Deprecated Functions and Methods

Win32::Semaphore still supports the ActiveWare syntax, but its use is deprecated.

Win32::Semaphore::Create($SemObject,$Initial,$Max,$Name)

Use $SemObject = Win32::Semaphore->new($Initial,$Max,$Name) instead.

Win32::Semaphore::Open($SemObject, $Name)

Use $SemObject = Win32::Semaphore->open($Name) instead.

$SemObj->Release($Count,$LastVal)

Use $SemObj->release($Count,$LastVal) instead.

AUTHOR

Christopher J. Madsen <cjm@pobox.com>

Loosely based on the original module by ActiveWare Internet Corp., http://www.ActiveWare.com


Win32::Service - manage system services in perl

  • FUNCTIONS
    • NOTE:

NAME

Win32::Service - manage system services in perl

SYNOPSIS

        use Win32::Service;

DESCRIPTION

This module offers control over the administration of system services.

FUNCTIONS

NOTE:

All of the functions return false if they fail, unless otherwise noted. If hostName is an empty string, the local machine is assumed.

StartService(hostName, serviceName)

Start the service serviceName on machine hostName.

StopService(hostName, serviceName)

Stop the service serviceName on the machine hostName.

GetStatus(hostName, serviceName, status)

Get the status of a service. The third argument must be a hash reference that will be populated with entries corresponding to the SERVICE_STATUS structure of the Win32 API. See the Win32 Platform SDK documentation for details of this structure.

PauseService(hostName, serviceName)
ResumeService(hostName, serviceName)
GetServices(hostName, hashref)

Enumerates both active and inactive Win32 services at the specified host. The hashref is populated with the descriptive service names as keys and the short names as the values.


Win32::Sound - An extension to play with Windows sounds

  • FUNCTIONS
  • THE WaveOut PACKAGE
    • FUNCTIONS
    • THE SOUND FORMAT
    • EXAMPLE
  • VERSION
  • AUTHOR

NAME

Win32::Sound - An extension to play with Windows sounds

SYNOPSIS

    use Win32::Sound;
    Win32::Sound::Volume('100%');
    Win32::Sound::Play("file.wav");
    Win32::Sound::Stop();

    # ...and read on for more fun ;-)

FUNCTIONS

Win32::Sound::Play(SOUND, [FLAGS])

Plays the specified sound: SOUND can the be name of a WAV file or one of the following predefined sound names:

    SystemDefault
    SystemAsterisk
    SystemExclamation
    SystemExit
    SystemHand
    SystemQuestion
    SystemStart

Additionally, if the named sound could not be found, the function plays the system default sound (unless you specify the SND_NODEFAULT flag). If no parameters are given, this function stops the sound actually playing (see also Win32::Sound::Stop).

FLAGS can be a combination of the following constants:

SND_ASYNC

The sound is played asynchronously and the function returns immediately after beginning the sound (if this flag is not specified, the sound is played synchronously and the function returns when the sound ends).

SND_LOOP

The sound plays repeatedly until it is stopped. You must also specify SND_ASYNC flag.

SND_NODEFAULT

No default sound is used. If the specified sound cannot be found, the function returns without playing anything.

SND_NOSTOP

If a sound is already playing, the function fails. By default, any new call to the function will stop previously playing sounds.

Win32::Sound::Stop()

Stops the sound currently playing.

Win32::Sound::Volume()

Returns the wave device volume; if called in an array context, returns left and right values. Otherwise, returns a single 32 bit value (left in the low word, right in the high word). In case of error, returns undef and sets $!.

Examples:

    ($L, $R) = Win32::Sound::Volume();
    if( not defined Win32::Sound::Volume() ) {
        die "Can't get volume: $!";
    }
Win32::Sound::Volume(LEFT, [RIGHT])

Sets the wave device volume; if two arguments are given, sets left and right channels independently, otherwise sets them both to LEFT (eg. RIGHT=LEFT). Values range from 0 to 65535 (0xFFFF), but they can also be given as percentage (use a string containing a number followed by a percent sign).

Returns undef and sets $! in case of error, a true value if successful.

Examples:

    Win32::Sound::Volume('50%');
    Win32::Sound::Volume(0xFFFF, 0x7FFF);
    Win32::Sound::Volume('100%', '50%');
    Win32::Sound::Volume(0);
Win32::Sound::Format(filename)

Returns information about the specified WAV file format; the array contains:

  • sample rate (in Hz)
  • bits per sample (8 or 16)
  • channels (1 for mono, 2 for stereo)

Example:

    ($hz, $bits, $channels)
        = Win32::Sound::Format("file.wav");
Win32::Sound::Devices()

Returns all the available sound devices; their names contain the type of the device (WAVEOUT, WAVEIN, MIDIOUT, MIDIIN, AUX or MIXER) and a zero-based ID number: valid devices names are for example:

    WAVEOUT0
    WAVEOUT1
    WAVEIN0
    MIDIOUT0
    MIDIIN0
    AUX0
    AUX1
    AUX2

There are also two special device names, WAVE_MAPPER and MIDI_MAPPER (the default devices for wave output and midi output).

Example:

    @devices = Win32::Sound::Devices();
Win32::Sound::DeviceInfo(DEVICE)

Returns an associative array of information about the sound device named DEVICE (the same format of Win32::Sound::Devices).

The content of the array depends on the device type queried. Each device type returns at least the following information:

    manufacturer_id
    product_id
    name
    driver_version

For additional data refer to the following table:

    WAVEIN..... formats
                channels
    WAVEOUT.... formats
                channels
                support
    MIDIOUT.... technology
                voices
                notes
                channels
                support
    AUX........ technology
                support
    MIXER...... destinations
                support

The meaning of the fields, where not obvious, can be evinced from the Microsoft SDK documentation (too long to report here, maybe one day... :-).

Example:

    %info = Win32::Sound::DeviceInfo('WAVE_MAPPER');
    print "$info{name} version $info{driver_version}\n";

THE WaveOut PACKAGE

Win32::Sound also provides a different, more powerful approach to wave audio data with its WaveOut package. It has methods to load and then play WAV files, with the additional feature of specifying the start and end range, so you can play only a portion of an audio file.

Furthermore, it is possible to load arbitrary binary data to the soundcard to let it play and save them back into WAV files; in a few words, you can do some sound synthesis work.

FUNCTIONS

new Win32::Sound::WaveOut(FILENAME)
new Win32::Sound::WaveOut(SAMPLERATE, BITS, CHANNELS)
new Win32::Sound::WaveOut()

This function creates a WaveOut object; the first form opens the specified wave file (see also Open() ), so you can directly Play() it.

The second (and third) form opens the wave output device with the format given (or if none given, defaults to 44.1kHz, 16 bits, stereo); to produce something audible you can either Open() a wave file or Load() binary data to the soundcard and then Write() it.

Close()

Closes the wave file currently opened.

CloseDevice()

Closes the wave output device; you can change format and reopen it with OpenDevice().

GetErrorText(ERROR)

Returns the error text associated with the specified ERROR number; note it only works for wave-output-specific errors.

Load(DATA)

Loads the DATA buffer in the soundcard. The format of the data buffer depends on the format used; for example, with 8 bit mono each sample is one character, while with 16 bit stereo each sample is four characters long (two 16 bit values for left and right channels). The sample rate defines how much samples are in one second of sound. For example, to fit one second at 44.1kHz 16 bit stereo your buffer must contain 176400 bytes (44100 * 4).

Open(FILE)

Opens the specified wave FILE.

OpenDevice()

Opens the wave output device with the current sound format (not needed unless you used CloseDevice()).

Pause()

Pauses the sound currently playing; use Restart() to continue playing.

Play( [FROM, TO] )

Plays the opened wave file. You can optionally specify a FROM - TO range, where FROM and TO are expressed in samples (or use FROM=0 for the first sample and TO=-1 for the last sample). Playback happens always asynchronously, eg. in the background.

Position()

Returns the sample number currently playing; note that the play position is not zeroed when the sound ends, so you have to call a Reset() between plays to receive the correct position in the current sound.

Reset()

Stops playing and resets the play position (see Position()).

Restart()

Continues playing the sound paused by Pause().

Save(FILE, [DATA])

Writes the DATA buffer (if not given, uses the buffer currently loaded in the soundcard) to the specified wave FILE.

Status()

Returns 0 if the soundcard is currently playing, 1 if it's free, or undef on errors.

Unload()

Frees the soundcard from the loaded data.

Volume( [LEFT, RIGHT] )

Gets or sets the volume for the wave output device. It works the same way as Win32::Sound::Volume.

Write()

Plays the data currently loaded in the soundcard; playback happens always asynchronously, eg. in the background.

THE SOUND FORMAT

The sound format is stored in three properties of the WaveOut object: samplerate, bits and channels. If you need to change them without creating a new object, you should close before and reopen afterwards the device.

    $WAV->CloseDevice();
    $WAV->{samplerate} = 44100; # 44.1kHz
    $WAV->{bits}       = 8;     # 8 bit
    $WAV->{channels}   = 1;     # mono
    $WAV->OpenDevice();

You can also use the properties to query the sound format currently used.

EXAMPLE

This small example produces a 1 second sinusoidal wave at 440Hz and saves it in sinus.wav:

    use Win32::Sound;

    # Create the object
    $WAV = new Win32::Sound::WaveOut(44100, 8, 2);

    $data = "";
    $counter = 0;
    $increment = 440/44100;

    # Generate 44100 samples ( = 1 second)
    for $i (1..44100) {

        # Calculate the pitch
        # (range 0..255 for 8 bits)
        $v = sin($counter/2*3.14) * 128 + 128;

        # "pack" it twice for left and right
        $data .= pack("cc", $v, $v);

        $counter += $increment;
            }

    $WAV->Load($data);       # get it
    $WAV->Write();           # hear it
    1 until $WAV->Status();  # wait for completion
    $WAV->Save("sinus.wav"); # write to disk
    $WAV->Unload();          # drop it

VERSION

Win32::Sound version 0.46, 25 Sep 1999.

AUTHOR

Aldo Calpini, dada@divinf.it

Parts of the code provided and/or suggested by Dave Roth.


Win32::TieRegistry - Powerful and easy ways to manipulate a registry [on Win32 for now].

  • EXAMPLES
  • DESCRIPTION
    • The Registry
    • Tied Hashes Documentation
      • Examples
      • Deleting items
      • Storing items
      • More examples
    • Objects Documentation
    • Exports [ use and import()]
      • Specifying constants in your Perl code
  • SUMMARY
    • Objects Summary
      • Other Useful Methods
    • Tied Hashes Summary
      • Opening keys
      • Reading values
      • Setting values
      • Adding keys
      • Listing all subkeys and values
      • Deleting values or keys with no subkeys
      • Closing keys
    • Tie::Registry
  • AUTHOR
  • SEE ALSO
  • BUGS
  • FUTURE DIRECTIONS

NAME

Win32::TieRegistry - Powerful and easy ways to manipulate a registry [on Win32 for now].

SYNOPSIS

  use Win32::TieRegistry 0.20 ( UseOptionName=>UseOptionValue[,...] );

  $Registry->SomeMethodCall(arg1,...);

  $subKey= $Registry->{"Key\\SubKey\\"};
  $valueData= $Registry->{"Key\\SubKey\\\\ValueName"};
  $Registry->{"Key\\SubKey\\"}= { "NewSubKey" => {...} };
  $Registry->{"Key\\SubKey\\\\ValueName"}= "NewValueData";
  $Registry->{"\\ValueName"}= [ pack("fmt",$data), REG_DATATYPE ];

EXAMPLES

  use Win32::TieRegistry( Delimiter=>"#", ArrayValues=>0 );
  $pound= $Registry->Delimiter("/");
  $diskKey= $Registry->{"LMachine/System/Disk/"}
    or  die "Can't read LMachine/System/Disk key: $^E\n";
  $data= $key->{"/Information"}
    or  die "Can't read LMachine/System/Disk//Information value: $^E\n";
  $remoteKey= $Registry->{"//ServerA/LMachine/System/"}
    or  die "Can't read //ServerA/LMachine/System/ key: $^E\n";
  $remoteData= $remoteKey->{"Disk//Information"}
    or  die "Can't read ServerA's System/Disk//Information value: $^E\n";
  foreach $entry (  keys(%$diskKey)  ) {
      ...
  }
  foreach $subKey (  $diskKey->SubKeyNames  ) {
      ...
  }
  $diskKey->AllowSave( 1 );
  $diskKey->RegSaveKey( "C:/TEMP/DiskReg", [] );

DESCRIPTION

The Win32::TieRegistry module lets you manipulate the Registry via objects [as in "object oriented"] or via tied hashes. But you will probably mostly use a combination reference, that is, a reference to a tied hash that has also been made an object so that you can mix both access methods [as shown above].

If you did not get this module as part of libwin32, you might want to get a recent version of libwin32 from CPAN which should include this module and the Win32API::Registry module that it uses.

Skip to the SUMMARY section if you just want to dive in and start using the Registry from Perl.

Accessing and manipulating the registry is extremely simple using Win32::TieRegistry. A single, simple expression can return you almost any bit of information stored in the Registry. Win32::TieRegistry also gives you full access to the "raw" underlying API calls so that you can do anything with the Registry in Perl that you could do in C. But the "simple" interface has been carefully designed to handle almost all operations itself without imposing arbitrary limits while providing sensible defaults so you can list only the parameters you care about.

But first, an overview of the Registry itself.

The Registry

The Registry is a forest: a collection of several tree structures. The root of each tree is a key. These root keys are identified by predefined constants whose names start with "HKEY_". Although all keys have a few attributes associated with each [a class, a time stamp, and security information], the most important aspect of keys is that each can contain subkeys and can contain values.

Each subkey has a name: a string which cannot be blank and cannot contain the delimiter character [backslash: '\\'] nor nul ['\0']. Each subkey is also a key and so can contain subkeys and values [and has a class, time stamp, and security information].

Each value has a name: a string which &can; be blank and &can; contain the delimiter character [backslash: '\\'] and any character except for null, '\0'. Each value also has data associated with it. Each value's data is a contiguous chunk of bytes, which is exactly what a Perl string value is so Perl strings will usually be used to represent value data.

Each value also has a data type which says how to interpret the value data. The primary data types are:

REG_SZ

A null-terminated string.

REG_EXPAND_SZ

A null-terminated string which contains substrings consisting of a percent sign ['%'], an environment variable name, then a percent sign, that should be replaced with the value associate with that environment variable. The system does not automatically do this substitution.

REG_BINARY

Some arbitrary binary value. You can think of these as being "packed" into a string.

If your system has the SetDualVar module installed, the DualBinVals() option wasn't turned off, and you fetch a REG_BINARY value of 4 bytes or fewer, then you can use the returned value in a numeric context to get at the "unpacked" numeric value. See GetValue() for more information.

REG_MULTI_SZ

Several null-terminated strings concatenated together with an extra trailing '\0' at the end of the list. Note that the list can include empty strings so use the value's length to determine the end of the list, not the first occurrence of '\0\0'. It is best to set the SplitMultis() option so Win32::TieRegistry will split these values into an array of strings for you.

REG_DWORD

A long [4-byte] integer value. These values are expected either packed into a 4-character string or as a hex string of &more than; 4 characters [but not as a numeric value, unfortunately, as there is no sure way to tell a numeric value from a packed 4-byte string that just happens to be a string containing a valid numeric value].

How such values are returned depends on the DualBinVals() and DWordsToHex() options. See GetValue() for details.

In the underlying Registry calls, most places which take a subkey name also allow you to pass in a subkey "path" -- a string of several subkey names separated by the delimiter character, backslash ['\\']. For example, doing RegOpenKeyEx(HKEY_LOCAL_MACHINE,"SYSTEM\\DISK",...) is much like opening the "SYSTEM" subkey of HKEY_LOCAL_MACHINE, then opening its "DISK" subkey, then closing the "SYSTEM" subkey.

All of the Win32::TieRegistry features allow you to use your own delimiter in place of the system's delimiter, ['\\']. In most of our examples we will use a forward slash ['/'] as our delimiter as it is easier to read and less error prone to use when writing Perl code since you have to type two backslashes for each backslash you want in a string. Note that this is true even when using single quotes -- '\\HostName\LMachine\' is an invalid string and must be written as '\\\\HostName\\LMachine\\'.

You can also connect to the registry of other computers on your network. This will be discussed more later.

Although the Registry does not have a single root key, the Win32::TieRegistry module creates a virtual root key for you which has all of the HKEY_* keys as subkeys.

Tied Hashes Documentation

Before you can use a tied hash, you must create one. One way to do that is via:

    use Win32::TieRegistry ( TiedHash => '%RegHash' );

which exports a %RegHash variable into your package and ties it to the virtual root key of the Registry. An alternate method is:

    my %RegHash;
    use Win32::TieRegistry ( TiedHash => \%RegHash );

There are also several ways you can tie a hash variable to any other key of the Registry, which are discussed later.

Note that you will most likely use $Registry instead of using a tied hash. $Registry is a reference to a hash that has been tied to the virtual root of your computer's Registry [as if, $Registry= \%RegHash]. So you would use $Registry->{Key} rather than $RegHash{Key} and use keys %{$Registry} rather than keys %RegHash, for example.

For each hash which has been tied to a Registry key, the Perl keys function will return a list containing the name of each of the key's subkeys with a delimiter character appended to it and containing the name of each of the key's values with a delimiter prepended to it. For example:

    keys( %{ $Registry->{"HKEY_CLASSES_ROOT\\batfile\\"} } )

might yield the following list value:

    ( "DefaultIcon\\",  # The subkey named "DefaultIcon"
      "shell\\",        # The subkey named "shell"
      "shellex\\",      # The subkey named "shellex"
      "\\",             # The default value [named ""]
      "\\EditFlags" )   # The value named "EditFlags"

For the virtual root key, short-hand subkey names are used as shown below. You can use the short-hand name, the regular HKEY_* name, or any numeric value to access these keys, but the short-hand names are all that will be returned by the keys function.

"Classes" for HKEY_CLASSES_ROOT

Contains mappings between file name extensions and the uses for such files along with configuration information for COM [MicroSoft's Common Object Model] objects. Usually a link to the "SOFTWARE\\Classes" subkey of the HKEY_LOCAL_MACHINE key.

"CUser" for HKEY_CURRENT_USER

Contains information specific to the currently logged-in user. Mostly software configuration information. Usually a link to a subkey of the HKEY_USERS key.

"LMachine" for HKEY_LOCAL_MACHINE

Contains all manner of information about the computer.

"Users" for HKEY_USERS

Contains one subkey, ".DEFAULT", which gets copied to a new subkey whenever a new user is added. Also contains a subkey for each user of the system, though only those for active users [usually only one] are loaded at any given time.

"PerfData" for HKEY_PERFORMANCE_DATA

Used to access data about system performance. Access via this key is "special" and all but the most carefully constructed calls will fail, usually with ERROR_INSUFFICIENT_BUFFER. For example, you can't enumerate key names without also enumerating values which require huge buffers but the exact buffer size required cannot be determined beforehand because RegQueryInfoKey() &always; fails with ERROR_INSUFFICIENT_BUFFER for HKEY_PERFORMANCE_DATA no matter how it is called. So it is currently not very useful to tie a hash to this key. You can use it to create an object to use for making carefully constructed calls to the underlying Reg*() routines.

"CConfig" for HKEY_CURRENT_CONFIG

Contains minimal information about the computer's current configuration that is required very early in the boot process. For example, setting for the display adapter such as screen resolution and refresh rate are found in here.

"DynData" for HKEY_DYN_DATA

Dynamic data. We have found no documentation for this key.

A tied hash is much like a regular hash variable in Perl -- you give it a key string inside braces, [{ and }], and it gives you back a value [or lets you set a value]. For Win32::TieRegistry hashes, there are two types of values that will be returned.

SubKeys

If you give it a string which represents a subkey, then it will give you back a reference to a hash which has been tied to that subkey. It can't return the hash itself, so it returns a reference to it. It also blesses that reference so that it is also an object so you can use it to call method functions.

Values

If you give it a string which is a value name, then it will give you back a string which is the data for that value. Alternately, you can request that it give you both the data value string and the data value type [we discuss how to request this later]. In this case, it would return a reference to an array where the value data string is element [0] and the value data type is element [1].

The key string which you use in the tied hash must be interpreted to determine whether it is a value name or a key name or a path that combines several of these or even other things. There are two simple rules that make this interpretation easy and unambiguous:

    Put a delimiter after each key name.
    Put a delimiter in front of each value name.

Exactly how the key string will be intepreted is governed by the following cases, in the order listed. These cases are designed to "do what you mean". Most of the time you won't have to think about them, especially if you follow the two simple rules above. After the list of cases we give several examples which should be clear enough so feel free to skip to them unless you are worried about the details.

Remote machines

If the hash is tied to the virtual root of the registry [or the virtual root of a remote machine's registry], then we treat hash key strings which start with the delimiter character specially.

If the hash key string starts with two delimiters in a row, then those should be immediately followed by the name of a remote machine whose registry we wish to connect to. That can be followed by a delimiter and more subkey names, etc. If the machine name is not following by anything, then a virtual root for the remote machine's registry is created, a hash is tied to it, and a reference to that hash it is returned.

Hash key string starts with the delimiter

If the hash is tied to a virtual root key, then the leading delimiter is ignored. It should be followed by a valid Registry root key name [either a short-hand name like "LMachine", an HKEY_* value, or a numeric value]. This alternate notation is allowed in order to be more consistant with the Open() method function.

For all other Registry keys, the leading delimiter indicates that the rest of the string is a value name. The leading delimiter is stripped and the rest of the string [which can be empty and can contain more delimiters] is used as a value name with no further parsing.

Exact match with direct subkey name followed by delimiter

If you have already called the Perl keys function on the tied hash [or have already called MemberNames on the object] and the hash key string exactly matches one of the strings returned, then no further parsing is done. In other words, if the key string exactly matches the name of a direct subkey with a delimiter appended, then a reference to a hash tied to that subkey is returned [but only if keys or MemberNames has already been called for that tied hash].

This is only important if you have selected a delimiter other than the system default delimiter and one of the subkey names contains the delimiter you have chosen. This rule allows you to deal with subkeys which contain your chosen delimiter in their name as long as you only traverse subkeys one level at a time and always enumerate the list of members before doing so.

The main advantage of this is that Perl code which recursively traverses a hash will work on hashes tied to Registry keys even if a non-default delimiter has been selected.

Hash key string contains two delimiters in a row

If the hash key string contains two [or more] delimiters in a row, then the string is split between the first pair of delimiters. The first part is interpreted as a subkey name or a path of subkey names separated by delimiters and with a trailing delimiter. The second part is interpreted as a value name with one leading delimiter [any extra delimiters are considered part of the value name].

Hash key string ends with a delimiter

If the key string ends with a delimiter, then it is treated as a subkey name or path of subkey names separated by delimiters.

Hash key string contains a delimiter

If the key string contains a delimiter, then it is split after the last delimiter. The first part is treated as a subkey name or path of subkey names separated by delimiters. The second part is ambiguous and is treated as outlined in the next item.

Hash key string contains no delimiters

If the hash key string contains no delimiters, then it is ambiguous.

If you are reading from the hash [fetching], then we first use the key string as a value name. If there is a value with a matching name in the Registry key which the hash is tied to, then the value data string [and possibly the value data type] is returned. Otherwise, we retry by using the hash key string as a subkey name. If there is a subkey with a matching name, then we return a reference to a hash tied to that subkey. Otherwise we return undef.

If you are writing to the hash [storing], then we use the key string as a subkey name only if the value you are storing is a reference to a hash value. Otherwise we use the key string as a value name.

Examples

Here are some examples showing different ways of accessing Registry information using references to tied hashes:

Canonical value fetch
    $tip18= $Registry->{"HKEY_LOCAL_MACHINE\\Software\\Microsoft\\"
               . 'Windows\\CurrentVersion\\Explorer\\Tips\\\\18'};

Should return the text of important tip number 18. Note that two backslashes, "\\", are required to get a single backslash into a Perl double-quoted or single-qouted string. Note that "\\" is appended to each key name ["HKEY_LOCAL_MACHINE" through "Tips"] and "\\" is prepended to the value name, "18".

Changing your delimiter
    $Registry->Delimiter("/");
    $tip18= $Registry->{"HKEY_LOCAL_MACHINE/Software/Microsoft/"
               . 'Windows/CurrentVersion/Explorer/Tips//18'};

This usually makes things easier to read when working in Perl. All remaining examples will assume the delimiter has been changed as above.

Using intermediate keys
    $ms= $Registry->{"LMachine/Software/Microsoft/"};
    $tips= $ms->{"Windows/CurrentVersion/Explorer/Tips/"};
    $tip18= $winlogon->{"/18"};

Same as above but opens more keys into the Registry which lets you efficiently re-access those intermediate keys. This is slightly less efficient if you never reuse those intermediate keys.

Chaining in a single statement
    $tip18= $Registry->{"LMachine/Software/Microsoft/"}->
              {"Windows/CurrentVersion/Explorer/Tips/"}->{"/18"};

Like above, this creates intermediate key objects then uses them to access other data. Once this statement finishes, the intermediate key objects are destroyed. Several handles into the Registry are opened and closed by this statement so it is less efficient but there are times when this will be useful.

Even less efficient example of chaining
    $tip18= $Registry->{"LMachine/Software/Microsoft"}->
              {"Windows/CurrentVersion/Explorer/Tips"}->{"/18"};

Because we left off the trailing delimiters, Win32::TieRegistry doesn't know whether final names, "Microsoft" and "Tips", are subkey names or value names. So this statement ends up executing the same code as the next one.

What the above really does
    $tip18= $Registry->{"LMachine/Software/"}->{"Microsoft"}->
              {"Windows/CurrentVersion/Explorer/"}->{"Tips"}->{"/18"};

With more chains to go through, more temporary objects are created and later destroyed than in our first chaining example. Also, when "Microsoft" is looked up, Win32::TieRegistry first tries to open it as a value and fails then tries it as a subkey. The same is true for when it looks up "Tips".

Getting all of the tips
    $tips= $Registry->{"LMachine/Software/Microsoft/"}->
              {"Windows/CurrentVersion/Explorer/Tips/"}
      or  die "Can't find the Windows tips: $^E\n";
    foreach(  keys %$tips  ) {
        print "$_: ", $tips->{$_}, "\n";
    }

First notice that we actually check for failure for the first time. We are assuming that the "Tips" key contains no subkeys. Otherwise the print statement would show something like "Win32::TieRegistry=HASH(0xc03ebc)" for each subkey.

The output from the above code will start something like:

    /0: If you don't know how to do something,[...]

Deleting items

You can use the Perl delete function to delete a value from a Registry key or to delete a subkey as long that subkey contains no subkeys of its own. See More Examples, below, for more information.

Storing items

You can use the Perl assignment operator [=] to create new keys, create new values, or replace values. The values you store should be in the same format as the values you would fetch from a tied hash. For example, you can use a single assignment statement to copy an entire Registry tree. The following statement:

    $Registry->{"LMachine/Software/Classes/Tie_Registry/"}=
      $Registry->{"LMachine/Software/Classes/batfile/"};

creates a "Tie_Registry" subkey under the "Software\\Classes" subkey of the HKEY_LOCAL_MACHINE key. Then it populates it with copies of all of the subkeys and values in the "batfile" subkey and all of its subkeys. Note that you need to have called $Registry->ArrayValues(1) for the proper value data type information to be copied. Note also that this release of Win32::TieRegistry does not copy key attributes such as class name and security information [this is planned for a future release].

The following statement creates a whole subtree in the Registry:

    $Registry->{"LMachine/Software/FooCorp/"}= {
        "FooWriter/" => {
            "/Version" => "4.032",
            "Startup/" => {
                "/Title" => "Foo Writer Deluxe ][",
                "/WindowSize" => [ pack("LL",$wid,$ht), "REG_BINARY" ],
                "/TaskBarIcon" => [ "0x0001", "REG_DWORD" ],
            },
            "Compatibility/" => {
                "/AutoConvert" => "Always",
                "/Default Palette" => "Windows Colors",
            },
        },
        "/License", => "0123-9C8EF1-09-FC",
    };

Note that all but the last Registry key used on the left-hand side of the assignment [that is, "LMachine/Software/" but not "FooCorp/"] must already exist for this statement to succeed.

By using the leading a trailing delimiters on each subkey name and value name, Win32::TieRegistry will tell you if you try to assign subkey information to a value or visa-versa.

More examples

Adding a new tip
    $tips= $Registry->{"LMachine/Software/Microsoft/"}->
              {"Windows/CurrentVersion/Explorer/Tips/"}
      or  die "Can't find the Windows tips: $^E\n";
    $tips{'/186'}= "Be very careful when making changes to the Registry!";
Deleting our new tip
    $tips= $Registry->{"LMachine/Software/Microsoft/"}->
              {"Windows/CurrentVersion/Explorer/Tips/"}
      or  die "Can't find the Windows tips: $^E\n";
    $tip186= delete $tips{'/186'};

Note that Perl's delete function returns the value that was deleted.

Adding a new tip differently
    $Registry->{"LMachine/Software/Microsoft/" .
                "Windows/CurrentVersion/Explorer/Tips//186"}=
      "Be very careful when making changes to the Registry!";
Deleting differently
    $tip186= delete $Registry->{"LMachine/Software/Microsoft/Windows/" .
                                "CurrentVersion/Explorer/Tips//186"};

Note that this only deletes the tail of what we looked up, the "186" value, not any of the keys listed.

Deleting a key

WARNING: The following code will delete all information about the current user's tip preferences. Actually executing this command would probably cause the user to see the Welcome screen the next time they log in and may cause more serious problems. This statement is shown as an example only and should not be used when experimenting.

    $tips= delete $Registry->{"CUser/Software/Microsoft/Windows/" .
                              "CurrentVersion/Explorer/Tips/"};

This deletes the "Tips" key and the values it contains. The delete function will return a reference to a hash [not a tied hash] containing the value names and value data that were deleted.

The information to be returned is copied from the Registry into a regular Perl hash before the key is deleted. If the key has many subkeys, this copying could take a significant amount of memory and/or processor time. So you can disable this process by calling the FastDelete member function:

    $prevSetting= $regKey->FastDelete(1);

which will cause all subsequent delete operations via $regKey to simply return a true value if they succeed. This optimization is automatically done if you use delete in a void context.

Technical notes on deleting

If you use delete to delete a Registry key or value and use the return value, then Win32::TieRegistry usually looks up the current contents of that key or value so they can be returned if the deletion is successful. If the deletion succeeds but the attempt to lookup the old contents failed, then the return value of delete will be $^E from the failed part of the operation.

Undeleting a key
    $Registry->{"LMachine/Software/Microsoft/Windows/" .
                "CurrentVersion/Explorer/Tips/"}= $tips;

This adds back what we just deleted. Note that this version of Win32::TieRegistry will use defaults for the key attributes [such as class name and security] and will not restore the previous attributes.

Not deleting a key

WARNING: Actually executing the following code could cause serious problems. This statement is shown as an example only and should not be used when experimenting.

    $res= delete $Registry->{"CUser/Software/Microsoft/Windows/"}
    defined($res)  ||  die "Can't delete URL key: $^E\n";

Since the "Windows" key should contain subkeys, that delete statement should make no changes to the Registry, return undef, and set $^E to "Access is denied".

Not deleting again
    $tips= $Registry->{"CUser/Software/Microsoft/Windows/" .
                       "CurrentVersion/Explorer/Tips/"};
    delete $tips;

The Perl delete function requires that its argument be an expression that ends in a hash element lookup [or hash slice], which is not the case here. The delete function doesn't know which hash $tips came from and so can't delete it.

Objects Documentation

The following member functions are defined for use on Win32::TieRegistry objects:

new

The new method creates a new Win32::TieRegistry object. new is mostly a synonym for Open() so see Open() below for information on what arguments to pass in. Examples:

    $machKey= new Win32::TieRegistry "LMachine"
      or  die "Can't access HKEY_LOCAL_MACHINE key: $^E\n";
    $userKey= Win32::TieRegistry->new("CUser")
      or  die "Can't access HKEY_CURRENT_USER key: $^E\n";

Note that calling new via a reference to a tied hash returns a simple object, not a reference to a tied hash.

Open
$subKey= $key->Open( $sSubKey, $rhOptions )

The Open method opens a Registry key and returns a new Win32::TieRegistry object associated with that Registry key. If Open is called via a reference to a tied hash, then Open returns another reference to a tied hash. Otherwise Open returns a simple object and you should then use TiedRef to get a reference to a tied hash.

$sSubKey is a string specifying a subkey to be opened. Alternately $sSubKey can be a reference to an array value containing the list of increasingly deep subkeys specifying the path to the subkey to be opened.

$rhOptions is an optional reference to a hash containing extra options. The Open method supports two options, "Delimiter" and "Access", and $rhOptions should have only have zero or more of these strings as keys. See the "Examples" section below for more information.

The "Delimiter" option specifies what string [usually a single character] will be used as the delimiter to be appended to subkey names and prepended to value names. If this option is not specified, the new key [$subKey] inherits the delimiter of the old key [$key].

The "Access" option specifies what level of access to the Registry key you wish to have once it has been opened. If this option is not specified, the new key [$subKey] is opened with the same access level used when the old key [$key] was opened. The virtual root of the Registry pretends it was opened with access KEY_READ()|KEY_WRITE() so this is the default access when opening keys directory via $Registry. If you don't plan on modifying a key, you should open it with KEY_READ access as you may not have KEY_WRITE access to it or some of its subkeys.

If the "Access" option value is a string that starts with "KEY_", then it should match &one; of the predefined access levels [probably "KEY_READ", "KEY_WRITE", or "KEY_ALL_ACCESS"] exported by the Win32API::Registry module. Otherwise, a numeric value is expected. For maximum flexibility, include use Win32::TieRegistry qw(:KEY_);, for example, near the top of your script so you can specify more complicated access levels such as KEY_READ()|KEY_WRITE().

If $sSubKey does not begin with the delimiter [or $sSubKey is an array reference], then the path to the subkey to be opened will be relative to the path of the original key [$key]. If $sSubKey begins with a single delimiter, then the path to the subkey to be opened will be relative to the virtual root of the Registry on whichever machine the original key resides. If $sSubKey begins with two consectutive delimiters, then those must be followed by a machine name which causes the Connect() method function to be called.

Examples:

    $machKey= $Registry->Open( "LMachine", {Access=>KEY_READ(),Delimiter=>"/"} )
      or  die "Can't open HKEY_LOCAL_MACHINE key: $^E\n";
    $swKey= $machKey->Open( "Software" );
    $logonKey= $swKey->Open( "Microsoft/Windows NT/CurrentVersion/Winlogon/" );
    $NTversKey= $swKey->Open( ["Microsoft","Windows NT","CurrentVersion"] );
    $versKey= $swKey->Open( qw(Microsoft Windows CurrentVersion) );

    $remoteKey= $Registry->Open( "//HostA/LMachine/System/", {Delimiter=>"/"} )
      or  die "Can't connect to HostA or can't open subkey: $^E\n";
Clone
$copy= $key->Clone

Creates a new object that is associated with the same Registry key as the invoking object.

Connect
$remoteKey= $Registry->Connect( $sMachineName, $sKeyPath, $rhOptions )

The Connect method connects to the Registry of a remote machine, and opens a key within it, then returns a new Win32::TieRegistry object associated with that remote Registry key. If Connect was called using a reference to a tied hash, then the return value will also be a reference to a tied hash [or undef]. Otherwise, if you wish to use the returned object as a tied hash [not just as an object], then use the TiedRef method function after Connect.

$sMachineName is the name of the remote machine. You don't have to preceed the machine name with two delimiter characters.

$sKeyPath is a string specifying the remote key to be opened. Alternately $sKeyPath can be a reference to an array value containing the list of increasingly deep keys specifying the path to the key to be opened.

$rhOptions is an optional reference to a hash containing extra options. The Connect method supports two options, "Delimiter" and "Access". See the Open method documentation for more information on these options.

$sKeyPath is already relative to the virtual root of the Registry of the remote machine. A single leading delimiter on sKeyPath will be ignored and is not required.

$sKeyPath can be empty in which case Connect will return an object representing the virtual root key of the remote Registry. Each subsequent use of Open on this virtual root key will call the system RegConnectRegistry function.

The Connect method can be called via any Win32::TieRegistry object, not just $Registry. Attributes such as the desired level of access and the delimiter will be inherited from the object used but the $sKeyPath will always be relative to the virtual root of the remote machine's registry.

Examples:

    $remMachKey= $Registry->Connect( "HostA", "LMachine", {Delimiter->"/"} )
      or  die "Can't connect to HostA's HKEY_LOCAL_MACHINE key: $^E\n";

    $remVersKey= $remMachKey->Connect( "www.microsoft.com",
                   "LMachine/Software/Microsoft/Inetsrv/CurrentVersion/",
                   { Access=>KEY_READ, Delimiter=>"/" } )
      or  die "Can't check what version of IIS Microsoft is running: $^E\n";

    $remVersKey= $remMachKey->Connect( "www",
                   qw(LMachine Software Microsoft Inetsrv CurrentVersion) )
      or  die "Can't check what version of IIS we are running: $^E\n";
ObjectRef
$object_ref= $obj_or_hash_ref->ObjectRef

For a simple object, just returns itself [$obj == $obj-ObjectRef>].

For a reference to a tied hash [if it is also an object], ObjectRef returns the simple object that the hash is tied to.

This is primarilly useful when debugging since typing x $Registry will try to display your entire registry contents to your screen. But the debugger command x $Registry-ObjectRef> will just dump the implementation details of the underlying object to your screen.

Flush( $bFlush )

Flushes all cached information about the Registry key so that future uses will get fresh data from the Registry.

If the optional $bFlush is specified and a true value, then RegFlushKey() will be called, which is almost never necessary.

GetValue
$ValueData= $key->GetValue( $sValueName )
($ValueData,$ValueType)= $key->GetValue( $sValueName )

Gets a Registry value's data and data type.

$ValueData is usually just a Perl string that contains the value data [packed into it]. For certain types of data, however, $ValueData may be processed as described below.

$ValueType is the REG_* constant describing the type of value data stored in $ValueData. If the DualTypes() option is on, then $ValueType will be a dual value. That is, when used in a numeric context, $ValueType will give the numeric value of a REG_* constant. However, when used in a non-numeric context, $ValueType will return the name of the REG_* constant, for example "REG_SZ" [note the quotes]. So both of the following can be true at the same time:

    $ValueType == REG_SZ()
    $ValueType eq "REG_SZ"
REG_SZ and REG_EXPAND_SZ

If the FixSzNulls() option is on, then the trailing '\0' will be stripped [unless there isn't one] before values of type REG_SZ and REG_EXPAND_SZ are returned. Note that SetValue() will add a trailing '\0' under similar circumstances.

REG_MULTI_SZ

If the SplitMultis() option is on, then values of this type are returned as a reference to an array containing the strings. For example, a value that, with SplitMultis() off, would be returned as:

    "Value1\000Value2\000\000"

would be returned, with SplitMultis() on, as:

    [ "Value1", "Value2" ]
REG_DWORD

If the DualBinVals() option is on, then the value is returned as a scalar containing both a string and a number [much like the $! variable -- see the SetDualVar module for more information] where the number part is the "unpacked" value. Use the returned value in a numeric context to access this part of the value. For example:

    $num= 0 + $Registry->{"CUser/Console//ColorTable01"};

If the DWordsToHex() option is off, the string part of the returned value is a packed, 4-byte string [use unpack("L",$value) to get the numeric value.

If DWordsToHex() is on, the string part of the returned value is a 10-character hex strings [with leading "0x"]. You can use hex($value) to get the numeric value.

Note that SetValue() will properly understand each of these returned value formats no matter how DualBinVals() is set.

ValueNames
@names= $key->ValueNames

Returns the list of value names stored directly in a Registry key. Note that the names returned do not have a delimiter prepended to them like with MemberNames() and tied hashes.

Once you request this information, it is cached in the object and future requests will always return the same list unless Flush() has been called.

SubKeyNames
@key_names= $key->SubKeyNames

Returns the list of subkey names stored directly in a Registry key. Note that the names returned do not have a delimiter appended to them like with MemberNames() and tied hashes.

Once you request this information, it is cached in the object and future requests will always return the same list unless Flush() has been called.

SubKeyClasses
@classes= $key->SubKeyClasses

Returns the list of classes for subkeys stored directly in a Registry key. The classes are returned in the same order as the subkey names returned by SubKeyNames().

SubKeyTimes
@times= $key->SubKeyTimes

Returns the list of last-modified times for subkeys stored directly in a Registry key. The times are returned in the same order as the subkey names returned by SubKeyNames(). Each time is a FILETIME structure packed into a Perl string.

Once you request this information, it is cached in the object and future requests will always return the same list unless Flush() has been called.

MemberNames
@members= $key->MemberNames

Returns the list of subkey names and value names stored directly in a Registry key. Subkey names have a delimiter appended to the end and value names have a delimiter prepended to the front.

Note that a value name could end in a delimiter [or could be "" so that the member name returned is just a delimiter] so the presence or absence of the leading delimiter is what should be used to determine whether a particular name is for a subkey or a value, not the presence or absence of a trailing delimiter.

Once you request this information, it is cached in the object and future requests will always return the same list unless Flush() has been called.

Information
%info= $key->Information
@items= $key->Information( @itemNames );

Returns the following information about a Registry key:

LastWrite

A FILETIME structure indicating when the key was last modified and packed into a Perl string.

CntSubKeys

The number of subkeys stored directly in this key.

CntValues

The number of values stored directly in this key.

SecurityLen

The length [in bytes] of the largest[?] SECURITY_DESCRIPTOR associated with the Registry key.

MaxValDataLen

The length [in bytes] of the longest value data associated with a value stored in this key.

MaxSubKeyLen

The length [in chars] of the longest subkey name associated with a subkey stored in this key.

MaxSubClassLen

The length [in chars] of the longest class name associated with a subkey stored directly in this key.

MaxValNameLen

The length [in chars] of the longest value name associated with a value stored in this key.

With no arguments, returns a hash [not a reference to a hash] where the keys are the names for the items given above and the values are the information describe above. For example:

    %info= ( "CntValues" => 25,         # Key contains 25 values.
             "MaxValNameLen" => 20,     # One of which has a 20-char name.
             "MaxValDataLen" => 42,     # One of which has a 42-byte value.
             "CntSubKeys" => 1,         # Key has 1 immediate subkey.
             "MaxSubKeyLen" => 13,      # One of which has a 12-char name.
             "MaxSubClassLen" => 0,     # All of which have class names of "".
             "SecurityLen" => 232,      # One SECURITY_DESCRIPTOR is 232 bytes.
             "LastWrite" => "\x90mZ\cX{\xA3\xBD\cA\c@\cA"
                           # Key was last modifed 1998/06/01 16:29:32 GMT
           );

With arguments, each one must be the name of a item given above. The return value is the information associated with the listed names. In other words:

    return $key->Information( @names );

returns the same list as:

    %info= $key->Information;
    return @info{@names};
Delimiter
$oldDelim= $key->Delimiter
$oldDelim= $key->Delimiter( $newDelim )

Gets and possibly changes the delimiter used for this object. The delimiter is appended to subkey names and prepended to value names in many return values. It is also used when parsing keys passed to tied hashes.

The delimiter defaults to backslash ('\\') but is inherited from the object used to create a new object and can be specified by an option when a new object is created.

Handle
$handle= $key->Handle

Returns the raw HKEY handle for the associated Registry key as an integer value. This value can then be used to Reg*() calls from Win32API::Registry. However, it is usually easier to just call the Win32API::Registry calls directly via:

    $key->RegNotifyChangeKeyValue( ... );

For the virtual root of the local or a remote Registry, Handle() return "NONE".

Path
$path= $key->Path

Returns a string describing the path of key names to this Registry key. The string is built so that if it were passed to $Registry-Open()>, it would reopen the same Registry key [except in the rare case where one of the key names contains $key-Delimiter>].

Machine
$computerName= $key->Machine

Returns the name of the computer [or "machine"] on which this Registry key resides. Returns "" for local Registry keys.

Access

Returns the numeric value of the bit mask used to specify the types of access requested when this Registry key was opened. Can be compared to KEY_* values.

OS_Delimiter

Returns the delimiter used by the operating system's RegOpenKeyEx() call. For Win32, this is always backslash ("\\").

Roots

Returns the mapping from root key names like "LMachine" to their associated HKEY_* constants. Primarily for internal use and subject to change.

Tie
$key->Tie( \%hash );

Ties the referenced hash to that Registry key. Pretty much the same as

    tie %hash, ref($key), $key;

Since ref($key) is the class [package] to tie the hash to and TIEHASH() just returns its argument, $key, [without calling new()] when it sees that it is already a blessed object.

TiedRef
$TiedHashRef= $hash_or_obj_ref->TiedRef

For a simple object, returns a reference to a hash tied to the object. Used to promote a simple object into a combined object and hash ref.

If already a reference to a tied hash [that is also an object], it just returns itself [$ref == $ref-TiedRef>].

Mostly used internally.

ArrayValues
$oldBool= $key->ArrayValues
$oldBool= $key->ArrayValues( $newBool )

Gets the current setting of the ArrayValues option and possibly turns it on or off.

When off, Registry values fetched via a tied hash are returned as just a value scalar [the same as GetValue() in a scalar context]. When on, they are returned as a reference to an array containing the value data as the [0] element and the data type as the [1] element.

TieValues
$oldBool= TieValues
$oldBool= TieValues( $newBool )

Gets the current setting of the TieValues option and possibly turns it on or off.

Turning this option on is not yet supported in this release of Win32::TieRegistry. In a future release, turning this option on will cause Registry values returned from a tied hash to be a tied array that you can use to modify the value in the Registry.

FastDelete
$oldBool= $key->FastDelete
$oldBool= $key->FastDelete( $newBool )

Gets the current setting of the FastDelete option and possibly turns it on or off.

When on, successfully deleting a Registry key [via a tied hash] simply returns 1.

When off, successfully deleting a Registry key [via a tied hash and not in a void context] returns a reference to a hash that contains the values present in the key when it was deleted. This hash is just like that returned when referencing the key before it was deleted except that it is an ordinary hash, not one tied to the Win32::TieRegistry package.

Note that deleting either a Registry key or value via a tied hash in a void context prevents any overhead in trying to build an appropriate return value.

Note that deleting a Registry value via a tied hash [not in a void context] returns the value data even if <FastDelete> is on.

SplitMultis
$oldBool= $key->SplitMultis
$oldBool= $key->SplitMultis( $newBool )

Gets the current setting of the SplitMultis option and possibly turns it on or off.

If on, Registry values of type REG_MULTI_SZ are returned as a reference to an array of strings. See GetValue() for more information.

DWordsToHex
$oldBool= $key->DWordsToHex
$oldBool= $key->DWordsToHex( $newBool )

Gets the current setting of the DWordsToHex option and possibly turns it on or off.

If on, Registry values of type REG_DWORD are returned as a hex string with leading "0x" and longer than 4 characters. See GetValue() for more information.

FixSzNulls
$oldBool= $key->FixSzNulls
$oldBool= $key->FixSzNulls( $newBool )

Gets the current setting of the FixSzNulls option and possibly turns it on or off.

If on, Registry values of type REG_SZ and REG_EXPAND_SZ have trailing '\0's added before they are set and stripped before they are returned. See GetValue() and SetValue() for more information.

DualTypes
$oldBool= $key->DualTypes
$oldBool= $key->DualTypes( $newBool )

Gets the current setting of the DualTypes option and possibly turns it on or off.

If on, data types are returned as a combined numeric/string value holding both the numeric value of a REG_* constant and the string value of the constant's name. See GetValue() for more information.

DualBinVals
$oldBool= $key->DualBinVals
$oldBool= $key->DualBinVals( $newBool )

Gets the current setting of the DualBinVals option and possibly turns it on or off.

If on, Registry value data of type REG_BINARY and no more than 4 bytes long and Registry values of type REG_DWORD are returned as a combined numeric/string value where the numeric value is the "unpacked" binary value as returned by:

        hex reverse unpack( "h*", $valData )

on a "little-endian" computer. [Would be hex unpack("H*",$valData) on a "big-endian" computer if this module is ever ported to one.]

See GetValue() for more information.

GetOptions
@oldOptValues= $key->GetOptions( @optionNames )
$refHashOfOldOpts= $key->GetOptions()
$key->GetOptions( \%hashForOldOpts )

Returns the current setting of any of the following options:

    Delimiter     FixSzNulls    DWordsToHex
    ArrayValues   SplitMultis   DualBinVals
    TieValues     FastDelete    DualTypes

Pass in one or more of the above names (as strings) to get back an array of the corresponding current settings in the same order:

  my( $fastDel, $delim )= $key->GetOptions("FastDelete","Delimiter");

Pass in no arguments to get back a reference to a hash where the above option names are the keys and the values are the corresponding current settings for each option:

  my $href= $key->GetOptions();
  my $delim= $href->{Delimiter};

Pass in a single reference to a hash to have the above key/value pairs added to the referenced hash. For this case, the return value is the original object so further methods can be chained after the call to GetOptions:

  my %oldOpts;
  $key->GetOptions( \%oldOpts )->SetOptions( Delimiter => "/" );
SetOptions
@oldOpts= $key->SetOptions( optNames=>$optValue,... )

Changes the current setting of any of the following options, returning the previous setting(s):

    Delimiter     FixSzNulls    DWordsToHex   AllowLoad
    ArrayValues   SplitMultis   DualBinVals   AllowSave
    TieValues     FastDelete    DualTypes

For AllowLoad and AllowSave, instead of the previous setting, SetOptions returns whether or not the change was successful.

In a scalar context, returns only the last item. The last option can also be specified as "ref" or "r" [which doesn't need to be followed by a value] to allow chaining:

    $key->SetOptions(AllowSave=>1,"ref")->RegSaveKey(...)
SetValue
$okay= $key->SetValue( $ValueName, $ValueData );
$okay= $key->SetValue( $ValueName, $ValueData, $ValueType );

Adds or replaces a Registry value. Returns a true value if successfully, false otherwise.

$ValueName is the name of the value to add or replace and should not have a delimiter prepended to it. Case is ignored.

$ValueType is assumed to be REG_SZ if it is omitted. Otherwise, it should be one the REG_* constants.

$ValueData is the data to be stored in the value, probably packed into a Perl string. Other supported formats for value data are listed below for each posible $ValueType.

REG_SZ or REG_EXPAND_SZ

The only special processing for these values is the addition of the required trailing '\0' if it is missing. This can be turned off by disabling the FixSzNulls option.

REG_MULTI_SZ

These values can also be specified as a reference to a list of strings. For example, the following two lines are equivalent:

    $key->SetValue( "Val1\000Value2\000LastVal\000\000", "REG_MULTI_SZ" );
    $key->SetValue( ["Val1","Value2","LastVal"], "REG_MULTI_SZ" );

Note that if the required two trailing nulls ("\000\000") are missing, then this release of SetValue() will not add them.

REG_DWORD

These values can also be specified as a hex value with the leading "0x" included and totaling more than 4 bytes. These will be packed into a 4-byte string via:

    $data= pack( "L", hex($data) );
REG_BINARY

This value type is listed just to emphasize that no alternate format is supported for it. In particular, you should not pass in a numeric value for this type of data. SetValue() cannot distinguish such from a packed string that just happens to match a numeric value and so will treat it as a packed string.

An alternate calling format:

    $okay= $key->SetValue( $ValueName, [ $ValueData, $ValueType ] );

[two arguments, the second of which is a reference to an array containing the value data and value type] is supported to ease using tied hashes with SetValue().

CreateKey
$newKey= $key->CreateKey( $subKey );
$newKey= $key->CreateKey( $subKey, { Option=>OptVal,... } );

Creates a Registry key or just updates attributes of one. Calls RegCreateKeyEx() then, if it succeeded, creates an object associated with the [possibly new] subkey.

$subKey is the name of a subkey [or a path to one] to be created or updated. It can also be a reference to an array containing a list of subkey names.

The second argument, if it exists, should be a reference to a hash specifying options either to be passed to RegCreateKeyEx() or to be used when creating the associated object. The following items are the supported keys for this options hash:

Delimiter

Specifies the delimiter to be used to parse $subKey and to be used in the new object. Defaults to $key-Delimiter>.

Access

Specifies the types of access requested when the subkey is opened. Should be a numeric bit mask that combines one or more KEY_* constant values.

Class

The name to assign as the class of the new or updated subkey. Defaults to "" as we have never seen a use for this information.

Disposition

Lets you specify a reference to a scalar where, upon success, will be stored either REG_CREATED_NEW_KEY() or REG_OPENED_EXISTING_KEY() depending on whether a new key was created or an existing key was opened.

If you, for example, did use Win32::TieRegistry qw(REG_CREATED_NEW_KEY) then you can use REG_CREATED_NEW_KEY() to compare against the numeric value stored in the referenced scalar.

If the DualTypes option is enabled, then in addition to the numeric value described above, the referenced scalar will also have a string value equal to either "REG_CREATED_NEW_KEY" or "REG_OPENED_EXISTING_KEY", as appropriate.

Security

Lets you specify a SECURITY_ATTRIBUTES structure packed into a Perl string. See Win32API::Registry::RegCreateKeyEx() for more information.

Volatile

If true, specifies that the new key should be volatile, that is, stored only in memory and not backed by a hive file [and not saved if the computer is rebooted]. This option is ignored under Windows 95. Specifying Volatile=1 is the same as specifying Options=REG_OPTION_VOLATILE.

Backup

If true, specifies that the new key should be opened for backup/restore access. The Access option is ignored. If the calling process has enabled "SeBackupPrivilege", then the subkey is opened with KEY_READ access as the "LocalSystem" user which should have access to all subkeys. If the calling process has enabled "SeRestorePrivilege", then the subkey is opened with KEY_WRITE access as the "LocalSystem" user which should have access to all subkeys.

This option is ignored under Windows 95. Specifying Backup=1 is the same as specifying Options=REG_OPTION_BACKUP_RESTORE.

Options

Lets you specify options to the RegOpenKeyEx() call. The value for this option should be a numeric value combining zero or more of the REG_OPTION_* bit masks. You may with to used the Volatile and/or Backup options instead of this one.

StoreKey
$newKey= $key->StoreKey( $subKey, \%Contents );

Primarily for internal use.

Used to create or update a Registry key and any number of subkeys or values under it or its subkeys.

$subKey is the name of a subkey to be created [or a path of subkey names separated by delimiters]. If that subkey already exists, then it is updated.

\%Contents is a reference to a hash containing pairs of value names with value data and/or subkey names with hash references similar to \%Contents. Each of these cause a value or subkey of $subKey to be created or updated.

If $Contents{""} exists and is a reference to a hash, then it used as the options argument when CreateKey() is called for $subKey. This allows you to specify ...

    if(  defined( $$data{""} )  &&  "HASH" eq ref($$data{""})  ) {
        $self= $this->CreateKey( $subKey, delete $$data{""} );
Load
$newKey= $key->Load( $file )
$newKey= $key->Load( $file, $newSubKey )
$newKey= $key->Load( $file, $newSubKey, { Option=>OptVal... } )
$newKey= $key->Load( $file, { Option=>OptVal... } )

Loads a hive file into a Registry. That is, creates a new subkey and associates a hive file with it.

$file is a hive file, that is a file created by calling RegSaveKey(). The $file path is interpreted relative to %SystemRoot%/System32/config on the machine where $key resides.

$newSubKey is the name to be given to the new subkey. If $newSubKey is specified, then $key must be HKEY_LOCAL_MACHINE or HKEY_USERS of the local computer or a remote computer and $newSubKey should not contain any occurrences of either the delimiter or the OS delimiter.

If $newSubKey is not specified, then it is as if $key was $Registry-{LMachine} and $newSubKey is "PerlTie:999" where "999" is actually a sequence number incremented each time this process calls Load().

You can specify as the last argument a reference to a hash containing options. You can specify the same options that you can specify to Open(). See Open() for more information on those. In addition, you can specify the option "NewSubKey". The value of this option is interpretted exactly as if it was specified as the $newSubKey parameter and overrides the $newSubKey if one was specified.

The hive is automatically unloaded when the returned object [$newKey] is destroyed. Registry key objects opened within the hive will keep a reference to the $newKey object so that it will not be destroyed before these keys are closed.

UnLoad
$okay= $key->UnLoad

Unloads a hive that was loaded via Load(). Cannot unload other hives. $key must be the return from a previous call to Load(). $key is closed and then the hive is unloaded.

AllowSave
$okay= AllowSave( $bool )

Enables or disables the "ReBackupPrivilege" privilege for the current process. You will probably have to enable this privilege before you can use RegSaveKey().

The return value indicates whether the operation succeeded, not whether the privilege was previously enabled.

AllowLoad
$okay= AllowLoad( $bool )

Enables or disables the "ReRestorePrivilege" privilege for the current process. You will probably have to enable this privilege before you can use RegLoadKey(), RegUnLoadKey(), RegReplaceKey(), or RegRestoreKey and thus Load() and UnLoad().

The return value indicates whether the operation succeeded, not whether the privilege was previously enabled.

Exports [use and import()]

To have nothing imported into your package, use something like:

    use Win32::TieRegistry 0.20 ();

which would verify that you have at least version 0.20 but wouldn't call import(). The Changes file can be useful in figuring out which, if any, prior versions of Win32::TieRegistry you want to support in your script.

The code

    use Win32::TieRegistry;

imports the variable $Registry into your package and sets it to be a reference to a hash tied to a copy of the master Registry virtual root object with the default options. One disadvantage to this "default" usage is that Perl does not support checking the module version when you use it.

Alternately, you can specify a list of arguments on the use line that will be passed to the Win32::TieRegistry-import()> method to control what items to import into your package. These arguments fall into the following broad categories:

Import a reference to a hash tied to a Registry virtual root

You can request that a scalar variable be imported (possibly) and set to be a reference to a hash tied to a Registry virtual root using any of the following types of arguments or argument pairs:

"TiedRef", '$scalar'
"TiedRef", '$pack::scalar'
"TiedRef", 'scalar'
"TiedRef", 'pack::scalar'

All of the above import a scalar named $scalar into your package (or the package named "pack") and then sets it.

'$scalar'
'$pack::scalar'

These are equivalent to the previous items to support a more traditional appearance to the list of exports. Note that the scalar name cannot be "RegObj" here.

"TiedRef", \$scalar
\$scalar

These versions don't import anything but set the referenced $scalar.

Import a hash tied to the Registry virtual root

You can request that a hash variable be imported (possibly) and tied to a Registry virtual root using any of the following types of arguments or argument pairs:

"TiedHash", '%hash'
"TiedHash", '%pack::hash'
"TiedHash", 'hash'
"TiedHash", 'pack::hash'

All of the above import a hash named %hash into your package (or the package named "pack") and then sets it.

'%hash'
'%pack::hash'

These are equivalent to the previous items to support a more traditional appearance to the list of exports.

"TiedHash", \%hash
\%hash

These versions don't import anything but set the referenced %hash.

Import a Registry virtual root object

You can request that a scalar variable be imported (possibly) and set to be a Registry virtual root object using any of the following types of arguments or argument pairs:

"ObjectRef", '$scalar'
"ObjectRef", '$pack::scalar'
"ObjectRef", 'scalar'
"ObjectRef", 'pack::scalar'

All of the above import a scalar named $scalar into your package (or the package named "pack") and then sets it.

'$RegObj'

This is equivalent to the previous items for backward compatibility.

"ObjectRef", \$scalar

This version doesn't import anything but sets the referenced $scalar.

Import constant(s) exported by Win32API::Registry

You can list any constants that are exported by Win32API::Registry to have them imported into your package. These constants have names starting with "KEY_" or "REG_" (or even "HKEY_").

You can also specify ":KEY_", ":REG_", and even ":HKEY_" to import a whole set of constants.

See Win32API::Registry documentation for more information.

Options

You can list any option names that can be listed in the SetOptions() method call, each folowed by the value to use for that option. A Registry virtual root object is created, all of these options are set for it, then each variable to be imported/set is associated with this object.

In addition, the following special options are supported:

ExportLevel

Whether to import variables into your package or some package that uses your package. Defaults to the value of $Exporter::ExportLevel and has the same meaning. See the the Exporter manpage module for more information.

ExportTo

The name of the package to import variables and constants into. Overrides ExportLevel.

Specifying constants in your Perl code

This module was written with a strong emphasis on the convenience of the module user. Therefore, most places where you can specify a constant like REG_SZ() also allow you to specify a string containing the name of the constant, "REG_SZ". This is convenient because you may not have imported that symbolic constant.

Perl also emphasizes programmer convenience so the code REG_SZ can be used to mean REG_SZ() or "REG_SZ" or be illegal. Note that using &REG_SZ (as we've seen in much Win32 Perl code) is not a good idea since it passes the current @_ to the constant() routine of the module which, at the least, can give you a warning under -w.

Although greatly a matter of style, the "safest" practice is probably to specifically list all constants in the use Win32::TieRegistry statement, specify use strict [or at least use strict qw(subs)], and use bare constant names when you want the numeric value. This will detect mispelled constant names at compile time.

    use strict;
    my $Registry;
    use Win32::TieRegistry 0.20 (
        TiedRef => \$Registry,  Delimiter => "/",  ArrayValues => 1,
        SplitMultis => 1,  AllowLoad => 1,
        qw( REG_SZ REG_EXPAND_SZ REG_DWORD REG_BINARY REG_MULTI_SZ
            KEY_READ KEY_WRITE KEY_ALL_ACCESS ),
    );
    $Registry->{"LMachine/Software/FooCorp/"}= {
        "FooWriter/" => {
            "/Fonts" => [ ["Times","Courier","Lucinda"], REG_MULTI_SZ ],
            "/WindowSize" => [ pack("LL",24,80), REG_BINARY ],
            "/TaskBarIcon" => [ "0x0001", REG_DWORD ],
        },
    }  or  die "Can't create Software/FooCorp/: $^E\n";

If you don't want to use strict qw(subs), the second safest practice is similar to the above but use the REG_SZ() form for constants when possible and quoted constant names when required. Note that qw() is a form of quoting.

    use Win32::TieRegistry 0.20 qw(
        TiedRef $Registry
        Delimiter /  ArrayValues 1  SplitMultis 1  AllowLoad 1
        REG_SZ REG_EXPAND_SZ REG_DWORD REG_BINARY REG_MULTI_SZ
        KEY_READ KEY_WRITE KEY_ALL_ACCESS
    );
    $Registry->{"LMachine/Software/FooCorp/"}= {
        "FooWriter/" => {
            "/Fonts" => [ ["Times","Courier","Lucinda"], REG_MULTI_SZ() ],
            "/WindowSize" => [ pack("LL",24,80), REG_BINARY() ],
            "/TaskBarIcon" => [ "0x0001", REG_DWORD() ],
        },
    }  or  die "Can't create Software/FooCorp/: $^E\n";

The examples in this document mostly use quoted constant names ("REG_SZ") since that works regardless of which constants you imported and whether or not you have use strict in your script. It is not the best choice for you to use for real scripts (vs. examples) because it is less efficient and is not supported by most other similar modules.

SUMMARY

Most things can be done most easily via tied hashes. Skip down to the the Tied Hashes Summary to get started quickly.

Objects Summary

Here are quick examples that document the most common functionality of all of the method functions [except for a few almost useless ones].

    # Just another way of saying Open():
    $key= new Win32::TieRegistry "LMachine\\Software\\",
      { Access=>KEY_READ()|KEY_WRITE(), Delimiter=>"\\" };

    # Open a Registry key:
    $subKey= $key->Open( "SubKey/SubSubKey/",
      { Access=>KEY_ALL_ACCESS, Delimiter=>"/" } );

    # Connect to a remote Registry key:
    $remKey= $Registry->Connect( "MachineName", "LMachine/",
      { Access=>KEY_READ, Delimiter=>"/" } );

    # Get value data:
    $valueString= $key->GetValue("ValueName");
    ( $valueString, $valueType )= $key->GetValue("ValueName");

    # Get list of value names:
    @valueNames= $key->ValueNames;

    # Get list of subkey names:
    @subKeyNames= $key->SubKeyNames;

    # Get combined list of value names (with leading delimiters)
    # and subkey names (with trailing delimiters):
    @memberNames= $key->MemberNames;

    # Get all information about a key:
    %keyInfo= $key->Information;
    # keys(%keyInfo)= qw( Class LastWrite SecurityLen
    #   CntSubKeys MaxSubKeyLen MaxSubClassLen
    #   CntValues MaxValNameLen MaxValDataLen );

    # Get selected information about a key:
    ( $class, $cntSubKeys )= $key->Information( "Class", "CntSubKeys" );

    # Get and/or set delimiter:
    $delim= $key->Delimiter;
    $oldDelim= $key->Delimiter( $newDelim );

    # Get "path" for an open key:
    $path= $key->Path;
    # For example, "/CUser/Control Panel/Mouse/"
    # or "//HostName/LMachine/System/DISK/".

    # Get name of machine where key is from:
    $mach= $key->Machine;
    # Will usually be "" indicating key is on local machine.

    # Control different options (see main documentation for descriptions):
    $oldBool= $key->ArrayValues( $newBool );
    $oldBool= $key->FastDelete( $newBool );
    $oldBool= $key->FixSzNulls( $newBool );
    $oldBool= $key->SplitMultis( $newBool );
    $oldBool= $key->DWordsToHex( $newBool );
    $oldBool= $key->DualBinVals( $newBool );
    $oldBool= $key->DualTypes( $newBool );
    @oldBools= $key->SetOptions( ArrayValues=>1, FastDelete=>1, FixSzNulls=>0,
      Delimiter=>"/", AllowLoad=>1, AllowSave=>1 );
    @oldBools= $key->GetOptions( ArrayValues, FastDelete, FixSzNulls );

    # Add or set a value:
    $key->SetValue( "ValueName", $valueDataString );
    $key->SetValue( "ValueName", pack($format,$valueData), "REG_BINARY" );

    # Add or set a key:
    $key->CreateKey( "SubKeyName" );
    $key->CreateKey( "SubKeyName",
      { Access=>"KEY_ALL_ACCESS", Class=>"ClassName",
        Delimiter=>"/", Volatile=>1, Backup=>1 } );

    # Load an off-line Registry hive file into the on-line Registry:
    $newKey= $Registry->Load( "C:/Path/To/Hive/FileName" );
    $newKey= $key->Load( "C:/Path/To/Hive/FileName", "NewSubKeyName",
                     { Access=>"KEY_READ" } );
    # Unload a Registry hive file loaded via the Load() method:
    $newKey->UnLoad;

    # (Dis)Allow yourself to load Registry hive files:
    $success= $Registry->AllowLoad( $bool );

    # (Dis)Allow yourself to save a Registry key to a hive file:
    $success= $Registry->AllowSave( $bool );

    # Save a Registry key to a new hive file:
    $key->RegSaveKey( "C:/Path/To/Hive/FileName", [] );

Other Useful Methods

See Win32API::Registry for more information on these methods. These methods are provided for coding convenience and are identical to the Win32API::Registry functions except that these don't take a handle to a Registry key, instead getting the handle from the invoking object [$key].

    $key->RegGetKeySecurity( $iSecInfo, $sSecDesc, $lenSecDesc );
    $key->RegLoadKey( $sSubKeyName, $sPathToFile );
    $key->RegNotifyChangeKeyValue(
      $bWatchSubtree, $iNotifyFilter, $hEvent, $bAsync );
    $key->RegQueryMultipleValues(
      $structValueEnts, $cntValueEnts, $Buffer, $lenBuffer );
    $key->RegReplaceKey( $sSubKeyName, $sPathToNewFile, $sPathToBackupFile );
    $key->RegRestoreKey( $sPathToFile, $iFlags );
    $key->RegSetKeySecurity( $iSecInfo, $sSecDesc );
    $key->RegUnLoadKey( $sSubKeyName );

Tied Hashes Summary

For fast learners, this may be the only section you need to read. Always append one delimiter to the end of each Registry key name and prepend one delimiter to the front of each Registry value name.

Opening keys

    use Win32::TieRegistry ( Delimiter=>"/", ArrayValues=>1 );
    $Registry->Delimiter("/");                  # Set delimiter to "/".
    $swKey= $Registry->{"LMachine/Software/"};
    $winKey= $swKey->{"Microsoft/Windows/CurrentVersion/"};
    $userKey= $Registry->
      {"CUser/Software/Microsoft/Windows/CurrentVersion/"};
    $remoteKey= $Registry->{"//HostName/LMachine/"};

Reading values

    $progDir= $winKey->{"/ProgramFilesDir"};    # "C:\\Program Files"
    $tip21= $winKey->{"Explorer/Tips//21"};     # Text of tip #21.

    $winKey->ArrayValues(1);
    ( $devPath, $type )= $winKey->{"/DevicePath"};
    # $devPath eq "%SystemRoot%\\inf"
    # $type eq "REG_EXPAND_SZ"  [if you have SetDualVar.pm installed]
    # $type == REG_EXPAND_SZ()  [if did C<use Win32::TieRegistry qw(:REG_)>]

Setting values

    $winKey->{"Setup//SourcePath"}= "\\\\SwServer\\SwShare\\Windows";
    # Simple.  Assumes data type of REG_SZ.

    $winKey->{"Setup//Installation Sources"}=
      [ "D:\x00\\\\SwServer\\SwShare\\Windows\0\0", "REG_MULTI_SZ" ];
    # "\x00" and "\0" used to mark ends of each string and end of list.

    $winKey->{"Setup//Installation Sources"}=
      [ ["D:","\\\\SwServer\\SwShare\\Windows"], "REG_MULTI_SZ" ];
    # Alternate method that is easier to read.

    $userKey->{"Explorer/Tips//DisplayInitialTipWindow"}=
      [ pack("L",0), "REG_DWORD" ];
    $userKey->{"Explorer/Tips//Next"}= [ pack("S",3), "REG_BINARY" ];
    $userKey->{"Explorer/Tips//Show"}= [ pack("L",0), "REG_BINARY" ];

Adding keys

    $swKey->{"FooCorp/"}= {
        "FooWriter/" => {
            "/Version" => "4.032",
            "Startup/" => {
                "/Title" => "Foo Writer Deluxe ][",
                "/WindowSize" => [ pack("LL",$wid,$ht), "REG_BINARY" ],
                "/TaskBarIcon" => [ "0x0001", "REG_DWORD" ],
            },
            "Compatibility/" => {
                "/AutoConvert" => "Always",
                "/Default Palette" => "Windows Colors",
            },
        },
        "/License", => "0123-9C8EF1-09-FC",
    };

Listing all subkeys and values

    @members= keys( %{$swKey} );
    @subKeys= grep(  m#^/#,  keys( %{$swKey->{"Classes/batfile/"}} )  );
    # @subKeys= ( "/", "/EditFlags" );
    @valueNames= grep(  ! m#^/#,  keys( %{$swKey->{"Classes/batfile/"}} )  );
    # @valueNames= ( "DefaultIcon/", "shell/", "shellex/" );

Deleting values or keys with no subkeys

    $oldValue= delete $userKey->{"Explorer/Tips//Next"};

    $oldValues= delete $userKey->{"Explorer/Tips/"};
    # $oldValues will be reference to hash containing deleted keys values.

Closing keys

    undef $swKey;               # Explicit way to close a key.
    $winKey= "Anything else";   # Implicitly closes a key.
    exit 0;                     # Implicitly closes all keys.

Tie::Registry

This module was originally called Tie::Registry. Changing code that used Tie::Registry over to Win32::TieRegistry is trivial as the module name should only be mentioned once, in the use line. However, finding all of the places that used Tie::Registry may not be completely trivial so we have included Tie/Registry.pm which you can install to provide backward compatibility.

AUTHOR

Tye McQueen. See http://www.metronet.com/~tye/ or e-mail tye@metronet.com with bug reports.

SEE ALSO

Win32API::Registry - Provides access to Reg*(), HKEY_*, KEY_*, REG_* [required].

Win32::WinError - Defines ERROR_* values [optional].

SetDualVar - For returning REG_* values as combined string/integer values [optional].

BUGS

Perl5.004_02 has bugs that make Win32::TieRegistry fail in strange and subtle ways.

Using Win32::TieRegistry with versions of Perl prior to 5.005 can be tricky or impossible. Most notes about this have been removed from the documentation (they get rather complicated and confusing). This includes references to $^E perhaps not being meaningful.

Because Perl hashes are case sensitive, certain lookups are also case sensistive. In particular, the root keys ("Classes", "CUser", "LMachine", "Users", "PerfData", "CConfig", "DynData", and HKEY_*) must always be entered without changing between upper and lower case letters. Also, the special rule for matching subkey names that contain the user-selected delimiter only works if case is matched. All other key name and value name lookups should be case insensitive because the underlying Reg*() calls ignore case.

Information about each key is cached when using a tied hash. This cache is not flushed nor updated when changes are made, even when the same tied hash is used to make the changes.

Current implementations of Perl's "global destruction" phase can cause objects returned by Load() to be destroyed while keys within the hive are still open, if the objects still exist when the script starts to exit. When this happens, the automatic UnLoad() will report a failure and the hive will remain loaded in the Registry.

Trying to Load() a hive file that is located on a remote network share may silently delete all data from the hive. This is a bug in the Win32 APIs, not any Perl code or modules. This module does not try to protect you from this bug.

There is no test suite.

FUTURE DIRECTIONS

The following items are desired by the author and may appear in a future release of this module.

TieValues option

Currently described in main documentation but no yet implemented.

AutoRefresh option

Trigger use of RegNotifyChangeKeyValue() to keep tied hash caches up-to-date even when other programs make changes.

Error options

Allow the user to have unchecked calls (calls in a "void context") to automatically report errors via warn or die.

For complex operations, such a copying an entire subtree, provide access to detailed information about errors (and perhaps some warnings) that were encountered. Let the user control whether the complex operation continues in spite of errors.


Win32API::File - Low-level access to Win32 system API calls for files/dirs.

    • Object Oriented/Tied Handle Interface
    • Exports
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

Win32API::File - Low-level access to Win32 system API calls for files/dirs.

SYNOPSIS

  use Win32API::File 0.08 qw( :ALL );

  MoveFile( $Source, $Destination )
    or  die "Can't move $Source to $Destination: ",fileLastError(),"\n";
  MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() )
    or  die "Can't move $Source to $Destination: ",fileLastError(),"\n";
  [...]

DESCRIPTION

This provides fairly low-level access to the Win32 System API calls dealing with files and directories.

To pass in NULL as the pointer to an optional buffer, pass in an empty list reference, [].

Beyond raw access to the API calls and related constants, this module handles smart buffer allocation and translation of return codes.

All functions, unless otherwise noted, return a true value for success and a false value for failure and set $^E on failure.

Object Oriented/Tied Handle Interface

WARNING: this is new code, use at your own risk.

This version of Win32API::File can be used like an IO::File object:

  my $file = new Win32API::File "+> foo";
  binmode $file;
  print $file "hello there\n";
  seek $file, 0, 0;
  my $line = <$file>;
  $file->close;

It also supports tying via a win32 handle (for example, from createFile()):

  tie FILE, 'Win32API::File', $win32_handle;
  print FILE "...";

It has not been extensively tested yet and buffered I/O is not yet implemented.

Exports

Nothing is exported by default. The following tags can be used to have large sets of symbols exported: ":Func", ":FuncA", ":FuncW", ":Misc", ":DDD_", ":DRIVE_", ":FILE_", ":FILE_ATTRIBUTE_", ":FILE_FLAG_", ":FILE_SHARE_", ":FILE_TYPE_", ":FS_", ":FSCTL_", ":HANDLE_FLAG_", ":IOCTL_STORAGE_", ":IOCTL_DISK_", ":GENERIC_", ":MEDIA_TYPE", ":MOVEFILE_", ":SECURITY_", ":SEM_", and ":PARTITION_".

":Func"

The basic function names: attrLetsToBits, createFile, fileConstant, fileLastError, getLogicalDrives, setFilePointer, getFileSize, CloseHandle, CopyFile, CreateFile, DefineDosDevice, DeleteFile, DeviceIoControl, FdGetOsFHandle, GetDriveType, GetFileAttributes, GetFileSize, GetFileType, GetHandleInformation, GetLogicalDrives, GetLogicalDriveStrings, GetOsFHandle, GetOverlappedResult, GetVolumeInformation, IsContainerPartition, IsRecognizedPartition, MoveFile, MoveFileEx, OsFHandleOpen, OsFHandleOpenFd, QueryDosDevice, ReadFile, SetErrorMode, SetFilePointer, SetHandleInformation, and WriteFile.

attrLetsToBits
$uBits= attrLetsToBits( $sAttributeLetters )

Converts a string of file attribute letters into an unsigned value with the corresponding bits set. $sAttributeLetters should contain zero or more letters from "achorst":

"a"

FILE_ATTRIBUTE_ARCHIVE

"c"

FILE_ATTRIBUTE_COMPRESSED

"h"

FILE_ATTRIBUTE_HIDDEN

"o"

FILE_ATTRIBUTE_OFFLINE

"r"

FILE_ATTRIBUTE_READONLY

"s"

FILE_ATTRIBUTE_SYSTEM

"t"

FILE_ATTRIBUTE_TEMPORARY

createFile
$hObject= createFile( $sPath )
$hObject= createFile( $sPath, $rvhvOptions )
$hObject= createFile( $sPath, $svAccess )
$hObject= createFile( $sPath, $svAccess, $rvhvOptions )
$hObject= createFile( $sPath, $svAccess, $svShare )
$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )

This is a Perl-friendly wrapper around CreateFile.

On failure, $hObject gets set to a false value and regLastError() and $^E are set to the reason for the failure. Otherwise, $hObject gets set to a Win32 native file handle which is alwasy a true value [returns "0 but true" in the impossible(?) case of the handle having a value of 0].

$sPath is the path to the file [or device, etc.] to be opened. See CreateFile for more information on possible special values for $sPath.

$svAccess can be a number containing the bit mask representing the specific type(s) of access to the file that you desire. See the $uAccess parameter to CreateFile for more information on these values.

More likely, $svAccess is a string describing the generic type of access you desire and possibly the file creation options to use. In this case, $svAccess should contain zero or more characters from "qrw" [access desired], zero or one character each from "ktn" and "ce", and optional white space. These letters stand for, respectively, "Query access", "Read access", "Write access", "Keep if exists", "Truncate if exists", "New file only", "Create if none", and "Existing file only". Case is ignored.

You can pass in "?" for $svAccess to have an error message displayed summarizing its possible values. This is very handy when doing on-the-fly programming using the Perl debugger:

    Win32API::File::createFile:  $svAccess can use the following:
        One or more of the following:
            q -- Query access (same as 0)
            r -- Read access (GENERIC_READ)
            w -- Write access (GENERIC_WRITE)
        At most one of the following:
            k -- Keep if exists
            t -- Truncate if exists
            n -- New file only (fail if file already exists)
        At most one of the following:
            c -- Create if doesn't exist
            e -- Existing file only (fail if doesn't exist)
      ''   is the same as 'q  k e'
      'r'  is the same as 'r  k e'
      'w'  is the same as 'w  t c'
      'rw' is the same as 'rw k c'
      'rt' or 'rn' implies 'c'.
      Or $access can be numeric.

$svAccess is designed to be "do what I mean", so you can skip the rest of its explanation unless you are interested in the complex details. Note that, if you want write access to a device, you need to specify "k" [and perhaps "e", as in "w ke" or "rw ke"] since Win32 suggests OPEN_EXISTING be used when opening a device.

"q"

Stands for "Query access". This is really a no-op since you always have query access when you open a file. You can specify "q" to document that you plan to query the file [or device, etc.]. This is especially helpful when you don't want read nor write access since something like "q" or "q ke" may be easier to understand than just "" or "ke".

"r"

Stands for "Read access". Sets the GENERIC_READ bit(s) in the $uAccess that is passed to CreateFile. This is the default access if the $svAccess parameter is missing [or if it is undef and $rvhvOptions doesn't specify an "Access" option].

"w"

Stands for "Write access". Sets the GENERIC_WRITE bit(s) in the $uAccess that is passed to CreateFile.

"k"

Stands for "Keep if exists". If the requested file exists, then it is opened. This is the default unless GENERIC_WRITE access has been requested but GENERIC_READ access has not been requested. Contrast with "t" and "n".

"t"

Stands for "Truncate if exists". If the requested file exists, then it is truncated to zero length and then opened. This is the default if GENERIC_WRITE access has been requested and GENERIC_READ access has not been requested. Contrast with "k" and "n".

"n"

Stands for "New file only". If the requested file exists, then it is not opened and the createFile call fails. Contrast with "k" and "t". Can't be used with "e".

"c"

Stands for "Create if none". If the requested file does not exist, then it is created and then opened. This is the default if GENERIC_WRITE access has been requested or if "t" or "n" was specified. Contrast with "e".

"e"

Stands for "Existing file only". If the requested file does not exist, then nothing is opened and the createFile call fails. This is the default unless GENERIC_WRITE access has been requested or "t" or "n" was specified. Contrast with "c". Can't be used with "n".

The characters from "ktn" and "ce" are combined to determine the what value for $uCreate to pass to CreateFile [unless overridden by $rvhvOptions]:

"kc"

OPEN_ALWAYS

"ke"

OPEN_EXISTING

"tc"

TRUNCATE_EXISTING

"te"

CREATE_ALWAYS

"nc"

CREATE_NEW

"ne"

Illegal.

$svShare controls how the file is shared, that is, whether other processes can have read, write, and/or delete access to the file while we have it opened. $svShare will usually be a string containing zero or more characters from "rwd" but can also be a numeric bit mask.

"r" sets the FILE_SHARE_READ bit which allows other processes to have read access to the file. "w" sets the FILE_SHARE_WRITE bit which allows other processes to have write access to the file. "d" sets the FILE_SHARE_DELETE bit which allows other processes to have delete access to the file [ignored under Windows 95].

The default for $svShare is "rw" which provides the same sharing as using regular perl open().

If another process currently has read, write, and/or delete access to the file and you don't allow that level of sharing, then your call to createFile will fail. If you requested read, write, and/or delete access and another process already has the file open but doesn't allow that level of sharing, then your call to createFile will fail. Once you have the file open, if another process tries to open it with read, write, and/or delete access and you don't allow that level of sharing, then that process won't be allowed to open the file.

$rvhvOptions is a reference to a hash where any keys must be from the list qw( Access Create Share Attributes Flags Security Model ). The meaning of the value depends on the key name, as described below. Any option values in $rvhvOptions override the settings from $svAccess and $svShare if they conflict.

Flags => $uFlags

$uFlags is an unsigned value having any of the FILE_FLAG_* or FILE_ATTRIBUTE_* bits set. Any FILE_ATTRIBUTE_* bits set via the Attributes option are logically ored with these bits. Defaults to 0.

If opening the client side of a named pipe, then you can also specify SECURITY_SQOS_PRESENT along with one of the other SECURITY_* constants to specify the security quality of service to be used.

Attributes => $sAttributes

A string of zero or more characters from "achorst" [see attrLetsToBits for more information] which are converted to FILE_ATTRIBUTE_* bits to be set in the $uFlags argument passed to CreateFile.

Security => $pSecurityAttributes

$pSecurityAttributes should contain a SECURITY_ATTRIBUTES structure packed into a string or [] [the default].

Model => $hModelFile

$hModelFile should contain a handle opened with GENERIC_READ access to a model file from which file attributes and extended attributes are to be copied. Or $hModelFile can be 0 [the default].

Access => $sAccess
Access => $uAccess

$sAccess should be a string of zero or more characters from "qrw" specifying the type of access desired: "query" or 0, "read" or GENERIC_READ [the default], or "write" or GENERIC_WRITE.

$uAccess should be an unsigned value containing bits set to indicate the type of access desired. GENERIC_READ is the default.

Create => $sCreate
Create => $uCreate

$sCreate should be a string constaing zero or one character from "ktn" and zero or one character from "ce". These stand for "Keep if exists", "Truncate if exists", "New file only", "Create if none", and "Existing file only". These are translated into a $uCreate value.

$uCreate should be one of OPEN_ALWAYS, OPEN_EXISTING, TRUNCATE_EXISTING, CREATE_ALWAYS, or CREATE_NEW.

Share => $sShare
Share => $uShare

$sShare should be a string with zero or more characters from "rwd" that is translated into a $uShare value. "rw" is the default.

$uShare should be an unsigned value having zero or more of the following bits set: FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE. FILE_SHARE_READ|FILE_SHARE_WRITE is the default.

Examples:

    $hFlop= createFile( "//./A:", "r", "r" )
      or  die "Can't prevent others from writing to floppy: $^E\n";
    $hDisk= createFile( "//./C:", "rw ke", "" )
      or  die "Can't get exclusive access to C: $^E\n";
    $hDisk= createFile( $sFilePath, "ke",
      { Access=>FILE_READ_ATTRIBUTES } )
      or  die "Can't read attributes of $sFilePath: $^E\n";
    $hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "",
      { Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } )
      or  die "Can't create temporary file, temp.$$: $^E\n";
getLogicalDrives
@roots= getLogicalDrives()

Returns the paths to the root directories of all logical drives currently defined. This includes all types of drive lettters, such as floppies, CD-ROMs, hard disks, and network shares. A typical return value on a poorly equipped computer would be ("A:\\","C:\\").

CloseHandle
CloseHandle( $hObject )

Closes a Win32 native handle, such as one opened via CreateFile. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

CopyFile
CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )

$sOldFileName is the path to the file to be copied. $sNewFileName is the path to where the file should be copied. Note that you can NOT just specify a path to a directory in $sNewFileName to copy the file to that directory using the same file name.

If $bFailIfExists is true and $sNewFileName is the path to a file that already exists, then CopyFile will fail. If $bFailIfExists is falsea, then the copy of the $sOldFileNmae file will overwrite the $sNewFileName file if it already exists.

Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

CreateFile
$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )

On failure, $hObject gets set to a false value and $^E and fileLastError() are set to the reason for the failure. Otherwise, $hObject gets set to a Win32 native file handle which is always a true value [returns "0 but true" in the impossible(?) case of the handle having a value of 0].

$sPath is the path to the file [or device, etc.] to be opened.

$sPath can use "/" or "\\" as path delimiters and can even mix the two. We will usually only use "/" in our examples since using "\\" is usually harder to read.

Under Windows NT, $sPath can start with "//?/" to allow the use of paths longer than MAX_PATH [for UNC paths, replace the leading "//" with "//?/UNC/", as in "//?/UNC/Server/Share/Dir/File.Ext"].

$sPath can start with "//./" to indicate that the rest of the path is the name of a "DOS device." You can use QueryDosDevice to list all current DOS devices and can add or delete them with DefineDosDevice. If you get the source-code distribution of this module from CPAN, then it includes an example script, ex/ListDevs.plx that will list all current DOS devices and their "native" definition. Again, note that this doesn't work under Win95 nor Win98.

The most common such DOS devices include:

"//./PhysicalDrive0"

Your entire first hard disk. Doesn't work under Windows 95. This allows you to read or write raw sectors of your hard disk and to use DeviceIoControl to perform miscellaneous queries and operations to the hard disk. Writing raw sectors and certain other operations can seriously damage your files or the function of your computer.

Locking this for exclusive access [by specifying 0 for $uShare] doesn't prevent access to the partitions on the disk nor their file systems. So other processes can still access any raw sectors within a partition and can use the file system on the disk as usual.

"//./C:"

Your C: partition. Doesn't work under Windows 95. This allows you to read or write raw sectors of that partition and to use DeviceIoControl to perform miscellaneous queries and operations to the partition. Writing raw sectors and certain other operations can seriously damage your files or the function of your computer.

Locking this for exclusive access doesn't prevent access to the physical drive that the partition is on so other processes can still access the raw sectors that way. Locking this for exclusive access does prevent other processes from opening the same raw partition and does prevent access to the file system on it. It even prevents the current process from accessing the file system on that partition.

"//./A:"

The raw floppy disk. Doesn't work under Windows 95. This allows you to read or write raw sectors of the floppy disk and to use DeviceIoControl to perform miscellaneous queries and operations to the floopy disk or drive.

Locking this for exclusive access prevents all access to the floppy.

"//./PIPE/PipeName"

A named pipe, created via CreateNamedPipe.

$uAccess is an unsigned value with bits set indicating the type of access desired. Usually either 0 ["query" access], GENERIC_READ, GENERIC_WRITE, GENERIC_READ|GENERIC_WRITE, or GENERIC_ALL. More specific types of access can be specified, such as FILE_APPEND_DATA or FILE_READ_EA.

$uShare controls how the file is shared, that is, whether other processes can have read, write, and/or delete access to the file while we have it opened. $uShare is an unsigned value with zero or more of these bits set: FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE.

If another process currently has read, write, and/or delete access to the file and you don't allow that level of sharing, then your call to CreateFile will fail. If you requested read, write, and/or delete access and another process already has the file open but doesn't allow that level of sharing, thenn your call to createFile will fail. Once you have the file open, if another process tries to open it with read, write, and/or delete access and you don't allow that level of sharing, then that process won't be allowed to open the file.

$pSecAttr should either be [] [for NULL] or a SECURITY_ATTRIBUTES data structure packed into a string. For example, if $pSecDesc contains a SECURITY_DESCRIPTOR structure packed into a string, perhaps via:

    RegGetKeySecurity( $key, 4, $pSecDesc, 1024 );

then you can set $pSecAttr via:

    $pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle );

$uCreate is one of the following values: OPEN_ALWAYS, OPEN_EXISTING, TRUNCATE_EXISTING, CREATE_ALWAYS, and CREATE_NEW.

$uFlags is an unsigned value with zero or more bits set indicating attributes to associate with the file [FILE_ATTRIBUTE_* values] or special options [FILE_FLAG_* values].

If opening the client side of a named pipe, then you can also set $uFlags to include SECURITY_SQOS_PRESENT along with one of the other SECURITY_* constants to specify the security quality of service to be used.

$hModel is 0 [or [], both of which mean NULL] or a Win32 native handle opened with GENERIC_READ access to a model file from which file attributes and extended attributes are to be copied if a new file gets created.

Examples:

    $hFlop= CreateFile( "//./A:", GENERIC_READ(),
      FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] )
      or  die "Can't prevent others from writing to floppy: $^E\n";
    $hDisk= createFile( $sFilePath, FILE_READ_ATTRIBUTES(),
      FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] )
      or  die "Can't read attributes of $sFilePath: $^E\n";
    $hTemp= createFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0,
      CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] )
      or  die "Can't create temporary file, temp.$$: $^E\n";
DefineDosDevice
DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )

Defines a new DOS device, overrides the current definition of a DOS device, or deletes a definition of a DOS device. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

$sDosDeviceName is the name of a DOS device for which we'd like to add or delete a definition.

$uFlags is an unsigned value with zero or more of the following bits set:

DDD_RAW_TARGET_PATH

Indicates that $sTargetPath will be a raw Windows NT object name. This usually means that $sTargetPath starts with "\\Device\\". Note that you cannot use "/" in place of "\\" in raw target path names.

DDD_REMOVE_DEFINITION

Requests that a definition be deleted. If $sTargetPath is [] [for NULL], then the most recently added definition for $sDosDeviceName is removed. Otherwise the most recently added definition matching $sTargetPath is removed.

If the last definition is removed, then the DOS device name is also deleted.

DDD_EXACT_MATCH_ON_REMOVE

When deleting a definition, this bit causes each $sTargetPath to be compared to the full-length definition when searching for the most recently added match. If this bit is not set, then $sTargetPath only needs to match a prefix of the definition.

$sTargetPath is the DOS device's specific definition that you wish to add or delete. For DDD_RAW_TARGET_PATH, these usually start with "\\Device\\". If the DDD_RAW_TARGET_PATH bit is not set, then $sTargetPath is just an ordinary path to some file or directory, providing the functionality of the subst command.

DeleteFile
DeleteFile( $sFileName )

Deletes the named file. Compared to Perl's unlink, DeleteFile has the advantage of not deleting read-only files. For some versions of Perl, unlink silently calls chmod whether it needs to or not before deleting the file so that files that you have protected by marking them as read-only are not always protected from Perl's unlink.

Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

DeviceIoControl
DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )

Requests a special operation on an I/O [input/output] device, such as ejecting a tape or formatting a disk. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

$hDevice is a Win32 native file handle to a device [return value from CreateFile].

$uIoControlCode is an unsigned value [a IOCTL_* or FSCTL_* constant] indicating the type query or other operation to be performed.

$pInBuf is [] [for NULL] or a data structure packed into a string. The type of data structure depends on the $uIoControlCode value. $lInBuf is 0 or the length of the structure in $pInBuf. If $pInBuf is not [] and $lInBuf is 0, then $lInBuf will automatically be set to length($pInBuf) for you.

$opOutBuf is [] [for NULL] or will be set to contain a returned data structure packed into a string. $lOutBuf indicates how much space to allocate in $opOutBuf for DeviceIoControl to store the data structure. If $lOutBuf is a number and $opOutBuf already has a buffer allocated for it that is larger than $lOutBuf bytes, then this larger buffer size will be passed to DeviceIoControl. However, you can force a specific buffer size to be passed to DeviceIoControl by prepending a "=" to the front of $lOutBuf.

$olRetBytes is [] or is a scalar to receive the number of bytes written to $opOutBuf. Even when $olRetBytes is [], a valid pointer to a DWORD [and not NULL] is passed to DeviceIoControl. In this case, [] just means that you don't care about the value that might be written to $olRetBytes, which is usually the case since you can usually use length($opOutBuf) instead.

$pOverlapped is [] or is a OVERLAPPED structure packed into a string. This is only useful if $hDevice was opened with the FILE_FLAG_OVERLAPPED flag set.

FdGetOsFHandle
$hNativeHandle= FdGetOsFHandle( $ivFd )

FdGetOsFHandle simply calls _get_osfhandle(). It was renamed to better fit in with the rest the function names of this module, in particular to distinguish it from GetOsFHandle. It takes an integer file descriptor [as from Perl's fileno] and returns the Win32 native file handle associated with that file descriptor or INVALID_HANDLE_VALUE if $ivFd is not an open file descriptor.

When you call Perl's open to set a Perl file handle [like STDOUT], Perl calls C's fopen to set a stdio FILE *. C's fopen calls something like Unix's open, that is, Win32's _sopen, to get an integer file descriptor [where 0 is for STDIN, 1 for STDOUT, etc.]. Win32's _sopen calls CreateFile to set a HANDLE, a Win32 native file handle. So every Perl file handle [like STDOUT] has an integer file descriptor associated with it that you can get via fileno. And, under Win32, every file descriptor has a Win32 native file handle associated with it. FdGetOsFHandle lets you get access to that.

$hNativeHandle is set to INVALID_HANDLE_VALUE [and lastFileError() and $^E are set] if FdGetOsFHandle fails. See also GetOsFHandle which provides a friendlier interface.

fileConstant
$value= fileConstant( $sConstantName )

Fetch the value of a constant. Returns undef if $sConstantName is not the name of a constant supported by this module. Never sets $! nor $^E.

This function is rarely used since you will usually get the value of a constant by having that constant imported into your package by listing the constant name in the use Win32API::File statement and then simply using the constant name in your code [perhaps followed by ()]. This function is useful for verifying constant names not in Perl code, for example, after prompting a user to type in a constant name.

fileLastError
$svError= fileLastError();
fileLastError( $uError );

Returns the last error encountered by a routine from this module. It is just like $^E except it isn't changed by anything except routines from this module. Ideally you could just use $^E, but current versions of Perl often overwrite $^E before you get a chance to check it and really old versions of Perl don't really support $^E under Win32.

Just like $^E, in a numeric context fileLastError() returns the numeric error value while in a string context it returns a text description of the error [actually it returns a Perl scalar that contains both values so $x= fileLastError() causes $x to give different values in string vs. numeric contexts].

The last form sets the error returned by future calls to fileLastError() and should not be used often. $uError must be a numeric error code. Also returns the dual-valued version of $uError.

GetDriveType
$uDriveType= GetDriveType( $sRootPath )

Takes a string giving the path to the root directory of a file system [called a "drive" because every file system is assigned a "drive letter"] and returns an unsigned value indicating the type of drive the file system is on. The return value should be one of:

DRIVE_UNKNOWN

None of the following.

DRIVE_NO_ROOT_DIR

A "drive" that does not have a file system. This can be a drive letter that hasn't been defined or a drive letter assigned to a partition that hasn't been formatted yet.

DRIVE_REMOVABLE

A floppy diskette drive or other removable media drive, but not a CD-ROM drive.

DRIVE_FIXED

An ordinary hard disk partition.

DRIVE_REMOTE

A network share.

DRIVE_CDROM

A CD-ROM drive.

DRIVE_RAMDISK

A "ram disk" or memory-resident virtual file system used for high-speed access to small amounts of temporary file space.

GetFileAttributes
$uAttrs = GetFileAttributes( $sPath )

Takes a path string and returns an unsigned value with attribute flags. If it fails, it returns INVALID_FILE_ATTRIBUTES, otherwise it can be one or more of the following values:

FILE_ATTRIBUTE_ARCHIVE

The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.

FILE_ATTRIBUTE_COMPRESSED

The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.

FILE_ATTRIBUTE_DEVICE

Reserved; do not use.

FILE_ATTRIBUTE_DIRECTORY

The handle identifies a directory.

FILE_ATTRIBUTE_ENCRYPTED

The file or directory is encrypted. For a file, this means that all data streams in the file are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.

FILE_ATTRIBUTE_HIDDEN

The file or directory is hidden. It is not included in an ordinary directory listing.

FILE_ATTRIBUTE_NORMAL

The file or directory has no other attributes set. This attribute is valid only if used alone.

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED

The file will not be indexed by the content indexing service.

FILE_ATTRIBUTE_OFFLINE

The data of the file is not immediately available. This attribute indicates that the file data has been physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.

FILE_ATTRIBUTE_READONLY

The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.

FILE_ATTRIBUTE_REPARSE_POINT

The file or directory has an associated reparse point.

FILE_ATTRIBUTE_SPARSE_FILE

The file is a sparse file.

FILE_ATTRIBUTE_SYSTEM

The file or directory is part of, or is used exclusively by, the operating system.

FILE_ATTRIBUTE_TEMPORARY

The file is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because often the application deletes the temporary file shortly after the handle is closed. In that case, the system can entirely avoid writing the data. Otherwise, the data will be written after the handle is closed.

GetFileType
$uFileType= GetFileType( $hFile )

Takes a Win32 native file handle and returns a FILE_TYPE_* constant indicating the type of the file opened on that handle:

FILE_TYPE_UNKNOWN

None of the below. Often a special device.

FILE_TYPE_DISK

An ordinary disk file.

FILE_TYPE_CHAR

What Unix would call a "character special file", that is, a device that works on character streams such as a printer port or a console.

FILE_TYPE_PIPE

Either a named or anonymous pipe.

getFileSize
$size= getFileSize( $hFile )

This is a Perl-friendly wrapper for the GetFileSize (below) API call.

It takes a Win32 native file handle and returns the size in bytes. Since the size can be a 64 bit value, on non 64 bit integer Perls the value returned will be an object of type Math::BigInt.

GetFileSize
$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)

Returns the size of a file pointed to by $win32Handle, optionally storing the high order 32 bits into $iSizeHigh if it is not []. If $iSizeHigh is [], a non-zero value indicates success. Otherwise, on failure the return value will be 0xffffffff and fileLastError() will not be NO_ERROR.

GetOverlappedResult
$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped, $numBytesTransferred, $bWait )

Used for asynchronous IO in Win32 to get the result of a pending IO operation, such as when a file operation returns ERROR_IO_PENDING. Returns a false value on failure. The $overlapped structure and $numBytesTransferred will be modified with the results of the operation.

As far as creating the $pOverlapped structure, you are currently on your own.

See http://msdn.microsoft.com/library/default.asp for more information.

GetLogicalDrives
$uDriveBits= GetLogicalDrives()

Returns an unsigned value with one bit set for each drive letter currently defined. If "A:" is currently a valid drive letter, then the 1 bit will be set in $uDriveBits. If "B:" is valid, then the 2 bit will be set. If "Z:" is valid, then the 2**26 [0x4000000] bit will be set.

GetLogicalDriveStrings
$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )

For each currently defined drive letter, a '\0'-terminated string of the path to the root of its file system is constructed. All of these strings are concatenated into a single larger string and an extra terminating '\0' is added. This larger string is returned in $osBuffer. Note that this includes drive letters that have been defined but that have no file system, such as drive letters assigned to unformatted partitions.

$lBufSize is the size of the buffer to allocate to store this list of strings. 26*4+1 is always sufficient and should usually be used.

$osBuffer is a scalar to be set to contain the constructed string.

$olOutLength is the number of bytes actually written to $osBuffer but length($osBuffer) can also be used to determine this.

For example, on a poorly equipped computer,

    GetLogicalDriveStrings( 4*26+1, $osBuffer );

might set $osBuffer to the 9-character string, "A:\\\0C:\\\0\0".

GetHandleInformation
GetHandleInformation( $hObject, $ouFlags )

Retrieves the flags associated with a Win32 native file handle or object handle.

$hObject is an open Win32 native file handle or an open Win32 native handle to some other type of object.

$ouFlags will be set to an unsigned value having zero or more of the bits HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE set. See the ":HANDLE_FLAG_" export class for the meanings of these bits.

GetOsFHandle
$hNativeHandle= GetOsFHandle( FILE )

Takes a Perl file handle [like STDIN] and returns the Win32 native file handle associated with it. See FdGetOsFHandle for more information about Win32 native file handles.

$hNativeHandle is set to a false value [and lastFileError() and $^E are set] if GetOsFHandle fails. GetOsFHandle returns "0 but true" in the impossible(?) case of the handle having a value of 0.

GetVolumeInformation
GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )

Gets information about a file system volume, returning a true value if successful. On failure, returns a false value and sets fileLastError() and $^E.

$sRootPath is a string specifying the path to the root of the file system, for example, "C:/".

$osVolName is a scalar to be set to the string representing the volume name, also called the file system label. $lVolName is the number of bytes to allocate for the $osVolName buffer [see Buffer Sizes for more information].

$ouSerialNum is [] [for NULL] or will be set to the numeric value of the volume's serial number.

$ouMaxNameLen is [] [for NULL] or will be set to the maximum length allowed for a file name or directory name within the file system.

$osFsType is a scalar to be set to the string representing the file system type, such as "FAT" or "NTFS". $lFsType is the number of bytes to allocate for the $osFsType buffer [see Buffer Sizes for more information].

$ouFsFlags is [] [for NULL] or will be set to an unsigned integer with bits set indicating properties of the file system:

FS_CASE_IS_PRESERVED

The file system preserves the case of file names [usually true]. That is, it doesn't change the case of file names such as forcing them to upper- or lower-case.

FS_CASE_SENSITIVE

The file system supports the ability to not ignore the case of file names [but might ignore case the way you are using it]. That is, the file system has the ability to force you to get the letter case of a file's name exactly right to be able to open it. This is true for "NTFS" file systems, even though case in file names is usually still ignored.

FS_UNICODE_STORED_ON_DISK

The file system preserves Unicode in file names [true for "NTFS"].

FS_PERSISTENT_ACLS

The file system supports setting Access Control Lists on files [true for "NTFS"].

FS_FILE_COMPRESSION

The file system supports compression on a per-file basis [true for "NTFS"].

FS_VOL_IS_COMPRESSED

The entire file system is compressed such as via "DoubleSpace".

IsRecognizedPartition
IsRecognizedPartition( $ivPartitionType )

Takes a partition type and returns whether that partition type is supported under Win32. $ivPartitonType is an integer value as from the operating system byte of a hard disk's DOS-compatible partition table [that is, a partition table for x86-based Win32, not, for example, one used with Windows NT for Alpha processors]. For example, the PartitionType member of the PARTITION_INFORMATION structure.

Common values for $ivPartitionType include PARTITION_FAT_12==1, PARTITION_FAT_16==4, PARTITION_EXTENDED==5, PARTITION_FAT32==0xB.

IsContainerPartition
IsContainerPartition( $ivPartitionType )

Takes a partition type and returns whether that partition is a "container" partition that is supported under Win32, that is, whether it is an "extended" partition that can contain "logical" partitions. $ivPartitonType is as for IsRecognizedPartition.

MoveFile
MoveFile( $sOldName, $sNewName )

Renames a file or directory. $sOldName is the name of the existing file or directory that is to be renamed. $sNewName is the new name to give the file or directory. Returns a true value if the move succeeds. For failure, returns a false value and sets fileLastErorr() and $^E to the reason for the failure.

Files can be "renamed" between file systems and the file contents and some attributes will be moved. Directories can only be renamed within one file system. If there is already a file or directory named $sNewName, then MoveFile will fail.

MoveFileEx
MoveFileEx( $sOldName, $sNewName, $uFlags )

Renames a file or directory. $sOldName is the name of the existing file or directory that is to be renamed. $sNewName is the new name to give the file or directory. Returns a true value if the move succeeds. For failure, returns a false value and sets fileLastErorr() and $^E to the reason for the failure.

$uFlags is an unsigned value with zero or more of the following bits set:

MOVEFILE_REPLACE_EXISTING

If this bit is set and a file [but not a directory] named $sNewName already exists, then it will be replaced by $sOldName. If this bit is not set then MoveFileEx will fail rather than replace an existing $sNewName.

MOVEFILE_COPY_ALLOWED

Allows files [but not directories] to be moved between file systems by copying the $sOldName file data and some attributes to $sNewName and then deleting $sOldName. If this bit is not set [or if $sOldName denotes a directory] and $sNewName refers to a different file system than $sOldName, then MoveFileEx will fail.

MOVEFILE_DELAY_UNTIL_REBOOT

Preliminary verifications are made and then an entry is added to the Registry to cause the rename [or delete] operation to be done the next time this copy of the operating system is booted [right after any automatic file system checks have completed]. This is not supported under Windows 95.

When this bit is set, $sNewName can be [] [for NULL] to indicate that $sOldName should be deleted during the next boot rather than renamed.

Setting both the MOVEFILE_COPY_ALLOWED and MOVEFILE_DELAY_UNTIL_REBOOT bits will cause MoveFileEx to fail.

MOVEFILE_WRITE_THROUGH

Ensures that MoveFileEx won't return until the operation has finished and been flushed to disk. This is not supported under Windows 95. Only affects file renames to another file system, forcing a buffer flush at the end of the copy operation.

OsFHandleOpen
OsFHandleOpen( FILE, $hNativeHandle, $sMode )

Opens a Perl file handle based on an already open Win32 native file handle [much like C's fdopen() does with a file descriptor]. Returns a true value if the open operation succeeded. For failure, returns a false value and sets $! [and possibly fileLastError() and $^E] to the reason for the failure.

FILE is a Perl file handle [in any of the supported forms, a bareword, a string, a typeglob, or a reference to a typeglob] that will be opened. If FILE is already open, it will automatically be closed before it is reopened.

$hNativeHandle is an open Win32 native file handle, probably the return value from CreateFile or createFile.

$sMode is string of zero or more letters from "rwatb". These are translated into a combination O_RDONLY ["r"], O_WRONLY ["w"], O_RDWR ["rw"], O_APPEND ["a"], O_TEXT ["t"], and O_BINARY ["b"] flags [see the the Fcntl manpage module] that is passed to OsFHandleOpenFd. Currently only O_APPEND and O_TEXT have any significance.

Also, a "r" and/or "w" in $sMode is used to decide how the file descriptor is converted into a Perl file handle, even though this doesn't appear to make a difference. One of the following is used:

    open( FILE, "<&=".$ivFd )   # "r" w/o "w"
    open( FILE, ">&=".$ivFd )   # "w" w/o "r"
    open( FILE, "+<&=".$ivFd )  # both "r" and "w"

OsFHandleOpen eventually calls the Win32-specific C routine _open_osfhandle() or Perl's "improved" version called win32_open_osfhandle(). Prior to Perl5.005, C's _open_osfhandle() is called which will fail if GetFileType($hNativeHandle) would return FILE_TYPE_UNKNOWN. For Perl5.005 and later, OsFHandleOpen calls win32_open_osfhandle() from the Perl DLL which doesn't have this restriction.

OsFHandleOpenFd
$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )

Opens a file descriptor [$ivFD] based on an already open Win32 native file handle, $hNativeHandle. This just calls the Win32-specific C routine _open_osfhandle() or Perl's "improved" version called win32_open_osfhandle(). Prior to Perl5.005 and in Cygwin Perl, C's _open_osfhandle() is called which will fail if GetFileType($hNativeHandle) would return FILE_TYPE_UNKNOWN. For Perl5.005 and later, OsFHandleOpenFd calls win32_open_osfhandle() from the Perl DLL which doesn't have this restriction.

$uMode the logical combination of zero or more O_* constants exported by the Fcntl module. Currently only O_APPEND and O_TEXT have any significance.

$ivFD will be non-negative if the open operation was successful. For failure, -1 is returned and $! [and possibly fileLastError() and $^E] is set to the reason for the failure.

QueryDosDevice
$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )

Looks up the definition of a given "DOS" device name, yielding the active Windows NT native device name along with any currently dormant definitions.

$sDosDeviceName is the name of the "DOS" device whose definitions we want. For example, "C:", "COM1", or "PhysicalDrive0". If $sDosDeviceName is [] [for NULL], the list of all DOS device names is returned instead.

$osTargetPath will be assigned a string containing the list of definitions. The definitions are each '\0'-terminate and are concatenated into the string, most recent first, with an extra '\0' at the end of the whole string [see GetLogicalDriveStrings for a sample of this format].

$lTargetBuf is the size [in bytes] of the buffer to allocate for $osTargetPath. See Buffer Sizes for more information.

$olTargetLen is set to the number of bytes written to $osTargetPath but you can also use length($osTargetPath) to determine this.

For failure, 0 is returned and fileLastError() and $^E are set to the reason for the failure.

ReadFile
ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )

Reads bytes from a file or file-like device. Returns a true value if the read operation was successful. For failure, returns a false value and sets fileLastError() and $^E for the reason for the failure.

$hFile is a Win32 native file handle that is already open to the file or device to read from.

$opBuffer will be set to a string containing the bytes read.

$lBytes is the number of bytes you would like to read. $opBuffer is automatically initialized to have a buffer large enough to hold that many bytes. Unlike other buffer sizes, $lBytes does not need to have a "=" prepended to it to prevent a larger value to be passed to the underlying Win32 ReadFile API. However, a leading "=" will be silently ignored, even if Perl warnings are enabled.

If $olBytesRead is not [], it will be set to the actual number of bytes read, though length($opBuffer) can also be used to determine this.

$pOverlapped is [] or is a OVERLAPPED structure packed into a string. This is only useful if $hFile was opened with the FILE_FLAG_OVERLAPPED flag set.

SetErrorMode
$uOldMode= SetErrorMode( $uNewMode )

Sets the mode controlling system error handling and returns the previous mode value. Both $uOldMode and $uNewMode will have zero or more of the following bits set:

SEM_FAILCRITICALERRORS

If set, indicates that when a critical error is encountered, the call that triggered the error fails immediately. Normally this bit is not set, which means that a critical error causes a dialogue box to appear notifying the desktop user that some application has triggered a critical error. The dialogue box allows the desktop user to decide whether the critical error is returned to the process, is ignored, or the offending operation is retried.

This affects the CreateFile and GetVolumeInformation calls.

Setting this bit is useful for allowing you to check whether a floppy diskette is in the floppy drive.

SEM_NOALIGNMENTFAULTEXCEPT

If set, this causes memory access misalignment faults to be automatically fixed in a manner invisible to the process. This flag is ignored on x86-based versions of Windows NT. This flag is not supported on Windows 95.

SEM_NOGPFAULTERRORBOX

If set, general protection faults do not generate a dialogue box but can instead be handled by the process via an exception handler. This bit should not be set by programs that don't know how to handle such faults.

SEM_NOOPENFILEERRORBOX

If set, then when an attempt to continue reading from or writing to an already open file [usually on a removable medium like a floppy diskette] finds the file no longer available, the call will immediately fail. Normally this bit is not set, which means that instead a dialogue box will appear notifying the desktop user that some application has run into this problem. The dialogue box allows the desktop user to decide whether the failure is returned to the process, is ignored, or the offending operation is retried.

This affects the ReadFile and WriteFile calls.

setFilePointer
$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )

This is a perl-friendly wrapper for the SetFilePointer API (below). $ivOffset can be a 64 bit integer or Math::BigInt object if your Perl doesn't have 64 bit integers. The return value is the new offset and will likewise be a 64 bit integer or a Math::BigInt object.

SetFilePointer
$uNewPos = SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh, $uFromWhere )

The native Win32 version of seek(). SetFilePointer sets the position within a file where the next read or write operation will start from.

$hFile is a Win32 native file handle.

$uFromWhere is either FILE_BEGIN, FILE_CURRENT, or FILE_END, indicating that the new file position is being specified relative to the beginning of the file, the current file pointer, or the end of the file, respectively.

$ivOffset is [if $ioivOffsetHigh is []] the offset [in bytes] to the new file position from the position specified via $uFromWhere. If $ioivOffsetHigh is not [], then $ivOffset is converted to an unsigned value to be used as the low-order 4 bytes of the offset.

$ioivOffsetHigh can be [] [for NULL] to indicate that you are only specifying a 4-byte offset and the resulting file position will be 0xFFFFFFFE or less [just under 4GB]. Otherwise $ioivOfffsetHigh starts out with the high-order 4 bytes [signed] of the offset and gets set to the [unsigned] high-order 4 bytes of the resulting file position.

The underlying SetFilePointer returns 0xFFFFFFFF to indicate failure, but if $ioivOffsetHigh is not [], you would also have to check $^E to determine whether 0xFFFFFFFF indicates an error or not. Win32API::File::SetFilePointer does this checking for you and returns a false value if and only if the underlying SetFilePointer failed. For this reason, $uNewPos is set to "0 but true" if you set the file pointer to the beginning of the file [or any position with 0 for the low-order 4 bytes].

So the return value will be true if the seek operation was successful. For failure, a false value is returned and fileLastError() and $^E are set to the reason for the failure.

SetHandleInformation
SetHandleInformation( $hObject, $uMask, $uFlags )

Sets the flags associated with a Win32 native file handle or object handle. Returns a true value if the operation was successful. For failure, returns a false value and sets fileLastError() and $^E for the reason for the failure.

$hObject is an open Win32 native file handle or an open Win32 native handle to some other type of object.

$uMask is an unsigned value having one or more of the bits HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE set. Only bits set in $uMask will be modified by SetHandleInformation.

$uFlags is an unsigned value having zero or more of the bits HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE set. For each bit set in $uMask, the cooresponding bit in the handle's flags is set to the value of the cooresponding bit in $uFlags.

If $uOldFlags were the value of the handle's flags before the call to SetHandleInformation, then the value of the handle's flags afterward would be:

    ( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask )

[at least as far as the HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE bits are concerned.]

See the ":HANDLE_FLAG_" export class for the meanings of these bits.

WriteFile
WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )

Write bytes to a file or file-like device. Returns a true value if the operation was successful. For failure, returns a false value and sets fileLastError() and $^E for the reason for the failure.

$hFile is a Win32 native file handle that is already open to the file or device to be written to.

$pBuffer is a string containing the bytes to be written.

$lBytes is the number of bytes you would like to write. If $pBuffer is not at least $lBytes long, WriteFile croaks. You can specify 0 for $lBytes to write length($pBuffer) bytes. A leading "=" on $lBytes will be silently ignored, even if Perl warnings are enabled.

$ouBytesWritten will be set to the actual number of bytes written unless you specify it as [].

$pOverlapped is [] or is an OVERLAPPED structure packed into a string. This is only useful if $hFile was opened with the FILE_FLAG_OVERLAPPED flag set.

":FuncA"

The ASCII-specific functions. Each of these is just the same as the version without the trailing "A".

        CopyFileA
        CreateFileA
        DefineDosDeviceA
        DeleteFileA
        GetDriveTypeA
        GetFileAttributesA
        GetLogicalDriveStringsA
        GetVolumeInformationA
        MoveFileA
        MoveFileExA
        QueryDosDeviceA
":FuncW"

The wide-character-specific (Unicode) functions. Each of these is just the same as the version without the trailing "W" except that strings are expected in Unicode and some lengths are measured as number of WCHARs instead of number of bytes, as indicated below.

CopyFileW
CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )

$swOldFileName and $swNewFileName are Unicode strings.

CreateFileW
$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )

$swPath is Unicode.

DefineDosDeviceW
DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )

$swDosDeviceName and $swTargetPath are Unicode.

DeleteFileW
DeleteFileW( $swFileName )

$swFileName is Unicode.

GetDriveTypeW
$uDriveType= GetDriveTypeW( $swRootPath )

$swRootPath is Unicode.

GetFileAttributesW
$uAttrs= GetFileAttributesW( $swPath )

$swPath is Unicode.

GetLogicalDriveStringsW
$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )

Unicode is stored in $oswBuffer. $lwBufSize and $olwOutLength are measured as number of WCHARs.

GetVolumeInformationW
GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )

$swRootPath is Unicode and Unicode is written to $oswVolName and $oswFsType. $lwVolName and $lwFsType are measures as number of WCHARs.

MoveFileW
MoveFileW( $swOldName, $swNewName )

$swOldName and $swNewName are Unicode.

MoveFileExW
MoveFileExW( $swOldName, $swNewName, $uFlags )

$swOldName and $swNewName are Unicode.

QueryDosDeviceW
$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath, $lwTargetBuf )

$swDeviceName is Unicode and Unicode is written to $oswTargetPath. $lwTargetBuf and $olwTargetLen are measured as number of WCHARs.

":Misc"

Miscellaneous constants. Used for the $uCreate argument of CreateFile or the $uFromWhere argument of SetFilePointer. Plus INVALID_HANDLE_VALUE, which you usually won't need to check for since most routines translate it into a false value.

        CREATE_ALWAYS           CREATE_NEW              OPEN_ALWAYS
        OPEN_EXISTING           TRUNCATE_EXISTING       INVALID_HANDLE_VALUE
        FILE_BEGIN              FILE_CURRENT            FILE_END
":DDD_"

Constants for the $uFlags argument of DefineDosDevice.

        DDD_EXACT_MATCH_ON_REMOVE
        DDD_RAW_TARGET_PATH
        DDD_REMOVE_DEFINITION
":DRIVE_"

Constants returned by GetDriveType.

        DRIVE_UNKNOWN           DRIVE_NO_ROOT_DIR       DRIVE_REMOVABLE
        DRIVE_FIXED             DRIVE_REMOTE            DRIVE_CDROM
        DRIVE_RAMDISK
":FILE_"

Specific types of access to files that can be requested via the $uAccess argument to CreateFile.

        FILE_READ_DATA                  FILE_LIST_DIRECTORY
        FILE_WRITE_DATA                 FILE_ADD_FILE
        FILE_APPEND_DATA                FILE_ADD_SUBDIRECTORY
        FILE_CREATE_PIPE_INSTANCE       FILE_READ_EA
        FILE_WRITE_EA                   FILE_EXECUTE
        FILE_TRAVERSE                   FILE_DELETE_CHILD
        FILE_READ_ATTRIBUTES            FILE_WRITE_ATTRIBUTES
        FILE_ALL_ACCESS                 FILE_GENERIC_READ
        FILE_GENERIC_WRITE              FILE_GENERIC_EXECUTE )],
":FILE_ATTRIBUTE_"

File attribute constants. Returned by attrLetsToBits and used in the $uFlags argument to CreateFile.

        FILE_ATTRIBUTE_ARCHIVE                  FILE_ATTRIBUTE_COMPRESSED
        FILE_ATTRIBUTE_HIDDEN                   FILE_ATTRIBUTE_NORMAL
        FILE_ATTRIBUTE_OFFLINE                  FILE_ATTRIBUTE_READONLY
        FILE_ATTRIBUTE_SYSTEM                   FILE_ATTRIBUTE_TEMPORARY

In addition, GetFileAttributes can return these constants (or INVALID_FILE_ATTRIBUTES in case of an error).

        FILE_ATTRIBUTE_DEVICE                   FILE_ATTRIBUTE_DIRECTORY
        FILE_ATTRIBUTE_ENCRYPTED                FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
        FILE_ATTRIBUTE_REPARSE_POINT    FILE_ATTRIBUTE_SPARSE_FILE
":FILE_FLAG_"

File option flag constants. Used in the $uFlags argument to CreateFile.

        FILE_FLAG_BACKUP_SEMANTICS      FILE_FLAG_DELETE_ON_CLOSE
        FILE_FLAG_NO_BUFFERING          FILE_FLAG_OVERLAPPED
        FILE_FLAG_POSIX_SEMANTICS       FILE_FLAG_RANDOM_ACCESS
        FILE_FLAG_SEQUENTIAL_SCAN       FILE_FLAG_WRITE_THROUGH
        FILE_FLAG_OPEN_REPARSE_POINT
":FILE_SHARE_"

File sharing constants. Used in the $uShare argument to CreateFile.

        FILE_SHARE_DELETE       FILE_SHARE_READ         FILE_SHARE_WRITE
":FILE_TYPE_"

File type constants. Returned by GetFileType.

        FILE_TYPE_CHAR          FILE_TYPE_DISK
        FILE_TYPE_PIPE          FILE_TYPE_UNKNOWN
":FS_"

File system characteristics constants. Placed in the $ouFsFlags argument to GetVolumeInformation.

        FS_CASE_IS_PRESERVED            FS_CASE_SENSITIVE
        FS_UNICODE_STORED_ON_DISK       FS_PERSISTENT_ACLS
        FS_FILE_COMPRESSION             FS_VOL_IS_COMPRESSED
":HANDLE_FLAG_"

Flag bits modifying the behavior of an object handle and accessed via GetHandleInformation and SetHandleInformation.

HANDLE_FLAG_INHERIT

If this bit is set, then children of this process who inherit handles [that is, processes created by calls to the Win32 CreateProcess API with the bInheritHandles parameter specified as TRUE], will inherit this particular object handle.

HANDLE_FLAG_PROTECT_FROM_CLOSE

If this bit is set, then calls to CloseHandle against this handle will be ignored, leaving the handle open and usable.

":IOCTL_STORAGE_"

I/O control operations for generic storage devices. Used in the $uIoControlCode argument to DeviceIoControl. Includes IOCTL_STORAGE_CHECK_VERIFY, IOCTL_STORAGE_MEDIA_REMOVAL, IOCTL_STORAGE_EJECT_MEDIA, IOCTL_STORAGE_LOAD_MEDIA, IOCTL_STORAGE_RESERVE, IOCTL_STORAGE_RELEASE, IOCTL_STORAGE_FIND_NEW_DEVICES, and IOCTL_STORAGE_GET_MEDIA_TYPES.

IOCTL_STORAGE_CHECK_VERIFY

Verify that a device's media is accessible. $pInBuf and $opOutBuf should both be []. If DeviceIoControl returns a true value, then the media is currently accessible.

IOCTL_STORAGE_MEDIA_REMOVAL

Allows the device's media to be locked or unlocked. $opOutBuf should be []. $pInBuf should be a PREVENT_MEDIA_REMOVAL data structure, which is simply an interger containing a boolean value:

    $pInBuf= pack( "i", $bPreventMediaRemoval );
IOCTL_STORAGE_EJECT_MEDIA

Requests that the device eject the media. $pInBuf and $opOutBuf should both be [].

IOCTL_STORAGE_LOAD_MEDIA

Requests that the device load the media. $pInBuf and $opOutBuf should both be [].

IOCTL_STORAGE_RESERVE

Requests that the device be reserved. $pInBuf and $opOutBuf should both be [].

IOCTL_STORAGE_RELEASE

Releases a previous device reservation. $pInBuf and $opOutBuf should both be [].

IOCTL_STORAGE_FIND_NEW_DEVICES

No documentation on this IOCTL operation was found.

IOCTL_STORAGE_GET_MEDIA_TYPES

Requests information about the type of media supported by the device. $pInBuf should be []. $opOutBuf will be set to contain a vector of DISK_GEOMETRY data structures, which can be decoded via:

    # Calculate the number of DISK_GEOMETRY structures returned:
    my $cStructs= length($opOutBuf)/(4+4+4+4+4+4);
    my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf )
    my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl,
      @uSectsPerTrack, @uBytesPerSect )= ();
    while(  @fields  ) {
        push( @ucCylsLow, unshift @fields );
        push( @ivcCylsHigh, unshift @fields );
        push( @uMediaType, unshift @fields );
        push( @uTracksPerCyl, unshift @fields );
        push( @uSectsPerTrack, unshift @fields );
        push( @uBytesPerSect, unshift @fields );
    }

For the $ith type of supported media, the following variables will contain the following data.

$ucCylsLow[$i]

The low-order 4 bytes of the total number of cylinders.

$ivcCylsHigh[$i]

The high-order 4 bytes of the total number of cylinders.

$uMediaType[$i]

A code for the type of media. See the ":MEDIA_TYPE" export class.

$uTracksPerCyl[$i]

The number of tracks in each cylinder.

$uSectsPerTrack[$i]

The number of sectors in each track.

$uBytesPerSect[$i]

The number of bytes in each sector.

":IOCTL_DISK_"

I/O control operations for disk devices. Used in the $uIoControlCode argument to DeviceIoControl. Most of these are to be used on physical drive devices like "//./PhysicalDrive0". However, IOCTL_DISK_GET_PARTITION_INFO and IOCTL_DISK_SET_PARTITION_INFO should only be used on a single-partition device like "//./C:". Also, IOCTL_DISK_GET_MEDIA_TYPES is documented as having been superceded but is still useful when used on a floppy device like "//./A:".

Includes IOCTL_DISK_FORMAT_TRACKS, IOCTL_DISK_FORMAT_TRACKS_EX, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_GET_MEDIA_TYPES, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_HISTOGRAM_DATA, IOCTL_DISK_HISTOGRAM_RESET, IOCTL_DISK_HISTOGRAM_STRUCTURE, IOCTL_DISK_IS_WRITABLE, IOCTL_DISK_LOGGING, IOCTL_DISK_PERFORMANCE, IOCTL_DISK_REASSIGN_BLOCKS, IOCTL_DISK_REQUEST_DATA, IOCTL_DISK_REQUEST_STRUCTURE, IOCTL_DISK_SET_DRIVE_LAYOUT, IOCTL_DISK_SET_PARTITION_INFO, and IOCTL_DISK_VERIFY.

IOCTL_DISK_GET_DRIVE_GEOMETRY

Request information about the size and geometry of the disk. $pInBuf should be []. $opOutBuf will be set to a DISK_GEOMETRY data structure which can be decode via:

    ( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl,
      $uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf );
$ucCylsLow

The low-order 4 bytes of the total number of cylinders.

$ivcCylsHigh

The high-order 4 bytes of the total number of cylinders.

$uMediaType

A code for the type of media. See the ":MEDIA_TYPE" export class.

$uTracksPerCyl

The number of tracks in each cylinder.

$uSectsPerTrack

The number of sectors in each track.

$uBytesPerSect

The number of bytes in each sector.

IOCTL_DISK_GET_PARTITION_INFO

Request information about the size and geometry of the partition. $pInBuf should be []. $opOutBuf will be set to a PARTITION_INFORMATION data structure which can be decode via:

    ( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber,
      $uPartitionType, $bActive, $bRecognized, $bToRewrite )=
      unpack( "L l L L C c c c", $opOutBuf );
$uStartLow and $ivStartHigh

The low-order and high-order [respectively] 4 bytes of the starting offset of the partition, measured in bytes.

$ucHiddenSects

The number of "hidden" sectors for this partition. Actually this is the number of sectors found prior to this partiton, that is, the starting offset [as found in $uStartLow and $ivStartHigh] divided by the number of bytes per sector.

$uPartitionSeqNumber

The sequence number of this partition. Partitions are numbered starting as 1 [with "partition 0" meaning the entire disk]. Sometimes this field may be 0 and you'll have to infer the partition sequence number from how many partitions preceed it on the disk.

$uPartitionType

The type of partition. See the ":PARTITION_" export class for a list of known types. See also IsRecognizedPartition and IsContainerPartition.

$bActive

1 for the active [boot] partition, 0 otherwise.

$bRecognized

Whether this type of partition is support under Win32.

$bToRewrite

Whether to update this partition information. This field is not used by IOCTL_DISK_GET_PARTITION_INFO. For IOCTL_DISK_SET_DRIVE_LAYOUT, you must set this field to a true value for any partitions you wish to have changed, added, or deleted.

IOCTL_DISK_SET_PARTITION_INFO

Change the type of the partition. $opOutBuf should be []. $pInBuf should be a SET_PARTITION_INFORMATION data structure which is just a single byte containing the new parition type [see the ":PARTITION_" export class for a list of known types]:

    $pInBuf= pack( "C", $uPartitionType );
IOCTL_DISK_GET_DRIVE_LAYOUT

Request information about the disk layout. $pInBuf should be []. $opOutBuf will be set to contain DRIVE_LAYOUT_INFORMATION structure including several PARTITION_INFORMATION structures:

    my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf );
    my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ),
                        $opOutBuf );
    my( @uStartLow, @ivStartHigh, @ucHiddenSects,
      @uPartitionSeqNumber, @uPartitionType, @bActive,
      @bRecognized, @bToRewrite )= ();
    for(  1..$cPartition  ) {
        push( @uStartLow, unshift @fields );
        push( @ivStartHigh, unshift @fields );
        push( @ucHiddenSects, unshift @fields );
        push( @uPartitionSeqNumber, unshift @fields );
        push( @uPartitionType, unshift @fields );
        push( @bActive, unshift @fields );
        push( @bRecognized, unshift @fields );
        push( @bToRewrite, unshift @fields );
    }
$cPartitions

If the number of partitions on the disk.

$uDiskSignature

Is the disk signature, a unique number assigned by Disk Administrator [WinDisk.exe] and used to identify the disk. This allows drive letters for partitions on that disk to remain constant even if the SCSI Target ID of the disk gets changed.

See IOCTL_DISK_GET_PARTITION_INFORMATION for information on the remaining these fields.

IOCTL_DISK_GET_MEDIA_TYPES

Is supposed to be superseded by IOCTL_STORAGE_GET_MEDIA_TYPES but is still useful for determining the types of floppy diskette formats that can be produced by a given floppy drive. See ex/FormatFloppy.plx for an example.

IOCTL_DISK_SET_DRIVE_LAYOUT

Change the partition layout of the disk. $pOutBuf should be []. $pInBuf should be a DISK_LAYOUT_INFORMATION data structure including several PARTITION_INFORMATION data structures.

    # Already set:  $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh,
    #   @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive,
    #   @bRecognized, and @bToRewrite.
    my( @fields, $prtn )= ();
    for $prtn (  1..$cPartition  ) {
        push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1],
            $ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1],
            $uPartitionType[$prtn-1], $bActive[$prtn-1],
            $bRecognized[$prtn-1], $bToRewrite[$prtn-1] );
    }
    $pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ),
                   $cPartitions, $uDiskSignature, @fields );

To delete a partition, zero out all fields except for $bToRewrite which should be set to 1. To add a partition, increment $cPartitions and add the information for the new partition into the arrays, making sure that you insert 1 into @bToRewrite.

See IOCTL_DISK_GET_DRIVE_LAYOUT and IOCTL_DISK_GET_PARITITON_INFORMATION for descriptions of the fields.

IOCTL_DISK_VERIFY

Performs a logical format of [part of] the disk. $opOutBuf should be []. $pInBuf should contain a VERIFY_INFORMATION data structure:

    $pInBuf= pack( "L l L",
                   $uStartOffsetLow, $ivStartOffsetHigh, $uLength );
$uStartOffsetLow and $ivStartOffsetHigh

The low-order and high-order [respectively] 4 bytes of the offset [in bytes] where the formatting should begin.

$uLength

The length [in bytes] of the section to be formatted.

IOCTL_DISK_FORMAT_TRACKS

Format a range of tracks on the disk. $opOutBuf should be []. $pInBuf should contain a FORMAT_PARAMETERS data structure:

    $pInBuf= pack( "L L L L L", $uMediaType,
                   $uStartCyl, $uEndCyl, $uStartHead, $uEndHead );

$uMediaType if the type of media to be formatted. Mostly used to specify the density to use when formatting a floppy diskette. See the ":MEDIA_TYPE" export class for more information.

The remaining fields specify the starting and ending cylinder and head of the range of tracks to be formatted.

IOCTL_DISK_REASSIGN_BLOCKS

Reassign a list of disk blocks to the disk's spare-block pool. $opOutBuf should be []. $pInBuf should be a REASSIGN_BLOCKS data structure:

    $pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );
IOCTL_DISK_PERFORMANCE

Request information about disk performance. $pInBuf should be []. $opOutBuf will be set to contain a DISK_PERFORMANCE data structure:

    my( $ucBytesReadLow, $ivcBytesReadHigh,
        $ucBytesWrittenLow, $ivcBytesWrittenHigh,
        $uReadTimeLow, $ivReadTimeHigh,
        $uWriteTimeLow, $ivWriteTimeHigh,
        $ucReads, $ucWrites, $uQueueDepth )=
        unpack( "L l L l L l L l L L L", $opOutBuf );
IOCTL_DISK_IS_WRITABLE

No documentation on this IOCTL operation was found.

IOCTL_DISK_LOGGING

Control disk logging. Little documentation for this IOCTL operation was found. It makes use of a DISK_LOGGING data structure:

DISK_LOGGING_START

Start logging each disk request in a buffer internal to the disk device driver of size $uLogBufferSize:

    $pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );
DISK_LOGGING_STOP

Stop loggin each disk request:

    $pInBuf= pack( "C L L", 1, 0, 0 );
DISK_LOGGING_DUMP

Copy the interal log into the supplied buffer:

    $pLogBuffer= ' ' x $uLogBufferSize
    $pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize );

    ( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i],
      $uStartTimeLow[$i], $ivStartTimeHigh[$i],
      $uEndTimeLog[$i], $ivEndTimeHigh[$i],
      $hVirtualAddress[$i], $ucBytes[$i],
      $uDeviceNumber[$i], $bWasReading[$i] )=
      unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer );
DISK_LOGGING_BINNING

Keep statics grouped into bins based on request sizes.

    $pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );
IOCTL_DISK_FORMAT_TRACKS_EX

No documentation on this IOCTL is included.

IOCTL_DISK_HISTOGRAM_STRUCTURE

No documentation on this IOCTL is included.

IOCTL_DISK_HISTOGRAM_DATA

No documentation on this IOCTL is included.

IOCTL_DISK_HISTOGRAM_RESET

No documentation on this IOCTL is included.

IOCTL_DISK_REQUEST_STRUCTURE

No documentation on this IOCTL operation was found.

IOCTL_DISK_REQUEST_DATA

No documentation on this IOCTL operation was found.

":FSCTL_"

File system control operations. Used in the $uIoControlCode argument to DeviceIoControl.

Includes FSCTL_SET_REPARSE_POINT, FSCTL_GET_REPARSE_POINT, FSCTL_DELETE_REPARSE_POINT.

FSCTL_SET_REPARSE_POINT

Sets reparse point data to be associated with $hDevice.

FSCTL_GET_REPARSE_POINT

Retrieves the reparse point data associated with $hDevice.

FSCTL_DELETE_REPARSE_POINT

Deletes the reparse point data associated with $hDevice.

":GENERIC_"

Constants specifying generic access permissions that are not specific to one type of object.

        GENERIC_ALL                     GENERIC_EXECUTE
        GENERIC_READ            GENERIC_WRITE
":MEDIA_TYPE"

Different classes of media that a device can support. Used in the $uMediaType field of a DISK_GEOMETRY structure.

Unknown

Format is unknown.

F5_1Pt2_512

5.25" floppy, 1.2MB [really 1,200KB] total space, 512 bytes/sector.

F3_1Pt44_512

3.5" floppy, 1.44MB [really 1,440KB] total space, 512 bytes/sector.

F3_2Pt88_512

3.5" floppy, 2.88MB [really 2,880KB] total space, 512 bytes/sector.

F3_20Pt8_512

3.5" floppy, 20.8MB total space, 512 bytes/sector.

F3_720_512

3.5" floppy, 720KB total space, 512 bytes/sector.

F5_360_512

5.25" floppy, 360KB total space, 512 bytes/sector.

F5_320_512

5.25" floppy, 320KB total space, 512 bytes/sector.

F5_320_1024

5.25" floppy, 320KB total space, 1024 bytes/sector.

F5_180_512

5.25" floppy, 180KB total space, 512 bytes/sector.

F5_160_512

5.25" floppy, 160KB total space, 512 bytes/sector.

RemovableMedia

Some type of removable media other than a floppy diskette.

FixedMedia

A fixed hard disk.

F3_120M_512

3.5" floppy, 120MB total space.

":MOVEFILE_"

Constants for use in $uFlags arguments to MoveFileEx.

        MOVEFILE_COPY_ALLOWED           MOVEFILE_DELAY_UNTIL_REBOOT
        MOVEFILE_REPLACE_EXISTING       MOVEFILE_WRITE_THROUGH
":SECURITY_"

Security quality of service values that can be used in the $uFlags argument to CreateFile if opening the client side of a named pipe.

        SECURITY_ANONYMOUS              SECURITY_CONTEXT_TRACKING
        SECURITY_DELEGATION             SECURITY_EFFECTIVE_ONLY
        SECURITY_IDENTIFICATION         SECURITY_IMPERSONATION
        SECURITY_SQOS_PRESENT
":SEM_"

Constants to be used with SetErrorMode.

        SEM_FAILCRITICALERRORS          SEM_NOGPFAULTERRORBOX
        SEM_NOALIGNMENTFAULTEXCEPT      SEM_NOOPENFILEERRORBOX
":PARTITION_"

Constants describing partition types.

        PARTITION_ENTRY_UNUSED          PARTITION_FAT_12
        PARTITION_XENIX_1               PARTITION_XENIX_2
        PARTITION_FAT_16                PARTITION_EXTENDED
        PARTITION_HUGE                  PARTITION_IFS
        PARTITION_FAT32                 PARTITION_FAT32_XINT13
        PARTITION_XINT13                PARTITION_XINT13_EXTENDED
        PARTITION_PREP                  PARTITION_UNIX
        VALID_NTFT                      PARTITION_NTFT
":ALL"

All of the above.

BUGS

None known at this time.

AUTHOR

Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.

SEE ALSO

The pyramids.


Win32API::Net - Perl interface to the Windows NT LanManager API account management functions.

  • NOTE ON VERSIONS PRIOR TO 0.08
  • DESCRIPTION
    • Using References
  • DATA STRUCTURES
  • EXPORTS
  • NET USER FUNCTIONS
    • UserAdd(server, level, hash, error)
    • UserChangePassword(server, user, old, new)
    • UserDel(server, user)
    • UserEnum(server, array[, filter])
    • UserGetGroups(server, user, array)
    • UserGetInfo(server, user, level, hash)
    • UserGetLocalGroups(server, user, array[, flags])
    • UserModalsGet()
    • UserModalsSet()
    • UserSetGroups(server, user, array)
    • UserSetInfo(server, user, level, hash, error)
  • NET GROUP FUNCTIONS
    • GroupAdd(server, level, hash, error)
    • GroupAddUser(server, group, user)
    • GroupDel(server, group)
    • GroupDelUser(server, group, user)
    • GroupEnum(server, array)
    • GroupGetInfo(server, group, level, hash)
    • GroupGetUsers(server, group, array)
    • GroupSetInfo(server, group, level, hash, error)
    • GroupSetUsers(server, group, array)
  • NET LOCAL GROUP FUNCTIONS
    • LocalGroupAdd(server, level, hash, error)
    • LocalGroupAddMember()
    • LocalGroupAddMembers(server, group, array)
    • LocalGroupDel(server, group)
    • LocalGroupDelMember()
    • LocalGroupDelMembers(server, group, array)
    • LocalGroupEnum(server, array)
    • LocalGroupGetInfo(server, group, level, hash)
    • LocalGroupGetMembers(server, group, hash)
    • LocalGroupSetInfo(server, level, hash, error)
    • LocalGroupSetMembers()
  • NET GET FUNCTIONS
    • GetDCName(server, domain, domain-controller)
  • USER INFO LEVELS
  • USER INFO FIELDS
  • USER FLAGS
  • USER PRIVILEGE FLAGS
  • USER ENUM FILTER
  • USER FIELD ERRORS
  • GROUP INFO LEVELS
  • GROUP INFO FIELDS
  • GROUP FIELD ERRORS
  • GROUP USERS INFO LEVELS
  • GROUP USERS INFO FIELDS
  • LOCAL GROUP INFO LEVELS
  • LOCAL GROUP INFO FIELDS
  • LOCAL GROUP FIELD ERRORS
  • EXAMPLES
  • AUTHOR
  • SEE ALSO
  • ACKNOWEDGEMENTS

NAME

Win32API::Net - Perl interface to the Windows NT LanManager API account management functions.

SYNOPSIS

use Win32API::Net;

NOTE ON VERSIONS PRIOR TO 0.08

As of version 0.08 of this module, the behaviour relating to empty strings in input hashes has changed. The old behaviour converted such strings to the NULL pointer. The underlying API uses this value as an indication to not change the value stored for a given field. This meant that you were not able to clear (say) the logonScript field for a user using UserSetInfo().

The new behaviour is to leave the string as an empty C string which will allow fields to be cleared. To pass a NULL pointer to the underlying API call (and thus, to leave the field as it was), you need to set the corresponding field to undef.

WARNING: THIS IS AN INCOMPATIBLE CHANGE. EXISTING SCRIPTS THAT RELIED ON PRIOR BEHAVIOR MAY NEED TO BE MODIFIED.

DESCRIPTION

Win32API::Net provides a more complete wrapper for the account management parts of the NT LanManager API than do other similar packages. Most of what you can achieve with the native C++ API is possible with this package - albeit in a more Perl like manner by using references to pass information to and from functions.

For an understanding of the environment in which these functions operate see DATA STRUCTURES.

The following groups of functions are available:

NET USER FUNCTIONS
NET GROUP FUNCTIONS
NET LOCAL GROUP FUNCTIONS
NET GET FUNCTIONS

All functions return 0 on failure and 1 on success. Use the Win32::GetLastError() function to find out more information on why a function failed. In addition, some functions that take a hash reference to pass information in (e.g. UserAdd()) have a last argument that will allow more detailed information on which key/value pair was not properly specified.

Using References

References to hashes and arrays are used throughout this package to pass information into and out of functions.

Using Hash References

Where a hash reference is required you can use anything that evaluates to a hash reference. e.g.

        $href = \%someHash;
        UserAdd(server, 2, $hRef);

Or more directly:

        UserAdd(server, 2, \%someHash);
Using Array references

Array references are used in a similar manner to hash references. e.g.

        $aref = \@someArray;
        UserEnum(server, $aref);

Or more directly:

        UserEnum(server, \@someArray);

Please note: Any *Get*() or *Enum() operation will first clear the contents of the input hash or array being referenced.

See EXAMPLES and the test.pl script for examples of usage.

DATA STRUCTURES

Most the the functions in the underlying API allow the programmer to pass specify at runtime the amount of information that is supplied to the function. For example, the NetUserGetInfo() call allows the programmer to specify levels of 0, 1, 2, 3 (and others). Having specified this level, the function returns a structure that will contain different fields. For a level 0, the function returns a structure that has only one field. For a supplied level of 1, the function returns a structure with 8 fields. The programmer needs to know in advance what fields should be provided or will be returned for a given level. This mechanism works very will since it effectively overloads functions without having to use different function prototypes. Perl provides better higher level data structures in the form of arrays and hashes. This package uses hashes as the means to pass these variable size structure into and out of functions.

For any function that takes a reference to a hash as input, the programmer is expected to provide appropriate keys and corresponding values as well as the level parameter. The called function will then takes the values out of the supplied hash and build the approprite structure to pass to the underlying API function.

For any function that takes a reference to a hash to recieve output, the function will first clear any keys an corresponding values in the supplied hash. It will call the underlying API call and will then return in the hash any keys and values that are applicable at the requested level.

Example:

The UserGetInfo() can takes a number of levels. If called with level 0 the supplied hash will, on return from the function, contain a single key and value - namely name/requested-users-name. If called with a level of 1 the supplied hash will, on return from the function, contain 8 keys and values. The returned keys are name, password, passwordAge, priv, homeDir, comment, flags, scriptPath. See USER INFO FIELDS for more information on what these represent.

EXPORTS

By default, Win32API::Net exports no symbols into the callers namespace. The following tags can be used to selectively import symbols into the main namespace.

:User

Exports all symbols needed for the User*() functions. See NET USER FUNCTIONS.

:Get

Exports all symbols needed for the Get*() functions. See NET GET FUNCTIONS.

:Group

Exports all symbols needed for the Group*() functions. See NET GROUP FUNCTIONS.

:LocalGroup

Exports all symbols needed for the LocalGroup*() functions. See NET LOCAL GROUP FUNCTIONS.

NET USER FUNCTIONS

The User*() functions operate on NT user accounts.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled. Administrator privileges are required to add an Administrator Privilege account. There are some exceptions to this whereby a user can change some of their own settings where these don't conflict with 'administrative information' (e.g. full name).

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function GetDCName() to find out what the domain controller is, should you not be running this on the PDC.

All functions in this section are 'DOMAIN functions'. This means that, for example, the UserGetLocalGroups() function actually lists the domain's local groups of which the named user is a member.

The following functions are available.

UserAdd(server, level, hash, error)

Add a new user account. The user name is taken from the name-key's value in the supplied hash.

server - Scalar String

The server on which to add the account.

level - Scalar Int

Level of information provided in hash. This can be either 1, 2 or 3. See USER INFO LEVELS.

hash - Hash Reference

The information to use to add this account. This should have all the appropriate keys and values required for level.

error - Scalar Int

Provides information on which field in the hash was not properly specified. See USER FIELD ERRORS for more information about what values this can take.

UserChangePassword(server, user, old, new)

Changes the password for user. If the policy of the machine/domain only allows password changes if the user is logged on then the user must be logged on to execute this function. With Administrator or Account Operator privilege you can use this function to change anyone's password, so long as you know the old password.

server - Scalar String

The server on which to change the password.

user - Scalar String

The name of the user whose password is being changed.

old - Scalar String

The existing password for user.

new - Scalar String

The new password for user.

UserDel(server, user)

Deletes the specified user account. Administrator or Account Operator privilege is required to execute this function.

server - Scalar String

The server on which to delete the user.

user - Scalar String

The user account to delete.

UserEnum(server, array[, filter])

Enumerates all the accounts on server that satisfy filter. Unlike the NetUserEnum() function in the API, this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it) - see Example 1.

server - Scalar String

The server on which to enumerate the accounts satisfying filter.

array - Array Reference

The array that will hold the names of all users on server whose accounts match filter.

filter - Scalar Int (optional)

The filter to apply (see USER ENUM FILTER). This argument is optional and if not present a default of FILTER_NORMAL_ACCOUNT is used.

UserGetGroups(server, user, array)

Get the global groups for which user is a member. It returns the group names in array. Unlike the NetUserGetGroups() function in the API, this function does not allow you to specify a level (internally is hardcoded to 0). In Perl it is trivial to implement the equivalent function (in the unlikely event that you might need it).

server - Scalar String

The server from which to get the groups of which user is a member.

user - Scalar String

The user whose group membership you wish to examine.

array - Scalar String

The array that will contain the group names to which user belongs.

UserGetInfo(server, user, level, hash)

Returns the information at the specified level for the named user in hash.

server - Scalar String

The server from which to get the requested information about user.

user - Scalar String

The user whose information you want.

level - Scalar Int

One of: 0, 1, 2, 3, 10, 11 and 20. See USER INFO LEVELS.

hash - Hash Reference

The hash that will contain the keys and values for the information requested. See USER INFO FIELDS for information about which keys are present in a given level.

UserGetLocalGroups(server, user, array[, flags])

Gets the names of the local groups of which user is a member. Unlike the NetUserEnum() function in the API, this function does not allow you to specify a level. Since the underlying API restricts you to level 0 there really isn't any need to include it...

server - Scalar String

The server from which to get the local groups of which user is a member.

user - Scalar String

The user whose local group membership you wish to enumerate.

array - Array Reference

The array that will hold the names of the local groups to which user belongs.

flags - Scalar Int <em>(optional)</em>

Either Win32API::Net::LG_INCLUDE_INDIRECT() or 0. if flags is omitted, the function internally uses 0. Specifying LG_INCLUDE_INDIRECT() will include in the list the names of the groups of which the user is indirectly a member (e.g. by being in a global group that is a member of a local group).

This field can take no other values.

UserModalsGet()

This function is not currently implemented.

UserModalsSet()

This function is not currently implemented.

UserSetGroups(server, user, array)

Sets the (global) group membership for user to the specified groups. Unlike the API function NetUserSetGroups(), this function does not take a level parameter (mainly because this option is largely redundant).

server - Scalar String

The server on which you wish to set the group membership for user.

user - Scalar String

The user whose group membership you wish to set.

array - Array Reference

The array containing the (global) group names to set the users membership of.

This function will fail if any of the group names specified do not exist.

UserSetInfo(server, user, level, hash, error)

Sets the info for user according to the information contained in hash for level (see USER INFO LEVELS).

server - Scalar String

The server on which you wish to change the info for user.

user - Scalar String

The user whose info you wish to change.

level - Scalar Int

One of 0, 1, 2, 3, or 20 (according to Microsoft documentation). In practice, you can use all the 10xx levels as well to change most of the individual properties of the named user - although this may not be supported in future...

hash - Hash Reference

The hash that will contain the necessary key/value pairs required for level (see USER INFO LEVELS).

error - Scalar Int

Provides information on which field in hash were not properly specified. See USER FIELD ERRORS for more information about what values can be returned in this field.

NET GROUP FUNCTIONS

The Group*() functions all operate only on global groups. To modify local groups, use the corresponding LocalGroup*() functions.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled.

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function GetDCName() to find out what the domain controller is, should you not be running this on the PDC.

The following functions are available.

GroupAdd(server, level, hash, error)

Adds the specified group.

server - Scalar String

The server on which to add the group.

level - Scalar String

The level of information contained in hash. This can be one of 0, 1 or 2. See GROUP INFO LEVELS.

hash - Hash Reference

A hash containing the required key/value pairs for level.

error - Scalar Int

Provides information on which field in hash was not properly specified. See GROUP FIELD ERRORS for more information about what values can be returned in this field.

GroupAddUser(server, group, user)

Adds the specified user to the specified group.

server - Scalar String

The server on which to add the user to group.

group - Scalar String

The group to add the user to.

user - Scalar String

The user to add to group.

GroupDel(server, group)

Deletes the specified global group.

server - Scalar String

The server on which to delete the named group.

group -Scalar String

The group to delete.

GroupDelUser(server, group, user)

Deletes the specified user from the specified group.

server - Scalar String

The server on which to delete user from group.

group - Scalar String

The group from which to delete user.

user - Scalar String

The user to delete from group.

GroupEnum(server, array)

Enumerates all the global groups on the server. Unlike the API call NetGroupEnum(), this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

The server on which to enumerate the (global) groups.

array - Array Reference

An array that, on return, will contain the group names.

GroupGetInfo(server, group, level, hash)

Retrieves level information for group returning information in hash.

server - Scalar String

The server from which to get the group information.

group - Scalar String

The group whose information you wish to obtain.

level - Scalar Int

The level of information you wish to retrieve. This can be one of 1, 2 or 3. See GROUP INFO LEVELS.

hash - Hash Reference

The hash that will contain the information.

GroupGetUsers(server, group, array)

Returns (in array) the users belonging to group. Unlike the API call NetGroupGetUsers(), this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

The server from which to get the group information.

group - Scalar String

The group whose users you wish to obtain.

array - Array Reference

The array to hold the user names retrieved.

GroupSetInfo(server, group, level, hash, error)

Sets the information for group according to level.

server - Scalar String

The server on which to set the group information.

group - Scalar String

The group whose information you wish to set.

level - Scalar Int

The level of information you are supplying in hash. Level can be one of 0, 1 or 2. See GROUP INFO LEVELS.

hash - Hash Reference

The hash containing the required key/value pairs for level.

error - Scalar String

On failure, the error parameter will contain a value which specifies which field caused the error. See GROUP FIELD ERRORS.

GroupSetUsers(server, group, array)

Sets the membership of group to contain only those users specified in array. This function will fail if any user names contained in the array are not valid users on server. On successful completion group will contain only the users specified in array. Use the functions GroupAddUser()/GroupDelUser() to add and delete individual users from a group.

server - Scalar String

The server on which to set the group membership.

group - Scalar String

The group to set the membership of.

array - Array Reference

The array containing the names of all users who will be members of group.

NET LOCAL GROUP FUNCTIONS

The LocalGroup*() functions operate on local groups. If these functions are run on a PDC then these functions operate on the domains local groups.

Administrator or Account Operator group membership is required to successfully execute most of these functions on a remote server or on a computer that has local security enabled.

The server field can be the empty string, in which case the function defaults to running on the local computer. If you leave this field blank then you should ensure that you are running the function on a PDC or BDC for your current domain. Use the support function GetDCName() to find out what the domain controller is, should you not be running this on the PDC.

The following functions are available.

LocalGroupAdd(server, level, hash, error)

Adds the specified group. The name of the group is contained in the name key of hash.

server - Scalar String

The server on which to add the group.

level - Scalar String

The level of information contained in hash. This can be one of 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

A hash containing the required key/value pairs for level.

error - Scalar Int

Provides information on which field in hash wasn't properly specified. See LOCAL GROUP FIELD ERRORS for more information about what values this can take.

LocalGroupAddMember()

This function is obselete in the underlying API and has therefore not been implemented. Use LocalGroupAddMembers instead.

LocalGroupAddMembers(server, group, array)

Adds the specified users (members) to the local group. Unlike the API function NetLocalGroupAddMembers(), this function does not allow you to specify a level (internally it is hardcoded to 3). This was done to simplify the implementation. To add a 'local' user, you need only specify the name. You can also specify users using the DOMAIN\user syntax.

server - Scalar String

The server on which to add the members to group.

group - Scalar String

The group to add the members to.

array - Array Reference

The array containing the members to add to group.

LocalGroupDel(server, group)

Delete the specified local group.

server - Scalar String

The server on which to delete the named group.

group -Scalar String

The group to delete.

LocalGroupDelMember()

This function is obselete in the underlying API and has therefore not been implemented. Use LocalGroupDelMembers() instead.

LocalGroupDelMembers(server, group, array)

Delete the specified users (members) of the local group. Unlike the API function NetLocalGroupDelMembers(), this function does not allow you to specify a level (internally it is hardcoded to 3). This was done to simplify the implementation. To delete a 'local' user, you need only specify the name. You can also specify users using the DOMAIN\user syntax.

server - Scalar String

The server on which to delete the members from group.

group - Scalar String

The group to delete the members from.

array - Array Reference

The array containing the members to delete from group.

LocalGroupEnum(server, array)

Enumerates all the local groups on the server. Unlike the API call NetLocalGroupEnum(), this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

The server on which to enumerate the (local) groups.

array - Array Reference

The array to hold the group names.

LocalGroupGetInfo(server, group, level, hash)

Retrieves level information for group.

server - Scalar String

The server from which to get the group information.

group - Scalar String

The group whose information you wish to obtain.

level - Scalar Int

The level of information you wish to retrieve. This can be 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

The hash that will contain the information.

LocalGroupGetMembers(server, group, hash)

Retrieves the users belonging to group. Unlike the API call NetLocalGroupGetUsers(), this function does not allow you to specify a level (internally it is hardcoded to 0). In Perl it is trivial to implement the equivalent function (should you need it).

server - Scalar String

The server from which to retrieve the group information.

group - Scalar String

The group whose users you wish to obtain.

array - Array Reference

The array to hold the user names retrieved.

LocalGroupSetInfo(server, level, hash, error)

Sets the information for group according to level.

server - Scalar String

The server on which to set the group information.

group - Scalar String

The group whose information you wish to set.

level - Scalar Int

The level of information you are supplying in hash. Level can be one of 0 or 1. See LOCAL GROUP INFO LEVELS.

hash - Hash Reference

The hash containing the required key/value pairs for level.

error - Scalar String

On failure, the error parameter will contain a value which specifies which field caused the error. See LOCAL GROUP FIELD ERRORS.

LocalGroupSetMembers()

This function has not been implemented at present.

NET GET FUNCTIONS

GetDCName(server, domain, domain-controller)

Gets the domain-controller name for server and domain.

server - Scalar String

The server whose domain controller you wish to locate.

domain - Scalar String

The domain that server is a member of whose domain-controller you wish the locate.

domain-controller - Scalar String (output)

The name of the domain-controller for the requested domain.

Note: This module does not implement the NetGetAnyDCName()API function as this is obsolete.

USER INFO LEVELS

Most of the User*() functions take a level parameter. This level specifies how much detail the corresponding hash should contain (or in the case of a UserGet*() function, will contain after the call). The following level descriptions provide information on what fields should be present for a given level. See USER INFO FIELDS for a description of the fields.

Level 0

name

Level 1

name, password, passwordAge, priv, homeDir, comment, flags, scriptPath

Level 2

name, password, passwordAge, priv, homeDir, comment, flags, scriptPath, authFlags, fullName, usrComment, parms, workstations, lastLogon, lastLogoff, acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount, numLogons, logonServer, countryCode, codePage

Level 3

name, password, passwordAge, priv, homeDir, comment, flags, scriptPath, authFlags, fullName, usrComment, parms, workstations, lastLogon, lastLogoff, acctExpires, maxStorage, unitsPerWeek, logonHours, badPwCount, numLogons, logonServer, countryCode, codePage, userId, primaryGroupId, profile, homeDirDrive, passwordExpired

Level 10

name, comment, usrComment, fullName

Level 11

name, comment, usrComment, fullName, priv, authFlags, passwordAge, homeDir, parms, lastLogon, lastLogoff, badPwCount, numLogons, logonServer, countryCode, workstations, maxStorage, unitsPerWeek, logonHours, codePage

Level 20

name, fullName, comment, flags, userId

Level 21

Not available in this implementation

Level 22

Not available in this implementation

Level 1003

password

Level 1005

priv

Level 1006

homeDir

Level 1007

comment

Level 1008

flags

Level 1009

scriptPath

Level 1010

authFlags

Level 1011

fullName

Level 1012

usrComment

Level 1013

parms

Level 1014

workstations

Level 1017

acctExpires

Level 1018

maxStorage

Level 1020

unitsPerWeek, logonHours

Level 1023

logonServer

Level 1024

countryCode

Level 1025

codePage

Level 1051

primaryGroupId

Level 1052

profile

Level 1053

homeDirDrive

USER INFO FIELDS

The following is an alphabetical listing of each possible field, together with the data type that the field is expected to contain.

acctExpires - Scalar Int (UTC)

The time (as the number of seconds since 00:00:00, 1st January 1970) when the account expires. A -1 in this field specifies that the account never expires.

authFlags - Scalar Int (See USER_AUTH_FLAGS).

The level of authority that this use has. The value this can take depends on the users group membership - this value is therefore read only and cannot be set using UserAdd() or UserSetInfo(). Its value can be one of:

        User belongs to group           Flag value
        ---------------------           ----------
        Print Operators                 Win32API::Net::AF_OP_PRINT()
        Server Operators                Win32API::Net::AF_OP_SERVER()
        Account Operators               Win32API::Net::AF_OP_ACCOUNTS()
badPwCount - Scalar Int

The number of times that the user has failed to logon by specifying an incorrect password.

codePage - Scalar Int

The code page that this user uses.

comment - Scalar String

The comment associated with this user account. This can be any string (apparently of any length).

countryCode - Scalar Int

The country code that this user uses.

flags - Scalar Int (Bitwise OR of USER_FLAGS)

The flags for this user. See USER FLAGS.

fullName - Scalar String

The users' full name.

homeDir - Scalar String

The home directory of the user. This can be either a UNC path or an absolute path (drive letter + path). Can be the empty string ("").

homeDirDrive - Scalar String

The home directory drive that the users home directory is mapped to (assuming that the specified home directory is a UNC path).

lastLogon - Scalar Int (UTC)

The time (as the number of seconds since 00:00:00, 1st January 1970) that the user last logged on.

lastLogoff - Scalar Int (UTC)

The time (as the number of seconds since 00:00:00, 1st January 1970) that the user last logged off .

logonHours - Reference to Array of Integers (length 21 elements)

The times at which the user can logon. This should be an integer array with 21 elements. Each element represents an 8 hour period and each bit represents represents an hour. Only the lower byte of each integer is used. If this is left undefined then no restrictions are placed on the account.

logonServer - Scalar String

The logon server for this user. Under Windows NT, this value cannot be set and will always have the value '\\*' when queried.

maxStorage - Scalar Int

The current release of Windows NT does not implement disk quotas so it is believed that the value of this key is ignored.

name - Scalar String

The user name that this request applies to. Most of the functions take the user name as a separate argument. In general, the user name provided should be the same as that in the one provided in the hash.

numLogons - Scalar Int

The number of times that the named user has successfully logged on to this machine/domain.

parms - Scalar String

The value of this key can be used by applications. There are none known to to author that use it, although it could be used to hold adminitrative information.

password - Scalar String

The password to be set. The password is never returned in a UserGet() operation.

passwordAge - Scalar Int (UTC)

The current age of the password (stored as the number of seconds since 00:00:00, 1st January 1970).

passwordExpired - Scalar Int

The value of this key is used in two different ways. When queried via UserGetInfo() the return value is 0 is the password has not expired and 1 if it has. When setting the value via UserAdd() or UserSetInfo() a value of 0 indicates that the users' password has not expired whereas a value of 1 will force the user to change their password at the next logon.

primaryGroupId - Scalar Int

The id of the primary group that this user belongs to. When creating accounts with UserAdd() you should use a value of 0x201.

priv - Scalar Int (Bitwise OR of USER_PRIVILEGE_FLAGS)

The privilege level that this user has. This is never returned from a UserGet() call. See USER PRIVILEGE FLAGS.

profile - Scalar String

The profile that is associated with the named user. This can be UNC path, a local path or undefined.

scriptPath - Scalar String

The path to the logon script for this user. This should be specified as a relative path and will cause the logon script to be run from (relative location) in the logon servers export directory.

unitsPerWeek - Scalar Int

The value of this key represents the granularity of the logonHours array. Its use is beyond the scope of this package.

usrComment - Scalar String

The user comment field (contrasted with the comment field ;-).

workstations - Scalar String

A comma-separated string containing upto 8 workstation that the named user can login to. Setting a value for this key will then allow the named user to login to only those computers named.

userId - Scalar Int

The user id associated with this user This value is generated by the system and cannot be set or changed using the UserAdd() or UserSetInfo() calls.

USER FLAGS

The following is an alphabetical listing of the user flags. The flags key (see USER INFO FIELDS) should be the bitwise OR of one or more of these values.

UF_ACCOUNTDISABLE()

This account has been disabled.

UF_DONT_EXPIRE_PASSWD()

Never expire the password on this account.

UF_HOMEDIR_REQUIRED()

A home directory must be specified (ignored for NT).

UF_INTERDOMAIN_TRUST_ACCOUNT()

The account represents a interdomain trust account.

UF_LOCKOUT()

Lock out this account (or this account has been locked out due to security policy - i.e. badLogonCount is greater than your policy allows). This value can be cleared but not set by a UserSetInfo() call.

UF_NORMAL_ACCOUNT()

The account is a normal user account.

UF_PASSWD_CANT_CHANGE()

The password for this account cannot be changed (execpt by an Administrator using one of the above calls).

UF_PASSWD_NOTREQD()

A password is not required for this account.

UF_SCRIPT()

This <strong>must be set when creating account on Windows NT.

UF_SERVER_TRUST_ACCOUNT()

The account represents a Windows NT Backup Domain Controller account in the domain.

UF_TEMP_DUPLICATE_ACCOUNT()

To quote the Microsoft Documentation <em>&quot;This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.

UF_WORKSTATION_TRUST_ACCOUNT()

The account represents a computer account for a workstation or server in the domain.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

        $ufScript = Win32API::Net::UF_SCRIPT();

USER PRIVILEGE FLAGS

These following values are used in the priv key. This field is never initialised on a UserGet*() call and once set cannot be changed in a UserSetInfo() call.

USER_PRIV_ADMIN()

Account is an an administrative account.

USER_PRIV_GUEST()

Account is a guest account.

USER_PRIV_USER()

Account is a user account.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

        $userPrivUser = Win32API::Net::USER_PRIV_USER();

USER ENUM FILTER

These flags are used in the UserEnum() function to specify which accounts to retrieve. It should be a bitwise OR of some (or all) of the following.

FILTER_TEMP_DUPLICATE_ACCOUNT()

Show temporary duplicate account (one presumes).

FILTER_NORMAL_ACCOUNT()

Show normal user account.

FILTER_INTERDOMAIN_TRUST_ACCOUNT()

Show interdomain trust accounts.

FILTER_WORKSTATION_TRUST_ACCOUNT()

Show workstation trust accounts.

FILTER_SERVER_TRUST_ACCOUNT()

Show server trust accounts.

Please note that these are implemented as functions and are therefore called in the same way as other functions. You should typically use them like:

        $filterNormalAccounts = Win32API::Net::FILTER_NORMAL_ACCOUNT();

USER FIELD ERRORS

For the User*() functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing from the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful in debugging.

USER_ACCT_EXPIRES_PARMNUM()

acctExpires field was absent or not correctly specified.

USER_AUTH_FLAGS_PARMNUM()

authFlags field was absent or not correctly specified.

USER_BAD_PW_COUNT_PARMNUM()

badPasswordCount field was absent or not correctly specified.

USER_CODE_PAGE_PARMNUM()

codePage field was absent or not correctly specified.

USER_COMMENT_PARMNUM()

comment field was absent or not correctly specified.

USER_COUNTRY_CODE_PARMNUM()

countryCode field was absent or not correctly specified.

USER_FLAGS_PARMNUM()

flags field was absent or not correctly specified.

USER_FULL_NAME_PARMNUM()

fullName field was absent or not correctly specified.

USER_HOME_DIR_DRIVE_PARMNUM()

homeDirDrive field was absent or not correctly specified.

USER_HOME_DIR_PARMNUM()

homeDir field was absent or not correctly specified.

USER_LAST_LOGOFF_PARMNUM()

lastLogoff field was absent or not correctly specified.

USER_LAST_LOGON_PARMNUM()

lastLogon field was absent or not correctly specified.

USER_LOGON_HOURS_PARMNUM()

logonHours field was absent or not correctly specified.

USER_LOGON_SERVER_PARMNUM()

logonServer field was absent or not correctly specified.

USER_MAX_STORAGE_PARMNUM()

maxStorage field was absent or not correctly specified.

USER_NAME_PARMNUM()

name field was absent or not correctly specified.

USER_NUM_LOGONS_PARMNUM()

numLogons field was absent or not correctly specified.

USER_PARMS_PARMNUM()

parms field was absent or not correctly specified.

USER_PASSWORD_AGE_PARMNUM()

passwordAge field was absent or not correctly specified.

USER_PASSWORD_PARMNUM()

password field was absent or not correctly specified.

USER_PRIMARY_GROUP_PARMNUM()

primaryGroup field was absent or not correctly specified.

USER_PRIV_PARMNUM()

priv field was absent or not correctly specified.

USER_PROFILE_PARMNUM()

profile field was absent or not correctly specified.

USER_SCRIPT_PATH_PARMNUM()

scriptPath field was absent or not correctly specified.

USER_UNITS_PER_WEEK_PARMNUM()

unitPerWeek field was absent or not correctly specified.

USER_USR_COMMENT_PARMNUM()

usrComment field was absent or not correctly specified.

USER_WORKSTATIONS_PARMNUM()

workstations field was absent or not correctly specified.

GROUP INFO LEVELS

Some of the Group*() functions take a level parameter. This level specifies how much detail the corresponding hash should contain (or in the case of a GroupGetInfo() function, will contain after the call). The following level descriptions provide information on what fields should be present for a given level. See GROUP INFO FIELDS for a description of the fields.

Level 0

name.

Level 1

name, comment.

Level 2

name, comment, groupId, attributes.

Level 1002

comment.

Level 1005

attributes.

GROUP INFO FIELDS

attributes - Scalar Int

The attributes of the group. These are no longer settable in Windows NT 4.0 and they are not currently supported in this package either.

comment - Scalar String

The comment that applies to this group. This is the only value that can be set via a GroupSetInfo call.

groupId - Scalar Int

The groups Id.

name - Scalar String

The groups name.

GROUP FIELD ERRORS

For the Group*() functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing from the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful for debugging purposes.

GROUP_ATTRIBUTES_PARMNUM()

attributes field was absent or not correctly specified.

GROUP_COMMENT_PARMNUM()

comment field was absent or not correctly specified.

GROUP_NAME_PARMNUM()

name field was absent or not correctly specified.

GROUP USERS INFO LEVELS

The GroupGetUsers() function can take a level of 0 or 1. These will return the following:

Level 0

name.

Level 1

name, attributes.

GROUP USERS INFO FIELDS

name - Scalar String

The user's name.

attributes - Scalar Int

The attributes of the group. These are no longer settable in Windows NT 4.0 and they are not currently supported in this package either.

LOCAL GROUP INFO LEVELS

Level 0

name

Level 1

name, comment

Level 1002

comment

LOCAL GROUP INFO FIELDS

name - Scalar String

The groups name

comment - Scalar String

The groups 'comment'

LOCAL GROUP FIELD ERRORS

For the LocalGroup*() functions that take an error parameter this variable will, on failure, contain one of the following constants. Note that the function may fail because more than one key/value was missing or incorrectly specified in the input hash. You will only find out about the first one that was incorrectly specified. This is only really useful for debugging purposes.

LOCALGROUP_NAME_PARMNUM()

The name field was absent or not correctly specified.

LOCALGROUP_COMMENT_PARMNUM()

The comment field wasabsent or not correctly specified.

EXAMPLES

The following example shows how you can create a function in Perl that has the same functionality as the NetUserEnum() API call. The Perl version doesn't have the level parameter so you must first use the UserEnum() function to retrieve all the account names and then iterate through the returned array issuing UserGetInfo() calls.

    sub userEnumAtLevel {
       my($server, $level, $filter) = @_;
       my(@array);
       Win32API::Net::UserEnum($server, \@array, $filter);
       for $user (@array) {
          Win32API::Net::UserGetInfo($server, $user, $level, \%hash);
          print "This could access all level $level settings for $user - eg fullName $hash{fullName}\n";
       }
    }
    userEnumAtLevel("", 2, 0);

AUTHOR

Bret Giddings, <bret@essex.ac.uk>

SEE ALSO

perl(1)

ACKNOWEDGEMENTS

This work was built upon work done by HiP Communications along with modifications to HiPs code by <michael@ecel.uwa.edu.au> and <rothd@roth.net>. In addition, I would like to thank Jenny Emby at GEC Marconi, U.K. for proof reading this manual page and making many suggestions that have led to its current layout. Last but not least I would like to thank Larry Wall and all the other Perl contributors for making this truly wonderful language.


Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H

    • Exports
    • The Win32API:: heirarchy
    • Buffer sizes
    • Hungarian Notation
  • BUGS
  • AUTHOR
  • SEE ALSO

NAME

Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H

SYNOPSIS

  use Win32API::Registry 0.21 qw( :ALL );

  RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key );
    or  die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
            regLastError(),"\n";
  RegQueryValueEx( $key, "Information", [], $type, $data, [] );
    or  die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: ",
            regLastError(),"\n";
  [...]
  RegCloseKey( $key )
    or  die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
            regLastError(),"\n";

DESCRIPTION

This provides fairly low-level access to the Win32 System API calls dealing with the Registry [mostly from WINREG.H]. This is mostly intended to be used by other modules such as Win32::TieRegistry [which provides an extremely Perl-friendly method for using the Registry].

For a description of the logical structure of the Registry, see the documentation for the Win32::TieRegistry module.

To pass in NULL as the pointer to an optional buffer, pass in an empty list reference, [].

Beyond raw access to the API calls and related constants, this module handles smart buffer allocation and translation of return codes.

All calls return a true value for success and a false value for failure. After any failure, $^E should automatically be set to indicate the reason. However, current versions of Perl often overwrite $^E too quickly, so you can use regLastError() instead, which is only set by Win32API::Registry routines.

Note that $! is not set by these routines except by Win32API::Registry::constant() when a constant is not defined.

Exports

Nothing is exported by default. The following tags can be used to have sets of symbols exported.

[Note that much of the following documentation refers to the behavior of the underlying API calls which may vary in current and future versions of the Win32 API without any changes to this module. Therefore you should check the Win32 API documentation directly when needed.]

:Func

The basic function names:

AllowPriv
AllowPriv( $sPrivName, $bEnable )

Not a Win32 API call. Enables or disables a specific privilege for the current process. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure. This routine does not provide a way to tell if a privilege is currently enabled.

$sPrivname is a Win32 privilege name [see :SE_]. For example, "SeBackupPrivilege" [a.k.a. SE_BACKUP_NAME] controls whether you can use RegSaveKey() and "SeRestorePrivilege" [a.k.a. SE_RESTORE_NAME] controls whether you can use RegLoadKey().

If $bEnable is true, then AllowPriv() tries to enable the privilege. Otherwise it tries to disable the privilege.

AbortSystemShutdown
AbortSystemShutdown( $sComputerName )

Tries to abort a remote shutdown request previously made via InitiateSystemShutdown(). Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

InitiateSystemShutdown
InitiateSystemShutdown( $sComputer, $sMessage, $uTimeoutSecs, $bForce, $bReboot )

Requests that a [remote] computer be shutdown or rebooted. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$sComputer is the name [or address] of the computer to be shutdown or rebooted. You can use [] [for NULL] or "" to indicate the local computer.

$sMessage is the message to be displayed in a pop-up window on the desktop of the computer to be shutdown or rebooted until the timeout expires or the shutdown is aborted via AbortSystemShutdown(). With $iTimeoutSecs == 0, the message will never be visible.

$iTimeoutSecs is the number of seconds to wait before starting the shutdown.

If $bForce is false, then any applications running on the remote computer get a chance to prompt the remote user whether they want to save changes. Also, for any applications that do not exit quickly enough, the operating system will prompt the user whether they wish to wait longer for the application to exit or force it to exit now. At any of these prompts the user can press CANCEL to abort the shutdown but if no applications have unsaved data, they will likely all exit quickly and the shutdown will progress with the remote user having no option to cancel the shutdown.

If $bForce is true, all applications are told to exit immediately and so will not prompt the user even if there is unsaved data. Any applications that take too long to exit will be forcibly killed after a short time. The only way to abort the shutdown is to call AbortSystemShutdown() before the timeout expires and there is no way to abort the shutdown once it has begun.

If $bReboot is true, the computer will automatically reboot once the shutdown is complete. If $bReboot is false, then when the shutdown is complete the computer will halt at a screen indicating that the shutdown is complete and offering a way for the user to start to boot the computer.

You must have the "SeRemoteShutdownPrivilege" privilege on the remote computer for this call to succeed. If shutting down the local computer, then the calling process must have the "SeShutdownPrivilege" privilege and have it enabled.

RegCloseKey
RegCloseKey( $hKey )

Closes the handle to a Registry key returned by RegOpenKeyEx(), RegConnectRegistry(), RegCreateKeyEx(), or a few other routines. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

RegConnectRegistry
RegConnectRegistry( $sComputer, $hRootKey, $ohKey )

Connects to one of the root Registry keys of a remote computer. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$sComputer is the name [or address] of a remote computer whose Registry you wish to access.

$hKey must be either HKEY_LOCAL_MACHINE or HKEY_USERS and specifies which root Registry key on the remote computer you wish to have access to.

$phKey will be set to the handle to be used to access the remote Registry key if the call succeeds.

regConstant
$value= regConstant( $sConstantName )

Fetch the value of a constant. Returns undef if $sConstantName is not the name of a constant supported by this module. Never sets $! nor $^E.

This function is rarely used since you will usually get the value of a constant by having that constant imported into your package by listing the constant name in the use Win32API::Registry statement and then simply using the constant name in your code [perhaps followed by ()]. This function is useful for verifying constant names not in Perl code, for example, after prompting a user to type in a constant name.

RegCreateKey
RegCreateKey( $hKey, $sSubKey, $ohSubKey )

This routine is meant only for compatibility with Windows version 3.1. Use RegCreateKeyEx() instead.

RegCreateKeyEx
RegCreateKeyEx( $hKey, $sSubKey, $uZero, $sClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )

Creates a new Registry subkey. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of the new subkey to be created.

$iZero is reserved for future use and should always be specified as 0.

$sClass is a string to be used as the class for the new subkey. We are not aware of any current use for Registry key class information so the empty string, "", should usually be used here.

$iOpts is a numeric value containing bits that control options used while creating the new subkey. REG_OPTION_NON_VOLATILE is the default. REG_OPTION_VOLATILE [which is ignored on Windows 95] means the data stored under this key is not kept in a file and will not be preserved when the system reboots. REG_OPTION_BACKUP_RESTORE [also ignored on Windows 95] means ignore the $iAccess parameter and try to open the new key with the access required to backup or restore the key.

$iAccess is a numeric mask of bits specifying what type of access is desired when opening the new subkey. See RegOpenKeyEx().

$pSecAttr is a SECURITY_ATTRIBUTES structure packed into a Perl string which controls whether the returned handle can be inherited by child processes. Normally you would pass [] for this parameter to have NULL passed to the underlying API indicating that the handle cannot be inherited. If not under Windows95, then $pSecAttr also allows you to specify SECURITY_DESCRIPTOR that controls which users will have what type of access to the new key -- otherwise the new key inherits its security from its parent key.

$phKey will be set to the handle to be used to access the new subkey if the call succeeds.

$piDisp will be set to either REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY to indicate for which reason the call succeeded. Can be specified as [] if you don't care.

If $phKey and $piDisp start out as integers, then they will probably remain unchanged if the call fails.

RegDeleteKey
RegDeleteKey( $hKey, $sSubKey )

Deletes a subkey of an open Registry key provided that the subkey contains no subkeys of its own [but the subkey may contain values]. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of the subkey to be deleted.

RegDeleteValue
RegDeleteValue( $hKey, $sValueName )

Deletes a value from an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sValueKey is the name of the value to be deleted.

RegEnumKey
RegEnumKey( $hKey, $uIndex, $osName, $ilNameSize )

This routine is meant only for compatibility with Windows version 3.1. Use RegEnumKeyEx() instead.

RegEnumKeyEx
RegEnumKeyEx( $hKey, $uIndex, $osName, $iolName, $pNull, $osClass, $iolClass, $opftLastWrite )

Lets you enumerate the names of all of the subkeys directly under an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iIndex is the sequence number of the immediate subkey that you want information on. Start with this value as 0 then repeat the call incrementing this value each time until the call fails with $^E/regLastError() numerically equal to ERROR_NO_MORE_ITEMS.

$sName will be set to the name of the subkey. Can be [] if you don't care about the name.

$plName initially specifies the [minimum] buffer size to be allocated for $sName. Will be set to the length of the subkey name if the requested subkey exists even if $sName isn't successfully set to the subkey name. See Buffer sizes for more information.

$pNull is reserved for future used and should be passed as [].

$sClass will be set to the class name for the subkey. Can be [] if you don't care about the class.

$plClass initially specifies the [minimum] buffer size to be allocated for $sClass and will be set to the length of the subkey class name if the requested subkey exists. See Buffer sizes for more information.

$pftLastWrite will be set to a FILETIME structure packed into a Perl string and indicating when the subkey was last changed. Can be [].

You may omit both $plName and $plClass to get the same effect as passing in [] for each of them.

RegEnumValue
RegEnumValue( $hKey, $uIndex, $osValName, $iolValName, $pNull, $ouType, $opValData, $iolValData )

Lets you enumerate the names of all of the values contained in an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iIndex is the sequence number of the value that you want information on. Start with this value as 0 then repeat the call incrementing this value each time until the call fails with ERROR_NO_MORE_ITEMS.

$sValName will be set to the name of the value. Can be [] if you don't care about the name.

$plValName initially specifies the [minimum] buffer size to be allocated for $sValName. Will be set to the length of the value name if the requested value exists even if $sValName isn't successfully set to the value name. See Buffer sizes for more information.

$pNull is reserved for future used and should be passed as [].

$piType will be set to the type of data stored in the value data. If the call succeeds, it will be set to a REG_* value unless passed in as [].

$pValData will be set to the data [packed into a Perl string] that is stored in the requested value. Can be [] if you don't care about the value data.

$plValData initially specifies the [minimum] buffer size to be allocated for $sValData and will be set to the length of the value data if the requested value exists. See Buffer sizes for more information.

You may omit both $plValName and $plValData to get the same effect as passing in [] for each of them.

RegFlushKey
RegFlushKey( $hKey )

Forces the data stored under an open Registry key to be flushed to the disk file where the data is preserved between reboots. Forced flushing is not guaranteed to be efficient so this routine should almost never be called. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

RegGetKeySecurity
RegGetKeySecurity( $hKey, $uSecInfo, $opSecDesc, $iolSecDesc )

Retrieves one of the SECURITY_DESCRIPTOR structures describing part of the security for an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$iSecInfo is a numeric SECURITY_INFORMATION value that specifies which parts of the SECURITY_DESCRIPTOR structure to retrieve. Should be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or or SACL_SECURITY_INFORMATION or two or more of these bits combined using |.

$pSecDesc will be set to the requested SECURITY_DESCRIPTOR structure [packed into a Perl string].

$plSecDesc initially specifies the [minimum] buffer size to be allocated for $sSecDesc and will be set to the length of the security descriptor. See Buffer sizes for more information. You may omit this parameter to get the same effect as passing in [] for it.

regLastError
$svError= regLastError();
regLastError( $uError );

Returns the last error encountered by a routine from this module. It is just like $^E except it isn't changed by anything except routines from this module. Ideally you could just use $^E, but current versions of Perl often overwrite $^E before you get a chance to check it and really old versions of Perl don't really support $^E under Win32.

Just like $^E, in a numeric context regLastError() returns the numeric error value while in a string context it returns a text description of the error [actually it returns a Perl scalar that contains both values so $x= regLastError() causes $x to give different values in string vs. numeric contexts].

The last form sets the error returned by future calls to regLastError() and should not be used often. $uError must be a numeric error code. Also returns the dual-valued version of $uError.

RegLoadKey
RegLoadKey( $hKey, $sSubKey, $sFileName )

Loads a hive file. That is, it creates a new subkey in the Registry and associates that subkey with a disk file that contains a Registry hive so that the new subkey can be used to access the keys and values stored in that hive. Hives are usually created via RegSaveKey(). Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key that can have hives loaded to it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the new subkey to created and associated with the hive file.

$sFileName is the name of the hive file to be loaded. This file name is interpretted relative to the %SystemRoot%/System32/config directory on the computer where the $hKey key resides. If $sFileName is on a FAT file system, then its name must not have an extension.

You must have the SE_RESTORE_NAME privilege to use this routine.

WARNING: Loading of hive files via a network share may silently corrupt the hive and so should not be attempted [this is a problem in at least some versions of the underlying API which this module does not try to fix or avoid]. To access a hive file located on a remote computer, connect to the remote computer's Registry and load the hive via that.

RegNotifyChangeKeyValue
RegNotifyChangeKeyValue( $hKey, $bWatchSubtree, $uNotifyFilter, $hEvent, $bAsync )

Arranges for your process to be notified when part of the Registry is changed. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call] for which you wish to be notified when any changes are made to it.

If $bWatchSubtree is true, then changes to any subkey or descendant of $hKey are also reported.

$iNotifyFilter controllers what types of changes are reported. It is a numeric value containing one or more of the following bit masks:

REG_NOTIFY_CHANGE_NAME

Notify if a subkey is added or deleted to a monitored key.

REG_NOTIFY_CHANGE_LAST_SET

Notify if a value in a monitored key is added, deleted, or modified.

REG_NOTIFY_CHANGE_SECURITY

Notify if a security descriptor of a monitored key is changed.

REG_NOTIFY_CHANGE_ATTRIBUTES

Notify if any attributes of a monitored key are changed [class name or security descriptors].

$hEvent is ignored unless $bAsync is true. Otherwise, $hEvent is a handle to a Win32 event that will be signaled when changes are to be reported.

If $bAsync is true, then RegNotifyChangeKeyValue() returns immediately and uses $hEvent to notify your process of changes. If $bAsync is false, then RegNotifyChangeKeyValue() does not return until there is a change to be notified of.

This routine does not work with Registry keys on remote computers.

RegOpenKey
RegOpenKey( $hKey, $sSubKey, $ohSubKey )

This routine is meant only for compatibility with Windows version 3.1. Use RegOpenKeyEx() instead.

RegOpenKeyEx
RegOpenKeyEx( $hKey, $sSubKey, $uOptions, $uAccess, $ohSubKey )

Opens an existing Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sSubKey is the name of an existing subkey to be opened. Can be "" or [] to open an additional handle to the key specified by $hKey.

$iOptions is a numeric value containing bits that control options used while opening the subkey. There are currently no supported options so this parameter should be specified as 0.

$iAccess is a numeric mask of bits specifying what type of access is desired when opening the new subkey. Should be a combination of one or more of the following bit masks:

KEY_ALL_ACCESS
    KEY_READ | KEY_WRITE | KEY_CREATE_LINK
KEY_READ
    KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
KEY_WRITE
    KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
KEY_QUERY_VALUE
KEY_SET_VALUE
KEY_ENUMERATE_SUB_KEYS
KEY_CREATE_SUB_KEY
KEY_NOTIFY

Allows you to use RegNotifyChangeKeyValue() on the opened key.

KEY_EXECUTE

Same as KEY_READ.

KEY_CREATE_LINK

Gives you permission to create a symbolic link like HKEY_CLASSES_ROOT and HKEY_CURRENT_USER, though the method for doing so is not documented [and probably requires use of the mostly undocumented "native" routines, Nt*() a.k.a. Zw*()].

$phKey will be set to the handle to be used to access the new subkey if the call succeeds.

RegQueryInfoKey
RegQueryInfoKey( $hKey, $osClass, $iolClass, $pNull, $ocSubKeys, $olSubKey, $olSubClass, $ocValues, $olValName, $olValData, $olSecDesc, $opftTime )

Gets miscellaneous information about an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sClass will be set to the class name for the key. Can be [] if you don't care about the class.

$plClass initially specifies the [minimum] buffer size to be allocated for $sClass and will be set to the length of the key's class name. See Buffer sizes for more information. You may omit this parameter to get the same effect as passing in [] for it.

$pNull is reserved for future use and should be passed as [].

$pcSubKeys will be set to the count of the number of subkeys directly under this key. Can be [].

$plSubKey will be set to the length of the longest subkey name. Can be [].

$plSubClass will be set to the length of the longest class name used with an immediate subkey of this key. Can be [].

$pcValues will be set to the count of the number of values in this key. Can be [].

$plValName will be set to the length of the longest value name in this key. Can be [].

$plValData will be set to the length of the longest value data in this key. Can be [].

$plSecDesc will be set to the length of this key's full security descriptor.

$pftTime will be set to a FILETIME structure packed into a Perl string and indicating when this key was last changed. Can be [].

RegQueryMultipleValues
RegQueryMultipleValues( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )

Allows you to use a single call to query several values from a single open Registry key to maximize efficiency. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$pValueEnts should contain a list of VALENT structures packed into a single Perl string. Each VALENT structure should have the ve_valuename entry [the first 4 bytes] pointing to a string containing the name of a value stored in this key. The remaining fields are set if the function succeeds.

$cValueEnts should contain the count of the number of VALENT structures contained in $pValueEnts.

$pBuffer will be set to the data from all of the requested values concatenated into a single Perl string.

$plBuffer initially specifies the [minimum] buffer size to be allocated for $sBuffer and will be set to the total length of the data to be written to $sBuffer. See Buffer sizes for more information. You may omit this parameter to get the same effect as passing in [] for it.

Here is sample code to populate $pValueEnts:

    # @ValueNames= ...list of value name strings...;
    $cValueEnts= @ValueNames;
    $pValueEnts= pack( " p x4 x4 x4 " x $cValueEnts, @ValueNames );

Here is sample code to retrieve the data type and data length returned in $pValueEnts:

    @Lengths= unpack( " x4 L x4 x4 " x $cValueEnts, $pValueEnts );
    @Types=   unpack( " x4 x4 x4 L " x $cValueEnts, $pValueEnts );

Given the above, and assuming you haven't modified $sBuffer since the call, you can also extract the value data strings from $sBuffer by using the pointers returned in $pValueEnts:

    @Data=    unpack(  join( "", map {" x4 x4 P$_ x4 "} @Lengths ),
                $pValueEnts  );

Much better is to use the lengths and extract directly from $sBuffer using unpack() [or substr()]:

    @Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
RegQueryValue
RegQueryValue( $hKey, $sSubKey, $osValueData, $iolValueData )

This routine is meant only for compatibility with Windows version 3.1. Use RegQueryValueEx() instead. This routine can only query unamed values [a.k.a. "default values"], that is, values with a name of "".

RegQueryValueEx
RegQueryValueEx( $hKey, $sValueName, $pNull, $ouType, $opValueData, $iolValueData )

Lets you look up value data stored in an open Registry key by specifying the value name. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sValueName is the name of the value whose data you wish to retrieve.

$pNull this parameter is reserved for future use and should be specified as [].

$piType will be set to indicate what type of data is stored in the named value. Will be set to a REG_* value if the function succeeds.

$pValueData will be set to the value data [packed into a Perl string] that is stored in the named value. Can be [] if you don't care about the value data.

$plValueData initially specifies the [minimum] buffer size to be allocated for $sValueData and will be set to the size [always in bytes] of the data to be written to $sValueData, even if $sValueData is not successfully written to. See Buffer sizes for more information.

RegReplaceKey
RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )

Lets you replace an entire hive when the system is next booted. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key that has hive(s) loaded in it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the subkey of $hKey whose hive you wish to have replaced on the next reboot.

$sNewFile is the name of a file that will replace the existing hive file when the system reboots.

$sOldFile is the file name to save the current hive file to when the system reboots.

$sNewFile and $sOldFile are interpretted relative to the %SystemRoot%/System32/config directory on the computer where the $hKey key resides [I think]. If either file is [would be] on a FAT file system, then its name must not have an extension.

You must have the SE_RESTORE_NAME privilege to use this routine.

RegRestoreKey
RegRestoreKey( $hKey, $sFileName, $uFlags )

Reads in a hive file and copies its contents over an existing Registry tree. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sFileName is the name of the hive file to be read. For each value and subkey in this file, a value or subkey will be added or replaced in $hKey.

$uFlags is usally 0. It can also be REG_WHOLE_HIVE_VOLATILE which, rather than copying the hive over the existing key, replaces the existing key with a temporary, memory-only Registry key and then copies the hive contents into it. This option only works if $hKey is HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

RegRestoreKey does not delete values nor keys from the existing Registry tree when there is no corresponding value/key in the hive file.

RegSaveKey
RegSaveKey( $hKey, $sFileName, $pSecAttr )

Dumps any open Registry key and all of its subkeys and values into a new hive file. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sFileName is the name of the file that the Registry tree should be saved to. It is interpretted relative to the %SystemRoot%/System32/config directory on the computer where the $hKey key resides. If $sFileName is on a FAT file system, then it must not have an extension.

$pSecAttr contains a SECURITY_ATTRIBUTES structure that specifies the permissions to be set on the new file that is created. This can be [].

You must have the SE_RESTORE_NAME privilege to use this routine.

RegSetKeySecurity
RegSetKeySecurity( $hKey, $uSecInfo, $pSecDesc )

Sets [part of] the SECURITY_DESCRIPTOR structure describing part of the security for an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$uSecInfo is a numeric SECURITY_INFORMATION value that specifies which SECURITY_DESCRIPTOR structure to set. Should be OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION or two or more of these bits combined using |.

$pSecDesc contains the new SECURITY_DESCRIPTOR structure packed into a Perl string.

RegSetValue
RegSetValue( $hKey, $sSubKey, $uType, $sValueData, $lValueData )

This routine is meant only for compatibility with Windows version 3.1. Use RegSetValueEx() instead. This routine can only set unamed values [a.k.a. "default values"].

RegSetValueEx
RegSetValueEx( $hKey, $sName, $uZero, $uType, $pData, $lData )

Adds or replaces a value in an open Registry key. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key [either HKEY_* or from a previous call].

$sName is the name of the value to be set.

$uZero is reserved for future use and should be specified as 0.

$uType is the type of data stored in $pData. It should be a REG_* value.

$pData is the value data packed into a Perl string.

$lData is the length of the value data that is stored in $pData. You will usually omit this parameter or pass in 0 to have length($pData) used. In both of these cases, if $iType is REG_SZ or REG_EXPAND_SZ, RegSetValueEx() will append a trailing '\0' to the end of $pData [unless there is already one].

RegUnLoadKey
RegUnLoadKey( $hKey, $sSubKey )

Unloads a previously loaded hive file. That is, closes the hive file then deletes the subkey that was providing access to it. Returns a true value if successful and a false value [and sets $^E/regLastError()] on failure.

$hKey is the handle to a Registry key that has hives loaded in it. This must be HKEY_LOCAL_MACHINE, HKEY_USERS, or a remote version of one of these from a call to RegConnectRegistry().

$sSubKey is the name of the subkey whose hive you wish to have unloaded.

:FuncA

The ASCII-specific function names.

Each of these is identical to the version listed above without the trailing "A":

        AbortSystemShutdownA    InitiateSystemShutdownA
        RegConnectRegistryA     RegCreateKeyA           RegCreateKeyExA
        RegDeleteKeyA           RegDeleteValueA         RegEnumKeyA
        RegEnumKeyExA           RegEnumValueA           RegLoadKeyA
        RegOpenKeyA             RegOpenKeyExA           RegQueryInfoKeyA
        RegQueryMultipleValuesA RegQueryValueA          RegQueryValueExA
        RegReplaceKeyA          RegRestoreKeyA          RegSaveKeyA
        RegSetValueA            RegSetValueExA          RegUnLoadKeyA
:FuncW

The UNICODE-specific function names. These are the same as the versions listed above without the trailing "W" except that string parameters are UNICODE strings rather than ASCII strings, as indicated.

AbortSystemShutdownW
AbortSystemShutdownW( $swComputerName )

$swComputerName is UNICODE.

InitiateSystemShutdownW
InitiateSystemShutdownW( $swComputer, $swMessage, $uTimeoutSecs, $bForce, $bReboot )

$swComputer and $swMessage are UNICODE.

RegConnectRegistryW
RegConnectRegistryW( $swComputer, $hRootKey, $ohKey )

$swComputer is UNICODE.

RegCreateKeyW
RegCreateKeyW( $hKey, $swSubKey, $ohSubKey )

$swSubKey is UNICODE.

RegCreateKeyExW
RegCreateKeyExW( $hKey, $swSubKey, $uZero, $swClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )

$swSubKey and $swClass are UNICODE.

RegDeleteKeyW
RegDeleteKeyW( $hKey, $swSubKey )

$swSubKey is UNICODE.

RegDeleteValueW
RegDeleteValueW( $hKey, $swValueName )

$swValueName is UNICODE.

RegEnumKeyW
RegEnumKeyW( $hKey, $uIndex, $oswName, $ilwNameSize )

$oswName is UNICODE and $ilwNameSize is measured as number of WCHARs.

RegEnumKeyExW
RegEnumKeyExW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $oswClass, $iolwClass, $opftLastWrite )

$swName and $swClass are UNICODE and $iolwName and $iolwClass are measured as number of WCHARs.

RegEnumValueW
RegEnumValueW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $ouType, $opData, $iolData )

$oswName is UNICODE and $iolwName is measured as number of WCHARs.

$opData is UNICODE if $piType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $iolData is measured as number of bytes even in these cases.

RegLoadKeyW
RegLoadKeyW( $hKey, $swSubKey, $swFileName )

$swSubKey and $swFileName are UNICODE.

RegOpenKeyW
RegOpenKeyW( $hKey, $swSubKey, $ohSubKey )

$swSubKey is UNICODE.

RegOpenKeyExW
RegOpenKeyExW( $hKey, $swSubKey, $uOptions, $uAccess, $ohSubKey )

$swSubKey is UNICODE.

RegQueryInfoKeyW
RegQueryInfoKeyW( $hKey, $oswClass, $iolwClass, $pNull, $ocSubKeys, $olwSubKey, $olwSubClass, $ocValues, $olwValName, $olValData, $olSecDesc, $opftTime )

$swClass is UNICODE. $iolwClass, $olwSubKey, $olwSubClass, and $olwValName are measured as number of WCHARs. Note that $olValData is measured as number of bytes.

RegQueryMultipleValuesW
RegQueryMultipleValuesW( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )

The ve_valuename fields of the VALENT [actually VALENTW] structures in $ioarValueEnts are UNICODE. Values of type REG_SZ, REG_EXPAND_SZ, and REG_MULTI_SZ are written to $opBuffer in UNICODE. Note that $iolBuffer and the ve_valuelen fields of the VALENT [VALENTW] structures are measured as number of bytes.

RegQueryValueW
RegQueryValueW( $hKey, $swSubKey, $oswValueData, $iolValueData )

$swSubKey and $oswValueData are UNICODE. Note that $iolValueData is measured as number of bytes.

RegQueryValueExW
RegQueryValueExW( $hKey, $swName, $pNull, $ouType, $opData, $iolData )

$swName is UNICODE.

$opData is UNICODE if $ouType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $iolData is measured as number of bytes even in these cases.

RegReplaceKeyW
RegReplaceKeyW( $hKey, $swSubKey, $swNewFile, $swOldFile )

$swSubKey, $swNewFile, and $swOldFile are UNICODE.

RegRestoreKeyW
RegRestoreKeyW( $hKey, $swFileName, $uFlags )

$swFileName is UNICODE.

RegSaveKeyW
RegSaveKeyW( $hKey, $swFileName, $pSecAttr )

$swFileName is UNICODE.

RegSetValueW
RegSetValueW( $hKey, $swSubKey, $uType, $swValueData, $lValueData )

$swSubKey and $swValueData are UNICODE. Note that $lValueData is measured as number of bytes even though $swValueData is always UNICODE.

RegSetValueExW
RegSetValueExW( $hKey, $swName, $uZero, $uType, $pData, $lData )

$swName is UNICODE.

$pData is UNICODE if $uType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ. Note that $lData is measured as number of bytes even in these cases.

RegUnLoadKeyW
RegUnLoadKeyW( $hKey, $swSubKey )

$swSubKey is UNICODE.

:HKEY_

All HKEY_* constants:

        HKEY_CLASSES_ROOT       HKEY_CURRENT_CONFIG     HKEY_CURRENT_USER
        HKEY_DYN_DATA           HKEY_LOCAL_MACHINE      HKEY_PERFORMANCE_DATA
        HKEY_USERS
:KEY_

All KEY_* constants:

        KEY_QUERY_VALUE         KEY_SET_VALUE           KEY_CREATE_SUB_KEY
        KEY_ENUMERATE_SUB_KEYS  KEY_NOTIFY              KEY_CREATE_LINK
        KEY_READ                KEY_WRITE               KEY_EXECUTE
        KEY_ALL_ACCESS
:REG_

All REG_* constants:

        REG_CREATED_NEW_KEY             REG_OPENED_EXISTING_KEY
        REG_LEGAL_CHANGE_FILTER         REG_NOTIFY_CHANGE_ATTRIBUTES
        REG_NOTIFY_CHANGE_NAME          REG_NOTIFY_CHANGE_LAST_SET
        REG_NOTIFY_CHANGE_SECURITY      REG_LEGAL_OPTION
        REG_OPTION_BACKUP_RESTORE       REG_OPTION_CREATE_LINK
        REG_OPTION_NON_VOLATILE         REG_OPTION_OPEN_LINK
        REG_OPTION_RESERVED             REG_OPTION_VOLATILE
        REG_WHOLE_HIVE_VOLATILE         REG_REFRESH_HIVE
        REG_NO_LAZY_FLUSH
        REG_NONE                        REG_SZ
        REG_EXPAND_SZ                   REG_BINARY
        REG_DWORD                       REG_DWORD_LITTLE_ENDIAN
        REG_DWORD_BIG_ENDIAN            REG_LINK
        REG_MULTI_SZ                    REG_RESOURCE_LIST
        REG_FULL_RESOURCE_DESCRIPTOR    REG_RESOURCE_REQUIREMENTS_LIST
:ALL

All of the above.

:SE_

The strings for the following privilege names:

        SE_ASSIGNPRIMARYTOKEN_NAME      SE_AUDIT_NAME
        SE_BACKUP_NAME                  SE_CHANGE_NOTIFY_NAME
        SE_CREATE_PAGEFILE_NAME         SE_CREATE_PERMANENT_NAME
        SE_CREATE_TOKEN_NAME            SE_DEBUG_NAME
        SE_INCREASE_QUOTA_NAME          SE_INC_BASE_PRIORITY_NAME
        SE_LOAD_DRIVER_NAME             SE_LOCK_MEMORY_NAME
        SE_MACHINE_ACCOUNT_NAME         SE_PROF_SINGLE_PROCESS_NAME
        SE_REMOTE_SHUTDOWN_NAME         SE_RESTORE_NAME
        SE_SECURITY_NAME                SE_SHUTDOWN_NAME
        SE_SYSTEMTIME_NAME              SE_SYSTEM_ENVIRONMENT_NAME
        SE_SYSTEM_PROFILE_NAME          SE_TAKE_OWNERSHIP_NAME
        SE_TCB_NAME                     SE_UNSOLICITED_INPUT_NAME

It can be difficult to successfully build this module in a way that makes these constants available. So some builds of this module may not make them available. For such builds, trying to export any of these constants will cause a fatal error. For this reason, none of these symbols are currently included in the ":ALL" grouping.

The Win32API:: heirarchy

This and the other Win32API:: modules are meant to expose the nearly raw API calls so they can be used from Perl code in any way they might be used from C code. This provides the following advantages:

Many modules can be written by people that don't have a C compiler.
Encourages more module code to be written in Perl [not C].

Perl code is often much easier to inspect, debug, customize, and enhance than XS code.

Allows those already familiar with the Win32 API to get off to a quick start.
Provides an interactive tool for exploring even obscure details of the Win32 API.

It can be very useful to interactively explore ad-hoc calls into parts of the Win32 API using:

    perl -de 0
Ensures that native Win32 data structures can be used.

This allows maximum efficiency. It also allows data from one module [for example, time or security information from the Win32API::Registry or Win32API::File modules] to be used with other modules [for example, Win32API::Time and Win32API::SecDesc].

Provides a single version of the XS interface to each API call where improvements can be collected.

Buffer sizes

For each parameter that specifies a buffer size, a value of 0 can be passed. For parameter that are pointers to buffer sizes, you can also pass in NULL by specifying an empty list reference, []. Both of these cases will ensure that the variable has some buffer space allocated to it and pass in that buffer's allocated size. Many of the calls indicate, via ERROR_MORE_DATA, that the buffer size was not sufficient and the Registry.xs code will automatically enlarge the buffer to the required size and repeat the call.

Numeric buffer sizes are used as minimum initial sizes for the buffers. The larger of this size and the size of space already allocated to the scalar will be passed to the underlying routine. If that size was insufficient, and the underlying call provides an easy method for determining the needed buffer size, then the buffer will be enlarged and the call repeated as above.

The underlying calls define buffer size parameter as unsigned, so negative buffer sizes are treated as very large positive buffer sizes which usually cause malloc() to fail.

To force the Registry.xs code to pass in a specific value for a buffer size, preceed the size with an equals sign via "=".. Buffer sizes that are passed in as strings starting with an equals sign will have the equal sign stripped and the remainder of the string interpretted as a number [via C's strtoul() using only base 10] which will be passed to the underlying routine [even if the allocated buffer is actually larger]. The Registry.xs code will enlarge the buffer to the specified size, if needed, but will not enlarge the buffer based on the underlying routine requesting more space.

Some Reg*() calls may not currently set the buffer size when they return ERROR_MORE_DATA. But some that are not documented as doing so, currently do so anyway. So the code assumes that any routine might do this and resizes any buffers and repeats the call. We hope that eventually all routines will provide this feature.

When you use [] for a buffer size, you can still find the length of the data returned by using length($buffer). Note that this length will be in bytes while a few of the buffer sizes would have been in units of wide characters.

Note that the RegQueryValueEx*() and RegEnumValue*() calls will trim the trailing '\0' [if present] from the returned data values of type REG_SZ or REG_EXPAND_SZ but only if the value data length parameter is omitted [or specified as []].

The RegSetValueEx*() calls will add a trailing '\0' [if missing] to the supplied data values of type REG_SZ and REG_EXPAND_SZ but only if the value data length parameter is omitted [or specified as 0].

Hungarian Notation

The following abbreviations are used at the start of each parameter name to hint at aspects of how the parameter is used. The prefix is always in lower case and followed by a capital letter that starts the descriptive part of the parameter name. Several of the following abbreviations can be combined into a single prefix.

Probably not all of these prefix notations are used by this module. This document section may be included in any Win32API module and so covers some notations not used by this specific module.

s

A string. In C, a '\0'-terminated char *. In Perl, just a string except that it will be truncated at the first "\0", if it contains one.

sw

A wide [UNICODE] string. In C, a L'\0'-terminated WCHAR *. In Perl, a string that contains UNICODE data. You can convert a string to UNICODE in Perl via:

    $string= "This is an example string";
    $unicode= pack( "S*", unpack("C*",$string), 0 );

Note how , 0 above causes an explicit L'\0' to be added since Perl's implicit '\0' that it puts after each of its strings is not wide enough to terminate a UNICODE string. So UNICODE strings are different than regular strings in that the Perl version of a regular string will not include the trialing '\0' while the Perl version of a UNICODE string must include the trailing L'\0'.

If a UNICODE string contains no non-ASCII characters, then you can convert it back into a normal string via:

    $string= pack( "C*", unpack("S*",$unicode) );
    $string =~ s/\0$//;
p

A pointer to some buffer [usually containing some struct]. In C, a void * or some other pointer type. In Perl, a string that is usually manipulated using pack and unpack. The "p" is usually followed by more prefix character(s) to indicate what type of data is stored in the bufffer.

a

A packed array. In C, an array [usually of structs]. In Perl, a string containing the packed data. The "a" is usually followed by more prefix character(s) to indicate the data type of the elements.

These packed arrays are also called "vectors" in places to avoid confusion with Perl arrays.

n

A generic number. In C, any of the integer or floating point data types. In Perl, a number; either an integer, unsigned, or double [IV, UV, or NV, respectively]. Usually an integer.

iv

A signed integral value. In C, any of the signed integer data types. In Perl, an integer [IV].

u

An unsigned integral value. In C, any of the unsigned integer data types. In Perl, an unsigned integer [UV].

d

A floating-point number. In C, a float or double or, perhaps, a long double. In Perl, a double-precision floating-point number [NV].

b

A Boolean value. In C, any integer data type, though usually via a type alias of bool or BOOL, containing either a 0 [false] or non-zero [true] value. In Perl, a scalar containing a Boolean value [0, "", or undef for "false" and anything else for "true"].

c

A count of items. In C, any integer data type. In Perl, an unsigned integer [UV]. Usually used in conjunction with a "vector" parameter [see a above] to indicate the number of elements.

l

A length [in bytes]. In C, any integer data type. In Perl, an unsigned integer [UV]. Usually used in conjunction with a "string" or "pointer" parameter [see s and p above] to indicate the buffer size or the size of the value stored in the buffer.

For strings, there is no general rule as to whether the trailing '\0' is included in such sizes. For this reason, the Win32API modules follow the Perl rule of always allocating one extra byte and reporting buffer sizes as being one smaller than allocated in case the '\0' is not included in the size.

lw

A length measured as number of UNICODE characters. In C, a count of WCHARs. In Perl, an unsigned integer [UV] counting "shorts" [see "s" and "S" in pack and unpack].

For UNICODE strings, the trailing L'\0' may or may not be included in a length so, again, we always allocate extra room for one and don't report that extra space.

h

A handle. In C, a HANDLE or more-specific handle data type. In Perl, an unsigned integer [UV]. In C, these handles are often actually some type of pointer, but Perl just treats them as opaque numbers, as it should. This prefix is also used for other pointers that are treated as integers in Perl code.

r

A record. In C, almost always a struct or perhaps union. Note that C structs are rarely passed by value so the "r" is almost always preceeded by a "p" or "a" [see p and a above]. For the very rare unadorned "r", Perl stores the record in the same way as a "pr", that is, in a string. For the very rare case where Perl explicitly stores a pointer to the struct rather than storing the struct directly in a Perl string, the prefix "pp" or "ppr" or even "par" is used.

sv
rv
hv
av
cv

A Perl data type. Respectively, a scalar value [SV], a reference [RV] [usually to a scalar], a hash [HV], a Perl array [AV], or a Perl code reference [PVCV]. For the "hv", "av", and "cv" prefixes, a leading "rv" is usually assumed. For a parameter to an XS subroutine, a prefix of "sv" means the parameter is a scalar and so may be a string or a number [or undef] or even both at the same time. So "sv" doesn't imply a leading "rv".

Input or Output

Whether a parameter is for input data, output data, or both is usually not reflected by the data type prefix. In cases where this is not obvious nor reflected in the parameter name proper, we may use the following in front of the data type prefix.

i

An input parameter given to the API [usually omitted].

o

An output-only parameter taken from the API. You should not get a warning if such a parameter is undef when you pass it into the function. You should get an error if such a parameter is read-only. You can [usually] pass in [] for such a parameter to have the parameter silently ignored.

The output may be written directly into the Perl variable passed to the subroutine, the same way the buffer parameter to Perl's sysread(). This method is often avoided in Perl because the call then lacks any visual cue that some parameters are being overwritten. But this method closely matches the C API which is what we are trying to do.

io

Input given to the API then overwritten with output taken from the API. You should get a warning [if -w is in effect] if such a parameter is undef when you pass it into the function [unless it is a buffer or buffer length parameter]. If the value is read-only, then [for most parameters] the output is silently not written. This is because it is often convenient to pass in read-only constants for many such parameters. You can also usually pass in [] for such parameters.

pp
ppr
par
pap

These are just unusual combinations of prefix characters described above.

For each, a pointer is stored in a [4-byte] Perl string. You can usually use unpack "P" to access the real data from Perl.

For "ppr" [and often for "pp"], the pointer points directly at a C struct. For "par", the pointer points to the first element of a C [packed] array of structs. For "pap", the pointer points to a C [packed] array of pointers to other things.

ap

Here we have a list of pointers packed into a single Perl string.

BUGS

The old ActiveState ports of Perl for Win32 [but not, ActivePerl, the ActiveState distributions of standard Perl 5.004 and beyond] do not support the tools for building extensions and so do not support this extension.

No routines are provided for using the data returned in the FILETIME buffers. Those are in the Win32API::Time module.

No routines are provided for dealing with UNICODE data effectively. See :FuncW above for some simple-minded UNICODE methods.

Parts of the module test will fail if used on a version of Perl that does not yet set $^E based on GetLastError().

On NT 4.0 [at least], the RegEnum*() calls do not set the required buffer sizes when returning ERROR_MORE_DATA so this module will not grow the buffers in such cases. Win32::TieRegistry overcomes this by using values from RegQueryInfoKey() for buffer sizes in RegEnum* calls.

On NT 4.0 [at least], RegQueryInfoKey() on HKEY_PERFORMANCE_DATA never succeeds. Also, RegQueryValueEx() on HKEY_PERFORMANCE_DATA never returns the required buffer size. To access HKEY_PERFORMANCE_DATA you will need to keep growing the data buffer until the call succeeds.

Because goto &subroutine seems to be buggy under Win32 Perl, it is not used in the stubs in Registry.pm.

AUTHOR

Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.

SEE ALSO

the Win32::TieRegistry manpage
the Win32::Registry manpage


XML::LibXML - Perl Binding for libxml2

  • SYNOPSIS
  • DESCRIPTION
  • VERSION INFORMATION
  • RELATED MODULES
  • XML::LIBXML AND XML::GDOME
  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML - Perl Binding for libxml2

SYNOPSIS

  $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
  $Version_ID = XML::LibXML::LIBXML_VERSION;
  $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
  $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
  $gdomenode = XML::LibXML->export_GDOME( $node, $deep );

DESCRIPTION

SYNOPSIS

  use XML::LibXML;
  my $parser = XML::LibXML->new();

  my $doc = $parser->parse_string(<<'EOT');
  <some-xml/>
  EOT

DESCRIPTION

This module is an interface to the gnome libxml2 DOM and SAX parser and the DOM tree. It also provides an XML::XPath-like findnodes() interface, providing access to the XPath API in libxml2. The module is split into several packages which are not described in this section.

For further information, please check the following documentation:

XML::LibXML::Parser

Parsing XML Files with XML::LibXML

XML::LibXML::DOM

XML::LibXML DOM Implementation

XML::LibXML::SAX

XML::LibXML direct SAX parser

XML::LibXML::Reader

Reading XML with a pull-parser

XML::LibXML::Document

XML::LibXML DOM Document Class

XML::LibXML::Node

Abstract Base Class of XML::LibXML Nodes

XML::LibXML::Element

XML::LibXML Class for Element Nodes

XML::LibXML::Text

XML::LibXML Class for Text Nodes

XML::LibXML::Comment

XML::LibXML Comment Nodes

XML::LibXML::CDATASection

XML::LibXML Class for CDATA Sections

XML::LibXML::Attr

XML::LibXML Attribute Class

XML::LibXML::DocumentFragment

XML::LibXML's DOM L2 Document Fragment Implementation

XML::LibXML::Namespace

XML::LibXML Namespace Implementation

XML::LibXML::PI

XML::LibXML Processing Instructions

XML::LibXML::Dtd

XML::LibXML DTD Support

XML::LibXML::RelaxNG

XML::LibXML frontend for RelaxNG schema validation

XML::LibXML::Schema

XML::LibXML frontend for W3C Schema schema validation

XML::LibXML::XPathContext

API for evaluating XPath expressions

XML::LibXMLguts

Internal of the Perl Layer for libxml2 (not done yet)

VERSION INFORMATION

Sometimes it is usefull to figure out, for which version XML::LibXML was compiled for. In most cases this is for debugging or to check if a given installation meets all functionality for the package. The functiones XML::LibXML::LIBXML_DOTTED_VERSION and XML::LibXML::LIBXML_VERSION provide this version information. Both functions simply pass through the values of the similar named macros of libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION returns the version of the (usually dynamically) linked libxml2.

XML::LibXML::LIBXML_DOTTED_VERSION
  $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;

Returns the version string of the libxml2 version XML::LibXML was compiled for. This will be "2.6.2" for "libxml2 2.6.2".

XML::LibXML::LIBXML_VERSION
  $Version_ID = XML::LibXML::LIBXML_VERSION;

Returns the version id of the libxml2 version XML::LibXML was compiled for. This will be "20602" for "libxml2 2.6.2". Don't mix this version id with $XML::LibXML::VERSION. The latter contains the version of XML::LibXML itself while the first contains the version of libxml2 XML::LibXML was compiled for.

XML::LibXML::LIBXML_RUNTIME_VERSION
  $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;

Returns a version string of the libxml2 which is (usually dynamically) linked by XML::LibXML. This will be "20602" for libxml2 released as "2.6.2" and something like "20602-CVS2032" for a CVS build of libxml2.

XML::LibXML issues a warning if the version of libxml2 dynamically linked to it is less than the version of libxml2 which it was compiled against.

RELATED MODULES

The modules described in this section are not part of the XML::LibXML package itself. As they support some additional features, they are mentioned here.

XML::LibXSLT

XSLT Processor using libxslt and XML::LibXML

XML::LibXML::Common

Common functions for XML::LibXML related Classes

XML::LibXML::Iterator

XML::LibXML Implementation of the DOM Traversal Specification

XML::LIBXML AND XML::GDOME

Note: THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL

Although both modules make use of libxml2's XML capabilities, the DOM implementation of both modules are not compatible. But still it is possible to exchange nodes from one DOM to the other. The concept of this exchange is pretty similar to the function cloneNode(): The particular node is copied on the lowlevel to the opposite DOM implementation.

Since the DOM implementations cannot coexist within one document, one is forced to copy each node that should be used. Because you are always keeping two nodes this may cause quite an impact on a machines memory usage.

XML::LibXML provides two functions to export or import GDOME nodes: import_GDOME() and export_GDOME(). Both function have two parameters: the node and a flag for recursive import. The flag works as in cloneNode().

The two functions allow to export and import XML::GDOME nodes explicitly, however, XML::LibXML allows also the transparent import of XML::GDOME nodes in functions such as appendChild(), insertAfter() and so on. While native nodes are automaticly adopted in most functions XML::GDOME nodes are always cloned in advance. Thus if the original node is modified after the operation, the node in the XML::LibXML document will not have this information.

import_GDOME
  $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );

This clones an XML::GDOME node to a XML::LibXML node explicitly.

export_GDOME
  $gdomenode = XML::LibXML->export_GDOME( $node, $deep );

Allows to clone an XML::LibXML node into a XML::GDOME node.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Attr - XML::LibXML Attribute Class

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Attr - XML::LibXML Attribute Class

SYNOPSIS

  $attr = XML::LibXML::Attr->new($name [,$value]);
  $string = $attr->getValue();
  $string = $attr->value;
  $attr->setValue( $string );
  $node = $attr->getOwnerElement();
  $attr->setNamespace($nsURI, $prefix);
  $bool = $attr->isId;
  $string = $attr->serializeContent;

DESCRIPTION

This is the interface to handle Attributes like ordinary nodes. The naming of the class relies on the W3C DOM documentation.

new
  $attr = XML::LibXML::Attr->new($name [,$value]);

Class constructor. If you need to work with iso encoded strings, you should always use the createAttrbute of XML::LibXML::Document.

getValue
  $string = $attr->getValue();

Returns the value stored for the attribute. If undef is returned, the attribute has no value, which is different of being not specified.

value
  $string = $attr->value;

Alias for getValue()

setValue
  $attr->setValue( $string );

This is needed to set a new attribute value. If iso encoded strings are passed as parameter, the node has to be bound to a document, otherwise the encoding might be done incorrectly.

getOwnerElement
  $node = $attr->getOwnerElement();

returns the node the attribute belongs to. If the attribute is not bound to a node, undef will be returned. Overwriting the underlying implementation, the parentNode function will return undef, instead of the owner element.

setNamespace
  $attr->setNamespace($nsURI, $prefix);

This function tries to bound the attribute to a given namespace. If $nsURI is undefined or empty, the function discards any previous association of the attribute with a namespace. If the namespace was not previously declared in the context of the attribute, this function will fail. In this case you may wish to call setNamespace() on the ownerElement. If the namespace URI is non-empty and declared in the context of the attribute, but only with a different (non-empty) prefix, then the attribute is still bound to the namespace but gets a different prefix than $prefix. The function also fails if the prefix is empty but the namespace URI is not (because unprefixed attributes should by definition belong to no namespace). This function returns 1 on success, 0 otherwise.

isId
  $bool = $attr->isId;

Determine whether an attribute is of type ID. For documents with a DTD, this information is only available if DTD loading/validation has been requested. For HTML documents parsed with the HTML parser ID detection is done automatically. In XML documents, all "xml:id" attributes are considered to be of type ID.

serializeContent($docencoding)
  $string = $attr->serializeContent;

This functin is not part of DOM API. It returns attribute content in the form in which it serializes into XML, that is with all meta-characters properly quoted and with raw entity references (except for entities expanded during parse time). Setting the optional $docencoding flag to 1 enforces document encoding for the output string (wich is then passed to Perl as a byte string). Otherwise the string is passed to Perl as (UTF-8 encododed) characters.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Boolean - Boolean true/false values

  • API
    • XML::LibXML::Boolean->True
    • XML::LibXML::Boolean->False
    • value()
    • to_literal()

NAME

XML::LibXML::Boolean - Boolean true/false values

DESCRIPTION

XML::LibXML::Boolean objects implement simple boolean true/false objects.

API

XML::LibXML::Boolean->True

Creates a new Boolean object with a true value.

XML::LibXML::Boolean->False

Creates a new Boolean object with a false value.

value()

Returns true or false.

to_literal()

Returns the string "true" or "false".


XML::LibXML::CDATASection - XML::LibXML Class for CDATA Sections

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::CDATASection - XML::LibXML Class for CDATA Sections

SYNOPSIS

  $node = XML::LibXML::CDATASection( $content );

DESCRIPTION

This class provides all functions of XML::LibXML::Text, but for CDATA nodes.

new
  $node = XML::LibXML::CDATASection( $content );

The constructor is the only provided function for this package. It is required, because libxml2 treats the different textnode types slightly differently.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Comment - XML::LibXML Comment Class

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Comment - XML::LibXML Comment Class

SYNOPSIS

  $node = XML::LibXML::Comment( $content );

DESCRIPTION

This class provides all functions of XML::LibXML::Text, but for comment nodes. This can be done, since only the output of the nodetypes is different, but not the datastructure. :-)

new
  $node = XML::LibXML::Comment( $content );

The constructor is the only provided function for this package. It is required, because libxml2 treats text nodes and comment nodes slightly differently.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Common - Routines and Constants common for XML::LibXML and XML::GDOME

    • encoding functions
    • encodeToUTF8
    • decodeFromUTF8
  • AUTHOR
  • COPYRIGHT
  • SEE ALSO

NAME

XML::LibXML::Common - Routines and Constants common for XML::LibXML and XML::GDOME

SYNOPSIS

  use XML::LibXML::Common;

DESCRIPTION

XML::LibXML and XML::GDOME share some of the same functionality. This package should bundle some shared constansts and functions, so both modules may coexist within the same scripts.

XML::LibXML::Common defines all node types as constants. While XML::LibXML and XML::GDOME originally declared their own node type definitions, one may want to use XML::LibXML::Common in its compatibility mode:

  • use XML::LibXML::Common qw(:libxml);

    :libxml will use the XML::LibXML Compatibility mode, which defines the old 'XML_' node-type definitions

  • use XML::LibXML::Common qw(:gdome);

    This allows one to use the XML::LibXML Compatibility mode, which defines the old 'GDOME_' node-type definitions

  • use XML::LibXML::Common qw(:w3c);

    This uses the nodetype definition names as specified for DOM.

  • use XML::LibXML::Common qw(:encoding);

    This is ment if only the encoding functions of XML::LibXML::Common should be used.

By default the W3 definitions as defined in the DOM specifications and the encoding functions are exported by XML::LibXML::Common.

encoding functions

To encode or decode a string to or from UTF-8 XML::LibXML::Common exports two functions, which use the encoding mechanism of the underlaying implementation. These functions should be used, if external encoding is required (e.g. for queryfunctions).

encodeToUTF8

    $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );

The function will encode a string from the specified encoding to UTF-8.

decodeFromUTF8

    $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );

This Function transforms an UTF-8 encoded string the specified encoding. While transforms to ISO encodings may cause errors if the given stirng contains unsupported characters, both functions can transform to UTF-16 encodings as well.

Note that both encoding functions report their errors on the standard error. If an error occours the function will croak(). To catch the error information it is required to call the encoding function from within an eval block to avoid a script to stop.

AUTHOR

Christian Glahn, (christian.glahn@uibk.ac.at) Innsbruck University

COPYRIGHT

(c) 2002 Christian Glahn. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

the perl manpage, the XML::LibXML manpage, the XML::GDOME manpage


XML::LibXML::DOM - XML::LibXML DOM Implementation

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::DOM - XML::LibXML DOM Implementation

DESCRIPTION

XML::LibXML provides an lightwight interface to modify a node of the document tree generated by the XML::LibXML parser. This interface follows as far as possible the DOM Level 3 specification. Additionally to the specified functions the XML::LibXML supports some functions that are more handy to use in the perl environment.

One also has to remember, that XML::LibXML is an interface to libxml2 nodes which actually reside on the C-Level of XML::LibXML. This means each node is a reference to a structure different than a perl hash or array. The only way to access these structure's values is through the DOM interface provided by XML::LibXML. This also means, that one can't simply inherit a XML::LibXML node and add new member variables as they were hash keys.

The DOM interface of XML::LibXML does not intend to implement a full DOM interface as it is done by XML::GDOME and used for full featured application. Moreover, it offers an simple way to build or modify documents that are created by XML::LibXML's parser.

Another target of the XML::LibXML interface is to make the interfaces of libxml2 available to the perl community. This includes also some workarounds to some features where libxml2 assumes more control over the C-Level that most perl users don't have.

One of the most important parts of the XML::LibXML DOM interface is, that the interfaces try do follow the DOM Level 3 specification rather strictly. This means the interface functions are named as the DOM specification says and not what widespread Java interfaces claim to be standard. Although there are several functions that have only a singular interface that conforms to the DOM spec XML::LibXML provides an additional Java style alias interface.

Also there are some function interfaces left over from early stages of XML::LibXML for compatibility reasons. These interfaces are for compatibility reasons only. They might disappear in one of the future versions of XML::LibXML, so a user is requested to switch over to the official functions.

More recent versions of perl (e.g. 5.6.1 or higher) support special flags to disinguish between UTF-8 and so called binary data. XML::LibXML provides for these versions functionality to make efficient use of these flags: If a document has set an encoding other than UTF-8 all strings that are not already in UTF-8 are implicitly encoded from the document encoding to UTF-8. On output these strings are commonly returned as UTF-8 unless a user does request explicitly the original (aka. document) encoding.

Older version of perl (such as 5.00503 or less) do not support these flags. If XML::LibXML is build for these versions, all strings have to get encoded to UTF-8 manualy before they are passed to any DOM functions.

NOTE: XML::LibXML's magic encoding may not work on all plattforms. Some platforms are known to have a broken iconv(), which is partly used by libxml2. To test if your platform works correctly with your language encoding, build a simple document in the particular encoding and try to parse it with XML::LibXML. If your document gets parsed with out causing any segmentation faults, bus errors or whatever your OS throws. An example for such a test can be found in test 19encoding.t of the distribution.

Namespaces and XML::LibXML's DOM implementation

XML::LibXML's DOM implementation is limitted by the DOM implementation of libxml2 which treats namespaces slightly differently than required by the DOM Level 2 specification.

According to the DOM Level 2 specification, namespaces of elements and attributes should be persistent, and nodes should be permanently bound to namespace URIs as they get created; it should be possible to manipulate the special attributes used for declaring XML namespaces just as other attributes without affecting the namespaces of other nodes. In DOM Level 2, the application is responsible for creating the special attributes consistently and/or for correct serialization of the document.

This is both unconvenient, causes problems in serialization of DOM to XML, and most importantly, seems almost impossible to implement over libxml2.

In libxml2, namespace URI and prefix of a node is provided by a pointer to a namespace declaration (appearing as a special xmlns attribute in the XML document). If the prefix or namespace URI of the declaration changes, the prefix and namespace URI of all nodes that point to it changes as well. Moreover, in contrast to DOM, a node (element or attribute) can only be bound to a namespace URI if there is some namespace declaration in the document to point to.

Therefore current DOM implementation in XML::LibXML tries to treat namespace declarations in a compromise between reason, common sense, limitations of libxml2, and the DOM Level 2 specification.

In XML::LibXML, special attributes declaring XML namespaces are often created automatically, usually when a namespaced node is attached to a document and no existing declaration of the namespace and prefix is in the scope to be reused. In this respect, XML::LibXML DOM implementation differs from the DOM Level 2 specification according to which special attributes for declaring the appropriate XML namespaces should not be added when a node with a namespace prefix and namespace URI is created.

Namespace declarations are also created when XML::LibXML::Document's createElementNS() or createAttributeNS() function are used. If the a namespace is not declared on the documentElement, the namespace will be localy declared for the newly created node. In case of Attributes this may look a bit confusing, since these nodes cannot have namespace declarations itself. In this case the namespace is internally applied to the attribute and later declared on the node the attribute is appended to (if required).

The following example may explain this a bit:

   my $doc = XML::LibXML->createDocument;
   my $root = $doc->createElementNS( "", "foo" );
   $doc->setDocumentElement( $root );

   my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
   $root->setAttributeNodeNS( $attr );

This piece of code will result in the following document:

   <?xml version="1.0"?>
   <foo xmlns:bar="bar" bar:foo="test"/>

The namespace is declared on the document element during the setAttributeNodeNS() call.

Namespaces can be also declared explicitly by the use of XML::LibXML:Element's setNamespace() function. Since 1.61, they can also be manipulated with functions setNamespaceDeclPrefix() and setNamespaceDeclURI() (not available in DOM). Changing an URI or prefix of an existing namespace declaration affects the namespace URI and prefix of all nodes which point to it (that is the nodes in its scope).

It is also important to repeat the specification: While working with namespaces you should use the namespace aware functions instead of the simplified versions. For example you should never use setAttribute() but setAttributeNS().

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Document - XML::LibXML DOM Document Class

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Document - XML::LibXML DOM Document Class

SYNOPSIS

  $dom = XML::LibXML::Document->new( $version, $encoding );
  $dom = XML::LibXML::Document->createDocument( $version, $encoding );
  $strEncoding = $doc->encoding();
  $doc->setEncoding($new_encoding);
  $strVersion = $doc->version();
  $doc->standalone
  $doc->setStandalone($numvalue);
  my $compression = $doc->compression;
  $doc->setCompression($ziplevel);
  $docstring = $dom->toString($format);
  $c14nstr = $doc->toStringC14N($comment_flag,$xpath);
  $str = $doc->serialze($format);
  $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
  $state = $doc->toFile($filename, $format);
  $state = $doc->toFH($fh, $format);
  $str = $document->toStringHTML();
  $str = $document->serialize_html();
  $bool = $dom->is_valid();
  $dom->validate();
  $root = $dom->documentElement();
  $dom->setDocumentElement( $root );
  $element = $dom->createElement( $nodename );
  $element = $dom->createElementNS( $namespaceURI, $qname );
  $text = $dom->createTextNode( $content_text );
  $comment = $dom->createComment( $comment_text );
  $attrnode = $doc->createAttribute($name [,$value]);
  $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
  $fragment = $doc->createDocumentFragment();
  $cdata = $dom->create( $cdata_content );
  my $pi = $doc->createProcessingInstruction( $target, $data );
  my $entref = $doc->createEntityReference($refname);
  $dtd = $document->createInternalSubset( $rootnode, $public, $system);
  $dtd = $document->createExternalSubset( $rootnode, $public, $system);
  $document->importNode( $node );
  $document->adoptNode( $node );
  my $dtd = $doc->externalSubset;
  my $dtd = $doc->internalSubset;
  $doc->setExternalSubset($dtd);
  $doc->setInternalSubset($dtd);
  my $dtd = $doc->removeExternalSubset();
  my $dtd = $doc->removeInternalSubset();
  my @nodelist = $doc->getElementsByTagName($tagname);
  my @nodelist = $doc->getElementsByTagName($nsURI,$tagname);
  my @nodelist = $doc->getElementsByLocalName($localname);
  my $node = $doc->getElementById($id);
  $dom->indexElements();

DESCRIPTION

The Document Class is in most cases the result of a parsing process. But sometimes it is necessary to create a Document from scratch. The DOM Document Class provides functions that conform to the DOM Core naming style.

It inherits all functions from XML::LibXML::Node as specified in the DOM specification. This enables access to the nodes besides the root element on document level - a DTD for example. The support for these nodes is limited at the moment.

While generaly nodes are bound to a document in the DOM concept it is suggested that one should always create a node not bound to any document. There is no need of really including the node to the document, but once the node is bound to a document, it is quite safe that all strings have the correct encoding. If an unbound textnode with an iso encoded string is created (e.g. with $CLASS->new()), the toString function may not return the expected result.

All this seems like a limitation as long as UTF-8 encoding is assured. If iso encoded strings come into play it is much safer to use the node creation functions of XML::LibXML::Document.

new
  $dom = XML::LibXML::Document->new( $version, $encoding );

alias for createDocument()

createDocument
  $dom = XML::LibXML::Document->createDocument( $version, $encoding );

The constructor for the document class. As Parameter it takes the version string and (optionally) the encoding string. Simply calling createDocument() will create the document:

  <?xml version="your version" encoding="your encoding"?>

Both parameter are optional. The default value for $version is 1.0, of course. If the $encoding parameter is not set, the encoding will be left unset, which means UTF-8 is implied.

The call of createDocument() without any parameter will result the following code:

  <?xml version="1.0"?>

Alternatively one can call this constructor directly from the XML::LibXML class level, to avoid some typing. This will not have any effect on the class instance, which is always XML::LibXML::Document.

   my $document = XML::LibXML->createDocument( "1.0", "UTF-8" );

is therefore a shortcut for

  my $document = XML::LibXML::Document->createDocument( "1.0", "UTF-8" );
encoding
  $strEncoding = $doc->encoding();

returns the encoding string of the document.

  my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
  print $doc->encoding; # prints ISO-8859-15

Optionally this function can be accessed by actualEncoding or getEncoding.

setEncoding
  $doc->setEncoding($new_encoding);

From time to time it is useful to change the effective encoding of a document. This method provides the interface to manipulate the encoding of a document.

Note that this function has to be used very carefully, since you can't simply convert one encoding in any other, since some (or even all) characters may not exist in the new encoding. XML::LibXML will not test if the operation is allowed or possible for the given document. The only switching assured to work is to UTF-8.

version
  $strVersion = $doc->version();

returns the version string of the document

getVersion() is an alternative form of this function.

standalone
  $doc->standalone

This function returns the Numerical value of a documents XML declarations standalone attribute. It returns 1 if standalone="yes" was found, 0 if standalone="no" was found and -1 if standalone was not specified (default on creation).

setStandalone
  $doc->setStandalone($numvalue);

Through this method it is possible to alter the value of a documents standalone attribute. Set it to 1 to set standalone="yes", to 0 to set standalone="no" or set it to -1 to remove the standalone attribute from the XML declaration.

compression
  my $compression = $doc->compression;

libxml2 allows reading of documents directly from gziped files. In this case the compression variable is set to the compression level of that file (0-8). If XML::LibXML parsed a different source or the file wasn't compressed, the returned value will be -1.

setCompression
  $doc->setCompression($ziplevel);

If one intends to write the document directly to a file, it is possible to set the compression level for a given document. This level can be in the range from 0 to 8. If XML::LibXML should not try to compress use -1 (default).

Note that this feature will only work if libxml2 is compiled with zlib support and toFile() is used for output.

toString
  $docstring = $dom->toString($format);

toString is a deparsing function, so the DOM Tree can be translated into a string, ready for output.

The optional $format parameter sets the indenting of the output. This parameter is expected to be an integer value, that specifies that indentation should be used. The format parameter can have three different values if it is used:

If $format is 0, than the document is dumped as it was originally parsed

If $format is 1, libxml2 will add ignorable whitespaces, so the nodes content is easier to read. Existing text nodes will not be altered

If $format is 2 (or higher), libxml2 will act as $format == 1 but it add a leading and a trailing linebreak to each text node.

libxml2 uses a hardcoded indentation of 2 space characters per indentation level. This value can not be altered on runtime.

NOTE: XML::LibXML::Document::toString returns the data in the document encoding rather than UTF-8! If you want UTF-8 ecoded XML, you have to change the conding by using setEncoding()

toStringC14N

$c14nstr = $doc->toStringC14N($comment_flag,$xpath); A variation to toString, that returns the canonized form of the given document.

serialize
  $str = $doc->serialze($format);

Alternative form of toString(). This function name added to be more conformant with libxml2's examples.

serialize_c14n
  $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);

Alternative form of toStringC14N().

toFile
  $state = $doc->toFile($filename, $format);

This function is similar to toString(), but it writes the document directly into a filesystem. This function is very useful, if one needs to store large documents.

The format parameter has the same behaviour as in toString().

toFH
  $state = $doc->toFH($fh, $format);

This function is similar to toString(), but it writes the document directly to a filehandler or a stream.

The format parameter has the same behaviour as in toString().

toStringHTML
  $str = $document->toStringHTML();

toStringHTML deparses the tree to a string as HTML. With this method indenting is automatic and managed by libxml2 internally.

serialize_html
  $str = $document->serialize_html();

Alternative form of toStringHTML().

is_valid
  $bool = $dom->is_valid();

Returns either TRUE or FALSE depending on whether the DOM Tree is a valid Document or not.

You may also pass in a XML::LibXML::Dtd object, to validate against an external DTD:

   if (!$dom->is_valid($dtd)) {
       warn("document is not valid!");
   }
validate
  $dom->validate();

This is an exception throwing equivalent of is_valid. If the document is not valid it will throw an exception containing the error. This allows you much better error reporting than simply is_valid or not.

Again, you may pass in a DTD object

documentElement
  $root = $dom->documentElement();

Returns the root element of the Document. A document can have just one root element to contain the documents data.

Optionaly one can use getDocumentElement.

setDocumentElement
  $dom->setDocumentElement( $root );

This function enables you to set the root element for a document. The function supports the import of a node from a different document tree.

createElement
  $element = $dom->createElement( $nodename );

This function creates a new Element Node bound to the DOM with the name $nodename.

createElementNS
  $element = $dom->createElementNS( $namespaceURI, $qname );

This function creates a new Element Node bound to the DOM with the name $nodename and placed in the given namespace.

createTextNode
  $text = $dom->createTextNode( $content_text );

As an equivalent of createElement, but it creates a Text Node bound to the DOM.

createComment
  $comment = $dom->createComment( $comment_text );

As an equivalent of createElement, but it creates a Comment Node bound to the DOM.

createAttribute
  $attrnode = $doc->createAttribute($name [,$value]);

Creates a new Attribute node.

createAttributeNS
  $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );

Creates an Attribute bound to a namespace.

createDocumentFragment
  $fragment = $doc->createDocumentFragment();

This function creates a DocumentFragment.

createCDATASection
  $cdata = $dom->create( $cdata_content );

Similar to createTextNode and createComment, this function creates a CDataSection bound to the current DOM.

createProcessingInstruction
  my $pi = $doc->createProcessingInstruction( $target, $data );

create a processing instruction node.

Since this method is quite long one may use its short form createPI().

createEntityReference
  my $entref = $doc->createEntityReference($refname);

If a document has a DTD specified, one can create entity references by using this function. If one wants to add a entity reference to the document, this reference has to be created by this function.

An entity reference is unique to a document and cannot be passed to other documents as other nodes can be passed.

NOTE: A text content containing something that looks like an entity reference, will not be expanded to a real entity reference unless it is a predefined entity

   my $string = "&foo;";
   $some_element->appendText( $string );
   print $some_element->textContent; # prints "&amp;foo;"
createInternalSubset
  $dtd = $document->createInternalSubset( $rootnode, $public, $system);

This function creates and adds an internal subset to the given document. Because the function automaticly adds the DTD to the document there is no need to add the created node explicitly to the document.

   my $document = XML::LibXML::Document->new();
   my $dtd      = $document->createInternalSubset( "foo", undef, "foo.dtd" );

will result in the following XML document:

  <?xml version="1.0"?>
   <!DOCTYPE foo SYSTEM "foo.dtd">

By setting the public parameter it is possible to set PUBLIC dtds to a given document. So

  my $document = XML::LibXML::Document->new();
  my $dtd      = $document->createInternalSubset( "foo", "-//FOO//DTD FOO 0.1//EN", undef );

will cause the following declaration to be created on the document:

  <?xml version="1.0"?>
  <!DOCTYPE foo PUBLIC "-//FOO//DTD FOO 0.1//EN">
createExternalSubset
  $dtd = $document->createExternalSubset( $rootnode, $public, $system);

This function is similar to createInternalSubset() but this DTD is considered to be external and is therefore not added to the document itself. Nevertheless it can be used for validation purposes.

importNode
  $document->importNode( $node );

If a node is not part of a document, it can be imported to another document. As specified in DOM Level 2 Specification the Node will not be altered or removed from its original document ($node->cloneNode(1) will get called implicitly).

NOTE: Don't try to use importNode() to import subtrees that contain an entity reference - even if the entity reference is the root node of the subtree. This will cause serious problems to your program. This is a limitation of libxml2 and not of XML::LibXML itself.

adoptNode
  $document->adoptNode( $node );

If a node is not part of a document, it can be imported to another document. As specified in DOM Level 3 Specification the Node will not be altered but it will removed from its original document.

After a document adopted a node, the node, its attributes and all its descendants belong to the new document. Because the node does not belong to the old document, it will be unlinked from its old location first.

NOTE: Don't try to adoptNode() to import subtrees that contain entity references - even if the entity reference is the root node of the subtree. This will cause serious problems to your program. This is a limitation of libxml2 and not of XML::LibXML itself.

externalSubset
  my $dtd = $doc->externalSubset;

If a document has an external subset defined it will be returned by this function.

NOTE Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in XML::LibXML is still limited. In particular one may not want use common node function on doctype declaration nodes!

internalSubset
  my $dtd = $doc->internalSubset;

If a document has an internal subset defined it will be returned by this function.

NOTE Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in XML::LibXML is still limited. In particular one may not want use common node function on doctype declaration nodes!

setExternalSubset
  $doc->setExternalSubset($dtd);

EXPERIMENTAL!

This method sets a DTD node as an external subset of the given document.

setInternalSubset
  $doc->setInternalSubset($dtd);

EXPERIMENTAL!

This method sets a DTD node as an internal subset of the given document.

removeExternalSubset
  my $dtd = $doc->removeExternalSubset();

EXPERIMENTAL!

If a document has an external subset defined it can be removed from the document by using this function. The removed dtd node will be returned.

removeInternalSubset
  my $dtd = $doc->removeInternalSubset();

EXPERIMENTAL!

If a document has an internal subset defined it can be removed from the document by using this function. The removed dtd node will be returned.

getElementsByTagName
  my @nodelist = $doc->getElementsByTagName($tagname);

Implements the DOM Level 2 function

In SCALAR context this function returns a XML::LibXML::NodeList object.

getElementsByTagNameNS
  my @nodelist = $doc->getElementsByTagName($nsURI,$tagname);

Implements the DOM Level 2 function

In SCALAR context this function returns a XML::LibXML::NodeList object.

getElementsByLocalName
  my @nodelist = $doc->getElementsByLocalName($localname);

This allows the fetching of all nodes from a given document with the given Localname.

In SCALAR context this function returns a XML::LibXML::NodeList object.

getElementById
  my $node = $doc->getElementById($id);

Returns the element that has an ID attribute with the given value. If no such element exists, this returns undef.

Note: the ID of an element may change while manipulating the document. For documents with a DTD, the information about ID attributes is only available if DTD loading/validation has been requested. For HTML documents parsed with the HTML parser ID detection is done automatically. In XML documents, all "xml:id" attributes are considered to be of type ID. You can test ID-ness of an attribute node with $attr->isId().

In versions 1.59 and earlier this method was called getElementsById() (plural) by mistake. Starting from 1.60 this name is maintained as an alias only for backward compatibility.

indexElements
  $dom->indexElements();

This function causes libxml2 to stamp all elements in a document with their document position index which considerably speeds up XPath queries for large documents. It should only be used with static documents that won't be further changed by any DOM methods, because once a document is indexed, XPath will always prefer the index to other methods of determining the document order of nodes. XPath could therefore return improperly ordered node-lists when applied on a document that has been changed after being indexed. It is of course possible to use this method to re-index a modified document before using it with XPath again. This function is not a part of the DOM specification.

This function returns number of elements indexed, -1 if error occurred, or -2 if this feature is not available in the running libxml2.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::DocumentFragment - XML::LibXML's DOM L2 Document Fragment Implementation

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::DocumentFragment - XML::LibXML's DOM L2 Document Fragment Implementation

This class is a helper class as described in the DOM Level 2 Specification. It is implemented as a node without name. All adding, inserting or replacing functions are aware of document fragments now.

As well all unbound nodes (all nodes that do not belong to any document subtree) are implicit members of document fragments.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Dtd - XML::LibXML DTD Handling

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Dtd - XML::LibXML DTD Handling

SYNOPSIS

  $dtd = XML::LibXML::Dtd->new($public_id, $system_id);
  $dtd = XML::LibXML::Dtd->parse_string($dtd_str);
  $publicId = $dtd->getName();
  $publicId = $dtd->publicId();
  $systemId = $dtd->systemId();

DESCRIPTION

This class holds a DTD. You may parse a DTD from either a string, or from an external SYSTEM identifier.

No support is available as yet for parsing from a filehandle.

XML::LibXML::Dtd is a sub-class of Node, so all the methods available to nodes (particularly toString()) are available to Dtd objects.

new
  $dtd = XML::LibXML::Dtd->new($public_id, $system_id);

Parse a DTD from the system identifier, and return a DTD object that you can pass to $doc->is_valid() or $doc->validate().

   my $dtd = XML::LibXML::Dtd->new(
                        "SOME // Public / ID / 1.0",
                        "test.dtd"
                                  );
   my $doc = XML::LibXML->new->parse_file("test.xml");
   $doc->validate($dtd);
parse_string
  $dtd = XML::LibXML::Dtd->parse_string($dtd_str);

The same as new() above, except you can parse a DTD from a string. Note that parsing from string may fail if the DTD contains external parametric-entity references with relative URLs.

getName
  $publicId = $dtd->getName();

Returns the name of DTD; i.e., the name immediately following the DOCTYPE keyword.

publicId
  $publicId = $dtd->publicId();

Returns the public identifier of the external subset.

systemId
  $systemId = $dtd->systemId();

Returns the system identifier of the external subset.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Element - XML::LibXML Class for Element Nodes

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Element - XML::LibXML Class for Element Nodes

SYNOPSIS

  $node = XML::LibXML::Element->new( $name );
  $node->setAttribute( $aname, $avalue );
  $node->setAttributeNS( $nsURI, $aname, $avalue );
  $avalue = $node->getAttribute( $aname );
  $avalue = $node->setAttributeNS( $nsURI, $aname );
  $attrnode = $node->getAttributeNode( $aname );
  $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
  $node->removeAttribute( $aname );
  $node->removeAttributeNS( $nsURI, $aname );
  $boolean = $node->hasAttribute( $aname );
  $boolean = $node->hasAttributeNS( $nsURI, $aname );
  @nodes = $node->getChildrenByTagName($tagname);
  @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
  @nodes = $node->getChildrenByLocalName($localname);
  @nodes = $node->getElementsByTagName($tagname);
  @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
  @nodes = $node->getElementsByLocalName($localname);
  $node->appendWellBalancedChunk( $chunk );
  $node->appendText( $PCDATA );
  $node->appendTextNode( $PCDATA );
  $node->appendTextChild( $childname , $PCDATA );
  $node->setNamespace( $nsURI , $nsPrefix, $activate );
  $node->setNamespaceDeclURI( $nsPrefix, $newURI );
  $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );

DESCRIPTION

new
  $node = XML::LibXML::Element->new( $name );

This function creates a new node unbound to any DOM.

setAttribute
  $node->setAttribute( $aname, $avalue );

This method sets or replaces the node's attribute $aname to the value $avalue

setAttributeNS
  $node->setAttributeNS( $nsURI, $aname, $avalue );

Namespace-aware version of setAttribute, where $nsURI is a namespace URI, $aname is a qualified name, and $avalue is the value. The namespace URI may be null (empty or undefined) in order to create an attribute which has no namespace.

The current implementation differs from DOM in the following aspectse

If an attribute with the same local name and namespace URI already exists on the element, but its prefix differs from the prefix of $aname, then this function is supposed to change the prefix (regardless of namespace declarations and possible collisions). However, the current implementation does rather the opposite. If a prefix is declared for the namespace URI in the scope of the attribute, then the already declared prefix is used, disregarding the prefix specified in $aname. If no prefix is declared for the namespace, the function tries to declare the prefix specified in $aname and dies if the prefix is already taken by some other namespace.

According to DOM Level 2 specification, this method can also be used to create or modify special attributes used for declaring XML namespaces (which belong to the namespace "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns"). This should work since version 1.61, but again the implementation differs from DOM specification in the following: if a declaration of the same namespace prefix already exists on the element, then changing its value via this method automatically changes the namespace of all elements and attributes in its scope. This is because in libxml2 the namespace URI of an element is not static but is computed from a pointer to a namespace declaration attribute.

getAttribute
  $avalue = $node->getAttribute( $aname );

If $node has an attribute with the name $aname, the value of this attribute will get returned.

getAttributeNS
  $avalue = $node->setAttributeNS( $nsURI, $aname );

Retrieves an attribute value by local name and namespace URI.

getAttributeNode
  $attrnode = $node->getAttributeNode( $aname );

Retrieve an attribute node by name. If no attribute with a given name exists, undef is returned.

getAttributeNodeNS
  $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );

Retrieves an attribute node by local name and namespace URI. If no attribute with a given localname and namespace exists, undef is returned.

removeAttribute
  $node->removeAttribute( $aname );

The method removes the attribute $aname from the node's attribute list, if the attribute can be found.

removeAttributeNS
  $node->removeAttributeNS( $nsURI, $aname );

Namespace version of removeAttribute

hasAttribute
  $boolean = $node->hasAttribute( $aname );

This funcion tests if the named attribute is set for the node. If the attribute is specified, TRUE (1) will be returned, otherwise the returnvalue is FALSE (0).

hasAttributeNS
  $boolean = $node->hasAttributeNS( $nsURI, $aname );

namespace version of hasAttribute

getChildrenByTagName
  @nodes = $node->getChildrenByTagName($tagname);

The function gives direct access to all child elements of the current node with a given tagname, where tagname is a qualified name, that is, in case of namespace usage it may consist of a prefix and local name. This function makes things a lot easier if one needs to handle big datasets. A special tagname '*' can be used to match any name.

If this function is called in SCALAR context, it returns the number of elements found.

getChildrenByTagNameNS
  @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);

Namespace version of getChildrenByTagName. A special nsURI '*' matches any namespace URI, in which case the function behaves just like getChildrenByLocalName.

If this function is called in SCALAR context, it returns the number of elements found.

getChildrenByLocalName
  @nodes = $node->getChildrenByLocalName($localname);

The function gives direct access to all child elements of the current node with a given local name. It makes things a lot easier if one needs to handle big datasets. A special localname '*' can be used to match any local name.

If this function is called in SCALAR context, it returns the number of elements found.

getElementsByTagName
  @nodes = $node->getElementsByTagName($tagname);

This function is part of the spec. It fetches all descendants of a node with a given tagname, where tagname is a qualified name, that is, in case of namespace usage it may consist of a prefix and local name. A special tagname '*' can be used to match any tag name.

In SCALAR context this function returns a XML::LibXML::NodeList object.

getElementsByTagNameNS
  @nodes = $node->getElementsByTagNameNS($nsURI,$localname);

Namespace version of getElementsByTagName as found in the DOM spec. A special localname '*' can be used to match any local name and nsURI '*' can be used to match any namespace URI.

In SCALAR context this function returns a XML::LibXML::NodeList object.

getElementsByLocalName
  @nodes = $node->getElementsByLocalName($localname);

This function is not found in the DOM specification. It is a mix of getElementsByTagName and getElementsByTagNameNS. It will fetch all tags matching the given local-name. This alows one to select tags with the same local name across namespace borders.

In SCALAR context this function returns a XML::LibXML::NodeList object.

appendWellBalancedChunk
  $node->appendWellBalancedChunk( $chunk );

Sometimes it is nessecary to append a string coded XML Tree to a node. appendWellBalancedChunk will do the trick for you. But this is only done if the String is well-balanced.

Note that appendWellBalancedChunk() is only left for compatibility reasons. Implicitly it uses

   my $fragment = $parser->parse_xml_chunk( $chunk );
   $node->appendChild( $fragment );

This form is more explicit and makes it easier to control the flow of a script.

appendText
  $node->appendText( $PCDATA );

alias for appendTextNode().

appendTextNode
  $node->appendTextNode( $PCDATA );

This wrapper function lets you add a string directly to an element node.

appendTextChild
  $node->appendTextChild( $childname , $PCDATA );

Somewhat similar with appendTextNode: It lets you set an Element, that contains only a text node directly by specifying the name and the text content.

setNamespace
  $node->setNamespace( $nsURI , $nsPrefix, $activate );

setNamespace() allows one to apply a namespace to an element. The function takes three parameters: 1. the namespace URI, which is required and the two optional values prefix, which is the namespace prefix, as it should be used in child elements or attributes as well as the additional activate parameter. If prefix is not given, undefined or empty, this function tries to create a declaration of the default namespace.

The activate parameter is most useful: If this parameter is set to FALSE (0), a new namespace declaration is simply added to the element while the element's namespace itself is not altered. Nevertheless, activate is set to TRUE (1) on default. In this case the namespace is used as the node's effective namespace. This means the namespace prefix is added to the node name and if there was a namespace already active for the node, it will be replaced (but its declaration is not removed from the document). A new namespace declaration is only created if necessary (that is, if the element is already in the scope of a namespace declaration associating the prefix with the namespace URI, then this declaration is reused).

The following example may clarify this:

   my $e1 = $doc->createElement("bar");
   $e1->setNamespace("http://foobar.org", "foo")

results

   <foo:bar xmlns:foo="http://foobar.org"/>;

while

   my $e2 = $doc->createElement("bar");
   $e2->setNamespace("http://foobar.org", "foo",0)

results only

   <bar xmlns:foo="http://foobar.org"/>;

By using $activate == 0 it is possible to create multiple namepace declarations on a single element.

The function fails if it is required to create a declaration associating the prefix with the namespace URI but the element already carries a declaration with the same prefix but different namespace URI.

setNamespaceDeclURI
  $node->setNamespaceDeclURI( $nsPrefix, $newURI );

EXPERIMENTAL IN 1.61 !

This function manipulates directly with an existing namespace declaration on an element. It takes two parameters: the prefix by which it looks up the namespace declaration and a new namespace URI which replaces its previous value.

It returns 1 if the namespace declaration was found and changed, 0 otherwise.

All elements and attributes (even those previously unbound from the document) for which the namespace declaration determines their namespace belong to the new namespace after the change.

If the new URI is undef or empty, the nodes have no namespace and no prefix after the change. Namespace declarations once nulled in this way do not further appear in the serialized output (but do remain in the document for internal integrity of libxml2 data structures).

This function is NOT part of any DOM API.

setNamespaceDeclPrefix
  $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );

EXPERIMENTAL IN 1.61 !

This function manipulates directly with an existing namespace declaration on an element. It takes two parameters: the old prefix by which it looks up the namespace declaration and a new prefix which is to replace the old one.

The function dies with an error if the element is in the scope of another declaration whose prefix equals to the new prefix, or if the change should result in a declaration with a non-empty prefix but empty namespace URI. Otherwise, it returns 1 if the namespace declaration was found and changed and 0 if not found.

All elements and attributes (even those previously unbound from the document) for which the namespace declaration determines their namespace change their prefix to the new value.

If the new prefix is undef or empty, the namespace declaration becomes a declaration of a default namespace. The corresponding nodes drop their namespace prefix (but remain in the, now default, namespace). In this case the function fails, if the containig element is in the scope of another default namespace declaration.

This function is NOT part of any DOM API.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks

    • How does XML::LibXML::InputCallback work?
    • Using XML::LibXML::InputCallback
    • What about the old callback system prior to XML::LibXML::InputCallback?
  • INTERFACE DESCRIPTION
    • Global Variables
    • Global Callbacks
    • Class methods
  • EXAMPLE CALLBACKS
  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks

SYNOPSIS

  my $input_callbacks = XML::LibXML::InputCallback->new();
  $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
                                         $read_cb1, $close_cb1 ] );
  $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
                                         $read_cb2, $close_cb2 ] );
  $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
                                          $read_cb3, $close_cb3 ] );

  $parser->input_callbacks( $input_callbacks );
  $parser->parse_file( $some_xml_file );

DESCRIPTION

You may get unexpected results if you are trying to load external documents during libxml2 parsing if the location of the ressource is not a HTTP, FTP or relative location but a absolute path for example. To get around this limitation, you may add your own input handler to open, read and close particular types of locations or URI classes. Using this input callback handlers, you can handle your own custom URI schemes for example.

The input callbacks are used whenever LibXML has to get something other than externally parsed entities from somewhere. They are implemented using a callback stack on the Perl layer in analogy to libxml2's native callback stack.

The XML::LibXML::InputCallback class transparently registers the input callbacks for the libxml2's parser processes.

How does XML::LibXML::InputCallback work?

The libxml2 library offers a callback implementation as global functions only. To work-around the troubles resulting in having only global callbacks - for example, if the same global callback stack is manipulated by different applications running together in a single Apache Webserver environment -, XML::LibXML::InputCallback comes with a object-oriented and a function-oriented part.

Using the function-oriented part the global callback stack of libxml2 can be manipulated. Those functions can be used as interface to the callbacks on the C- and XS Layer. At the object-oriented part, operations for working with the "pseudo-localized" callback stack are implemented. Currently, you can register and de-register callbacks on the Perl layer and initialize them on a per parser basis.

Using XML::LibXML::InputCallback

After object instantiation using the parameter-less constructor, you can register callback groups.

  my $input_callbacks = XML::LibXML::InputCallback->new();
  $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
                                         $read_cb1, $close_cb1 ] );
  $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
                                         $read_cb2, $close_cb2 ] );
  $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
                                          $read_cb3, $close_cb3 ] );

  $parser->input_callbacks( $input_callbacks );
  $parser->parse_file( $some_xml_file );

What about the old callback system prior to XML::LibXML::InputCallback?

In XML::LibXML versions prior to 1.59 - i.e. without the XML::LibXML::InputCallback module - you could define your callbacks either using globally or locally. You still can do that using XML::LibXML::InputCallback, and in addition to that you can define the callbacks on a per parser basis!

If you use the old callback interface through global callbacks, XML::LibXML::InputCallback will treat them with a lower priority as the ones registered using the new interface. The global callbacks will not override the callback groups registered using the new interface. Local callbacks are attached to a specific parser instance, therefore they are treated with highest priority. If the match callback of the callback group registered as local variable is identical to one of the callback groups registered using the new interface, that callback group will be replaced.

Users of the old callback implementation whose open callback returned a plain string, will have to adapt their code to return a reference to that string after upgrading to version >= 1.59. The new callback system can only deal with the open callback returning a reference!

INTERFACE DESCRIPTION

Global Variables

$_CUR_CB

Stores the current callback and can be used as shortcut to access the callback stack.

@_GLOBAL_CALLBACKS

Stores all callback groups for the current parser process.

@_CB_STACK

Stores the currently used callback group. Used to prevent parser errors when dealing with nested XML data.

Global Callbacks

_callback_match

Implements the interface for the match callback at C-level and for the selection of the callback group from the callbacks defined at the Perl-level.

_callback_open

Forwards the open callback from libxml2 to the corresponding callback function at the Perl-level.

_callback_read

Forwards the read request to the corresponding callback function at the Perl-level and returns the result to libxml2.

_callback_close

Forwards the close callback from libxml2 to the corresponding callback function at the Perl-level..

Class methods

new()

A simple constructor.

register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])

The four callbacks have to be given as array reference in the above order match, open, read, close!

unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])

With no arguments given, unregister_callbacks() will delete the last registered callback group from the stack. If four callbacks are passed as array reference, the callback group to unregister will be identified by the match callback and deleted from the callback stack. Note that if several identical match callbacks are defined in different callback groups, ALL of them will be deleted from the stack.

init_callbacks()

Initializes the callback system before a parsing process.

cleanup_callbacks()

Resets global variables and the libxml2 callback stack.

lib_init_callbacks()

Used internally for callback registration at C-level.

lib_cleanup_callbacks()

Used internally for callback resetting at the C-level.

EXAMPLE CALLBACKS

The following example is a purely fictitious example that uses a MyScheme::Handler object that responds to methods similar to an IO::Handle.

       # Define the four callback functions
       sub match_uri {
      my $uri = shift;
      return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs
       }

       sub open_uri {
      my $uri = shift;
      my $handler = MyScheme::Handler->new($uri);
      return $handler;
       }

       # The returned $buffer will be parsed by the libxml2 parser
       sub read_uri {
      my $handler = shift;
      my $length = shift;
      my $buffer;
      read($handler, $buffer, $length);
      return $buffer; # $buffer will be an empty string '' if read() is done
       }

       # Close the handle associated with the resource.
       sub close_uri {
      my $handler = shift;
      close($handler);
       }

       # Register them with a instance of XML::LibXML::InputCallback
       my $input_callbacks = XML::LibXML::InputCallback->new();
       $input_callbacks->register_callbacks([ \&match_uri, \&open_uri,
                                         \&read_uri, \&close_uri ] );

       # Register the callback group at a parser instance
       $parser->input_callbacks( $input_callbacks );

       # $some_xml_file will be parsed using our callbacks
       $parser->parse_file( $some_xml_file );

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Literal - Simple string values.

  • API
    • new($string)
    • value()
    • cmp($literal)

NAME

XML::LibXML::Literal - Simple string values.

DESCRIPTION

In XPath terms a Literal is what we know as a string.

API

new($string)

Create a new Literal object with the value in $string. Note that &quot; and &apos; will be converted to " and ' respectively. That is not part of the XPath specification, but I consider it useful. Note though that you have to go to extraordinary lengths in an XML template file (be it XSLT or whatever) to make use of this:

        <xsl:value-of select="&quot;I'm feeling &amp;quot;sad&amp;quot;&quot;"/>

Which produces a Literal of:

        I'm feeling "sad"

value()

Also overloaded as stringification, simply returns the literal string value.

cmp($literal)

Returns the equivalent of perl's cmp operator against the given $literal.


XML::LibXML::Namespace - XML::LibXML Namespace Implementation

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Namespace - XML::LibXML Namespace Implementation

SYNOPSIS

  my $ns = XML::LibXML::Namespace->new($nsURI);
  print $ns->getName();
  print $ns->name();
  print $ns->prefix();
  $localname = $ns->getLocalName();
  print $ns->getData();
  print $ns->getValue();
  print $ns->value();
  print $ns->uri();
  $known_uri = $ns->getNamespaceURI();
  $known_prefix = $ns->getPrefix();

DESCRIPTION

Namespace nodes are returned by both $element->findnodes('namespace::foo') or by $node->getNamespaces().

The namespace node API is not part of any current DOM API, and so it is quite minimal. It should be noted that namespace nodes are not a sub class of XML::LibXML::Node, however Namespace nodes act a lot like attribute nodes, and similarly named methods will return what you would expect if you treated the namespace node as an attribute.

new
  my $ns = XML::LibXML::Namespace->new($nsURI);

Creates a new Namespace node. Note that this is not a 'node' as an attribute or an element node. Therefore you can't do call all XML::LibXML::Node Functions. All functions available for this node are listed below.

Optionally you can pass the prefix to the namespace constructor. If this second parameter is omitted you will create a so called default namespace. Note, the newly created namespace is not bound to any docuement or node, therefore you should not expect it to be available in an existing document.

getName
  print $ns->getName();

Returns "xmlns:prefix", where prefix is the prefix for this namespace.

name
  print $ns->name();

Alias for getName()

prefix
  print $ns->prefix();

Returns the prefix bound to this namespace declaration.

getLocalName
  $localname = $ns->getLocalName();

Alias for prefix()

getData
  print $ns->getData();

Returns the URI of the namespace.

getValue
  print $ns->getValue();

Alias for getData()

value
  print $ns->value();

Alias for getData()

uri
  print $ns->uri();

Alias for getData()

getNamespaceURI
  $known_uri = $ns->getNamespaceURI();

Returns the string "http://www.w3.org/2000/xmlns/"

getPrefix
  $known_prefix = $ns->getPrefix();

Returns the string "xmlns"

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Node - Abstract Base Class of XML::LibXML Nodes

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Node - Abstract Base Class of XML::LibXML Nodes

SYNOPSIS

  $name = $node->nodeName;
  $node->setNodeName( $newName );
  $bool = $node->isSameNode( $other_node );
  $bool = $node->isEqual( $other_node );
  $content = $node->nodeValue;
  $content = $node->textContent;
  $type = $node->nodeType;
  $node->unbindNode();
  $childnode = $node->removeChild( $childnode );
  $oldnode = $node->replaceChild( $newNode, $oldNode );
  $node->replaceNode($newNode);
  $childnode = $node->appendChild( $childnode );
  $childnode = $node->addChild( $chilnode );
  $node = $parent->addNewChild( $nsURI, $name );
  $node->addSibling($newNode);
  $newnode =$node->cloneNode( $deep );
  $parentnode = $node->parentNode;
  $nextnode = $node->nextSibling();
  $prevnode = $node->previousSibling();
  $boolean = $node->hasChildNodes();
  $childnode = $node->firstChild;
  $childnode = $node->lastChild;
  $documentnode = $node->ownerDocument;
  $node = $node->getOwner;
  $node->setOwnerDocument( $doc );
  $node->insertBefore( $newNode, $refNode );
  $node->insertAfter( $newNode, $refNode );
  @nodes = $node->findnodes( $xpath_expression );
  $result = $node->find( $xpath );
  print $node->findvalue( $xpath );
  @childnodes = $node->childNodes;
  $xmlstring = $node->toString($format,$docencoding);
  $c14nstring = $node->toStringC14N($with_comments, $xpath_expression);
  $str = $doc->serialze($format);
  $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
  $localname = $node->localname;
  $nameprefix = $node->prefix;
  $uri = $node->namespaceURI();
  $boolean = $node->hasAttributes();
  @attributelist = $node->attributes();
  $URI = $node->lookupNamespaceURI( $prefix );
  $prefix = $node->lookupNamespacePrefix( $URI );
  $iter = $node->iterator;
  $node->normalize;
  @nslist = $node->getNamespaces;
  $node->removeChildNodes();
  $node->nodePath();
  $lineno = $node->line_number();

DESCRIPTION

XML::LibXML::Node defines functions that are common to all Node Types. A LibXML::Node should never be created standalone, but as an instance of a high level class such as LibXML::Element or LibXML::Text. The class itself should provide only common functionality. In XML::LibXML each node is part either of a document or a document-fragment. Because of this there is no node without a parent. This may causes confusion with "unbound" nodes.

nodeName
  $name = $node->nodeName;

Returns the node's name. This function is aware of namespaces and returns the full name of the current node (prefix:localname).

Since 1.62 this function also returns the correct DOM names for node types with constant names, namely: #text, #cdata-section, #comment, #document, #document-fragment.

setNodeName
  $node->setNodeName( $newName );

In very limited situations, it is useful to change a nodes name. In the DOM specification this should throw an error. This Function is aware of namespaces.

isSameNode
  $bool = $node->isSameNode( $other_node );

returns TRUE (1) if the given nodes refer to the same node structure, otherwise FALSE (0) is returned.

isEqual
  $bool = $node->isEqual( $other_node );

deprecated version of isSameNode().

NOTE isEqual will change behaviour to follow the DOM specification

nodeValue
  $content = $node->nodeValue;

If the node has any content (such as stored in a text node) it can get requested through this function.

NOTE: Element Nodes have no content per definition. To get the text value of an Element use textContent() instead!

textContent
  $content = $node->textContent;

this function returns the content of all text nodes in the descendants of the given node as spacified in DOM.

nodeType
  $type = $node->nodeType;

Retrun the node's type. The possible types are described in the libxml2 tree.h documentation. The return value of this function is a numeric value. Therefore it differs from the result of perl ref function.

unbindNode
  $node->unbindNode();

Unbinds the Node from its siblings and Parent, but not from the Document it belongs to. If the node is not inserted into the DOM afterwards it will be lost after the programm terminated. From a low level view, the unbound node is stripped from the context it is and inserted into a (hidden) document-fragment.

removeChild
  $childnode = $node->removeChild( $childnode );

This will unbind the Child Node from its parent $node. The function returns the unbound node. If oldNode is not a child of the given Node the function will fail.

replaceChild
  $oldnode = $node->replaceChild( $newNode, $oldNode );

Replaces the $oldNode with the $newNode. The $oldNode will be unbound from the Node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.

replaceNode
  $node->replaceNode($newNode);

This function is very similar to replaceChild(), but it replaces the node itself rather than a childnode. This is useful if a node found by any XPath function, should be replaced.

appendChild
  $childnode = $node->appendChild( $childnode );

The function will add the $childnode to the end of $node's children. The function should fail, if the new childnode is allready a child of $node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first.

addChild
  $childnode = $node->addChild( $chilnode );

As an alternative to appendChild() one can use the addChild() function. This function is a bit faster, because it avoids all DOM conformity checks. Therefore this function is quite useful if one builds XML documents in memory where the order and ownership (ownerDocument) is assured.

addChild() uses libxml2's own xmlAddChild() function. Thus it has to be used with extra care: If a text node is added to a node and the node itself or its last childnode is as well a text node, the node to add will be merged with the one already available. The current node will be removed from memory after this action. Because perl is not aware of this action, the perl instance is still available. XML::LibXML will catch the loss of a node and refuse to run any function called on that node.

   my $t1 = $doc->createTextNode( "foo" );
   my $t2 = $doc->createTextNode( "bar" );
   $t1->addChild( $t2 );       # is ok
   my $val = $t2->nodeValue(); # will fail, script dies

Also addChild() will not check it the added node belongs to the same document as the node it will be added to. This could lead to inconsistent documents and in more worse cases even to memory violations, if one does not keep track of this issue.

Although this sounds like a lot of trouble, addChild() is useful if a document is built from a stream, such as happens sometimes in SAX handlers or filters.

If you are not sure about the source of your nodes, you better stay with appendChild(), because this function is more user friendly in the sense of being more error tolerant.

addNewChild
  $node = $parent->addNewChild( $nsURI, $name );

Similar to addChild(), this function uses low level libxml2 functionality to provide faster interface for DOM building. addNewChild() uses xmlNewChild() to create a new node on a given parent element.

addNewChild() has two parameters $nsURI and $name, where $nsURI is an (optional) namespace URI. $name is the fully qualified element name; addNewChild() will determine the correct prefix if nessecary.

The function returns the newly created node.

This function is very useful for DOM building, where a created node can be directly associated with its parent. NOTE this function is not part of the DOM specification and its use will limit your code to XML::LibXML.

addSibling
  $node->addSibling($newNode);

addSibling() allows adding an additional node to the end of a nodelist, defined by the given node.

cloneNode
  $newnode =$node->cloneNode( $deep );

cloneNode creates a copy of $node. When $deep is set to 1 (true) the function will copy all childnodes as well. If $deep is 0 only the current node will be copied. Note that in case of element, attributes are copied iven if $deep is 0.

Note that the behavior of this function for $deep=0 has changed in 1.62 in order to be consistent with the DOM spec (in older versions attributes and namespace information was not copied for elements).

parentNode
  $parentnode = $node->parentNode;

Returns simply the Parent Node of the current node.

nextSibling
  $nextnode = $node->nextSibling();

Returns the next sibling if any .

previousSibling
  $prevnode = $node->previousSibling();

Analogous to getNextSibling the function returns the previous sibling if any.

hasChildNodes
  $boolean = $node->hasChildNodes();

If the current node has Childnodes this function returns TRUE (1), otherwise it returns FALSE (0, not undef).

firstChild
  $childnode = $node->firstChild;

If a node has childnodes this function will return the first node in the childlist.

lastChild
  $childnode = $node->lastChild;

If the $node has childnodes this function returns the last child node.

ownerDocument
  $documentnode = $node->ownerDocument;

Through this function it is always possible to access the document the current node is bound to.

getOwner
  $node = $node->getOwner;

This function returns the node the current node is associated with. In most cases this will be a document node or a document fragment node.

setOwnerDocument
  $node->setOwnerDocument( $doc );

This function binds a node to another DOM. This method unbinds the node first, if it is allready bound to another document.

This function is the oposite calling of XML::LibXML::Document's adoptNode() function. Because of this it has the same limitations with Entity References as adoptNode().

insertBefore
  $node->insertBefore( $newNode, $refNode );

The method inserts $newNode before $refNode. If $refNode is undefined, the newNode will be set as the new last child of the parent node. This function differs from the DOM L2 specification, in the case, if the new node is not part of the document, the node will be imported first, automatically.

$refNode has to be passed to the function even if it is undefined:

   $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
   $node->insertBefore( $newNode ); # wrong

Note, that the reference node has to be a direct child of the node the function is called on. Also, $newChild is not allowed to be an ancestor of the new parent node.

insertAfter
  $node->insertAfter( $newNode, $refNode );

The method inserts $newNode after $refNode. If $refNode is undefined, the newNode will be set as the new last child of the parent node.

Note, that $refNode has to be passed explicitly even if it is undef.

findnodes
  @nodes = $node->findnodes( $xpath_expression );

findnodes evaluates the xpath expression (XPath 1.0) on the current node and returns the resulting node set as an array. In scalar context returns a XML::LibXML::NodeList object.

NOTE ON NAMESPACES AND XPATH:

A common mistake about XPath is to assume that node tests consisting of an element name with no prefix match elements in the default namespace. This assumption is wrong - by XPath specification, such node tests can only match elements that are in no (i.e. null) namespace.

So, for example, one cannot match the root element of an XHTML document with $node->find('/html') since '/html' would only match if the root element <html> had no namespace, but all XHTML elements belong to the namespace http://www.w3.org/1999/xhtml. (Note that xmlns="..." namespace declarations can also be specified in a DTD, which makes the situation even worse, since the XML document looks as if there was no default namespace).

There are several possible ways to deal with namespaces in XPath:

  • The recommended way is to use the XML::LibXML::XPathContext module to define an explicit context for XPath evaluation, in which a document independent prefix-to-namespace mapping can be defined. For example:

      my $xpc = XML::LibXML::XPathContext->new;
  $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
  $xpc->find('/x:html',$node);

  • Another possibility is to use prefixes declared in the queried document (if known). If the document declares a prefix for the namespace in question (and the context node is in the scope of the declaration), XML::LibXML allows you to use the prefix in the XPath expression, e.g.:

      $node->find('/x:html');

See also XML::LibXML::XPathContext->findnodes.

find
  $result = $node->find( $xpath );

find evaluates the XPath 1.0 expression using the current node as the context of the expression, and returns the result depending on what type of result the XPath expression had. For example, the XPath "1 * 3 + 52" results in a XML::LibXML::Number object being returned. Other expressions might return a XML::LibXML::Boolean object, or a XML::LibXML::Literal object (a string). Each of those objects uses Perl's overload feature to "do the right thing" in different contexts.

See also XML::LibXML::XPathContext->find.

findvalue
  print $node->findvalue( $xpath );

findvalue is exactly equivalent to:

   $node->find( $xpath )->to_literal;

That is, it returns the literal value of the results. This enables you to ensure that you get a string back from your search, allowing certain shortcuts. This could be used as the equivalent of XSLT's <xsl:value-of select="some_xpath"/>.

See also XML::LibXML::XPathContext->findvalue.

childNodes
  @childnodes = $node->childNodes;

getChildnodes implements a more intuitive interface to the childnodes of the current node. It enables you to pass all children directly to a map or grep. If this function is called in scalar context, a XML::LibXML::NodeList object will be returned.

toString
  $xmlstring = $node->toString($format,$docencoding);

This is the equivalent to XML::LibXML::Document::toString for a single node. This means a node and all its childnodes will be dumped into the result string.

Additionally to the $format flag of XML::LibXML::Document, this version accepts the optional $docencoding flag. If this flag is set this function returns the string in its original encoding (the encoding of the document) rather than UTF-8.

toStringC14N
  $c14nstring = $node->toStringC14N($with_comments, $xpath_expression);

The function is similar to toString(). Instead of simply serializing the document tree, it transforms it as it is specified in the XML-C14N Specification. Such transformation is known as canonization.

If $with_comments is 0 or not defined, the result-document will not contain any comments that exist in the original document. To include comments into the canonized document, $with_comments has to be set to 1.

The parameter $xpath_expression defines the nodeset of nodes that should be visible in the resulting document. This can be used to filter out some nodes. One has to note, that only the nodes that are part of the nodeset, will be included into the result-document. Their child-nodes will not exist in the resulting document, unless they are part of the nodeset defined by the xpath expression.

If $xpath_expression is ommitted or empty, toStringC14N() will include all nodes in the given sub-tree.

No serializing flags will be recognized by this function!

serialize
  $str = $doc->serialze($format);

Alternative form of toString(). This function name added to be more conform with libxml2's examples.

serialize_c14n
  $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);

Alternative form of toStringC14N().

localname
  $localname = $node->localname;

Returns the local name of a tag. This is the part behind the colon.

prefix
  $nameprefix = $node->prefix;

Returns the prefix of a tag. This is the part before the colon.

namespaceURI
  $uri = $node->namespaceURI();

returns the URI of the current namespace.

hasAttributes
  $boolean = $node->hasAttributes();

returns 1 (TRUE) if the current node has any attributes set, otherwise 0 (FALSE) is returned.

attributes
  @attributelist = $node->attributes();

This function returns all attributes and namespace declarations assigned to the given node.

Because XML::LibXML does not implement namespace declarations and attributes the same way, it is required to test what kind of node is handled while accessing the functions result.

If this function is called in array context the attribute nodes are returned as an array. In scalar context the function will return a XML::LibXML::NamedNodeMap object.

lookupNamespaceURI
  $URI = $node->lookupNamespaceURI( $prefix );

Find a namespace URI by its prefix starting at the current node.

lookupNamespacePrefix
  $prefix = $node->lookupNamespacePrefix( $URI );

Find a namespace prefix by its URI starting at the current node.

NOTE Only the namespace URIs are meant to be unique. The prefix is only document related. Also the document might have more than a single prefix defined for a namespace.

iterator
  $iter = $node->iterator;

This function is deprecated since XML::LibXML 1.54. It is only a dummy function that will get removed entirely in one of the next versions.

To make use of iterator functions use XML::LibXML::Iterator Module available on CPAN.

normalize
  $node->normalize;

This function normalizes adjacent textnodes. This function is not as strict as libxml2's xmlTextMerge() function, since it will not free a node that is still referenced by the perl layer.

getNamespaces
  @nslist = $node->getNamespaces;

If a node has any namespaces defined, this function will return these namespaces. Note, that this will not return all namespaces that are in scope, but only the ones declared explicitly for that node.

Although getNamespaces is available for all nodes, it only makes sense if used with element nodes.

removeChildNodes
  $node->removeChildNodes();

This function is not specified for any DOM level: It removes all childnodes from a node in a single step. Other than the libxml2 function itself (xmlFreeNodeList), this function will not immediately remove the nodes from the memory. This saves one from getting memory violations, if there are nodes still referred to from the Perl level.

nodePath
  $node->nodePath();

This function is not specified for any DOM level: It returns a cannonical structure based XPath for a given node.

line_number
  $lineno = $node->line_number();

This function returns the line number where the tag was found during parsing. If a node is added to the document the line number is 0. Problems may occour, if a node from one document is passed to another one.

Note: line_number() is special to XML::LibXML and not part of the DOM specification.

If the line_numbers flag of the parser was not activated before parsing, line_number() will always return 0.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::NodeList - a list of XML document nodes

  • API
    • new()
    • get_nodelist()
    • string_value()
    • to_literal()
    • get_node($pos)
    • size()
    • pop()
    • push(@nodes)
    • append($nodelist)
    • shift()
    • unshift(@nodes)
    • prepend($nodeset)
    • iterator()

NAME

XML::LibXML::NodeList - a list of XML document nodes

DESCRIPTION

An XML::LibXML::NodeList object contains an ordered list of nodes, as detailed by the W3C DOM documentation of Node Lists.

SYNOPSIS

  my $results = $dom->findnodes('//somepath');
  foreach my $context ($results->get_nodelist) {
    my $newresults = $context->findnodes('./other/element');
    ...
  }

API

new()

You will almost never have to create a new NodeSet object, as it is all done for you by XPath.

get_nodelist()

Returns a list of nodes, the contents of the node list, as a perl list.

string_value()

Returns the string-value of the first node in the list. See the XPath specification for what "string-value" means.

to_literal()

Returns the concatenation of all the string-values of all the nodes in the list.

get_node($pos)

Returns the node at $pos. The node position in XPath is based at 1, not 0.

size()

Returns the number of nodes in the NodeSet.

pop()

Equivalent to perl's pop function.

push(@nodes)

Equivalent to perl's push function.

append($nodelist)

Given a nodelist, appends the list of nodes in $nodelist to the end of the current list.

shift()

Equivalent to perl's shift function.

unshift(@nodes)

Equivalent to perl's unshift function.

prepend($nodeset)

Given a nodelist, prepends the list of nodes in $nodelist to the front of the current list.

iterator()

Will return a new nodelist iterator for the current nodelist. A nodelist iterator is usefull if more complex nodelist processing is needed.


XML::LibXML::Number - Simple numeric values.

  • API
    • new($num)
    • value()

NAME

XML::LibXML::Number - Simple numeric values.

DESCRIPTION

This class holds simple numeric values. It doesn't support -0, +/- Infinity, or NaN, as the XPath spec says it should, but I'm not hurting anyone I don't think.

API

new($num)

Creates a new XML::LibXML::Number object, with the value in $num. Does some rudimentary numeric checking on $num to ensure it actually is a number.

value()

Also as overloaded stringification. Returns the numeric value held.


XML::LibXML::PI - XML::LibXML Processing Instructions

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::PI - XML::LibXML Processing Instructions

SYNOPSIS

  $pinode->setData( $data_string );
  $pinode->setData( name=>string_value [...] );

DESCRIPTION

Processing instructions are implemented with XML::LibXML with read and write access. The PI data is the PI without the PI target (as specified in XML 1.0 [17]) as a string. This string can be accessed with getData as implemented in XML::LibXML::Node.

The write access is aware about the fact, that many processing instructions have attribute like data. Therefore setData() provides besides the DOM spec conform Interface to pass a set of named parameter. So the code segment

  my $pi = $dom->createProcessingInstruction("abc");
  $pi->setData(foo=>'bar', foobar=>'foobar');
  $dom->appendChild( $pi );

will result the following PI in the DOM:

  <?abc foo="bar" foobar="foobar"?>

Which is how it is specified in the DOM specification. This three step interface creates temporary a node in perl space. This can be avoided while using the insertProcessingInstruction() method. Instead of the three calls described above, the call

  $dom->insertProcessingInstruction("abc",'foo="bar" foobar="foobar"');

will have the same result as above.

XML::LibXML::PI's implementation of setData() differs a bit from the the standard version as available in XML::LibXML::Node():

setData
  $pinode->setData( $data_string );
  $pinode->setData( name=>string_value [...] );

This method allows to change the content data of a PI. Additionaly to the interface specified for DOM Level2, the method provides a named parameter interface to set the data. This parameterlist is converted into a string before it is appended to the PI.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Parser - Parsing XML Data with XML::LibXML

  • SYNOPSIS
  • PARSING
    • Creating a Parser Instance
    • DOM Parser
    • Push Parser
    • DOM based SAX Parser
  • SERIALIZATION
  • PARSER OPTIONS
  • ERROR REPORTING
  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Parser - Parsing XML Data with XML::LibXML

SYNOPSIS

  $parser = XML::LibXML->new();
  $doc = $parser->parse_file( $xmlfilename );
  $doc = $parser->parse_fh( $io_fh );
  $doc = $parser->parse_string( $xmlstring);
  $doc = $parser->parse_html_file( $htmlfile, \%opts );
  $doc = $parser->parse_html_fh( $io_fh, \%opts );
  $doc = $parser->parse_html_string( $htmlstring, \%opts );
  $fragment = $parser->parse_balanced_chunk( $wbxmlstring );
  $fragment = $parser->parse_xml_chunk( $wbxmlstring );
  $parser->process_xincludes( $doc );
  $parser->processXIncludes( $doc );
  $parser->parse_chunk($string, $terminate);
  $parser->start_push();
  $parser->push(@data);
  $doc = $parser->finish_push( $recover );
  $parser->validation(1);
  $parser->recover(1);
  $parser->recover_silently(1);
  $parser->expand_entities(0);
  $parser->keep_blanks(0);
  $parser->pedantic_parser(1);
  $parser->line_numbers(1);
  $parser->load_ext_dtd(1);
  $parser->complete_attributes(1);
  $parser->expand_xinclude(1);
  $parser->load_catalog( $catalog_file );
  $parser->base_uri( $your_base_uri );
  $parser->gdome_dom(1);
  $parser->clean_namespaces( 1 );

DESCRIPTION

SYNOPSIS

  use XML::LibXML;
  my $parser = XML::LibXML->new();

  my $doc = $parser->parse_string(<<'EOT');
  <some-xml/>
  EOT
  my $fdoc = $parser->parse_file( $xmlfile );

  my $fhdoc = $parser->parse_fh( $xmlstream );

  my $fragment = $parser->parse_xml_chunk( $xml_wb_chunk );

PARSING

A XML document is read into a datastructure such as a DOM tree by a piece of software, called a parser. XML::LibXML currently provides four diffrent parser interfaces:

  • A DOM Pull-Parser

  • A DOM Push-Parser

  • A SAX Parser

  • A DOM based SAX Parser.

Creating a Parser Instance

XML::LibXML provides an OO interface to the libxml2 parser functions. Thus you have to create a parser instance before you can parse any XML data.

new
  $parser = XML::LibXML->new();

There is nothing much to say about the constructor. It simply creates a new parser instance.

Although libxml2 uses mainly global flags to alter the behaviour of the parser, each XML::LibXML parser instance has its own flags or callbacks and does not interfere with other instances.

DOM Parser

One of the common parser interfaces of XML::LibXML is the DOM parser. This parser reads XML data into a DOM like datastructure, so each tag can get accessed and transformed.

XML::LibXML's DOM parser is not only capable to parse XML data, but also (strict) HTML files. There are three ways to parse documents - as a string, as a Perl filehandle, or as a filename/URL. The return value from each is a XML::LibXML::Document object, which is a DOM object.

All of the functions listed below will throw an exception if the document is invalid. To prevent this causing your program exiting, wrap the call in an eval{} block

parse_file
  $doc = $parser->parse_file( $xmlfilename );

This function parses an XML document from a file or network; $xmlfilename can be either a filename or an URL. Note that for parsing files, this function is the fastest choice, about 6-8 times faster then parse_fh().

parse_fh
  $doc = $parser->parse_fh( $io_fh );

parse_fh() parses a IOREF or a subclass of IO::Handle.

Because the data comes from an open handle, libxml2's parser does not know about the base URI of the document. To set the base URI one should use parse_fh() as follows:

  my $doc = $parser->parse_fh( $io_fh, $baseuri );
parse_string
  $doc = $parser->parse_string( $xmlstring);

This function is similar to parse_fh(), but it parses a XML document that is available as a single string in memory. Again, you can pass an optional base URI to the function.

  my $doc = $parser->parse_string( $xmlstring, $baseuri );
parse_html_file
  $doc = $parser->parse_html_file( $htmlfile, \%opts );

Similar to parse_file() but parses HTML (strict) documents; $htmlfile can be filename or URL.

An optional second argument can be used to pass some options to the HTML parser as a HASH reference. Possible options are: Possible options are: encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally: recover, suppress_errors, suppress_warnings, pedantic_parser, no_blanks, and no_network.

parse_html_fh
  $doc = $parser->parse_html_fh( $io_fh, \%opts );

Similar to parse_fh() but parses HTML (strict) streams.

An optional second argument can be used to pass some options to the HTML parser as a HASH reference. Possible options are: encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally: recover, suppress_errors, suppress_warnings, pedantic_parser, no_blanks, and no_network. Note: encoding option may not work correctly with this function in libxml2 < 2.6.27 if the HTML file declares charset using a META tag.

parse_html_string
  $doc = $parser->parse_html_string( $htmlstring, \%opts );

Similar to parse_string() but parses HTML (strict) strings.

An optional second argument can be used to pass some options to the HTML parser as a HASH reference. Possible options are: encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally: recover, suppress_errors, suppress_warnings, pedantic_parser, no_blanks, and no_network.

Parsing HTML may cause problems, especially if the ampersand ('&') is used. This is a common problem if HTML code is parsed that contains links to CGI-scripts. Such links cause the parser to throw errors. In such cases libxml2 still parses the entire document as there was no error, but the error causes XML::LibXML to stop the parsing process. However, the document is not lost. Such HTML documents should be parsed using the recover flag. By default recovering is deactivated.

The functions described above are implemented to parse well formed documents. In some cases a program gets well balanced XML instead of well formed documents (e.g. a XML fragment from a Database). With XML::LibXML it is not required to wrap such fragments in the code, because XML::LibXML is capable even to parse well balanced XML fragments.

parse_balanced_chunk
  $fragment = $parser->parse_balanced_chunk( $wbxmlstring );

This function parses a well balanced XML string into a XML::LibXML::DocumentFragment.

parse_xml_chunk
  $fragment = $parser->parse_xml_chunk( $wbxmlstring );

This is the old name of parse_balanced_chunk(). Because it may causes confusion with the push parser interface, this function should be used anymore.

By default XML::LibXML does not process XInclude tags within a XML Document (see options section below). XML::LibXML allows to post process a document to expand XInclude tags.

process_xincludes
  $parser->process_xincludes( $doc );

After a document is parsed into a DOM structure, you may want to expand the documents XInclude tags. This function processes the given document structure and expands all XInclude tags (or throws an error) by using the flags and callbacks of the given parser instance.

Note that the resulting Tree contains some extra nodes (of type XML_XINCLUDE_START and XML_XINCLUDE_END) after successfully processing the document. These nodes indicate where data was included into the original tree. if the document is serialized, these extra nodes will not show up.

Remember: A Document with processed XIncludes differs from the original document after serialization, because the original XInclude tags will not get restored!

If the parser flag "expand_xincludes" is set to 1, you need not to post process the parsed document.

processXIncludes
  $parser->processXIncludes( $doc );

This is an alias to process_xincludes, but through a JAVA like function name.

Push Parser

XML::LibXML provides a push parser interface. Rather than pulling the data from a given source the push parser waits for the data to be pushed into it.

This allows one to parse large documents without waiting for the parser to finish. The interface is especially useful if a program needs to preprocess the incoming pieces of XML (e.g. to detect document boundaries).

While XML::LibXML parse_*() functions force the data to be a wellformed XML, the push parser will take any arbitrary string that contains some XML data. The only requirement is that all the pushed strings are together a well formed document. With the push parser interface a programm can interrupt the parsing process as required, where the parse_*() functions give not enough flexibility.

Different to the pull parser implemented in parse_fh() or parse_file(), the push parser is not able to find out about the documents end itself. Thus the calling program needs to indicate explicitly when the parsing is done.

In XML::LibXML this is done by a single function:

parse_chunk
  $parser->parse_chunk($string, $terminate);

parse_chunk() tries to parse a given chunk of data, which isn't nessecarily well balanced data. The function takes two parameters: The chunk of data as a string and optional a termination flag. If the termination flag is set to a true value (e.g. 1), the parsing will be stopped and the resulting document will be returned as the following exable describes:

  my $parser = XML::LibXML->new;
  for my $string ( "<", "foo", ' bar="hello worls"', "/>") {
       $parser->parse_chunk( $string );
  }
  my $doc = $parser->parse_chunk("", 1); # terminate the parsing

Internally XML::LibXML provides three functions that control the push parser process:

start_push
  $parser->start_push();

Initializes the push parser.

push
  $parser->push(@data);

This function pushes the data stored inside the array to libxml2's parser. Each entry in @data must be a normal scalar!

finish_push
  $doc = $parser->finish_push( $recover );

This function returns the result of the parsing process. If this function is called without a parameter it will complain about non wellformed documents. If $restore is 1, the push parser can be used to restore broken or non well formed (XML) documents as the following example shows:

  eval {
      $parser->push( "<foo>", "bar" );
      $doc = $parser->finish_push();    # will report broken XML
  };
  if ( $@ ) {
     # ...
  }

This can be annoying if the closing tag is missed by accident. The following code will restore the document:

  eval {
      $parser->push( "<foo>", "bar" );
      $doc = $parser->finish_push(1);   # will return the data parsed
                                        # unless an error happened
  };

  print $doc->toString(); # returns "<foo>bar</foo>"

Of course finish_push() will return nothing if there was no data pushed to the parser before.

DOM based SAX Parser

XML::LibXML provides a DOM based SAX parser. The SAX parser is defined in XML::LibXML::SAX::Parser. As it is not a stream based parser, it parses documents into a DOM and traverses the DOM tree instead.

The API of this parser is exactly the same as any other Perl SAX2 parser. See XML::SAX::Intro for details.

Aside from the regular parsing methods, you can access the DOM tree traverser directly, using the generate() method:

  my $doc = build_yourself_a_document();
  my $saxparser = $XML::LibXML::SAX::Parser->new( ... );
  $parser->generate( $doc );

This is useful for serializing DOM trees, for example that you might have done prior processing on, or that you have as a result of XSLT processing.

WARNING

This is NOT a streaming SAX parser. As I said above, this parser reads the entire document into a DOM and serialises it. Some people couldn't read that in the paragraph above so I've added this warning.

If you want a streaming SAX parser look at the XML::LibXML::SAX man page

SERIALIZATION

XML::LibXML provides some functions to serialize nodes and documents. The serialization functions are described on the XML::LibXML::Node manpage or the XML::LibXML::Document manpage. XML::LibXML checks three global flags that alter the serialization process:

  • skipXMLDeclaration

  • skipDTD

  • setTagCompression

of that three functions only setTagCompression is available for all serialization functions.

Because XML::LibXML does these flags not itself, one has to define them locally as the following example shows:

  local $XML::LibXML::skipXMLDeclaration = 1;
  local $XML::LibXML::skipDTD = 1;
  local $XML::LibXML::setTagCompression = 1;

If skipXMLDeclaration is defined and not '0', the XML declaration is omitted during serialization.

If skipDTD is defined and not '0', an existing DTD would not be serialized with the document.

If setTagCompression is defined and not '0' empty tags are displayed as open and closing tags ranther than the shortcut. For example the empty tag foo will be rendered as <foo></foo> rather than <foo/>.

PARSER OPTIONS

LibXML options are global (unfortunately this is a limitation of the underlying implementation, not this interface). They can either be set using $parser->option(...), or XML::LibXML->option(...), both are treated in the same manner. Note that even two parser processes will share some of the same options, so be careful out there!

Every option returns the previous value, and can be called without parameters to get the current value.

validation
  $parser->validation(1);

Turn validation on (or off). Defaults to off.

recover
  $parser->recover(1);

Turn the parsers recover mode on (or off). Defaults to off.

This allows one to parse broken XML data into memory. This switch will only work with XML data rather than HTML data. Also the validation will be switched off automaticly.

The recover mode helps to recover documents that are almost wellformed very efficiently. That is for example a document that forgets to close the document tag (or any other tag inside the document). The recover mode of XML::LibXML has problems restoring documents that are more like well ballanced chunks.

XML::LibXML will only parse until the first fatal error occours, reporting recoverable parsing errors as warnings. To suppress these warnings use $parser->recover_silently(1); or, equivalently, $parser->recover(2).

recover_silently
  $parser->recover_silently(1);

Turns the parser warnings off (or on). Defaults to on.

This allows to switch off warnings printed to STDERR when parsing documents with recover(1).

Please note that calling recover_silently(0) also turns the parser recover mode off and calling recover_silently(1) automatically activates the parser recover mode.

expand_entities
  $parser->expand_entities(0);

Turn entity expansion on or off, enabled by default. If entity expansion is off, any external parsed entities in the document are left as entities. Probably not very useful for most purposes.

keep_blanks
  $parser->keep_blanks(0);

Allows you to turn off XML::LibXML's default behaviour of maintaining whitespace in the document.

pedantic_parser
  $parser->pedantic_parser(1);

You can make XML::LibXML more pedantic if you want to.

line_numbers
  $parser->line_numbers(1);

If this option is activated XML::LibXML will store the line number of a node. This gives more information where a validation error occoured. It could be also used to find out about the position of a node after parsing (see also XML::LibXML::Node::line_number())

By default line numbering is switched off (0).

load_ext_dtd
  $parser->load_ext_dtd(1);

Load external DTD subsets while parsing.

This flag is also required for DTD Validation, to provide complete attribute, and to expand entities, regardless if the document has an internal subset. Thus switching off external DTD loading, will disable entity expansion, validation, and complete attributes on internal subsets as well.

If you leave this parser flag untouched, everythig will work, because the default is 1 (activated)

complete_attributes
  $parser->complete_attributes(1);

Complete the elements attributes lists with the ones defaulted from the DTDs. By default, this option is enabled.

expand_xinclude
  $parser->expand_xinclude(1);

Expands XIinclude tags immediately while parsing the document. This flag assures that the parser callbacks are used while parsing the included document.

load_catalog
  $parser->load_catalog( $catalog_file );

Will use $catalog_file as a catalog during all parsing processes. Using a catalog will significantly speed up parsing processes if many external resources are loaded into the parsed documents (such as DTDs or XIncludes).

Note that catalogs will not be available if an external entity handler was specified. At the current state it is not possible to make use of both types of resolving systems at the same time.

base_uri
  $parser->base_uri( $your_base_uri );

In case of parsing strings or file handles, XML::LibXML doesn't know about the base uri of the document. To make relative references such as XIncludes work, one has to set a separate base URI, that is then used for the parsed documents.

gdome_dom
  $parser->gdome_dom(1);

THIS FLAG IS EXPERIMENTAL!

Although quite powerful XML:LibXML's DOM implementation is limited if one needs or wants full DOM level 2 or level 3 support. XML::GDOME is based on libxml2 as well but provides a rather complete DOM implementation by wrapping libgdome. This allows you to make use of XML::LibXML's full parser options and XML::GDOME's DOM implementation at the same time.

To make use of this function, one has to install libgdome and configure XML::LibXML to use this library. For this you need to rebuild XML::LibXML!

clean_namespaces
  $parser->clean_namespaces( 1 );

libxml2 2.6.0 and later allows to strip redundant namespace declarations from the DOM tree. To do this, one has to set clean_namespaces() to 1 (TRUE). By default no namespace cleanup is done.

ERROR REPORTING

XML::LibXML throws exceptions during parsing, validation or XPath processing (and some other occations). These errors can be caught by using eval blocks. The error then will be stored in $@.

XML::LibXML throws errors as they occour and does not wait if a user test for them. This is a very common misunderstanding in the use of XML::LibXML. If the eval is ommited, XML::LibXML will allways halt your script by "croaking" (see Carp man page for details).

Also note that an increasing number of functions throw errors if bad data is passed. If you cannot asure valid data passed to XML::LibXML you should eval these functions.

Note: since version 1.59, get_last_error() is no longer available in XML::LibXML for thread-safety reasons.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Reader - XML::LibXML::Reader - interface to libxml2 pull parser

  • CONSTRUCTOR
    • Source specification
    • Parsing options
  • METHODS CONTROLLING PARSING PROGRESS
  • METHODS EXTRACTING INFORMATION
  • METHODS EXTRACTING DOM NODES
  • METHODS PROCESSING ATTRIBUTES
  • OTHER METHODS
  • DESTRUCTION
  • NODE TYPES
  • STATES
  • VERSION
  • AUTHORS
  • SEE ALSO
  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Reader - XML::LibXML::Reader - interface to libxml2 pull parser

SYNOPSIS

  use XML::LibXML::Reader;

  $reader = new XML::LibXML::Reader("file.xml")
         or die "cannot read file.xml\n";
  while ($reader->read) {
    processNode($reader);
  }

  sub processNode {
      $reader = shift;
      printf "%d %d %s %d\n", ($reader->depth,
                               $reader->nodeType,
                               $reader->name,
                               $reader->isEmptyElement);
  }

or

    $reader = new XML::LibXML::Reader("file.xml")
         or die "cannot read file.xml\n";
    $reader->preservePattern('//table/tr');
    $reader->finish;
    print $reader->document->toString(1);

DESCRIPTION

This is a perl interface to libxml2's pull-parser implementation xmlTextReader http://xmlsoft.org/html/libxml-xmlreader.html. Pull-parser (StAX in Java, XmlReader in C#) use an iterator approach to parse a xml-file. They are easier to program than event-based parser (SAX) and much more lightweight than tree-based parser (DOM), which load the complete tree into memory.

The Reader acts as a cursor going forward on the document stream and stopping at each node in the way. At every point DOM-like methods of the Reader object allow to examine the current node (name, namespace, attributes, etc.)

The user's code keeps control of the progress and simply calls the read() function repeatedly to progress to the next node in the document order. Other functions provide means for skipping complete subtrees, or nodes until a specific element, etc.

At every time, only a very limitted portion of the document is kept in the memory, which makes the API more memory-efficient than using DOM. However, it is also possible to mix Reader with DOM. At every point the user may copy the current node (optionally expanded into a complete subtree) from the processed document to another DOM tree, or to instruct the Reader to collect sub-document in form of a DOM tree consisting of selected nodes.

Reader API also supports namespaces, xml:base, entity handling, and DTD validation. Schema and RelaxNG validation support will probably be added in some later revision of the Perl interface.

The naming of methods compared to libxml2 and C# XmlTextReader has been changed slightly to match the conventions of XML::LibXML. Some functions have been changed or added with respect to the C interface.

CONSTRUCTOR

Depending on the XML source, the Reader object can be created with either of:

    my $reader = XML::LibXML::Reader->new( location => "file.xml", ... );
    my $reader = XML::LibXML::Reader->new( string => $xml_string, ... );
    my $reader = XML::LibXML::Reader->new( IO => $file_handle, ... );
    my $reader = XML::LibXML::Reader->new( DOM => $dom, ... );

where ... are (optional) reader options described below in Parser options. The constructor recognizes the following XML sources:

Source specification

location

Read XML from a local file or URL.

string

Read XML from a string.

IO

Read XML a Perl IO filehandle.

FD

Read XML from a file descriptor (bypasses Perl I/O layer, only applicable to filehandles for regular files or pipes). Possibly faster than IO.

DOM

Use reader API to walk through a preparsed XML::LibXML::Document.

Parsing options

URI

can be used to provide baseURI when parsing strings or filehandles.

encoding

override document encoding.

RelaxNG

can be used to pass either a XML::LibXML::RelaxNG object or a filename or URL of a RelaxNG schema to the constructor. The schema is then used to validate the document as it is processed.

Schema

can be used to pass either a XML::LibXML::Schema object or a filename or URL of a W3C XSD schema to the constructor. The schema is then used to validate the document as it is processed.

recover

recover on errors (0 or 1)

expand_entities

substitute entities (0 or 1)

load_ext_dtd

load the external subset (0 or 1)

complete_attributes

default DTD attributes (0 or 1)

validation

validate with the DTD (0 or 1)

suppress_errors

suppress error reports (0 or 1)

suppress_warnings

suppress warning reports (0 or 1)

pedantic_parser

pedantic error reporting (0 or 1)

no_blanks

remove blank nodes (0 or 1)

expand_xinclude

Implement XInclude substitition (0 or 1)

no_network

Forbid network access (0 or 1)

clean_namespaces

remove redundant namespaces declarations (0 or 1)

no_cdata

merge CDATA as text nodes (0 or 1)

no_xinclude_nodes

do not generate XINCLUDE START/END nodes (0 or 1)

METHODS CONTROLLING PARSING PROGRESS

read ()

Moves the position to the next node in the stream, exposing its properties.

Returns 1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error

readAttributeValue ()

Parses an attribute value into one or more Text and EntityReference nodes.

Returns 1 in case of success, 0 if the reader was not positionned on an attribute node or all the attribute values have been read, or -1 in case of error.

readState ()

Gets the read state of the reader. Returns the state value, or -1 in case of error. The module exports constants for the Reader states, see STATES below.

depth ()

The depth of the node in the tree, starts at 0 for the root node.

next ()

Skip to the node following the current one in the document order while avoiding the subtree if any. Returns 1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error.

nextElement (localname?,nsURI?)

Skip nodes following the current one in the document order until a specific element is reached. The element's name must be equal to a given localname if defined, and its namespace must equal to a given nsURI if defined. Either of the arguments can be undefined (or omitted, in case of the latter or both).

Returns 1 if the element was found, 0 if there is no more nodes to read, or -1 in case of error.

skipSiblings ()

Skip all nodes on the same or lower level until the first node on a higher level is reached. In particular, if the current node occurs in an element, the reader stops at the end tag of the parent element, otherwise it stops at a node immediately following the parent node.

Returns 1 if successful, 0 if end of the document is reached, or -1 in case of error.

nextSibling ()

It skips to the node following the current one in the document order while avoiding the subtree if any.

Returns 1 if the node was read successfully, 0 if there is no more nodes to read, or -1 in case of error

nextSiblingElement (name?,nsURI?)

Like nextElement but only processes sibling elements of the current node (moving forward using nextSibling () rather than read (), internally).

Returns 1 if the element was found, 0 if there is no more sibling nodes, or -1 in case of error.

finish ()

Skip all remaining nodes in the document, reaching end of the document.

Returns 1 if successful, 0 in case of error.

close ()

This method releases any resources allocated by the current instance and closes any underlying input. It returns 0 on failure and 1 on success. This method is automatically called by the destructor when the reader is forgotten, therefore you do not have to call it directly.

METHODS EXTRACTING INFORMATION

name ()

Returns the qualified name of the current node, equal to (Prefix:)LocalName.

nodeType ()

Returns the type of the current node. See NODE TYPES below.

localName ()

Returns the local name of the node.

prefix ()

Returns the prefix of the namespace associated with the node.

namespaceURI ()

Returns the URI defining the namespace associated with the node.

isEmptyElement ()

Check if the current node is empty, this is a bit bizarre in the sense that <a/> will be considered empty while <a></a> will not.

hasValue ()

Returns true if the node can have a text value.

value ()

Provides the text value of the node if present or undef if not available.

readInnerXml ()

Reads the contents of the current node, including child nodes and markup. Returns a string containing the XML of the node's content, or undef if the current node is neither an element nor attribute, or has no child nodes.

readOuterXml ()

Reads the contents of the current node, including child nodes and markup.

Returns a string containing the XML of the node including its content, or undef if the current node is neither an element nor attribute.

METHODS EXTRACTING DOM NODES

document ()

Provides access to the document tree built by the reader. This function can be used to collect the preserved nodes (see preserveNode() and preservePattern).

CAUTION: Never use this function to modify the tree unless reading of the whole document is completed!

copyCurrentNode (deep)

This function is similar a DOM function copyNode(). It returns a copy of the currently processed node as a corresponding DOM object. Use deep = 1 to obtain the full subtree.

preserveNode ()

This tells the XML Reader to preserve the current node in the document tree. A document tree consisting of the preserved nodes and their content can be obtained using the method document() once parsing is finished.

Returns the node or NULL in case of error.

preservePattern (pattern,\%ns_map)

This tells the XML Reader to preserve all nodes matched by the pattern (which is a streaming XPath subset). A document tree consisting of the preserved nodes and their content can be obtained using the method document() once parsing is finished.

An optional second argument can be used to provide a HASH reference mapping prefixes used by the XPath to namespace URIs.

The XPath subset available with this function is described at

  http://www.w3.org/TR/xmlschema-1/#Selector

and matches the production

  Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest )

Returns a positive number in case of success and -1 in case of error

METHODS PROCESSING ATTRIBUTES

attributeCount ()

Provides the number of attributes of the current node.

hasAttributes ()

Whether the node has attributes.

getAttribute (name)

Provides the value of the attribute with the specified qualified name.

Returns a string containing the value of the specified attribute, or undef in case of error.

getAttributeNs (localName, namespaceURI)

Provides the value of the specified attribute.

Returns a string containing the value of the specified attribute, or undef in case of error.

getAttributeNo (no)

Provides the value of the attribute with the specified index relative to the containing element.

Returns a string containing the value of the specified attribute, or undef in case of error.

isDefault ()

Returns true if the current attribute node was generated from the default value defined in the DTD.

moveToAttribute (name)

Moves the position to the attribute with the specified local name and namespace URI.

Returns 1 in case of success, -1 in case of error, 0 if not found

moveToAttributeNo (no)

Moves the position to the attribute with the specified index relative to the containing element.

Returns 1 in case of success, -1 in case of error, 0 if not found

moveToAttributeNs (localName,namespaceURI)

Moves the position to the attribute with the specified local name and namespace URI.

Returns 1 in case of success, -1 in case of error, 0 if not found

moveToFirstAttribute ()

Moves the position to the first attribute associated with the current node.

Returns 1 in case of success, -1 in case of error, 0 if not found

moveToNextAttribute ()

Moves the position to the next attribute associated with the current node.

Returns 1 in case of success, -1 in case of error, 0 if not found

moveToElement ()

Moves the position to the node that contains the current attribute node.

Returns 1 in case of success, -1 in case of error, 0 if not moved

isNamespaceDecl ()

Determine whether the current node is a namespace declaration rather than a regular attribute.

Returns 1 if the current node is a namespace declaration, 0 if it is a regular attribute or other type of node, or -1 in case of error.

OTHER METHODS

lookupNamespace (prefix)

Resolves a namespace prefix in the scope of the current element.

Returns a string containing the namespace URI to which the prefix maps or undef in case of error.

encoding ()

Returns a string containing the encoding of the document or undef in case of error.

standalone ()

Determine the standalone status of the document being read. Returns 1 if the document was declared to be standalone, 0 if it was declared to be not standalone, or -1 if the document did not specify its standalone status or in case of error.

xmlVersion ()

Determine the XML version of the document being read. Returns a string containing the XML version of the document or undef in case of error.

baseURI ()

The base URI of the node. See the XML Base W3C specification.

isValid ()

Retrieve the validity status from the parser.

Returns 1 if valid, 0 if no, and -1 in case of error.

xmlLang ()

The xml:lang scope within which the node resides.

lineNumber ()

Provide the line number of the current parsing point. Available if libxml2 >= 2.6.17.

columnNumber ()

Provide the column number of the current parsing point. Available if libxml2 >= 2.6.17.

byteConsumed ()

This function provides the current index of the parser relative to the start of the current entity. This function is computed in bytes from the beginning starting at zero and finishing at the size in bytes of the file if parsing a file. The function is of constant cost if the input is UTF-8 but can be costly if run on non-UTF-8 input. Available if libxml2 >= 2.6.18.

setParserProp (prop = value, ...)>

Change the parser processing behaviour by changing some of its internal properties. The following properties are available with this function: ``load_ext_dtd'', ``complete_attributes'', ``validation'', ``expand_entities''.

Since some of the properties can only be changed before any read has been done, it is best to set the parsing properties at the constructor.

Returns 0 if the call was successful, or -1 in case of error

getParserProp (prop)

Get value of an parser internal property. The following property names can be used: ``load_ext_dtd'', ``complete_attributes'', ``validation'', ``expand_entities''.

Returns the value, usually 0 or 1, or -1 in case of error.

DESTRUCTION

XML::LibXML takes care of the reader object destruction when the last reference to the reader object goes out of scope. The document tree is preserved, though, if either of $reader->document or $reader->preserveNode was used and references to the document tree exist.

NODE TYPES

The reader interface provides the following constants for node types (the constant symbols are exported by default or if tag :types is used).

    XML_READER_TYPE_NONE                    => 0
    XML_READER_TYPE_ELEMENT                 => 1
    XML_READER_TYPE_ATTRIBUTE               => 2
    XML_READER_TYPE_TEXT                    => 3
    XML_READER_TYPE_CDATA                   => 4
    XML_READER_TYPE_ENTITY_REFERENCE        => 5
    XML_READER_TYPE_ENTITY                  => 6
    XML_READER_TYPE_PROCESSING_INSTRUCTION  => 7
    XML_READER_TYPE_COMMENT                 => 8
    XML_READER_TYPE_DOCUMENT                => 9
    XML_READER_TYPE_DOCUMENT_TYPE           => 10
    XML_READER_TYPE_DOCUMENT_FRAGMENT       => 11
    XML_READER_TYPE_NOTATION                => 12
    XML_READER_TYPE_WHITESPACE              => 13
    XML_READER_TYPE_SIGNIFICANT_WHITESPACE  => 14
    XML_READER_TYPE_END_ELEMENT             => 15
    XML_READER_TYPE_END_ENTITY              => 16
    XML_READER_TYPE_XML_DECLARATION         => 17

STATES

The following constants represent the values returned by readState(). They are exported by default, or if tag :states is used:

    XML_READER_NONE      => -1
    XML_READER_START     =>  0
    XML_READER_ELEMENT   =>  1
    XML_READER_END       =>  2
    XML_READER_EMPTY     =>  3
    XML_READER_BACKTRACK =>  4
    XML_READER_DONE      =>  5
    XML_READER_ERROR     =>  6

VERSION

0.02

AUTHORS

Heiko Klein, <H.Klein@gmx.net> and Petr Pajas, < pajas@matfyz.cz>

SEE ALSO

http://xmlsoft.org/html/libxml-xmlreader.html

http://dotgnu.org/pnetlib-doc/System/Xml/XmlTextReader.html

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::RelaxNG - RelaxNG Schema Validation

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::RelaxNG - RelaxNG Schema Validation

SYNOPSIS

  $rngschema = XML::LibXML::RelaxNG->new( location => $filename_or_url );
  $rngschema = XML::LibXML::RelaxNG->new( string => $xmlschemastring );
  $rngschema = XML::LibXML::RelaxNG->new( DOM => $doc );
  eval { $rngschema->validate( $doc ); };

DESCRIPTION

The XML::LibXML::RelaxNG class is a tiny frontend to libxml2's RelaxNG implementation. Currently it supports only schema parsing and document validation.

new
  $rngschema = XML::LibXML::RelaxNG->new( location => $filename_or_url );
  $rngschema = XML::LibXML::RelaxNG->new( string => $xmlschemastring );
  $rngschema = XML::LibXML::RelaxNG->new( DOM => $doc );

The constructor of XML::LibXML::RelaxNG may get called with either one of three parameters. The parameter tells the class from which source it should generate a validation schema. It is important, that each schema only have a single source.

The location parameter allows to parse a schema from the filesystem or a URL.

The string parameter will parse the schema from the given XML string.

The DOM parameter allows to parse the schema from a preparsed XML::LibXML::Document.

Note that the constructor will die() if the schema does not meed the constraints of the RelaxNG specification.

validate
  eval { $rngschema->validate( $doc ); };

This function allows to validate a document against the given RelaxNG schema. If this function succeeds, it will return 0, otherwise it will die() and report the errors found. Because of this validate() should be always evaluated.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::SAX - XML::LibXML direct SAX parser

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::SAX - XML::LibXML direct SAX parser

DESCRIPTION

XML::LibXML provides an interface to libxml2 direct SAX interface. Through this interface it is possible to generate SAX events directly while parsing a document. While using the SAX parser XML::LibXML will not create a DOM Document tree.

Such an interface is useful if very large XML documents have to be processed and no DOM functions are required. By using this interface it is possible to read data stored within a XML document directly into the application datastructures without loading the document into memory.

The SAX interface of XML::LibXML is based on the famous XML::SAX interface. It uses the generic interface as provided by XML::SAX::Base.

Additionally to the generic functions, which are only able to process entire documents, XML::LibXML::SAX provides parse_chunk(). This method generates SAX events from well ballanced data such as is often provided by databases.

NOTE: At the moment XML::LibXML provides only an incomplete interface to libxml2's native SAX implementaion. The current implementation is not tested in production environment. It may causes significant memory problems or shows wrong behaviour. If you run into specific problems using this part of XML::LibXML, let me know.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::SAX::Builder - Building DOM trees from SAX events.

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::SAX::Builder - Building DOM trees from SAX events.

SYNOPSIS

  my $builder = XML::LibXML::SAX::Builder->new();

  my $gen = XML::Generator::DBI->new(Handler => $builder, dbh => $dbh);
  $gen->execute("SELECT * FROM Users");

  my $doc = $builder->result();

DESCRIPTION

This is a SAX handler that generates a DOM tree from SAX events. Usage is as above. Input is accepted from any SAX1 or SAX2 event generator.

Building DOM trees from SAX events is quite easy with XML::LibXML::SAX::Builder. The class is designed as a SAX2 final handler not as a filter!

Since SAX is strictly stream oriented, you should not expect anything to return from a generator. Instead you have to ask the builder instance directly to get the document built. XML::LibXML::SAX::Builder's result() function holds the document generated from the last SAX stream.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::SAX::Generator - Generate SAX events from a LibXML tree

NAME

XML::LibXML::SAX::Generator - Generate SAX events from a LibXML tree

SYNOPSIS

  my $handler = MySAXHandler->new();
  my $generator = XML::LibXML::SAX::Generator->new(Handler => $handler);
  my $dom = XML::LibXML->new->parse_file("foo.xml");

  $generator->generate($dom);

DESCRIPTION

THIS CLASS IS DEPRACED! Use XML::LibXML::SAX::Parser instead!

This helper class allows you to generate SAX events from any XML::LibXML node, and all it's sub-nodes. This basically gives you interop from XML::LibXML to other modules that may implement SAX.

It uses SAX2 style, but should be compatible with anything SAX1, by use of stringification overloading.

There is nothing to really know about, beyond the synopsis above, and a general knowledge of how to use SAX, which is beyond the scope here.


XML::LibXML::Schema - XML Schema Validation

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Schema - XML Schema Validation

SYNOPSIS

  $xmlschema = XML::LibXML::Schema->new( location => $filename_or_url );
  $xmlschema = XML::LibXML::Schema->new( string => $xmlschemastring );
  eval { $xmlschema->validate( $doc ); };

DESCRIPTION

The XML::LibXML::Schema class is a tiny frontend to libxml2's XML Schema implementation. Currently it supports only schema parsing and document validation.

new
  $xmlschema = XML::LibXML::Schema->new( location => $filename_or_url );
  $xmlschema = XML::LibXML::Schema->new( string => $xmlschemastring );

The constructor of XML::LibXML::Schema may get called with either one of two parameters. The parameter tells the class from which source it should generate a validation schema. It is important, that each schema only have a single source.

The location parameter allows to parse a schema from the filesystem or a URL.

The string parameter will parse the schema from the given XML string.

Note that the constructor will die() if the schema does not meed the constraints of the XML Schema specification.

validate
  eval { $xmlschema->validate( $doc ); };

This function allows to validate a document against the given XML Schema. If this function succeeds, it will return 0, otherwise it will die() and report the errors found. Because of this validate() should be always evaluated.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::Text - XML::LibXML Class for Text Nodes

  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::Text - XML::LibXML Class for Text Nodes

SYNOPSIS

  $text = XML::LibXML::Text->new( $content );
  $nodedata = $text->data;
  $text->setData( $text_content );
  $text->substringData($offset, $length);
  $text->appendData( $somedata );
  $text->insertData($offset, $string);
  $text->deleteData($offset, $length);
  $text->deleteDataString($remstring, $all);
  $text->replaceData($offset, $length, $string);
  $text->replaceDataString($old, $new, $flag);
  $text->replaceDataRegEx( $search_cond, $replace_cond, $reflags );

DESCRIPTION

Different to the DOM specification XML::LibXML implements the text node as the base class of all character data node. Therefor there exists no CharacterData class. This allow one to use all methods that are available for textnodes as well for Comments or CDATA-sections.

new
  $text = XML::LibXML::Text->new( $content );

The constuctor of the class. It creates an unbound text node.

data
  $nodedata = $text->data;

Although there exists the nodeValue attribute in the Node class, the DOM specification defines data as a separate attribute. XML::LibXML implements these two attributes not as different attributes, but as aliases, such as libxml2 does. Therefore

   $text->data;

and

   $text->nodeValue;

will have the same result and are not different entities.

setData($string)
  $text->setData( $text_content );

This function sets or replaces text content to a node. The node has to be of the type "text", "cdata" or "comment".

substringData($offset,$length)
  $text->substringData($offset, $length);

Extracts a range of data from the node. (DOM Spec) This function takes the two parameters $offset and $length and returns the substring, if available.

If the node contains no data or $offset refers to an nonexisting string index, this function will return undef. If $length is out of range substringData will return the data starting at $offset instead of causing an error.

appendData($string)
  $text->appendData( $somedata );

Appends a string to the end of the existing data. If the current text node contains no data, this function has the same effect as setData.

insertData($offset,$string)
  $text->insertData($offset, $string);

Inserts the parameter $string at the given $offset of the existing data of the node. This operation will not remove existing data, but change the order of the existing data.

The $offset has to be a positive value. If $offset is out of range, insertData will have the same behaviour as appendData.

deleteData($offset, $length)
  $text->deleteData($offset, $length);

This method removes a chunk from the existing node data at the given offset. The $length parameter tells, how many characters should be removed from the string.

deleteDataString($string, [$all])
  $text->deleteDataString($remstring, $all);

This method removes a chunk from the existing node data. Since the DOM spec is quite unhandy if you already know which string to remove from a text node, this method allows more perlish code :)

The functions takes two parameters: $string and optional the $all flag. If $all is not set, undef or 0, deleteDataString will remove only the first occourance of $string. If $all is TRUE deleteDataString will remove all occurrences of $string from the node data.

replaceData($offset, $length, $string)
  $text->replaceData($offset, $length, $string);

The DOM style version to replace node data.

replaceDataString($oldstring, $newstring, [$all])
  $text->replaceDataString($old, $new, $flag);

The more programmer friendly version of replaceData() :)

Instead of giving offsets and length one can specify the exact string ($oldstring) to be replaced. Additionally the $all flag allows to replace all occourences of $oldstring.

replaceDataRegEx( $search_cond, $replace_cond, $reflags )
  $text->replaceDataRegEx( $search_cond, $replace_cond, $reflags );

This method replaces the node's data by a simple regular expression. Optional, this function allows to pass some flags that will be added as flag to the replace statement.

NOTE: This is a shortcut for

   my $datastr = $node->getData();
   $datastr =~ s/somecond/replacement/g; # 'g' is just an example for any flag
   $node->setData( $datastr );

This function can make things easier to read for simple replacements. For more complex variants it is recommended to use the code snippet above.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXML::XPathContext - XPath Evaluation

  • EXAMPLES
    • Namespaces
    • Custom XPath functions
    • Variables
  • METHODS
  • BUGS AND CAVEATS
  • AUTHORS
  • HISTORICAL REMARK
  • AUTHORS
  • VERSION
  • COPYRIGHT

NAME

XML::LibXML::XPathContext - XPath Evaluation

SYNOPSIS

  my $xpc = XML::LibXML::XPathContext->new();
  my $xpc = XML::LibXML::XPathContext->new($node);
  $xpc->registerNs($prefix, $namespace_uri)
  $xpc->unregisterNs($prefix)
  $uri = $xpc->lookupNs($prefix)
  $xpc->registerVarLookupFunc($callback, $data)
  $data = $xpc->getVarLookupData();
  $callback = $xpc->getVarLookupFunc();
  $xpc->unregisterVarLookupFunc($name);
  $xpc->registerFunctionNS($name, $uri, $callback)
  $xpc->unregisterFunctionNS($name, $uri)
  $xpc->registerFunction($name, $callback)
  $xpc->unregisterFunction($name)
  @nodes = $xpc->findnodes($xpath)
  @nodes = $xpc->findnodes($xpath, $context_node )
  $nodelist = $xpc->findnodes($xpath, $context_node )
  $object = $xpc->find($xpath )
  $object = $xpc->find($xpath, $context_node )
  $value = $xpc->findvalue($xpath )
  $value = $xpc->findvalue($xpath, $context_node )
  $xpc->setContextNode($node)
  my $node = $xpc->getContextNode;
  $xpc->setContextPosition($position)
  my $position = $xpc->getContextPosition;
  $xpc->setContextSize($size)
  my $size = $xpc->getContextSize;
  $xpc->setContextNode($node)

DESCRIPTION

The XML::LibXML::XPathContext class provides an almost complete interface to libxml2's XPath implementation. With XML::LibXML::XPathContext is is possible to evaluate XPath expressions in the context of arbitrary node, context size, and context position, with a user-defined namespace-prefix mapping, custom XPath functions written in Perl, and even a custom XPath variable resolver.

EXAMPLES

Namespaces

This example demonstrates registerNs() method. It finds all paragraph nodes in an XHTML document.

  my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
  $xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
  my @nodes = $xc->findnodes('//xhtml:p');

Custom XPath functions

This example demonstrates registerFunction() method by defining a function filtering nodes based on a Perl regular expression:

  sub grep_nodes {
    my ($nodelist,$regexp) =  @_;
    my $result = XML::LibXML::NodeList->new;
    for my $node ($nodelist->get_nodelist()) {
      $result->push($node) if $node->textContent =~ $regexp;
    }
    return $result;
  };

  my $xc = XML::LibXML::XPathContext->new($node);
  $xc->registerFunction('grep_nodes', \&grep_nodes);
  my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing|es)?\b")]');

Variables

This example demonstrates registerVarLookup() method. We use XPath variables to recycle results of previous evaluations:

  sub var_lookup {
    my ($varname,$ns,$data)=@_;
    return $data->{$varname};
  }

  my $areas = XML::LibXML->new->parse_file('areas.xml');
  my $empl = XML::LibXML->new->parse_file('employees.xml');

  my $xc = XML::LibXML::XPathContext->new($empl);

  my %variables = (
    A => $xc->find('/employees/employee[@salary>10000]'),
    B => $areas->find('/areas/area[district='Brooklyn']/street'),
  );

  # get names of employees from $A woring in an area listed in $B
  $xc->registerVarLookupFunc(\&var_lookup, \%variables);
  my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');

METHODS

new
  my $xpc = XML::LibXML::XPathContext->new();

Creates a new XML::LibXML::XPathContext object without a context node.

  my $xpc = XML::LibXML::XPathContext->new($node);

Creates a new XML::LibXML::XPathContext object with the context node set to $node.

registerNs
  $xpc->registerNs($prefix, $namespace_uri)

Registers namespace $prefix to $namespace_uri.

unregisterNs
  $xpc->unregisterNs($prefix)

Unregisters namespace $prefix.

lookupNs
  $uri = $xpc->lookupNs($prefix)

Returns namespace URI registered with $prefix. If $prefix is not registered to any namespace URI returns undef.

registerVarLookupFunc
  $xpc->registerVarLookupFunc($callback, $data)

Registers variable lookup function $prefix. The registered function is executed by the XPath engine each time an XPath variable is evaluated. It takes three arguments: $data, variable name, and variable ns-URI and must return one value: a number or string or any XML::LibXML:: object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g. Document, Element, etc.), or NodeList. For convenience, simple (non-blessed) array references containing only XML::LibXML::Node objects can be used instead of a XML::LibXML::NodeList.

getVarLookupData
  $data = $xpc->getVarLookupData();

Returns the data that have been associated with a variable lookup function during a previous call to registerVarLookupFunc.

getVarLookupFunc
  $callback = $xpc->getVarLookupFunc();

Returns the variable lookup function previously registered with registerVarLookupFunc.

unregisterVarLookupFunc
  $xpc->unregisterVarLookupFunc($name);

Unregisters variable lookup function and the associated lookup data.

registerFunctionNS
  $xpc->registerFunctionNS($name, $uri, $callback)

Registers an extension function $name in $uri namespace. $callback must be a CODE reference. The arguments of the callback function are either simple scalars or XML::LibXML::* objects depending on the XPath argument types. The function is responsible for checking the argument number and types. Result of the callback code must be a single value of the following types: a simple scalar (number, string) or an arbitrary XML::LibXML::* object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g. Document, Element, etc.), or NodeList. For convenience, simple (non-blessed) array references containing only XML::LibXML::Node objects can be used instead of a XML::LibXML::NodeList.

unregisterFunctionNS
  $xpc->unregisterFunctionNS($name, $uri)

Unregisters extension function $name in $uri namespace. Has the same effect as passing undef as $callback to registerFunctionNS.

registerFunction
  $xpc->registerFunction($name, $callback)

Same as registerFunctionNS but without a namespace.

unregisterFunction
  $xpc->unregisterFunction($name)

Same as unregisterFunctionNS but without a namespace.

findnodes
  @nodes = $xpc->findnodes($xpath)
  @nodes = $xpc->findnodes($xpath, $context_node )
  $nodelist = $xpc->findnodes($xpath, $context_node )

Performs the xpath statement on the current node and returns the result as an array. In scalar context returns a XML::LibXML::NodeList object. Optionally, a node may be passed as a second argument to set the context node for the query.

find
  $object = $xpc->find($xpath )
  $object = $xpc->find($xpath, $context_node )

Performs the xpath expression using the current node as the context of the expression, and returns the result depending on what type of result the XPath expression had. For example, the XPath 1 * 3 + 52 results in a XML::LibXML::Number object being returned. Other expressions might return a XML::LibXML::Boolean object, or a XML::LibXML::Literal object (a string). Each of those objects uses Perl's overload feature to ``do the right thing'' in different contexts. Optionally, a node may be passed as a second argument to set the context node for the query.

findvalue
  $value = $xpc->findvalue($xpath )
  $value = $xpc->findvalue($xpath, $context_node )

Is exactly equivalent to:

  $node->find( $xpath )->to_literal;

That is, it returns the literal value of the results. This enables you to ensure that you get a string back from your search, allowing certain shortcuts. This could be used as the equivalent of <xsl:value-of select=``some_xpath''/>. Optionally, a node may be passed in the second argument to set the context node for the query.

setContextNode
  $xpc->setContextNode($node)

Set the current context node.

getContextNode
  my $node = $xpc->getContextNode;

Get the current context node.

setContextPosition
  $xpc->setContextPosition($position)

Set the current context position. By default, this value is -1 (and evaluating XPath function position() in the initial context raises an XPath error), but can be set to any value up to context size. This usually only serves to cheat the XPath engine to return given position when position() XPath function is called. Setting this value to -1 restores the default behavior.

getContextPosition
  my $position = $xpc->getContextPosition;

Get the current context position.

setContextSize
  $xpc->setContextSize($size)

Set the current context size. By default, this value is -1 (and evaluating XPath function last() in the initial context raises an XPath error), but can be set to any non-negative value. This usually only serves to cheat the XPath engine to return the given value when last() XPath function is called. If context size is set to 0, position is automatically also set to 0. If context size is positive, position is automatically set to 1. Setting context size to -1 restores the default behavior.

getContextSize
  my $size = $xpc->getContextSize;

Get the current context size.

setContextNode
  $xpc->setContextNode($node)

Set the current context node.

BUGS AND CAVEATS

XML::LibXML::XPathContext objects are reentrant, meaning that you can call methods of an XML::LibXML::XPathContext even from XPath extension functions registered with the same object or from a variable lookup function. On the other hand, you should rather avoid registering new extension functions, namespaces and a variable lookup function from within extension functions and a variable lookup function, unless you want to experience untested behavior.

AUTHORS

Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT code by Matt Sergeant and Christian Glahn.

HISTORICAL REMARK

Prior to XML::LibXML 1.61 this module was distributed separately for maintanance reasons.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION

1.62

COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.


XML::LibXSLT - Interface to the gnome libxslt library

  • OPTIONS
  • API
  • Input Callbacks
  • Security Callbacks
  • XML::LibXSLT::Stylesheet
  • Parameters
  • XML::LibXSLT::Security
    • Using XML::LibXSLT::Security
    • Interface
  • BENCHMARK
  • LIBRARY VERSIONS
  • AUTHOR
  • SEE ALSO

NAME

XML::LibXSLT - Interface to the gnome libxslt library

SYNOPSIS

  use XML::LibXSLT;
  use XML::LibXML;

  my $parser = XML::LibXML->new();
  my $xslt = XML::LibXSLT->new();

  my $source = $parser->parse_file('foo.xml');
  my $style_doc = $parser->parse_file('bar.xsl');

  my $stylesheet = $xslt->parse_stylesheet($style_doc);

  my $results = $stylesheet->transform($source);

  print $stylesheet->output_string($results);

DESCRIPTION

This module is an interface to the gnome project's libxslt. This is an extremely good XSLT engine, highly compliant and also very fast. I have tests showing this to be more than twice as fast as Sablotron.

OPTIONS

XML::LibXSLT has some global options. Note that these are probably not thread or even fork safe - so only set them once per process. Each one of these options can be called either as class methods, or as instance methods. However either way you call them, it still sets global options.

Each of the option methods returns its previous value, and can be called without a parameter to retrieve the current value.

max_depth
  XML::LibXSLT->max_depth(1000);

This option sets the maximum recursion depth for a stylesheet. See the very end of section 5.4 of the XSLT specification for more details on recursion and detecting it. If your stylesheet or XML file requires seriously deep recursion, this is the way to set it. Default value is 250.

debug_callback
  XML::LibXSLT->debug_callback($subref);

Sets a callback to be used for debug messages. If you don't set this, debug messages will be ignored.

register_function
  XML::LibXSLT->register_function($uri, $name, $subref);

Registers an XSLT extension function mapped to the given URI. For example:

  XML::LibXSLT->register_function("urn:foo", "bar",
    sub { scalar localtime });

Will register a bar function in the urn:foo namespace (which you have to define in your XSLT using xmlns:...) that will return the current date and time as a string:

  <xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
    xmlns:foo="urn:foo">
  <xsl:template match="/">
    The time is: <xsl:value-of select="foo:bar()"/>
  </xsl:template>
  </xsl:stylesheet>

Parameters can be in whatever format you like. If you pass in a nodelist it will be a XML::LibXML::NodeList object in your perl code, but ordinary values (strings, numbers and booleans) will be ordinary perl scalars. If you wish them to be XML::LibXML::Literal, XML::LibXML::Number and XML::LibXML::Number values respectively then set the variable $XML::LibXSLT::USE_LIBXML_DATA_TYPES to a true value. Return values can be a nodelist or a plain value - the code will just do the right thing. But only a single return value is supported (a list is not converted to a nodelist).

API

The following methods are available on the new XML::LibXSLT object:

parse_stylesheet($doc)

$doc here is an XML::LibXML::Document object (see the XML::LibXML manpage) representing an XSLT file. This method will return a XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT is invalid, an exception will be thrown, so wrap the call to parse_stylesheet in an eval{} block to trap this.

parse_stylesheet_file($filename)

Exactly the same as the above, but parses the given filename directly.

Input Callbacks

To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input callbacks, reuse the XML::LibXML input callback API as described in the XML::LibXML::InputCallback(3) manpage.

Security Callbacks

To create security preferences for the transformation see the XML::LibXSLT::Security manpage. Once the security preferences have been defined you can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet instance using the security_callbacks() method.

XML::LibXSLT::Stylesheet

The main API is on the stylesheet, though it is fairly minimal.

One of the main advantages of XML::LibXSLT is that you have a generic stylesheet object which you call the transform() method passing in a document to transform. This allows you to have multiple transformations happen with one stylesheet without requiring a reparse.

transform(doc, %params)
  my $results = $stylesheet->transform($doc, foo => "value);

Transforms the passed in XML::LibXML::Document object, and returns a new XML::LibXML::Document. Extra hash entries are used as parameters.

transform_file(filename, %params)
  my $results = $stylesheet->transform_file($filename, bar => "value");
output_string(result)

Returns a scalar that is the XSLT rendering of the XML::LibXML::Document object using the desired output format (specified in the xsl:output tag in the stylesheet). Note that you can also call $result->toString, but that will *always* output the document in XML format which may not be what you asked for in the xsl:output tag.

Important note: The string returned by this function appears to Perl as characters if the output encoding was specified as UTF-8 and as bytes if no output encoding was specified or if the output encoding was different from UTF-8. See also output_as_bytes(result) and output_as_chars(result).

output_as_bytes(result)

Like output_string(result), but always return the output as a byte string encoded in the output encoding specified in the stylesheet.

output_as_chars(result)

Like output_string(result), but always return the output as (UTF-8 encoded) string of characters.

output_fh(result, fh)

Outputs the result to the filehandle given in $fh.

output_file(result, filename)

Outputs the result to the file named in $filename.

output_encoding()

Returns the output encoding of the results. Defaults to "UTF-8".

media_type()

Returns the output media_type of the results. Defaults to "text/html".

Parameters

LibXSLT expects parameters in XPath format. That is, if you wish to pass a string to the XSLT engine, you actually have to pass it as a quoted string:

  $stylesheet->transform($doc, param => "'string'");

Note the quotes within quotes there!

Obviously this isn't much fun, so you can make it easy on yourself:

  $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
        param => "string"
        ));

The utility function does the right thing with respect to strings in XPath, including when you have quotes already embedded within your string.

XML::LibXSLT::Security

Provides an interface to the libxslt security framework by allowing callbacks to be defined that can restrict access to various resources (files or URLs) during a transformation.

The libxslt security framework allows callbacks to be defined for certain actions that a stylesheet may attempt during a transformation. It may be desirable to restrict some of these actions (for example, writing a new file using exsl:document). The actions that may be restricted are:

read_file

Called when the stylesheet attempts to open a local file (ie: when using the document() function).

write_file

Called when an attempt is made to write a local file (ie: when using the exsl:document element).

create_dir

Called when a directory needs to be created in order to write a file.

NOTE: By default, create_dir is not allowed. To enable it a callback must be registered.

read_net

Called when the stylesheet attempts to read from the network.

write_net

Called when the stylesheet attempts to write to the network.

Using XML::LibXSLT::Security

The interface for this module is similar to XML::LibXML::InputCallback. After creating a new instance you may register callbacks for each of the security options listed above. Then you apply the security preferences to the XML::LibXSLT or XML::LibXSLT::Stylesheet object using security_callbacks().

  my $security = XML::LibXSLT::Security->new();
  $security->register_callback( read_file  => $read_cb );
  $security->register_callback( write_file => $write_cb );
  $security->register_callback( create_dir => $create_cb );
  $security->register_callback( read_net   => $read_net_cb );
  $security->register_callback( write_net  => $write_net_cb );

  $xslt->security_callbacks( $security );
   -OR-
  $stylesheet->security_callbacks( $security );

The registered callback functions are called when access to a resource is requested. If the access should be allowed the callback should return 1, if not it should return 0. The callback functions should accept the following arguments:

$tctxt

This is the transform context (XML::LibXSLT::TransformContext). You can use this to get the current XML::LibXSLT::Stylesheet object by calling stylesheet().

  my $stylesheet = $tctxt->stylesheet();

The stylesheet object can then be used to share contextual information between different calls to the security callbacks.

$value

This is the name of the resource (file or URI) that has been requested.

If a particular option (except for create_dir) doesn't have a registered callback, then the stylesheet will have full access for that action.

Interface

new()

Creates a new XML::LibXSLT::Security object.

register_callback( $option, $callback )

Registers a callback function for the given security option (listed above).

unregister_callback( $option )

Removes the callback for the given option. This has the effect of allowing all access for the given option (except for create_dir).

BENCHMARK

Included in the distribution is a simple benchmark script, which has two drivers - one for LibXSLT and one for Sablotron. The benchmark requires the testcases files from the XSLTMark distribution which you can find at http://www.datapower.com/XSLTMark/

Put the testcases directory in the directory created by this distribution, and then run:

  perl benchmark.pl -h

to get a list of options.

The benchmark requires XML::XPath at the moment, but I hope to factor that out of the equation fairly soon. It also requires Time::HiRes, which I could be persuaded to factor out, replacing it with Benchmark.pm, but I haven't done so yet.

I would love to get drivers for XML::XSLT and XML::Transformiix, if you would like to contribute them. Also if you get this running on Win32, I'd love to get a driver for MSXSLT via OLE, to see what we can do against those Redmond boys!

LIBRARY VERSIONS

For debugging purposes, XML::LibXSLT provides version information about the libxslt C library (but do not confuse it with the version number of XML::LibXSLT module itself, i.e. with $XML::LibXSLT::VERSION). XML::LibXSLT issues a warning if the runtime version of the library is less then the compile-time version.

XML::LibXSLT::LIBXSLT_VERSION()

Returns version number of libxslt library which was used to compile XML::LibXSLT as an integer. For example, for libxslt-1.1.15, it will return 10115.

XML::LibXSLT::LIBXSLT_DOTTED_VERSION()

Returns version number of libxslt library which was used to compile XML::LibXSLT as a string, e.g. "1.1.15".

XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()

Returns version number of libxslt library to which XML::LibXSLT is linked at runtime (either dynamically or statically). For example, for example, for libxslt.so.1.1.15, it will return 10115.

AUTHOR

Matt Sergeant, matt@sergeant.org

Security callbacks implementation contributed by Shane Corgatelli.

Copyright 2001-2006, AxKit.com Ltd. All rights reserved.

SEE ALSO

XML::LibXML


XML::NamespaceSupport - a simple generic namespace support class

  • METHODS
  • VARIABLES
  • TODO
  • AUTHOR
  • COPYRIGHT
  • SEE ALSO

NAME

XML::NamespaceSupport - a simple generic namespace support class

SYNOPSIS

  use XML::NamespaceSupport;
  my $nsup = XML::NamespaceSupport->new;

  # add a new empty context
  $nsup->push_context;
  # declare a few prefixes
  $nsup->declare_prefix($prefix1, $uri1);
  $nsup->declare_prefix($prefix2, $uri2);
  # the same shorter
  $nsup->declare_prefixes($prefix1 => $uri1, $prefix2 => $uri2);

  # get a single prefix for a URI (randomly)
  $prefix = $nsup->get_prefix($uri);
  # get all prefixes for a URI (probably better)
  @prefixes = $nsup->get_prefixes($uri);
  # get all prefixes in scope
  @prefixes = $nsup->get_prefixes();
  # get all prefixes that were declared for the current scope
  @prefixes = $nsup->get_declared_prefixes;
  # get a URI for a given prefix
  $uri = $nsup->get_uri($prefix);

  # get info on a qname (java-ish way, it's a bit weird)
  ($ns_uri, $local_name, $qname) = $nsup->process_name($qname, $is_attr);
  # the same, more perlish
  ($ns_uri, $prefix, $local_name) = $nsup->process_element_name($qname);
  ($ns_uri, $prefix, $local_name) = $nsup->process_attribute_name($qname);

  # remove the current context
  $nsup->pop_context;

  # reset the object for reuse in another document
  $nsup->reset;

  # a simple helper to process Clarkian Notation
  my ($ns, $lname) = $nsup->parse_jclark_notation('{http://foo}bar');
  # or (given that it doesn't care about the object
  my ($ns, $lname) = XML::NamespaceSupport->parse_jclark_notation('{http://foo}bar');

DESCRIPTION

This module offers a simple to process namespaced XML names (unames) from within any application that may need them. It also helps maintain a prefix to namespace URI map, and provides a number of basic checks.

The model for this module is SAX2's NamespaceSupport class, readable at http://www.megginson.com/SAX/Java/javadoc/org/xml/sax/helpers/NamespaceSupport.html. It adds a few perlisations where we thought it appropriate.

METHODS

  • XML::NamespaceSupport->new(\%options)

    A simple constructor.

    The options are xmlns, fatal_errors, and auto_prefix

    If xmlns is turned on (it is off by default) the mapping from the xmlns prefix to the URI defined for it in DOM level 2 is added to the list of predefined mappings (which normally only contains the xml prefix mapping).

    If fatal_errors is turned off (it is on by default) a number of validity errors will simply be flagged as failures, instead of die()ing.

    If auto_prefix is turned on (it is off by default) when one provides a prefix of undef to declare_prefix it will generate a random prefix mapped to that namespace. Otherwise an undef prefix will trigger a warning (you should probably know what you're doing if you turn this option on).

    If xmlns_11 us turned off, it becomes illegal to undeclare namespace prefixes. It is on by default. This behaviour is compliant with Namespaces in XML 1.1, turning it off reverts you to version 1.0.

  • $nsup->push_context

    Adds a new empty context to the stack. You can then populate it with new prefixes defined at this level.

  • $nsup->pop_context

    Removes the topmost context in the stack and reverts to the previous one. It will die() if you try to pop more than you have pushed.

  • $nsup->declare_prefix($prefix, $uri)

    Declares a mapping of $prefix to $uri, at the current level.

    Note that with auto_prefix turned on, if you declare a prefix mapping in which $prefix is undef(), you will get an automatic prefix selected for you. If it is off you will get a warning.

    This is useful when you deal with code that hasn't kept prefixes around and need to reserialize the nodes. It also means that if you want to set the default namespace (ie with an empty prefix) you must use the empty string instead of undef. This behaviour is consistent with the SAX 2.0 specification.

  • $nsup->declare_prefixes(%prefixes2uris)

    Declares a mapping of several prefixes to URIs, at the current level.

  • $nsup->get_prefix($uri)

    Returns a prefix given an URI. Note that as several prefixes may be mapped to the same URI, it returns an arbitrary one. It'll return undef on failure.

  • $nsup->get_prefixes($uri)

    Returns an array of prefixes given an URI. It'll return all the prefixes if the uri is undef.

  • $nsup->get_declared_prefixes

    Returns an array of all the prefixes that have been declared within this context, ie those that were declared on the last element, not those that were declared above and are simply in scope.

  • $nsup->get_uri($prefix)

    Returns a URI for a given prefix. Returns undef on failure.

  • $nsup->process_name($qname, $is_attr)

    Given a qualified name and a boolean indicating whether this is an attribute or another type of name (those are differently affected by default namespaces), it returns a namespace URI, local name, qualified name tuple. I know that that is a rather abnormal list to return, but it is so for compatibility with the Java spec. See below for more Perlish alternatives.

    If the prefix is not declared, or if the name is not valid, it'll either die or return undef depending on the current setting of fatal_errors.

  • $nsup->undeclare_prefix($prefix);

    Removes a namespace prefix from the current context. This function may be used in SAX's end_prefix_mapping when there is fear that a namespace declaration might be available outside their scope (which shouldn't normally happen, but you never know ;). This may be needed in order to properly support Namespace 1.1.

  • $nsup->process_element_name($qname)

    Given a qualified name, it returns a namespace URI, prefix, and local name tuple. This method applies to element names.

    If the prefix is not declared, or if the name is not valid, it'll either die or return undef depending on the current setting of fatal_errors.

  • $nsup->process_attribute_name($qname)

    Given a qualified name, it returns a namespace URI, prefix, and local name tuple. This method applies to attribute names.

    If the prefix is not declared, or if the name is not valid, it'll either die or return undef depending on the current setting of fatal_errors.

  • $nsup->reset

    Resets the object so that it can be reused on another document.

All methods of the interface have an alias that is the name used in the original Java specification. You can use either name interchangeably. Here is the mapping:

  Java name                 Perl name
  ---------------------------------------------------
  pushContext               push_context
  popContext                pop_context
  declarePrefix             declare_prefix
  declarePrefixes           declare_prefixes
  getPrefix                 get_prefix
  getPrefixes               get_prefixes
  getDeclaredPrefixes       get_declared_prefixes
  getURI                    get_uri
  processName               process_name
  processElementName        process_element_name
  processAttributeName      process_attribute_name
  parseJClarkNotation       parse_jclark_notation
  undeclarePrefix           undeclare_prefix

VARIABLES

Two global variables are made available to you. They used to be constants but simple scalars are easier to use in a number of contexts. They are not exported but can easily be accessed from any package, or copied into it.

  • $NS_XMLNS

    The namespace for xmlns prefixes, http://www.w3.org/2000/xmlns/.

  • $NS_XML

    The namespace for xml prefixes, http://www.w3.org/XML/1998/namespace.

TODO

 - add more tests
 - optimise here and there

AUTHOR

Robin Berjon, robin@knowscape.com, with lots of it having been done by Duncan Cameron, and a number of suggestions from the perl-xml list.

COPYRIGHT

Copyright (c) 2001-2005 Robin Berjon. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

XML::Parser::PerlSAX


XML::Parser - A perl module for parsing XML documents

  • METHODS
  • HANDLERS
    • Init (Expat)
    • Final (Expat)
    • Start (Expat, Element [, Attr, Val [,...]])
    • End (Expat, Element)
    • Char (Expat, String)
    • Proc (Expat, Target, Data)
    • Comment (Expat, Data)
    • CdataStart (Expat)
    • CdataEnd (Expat)
    • Default (Expat, String)
    • Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)
    • Notation (Expat, Notation, Base, Sysid, Pubid)
    • ExternEnt (Expat, Base, Sysid, Pubid)
    • ExternEntFin (Expat)
    • Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)
    • Element (Expat, Name, Model)
    • Attlist (Expat, Elname, Attname, Type, Default, Fixed)
    • Doctype (Expat, Name, Sysid, Pubid, Internal)
    • * DoctypeFin (Parser)
    • XMLDecl (Expat, Version, Encoding, Standalone)
  • STYLES
    • Debug
    • Subs
    • Tree
    • Objects
    • Stream
  • ENCODINGS
  • AUTHORS

NAME

XML::Parser - A perl module for parsing XML documents

SYNOPSIS

  use XML::Parser;

  $p1 = new XML::Parser(Style => 'Debug');
  $p1->parsefile('REC-xml-19980210.xml');
  $p1->parse('<foo id="me">Hello World</foo>');

  # Alternative
  $p2 = new XML::Parser(Handlers => {Start => \&handle_start,
                                     End   => \&handle_end,
                                     Char  => \&handle_char});
  $p2->parse($socket);

  # Another alternative
  $p3 = new XML::Parser(ErrorContext => 2);

  $p3->setHandlers(Char    => \&text,
                   Default => \&other);

  open(FOO, 'xmlgenerator |');
  $p3->parse(*FOO, ProtocolEncoding => 'ISO-8859-1');
  close(FOO);

  $p3->parsefile('junk.xml', ErrorContext => 3);

DESCRIPTION

This module provides ways to parse XML documents. It is built on top of the XML::Parser::Expat manpage, which is a lower level interface to James Clark's expat library. Each call to one of the parsing methods creates a new instance of XML::Parser::Expat which is then used to parse the document. Expat options may be provided when the XML::Parser object is created. These options are then passed on to the Expat object on each parse call. They can also be given as extra arguments to the parse methods, in which case they override options given at XML::Parser creation time.

The behavior of the parser is controlled either by /Style and/or /Handlers options, or by setHandlers method. These all provide mechanisms for XML::Parser to set the handlers needed by XML::Parser::Expat. If neither Style nor Handlers are specified, then parsing just checks the document for being well-formed.

When underlying handlers get called, they receive as their first parameter the Expat object, not the Parser object.

METHODS

new

This is a class method, the constructor for XML::Parser. Options are passed as keyword value pairs. Recognized options are:

  • Style

    This option provides an easy way to create a given style of parser. The built in styles are: Debug, Subs, Tree, Objects, and Stream. These are all defined in separate packages under XML::Parser::Style::*, and you can find further documentation for each style both below, and in those packages.

    Custom styles can be provided by giving a full package name containing at least one '::'. This package should then have subs defined for each handler it wishes to have installed. See STYLES below for a discussion of each built in style.

  • Handlers

    When provided, this option should be an anonymous hash containing as keys the type of handler and as values a sub reference to handle that type of event. All the handlers get passed as their 1st parameter the instance of expat that is parsing the document. Further details on handlers can be found in HANDLERS. Any handler set here overrides the corresponding handler set with the Style option.

  • Pkg

    Some styles will refer to subs defined in this package. If not provided, it defaults to the package which called the constructor.

  • ErrorContext

    This is an Expat option. When this option is defined, errors are reported in context. The value should be the number of lines to show on either side of the line in which the error occurred.

  • ProtocolEncoding

    This is an Expat option. This sets the protocol encoding name. It defaults to none. The built-in encodings are: UTF-8, ISO-8859-1, UTF-16, and US-ASCII. Other encodings may be used if they have encoding maps in one of the directories in the @Encoding_Path list. Check ENCODINGS for more information on encoding maps. Setting the protocol encoding overrides any encoding in the XML declaration.

  • Namespaces

    This is an Expat option. If this is set to a true value, then namespace processing is done during the parse. See Namespaces in the XML::Parser::Expat manpage for further discussion of namespace processing.

  • NoExpand

    This is an Expat option. Normally, the parser will try to expand references to entities defined in the internal subset. If this option is set to a true value, and a default handler is also set, then the default handler will be called when an entity reference is seen in text. This has no effect if a default handler has not been registered, and it has no effect on the expansion of entity references inside attribute values.

  • Stream_Delimiter

    This is an Expat option. It takes a string value. When this string is found alone on a line while parsing from a stream, then the parse is ended as if it saw an end of file. The intended use is with a stream of xml documents in a MIME multipart format. The string should not contain a trailing newline.

  • ParseParamEnt

    This is an Expat option. Unless standalone is set to "yes" in the XML declaration, setting this to a true value allows the external DTD to be read, and parameter entities to be parsed and expanded.

  • NoLWP

    This option has no effect if the ExternEnt or ExternEntFin handlers are directly set. Otherwise, if true, it forces the use of a file based external entity handler.

  • Non-Expat-Options

    If provided, this should be an anonymous hash whose keys are options that shouldn't be passed to Expat. This should only be of concern to those subclassing XML::Parser.

setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])

This method registers handlers for various parser events. It overrides any previous handlers registered through the Style or Handler options or through earlier calls to setHandlers. By providing a false or undefined value as the handler, the existing handler can be unset.

This method returns a list of type, handler pairs corresponding to the input. The handlers returned are the ones that were in effect prior to the call.

See a description of the handler types in HANDLERS.

parse(SOURCE [, OPT => OPT_VALUE [...]])

The SOURCE parameter should either be a string containing the whole XML document, or it should be an open IO::Handle. Constructor options to XML::Parser::Expat given as keyword-value pairs may follow the SOURCE parameter. These override, for this call, any options or attributes passed through from the XML::Parser instance.

A die call is thrown if a parse error occurs. Otherwise it will return 1 or whatever is returned from the Final handler, if one is installed. In other words, what parse may return depends on the style.

parsestring

This is just an alias for parse for backwards compatibility.

parsefile(FILE [, OPT => OPT_VALUE [...]])

Open FILE for reading, then call parse with the open handle. The file is closed no matter how parse returns. Returns what parse returns.

parse_start([ OPT => OPT_VALUE [...]])

Create and return a new instance of XML::Parser::ExpatNB. Constructor options may be provided. If an init handler has been provided, it is called before returning the ExpatNB object. Documents are parsed by making incremental calls to the parse_more method of this object, which takes a string. A single call to the parse_done method of this object, which takes no arguments, indicates that the document is finished.

If there is a final handler installed, it is executed by the parse_done method before returning and the parse_done method returns whatever is returned by the final handler.

HANDLERS

Expat is an event based parser. As the parser recognizes parts of the document (say the start or end tag for an XML element), then any handlers registered for that type of an event are called with suitable parameters. All handlers receive an instance of XML::Parser::Expat as their first argument. See METHODS in the XML::Parser::Expat manpage for a discussion of the methods that can be called on this object.

Init (Expat)

This is called just before the parsing of the document starts.

Final (Expat)

This is called just after parsing has finished, but only if no errors occurred during the parse. Parse returns what this returns.

Start (Expat, Element [, Attr, Val [,...]])

This event is generated when an XML start tag is recognized. Element is the name of the XML element type that is opened with the start tag. The Attr & Val pairs are generated for each attribute in the start tag.

End (Expat, Element)

This event is generated when an XML end tag is recognized. Note that an XML empty tag (<foo/>) generates both a start and an end event.

Char (Expat, String)

This event is generated when non-markup is recognized. The non-markup sequence of characters is in String. A single non-markup sequence of characters may generate multiple calls to this handler. Whatever the encoding of the string in the original document, this is given to the handler in UTF-8.

Proc (Expat, Target, Data)

This event is generated when a processing instruction is recognized.

Comment (Expat, Data)

This event is generated when a comment is recognized.

CdataStart (Expat)

This is called at the start of a CDATA section.

CdataEnd (Expat)

This is called at the end of a CDATA section.

Default (Expat, String)

This is called for any characters that don't have a registered handler. This includes both characters that are part of markup for which no events are generated (markup declarations) and characters that could generate events, but for which no handler has been registered.

Whatever the encoding in the original document, the string is returned to the handler in UTF-8.

Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)

This is called for a declaration of an unparsed entity. Entity is the name of the entity. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Notation is the notation name. Base and Pubid may be undefined.

Notation (Expat, Notation, Base, Sysid, Pubid)

This is called for a declaration of notation. Notation is the notation name. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Base, Sysid, and Pubid may all be undefined.

ExternEnt (Expat, Base, Sysid, Pubid)

This is called when an external entity is referenced. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Base, and Pubid may be undefined.

This handler should either return a string, which represents the contents of the external entity, or return an open filehandle that can be read to obtain the contents of the external entity, or return undef, which indicates the external entity couldn't be found and will generate a parse error.

If an open filehandle is returned, it must be returned as either a glob (*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).

A default handler is installed for this event. The default handler is XML::Parser::lwp_ext_ent_handler unless the NoLWP option was provided with a true value, otherwise XML::Parser::file_ext_ent_handler is the default handler for external entities. Even without the NoLWP option, if the URI or LWP modules are missing, the file based handler ends up being used after giving a warning on the first external entity reference.

The LWP external entity handler will use proxies defined in the environment (http_proxy, ftp_proxy, etc.).

Please note that the LWP external entity handler reads the entire entity into a string and returns it, where as the file handler opens a filehandle.

Also note that the file external entity handler will likely choke on absolute URIs or file names that don't fit the conventions of the local operating system.

The expat base method can be used to set a basename for relative pathnames. If no basename is given, or if the basename is itself a relative name, then it is relative to the current working directory.

ExternEntFin (Expat)

This is called after parsing an external entity. It's not called unless an ExternEnt handler is also set. There is a default handler installed that pairs with the default ExternEnt handler.

If you're going to install your own ExternEnt handler, then you should set (or unset) this handler too.

Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)

This is called when an entity is declared. For internal entities, the Val parameter will contain the value and the remaining three parameters will be undefined. For external entities, the Val parameter will be undefined, the Sysid parameter will have the system id, the Pubid parameter will have the public id if it was provided (it will be undefined otherwise), the Ndata parameter will contain the notation for unparsed entities. If this is a parameter entity declaration, then the IsParam parameter is true.

Note that this handler and the Unparsed handler above overlap. If both are set, then this handler will not be called for unparsed entities.

Element (Expat, Name, Model)

The element handler is called when an element declaration is found. Name is the element name, and Model is the content model as an XML::Parser::Content object. See XML::Parser::ContentModel Methods in the XML::Parser::Expat manpage for methods available for this class.

Attlist (Expat, Elname, Attname, Type, Default, Fixed)

This handler is called for each attribute in an ATTLIST declaration. So an ATTLIST declaration that has multiple attributes will generate multiple calls to this handler. The Elname parameter is the name of the element with which the attribute is being associated. The Attname parameter is the name of the attribute. Type is the attribute type, given as a string. Default is the default value, which will either be "#REQUIRED", "#IMPLIED" or a quoted string (i.e. the returned string will begin and end with a quote character). If Fixed is true, then this is a fixed attribute.

Doctype (Expat, Name, Sysid, Pubid, Internal)

This handler is called for DOCTYPE declarations. Name is the document type name. Sysid is the system id of the document type, if it was provided, otherwise it's undefined. Pubid is the public id of the document type, which will be undefined if no public id was given. Internal is the internal subset, given as a string. If there was no internal subset, it will be undefined. Internal will contain all whitespace, comments, processing instructions, and declarations seen in the internal subset. The declarations will be there whether or not they have been processed by another handler (except for unparsed entities processed by the Unparsed handler). However, comments and processing instructions will not appear if they've been processed by their respective handlers.

* DoctypeFin (Parser)

This handler is called after parsing of the DOCTYPE declaration has finished, including any internal or external DTD declarations.

XMLDecl (Expat, Version, Encoding, Standalone)

This handler is called for xml declarations. Version is a string containg the version. Encoding is either undefined or contains an encoding string. Standalone will be either true, false, or undefined if the standalone attribute is yes, no, or not made respectively.

STYLES

Debug

This just prints out the document in outline form. Nothing special is returned by parse.

Subs

Each time an element starts, a sub by that name in the package specified by the Pkg option is called with the same parameters that the Start handler gets called with.

Each time an element ends, a sub with that name appended with an underscore ("_"), is called with the same parameters that the End handler gets called with.

Nothing special is returned by parse.

Tree

Parse will return a parse tree for the document. Each node in the tree takes the form of a tag, content pair. Text nodes are represented with a pseudo-tag of "0" and the string that is their content. For elements, the content is an array reference. The first item in the array is a (possibly empty) hash reference containing attributes. The remainder of the array is a sequence of tag-content pairs representing the content of the element.

So for example the result of parsing:

  <foo><head id="a">Hello <em>there</em></head><bar>Howdy<ref/></bar>do</foo>

would be:

             Tag   Content
               ==================================================================
               [foo, [{}, head, [{id => "a"}, 0, "Hello ",  em, [{}, 0, "there"]],
              bar, [         {}, 0, "Howdy",  ref, [{}]],
                0, "do"
                     ]
               ]

The root document "foo", has 3 children: a "head" element, a "bar" element and the text "do". After the empty attribute hash, these are represented in it's contents by 3 tag-content pairs.

Objects

This is similar to the Tree style, except that a hash object is created for each element. The corresponding object will be in the class whose name is created by appending "::" and the element name to the package set with the Pkg option. Non-markup text will be in the ::Characters class. The contents of the corresponding object will be in an anonymous array that is the value of the Kids property for that object.

Stream

This style also uses the Pkg package. If none of the subs that this style looks for is there, then the effect of parsing with this style is to print a canonical copy of the document without comments or declarations. All the subs receive as their 1st parameter the Expat instance for the document they're parsing.

It looks for the following routines:

  • StartDocument

    Called at the start of the parse .

  • StartTag

    Called for every start tag with a second parameter of the element type. The $_ variable will contain a copy of the tag and the %_ variable will contain attribute values supplied for that element.

  • EndTag

    Called for every end tag with a second parameter of the element type. The $_ variable will contain a copy of the end tag.

  • Text

    Called just before start or end tags with accumulated non-markup text in the $_ variable.

  • PI

    Called for processing instructions. The $_ variable will contain a copy of the PI and the target and data are sent as 2nd and 3rd parameters respectively.

  • EndDocument

    Called at conclusion of the parse.

ENCODINGS

XML documents may be encoded in character sets other than Unicode as long as they may be mapped into the Unicode character set. Expat has further restrictions on encodings. Read the xmlparse.h header file in the expat distribution to see details on these restrictions.

Expat has built-in encodings for: UTF-8, ISO-8859-1, UTF-16, and US-ASCII. Encodings are set either through the XML declaration encoding attribute or through the ProtocolEncoding option to XML::Parser or XML::Parser::Expat.

For encodings other than the built-ins, expat calls the function load_encoding in the Expat package with the encoding name. This function looks for a file in the path list @XML::Parser::Expat::Encoding_Path, that matches the lower-cased name with a '.enc' extension. The first one it finds, it loads.

If you wish to build your own encoding maps, check out the XML::Encoding module from CPAN.

AUTHORS

Larry Wall <larry@wall.org> wrote version 1.0.

Clark Cooper <coopercc@netheaven.com> picked up support, changed the API for this version (2.x), provided documentation, and added some standard package features.

Matt Sergeant <matt@sergeant.org> is now maintaining XML::Parser


XML::Parser::Expat - Lowlevel access to James Clark's expat XML parser

  • METHODS
    • XML::Parser::ContentModel Methods
    • XML::Parser::ExpatNB Methods
  • FUNCTIONS
  • AUTHORS

NAME

XML::Parser::Expat - Lowlevel access to James Clark's expat XML parser

SYNOPSIS

 use XML::Parser::Expat;

 $parser = new XML::Parser::Expat;
 $parser->setHandlers('Start' => \&sh,
                      'End'   => \&eh,
                      'Char'  => \&ch);
 open(FOO, 'info.xml') or die "Couldn't open";
 $parser->parse(*FOO);
 close(FOO);
 # $parser->parse('<foo id="me"> here <em>we</em> go </foo>');

 sub sh
 {
   my ($p, $el, %atts) = @_;
   $p->setHandlers('Char' => \&spec)
     if ($el eq 'special');
   ...
 }

 sub eh
 {
   my ($p, $el) = @_;
   $p->setHandlers('Char' => \&ch)  # Special elements won't contain
     if ($el eq 'special');         # other special elements
   ...
 }

DESCRIPTION

This module provides an interface to James Clark's XML parser, expat. As in expat, a single instance of the parser can only parse one document. Calls to parsestring after the first for a given instance will die.

Expat (and XML::Parser::Expat) are event based. As the parser recognizes parts of the document (say the start or end of an XML element), then any handlers registered for that type of an event are called with suitable parameters.

METHODS

new

This is a class method, the constructor for XML::Parser::Expat. Options are passed as keyword value pairs. The recognized options are:

  • ProtocolEncoding

    The protocol encoding name. The default is none. The expat built-in encodings are: UTF-8, ISO-8859-1, UTF-16, and US-ASCII. Other encodings may be used if they have encoding maps in one of the directories in the @Encoding_Path list. Setting the protocol encoding overrides any encoding in the XML declaration.

  • Namespaces

    When this option is given with a true value, then the parser does namespace processing. By default, namespace processing is turned off. When it is turned on, the parser consumes xmlns attributes and strips off prefixes from element and attributes names where those prefixes have a defined namespace. A name's namespace can be found using the namespace method and two names can be checked for absolute equality with the eq_name method.

  • NoExpand

    Normally, the parser will try to expand references to entities defined in the internal subset. If this option is set to a true value, and a default handler is also set, then the default handler will be called when an entity reference is seen in text. This has no effect if a default handler has not been registered, and it has no effect on the expansion of entity references inside attribute values.

  • Stream_Delimiter

    This option takes a string value. When this string is found alone on a line while parsing from a stream, then the parse is ended as if it saw an end of file. The intended use is with a stream of xml documents in a MIME multipart format. The string should not contain a trailing newline.

  • ErrorContext

    When this option is defined, errors are reported in context. The value of ErrorContext should be the number of lines to show on either side of the line in which the error occurred.

  • ParseParamEnt

    Unless standalone is set to "yes" in the XML declaration, setting this to a true value allows the external DTD to be read, and parameter entities to be parsed and expanded.

  • Base

    The base to use for relative pathnames or URLs. This can also be done by using the base method.

setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])

This method registers handlers for the various events. If no handlers are registered, then a call to parsestring or parsefile will only determine if the corresponding XML document is well formed (by returning without error.) This may be called from within a handler, after the parse has started.

Setting a handler to something that evaluates to false unsets that handler.

This method returns a list of type, handler pairs corresponding to the input. The handlers returned are the ones that were in effect before the call to setHandlers.

The recognized events and the parameters passed to the corresponding handlers are:

  • Start (Parser, Element [, Attr, Val [,...]])

    This event is generated when an XML start tag is recognized. Parser is an XML::Parser::Expat instance. Element is the name of the XML element that is opened with the start tag. The Attr & Val pairs are generated for each attribute in the start tag.

  • End (Parser, Element)

    This event is generated when an XML end tag is recognized. Note that an XML empty tag (<foo/>) generates both a start and an end event.

    There is always a lower level start and end handler installed that wrap the corresponding callbacks. This is to handle the context mechanism. A consequence of this is that the default handler (see below) will not see a start tag or end tag unless the default_current method is called.

  • Char (Parser, String)

    This event is generated when non-markup is recognized. The non-markup sequence of characters is in String. A single non-markup sequence of characters may generate multiple calls to this handler. Whatever the encoding of the string in the original document, this is given to the handler in UTF-8.

  • Proc (Parser, Target, Data)

    This event is generated when a processing instruction is recognized.

  • Comment (Parser, String)

    This event is generated when a comment is recognized.

  • CdataStart (Parser)

    This is called at the start of a CDATA section.

  • CdataEnd (Parser)

    This is called at the end of a CDATA section.

  • Default (Parser, String)

    This is called for any characters that don't have a registered handler. This includes both characters that are part of markup for which no events are generated (markup declarations) and characters that could generate events, but for which no handler has been registered.

    Whatever the encoding in the original document, the string is returned to the handler in UTF-8.

  • Unparsed (Parser, Entity, Base, Sysid, Pubid, Notation)

    This is called for a declaration of an unparsed entity. Entity is the name of the entity. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Notation is the notation name. Base and Pubid may be undefined.

  • Notation (Parser, Notation, Base, Sysid, Pubid)

    This is called for a declaration of notation. Notation is the notation name. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Base, Sysid, and Pubid may all be undefined.

  • ExternEnt (Parser, Base, Sysid, Pubid)

    This is called when an external entity is referenced. Base is the base to be used for resolving a relative URI. Sysid is the system id. Pubid is the public id. Base, and Pubid may be undefined.

    This handler should either return a string, which represents the contents of the external entity, or return an open filehandle that can be read to obtain the contents of the external entity, or return undef, which indicates the external entity couldn't be found and will generate a parse error.

    If an open filehandle is returned, it must be returned as either a glob (*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).

  • ExternEntFin (Parser)

    This is called after an external entity has been parsed. It allows applications to perform cleanup on actions performed in the above ExternEnt handler.

  • Entity (Parser, Name, Val, Sysid, Pubid, Ndata, IsParam)

    This is called when an entity is declared. For internal entities, the Val parameter will contain the value and the remaining three parameters will be undefined. For external entities, the Val parameter will be undefined, the Sysid parameter will have the system id, the Pubid parameter will have the public id if it was provided (it will be undefined otherwise), the Ndata parameter will contain the notation for unparsed entities. If this is a parameter entity declaration, then the IsParam parameter is true.

    Note that this handler and the Unparsed handler above overlap. If both are set, then this handler will not be called for unparsed entities.

  • Element (Parser, Name, Model)

    The element handler is called when an element declaration is found. Name is the element name, and Model is the content model as an XML::Parser::ContentModel object. See XML::Parser::ContentModel Methods for methods available for this class.

  • Attlist (Parser, Elname, Attname, Type, Default, Fixed)

    This handler is called for each attribute in an ATTLIST declaration. So an ATTLIST declaration that has multiple attributes will generate multiple calls to this handler. The Elname parameter is the name of the element with which the attribute is being associated. The Attname parameter is the name of the attribute. Type is the attribute type, given as a string. Default is the default value, which will either be "#REQUIRED", "#IMPLIED" or a quoted string (i.e. the returned string will begin and end with a quote character). If Fixed is true, then this is a fixed attribute.

  • Doctype (Parser, Name, Sysid, Pubid, Internal)

    This handler is called for DOCTYPE declarations. Name is the document type name. Sysid is the system id of the document type, if it was provided, otherwise it's undefined. Pubid is the public id of the document type, which will be undefined if no public id was given. Internal will be true or false, indicating whether or not the doctype declaration contains an internal subset.

  • DoctypeFin (Parser)

    This handler is called after parsing of the DOCTYPE declaration has finished, including any internal or external DTD declarations.

  • XMLDecl (Parser, Version, Encoding, Standalone)

    This handler is called for XML declarations. Version is a string containg the version. Encoding is either undefined or contains an encoding string. Standalone is either undefined, or true or false. Undefined indicates that no standalone parameter was given in the XML declaration. True or false indicates "yes" or "no" respectively.

namespace(name)

Return the URI of the namespace that the name belongs to. If the name doesn't belong to any namespace, an undef is returned. This is only valid on names received through the Start or End handlers from a single document, or through a call to the generate_ns_name method. In other words, don't use names generated from one instance of XML::Parser::Expat with other instances.

eq_name(name1, name2)

Return true if name1 and name2 are identical (i.e. same name and from the same namespace.) This is only meaningful if both names were obtained through the Start or End handlers from a single document, or through a call to the generate_ns_name method.

generate_ns_name(name, namespace)

Return a name, associated with a given namespace, good for using with the above 2 methods. The namespace argument should be the namespace URI, not a prefix.

new_ns_prefixes

When called from a start tag handler, returns namespace prefixes declared with this start tag. If called elsewere (or if there were no namespace prefixes declared), it returns an empty list. Setting of the default namespace is indicated with '#default' as a prefix.

expand_ns_prefix(prefix)

Return the uri to which the given prefix is currently bound. Returns undef if the prefix isn't currently bound. Use '#default' to find the current binding of the default namespace (if any).

current_ns_prefixes

Return a list of currently bound namespace prefixes. The order of the the prefixes in the list has no meaning. If the default namespace is currently bound, '#default' appears in the list.

recognized_string

Returns the string from the document that was recognized in order to call the current handler. For instance, when called from a start handler, it will give us the the start-tag string. The string is encoded in UTF-8. This method doesn't return a meaningful string inside declaration handlers.

original_string

Returns the verbatim string from the document that was recognized in order to call the current handler. The string is in the original document encoding. This method doesn't return a meaningful string inside declaration handlers.

default_current

When called from a handler, causes the sequence of characters that generated the corresponding event to be sent to the default handler (if one is registered). Use of this method is deprecated in favor the recognized_string method, which you can use without installing a default handler. This method doesn't deliver a meaningful string to the default handler when called from inside declaration handlers.

xpcroak(message)

Concatenate onto the given message the current line number within the XML document plus the message implied by ErrorContext. Then croak with the formed message.

xpcarp(message)

Concatenate onto the given message the current line number within the XML document plus the message implied by ErrorContext. Then carp with the formed message.

current_line

Returns the line number of the current position of the parse.

current_column

Returns the column number of the current position of the parse.

current_byte

Returns the current position of the parse.

base([NEWBASE]);

Returns the current value of the base for resolving relative URIs. If NEWBASE is supplied, changes the base to that value.

context

Returns a list of element names that represent open elements, with the last one being the innermost. Inside start and end tag handlers, this will be the tag of the parent element.

current_element

Returns the name of the innermost currently opened element. Inside start or end handlers, returns the parent of the element associated with those tags.

in_element(NAME)

Returns true if NAME is equal to the name of the innermost currently opened element. If namespace processing is being used and you want to check against a name that may be in a namespace, then use the generate_ns_name method to create the NAME argument.

within_element(NAME)

Returns the number of times the given name appears in the context list. If namespace processing is being used and you want to check against a name that may be in a namespace, then use the generate_ns_name method to create the NAME argument.

depth

Returns the size of the context list.

element_index

Returns an integer that is the depth-first visit order of the current element. This will be zero outside of the root element. For example, this will return 1 when called from the start handler for the root element start tag.

skip_until(INDEX)

INDEX is an integer that represents an element index. When this method is called, all handlers are suspended until the start tag for an element that has an index number equal to INDEX is seen. If a start handler has been set, then this is the first tag that the start handler will see after skip_until has been called.

position_in_context(LINES)

Returns a string that shows the current parse position. LINES should be an integer >= 0 that represents the number of lines on either side of the current parse line to place into the returned string.

xml_escape(TEXT [, CHAR [, CHAR ...]])

Returns TEXT with markup characters turned into character entities. Any additional characters provided as arguments are also turned into character references where found in TEXT.

parse (SOURCE)

The SOURCE parameter should either be a string containing the whole XML document, or it should be an open IO::Handle. Only a single document may be parsed for a given instance of XML::Parser::Expat, so this will croak if it's been called previously for this instance.

parsestring(XML_DOC_STRING)

Parses the given string as an XML document. Only a single document may be parsed for a given instance of XML::Parser::Expat, so this will die if either parsestring or parsefile has been called for this instance previously.

This method is deprecated in favor of the parse method.

parsefile(FILENAME)

Parses the XML document in the given file. Will die if parsestring or parsefile has been called previously for this instance.

is_defaulted(ATTNAME)

NO LONGER WORKS. To find out if an attribute is defaulted please use the specified_attr method.

specified_attr

When the start handler receives lists of attributes and values, the non-defaulted (i.e. explicitly specified) attributes occur in the list first. This method returns the number of specified items in the list. So if this number is equal to the length of the list, there were no defaulted values. Otherwise the number points to the index of the first defaulted attribute name.

finish

Unsets all handlers (including internal ones that set context), but expat continues parsing to the end of the document or until it finds an error. It should finish up a lot faster than with the handlers set.

release

There are data structures used by XML::Parser::Expat that have circular references. This means that these structures will never be garbage collected unless these references are explicitly broken. Calling this method breaks those references (and makes the instance unusable.)

Normally, higher level calls handle this for you, but if you are using XML::Parser::Expat directly, then it's your responsibility to call it.

XML::Parser::ContentModel Methods

The element declaration handlers are passed objects of this class as the content model of the element declaration. They also represent content particles, components of a content model.

When referred to as a string, these objects are automagicly converted to a string representation of the model (or content particle).

isempty

This method returns true if the object is "EMPTY", false otherwise.

isany

This method returns true if the object is "ANY", false otherwise.

ismixed

This method returns true if the object is "(#PCDATA)" or "(#PCDATA|...)*", false otherwise.

isname

This method returns if the object is an element name.

ischoice

This method returns true if the object is a choice of content particles.

isseq

This method returns true if the object is a sequence of content particles.

quant

This method returns undef or a string representing the quantifier ('?', '*', '+') associated with the model or particle.

children

This method returns undef or (for mixed, choice, and sequence types) an array of component content particles. There will always be at least one component for choices and sequences, but for a mixed content model of pure PCDATA, "(#PCDATA)", then an undef is returned.

XML::Parser::ExpatNB Methods

The class XML::Parser::ExpatNB is a subclass of XML::Parser::Expat used for non-blocking access to the expat library. It does not support the parse, parsestring, or parsefile methods, but it does have these additional methods:

parse_more(DATA)

Feed expat more text to munch on.

parse_done

Tell expat that it's gotten the whole document.

FUNCTIONS

XML::Parser::Expat::load_encoding(ENCODING)

Load an external encoding. ENCODING is either the name of an encoding or the name of a file. The basename is converted to lowercase and a '.enc' extension is appended unless there's one already there. Then, unless it's an absolute pathname (i.e. begins with '/'), the first file by that name discovered in the @Encoding_Path path list is used.

The encoding in the file is loaded and kept in the %Encoding_Table table. Earlier encodings of the same name are replaced.

This function is automaticly called by expat when it encounters an encoding it doesn't know about. Expat shouldn't call this twice for the same encoding name. The only reason users should use this function is to explicitly load an encoding not contained in the @Encoding_Path list.

AUTHORS

Larry Wall <larry@wall.org> wrote version 1.0.

Clark Cooper <coopercc@netheaven.com> picked up support, changed the API for this version (2.x), provided documentation, and added some standard package features.


XML::Parser::Lite - Lightweight regexp-based XML parser

  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

XML::Parser::Lite - Lightweight regexp-based XML parser

SYNOPSIS

  use XML::Parser::Lite;

  $p1 = new XML::Parser::Lite;
  $p1->setHandlers(
    Start => sub { shift; print "start: @_\n" },
    Char => sub { shift; print "char: @_\n" },
    End => sub { shift; print "end: @_\n" },
  );
  $p1->parse('<foo id="me">Hello World!</foo>');

  $p2 = new XML::Parser::Lite
    Handlers => {
      Start => sub { shift; print "start: @_\n" },
      Char => sub { shift; print "char: @_\n" },
      End => sub { shift; print "end: @_\n" },
    }
  ;
  $p2->parse('<foo id="me">Hello <bar>cruel</bar> World!</foo>');

DESCRIPTION

This Perl module gives you access to XML parser with interface similar to XML::Parser interface. Though only basic calls are supported (init, final, start, char, and end) you should be able to use it in the same way you use XML::Parser. Due to using experimantal regexp features it'll work only on Perl 5.6 and may behave differently on different platforms.

SEE ALSO

 XML::Parser

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This parser is based on "shallow parser" http://www.cs.sfu.ca/~cameron/REX.html Copyright (c) 1998, Robert D. Cameron.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XML::Parser::Style::Debug - Debug style for XML::Parser

NAME

XML::Parser::Style::Debug - Debug style for XML::Parser

SYNOPSIS

  use XML::Parser;
  my $p = XML::Parser->new(Style => 'Debug');
  $p->parsefile('foo.xml');

DESCRIPTION

This just prints out the document in outline form to STDERR. Nothing special is returned by parse.


XML::Parser::Style::Objects - Objects style for XML::Parser

  • SEE ALSO

NAME

XML::Parser::Style::Objects - Objects style for XML::Parser

SYNOPSIS

  use XML::Parser;
  my $p = XML::Parser->new(Style => 'Objects', Pkg => 'MyNode');
  my $tree = $p->parsefile('foo.xml');

DESCRIPTION

This module implements XML::Parser's Objects style parser.

This is similar to the Tree style, except that a hash object is created for each element. The corresponding object will be in the class whose name is created by appending "::" and the element name to the package set with the Pkg option. Non-markup text will be in the ::Characters class. The contents of the corresponding object will be in an anonymous array that is the value of the Kids property for that object.

SEE ALSO

the XML::Parser::Style::Tree manpage


XML::Parser::Style::Stream - Stream style for XML::Parser

NAME

XML::Parser::Style::Stream - Stream style for XML::Parser

SYNOPSIS

  use XML::Parser;
  my $p = XML::Parser->new(Style => 'Stream', Pkg => 'MySubs');
  $p->parsefile('foo.xml');

  {
    package MySubs;

    sub StartTag {
      my ($e, $name) = @_;
      # do something with start tags
    }

    sub EndTag {
      my ($e, $name) = @_;
      # do something with end tags
    }

    sub Characters {
      my ($e, $data) = @_;
      # do something with text nodes
    }
  }

DESCRIPTION

This style uses the Pkg option to find subs in a given package to call for each event. If none of the subs that this style looks for is there, then the effect of parsing with this style is to print a canonical copy of the document without comments or declarations. All the subs receive as their 1st parameter the Expat instance for the document they're parsing.

It looks for the following routines:

  • StartDocument

    Called at the start of the parse .

  • StartTag

    Called for every start tag with a second parameter of the element type. The $_ variable will contain a copy of the tag and the %_ variable will contain attribute values supplied for that element.

  • EndTag

    Called for every end tag with a second parameter of the element type. The $_ variable will contain a copy of the end tag.

  • Text

    Called just before start or end tags with accumulated non-markup text in the $_ variable.

  • PI

    Called for processing instructions. The $_ variable will contain a copy of the PI and the target and data are sent as 2nd and 3rd parameters respectively.

  • EndDocument

    Called at conclusion of the parse.


XML::Parser::Style::Subs - Subs style for XML::Parser

NAME

XML::Parser::Style::Subs - Subs style for XML::Parser

SYNOPSIS

  use XML::Parser;
  my $p = XML::Parser->new(Style => 'Subs', Pkg => 'MySubs');
  $p->parsefile('foo.xml');

  {
    package MySubs;

    sub foo {
      # start of foo tag
    }

    sub foo_ {
      # end of foo tag
    }
  }

DESCRIPTION

Each time an element starts, a sub by that name in the package specified by the Pkg option is called with the same parameters that the Start handler gets called with.

Each time an element ends, a sub with that name appended with an underscore ("_"), is called with the same parameters that the End handler gets called with.

Nothing special is returned by parse.


XML::Parser::Style::Tree - Tree style for XML::Parser

NAME

XML::Parser::Style::Tree - Tree style for XML::Parser

SYNOPSIS

  use XML::Parser;
  my $p = XML::Parser->new(Style => 'Tree');
  my $tree = $p->parsefile('foo.xml');

DESCRIPTION

This module implements XML::Parser's Tree style parser.

When parsing a document, parse() will return a parse tree for the document. Each node in the tree takes the form of a tag, content pair. Text nodes are represented with a pseudo-tag of "0" and the string that is their content. For elements, the content is an array reference. The first item in the array is a (possibly empty) hash reference containing attributes. The remainder of the array is a sequence of tag-content pairs representing the content of the element.

So for example the result of parsing:

  <foo><head id="a">Hello <em>there</em></head><bar>Howdy<ref/></bar>do</foo>

would be:

             Tag   Content
               ==================================================================
               [foo, [{}, head, [{id => "a"}, 0, "Hello ",  em, [{}, 0, "there"]],
              bar, [         {}, 0, "Howdy",  ref, [{}]],
                0, "do"
                     ]
               ]

The root document "foo", has 3 children: a "head" element, a "bar" element and the text "do". After the empty attribute hash, these are represented in it's contents by 3 tag-content pairs.


XML::SAX - Simple API for XML

  • USING A SAX2 PARSER
  • WRITING A SAX2 PARSER
  • EXPORTS
  • AUTHOR
  • LICENSE
  • SEE ALSO

NAME

XML::SAX - Simple API for XML

SYNOPSIS

  use XML::SAX;

  # get a list of known parsers
  my $parsers = XML::SAX->parsers();

  # add/update a parser
  XML::SAX->add_parser(q(XML::SAX::PurePerl));

  # remove parser
  XML::SAX->remove_parser(q(XML::SAX::Foodelberry));

  # save parsers
  XML::SAX->save_parsers();

DESCRIPTION

XML::SAX is a SAX parser access API for Perl. It includes classes and APIs required for implementing SAX drivers, along with a factory class for returning any SAX parser installed on the user's system.

USING A SAX2 PARSER

The factory class is XML::SAX::ParserFactory. Please see the documentation of that module for how to instantiate a SAX parser: the XML::SAX::ParserFactory manpage. However if you don't want to load up another manual page, here's a short synopsis:

  use XML::SAX::ParserFactory;
  use XML::SAX::XYZHandler;
  my $handler = XML::SAX::XYZHandler->new();
  my $p = XML::SAX::ParserFactory->parser(Handler => $handler);
  $p->parse_uri("foo.xml");
  # or $p->parse_string("<foo/>") or $p->parse_file($fh);

This will automatically load a SAX2 parser (defaulting to XML::SAX::PurePerl if no others are found) and return it to you.

In order to learn how to use SAX to parse XML, you will need to read the XML::SAX::Intro manpage and for reference, the XML::SAX::Specification manpage.

WRITING A SAX2 PARSER

The first thing to remember in writing a SAX2 parser is to subclass XML::SAX::Base. This will make your life infinitely easier, by providing a number of methods automagically for you. See the XML::SAX::Base manpage for more details.

When writing a SAX2 parser that is compatible with XML::SAX, you need to inform XML::SAX of the presence of that driver when you install it. In order to do that, XML::SAX contains methods for saving the fact that the parser exists on your system to a "INI" file, which is then loaded to determine which parsers are installed.

The best way to do this is to follow these rules:

  • Add XML::SAX as a prerequisite in Makefile.PL:
      WriteMakefile(
      ...
      PREREQ_PM => { 'XML::SAX' => 0 },
      ...
  );

    Alternatively you may wish to check for it in other ways that will cause more than just a warning.

  • Add the following code snippet to your Makefile.PL:
      sub MY::install {
    package MY;
    my $script = shift->SUPER::install(@_);
    if (ExtUtils::MakeMaker::prompt(
      "Do you want to modify ParserDetails.ini?", 'Y')
      =~ /^y/i) {
      $script =~ s/install :: (.*)$/install :: $1 install_sax_driver/m;
      $script .= <<"INSTALL";

  install_sax_driver :
  \t\@\$(PERL) -MXML::SAX -e "XML::SAX->add_parser(q(\$(NAME)))->save_parsers()"

  INSTALL
    }
    return $script;
  }

    Note that you should check the output of this - \$(NAME) will use the name of your distribution, which may not be exactly what you want. For example XML::LibXML has a driver called XML::LibXML::SAX::Generator, which is used in place of \$(NAME) in the above.

  • Add an XML::SAX test:

    A test file should be added to your t/ directory containing something like the following:

      use Test;
  BEGIN { plan tests => 3 }
  use XML::SAX;
  use XML::SAX::PurePerl::DebugHandler;
  XML::SAX->add_parser(q(XML::SAX::MyDriver));
  local $XML::SAX::ParserPackage = 'XML::SAX::MyDriver';
  eval {
    my $handler = XML::SAX::PurePerl::DebugHandler->new();
    ok($handler);
    my $parser = XML::SAX::ParserFactory->parser(Handler => $handler);
    ok($parser);
    ok($parser->isa('XML::SAX::MyDriver');
    $parser->parse_string("<tag/>");
    ok($handler->{seen}{start_element});
  };

EXPORTS

By default, XML::SAX exports nothing into the caller's namespace. However you can request the symbols Namespaces and Validation which are the URIs for those features, allowing an easier way to request those features via ParserFactory:

  use XML::SAX qw(Namespaces Validation);
  my $factory = XML::SAX::ParserFactory->new();
  $factory->require_feature(Namespaces);
  $factory->require_feature(Validation);
  my $parser = $factory->parser();

AUTHOR

Current maintainer: Grant McLean, grantm@cpan.org

Originally written by:

Matt Sergeant, matt@sergeant.org

Kip Hampton, khampton@totalcinema.com

Robin Berjon, robin@knowscape.com

LICENSE

This is free software, you may use it and distribute it under the same terms as Perl itself.

SEE ALSO

the XML::SAX::Base manpage for writing SAX Filters and Parsers

the XML::SAX::PurePerl manpage for an XML parser written in 100% pure perl.

the XML::SAX::Exception manpage for details on exception handling


XML::SAX::Base - Base class SAX Drivers and Filters

  • WRITING SAX DRIVERS AND FILTERS
  • METHODS
  • TODO
  • AUTHOR
  • SEE ALSO

NAME

XML::SAX::Base - Base class SAX Drivers and Filters

SYNOPSIS

  package MyFilter;
  use XML::SAX::Base;
  @ISA = ('XML::SAX::Base');

DESCRIPTION

This module has a very simple task - to be a base class for PerlSAX drivers and filters. It's default behaviour is to pass the input directly to the output unchanged. It can be useful to use this module as a base class so you don't have to, for example, implement the characters() callback.

The main advantages that it provides are easy dispatching of events the right way (ie it takes care for you of checking that the handler has implemented that method, or has defined an AUTOLOAD), and the guarantee that filters will pass along events that they aren't implementing to handlers downstream that might nevertheless be interested in them.

WRITING SAX DRIVERS AND FILTERS

Writing SAX Filters is tremendously easy: all you need to do is inherit from this module, and define the events you want to handle. A more detailed explanation can be found at http://www.xml.com/pub/a/2001/10/10/sax-filters.html.

Writing Drivers is equally simple. The one thing you need to pay attention to is NOT to call events yourself (this applies to Filters as well). For instance:

  package MyFilter;
  use base qw(XML::SAX::Base);

  sub start_element {
    my $self = shift;
    my $data = shift;
    # do something
    $self->{Handler}->start_element($data); # BAD
  }

The above example works well as precisely that: an example. But it has several faults: 1) it doesn't test to see whether the handler defines start_element. Perhaps it doesn't want to see that event, in which case you shouldn't throw it (otherwise it'll die). 2) it doesn't check ContentHandler and then Handler (ie it doesn't look to see that the user hasn't requested events on a specific handler, and if not on the default one), 3) if it did check all that, not only would the code be cumbersome (see this module's source to get an idea) but it would also probably have to check for a DocumentHandler (in case this were SAX1) and for AUTOLOADs potentially defined in all these packages. As you can tell, that would be fairly painful. Instead of going through that, simply remember to use code similar to the following instead:

  package MyFilter;
  use base qw(XML::SAX::Base);

  sub start_element {
    my $self = shift;
    my $data = shift;
    # do something to filter
    $self->SUPER::start_element($data); # GOOD (and easy) !
  }

This way, once you've done your job you hand the ball back to XML::SAX::Base and it takes care of all those problems for you!

Note that the above example doesn't apply to filters only, drivers will benefit from the exact same feature.

METHODS

A number of methods are defined within this class for the purpose of inheritance. Some probably don't need to be overridden (eg parse_file) but some clearly should be (eg parse). Options for these methods are described in the PerlSAX2 specification available from http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/perl-xml/libxml-perl/doc/sax-2.0.html?rev=HEAD&content-type=text/html.

  • parse

    The parse method is the main entry point to parsing documents. Internally the parse method will detect what type of "thing" you are parsing, and call the appropriate method in your implementation class. Here is the mapping table of what is in the Source options (see the Perl SAX 2.0 specification for the meaning of these values):

      Source Contains           parse() calls
  ===============           =============
  CharacterStream (*)       _parse_characterstream($stream, $options)
  ByteStream                _parse_bytestream($stream, $options)
  String                    _parse_string($string, $options)
  SystemId                  _parse_systemid($string, $options)

    However note that these methods may not be sensible if your driver class is not for parsing XML. An example might be a DBI driver that generates XML/SAX from a database table. If that is the case, you likely want to write your own parse() method.

    Also note that the Source may contain both a PublicId entry, and an Encoding entry. To get at these, examine $options->{Source} as passed to your method.

    (*) A CharacterStream is a filehandle that does not need any encoding translation done on it. This is implemented as a regular filehandle and only works under Perl 5.7.2 or higher using PerlIO. To get a single character, or number of characters from it, use the perl core read() function. To get a single byte from it (or number of bytes), you can use sysread(). The encoding of the stream should be in the Encoding entry for the Source.

  • parse_file, parse_uri, parse_string

    These are all convenience variations on parse(), and in fact simply set up the options before calling it. You probably don't need to override these.

  • get_options

    This is a convenience method to get options in SAX2 style, or more generically either as hashes or as hashrefs (it returns a hashref). You will probably want to use this method in your own implementations of parse() and of new().

  • get_feature, set_feature

    These simply get and set features, and throw the appropriate exceptions defined in the specification if need be.

    If your subclass defines features not defined in this one, then you should override these methods in such a way that they check for your features first, and then call the base class's methods for features not defined by your class. An example would be:

      sub get_feature {
      my $self = shift;
      my $feat = shift;
      if (exists $MY_FEATURES{$feat}) {
          # handle the feature in various ways
      }
      else {
          return $self->SUPER::get_feature($feat);
      }
  }

    Currently this part is unimplemented.

  • set_handler

    This method takes a handler type (Handler, ContentHandler, etc.) and a handler object as arguments, and changes the current handler for that handler type, while taking care of resetting the internal state that needs to be reset. This allows one to change a handler during parse without running into problems (changing it on the parser object directly will most likely cause trouble).

  • set_document_handler, set_content_handler, set_dtd_handler, set_lexical_handler, set_decl_handler, set_error_handler, set_entity_resolver

    These are just simple wrappers around the former method, and take a handler object as their argument. Internally they simply call set_handler with the correct arguments.

  • get_handler

    The inverse of set_handler, this method takes a an optional string containing a handler type (DTDHandler, ContentHandler, etc. 'Handler' is used if no type is passed). It returns a reference to the object that implements that that class, or undef if that handler type is not set for the current driver/filter.

  • get_document_handler, get_content_handler, get_dtd_handler, get_lexical_handler, get_decl_handler, get_error_handler, get_entity_resolver

    These are just simple wrappers around the get_handler() method, and take no arguments. Internally they simply call get_handler with the correct handler type name.

It would be rather useless to describe all the methods that this module implements here. They are all the methods supported in SAX1 and SAX2. In case your memory is a little short, here is a list. The apparent duplicates are there so that both versions of SAX can be supported.

  • start_document
  • end_document
  • start_element
  • start_document
  • end_document
  • start_element
  • end_element
  • characters
  • processing_instruction
  • ignorable_whitespace
  • set_document_locator
  • start_prefix_mapping
  • end_prefix_mapping
  • skipped_entity
  • start_cdata
  • end_cdata
  • comment
  • entity_reference
  • notation_decl
  • unparsed_entity_decl
  • element_decl
  • attlist_decl
  • doctype_decl
  • xml_decl
  • entity_decl
  • attribute_decl
  • internal_entity_decl
  • external_entity_decl
  • resolve_entity
  • start_dtd
  • end_dtd
  • start_entity
  • end_entity
  • warning
  • error
  • fatal_error

TODO

  - more tests
  - conform to the "SAX Filters" and "Java and DOM compatibility"
    sections of the SAX2 document.

AUTHOR

Kip Hampton (khampton@totalcinema.com) did most of the work, after porting it from XML::Filter::Base.

Robin Berjon (robin@knowscape.com) pitched in with patches to make it usable as a base for drivers as well as filters, along with other patches.

Matt Sergeant (matt@sergeant.org) wrote the original XML::Filter::Base, and patched a few things here and there, and imported it into the XML::SAX distribution.

SEE ALSO

the XML::SAX manpage


XML::SAX::DocumentLocator - Helper class for document locators

  • API

NAME

XML::SAX::DocumentLocator - Helper class for document locators

SYNOPSIS

  my $locator = XML::SAX::DocumentLocator->new(
      sub { $object->get_public_id },
      sub { $object->get_system_id },
      sub { $reader->current_line },
      sub { $reader->current_column },
      sub { $reader->get_encoding },
      sub { $reader->get_xml_version },
  );

DESCRIPTION

This module gives you a tied hash reference that calls the specified closures when asked for PublicId, SystemId, LineNumber and ColumnNumber.

It is useful for writing SAX Parsers so that you don't have to constantly update the line numbers in a hash reference on the object you pass to set_document_locator(). See the source code for XML::SAX::PurePerl for a usage example.

API

There is only 1 method: new. Simply pass it a list of closures that when called will return the PublicId, the SystemId, the LineNumber, the ColumnNumber, the Encoding and the XMLVersion respectively.

The closures are passed a single parameter, the key being requested. But you're free to ignore that.


XML::SAX::Exception - Exception classes for XML::SAX

  • CREATING NEW EXCEPTION CLASSES
  • THROWING EXCEPTIONS

NAME

XML::SAX::Exception - Exception classes for XML::SAX

SYNOPSIS

  throw XML::SAX::Exception::NotSupported(
          Message => "The foo feature is not supported",
          );

DESCRIPTION

This module is the base class for all SAX Exceptions, those defined in the spec as well as those that one may create for one's own SAX errors.

There are three subclasses included, corresponding to those of the SAX spec:

  XML::SAX::Exception::NotSupported
  XML::SAX::Exception::NotRecognized
  XML::SAX::Exception::Parse

Use them wherever you want, and as much as possible when you encounter such errors. SAX is meant to use exceptions as much as possible to flag problems.

CREATING NEW EXCEPTION CLASSES

All you need to do to create a new exception class is:

  @XML::SAX::Exception::MyException::ISA = ('XML::SAX::Exception')

The given package doesn't need to exist, it'll behave correctly this way. If your exception refines an existing exception class, then you may also inherit from that instead of from the base class.

THROWING EXCEPTIONS

This is as simple as exemplified in the SYNOPSIS. In fact, there's nothing more to know. All you have to do is:

  throw XML::SAX::Exception::MyException( Message => 'Something went wrong' );

and voila, you've thrown an exception which can be caught in an eval block.


XML::SAX::Intro - An Introduction to SAX Parsing with Perl

  • Introduction
  • Replacing XML::Parser
  • Introducing SAX
  • Callback Parameters
    • start_element
    • end_element
    • characters
    • comment
    • processing_instruction
  • Tip of the iceberg
  • AUTHOR

NAME

XML::SAX::Intro - An Introduction to SAX Parsing with Perl

Introduction

XML::SAX is a new way to work with XML Parsers in Perl. In this article we'll discuss why you should be using SAX, why you should be using XML::SAX, and we'll see some of the finer implementation details. The text below assumes some familiarity with callback, or push based parsing, but if you are unfamiliar with these techniques then a good place to start is Kip Hampton's excellent series of articles on XML.com.

Replacing XML::Parser

The de-facto way of parsing XML under perl is to use Larry Wall and Clark Cooper's XML::Parser. This module is a Perl and XS wrapper around the expat XML parser library by James Clark. It has been a hugely successful project, but suffers from a couple of rather major flaws. Firstly it is a proprietary API, designed before the SAX API was conceived, which means that it is not easily replaceable by other streaming parsers. Secondly it's callbacks are subrefs. This doesn't sound like much of an issue, but unfortunately leads to code like:

  sub handle_start {
    my ($e, $el, %attrs) = @_;
    if ($el eq 'foo') {
      $e->{inside_foo}++; # BAD! $e is an XML::Parser::Expat object.
    }
  }

As you can see, we're using the $e object to hold our state information, which is a bad idea because we don't own that object - we didn't create it. It's an internal object of XML::Parser, that happens to be a hashref. We could all too easily overwrite XML::Parser internal state variables by using this, or Clark could change it to an array ref (not that he would, because it would break so much code, but he could).

The only way currently with XML::Parser to safely maintain state is to use a closure:

  my $state = MyState->new();
  $parser->setHandlers(Start => sub { handle_start($state, @_) });

This closure traps the $state variable, which now gets passed as the first parameter to your callback. Unfortunately very few people use this technique, as it is not documented in the XML::Parser POD files.

Another reason you might not want to use XML::Parser is because you need some feature that it doesn't provide (such as validation), or you might need to use a library that doesn't use expat, due to it not being installed on your system, or due to having a restrictive ISP. Using SAX allows you to work around these restrictions.

Introducing SAX

SAX stands for the Simple API for XML. And simple it really is. Constructing a SAX parser and passing events to handlers is done as simply as:

  use XML::SAX;
  use MySAXHandler;

  my $parser = XML::SAX::ParserFactory->parser(
        Handler => MySAXHandler->new
  );

  $parser->parse_uri("foo.xml");

The important concept to grasp here is that SAX uses a factory class called XML::SAX::ParserFactory to create a new parser instance. The reason for this is so that you can support other underlying parser implementations for different feature sets. This is one thing that XML::Parser has always sorely lacked.

In the code above we see the parse_uri method used, but we could have equally well called parse_file, parse_string, or parse(). Please see XML::SAX::Base for what these methods take as parameters, but don't be fooled into believing parse_file takes a filename. No, it takes a file handle, a glob, or a subclass of IO::Handle. Beware.

SAX works very similarly to XML::Parser's default callback method, except it has one major difference: rather than setting individual callbacks, you create a new class in which to recieve the callbacks. Each callback is called as a method call on an instance of that handler class. An example will best demonstrate this:

  package MySAXHandler;
  use base qw(XML::SAX::Base);

  sub start_document {
    my ($self, $doc) = @_;
    # process document start event
  }

  sub start_element {
    my ($self, $el) = @_;
    # process element start event
  }

Now, when we instantiate this as above, and parse some XML with this as the handler, the methods start_document and start_element will be called as method calls, so this would be the equivalent of directly calling:

  $object->start_element($el);

Notice how this is different to XML::Parser's calling style, which calls:

  start_element($e, $name, %attribs);

It's the difference between function calling and method calling which allows you to subclass SAX handlers which contributes to SAX being a powerful solution.

As you can see, unlike XML::Parser, we have to define a new package in which to do our processing (there are hacks you can do to make this uneccessary, but I'll leave figuring those out to the experts). The biggest benefit of this is that you maintain your own state variable ($self in the above example) thus freeing you of the concerns listed above. It is also an improvement in maintainability - you can place the code in a separate file if you wish to, and your callback methods are always called the same thing, rather than having to choose a suitable name for them as you had to with XML::Parser. This is an obvious win.

SAX parsers are also very flexible in how you pass a handler to them. You can use a constructor parameter as we saw above, or we can pass the handler directly in the call to one of the parse methods:

  $parser->parse(Handler => $handler,
                 Source => { SystemId => "foo.xml" });
  # or...
  $parser->parse_file($fh, Handler => $handler);

This flexibility allows for one parser to be used in many different scenarios throughout your script (though one shouldn't feel pressure to use this method, as parser construction is generally not a time consuming process).

Callback Parameters

The only other thing you need to know to understand basic SAX is the structure of the parameters passed to each of the callbacks. In XML::Parser, all parameters are passed as multiple options to the callbacks, so for example the Start callback would be called as my_start($e, $name, %attributes), and the PI callback would be called as my_processing_instruction($e, $target, $data). In SAX, every callback is passed a hash reference, containing entries that define our "node". The key callbacks and the structures they receive are:

start_element

The start_element handler is called whenever a parser sees an opening tag. It is passed an element structure consisting of:

LocalName

The name of the element minus any namespace prefix it may have come with in the document.

NamespaceURI

The URI of the namespace associated with this element, or the empty string for none.

Attributes

A set of attributes as described below.

Name

The name of the element as it was seen in the document (i.e. including any prefix associated with it)

Prefix

The prefix used to qualify this element's namespace, or the empty string if none.

The Attributes are a hash reference, keyed by what we have called "James Clark" notation. This means that the attribute name has been expanded to include any associated namespace URI, and put together as {ns}name, where "ns" is the expanded namespace URI of the attribute if and only if the attribute had a prefix, and "name" is the LocalName of the attribute.

The value of each entry in the attributes hash is another hash structure consisting of:

LocalName

The name of the attribute minus any namespace prefix it may have come with in the document.

NamespaceURI

The URI of the namespace associated with this attribute. If the attribute had no prefix, then this consists of just the empty string.

Name

The attribute's name as it appeared in the document, including any namespace prefix.

Prefix

The prefix used to qualify this attribute's namepace, or the empty string if none.

Value

The value of the attribute.

So a full example, as output by Data::Dumper might be:

  ....

end_element

The end_element handler is called either when a parser sees a closing tag, or after start_element has been called for an empty element (do note however that a parser may if it is so inclined call characters with an empty string when it sees an empty element. There is no simple way in SAX to determine if the parser in fact saw an empty element, a start and end element with no content..

The end_element handler receives exactly the same structure as start_element, minus the Attributes entry. One must note though that it should not be a reference to the same data as start_element receives, so you may change the values in start_element but this will not affect the values later seen by end_element.

characters

The characters callback may be called in serveral circumstances. The most obvious one is when seeing ordinary character data in the markup. But it is also called for text in a CDATA section, and is also called in other situations. A SAX parser has to make no guarantees whatsoever about how many times it may call characters for a stretch of text in an XML document - it may call once, or it may call once for every character in the text. In order to work around this it is often important for the SAX developer to use a bundling technique, where text is gathered up and processed in one of the other callbacks. This is not always necessary, but it is a worthwhile technique to learn, which we will cover in XML::SAX::Advanced (when I get around to writing it).

The characters handler is called with a very simple structure - a hash reference consisting of just one entry:

Data

The text data that was received.

comment

The comment callback is called for comment text. Unlike with characters(), the comment callback *must* be invoked just once for an entire comment string. It receives a single simple structure - a hash reference containing just one entry:

Data

The text of the comment.

processing_instruction

The processing instruction handler is called for all processing instructions in the document. Note that these processing instructions may appear before the document root element, or after it, or anywhere where text and elements would normally appear within the document, according to the XML specification.

The handler is passed a structure containing just two entries:

Target

The target of the processing instrcution

Data

The text data in the processing instruction. Can be an empty string for a processing instruction that has no data element. For example <?wiggle?> is a perfectly valid processing instruction.

Tip of the iceberg

What we have discussed above is really the tip of the SAX iceberg. And so far it looks like there's not much of interest to SAX beyond what we have seen with XML::Parser. But it does go much further than that, I promise.

People who hate Object Oriented code for the sake of it may be thinking here that creating a new package just to parse something is a waste when they've been parsing things just fine up to now using procedural code. But there's reason to all this madness. And that reason is SAX Filters.

As you saw right at the very start, to let the parser know about our class, we pass it an instance of our class as the Handler to the parser. But now imagine what would happen if our class could also take a Handler option, and simply do some processing and pass on our data further down the line? That in a nutshell is how SAX filters work. It's Unix pipes for the 21st century!

There are two downsides to this. Number 1 - writing SAX filters can be tricky. If you look into the future and read the advanced tutorial I'm writing, you'll see that Handler can come in several shapes and sizes. So making sure your filter does the right thing can be tricky. Secondly, constructing complex filter chains can be difficult, and simple thinking tells us that we only get one pass at our document, when often we'll need more than that.

Luckily though, those downsides have been fixed by the release of two very cool modules. What's even better is that I didn't write either of them!

The first module is XML::SAX::Base. This is a VITAL SAX module that acts as a base class for all SAX parsers and filters. It provides an abstraction away from calling the handler methods, that makes sure your filter or parser does the right thing, and it does it FAST. So, if you ever need to write a SAX filter, which if you're processing XML -> XML, or XML -> HTML, then you probably do, then you need to be writing it as a subclass of XML::SAX::Base. Really - this is advice not to ignore lightly. I will not go into the details of writing a SAX filter here. Kip Hampton, the author of XML::SAX::Base has covered this nicely in his article on XML.com here <URI>.

To construct SAX pipelines, Barrie Slaymaker, a long time Perl hacker who's modules you will probably have heard of or used, wrote a very clever module called XML::SAX::Machines. This combines some really clever SAX filter-type modules, with a construction toolkit for filters that makes building pipelines easy. But before we see how it makes things easy, first lets see how tricky it looks to build complex SAX filter pipelines.

  use XML::SAX::ParserFactory;
  use XML::Filter::Filter1;
  use XML::Filter::Filter2;
  use XML::SAX::Writer;

  my $output_string;
  my $writer = XML::SAX::Writer->new(Output => \$output_string);
  my $filter2 = XML::SAX::Filter2->new(Handler => $writer);
  my $filter1 = XML::SAX::Filter1->new(Handler => $filter2);
  my $parser = XML::SAX::ParserFactory->parser(Handler => $filter1);

  $parser->parse_uri("foo.xml");

This is a lot easier with XML::SAX::Machines:

  use XML::SAX::Machines qw(Pipeline);

  my $output_string;
  my $parser = Pipeline(
        XML::SAX::Filter1 => XML::SAX::Filter2 => \$output_string
        );

  $parser->parse_uri("foo.xml");

One of the main benefits of XML::SAX::Machines is that the pipelines are constructed in natural order, rather than the reverse order we saw with manual pipeline construction. XML::SAX::Machines takes care of all the internals of pipe construction, providing you at the end with just a parser you can use (and you can re-use the same parser as many times as you need to).

Just a final tip. If you ever get stuck and are confused about what is being passed from one SAX filter or parser to the next, then Devel::TraceSAX will come to your rescue. This perl debugger plugin will allow you to dump the SAX stream of events as it goes by. Usage is really very simple just call your perl script that uses SAX as follows:

  $ perl -d:TraceSAX <scriptname>

And preferably pipe the output to a pager of some sort, such as more or less. The output is extremely verbose, but should help clear some issues up.

AUTHOR

Matt Sergeant, matt@sergeant.org

$Id: Intro.pod,v 1.3 2002/04/30 07:16:00 matt Exp $


XML::SAX::ParserFactory - Obtain a SAX parser

  • AUTHOR
  • LICENSE

NAME

XML::SAX::ParserFactory - Obtain a SAX parser

SYNOPSIS

  use XML::SAX::ParserFactory;
  use XML::SAX::XYZHandler;
  my $handler = XML::SAX::XYZHandler->new();
  my $p = XML::SAX::ParserFactory->parser(Handler => $handler);
  $p->parse_uri("foo.xml");
  # or $p->parse_string("<foo/>") or $p->parse_file($fh);

DESCRIPTION

XML::SAX::ParserFactory is a factory class for providing an application with a Perl SAX2 XML parser. It is akin to DBI - a front end for other parser classes. Each new SAX2 parser installed will register itself with XML::SAX, and then it will become available to all applications that use XML::SAX::ParserFactory to obtain a SAX parser.

Unlike DBI however, XML/SAX parsers almost all work alike (especially if they subclass XML::SAX::Base, as they should), so rather than specifying the parser you want in the call to parser(), XML::SAX has several ways to automatically choose which parser to use:

  • $XML::SAX::ParserPackage

    If this package variable is set, then this package is require()d and an instance of this package is returned by calling the new() class method in that package. If it cannot be loaded or there is an error, an exception will be thrown. The variable can also contain a version number:

      $XML::SAX::ParserPackage = "XML::SAX::Expat (0.72)";

    And the number will be treated as a minimum version number.

  • Required features

    It is possible to require features from the parsers. For example, you may wish for a parser that supports validation via a DTD. To do that, use the following code:

      use XML::SAX::ParserFactory;
  my $factory = XML::SAX::ParserFactory->new();
  $factory->require_feature('http://xml.org/sax/features/validation');
  my $parser = $factory->parser(...);

    Alternatively, specify the required features in the call to the ParserFactory constructor:

      my $factory = XML::SAX::ParserFactory->new(
          RequiredFeatures => {
               'http://xml.org/sax/features/validation' => 1,
               }
          );

    If the features you have asked for are unavailable (for example the user might not have a validating parser installed), then an exception will be thrown.

    The list of known parsers is searched in reverse order, so it will always return the last installed parser that supports all of your requested features (Note: this is subject to change if someone comes up with a better way of making this work).

  • SAX.ini

    ParserFactory will search @INC for a file called SAX.ini, which is in a simple format:

      # a comment looks like this,
  ; or like this, and are stripped anywhere in the file
  key = value # SAX.in contains key/value pairs.

    All whitespace is non-significant.

    This file can contain either a line:

      ParserPackage = MyParserModule (1.02)

    Where MyParserModule is the module to load and use for the parser, and the number in brackets is a minimum version to load.

    Or you can list required features:

      http://xml.org/sax/features/validation = 1

    And each feature with a true value will be required.

  • Fallback

    If none of the above works, the last parser installed on the user's system will be used. The XML::SAX package ships with a pure perl XML parser, XML::SAX::PurePerl, so that there will always be a fallback parser.

AUTHOR

Matt Sergeant, matt@sergeant.org

LICENSE

This is free software, you may use it and distribute it under the same terms as Perl itself.


XML::SAX::PurePerl - Pure Perl XML Parser with SAX2 interface

  • BUGS
  • AUTHOR
  • LICENSE

NAME

XML::SAX::PurePerl - Pure Perl XML Parser with SAX2 interface

SYNOPSIS

  use XML::Handler::Foo;
  use XML::SAX::PurePerl;
  my $handler = XML::Handler::Foo->new();
  my $parser = XML::SAX::PurePerl->new(Handler => $handler);
  $parser->parse_uri("myfile.xml");

DESCRIPTION

This module implements an XML parser in pure perl. It is written around the upcoming perl 5.8's unicode support and support for multiple document encodings (using the PerlIO layer), however it has been ported to work with ASCII/UTF8 documents under lower perl versions.

The SAX2 API is described in detail at http://sourceforge.net/projects/perl-xml/, in the CVS archive, under libxml-perl/docs. Hopefully those documents will be in a better location soon.

Please refer to the SAX2 documentation for how to use this module - it is merely a front end to SAX2, and implements nothing that is not in that spec (or at least tries not to - please email me if you find errors in this implementation).

BUGS

XML::SAX::PurePerl is slow. Very slow. I suggest you use something else in fact. However it is great as a fallback parser for XML::SAX, where the user might not be able to install an XS based parser or C library.

Currently lots, probably. At the moment the weakest area is parsing DOCTYPE declarations, though the code is in place to start doing this. Also parsing parameter entity references is causing me much confusion, since it's not exactly what I would call trivial, or well documented in the XML grammar. XML documents with internal subsets are likely to fail.

I am however trying to work towards full conformance using the Oasis test suite.

AUTHOR

Matt Sergeant, matt@sergeant.org. Copyright 2001.

Please report all bugs to the Perl-XML mailing list at perl-xml@listserv.activestate.com.

LICENSE

This is free software. You may use it or redistribute it under the same terms as Perl 5.7.2 itself.


XML::Parser::PurePerl::Reader - Abstract Reader factory class

  • NAME

NAME

XML::Parser::PurePerl::Reader - Abstract Reader factory class


XML::Simple - Easy API to maintain XML

  • QUICK START
  • DESCRIPTION
    • XMLin()
    • XMLout()
    • Caveats
  • OPTIONS
    • AttrIndent => 1 # out - handy
    • Cache => [ cache schemes ] # in - advanced
    • ContentKey => 'keyname' # in+out - seldom used
    • DataHandler => code_ref # in - SAX only
    • ForceArray => 1 # in - important
    • ForceArray => [ names ] # in - important
    • ForceContent => 1 # in - seldom used
    • GroupTags => { grouping tag => grouped tag } # in+out - handy
    • Handler => object_ref # out - SAX only
    • KeepRoot => 1 # in+out - handy
    • KeyAttr => [ list ] # in+out - important
    • KeyAttr => { list } # in+out - important
    • NoAttr => 1 # in+out - handy
    • NoEscape => 1 # out - seldom used
    • NoIndent => 1 # out - seldom used
    • NoSort => 1 # out - seldom used
    • NormaliseSpace => 0 | 1 | 2 # in - handy
    • NSExpand => 1 # in+out handy - SAX only
    • NumericEscape => 0 | 1 | 2 # out - handy
    • OutputFile => <file specifier> # out - handy
    • ParserOpts => [ XML::Parser Options ] # in - don't use this
    • RootName => 'string' # out - handy
    • SearchPath => [ list ] # in - handy
    • SuppressEmpty => 1 | '' | undef # in+out - handy
    • ValueAttr => [ names ] # in - handy
    • ValueAttr => { element => attribute, ... } # in+out - handy
    • Variables => { name => value } # in - handy
    • VarAttr => 'attr_name' # in - handy
    • XMLDecl => 1 or XMLDecl => 'string' # out - handy
  • OPTIONAL OO INTERFACE
  • STRICT MODE
  • SAX SUPPORT
  • ENVIRONMENT
  • ERROR HANDLING
  • EXAMPLES
  • WHERE TO FROM HERE?
  • SEE ALSO
  • COPYRIGHT

NAME

XML::Simple - Easy API to maintain XML (esp config files)

SYNOPSIS

    use XML::Simple;

    my $ref = XMLin([<xml file or string>] [, <options>]);

    my $xml = XMLout($hashref [, <options>]);

Or the object oriented way:

    require XML::Simple;

    my $xs = new XML::Simple(options);

    my $ref = $xs->XMLin([<xml file or string>] [, <options>]);

    my $xml = $xs->XMLout($hashref [, <options>]);

(or see SAX SUPPORT for 'the SAX way').

To catch common errors:

    use XML::Simple qw(:strict);

(see STRICT MODE for more details).

QUICK START

Say you have a script called foo and a file of configuration options called foo.xml containing this:

  <config logdir="/var/log/foo/" debugfile="/tmp/foo.debug">
    <server name="sahara" osname="solaris" osversion="2.6">
      <address>10.0.0.101</address>
      <address>10.0.1.101</address>
    </server>
    <server name="gobi" osname="irix" osversion="6.5">
      <address>10.0.0.102</address>
    </server>
    <server name="kalahari" osname="linux" osversion="2.0.34">
      <address>10.0.0.103</address>
      <address>10.0.1.103</address>
    </server>
  </config>

The following lines of code in foo:

  use XML::Simple;

  my $config = XMLin();

will 'slurp' the configuration options into the hashref $config (because no arguments are passed to XMLin() the name and location of the XML file will be inferred from name and location of the script). You can dump out the contents of the hashref using Data::Dumper:

  use Data::Dumper;

  print Dumper($config);

which will produce something like this (formatting has been adjusted for brevity):

  {
      'logdir'        => '/var/log/foo/',
      'debugfile'     => '/tmp/foo.debug',
      'server'        => {
          'sahara'        => {
              'osversion'     => '2.6',
              'osname'        => 'solaris',
              'address'       => [ '10.0.0.101', '10.0.1.101' ]
          },
          'gobi'          => {
              'osversion'     => '6.5',
              'osname'        => 'irix',
              'address'       => '10.0.0.102'
          },
          'kalahari'      => {
              'osversion'     => '2.0.34',
              'osname'        => 'linux',
              'address'       => [ '10.0.0.103', '10.0.1.103' ]
          }
      }
  }

Your script could then access the name of the log directory like this:

  print $config->{logdir};

similarly, the second address on the server 'kalahari' could be referenced as:

  print $config->{server}->{kalahari}->{address}->[1];

What could be simpler? (Rhetorical).

For simple requirements, that's really all there is to it. If you want to store your XML in a different directory or file, or pass it in as a string or even pass it in via some derivative of an IO::Handle, you'll need to check out OPTIONS. If you want to turn off or tweak the array folding feature (that neat little transformation that produced $config->{server}) you'll find options for that as well.

If you want to generate XML (for example to write a modified version of $config back out as XML), check out XMLout().

If your needs are not so simple, this may not be the module for you. In that case, you might want to read WHERE TO FROM HERE?.

DESCRIPTION

The XML::Simple module provides a simple API layer on top of an underlying XML parsing module (either XML::Parser or one of the SAX2 parser modules). Two functions are exported: XMLin() and XMLout(). Note: you can explicity request the lower case versions of the function names: xml_in() and xml_out().

The simplest approach is to call these two functions directly, but an optional object oriented interface (see OPTIONAL OO INTERFACE below) allows them to be called as methods of an XML::Simple object. The object interface can also be used at either end of a SAX pipeline.

XMLin()

Parses XML formatted data and returns a reference to a data structure which contains the same information in a more readily accessible form. (Skip down to EXAMPLES below, for more sample code).

XMLin() accepts an optional XML specifier followed by zero or more 'name => value' option pairs. The XML specifier can be one of the following:

A filename

If the filename contains no directory components XMLin() will look for the file in each directory in the SearchPath (see OPTIONS below) or in the current directory if the SearchPath option is not defined. eg:

  $ref = XMLin('/etc/params.xml');

Note, the filename '-' can be used to parse from STDIN.

undef

If there is no XML specifier, XMLin() will check the script directory and each of the SearchPath directories for a file with the same name as the script but with the extension '.xml'. Note: if you wish to specify options, you must specify the value 'undef'. eg:

  $ref = XMLin(undef, ForceArray => 1);
A string of XML

A string containing XML (recognised by the presence of '<' and '>' characters) will be parsed directly. eg:

  $ref = XMLin('<opt username="bob" password="flurp" />');
An IO::Handle object

An IO::Handle object will be read to EOF and its contents parsed. eg:

  $fh = new IO::File('/etc/params.xml');
  $ref = XMLin($fh);

XMLout()

Takes a data structure (generally a hashref) and returns an XML encoding of that structure. If the resulting XML is parsed using XMLin(), it should return a data structure equivalent to the original (see caveats below).

The XMLout() function can also be used to output the XML as SAX events see the Handler option and SAX SUPPORT for more details).

When translating hashes to XML, hash keys which have a leading '-' will be silently skipped. This is the approved method for marking elements of a data structure which should be ignored by XMLout. (Note: If these items were not skipped the key names would be emitted as element or attribute names with a leading '-' which would not be valid XML).

Caveats

Some care is required in creating data structures which will be passed to XMLout(). Hash keys from the data structure will be encoded as either XML element names or attribute names. Therefore, you should use hash key names which conform to the relatively strict XML naming rules:

Names in XML must begin with a letter. The remaining characters may be letters, digits, hyphens (-), underscores (_) or full stops (.). It is also allowable to include one colon (:) in an element name but this should only be used when working with namespaces (XML::Simple can only usefully work with namespaces when teamed with a SAX Parser).

You can use other punctuation characters in hash values (just not in hash keys) however XML::Simple does not support dumping binary data.

If you break these rules, the current implementation of XMLout() will simply emit non-compliant XML which will be rejected if you try to read it back in. (A later version of XML::Simple might take a more proactive approach).

Note also that although you can nest hashes and arrays to arbitrary levels, circular data structures are not supported and will cause XMLout() to die.

If you wish to 'round-trip' arbitrary data structures from Perl to XML and back to Perl, then you should probably disable array folding (using the KeyAttr option) both with XMLout() and with XMLin(). If you still don't get the expected results, you may prefer to use the XML::Dumper manpage which is designed for exactly that purpose.

Refer to WHERE TO FROM HERE? if XMLout() is too simple for your needs.

OPTIONS

XML::Simple supports a number of options (in fact as each release of XML::Simple adds more options, the module's claim to the name 'Simple' becomes increasingly tenuous). If you find yourself repeatedly having to specify the same options, you might like to investigate OPTIONAL OO INTERFACE below.

If you can't be bothered reading the documentation, refer to STRICT MODE to automatically catch common mistakes.

Because there are so many options, it's hard for new users to know which ones are important, so here are the two you really need to know about:

  • check out ForceArray because you'll almost certainly want to turn it on

  • make sure you know what the KeyAttr option does and what its default value is because it may surprise you otherwise (note in particular that 'KeyAttr' affects both XMLin and XMLout)

The option name headings below have a trailing 'comment' - a hash followed by two pieces of metadata:

  • Options are marked with 'in' if they are recognised by XMLin() and 'out' if they are recognised by XMLout().

  • Each option is also flagged to indicate whether it is:

     'important'   - don't use the module until you understand this one
 'handy'       - you can skip this on the first time through
 'advanced'    - you can skip this on the second time through
 'SAX only'    - don't worry about this unless you're using SAX (or
                 alternatively if you need this, you also need SAX)
 'seldom used' - you'll probably never use this unless you were the
                 person that requested the feature

The options are listed alphabetically:

Note: option names are no longer case sensitive so you can use the mixed case versions shown here; all lower case as required by versions 2.03 and earlier; or you can add underscores between the words (eg: key_attr).

AttrIndent => 1 # out - handy

When you are using XMLout(), enable this option to have attributes printed one-per-line with sensible indentation rather than all on one line.

Cache => [ cache schemes ] # in - advanced

Because loading the XML::Parser module and parsing an XML file can consume a significant number of CPU cycles, it is often desirable to cache the output of XMLin() for later reuse.

When parsing from a named file, XML::Simple supports a number of caching schemes. The 'Cache' option may be used to specify one or more schemes (using an anonymous array). Each scheme will be tried in turn in the hope of finding a cached pre-parsed representation of the XML file. If no cached copy is found, the file will be parsed and the first cache scheme in the list will be used to save a copy of the results. The following cache schemes have been implemented:

storable

Utilises Storable.pm to read/write a cache file with the same name as the XML file but with the extension .stor

memshare

When a file is first parsed, a copy of the resulting data structure is retained in memory in the XML::Simple module's namespace. Subsequent calls to parse the same file will return a reference to this structure. This cached version will persist only for the life of the Perl interpreter (which in the case of mod_perl for example, may be some significant time).

Because each caller receives a reference to the same data structure, a change made by one caller will be visible to all. For this reason, the reference returned should be treated as read-only.

memcopy

This scheme works identically to 'memshare' (above) except that each caller receives a reference to a new data structure which is a copy of the cached version. Copying the data structure will add a little processing overhead, therefore this scheme should only be used where the caller intends to modify the data structure (or wishes to protect itself from others who might). This scheme uses Storable.pm to perform the copy.

Warning! The memory-based caching schemes compare the timestamp on the file to the time when it was last parsed. If the file is stored on an NFS filesystem (or other network share) and the clock on the file server is not exactly synchronised with the clock where your script is run, updates to the source XML file may appear to be ignored.

ContentKey => 'keyname' # in+out - seldom used

When text content is parsed to a hash value, this option let's you specify a name for the hash key to override the default 'content'. So for example:

  XMLin('<opt one="1">Text</opt>', ContentKey => 'text')

will parse to:

  { 'one' => 1, 'text' => 'Text' }

instead of:

  { 'one' => 1, 'content' => 'Text' }

XMLout() will also honour the value of this option when converting a hashref to XML.

You can also prefix your selected key name with a '-' character to have XMLin() try a little harder to eliminate unnecessary 'content' keys after array folding. For example:

  XMLin(
    '<opt><item name="one">First</item><item name="two">Second</item></opt>',
    KeyAttr => {item => 'name'},
    ForceArray => [ 'item' ],
    ContentKey => '-content'
  )

will parse to:

  {
    'item' => {
      'one' =>  'First'
      'two' =>  'Second'
    }
  }

rather than this (without the '-'):

  {
    'item' => {
      'one' => { 'content' => 'First' }
      'two' => { 'content' => 'Second' }
    }
  }

DataHandler => code_ref # in - SAX only

When you use an XML::Simple object as a SAX handler, it will return a 'simple tree' data structure in the same format as XMLin() would return. If this option is set (to a subroutine reference), then when the tree is built the subroutine will be called and passed two arguments: a reference to the XML::Simple object and a reference to the data tree. The return value from the subroutine will be returned to the SAX driver. (See SAX SUPPORT for more details).

ForceArray => 1 # in - important

This option should be set to '1' to force nested elements to be represented as arrays even when there is only one. Eg, with ForceArray enabled, this XML:

    <opt>
      <name>value</name>
    </opt>

would parse to this:

    {
      'name' => [
                  'value'
                ]
    }

instead of this (the default):

    {
      'name' => 'value'
    }

This option is especially useful if the data structure is likely to be written back out as XML and the default behaviour of rolling single nested elements up into attributes is not desirable.

If you are using the array folding feature, you should almost certainly enable this option. If you do not, single nested elements will not be parsed to arrays and therefore will not be candidates for folding to a hash. (Given that the default value of 'KeyAttr' enables array folding, the default value of this option should probably also have been enabled too - sorry).

ForceArray => [ names ] # in - important

This alternative (and preferred) form of the 'ForceArray' option allows you to specify a list of element names which should always be forced into an array representation, rather than the 'all or nothing' approach above.

It is also possible (since version 2.05) to include compiled regular expressions in the list - any element names which match the pattern will be forced to arrays. If the list contains only a single regex, then it is not necessary to enclose it in an arrayref. Eg:

  ForceArray => qr/_list$/

ForceContent => 1 # in - seldom used

When XMLin() parses elements which have text content as well as attributes, the text content must be represented as a hash value rather than a simple scalar. This option allows you to force text content to always parse to a hash value even when there are no attributes. So for example:

  XMLin('<opt><x>text1</x><y a="2">text2</y></opt>', ForceContent => 1)

will parse to:

  {
    'x' => {           'content' => 'text1' },
    'y' => { 'a' => 2, 'content' => 'text2' }
  }

instead of:

  {
    'x' => 'text1',
    'y' => { 'a' => 2, 'content' => 'text2' }
  }

GroupTags => { grouping tag => grouped tag } # in+out - handy

You can use this option to eliminate extra levels of indirection in your Perl data structure. For example this XML:

  <opt>
   <searchpath>
     <dir>/usr/bin</dir>
     <dir>/usr/local/bin</dir>
     <dir>/usr/X11/bin</dir>
   </searchpath>
 </opt>

Would normally be read into a structure like this:

  {
    searchpath => {
                    dir => [ '/usr/bin', '/usr/local/bin', '/usr/X11/bin' ]
                  }
  }

But when read in with the appropriate value for 'GroupTags':

  my $opt = XMLin($xml, GroupTags => { searchpath => 'dir' });

It will return this simpler structure:

  {
    searchpath => [ '/usr/bin', '/usr/local/bin', '/usr/X11/bin' ]
  }

The grouping element (<searchpath> in the example) must not contain any attributes or elements other than the grouped element.

You can specify multiple 'grouping element' to 'grouped element' mappings in the same hashref. If this option is combined with KeyAttr, the array folding will occur first and then the grouped element names will be eliminated.

XMLout will also use the grouptag mappings to re-introduce the tags around the grouped elements. Beware though that this will occur in all places that the 'grouping tag' name occurs - you probably don't want to use the same name for elements as well as attributes.

Handler => object_ref # out - SAX only

Use the 'Handler' option to have XMLout() generate SAX events rather than returning a string of XML. For more details see SAX SUPPORT below.

Note: the current implementation of this option generates a string of XML and uses a SAX parser to translate it into SAX events. The normal encoding rules apply here - your data must be UTF8 encoded unless you specify an alternative encoding via the 'XMLDecl' option; and by the time the data reaches the handler object, it will be in UTF8 form regardless of the encoding you supply. A future implementation of this option may generate the events directly.

KeepRoot => 1 # in+out - handy

In its attempt to return a data structure free of superfluous detail and unnecessary levels of indirection, XMLin() normally discards the root element name. Setting the 'KeepRoot' option to '1' will cause the root element name to be retained. So after executing this code:

  $config = XMLin('<config tempdir="/tmp" />', KeepRoot => 1)

You'll be able to reference the tempdir as $config->{config}->{tempdir} instead of the default $config->{tempdir}.

Similarly, setting the 'KeepRoot' option to '1' will tell XMLout() that the data structure already contains a root element name and it is not necessary to add another.

KeyAttr => [ list ] # in+out - important

This option controls the 'array folding' feature which translates nested elements from an array to a hash. It also controls the 'unfolding' of hashes to arrays.

For example, this XML:

    <opt>
      <user login="grep" fullname="Gary R Epstein" />
      <user login="stty" fullname="Simon T Tyson" />
    </opt>

would, by default, parse to this:

    {
      'user' => [
                  {
                    'login' => 'grep',
                    'fullname' => 'Gary R Epstein'
                  },
                  {
                    'login' => 'stty',
                    'fullname' => 'Simon T Tyson'
                  }
                ]
    }

If the option 'KeyAttr => "login"' were used to specify that the 'login' attribute is a key, the same XML would parse to:

    {
      'user' => {
                  'stty' => {
                              'fullname' => 'Simon T Tyson'
                            },
                  'grep' => {
                              'fullname' => 'Gary R Epstein'
                            }
                }
    }

The key attribute names should be supplied in an arrayref if there is more than one. XMLin() will attempt to match attribute names in the order supplied. XMLout() will use the first attribute name supplied when 'unfolding' a hash into an array.

Note 1: The default value for 'KeyAttr' is ['name', 'key', 'id']. If you do not want folding on input or unfolding on output you must setting this option to an empty list to disable the feature.

Note 2: If you wish to use this option, you should also enable the ForceArray option. Without 'ForceArray', a single nested element will be rolled up into a scalar rather than an array and therefore will not be folded (since only arrays get folded).

KeyAttr => { list } # in+out - important

This alternative (and preferred) method of specifiying the key attributes allows more fine grained control over which elements are folded and on which attributes. For example the option 'KeyAttr => { package => 'id' } will cause any package elements to be folded on the 'id' attribute. No other elements which have an 'id' attribute will be folded at all.

Note: XMLin() will generate a warning (or a fatal error in STRICT MODE) if this syntax is used and an element which does not have the specified key attribute is encountered (eg: a 'package' element without an 'id' attribute, to use the example above). Warnings will only be generated if -w is in force.

Two further variations are made possible by prefixing a '+' or a '-' character to the attribute name:

The option 'KeyAttr => { user => "+login" }' will cause this XML:

    <opt>
      <user login="grep" fullname="Gary R Epstein" />
      <user login="stty" fullname="Simon T Tyson" />
    </opt>

to parse to this data structure:

    {
      'user' => {
                  'stty' => {
                              'fullname' => 'Simon T Tyson',
                              'login'    => 'stty'
                            },
                  'grep' => {
                              'fullname' => 'Gary R Epstein',
                              'login'    => 'grep'
                            }
                }
    }

The '+' indicates that the value of the key attribute should be copied rather than moved to the folded hash key.

A '-' prefix would produce this result:

    {
      'user' => {
                  'stty' => {
                              'fullname' => 'Simon T Tyson',
                              '-login'    => 'stty'
                            },
                  'grep' => {
                              'fullname' => 'Gary R Epstein',
                              '-login'    => 'grep'
                            }
                }
    }

As described earlier, XMLout will ignore hash keys starting with a '-'.

NoAttr => 1 # in+out - handy

When used with XMLout(), the generated XML will contain no attributes. All hash key/values will be represented as nested elements instead.

When used with XMLin(), any attributes in the XML will be ignored.

NoEscape => 1 # out - seldom used

By default, XMLout() will translate the characters '<', '>', '&' and '"' to '&lt;', '&gt;', '&amp;' and '&quot' respectively. Use this option to suppress escaping (presumably because you've already escaped the data in some more sophisticated manner).

NoIndent => 1 # out - seldom used

Set this option to 1 to disable XMLout()'s default 'pretty printing' mode. With this option enabled, the XML output will all be on one line (unless there are newlines in the data) - this may be easier for downstream processing.

NoSort => 1 # out - seldom used

Newer versions of XML::Simple sort elements and attributes alphabetically (*), by default. Enable this option to suppress the sorting - possibly for backwards compatibility.

* Actually, sorting is alphabetical but 'key' attribute or element names (as in 'KeyAttr') sort first. Also, when a hash of hashes is 'unfolded', the elements are sorted alphabetically by the value of the key field.

NormaliseSpace => 0 | 1 | 2 # in - handy

This option controls how whitespace in text content is handled. Recognised values for the option are:

  • 0 = (default) whitespace is passed through unaltered (except of course for the normalisation of whitespace in attribute values which is mandated by the XML recommendation)

  • 1 = whitespace is normalised in any value used as a hash key (normalising means removing leading and trailing whitespace and collapsing sequences of whitespace characters to a single space)

  • 2 = whitespace is normalised in all text content

Note: you can spell this option with a 'z' if that is more natural for you.

NSExpand => 1 # in+out handy - SAX only

This option controls namespace expansion - the translation of element and attribute names of the form 'prefix:name' to '{uri}name'. For example the element name 'xsl:template' might be expanded to: '{http://www.w3.org/1999/XSL/Transform}template'.

By default, XMLin() will return element names and attribute names exactly as they appear in the XML. Setting this option to 1 will cause all element and attribute names to be expanded to include their namespace prefix.

Note: You must be using a SAX parser for this option to work (ie: it does not work with XML::Parser).

This option also controls whether XMLout() performs the reverse translation from '{uri}name' back to 'prefix:name'. The default is no translation. If your data contains expanded names, you should set this option to 1 otherwise XMLout will emit XML which is not well formed.

Note: You must have the XML::NamespaceSupport module installed if you want XMLout() to translate URIs back to prefixes.

NumericEscape => 0 | 1 | 2 # out - handy

Use this option to have 'high' (non-ASCII) characters in your Perl data structure converted to numeric entities (eg: &#8364;) in the XML output. Three levels are possible:

0 - default: no numeric escaping (OK if you're writing out UTF8)

1 - only characters above 0xFF are escaped (ie: characters in the 0x80-FF range are not escaped), possibly useful with ISO8859-1 output

2 - all characters above 0x7F are escaped (good for plain ASCII output)

OutputFile => <file specifier> # out - handy

The default behaviour of XMLout() is to return the XML as a string. If you wish to write the XML to a file, simply supply the filename using the 'OutputFile' option.

This option also accepts an IO handle object - especially useful in Perl 5.8.0 and later for output using an encoding other than UTF-8, eg:

  open my $fh, '>:encoding(iso-8859-1)', $path or die "open($path): $!";
  XMLout($ref, OutputFile => $fh);

ParserOpts => [ XML::Parser Options ] # in - don't use this

Note: This option is now officially deprecated. If you find it useful, email the author with an example of what you use it for. Do not use this option to set the ProtocolEncoding, that's just plain wrong - fix the XML.

This option allows you to pass parameters to the constructor of the underlying XML::Parser object (which of course assumes you're not using SAX).

RootName => 'string' # out - handy

By default, when XMLout() generates XML, the root element will be named 'opt'. This option allows you to specify an alternative name.

Specifying either undef or the empty string for the RootName option will produce XML with no root elements. In most cases the resulting XML fragment will not be 'well formed' and therefore could not be read back in by XMLin(). Nevertheless, the option has been found to be useful in certain circumstances.

SearchPath => [ list ] # in - handy

If you pass XMLin() a filename, but the filename include no directory component, you can use this option to specify which directories should be searched to locate the file. You might use this option to search first in the user's home directory, then in a global directory such as /etc.

If a filename is provided to XMLin() but SearchPath is not defined, the file is assumed to be in the current directory.

If the first parameter to XMLin() is undefined, the default SearchPath will contain only the directory in which the script itself is located. Otherwise the default SearchPath will be empty.

SuppressEmpty => 1 | '' | undef # in+out - handy

This option controls what XMLin() should do with empty elements (no attributes and no content). The default behaviour is to represent them as empty hashes. Setting this option to a true value (eg: 1) will cause empty elements to be skipped altogether. Setting the option to 'undef' or the empty string will cause empty elements to be represented as the undefined value or the empty string respectively. The latter two alternatives are a little easier to test for in your code than a hash with no keys.

The option also controls what XMLout() does with undefined values. Setting the option to undef causes undefined values to be output as empty elements (rather than empty attributes), it also suppresses the generation of warnings about undefined values. Setting the option to a true value (eg: 1) causes undefined values to be skipped altogether on output.

ValueAttr => [ names ] # in - handy

Use this option to deal elements which always have a single attribute and no content. Eg:

  <opt>
    <colour value="red" />
    <size   value="XXL" />
  </opt>

Setting ValueAttr => [ 'value' ] will cause the above XML to parse to:

  {
    colour => 'red',
    size   => 'XXL'
  }

instead of this (the default):

  {
    colour => { value => 'red' },
    size   => { value => 'XXL' }
  }

Note: This form of the ValueAttr option is not compatible with XMLout() - since the attribute name is discarded at parse time, the original XML cannot be reconstructed.

ValueAttr => { element => attribute, ... } # in+out - handy

This (preferred) form of the ValueAttr option requires you to specify both the element and the attribute names. This is not only safer, it also allows the original XML to be reconstructed by XMLout().

Note: You probably don't want to use this option and the NoAttr option at the same time.

Variables => { name => value } # in - handy

This option allows variables in the XML to be expanded when the file is read. (there is no facility for putting the variable names back if you regenerate XML using XMLout).

A 'variable' is any text of the form ${name} which occurs in an attribute value or in the text content of an element. If 'name' matches a key in the supplied hashref, ${name} will be replaced with the corresponding value from the hashref. If no matching key is found, the variable will not be replaced.

VarAttr => 'attr_name' # in - handy

In addition to the variables defined using Variables, this option allows variables to be defined in the XML. A variable definition consists of an element with an attribute called 'attr_name' (the value of the VarAttr option). The value of the attribute will be used as the variable name and the text content of the element will be used as the value. A variable defined in this way will override a variable defined using the Variables option. For example:

  XMLin( '<opt>
            <dir name="prefix">/usr/local/apache</dir>
            <dir name="exec_prefix">${prefix}</dir>
            <dir name="bindir">${exec_prefix}/bin</dir>
          </opt>',
         VarAttr => 'name', ContentKey => '-content'
        );

produces the following data structure:

  {
    dir => {
             prefix      => '/usr/local/apache',
             exec_prefix => '/usr/local/apache',
             bindir      => '/usr/local/apache/bin',
           }
  }

XMLDecl => 1 or XMLDecl => 'string' # out - handy

If you want the output from XMLout() to start with the optional XML declaration, simply set the option to '1'. The default XML declaration is:

        <?xml version='1.0' standalone='yes'?>

If you want some other string (for example to declare an encoding value), set the value of this option to the complete string you require.

OPTIONAL OO INTERFACE

The procedural interface is both simple and convenient however there are a couple of reasons why you might prefer to use the object oriented (OO) interface:

  • to define a set of default values which should be used on all subsequent calls to XMLin() or XMLout()

  • to override methods in XML::Simple to provide customised behaviour

The default values for the options described above are unlikely to suit everyone. The OO interface allows you to effectively override XML::Simple's defaults with your preferred values. It works like this:

First create an XML::Simple parser object with your preferred defaults:

  my $xs = new XML::Simple(ForceArray => 1, KeepRoot => 1);

then call XMLin() or XMLout() as a method of that object:

  my $ref = $xs->XMLin($xml);
  my $xml = $xs->XMLout($ref);

You can also specify options when you make the method calls and these values will be merged with the values specified when the object was created. Values specified in a method call take precedence.

Overriding methods is a more advanced topic but might be useful if for example you wished to provide an alternative routine for escaping character data (the escape_value method) or for building the initial parse tree (the build_tree method).

Note: when called as methods, the XMLin() and XMLout() routines may be called as xml_in() or xml_out(). The method names are aliased so the only difference is the aesthetics.

STRICT MODE

If you import the XML::Simple routines like this:

  use XML::Simple qw(:strict);

the following common mistakes will be detected and treated as fatal errors

  • Failing to explicitly set the KeyAttr option - if you can't be bothered reading about this option, turn it off with: KeyAttr => [ ]

  • Failing to explicitly set the ForceArray option - if you can't be bothered reading about this option, set it to the safest mode with: ForceArray => 1

  • Setting ForceArray to an array, but failing to list all the elements from the KeyAttr hash.

  • Data error - KeyAttr is set to say { part => 'partnum' } but the XML contains one or more <part> elements without a 'partnum' attribute (or nested element). Note: if strict mode is not set but -w is, this condition triggers a warning.

  • Data error - as above, but value of key attribute (eg: partnum) is not a scalar string (due to nested elements etc). This will also trigger a warning if strict mode is not enabled.

SAX SUPPORT

From version 1.08_01, XML::Simple includes support for SAX (the Simple API for XML) - specifically SAX2.

In a typical SAX application, an XML parser (or SAX 'driver') module generates SAX events (start of element, character data, end of element, etc) as it parses an XML document and a 'handler' module processes the events to extract the required data. This simple model allows for some interesting and powerful possibilities:

  • Applications written to the SAX API can extract data from huge XML documents without the memory overheads of a DOM or tree API.

  • The SAX API allows for plug and play interchange of parser modules without having to change your code to fit a new module's API. A number of SAX parsers are available with capabilities ranging from extreme portability to blazing performance.

  • A SAX 'filter' module can implement both a handler interface for receiving data and a generator interface for passing modified data on to a downstream handler. Filters can be chained together in 'pipelines'.

  • One filter module might split a data stream to direct data to two or more downstream handlers.

  • Generating SAX events is not the exclusive preserve of XML parsing modules. For example, a module might extract data from a relational database using DBI and pass it on to a SAX pipeline for filtering and formatting.

XML::Simple can operate at either end of a SAX pipeline. For example, you can take a data structure in the form of a hashref and pass it into a SAX pipeline using the 'Handler' option on XMLout():

  use XML::Simple;
  use Some::SAX::Filter;
  use XML::SAX::Writer;

  my $ref = {
               ....   # your data here
            };

  my $writer = XML::SAX::Writer->new();
  my $filter = Some::SAX::Filter->new(Handler => $writer);
  my $simple = XML::Simple->new(Handler => $filter);
  $simple->XMLout($ref);

You can also put XML::Simple at the opposite end of the pipeline to take advantage of the simple 'tree' data structure once the relevant data has been isolated through filtering:

  use XML::SAX;
  use Some::SAX::Filter;
  use XML::Simple;

  my $simple = XML::Simple->new(ForceArray => 1, KeyAttr => ['partnum']);
  my $filter = Some::SAX::Filter->new(Handler => $simple);
  my $parser = XML::SAX::ParserFactory->parser(Handler => $filter);

  my $ref = $parser->parse_uri('some_huge_file.xml');

  print $ref->{part}->{'555-1234'};

You can build a filter by using an XML::Simple object as a handler and setting its DataHandler option to point to a routine which takes the resulting tree, modifies it and sends it off as SAX events to a downstream handler:

  my $writer = XML::SAX::Writer->new();
  my $filter = XML::Simple->new(
                 DataHandler => sub {
                                  my $simple = shift;
                                  my $data = shift;

                                  # Modify $data here

                                  $simple->XMLout($data, Handler => $writer);
                                                                  }
                                                 );
                                    my $parser = XML::SAX::ParserFactory->parser(Handler => $filter);

  $parser->parse_uri($filename);

Note: In this last example, the 'Handler' option was specified in the call to XMLout() but it could also have been specified in the constructor.

ENVIRONMENT

If you don't care which parser module XML::Simple uses then skip this section entirely (it looks more complicated than it really is).

XML::Simple will default to using a SAX parser if one is available or XML::Parser if SAX is not available.

You can dictate which parser module is used by setting either the environment variable 'XML_SIMPLE_PREFERRED_PARSER' or the package variable $XML::Simple::PREFERRED_PARSER to contain the module name. The following rules are used:

  • The package variable takes precedence over the environment variable if both are defined. To force XML::Simple to ignore the environment settings and use its default rules, you can set the package variable to an empty string.

  • If the 'preferred parser' is set to the string 'XML::Parser', then the XML::Parser manpage will be used (or XMLin() will die if the XML::Parser manpage is not installed).

  • If the 'preferred parser' is set to some other value, then it is assumed to be the name of a SAX parser module and is passed to the XML::SAX::ParserFactory. manpage If the XML::SAX manpage is not installed, or the requested parser module is not installed, then XMLin() will die.

  • If the 'preferred parser' is not defined at all (the normal default state), an attempt will be made to load the XML::SAX manpage. If the XML::SAX manpage is installed, then a parser module will be selected according to the XML::SAX::ParserFactory manpage's normal rules (which typically means the last SAX parser installed).

  • if the 'preferred parser' is not defined and XML::SAX is not installed, then XML::Parser will be used. XMLin() will die if the XML::Parser manpage is not installed.

Note: The XML::SAX distribution includes an XML parser written entirely in Perl. It is very portable but it is not very fast. You should consider installing the XML::LibXML manpage or the XML::SAX::Expat manpage if they are available for your platform.

ERROR HANDLING

The XML standard is very clear on the issue of non-compliant documents. An error in parsing any single element (for example a missing end tag) must cause the whole document to be rejected. XML::Simple will die with an appropriate message if it encounters a parsing error.

If dying is not appropriate for your application, you should arrange to call XMLin() in an eval block and look for errors in $@. eg:

    my $config = eval { XMLin() };
    PopUpMessage($@) if($@);

Note, there is a common misconception that use of eval will significantly slow down a script. While that may be true when the code being eval'd is in a string, it is not true of code like the sample above.

EXAMPLES

When XMLin() reads the following very simple piece of XML:

    <opt username="testuser" password="frodo"></opt>

it returns the following data structure:

    {
      'username' => 'testuser',
      'password' => 'frodo'
    }

The identical result could have been produced with this alternative XML:

    <opt username="testuser" password="frodo" />

Or this (although see 'ForceArray' option for variations):

    <opt>
      <username>testuser</username>
      <password>frodo</password>
    </opt>

Repeated nested elements are represented as anonymous arrays:

    <opt>
      <person firstname="Joe" lastname="Smith">
        <email>joe@smith.com</email>
        <email>jsmith@yahoo.com</email>
      </person>
      <person firstname="Bob" lastname="Smith">
        <email>bob@smith.com</email>
      </person>
    </opt>
    {
      'person' => [
                    {
                      'email' => [
                                   'joe@smith.com',
                                   'jsmith@yahoo.com'
                                 ],
                      'firstname' => 'Joe',
                      'lastname' => 'Smith'
                    },
                    {
                      'email' => 'bob@smith.com',
                      'firstname' => 'Bob',
                      'lastname' => 'Smith'
                    }
                  ]
    }

Nested elements with a recognised key attribute are transformed (folded) from an array into a hash keyed on the value of that attribute (see the KeyAttr option):

    <opt>
      <person key="jsmith" firstname="Joe" lastname="Smith" />
      <person key="tsmith" firstname="Tom" lastname="Smith" />
      <person key="jbloggs" firstname="Joe" lastname="Bloggs" />
    </opt>
    {
      'person' => {
                    'jbloggs' => {
                                   'firstname' => 'Joe',
                                   'lastname' => 'Bloggs'
                                 },
                    'tsmith' => {
                                  'firstname' => 'Tom',
                                  'lastname' => 'Smith'
                                },
                    'jsmith' => {
                                  'firstname' => 'Joe',
                                  'lastname' => 'Smith'
                                }
                  }
    }

The <anon> tag can be used to form anonymous arrays:

    <opt>
      <head><anon>Col 1</anon><anon>Col 2</anon><anon>Col 3</anon></head>
      <data><anon>R1C1</anon><anon>R1C2</anon><anon>R1C3</anon></data>
      <data><anon>R2C1</anon><anon>R2C2</anon><anon>R2C3</anon></data>
      <data><anon>R3C1</anon><anon>R3C2</anon><anon>R3C3</anon></data>
    </opt>
    {
      'head' => [
                  [ 'Col 1', 'Col 2', 'Col 3' ]
                ],
      'data' => [
                  [ 'R1C1', 'R1C2', 'R1C3' ],
                  [ 'R2C1', 'R2C2', 'R2C3' ],
                  [ 'R3C1', 'R3C2', 'R3C3' ]
                ]
    }

Anonymous arrays can be nested to arbirtrary levels and as a special case, if the surrounding tags for an XML document contain only an anonymous array the arrayref will be returned directly rather than the usual hashref:

    <opt>
      <anon><anon>Col 1</anon><anon>Col 2</anon></anon>
      <anon><anon>R1C1</anon><anon>R1C2</anon></anon>
      <anon><anon>R2C1</anon><anon>R2C2</anon></anon>
    </opt>
    [
      [ 'Col 1', 'Col 2' ],
      [ 'R1C1', 'R1C2' ],
      [ 'R2C1', 'R2C2' ]
    ]

Elements which only contain text content will simply be represented as a scalar. Where an element has both attributes and text content, the element will be represented as a hashref with the text content in the 'content' key (see the ContentKey option):

  <opt>
    <one>first</one>
    <two attr="value">second</two>
  </opt>
  {
    'one' => 'first',
    'two' => { 'attr' => 'value', 'content' => 'second' }
  }

Mixed content (elements which contain both text content and nested elements) will be not be represented in a useful way - element order and significant whitespace will be lost. If you need to work with mixed content, then XML::Simple is not the right tool for your job - check out the next section.

WHERE TO FROM HERE?

XML::Simple is able to present a simple API because it makes some assumptions on your behalf. These include:

  • You're not interested in text content consisting only of whitespace

  • You don't mind that when things get slurped into a hash the order is lost

  • You don't want fine-grained control of the formatting of generated XML

  • You would never use a hash key that was not a legal XML element name

  • You don't need help converting between different encodings

In a serious XML project, you'll probably outgrow these assumptions fairly quickly. This section of the document used to offer some advice on chosing a more powerful option. That advice has now grown into the 'Perl-XML FAQ' document which you can find at: http://perl-xml.sourceforge.net/faq/

The advice in the FAQ boils down to a quick explanation of tree versus event based parsers and then recommends:

For event based parsing, use SAX (do not set out to write any new code for XML::Parser's handler API - it is obselete).

For tree-based parsing, you could choose between the 'Perlish' approach of the XML::Twig manpage and more standards based DOM implementations - preferably one with XPath support.

SEE ALSO

XML::Simple requires either the XML::Parser manpage or the XML::SAX manpage.

To generate documents with namespaces, the XML::NamespaceSupport manpage is required.

The optional caching functions require the Storable manpage.

Answers to Frequently Asked Questions about XML::Simple are bundled with this distribution as: the XML::Simple::FAQ manpage

COPYRIGHT

Copyright 1999-2004 Grant McLean <grantm@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Frequently Asked Questions about XML::Simple

  • Frequently Asked Questions about XML::Simple
  • Basics
    • What is XML::Simple designed to be used for?
    • Why store configuration data in XML anyway?
    • What isn't XML::Simple good for?
    • What is mixed content?
    • Why doesn't XML::Simple handle mixed content?
    • Which Perl modules do handle mixed content?
  • Installation
    • How do I install XML::Simple?
    • I'm trying to install XML::Simple and 'make test' fails
    • Why is XML::Simple so slow?
  • Usage
    • How do I use XML::Simple?
    • There are so many options, which ones do I really need to know about?
    • What is the forcearray option all about?
    • What is the keyattr option all about?
    • So what's the catch with 'keyattr'?
    • How do I know what my data structure should look like?
    • I'm getting 'Use of uninitialized value' warnings
    • I'm getting a 'Not an ARRAY reference' error
    • I'm getting a 'No such array field' error
    • I'm getting an 'Out of memory' error
    • My element order is getting jumbled up
    • XML::Simple turns nested elements into attributes
    • Why does XMLout() insert <name> elements (or attributes)?
    • Why are empty elements represented as empty hashes?
    • Why is ParserOpts deprecated?

Frequently Asked Questions about XML::Simple

Basics

What is XML::Simple designed to be used for?

XML::Simple is a Perl module that was originally developed as a tool for reading and writing configuration data in XML format. You can use it for many other purposes that involve storing and retrieving structured data in XML.

You might also find XML::Simple a good starting point for playing with XML from Perl. It doesn't have a steep learning curve and if you outgrow its capabilities there are plenty of other Perl/XML modules to 'step up' to.

Why store configuration data in XML anyway?

The many advantages of using XML format for configuration data include:

  • Using existing XML parsing tools requires less development time, is easier and more robust than developing your own config file parsing code

  • XML can represent relationships between pieces of data, such as nesting of sections to arbitrary levels (not easily done with .INI files for example)

  • XML is basically just text, so you can easily edit a config file (easier than editing a Win32 registry)

  • XML provides standard solutions for handling character sets and encoding beyond basic ASCII (important for internationalization)

  • If it becomes necessary to change your configuration file format, there are many tools available for performing transformations on XML files

  • XML is an open standard (the world does not need more proprietary binary file formats)

  • Taking the extra step of developing a DTD allows the format of configuration files to be validated before your program reads them (not directly supported by XML::Simple)

  • Combining a DTD with a good XML editor can give you a GUI config editor for minimal coding effort

What isn't XML::Simple good for?

The main limitation of XML::Simple is that it does not work with 'mixed content' (see the next question). If you consider your XML files contain marked up text rather than structured data, you should probably use another module.

If you are working with very large XML files, XML::Simple's approach of representing the whole file in memory as a 'tree' data structure may not be suitable.

What is mixed content?

Consider this example XML:

  <document>
    <para>This is <em>mixed</em> content.</para>
  </document>

This is said to be mixed content, because the <para> element contains both character data (text content) and nested elements.

Here's some more XML:

  <person>
    <first_name>Joe</first_name>
    <last_name>Bloggs</last_name>
    <dob>25-April-1969</dob>
  </person>

This second example is not generally considered to be mixed content. The <first_name>, <last_name> and <dob> elements contain only character data and the <person> element contains only nested elements. (Note: Strictly speaking, the whitespace between the nested elements is character data, but it is ignored by XML::Simple).

Why doesn't XML::Simple handle mixed content?

Because if it did, it would no longer be simple :-)

Seriously though, there are plenty of excellent modules that allow you to work with mixed content in a variety of ways. Handling mixed content correctly is not easy and by ignoring these issues, XML::Simple is able to present an API without a steep learning curve.

Which Perl modules do handle mixed content?

Every one of them except XML::Simple :-)

If you're looking for a recommendation, I'd suggest you look at the Perl-XML FAQ at:

  http://perl-xml.sourceforge.net/faq/

Installation

How do I install XML::Simple?

If you're running ActiveState Perl, you've probably already got XML::Simple (although you may want to upgrade to version 1.09 or better for SAX support).

If you do need to install XML::Simple, you'll need to install an XML parser module first. Install either XML::Parser (which you may have already) or XML::SAX. If you install both, XML::SAX will be used by default.

Once you have a parser installed ...

On Unix systems, try:

  perl -MCPAN -e 'install XML::Simple'

If that doesn't work, download the latest distribution from ftp://ftp.cpan.org/pub/CPAN/authors/id/G/GR/GRANTM , unpack it and run these commands:

  perl Makefile.PL
  make
  make test
  make install

On Win32, if you have a recent build of ActiveState Perl (618 or better) try this command:

  ppm install XML::Simple

If that doesn't work, you really only need the Simple.pm file, so extract it from the .tar.gz file (eg: using WinZIP) and save it in the \site\lib\XML directory under your Perl installation (typically C:\Perl).

I'm trying to install XML::Simple and 'make test' fails

Is the directory where you've unpacked XML::Simple mounted from a file server using NFS, SMB or some other network file sharing? If so, that may cause errors in the the following test scripts:

  3_Storable.t
  4_MemShare.t
  5_MemCopy.t

The test suite is designed to exercise the boundary conditions of all XML::Simple's functionality and these three scripts exercise the caching functions. If XML::Simple is asked to parse a file for which it has a cached copy of a previous parse, then it compares the timestamp on the XML file with the timestamp on the cached copy. If the cached copy is *newer* then it will be used. If the cached copy is older or the same age then the file is re-parsed. The test scripts will get confused by networked filesystems if the workstation and server system clocks are not synchronised (to the second).

If you get an error in one of these three test scripts but you don't plan to use the caching options (they're not enabled by default), then go right ahead and run 'make install'. If you do plan to use caching, then try unpacking the distribution on local disk and doing the build/test there.

It's probably not a good idea to use the caching options with networked filesystems in production. If the file server's clock is ahead of the local clock, XML::Simple will re-parse files when it could have used the cached copy. However if the local clock is ahead of the file server clock and a file is changed immediately after it is cached, the old cached copy will be used.

Is one of the three test scripts (above) failing but you're not running on a network filesystem? Are you running Win32? If so, you may be seeing a bug in Win32 where writes to a file do not affect its modfication timestamp.

If none of these scenarios match your situation, please confirm you're running the latest version of XML::Simple and then email the output of 'make test' to me at grantm@cpan.org

Why is XML::Simple so slow?

If you find that XML::Simple is very slow reading XML, the most likely reason is that you have XML::SAX installed but no additional SAX parser module. The XML::SAX distribution includes an XML parser written entirely in Perl. This is very portable but not very fast. For better performance install either XML::SAX::Expat or XML::LibXML.

Usage

How do I use XML::Simple?

If you had an XML document called /etc/appconfig/foo.xml you could 'slurp' it into a simple data structure (typically a hashref) with these lines of code:

  use XML::Simple;

  my $config = XMLin('/etc/appconfig/foo.xml');

The XMLin() function accepts options after the filename.

There are so many options, which ones do I really need to know about?

Although you can get by without using any options, you shouldn't even consider using XML::Simple in production until you know what these two options do:

  • forcearray

  • keyattr

The reason you really need to read about them is because the default values for these options will trip you up if you don't. Although everyone agrees that these defaults are not ideal, there is not wide agreement on what they should be changed to. The answer therefore is to read about them (see below) and select values which are right for you.

What is the forcearray option all about?

Consider this XML in a file called ./person.xml:

  <person>
    <first_name>Joe</first_name>
    <last_name>Bloggs</last_name>
    <hobbie>bungy jumping</hobbie>
    <hobbie>sky diving</hobbie>
    <hobbie>knitting</hobbie>
  </person>

You could read it in with this line:

  my $person = XMLin('./person.xml');

Which would give you a data structure like this:

  $person = {
    'first_name' => 'Joe',
    'last_name'  => 'Bloggs',
    'hobbie'     => [ 'bungy jumping', 'sky diving', 'knitting' ]
  };

The <first_name> and <last_name> elements are represented as simple scalar values which you could refer to like this:

  print "$person->{first_name} $person->{last_name}\n";

The <hobbie> elements are represented as an array - since there is more than one. You could refer to the first one like this:

  print $person->{hobbie}->[0], "\n";

Or the whole lot like this:

  print join(', ', @{$person->{hobbie}} ), "\n";

The catch is, that these last two lines of code will only work for people who have more than one hobbie. If there is only one <hobbie> element, it will be represented as a simple scalar (just like <first_name> and <last_name>). Which might lead you to write code like this:

  if(ref($person->{hobbie})) {
    print join(', ', @{$person->{hobbie}} ), "\n";
  }
  else {
    print $person->{hobbie}, "\n";
  }

Don't do that.

One alternative approach is to set the forcearray option to a true value:

  my $person = XMLin('./person.xml', forcearray => 1);

Which will give you a data structure like this:

  $person = {
    'first_name' => [ 'Joe' ],
    'last_name'  => [ 'Bloggs' ],
    'hobbie'     => [ 'bungy jumping', 'sky diving', 'knitting' ]
  };

Then you can use this line to refer to all the list of hobbies even if there was only one:

  print join(', ', @{$person->{hobbie}} ), "\n";

The downside of this approach is that the <first_name> and <last_name> elements will also always be represented as arrays even though there will never be more than one:

  print "$person->{first_name}->[0] $person->{last_name}->[0]\n";

This might be OK if you change the XML to use attributes for things that will always be singular and nested elements for things that may be plural:

  <person first_name="Jane" last_name="Bloggs">
    <hobbie>motorcycle maintenance</hobbie>
  </person>

On the other hand, if you prefer not to use attributes, then you could specify that any <hobbie> elements should always be represented as arrays and all other nested elements should be simple scalar values unless there is more than one:

  my $person = XMLin('./person.xml', forcearray => [ 'hobbie' ]);

The forcearray option accepts a list of element names which should always be forced to an array representation:

  forcearray => [ qw(hobbie qualification childs_name) ]

See the XML::Simple manual page for more information.

What is the keyattr option all about?

Consider this sample XML:

  <catalog>
    <part partnum="1842334" desc="High pressure flange" price="24.50" />
    <part partnum="9344675" desc="Threaded gasket"      price="9.25" />
    <part partnum="5634896" desc="Low voltage washer"   price="12.00" />
  </catalog>

You could slurp it in with this code:

  my $catalog = XMLin('./catalog.xml');

Which would return a data structure like this:

  $catalog = {
      'part' => [
          {
            'partnum' => '1842334',
            'desc'    => 'High pressure flange',
            'price'   => '24.50'
          },
          {
            'partnum' => '9344675',
            'desc'    => 'Threaded gasket',
            'price'   => '9.25'
          },
          {
            'partnum' => '5634896',
            'desc'    => 'Low voltage washer',
            'price'   => '12.00'
          }
      ]
  };

Then you could access the description of the first part in the catalog with this code:

  print $catalog->{part}->[0]->{desc}, "\n";

However, if you wanted to access the description of the part with the part number of "9344675" then you'd have to code a loop like this:

  foreach my $part (@{$catalog->{part}}) {
    if($part->{partnum} eq '9344675') {
      print $part->{desc}, "\n";
      last;
    }
  }

The knowledge that each <part> element has a unique partnum attribute allows you to eliminate this search. You can pass this knowledge on to XML::Simple like this:

  my $catalog = XMLin($xml, keyattr => ['partnum']);

Which will return a data structure like this:

  $catalog = {
    'part' => {
      '5634896' => { 'desc' => 'Low voltage washer',   'price' => '12.00' },
      '1842334' => { 'desc' => 'High pressure flange', 'price' => '24.50' },
      '9344675' => { 'desc' => 'Threaded gasket',      'price' => '9.25'  }
    }
  };

XML::Simple has been able to transform $catalog->{part} from an arrayref to a hashref (keyed on partnum). This transformation is called 'array folding'.

Through the use of array folding, you can now index directly to the description of the part you want:

  print $catalog->{part}->{9344675}->{desc}, "\n";

The 'keyattr' option also enables array folding when the unique key is in a nested element rather than an attribute. eg:

  <catalog>
    <part>
      <partnum>1842334</partnum>
      <desc>High pressure flange</desc>
      <price>24.50</price>
    </part>
    <part>
      <partnum>9344675</partnum>
      <desc>Threaded gasket</desc>
      <price>9.25</price>
    </part>
    <part>
      <partnum>5634896</partnum>
      <desc>Low voltage washer</desc>
      <price>12.00</price>
    </part>
  </catalog>

See the XML::Simple manual page for more information.

So what's the catch with 'keyattr'?

One thing to watch out for is that you might get array folding even if you don't supply the keyattr option. The default value for this option is:

  [ 'name', 'key', 'id']

Which means if your XML elements have a 'name', 'key' or 'id' attribute (or nested element) then they may get folded on those values. This means that you can take advantage of array folding simply through careful choice of attribute names. On the hand, if you really don't want array folding at all, you'll need to set 'key attr to an empty list:

  my $ref = XMLin($xml, keyattr => []);

A second 'gotcha' is that array folding only works on arrays. That might seem obvious, but if there's only one record in your XML and you didn't set the 'forcearray' option then it won't be represented as an array and consequently won't get folded into a hash. The moral is that if you're using array folding, you should always turn on the forcearray option.

You probably want to be as specific as you can be too. For instance, the safest way to parse the <catalog> example above would be:

  my $catalog = XMLin($xml, keyattr => { part => 'partnum'},
                            forcearray => ['part']);

By using the hashref for keyattr, you can specify that only <part> elements should be folded on the 'partnum' attribute (and that the <part> elements should not be folded on any other attribute).

By supplying a list of element names for forcearray, you're ensuring that folding will work even if there's only one <part>. You're also ensuring that if the 'partnum' unique key is supplied in a nested element then that element won't get forced to an array too.

How do I know what my data structure should look like?

The rules are fairly straightforward:

  • each element gets represented as a hash

  • unless it contains only text, in which case it'll be a simple scalar value

  • or unless there's more than one element with the same name, in which case they'll be represented as an array

  • unless you've got array folding enabled, in which case they'll be folded into a hash

  • empty elements (no text contents and no attributes) will either be represented as an empty hash, an empty string or undef - depending on the value of the 'suppressempty' option.

If you're in any doubt, use Data::Dumper, eg:

  use XML::Simple;
  use Data::Dumper;

  my $ref = XMLin($xml);

  print Dumper($ref);

I'm getting 'Use of uninitialized value' warnings

You're probably trying to index into a non-existant hash key - try Data::Dumper.

I'm getting a 'Not an ARRAY reference' error

Something that you expect to be an array is not. The two most likely causes are that you forgot to use 'forcearray' or that the array got folded into a hash - try Data::Dumper.

I'm getting a 'No such array field' error

Something that you expect to be a hash is actually an array. Perhaps array folding failed because one element was missing the key attribute - try Data::Dumper.

I'm getting an 'Out of memory' error

Something in the data structure is not as you expect and Perl may be trying unsuccessfully to autovivify things - try Data::Dumper.

If you're already using Data::Dumper, try calling Dumper() immediately after XMLin() - ie: before you attempt to access anything in the data structure.

My element order is getting jumbled up

If you read an XML file with XMLin() and then write it back out with XMLout(), the order of the elements will likely be different. (However, if you read the file back in with XMLin() you'll get the same Perl data structure).

The reordering happens because XML::Simple uses hashrefs to store your data and Perl hashes do not really have any order.

It is possible that a future version of XML::Simple will use Tie::IxHash to store the data in hashrefs which do retain the order. However this will not fix all cases of element order being lost.

If your application really is sensitive to element order, don't use XML::Simple (and don't put order-sensitive values in attributes).

XML::Simple turns nested elements into attributes

If you read an XML file with XMLin() and then write it back out with XMLout(), some data which was originally stored in nested elements may end up in attributes. (However, if you read the file back in with XMLin() you'll get the same Perl data structure).

There are a number of ways you might handle this:

  • use the 'forcearray' option with XMLin()

  • use the 'noattr' option with XMLout()

  • live with it

  • don't use XML::Simple

Why does XMLout() insert <name> elements (or attributes)?

Try setting keyattr => [].

When you call XMLin() to read XML, the 'keyattr' option controls whether arrays get 'folded' into hashes. Similarly, when you call XMLout(), the 'keyattr' option controls whether hashes get 'unfolded' into arrays. As described above, 'keyattr' is enabled by default.

Why are empty elements represented as empty hashes?

An element is always represented as a hash unless it contains only text, in which case it is represented as a scalar string.

If you would prefer empty elements to be represented as empty strings or the undefined value, set the 'suppressempty' option to '' or undef respectively.

Why is ParserOpts deprecated?

The ParserOpts option is a remnant of the time when XML::Simple only worked with the XML::Parser API. Its value is completely ignored if you're using a SAX parser, so writing code which relied on it would bar you from taking advantage of SAX.

Even if you are using XML::Parser, it is seldom necessary to pass options to the parser object. A number of people have written to say they use this option to set XML::Parser's ProtocolEncoding option. Don't do that, it's wrong, Wrong, WRONG! Fix the XML document so that it's well-formed and you won't have a problem.

Having said all of that, as long as XML::Simple continues to support the XML::Parser API, this option will not be removed. There are currently no plans to remove support for the XML::Parser API.


XMLRPC::Lite - client and server implementation of XML-RPC protocol

  • DEPENDENCIES
  • SEE ALSO
  • CREDITS
  • COPYRIGHT
  • AUTHOR

NAME

XMLRPC::Lite - client and server implementation of XML-RPC protocol

SYNOPSIS

Client
  use XMLRPC::Lite;
  print XMLRPC::Lite
      -> proxy('http://betty.userland.com/RPC2')
      -> call('examples.getStateStruct', {state1 => 12, state2 => 28})
      -> result;
CGI server
  use XMLRPC::Transport::HTTP;

  my $server = XMLRPC::Transport::HTTP::CGI
    -> dispatch_to('methodName')
    -> handle
  ;
Daemon server
  use XMLRPC::Transport::HTTP;

  my $daemon = XMLRPC::Transport::HTTP::Daemon
    -> new (LocalPort => 80)
    -> dispatch_to('methodName')
  ;
  print "Contact to XMLRPC server at ", $daemon->url, "\n";
  $daemon->handle;

DESCRIPTION

XMLRPC::Lite is a Perl modules which provides a simple nterface to the XML-RPC protocol both on client and server side. Based on SOAP::Lite module, it gives you access to all features and transports available in that module.

See t/26-xmlrpc.t for client examples and examples/XMLRPC/* for server implementations.

DEPENDENCIES

 SOAP::Lite

SEE ALSO

 SOAP::Lite

CREDITS

The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software, Inc. See <http://www.xmlrpc.com> for more information about the XML-RPC specification.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XMLRPC::Test - Test framework for XMLRPC::Lite

  • COPYRIGHT
  • AUTHOR

NAME

XMLRPC::Test - Test framework for XMLRPC::Lite

SYNOPSIS

  use XMLRPC::Test;

  XMLRPC::Test::Server::run_for('http://localhost/cgi-bin/XMLRPC.cgi');

DESCRIPTION

XMLRPC::Test provides simple framework for testing server implementations. Specify your address (endpoint) and run provided tests against your server. See t/1*.t for examples.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XMLRPC::Transport::HTTP - Server/Client side HTTP support for XMLRPC::Lite

    • PROXY SETTINGS
    • COOKIE-BASED AUTHENTICATION
    • COMPRESSION
  • DEPENDENCIES
  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

XMLRPC::Transport::HTTP - Server/Client side HTTP support for XMLRPC::Lite

SYNOPSIS

Client
  use XMLRPC::Lite
    proxy => 'http://localhost/',
  # proxy => 'http://localhost/cgi-bin/xmlrpc.cgi', # local CGI server
  # proxy => 'http://localhost/',                   # local daemon server
  # proxy => 'http://login:password@localhost/cgi-bin/xmlrpc.cgi', # local CGI server with authentication
  ;

  print getStateName(1);
CGI server
  use XMLRPC::Transport::HTTP;

  my $server = XMLRPC::Transport::HTTP::CGI
    -> dispatch_to('methodName')
    -> handle
  ;
Daemon server
  use XMLRPC::Transport::HTTP;

  my $daemon = XMLRPC::Transport::HTTP::Daemon
    -> new (LocalPort => 80)
    -> dispatch_to('methodName')
  ;
  print "Contact to XMLRPC server at ", $daemon->url, "\n";
  $daemon->handle;

DESCRIPTION

This class encapsulates all HTTP related logic for a XMLRPC server, independent of what web server it's attached to. If you want to use this class you should follow simple guideline mentioned above.

PROXY SETTINGS

You can use any proxy setting you use with LWP::UserAgent modules:

 XMLRPC::Lite->proxy('http://endpoint.server/',
                     proxy => ['http' => 'http://my.proxy.server']);

or

 $xmlrpc->transport->proxy('http' => 'http://my.proxy.server');

should specify proxy server for you. And if you use HTTP_proxy_user and HTTP_proxy_pass for proxy authorization SOAP::Lite should know how to handle it properly.

COOKIE-BASED AUTHENTICATION

  use HTTP::Cookies;

  my $cookies = HTTP::Cookies->new(ignore_discard => 1);
    # you may also add 'file' if you want to keep them between sessions

  my $xmlrpc = XMLRPC::Lite->proxy('http://localhost/');
  $xmlrpc->transport->cookie_jar($cookies);

Cookies will be taken from response and provided for request. You may always add another cookie (or extract what you need after response) with HTTP::Cookies interface.

You may also do it in one line:

  $xmlrpc->proxy('http://localhost/',
                 cookie_jar => HTTP::Cookies->new(ignore_discard => 1));

COMPRESSION

XMLRPC::Lite provides you option for enabling compression on wire (for HTTP transport only). Both server and client should support this capability, but this logic should be absolutely transparent for your application. Server will respond with encoded message only if client can accept it (client sends Accept-Encoding with 'deflate' or '*' values) and client has fallback logic, so if server doesn't understand specified encoding (Content-Encoding: deflate) and returns proper error code (415 NOT ACCEPTABLE) client will repeat the same request not encoded and will store this server in per-session cache, so all other requests will go there without encoding.

Having options on client and server side that let you specify threshold for compression you can safely enable this feature on both client and server side.

Compression will be enabled on client side IF: threshold is specified AND size of current message is bigger than threshold AND module Compress::Zlib is available. Client will send header 'Accept-Encoding' with value 'deflate' if threshold is specified AND module Compress::Zlib is available.

Server will accept compressed message if module Compress::Zlib is available, and will respond with compressed message ONLY IF: threshold is specified AND size of current message is bigger than threshold AND module Compress::Zlib is available AND header 'Accept-Encoding' is presented in request.

DEPENDENCIES

 Crypt::SSLeay             for HTTPS/SSL
 HTTP::Daemon              for XMLRPC::Transport::HTTP::Daemon
 Apache, Apache::Constants for XMLRPC::Transport::HTTP::Apache

SEE ALSO

 See ::CGI, ::Daemon and ::Apache for implementation details.
 See examples/XMLRPC/* for examples.

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XMLRPC::Transport::POP3 - Server side POP3 support for XMLRPC::Lite

  • COPYRIGHT
  • AUTHOR

NAME

XMLRPC::Transport::POP3 - Server side POP3 support for XMLRPC::Lite

SYNOPSIS

  use XMLRPC::Transport::POP3;

  my $server = XMLRPC::Transport::POP3::Server
    -> new('pop://pop.mail.server')
    # if you want to have all in one place
    # -> new('pop://user:password@pop.mail.server')
    # or, if you have server that supports MD5 protected passwords
    # -> new('pop://user:password;AUTH=+APOP@pop.mail.server')
    # specify path to My/Examples.pm here
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  # you don't need to use next line if you specified your password in new()
  $server->login('user' => 'password') or die "Can't authenticate to POP3 server\n";

  # handle will return number of processed mails
  # you can organize loop if you want
  do { $server->handle } while sleep 10;

  # you may also call $server->quit explicitly to purge deleted messages

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XMLRPC::Transport::TCP - Server/Client side TCP support for XMLRPC::Lite

  • COPYRIGHT
  • AUTHOR

NAME

XMLRPC::Transport::TCP - Server/Client side TCP support for XMLRPC::Lite

SYNOPSIS

  use XMLRPC::Transport::TCP;

  my $daemon = XMLRPC::Transport::TCP::Server
    -> new (LocalAddr => 'localhost', LocalPort => 82, Listen => 5, Reuse => 1)
    -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
  ;
  print "Contact to XMLRPC server at ", join(':', $daemon->sockhost, $daemon->sockport), "\n";
  $daemon->handle;

DESCRIPTION

COPYRIGHT

Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)


XS::APItest - Test the perl C API

  • ABSTRACT
  • DESCRIPTION
    • EXPORT
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT AND LICENSE

NAME

XS::APItest - Test the perl C API

SYNOPSIS

  use XS::APItest;
  print_double(4);

ABSTRACT

This module tests the perl C API. Currently tests that printf works correctly.

DESCRIPTION

This module can be used to check that the perl C API is behaving correctly. This module provides test functions and an associated test script that verifies the output.

This module is not meant to be installed.

EXPORT

Exports all the test functions:

print_double

Test that a double-precision floating point number is formatted correctly by printf.

  print_double( $val );

Output is sent to STDOUT.

print_long_double

Test that a long double is formatted correctly by printf. Takes no arguments - the test value is hard-wired into the function (as "7").

  print_long_double();

Output is sent to STDOUT.

have_long_double

Determine whether a long double is supported by Perl. This should be used to determine whether to test print_long_double.

  print_long_double() if have_long_double;
print_nv

Test that an NV is formatted correctly by printf.

  print_nv( $val );

Output is sent to STDOUT.

print_iv

Test that an IV is formatted correctly by printf.

  print_iv( $val );

Output is sent to STDOUT.

print_uv

Test that an UV is formatted correctly by printf.

  print_uv( $val );

Output is sent to STDOUT.

print_int

Test that an int is formatted correctly by printf.

  print_int( $val );

Output is sent to STDOUT.

print_long

Test that an long is formatted correctly by printf.

  print_long( $val );

Output is sent to STDOUT.

print_float

Test that a single-precision floating point number is formatted correctly by printf.

  print_float( $val );

Output is sent to STDOUT.

call_sv, call_pv, call_method

These exercise the C calls of the same names. Everything after the flags arg is passed as the the args to the called function. They return whatever the C function itself pushed onto the stack, plus the return value from the function; for example

    call_sv( sub { @_, 'c' }, G_ARRAY,  'a', 'b'); # returns 'a', 'b', 'c', 3
    call_sv( sub { @_ },      G_SCALAR, 'a', 'b'); # returns 'b', 1
eval_sv

Evaluates the passed SV. Result handling is done the same as for call_sv() etc.

eval_pv

Exercises the C function of the same name in scalar context. Returns the same SV that the C function returns.

require_pv

Exercises the C function of the same name. Returns nothing.

SEE ALSO

the XS::Typemap manpage, the perlapi manpage.

AUTHORS

Tim Jenness, <t.jenness@jach.hawaii.edu>, Christian Soeller, <csoelle@mph.auckland.ac.nz>, Hugo van der Sanden <hv@crypt.compulink.co.uk>

COPYRIGHT AND LICENSE

Copyright (C) 2002,2004 Tim Jenness, Christian Soeller, Hugo van der Sanden. All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


XS::Typemap - module to test the XS typemaps distributed with perl

  • NOTES
  • AUTHOR

NAME

XS::Typemap - module to test the XS typemaps distributed with perl

SYNOPSIS

  use XS::Typemap;

  $output = T_IV( $input );
  $output = T_PV( $input );
  @output = T_ARRAY( @input );

DESCRIPTION

This module is used to test that the XS typemaps distributed with perl are working as advertised. A function is available for each typemap definition (eventually). In general each function takes a variable, processes it through the OUTPUT typemap and then returns it using the INPUT typemap.

A test script can then compare the input and output to make sure they are the expected values. When only an input or output function is provided the function will be named after the typemap entry and have either '_IN' or '_OUT' appended.

All the functions are exported. There is no reason not to do this since the entire purpose is for testing Perl. Namespace pollution will be limited to the test script.

NOTES

This module is for testing only and should not normally be installed.

AUTHOR

Tim Jenness <t.jenness@jach.hawaii.edu>

Copyright (C) 2001 Tim Jenness All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


XSLoader - Dynamically load C libraries into Perl code

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
    • Migration from DynaLoader
    • Backward compatible boilerplate
  • Order of initialization: early load()
    • The most hairy case
  • DIAGNOSTICS
  • LIMITATIONS
  • BUGS
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

XSLoader - Dynamically load C libraries into Perl code

VERSION

Version 0.06

SYNOPSIS

    package YourPackage;
    use XSLoader;

    XSLoader::load 'YourPackage', $YourPackage::VERSION;

DESCRIPTION

This module defines a standard simplified interface to the dynamic linking mechanisms available on many platforms. Its primary purpose is to implement cheap automatic dynamic loading of Perl modules.

For a more complicated interface, see the DynaLoader manpage. Many (most) features of DynaLoader are not implemented in XSLoader, like for example the dl_load_flags, not honored by XSLoader.

Migration from DynaLoader

A typical module using DynaLoader starts like this:

    package YourPackage;
    require DynaLoader;

    our @ISA = qw( OnePackage OtherPackage DynaLoader );
    our $VERSION = '0.01';
    bootstrap YourPackage $VERSION;

Change this to

    package YourPackage;
    use XSLoader;

    our @ISA = qw( OnePackage OtherPackage );
    our $VERSION = '0.01';
    XSLoader::load 'YourPackage', $VERSION;

In other words: replace require DynaLoader by use XSLoader, remove DynaLoader from @ISA, change bootstrap by XSLoader::load. Do not forget to quote the name of your package on the XSLoader::load line, and add comma (,) before the arguments ($VERSION above).

Of course, if @ISA contained only DynaLoader, there is no need to have the @ISA assignment at all; moreover, if instead of our one uses the more backward-compatible

    use vars qw($VERSION @ISA);

one can remove this reference to @ISA together with the @ISA assignment.

If no $VERSION was specified on the bootstrap line, the last line becomes

    XSLoader::load 'YourPackage';

Backward compatible boilerplate

If you want to have your cake and eat it too, you need a more complicated boilerplate.

    package YourPackage;
    use vars qw($VERSION @ISA);

    @ISA = qw( OnePackage OtherPackage );
    $VERSION = '0.01';
    eval {
       require XSLoader;
       XSLoader::load('YourPackage', $VERSION);
       1;
    } or do {
       require DynaLoader;
       push @ISA, 'DynaLoader';
       bootstrap YourPackage $VERSION;
    };

The parentheses about XSLoader::load() arguments are needed since we replaced use XSLoader by require, so the compiler does not know that a function XSLoader::load() is present.

This boilerplate uses the low-overhead XSLoader if present; if used with an antic Perl which has no XSLoader, it falls back to using DynaLoader.

Order of initialization: early load()

Skip this section if the XSUB functions are supposed to be called from other modules only; read it only if you call your XSUBs from the code in your module, or have a BOOT: section in your XS file (see The BOOT: Keyword in the perlxs manpage). What is described here is equally applicable to the DynaLoader interface.

A sufficiently complicated module using XS would have both Perl code (defined in YourPackage.pm) and XS code (defined in YourPackage.xs). If this Perl code makes calls into this XS code, and/or this XS code makes calls to the Perl code, one should be careful with the order of initialization.

The call to XSLoader::load() (or bootstrap()) has three side effects:

  • if $VERSION was specified, a sanity check is done to ensure that the versions of the .pm and the (compiled) .xs parts are compatible;

  • the XSUBs are made accessible from Perl;

  • if a BOOT: section was present in the .xs file, the code there is called.

Consequently, if the code in the .pm file makes calls to these XSUBs, it is convenient to have XSUBs installed before the Perl code is defined; for example, this makes prototypes for XSUBs visible to this Perl code. Alternatively, if the BOOT: section makes calls to Perl functions (or uses Perl variables) defined in the .pm file, they must be defined prior to the call to XSLoader::load() (or bootstrap()).

The first situation being much more frequent, it makes sense to rewrite the boilerplate as

    package YourPackage;
    use XSLoader;
    use vars qw($VERSION @ISA);

    BEGIN {
       @ISA = qw( OnePackage OtherPackage );
       $VERSION = '0.01';

       # Put Perl code used in the BOOT: section here

       XSLoader::load 'YourPackage', $VERSION;
           }

    # Put Perl code making calls into XSUBs here

The most hairy case

If the interdependence of your BOOT: section and Perl code is more complicated than this (e.g., the BOOT: section makes calls to Perl functions which make calls to XSUBs with prototypes), get rid of the BOOT: section altogether. Replace it with a function onBOOT(), and call it like this:

    package YourPackage;
    use XSLoader;
    use vars qw($VERSION @ISA);

    BEGIN {
       @ISA = qw( OnePackage OtherPackage );
       $VERSION = '0.01';
       XSLoader::load 'YourPackage', $VERSION;
    }

    # Put Perl code used in onBOOT() function here; calls to XSUBs are
    # prototype-checked.

    onBOOT;

    # Put Perl initialization code assuming that XS is initialized here

DIAGNOSTICS

Can't find '%s' symbol in %s

(F) The bootstrap symbol could not be found in the extension module.

Can't load '%s' for module %s: %s

(F) The loading or initialisation of the extension module failed. The detailed error follows.

Undefined symbols present after loading %s: %s

(W) As the message says, some symbols stay undefined although the extension module was correctly loaded and initialised. The list of undefined symbols follows.

XSLoader::load('Your::Module', $Your::Module::VERSION)

(F) You tried to invoke load() without any argument. You must supply a module name, and optionally its version.

LIMITATIONS

To reduce the overhead as much as possible, only one possible location is checked to find the extension DLL (this location is where make install would put the DLL). If not found, the search for the DLL is transparently delegated to DynaLoader, which looks for the DLL along the @INC list.

In particular, this is applicable to the structure of @INC used for testing not-yet-installed extensions. This means that running uninstalled extensions may have much more overhead than running the same extensions after make install.

BUGS

Please report any bugs or feature requests via the perlbug(1) utility.

SEE ALSO

the DynaLoader manpage

AUTHORS

Ilya Zakharevich originally extracted XSLoader from DynaLoader.

CPAN version is currently maintained by Sébastien Aperghis-Tramoni <sebastien@aperghis.net>

Previous maintainer was Michael G Schwern <schwern@pobox.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


YAML - YAML Ain't Markup Language

  • WHY YAML IS COOL
  • YAML IMPLEMENTATIONS IN PERL
  • FUNCTIONAL USAGE
    • Exported Functions
    • Exportable Functions
  • GLOBAL OPTIONS
  • YAML TERMINOLOGY
  • ysh - The YAML Shell
  • BUGS & DEFICIENCIES
  • RESOURCES
  • SEE ALSO
  • AUTHOR
  • COPYRIGHT

NAME

YAML - YAML Ain't Markup Language (tm)

SYNOPSIS

    use YAML;

    # Load a YAML stream of 3 YAML documents into Perl data structures.
    my ($hashref, $arrayref, $string) = Load(<<'...');
    ---
    name: ingy
    age: old
    weight: heavy
    # I should comment that I also like pink, but don't tell anybody.
    favorite colors:
        - red
        - green
        - blue
    ---
    - Clark Evans
    - Oren Ben-Kiki
    - Ingy döt Net
    --- >
    You probably think YAML stands for "Yet Another Markup Language". It
    ain't! YAML is really a data serialization language. But if you want
    to think of it as a markup, that's OK with me. A lot of people try
    to use XML as a serialization format.

    "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!"
    ...

    # Dump the Perl data structures back into YAML.
    print Dump($string, $arrayref, $hashref);

    # YAML::Dump is used the same way you'd use Data::Dumper::Dumper
    use Data::Dumper;
    print Dumper($string, $arrayref, $hashref);

DESCRIPTION

The YAML.pm module implements a YAML Loader and Dumper based on the YAML 1.0 specification. http://www.yaml.org/spec/

YAML is a generic data serialization language that is optimized for human readability. It can be used to express the data structures of most modern programming languages. (Including Perl!!!)

For information on the YAML syntax, please refer to the YAML specification.

WHY YAML IS COOL

YAML is readable for people.

It makes clear sense out of complex data structures. You should find that YAML is an exceptional data dumping tool. Structure is shown through indentation, YAML supports recursive data, and hash keys are sorted by default. In addition, YAML supports several styles of scalar formatting for different types of data.

YAML is editable.

YAML was designed from the ground up to be an excellent syntax for configuration files. Almost all programs need configuration files, so why invent a new syntax for each one? And why subject users to the complexities of XML or native Perl code?

YAML is multilingual.

Yes, YAML supports Unicode. But I'm actually referring to programming languages. YAML was designed to meet the serialization needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was also designed to be interoperable between those languages. That means YAML serializations produced by Perl can be processed by Python.

YAML is taint safe.

Using modules like Data::Dumper for serialization is fine as long as you can be sure that nobody can tamper with your data files or transmissions. That's because you need to use Perl's eval() built-in to deserialize the data. Somebody could add a snippet of Perl to erase your files.

YAML's parser does not need to eval anything.

YAML is full featured.

YAML can accurately serialize all of the common Perl data structures and deserialize them again without losing data relationships. Although it is not 100% perfect (no serializer is or can be perfect), it fares as well as the popular current modules: Data::Dumper, Storable, XML::Dumper and Data::Denter.

YAML.pm also has the ability to handle code (subroutine) references and typeglobs. (Still experimental) These features are not found in Perl's other serialization modules.

YAML is extensible.

The YAML language has been designed to be flexible enough to solve it's own problems. The markup itself has 3 basic construct which resemble Perl's hash, array and scalar. By default, these map to their Perl equivalents. But each YAML node also supports a tagging mechanism (type system) which can cause that node to be interpreted in a completely different manner. That's how YAML can support object serialization and oddball structures like Perl's typeglob.

YAML IMPLEMENTATIONS IN PERL

This module, YAML.pm, is really just the interface module for YAML modules written in Perl. The basic interface for YAML consists of two functions: Dump and Load. The real work is done by the modules YAML::Dumper and YAML::Loader.

Different YAML module distributions can be created by subclassing YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.

Why would there be more than one implementation of YAML? Well, despite YAML's offering of being a simple data format, YAML is actually very deep and complex. Implementing the entirety of the YAML specification is a daunting task.

For this reason I am currently working on 3 different YAML implementations.

YAML

The main YAML distribution will keeping evolving to support the entire YAML specification in pure Perl. This may not be the fastest or most stable module though. Currently, YAML.pm has lots of known bugs. It is mostly a great tool for dumping Perl data structures to a readable form.

YAML::Lite

The point of YAML::Lite is to strip YAML down to the 90% that people use most and offer that in a small, fast, stable, pure Perl form. YAML::Lite will simply die when it is asked to do something it can't.

YAML::Syck

libsyck is the C based YAML processing library used by the Ruby programming language (and also Python, PHP and Pugs). YAML::Syck is the Perl binding to libsyck. It should be very fast, but may have problems of its own. It will also require C compilation.

NOTE: Audrey Tang has actually completed this module and it works great and is 10 times faster than YAML.pm.

In the future, there will likely be even more YAML modules. Remember, people other than Ingy are allowed to write YAML modules!

FUNCTIONAL USAGE

YAML is completely OO under the hood. Still it exports a few useful top level functions so that it is dead simple to use. These functions just do the OO stuff for you. If you want direct access to the OO API see the documentation for YAML::Dumper and YAML::Loader.

Exported Functions

The following functions are exported by YAML.pm by default. The reason they are exported is so that YAML works much like Data::Dumper. If you don't want functions to be imported, just use YAML with an empty import list:

    use YAML ();
Dump(list-of-Perl-data-structures)

Turn Perl data into YAML. This function works very much like Data::Dumper::Dumper(). It takes a list of Perl data strucures and dumps them into a serialized form. It returns a string containing the YAML stream. The structures can be references or plain scalars.

Load(string-containing-a-YAML-stream)

Turn YAML into Perl data. This is the opposite of Dump. Just like Storable's thaw() function or the eval() function in relation to Data::Dumper. It parses a string containing a valid YAML stream into a list of Perl data structures.

Exportable Functions

These functions are not exported by default but you can request them in an import list like this:

    use YAML qw'freeze thaw Bless';
freeze() and thaw()

Aliases to Dump() and Load() for Storable fans. This will also allow YAML.pm to be plugged directly into modules like POE.pm, that use the freeze/thaw API for internal serialization.

DumpFile(filepath, list)

Writes the YAML stream to a file instead of just returning a string.

LoadFile(filepath)

Reads the YAML stream from a file instead of a string.

Bless(perl-node, [yaml-node | class-name])

Associate a normal Perl node, with a yaml node. A yaml node is an object tied to the YAML::Node class. The second argument is either a yaml node that you've already created or a class (package) name that supports a yaml_dump() function. A yaml_dump() function should take a perl node and return a yaml node. If no second argument is provided, Bless will create a yaml node. This node is not returned, but can be retrieved with the Blessed() function.

Here's an example of how to use Bless. Say you have a hash containing three keys, but you only want to dump two of them. Furthermore the keys must be dumped in a certain order. Here's how you do that:

    use YAML qw(Dump Bless);
    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
    print Dump $hash;
    Bless($hash)->keys(['banana', 'apple']);
    print Dump $hash;

produces:

    ---
    apple: good
    banana: bad
    cauliflower: ugly
    ---
    banana: bad
    apple: good

Bless returns the tied part of a yaml-node, so that you can call the YAML::Node methods. This is the same thing that YAML::Node::ynode() returns. So another way to do the above example is:

    use YAML qw(Dump Bless);
    use YAML::Node;
    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
    print Dump $hash;
    Bless($hash);
    $ynode = ynode(Blessed($hash));
    $ynode->keys(['banana', 'apple']);
    print Dump $hash;

Note that Blessing a Perl data structure does not change it anyway. The extra information is stored separately and looked up by the Blessed node's memory address.

Blessed(perl-node)

Returns the yaml node that a particular perl node is associated with (see above). Returns undef if the node is not (YAML) Blessed.

GLOBAL OPTIONS

YAML options are set using a group of global variables in the YAML namespace. This is similar to how Data::Dumper works.

For example, to change the indentation width, do something like:

    local $YAML::Indent = 3;

The current options are:

DumperClass

You can override which module/class YAML uses for Dumping data.

LoaderClass

You can override which module/class YAML uses for Loading data.

Indent

This is the number of space characters to use for each indentation level when doing a Dump(). The default is 2.

By the way, YAML can use any number of characters for indentation at any level. So if you are editing YAML by hand feel free to do it anyway that looks pleasing to you; just be consistent for a given level.

SortKeys

Default is 1. (true)

Tells YAML.pm whether or not to sort hash keys when storing a document.

YAML::Node objects can have their own sort order, which is usually what you want. To override the YAML::Node order and sort the keys anyway, set SortKeys to 2.

Stringify

Default is 0. (false)

Objects with string overloading should honor the overloading and dump the stringification of themselves, rather than the actual object's guts.

UseHeader

Default is 1. (true)

This tells YAML.pm whether to use a separator string for a Dump operation. This only applies to the first document in a stream. Subsequent documents must have a YAML header by definition.

UseVersion

Default is 0. (false)

Tells YAML.pm whether to include the YAML version on the separator/header.

    --- %YAML:1.0
AnchorPrefix

Default is ''.

Anchor names are normally numeric. YAML.pm simply starts with '1' and increases by one for each new anchor. This option allows you to specify a string to be prepended to each anchor number.

UseCode

Setting the UseCode option is a shortcut to set both the DumpCode and LoadCode options at once. Setting UseCode to '1' tells YAML.pm to dump Perl code references as Perl (using B::Deparse) and to load them back into memory using eval(). The reason this has to be an option is that using eval() to parse untrusted code is, well, untrustworthy.

DumpCode

Determines if and how YAML.pm should serialize Perl code references. By default YAML.pm will dump code references as dummy placeholders (much like Data::Dumper). If DumpCode is set to '1' or 'deparse', code references will be dumped as actual Perl code.

DumpCode can also be set to a subroutine reference so that you can write your own serializing routine. YAML.pm passes you the code ref. You pass back the serialization (as a string) and a format indicator. The format indicator is a simple string like: 'deparse' or 'bytecode'.

LoadCode

LoadCode is the opposite of DumpCode. It tells YAML if and how to deserialize code references. When set to '1' or 'deparse' it will use eval(). Since this is potentially risky, only use this option if you know where your YAML has been.

LoadCode can also be set to a subroutine reference so that you can write your own deserializing routine. YAML.pm passes the serialization (as a string) and a format indicator. You pass back the code reference.

UseBlock

YAML.pm uses heuristics to guess which scalar style is best for a given node. Sometimes you'll want all multiline scalars to use the 'block' style. If so, set this option to 1.

NOTE: YAML's block style is akin to Perl's here-document.

UseFold

If you want to force YAML to use the 'folded' style for all multiline scalars, then set $UseFold to 1.

NOTE: YAML's folded style is akin to the way HTML folds text, except smarter.

UseAliases

YAML has an alias mechanism such that any given structure in memory gets serialized once. Any other references to that structure are serialized only as alias markers. This is how YAML can serialize duplicate and recursive structures.

Sometimes, when you KNOW that your data is nonrecursive in nature, you may want to serialize such that every node is expressed in full. (ie as a copy of the original). Setting $YAML::UseAliases to 0 will allow you to do this. This also may result in faster processing because the lookup overhead is by bypassed.

THIS OPTION CAN BE DANGEROUS. *If* your data is recursive, this option *will* cause Dump() to run in an endless loop, chewing up your computers memory. You have been warned.

CompressSeries

Default is 1.

Compresses the formatting of arrays of hashes:

    -
      foo: bar
    -
      bar: foo

becomes:

    - foo: bar
    - bar: foo

Since this output is usually more desirable, this option is turned on by default.

YAML TERMINOLOGY

YAML is a full featured data serialization language, and thus has its own terminology.

It is important to remember that although YAML is heavily influenced by Perl and Python, it is a language in its own right, not merely just a representation of Perl structures.

YAML has three constructs that are conspicuously similar to Perl's hash, array, and scalar. They are called mapping, sequence, and string respectively. By default, they do what you would expect. But each instance may have an explicit or implicit tag (type) that makes it behave differently. In this manner, YAML can be extended to represent Perl's Glob or Python's tuple, or Ruby's Bigint.

stream

A YAML stream is the full sequence of unicode characters that a YAML parser would read or a YAML emitter would write. A stream may contain one or more YAML documents separated by YAML headers.

    ---
    a: mapping
    foo: bar
    ---
    - a
    - sequence
document

A YAML document is an independent data structure representation within a stream. It is a top level node. Each document in a YAML stream must begin with a YAML header line. Actually the header is optional on the first document.

    ---
    This: top level mapping
    is:
        - a
        - YAML
        - document
header

A YAML header is a line that begins a YAML document. It consists of three dashes, possibly followed by more info. Another purpose of the header line is that it serves as a place to put top level tag and anchor information.

    --- !recursive-sequence &001
    - * 001
    - * 001
node

A YAML node is the representation of a particular data stucture. Nodes may contain other nodes. (In Perl terms, nodes are like scalars. Strings, arrayrefs and hashrefs. But this refers to the serialized format, not the in-memory structure.)

tag

This is similar to a type. It indicates how a particular YAML node serialization should be transferred into or out of memory. For instance a Foo::Bar object would use the tag 'perl/Foo::Bar':

    - !perl/Foo::Bar
        foo: 42
        bar: stool
collection

A collection is the generic term for a YAML data grouping. YAML has two types of collections: mappings and sequences. (Similar to hashes and arrays)

mapping

A mapping is a YAML collection defined by unordered key/value pairs with unique keys. By default YAML mappings are loaded into Perl hashes.

    a mapping:
        foo: bar
        two: times two is 4
sequence

A sequence is a YAML collection defined by an ordered list of elements. By default YAML sequences are loaded into Perl arrays.

    a sequence:
        - one bourbon
        - one scotch
        - one beer
scalar

A scalar is a YAML node that is a single value. By default YAML scalars are loaded into Perl scalars.

    a scalar key: a scalar value

YAML has many styles for representing scalars. This is important because varying data will have varying formatting requirements to retain the optimum human readability.

plain scalar

A plain sclar is unquoted. All plain scalars are automatic candidates for "implicit tagging". This means that their tag may be determined automatically by examination. The typical uses for this are plain alpha strings, integers, real numbers, dates, times and currency.

    - a plain string
    - -42
    - 3.1415
    - 12:34
    - 123 this is an error
single quoted scalar

This is similar to Perl's use of single quotes. It means no escaping except for single quotes which are escaped by using two adjacent single quotes.

    - 'When I say ''\n'' I mean "backslash en"'
double quoted scalar

This is similar to Perl's use of double quotes. Character escaping can be used.

    - "This scalar\nhas two lines, and a bell -->\a"
folded scalar

This is a multiline scalar which begins on the next line. It is indicated by a single right angle bracket. It is unescaped like the single quoted scalar. Line folding is also performed.

    - >
     This is a multiline scalar which begins on
     the next line. It is indicated by a single
     carat. It is unescaped like the single
     quoted scalar. Line folding is also
     performed.
block scalar

This final multiline form is akin to Perl's here-document except that (as in all YAML data) scope is indicated by indentation. Therefore, no ending marker is required. The data is verbatim. No line folding.

    - |
        QTY  DESC          PRICE  TOTAL
        ---  ----          -----  -----
          1  Foo Fighters  $19.95 $19.95
          2  Bar Belles    $29.95 $59.90
parser

A YAML processor has four stages: parse, load, dump, emit.

A parser parses a YAML stream. YAML.pm's Load() function contains a parser.

loader

The other half of the Load() function is a loader. This takes the information from the parser and loads it into a Perl data structure.

dumper

The Dump() function consists of a dumper and an emitter. The dumper walks through each Perl data structure and gives info to the emitter.

emitter

The emitter takes info from the dumper and turns it into a YAML stream.

NOTE: In YAML.pm the parser/loader and the dumper/emitter code are currently very closely tied together. In the future they may be broken into separate stages.

For more information please refer to the immensely helpful YAML specification available at http://www.yaml.org/spec/.

ysh - The YAML Shell

The YAML distribution ships with a script called 'ysh', the YAML shell. ysh provides a simple, interactive way to play with YAML. If you type in Perl code, it displays the result in YAML. If you type in YAML it turns it into Perl code.

To run ysh, (assuming you installed it along with YAML.pm) simply type:

    ysh [options]

Please read the ysh documentation for the full details. There are lots of options.

BUGS & DEFICIENCIES

If you find a bug in YAML, please try to recreate it in the YAML Shell with logging turned on ('ysh -L'). When you have successfully reproduced the bug, please mail the LOG file to the author (ingy@cpan.org)

WARNING: This is still *ALPHA* code. Well, most of this code has been around for years...

BIGGER WARNING: YAML.pm has been slow in the making, but I am committed to having top notch YAML tools in the Perl world. The YAML team is close to finalizing the YAML 1.1 spec. This version of YAML.pm is based off of a very old pre 1.0 spec. In actuality there isn't a ton of difference, and this YAML.pm is still fairly useful. Things will get much better in the future.

RESOURCES

http://lists.sourceforge.net/lists/listinfo/yaml-core is the mailing list. This is where the language is discussed and designed.

http://www.yaml.org is the official YAML website.

http://www.yaml.org/spec/ is the YAML 1.0 specification.

http://yaml.kwiki.org is the official YAML wiki.

SEE ALSO

See YAML::Syck. Fast!

AUTHOR

Ingy döt Net <ingy@cpan.org>

is resonsible for YAML.pm.

The YAML serialization language is the result of years of collaboration between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others have added help along the way.

COPYRIGHT

Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Base - Base class for YAML classes

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Base - Base class for YAML classes

SYNOPSIS

    package YAML::Something;
    use YAML::Base -base;

DESCRIPTION

YAML::Base is the parent of all YAML classes.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Dumper - YAML class for dumping Perl objects to YAML

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Dumper - YAML class for dumping Perl objects to YAML

SYNOPSIS

    use YAML::Dumper;
    my $dumper = YAML::Dumper->new;
    $dumper->indent_width(4);
    print $dumper->dump({foo => 'bar'});

DESCRIPTION

YAML::Dumper is the module that YAML.pm used to serialize Perl objects to YAML. It is fully object oriented and usable on its own.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Dumper::Base - Base class for YAML Dumper classes

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Dumper::Base - Base class for YAML Dumper classes

SYNOPSIS

    package YAML::Dumper::Something;
    use YAML::Dumper::Base -base;

DESCRIPTION

YAML::Dumper::Base is a base class for creating YAML dumper classes.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Error - Error formatting class for YAML modules

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Error - Error formatting class for YAML modules

SYNOPSIS

    $self->die('YAML_PARSE_ERR_NO_ANCHOR', $alias);
    $self->warn('YAML_LOAD_WARN_DUPLICATE_KEY');

DESCRIPTION

This module provides a die and a warn facility.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Loader - YAML class for loading Perl objects to YAML

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Loader - YAML class for loading Perl objects to YAML

SYNOPSIS

    use YAML::Loader;
    my $loader = YAML::Loader->new;
    my $hash = $loader->load(<<'...');
    foo: bar
    ...

DESCRIPTION

YAML::Loader is the module that YAML.pm used to deserialize YAML to Perl objects. It is fully object oriented and usable on its own.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Loader::Base - Base class for YAML Loader classes

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Loader::Base - Base class for YAML Loader classes

SYNOPSIS

    package YAML::Loader::Something;
    use YAML::Loader::Base -base;

DESCRIPTION

YAML::Loader::Base is a base class for creating YAML loader classes.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Marshall - YAML marshalling class you can mixin to your classes

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Marshall - YAML marshalling class you can mixin to your classes

SYNOPSIS

    package Bar;
    use Foo -base;
    use YAML::Marshall -mixin;

DESCRIPTION

For classes that want to handle their own YAML serialization.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Node - A generic data node that encapsulates YAML information

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Node - A generic data node that encapsulates YAML information

SYNOPSIS

    use YAML;
    use YAML::Node;

    my $ynode = YAML::Node->new({}, 'ingerson.com/fruit');
    %$ynode = qw(orange orange apple red grape green);
    print Dump $ynode;

yields:

    --- !ingerson.com/fruit
    orange: orange
    apple: red
    grape: green

DESCRIPTION

A generic node in YAML is similar to a plain hash, array, or scalar node in Perl except that it must also keep track of its type. The type is a URI called the YAML type tag.

YAML::Node is a class for generating and manipulating these containers. A YAML node (or ynode) is a tied hash, array or scalar. In most ways it behaves just like the plain thing. But you can assign and retrieve and YAML type tag URI to it. For the hash flavor, you can also assign the order that the keys will be retrieved in. By default a ynode will offer its keys in the same order that they were assigned.

YAML::Node has a class method call new() that will return a ynode. You pass it a regular node and an optional type tag. After that you can use it like a normal Perl node, but when you YAML::Dump it, the magical properties will be honored.

This is how you can control the sort order of hash keys during a YAML serialization. By default, YAML sorts keys alphabetically. But notice in the above example that the keys were Dumped in the same order they were assigned.

YAML::Node exports a function called ynode(). This function returns the tied object so that you can call special methods on it like ->keys().

keys() works like this:

    use YAML;
    use YAML::Node;

    %$node = qw(orange orange apple red grape green);
    $ynode = YAML::Node->new($node);
    ynode($ynode)->keys(['grape', 'apple']);
    print Dump $ynode;

produces:

    ---
    grape: green
    apple: red

It tells the ynode which keys and what order to use.

ynodes will play a very important role in how programs use YAML. They are the foundation of how a Perl class can marshall the Loading and Dumping of its objects.

The upcoming versions of YAML.pm will have much more information on this.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved. Copyright (c) 2002. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Tag - Tag URI object class for YAML

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Tag - Tag URI object class for YAML

SYNOPSIS

    use YAML::Tag;

DESCRIPTION

Used by YAML::Node.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


YAML::Transfer - Marshall Perl internal data types to/from YAML

  • AUTHOR
  • COPYRIGHT

NAME

YAML::Transfer - Marshall Perl internal data types to/from YAML

SYNOPSIS

    $::foo = 42;
    print YAML::Dump(*::foo);

    print YAML::Dump(qr{match me});

DESCRIPTION

This module has the helper classes for transferring objects, subroutines, references, globs, regexps and file handles to and from YAML.

AUTHOR

Ingy döt Net <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2006. Ingy döt Net. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


attributes - get/set subroutine or variable attributes

    • Built-in Attributes
    • Available Subroutines
    • Package-specific Attribute Handling
    • Syntax of Attribute Lists
  • EXPORTS
    • Default exports
    • Available exports
    • Export tags defined
  • EXAMPLES
  • SEE ALSO

NAME

attributes - get/set subroutine or variable attributes

SYNOPSIS

  sub foo : method ;
  my ($x,@y,%z) : Bent = 1;
  my $s = sub : method { ... };

  use attributes ();    # optional, to get subroutine declarations
  my @attrlist = attributes::get(\&foo);

  use attributes 'get'; # import the attributes::get subroutine
  my @attrlist = get \&foo;

DESCRIPTION

Subroutine declarations and definitions may optionally have attribute lists associated with them. (Variable my declarations also may, but see the warning below.) Perl handles these declarations by passing some information about the call site and the thing being declared along with the attribute list to this module. In particular, the first example above is equivalent to the following:

    use attributes __PACKAGE__, \&foo, 'method';

The second example in the synopsis does something equivalent to this:

    use attributes ();
    my ($x,@y,%z);
    attributes::->import(__PACKAGE__, \$x, 'Bent');
    attributes::->import(__PACKAGE__, \@y, 'Bent');
    attributes::->import(__PACKAGE__, \%z, 'Bent');
    ($x,@y,%z) = 1;

Yes, that's a lot of expansion.

WARNING: attribute declarations for variables are still evolving. The semantics and interfaces of such declarations could change in future versions. They are present for purposes of experimentation with what the semantics ought to be. Do not rely on the current implementation of this feature.

There are only a few attributes currently handled by Perl itself (or directly by this module, depending on how you look at it.) However, package-specific attributes are allowed by an extension mechanism. (See Package-specific Attribute Handling below.)

The setting of subroutine attributes happens at compile time. Variable attributes in our declarations are also applied at compile time. However, my variables get their attributes applied at run-time. This means that you have to reach the run-time component of the my before those attributes will get applied. For example:

    my $x : Bent = 42 if 0;

will neither assign 42 to $x nor will it apply the Bent attribute to the variable.

An attempt to set an unrecognized attribute is a fatal error. (The error is trappable, but it still stops the compilation within that eval.) Setting an attribute with a name that's all lowercase letters that's not a built-in attribute (such as "foo") will result in a warning with -w or use warnings 'reserved'.

Built-in Attributes

The following are the built-in attributes for subroutines:

locked

5.005 threads only! The use of the "locked" attribute currently only makes sense if you are using the deprecated "Perl 5.005 threads" implementation of threads.

Setting this attribute is only meaningful when the subroutine or method is to be called by multiple threads. When set on a method subroutine (i.e., one marked with the method attribute below), Perl ensures that any invocation of it implicitly locks its first argument before execution. When set on a non-method subroutine, Perl ensures that a lock is taken on the subroutine itself before execution. The semantics of the lock are exactly those of one explicitly taken with the lock operator immediately after the subroutine is entered.

method

Indicates that the referenced subroutine is a method. This has a meaning when taken together with the locked attribute, as described there. It also means that a subroutine so marked will not trigger the "Ambiguous call resolved as CORE::%s" warning.

lvalue

Indicates that the referenced subroutine is a valid lvalue and can be assigned to. The subroutine must return a modifiable value such as a scalar variable, as described in the perlsub manpage.

For global variables there is unique attribute: see our in the perlfunc manpage.

Available Subroutines

The following subroutines are available for general use once this module has been loaded:

get

This routine expects a single parameter--a reference to a subroutine or variable. It returns a list of attributes, which may be empty. If passed invalid arguments, it uses die() (via Carp::croak) to raise a fatal exception. If it can find an appropriate package name for a class method lookup, it will include the results from a FETCH_type_ATTRIBUTES call in its return list, as described in Package-specific Attribute Handling below. Otherwise, only built-in attributes will be returned.

reftype

This routine expects a single parameter--a reference to a subroutine or variable. It returns the built-in type of the referenced variable, ignoring any package into which it might have been blessed. This can be useful for determining the type value which forms part of the method names described in Package-specific Attribute Handling below.

Note that these routines are not exported by default.

Package-specific Attribute Handling

WARNING: the mechanisms described here are still experimental. Do not rely on the current implementation. In particular, there is no provision for applying package attributes to 'cloned' copies of subroutines used as closures. (See Making References in the perlref manpage for information on closures.) Package-specific attribute handling may change incompatibly in a future release.

When an attribute list is present in a declaration, a check is made to see whether an attribute 'modify' handler is present in the appropriate package (or its @ISA inheritance tree). Similarly, when attributes::get is called on a valid reference, a check is made for an appropriate attribute 'fetch' handler. See EXAMPLES to see how the "appropriate package" determination works.

The handler names are based on the underlying type of the variable being declared or of the reference passed. Because these attributes are associated with subroutine or variable declarations, this deliberately ignores any possibility of being blessed into some package. Thus, a subroutine declaration uses "CODE" as its type, and even a blessed hash reference uses "HASH" as its type.

The class methods invoked for modifying and fetching are these:

FETCH_type_ATTRIBUTES

This method receives a single argument, which is a reference to the variable or subroutine for which package-defined attributes are desired. The expected return value is a list of associated attributes. This list may be empty.

MODIFY_type_ATTRIBUTES

This method is called with two fixed arguments, followed by the list of attributes from the relevant declaration. The two fixed arguments are the relevant package name and a reference to the declared subroutine or variable. The expected return value is a list of attributes which were not recognized by this handler. Note that this allows for a derived class to delegate a call to its base class, and then only examine the attributes which the base class didn't already handle for it.

The call to this method is currently made during the processing of the declaration. In particular, this means that a subroutine reference will probably be for an undefined subroutine, even if this declaration is actually part of the definition.

Calling attributes::get() from within the scope of a null package declaration package ; for an unblessed variable reference will not provide any starting package name for the 'fetch' method lookup. Thus, this circumstance will not result in a method call for package-defined attributes. A named subroutine knows to which symbol table entry it belongs (or originally belonged), and it will use the corresponding package. An anonymous subroutine knows the package name into which it was compiled (unless it was also compiled with a null package declaration), and so it will use that package name.

Syntax of Attribute Lists

An attribute list is a sequence of attribute specifications, separated by whitespace or a colon (with optional whitespace). Each attribute specification is a simple name, optionally followed by a parenthesised parameter list. If such a parameter list is present, it is scanned past as for the rules for the q() operator. (See Quote and Quote-like Operators in the perlop manpage.) The parameter list is passed as it was found, however, and not as per q().

Some examples of syntactically valid attribute lists:

    switch(10,foo(7,3))  :  expensive
    Ugly('\(") :Bad
    _5x5
    locked method

Some examples of syntactically invalid attribute lists (with annotation):

    switch(10,foo()             # ()-string not balanced
    Ugly('(')                   # ()-string not balanced
    5x5                         # "5x5" not a valid identifier
    Y2::north                   # "Y2::north" not a simple identifier
    foo + bar                   # "+" neither a colon nor whitespace

EXPORTS

Default exports

None.

Available exports

The routines get and reftype are exportable.

Export tags defined

The :ALL tag will get all of the above exports.

EXAMPLES

Here are some samples of syntactically valid declarations, with annotation as to how they resolve internally into use attributes invocations by perl. These examples are primarily useful to see how the "appropriate package" is found for the possible method lookups for package-defined attributes.

  1. Code:

        package Canine;
    package Dog;
    my Canine $spot : Watchful ;

    Effect:

        use attributes ();
    attributes::->import(Canine => \$spot, "Watchful");

  2. Code:

        package Felis;
    my $cat : Nervous;

    Effect:

        use attributes ();
    attributes::->import(Felis => \$cat, "Nervous");

  3. Code:

        package X;
    sub foo : locked ;

    Effect:

        use attributes X => \&foo, "locked";

  4. Code:

        package X;
    sub Y::x : locked { 1 }

    Effect:

        use attributes Y => \&Y::x, "locked";

  5. Code:

        package X;
    sub foo { 1 }

        package Y;
    BEGIN { *bar = \&X::foo; }

        package Z;
    sub Y::bar : locked ;

    Effect:

        use attributes X => \&X::foo, "locked";

This last example is purely for purposes of completeness. You should not be trying to mess with the attributes of something in a package that's not your own.

SEE ALSO

Private Variables via my() in the perlsub manpage and Subroutine Attributes in the perlsub manpage for details on the basic declarations; the attrs manpage for the obsolescent form of subroutine attribute specification which this module replaces; use in the perlfunc manpage for details on the normal invocation mechanism.


attrs - set/get attributes of a subroutine

NAME

attrs - set/get attributes of a subroutine (deprecated)

SYNOPSIS

    sub foo {
        use attrs qw(locked method);
        ...
    }

    @a = attrs::get(\&foo);

DESCRIPTION

NOTE: Use of this pragma is deprecated. Use the syntax

    sub foo : locked method { }

to declare attributes instead. See also the attributes manpage.

This pragma lets you set and get attributes for subroutines. Setting attributes takes place at compile time; trying to set invalid attribute names causes a compile-time error. Calling attrs::get on a subroutine reference or name returns its list of attribute names. Notice that attrs::get is not exported. Valid attributes are as follows.

method

Indicates that the invoking subroutine is a method.

locked

Setting this attribute is only meaningful when the subroutine or method is to be called by multiple threads. When set on a method subroutine (i.e. one marked with the method attribute above), perl ensures that any invocation of it implicitly locks its first argument before execution. When set on a non-method subroutine, perl ensures that a lock is taken on the subroutine itself before execution. The semantics of the lock are exactly those of one explicitly taken with the lock operator immediately after the subroutine is entered.


autouse - postpone load of modules until a function is used

  • WARNING
  • AUTHOR
  • SEE ALSO

NAME

autouse - postpone load of modules until a function is used

SYNOPSIS

  use autouse 'Carp' => qw(carp croak);
  carp "this carp was predeclared and autoused ";

DESCRIPTION

If the module Module is already loaded, then the declaration

  use autouse 'Module' => qw(func1 func2($;$));

is equivalent to

  use Module qw(func1 func2);

if Module defines func2() with prototype ($;$), and func1() has no prototypes. (At least if Module uses Exporter's import, otherwise it is a fatal error.)

If the module Module is not loaded yet, then the above declaration declares functions func1() and func2() in the current package. When these functions are called, they load the package Module if needed, and substitute themselves with the correct definitions.

WARNING

Using autouse will move important steps of your program's execution from compile time to runtime. This can

  • Break the execution of your program if the module you autoused has some initialization which it expects to be done early.

  • hide bugs in your code since important checks (like correctness of prototypes) is moved from compile time to runtime. In particular, if the prototype you specified on autouse line is wrong, you will not find it out until the corresponding function is executed. This will be very unfortunate for functions which are not always called (note that for such functions autouseing gives biggest win, for a workaround see below).

To alleviate the second problem (partially) it is advised to write your scripts like this:

  use Module;
  use autouse Module => qw(carp($) croak(&$));
  carp "this carp was predeclared and autoused ";

The first line ensures that the errors in your argument specification are found early. When you ship your application you should comment out the first line, since it makes the second one useless.

AUTHOR

Ilya Zakharevich (ilya@math.ohio-state.edu)

SEE ALSO

perl(1).


base - Establish IS-A relationship with base classes at compile time

  • DIAGNOSTICS
  • HISTORY
  • CAVEATS
  • SEE ALSO

NAME

base - Establish IS-A relationship with base classes at compile time

SYNOPSIS

    package Baz;
    use base qw(Foo Bar);

DESCRIPTION

Allows you to both load one or more modules, while setting up inheritance from those modules at the same time. Roughly similar in effect to

    package Baz;
    BEGIN {
        require Foo;
        require Bar;
        push @ISA, qw(Foo Bar);
    }

If any of the listed modules are not loaded yet, base silently attempts to require them (and silently continues if the require failed). Whether to require a base class module is determined by the absence of a global variable $VERSION in the base package. If $VERSION is not detected even after loading it, <base> will define $VERSION in the base package, setting it to the string -1, set by base.pm.

Will also initialize the fields if one of the base classes has it. Multiple inheritence of fields is NOT supported, if two or more base classes each have inheritable fields the 'base' pragma will croak. See the fields manpage, public and protected for a description of this feature.

DIAGNOSTICS

Base class package "%s" is empty.

base.pm was unable to require the base package, because it was not found in your path.

HISTORY

This module was introduced with Perl 5.004_04.

CAVEATS

Due to the limitations of the implementation, you must use base before you declare any of your own fields.

SEE ALSO

the fields manpage


bigint - Transparent BigInteger support for Perl

    • Options
    • Math Library
    • Internal Format
    • Sign
    • Methods
    • Caveat
  • MODULES USED
  • EXAMPLES
  • LICENSE
  • SEE ALSO
  • AUTHORS

NAME

bigint - Transparent BigInteger support for Perl

SYNOPSIS

  use bigint;

  $x = 2 + 4.5,"\n";                    # BigInt 6
  print 2 ** 512,"\n";                  # really is what you think it is
  print inf + 42,"\n";                  # inf
  print NaN * 7,"\n";                   # NaN

DESCRIPTION

All operators (including basic math operations) are overloaded. Integer constants are created as proper BigInts.

Floating point constants are truncated to integer. All results are also truncated.

Options

bigint recognizes some options that can be passed while loading it via use. The options can (currently) be either a single letter form, or the long form. The following options exist:

a or accuracy

This sets the accuracy for all math operations. The argument must be greater than or equal to zero. See Math::BigInt's bround() function for details.

        perl -Mbigint=a,2 -le 'print 12345+1'
p or precision

This sets the precision for all math operations. The argument can be any integer. Negative values mean a fixed number of digits after the dot, and are <B>ignored</B> since all operations happen in integer space. A positive value rounds to this digit left from the dot. 0 or 1 mean round to integer and are ignore like negative values.

See Math::BigInt's bfround() function for details.

        perl -Mbignum=p,5 -le 'print 123456789+123'
t or trace

This enables a trace mode and is primarily for debugging bigint or Math::BigInt.

l or lib

Load a different math lib, see MATH LIBRARY.

        perl -Mbigint=l,GMP -e 'print 2 ** 512'

Currently there is no way to specify more than one library on the command line. This will be hopefully fixed soon ;)

v or version

This prints out the name and version of all modules used and then exits.

        perl -Mbigint=v

Math Library

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use bigint lib => 'Calc';

You can change this by using:

        use bigint lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use bigint lib => 'Foo,Math::BigInt::Bar';

Please see respective module documentation for further details.

Internal Format

The numbers are stored as objects, and their internals might change at anytime, especially between math operations. The objects also might belong to different classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even with normal scalars is not extraordinary, but normal and expected.

You should not depend on the internal format, all accesses must go through accessor methods. E.g. looking at $x->{sign} is not a good idea since there is no guaranty that the object in question has such a hash key, nor is a hash underneath at all.

Sign

The sign is either '+', '-', 'NaN', '+inf' or '-inf'. You can access it with the sign() method.

A sign of 'NaN' is used to represent the result when input arguments are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively minus infinity. You will get '+inf' when dividing a positive number by 0, and '-inf' when dividing any negative number by 0.

Methods

Since all numbers are now objects, you can use all functions that are part of the BigInt API. You can only use the bxxx() notation, and not the fxxx() notation, though.

Caveat

But a warning is in order. When using the following to make a copy of a number, only a shallow copy will be made.

        $x = 9; $y = $x;
        $x = $y = 7;

Using the copy or the original with overloaded math is okay, e.g. the following work:

        $x = 9; $y = $x;
        print $x + 1, " ", $y,"\n";     # prints 10 9

but calling any method that modifies the number directly will result in both the original and the copy beeing destroyed:

        $x = 9; $y = $x;
        print $x->badd(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->binc(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->bmul(2), " ", $y,"\n";        # prints 18 18

Using methods that do not modify, but testthe contents works:
        $x = 9; $y = $x;
        $z = 9 if $x->is_zero();                # works fine

See the documentation about the copy constructor and = in overload, as well as the documentation in BigInt for further details.

MODULES USED

bigint is just a thin wrapper around various modules of the Math::BigInt family. Think of it as the head of the family, who runs the shop, and orders the others to do the work.

The following modules are currently used by bigint:

        Math::BigInt::Lite      (for speed, and only if it is loadable)
        Math::BigInt

EXAMPLES

Some cool command line examples to impress the Python crowd ;) You might want to compare them to the results under -Mbignum or -Mbigrat:

        perl -Mbigint -le 'print sqrt(33)'
        perl -Mbigint -le 'print 2*255'
        perl -Mbigint -le 'print 4.5+2*255'
        perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
        perl -Mbigint -le 'print 123->is_odd()'
        perl -Mbigint -le 'print log(2)'
        perl -Mbigint -le 'print 2 ** 0.5'
        perl -Mbigint=a,65 -le 'print 2 ** 0.2'

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Especially the bigrat manpage as in perl -Mbigrat -le 'print 1/3+1/4' and the bignum manpage as in perl -Mbignum -le 'print sqrt(2)'.

the Math::BigInt manpage, the Math::BigRat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

AUTHORS

(C) by Tels http://bloodgate.com/ in early 2002 - 2005.


bignum - Transparent BigNumber support for Perl

    • Options
    • Methods
    • Caveat
    • MATH LIBRARY
    • INTERNAL FORMAT
    • SIGN
  • MODULES USED
  • EXAMPLES
  • LICENSE
  • SEE ALSO
  • AUTHORS

NAME

bignum - Transparent BigNumber support for Perl

SYNOPSIS

  use bignum;

  $x = 2 + 4.5,"\n";                    # BigFloat 6.5
  print 2 ** 512 * 0.1,"\n";            # really is what you think it is
  print inf * inf,"\n";                 # prints inf
  print NaN * 3,"\n";                   # prints NaN

DESCRIPTION

All operators (including basic math operations) are overloaded. Integer and floating-point constants are created as proper BigInts or BigFloats, respectively.

If you do

        use bignum;

at the top of your script, Math::BigFloat and Math::BigInt will be loaded and any constant number will be converted to an object (Math::BigFloat for floats like 3.1415 and Math::BigInt for integers like 1234).

So, the following line:

        $x = 1234;

creates actually a Math::BigInt and stores a reference to in $x. This happens transparently and behind your back, so to speak.

You can see this with the following:

        perl -Mbignum -le 'print ref(1234)'

Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite if it is installed since it is faster for some operations. It will be automatically upgraded to BigInt whenever neccessary:

        perl -Mbignum -le 'print ref(2**255)'

This also means it is a bad idea to check for some specific package, since the actual contents of $x might be something unexpected. Due to the transparent way of bignum ref() should not be neccessary, anyway.

Since Math::BigInt and BigFloat also overload the normal math operations, the following line will still work:

        perl -Mbignum -le 'print ref(1234+1234)'

Since numbers are actually objects, you can call all the usual methods from BigInt/BigFloat on them. This even works to some extent on expressions:

        perl -Mbignum -le '$x = 1234; print $x->bdec()'
        perl -Mbignum -le 'print 1234->binc();'
        perl -Mbignum -le 'print 1234->binc->badd(6);'
        perl -Mbignum -le 'print +(1234)->binc()'

(Note that print doesn't do what you expect if the expression starts with '(' hence the +)

You can even chain the operations together as usual:

        perl -Mbignum -le 'print 1234->binc->badd(6);'
        1241

Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers appropriately. This means that:

        perl -Mbignum -le 'print 1234+4.5'
        1238.5

will work correctly. These mixed cases don't do always work when using Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl scalars work.

If you do want to work with large integers like under use integer;, try use bigint;:

        perl -Mbigint -le 'print 1234.5+4.5'
        1238

There is also use bigrat; which gives you big rationals:

        perl -Mbigrat -le 'print 1234+4.1'
        12381/10

The entire upgrading/downgrading is still experimental and might not work as you expect or may even have bugs.

You might get errors like this:

        Can't use an undefined value as an ARRAY reference at
        /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864

This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or vice versa) and the upgrade/downgrad path was missing. This is a bug, please report it so that we can fix it.

You might consider using just Math::BigInt or Math::BigFloat, since they allow you finer control over what get's done in which module/space. For instance, simple loop counters will be Math::BigInts under use bignum; and this is slower than keeping them as Perl scalars:

        perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'

Please note the following does not work as expected (prints nothing), since overloading of '..' is not yet possible in Perl (as of v5.8.0):

        perl -Mbignum -le 'for (1..2) { print ref($_); }'

Options

bignum recognizes some options that can be passed while loading it via use. The options can (currently) be either a single letter form, or the long form. The following options exist:

a or accuracy

This sets the accuracy for all math operations. The argument must be greater than or equal to zero. See Math::BigInt's bround() function for details.

        perl -Mbignum=a,50 -le 'print sqrt(20)'
p or precision

This sets the precision for all math operations. The argument can be any integer. Negative values mean a fixed number of digits after the dot, while a positive value rounds to this digit left from the dot. 0 or 1 mean round to integer. See Math::BigInt's bfround() function for details.

        perl -Mbignum=p,-50 -le 'print sqrt(20)'
t or trace

This enables a trace mode and is primarily for debugging bignum or Math::BigInt/Math::BigFloat.

l or lib

Load a different math lib, see MATH LIBRARY.

        perl -Mbignum=l,GMP -e 'print 2 ** 512'

Currently there is no way to specify more than one library on the command line. This will be hopefully fixed soon ;)

v or version

This prints out the name and version of all modules used and then exits.

        perl -Mbignum=v

Methods

Beside import() and AUTOLOAD() there are only a few other methods.

Since all numbers are now objects, you can use all functions that are part of the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not the fxxx() notation, though. This makes it possible that the underlying object might morph into a different class than BigFloat.

Caveat

But a warning is in order. When using the following to make a copy of a number, only a shallow copy will be made.

        $x = 9; $y = $x;
        $x = $y = 7;

If you want to make a real copy, use the following:

        $y = $x->copy();

Using the copy or the original with overloaded math is okay, e.g. the following work:

        $x = 9; $y = $x;
        print $x + 1, " ", $y,"\n";     # prints 10 9

but calling any method that modifies the number directly will result in both the original and the copy beeing destroyed:

        $x = 9; $y = $x;
        print $x->badd(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->binc(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->bmul(2), " ", $y,"\n";        # prints 18 18

Using methods that do not modify, but testthe contents works:

        $x = 9; $y = $x;
        $z = 9 if $x->is_zero();                # works fine

See the documentation about the copy constructor and = in overload, as well as the documentation in BigInt for further details.

inf()

A shortcut to return Math::BigInt->binf(). Usefull because Perl does not always handle bareword inf properly.

NaN()

A shortcut to return Math::BigInt->bnan(). Usefull because Perl does not always handle bareword NaN properly.

upgrade()

Return the class that numbers are upgraded to, is in fact returning $Math::BigInt::upgrade.

MATH LIBRARY

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use bignum lib => 'Calc';

You can change this by using:

        use bignum lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use bignum lib => 'Foo,Math::BigInt::Bar';

Please see respective module documentation for further details.

INTERNAL FORMAT

The numbers are stored as objects, and their internals might change at anytime, especially between math operations. The objects also might belong to different classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even with normal scalars is not extraordinary, but normal and expected.

You should not depend on the internal format, all accesses must go through accessor methods. E.g. looking at $x->{sign} is not a bright idea since there is no guaranty that the object in question has such a hashkey, nor is a hash underneath at all.

SIGN

The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately. You can access it with the sign() method.

A sign of 'NaN' is used to represent the result when input arguments are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively minus infinity. You will get '+inf' when dividing a positive number by 0, and '-inf' when dividing any negative number by 0.

MODULES USED

bignum is just a thin wrapper around various modules of the Math::BigInt family. Think of it as the head of the family, who runs the shop, and orders the others to do the work.

The following modules are currently used by bignum:

        Math::BigInt::Lite      (for speed, and only if it is loadable)
        Math::BigInt
        Math::BigFloat

EXAMPLES

Some cool command line examples to impress the Python crowd ;)

        perl -Mbignum -le 'print sqrt(33)'
        perl -Mbignum -le 'print 2*255'
        perl -Mbignum -le 'print 4.5+2*255'
        perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
        perl -Mbignum -le 'print 123->is_odd()'
        perl -Mbignum -le 'print log(2)'
        perl -Mbignum -le 'print 2 ** 0.5'
        perl -Mbignum=a,65 -le 'print 2 ** 0.2'

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Especially the bigrat manpage as in perl -Mbigrat -le 'print 1/3+1/4'.

the Math::BigFloat manpage, the Math::BigInt manpage, the Math::BigRat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

AUTHORS

(C) by Tels http://bloodgate.com/ in early 2002, 2003.


bigrat - Transparent BigNumber/BigRational support for Perl

    • Modules Used
    • Math Library
    • Sign
    • Methods
    • Cavaet
    • Options
  • EXAMPLES
  • LICENSE
  • SEE ALSO
  • AUTHORS

NAME

bigrat - Transparent BigNumber/BigRational support for Perl

SYNOPSIS

  use bigrat;

  $x = 2 + 4.5,"\n";                    # BigFloat 6.5
  print 1/3 + 1/4,"\n";                 # produces 7/12

DESCRIPTION

All operators (inlcuding basic math operations) are overloaded. Integer and floating-point constants are created as proper BigInts or BigFloats, respectively.

Other than the bignum manpage, this module upgrades to Math::BigRat, meaning that instead of 2.5 you will get 2+1/2 as output.

Modules Used

bigrat is just a thin wrapper around various modules of the Math::BigInt family. Think of it as the head of the family, who runs the shop, and orders the others to do the work.

The following modules are currently used by bignum:

        Math::BigInt::Lite      (for speed, and only if it is loadable)
        Math::BigInt
        Math::BigFloat
        Math::BigRat

Math Library

Math with the numbers is done (by default) by a module called Math::BigInt::Calc. This is equivalent to saying:

        use bigrat lib => 'Calc';

You can change this by using:

        use bigrat lib => 'BitVect';

The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

        use bigrat lib => 'Foo,Math::BigInt::Bar';

Please see respective module documentation for further details.

Sign

The sign is either '+', '-', 'NaN', '+inf' or '-inf'.

A sign of 'NaN' is used to represent the result when input arguments are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively minus infinity. You will get '+inf' when dividing a positive number by 0, and '-inf' when dividing any negative number by 0.

Methods

Since all numbers are not objects, you can use all functions that are part of the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not the fxxx() notation, though. This makes you independed on the fact that the underlying object might morph into a different class than BigFloat.

Cavaet

But a warning is in order. When using the following to make a copy of a number, only a shallow copy will be made.

        $x = 9; $y = $x;
        $x = $y = 7;

If you want to make a real copy, use the following:

        $y = $x->copy();

Using the copy or the original with overloaded math is okay, e.g. the following work:

        $x = 9; $y = $x;
        print $x + 1, " ", $y,"\n";     # prints 10 9

but calling any method that modifies the number directly will result in both the original and the copy beeing destroyed:

        $x = 9; $y = $x;
        print $x->badd(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->binc(1), " ", $y,"\n";        # prints 10 10

        $x = 9; $y = $x;
        print $x->bmul(2), " ", $y,"\n";        # prints 18 18

Using methods that do not modify, but testthe contents works:

        $x = 9; $y = $x;
        $z = 9 if $x->is_zero();                # works fine

See the documentation about the copy constructor and = in overload, as well as the documentation in BigInt for further details.

Options

bignum recognizes some options that can be passed while loading it via use. The options can (currently) be either a single letter form, or the long form. The following options exist:

a or accuracy

This sets the accuracy for all math operations. The argument must be greater than or equal to zero. See Math::BigInt's bround() function for details.

        perl -Mbigrat=a,50 -le 'print sqrt(20)'
p or precision

This sets the precision for all math operations. The argument can be any integer. Negative values mean a fixed number of digits after the dot, while a positive value rounds to this digit left from the dot. 0 or 1 mean round to integer. See Math::BigInt's bfround() function for details.

        perl -Mbigrat=p,-50 -le 'print sqrt(20)'
t or trace

This enables a trace mode and is primarily for debugging bignum or Math::BigInt/Math::BigFloat.

l or lib

Load a different math lib, see MATH LIBRARY.

        perl -Mbigrat=l,GMP -e 'print 2 ** 512'

Currently there is no way to specify more than one library on the command line. This will be hopefully fixed soon ;)

v or version

This prints out the name and version of all modules used and then exits.

        perl -Mbigrat=v

EXAMPLES

        perl -Mbigrat -le 'print sqrt(33)'
        perl -Mbigrat -le 'print 2*255'
        perl -Mbigrat -le 'print 4.5+2*255'
        perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
        perl -Mbigrat -le 'print 12->is_odd()';

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Especially the bignum manpage.

the Math::BigFloat manpage, the Math::BigInt manpage, the Math::BigRat manpage and the Math::Big manpage as well as the Math::BigInt::BitVect manpage, the Math::BigInt::Pari manpage and the Math::BigInt::GMP manpage.

AUTHORS

(C) by Tels http://bloodgate.com/ in early 2002 - 2005.


blib - Use MakeMaker's uninstalled version of a package

  • BUGS
  • AUTHOR

NAME

blib - Use MakeMaker's uninstalled version of a package

SYNOPSIS

 perl -Mblib script [args...]
 perl -Mblib=dir script [args...]

DESCRIPTION

Looks for MakeMaker-like 'blib' directory structure starting in dir (or current directory) and working back up to five levels of '..'.

Intended for use on command line with -M option as a way of testing arbitrary scripts against an uninstalled version of a package.

However it is possible to :

 use blib;
 or
 use blib '..';

etc. if you really must.

BUGS

Pollutes global name space for development only task.

AUTHOR

Nick Ing-Simmons nik@tiuk.ti.com


bytes - Perl pragma to force byte semantics rather than character semantics

  • LIMITATIONS
  • SEE ALSO

NAME

bytes - Perl pragma to force byte semantics rather than character semantics

SYNOPSIS

    use bytes;
    ... chr(...);       # or bytes::chr
    ... index(...);     # or bytes::index
    ... length(...);    # or bytes::length
    ... ord(...);       # or bytes::ord
    ... rindex(...);    # or bytes::rindex
    ... substr(...);    # or bytes::substr
    no bytes;

DESCRIPTION

The use bytes pragma disables character semantics for the rest of the lexical scope in which it appears. no bytes can be used to reverse the effect of use bytes within the current lexical scope.

Perl normally assumes character semantics in the presence of character data (i.e. data that has come from a source that has been marked as being of a particular character encoding). When use bytes is in effect, the encoding is temporarily ignored, and each string is treated as a series of bytes.

As an example, when Perl sees $x = chr(400), it encodes the character in UTF-8 and stores it in $x. Then it is marked as character data, so, for instance, length $x returns 1. However, in the scope of the bytes pragma, $x is treated as a series of bytes - the bytes that make up the UTF8 encoding - and length $x returns 2:

    $x = chr(400);
    print "Length is ", length $x, "\n";     # "Length is 1"
    printf "Contents are %vd\n", $x;         # "Contents are 400"
    {
        use bytes; # or "require bytes; bytes::length()"
        print "Length is ", length $x, "\n"; # "Length is 2"
        printf "Contents are %vd\n", $x;     # "Contents are 198.144"
    }

chr(), ord(), substr(), index() and rindex() behave similarly.

For more on the implications and differences between character semantics and byte semantics, see the perluniintro manpage and the perlunicode manpage.

LIMITATIONS

bytes::substr() does not work as an lvalue().

SEE ALSO

the perluniintro manpage, the perlunicode manpage, the utf8 manpage


charnames - define character names for C<\N{named}> string literal escapes

  • CUSTOM TRANSLATORS
  • CUSTOM ALIASES
    • Anonymous hashes
    • Alias file
    • Alias shortcut
  • charnames::viacode(code)
  • charnames::vianame(name)
  • ALIASES
  • ILLEGAL CHARACTERS
  • BUGS

NAME

charnames - define character names for \N{named} string literal escapes

SYNOPSIS

  use charnames ':full';
  print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";

  use charnames ':short';
  print "\N{greek:Sigma} is an upper-case sigma.\n";

  use charnames qw(cyrillic greek);
  print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";

  use charnames ":full", ":alias" => {
    e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
  };
  print "\N{e_ACUTE} is a small letter e with an acute.\n";

  use charnames ();
  print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE"
  printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints "10330"

DESCRIPTION

Pragma use charnames supports arguments :full, :short, script names and customized aliases. If :full is present, for expansion of \N{CHARNAME}, the string CHARNAME is first looked up in the list of standard Unicode character names. If :short is present, and CHARNAME has the form SCRIPT:CNAME, then CNAME is looked up as a letter in script SCRIPT. If pragma use charnames is used with script name arguments, then for \N{CHARNAME} the name CHARNAME is looked up as a letter in the given scripts (in the specified order). Customized aliases are explained in CUSTOM ALIASES.

For lookup of CHARNAME inside a given script SCRIPTNAME this pragma looks for the names

  SCRIPTNAME CAPITAL LETTER CHARNAME
  SCRIPTNAME SMALL LETTER CHARNAME
  SCRIPTNAME LETTER CHARNAME

in the table of standard Unicode names. If CHARNAME is lowercase, then the CAPITAL variant is ignored, otherwise the SMALL variant is ignored.

Note that \N{...} is compile-time, it's a special form of string constant used inside double-quoted strings: in other words, you cannot use variables inside the \N{...}. If you want similar run-time functionality, use charnames::vianame().

For the C0 and C1 control characters (U+0000..U+001F, U+0080..U+009F) as of Unicode 3.1, there are no official Unicode names but you can use instead the ISO 6429 names (LINE FEED, ESCAPE, and so forth). In Unicode 3.2 (as of Perl 5.8) some naming changes take place ISO 6429 has been updated, see ALIASES. Also note that the U+UU80, U+0081, U+0084, and U+0099 do not have names even in ISO 6429.

Since the Unicode standard uses "U+HHHH", so can you: "\N{U+263a}" is the Unicode smiley face, or "\N{WHITE SMILING FACE}".

CUSTOM TRANSLATORS

The mechanism of translation of \N{...} escapes is general and not hardwired into charnames.pm. A module can install custom translations (inside the scope which uses the module) with the following magic incantation:

    use charnames ();           # for $charnames::hint_bits
    sub import {
        shift;
        $^H |= $charnames::hint_bits;
        $^H{charnames} = \&translator;
    }

Here translator() is a subroutine which takes CHARNAME as an argument, and returns text to insert into the string instead of the \N{CHARNAME} escape. Since the text to insert should be different in bytes mode and out of it, the function should check the current state of bytes-flag as in:

    use bytes ();                       # for $bytes::hint_bits
    sub translator {
        if ($^H & $bytes::hint_bits) {
            return bytes_translator(@_);
        }
        else {
            return utf8_translator(@_);
        }
    }

CUSTOM ALIASES

This version of charnames supports three mechanisms of adding local or customized aliases to standard Unicode naming conventions (:full)

Anonymous hashes

    use charnames ":full", ":alias" => {
        e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
        };
    my $str = "\N{e_ACUTE}";

Alias file

    use charnames ":full", ":alias" => "pro";

    will try to read "unicore/pro_alias.pl" from the @INC path. This
    file should return a list in plain perl:
    (
    A_GRAVE         => "LATIN CAPITAL LETTER A WITH GRAVE",
    A_CIRCUM        => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
    A_DIAERES       => "LATIN CAPITAL LETTER A WITH DIAERESIS",
    A_TILDE         => "LATIN CAPITAL LETTER A WITH TILDE",
    A_BREVE         => "LATIN CAPITAL LETTER A WITH BREVE",
    A_RING          => "LATIN CAPITAL LETTER A WITH RING ABOVE",
    A_MACRON        => "LATIN CAPITAL LETTER A WITH MACRON",
    );

Alias shortcut

    use charnames ":alias" => ":pro";

    works exactly the same as the alias pairs, only this time,
    ":full" is inserted automatically as first argument (if no
    other argument is given).

charnames::viacode(code)

Returns the full name of the character indicated by the numeric code. The example

    print charnames::viacode(0x2722);

prints "FOUR TEARDROP-SPOKED ASTERISK".

Returns undef if no name is known for the code.

This works only for the standard names, and does not yet apply to custom translators.

Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK SPACE", not "BYTE ORDER MARK".

charnames::vianame(name)

Returns the code point indicated by the name. The example

    printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");

prints "2722".

Returns undef if the name is unknown.

This works only for the standard names, and does not yet apply to custom translators.

ALIASES

A few aliases have been defined for convenience: instead of having to use the official names

    LINE FEED (LF)
    FORM FEED (FF)
    CARRIAGE RETURN (CR)
    NEXT LINE (NEL)

(yes, with parentheses) one can use

    LINE FEED
    FORM FEED
    CARRIAGE RETURN
    NEXT LINE
    LF
    FF
    CR
    NEL

One can also use

    BYTE ORDER MARK
    BOM

and

    ZWNJ
    ZWJ

for ZERO WIDTH NON-JOINER and ZERO WIDTH JOINER.

For backward compatibility one can use the old names for certain C0 and C1 controls

    old                         new
    HORIZONTAL TABULATION       CHARACTER TABULATION
    VERTICAL TABULATION         LINE TABULATION
    FILE SEPARATOR              INFORMATION SEPARATOR FOUR
    GROUP SEPARATOR             INFORMATION SEPARATOR THREE
    RECORD SEPARATOR            INFORMATION SEPARATOR TWO
    UNIT SEPARATOR              INFORMATION SEPARATOR ONE
    PARTIAL LINE DOWN           PARTIAL LINE FORWARD
    PARTIAL LINE UP             PARTIAL LINE BACKWARD

but the old names in addition to giving the character will also give a warning about being deprecated.

ILLEGAL CHARACTERS

If you ask by name for a character that does not exist, a warning is given and the Unicode replacement character "\x{FFFD}" is returned.

If you ask by code for a character that does not exist, no warning is given and undef is returned. (Though if you ask for a code point past U+10FFFF you do get a warning.)

BUGS

Since evaluation of the translation function happens in a middle of compilation (of a string literal), the translation function should not do any evals or requires. This restriction should be lifted in a future version of Perl.


constant - Perl pragma to declare constants

  • NOTES
    • List constants
    • Defining multiple constants at once
    • Magic constants
  • TECHNICAL NOTES
  • BUGS
  • AUTHOR
  • COPYRIGHT

NAME

constant - Perl pragma to declare constants

SYNOPSIS

    use constant PI    => 4 * atan2(1, 1);
    use constant DEBUG => 0;

    print "Pi equals ", PI, "...\n" if DEBUG;

    use constant {
        SEC   => 0,
        MIN   => 1,
        HOUR  => 2,
        MDAY  => 3,
        MON   => 4,
        YEAR  => 5,
        WDAY  => 6,
        YDAY  => 7,
        ISDST => 8,
    };

    use constant WEEKDAYS => qw(
        Sunday Monday Tuesday Wednesday Thursday Friday Saturday
    );

    print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\n";

DESCRIPTION

This will declare a symbol to be a constant with the given value.

When you declare a constant such as PI using the method shown above, each machine your script runs upon can have as many digits of accuracy as it can use. Also, your program will be easier to read, 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 3.14195.

When a constant is used in an expression, perl replaces it with its value at compile time, and may then optimize the expression further. In particular, any code in an if (CONSTANT) block will be optimized away if the constant is false.

NOTES

As with all use directives, defining a constant happens at compile time. Thus, it's probably not correct to put a constant declaration inside of a conditional statement (like if ($foo) { use constant ... }).

Constants defined using this module cannot be interpolated into strings like variables. However, concatenation works just fine:

    print "Pi equals PI...\n";        # WRONG: does not expand "PI"
    print "Pi equals ".PI."...\n";    # right

Even though a reference may be declared as a constant, the reference may point to data which may be changed, as this code shows.

    use constant ARRAY => [ 1,2,3,4 ];
    print ARRAY->[1];
    ARRAY->[1] = " be changed";
    print ARRAY->[1];

Dereferencing constant references incorrectly (such as using an array subscript on a constant hash reference, or vice versa) will be trapped at compile time.

Constants belong to the package they are defined in. To refer to a constant defined in another package, specify the full package name, as in Some::Package::CONSTANT. Constants may be exported by modules, and may also be called as either class or instance methods, that is, as Some::Package->CONSTANT or as $obj->CONSTANT where $obj is an instance of Some::Package. Subclasses may define their own constants to override those in their base class.

The 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 or underscore. Names beginning with a double underscore are reserved. Some poor choices for names will generate warnings, if warnings are enabled at compile time.

List constants

Constants may be lists of more (or less) than one value. A constant with no values evaluates to undef in scalar context. Note that constants with more than one value do not return their last value in scalar context as one might expect. They currently return the number of values, but this may change in the future. Do not use constants with multiple values in scalar context.

NOTE: This implies that the expression defining the value of a constant is evaluated in list context. This may produce surprises:

    use constant TIMESTAMP => localtime;                # WRONG!
    use constant TIMESTAMP => scalar localtime;         # right

The first line above defines TIMESTAMP as a 9-element list, as returned by localtime() in list context. To set it to the string returned by localtime() in scalar context, an explicit scalar keyword is required.

List constants are lists, not arrays. To index or slice them, they must be placed in parentheses.

    my @workdays = WEEKDAYS[1 .. 5];            # WRONG!
    my @workdays = (WEEKDAYS)[1 .. 5];          # right

Defining multiple constants at once

Instead of writing multiple use constant statements, you may define multiple constants in a single statement by giving, instead of the constant name, a reference to a hash where the keys are the names of the constants to be defined. Obviously, all constants defined using this method must have a single value.

    use constant {
        FOO => "A single value",
        BAR => "This", "won't", "work!",        # Error!
    };

This is a fundamental limitation of the way hashes are constructed in Perl. The error messages produced when this happens will often be quite cryptic -- in the worst case there may be none at all, and you'll only later find that something is broken.

When defining multiple constants, you cannot use the values of other constants defined in the same declaration. This is because the calling package doesn't know about any constant within that group until after the use statement is finished.

    use constant {
        BITMASK => 0xAFBAEBA8,
        NEGMASK => ~BITMASK,                    # Error!
    };

Magic constants

Magical values and references can be made into constants at compile time, allowing for way cool stuff like this. (These error numbers aren't totally portable, alas.)

    use constant E2BIG => ($! = 7);
    print   E2BIG, "\n";        # something like "Arg list too long"
    print 0+E2BIG, "\n";        # "7"

You can't produce a tied constant by giving a tied scalar as the value. References to tied variables, however, can be used as constants without any problems.

TECHNICAL NOTES

In 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 in the perlsub manpage for details about how and when this happens.

In the rare case in which you need to discover at run time whether a particular constant has been declared via this module, you may use this function to examine the hash %constant::declared. If the given constant name does not include a package name, the current package is used.

    sub declared ($) {
        use constant 1.01;              # don't omit this!
        my $name = shift;
        $name =~ s/^::/main::/;
        my $pkg = caller;
        my $full_name = $name =~ /::/ ? $name : "${pkg}::$name";
        $constant::declared{$full_name};
    }

BUGS

In the current version of Perl, list constants are not inlined and some symbols may be redefined without generating a warning.

It is not possible to have a subroutine or a keyword with the same name as a constant in the same package. This is probably a Good Thing.

A constant with a name in the list STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG is not allowed anywhere but in package main::, for technical reasons.

Unlike constants in some languages, these cannot be overridden on the command line or via environment variables.

You can get into trouble if you use constants in a context which automatically quotes barewords (as is true for any subroutine call). For example, you can't say $hash{CONSTANT} because CONSTANT will be interpreted as a string. Use $hash{CONSTANT()} or $hash{+CONSTANT} to prevent the bareword quoting mechanism from kicking in. Similarly, since the => operator quotes a bareword immediately to its left, you have to say CONSTANT() => 'value' (or simply use a comma in place of the big arrow) instead of CONSTANT => 'value'.

AUTHOR

Tom Phoenix, <rootbeer@redcat.com>, with help from many other folks.

Multiple constant declarations at once added by Casey West, <casey@geeknest.com>.

Documentation mostly rewritten by Ilmari Karonen, <perl@itz.pp.sci.fi>.

COPYRIGHT

Copyright (C) 1997, 1999 Tom Phoenix

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.


splain - produce verbose warning diagnostics

    • The diagnostics Pragma
    • The splain Program
  • EXAMPLES
  • INTERNALS
  • BUGS
  • AUTHOR

NAME

diagnostics, splain - produce verbose warning diagnostics

SYNOPSIS

Using the diagnostics pragma:

    use diagnostics;
    use diagnostics -verbose;

    enable  diagnostics;
    disable diagnostics;

Using the splain standalone filter program:

    perl program 2>diag.out
    splain [-v] [-p] diag.out

Using diagnostics to get stack traces from a misbehaving script:

    perl -Mdiagnostics=-traceonly my_script.pl

DESCRIPTION

The diagnostics Pragma

This module extends the terse diagnostics normally emitted by both the perl compiler and the perl interpreter (from running perl with a -w switch or use warnings), augmenting them with the more explicative and endearing descriptions found in the perldiag manpage. Like the other pragmata, it affects the compilation phase of your program rather than merely the execution phase.

To use in your program as a pragma, merely invoke

    use diagnostics;

at the start (or near the start) of your program. (Note that this does enable perl's -w flag.) Your whole compilation will then be subject(ed :-) to the enhanced diagnostics. These still go out STDERR.

Due to the interaction between runtime and compiletime issues, and because it's probably not a very good idea anyway, you may not use no diagnostics to turn them off at compiletime. However, you may control their behaviour at runtime using the disable() and enable() methods to turn them off and on respectively.

The -verbose flag first prints out the the perldiag manpage introduction before any other diagnostics. The $diagnostics::PRETTY variable can generate nicer escape sequences for pagers.

Warnings dispatched from perl itself (or more accurately, those that match descriptions found in the perldiag manpage) are only displayed once (no duplicate descriptions). User code generated warnings a la warn() are unaffected, allowing duplicate user messages to be displayed.

This module also adds a stack trace to the error message when perl dies. This is useful for pinpointing what caused the death. The -traceonly (or just -t) flag turns off the explanations of warning messages leaving just the stack traces. So if your script is dieing, run it again with

  perl -Mdiagnostics=-traceonly my_bad_script

to see the call stack at the time of death. By supplying the -warntrace (or just -w) flag, any warnings emitted will also come with a stack trace.

The splain Program

While apparently a whole nuther program, splain is actually nothing more than a link to the (executable) diagnostics.pm module, as well as a link to the diagnostics.pod documentation. The -v flag is like the use diagnostics -verbose directive. The -p flag is like the $diagnostics::PRETTY variable. Since you're post-processing with splain, there's no sense in being able to enable() or disable() processing.

Output from splain is directed to STDOUT, unlike the pragma.

EXAMPLES

The following file is certain to trigger a few errors at both runtime and compiletime:

    use diagnostics;
    print NOWHERE "nothing\n";
    print STDERR "\n\tThis message should be unadorned.\n";
    warn "\tThis is a user warning";
    print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
    my $a, $b = scalar <STDIN>;
    print "\n";
    print $x/$y;

If you prefer to run your program first and look at its problem afterwards, do this:

    perl -w test.pl 2>test.out
    ./splain < test.out

Note that this is not in general possible in shells of more dubious heritage, as the theoretical

    (perl -w test.pl >/dev/tty) >& test.out
    ./splain < test.out

Because you just moved the existing stdout to somewhere else.

If you don't want to modify your source code, but still have on-the-fly warnings, do this:

    exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-

Nifty, eh?

If you want to control warnings on the fly, do something like this. Make sure you do the use first, or you won't be able to get at the enable() or disable() methods.

    use diagnostics; # checks entire compilation phase
        print "\ntime for 1st bogus diags: SQUAWKINGS\n";
        print BOGUS1 'nada';
        print "done with 1st bogus\n";

    disable diagnostics; # only turns off runtime warnings
        print "\ntime for 2nd bogus: (squelched)\n";
        print BOGUS2 'nada';
        print "done with 2nd bogus\n";

    enable diagnostics; # turns back on runtime warnings
        print "\ntime for 3rd bogus: SQUAWKINGS\n";
        print BOGUS3 'nada';
        print "done with 3rd bogus\n";

    disable diagnostics;
        print "\ntime for 4th bogus: (squelched)\n";
        print BOGUS4 'nada';
        print "done with 4th bogus\n";

INTERNALS

Diagnostic messages derive from the perldiag.pod file when available at runtime. Otherwise, they may be embedded in the file itself when the splain package is built. See the Makefile for details.

If an extant $SIG{__WARN__} handler is discovered, it will continue to be honored, but only after the diagnostics::splainthis() function (the module's $SIG{__WARN__} interceptor) has had its way with your warnings.

There is a $diagnostics::DEBUG variable you may set if you're desperately curious what sorts of things are being intercepted.

    BEGIN { $diagnostics::DEBUG = 1 }

BUGS

Not being able to say "no diagnostics" is annoying, but may not be insurmountable.

The -pretty directive is called too late to affect matters. You have to do this instead, and before you load the module.

    BEGIN { $diagnostics::PRETTY = 1 }

I could start up faster by delaying compilation until it should be needed, but this gets a "panic: top_level" when using the pragma form in Perl 5.001e.

While it's true that this documentation is somewhat subserious, if you use a program named splain, you should expect a bit of whimsy.

AUTHOR

Tom Christiansen <tchrist@mox.perl.com>, 25 June 1995.


encoding - allows you to write your script in non-ascii or non-utf8

  • ABSTRACT
    • Literal Conversions
    • PerlIO layers for STD(IN|OUT)
    • Implicit upgrading for byte strings
  • FEATURES THAT REQUIRE 5.8.1
  • USAGE
  • The Filter Option
    • Filter-related changes at Encode version 1.87
  • CAVEATS
    • NOT SCOPED
    • DO NOT MIX MULTIPLE ENCODINGS
    • tr/// with ranges
      • workaround to tr///;
  • EXAMPLE - Greekperl
  • KNOWN PROBLEMS
    • The Logic of :locale
  • HISTORY
  • SEE ALSO

NAME

encoding - allows you to write your script in non-ascii or non-utf8

SYNOPSIS

  use encoding "greek";  # Perl like Greek to you?
  use encoding "euc-jp"; # Jperl!

  # or you can even do this if your shell supports your native encoding

  perl -Mencoding=latin2 -e '...' # Feeling centrally European?
  perl -Mencoding=euc-kr -e '...' # Or Korean?
  # more control

  # A simple euc-cn => utf-8 converter
  use encoding "euc-cn", STDOUT => "utf8";  while(<>){print};

  # "no encoding;" supported (but not scoped!)
  no encoding;

  # an alternate way, Filter
  use encoding "euc-jp", Filter=>1;
  # now you can use kanji identifiers -- in euc-jp!

  # switch on locale -
  # note that this probably means that unless you have a complete control
  # over the environments the application is ever going to be run, you should
  # NOT use the feature of encoding pragma allowing you to write your script
  # in any recognized encoding because changing locale settings will wreck
  # the script; you can of course still use the other features of the pragma.
  use encoding ':locale';

ABSTRACT

Let's start with a bit of history: Perl 5.6.0 introduced Unicode support. You could apply substr() and regexes even to complex CJK characters -- so long as the script was written in UTF-8. But back then, text editors that supported UTF-8 were still rare and many users instead chose to write scripts in legacy encodings, giving up a whole new feature of Perl 5.6.

Rewind to the future: starting from perl 5.8.0 with the encoding pragma, you can write your script in any encoding you like (so long as the Encode module supports it) and still enjoy Unicode support. This pragma achieves that by doing the following:

  • Internally converts all literals (q//,qq//,qr//,qw///, qx//) from the encoding specified to utf8. In Perl 5.8.1 and later, literals in tr/// and DATA pseudo-filehandle are also converted.

  • Changing PerlIO layers of STDIN and STDOUT to the encoding specified.

Literal Conversions

You can write code in EUC-JP as follows:

  my $Rakuda = "\xF1\xD1\xF1\xCC"; # Camel in Kanji
               #<-char-><-char->   # 4 octets
  s/\bCamel\b/$Rakuda/;

And with use encoding "euc-jp" in effect, it is the same thing as the code in UTF-8:

  my $Rakuda = "\x{99F1}\x{99DD}"; # two Unicode Characters
  s/\bCamel\b/$Rakuda/;

PerlIO layers for STD(IN|OUT)

The encoding pragma also modifies the filehandle layers of STDIN and STDOUT to the specified encoding. Therefore,

  use encoding "euc-jp";
  my $message = "Camel is the symbol of perl.\n";
  my $Rakuda = "\xF1\xD1\xF1\xCC"; # Camel in Kanji
  $message =~ s/\bCamel\b/$Rakuda/;
  print $message;

Will print "\xF1\xD1\xF1\xCC is the symbol of perl.\n", not "\x{99F1}\x{99DD} is the symbol of perl.\n".

You can override this by giving extra arguments; see below.

Implicit upgrading for byte strings

By default, if strings operating under byte semantics and strings with Unicode character data are concatenated, the new string will be created by decoding the byte strings as ISO 8859-1 (Latin-1).

The encoding pragma changes this to use the specified encoding instead. For example:

    use encoding 'utf8';
    my $string = chr(20000); # a Unicode string
    utf8::encode($string);   # now it's a UTF-8 encoded byte string
    # concatenate with another Unicode string
    print length($string . chr(20000));

Will print 2, because $string is upgraded as UTF-8. Without use encoding 'utf8';, it will print 4 instead, since $string is three octets when interpreted as Latin-1.

FEATURES THAT REQUIRE 5.8.1

Some of the features offered by this pragma requires perl 5.8.1. Most of these are done by Inaba Hiroto. Any other features and changes are good for 5.8.0.

"NON-EUC" doublebyte encodings

Because perl needs to parse script before applying this pragma, such encodings as Shift_JIS and Big-5 that may contain '\' (BACKSLASH; \x5c) in the second byte fails because the second byte may accidentally escape the quoting character that follows. Perl 5.8.1 or later fixes this problem.

tr//

tr// was overlooked by Perl 5 porters when they released perl 5.8.0 See the section below for details.

DATA pseudo-filehandle

Another feature that was overlooked was DATA.

USAGE

use encoding [ENCNAME] ;

Sets the script encoding to ENCNAME. And unless ${^UNICODE} exists and non-zero, PerlIO layers of STDIN and STDOUT are set to ":encoding(ENCNAME)".

Note that STDERR WILL NOT be changed.

Also note that non-STD file handles remain unaffected. Use use open or binmode to change layers of those.

If no encoding is specified, the environment variable PERL_ENCODING is consulted. If no encoding can be found, the error Unknown encoding 'I<ENCNAME>' will be thrown.

use encoding ENCNAME [ STDIN => ENCNAME_IN ...] ;

You can also individually set encodings of STDIN and STDOUT via the STDIN => ENCNAME form. In this case, you cannot omit the first ENCNAME. STDIN => undef turns the IO transcoding completely off.

When ${^UNICODE} exists and non-zero, these options will completely ignored. ${^UNICODE} is a variable introduced in perl 5.8.1. See the perlrun manpage see ${^UNICODE} in the perlvar manpage and -C in the perlrun manpage for details (perl 5.8.1 and later).

use encoding ENCNAME Filter=>1;

This turns the encoding pragma into a source filter. While the default approach just decodes interpolated literals (in qq() and qr()), this will apply a source filter to the entire source code. See The Filter Option below for details.

no encoding;

Unsets the script encoding. The layers of STDIN, STDOUT are reset to ":raw" (the default unprocessed raw stream of bytes).

The Filter Option

The magic of use encoding is not applied to the names of identifiers. In order to make ${"\x{4eba}"}++ ($human++, where human is a single Han ideograph) work, you still need to write your script in UTF-8 -- or use a source filter. That's what 'Filter=>1' does.

What does this mean? Your source code behaves as if it is written in UTF-8 with 'use utf8' in effect. So even if your editor only supports Shift_JIS, for example, you can still try examples in Chapter 15 of Programming Perl, 3rd Ed.. For instance, you can use UTF-8 identifiers.

This option is significantly slower and (as of this writing) non-ASCII identifiers are not very stable WITHOUT this option and with the source code written in UTF-8.

Filter-related changes at Encode version 1.87

  • The Filter option now sets STDIN and STDOUT like non-filter options. And STDIN=>ENCODING and STDOUT=>ENCODING work like non-filter version.

  • use utf8 is implicitly declared so you no longer have to use utf8 to ${"\x{4eba}"}++.

CAVEATS

NOT SCOPED

The pragma is a per script, not a per block lexical. Only the last use encoding or no encoding matters, and it affects the whole script. However, the <no encoding> pragma is supported and use encoding can appear as many times as you want in a given script. The multiple use of this pragma is discouraged.

By the same reason, the use this pragma inside modules is also discouraged (though not as strongly discouraged as the case above. See below).

If you still have to write a module with this pragma, be very careful of the load order. See the codes below;

  # called module
  package Module_IN_BAR;
  use encoding "bar";
  # stuff in "bar" encoding here
  1;

  # caller script
  use encoding "foo"
  use Module_IN_BAR;
  # surprise! use encoding "bar" is in effect.

The best way to avoid this oddity is to use this pragma RIGHT AFTER other modules are loaded. i.e.

  use Module_IN_BAR;
  use encoding "foo";

DO NOT MIX MULTIPLE ENCODINGS

Notice that only literals (string or regular expression) having only legacy code points are affected: if you mix data like this

        \xDF\x{100}

the data is assumed to be in (Latin 1 and) Unicode, not in your native encoding. In other words, this will match in "greek":

        "\xDF" =~ /\x{3af}/

but this will not

        "\xDF\x{100}" =~ /\x{3af}\x{100}/

since the \xDF (ISO 8859-7 GREEK SMALL LETTER IOTA WITH TONOS) on the left will not be upgraded to \x{3af} (Unicode GREEK SMALL LETTER IOTA WITH TONOS) because of the \x{100} on the left. You should not be mixing your legacy data and Unicode in the same string.

This pragma also affects encoding of the 0x80..0xFF code point range: normally characters in that range are left as eight-bit bytes (unless they are combined with characters with code points 0x100 or larger, in which case all characters need to become UTF-8 encoded), but if the encoding pragma is present, even the 0x80..0xFF range always gets UTF-8 encoded.

After all, the best thing about this pragma is that you don't have to resort to \x{....} just to spell your name in a native encoding. So feel free to put your strings in your encoding in quotes and regexes.

tr/// with ranges

The encoding pragma works by decoding string literals in q//,qq//,qr//,qw///, qx// and so forth. In perl 5.8.0, this does not apply to tr///. Therefore,

  use encoding 'euc-jp';
  #....
  $kana =~ tr/\xA4\xA1-\xA4\xF3/\xA5\xA1-\xA5\xF3/;
  #           -------- -------- -------- --------

Does not work as

  $kana =~ tr/\x{3041}-\x{3093}/\x{30a1}-\x{30f3}/;
Legend of characters above
  utf8     euc-jp   charnames::viacode()
  -----------------------------------------
  \x{3041} \xA4\xA1 HIRAGANA LETTER SMALL A
  \x{3093} \xA4\xF3 HIRAGANA LETTER N
  \x{30a1} \xA5\xA1 KATAKANA LETTER SMALL A
  \x{30f3} \xA5\xF3 KATAKANA LETTER N

This counterintuitive behavior has been fixed in perl 5.8.1.

workaround to tr///;

In perl 5.8.0, you can work around as follows;

  use encoding 'euc-jp';
  #  ....
  eval qq{ \$kana =~ tr/\xA4\xA1-\xA4\xF3/\xA5\xA1-\xA5\xF3/ };

Note the tr// expression is surrounded by qq{}. The idea behind is the same as classic idiom that makes tr/// 'interpolate'.

   tr/$from/$to/;            # wrong!
   eval qq{ tr/$from/$to/ }; # workaround.

Nevertheless, in case of encoding pragma even q// is affected so tr/// not being decoded was obviously against the will of Perl5 Porters so it has been fixed in Perl 5.8.1 or later.

EXAMPLE - Greekperl

    use encoding "iso 8859-7";

    # \xDF in ISO 8859-7 (Greek) is \x{3af} in Unicode.

    $a = "\xDF";
    $b = "\x{100}";

    printf "%#x\n", ord($a); # will print 0x3af, not 0xdf

    $c = $a . $b;

    # $c will be "\x{3af}\x{100}", not "\x{df}\x{100}".

    # chr() is affected, and ...

    print "mega\n"  if ord(chr(0xdf)) == 0x3af;

    # ... ord() is affected by the encoding pragma ...

    print "tera\n" if ord(pack("C", 0xdf)) == 0x3af;

    # ... as are eq and cmp ...

    print "peta\n" if "\x{3af}" eq  pack("C", 0xdf);
    print "exa\n"  if "\x{3af}" cmp pack("C", 0xdf) == 0;

    # ... but pack/unpack C are not affected, in case you still
    # want to go back to your native encoding

    print "zetta\n" if unpack("C", (pack("C", 0xdf))) == 0xdf;

KNOWN PROBLEMS

literals in regex that are longer than 127 bytes

For native multibyte encodings (either fixed or variable length), the current implementation of the regular expressions may introduce recoding errors for regular expression literals longer than 127 bytes.

EBCDIC

The encoding pragma is not supported on EBCDIC platforms. (Porters who are willing and able to remove this limitation are welcome.)

format

This pragma doesn't work well with format because PerlIO does not get along very well with it. When format contains non-ascii characters it prints funny or gets "wide character warnings". To understand it, try the code below.

  # Save this one in utf8
  # replace *non-ascii* with a non-ascii string
  my $camel;
  format STDOUT =
  *non-ascii*@>>>>>>>
  $camel
  .
  $camel = "*non-ascii*";
  binmode(STDOUT=>':encoding(utf8)'); # bang!
  write;              # funny
  print $camel, "\n"; # fine

Without binmode this happens to work but without binmode, print() fails instead of write().

At any rate, the very use of format is questionable when it comes to unicode characters since you have to consider such things as character width (i.e. double-width for ideographs) and directions (i.e. BIDI for Arabic and Hebrew).

The Logic of :locale

The logic of :locale is as follows:

  1. If the platform supports the langinfo(CODESET) interface, the codeset returned is used as the default encoding for the open pragma.

  2. If 1. didn't work but we are under the locale pragma, the environment variables LC_ALL and LANG (in that order) are matched for encodings (the part after ., if any), and if any found, that is used as the default encoding for the open pragma.

  3. If 1. and 2. didn't work, the environment variables LC_ALL and LANG (in that order) are matched for anything looking like UTF-8, and if any found, :utf8 is used as the default encoding for the open pragma.

If your locale environment variables (LC_ALL, LC_CTYPE, LANG) contain the strings 'UTF-8' or 'UTF8' (case-insensitive matching), the default encoding of your STDIN, STDOUT, and STDERR, and of any subsequent file open, is UTF-8.

HISTORY

This pragma first appeared in Perl 5.8.0. For features that require 5.8.1 and better, see above.

The :locale subpragma was implemented in 2.01, or Perl 5.8.6.

SEE ALSO

the perlunicode manpage, the Encode manpage, the open manpage, the Filter::Util::Call manpage,

Ch. 15 of Programming Perl (3rd Edition) by Larry Wall, Tom Christiansen, Jon Orwant; O'Reilly & Associates; ISBN 0-596-00027-8


fields - compile-time class fields

  • SEE ALSO

NAME

fields - compile-time class fields

SYNOPSIS

    {
        package Foo;
        use fields qw(foo bar _Foo_private);
        sub new {
            my Foo $self = shift;
            unless (ref $self) {
                $self = fields::new($self);
                $self->{_Foo_private} = "this is Foo's secret";
            }
            $self->{foo} = 10;
            $self->{bar} = 20;
            return $self;
        }
    }

    my $var = Foo->new;
    $var->{foo} = 42;

    # this will generate an error
    $var->{zap} = 42;

    # subclassing
    {
        package Bar;
        use base 'Foo';
        use fields qw(baz _Bar_private);        # not shared with Foo
        sub new {
            my $class = shift;
            my $self = fields::new($class);
            $self->SUPER::new();                # init base fields
            $self->{baz} = 10;                  # init own fields
            $self->{_Bar_private} = "this is Bar's secret";
            return $self;
        }
    }

DESCRIPTION

The fields pragma enables compile-time verified class fields.

NOTE: The current implementation keeps the declared fields in the %FIELDS hash of the calling package, but this may change in future versions. Do not update the %FIELDS hash directly, because it must be created at compile-time for it to be fully useful, as is done by this pragma.

Only valid for perl before 5.9.0:

If a typed lexical variable holding a reference is used to access a hash element and a package with the same name as the type has declared class fields using this pragma, then the operation is turned into an array access at compile time.

The related base pragma will combine fields from base classes and any fields declared using the fields pragma. This enables field inheritance to work properly.

Field names that start with an underscore character are made private to the class and are not visible to subclasses. Inherited fields can be overridden but will generate a warning if used together with the -w switch.

Only valid for perls before 5.9.0:

The effect of all this is that you can have objects with named fields which are as compact and as fast arrays to access. This only works as long as the objects are accessed through properly typed variables. If the objects are not typed, access is only checked at run time.

The following functions are supported:

new

perl before 5.9.0: fields::new() creates and blesses a pseudo-hash comprised of the fields declared using the fields pragma into the specified class.

perl 5.9.0 and higher: fields::new() creates and blesses a restricted-hash comprised of the fields declared using the fields pragma into the specified class.

This function is usable with or without pseudo-hashes. It is the recommended way to construct a fields-based object.

This makes it possible to write a constructor like this:

    package Critter::Sounds;
    use fields qw(cat dog bird);

    sub new {
        my $self = shift;
        $self = fields::new($self) unless ref $self;
        $self->{cat} = 'meow';                          # scalar element
        @$self{'dog','bird'} = ('bark','tweet');        # slice
        return $self;
    }
phash

before perl 5.9.0:

fields::phash() can be used to create and initialize a plain (unblessed) pseudo-hash. This function should always be used instead of creating pseudo-hashes directly.

If the first argument is a reference to an array, the pseudo-hash will be created with keys from that array. If a second argument is supplied, it must also be a reference to an array whose elements will be used as the values. If the second array contains less elements than the first, the trailing elements of the pseudo-hash will not be initialized. This makes it particularly useful for creating a pseudo-hash from subroutine arguments:

    sub dogtag {
       my $tag = fields::phash([qw(name rank ser_num)], [@_]);
    }

fields::phash() also accepts a list of key-value pairs that will be used to construct the pseudo hash. Examples:

    my $tag = fields::phash(name => "Joe",
                            rank => "captain",
                            ser_num => 42);

    my $pseudohash = fields::phash(%args);

perl 5.9.0 and higher:

Pseudo-hashes have been removed from Perl as of 5.10. Consider using restricted hashes or fields::new() instead. Using fields::phash() will cause an error.

SEE ALSO

the base manpage


filetest - Perl pragma to control the filetest permission operators

    • subpragma access

NAME

filetest - Perl pragma to control the filetest permission operators

SYNOPSIS

    $can_perhaps_read = -r "file";      # use the mode bits
    {
        use filetest 'access';          # intuit harder
        $can_really_read = -r "file";
    }
    $can_perhaps_read = -r "file";      # use the mode bits again

DESCRIPTION

This pragma tells the compiler to change the behaviour of the filetest permission operators, -r -w -x -R -W -X (see the perlfunc manpage).

The default behaviour is to use the mode bits as returned by the stat() family of calls. This, however, may not be the right thing to do if for example various ACL (access control lists) schemes are in use. For such environments, use filetest may help the permission operators to return results more consistent with other tools.

Each "use filetest" or "no filetest" affects statements to the end of the enclosing block.

There may be a slight performance decrease in the filetests when use filetest is in effect, because in some systems the extended functionality needs to be emulated.

NOTE: using the file tests for security purposes is a lost cause from the start: there is a window open for race conditions (who is to say that the permissions will not change between the test and the real operation?). Therefore if you are serious about security, just try the real operation and test for its success - think in terms of atomic operations.

subpragma access

Currently only one subpragma, access is implemented. It enables (or disables) the use of access() or similar system calls. This extended filetest functionality is used only when the argument of the operators is a filename, not when it is a filehandle.


if - C<use> a Perl module if a condition holds

  • BUGS
  • AUTHOR

NAME

if - use a Perl module if a condition holds

SYNOPSIS

  use if CONDITION, MODULE => ARGUMENTS;

DESCRIPTION

The construct

  use if CONDITION, MODULE => ARGUMENTS;

has no effect unless CONDITION is true. In this case the effect is the same as of

  use MODULE ARGUMENTS;

Above => provides necessary quoting of MODULE. If not used (e.g., no ARGUMENTS to give), you'd better quote MODULE yourselves.

BUGS

The current implementation does not allow specification of the required version of the module.

AUTHOR

Ilya Zakharevich mailto:perl-module-if@ilyaz.org.


integer - Perl pragma to use integer arithmetic instead of floating point

NAME

integer - Perl pragma to use integer arithmetic instead of floating point

SYNOPSIS

    use integer;
    $x = 10/3;
    # $x is now 3, not 3.33333333333333333

DESCRIPTION

This tells the compiler to use integer operations from here to the end of the enclosing BLOCK. On many machines, this doesn't matter a great deal for most computations, but on those without floating point hardware, it can make a big difference in performance.

Note that this only affects how most of the arithmetic and relational operators handle their operands and results, and not how all numbers everywhere are treated. Specifically, use integer; has the effect that before computing the results of the arithmetic operators (+, -, *, /, %, +=, -=, *=, /=, %=, and unary minus), the comparison operators (<, <=, >, >=, ==, !=, <=>), and the bitwise operators (|, &, ^, <<, >>, |=, &=, ^=, <<=, >>=), the operands have their fractional portions truncated (or floored), and the result will have its fractional portion truncated as well. In addition, the range of operands and results is restricted to that of familiar two's complement integers, i.e., -(2**31) .. (2**31-1) on 32-bit architectures, and -(2**63) .. (2**63-1) on 64-bit architectures. For example, this code

    use integer;
    $x = 5.8;
    $y = 2.5;
    $z = 2.7;
    $a = 2**31 - 1;  # Largest positive integer on 32-bit machines
    $, = ", ";
    print $x, -$x, $x + $y, $x - $y, $x / $y, $x * $y, $y == $z, $a, $a + 1;

will print: 5.8, -5, 7, 3, 2, 10, 1, 2147483647, -2147483648

Note that $x is still printed as having its true non-integer value of 5.8 since it wasn't operated on. And note too the wrap-around from the largest positive integer to the largest negative one. Also, arguments passed to functions and the values returned by them are not affected by use integer;. E.g.,

    srand(1.5);
    $, = ", ";
    print sin(.5), cos(.5), atan2(1,2), sqrt(2), rand(10);

will give the same result with or without use integer; The power operator ** is also not affected, so that 2 ** .5 is always the square root of 2. Now, it so happens that the pre- and post- increment and decrement operators, ++ and --, are not affected by use integer; either. Some may rightly consider this to be a bug -- but at least it's a long-standing one.

Finally, use integer; also has an additional affect on the bitwise operators. Normally, the operands and results are treated as unsigned integers, but with use integer; the operands and results are signed. This means, among other things, that ~0 is -1, and -2 & -5 is -6.

Internally, native integer arithmetic (as provided by your C compiler) is used. This means that Perl's own semantics for arithmetic operations may not be preserved. One common source of trouble is the modulus of negative numbers, which Perl does one way, but your hardware may do another.

    % perl -le 'print (4 % -3)'
    -2
    % perl -Minteger -le 'print (4 % -3)'
    1

See Pragmatic Modules in the perlmodlib manpage, Integer Arithmetic in the perlop manpage


less - perl pragma to request less of something from the compiler

NAME

less - perl pragma to request less of something from the compiler

SYNOPSIS

    use less;  # unimplemented

DESCRIPTION

Currently unimplemented, this may someday be a compiler directive to make certain trade-offs, such as perhaps

    use less 'memory';
    use less 'CPU';
    use less 'fat';


lib - manipulate @INC at compile time

    • Adding directories to @INC
    • Deleting directories from @INC
    • Restoring original @INC
  • CAVEATS
  • NOTES
  • SEE ALSO
  • AUTHOR

NAME

lib - manipulate @INC at compile time

SYNOPSIS

    use lib LIST;

    no lib LIST;

DESCRIPTION

This is a small simple module which simplifies the manipulation of @INC at compile time.

It is typically used to add extra directories to perl's search path so that later use or require statements will find modules which are not located on perl's default search path.

Adding directories to @INC

The parameters to use lib are added to the start of the perl search path. Saying

    use lib LIST;

is almost the same as saying

    BEGIN { unshift(@INC, LIST) }

For each directory in LIST (called $dir here) the lib module also checks to see if a directory called $dir/$archname/auto exists. If so the $dir/$archname directory is assumed to be a corresponding architecture specific directory and is added to @INC in front of $dir.

To avoid memory leaks, all trailing duplicate entries in @INC are removed.

Deleting directories from @INC

You should normally only add directories to @INC. If you need to delete directories from @INC take care to only delete those which you added yourself or which you are certain are not needed by other modules in your script. Other modules may have added directories which they need for correct operation.

The no lib statement deletes all instances of each named directory from @INC.

For each directory in LIST (called $dir here) the lib module also checks to see if a directory called $dir/$archname/auto exists. If so the $dir/$archname directory is assumed to be a corresponding architecture specific directory and is also deleted from @INC.

Restoring original @INC

When the lib module is first loaded it records the current value of @INC in an array @lib::ORIG_INC. To restore @INC to that value you can say

    @INC = @lib::ORIG_INC;

CAVEATS

In order to keep lib.pm small and simple, it only works with Unix filepaths. This doesn't mean it only works on Unix, but non-Unix users must first translate their file paths to Unix conventions.

    # VMS users wanting to put [.stuff.moo] into
    # their @INC would write
    use lib 'stuff/moo';

NOTES

In the future, this module will likely use File::Spec for determining paths, as it does now for Mac OS (where Unix-style or Mac-style paths work, and Unix-style paths are converted properly to Mac-style paths before being added to @INC).

SEE ALSO

FindBin - optional module which deals with paths relative to the source file.

AUTHOR

Tim Bunce, 2nd June 1995.


locale - Perl pragma to use and avoid POSIX locales for built-in operations

NAME

locale - Perl pragma to use and avoid POSIX locales for built-in operations

SYNOPSIS

    @x = sort @y;       # ASCII sorting order
    {
        use locale;
        @x = sort @y;   # Locale-defined sorting order
    }
    @x = sort @y;       # ASCII sorting order again

DESCRIPTION

This pragma tells the compiler to enable (or disable) the use of POSIX locales for built-in operations (LC_CTYPE for regular expressions, and LC_COLLATE for string comparison). Each "use locale" or "no locale" affects statements to the end of the enclosing BLOCK.

See the perllocale manpage for more detailed information on how Perl supports locales.


open - perl pragma to set default PerlIO layers for input and output

  • NONPERLIO FUNCTIONALITY
  • IMPLEMENTATION DETAILS
  • SEE ALSO

NAME

open - perl pragma to set default PerlIO layers for input and output

SYNOPSIS

    use open IN  => ":crlf", OUT => ":bytes";
    use open OUT => ':utf8';
    use open IO  => ":encoding(iso-8859-7)";

    use open IO  => ':locale';

    use open ':utf8';
    use open ':locale';
    use open ':encoding(iso-8859-7)';

    use open ':std';

DESCRIPTION

Full-fledged support for I/O layers is now implemented provided Perl is configured to use PerlIO as its IO system (which is now the default).

The open pragma serves as one of the interfaces to declare default "layers" (also known as "disciplines") for all I/O. Any two-argument open(), readpipe() (aka qx//) and similar operators found within the lexical scope of this pragma will use the declared defaults. Even three-argument opens may be affected by this pragma when they don't specify IO layers in MODE.

With the IN subpragma you can declare the default layers of input streams, and with the OUT subpragma you can declare the default layers of output streams. With the IO subpragma you can control both input and output streams simultaneously.

If you have a legacy encoding, you can use the :encoding(...) tag.

If you want to set your encoding layers based on your locale environment variables, you can use the :locale tag. For example:

    $ENV{LANG} = 'ru_RU.KOI8-R';
    # the :locale will probe the locale environment variables like LANG
    use open OUT => ':locale';
    open(O, ">koi8");
    print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
    close O;
    open(I, "<koi8");
    printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
    close I;

These are equivalent

    use open ':utf8';
    use open IO => ':utf8';

as are these

    use open ':locale';
    use open IO => ':locale';

and these

    use open ':encoding(iso-8859-7)';
    use open IO => ':encoding(iso-8859-7)';

The matching of encoding names is loose: case does not matter, and many encodings have several aliases. See the Encode::Supported manpage for details and the list of supported locales.

Note that :utf8 PerlIO layer must always be specified exactly like that, it is not subject to the loose matching of encoding names.

When open() is given an explicit list of layers (with the three-arg syntax), they override the list declared using this pragma.

The :std subpragma on its own has no effect, but if combined with the :utf8 or :encoding subpragmas, it converts the standard filehandles (STDIN, STDOUT, STDERR) to comply with encoding selected for input/output handles. For example, if both input and out are chosen to be :utf8, a :std will mean that STDIN, STDOUT, and STDERR are also in :utf8. On the other hand, if only output is chosen to be in :encoding(koi8r), a :std will cause only the STDOUT and STDERR to be in koi8r. The :locale subpragma implicitly turns on :std.

The logic of :locale is described in full in the encoding manpage, but in short it is first trying nl_langinfo(CODESET) and then guessing from the LC_ALL and LANG locale environment variables.

Directory handles may also support PerlIO layers in the future.

NONPERLIO FUNCTIONALITY

If Perl is not built to use PerlIO as its IO system then only the two pseudo-layers :bytes and :crlf are available.

The :bytes layer corresponds to "binary mode" and the :crlf layer corresponds to "text mode" on platforms that distinguish between the two modes when opening files (which is many DOS-like platforms, including Windows). These two layers are no-ops on platforms where binmode() is a no-op, but perform their functions everywhere if PerlIO is enabled.

IMPLEMENTATION DETAILS

There is a class method in PerlIO::Layer find which is implemented as XS code. It is called by import to validate the layers:

   PerlIO::Layer::->find("perlio")

The return value (if defined) is a Perl object, of class PerlIO::Layer which is created by the C code in perlio.c. As yet there is nothing useful you can do with the object at the perl level.

SEE ALSO

binmode in the perlfunc manpage, open in the perlfunc manpage, the perlunicode manpage, the PerlIO manpage, the encoding manpage


ops - Perl pragma to restrict unsafe operations when compiling

  • SEE ALSO

NAME

ops - Perl pragma to restrict unsafe operations when compiling

SYNOPSIS

  perl -Mops=:default ...    # only allow reasonably safe operations
  perl -M-ops=system ...     # disable the 'system' opcode

DESCRIPTION

Since the ops pragma currently has an irreversible global effect, it is only of significant practical use with the -M option on the command line.

See the the Opcode manpage module for information about opcodes, optags, opmasks and important information about safety.

SEE ALSO

Opcode(3), Safe(3), perlrun(3)


overload - Package for overloading Perl operations

    • Declaration of overloaded functions
    • Calling Conventions for Binary Operations
    • Calling Conventions for Unary Operations
    • Calling Conventions for Mutators
    • Overloadable Operations
    • Inheritance and overloading
  • SPECIAL SYMBOLS FOR use overload
    • Last Resort
    • Fallback
    • Copy Constructor
  • MAGIC AUTOGENERATION
  • Losing overloading
  • Run-time Overloading
  • Public functions
  • Overloading constants
  • IMPLEMENTATION
  • Metaphor clash
  • Cookbook
    • Two-face scalars
    • Two-face references
    • Symbolic calculator
    • Really symbolic calculator
  • AUTHOR
  • DIAGNOSTICS
  • BUGS

NAME

overload - Package for overloading Perl operations

SYNOPSIS

    package SomeThing;

    use overload
        '+' => \&myadd,
        '-' => \&mysub;
        # etc
    ...

    package main;
    $a = new SomeThing 57;
    $b=5+$a;
    ...
    if (overload::Overloaded $b) {...}
    ...
    $strval = overload::StrVal $b;

DESCRIPTION

Declaration of overloaded functions

The compilation directive

    package Number;
    use overload
        "+" => \&add,
        "*=" => "muas";

declares function Number::add() for addition, and method muas() in the "class" Number (or one of its base classes) for the assignment form *= of multiplication.

Arguments of this directive come in (key, value) pairs. Legal values are values legal inside a &{ ... } call, so the name of a subroutine, a reference to a subroutine, or an anonymous subroutine will all work. Note that values specified as strings are interpreted as methods, not subroutines. Legal keys are listed below.

The subroutine add will be called to execute $a+$b if $a is a reference to an object blessed into the package Number, or if $a is not an object from a package with defined mathemagic addition, but $b is a reference to a Number. It can also be called in other situations, like $a+=7, or $a++. See MAGIC AUTOGENERATION. (Mathemagical methods refer to methods triggered by an overloaded mathematical operator.)

Since overloading respects inheritance via the @ISA hierarchy, the above declaration would also trigger overloading of + and *= in all the packages which inherit from Number.

Calling Conventions for Binary Operations

The functions specified in the use overload ... directive are called with three (in one particular case with four, see Last Resort) arguments. If the corresponding operation is binary, then the first two arguments are the two arguments of the operation. However, due to general object calling conventions, the first argument should always be an object in the package, so in the situation of 7+$a, the order of the arguments is interchanged. It probably does not matter when implementing the addition method, but whether the arguments are reversed is vital to the subtraction method. The method can query this information by examining the third argument, which can take three different values:

FALSE

the order of arguments is as in the current operation.

TRUE

the arguments are reversed.

undef

the current operation is an assignment variant (as in $a+=7), but the usual function is called instead. This additional information can be used to generate some optimizations. Compare Calling Conventions for Mutators.

Calling Conventions for Unary Operations

Unary operation are considered binary operations with the second argument being undef. Thus the functions that overloads {"++"} is called with arguments ($a,undef,'') when $a++ is executed.

Calling Conventions for Mutators

Two types of mutators have different calling conventions:

++ and --

The routines which implement these operators are expected to actually mutate their arguments. So, assuming that $obj is a reference to a number,

  sub incr { my $n = $ {$_[0]}; ++$n; $_[0] = bless \$n}

is an appropriate implementation of overloaded ++. Note that

  sub incr { ++$ {$_[0]} ; shift }

is OK if used with preincrement and with postincrement. (In the case of postincrement a copying will be performed, see Copy Constructor.)

x= and other assignment versions

There is nothing special about these methods. They may change the value of their arguments, and may leave it as is. The result is going to be assigned to the value in the left-hand-side if different from this value.

This allows for the same method to be used as overloaded += and +. Note that this is allowed, but not recommended, since by the semantic of Fallback Perl will call the method for + anyway, if += is not overloaded.

Warning. Due to the presence of assignment versions of operations, routines which may be called in assignment context may create self-referential structures. Currently Perl will not free self-referential structures until cycles are explicitly broken. You may get problems when traversing your structures too.

Say,

  use overload '+' => sub { bless [ \$_[0], \$_[1] ] };

is asking for trouble, since for code $obj += $foo the subroutine is called as $obj = add($obj, $foo, undef), or $obj = [\$obj, \$foo]. If using such a subroutine is an important optimization, one can overload += explicitly by a non-"optimized" version, or switch to non-optimized version if not defined $_[2] (see Calling Conventions for Binary Operations).

Even if no explicit assignment-variants of operators are present in the script, they may be generated by the optimizer. Say, ",$obj," or ',' . $obj . ',' may be both optimized to

  my $tmp = ',' . $obj;    $tmp .= ',';

Overloadable Operations

The following symbols can be specified in use overload directive:

  • Arithmetic operations
        "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
    "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",

    For these operations a substituted non-assignment variant can be called if the assignment variant is not available. Methods for operations +, -, +=, and -= can be called to automatically generate increment and decrement methods. The operation - can be used to autogenerate missing methods for unary minus or abs.

    See MAGIC AUTOGENERATION, Calling Conventions for Mutators and Calling Conventions for Binary Operations) for details of these substitutions.

  • Comparison operations
        "<",  "<=", ">",  ">=", "==", "!=", "<=>",
    "lt", "le", "gt", "ge", "eq", "ne", "cmp",

    If the corresponding "spaceship" variant is available, it can be used to substitute for the missing operation. During sorting arrays, cmp is used to compare values subject to use overload.

  • Bit operations
        "&", "^", "|", "neg", "!", "~",

    neg stands for unary minus. If the method for neg is not specified, it can be autogenerated using the method for subtraction. If the method for ! is not specified, it can be autogenerated using the methods for bool, or "", or 0+.

  • Increment and decrement
        "++", "--",

    If undefined, addition and subtraction methods can be used instead. These operations are called both in prefix and postfix form.

  • Transcendental functions
        "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", "int"

    If abs is unavailable, it can be autogenerated using methods for "<" or "<=>" combined with either unary minus or subtraction.

    Note that traditionally the Perl function int rounds to 0, thus for floating-point-like types one should follow the same semantic. If int is unavailable, it can be autogenerated using the overloading of 0+.

  • Boolean, string and numeric conversion
        'bool', '""', '0+',

    If one or two of these operations are not overloaded, the remaining ones can be used instead. bool is used in the flow control operators (like while) and for the ternary ?: operation. These functions can return any arbitrary Perl value. If the corresponding operation for this value is overloaded too, that operation will be called again with this value.

    As a special case if the overload returns the object itself then it will be used directly. An overloaded conversion returning the object is probably a bug, because you're likely to get something that looks like YourPackage=HASH(0x8172b34).

  • Iteration
        "<>"

    If not overloaded, the argument will be converted to a filehandle or glob (which may require a stringification). The same overloading happens both for the read-filehandle syntax <$var> and globbing syntax <${var}>.

    BUGS Even in list context, the iterator is currently called only once and with scalar context.

  • Dereferencing
        '${}', '@{}', '%{}', '&{}', '*{}'.

    If not overloaded, the argument will be dereferenced as is, thus should be of correct type. These functions should return a reference of correct type, or another object with overloaded dereferencing.

    As a special case if the overload returns the object itself then it will be used directly (provided it is the correct type).

    The dereference operators must be specified explicitly they will not be passed to "nomethod".

  • Special
        "nomethod", "fallback", "=",

    see SPECIAL SYMBOLS FOR use overload.

See Fallback for an explanation of when a missing method can be autogenerated.

A computer-readable form of the above table is available in the hash %overload::ops, with values being space-separated lists of names:

 with_assign      => '+ - * / % ** << >> x .',
 assign           => '+= -= *= /= %= **= <<= >>= x= .=',
 num_comparison   => '< <= > >= == !=',
 '3way_comparison'=> '<=> cmp',
 str_comparison   => 'lt le gt ge eq ne',
 binary           => '& | ^',
 unary            => 'neg ! ~',
 mutators         => '++ --',
 func             => 'atan2 cos sin exp abs log sqrt',
 conversion       => 'bool "" 0+',
 iterators        => '<>',
 dereferencing    => '${} @{} %{} &{} *{}',
 special          => 'nomethod fallback ='

Inheritance and overloading

Inheritance interacts with overloading in two ways.

Strings as values of use overload directive

If value in

  use overload key => value;

is a string, it is interpreted as a method name.

Overloading of an operation is inherited by derived classes

Any class derived from an overloaded class is also overloaded. The set of overloaded methods is the union of overloaded methods of all the ancestors. If some method is overloaded in several ancestor, then which description will be used is decided by the usual inheritance rules:

If A inherits from B and C (in this order), B overloads + with \&D::plus_sub, and C overloads + by "plus_meth", then the subroutine D::plus_sub will be called to implement operation + for an object in package A.

Note that since the value of the fallback key is not a subroutine, its inheritance is not governed by the above rules. In the current implementation, the value of fallback in the first overloaded ancestor is used, but this is accidental and subject to change.

SPECIAL SYMBOLS FOR use overload

Three keys are recognized by Perl that are not covered by the above description.

Last Resort

"nomethod" should be followed by a reference to a function of four parameters. If defined, it is called when the overloading mechanism cannot find a method for some operation. The first three arguments of this function coincide with the arguments for the corresponding method if it were found, the fourth argument is the symbol corresponding to the missing method. If several methods are tried, the last one is used. Say, 1-$a can be equivalent to

        &nomethodMethod($a,1,1,"-")

if the pair "nomethod" => "nomethodMethod" was specified in the use overload directive.

The "nomethod" mechanism is not used for the dereference operators ( ${} @{} %{} &{} *{} ).

If some operation cannot be resolved, and there is no function assigned to "nomethod", then an exception will be raised via die()-- unless "fallback" was specified as a key in use overload directive.

Fallback

The key "fallback" governs what to do if a method for a particular operation is not found. Three different cases are possible depending on the value of "fallback":

  • undef

    Perl tries to use a substituted method (see MAGIC AUTOGENERATION). If this fails, it then tries to calls "nomethod" value; if missing, an exception will be raised.

  • TRUE

    The same as for the undef value, but no exception is raised. Instead, it silently reverts to what it would have done were there no use overload present.

  • defined, but FALSE

    No autogeneration is tried. Perl tries to call "nomethod" value, and if this is missing, raises an exception.

Note. "fallback" inheritance via @ISA is not carved in stone yet, see Inheritance and overloading.

Copy Constructor

The value for "=" is a reference to a function with three arguments, i.e., it looks like the other values in use overload. However, it does not overload the Perl assignment operator. This would go against Camel hair.

This operation is called in the situations when a mutator is applied to a reference that shares its object with some other reference, such as

        $a=$b;
        ++$a;

To make this change $a and not change $b, a copy of $$a is made, and $a is assigned a reference to this new object. This operation is done during execution of the ++$a, and not during the assignment, (so before the increment $$a coincides with $$b). This is only done if ++ is expressed via a method for '++' or '+=' (or nomethod). Note that if this operation is expressed via '+' a nonmutator, i.e., as in

        $a=$b;
        $a=$a+1;

then $a does not reference a new copy of $$a, since $$a does not appear as lvalue when the above code is executed.

If the copy constructor is required during the execution of some mutator, but a method for '=' was not specified, it can be autogenerated as a string copy if the object is a plain scalar.

Example

The actually executed code for

        $a=$b;
        Something else which does not modify $a or $b....
        ++$a;

may be

        $a=$b;
        Something else which does not modify $a or $b....
        $a = $a->clone(undef,"");
        $a->incr(undef,"");

if $b was mathemagical, and '++' was overloaded with \&incr, '=' was overloaded with \&clone.

Same behaviour is triggered by $b = $a++, which is consider a synonym for $b = $a; ++$a.

MAGIC AUTOGENERATION

If a method for an operation is not found, and the value for "fallback" is TRUE or undefined, Perl tries to autogenerate a substitute method for the missing operation based on the defined operations. Autogenerated method substitutions are possible for the following operations:

Assignment forms of arithmetic operations

$a+=$b can use the method for "+" if the method for "+=" is not defined.

Conversion operations

String, numeric, and boolean conversion are calculated in terms of one another if not all of them are defined.

Increment and decrement

The ++$a operation can be expressed in terms of $a+=1 or $a+1, and $a-- in terms of $a-=1 and $a-1.

abs($a)

can be expressed in terms of $a<0 and -$a (or 0-$a).

Unary minus

can be expressed in terms of subtraction.

Negation

! and not can be expressed in terms of boolean conversion, or string or numerical conversion.

Concatenation

can be expressed in terms of string conversion.

Comparison operations

can be expressed in terms of its "spaceship" counterpart: either <=> or cmp:

    <, >, <=, >=, ==, !=        in terms of <=>
    lt, gt, le, ge, eq, ne      in terms of cmp
Iterator
    <>                          in terms of builtin operations
Dereferencing
    ${} @{} %{} &{} *{}         in terms of builtin operations
Copy operator

can be expressed in terms of an assignment to the dereferenced value, if this value is a scalar and not a reference.

Losing overloading

The restriction for the comparison operation is that even if, for example, `cmp' should return a blessed reference, the autogenerated `lt' function will produce only a standard logical value based on the numerical value of the result of `cmp'. In particular, a working numeric conversion is needed in this case (possibly expressed in terms of other conversions).

Similarly, .= and x= operators lose their mathemagical properties if the string conversion substitution is applied.

When you chop() a mathemagical object it is promoted to a string and its mathemagical properties are lost. The same can happen with other operations as well.

Run-time Overloading

Since all use directives are executed at compile-time, the only way to change overloading during run-time is to

    eval 'use overload "+" => \&addmethod';

You can also use

    eval 'no overload "+", "--", "<="';

though the use of these constructs during run-time is questionable.

Public functions

Package overload.pm provides the following public functions:

overload::StrVal(arg)

Gives string value of arg as in absence of stringify overloading. If you are using this to get the address of a reference (useful for checking if two references point to the same thing) then you may be better off using Scalar::Util::refaddr(), which is faster.

overload::Overloaded(arg)

Returns true if arg is subject to overloading of some operations.

overload::Method(obj,op)

Returns undef or a reference to the method that implements op.

Overloading constants

For some applications, the Perl parser mangles constants too much. It is possible to hook into this process via overload::constant() and overload::remove_constant() functions.

These functions take a hash as an argument. The recognized keys of this hash are:

integer

to overload integer constants,

float

to overload floating point constants,

binary

to overload octal and hexadecimal constants,

q

to overload q-quoted strings, constant pieces of qq- and qx-quoted strings and here-documents,

qr

to overload constant pieces of regular expressions.

The corresponding values are references to functions which take three arguments: the first one is the initial string form of the constant, the second one is how Perl interprets this constant, the third one is how the constant is used. Note that the initial string form does not contain string delimiters, and has backslashes in backslash-delimiter combinations stripped (thus the value of delimiter is not relevant for processing of this string). The return value of this function is how this constant is going to be interpreted by Perl. The third argument is undefined unless for overloaded q- and qr- constants, it is q in single-quote context (comes from strings, regular expressions, and single-quote HERE documents), it is tr for arguments of tr/y operators, it is s for right-hand side of s-operator, and it is qq otherwise.

Since an expression "ab$cd,," is just a shortcut for 'ab' . $cd . ',,', it is expected that overloaded constant strings are equipped with reasonable overloaded catenation operator, otherwise absurd results will result. Similarly, negative numbers are considered as negations of positive constants.

Note that it is probably meaningless to call the functions overload::constant() and overload::remove_constant() from anywhere but import() and unimport() methods. From these methods they may be called as

        sub import {
          shift;
          return unless @_;
          die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
          overload::constant integer => sub {Math::BigInt->new(shift)};
        }

BUGS Currently overloaded-ness of constants does not propagate into eval '...'.

IMPLEMENTATION

What follows is subject to change RSN.

The table of methods for all operations is cached in magic for the symbol table hash for the package. The cache is invalidated during processing of use overload, no overload, new function definitions, and changes in @ISA. However, this invalidation remains unprocessed until the next blessing into the package. Hence if you want to change overloading structure dynamically, you'll need an additional (fake) blessing to update the table.

(Every SVish thing has a magic queue, and magic is an entry in that queue. This is how a single variable may participate in multiple forms of magic simultaneously. For instance, environment variables regularly have two forms at once: their %ENV magic and their taint magic. However, the magic which implements overloading is applied to the stashes, which are rarely used directly, thus should not slow down Perl.)

If an object belongs to a package using overload, it carries a special flag. Thus the only speed penalty during arithmetic operations without overloading is the checking of this flag.

In fact, if use overload is not present, there is almost no overhead for overloadable operations, so most programs should not suffer measurable performance penalties. A considerable effort was made to minimize the overhead when overload is used in some package, but the arguments in question do not belong to packages using overload. When in doubt, test your speed with use overload and without it. So far there have been no reports of substantial speed degradation if Perl is compiled with optimization turned on.

There is no size penalty for data if overload is not used. The only size penalty if overload is used in some package is that all the packages acquire a magic during the next blessing into the package. This magic is three-words-long for packages without overloading, and carries the cache table if the package is overloaded.

Copying ($a=$b) is shallow; however, a one-level-deep copying is carried out before any operation that can imply an assignment to the object $a (or $b) refers to, like $a++. You can override this behavior by defining your own copy constructor (see Copy Constructor).

It is expected that arguments to methods that are not explicitly supposed to be changed are constant (but this is not enforced).

Metaphor clash

One may wonder why the semantic of overloaded = is so counter intuitive. If it looks counter intuitive to you, you are subject to a metaphor clash.

Here is a Perl object metaphor:

object is a reference to blessed data

and an arithmetic metaphor:

object is a thing by itself.

The main problem of overloading = is the fact that these metaphors imply different actions on the assignment $a = $b if $a and $b are objects. Perl-think implies that $a becomes a reference to whatever $b was referencing. Arithmetic-think implies that the value of "object" $a is changed to become the value of the object $b, preserving the fact that $a and $b are separate entities.

The difference is not relevant in the absence of mutators. After a Perl-way assignment an operation which mutates the data referenced by $a would change the data referenced by $b too. Effectively, after $a = $b values of $a and $b become indistinguishable.

On the other hand, anyone who has used algebraic notation knows the expressive power of the arithmetic metaphor. Overloading works hard to enable this metaphor while preserving the Perlian way as far as possible. Since it is not possible to freely mix two contradicting metaphors, overloading allows the arithmetic way to write things as far as all the mutators are called via overloaded access only. The way it is done is described in Copy Constructor.

If some mutator methods are directly applied to the overloaded values, one may need to explicitly unlink other values which references the same value:

    $a = new Data 23;
    ...
    $b = $a;            # $b is "linked" to $a
    ...
    $a = $a->clone;     # Unlink $b from $a
    $a->increment_by(4);

Note that overloaded access makes this transparent:

    $a = new Data 23;
    $b = $a;            # $b is "linked" to $a
    $a += 4;            # would unlink $b automagically

However, it would not make

    $a = new Data 23;
    $a = 4;             # Now $a is a plain 4, not 'Data'

preserve "objectness" of $a. But Perl has a way to make assignments to an object do whatever you want. It is just not the overload, but tie()ing interface (see tie in the perlfunc manpage). Adding a FETCH() method which returns the object itself, and STORE() method which changes the value of the object, one can reproduce the arithmetic metaphor in its completeness, at least for variables which were tie()d from the start.

(Note that a workaround for a bug may be needed, see BUGS.)

Cookbook

Please add examples to what follows!

Two-face scalars

Put this in two_face.pm in your Perl library directory:

  package two_face;             # Scalars with separate string and
                                # numeric values.
  sub new { my $p = shift; bless [@_], $p }
  use overload '""' => \&str, '0+' => \&num, fallback => 1;
  sub num {shift->[1]}
  sub str {shift->[0]}

Use it as follows:

  require two_face;
  my $seven = new two_face ("vii", 7);
  printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
  print "seven contains `i'\n" if $seven =~ /i/;

(The second line creates a scalar which has both a string value, and a numeric value.) This prints:

  seven=vii, seven=7, eight=8
  seven contains `i'

Two-face references

Suppose you want to create an object which is accessible as both an array reference and a hash reference, similar to the pseudo-hash builtin Perl type. Let's make it better than a pseudo-hash by allowing index 0 to be treated as a normal element.

  package two_refs;
  use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
  sub new {
    my $p = shift;
    bless \ [@_], $p;
  }
  sub gethash {
    my %h;
    my $self = shift;
    tie %h, ref $self, $self;
    \%h;
  }

  sub TIEHASH { my $p = shift; bless \ shift, $p }
  my %fields;
  my $i = 0;
  $fields{$_} = $i++ foreach qw{zero one two three};
  sub STORE {
    my $self = ${shift()};
    my $key = $fields{shift()};
    defined $key or die "Out of band access";
    $$self->[$key] = shift;
  }
  sub FETCH {
    my $self = ${shift()};
    my $key = $fields{shift()};
    defined $key or die "Out of band access";
    $$self->[$key];
  }

Now one can access an object using both the array and hash syntax:

  my $bar = new two_refs 3,4,5,6;
  $bar->[2] = 11;
  $bar->{two} == 11 or die 'bad hash fetch';

Note several important features of this example. First of all, the actual type of $bar is a scalar reference, and we do not overload the scalar dereference. Thus we can get the actual non-overloaded contents of $bar by just using $$bar (what we do in functions which overload dereference). Similarly, the object returned by the TIEHASH() method is a scalar reference.

Second, we create a new tied hash each time the hash syntax is used. This allows us not to worry about a possibility of a reference loop, which would lead to a memory leak.

Both these problems can be cured. Say, if we want to overload hash dereference on a reference to an object which is implemented as a hash itself, the only problem one has to circumvent is how to access this actual hash (as opposed to the virtual hash exhibited by the overloaded dereference operator). Here is one possible fetching routine:

  sub access_hash {
    my ($self, $key) = (shift, shift);
    my $class = ref $self;
    bless $self, 'overload::dummy'; # Disable overloading of %{}
    my $out = $self->{$key};
    bless $self, $class;        # Restore overloading
    $out;
  }

To remove creation of the tied hash on each access, one may an extra level of indirection which allows a non-circular structure of references:

  package two_refs1;
  use overload '%{}' => sub { ${shift()}->[1] },
               '@{}' => sub { ${shift()}->[0] };
  sub new {
    my $p = shift;
    my $a = [@_];
    my %h;
    tie %h, $p, $a;
    bless \ [$a, \%h], $p;
  }
  sub gethash {
    my %h;
    my $self = shift;
    tie %h, ref $self, $self;
    \%h;
  }

  sub TIEHASH { my $p = shift; bless \ shift, $p }
  my %fields;
  my $i = 0;
  $fields{$_} = $i++ foreach qw{zero one two three};
  sub STORE {
    my $a = ${shift()};
    my $key = $fields{shift()};
    defined $key or die "Out of band access";
    $a->[$key] = shift;
  }
  sub FETCH {
    my $a = ${shift()};
    my $key = $fields{shift()};
    defined $key or die "Out of band access";
    $a->[$key];
  }

Now if $baz is overloaded like this, then $baz is a reference to a reference to the intermediate array, which keeps a reference to an actual array, and the access hash. The tie()ing object for the access hash is a reference to a reference to the actual array, so

  • There are no loops of references.

  • Both "objects" which are blessed into the class two_refs1 are references to a reference to an array, thus references to a scalar. Thus the accessor expression $$foo->[$ind] involves no overloaded operations.

Symbolic calculator

Put this in symbolic.pm in your Perl library directory:

  package symbolic;             # Primitive symbolic calculator
  use overload nomethod => \&wrap;

  sub new { shift; bless ['n', @_] }
  sub wrap {
    my ($obj, $other, $inv, $meth) = @_;
    ($obj, $other) = ($other, $obj) if $inv;
    bless [$meth, $obj, $other];
  }

This module is very unusual as overloaded modules go: it does not provide any usual overloaded operators, instead it provides the Last Resort operator nomethod. In this example the corresponding subroutine returns an object which encapsulates operations done over the objects: new symbolic 3 contains ['n', 3], 2 + new symbolic 3 contains ['+', 2, ['n', 3]].

Here is an example of the script which "calculates" the side of circumscribed octagon using the above package:

  require symbolic;
  my $iter = 1;                 # 2**($iter+2) = 8
  my $side = new symbolic 1;
  my $cnt = $iter;

  while ($cnt--) {
    $side = (sqrt(1 + $side**2) - 1)/$side;
  }
  print "OK\n";

The value of $side is

  ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
                       undef], 1], ['n', 1]]

Note that while we obtained this value using a nice little script, there is no simple way to use this value. In fact this value may be inspected in debugger (see the perldebug manpage), but ony if bareStringify Option is set, and not via p command.

If one attempts to print this value, then the overloaded operator "" will be called, which will call nomethod operator. The result of this operator will be stringified again, but this result is again of type symbolic, which will lead to an infinite loop.

Add a pretty-printer method to the module symbolic.pm:

  sub pretty {
    my ($meth, $a, $b) = @{+shift};
    $a = 'u' unless defined $a;
    $b = 'u' unless defined $b;
    $a = $a->pretty if ref $a;
    $b = $b->pretty if ref $b;
    "[$meth $a $b]";
  }

Now one can finish the script by

  print "side = ", $side->pretty, "\n";

The method pretty is doing object-to-string conversion, so it is natural to overload the operator "" using this method. However, inside such a method it is not necessary to pretty-print the components $a and $b of an object. In the above subroutine "[$meth $a $b]" is a catenation of some strings and components $a and $b. If these components use overloading, the catenation operator will look for an overloaded operator .; if not present, it will look for an overloaded operator "". Thus it is enough to use

  use overload nomethod => \&wrap, '""' => \&str;
  sub str {
    my ($meth, $a, $b) = @{+shift};
    $a = 'u' unless defined $a;
    $b = 'u' unless defined $b;
    "[$meth $a $b]";
  }

Now one can change the last line of the script to

  print "side = $side\n";

which outputs

  side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]

and one can inspect the value in debugger using all the possible methods.

Something is still amiss: consider the loop variable $cnt of the script. It was a number, not an object. We cannot make this value of type symbolic, since then the loop will not terminate.

Indeed, to terminate the cycle, the $cnt should become false. However, the operator bool for checking falsity is overloaded (this time via overloaded ""), and returns a long string, thus any object of type symbolic is true. To overcome this, we need a way to compare an object to 0. In fact, it is easier to write a numeric conversion routine.

Here is the text of symbolic.pm with such a routine added (and slightly modified str()):

  package symbolic;             # Primitive symbolic calculator
  use overload
    nomethod => \&wrap, '""' => \&str, '0+' => \&num;

  sub new { shift; bless ['n', @_] }
  sub wrap {
    my ($obj, $other, $inv, $meth) = @_;
    ($obj, $other) = ($other, $obj) if $inv;
    bless [$meth, $obj, $other];
  }
  sub str {
    my ($meth, $a, $b) = @{+shift};
    $a = 'u' unless defined $a;
    if (defined $b) {
      "[$meth $a $b]";
    } else {
      "[$meth $a]";
    }
  }
  my %subr = ( n => sub {$_[0]},
               sqrt => sub {sqrt $_[0]},
               '-' => sub {shift() - shift()},
               '+' => sub {shift() + shift()},
               '/' => sub {shift() / shift()},
               '*' => sub {shift() * shift()},
               '**' => sub {shift() ** shift()},
             );
  sub num {
    my ($meth, $a, $b) = @{+shift};
    my $subr = $subr{$meth}
      or die "Do not know how to ($meth) in symbolic";
    $a = $a->num if ref $a eq __PACKAGE__;
    $b = $b->num if ref $b eq __PACKAGE__;
    $subr->($a,$b);
  }

All the work of numeric conversion is done in %subr and num(). Of course, %subr is not complete, it contains only operators used in the example below. Here is the extra-credit question: why do we need an explicit recursion in num()? (Answer is at the end of this section.)

Use this module like this:

  require symbolic;
  my $iter = new symbolic 2;    # 16-gon
  my $side = new symbolic 1;
  my $cnt = $iter;

  while ($cnt) {
    $cnt = $cnt - 1;            # Mutator `--' not implemented
    $side = (sqrt(1 + $side**2) - 1)/$side;
  }
  printf "%s=%f\n", $side, $side;
  printf "pi=%f\n", $side*(2**($iter+2));

It prints (without so many line breaks)

  [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
                          [n 1]] 2]]] 1]
     [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
  pi=3.182598

The above module is very primitive. It does not implement mutator methods (++, -= and so on), does not do deep copying (not required without mutators!), and implements only those arithmetic operations which are used in the example.

To implement most arithmetic operations is easy; one should just use the tables of operations, and change the code which fills %subr to

  my %subr = ( 'n' => sub {$_[0]} );
  foreach my $op (split " ", $overload::ops{with_assign}) {
    $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
  }
  my @bins = qw(binary 3way_comparison num_comparison str_comparison);
  foreach my $op (split " ", "@overload::ops{ @bins }") {
    $subr{$op} = eval "sub {shift() $op shift()}";
  }
  foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
    print "defining `$op'\n";
    $subr{$op} = eval "sub {$op shift()}";
  }

Due to Calling Conventions for Mutators, we do not need anything special to make += and friends work, except filling += entry of %subr, and defining a copy constructor (needed since Perl has no way to know that the implementation of '+=' does not mutate the argument, compare Copy Constructor).

To implement a copy constructor, add '=' => \&cpy to use overload line, and code (this code assumes that mutators change things one level deep only, so recursive copying is not needed):

  sub cpy {
    my $self = shift;
    bless [@$self], ref $self;
  }

To make ++ and -- work, we need to implement actual mutators, either directly, or in nomethod. We continue to do things inside nomethod, thus add

    if ($meth eq '++' or $meth eq '--') {
      @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
      return $obj;
    }

after the first line of wrap(). This is not a most effective implementation, one may consider

  sub inc { $_[0] = bless ['++', shift, 1]; }

instead.

As a final remark, note that one can fill %subr by

  my %subr = ( 'n' => sub {$_[0]} );
  foreach my $op (split " ", $overload::ops{with_assign}) {
    $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
  }
  my @bins = qw(binary 3way_comparison num_comparison str_comparison);
  foreach my $op (split " ", "@overload::ops{ @bins }") {
    $subr{$op} = eval "sub {shift() $op shift()}";
  }
  foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
    $subr{$op} = eval "sub {$op shift()}";
  }
  $subr{'++'} = $subr{'+'};
  $subr{'--'} = $subr{'-'};

This finishes implementation of a primitive symbolic calculator in 50 lines of Perl code. Since the numeric values of subexpressions are not cached, the calculator is very slow.

Here is the answer for the exercise: In the case of str(), we need no explicit recursion since the overloaded .-operator will fall back to an existing overloaded operator "". Overloaded arithmetic operators do not fall back to numeric conversion if fallback is not explicitly requested. Thus without an explicit recursion num() would convert ['+', $a, $b] to $a + $b, which would just rebuild the argument of num().

If you wonder why defaults for conversion are different for str() and num(), note how easy it was to write the symbolic calculator. This simplicity is due to an appropriate choice of defaults. One extra note: due to the explicit recursion num() is more fragile than sym(): we need to explicitly check for the type of $a and $b. If components $a and $b happen to be of some related type, this may lead to problems.

Really symbolic calculator

One may wonder why we call the above calculator symbolic. The reason is that the actual calculation of the value of expression is postponed until the value is used.

To see it in action, add a method

  sub STORE {
    my $obj = shift;
    $#$obj = 1;
    @$obj->[0,1] = ('=', shift);
  }

to the package symbolic. After this change one can do

  my $a = new symbolic 3;
  my $b = new symbolic 4;
  my $c = sqrt($a**2 + $b**2);

and the numeric value of $c becomes 5. However, after calling

  $a->STORE(12);  $b->STORE(5);

the numeric value of $c becomes 13. There is no doubt now that the module symbolic provides a symbolic calculator indeed.

To hide the rough edges under the hood, provide a tie()d interface to the package symbolic (compare with Metaphor clash). Add methods

  sub TIESCALAR { my $pack = shift; $pack->new(@_) }
  sub FETCH { shift }
  sub nop {  }          # Around a bug

(the bug is described in BUGS). One can use this new interface as

  tie $a, 'symbolic', 3;
  tie $b, 'symbolic', 4;
  $a->nop;  $b->nop;    # Around a bug

  my $c = sqrt($a**2 + $b**2);

Now numeric value of $c is 5. After $a = 12; $b = 5 the numeric value of $c becomes 13. To insulate the user of the module add a method

  sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }

Now

  my ($a, $b);
  symbolic->vars($a, $b);
  my $c = sqrt($a**2 + $b**2);

  $a = 3; $b = 4;
  printf "c5  %s=%f\n", $c, $c;

  $a = 12; $b = 5;
  printf "c13  %s=%f\n", $c, $c;

shows that the numeric value of $c follows changes to the values of $a and $b.

AUTHOR

Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.

DIAGNOSTICS

When Perl is run with the -Do switch or its equivalent, overloading induces diagnostic messages.

Using the m command of Perl debugger (see the perldebug manpage) one can deduce which operations are overloaded (and which ancestor triggers this overloading). Say, if eq is overloaded, then the method (eq is shown by debugger. The method () corresponds to the fallback key (in fact a presence of this method shows that this package has overloading enabled, and it is what is used by the Overloaded function of module overload).

The module might issue the following warnings:

Odd number of arguments for overload::constant

(W) The call to overload::constant contained an odd number of arguments. The arguments should come in pairs.

`%s' is not an overloadable type

(W) You tried to overload a constant type the overload package is unaware of.

`%s' is not a code reference

(W) The second (fourth, sixth, ...) argument of overload::constant needs to be a code reference. Either an anonymous subroutine, or a reference to a subroutine.

BUGS

Because it is used for overloading, the per-package hash %OVERLOAD now has a special meaning in Perl. The symbol table is filled with names looking like line-noise.

For the purpose of inheritance every overloaded package behaves as if fallback is present (possibly undefined). This may create interesting effects if some package is not overloaded, but inherits from two overloaded packages.

Relation between overloading and tie()ing is broken. Overloading is triggered or not basing on the previous class of tie()d value.

This happens because the presence of overloading is checked too early, before any tie()d access is attempted. If the FETCH()ed class of the tie()d value does not change, a simple workaround is to access the value immediately after tie()ing, so that after this call the previous class coincides with the current one.

Needed: a way to fix this without a speed penalty.

Barewords are not covered by overloaded string constants.

This document is confusing. There are grammos and misleading language used in places. It would seem a total rewrite is needed.


re - Perl pragma to alter regular expression behaviour

NAME

re - Perl pragma to alter regular expression behaviour

SYNOPSIS

    use re 'taint';
    ($x) = ($^X =~ /^(.*)$/s);     # $x is tainted here

    $pat = '(?{ $foo = 1 })';
    use re 'eval';
    /foo${pat}bar/;                # won't fail (when not under -T switch)

    {
        no re 'taint';             # the default
        ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here

        no re 'eval';              # the default
        /foo${pat}bar/;            # disallowed (with or without -T switch)
            }

    use re 'debug';                # NOT lexically scoped (as others are)
    /^(.*)$/s;                     # output debugging info during
                                   #     compile and run time

    use re 'debugcolor';           # same as 'debug', but with colored output
    ...

(We use $^X in these examples because it's tainted by default.)

DESCRIPTION

When use re 'taint' is in effect, and a tainted string is the target of a regex, the regex memories (or values returned by the m// operator in list context) are tainted. This feature is useful when regex operations on tainted data aren't meant to extract safe substrings, but to perform other transformations.

When use re 'eval' is in effect, a regex is allowed to contain (?{ ... }) zero-width assertions even if regular expression contains variable interpolation. That is normally disallowed, since it is a potential security risk. Note that this pragma is ignored when the regular expression is obtained from tainted data, i.e. evaluation is always disallowed with tainted regular expressions. See (?{ code }) in the perlre manpage.

For the purpose of this pragma, interpolation of precompiled regular expressions (i.e., the result of qr//) is not considered variable interpolation. Thus:

    /foo${pat}bar/

is allowed if $pat is a precompiled regular expression, even if $pat contains (?{ ... }) assertions.

When use re 'debug' is in effect, perl emits debugging messages when compiling and using regular expressions. The output is the same as that obtained by running a -DDEBUGGING-enabled perl interpreter with the -Dr switch. It may be quite voluminous depending on the complexity of the match. Using debugcolor instead of debug enables a form of output that can be used to get a colorful display on terminals that understand termcap color sequences. Set $ENV{PERL_RE_TC} to a comma-separated list of termcap properties to use for highlighting strings on/off, pre-point part on/off. See Debugging regular expressions in the perldebug manpage for additional info.

The directive use re 'debug' is not lexically scoped, as the other directives are. It has both compile-time and run-time effects.

See Pragmatic Modules in the perlmodlib manpage.


sigtrap - Perl pragma to enable simple signal handling

  • OPTIONS
    • SIGNAL HANDLERS
    • SIGNAL LISTS
    • OTHER
  • EXAMPLES

NAME

sigtrap - Perl pragma to enable simple signal handling

SYNOPSIS

    use sigtrap;
    use sigtrap qw(stack-trace old-interface-signals);  # equivalent
    use sigtrap qw(BUS SEGV PIPE ABRT);
    use sigtrap qw(die INT QUIT);
    use sigtrap qw(die normal-signals);
    use sigtrap qw(die untrapped normal-signals);
    use sigtrap qw(die untrapped normal-signals
                    stack-trace any error-signals);
    use sigtrap 'handler' => \&my_handler, 'normal-signals';
    use sigtrap qw(handler my_handler normal-signals
                    stack-trace error-signals);

DESCRIPTION

The sigtrap pragma is a simple interface to installing signal handlers. You can have it install one of two handlers supplied by sigtrap itself (one which provides a Perl stack trace and one which simply die()s), or alternately you can supply your own handler for it to install. It can be told only to install a handler for signals which are either untrapped or ignored. It has a couple of lists of signals to trap, plus you can supply your own list of signals.

The arguments passed to the use statement which invokes sigtrap are processed in order. When a signal name or the name of one of sigtrap's signal lists is encountered a handler is immediately installed, when an option is encountered it affects subsequently installed handlers.

OPTIONS

SIGNAL HANDLERS

These options affect which handler will be used for subsequently installed signals.

stack-trace

The handler used for subsequently installed signals outputs a Perl stack trace to STDERR and then tries to dump core. This is the default signal handler.

die

The handler used for subsequently installed signals calls die (actually croak) with a message indicating which signal was caught.

handler your-handler

your-handler will be used as the handler for subsequently installed signals. your-handler can be any value which is valid as an assignment to an element of %SIG.

SIGNAL LISTS

sigtrap has a few built-in lists of signals to trap. They are:

normal-signals

These are the signals which a program might normally expect to encounter and which by default cause it to terminate. They are HUP, INT, PIPE and TERM.

error-signals

These signals usually indicate a serious problem with the Perl interpreter or with your script. They are ABRT, BUS, EMT, FPE, ILL, QUIT, SEGV, SYS and TRAP.

old-interface-signals

These are the signals which were trapped by default by the old sigtrap interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT, SEGV, SYS, TERM, and TRAP. If no signals or signals lists are passed to sigtrap, this list is used.

For each of these three lists, the collection of signals set to be trapped is checked before trapping; if your architecture does not implement a particular signal, it will not be trapped but rather silently ignored.

OTHER

untrapped

This token tells sigtrap to install handlers only for subsequently listed signals which aren't already trapped or ignored.

any

This token tells sigtrap to install handlers for all subsequently listed signals. This is the default behavior.

signal

Any argument which looks like a signal name (that is, /^[A-Z][A-Z0-9]*$/) indicates that sigtrap should install a handler for that name.

number

Require that at least version number of sigtrap is being used.

EXAMPLES

Provide a stack trace for the old-interface-signals:

    use sigtrap;

Ditto:

    use sigtrap qw(stack-trace old-interface-signals);

Provide a stack trace on the 4 listed signals only:

    use sigtrap qw(BUS SEGV PIPE ABRT);

Die on INT or QUIT:

    use sigtrap qw(die INT QUIT);

Die on HUP, INT, PIPE or TERM:

    use sigtrap qw(die normal-signals);

Die on HUP, INT, PIPE or TERM, except don't change the behavior for signals which are already trapped or ignored:

    use sigtrap qw(die untrapped normal-signals);

Die on receipt one of an of the normal-signals which is currently untrapped, provide a stack trace on receipt of any of the error-signals:

    use sigtrap qw(die untrapped normal-signals
                    stack-trace any error-signals);

Install my_handler() as the handler for the normal-signals:

    use sigtrap 'handler', \&my_handler, 'normal-signals';

Install my_handler() as the handler for the normal-signals, provide a Perl stack trace on receipt of one of the error-signals:

    use sigtrap qw(handler my_handler normal-signals
                    stack-trace error-signals);


sort - perl pragma to control sort behaviour

  • CAVEATS

NAME

sort - perl pragma to control sort() behaviour

SYNOPSIS

    use sort 'stable';          # guarantee stability
    use sort '_quicksort';      # use a quicksort algorithm
    use sort '_mergesort';      # use a mergesort algorithm
    use sort 'defaults';        # revert to default behavior
    no  sort 'stable';          # stability not important

    use sort '_qsort';          # alias for quicksort

    my $current = sort::current();      # identify prevailing algorithm

DESCRIPTION

With the sort pragma you can control the behaviour of the builtin sort() function.

In Perl versions 5.6 and earlier the quicksort algorithm was used to implement sort(), but in Perl 5.8 a mergesort algorithm was also made available, mainly to guarantee worst case O(N log N) behaviour: the worst case of quicksort is O(N**2). In Perl 5.8 and later, quicksort defends against quadratic behaviour by shuffling large arrays before sorting.

A stable sort means that for records that compare equal, the original input ordering is preserved. Mergesort is stable, quicksort is not. Stability will matter only if elements that compare equal can be distinguished in some other way. That means that simple numerical and lexical sorts do not profit from stability, since equal elements are indistinguishable. However, with a comparison such as

   { substr($a, 0, 3) cmp substr($b, 0, 3) }

stability might matter because elements that compare equal on the first 3 characters may be distinguished based on subsequent characters. In Perl 5.8 and later, quicksort can be stabilized, but doing so will add overhead, so it should only be done if it matters.

The best algorithm depends on many things. On average, mergesort does fewer comparisons than quicksort, so it may be better when complicated comparison routines are used. Mergesort also takes advantage of pre-existing order, so it would be favored for using sort() to merge several sorted arrays. On the other hand, quicksort is often faster for small arrays, and on arrays of a few distinct values, repeated many times. You can force the choice of algorithm with this pragma, but this feels heavy-handed, so the subpragmas beginning with a _ may not persist beyond Perl 5.8. The default algorithm is mergesort, which will be stable even if you do not explicitly demand it. But the stability of the default sort is a side-effect that could change in later versions. If stability is important, be sure to say so with a

  use sort 'stable';

The no sort pragma doesn't forbid what follows, it just leaves the choice open. Thus, after

  no sort qw(_mergesort stable);

a mergesort, which happens to be stable, will be employed anyway. Note that

  no sort "_quicksort";
  no sort "_mergesort";

have exactly the same effect, leaving the choice of sort algorithm open.

CAVEATS

This pragma is not lexically scoped: its effect is global to the program it appears in. That means the following will probably not do what you expect, because both pragmas take effect at compile time, before either sort() happens.

  { use sort "_quicksort";
    print sort::current . "\n";
    @a = sort @b;
  }
  { use sort "stable";
    print sort::current . "\n";
    @c = sort @d;
  }
  # prints:
  # quicksort stable
  # quicksort stable

You can achieve the effect you probably wanted by using eval() to defer the pragmas until run time. Use the quoted argument form of eval(), not the BLOCK form, as in

  eval { use sort "_quicksort" }; # WRONG

or the effect will still be at compile time. Reset to default options before selecting other subpragmas (in case somebody carelessly left them on) and after sorting, as a courtesy to others.

  { eval 'use sort qw(defaults _quicksort)'; # force quicksort
    eval 'no sort "stable"';      # stability not wanted
    print sort::current . "\n";
    @a = sort @b;
    eval 'use sort "defaults"';   # clean up, for others
  }
  { eval 'use sort qw(defaults stable)';     # force stability
    print sort::current . "\n";
    @c = sort @d;
    eval 'use sort "defaults"';   # clean up, for others
  }
  # prints:
  # quicksort
  # stable

Scoping for this pragma may change in future versions.


strict - Perl pragma to restrict unsafe constructs

  • HISTORY

NAME

strict - Perl pragma to restrict unsafe constructs

SYNOPSIS

    use strict;

    use strict "vars";
    use strict "refs";
    use strict "subs";

    use strict;
    no strict "vars";

DESCRIPTION

If no import list is supplied, all possible restrictions are assumed. (This is the safest mode to operate in, but is sometimes too strict for casual programming.) Currently, there are three possible things to be strict about: "subs", "vars", and "refs".

strict refs

This generates a runtime error if you use symbolic references (see the perlref manpage).

    use strict 'refs';
    $ref = \$foo;
    print $$ref;        # ok
    $ref = "foo";
    print $$ref;        # runtime error; normally ok
    $file = "STDOUT";
    print $file "Hi!";  # error; note: no comma after $file

There is one exception to this rule:

    $bar = \&{'foo'};
    &$bar;

is allowed so that goto &$AUTOLOAD would not break under stricture.

strict vars

This generates a compile-time error if you access a variable that wasn't declared via our or use vars, localized via my(), or wasn't fully qualified. Because this is to avoid variable suicide problems and subtle dynamic scoping issues, a merely local() variable isn't good enough. See my in the perlfunc manpage and local in the perlfunc manpage.

    use strict 'vars';
    $X::foo = 1;         # ok, fully qualified
    my $foo = 10;        # ok, my() var
    local $foo = 9;      # blows up

    package Cinna;
    our $bar;                   # Declares $bar in current package
    $bar = 'HgS';               # ok, global declared via pragma

The local() generated a compile-time error because you just touched a global name without fully qualifying it.

Because of their special use by sort(), the variables $a and $b are exempted from this check.

strict subs

This disables the poetry optimization, generating a compile-time error if you try to use a bareword identifier that's not a subroutine, unless it is a simple identifier (no colons) and that it appears in curly braces or on the left hand side of the => symbol.

    use strict 'subs';
    $SIG{PIPE} = Plumber;       # blows up
    $SIG{PIPE} = "Plumber";     # just fine: quoted string is always ok
    $SIG{PIPE} = \&Plumber;     # preferred form

See Pragmatic Modules in the perlmodlib manpage.

HISTORY

strict 'subs', with Perl 5.6.1, erroneously permitted to use an unquoted compound identifier (e.g. Foo::Bar) as a hash key (before => or inside curlies), but without forcing it always to a literal string.

Starting with Perl 5.8.1 strict is strict about its restrictions: if unknown restrictions are used, the strict pragma will abort with

    Unknown 'strict' tag(s) '...'


subs - Perl pragma to predeclare sub names

NAME

subs - Perl pragma to predeclare sub names

SYNOPSIS

    use subs qw(frob);
    frob 3..10;

DESCRIPTION

This will predeclare all the subroutine whose names are in the list, allowing you to use them without parentheses even before they're declared.

Unlike pragmas that affect the $^H hints variable, the use vars and use subs declarations are not BLOCK-scoped. They are thus effective for the entire file in which they appear. You may not rescind such declarations with no vars or no subs.

See Pragmatic Modules in the perlmodlib manpage and strict subs in the strict manpage.


threads - Perl interpreter-based threads

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • THREAD CONTEXT
    • Explicit context
    • Implicit context
  • THREAD STACK SIZE
  • THREAD SIGNALLING
  • WARNINGS
  • ERRORS
  • BUGS
  • REQUIREMENTS
  • SEE ALSO
  • AUTHOR
  • ACKNOWLEDGEMENTS

NAME

threads - Perl interpreter-based threads

VERSION

This document describes threads version 1.31

SYNOPSIS

    use threads ('yield', 'stack_size' => 64*4096);

    sub start_thread {
        my @args = @_;
        print('Thread started: ', join(' ', @args), "\n");
    }
    my $thread = threads->create('start_thread', 'argument');
    $thread->join();

    threads->create(sub { print("I am a thread\n"); })->join();

    my $thread3 = async { foreach (@files) { ... } };
    $thread3->join();

    # Invoke thread in list context (implicit) so it can return a list
    my ($thr) = threads->create(sub { return (qw/a b c/); });
    # or specify list context explicitly
    my $thr = threads->create({'context' => 'list'},
                              sub { return (qw/a b c/); });
    my @results = $thr->join();

    $thread->detach();

    $thread = threads->self();
    $thread = threads->object($tid);

    $tid = threads->tid();
    $tid = threads->self->tid();
    $tid = $thread->tid();

    threads->yield();
    yield();

    my @threads = threads->list();
    my $thread_count = threads->list();

    if ($thr1 == $thr2) {
        ...
    }

    $stack_size = threads->get_stack_size();
    $old_size = threads->set_stack_size(32*4096);

    # Create a thread with a specific context and stack size
    my $thr = threads->create({ 'context'    => 'list',
                                'stack_size' => 32*4096 },
                              \&foo);
    my @results = $thr->join();

    $thr->kill('SIGUSR1');

DESCRIPTION

Perl 5.6 introduced something called interpreter threads. Interpreter threads are different from 5005threads (the thread model of Perl 5.005) by creating a new Perl interpreter per thread, and not sharing any data or state between threads by default.

Prior to Perl 5.8, this has only been available to people embedding Perl, and for emulating fork() on Windows.

The threads API is loosely based on the old Thread.pm API. It is very important to note that variables are not shared between threads, all variables are by default thread local. To use shared variables one must use the threads::shared manpage.

It is also important to note that you must enable threads by doing use threads as early as possible in the script itself, and that it is not possible to enable threading inside an eval "", do, require, or use. In particular, if you are intending to share variables with the threads::shared manpage, you must use threads before you use threads::shared. (threads will emit a warning if you do it the other way around.)

$thr = threads->create(FUNCTION, ARGS)

This will create a new thread that will begin execution with the specified entry point function, and give it the ARGS list as parameters. It will return the corresponding threads object, or undef if thread creation failed.

FUNCTION may either be the name of a function, an anonymous subroutine, or a code ref.

    my $thr = threads->create('func_name', ...);
        # or
    my $thr = threads->create(sub { ... }, ...);
        # or
    my $thr = threads->create(\&func, ...);

The ->new() method is an alias for ->create().

$thr->join()

This will wait for the corresponding thread to complete its execution. When the thread finishes, ->join() will return the return value(s) of the entry point function.

The context (void, scalar or list) for the return value(s) for ->join() is determined at the time of thread creation.

    # Create thread in list context (implicit)
    my ($thr1) = threads->create(sub {
                                    my @results = qw(a b c);
                                    return (@results);
                                 });
    #   or (explicit)
    my $thr1 = threads->create({'context' => 'list'},
                               sub {
                                    my @results = qw(a b c);
                                    return (@results);
                               });
    # Retrieve list results from thread
    my @res1 = $thr1->join();

    # Create thread in scalar context (implicit)
    my $thr2 = threads->create(sub {
                                    my $result = 42;
                                    return ($result);
                                 });
    # Retrieve scalar result from thread
    my $res2 = $thr2->join();

    # Create a thread in void context (explicit)
    my $thr3 = threads->create({'void' => 1},
                               sub { print("Hello, world\n"); });
    # Join the thread in void context (i.e., no return value)
    $thr3->join();

See THREAD CONTEXT for more details.

If the program exits without all other threads having been either joined or detached, then a warning will be issued. (A program exits either because one of its threads explicitly calls exit(), or in the case of the main thread, reaches the end of the main program file.)

Calling ->join() or ->detach() on an already joined thread will cause an error to be thrown.

$thr->detach()

Makes the thread unjoinable, and causes any eventual return value to be discarded.

Calling ->join() or ->detach() on an already detached thread will cause an error to be thrown.

threads->detach()

Class method that allows a thread to detach itself.

threads->self()

Class method that allows a thread to obtain its own threads object.

$thr->tid()

Returns the ID of the thread. Thread IDs are unique integers with the main thread in a program being 0, and incrementing by 1 for every thread created.

threads->tid()

Class method that allows a thread to obtain its own ID.

threads->object($tid)

This will return the threads object for the active thread associated with the specified thread ID. Returns undef if there is no thread associated with the TID, if the thread is joined or detached, if no TID is specified or if the specified TID is undef.

threads->yield()

This is a suggestion to the OS to let this thread yield CPU time to other threads. What actually happens is highly dependent upon the underlying thread implementation.

You may do use threads qw(yield), and then just use yield() in your code.

threads->list()

In a list context, returns a list of all non-joined, non-detached threads objects. In a scalar context, returns a count of the same.

$thr1->equal($thr2)

Tests if two threads objects are the same thread or not. This is overloaded to the more natural forms:

    if ($thr1 == $thr2) {
        print("Threads are the same\n");
    }
    # or
    if ($thr1 != $thr2) {
        print("Threads differ\n");
    }

(Thread comparison is based on thread IDs.)

async BLOCK;

async creates a thread to execute the block immediately following it. This block is treated as an anonymous subroutine, and so must have a semi-colon after the closing brace. Like threads-create()>, async returns a threads object.

$thr->_handle()

This private method returns the memory location of the internal thread structure associated with a threads object. For Win32, this is a pointer to the HANDLE value returned by CreateThread (i.e., HANDLE *); for other platforms, it is a pointer to the pthread_t structure used in the pthread_create call (i.e., pthread_t *).

This method is of no use for general Perl threads programming. Its intent is to provide other (XS-based) thread modules with the capability to access, and possibly manipulate, the underlying thread structure associated with a Perl thread.

threads->_handle()

Class method that allows a thread to obtain its own handle.

THREAD CONTEXT

As with subroutines, the type of value returned from a thread's entry point function may be determined by the thread's context: list, scalar or void. The thread's context is determined at thread creation. This is necessary so that the context is available to the entry point function via wantarray(). The thread may then specify a value of the appropriate type to be returned from ->join().

Explicit context

Because thread creation and thread joining may occur in different contexts, it may be desirable to state the context explicitly to the thread's entry point function. This may be done by calling ->create() with a parameter hash as the first argument:

    my $thr = threads->create({'context' => 'list'}, \&foo);
    ...
    my @results = $thr->join();

In the above, the threads object is returned to the parent thread in scalar context, and the thread's entry point function foo will be called in list context such that the parent thread can receive a list from the ->join() call. Similarly, if you need the threads object, but your thread will not be returning a value (i.e., void context), you would do the following:

    my $thr = threads->create({'context' => 'void'}, \&foo);
    ...
    $thr->join();

The context type may also be used as the key in the parameter hash followed by a true value:

    threads->create({'scalar' => 1}, \&foo);
    ...
    my ($thr) = threads->list();
    my $result = $thr->join();

Implicit context

If not explicitly stated, the thread's context is implied from the context of the ->create() call:

    # Create thread in list context
    my ($thr) = threads->create(...);

    # Create thread in scalar context
    my $thr = threads->create(...);

    # Create thread in void context
    threads->create(...);

THREAD STACK SIZE

The default per-thread stack size for different platforms varies significantly, and is almost always far more than is needed for most applications. On Win32, Perl's makefile explicitly sets the default stack to 16 MB; on most other platforms, the system default is used, which again may be much larger than is needed.

By tuning the stack size to more accurately reflect your application's needs, you may significantly reduce your application's memory usage, and increase the number of simultaneously running threads.

N.B., on Windows, Address space allocation granularity is 64 KB, therefore, setting the stack smaller than that on Win32 Perl will not save any more memory.

threads->get_stack_size();

Returns the current default per-thread stack size. The default is zero, which means the system default stack size is currently in use.

$size = $thr->get_stack_size();

Returns the stack size for a particular thread. A return value of zero indicates the system default stack size was used for the thread.

$old_size = threads->set_stack_size($new_size);

Sets a new default per-thread stack size, and returns the previous setting.

Some platforms have a minimum thread stack size. Trying to set the stack size below this value will result in a warning, and the minimum stack size will be used.

Some Linux platforms have a maximum stack size. Setting too large of a stack size will cause thread creation to fail.

If needed, $new_size will be rounded up to the next multiple of the memory page size (usually 4096 or 8192).

Threads created after the stack size is set will then either call pthread_attr_setstacksize() (for pthreads platforms), or supply the stack size to CreateThread() (for Win32 Perl).

(Obviously, this call does not affect any currently extant threads.)

use threads ('stack_size' => VALUE);

This sets the default per-thread stack size at the start of the application.

$ENV{'PERL5_ITHREADS_STACK_SIZE'}

The default per-thread stack size may be set at the start of the application through the use of the environment variable PERL5_ITHREADS_STACK_SIZE:

    PERL5_ITHREADS_STACK_SIZE=1048576
    export PERL5_ITHREADS_STACK_SIZE
    perl -e'use threads; print(threads->get_stack_size(), "\n")'

This value overrides any stack_size parameter given to use threads. Its primary purpose is to permit setting the per-thread stack size for legacy threaded applications.

threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)

The stack size an individual threads may also be specified. This may be done by calling ->create() with a parameter hash as the first argument:

    my $thr = threads->create({'stack_size' => 32*4096}, \&foo, @args);
$thr2 = $thr1->create(FUNCTION, ARGS)

This creates a new thread ($thr2) that inherits the stack size from an existing thread ($thr1). This is shorthand for the following:

    my $stack_size = $thr1->get_stack_size();
    my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);

THREAD SIGNALLING

When safe signals is in effect (the default behavior - see Unsafe signals for more details), then signals may be sent and acted upon by individual threads.

$thr->kill('SIG...');

Sends the specified signal to the thread. Signal names and (positive) signal numbers are the same as those supported by kill(). For example, 'SIGTERM', 'TERM' and (depending on the OS) 15 are all valid arguments to ->kill().

Returns the thread object to allow for method chaining:

    $thr->kill('SIG...')->join();

Signal handlers need to be set up in the threads for the signals they are expected to act upon. Here's an example for cancelling a thread:

    use threads;

    # Suppress warning message when thread is 'killed'
    no warnings 'threads';

    sub thr_func
    {
        # Thread 'cancellation' signal handler
        $SIG{'KILL'} = sub { die("Thread killed\n"); };

        ...
    }
    # Create a thread
    my $thr = threads->create('thr_func');

    ...
    # Signal the thread to terminate, and then detach
    # it so that it will get cleaned up automatically
    $thr->kill('KILL')->detach();

Here's another simplistic example that illustrates the use of thread signalling in conjunction with a semaphore to provide rudimentary suspend and resume capabilities:

    use threads;
    use Thread::Semaphore;

    sub thr_func
    {
        my $sema = shift;

        # Thread 'suspend/resume' signal handler
        $SIG{'STOP'} = sub {
            $sema->down();      # Thread suspended
            $sema->up();        # Thread resumes
        };

        ...
    }
    # Create a semaphore and send it to a thread
    my $sema = Thread::Semaphore->new();
    my $thr = threads->create('thr_func', $sema);

    # Suspend the thread
    $sema->down();
    $thr->kill('STOP');

    ...
    # Allow the thread to continue
    $sema->up();

CAVEAT: The thread signalling capability provided by this module does not actually send signals via the OS. It emulates signals at the Perl-level such that signal handlers are called in the appropriate thread. For example, sending $thr->kill('STOP') does not actually suspend a thread (or the whole process), but does cause a $SIG{'STOP'} handler to be called in that thread (as illustrated above).

As such, signals that would normally not be appropriate to use in the kill() command (e.g., kill('KILL', $$)) are okay to use with the ->kill() method (again, as illustrated above).

Correspondingly, sending a signal to a thread does not disrupt the operation the thread is currently working on: The signal will be acted upon after the current operation has completed. For instance, if the thread is stuck on an I/O call, sending it a signal will not cause the I/O call to be interrupted such that the signal is acted up immediately.

WARNINGS

A thread exited while # other threads were still running

A thread (not necessarily the main thread) exited while there were still other threads running. Usually, it's a good idea to first collect the return values of the created threads by joining them, and only then exit from the main thread.

Thread creation failed: pthread_create returned #

See the appropriate man page for pthread_create to determine the actual cause for the failure.

Thread # terminated abnormally: ...

A thread terminated in some manner other than just returning from its entry point function. For example, the thread may have exited via die.

Using minimum thread stack size of #

Some platforms have a minimum thread stack size. Trying to set the stack size below this value will result in the above warning, and the stack size will be set to the minimum.

Thread creation failed: pthread_attr_setstacksize(SIZE) returned 22

The specified SIZE exceeds the system's maximum stack size. Use a smaller value for the stack size.

If needed, thread warnings can be suppressed by using:

    no warnings 'threads';

in the appropriate scope.

ERRORS

This Perl not built to support threads

The particular copy of Perl that you're trying to use was not built using the useithreads configuration option.

Having threads support requires all of Perl and all of the XS modules in the Perl installation to be rebuilt; it is not just a question of adding the the threads manpage module (i.e., threaded and non-threaded Perls are binary incompatible.)

Cannot change stack size of an existing thread

The stack size of currently extant threads cannot be changed, therefore, the following results in the above error:

    $thr->set_stack_size($size);
Cannot signal other threads without safe signals

Safe signals must be in effect to use the ->kill() signalling method. See Unsafe signals for more details.

Unrecognized signal name: ...

The particular copy of Perl that you're trying to use does not support the specified signal being used in a ->kill() call.

BUGS

Parent-child threads

On some platforms, it might not be possible to destroy parent threads while there are still existing child threads.

Creating threads inside special blocks

Creating threads inside BEGIN, CHECK or INIT blocks should not be relied upon. Depending on the Perl version and the application code, results may range from success, to (apparently harmless) warnings of leaked scalar, all the way up to crashing of the Perl interpreter.

Unsafe signals

Since Perl 5.8.0, signals have been made safer in Perl by postponing their handling until the interpreter is in a safe state. See Safe Signals in the perl58delta manpage and Deferred Signals (Safe Signals) in the perlipc manpage for more details.

Safe signals is the default behavior, and the old, immediate, unsafe signalling behavior is only in effect in the following situations:

  • Perl was been built with PERL_OLD_SIGNALS (see perl -V).
  • The environment variable PERL_SIGNALS is set to unsafe (see PERL_SIGNALS in the perlrun manpage).
  • The module the Perl::Unsafe::Signals manpage is used.

If unsafe signals is in effect, then signal handling is not thread-safe, and the ->kill() signalling method cannot be used.

Returning closures from threads

Returning closures from threads should not be relied upon. Depending of the Perl version and the application code, results may range from success, to (apparently harmless) warnings of leaked scalar, all the way up to crashing of the Perl interpreter.

Perl Bugs and the CPAN Version of the threads manpage

Support for threads extents beyond the code in this module (i.e., threads.pm and threads.xs), and into the Perl iterpreter itself. Older versions of Perl contain bugs that may manifest themselves despite using the latest version of the threads manpage from CPAN. There is no workaround for this other than upgrading to the lastest version of Perl.

(Before you consider posting a bug report, please consult, and possibly post a message to the discussion forum to see if what you've encountered is a known problem.)

REQUIREMENTS

Perl 5.8.0 or later

SEE ALSO

the threads manpage Discussion Forum on CPAN: http://www.cpanforum.com/dist/threads

Annotated POD for the threads manpage: http://annocpan.org/~JDHEDDEN/threads-1.31/shared.pm

the threads::shared manpage, the perlthrtut manpage

http://www.perl.com/pub/a/2002/06/11/threads.html and http://www.perl.com/pub/a/2002/09/04/threads.html

Perl threads mailing list: http://lists.cpan.org/showlist.cgi

Stack size discussion: http://www.perlmonks.org/

AUTHOR

Artur Bergman <sky AT crucially DOT net>

threads is released under the same license as Perl.

CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>

ACKNOWLEDGEMENTS

Richard Soderberg <perl AT crystalflame DOT net> - Helping me out tons, trying to find reasons for races and other weird bugs!

Simon Cozens <simon AT brecon DOT co DOT uk> - Being there to answer zillions of annoying questions

Rocco Caputo <troc AT netrus DOT net>

Vipul Ved Prakash <mail AT vipul DOT net> - Helping with debugging

Dean Arnold <darnold AT presicient DOT com> - Stack size API


threads::shared - Perl extension for sharing data structures between threads

  • VERSION
  • SYNOPSIS
  • DESCRIPTION
  • EXPORT
  • FUNCTIONS
  • OBJECTS
  • NOTES
  • BUGS AND LIMITATIONS
  • SEE ALSO
  • AUTHOR

NAME

threads::shared - Perl extension for sharing data structures between threads

VERSION

This document describes threads::shared version 1.01

SYNOPSIS

  use threads;
  use threads::shared;

  my $var :shared;
  $var = $scalar_value;
  $var = $shared_ref_value;
  $var = share($simple_unshared_ref_value);

  my($scalar, @array, %hash);
  share($scalar);
  share(@array);
  share(%hash);
  my $bar = &share([]);
  $hash{bar} = &share({});

  { lock(%hash); ...  }

  cond_wait($scalar);
  cond_timedwait($scalar, time() + 30);
  cond_broadcast(@array);
  cond_signal(%hash);

  my $lockvar :shared;
  # condition var != lock var
  cond_wait($var, $lockvar);
  cond_timedwait($var, time()+30, $lockvar);

DESCRIPTION

By default, variables are private to each thread, and each newly created thread gets a private copy of each existing variable. This module allows you to share variables across different threads (and pseudoforks on Win32). It is used together with the the threads manpage module.

EXPORT

share, cond_wait, cond_timedwait, cond_signal, cond_broadcast, is_shared

Note that if this module is imported when the threads manpage has not yet been loaded, then these functions all become no-ops. This makes it possible to write modules that will work in both threaded and non-threaded environments.

FUNCTIONS

share VARIABLE

share takes a value and marks it as shared. You can share a scalar, array, hash, scalar ref, array ref, or hash ref. share will return the shared rvalue, but always as a reference.

A variable can also be marked as shared at compile time by using the :shared attribute: my $var :shared;.

Due to problems with Perl's prototyping, if you want to share a newly created reference, you need to use the &share([]) and &share({}) syntax.

The only values that can be assigned to a shared scalar are other scalar values, or shared refs:

  my $var :shared;
  $var = 1;              # ok
  $var = [];             # error
  $var = &share([]);     # ok

share will traverse up references exactly one level. share(\$a) is equivalent to share($a), while share(\\$a) is not. This means that you must create nested shared data structures by first creating individual shared leaf nodes, and then adding them to a shared hash or array.

  my %hash :shared;
  $hash{'meaning'} = &share([]);
  $hash{'meaning'}[0] = &share({});
  $hash{'meaning'}[0]{'life'} = 42;
is_shared VARIABLE

is_shared checks if the specified variable is shared or not. If shared, returns the variable's internal ID (similar to refaddr()). Otherwise, returns undef.

  if (is_shared($var)) {
      print("\$var is shared\n");
  } else {
      print("\$var is not shared\n");
  }
lock VARIABLE

lock places a lock on a variable until the lock goes out of scope. If the variable is locked by another thread, the lock call will block until it's available. lock is recursive, so multiple calls to lock are safe -- the variable will remain locked until the outermost lock on the variable goes out of scope.

If a container object, such as a hash or array, is locked, all the elements of that container are not locked. For example, if a thread does a lock @a, any other thread doing a lock($a[12]) won't block.

lock will traverse up references exactly one level. lock(\$a) is equivalent to lock($a), while lock(\\$a) is not.

Note that you cannot explicitly unlock a variable; you can only wait for the lock to go out of scope. This is most easily accomplished by locking the variable inside a block.

  my $var :shared;
  {
      lock($var);
      # $var is locked from here to the end of the block
      ...
  }
  # $var is now unlocked

If you need more fine-grained control over shared variable access, see the Thread::Semaphore manpage.

cond_wait VARIABLE
cond_wait CONDVAR, LOCKVAR

The cond_wait function takes a locked variable as a parameter, unlocks the variable, and blocks until another thread does a cond_signal or cond_broadcast for that same locked variable. The variable that cond_wait blocked on is relocked after the cond_wait is satisfied. If there are multiple threads cond_waiting on the same variable, all but one will reblock waiting to reacquire the lock on the variable. (So if you're only using cond_wait for synchronisation, give up the lock as soon as possible). The two actions of unlocking the variable and entering the blocked wait state are atomic, the two actions of exiting from the blocked wait state and relocking the variable are not.

In its second form, cond_wait takes a shared, unlocked variable followed by a shared, locked variable. The second variable is unlocked and thread execution suspended until another thread signals the first variable.

It is important to note that the variable can be notified even if no thread cond_signal or cond_broadcast on the variable. It is therefore important to check the value of the variable and go back to waiting if the requirement is not fulfilled. For example, to pause until a shared counter drops to zero:

  { lock($counter); cond_wait($count) until $counter == 0; }
cond_timedwait VARIABLE, ABS_TIMEOUT
cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR

In its two-argument form, cond_timedwait takes a locked variable and an absolute timeout as parameters, unlocks the variable, and blocks until the timeout is reached or another thread signals the variable. A false value is returned if the timeout is reached, and a true value otherwise. In either case, the variable is re-locked upon return.

Like cond_wait, this function may take a shared, locked variable as an additional parameter; in this case the first parameter is an unlocked condition variable protected by a distinct lock variable.

Again like cond_wait, waking up and reacquiring the lock are not atomic, and you should always check your desired condition after this function returns. Since the timeout is an absolute value, however, it does not have to be recalculated with each pass:

  lock($var);
  my $abs = time() + 15;
  until ($ok = desired_condition($var)) {
      last if !cond_timedwait($var, $abs);
  }
  # we got it if $ok, otherwise we timed out!
cond_signal VARIABLE

The cond_signal function takes a locked variable as a parameter and unblocks one thread that's cond_waiting on that variable. If more than one thread is blocked in a cond_wait on that variable, only one (and which one is indeterminate) will be unblocked.

If there are no threads blocked in a cond_wait on the variable, the signal is discarded. By always locking before signaling, you can (with care), avoid signaling before another thread has entered cond_wait().

cond_signal will normally generate a warning if you attempt to use it on an unlocked variable. On the rare occasions where doing this may be sensible, you can skip the warning with:

  { no warnings 'threads'; cond_signal($foo); }
cond_broadcast VARIABLE

The cond_broadcast function works similarly to cond_signal. cond_broadcast, though, will unblock all the threads that are blocked in a cond_wait on the locked variable, rather than only one.

OBJECTS

the threads::shared manpage exports a version of bless() that works on shared objects such that i<blessings> propagate across threads.

  # Create a shared 'foo' object
  my $foo;
  share($foo);
  $foo = &share({});
  bless($foo, 'foo');

  # Create a shared 'bar' object
  my $bar;
  share($bar);
  $bar = &share({});
  bless($bar, 'bar');

  # Put 'bar' inside 'foo'
  $foo->{'bar'} = $bar;

  # Rebless the objects via a thread
  threads->create(sub {
      # Rebless the outer object
      bless($foo, 'yin');

      # Cannot directly rebless the inner object
      #bless($foo->{'bar'}, 'yang');

      # Retrieve and rebless the inner object
      my $obj = $foo->{'bar'};
      bless($obj, 'yang');
      $foo->{'bar'} = $obj;

  })->join();

  print(ref($foo),          "\n");    # Prints 'yin'
  print(ref($foo->{'bar'}), "\n");    # Prints 'yang'
  print(ref($bar),          "\n");    # Also prints 'yang'

NOTES

threads::shared is designed to disable itself silently if threads are not available. If you want access to threads, you must use threads before you use threads::shared. the threads manpage will emit a warning if you use it after the threads::shared manpage.

BUGS AND LIMITATIONS

When share is used on arrays, hashes, array refs or hash refs, any data they contain will be lost.

  my @arr = qw(foo bar baz);
  share(@arr);
  # @arr is now empty (i.e., == ());

  # Create a 'foo' object
  my $foo = { 'data' => 99 };
  bless($foo, 'foo');

  # Share the object
  share($foo);        # Contents are now wiped out
  print("ERROR: \$foo is empty\n")
      if (! exists($foo->{'data'}));

Therefore, populate such variables after declaring them as shared. (Scalar and scalar refs are not affected by this problem.)

It is often not wise to share an object unless the class itself has been written to support sharing. For example, an object's destructor may get called multiple times, one for each thread's scope exit. Another example, is that the contents of hash-based objects will be lost due to the above mentioned limitation.

Does not support splice on arrays!

Taking references to the elements of shared arrays and hashes does not autovivify the elements, and neither does slicing a shared array/hash over non-existent indices/keys autovivify the elements.

share() allows you to share($hashref->{key}) without giving any error message. But the $hashref->{key} is not shared, causing the error "locking can only be used on shared values" to occur when you attempt to lock($hasref->{key}).

View existing bug reports at, and submit any new bugs, problems, patches, etc. to: http://rt.cpan.org/NoAuth/Bugs.html

SEE ALSO

the threads::shared manpage Discussion Forum on CPAN: http://www.cpanforum.com/dist/threads-shared

Annotated POD for the threads::shared manpage: http://annocpan.org/~JDHEDDEN/threads-shared-1.01/shared.pm

the threads manpage, the perlthrtut manpage

http://www.perl.com/pub/a/2002/06/11/threads.html and http://www.perl.com/pub/a/2002/09/04/threads.html

Perl threads mailing list: http://lists.cpan.org/showlist.cgi

AUTHOR

Artur Bergman <sky AT crucially DOT net>

threads::shared is released under the same license as Perl.

Documentation borrowed from the old Thread.pm.

CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>.


utf8 - Perl pragma to enable/disable UTF-8 in source code

    • Utility functions
  • BUGS
  • SEE ALSO

NAME

utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code

SYNOPSIS

    use utf8;
    no utf8;

    # Convert a Perl scalar to/from UTF-8.
    $num_octets = utf8::upgrade($string);
    $success    = utf8::downgrade($string[, FAIL_OK]);

    # Change the native bytes of a Perl scalar to/from UTF-8 bytes.
    utf8::encode($string);
    utf8::decode($string);

    $flag = utf8::is_utf8(STRING); # since Perl 5.8.1
    $flag = utf8::valid(STRING);

DESCRIPTION

The use utf8 pragma tells the Perl parser to allow UTF-8 in the program text in the current lexical scope (allow UTF-EBCDIC on EBCDIC based platforms). The no utf8 pragma tells Perl to switch back to treating the source text as literal bytes in the current lexical scope.

This pragma is primarily a compatibility device. Perl versions earlier than 5.6 allowed arbitrary bytes in source code, whereas in future we would like to standardize on the UTF-8 encoding for source text.

Do not use this pragma for anything else than telling Perl that your script is written in UTF-8. The utility functions described below are useful for their own purposes, but they are not really part of the "pragmatic" effect.

Until UTF-8 becomes the default format for source text, either this pragma or the the encoding manpage pragma should be used to recognize UTF-8 in the source. When UTF-8 becomes the standard source format, this pragma will effectively become a no-op. For convenience in what follows the term UTF-X is used to refer to UTF-8 on ASCII and ISO Latin based platforms and UTF-EBCDIC on EBCDIC based platforms.

See also the effects of the -C switch and its cousin, the $ENV{PERL_UNICODE}, in the perlrun manpage.

Enabling the utf8 pragma has the following effect:

  • Bytes in the source text that have their high-bit set will be treated as being part of a literal UTF-8 character. This includes most literals such as identifier names, string constants, and constant regular expression patterns.

    On EBCDIC platforms characters in the Latin 1 character set are treated as being part of a literal UTF-EBCDIC character.

Note that if you have bytes with the eighth bit on in your script (for example embedded Latin-1 in your string literals), use utf8 will be unhappy since the bytes are most probably not well-formed UTF-8. If you want to have such bytes and use utf8, you can disable utf8 until the end the block (or file, if at top level) by no utf8;.

If you want to automatically upgrade your 8-bit legacy bytes to UTF-8, use the the encoding manpage pragma instead of this pragma. For example, if you want to implicitly upgrade your ISO 8859-1 (Latin-1) bytes to UTF-8 as used in e.g. chr() and \x{...}, try this:

    use encoding "latin-1";
    my $c = chr(0xc4);
    my $x = "\x{c5}";

In case you are wondering: yes, use encoding 'utf8'; works much the same as use utf8;.

Utility functions

The following functions are defined in the utf8:: package by the Perl core. You do not need to say use utf8 to use these and in fact you should not say that unless you really want to have UTF-8 source code.

  • $num_octets = utf8::upgrade($string)

    Converts in-place the octet sequence in the native encoding (Latin-1 or EBCDIC) to the equivalent character sequence in UTF-X. $string already encoded as characters does no harm. Returns the number of octets necessary to represent the string as UTF-X. Can be used to make sure that the UTF-8 flag is on, so that \w or lc() work as Unicode on strings containing characters in the range 0x80-0xFF (on ASCII and derivatives).

    Note that this function does not handle arbitrary encodings. Therefore Encode.pm is recommended for the general purposes.

    Affected by the encoding pragma.

  • $success = utf8::downgrade($string[, FAIL_OK])

    Converts in-place the character sequence in UTF-X to the equivalent octet sequence in the native encoding (Latin-1 or EBCDIC). $string already encoded as octets does no harm. Returns true on success. On failure dies or, if the value of FAIL_OK is true, returns false. Can be used to make sure that the UTF-8 flag is off, e.g. when you want to make sure that the substr() or length() function works with the usually faster byte algorithm.

    Note that this function does not handle arbitrary encodings. Therefore Encode.pm is recommended for the general purposes.

    Not affected by the encoding pragma.

    NOTE: this function is experimental and may change or be removed without notice.

  • utf8::encode($string)

    Converts in-place the character sequence to the corresponding octet sequence in UTF-X. The UTF-8 flag is turned off. Returns nothing.

    Note that this function does not handle arbitrary encodings. Therefore Encode.pm is recommended for the general purposes.

  • utf8::decode($string)

    Attempts to convert in-place the octet sequence in UTF-X to the corresponding character sequence. The UTF-8 flag is turned on only if the source string contains multiple-byte UTF-X characters. If $string is invalid as UTF-X, returns false; otherwise returns true.

    Note that this function does not handle arbitrary encodings. Therefore Encode.pm is recommended for the general purposes.

    NOTE: this function is experimental and may change or be removed without notice.

  • $flag = utf8::is_utf8(STRING)

    (Since Perl 5.8.1) Test whether STRING is in UTF-8. Functionally the same as Encode::is_utf8().

  • $flag = utf8::valid(STRING)

    [INTERNAL] Test whether STRING is in a consistent state regarding UTF-8. Will return true is well-formed UTF-8 and has the UTF-8 flag on or if string is held as bytes (both these states are 'consistent'). Main reason for this routine is to allow Perl's testsuite to check that operations have left strings in a consistent state. You most probably want to use utf8::is_utf8() instead.

utf8::encode is like utf8::upgrade, but the UTF8 flag is cleared. See the perlunicode manpage for more on the UTF8 flag and the C API functions sv_utf8_upgrade, sv_utf8_downgrade, sv_utf8_encode, and sv_utf8_decode, which are wrapped by the Perl functions utf8::upgrade, utf8::downgrade, utf8::encode and utf8::decode. Note that in the Perl 5.8.0 and 5.8.1 implementation the functions utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade, and utf8::downgrade are always available, without a require utf8 statement-- this may change in future releases.

BUGS

One can have Unicode in identifier names, but not in package/class or subroutine names. While some limited functionality towards this does exist as of Perl 5.8.0, that is more accidental than designed; use of Unicode for the said purposes is unsupported.

One reason of this unfinishedness is its (currently) inherent unportability: since both package names and subroutine names may need to be mapped to file and directory names, the Unicode capability of the filesystem becomes important-- and there unfortunately aren't portable answers.

SEE ALSO

the perluniintro manpage, the encoding manpage, the perlrun manpage, the bytes manpage, the perlunicode manpage


vars - Perl pragma to predeclare global variable names

NAME

vars - Perl pragma to predeclare global variable names (obsolete)

SYNOPSIS

    use vars qw($frob @mung %seen);

DESCRIPTION

NOTE: For variables in the current package, the functionality provided by this pragma has been superseded by our declarations, available in Perl v5.6.0 or later. See our in the perlfunc manpage.

This will predeclare all the variables whose names are in the list, allowing you to use them under "use strict", and disabling any typo warnings.

Unlike pragmas that affect the $^H hints variable, the use vars and use subs declarations are not BLOCK-scoped. They are thus effective for the entire file in which they appear. You may not rescind such declarations with no vars or no subs.

Packages such as the AutoLoader and SelfLoader that delay loading of subroutines within packages can create problems with package lexicals defined using my(). While the vars pragma cannot duplicate the effect of package lexicals (total transparency outside of the package), it can act as an acceptable substitute by pre-declaring global symbols, ensuring their availability to the later-loaded routines.

See Pragmatic Modules in the perlmodlib manpage.


version - Perl extension for Version Objects

    • BEST PRACTICES
    • Using modules that use version.pm
    • What IS a version
    • Numeric Versions
    • Extended Versions
    • Numeric Alpha Versions
    • Object Methods
    • Quoting
    • What about v-strings?
    • Types of Versions Objects
    • Replacement UNIVERSAL::VERSION
  • SUBCLASSING
  • EXPORT
  • AUTHOR
  • SEE ALSO

NAME

version - Perl extension for Version Objects

SYNOPSIS

  use version;
  $version = version->new("12.2.1"); # must be quoted for Perl < 5.8.1
  print $version;               # v12.2.1
  print $version->numify;       # 12.002001
  if ( $version gt "12.2" )     # true

  $alphaver = version->new("1.02_03"); # must be quoted!
  print $alphaver;              # 1.02_0300
  print $alphaver->is_alpha();  # true

  $ver = qv("1.2.0");           # v1.2.0

  $perlver = version->new(5.005_03); # must not be quoted!
  print $perlver;               # 5.005030

DESCRIPTION

Overloaded version objects for all modern versions of Perl. This module implements all of the features of version objects which will be part of Perl 5.10.0.

BEST PRACTICES

If you intend for your module to be used by different releases of Perl, and/or for your $VERSION scalar to mean what you think it means, there are a few simple rules to follow:

  • Be consistent

    Whichever of the two types of version objects that you choose to employ, you should stick to either Numeric Versions or Extended Versions and not mix them together. While this is possible, it is very confusing to the average user.

    If you intend to use Extended Versions, you are strongly encouraged to use the qv() operator with a quoted term, e.g.:

      use version; our $VERSION = qv("1.2.3");

    on a single line as above.

    At the very least, decide on which of the several ways to initialize your version objects you prefer and stick with it. It is also best to be explicit about what value you intend to assign your version object and to not rely on hidden behavior of the parser.

  • Be careful

    If you are using Module::Build or ExtUtils::MakeMaker, so that you can release your module to CPAN, you have to recognize that neither of those programs completely handles version objects natively (yet). If you use version objects with Module::Build, you should add an explicit dependency to the release of version.pm in your Build.PL:

      my $builder = Module::Build->new(
     ...
     requires => {
         ... ,
         'version'    => 0.50,
         ...,
     },
     ...
  );

    and it should Just Work(TM). Module::Build will [hopefully soon] include full support for version objects; there are no current plans to patch ExtUtils::MakeMaker to support version objects.

Using modules that use version.pm

As much as possible, the version.pm module remains compatible with all current code. However, if your module is using a module that has defined $VERSION using the version class, there are a couple of things to be aware of. For purposes of discussion, we will assume that we have the following module installed:

  package Example;
  use version;  $VERSION = qv('1.2.2');
  ...module code here...
  1;
Numeric versions always work

Code of the form:

  use Example 1.002003;

will always work correctly. The use will perform an automatic $VERSION comparison using the floating point number given as the first term after the module name (e.g. above 1.002.003). In this case, the installed module is too old for the requested line, so you would see an error like:

  Example version 1.002003 (v1.2.3) required--this is only version 1.002002 (v1.2.2)...
Extended version work sometimes

With Perl >= 5.6.2, you can also use a line like this:

  use Example 1.2.3;

and it will again work (i.e. give the error message as above), even with releases of Perl which do not normally support v-strings (see What about v-strings below). This has to do with that fact that use only checks to see if the second term looks like a number and passes that to the replacement the UNIVERSAL::VERSION manpage. This is not true in Perl 5.005_04, however, so you are strongly encouraged to always use a numeric version in your code, even for those versions of Perl which support the extended version.

What IS a version

For the purposes of this module, a version "number" is a sequence of positive integer values separated by one or more decimal points and optionally a single underscore. This corresponds to what Perl itself uses for a version, as well as extending the "version as number" that is discussed in the various editions of the Camel book.

There are actually two distinct kinds of version objects:

  • Numeric Versions

    Any initial parameter which "looks like a number", see Numeric Versions. This also covers versions with a single decimal point and a single embedded underscore, see Numeric Alpha Versions, even though these must be quoted to preserve the underscore formatting.

  • Extended Versions

    Any initial parameter which contains more than one decimal point and an optional embedded underscore, see Extended Versions. This is what is commonly used in most open source software as the "external" version (the one used as part of the tag or tarfile name). The use of the exported qv() function also produces this kind of version object.

Both of these methods will produce similar version objects, in that the default stringification will yield the version Normal Form only if required:

  $v  = version->new(1.002);     # 1.002, but compares like 1.2.0
  $v  = version->new(1.002003);  # 1.002003
  $v2 = version->new("1.2.3");   # v1.2.3

In specific, version numbers initialized as Numeric Versions will stringify as they were originally created (i.e. the same string that was passed to new(). Version numbers initialized as Extended Versions will be stringified as Normal Form.

Numeric Versions

These correspond to historical versions of Perl itself prior to 5.6.0, as well as all other modules which follow the Camel rules for the $VERSION scalar. A numeric version is initialized with what looks like a floating point number. Leading zeros are significant and trailing zeros are implied so that a minimum of three places is maintained between subversions. What this means is that any subversion (digits to the right of the decimal place) that contains less than three digits will have trailing zeros added to make up the difference, but only for purposes of comparison with other version objects. For example:

                                   # Prints     Equivalent to
                                     $v = version->new(      1.2);    # 1.2        v1.200.0
                                     $v = version->new(     1.02);    # 1.02       v1.20.0
                                     $v = version->new(    1.002);    # 1.002      v1.2.0
                                     $v = version->new(   1.0023);    # 1.0023     v1.2.300
                                     $v = version->new(  1.00203);    # 1.00203    v1.2.30
                                     $v = version->new( 1.002003);    # 1.002003   v1.2.3

All of the preceding examples are true whether or not the input value is quoted. The important feature is that the input value contains only a single decimal. See also Alpha Versions for how to handle

IMPORTANT NOTE: As shown above, if your numeric version contains more than 3 significant digits after the decimal place, it will be split on each multiple of 3, so 1.0003 is equivalent to v1.0.300, due to the need to remain compatible with Perl's own 5.005_03 == 5.5.30 interpretation. Any trailing zeros are ignored for mathematical comparison purposes.

Extended Versions

These are the newest form of versions, and correspond to Perl's own version style beginning with 5.6.0. Starting with Perl 5.10.0, and most likely Perl 6, this is likely to be the preferred form. This method normally requires that the input parameter be quoted, although Perl's after 5.8.1 can use v-strings as a special form of quoting, but this is highly discouraged.

Unlike Numeric Versions, Extended Versions have more than a single decimal point, e.g.:

                                   # Prints
                                     $v = version->new( "v1.200");    # v1.200.0
                                     $v = version->new("v1.20.0");    # v1.20.0
                                     $v = qv("v1.2.3");               # v1.2.3
                                     $v = qv("1.2.3");                # v1.2.3
                                     $v = qv("1.20");                 # v1.20.0

In general, Extended Versions permit the greatest amount of freedom to specify a version, whereas Numeric Versions enforce a certain uniformity. See also New Operator for an additional method of initializing version objects.

Just like Numeric Versions, Extended Versions can be used as Alpha Versions.

Numeric Alpha Versions

The one time that a numeric version must be quoted is when a alpha form is used with an otherwise numeric version (i.e. a single decimal point). This is commonly used for CPAN releases, where CPAN or CPANPLUS will ignore alpha versions for automatic updating purposes. Since some developers have used only two significant decimal places for their non-alpha releases, the version object will automatically take that into account if the initializer is quoted. For example Module::Example was released to CPAN with the following sequence of $VERSION's:

  # $VERSION    Stringified
  0.01          0.01
  0.02          0.02
  0.02_01       0.02_01
  0.02_02       0.02_02
  0.03          0.03
  etc.

The stringified form of numeric versions will always be the same string that was used to initialize the version object.

Object Methods

Overloading has been used with version objects to provide a natural interface for their use. All mathematical operations are forbidden, since they don't make any sense for base version objects. Consequently, there is no overloaded numification available. If you want to use a version object in a numeric context for some reason, see the numify object method.

  • New Operator

    Like all OO interfaces, the new() operator is used to initialize version objects. One way to increment versions when programming is to use the CVS variable $Revision, which is automatically incremented by CVS every time the file is committed to the repository.

    In order to facilitate this feature, the following code can be employed:

      $VERSION = version->new(qw$Revision: 2.7 $);

    and the version object will be created as if the following code were used:

      $VERSION = version->new("v2.7");

    In other words, the version will be automatically parsed out of the string, and it will be quoted to preserve the meaning CVS normally carries for versions. The CVS $Revision$ increments differently from numeric versions (i.e. 1.10 follows 1.9), so it must be handled as if it were a Extended Version.

    A new version object can be created as a copy of an existing version object, either as a class method:

      $v1 = version->new(12.3);
  $v2 = version->new($v1);

    or as an object method:

      $v1 = version->new(12.3);
  $v2 = $v1->new(12.3);

    and in each case, $v1 and $v2 will be identical. NOTE: if you create a new object using an existing object like this:

      $v2 = $v1->new();

    the new object will not be a clone of the existing object. In the example case, $v2 will be an empty object of the same type as $v1.

  • qv()

    An alternate way to create a new version object is through the exported qv() sub. This is not strictly like other q? operators (like qq, qw), in that the only delimiters supported are parentheses (or spaces). It is the best way to initialize a short version without triggering the floating point interpretation. For example:

      $v1 = qv(1.2);         # 1.2.0
  $v2 = qv("1.2");       # also 1.2.0

    As you can see, either a bare number or a quoted string can usually be used interchangably, except in the case of a trailing zero, which must be quoted to be converted properly. For this reason, it is strongly recommended that all initializers to qv() be quoted strings instead of bare numbers.

    To prevent the qv() function from being exported to the caller's namespace, either use version with a null parameter:

      use version ();

    or just require version, like this:

      require version;

    Both methods will prevent the import() method from firing and exporting the qv() sub. This is true of subclasses of version as well, see SUBCLASSING for details.

For the subsequent examples, the following three objects will be used:

  $ver   = version->new("1.2.3.4"); # see "Quoting" below
  $alpha = version->new("1.2.3_4"); # see "Alpha versions" below
  $nver  = version->new(1.002);     # see "Numeric Versions" above
  • Normal Form

    For any version object which is initialized with multiple decimal places (either quoted or if possible v-string), or initialized using the qv() operator, the stringified representation is returned in a normalized or reduced form (no extraneous zeros), and with a leading 'v':

      print $ver->normal;         # prints as v1.2.3.4
  print $ver->stringify;      # ditto
  print $ver;                 # ditto
  print $nver->normal;        # prints as v1.2.0
  print $nver->stringify;     # prints as 1.002, see "Stringification"

    In order to preserve the meaning of the processed version, the normalized representation will always contain at least three sub terms. In other words, the following is guaranteed to always be true:

      my $newver = version->new($ver->stringify);
  if ($newver eq $ver ) # always true
    {...}
  • Numification

    Although all mathematical operations on version objects are forbidden by default, it is possible to retrieve a number which corresponds to the version object through the use of the $obj->numify method. For formatting purposes, when displaying a number which corresponds a version object, all sub versions are assumed to have three decimal places. So for example:

      print $ver->numify;         # prints 1.002003004
  print $nver->numify;        # prints 1.002

    Unlike the stringification operator, there is never any need to append trailing zeros to preserve the correct version value.

  • Stringification

    The default stringification for version objects returns exactly the same string as was used to create it, whether you used new() or qv(), with one exception. The sole exception is if the object was created using qv() and the initializer did not have two decimal places or a leading 'v' (both optional), then the stringified form will have a leading 'v' prepended, in order to support round-trip processing.

    For example:

      Initialized as          Stringifies to
  ==============          ==============
  version->new("1.2")       1.2
  version->new("v1.2")     v1.2
  qv("1.2.3")               1.2.3
  qv("v1.3.5")             v1.3.5
  qv("1.2")                v1.2   ### exceptional case

    See also the UNIVERSAL::VERSION manpage, as this also returns the stringified form when used as a class method.

  • Comparison operators

    Both cmp and <=> operators perform the same comparison between terms (upgrading to a version object automatically). Perl automatically generates all of the other comparison operators based on those two. In addition to the obvious equalities listed below, appending a single trailing 0 term does not change the value of a version for comparison purposes. In other words "v1.2" and "1.2.0" will compare as identical.

    For example, the following relations hold:

      As Number        As String           Truth Value
  -------------    ----------------    -----------
  $ver >  1.0      $ver gt "1.0"       true
  $ver <  2.5      $ver lt             true
  $ver != 1.3      $ver ne "1.3"       true
  $ver == 1.2      $ver eq "1.2"       false
  $ver == 1.2.3.4  $ver eq "1.2.3.4"   see discussion below

    It is probably best to chose either the numeric notation or the string notation and stick with it, to reduce confusion. Perl6 version objects may only support numeric comparisons. See also Quoting.

    WARNING: Comparing version with unequal numbers of decimal points (whether explicitly or implicitly initialized), may yield unexpected results at first glance. For example, the following inequalities hold:

      version->new(0.96)     > version->new(0.95); # 0.960.0 > 0.950.0
  version->new("0.96.1") < version->new(0.95); # 0.096.1 < 0.950.0

    For this reason, it is best to use either exclusively Numeric Versions or Extended Versions with multiple decimal points.

  • Logical Operators

    If you need to test whether a version object has been initialized, you can simply test it directly:

      $vobj = version->new($something);
  if ( $vobj )   # true only if $something was non-blank

    You can also test whether a version object is an Alpha version, for example to prevent the use of some feature not present in the main release:

      $vobj = version->new("1.2_3"); # MUST QUOTE
  ...later...
  if ( $vobj->is_alpha )       # True

Quoting

Because of the nature of the Perl parsing and tokenizing routines, certain initialization values must be quoted in order to correctly parse as the intended version, especially when using the qv() operator. In all cases, a floating point number passed to version->new() will be identically converted whether or not the value itself is quoted. This is not true for qv(), however, when trailing zeros would be stripped on an unquoted input, which would result in a very different version object.

In addition, in order to be compatible with earlier Perl version styles, any use of versions of the form 5.006001 will be translated as v5.6.1. In other words, a version with a single decimal point will be parsed as implicitly having three digits between subversions, but only for internal comparison purposes.

The complicating factor is that in bare numbers (i.e. unquoted), the underscore is a legal numeric character and is automatically stripped by the Perl tokenizer before the version code is called. However, if a number containing one or more decimals and an underscore is quoted, i.e. not bare, that is considered a Alpha Version and the underscore is significant.

If you use a mathematic formula that resolves to a floating point number, you are dependent on Perl's conversion routines to yield the version you expect. You are pretty safe by dividing by a power of 10, for example, but other operations are not likely to be what you intend. For example:

  $VERSION = version->new((qw$Revision: 1.4)[1]/10);
  print $VERSION;          # yields 0.14
  $V2 = version->new(100/9); # Integer overflow in decimal number
  print $V2;               # yields something like 11.111.111.100

Perl 5.8.1 and beyond will be able to automatically quote v-strings but that is not possible in earlier versions of Perl. In other words:

  $version = version->new("v2.5.4");  # legal in all versions of Perl
  $newvers = version->new(v2.5.4);    # legal only in Perl >= 5.8.1

What about v-strings?

Beginning with Perl 5.6.0, an alternate method to code arbitrary strings of bytes was introduced, called v-strings. They were intended to be an easy way to enter, for example, Unicode strings (which contain two bytes per character). Some programs have used them to encode printer control characters (e.g. CRLF). They were also intended to be used for $VERSION, but their use as such has been problematic from the start.

There are two ways to enter v-strings: a bare number with two or more decimal points, or a bare number with one or more decimal points and a leading 'v' character (also bare). For example:

  $vs1 = 1.2.3; # encoded as \1\2\3
  $vs2 = v1.2;  # encoded as \1\2

However, the use of bare v-strings to initialize version objects is strongly discouraged in all circumstances (especially the leading 'v' style), since the meaning will change depending on which Perl you are running. It is better to directly use Extended Versions to ensure the proper interpretation.

If you insist on using bare v-strings with Perl > 5.6.0, be aware of the following limitations:

1) For Perl releases 5.6.0 through 5.8.0, the v-string code merely guesses, based on some characteristics of v-strings. You must use a three part version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful.

2) For Perl releases 5.8.1 and later, v-strings have changed in the Perl core to be magical, which means that the version.pm code can automatically determine whether the v-string encoding was used.

Types of Versions Objects

There are two types of Version Objects:

  • Ordinary versions

    These are the versions that normal modules will use. Can contain as many subversions as required. In particular, those using RCS/CVS can use the following:

      $VERSION = version->new(qw$Revision: 2.7 $);

    and the current RCS Revision for that file will be inserted automatically. If the file has been moved to a branch, the Revision will have three or more elements; otherwise, it will have only two. This allows you to automatically increment your module version by using the Revision number from the primary file in a distribution, see VERSION_FROM in the ExtUtils::MakeMaker manpage.

  • Alpha Versions

    For module authors using CPAN, the convention has been to note unstable releases with an underscore in the version string, see the CPAN manpage. Alpha releases will test as being newer than the more recent stable release, and less than the next stable release. For example:

      $alphaver = version->new("12.03_01"); # must be quoted

    obeys the relationship

      12.03 < $alphaver < 12.04

    Alpha versions with a single decimal point will be treated exactly as if they were Numeric Versions, for parsing and output purposes. The underscore will be output when an alpha version is stringified, in the same place as it was when input.

    Alpha versions with more than a single decimal point will be treated exactly as if they were Extended Versions, and will display without any trailing (or leading) zeros, in the Version Normal form. For example,

      $newver = version->new("12.3.1_1");
  print $newver; # v12.3.1_1

Replacement UNIVERSAL::VERSION

In addition to the version objects, this modules also replaces the core UNIVERSAL::VERSION function with one that uses version objects for its comparisons. The return from this operator is always the stringified form, but the warning message generated includes either the stringified form or the normal form, depending on how it was called.

For example:

  package Foo;
  $VERSION = 1.2;

  package Bar;
  $VERSION = "1.3.5"; # works with all Perl's (since it is quoted)

  package main;
  use version;

  print $Foo::VERSION; # prints 1.2

  print $Bar::VERSION; # prints 1.003005

  eval "use foo 10";
  print $@; # prints "foo version 10 required..."
  eval "use foo 1.3.5; # work in Perl 5.6.1 or better
  print $@; # prints "foo version 1.3.5 required..."

  eval "use bar 1.3.6";
  print $@; # prints "bar version 1.3.6 required..."
  eval "use bar 1.004"; # note numeric version
  print $@; # prints "bar version 1.004 required..."

IMPORTANT NOTE: This may mean that code which searches for a specific string (to determine whether a given module is available) may need to be changed. It is always better to use the built-in comparison implicit in use or require, rather than manually poking at class-VERSION> and then doing a comparison yourself.

The replacement UNIVERSAL::VERSION, when used as a function, like this:

  print $module->VERSION;

will also exclusively return the stringified form. See Stringification for more details.

SUBCLASSING

This module is specifically designed and tested to be easily subclassed. In practice, you only need to override the methods you want to change, but you have to take some care when overriding new() (since that is where all of the parsing takes place). For example, this is a perfect acceptable derived class:

  package myversion;
  use base version;
  sub new {
      my($self,$n)=@_;
      my $obj;
      # perform any special input handling here
      $obj = $self->SUPER::new($n);
      # and/or add additional hash elements here
      return $obj;
  }

See also the version::AlphaBeta manpage on CPAN for an alternate representation of version strings.

NOTE: Although the qv operator is not a true class method, but rather a function exported into the caller's namespace, a subclass of version will inherit an import() function which will perform the correct magic on behalf of the subclass.

EXPORT

qv - Extended Version initialization operator

AUTHOR

John Peacock <jpeacock@cpan.org>

SEE ALSO

the perl manpage.


vmsish - Perl pragma to control VMS-specific language features

NAME

vmsish - Perl pragma to control VMS-specific language features

SYNOPSIS

    use vmsish;

    use vmsish 'status';        # or '$?'
    use vmsish 'exit';
    use vmsish 'time';

    use vmsish 'hushed';
    no vmsish 'hushed';
    vmsish::hushed($hush);

    use vmsish;
    no vmsish 'time';

DESCRIPTION

If no import list is supplied, all possible VMS-specific features are assumed. Currently, there are four VMS-specific features available: 'status' (a.k.a '$?'), 'exit', 'time' and 'hushed'.

If you're not running VMS, this module does nothing.

vmsish status

This makes $? and system return the native VMS exit status instead of emulating the POSIX exit status.

vmsish exit

This makes exit 1 produce a successful exit (with status SS$_NORMAL), instead of emulating UNIX exit(), which considers exit 1 to indicate an error. As with the CRTL's exit() function, exit 0 is also mapped to an exit status of SS$_NORMAL, and any other argument to exit() is used directly as Perl's exit status.

vmsish time

This makes all times relative to the local time zone, instead of the default of Universal Time (a.k.a Greenwich Mean Time, or GMT).

vmsish hushed

This suppresses printing of VMS status messages to SYS$OUTPUT and SYS$ERROR if Perl terminates with an error status. and allows programs that are expecting "unix-style" Perl to avoid having to parse VMS error messages. It does not suppress any messages from Perl itself, just the messages generated by DCL after Perl exits. The DCL symbol $STATUS will still have the termination status, but with a high-order bit set:

EXAMPLE: $ perl -e"exit 44;" Non-hushed error exit %SYSTEM-F-ABORT, abort DCL message $ show sym $STATUS $STATUS == "%X0000002C"

    $ perl -e"use vmsish qw(hushed); exit 44;"      Hushed error exit
    $ show sym $STATUS
      $STATUS == "%X1000002C"

The 'hushed' flag has a global scope during compilation: the exit() or die() commands that are compiled after 'vmsish hushed' will be hushed when they are executed. Doing a "no vmsish 'hushed'" turns off the hushed flag.

The status of the hushed flag also affects output of VMS error messages from compilation errors. Again, you still get the Perl error message (and the code in $STATUS)

EXAMPLE: use vmsish 'hushed'; # turn on hushed flag use Carp; # Carp compiled hushed exit 44; # will be hushed croak('I die'); # will be hushed no vmsish 'hushed'; # turn off hushed flag exit 44; # will not be hushed croak('I die2'): # WILL be hushed, croak was compiled hushed

You can also control the 'hushed' flag at run-time, using the built-in routine vmsish::hushed(). Without argument, it returns the hushed status. Since vmsish::hushed is built-in, you do not need to "use vmsish" to call it.

EXAMPLE:
    if ($quiet_exit) {
        vmsish::hushed(1);
    }
    print "Sssshhhh...I'm hushed...\n" if vmsish::hushed();
    exit 44;

Note that an exit() or die() that is compiled 'hushed' because of "use vmsish" is not un-hushed by calling vmsish::hushed(0) at runtime.

The messages from error exits from inside the Perl core are generally more serious, and are not suppressed.

See Pragmatic Modules in the perlmod manpage.


warnings - Perl pragma to control optional warnings

NAME

warnings - Perl pragma to control optional warnings

SYNOPSIS

    use warnings;
    no warnings;

    use warnings "all";
    no warnings "all";

    use warnings::register;
    if (warnings::enabled()) {
        warnings::warn("some warning");
    }

    if (warnings::enabled("void")) {
        warnings::warn("void", "some warning");
    }

    if (warnings::enabled($object)) {
        warnings::warn($object, "some warning");
    }

    warnings::warnif("some warning");
    warnings::warnif("void", "some warning");
    warnings::warnif($object, "some warning");

DESCRIPTION

The warnings pragma is a replacement for the command line flag -w, but the pragma is limited to the enclosing block, while the flag is global. See the perllexwarn manpage for more information.

If no import list is supplied, all possible warnings are either enabled or disabled.

A number of functions are provided to assist module authors.

use warnings::register

Creates a new warnings category with the same name as the package where the call to the pragma is used.

warnings::enabled()

Use the warnings category with the same name as the current package.

Return TRUE if that warnings category is enabled in the calling module. Otherwise returns FALSE.

warnings::enabled($category)

Return TRUE if the warnings category, $category, is enabled in the calling module. Otherwise returns FALSE.

warnings::enabled($object)

Use the name of the class for the object reference, $object, as the warnings category.

Return TRUE if that warnings category is enabled in the first scope where the object is used. Otherwise returns FALSE.

warnings::warn($message)

Print $message to STDERR.

Use the warnings category with the same name as the current package.

If that warnings category has been set to "FATAL" in the calling module then die. Otherwise return.

warnings::warn($category, $message)

Print $message to STDERR.

If the warnings category, $category, has been set to "FATAL" in the calling module then die. Otherwise return.

warnings::warn($object, $message)

Print $message to STDERR.

Use the name of the class for the object reference, $object, as the warnings category.

If that warnings category has been set to "FATAL" in the scope where $object is first used then die. Otherwise return.

warnings::warnif($message)

Equivalent to:

    if (warnings::enabled())
      { warnings::warn($message) }
warnings::warnif($category, $message)

Equivalent to:

    if (warnings::enabled($category))
      { warnings::warn($category, $message) }
warnings::warnif($object, $message)

Equivalent to:

    if (warnings::enabled($object))
      { warnings::warn($object, $message) }

See Pragmatic Modules in the perlmodlib manpage and the perllexwarn manpage.


warnings::register - warnings import function

NAME

warnings::register - warnings import function

SYNOPSIS

    use warnings::register;

DESCRIPTION

Creates a warnings category with the same name as the current package.

See the warnings manpage and the perllexwarn manpage for more information on this module's usage.


Welcome to ActivePerl

Thank you for using ActivePerl, ActiveState's quality-assured binary build of Perl, available for AIX, Linux, Mac OS X, Solaris and Windows. As part of ActiveState's support for Perl, ActiveState provides the ActivePerl binary packages free to the community. ActivePerl includes:

  • Perl, the binary core distribution
  • The Perl Package Manager, for installing Perl extension modules
  • Complete documentation

The Windows version of ActivePerl also includes:

  • PerlScript, an ActiveX scripting engine, like JavaScript or VBScript, with a Perl brain
  • Perl for ISAPI, an IIS plug-in that runs Perl CGI scripts faster
  • PerlEz, for embedding Perl the easy way

Refer to the Release Notes for information about this version of ActivePerl.

ActiveState Products

ActiveState is the leading provider of technology solutions based on Perl and development tools for Perl programmers.

Solutions

  • ActivePerl Pro Studio, a complete package of Perl development tools and programming information.

Development Tools

  • Perl Dev Kit, the essential toolkit for building Perl applications for UNIX and Windows platforms.
  • Komodo, the cross-platform integrated development environment for open source languages.

Contact ActiveState

For installation-related support issues, contact support@ActiveState.com.

For general information and support, refer to the ActivePerl mailing list at http://aspn.ActiveState.com/ASPN/Mail/Browse/Threaded/ActivePerl.

To report a bug, or to view bugs fixed in this release, see the ActivePerl bug site, at http://bugs.ActiveState.com/ActivePerl.


ActivePerl 820 -- Release Notes

Welcome, and thank you for downloading ActivePerl. This release corresponds to Perl version 5.8.8.

The following platforms are supported by this release:

  • AIX 5.1 or later (rs6000)

  • Linux: glibc 2.2 or later (x86)

    Linux: glibc 2.3 or later (x64)

  • Mac OS X 10.3 "Panther" or later (x86 or powerpc)

  • Solaris 2.6 or later (sparc, 32 and 64 bit)

    Solaris 10 or later (x86)

  • Windows 9x, Me, NT, 2000 (x86)

    Windows XP and 2003 (x86 and x64)

For a chronological list of changes included in this and past releases, see the ActivePerl 5.8 Change Log.

Incompatibilities

Perl 5.8 is not binary compatible with Perl 5.6. In particular, do not attempt to use extensions or PPM packages built for ActivePerl 600 series builds with ActivePerl 800 series builds and vice versa. Please check Incompatible Changes in the perl58delta manpage for known source level incompatibilities between the Perl 5.8 releases and the earlier releases in the Perl 5.6 series.

You may also want to check Incompatible Changes in the perl581delta manpage, Incompatible Changes in the perl582delta manpage, and Incompatible Changes in the perl584delta manpage, for additional minor incompatible changes made in Perl 5.8.1, Perl 5.8.2 and Perl 5.8.4 respectively.

The order of the directories in @INC has changed since build 817 of ActivePerl. The $PREFIX/site/lib directory is now searched for modules before $PREFIX/lib. This means that core modules might be shadowed by what is installed locally and these updates might bring incompatibilities that break applications only tested against the original core module.

All modules that ActivePerl bundles in addition to the core modules are now installed in $PREFIX/lib. In ActivePerl build 817 and earlier, these were installed in $PREFIX/site/lib.

The $Config{siteprefix} is now $PREFIX/site. In ActivePerl build 817 and earlier, it was just $PREFIX and $Config{sitelib} compensated by introducing the site level. As a consequence programs included with packages installed into the site area now get installed in $PREFIX/site/bin. In ActivePerl build 817 and earlier, these were installed in $PREFIX/bin. Another consequence of the $Config{siteprefix} update is that modules configured and built with perl Makefile.PL PREFIX=... are now installed directly in the lib directory of the given PREFIX.

PPM version 4

PPM version 4 differs from version 3 (distributed with ActivePerl build 817 and earlier) in the following ways:

  • Running ppm without arguments now bring up a graphical user interface; there is no more console shell.

  • The output format of most commands have changed. Scripts that parse the output of ppm need to change.

  • ppm describe only takes a number as argument. The other forms are not supported.

  • ppm install without argument does not install a default package and does not support the range argument. The --follow and --no-follow options are not supported.

  • ppm profile, ppm properties, ppm set, and ppm target commands are not supported.

  • ppm repo up and ppm repo down commands are not supported.

  • ppm search does not support the field=glob syntax.

  • SOAP-based repositories are no longer supported.

Known Issues

PPM

There are some known outstanding issues with the PPM 4 client:

  • The PPM state database (containing configuration information for repositories, view options in the GUI, and repository state) is not imported from previous installations.

    If you have added custom PPM 4 repositories with ActivePerl 5.8.8.819, you should reconfigure them manually with ppm repo add ... or in the GUI. The repository state will be automatically re-synchronized when PPM is run.

  • Packages using post install scripts can't be installed from the GUI. The workaround is to use the command line version of ppm to install these packages.

  • The "Upgradable View" shows packages that would downgrade the installation. PPM will warn you if select a package for installation which would downgrade the currently installed version.

  • List icons will sometimes not repaint properly after scrolling under X11. This does not affect the Windows and Mac OS X builds.

  • Running sudo ppm ... the first time ppm is invoked from a regular user account on Unix will create a root owned state database. This effectively makes the database read-only when running ppm without sudo, and might manifest itself as Application Error dialogs when running the GUI. Workaround is to run sudo chown -R $USER ~/.ActivePerl once to fix up ownership of the state database.

  • Sync of repository state might be slow. (#45830)

  • No PPM GUI for the 64 bit versions of ActivePerl.

If you find other issues with the new PPM client, please report them at http://bugs.ActiveState.com/ActivePerl/.

AIX

The following issues are know to exists when installing ActivePerl on AIX:

  • The reloc_perl script does not correctly update the perl-dynamic executable. The workaround is to install directly from the tarball into the new location.

Linux and Solaris

The following issues are know to exists when installing ActivePerl on Unix:

  • Some versions of tar on Solaris have bugs that prevent proper extraction of files in a package that has long path names. Most other versions of tar on Solaris use a different method than GNU tar to encode pathnames longer than 100 characters. GNU tar is therefore required to extract the package into the file system correctly. A precompiled version of GNU tar for the sparc platform is available from:

        http://www.sunfreeware.com/

    You can also get the source package for GNU tar from:

        http://www.gnu.org/

  • The suidperl executable is not included in this package due to potential security issues. If you wish to use suidperl in your installation, we recommend building Perl from source. The source code for ActivePerl is available at:

        http://www.ActiveState.com

Mac OS X

  • Perl library paths, and thus PPM Areas, defined in the shell by the PERL5LIB environment variable are not available to PPM when it is launched by clicking the PPM icon in OS X. To to make this variable available in the OS X GUI, add an entry similar to the following to ~/.MacOSX/environment.plist:

     <key>PERL5LIB</key>
 <string>/path/to/perl/lib</string>

  • Running sudo ppm or sudo ppm gui does not start up the GUI with root privileges. Use ppm as a command line tool with sudo.

  • On version 10.3 or earlier, running ppm without arguments from a remote console (e.g. via ssh) causes a core dump as it attempts to launch the PPM GUI instead of providing an informative "ppm gui failed" error.

Windows

The following issues are know to exists when installing ActivePerl on Windows:

  • The installer cannot create IIS script mappings on Windows Vista.

  • The fork() emulation has known limitations. See the perlfork manpage for a detailed summary. In particular, fork() emulation will not work correctly with extensions that are either not thread-safe, or maintain internal state that cannot be cloned in the pseudo-child process. This caveat currently applies to extensions such as Tk and Storable.

  • It seems that some people are having problems with the ActivePerl MSI installer. The first thing to note is that you CANNOT install ActivePerl 5.8 over an older version of ActivePerl based on 5.6 or 5.005, such as build 633 or any other 600 or 500 series build. We have determined that some of these problems are due to other installations of Perl that may be pointed at by something in the environment.

    The sure-fire solution is to make absolutely certain that no other installations of Perl are on the target machine. Realizing that this is not always possible, you can follow these steps to ensure the other installations will not interfere.

    1. Stop the "Windows Installer" service. This can be accomplished from the command prompt using the following command:

          c:\> net stop "Windows Installer"

    2. Temporarily remove or rename PERLLIB and PERL5LIB environment variables in the system environment.

    3. Temporarily remove or rename the following registry values:

          [\\HKEY_LOCAL_MACHINE\Software\Perl] lib = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] lib-<PerlVersion> = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib-<PerlVersion> = <directory>(REG_SV)

    4. Proceed with the installation.

    Once the installation has completed successfully, the above actions may be undone although restoring the environment variables or the registry values may interfere with the proper operation of your new ActivePerl installation. In order to perform all of the above steps, you will need to have Administrative privileges on the target machine. If you do not have the required privileges you should contact you Administrator.

    The following Microsoft knowledge base articles may be helpful in solving MSI problems:

    Q236597 - OFF2000: Error Message: The Installation Package Could Not Be Opened ...

    http://support.microsoft.com/support/kb/articles/Q236/5/97.ASP

    • Q224094 - OFF2000: Error Message: This Application Requires the Windows Installer to Run

    http://support.microsoft.com/support/kb/articles/Q224/0/94.ASP

    Q247532 - Works 2000 Err Msg: Installer Terminated Prematurely

    http://support.microsoft.com/support/kb/articles/Q247/5/32.ASP

    "Error 1303. The installer has insufficient privileges..." Running Office Setup

    http://support.microsoft.com/support/kb/articles/Q228/6/58.ASP

    Error Message: Error 1316 Running Setup for Admin Installation

    http://support.microsoft.com/support/kb/articles/Q228/5/92.ASP

    Error 1327 Invalid Drive During Office Installation

    http://support.microsoft.com/support/kb/articles/Q217/6/66.ASP

  • On Windows 9x, the system must be rebooted for the PATH environment variable to take effect.

  • On Windows 9x, the PATH environment variable settings are not removed after an uninstall.

Further Information

The Perl distribution comes with extensive documentation. On Unix platforms, all the standard documentation is installed as man pages under the Perl install location. The location of the man pages may need to be added to the MANPATH environment variable in order to access them. For example, in the C shell:

    % setenv MANPATH /opt/ActivePerl-5.8/man:$MANPATH

The documentation is installed in HTML format on all platforms. If ActivePerl was installed in /opt/ActivePerl-5.8 then the HTML documentation would be located in /opt/ActivePerl-5.8/html.

On Windows, the standard documentation along with Windows-specific Perl documentation is installed in HTML format, and is accessible from the "Start" menu.

Updated versions of the HTML documentation will always be available at the ActiveState website:

    http://www.ActiveState.com/ActivePerl/

Reporting Problems

Please report any problems you encounter with this release at the following location:

    http://bugs.ActiveState.com/ActivePerl/

If you do not have web access, reports can be also sent via email to ActivePerl-Bugs@ActiveState.com. Please be sure to include detailed information about the platform in your message.

As far as possible, please ensure that there is enough information in the report to reproduce the bug elsewhere. It also helps to submit a minimal test case that exhibits the bug.


ActivePerl 5.8.8.820 -- Installation Guide

Installing ActivePerl 5.8.8.820

  • Selecting the Appropriate Version of ActivePerl

  • Installing ActivePerl on Windows (x86)
    • Windows Prerequisites
    • Upgrading from ActivePerl 5.6.x
    • Upgrading from ActivePerl 5.8.x
    • Windows Installers
    • Windows Configuration
    • Uninstalling ActivePerl on Windows
  • Installing ActivePerl on Mac OS X (x86, powerpc)
    • OS X Prerequisites
    • OS X Installer
    • OS X Configuration
    • Uninstalling ActivePerl on OS X
  • Installing ActivePerl on Linux (x86)
    • Linux Prerequisites
    • Linux Installers
    • Linux Configuration
    • Uninstalling ActivePerl on Linux
  • Installing ActivePerl on Solaris (sparc, x86)
    • Solaris Prerequisites
    • Solaris Installers
    • Solaris Configuration
    • Uninstalling ActivePerl on Solaris
  • Installing ActivePerl on AIX (rs6000)
    • AIX Prerequisites
    • AIX Installers
    • AIX Configuration
    • Uninstalling ActivePerl on AIX
  • Installing ActivePerl on HP-UX (pa-risc, ia64)

Welcome, and thank you for choosing ActivePerl.

Note: The first three numbers of an ActivePerl release correspond to the core Perl version. The fourth number is the ActivePerl build number, which may be followed by a fifth number that specifies a modified build for ActivePerl Enterprise Edition. For example, this release of ActivePerl is 5.8.8.820, which corresponds to Perl 5.8.8.

Please note that ActivePerl 800 series builds are NOT binary-compatible with the older 600 and 500 series builds. In particular, do not attempt to use extensions or PPM packages built for the 500 and 600 series builds with ActivePerl 800 series builds and vice versa.

Binaries for the following platforms are available:

  • AIX rs6000 for AIX 5.1 or later
  • Linux x86 for Red Hat 6.2 or later
  • Linux x86 for Debian 2.2 or later
  • Mac powerpc for Mac OS X 10.3 or later
  • Mac x86 for Mac OS X 10.4 or later
  • SunOS sparc for Solaris 2.6 or later
  • SunOS x86 for Solaris 10 or later
  • Windows x86 for Windows 9x, NT, Me, 2000, 2003 and XP

Binaries of ActivePerl for HP-UX are available from HP:

  • https://payment.ecommerce.hp.com/portal/swdepot/try.do?productNumber=PERL

Selecting the Appropriate Version of ActivePerl

There are currently two versions of ActivePerl that are supported. The most significant differences between the two versions are that:

ActivePerl 5.6.x, build 6xx

  • is smaller
  • may be faster
  • has a broken threading model
  • does not have unicode support

ActivePerl 5.8.x, build 8xx:

  • is larger
  • may be slower
  • has a working threading model
  • has unicode support

ActivePerl 5.6.x is generally better for web hosting purposes and high performance applications; however, ActiveState does not intend to continue releasing builds of Perl 5.6.x, unless a major security vulnerability is discovered.

ActivePerl 5.8.x is recommended for most Perl scripting needs. It has better support for more recent developments such as XML, and the bundled modules are much more up to date.

For more information, please refer to the release notes for latest release of each version:

  • For ActivePerl 5.6.x, see:
    http://aspn.activestate.com/ASPN/docs/ActivePerl-5.6/RELEASE.html
  • For ActivePerl 5.8.x, see:
    http://aspn.activestate.com/ASPN/docs/ActivePerl/release.html

Installing ActivePerl on Windows (x86)

Windows Prerequisites

  • Hardware: 90 MB hard disk space for typical install
  • Perl for ISAPI: requires an ISAPI-compatible web server, such as IIS 4.0 or greater, or PWS 4.0 or greater
  • PerlScript: requires an ActiveX scripting host such as Internet Explorer 4.0 or greater or Windows Scripting Host
  • Perl Environment Variables: if Perl environment variables such as PERLLIB, PERL5LIB or PERL5OPT have been set on your system, you should unset them before installing ActivePerl. Otherwise, these variables may cause incompatible versions of Perl modules to be used during the installation process.
  • System Account: (MSI Installer only) Do not launch the installation package from a directory for which the "System" account does not have read permission. If you do, the Windows Installer Service will not be able to access the MSI file in order to perform the installation. You may get an error message to this effect, or it may fail mysteriously.
  • Administrative Privileges: On Windows NT/2000/XP/2003 systems ActivePerl installations must be performed by a privileged user only. If you install ActivePerl without full administrator privileges, the following problems occur:
    • Environment variables are set only for the current user
    • PerlScript file associations are not created
    • The PerlScript feature will be unavailable
    • Registry entries are created under HKEY_CURRENT_USER and not under HKEY_LOCAL_MACHINE
    • IIS script mappings are not set
    • ActivePerl applications will not write messages to the event log
    • ActivePerl only appears in the Add/Remove Programs list for the current user
  • Internet Explorer: Ensure that you have at least IE 6. If necessary, get an update from:
    http://windowsupdate.microsoft.com
  • Windows XP / Windows 2003 Server: no additional requirements
  • Windows 2000
    • (MSI Installer only) Microsoft Windows Installer 2.0 or greater, available from: http://downloads.ActiveState.com/contrib/Microsoft/MSI2.0/NT/InstMsiW.exe
  • Windows Me
    • (MSI Installer only) Microsoft Windows Installer 2.0 or greater, available from: http://downloads.ActiveState.com/contrib/Microsoft/MSI2.0/9x/InstMsiA.exe
  • Windows NT
    • Service Pack 5 or greater
    • (MSI Installer only) Microsoft Windows Installer 2.0 or greater, available from: http://downloads.ActiveState.com/contrib/Microsoft/MSI2.0/NT/InstMsiW.exe
    • (for the ActiveX Scripting Engine) Internet Explorer 5 or greater, available from: http://windowsupdate.microsoft.com
  • Windows 9x
    • (MSI Installer only) Microsoft Windows Installer 2.0 or greater, available from: http://downloads.ActiveState.com/contrib/Microsoft/MSI2.0/9x/InstMsiA.exe
    • (for the ActiveX Scripting Engine) Internet Explorer 5 or greater available from: http://windowsupdate.microsoft.com
    • (for the ActiveX Scripting Engine) DCOM for Windows 9x, available from: http://www.microsoft.com/com/default.mspx

Upgrading from ActivePerl 5.6.x

Upgrading from ActivePerl version 5.6 requires that you delete the old version of ActivePerl, and then install the 5.8.x version. This means that any additional packages that were installed using PPM must be manually reinstalled after the ActivePerl 5.8.x installation, so creating a list of these packages is an important first step.

To upgrade from ActivePerl 5.6.x:

  1. Generate a list of modules using the following command (changed as required to suit your system):
        dir /b c:\perl\site\lib\ppm-conf\*.ppd > c:\ppm_modules.txt
  2. Uninstall the old version of ActivePerl.
  3. Manually delete the Perl directory (by default, c:\perl).
  4. Reboot.
  5. Install ActivePerl 5.8.x using the downloaded installer from:
    http://activestate.com/Products/Download/Download.plex?id=ActivePerl
  6. Use the version of PPM that was installed as part of the ActivePerl 5.8 installation to re-install the modules listed in ppm_modules.txt.

Upgrading from ActivePerl 5.8.x

If you have installed modules using the PPM included with earlier versions of ActivePerl 5.8, use the following steps to upgrade ActivePerl. PPM modules can only be migrated to later ActivePerl builds if you installed ActivePerl using the MSI Installer.

  1. Use Window's Add / Remove Programs applet (accessible from the Control Panel) to uninstall ActivePerl.
  2. Manually delete all directories beneath the Perl installation directory (by default C:\Perl) except the site\lib directory.
  3. Install ActivePerl to the same directory (i.e., C:\Perl).
  4. Use the ppm upgrade command to check for module updates.

If your site\lib has been created with ActivePerl 817 or earlier, then you need to completely remove the whole directory tree, do a clean installation, and reinstall your modules with PPM. This is necessary because in ActivePerl 818 the order of lib and site\lib in @INC has been reversed, and all bundled modules now reside in the lib directory. Having older versions of these bundled modules in site\lib at the front of @INC results in a broken installation.

Alternatively, you can use PPM-Profile to help save and restore your locally installed PPM packages. PPM-Profile is available through PPM and allows you to save a profile of all the PPM packages you have installed. For example, to save a profile before you upgrade, you can type:

  ppm install PPM-Profile
  ppmprofile save C:\profile.xml

Once you have saved this profile, you can proceed with the upgrade as explained above. Once done, you can use the profile you saved to reinstall the same set of PPM packages in your new installation by typing (add the --verbose flag for more details on what is being installed) :

  ppm install PPM-Profile
  ppmprofile restore C:\profile.xml

Windows Installers

If you are using ActivePerl to serve CGI / ASP scripts using IIS or another Web server, stop the Web server before installing ActivePerl.

MSI Installer Package
To install the MSI package double-click on the MSI file in Windows Explorer.

Do not install over a 500 or 600 series build of ActivePerl. This package must be installed into a separate directory.

MSI Package Installation from the Command Line
You can install ActivePerl from the command line using the 'msiexec' program. For example:
    msiexec /i msi_file.msi

The ADDLOCAL command line property is used to specify which features should be installed. (If ADDLOCAL is not specified, all features are installed.) For example:

    msiexec /i msi_file.msi ADDLOCAL="PERL_FEATURE,PERLIS"

The following features may be specified with the ADDLOCAL switch:

  • PERL_FEATURE (the Perl core)
  • PPM (the Programmer's Package Manager)
  • PERLIS (the Perl for ISAPI interpreter)
  • PERLSE (the Perl ActiveX Scripting Engine)
  • EXAMPLES (some simple examples)
  • DOCUMENTATION (the ActivePerl documentation)

A set of command-line properties can be used to configure the installation. For example:

    msiexec /i msi_file.msi TARGETDIR="c:\perl" PERL_PATH="Yes"
  • TARGETDIR: Used to specify the absolute path where ActivePerl will be installed. If not specified, ActivePerl will be installed in a default location on the same drive as the Windows operating system. If this option is used, a value is required.
    Note: Ensure that the NT 'SYSTEM' user account that actually runs the MSI installer has full access to the target directory.
    Also, don't select a directory with spaces in its name. Perl will likely work, but many scripts will not.
  • PL_IISMAP: If this option is set to 'Yes', the installer will create a global IIS script mapping for '.pl' and Perl. By default, the installation does not create the script mapping.
  • PLX_IISMAP: If this option is set to 'Yes', the installer will create a global IIS script mapping for '.plx' and PerlIS. By default, the installation does not create the script mapping.
  • PERL_PATH: If this option is set to 'Yes', the Perl/bin directory will be added to the system PATH environment variable. By default, the directory is not added to the path.

The following command-line switches can be used:

Silent Mode
To run in silent mode, specify the '/q' command line option. The installer will run with no UI.
Logging
To log the installation process, specify the '/l' command line option and the name of the log file. For example:
    msiexec /i msi_file.msi /l log.txt

To enable verbose logging, use the *v modifier with the /l command line option. For example:

    msiexec /i msi_file.msi /l*v log.txt
AS Installer Package
The AS package is a generic installation package that can be used on systems where the MSI package is not supported. The AS package provides no uninstall functionality. To install using the AS package, double-click the installer file and follow the prompts.

Windows Configuration

If you run Perl at the command prompt, the script will be executed by the first Perl.exe it encounters in the list of paths in the PATH environment variable. To ensure the script is executed by the Perl interpreter of your choice, specify the complete path to the Perl.exe you want to use. (Typing perl -v at the command prompt will tell you which version of Perl is currently first in your PATH)

Installing ActivePerl will change your Path environment variable and may change registry settings, such as file associations, which may affect your Web server. If you want to use a previously installed copy of Perl, you will need to modify these settings.

    ftype PerlScript=perl.exe %1 %*
    assoc .pl=PerlScript
Windows 9x/Me
Piping doesn't work properly on older operating systems, such as Windows 9x/Me. Add the following patch to config.pm:
    797 otherlibdirs=''
    798 package='perl5'
    799 # pager='more /e' NOTE: The " /e" does not work on WIN9x systems
    800 pager='more'
    801 passcat=''

Uninstalling ActivePerl on Windows

MSI Package
If you installed ActivePerl using the MSI installer, uninstall using the Windows Add / Remove Programs applet.
AS Package
If you installed ActivePerl using the AS installer, uninstall by deleting the directory in which ActivePerl was installed.
Manual Uninstall
If you must uninstall ActivePerl manually, delete the Perl directory, including all sub-directories, and the following registry entries:
  1. HKEY_LOCAL_MACHINE/Software/ActiveState/ActivePerl
  2. HKEY_LOCAL_MACHINE/Software/ActiveState/PerlScript
  3. HKEY_LOCAL_MACHINE/Software/Microsoft/Windows/CurrentVersion/Uninstall/ActivePerl

Installing ActivePerl on Mac OS X (x86, powerpc)

OS X Prerequisites

  • Hardware: 90 MB hard disk space for typical install
  • Operating System: OS X 10.3 "Panther" or later
  • Software: X11 - for use of ActivePerl's bundled Tk modules (optional)

OS X Installer

Installing the OS X Package

ActivePerl is distributed on Mac OS X as a disk image (.dmg file). The disk image contains an installer package (.pkg bundle) that installs ActivePerl.

  • Download the ActivePerl disk image (ActivePerl-<version>-<platform>.dmg).
  • If the browser does not automatically mount the disk image and open the mounted folder in Finder, double-click ActivePerl-<version>-<platform>.dmg to do so.
  • Double-click the ActivePerl installer package (ActivePerl-<version>.pkg) to start the installation.
  • Follow the Installer prompts. The installer will ask for administrative authentication if the current user does not have administrative priviledges.
  • After installation is complete, you may eject the ActivePerl disk image and move ActivePerl-version.dmg to the Trash.

OS X includes a non-interactive command line interface to Apple's Installer. To install the ActivePerl Apple installer from the command line:

    $ sudo installer -pkg /Users/<username>/ActivePerl-<version>.pkg -target /

More information on the command line interface to Installer can be found in its man page.

OS X Configuration

The Apple Installer package installs ActivePerl in /usr/local/ActivePerl-5.8. To run the perl interpreter and PPM package manager (without having to enter the full path), add /usr/local/ActivePerl-5.8/bin to your PATH environment variable. For example:

    $ export PATH=/usr/local/ActivePerl-5.8/bin:$PATH
    $ export PATH=/usr/local/ActivePerl-5.8/site/bin:$PATH

To permanently add the directory to your PATH, add it to the .profile or .bash_profile file in the user's home directory. For example:

    PATH=/usr/local/ActivePerl-5.8/bin:$PATH
    PATH=/usr/local/ActivePerl-5.8/site/bin:$PATH
    export PATH

Alternatively, symbolic links to the binaries can be created in any bin directory currently in the PATH. For example:

    PATH=/Users/<username>/bin:$PATH

    $ ln -s /usr/local/ActivePerl-5.8/bin/perl /Users/<username>/bin/perl
    $ ln -s /usr/local/ActivePerl-5.8/bin/ppm /Users/<username>/bin/ppm

Uninstalling ActivePerl on OS X

To uninstall ActivePerl, run the uninstall script:

    $ /Library/Receipts/ActivePerl-5.8.pkg/Contents/Resources/uninstall

Removing ActivePerl will also remove perl modules manually installed using PPM.

If neccessary, remove any symbolic links created during configuration. For example:

    $ rm /Users/<username>/bin/perl

Linux Prerequisites

  • Hardware: 90 MB hard disk space for typical install
  • Operating System: Red Hat 6.2 or later, Debian 2.2 or later
  • Online Help: Web browser

Installing ActivePerl on Linux (x86)

Linux Installers

RPM Package for Red Hat 6.2 or later
The Red Hat compatible package is in RPM format. This should be installed as root, using the following command:
    % rpm -i ActivePerl-5.8.8.820-i686-linux.rpm

This will install ActivePerl into /opt/ActivePerl-5.8.

To uninstall ActivePerl, run:

    % rpm -e ActivePerl

The RPM package has only been tested with Red Hat 6.2, but is expected to be compatible with other Red Hat 6.2 compatible installations as well.

Note: Previous versions of ActivePerl were installed in /usr/local. Upgrading using rpm will not remove modules and documentation subsequently added using PPM or the CPAN shell, nor will it move them to the new location in /opt. These modules must be reinstalled after the upgrade. The old ActivePerl directory in /usr/local can be removed.

Dpkg Package for Debian 2.2 or later
The Debian-compatible package is in dpkg format. This should be installed as root, using the following command:
    % dpkg -i ActivePerl-5.8.8.820-i686-linux.deb

This will install ActivePerl into /opt/ActivePerl-5.8.

To uninstall ActivePerl, run:

    % dpkg -r ActivePerl

The Debian package has only been tested with Debian 2.2, but is expected to be compatible with other Debian 2.2 compatible installations as well.

Generic AS Package for Linux
The generic installer allows installation as an unprivileged user into a user-specified path. GNU tar is required for extracting the files. See Known Issues in the ActivePerl Release Notes for details.

Download the distribution to a temporary directory, extract the files, chdir to the ActivePerl directory and then run the script install.sh. The installation script will prompt you for the target installation directory.

    % tar zxf ActivePerl-5.8.8.820-i686-linux.tar.gz
    % cd ActivePerl-5.8.8.820
    % ./install.sh

If you share the system with other people, or if you do not have root access, it is recommended that you install ActivePerl in your own user directory. For example:

    /home/<username>/ActivePerl-5.8

We suggest adding the following line to your .bash_profile file:

    PATH=$PATH:/home/<username>/bin

Also, we suggest that you create symbolic links to the binaries:

    ln -s /home/<username>/ActivePerl-5.8/bin/perl /home/<username>/bin/perl
    ln -s /home/<username>/ActivePerl-5.8/bin/ppm /home/<username>/bin/ppm

This will allow you to call ActivePerl with a command like:

    perl -le "Hello World!;"

Linux Configuration

The Red Hat and Debian packages are installed into the /opt/ActivePerl-5.8 directory. Add the /opt/ActivePerl-5.8/bin directory to your PATH environment variable to conveniently access it. For example, in the C shell:

    % setenv PATH /opt/ActivePerl-5.8/bin:$PATH

The ActivePerl Generic installer allows you to install the package anywhere that the user has write permission. Add the bin directory to your PATH environment variable to conveniently access it. For example, in the C shell (assuming you installed into /home/<username>/ActivePerl-5.8):

    % setenv PATH /home/<username>/ActivePerl-5.8/bin:$PATH

Uninstalling ActivePerl on Linux

Debian Package
If you installed ActivePerl using the dpkg format installer, uninstall as follows:
    dpkg -r ActivePerl
RPM Package
If you installed ActivePerl using the RPM format installer, uninstall as follows:
    rpm -e ActivePerl
AS Package
If you installed ActivePerl using the AS format installer, remove the directory into which ActivePerl was installed. For example:
    /bin/rm -rf /opt/ActivePerl-5.8

Installing ActivePerl on Solaris (sparc, x86)

Solaris Prerequisites

  • Hardware: 90 MB hard disk space for typical install
  • Operating System: Solaris 2.6 or later for sparc, Solaris 10 or later for x86
  • Online Help: Web browser

Solaris Installers

PKGADD Package
The Solaris package is in pkgadd format. This should be installed as root, using the following commands:
    % gunzip ActivePerl-5.8.8.820-sun4-solaris.pkg.gz
    % pkgadd -d ActivePerl-5.8.8.820-sun4-solaris.pkg

This will install ActivePerl into /opt/ActivePerl-5.8.

To uninstall ActivePerl, run:

    % pkgrm ASperl

This package has only been tested with Solaris 2.6, but is expected to be compatible with other Solaris 2.6 compatible installations as well, including Solaris 7 and Solaris 8.

Generic AS Package for Solaris
The Generic Installer allows installation as an unprivileged user, and into a user-specified path. GNU tar is required for extracting the files. See Known Issues in the ActivePerl Release Notes for details.

Download the distribution to a temporary directory, extract the files, chdir to the ActivePerl directory and then run the script install.sh. The installation script will prompt you for the target installation directory.

    % tar zxf ActivePerl-5.8.8.820-sun4-solaris.tar.gz
    % cd ActivePerl-5.8.8.820
    % ./install.sh

Solaris Configuration

The Solaris package is installed into the /opt/ActivePerl-5.8 directory. Add the /opt/ActivePerl-5.8/bin directory to your PATH environment variable to conveniently access it. For example, in the C shell:

    % setenv PATH /opt/ActivePerl-5.8/bin:$PATH

The ActivePerl Generic installer allows you to install the package anywhere that the user has write permission. Add the bin directory to your PATH environment variable to conveniently access it. For example, in the C shell (assuming you installed into /home/<username>/ActivePerl-5.8):

    % setenv PATH /home/<username>/ActivePerl-5.8/bin:$PATH

Uninstalling ActivePerl on Solaris

PKGADD Package
If you installed ActivePerl using the PKGADD format installer, uninstall as follows:
    pkgrm -d ASperl
AS Package
If you installed ActivePerl using the AS format installer, remove the directory into which ActivePerl was installed. For example:
    /bin/rm -rf /opt/ActivePerl-5.8

Installing ActivePerl on AIX (rs6000)

AIX Prerequisites

  • Hardware: 90 MB hard disk space for typical install
  • Operating System: AIX 5.1

AIX Installers

Generic AS Package for AIX
ActivePerl is distributed on AIX as a gzipped tarball containing an installer. GNU tar is required for extracting the files (see Known Issues in the ActivePerl Release Notes for details).

Download the distribution to a temporary directory, extract the files, chdir to the ActivePerl directory and run the script install.sh.

    $ tar zxf ActivePerl-5.8.8.820-aix-5.1-<seq>.tar.gz
    $ cd ActivePerl-5.8.8.820
    $ ./install.sh

The installation script will prompt you for a target installation directory. If you share the system with other people, or if you do not have root access, you may install ActivePerl in your own user directory. For example:

    /home/<username>/ActivePerl-5.8

AIX Configuration

We suggest adding the bin directory of the ActivePerl installation to your .profile file. For example:

    PATH=$PATH:/home/<username>/ActivePerl-5.8/bin

Alternatively, create symbolic links to the binaries in a directory already in your path. For example:

    $ ln -s /home/<username>/ActivePerl-5.8/bin/perl /home/<username>/bin/perl
    $ ln -s /home/<username>/ActivePerl-5.8/bin/ppm /home/<username>/bin/ppm

Uninstalling ActivePerl on AIX

To uninstall ActivePerl, remove the directory ActivePerl was installed in. For example:

    $ rm -rf /opt/ActivePerl-5.8

If neccessary, remove any symbolic links created during configuration. For example:

    $ rm /Users/<username>/bin/perl

Installing ActivePerl on HP-UX (pa-risc, ia64)

Installation instructions for ActivePerl on HP-UX are available from the HP website:

  • http://h21007.www2.hp.com/dspp/tech/tech_TechDocumentDetailPage_IDX/1,1701,5672,00.html#install


Using PPM

  • What is PPM?
    • Setup
  • The PPM GUI
  • The PPM Command Line
  • Finding, Installing, Removing and Upgrading Packages
    • Find a package.
    • Install a package.
    • Remove a package.
    • Upgrade a package.
  • PPM Preferences
    • Areas
    • Repositories
      • Default Repository
      • Additional Repositories
      • Additional Resources
  • Additional Information
    • Creating an Install Area
    • Using Zip Files
    • Unavailable Packages
    • A Perl Module Disclaimer
    • Creating PPM packages
    • PPM, Proxies and Firewalls
      • The http_proxy Environment Variable
      • Setting http_proxy
    • Using the CPAN shell

What is PPM?

PPM is the package management utility for ActivePerl. It simplifies the task of locating, installing, upgrading and removing Perl packages. The PPM client accesses PPM repositories (collections of packages) on the internet or on a local network. It is also used to update previously installed packages with the latest versions and to remove unused packages from your system.

Setup

PPM is installed automatically with ActivePerl.

To use PPM, your computer must be connected to the internet, have access to a PPM repository on a local hard drive or network share, or have access to a mounted ActiveState ActiveCD.

If you connect to the internet via firewall or proxy, you may need to set the http_proxy environment variable. See PPM, Proxies and Firewalls for more information.

The PPM GUI

To launch PPM's graphical user interface, run ppm without any command line arguments:

  ppm

The interface should look something like this:

When launched, PPM automatically synchronizes its local database with the installed perl packages (including those installed manually or via the CPAN shell). The interface is temporarily locked while this synchronization takes place.

Hovering the mouse pointer over icons in the toolbar displays tool tips describing what each button does. These buttons are:

  • All packages: Displays all packages installed locally and available in the repository.
  • Installed packages: Displays all installed packages.
  • Upgradable packages: Displays packages for which an upgrade is available from the repository.
  • Packages to install/remove: Displays packages marked for installation or removal.
  • Mark for install: Marks the selected packages for installation or upgrade.
  • Mark for remove: Marks the selected packages for removal.
  • Run marked actions: Runs all marked actions (i.e. install, upgrade, remove)
  • Refresh all data: Refreshes the list view.
  • PPM Preferences: Opens the PPM Preferences dialog box.

Use the Filter text field to limit the packages displayed in the Package List pane to those matching the text entered (case insensitive substring match).

Click the magnifying glass icon to select which package meta-data to match against:

  • Name
  • Abstract
  • Name or Abstract (default)
  • Author

The Package List pane can display the following columns of package information:

  • Package Name: The name of the package.
  • Area: Where the package is installed. See install areas below.
  • Installed: Version number of the installed package.
  • Available: Version number of the package in the repository.
  • Abstract: A short description of the package.
  • Author: Name and email address of the package's author.

The Status tab displays messages about the current status of the PPM client, marked actions, and information about the actions being run.

The Details tab displays package information and, for installed packages, a list of all installed files.

The PPM Command Line

All PPM operations and configuration can also be performed at the command line. See the ppm man page or 'ppm help' for more information.

Finding, Installing, Removing and Upgrading Packages

Find a package.

To find a package in the repository:

  • Click the All packages button,
  • Enter text from the package's name or abstract in the Filter field

As text is entered in the Filter field, the list of packages is automatically updated as the substring match becomes more precise. Click the magnifying glass icon to filter on different meta-data (e.g. Author).

Alternatively, just start typing the name of the package. The Package List will highlight the first package that matches the string you have typed.

Install a package.

To install a package from the repository:

  • Click on the desired package in the Package List to select it.
  • Mark the package by:
    • Clicking the Mark for install button or,
    • Hitting the "+" key or,
    • Selecting Install <package-name> from the Action menu or,
    • Right-clicking the selection and choosing Install <package-name> from the context menu.
  • Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

Remove a package.

To remove a package from your local perl installation:

  • Click on the Installed package in the Package List to select it. You may want to use the Installed packages button to filter the list.
  • Mark the package by:
    • Clicking the Mark for remove button or,
    • Hitting the "-" key or,
    • Selecting Remove <package-name> from the Action menu or,
    • Right-clicking the selection and choosing Remove <package-name> from the context menu.
  • Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

Upgrade a package.

To upgrade a package to the most recent version available in the repository:

  • Click on the desired package in the Package List to select it. You may want to use the Upgradable packages button to filter the list.
  • Mark the package by:
    • Clicking the Mark for install button or,
    • Hitting the "+" key or,
    • Selecting Install <package-name> from the Action menu or,
    • Right-clicking the selection and choosing Install <package-name> from the context menu.
  • Click the Run marked actions button or select Run Marked Actions (Ctrl-Enter) from the File menu.

PPM Preferences

Installation Areas can be selected and Repositories configured by clicking the PPM Preferences button or selecting Preferences from the Edit menu.

Areas

PPM allows for the addition of new install areas, which is useful for shared ActivePerl installations where the user does not have write permissions for the site and perl areas. New install areas are added by simply setting up new library directories for perl to search, and PPM will set up install areas to match. The easiest way to add library directories for perl is to specify them in the PERL5LIB environment variable, see the perlrun manpage for details. PPM will create etc, bin, html directories as needed when installing packages. If the last segment of the library directory path is lib then the other directories will be created as siblings of the lib directory, otherwise they will be subdirectories.

Repositories

The Repositories tab lists the repositories that PPM is currently configured to use and allows you to add additional ones. Simple PPM repositories are just a directory containing ppm packages. You can create your own by putting packages in an HTTP, FTP directory or a locally accessible mount or filesystem directory.

To add a repository fill out the fields in the Add Repository pane and click Add.

  • Name: The name you want to give the new repository.
  • Location: The URL of the repository. Enter an HTTP or FTP URL, a filesystem path, or use the Browse button to select a local directory. For password protected FTP sites, use the format:
      ftp://user:password@server/path.

To remove a repository, click the Delete Repository icon next to it.

Enabled repositories show the Enabled Repository icon; disabled ones show the Disabled Repository icon. Click these icons to toggle between states.

Default Repository

http://ppm4.activestate.com/MSWin32-x86/5.8/819/ ActiveState's PPM Repository

Note: ActiveState does not maintain PPM repositories for AIX, Solaris x86, Windows x86_64, or Linux x86_64. Use the CPAN shell to install perl modules on these platforms.

Additional Repositories

http://theoryx5.uwinnipeg.ca/ppms/package.lst | The University of Winnipeg's 5.8 PPM repository
http://bioperl.org/DIST | A repository of Bioperl packages
http://www.roth.net/perl/packages/ | Roth Consulting's package repository
http://www.bribes.org/perl/ppm/ | the "Bribes de Perl" (Scraps of Perl) repository (en Français et Anglais)

Additional Resources

http://cpan.uwinnipeg.ca/htdocs/faqs/cpan-search.html Randy Kobes' excellent package search engine, with browsable categories of the packages at the University of Winnipeg's CPAN site, allows you to search for modules and displays the availability of Win32 ppm packages from a number of repositories.

Additional Information

Creating an Install Area

On systems where ActivePerl is installed in a directory that is not writable by users (i.e. owned by root), a new perl library location can be defined with the PERL5LIB environment variable. PPM will recognize this library as an install area.

To create a new, user-writable install area:

  1. Make a directory for the library. For example:

        mkdir -p ~/perl/lib

  2. Set or modify the PERL5LIB environment variable using the command specific to your shell (e.g. set or export). To make this change persistent, add the command to the appropriate profile file for the shell. For example, in bash, add a line like the following to your .bash_profile or .bashrc file:

        PERL5LIB=~/perl/lib; export PERL5LIB
  3. Launch PPM and click the PPM Preferences button. In the Area tab, select the new install area to make it active.

Note: On Mac OS X, user-writable install areas called "ActivePerl" are created for all users during installation (in /Users/<username>/Library/ActivePerl).

Using Zip Files

As an alternate method for installing packages, you can download zip files for the packages that you need from http://ppm.activestate.com/PPMPackages/zips/. To use these files:

  1. Unzip the package to a temporary directory.
  2. Install the package by specifying the ppd file directly:
    ppm install c:\tmp\module-name.ppd

Some modules have dependencies that may cause them to fail to install if those packages are not available in a repository that PPM is connected to. You can use the ppm describe command to see what dependencies the package has, but those packages may have their own dependencies.

Unavailable Packages

Cryptographic Packages Unlike the United States, the Export Control List of Canada places no significant restriction on the export of cryptographic software; however, the Canadian Federal Government does require that companies, organizations or individuals that wish to distribute cryptographic software get a permit in order to do so. ActiveState does not currently have this permission, so you must currently access other repositories for the following modules:

    Crypt-Blowfish, Crypt-Blowfish_PP
    Crypt-CAST5, Crypt-CAST5_PP
    Crypt-DH
    Crypt-DSA, Crypt-RSA
    Crypt-GPG
    Crypt-GOST, Crypt-GOST_PP
    Crypt-IDEA
    Crypt-OpenPGP, Crypt-PGP2, Crypt-PGP5, Crypt-PGPSimple
    Crypt-OpenSSL-DSA, Crypt-OpenSSL-RSA, Crypt-OpenSSL-SMIME
    Crypt-RC4, Crypt-RC5, Crypt-RC6
    Crypt-RIPEMD160
    Crypt-Rijndael, Crypt-Rijndael_PP
    Crypt-Serpent
    Crypt-Twofish, Crypt-Twofish2, TwoFish
    Crypt-SSLeay, Net_SSLeay

DBD::Oracle Oracle no longer provides the Oracle client libraries for free, so we can no longer provide DBD Oracle as a PPM/PPM3 module. The DBD-Oracle package for ActivePerl 5.6 is the last package compiled before the licensing changed that is still available on our site. If you wish to compile this module locally, the source may be obtained from www.cpan.org. Instructions on using CPAN are at: http://aspn.activestate.com/ASPN/Reference/Products/ActivePerl/lib/CPAN.html. If you are using Windows, an easy workaround for you might be just to use DBD-ODBC instead.

GD module The GD module currently is not available from the ActiveState ppm server because of the difficulty of incorporating it into our automated build process. The GD module is available from the University of Winnipeg's repository.

A Perl Module Disclaimer

ActiveState does not maintain or own the vast majority of the modules available via PPM. We only pre-package those modules available from CPAN that can be built automatically. As a result, not all PPM packages in the repository are completely up-to-date or available for every platform.

If you require a package or package version that is not available in a PPM repository, you can install it using the CPAN shell.

Creating PPM packages

Specify the AUTHOR and ABSTRACT parameters in the Makefile.PL. However you should only pass them to WriteMakefile if the version of the perl is greater than 5.005 - older perls do not have these parameters added and do not expect to see them. This is an example Makefile.PL:

use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
WriteMakefile(
    'NAME' => 'Term::Control',
    'VERSION_FROM' => 'Control.pm', # finds $VERSION
    ($] ge '5.005') ? (
        'AUTHOR' => 'Johnny Doel (johnny@doel.org)',
        'ABSTRACT' => 'Control the IO for terminals',
    ) : (),
);

Then you make the archive with the commands

perl Makefile.PL
nmake

The resulting files are placed in the blib directory that is created when you run nmake. These files should be packed into an archive like this:

tar cvf package.tar blib
gzip --best package.tar

You now have an archive called package.tar.gz. Then you generate the PPD file by:

nmake ppd

You have to edit the resulting PPD file and add the location of the package archive into <CODEBASE HREF="" />. The location is relative to the PPD file.

You can get nmake from http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe.

PPM, Proxies and Firewalls

If you use a proxy server or firewall, you may need to set the http_proxy environment variable in order for PPM to work.

The http_proxy Environment Variable

Set the http_proxy variable with the hostname or IP address of the proxy server:

  http_proxy=http://proxy.example.org

If the proxy server requires a user name and password, include them in the following form:

  http_proxy=http://username:password@proxy.example.org

If the proxy server uses a port other than 80, include the port number:

  http_proxy=http://username:password@proxy.example.org:8080

Setting http_proxy

Windows XP

  1. Open the Control Panel and click the System icon.
    The System Properties dialog is displayed.
  2. On the Advanced tab, click on Environment Variables.
    The Environment Variables dialog is displayed.
  3. Click New in the System variables panel.
    The New Sytem Variable dialog is displayed.
  4. Add http_proxy with the appropriate proxy information (see examples above).

Windows 200x

  1. Right click on My Computer.
  2. Click on Properties and select the Advanced tab.
  3. Click "Environment Variables".
    The "System Variables" dialog appears.
  4. Click New and add http_proxy, with the appropriate proxy information (see examples above).

Windows NT

  1. Right click on My Computer.
  2. Click on Properties, select the Environment tab.
  3. Add http_proxy with the appropriate proxy information (see examples above).

Windows 95/98/ME

  1. Open the C:\autoexec.bat file for editing (e.g. in Notepad).
  2. Add a "SET" line like the following (see examples above):
          SET http_proxy=http://username:password@hostname:port
  3. Restart your computer for the change to take effect.

Mac OS X

The http_proxy should be set in two places on OS X:

  • Shell: Add a line like the following in .bash_profile (/Users/<name>/.bash_profile):
          http_proxy=http://username:password@hostname:port;  export http_proxy

    This setting applies to PPM when it is launched from or used at the command line.

  • Desktop: Add an entry like the following in your environment.plist file (/Users/<name>/.MacOSX/environment.plist):
          <key>http_proxy</key>
      <string>http://username:password@hostname:port</string>

    This setting applies to PPM when it is launched by clicking the PPM icon.

Linux, Solaris or HP-UX

Set the http_proxy environment variable using the command specific to your shell (e.g. set or export). To make this change persistent, add the command to the appropriate profile file for the shell. For example, in bash, add a line like the following to your .bash_profile or .bashrc file:

    http_proxy=http://username:password@hostname:port;  export http_proxy

Using the CPAN shell

If you require a module that is not available via ppm, or you require a more recent version, you can build the module from CPAN sources. The CPAN shell is a command-line interface for fetching and building modules directly from CPAN archives. To run it, enter the following command:

    cpan

Building modules from source requires the following components:

Windows:

  • Microsoft's nmake, which is available from: http://support.microsoft.com/default.aspx?scid=kb;en-us;Q132084, or dmake, which is available from http://search.cpan.org/dist/dmake.
  • a C compiler (not required for 100% pure perl modules). Supported compilers are MicroSoft Visual C/C++ 6.0 and MinGW (gcc)

Mac OS X:

  • Apple's Xcode tool suite, available from: http://developer.apple.com/tools/xcode/index.html

Linux and Solaris systems will normally have a compiler and a make utility installed by default.


ActivePerl FAQ - Web Server Information

Web Server Information

  • NAME
  • DESCRIPTION
    • General Web Server Configuration Issues
      • What web servers support ActivePerl?
      • Why does my ActivePerl script run from the command line, but not as a CGI script?
      • Can't I put perl.exe in my CGI directory and call it in the URL? NO!
    • Using the Apache Web Server
      • How do I configure Apache 2.0.x to support ActivePerl?
      • How do I configure Apache 1.3.x to support ActivePerl?
    • Using the Microsoft Web Servers
      • How do I configure Microsoft IIS 6 to support ActivePerl?
      • How do I configure Microsoft IIS 4.0/IIS 5.0 to support ActivePerl?
      • How do I configure Microsoft IIS 3.0 or lower to support ActivePerl?
      • How do I configure Personal Web Server 1.0x for Windows 95 to support ActivePerl?
    • Using Other Web Servers
      • How do I configure other web servers to support ActivePerl?
    • Testing Your Web Server Configuration
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq6 - Web server information

DESCRIPTION

ActivePerl Web Server Configuration and Troubleshooting

General Web Server Configuration Issues

What web servers support ActivePerl?

Most Windows web servers that use the CGI standard or ISAPI will run ActivePerl scripts. The following servers are known to work with ActivePerl (known protocols in brackets):

Apache for Win32 [CGI, mod_perl]
http://www.apache.org
mod_perl home page: http://perl.apache.org
Microsoft Internet Information Server [CGI, ISAPI]
http://www.microsoft.com/WindowsServer2003/iis/default.mspx

Why does my ActivePerl script run from the command line, but not as a CGI script?

Usually, this means one of two things: either your system is misconfigured, or your script does not send the correct output for a CGI script.

Before you do anything else, check this list:

  • Make sure you have correctly configured your server for perl.exe or PerlIS.dll. This is often accomplished by mapping a specific extension, such as .pl or .plx, to perl.exe or PerlIS.dll. Usually, web servers rely on their own mappings, rather than the Windows command-line mappings.
  • If your web server depends on the PATH variable to find perl.exe, make sure that you put perl.exe in your system PATH, not just your user PATH. This only applies to Windows NT/200x/XP.
  • If your web server requires directories to be marked as executable, make sure the directory that contains the script is marked as such.
  • Since the web server can be configured to run as a local user, be sure that the user has access to the script file and the Perl binaries and libraries. Many web servers run as the ``Local System'' account, which generally has sufficient permissions.
  • If Perl.exe or Perl for ISAPI fail to work as expected check your event logs for clues.
  • Ensure that HTTP headers are being output correctly. Use the following script as a test:
        #!C:\perl\bin\perl.exe
    # previous line added to support Apache 1/2
    # please adjust to your own Perl path!
    use strict;
    use CGI;

    my $page = new CGI;
    my $msg = "Hello from ActivePerl CGI!";

    # print header and start the markup output
    print $page->header( "text/html" ),$page->start_html( $msg );
    print $page->h2($msg);
    print $page->end_html;
    # end code

Check the information above with a script that you know produces the right output for the CGI protocol (scripts in this FAQ are a good first choice). Try it with your own script after you're sure the test script will work.

If you are sure the server is running the script, but it only generates error messages in your browser, there are some tools that may help you out. CGI::Carp is used to send debugging information to the browser or log file. Even if your script has a compilation error, it can usually intercept and report errors. To use CGI::Carp, include the following lines in your program:

    # The code in the BEGIN block will be executed very early
    # on, even before the rest of this script is parsed.
    #
    BEGIN {

        # Use the CGI::Carp module and import the carpout() function.
        #
        use CGI::Carp qw(carpout);

        # Send warnings and die messages to the browser.
        #
        carpout(STDOUT);

    }

If your script has an error, you may see something like this in the browser:

    [Wed Jun 3 09:32:28 1998] C:\inetpub\scripts\test.pl: Error message! at
    C:\inetpub\scripts\test.pl line 38.

Sometimes, it can be helpful to put yourself in somebody else's position. The libwww-perl bundle (LWP) is available from CPAN, but you can install it using the Perl Package Manager (PPM). LWP may be included with future releases of ActivePerl.

LWP includes the powerful lwp-request script, which lets you see things from the browser's perspective. Invoke lwp-request with the name of a URL to see the content of the response, as in lwp-request http://localhost. To inspect the headers of an HTTP response, invoke lwp-request with the -de switch:

    C:\>lwp-request -de http://localhost
    Date: Wed, 03 Jun 1998 13:37:31 GMT
    Accept-Ranges: bytes
    Server: Microsoft-IIS/4.0
    Content-Length: 4325
    Content-Location: http://localhost/Default.htm
    Content-Type: text/html
    ETag: "0c1e58b063bd1:1237"
    Last-Modified: Thu, 09 Apr 1998 12:09:28 GMT
    Client-Date: Wed, 03 Jun 1998 13:37:31 GMT
    Client-Peer: 127.0.0.1:0

This tool can be very helpful in figuring out exactly what your scripts are doing. Whatever you do, don't give up hope. It is, in fact, possible to get a Perl script running on your web server. Really.

Can't I put perl.exe in my CGI directory and call it in the URL? No!

First, the warning: do not do this. Really. Even if you don't understand why not, don't.

Now the explanation: the idea here is to put perl.exe in your CGI directory (however you configure that on your server), and use URL syntax like the following:

    http://soon.to.be.a.victim.net/cgi-bin/perl.exe?myscript.pl

to run myscript.pl. This keeps you from having to figure out how to configure your server to associate extensions like .pl with an interpreter like perl.exe.

In fact, on some early Win32-based web servers (iPlanet 1.x servers in particular), it was impossible to associate a script file with an interpreter. This method was recommended by vendors as a viable approach to running Perl scripts on your web server.

With this configuration, anyone with a devious mind and a little knowledge of Perl could start doing all kinds of destructive things on the server. All they'd have to do is send made-up URLs, using the -e command line switch in perl.exe, in order to do things like delete all files on a drive:

    http://aaaugh.that.hurts.net/cgi-bin/perl.exe?-e?'del%20c:\*.*%20/S%20/Q'

Of course, a true computer criminal would never do something this crude and obvious, but would instead use this as a launching point to cause irreparable harm to your organization.

The following URL covers this issue in more depth:

    http://www.cert.org/advisories/CA-1996-11.html

Note that one suggested solution to this problem is wrapping your Perl script in a batch file using pl2bat or your own custom batch code. This is also not a good idea. Most servers that won't allow file associations are also susceptible to a bug that allows a user to enter any DOS command after the bat file.

Using the Apache Web Server

How do I configure Apache 2.0.x to support ActivePerl?

These instructions assume that you have installed the Apache web server according to the instructions for the 2.0.x Windows version.

  1. Open the httpd.conf file for editing by selecting Start > Programs > Apache HTTP Server > Configure Apache Server > Edit the Apache httpd.conf Configuration File.

    This will open your httpd.conf file in the notepad editor.
  2. Make the following changes to the httpd.conf file:
    • In the DocumentRoot section, set the value of DocumentRoot to the directory in which your web site files will be located on your system's hard drive(s). Ensure that you use forward slashes (/) in the path, as Apache doesn't understand backward slashes (\) in paths. For example:
          # DocumentRoot: The directory out of which you will serve your
    # documents. By default, all requests are taken from this directory, but
    # symbolic links and aliases may be used to point to other locations.
    #
    DocumentRoot "C:/apacheroot"
    • In the main directory section, add ExecCGI to the Options line. For example:
          Options FollowSymLinks ExecCGI
    • Search for the following line and remove the hash mark character (#) to uncomment this line. (You can also change .cgi to .pl if you prefer.) For example:
          #AddHandler cgi-script .cgi

      Should look like:

          AddHandler cgi-script .pl
  3. Save your changes to the httpd.conf file, and restart the Apache Service using the Apache Service Monitor.
  4. Test your configuration as described in the Testing Your Web Server Configuration section below.

How do I configure Apache 1.3.x to support ActivePerl?

There are two ways to configure Apache to support CGI scripts: by setting the directory in which the ActivePerl scripts reside, or by setting the file extension that Apache will associate with CGI scripts.

To add a directory in which all of your CGI scripts will reside, do the following:

  1. Open the httpd.conf file for editing by selecting Start > Programs > Apache HTTP Server > Configure Apache Server > Edit the Apache httpd.conf Configuration File.

    This will open your httpd.conf file in the notepad editor.
  2. Make the following changes to the httpd.conf file:
    3.     ScriptAlias /cgi-bin/ "C:/Program Files/Apache Group/Apache/cgi-bin/"
    You can choose any directory that you like, but you must ensure that it exists.
  3. After you have made this change, stop and restart the Apache service.
    Note: Apache provides an emulation of the UNIX ``shebang'' syntax, where the first two characters on the first line of a script begin with the hash mark ("#") and bang ("!") characters, which is then followed by the path to the script interpreter. This will ensure that the proper interpreter will always be used to run your script. You should begin each ActivePerl script that you place in your cgi-bin directory with a valid path to the ActivePerl interpreter. For example:
        #!C:\PERL\5.00464\bin\MSWin32-x86\perl.exe

    use CGI qw(:standard) ;
    print header();
    print "Hello, world";
  4. Test your configuration as described in the Testing Your Web Server Configuration section, below.

To enable CGI scripts based on an extension, such as .pl or .cgi, do the following:

  1. Add the following line to the httpd.conf file:
        AddHandler cgi-script .pl
    Note: By default, CGI scripts are not allowed to be in your DocumentRoot directory, but they are allowed in other document directories. Document directories are created with the Alias command in httpd.conf. For example:
        Alias /ResourceKit/ "E:/utilsamp/"
    You can then include files that end in .pl (or .cgi, if you set that as the extension in the AddHandler line) within a document directory. You will still need to include the #! line with the full valid path to the perl.exe interpreter, as shown in the previous procedure.
  2. If you want to allow CGI scripts in the DocumentRoot directory, add the ExecCGI option to the Options directive in the <Directory> section for your DocumentRoot in the httpd.conf file; this section appears directly after the comment titled:
    3.     # This should be changed to whatever you set DocumentRoot to.
    After you have updated it, your Options directive should look similar to this:
        Options Indexes FollowSymLinks ExecCGI
  3. After you have made these changes, stop and restart the Apache service.
  4. Test your configuration as described in the Testing Your Web Server Configuration section, below.

Using the Microsoft Web Servers

How do I configure Microsoft IIS 6 to support ActivePerl?

To configure ActivePerl to work with IIS 6 on Windows 2003:

  1. Load the Internet Information Services (IIS) Manager applet from Window's Administrative Tools menu.
  2. Select the desired system, then select Web Service Extensions. Click Add New Web Service Extension.
  3. Enter a descriptive Extension Name (such as "Perl CGI"), then enter the following string in the Required Files field:

    C:\Perl\bin\perl.exe "%s" %s

    As necessary, modify the path to the Perl executable on the selected system. Check Set Extension Status to Allowed, then click OK.

  4. Expand the Web Sites directory in the IIS Manager and right-click Default Web Site. Select New | Virtual Directory.... Use the wizard to specify the location of your Perl CGI programs. On the Access Permissions page, ensure that Read, Run Scripts and Execute are enabled.
  5. Right-click the new virtual directory and select Properties. On the Mappings tab of the Application Configuration page, ensure that the .pl or .cgi extension is mapped to the Perl interpreter specified above. (Enter the same string in the Executable Path field as shown in step 3.)
  6. In order to run ASP scripts, ensure that Active Server Pages are "allowed". Under the Web Service Extensions directory, select Active Server Pages. Change the status from "Prohibited" to "Allowed".
  7. Restart the IIS service.
  8. Test your configuration as described in Testing Your Web Server Configuration.

How do I configure Microsoft IIS 4.0/IIS 5.0 to support ActivePerl?

Microsoft IIS 4.0 ships with Windows NT Server 5.0, and PWS 4.0 ships with Windows NT Workstation 5.0. Both IIS and PWS are available as part of the Microsoft Windows NT 4.0 Option Pack. You can find a link to the Option Pack at http://www.microsoft.com/WindowsServer2003/iis/default.mspx

Microsoft IIS 5.0 is not automatically installed on all Windows 2000 systems. Check your Windows 2000 documentation on how to install IIS 5.0.

To configure IIS or PWS 4.0 to run Perl scripts:

  1. Open the Internet Services Manager. This will bring up the Microsoft Management Console with the Internet Services Manager snap-in already selected.
  2. From the tree display on the left, select the level at which to apply the mappings. You can choose an entire server, web site, or a given virtual directory.
  3. Select Properties from the Action menu.
  4. If you chose to administer the properties for the entire server, the Server Properties dialog will be displayed. Select WWW Service from the Master Properties pull-down menu and click the Edit button under Master Properties. This opens WWW Service Master Properties. Select the Home Directory tab and proceed to step 7.
  5. If you chose to administer the properties for an entire web site, the Web Site Properties sheet is displayed. Select the Home Directory tab and proceed to step 7.
  6. If you chose to administer the properties for a virtual directory, the Virtual Directory Properties sheet is displayed. Select the Virtual Directory tab and proceed to step 7.
  7. Click the Configuration button. This opens the Application Configuration dialog.
  8. Select the App Mappings tab and click the Add button. You now see the Add/Edit Application Extension Mapping dialog.
  9. To run Perl as a CGI application, type the full path to Perl.exe followed by "%s" %s. When a script is executed, the first "%s" (double-quoted) will be replaced by the full path to the script, and the second %s will be replaced by the script parameters.
  10. To run Perl for ISAPI, type the full path to PerlIS.dll. The %s %s is not required for ISAPI DLLs.
  11. In the Extension field, type .pl or .cgi (or whichever extension you want to use).
  12. The application mapping is now complete. Click the OK button and click OK to dismiss any remaining dialogs/property sheets.
  13. Close the IIS Internet Services Manager.
  14. After you have made these changes, stop and restart the IIS service.
  15. Test your configuration as described in the Testing Your Web Server Configuration section, below.

Because IIS runs as a service (see What is a Windows NT service?), you need to take special steps to make sure that files and environment variables are available to it.

How do I configure Microsoft IIS 3.0 or lower to support ActivePerl?

By default, the ActivePerl installation maps the .plx extension to Perl for ISAPI. You can override the extension used during installation. Because the installation does this only when IIS is already installed, you must install IIS first, then install ActivePerl. If you need to reconfigure these settings, or if you must set these by hand, the instructions in this section will prove useful.

Microsoft Internet Information Server (IIS) ships with Windows NT Server. Peer Web Services (PWS) ships with Windows NT Workstation. Configuring the products is essentially the same. First, you should consult Chapter 8, Publishing Information and Applications, in the IIS documentation.

You need to follow these steps to get ActivePerl scripts to run under IIS:

  1. Open the Registry Editor by clicking Start > Run and typing regedit in the Open field of the Run dialog, and then click OK.
  2. In the registry tree on the left, expand HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > W3SVC > Parameters and click on Script Map.
  3. Associate the extension for your scripts with the appropriate interpreter in the script map for IIS. Many people map two extensions: one to perl.exe %s (for example, .pl) and another to PerlIS.dll (for example, .plx). Note that mapping an extension in the script map is not the same as associating the extension in Explorer. Use the full paths to the executable files in the script map.
  4. Put your scripts in a virtual directory on the server that has Execute access but not Read access. You can add virtual directories or view their access with the Internet Services Manager. Remember that the URLs for your virtual directories can't overlap with URLs to directories in the WWW root directory. For example, You can't have a cgi-bin virtual directory and a real cgi-bin subdirectory of the WWW root.
  5. Ensure that your scripts are readable by the account used by the IIS server. You set this account in Internet Services Manager; by default, it is set to IUSR_[your server name].
  6. Ensure that all supporting files, such as the perl binary files, the perl library files, and the modules that you use, are all readable by the account used by the IIS server. See also What is a Windows NT service? and How do I set permissions on a file?.
  7. After you have made these changes, stop and restart the IIS service.
  8. Test your configuration as described in the Testing Your Web Server Configuration section below.

Because IIS runs as a service (see What is a Windows NT service?), you need to take special steps to make sure that files and environment variables are available to it.

How do I configure Personal Web Server 1.0x for Windows 95 to support ActivePerl?

Microsoft Personal Web Server for Windows 95 is a scaled-down version of Microsoft Internet Information Server. Although it is not documented, it appears that the method used to support ActivePerl with IIS will also work with Personal Web Server. See How do I configure IIS 3.0 or lower to support ActivePerl?.

Using Other Web Servers

How do I configure other web servers to support ActivePerl?

If your web server isn't listed, check the server's documentation on how to set up a CGI interpreter. In general, the process is as follows:

  • Associate a file extension like .pl with the perl binary, and let the server know where the binary is. This may be a shell association, (see How do I associate Perl scripts with perl?), or a custom association.
  • Set up a directory where executable scripts go, and put your Perl script there.
  • Ensure that the user account used by the web server has permission to read the script as well as any ancillary files (perl binary files, library files, modules, etc.). This usually means making the files available to the Everyone group.

Because most web servers run as services (see How do I configure IIS 3.0 or lower to support ActivePerl?), you need to take special steps to ensure that files and environment variables are available to them.

Testing Your Web Server Configuration

Regardless of which of the above configurations you performed, you should test your configuration to ensure that your web server properly handles ActivePerl CGI scripts. The following script provides a simple test of your configuration:

  1. Save the following test script in your DocumentRoot directory as test.pl or test.cgi (depending on your configuration of the AddHandler line) and modify the first line as required to point to your ActivePerl interpreter:
        #!c:\perl\bin\perl.exe
    # ^^^ this must be the first line of the script! ^^^
    # start code

    use strict;
    use CGI;
    my $q = new CGI;

    # print header and start the markup output

    print $q->header( "text/html" ),$q->start_html( "hello from perl cgi!" );
    print $q->h2("hello dave...");
    print $q->end_html;
    # end code
  2. Open the script in your browser to test your configuration. You should see a page that displays a level two heading with the following text:

    hello dave...

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly and Associates, and David Grove and David Dmytryshyn of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Web Server Information


ActivePerl -- Readme

Contents

  • What is ActivePerl
  • Getting Started on Windows
  • Troubleshooting ActivePerl

What is ActivePerl?

ActivePerl is a quality-assured binary build of Perl, available for AIX, HP-UX, Linux, Mac OS X, Solaris and Windows.

New Features in ActivePerl 5.8:

  • I/O filters
  • Improved Unicode support
  • Reliable signals
  • New threads package
  • Better accuracy in numeric operations
  • Support for large file operations on all platforms
  • Additional documentation and tutorials

The complete ActivePerl Package contains:

  • Perl - binary of core perl distribution
  • Perl Package Manager - Perl extension installer and manager.
  • Complete Online documentation

The Windows version also includes:

  • Perl for ISAPI - an IIS plug-in that makes Perl CGI scripts run faster
  • PerlScript - an ActiveX scripting engine, like that used for JavaScript or VBScript, but with a Perl interpreter
  • PerlEz - Embedded Perl

Getting Started on Windows

Running Perl scripts from the command line

To run your Perl scripts, enter the following command at the command prompt:

perl -w yourscriptname.pl

Where yourscriptname.pl is the name of the script you want to run. If you are using Windows and have associated the extension of the file with Perl, typing yourscriptname.pl (that is, without calling perl first) will also launch the script.

Sample Script

In the /eg directory of your Perl install there is a sample script named example.pl. To run it, launch a console window (command prompt), navigate to the /eg directory, and type:

perl example.pl

You should see:

"Hello from ActivePerl!"

If you do, you have successfully installed ActivePerl! If not, there's something wrong with your installation. Check to make sure that your PATH environment variable includes the directories to which you installed the Perl core binaries. You can type set at the command prompt to see what's in your Path. If you chose the defaults during the install, these should be set to the correct values for you when you start a new command prompt window. If you continue to have problems, refer to the Installation Guide.

Note: Typing perl -h will print a screen of all of the available command line options.

Troubleshooting ActivePerl

ActivePerl includes a collection of Frequently Asked Questions about ActivePerl. The FAQ is a valuable source of distilled information about using Perl. It is a must read!

The Perl FAQ, which is also included in the ActivePerl documentation, answers many questions regarding the use of Perl.

Search the ActivePerl Mailing List archives for information about your problem. Before posting to the mailing list, ensure that you have thoroughly read the FAQs and the relevant Perl documentation.

See More Resources for additional sources of information.


ActivePerl 5.6 Change Log

For the latest information on ActivePerl, please see:

    http://www.ActiveState.com/ActivePerl/

Build 638 Thursday, Apr 15, 2004

PPM2 and PPM3

PPM3 has not been updated to the latest version PPM 3.1 as shipped with the ActivePerl 5.8 series. PPM 3.1 assumes that PPM 2.x is no longer installed and doesn't synchronize package information with it. Since PPM2 is the default PPM version in ActivePerl 5.6, PPM3 has been kept at version 3.0.

Bug Fixes and Changes

  • On Windows, a potential buffer overrun in the stat() function has been fixed.

  • On Windows, a handle leak in kill() has been fixed.

  • On Windows, a memory leak in fork() has been fixed.

  • On Windows NT and later, subprocesses are now started via "cmd /x/d/c" instead of "cmd /x/c". This disables execution of AutoRun command specified in the registry.

  • On Windows, the four-argument form of select() did not report the $! (errno) value properly after errors. This has been corrected.

  • Win32::GetOSVersion() returns additional information about the system (when available, Windows NT SP6 and later).

  • Perl for ISAPI would sometimes close a filehandle twice. This leads to a race condition where another thread could have reused the filehandle before the second close would be executed. This usually happens in high load scenarios. Typical symptoms include error messages that Perl could not load standard modules, even though they are installed on the server.

    Perl for ISAPI no longer closes filehandles implicitly and relies now on the application to properly clean up file and socket handle resources.

  • Perl for ISAPI now avoids closing the special handles STDIN, STDOUT and STDERR, even if the script asked for that explicitly.

  • The following bundled modules have been updated to their latest versions:

      Archive-Tar
  Compress-Zlib
  Digest
  Digest-MD2
  Digest-MD5
  Digest-SHA1
  File-CounterFile
  HTML-Parser
  HTML-Tree
  libnet
  libwin32
  libwww-perl
  MD5
  MIME-Base64
  Storable
  Test-Harness
  URI

    The following modules have been added to ActivePerl:

      Data-Dump
  IO-Zlib
  Test-Simple

  • Other minor bug fixes and documentation updates.

Build 635 Thursday, Feb 6, 2003

Fixes for Security Issues

  • On Linux, the crypt() builtin did not return consistent results. This has been corrected.

  • The reval() and rdo() methods in the Safe module could be subverted into executing unsafe code by the callee. This problem has been corrected.

Other Bug Fixes and Changes

  • Overloading bool could result in core dumps in some situations. This has been corrected.

  • On Windows, sockets opened by code running under PerlScript and Perl for ISAPI were not fully closed internally. The ensuing leak resulted in failure to open files or sockets after a certain number of sockets had been opened and closed under these environments. This problem was particularly severe when running under ActivePerl 5.6.1.632 or 5.6.1.633, and is now fixed.

  • On Windows, PerlScript and Perl for ISAPI were affected by a reentrancy problem, which meant that recursive invocation of these two engines could fail. This problem has been corrected.

  • PPM3 includes a number of bug fixes for better handling of both PPM2 and PPM3 repositories.

  • Tk and libwww-perl have been updated to their latest versions.

  • Win32::EventLog could fail to retrieve messages under some circumstances. This has been corrected.

  • Win32::OLE has been updated. Run "perldoc Win32::OLE::NEWS" for a summary.

  • Win32::Shortcut no longer calls CoUninitialize() within an END block. This avoids random coredumps from this module when its DESTROY methods happen to get called after the END block executes.

  • Win32::Job now propagates environment changes to its subprocesses correctly.

  • A Win32::GetFolderPath() builtin is now supported. Run "perldoc Win32" for documentation on this new builtin.

  • PPM v2 and v3 can now optionally generate HTML documentation when installing packages if POD documentation is found in the package. This is controlled by the rebuildhtml option in PPM v2 and the rebuild-html option in PPM v3.

  • Other minor bug fixes and documentation updates.

  • Build 634 was not formally released to the public.

Build 633 Monday, June 17, 2002

Bug Fixes and Changes

  • The PPM3 release included in Build 632 had a bug in the package upgrade functionality. This has been corrected in PPM v3.0.1.

  • Some modules that autoloaded their constants could reset $! during autoloading. Such locations now properly localize $! before potentially modifying it.

  • IO::Pipe now works on Windows.

  • libwin32 v0.191 is included on Windows.

Build 632 Monday, June 3, 2002

Fixes for Security Issues

  • Compress-Zlib is now linked with zlib v1.1.4, which fixes a buffer overflow vulnerability in this library.

  • The version of SOAP-Lite included in ActivePerl 5.6.1.631 and earlier allowed untrusted data to call any subroutine that is defined in the program that loads SOAP::Lite, or in any modules used by the program. SOAP-Lite v0.55, included in this release of ActivePerl, contains a fix for this issue.

Other Bug Fixes and Changes

  • Redirecting STD* handles with open(STDOUT, "&=FOO")> leaked memory on all platforms. This leak has been fixed.

  • Race conditions involving backticks, piped open() have been fixed. These problems could affect environments where multiple Perl interpreters execute in concurrent threads.

  • Use of the range operator on constant numbers, as for example 1..20, could result in compile-time stricture checks being disabled for parts of the program. The problem has been corrected.

  • XSUBs can now be undefined using undef().

  • On Unix platforms, %ENV and %SIG handling could result in race conditions. Changes to %ENV and %SIG are now only propagated to the underlying system process context within the top level interpreter.

  • On Unix platforms, ActivePerl now uses reentrant versions of library functions, where available. This further improves thread-safety in multiple-interpreter environments.

  • Win32::GetLongPathName() did not work correctly if there were "." or ".." components in the argument. The implementation has been improved to handle this better.

  • On Windows platforms, a Win32::SetChildShowWindow() builtin is now supported. This can be used to set the visibility of child process windows. See the Win32 manpage for more information.

  • Newer versions of the following modules are included: Digest-MD5, MIME-Base64, URI, HTML-Parser, libwww-perl, SOAP-Lite, and libnet.

  • libwin32 has been updated on Windows platforms. There is support for job objects (available in Windows 2000 and XP) through the new Win32::Job extension, which can be used to manage a group of processes.

  • On Windows platforms, the installer ensures that the Microsoft Installer automatic repair "feature" will not be triggered. This ensures that the repair "feature" does not corrupt the ActivePerl installation by "repairing" critical files to their unrelocated state.

  • Documentation for perl programs is now included in the table of contents.

Build 631 Monday, December 31, 2001

Bug Fixes and Changes

  • ActivePerl 5.6.1.628 introduced a memory leak in eval "..." expressions that create anonymous subroutines. This has been fixed.

  • On Windows, the behavior of system(@list) has been further rationalized to improve compatibility with the behavior before 5.6.1.630. Automatic quoting of arguments with whitespace is now skipped if the argument already contains double quotes anywhere within it. Previously, the double quotes needed to be at both ends in order for further quoting to be skipped.

  • Bugs in command.com on Windows 9x/Me prevented the system() enhancements in ActivePerl 5.6.1.630 from working in some situations. These enhancements are now disabled under Windows 9x/Me.

  • Perl for ISAPI and PerlScript had a bug in ActivePerl 5.6.1.630 that caused system() and backticks to leak handles, resulting in failure of these functions after a certain number of invocations. This has been corrected.

  • ActivePerl 5.6.1.629 and later had a problem in Perl for ISAPI that caused %ENV modifications done by the script to affect the real environment, resulting in incompatible behavior of scripts that assumed the older behavior. The behavior before 5.6.1.629 has been reinstated.

  • On Windows, the internal memory allocator used by Perl could fail after around 1 GB of allocations even though more memory may be available on the system. Allocating up to and beyond 2GB is now possible if the system has memory available and allows a single process to allocate that amount of memory. Note that most Windows systems running on x86 have a 2GB limit on allocations by a single process.

  • Non-blocking waitpid() on any process (a.k.a. waitpid(-1, WNOHANG)) is now supported on Windows.

  • Due to popular demand, the following modules are now included by default: Storable, Tk, and XML-Simple.

  • PPM v3 beta 3 is included. A number of bugs in beta 2 have been fixed. Installing from URLs (http, ftp, and file) and installing through a HTTP proxy server are now supported.

  • Compress-Zlib and MIME-Base64 have been updated to their latest versions.

  • Due to popular demand, HTML documentation has been reintroduced into the default installation for Windows.

  • Various other minor bugs have been fixed. See the ActivePerl bug database at http://bugs.ActiveState.com/ for more information.

Build 630 Wednesday, October 30, 2001

Bug Fixes and Changes

  • PPM v3 beta 2 is included. This version of PPM is a complete rewrite, and comes with many new features and improvements, including support for managing installation profiles through the ASPN web site.

  • Many of the standard extensions supplied with Perl have been audited for the use of C "static" variables and fixed to avoid such uses, making these extensions safe to use in multi-threaded environments such as PerlEx and PerlMx Enterprise. The list includes B, DynaLoader, File::Glob, DB_File, Opcode, and re.

  • The readline() (aka "diamond") operator now works on "our" variables.

  • On Windows, system() and backticks behave more sanely with respect to whitespace in arguments. Any whitespace inside quoted arguments are correctly preserved. system() with multiple arguments also automatically quotes any arguments that contain whitespace by enclosing them in double-quotes, as necessary. This improves portability of the standard idiom of calling system() with multiple arguments.

  • On Windows, IO::File::new_tmpfile() does not fail after 32767 calls

  • On Windows, entries in %ENV were sometimes being improperly propagated to child processes if such entries happened to be at the end of the internal process environment table. This misbehavior has been corrected.

  • PerlScript and Perl for ISAPI ignore the \\?\ prefix in new-fangled file names returned by IIS in Windows XP.

  • In scripts running under PerlScript or Perl for ISAPI, print() with more than one argument did not print the second and subsequent arguments. This has been fixed.

  • The style and content of the included online documentation has been extensively revised. On Windows, all the documentation is now provided in fully searchable HTML Help format. Documentation in conventional HTML format continues to be included only for Unix platforms, and can also be downloaded separately.

  • Some of the bundled modules have been updated to their latest available versions: libwin32 v0.18, URI v1.17, and SOAP-Lite v0.51 are now included.

Build 629 Thursday, August 23, 2001

Bug Fixes and Changes

  • Perl now uses the reentrant versions of time functions localtime_r(), gmtime_r(), and asctime_r() on Unix platforms, making the corresponding builtins and POSIX::asctime() thread-safe.

  • On Windows, child processes launched with Win32::Spawn() now correctly inherit any modifications to %ENV done by the script.

  • On Windows, modifications to $ENV{PATH} in the script correctly affect the lookup of executables in system() and backticks. Previous versions did not propagate %ENV modifications completely enough for the underlying CreateProcess() system call to notice any changes.

  • A small number of minor bug fixes from the Perl development track have been incorporated. See the ActivePerl source code diff for the complete list.

  • Compress-Zlib has been updated to v1.13.

  • libwin32 v0.173 is included.

Build 628 Thursday, July 5, 2001

Bug Fixes and Changes

  • A few bug fixes from the Perl development track have been incorporated. See the ActivePerl source code diff for the complete list.

  • ActivePerl on Solaris does not use Perl's malloc by default. Sufficient compatibility stubs are included such that binary compatibility with previous builds will not be affected.

  • HTML-Parser has been updated to v3.25.

  • The included HTML documentation has many substantive and cosmetic improvements.

  • Build 627 was not formally released to the public.

Build 626 Thursday, May 1, 2001

Build 626 is based on Perl 5.6.1. This is the first release of ActivePerl based on this new maintenance release of Perl. This release is meant for use in production systems. However, owing to the sheer volume of changes between Perl 5.6.0 and 5.6.1 that have been incorporated, please be sure to test it thoroughly in a non-critical environment before you upgrade your production systems.

Please check the perl561delta manpage for a list of the major changes in Perl. Only additional changes specific to ActivePerl are mentioned here.

Bug Fixes and Changes

  • Perl 5.6.1 has been incorporated. See the perl561delta manpage for a list of changes.

  • The Solaris pkgadd and Red Hat RPM packages are now relocatable. See the release notes for how to install them to a location other than the default one.

  • The following new modules have been included: HTML-Tagset v3.03

  • The following modules have been updated to newer versions: SOAP-Lite, HTML-Parser v3.19, HTML-Tree v3.11, URI v1.11, libwww-perl v5.51.

    For additional information on module updates in Perl 5.6.1, see the perl561delta manpage.

  • A number of fixes to PPM have been included. PPM now displays a download status indicator, and sports a "getconfig" command.

  • A large number of documentation updates are included.

Build 623 Sunday, December 12, 2000

Bug Fixes and Changes

  • Windows 95, Windows 98 and Windows Me Installation

    Installer now adds Perl/bin directory to the PATH environment variable for Windows 9x. Windows 9x will need to be rebooted for this to take effect.

    The PATH settings are not removed after an uninstallation.

  • PPM updated to 2.1.2. It now uses SOAP-Lite and has drastically reduced bandwidth requirements for SUMMARY requests. This is a prerequisite for supporting the new PPM repository containing most of CPAN.

  • OLE Browser has been fixed to work on IE 5.5.

  • minor bug fixes to fork() emulation and duplication of socket handles on Windows 9X.

Build 622 Sunday, November 5, 2000

Bug Fixes and Changes

  • Custom build for ActivePerl CDROM

  • MSI installer addes the CDROM repository to the ppm.xml file (Windows only)

Build 620 Sunday, October 29, 2000

Bug Fixes and Changes

  • bug fixes in environment setup for backticks and system()

PerlScript

  • works now with IIS5. Previously ASP would sometimes return an empty page when the page was accessed simultaneously from multiple clients.

  • supports OLE objects as parameters (VT_DISPATCH)

  • various namespace / package setup problems fixed

  • STDIN/STDOUT/STDERR are now available when run under WSH

  • JScript and VBScript functions can be called directly (on ASP pages)

Documentation

  • Commandline parameters for MSI installer documented (installation notes)

  • Win32 builtin documentation moved from Pod to Modules

Modules

  • CGI.pm updated to 2.74

  • Win32API::Net updated to version 0.09

Build 618 Tuesday, September 12, 2000

Bug Fixes and Changes

  • Bug fixes imported from the Perl development track. See the following file for the detailed log:

        http://www.ActiveState.com/download/ActivePerl/src/5.6/AP618_diff.txt

    Individual patches for each of these changes may also be obtained. See the perlhack manpage.

  • Perl's newSVrv() API function could result in corrupt data when coercing an already initialized value to the right type, and could also lead to memory leaks. Win32::OLE v0.14 tickled these bugs. newSVrv() has been fixed to resolve these issues.

  • Perl's optimizer could coredump on stacked assignments involving split(), such as @a = @b = split(...). This is now fixed.

  • Windows sockets weren't being initialized correctly in child threads if the parent already initialized it. This resulted in print() on a socket created under such conditions not being handled correctly (whereas send() would do the right thing). The problem has been fixed.

  • Win32::OLE v0.14 had a bug that could cause strings longer than 256 characters to be truncated by a single character. This has been corrected.

Build 617 Thursday, August 31, 2000

Bug Fixes and Changes

  • Bug fixes imported from the Perl development track. See the following file for the detailed log:

        http://www.ActiveState.com/download/ActivePerl/src/5.6/AP617_diff.txt

    Individual patches for each of these changes may also be obtained. See the perlhack manpage.

  • Problems with backticks not returning a proper return code under Windows 9x have been fixed. Linux, Solaris and Windows NT/2000 weren't affected.

  • wait() and waitpid() now return the correct pid values for pseudo-pids on Windows.

  • New entries added to the end of the environment via %ENV did not get inherited by child processes on Windows. This has been corrected.

  • Build 616 introduced a change that could make close(SOCKET) return a bogus return value. This has been corrected.

  • Various minor PerlScript incompatibilities under Internet Explorer 5.5 on Windows have been corrected.

  • Perl for ISAPI and PerlScript do not add entries to the EventLog by default.

  • libnet v1.06 is now included with ActivePerl. To configure the site-specific defaults for libnet, run $Config{installprefix}/bin/libnetcfg.pl.

  • Digest-MD5 v2.11 is now included with ActivePerl.

  • Several bundled extensions have been upgraded to newer versions. URI v1.09, libwww-perl v5.48, Compress-Zlib v1.08 and libwin32 v0.17 are now included.

  • The included HTML documentation has been improved and updated to be current with the latest modules.

  • The HtmlHelp.pm module is no longer included with ActivePerl. If you want this module, please obtain it from a release prior to ActivePerl 617.

Build 616 Friday, July 14, 2000

Bug Fixes and Changes

  • Bug fixes imported from the Perl development track. See the following file for the detailed log:

        http://www.ActiveState.com/download/ActivePerl/src/5.6/AP616_diff.txt

    Individual patches for each of these changes may also be obtained. See the perlhack manpage.

  • A bug in Win32::OLE that prevented PerlScript from working properly has been fixed.

  • On Windows, a small memory leak in the accept() builtin function has been fixed.

  • On Windows, creating sockets in pseudo-child processes did not work because Winsock was not initialized in the pseudo-process. This has been rectified.

Build 615 Thursday, June 29, 2000

Bug Fixes and Changes

  • Bug fixes imported from the Perl development track. See the following file for the detailed log:

        http://www.ActiveState.com/download/ActivePerl/src/5.6/AP615_diff.txt

    Individual patches for each of these changes may also be obtained. See the perlhack manpage.

  • On Unix platforms, ActivePerl is now built with the -Duseithreads Configure option, just as on Windows. While this provides a functionally identical perl, it also makes this build binary incompatible with earlier builds on Unix platforms. If you had installed any extensions (i.e. modules with XS code) using earlier builds via PPM or otherwise, you will need to reinstall them under this build. Future builds will maintain binary compatibility with this one.

    On Windows, this build continues to be binary compatible with build 613.

  • The installation location for the native installations on Unix (Red Hat RPM, Debian dpkg, or Solaris pkgadd) have changed. These packages will now be installed under /usr/local/ActivePerl-5.6/ rather than under /usr/local/perl-5.6. This one-time change avoids confusion with locally installed versions built from the sources, and also avoids installing on top of existing binary-incompatible build 613 installations.

    The installation location can be chosen as usual on Windows, and when installing using the generic installers on Unix.

  • On Windows, chdir() could sometimes fail to return failure when given a non-existent directory, and UNC paths didn't work correctly. These problems have been corrected.

  • The libwin32 v0.16 release from CPAN is included for the Windows builds.

  • Various small PPM bugs have been fixed.

  • A bug in PerlScript that prevented it from working under IIS5 on Windows 2000 has been fixed.

Build 613 Thursday, March 23, 2000

Bug Fixes and Changes

  • This build corresponds to the Perl 5.6.0 source code release.

  • This package contains some files that were missing in build 612.

Build 612 Wednesday, March 22, 2000

Bug Fixes and Changes

  • This build corresponds to the Perl 5.6.0 source code release.

  • This build incorporates mostly minor bug fixes between 5.6.0 release candidate 2 and the final 5.6.0 source code release. See the perl56delta manpage for a detailed summary of changes between 5.005 and 5.6.0.

Build 611 Wednesday, March 15, 2000

Bug Fixes and Changes

  • This build corresponds to the Perl 5.6.0 release candidate 2 sources.

  • binmode() now supports a second optional argument that can be used to switch a file handle to ":crlf" or ":raw" mode. (These correspond to the traditional text and binary modes.) See binmode in the perlfunc manpage.

  • The new open pragma can be used to set the default mode for implicitly opened handles in the current lexical scope. This is useful to set a particular mode for the results of the qx// operator. See the open manpage.

  • The bundled ActivePerl documentation has been reorganized. Outdated material has either been reworked to reflect the current status, or removed when it was no longer applicable.

  • Many bugs in the beta releases have been fixed.

Build 609 Wednesday, March 1, 2000

Bug Fixes and Changes

  • This build corresponds to the public Perl 5.6 beta 3 release, otherwise known as v5.5.670.

  • The Windows version of the installer now supports installing into paths that contain spaces.

  • Linux and Solaris install packages that allow non-privileged users to install anywhere are supported. The system-specific packaging formats that typically require root privileges continue to be available.

  • Support for kill(0,$pid) on Windows to test if process exists.

  • There is a new tutorial on Object Oriented Perl for beginners. See `perlboot'.

  • The PPM repository has been updated with newer versions of modules for all supported platforms.

Build 607 Friday, February 11, 2000

Bug Fixes and Changes

  • This build corresponds to the public Perl 5.6 beta 1 release, otherwise known as v5.5.650.

  • Several bugs in the Unicode support have been fixed.

  • Support for Unicode has changed from previous development versions. See the perlunicode manpage for details.

  • There is a new -C command-line switch to request that system calls use the wide-character APIs. This can also be used in the shebang line.

  • The byte pragma can be used to force byte-semantics on Perl operations. When not used, character semantics apply if the data is Unicode; otherwise, byte semantics are used.

Build 606 Friday, February 4, 2000

Bug Fixes and Changes

  • PPM can communicate with the package repository via SOAP. Currently PPM's and SOAP's integration is somewhat limited; however, it serves as proof of concept.

  • New modules included with the distribution are:

             - SOAP
         - File::CounterFile
         - Font::AFM

  • Support for Unicode has changed from previous versions. See the perlunicode manpage for details.

Build 604 Friday, November 26, 1999

Bug Fixes and Changes

  • A few bugs in the fork() emulation have been fixed. the perlfork manpage reflects these changes.

Build 603 Tuesday, November 23, 1999

Bug Fixes and Changes

  • NOTE:Build 603 is not binary compatible with earlier builds. If you have compiled your own extensions with earlier builds, you will need to recompile all of them.

  • Build 603 corresponds to Perl 5.005_62. Additional patches available since 5.005_62 in the public Perl repository have been incorporated.

  • Preliminary support for fork() is included. See the perlfork manpage for details about this functionality.

  • Documentation in fully searchable HTMLHelp format is included.

  • Many of the included extensions from CPAN have been updated to newer versions.

  • A large number of minor bugs in the Perl core have been fixed. See the Changes file in the included sources for a detailed list.

Build 602 Thursday, August 5, 1999

Bug Fixes and Changes

  • Build 602 corresponds to Perl 5.005_60. Additional patches available since 5.005_60 in the public Perl repository have been incorporated.

  • A number of pre-built extensions from CPAN are included in this release. These may be installed using PPM or VPM (both of which are included).

Build 601 Tuesday, July 13, 1999

Bug Fixes and Changes

  • Build 601 corresponds to Perl 5.005_57. Additional patches available since 5.005_57 in the public Perl repository have been incorporated.

  • This build features a major reworking of the API exposed by the PERL_OBJECT build option. The result is a well-defined Perl API (restricted to C syntax) that provides very high degree of compatibility for extensions available from CPAN.

  • Perl for ISAPI, PerlScript, PerlEz and PerlMsg have been modified to use the new PERL_OBJECT API.

  • Visual Package Manager (VPM) is now available. VPM can be used to install pre-built binaries from a package repository. One such is available at http://www.activestate.com/packages/perl5_6/.

What's new in the 600 Series

Major Changes

  • This series is built around development versions of Perl 5.006. Build 600 corresponds to Perl 5.005_57.

  • Significant changes that have occurred in the 5.006 development track are documented in perldelta.

  • Build 600 includes additional changes for supporting globalization. All Win32 API calls made by Perl now follow the utf8 mode of the interpreter. Wide versions of the API calls are made when utf8 is in effect. See utf8 for more information on enabling support for Unicode.

  • The 600 series is not binary compatible with builds in the 500 series. Any extensions built using binaries from the ActivePerl 500 series will need to be recompiled. Note especially that this applies to PPDs that may have been built for 500 series builds.


ActivePerl 5.8 Change Log

For the latest information on ActivePerl, please see:

    http://www.ActiveState.com/ActivePerl/

Build 820 Wednesday, Jan 24, 2007

Build 820 is based on Perl 5.8.8.

Bug Fixes and Changes since build 819

  • PPM has been upgraded to version 4.01.

    • The self-contained tkkits required by the Tcl module have been updated.

    • The PPM UI now supports install and uninstall of modules with post-install or uninstall scripts.

    • PPM now always uses package.xml for the ActiveState repository and doesn't fall back to downloading thousands of PPDs if the package.xml file is temporarily unavailable.

    • PPM now runs post-install scripts in dependency order.

    • The --force option to 'ppm install' now allows files already installed by other packages to be overwritten. Ownership of these files is transferred to the new package.

    • Added --no-sync option to the 'ppm search', 'ppm install' and 'ppm upgrade' commands.

    • Added --max-ppd option to 'ppm repo sync' command.

    • Added 'ppm config' command.

    • Added 'ppm tree' command.

    • The 'ppm repo sync' command now always checks the server to see if updates to the repository are available.

    • Improved compatiblity with PPD files from PPM3 repositories.

    • PPM4 now supports ZIP archives as the codebase of PPD files.

    • The 'ppm-shell' command on Windows now uses Term::ReadLine::Stub for terminal I/O to provide command history recall.

    • On Windows, PPM state data is now stored in LOCAL_APPDATA instead of APPDATA. The database can be quite large and is therefore not suitable for the roaming profile.

    • PPM now picks up modules from site; but still looks in the perl area first. This allows you to install Crypt-SSLeay in order to be able to access https://...-repositories.

    • Fixed a problem causing PPM to sometimes download package tarballs from the wrong repository.

    • The PPM GUI now shows which repository a package comes from. The Repository column is hidden by default.

    • The PPM GUI now warns about downgrades on modules selected for installation which have a lower version number than the currently installed version.

    • The PPM GUI used to drop all dependencies if some of them failed. It now keeps any remaining dependencies.

    • In the PPM GUI, package selection is not cleared if the install fails. This makes it possible to retry without having to select all the same packages again.

    • The PPM GUI now shows a download progress bar.

    • New PPM icon on Mac OS.

  • There have been various improvements in Unicode handling on Windows. Most of them rely on the fact that Windows stores a short 8.3 name for each filename that is longer, or contains characters not in the system codepage. By using the short name Perl is able to access these files throught the byte stream APIs that the Perl core is using.

    If the generation of short filenames has been disabled, then filenames containing characters outside the system codepage will still not be accessible. Since the short file names are stored by the file system, this mechanism will also only work for existing files. There is no way to determine a short file name for files that have not yet been created.

    • readdir() and glob() will return the short name if the long name cannot be represented in the system codepage.

    • The PATH environment variable is preprocessed and all entries using characters that are not in the system codepage will be replaced with their short name versions. This preprocessing step will also remove surrounding quote characters from all entries in the PATH variable.

      The PATH cleanup happens early enough that perl.exe will be able to find scripts via the -S commandline option in those "inaccessible" directories.

    • Both $^X and the @INC entries derived from $^X (lib and site/lib directories) will be converted to the short form, if necessary.

      Note that installing ActivePerl into a directory whose name cannot be represented in the system codepage is still discouraged.

    • Win32::GetCwd() will return a short name, if necessary, and Win32::SetCwd() can accept a Unicode name.

    • The new Win32::GetANSIPathName() accepts a pathname that may contain Unicode characters and returns the name in the system codepage.

      The file or directory must already exist; otherwise characters not in the system codepage will be translated using replacement characters (usually '?'), resulting in a potentially invalid filename.

    • Win32::GetLongPathName() may return Unicode characters now.

    • Win32::GetFullPathName() will return a short name, if necessary. Call Win32::GetLongPathName() on the return value (in scalar context) to get the full pathname in Unicode:

    • Win32::GetFolderPath() will return a short name, if necessary. Call Win32::GetLongPathName() on the return value to get the full pathname in Unicode.

    • Win32::ExpandEnvironmentStrings() may return Unicode characters because it will use the Unicode process environment directly.

      Any changes to %ENV however will be propagated to the process environment, and %ENV only stores byte strings. There is currently no API to set environment variables to a Unicode string.

    • Win32::MsgBox() now accepts Unicode strings for both the MESSAGE and TITLE paramters.

    • Win32::LoginName() may return Unicode characters.

  • The builtin Perl kill() function now support killing process trees by using negative signal numbers on Windows too. Currently kill() on Windows will still only terminate processes owned by the same user, even when the user is a member of the Administrators group.

  • Perl on Windows could hang indefinitely under certain conditions involving more than one of: alarm(), sleep(), waitpid(), system() and a GUI toolkit like Tk, wxPerl, Win32::GUI (or any other function that uses a messageloop). This indefinite loop should no longer occur.

  • The Windows installer now puts site\bin in the PATH.

  • The Windows installer now detects and prevents installation on top of ActivePerl 817 or earlier. This is necessary because the changed order of lib and site/lib in @INC would otherwise put old modules from the previous installation in front of the new modules bundled with this release.

    Also see the installation guide for help on saving and restoring your installed PPM modules with PPM-Profile.

  • The Windows installer for 64-bit ActivePerl will default the install location to C:\Perl64 instead of C:\Perl. Installing both the 32 and 64 bit versions of ActivePerl into the same directory is not supported.

    The Start menu shortcut and the Add Remove Programs entry for the 64 bit version are marked with a " (64-bit)" suffix to differentiate them from the 32 bit versions.

  • Improved MingW compatiblity on Windows.

  • The lwp-request aliases GET, HEAD, POST are no longer installed; use lwp-request directly instead. These aliases created problems on case-insensitive systems where they shadowed other commands.

  • Restored the old (pre 818) behaviour of ActivePerl::DocTools::WriteTOC(). It now only warns if it can't write to the perltoc.html file.

  • ActiveState::Browser now also looks for xdg-open, galeon and opera on Unix. It also knows how to detect KDE/Gnome properly.

  • ActiveState::Scineplex now has a JSON output mode.

  • Long hostnames are now supported on HP-UX.

  • Many bundled modules have been updated to their latest versions:

        Archive-Zip-1.18
    Data-Dump-1.08
    DBD-SQLite-1.13
    HTML-Parser-3.56
    HTML-Tree-3.23
    Mac-Apps-Launch-1.93
    Mac-Errors-1.13
    Mac-Glue-1.30
    Win32-0.28
    XML-Simple-2.16

  • A patch has been applied to DBI-1.52 to make it more robust against drivers not handling multiple result sets with different numbers of columns correctly. DBI wasn't upgraded to version 1.53 because that one breaks compatibility with DBD-Sybase.

Build 819 Wednesday, Aug 31, 2006

Build 819 is based on Perl 5.8.8.

Bug Fixes and Changes since build 818

  • HTML table of contents did not get updated as packages were installed/removed.

  • libwww-perl package was not properly recorded by PPM.

  • Term-ReadLine-Perl was missing.

  • Upgradable packages no longer show packages with equal version number in the PPM GUI.

Build 818 Wednesday, Aug 16, 2006

Build 818 is based on Perl 5.8.8.

Bug Fixes and Changes since build 817

  • This is the first non-beta release of 64 bit ActivePerl. It is available for Windows and Linux on x64 as well as Solaris on Sparc. The 64 bit Windows release does not include PerlScript, PerlEx, Perl for ISAPI or PerlEz.

    The 64 bit releases do not yet contain the Tcl and Tkx modules.

  • PPM has been rewritten; see Release Notes and ppm for details.

  • All bundled modules and scripts are now installed in the perl area and the site area is now completely empty in a new ActivePerl installation.

  • Rearranged order of @INC; modules installed in site area now take precedence over the bundled modules.

  • Simplified directory layout on Unix; no more architecture and version specific directories. This makes the layout the same as the Windows version of ActivePerl.

  • Term::ReadLine console fix for Windows.

  • Avoid trying to read C:\dev\urandom at startup on Windows.

  • The gridRemove method has been enabled for Tk.pm.

  • The Win32::OLE module in libwin32 package has been upgraded from version 0.1704 to version 0.1707.

    • add special support for tlbinf32.dll from Microsoft

    • add support for receiving VT_RECORD and arrays of VT_RECORD

    • improve error handling logic

    • fix memory leak in Win32::OLE::Enum::All() and Win32::OLE::Enum::Next()

    • in ClearVariantObject() check IDispatch/IUnknown variants for NULL before calling Release() on them

  • Double quotes are now displayed properly in the HTML documentation.

  • DynaLoader.o has now been moved into libperl.so on Unix. This makes it easier to embed perl and is the same arrangement as perl on Windows.

  • Added ActiveState::Browser module to ActiveState-Utils.

  • Most files of the Perl installation are now readonly on Windows.

  • Added a workaround for Module::Install brokenness that affected ActivePerl::Config (introduced in build 815). This prevented some modules to install under the CPAN shell.

  • Added error checks after execing PL_cshname or PL_sh_path.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.30
    CGI 3.20
    Compress-Zlib-1.42
    HTML-Parser-3.55
    HTML-Tree-3.20
    Mac-AppleEvents-Simple-1.18
    Mac-Carbon-0.77
    Mac-Errors-1.12
    Mac-Glue-1.27
    threads 1.31
    threads-shared 1.01
    Term-ReadLine-Perl-1.0302

  • New bundled modules:

        DBI-1.52
    DBD-SQLite-1.12
    Math-BigInt-FastCalc-0.10
    Tcl-0.89
    Tkx-1.04

Build 817.91 (818 Beta 2) Wednesday, Jul 19, 2006

Introduce PPM graphical interface and Tkx.

Build 817.90 (818 Beta 1) Wednesday, May 31, 2006

Introduce rearranged order of @INC and the new PPM command line client.

Build 817 Wednesday, Mar 22, 2006

Build 817 is based on Perl 5.8.8.

Bug Fixes and Changes

  • Upgraded the core threads and threads::shared modules with threads-1.12 and threads-shared-0.99 from CPAN. This fixes the handle leakage on Windows and allows setting the stack size for new threads. It also fixes both the '!=' comparison operator for thread objects and the crashes while joining threads that go re-introduced in build 816.

  • Fixed several bugs in the new implementation of alarm() for Windows. They did manifest themselves by signals not being delivered, or by GUI applications randomly hanging.

  • Restored binary compatibility for SvPV_nolen() and similar macros. This incompatibility made it impossible to use perlapp for Unix on Tk based applications.

  • Reintroduce PL_memory_wrap for binary compatibility.

  • The require builtin now ignores directories matching the given name when searching @INC.

Build 816 Thursday, Mar 2, 2006

Build 816 is based on Perl 5.8.8.

Bug Fixes and Changes

  • Perl 5.8.8 has been incorporated. See perl588delta.pod for a list of changes.

  • ActivePerl build 816 is now also available as a 64 bit Beta release for Windows and Linux on x86_64 as well as Solaris on Sparc. The 64 bit Windows Beta does not include PerlScript, PerlEx, Perl for ISAPI or PerlEz.

  • The ActivePerl Community License has been clarified. It now explicitly allows you to redistribute certain parts of ActivePerl as part of applications generated by wrapping tools such as by PAR, PerlApp and Perl2Exe. Please refer to the license text for actual terms and conditions.

  • ActivePerl for Mac OS X is now a Universal binary that supports all Macintosh hardware natively.

  • ActivePerl for Solaris is now built with the vendor compiler. Previous releases were built with the GNU compiler (gcc).

  • ActivePerl::Config on Solaris and HP-UX now provide compatibility so that extensions can be built using gcc. This happens automatically if the vendor compiler is not available on the target system.

  • ActivePerl now ships with a preinitialized CPAN::Config module. This avoids the need to go through the configuration dialog the first the CPAN shell is invoked. The configuration dialog can still be invoked by the o conf init command to the CPAN shell.

  • Syntax colored documentation and ActiveState::Scineplex is now supported for all the Unix platforms.

  • Passive transfer mode is now the default for Net::FTP. This mode is more likely to work with modern firewall setups.

  • Problem where 'perl -s' wasn't able to parse -foo=bar switches has been corrected.

  • The stat() builtin would not return the expected result when passed a directory name with trailing slashes on Windows. This problem has been fixed.

    This problem caused the rmtree() function of the File::Path module introduced in build 815 to fail for such directory names on Windows.

  • The IO::Socket::INET is now more efficient and it does not rely on getprotobyname("tcp") to be functional any more.

  • A problem where long groups entries could cause memory exhaustion has been fixed.

  • A problem with the alarm() function on Windows 2003 has been fixed.

  • The Tk module would sometimes fail to update the -cursor attribute of widgets for 64-bit builds of perl. This problem has now been fixed.

  • Many bundled modules have been updated to their latest versions:

        Digest-SHA-2.11
    HTML-Tagset-3.10
    HTML-Parser-3.50
    HTML-Tree-3.1901
    IO-String-1.08
    libwww-perl-5.805
    Mac-Errors-1.11
    Win32-OLE-0.1704

Build 815 Wednesday, Nov 2, 2005

Build 815 is based on Perl 5.8.7.

Bug Fixes and Changes

  • The PerlEx plugin for IIS has been added to ActivePerl for Windows. It caches precompiled CGI scripts in memory to increase their performance.

  • The table of contents for the HTML documentation has been reverted back to the format used before build 813 (it no longer requires JavaScript to be enabled).

  • ExtUtils::MakeMaker now generates and installs HTML documentation automatically. Regardless how modules are being installed (via PPM, through the CPAN shell, or by manual compilation and installation), the HTML documentation is always kept up-to-date.

  • Code snippets in the HTML documentation are syntax colored. This feature is currently only available on Windows and Mac OS X.

  • ActiveState::Scineplex has been added on Windows and Mac OS X. This module analyzes source code for various programming languages and is being used to colorize the code snippets in the HTML documentation.

  • The ActivePerl::Config module has been added. It allows perl's configuration options to be overridden. The module can also automatically reconfigure ActivePerl for alternative compilation environments when the default compiler cannot be found.

    On Windows, MakeMaker will use the gcc.exe compiler from MinGW and the dmake.exe utility if the Microsoft Visual C++ compiler cl.exe and the nmake.exe utility are not available on the PATH. This will also work automatically from within the CPAN shell.

  • The perl-static executable on Unix will now pick up a matching Config.pm (there is no statically linked Perl on Windows).

  • File::Path's rmtree() function has been replaced to address security vulnerability CAN-2005-0448.

  • Fixed incompatibility problem with Tk and Encode version 2.10 which was introduced in build 813 (perl-5.8.7).

  • Win32::GetOSName() can now identify Windows Vista.

  • Various ActiveState::* utility modules have been added.

  • libwin32 has been updated to version 0.26:

    • Win32API::File

      New GetFileAttributes() function and corresponding constants.

      Added GetFileSize(), getFileSize(), setFilePointer(), and GetOverlappedResult() functions. The file position operations can use Math::BigInt objects.

      Experimental new object oriented interface added. This will be moved into a separate module in a later release.

    • Win32API::Registry

      Added DELETE/READ_CONTROL/WRITE_DAC/WRITE_OWNER/SYNCHRONIZE as KEY_*.

    • Win32::Clipboard

      GetBitmap() should now work correctly with 1 bit, 4 bit, 8 bit, 16 bit, 24 bit, and 32 bit colors.

    • Win32::Console

      Renamed GRAY to LIGHTGRAY and added definitions for the "real" GRAY colors.

      Added get_Win32_IPC_HANDLE() method so that Win32::IPC can wait on a console handle.

      Added SetIcon() method to change the icon of the window.

      Don't export the scalar variables to %main:: but into the callers namespace.

    • Win32::Process

      Added get_Win32_IPC_HANDLE() method for Win32::IPC compatibility.

      Added STILL_ACTIVE constant for GetExitCode().

      Win32::Process::Open() now records the process ID correctly for GetProcessID(). It also creates handle now that can be used with the Wait() method.

    • Win32::Shortcut

      The Save() function now calls Win32::GetLongPathName() on the filename to make sure to use a fully qualified pathname.

      The Save() will store the new filename as the 'File' property unless the Shortcut object already has a 'File' property.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.26
    Archive-Zip-1.16
    Compress-Zlib-1.41
    HTML-Parser-3.46
    IO-String-1.07
    Mac-Apps-Launch-1.92
    Mac-OSA-Simple-1.09
    Time-HiRes-1.76
    Unicode-String-1.09

Build 814 Beta Tuesday, Jun 28, 2005

Build 814 Beta is based on Perl 5.8.7. This release is provided as a Windows MSI installer only.

Bug Fixes and Changes

  • Bundled PerlEx, an ISAPI plugin for the IIS web server.

  • Built in ActivePerl:: module providing version information.

  • The gedi program now actually runs. This is a demo program installed by the Tk package.

  • Text-Autoformat module updated to version 1.13.

Build 813 Tuesday, Jun 7, 2005

Build 813 is based on Perl 5.8.7.

Bug Fixes and Changes

  • ActivePerl is now supported on the Mac OS X, Solaris (x86), and AIX platforms.

  • New improved HTML documentation which requires JavaScript enabled browser.

  • Installation of the HTML documentation is now optional.

  • Perl 5.8.7 has been incorporated. See perl587delta.pod for a list of changes.

  • ActivePerl will now evaluate 'sitecustomize.pl' at startup if present. The ActivePerl distribution does not ship with this file, but it is a hook that the system administrator can use to set up set up additional site specific @INC entries.

  • Fixed Net::Ping's ICMP implementation to not give up waiting for the echo reply until it either receives an unreachable reply or times out. Previous versions would for instance give up if they received a source quench reply.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.23
    Compress-Zlib-1.34
    Convert-ASN1-0.19 (only for HP-UX)
    HTML-Parser-3.45
    HTML-Tagset-3.04
    libwww-perl-5.803
    XML-Simple-2.14

  • New modules

        Mac-AppleEvents-Simple-1.17
    Mac-Apps-Launch-1.91
    Mac-Carbon-0.74
    Mac-Errors-1.10
    Mac-Glue-1.25
    Mac-OSA-Simple-1.08
    MLDBM-2.01 (only for Mac OS X)
    Text-Autoformat-1.12
    Text-Reform-1.11
    Time-Epoch-0.02 (only for Mac OS X)
    Unicode-String-2.07

    The "Mac-" modules are only present for Mac OS X as well.

  • The ActiveState-Rx module has been dropped from the distribution.

Build 812 Monday, Jan 10, 2005

Build 812 is based on Perl 5.8.6.

Bug Fixes and Changes

  • On Unix, provide a destructor for libperl. This allows libperl to be repeatedly loaded and unloaded by e.g. mod_perl without running out of thread local storage slots. On Windows this was already handled correctly.

  • The reloc_perl -a option has been fixed. It is now possible to relocate from a shorter to a longer path.

Build 811 Wednesday, Dec 1, 2004

Build 811 is based on Perl 5.8.6.

Bug Fixes and Changes

  • Perl 5.8.6 has been incorporated. See perl585delta.pod and the perl586delta manpage for a list of changes.

  • Fixed stack corruption in the Tk-804.027 module. This would sometimes make Tk programs crash.

  • Fixed handling of Unicode in XML-DOM-1.43. Some Unicode strings would end up UTF-8 encoded when they should not be. The XML::DOM module is only distributed as part of ActivePerl on HP-UX.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.22
    Data-Dump-1.06
    Digst-MD4-1.4
    Encode-2.09
    HTML-Parser-3.38
    IO-Zlib-1.04
    libwin32-0.24 (only for Windows)
    libwww-perl-5.801
    libxml-perl-0.08 (only for HP-UX)
    perl-ldap-0.3202
    URI-1.35

    In addition, IO::String version 1.06 is now included with ActivePerl.

Build 810 Monday, Jun 7, 2004

Build 810 is based on Perl 5.8.4.

Bug Fixes and Changes

  • Perl 5.8.4 has been incorporated. See the perl584delta manpage for a list of changes.

  • The default install location on Unix is now /opt/ActivePerl-5.8. Earlier versions installed into /usr/local/ActivePerl-5.8 by default.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.08
    Compress-Zlib-1.33
    Data-Dump-1.03
    Digest-SHA1-2.10
    File-CounterFile-1.04
    Font-AFM-1.19
    HTML-Parser-3.36
    libwww-perl-5.79
    MD5-2.03
    perl-ldap-0.31 (only for HP-UX))
    Tk-804.027
    URI-1.30
    XML-Simple-2.12
    XML-XSLT-0.48 (only for HP-UX))

Build 809 Monday, Feb 2, 2004

Build 809 is based on Perl 5.8.3.

Bug Fixes and Changes

  • Perl 5.8.3 has been incorporated. See the perl583delta manpage for a list of changes.

  • The Win32 module now includes the Win32::IsAdminUser() function that checks if the current interpreter runs with Administrator privileges.

  • The access violations of detached threads on thread exit have been fixed.

  • Time::HiRes now provides high resolution on Windows too.

Build 808 Saturday, Dec 6, 2003

Build 808 is based on Perl 5.8.2.

Changes

  • Perl 5.8.2 has been incorporated. See the perl582delta manpage for a list of changes.

    ActivePerl build 808 is still being compiled with the -DNO_HASH_SEED option to maintain binary compatibility with earlier releases. Perl 5.8.2 implements a new rehashing scheme that will kick in dynamically based on the actual data being stored in a hash. This new scheme is backwards compatible and is enabled in ActivePerl build 808.

  • The following modules are bundled with ActivePerl for HP-UX and have been updated to their latest versions:

        Convert-ASN1-0.18
    XML-DOM-1.43
    XML-XPath-1.13
    XML-XSLT-0.45
    perl-ldap-0.30

Build 807 Thursday, Nov 6, 2003

Build 807 is based on Perl 5.8.1. This is the first release of ActivePerl based on this new maintenance release of Perl. This release is meant for use in production systems. However, owing to the sheer volume of changes between Perl 5.8.0 and 5.8.1 that have been incorporated, please be sure to test it thoroughly in a non-critical environment before you upgrade your production systems.

Please check the perl581delta manpage for a list of the major changes in Perl. Only additional changes specific to ActivePerl are mentioned here.

Bug Fixes and Changes

  • Perl 5.8.1 has been incorporated. See the perl581delta manpage for a list of changes.

    Important note: The new Hash Randomization feature has been disabled in ActivePerl because it is not compatible with Perl 5.8.0. If we enabled this feature then some modules compiled with 5.8.0 would not work correctly with 5.8.1 and most modules compiled with 5.8.1 would not work at all with Perl 5.8.0. This would require maintaining separate PPM module repositories for 5.8.0 and 5.8.1.

    To enable the Hash Randomization feature you must recompile ActivePerl from source and remove the -DNO_HASH_SEED definition from the C compiler options. In that case you must compile all CPAN modules yourself too because the PPM repository binaries will not be compatible.

  • Windows 2003 Server is now officially supported. The installer adds entries to the IIS6 "Web Services Extensions" list for both "Perl CGI" and "Perl ISAPI". Both are set to "Prohibited" by default and must be explicitly changed to "Allow" in the IIS Manager.

    Win32::GetOSName() detects the release version of Windows 2003 correctly.

  • ActiveState::Rx module has been included. This module is necessary to use the Rx Toolkit in ActiveState Visual Perl. You must upgrade Visual Perl to version 1.8.1 to use the Rx Toolkit with Perl 5.8.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.07
    Compress-Zlib-1.22
    Data-Dump-1.01
    Digest-MD2-2.03
    Digest-MD5-2.30
    Digest-SHA1-2.06
    File-CounterFile-1.01
    HTML-Parser-3.34
    HTML-Tree-3.18
    URI-1.27
    XML-Parser-2.34
    XML-Simple-2.09
    libwin32-0.21
    libwww-perl-5.75

    In addition, IO::Zlib version 1.01 is now included with ActivePerl.

PPM

  • The upgrade command has been fixed.

  • It is now possible to install from a file URL while not being connected to the Internet.

  • PPM now works on Windows even when the Term::InKey module is installed.

Perl for ISAPI

  • Perl for ISAPI no longer uses line buffering for STDOUT. This is especially important for running under IIS6 which bypasses TCP/IP nagling and directly sends every packet individually.

  • Perl for ISAPI used to close all open file handles before shutting down the Perl interpreter. The intention was to prevent file handle leaks from buggy Perl scripts while running inside the IIS process. Unfortunately Perl may still execute END blocks or call DESTROY methods during final destruction and some file handles may get closed twice in this scenario.

    This creates a race condition: the file handle may already have been re-opened by a different thread before the second close happens. Perl then closes a file handle it doesn't own anymore. This may cause a different page request to fail.

    To avoid this race condition Perl for ISAPI will no longer try to automatically close open file handles. Therefore it is possible that broken Perl applications will now start leaking file handles if they don't close them correctly themselves.

Build 806 Monday, March 31, 2003

Bug Fixes and Changes

  • Several bug fixes and other improvements have been merged from the Perl development track. In particular, many of these fixes address problems in the PerlIO implementation. See the ActivePerl source code diff for the complete list of included changes.

  • Other minor bug fixes and documentation updates.

PPM

PPM has been upgraded to version 3.1. It fixes most of the known problems, including:

  • PPM 3.1 now provides all the functionality of PPM 2.0 and 3.0. PPM 2.0 is therefore no longer included in ActivePerl 5.8.

  • PPM now works correctly through a proxy server requiring basic authentication. Previous versions of PPM 3.0 only supported proxy servers that did not require authentication.

  • PPM is now more robust in handling user-defined repository URLs. For instance, URLs with a trailing slash no longer result in fatal errors.

  • Support for ASPN Perl profiles has been much improved. However, at the time of this writing, the ActivePerl 5.8 repositories do not yet support profiles. This is expected to become available shortly.

  • In previous versions of PPM 3, incorrect search results from the repository (such as package names that do not have corresponding PPD files) could crash the PPM3 client. PPM now generates meaningful error messages under these circumstances.

Build 805 Thursday, Feb 6, 2003

Bug Fixes and Changes

  • Several bug fixes and other improvements have been merged from the Perl development track. In particular, many of these fixes address weaknesses in Unicode support. See the ActivePerl source code diff for the complete list of included changes.

  • Bugs in the Perl 5.8 integration of Perl for ISAPI and PerlScript that resulted in failure to flush output correctly at the termination of the script have been fixed.

  • On Windows, system() and backticks could return invalid status when running under environments where the process has to handle Windows messages. PerlScript and Perl for ISAPI fall under this category. The problem has been corrected.

  • On Windows, PerlScript and Perl for ISAPI were affected by a reentrancy problem, which meant that recursive invocation of these two engines could fail. This problem has been corrected.

  • Tk and libwww-perl has been updated to their latest versions.

  • Win32::Shortcut no longer calls CoUninitialize() within an END block. This avoids random coredumps from this module when its DESTROY methods happen to get called after the END block executes.

  • PPM v2 and v3 can now optionally generate HTML documentation when installing packages if POD documentation is found in the package. This is controlled by the rebuildhtml option in PPM v2 and the rebuild-html option in PPM v3.

  • Other minor bug fixes and documentation updates.

Build 804 Friday, Nov 29, 2002

What's new in the 800 Series

  • This build corresponds to the Perl 5.8.0 source code release.

  • The 800 series builds of ActivePerl are not binary compatible with builds in the 500 or 600 series. Any extensions built using binaries from the ActivePerl 500 or 600 series will need to be recompiled. Note especially that this applies to PPM packages that may have been built for 500 or 600 series builds.

  • Significant changes that have occurred in the 5.8.0 release are documented in the perl58delta manpage.

  • Support has been enabled for large file access on all platforms, meaning that file manipulation facilities within perl can cope with files larger than 2GB or 4GB.

  • Many new modules are included as a standard part of perl 5.8.0. See "Modules and Pragmata" in the perl58delta manpage for a detailed list. In addition, the Data::Dump module is now included with ActivePerl. Many other modules have been updated to their latest versions.

  • PPM v3 is now included as the default ppm executable. PPM v2 continues to be available, and can be executed as ppm2.


ActivePerl -- Resources

  • Documentation
  • Support
  • More Perl Resources

Documentation

ActivePerl includes the core Perl documentation, the Perl FAQ, and the ActivePerl User Guide (which contains information specific to ActivePerl, such as the Release Notes and ActivePerl component documentation).

The ActivePerl User Guide is provided in HTML format; using a web browser, load the file <ActivePerlInstallDir>/html/index.html to view the document set. The ActivePerl User Guide includes the following information:

  • Getting Started This section contains a high-level introduction to ActivePerl, documentation of the Perl Package Manager, instructions on how to configure your web browser to support ActivePerl CGI scripts, and general information specific to ActivePerl, such as the Release Notes, Change Logs and the License and Copyright information.
  • ActivePerl Components This section contains an overview of the ActivePerl components, as well as documentation of the major ActivePerl components, such as the OLE Browser, PerlScript, Perl for ISAPI, PerlEx and PerlEz.
  • ActivePerl FAQ This section includes general ActivePerl Frequently Asked Questions pages, as well as several FAQs on Windows-related issues.
  • Windows Scripting This section includes several pages documenting issues specific to writing ActivePerl scripts on Windows platforms.
  • Core Documentation, Programs, Pragmas and Modules These sections contain HTML versions of the PerlDoc or Man Page documentation for the Perl core, Perl programs, Perl pragmas, and Perl modules that are included with ActivePerl.

Note: When you add packages to your Perl installation using the Perl Package Manager, the ActivePerl User Guide is updated with the documentation contained in the new modules.

Perl documentation can also be accessed from the command line by using the perldoc command to display the embedded documentation for the specified module. For example:

perldoc module.pm

Support

For installation-related support issues, check the ActivePerl Mailing List archives. If you do not find the answer to your problem, contact support@ActiveState.com for installation assistance.

Please submit bug reports and enhancement requests via the ActivePerl Bug Database. All bug reports should be accompanied by one or more concrete examples that will help us reproduce the problem. Include all relevant information that you think will help us recreate the particular environment in which the bug was observed. Remember, if we cannot reproduce the problem, we cannot fix it!

Commercial Support

ActivePerl Enterprise Edition is a corporate support solution for Perl. ActivePerl Enterprise Edition provides the comprehensive support that an enterprise needs to deploy Perl in mission-critical applications.

More Perl Resources

Internet Web sites

ASPN, the ActiveState Programmer Network

ActiveState Professional Services

The O'Reilly Perl Resource Center

Perl Mongers

use Perl;

CPAN

Usenet Newsgroups

Usenet newsgroups are another good source of information and advice regarding Perl. Please consult your system administrator or Internet service provider for availability of the following groups:

comp.lang.perl.announce

comp.lang.perl.misc

comp.lang.perl.modules

comp.lang.perl.tk

There are also some non-English Perl related newsgroups:

de.comp.lang.perl

fj.lang.perl

fr.comp.lang.perl

it.comp.lang.perl

no.it.programmering.perl

pl.comp.lang.perl

japan.comp.lang.per

Books on Perl

    The following books published by O'Reilly & Associates are useful additions to any Perl aficionado's bookcase:

      Srinivasan, Sriram. Advanced Perl Programming

      Gundavaram, Shishir. CGI Programming on the World Wide Web

      Schwartz, Randal L., Erik Olson & Tom Christiansen. Learning Perl on Win32 Systems

      Schwartz, Randal L. & Tom Christiansen, foreword by Larry Wall. Learning Perl, 2nd Edition

      Friedl, Jeffrey E. F. Mastering Regular Expressions: Powerful Techniques for Perl and Other Tools

      Vromans, Johan. Perl 5 Desktop Reference

      Christiansen, Tom & Nathan Torkington. Perl Cookbook

      Wall, Larry, Tom Christiansen & Randal L. Schwartz. Programming Perl, 2nd Edition

      Wong, Clinton. Web Client Programming with Perl: Automating Tasks on the Web


Welcome to ActivePerl

Copyrights, Trademarks and Licensing

Copyright

ActivePerl is Copyright (c) 1996-2006 ActiveState Software Inc. All rights reserved.

ActivePerl includes Perl and Perl modules copyrighted by other parties. Documentation and usage information for such components reflects these additional copyrights held by their respective owners.

Trademarks

ActivePerl is a trademark of ActiveState Software Inc.

Open Source is a trademark of Software in the Public Interest (www.opensource.org).

All other products mentioned are trademarks or registered trademarks of their respective companies.

Licensing

The ActivePerl Package is covered by the ActiveState Community License.

The source code used in the ActivePerl Package comprises of both Open Source and proprietary software components.

All the Open Source components used in the ActivePerl Package are distributed by their original authors under the same licensing terms as Perl. The following is a full list of such components:

  • Perl
  • Bundled Perl modules
    • Archive-Tar
    • Archive-Zip
    • Compress-Zlib
    • Data-Dump
    • DBD-SQLite
    • DBI
    • Digest-HMAC
    • Digest-MD2
    • Digest-MD4
    • Digest-SHA1
    • File-CounterFile
    • Font-AFM
    • HTML-Parser
    • HTML-Tagset
    • HTML-Tree
    • IO-String
    • IO-Zlib
    • libwin32
    • libwww-perl
    • Math-BigInt-FastCalc
    • MD5
    • MIME-Base64-Scripts
    • SOAP-Lite
    • Tcl
    • Term-ReadLine-Perl
    • TermReadKey
    • Text-Autoformat
    • Text-Reform
    • Tk
    • Tkx
    • Unicode-String
    • URI
    • XML-Parser
    • XML-Simple

ActiveState Software Inc., has chosen to use all Open Source content in the ActivePerl Package under the terms of the Artistic License.

All other components included in the ActivePerl Package are original works of ActiveState Software Inc., and may be used under the terms of the ActiveState Community License.

Source Code

The ActivePerl Package may include a version of Perl with bug fixes and other minor modifications. The source code for this modified Perl distribution used in the ActivePerl Package is always available from the ActiveState website for each release of ActivePerl, and can be distributed under the same terms as Perl.

The source code for each of the bundled modules included in the ActivePerl distribution is available from CPAN (www.CPAN.org).


ActivePerl Components

Perl

    ActivePerl includes all of the core binaries and modules you will need to write and run Perl scripts on your system.

    See the Perl page and the Perl Introduction page for more information.

Perl Package Manager (PPM)

    The Perl Package Manager (PPM) provides a command line interface for managing your Perl modules and extensions.

    PPM allows you to access package repositories and install new packages or update old ones you already have with relative ease.

    To launch PPM, type: ppm at the command prompt.

    See the Using PPM page for full instructions in the Perl Package Manager's use and capabilities.

Windows Components

Perl for ISAPI

    A plug-in designed to run Perl scripts faster on ISAPI compliant Web servers. Sometimes referred to as PerlIS. Requires ActivePerl and an ISAPI compliant Web server.

    See the Perl for ISAPI page for more information.

PerlScript

    An ActiveX scripting engine which works with any ActiveX scripting host, such as Windows Scripting Host, MS Internet Explorer 4.0+ or MS Internet Information Server 3.0+. Requires ActivePerl and an ActiveX scripting host.

    See the PerlScript page for more information.

PerlEz

    A Dynamic Linked Library (DLL) that allows you to embed a Perl interpreter under Windows.

    See the PerlEz page for more information.

ActivePerl Components


PerlScript

  • What is PerlScript?
  • What do I need to run PerlScript?
  • How do I install PerlScript?
  • Why aren't my event handlers called?
  • What is Windows Script Host?
  • Can I write Active Server Pages with PerlScript?
  • What can I do when PerlScript in ASP seems capsized in PWS?
  • What is Global.asa to ASP and PerlScript?
  • Client-side PerlScript
  • How can I configure client-side PerlScript security?
  • Other References

What is PerlScript?

PerlScript is an ActiveX scripting engine that allows you to use Perl with any ActiveX scripting host. At this time, ActiveX scripting hosts include:

  • Internet Information Server 3.0/4.0/5.0
  • Peer Web Services 3.0/4.0
  • Microsoft Internet Explorer 5.0x
  • Windows Scripting Host

What do I need to run PerlScript?

  • ActivePerl
  • an ActiveX scripting host (see above)
  • Windows 200x/NT/XP/Me/9x
  • Perl scripts!

How do I install PerlScript?

When you launch the ActivePerl installer, PerlScript is one of the components you can optionally install. To use PerlScript, ActivePerl must be installed.

Why aren't my event handlers called?

It is possible that case sensitive lookups of event names are being performed. Event name lookups can be made case insensitive by adding the key

    HKEY_LOCAL_MACHINE\SOFTWARE\ActiveState\PerlScript\1.0
    REG_DWORD: NoCaseCompare = 1 (default)
to the Registry.

What is Windows Script Host?

Microsoft advertises Windows Script Host (WSH) as being "a language-independent scripting host for 32-bit Windows operating system platforms". WSH offers a lot to VBScript and JScript developers for whom console type programs have traditionally been difficult to work with. For Perl Developers, the same functionality can be found with a Perl module or extension.

More information can be found in the Windows Script Host tutorial.

What do I need to have so that I can write Active Server Pages with PerlScript?

Active Server Pages, or ASP for short, is a server-side technology that enables you to embed script commands within HTML. ActivePerl and PerlScript are required on the webserver that is providing the webpages, but are not required on the client. However, remember that if you develop Active Server Pages on your local machine, your system is considered to be both the client and the server.

In order to have a web server on Windows 95, users will need the Personal Web Server (PWS), which is freely downloadable as a component included in the NT Option Pack available from Microsoft.

Windows 98/Me users will need to either install this from the CD that comes with Windows 98/Me or download the NT Option pack. Windows XP Pro/NT/200x users will either find it already installed under the name "Internet Information Services", or else they can install it from the CD that came with Windows XP Pro/NT/200x.

Windows XP Home users will need to install the Apache webserver; Windows IIS and PWS are not supported on Windows XP Home.

For more information about how to use the technology, see the Active Server Pages tutorial.

What can I do when PerlScript in ASP seems to work unpredictably in Personal Web Server (PWS)?

There are three widely used solutions when PerlScript and ASP don't function correctly in PWS:

  • Reboot the computer and see if it works
  • Reinstall ActivePerl with PerlScript checked and see if it works
  • If the previous steps fail, reinstall PWS.
PWS and IIS generally set the permissions on virtual directories to allow scripting by default, it is rarely necessary to alter "scripts" permissions on directories. The steps above will solve most problems with scripting.

How does Global.asa relate to ASP and PerlScript?

Global.asa is a file that exists for each IIS application. On PWS, there is only one IIS application, while later versions of the IIS web-server support a number of different IIS applications. Global.asa can be used to declare objects that are given either Session or Application scope within the web service. This should be similar to the following code:

    <script language=perlscript runat=server>
    sub Application_OnStart {
    }

    sub Application_OnEnd {
    }

    sub Session_OnStart {
    }

    sub Session_OnEnd {
    }
    </script>

Then you can put code within the subroutines that create variables, objects, and so forth. The subroutines, or events, will be called at their designated times: Session_OnStart is run when a new session is started, and its OnEnd event is run when the session is ended. The application's start and end signifies the starting and stopping of the webserver.

Client-side PerlScript

Client-Side PerlScript is Perl embedded within your HTML documents. All PerlScript code must be contained between <script language="PerlScript"> and </script> tags.

Client-Side PerlScript also has the added requirement that both ActivePerl and PerlScript must be installed on each computer that will be loading PerlScript pages.

Client-side Perlscript should only be used if you can control the configuration of the computers on which it will be run. If your goal is to build an application that will be used by a large number of users, server-side PerlScript is considerably more practical.

To display something in the browser, use the document object method write(). You can use the write() method with $windows->document->write('any old text').

The sample below is another Hello World variation, but this time using client-side PerlScript:

    <html>
    <head>
    <title>PerlScript Hello World!</title>
    </head>
    <body bgcolor="#ffffff">
    <h2>PerlScript Hello world!</h2>
    <script language="PerlScript">
    $window->document->write('Hello world!');
    </script>
    </body>
    </html>

How can I configure client-side PerlScript security?

PerlScript in IE 4.0 and higher can be enabled/disabled by zones

    HKEY_LOCAL_MACHINE\SOFTWARE\ActiveState\PerlScript\1.0
    REG_DWORD: EnabledZones = 0x0010 (default)

Values

  • Enable All 0x0001
  • Enable Local 0x0010
  • Enable Internet 0x0020
  • Enable Trusted 0x0040

Note: By default, PerlScript is only enabled in IE's Local zone. Enabling PerlScript any other zones is not recommended. It allows websites to execute Perl code on the local machine as the current user.

Other References

Another PerlScript FAQ available on the net can be found at:

  • The Perl-Win32-ASP FAQ. Maintained by Matthew Sergeant.

PerlScript


PerlEz - Perl Host DLL

  • Datatypes
  • PerlEzCreate
  • PerlEzCreateOpt
  • PerlEzDelete
  • PerlEzEvalString
  • PerlEzCall1
  • PerlEzCall2
  • PerlEzCall4
  • PerlEzCall8
  • PerlEzCall
  • PerlEzCallContext
  • PerlEzSetMagicScalarFunctions
  • PerlEzSetMagicScalarName
  • Format String
  • Error Codes
  • Authors

This document attempts to describe the functions of the PerlEz host Dynamically Linked Library (DLL). Please refer any questions or comments to the author below.

Datatypes

PerlEz has one specific data type, PERLEZHANDLE; this is a non-zero handle to a Perl interpreter that is created and can be accessed by the routines described below.

PerlEzCreate

 PERLEZHANDLE PerlEzCreate(LPCSTR lpFileName, LPCSTR lpOptions);
DESCRIPTION:
  • Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls. Multiple interpreters can be created, but only one will be executing at a time.

    PARAMS:
  • lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL

  • lpOptions a pointer to a ASCIIZ string that are the command line options that will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.

    RETURNS:
  • A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

    See also PerlEzDelete PerlEzCreateOpt

    • PerlEzCreateOpt

     PERLEZHANDLE PerlEzCreateOpt(LPCSTR lpFileName, LPCSTR lpOptions, LPCSTR lpScriptOpts);
    DESCRIPTION:
  • Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls. Multiple interpreters can be created, but only one will be executing at a time.

    PARAMS:
  • lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL

  • lpOptions a pointer to a ASCIIZ string that are the command line options that will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.

  • lpScriptOpts a pointer to a ASCIIZ string that are the command line options that will be provided as parameters to the script; can be NULL.

    RETURNS:
  • A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.

    See also PerlEzDelete PerlEzCreate

    • PerlEzDelete

     BOOL PerlEzDelete(PERLEZHANDLE hHandle);
    DESCRIPTION:
  • Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate or PerlEzCreateOpt.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

    RETURNS:
  • True if no error false otherwise.

    • PerlEzEvalString

     int PerlEzEvalString(PERLEZHANDLE hHandle, LPCSTR lpString, LPSTR lpBuffer, DWORD dwBufSize);
    DESCRIPTION:
  • Evaluates the string a returns the result in lpBuffer. If there is an error $! is returned in lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpString a pointer to the ASCIIZ string to evaluate

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall1

     int PerlEzCall1(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, LPVOID lpVoid);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid a pointer to a parameter will be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall2

     int PerlEzCall2(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
  LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...2 pointers to parameters that will be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall4

     int PerlEzCall4(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...4 pointers to parameters that will be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall8

     int PerlEzCall8(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4, LPVOID lpVoid5,
   LPVOID lpVoid6, LPVOID lpVoid7, LPVOID lpVoid8);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • lpVoid1...8 pointers to parameters that will be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCall

     int PerlEzCall(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
   LPCSTR lpFormat, ...);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzCallContext

     int PerlEzCallContext(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPVOID lpContextInfo,
   LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, ...);
    DESCRIPTION:
  • Calls the function lpFunction and returns the result in the buffer lpBuffer.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpFunction a pointer name of the function to call

  • lpContextInfo context info for magic fetch and store functions

  • lpBuffer a pointer to the buffer where the result will be placed

  • dwBufSize the size in bytes of the space where lpBuffer points

  • lpFormat a pointer to the parameter specifier; can be NULL. See Format String

  • ... parameters to be interpreted based on lpFormat

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    • PerlEzSetMagicScalarFunctions

     int PerlEzSetMagicScalarFunctions(PERLEZHANDLE hHandle, LPFETCHVALUEFUNCTION lpfFetch,
                LPSTOREVALUEFUNCTION lpfStore);
    DESCRIPTION:
  • Sets the call back function pointers for magic scalar variables.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • lpfFetch a pointer to the call back function for fetching a string. if lpfFetch is NULL, then the scalar is write only.

  • lpfStore a pointer to the call back function for storinging a string. if lpfStore is NULL, then the scalar is read only.

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes NOTE: if lpfFetch and lpfStore are both NULL, then it is an error.

    See also PerlEzSetMagicScalarName

    • PerlEzSetMagicScalarName

     int PerlEzSetMagicScalarName(PERLEZHANDLE hHandle, LPCSTR pVariableName);
    DESCRIPTION:
  • Creates the variable if it does not exists and sets it to be tied to the call back function pointer for magic variables.

    PARAMS:
  • hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt

  • pVariableName a pointer to the name of the variable.

    RETURNS:
  • A zero if no error; otherwise error code. See Error Codes

    See also PerlEzSetMagicScalarFunctions

    • Format String

    The format string is a series of characters that represents the type of parameters being supplied.

    s
  • this parameter is a pointer to a null terminated string.

    i
  • this parameter is to be considered an integer.

    d
  • this parameter is to be considered a double.

    l[s | i | d]x
  • the next 'x' parameters will be put into an anonymous list of the type specifed. Either 's', 'i', or 'd'

    • Error Codes

    1. More space is needed to return a result

    2. Error string returned in the buffer

    3. More space needed to return the error message

    4. Format string is invalid

    5. Function call caused an exception

    6. Handle is invalid

    7. The second call to PerlEzSetMagicFunction failed

    8. Invalid parameter was passed to the routine

    9. Cannot allocate more memory

    Authors

    This document is maintained by Douglas Lankshear <dougl@ActiveState.com>


Perl for ISAPI

  • What is Perl for ISAPI?
  • What do I need to run Perl for ISAPI
  • How do I install Perl for ISAPI?

What is Perl for ISAPI?

Perl for ISAPI is a plug-in designed to run Perl scripts faster on ISAPI compliant Web servers. Requires ActivePerl and an ISAPI compliant Web server such as Microsoft Internet Information Server 3.0+.

What do I need to run Perl for ISAPI?

  • ActivePerl
  • an ISAPI compatible Web server
  • Perl scripts!

How do I install Perl for ISAPI?

When you launch the ActivePerl installer, Perl for ISAPI is one of the components you can optionally install. You must install, or have previously installed, ActivePerl to use Perl for ISAPI.

Other References

The ActivePerl FAQ has a useful section on Perl for ISAPI. You can find it here.

Perl for ISAPI


ActivePerl Components

Welcome to PerlEx

PerlEx is an ISAPI plugin for the IIS web server which increases the performance of CGI programs written in Perl. Much as mod_perl works with Apache, PerlEx works with IIS to precompile scripts and add extended functionality such as embedding capabilities and persistent data connections.

Using PerlEx

Getting Started with PerlEx
 Provides an overview of the steps required to get up and running with PerlEx.

WebServer Configuration
 Describes how to configure your WebServer for maximum PerlEx performance.

Coding With PerlEx
 Explains how to optimize your scripts for PerlEx.

Troubleshooting
 Where to go if you encounter any problems while using PerlEx.


ActivePerl Components

Getting Started with PerlEx

  • PerlEx Example Scripts
  • Deploying Your Own Scripts

Getting Started with the PerlEx Examples

PerlEx includes a number of examples to help you get started. To run the examples, click the Examples tab at the top of the Table of Contents pane.

Note: the examples assume that PerlEx is installed on this machine, and that the address http://localhost/PerlEx/scriptname is valid.

If you have difficulties running the following examples, see the FAQ entry I can't get any of the samples to work, what should I do?.

About the Examples

By default, during the PerlEx installation routine, PerlEx associates the file extensions ".plex" and ".aspl" with PerlEx. Additionally, PerlEx creates a virtual directory mapping with the appropriate permissions to the directory <PerlPath>/eg/PerlEx (where <PerlPath> is the location of your ActivePerl installation).

  • PerlEx Examples The PerlEx Examples page shows how to deploy an embedded Perl script.
  • Benchmarks The Benchmarks page provides a number of performance tests that illustrate the speed improvements gained from using PerlEx.

Deploying Your Own Scripts

First, read How PerlEx Works. This describes the PerlEx precompiler, threading behavior and interpreter classes.

Second, ensure that your scripts adhere to PerlEx's extension format. By default, scripts with the extension ".plex" (standard scripts) and ".aspl" (embedded scripts) are handled by PerlEx. To add additional extensions, refer to the Script Mappings section of the Web Server Configuration topic.

Third, optimize your scripts to work with PerlEx.

  • Refer to Coding with PerlEx for information about adapting scripts to take full advantage of PerlEx.
  • There are numerous topics in the PerlEx FAQ that discuss the migration of scripts to PerlEx.

If necessary, create Interpreter Classes to segregate scripts as you optimize them for PerlEx. Using Interpreter Classes, you can configure the Interpreter value for one or more scripts. See the PerlEx FAQ.


ActivePerl Components

How PerlEx Works

The PerlEx Precompiler

When your web server receives its first request to execute a Perl script, PerlEx is loaded. PerlEx then runs its precompiler on the Perl script, which executes any operations within BEGIN blocks or use statements, compiles the main body of the Perl script, and retains the compiled state of the script in memory. The compiled state of the script is then executed by PerlEx.

The second time that the same Perl script is requested, PerlEx simply executes the compiled state of the script which is memory-resident - it is not necessary to go through the compilation phase again. This accounts for much of the performance increase PerlEx has over standard CGI Perl scripts.

Note that the first execution of any PerlEx script will not be as fast as those that follow, as the script will be compiled by the PerlEx precompiler the first time it is requested.

When the total number of times an individual Perl interpreter has been used to execute scripts reaches the number defined by the Reload registry entry, all of the END blocks will be run for each precompiled script, the compiled state of the script will be released from memory, and the Perl interpreter will be reinitialized. Reloading interpreters ensures that arbitrary Perl scripts that might accumulate small amounts of memory for each request do not eventually make the system run out of memory. If you are sure your scripts do not have such memory leaks, you could increase this value, though the benefit of doing so will usually be negligible.

Threading Behavior

Normally, PerlEx runs scripts in the same thread of execution that called into it. Such threads are created and managed by the web server, and their numbers are determined by the web server based on available resources and current load on the server. However, if the MinThreads registry option is set to a particular number greater than 0, PerlEx will create its own pool of threads to process incoming requests. Under this scenario, the incoming web server thread can return immediately while PerlEx is processing the request. PerlEx will subsequently notify the web server when it has finished processing the request, and is ready to hand the response back to the web server. Making PerlEx use its own pool of threads in this fashion can be advantageous in many situations, most notably those involving COM objects that are capable of executing in the Multi-Threaded Apartment (MTA) thread model.

PerlEx can dynamically alter the number of threads automatically based on prevailing demand and load conditions; if the number of requests exceeds the MinThreads setting and the CPUs have spare capacity, PerlEx will create additional threads to service these requests. The total number of such threads is only limited by the total number of Interpreters configured. Any additional requests over and above the available number of threads will be queued up and processed in the order they were received, as threads become available.

Interpreter Classes

The run time characteristics of PerlEx can be controlled by specifying parameters that apply to a group of interpreters that must be used to serve one or more scripts. A set of such parameters is referred to in this document as an Interpreter Class. The Interpreters option in an Interpreter Class specifies how many Perl interpreters are exclusively devoted to serving scripts in that Interpreter Class. When there are more requests for script execution than there are interpreters in a particular Interpreter Class, PerlEx will make the additional requests wait until interpreters become available.

An Interpreter Class with the Interpreters option set to 0 will not precompile any scripts found matching its ScriptLocation setting. This is similar to the functionality of the Noload registry entry in older versions of PerlEx, and closely matches the behavior of regular CGI scripts, and scripts run under Perl for ISAPI. Enabling this option disables many of the performance benefits of PerlEx over CGI, but it can be useful for Perl scripts that cannot run properly with PerlEx, due to various coding issues that must be considered in the PerlEx environment.

For more information, please see:

PerlEx Interpreter Classes

WebServer Configuration

BEGIN and END blocks

Embedding Perl in HTML files

PerlEx Precompiler

Registry Entries

Reload & ReloadAll functions


ActivePerl Components

WebServer Configuration

Installation and configuration of PerlEx requires that you have administrator privileges on the computer that is hosting the target web server.

    Script Mapping on Microsoft IIS 5 servers
    Directory Mapping on Microsoft IIS 5 servers

Microsoft Internet Information Server 5

Script Mapping on IIS5

During installation, you had the option to add the .plex and .aspl file extensions as script mappings. If you did not do so, or if you wish to add additional mappings, follow the instructions below.

To configure script mappings, select Internet Services Manager from the Administrative Tools menu in the Windows Control Panel.

  1. In the Tree panel on the left, right-click the web site you wish to configure.
  2. Select Properties.
  3. Click the Home Directory tab.
  4. Click the Configuration button in the Application Settings section.
  5. Click Add.
  6. In the Executable field, enter <Perl/bin>/PerlISEX.dll, where <Perl/bin> is the path to your PerlEx installation.
  7. In the Extension field, enter the file extension you would like associated with PerlISEX.dll.
  8. Click OK to accept the new Script Mapping.

Directory Mapping (Virtual Directories) on IIS 5

During installation, you had the option to create a virtual directory containing PerlEx examples. If you did not do so, or if you wish to add another virtual directory, follow the instructions below.

To create a virtual directory, select Internet Services Manager from the Administrative Tools menu in the Windows Control Panel.

  1. In the Tree panel on the left, right-click the web site you wish to configure.
  2. Select New|Virtual Directory.
  3. Enter the alias you wish to use for the directory.
  4. Click Next.
  5. Enter the path to the physical directory you want to use, e.g. <PerlPath>/eg/PerlEx, where <PerlPath> is the path to where ActivePerl is installed.
  6. Click Next.
  7. Select Read, Run scripts and Execute.
  8. Click Finish.


ActivePerl Components

PerlEx Interpreter Classes

PerlEx can create a configurable number of Perl interpreters to run your CGI scripts. The phrase Interpreter Class is used in this document to identify the set of run time parameters that are applied as a whole to a group of interpreters that are designated to run one or more scripts.

Run time options for PerlEx are specified in the Windows registry, under the following key:

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>]

The parameters that make up an Interpreter Class are specified in keys under the key "Classes". For example, the parameters for the XYZ Interpreter Class live under the following registry key:

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>/Classes/XYZ]

The following run time parameters can be specified for each Interpreter Class:

  • ScriptLocation: The full or partial path prefix used to identify scripts that belong to this Interpreter Class (required).
  • Interpreters: The number of Perl interpreters to set aside for executing scripts in the ScriptLocation for this Interpreter Class (optional).
  • CommandLineOptions: The arguments passed to the Perl interpreters that will be created for for executing scripts (optional).
  • Environment: Additional environment variables that must be set while executing scripts (optional).
  • Reload: The number of times interpreters in this Interpreter Class will execute requests before being reinitialized (optional).
  • Trace: The detail level of messages written to the PerlEx log file for requests executed by interpreters in this Interpreter Class (optional).
  • EnableCGIHeader: Whether or not CGI status headers should be emitted by PerlEx (optional).
  • EnableDebugOutput: Whether or not output that normally goes to a log file should also be sent to the browser (optional).
  • EnableReadAhead: Whether to completely read all the request data sent by the client before allocating an interpreter to process it (optional).
  • DisableImpersonate: Whether PerlEx should execute the request within the security context of the web server, rather than that of the user making the request (optional).
  • DisableThreadPool: When the global thread pool is enabled, whether to use it for running scripts within this Interpreter Class (optional).
  • ReadAheadMemorySizeLimit: When read-ahead is enabled, how much memory to use as buffer for the read-ahead data (optional).
  • ReadAheadFileSizeLimit: When read-ahead is enabled, how much storage space to use as buffer for the read-ahead data (optional).
  • OverLimitFileName: A response to send to the client when read-ahead is enabled and there is insufficient buffer space to hold the read-ahead data (optional).
  • UseAsyncReadAhead: When read-ahead is enabled, whether to read the request data asynchronously, provided the web server supports doing so (optional).

If no Interpreter Classes are defined, or for scripts whose location does not match the ScriptLocation entry of any of the defined Interpreter Classes, PerlEx applies the parameters in the Default Interpreter Class. The Default Interpreter Class is made up of registry entries at the top level:

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>]

Optional parameters that are omitted in Interpreter Classes also inherit their values from the Default Interpreter Class.

For more information, please see:

Registry Entries

Reload & ReloadAll functions


ActivePerl Components

PerlEx Registry Entries

You can find the PerlEx registry entries in registry key:

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>]

Many of the registry entries specified here can appear either under the top level registry key above, or be associated with an Interpreter Class, or both. Entries under the top level registry key describe the options in the Default Interpreter Class. These options can be inherited by Interpreter Classes that do not override the same options with a corresponding setting within the registry key that describes that Interpreter Class.

CommandLineOptions

STRING or BINARY Value. Commandline Options can be added to alter the configuration of the Perl interpreters that PerlEx starts. Most Perl commandline options can be entered here. For instance, to turn on tainting, you can add -T to the commandline options. This entry is also used to preload Perl modules. For example, to preload the PerlEx::DBImodule, add -mPerlEx::DBI. To enable debugging, add -d.

This can be specified at both the top level key and within registry keys for Interpreter Classes.

DisableImpersonate

DWORD Value. By default, scripts running under PerlEx will execute using the authentication of the client, or the default Anonymous user configured in IIS. If set to non zero, scripts will run as the user the IIS Service is configured to run under, which is typically system.

The default value is 0 (off).

This registry entry is optional. If not set, it defaults to 0. It can be set both at the top level and within registry keys for Interpreter Classes.

DisableThreadPool

DWORD Value. This option controls whether scripts will use that thread pool or not. If set to 1, PerlEx will not execute scripts using the thread pool managed by PerlEx.

This may be needed for scripts that must execute in the calling web server thread.

The default value is 0 (use of the thread pool is enabled when the thread pool is available). This option can be set both at the top level and within registry keys for Interpreter Classes.

Embed

Contains a key whose name is the extension for files that contain embedded Perl. The default extension is .aspl. The .aspl key contains 3 values: begin, end and decode.

Here are the default values:

name | type | value
begin | String | <%
decode | DWORD | 0
end | String | %>

To associate another file extension with this feature, duplicate the .aspl key, and give the new key a name which corresponds to the new file extension. Include the leading dot in the name.

The Embed key and its contents must be present. It can be set only at the top level registry key.

For more information on embedding scripts with PerlEx see Embedding Perl in HTML files.

EnableCGIHeader

DWORD Value. Determines whether PerlEx adds HTTP headers or not.

Can take the values of 0 and 1. The default value is 1 (on).

When EnableCGIHeader is set to 1, PerlEx will emit Server: and Date: HTTP header lines.

If you are using Server Side Includes in the documents which you are serving with PerlEx, set EnableCGIHeader to 0 (off).

If you see HTTP header information appearing in the body of the client browser, you should change EnableCGIHeader registry entry to 0.

If EnableCGIHeader is set to 0, you are responsible for outputting all HTTP headers.

This registry entry is optional. If not set, it defaults to 1. It can be set both at the top level and within registry keys for Interpreter Classes.

EnableDebugOutput

DWORD Value. Determines if information that normally goes to the PerlEx log files is sent to the browser or not.

Can take the values of 0 and 1. The default value is 0 (off).

This registry entry is optional. If not set, it defaults to 0. It can be set both at the top level and within registry keys for Interpreter Classes.

EnableReadAhead

DWORD Value. If non-zero, enables web server read-ahead for processing the request. Read-ahead improves the handling of large POST requests that might otherwise tie up PerlEx interpreters for the duration it takes for the request to be sent over the network. On the other hand, enabling read-ahead results in increased memory consumption on the server, because all of the read-ahead data must be buffered before it can be processed.

When serving a POST request, PerlEx will attempt to read all of the request before acquiring an interpreter, subject to the following limits:

  • If the amount of data in the request is less than ReadAheadMemorySizeLimit, the data will be stored entirely in memory.
  • If the amount is less than ReadAheadFileSizeLimit, the data will be stored in a temporary file on disk.
  • If ReadAheadFileSizeLimit is equal to or less than ReadAheadMemorySizeLimit, only memory will be used.
  • If the amount that the client sends exceeds the larger of ReadAheadMemorySizeLimit and ReadAheadFileSizeLimit, PerlEx will refuse the request and send the contents of the file specified by OverLimitFileName, if it exists. If the file doesn't exist, PerlEx will return an error to the web server.

This registry entry is optional. If not set, it defaults to 0 (off). It can be set both at the top level and within registry keys for Interpreter Classes.

See OverLimitFileName, ReadAheadMemorySizeLimit, and ReadAheadFileSizeLimit

Environment

STRING or BINARY Value. This entry can be used to preset additional environment variables needed by scripts. One use is to set the PERLDB_OPTS variable for debugging scripts running under PerlEx.

Each environment entry is made up of the variable name and its value, separated by a single = character, with no spaces surrounding it. If there are multiple environment entries, they must be delimited with a newline.

Note: newline characters in a registry value can be entered in the Registry Editor (either REGEDIT or REGEDT32) by pressing and holding the ALT key, typing 10 (i.e. one, zero) on the numeric keypad, and then releasing the ALT key. For more information on this method of entering characters, search the Microsoft Windows help documentation for "input characters using ALT numeric keypad".

The default value is the empty string. It can be set both at the top level and within registry keys for Interpreter Classes.

Interpreters

DWORD Value. Sets the maximum number of interpreters that can be created to service requests within a particular Interpreter Class. If set to zero, PerlEx script caching will be disabled, and scripts will be loaded and compiled for every request in a brand new interpreter. This "zero interpreter mode" is useful to provide compatibility for some Perl CGI scripts. See the FAQ for more information.

The default value is 3.

This registry entry is optional. If not set, it defaults to 3. It can be set both at the top level and within registry keys for Interpreter Classes.

LogPath

String value. The path to where the interpreter log files will be written. The log files have the form 'PerlEx-Err-AAAA-NNN.log', where 'NNN' is the ID of the interpreter that created the log, and 'AAAA' is the Interpreter Class name with which the interpreter is associated.

The default value is the directory where PerlEx.dll is located.

This registry entry is optional. It can only be set at the top level registry key.

OverLimitFileName

String value. The path to a file containing information sent to the browser when the amount of read-ahead required to process the request exceeds the larger of ReadAheadMemorySizeLimit and ReadAheadFileSizeLimit. This file is used only if EnableReadAhead is set.

This registry entry is optional. If not set, no notification will be sent. It can be set both at the top level and within registry keys for Interpreter Classes.

ReadAheadFileSizeLimit

DWORD Value. The maximum amount of POST data that will be accepted and backed by a temporary file, specified in bytes.

This registry entry is optional. If not set, it defaults to 0x01000000 (16 MB). It can be set both at the top level and within registry keys for Interpreter Classes.

See OverLimitFileName

ReadAheadMemorySizeLimit

DWORD Value. The amount of POST data that will be backed entirely in memory, specified in bytes.

This registry entry is optional. If not set, it defaults to 0x00200000 (2 MB). It can be set both at the top level and within registry keys for Interpreter Classes.

See OverLimitFileName

Reload

DWORD Value. Determines the number of scripts an interpreter must run before it is reloaded.

This registry entry is optional. If not set, it defaults to 1024 (0x400 hex). It can be set both at the top level and within registry keys for Interpreter Classes.

ScriptLocation

String value. Specifies a partial or full path name where an interpreter can find an executable script or a set of scripts. Paths must be absolute, and either forward or backslashes may be used to separate file and directory components in the path.

When there is more than one Interpreter Class, PerlEx associates a given script with the Interpreter Class that has the most specific ScriptLocation that matches as a valid path prefix for the script. For example, consider three different Interpreter Classes with the following ScriptLocation entries:

  1. C:/foo/bar/baz.plex
  2. C:/foo/baz/
  3. C:\foo\b

A given script C:/foo/bar/baz.plex will match the first Interpreter Class; C:/foo/bar.plex will match the third Interpreter class; C:\foo\baz\xxx.aspl will match the second; and D:\mno\pqr.plex will match the Default Interpreter Class.

This registry entry is mandatory within every Interpreter Class, and can only be set within registry keys for Interpreter Classes.

StartupCode

STRING or BINARY Value. This entry can be used to enter code that you want to have executed at the beginning of every script, during the execution phase.

The default value is empty. It can be set both at the top level and within registry keys for Interpreter Classes.

Trace

DWORD Value. Sets the verbosity of information written to the PerlEx log (PerlEx-Err-NNN.log or PerlEx-Err-AAAA-NNN.log).

Values are 1-4 (1 is minimal feedback, 4 is maximal feedback), 0 is no feedback. The default value is 0.

This registry entry is optional. If not set, it defaults to 0. It can be set both at the top level and within registry keys for Interpreter Classes.

UseAsyncReadAhead

DWORD Value. If non zero, PerlEx will ask the web server to read POST data asynchronously.

This value is only meaningful if EnableReadAhead is enabled.

This registry entry is optional. If not set, it defaults to 0 (off). It can be set both at the top level and within registry keys for Interpreter Classes.


ActivePerl Components

Debugging Scripts Running Under PerlEx

With a few settings, you can enable the Perl debugger for scripts running under PerlEx. This enables you to debug scripts in the environment in which they will be running.

To configure debugging:

  1. Create an Interpreter Class. Set the ScriptLocation to the directory or the file you wish to debug.
  2. Add '-d' to the CommandLineOptions option.
  3. Add PERLDB_OPTS and PERL5LIB variables to the running script Environment. See below for specific instructions regarding setting these values for debugging with Visual Perl, Komodo or the Perl Dev Kit.
  4. Restart the web server.
  5. Set the debugger to listen for connections.
  6. Request the script through your web browser. The debugger should now stop at the first line of the script and allow you to step through it.

Notice that, with the above configuration, the debugger sockets will be kept alive between requests for a given script. This allows you to debug the persistent behavior of your scripts.

If you want to have the socket disconnected at the end of each request, set the Interpreters value to zero for your Interpreter Class, and add the "shebang" line #!/path/to/perl -d to the first line of your script. Note that this will also disable the PerlEx precompiler and any persistence of global variables.

Debugging with Visual Perl, Komodo or the Perl Dev Kit

In Step 3 above, configure the variables as follows:

Visual Perl

PERL5LIB=C:/path/to/VisualPerl/
PERLDB_OPTS=WatcherPort=localhost:WatcherPortNumber RemotePort=localhost:RemotePortNubmer PrintRet=0

Replace WatcherPortNumber and RemotePortNubmer with the port values configured in Visual Perl. The above settings are appropriate for Visual Perl version 1.2. Consult the Remote Debugging section of the Visual Perl User Guide for more information.

Komodo

  1. Copy Komodo's perl debugger and its associated libraries to the remote machine by copying the entire dbgp/perllib sub-directory of the Komodo installation to the new machine, or download a package from the Komodo Remote Debugging page. Note: Do not copy perl5db.pl to the Perl "lib" directory on the remote machine, as this will overwrite the standard perl5db.pl file.
  2. On the remote machine, set the PERL5LIB environment variable to the location of the new perl5db.pl and its libraries. For example, if the remote machine is running Windows and perllib directory was copied to C:\misc\perllib, set the variable as follows:
        set PERL5LIB=C:\misc\perllib

    For example, if the remote machine is running Linux and perllib was copied to the /home/me/perl/komodo_perl_debugging directory, set the variable as follows:

    export PERL5LIB=/home/me/perl/komodo_perl_debugging/perllib
  3. On the remote machine, set the PERLDB_OPTS and DBGP_IDEKEY variables. This tells the Perl interpreter on the remote machine where to connect to Komodo or the DBGP Proxy and how to identify itself.
        PERLDB_OPTS=RemotePort=<hostname>:<port>

    DBGP_IDEKEY=<ide_key>
    • The port number must match the port number specified in Edit|Preferences|Debugger. Click Debug|Listener Status to check the current port.
    • Replace <hostname> with the name or IP address of the machine running Komodo.
    • If DBGP_IDEKEY is unset, the USER or USERNAME environment variable is used as the IDE Key.
    • The variable definitions must be on one line.

Consult the Remote Debugging section of the Komodo User Guide for more information.

Perl Dev Kit

PERLDB_OPTS=RemotePort=localhost:port PrintRet=0

Replace port with the value configured in the Perl Dev Kit debugger (by default, 2000). Note that if the Perl Dev Kit is installed on your system, and you wish to use Visual Perl or Komodo to debug, you may need to disable the PerlSock service. See the Visual Perl or Komodo User Guides for more information.


ActivePerl Components

BEGIN and END blocks

BEGIN and END blocks are a powerful feature in PerlEx. Any code you have in a BEGIN block will be executed only when the script is first compiled. Code in an END block will be executed only when the PerlEx DLL is unloaded, due to server shutdown or inactivity, or if you use either the Reload or ReloadAll functions in your program. Remember, if you put an ordinary Perl exit statement into your PerlEx script, the END block will not be executed.

For more information, please see:

Managing Persistent Connections


ActivePerl Components

Managing Persistent Connections

Using PerlEx::DBI

PerlEx::DBI provides a mechanism to handle persistent database connections within an Interpreter Class, providing better scalability than persisting the connections within a BEGIN block. PerlEx::DBI will cache the database handles used by all scripts that execute within a particular interpreter. As long as the connection information is identical across scripts, the same handle can be reused across scripts executed within the same interpreter. To enable PerlEx::DBI, you must add:

    -mPerlEx::DBI

to the CommandLineOptions setting, or add:

    use PerlEx::DBI ();

to the StartupCode setting.

Your script does not require any modification to work with PerlEx::DBI. See the PerlEx::DBI reference documentation for more information.

Using BEGIN and END Blocks

If you cannot make use of the PerlEx::DBI approach described above, you can create your own persistent database connections using BEGIN and END blocks. The following sample code illustrates how to do it:

    # start of .plex file
    BEGIN {
      use DBI;
      $dbh = DBI->connect('dbi:ODBC:DSN', 'user', 'password');
    }

    <the main body of your Perl code goes here>

    END {
      $dbh->disconnect;
    }

The above example opens a connection to a database in the BEGIN block, keeps it open for the duration of the script, and closes it in the END block.

This method of persisting database connections does not provide all the features of PerlEx::DBI, such as managing connection timeouts.

For more information, see BEGIN and END blocks.


ActivePerl Components

Embedding Perl in HTML files

Similar to Active Server Pages, or .asp files on Microsoft Internet Information Server, the Embed function of PerlEx brings the functionality of Server Side Includes to your Perl CGI programs. Perl code contained in an Embed file is virtually "transparent" to your HTML editor, so you can edit the HTML in the file with relative ease and immediately see what the page will look like in a browser.

During installation, the following entries are created in your registry:

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx]
    CurrentVersion = <version> (REG_SZ)

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>/Embed/.aspl]

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>/Embed/.aspl]
    begin = "<%" (REG_SZ)

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>/Embed/.aspl]
    end = "%>" (REG_SZ)

[HKEY_LOCAL_MACHINE/SOFTWARE/ActiveState/PerlEx/<version>/Embed/.aspl]
    decode = 0 (REG_DWORD)

In the following example, when the server encounters a file with the .aspl extension, it is passed to PerlEx for processing. The begin string value defines the characters which mark or tag the beginning of a segment of Perl code. The end string value defines the characters that indicate the end of a segment of Perl code. The decode DWORD value defines whether PerlEx decodes the files or not. This is useful if you are using an HTML editor that converts characters to their escaped equivalents. In the .aspl example, some editors may convert the ">" characters to "&gt;" within the Perl code segments. The decode DWORD value can take the values of 0 and 1. In the .aspl example, the value is set to 0, or off.

.aspl is just an example. Using its structure as a basis, you can add your own Embed implementation to the registry, and have PerlEx process it similarly to how it processes .aspl files.

All standard Perl constructs are allowed within the Perl sections. Also, the "=" character has a special function when it immediately follows the begin tag. In the case of <%=$x+4%>, the expression $x+4 is converted from <%=$x+4%> to print $x+4;.

A short example of the Embed function using the .aspl instance is listed below:

# file embedTest.aspl
<Html>
<head><title>Embed Demo</title></head>
<body bgcolor=ffffff>
<bold>Counting from 0 to 4!</bold><br>
<%

  # perl code
  foreach $i (0..4) {
    # starts a small loop
%>
<br>
<%=$i%> #loop variable is printed for each number from 0 to 4

<%
  } # end of loop
%>
<br>

<pre>
Finished!
</pre>

</html>

The output of the above file will look like:

Counting from 0 to 4!

0 #loop variable is printed for each number from 0 to 4
1 #loop variable is printed for each number from 0 to 4
2 #loop variable is printed for each number from 0 to 4
3 #loop variable is printed for each number from 0 to 4
4 #loop variable is printed for each number from 0 to 4
Finished!

NOTE: Support for script embedding is currently not available when script caching is disabled by running PerlEx in zero interpreter mode.


ActivePerl Components

Reload & ReloadAll

Two additional built-in functions that are accessible to all scripts executing under PerlEx are Reload and ReloadAll.

Reload

The Reload function causes the current interpreter to reload when the script exits. The interpreter will be reinitialized before the next request processed by that interpreter is executed.

To call the Reload function:

PerlEx::Reload();

Reload can be useful if you know that there is something wrong with a specific interpreter.

ReloadAll

The ReloadAll function causes all interpreters in the Interpreter Class to be reloaded; interpreters belonging other Interpreter Classes will remain unaffected. If the executing script doesn't belong to a named Interpreter Class, all interpreters in the Default Interpreter Class will be reloaded. Interpreters currently in use (i.e. running a Perl program) will reload when the script finishes execution. Interpreters not currently in use will be reloaded immediately.

To call the ReloadAll function:

PerlEx::ReloadAll();

ReloadAll can be useful if you have changed one of your scripts that contains a use or require statement and don't want to restart your server.


ActivePerl Components

Getting your code working with PerlEx

Probably the most important thing to remember when rewriting code to work with PerlEx is data persistence. Since scripts do not "exit", all data stays in memory. If you depend on something to be empty, or filled from the results of previous code, declaring my $variable=""; in the early part of your code will clear up most data persistence errors.

Remember that BEGIN blocks are executed only when the script is compiled, i.e., the first time you run it. This means that you can open your log files, and your data files / data connections and then leave them open until the END block is run, i.e., on server shutdown, or when the script has been run the number of times defined by the Reload registry entry.

For the average user, Perl scripts should run with no changes. You will usually run into these issues only if the script makes assumptions about variables automatically becoming uninitialized when it is finished executing.

Exit handling

When executing a script that returns a non-zero exit value, PerlEx removes the script from its internal memory, and the script will be recompiled before it is next executed. A script that calls exit with the value "0", or with no argument, will not be removed from memory.

Lazy access to CGI and HTTP variables via %ENV

Under PerlEx, like under perl.exe, the environment variable hash %ENV is preloaded at startup with all the system environment variables. However, unlike perl.exe when it is running CGI programs, %ENV under PerlEx does not contain any of the HTTP and CGI variables when the script starts up, since doing this can be an expensive operation.

This means that a script running under PerlEx has to individually fetch each HTTP or CGI variable that it is interested in explicitly. When the script loads, keys(%ENV) will only return the keys from the system environment. After the initial fetch, these values will be cached in %ENV, so a subsequent keys(%ENV) will return the system variables along with any cached HTTP and CGI variables.

The following script illustrates this behavior when run under PerlEx:

#!/bin/perl
print "Content-type: text/plain\n\n";
print "Startup environment:\n";
print "$_=$ENV{$_}\n" for sort keys %ENV;
print "-" x 75, "\n";
my (@list) = qw/GATEWAY_INTERFACE
        HTTPS
        HTTP_ACCEPT
        HTTP_ACCEPT_ENCODING
        HTTP_ACCEPT_LANGUAGE
        HTTP_CONNECTION
        HTTP_HOST
        HTTP_REFERER
        HTTP_USER_AGENT
        PATH
        REMOTE_ADDR
        REMOTE_HOST
        REQUEST_METHOD
        SCRIPT_NAME
        SERVER_NAME
        SERVER_PORT
        SERVER_PROTOCOL
        SERVER_SOFTWARE
        SERVER_URL
        SYSTEMROOT
        CONTENT_LENGTH/;

print "HTTP environment:\n";
print "$_=$ENV{$_}\n" for sort @list;
print "-" x 75, "\n";
print "Cached environment:\n";
print "$_=$ENV{$_}\n" for sort keys %ENV;

PerlEx handling of %ENV, @INC and Perl special global variables

After a script is compiled and ready to be executed, PerlEx saves the script's current %ENV, @INC, and the state of some of its Perl global variables ($@, $!, $,, $/, $\, $^W and $?). Each time the script is subsequently executed, PerlEx restores the state of these variables. Because the state is saved after the script is compiled, but before it is executed, any %ENV, @INC, or Perl global variable changes that take place in the BEGIN block will be in effect every time the script is executed.


ActivePerl Components

PerlEx FAQ

What is PerlEx?

Why are HTTP headers appearing in the browser body?

Why does my Server Side Include produce HTTP headers?

I can't get the samples to work, what should I do?

Can I set up a persistent data connection with PerlEx?

My script worked with perl.exe, but doesn't work with PerlEx, why?

Why don't my scripts that read from the DATA filehandle work?

I edited some of my scripts and now they don't work, why?

When I run PerlEx, I'm not seeing any increase in speed. Why?

How can I check if PerlEx is running from within a script?

How do I optimize print() performance?

Why isn't my required file working properly?

Why do I have unwanted data persistence problems when using certain modules?

My scripts that use CGI.pm don't seem to work, why?

Are there UNIX versions of PerlEx?

Does PerlEx work well with all available CPAN modules?

What is PerlEx?

PerlEx is a web server plugin designed to work with your Windows web server to substantially increase the speed at which your Perl CGI programs are run by the server. PerlEx also enhances the functionality of Perl by adding features such as embedded scripts which are not present in similar products.

Why are HTTP headers appearing in the browser body?

If you see HTTP header information appearing in the body of a client browser that accesses scripts served by PerlEx, you should change the EnableCGIHeader registry entry to 0. The script will then be responsible for outputting all HTTP headers.

Why does my Server Side Include produce HTTP headers?

PerlEx does not distinguish between files which are served up in their entirety and files which are included. If you have EnableCGIHeader set to 1 in the registry, PerlEx will emit HTTP headers for each document which it serves.

If you use Server Side Includes in the documents that you are serving with PerlEx, turn off EnableCGIHeader in the registry, and provide your own HTTP headers for your documents.

I can't get any of the PerlEx examples to work, what should I do?

If the PerlEx example scripts won't run, check the following:

  • The links to the examples from the User Guide call the address http://localhost/PerlEx/scriptname. If you are trying to run the examples from a machine where PerlEx is not installed, or if the "localhost" name is not valid on your system, manually enter the URL as required.
  • Ensure that the file extensions used for Perl programs have been correctly associated with PerlEx. See Web Server Configuration for information on configuring Script Mappings.
  • Ensure that the PerlEx Virtual Directories are correctly identified and have the appropriate permissions. See Web Server Configuration for information on Directory Mapping.
  • Manually stop and re-start your web server.

Can I set up a persistent data connection with PerlEx?

Yes. See the section on Persistent Connections in the documentation for more info.

My script worked with perl.exe, but doesn't work with PerlEx, why?

Try setting the Interpreters registry entry to 0. Some Perl programs may not be compatible with PerlEx, because they may not be initializing themselves correctly at startup.

You can isolate such scripts in a particular directory and specify an interpreter class for these scripts. Thus, other scripts that don't have this problem can continue to get the benefits of PerlEx.

Why don't my scripts that read from the DATA filehandle work?

PerlEx uses Perl's eval() operator to precompile scripts. This operator does not keep a reference to the source text in memory, since doing so would cause a memory leak. Since the DATA filehandle relies on the source text after the __END__ or __DATA__ tokens being available at run time, this does not work under PerlEx.

Note that __END__ and __DATA__ tokens in your scripts are harmless as long as your script either does not rely on the DATA filehandle, or knows how to deal with the DATA filehandle being unavailable.

You have two choices to deal with this issue:

  1. rewrite your script to not rely on the DATA filehandle
  2. move these scripts into a separate folder and add an interpreter class for this folder, and set the Interpreters entry to 0.

I edited some of my scripts and now they don't work, why?

PerlEx normally compares the file timestamp of a script with the time it was last compiled and reloads it if it has changed since the last time it was compiled.

However, this only works for scripts launched directly by PerlEx. If you change a script that has been referenced by a require or use statement, you will either have to stop and restart the server, or use the Reload function within the script for it to work properly.

When I run PerlEx, I'm not seeing any increase in speed. Why?

The first time PerlEx runs one of your scripts, it will always be slow, as it is precompiling them, but every time you run them after that, you should experience a noticeable increase in speed.

If the problem persists, check to make sure of the following:

  1. The Interpreters registry entry should not be set to 0. This entry should be set to 0 only within specific interpreter classes that are deliberately meant to not cache scripts that are at a particular location. Setting this entry in the default interpreter class (i.e. at the top level of PerlEx registry settings) will disable caching for all scripts run by PerlEx that don't match an interpreter class with an overriding setting.
  2. The script should not exit with a non-zero status, either by calling exit() with a non-zero argument, or by throwing an exception, for example, by calling die(). Under those circumstances, PerlEx will flush its cache for that script and recompile it during the subsequent request, resulting in the observed degradation in performance.
  3. The web server is properly configured to run the script under PerlEx. Make sure that ISAPI caching has not been disabled.

Setting the Trace registry entry can help debug some of these issues.

How can I check if PerlEx is running from within a script?

You can check if PerlEx is running from within a script by adding the following:

if (exists $ENV{'GATEWAY_INTERFACE'}
    and $ENV{'GATEWAY_INTERFACE'} eq "CGI-PerlEx")
{
    ...
}

This test actually indicates that the script has been cached by the PerlEx compiler. When scripts are running under PerlEx with no caching, i.e., the Interpreters registry entry is set to 0, this test will return false because PerlEx behaves just like regular CGI or Perl for ISAPI under this setting.

How do I optimize print() performance?

My script makes many calls to print, and PerlEx does not seem to be a lot faster than regular Perl CGI when running it. How do I optimize print() performance?

Outputting data is a relatively expensive operation, whether it is a regular Perl CGI script, or one running under PerlEx. While most scripts will not be affected to any significant degree by this fact, any Perl script that performs many calls to print will see an increase in speed by gathering as much data as possible before calling print. Perl makes this easy by providing the '.=' operator.

For example, if the following code:

$data = "Hello";
print $data;
$data = " world";
print $data;
$data = "\n";
print $data;

is rewritten as:

$data = "Hello";
$data .= " world";
$data .= "\n";
print $data;

it will execute faster, whether it is running with Perl or PerlEx.

An additional point to note is that PerlEx output is unbuffered--every print statement results in output from the web server. While this gives the programmer precise control over what gets sent from the web server, it also imposes a slight penalty on execution time when many print statements are used in a script.

Why isn't my file loaded with require working properly?

Example: A common file, C.plex, is included (via a require statement) by two other scripts, A.plex and B.plex. The first time either A.plex or B.plex is run, the script works, but then the other script won't run.

The problem here is a namespace issue. Once script C.plex is loaded by either script A.plex or by script B.plex, its data and subroutines become part of the calling script's namespace, if C.plex does not contain a namespace declaration.

The solution is to declare a namespace in C.plex using a package declaration. C.plex will look like this:

package C;
sub foo
{

[your code here...]

}

A.plex and B.plex need to access subroutines in package C by using the following syntax:

C::foo(...);

In general, it is good Perl programming practice to explicitly declare a namespace in any file that will be loaded by other scripts.

Why do I have unwanted data persistence problems when using certain modules?

Some modules on CPAN use global variables which will persist when using PerlEx. If you discover that this is the case, and if the module does not have a way for you to initialize its data, you may wish to add the scripts which use these modules to an interpreter class that has the Interpreters registry entry set to 0. This is known as running the script in "zero interpreter mode". Note that doing this will make PerlEx not precompile the script anymore, and therefore it will execute significantly slower.

My scripts that use CGI.pm don't seem to work, why?

If you use the CGI.pm package in your scripts, we recommend using CGI.pm version 2.56 or higher.

There are some specific issues to be aware of when using CGI.pm because global data is persistent across script invocations when running PerlEx. ActiveState works with the author of CGI.pm on an ongoing basis to ensure compatibility of PerlEx and CGI.pm.

You can avoid global data persistence problems by using the object interface. New CGI objects should be created like so:

my $cgi = CGI->new();

Thus, instead of this code:

use CGI qw/:standard/;
$aVariable = param('value');

you should create a CGI object:

use CGI qw/:standard/;
my $cgi = CGI::->new();
$aVariable = $cgi->param('value');

Do not create more than one CGI object in your scripts because when doing a POST, after the first CGI object is created, subsequently created CGI objects will not contain the posted data.

When using the functional interface to CGI.pm, you should call the following function before your script exits:

CGI::initialize_globals();

This will make sure that CGI.pm initializes its internal global variables and handles future invocations of your script correctly. This function must be called regardless of the path of execution in your script, otherwise your script will work against the data from the previous invocation of the script.

The alternative to taking these precautions is to run the scripts at an Interpreters setting of 0, thereby losing the performance advantages of PerlEx caching.

Are there any Unix versions of PerlEx™?

There are currently no PerlEx Unix versions available.

Does PerlEx work well with all available CPAN modules?

PerlEx requires that all code loaded by executing scripts be thread-safe. Some CPAN extensions (Perl modules that contain XS code) are not thread-safe, and could cause problems running under the PerlEx environment, especially under heavy load.

Any CPAN module written in pure Perl (i.e., that does not contain XS code) will work fine under PerlEx. In addition, ActiveState has worked with the authors of the following extensions to make them thread-safe:

  • DBI
  • DBD::*
  • GD
  • Storable
  • SHA
  • Win32::OLE

Any other extensions should be used with some degree of caution. If you have any concerns about the thread-safety of a particular extension, try reading the archives of the PerlEx mailing list, or posting your concerns to the list.

ActiveState is committed to ensuring that PerlEx works well with common extensions our customers rely on; when problems are brought to our attention, we will work with the extension authors to resolve the problem.


ActivePerl Components

Troubleshooting

If you are having problems getting your scripts to work with PerlEx, there are several things you can do.

If you change Perl programs that have require or use statements in them, you will have to stop and restart your web server for them to work properly.

Certain modules use global variables, and may cause unwanted data persistence problems. Becoming familiar with the modules which you use will assist in solving your problems in using your scripts with PerlEx.

For more information, see:

PerlEx FAQ

Event Log and Error Messages


ActivePerl Components

PerlEx Precompiler

Before a Perl script is executed, the precompiler compares the last modification time of the script file against the last time it was compiled and cached by PerlEx. If the modification time is more recent, the PerlEx precompiler throws away the cached state, recompiles, and caches the compiled state of the script. The cached state of the script is then executed.

This ensures that PerlEx recognizes any changes to the script that you may make while PerlEx is running. However, any files or modules loaded by the script via require or use will not be reloaded by PerlEx in this way. If you change any modules used by your scripts, restart the web server or reload the PerlEx interpreters.


ActivePerl Components

Event Log and Error Messages

PerlEx records runtime information in two places – to the Windows Event log, and to the file PerlEx-Err-ClassAAAA-NNN.log, which is located in the Perl\bin directory. When PerlEx encounters an error or other noteworthy event, an entry is written in the Windows NT Event log file (please refer to your Windows NT/2000 documentation for information regarding the Windows NT/2000 Event log). This entry will only indicate that an error has occurred. To find more detailed information regarding what actually happened, it may be helpful to look at the PerlEx log files. The verbosity of the information written to the PerlEx log files is set through the Trace Registry entry.

PerlEx log file names are of the form PerlEx-Err-ClassAAAA-NNN.log, where NNN is the interpreter number and ClassAAA is the class name associated with that interpreter. Log files for interpreters in the Default Interpreter Class are of the form PerlEx-Err-NNN.log. These log files may be found in the location identified by the LogPath registry entry, or if that is not set, in the same directory as PerlEx.dll.

Each interpreter is assigned a unique number when it is created. These numbers begin at 0, and are numbered sequentially across all Interpreter Classes.

All messages sent to PerlEx log files have the form:

*** <script name> log message at: YYYY/MM/DD/HH:MM:SS

<script name> is present only if the script generating the message is not a precompiler script.

Event Log Messages

PerlEx.dll attached by process; ID: <number>

<number> is the process ID of the application that loaded or unloaded PerlEx.

Event Log Warnings

Script error(s) from PerlEx.dll logged in: <path>/PerlEx-Err-ClassAAAA-NNN.log

Anything written to STDERR will be logged in the file Perl\bin\PerlEx-Err-ClassAAAA-NNN.log.

Event Log Errors

Problem: PerlEx.dll was unable to open PerlEx-Err-ClassAAAA-NNN.log

Cause: The file PerlEx-Err-ClassAAAA-NNN.log is missing or open by another application.

Problem: PerlEx.dll was unable to load <path>/<filename>.dll

or

Problem: HTTP/1.0 500 Server Error (A dynamic link library (DLL) initialization routine failed.)

Cause: A DLL file is either missing, or it resides in an incorrect directory or in a directory which is not mentioned in your PATH environment variable.

Problem: PerlEx: Exception during script initialization.

Cause: Perl was unable to evaluate your script. This message is reported in the Event log.

Problem: PerlEx: Exception during execution of script '<script name>'

Cause: Perl was unable to execute your script. This message is reported in the Event log.

Problem: PerlWSEX.dll was unable to load <path>/PerlWSEX.dll

Cause: The PerlWSEX.dll is missing or the path to it is incorrect.

Problem: PerlISEX.dll was unable to load <path>/PerlISEX.dll

Cause: The PerlISEX.dll is missing or the path to it is incorrect.

Problem: PerlNSEX.dll was unable to load <path>/PerlNSEx.dll

Cause: The PerlNSEX.dll is missing or the path to it is incorrect.

Problem: PerlEx.dll was unable to start sockets

Cause: The Windows Sockets DLL was unable to start. There are several possible causes for this: the underlying network subsystem is not ready for communication, your Windows Sockets DLL version is incorrect, Windows Sockets can not support any more tasks, or a blocking sockets operation is in progress.

Perl program errors

Perl program errors are written to the file PerlEx-Err-ClassAAAA-NNN.log. Anything written to STDERR will be logged to this file. The Trace registry entry sets the amount of information recorded.

Any value for the Trace registry entry will give the following messages:

    <script name> script produced no output

    PerlEx: Parse failed in precompiler <script name>!

    PerlEx: Parse exception in precompiler <script name>!

    PerlEx: Unable to create a Perl space for precompiler <script name>!

    No script was supplied to PerlEx.dll

The following messages occur when PerlEx was unable to get a free interpreter, or the Perl program was not precompiled:

    PerlEx: Parse failed on script <script name>!

    PerlEx: PerlCreate failed on script <script name>!

If you set Trace to 1, then PerlEx will add the following messages, should they occur:

    PerlEx: Double exception!

    PerlEx: Error return: <value>

Set the Trace registry entry to 4, and the following messages will be added, should they occur:

    PerlEx: Loaded precompiler: <precompiler name>

    PerlEx: Unloading at count of: <number>

    PerlEx: Executing script: <script name>

    PerlEx: Execute returned: <value>

The following messages occur when PerlEx was either unable to get a free interpreter or the Perl program was not precompiled:

    PerlEx: Parsing script: <script name>

    PerlEx: Executing script: <script name>

    PerlEx: Execution returned: <value>


ActivePerl Components

Reporting Bugs

All bug reports should be accompanied by one or more concrete examples that will help us reproduce the problem. Include all relevant information that you think will help us recreate the particular environment in which the bug was observed. Remember, if we cannot reproduce the problem, we cannot fix it!

To report bugs in PerlEx, please go to the bug page on the ActiveState Web site at: http://bugs.activestate.com/ActivePerl/query.cgi

Questions, Comments and Info

We're interested in what you have to say. Do you have something that used to work that just doesn't work anymore? Any incompatibilities? Let us know by sending an email to ActivePerl-Feedback@ActiveState.com. We can't guarantee that all suggestions will be implemented in future releases, but we'll do our best!

The Perl-Win32-Web mailing list is a public forum for discussion about using Perl on Windows for web applications. Archives of this list can be found on ASPN.


ActivePerl FAQ - ActivePerl Frequently Asked Questions

ActivePerl FAQ Introduction

  • NAME
  • DESCRIPTION
    • About this document

NAME

ActivePerl-FAQ - ActivePerl Frequently Asked Questions (FAQ)

DESCRIPTION

ActivePerl Frequently Asked Questions (FAQ)

About this document

This FAQ was assembled and is maintained by David Sparks of ActiveState.

Parts of this FAQ are based on and include sections from the Perl for Win32 FAQ.

This FAQ will be updated over time. Be sure to check out ASPN for the latest version of this and other FAQs.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

Note that all code examples in this FAQ have been indented to be easy to read. If you cut-and-paste an example to a real Perl script, remember to outdent the code again so that the farthest-left column of code is in the first column. This can be crucial!

All of the trademarks in this document are the property of their respective owners.

Contents of this FAQ

    ActivePerl-faq1: Availability and Installation FAQ
    ActivePerl-faq2: Perl Package Manager (PPM) FAQ
    ActivePerl-faq3: Documentation and Support FAQ

Additions/Changes/Comments

Send email to the FAQ maintainers, at support@ActiveState.com

ActivePerl FAQ


ActivePerl FAQ - Availability and Installation

    • What is Perl?
    • Where can I get tons of information about Perl?
    • Where can I get the ActivePerl interpreter?
    • What do I get with ActivePerl?
    • How do I install ActivePerl?
    • Can I build Perl from the source code?
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq1 - Availability and Installation

DESCRIPTION

Getting, installing, and using Perl.

What is Perl?

Perl is a scripting language widely used for system administration and programming on the World Wide Web. It originated in the UNIX community and has a strong UNIX slant, but usage on Windows has grown rapidly. ActivePerl is a quality-assured binary distribution of Perl for popular UNIX platforms and Windows.

perl (small 'p') is the program used to interpret the Perl language.

Where can I get tons of information about Perl?

Extensive online documentation is included with Perl itself. You can read the documentation with the perldoc command, as in perldoc document_name. You should start with the perl document and the perlfaq document. For information on other ways of accessing the Perl documentation (including HTML versions of this documentation), see Where can I get documentation on ActivePerl?.

To get more information about Perl, check out these URLs:

  • http://www.ActiveState.com - The ActiveState Home Page.

  • http://www.perl.com - The Perl home page.

  • http://dir.yahoo.com/Computers_and_Internet/Programming_and_Development/Languages/Perl/ - The Yahoo Perl page.

There are several good books about Perl. The premier book on ActivePerl for Windows is Learning Perl On Win32 Systems By Schwartz, Olson, and Christiansen (O'Reilly & Associates, 1997). This is the Gecko book, and has a picture of a gecko (little chubby lizard with big toes and a smile) on the front cover.

For general perl, two books to consider are Programming Perl, 3rd Edition, by Larry Wall, Tom Christiansen and Randal L. Schwartz (O'Reilly & Associates, 1996) and Learning Perl, 3rd Edition, by Randal L. Schwartz (O'Reilly & Associates, 1993). These are referred to by Perl enthusiasts as the Camel book and the Llama book, respectively.

If you are new to Perl and there are any terms mentioned in this FAQ that you don't get, try one of the above resources. See the perlbook document that comes with Perl for more information.

Where can I get the ActivePerl interpreter?

ActivePerl is available from the ActiveState home page.

To download ActivePerl from ActiveState, look in this directory:

  http://www.ActiveState.com/ActivePerl

What do I get with ActivePerl?

ActivePerl is a complete, self-installing distribution of Perl based on the standard Perl sources. It is distributed online at the ActiveState site.

"Perl for Win32" generally refers to ActivePerl for Windows.

How do I install ActivePerl?

For complete installation information, see the ActivePerl Installation Guide.

Can I build Perl from the source code?

The Perl source code includes complete instructions on building Perl. You can obtain the latest Perl source from:

    http://www.perl.com/CPAN/src/latest.tar.gz

Once you extract the source, read the README file for instructions on compiling Perl.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn, David Sparks and Michael Smith of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Availability and Installation


ActivePerl FAQ - Documentation and Support

Documentation and Support

  • NAME
  • DESCRIPTION
    • Where can I get documentation on ActivePerl?
    • What kind of documentation comes with ActivePerl?
    • Is there formal support for ActivePerl or PerlIS?
    • Are there information sources available on ActivePerl on
    • Is there a mailing list for ActivePerl or Perl for ISAPI?
    • Is there a Usenet newsgroup devoted to ActivePerl?
    • Is there a FAQ for ActivePerl?
    • How do I report a bug in ActivePerl?
    • Can I ask a question? ... or ... How do I ask a question?
    • Are there any live chats where I can talk about Perl stuff?
  • AUTHOR AND COPYRIGHT

NAME

Documentation and Support

DESCRIPTION

ActivePerl Documentation and Support

Where can I get documentation on ActivePerl?

Documentation for ActivePerl is provided in HTML format in the html directory in your perl directory. This has the documentation from the standard perl distribution, as well as the complete documentation for modules and extensions. For more information on Win32-specific extensions, see What modules come with the ActivePerl distribution?.

Note that the standard perl distribution documentation (perl*.html) has some UNIX-specific information, and lists some features/functions that will not work on the Windows version of ActivePerl. The perlwin32 and perlport pages discuss the portability issues under the Win32 platform.

You can also read the Perl documentation with the perldoc command. At the command prompt, type perldoc followed by the name of the document you want to read, as in:

    perldoc perlwin32
    perldoc perlfaq

Documentation is provided in the binary distributions (it is created during install), and can be created by install or it can be made by "make installhtml" in the source distribution.

What kind of documentation comes with ActivePerl?

ActivePerl comes with the standard Perl documentation, as well as documentation for all Core modules.

Is there formal support for ActivePerl or PerlIS?

Peer support is available from the Perl-related mailing lists that ActiveState hosts. You can find more information on these mailing lists at http://www.ActiveState.com/support/

Support for applications and internals is available through customized professional services. Contact us at http://www.ActiveState.com/Professional_Services for a quotation.

ActivePerl Enterprise Edition offers corporate support solutions for Perl. ActivePerl Enterprise Edition provides the comprehensive support that an enterprise needs to deploy Perl.

Are there information sources available on ActivePerl on the World Wide Web?

There are several web pages devoted to ActivePerl. Here is a short listing:

  • http://www.ActiveState.com/ - The ActivePerl home page.

  • http://www.ActiveState.com/support - Introductory information, FAQs, mailing lists, and more.

  • http://dada.perl.it/ - Aldo Calpini's page, which includes many links, modules for Win32, and more.

  • http://www.geocities.com/SiliconValley/Park/8312/ - Robin Chatterjee's Perl for Win32 page, which includes FAQs, links, etc.

  • http://www.northbound-train.com/perlwin32.html - Joe's Perl for Win32 Page, which has general information, pointers to modules, etc.

Is there a mailing list for ActivePerl or Perl for ISAPI?

ActiveState hosts a variety of mailing lists for the ActivePerl community. More information can be found at http://www.ActiveState.com/support/mailing_lists.htm

Archives of the mailing lists can also be found on the ActiveState web site.

You should check the archives or a FAQ like this (see Is there a FAQ for ActivePerl?) before posting a question to the mailing list. List members are mostly overworked programmers and admins like yourself. So, for best results, be courteous, specific, and show that you really have tried to figure out your problems for yourself.

Is there a Usenet newsgroup devoted to ActivePerl issues?

Not yet. You can use comp.lang.perl.misc for miscellaneous Perl questions; the members of most Usenet Perl newsgroups tend to concentrate on UNIX platforms.

Try the perl-win32-users mailing list (see Is there a mailing list for ActivePerl or PerlIS?) for more specific Win32 information.

For web server setup and CGI programming, try one of the following three newsgroups:

    comp.infosystems.www.servers.ms-windows
    comp.infosystems.www.authoring.cgi
    comp.infosystems.www.authoring.misc

Is there a FAQ for ActivePerl?

You are reading one of them. Also, Perl is shipped with the main PerlFAQ inside the help system, which is over a hundred pages long and split into several parts.

Robin Chatterjee's Perl for Win32 page contains frequently asked questions and copies of the perl-win32-users mailing list responses to them:

    http://www.geocities.com/SiliconValley/Park/8312/

How do I report a bug in ActivePerl?

The ActiveState bug reporting system can be found at http://bugs.ActiveState.com

Before you report a bug to this location, you need to do several things:

  • Make sure it's a real bug, and not a logic error in your program.

  • Make sure it's a real bug, and not just a misunderstanding about how Perl works. Check the mailing list archives and FAQs, so you can see if someone else has come across this problem. ALWAYS do this first, even if you are otherwise certain that it is a real bug. Most bugs reported to ActiveState are not bugs and could be solved by looking through the list archives or FAQs.

  • You can also use http://groups.google.com/ to search comp.lang.perl.misc. If this is a problem that has been discussed in the newsgroup, your answer may be there. After exhausting these possibilities, you may want to post to one of the mailing lists to see if other people might have an answer. See also Can I ask a question? ... or ... How do I ask a question?

  • You should check the bug list to see if your bug has already been reported or fixed.

  • You need to be able to reproduce the bug. If it just happens once, then it is not a bug. This needs to be clear: if it can't be repeated then it is not a bug.

  • Create a short, simple script as an example of the bug. Do not send the original source code as your example - do what you can to reduce the example to the smallest possible case. This process has been known to reveal errors that have been cleverly masquerading as bugs.

  • It should not be necessary to do much setup for ActiveState bug testers to reproduce your bug. If setup or example data files are required, prepare simple instructions.

  • Once all this is done, you should send your bug report to ActiveState, stating clearly the nature of the bug, how to reproduce it, and what platform, operating system, and perl version is causing the problem. Remember that your goal is to give ActiveState enough information to reproduce the bug. If it is not reproducible, it can't be considered a bug.

  • You should get email about the status of your bug as it goes through the process of verification and fixing.

  • Do not submit the same bug more than once.

    Submit bugs here.

Can I ask a question? ... or ... How do I ask a question?

The etiquette for asking questions is about the same whether you're working with mailing lists, newsgroups, chatrooms, or IRC channels. Here are some pointers that will help you get your questions answered.

  • Do your own study before you ask a question. Buy a book (or more than one... O'Reilly has lots to choose from), read the online help, and search the web for yourself. If you don't have time to try to find find the answer yourself, these folks won't have time to answer you.

  • Check the FAQ first - if the question has already been answered in the FAQ, you may not get an answer to it if you ask it in a public forum.

  • Never ask, "Can I ask a question?", because that is a sure sign that the person doing the asking is a newbie. People on IRC and newsgroups get bored with newbies because they always seem to ask and never seem to do their own study.

  • Read the mailing list or newsgroup for a while before you ask a question. If you need to ask a question immediately, and you've never read the newsgroup or mailing list, read the mailing list archives or use http://groups.google.com/ to read old messages posted to the newsgroup. This will familiarize you with the way people ask questions in the particular newsgroup or mailing list you want to post to. If your question has come up before, there is a good chance it has been answered before - the newsgroup or mailing list archives will turn up these answers if you search them carefully.

  • Ask your question directly. Plan your question beforehand, then just come right out and ask it. It might seem rude just to blurt out a question like that, but it's the way it's done.

Are there any live chats where I can talk about Perl stuff?

For UNIX or more general perl programming discussion, you can try out #perl on EFNet (the big one) and UnderNet. Be careful of EFNet #perl though. There are a number of discussion topics that are not tolerated there: Win32-specific Perl issues, non-programmer questions (e.g., I just downloaded this neat script - how do I make it work?), and CGI/WWW programming. EFNet #perl is a good place to meet some Perl masters, however, like Tom Christiansen (tchrist) and Randall Schwartz (q[merlyn]). I've never seen Larry on there but I'm told he does come on from time to time.

In any of these IRC channels, you need to do your own work, and try to solve your own problems. Don't go in expecting someone to look over some neat script you downloaded and want to get working if you "just want it to work and don't have time to learn perl". That kind of attitude is an easy way to get banned from the channel. The members of these channels are overworked Perl programmers with little tolerance for people who want others to do their work for them.

After you ask a question, you should stick around and chat for a while. It's polite, and a very good way to learn "perl style", or how perl programmers think about everyday things.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Documentation and Support


PerlIS - Perl for ISAPI

    • Sources of other information
    • What is ISAPI?
    • What is Perl for ISAPI?
    • Where can I get Perl for ISAPI?
    • Why should I use Perl for ISAPI rather than ActivePerl (perl.exe)?
    • Where's the source code for Perl for ISAPI?
  • AUTHOR AND COPYRIGHT

NAME

PerlIS - Perl for ISAPI

DESCRIPTION

About Perl for ISAPI.

Sources of other information

Information on Perl for ISAPI can also be found in the ActivePerl-Winfaq6 manpage and the ActivePerl-Winfaq7 manpage.

What is ISAPI?

ISAPI (Internet Server Application Programming Interface) is an API for writing extensions to web servers. It was originally developed by Process Software, and adopted by Microsoft as its standard server API. It complements or replaces the Common Gateway Interface (CGI), the standard interprocess protocol for writing extensions to web servers.

ISAPI's main advantage over CGI is that it uses dynamic-link library (DLL) function calls to communicate with extension components, rather than environment variables and standard I/O, as CGI does. There's a lot of overhead when starting new processes on Win32 platforms, and DLL calls eliminate the need for new processes, thus reducing the running time.

Although it was originally developed for Microsoft Internet Information Server, many Windows NT-hosted web servers now support ISAPI. See What web servers support ActivePerl? for the names of a few. If your server isn't there, check its documentation.

What is Perl for ISAPI?

Perl for ISAPI, is an ISAPI extension that runs Perl scripts on Win32 platforms.

Perl for ISAPI is mainly used for creating dynamic content on World Wide Web sites. Writing Perl scripts that run under PerlIS is not much different than writing scripts for the Common Gateway Interface (CGI).

Perl for ISAPI doesn't have much general purpose use. For general purpose programming, stick with the perl interpreter (perl.exe).

You may also see Perl for ISAPI referred to as PerlIS. PerlIS is the name of the Perl for ISAPI DLL.

Where can I get Perl for ISAPI?

Perl for ISAPI is distributed as a part of the ActivePerl distribution. You can optionally install it when installing ActivePerl.

Why should I use Perl for ISAPI rather than Perl for Win32 (perl.exe)?

The short answer is: it's faster. The long answer gets kind of technical, but it goes like this:

The main advantage of PerlIS over perl.exe is that PerlIS runs as a DLL in the web server's process space. Because Win32 platforms set up a protected memory space for each process that is started, there's a lot of overhead in starting a new process or program. Passing scripts to an interpreter, such as perl.exe, requires starting a new process for every script, which gets expensive in terms of system resources.

DLLs, on the other hand, don't need their own process space; they use the space of the process that calls them. They don't require nearly as much overhead to start, and once loaded they stay loaded until the calling process ends. PerlIS therefore runs Perl scripts with a quicker turn-around time than perl.exe.

Extra care should be taken when you write PerlIS applications. It is difficult to crash the web server using CGI, but because the PerlIS DLL runs in the process space of the server, your web server is more susceptible to crashes and hangs caused by programming errors.

Where's the source code for Perl for ISAPI?

The source for Perl for ISAPI is not distributed to the public.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - PerlIS - Perl for ISAPI


Windows NT/200x/XP and Windows 9x/Me

    • Where can I get Windows 200x/XP information?
    • Where can I get Windows NT information?
    • Where can I get Windows 9x/Me information?
    • What's the equivalent of the shebang ("#!") syntax for Win32?
    • What's the equivalent of chmod for Win32?
    • How do I send email from ActivePerl?
    • How do I schedule jobs on Win32 platforms?
    • Where can I find Win32 ports of UNIX tools?
    • What is a Windows NT/200x/XP service?
    • How do I run a Perl script as a Windows NT service?
    • How do I set permissions on a file?
    • How do I associate Perl scripts with perl?
    • Why doesn't "perl -e" work?
    • What editors are available for Windows?
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq4 - Windows NT/200x/XP and Windows 9x/Me

DESCRIPTION

Useful information about Windows NT/200x/XP and Windows 9x/Me for Perl developers

Where can I get Windows 200x/XP information?

The help files enclosed with Windows 200x/XP are an excellent source of information and can answer most of your questions about Windows 200x/XP.

World Wide Web support for Windows 200x/XP can be found at:

http://support.microsoft.com/

Where can I get Windows NT information?

A good starting place is the printed documentation that came with Windows NT and on the Windows NT CD in the support\books directory. Windows Help files are also available.

You can get some in-depth information on Windows NT from the Windows NT Resource Kit, available at bookstores and from Microsoft. Microsoft TechNet is also a valuable resource.

World Wide Web support for Windows NT Server is at:

http://www.microsoft.com/ntserver/

Support for Windows NT Workstation is at:

http://www.microsoft.com/ntworkstation/

Where can I get Windows 9x/Me information?

Printed documentation comes with Windows 9x, as well as some documentation on the CD-ROM. Help files are available from the Start menu.

World Wide Web support for Windows 9x/Me is at:

http://www.microsoft.com/windows95/
http://www.microsoft.com/windows98/
http://www.microsoft.com/windowsMe/

What's the equivalent of the shebang ("#!") syntax for Win32?

Unfortunately, Win32 platforms don't provide the shebang syntax, or anything like it. You can try one of the two following methods to run a script from the command line. If all else fails, you can always just call the perl interpreter directly, as in perl myscript.pl.

Although Win32 systems themselves don't use the shebang, the Apache webserver does. If you are using the Apache webserver on your Win32 system you should put the shebang line at the top of your CGI scripts.

Your shebang line should look something like:

 #!perl

For Windows NT 4.0/200x/XP, the coolest method is to use associated file types (see How do I associate Perl scripts with perl?). If you've associated Perl scripts with the .pl extension, you can just type the name of your file at the command line and Windows NT/200x/XP will launch perl.exe for you. If you change the PATHEXT environment variable to include .pl files, like this:

    SET PATHEXT=.pl;%PATHEXT%

you can just type the file name without an extension, and Windows NT/200x/XP will find the first .pl file in your path with that name. You may want to set PATHEXT in the System control panel rather than on the command line. Otherwise, you'll have to re-enter it each time the command prompt window closes.

Given this setup, you can have a Perl script called cat.pl that looks like this:

    while ( <> ) {
        print;
    }

and you can invoke it on the command line like this:

    cat myfile.txt

However, you can't invoke it with I/O redirection, like this:

    cat < myfile.txt
    cat myfile.txt | more

although it looks like you should be able to (this is a limitation of Windows NT/200x/XP). Your script can be in your path or you can provide a path to the file.

Note that the file association method does not work for Windows 9x/Me, nor does it work with Windows NT/200x/XP if you have command extensions disabled. You can, however, still start the Perl script from an Explorer window if the extension is associated with perl.

Another option is to use the pl2bat utility distributed with ActivePerl to convert your Perl script into a batch file. What this does is tag some Win32 batch language to the front of your script so that the system calls the perl interpreter on the file. It's quite a clever piece of batch coding, actually.

If you call the pl2bat utility on your Perl script helloworld.pl, like this:

    C:\> pl2bat helloworld.pl

it will produce a batch file, helloworld.bat. You can then invoke the script just like this:

    C:\> helloworld
    Hello, World!

You can pass command line parameters, as well. Your script can be in your PATH, or in another directory, and the pl2bat code will usually find it and execute it correctly. The big advantage of this over file associations is that I/O redirection will work correctly.

pl2bat has a number of useful command line options to affect how the wrapping is done, what command line switches to pass to perl, etc. Running perldoc pl2bat at the command line will show a full description of these options.

PerlApp, available in the Perl Dev Kit creates standalone .exe files from Perl Scripts. Redirection works correctly on PerlApp .exe files.

What's the equivalent of chmod for Win32?

There is no direct equivalent of the chmod tool on Win32 systems. For file attributes, you can use the ATTRIB command line tool (type HELP ATTRIB at the command line for details). For more complex permissions, see How do I set permissions on a file?.

For information on the chmod() function, see How does the chmod function work on Win32 platforms?.

How do I send email from ActivePerl?

You may come across scripts that send email with an external mail program, as in:

        open(MAIL, '| /usr/lib/sendmail user@there.com') or "die";
        print MAIL <<EOF;
        To: user@there.com
        From: user@here.com
        Hello, World!
        EOF

These sort of scripts generally cause people to ask, "is there a sendmail equivalent on Windows?'' If you need to send email from a Perl script, there is no need to use an external program like sendmail. The libnet bundle includes Net::SMTP, a module that can be used to send mail. Here is an example:

        use Net::SMTP;

        $smtp = Net::SMTP->new('here.com'); # connect to an SMTP server
        $smtp->mail( 'user@here.com' );     # use the sender's address here
        $smtp->to('user@there.com');        # recipient's address
        $smtp->data();                      # Start the mail

        # Send the header.
        $smtp->datasend("To: user@there.com\n");
        $smtp->datasend("From: user@here.com\n");
        $smtp->datasend("\n");

        # Send the body.
        $smtp->datasend("Hello, World!\n");
        $smtp->dataend();                   # Finish sending the mail
        $smtp->quit;                        # Close the SMTP connection

Another alternative is Mail::Sender, which can be used like so:

        use Mail::Sender;

        $sender = new Mail::Sender {smtp => 'mail.yourdomain.com', from => 'your@address.com'};
        $sender->MailFile({to => 'some@address.com', subject => 'Here is the file',
                       msg => "I'm sending you the list you wanted.",
                           file => 'filename.txt'});

Or Mail::Sendmail, which can be used like this:

        use Mail::Sendmail;

        %mail = ( To      => 'you@there.com',
                  From    => 'me@here.com',
                  Message => "This is a minimalistic message"
                 );

        if (sendmail %mail) { print "Mail sent OK.\n" }
        else { print "Error sending mail: $Mail::Sendmail::error \n" }

A Perl script for sending mail without using an external program is also available on Robin Chatterjee's Perl for Win32 page (see Are there information sources available on ActivePerl on the World Wide Web?).

If you really need a sendmail equivalent for Windows, several such equivalents exist:

Blat

Blat is a public domain program for sending email from the Windows NT command-line. Although it is reputed to work under Windows 95, the Blat authors have not tested it under Windows 98. The Blat home page is located at http://www.blat.net/

sendmail

A commercial sendmail product is available from MetaInfo, Inc. An evaluation version is available at http://www.metainfo.com/index.cfm

wrmail

Another commercial mail product is wrmail, part of the slmail product from Seattle Labs. A free version is available at http://www.seattlelab.com/

How do I schedule jobs on Win32 platforms?

The UNIX cron utility doesn't exist on Win32 platforms.

For Windows 200x/XP, there is a scheduling application available. It can be accessed through the Start menu: Start | Settings | Control Panel | Scheduled Tasks. By clicking "Add Scheduled Task", you start the Scheduled Task Wizard which walks you through the process.

For Windows NT, a scheduling tool called AT is available. Unlike the UNIX cron utility, AT doesn't store its schedule in a flat file, but is configured using command-line arguments. Note the AT command seems to be very picky about syntax. Here is one example:

        at 23:37 /interactive /every:M,T,W,Th,F,S,Su cmd /c "c:\perl\bin\perl.exe c:\test.pl"

If you don't like the command-line version of AT, there's a GUI version, WinAT, which is available with the Windows NT Resource Kit. The "Schedule" service must be running when your job is supposed to happen.

Note that you may have problems when running AT or WinAT if the scheduled program or script requires any special rights or permissions other than those held by "System" (ie, if it is working across computers or NT domains). This is because NT does not properly allow you to run preinstalled NT services, such as the "Schedule" service as a user with network priveleges. It may look like you can set the scheduler to login as a user with network priveledges, but the service just does not recognize that user's right's and permissions and the System userid has only local permissions.

An all-Perl cron-like solution exists at http://www.megadodo.demon.co.uk/perl/ which uses a familiar Unix-like crontab file. This script can be ran as an NT Service (see How do I set up a Perl script as an NT Service?). When you create your own NT service, NT lets you set the useid/password pair, and these services do recognize that userid's rights and permissions. Hence, the scheduled program or script will have the necessary rights.

There are a few commercial cron-like schedulers. NTcrond, is available from ifdef software: http://www.ifdef.com/ and AutoTask2000 is available from http://www.cypressnet.com/. These programs should recognize the rights and priveleges of the userid you set their service to run under to enable the scheduled program or script to have the necessary rights.

For Windows 9x/Me, there's a System Agent available with the Microsoft Plus! Pack. Also, there are several shareware scheduling utilities, notably LaunchPad and Metz Scheduler. These can be found on a good shareware search engine, such as http://www.shareware.com/. There is also an optional "Task Scheduler" component with IE4.01 and Windows 98.

Because scheduled jobs on Windows NT run as a service (see What is a Windows NT service?), you need to take special steps to make sure that files and environment variables are available to your script.

In some instances, Perl's internal sleep function might be an appropriate means of scheduling. For example:

        $seconds = 180;
        sub action;
        while(1) {
                &action;
                sleep($seconds);
        }

Where can I find Win32 ports of UNIX tools?

You might want to take a look at the help file for Windows NT and Windows 9x/Me commands to see if there's a rough equivalent distributed with your Win32 platform. If not, try one of these URLs:

  • Cygwin - Linux-like environment for Windows, contains many GNU tools, as well as a complete development environment. http://www.cygwin.com/

  • GnuWin32 http://gnuwin32.sourceforge.net/

There are also several UNIX-like tools available in the Windows NT Resource Kit. Also, there are several UNIX-to-Win32 commercial packages available, including the MKS Toolkit from Mortice Kerns Systems, Inc.: http://www.mks.com/.

You can also check into the Perl Power Tools, being developed under the UNIX Reconstruction Project. Here you can find UNIX tools that are being reimplemented into all Perl. You can see the latest at http://ppt.perl.org/

What is a Windows NT/200x/XP service?

On Windows NT/200x/XP, a service is a special kind of executable program that runs in the background. Services are used for programs that are constantly working, such as network protocols or database servers. Most WWW servers on Windows NT/200x/XP are implemented as services.

A service is different from other programs in several ways:

  • Services aren't run interactively, although the NET START and NET STOP commands can be used to start or stop a server. The Services control panel is used to start, stop, or pause a service.

  • Services don't act with the authority of the logged-in user. That means that services can't see user environment variables or read files that are readable only by the logged-in user. You can set the account that a service uses in the Services control panel.

  • Services run even when no one is logged in to the machine.

The most important thing to remember is that you have to take special steps to make resources available to services. In general, you need to make files available to the Everyone group, and you have to have environment variables (like PATH) be system environment variables.

How do I run a Perl script as a Windows NT Service?

You can run your Perl scripts as Windows NT Services via a program called srvany.exe, which comes with the Windows NT Resource Kit. Once srvany.exe is installed, read the srvany.wri file which should be with it. This document will explain how to set up registry entries for your new service.

After you are set up, to run your script as a service do:

  x:>srvany perl script.pl

How do I run a Perl script as a Windows 200x/XP Service?

You can run your Perl scripts as Windows 200x/XP Services by accessing the Microsoft Management Console. The Windows 200x/XP help files contain plenty of information on how to start the MMC and how you can use it for Perl scripts.

How do I set permissions on a file?

Win32 platforms don't have the same mechanisms for setting permissions on files as UNIX does. For files on FAT partitions (which means all files in Windows 9x/Me), you don't have to set permissions explicitly on a file. All files are available to all users.

For files on an NTFS partition on Windows NT, you can set the security permissions on a file using the Explorer and the properties sheet of the file. Right-click the file in Explorer, and choose Properties from the drop-down menu. Select the Security tab, and click Permissions to set the Permissions on the file. Click Help for more information.

A command-line program, CACLS, will also change the permissions on a file. For more details, type HELP CACLS on the command line.

Windows 9x/Me machines that are administered using Novell can have accounts and permissions similiar to NT. However, these permissions must be set up by the Novell administrator.

How do I associate Perl scripts with perl?

On Windows systems, association is the process of specifying which programs should be used for which kind of files. Files are grouped into file types, such as JPEG files or Perl scripts. The file type of a file is identified by its file name extension (all the letters after the last ".'' in the file name).

So, for example, we can say that there's a type of file called a text file, which has the file extension .txt, and which is handled by the Notepad program.

Usually, ActivePerl programmers create a file type like Perl Script and associate the extension .pl with that type. We specify that the perl interpreter binary, perl.exe, is responsible for that file type. Several Web servers require that you associate your scripts with perl.exe before the script can be run.

On Windows 200x/XP, you can create a new file type and associate it with the perl intepreter with it as follows:

  1. Double-click on the My Computer icon.

  2. From the Tools menu, choose Folder Options. This opens the Folder Options dialog box.

  3. Choose the File Types tab. This gives you a list of file types currently registered (or already associated in Windows 200x/XP).

  4. Click the New button.

  5. In the File Extension box, type "pl" and click OK.

  6. Click the Advanced button. This opens the Edit File Type window.

  7. Click the New button. This opens the New Action dialog box. Type "Open" in the Action window (as you would want the Perl files to be "opened" by the Perl interpreter). Then, either type the full path of the location of the Path interpreter in the Application window, or click the Browse button to select the executable file of the Perl interpreter.

  8. Click OK to close the New Action window. You can click the Change Icon button, if you want to find an icon to match the file type. When you click the Change Icon button, you are given a selection of pre-set icons or you can browse to a different location. If you want to use a Perl icon for the .pl files, browse to the folder where the Perl interpreter is located, choose the Perl interpreter and click Open. Then click OK to close the Change Icon Window.

  9. Click OK to close the Edit File Type window.

  10. Click Close to close the Folder Options window.

On Windows 9x/Me and Windows NT 4.0, you can create a new file type and associate the perl interpreter with it as follows:

  1. Open the My Computer icon on the Desktop. The My Computer window should appear.

  2. From the View menu in the My Computer window, choose Options. The Options dialog box appears.

  3. In the Options dialog box, select the File Types tab.

  4. Click the New Type button. The Add New File Type dialog box appears.

  5. In the "Description of type'' box, type "Perl Script''.

  6. In the "Associated extension'' box, type ".pl''.

  7. Leave the Content Type (MIME) box blank.

  8. Click the New button beneath the Actions list. The New Action dialog box will appear.

  9. In the Action box, type "Open'' (it's important to use this name for the action!).

  10. In the "Application used to perform action'' box, type [full path to perl]\perl.exe %1 %*, where [full path to perl] is the full path to perl.exe on your machine. If perl is in your path, you can put just perl.exe, but for esoteric reasons it's better to put the full path. Also, if the path to your interpreter includes spaces (like C:\Program Files\perl5) put in the DOS path instead (C:\progra~1\perl5).

  11. Click OK to close the New Action dialog box.

  12. Click OK to close the Add New File Type dialog box.

  13. Click OK to close the Options dialog box.

You can test your association by double-clicking on a perl script in the Explorer window. If perl.exe starts and executes the script, things are OK.

On Windows NT 4.0, you can avoid all the hassle of the above and just type the following from the command line:

    ASSOC .pl=PerlScript
    FTYPE PerlScript=[full path to perl]\perl.exe %1 %*

For more information on these commands, type HELP FTYPE at the command prompt.

Note that for this to work you have to have command extensions enabled. (These are enabled by default; you'd know if you'd turned them off.)

Why doesn't 'perl -e' work?

It does - it's just that some command shells (for example COMMAND.COM, CMD.EXE and 4DOS) don't accept single quotes wrapped around command arguments.

The safest way to do perl one-liners is to wrap the parameters within "" (double-quotes) the use q() and qq() inside the parameters. q() and qq() with put whatever is inside them between single-quotes or double-quotes, respectively.
For example:

perl -e "use LWP::Simple; while(@c = head <>) { $c = join qq(\n\t), @c; print qq(Header info:\n\t$c\n); }"

(this was all one line)

Run this from the command line and type in the URL to your favorite website, like http://www.perl.com/.

The perlwin32 and perlrun POD pages have more information on using the command line.

What editors are available for Windows?

Windows comes with two editors that are great for editing Perl, NotePad and WordPad. But, if you need more features for ease of editing, here is a list of free and commercial editors:

  • Komodo - http://www.ActiveState.com/Products/Komodo/
    • Komodo is a complete, powerful development environment for Perl and other languages. Komodo also includes the Rx Toolkit, which provides the unique ability to interactively step through a regular expression as it is being matched, providing support for one of the most difficult technologies used in scripting languages.
  • MED - http://www.utopia-planitia.de/indexus.html
    • MED is a powerful shareware text editor for programmers, currently available for the platforms Windows 9x/Me/NT4.0/200x/XP.
  • GNU Emacs for Windows - http://www.gnu.org/software/emacs/windows/ntemacs.html
    • "Emacs is the extensible, customizable, self-documenting real-time display editor."
  • VIM - http://www.vim.org
    • The "Vi IMproved" editor -- Now with Perl support. VIM provides Perl syntax highlighting, and a Perl interface. The Perl interface provides the ability to run a Perl command or run a Perl command for each line in a range. For more information on Perl support, see the Perl and VIM help page.
  • Open Perl IDE - http://open-perl-ide.sourceforge.net
    • Open Perl IDE is an integrated development environment for writing and debugging Perl scripts with any standard perl distribution under Windows 95/98/NT/2000.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly and Associates, and David Grove, David Dmytryshyn of ActiveState, Kevin Meltzer, Eric Smith and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Windows NT/200x/XP and Windows 9x/Me


Implementation Quirks

    • Certain functions don't seem to work on ActivePerl.
    • The exec function doesn't seem to work under Perl for ISAPI, Perl for WebSite, or PerlScript. Why not?
    • What's the history of ActivePerl?
    • What's the difference between running ActivePerl on Windows NT/2000
    • Why don't the examples from the Camel book work?
    • Why don't certain standard library modules work?
    • How do I make a UNIX-based script work?
    • How does the chmod function work on Win32 platforms?
    • 4DOS doesn't recognize \" on the command line.
    • STDIN and STDOUT, and Piping don't always work on NT.
    • Why doesn't signal handling work on Windows.
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq5 - Implementation Quirks

DESCRIPTION

Issues specific to ActivePerl.

Certain functions don't seem to work on ActivePerl.

There are several functions that are unimplemented in the ActivePerl system. Here is a complete list of unimplemented functions:

Functions for processes and process groups

alarm(), getpgrp(), getppid(), getpriority(), setpgrp(), setpriority()

Fetching user and group info

endgrent(), endpwent(), getgrent(), getgrgid(), getgrnam(), getpwent(), getpwnam(), getpwuid(), setgrent(), setpwent()

System V interprocess communication functions

msgctl(), msgget(), msgrcv(), msgsnd(), semctl(), semget(), semop(), shmctl(), shmget(), shmread(), shmwrite()

Functions for filehandles, files, or directories

link(), symlink(), chroot()

Input and output functions

syscall()

Fetching network info

getnetbyname(), getnetbyaddr(), getnetent(), getprotoent(), getservent(), sethostent(), setnetent(), setprotoent(), setservent(), endhostent(), endnetent(), endprotoent(), endservent(), socketpair()

See the perlport and Win32 documentation pages for more information on the portability of builtin functions in ActivePerl.

The exec function doesn't seem to work under Perl for ISAPI or PerlScript. Why not?

Perl for ISAPI and PerlScript share a process space with the web server and any number of other extensions. As a result, the exec() function is unimplemented, because it would cause the web server to terminate (the exec() function executes a system command and never returns).

What's the history of ActivePerl on Windows?

At one time, Perl on the Win32 platform was found in two versions, Gurusamy Sarathy's port, and the ActiveState port. The ActiveState port of Perl included such tools as Perl for ISAPI and PerlScript, at the expense of exposing Perl's internals in a slightly different fashion than standard Perl. Sarathy's port featured a high degree of compatibility with standard Perl, which enabled users of Sarathy's port to use many modules that were not compatible with ActiveState Perl.

The oneperl effort brought both ports of Perl together, and ActivePerl is the standard perl distribution for the Win32 system. All modules that can be used on Win32 can be used with this port. You no longer have to worry about whose perl the module is for. Just grab it, compile it (if needed), and use it.

What's the difference between running ActivePerl on Windows NT versus running it on Windows 95?

There should be little difference between running Perl on the two operating systems. You should watch for the following, though:

  • The Win32::NetAdmin, Win32::NetResource, and Win32::EventLog modules will not run on Windows 95.

  • Some functions that work on Windows NT/2000 reportedly do not work or are buggy on Windows 95. An example is flock().

  • Finally, many helpful programs that are available on Windows NT/2000 are not there on Windows 95. hostname, for example, is not available on Windows 95.

If you're worried about using a feature from one or the other, check the result of the function Win32::IsWinNT() to see what OS you're running on. See What modules come with the ActivePerl distribution?.

Why don't the examples from the Camel book work?

The Camel book (aka Programming Perl (3rd edition), Wall et.al., O'Reilly & Associates 2000) was written by UNIX people for, in general, UNIX people.

Some of the examples in the Camel book will work. Some will not. If they fail, it's because either the functions used are not available, the external tools used are not available, or the modules used are not available. Usually, for small scripts, it's not too hard to fiddle with them until they come out correct (see How do I make a UNIX-based script work?).

The Camel and Llama books are good learning tools. However, one of the things you learn as a ActivePerl programmer is how to port UNIX-targeted scripts and modules to ActivePerl.

For better examples of using ActivePerl, you may want to look at the Gecko book, ``Learning Perl on Win32 Systems,'' published by O'Reilly.

Why don't certain standard library modules work?

With ActivePerl, almost all modules will work with ActivePerl as long as they can be built to run on Win32. The problems that existed with the 3xx versions of Perl for Win32 no longer exist: modules work on Win32, not just this port or that port of Perl for the Win32 platform!

If a module doesn't work, it may be because the functions it uses are specific to UNIX and won't work on Win32, or specific to NT/2000 and won't work on Windows 95 or Windows 98.

How do I make a UNIX-based script work?

First, make extra-super sure that you are using the script or module in the way it was intended. Many of us are quick to blame the module, the operating system, or the interpreter when, in reality, it is our own code that isn't working right.

If you're sure that it's not a problem in your code, the best way to make a UNIX-based script work is to desk-check it before running it. Look for some of the following things:

  • Calls to functions unimplemented in ActivePerl. For a list, see Certain functions don't seem to work on ActivePerl..

  • Calls to standard library modules or CPAN modules that aren't available on ActivePerl, or that don't work.

  • system() or backtick (``) calls to system tools that aren't available on ActivePerl.

  • Reading and writing files that may be binary. See Reading from and writing to files mysteriously fails. What's wrong?.

  • File-system dependent path names and path name parsing. Watch for hard-coded UNIX paths like /usr/lib.

  • The module or script may require a specific version of Perl or another module. Watch out for things like require 5.003; or require Sockets 1.03; Check to see if the script or module really requires the new version.

Of course, it should go without saying that for everything you take out you'll have to put in a work-around.

Once you've worked around UNIX dependencies in the script or module, try running it through the debugger to see if what you did helps. If the script or module comes with a .t test file, try using that to test your changed version.

If you do make a change to a UNIX-based script or module, please let the author know. Sometimes the author will be gracious enough to make changes that will let the program run on ActivePerl. If the author won't change the program, ask if you can make the altered version available to other users.

How does the chmod function work on Win32 platforms?

chmod() is supported in ActivePerl. However, it can only be used for setting "owner" read/write access. (The "group" and "other" bits are ignored.)

UNIX-style security for files is not applicable to files on Win32 systems. Win32 systems inherit from DOS four possible file attributes: archived (A), read-only (R), hidden (H), and system (S). These can be checked and set with the Win32::File::Get/SetAttributes().

Windows NT/2000 systems using NTFS can also have more specific permissions granted on individual files to users and groups. For builds 300 and above, and the Perl Resource Kit for Win32, you can use the Win32::FileSecurity module to maintain file permissions.

4DOS doesn't recognize \" on the command line.

4DOS doesn't recognize the escaped quote on the command line, because all double-quote characters are seen as delimiters for command line parameters. This is one of the few points (if not the only one) where 4DOS doesn't quite match up to COMMAND.COM.

To get around this, you can enter

    perl -e "print \"Hello, World\n\""

as

    perl -e "print qq(Hello, World\n)"

using Perl's alternative quoting mechanism. The alternative quotes are qq() for double quotes, q() for single quotes, qx() for backquotes, and qw() for list quotes. The parentheses can be substituted for just about anything (like + or | or {} or <> or #), but that looks weird.

STDIN and STDOUT, and Piping don't always work on NT/2000.

You may get unexpected results when you try to redirect the output of files that use Windows NT/2000's file association feature. You can use PerlApp or pl2bat to convert a Perl script to an executable or a batch file. This should solve any problems you may have with redirection.

Why doesn't signal handling work on Windows?

Signals are unsupported by the Win32 API. The C Runtime provides crude support for signals, but there are serious caveats, such as inability to die() or exit() from a signal handler. Perl itself does not guarantee that signal handlers will not interrupt critical operations such as memory allocation, which means signal invocation may throw perl internals into disarray. For these reasons, signals are unsupported at this time.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly and Associates, and David Grove, David Dmytryshyn, and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Implementation Quirks


ActivePerl FAQ - Web Programming

Web Programming (CGI and PerlIS)

  • NAME
  • DESCRIPTION
    • What is HTTP, and how do I get more information on it?
    • What is CGI, and how do I get more information on it?
    • How do I return a graphics file from a CGI script?
    • My CGI scripts don't seem to run right under PerlIS.
    • How does my script know if it's running under ActivePerl or Perl for ISAPI?
    • How does my script know if it's running under ActivePerl or Perl for WebSite?
    • What CGI modules run with ActivePerl?
    • How do I use redirection in my script?
    • What are cookies and how do I use them?
    • How do I get the e-mail address of the user?
    • I need a CGI script to do a certain task. Has anyone done it before?
    • How do I test my CGI programs that take arguments without running
    • The Content-Type: header field I output from my CGI script shows up
    • When I try to run a CGI script from my browser, it tries to
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq7 - Web Programming (CGI and PerlIS)

DESCRIPTION

Web development with ActivePerl

What is HTTP, and how do I get more information on it?

HTTP (HyperText Transfer Protocol) is the protocol that web browsers use to talk to web servers. The official specification for the HTTP standard is available on the W3 Consortium web server at:

    http://www.w3.org/Protocols/

Some more readable introductions can be found on the Yahoo HTTP page at:

    http://www.yahoo.com/Computers_and_Internet/Internet/World_Wide_Web/HTTP/

What is CGI, and how do I get more information on it?

CGI (Common Gateway Interface) is a protocol used by web servers to run server programs. Scripts that support the CGI protocol are sometimes called ``CGI scripts''; this leads to the unfortunate misperception that CGI is a language of its own.

The classic information on CGI is available on the NCSA server at:

    http://hoohoo.ncsa.uiuc.edu/cgi/

If you haven't read this, read it now. If it doesn't click for you, you can check the Yahoo CGI page at:

    http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Server_Side_Scripting/Common_Gateway_Interface__CGI_/

(All one URL)

Try also the following URL for CGI programming in Perl:

    http://www.perl.com/doc/FAQs/cgi/perl-cgi-faq.html

If you still don't get it, try one of the ``get-rich-quick-by-writing-CGI-scripts'' books at your local bookstores.

How do I return a graphics file from a CGI script?

One of the big differences between UNIX and Win32 platforms is that on Win32 there's a difference between text or ASCII files and binary file. To return a graphics file, you need to specify that the file is a binary file, and that the standard output stream should accept binary data. Try something like this:

    $MY_FILE_NAME = 'Penelope.jpg';
    $CHUNK_SIZE = 4096;

    open( MY_FILE, "<$MY_FILE_NAME" )
        or die( "Can't open $MY_FILE_NAME: $!\n" );

    print "Content-type: image/jpeg\r\n";
    print "\r\n";

    binmode( MY_FILE ); # These are crucial!
    binmode( STDOUT );

    while ( $cb = read( MY_FILE, $data, $CHUNK_SIZE ) ) {
        print $data;
    }

    close( MY_FILE );

My CGI scripts don't seem to run right under PerlIS.

Earlier versions of Perl for ISAPI did not output headers correctly, and this caused Perl for ISAPI scripts to misbehave. You could work around this in earlier versions of PerlIS by sending the headers at the beginning of your script like this:

    print <<"END";
    HTTP/1.0 200 OK
    Content-Type: text/html

    END

This is no longer necessary with the current version of Perl for ISAPI, as Perl for ISAPI sends the correct headers. The Registry value that governs this is EnableCGIHeader, a REG_DWORD value that is set to 1 by default. This value is stored under the Registry key HKEY_LOCAL_MACHINE\SOFTWARE\ActiveState\PerlIS. If you need to turn off the automatic generation of the header, set this value to 0.

How does my script know if it's running under ActivePerl or Perl for ISAPI?

Perl for ISAPI sets an environment variable, PERLXS, for scripts that are executed under Perl for ISAPI.

    my $running_under_perlis = $ENV{PERLXS} eq 'PerlIS';

How does my script know if it's running under ActivePerl or Perl for WebSite?

Perl for WebSite sets an environment variable, PERLXS, for scripts that are executed under Perl for WebSite.

    my $running_under_perlws = $ENV{PERLXS} eq 'PerlWS';

What CGI modules run with ActivePerl?

The CGI.pm module works with ActivePerl. It's included with ActivePerl, and you can use it in your program with the statement use CGI. Complete documentation for the CGI module is embedded in the module, and can be read with perldoc CGI.

How do I use redirection in my script?

You can use redirection to point the client browser to another file or script, usually in a way that's invisible to the user. The CGI module provides the redirect() function for this purpose. The following code redirects the client browser to http://www.perl.com and works with both CGI or PerlIS:

    use CGI qw(:standard);
    print redirect('http://www.perl.com');

What are cookies and how do I use them?

Cookies are packets of data that a server can give to a client, such as a browser, to maintain information even after the browser has left this site. This can be used to to identify the client in future interactions or to store user preferences. Cookies were first defined by Netscape, and the definition of cookies can be found at:

    http://home.netscape.com/newsref/std/cookie_spec.html

The CGI module provides support for managing cookies. See What CGI modules run with ActivePerl? for information about the CGI module, including the location of online documentation.

How do I get the e-mail address of the user?

It's not, in general, possible to get the e-mail address of a user without asking them for it. If you need an e-mail address, provide the user with a form to fill in an address.

The HTTP specification (see What is HTTP, and how do I get more information on it?) defines an HTTP request header field, From:, that can contain the e-mail address of the user making the connection. Your script can retrieve it using the environment variable HTTP_FROM. However, it's rarely provided and can't really be counted on.

There are all kinds of sneaky ways to determine where requests come from -- like checking the IP address that was used to connect -- but you can't figure out the e-mail address of the user this way.

Generally, it's considered a violation of the user's privacy to get their e-mail address without their knowledge. Perhaps that's why it's so difficult.

I need a CGI script to do a certain task. Has anyone done it before?

There are several CGI script archives on the web. You may not be able to find exactly the script you want, but you will probably find something that can be adapted to your needs.

Two of the most famous script pages are:

  • Jenda's pages: www24.brinkster.com/jenda/

  • The Perl Monks: www.perlmonks.org

  • Matt's script replacements: nms-cgi.sourceforge.net

  • Dave Doyle's Script Archive: www.davedoyle.com/help/scripts.html

Note that most script archives have UNIX-targeted scripts, and you may have to make some adaptations to them to make them run (see How do I make a UNIX-based script work?).

This is one of the most common questions on the Perl-Win32-Users list. Occasionally it's phrased more like "I have a program to write. Here are the specs. Please e-mail it to me by Friday." Hopefully the reader can understand why these messages are usually answered rudely, if they are answered at all.

How do I test my CGI programs that take arguments without running them through the web server?

The hard way to test your CGI programs from the command line is to set up environment variables and a standard input stream just like a web server would (see the CGI 1.1 specification for more details on this -- see What is CGI, and how do I get more information on it?).

The easy way is to use CGI.pm, the Perl module for CGI programming. It provides an easy mechanism to run CGI programs, with arguments, from the command line. See What CGI modules run with ActivePerl?.

The Content-Type: header field I output from my CGI script shows up in the web browser.

You are using an older version of Perl for ISAPI as your Perl interpreter on an IIS web server, but it's not outputting an HTTP status line. You should be able to fix this by installing the most recent version of Perl and PerlIS. See My CGI scripts don't seem to run right under Perl for ISAPI. for more details.

When I try to run a CGI script from my browser, it tries to download a file of type "application/x-perl" instead.

Your web server has been misconfigured. It doesn't know that it should execute your Perl program, so it's just returning it to the browser. See the perlwin32faq6 manpage for details on how to configure your particular web server to know that Perl scripts should be executed.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Web Programming (CGI and PerlIS)


ActivePerl FAQ - General programming

General programming

  • NAME
  • DESCRIPTION
    • How do I change the Win32 Registry?
    • How do I read from/write to a named pipe?
    • How do I write socket scripts?
    • What's all this I hear about not being able to use a socket as a
    • How do I write a sockets server in ActivePerl?
    • How do I send or receive files by FTP?
    • How do I send or receive files by HTTP?
    • How do I manage user accounts with ActivePerl?
    • How do I read from and write to serial ports?
    • Why doesn't the -d operator work?
    • Reading from and writing to files mysteriously fails. What's wrong?
    • When I try to open a file, I get a "bad argument" error.
    • Why do I get an error using Perl's here-doc syntax (<<), that
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq8 - General programming

DESCRIPTION

General programming questions about ActivePerl

How do I change the Win32 Registry?

There are several Win32 Registry functions provided with ActivePerl. Check the win32mod document provided with ActivePerl.

If you don't understand how the Registry works, remember that a Registry key is like a directory, and a Registry value is like a file. There are several top level keys, and these are kind of like drives.

If you really don't fully understand the Registry, it's probably in your best interest not to mess around with it.

How do I read from/write to a named pipe?

Named pipes are a interprocess communcations mechanism, mainly used with Microsoft operating systems (like Win32 platforms). A named pipe can be addressed just like a file.

The name of a named pipe is a UNC (Universal Naming Convention) name, and looks like \\servername\pipe\pipename. servername is the name of the server you're connecting to, or . for the current computer. pipe is a constant, and pipename is the name of the pipe, such as sql for Microsoft SQL Server.

You can use open(), close(), read(), and print() on a named pipe just like a file. However, you can't use sysread() or syswrite() on one, because they aren't really files.

There's a program called Win32Pipe on the CPAN archive that can be used to create a named pipe.

If you're starting from scratch, and you have a TCP/IP infrastructure, consider using sockets rather than named pipes for your IPC mechanism.

How do I write socket scripts?

There are several examples of socket scripts that are distributed with ActivePerl. They're in the eg subdirectory of your perl directory.

See How do I write a sockets server in Perl for Win32? for information about sockets servers.

What's all this I hear about not being able to use a socket as a filehandle?

Early versions of Perl for Win32 didn't allow you to read or write to a socket as if it were a filehandle. The current versions fully support this, and you shouldn't worry about it too much. If the version that you're using doesn't work well, get the latest build from ActiveState (see Where is the ActivePerl interpreter available?).

You don't have to specify USE_SOCKETS_AS_FILEHANDLES when building Perl for Win32 to get sockets to work like filehandles. It doesn't hurt, but it's not necessary.

How do I write a sockets server in Perl for Win32?

There's an example of a socket server, TCP-SERVER, in the eg directory of your perl directory. In general, information on socket programming for UNIX is applicable to ActivePerl. See especially the perlipc page of the documentation.

If you need to develop a server that can service multiple clients at once, take a look at the IO::Select module. This module allows you to write servers that can manage open connections from multiple clients. Individual requests on a connection are queued up, so if your server can provide quick responses, this approach may work well for you. Here's an example, adapted from Erik Olson's Programming with Perl Modules (one of the volumes in O'Reilly's Win32 Perl Resource Kit):

    use IO::Socket;
    use IO::Select;

    # Create a socket to listen on.
    #
    my $listener =
      IO::Socket::INET->new( LocalPort => 8008, Listen => 5, Reuse => 1 );

    die "Can't create socket for listening: $!" unless $listener;
    print "Listening for connections on port 8008\n";

    my $readable = IO::Select->new;     # Create a new IO::Select object
    $readable->add($listener);          # Add the listener to it

    while(1) {

        # Get a list of sockets that are ready to talk to us.
        #
        my ($ready) = IO::Select->select($readable, undef, undef, undef);
        foreach my $s (@$ready) {

            # Is it a new connection?
            #
            if($s == $listener) {

                # Accept the connection and add it to our readable list.
                #
                my $new_sock = $listener->accept;
                $readable->add($new_sock) if $new_sock;

                print $new_sock "Welcome!\r\n";

            } else {  # It's an established connection

                my $buf = <$s>;   # Try to read a line

                # Was there anyone on the other end?
                #
                if( defined $buf ) {

                    # If they said goodbye, close the socket. If not,
                    # echo what they said to us.
                    #
                    if ($buf =~ /goodbye/i) {
                        print $s "See you later!\n";
                        $readable->remove($s);
                        $s->close;
                    } else {
                        print $s "You said: $buf\n";
                    }

                } else { # The client disconnected.

                    $readable->remove($s);
                    $s->close;
                    print STDERR "Client Connection closed\n";

                }
            }
        }
    }

For more information, see the IO::Socket and IO::Select documentation. It is also possible to write a multithreaded server using ActivePerl, if threads are enabled in the version of Perl you are using. However, threading is still somewhat experimental in Perl 5.005, so use this feature with caution.

How do I send or receive files by FTP?

See the Net::FTP module. Net::FTP is part of the libnet bundle, which is available from CPAN, and can be installed using the Perl Package Manager (PPM).

Aldo Calpini has developed a ActivePerl extension to do FTP and HTTP using the WININET library. It's in alpha testing and is available on his web page at http:// dada.perl.it/

How do I send or receive files by HTTP?

The libwww-perl bundle (LWP) is a collection of modules for WWW access in Perl. LWP is available from CPAN in source form, or you can install it using the Perl Package Manager (PPM). LWP may also be included with future binary releases of Perl.

Aldo Calpini has developed a ActivePerl extension to do FTP and HTTP using the WININET library. It's in alpha testing and is available on his web page at http://dada.perl.it/

How do I manage user accounts with ActivePerl?

There's an extension called Win32::NetAdmin distributed with ActivePerl. It has a pretty low-level interface, but it is very possible to manage users and groups with this module.

How do I read from and write to serial ports?

Serial ports can be opened just like files in ActivePerl. To open COM1, just do this:

    open( PORT, "+>COM1" ) or die "Can't open COM1: $!";

You should be able to read from and write to the file handle using the standard I/O functions (read() and print()), but not the system functions (sysread() and syswrite()).

It has been noted (but not tested) that modems that use the Hayes command set require a carriage return (\r) rather than a line feed (\n) at the end of the command.

Why doesn't the -d operator work?

It does, in fact, work. However, people tend to use it incorrectly and get bad results. To check for all the subdirectories in a directory, try code like this:

    $path = shift;
    $path = "." unless $path;

    opendir( DIR, $path )
        or die "Can't open $path: $!";

    while ( $entry = readdir( DIR ) ) {
        $type = ( -d "$path\\$entry" ) ? "dir" : "file"; # $path is crucial!
        print "$type\t$entry\n";
    }

    closedir( DIR );

It's a common mistake to leave out the $path from the -d check. If you do this, perl thinks you're talking about files in the current directory. Since the dirs don't -e in your current directory, they definitely don't -d. Exceptions are . and .., which exist in every directory.

Reading from and writing to files mysteriously fails. What's wrong?

On Win32 platforms, there's a big difference between text files and binary files. For text files, the \r\n characters are translated into \n when read from disk, and the ^Z character is read as an end-of-file marker. For binary files, no such translation is used.

Although this works great for text files, it really messes things up when you're trying to read and write binary files. If the read or write does not abort prematurely because a ^Z was found in the file, you will almost definitely get incorrect bytes in the file due to \n -> \r\n translation.

The problem is that ActivePerl, and the C runtime library it uses, open file in text mode by default. For each file handle you use in Perl for binary data, you need to specify that the file handle is in binary mode. Fortunately, there's a function, binmode, that does just that. See the perlfunc documentation file for details.

This script copies one binary file to another. Note its use of binmode to set the mode of the file handle.

    open( INFILE, "<$infile" );
    open( OUTFILE, ">$outfile" );

    binmode( INFILE ); binmode( OUTFILE ); # crucial for binary files!

    while ( read( INFILE, $buffer, 1024 ) ) {
        print OUTFILE $buffer;
    }

    close( INFILE );
    close( OUTFILE );

When I try to open a file, I get a "bad argument" error.

Win32 platforms use the '\' character as a delimiter for paths in a file name (C:\like\this). However, Perl uses the '\' character as an escape code, to symbolize a special character like the line feed character (\n) or the tab character (\t).

So, if you try and open a file like this:

    open( MYFILE, "C:\temp\newfile.txt" );

you'll get an error. One solution is to replace each '\' with a double-'\', to show that you really mean to use that character, not an escape:

   open( MYFILE, "C:\\temp\\newfile.txt" );

Another solution is to use non-interpolating single quote strings, which lets Perl know not to use any special characters:

   open( MYFILE, 'C:\temp\newfile.txt' );

Finally, you can also use the / character to separate directory components in pathnames. You must avoid using this in calls to external programs, because some programs tend to treat / as the option-prefix instead of directory separator. However, ActivePerl (and in fact, all of the Win32 API) understands that / is a directory separator, so using / allows you to more easily port scripts between UNIX and Win32:

   open( MYFILE, '/temp/newfile.txt' );

See the perlop documentation page for more information on the differences between single quotes (') and double quotes (``).

Why do I get an error using Perl's here-doc syntax (<<), that says "Can't find string terminator anywhere before EOF"?

This is a weird error that occurs when your string terminator is on the last line of your script. With a script like:

    print <<"END";
    The snake is old, and his skin is cold.
    END

perl is looking for the word END on a line by itself, followed by a line-feed character (\n). If the END is the last line of your script, you have to remember to hit <Enter> after the word END, so that Perl can recognize it as the string terminator.

Most UNIX text editors will do this automatically. Most Windows text editors won't. Thus the problem.

Note that this can also cause a problem with Perl formats, since these are terminated with a single . on a line by itself. However, it's much more rare, since programmers often specify the format for output at the top rather than at the bottom of a file.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - General programming


ActivePerl FAQ - Modules and sample scripts

Modules and sample scripts

  • NAME
  • DESCRIPTION
    • How can I use modules from CPAN?
    • Where do I get make for Win32?
    • How do I access databases from my Perl script?
    • Is there a way to use OLE Automation servers from my Perl script?
    • Is there a way to access Data Access Objects (DAO) from my Perl
    • Can I send Internet mail from ActivePerl?
    • Is there a way to access MAPI from my Perl script?
    • Is there a DBM implementation available for ActivePerl?
    • Is there a way to do GUI programming with ActivePerl?
    • Is there a port of Oraperl for Win32?
    • What modules come with the ActivePerl distribution?
    • Where can I find other modules for ActivePerl?
    • What is CPAN and how do I use it?
    • Is there a library to read or write Microsoft Office or other application files?
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq9 - Modules and sample scripts

DESCRIPTION

General questions about using modules and scripts with ActivePerl

How can I use modules from CPAN?

As of version 5.005, ActivePerl supports the MakeMaker utility. This allows you to install modules from CPAN, but requires you to have a make utility, such as nmake or dmake. Modules are generally distributed in gzipped tar files, such as Data-Dumper-2.08.tar.gz.

However, ActivePerl includes the Perl Package Manager (PPM), a utility that allows you to install modules, including modules that contain binary extensions. You should consider using PPM to install a module, as this greatly simplifies the management of modules.

Nevertheless, there are times when it is necessary to build a module from source. Typically, an installation session goes something like this:

  1. Extract the module. This creates a directory based on the name of the archive.

        gzip -d -c Data-Dumper-2.08.tar.gz | tar xvf -

  2. Change directory to the module's directory.

        cd Data-Dumper-2.08

  3. Consult the README file.

        more < README

  4. Run the Makefile.PL script. This uses the MakeMaker module to build a makefile you can build the extension with.

        perl Makefile.PL

  5. Run your make utility. This prepares the module for installation, and compiles any extension if one is present.

        nmake

  6. If this module has tests, run them.

        nmake test

  7. If the tests succeeded, install the module.

        nmake install

See Where can I find Win32 ports of UNIX tools? for information on the availability of tools like gzip and tar.

Where do I get make for Win32?

Nmake is a 'make' like program for Win32 systems by Microsoft. It is included in several Microsoft development tools (such as VisualStudio for .NET) and it is included in the Shared Source Common Language Infrastructure 1.0 Release.

How do I access databases from my Perl script?

DBI

DBI, a Database Interface Module for Perl provides a consistent interface for database application development. DBI supports ODBC drivers as well as the native APIs of certain databases, including Oracle. The DBI home page is located at:

    http://dbi.perl.org/

ADO

The ActiveX Data Objects (ADO) API can be used with the Win32::OLE module. You can use ADO to access any ODBC data source. The Perl-Win32-Database FAQ includes some information on ADO:

    http://unix.za.net/docs/documentation/programming/perl/matt_sergeant/Perl/perl-win32-database.html

The ADO home page is located at:

    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ado270/htm/dasdkadooverview.asp

Win32::ODBC

There are a couple of extensions that have been developed to access databases from ActivePerl. Win32::ODBC is widely popular, and is available on CPAN and at this URL:

    http://www.roth.net/perl/odbc/

Sybase

The Sybperl module allows you to connect to Sybase SQL Server (and possibly Microsoft SQL Server). The Sybperl home page, which includes links to binary releases of Sybperl, is located at:

    http://www.peppler.org/freeware/sybperl.html

If you choose to use a database API that depends on ODBC, you must have an ODBC driver for the DBMS you're using. You will need to configure a data source for that driver on each machine that needs to access the database. For more information on ODBC and how to configure a data source, check the ODBC Control Panel help.

Some DBMSes, such as Microsoft Access and Microsoft SQL Server, can be controlled through OLE Automation (see the next question). See the product documentation for details.

Is there a way to use OLE Automation servers from my Perl script?

Yes. See the documentation for the Win32::OLE module, which is included with Perl. You can use Win32::OLE to control a wide range of Win32 applications and APIs, including ADO.

After reading the documentation, you can read the FAQ on using OLE.

Is there a way to access Data Access Objects (DAO) from my Perl script?

You should use Win32::OLE to access this API. See question Is there a way to use OLE Automation servers from my Perl script? and consult the DAO documentation.

Can I send Internet mail from ActivePerl?

If you need to send Internet mail, you should use Net::SMTP, Mail::Sender, or Mail::Sendmail. For more information on these modules, see How do I send email from ActivePerl?.

Is there a way to access MAPI from my Perl script?

You can use the Win32::OLE module to create an instance of a MAPI session and send a message. In order for this to work, you must have messaging configured correctly on your machine. If you are using Microsoft Exchange, chances are this will work fine.

If you need to send Internet mail, you should use Net::SMTP. For more information on Net::SMTP, see How do I send email from ActivePerl?. Here is an example script that sends mail using MAPI:

    # Sender's Name and Password
    #
    my $sender = "YOUR NAME HERE";
    my $passwd = "YOUR PASSWORD HERE";

    # Create a new MAPI Session
    #
    use Win32::OLE;
    $session = Win32::OLE->new("MAPI.Session")
        or die "Could not create a new MAPI Session: $!";

    # Attempt to log on.
    #
    my $err = $session->Logon($sender, $passwd);
    if ($err) {
        die "Logon failed: $!";
    }

    # Add a new message to the Outbox.
    #
    $msg = $session->Outbox->Messages->Add();

    # Add the recipient.
    #
    $rcpt = $msg->Recipients->Add();
    $rcpt->{Name} = "RECIPIENT NAME HERE";
    $rcpt->Resolve();

    # Create a subject and a body.
    #
    $msg->{Subject} = "Test Message";
    $msg->{Text} = <<EOF;
    This is a sample test message.

    Cheers,

    Mr. Email

    EOF

    # Send the message and log off.
    #
    $msg->Update();
    $msg->Send(0, 0, 0);
    $session->Logoff();

Is there a DBM implementation available for ActivePerl?

Yes, there is. SDBM_File is a free clone of DBM, and is implemented and distributed with the ActivePerl distribution. You can use it as follows:

    use SDBM_File;
    use Fcntl;

    tie( %myhash, "SDBM_File", 'myfile', O_RDWR | O_CREAT | O_BINARY, 0666 )
        or die( "Can't tie: $!" );

    $myhash{"bibim"} = "bap";

    untie( %myhash );

After the DBM file is tied, you can use it just like any other hash.

Is there a way to do GUI programming with ActivePerl?

As of the Perl Resource Kit for Win32, the Tk library has been successfully ported to ActivePerl. Tk version 8xx and above also now has the look and feel of Windows programs, and not the old UNIX look of previous versions.

You can also use the Win32::GUI module which also allows for GUI's to be made/manipulated using Perl. This module uses the standard Windows widgets to give the look and feel of Windows programs.

For Perl Tk information, go to http://www.perltk.org/

For Win32::GUI, go to http://dada.perl.it

Win32::MsgBox allows for a fast and easy way to display a Windows message box, for example:

use Win32;

MsgBox("Test", "This is a test", 48);
# display a message box with an exclamation mark and an 'Ok' button

sub MsgBox {
my ($caption, $message, $icon_buttons) = @_;
my @return = qw/- Ok Cancel Abort Retry Ignore Yes
  No/;
my $result = Win32::MsgBox($message, $icon_buttons,
  $caption);
return $return[$result];
}

The last value, $icon_buttons, is the sum of two values, the value for the icon and the value for the buttons. For example, if you need a message box with a question mark and the 'Ok' and 'Cancel' buttons the value you want is 32 (question mark) + 1 (Ok, Cancel) = 39. The values are listed here:

Icons:
   0 - no icon
  16 - Hand
  32 - Question
  48 - Exclamation
  64 - Asterisk

Buttons:
   0 - Ok
   1 - Ok, Cancel
   2 - Abort, Retry, Ignore
   3 - Yes, No, Cancel
   4 - Yes, No
   5 - Retry, Cancel

Is there a port of Oraperl for Win32?

Oraperl is available as an emulation layer on top of DBD::Oracle. Oraperl is included with the DBD::Oracle distribution. Because the DBI interface is evolving, the Oraperl emulation layer is recommended because its API is fairly stable. Patches are available for DBD::Oracle that allow it to build on Windows. More information is available at:

   http://www.symbolstone.org/technology/perl/DBI/index.html

What modules come with the ActivePerl distribution?

Along with the standard library files, there are several Win32-specific modules that are distributed with ActivePerl. These include:

  • Win32::Clipboard: Perl module for Windows clipboard interaction
  • Win32::Console: Perl module for Windows console interaction
  • Win32::ChangeNotification: Create and use ChangeNotification objects
  • Win32::Event: Use Win32 event objects from Perl
  • Win32::EventLog: Read from and write to the Windows NT event log
  • Win32::File: Manage file attributes (read only, system, hidden...)
  • Win32::FileSecurity: manage ACLs in Perl
  • Win32::Internet: Perl module for Internet extensions
  • Win32::IPC: Wait for objects (processes, mutexes, semaphores)
  • Win32::Mutex: Create and use mutexes
  • Win32::NetAdmin: Administer users and groups
  • Win32::NetResource: Manage resources (servers, file shares, printers)
  • Win32::ODBC: work with ODBC data sources
  • Win32::OLE: Use OLE automation from Perl
  • Win32::Pipe: Perl module for pipes
  • Win32::Process: Start and stop Win32 processes
  • Win32::Registry: Read and manage the Win32 Registry
  • Win32::Semaphore: Create and use semaphores
  • Win32::Service: Manage Windows NT services
  • Win32::Shortcut: Perl module for shell link interface
  • Win32::WinError: For retrieving Win32-defined errors

These are documented on the Win32mod documentation page. There are also a number of subs built into the Win32 package, namely:

  • AbortSystemShutdown: I mean, don't shut down this computer
  • DomainName: Name of the domain this machine is in
  • ExpandEnvironmentStrings: Take a string like %HOMEPATH% and expand it to the actual value
  • FormatMessage: Format a Win32 error code into a error message
  • FsType: Get the file system type of a drive
  • GetCwd: Get current working directory
  • GetLastError: Retrieve the last Win32 error code.
  • GetNextAvailDrive: Returns the next available drive letter
  • GetOSVersion: Get Win32 operating system version
  • GetShortPathName: Returns the 8.3 name of a filename
  • GetTickCount: Time since Windows started, in milliseconds (for timing)
  • InitiateSystemShutdown: Shut down this computer
  • IsWinNT: Is this Windows NT?
  • IsWin95: Or, is it Windows 95?
  • LoginName: Name of logged-in user
  • LookupAccountName: Given a user name, get domain, SID, SID type
  • LookupAccountSID: Given a SID, get domain, user name, SID type
  • NodeName: Name of this machine
  • SetCwd: Set current working directory
  • Sleep: Sleep for a given number of milliseconds
  • Spawn: Spawn a Win32 process
  • ExpandEnvironmentStrings: Take a string like %HOMEPATH% and expand it to the actual value

No longer included in the Win32 module:

  • PerlVersion: Use $] instead
  • GetArchName: Use $ENV{PROCESSOR_ARCHITECTURE}
  • GetChipName: Use $ENV{PROCESSOR_LEVEL} . $ENV{PROCESSOR_ARCHITECTURE}

Where can I find other modules for ActivePerl?

Modules for ActivePerl are available on CPAN (Comprehensive Perl Archive Network), a Perl archive that's mirrored around the world. To find your nearest mirror, check here:

    http://mirrors.cpan.org/

(Note that this will send you to your nearest mirror automagically. Cool, huh?)

What is CPAN and how do I use it?

CPAN is the Comprehensive Perl Archive Network, a collection of pretty much every file you could ever want for Perl programming. The original archive is in Finland, but it is mirrored on FTP servers throughout the world.

You can connect to your closest CPAN mirror using the CPAN redirector at http://www.perl.com. The following URL:

    http://www.perl.com/CPAN/

will redirect your browser to the nearest CPAN mirror (one on your continent and maybe only a few hops away). This URL

    http://mirrors.cpan.org/

lets you pick a CPAN mirror site yourself, as well as giving a little more information.

CPAN is good for finding ActivePerl distributions as well as modules and scripts. However, read

    How can I use modules from CPAN?

for more information.

Is there a library to read or write Microsoft Office or other application files?

In general, there aren't any library modules to read or write application files, like Microsoft Word, Microsoft Excel, Microsoft Access, WordPerfect, Lotus 1-2-3, etc.

However, many if not most major Windows applications now support OLE Automation. You can use the OLE Automation support of Microsoft Office applications to read and write their file formats, for example. See the documentation on your application for information on its support for OLE Automation. See Is there a way to use OLE Automation servers from my Perl script? for more information.

As a special case, many database files, like Microsoft Access, FoxPro, dBase or Paradox files, can be accessed using ODBC (Open DataBase Connectivity). See How do I access databases from my Perl script? for details on how to use ODBC with ActivePerl.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove and David Dmytryshyn of ActiveState, Henning Michael Møller-Nielsen of RTO, Kevin Meltzer and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Modules and sample scripts


ActivePerl faq10 - Embedding and Extending

Embedding and Extending

  • NAME
  • DESCRIPTION
    • How do I write an extension for ActivePerl?
    • How do I embed the Perl interpreter into my C/C++ program?
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq10 - Embedding and Extending

DESCRIPTION

Techniques for Embedding and Extending ActivePerl

How do I write an extension for ActivePerl?

Writing extensions in C or C++ for ActivePerl is identical to writing them for standard Perl. Consult the perlxstut document for complete information and pointers to other sources of information.

As a result of the oneperl effort, you no longer need to build ActivePerl from the source distribution to write or compile extensions. The Perl installation will detect your C compiler (currently, just Visual C++), and configure Perl to use it for compiling extensions.

Note that writing extensions in C or C++ is not easy. You need to have experience writing C programs for Windows platforms before you should even think about writing an extension.

How do I embed the Perl interpreter into my C/C++ program?

Writing applications that contain Perl interpreters using ActivePerl is identical to writing them for standard Perl. Consult the perlembed document for complete information and pointers to other sources of information.

Note that the subject of embedding Perl interpreters inside applications is not a trivial one. You need to have experience writing C programs for Windows platforms before you should even think about writing an embedding Perl interpreters in your application.

NOTE: ActivePerl 5xx series builds had a different mechanism for embedding that was restricted to C++. This is no longer supported. The standard way to embed interpreters now supports all the functionality that used to be available only with C++, and then some. Use the mechanisms described in the perlembed documentation.

AUTHOR AND COPYRIGHT

This FAQ was originally assembled and maintained by Evangelo Prodromou. It has been revised and updated by Brian Jepson of O'Reilly & Associates, David Grove, David Dmytryshyn, and David Sparks of ActiveState.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Embedding and Extending


ActivePerl FAQ - Using OLE with Perl

Using OLE with Perl

  • NAME
  • DESCRIPTION
    • Can I use OLE with Perl?
    • What has changed with OLE since build 3xx
    • How do I print a Microsoft Word document?
    • How do I extract a series of cells from Microsoft Excel?
    • How do I make a chart in Microsoft Excel?
    • How do I save a chart from Microsoft Excel as GIF/JPEG/PNG?
    • How do I run a macro in Microsoft Excel?
    • How do I set the name of a cell in Microsoft Excel?
    • How do I create a new folder in Outlook?
    • How do I use ADO?
    • How do I use Lotus Notes?
    • How do I set the printer?
    • How do I convert a VBA macro to Perl?
    • Where do I find documentation for the object models?
    • OK, but can I at least find the constants that are exported from Win32::OLE::Const?
    • Why doesn't $! get set with the error message I am generating?
    • Why do I get an error when using ODBC and OLE?
    • Why doesn't it work - even after all this?
  • AUTHOR AND COPYRIGHT

NAME

ActivePerl-faq12 - Using OLE with Perl

DESCRIPTION

How to use OLE automation with Perl - through the Win32::OLE module

Can I use OLE with Perl?

Yes - otherwise this FAQ wouldn't have been a separate FAQ. ;-)

If you want to use OLE with Perl you need the Win32::OLE module. And you need to read the documentation that comes with it.

use Win32::OLE doesn't export any variables and functions to the main namespace, so if you want easy access to the in and with functions you should load the module with

use Win32::OLE qw(in with);

What has changed with OLE since build 3xx

A lot - Gurusamy Sarathy and then Jan Dubois redesigned the code and added a bundle of enhancements. Old scripts should run with little or no modifications. When writing new scripts there is no excuse for not using the new Win32::OLE module options.

Look at the Win::OLE module documentation (under Incompatibilities).

How do I print a Microsoft Word document?

Use the method PrintOut on a document object, for example:

use strict;
use Win32::OLE;
use Win32::OLE::Const 'Microsoft Word';

my $Word = Win32::OLE->new('Word.Application', 'Quit');
# $Word->{'Visible'} = 1;         #
  if you want to see what's going on
$Word->Documents->Open("C:\\DOCUMENTS\\test.doc")
|| die("Unable to open document ",
  Win32::OLE->LastError());
$Word->ActiveDocument->PrintOut({
Background => 0,
Append     => 0,
Range      =>
  wdPrintAllDocument,
Item       =>
  wdPrintDocumentContent,
Copies     => 1,
PageType   => wdPrintAllPages,
});

or simply

$Word->ActiveDocument->PrintOut;

How do I extract a series of cells from Microsoft Excel?

If you have a sheet object you can extract the values of a series of cells through $Sheet->Range->{'Value'}, for example:

my $array = $Sheet->Range("A8:B9")->{'Value'};

Now $array[0][0] contains the value of cell A8, $array[0][1] the value of cell B8, $array[1][0] the value of cell A9 and $array[1][1] the value of cell B9.

What is returned is an two-dimensional array (OK, an array with references to arrays) that contains the values of the requested cells.

A complete example is here:

use strict;
use Win32::OLE qw(in with);
use Win32::OLE::Const 'Microsoft Excel';
$Win32::OLE::Warn = 3;                                # die on errors...
my $Excel = Win32::OLE->GetActiveObject('Excel.Application')
    || Win32::OLE->new('Excel.Application', 'Quit');  # get already active Excel
                                                      # application or open new
my $Book = $Excel->Workbooks->Open("C:\\DOCUMENTS\\test.xls"); # open Excel file
my $Sheet = $Book->Worksheets(1);                     # select worksheet number 1
my $array = $Sheet->Range("A8:B9")->{'Value'};        # get the contents
$Book->Close;
foreach my $ref_array (@$array) {                     # loop through the array
                                                      # referenced by $array
    foreach my $scalar (@$ref_array) {
        print "$scalar\t";
    }
    print "\n";
}

To retrieve the formatted value of a cell you should use the {'Text'} property instead of the {'Value'} property. This returns exactly what is being displayed on the screen though! If the column is not wide enough, you get a value of '######':

my $array = $Sheet->Range("A8:B9")->{'Text'};

How do I make a chart in Microsoft Excel?

A good idea would be to record a macro in Microsoft Excel and then convert it to Perl. But here is a complete example:

use strict;
use Win32::OLE;
use Win32::OLE::Const 'Microsoft Excel';

my $Excel = Win32::OLE->new("Excel.Application");
$Excel->{Visible} = 1;

my $Book = $Excel->Workbooks->Add;
my $Sheet = $Book->Worksheets(1);
my $Range = $Sheet->Range("A2:C7");
$Range->{Value} =
[['Delivered', 'En route', 'To be shipped'],
[504, 102, 86],
[670, 150, 174],
[891, 261, 201],
[1274, 471, 321],
[1563, 536, 241]];

my $Chart = $Excel->Charts->Add;
$Chart->{ChartType} = xlAreaStacked;
$Chart->SetSourceData({Source => $Range, PlotBy => xlColumns});
$Chart->{HasTitle} = 1;
$Chart->ChartTitle->{Text} = "Items delivered, en route and to be
  shipped";

How do I save a chart from Microsoft Excel as GIF/JPEG/PNG?

You can use the Export method of a chart. If you have a chartobject the code looks like this

$ChartObj->Chart->Export({
    FileName    => "$graphics_filename",
    FilterName  => 'GIF',
    Interactive => 0});

A complete example that opens an Excel workbook, loops through all the charts and saves them as GIFs and then closes the Excel workbook is here:

use strict;
use Win32::OLE qw(in with);
use Win32::OLE::Const;
use Win32::OLE::Const 'Microsoft Excel';
$Win32::OLE::Warn = 3;        # die on
  errors...

my $filename = 'c:\\documents\\test.xls';
my $filter = 'GIF';           #
  can be GIF, JPG, JPEG or PNG
my $count = 0;

my $Excel = Win32::OLE->GetActiveObject('Excel.Application')
|| Win32::OLE->new('Excel.Application', 'Quit');  #
  use the Excel application if it's open, otherwise open new
my $Book = $Excel->Workbooks->Open( $filename );      #
  open the file
foreach my $Sheet (in $Book->Sheets) {                #
  loop through all sheets
foreach my $ChartObj (in $Sheet->ChartObjects) {  #
  loop through all chartobjects in the sheet
my $savename =
  "$filename." . $count++ . ".$filter";
$ChartObj->Chart->Export({
FileName    =>
  $savename,
FilterName  =>
  $filter,
Interactive =>
  0});
}
}
$Book->Close;

How do I run a macro in Microsoft Excel?

Macros in Microsoft Excel can be run by using the $Excel->Run method, for example:

$Excel->Run("PrintPDFFile");

In order to do this, you of course need to have a macro in Excel that's called 'PrintPDFFile'...

How do I set the name of a cell in Microsoft Excel?

Use the Names->Add method on a sheet, giving it a name and a range object to apply the name to, for example:

$Sheet->Names->Add({Name => 'NetCost', RefersTo => $Sheet->Range('$B$10')});

How do I create a new folder in Outlook?

Again, an example :-)

use strict;
use Win32::OLE;
use Win32::OLE::Const 'Microsoft Outlook';

my $Outlook = Win32::OLE->new('Outlook.Application', 'Quit');
my $ol = Win32::OLE::Const->Load($Outlook);

my $namespace = $Outlook->GetNamespace("MAPI");
my $Folder = $namespace->GetDefaultFolder(olFolderInbox);
my $NewFolder = $Folder->Folders->Add("Test1");

How do I use ADO?

To use ActiveX Data Objects (ADO):

  use strict;
  use Win32::OLE;
  use Win32::OLE::Const 'Microsoft ActiveX Data Objects';
  my $Conn = Win32::OLE->new('ADODB.Connection'); # creates a connection object
  my $RS = Win32::OLE->new('ADODB.Recordset');    # creates a recordset object
  $Conn->Open('DBname');                          # opens the database connection

  my $Fields = ['Id', 'Name', 'Phone'];
  my $Values = [1, 'Joe Doe', '555-1234'];
  $RS->AddNew($Fields, $Values);                  # adds a record

  print "This didn't go well: ", Win32::OLE->LastError(), "\n";
      if (Win32::OLE->LastError());

  $RS->Close;
  $Conn->Close;

More information can be found in:

  • The ADO FAQ at http://support.microsoft.com/support/kb/articles/Q183/6/06.asp
  • The Perl Journal #10 - Win32::OLE by Jan Dubois.

How do I use Lotus Notes?

Lotus Notes can be accessed through OLE like this:

  use strict;
  use Win32::OLE;
  my $Notes = Win32::OLE->new('Notes.NotesSession')
      or die "Cannot start Lotus Notes Session object.\n";
  my ($Version) = ($Notes->{NotesVersion} =~ /\s*(.*\S)\s*$/);
  print "The current user is $Notes->{UserName}.\n";
  print "Running Notes \"$Version\" on \"$Notes->{Platform}\".\n";
  my $Database = $Notes->GetDatabase('', 'help4.nsf');
  my $AllDocuments = $Database->AllDocuments;
  my $Count = $AllDocuments->Count;
  print "There are $Count documents in the database.\n";
  for (my $Index = 1 ; $Index <= $Count ; ++$Index) {
      my $Document = $AllDocuments->GetNthDocument($Index);
      printf "$Index. %s\n", $Document->GetFirstItem('Subject')->{Text};
      my $Values = $Document->GetItemValue('Index_Entries');
      foreach my $Value (@$Values) {
          print " Index: $Value\n";
      }
      last unless $Index < 5;
  }

You can access all objects that are accessible to LotusScript. The LotusScript classes can be seen at http://www.lotus.com/products/lotusscript.nsf.

See also the Lotus Notes section of The Perl Journal #10 - Win32::OLE by Jan Dubois.

How do I set the printer in Word?

The active printer can be set and retrieved through the word application object with $Word->{ActivePrinter} = $printername.

How do I convert a VBA macro to Perl?

If you record a macro in Microsoft Office, this can often be translated directly into Perl. In Visual Basic for Applications (VBA) the syntax is like this:

object.method(argument).property = value

In Perl this becomes

object->method(argument)->{property} = value;

So for example this code from VBA:

ActiveChart.Axes(xlCategory, xlPrimary).CategoryType = xlCategoryScale

becomes this in Perl:

$Chart->Axes(xlCategory, xlPrimary)->{CategoryType} = xlCategoryScale;

Where do I find documentation for the object models?

The best way to learn about methods/properties would be through an OLE type browser if the documentation is unavailable.

If you have Microsoft Excel or Microsoft Word available, go into the Visual Basic Editor (Alt+F11). Now you can open the object browser window (F2) and see what you find.

There is also an OleView program (various names and versions) included in Microsoft Visual C++ / Microsoft Visual Studio if you don't have Office. Or you can download it from the Microsoft COM website (http://www.microsoft.com/com/).

But it is still possible that Notes doesn't reveal anything; objects are not required to provide type info support. For example Lotus Notes doesn't reveal nothing about its internal constants, methods and properties; you have to look them up in the documentation.

For Lotus Notes look at http://www.lotus.com/products/lotusscript.nsf.

OK, but can I at least find the constants that are exported from Win32::OLE::Const?

Yes, you can use the following code example to view all the constants - you really shouldn't need this, but if you want to know what's going on, it might help:

use strict;
use Win32::OLE;
use Win32::OLE::Const;

my $xl = Win32::OLE::Const->Load("Microsoft Excel");
printf "Excel type library contains %d constants:\n", scalar keys
  %$xl;
foreach my $Key (sort keys %$xl) {
print "$Key = $xl->{$Key}\n";
}

Generally you should look at the documentation for Win32::OLE::Const.

Why doesn't $! get set with the error message I am generating?

Error messages from Win32::OLE doesn't go to the $! variable, but can be accessed as Win32::OLE->LastError()

Why do I get an error when using ODBC and OLE?

For some reason you get an 'OleInitialize' error if you open an OLE application first and then open an ODBC connection to the Access ODBC driver. If you do it the other way around, there is no problem with this.

It looks like the Access ODBC driver calls OleInitialize(). This fails when Win32::OLE already initialized the COM subsystem as "apartment threaded".

In order to remove the error either start the ODBC driver before the OLE application or, better yet, initialize the OLE system with Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);

Why doesn't it work - even after all this?

Execute your scripts with perl -w and use strict - this catches most of your errors. Apart from this, read the documentation for Win32::OLE (a good start) and possibly the documentation for the object you are trying to use.

In the case of Microsoft Office 97, make sure that you have at least updated to Service Release 1 - much of the OLE in Microsoft Office 97 is broken without this update.

AUTHOR AND COPYRIGHT

This FAQ was compiled by Henning Michael Møller-Nielsen of RTO based on examples by many people, especially Jan Dubois. It is maintained by Henning Michael Møller-Nielsen, Philip Martin, Kevin Meltzer and Eric Smith at perlwin32faq@rto.dk.

This FAQ is in the public domain. If you use it, however, please ensure that you give credit to the original authors.

ActivePerl FAQ - Using OLE with Perl


Active Server Pages

  • Active Server Pages
    • The Script Delimiters
    • The Scripting Host
    • Creating An ASP Page
  • The ASP Interface
    • The ASP Intrinsic Objects
      • The Application Object
      • The ASPError Object
      • The ObjectContext Object
      • The Request Object
      • The Response Object
      • The Server Object
      • The Session Object
  • Active Server Pages Samples
    • Say "Hello World!"
    • Accessing HTTP Server Variables
    • Reading the QueryString
    • Interactive Web Forms
    • Database Connections (ADO and ASP)
  • Variants and Binary Data
    • To Read And Display Binary Large Objects (ADO and ASP)
  • Appendix A
    • How To Set Up A System DSN
    • Why Not To Use A System DSN
    • How To Use The Native OLE DB Provider
  • Appendix B
    • Book Resources
    • Online Resources
  • AUTHOR AND COPYRIGHT

Active Server Pages (ASP)

Introduced in 1996, Active Server Pages (ASP) is an easy to learn server-side technology from Microsoft that has taken the web by storm. ASP is implemented as a set of objects with built-in features for fast and simple access to common services provided by the web-server for the Internet. As we will see, there are versatile reasons for using ASP as a server-side technology with ActivePerl.

To begin, if you in general are unfamiliar with server-side technologies, let's start at the core by describing the need-to-know about ASP. ASP is a feature that installs with Microsoft's Internet Information Services (IIS) web-server. No special interaction or configuration is needed afterwards, and it should run out of the box just as easily as IIS. Fundamentally, a server-side technology such as ASP puts no requirements on the client or browser, and, as a result, no browser-compatibility issues will ever occur, no browser plug-ins have to be installed, and the client does not need a local installation of ActivePerl.

Since there are no client requirements for ASP, it needs something on the server-side that tells it what to do with its features. A special implementation of a scripting language is therefore installed on the server and used in order to control and program ASP; PerlScript, which installs with ActivePerl, is suitable for the role as scripting language because it brings the power of Perl into the environment of ASP and there merges it with the services provided by ASP. There are only two things that you either may already know or will need to learn while using PerlScript:

  • The Active Server Pages Object Model
  • How Perl Works with Objects

On the Internet, ASP serves documents of its own filetype as opposed to familiar document types like HTML documents. This is so that the ASP document can be processed on the server side before returned to the client's browser. An ASP document has the file extension .asp, and it provides both existing features derived from ASP and the ability to execute script commands within the document. The file extension is by the webserver recognized in a special way which results in the underlying technology executing script commands that are within the file and treat other markup such as HTML in a standard fashion. The source code of your saved file's PerlScript script commands will by default never be available to the user when choosing to view the document source in the browser, so any script that you write can not be copied. The reason for this is because everything is processed on the server side and what is returned to the browser is a standard format such as HTML.

For a closure, it deserves to be repeated that if you are unfamiliar with object-oriented programming in Perl, it is strongly recommended that you sometime browse the Perl documentation on object-oriented programming to get a basic understanding of the aspects of an object and its origin. Next up, let's look at how to embed PerlScript commands within an ASP document.

The Script Delimiters

To successfully execute the script commands within an ASP file, you must specify what scripting language ASP should use to interpret the script commands. You can do this within the .asp document by either setting a default scripting language in which all script commands within the script-delimiters <% and %> will be executed by the specified scripting language. Either you can apply that setting within the Microsoft Management Console's IIS snap-in or you can use what ASP recognizes as a page command, which is indicated by the special directive @. The following example is for illustrational purposes only and it shows you how to set the default scripting language for the ASP file to PerlScript; as a result, all commands will be treated by the PerlScript engine; however, please note that no actual output or result is being displayed by the script, so if you run the code shown in the example below, you won't see an output although the code is being executed and interpreted.

    <%@ Language=PerlScript %>
    <%
    for($i=0; $i<=10; $i++) {
    #
    # Your Perl code here
    #
    }
    %>

In addition to page-commands, you can set the scripting language for a defined scope by using the <SCRIPT Language=PerlScript RUNAT=Server> and </SCRIPT> delimiters. This results in the scripting language only executing the code within the <script> elements regardless of what the default scripting language is set to for a language by the webserver or by an ASP page command for the current document.

    <SCRIPT Language=PerlScript RUNAT=Server>
    for($i=0; $i<=10; $i++) {
    #
    # Your Perl code here
    #
    }
    </SCRIPT>

The Scripting Host

When Active Server Pages acts as the scripting host for PerlScript, it is initalized as a host first when an ASP file on the web-server is requested by the way of a URL (such as http://www.domain.com/home.asp). The web-server locates the file, and the scripting host locates the script commands that are within the script delimiters. The chunks of code found within the delimiters are passed on to PerlScript, which creates a Perl interpreter that treats the code. Afterwards, it returns to the scripting host, which waits for the next incoming call. Certain rules apply to when you write code to interact with scripting hosts such as ASP, and let's look at one of those necessary things to know by illustrating it as a parallel to writing a command-line Perl script. When you began programming Perl, among the first things you probably learned was how to print text to the screen, and it is not unusual that such a script looks as follows.

    print "Hello World";

As seen, the "print()"-function of Perl outputs the string "Hello World" to what is known as the Standard Output. PerlScript, too, will send any output to what it knows as Standard Output, and when executed within the ASP scripting host, the PerlScript engine will use the features of the host's object-model in order to reach the standard output. Essentially, the host provides a set of features, and you pick the scripting language in which you wish to write your application to interact with the host. In ASP, you need to know the host because it decides what method and what object you need to deploy of the host's in order to output a string. A scripting language would become extremely bloated if it had to keep track of all those things. In contrast, the scripter needs to keep track of such features. :-) To send "Hello World" to the client's browser by using ASP, you call the "Write()"-method of the Response object as in the next example.

    $Response->Write("Hello World");

In essence, it is of most importance that you know the object-model of the ASP scripting host within which you use PerlScript so that you know what object to call and how to get the best performance out of your application.

Creating An ASP Page

When looking back, the little we've seen about ASP so far is that it contains a set of objects that you can use for your programming. It also requires a scripting language that is used to access these objects, and for that purpose, PerlScript can be used to execute Perl commands that are mixed and embedded within the HTML of your Active Server Pages document. Lastly, the ASP document has its own file extension .asp which is recognized by the web server as a document parsed for first script commands and then HTML tags.

    1) Create a file named PerlScript.asp
    2) Edit it and enter "<HTML> Hello World </HTML>"
    3) Save the file where you can access it by a URL such as http://localhost/. On IIS, the following path is often valid <device>:\inetpub\wwwroot\ where <device> is a hard-disk such as C:\ or D:\
    4) Run the file in your browser by entering the URL pointing to PerlScript.asp; for example, http://localhost/PerlScript.asp

If it instead of finding the file reports an error such as "File Not Found," you need to open Windows Explorer and reassure yourself of that the file is saved with the .asp file-extension and in the correct physical location for being accessible by the browser. If the browser finds the file and "Hello World" is outputted, you can place a few script commands in the file and rest assured that ASP will execute everything as for which it was built. Edit the file so that is looks as follows.

    <%@Language=PerlScript%>
    <HTML>
    <TITLE> PerlScript Test </TITLE>
    <%
    for($i=0; $i<=10; $i+=2) {
      $Response->Write("<FONT SIZE=$i COLOR=#000000>");
      $Response->Write("Hello World! </FONT> <BR>");
    }
    %>
    </HTML>

The script shown is used only to output HTML and text. Essentially, the Response object's "Write()"-method sends the HTML and variable value of $i to the browser. However, $i is a part of the HTML Font element, so the result is that the font size is increased by 2 for each time "Hello World" is sent to the client's browser. You could also write the script this way:

    <HTML>
    <TITLE> PerlScript Example </TITLE>
    <script language=perlscript runat=server>
    for($i=0; $i<=10; $i+=2) {
      $Response->Write("<FONT SIZE=$i COLOR=#000000>");
      $Response->Write("Hello World! </FONT> <BR>");
    }
    </script>
    </HTML>

A closure to this example, there is a shorthand for writing $Response->Write($variable), and it is not available when already within script delimiters; however, to easily mix variables with HTML you can automatically call the mentioned method by <%=$variable%> where the equal-sign automatically translates into $Response->Write(). For example:

    <HTML>
    <TITLE> PerlScript Example </TITLE>
    <% @Language=PerlScript %>
    <% for($i=0; $i<=10; $i+=2) {
    %>
    <FONT SIZE=<%=$i%> COLOR=#000000>
    Hello World!
    </FONT>
    <BR>
    <% } >%
    </HTML>

The ASP Programming Interface

Providing an interface to common tasks for a web programmer, ASP simplifies web-programming by making the simple tasks even easier. The features of ASP are implemented and exposed as objects, and, in addition, a scripting language is enabled to not only use those features of the ASP host, the language can certainly use its own features, too.

The ASP Intrinsic Objects

In object-oriented programming as we know it, the programmer is required to create an instance of the object she wishes to use. The ASP objects, on the other hand, are "intrinsic", which means that they are already instantiated and available to your scripting language engine. No pre-work at all is associated with these objects and you can access them at any time. Now, each object encapsulate a set of very specific services and provides shorthand access to common tasks for the web developer such as reading the data submitted from a web-form, reading and writing cookies, redirecting the client's browser, and also extended functionality such as the ability to identify each user as a unique client and associate private server-side variables with her. Before diving into the syntax, these are the objects as of ASP 3.0:

Application

The Application Object an object that is a place-holder for global variables stored on the server side. A global variable in this sense is a variable that is global to what is known as the IIS application. The IIS application defines the physical space of a webserver such as the range on the hard disk for the URL http://members.someperlsite.com/. A webserver can have more than one IIS application, but there is only one ASP application object per IIS application. Confused? Hang on a minute. The Application object, like the Session object, has what is called a collection. The collection contains variables created by you. Whenever you want to create a variable, the variable must be put on the contents collection, and the following is one way of doing it.

    # Set an application variable
    #
    $Application->Contents->SetProperty('Item', 'myName', 'Tobias');

The contents collection can store scalar variables, arrays, or objects that somehow are associated with all users; for example, a visitor counter or a connection-string used to connect to a database through the Microsoft universal ADO application-programming interface. The variable can be accessed easily, too.

    # Access an application variable
    #
    $Application->Contents->Item('myName');

However, when you're comfortable within the Microsoft Management Console and can set and define your own IIS applications, you will notice that there is only one ASP Application object per IIS Applcation and the variables placed in the Contents colleciton are only available within that IIS application and no other. If it's a bit confusing, it's guaranteed to have cleared out after playing around with this for a while. It's the most abstract part about ASP if you are not used to defining IIS applications. On the downside, Personal Web Server does not enable you to define more than one IIS application.

ASPError

The ASPError object is the only new object that shipped with ASP 3.0. It contains detailed information about an error which occured during the processing of an ASP page. Unless told otherwise by the administrator, ASP 3.0 redirects the client to a page named 500-100.asp when an error occurs, and in that page, the ASPError object is deployed to show detailed descriptions about the error. You can with PerlScript easily also extend the use the 500-100.asp page to perform custom tasks such as emailing you a formatted page of the contents of the ASPError object on an arror or writing it to a special log. Some of its useful properties include: SourceCode for returning the source code of the part of a script that generated the error, Category for tracking down the categoru of the error to ASP, scripting language, or an object, File for the name of the file processed when error was generated, and Description to return a description of the error; however, please note that ASPError objects are only returned by the Server object's GetLastError method.

    # Return the ASPError object
    #
    $ASPError = $Server->GetLastError();

    # Output the error's description
    #
    $Response->Write( $ASPError->{Description} );

ObjectContext

The ObjectContext object is used for a page that is run as a transaction. This object enables you to commit or abort a transaction, which is an important functionality for deployed business applications. Its only methods are SetAbort() and SetComplete(). They are used to commit or abort the transaction. Before this can be used, your page must include a @TRANSACTION page command in the page, whereas you are enabled only to define @ once per file; however, you can use multiple directives within the @ such as <%@directiveA=something directiveB=somethingelse%>. If you use PerlScript a lot, you are better off setting it as the default language in the Microsoft Management Console. Setting the default language in the MMC is unfortunately not an option for Personal Web Server. PWS is good for practicing a scripting language and ASP, but it is not good for tailormaking your webservice in terms of IIS applications and other tasks that are administrative. For example, it does not have the Microsoft Management Console. What PWS mainly does is to allow you to publish and develop Active Server Pages within reson while it hides the administrative tasks.

Request

For good reason, the Request object is a widely used object. It contains a collection of information such as form-data or cookies gathered from the client. With this object you can gather the contents submitted from any type of web-form, read server variables or the contents of a digital client certificate. You can also read binary data such as an uploaded file by first determining the number of bytes sent with the TotalBytes-property and then read it with the BinaryRead($bytes_to_read) method.

    # Get the number of total bytes in the request
    #
    $bytes_to_read = $Request->{TotalBytes};

    # Read and return a variant array of type VT_U1
    #
    $read_bytes=$Request->BinaryRead( $bytes_to_read );

In the Request object, collections that you can read includes ClientCertificate for digital certificated, Cookies for cookies sent with the HTTP request, Form for data posted by a web form using the POST method, QueryString for data passed with the QueryString or GET method from a web form, and ServerVariables for HTTP environment variables such as the server software or the users browser.

    # Let's see what's in the ALL_HTTP variable
    #
    $Response->Write( $Request->ServerVariables('ALL_HTTP')->Item() );

Response

The Response Object is responsible for sending data from the client to the server. For example, you can print strings such as HTML or scalar variables, and you can also print binary data such as images, set cookies, control cache, character sets, and content-types, plus send the client status headers, append data to the log, set PICS labels, and see if the client is still connected. A cookie can contain the attributed Domain, Expires, HasKeys, Path, and Secure, and you first declare a cookie before setting these attributes.

    # Ask the client's browser if it wants a cookie
    #
    $Response->Cookies->SetProperty(
                'Item',
                'someCookie',
                'Hi! This is a cookie!'
                );

    # ==================================================
    # Let's set some attributes of the cookie!
    # ==================================================

    # This is the domain that can read the cookie; to specify it further,
    # use the Path-attribute to define a more complete URL
    #
    $Response->Cookies('someCookie')->{Domain} = 'somesite.com';

    # The expiration date for the cookie
    #
    $Response->Cookies('someCookie')->{Expires} = 'January 1, 1999';

    # Not a secure cookie; 1 defines it as secure
    #
    $Response->Cookies('someCookie')->{Secure} = 0;

Server

The Server object provides certain server-side functions. Its only property is Timeout which defines for how many seconds a script should try executing before returning an error. This setting can also be set in the Microsoft Management Console. In terms of methods, you can create instances of COM objects in your page, encoding HTML and URL's, mapping the physical path to a file by providing its URL, execute other .asp files, and seamlessly transfer the client to a new page while maintaining the state of the current ASP objects, which means that any form data that was gathered can be transferred between pages.

    # Open the file in the virtual path /scripts/forum.asp/
    #
    open( FILE, $Server->MapPath('/scripts/forum.asp') );

You can use CreateObject('ProgID') to return a valid COM object to the Active Server Page. For example, to instantiate an ADO object, you'd do the following:

    # Create an ADO Connection object
    #
    $ADOConnObj = $Server->CreateObject('ADODB.Connection');

When using strings, HTMLEncode($string) encodes charaters such as greater than and less than into its valid character represenation within an HTML page. This prevents, for example, users to post HTML to a chatroom or messageboard. The URLEncode($string)-method encodes a string for valid represenation as a URL. New in IIS 5, you can Execute('/scripts/page.asp') ASP scripts in other files, and to transfer the user without losing the state of the Request object's existing variables such as the contents of the Form-collection you can use the Transfer-method.

    # Transfer the user to a different page
    #
    $Server->Transfer('/step2.asp');

Worth noting about the transfer method is that it takes place on the server side. There is never a request sent to the users browser telling the browser to redirect, thus a roundtrip is spared.

Session

The Session object enables you to associate variables with each unique client and keep the variables stored until she leaves the domain. It has the same abilities as the Application object, but with the important difference that these variables will only be available to the single user and the script engine, making it ideal for applications such as shopping carts. The syntax is the same as the Application object in terms of adding entities to the Contents collection. In addition, you can set the Timeout-property to the number of minutes that you wish the Session to last before it is ended or you can deliberately end the Session by calling the Abandon-method and then redirect to a new page. The redirection is very important! Other properties that you can use is CodePage which is used for Symbol Mapping, LCID for the locale identifier, and SessionID which uniquely identifies the client.

For both the Session and Application object, the Contents collections contain a Remove() and RemoveAll() method. Remove() takes either an index or a keyname for the variable in the Collection to remove, and RemoveAll() removes all variables stored in the collection. In example, consider that you have stores a property called "myName" in the Session s Contents collection, you would remove it as follows:

    $Session->Contents->Remove('myName');

Earlier than IIS 5, Remove() and RemoveAll() are not available, so you will have to use the Perl built-in function undef(),.

The Active Server Pages Samples

The following examples are taken from the \eg\aspsamples\ directory, which will be installed on your machine if you installed the example files with ActivePerl. In addition to these examples, there are useful and advanced examples in the \eg\aspsamples\ directory.

Say "Hello World!"

File Location: [\eg\aspsamples\hello.asp]

In this example, a for-loop is used to print a series of "Hello World!" strings of increasing font-size. Notice the <%=$i%> call, which is shorthand for writing $Response->write($i).

    <%
    for ($i = 3; $i < 8; $i++) {
    %>
    <font size=<%= $i %>>
    "Hello World!"
    </font>
    <BR>
    <%
    }
    %>

Accessing HTTP Server Variables

File Location: [\eg\aspsamples\srvvar.asp]

The HyperText Transfer Protocol (HTTP) variables that are sent with each request can be retrieved from the Request object. You need to specify that you want the server variables, and then call a method named "Item" in order to return the value.

    <%= $Request->ServerVariables('SERVER_SOFTWARE')->Item() %>

Reading the QueryString

File Location: [\eg\aspsamples\qstring.asp]

The QueryString can be either manufactured by handcoding it, or it is automatically generated for form-fields if you use a HTML form that uses the GET method for submitting its data. The following is one way you can use it.

    <a class="doc" href="<%=$Request->ServerVariables('PATH_INFO')->item()%>?Size=Medium&Color=Yellow">
    This link will demonstrate the Request object's QueryString collection.
    </A>

    The current value of Size is
    <%= $Request->QueryString('Size')->item() %>

    <BR>

    The current value of Color is
    <%= $Request->QueryString('Color')->item() %>

Interactive Web Forms

File Location: [\eg\aspsamples\wform.asp]

In this example, the POST method is used to submit a form. The Request object gathers data by calling the Form-element by its name in $Request->Form('name')->Item() instead of in $Request->QueryString('name')->Item() as it is passed when the method is GET.

Once fetched, the "$Server->HTMLEncode()"-method is called to correctly translate HTML tags into proper encoding so that no HTML tags can be submitted.

      <%
my($name) = $Request->Form('Yourname')->Item();
$name = $Server->HTMLEncode($name);
%>

<%
if($name eq 'Enter Your name here') {
$Response->Write("Please type your name in the box below and then
  press the button");
}
else {
$Response->Write("Hello $name");
}
%>

<CENTER>
<FORM ACTION="wform.asp" METHOD="POST">
<INPUT TYPE="Textfield" NAME="Yourname" MAXLENGTH="30"
  VALUE="Enter Your Name Here">
<INPUT TYPE="SUBMIT" VALUE="Click Me">
</FORM>
</CENTER>

Database Connections (ADO and ASP)

File Location: [\eg\aspsamples\ado1.asp]

This database example requires the ActiveX Data Objects from the Microsoft Data Access Components, available at http://www.microsoft.com/data/.

    <%
    # Create an instance of the ADO Connection object
    #
    $Conn = $Server->CreateObject("ADODB.Connection");

    # Open a system DSN
    #
    $Conn->Open( "ADOSamples" );

    # Execute an SQL Query
    #
    $RS = $Conn->Execute( "SELECT * FROM Orders" );

    # Read a property to get the number of columns
    # present in the Recordset returned from the
    # query.
    #
    $count = $RS->Fields->{Count};

    # Print out the names of each column
    #
    for ( $i = 0; $i < $count; $i++ ) {
    $Response->Write( $RS->Fields($i)->Name );
    $Response->Write("<BR>");
    };

    # Loop the Recordset until there are no more records
    #
    while ( ! $RS->{EOF} ) {
    for ( $i = 0; $i < $count; $i++ ) {
    $Response->Write(" ");
    $Response->Write($RS->Fields($i)->{Value});
    $Response->Write("<BR>");
    };

    # Move to the next record
    #
    $RS->MoveNext();
    };

    # Close the Recordset
    #
    $RS->Close();
    $Conn->Close();
    %>

As an important note, the ActiveX Data Objects is an easy-to-use and easy-to-learn set of objects that provides universal data access. Regardless of what language you use ADO from within, the application-level programming interface of ADO remains the same.

Moreover, not only can you access relational databases such as MS Access, SQL Server, or Oracle with these components, you can access non-relational data such as video, filesystems, and email systems -- all from one single interface. It is the post-ODBC industry standard for accessing data stores, and a fast and powerful way to get your databases out on the Internet.

Variants and Binary Data

At times, you will be working with binary data that is passed to PerlScript from a COM object or passed from PerlScript to a COM object. In Windows Script, the data comes in a data type called a Variant. The Variant resembles Perl's scalar variables because it was designed for holding most types of data. And most of the time, Perl is able to determine what type of Variant that is being returned to it from a COM object; however, with binary data, it sometimes becomes necessary to define what the variant is exactly for a type, so the "Win32::OLE::Variant"-module provides functionality for this conversion and much more. For example, if you have a GIF image stored in the variable $image, and you want to output it to the screen by using the Response object's "BinaryWrite()"-method, you must convert it to a VT_UI1 variant before it is passed to the "BinaryWrite()"-method simply because a VT_UI1 variant is expected by the method.

    use Win32::OLE::Variant;

    # Tell the browser a GIF image is on its way
    #
    $Response->{ContentType} = "image/GIF";

    # Send the GIF as a VT_UI1 Variant
    #
    $Response->BinaryWrite(Win32::OLE->Variant(VT_UI1, $image));

An issue of needing to convert to the accurate type of Variant occurs most of the time when working with binary data; two concrete examples are binary large objects (BLOBs) returned from SQL Server and binary data being output through the ASP Response object's "BinaryWrite()"-method. The "BinaryWrite()"-method expects a Variant of the type VT_UI1, and that is the same type which is returned when reading a BLOB from SQL Server. However, as the variant is returned to PerlScript, it converts it into the type of scalar that most resembles the variant, and although that is an accurate conversion for use in Perl, you will need to convert data if it's used in a VT_UI1 context.

To Read And Display Binary Large Objects (ADO and ASP)

The following example will demonstrate how ADO can be used to read a Binary Large Object from SQL Server, and how ASP is used to output the BLOB as an image.

    <%@Language=PerlScript%> <%
    use Win32::OLE::Variant;

    # One note, 40 as bytes to read per GetChunk()-call is not
    # a good number to choose for a real application. I emphasize
    # _not_. Instead, whatever you choose depends much on your
    # system and the power of it; however, 4000 is a much more
    # realistic real-world number compared to 32.
    #
    my($blob_size, $read_size, $bytes_to_read) = (0, 0, 32);

    # Let's create the Connection object used to establish the connection
    #
    $conn = $Server->CreateObject('ADODB.Connection');

    # Open a connection using the SQL Server OLE DB Provider
    #
    $conn->Open(<<EOF);
    Provider=SQLOLEDB;
    Persist Security Info=False;
    User ID=sa;Initial Catalog=pubs
    EOF

    # Execute the query which returns the BLOB from our database
    #
    $rs = $conn->Execute("SELECT logo FROM pub_info WHERE pub_id='0736'");

    # Get the size of the BLOB
    #
    $blob_size = $rs->FieldS('logo')->{ActualSize};

    # And here's the routine for reading in the blob. Alternatively you can
    # make a control statement that says if the $blob_size is less than
    # 4096, it should just swallow it in one chunk, but the routine below
    # is good to have handy
    #
    while($read_size < $blob_size) {
      $buffer .= $rs->Fields('logo')->GetChunk($bytes_to_read);
      $read_size += $bytes_to_read;
      if($read_size+$bytes_to_read > $ blob_size) {
        $bytes_to_read = $blob_size - $read_size;
      }
    }

    # Make a VT_UI1 variant of the retrieved Chunks
    #
    $image = new Win32::OLE::Variant(VT_UI1, $buffer);

    # Tell the browser that the content coming is an image of the type GIF
    #
    $Response->{ContentType}="image/gif";

    # Do a binarywrite of the VT_UI1 variant image
    #
    $Response->BinaryWrite($image);
    %>

Appendix A

How To Set Up A System DSN

The System Data Source Name is information stored in the Windows-registry. The information is used by your application to connect to a database. To create a SystemDSN you must have a database ready to be used by your application and know the path to the database. When the information above is gathered you open "32 Bit ODBC" from the control-panel andclick on the "SystemDSN"-tab. Choose to "Add" a new SystemDSN and select the driver for your database. Enter the "Data Source Name" that you will call on the database by from your application, then click on the "Select"-button and browse to your database-file. Okay everything, then close the program. You'll now be able to call on your database by the Data Source Name you entered for it as follows:

    $Conn = $Server->CreateObject("ADODB.Connection");
    $Conn->Open("Name");

Why Not To Use A System DSN

With the ActiveX Data Objects (ADO), the layer that connectes to a database is called the OLE DB layer. It is the very closest to the physical database, and directly connecting to OLE DB is ADO. Most databases will have what is called an OLE DB Provider, and if you have worked with ODBC, the OLE DB provider is OLE DB's equivalent of the ODBC driver. In ADO, ideally you should connect via ADO directly to OLE DB and from OLE DB directly to the physical database or other data store. A System DSN is for ODBC data sources and it causes OLE DB to wrap an ODBC driver within itself, which adds an overhead and reduces performance.

How To Use The Native OLE DB Provider

There are a number of things you can do to get the native provider set up. When you have it set up, you simply replace the name of the system DSN with the string that has been produced in order to connect to the data store using the native OLE DB provider. First, try to create an Universal Data Link file by doing the following:

  1. Create a file named connectionstring.udl.

  2. Right-click on it.

  3. Choose Properties.

  4. Choose the OLE DB Provider to use.

  5. Define what source to connect to and possibly a username and password.

  6. Click "Test Connection".

  7. Open the file in "Notepad".

  8. Highlight the connectionstring and press CTRL+C to copy it into memory.

  9. Paste it into your ADO application by pressing CTRL+V.

If you are not lucky enough to have .udl, locate a friend who has it or dig around for the connectionstrings. It is more than feasible that there are texts on it available on the Internet, too. To give an example, this is what a typical connectionstring looks like for an Access database:

    Provider=Microsoft.Jet.OLEDB.4.0;
    User ID=Somebody;
    Data Source=c:\\access.mdb;
    Persist Security Info=False

And here's one for SQL Server:

    Provider=SQLOLEDB;
    Persist Security Info=False;
    User ID=sa;
    Initial Catalog=Northwind

Appendix B

Books Resources

    ActivePerl with ASP and ADO:
    by Tobias Martinsson
    ISBN 0471383147
    URL: http://www.wiley.com/compbooks/

Online Resources

  • Microsoft Data Access Components; MDAC includes ADO, OLE DB, and every component needed for getting your databases out on the Internet.
  • Windows 95 users will have to download the NT Option Pack from Microsoft and install Personal Web Server which ships with it. Win 98 already has it on its CD.
  • The ASP PerlScript mailing list is pretty much where the most questions and answers on PerlScript and ASP circulate.
  • PerlScript Community is a Deja community for users who want to find users that PerlScript.
  • The Perl-Win32-ASP FAQ, maintained by Matthew Sergeant.

AUTHOR AND COPYRIGHT

Copyright (c) 2000 Tobias Martinsson. All Rights Reserved.

When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work may be distributed only under the terms of Perl's Artistic License. Any distribution of this file or derivatives thereof outside of that package require that special arrangements be made with copyright holder.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

Active Server Pages is copyright (c) Microsoft Corporation. All rights reserved.

Active Server Pages


Rough Guide to Windows Script Host

Windows Script Host (WSH)

  • Windows Script Host (WSH)
    • Running a WSH File
    • The Object Model
      • The Windows Script Object
      • The WshShell Object
        • Creating Shortcuts
        • Special Folders
        • working with The Registry
        • Miscellanous
      • The WshNetwork Object
    • XML Element Referece
      • <job>
      • <script>
      • <resource>
      • <reference>
  • AUTHOR AND COPYRIGHT

Windows Script Host (ASP)

Windows Script Host (WSH) is a scripting host for ActiveX Scripting Engines such as PerlScript. As a host, WSH enables you to use the scripting language from the command-line and from within the Windows desktop with the WSH features.

Running a WSH File

In order to execute a WSH-file, use one of two executable files depending on your needs: WScript.exe for Windows desktop files and CScript.exe is for command-line scripts. You can set the behavior and appearance of these executed scripts by running the executable without providing a file; if so, WScript will display a properties page that you can modify, and CScript will show the available switches. At work, WSH enables you to use more than one scripting engine in the same file, include typelibraries, and run more than a single job from one file to name a few.

Installing ActivePerl on Windows registers the .pls extension for use with the Windows Scripting Host.

The Object Model

Implemented as an object-model, WSH provides a simple interface for its tasks. As you author, the WSH file uses XML as its markup for separating the elements. Let's look at a simple WSH file that prints "Hello World!".

<Job ID="HelloWorld">
<script language=PerlScript>
    $WScript->Echo("Hello World!");
</script>
</Job>

The XML Job-elements encloses the ID of the Job that is run, and the script elements define PerlScript as the script language to use. You will experience different results depending if you execute this from the command-line or from the windows desktop. The first instance will print text to the screen, but the Windows desktop will pop up a messagebox with "Hello World!" Next, let's look at what the WScript object has to offer.

The Windows Script Object

The WScript object is a built-in object; therefore, you do not need to create a specific instance of it within your WSH. On the contrary, the object in place is used to create instances of most other objects exposed through the WSH programming interface.

The CreateObject method will create an instance of a given object. In the following example, we'll see how an ADO Connection object is easily created within WSH.

  <Job ID="ADOSample1">
<script language=PerlScript>
$conn = $WScript->CreateObject('ADODB.Connection');
$conn->Open('ADOSamples');

if($conn->{State} == 1) {
$WScript->Echo("Connection
  Successful!")
}
else {
$WScript->Echo("Connection
  Failed ...");
}
</script>
</Job>

In addition to the above, you can specify a second parameter in the call to CreateObject. This parameter contains a string which defines a prefix that you specify. By doing so, the object's outgoing interface is connected and any time an event is fired from the object, you can intercept it within the WSH file. For example, in the ADO connection object, there are a number of events. Sparing the details, WillConnect is called before a connection starts, and Connectcomplete is called after a connection has been started. They can be easily intercepted within the WSH file.

  <Job ID="Test">
<script language=PerlScript>
$conn=$WScript->CreateObject('ADODB.Connection', 'MyWSH_');
$conn->Open('ADOSamples');

if($conn->{State} == 1) {
$WScript->Echo("Connection
  Successful!")
}
else {
$WScript->Echo("Connection
  Failed ...");
}

sub MyWSH_ConnectComplete {
$WScript->Echo("ConnectComplete
  was fired ... ");
}

sub MyWSH_WillConnect {
$WScript->Echo("WillConnect
  was fired ... ");
}
</script>
</Job>

For the same result as above, you can use the ConnectObject-method whose syntax is $WScript->ConnectObject(Object, Prefix);. The method $WScript->DisconnectObject(Object); will disconnect its event handling provided that the object is connected. Some other methods are as follows: $Wscript->Echo(1, 2, 3, n); Print text to the standard output defined by WSH. Separating the arguments cause only a space to separate the items in a desktop environment and a newline to separate the items in a command-line scenario.

$WScript->GetObject(Pathname [,ProgID] [,Prefix]);

Retrieves an Automation object from a file or an object specified by the strProgID parameter.

$WScript->Quit([$int_errorcode]);

Quit and process and optionally provide an integer which represents an error code.

$WScript->Sleep($int_milliseconds);

Places the script process into an inactive state for the number of milliseconds specified and then continues execution.

And its properties are:

$WScript->{Application};

Provides the IDispatch interface on the WScript object

$WScript->{Arguments};

Returns a pointer to the WshArguments collection or identifies arguments for the shortcut to the collection.

$WScript->{Fullname};

Returns a string containing the full path to the host executable file or shortcut object.

$WScript->{Name};

Returns a string containing the friendly name of the WScript object.

$WScript->{Path};

Provides a string containing the name of the directory where WScript.exe or CScript.exe resides.

$WScript->{Scriptfullname};

Provides the full path to the script currently being run.

$WScript->{Scriptname};

Provides the file name of the script currently being run.

$WScript->{StdError};

Exposes the write-only error output stream for the current script. Only applicable with CScript command-line WSH files.

$WScript->{StdIn};

Exposes the read-only input stream for the current script. CScript only.

WScript->{StdOut};

Exposes the write-only output stream for the current script. CScript only.

$WScript->{Version};

Returns the version of Microsoft Windows Script Host.

On a final note, if you are using Cscript.exe and passing arguments to the file, you can read the arguments as follows:

<Job ID="args">
<script language=PerlScript>
    $arg = $WScript->{Arguments};

    $countArgs = $arg->{Count};

    for($i=0; $i<$countArgs; $i++) {
        $WScript->Echo($arg->Item($i));
    }
</script>
</job>

The WShShell Object

The WshShell object must be instantiated by the WScript object.

$WshShell = $WScript->CreateObject("WScript.Shell")

An interesting method of the WshShell object is the ability to activate an application window and putting it in focus. This is done by calling AppActivate either with the title in the title bar of the running application window as a parameter or by using the task ID as a parameter.

  <Job Id="WshShell">
<script language=PerlScript>
$WshShell = $WScript->CreateObject("WScript.Shell");
$WshShell->Run("notepad");
$WshShell->AppActivate("Untitled -
  Notepad");

my $message = "Hello from PerlScript!\n";

for($i=0; $i < length($message); $i++) {
$char = substr($message, $i,
  1);
$WScript->Sleep(100);
$WshShell->SendKeys($char);
}
</script>
</job>

The SendKeys-method simply sends keystrokes to the active windows.

The Run method is a little more flexible.

$WshShell->Run(Command, [WindowStyle], [WaitOnReturn]);

The WindowStyle can be an integer between 0 through 10, and WaitOnReturn is a boolean value or 1 (TRUE) or 0 (FALSE). FALSE is the default value it means that an immeditate return to script execution contrary to waiting for the process to end is preferable. It also returns an error code of zero while TRUE returns any error code generated by the active application.

Creating Shortcuts

In addition, you can create shortcuts. Either you create a dekstop shortcut or a URL shortcul. The method call CreateShortcut($path_or_url) returns an object reference to a WshShortcut-object. Keep in mind that a dekstop shortcut has tbe extension .lnk and an URL shortcul has the file extension .url. In the latter case, a WshURLShortcut object is returned.

With the WshShortcut-object, one method exists, so it is mainly properties regarding the shortcut that you need to set. The Description-property contains a string describing the shortcut, Fullname returns the full path to the host executable, Hotkey allows for combinations such as "ALT+CTRL+X" as hotkeys for shortcuts on the Windows dekstop or windows startmenu, IconLocation is a property that you set to "Path, index" to provide the Icon location of the shortcut. In addition, use the TargetPath-property to set the path to the executable file pointed to by the shortcut, WindowStyle can be set to either 1, 3, or 7 for the shortcut object, and WorkingDirectory defines the directory in which the shortcut should start. If you are shortcutting a URL, you have only the Fullname and TargetPath properties where the latter one is a URL. All shortcut objects are final when you call the Save method.

Special Folders

The WshShell object can also return a WshSpecialFolders object which contains paths to shell folders such as the desktop, start menu, and personal documents.

<Job Id="SpecialFolder">
<script language=PerlScript>
    $WshShell = $WScript->CreateObject("WScript.Shell");
    $numFolders = $WshShell->SpecialFolders->{Count};
    $title = "PerlScript & WSH Example";
    $style = 1;

    for($i=0; $i<$numFolders; $i++) {
        $ok_or_cancel = $WshShell->Popup(
            $WshShell->SpecialFolders($i),
            undef,
            $title,
            $style);

        exit if ($ok_or_cancel == 2);
    }
</script>
</job>

Working With the Registry

The WshShell object provides functionality for working with the registry. The three methods for this are: RegRead, RegWrite, and RegDelete. Simply provide either method with a string such as the short form HKCU\ScriptEngine\Val or longer variant HKEY_CURRENT_USER\ScrtipeEngine\Val. Notice that a key is returned if the last character is a backslash, and a value is returned if no backslash is at the end. The RegRead method supports the following data types:

  • REG_SZ
  • REG_EXPAND_SZ
  • REG_DWORD
  • REG_BINARY
  • REG_MULTI_SZ

RegWrite requires a few extra parameters:

$WshShell->RegWrite(Name, Value [,Type]);

The name is a fully qualified string such as HKCU\ScriptEngine\Val where the same rules apply for key and value as previously mentioned. The Type-parameter is optional, but if used, it must be one of the following data types:

  • REG_SZ
  • REG_EXPAND_SZ
  • REG_DWORD
  • REG_BINARY

Miscellanous

Expands the requested environment variable from the running process:

$WshShell->ExpandEnvironmentStrings($string);

In addition, log an event in the NT event log or WSH.log (Windows 9x) file using:

$WshShell->LogEvent(Type, Message [,Target]);

Target is the name of the system on NT, thus only applicable on NT. The Type of event is either

  • 0 (SUCCESS)
  • 1 (ERROR)
  • 2 (WARNING)
  • 4 (INFORMATION),
  • 8 (AUDIT_SUCCESS)
  • 16 (AUDIT_FAILURE)

This method returns a boolean value indicating success or failure. Another method is Popup, which sends a Windows messagebox up on the screen.

$retval = $WshShell->Popup(Text, [SecondsWait], [Title], [Type]);

The method allows you to define the text to pop up, alternatively seconds to wait before closing window, the title of the window, and lastly the type of buttons available in the window. They can be:

  • 0 (Ok)
  • 1 (Ok and Cancel)
  • 2 (Abort, Retry, and Ignore)
  • 3 (Yes, No, and Cancel)
  • 4 (Yes and No)
  • 5 (Retry and Cancel)

The value that you choose can also be combined with an icon:

  • 16 (Stop Mark)
  • 32 (Question Mark)
  • 48 (Exclamation Mark)
  • 64 (Information Mark)

The return values returned to $retval indicates which button was pressed. The value will be one of the following:

  • 1 (OK)
  • 2 (Cancel)
  • 3 (Abort)
  • 4 (Retry)
  • 5 (Ignore)
  • 6 (Yes)
  • 7 (No)

The WshNetwork Object

The WshNetwork object exposes some network functionality. To begin:

$WshNetwork->AddPrinterConnection($LocalName, $RemoteName[,$UpdateProfile][,$User][,$Password]);

User and password are two parameters with given meaning. Localname and Remotename are the names of the printer resource. Set UpdateProfile to TRUE for storing this mapping in the user profile. Next, AddWindowsPrinterConnection() adds a printer just as you would add one using the control panel. On Windows NT/2000 the only parameter you need to call this method with is the path to the printer while windows 9x requires you to specify the driver to use, and optionally specify which port to which it is connected. In the last event, the syntax is:

$WshNetwork->AddWindowsPrinterConnection($PrinterPath, $DriverName[,$Port])

As easily as adding a printer, you can remove a printer. Simply do

$WshNetwork->RemovePrinterConnection($Name, [$Force], [$UpdateProfile]);

If you set $Force to TRUE (1), it will remove the connection regardless if it is being used, and setting $UpdateProfile to true will remove any user profile mapping.

If you're happy with your printers, you can set one of the printer as your default printer by a quick call:

$WshNetwork->SetDefaultPrinter($PrinterName);

To return a collection of all your printers, call:

$Printers = $WshNetwork->EnumPrinterConnections();

Then use the Count-property to retrieve the number of items in the $Printers collection object.

When you want to map a drive to a network share, you can use the MapNetworkDrive method.

$WshNetwork->MapNetworkDrive($LocalName, $RemoteName, [$UpdateProfile], [$User], [$Password]);

For example:

$WshNetwork->MapNetworkDrive('C:\', '\\MyComputerServer\\ShareHere);

Remove a network drive using the now familiar syntax

$WshNetwork->RemoveNetworkDrive($Name, [$Force], [$UpdateProfile])

or enumerate the network drives as:

$Drives = $WshNetwork->EnumNetworkDrive();

The three properties of the network object are ComputerName, UserName, and UserDomain.

XML Element Reference

Like Windows Script Components, the Windows Script Host has a set of XML elements that can be deployed. For a basic understanding of how they are used, please refer to the section about Windows Script Components.

The Job Element

The Job element is used to define the beginning and the end of the components. It encapsulates all other tags. Should your WSH file contain more than one job, encapsulate them within a <package> element. When declaring jobs, the ID attribute is optional.

Syntax:

<Job [id=JobID]>

For example:

<package>
    <Job id="PrintOutput">
    </Job>
    <Job id="ReadInput">
    </Job>
</package>

You can also set a boolean value of true (1) or false (0) for error checking or debugging by using the additional tag

<? job error="true" debug="true" ?>

The Script Element

The script element lets you define the scripting language to use, and then with its closing-tag functions as delimiters for the script code.

Syntax:

<script language="languageName"> code </script>

For example.

<?XML version="1.0"?>
<job>
...
<script language="PerlScriptt">
<![CDATA[
    sub ReturnValue {
    #
    # Perl code here
    #
    }
]]>
</script>
</job>

The Resource Element

The resource element is a placeholder for strings or numeric data that should be separate from the script commands yet may be used within the script.

Syntax:

<resource id="resourceID"> text or number to represent resource goes here </resource>

You use the getResource(resourceID) to retrieve the contents of the resource specified in the resourceID parameter.

The Reference Element

You can import external type libraries by using the reference element. By importing a type library, you will be able to naturally access the constants that belongs to it, too.

Syntax:

<reference [object="progID" | guid="typelibGUID"] [version="versionNo"] />

AUTHOR AND COPYRIGHT

Written document copyright (c) 2000 Tobias Martinsson. All rights reserved.

When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work may be distributed only under the terms of Perl's Artistic License. Any distribution of this file or derivatives thereof outside of that package require that special arrangements be made with copyright holder.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

Windows Script Host is copyright (c) 1991-2000 Microsoft Corporation. All Rights Reserved.

Rough Guide to Windows Script Host


Windows Script Components (WSC)

  • Windows Script Components (WSC)
    • The Component Object Model
    • A Standard And An Implementation
    • The Parts of A Component
      • COM Interface
      • COM Class
      • COM Object
      • COM Component
    • Scripting Languages And Automation
      • The Dispatch Interface
    • Creating Windows Script Components
      • Ten Easy Steps
        • Implementing the PerlScript
        • Registering the Component
      • WSC with Properties and Notification
    • XML Element Reference
      • <component>
      • <registration>
      • <public>
        • <property>
        • <method>
        • <event>
      • <implements>
      • <script>
      • <object>
      • <resource>
      • <reference>
      • <comment>
  • AUTHOR AND COPYRIGHT

Windows Script Components (WSC)

Windows Script Components (WSC), formerly known as Scriplets, is a technology for developing powerful COM components in an easy fashion. WSC's can be authored in any scripting language that has implemented the ActiveX Scripting Interfaces, which means that units of PerlScript code can be encapsulated as Windows Script Components.

Be warned, reader, a lengthy introduction to the Component Object Model (COM) stretches until the topic of Windows Script Components. Please move directly to the topic of Windows Script Components if you feel that you understand the COM; the COM is essential to WSC, thus it is necessary to cover the fundamentals of the COM.

The Component Object Model

The Component Object Model (COM) is a language-independent and object-oriented programming model. It is not, however, a programming language, and it does not demand that a new style of programming be learned. It is a binary standard that enables software to be implemented as units called components. The component can be authored in any programming language or scripting language provided that the language supports the standard defined by the COM. After the binary unit has been built, it can communicate with other units that were produced in any other language, on the same machine or on remote machines provided that the units were written as COM components.

As many see it, the Component Object Model is elegant and powerful. The basic yet ingenious programming model provides the foundation for application-development. The power resides in that everything built on the same foundation can communicate with each other without any restrictions such as programming languages or platforms. When developing an application devoted to COM, components should encapsulate every functionality that the application requires. A task performed by the application would be executed by a component, and these components would be reused in other and future applications. For example, a Perl component can contain the process of sending an email or performing a series of regular expressions on text. The component can then be used to provide functionality for an Active Server Pages application or a Windows desktop application.

In summary, although the language in which a component is generated may vary from component to component, a binary standard overcomes the limitation of programming in different languages. It does not care about anything else but the binary form of the machine code that the once source code was turned into and the fact that is implemented into COM. In this sense, the component is not a regular script or executable, but a black box that performs one task and returns the projected result. Multiple languages can be used for one application because COM provides a binary standard. A binary standard also results in platform-independence provided that multiple platforms support COM. Units of code that are used in COM are known as components, and on Windows a component is normally file with the extension .dll; however, there are offshoots such as Windows Script Components, which have the extension .wsc. The purpose of the component is to perform the one task that it has been programmed for, and through COM, it can communicate with other components, languages, and platforms.

A Standard And An Implementation

COM is both a specification and an implementation. And being both a specification and an implementation, the COM defines a standard for how the components are created and how they communicate - namely as objects. As a result, the specification solves the implementation issues of the following key issues:

  • The calling of a component
  • The locating of a component
  • The identification of a component
  • The creation of a component

Although the parts above are involved in the specification of how to implement components, the programmer normally does not have to worry much about them. A software development tool that holds high class will create a skeleton for a component, and leave it up to the programmer only to plug in the code in the right places. Thanks to this, the code itself can be developed, debugged, and experimented with as usual. And then when the code is finished, it is placed in the skeleton, the right buttons are clicked, and the component pops out.

The Parts of A Component

When wondering what makes up a component, recall that COM is an object-oriented programming model that requires every component to be implemented as an object, so from this we know that we will be talking about classes, methods, properties, and such entities that belong in an object-oriented programming model. However, let’s start at the bottom level and move our way up from interfaces, to classes, and to objects.

COM Interface

When the component is implemented, it exposes its features through one or more interfaces. The interface is a specification of a collection of methods and properties that are related to each other, so when a component is called, it must be called through one of its interfaces. In general, this means that an interface relates to an operation such as verifying a credit-card number or sending an email. Because the component may expose several interfaces and the method-calls pass by way of the correct interface, the interface that is called must be identifiable. It is a fact that names easily clash, and especially with a high pace of component development, so another solution is provided. An interface uses a globally unique identifier (GUID) which is a 128-bit integer. And through the GUID, the interface is identified to the COM.

COM Class

Next, the COM class implements, or maybe better 'inherits', one or more COM interfaces. A Class ID (CLSID) uniquely identifies the COM class, and while the interfaces are at the base level of the COM architecture, the COM class is on top of the interfaces - one step close to the application. The main purpose of the COM class is to generate, or instantiate, the COM object that represents the functionality of the unit of code.

COM Object

As previously mentioned, this part of COM simply is the instance of a COM class, or the entity from which all the features of the COM class are accessed.

COM Component

In the midst of everything, where does the component fit into the picture? It can be easily summarized as that the component is used to include a COM class by identifying it by the CLSID, create an instance of the COM class as the COM object, and then let the application make use if the COM object on the machine.

Scripting Languages and Automation

Automation, formerly OLE automation, makes it easier for the masses to access COM object servers such as components. In terms of a scripting language, the only way for a COM component to make its features available is through Automation. Automation is one level higher up than COM, in other words one step closer to the application, and it is the technology that lets software packages such as Microsoft Office expose its functionality in an object-model for scripting languages that support Automation.

In the same manner as large applications like MS Office are exposed, smaller COM components are made available to a scripting language through Automation, as well. Without it, the scripting language would necessarily have to know all the interfaces of an object that it wants to use before calling it - too much information to build into a language.

Instead of bloating a language with junk, COM defines the standard for accessing COM object servers: Automation. In turn, Automation makes sure that a standard interface that allows, in our case, script-access to the component is always available for object-access. This standard interface used in Automation is called a dispatch interface, dispinterface, or automation interface.

The Dispatch Interface

A dispatch interface is somewhat different than the standard COM interface. Methods are associated with dispatch IDs (dispids), and methods have been provided for reading and writing the values of properties - the access to the data members in the underlying data structure.

The standard dispatch interface for automation is called IDispatch. Through IDispatch, a component can expose as much as it wants to expose. Then in order for Perl to gain access to components, the interpreter needs to support an object-oriented programming model, have the ability to call methods through IDispatch, know how to return errors, and be able to destroy objects.

A method that belongs to an interface of a COM component is retrieved by the dispatch interface and in Perl this can occur by what is known as late binding. A dispatch method called GetIDsOfNames is called with the name and the parameters of the method of the COM interface that is called. The dispatch ID of the method is returned. Next, the Invoke-method of IDispatch is called with all the processed information returned from GetIDsOfNames, and from that call the result is returned in an output parameter. This method is called late binding, and there are two things to notice about it:

  • There is an overhead involved in the Automation discussed
  • All data types that are sent as parameters through Invoke to the method of an interface must be passed as Variants or converted into Variants.

When not using late binding, the application already is aware of all the dispatch IDs and does not call GetIDsOfNames at all. This is called early binding since the information needed for using the components have been built into the application and are used at run-time.

Perl uses late binding, and the process of late binding is simple. First, a moniker is required, which is a name that uniquely identifies the COM object. The moniker is then used to locate the object, which next is either in running state or put into running state. When in running state, the server application can access the interfaces of the COM object, and when that is completed, an interface pointer is returned to it. The dispatch interface that makes COM objects accessible to a scripting language is implemented as a COM interface that uses IDispatch. And the IDispatch functions of this interface only calls the methods that are laid out in the COM interface, and these two interfaces are called dual interfaces because an application that knows only early-binding can access it while another language that knows only late-binding can access it, as well.

Although the implementation of all of the above is hidden to Perl, there are some things to know. In most cases, Automation will accept and convert scalar data into the correct variant-type. However, it might be necessary to specify the type of data; so to solve this issue, you would convert Perl data types to the variants used.

VT_EMPTY | No Value
VT_NULL | Null Value
VT_I2 | 2-byte integer
VT_I4 | 4-byte integer
VT_R4 | 4-byte real value
VT_R8 | 8-byte real value
VT_CY | Currency
VT_DATE | Date
VT_BSTR | Binary string
VT_DISPATCH | Automation object
VT_ERROR | Error code
VT_BOOL | Boolean value
VT_VARIANT | Variant
VT_UNKNOWN | IUknown Pointer
VT_UI1 | Unsigned 1-byte character
VT_BYREF | Describes the data as passed by reference
VT_ARRAY | An OLE Safearray

In Perl, Automation and creation of Automation objects is provided by the Win32::OLE module, Furthermore, Variant data types can be converted by the Variant() method or the OLE module although Perl seamlessly takes care of most of the conversion needed.

Creating Windows Script Component's

When it comes to writing a WSC, it is a surprisingly quick and easy process. In fact, anybody who has written an ASP page with some script commands and HTML will have completed a WSC in less than five minutes. And although .wsc files are Extensible Markup Language (XML) files, no previous experience with XML is necessary in order to build a successful component.

Ten Easy Steps

In order to create a WSC, you can use the Windows Script Component Wizard. The wizard will produce a valid skeleton for your WSC, and all you will have to do is enter your PerlScript. Let's create a simple WSC that can be instantiated within a script and holds the basic functionality of being passed a string and retuns the reversed string, so follow me on these steps.

  • Open the Windows Script Component Wizard
  • Enter "Easy" in the component name-field; progID automatically becomes Easy.WSC, which is fine.
  • Click "Next"
  • Set the "Language"-option for the component to "Other" and enter "PerlScript"
  • Click "Next"
  • Click "Next" in the "Properties" window
  • Enter "SayHello" as a method with no parameters
  • Click "Next"
  • Click "Next" in the "Events" windows
  • Click "Finish"

Implementing the PerlScript

Following the simple steps above will create a nice skeleton to hold your code. With the exception for the classid, which is unique each time one is generated, it will look as illustrated.

<?xml version="1.0"?>
<component>

<registration>
    description="Easy"
    progid="Easy.WSC"
    version="1.00"
    classid="{74bb1ba9-2e69-4ad6-b02c-c52f3cbe153b}"
</registration>

<public>
    <method name="SayHello">
    </method>
</public>

<script language="PerlScript">
<![CDATA[

]]>
</script>
</component>

As seen above, you have a Window Script Component that is an XML file. The first declaration of the WSC enables strict XML. In that mode, the elements and attributes are case-sensitive, and attribute values must be enclosed within single quotes or double quotes. You may omit the XML declaration on top of the document and it will not be compiled as strictly, but in these examples, we will stick with XML conformity and leave the declaration in each document. Note: XML elements is that they, like HTML, have tag pairs like "<registration>" and "</registration>".

Secondly, you have a component element. This element is used to enclose each component. You will place one at the beginning, and one at the end. As an exception to the rule, there is an element that has a higher priority than the component, and that element must be used whenever you keep more than one component in your WSC file. Is is the package element. It will as a single element enclose all components; however, as mentioned, it is not required when you have one component within the file.

Next, the registration element contains the information about your component such as the progid, classid, description, and version number. Description is a string in which you can write a short abstract summary the funcitonality of your component. The progid is used by the program which creates an instance of your component, and the version number should be incremented if you release a new version of your component. The version number can also be appeneded to the progid as as Easy.WSC.1.00 when creating the instance of your component.

After the registration element, the data and functionality that the component expose are defined. The public element will hold properties, methods, and events. We declare a method by the name "SayHello" and then skip on down to the script-elements. As you can tell, there is no source code, so we need to fill that out. In the empty space, enter the following:

sub SayHello {
    my($param) = shift @_;
    return reverse($param);
}

Finally, your script file will look like this:

<?xml version="1.0"?>
<component>

<registration>
    description="Easy"
    progid="Easy.WSC"
    version="1.00"
    classid="{74bb1ba9-2e69-4ad6-b02c-c52f3cbe153b}"
</registration>

<public>
    <method name="SayHello">
    </method>
</public>

<script language="PerlScript">
<![CDATA[
sub SayHello {
    my($param) = shift @_;
    return reverse($param);
}
]]>
</script>
</component>

Registering the Component

Now, it's time to register the component on the system so that it can be used. If we assume that the file is saved as c:\easy.wsc, there are two ways to do this:

  • You can type regsvr32 c:\easy.wsc in the command window.
  • Or you can locate it through Windows Explorer, right-click on the file and then choose "Register".

Either one of the above methods for registering a component should notify you upon success or failure. After registering the component, you can use it from within Active Server Pages by authoring a small script.

<%@Language=PerlScript%>
<%
    $obj = $Server->CreateObject('Easy.WSC');
    $retval = $obj->SayHello("Hello World");
    $Response->Write($retval);
%>

WSC with Properties and Notification

Next, let's look at how to get a few properties included in the component, too. The following example will display how to read and write properties. It also includes comments, and, in addition, a custom subroutine is run when the component is registered and unregistered. What will happen is that when the component has been registered, a message box pops up with the text "Windows Script Component says: First.WSC has been registered!" and a similar tailored message when the component is unregistered by either one of the ways previously shown. So, open up the Windows Script Component wizard, again, and this time enter the read/write property "YourName", and the method "SayHello." The property is a global variable, and it internally is read and written by subroutines that implement the functionality needed for performing the given operation. The property can either use "get" and "set" attributes that point to the mentioned subroutines or there can be separate "get" and "set" elements as in the example. Their values point to internal Perl subroutines that do their thing on the property. It is a simple example, and it is as follows.

<?xml version="1.0"?>
<component>

<registration>
    description="First"
    progid="First.WSC"
    version="1.00"
    classid="{d0ccb637-bd0c-4c90-a4bd-7473f499d35a}">

    <comment> This makes the messagebox pop up on registration and unregistation </comment>

    <script language="PerlScript">
    <![CDATA[
        use Win32;
        sub register {
            Win32::MsgBox('Windows Script Component says: First.WSC has been registered!');
        }
        sub unregister {
            Win32::MsgBox('Windows Script Component says: First.WSC has been unregistered!');
        }
    ]]>
    </script>
</registration>

<comment> The methods and properties to expose to the data consumer </comment>

<public>
    <property name="YourName">
        <get internalName="hiddenGetProperty"/>
        <put internalName="hiddenSetProperty"/>
    </property>

    <method name="SayHello">
    </method>
</public>

<comment> The code that implements the functionality of the component </comment>

<script language="PerlScript">
<![CDATA[
    use vars qw($YourName_Property);

    sub hiddenGetProperty {
        return $YourName_Property;
    }

    sub hiddenSetProperty {
        my $param = shift;
        $YourName_Property = $param;
    }

    sub SayHello {
        return "Hello $YourName_Property!";
    }
]]>
</script>

</component>

XML Element Reference

Windows Script Components use XML to mark up the definition of the component and what is exposed by the component. Listed below are the elements that are valid XML elements for use within WSC components.

The Component Element

The component element is used to define the beginning and the end of the components. It encapsulates all other WSC tags as illustrated.

<component>
.
.
.
</component>

You can also set a boolean value of true (1) or false (0) for error checking or debugging by using <? component error="true" debug="true" ?>

In case your file will contain more than one component, you use a <component id=componentID> element for each, and you are required to then enclose all components within a <package> element.

<package>
<component id="ComponentA">
.
.
.
</component>
<component id="ComponentB">
.
.
.
</component>
</package>

The default value for the component ID is ComponentCoClass, and when you define your own, either to identify the components or for generating a type library, the name must be unique and it must begin with a letter and contain no spaces.

When using more than one component within a package, you can create instances of the other component within the current component by calling the createComponent(componentID) function.

The Registration Element

<registration> contains the necessary information in order to successfully register the component as a COM component, and it has two ways of writing.

Syntax:

<registration
    progid="progID"
    classid="GUID"
    description="description"
    version="version"
    [remotable=remoteFlag]
/>

or

<registration
    progid="progID"
    classid="GUID"
    description="description"
    version="version"
    [remotable=remoteFlag]
>
<script>
    (registration and unregistration script)
</script>
</registration>

Most of the element attributes have been discussed in the introduction to the COM. However, remotable, which is optional, specifies if the component can be instantiated using DCOM. Its value can be true or false.

The Public Element

The public element implements Automation, formerly known as OLE Automation, and within the public elements you define the properties, methods, and events that the component exposes after it has been registered. This is done using the property, method, and event elements.

<public>
    <property name="myProperty"/>
    <method name="myMethod"/>
    <event name="myEvent"/>
</public>

The Property Element

Property declares a property exposed by the component. Syntax:

<property name="myProperty" [internalName="propertyScalarVariable"] />

The name of the property is what it will be exposed as, which needs to be the same name as the global variable used to represent the proeprty. In contrast, you can set an internalName attribute and run the property under another name within the <script> elements. You may also use the following syntax if you wish to implement the properties as subroutines that calculate the value of the property.

<property name="myProperty" get="getSubroutineNamet" put="putSubroutineName"/>

or

<property name="myProperty">
    <get [internalName="getSubroutineName"] />
    <put [internalName="putSubroutineName"] />
</property>

Put indicates write-permissions while get indicated read-permissions. A combination of the both as seen above indicated read/wrote permissons.

The Method Element

The method elements define the methods that are exposed by the component.

Syntax:

<method name="methodName" internalName="subroutineName" dispid=dispatchID />

or

  <method name="methodName"
  internalName="subroutineName" dispid=dispatchID >
[<parameter name="param"/>]
</method>

The dispatchID is automatically generated unless you specify "0" as a dispatchID, which will result in it being the default method of the component. Parameter elements may belong to the method, if defined.

<parameter name="param"/>

The Event Element

Declare an event that can be fired from within the component.

Syntax:

<event name="name" dispid=dispatchID/>

DispatchID is a numeric value that is generated automatically unless you specify it. From within your script, you use the fireEvent(eventname); method to execute an event.

The Implements Element

The Implements element enables you to include more COM interface handlers within your script.

Syntax:

<implements type="COMHandlerName" [id="internalName"] [default=fAssumed] >
    Information related to the COMHandler goes here
</implements>

COMHandlerName is the name of an interface handler that you wish to implement, and internalName is the name to which you want to reference the COMHandler. This is useful to avoid naming conflicts because the components exposed data is available in the global namespace. The fAssumed flag is a boolean value used to define if internalName is assumed in scripts, which is the default setting.

The Windows Script Components run-time (scrobj.dll) implement handlers for Automation and ASP, and also handlers for accesing the DHTML object model in the page.

<component>
<registration progid="SimpleASP.WSC"/>

<public>
    <method name="TestWrite"/>
</public>

<implements type="ASP"/>
<script language="PerlScript">
<![CDATA[
    sub TestWrite {
        Response.Write("Hello World, says ASP!")
    }
]]>
</script>
</component>

The Script Element

The script element lets you define the scripting language to use, and then with its closing-tag functions as delimiters for the script code.

Syntax:

<script language="languageName"> code </script>

For example.

<?XML version="1.0"?>
<component>
...
<script language="PerlScriptt">
<![CDATA[
    sub ReturnValue {
    #
    # Perl code here
    #
    }
]]>
</script>
</component>

The Object Element

The object element enables you to create an instance of a COM object that you want to use within your Windows Script Component.

Syntax:

<object id="objectID" [classid="classid:GUID" | progid="progID"]/>

The objectID is the name by which you want to reference the object within your script, and you can use either the progID or classID to locate the component. For example, how to create an instance using the COM components progID:

  <?XML version="1.0"?>
<component>
<object id="conn" progid="ADODB.Connection.2.5">
<script language="PerlScript">
<![CDATA[
sub OpenConn {
my($status);

$conn->Open('ADOSamples');

if($conn->{State} ==
  adStateOpen) {
$status
  = "Connection was a success";
}
else {
$status
  = "Connection failed because ";
$status
  .= $conn->Errors(0)->{Description};
}

$conn->Close();

return $status;
}
]]>
</script>
</component>

The Resource Element

The resource element is a placeholder for strings or numeric data that should be separate from the script commands yet may be used within the script.

Syntax:

<resource id="resourceID"> text or number to represent resource goes here </resource>

You use the getResource(resourceID) to retrieve the contents of the resource specified in the resourceID parameter.

The Reference Element

You can import external type libraries into your component by using the reference element. By importing a type library into your component, you will be able to naturally access the constants that belongs to it, too.

Syntax:

<reference [object="progID" | guid="typelibGUID"] [version="versionNo"] />

For example, you can use an ActiveX Data Object within your component.

  <?XML version="1.0"?>
<component>
<reference object="ADODB.Connection.2.5"/>
<registration progid="SimpleADO.WSC"/>
<public>
<method name="OpenConn"/>
</public>

<script language="PerlScript">
<![CDATA[
sub OpenConn {
my($status);

$conn = new
  Win32::OLE("ADODB.Connection");
$conn->Open("ADOSamples');

if($conn->{State} ==
  adStateOpen) {
$status
  = "Connection was a success";
}
else {
$status
  = "Connection failed because ";
$status
  .= $conn->Errors(0)->{Description};
}

$conn->Close();

return $status;
}
]]>
</script>
</component>

The Comment Element

The Comment element encloses descriptive strings that are used to describe the on-goings in the code and the strings are ignored by the language parser when preparing the code to execute.

<comment>
    Author: John Doe
    Description: This WSC component is used to output a Binary Large Object (BLOB)
    from an SQL Server database . . .
</comment>

AUTHOR AND COPYRIGHT

Copyright (c) 2000 Tobias Martinsson. All Rights Reserved.

When included as part of the Standard Version of Perl, or as part of its complete documentation whether printed or otherwise, this work may be distributed only under the terms of Perl's Artistic License. Any distribution of this file or derivatives thereof outside of that package require that special arrangements be made with copyright holder.

Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.

Windows Script Components is copyright (c) 1991-2000 Microsoft Corporation. All rights reserved.

Windows Script Components


Perl 5.8.8 Documentation Generated on Fri Aug 3 16:27:22 2007 with HelpDocUpdate.pl (Version 0.2.0) Chapters: core mods pragmas ap -- -- -- -- Source code of HelpDocUpdate.pl -- -- -- -- # HelpDocUpdate.pl # # PURPOSE # # Generate a .chm help file from ActivePerl's HTML Documentation # # REQUIREMENTS # # Active Perl 5.8 and File::Slurp module # MS HTML Help WorkShop # # USAGE # # usage: HelpDocUpdate.pl [options] # or: HelpDocUpdate.pl [options] default # # Options: # # --no-strip Do not remove # and


ActivePerl Community License v2.1

Preamble:

This license establishes the terms under which the Package may be
copied, modified, distributed and/or redistributed.  The intent is
that ActiveState Software Inc. ("ActiveState") maintains control over
the development and distribution of the Package, while allowing the
users of the Package to use the Package in a variety of ways. You are
always permitted to make arrangements wholly outside of this license
directly with ActiveState.  If the terms of this license do not permit
the full use that you propose to make of the Package or if you require
clarification regarding your particular intended use of the Package,
You should contact sales@activestate.com in order to seek
clarification or to request a different licensing arrangement.

Definitions:

"ActiveState" refers to ActiveState Software Inc., the copyright
holder of the Package.

"Package" refers to those files, including, but not limited to, source
code, binary executables, images, and scripts, which are distributed
by ActiveState, and derivatives of that collection and/or those files.

"You" and "your" means any person who copies, distributes, or modifies
the Package.

1. You may use this Package for commercial or non-commercial purposes
   without charge.

2. You may make and give away verbatim copies of this Package for
   personal use, or for use within your organization, provided that
   you duplicate all of the original copyright notices and associated
   disclaimers. You may not distribute copies of this Package, or
   copies of packages derived from this Package, or cause by Your
   actions copies of this Package to be distributed, to others outside
   your organization without specific prior written permission from
   ActiveState (although you are encouraged to direct them to sources
   from which they may obtain it for themselves).

3. You may apply bug fixes, portability fixes, and other modifications
   made available from ActiveState. A Package modified in such a way
   shall still be covered by the terms of this license.

4. The license also allows You to redistribute parts of the Package as
   part of an application generated by wrapping tools such as PAR,
   PerlApp or Perl2Exe.  However, this License does not allow You to
   (a) redistribute the Package as a whole, (b) use its parts to
   create a language distribution, or (c) redistribute the PerlScript,
   Perl for ISAPI or PerlEx components with Your application.

5. ActiveState's name and trademarks may not be used to endorse or
   promote packages derived from this Package without specific prior
   written permission from ActiveState.

6. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
   WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES
   OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.


dbiprof - command-line client for DBI::ProfileData

  • OPTIONS
  • AUTHOR
  • COPYRIGHT AND LICENSE
  • SEE ALSO

NAME

dbiprof - command-line client for DBI::ProfileData

SYNOPSIS

See a report of the ten queries with the longest total runtime in the profile dump file prof1.out:

 dbiprof prof1.out

See the top 10 most frequently run queries in the profile file dbi.prof (the default):

  dbiprof --sort count

See the same report with 15 entries:

  dbiprof --sort count --number 15

DESCRIPTION

This tool is a command-line client for the DBI::ProfileData. It allows you to analyze the profile data file produced by DBI::ProfileDumper and produce various useful reports.

OPTIONS

This program accepts the following options:

--number N

Produce this many items in the report. Defaults to 10. If set to "all" then all results are shown.

--sort field

Sort results by the given field. Sorting by multiple fields isn't currently supported (patches welcome). The available sort fields are:

total

Sorts by total time run time across all runs. This is the default sort.

longest

Sorts by the longest single run.

count

Sorts by total number of runs.

first

Sorts by the time taken in the first run.

shortest

Sorts by the shortest single run.

key1

Sorts by the value of the first element in the Path, which should be numeric. You can also sort by key2 and key3.

--reverse

Reverses the selected sort. For example, to see a report of the shortest overall time:

  dbiprof --sort total --reverse
--match keyN=value

Consider only items where the specified key matches the given value. Keys are numbered from 1. For example, let's say you used a DBI::Profile Path of:

  [ DBIprofile_Statement, DBIprofile_Methodname ]

And called dbiprof as in:

  dbiprof --match key2=execute

Your report would only show execute queries, leaving out prepares, fetches, etc.

If the value given starts and ends with slashes (/) then it will be treated as a regular expression. For example, to only include SELECT queries where key1 is the statement:

  dbiprof --match key1=/^SELECT/

By default the match expression is matched case-insensitively, but this can be changed with the --case-sensitive option.

--exclude keyN=value

Remove items for where the specified key matches the given value. For example, to exclude all prepare entries where key2 is the method name:

  dbiprof --exclude key2=prepare

Like --match, If the value given starts and ends with slashes (/) then it will be treated as a regular expression. For example, to exclude UPDATE queries where key1 is the statement:

  dbiprof --match key1=/^UPDATE/

By default the exclude expression is matched case-insensitively, but this can be changed with the --case-sensitive option.

--case-sensitive

Using this option causes --match and --exclude to work case-sensitively. Defaults to off.

--delete

Sets the DeleteFiles option to the DBI::ProfileData manpage which causes the files to be deleted after reading. See the DBI::ProfileData manpage for more details.

--dumpnodes

Print the list of nodes in the form of a perl data structure. Use the -sort option if you want the list sorted.

--version

Print the dbiprof version number and exit.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

SEE ALSO

DBI::ProfileDumper, DBI::Profile, DBI.


lwp-mirror - Simple mirror utility

  • SEE ALSO
  • AUTHOR

NAME

lwp-mirror - Simple mirror utility

SYNOPSIS

 lwp-mirror [-v] [-t timeout] <url> <local file>

DESCRIPTION

This program can be used to mirror a document from a WWW server. The document is only transfered if the remote copy is newer than the local copy. If the local copy is newer nothing happens.

Use the -v option to print the version number of this program.

The timeout value specified with the -t option. The timeout value is the time that the program will wait for response from the remote server before it fails. The default unit for the timeout value is seconds. You might append "m" or "h" to the timeout value to make it minutes or hours, respectively.

Because this program is implemented using the LWP library, it only supports the protocols that LWP supports.

SEE ALSO

the lwp-request manpage, the LWP manpage

AUTHOR

Gisle Aas <gisle@aas.no>


lwp-request - Simple command line user agent

  • SEE ALSO
  • COPYRIGHT
  • AUTHOR

NAME

lwp-request - Simple command line user agent

SYNOPSIS

 lwp-request [-aeEdvhx] [-m method] [-b <base URL>] [-t <timeout>]
             [-i <if-modified-since>] [-c <content-type>] [-C <credentials>]
             [-p <proxy-url>] [-o <format>] <url>...

DESCRIPTION

This program can be used to send requests to WWW servers and your local file system. The request content for POST and PUT methods is read from stdin. The content of the response is printed on stdout. Error messages are printed on stderr. The program returns a status value indicating the number of URLs that failed.

The options are:

-m <method>

Set which method to use for the request. If this option is not used, then the method is derived from the name of the program.

-f

Force request through, even if the program believes that the method is illegal. The server might reject the request eventually.

-b <uri>

This URI will be used as the base URI for resolving all relative URIs given as argument.

-t <timeout>

Set the timeout value for the requests. The timeout is the amount of time that the program will wait for a response from the remote server before it fails. The default unit for the timeout value is seconds. You might append "m" or "h" to the timeout value to make it minutes or hours, respectively. The default timeout is '3m', i.e. 3 minutes.

-i <time>

Set the If-Modified-Since header in the request. If time is the name of a file, use the modification timestamp for this file. If time is not a file, it is parsed as a literal date. Take a look at the HTTP::Date manpage for recognized formats.

-c <content-type>

Set the Content-Type for the request. This option is only allowed for requests that take a content, i.e. POST and PUT. You can force methods to take content by using the -f option together with -c. The default Content-Type for POST is application/x-www-form-urlencoded. The default Content-type for the others is text/plain.

-p <proxy-url>

Set the proxy to be used for the requests. The program also loads proxy settings from the environment. You can disable this with the -P option.

-H <header>

Send this HTTP header with each request. You can specify several, e.g.:

    lwp-request \
        -H 'Referer: http://other.url/' \
        -H 'Host: somehost' \
        http://this.url/
-C <username>:<password>

Provide credentials for documents that are protected by Basic Authentication. If the document is protected and you did not specify the username and password with this option, then you will be prompted to provide these values.

The following options controls what is displayed by the program:

-u

Print request method and absolute URL as requests are made.

-U

Print request headers in addition to request method and absolute URL.

-s

Print response status code. This option is always on for HEAD requests.

-S

Print response status chain. This shows redirect and authorization requests that are handled by the library.

-e

Print response headers. This option is always on for HEAD requests.

-d

Do not print the content of the response.

-o <format>

Process HTML content in various ways before printing it. If the content type of the response is not HTML, then this option has no effect. The legal format values are; text, ps, links, html and dump.

If you specify the text format then the HTML will be formatted as plain latin1 text. If you specify the ps format then it will be formatted as Postscript.

The links format will output all links found in the HTML document. Relative links will be expanded to absolute ones.

The html format will reformat the HTML code and the dump format will just dump the HTML syntax tree.

Note that the HTML-Tree distribution needs to be installed for this option to work. In addition the HTML-Format distribution needs to be installed for -o text or -o ps to work.

-v

Print the version number of the program and quit.

-h

Print usage message and quit.

-x

Extra debugging output.

-a

Set text(ascii) mode for content input and output. If this option is not used, content input and output is done in binary mode.

Because this program is implemented using the LWP library, it will only support the protocols that LWP supports.

SEE ALSO

the lwp-mirror manpage, the LWP manpage

COPYRIGHT

Copyright 1995-1999 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Gisle Aas <gisle@aas.no>


ppm - Perl Package Manager, version 4

  • FILES
  • ENVIRONMENT
  • WHAT'S NEW IN VERSION 4
  • SEE ALSO
  • COPYRIGHT

NAME

ppm - Perl Package Manager, version 4

SYNOPSIS

Invoke the graphical user interface:

    ppm
    ppm gui

Install, upgrade and remove packages:

    ppm install [--area <area>] [--force] <pkg>
    ppm install [--area <area>] [--force] <module>
    ppm install [--area <area>] <url>
    ppm install [--area <area>] <file>.ppd
    ppm install [--area <area>] <num>
    ppm upgrade [--install]
    ppm upgrade <pkg>
    ppm upgrade <module>
    ppm remove [--area <area>] [--force] <pkg>

Manage and search install areas:

    ppm area list [--csv] [--no-header]
    ppm area sync
    ppm list [--fields <fieldnames>] [--csv]
    ppm list <area> [--fields <fieldnames>] [--csv]
    ppm files <pkg>
    ppm verify [<pkg>]

Manage and search repositories:

    ppm repo list [--csv] [--no-header]
    ppm repo sync [--force] [<num>]
    ppm repo on <num>
    ppm repo off <num>
    ppm repo describe <num>
    ppm repo add <url> [<name>] [--username <user> [--password <passwd>]]
    ppm repo rename <num> <name>
    ppm repo location <num> <url>
    ppm repo suggest
    ppm search <pattern>
    ppm describe <num>
    ppm tree <package>
    ppm tree <num>

Obtain version and copyright information about this program:

    ppm --version
    ppm version

DESCRIPTION

The ppm program is the package manager for ActivePerl. It simplifies the task of locating, installing, upgrading and removing Perl packages.

Invoking ppm without arguments brings up the graphical user interface, but ppm can also be used as a command line tool where the first argument provide the name of the sub-command to invoke. The following sub-commands are recognized:

ppm area init area

Will initialize the given area so that PPM starts tracking the packages it contains.

PPM allows for the addition of new install areas, which is useful for shared ActivePerl installations where the user does not have write permissions for the site and perl areas. New install areas are added by simply setting up new library directories for perl to search, and PPM will set up install areas to match. The easiest way to add library directories for perl is to specify them in the PERL5LIB environment variable, see the perlrun manpage for details. PPM will create etc, bin, html directories as needed when installing packages. If the last segment of the library directory path is lib then the other directories will be created as siblings of the lib directory, otherwise they will be subdirectories.

ppm area list [ --csv [ sep ] ] [ --no-header ]

Lists the available install areas. The list displays the name, number of installed packages and lib directory location for each install area. If that area is read-only, the name appears in parenthesis. You will not be able to install packages or remove packages in these areas. The default install area is marked with a * after its name.

The order of the listed install areas is the order perl uses when searching for modules. Modules installed in earlier areas override modules installed in later ones.

The --csv option selects CSV (comma-separated values) format for the output. The default field separator can be overridden by the argument following --csv.

The --no-header option suppresses column headings.

ppm area sync [ area ... ]

Synchronizes installed packages, including those installed by means other than PPM (e.g. the CPAN shell), with the ppm database. PPM searches the install area(s) for packages, making PPM database entries if they do not already exist, or dropping entries for packages that no longer exist. When used without an area argument, all install areas are synced.

ppm config name [ value ]

Get or set various PPM configuration values.

ppm config list

List all configuration options currently set.

ppm describe num

Shows all properties for a particular package from the last search result.

ppm files pkg

Lists the full path name of the files belonging to the given package, one line per file.

ppm help [ subcommand ]

Prints the documentation for ppm (this file).

ppm install pkg [ --area area ] [ --force ] [ --nodeps ]
ppm install module [ --area area ] [ --force ] [ --nodeps ]
ppm install file.ppd [ --area area ] [ --nodeps ]
ppm install url [ --area area ] [ --nodeps ]
ppm install num [ --area area ] [ --nodeps ]

Install a package and its dependencies.

The argument to ppm install can be the name of a package, the name of a module provided by the package, the file name or the URL of a PPD file, or the associated number for the package returned by the last ppm search command.

If the package or module requested is already installed, PPM installs nothing. The --force option can be used to make PPM install a package even if it's already present. With --force PPM resolves file conflicts during package installation or upgrade by allowing files already installed by other packages to be overwritten and ownership transferred to the new package. This may break the package that originally owned the file.

By default, new packages are installed in the site area, but if the site area is read only, and there are user-defined areas set up, the first user-defined area is used as the default instead. Use the --area option to install the package into an alternative location.

The --nodeps option makes PPM attempt to install the package without resolving any dependencies the package might have.

ppm list [ area ] [ --matching pattern ] [ --csv [ sep ] ] [ --no-header ] [ ---fields fieldlist ]

List installed packages. If the area argument is not provided, list the content of all install areas.

The --matching option limits the output to only include packages matching the given pattern. See ppm search for pattern syntax.

The --csv option selects CSV (comma-separated values) format for the output. The default field separator can be overridden by the argument following --csv.

The --no-header option suppress printing of the column headings.

The --fields argument can be used to select what fields to show. The argument is a comma separated list of the following field names:

name

The package name. This field is always shown, but if specified alone get rid of the decorative box.

version

The version number of the package.

release_date

The release date of the package.

abstract

A one sentence description of the purpose of the package.

author

The package author or maintainer.

area

Where the package is installed.

files

The number of files installed for the package.

size

The combined disk space used for the package.

ppd_uri

The location of the package description file.

ppm log [ --errors ] [ minutes ]

Print entries from the log for the last few minutes. By default print log lines for the last minute. With --errors option suppress warnings, trace and debug events.

ppm query pattern

Alias for ppm list --matching pattern. Provided for PPM version 3 compatibility.

ppm remove [ --area area ] [ --force ] pkg ...

Uninstalls the specified package. If area is provided unininstall from the specified area only. With --force uninstall even if there are other packages that depend on features provided by the given package.

ppm rep ...

Alias for ppm repo. Provided for PPM version 3 compatibility.

ppm repo

Alias for ppm repo list.

ppm repo add url [ name ] [ --username user [ --password password ]

Set up a new repository for PPM to fetch packages from.

ppm repo delete num

Remove repository number num.

ppm repo describe num

Show all properties for repository number num.

ppm repo list [ --csv [ sep ] ] [ --no-header ]

List the repositories that PPM is currently configured to use. Use this to identify which number specifies a particular repository.

The --csv option selects comma-separated values format for the output. The default field separator can be overridden by the argument following --csv.

The --no-header option suppress printing of the column headings.

ppm repo num

Alias for ppm repo describe num.

ppm repo num cmd

Alias for ppm repo cmd num.

ppm repo off num

Disable repository number num for ppm install or ppm search.

ppm repo on num

Enable repository number num if it has been previously disabled with ppm repo off.

ppm repo rename num name

Change name by which the given repo is known.

ppm repo location num url

Change the location of the given repo. This will make PPM forget all cached data from the old repository and try to refetch it from the new location.

ppm repo search ...

Alias for ppm seach.

ppm repo suggest

List some known repositories that can be added with ppm add. PPM needs the PPM-Repositories package to be installed for this option to work. To install it:

  ppm install PPM-Repositories

This package supplies PPM with a list of repositories maintained by third parties (not by ActiveState). For example, to add the theoryx5 repository:

  ppm repo add theory58S
ppm repo sync [ --force ] [ --max-ppd max ] [ num ]

Synchronize local cache of packages found in the enabled repositories. With the --force option, download state from remote repositories even if the local state has not expired yet. If num is provided, only sync the given repository.

PPM will need to download every PPD file for repositories that don't provide a summary file (package.xml). This can be very slow for large repositories. Thus PPM refuses to start the downloads with repositores linking to more that 100 PPD files unless the --max-ppd option provides a higher limit.

ppm search pattern

Search for packages matching pattern in all enabled repositories.

For pattern, use the wildcard * to match any number of characters and the wildcard ? to match a single character. For example, to find packages starting with the string "List" search for list*. Searches are case insensitive.

If pattern contains ::, PPM will search for packages that provide modules matching the pattern.

If pattern matches the name of a package exactly (case-sensitively), only that package is shown. A pattern without wildcards that does not match any package names exactly is used for a substring search against available package names (i.e. treated the same as "*pattern*").

The output format depends on how many packages match. If there is only one match, the ppm describe format is used. If only a few packages match, limited information is displayed. If many packages match, only the package names and version numbers are displayed, one per line.

The number prefixing each entry in search output can be used to look up full information with ppm describe num, dependencies with ppm tree num or to install the package with ppm install num.

ppm tree package
ppm tree num

Shows all the dependencies (recusively) for a particular package. The package can be identified by a package name or the associated number for the package returned by the last ppm search command.

ppm uninstall ...

Alias for ppm remove.

ppm update ...

Alias for ppm upgrade.

ppm upgrade [ --install ]

List packages that there are upgrades available for. With --install option install the upgrades as well.

ppm upgrade pkg
ppm upgrade module

Upgrades the specified package or module if an upgrade is available in one of the currently enabled repositories.

ppm verify [ pkg ]

Checks that the installed files are still present and unmodified. If the package name is given, only that packages is verified.

ppm version

Will print the version of PPM and a copyright notice.

FILES

The following lists files and directories that PPM uses and creates:

$HOME/.ActivePerl/$VERSION/

Directory where PPM keeps its state. On Windows this directory is $LOCAL_APPDATA/ActiveState/ActivePerl/$VERSION. The $VERSION is a string like "818".

$HOME/.ActivePerl/$VERSION/ppm-$ARCH.db

SQLite database where ppm keeps its configuration and caches meta information about the content of the enabled repositories.

$HOME/ppm4.log

Log file created to record actions that PPM takes. On Windows this is logged to $TEMPDIR/ppm4.log.

$PREFIX/etc/ppm-$NAME-area.db

SQLite database where PPM tracks packages installed in the install area under $PREFIX.

$TEMPDIR/ppm-XXXXXX/

Temporary directories used during install. Packages to be installed are unpacked here.

  • XML files containing meta information about packages. Each package has its own .ppd file. See the ActivePerl::PPM::PPD manpage for additional information.

    • package.xml

    Meta information about repositories. When a repository is added, PPM looks for this file and if present, monitors it too stay in sync with the state of the repository.

    package.lst

    Same as package.xml but PPM 3 compatible. PPM will use this file if package.xml is not available.

    ENVIRONMENT

    The following environment variables affect how PPM behaves:

    ACTIVEPERL_PPM_DEBUG

    If set to a TRUE value, makes PPM print more internal diagnostics.

    ACTIVEPERL_PPM_BOX_CHARS

    Select what kind of box drawing characters to use for the ppm * list outputs. Valid values are ascii, dos and unicode. The default varies.

    ACTIVEPERL_PPM_HOME

    If set, use this directory to store state and configuration information for PPM. This defaults to $LOCAL_APPDATA/ActiveState/ActivePerl/$VERSION on Windows and $HOME/.ActivePerl/$VERSION/ on Unix systems.

    ACTIVEPERL_PPM_LOG_CONS

    If set to a TRUE value, make PPM print any log output to the console as well.

    DBI_TRACE

    PPM uses the DBI manpage to access the internal SQLite databases. Setting DBI_TRACE allow you to see what queries are performed. Output goes to STDERR. See the DBI manpage for further details.

    WHAT'S NEW IN VERSION 4

    PPM version 4 is a complete rewrite. The main changes since PPM version 3 are:

    • The command line shell has been replaced with a graphical user interface.

    • PPM can now manage different installation areas.

    • No more 'precious' packages. PPM can upgrade itself as well other bundled and core modules.

    • Installation of packages and their dependencies happen as atomic transactions.

    • PPM tracks what files it has installed and can notice if files have been modified or deleted. The command 'ppm verify' will report on mismatches.

    • State is kept in local SQLite databases. All repository state is kept local which makes searching much faster.

    • PPM will pick up and manage packages installed by other means (e.g. manually or with the CPAN shell).

    • No more SOAP.

    • Underlying modules moved to the ActivePerl::PPM:: namespace.

    SEE ALSO

    the activeperl manpage

    http://search.cpan.org/dist/PPM-Repositories/

    COPYRIGHT

    Copyright (C) 2007 ActiveState Software Inc. All rights reserved.


reloc_perl - copy a perl installation to a new location

  • OPTIONS
  • SEE ALSO
  • COPYRIGHT

NAME

reloc_perl - copy a perl installation to a new location

SYNOPSIS

  reloc_perl [-a] [-b] [-d] [-e path] [-f file] [-i] [-t] [-r] [-v]
             topath [frompath]

DESCRIPTION

The reloc_perl program will copy a perl installation wholesale to a new location. During the copy it edits path names in the copied files to reflect the new location.

The topath is the file system location where the perl installation should be copied to. This location should normally not already exists. A directory will be created at topath and then populated with the bin, lib, html and man directories of the perl installation.

The perl installation copied is the one where reloc_perl itself resides, but this can be overridden by providing a frompath. Running reloc_perl without arguments will show what this path is, as well as a short usage message.

OPTIONS

The following options are recognized by the reloc_perl program:

-a

The reloc_perl program will refuse to copy if topath is longer than frompath. This option overrides this restriction. The topath must still be shorter than the path built into the perl binary.

-b

Don't delete the backups created during the edits performed in topath.

-d

Delete the perl installation that was copied. Use with care!

-e path

Edit files to contain this path instead of the topath. This allow relocation to a different location than where the files themselves are copied.

-f logfile

Creates logfile and writes the full path name of each file that was modified (one line per file).

-i

Edit perl installation at topath in-place. Makes no attempt to move tree and the -d is ignored. This option is assumed if topath exists, is a directory, and frompath doesn't exist.

-t

Only edit the text files. When this option is used, the restriction that topath must not be longer than frompath is relaxed.

-r

Do not run ranlib any *.a files that were edited.

-v

Print a trace of what's going on.

SEE ALSO

the ActiveState::RelocateTree manpage

COPYRIGHT

Copyright 1999-2001 ActiveState Software Inc. All rights reserved.


tkx-ed - Simple editor

  • LICENSE
  • SEE ALSO

NAME

tkx-ed - Simple editor

SYNOPSIS

 tkx-ed [<file>]

DESCRIPTION

The tkx-ed program is a simple text editor implemented with the Tkx toolkit. Its main purpose is to demonstrate how this kind of application is written, so please take a look at its source code.

When the editor starts up it shows a blank page where you can start entering text directly.

If a file name is passed on the command line then the editor will visit this file initially.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 2005 ActiveState. All rights reserved.

SEE ALSO

the Tkx manpage

__END__ :endofperl


DBI - Database independent interface for Perl

    • GETTING HELP
    • NOTES
  • DESCRIPTION
    • Architecture of a DBI Application
    • Notation and Conventions
    • Outline Usage
    • General Interface Rules & Caveats
    • Naming Conventions and Name Space
    • SQL - A Query Language
    • Placeholders and Bind Values
  • THE DBI PACKAGE AND CLASS
    • DBI Constants
    • DBI Class Methods
    • DBI Utility Functions
    • DBI Dynamic Attributes
  • METHODS COMMON TO ALL HANDLES
  • ATTRIBUTES COMMON TO ALL HANDLES
  • DBI DATABASE HANDLE OBJECTS
    • Database Handle Methods
    • Database Handle Attributes
  • DBI STATEMENT HANDLE OBJECTS
    • Statement Handle Methods
    • Statement Handle Attributes
  • OTHER METHODS
  • FURTHER INFORMATION
    • Catalog Methods
    • Transactions
    • Handling BLOB / LONG / Memo Fields
    • Simple Examples
    • Threads and Thread Safety
    • Signal Handling and Canceling Operations
    • Subclassing the DBI
  • TRACING
    • Trace Settings
    • Trace Levels
    • Trace Flags
    • Enabling Trace
    • Trace Output
    • Trace Content
    • Tracing Tips
  • DBI ENVIRONMENT VARIABLES
    • DBI_DSN
    • DBI_DRIVER
    • DBI_AUTOPROXY
    • DBI_USER
    • DBI_PASS
    • DBI_DBNAME (obsolete)
    • DBI_TRACE
    • PERL_DBI_DEBUG (obsolete)
    • DBI_PROFILE
    • DBI_PUREPERL
  • WARNING AND ERROR MESSAGES
    • Fatal Errors
  • Pure-Perl DBI
  • SEE ALSO
    • Driver and Database Documentation
    • ODBC and SQL/CLI Standards Reference Information
    • Standards Reference Information
    • Books and Articles
    • Perl Modules
    • Mailing List
    • Assorted Related WWW Links
    • FAQ
  • AUTHORS
  • COPYRIGHT
  • SUPPORT / WARRANTY
    • Support
    • Sponsor Enhancements
  • ACKNOWLEDGEMENTS
  • CONTRIBUTING
    • Browsing the source code repository
    • How to create a patch using Subversion
    • How to create a patch without Subversion
    • Speak before you patch
  • TRANSLATIONS
  • TRAINING
  • FREQUENTLY ASKED QUESTIONS
    • Why doesn't my CGI script work right?
    • How can I maintain a WWW connection to a database?
  • OTHER RELATED WORK AND PERL MODULES

NAME

DBI - Database independent interface for Perl

SYNOPSIS

  use DBI;

  @driver_names = DBI->available_drivers;
  %drivers      = DBI->installed_drivers;
  @data_sources = DBI->data_sources($driver_name, \%attr);

  $dbh = DBI->connect($data_source, $username, $auth, \%attr);

  $rv  = $dbh->do($statement);
  $rv  = $dbh->do($statement, \%attr);
  $rv  = $dbh->do($statement, \%attr, @bind_values);

  $ary_ref  = $dbh->selectall_arrayref($statement);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field);

  $ary_ref  = $dbh->selectcol_arrayref($statement);
  $ary_ref  = $dbh->selectcol_arrayref($statement, \%attr);

  @row_ary  = $dbh->selectrow_array($statement);
  $ary_ref  = $dbh->selectrow_arrayref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement);

  $sth = $dbh->prepare($statement);
  $sth = $dbh->prepare_cached($statement);

  $rc = $sth->bind_param($p_num, $bind_value);
  $rc = $sth->bind_param($p_num, $bind_value, $bind_type);
  $rc = $sth->bind_param($p_num, $bind_value, \%attr);

  $rv = $sth->execute;
  $rv = $sth->execute(@bind_values);
  $rv = $sth->execute_array(\%attr, ...);

  $rc = $sth->bind_col($col_num, \$col_variable);
  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

  @row_ary  = $sth->fetchrow_array;
  $ary_ref  = $sth->fetchrow_arrayref;
  $hash_ref = $sth->fetchrow_hashref;

  $ary_ref  = $sth->fetchall_arrayref;
  $ary_ref  = $sth->fetchall_arrayref( $slice, $max_rows );

  $hash_ref = $sth->fetchall_hashref( $key_field );

  $rv  = $sth->rows;

  $rc  = $dbh->begin_work;
  $rc  = $dbh->commit;
  $rc  = $dbh->rollback;

  $quoted_string = $dbh->quote($string);

  $rc  = $h->err;
  $str = $h->errstr;
  $rv  = $h->state;

  $rc  = $dbh->disconnect;

The synopsis above only lists the major methods and parameters.

GETTING HELP

If you have questions about DBI, or DBD driver modules, you can get help from the dbi-users@perl.org mailing list. You can get help on subscribing and using the list by emailing dbi-users-help@perl.org.

To help you make the best use of the dbi-users mailing list, and any other lists or forums you may use, I strongly recommend that you read "How To Ask Questions The Smart Way" by Eric Raymond: http://www.catb.org/~esr/faqs/smart-questions.html.

If you think you've found a bug then please also read "How to Report Bugs Effectively" by Simon Tatham: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html.

The DBI home page at http://dbi.perl.org/ is always worth a visit and includes an FAQ and links to other resources.

Before asking any questions, reread this document, consult the archives and read the DBI FAQ. The archives are listed at the end of this document and on the DBI home page. An FAQ is installed as a the DBI::FAQ manpage module so you can read it by executing perldoc DBI::FAQ. However the DBI::FAQ module is currently (2004) outdated relative to the online FAQ on the DBI home page.

This document often uses terms like references, objects, methods. If you're not familar with those terms then it would be a good idea to read at least the following perl manuals first: the perlreftut manpage, the perldsc manpage, the perllol manpage, and the perlboot manpage.

Please note that Tim Bunce does not maintain the mailing lists or the web page (generous volunteers do that). So please don't send mail directly to him; he just doesn't have the time to answer questions personally. The dbi-users mailing list has lots of experienced people who should be able to help you if you need it. If you do email Tim he's very likely to just forward it to the mailing list.

NOTES

This is the DBI specification that corresponds to the DBI version 1.52.

The DBI is evolving at a steady pace, so it's good to check that you have the latest copy.

The significant user-visible changes in each release are documented in the the DBI::Changes manpage module so you can read them by executing perldoc DBI::Changes.

Some DBI changes require changes in the drivers, but the drivers can take some time to catch up. Newer versions of the DBI have added features that may not yet be supported by the drivers you use. Talk to the authors of your drivers if you need a new feature that's not yet supported.

Features added after DBI 1.21 (February 2002) are marked in the text with the version number of the DBI release they first appeared in.

Extensions to the DBI API often use the DBIx::* namespace. See Naming Conventions and Name Space. DBI extension modules can be found at http://search.cpan.org/search. And all modules related to the DBI can be found at http://search.cpan.org/search.

DESCRIPTION

The DBI is a database access module for the Perl programming language. It defines a set of methods, variables, and conventions that provide a consistent database interface, independent of the actual database being used.

It is important to remember that the DBI is just an interface. The DBI is a layer of "glue" between an application and one or more database driver modules. It is the driver modules which do most of the real work. The DBI provides a standard interface and framework for the drivers to operate within.

Architecture of a DBI Application

             |<- Scope of DBI ->|
                  .-.   .--------------.   .-------------.
  .-------.       | |---| XYZ Driver   |---| XYZ Engine  |
  | Perl  |       | |   `--------------'   `-------------'
  | script|  |A|  |D|   .--------------.   .-------------.
  | using |--|P|--|B|---|Oracle Driver |---|Oracle Engine|
  | DBI   |  |I|  |I|   `--------------'   `-------------'
  | API   |       | |...
  |methods|       | |... Other drivers
  `-------'       | |...
                  `-'

The API, or Application Programming Interface, defines the call interface and variables for Perl scripts to use. The API is implemented by the Perl DBI extension.

The DBI "dispatches" the method calls to the appropriate driver for actual execution. The DBI is also responsible for the dynamic loading of drivers, error checking and handling, providing default implementations for methods, and many other non-database specific duties.

Each driver contains implementations of the DBI methods using the private interface functions of the corresponding database engine. Only authors of sophisticated/multi-database applications or generic library functions need be concerned with drivers.

Notation and Conventions

The following conventions are used in this document:

  $dbh    Database handle object
  $sth    Statement handle object
  $drh    Driver handle object (rarely seen or used in applications)
  $h      Any of the handle types above ($dbh, $sth, or $drh)
  $rc     General Return Code  (boolean: true=ok, false=error)
  $rv     General Return Value (typically an integer)
  @ary    List of values returned from the database, typically a row of data
  $rows   Number of rows processed (if available, else -1)
  $fh     A filehandle
  undef   NULL values are represented by undefined values in Perl
  \%attr  Reference to a hash of attribute values passed to methods

Note that Perl will automatically destroy database and statement handle objects if all references to them are deleted.

Outline Usage

To use DBI, first you need to load the DBI module:

  use DBI;
  use strict;

(The use strict; isn't required but is strongly recommended.)

Then you need to connect to your data source and get a handle for that connection:

  $dbh = DBI->connect($dsn, $user, $password,
                      { RaiseError => 1, AutoCommit => 0 });

Since connecting can be expensive, you generally just connect at the start of your program and disconnect at the end.

Explicitly defining the required AutoCommit behaviour is strongly recommended and may become mandatory in a later version. This determines whether changes are automatically committed to the database when executed, or need to be explicitly committed later.

The DBI allows an application to "prepare" statements for later execution. A prepared statement is identified by a statement handle held in a Perl variable. We'll call the Perl variable $sth in our examples.

The typical method call sequence for a SELECT statement is:

  prepare,
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...

for example:

  $sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?");

  $sth->execute( $baz );

  while ( @row = $sth->fetchrow_array ) {
    print "@row\n";
  }

The typical method call sequence for a non-SELECT statement is:

  prepare,
    execute,
    execute,
    execute.

for example:

  $sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)");

  while(<CSV>) {
    chomp;
    my ($foo,$bar,$baz) = split /,/;
        $sth->execute( $foo, $bar, $baz );
  }

The do() method can be used for non repeated non-SELECT statement (or with drivers that don't support placeholders):

  $rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1");

To commit your changes to the database (when AutoCommit is off):

  $dbh->commit;  # or call $dbh->rollback; to undo changes

Finally, when you have finished working with the data source, you should disconnect from it:

  $dbh->disconnect;

General Interface Rules & Caveats

The DBI does not have a concept of a "current session". Every session has a handle object (i.e., a $dbh) returned from the connect method. That handle object is used to invoke database related methods.

Most data is returned to the Perl script as strings. (Null values are returned as undef.) This allows arbitrary precision numeric data to be handled without loss of accuracy. Beware that Perl may not preserve the same accuracy when the string is used as a number.

Dates and times are returned as character strings in the current default format of the corresponding database engine. Time zone effects are database/driver dependent.

Perl supports binary data in Perl strings, and the DBI will pass binary data to and from the driver without change. It is up to the driver implementors to decide how they wish to handle such binary data.

Most databases that understand multiple character sets have a default global charset. Text stored in the database is, or should be, stored in that charset; if not, then that's the fault of either the database or the application that inserted the data. When text is fetched it should be automatically converted to the charset of the client, presumably based on the locale. If a driver needs to set a flag to get that behaviour, then it should do so; it should not require the application to do that.

Multiple SQL statements may not be combined in a single statement handle ($sth), although some databases and drivers do support this (notably Sybase and SQL Server).

Non-sequential record reads are not supported in this version of the DBI. In other words, records can only be fetched in the order that the database returned them, and once fetched they are forgotten.

Positioned updates and deletes are not directly supported by the DBI. See the description of the CursorName attribute for an alternative.

Individual driver implementors are free to provide any private functions and/or handle attributes that they feel are useful. Private driver functions can be invoked using the DBI func() method. Private driver attributes are accessed just like standard attributes.

Many methods have an optional \%attr parameter which can be used to pass information to the driver implementing the method. Except where specifically documented, the \%attr parameter can only be used to pass driver specific hints. In general, you can ignore \%attr parameters or pass it as undef.

Naming Conventions and Name Space

The DBI package and all packages below it (DBI::*) are reserved for use by the DBI. Extensions and related modules use the DBIx:: namespace (see http://www.perl.com/CPAN/modules/by-module/DBIx/). Package names beginning with DBD:: are reserved for use by DBI database drivers. All environment variables used by the DBI or by individual DBDs begin with "DBI_" or "DBD_".

The letter case used for attribute names is significant and plays an important part in the portability of DBI scripts. The case of the attribute name is used to signify who defined the meaning of that name and its values.

  Case of name  Has a meaning defined by
  ------------  ------------------------
  UPPER_CASE    Standards, e.g.,  X/Open, ISO SQL92 etc (portable)
  MixedCase     DBI API (portable), underscores are not used.
  lower_case    Driver or database engine specific (non-portable)

It is of the utmost importance that Driver developers only use lowercase attribute names when defining private attributes. Private attribute names must be prefixed with the driver name or suitable abbreviation (e.g., "ora_" for Oracle, "ing_" for Ingres, etc).

SQL - A Query Language

Most DBI drivers require applications to use a dialect of SQL (Structured Query Language) to interact with the database engine. The Standards Reference Information section provides links to useful information about SQL.

The DBI itself does not mandate or require any particular language to be used; it is language independent. In ODBC terms, the DBI is in "pass-thru" mode, although individual drivers might not be. The only requirement is that queries and other statements must be expressed as a single string of characters passed as the first argument to the prepare or do methods.

For an interesting diversion on the real history of RDBMS and SQL, from the people who made it happen, see:

  http://ftp.digital.com/pub/DEC/SRC/technical-notes/SRC-1997-018-html/sqlr95.html

Follow the "Full Contents" then "Intergalactic dataspeak" links for the SQL history.

Placeholders and Bind Values

Some drivers support placeholders and bind values. Placeholders, also called parameter markers, are used to indicate values in a database statement that will be supplied later, before the prepared statement is executed. For example, an application might use the following to insert a row of data into the SALES table:

  INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)

or the following, to select the description for a product:

  SELECT description FROM products WHERE product_code = ?

The ? characters are the placeholders. The association of actual values with placeholders is known as binding, and the values are referred to as bind values.

Note that the ? is not enclosed in quotation marks, even when the placeholder represents a string. Some drivers also allow placeholders like :name and :n (e.g., :1, :2, and so on) in addition to ?, but their use is not portable.

With most drivers, placeholders can't be used for any element of a statement that would prevent the database server from validating the statement and creating a query execution plan for it. For example:

  "SELECT name, age FROM ?"         # wrong (will probably fail)
  "SELECT name, ?   FROM people"    # wrong (but may not 'fail')

Also, placeholders can only represent single scalar values. For example, the following statement won't work as expected for more than one value:

  "SELECT name, age FROM people WHERE name IN (?)"    # wrong
  "SELECT name, age FROM people WHERE name IN (?,?)"  # two names

When using placeholders with the SQL LIKE qualifier, you must remember that the placeholder substitutes for the whole string. So you should use "... LIKE ? ..." and include any wildcard characters in the value that you bind to the placeholder.

NULL Values

Undefined values, or undef, are used to indicate NULL values. You can insert and update columns with a NULL value as you would a non-NULL value. These examples insert and update the column age with a NULL value:

  $sth = $dbh->prepare(qq{
    INSERT INTO people (fullname, age) VALUES (?, ?)
  });
  $sth->execute("Joe Bloggs", undef);

  $sth = $dbh->prepare(qq{
    UPDATE people SET age = ? WHERE fullname = ?
  });
  $sth->execute(undef, "Joe Bloggs");

  However, care must be taken when trying to use NULL values in a
  C<WHERE> clause.  Consider:

  SELECT fullname FROM people WHERE age = ?

Binding an undef (NULL) to the placeholder will not select rows which have a NULL age! At least for database engines that conform to the SQL standard. Refer to the SQL manual for your database engine or any SQL book for the reasons for this. To explicitly select NULLs you have to say "WHERE age IS NULL".

A common issue is to have a code fragment handle a value that could be either defined or undef (non-NULL or NULL) at runtime. A simple technique is to prepare the appropriate statement as needed, and substitute the placeholder for non-NULL cases:

  $sql_clause = defined $age? "age = ?" : "age IS NULL";
  $sth = $dbh->prepare(qq{
    SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(defined $age ? $age : ());

The following technique illustrates qualifying a WHERE clause with several columns, whose associated values (defined or undef) are in a hash %h:

  for my $col ("age", "phone", "email") {
    if (defined $h{$col}) {
      push @sql_qual, "$col = ?";
      push @sql_bind, $h{$col};
    }
    else {
      push @sql_qual, "$col IS NULL";
    }
  }
  $sql_clause = join(" AND ", @sql_qual);
  $sth = $dbh->prepare(qq{
      SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(@sql_bind);

The techniques above call prepare for the SQL statement with each call to execute. Because calls to prepare() can be expensive, performance can suffer when an application iterates many times over statements like the above.

A better solution is a single WHERE clause that supports both NULL and non-NULL comparisons. Its SQL statement would need to be prepared only once for all cases, thus improving performance. Several examples of WHERE clauses that support this are presented below. But each example lacks portability, robustness, or simplicity. Whether an example is supported on your database engine depends on what SQL extensions it provides, and where it supports the ? placeholder in a statement.

  0)  age = ?
  1)  NVL(age, xx) = NVL(?, xx)
  2)  ISNULL(age, xx) = ISNULL(?, xx)
  3)  DECODE(age, ?, 1, 0) = 1
  4)  age = ? OR (age IS NULL AND ? IS NULL)
  5)  age = ? OR (age IS NULL AND SP_ISNULL(?) = 1)
  6)  age = ? OR (age IS NULL AND ? = 1)

Statements formed with the above C<WHERE> clauses require execute
statements as follows.  The arguments are required, whether their
values are C<defined> or C<undef>.
  0,1,2,3)  $sth->execute($age);
  4,5)      $sth->execute($age, $age);
  6)        $sth->execute($age, defined($age) ? 0 : 1);

Example 0 should not work (as mentioned earlier), but may work on a few database engines anyway (e.g. Sybase). Example 0 is part of examples 4, 5, and 6, so if example 0 works, these other examples may work, even if the engine does not properly support the right hand side of the OR expression.

Examples 1 and 2 are not robust: they require that you provide a valid column value xx (e.g. '~') which is not present in any row. That means you must have some notion of what data won't be stored in the column, and expect clients to adhere to that.

Example 5 requires that you provide a stored procedure (SP_ISNULL in this example) that acts as a function: it checks whether a value is null, and returns 1 if it is, or 0 if not.

Example 6, the least simple, is probably the most portable, i.e., it should work with with most, if not all, database engines.

Here is a table that indicates which examples above are known to work on various database engines:

                   -----Examples------
                   0  1  2  3  4  5  6
                   -  -  -  -  -  -  -
  Oracle 9         N  Y  N  Y  Y  ?  Y
  Informix IDS 9   N  N  N  Y  N  Y  Y
  MS SQL           N  N  Y  N  Y  ?  Y
  Sybase           Y  N  N  N  N  N  Y
  AnyData,DBM,CSV  Y  N  N  N  Y  Y* Y

* Works only because Example 0 works.

DBI provides a sample perl script that will test the examples above on your database engine and tell you which ones work. It is located in the ex/ subdirectory of the DBI source distribution, or here: http://svn.perl.org/modules/dbi/trunk/ex/perl_dbi_nulls_test.pl Please use the script to help us fill-in and maintain this table.

Performance

Without using placeholders, the insert statement shown previously would have to contain the literal values to be inserted and would have to be re-prepared and re-executed for each row. With placeholders, the insert statement only needs to be prepared once. The bind values for each row can be given to the execute method each time it's called. By avoiding the need to re-prepare the statement for each row, the application typically runs many times faster. Here's an example:

  my $sth = $dbh->prepare(q{
    INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)
  }) or die $dbh->errstr;
  while (<>) {
      chomp;
      my ($product_code, $qty, $price) = split /,/;
      $sth->execute($product_code, $qty, $price) or die $dbh->errstr;
  }
  $dbh->commit or die $dbh->errstr;

See execute and bind_param for more details.

The q{...} style quoting used in this example avoids clashing with quotes that may be used in the SQL statement. Use the double-quote like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

See also the bind_columns method, which is used to associate Perl variables with the output columns of a SELECT statement.

THE DBI PACKAGE AND CLASS

In this section, we cover the DBI class methods, utility functions, and the dynamic attributes associated with generic DBI handles.

DBI Constants

Constants representing the values of the SQL standard types can be imported individually by name, or all together by importing the special :sql_types tag.

The names and values of all the defined SQL standard types can be produced like this:

  foreach (@{ $DBI::EXPORT_TAGS{sql_types} }) {
    printf "%s=%d\n", $_, &{"DBI::$_"};
  }

These constants are defined by SQL/CLI, ODBC or both. SQL_BIGINT is (currently) omitted, because SQL/CLI and ODBC provide conflicting codes.

See the type_info, type_info_all, and bind_param methods for possible uses.

Note that just because the DBI defines a named constant for a given data type doesn't mean that drivers will support that data type.

DBI Class Methods

The following methods are provided by the DBI class:

parse_dsn
  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn) = DBI->parse_dsn($dsn)
      or die "Can't parse DBI DSN '$dsn'";

Breaks apart a DBI Data Source Name (DSN) and returns the individual parts. If $dsn doesn't contain a valid DSN then parse_dsn() returns an empty list.

$scheme is the first part of the DSN and is currently always 'dbi'. $driver is the driver name, possibly defaulted to $ENV{DBI_DRIVER}, and may be undefined. $attr_string is the contents of the optional attribute string, which may be undefined. If $attr_string is not empty then $attr_hash is a reference to a hash containing the parsed attribute names and values. $driver_dsn is the last part of the DBI DSN string. For example:

  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn)
      = DBI->parse_dsn("DBI:MyDriver(RaiseError=>1):db=test;port=42");
  $scheme      = 'dbi';
  $driver      = 'MyDriver';
  $attr_string = 'RaiseError=>1';
  $attr_hash   = { 'RaiseError' => '1' };
  $driver_dsn  = 'db=test;port=42';

The parse_dsn() method was added in DBI 1.43.

connect
  $dbh = DBI->connect($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

Establishes a database connection, or session, to the requested $data_source. Returns a database handle object if the connection succeeds. Use $dbh->disconnect to terminate the connection.

If the connect fails (see below), it returns undef and sets both $DBI::err and $DBI::errstr. (It does not explicitly set $!.) You should generally test the return status of connect and print $DBI::errstr if it has failed.

Multiple simultaneous connections to multiple databases through multiple drivers can be made via the DBI. Simply make one connect call for each database and keep a copy of each returned database handle.

The $data_source value must begin with "dbi:driver_name:". The driver_name specifies the driver that will be used to make the connection. (Letter case is significant.)

As a convenience, if the $data_source parameter is undefined or empty, the DBI will substitute the value of the environment variable DBI_DSN. If just the driver_name part is empty (i.e., the $data_source prefix is "dbi::"), the environment variable DBI_DRIVER is used. If neither variable is set, then connect dies.

Examples of $data_source values are:

  dbi:DriverName:database_name
  dbi:DriverName:database_name@hostname:port
  dbi:DriverName:database=database_name;host=hostname;port=port

There is no standard for the text following the driver name. Each driver is free to use whatever syntax it wants. The only requirement the DBI makes is that all the information is supplied in a single string. You must consult the documentation for the drivers you are using for a description of the syntax they require.

It is recommended that drivers support the ODBC style, shown in the last example above. It is also recommended that that they support the three common names 'host', 'port', and 'database' (plus 'db' as an alias for database). This simplifies automatic construction of basic DSNs: "dbi:$driver:database=$db;host=$host;port=$port". Drivers should aim to 'do something reasonable' when given a DSN in this form, but if any part is meaningless for that driver (such as 'port' for Informix) it should generate an error if that part is not empty.

If the environment variable DBI_AUTOPROXY is defined (and the driver in $data_source is not "Proxy") then the connect request will automatically be changed to:

  $ENV{DBI_AUTOPROXY};dsn=$data_source

DBI_AUTOPROXY is typically set as "dbi:Proxy:hostname=...;port=...". If $ENV{DBI_AUTOPROXY} doesn't begin with 'dbi:' then "dbi:Proxy:" will be prepended to it first. See the DBD::Proxy documentation for more details.

If $username or $password are undefined (rather than just empty), then the DBI will substitute the values of the DBI_USER and DBI_PASS environment variables, respectively. The DBI will warn if the environment variables are not defined. However, the everyday use of these environment variables is not recommended for security reasons. The mechanism is primarily intended to simplify testing. See below for alternative way to specify the username and password.

DBI->connect automatically installs the driver if it has not been installed yet. Driver installation either returns a valid driver handle, or it dies with an error message that includes the string "install_driver" and the underlying problem. So DBI->connect will die on a driver installation failure and will only return undef on a connect failure, in which case $DBI::errstr will hold the error message. Use eval { ... } if you need to catch the "install_driver" error.

The $data_source argument (with the "dbi:...:" prefix removed) and the $username and $password arguments are then passed to the driver for processing. The DBI does not define any interpretation for the contents of these fields. The driver is free to interpret the $data_source, $username, and $password fields in any way, and supply whatever defaults are appropriate for the engine being accessed. (Oracle, for example, uses the ORACLE_SID and TWO_TASK environment variables if no $data_source is specified.)

The AutoCommit and PrintError attributes for each connection default to "on". (See AutoCommit and PrintError for more information.) However, it is strongly recommended that you explicitly define AutoCommit rather than rely on the default. The PrintWarn attribute defaults to on if $^W is true, i.e., perl is running with warnings enabled.

The \%attr parameter can be used to alter the default settings of PrintError, RaiseError, AutoCommit, and other attributes. For example:

  $dbh = DBI->connect($data_source, $user, $pass, {
        PrintError => 0,
        AutoCommit => 0
  });

The username and password can also be specified using the attributes Username and Password, in which case they take precedence over the $username and $password parameters.

You can also define connection attribute values within the $data_source parameter. For example:

  dbi:DriverName(PrintWarn=>1,PrintError=>0,Taint=>1):...

Individual attributes values specified in this way take precedence over any conflicting values specified via the \%attr parameter to connect.

The dbi_connect_method attribute can be used to specify which driver method should be called to establish the connection. The only useful values are 'connect', 'connect_cached', or some specialized case like 'Apache::DBI::connect' (which is automatically the default when running within Apache).

Where possible, each session ($dbh) is independent from the transactions in other sessions. This is useful when you need to hold cursors open across transactions--for example, if you use one session for your long lifespan cursors (typically read-only) and another for your short update transactions.

For compatibility with old DBI scripts, the driver can be specified by passing its name as the fourth argument to connect (instead of \%attr):

  $dbh = DBI->connect($data_source, $user, $pass, $driver);

In this "old-style" form of connect, the $data_source should not start with "dbi:driver_name:". (If it does, the embedded driver_name will be ignored). Also note that in this older form of connect, the $dbh->{AutoCommit} attribute is undefined, the $dbh->{PrintError} attribute is off, and the old DBI_DBNAME environment variable is checked if DBI_DSN is not defined. Beware that this "old-style" connect will soon be withdrawn in a future version of DBI.

connect_cached
  $dbh = DBI->connect_cached($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect_cached($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

connect_cached is like connect, except that the database handle returned is also stored in a hash associated with the given parameters. If another call is made to connect_cached with the same parameter values, then the corresponding cached $dbh will be returned if it is still valid. The cached database handle is replaced with a new connection if it has been disconnected or if the ping method fails.

That the behaviour of this method differs in several respects from the behaviour of persistent connections implemented by Apache::DBI. However, if Apache::DBI is loaded then connect_cached will use it.

Caching connections can be useful in some applications, but it can also cause problems, such as too many connections, and so should be used with care. In particular, avoid changing the attributes of a database handle created via connect_cached() because it will affect other code that may be using the same handle.

Where multiple separate parts of a program are using connect_cached() to connect to the same database with the same (initial) attributes it is a good idea to add a private attribute to the connect_cached() call to effectively limit the scope of the caching. For example:

  DBI->connect_cached(..., { private_foo_cachekey => "Bar", ... });

Handles returned from that connect_cached() call will only be returned by other connect_cached() call elsewhere in the code if those other calls also pass in the same attribute values, including the private one. (I've used private_foo_cachekey here as an example, you can use any attribute name with a private_ prefix.)

Taking that one step further, you can limit a particular connect_cached() call to return handles unique to that one place in the code by setting the private attribute to a unique value for that place:

  DBI->connect_cached(..., { private_foo_cachekey => __FILE__.__LINE__, ... });

By using a private attribute you still get connection caching for the individual calls to connect_cached() but, by making separate database conections for separate parts of the code, the database handles are isolated from any attribute changes made to other handles.

The cache can be accessed (and cleared) via the CachedKids attribute:

  my $CachedKids_hashref = $dbh->{Driver}->{CachedKids};
  %$CachedKids_hashref = () if $CachedKids_hashref;
available_drivers
  @ary = DBI->available_drivers;
  @ary = DBI->available_drivers($quiet);

Returns a list of all available drivers by searching for DBD::* modules through the directories in @INC. By default, a warning is given if some drivers are hidden by others of the same name in earlier directories. Passing a true value for $quiet will inhibit the warning.

installed_drivers
  %drivers = DBI->installed_drivers();

Returns a list of driver name and driver handle pairs for all drivers 'installed' (loaded) into the current process. The driver name does not include the 'DBD::' prefix.

To get a list of all drivers available in your perl instalation you can use available_drivers.

Added in DBI 1.49.

installed_versions
  DBI->installed_versions;
  @ary  = DBI->installed_versions;
  %hash = DBI->installed_versions;

Calls available_drivers() and attempts to load each of them in turn using install_driver(). For each load that succeeds the driver name and version number are added to a hash. When running under the DBI::PurePerl manpage drivers which appear not be pure-perl are ignored.

When called in array context the list of successfully loaded drivers is returned (without the 'DBD::' prefix).

When called in scalar context a reference to the hash is returned and the hash will also contain other entries for the DBI version, OS name, etc.

When called in a void context the installed_versions() method will print out a formatted list of the hash contents, one per line.

Due to the potentially high memory cost and unknown risks of loading in an unknown number of drivers that just happen to be installed on the system, this method is nor recommended for general use. Use available_drivers() instead.

The installed_versions() method is primarily intended as a quick way to see from the command line what's installed. For example:

  perl -MDBI -e 'DBI->installed_versions'

The installed_versions() method was added in DBI 1.38.

data_sources
  @ary = DBI->data_sources($driver);
  @ary = DBI->data_sources($driver, \%attr);

Returns a list of data sources (databases) available via the named driver. If $driver is empty or undef, then the value of the DBI_DRIVER environment variable is used.

The driver will be loaded if it hasn't been already. Note that if the driver loading fails then data_sources() dies with an error message that includes the string "install_driver" and the underlying problem.

Data sources are returned in a form suitable for passing to the connect method (that is, they will include the "dbi:$driver:" prefix).

Note that many drivers have no way of knowing what data sources might be available for it. These drivers return an empty or incomplete list or may require driver-specific attributes.

There is also a data_sources() method defined for database handles.

trace
  DBI->trace($trace_setting)
  DBI->trace($trace_setting, $trace_filename)
  $trace_setting = DBI->trace;

The DBI->trace method sets the global default trace settings and returns the previous trace settings. It can also be used to change where the trace output is sent.

There's a similar method, $h->trace, which sets the trace settings for the specific handle it's called on.

See the TRACING section for full details about the DBI's powerful tracing facilities.

DBI Utility Functions

In addition to the DBI methods listed in the previous section, the DBI package also provides several utility functions.

These can be imported into your code by listing them in the use statement. For example:

  use DBI qw(neat data_diff);

Alternatively, all these utility functions (except hash) can be imported using the :utils import tag. For example:

  use DBI qw(:utils);
data_string_desc
  $description = data_string_desc($string);

Returns an informal description of the string. For example:

  UTF8 off, ASCII, 42 characters 42 bytes
  UTF8 off, non-ASCII, 42 characters 42 bytes
  UTF8 on, non-ASCII, 4 characters 6 bytes
  UTF8 on but INVALID encoding, non-ASCII, 4 characters 6 bytes
  UTF8 off, undef

The initial UTF8 on/off refers to Perl's internal SvUTF8 flag. If $string has the SvUTF8 flag set but the sequence of bytes it contains are not a valid UTF-8 encoding then data_string_desc() will report UTF8 on but INVALID encoding.

The ASCII vs non-ASCII portion shows ASCII if all the characters in the string are ASCII (have code points <= 127).

The data_string_desc() function was added in DBI 1.46.

data_string_diff
  $diff = data_string_diff($a, $b);

Returns an informal description of the first character difference between the strings. If both $a and $b contain the same sequence of characters then data_string_diff() returns an empty string. For example:

 Params a & b     Result
 ------------     ------
 'aaa', 'aaa'     ''
 'aaa', 'abc'     'Strings differ at index 2: a[2]=a, b[2]=b'
 'aaa', undef     'String b is undef, string a has 3 characters'
 'aaa', 'aa'      'String b truncated after 2 characters'

Unicode characters are reported in \x{XXXX} format. Unicode code points in the range U+0800 to U+08FF are unassigned and most likely to occur due to double-encoding. Characters in this range are reported as \x{08XX}='C' where C is the corresponding latin-1 character.

The data_string_diff() function only considers logical characters and not the underlying encoding. See data_diff for an alternative.

The data_string_diff() function was added in DBI 1.46.

data_diff
  $diff = data_diff($a, $b);
  $diff = data_diff($a, $b, $logical);

Returns an informal description of the difference between two strings. It calls data_string_desc and data_string_diff and returns the combined results as a multi-line string.

For example, data_diff("abc", "ab\x{263a}") will return:

  a: UTF8 off, ASCII, 3 characters 3 bytes
  b: UTF8 on, non-ASCII, 3 characters 5 bytes
  Strings differ at index 2: a[2]=c, b[2]=\x{263A}

If $a and $b are identical in both the characters they contain and their physical encoding then data_diff() returns an empty string. If $logical is true then physical encoding differences are ignored (but are still reported if there is a difference in the characters).

The data_diff() function was added in DBI 1.46.

neat
  $str = neat($value);
  $str = neat($value, $maxlen);

Return a string containing a neat (and tidy) representation of the supplied value.

Strings will be quoted, although internal quotes will not be escaped. Values known to be numeric will be unquoted. Undefined (NULL) values will be shown as undef (without quotes).

If the string is flagged internally as utf8 then double quotes will be used, otherwise single quotes are used and unprintable characters will be replaced by dot (.).

For result strings longer than $maxlen the result string will be truncated to $maxlen-4 and "...'" will be appended. If $maxlen is 0 or undef, it defaults to $DBI::neat_maxlen which, in turn, defaults to 400.

This function is designed to format values for human consumption. It is used internally by the DBI for trace output. It should typically not be used for formatting values for database use. (See also quote.)

neat_list
  $str = neat_list(\@listref, $maxlen, $field_sep);

Calls neat on each element of the list and returns a string containing the results joined with $field_sep. $field_sep defaults to ", ".

looks_like_number
  @bool = looks_like_number(@array);

Returns true for each element that looks like a number. Returns false for each element that does not look like a number. Returns undef for each element that is undefined or empty.

hash
  $hash_value = DBI::hash($buffer, $type);

Return a 32-bit integer 'hash' value corresponding to the contents of $buffer. The $type parameter selects which kind of hash algorithm should be used.

For the technically curious, type 0 (which is the default if $type isn't specified) is based on the Perl 5.1 hash except that the value is forced to be negative (for obscure historical reasons). Type 1 is the better "Fowler / Noll / Vo" (FNV) hash. See http://www.isthe.com/chongo/tech/comp/fnv/ for more information. Both types are implemented in C and are very fast.

This function doesn't have much to do with databases, except that it can be handy to store hash values in a database.

DBI Dynamic Attributes

Dynamic attributes are always associated with the last handle used (that handle is represented by $h in the descriptions below).

Where an attribute is equivalent to a method call, then refer to the method call for all related documentation.

Warning: these attributes are provided as a convenience but they do have limitations. Specifically, they have a short lifespan: because they are associated with the last handle used, they should only be used immediately after calling the method that "sets" them. If in any doubt, use the corresponding method call.

$DBI::err

Equivalent to $h->err.

$DBI::errstr

Equivalent to $h->errstr.

$DBI::state

Equivalent to $h->state.

$DBI::rows

Equivalent to $h->rows. Please refer to the documentation for the rows method.

$DBI::lasth

Returns the DBI object handle used for the most recent DBI method call. If the last DBI method call was a DESTROY then $DBI::lasth will return the handle of the parent of the destroyed handle, if there is one.

METHODS COMMON TO ALL HANDLES

The following methods can be used by all types of DBI handles.

err
  $rv = $h->err;

Returns the native database engine error code from the last driver method called. The code is typically an integer but you should not assume that.

The DBI resets $h->err to undef before almost all DBI method calls, so the value only has a short lifespan. Also, for most drivers, the statement handles share the same error variable as the parent database handle, so calling a method on one handle may reset the error on the related handles.

(Methods which don't reset err before being called include err() and errstr(), obviously, state(), rows(), func(), trace(), trace_msg(), ping(), and the tied hash attribute FETCH() and STORE() methods.)

If you need to test for specific error conditions and have your program be portable to different database engines, then you'll need to determine what the corresponding error codes are for all those engines and test for all of them.

A driver may return 0 from err() to indicate a warning condition after a method call. Similarly, a driver may return an empty string to indicate a 'success with information' condition. In both these cases the value is false but not undef. The errstr() and state() methods may be used to retrieve extra information in these cases.

See set_err for more information.

errstr
  $str = $h->errstr;

Returns the native database engine error message from the last DBI method called. This has the same lifespan issues as the err method described above.

The returned string may contain multiple messages separated by newline characters.

The errstr() method should not be used to test for errors, use err() for that, because drivers may return 'success with information' or warning messages via errstr() for methods that have not 'failed'.

See set_err for more information.

state
  $str = $h->state;

Returns a state code in the standard SQLSTATE five character format. Note that the specific success code 00000 is translated to any empty string (false). If the driver does not support SQLSTATE (and most don't), then state will return S1000 (General Error) for all errors.

The driver is free to return any value via state, e.g., warning codes, even if it has not declared an error by returning a true value via the err method described above.

The state() method should not be used to test for errors, use err() for that, because drivers may return a 'success with information' or warning state code via errstr() for methods that have not 'failed'.

set_err
  $rv = $h->set_err($err, $errstr);
  $rv = $h->set_err($err, $errstr, $state);
  $rv = $h->set_err($err, $errstr, $state, $method);
  $rv = $h->set_err($err, $errstr, $state, $method, $rv);

Set the err, errstr, and state values for the handle. This method is typically only used by DBI drivers and DBI subclasses.

If the HandleSetErr attribute holds a reference to a subroutine it is called first. The subroutine can alter the $err, $errstr, $state, and $method values. See HandleSetErr for full details. If the subroutine returns a true value then the handle err, errstr, and state values are not altered and set_err() returns an empty list (it normally returns $rv which defaults to undef, see below).

Setting err to a true value indicates an error and will trigger the normal DBI error handling mechanisms, such as RaiseError and HandleError, if they are enabled, when execution returns from the DBI back to the application.

Setting err to "" indicates an 'information' state, and setting it to "0" indicates a 'warning' state. Setting err to undef also sets errstr to undef, and state to "", irrespective of the values of the $errstr and $state parameters.

The $method parameter provides an alternate method name for the RaiseError/PrintError/PrintWarn error string instead of the fairly unhelpful 'set_err'.

The set_err method normally returns undef. The $rv parameter provides an alternate return value.

Some special rules apply if the err or errstr values for the handle are already set...

If errstr is true then: " [err was %s now %s]" is appended if $err is true and err is already true; " [state was %s now %s]" is appended if $state is true and state is already true; then "\n" and the new $errstr are appended. Obviously the %s's above are replaced by the corresponding values.

The handle err value is set to $err if: $err is true; or handle err value is undef; or $err is defined and the length is greater than the handle err length. The effect is that an 'information' state only overrides undef; a 'warning' overrides undef or 'information', and an 'error' state overrides anything.

The handle state value is set to $state if $state is true and the handle err value was set (by the rules above).

Support for warning and information states was added in DBI 1.41.

trace
  $h->trace($trace_settings);
  $h->trace($trace_settings, $trace_filename);
  $trace_settings = $h->trace;

The trace() method is used to alter the trace settings for a handle (and any future children of that handle). It can also be used to change where the trace output is sent.

There's a similar method, DBI->trace, which sets the global default trace settings.

See the TRACING section for full details about the DBI's powerful tracing facilities.

trace_msg
  $h->trace_msg($message_text);
  $h->trace_msg($message_text, $min_level);

Writes $message_text to the trace file if the trace level is greater than or equal to $min_level (which defaults to 1). Can also be called as DBI->trace_msg($msg).

See TRACING for more details.

func
  $h->func(@func_arguments, $func_name) or die ...;

The func method can be used to call private non-standard and non-portable methods implemented by the driver. Note that the function name is given as the last argument.

It's also important to note that the func() method does not clear a previous error ($DBI::err etc.) and it does not trigger automatic error detection (RaiseError etc.) so you must check the return status and/or $h->err to detect errors.

(This method is not directly related to calling stored procedures. Calling stored procedures is currently not defined by the DBI. Some drivers, such as DBD::Oracle, support it in non-portable ways. See driver documentation for more details.)

See also install_method for how you can avoid needing to use func() and gain.

can
  $is_implemented = $h->can($method_name);

Returns true if $method_name is implemented by the driver or a default method is provided by the DBI. It returns false where a driver hasn't implemented a method and the default method is provided by the DBI is just an empty stub.

parse_trace_flags
  $trace_settings_integer = $h->parse_trace_flags($trace_settings);

Parses a string containing trace settings and returns the corresponding integer value used internally by the DBI and drivers.

The $trace_settings argument is a string containing a trace level between 0 and 15 and/or trace flag names separated by vertical bar ("|") or comma (",") characters. For example: "SQL|3|foo".

It uses the parse_trace_flag() method, described below, to process the individual trage flag names.

The parse_trace_flags() method was added in DBI 1.42.

parse_trace_flag
  $bit_flag = $h->parse_trace_flag($trace_flag_name);

Returns the bit flag corresponding to the trace flag name in $trace_flag_name. Drivers are expected to override this method and check if $trace_flag_name is a driver specific trace flags and, if not, then call the DBIs default parse_trace_flag().

The parse_trace_flag() method was added in DBI 1.42.

swap_inner_handle
  $rc = $h1->swap_inner_handle( $h2 );
  $rc = $h1->swap_inner_handle( $h2, $allow_reparent );

Brain transplants for handles. You don't need to know about this unless you want to become a handle surgeon.

A DBI handle is a reference to a tied hash. A tied hash has an inner hash that actually holds the contents. The swap_inner_handle() method swaps the inner hashes between two handles. The $h1 and $h2 handles still point to the same tied hashes, but what those hashes are tied to has been swapped. In effect $h1 becomes $h2 and vice-versa. This is powerful stuff. Use with care.

As a small safety measure, the two handles, $h1 and $h2, have to share the same parent unless $allow_reparent is true.

The swap_inner_handle() method was added in DBI 1.44.

ATTRIBUTES COMMON TO ALL HANDLES

These attributes are common to all types of DBI handles.

Some attributes are inherited by child handles. That is, the value of an inherited attribute in a newly created statement handle is the same as the value in the parent database handle. Changes to attributes in the new statement handle do not affect the parent database handle and changes to the database handle do not affect existing statement handles, only future ones.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver specific attributes (which all have names starting with a lowercase letter).

Example:

  $h->{AttributeName} = ...;    # set/write
  ... = $h->{AttributeName};    # get/read
Warn (boolean, inherited)

The Warn attribute enables useful warnings for certain bad practices. It is enabled by default and should only be disabled in rare circumstances. Since warnings are generated using the Perl warn function, they can be intercepted using the Perl $SIG{__WARN__} hook.

The Warn attribute is not related to the PrintWarn attribute.

Active (boolean, read-only)

The Active attribute is true if the handle object is "active". This is rarely used in applications. The exact meaning of active is somewhat vague at the moment. For a database handle it typically means that the handle is connected to a database ($dbh->disconnect sets Active off). For a statement handle it typically means that the handle is a SELECT that may have more data to fetch. (Fetching all the data or calling $sth->finish sets Active off.)

Executed (boolean)

The Executed attribute is true if the handle object has been "executed". Currently only the $dbh do() method and the $sth execute(), execute_array(), and execute_for_fetch() methods set the Executed attribute.

When it's set on a handle it is also set on the parent handle at the same time. So calling execute() on a $sth also sets the Executed attribute on the parent $dbh.

The Executed attribute for a database handle is cleared by the commit() and rollback() methods. The Executed attribute of a statement handle is not cleared by the DBI under any circumstances and so acts as a permanent record of whether the statement handle was ever used.

The Executed attribute was added in DBI 1.41.

Kids (integer, read-only)

For a driver handle, Kids is the number of currently existing database handles that were created from that driver handle. For a database handle, Kids is the number of currently existing statement handles that were created from that database handle. For a statement handle, the value is zero.

ActiveKids (integer, read-only)

Like Kids, but only counting those that are Active (as above).

CachedKids (hash ref)

For a database handle, CachedKids returns a reference to the cache (hash) of statement handles created by the prepare_cached method. For a driver handle, returns a reference to the cache (hash) of database handles created by the connect_cached method.

Type (scalar)

The Type attribute identifies the type of a DBI handle. Returns "dr" for driver handles, "db" for database handles and "st" for statement handles.

ChildHandles (array ref)

The ChildHandles attribute contains a reference to an array of all the handles created by this handle which are still accessible. The contents of the array are weak-refs and will become undef when the handle goes out of scope.

ChildHandles returns undef if your perl version does not support weak references (check the Scalar::Util module). The referenced array returned should be treated as read-only.

For example, to enumerate all driver handles, database handles and statement handles:

    sub show_child_handles {
        my ($h, $level) = @_;
        $level ||= 0;
        printf "%sh %s %s\n", $h->{Type}, "\t" x $level, $h;
        show_child_handles($_, $level + 1)
            for (grep { defined } @{$h->{ChildHandles}});
    }

    my %drivers = DBI->installed_drivers();
    show_child_handles($_) for (values %drivers);
CompatMode (boolean, inherited)

The CompatMode attribute is used by emulation layers (such as Oraperl) to enable compatible behaviour in the underlying driver (e.g., DBD::Oracle) for this handle. Not normally set by application code.

It also has the effect of disabling the 'quick FETCH' of attribute values from the handles attribute cache. So all attribute values are handled by the drivers own FETCH method. This makes them slightly slower but is useful for special-purpose drivers like DBD::Multiplex.

InactiveDestroy (boolean)

The default value, false, means a handle will be fully destroyed as normal when the last reference to it is removed, just as you'd expect.

If set true then the handle will be treated by the DESTROY as if it was no longer Active, and so the database engine related effects of DESTROYing a handle will be skipped.

Think of the name as meaning 'treat the handle as not-Active in the DESTROY method'.

For a database handle, this attribute does not disable an explicit call to the disconnect method, only the implicit call from DESTROY that happens if the handle is still marked as Active.

This attribute is specifically designed for use in Unix applications that "fork" child processes. Either the parent or the child process, but not both, should set InactiveDestroy true on all their shared handles. (Note that some databases, including Oracle, don't support passing a database connection across a fork.)

To help tracing applications using fork the process id is shown in the trace log whenever a DBI or handle trace() method is called. The process id also shown for every method call if the DBI trace level (not handle trace level) is set high enough to show the trace from the DBI's method dispatcher, e.g. >= 9.

PrintWarn (boolean, inherited)

The PrintWarn attribute controls the printing of warnings recorded by the driver. When set to a true value the DBI will check method calls to see if a warning condition has been set. If so, the DBI will effectively do a warn("$class $method warning: $DBI::errstr") where $class is the driver class and $method is the name of the method which failed. E.g.,

  DBD::Oracle::db execute warning: ... warning text here ...

By default, DBI->connect sets PrintWarn "on" if $^W is true, i.e., perl is running with warnings enabled.

If desired, the warnings can be caught and processed using a $SIG{__WARN__} handler or modules like CGI::Carp and CGI::ErrorWrap.

See also set_err for how warnings are recorded and HandleSetErr for how to influence it.

Fetching the full details of warnings can require an extra round-trip to the database server for some drivers. In which case the driver may opt to only fetch the full details of warnings if the PrintWarn attribute is true. If PrintWarn is false then these drivers should still indicate the fact that there were warnings by setting the warning string to, for example: "3 warnings".

PrintError (boolean, inherited)

The PrintError attribute can be used to force errors to generate warnings (using warn) in addition to returning error codes in the normal way. When set "on", any method which results in an error occuring will cause the DBI to effectively do a warn("$class $method failed: $DBI::errstr") where $class is the driver class and $method is the name of the method which failed. E.g.,

  DBD::Oracle::db prepare failed: ... error text here ...

By default, DBI->connect sets PrintError "on".

If desired, the warnings can be caught and processed using a $SIG{__WARN__} handler or modules like CGI::Carp and CGI::ErrorWrap.

RaiseError (boolean, inherited)

The RaiseError attribute can be used to force errors to raise exceptions rather than simply return error codes in the normal way. It is "off" by default. When set "on", any method which results in an error will cause the DBI to effectively do a die("$class $method failed: $DBI::errstr"), where $class is the driver class and $method is the name of the method that failed. E.g.,

  DBD::Oracle::db prepare failed: ... error text here ...

If you turn RaiseError on then you'd normally turn PrintError off. If PrintError is also on, then the PrintError is done first (naturally).

Typically RaiseError is used in conjunction with eval { ... } to catch the exception that's been thrown and followed by an if ($@) { ... } block to handle the caught exception. For example:

  eval {
    ...
    $sth->execute();
    ...
  };
  if ($@) {
    # $sth->err and $DBI::err will be true if error was from DBI
    warn $@; # print the error
    ... # do whatever you need to deal with the error
  }

In that eval block the $DBI::lasth variable can be useful for diagnosis and reporting if you can't be sure which handle triggered the error. For example, $DBI::lasth->{Type} and $DBI::lasth->{Statement}.

See also Transactions.

If you want to temporarily turn RaiseError off (inside a library function that is likely to fail, for example), the recommended way is like this:

  {
    local $h->{RaiseError};  # localize and turn off for this block
    ...
  }

The original value will automatically and reliably be restored by Perl, regardless of how the block is exited. The same logic applies to other attributes, including PrintError.

HandleError (code ref, inherited)

The HandleError attribute can be used to provide your own alternative behaviour in case of errors. If set to a reference to a subroutine then that subroutine is called when an error is detected (at the same point that RaiseError and PrintError are handled).

The subroutine is called with three parameters: the error message string that RaiseError and PrintError would use, the DBI handle being used, and the first value being returned by the method that failed (typically undef).

If the subroutine returns a false value then the RaiseError and/or PrintError attributes are checked and acted upon as normal.

For example, to die with a full stack trace for any error:

  use Carp;
  $h->{HandleError} = sub { confess(shift) };

Or to turn errors into exceptions:

  use Exception; # or your own favourite exception module
  $h->{HandleError} = sub { Exception->new('DBI')->raise($_[0]) };

It is possible to 'stack' multiple HandleError handlers by using closures:

  sub your_subroutine {
    my $previous_handler = $h->{HandleError};
    $h->{HandleError} = sub {
      return 1 if $previous_handler and &$previous_handler(@_);
      ... your code here ...
    };
  }

Using a my inside a subroutine to store the previous HandleError value is important. See the perlsub manpage and the perlref manpage for more information about closures.

It is possible for HandleError to alter the error message that will be used by RaiseError and PrintError if it returns false. It can do that by altering the value of $_[0]. This example appends a stack trace to all errors and, unlike the previous example using Carp::confess, this will work PrintError as well as RaiseError:

  $h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; };

It is also possible for HandleError to hide an error, to a limited degree, by using set_err to reset $DBI::err and $DBI::errstr, and altering the return value of the failed method. For example:

  $h->{HandleError} = sub {
    return 0 unless $_[0] =~ /^\S+ fetchrow_arrayref failed:/;
    return 0 unless $_[1]->err == 1234; # the error to 'hide'
    $h->set_err(undef,undef);   # turn off the error
    $_[2] = [ ... ];    # supply alternative return value
    return 1;
  };

This only works for methods which return a single value and is hard to make reliable (avoiding infinite loops, for example) and so isn't recommended for general use! If you find a good use for it then please let me know.

HandleSetErr (code ref, inherited)

The HandleSetErr attribute can be used to intercept the setting of handle err, errstr, and state values. If set to a reference to a subroutine then that subroutine is called whenever set_err() is called, typically by the driver or a subclass.

The subroutine is called with five arguments, the first five that were passed to set_err(): the handle, the err, errstr, and state values being set, and the method name. These can be altered by changing the values in the @_ array. The return value affects set_err() behaviour, see set_err for details.

It is possible to 'stack' multiple HandleSetErr handlers by using closures. See HandleError for an example.

The HandleSetErr and HandleError subroutines differ in subtle but significant ways. HandleError is only invoked at the point where the DBI is about to return to the application with err set true. It's not invoked by the failure of a method that's been called by another DBI method. HandleSetErr, on the other hand, is called whenever set_err() is called with a defined err value, even if false. So it's not just for errors, despite the name, but also warn and info states. The set_err() method, and thus HandleSetErr, may be called multiple times within a method and is usually invoked from deep within driver code.

In theory a driver can use the return value from HandleSetErr via set_err() to decide whether to continue or not. If set_err() returns an empty list, indicating that the HandleSetErr code has 'handled' the 'error', the driver could then continue instead of failing (if that's a reasonable thing to do). This isn't excepted to be common and any such cases should be clearly marked in the driver documentation and discussed on the dbi-dev mailing list.

The HandleSetErr attribute was added in DBI 1.41.

ErrCount (unsigned integer)

The ErrCount attribute is incremented whenever the set_err() method records an error. It isn't incremented by warnings or information states. It is not reset by the DBI at any time.

The ErrCount attribute was added in DBI 1.41. Older drivers may not have been updated to use set_err() to record errors and so this attribute may not be incremented when using them.

ShowErrorStatement (boolean, inherited)

The ShowErrorStatement attribute can be used to cause the relevant Statement text to be appended to the error messages generated by the RaiseError, PrintError, and PrintWarn attributes. Only applies to errors on statement handles plus the prepare(), do(), and the various select*() database handle methods. (The exact format of the appended text is subject to change.)

If $h->{ParamValues} returns a hash reference of parameter (placeholder) values then those are formatted and appended to the end of the Statement text in the error message.

TraceLevel (integer, inherited)

The TraceLevel attribute can be used as an alternative to the trace method to set the DBI trace level and trace flags for a specific handle. See TRACING for more details.

The TraceLevel attribute is especially useful combined with local to alter the trace settings for just a single block of code.

FetchHashKeyName (string, inherited)

The FetchHashKeyName attribute is used to specify whether the fetchrow_hashref() method should perform case conversion on the field names used for the hash keys. For historical reasons it defaults to 'NAME' but it is recommended to set it to 'NAME_lc' (convert to lower case) or 'NAME_uc' (convert to upper case) according to your preference. It can only be set for driver and database handles. For statement handles the value is frozen when prepare() is called.

ChopBlanks (boolean, inherited)

The ChopBlanks attribute can be used to control the trimming of trailing space characters from fixed width character (CHAR) fields. No other field types are affected, even where field values have trailing spaces.

The default is false (although it is possible that the default may change). Applications that need specific behaviour should set the attribute as needed.

Drivers are not required to support this attribute, but any driver which does not support it must arrange to return undef as the attribute value.

LongReadLen (unsigned integer, inherited)

The LongReadLen attribute may be used to control the maximum length of 'long' type fields (LONG, BLOB, CLOB, MEMO, etc.) which the driver will read from the database automatically when it fetches each row of data.

The LongReadLen attribute only relates to fetching and reading long values; it is not involved in inserting or updating them.

A value of 0 means not to automatically fetch any long data. Drivers may return undef or an empty string for long fields when LongReadLen is 0.

The default is typically 0 (zero) bytes but may vary between drivers. Applications fetching long fields should set this value to slightly larger than the longest long field value to be fetched.

Some databases return some long types encoded as pairs of hex digits. For these types, LongReadLen relates to the underlying data length and not the doubled-up length of the encoded string.

Changing the value of LongReadLen for a statement handle after it has been prepare'd will typically have no effect, so it's common to set LongReadLen on the $dbh before calling prepare.

For most drivers the value used here has a direct effect on the memory used by the statement handle while it's active, so don't be too generous. If you can't be sure what value to use you could execute an extra select statement to determine the longest value. For example:

  $dbh->{LongReadLen} = $dbh->selectrow_array(qq{
      SELECT MAX(OCTET_LENGTH(long_column_name))
      FROM table WHERE ...
  });
  $sth = $dbh->prepare(qq{
      SELECT long_column_name, ... FROM table WHERE ...
  });

You may need to take extra care if the table can be modified between the first select and the second being executed. You may also need to use a different function if OCTET_LENGTH() does not work for long types in your database. For example, for Sybase use DATALENGTH() and for Oracle use LENGTHB().

See also LongTruncOk for information on truncation of long types.

LongTruncOk (boolean, inherited)

The LongTruncOk attribute may be used to control the effect of fetching a long field value which has been truncated (typically because it's longer than the value of the LongReadLen attribute).

By default, LongTruncOk is false and so fetching a long value that needs to be truncated will cause the fetch to fail. (Applications should always be sure to check for errors after a fetch loop in case an error, such as a divide by zero or long field truncation, caused the fetch to terminate prematurely.)

If a fetch fails due to a long field truncation when LongTruncOk is false, many drivers will allow you to continue fetching further rows.

See also LongReadLen.

TaintIn (boolean, inherited)

If the TaintIn attribute is set to a true value and Perl is running in taint mode (e.g., started with the -T option), then all the arguments to most DBI method calls are checked for being tainted. This may change.

The attribute defaults to off, even if Perl is in taint mode. See the perlsec manpage for more about taint mode. If Perl is not running in taint mode, this attribute has no effect.

When fetching data that you trust you can turn off the TaintIn attribute, for that statement handle, for the duration of the fetch loop.

The TaintIn attribute was added in DBI 1.31.

TaintOut (boolean, inherited)

If the TaintOut attribute is set to a true value and Perl is running in taint mode (e.g., started with the -T option), then most data fetched from the database is considered tainted. This may change.

The attribute defaults to off, even if Perl is in taint mode. See the perlsec manpage for more about taint mode. If Perl is not running in taint mode, this attribute has no effect.

When fetching data that you trust you can turn off the TaintOut attribute, for that statement handle, for the duration of the fetch loop.

Currently only fetched data is tainted. It is possible that the results of other DBI method calls, and the value of fetched attributes, may also be tainted in future versions. That change may well break your applications unless you take great care now. If you use DBI Taint mode, please report your experience and any suggestions for changes.

The TaintOut attribute was added in DBI 1.31.

Taint (boolean, inherited)

The Taint attribute is a shortcut for TaintIn and TaintOut (it is also present for backwards compatibility).

Setting this attribute sets both TaintIn and TaintOut, and retrieving it returns a true value if and only if TaintIn and TaintOut are both set to true values.

Profile (inherited)

The Profile attribute enables the collection and reporting of method call timing statistics. See the the DBI::Profile manpage module documentation for much more detail.

The Profile attribute was added in DBI 1.24.

private_your_module_name_*

The DBI provides a way to store extra information in a DBI handle as "private" attributes. The DBI will allow you to store and retrieve any attribute which has a name starting with "private_".

It is strongly recommended that you use just one private attribute (e.g., use a hash ref) and give it a long and unambiguous name that includes the module or application name that the attribute relates to (e.g., "private_YourFullModuleName_thingy").

Because of the way the Perl tie mechanism works you cannot reliably use the ||= operator directly to initialise the attribute, like this:

  my $foo = $dbh->{private_yourmodname_foo} ||= { ... }; # WRONG

you should use a two step approach like this:

  my $foo = $dbh->{private_yourmodname_foo};
  $foo ||= $dbh->{private_yourmodname_foo} = { ... };

This attribute is primarily of interest to people sub-classing DBI.

DBI DATABASE HANDLE OBJECTS

This section covers the methods and attributes associated with database handles.

Database Handle Methods

The following methods are specified for DBI database handles:

clone
  $new_dbh = $dbh->clone();
  $new_dbh = $dbh->clone(\%attr);

The clone method duplicates the $dbh connection by connecting with the same parameters ($dsn, $user, $password) as originally used.

The attributes for the cloned connect are the same as those used for the original connect, with some other attribute merged over them depending on the \%attr parameter.

If \%attr is given then the attributes it contains are merged into the original attributes and override any with the same names. Effectively the same as doing:

  %attribues_used = ( %original_attributes, %attr );

If \%attr is not given then it defaults to a hash containing all the attributes in the attribute cache of $dbh excluding any non-code references, plus the main boolean attributes (RaiseError, PrintError, AutoCommit, etc.). This behaviour is subject to change.

The clone method can be used even if the database handle is disconnected.

The clone method was added in DBI 1.33. It is very new and likely to change.

data_sources
  @ary = $dbh->data_sources();
  @ary = $dbh->data_sources(\%attr);

Returns a list of data sources (databases) available via the $dbh driver's data_sources() method, plus any extra data sources that the driver can discover via the connected $dbh. Typically the extra data sources are other databases managed by the same server process that the $dbh is connected to.

Data sources are returned in a form suitable for passing to the connect method (that is, they will include the "dbi:$driver:" prefix).

The data_sources() method, for a $dbh, was added in DBI 1.38.

do
  $rows = $dbh->do($statement)           or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr)   or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr, @bind_values) or die ...

Prepare and execute a single statement. Returns the number of rows affected or undef on error. A return value of -1 means the number of rows is not known, not applicable, or not available.

This method is typically most useful for non-SELECT statements that either cannot be prepared in advance (due to a limitation of the driver) or do not need to be executed repeatedly. It should not be used for SELECT statements because it does not return a statement handle (so you can't fetch any data).

The default do method is logically similar to:

  sub do {
      my($dbh, $statement, $attr, @bind_values) = @_;
      my $sth = $dbh->prepare($statement, $attr) or return undef;
      $sth->execute(@bind_values) or return undef;
      my $rows = $sth->rows;
      ($rows == 0) ? "0E0" : $rows; # always return true if no error
  }

For example:

  my $rows_deleted = $dbh->do(q{
      DELETE FROM table
      WHERE status = ?
  }, undef, 'DONE') or die $dbh->errstr;

Using placeholders and @bind_values with the do method can be useful because it avoids the need to correctly quote any variables in the $statement. But if you'll be executing the statement many times then it's more efficient to prepare it once and call execute many times instead.

The q{...} style quoting used in this example avoids clashing with quotes that may be used in the SQL statement. Use the double-quote-like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

last_insert_id
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field);
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr);

Returns a value 'identifying' the row just inserted, if possible. Typically this would be a value assigned by the database server to a column with an auto_increment or serial type. Returns undef if the driver does not support the method or can't determine the value.

The $catalog, $schema, $table, and $field parameters may be required for some drivers (see below). If you don't know the parameter values and your driver does not need them, then use undef for each.

There are several caveats to be aware of with this method if you want to use it for portable applications:

* For some drivers the value may only available immediately after the insert statement has executed (e.g., mysql, Informix).

* For some drivers the $catalog, $schema, $table, and $field parameters are required, for others they are ignored (e.g., mysql).

* Drivers may return an indeterminate value if no insert has been performed yet.

* For some drivers the value may only be available if placeholders have not been used (e.g., Sybase, MS SQL). In this case the value returned would be from the last non-placeholder insert statement.

* Some drivers may need driver-specific hints about how to get the value. For example, being told the name of the database 'sequence' object that holds the value. Any such hints are passed as driver-specific attributes in the \%attr parameter.

* If the underlying database offers nothing better, then some drivers may attempt to implement this method by executing "select max($field) from $table". Drivers using any approach like this should issue a warning if AutoCommit is true because it is generally unsafe - another process may have modified the table between your insert and the select. For situations where you know it is safe, such as when you have locked the table, you can silence the warning by passing Warn => 0 in \%attr.

* If no insert has been performed yet, or the last insert failed, then the value is implementation defined.

Given all the caveats above, it's clear that this method must be used with care.

The last_insert_id method was added in DBI 1.38.

selectrow_array
  @row_ary = $dbh->selectrow_array($statement);
  @row_ary = $dbh->selectrow_array($statement, \%attr);
  @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_array into a single call. If called in a list context, it returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_array will return an empty list.

If called in a scalar context for a statement handle that has more than one column, it is undefined whether the driver will return the value of the first column or the last. So don't do that. Also, in a scalar context, an undef is returned if there are no more rows or if an error occurred. That undef can't be distinguished from an undef returned because the first field value was NULL. For these reasons you should exercise some caution if you use selectrow_array in a scalar context, or just don't do that.

selectrow_arrayref
  $ary_ref = $dbh->selectrow_arrayref($statement);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_arrayref into a single call. It returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_array will return undef.

selectrow_hashref
  $hash_ref = $dbh->selectrow_hashref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchrow_hashref into a single call. It returns the first row of data from the statement. The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped.

If any method fails, and RaiseError is not set, selectrow_hashref will return undef.

selectall_arrayref
  $ary_ref = $dbh->selectall_arrayref($statement);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute and fetchall_arrayref into a single call. It returns a reference to an array containing a reference to an array (or hash, see below) for each row of data fetched.

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

If RaiseError is not set and any method except fetchall_arrayref fails then selectall_arrayref will return undef; if fetchall_arrayref fails then it will return with whatever data has been fetched thus far. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

The fetchall_arrayref method called by selectall_arrayref supports a $max_rows parameter. You can specify a value for $max_rows by including a 'MaxRows' attribute in \%attr. In which case finish() is called for you after fetchall_arrayref() returns.

The fetchall_arrayref method called by selectall_arrayref also supports a $slice parameter. You can specify a value for $slice by including a 'Slice' or 'Columns' attribute in \%attr. The only difference between the two is that if Slice is not defined and Columns is an array ref, then the array is assumed to contain column index values (which count from 1), rather than perl array index values. In which case the array is copied and each value decremented before passing to /fetchall_arrayref.

You may often want to fetch an array of rows where each row is stored as a hash. That can be done simple using:

  my $emps = $dbh->selectall_arrayref(
      "SELECT ename FROM emp ORDER BY ename",
      { Slice => {} }
  );
  foreach my $emp ( @$emps ) {
      print "Employee: $emp->{ename}\n";
  }

Or, to fetch into an array instead of an array ref:

  @result = @{ $dbh->selectall_arrayref($sql, { Slice => {} }) };

See fetchall_arrayref method for more details.

=item C<selectall_hashref>
  $hash_ref = $dbh->selectall_hashref($statement, $key_field);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_values);

This utility method combines prepare, execute and fetchall_hashref into a single call. It returns a reference to a hash containing one entry, at most, for each row, as returned by fetchall_hashref().

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

The $key_field parameter defines which column, or columns, are used as keys in the returned hash. It can either be the name of a single field, or a reference to an array containing multiple field names. Using multiple names yields a tree of nested hashes.

If a row has the same key as an earlier row then it replaces the earlier row.

If any method except fetchrow_hashref fails, and RaiseError is not set, selectall_hashref will return undef. If fetchrow_hashref fails and RaiseError is not set, then it will return with whatever data it has fetched thus far. $DBI::err should be checked to catch that.

See fetchall_hashref() for more details.

selectcol_arrayref
  $ary_ref = $dbh->selectcol_arrayref($statement);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);

This utility method combines prepare, execute, and fetching one column from all the rows, into a single call. It returns a reference to an array containing the values of the first column from each row.

The $statement parameter can be a previously prepared statement handle, in which case the prepare is skipped. This is recommended if the statement is going to be executed many times.

If any method except fetch fails, and RaiseError is not set, selectcol_arrayref will return undef. If fetch fails and RaiseError is not set, then it will return with whatever data it has fetched thus far. $DBI::err should be checked to catch that.

The selectcol_arrayref method defaults to pushing a single column value (the first) from each row into the result array. However, it can also push another column, or even multiple columns per row, into the result array. This behaviour can be specified via a 'Columns' attribute which must be a ref to an array containing the column number or numbers to use. For example:

  # get array of id and name pairs:
  my $ary_ref = $dbh->selectcol_arrayref("select id, name from table", { Columns=>[1,2] });
  my %hash = @$ary_ref; # build hash from key-value pairs so $hash{$id} => name

You can specify a maximum number of rows to fetch by including a 'MaxRows' attribute in \%attr.

prepare
  $sth = $dbh->prepare($statement)          or die $dbh->errstr;
  $sth = $dbh->prepare($statement, \%attr)  or die $dbh->errstr;

Prepares a statement for later execution by the database engine and returns a reference to a statement handle object.

The returned statement handle can be used to get attributes of the statement and invoke the execute method. See Statement Handle Methods.

Drivers for engines without the concept of preparing a statement will typically just store the statement in the returned handle and process it when $sth->execute is called. Such drivers are unlikely to give much useful information about the statement, such as $sth->{NUM_OF_FIELDS}, until after $sth->execute has been called. Portable applications should take this into account.

In general, DBI drivers do not parse the contents of the statement (other than simply counting any Placeholders). The statement is passed directly to the database engine, sometimes known as pass-thru mode. This has advantages and disadvantages. On the plus side, you can access all the functionality of the engine being used. On the downside, you're limited if you're using a simple engine, and you need to take extra care if writing applications intended to be portable between engines.

Portable applications should not assume that a new statement can be prepared and/or executed while still fetching results from a previous statement.

Some command-line SQL tools use statement terminators, like a semicolon, to indicate the end of a statement. Such terminators should not normally be used with the DBI.

prepare_cached
  $sth = $dbh->prepare_cached($statement)
  $sth = $dbh->prepare_cached($statement, \%attr)
  $sth = $dbh->prepare_cached($statement, \%attr, $if_active)

Like prepare except that the statement handle returned will be stored in a hash associated with the $dbh. If another call is made to prepare_cached with the same $statement and %attr parameter values, then the corresponding cached $sth will be returned without contacting the database server.

The $if_active parameter lets you adjust the behaviour if an already cached statement handle is still Active. There are several alternatives:

  1. 0: A warning will be generated, and finish() will be called on the statement handle before it is returned. This is the default behaviour if $if_active is not passed.
  2. 1: finish() will be called on the statement handle, but the warning is suppressed.
  3. 2: Disables any checking.
  4. 3: The existing active statement handle will be removed from the cache and a new statement handle prepared and cached in its place. This is the safest option because it doesn't affect the state of the old handle, it just removes it from the cache. [Added in DBI 1.40]

Here are some examples of prepare_cached:

  sub insert_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $sql = sprintf "insert into %s (%s) values (%s)",
        $table, join(",", @fields), join(",", ("?")x@fields);
    my $sth = $dbh->prepare_cached($sql);
    return $sth->execute(@values);
  }

  sub search_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $qualifier = "";
    $qualifier = "where ".join(" and ", map { "$_=?" } @fields) if @fields;
    $sth = $dbh->prepare_cached("SELECT * FROM $table $qualifier");
    return $dbh->selectall_arrayref($sth, {}, @values);
  }

Caveat emptor: This caching can be useful in some applications, but it can also cause problems and should be used with care. Here is a contrived case where caching would cause a significant problem:

  my $sth = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
  $sth->execute(...);
  while (my $data = $sth->fetchrow_hashref) {

    # later, in some other code called within the loop...
    my $sth2 = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
    $sth2->execute(...);
    while (my $data2 = $sth2->fetchrow_arrayref) {
      do_stuff(...);
    }
      }

In this example, since both handles are preparing the exact same statement, $sth2 will not be its own statement handle, but a duplicate of $sth returned from the cache. The results will certainly not be what you expect. Typically the the inner fetch loop will work normally, fetching all the records and terminating when there are no more, but now $sth is the same as $sth2 the outer fetch loop will also terminate.

You'll know if you run into this problem because prepare_cached() will generate a warning by default (when $if_active is false).

The cache used by prepare_cached() is keyed by both the statement and any attributes so you can also avoid this issue by doing something like:

  $sth = $dbh->prepare_cached("...", { dbi_dummy => __FILE__.__LINE__ });

which will ensure that prepare_cached only returns statements cached by that line of code in that source file.

commit
  $rc  = $dbh->commit     or die $dbh->errstr;

Commit (make permanent) the most recent series of database changes if the database supports transactions and AutoCommit is off.

If AutoCommit is on, then calling commit will issue a "commit ineffective with AutoCommit" warning.

See also Transactions in the FURTHER INFORMATION section below.

rollback
  $rc  = $dbh->rollback   or die $dbh->errstr;

Rollback (undo) the most recent series of uncommitted database changes if the database supports transactions and AutoCommit is off.

If AutoCommit is on, then calling rollback will issue a "rollback ineffective with AutoCommit" warning.

See also Transactions in the FURTHER INFORMATION section below.

begin_work
  $rc  = $dbh->begin_work   or die $dbh->errstr;

Enable transactions (by turning AutoCommit off) until the next call to commit or rollback. After the next commit or rollback, AutoCommit will automatically be turned on again.

If AutoCommit is already off when begin_work is called then it does nothing except return an error. If the driver does not support transactions then when begin_work attempts to set AutoCommit off the driver will trigger a fatal error.

See also Transactions in the FURTHER INFORMATION section below.

disconnect
  $rc = $dbh->disconnect  or warn $dbh->errstr;

Disconnects the database from the database handle. disconnect is typically only used before exiting the program. The handle is of little use after disconnecting.

The transaction behaviour of the disconnect method is, sadly, undefined. Some database systems (such as Oracle and Ingres) will automatically commit any outstanding changes, but others (such as Informix) will rollback any outstanding changes. Applications not using AutoCommit should explicitly call commit or rollback before calling disconnect.

The database is automatically disconnected by the DESTROY method if still connected when there are no longer any references to the handle. The DESTROY method for each driver should implicitly call rollback to undo any uncommitted changes. This is vital behaviour to ensure that incomplete transactions don't get committed simply because Perl calls DESTROY on every object before exiting. Also, do not rely on the order of object destruction during "global destruction", as it is undefined.

Generally, if you want your changes to be commited or rolled back when you disconnect, then you should explicitly call commit or rollback before disconnecting.

If you disconnect from a database while you still have active statement handles (e.g., SELECT statement handles that may have more data to fetch), you will get a warning. The warning may indicate that a fetch loop terminated early, perhaps due to an uncaught error. To avoid the warning call the finish method on the active handles.

ping
  $rc = $dbh->ping;

Attempts to determine, in a reasonably efficient way, if the database server is still running and the connection to it is still working. Individual drivers should implement this function in the most suitable manner for their database engine.

The current default implementation always returns true without actually doing anything. Actually, it returns "0 but true" which is true but zero. That way you can tell if the return value is genuine or just the default. Drivers should override this method with one that does the right thing for their type of database.

Few applications would have direct use for this method. See the specialized Apache::DBI module for one example usage.

get_info
  $value = $dbh->get_info( $info_type );

Returns information about the implementation, i.e. driver and data source capabilities, restrictions etc. It returns undef for unknown or unimplemented information types. For example:

  $database_version  = $dbh->get_info(  18 ); # SQL_DBMS_VER
  $max_select_tables = $dbh->get_info( 106 ); # SQL_MAXIMUM_TABLES_IN_SELECT

See Standards Reference Information for more detailed information about the information types and their meanings and possible return values.

The DBI::Const::GetInfoType module exports a %GetInfoType hash that can be used to map info type names to numbers. For example:

  $database_version = $dbh->get_info( $GetInfoType{SQL_DBMS_VER} );

The names are a merging of the ANSI and ODBC standards (which differ in some cases). See the DBI::Const::GetInfoType manpage for more details.

Because some DBI methods make use of get_info(), drivers are strongly encouraged to support at least the following very minimal set of information types to ensure the DBI itself works properly:

 Type  Name                        Example A     Example B
 ----  --------------------------  ------------  ----------------
   17  SQL_DBMS_NAME               'ACCESS'      'Oracle'
   18  SQL_DBMS_VER                '03.50.0000'  '08.01.0721 ...'
   29  SQL_IDENTIFIER_QUOTE_CHAR   '`'           '"'
   41  SQL_CATALOG_NAME_SEPARATOR  '.'           '@'
  114  SQL_CATALOG_LOCATION        1             2
table_info
  $sth = $dbh->table_info( $catalog, $schema, $table, $type );
  $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );

Returns an active statement handle that can be used to fetch information about tables and views that exist in the database.

The arguments $catalog, $schema and $table may accept search patterns according to the database/driver, for example: $table = '%FOO%'; Remember that the underscore character ('_') is a search pattern that means match any character, so 'FOO_%' is the same as 'FOO%' and 'FOO_BAR%' will match names like 'FOO1BAR'.

The value of $type is a comma-separated list of one or more types of tables to be returned in the result set. Each value may optionally be quoted, e.g.:

  $type = "TABLE";
  $type = "'TABLE','VIEW'";

In addition the following special cases may also be supported by some drivers:

  • If the value of $catalog is '%' and $schema and $table name are empty strings, the result set contains a list of catalog names. For example:
      $sth = $dbh->table_info('%', '', '');
  • If the value of $schema is '%' and $catalog and $table are empty strings, the result set contains a list of schema names.
  • If the value of $type is '%' and $catalog, $schema, and $table are all empty strings, the result set contains a list of table types.

If your driver doesn't support one or more of the selection filter parameters then you may get back more than you asked for and can do the filtering yourself.

This method can be expensive, and can return a large amount of data. (For example, small Oracle installation returns over 2000 rows.) So it's a good idea to use the filters to limit the data as much as possible.

The statement handle returned has at least the following fields in the order show below. Other fields, after these, may also be present.

TABLE_CAT: Table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is usually the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The name of the schema containing the TABLE_NAME value. This field is NULL (undef) if not applicable to data source, and empty if not applicable to the table.

TABLE_NAME: Name of the table (or view, synonym, etc).

TABLE_TYPE: One of the following: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" or a type identifier that is specific to the data source.

REMARKS: A description of the table. May be NULL (undef).

Note that table_info might not return records for all tables. Applications can use any valid table regardless of whether it's returned by table_info.

See also tables, Catalog Methods and Standards Reference Information.

column_info
  $sth = $dbh->column_info( $catalog, $schema, $table, $column );

Returns an active statement handle that can be used to fetch information about columns in specified tables.

The arguments $schema, $table and $column may accept search patterns according to the database/driver, for example: $table = '%FOO%';

Note: The support for the selection criteria is driver specific. If the driver doesn't support one or more of them then you may get back more than you asked for and can do the filtering yourself.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier. Note: A driver may provide column metadata not only for base tables, but also for derived objects like SYNONYMS etc.

COLUMN_NAME: The column identifier.

DATA_TYPE: The concise data type code.

TYPE_NAME: A data source dependent data type name.

COLUMN_SIZE: The column size. This is the maximum length in characters for character data types, the number of digits or bits for numeric data types or the length in the representation of temporal types. See the relevant specifications for detailed information.

BUFFER_LENGTH: The length in bytes of transferred data.

DECIMAL_DIGITS: The total number of significant digits to the right of the decimal point.

NUM_PREC_RADIX: The radix for numeric precision. The value is 10 or 2 for numeric data types and NULL (undef) if not applicable.

NULLABLE: Indicates if a column can accept NULLs. The following values are defined:

  SQL_NO_NULLS          0
  SQL_NULLABLE          1
  SQL_NULLABLE_UNKNOWN  2

REMARKS: A description of the column.

COLUMN_DEF: The default value of the column.

SQL_DATA_TYPE: The SQL data type.

SQL_DATETIME_SUB: The subtype code for datetime and interval data types.

CHAR_OCTET_LENGTH: The maximum length in bytes of a character or binary data type column.

ORDINAL_POSITION: The column sequence number (starting with 1).

IS_NULLABLE: Indicates if the column can accept NULLs. Possible values are: 'NO', 'YES' and ''.

SQL/CLI defines the following additional columns:

  CHAR_SET_CAT
  CHAR_SET_SCHEM
  CHAR_SET_NAME
  COLLATION_CAT
  COLLATION_SCHEM
  COLLATION_NAME
  UDT_CAT
  UDT_SCHEM
  UDT_NAME
  DOMAIN_CAT
  DOMAIN_SCHEM
  DOMAIN_NAME
  SCOPE_CAT
  SCOPE_SCHEM
  SCOPE_NAME
  MAX_CARDINALITY
  DTD_IDENTIFIER
  IS_SELF_REF

Drivers capable of supplying any of those values should do so in the corresponding column and supply undef values for the others.

Drivers wishing to provide extra database/driver specific information should do so in extra columns beyond all those listed above, and use lowercase field names with the driver-specific prefix (i.e., 'ora_...'). Applications accessing such fields should do so by name and not by column number.

The result set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION.

Note: There is some overlap with statement attributes (in perl) and SQLDescribeCol (in ODBC). However, SQLColumns provides more metadata.

See also Catalog Methods and Standards Reference Information.

primary_key_info
  $sth = $dbh->primary_key_info( $catalog, $schema, $table );

Returns an active statement handle that can be used to fetch information about columns that make up the primary key for a table. The arguments don't accept search patterns (unlike table_info()).

For example:

  $sth = $dbh->primary_key_info( undef, $user, 'foo' );
  $data = $sth->fetchall_arrayref;

The statement handle will return one row per column, ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and KEY_SEQ. If there is no primary key then the statement handle will fetch no rows.

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier.

COLUMN_NAME: The column identifier.

KEY_SEQ: The column sequence number (starting with 1). Note: This field is named ORDINAL_POSITION in SQL/CLI.

PK_NAME: The primary key constraint identifier. This field is NULL (undef) if not applicable to the data source.

See also Catalog Methods and Standards Reference Information.

primary_key
  @key_column_names = $dbh->primary_key( $catalog, $schema, $table );

Simple interface to the primary_key_info() method. Returns a list of the column names that comprise the primary key of the specified table. The list is in primary key column sequence order. If there is no primary key then an empty list is returned.

foreign_key_info
  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table );

  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table
                               , \%attr );

Returns an active statement handle that can be used to fetch information about foreign keys in and/or referencing the specified table(s). The arguments don't accept search patterns (unlike table_info()).

$pk_catalog, $pk_schema, $pk_table identify the primary (unique) key table (PKT).

$fk_catalog, $fk_schema, $fk_table identify the foreign key table (FKT).

If both PKT and FKT are given, the function returns the foreign key, if any, in table FKT that refers to the primary (unique) key of table PKT. (Note: In SQL/CLI, the result is implementation-defined.)

If only PKT is given, then the result set contains the primary key of that table and all foreign keys that refer to it.

If only FKT is given, then the result set contains all foreign keys in that table and the primary keys to which they refer. (Note: In SQL/CLI, the result includes unique keys too.)

For example:

  $sth = $dbh->foreign_key_info( undef, $user, 'master');
  $sth = $dbh->foreign_key_info( undef, undef,   undef , undef, $user, 'detail');
  $sth = $dbh->foreign_key_info( undef, $user, 'master', undef, $user, 'detail');

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has the following fields in the order shown below. Because ODBC never includes unique keys, they define different columns in the result set than SQL/CLI. SQL/CLI column names are shown in parentheses.

PKTABLE_CAT ( UK_TABLE_CAT ): The primary (unique) key table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

PKTABLE_SCHEM ( UK_TABLE_SCHEM ): The primary (unique) key table schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

PKTABLE_NAME ( UK_TABLE_NAME ): The primary (unique) key table identifier.

PKCOLUMN_NAME (UK_COLUMN_NAME ): The primary (unique) key column identifier.

FKTABLE_CAT ( FK_TABLE_CAT ): The foreign key table catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

FKTABLE_SCHEM ( FK_TABLE_SCHEM ): The foreign key table schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

FKTABLE_NAME ( FK_TABLE_NAME ): The foreign key table identifier.

FKCOLUMN_NAME ( FK_COLUMN_NAME ): The foreign key column identifier.

KEY_SEQ ( ORDINAL_POSITION ): The column sequence number (starting with 1).

UPDATE_RULE ( UPDATE_RULE ): The referential action for the UPDATE rule. The following codes are defined:

  CASCADE              0
  RESTRICT             1
  SET NULL             2
  NO ACTION            3
  SET DEFAULT          4

DELETE_RULE ( DELETE_RULE ): The referential action for the DELETE rule. The codes are the same as for UPDATE_RULE.

FK_NAME ( FK_NAME ): The foreign key name.

PK_NAME ( UK_NAME ): The primary (unique) key name.

DEFERRABILITY ( DEFERABILITY ): The deferrability of the foreign key constraint. The following codes are defined:

  INITIALLY DEFERRED   5
  INITIALLY IMMEDIATE  6
  NOT DEFERRABLE       7

( UNIQUE_OR_PRIMARY ): This column is necessary if a driver includes all candidate (i.e. primary and alternate) keys in the result set (as specified by SQL/CLI). The value of this column is UNIQUE if the foreign key references an alternate key and PRIMARY if the foreign key references a primary key, or it may be undefined if the driver doesn't have access to the information.

See also Catalog Methods and Standards Reference Information.

statistics_info

Warning: This method is experimental and may change.

  $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick );

Returns an active statement handle that can be used to fetch statistical information about a table and its indexes.

The arguments don't accept search patterns (unlike table_info).

If the boolean argument $unique_only is true, only UNIQUE indexes will be returned in the result set, otherwise all indexes will be returned.

If the boolean argument $quick is set, the actual statistical information columns (CARDINALITY and PAGES) will only be returned if they are readily available from the server, and might not be current. Some databases may return stale statistics or no statistics at all with this flag set.

For example:

  $sth = $dbh->statistics_info( undef, $user, 'foo', 1, 1 );
  $data = $sth->fetchall_arrayref;

The statement handle will return at most one row per column name per index, plus at most one row for the entire table itself, ordered by NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, and ORDINAL_POSITION.

Note: The support for the selection criteria, such as $catalog, is driver specific. If the driver doesn't support catalogs and/or schemas, it may ignore these criteria.

The statement handle returned has at least the following fields in the order shown below. Other fields, after these, may also be present.

TABLE_CAT: The catalog identifier. This field is NULL (undef) if not applicable to the data source, which is often the case. This field is empty if not applicable to the table.

TABLE_SCHEM: The schema identifier. This field is NULL (undef) if not applicable to the data source, and empty if not applicable to the table.

TABLE_NAME: The table identifier.

NON_UNIQUE: Unique index indicator. Returns 0 for unique indexes, 1 for non-unique indexes

INDEX_QUALIFIER: Index qualifier identifier. The identifier that is used to qualify the index name when doing a DROP INDEX; NULL (undef) is returned if an index qualifier is not supported by the data source. If a non-NULL (defined) value is returned in this column, it must be used to qualify the index name on a DROP INDEX statement; otherwise, the TABLE_SCHEM should be used to qualify the index name.

INDEX_NAME: The index identifier.

TYPE: The type of information being returned. Can be any of the following values: 'table', 'btree', 'clustered', 'content', 'hashed', or 'other'.

In the case that this field is 'table', all fields other than TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TYPE, CARDINALITY, and PAGES will be NULL (undef).

ORDINAL_POSITION: Column sequence number (starting with 1).

COLUMN_NAME: The column identifier.

ASC_OR_DESC: Column sort sequence. A for Ascending, D for Descending, or NULL (undef) if not supported for this index.

CARDINALITY: Cardinality of the table or index. For indexes, this is the number of unique values in the index. For tables, this is the number of rows in the table. If not supported, the value will be NULL (undef).

PAGES: Number of storage pages used by this table or index. If not supported, the value will be NULL (undef).

FILTER_CONDITION: The index filter condition as a string. If the index is not a filtered index, or it cannot be determined whether the index is a filtered index, this value is NULL (undef). If the index is a filtered index, but the filter condition cannot be determined, this value is the empty string ''. Otherwise it will be the literal filter condition as a string, such as SALARY <= 4500.

See also Catalog Methods and Standards Reference Information.

tables
  @names = $dbh->tables( $catalog, $schema, $table, $type );
  @names = $dbh->tables;        # deprecated

Simple interface to table_info(). Returns a list of matching table names, possibly including a catalog/schema prefix.

See table_info for a description of the parameters.

If $dbh->get_info(29) returns true (29 is SQL_IDENTIFIER_QUOTE_CHAR) then the table names are constructed and quoted by quote_identifier to ensure they are usable even if they contain whitespace or reserved words etc. This means that the table names returned will include quote characters.

type_info_all
  $type_info_all = $dbh->type_info_all;

Returns a reference to an array which holds information about each data type variant supported by the database and driver. The array and its contents should be treated as read-only.

The first item is a reference to an 'index' hash of Name => Index pairs. The items following that are references to arrays, one per supported data type variant. The leading index hash defines the names and order of the fields within the arrays that follow it. For example:

  $type_info_all = [
    {   TYPE_NAME         => 0,
        DATA_TYPE         => 1,
        COLUMN_SIZE       => 2,     # was PRECISION originally
        LITERAL_PREFIX    => 3,
        LITERAL_SUFFIX    => 4,
        CREATE_PARAMS     => 5,
        NULLABLE          => 6,
        CASE_SENSITIVE    => 7,
        SEARCHABLE        => 8,
        UNSIGNED_ATTRIBUTE=> 9,
        FIXED_PREC_SCALE  => 10,    # was MONEY originally
        AUTO_UNIQUE_VALUE => 11,    # was AUTO_INCREMENT originally
        LOCAL_TYPE_NAME   => 12,
        MINIMUM_SCALE     => 13,
        MAXIMUM_SCALE     => 14,
        SQL_DATA_TYPE     => 15,
        SQL_DATETIME_SUB  => 16,
        NUM_PREC_RADIX    => 17,
        INTERVAL_PRECISION=> 18,
    },
    [ 'VARCHAR', SQL_VARCHAR,
        undef, "'","'", undef,0, 1,1,0,0,0,undef,1,255, undef
    ],
    [ 'INTEGER', SQL_INTEGER,
        undef,  "", "", undef,0, 0,1,0,0,0,undef,0,  0, 10
    ],
  ];

More than one row may have the same value in the DATA_TYPE field if there are different ways to spell the type name and/or there are variants of the type with different attributes (e.g., with and without AUTO_UNIQUE_VALUE set, with and without UNSIGNED_ATTRIBUTE, etc).

The rows are ordered by DATA_TYPE first and then by how closely each type maps to the corresponding ODBC SQL data type, closest first.

The meaning of the fields is described in the documentation for the type_info method.

An 'index' hash is provided so you don't need to rely on index values defined above. However, using DBD::ODBC with some old ODBC drivers may return older names, shown as comments in the example above. Another issue with the index hash is that the lettercase of the keys is not defined. It is usually uppercase, as show here, but drivers may return names with any lettercase.

Drivers are also free to return extra driver-specific columns of information - though it's recommended that they start at column index 50 to leave room for expansion of the DBI/ODBC specification.

The type_info_all() method is not normally used directly. The type_info method provides a more usable and useful interface to the data.

type_info
  @type_info = $dbh->type_info($data_type);

Returns a list of hash references holding information about one or more variants of $data_type. The list is ordered by DATA_TYPE first and then by how closely each type maps to the corresponding ODBC SQL data type, closest first. If called in a scalar context then only the first (best) element is returned.

If $data_type is undefined or SQL_ALL_TYPES, then the list will contain hashes for all data type variants supported by the database and driver.

If $data_type is an array reference then type_info returns the information for the first type in the array that has any matches.

The keys of the hash follow the same letter case conventions as the rest of the DBI (see Naming Conventions and Name Space). The following uppercase items should always exist, though may be undef:

TYPE_NAME (string)

Data type name for use in CREATE TABLE statements etc.

DATA_TYPE (integer)

SQL data type number.

COLUMN_SIZE (integer)

For numeric types, this is either the total number of digits (if the NUM_PREC_RADIX value is 10) or the total number of bits allowed in the column (if NUM_PREC_RADIX is 2).

For string types, this is the maximum size of the string in characters.

For date and interval types, this is the maximum number of characters needed to display the value.

LITERAL_PREFIX (string)

Characters used to prefix a literal. A typical prefix is "'" for characters, or possibly "0x" for binary values passed as hexadecimal. NULL (undef) is returned for data types for which this is not applicable.

LITERAL_SUFFIX (string)

Characters used to suffix a literal. Typically "'" for characters. NULL (undef) is returned for data types where this is not applicable.

CREATE_PARAMS (string)

Parameter names for data type definition. For example, CREATE_PARAMS for a DECIMAL would be "precision,scale" if the DECIMAL type should be declared as DECIMAL(precision,scale) where precision and scale are integer values. For a VARCHAR it would be "max length". NULL (undef) is returned for data types for which this is not applicable.

NULLABLE (integer)

Indicates whether the data type accepts a NULL value: 0 or an empty string = no, 1 = yes, 2 = unknown.

CASE_SENSITIVE (boolean)

Indicates whether the data type is case sensitive in collations and comparisons.

SEARCHABLE (integer)

Indicates how the data type can be used in a WHERE clause, as follows:

  0 - Cannot be used in a WHERE clause
  1 - Only with a LIKE predicate
  2 - All comparison operators except LIKE
  3 - Can be used in a WHERE clause with any comparison operator
UNSIGNED_ATTRIBUTE (boolean)

Indicates whether the data type is unsigned. NULL (undef) is returned for data types for which this is not applicable.

FIXED_PREC_SCALE (boolean)

Indicates whether the data type always has the same precision and scale (such as a money type). NULL (undef) is returned for data types for which this is not applicable.

AUTO_UNIQUE_VALUE (boolean)

Indicates whether a column of this data type is automatically set to a unique value whenever a new row is inserted. NULL (undef) is returned for data types for which this is not applicable.

LOCAL_TYPE_NAME (string)

Localized version of the TYPE_NAME for use in dialog with users. NULL (undef) is returned if a localized name is not available (in which case TYPE_NAME should be used).

MINIMUM_SCALE (integer)

The minimum scale of the data type. If a data type has a fixed scale, then MAXIMUM_SCALE holds the same value. NULL (undef) is returned for data types for which this is not applicable.

MAXIMUM_SCALE (integer)

The maximum scale of the data type. If a data type has a fixed scale, then MINIMUM_SCALE holds the same value. NULL (undef) is returned for data types for which this is not applicable.

SQL_DATA_TYPE (integer)

This column is the same as the DATA_TYPE column, except for interval and datetime data types. For interval and datetime data types, the SQL_DATA_TYPE field will return SQL_INTERVAL or SQL_DATETIME, and the SQL_DATETIME_SUB field below will return the subcode for the specific interval or datetime data type. If this field is NULL, then the driver does not support or report on interval or datetime subtypes.

SQL_DATETIME_SUB (integer)

For interval or datetime data types, where the SQL_DATA_TYPE field above is SQL_INTERVAL or SQL_DATETIME, this field will hold the subcode for the specific interval or datetime data type. Otherwise it will be NULL (undef).

Although not mentioned explicitly in the standards, it seems there is a simple relationship between these values:

  DATA_TYPE == (10 * SQL_DATA_TYPE) + SQL_DATETIME_SUB
NUM_PREC_RADIX (integer)

The radix value of the data type. For approximate numeric types, NUM_PREC_RADIX contains the value 2 and COLUMN_SIZE holds the number of bits. For exact numeric types, NUM_PREC_RADIX contains the value 10 and COLUMN_SIZE holds the number of decimal digits. NULL (undef) is returned either for data types for which this is not applicable or if the driver cannot report this information.

INTERVAL_PRECISION (integer)

The interval leading precision for interval types. NULL is returned either for data types for which this is not applicable or if the driver cannot report this information.

For example, to find the type name for the fields in a select statement you can do:

  @names = map { scalar $dbh->type_info($_)->{TYPE_NAME} } @{ $sth->{TYPE} }

Since DBI and ODBC drivers vary in how they map their types into the ISO standard types you may need to search for more than one type. Here's an example looking for a usable type to store a date:

  $my_date_type = $dbh->type_info( [ SQL_DATE, SQL_TIMESTAMP ] );

Similarly, to more reliably find a type to store small integers, you could use a list starting with SQL_SMALLINT, SQL_INTEGER, SQL_DECIMAL, etc.

See also Standards Reference Information.

quote
  $sql = $dbh->quote($value);
  $sql = $dbh->quote($value, $data_type);

Quote a string literal for use as a literal value in an SQL statement, by escaping any special characters (such as quotation marks) contained within the string and adding the required type of outer quotation marks.

  $sql = sprintf "SELECT foo FROM bar WHERE baz = %s",
                $dbh->quote("Don't");

For most database types, quote would return 'Don''t' (including the outer quotation marks).

An undefined $value value will be returned as the string NULL (without single quotation marks) to match how NULLs are represented in SQL.

If $data_type is supplied, it is used to try to determine the required quoting behaviour by using the information returned by type_info. As a special case, the standard numeric types are optimized to return $value without calling type_info.

Quote will probably not be able to deal with all possible input (such as binary data or data containing newlines), and is not related in any way with escaping or quoting shell meta-characters.

It is valid for the quote() method to return an SQL expression that evaluates to the desired string. For example:

  $quoted = $dbh->quote("one\ntwo\0three")

may return something like:

  CONCAT('one', CHAR(12), 'two', CHAR(0), 'three')

The quote() method should not be used with Placeholders and Bind Values.

quote_identifier
  $sql = $dbh->quote_identifier( $name );
  $sql = $dbh->quote_identifier( $catalog, $schema, $table, \%attr );

Quote an identifier (table name etc.) for use in an SQL statement, by escaping any special characters (such as double quotation marks) it contains and adding the required type of outer quotation marks.

Undefined names are ignored and the remainder are quoted and then joined together, typically with a dot (.) character. For example:

  $id = $dbh->quote_identifier( undef, 'Her schema', 'My table' );

would, for most database types, return "Her schema"."My table" (including all the double quotation marks).

If three names are supplied then the first is assumed to be a catalog name and special rules may be applied based on what get_info returns for SQL_CATALOG_NAME_SEPARATOR (41) and SQL_CATALOG_LOCATION (114). For example, for Oracle:

  $id = $dbh->quote_identifier( 'link', 'schema', 'table' );

would return "schema"."table"@"link".

take_imp_data
  $imp_data = $dbh->take_imp_data;

Leaves the $dbh in an almost dead, zombie-like, state and returns a binary string of raw implementation data from the driver which describes the current database connection. Effectively it detaches the underlying database API connection data from the DBI handle. After calling take_imp_data(), all other methods except DESTROY will generate a warning and return undef.

Why would you want to do this? You don't, forget I even mentioned it. Unless, that is, you're implementing something advanced like a multi-threaded connection pool. See the DBI::Pool manpage.

The returned $imp_data can be passed as a dbi_imp_data attribute to a later connect() call, even in a separate thread in the same process, where the driver can use it to 'adopt' the existing connection that the implementation data was taken from.

Some things to keep in mind...

* the $imp_data holds the only reference to the underlying database API connection data. That connection is still 'live' and won't be cleaned up properly unless the $imp_data is used to create a new $dbh which is then allowed to disconnect() normally.

* using the same $imp_data to create more than one other new $dbh at a time may well lead to unpleasant problems. Don't do that.

Any child statement handles are effectively destroyed when take_imp_data() is called.

The take_imp_data method was added in DBI 1.36 but wasn't useful till 1.49.

Database Handle Attributes

This section describes attributes specific to database handles.

Changes to these database handle attributes do not affect any other existing or future database handles.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver-specific attributes (which all have names starting with a lowercase letter).

Example:

  $h->{AutoCommit} = ...;       # set/write
  ... = $h->{AutoCommit};       # get/read
AutoCommit (boolean)

If true, then database changes cannot be rolled-back (undone). If false, then database changes automatically occur within a "transaction", which must either be committed or rolled back using the commit or rollback methods.

Drivers should always default to AutoCommit mode (an unfortunate choice largely forced on the DBI by ODBC and JDBC conventions.)

Attempting to set AutoCommit to an unsupported value is a fatal error. This is an important feature of the DBI. Applications that need full transaction behaviour can set $dbh->{AutoCommit} = 0 (or set AutoCommit to 0 via connect) without having to check that the value was assigned successfully.

For the purposes of this description, we can divide databases into three categories:

  Databases which don't support transactions at all.
  Databases in which a transaction is always active.
  Databases in which a transaction must be explicitly started (C<'BEGIN WORK'>).

* Databases which don't support transactions at all

For these databases, attempting to turn AutoCommit off is a fatal error. commit and rollback both issue warnings about being ineffective while AutoCommit is in effect.

* Databases in which a transaction is always active

These are typically mainstream commercial relational databases with "ANSI standard" transaction behaviour. If AutoCommit is off, then changes to the database won't have any lasting effect unless commit is called (but see also disconnect). If rollback is called then any changes since the last commit are undone.

If AutoCommit is on, then the effect is the same as if the DBI called commit automatically after every successful database operation. So calling commit or rollback explicitly while AutoCommit is on would be ineffective because the changes would have already been commited.

Changing AutoCommit from off to on will trigger a commit.

For databases which don't support a specific auto-commit mode, the driver has to commit each statement automatically using an explicit COMMIT after it completes successfully (and roll it back using an explicit ROLLBACK if it fails). The error information reported to the application will correspond to the statement which was executed, unless it succeeded and the commit or rollback failed.

* Databases in which a transaction must be explicitly started

For these databases, the intention is to have them act like databases in which a transaction is always active (as described above).

To do this, the driver will automatically begin an explicit transaction when AutoCommit is turned off, or after a commit or rollback (or when the application issues the next database operation after one of those events).

In this way, the application does not have to treat these databases as a special case.

See commit, disconnect and Transactions for other important notes about transactions.

Driver (handle)

Holds the handle of the parent driver. The only recommended use for this is to find the name of the driver using:

  $dbh->{Driver}->{Name}
Name (string)

Holds the "name" of the database. Usually (and recommended to be) the same as the "dbi:DriverName:..." string used to connect to the database, but with the leading "dbi:DriverName:" removed.

Statement (string, read-only)

Returns the statement string passed to the most recent prepare method called in this database handle, even if that method failed. This is especially useful where RaiseError is enabled and the exception handler checks $@ and sees that a 'prepare' method call failed.

RowCacheSize (integer)

A hint to the driver indicating the size of the local row cache that the application would like the driver to use for future SELECT statements. If a row cache is not implemented, then setting RowCacheSize is ignored and getting the value returns undef.

Some RowCacheSize values have special meaning, as follows:

  0 - Automatically determine a reasonable cache size for each C<SELECT>
  1 - Disable the local row cache
 >1 - Cache this many rows
 <0 - Cache as many rows that will fit into this much memory for each C<SELECT>.

Note that large cache sizes may require a very large amount of memory (cached rows * maximum size of row). Also, a large cache will cause a longer delay not only for the first fetch, but also whenever the cache needs refilling.

See also the RowsInCache statement handle attribute.

Username (string)

Returns the username used to connect to the database.

DBI STATEMENT HANDLE OBJECTS

This section lists the methods and attributes associated with DBI statement handles.

Statement Handle Methods

The DBI defines the following methods for use on DBI statement handles:

bind_param
  $sth->bind_param($p_num, $bind_value)
  $sth->bind_param($p_num, $bind_value, \%attr)
  $sth->bind_param($p_num, $bind_value, $bind_type)

The bind_param method takes a copy of $bind_value and associates it (binds it) with a placeholder, identified by $p_num, embedded in the prepared statement. Placeholders are indicated with question mark character (?). For example:

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("SELECT name, age FROM people WHERE name LIKE ?");
  $sth->bind_param(1, "John%");  # placeholders are numbered from 1
  $sth->execute;
  DBI::dump_results($sth);

See Placeholders and Bind Values for more information.

Data Types for Placeholders

The \%attr parameter can be used to hint at the data type the placeholder should have. This is rarely needed. Typically, the driver is only interested in knowing if the placeholder should be bound as a number or a string.

  $sth->bind_param(1, $value, { TYPE => SQL_INTEGER });

As a short-cut for the common case, the data type can be passed directly, in place of the \%attr hash reference. This example is equivalent to the one above:

  $sth->bind_param(1, $value, SQL_INTEGER);

The TYPE value indicates the standard (non-driver-specific) type for this parameter. To specify the driver-specific type, the driver may support a driver-specific attribute, such as { ora_type => 97 }.

The SQL_INTEGER and other related constants can be imported using

  use DBI qw(:sql_types);

See DBI Constants for more information.

The data type for a placeholder cannot be changed after the first bind_param call. In fact the whole \%attr parameter is 'sticky' in the sense that a driver only needs to consider the \%attr parameter for the first call, for a given $sth and parameter. After that the driver may ignore the \%attr parameter for that placeholder.

Perl only has string and number scalar data types. All database types that aren't numbers are bound as strings and must be in a format the database will understand except where the bind_param() TYPE attribute specifies a type that implies a particular format. For example, given:

  $sth->bind_param(1, $value, SQL_DATETIME);

the driver should expect $value to be in the ODBC standard SQL_DATETIME format, which is 'YYYY-MM-DD HH:MM:SS'. Similarly for SQL_DATE, SQL_TIME etc.

As an alternative to specifying the data type in the bind_param call, you can let the driver pass the value as the default type (VARCHAR). You can then use an SQL function to convert the type within the statement. For example:

  INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?))

The CONVERT function used here is just an example. The actual function and syntax will vary between different databases and is non-portable.

See also Placeholders and Bind Values for more information.

bind_param_inout
  $rc = $sth->bind_param_inout($p_num, \$bind_value, $max_len)  or die $sth->errstr;
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, \%attr)     or ...
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, $bind_type) or ...

This method acts like bind_param, but also enables values to be updated by the statement. The statement is typically a call to a stored procedure. The $bind_value must be passed as a reference to the actual value to be used.

Note that unlike bind_param, the $bind_value variable is not copied when bind_param_inout is called. Instead, the value in the variable is read at the time execute is called.

The additional $max_len parameter specifies the minimum amount of memory to allocate to $bind_value for the new value. If the value returned from the database is too big to fit, then the execution should fail. If unsure what value to use, pick a generous length, i.e., a length larger than the longest value that would ever be returned. The only cost of using a larger value than needed is wasted memory.

Undefined values or undef are used to indicate null values. See also Placeholders and Bind Values for more information.

bind_param_array
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, \%attr)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, $bind_type)

The bind_param_array method is used to bind an array of values to a placeholder embedded in the prepared statement which is to be executed with execute_array. For example:

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name, dept) VALUES(?, ?, ?)");
  $sth->bind_param_array(1, [ 'John', 'Mary', 'Tim' ]);
  $sth->bind_param_array(2, [ 'Booth', 'Todd', 'Robinson' ]);
  $sth->bind_param_array(3, "SALES"); # scalar will be reused for each row
  $sth->execute_array( { ArrayTupleStatus => \my @tuple_status } );

The %attr ($bind_type) argument is the same as defined for bind_param. Refer to bind_param for general details on using placeholders.

(Note that bind_param_array() can not be used to expand a placeholder into a list of values for a statement like "SELECT foo WHERE bar IN (?)". A placeholder can only ever represent one value per execution.)

Scalar values, including undef, may also be bound by bind_param_array. In which case the same value will be used for each execute call. Driver-specific implementations may behave differently, e.g., when binding to a stored procedure call, some databases may permit mixing scalars and arrays as arguments.

The default implementation provided by DBI (for drivers that have not implemented array binding) is to iteratively call execute for each parameter tuple provided in the bound arrays. Drivers may provide more optimized implementations using whatever bulk operation support the database API provides. The default driver behaviour should match the default DBI behaviour, but always consult your driver documentation as there may be driver specific issues to consider.

Note that the default implementation currently only supports non-data returning statements (INSERT, UPDATE, but not SELECT). Also, bind_param_array and bind_param cannot be mixed in the same statement execution, and bind_param_array must be used with execute_array; using bind_param_array will have no effect for execute.

The bind_param_array method was added in DBI 1.22.

execute
  $rv = $sth->execute                or die $sth->errstr;
  $rv = $sth->execute(@bind_values)  or die $sth->errstr;

Perform whatever processing is necessary to execute the prepared statement. An undef is returned if an error occurs. A successful execute always returns true regardless of the number of rows affected, even if it's zero (see below). It is always important to check the return status of execute (and most other DBI methods) for errors if you're not using RaiseError.

For a non-SELECT statement, execute returns the number of rows affected, if known. If no rows were affected, then execute returns "0E0", which Perl will treat as 0 but will regard as true. Note that it is not an error for no rows to be affected by a statement. If the number of rows affected is not known, then execute returns -1.

For SELECT statements, execute simply "starts" the query within the database engine. Use one of the fetch methods to retrieve the data after calling execute. The execute method does not return the number of rows that will be returned by the query (because most databases can't tell in advance), it simply returns a true value.

You can tell if the statement was a SELECT statement by checking if $sth->{NUM_OF_FIELDS} is greater than zero after calling execute.

If any arguments are given, then execute will effectively call bind_param for each value before executing the statement. Values bound in this way are usually treated as SQL_VARCHAR types unless the driver can determine the correct type (which is rare), or unless bind_param (or bind_param_inout) has already been used to specify the type.

If execute() is called on a statement handle that's still active ($sth->{Active} is true) then it should effectively call finish() to tidy up the previous execution results before starting this new execution.

execute_array
  $rv = $sth->execute_array(\%attr) or die $sth->errstr;
  $rv = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;

Execute the prepared statement once for each parameter tuple (group of values) provided either in the @bind_values, or by prior calls to bind_param_array, or via a reference passed in \%attr.

The execute_array() method returns the number of tuples executed, or undef if an error occured. Like execute(), a successful execute_array() always returns true regardless of the number of tuples executed, even if it's zero. See the ArrayTupleStatus attribute below for how to determine the execution status for each tuple.

Bind values for the tuples to be executed may be supplied row-wise by an ArrayTupleFetch attribute, or else column-wise in the @bind_values argument, or else column-wise by prior calls to bind_param_array.

Where column-wise binding is used (via the @bind_values argument or calls to bind_param_array()) the maximum number of elements in any one of the bound value arrays determines the number of tuples executed. Placeholders with fewer values in their parameter arrays are treated as if padded with undef (NULL) values.

If a scalar value is bound, instead of an array reference, it is treated as a variable length array with all elements having the same value. It's does not influence the number of tuples executed, so if all bound arrays have zero elements then zero tuples will be executed. If all bound values are scalars then one tuple will be executed, making execute_array() act just like execute().

The ArrayTupleFetch attribute can be used to specify a reference to a subroutine that will be called to provide the bind values for each tuple execution. The subroutine should return an reference to an array which contains the appropriate number of bind values, or return an undef if there is no more data to execute.

As a convienience, the ArrayTupleFetch attribute can also be used to specify a statement handle. In which case the fetchrow_arrayref() method will be called on the given statement handle in order to provide the bind values for each tuple execution.

The values specified via bind_param_array() or the @bind_values parameter may be either scalars, or arrayrefs. If any @bind_values are given, then execute_array will effectively call bind_param_array for each value before executing the statement. Values bound in this way are usually treated as SQL_VARCHAR types unless the driver can determine the correct type (which is rare), or unless bind_param, bind_param_inout, bind_param_array, or bind_param_inout_array has already been used to specify the type. See bind_param_array for details.

The ArrayTupleStatus attribute can be used to specify a reference to an array which will receive the execute status of each executed parameter tuple. Note the ArrayTupleStatus attribute was mandatory until DBI 1.38.

For tuples which are successfully executed, the element at the same ordinal position in the status array is the resulting rowcount. If the execution of a tuple causes an error, then the corresponding status array element will be set to a reference to an array containing the error code and error string set by the failed execution.

If any tuple execution returns an error, execute_array will return undef. In that case, the application should inspect the status array to determine which parameter tuples failed. Some databases may not continue executing tuples beyond the first failure. In this case the status array will either hold fewer elements, or the elements beyond the failure will be undef.

If all parameter tuples are successfully executed, execute_array returns the number tuples executed. If no tuples were executed, then execute_array() returns "0E0", just like execute() does, which Perl will treat as 0 but will regard as true.

For example:

  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name) VALUES (?, ?)");
  my $tuples = $sth->execute_array(
      { ArrayTupleStatus => \my @tuple_status },
      \@first_names,
      \@last_names,
  );
  if ($tuples) {
      print "Successfully inserted $tuples records\n";
  }
  else {
      for my $tuple (0..@last_names-1) {
          my $status = $tuple_status[$tuple];
          $status = [0, "Skipped"] unless defined $status;
          next unless ref $status;
          printf "Failed to insert (%s, %s): %s\n",
              $first_names[$tuple], $last_names[$tuple], $status->[1];
      }
  }

Support for data returning statements such as SELECT is driver-specific and subject to change. At present, the default implementation provided by DBI only supports non-data returning statements.

Transaction semantics when using array binding are driver and database specific. If AutoCommit is on, the default DBI implementation will cause each parameter tuple to be inidividually committed (or rolled back in the event of an error). If AutoCommit is off, the application is responsible for explicitly committing the entire set of bound parameter tuples. Note that different drivers and databases may have different behaviours when some parameter tuples cause failures. In some cases, the driver or database may automatically rollback the effect of all prior parameter tuples that succeeded in the transaction; other drivers or databases may retain the effect of prior successfully executed parameter tuples. Be sure to check your driver and database for its specific behaviour.

Note that, in general, performance will usually be better with AutoCommit turned off, and using explicit commit after each execute_array call.

The execute_array method was added in DBI 1.22, and ArrayTupleFetch was added in 1.36.

execute_for_fetch
  $rc = $sth->execute_for_fetch($fetch_tuple_sub);
  $rc = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);

The execute_for_fetch() method is used to perform bulk operations and is most often used via the execute_array() method, not directly.

The fetch subroutine, referenced by $fetch_tuple_sub, is expected to return a reference to an array (known as a 'tuple') or undef.

The execute_for_fetch() method calls $fetch_tuple_sub, without any parameters, until it returns a false value. Each tuple returned is used to provide bind values for an $sth->execute(@$tuple) call.

If there were any errors then undef is returned and the @tuple_status array can be used to discover which tuples failed and with what errors. If there were no errors then execute_for_fetch() returns the number of tuples executed. Like execute() and execute_array() a zero is returned as "0E0" so execute_for_fetch() is only false on error.

If \@tuple_status is passed then the execute_for_fetch method uses it to return status information. The tuple_status array holds one element per tuple. If the corresponding execute() did not fail then the element holds the return value from execute(), which is typically a row count. If the execute() did fail then the element holds a reference to an array containing ($sth->err, $sth->errstr, $sth->state).

Although each tuple returned by $fetch_tuple_sub is effectively used to call $sth->execute(@$tuple_array_ref) the exact timing may vary. Drivers are free to accumulate sets of tuples to pass to the database server in bulk group operations for more efficient execution. However, the $fetch_tuple_sub is specifically allowed to return the same array reference each time (which is what fetchrow_arrayref() usually does).

For example:

  my $sel = $dbh1->prepare("select foo, bar from table1");
  $sel->execute;

  my $ins = $dbh2->prepare("insert into table2 (foo, bar) values (?,?)");
  my $fetch_tuple_sub = sub { $sel->fetchrow_arrayref };

  my @tuple_status;
  $rc = $ins->execute_for_fetch($fetch_tuple_sub, \@tuple_status);
  my @errors = grep { ref $_ } @tuple_status;

Similarly, if you already have an array containing the data rows to be processed you'd use a subroutine to shift off and return each array ref in turn:

  $ins->execute_for_fetch( sub { shift @array_of_arrays }, \@tuple_status);

The execute_for_fetch method was added in DBI 1.38.

fetchrow_arrayref
  $ary_ref = $sth->fetchrow_arrayref;
  $ary_ref = $sth->fetch;    # alias

Fetches the next row of data and returns a reference to an array holding the field values. Null fields are returned as undef values in the array. This is the fastest way to fetch data, particularly if used with $sth->bind_columns.

If there are no more rows or if an error occurs, then fetchrow_arrayref returns an undef. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the undef returned was due to an error.

Note that the same array reference is returned for each fetch, so don't store the reference and then use it after a later fetch. Also, the elements of the array are also reused for each row, so take care if you want to take a reference to an element. See also bind_columns.

fetchrow_array
 @ary = $sth->fetchrow_array;

An alternative to fetchrow_arrayref. Fetches the next row of data and returns it as a list containing the field values. Null fields are returned as undef values in the list.

If there are no more rows or if an error occurs, then fetchrow_array returns an empty list. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the empty list returned was due to an error.

If called in a scalar context for a statement handle that has more than one column, it is undefined whether the driver will return the value of the first column or the last. So don't do that. Also, in a scalar context, an undef is returned if there are no more rows or if an error occurred. That undef can't be distinguished from an undef returned because the first field value was NULL. For these reasons you should exercise some caution if you use fetchrow_array in a scalar context.

fetchrow_hashref
 $hash_ref = $sth->fetchrow_hashref;
 $hash_ref = $sth->fetchrow_hashref($name);

An alternative to fetchrow_arrayref. Fetches the next row of data and returns it as a reference to a hash containing field name and field value pairs. Null fields are returned as undef values in the hash.

If there are no more rows or if an error occurs, then fetchrow_hashref returns an undef. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the undef returned was due to an error.

The optional $name parameter specifies the name of the statement handle attribute. For historical reasons it defaults to "NAME", however using either "NAME_lc" or "NAME_uc" is recomended for portability.

The keys of the hash are the same names returned by $sth->{$name}. If more than one field has the same name, there will only be one entry in the returned hash for those fields.

Because of the extra work fetchrow_hashref and Perl have to perform, it is not as efficient as fetchrow_arrayref or fetchrow_array.

By default a reference to a new hash is returned for each row. It is likely that a future version of the DBI will support an attribute which will enable the same hash to be reused for each row. This will give a significant performance boost, but it won't be enabled by default because of the risk of breaking old code.

fetchall_arrayref
  $tbl_ary_ref = $sth->fetchall_arrayref;
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice );
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows  );

The fetchall_arrayref method can be used to fetch all the data to be returned from a prepared and executed statement handle. It returns a reference to an array that contains one reference per row.

If there are no rows to return, fetchall_arrayref returns a reference to an empty array. If an error occurs, fetchall_arrayref returns the data fetched thus far, which may be none. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

If $slice is an array reference, fetchall_arrayref uses fetchrow_arrayref to fetch each row as an array ref. If the $slice array is not empty then it is used as a slice to select individual columns by perl array index number (starting at 0, unlike column and parameter numbers which start at 1).

With no parameters, or if $slice is undefined, fetchall_arrayref acts as if passed an empty array ref.

If $slice is a hash reference, fetchall_arrayref uses fetchrow_hashref to fetch each row as a hash reference. If the $slice hash is empty then fetchrow_hashref() is simply called in a tight loop and the keys in the hashes have whatever name lettercase is returned by default from fetchrow_hashref. (See FetchHashKeyName attribute.) If the $slice hash is not empty, then it is used as a slice to select individual columns by name. The values of the hash should be set to 1. The key names of the returned hashes match the letter case of the names in the parameter hash, regardless of the FetchHashKeyName attribute.

For example, to fetch just the first column of every row:

  $tbl_ary_ref = $sth->fetchall_arrayref([0]);

To fetch the second to last and last column of every row:

  $tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]);

To fetch all fields of every row as a hash ref:

  $tbl_ary_ref = $sth->fetchall_arrayref({});

To fetch only the fields called "foo" and "bar" of every row as a hash ref (with keys named "foo" and "BAR"):

  $tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, BAR=>1 });

The first two examples return a reference to an array of array refs. The third and forth return a reference to an array of hash refs.

If $max_rows is defined and greater than or equal to zero then it is used to limit the number of rows fetched before returning. fetchall_arrayref() can then be called again to fetch more rows. This is especially useful when you need the better performance of fetchall_arrayref() but don't have enough memory to fetch and return all the rows in one go. Here's an example:

  my $rows = []; # cache for batches of rows
  while( my $row = ( shift(@$rows) || # get row from cache, or reload cache:
                     shift(@{$rows=$sth->fetchall_arrayref(undef,10_000)||[]}) )
  ) {
    ...
  }

That can be the fastest way to fetch and process lots of rows using the DBI, but it depends on the relative cost of method calls vs memory allocation.

A standard while loop with column binding is often faster because the cost of allocating memory for the batch of rows is greater than the saving by reducing method calls. It's possible that the DBI may provide a way to reuse the memory of a previous batch in future, which would then shift the balance back towards fetchall_arrayref().

fetchall_hashref
  $hash_ref = $sth->fetchall_hashref($key_field);

The fetchall_hashref method can be used to fetch all the data to be returned from a prepared and executed statement handle. It returns a reference to a hash containing a key for each distinct value of the $key_field column that was fetched. For each key the corresponding value is a reference to a hash containing all the selected columns and their values, as returned by fetchrow_hashref().

If there are no rows to return, fetchall_hashref returns a reference to an empty hash. If an error occurs, fetchall_hashref returns the data fetched thus far, which may be none. You should check $sth->err afterwards (or use the RaiseError attribute) to discover if the data is complete or was truncated due to an error.

The $key_field parameter provides the name of the field that holds the value to be used for the key for the returned hash. For example:

  $dbh->{FetchHashKeyName} = 'NAME_lc';
  $sth = $dbh->prepare("SELECT FOO, BAR, ID, NAME, BAZ FROM TABLE");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref('id');
  print "Name for id 42 is $hash_ref->{42}->{name}\n";

The $key_field parameter can also be specified as an integer column number (counting from 1). If $key_field doesn't match any column in the statement, as a name first then as a number, then an error is returned.

For queries returing more than one 'key' column, you can specify multiple column names by passing $key_field as a reference to an array containing one or more key column names (or index numbers). For example:

  $sth = $dbh->prepare("SELECT foo, bar, baz FROM table");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref( [ qw(foo bar) ] );
  print "For foo 42 and bar 38, baz is $hash_ref->{42}->{38}->{baz}\n";

The fetchall_hashref() method is normally used only where the key fields values for each row are unique. If multiple rows are returned with the same values for the key fields then later rows overwrite earlier ones.

finish
  $rc  = $sth->finish;

Indicate that no more data will be fetched from this statement handle before it is either executed again or destroyed. The finish method is rarely needed, and frequently overused, but can sometimes be helpful in a few very specific situations to allow the server to free up resources (such as sort buffers).

When all the data has been fetched from a SELECT statement, the driver should automatically call finish for you. So you should not normally need to call it explicitly except when you know that you've not fetched all the data from a statement handle. The most common example is when you only want to fetch one row, but in that case the selectrow_* methods are usually better anyway. Adding calls to finish after each fetch loop is a common mistake, don't do it, it can mask genuine problems like uncaught fetch errors.

Consider a query like:

  SELECT foo FROM table WHERE bar=? ORDER BY foo

where you want to select just the first (smallest) "foo" value from a very large table. When executed, the database server will have to use temporary buffer space to store the sorted rows. If, after executing the handle and selecting one row, the handle won't be re-executed for some time and won't be destroyed, the finish method can be used to tell the server that the buffer space can be freed.

Calling finish resets the Active attribute for the statement. It may also make some statement handle attributes (such as NAME and TYPE) unavailable if they have not already been accessed (and thus cached).

The finish method does not affect the transaction status of the database connection. It has nothing to do with transactions. It's mostly an internal "housekeeping" method that is rarely needed. See also disconnect and the Active attribute.

The finish method should have been called discard_pending_rows.

rows
  $rv = $sth->rows;

Returns the number of rows affected by the last row affecting command, or -1 if the number of rows is not known or not available.

Generally, you can only rely on a row count after a non-SELECT execute (for some specific operations like UPDATE and DELETE), or after fetching all the rows of a SELECT statement.

For SELECT statements, it is generally not possible to know how many rows will be returned except by fetching them all. Some drivers will return the number of rows the application has fetched so far, but others may return -1 until all rows have been fetched. So use of the rows method or $DBI::rows with SELECT statements is not recommended.

One alternative method to get a row count for a SELECT is to execute a "SELECT COUNT(*) FROM ..." SQL statement with the same "..." as your query and then fetch the row count from that.

bind_col
  $rc = $sth->bind_col($column_number, \$var_to_bind);
  $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr );
  $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type );

Binds a Perl variable and/or some attributes to an output column (field) of a SELECT statement. Column numbers count up from 1. You do not need to bind output columns in order to fetch data. For maximum portability between drivers, bind_col() should be called after execute() and not before. See also bind_columns for an example.

The binding is performed at a low level using Perl aliasing. Whenever a row is fetched from the database $var_to_bind appears to be automatically updated simply because it now refers to the same memory location as the corresponding column value. This makes using bound variables very efficient. Binding a tied variable doesn't work, currently.

The bind_param method performs a similar, but opposite, function for input variables.

Data Types for Column Binding

The \%attr parameter can be used to hint at the data type formatting the column should have. For example, you can use:

  $sth->bind_col(1, undef, { TYPE => SQL_DATETIME });

to specify that you'd like the column (which presumably is some kind of datetime type) to be returned in the standard format for SQL_DATETIME, which is 'YYYY-MM-DD HH:MM:SS', rather than the native formatting the database would normally use.

There's no $var_to_bind in that example to emphasize the point that bind_col() works on the underlying column value and not just a particular bound variable.

As a short-cut for the common case, the data type can be passed directly, in place of the \%attr hash reference. This example is equivalent to the one above:

  $sth->bind_col(1, undef, SQL_DATETIME);

The TYPE value indicates the standard (non-driver-specific) type for this parameter. To specify the driver-specific type, the driver may support a driver-specific attribute, such as { ora_type => 97 }.

The SQL_DATETIME and other related constants can be imported using

  use DBI qw(:sql_types);

See DBI Constants for more information.

The data type for a bind variable cannot be changed after the first bind_col call. In fact the whole \%attr parameter is 'sticky' in the sense that a driver only needs to consider the \%attr parameter for the first call for a given $sth and column.

The TYPE attribute for bind_col() was first specified in DBI 1.41.

bind_columns
  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

Calls bind_col for each column of the SELECT statement.

The list of references should have the same number of elements as the number of columns in the SELECT statement. If it doesn't then bind_columns will bind the elements given, upto the number of columns, and then return an error.

For maximum portability between drivers, bind_columns() should be called after execute() and not before.

For example:

  $dbh->{RaiseError} = 1; # do this, or check every call for errors
  $sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
  $sth->execute;
  my ($region, $sales);

  # Bind Perl variables to columns:
  $rv = $sth->bind_columns(\$region, \$sales);

  # you can also use Perl's \(...) syntax (see perlref docs):
  #     $sth->bind_columns(\($region, $sales));

  # Column binding is the most efficient way to fetch data
  while ($sth->fetch) {
      print "$region: $sales\n";
  }

For compatibility with old scripts, the first parameter will be ignored if it is undef or a hash reference.

Here's a more fancy example that binds columns to the values inside a hash (thanks to H.Merijn Brand):

  $sth->execute;
  my %row;
  $sth->bind_columns( \( @row{ @{$sth->{NAME_lc} } } ));
  while ($sth->fetch) {
      print "$row{region}: $row{sales}\n";
  }
dump_results
  $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);

Fetches all the rows from $sth, calls DBI::neat_list for each row, and prints the results to $fh (defaults to STDOUT) separated by $lsep (default "\n"). $fsep defaults to ", " and $maxlen defaults to 35.

This method is designed as a handy utility for prototyping and testing queries. Since it uses neat_list to format and edit the string for reading by humans, it is not recomended for data transfer applications.

Statement Handle Attributes

This section describes attributes specific to statement handles. Most of these attributes are read-only.

Changes to these statement handle attributes do not affect any other existing or future statement handles.

Attempting to set or get the value of an unknown attribute generates a warning, except for private driver specific attributes (which all have names starting with a lowercase letter).

Example:

  ... = $h->{NUM_OF_FIELDS};    # get/read

Some drivers cannot provide valid values for some or all of these attributes until after $sth->execute has been successfully called. Typically the attribute will be undef in these situations.

Some attributes, like NAME, are not appropriate to some types of statement, like SELECT. Typically the attribute will be undef in these situations.

See also finish to learn more about the effect it may have on some attributes.

NUM_OF_FIELDS (integer, read-only)

Number of fields (columns) in the data the prepared statement may return. Statements that don't return rows of data, like DELETE and CREATE set NUM_OF_FIELDS to 0 (though it may be undef in some drivers).

NUM_OF_PARAMS (integer, read-only)

The number of parameters (placeholders) in the prepared statement. See SUBSTITUTION VARIABLES below for more details.

NAME (array-ref, read-only)

Returns a reference to an array of field names for each column. The names may contain spaces but should not be truncated or have any trailing space. Note that the names have the letter case (upper, lower or mixed) as returned by the driver being used. Portable applications should use NAME_lc or NAME_uc.

  print "First column name: $sth->{NAME}->[0]\n";
NAME_lc (array-ref, read-only)

Like NAME but always returns lowercase names.

NAME_uc (array-ref, read-only)

Like NAME but always returns uppercase names.

NAME_hash (hash-ref, read-only)
NAME_lc_hash (hash-ref, read-only)
NAME_uc_hash (hash-ref, read-only)

The NAME_hash, NAME_lc_hash, and NAME_uc_hash attributes return column name information as a reference to a hash.

The keys of the hash are the names of the columns. The letter case of the keys corresponds to the letter case returned by the NAME, NAME_lc, and NAME_uc attributes respectively (as described above).

The value of each hash entry is the perl index number of the corresponding column (counting from 0). For example:

  $sth = $dbh->prepare("select Id, Name from table");
  $sth->execute;
  @row = $sth->fetchrow_array;
  print "Name $row[ $sth->{NAME_lc_hash}{name} ]\n";
TYPE (array-ref, read-only)

Returns a reference to an array of integer values for each column. The value indicates the data type of the corresponding column.

The values correspond to the international standards (ANSI X3.135 and ISO/IEC 9075) which, in general terms, means ODBC. Driver-specific types that don't exactly match standard types should generally return the same values as an ODBC driver supplied by the makers of the database. That might include private type numbers in ranges the vendor has officially registered with the ISO working group:

  ftp://sqlstandards.org/SC32/SQL_Registry/

Where there's no vendor-supplied ODBC driver to be compatible with, the DBI driver can use type numbers in the range that is now officially reserved for use by the DBI: -9999 to -9000.

All possible values for TYPE should have at least one entry in the output of the type_info_all method (see type_info_all).

PRECISION (array-ref, read-only)

Returns a reference to an array of integer values for each column.

For numeric columns, the value is the maximum number of digits (without considering a sign character or decimal point). Note that the "display size" for floating point types (REAL, FLOAT, DOUBLE) can be up to 7 characters greater than the precision (for the sign + decimal point + the letter E + a sign + 2 or 3 digits).

For any character type column the value is the OCTET_LENGTH, in other words the number of bytes, not characters.

(More recent standards refer to this as COLUMN_SIZE but we stick with PRECISION for backwards compatibility.)

SCALE (array-ref, read-only)

Returns a reference to an array of integer values for each column. NULL (undef) values indicate columns where scale is not applicable.

NULLABLE (array-ref, read-only)

Returns a reference to an array indicating the possibility of each column returning a null. Possible values are 0 (or an empty string) = no, 1 = yes, 2 = unknown.

  print "First column may return NULL\n" if $sth->{NULLABLE}->[0];
CursorName (string, read-only)

Returns the name of the cursor associated with the statement handle, if available. If not available or if the database driver does not support the "where current of ..." SQL syntax, then it returns undef.

Database (dbh, read-only)

Returns the parent $dbh of the statement handle.

ParamValues (hash ref, read-only)

Returns a reference to a hash containing the values currently bound to placeholders. The keys of the hash are the 'names' of the placeholders, typically integers starting at 1. Returns undef if not supported by the driver.

See ShowErrorStatement for an example of how this is used.

If the driver supports ParamValues but no values have been bound yet then the driver should return a hash with placeholders names in the keys but all the values undef, but some drivers may return a ref to an empty hash.

It is possible that the values in the hash returned by ParamValues are not exactly the same as those passed to bind_param() or execute(). The driver may have slightly modified values in some way based on the TYPE the value was bound with. For example a floating point value bound as an SQL_INTEGER type may be returned as an integer. The values returned by ParamValues can be passed to another bind_param() method with the same TYPE and will be seen by the database as the same value.

It is also possible that the keys in the hash returned by ParamValues are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

The ParamValues attribute was added in DBI 1.28.

ParamArrays (hash ref, read-only)

Returns a reference to a hash containing the values currently bound to placeholders with execute_array or bind_param_array. The keys of the hash are the 'names' of the placeholders, typically integers starting at 1. Returns undef if not supported by the driver or no arrays of parameters are bound.

Each key value is an array reference containing a list of the bound parameters for that column.

For example:

  $sth = $dbh->prepare("INSERT INTO staff (id, name) values (?,?)");
  $sth->execute_array({},[1,2], ['fred','dave']);
  if ($sth->{ParamArrays}) {
      foreach $param (keys %{$sth->{ParamArrays}}) {
          printf "Parameters for %s : %s\n", $param,
          join(",", @{$sth->{ParamArrays}->{$param}});
      }
  }

It is possible that the values in the hash returned by ParamArrays are not exactly the same as those passed to bind_param_array or execute_array. The driver may have slightly modified values in some way based on the TYPE the value was bound with. For example a floating point value bound as an SQL_INTEGER type may be returned as an integer.

It is also possible that the keys in the hash returned by ParamArrays are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

ParamTypes (hash ref, read-only)

Returns a reference to a hash containing the type information currently bound to placeholders. The keys of the hash are the 'names' of the placeholders: either integers starting at 1, or, for drivers that support named placeholders, the actual parameter name string. The hash values are hashrefs of type information in the same form as that provided to the various bind_param() methods (See Data Types for Placeholders for the format and values), plus anything else that was passed as the third argument to bind_param(). Returns undef if not supported by the driver.

If the driver supports ParamTypes, but no values have been bound yet, then the driver should return a hash with the placeholder name keys, but all the values undef; however, some drivers may return a ref to an empty hash, or, alternately, may provide type information supplied by the database (only a few databases can do that).

It is possible that the values in the hash returned by ParamTypes are not exactly the same as those passed to bind_param() or execute(). The driver may have modified the type information in some way based on the bound values, other hints provided by the prepare()'d SQL statement, or alternate type mappings required by the driver or target database system.

It is also possible that the keys in the hash returned by ParamTypes are not exactly the same as those implied by the prepared statement. For example, DBD::Oracle translates '?' placeholders into ':pN' where N is a sequence number starting at 1.

The ParamTypes attribute was added in DBI 1.49. Implementation is the responsibility of individual drivers; the DBI layer default implementation simply returns undef.

Statement (string, read-only)

Returns the statement string passed to the prepare method.

RowsInCache (integer, read-only)

If the driver supports a local row cache for SELECT statements, then this attribute holds the number of un-fetched rows in the cache. If the driver doesn't, then it returns undef. Note that some drivers pre-fetch rows on execute, whereas others wait till the first fetch.

See also the RowCacheSize database handle attribute.

OTHER METHODS

install_method
    DBD::Foo::db->install_method($method_name, \%attr);

Installs the driver-private method named by $method_name into the DBI method dispatcher so it can be called directly, avoiding the need to use the func() method.

It is called as a static method on the driver class to which the method belongs. The method name must begin with the corresponding registered driver-private prefix. For example, for DBD::Oracle $method_name must being with 'ora_', and for DBD::AnyData it must begin with 'ad_'.

The attributes can be used to provide fine control over how the DBI dispatcher handles the dispatching of the method. However, at this point, it's undocumented and very liable to change. (Volunteers to polish up and document the interface are very welcome to get in touch via dbi-dev@perl.org)

Methods installed using install_method default to the standard error handling behaviour for DBI methods: clearing err and errstr before calling the method, and checking for errors to trigger RaiseError etc. on return. This differs from the default behaviour of func().

Note for driver authors: The DBD::Foo::xx->install_method call won't work until the class-hierarchy has been setup. Normally the DBI looks after that just after the driver is loaded. This means install_method() can't be called at the time the driver is loaded unless the class-hierarchy is set up first. The way to do that is to call the setup_driver() method:

    DBI->setup_driver('DBD::Foo');

before using install_method().

FURTHER INFORMATION

Catalog Methods

An application can retrieve metadata information from the DBMS by issuing appropriate queries on the views of the Information Schema. Unfortunately, INFORMATION_SCHEMA views are seldom supported by the DBMS. Special methods (catalog methods) are available to return result sets for a small but important portion of that metadata:

  column_info
  foreign_key_info
  primary_key_info
  table_info
  statistics_info

All catalog methods accept arguments in order to restrict the result sets. Passing undef to an optional argument does not constrain the search for that argument. However, an empty string ('') is treated as a regular search criteria and will only match an empty value.

Note: SQL/CLI and ODBC differ in the handling of empty strings. An empty string will not restrict the result set in SQL/CLI.

Most arguments in the catalog methods accept only ordinary values, e.g. the arguments of primary_key_info(). Such arguments are treated as a literal string, i.e. the case is significant and quote characters are taken literally.

Some arguments in the catalog methods accept search patterns (strings containing '_' and/or '%'), e.g. the $table argument of column_info(). Passing '%' is equivalent to leaving the argument undef.

Caveat: The underscore ('_') is valid and often used in SQL identifiers. Passing such a value to a search pattern argument may return more rows than expected! To include pattern characters as literals, they must be preceded by an escape character which can be achieved with

  $esc = $dbh->get_info( 14 );  # SQL_SEARCH_PATTERN_ESCAPE
  $search_pattern =~ s/([_%])/$esc$1/g;

The ODBC and SQL/CLI specifications define a way to change the default behaviour described above: All arguments (except list value arguments) are treated as identifier if the SQL_ATTR_METADATA_ID attribute is set to SQL_TRUE. Quoted identifiers are very similar to ordinary values, i.e. their body (the string within the quotes) is interpreted literally. Unquoted identifiers are compared in UPPERCASE.

The DBI (currently) does not support the SQL_ATTR_METADATA_ID attribute, i.e. it behaves like an ODBC driver where SQL_ATTR_METADATA_ID is set to SQL_FALSE.

Transactions

Transactions are a fundamental part of any robust database system. They protect against errors and database corruption by ensuring that sets of related changes to the database take place in atomic (indivisible, all-or-nothing) units.

This section applies to databases that support transactions and where AutoCommit is off. See AutoCommit for details of using AutoCommit with various types of databases.

The recommended way to implement robust transactions in Perl applications is to use RaiseError and eval { ... } (which is very fast, unlike eval "..."). For example:

  $dbh->{AutoCommit} = 0;  # enable transactions, if possible
  $dbh->{RaiseError} = 1;
  eval {
      foo(...)        # do lots of work here
      bar(...)        # including inserts
      baz(...)        # and updates
      $dbh->commit;   # commit the changes if we get this far
  };
  if ($@) {
      warn "Transaction aborted because $@";
      # now rollback to undo the incomplete changes
      # but do it in an eval{} as it may also fail
      eval { $dbh->rollback };
      # add other application on-error-clean-up code here
  }

If the RaiseError attribute is not set, then DBI calls would need to be manually checked for errors, typically like this:

  $h->method(@args) or die $h->errstr;

With RaiseError set, the DBI will automatically die if any DBI method call on that handle (or a child handle) fails, so you don't have to test the return value of each method call. See RaiseError for more details.

A major advantage of the eval approach is that the transaction will be properly rolled back if any code (not just DBI calls) in the inner application dies for any reason. The major advantage of using the $h->{RaiseError} attribute is that all DBI calls will be checked automatically. Both techniques are strongly recommended.

After calling commit or rollback many drivers will not let you fetch from a previously active SELECT statement handle that's a child of the same database handle. A typical way round this is to connect the the database twice and use one connection for SELECT statements.

See AutoCommit and disconnect for other important information about transactions.

Handling BLOB / LONG / Memo Fields

Many databases support "blob" (binary large objects), "long", or similar datatypes for holding very long strings or large amounts of binary data in a single field. Some databases support variable length long values over 2,000,000,000 bytes in length.

Since values of that size can't usually be held in memory, and because databases can't usually know in advance the length of the longest long that will be returned from a SELECT statement (unlike other data types), some special handling is required.

In this situation, the value of the $h->{LongReadLen} attribute is used to determine how much buffer space to allocate when fetching such fields. The $h->{LongTruncOk} attribute is used to determine how to behave if a fetched value can't fit into the buffer.

See the description of LongReadLen for more information.

When trying to insert long or binary values, placeholders should be used since there are often limits on the maximum size of an INSERT statement and the quote method generally can't cope with binary data. See Placeholders and Bind Values.

Simple Examples

Here's a complete example program to select and fetch some data:

  my $data_source = "dbi::DriverName:db_name";
  my $dbh = DBI->connect($data_source, $user, $password)
      or die "Can't connect to $data_source: $DBI::errstr";

  my $sth = $dbh->prepare( q{
          SELECT name, phone
          FROM mytelbook
  }) or die "Can't prepare statement: $DBI::errstr";

  my $rc = $sth->execute
      or die "Can't execute statement: $DBI::errstr";

  print "Query will return $sth->{NUM_OF_FIELDS} fields.\n\n";
  print "Field names: @{ $sth->{NAME} }\n";

  while (($name, $phone) = $sth->fetchrow_array) {
      print "$name: $phone\n";
  }
  # check for problems which may have terminated the fetch early
  die $sth->errstr if $sth->err;

  $dbh->disconnect;

Here's a complete example program to insert some data from a file. (This example uses RaiseError to avoid needing to check each call).

  my $dbh = DBI->connect("dbi:DriverName:db_name", $user, $password, {
      RaiseError => 1, AutoCommit => 0
  });

  my $sth = $dbh->prepare( q{
      INSERT INTO table (name, phone) VALUES (?, ?)
  });

  open FH, "<phone.csv" or die "Unable to open phone.csv: $!";
  while (<FH>) {
      chomp;
      my ($name, $phone) = split /,/;
      $sth->execute($name, $phone);
  }
  close FH;

  $dbh->commit;
  $dbh->disconnect;

Here's how to convert fetched NULLs (undefined values) into empty strings:

  while($row = $sth->fetchrow_arrayref) {
    # this is a fast and simple way to deal with nulls:
    foreach (@$row) { $_ = '' unless defined }
    print "@$row\n";
  }

The q{...} style quoting used in these examples avoids clashing with quotes that may be used in the SQL statement. Use the double-quote like qq{...} operator if you want to interpolate variables into the string. See Quote and Quote-like Operators in the perlop manpage for more details.

Threads and Thread Safety

Perl 5.7 and later support a new threading model called iThreads. (The old "5.005 style" threads are not supported by the DBI.)

In the iThreads model each thread has it's own copy of the perl interpreter. When a new thread is created the original perl interpreter is 'cloned' to create a new copy for the new thread.

If the DBI and drivers are loaded and handles created before the thread is created then it will get a cloned copy of the DBI, the drivers and the handles.

However, the internal pointer data within the handles will refer to the DBI and drivers in the original interpreter. Using those handles in the new interpreter thread is not safe, so the DBI detects this and croaks on any method call using handles that don't belong to the current thread (except for DESTROY).

Because of this (possibly temporary) restriction, newly created threads must make their own connctions to the database. Handles can't be shared across threads.

But BEWARE, some underlying database APIs (the code the DBD driver uses to talk to the database, often supplied by the database vendor) are not thread safe. If it's not thread safe, then allowing more than one thread to enter the code at the same time may cause subtle/serious problems. In some cases allowing more than one thread to enter the code, even if not at the same time, can cause problems. You have been warned.

Using DBI with perl threads is not yet recommended for production environments. For more information see http://www.perlmonks.org/index.pl

Note: There is a bug in perl 5.8.2 when configured with threads and debugging enabled (bug #24463) which causes a DBI test to fail.

Signal Handling and Canceling Operations

[The following only applies to systems with unix-like signal handling. I'd welcome additions for other systems, especially Windows.]

The first thing to say is that signal handling in Perl versions less than 5.8 is not safe. There is always a small risk of Perl crashing and/or core dumping when, or after, handling a signal because the signal could arrive and be handled while internal data structures are being changed. If the signal handling code used those same internal data structures it could cause all manner of subtle and not-so-subtle problems. The risk was reduced with 5.4.4 but was still present in all perls up through 5.8.0.

Beginning in perl 5.8.0 perl implements 'safe' signal handling if your system has the POSIX sigaction() routine. Now when a signal is delivered perl just makes a note of it but does not run the %SIG handler. The handling is 'defered' until a 'safe' moment.

Although this change made signal handling safe, it also lead to a problem with signals being defered for longer than you'd like. If a signal arrived while executing a system call, such as waiting for data on a network connection, the signal is noted and then the system call that was executing returns with an EINTR error code to indicate that it was interrupted. All fine so far.

The problem comes when the code that made the system call sees the EINTR code and decides it's going to call it again. Perl doesn't do that, but database code sometimes does. If that happens then the signal handler doesn't get called untill later. Maybe much later.

Fortunately there are ways around this which we'll discuss below. Unfortunately they make signals unsafe again.

The two most common uses of signals in relation to the DBI are for canceling operations when the user types Ctrl-C (interrupt), and for implementing a timeout using alarm() and $SIG{ALRM}.

Cancel

The DBI provides a cancel method for statement handles. The cancel method should abort the current operation and is designed to be called from a signal handler. For example:

  $SIG{INT} = sub { $sth->cancel };

However, few drivers implement this (the DBI provides a default method that just returns undef) and, even if implemented, there is still a possibility that the statement handle, and even the parent database handle, will not be usable afterwards.

If cancel returns true, then it has successfully invoked the database engine's own cancel function. If it returns false, then cancel failed. If it returns undef, then the database driver does not have cancel implemented.

Timeout

The traditional way to implement a timeout is to set $SIG{ALRM} to refer to some code that will be executed when an ALRM signal arrives and then to call alarm($seconds) to schedule an ALRM signal to be delivered $seconds in the future. For example:

  eval {
    local $SIG{ALRM} = sub { die "TIMEOUT\n" };
    alarm($seconds);
    ... code to execute with timeout here ...
    alarm(0);  # cancel alarm (if code ran fast)
  };
  alarm(0);    # cancel alarm (if eval failed)
  if ( $@ eq "TIMEOUT" ) { ... }

Unfortunately, as described above, this won't always work as expected, depending on your perl version and the underlying database code.

With Oracle for instance (DBD::Oracle), if the system which hosts the database is down the DBI->connect() call will hang for several minutes before returning an error.

The solution on these systems is to use the POSIX::sigaction() routine to gain low level access to how the signal handler is installed.

The code would look something like this (for the DBD-Oracle connect()):

   use POSIX ':signal_h';

   my $mask = POSIX::SigSet->new( SIGALRM ); # signals to mask in the handler
   my $action = POSIX::SigAction->new(
       sub { die "connect timeout" },        # the handler code ref
       $mask,
       # not using (perl 5.8.2 and later) 'safe' switch or sa_flags
   );
   my $oldaction = POSIX::SigAction->new();
   sigaction( 'ALRM', $action, $oldaction );
   my $dbh;
   eval {
      alarm(5); # seconds before time out
      $dbh = DBI->connect("dbi:Oracle:$dsn" ... );
      alarm(0); # cancel alarm (if connect worked fast)
   };
   alarm(0);    # cancel alarm (if eval failed)
   sigaction( 'ALRM', $oldaction );  # restore original signal handler
   if ( $@ ) ....

Similar techniques can be used for canceling statement execution.

Unfortunately, this solution is somewhat messy, and it does not work with perl versions less than perl 5.8 where POSIX::sigaction() appears to be broken.

For a cleaner implementation that works across perl versions, see Lincoln Baxter's Sys::SigAction module at http://search.cpan.org/~lbaxter/Sys-SigAction/. The documentation for Sys::SigAction includes an longer discussion of this problem, and a DBD::Oracle test script.

Be sure to read all the signal handling sections of the the perlipc manpage manual.

And finally, two more points to keep firmly in mind. Firstly, remember that what we've done here is essentially revert to old style unsafe handling of these signals. So do as little as possible in the handler. Ideally just die(). Secondly, the handles in use at the time the signal is handled may not be safe to use afterwards.

Subclassing the DBI

DBI can be subclassed and extended just like any other object oriented module. Before we talk about how to do that, it's important to be clear about the various DBI classes and how they work together.

By default $dbh = DBI->connect(...) returns a $dbh blessed into the DBI::db class. And the $dbh->prepare method returns an $sth blessed into the DBI::st class (actually it simply changes the last four characters of the calling handle class to be ::st).

The leading 'DBI' is known as the 'root class' and the extra '::db' or '::st' are the 'handle type suffixes'. If you want to subclass the DBI you'll need to put your overriding methods into the appropriate classes. For example, if you want to use a root class of MySubDBI and override the do(), prepare() and execute() methods, then your do() and prepare() methods should be in the MySubDBI::db class and the execute() method should be in the MySubDBI::st class.

To setup the inheritance hierarchy the @ISA variable in MySubDBI::db should include DBI::db and the @ISA variable in MySubDBI::st should include DBI::st. The MySubDBI root class itself isn't currently used for anything visible and so, apart from setting @ISA to include DBI, it can be left empty.

So, having put your overriding methods into the right classes, and setup the inheritance hierarchy, how do you get the DBI to use them? You have two choices, either a static method call using the name of your subclass:

  $dbh = MySubDBI->connect(...);

or specifying a RootClass attribute:

  $dbh = DBI->connect(..., { RootClass => 'MySubDBI' });

If both forms are used then the attribute takes precedence.

The only differences between the two are that using an explicit RootClass attribute will a) make the DBI automatically attempt to load a module by that name if the class doesn't exist, and b) won't call your MySubDBI::connect() method, if you have one.

When subclassing is being used then, after a successful new connect, the DBI->connect method automatically calls:

  $dbh->connected($dsn, $user, $pass, \%attr);

The default method does nothing. The call is made just to simplify any post-connection setup that your subclass may want to perform. The parameters are the same as passed to DBI->connect. If your subclass supplies a connected method, it should be part of the MySubDBI::db package.

One more thing to note: you must let the DBI do the handle creation. If you want to override the connect() method in your *::dr class then it must still call SUPER::connect to get a $dbh to work with. Similarly, an overridden prepare() method in *::db must still call SUPER::prepare to get a $sth. If you try to create your own handles using bless() then you'll find the DBI will reject them with an "is not a DBI handle (has no magic)" error.

Here's a brief example of a DBI subclass. A more thorough example can be found in t/subclass.t in the DBI distribution.

  package MySubDBI;

  use strict;

  use DBI;
  use vars qw(@ISA);
  @ISA = qw(DBI);

  package MySubDBI::db;
  use vars qw(@ISA);
  @ISA = qw(DBI::db);

  sub prepare {
    my ($dbh, @args) = @_;
    my $sth = $dbh->SUPER::prepare(@args)
        or return;
    $sth->{private_mysubdbi_info} = { foo => 'bar' };
    return $sth;
  }

  package MySubDBI::st;
  use vars qw(@ISA);
  @ISA = qw(DBI::st);

  sub fetch {
    my ($sth, @args) = @_;
    my $row = $sth->SUPER::fetch(@args)
        or return;
    do_something_magical_with_row_data($row)
        or return $sth->set_err(1234, "The magic failed", undef, "fetch");
    return $row;
  }

When calling a SUPER::method that returns a handle, be careful to check the return value before trying to do other things with it in your overridden method. This is especially important if you want to set a hash attribute on the handle, as Perl's autovivification will bite you by (in)conveniently creating an unblessed hashref, which your method will then return with usually baffling results later on. It's best to check right after the call and return undef immediately on error, just like DBI would and just like the example above.

If your method needs to record an error it should call the set_err() method with the error code and error string, as shown in the example above. The error code and error string will be recorded in the handle and available via $h->err and $DBI::errstr etc. The set_err() method always returns an undef or empty list as approriate. Since your method should nearly always return an undef or empty list as soon as an error is detected it's handy to simply return what set_err() returns, as shown in the example above.

If the handle has RaiseError, PrintError, or HandleError etc. set then the set_err() method will honour them. This means that if RaiseError is set then set_err() won't return in the normal way but will 'throw an exception' that can be caught with an eval block.

You can stash private data into DBI handles via $h->{private_..._*}. See the entry under ATTRIBUTES COMMON TO ALL HANDLES for info and important caveats.

TRACING

The DBI has a powerful tracing mechanism built in. It enables you to see what's going on 'behind the scenes', both within the DBI and the drivers you're using.

Trace Settings

Which details are written to the trace output is controlled by a combination of a trace level, an integer from 0 to 15, and a set of trace flags that are either on or off. Together these are known as the trace settings and are stored together in a single integer. For normal use you only need to set the trace level, and generally only to a value between 1 and 4.

Each handle has it's own trace settings, and so does the DBI. When you call a method the DBI merges the handles settings into its own for the duration of the call: the trace flags of the handle are OR'd into the trace flags of the DBI, and if the handle has a higher trace level then the DBI trace level is raised to match it. The previous DBI trace setings are restored when the called method returns.

Trace Levels

Trace levels are as follows:

  0 - Trace disabled.
  1 - Trace DBI method calls returning with results or errors.
  2 - Trace method entry with parameters and returning with results.
  3 - As above, adding some high-level information from the driver
      and some internal information from the DBI.
  4 - As above, adding more detailed information from the driver.
  5 to 15 - As above but with more and more obscure information.

Trace level 1 is best for a simple overview of what's happening. Trace level 2 is a good choice for general purpose tracing. Levels 3 and above are best reserved for investigating a specific problem, when you need to see "inside" the driver and DBI.

The trace output is detailed and typically very useful. Much of the trace output is formatted using the neat function, so strings in the trace output may be edited and truncated by that function.

Trace Flags

Trace flags are used to enable tracing of specific activities within the DBI and drivers. The DBI defines some trace flags and drivers can define others. DBI trace flag names begin with a capital letter and driver specific names begin with a lowercase letter, as usual.

Curently the DBI only defines two trace flags:

  ALL - turn on all DBI and driver flags (not recommended)
  SQL - trace SQL statements executed (not yet implemented)

The parse_trace_flags and parse_trace_flag methods are used to convert trace flag names into the coresponding integer bit flags.

Enabling Trace

The $h->trace method sets the trace settings for a handle and DBI->trace does the same for the DBI.

In addition to the trace method, you can enable the same trace information, and direct the output to a file, by setting the DBI_TRACE environment variable before starting Perl. See DBI_TRACE for more information.

Finally, you can set, or get, the trace settings for a handle using the TraceLevel attribute.

All of those methods use parse_trace_flags() and so allow you set both the trace level and multiple trace flags by using a string containing the trace level and/or flag names separated by vertical bar ("|") or comma (",") characters. For example:

  local $h->{TraceLevel} = "3|SQL|foo";

Trace Output

Initially trace output is written to STDERR. Both the $h->trace and DBI->trace methods take an optional $trace_filename parameter. If specified, and can be opened in append mode, then all trace output (currently including that from other handles) is redirected to that file. A warning is generated if the file can't be opened.

Further calls to trace() without a $trace_filename do not alter where the trace output is sent. If $trace_filename is undefined, then trace output is sent to STDERR and the previous trace file is closed.

Currently $trace_filename can't be a filehandle. But meanwhile you can use the special strings "STDERR" and "STDOUT" to select those filehandles.

Trace Content

Many of the values embeded in trace output are formatted using the neat() utility function. This means they may be quoted, sanitized, and possibly truncated if longer than $DBI::neat_maxlen. See neat for more details.

Tracing Tips

You can add tracing to your own application code using the trace_msg method.

It can sometimes be handy to compare trace files from two different runs of the same script. However using a tool like diff doesn't work well because the trace file is full of object addresses that may differ each run. Here's a handy little command to strip those out:

  perl -pe 's/\b0x[\da-f]{6,}/0xNNNN/gi; s/\b[\da-f]{6,}/<long number>/gi'

DBI ENVIRONMENT VARIABLES

The DBI module recognizes a number of environment variables, but most of them should not be used most of the time. It is better to be explicit about what you are doing to avoid the need for environment variables, especially in a web serving system where web servers are stingy about which environment variables are available.

DBI_DSN

The DBI_DSN environment variable is used by DBI->connect if you do not specify a data source when you issue the connect. It should have a format such as "dbi:Driver:databasename".

DBI_DRIVER

The DBI_DRIVER environment variable is used to fill in the database driver name in DBI->connect if the data source string starts "dbi::" (thereby omitting the driver). If DBI_DSN omits the driver name, DBI_DRIVER can fill the gap.

DBI_AUTOPROXY

The DBI_AUTOPROXY environment variable takes a string value that starts "dbi:Proxy:" and is typically followed by "hostname=...;port=...". It is used to alter the behaviour of DBI->connect. For full details, see DBI::Proxy documentation.

DBI_USER

The DBI_USER environment variable takes a string value that is used as the user name if the DBI->connect call is given undef (as distinct from an empty string) as the username argument. Be wary of the security implications of using this.

DBI_PASS

The DBI_PASS environment variable takes a string value that is used as the password if the DBI->connect call is given undef (as distinct from an empty string) as the password argument. Be extra wary of the security implications of using this.

DBI_DBNAME (obsolete)

The DBI_DBNAME environment variable takes a string value that is used only when the obsolescent style of DBI->connect (with driver name as fourth parameter) is used, and when no value is provided for the first (database name) argument.

DBI_TRACE

The DBI_TRACE environment variable specifies the global default trace settings for the DBI at startup. Can also be used to direct trace output to a file. When the DBI is loaded it does:

  DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE};

So if DBI_TRACE contains an "=" character then what follows it is used as the name of the file to append the trace to.

output appended to that file. If the name begins with a number followed by an equal sign (=), then the number and the equal sign are stripped off from the name, and the number is used to set the trace level. For example:

  DBI_TRACE=1=dbitrace.log perl your_test_script.pl

On Unix-like systems using a Bourne-like shell, you can do this easily on the command line:

  DBI_TRACE=2 perl your_test_script.pl

See TRACING for more information.

PERL_DBI_DEBUG (obsolete)

An old variable that should no longer be used; equivalent to DBI_TRACE.

DBI_PROFILE

The DBI_PROFILE environment variable can be used to enable profiling of DBI method calls. See the DBI::Profile manpage for more information.

DBI_PUREPERL

The DBI_PUREPERL environment variable can be used to enable the use of DBI::PurePerl. See the DBI::PurePerl manpage for more information.

WARNING AND ERROR MESSAGES

Fatal Errors

Can't call method "prepare" without a package or object reference

The $dbh handle you're using to call prepare is probably undefined because the preceding connect failed. You should always check the return status of DBI methods, or use the RaiseError attribute.

Can't call method "execute" without a package or object reference

The $sth handle you're using to call execute is probably undefined because the preceeding prepare failed. You should always check the return status of DBI methods, or use the RaiseError attribute.

DBI/DBD internal version mismatch

The DBD driver module was built with a different version of DBI than the one currently being used. You should rebuild the DBD module under the current version of DBI.

(Some rare platforms require "static linking". On those platforms, there may be an old DBI or DBD driver version actually embedded in the Perl executable being used.)

DBD driver has not implemented the AutoCommit attribute

The DBD driver implementation is incomplete. Consult the author.

Can't [sg]et %s->{%s}: unrecognised attribute

You attempted to set or get an unknown attribute of a handle. Make sure you have spelled the attribute name correctly; case is significant (e.g., "Autocommit" is not the same as "AutoCommit").

Pure-Perl DBI

A pure-perl emulation of the DBI is included in the distribution for people using pure-perl drivers who, for whatever reason, can't install the compiled DBI. See the DBI::PurePerl manpage.

SEE ALSO

Driver and Database Documentation

Refer to the documentation for the DBD driver that you are using.

Refer to the SQL Language Reference Manual for the database engine that you are using.

ODBC and SQL/CLI Standards Reference Information

More detailed information about the semantics of certain DBI methods that are based on ODBC and SQL/CLI standards is available on-line via microsoft.com, for ODBC, and www.jtc1sc32.org for the SQL/CLI standard:

 DBI method        ODBC function     SQL/CLI Working Draft
 ----------        -------------     ---------------------
 column_info       SQLColumns        Page 124
 foreign_key_info  SQLForeignKeys    Page 163
 get_info          SQLGetInfo        Page 214
 primary_key_info  SQLPrimaryKeys    Page 254
 table_info        SQLTables         Page 294
 type_info         SQLGetTypeInfo    Page 239
 statistics_info   SQLStatistics

For example, for ODBC information on SQLColumns you'd visit:

  http://msdn.microsoft.com/library/en-us/odbc/htm/odbcsqlcolumns.asp

If that URL ceases to work then use the MSDN search facility at:

  http://search.microsoft.com/us/dev/

and search for SQLColumns returns using the exact phrase option. The link you want will probably just be called SQLColumns and will be part of the Data Access SDK.

And for SQL/CLI standard information on SQLColumns you'd read page 124 of the (very large) SQL/CLI Working Draft available from:

  http://jtc1sc32.org/doc/N0701-0750/32N0744T.pdf

Standards Reference Information

A hyperlinked, browsable version of the BNF syntax for SQL92 (plus Oracle 7 SQL and PL/SQL) is available here:

  http://cui.unige.ch/db-research/Enseignement/analyseinfo/SQL92/BNFindex.html

A BNF syntax for SQL3 is available here:

  http://www.sqlstandards.org/SC32/WG3/Progression_Documents/Informal_working_drafts/iso-9075-2-1999.bnf

The following links provide further useful information about SQL. Some of these are rather dated now but may still be useful.

  http://www.jcc.com/SQLPages/jccs_sql.htm
  http://www.contrib.andrew.cmu.edu/~shadow/sql.html
  http://www.altavista.com/query?q=sql+tutorial

Books and Articles

Programming the Perl DBI, by Alligator Descartes and Tim Bunce. http://books.perl.org/book/154

Programming Perl 3rd Ed. by Larry Wall, Tom Christiansen & Jon Orwant. http://books.perl.org/book/134

Learning Perl by Randal Schwartz. http://books.perl.org/book/101

Details of many other books related to perl can be found at http://books.perl.org

Perl Modules

Index of DBI related modules available from CPAN:

 http://search.cpan.org/search?mode=module&query=DBIx%3A%3A
 http://search.cpan.org/search?mode=doc&query=DBI

For a good comparison of RDBMS-OO mappers and some OO-RDBMS mappers (including Class::DBI, Alzabo, and DBIx::RecordSet in the former category and Tangram and SPOPS in the latter) see the Perl Object-Oriented Persistence project pages at:

 http://poop.sourceforge.net

A similar page for Java toolkits can be found at:

 http://c2.com/cgi-bin/wiki?ObjectRelationalToolComparison

Mailing List

The dbi-users mailing list is the primary means of communication among users of the DBI and its related modules. For details send email to:

 dbi-users-help@perl.org

There are typically between 700 and 900 messages per month. You have to subscribe in order to be able to post. However you can opt for a 'post-only' subscription.

Mailing list archives (of variable quality) are held at:

 http://groups.google.com/groups?group=perl.dbi.users
 http://www.xray.mpe.mpg.de/mailing-lists/dbi/
 http://www.mail-archive.com/dbi-users%40perl.org/

Assorted Related WWW Links

The DBI "Home Page":

 http://dbi.perl.org/

Other DBI related links:

 http://tegan.deltanet.com/~phlip/DBUIdoc.html
 http://dc.pm.org/perl_db.html
 http://wdvl.com/Authoring/DB/Intro/toc.html
 http://www.hotwired.com/webmonkey/backend/tutorials/tutorial1.html
 http://bumppo.net/lists/macperl/1999/06/msg00197.html
 http://gmax.oltrelinux.com/dbirecipes.html

Other database related links:

 http://www.jcc.com/sql_stnd.html
 http://cuiwww.unige.ch/OSG/info/FreeDB/FreeDB.home.html

Security, especially the "SQL Injection" attack:

 http://www.ngssoftware.com/research/papers.html
 http://www.ngssoftware.com/papers/advanced_sql_injection.pdf
 http://www.ngssoftware.com/papers/more_advanced_sql_injection.pdf
 http://www.esecurityplanet.com/trends/article.php/2243461
 http://www.spidynamics.com/papers/SQLInjectionWhitePaper.pdf
 http://www.imperva.com/application_defense_center/white_papers/blind_sql_server_injection.html
 http://online.securityfocus.com/infocus/1644

Commercial and Data Warehouse Links

 http://www.dwinfocenter.org
 http://www.datawarehouse.com
 http://www.datamining.org
 http://www.olapcouncil.org
 http://www.idwa.org
 http://www.knowledgecenters.org/dwcenter.asp

Recommended Perl Programming Links

 http://language.perl.com/style/

FAQ

Please also read the DBI FAQ which is installed as a DBI::FAQ module. You can use perldoc to read it by executing the perldoc DBI::FAQ command.

AUTHORS

DBI by Tim Bunce. This pod text by Tim Bunce, J. Douglas Dunlop, Jonathan Leffler and others. Perl by Larry Wall and the perl5-porters.

COPYRIGHT

The DBI module is Copyright (c) 1994-2004 Tim Bunce. Ireland. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SUPPORT / WARRANTY

The DBI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

Support

My consulting company, Data Plan Services, offers annual and multi-annual support contracts for the DBI. These provide sustained support for DBI development, and sustained value for you in return. Contact me for details.

Sponsor Enhancements

The DBI Roadmap is available at http://search.cpan.org/~timb/DBI/Roadmap.pod

If your company would benefit from a specific new DBI feature, please consider sponsoring its development. Work is performed rapidly, and usually on a fixed-price payment-on-delivery basis. Contact me for details.

Using such targeted financing allows you to contribute to DBI development, and rapidly get something specific and valuable in return.

ACKNOWLEDGEMENTS

I would like to acknowledge the valuable contributions of the many people I have worked with on the DBI project, especially in the early years (1992-1994). In no particular order: Kevin Stock, Buzz Moschetti, Kurt Andersen, Ted Lemon, William Hails, Garth Kennedy, Michael Peppler, Neil S. Briscoe, Jeff Urlwin, David J. Hughes, Jeff Stander, Forrest D Whitcher, Larry Wall, Jeff Fried, Roy Johnson, Paul Hudson, Georg Rehfeld, Steve Sizemore, Ron Pool, Jon Meek, Tom Christiansen, Steve Baumgarten, Randal Schwartz, and a whole lot more.

Then, of course, there are the poor souls who have struggled through untold and undocumented obstacles to actually implement DBI drivers. Among their ranks are Jochen Wiedmann, Alligator Descartes, Jonathan Leffler, Jeff Urlwin, Michael Peppler, Henrik Tougaard, Edwin Pratomo, Davide Migliavacca, Jan Pazdziora, Peter Haworth, Edmund Mergl, Steve Williams, Thomas Lowery, and Phlip Plumlee. Without them, the DBI would not be the practical reality it is today. I'm also especially grateful to Alligator Descartes for starting work on the first edition of the "Programming the Perl DBI" book and letting me jump on board.

The DBI and DBD::Oracle were originally developed while I was Technical Director (CTO) of the Paul Ingram Group (www.ig.co.uk). So I'd especially like to thank Paul for his generosity and vision in supporting this work for many years.

CONTRIBUTING

As you can see above, many people have contributed to the DBI and drivers in many ways over many years.

If you'd like to help then see http://dbi.perl.org/contributing and http://search.cpan.org/~timb/DBI/Roadmap.pod

If you'd like the DBI to do something new or different then a good way to make that happen is to do it yourself and send me a patch to the source code that shows the changes. (But read "Speak before you patch" below.)

Browsing the source code repository

Use http://svn.perl.org/modules/dbi/trunk (basic) or http://svn.perl.org/viewcvs/modules/ (more useful)

How to create a patch using Subversion

The DBI source code is maintained using Subversion (a replacement for CVS, see http://subversion.tigris.org/). To access the source you'll need to install a Subversion client. Then, to get the source code, do:

  svn checkout http://svn.perl.org/modules/dbi/trunk

If it prompts for a username and password use your perl.org account if you have one, else just 'guest' and 'guest'. The source code will be in a new subdirectory called trunk.

To keep informed about changes to the source you can send an empty email to dbi-changes@perl.org after which you'll get an email with the change log message and diff of each change checked-in to the source.

After making your changes you can generate a patch file, but before you do, make sure your source is still upto date using:

  svn update

If you get any conflicts reported you'll need to fix them first. Then generate the patch file from within the trunk directory using:

  svn diff > foo.patch

Read the patch file, as a sanity check, and then email it to dbi-dev@perl.org.

How to create a patch without Subversion

Unpack a fresh copy of the distribution:

  tar xfz DBI-1.40.tar.gz

Rename the newly created top level directory:

  mv DBI-1.40 DBI-1.40.your_foo

Edit the contents of DBI-1.40.your_foo/* till it does what you want.

Test your changes and then remove all temporary files:

  make test && make distclean

Go back to the directory you originally unpacked the distribution:

  cd ..

Unpack another copy of the original distribution you started with:

  tar xfz DBI-1.40.tar.gz

Then create a patch file by performing a recursive diff on the two top level directories:

  diff -r -u DBI-1.40 DBI-1.40.your_foo > DBI-1.40.your_foo.patch

Speak before you patch

For anything non-trivial or possibly controversial it's a good idea to discuss (on dbi-dev@perl.org) the changes you propose before actually spending time working on them. Otherwise you run the risk of them being rejected because they don't fit into some larger plans you may not be aware of.

TRANSLATIONS

A German translation of this manual (possibly slightly out of date) is available, thanks to O'Reilly, at:

  http://www.oreilly.de/catalog/perldbiger/

Some other translations:

 http://cronopio.net/perl/                              - Spanish
 http://member.nifty.ne.jp/hippo2000/dbimemo.htm        - Japanese

TRAINING

References to DBI related training resources. No recommendation implied.

  http://www.treepax.co.uk/
  http://www.keller.com/dbweb/

(If you offer professional DBI related training services, please send me your details so I can add them here.)

FREQUENTLY ASKED QUESTIONS

See the DBI FAQ for a more comprehensive list of FAQs. Use the perldoc DBI::FAQ command to read it.

Why doesn't my CGI script work right?

Read the information in the references below. Please do not post CGI related questions to the dbi-users mailing list (or to me).

 http://www.perl.com/cgi-bin/pace/pub/doc/FAQs/cgi/perl-cgi-faq.html
 http://www3.pair.com/webthing/docs/cgi/faqs/cgifaq.shtml
 http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html
 http://www.boutell.com/faq/
 http://www.perl.com/perl/faq/

How can I maintain a WWW connection to a database?

For information on the Apache httpd server and the mod_perl module see

  http://perl.apache.org/

OTHER RELATED WORK AND PERL MODULES

Apache::DBI by E.Mergl@bawue.de

To be used with the Apache daemon together with an embedded Perl interpreter like mod_perl. Establishes a database connection which remains open for the lifetime of the HTTP daemon. This way the CGI connect and disconnect for every database access becomes superfluous.

JDBC Server by Stuart 'Zen' Bishop zen@bf.rmit.edu.au

The server is written in Perl. The client classes that talk to it are of course in Java. Thus, a Java applet or application will be able to comunicate via the JDBC API with any database that has a DBI driver installed. The URL used is in the form jdbc:dbi://host.domain.etc:999/Driver/DBName. It seems to be very similar to some commercial products, such as jdbcKona.

Remote Proxy DBD support

As of DBI 1.02, a complete implementation of a DBD::Proxy driver and the DBI::ProxyServer are part of the DBI distribution.

SQL Parser

See also the the SQL::Statement manpage module, SQL parser and engine.


Tue Jan 23 16:15:21 2007: C<Module> L<HTML::Tagset|HTML::Tagset>

    • Tue Jan 23 16:15:21 2007: Module HTML::Tagset
    • Tue Jan 23 16:16:10 2007: Module ActiveState::Utils
    • Tue Jan 23 16:16:20 2007: Module Compress::Zlib
    • Tue Jan 23 16:16:35 2007: Module URI
    • Tue Jan 23 16:16:51 2007: Module HTML::Parser
    • Tue Jan 23 16:17:03 2007: Module Tcl
    • Tue Jan 23 16:17:38 2007: Module DBI
    • Tue Jan 23 16:17:45 2007: Module IO::Zlib
    • Tue Jan 23 16:17:50 2007: Module IO::String
    • Tue Jan 23 16:18:07 2007: Module ActiveState::RelocateTree
    • Tue Jan 23 16:18:24 2007: Module ActivePerl::DocTools
    • Tue Jan 23 16:18:43 2007: Module XML::Parser
    • Tue Jan 23 16:18:48 2007: Module Text::Reform
    • Tue Jan 23 16:19:29 2007: Module LWP
    • Tue Jan 23 16:19:37 2007: Module Digest::SHA1
    • Tue Jan 23 16:20:01 2007: Module Tkx
    • Tue Jan 23 16:20:08 2007: Module Term::ReadKey
    • Tue Jan 23 16:20:46 2007: Module DBD::SQLite
    • Tue Jan 23 16:20:59 2007: Module Archive::Tar
    • Tue Jan 23 16:21:16 2007: Module Win32::AuthenticateUser
    • Tue Jan 23 16:26:35 2007: Module libwin32
    • Tue Jan 23 16:28:25 2007: Module XML::Simple
    • Tue Jan 23 16:28:34 2007: Module Unicode::String
    • Tue Jan 23 16:36:18 2007: Module Tk
    • Tue Jan 23 16:36:28 2007: Module Text::Autoformat
    • Tue Jan 23 16:36:33 2007: Module Term::ReadLine::Perl
    • Tue Jan 23 16:36:49 2007: Module SOAP::Lite
    • Tue Jan 23 16:37:00 2007: Module MIME-Base64-Scripts
    • Tue Jan 23 16:37:06 2007: Module MD5
    • Tue Jan 23 16:37:19 2007: Module Math::BigInt::FastCalc
    • Tue Jan 23 16:37:29 2007: Module HTML-Tree
    • Tue Jan 23 16:37:34 2007: Module Font::AFM
    • Tue Jan 23 16:37:54 2007: Module File::CounterFile
    • Tue Jan 23 16:38:02 2007: Module Digest::MD4
    • Tue Jan 23 16:38:09 2007: Module Digest::MD2
    • Tue Jan 23 16:38:15 2007: Module Digest::HMAC
    • Tue Jan 23 16:38:21 2007: Module Data::Dump
    • Tue Jan 23 16:38:37 2007: Module Archive::Zip
    • Tue Jan 23 16:38:46 2007: Module ActiveState::Scineplex
    • Tue Jan 23 16:39:50 2007: Module ActivePerl::PPM
    • Tue Jan 23 16:39:56 2007: Module ActivePerl::Config

Tue Jan 23 16:15:21 2007: Module HTML::Tagset

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 3.10

  • EXE_FILES:

Tue Jan 23 16:16:10 2007: Module ActiveState::Utils

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.02

  • EXE_FILES:

Tue Jan 23 16:16:20 2007: Module Compress::Zlib

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.42

  • EXE_FILES:

Tue Jan 23 16:16:35 2007: Module URI

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.35

  • EXE_FILES:

Tue Jan 23 16:16:51 2007: Module HTML::Parser

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 3.56

  • EXE_FILES:

Tue Jan 23 16:17:03 2007: Module Tcl

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 0.89

  • EXE_FILES:

Tue Jan 23 16:17:38 2007: Module DBI

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.52

  • EXE_FILES: dbiproxy dbiprof

Tue Jan 23 16:17:45 2007: Module IO::Zlib

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.04

  • EXE_FILES:

Tue Jan 23 16:17:50 2007: Module IO::String

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.08

  • EXE_FILES:

Tue Jan 23 16:18:07 2007: Module ActiveState::RelocateTree

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.03

  • EXE_FILES: bin/reloc_perl

Tue Jan 23 16:18:24 2007: Module ActivePerl::DocTools

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.00

  • EXE_FILES: bin/ap-update-html bin/ap-user-guide

Tue Jan 23 16:18:43 2007: Module XML::Parser

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.34

  • EXE_FILES:

Tue Jan 23 16:18:48 2007: Module Text::Reform

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.11

  • EXE_FILES:

Tue Jan 23 16:19:29 2007: Module LWP

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 5.805

  • EXE_FILES: bin/lwp-request bin/lwp-mirror bin/lwp-rget bin/lwp-download

Tue Jan 23 16:19:37 2007: Module Digest::SHA1

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.11

  • EXE_FILES:

Tue Jan 23 16:20:01 2007: Module Tkx

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.04

  • EXE_FILES: tkx-ed tkx-prove

Tue Jan 23 16:20:08 2007: Module Term::ReadKey

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.30

  • EXE_FILES:

Tue Jan 23 16:20:46 2007: Module DBD::SQLite

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.13

  • EXE_FILES:

Tue Jan 23 16:20:59 2007: Module Archive::Tar

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.30

  • EXE_FILES: bin/ptar bin/ptardiff

Tue Jan 23 16:21:16 2007: Module Win32::AuthenticateUser

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 0.02

  • EXE_FILES:

Tue Jan 23 16:26:35 2007: Module libwin32

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 0.26.0.2

  • EXE_FILES:

Tue Jan 23 16:28:25 2007: Module XML::Simple

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.16

  • EXE_FILES:

Tue Jan 23 16:28:34 2007: Module Unicode::String

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.09

  • EXE_FILES:

Tue Jan 23 16:36:18 2007: Module Tk

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 804.027

  • EXE_FILES: ptksh ptked gedi

Tue Jan 23 16:36:28 2007: Module Text::Autoformat

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.13

  • EXE_FILES:

Tue Jan 23 16:36:33 2007: Module Term::ReadLine::Perl

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.0302

  • EXE_FILES:

Tue Jan 23 16:36:49 2007: Module SOAP::Lite

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 0.55

  • EXE_FILES: bin/SOAPsh.pl bin/XMLRPCsh.pl bin/stubmaker.pl

Tue Jan 23 16:37:00 2007: Module MIME-Base64-Scripts

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.00

  • EXE_FILES: encode-base64 decode-base64 encode-qp decode-qp

Tue Jan 23 16:37:06 2007: Module MD5

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.03

  • EXE_FILES:

Tue Jan 23 16:37:19 2007: Module Math::BigInt::FastCalc

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 0.10

  • EXE_FILES:

Tue Jan 23 16:37:29 2007: Module HTML-Tree

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 3.23

  • EXE_FILES:

Tue Jan 23 16:37:34 2007: Module Font::AFM

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.19

  • EXE_FILES:

Tue Jan 23 16:37:54 2007: Module File::CounterFile

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.04

  • EXE_FILES:

Tue Jan 23 16:38:02 2007: Module Digest::MD4

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.5

  • EXE_FILES:

Tue Jan 23 16:38:09 2007: Module Digest::MD2

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 2.03

  • EXE_FILES:

Tue Jan 23 16:38:15 2007: Module Digest::HMAC

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.01

  • EXE_FILES:

Tue Jan 23 16:38:21 2007: Module Data::Dump

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.08

  • EXE_FILES:

Tue Jan 23 16:38:37 2007: Module Archive::Zip

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.18

  • EXE_FILES: bin/crc32

Tue Jan 23 16:38:46 2007: Module ActiveState::Scineplex

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.01

  • EXE_FILES:

Tue Jan 23 16:39:50 2007: Module ActivePerl::PPM

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 4.01

  • EXE_FILES: bin/ppm bin/ppm-shell

Tue Jan 23 16:39:56 2007: Module ActivePerl::Config

  • installed into: C:\Programme\Perl\lib

  • LINKTYPE: dynamic

  • VERSION: 1.00

  • EXE_FILES:


Tcl - Tcl extension module for Perl

    • Methods in class Tcl
    • Linking Perl and Tcl variables
    • Accessing Perl from within Tcl
    • Moving Tcl/Tk around with Tcl.pm
      • First method
      • Second method
      • Third method
  • AUTHORS
  • COPYRIGHT

NAME

Tcl - Tcl extension module for Perl

SYNOPSIS

    use Tcl;

    $interp = new Tcl;
    $interp->Eval('puts "Hello world"');

DESCRIPTION

The Tcl extension module gives access to the Tcl library with functionality and interface similar to the C functions of Tcl. In other words, you can

create Tcl interpreters

The Tcl interpreters so created are Perl objects whose destructors delete the interpreters cleanly when appropriate.

execute Tcl code in an interpreter

The code can come from strings, files or Perl filehandles.

bind in new Tcl procedures

The new procedures can be either C code (with addresses presumably obtained using dl_open and dl_find_symbol) or Perl subroutines (by name, reference or as anonymous subs). The (optional) deleteProc callback in the latter case is another perl subroutine which is called when the command is explicitly deleted by name or else when the destructor for the interpreter object is explicitly or implicitly called.

Manipulate the result field of a Tcl interpreter
Set and get values of variables in a Tcl interpreter
Tie perl variables to variables in a Tcl interpreter

The variables can be either scalars or hashes.

Methods in class Tcl

To create a new Tcl interpreter, use

    $i = new Tcl;

The following methods and routines can then be used on the Perl object returned (the object argument omitted in each case).

Init ()

Invoke Tcl_Init on the interpeter.

Eval (STRING, FLAGS)

Evaluate script STRING in the interpreter. If the script returns successfully (TCL_OK) then the Perl return value corresponds to Tcl interpreter's result otherwise a die exception is raised with the $@ variable corresponding to Tcl's interpreter result object. In each case, corresponds means that if the method is called in scalar context then the string result is returned but if the method is called in list context then the result is split as a Tcl list and returned as a Perl list. The FLAGS field is optional and can be a bitwise OR of the constants Tcl::EVAL_GLOBAL or Tcl::EVAL_DIRECT.

GlobalEval (STRING)

REMOVED. Evalulate script STRING at global level. Call Eval(STRING, Tcl::EVAL_GLOBAL) instead.

EvalFile (FILENAME)

Evaluate the contents of the file with name FILENAME. Otherwise, the same as Eval() above.

EvalFileHandle (FILEHANDLE)

Evaluate the contents of the Perl filehandle FILEHANDLE. Otherwise, the same as Eval() above. Useful when using the filehandle DATA to tack on a Tcl script following an __END__ token.

call (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it using Tcl's eval semantics that does command tracing and will use the ::unknown (AUTOLOAD) mechanism. The arguments (ARG, ...) are not passed through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC.

Before invoking procedure PROC special processing is performed on ARG list:

1. All subroutine references within ARG will be substituted with Tcl name which is responsible to invoke this subroutine. This Tcl name will be created using CreateCommand subroutine (see below).

2. All references to scalars will be substituted with names of Tcl variables transformed appropriately.

These first two items allows to write and expect it to work properly such code as:

  my $r = 'aaaa';
  button(".d", -textvariable => \$r, -command=>sub {$r++});

3. As a special case, there is a mechanism to deal with Tk's special event variables (they are mentioned as '%x', '%y' and so on throughout Tcl). When creating a subroutine reference that uses such variables, you must declare the desired variables using Tcl::Ev as the first argument to the subroutine. Example:

  sub textPaste {
      my ($x,$y,$w) = @_;
      widget($w)->insert("\@$x,$y", $interp->Eval('selection get'));
  }
  $widget->bind('<2>', [\&textPaste, Tcl::Ev('%x', '%y'), $widget] );
return_ref (NAME)

returns a reference corresponding to NAME, which was associated during previously called $int->call(...) preprocessing. As a typical example this could be variable associated with a widget.

delete_ref (NAME)

deletes and returns a reference corresponding to NAME, which was associated during previously called $int->call(...) preprocessing.

icall (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it using Tcl's eval semantics that does command tracing and will use the ::unknown (AUTOLOAD) mechanism. The arguments (ARG, ...) are not passed through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC.

This is the lower-level procedure that the 'call' method uses. Arguments are converted efficiently from Perl SVs to Tcl_Objs. A Perl AV array becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc. The reverse conversion is done to the result.

invoke (PROC, ARG, ...)

Looks up procedure PROC in the interpreter and invokes it directly with arguments (ARG, ...) without passing through the Tcl parser. For example, spaces embedded in any ARG will not cause it to be split into two Tcl arguments before being passed to PROC. This differs from icall/call in that it directly invokes the command name without allowing for command tracing or making use of Tcl's unknown (AUTOLOAD) mechanism. If the command does not already exist in the interpreter, and error will be thrown.

Arguments are converted efficiently from Perl SVs to Tcl_Objs. A Perl AV array becomes a Tcl_ListObj, an SvIV becomes a Tcl_IntObj, etc. The reverse conversion is done to the result.

Tcl::Ev (FIELD, ...)

Used to declare %-substitution variables of interest to a subroutine callback. FIELD is expected to be of the form "%#" where # is a single character, and multiple fields may be specified. Returns a blessed object that the 'call' method will recognize when it is passed as the first argument to a subroutine in a callback. See description of 'call' method for details.

result ()

Returns the current Tcl interpreter result. List v. scalar context is handled as in Eval() above.

CreateCommand (CMDNAME, CMDPROC, CLIENTDATA, DELETEPROC)

Binds a new procedure named CMDNAME into the interpreter. The CLIENTDATA and DELETEPROC arguments are optional. There are two cases:

(1) CMDPROC is the address of a C function

(presumably obtained using dl_open and dl_find_symbol. In this case CLIENTDATA and DELETEPROC are taken to be raw data of the ClientData and deleteProc field presumably obtained in a similar way.

(2) CMDPROC is a Perl subroutine

(either a sub name, a sub reference or an anonymous sub). In this case CLIENTDATA can be any perl scalar (e.g. a ref to some other data) and DELETEPROC must be a perl sub too. When CMDNAME is invoked in the Tcl interpeter, the arguments passed to the Perl sub CMDPROC are

    (CLIENTDATA, INTERP, LIST)

where INTERP is a Perl object for the Tcl interpreter which called out and LIST is a Perl list of the arguments CMDNAME was called with. As usual in Tcl, the first element of the list is CMDNAME itself. When CMDNAME is deleted from the interpreter (either explicitly with DeleteCommand or because the destructor for the interpeter object is called), it is passed the single argument CLIENTDATA.

DeleteCommand (CMDNAME)

Deletes command CMDNAME from the interpreter. If the command was created with a DELETEPROC (see CreateCommand above), then it is invoked at this point. When a Tcl interpreter object is destroyed either explicitly or implicitly, an implicit DeleteCommand happens on all its currently registered commands.

SetResult (STRING)

Sets Tcl interpreter result to STRING.

AppendResult (LIST)

Appends each element of LIST to Tcl's interpreter result object.

AppendElement (STRING)

Appends STRING to Tcl interpreter result object as an extra Tcl list element.

ResetResult ()

Resets Tcl interpreter result.

SplitList (STRING)

Splits STRING as a Tcl list. Returns a Perl list or the empty list if there was an error (i.e. STRING was not a properly formed Tcl list). In the latter case, the error message is left in Tcl's interpreter result object.

SetVar (VARNAME, VALUE, FLAGS)

The FLAGS field is optional. Sets Tcl variable VARNAME in the interpreter to VALUE. The FLAGS argument is the usual Tcl one and can be a bitwise OR of the constants Tcl::GLOBAL_ONLY, Tcl::LEAVE_ERR_MSG, Tcl::APPEND_VALUE, Tcl::LIST_ELEMENT.

SetVar2 (VARNAME1, VARNAME2, VALUE, FLAGS)

Sets the element VARNAME1(VARNAME2) of a Tcl array to VALUE. The optional argument FLAGS behaves as in SetVar above.

GetVar (VARNAME, FLAGS)

Returns the value of Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

GetVar2 (VARNAME1, VARNAME2, FLAGS)

Returns the value of the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

UnsetVar (VARNAME, FLAGS)

Unsets Tcl variable VARNAME. The optional argument FLAGS behaves as in SetVar above.

UnsetVar2 (VARNAME1, VARNAME2, FLAGS)

Unsets the element VARNAME1(VARNAME2) of a Tcl array. The optional argument FLAGS behaves as in SetVar above.

Linking Perl and Tcl variables

You can tie a Perl variable (scalar or hash) into class Tcl::Var so that changes to a Tcl variable automatically "change" the value of the Perl variable. In fact, as usual with Perl tied variables, its current value is just fetched from the Tcl variable when needed and setting the Perl variable triggers the setting of the Tcl variable.

To tie a Perl scalar $scalar to the Tcl variable tclscalar in interpreter $interp with optional flags $flags (see SetVar above), use

        tie $scalar, Tcl::Var, $interp, "tclscalar", $flags;

Omit the $flags argument if not wanted.

To tie a Perl hash %hash to the Tcl array variable array in interpreter $interp with optional flags $flags (see SetVar above), use

        tie %hash, Tcl::Var, $interp, "array", $flags;

Omit the $flags argument if not wanted. Any alteration to Perl variable $hash{"key"} affects the Tcl variable array(key) and vice versa.

Accessing Perl from within Tcl

After creation of Tcl interpreter, in addition to evaluation of Tcl/Tk commands within Perl, other way round also instantiated. Within a special namespace ::perl following objects are created:

   ::perl::Eval

So it is possible to use Perl objects from within Tcl.

Moving Tcl/Tk around with Tcl.pm

NOTE: explanations below is for developers managing Tcl/Tk installations itself, users should skip this section.

In order to create Tcl/Tk application with this module, you need to make sure that Tcl/Tk is available within visibility of this module. There are many ways to achieve this, varying on ease of starting things up and providing flexible moveable archived files.

Following list enumerates them, in order of increased possibility to change location.

  • First method

    Install Tcl/Tk first, then install Perl module Tcl, so installed Tcl/Tk will be used. This is most normal approach, and no care of Tcl/Tk distribution is taken on Perl side (this is done on Tcl/Tk side)

  • Second method

    Copy installed Tcl/Tk binaries to some location, then install Perl module Tcl with a special action to make Tcl.pm know of this location. This approach makes sure that only chosen Tcl installation is used.

  • Third method

    During compiling Tcl Perl module, Tcl/Tk could be statically linked into module's shared library and all other files zipped into a single archive, so each file extracted when needed.

Some global variables within $Tcl::config:: namespace are used to make such installations possible.

First method

Second method

To use second approach, desired set of Tcl/Tk binaries should be prepared in a single directory. Mostly these files could be files from existing Tcl/Tk installation.

Use create-moveable-dist.pl script to create proper configuration this way.

From inmplementation side of view, following things are done in this way:

  • Entire Tcl/Tk directory is copied into blib/lib
  • Tcl.cfg file is created at the same dir where Tcl.pm is placed; this file contain some configuration and a code to initially load Tcl shared library.

Third method

To link Tcl/Tk binaries, prepare their libraries and then instruct Makefile.PL to use these libraries in a link stage. (TODO provide better detailed description)

AUTHORS

Malcolm Beattie, mbeattie@sable.ox.ac.uk, 23 Oct 1994. Vadim Konovalov, vkon@cpan.org, 19 May 2003. Jeff Hobbs, jeff (a) activestate . com, 22 Mar 2004. Gisle Aas, gisle (a) activestate . com, 14 Apr 2004.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html


DBI::Changes - List of significant changes to the DBI

  • NAME
    • Changes in DBI 1.52 (svn rev 6734), 30h July 2006
    • Changes in DBI 1.51 (svn rev 6475), 6th June 2006
    • Changes in DBI 1.50 (svn rev 2307), 13 December 2005
    • Changes in DBI 1.49 (svn rev 2287), 29th November 2005
    • Changes in DBI 1.48 (svn rev 928), 14th March 2005
    • Changes in DBI 1.47 (svn rev 854), 2nd February 2005
    • Changes in DBI 1.46 (svn rev 584), 16th November 2004
    • Changes in DBI 1.45 (svn rev 480), 6th October 2004
    • Changes in DBI 1.44 (svn rev 478), 5th October 2004
    • Changes in DBI 1.43 (svn rev 377), 2nd July 2004
    • Changes in DBI 1.42 (svn rev 222), 12th March 2004
    • Changes in DBI 1.41 (svn rev 130), 22nd February 2004
    • Changes in DBI 1.40, 7th January 2004
    • Changes in DBI 1.39, 27th November 2003
    • Changes in DBI 1.38, 21th August 2003
    • Changes in DBI 1.37, 15th May 2003
    • Changes in DBI 1.36, 11th May 2003
    • Changes in DBI 1.35, 7th March 2003
    • Changes in DBI 1.34, 28th February 2003
    • Changes in DBI 1.33, 27th February 2003
    • Changes in DBI 1.32, 1st December 2002
    • Changes in DBI 1.31, 29th November 2002
    • Changes in DBI 1.30, 18th July 2002
    • Changes in DBI 1.29, 15th July 2002
    • Changes in DBI 1.28, 14th June 2002
    • Changes in DBI 1.27, 13th June 2002
    • Changes in DBI 1.26, 13th June 2002
    • Changes in DBI 1.25, 5th June 2002
    • Changes in DBI 1.24, 4th June 2002
    • Changes in DBI 1.23, 25th May 2002
    • Changes in DBI 1.22, 22nd May 2002
    • Changes in DBI 1.21, 7th February 2002
    • Changes in DBI 1.20, 24th August 2001
    • Changes in DBI 1.19, 20th July 2001
    • Changes in DBI 1.18, 4th June 2001
    • Changes in DBI 1.16, 30th May 2001
    • Changes in DBI 1.15, 28th March 2001
    • Changes in DBI 1.14, 14th June 2000
    • Changes in DBI 1.13, 11th July 1999
    • Changes in DBI 1.12, 29th June 1999
    • Changes in DBI 1.11, 17th June 1999
    • Changes in DBI 1.10, 14th June 1999
    • Changes in DBI 1.09, 9th June 1999
    • Changes in DBI 1.08, 12th May 1999
    • Changes in DBI 1.07, 6th May 1999
    • Changes in DBI 1.06, 6th January 1999
    • Changes in DBI 1.05, 4th January 1999
    • Changes in DBI 1.04, 3rd January 1999
    • Changes in DBI 1.03, 1st January 1999
    • Changes in DBI 1.02, 2nd September 1998
    • Changes in DBI 1.01, 2nd September 1998
    • Changes in DBI 1.00, 14th August 1998
    • Changes in DBI 0.95, 10th August 1998
    • Changes in DBI 0.94, 9th August 1998
    • Changes in DBI 0.93, 13th February 1998
    • Changes in DBI 0.92, 3rd February 1998
    • Changes in DBI 0.91, 10th December 1997
    • Changes in DBI 0.90, 6th September 1997
    • Changes in DBI 0.89, 25th July 1997
    • Changes in DBI 0.88, 22nd July 1997
    • Changes in DBI 0.87, 18th July 1997
    • Changes in DBI 0.86, 16th July 1997
    • Changes in DBI 0.85, 25th June 1997
    • Changes in DBI 0.84, 20th June 1997
    • Changes in DBI 0.83, 11th June 1997
    • Changes in DBI 0.82, 23rd May 1997
    • Changes in DBI 0.81, 7th May 1997
    • Changes in DBI 0.80, 6th May 1997
    • Changes in DBI 0.79, 7th Apr 1997
    • Changes in DBI 0.78, 28th Mar 1997
    • Changes in DBI 0.77, 21st Feb 1997
    • Changes in DBI 0.76, 3rd Feb 1997
    • Changes in DBI 0.75, 27th Jan 1997
    • Changes in DBI 0.74, 14th Jan 1997
    • Changes in DBI 0.73, 10th Oct 1996
    • Changes in DBI 0.72, 23 Sep 1996
    • Changes in DBI 0.71, 10 July 1996
    • Changes in DBI 0.70, 16 June 1996
    • Changes in DBI 0.69
    • Changes in DBI 0.68, 2 Mar 1996
    • Changes in DBI 0.67, 15 Feb 1996
    • Changes in DBI 0.66, 29 Jan 1996
    • Changes in DBI 0.65, 23 Oct 1995
    • Changes in DBI 0.64, 23 Oct 1995
    • Changes in DBI 0.63, 1 Sep 1995
    • Changes in DBI 0.62, 26 Aug 1995
    • Changes in DBI 0.61, 22 Aug 1995
    • Changes in DBI 0.60, 17 Aug 1995
    • Changes in DBI 0.59 15 Aug 1995
    • Changes in DBI 0.58 21 June 1995
  • ANCIENT HISTORY

NAME

DBI::Changes - List of significant changes to the DBI

Changes in DBI 1.52 (svn rev 6734), 30h July 2006

  Fixed memory leak (per handle) thanks to Nicholas Clark and Ephraim Dan.
  Fixed memory leak (16 bytes per sth) thanks to Doru Theodor Petrescu.
  Fixed execute_for_fetch/execute_array to RaiseError thanks to Martin J. Evans.
  Fixed for perl 5.9.4. Users of Perl >= 5.9.4 will require DBI >= 1.52.
  Updated DBD::File to 0.35 to match the latest release on CPAN.
  Added $dbh->statistics_info specification thanks to Brandon Black.
  Many changes and additions to profiling:
    Profile Path can now uses sane strings instead of obscure numbers,
    can refer to attributes, assorted magical values, and even code refs!
    Parsing of non-numeric DBI_PROFILE env var values has changed.
    Changed DBI::Profile docs extensively - many new features.
    See DBI::Profile docs for more information.

Changes in DBI 1.51 (svn rev 6475), 6th June 2006

  Fixed $dbh->clone method 'signature' thanks to Jeffrey Klein.
  Fixed default ping() method to return false if !$dbh->{Active}.
  Fixed t/40profile.t to be insensitive to long double precision.
  Fixed for perl 5.8.0's more limited weaken() function.
  Fixed DBD::Proxy to not alter $@ in disconnect or AUTOLOADd methods.
  Fixed bind_columns() to use return set_err(...) instead of die()
    to report incorrect number of parameters, thanks to Ben Thul.
  Fixed bind_col() to ignore undef as bind location, thanks to David Wheeler.
  Fixed for perl 5.9.x for non-threaded builds thanks to Nicholas Clark.
    Users of Perl >= 5.9.x will require DBI >= 1.51.
  Fixed fetching of rows as hash refs to preserve utf8 on field names
    from $sth->{NAME} thanks to Alexey Gaidukov.
  Fixed build on Win32 (dbd_postamble) thanks to David Golden.

  Improved performance for thread-enabled perls thanks to Gisle Aas.
  Drivers can now use PERL_NO_GET_CONTEXT thanks to Gisle Aas.
    Driver authors please read the notes in the DBI::DBD docs.
  Changed DBI::Profile format to always include a percentage,
    if not exiting then uses time between the first and last DBI call.
  Changed DBI::ProfileData to be more forgiving of systems with
    unstable clocks (where time may go backwards occasionally).
  Clarified the 'Subclassing the DBI' docs.
  Assorted minor changes to docs from comments on annocpan.org.
  Changed Makefile.PL to avoid incompatible options for old gcc.
  Added 'fetch array of hash refs' example to selectall_arrayref
    docs thanks to Tom Schindl.
  Added docs for $sth->{ParamArrays} thanks to Martin J. Evans.
  Added reference to $DBI::neat_maxlen in TRACING section of docs.
  Added ability for DBI::Profile Path to include attributes
    and a summary of where the code was called from.

Changes in DBI 1.50 (svn rev 2307), 13 December 2005

  Fixed Makefile.PL options for gcc bug introduced in 1.49.
  Fixed handle magic order to keep DBD::Oracle happy.
  Fixed selectrow_array to return empty list on error.
  Changed dbi_profile_merge() to be able to recurse and merge
    sub-trees of profile data.
  Added documentation for dbi_profile_merge(), including how to
    measure the time spent inside the DBI for an http request.

Changes in DBI 1.49 (svn rev 2287), 29th November 2005

  Fixed assorted attribute handling bugs in DBD::Proxy.
  Fixed croak() in DBD::NullP thanks to Sergey Skvortsov.
  Fixed handling of take_imp_data() and dbi_imp_data attribute.
  Fixed bugs in DBD::DBM thanks to Jeff Zucker.
  Fixed bug in DBI::ProfileDumper thanks to Sam Tregar.
  Fixed ping in DBD::Proxy thanks to George Campbell.
  Fixed dangling ref in $sth after parent $dbh destroyed
    with thanks to il@rol.ru for the bug report #13151
  Fixed prerequisites to include Storable thanks to Michael Schwern.
  Fixed take_imp_data to be more practical.
  Change to require perl 5.6.1 (as advertised in 2003) not 5.6.0.
  Changed internals to be more strictly coded thanks to Andy Lester.
  Changed warning about multiple copies of Driver.xst found in @INC
    to ignore duplicated directories thanks to Ed Avis.
  Changed Driver.xst to enable drivers to define an dbd_st_prepare_sv
    function where the statement parameter is an SV. That enables
    compiled drivers to support SQL strings that are UTF-8.
  Changed "use DBI" to only set $DBI::connect_via if not already set.
  Changed docs to clarify pre-method clearing of err values.
  Added ability for DBI::ProfileData to edit profile path on loading.
    This enables aggregation of different SQL statements into the same
    profile node - very handy when not using placeholders or when working
    multiple separate tables for the same thing (ie logtable_2005_11_28)
  Added $sth->{ParamTypes} specification thanks to Dean Arnold.
  Added $h->{Callbacks} attribute to enable code hooks to be invoked
    when certain methods are called. For example:
    $dbh->{Callbacks}->{prepare} = sub { ... };
    With thanks to David Wheeler for the kick start.
  Added $h->{ChildHandles} (using weakrefs) thanks to Sam Tregar
    I've recoded it in C so there's no significant performance impact.
  Added $h->{Type} docs (returns 'dr', 'db', or 'st')
  Adding trace message in DESTROY if InactiveDestroy enabled.
  Added %drhs = DBI->installed_drivers();

  Ported DBI::ProfileDumper::Apache to mod_perl2 RC5+
    thanks to Philip M. Golluci

Changes in DBI 1.48 (svn rev 928), 14th March 2005

  Fixed DBI::DBD::Metadata generation of type_info_all thanks to Steffen Goeldner
    (driver authors who have used it should rerun it).
  Updated docs for NULL Value placeholders thanks to Brian Campbell.

  Added multi-keyfield nested hash fetching to fetchall_hashref()
    thanks to Zhuang (John) Li for polishing up my draft.
  Added registered driver prefixes: amzn_ for DBD::Amazon and yaswi_ for DBD::Yaswi.

Changes in DBI 1.47 (svn rev 854), 2nd February 2005

  Fixed DBI::ProxyServer to not create pid files by default.
    References: Ubuntu Security Notice USN-70-1, CAN-2005-0077
    Thanks to Javier Fernández-Sanguino Peña from the
    Debian Security Audit Project, and Jonathan Leffler.
  Fixed some tests to work with older Test::More versions.
  Fixed setting $DBI::err/errstr in DBI::PurePerl.
  Fixed potential undef warning from connect_cached().
  Fixed $DBI::lasth handling for DESTROY so lasth points to
    parent even if DESTROY called other methods.
  Fixed DBD::Proxy method calls to not alter $@.
  Fixed DBD::File problem with encoding pragma thanks to Erik Rijkers.
  Changed error handling so undef errstr doesn't cause warning.
  Changed DBI::DBD docs to use =head3/=head4 pod thanks to
    Jonathan Leffler. This may generate warnings for perl 5.6.
  Changed DBI::PurePerl to set autoflush on trace filehandle.
  Changed DBD::Proxy to treat Username as a local attribute
    so recent DBI version can be used with old DBI::ProxyServer.
  Changed driver handle caching in DBD::File.
  Added $GetInfoType{SQL_DATABASE_NAME} thanks to Steffen Goeldner.

  Updated docs to recommend some common DSN string attributes.
  Updated connect_cached() docs with issues and suggestions.
  Updated docs for NULL Value placeholders thanks to Brian Campbell.
  Updated docs for primary_key_info and primary_keys.
  Updated docs to clarify that the default fetchrow_hashref behaviour,
    of returning a ref to a new hash for each row, will not change.
  Updated err/errstr/state docs for DBD authors thanks to Steffen Goeldner.
  Updated handle/attribute docs for DBD authors thanks to Steffen Goeldner.
  Corrected and updated LongReadLen docs thanks to Bart Lateur.
  Added DBD::JDBC as a registered driver.

Changes in DBI 1.46 (svn rev 584), 16th November 2004

  Fixed parsing bugs in DBI::SQL::Nano thanks to Jeff Zucker.
  Fixed a couple of bad links in docs thanks to Graham Barr.
  Fixed test.pl Win32 undef warning thanks to H.Merijn Brand & David Repko.
  Fixed minor issues in DBI::DBD::Metadata thanks to Steffen Goeldner.
  Fixed DBI::PurePerl neat() to use double quotes for utf8.
  Changed execute_array() definition, and default implementation,
    to not consider scalar values for execute tuple count. See docs.
  Changed DBD::File to enable ShowErrorStatement by default,
    which affects DBD::File subclasses such as DBD::CSV and DBD::DBM.
  Changed use DBI qw(:utils) tag to include $neat_maxlen.
  Updated Roadmap and ToDo.
  Added data_string_diff() data_string_desc() and data_diff()
    utility functions to help diagnose Unicode issues.
    All can be imported via the use DBI qw(:utils) tag.

Changes in DBI 1.45 (svn rev 480), 6th October 2004

  Fixed DBI::DBD code for drivers broken in 1.44.
  Fixed "Free to wrong pool"/"Attempt to free unreferenced scalar" in FETCH.

Changes in DBI 1.44 (svn rev 478), 5th October 2004

  Fixed build issues on VMS thanks to Jakob Snoer.
  Fixed DBD::File finish() method to return 1 thanks to Jan Dubois.
  Fixed rare core dump during global destruction thanks to Mark Jason Dominus.
  Fixed risk of utf8 flag persisting from one row to the next.
  Changed bind_param_array() so it doesn't require all bind arrays
    to have the same number of elements.
  Changed bind_param_array() to error if placeholder number <= 0.
  Changed execute_array() definition, and default implementation,
    to effectively NULL-pad shorter bind arrays.
  Changed execute_array() to return "0E0" for 0 as per the docs.
  Changed execute_for_fetch() definition, and default implementation,
    to return "0E0" for 0 like execute() and execute_array().
  Changed Test::More prerequisite to Test::Simple (which is also the name
    of the distribution both are packaged in) to work around ppm behaviour.
  Corrected docs to say that get/set of unknown attribute generates
    a warning and is no longer fatal. Thanks to Vadim.
  Corrected fetchall_arrayref() docs example thanks to Drew Broadley.
  Added $h1->swap_inner_handle($h2) sponsored by BizRate.com

Changes in DBI 1.43 (svn rev 377), 2nd July 2004

  Fixed connect() and connect_cached() RaiseError/PrintError
    which would sometimes show "(no error string)" as the error.
  Fixed compiler warning thanks to Paul Marquess.
  Fixed "trace level set to" trace message thanks to H.Merijn Brand.
  Fixed DBD::DBM $dbh->{dbm_tables}->{...} to be keyed by the
    table name not the file name thanks to Jeff Zucker.
  Fixed last_insert_id(...) thanks to Rudy Lippan.
  Fixed propagation of scalar/list context into proxied methods.
  Fixed DBI::Profile::DESTROY to not alter $@.
  Fixed DBI::ProfileDumper new() docs thanks to Michael Schwern.
  Fixed _load_class to propagate $@ thanks to Drew Taylor.
  Fixed compile warnings on Win32 thanks to Robert Baron.
  Fixed problem building with recent versions of MakeMaker.
  Fixed DBD::Sponge not to generate warning with threads.
  Fixed DBI_AUTOPROXY to work more than once thanks to Steven Hirsch.

  Changed TraceLevel 1 to not show recursive/nested calls.
  Changed getting or setting an invalid attribute to no longer be
    a fatal error but generate a warning instead.
  Changed selectall_arrayref() to call finish() if
    $attr->{MaxRows} is defined.
  Changed all tests to use Test::More and enhanced the tests thanks
    to Stevan Little and Andy Lester. See http://qa.perl.org/phalanx/
  Changed Test::More minimum prerequisite version to 0.40 (2001).
  Changed DBI::Profile header to include the date and time.

  Added DBI->parse_dsn($dsn) method.
  Added warning if build directory path contains whitespace.
  Added docs for parse_trace_flags() and parse_trace_flag().
  Removed "may change" warnings from the docs for table_info(),
    primary_key_info(), and foreign_key_info() methods.

Changes in DBI 1.42 (svn rev 222), 12th March 2004

  Fixed $sth->{NUM_OF_FIELDS} of non-executed statement handle
    to be undef as per the docs (it was 0).
  Fixed t/41prof_dump.t to work with perl5.9.1.
  Fixed DBD_ATTRIB_DELETE macro thanks to Marco Paskamp.
  Fixed DBI::PurePerl looks_like_number() and $DBI::rows.
  Fixed ref($h)->can("foo") to not croak.

  Changed attributes (NAME, TYPE etc) of non-executed statement
    handle to be undef instead of triggering an error.
  Changed ShowErrorStatement to apply to more $dbh methods.
  Changed DBI_TRACE env var so just does this at load time:
    DBI->trace(split '=', $ENV{DBI_TRACE}, 2);
  Improved "invalid number of parameters" error message.
  Added DBI::common as base class for DBI::db, DBD::st etc.
  Moved methods common to all handles into DBI::common.

  Major tracing enhancement:
  Added $h->parse_trace_flags("foo|SQL|7") to map a group of
    trace flags into the corresponding trace flag bits.
  Added automatic calling of parse_trace_flags() if
    setting the trace level to a non-numeric value:
    $h->{TraceLevel}="foo|SQL|7"; $h->trace("foo|SQL|7");
    DBI->connect("dbi:Driver(TraceLevel=SQL|foo):...", ...);
    Currently no trace flags have been defined.
  Added to, and reworked, the trace documentation.
  Added dbivport.h for driver authors to use.

  Major driver additions that Jeff Zucker and I have been working on:
  Added DBI::SQL::Nano a 'smaller than micro' SQL parser
    with an SQL::Statement compatible API. If SQL::Statement
    is installed then DBI::SQL::Nano becomes an empty subclass
    of SQL::Statement, unless the DBI_SQL_NANO env var is true.
  Added DBD::File, modified to use DBI::SQL::Nano.
  Added DBD::DBM, an SQL interface to DBM files using DBD::File.
  Documentation changes:
  Corrected typos in docs thanks to Steffen Goeldner.
  Corrected execute_for_fetch example thanks to Dean Arnold.

Changes in DBI 1.41 (svn rev 130), 22nd February 2004

  Fixed execute_for_array() so tuple_status parameter is optional
    as per docs, thanks to Ed Avis.
  Fixed execute_for_array() docs to say that it returns undef if
    any of the execute() calls fail.
  Fixed take_imp_data() test on m68k reported by Christian Hammers.
  Fixed write_typeinfo_pm inconsistencies in DBI::DBD::Metadata
    thanks to Andy Hassall.
  Fixed $h->{TraceLevel} to not return DBI->trace trace level
    which it used to if DBI->trace trace level was higher.

  Changed set_err() to append to errstr, with a leading "\n" if it's
    not empty, so that multiple error/warning messages are recorded.
  Changed trace to limit elements dumped when an array reference is
    returned from a method to the max(40, $DBI::neat_maxlen/10)
    so that fetchall_arrayref(), for example, doesn't flood the trace.
  Changed trace level to be a four bit integer (levels 0 thru 15)
    and a set of topic flags (no topics have been assigned yet).
  Changed column_info() to check argument count.
  Extended bind_param() TYPE attribute specification to imply
    standard formating of value, eg SQL_DATE implies 'YYYY-MM-DD'.
  Added way for drivers to indicate 'success with info' or 'warning'
    by setting err to "0" for warning and "" for information.
    Both values are false and so don't trigger RaiseError etc.
    Thanks to Steffen Goeldner for the original idea.
  Added $h->{HandleSetErr} = sub { ... } to be called at the
    point that an error, warn, or info state is recorded.
    The code can alter the err, errstr, and state values
    (e.g., to promote an error to a warning, or the reverse).
  Added $h->{PrintWarn} attribute to enable printing of warnings
    recorded by the driver. Defaults to same value as $^W (perl -w).
  Added $h->{ErrCount} attribute, incremented whenever an error is
    recorded by the driver via set_err().
  Added $h->{Executed} attribute, set if do()/execute() called.
  Added \%attr parameter to foreign_key_info() method.
  Added ref count of inner handle to "DESTROY ignored for outer" msg.
  Added Win32 build config checks to DBI::DBD thanks to Andy Hassall.
  Added bind_col to Driver.xst so drivers can define their own.
  Added TYPE attribute to bind_col and specified the expected
    driver behaviour.

  Major update to signal handling docs thanks to Lincoln Baxter.
  Corrected dbiproxy usage doc thanks to Christian Hammers.
  Corrected type_info_all index hash docs thanks to Steffen Goeldner.
  Corrected type_info COLUMN_SIZE to chars not bytes thanks to Dean Arnold.
  Corrected get_info() docs to include details of DBI::Const::GetInfoType.
  Clarified that $sth->{PRECISION} is OCTET_LENGTH for char types.

Changes in DBI 1.40, 7th January 2004

  Fixed handling of CachedKids when DESTROYing threaded handles.
  Fixed sql_user_name() in DBI::DBD::Metadata (used by write_getinfo_pm)
    to use $dbh->{Username}. Driver authors please update your code.

  Changed connect_cached() when running under Apache::DBI
    to route calls to Apache::DBI::connect().
  Added CLONE() to DBD::Sponge and DBD::ExampleP.
  Added warning when starting a new thread about any loaded driver
    which does not have a CLONE() function.
  Added new prepare_cache($sql, \%attr, 3) option to manage Active handles.
  Added SCALE and NULLABLE support to DBD::Sponge.
  Added missing execute() in fetchall_hashref docs thanks to Iain Truskett.
  Added a CONTRIBUTING section to the docs with notes on creating patches.

Changes in DBI 1.39, 27th November 2003

  Fixed STORE to not clear error during nested DBI call, again/better,
    thanks to Tony Bowden for the report and helpful test case.
  Fixed DBI dispatch to not try to use AUTOLOAD for driver methods unless
    the method has been declared (as methods should be when using AUTOLOAD).
    This fixes a problem when the Attribute::Handlers module is loaded.
  Fixed cwd check code to use $Config{path_sep} thanks to Steve Hay.
  Fixed unqualified croak() calls thanks to Steffen Goeldner.
  Fixed DBD::ExampleP TYPE and PRECISION attributes thanks to Tom Lowery.
  Fixed tracing of methods that only get traced at high trace levels.

  The level 1 trace no longer includes nested method calls so it generally
    just shows the methods the application explicitly calls.
  Added line to trace log (level>=4) when err/errstr is cleared.
  Updated docs for InactiveDestroy and point out where and when the
    trace includes the process id.
  Update DBI::DBD docs thanks to Steffen Goeldner.
  Removed docs saying that the DBI->data_sources method could be
    passed a $dbh. The $dbh->data_sources method should be used instead.
  Added link to 'DBI recipes' thanks to Giuseppe Maxia:
    http://gmax.oltrelinux.com/dbirecipes.html (note that this
    is not an endorsement that the recipies are 'optimal')
  Note: There is a bug in perl 5.8.2 when configured with threads
  and debugging enabled (bug #24463) which causes a DBI test to fail.

Changes in DBI 1.38, 21th August 2003

  NOTE: The DBI now requires perl version 5.6.0 or later.
  (As per notice in DBI 1.33 released 27th February 2003)
  Fixed spurious t/03handles failure on 64bit perls reported by H.Merijn Brand.
  Fixed spurious t/15array failure on some perl versions thanks to Ed Avis.
  Fixed build using dmake on windows thanks to Steffen Goeldner.
  Fixed build on using some shells thanks to Gurusamy Sarathy.
  Fixed ParamValues to only be appended to ShowErrorStatement if not empty.
  Fixed $dbh->{Statement} not being writable by drivers in some cases.
  Fixed occasional undef warnings on connect failures thanks to Ed Avis.
  Fixed small memory leak when using $sth->{NAME..._hash}.
  Fixed 64bit warnings thanks to Marian Jancar.
  Fixed DBD::Proxy::db::DESTROY to not alter $@ thanks to Keith Chapman.
  Fixed Makefile.PL status from WriteMakefile() thanks to Leon Brocard.

  Changed "Can't set ...->{Foo}: unrecognised attribute" from an error to a
    warning when running with DBI::ProxyServer to simplify upgrades.
  Changed execute_array() to no longer require ArrayTupleStatus attribute.
  Changed DBI->available_drivers to not hide DBD::Sponge.
  Updated/moved placeholder docs to a better place thanks to Johan Vromans.
  Changed dbd_db_do4 api in Driver.xst to match dbd_st_execute (return int,
    not bool), relevant only to driver authors.
  Changed neat(), and thus trace(), so strings marked as utf8 are presented
    in double quotes instead of single quotes and are not sanitized.

  Added $dbh->data_sources method.
  Added $dbh->last_insert_id method.
  Added $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status) method.
  Added DBI->installed_versions thanks to Jeff Zucker.
  Added $DBI::Profile::ON_DESTROY_DUMP variable.
  Added docs for DBD::Sponge thanks to Mark Stosberg.

Changes in DBI 1.37, 15th May 2003

  Fixed "Can't get dbh->{Statement}: unrecognised attribute" error in test
    caused by change to perl internals in 5.8.0
  Fixed to build with latest development perl (5.8.1@19525).
  Fixed C code to use all ANSI declarations thanks to Steven Lembark.

Changes in DBI 1.36, 11th May 2003

  Fixed DBI->connect to carp instead of croak on 'old-style' usage.
  Fixed connect(,,, { RootClass => $foo }) to not croak if module not found.
  Fixed code generated by DBI::DBD::Metadata thanks to DARREN@cpan.org (#2270)
  Fixed DBI::PurePerl to not reset $@ during method dispatch.
  Fixed VMS build thanks to Michael Schwern.
  Fixed Proxy disconnect thanks to Steven Hirsch.
  Fixed error in DBI::DBD docs thanks to Andy Hassall.

  Changed t/40profile.t to not require Time::HiRes.
  Changed DBI::ProxyServer to load DBI only on first request, which
    helps threaded server mode, thanks to Bob Showalter.
  Changed execute_array() return value from row count to executed
    tuple count, and now the ArrayTupleStatus attribute is mandatory.
    NOTE: That is an API definition change that may affect your code.
  Changed CompatMode attribute to also disable attribute 'quick FETCH'.
  Changed attribute FETCH to be slightly faster thanks to Stas Bekman.
  Added workaround for perl bug #17575 tied hash nested FETCH
    thanks to Silvio Wanka.
  Added Username and Password attributes to connect(..., \%attr) and so
    also embedded in DSN like "dbi:Driver(Username=user,Password=pass):..."
    Username and Password can't contain ")", ",", or "=" characters.
    The predence is DSN first, then \%attr, then $user & $pass parameters,
    and finally the DBI_USER & DBI_PASS environment variables.
    The Username attribute is stored in the $dbh but the Password is not.
  Added ProxyServer HOWTO configure restrictions docs thanks to Jochen Wiedmann.
  Added MaxRows attribute to selectcol_arrayref prompted by Wojciech Pietron.
  Added dump_handle as a method not just a DBI:: utility function.
  Added on-demand by-row data feed into execute_array() using code ref,
    or statement handle. For example, to insert from a select:
    $insert_sth->execute_array( { ArrayTupleFetch => $select_sth, ... } )
  Added warning to trace log when $h->{foo}=... is ignored due to
    invalid prefix (e.g., not 'private_').

Changes in DBI 1.35, 7th March 2003

  Fixed memory leak in fetchrow_hashref introduced in DBI 1.33.
  Fixed various DBD::Proxy errors introduced in DBI 1.33.
  Fixed to ANSI C in dbd_dr_data_sources thanks to Jonathan Leffler.
  Fixed $h->can($method_name) to return correct code ref.
  Removed DBI::Format from distribution as it's now part of the
    separate DBI::Shell distribution by Tom Lowery.
  Updated DBI::DBD docs with a note about the CLONE method.
  Updated DBI::DBD docs thanks to Jonathan Leffler.
  Updated DBI::DBD::Metadata for perl 5.5.3 thanks to Jonathan Leffler.
  Added note to install_method docs about setup_driver() method.

Changes in DBI 1.34, 28th February 2003

  Fixed DBI::DBD docs to refer to DBI::DBD::Metadata thanks to Jonathan Leffler.
  Fixed dbi_time() compile using BorlandC on Windows thanks to Steffen Goeldner.
  Fixed profile tests to do enough work to measure on Windows.
  Fixed disconnect_all() to not be required by drivers.
  Added $okay = $h->can($method_name) to check if a method exists.
  Added DBD::*::*->install_method($method_name, \%attr) so driver private
    methods can be 'installed' into the DBI dispatcher and no longer
    need to be called using $h->func(..., $method_name).
  Enhanced $dbh->clone() and documentation.
  Enhanced docs to note that dbi_time(), and thus profiling, is limited
    to only millisecond (seconds/1000) resolution on Windows.
  Removed old DBI::Shell from distribution and added Tom Lowery's improved
    version to the Bundle::DBI file.
  Updated minimum version numbers for modules in Bundle::DBI.

Changes in DBI 1.33, 27th February 2003

  NOTE: Future versions of the DBI *will not* support perl 5.6.0 or earlier.
  : Perl 5.6.1 will be the minimum supported version.
  NOTE: The "old-style" connect: DBI->connect($database, $user, $pass, $driver);
  : has been deprecated for several years and will now generate a warning.
  : It will be removed in a later release. Please change any old connect() calls.

  Added $dbh2 = $dbh1->clone to make a new connection to the database
    that is identical to the original one. clone() can be called even after
    the original handle has been disconnected. See the docs for more details.
  Fixed merging of profile data to not sum DBIprof_FIRST_TIME values.
  Fixed unescaping of newlines in DBI::ProfileData thanks to Sam Tregar.
  Fixed Taint bug with fetchrow_hashref with help from Bradley Baetz.
  Fixed $dbh->{Active} for DBD::Proxy, reported by Bob Showalter.
  Fixed STORE to not clear error during nested DBI call,
    thanks to Tony Bowden for the report and helpful test case.
  Fixed DBI::PurePerl error clearing behaviour.
  Fixed dbi_time() and thus DBI::Profile on Windows thanks to Smejkal Petr.
  Fixed problem that meant ShowErrorStatement could show wrong statement,
   thanks to Ron Savage for the report and test case.
  Changed Apache::DBI hook to check for $ENV{MOD_PERL} instead of
    $ENV{GATEWAY_INTERFACE} thanks to Ask Bjoern Hansen.
  No longer tries to dup trace logfp when an interpreter is being cloned.
  Database handles no longer inherit shared $h->err/errstr/state storage
    from their drivers, so each $dbh has it's own $h->err etc. values
    and is no longer affected by calls made on other dbh's.
    Now when a dbh is destroyed it's err/errstr/state values are copied
    up to the driver so checking $DBI::errstr still works as expected.

  Build / portability fixes:
    Fixed t/40profile.t to not use Time::HiRes.
    Fixed t/06attrs.t to not be locale sensitive, reported by Christian Hammers.
    Fixed sgi compiler warnings, reported by Paul Blake.
    Fixed build using make -j4, reported by Jonathan Leffler.
    Fixed build and tests under VMS thanks to Craig A. Berry.
  Documentation changes:
    Documented $high_resolution_time = dbi_time() function.
    Documented that bind_col() can take an atribute hash.
    Clarified documentation for ParamValues attribute hash keys.
    Many good DBI documentation tweaks from Jonathan Leffler,
      including a major update to the DBI::DBD driver author guide.
    Clarified that execute() should itself call finish() if it's
      called on a statement handle that's still active.
    Clarified $sth->{ParamValues}. Driver authors please note.
    Removed "NEW" markers on some methods and attributes and
      added text to each giving the DBI version it was added in,
      if it was added after DBI 1.21 (Feb 2002).

  Changes of note for authors of all drivers:
    Added SQL_DATA_TYPE, SQL_DATETIME_SUB, NUM_PREC_RADIX, and
      INTERVAL_PRECISION fields to docs for type_info_all. There were
      already in type_info(), but type_info_all() didn't specify the
      index values.  Please check and update your type_info_all() code.
    Added DBI::DBD::Metadata module that auto-generates your drivers
      get_info and type_info_all data and code, thanks mainly to
      Jonathan Leffler and Steffen Goeldner. If you've not implemented
      get_info and type_info_all methods and your database has an ODBC
      driver available then this will do all the hard work for you!
    Drivers should no longer pass Err, Errstr, or State to _new_drh
      or _new_dbh functions.
    Please check that you support the slightly modified behaviour of
      $sth->{ParamValues}, e.g., always return hash with keys if possible.

  Changes of note for authors of compiled drivers:
    Added dbd_db_login6 & dbd_st_finish3 prototypes thanks to Jonathan Leffler.
    All dbd_*_*() functions implemented by drivers must have a
      corresponding #define dbd_*_* <driver_prefix>_*_* otherwise
      the driver may not work with a future release of the DBI.
  Changes of note for authors of drivers which use Driver.xst:
    Some new method hooks have been added are are enabled by
      defining corresponding macros:
          $drh->data_sources()      - dbd_dr_data_sources
          $dbh->do()                - dbd_db_do4
    The following methods won't be compiled into the driver unless
      the corresponding macro has been #defined:
          $drh->disconnect_all()    - dbd_discon_all

Changes in DBI 1.32, 1st December 2002

  Fixed to work with 5.005_03 thanks to Tatsuhiko Miyagawa (I've not tested it).
  Reenabled taint tests (accidentally left disabled) spotted by Bradley Baetz.
  Improved docs for FetchHashKeyName attribute thanks to Ian Barwick.
  Fixed core dump if fetchrow_hashref given bad argument (name of attribute
    with a value that wasn't an array reference), spotted by Ian Barwick.
  Fixed some compiler warnings thanks to David Wheeler.
  Updated Steven Hirsch's enhanced proxy work (seems I left out a bit).
  Made t/40profile.t tests more reliable, reported by Randy, who is part of
    the excellent CPAN testers team: http://testers.cpan.org/
    (Please visit, see the valuable work they do and, ideally, join in!)

Changes in DBI 1.31, 29th November 2002

  The fetchall_arrayref method, when called with a $maxrows parameter,
    no longer gives an error if called again after all rows have been
    fetched. This simplifies application logic when fetching in batches.
    Also added batch-fetch while() loop example to the docs.
  The proxy now supports non-lazy (synchronous) prepare, positioned
    updates (for selects containing 'for update'), PlRPC config set
    via attributes, and accurate propagation of errors, all thanks
    to Steven Hirsch (plus a minor fix from Sean McMurray and doc
    tweaks from Michael A Chase).
  The DBI_AUTOPROXY env var can now hold the full dsn of the proxy driver
    plus attributes, like "dbi:Proxy(proxy_foo=>1):host=...".
  Added TaintIn & TaintOut attributes to give finer control over
    tainting thanks to Bradley Baetz.
  The RootClass attribute no longer ignores failure to load a module,
    but also doesn't try to load a module if the class already exists,
    with thanks to James FitzGibbon.
  HandleError attribute works for connect failures thanks to David Wheeler.
  The connect() RaiseError/PrintError message now includes the username.
  Changed "last handle unknown or destroyed" warning to be a trace message.
  Removed undocumented $h->event() method.
  Further enhancements to DBD::PurePerl accuracy.
  The CursorName attribute now defaults to undef and not an error.
  DBI::Profile changes:
    New DBI::ProfileDumper, DBI::ProfileDumper::Apache, and
    DBI::ProfileData modules (to manage the storage and processing
    of profile data), plus dbiprof program for analyzing profile
    data - with many thanks to Sam Tregar.
    Added $DBI::err (etc) tied variable lookup time to profile.
    Added time for DESTROY method into parent handles profile (used to be ignored).
  Documentation changes:
    Documented $dbh = $sth->{Database} attribute.
    Documented $dbh->connected(...) post-connection call when subclassing.
    Updated some minor doc issues thanks to H.Merijn Brand.
    Updated Makefile.PL example in DBI::DBD thanks to KAWAI,Takanori.
    Fixed execute_array() example thanks to Peter van Hardenberg.

  Changes for driver authors, not required but strongly recommended:
    Change DBIS to DBIc_DBISTATE(imp_xxh)   [or imp_dbh, imp_sth etc]
    Change DBILOGFP to DBIc_LOGPIO(imp_xxh) [or imp_dbh, imp_sth etc]
    Any function from which all instances of DBIS and DBILOGFP are
    removed can also have dPERLINTERP removed (a good thing).
    All use of the DBIh_EVENT* macros should be removed.
    Major update to DBI::DBD docs thanks largely to Jonathan Leffler.
    Add these key values: 'Err' => \my $err, 'Errstr' => \my $errstr,
    to the hash passed to DBI::_new_dbh() in your driver source code.
    That will make each $dbh have it's own $h->err and $h->errstr
    values separate from other $dbh belonging to the same driver.
    If you have a ::db or ::st DESTROY methods that do nothing
    you can now remove them - which speeds up handle destruction.

Changes in DBI 1.30, 18th July 2002

  Fixed problems with selectrow_array, selectrow_arrayref, and
    selectall_arrayref introduced in DBI 1.29.
  Fixed FETCHing a handle attribute to not clear $DBI::err etc (broken in 1.29).
  Fixed core dump at trace level 9 or above.
  Fixed compilation with perl 5.6.1 + ithreads (i.e. Windows).
  Changed definition of behaviour of selectrow_array when called in a scalar
    context to match fetchrow_array.
  Corrected selectrow_arrayref docs which showed selectrow_array thanks to Paul DuBois.

Changes in DBI 1.29, 15th July 2002

  NOTE: This release changes the specified behaviour for the
  : fetchrow_array method when called in a scalar context:
  : The DBI spec used to say that it would return the FIRST field.
  : Which field it returns (i.e., the first or the last) is now undefined.
  : This does not affect statements that only select one column, which is
  : usually the case when fetchrow_array is called in a scalar context.
  : FYI, this change was triggered by discovering that the fetchrow_array
  : implementation in Driver.xst (used by most compiled drivers)
  : didn't match the DBI specification. Rather than change the code
  : to match, and risk breaking existing applications, I've changed the
  : specification (that part was always of dubious value anyway).
  NOTE: Future versions of the DBI may not support for perl 5.5 much longer.
  : If you are still using perl 5.005_03 you should be making plans to
  : upgrade to at least perl 5.6.1, or 5.8.0. Perl 5.8.0 is due to be
  : released in the next week or so.  (Although it's a "point 0" release,
  : it is the most throughly tested release ever.)
  Added XS/C implementations of selectrow_array, selectrow_arrayref, and
    selectall_arrayref to Driver.xst. See DBI 1.26 Changes for more info.
  Removed support for the old (fatally flawed) "5005" threading model.
  Added support for new perl 5.8 iThreads thanks to Gerald Richter.
    (Threading support and safety should still be regarded as beta
    quality until further notice. But it's much better than it was.)
  Updated the "Threads and Thread Safety" section of the docs.
  The trace output can be sent to STDOUT instead of STDERR by using
    "STDOUT" as the name of the file, i.e., $h->trace(..., "STDOUT")
  Added pointer to perlreftut, perldsc, perllol, and perlboot manuals
    into the intro section of the docs, suggested by Brian McCain.
  Fixed DBI::Const::GetInfo::* pod docs thanks to Zack Weinberg.
  Some changes to how $dbh method calls are treated by DBI::Profile:
    Meta-data methods now clear $dbh->{Statement} on entry.
    Some $dbh methods are now profiled as if $dbh->{Statement} was empty
    (because thet're unlikely to actually relate to its contents).
  Updated dbiport.h to ppport.h from perl 5.8.0.
  Tested with perl 5.5.3 (vanilla, Solaris), 5.6.1 (vanilla, Solaris), and
    perl 5.8.0 (RC3@17527 with iThreads & Multiplicity on Solaris and FreeBSD).

Changes in DBI 1.28, 14th June 2002

  Added $sth->{ParamValues} to return a hash of the most recent
    values bound to placeholders via bind_param() or execute().
    Individual drivers need to be updated to support it.
  Enhanced ShowErrorStatement to include ParamValues if available:
    "DBD::foo::st execute failed: errstr [for statement ``...'' with params: 1='foo']"
  Further enhancements to DBD::PurePerl accuracy.

Changes in DBI 1.27, 13th June 2002

  Fixed missing column in C implementation of fetchall_arrayref()
    thanks to Philip Molter for the prompt reporting of the problem.

Changes in DBI 1.26, 13th June 2002

  Fixed t/40profile.t to work on Windows thanks to Smejkal Petr.
  Fixed $h->{Profile} to return undef, not error, if not set.
  Fixed DBI->available_drivers in scalar context thanks to Michael Schwern.

  Added C implementations of selectrow_arrayref() and fetchall_arrayref()
    in Driver.xst.  All compiled drivers using Driver.xst will now be
    faster making those calls. Most noticable with fetchall_arrayref for
    many rows or selectrow_arrayref with a fast query. For example, using
    DBD::mysql a selectrow_arrayref for a single row using a primary key
    is ~20% faster, and fetchall_arrayref for 20000 rows is twice as fast!
    Drivers just need to be recompiled and reinstalled to enable it.
    The fetchall_arrayref speed up only applies if $slice parameter is not used.
  Added $max_rows parameter to fetchall_arrayref() to optionally limit
    the number of rows returned. Can now fetch batches of rows.
  Added MaxRows attribute to selectall_arrayref()
    which then passes it to fetchall_arrayref().
  Changed selectrow_array to make use of selectrow_arrayref.
  Trace level 1 now shows first two parameters of all methods
    (used to only for that for some, like prepare,execute,do etc)
  Trace indicator for recursive calls (first char on trace lines)
    now starts at 1 not 2.
  Documented that $h->func() does not trigger RaiseError etc
    so applications must explicitly check for errors.
  DBI::Profile with DBI_PROFILE now shows percentage time inside DBI.
  HandleError docs updated to show that handler can edit error message.
  HandleError subroutine interface is now regarded as stable.

Changes in DBI 1.25, 5th June 2002

  Fixed build problem on Windows and some compiler warnings.
  Fixed $dbh->{Driver} and $sth->{Statement} for driver internals
    These are 'inner' handles as per behaviour prior to DBI 1.16.
  Further minor improvements to DBI::PurePerl accuracy.

Changes in DBI 1.24, 4th June 2002

  Fixed reference loop causing a handle/memory leak
    that was introduced in DBI 1.16.
  Fixed DBI::Format to work with 'filehandles' from IO::Scalar
    and similar modules thanks to report by Jeff Boes.
  Fixed $h->func for DBI::PurePerl thanks to Jeff Zucker.
  Fixed $dbh->{Name} for DBI::PurePerl thanks to Dean Arnold.

  Added DBI method call profiling and benchmarking.
    This is a major new addition to the DBI.
    See $h->{Profile} attribute and DBI::Profile module.
    For a quick trial, set the DBI_PROFILE environment variable and
    run your favourite DBI script. Try it with DBI_PROFILE set to 1,
    then try 2, 4, 8, 10, and -10. Have fun!

  Added execute_array() and bind_param_array() documentation
    with thanks to Dean Arnold.
  Added notes about the DBI having not yet been tested with iThreads
    (testing and patches for SvLOCK etc welcome).
  Removed undocumented Handlers attribute (replaced by HandleError).
  Tested with 5.5.3 and 5.8.0 RC1.

Changes in DBI 1.23, 25th May 2002

  Greatly improved DBI::PurePerl in performance and accuracy.
  Added more detail to DBI::PurePerl docs about what's not supported.
  Fixed undef warnings from t/15array.t and DBD::Sponge.

Changes in DBI 1.22, 22nd May 2002

  Added execute_array() and bind_param_array() with special thanks
    to Dean Arnold. Not yet documented. See t/15array.t for examples.
    All drivers now automatically support these methods.
  Added DBI::PurePerl, a transparent DBI emulation for pure-perl drivers
    with special thanks to Jeff Zucker. Perldoc DBI::PurePerl for details.
  Added DBI::Const::GetInfo* modules thanks to Steffen Goeldner.
  Added write_getinfo_pm utility to DBI::DBD thanks to Steffen Goeldner.
  Added $allow_active==2 mode for prepare_cached() thanks to Stephen Clouse.
  Updated DBI::Format to Revision 11.4 thanks to Tom Lowery.
  Use File::Spec in Makefile.PL (helps VMS etc) thanks to Craig Berry.
  Extend $h->{Warn} to commit/rollback ineffective warning thanks to Jeff Baker.
  Extended t/preparse.t and removed "use Devel::Peek" thanks to Scott Hildreth.
  Only copy Changes to blib/lib/Changes.pm once thanks to Jonathan Leffler.
  Updated internals for modern perls thanks to Jonathan Leffler and Jeff Urlwin.
  Tested with perl 5.7.3 (just using default perl config).

  Documentation changes:
  Added 'Catalog Methods' section to docs thanks to Steffen Goeldner.
  Updated README thanks to Michael Schwern.
  Clarified that driver may choose not to start new transaction until
    next use of $dbh after commit/rollback.
  Clarified docs for finish method.
  Clarified potentials problems with prepare_cached() thanks to Stephen Clouse.

Changes in DBI 1.21, 7th February 2002

  The minimum supported perl version is now 5.005_03.
  Fixed DBD::Proxy support for AutoCommit thanks to Jochen Wiedmann.
  Fixed DBI::ProxyServer bind_param(_inout) handing thanks to Oleg Mechtcheriakov.
  Fixed DBI::ProxyServer fetch loop thanks to nobull@mail.com.
  Fixed install_driver do-the-right-thing with $@ on error. It, and connect(),
    will leave $@ empty on success and holding the error message on error.
    Thanks to Jay Lawrence, Gavin Sherlock and others for the bug report.
  Fixed fetchrow_hashref to assign columns to the hash left-to-right
    so later fields with the same name overwrite earlier ones
    as per DBI < 1.15, thanks to Kay Roepke.
  Changed tables() to use quote_indentifier() if the driver returns a
    true value for $dbh->get_info(29) # SQL_IDENTIFIER_QUOTE_CHAR
  Changed ping() so it no longer triggers RaiseError/PrintError.
  Changed connect() to not call $class->install_driver unless needed.
  Changed DESTROY to catch fatal exceptions and append to $@.
  Added ISO SQL/CLI & ODBCv3 data type definitions thanks to Steffen Goeldner.
  Removed the definition of SQL_BIGINT data type constant as the value is
    inconsistent between standards (ODBC=-5, SQL/CLI=25).
  Added $dbh->column_info(...) thanks to Steffen Goeldner.
  Added $dbh->foreign_key_info(...) thanks to Steffen Goeldner.
  Added $dbh->quote_identifier(...) insipred by Simon Oliver.
  Added $dbh->set_err(...) for DBD authors and DBI subclasses
    (actually been there for a while, now expanded and documented).
  Added $h->{HandleError} = sub { ... } addition and/or alternative
    to RaiseError/PrintError. See the docs for more info.
  Added $h->{TraceLevel} = N attribute to set/get trace level of handle
    thus can set trace level via an (eg externally specified) DSN
    using the embedded attribute syntax:
      $dsn = 'dbi:DB2(PrintError=1,TraceLevel=2):dbname';
    Plus, you can also now do: local($h->{TraceLevel}) = N;
    (but that leaks a little memory in some versions of perl).
  Added some call tree information to trace output if trace level >= 3
    With thanks to Graham Barr for the stack walking code.
  Added experimental undocumented $dbh->preparse(), see t/preparse.t
    With thanks to Scott T. Hildreth for much of the work.
  Added Fowler/Noll/Vo hash type as an option to DBI::hash().

  Documentation changes:
  Added DBI::Changes so now you can "perldoc DBI::Changes", yeah!
  Added selectrow_arrayref & selectrow_hashref docs thanks to Doug Wilson.
  Added 'Standards Reference Information' section to docs to gather
    together all references to relevant on-line standards.
  Added link to poop.sourceforge.net into the docs thanks to Dave Rolsky.
  Added link to hyperlinked BNF for SQL92 thanks to Jeff Zucker.
  Added 'Subclassing the DBI' docs thanks to Stephen Clouse, and
    then changed some of them to reflect the new approach to subclassing.
  Added stronger wording to description of $h->{private_*} attributes.
  Added docs for DBI::hash.

  Driver API changes:
  Now a COPY of the DBI->connect() attributes is passed to the driver
    connect() method, so it can process and delete any elements it wants.
    Deleting elements reduces/avoids the explicit
      $dbh->{$_} = $attr->{$_} foreach keys %$attr;
    that DBI->connect does after the driver connect() method returns.

Changes in DBI 1.20, 24th August 2001

  WARNING: This release contains two changes that may affect your code.
  : Any code using selectall_hashref(), which was added in March 2001, WILL
  : need to be changed. Any code using fetchall_arrayref() with a non-empty
  : hash slice parameter may, in a few rare cases, need to be changed.
  : See the change list below for more information about the changes.
  : See the DBI documentation for a description of current behaviour.
  Fixed memory leak thanks to Toni Andjelkovic.
  Changed fetchall_arrayref({ foo=>1, ...}) specification again (sorry):
    The key names of the returned hashes is identical to the letter case of
    the names in the parameter hash, regardless of the L</FetchHashKeyName>
    attribute. The letter case is ignored for matching.
  Changed fetchall_arrayref([...]) array slice syntax specification to
    clarify that the numbers in the array slice are perl index numbers
    (which start at 0) and not column numbers (which start at 1).
  Added { Columns=>... } and { Slice =>... } attributes to selectall_arrayref()
    which is passed to fetchall_arrayref() so it can fetch hashes now.
  Added a { Columns => [...] } attribute to selectcol_arrayref() so that
    the list it returns can be built from more than one column per row.
    Why? Consider my %hash = @{$dbh->selectcol_arrayref($sql,{ Columns=>[1,2]})}
    to return id-value pairs which can be used directly to build a hash.
  Added $hash_ref = $sth->fetchall_hashref( $key_field )
    which returns a ref to a hash with, typically, one element per row.
    $key_field is the name of the field to get the key for each row from.
    The value of the hash for each row is a hash returned by fetchrow_hashref.
  Changed selectall_hashref to return a hash ref (from fetchall_hashref)
    and not an array of hashes as it has since DBI 1.15 (end March 2001).
    WARNING: THIS CHANGE WILL BREAK ANY CODE USING selectall_hashref()!
    Sorry, but I think this is an important regularization of the API.
    To get previous selectall_hashref() behaviour (an array of hash refs)
    change $ary_ref = $dbh->selectall_hashref( $statement, undef, @bind);
        to $ary_ref = $dbh->selectall_arrayref($statement, { Columns=>{} }, @bind);
  Added NAME_lc_hash, NAME_uc_hash, NAME_hash statement handle attributes.
    which return a ref to a hash of field_name => field_index (0..n-1) pairs.
  Fixed select_hash() example thanks to Doug Wilson.
  Removed (unbundled) DBD::ADO and DBD::Multiplex from the DBI distribution.
    The latest versions of those modules are available from CPAN sites.
  Added $dbh->begin_work. This method causes AutoCommit to be turned
    off just until the next commit() or rollback().
    Driver authors: if the DBIcf_BegunWork flag is set when your commit or
    rollback method is called then please turn AutoCommit on and clear the
    DBIcf_BegunWork flag. If you don't then the DBI will but it'll be much
    less efficient and won't handle error conditions very cleanly.
  Retested on perl 5.4.4, but the DBI won't support 5.4.x much longer.
  Added text to SUPPORT section of the docs:
    For direct DBI and DBD::Oracle support, enhancement, and related work
    I am available for consultancy on standard commercial terms.
  Added text to ACKNOWLEDGEMENTS section of the docs:
    Much of the DBI and DBD::Oracle was developed while I was Technical
    Director (CTO) of the Paul Ingram Group (www.ig.co.uk).  So I'd
    especially like to thank Paul for his generosity and vision in
    supporting this work for many years.

Changes in DBI 1.19, 20th July 2001

  Made fetchall_arrayref({ foo=>1, ...}) be more strict to the specification
    in relation to wanting hash slice keys to be lowercase names.
    WARNING: If you've used fetchall_arrayref({...}) with a hash slice
    that contains keys with uppercase letters then your code will break.
    (As far as I recall the spec has always said don't do that.)
  Fixed $sth->execute() to update $dbh->{Statement} to $sth->{Statement}.
  Added row number to trace output for fetch method calls.
  Trace level 1 no longer shows fetches with row>1 (to reduce output volume).
  Added $h->{FetchHashKeyName} = 'NAME_lc' or 'NAME_uc' to alter
    behaviour of fetchrow_hashref() method. See docs.
  Added type_info quote caching to quote() method thanks to Dean Kopesky.
    Makes using quote() with second data type param much much faster.
  Added type_into_all() caching to type_info(), spotted by Dean Kopesky.
  Added new API definition for table_info() and tables(),
    driver authors please note!
  Added primary_key_info() to DBI API thanks to Steffen Goeldner.
  Added primary_key() to DBI API as simpler interface to primary_key_info().
  Indent and other fixes for DBI::DBD doc thanks to H.Merijn Brand.
  Added prepare_cached() insert_hash() example thanks to Doug Wilson.
  Removed false docs for fetchall_hashref(), use fetchall_arrayref({}).

Changes in DBI 1.18, 4th June 2001

  Fixed that altering ShowErrorStatement also altered AutoCommit!
    Thanks to Jeff Boes for spotting that clanger.
  Fixed DBD::Proxy to handle commit() and rollback(). Long overdue, sorry.
  Fixed incompatibility with perl 5.004 (but no one's using that right? :)
  Fixed connect_cached and prepare_cached to not be affected by the order
    of elements in the attribute hash. Spotted by Mitch Helle-Morrissey.
  Fixed version number of DBI::Shell
    reported by Stuhlpfarrer Gerhard and others.
  Defined and documented table_info() attribute semantics (ODBC compatible)
    thanks to Olga Voronova, who also implemented then in DBD::Oracle.
  Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.

Changes in DBI 1.16, 30th May 2001

  Reimplemented fetchrow_hashref in C, now fetches about 25% faster!
  Changed behaviour if both PrintError and RaiseError are enabled
    to simply do both (in that order, obviously :)
  Slight reduction in DBI handle creation overhead.
  Fixed $dbh->{Driver} & $sth->{Database} to return 'outer' handles.
  Fixed execute param count check to honour RaiseError spotted by Belinda Giardie.
  Fixed build for perl5.6.1 with PERLIO thanks to H.Merijn Brand.
  Fixed client sql restrictions in ProxyServer.pm thanks to Jochen Wiedmann.
  Fixed batch mode command parsing in Shell thanks to Christian Lemburg.
  Fixed typo in selectcol_arrayref docs thanks to Jonathan Leffler.
  Fixed selectrow_hashref to be available to callers thanks to T.J.Mather.
  Fixed core dump if statement handle didn't define Statement attribute.
  Added bind_param_inout docs to DBI::DBD thanks to Jonathan Leffler.
  Added note to data_sources() method docs that some drivers may
    require a connected database handle to be supplied as an attribute.
  Trace of install_driver method now shows path of driver file loaded.
  Changed many '||' to 'or' in the docs thanks to H.Merijn Brand.
  Updated DBD::ADO again (improvements in error handling) from Tom Lowery.
  Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.
  Updated email and web addresses in DBI::FAQ thanks to Michael A Chase.

Changes in DBI 1.15, 28th March 2001

  Added selectrow_arrayref
  Added selectrow_hashref
  Added selectall_hashref thanks to Leon Brocard.
  Added DBI->connect(..., { dbi_connect_method => 'method' })
  Added $dbh->{Statement} aliased to most recent child $sth->{Statement}.
  Added $h->{ShowErrorStatement}=1 to cause the appending of the
    relevant Statement text to the RaiseError/PrintError text.
  Modified type_info to always return hash keys in uppercase and
    to not require uppercase 'DATA_TYPE' key from type_info_all.
    Thanks to Jennifer Tong and Rob Douglas.
  Added \%attr param to tables() and table_info() methods.
  Trace method uses warn() if it can't open the new file.
  Trace shows source line and filename during global destruction.
  Updated packages:
    Updated Win32::DBIODBC (Win32::ODBC emulation) thanks to Roy Lee.
    Updated DBD::ADO to much improved version 0.4 from Tom Lowery.
    Updated DBD::Sponge to include $sth->{PRECISION} thanks to Tom Lowery.
    Changed DBD::ExampleP to use lstat() instead of stat().
  Documentation:
    Documented $DBI::lasth (which has been there since day 1).
    Documented SQL_* names.
    Clarified and extended docs for $h->state thanks to Masaaki Hirose.
    Clarified fetchall_arrayref({}) docs (thanks to, er, someone!).
    Clarified type_info_all re lettercase and index values.
    Updated DBI::FAQ to 0.38 thanks to Alligator Descartes.
    Added cute bind_columns example thanks to H.Merijn Brand.
    Extended docs on \%attr arg to data_sources method.
  Makefile.PL
    Removed obscure potential 'rm -rf /' (thanks to Ulrich Pfeifer).
    Removed use of glob and find (thanks to Michael A. Chase).
  Proxy:
    Removed debug messages from DBD::Proxy AUTOLOAD thanks to Brian McCauley.
    Added fix for problem using table_info thanks to Tom Lowery.
    Added better determination of where to put the pid file, and...
    Added KNOWN ISSUES section to DBD::Proxy docs thanks to Jochen Wiedmann.
  Shell:
    Updated DBI::Format to include DBI::Format::String thanks to Tom Lowery.
    Added describe command thanks to Tom Lowery.
    Added columnseparator option thanks to Tom Lowery (I think).
    Added 'raw' format thanks to, er, someone, maybe Tom again.
  Known issues:
    Perl 5.005 and 5.006 both leak memory doing local($handle->{Foo}).
    Perl 5.004 doesn't. The leak is not a DBI or driver bug.

Changes in DBI 1.14, 14th June 2000

  NOTE: This version is the one the DBI book is based on.
  NOTE: This version requires at least Perl 5.004.
  Perl 5.6 ithreads changes with thanks to Doug MacEachern.
  Changed trace output to use PerlIO thanks to Paul Moore.
  Fixed bug in RaiseError/PrintError handling.
    (% chars in the error string could cause a core dump.)
  Fixed Win32 PerlEx IIS concurrency bugs thanks to Murray Nesbitt.
  Major documentation polishing thanks to Linda Mui at O'Reilly.
  Password parameter now shown as **** in trace output.
  Added two fields to type_info and type_info_all.
  Added $dsn to PrintError/RaiseError message from DBI->connect().
  Changed prepare_cached() croak to carp if sth still Active.
  Added prepare_cached() example to the docs.
  Added further DBD::ADO enhancements from Thomas Lowery.

Changes in DBI 1.13, 11th July 1999

  Fixed Win32 PerlEx IIS concurrency bugs thanks to Murray Nesbitt.
  Fixed problems with DBD::ExampleP long_list test mode.
  Added SQL_WCHAR SQL_WVARCHAR SQL_WLONGVARCHAR and SQL_BIT
    to list of known and exportable SQL types.
  Improved data fetch performance of DBD::ADO.
  Added GetTypeInfo to DBD::ADO thanks to Thomas Lowery.
  Actually documented connect_cached thanks to Michael Schwern.
  Fixed user/key/cipher bug in ProxyServer thanks to Joshua Pincus.

Changes in DBI 1.12, 29th June 1999

  Fixed significant DBD::ADO bug (fetch skipped first row).
  Fixed ProxyServer bug handling non-select statements.
  Fixed VMS problem with t/examp.t thanks to Craig Berry.
  Trace only shows calls to trace_msg and _set_fbav at high levels.
  Modified t/examp.t to workaround Cygwin buffering bug.

Changes in DBI 1.11, 17th June 1999

  Fixed bind_columns argument checking to allow a single arg.
  Fixed problems with internal default_user method.
  Fixed broken DBD::ADO.
  Made default $DBI::rows more robust for some obscure cases.

Changes in DBI 1.10, 14th June 1999

  Fixed trace_msg.al error when using Apache.
  Fixed dbd_st_finish enhancement in Driver.xst (internals).
  Enable drivers to define default username and password
    and temporarily disabled warning added in 1.09.
  Thread safety optimised for single thread case.

Changes in DBI 1.09, 9th June 1999

  Added optional minimum trace level parameter to trace_msg().
  Added warning in Makefile.PL that DBI will require 5.004 soon.
  Added $dbh->selectcol_arrayref($statement) method.
  Fixed fetchall_arrayref hash-slice mode undef NAME problem.
  Fixed problem with tainted parameter checking and t/examp.t.
  Fixed problem with thread safety code, including 64 bit machines.
  Thread safety now enabled by default for threaded perls.
  Enhanced code for MULTIPLICITY/PERL_OBJECT from ActiveState.
  Enhanced prepare_cached() method.
  Minor changes to trace levels (less internal info at level 2).
  Trace log now shows "!! ERROR..." before the "<- method" line.
  DBI->connect() now warn's if user / password is undefined and
    DBI_USER / DBI_PASS environment variables are not defined.
  The t/proxy.t test now ignores any /etc/dbiproxy.conf file.
  Added portability fixes for MacOS from Chris Nandor.
  Updated mailing list address from fugue.com to isc.org.

Changes in DBI 1.08, 12th May 1999

  Much improved DBD::ADO driver thanks to Phlip Plumlee and others.
  Connect now allows you to specify attribute settings within the DSN
    E.g., "dbi:Driver(RaiseError=>1,Taint=>1,AutoCommit=>0):dbname"
  The $h->{Taint} attribute now also enables taint checking of
    arguments to almost all DBI methods.
  Improved trace output in various ways.
  Fixed bug where $sth->{NAME_xx} was undef in some situations.
  Fixed code for MULTIPLICITY/PERL_OBJECT thanks to Alex Smishlajev.
  Fixed and documented DBI->connect_cached.
  Workaround for Cygwin32 build problem with help from Jong-Pork Park.
  bind_columns no longer needs undef or hash ref as first parameter.

Changes in DBI 1.07, 6th May 1999

  Trace output now shows contents of array refs returned by DBI.
  Changed names of some result columns from type_info, type_info_all,
    tables and table_info to match ODBC 3.5 / ISO/IEC standards.
  Many fixes for DBD::Proxy and ProxyServer.
  Fixed error reporting in install_driver.
  Major enhancement to DBI::W32ODBC from Patrick Hollins.
  Added $h->{Taint} to taint fetched data if tainting (perl -T).
  Added code for MULTIPLICITY/PERL_OBJECT contributed by ActiveState.
  Added $sth->more_results (undocumented for now).

Changes in DBI 1.06, 6th January 1999

  Fixed Win32 Makefile.PL problem in 1.04 and 1.05.
  Significant DBD::Proxy enhancements and fixes
    including support for bind_param_inout (Jochen and I)
  Added experimental DBI->connect_cached method.
  Added $sth->{NAME_uc} and $sth->{NAME_lc} attributes.
  Enhanced fetchrow_hashref to take an attribute name arg.

Changes in DBI 1.05, 4th January 1999

  Improved DBD::ADO connect (thanks to Phlip Plumlee).
  Improved thread safety (thanks to Jochen Wiedmann).
  [Quick release prompted by truncation of copies on CPAN]

Changes in DBI 1.04, 3rd January 1999

  Fixed error in Driver.xst. DBI build now tests Driver.xst.
  Removed unused variable compiler warnings in Driver.xst.
  DBI::DBD module now tested during DBI build.
  Further clarification in the DBI::DBD driver writers manual.
  Added optional name parameter to $sth->fetchrow_hashref.

Changes in DBI 1.03, 1st January 1999

  Now builds with Perl>=5.005_54 (PERL_POLLUTE in DBIXS.h)
  DBI trace trims path from "at yourfile.pl line nnn".
  Trace level 1 now shows statement passed to prepare.
  Assorted improvements to the DBI manual.
  Assorted improvements to the DBI::DBD driver writers manual.
  Fixed $dbh->quote prototype to include optional $data_type.
  Fixed $dbh->prepare_cached problems.
  $dbh->selectrow_array behaves better in scalar context.
  Added a (very) experimental DBD::ADO driver for Win32 ADO.
  Added experimental thread support (perl Makefile.PL -thread).
  Updated the DBI::FAQ - thanks to Alligator Descartes.
  The following changes were implemented and/or packaged
    by Jochen Wiedmann - thanks Jochen:
  Added a Bundle for CPAN installation of DBI, the DBI proxy
    server and prerequisites (lib/Bundle/DBI.pm).
  DBI->available_drivers uses File::Spec, if available.
    This makes it work on MacOS. (DBI.pm)
  Modified type_info to work with read-only values returned
    by type_info_all. (DBI.pm)
  Added handling of magic values in $sth->execute,
    $sth->bind_param and other methods (Driver.xst)
  Added Perl's CORE directory to the linkers path on Win32,
    required by recent versions of ActiveState Perl.
  Fixed DBD::Sponge to work with empty result sets.
  Complete rewrite of DBI::ProxyServer and DBD::Proxy.

Changes in DBI 1.02, 2nd September 1998

  Fixed DBI::Shell including @ARGV and /current.
  Added basic DBI::Shell test.
  Renamed DBI::Shell /display to /format.

Changes in DBI 1.01, 2nd September 1998

  Many enhancements to Shell (with many contributions from
  Jochen Wiedmann, Tom Lowery and Adam Marks).
  Assorted fixes to DBD::Proxy and DBI::ProxyServer.
  Tidied up trace messages - trace(2) much cleaner now.
  Added $dbh->{RowCacheSize} and $sth->{RowsInCache}.
  Added experimental DBI::Format (mainly for DBI::Shell).
  Fixed fetchall_arrayref($slice_hash).
  DBI->connect now honours PrintError=1 if connect fails.
  Assorted clarifications to the docs.

Changes in DBI 1.00, 14th August 1998

  The DBI is no longer 'alpha' software!
  Added $dbh->tables and $dbh->table_info.
  Documented \%attr arg to data_sources method.
  Added $sth->{TYPE}, $sth->{PRECISION} and $sth->{SCALE}.
  Added $sth->{Statement}.
  DBI::Shell now uses neat_list to print results
  It also escapes "'" chars and converts newlines to spaces.

Changes in DBI 0.95, 10th August 1998

  WARNING: THIS IS AN EXPERIMENTAL RELEASE!
  Fixed 0.94 slip so it will build on pre-5.005 again.
  Added DBI_AUTOPROXY environment variable.
  Array ref returned from fetch/fetchrow_arrayref now readonly.
  Improved connect error reporting by DBD::Proxy.
  All trace/debug messages from DBI now go to trace file.

Changes in DBI 0.94, 9th August 1998

  WARNING: THIS IS AN EXPERIMENTAL RELEASE!
  Added DBD::Shell and dbish interactive DBI shell. Try it!
  Any database attribs can be set via DBI->connect(,,, \%attr).
  Added _get_fbav and _set_fbav methods for Perl driver developers
    (see ExampleP driver for perl usage). Drivers which don't use
    one of these methods (either via XS or Perl) are not compliant.
  DBI trace now shows adds " at yourfile.pl line nnn"!
  PrintError and RaiseError now prepend driver and method name.
  The available_drivers method no longer returns NullP or Sponge.
  Added $dbh->{Name}.
  Added $dbh->quote($value, $data_type).
  Added more hints to install_driver failure message.
  Added DBD::Proxy and DBI::ProxyServer (from Jochen Wiedmann).
  Added $DBI::neat_maxlen to control truncation of trace output.
  Added $dbh->selectall_arrayref and $dbh->selectrow_array methods.
  Added $dbh->tables.
  Added $dbh->type_info and $dbh->type_info_all.
  Added $h->trace_msg($msg) to write to trace log.
  Added @bool = DBI::looks_like_number(@ary).
  Many assorted improvements to the DBI docs.

Changes in DBI 0.93, 13th February 1998

  Fixed DBI::DBD::dbd_postamble bug causing 'Driver.xsi not found' errors.
  Changes to handling of 'magic' values in neatsvpv (used by trace).
  execute (in Driver.xst) stops binding after first bind error.
  This release requires drivers to be rebuilt.

Changes in DBI 0.92, 3rd February 1998

  Fixed per-handle memory leak (with many thanks to Irving Reid).
  Added $dbh->prepare_cached() caching variant of $dbh->prepare.
  Added some attributes:
    $h->{Active}       is the handle 'Active' (vague concept) (boolean)
    $h->{Kids}         e.g. number of sth's associated with a dbh
    $h->{ActiveKids}   number of the above which are 'Active'
    $dbh->{CachedKids} ref to prepare_cached sth cache
  Added support for general-purpose 'private_' attributes.
  Added experimental support for subclassing the DBI: see t/subclass.t
  Added SQL_ALL_TYPES to exported :sql_types.
  Added dbd_dbi_dir() and dbd_dbi_arch_dir() to DBI::DBD module so that
  DBD Makefile.PLs can work with the DBI installed in non-standard locations.
  Fixed 'Undefined value' warning and &sv_no output from neatsvpv/trace.
  Fixed small 'once per interpreter' leak.
  Assorted minor documentation fixes.

Changes in DBI 0.91, 10th December 1997

  NOTE: This fix may break some existing scripts:
  DBI->connect("dbi:...",$user,$pass) was not setting AutoCommit and PrintError!
  DBI->connect(..., { ... }) no longer sets AutoCommit or PrintError twice.
  DBI->connect(..., { RaiseError=>1 }) now croaks if connect fails.
  Fixed $fh parameter of $sth->dump_results;
  Added default statement DESTROY method which carps.
  Added default driver DESTROY method to silence AUTOLOAD/__DIE__/CGI::Carp
  Added more SQL_* types to %EXPORT_TAGS and @EXPORT_OK.
  Assorted documentation updates (mainly clarifications).
  Added workaround for perl's 'sticky lvalue' bug.
  Added better warning for bind_col(umns) where fields==0.
  Fixed to build okay with 5.004_54 with or without USE_THREADS.
  Note that the DBI has not been tested for thread safety yet.

Changes in DBI 0.90, 6th September 1997

  Can once again be built with Perl 5.003.
  The DBI class can be subclassed more easily now.
  InactiveDestroy fixed for drivers using the *.xst template.
  Slightly faster handle creation.
  Changed prototype for dbd_*_*_attrib() to add extra param.
  Note: 0.90, 0.89 and possibly some other recent versions have
  a small memory leak. This will be fixed in the next release.

Changes in DBI 0.89, 25th July 1997

  Minor fix to neatsvpv (mainly used for debug trace) to workaround
  bug in perl where SvPV removes IOK flag from an SV.
  Minor updates to the docs.

Changes in DBI 0.88, 22nd July 1997

  Fixed build for perl5.003 and Win32 with Borland.
  Fixed documentation formatting.
  Fixed DBI_DSN ignored for old-style connect (with explicit driver).
  Fixed AutoCommit in DBD::ExampleP
  Fixed $h->trace.
  The DBI can now export SQL type values: use DBI ':sql_types';
  Modified Driver.xst and renamed DBDI.h to dbd_xsh.h

Changes in DBI 0.87, 18th July 1997

  Fixed minor type clashes.
  Added more docs about placeholders and bind values.

Changes in DBI 0.86, 16th July 1997

  Fixed failed connect causing 'unblessed ref' and other errors.
  Drivers must handle AutoCommit FETCH and STORE else DBI croaks.
  Added $h->{LongReadLen} and $h->{LongTruncOk} attributes for BLOBS.
  Added DBI_USER and DBI_PASS env vars. See connect docs for usage.
  Added DBI->trace() to set global trace level (like per-handle $h->trace).
  PERL_DBI_DEBUG env var renamed DBI_DEBUG (old name still works for now).
  Updated docs, including commit, rollback, AutoCommit and Transactions sections.
  Added bind_param method and execute(@bind_values) to docs.
  Fixed fetchall_arrayref.

  Since the DBIS structure has change the internal version numbers have also
  changed (DBIXS_VERSION == 9 and DBISTATE_VERSION == 9) so drivers will have
  to be recompiled. The test is also now more sensitive and the version
  mismatch error message now more clear about what to do. Old drivers are
  likely to core dump (this time) until recompiled for this DBI. In future
  DBI/DBD version mismatch will always produce a clear error message.
  Note that this DBI release contains and documents many new features
  that won't appear in drivers for some time. Driver writers might like
  to read perldoc DBI::DBD and comment on or apply the information given.

Changes in DBI 0.85, 25th June 1997

  NOTE: New-style connect now defaults to AutoCommit mode unless
  { AutoCommit => 0 } specified in connect attributes. See the docs.
  AutoCommit attribute now defined and tracked by DBI core.
  Drivers should use/honour this and not implement their own.
  Added pod doc changes from Andreas and Jonathan.
  New DBI_DSN env var default for connect method. See docs.
  Documented the func method.
  Fixed "Usage: DBD::_::common::DESTROY" error.
  Fixed bug which set some attributes true when there value was fetched.
  Added new internal DBIc_set() macro for drivers to use.

Changes in DBI 0.84, 20th June 1997

  Added $h->{PrintError} attribute which, if set true, causes all errors to
  trigger a warn().
  New-style DBI->connect call now automatically sets PrintError=1 unless
  { PrintError => 0 } specified in the connect attributes. See the docs.
  The old-style connect with a separate driver parameter is deprecated.
  Fixed fetchrow_hashref.
  Renamed $h->debug to $h->trace() and added a trace filename arg.
  Assorted other minor tidy-ups.

Changes in DBI 0.83, 11th June 1997

  Added driver specification syntax to DBI->connect data_source
  parameter: DBI->connect('dbi:driver:...', $user, $passwd);
  The DBI->data_sources method should return data_source
  names with the appropriate 'dbi:driver:' prefix.
  DBI->connect will warn if \%attr is true but not a hash ref.
  Added the new fetchrow methods:
    @row_ary  = $sth->fetchrow_array;
    $ary_ref  = $sth->fetchrow_arrayref;
    $hash_ref = $sth->fetchrow_hashref;
  The old fetch and fetchrow methods still work.
  Driver implementors should implement the new names for
  fetchrow_array and fetchrow_arrayref ASAP (use the xs ALIAS:
  directive to define aliases for fetch and fetchrow).
  Fixed occasional problems with t/examp.t test.
  Added automatic errstr reporting to the debug trace output.
  Added the DBI FAQ from Alligator Descartes in module form for
  easy reading via "perldoc DBI::FAQ". Needs reformatting.
  Unknown driver specific attribute names no longer croak.
  Fixed problem with internal neatsvpv macro.

Changes in DBI 0.82, 23rd May 1997

  Added $h->{RaiseError} attribute which, if set true, causes all errors to
  trigger a die(). This makes it much easier to implement robust applications
  in terms of higher level eval { ... } blocks and rollbacks.
  Added DBI->data_sources($driver) method for implementation by drivers.
  The quote method now returns the string NULL (without quotes) for undef.
  Added VMS support thanks to Dan Sugalski.
  Added a 'quick start guide' to the README.
  Added neatsvpv function pointer to DBIS structure to make it available for
  use by drivers. A macro defines neatsvpv(sv,len) as (DBIS->neatsvpv(sv,len)).
  Old XS macro SV_YES_NO changes to standard boolSV.
  Since the DBIS structure has change the internal version numbers have also
  changed (DBIXS_VERSION == 8 and DBISTATE_VERSION == 8) so drivers will have
  to be recompiled.

Changes in DBI 0.81, 7th May 1997

  Minor fix to let DBI build using less modern perls.
  Fixed a suprious typo warning.

Changes in DBI 0.80, 6th May 1997

  Builds with no changes on NT using perl5.003_99 (with thanks to Jeffrey Urlwin).
  Automatically supports Apache::DBI (with thanks to Edmund Mergl).
    DBI scripts no longer need to be modified to make use of Apache::DBI.
  Added a ping method and an experimental connect_test_perf method.
  Added a fetchhash and fetch_all methods.
  The func method no longer pre-clears err and errstr.
  Added ChopBlanks attribute (currently defaults to off, that may change).
    Support for the attribute needs to be implemented by individual drivers.
  Reworked tests into standard t/*.t form.
  Added more pod text.  Fixed assorted bugs.

Changes in DBI 0.79, 7th Apr 1997

  Minor release. Tidied up pod text and added some more descriptions
  (especially disconnect). Minor changes to DBI.xs to remove compiler
  warnings.

Changes in DBI 0.78, 28th Mar 1997

  Greatly extended the pod documentation in DBI.pm, including the under
  used bind_columns method. Use 'perldoc DBI' to read after installing.
  Fixed $h->err. Fetching an attribute value no longer resets err.
  Added $h->{InactiveDestroy}, see documentation for details.
  Improved debugging of cached ('quick') attribute fetches.
  errstr will return err code value if there is no string value.
  Added DBI/W32ODBC to the distribution. This is a pure-perl experimental
  DBI emulation layer for Win32::ODBC. Note that it's unsupported, your
  mileage will vary, and bug reports without fixes will probably be ignored.

Changes in DBI 0.77, 21st Feb 1997

  Removed erroneous $h->errstate and $h->errmsg methods from DBI.pm.
  Added $h->err, $h->errstr and $h->state default methods in DBI.xs.
  Updated informal DBI API notes in DBI.pm. Updated README slightly.
  DBIXS.h now correctly installed into INST_ARCHAUTODIR.
  (DBD authors will need to edit their Makefile.PL's to use
  -I$(INSTALLSITEARCH)/auto/DBI -I$(INSTALLSITEARCH)/DBI)

Changes in DBI 0.76, 3rd Feb 1997

  Fixed a compiler type warnings (pedantic IRIX again).

Changes in DBI 0.75, 27th Jan 1997

  Fix problem introduced by a change in Perl5.003_XX.
  Updated README and DBI.pm docs.

Changes in DBI 0.74, 14th Jan 1997

  Dispatch now sets dbi_debug to the level of the current handle
  (this makes tracing/debugging individual handles much easier).
  The '>> DISPATCH' log line now only logged at debug >= 3 (was 2).
  The $csr->NUM_OF_FIELDS attribute can be set if not >0 already.
  You can log to a file using the env var PERL_DBI_DEBUG=/tmp/dbi.log.
  Added a type cast needed by IRIX.
  No longer sets perl_destruct_level unless debug set >= 4.
  Make compatible with PerlIO and sfio.

Changes in DBI 0.73, 10th Oct 1996

  Fixed some compiler type warnings (IRIX).
  Fixed DBI->internal->{DebugLog} = $filename.
  Made debug log file unbuffered.
  Added experimental bind_param_inout method to interface.
  Usage: $dbh->bind_param_inout($param, \$value, $maxlen [, \%attribs ])
  (only currently used by DBD::Oracle at this time.)

Changes in DBI 0.72, 23 Sep 1996

  Using an undefined value as a handle now gives a better
  error message (mainly useful for emulators like Oraperl).
  $dbh->do($sql, @params) now works for binding placeholders.

Changes in DBI 0.71, 10 July 1996

  Removed spurious abort() from invalid handle check.
  Added quote method to DBI interface and added test.

Changes in DBI 0.70, 16 June 1996

  Added extra invalid handle check (dbih_getcom)
  Fixed broken $dbh->quote method.
  Added check for old GCC in Makefile.PL

Changes in DBI 0.69

  Fixed small memory leak.
  Clarified the behaviour of DBI->connect.
  $dbh->do now returns '0E0' instead of 'OK'.
  Fixed "Can't read $DBI::errstr, lost last handle" problem.

Changes in DBI 0.68, 2 Mar 1996

  Changes to suit perl5.002 and site_lib directories.
  Detects old versions ahead of new in @INC.

Changes in DBI 0.67, 15 Feb 1996

  Trivial change to test suite to fix a problem shown up by the
  Perl5.002gamma release Test::Harness.

Changes in DBI 0.66, 29 Jan 1996

  Minor changes to bring the DBI into line with 5.002 mechanisms,
  specifically the xs/pm VERSION checking mechanism.
  No functionality changes. One no-last-handle bug fix (rare problem).
  Requires 5.002 (beta2 or later).

Changes in DBI 0.65, 23 Oct 1995

  Added $DBI::state to hold SQL CLI / ODBC SQLSTATE value.
  SQLSTATE "00000" (success) is returned as "" (false), all else is true.
  If a driver does not explicitly initialise it (via $h->{State} or
  DBIc_STATE(imp_xxh) then $DBI::state will automatically return "" if
  $DBI::err is false otherwise "S1000" (general error).
  As always, this is a new feature and liable to change.

  The is *no longer* a default error handler!
  You can add your own using push(@{$h->{Handlers}}, sub { ... })
  but be aware that this interface may change (or go away).

  The DBI now automatically clears $DBI::err, errstr and state before
  calling most DBI methods. Previously error conditions would persist.
  Added DBIh_CLEAR_ERROR(imp_xxh) macro.
  DBI now EXPORT_OK's some utility functions, neat($value),
  neat_list(@values) and dump_results($sth).
  Slightly enhanced t/min.t minimal test script in an effort to help
  narrow down the few stray core dumps that some porters still report.
  Renamed readblob to blob_read (old name still works but warns).
  Added default blob_copy_to_file method.
  Added $sth = $dbh->tables method. This returns an $sth for a query
  which has these columns: TABLE_CATALOGUE, TABLE_OWNER, TABLE_NAME,
  TABLE_TYPE, REMARKS in that order. The TABLE_CATALOGUE column
  should be ignored for now.

Changes in DBI 0.64, 23 Oct 1995

  Fixed 'disconnect invalidates 1 associated cursor(s)' problem.
  Drivers using DBIc_ACTIVE_on/off() macros should not need any changes
  other than to test for DBIc_ACTIVE_KIDS() instead of DBIc_KIDS().
  Fixed possible core dump in dbih_clearcom during global destruction.

Changes in DBI 0.63, 1 Sep 1995

  Minor update. Fixed uninitialised memory bug in method
  attribute handling and streamlined processing and debugging.
  Revised usage definitions for bind_* methods and readblob.

Changes in DBI 0.62, 26 Aug 1995

  Added method redirection method $h->func(..., $method_name).
  This is now the official way to call private driver methods
  that are not part of the DBI standard.  E.g.:
      @ary = $sth->func('ora_types');
  It can also be used to call existing methods. Has very low cost.

  $sth->bind_col columns now start from 1 (not 0) to match SQL.
  $sth->bind_columns now takes a leading attribute parameter (or undef),
  e.g., $sth->bind_columns($attribs, \$col1 [, \$col2 , ...]);

  Added handy DBD_ATTRIBS_CHECK macro to vet attribs in XS.
  Added handy DBD_ATTRIB_GET_SVP, DBD_ATTRIB_GET_BOOL and
  DBD_ATTRIB_GET_IV macros for handling attributes.
  Fixed STORE for NUM_OF_FIELDS and NUM_OF_PARAMS.
  Added FETCH for NUM_OF_FIELDS and NUM_OF_PARAMS.
  Dispatch no longer bothers to call _untie().
  Faster startup via install_method/_add_dispatch changes.

Changes in DBI 0.61, 22 Aug 1995

  Added $sth->bind_col($column, \$var [, \%attribs ]);

  This method enables perl variable to be directly and automatically
  updated when a row is fetched. It requires no driver support
  (if the driver has been written to use DBIS->get_fbav).
  Currently \%attribs is unused.
  Added $sth->bind_columns(\$var [, \$var , ...]);

  This method is a short-cut for bind_col which binds all the
  columns of a query in one go (with no attributes). It also
  requires no driver support.
  Added $sth->bind_param($parameter, $var [, \%attribs ]);

  This method enables attributes to be specified when values are
  bound to placeholders. It also enables binding to occur away
  from the execute method to improve execute efficiency.
  The DBI does not provide a default implementation of this.
  See the DBD::Oracle module for a detailed example.
  The DBI now provides default implementations of both fetch and
  fetchrow.  Each is written in terms of the other. A driver is
  expected to implement at least one of them.
  More macro and assorted structure changes in DBDXS.h. Sorry!
  The old dbihcom definitions have gone. All fields have macros.
  The imp_xxh_t type is now used within the DBI as well as drivers.
  Drivers must set DBIc_NUM_FIELDS(imp_sth) and DBIc_NUM_PARAMS(imp_sth).
  test.pl includes a trivial test of bind_param and bind_columns.

Changes in DBI 0.60, 17 Aug 1995

  This release has significant code changes but much less
  dramatic than the previous release. The new implementors data
  handling mechanism has matured significantly (don't be put off
  by all the struct typedefs in DBIXS.h, there's just to make it
  easier for drivers while keeping things type-safe).
  The DBI now includes two new methods:
  do            $dbh->do($statement)
  This method prepares, executes and finishes a statement. It is
  designed to be used for executing one-off non-select statements
  where there is no benefit in reusing a prepared statement handle.
  fetch         $array_ref = $sth->fetch;

  This method is the new 'lowest-level' row fetching method. The
  previous @row = $sth->fetchrow method now defaults to calling
  the fetch method and expanding the returned array reference.
  The DBI now provides fallback attribute FETCH and STORE functions
  which drivers should call if they don't recognise an attribute.
  THIS RELEASE IS A GOOD STARTING POINT FOR DRIVER DEVELOPERS!
  Study DBIXS.h from the DBI and Oracle.xs etc from DBD::Oracle.
  There will be further changes in the interface but nothing
  as dramatic as these last two releases! (I hope :-)

Changes in DBI 0.59 15 Aug 1995

  NOTE: THIS IS AN UNSTABLE RELEASE!
  Major reworking of internal data management!
  Performance improvements and memory leaks fixed.
  Added a new NullP (empty) driver and a -m flag
  to test.pl to help check for memory leaks.
  Study DBD::Oracle version 0.21 for more details.
  (Comparing parts of v0.21 with v0.20 may be useful.)

Changes in DBI 0.58 21 June 1995

  Added DBI->internal->{DebugLog} = $filename;
  Reworked internal logging.
  Added $VERSION.
  Made disconnect_all a compulsary method for drivers.

ANCIENT HISTORY

12th Oct 1994: First public release of the DBI module. (for Perl 5.000-beta-3h)

19th Sep 1994: DBperl project renamed to DBI.

29th Sep 1992: DBperl project started.


DBI::FAQ -- The Frequently Asked Questions for the Perl5 Database Interface

  • VERSION
  • DESCRIPTION
  • Basic Information & Information Sources
    • 1.1 What is DBI, DBperl, Oraperl and *perl?
    • 1.2. Where can I get it from?
    • 1.3. Where can I get more information?
  • Compilation Problems
    • 2.1. Compilation problems or "It fails the test!"
  • Platform and Driver Issues
    • 3.1 What's the difference between ODBC and DBI?
    • 3.2 What's the difference between Win32::ODBC and DBD::ODBC?
    • 3.3 Is DBI supported under Windows 95 / NT platforms?
    • 3.4 Can I access Microsoft Access or SQL-Server databases with DBI?
    • 3.5 Is the a DBD for <insert favourite database here>?
    • 3.6 What's DBM? And why should I use DBI instead?
    • 3.7 What database do you recommend me using?
    • 3.8 Is <insert feature here> supported in DBI?
  • Programming Questions
    • 4.1 Is DBI any use for CGI programming?
    • 4.2 How do I get faster connection times with DBD::Oracle and CGI?
    • 4.3 How do I get persistent connections with DBI and CGI?
    • 4.4 ``When I run a perl script from the command line, it works, but, when I run it under the httpd, it fails!'' Why?
    • 4.5 How do I get the number of rows returned from a SELECT statement?
  • Miscellaneous Questions
    • 5.1 Can I do multi-threading with DBI?
    • 5.2 How do I handle BLOB data with DBI?
    • 5.4 How can I get return values from stored procedures with DBI?
    • 5.5 How can I create or drop a database with DBI?
    • 5.6 How can I commit or rollback a statement with DBI?
    • 5.7 How are NULL values handled by DBI?
    • 5.8 What are these func() methods all about?
    • 5.9 Is DBI Year 2000 Compliant?
  • Support and Training
    • Commercial Support
    • Training
  • Other References
  • AUTHOR
  • COPYRIGHT

NAME

DBI::FAQ -- The Frequently Asked Questions for the Perl5 Database Interface

DBI Frequently Asked Questions v.0.38
Last updated: February 8th, 2000

SYNOPSIS

    perldoc DBI::FAQ

VERSION

This document is currently at version 0.38, as of February 8th, 2000.

DESCRIPTION

This document serves to answer the most frequently asked questions on both the DBI Mailing Lists and personally to members of the DBI development team.

Basic Information & Information Sources

1.1 What is DBI, DBperl, Oraperl and *perl?

To quote Tim Bunce, the architect and author of DBI:

    ``DBI is a database access Application Programming Interface (API)
      for the Perl Language. The DBI API Specification defines a set
      of functions, variables and conventions that provide a consistent
      database interface independant of the actual database being used.''

In simple language, the DBI interface allows users to access multiple database types transparently. So, if you connecting to an Oracle, Informix, mSQL, Sybase or whatever database, you don't need to know the underlying mechanics of the 3GL layer. The API defined by DBI will work on all these database types.

A similar benefit is gained by the ability to connect to two different databases of different vendor within the one perl script, ie, I want to read data from an Oracle database and insert it back into an Informix database all within one program. The DBI layer allows you to do this simply and powerfully.

Here's a diagram that demonstrates the principle:

[ DBI Architecture ]

DBperl is the old name for the interface specification. It's usually now used to denote perl4 modules on database interfacing, such as, oraperl, isqlperl, ingperl and so on. These interfaces didn't have a standard API and are generally not supported.

Here's a list of DBperl modules, their corresponding DBI counterparts and support information. Please note, the author's listed here generally do not maintain the DBI module for the same database. These email addresses are unverified and should only be used for queries concerning the perl4 modules listed below. DBI driver queries should be directed to the dbi-users mailing list.

    Module Name Database Required   Author          DBI
    ----------- -----------------   ------          ---
    Sybperl     Sybase              Michael Peppler DBD::Sybase
                                    <mpeppler@itf.ch>
    Oraperl     Oracle 6 & 7        Kevin Stock     DBD::Oracle
                                    <dbi-users@perl.org>
    Ingperl     Ingres              Tim Bunce &     DBD::Ingres
                                    Ted Lemon
                                    <dbi-users@perl.org>
    Interperl   Interbase           Buzz Moschetti  DBD::Interbase
                                    <buzz@bear.com>
    Uniperl     Unify 5.0           Rick Wargo      None
                                    <rickers@coe.drexel.edu>
    Pgperl      Postgres            Igor Metz       DBD::Pg
                                    <metz@iam.unibe.ch>
    Btreeperl   NDBM                John Conover    SDBM?
                                    <john@johncon.com>
    Ctreeperl   C-Tree              John Conover    None
                                    <john@johncon.com>
    Cisamperl   Informix C-ISAM     Mathias Koerber None
                                    <mathias@unicorn.swi.com.sg>
    Duaperl     X.500 Directory     Eric Douglas    None
                User Agent

However, some DBI modules have DBperl emulation layers, so, DBD::Oracle comes with an Oraperl emulation layer, which allows you to run legacy oraperl scripts without modification. The emulation layer translates the oraperl API calls into DBI calls and executes them through the DBI switch.

Here's a table of emulation layer information:

    Module                  Emulation Layer     Status
    ------          ---------------     ------
    DBD::Oracle     Oraperl             Complete
    DBD::Informix   Isqlperl            Under development
    DBD::Ingres     Ingperl             Complete?
    DBD::Sybase     Sybperl             Working? ( Needs verification )
    DBD::mSQL       Msqlperl            Experimentally released with
                                        DBD::mSQL-0.61

The Msqlperl emulation is a special case. Msqlperl is a perl5 driver for mSQL databases, but does not conform to the DBI Specification. It's use is being deprecated in favour of DBD::mSQL. Msqlperl may be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Msqlperl

1.2. Where can I get it from?

The Comprehensive Perl Archive Network resources should be used for retrieving up-to-date versions of the DBI and drivers. CPAN may be accessed via Tom Christiansen's splendid CPAN multiplexer program located at:

    http://www.perl.com/CPAN/

For more specific version information and exact URLs of drivers, please see the DBI drivers list and the DBI module pages which can be found on:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

This list is automatically generated on a nightly basis from CPAN and should be up-to-date.

1.3. Where can I get more information?

There are a few information sources on DBI.

"Programming the Perl DBI"

"Programming the Perl DBI" is the official book on the DBI written by Alligator Descartes and Tim Bunce and published by O'Reilly & Associates. The book was released on February 9th, 2000.

The table of contents is:

    Preface
    1. Introduction
        From Mainframes to Workstations
        Perl
        DBI in the Real World
        A Historical Interlude and Standing Stones
    2. Basic Non-DBI Databases
        Storage Managers and Layers
        Query Languages and Data Functions
        Standing Stones and the Sample Database
        Flat-File Databases
        Putting Complex Data into Flat Files
        Concurrent Database Access and Locking
        DBM Files and the Berkeley Database Manager
        The MLDBM Module
        Summary
    3. SQL and Relational Databases
        The Relational Database Methodology
        Datatypes and NULL Values
        Querying Data
        Modifying Data Within Tables
        Creating and Destroying Tables
    4. Programming with the DBI
        DBI Architecture
        Handles
        Data Source Names
        Connection and Disconnection
        Error Handling
        Utility Methods and Functions
    5. Interacting with the Database
        Issuing Simple Queries
        Executing Non-SELECT Statements
        Binding Parameters to Statements
        Binding Output Columns
        do() Versus prepare()
        Atomic and Batch Fetching
    6. Advanced DBI
        Handle Attributes and Metadata
        Handling LONG/LOB Data
        Transactions, Locking, and Isolation
    7. ODBC and the DBI
        ODBC -- Embraced and Extended
        DBI -- Thrashed and Mutated
        The Nuts and Bolts of ODBC
        ODBC from Perl
        The Marriage of DBI and ODBC
        Questions and Choices
        Moving Between Win32::ODBC and the DBI
        And What About ADO?
    8. DBI Shell and Database Proxying
        dbish -- The DBI Shell
        Database Proxying
    A. DBI Specification
    B. Driver and Database Characteristics
    C. ASLaN Sacred Site Charter
    Index

The book should be available from all good bookshops and can be ordered online either <I>via</I> O'Reilly & Associates

    http://www.oreilly.com/catalog/perldbi

or Amazon

    http://www.amazon.com/exec/obidos/ASIN/1565926994/dbi
POD documentation

PODs are chunks of documentation usually embedded within perl programs that document the code ``in place'', providing a useful resource for programmers and users of modules. POD for DBI and drivers is beginning to become more commonplace, and documentation for these modules can be read with the perldoc program included with Perl.

The DBI Specification

The POD for the DBI Specification can be read with the:

    perldoc DBI

command. The Specification also forms Appendix A of "Programming the Perl DBI".

Oraperl

Users of the Oraperl emulation layer bundled with DBD::Oracle, may read up on how to program with the Oraperl interface by typing:

    perldoc Oraperl

This will produce an updated copy of the original oraperl man page written by Kevin Stock for perl4. The oraperl API is fully listed and described there.

Drivers

Users of the DBD modules may read about some of the private functions and quirks of that driver by typing:

    perldoc <driver>

For example, the DBD::mSQL driver is bundled with driver-specific documentation that can be accessed by typing

    perldoc DBD::mSQL
Frequently Asked Questions

This document, the Frequently Asked Questions is also available as POD documentation! You can read this on your own system by typing:

    perldoc DBI::FAQ

This may be more convenient to persons not permanently, or conveniently, connected to the Internet. The DBI::FAQ module should be downloaded and installed for the more up-to-date version.

The version of DBI::FAQ shipped with the DBI module may be slightly out of date.

POD in general

Information on writing POD, and on the philosophy of POD in general, can be read by typing:

    perldoc perlpod

Users with the Tk module installed may be interested to learn there is a Tk-based POD reader available called tkpod, which formats POD in a convenient and readable way. This is available via CPAN as the module called Tk::POD and is highly recommended.

Driver and Database Characteristics

The driver summaries that were produced for Appendix B of "Programming the Perl DBI" are available online at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

in the driver information table. These summaries contain standardised information on each driver and database which should aid you in selecting a database to use. It will also inform you quickly of any issues within drivers or whether a driver is not fully compliant with the DBI Specification.

Rambles, Tidbits and Observations
    http://dbi.perl.org/tidbits
    http://www.symbolstone.org/technology/perl/DBI/tidbits

There are a series of occasional rambles from various people on the DBI mailing lists who, in an attempt to clear up a simple point, end up drafting fairly comprehensive documents. These are quite often varying in quality, but do provide some insights into the workings of the interfaces.

Articles

A list of articles discussing the DBI can be found on the DBI WWW page at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

These articles are of varying quality and age, from the original Perl Journal article written by Alligator and Tim, to more recent debacles published online from about.com.

README files

The README files included with each driver occasionally contains some useful information ( no, really! ) that may be pertinent to the user. Please read them. It makes our worthless existences more bearable. These can all be read from the main DBI WWW page at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI
Mailing Lists

There are three mailing lists for DBI:

    dbi-announce@perl.org     -- for announcements, very low traffic
    dbi-users@perl.org        -- general user support
    dbi-dev@perl.org          -- for driver developers (no user support)

For information on how to subscribe, set digest mode etc, and unsubscribe, send an email message (the content will be ignored) to:

    dbi-announce-help@perl.org
    dbi-users-help@perl.org
    dbi-dev-help@perl.org
Mailing List Archives
US Mailing List Archives
    http://outside.organic.com/mail-archives/dbi-users/

Searchable hypermail archives of the three mailing lists, and some of the much older traffic have been set up for users to browse.

European Mailing List Archives
    http://www.rosat.mpe-garching.mpg.de/mailing-lists/PerlDB-Interest

As per the US archive above.

Compilation Problems

2.1. Compilation problems or "It fails the test!"

First off, consult the README for that driver in case there is useful information about the problem. It may be a known problem for your given architecture and operating system or database. You can check the README files for each driver in advance online at:

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

If it's a known problem, you'll probably have to wait till it gets fixed. If you're really needing it fixed, try the following:

Attempt to fix it yourself

This technique is generally not recommended to the faint-hearted. If you do think you have managed to fix it, then, send a patch file ( context diff ) to the author with an explanation of:

  • What the problem was, and test cases, if possible.

  • What you needed to do to fix it. Please make sure you mention everything.

  • Platform information, database version, perl version, module version and DBI version.

Email the author Do NOT whinge!

Please email the address listed in the WWW pages for whichever driver you are having problems with. Do not directly email the author at a known address unless it corresponds with the one listed.

We tend to have real jobs to do, and we do read the mailing lists for problems. Besides, we may not have access to <insert your favourite brain-damaged platform here> and couldn't be of any assistance anyway! Apologies for sounding harsh, but that's the way of it!

However, you might catch one of these creative genii at 3am when we're doing this sort of stuff anyway, and get a patch within 5 minutes. The atmosphere in the DBI circle is that we do appreciate the users' problems, since we work in similar environments.

If you are planning to email the author, please furnish as much information as possible, ie:

  • ALL the information asked for in the README file in the problematic module. And we mean ALL of it. We don't put lines like that in documentation for the good of our health, or to meet obscure README file standards of length.

  • If you have a core dump, try the Devel::CoreStack module for generating a stack trace from the core dump. Send us that too. Devel::CoreStack can be found on CPAN at:

        http://www.perl.com/cgi-bin/cpan_mod?module=Devel::CoreStack

  • Module versions, perl version, test cases, operating system versions and any other pertinent information.

Remember, the more information you send us, the quicker we can track problems down. If you send us no useful information, expect nothing back.

Finally, please be aware that some authors, including Tim Bunce, specifically request that you do not mail them directly. Please respect their wishes and use the email addresses listed in the appropriate module README file.

Email the dbi-users Mailing List

It's usually a fairly intelligent idea to cc the mailing list anyway with problems. The authors all read the lists, so you lose nothing by mailing there.

Platform and Driver Issues

3.1 What's the difference between ODBC and DBI?

In terms of architecture - not much: Both define programming interfaces. Both allow multiple drivers to be loaded to do the actual work.

In terms of ease of use - much: The DBI is a 'high level' interface that, like Perl itself, strives to make the simple things easy while still making the hard things possible. The ODBC is a 'low level' interface. All nuts-bolts-knobs-and-dials.

Now there's an ODBC driver for the DBI (DBD::ODBC) the "What's the difference" question is more usefully rephrased as:

Chapter 7 of "Programming the Perl DBI" covers this topic in far more detail and should be consulted.

3.2 What's the difference between Win32::ODBC and DBD::ODBC?

The DBI, and thus DBD::ODBC, has a different philosophy from the Win32::ODBC module:

The Win32::ODBC module is a 'thin' layer over the low-level ODBC API. The DBI defines a simpler 'higher level' interface.

The Win32::ODBC module gives you access to more of the ODBC API. The DBI and DBD::ODBC give you access to only the essentials. (But, unlike Win32::ODBC, the DBI and DBD::ODBC do support parameter binding and multiple prepared statements which reduces the load on the database server and can dramatically increase performance.)

The Win32::ODBC module only works on Win32 systems. The DBI and DBD::ODBC are very portable and work on Win32 and Unix.

The DBI and DBD::ODBC modules are supplied as a standard part of the Perl 5.004 binary distribution for Win32 (they don't work with the older, non-standard, ActiveState port).

Scripts written with the DBI and DBD::ODBC are faster than Win32::ODBC on Win32 and are trivially portable to other supported database types.

The DBI offers optional automatic printing or die()ing on errors which
makes applications simpler and more robust.

The current DBD::ODBC driver version 0.16 is new and not yet fully stable.
A new release is due soon [relative to the date of the next TPJ issue :-]
and will be much improved and offer more ODBC functionality.

To summarise: The Win32::ODBC module is your best choice if you need access to more of the ODBC API than the DBI gives you. Otherwise, the DBI and DBD::ODBC combination may be your best bet.

Chapter 7 of "Programming the Perl DBI" covers this topic in far more detail and should be consulted.

3.3 Is DBI supported under Windows 95 / NT platforms?

Finally, yes! Jeff Urlwin has been working diligently on building DBI and DBD::ODBC under these platforms, and, with the advent of a stabler perl and a port of MakeMaker, the project has come on by great leaps and bounds.

The DBI and DBD::Oracle Win32 ports are now a standard part of DBI, so, downloading DBI of version higher than 0.81 should work fine as should using the most recent DBD::Oracle version.

3.4 Can I access Microsoft Access or SQL-Server databases with DBI?

Yes, use the DBD::ODBC driver.

3.5 Is the a DBD for <insert favourite database here>?

Is is listed on the DBI drivers page?

    http://dbi.perl.org/
    http://www.symbolstone.org/technology/perl/DBI

If not, no. A complete absence of a given database driver from that page means that no-one has announced any intention to work on it, not that such a driver is impossible to write.

A corollary of the above statement implies that if you see an announcement for a driver not on the above page, there's a good chance it's not actually a DBI driver, and may not conform to the specifications. Therefore, questions concerning problems with that code should not really be addressed to the DBI Mailing Lists.

3.6 What's DBM? And why should I use DBI instead?

Extracted from ``DBI - The Database Interface for Perl 5'':

    ``UNIX was originally blessed with simple file-based ``databases'', namely
    the dbm system. dbm lets you store data in files, and retrieve
    that data quickly. However, it also has serious drawbacks.
        File Locking
        The dbm systems did not allow particularly robust file locking
        capabilities, nor any capability for correcting problems arising through
        simultaneous writes [ to the database ].
        Arbitrary Data Structures
        The dbm systems only allows a single fixed data structure:
        key-value pairs. That value could be a complex object, such as a
        [ C ] struct, but the key had to be unique. This was a large
        limitation on the usefulness of dbm systems.
    However, dbm systems still provide a useful function for users with
    simple datasets and limited resources, since they are fast, robust and
    extremely well-tested. Perl modules to access dbm systems have now
    been integrated into the core Perl distribution via the
    AnyDBM_File module.''

To sum up, DBM is a perfectly satisfactory solution for essentially read-only databases, or small and simple datasets. However, for more scaleable dataset handling, not to mention robust transactional locking, users are recommended to use a more powerful database engine via DBI.

Chapter 2 of "Programming the Perl DBI" discusses DBM files in detail.

3.7 What database do you recommend me using?

This is a particularly thorny area in which an objective answer is difficult to come by, since each dataset, proposed usage and system configuration differs from person to person.

From the current author's point of view, if the dataset is relatively small, being tables of less than 1 million rows, and less than 1000 tables in a given database, then mSQL is a perfectly acceptable solution to your problem. This database is extremely cheap, is wonderfully robust and has excellent support. More information is available on the Hughes Technology WWW site at:

    http://www.hughes.com.au

You may also wish to look at MySQL which is a more powerful database engine that has a similar feel to mSQL.

    http://www.tcx.se

If the dataset is larger than 1 million row tables or 1000 tables, or if you have either more money, or larger machines, I would recommend Oracle RDBMS. Oracle's WWW site is an excellent source of more information.

    http://www.oracle.com

Informix is another high-end RDBMS that is worth considering. There are several differences between Oracle and Informix which are too complex for this document to detail. Information on Informix can be found on their WWW site at:

    http://www.informix.com

In the case of WWW fronted applications, mSQL may be a better option due to slow connection times between a CGI script and the Oracle RDBMS and also the amount of resource each Oracle connection will consume. mSQL is lighter resource-wise and faster.

These views are not necessarily representative of anyone else's opinions, and do not reflect any corporate sponsorship or views. They are provided as-is.

3.8 Is <insert feature here> supported in DBI?

Given that we're making the assumption that the feature you have requested is a non-standard database-specific feature, then the answer will be no.

DBI reflects a generic API that will work for most databases, and has no database-specific functionality.

However, driver authors may, if they so desire, include hooks to database-specific functionality through the func() method defined in the DBI API. Script developers should note that use of functionality provided via the func() methods is very unlikely to be portable across databases.

Programming Questions

4.1 Is DBI any use for CGI programming?

In a word, yes! DBI is hugely useful for CGI programming! In fact, I would tentatively say that CGI programming is one of two top uses for DBI.

DBI confers the ability to CGI programmers to power WWW-fronted databases to their users, which provides users with vast quantities of ordered data to play with. DBI also provides the possibility that, if a site is receiving far too much traffic than their database server can cope with, they can upgrade the database server behind the scenes with no alterations to the CGI scripts.

4.2 How do I get faster connection times with DBD::Oracle and CGI?

    Contributed by John D. Groenveld

The Apache httpd maintains a pool of httpd children to service client requests.

Using the Apache mod_perl module by Doug MacEachern, the perl interpreter is embedded with the httpd children. The CGI, DBI, and your other favorite modules can be loaded at the startup of each child. These modules will not be reloaded unless changed on disk.

For more information on Apache, see the Apache Project's WWW site:

    http://www.apache.org

The mod_perl module can be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Apache

4.3 How do I get persistent connections with DBI and CGI?

    Contributed by John D. Groenveld

Using Edmund Mergl's Apache::DBI module, database logins are stored in a hash with each of these httpd child. If your application is based on a single database user, this connection can be started with each child. Currently, database connections cannot be shared between httpd children.

Apache::DBI can be downloaded from CPAN via:

    http://www.perl.com/cgi-bin/cpan_mod?module=Apache::DBI

4.4 ``When I run a perl script from the command line, it works, but, when I run it under the httpd, it fails!'' Why?

Basically, a good chance this is occurring is due to the fact that the user that you ran it from the command line as has a correctly configured set of environment variables, in the case of DBD::Oracle, variables like ORACLE_HOME, ORACLE_SID or TWO_TASK.

The httpd process usually runs under the user id of nobody, which implies there is no configured environment. Any scripts attempting to execute in this situation will correctly fail.

One way to solve this problem is to set the environment for your database in a BEGIN { } block at the top of your script. Another technique is to configure your WWW server to pass-through certain environment variables to your CGI scripts.

Similarly, you should check your httpd error logfile for any clues, as well as the ``Idiot's Guide To Solving Perl / CGI Problems'' and ``Perl CGI Programming FAQ'' for further information. It is unlikely the problem is DBI-related.

The ``Idiot's Guide To Solving Perl / CGI Problems'' can be located at:

    http://www.perl.com/perl/faq/index.html

as can the ``Perl CGI Programming FAQ''. Read BOTH these documents carefully!

4.5 How do I get the number of rows returned from a SELECT statement?

Count them. Read the DBI docs for the rows() method.

Miscellaneous Questions

5.1 Can I do multi-threading with DBI?

Perl version 5.005 and later can be built to support multi-threading. The DBI, as of version 1.02, does not yet support multi-threading so it would be unsafe to let more than one thread enter the DBI at the same time.

It is expected that some future version of the DBI will at least be thread-safe (but not thread-hot) by automatically blocking threads intering the DBI while it's already in use.

For some OCI example code for Oracle that has multi-threaded SELECT statements, see:

    http://www.symbolstone.org/technology/oracle/oci/orathreads.tar.gz

5.2 How do I handle BLOB data with DBI?

Handling BLOB data with the DBI is very straight-forward. BLOB columns are specified in a SELECT statement as per normal columns. However, you also need to specify a maximum BLOB size that the <I>database handle</I> can fetch using the LongReadLen attribute.

For example:

    ### $dbh is a connected database handle
    $sth = $dbh->prepare( "SELECT blob_column FROM blobby_table" );
    $sth->execute;

would fail.

    ### $dbh is a connected database handle
    ### Set the maximum BLOB size...
    $dbh->{LongReadLen} = 16384;        ### 16Kb...Not much of a BLOB!

    $sth = $dbh->prepare( "..." );

would succeed <I>provided no column values were larger than the specified value</I>.

If the BLOB data is longer than the value of LongReadLen, then an error will occur. However, the DBI provides an additional piece of functionality that will automatically truncate the fetched BLOB to the size of LongReadLen if it is longer. This does not cause an error to occur, but may make your fetched BLOB data useless.

This behaviour is regulated by the LongTruncOk attribute which is defaultly set to a false value ( thus making overlong BLOB fetches fail ).

    ### Set BLOB handling such that it's 16Kb and can be truncated
    $dbh->{LongReadLen} = 16384;
    $dbh->{LongTruncOk} = 1;

Truncation of BLOB data may not be a big deal in cases where the BLOB contains run-length encoded data, but data containing checksums at the end, for example, a ZIP file, would be rendered useless.

=head2 5.3 How can I invoke stored procedures with DBI?

The DBI does not define a database-independent way of calling stored procedures.

However, most database that support them also provide a way to call them from SQL statements - and the DBI certainly supports that.

So, assuming that you have created a stored procedure within the target database, eg, an Oracle database, you can use $dbh->do() to immediately execute the procedure. For example,

    $dbh->do( "BEGIN someProcedure; END;" );   # Oracle-specific

You should also be able to prepare and execute, which is the recommended way if you'll be calling the procedure often.

5.4 How can I get return values from stored procedures with DBI?

    Contributed by Jeff Urlwin
    $sth = $dbh->prepare( "BEGIN foo(:1, :2, :3); END;" );
    $sth->bind_param(1, $a);
    $sth->bind_param_inout(2, \$path, 2000);
    $sth->bind_param_inout(3, \$success, 2000);
    $sth->execute;

Remember to perform error checking, though! ( Or use the RaiseError attribute ).

5.5 How can I create or drop a database with DBI?

Database creation and deletion are concepts that are entirely too abstract to be adequately supported by DBI. For example, Oracle does not support the concept of dropping a database at all! Also, in Oracle, the database server essentially is the database, whereas in mSQL, the server process runs happily without any databases created in it. The problem is too disparate to attack in a worthwhile way.

Some drivers, therefore, support database creation and deletion through the private func() methods. You should check the documentation for the drivers you are using to see if they support this mechanism.

5.6 How can I commit or rollback a statement with DBI?

See the commit() and rollback() methods in the DBI Specification.

Chapter 6 of "Programming the Perl DBI" discusses transaction handling within the context of DBI in more detail.

5.7 How are NULL values handled by DBI?

NULL values in DBI are specified to be treated as the value undef. NULLs can be inserted into databases as NULL, for example:

    $rv = $dbh->do( "INSERT INTO table VALUES( NULL )" );

but when queried back, the NULLs should be tested against undef. This is standard across all drivers.

5.8 What are these func() methods all about?

The func() method is defined within DBI as being an entry point for database-specific functionality, eg, the ability to create or drop databases. Invoking these driver-specific methods is simple, for example, to invoke a createDatabase method that has one argument, we would write:

    $rv =$dbh->func( 'argument', 'createDatabase' );

Software developers should note that the func() methods are non-portable between databases.

5.9 Is DBI Year 2000 Compliant?

DBI has no knowledge of understanding of what dates are. Therefore, DBI itself does not have a Year 2000 problem. Individual drivers may use date handling code internally and therefore be potentially susceptible to the Year 2000 problem, but this is unlikely.

You may also wish to read the ``Does Perl have a Year 2000 problem?'' section of the Perl FAQ at:

    http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html

Support and Training

The Perl5 Database Interface is FREE software. IT COMES WITHOUT WARRANTY OF ANY KIND. See the DBI README for more details.

However, some organizations are providing either technical support or training programs on DBI. The present author has no knowledge as to the quality of these services. The links are included for reference purposes only and should not be regarded as recommendations in any way. Caveat emptor.

Commercial Support

The Perl Clinic

The Perl Clinic provides commercial support for Perl and Perl related problems, including the DBI and its drivers. Support is provided by the company with whom Tim Bunce, author of DBI and DBD::Oracle, works and ActiveState. For more information on their services, please see:

    http://www.perlclinic.com

Training

Westlake Solutions

A hands-on class for experienced Perl CGI developers that teaches how to write database-connected CGI scripts using Perl and DBI.pm. This course, along with four other courses on CGI scripting with Perl, is taught in Washington, DC; Arlington, Virginia; and on-site worldwide upon request.

See:

    http://www.westlake.com/training

for more details.

Other References

In this section, we present some miscellaneous WWW links that may be of some interest to DBI users. These are not verified and may result in unknown sites or missing documents.

    http://www-ccs.cs.umass.edu/db.html
    http://www.odmg.org/odmg93/updates_dbarry.html
    http://www.jcc.com/sql_stnd.html

AUTHOR

Alligator Descartes <http://www.symbolstone.org/descarte/contact.html>. Portions are Copyright their original stated authors.

COPYRIGHT

This document is Copyright (c)1994-2000 Alligator Descartes, with portions Copyright (c)1994-2000 their original authors. This module is released under the 'Artistic' license which you can find in the perl distribution.

This document is Copyright (c)1997-2000 Alligator Descartes. All rights reserved. Permission to distribute this document, in full or in part, via email, Usenet, ftp archives or http is granted providing that no charges are involved, reasonable attempt is made to use the most current version and all credits and copyright notices are retained ( the AUTHOR and COPYRIGHT sections ). Requests for other distribution rights, including incorporation into commercial products, such as books, magazine articles or CD-ROMs should be made to Alligator Descartes <http://www.symbolstone.org/descarte/contact.html>.


DBI::Profile - Performance profiling and benchmarking for the DBI

  • OVERVIEW
  • ENABLING A PROFILE
  • THE PROFILE OBJECT
    • Data
    • Path
  • REPORTING
    • Report Format
    • Report Destination
  • CHILD HANDLES
  • CUSTOM DATA MANIPULATION
    • dbi_profile_merge
  • CUSTOM DATA COLLECTION
    • Using The Path Attribute
    • Adding Your Own Samples
  • SUBCLASSING
  • CAVEATS

NAME

DBI::Profile - Performance profiling and benchmarking for the DBI

SYNOPSIS

The easiest way to enable DBI profiling is to set the DBI_PROFILE environment variable to 2 and then run your code as usual:

  DBI_PROFILE=2 prog.pl

This will profile your program and then output a textual summary grouped by query when the program exits. You can also enable profiling by setting the Profile attribute of any DBI handle:

  $dbh->{Profile} = 2;

Then the summary will be printed when the handle is destroyed.

Many other values apart from are possible - see ENABLING A PROFILE below.

DESCRIPTION

The DBI::Profile module provides a simple interface to collect and report performance and benchmarking data from the DBI.

For a more elaborate interface, suitable for larger programs, see DBI::ProfileDumper and dbiprof. For Apache/mod_perl applications see DBI::ProfileDumper::Apache.

OVERVIEW

Performance data collection for the DBI is built around several concepts which are important to understand clearly.

Method Dispatch

Every method call on a DBI handle passes through a single 'dispatch' function which manages all the common aspects of DBI method calls, such as handling the RaiseError attribute.

Data Collection

If profiling is enabled for a handle then the dispatch code takes a high-resolution timestamp soon after it is entered. Then, after calling the appropriate method and just before returning, it takes another high-resolution timestamp and calls a function to record the information. That function is passed the two timestamps plus the DBI handle and the name of the method that was called. That data about a single DBI method call is called a profile sample.

Data Filtering

If the method call was invoked by the DBI or by a driver then the call is ignored for profiling because the time spent will be accounted for by the original 'outermost' call for your code.

For example, the calls that the selectrow_arrayref() method makes to prepare() and execute() etc. are not counted individually because the time spent in those methods is going to be allocated to the selectrow_arrayref() method when it returns. If this was not done then it would be very easy to double count time spent inside the DBI.

Data Storage Tree

The profile data is accumulated as 'leaves on a tree'. The 'path' through the branches of the tree to a particular leaf is determined dynamically for each sample. This is a key feature of DBI profiliing.

For each profiled method call the DBI walks along the Path and uses each value in the Path to step into and grow the Data tree.

For example, if the Path is

  [ 'foo', 'bar', 'baz' ]

then the new profile sample data will be merged into the tree at

  $h->{Profile}->{Data}->{foo}->{bar}->{baz}

But it's not very useful to merge all the call data into one leaf node (except to get an overall 'time spent inside the DBI' total). It's more common to want the Path to include dynamic values such as the current statement text and/or the name of the method called to show what the time spent inside the DBI was for.

The Path can contain some 'magic cookie' values that are automatically replaced by corresponding dynamic values when they're used. These magic cookies always start with a punctuation character.

For example a value of '!MethodName' in the Path causes the corresponding entry in the Data to be the name of the method that was called. For example, if the Path was:

  [ 'foo', '!MethodName', 'selectall_arrayref' ]

and the selectall_arrayref() method was called, then the profile sample data for that call will be merged into the tree at:

  $h->{Profile}->{Data}->{foo}->{selectall_arrayref}->{bar}
Profile Data

Profile data is stored at the 'leaves' of the tree as references to an array of numeric values. For example:

  [
    106,                  # 0: count of samples at this node
    0.0312958955764771,   # 1: total duration
    0.000490069389343262, # 2: first duration
    0.000176072120666504, # 3: shortest duration
    0.00140702724456787,  # 4: longest duration
    1023115819.83019,     # 5: time of first sample
    1023115819.86576,     # 6: time of last sample
  ]

After the first sample, later samples always update elements 0, 1, and 6, and may update 3 or 4 depending on the duration of the sampled call.

ENABLING A PROFILE

Profiling is enabled for a handle by assigning to the Profile attribute. For example:

  $h->{Profile} = DBI::Profile->new();

The Profile attribute holds a blessed reference to a hash object that contains the profile data and attributes relating to it.

The class the Profile object is blessed into is expected to provide at least a DESTROY method which will dump the profile data to the DBI trace file handle (STDERR by default).

All these examples have the same effect as each other:

  $h->{Profile} = 0;
  $h->{Profile} = "/DBI::Profile";
  $h->{Profile} = DBI::Profile->new();
  $h->{Profile} = {};
  $h->{Profile} = { Path => [] };

Similarly, these examples have the same effect as each other:

  $h->{Profile} = 6;
  $h->{Profile} = "6/DBI::Profile";
  $h->{Profile} = "!Statement:!MethodName/DBI::Profile";
  $h->{Profile} = { Path => [ '!Statement', '!MethodName' ] };

If a non-blessed hash reference is given then the DBI::Profile module is automatically require'd and the reference is blessed into that class.

If a string is given then it is processed like this:

    ($path, $module, $args) = split /\//, $string, 3
    @path = split /:/, $path
    @args = split /:/, $args
    eval "require $module" if $module
    $module ||= "DBI::Profile"
    $module->new( Path => \@Path, @args )

So the first value is used to select the Path to be used (see below). The second value, if present, is used as the name of a module which will be loaded and it's new method called. If not present it defaults to DBI::Profile. Any other values are passed as arguments to the new method. For example: "2/DBIx::OtherProfile/Foo:42".

Numbers can be used as a shorthand way to enable common Path values. The simplest way to explain how the values are interpreted is to show the code:

    push @Path, "DBI"           if $path_elem & 0x01;
    push @Path, "!Statement"    if $path_elem & 0x02;
    push @Path, "!MethodName"   if $path_elem & 0x04;
    push @Path, "!MethodClass"  if $path_elem & 0x08;
    push @Path, "!Caller2"      if $path_elem & 0x10;

So "2" is the same as "!Statement" and "6" (2+4) is the same as "!Statement:!Method". Those are the two most commonly used values. Using a negative number will reverse the path. Thus "-6" will group by method name then statement.

The spliting and parsing of string values assigned to the Profile attribute may seem a little odd, but there's a good reason for it. Remember that attributes can be embedded in the Data Source Name string which can be passed in to a script as a parameter. For example:

    dbi:DriverName(Profile=>2):dbname
    dbi:DriverName(Profile=>{Username}:!Statement/MyProfiler/Foo:42):dbname

And also, if the DBI_PROFILE environment variable is set then The DBI arranges for every driver handle to share the same profile object. When perl exits a single profile summary will be generated that reflects (as nearly as practical) the total use of the DBI by the application.

THE PROFILE OBJECT

The DBI core expects the Profile attribute value to be a hash reference and if the following values don't exist it will create them as needed:

Data

A reference to a hash containing the collected profile data.

Path

The Path value is a reference to an array. Each element controls the value to use at the corresponding level of the profile Data tree.

The elements of Path array can be one of the following types:

Special Constant

!Statement

Use the current Statement text. Typically that's the value of the Statement attribute for the handle the method was called with. Some methods, like commit() and rollback(), are unrelated to a particular statement. For those methods !Statement records an empty string.

For statement handles this is always simply the string that was given to prepare() when the handle was created. For database handles this is the statement that was last prepared or executed on that database handle. That can lead to a little 'fuzzyness' because, for example, calls to the quote() method to build a new statement will typically be associated with the previous statement. In practice this isn't a significant issue and the dynamic Path mechanism can be used to setup your own rules.

!MethodName

Use the name of the DBI method that the profile sample relates to.

!MethodClass

Use the fully qualified name of the DBI method, including the package, that the profile sample relates to. This shows you where the method was implemented. For example:

  'DBD::_::db::selectrow_arrayref' =>
      0.022902s
  'DBD::mysql::db::selectrow_arrayref' =>
      2.244521s / 99 = 0.022445s avg (first 0.022813s, min 0.022051s, max 0.028932s)

The "DBD::_::db::selectrow_arrayref" shows that the driver has inherited the selectrow_arrayref method provided by the DBI.

But you'll note that there is only one call to DBD::_::db::selectrow_arrayref but another 99 to DBD::mysql::db::selectrow_arrayref. Currently the first call Pern't record the true location. That may change.

!Caller

Use a string showing the filename and line number of the code calling the method.

!Caller2

Use a string showing the filename and line number of the code calling the method, as for !Caller, but also include filename and line number of the code that called that. Calls from DBI:: and DBD:: packages are skipped.

!File

Same as !Caller above except that only the filename is included, not the line number.

!File2

Same as !Caller2 above except that only the filenames are included, not the line number.

Code Reference

Not yet implemented.

The subroutine is passed the DBI method name and the handle it was called on. It should return a list of values to used at this point in the Path. If it returns an empty list then the method call is not profiled.

Attribute Specifier

A string enclosed in braces, such as '{Username}', specifies that the current value of the corresponding database handle attribute should be used at that point in the Path.

Other Values

Any other values are stringified and used literally.

(References, and values that begin with punctuation characters are reserved.)

Only the first 100 elements in Path are used.

If the value of Path is anything other than an array reference, it is treated as if it was:

        [ DBI::Profile::!Statement ]

REPORTING

Report Format

The current accumulated profile data can be formatted and output using

    print $h->{Profile}->format;

To discard the profile data and start collecting fresh data you can do:

    $h->{Profile}->{Data} = undef;

The default results format looks like this:

  DBI::Profile: 0.001015s 42.7% (5 calls) programname @ YYYY-MM-DD HH:MM:SS
  '' =>
      0.000024s / 2 = 0.000012s avg (first 0.000015s, min 0.000009s, max 0.000015s)
  'SELECT mode,size,name FROM table' =>
      0.000991s / 3 = 0.000330s avg (first 0.000678s, min 0.000009s, max 0.000678s)

Which shows the total time spent inside the DBI, with a count of the total number of method calls and the name of the script being run, then a formated version of the profile data tree.

If the results are being formated when the perl process is exiting (which is usually the case when the DBI_PROFILE environment variable is used) then the percentage of time the process spent inside the DBI is also shown. If the process is not exiting then the percentage is calculated using the time between the first and last call to the DBI.

In the example above the paths in the tree are only one level deep and use the Statement text as the value (that's the default behaviour).

The merged profile data at the 'leaves' of the tree are presented as total time spent, count, average time spent (which is simply total time divided by the count), then the time spent on the first call, the time spent on the fastest call, and finally the time spent on the slowest call.

The 'avg', 'first', 'min' and 'max' times are not particularly useful when the profile data path only contains the statement text. Here's an extract of a more detailed example using both statement text and method name in the path:

  'SELECT mode,size,name FROM table' =>
      'FETCH' =>
          0.000076s
      'fetchrow_hashref' =>
          0.036203s / 108 = 0.000335s avg (first 0.000490s, min 0.000152s, max 0.002786s)

Here you can see the 'avg', 'first', 'min' and 'max' for the 108 calls to fetchrow_hashref() become rather more interesting. Also the data for FETCH just shows a time value because it was only called once.

Currently the profile data is output sorted by branch names. That may change in a later version so the leaf nodes are sorted by total time per leaf node.

Report Destination

The default method of reporting is for the DESTROY method of the Profile object to format the results and write them using:

    DBI->trace_msg($results, 0);  # see $ON_DESTROY_DUMP below

to write them to the DBI trace() filehandle (which defaults to STDERR). To direct the DBI trace filehandle to write to a file without enabling tracing the trace() method can be called with a trace level of 0. For example:

    DBI->trace(0, $filename);

The same effect can be achieved without changing the code by setting the DBI_TRACE environment variable to 0=filename.

The $DBI::Profile::ON_DESTROY_DUMP variable holds a code ref that's called to perform the output of the formatted results. The default value is:

  $ON_DESTROY_DUMP = sub { DBI->trace_msg($results, 0) };

Apart from making it easy to send the dump elsewhere, it can also be useful as a simple way to disable dumping results.

CHILD HANDLES

Child handles inherit a reference to the Profile attribute value of their parent. So if profiling is enabled for a database handle then by default the statement handles created from it all contribute to the same merged profile data tree.

CUSTOM DATA MANIPULATION

Recall that $h-{Profile}->{Data}> is a reference to the collected data. Either to a 'leaf' array (when the Path is empty, i.e., DBI_PROFILE env var is 1), or a reference to hash containing values that are either further hash references or leaf array references.

Sometimes it's useful to be able to summarise some or all of the collected data. The dbi_profile_merge() function can be used to merge leaf node values.

dbi_profile_merge

  use DBI qw(dbi_profile_merge);

  $time_in_dbi = dbi_profile_merge(my $totals=[], @$leaves);

Merges profile data node. Given a reference to a destination array, and zero or more references to profile data, merges the profile data into the destination array. For example:

  $time_in_dbi = dbi_profile_merge(
      my $totals=[],
      [ 10, 0.51, 0.11, 0.01, 0.22, 1023110000, 1023110010 ],
      [ 15, 0.42, 0.12, 0.02, 0.23, 1023110005, 1023110009 ],
  );

$totals will then contain

  [ 25, 0.93, 0.11, 0.01, 0.23, 1023110000, 1023110010 ]

and $time_in_dbi will be 0.93;

For example, to get the time spent 'inside' the DBI during an http request, your logging code run at the end of the request (i.e. mod_perl LogHandler) could use:

  my $time_in_dbi = 0;
  if (my $Profile = $dbh->{Profile}) { # if DBI profiling is enabled
      $time_in_dbi = dbi_profile_merge(my $total=[], $Profile->{Data});
      $Profile->{Data} = {}; # reset the profile data
  }

If profiling has been enabled then $time_in_dbi will hold the time spent inside the DBI for that handle (and any other handles that share the same profile data) since the last request.

CUSTOM DATA COLLECTION

Using The Path Attribute

  XXX example to be added later using a selectall_arrayref call
  XXX nested inside a fetch loop where the first column of the
  XXX outer loop is bound to the profile Path using
  XXX bind_column(1, \${ $dbh->{Profile}->{Path}->[0] })
  XXX so you end up with separate profiles for each loop
  XXX (patches welcome to add this to the docs :)

Adding Your Own Samples

The dbi_profile() function can be used to add extra sample data into the profile data tree. For example:

    use DBI;
    use DBI::Profile (dbi_profile dbi_time);

    my $t1 = dbi_time(); # floating point high-resolution time

    ... execute code you want to profile here ...
    my $t2 = dbi_time();
    dbi_profile($h, $statement, $method, $t1, $t2);

The $h parameter is the handle the extra profile sample should be associated with. The $statement parameter is the string to use where the Path specifies !Statement. If $statement is undef then $h->{Statement} will be used. Similarly $method is the string to use if the Path specifies !MethodName. There is no default value for $method.

The $h->{Profile}{Path} attribute is processed by dbi_profile() in the usual way.

It is recommended that you keep these extra data samples separate from the DBI profile data samples by using values for $statement and $method that are distinct from any that are likely to appear in the profile data normally.

SUBCLASSING

Alternate profile modules must subclass DBI::Profile to help ensure they work with future versions of the DBI.

CAVEATS

Applications which generate many different statement strings (typically because they don't use placeholders) and profile with !Statement in the Path (the default) will consume memory in the Profile Data structure for each statement. Use a code ref in the Path to return an edited (simplified) form of the statement.

If a method throws an exception itself (not via RaiseError) then it won't be counted in the profile.

If a HandleError subroutine throws an exception (rather than returning 0 and letting RaiseError do it) then the method call won't be counted in the profile.

Time spent in DESTROY is added to the profile of the parent handle.

Time spent in DBI->*() methods is not counted. The time spent in the driver connect method, $drh->connect(), when it's called by DBI->connect is counted if the DBI_PROFILE environment variable is set.

Time spent fetching tied variables, $DBI::errstr, is counted.

Time spent in FETCH for $h->{Profile} is not counted, so getting the profile data doesn't alter it.

DBI::PurePerl does not support profiling (though it could in theory).

A few platforms don't support the gettimeofday() high resolution time function used by the DBI (and available via the dbi_time() function). In which case you'll get integer resolution time which is mostly useless.

On Windows platforms the dbi_time() function is limited to millisecond resolution. Which isn't sufficiently fine for our needs, but still much better than integer resolution. This limited resolution means that fast method calls will often register as taking 0 time. And timings in general will have much more 'jitter' depending on where within the 'current millisecond' the start and and timing was taken.

This documentation could be more clear. Probably needs to be reordered to start with several examples and build from there. Trying to explain the concepts first seems painful and to lead to just as many forward references. (Patches welcome!)


DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

  • METHODS
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileData - manipulate DBI::ProfileDumper data dumps

SYNOPSIS

The easiest way to use this module is through the dbiprof frontend (see the dbiprof manpage for details):

  dbiprof --number 15 --sort count

This module can also be used to roll your own profile analysis:

  # load data from dbi.prof
  $prof = DBI::ProfileData->new(File => "dbi.prof");

  # get a count of the records in the data set
  $count = $prof->count();

  # sort by longest overall time
  $prof->sort(field => "longest");

  # sort by longest overall time, least to greatest
  $prof->sort(field => "longest", reverse => 1);

  # exclude records with key2 eq 'disconnect'
  $prof->exclude(key2 => 'disconnect');

  # exclude records with key1 matching /^UPDATE/i
  $prof->exclude(key1 => qr/^UPDATE/i);

  # remove all records except those where key1 matches /^SELECT/i
  $prof->match(key1 => qr/^SELECT/i);

  # produce a formatted report with the given number of items
  $report = $prof->report(number => 10);

  # clone the profile data set
  $clone = $prof->clone();

  # get access to hash of header values
  $header = $prof->header();

  # get access to sorted array of nodes
  $nodes = $prof->nodes();

  # format a single node in the same style as report()
  $text = $prof->format($nodes->[0]);

  # get access to Data hash in DBI::Profile format
  $Data = $prof->Data();

DESCRIPTION

This module offers the ability to read, manipulate and format DBI::ProfileDumper profile data.

Conceptually, a profile consists of a series of records, or nodes, each of each has a set of statistics and set of keys. Each record must have a unique set of keys, but there is no requirement that every record have the same number of keys.

METHODS

The following methods are supported by DBI::ProfileData objects.

$prof = DBI::ProfileData->new(File => "dbi.prof")
$prof = DBI::ProfileData->new(File => "dbi.prof", Filter => sub { ... })
$prof = DBI::ProfileData->new(Files => [ "dbi.prof.1", "dbi.prof.2" ])

Creates a a new DBI::ProfileData object. Takes either a single file through the File option or a list of Files in an array ref. If multiple files are specified then the header data from the first file is used.

The Filter parameter can be used to supply a code reference that can manipulate the profile data as it is being read. This is most useful for editing SQL statements so that slightly different statements in the raw data will be merged and aggregated in the loaded data. For example:

  Filter => sub {
      my ($path_ref, $data_ref) = @_;
      s/foo = '.*?'/foo = '...'/ for @$path_ref;
  }

Here's an example that performs some normalization on the SQL. It converts all numbers to N and all quoted strings to S. It can also convert digits to N within names. Finally, it summarizes long "IN (...)" clauses.

It's aggressive and simplistic, but it's often sufficient, and serves as an example that you can tailor to suit your own needs:

  Filter => sub {
      my ($path_ref, $data_ref) = @_;
      local $_ = $path_ref->[0]; # whichever element contains the SQL Statement
      s/\b\d+\b/N/g;             # 42 -> N
      s/\b0x[0-9A-Fa-f]+\b/N/g;  # 0xFE -> N
      s/'.*?'/'S'/g;             # single quoted strings (doesn't handle escapes)
      s/".*?"/"S"/g;             # double quoted strings (doesn't handle escapes)
      # convert names like log_20001231 into log_NNNNNNNN, controlled by $opt{n}
      s/([a-z_]+)(\d{$opt{n},})/$1.('N' x length($2))/ieg if $opt{n};
      # abbreviate massive "in (...)" statements and similar
      s!(([NS],){100,})!sprintf("$2,{repeated %d times}",length($1)/2)!eg;
  }

It's often better to perform this kinds of normalization in the DBI while the data is being collected, to avoid too much memory being used by storing profile data for many different SQL statement. See the DBI::Profile manpage.

$copy = $prof->clone();

Clone a profile data set creating a new object.

$header = $prof->header();

Returns a reference to a hash of header values. These are the key value pairs included in the header section of the DBI::ProfileDumper data format. For example:

  $header = {
    Path    => [ '!Statement', '!MethodName' ],
    Program => 't/42profile_data.t',
  };

Note that modifying this hash will modify the header data stored inside the profile object.

$nodes = $prof->nodes()

Returns a reference the sorted nodes array. Each element in the array is a single record in the data set. The first seven elements are the same as the elements provided by DBI::Profile. After that each key is in a separate element. For example:

 $nodes = [
            [
              2,                      # 0, count
              0.0312958955764771,     # 1, total duration
              0.000490069389343262,   # 2, first duration
              0.000176072120666504,   # 3, shortest duration
              0.00140702724456787,    # 4, longest duration
              1023115819.83019,       # 5, time of first event
              1023115819.86576,       # 6, time of last event
              'SELECT foo FROM bar'   # 7, key1
              'execute'               # 8, key2
                                      # 6+N, keyN
            ],
                                      # ...
          ];

Note that modifying this array will modify the node data stored inside the profile object.

$count = $prof->count()

Returns the number of items in the profile data set.

$prof->sort(field => "field")
$prof->sort(field => "field", reverse => 1)

Sorts data by the given field. Available fields are:

  longest
  total
  count
  shortest

The default sort is greatest to smallest, which is the opposite of the normal Perl meaning. This, however, matches the expected behavior of the dbiprof frontend.

$count = $prof->exclude(key2 => "disconnect")
$count = $prof->exclude(key2 => "disconnect", case_sensitive => 1)
$count = $prof->exclude(key1 => qr/^SELECT/i)

Removes records from the data set that match the given string or regular expression. This method modifies the data in a permanent fashion - use clone() first to maintain the original data after exclude(). Returns the number of nodes left in the profile data set.

$count = $prof->match(key2 => "disconnect")
$count = $prof->match(key2 => "disconnect", case_sensitive => 1)
$count = $prof->match(key1 => qr/^SELECT/i)

Removes records from the data set that do not match the given string or regular expression. This method modifies the data in a permanent fashion - use clone() first to maintain the original data after match(). Returns the number of nodes left in the profile data set.

$Data = $prof->Data()

Returns the same Data hash structure as seen in DBI::Profile. This structure is not sorted. The nodes() structure probably makes more sense for most analysis.

$text = $prof->format($nodes->[0])

Formats a single node into a human-readable block of text.

$text = $prof->report(number => 10)

Produces a report with the given number of items.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


DBI::ProfileDumper - profile DBI usage and output data to a file

  • USAGE
  • METHODS
  • DATA FORMAT
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileDumper - profile DBI usage and output data to a file

SYNOPSIS

To profile an existing program using DBI::ProfileDumper, set the DBI_PROFILE environment variable and run your program as usual. For example, using bash:

  DBI_PROFILE=2/DBI::ProfileDumper program.pl

Then analyze the generated file (dbi.prof) with dbiprof:

  dbiprof

You can also activate DBI::ProfileDumper from within your code:

  use DBI;

  # profile with default path (2) and output file (dbi.prof)
  $dbh->{Profile} = "2/DBI::ProfileDumper";

  # same thing, spelled out
  $dbh->{Profile} = "2/DBI::ProfileDumper/File:dbi.prof";

  # another way to say it
  use DBI::Profile;
  $dbh->{Profile} = DBI::ProfileDumper->new(
                        Path => [ '!Statement' ]
                        File => 'dbi.prof' );

  # using a custom path
  $dbh->{Profile} = DBI::ProfileDumper->new( Path => [ "foo", "bar" ],
                                             File => 'dbi.prof' );

DESCRIPTION

DBI::ProfileDumper is a subclass of DBI::Profile which dumps profile data to disk instead of printing a summary to your screen. You can then use dbiprof to analyze the data in a number of interesting ways, or you can roll your own analysis using DBI::ProfileData.

NOTE: For Apache/mod_perl applications, use DBI::ProfileDumper::Apache.

USAGE

One way to use this module is just to enable it in your $dbh:

  $dbh->{Profile} = "1/DBI::ProfileDumper";

This will write out profile data by statement into a file called dbi.prof. If you want to modify either of these properties, you can construct the DBI::ProfileDumper object yourself:

  use DBI::Profile;
  $dbh->{Profile} = DBI::ProfileDumper->new(
                        Path => [ '!Statement' ]
                        File => 'dbi.prof' );

The Path option takes the same values as in the DBI::Profile manpage. The File option gives the name of the file where results will be collected. If it already exists it will be overwritten.

You can also activate this module by setting the DBI_PROFILE environment variable:

  $ENV{DBI_PROFILE} = "!Statement/DBI::ProfileDumper";

This will cause all DBI handles to share the same profiling object.

METHODS

The following methods are available to be called using the profile object. You can get access to the profile object from the Profile key in any DBI handle:

  my $profile = $dbh->{Profile};
$profile->flush_to_disk()

Flushes all collected profile data to disk and empties the Data hash. This method may be called multiple times during a program run.

$profile->empty()

Clears the Data hash without writing to disk.

DATA FORMAT

The data format written by DBI::ProfileDumper starts with a header containing the version number of the module used to generate it. Then a block of variable declarations describes the profile. After two newlines, the profile data forms the body of the file. For example:

  DBI::ProfileDumper 1.0
  Path = [ '!Statement', '!MethodName' ]
  Program = t/42profile_data.t
  + 1 SELECT name FROM users WHERE id = ?
  + 2 prepare
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 execute
  1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 fetchrow_hashref
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 1 UPDATE users SET name = ? WHERE id = ?
  + 2 prepare
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576
  + 2 execute
  = 1 0.0312958955764771 0.000490069389343262 0.000176072120666504 0.00140702724456787 1023115819.83019 1023115819.86576

The lines beginning with + signs signify keys. The number after the + sign shows the nesting level of the key. Lines beginning with = are the actual profile data, in the same order as in DBI::Profile.

Note that the same path may be present multiple times in the data file since format() may be called more than once. When read by DBI::ProfileData the data points will be merged to produce a single data set for each distinct path.

The key strings are transformed in three ways. First, all backslashes are doubled. Then all newlines and carriage-returns are transformed into \n and \r respectively. Finally, any NULL bytes (\0) are entirely removed. When DBI::ProfileData reads the file the first two transformations will be reversed, but NULL bytes will not be restored.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


DBI::ProfileDumper::Apache - capture DBI profiling data from Apache/mod_perl

  • USAGE
    • LOADING THE MODULE
    • GATHERING PROFILE DATA
    • CLEANING UP
  • MEMORY USAGE
  • AUTHOR
  • COPYRIGHT AND LICENSE

NAME

DBI::ProfileDumper::Apache - capture DBI profiling data from Apache/mod_perl

SYNOPSIS

Add this line to your httpd.conf:

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache

Under mod_perl2 RC5+ you'll need to also add:

  PerlSetEnv DBI_PROFILE_APACHE_LOG_DIR /server_root/logs

OR add

  PerlOptions +GlobalRequest

to the gobal config section you're about test with DBI::ProfileDumper::Apache. If you don't do this, you'll see messages in your error_log similar to:

  DBI::ProfileDumper::Apache on_destroy failed: Global $r object is not available. Set:
    PerlOptions +GlobalRequest in httpd.conf at ..../DBI/ProfileDumper/Apache.pm line 144

Then restart your server. Access the code you wish to test using a web browser, then shutdown your server. This will create a set of dbi.prof.* files in your Apache log directory. Get a profiling report with dbiprof:

  dbiprof /usr/local/apache/logs/dbi.prof.*

When you're ready to perform another profiling run, delete the old files

  rm /usr/local/apache/logs/dbi.prof.*

and start again.

DESCRIPTION

This module interfaces DBI::ProfileDumper to Apache/mod_perl. Using this module you can collect profiling data from mod_perl applications. It works by creating a DBI::ProfileDumper data file for each Apache process. These files are created in your Apache log directory. You can then use dbiprof to analyze the profile files.

USAGE

LOADING THE MODULE

The easiest way to use this module is just to set the DBI_PROFILE environment variable in your httpd.conf:

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache

If you want to use one of DBI::Profile's other Path settings, you can use a string like:

  PerlSetEnv DBI_PROFILE 2/DBI::ProfileDumper::Apache

It's also possible to use this module by setting the Profile attribute of any DBI handle:

  $dbh->{Profile} = "2/DBI::ProfileDumper::Apache";

See the DBI::ProfileDumper manpage for more possibilities.

GATHERING PROFILE DATA

Once you have the module loaded, use your application as you normally would. Stop the webserver when your tests are complete. Profile data files will be produced when Apache exits and you'll see something like this in your error_log:

  DBI::ProfileDumper::Apache writing to /usr/local/apache/logs/dbi.prof.2619

Now you can use dbiprof to examine the data:

  dbiprof /usr/local/apache/logs/dbi.prof.*

By passing dbiprof a list of all generated files, dbiprof will automatically merge them into one result set. You can also pass dbiprof sorting and querying options, see the dbiprof manpage for details.

CLEANING UP

Once you've made some code changes, you're ready to start again. First, delete the old profile data files:

  rm /usr/local/apache/logs/dbi.prof.*

Then restart your server and get back to work.

MEMORY USAGE

DBI::Profile can use a lot of memory for very active applications. It collects profiling data in memory for each distinct query your application runs. You can avoid this problem with a call like this:

  $dbh->{Profile}->flush_to_disk() if $dbh->{Profile};

Calling flush_to_disk() will clear out the profile data and write it to disk. Put this someplace where it will run on every request, like a CleanupHandler, and your memory troubles should go away. Well, at least the ones caused by DBI::Profile anyway.

AUTHOR

Sam Tregar <sam@tregar.com>

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.


ActivePerl - ActiveState's quality-assured binary build of Perl

  • SEE ALSO

NAME

ActivePerl - ActiveState's quality-assured binary build of Perl

DESCRIPTION

ActivePerl is ActiveState's quality-assured binary build of Perl, available for AIX, HP-UX, Linux, Mac OS X, Solaris and Windows. ActivePerl includes:

  • The binary core distribution of perl. See the perl manpage for details.

  • A set of useful additional CPAN modules "out of the box".

  • The Perl Package Manager, for quick and easy install of additional Perl extension modules. See the ppm manpage for details.

  • Complete documentation in HTML format. This is found in the html sub directory where ActivePerl was installed.

The release notes for this version of ActivePerl is available in the activeperl-release manpage. A list of changes beween builds of ActivePerl is found in the activeperl-changes manpage.

SEE ALSO

the perl manpage, the ppm manpage, the activeperl-release manpage, the activeperl-changes manpage


ActivePerl 5.8 Change Log

  • ActivePerl 5.8 Change Log
    • Build 820 Wednesday, Jan 24, 2007
    • Build 819 Wednesday, Aug 31, 2006
    • Build 818 Wednesday, Aug 16, 2006
    • Build 817.91 (818 Beta 2) Wednesday, Jul 19, 2006
    • Build 817.90 (818 Beta 1) Wednesday, May 31, 2006
    • Build 817 Wednesday, Mar 22, 2006
    • Build 816 Thursday, Mar 2, 2006
    • Build 815 Wednesday, Nov 2, 2005
    • Build 814 Beta Tuesday, Jun 28, 2005
    • Build 813 Tuesday, Jun 7, 2005
    • Build 812 Monday, Jan 10, 2005
    • Build 811 Wednesday, Dec 1, 2004
    • Build 810 Monday, Jun 7, 2004
    • Build 809 Monday, Feb 2, 2004
    • Build 808 Saturday, Dec 6, 2003
    • Build 807 Thursday, Nov 6, 2003
    • Build 806 Monday, March 31, 2003
    • Build 805 Thursday, Feb 6, 2003
    • Build 804 Friday, Nov 29, 2002

ActivePerl 5.8 Change Log

For the latest information on ActivePerl, please see:

    http://www.ActiveState.com/ActivePerl/

Build 820 Wednesday, Jan 24, 2007

Build 820 is based on Perl 5.8.8.

Bug Fixes and Changes since build 819

  • PPM has been upgraded to version 4.01.

    • The self-contained tkkits required by the Tcl module have been updated.

    • The PPM UI now supports install and uninstall of modules with post-install or uninstall scripts.

    • PPM now always uses package.xml for the ActiveState repository and doesn't fall back to downloading thousands of PPDs if the package.xml file is temporarily unavailable.

    • PPM now runs post-install scripts in dependency order.

    • The --force option to 'ppm install' now allows files already installed by other packages to be overwritten. Ownership of these files is transferred to the new package.

    • Added --no-sync option to the 'ppm search', 'ppm install' and 'ppm upgrade' commands.

    • Added --max-ppd option to 'ppm repo sync' command.

    • Added 'ppm config' command.

    • Added 'ppm tree' command.

    • The 'ppm repo sync' command now always checks the server to see if updates to the repository are available.

    • Improved compatiblity with PPD files from PPM3 repositories.

    • PPM4 now supports ZIP archives as the codebase of PPD files.

    • The 'ppm-shell' command on Windows now uses Term::ReadLine::Stub for terminal I/O to provide command history recall.

    • On Windows, PPM state data is now stored in LOCAL_APPDATA instead of APPDATA. The database can be quite large and is therefore not suitable for the roaming profile.

    • PPM now picks up modules from site; but still looks in the perl area first. This allows you to install Crypt-SSLeay in order to be able to access https://...-repositories.

    • Fixed a problem causing PPM to sometimes download package tarballs from the wrong repository.

    • The PPM GUI now shows which repository a package comes from. The Repository column is hidden by default.

    • The PPM GUI now warns about downgrades on modules selected for installation which have a lower version number than the currently installed version.

    • The PPM GUI used to drop all dependencies if some of them failed. It now keeps any remaining dependencies.

    • In the PPM GUI, package selection is not cleared if the install fails. This makes it possible to retry without having to select all the same packages again.

    • The PPM GUI now shows a download progress bar.

    • New PPM icon on Mac OS.

  • There have been various improvements in Unicode handling on Windows. Most of them rely on the fact that Windows stores a short 8.3 name for each filename that is longer, or contains characters not in the system codepage. By using the short name Perl is able to access these files throught the byte stream APIs that the Perl core is using.

    If the generation of short filenames has been disabled, then filenames containing characters outside the system codepage will still not be accessible. Since the short file names are stored by the file system, this mechanism will also only work for existing files. There is no way to determine a short file name for files that have not yet been created.

    • readdir() and glob() will return the short name if the long name cannot be represented in the system codepage.

    • The PATH environment variable is preprocessed and all entries using characters that are not in the system codepage will be replaced with their short name versions. This preprocessing step will also remove surrounding quote characters from all entries in the PATH variable.

      The PATH cleanup happens early enough that perl.exe will be able to find scripts via the -S commandline option in those "inaccessible" directories.

    • Both $^X and the @INC entries derived from $^X (lib and site/lib directories) will be converted to the short form, if necessary.

      Note that installing ActivePerl into a directory whose name cannot be represented in the system codepage is still discouraged.

    • Win32::GetCwd() will return a short name, if necessary, and Win32::SetCwd() can accept a Unicode name.

    • The new Win32::GetANSIPathName() accepts a pathname that may contain Unicode characters and returns the name in the system codepage.

      The file or directory must already exist; otherwise characters not in the system codepage will be translated using replacement characters (usually '?'), resulting in a potentially invalid filename.

    • Win32::GetLongPathName() may return Unicode characters now.

    • Win32::GetFullPathName() will return a short name, if necessary. Call Win32::GetLongPathName() on the return value (in scalar context) to get the full pathname in Unicode:

    • Win32::GetFolderPath() will return a short name, if necessary. Call Win32::GetLongPathName() on the return value to get the full pathname in Unicode.

    • Win32::ExpandEnvironmentStrings() may return Unicode characters because it will use the Unicode process environment directly.

      Any changes to %ENV however will be propagated to the process environment, and %ENV only stores byte strings. There is currently no API to set environment variables to a Unicode string.

    • Win32::MsgBox() now accepts Unicode strings for both the MESSAGE and TITLE paramters.

    • Win32::LoginName() may return Unicode characters.

  • The builtin Perl kill() function now support killing process trees by using negative signal numbers on Windows too. Currently kill() on Windows will still only terminate processes owned by the same user, even when the user is a member of the Administrators group.

  • Perl on Windows could hang indefinitely under certain conditions involving more than one of: alarm(), sleep(), waitpid(), system() and a GUI toolkit like Tk, wxPerl, Win32::GUI (or any other function that uses a messageloop). This indefinite loop should no longer occur.

  • The Windows installer now puts site\bin in the PATH.

  • The Windows installer now detects and prevents installation on top of ActivePerl 817 or earlier. This is necessary because the changed order of lib and site/lib in @INC would otherwise put old modules from the previous installation in front of the new modules bundled with this release.

    Also see the installation guide for help on saving and restoring your installed PPM modules with PPM-Profile.

  • The Windows installer for 64-bit ActivePerl will default the install location to C:\Perl64 instead of C:\Perl. Installing both the 32 and 64 bit versions of ActivePerl into the same directory is not supported.

    The Start menu shortcut and the Add Remove Programs entry for the 64 bit version are marked with a " (64-bit)" suffix to differentiate them from the 32 bit versions.

  • Improved MingW compatiblity on Windows.

  • The lwp-request aliases GET, HEAD, POST are no longer installed; use lwp-request directly instead. These aliases created problems on case-insensitive systems where they shadowed other commands.

  • Restored the old (pre 818) behaviour of ActivePerl::DocTools::WriteTOC(). It now only warns if it can't write to the perltoc.html file.

  • ActiveState::Browser now also looks for xdg-open, galeon and opera on Unix. It also knows how to detect KDE/Gnome properly.

  • ActiveState::Scineplex now has a JSON output mode.

  • Long hostnames are now supported on HP-UX.

  • Many bundled modules have been updated to their latest versions:

        Archive-Zip-1.18
    Data-Dump-1.08
    DBD-SQLite-1.13
    HTML-Parser-3.56
    HTML-Tree-3.23
    Mac-Apps-Launch-1.93
    Mac-Errors-1.13
    Mac-Glue-1.30
    Win32-0.28
    XML-Simple-2.16

  • A patch has been applied to DBI-1.52 to make it more robust against drivers not handling multiple result sets with different numbers of columns correctly. DBI wasn't upgraded to version 1.53 because that one breaks compatibility with DBD-Sybase.

Build 819 Wednesday, Aug 31, 2006

Build 819 is based on Perl 5.8.8.

Bug Fixes and Changes since build 818

  • HTML table of contents did not get updated as packages were installed/removed.

  • libwww-perl package was not properly recorded by PPM.

  • Term-ReadLine-Perl was missing.

  • Upgradable packages no longer show packages with equal version number in the PPM GUI.

Build 818 Wednesday, Aug 16, 2006

Build 818 is based on Perl 5.8.8.

Bug Fixes and Changes since build 817

  • This is the first non-beta release of 64 bit ActivePerl. It is available for Windows and Linux on x64 as well as Solaris on Sparc. The 64 bit Windows release does not include PerlScript, PerlEx, Perl for ISAPI or PerlEz.

    The 64 bit releases do not yet contain the Tcl and Tkx modules.

  • PPM has been rewritten; see Release Notes and the ppm manpage for details.

  • All bundled modules and scripts are now installed in the perl area and the site area is now completely empty in a new ActivePerl installation.

  • Rearranged order of @INC; modules installed in site area now take precedence over the bundled modules.

  • Simplified directory layout on Unix; no more architecture and version specific directories. This makes the layout the same as the Windows version of ActivePerl.

  • Term::ReadLine console fix for Windows.

  • Avoid trying to read C:\dev\urandom at startup on Windows.

  • The gridRemove method has been enabled for Tk.pm.

  • The Win32::OLE module in libwin32 package has been upgraded from version 0.1704 to version 0.1707.

    • add special support for tlbinf32.dll from Microsoft

    • add support for receiving VT_RECORD and arrays of VT_RECORD

    • improve error handling logic

    • fix memory leak in Win32::OLE::Enum::All() and Win32::OLE::Enum::Next()

    • in ClearVariantObject() check IDispatch/IUnknown variants for NULL before calling Release() on them

  • Double quotes are now displayed properly in the HTML documentation.

  • DynaLoader.o has now been moved into libperl.so on Unix. This makes it easier to embed perl and is the same arrangement as perl on Windows.

  • Added ActiveState::Browser module to ActiveState-Utils.

  • Most files of the Perl installation are now readonly on Windows.

  • Added a workaround for Module::Install brokenness that affected ActivePerl::Config (introduced in build 815). This prevented some modules to install under the CPAN shell.

  • Added error checks after execing PL_cshname or PL_sh_path.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.30
    CGI 3.20
    Compress-Zlib-1.42
    HTML-Parser-3.55
    HTML-Tree-3.20
    Mac-AppleEvents-Simple-1.18
    Mac-Carbon-0.77
    Mac-Errors-1.12
    Mac-Glue-1.27
    threads 1.31
    threads-shared 1.01
    Term-ReadLine-Perl-1.0302

  • New bundled modules:

        DBI-1.52
    DBD-SQLite-1.12
    Math-BigInt-FastCalc-0.10
    Tcl-0.89
    Tkx-1.04

Build 817.91 (818 Beta 2) Wednesday, Jul 19, 2006

Introduce PPM graphical interface and Tkx.

Build 817.90 (818 Beta 1) Wednesday, May 31, 2006

Introduce rearranged order of @INC and the new PPM command line client.

Build 817 Wednesday, Mar 22, 2006

Build 817 is based on Perl 5.8.8.

Bug Fixes and Changes

  • Upgraded the core threads and threads::shared modules with threads-1.12 and threads-shared-0.99 from CPAN. This fixes the handle leakage on Windows and allows setting the stack size for new threads. It also fixes both the '!=' comparison operator for thread objects and the crashes while joining threads that go re-introduced in build 816.

  • Fixed several bugs in the new implementation of alarm() for Windows. They did manifest themselves by signals not being delivered, or by GUI applications randomly hanging.

  • Restored binary compatibility for SvPV_nolen() and similar macros. This incompatibility made it impossible to use perlapp for Unix on Tk based applications.

  • Reintroduce PL_memory_wrap for binary compatibility.

  • The require builtin now ignores directories matching the given name when searching @INC.

Build 816 Thursday, Mar 2, 2006

Build 816 is based on Perl 5.8.8.

Bug Fixes and Changes

  • Perl 5.8.8 has been incorporated. See perl588delta.pod for a list of changes.

  • ActivePerl build 816 is now also available as a 64 bit Beta release for Windows and Linux on x86_64 as well as Solaris on Sparc. The 64 bit Windows Beta does not include PerlScript, PerlEx, Perl for ISAPI or PerlEz.

  • The ActivePerl Community License has been clarified. It now explicitly allows you to redistribute certain parts of ActivePerl as part of applications generated by wrapping tools such as by PAR, PerlApp and Perl2Exe. Please refer to the license text for actual terms and conditions.

  • ActivePerl for Mac OS X is now a Universal binary that supports all Macintosh hardware natively.

  • ActivePerl for Solaris is now built with the vendor compiler. Previous releases were built with the GNU compiler (gcc).

  • ActivePerl::Config on Solaris and HP-UX now provide compatibility so that extensions can be built using gcc. This happens automatically if the vendor compiler is not available on the target system.

  • ActivePerl now ships with a preinitialized CPAN::Config module. This avoids the need to go through the configuration dialog the first the CPAN shell is invoked. The configuration dialog can still be invoked by the o conf init command to the CPAN shell.

  • Syntax colored documentation and ActiveState::Scineplex is now supported for all the Unix platforms.

  • Passive transfer mode is now the default for Net::FTP. This mode is more likely to work with modern firewall setups.

  • Problem where 'perl -s' wasn't able to parse -foo=bar switches has been corrected.

  • The stat() builtin would not return the expected result when passed a directory name with trailing slashes on Windows. This problem has been fixed.

    This problem caused the rmtree() function of the File::Path module introduced in build 815 to fail for such directory names on Windows.

  • The IO::Socket::INET is now more efficient and it does not rely on getprotobyname("tcp") to be functional any more.

  • A problem where long groups entries could cause memory exhaustion has been fixed.

  • A problem with the alarm() function on Windows 2003 has been fixed.

  • The Tk module would sometimes fail to update the -cursor attribute of widgets for 64-bit builds of perl. This problem has now been fixed.

  • Many bundled modules have been updated to their latest versions:

        Digest-SHA-2.11
    HTML-Tagset-3.10
    HTML-Parser-3.50
    HTML-Tree-3.1901
    IO-String-1.08
    libwww-perl-5.805
    Mac-Errors-1.11
    Win32-OLE-0.1704

Build 815 Wednesday, Nov 2, 2005

Build 815 is based on Perl 5.8.7.

Bug Fixes and Changes

  • The PerlEx plugin for IIS has been added to ActivePerl for Windows. It caches precompiled CGI scripts in memory to increase their performance.

  • The table of contents for the HTML documentation has been reverted back to the format used before build 813 (it no longer requires JavaScript to be enabled).

  • ExtUtils::MakeMaker now generates and installs HTML documentation automatically. Regardless how modules are being installed (via PPM, through the CPAN shell, or by manual compilation and installation), the HTML documentation is always kept up-to-date.

  • Code snippets in the HTML documentation are syntax colored. This feature is currently only available on Windows and Mac OS X.

  • ActiveState::Scineplex has been added on Windows and Mac OS X. This module analyzes source code for various programming languages and is being used to colorize the code snippets in the HTML documentation.

  • The ActivePerl::Config module has been added. It allows perl's configuration options to be overridden. The module can also automatically reconfigure ActivePerl for alternative compilation environments when the default compiler cannot be found.

    On Windows, MakeMaker will use the gcc.exe compiler from MinGW and the dmake.exe utility if the Microsoft Visual C++ compiler cl.exe and the nmake.exe utility are not available on the PATH. This will also work automatically from within the CPAN shell.

  • The perl-static executable on Unix will now pick up a matching Config.pm (there is no statically linked Perl on Windows).

  • File::Path's rmtree() function has been replaced to address security vulnerability CAN-2005-0448.

  • Fixed incompatibility problem with Tk and Encode version 2.10 which was introduced in build 813 (perl-5.8.7).

  • Win32::GetOSName() can now identify Windows Vista.

  • Various ActiveState::* utility modules have been added.

  • libwin32 has been updated to version 0.26:

    • Win32API::File

      New GetFileAttributes() function and corresponding constants.

      Added GetFileSize(), getFileSize(), setFilePointer(), and GetOverlappedResult() functions. The file position operations can use Math::BigInt objects.

      Experimental new object oriented interface added. This will be moved into a separate module in a later release.

    • Win32API::Registry

      Added DELETE/READ_CONTROL/WRITE_DAC/WRITE_OWNER/SYNCHRONIZE as KEY_*.

    • Win32::Clipboard

      GetBitmap() should now work correctly with 1 bit, 4 bit, 8 bit, 16 bit, 24 bit, and 32 bit colors.

    • Win32::Console

      Renamed GRAY to LIGHTGRAY and added definitions for the "real" GRAY colors.

      Added get_Win32_IPC_HANDLE() method so that Win32::IPC can wait on a console handle.

      Added SetIcon() method to change the icon of the window.

      Don't export the scalar variables to %main:: but into the callers namespace.

    • Win32::Process

      Added get_Win32_IPC_HANDLE() method for Win32::IPC compatibility.

      Added STILL_ACTIVE constant for GetExitCode().

      Win32::Process::Open() now records the process ID correctly for GetProcessID(). It also creates handle now that can be used with the Wait() method.

    • Win32::Shortcut

      The Save() function now calls Win32::GetLongPathName() on the filename to make sure to use a fully qualified pathname.

      The Save() will store the new filename as the 'File' property unless the Shortcut object already has a 'File' property.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.26
    Archive-Zip-1.16
    Compress-Zlib-1.41
    HTML-Parser-3.46
    IO-String-1.07
    Mac-Apps-Launch-1.92
    Mac-OSA-Simple-1.09
    Time-HiRes-1.76
    Unicode-String-1.09

Build 814 Beta Tuesday, Jun 28, 2005

Build 814 Beta is based on Perl 5.8.7. This release is provided as a Windows MSI installer only.

Bug Fixes and Changes

  • Bundled PerlEx, an ISAPI plugin for the IIS web server.

  • Built in ActivePerl:: module providing version information.

  • The gedi program now actually runs. This is a demo program installed by the Tk package.

  • Text-Autoformat module updated to version 1.13.

Build 813 Tuesday, Jun 7, 2005

Build 813 is based on Perl 5.8.7.

Bug Fixes and Changes

  • ActivePerl is now supported on the Mac OS X, Solaris (x86), and AIX platforms.

  • New improved HTML documentation which requires JavaScript enabled browser.

  • Installation of the HTML documentation is now optional.

  • Perl 5.8.7 has been incorporated. See perl587delta.pod for a list of changes.

  • ActivePerl will now evaluate 'sitecustomize.pl' at startup if present. The ActivePerl distribution does not ship with this file, but it is a hook that the system administrator can use to set up set up additional site specific @INC entries.

  • Fixed Net::Ping's ICMP implementation to not give up waiting for the echo reply until it either receives an unreachable reply or times out. Previous versions would for instance give up if they received a source quench reply.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.23
    Compress-Zlib-1.34
    Convert-ASN1-0.19 (only for HP-UX)
    HTML-Parser-3.45
    HTML-Tagset-3.04
    libwww-perl-5.803
    XML-Simple-2.14

  • New modules

        Mac-AppleEvents-Simple-1.17
    Mac-Apps-Launch-1.91
    Mac-Carbon-0.74
    Mac-Errors-1.10
    Mac-Glue-1.25
    Mac-OSA-Simple-1.08
    MLDBM-2.01 (only for Mac OS X)
    Text-Autoformat-1.12
    Text-Reform-1.11
    Time-Epoch-0.02 (only for Mac OS X)
    Unicode-String-2.07

    The "Mac-" modules are only present for Mac OS X as well.

  • The ActiveState-Rx module has been dropped from the distribution.

Build 812 Monday, Jan 10, 2005

Build 812 is based on Perl 5.8.6.

Bug Fixes and Changes

  • On Unix, provide a destructor for libperl. This allows libperl to be repeatedly loaded and unloaded by e.g. mod_perl without running out of thread local storage slots. On Windows this was already handled correctly.

  • The reloc_perl -a option has been fixed. It is now possible to relocate from a shorter to a longer path.

Build 811 Wednesday, Dec 1, 2004

Build 811 is based on Perl 5.8.6.

Bug Fixes and Changes

  • Perl 5.8.6 has been incorporated. See perl585delta.pod and the perl586delta manpage for a list of changes.

  • Fixed stack corruption in the Tk-804.027 module. This would sometimes make Tk programs crash.

  • Fixed handling of Unicode in XML-DOM-1.43. Some Unicode strings would end up UTF-8 encoded when they should not be. The XML::DOM module is only distributed as part of ActivePerl on HP-UX.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.22
    Data-Dump-1.06
    Digst-MD4-1.4
    Encode-2.09
    HTML-Parser-3.38
    IO-Zlib-1.04
    libwin32-0.24 (only for Windows)
    libwww-perl-5.801
    libxml-perl-0.08 (only for HP-UX)
    perl-ldap-0.3202
    URI-1.35

    In addition, IO::String version 1.06 is now included with ActivePerl.

Build 810 Monday, Jun 7, 2004

Build 810 is based on Perl 5.8.4.

Bug Fixes and Changes

  • Perl 5.8.4 has been incorporated. See the perl584delta manpage for a list of changes.

  • The default install location on Unix is now /opt/ActivePerl-5.8. Earlier versions installed into /usr/local/ActivePerl-5.8 by default.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.08
    Compress-Zlib-1.33
    Data-Dump-1.03
    Digest-SHA1-2.10
    File-CounterFile-1.04
    Font-AFM-1.19
    HTML-Parser-3.36
    libwww-perl-5.79
    MD5-2.03
    perl-ldap-0.31 (only for HP-UX))
    Tk-804.027
    URI-1.30
    XML-Simple-2.12
    XML-XSLT-0.48 (only for HP-UX))

Build 809 Monday, Feb 2, 2004

Build 809 is based on Perl 5.8.3.

Bug Fixes and Changes

  • Perl 5.8.3 has been incorporated. See the perl583delta manpage for a list of changes.

  • The Win32 module now includes the Win32::IsAdminUser() function that checks if the current interpreter runs with Administrator privileges.

  • The access violations of detached threads on thread exit have been fixed.

  • Time::HiRes now provides high resolution on Windows too.

Build 808 Saturday, Dec 6, 2003

Build 808 is based on Perl 5.8.2.

Changes

  • Perl 5.8.2 has been incorporated. See the perl582delta manpage for a list of changes.

    ActivePerl build 808 is still being compiled with the -DNO_HASH_SEED option to maintain binary compatibility with earlier releases. Perl 5.8.2 implements a new rehashing scheme that will kick in dynamically based on the actual data being stored in a hash. This new scheme is backwards compatible and is enabled in ActivePerl build 808.

  • The following modules are bundled with ActivePerl for HP-UX and have been updated to their latest versions:

        Convert-ASN1-0.18
    XML-DOM-1.43
    XML-XPath-1.13
    XML-XSLT-0.45
    perl-ldap-0.30

Build 807 Thursday, Nov 6, 2003

Build 807 is based on Perl 5.8.1. This is the first release of ActivePerl based on this new maintenance release of Perl. This release is meant for use in production systems. However, owing to the sheer volume of changes between Perl 5.8.0 and 5.8.1 that have been incorporated, please be sure to test it thoroughly in a non-critical environment before you upgrade your production systems.

Please check the perl581delta manpage for a list of the major changes in Perl. Only additional changes specific to ActivePerl are mentioned here.

Bug Fixes and Changes

  • Perl 5.8.1 has been incorporated. See the perl581delta manpage for a list of changes.

    Important note: The new Hash Randomization feature has been disabled in ActivePerl because it is not compatible with Perl 5.8.0. If we enabled this feature then some modules compiled with 5.8.0 would not work correctly with 5.8.1 and most modules compiled with 5.8.1 would not work at all with Perl 5.8.0. This would require maintaining separate PPM module repositories for 5.8.0 and 5.8.1.

    To enable the Hash Randomization feature you must recompile ActivePerl from source and remove the -DNO_HASH_SEED definition from the C compiler options. In that case you must compile all CPAN modules yourself too because the PPM repository binaries will not be compatible.

  • Windows 2003 Server is now officially supported. The installer adds entries to the IIS6 "Web Services Extensions" list for both "Perl CGI" and "Perl ISAPI". Both are set to "Prohibited" by default and must be explicitly changed to "Allow" in the IIS Manager.

    Win32::GetOSName() detects the release version of Windows 2003 correctly.

  • ActiveState::Rx module has been included. This module is necessary to use the Rx Toolkit in ActiveState Visual Perl. You must upgrade Visual Perl to version 1.8.1 to use the Rx Toolkit with Perl 5.8.

  • Many bundled modules have been updated to their latest versions:

        Archive-Tar-1.07
    Compress-Zlib-1.22
    Data-Dump-1.01
    Digest-MD2-2.03
    Digest-MD5-2.30
    Digest-SHA1-2.06
    File-CounterFile-1.01
    HTML-Parser-3.34
    HTML-Tree-3.18
    URI-1.27
    XML-Parser-2.34
    XML-Simple-2.09
    libwin32-0.21
    libwww-perl-5.75

    In addition, IO::Zlib version 1.01 is now included with ActivePerl.

PPM

  • The upgrade command has been fixed.

  • It is now possible to install from a file URL while not being connected to the Internet.

  • PPM now works on Windows even when the Term::InKey module is installed.

Perl for ISAPI

  • Perl for ISAPI no longer uses line buffering for STDOUT. This is especially important for running under IIS6 which bypasses TCP/IP nagling and directly sends every packet individually.

  • Perl for ISAPI used to close all open file handles before shutting down the Perl interpreter. The intention was to prevent file handle leaks from buggy Perl scripts while running inside the IIS process. Unfortunately Perl may still execute END blocks or call DESTROY methods during final destruction and some file handles may get closed twice in this scenario.

    This creates a race condition: the file handle may already have been re-opened by a different thread before the second close happens. Perl then closes a file handle it doesn't own anymore. This may cause a different page request to fail.

    To avoid this race condition Perl for ISAPI will no longer try to automatically close open file handles. Therefore it is possible that broken Perl applications will now start leaking file handles if they don't close them correctly themselves.

Build 806 Monday, March 31, 2003

Bug Fixes and Changes

  • Several bug fixes and other improvements have been merged from the Perl development track. In particular, many of these fixes address problems in the PerlIO implementation. See the ActivePerl source code diff for the complete list of included changes.

  • Other minor bug fixes and documentation updates.

PPM

PPM has been upgraded to version 3.1. It fixes most of the known problems, including:

  • PPM 3.1 now provides all the functionality of PPM 2.0 and 3.0. PPM 2.0 is therefore no longer included in ActivePerl 5.8.

  • PPM now works correctly through a proxy server requiring basic authentication. Previous versions of PPM 3.0 only supported proxy servers that did not require authentication.

  • PPM is now more robust in handling user-defined repository URLs. For instance, URLs with a trailing slash no longer result in fatal errors.

  • Support for ASPN Perl profiles has been much improved. However, at the time of this writing, the ActivePerl 5.8 repositories do not yet support profiles. This is expected to become available shortly.

  • In previous versions of PPM 3, incorrect search results from the repository (such as package names that do not have corresponding PPD files) could crash the PPM3 client. PPM now generates meaningful error messages under these circumstances.

Build 805 Thursday, Feb 6, 2003

Bug Fixes and Changes

  • Several bug fixes and other improvements have been merged from the Perl development track. In particular, many of these fixes address weaknesses in Unicode support. See the ActivePerl source code diff for the complete list of included changes.

  • Bugs in the Perl 5.8 integration of Perl for ISAPI and PerlScript that resulted in failure to flush output correctly at the termination of the script have been fixed.

  • On Windows, system() and backticks could return invalid status when running under environments where the process has to handle Windows messages. PerlScript and Perl for ISAPI fall under this category. The problem has been corrected.

  • On Windows, PerlScript and Perl for ISAPI were affected by a reentrancy problem, which meant that recursive invocation of these two engines could fail. This problem has been corrected.

  • Tk and libwww-perl has been updated to their latest versions.

  • Win32::Shortcut no longer calls CoUninitialize() within an END block. This avoids random coredumps from this module when its DESTROY methods happen to get called after the END block executes.

  • PPM v2 and v3 can now optionally generate HTML documentation when installing packages if POD documentation is found in the package. This is controlled by the rebuildhtml option in PPM v2 and the rebuild-html option in PPM v3.

  • Other minor bug fixes and documentation updates.

Build 804 Friday, Nov 29, 2002

What's new in the 800 Series

  • This build corresponds to the Perl 5.8.0 source code release.

  • The 800 series builds of ActivePerl are not binary compatible with builds in the 500 or 600 series. Any extensions built using binaries from the ActivePerl 500 or 600 series will need to be recompiled. Note especially that this applies to PPM packages that may have been built for 500 or 600 series builds.

  • Significant changes that have occurred in the 5.8.0 release are documented in the perl58delta manpage.

  • Support has been enabled for large file access on all platforms, meaning that file manipulation facilities within perl can cope with files larger than 2GB or 4GB.

  • Many new modules are included as a standard part of perl 5.8.0. See "Modules and Pragmata" in the perl58delta manpage for a detailed list. In addition, the Data::Dump module is now included with ActivePerl. Many other modules have been updated to their latest versions.

  • PPM v3 is now included as the default ppm executable. PPM v2 continues to be available, and can be executed as ppm2.


ActivePerl 820 -- Release Notes

  • ActivePerl 820 - Release Notes
  • Incompatibilities
    • PPM version 4
  • Known Issues
    • PPM
    • AIX
    • Linux and Solaris
    • Mac OS X
    • Windows
    • Further Information
  • Reporting Problems

ActivePerl 820 -- Release Notes

Welcome, and thank you for downloading ActivePerl. This release corresponds to Perl version 5.8.8.

The following platforms are supported by this release:

  • AIX 5.1 or later (rs6000)

  • Linux: glibc 2.2 or later (x86)

    Linux: glibc 2.3 or later (x64)

  • Mac OS X 10.3 "Panther" or later (x86 or powerpc)

  • Solaris 2.6 or later (sparc, 32 and 64 bit)

    Solaris 10 or later (x86)

  • Windows 9x, Me, NT, 2000 (x86)

    Windows XP and 2003 (x86 and x64)

For a chronological list of changes included in this and past releases, see the ActivePerl 5.8 Change Log.

Incompatibilities

Perl 5.8 is not binary compatible with Perl 5.6. In particular, do not attempt to use extensions or PPM packages built for ActivePerl 600 series builds with ActivePerl 800 series builds and vice versa. Please check Incompatible Changes in the perl58delta manpage for known source level incompatibilities between the Perl 5.8 releases and the earlier releases in the Perl 5.6 series.

You may also want to check Incompatible Changes in the perl581delta manpage, Incompatible Changes in the perl582delta manpage, and Incompatible Changes in the perl584delta manpage, for additional minor incompatible changes made in Perl 5.8.1, Perl 5.8.2 and Perl 5.8.4 respectively.

The order of the directories in @INC has changed since build 817 of ActivePerl. The $PREFIX/site/lib directory is now searched for modules before $PREFIX/lib. This means that core modules might be shadowed by what is installed locally and these updates might bring incompatibilities that break applications only tested against the original core module.

All modules that ActivePerl bundles in addition to the core modules are now installed in $PREFIX/lib. In ActivePerl build 817 and earlier, these were installed in $PREFIX/site/lib.

The $Config{siteprefix} is now $PREFIX/site. In ActivePerl build 817 and earlier, it was just $PREFIX and $Config{sitelib} compensated by introducing the site level. As a consequence programs included with packages installed into the site area now get installed in $PREFIX/site/bin. In ActivePerl build 817 and earlier, these were installed in $PREFIX/bin. Another consequence of the $Config{siteprefix} update is that modules configured and built with perl Makefile.PL PREFIX=... are now installed directly in the lib directory of the given PREFIX.

PPM version 4

PPM version 4 differs from version 3 (distributed with ActivePerl build 817 and earlier) in the following ways:

  • Running ppm without arguments now bring up a graphical user interface; there is no more console shell.

  • The output format of most commands have changed. Scripts that parse the output of ppm need to change.

  • ppm describe only takes a number as argument. The other forms are not supported.

  • ppm install without argument does not install a default package and does not support the range argument. The --follow and --no-follow options are not supported.

  • ppm profile, ppm properties, ppm set, and ppm target commands are not supported.

  • ppm repo up and ppm repo down commands are not supported.

  • ppm search does not support the field=glob syntax.

  • SOAP-based repositories are no longer supported.

Known Issues

PPM

There are some known outstanding issues with the PPM 4 client:

  • The PPM state database (containing configuration information for repositories, view options in the GUI, and repository state) is not imported from previous installations.

    If you have added custom PPM 4 repositories with ActivePerl 5.8.8.819, you should reconfigure them manually with ppm repo add ... or in the GUI. The repository state will be automatically re-synchronized when PPM is run.

  • Packages using post install scripts can't be installed from the GUI. The workaround is to use the command line version of ppm to install these packages.

  • The "Upgradable View" shows packages that would downgrade the installation. PPM will warn you if select a package for installation which would downgrade the currently installed version.

  • List icons will sometimes not repaint properly after scrolling under X11. This does not affect the Windows and Mac OS X builds.

  • Running sudo ppm ... the first time ppm is invoked from a regular user account on Unix will create a root owned state database. This effectively makes the database read-only when running ppm without sudo, and might manifest itself as Application Error dialogs when running the GUI. Workaround is to run sudo chown -R $USER ~/.ActivePerl once to fix up ownership of the state database.

  • Sync of repository state might be slow. (#45830)

  • No PPM GUI for the 64 bit versions of ActivePerl.

If you find other issues with the new PPM client, please report them at http://bugs.ActiveState.com/ActivePerl/.

AIX

The following issues are know to exists when installing ActivePerl on AIX:

  • The reloc_perl script does not correctly update the perl-dynamic executable. The workaround is to install directly from the tarball into the new location.

Linux and Solaris

The following issues are know to exists when installing ActivePerl on Unix:

  • Some versions of tar on Solaris have bugs that prevent proper extraction of files in a package that has long path names. Most other versions of tar on Solaris use a different method than GNU tar to encode pathnames longer than 100 characters. GNU tar is therefore required to extract the package into the file system correctly. A precompiled version of GNU tar for the sparc platform is available from:

        http://www.sunfreeware.com/

    You can also get the source package for GNU tar from:

        http://www.gnu.org/

  • The suidperl executable is not included in this package due to potential security issues. If you wish to use suidperl in your installation, we recommend building Perl from source. The source code for ActivePerl is available at:

        http://www.ActiveState.com

Mac OS X

  • Perl library paths, and thus PPM Areas, defined in the shell by the PERL5LIB environment variable are not available to PPM when it is launched by clicking the PPM icon in OS X. To to make this variable available in the OS X GUI, add an entry similar to the following to ~/.MacOSX/environment.plist:

     <key>PERL5LIB</key>
 <string>/path/to/perl/lib</string>

  • Running sudo ppm or sudo ppm gui does not start up the GUI with root privileges. Use ppm as a command line tool with sudo.

  • On version 10.3 or earlier, running ppm without arguments from a remote console (e.g. via ssh) causes a core dump as it attempts to launch the PPM GUI instead of providing an informative "ppm gui failed" error.

Windows

The following issues are know to exists when installing ActivePerl on Windows:

  • The installer cannot create IIS script mappings on Windows Vista.

  • The fork() emulation has known limitations. See the perlfork manpage for a detailed summary. In particular, fork() emulation will not work correctly with extensions that are either not thread-safe, or maintain internal state that cannot be cloned in the pseudo-child process. This caveat currently applies to extensions such as Tk and Storable.

  • It seems that some people are having problems with the ActivePerl MSI installer. The first thing to note is that you CANNOT install ActivePerl 5.8 over an older version of ActivePerl based on 5.6 or 5.005, such as build 633 or any other 600 or 500 series build. We have determined that some of these problems are due to other installations of Perl that may be pointed at by something in the environment.

    The sure-fire solution is to make absolutely certain that no other installations of Perl are on the target machine. Realizing that this is not always possible, you can follow these steps to ensure the other installations will not interfere.

    1. Stop the "Windows Installer" service. This can be accomplished from the command prompt using the following command:

          c:\> net stop "Windows Installer"

    2. Temporarily remove or rename PERLLIB and PERL5LIB environment variables in the system environment.

    3. Temporarily remove or rename the following registry values:

          [\\HKEY_LOCAL_MACHINE\Software\Perl] lib = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] lib-<PerlVersion> = <directory> (REG_SV)
    [\\HKEY_LOCAL_MACHINE\Software\Perl] sitelib-<PerlVersion> = <directory>(REG_SV)

    4. Proceed with the installation.

    Once the installation has completed successfully, the above actions may be undone although restoring the environment variables or the registry values may interfere with the proper operation of your new ActivePerl installation. In order to perform all of the above steps, you will need to have Administrative privileges on the target machine. If you do not have the required privileges you should contact you Administrator.

    The following Microsoft knowledge base articles may be helpful in solving MSI problems:

    Q236597 - OFF2000: Error Message: The Installation Package Could Not Be Opened ...

    http://support.microsoft.com/support/kb/articles/Q236/5/97.ASP

    • Q224094 - OFF2000: Error Message: This Application Requires the Windows Installer to Run

    http://support.microsoft.com/support/kb/articles/Q224/0/94.ASP

    Q247532 - Works 2000 Err Msg: Installer Terminated Prematurely

    http://support.microsoft.com/support/kb/articles/Q247/5/32.ASP

    "Error 1303. The installer has insufficient privileges..." Running Office Setup

    http://support.microsoft.com/support/kb/articles/Q228/6/58.ASP

    Error Message: Error 1316 Running Setup for Admin Installation

    http://support.microsoft.com/support/kb/articles/Q228/5/92.ASP

    Error 1327 Invalid Drive During Office Installation

    http://support.microsoft.com/support/kb/articles/Q217/6/66.ASP

  • On Windows 9x, the system must be rebooted for the PATH environment variable to take effect.

  • On Windows 9x, the PATH environment variable settings are not removed after an uninstall.

Further Information

The Perl distribution comes with extensive documentation. On Unix platforms, all the standard documentation is installed as man pages under the Perl install location. The location of the man pages may need to be added to the MANPATH environment variable in order to access them. For example, in the C shell:

    % setenv MANPATH /opt/ActivePerl-5.8/man:$MANPATH

The documentation is installed in HTML format on all platforms. If ActivePerl was installed in /opt/ActivePerl-5.8 then the HTML documentation would be located in /opt/ActivePerl-5.8/html.

On Windows, the standard documentation along with Windows-specific Perl documentation is installed in HTML format, and is accessible from the "Start" menu.

Updated versions of the HTML documentation will always be available at the ActiveState website:

    http://www.ActiveState.com/ActivePerl/

Reporting Problems

Please report any problems you encounter with this release at the following location:

    http://bugs.ActiveState.com/ActivePerl/

If you do not have web access, reports can be also sent via email to ActivePerl-Bugs@ActiveState.com. Please be sure to include detailed information about the platform in your message.

As far as possible, please ensure that there is enough information in the report to reproduce the bug elsewhere. It also helps to submit a minimal test case that exhibits the bug.


perlcn - ¼òÌåÖÐÎÄ Perl Ö¸ÄÏ

    • ¶îÍâµÄÖÐÎÄ±àÂë
    • ½øÒ»²½µÄÐÅÏ¢
    • Ìá¹© Perl ×ÊÔ´µÄÍøÖ·
    • Ñ§Ï° Perl µÄÍøÖ·
    • Perl Ê¹ÓÃÕß¼¯»á
    • Unicode Ïà¹ØÍøÖ·
  • SEE ALSO
  • AUTHORS

NAME

perlcn - ¼òÌåÖÐÎÄ Perl Ö¸ÄÏ

DESCRIPTION

»¶ÓÀ´µ½ Perl µÄÌìµØ!

´Ó 5.8.0 °æ¿ªÊ¼, Perl ¾ß±¸ÁËÍêÉÆµÄ Unicode (Í³Ò»Âë) Ö§Ô®, Ò²Á¬´øÖ§Ô®ÁËÐí¶àÀ¶¡ÓïÏµÒÔÍâµÄ±àÂë·½Ê½; CJK (ÖÐÈÕº«) ±ãÊÇÆäÖÐµÄÒ»²¿·Ý. Unicode ÊÇ¹ú¼ÊÐÔµÄ±ê×¼, ÊÔÍ¼º¸ÇÊÀ½çÉÏËùÓÐµÄ×Ö·û: Î÷·½ÊÀ½ç, ¶«·½ÊÀ½ç, ÒÔ¼°Á½Õß¼äµÄÒ»ÇÐ (Ï£À°ÎÄ, ÐðÀûÑÇÎÄ, ÑÇÀ²®ÎÄ, Ï£²®À´ÎÄ, Ó¡¶ÈÎÄ, Ó¡µØ°²ÎÄ, µÈµÈ). ËüÒ²ÈÝÄÉÁË¶àÖÖ×÷ÒµÏµÍ³ÓëÆ½Ì¨ (Èç PC ¼°Âó½ðËþ).

Perl ±¾ÉíÒÔ Unicode ½øÐÐ²Ù×÷. Õâ±íÊ¾ Perl ÄÚ²¿µÄ×Ö·û´®Êý¾Ý¿ÉÓÃ Unicode ±íÊ¾; Perl µÄº¯Ê½ÓëËã·û (ÀýÈçÕý¹æ±íÊ¾Ê½±È¶Ô) Ò²ÄÜ¶Ô Unicode ½øÐÐ²Ù×÷. ÔÚÊäÈë¼°Êä³öÊ±, ÎªÁË´¦ÀíÒÔ Unicode Ö®Ç°µÄ±àÂë·½Ê½´æ·ÅµÄÊý¾Ý, Perl Ìá¹©ÁË Encode Õâ¸öÄ£¿é, ¿ÉÒÔÈÃÄãÇáÒ×µØ¶ÁÈ¡¼°Ð´Èë¾ÉÓÐµÄ±àÂëÊý¾Ý.

Encode ÑÓÉìÄ£¿éÖ§Ô®ÏÂÁÐ¼òÌåÖÐÎÄµÄ±àÂë·½Ê½ ('gb2312' ±íÊ¾ 'euc-cn'):

    euc-cn      Unix ÑÓÉì×Ö·û¼¯, Ò²¾ÍÊÇË×³ÆµÄ¹ú±êÂë
    gb2312-raw  Î´¾´¦ÀíµÄ (µÍ±ÈÌØ) GB2312 ×Ö·û±í
    gb12345     Î´¾´¦ÀíµÄÖÐ¹úÓÃ·±ÌåÖÐÎÄ±àÂë
    iso-ir-165  GB2312 + GB6345 + GB8565 + ÐÂÔö×Ö·û
    cp936       ×ÖÂëÒ³ 936, Ò²¿ÉÒÔÓÃ 'GBK' (À©³ä¹ú±êÂë) Ö¸Ã÷
    hz          7 ±ÈÌØÒÝ³öÊ½ GB2312 ±àÂë

¾ÙÀýÀ´Ëµ, ½« EUC-CN ±àÂëµÄµµ°¸×ª³É Unicode, ìóÐè¼üÈëÏÂÁÐÖ¸Áî:

    perl -Mencoding=euc-cn,STDOUT,utf8 -pe1 < file.euc-cn > file.utf8

Perl Ò²ÄÚ¸½ÁË "piconv", Ò»Ö§ÍêÈ«ÒÔ Perl Ð´³ÉµÄ×Ö·û×ª»»¹¤¾ß³ÌÐò, ÓÃ·¨ÈçÏÂ:

    piconv -f euc-cn -t utf8 < file.euc-cn > file.utf8
    piconv -f utf8 -t euc-cn < file.utf8 > file.euc-cn

ÁíÍâ, ÀûÓÃ encoding Ä£¿é, Äã¿ÉÒÔÇáÒ×Ð´³öÒÔ×Ö·ûÎªµ¥Î»µÄ³ÌÐòÂë, ÈçÏÂËùÊ¾:

    #!/usr/bin/env perl
    # Æô¶¯ euc-cn ×Ö´®½âÎö; ±ê×¼Êä³öÈë¼°±ê×¼´íÎó¶¼ÉèÎª euc-cn ±àÂë
    use encoding 'euc-cn', STDIN => 'euc-cn', STDOUT => 'euc-cn';
    print length("ÂæÍÕ");            #  2 (Ë«ÒýºÅ±íÊ¾×Ö·û)
    print length('ÂæÍÕ');            #  4 (µ¥ÒýºÅ±íÊ¾×Ö½Ú)
    print index("×»×»½Ì»å", "»×»½"); # -1 (²»°üº¬´Ë×Ó×Ö·û´®)
    print index('×»×»½Ì»å', '»×»½'); #  1 (´ÓµÚ¶þ¸ö×Ö½Ú¿ªÊ¼)

ÔÚ×îºóÒ»ÁÐÀý×ÓÀï, "×»" µÄµÚ¶þ¸ö×Ö½ÚÓë "×»" µÄµÚÒ»¸ö×Ö½Ú½áºÏ³É EUC-CN ÂëµÄ "»×"; "×»" µÄµÚ¶þ¸ö×Ö½ÚÔòÓë "½Ì" µÄµÚÒ»¸ö×Ö½Ú½áºÏ³É "»½". Õâ½â¾öÁËÒÔÇ° EUC-CN Âë±È¶Ô´¦ÀíÉÏ³£¼ûµÄÎÊÌâ.

¶îÍâµÄÖÐÎÄ±àÂë

Èç¹ûÐèÒª¸ü¶àµÄÖÐÎÄ±àÂë, ¿ÉÒÔ´Ó CPAN (http://www.cpan.org/) ÏÂÔØ Encode::HanExtra Ä£¿é. ËüÄ¿Ç°Ìá¹©ÏÂÁÐ±àÂë·½Ê½:

    gb18030     À©³ä¹ýµÄ¹ú±êÂë, °üº¬·±ÌåÖÐÎÄ

ÁíÍâ, Encode::HanConvert Ä£¿éÔòÌá¹©ÁË¼ò·±×ª»»ÓÃµÄÁ½ÖÖ±àÂë:

    big5-simp   Big5 ·±ÌåÖÐÎÄÓë Unicode ¼òÌåÖÐÎÄ»¥×ª
    gbk-trad    GBK ¼òÌåÖÐÎÄÓë Unicode ·±ÌåÖÐÎÄ»¥×ª

ÈôÏëÔÚ GBK Óë Big5 Ö®¼ä»¥×ª, Çë²Î¿¼¸ÃÄ£¿éÄÚ¸½µÄ b2g.pl Óë g2b.pl Á½Ö§³ÌÐò, »òÔÚ³ÌÐòÄÚÊ¹ÓÃÏÂÁÐÐ´·¨:

    use Encode::HanConvert;
    $euc_cn = big5_to_gb($big5); # ´Ó Big5 ×ªÎª GBK
    $big5 = gb_to_big5($euc_cn); # ´Ó GBK ×ªÎª Big5

½øÒ»²½µÄÐÅÏ¢

Çë²Î¿¼ Perl ÄÚ¸½µÄ´óÁ¿ËµÃ÷ÎÄ¼þ (²»ÐÒÈ«ÊÇÓÃÓ¢ÎÄÐ´µÄ), À´Ñ§Ï°¸ü¶à¹ØÓÚ Perl µÄÖªÊ¶, ÒÔ¼° Unicode µÄÊ¹ÓÃ·½Ê½. ²»¹ý, Íâ²¿µÄ×ÊÔ´Ïàµ±·á¸»:

Ìá¹© Perl ×ÊÔ´µÄÍøÖ·

http://www.perl.com/

Perl µÄÊ×Ò³ (ÓÉÅ·À³Àñ¹«Ë¾Î¬»¤)

http://www.cpan.org/

Perl ×ÛºÏµä²ØÍø (Comprehensive Perl Archive Network)

http://lists.perl.org/

Perl ÓÊµÝÂÛÌ³Ò»ÀÀ

Ñ§Ï° Perl µÄÍøÖ·

http://www.oreilly.com.cn/html/perl.html

¼òÌåÖÐÎÄ°æµÄÅ·À³Àñ Perl Êé½å

Perl Ê¹ÓÃÕß¼¯»á

http://www.pm.org/groups/asia.shtml#China

ÖÐ¹ú Perl ÍÆ¹ã×éÒ»ÀÀ

Unicode Ïà¹ØÍøÖ·

http://www.unicode.org/

Unicode Ñ§ÊõÑ§»á (Unicode ±ê×¼µÄÖÆ¶¨Õß)

http://www.cl.cam.ac.uk/%7Emgk25/unicode.html

Unix/Linux ÉÏµÄ UTF-8 ¼° Unicode ´ð¿ÍÎÊ

SEE ALSO

the Encode manpage, the Encode::CN manpage, the encoding manpage, the perluniintro manpage, the perlunicode manpage

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi>

Autrijus Tang (ÌÆ×Úºº) <autrijus@autrijus.org>


perljp - ÆüËÜ¸ì Perl ¥¬¥¤¥É

  • ÀâÌÀ
    • About (jcode.pl|Jcode.pm|JPerl)
    • ¤µ¤é¤Ë¾Ü¤·¤¯
    • PerlÁ´ÈÌ¤Ë´Ø¤¹¤ë URL
    • Perl¤Î½¤ÆÀ¤ËÌòÎ©¤Ä URL
    • Perl ¥æ¡¼¥¶¡¼¥°¥ë¡¼¥×
    • Unicode´ØÏ¢¤ÎURL
  • AUTHORS

NAME

perljp - ÆüËÜ¸ì Perl ¥¬¥¤¥É

ÀâÌÀ

Perl ¤ÎÀ¤³¦¤Ø¤è¤¦¤³¤½!

Perl 5.8.0 ¤è¤ê¡¢Unicode¥µ¥Ý¡¼¥È¤¬ÂçÉý¤Ë¶¯²½¤µ¤ì¡¢¤½¤Î·ë²Ì¥é¥Æ¥óÊ¸»ú°Ê³°¤ÎÊ¸»ú¥³¡¼¥É¤Î¥µ¥Ý¡¼¥È¤¬ CJK (Ãæ¹ñ¸ì¡¢ÆüËÜ¸ì¡¢¥Ï¥ó¥°¥ë)¤ò´Þ¤á¤Æ²Ã¤ï¤ê¤Þ¤·¤¿¡£Unicode¤ÏÀ¤³¦Ãæ¤ÎÊ¸»ú¤ò°ì¤Ä¤ÎÊ¸»ú¥³¡¼¥É¤Ç°·¤¦¤³¤È¤òÌÜ»Ø¤·¤¿É¸½àµ¬³Ê¤Ç¤¢¤ê¡¢Åì¤«¤éÀ¾¡¢¤Ï¤¿¤Þ¤¿¤½¤Î´Ö¤ÎÊ¸»ú¡Ê¥®¥ê¥·¥ãÊ¸»ú¡¢¥¥ê¡¼¥ëÊ¸»ú¡¢¥¢¥é¥Ó¥¢Ê¸»ú¡¢¥Ø¥Ö¥é¥¤Ê¸»ú¡¢¥Ç¥£¡¼¥ô¥¡¥Ê¥¬¡¼¥êÊ¸»ú¡¢¤Ê¤É¤Ê¤É¡Ë¤ä¡¢¤³¤ì¤Þ¤Ç¤ÏOS¥Ù¥ó¥À¡¼¤¬ÆÈ¼«¤ËÄê¤á¤Æ¤¤¤¿Ê¸»ú(PC¤ª¤è¤ÓMacintosh)¤¬¤¹¤Ç¤Ë´Þ¤Þ¤ì¤Æ¤¤¤Þ¤¹¡£

Perl ¼«¿È¤Ï Unicode ¤ÇÆ°ºî¤·¤Þ¤¹¡£Perl ¥¹¥¯¥ê¥×¥ÈÆâ¤ÎÊ¸»úÎó¥ê¥Æ¥é¥ë¤äÀµµ¬É½¸½¤Ï Unicode ¤òÁ°Äó¤È¤·¤Æ¤¤¤Þ¤¹¡£¤½¤·¤ÆÆþ½ÐÎÏ¤Î¤¿¤á¤Ë¤Ï¡¢¤³¤ì¤Þ¤Ç»È¤ï¤ì¤Æ¤¤¿¤µ¤Þ¤¶¤Þ¤ÊÊ¸»ú¥³¡¼¥É¤ËÂÐ±þ¤¹¤ë¥â¥¸¥å¡¼¥ë¡¢¡Ö Encode ¡×¤¬É¸½àÁõÈ÷¤µ¤ì¤Æ¤ª¤ê¡¢Unicode ¤È¤³¤ì¤é¤ÎÊ¸»ú¥³¡¼¥É¤ÎÁê¸ßÊÑ´¹¤â´ÊÃ±¤Ë¹Ô¤¨¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤Þ¤¹¡£

¸½»þÅÀ¤Ç Encode ¤¬¥µ¥Ý¡¼¥È¤¹¤ëÊ¸»ú¥³¡¼¥É¤Ï°Ê²¼¤Î¤È¤ª¤ê¤Ç¤¹¡£

  7bit-jis      AdobeStandardEncoding AdobeSymbol       AdobeZdingbat
  ascii             big5              big5-hkscs        cp1006
  cp1026            cp1047            cp1250            cp1251
  cp1252            cp1253            cp1254            cp1255
  cp1256            cp1257            cp1258            cp37
  cp424             cp437             cp500             cp737
  cp775             cp850             cp852             cp855
  cp856             cp857             cp860             cp861
  cp862             cp863             cp864             cp865
  cp866             cp869             cp874             cp875
  cp932             cp936             cp949             cp950
  dingbats          euc-cn            euc-jp            euc-kr
  gb12345-raw       gb2312-raw        gsm0338           hp-roman8
  hz                iso-2022-jp       iso-2022-jp-1     iso-8859-1
  iso-8859-10       iso-8859-11       iso-8859-13       iso-8859-14
  iso-8859-15       iso-8859-16       iso-8859-2        iso-8859-3
  iso-8859-4        iso-8859-5        iso-8859-6        iso-8859-7
  iso-8859-8        iso-8859-9        iso-ir-165        jis0201-raw
  jis0208-raw       jis0212-raw       johab             koi8-f
  koi8-r            koi8-u            ksc5601-raw       MacArabic
  MacCentralEurRoman  MacChineseSimp    MacChineseTrad    MacCroatian
  MacCyrillic       MacDingbats       MacFarsi          MacGreek
  MacHebrew         MacIcelandic      MacJapanese       MacKorean
  MacRoman          MacRomanian       MacRumanian       MacSami
  MacSymbol         MacThai           MacTurkish        MacUkrainian
  nextstep          posix-bc          shiftjis          symbol
  UCS-2BE           UCS-2LE           UTF-16            UTF-16BE
  UTF-16LE          UTF-32            UTF-32BE          UTF-32LE
  utf8              viscii

(Á´114¼ïÎà)

Îã¤¨¤Ð¡¢Ê¸»ú¥³¡¼¥ÉFOO¤Î¥Õ¥¡¥¤¥ë¤òUTF-8¤ËÊÑ´¹¤¹¤ë¤Ë¤Ï¡¢°Ê²¼¤Î¤è¤¦¤Ë¤·¤Þ¤¹¡£

    perl -Mencoding=FOO,STDOUT,utf8 -pe1 < file.FOO > file.utf8

¤Þ¤¿¡¢Perl¤Ë¤Ï¡¢Á´Éô¤¬Perl¤Ç½ñ¤«¤ì¤¿Ê¸»ú¥³¡¼¥ÉÊÑ´¹¥æ¡¼¥Æ¥£¥ê¥Æ¥£¡¢piconv¤âÉÕÂ°¤·¤Æ¤¤¤ë¤Î¤Ç¡¢°Ê²¼¤Î¤è¤¦¤Ë¤¹¤ë¤³¤È¤â¤Ç¤¤Þ¤¹¡£

   piconv -f FOO -t utf8 < file.FOO > file.utf8
   piconv -f utf8 -t FOO < file.utf8 > file.FOO

About (jcode.pl|Jcode.pm|JPerl)

5.8°ÊÁ°¤Î¡¢¥¹¥¯¥ê¥×¥È¤¬EUC-JP¤Ç¤¢¤ì¤Ð¥ê¥Æ¥é¥ë¤À¤±¤Ï°·¤¦¤³¤È¤¬¤Ç¤¤Þ¤·¤¿¡£¤Þ¤¿¡¢Æþ½ÐÎÏ¤ò°·¤¦¥â¥¸¥å¡¼¥ë¤È¤·¤Æ¤ÏJcode.pm¤¬( http://openlab.jp/Jcode/ )¡¢perl4ÍÑ¤Î¥æ¡¼¥Æ¥£¥ê¥Æ¥£¤È¤·¤Æ¤Ïjcode.pl( http://srekcah.org/jcode/ )¤¬¤½¤ì¤¾¤ìÂ¸ºß¤·¡¢ÆüËÜ¸ì¤Î°·¤¨¤ëCGI¤Ç¤è¤¯ÍøÍÑ¤µ¤ì¤Æ¤¤¤ë¤³¤È¤ò¸æÂ¸¤¸¤ÎÊý¤â¾¯¤Ê¤¯¤Ê¤¤¤«¤È»×¤ï¤ì¤Þ¤¹¡£¤¿¤À¤·¡¢ÆüËÜ¸ì¤Ë¤è¤ëÀµµ¬É½¸½¤ò¤¦¤Þ¤¯°·¤¦¤³¤È¤ÏÉÔ²ÄÇ½¤Ç¤·¤¿¡£

5.005°ÊÁ°¤ÎPerl¤Ë¤Ï¡¢ÆüËÜ¸ì¤ËÆÃ²½¤·¤¿¥í¡¼¥«¥é¥¤¥ºÈÇ¡¢Jperl¤¬Â¸ºß¤·¤Þ¤·¤¿( http://homepage2.nifty.com/kipp/perl/jperl/index.html )¡£¤Þ¤¿¡¢Mac OS 9.x/ClassicÍÑ¤ÎPerl¡¢MacPerl¤ÎÆüËÜ¸ìÈÇ¤âMacJPerl¤È¤·¤ÆÂ¸ºß¤·¤Æ¤Þ¤·¤¿¡£( http://world.std.com/~habilis/macjperl/ ).¤³¤ì¤é¤Ç¤ÏÊ¸»ú¥³¡¼¥É¤È¤·¤ÆEUC-JP¤Ë²Ã¤¨Shift_JIS¤â¤½¤Î¤Þ¤Þ°·¤¦¤³¤È¤¬¤Ç¤¡¢¤Þ¤¿ÆüËÜ¸ì¤Ë¤è¤ëÀµµ¬É½¸½¤ò°·¤¦¤³¤È¤â²ÄÇ½¤Ç¤·¤¿¡£

Perl5.8¤Ç¤Ï¡¢¤³¤ì¤é¤Îµ¡Ç½¤¬¤¹¤Ù¤ÆPerlËÜÂÎ¤À¤±¤Ç¼Â¸½¤Ç¤¤ë¾å¤Ë¡¢ÆüËÜ¸ì¤Î¤ß¤Ê¤é¤º¾åµ114¤ÎÊ¸»ú¥³¡¼¥É¤ò¤¹¤Ù¤Æ¡¢¤·¤«¤âÆ±»þ¤Ë°·¤¦¤³¤È¤¬¤Ç¤¤Þ¤¹¡£¤µ¤é¤Ë¡¢CPAN¤Ê¤É¤«¤é¿·¤·¤¤Ê¸»ú¥³¡¼¥ÉÍÑ¤Î¥â¥¸¥å¡¼¥ë¤òÆþ¼ê¤¹¤ë¤³¤È¤â´ÊÃ±¤Ë¤Ç¤¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤Þ¤¹¡£

  • Æþ½ÐÎÏ

    °Ê²¼¤ÎÎã¤Ï¤¤¤Å¤ì¤âShift_JIS¤ÎÆþÎÏ¤òEUC-JP¤ËÊÑ´¹¤·¤Æ½ÐÎÏ¤·¤Þ¤¹¡£

      # jcode.pl
  require "jcode.pl";
  while(<>){
    jcode::convert(*_, 'euc', 'sjis');
    print;
  }
  # Jcode.pm
  use Jcode;
  while(<>){
        print Jcode->new($_, 'sjis')->euc;
  }
  # Perl 5.8
  use Encode;
  while(<>){
    from_to($_, 'shiftjis', 'euc-jp');
    print;
  }
  # Perl 5.8 - encoding ¤òÍøÍÑ¤·¤Æ
  use encoding 'euc-jp', STDIN => 'shiftjis';
  while(<>){
        print;
  }

  • Jperl ¸ß´¹¥¹¥¯¥ê¥×¥È

     ¤¤¤ï¤æ¤ë"shebang"¤òÊÑ¹¹¤¹¤ë¤À¤±¤Ç¡¢JperlÍÑ¤Îscript¤Î¤Û¤È¤ó¤É¤ÏÊÑ¹¹¤Ê¤·¤ËÍøÍÑ²ÄÇ½¤À¤È»×¤ï¤ì¤Þ¤¹¡£
       #!/path/to/jperl
   ¢
   #!/path/to/perl -Mencoding=euc-jp
     ¾Ü¤·¤¯¤Ï perldoc encoding ¤ò»²¾È¤·¤Æ¤¯¤À¤µ¤¤¡£

¤µ¤é¤Ë¾Ü¤·¤¯

Perl¤Ë¤ÏËÄÂç¤Ê»ñÎÁ¤¬ÉÕÂ°¤·¤Æ¤ª¤ê¡¢Perl¤Î¿·µ¡Ç½¤äUnicode¥µ¥Ý¡¼¥È¡¢¤½¤·¤ÆEncode¥â¥¸¥å¡¼¥ë¤Î»ÈÍÑË¡¤Ê¤É¤¬ºÙ¤«¤¯ÌÖÍå¤µ¤ì¤Æ¤¤¤Þ¤¹¡Ê»ÄÇ°¤Ê¤¬¤é¡¢¤Û¤È¤ó¤É±Ñ¸ì¤Ç¤Ï¤¢¤ê¤Þ¤¹¤¬¡Ë¡£°Ê²¼¤Î¥³¥Þ¥ó¥É¤Ç¤½¤ì¤é¤Î°ìÉô¤ò±ÜÍ÷¤¹¤ë¤³¤È¤¬²ÄÇ½¤Ç¤¹¡£

  perldoc perlunicode # Perl¤ÎUnicode¥µ¥Ý¡¼¥ÈÁ´ÈÌ
  perldoc Encode      # Encode¥â¥¸¥å¡¼¥ë¤Ë´Ø¤·¤Æ
  perldoc Encode::JP  # ¤¦¤ÁÆüËÜ¸ìÊ¸»ú¥³¡¼¥É¤Ë´Ø¤·¤Æ

PerlÁ´ÈÌ¤Ë´Ø¤¹¤ë URL

http://www.perl.com/

Perl ¥Û¡¼¥à¥Ú¡¼¥¸ (O'Reilly and Associates)

http://www.cpan.org/

CPAN (Comprehensive Perl Archive Network)

http://lists.perl.org/

Perl ¥á¡¼¥ê¥ó¥°¥ê¥¹¥È½¸

Perl¤Î½¤ÆÀ¤ËÌòÎ©¤Ä URL

http://www.oreilly.com.tw/chinese/

O'Reilly ¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(ÈËÂÎ»úÃæ¹ñ¸ì)

http://www.oreilly.com.cn/chinese/

O'Reilly ¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(´ÊÂÎ»úÃæ¹ñ¸ì)

http://www.oreilly.co.jp/catalog.htm

¥ª¥é¥¤¥ê¡¼¼Ò¤ÎPerl´ØÏ¢½ñÀÒ(ÆüËÜ¸ì)

Perl ¥æ¡¼¥¶¡¼¥°¥ë¡¼¥×

http://www.pm.org/groups/asia.shtml#China

Ãæ¹ñ¡ÊÃæ²Ú¿ÍÌ±¶¦ÏÂ¹ñ¡Ë

http://www.pm.org/groups/asia.shtml#Japan

ÆüËÜ

http://www.pm.org/groups/asia.shtml#Korea%20(Republic%20of)

´Ú¹ñ¡ÊÂç´ÚÌ±¹ñ¡Ë

http://www.pm.org/groups/asia.shtml#Taiwan

ÂæÏÑ¡ÊÃæ²ÚÌ±¹ñ¡Ë

Unicode´ØÏ¢¤ÎURL

http://www.unicode.org/

Unicode ¥³¥ó¥½¡¼¥·¥¢¥à (Unicodeµ¬³Ê¤ÎÁªÄêÃÄÂÎ)

http://www.cl.cam.ac.uk/%7Emgk25/unicode.html

UTF-8 and Unicode FAQ for Unix/Linux

http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html

UTF-8 and Unicode FAQ for Unix/Linux (¥Ï¥ó¥°¥ëÌõ)

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi> Dan Kogai (¾®»ô¡¡ÃÆ) <dankogai@dan.co.jp>


perlko - Perl°ú ÇÑ±¹¾î ÀÎÄÚµù

    • ´õ ÀÚ¼¼È÷ ¾Ë°í ½ÍÀ¸¸é...
    • Perl °ü·Ã ÀÚ·á
    • PerlÀ» ´õ ±í°Ô °øºÎÇÏ´Âµ¥ µµ¿òÀ» ÁÙ ¼ö ÀÖ´Â ÇÑ±¹¾î °ü·Ã »çÀÌÆ®
    • À¯´ÏÄÚµå ¹× ÇÑ±¹¾î ÀÎÄÚµù °ü·Ã ÀÚ·á
  • SEE ALSO
  • AUTHORS

NAME

perlko - Perl°ú ÇÑ±¹¾î ÀÎÄÚµù

DESCRIPTION

PerlÀÇ ¼¼°è¿¡ ¿À½Å °ÍÀ» È¯¿µÇÕ´Ï´Ù !

PerlÀº 5.8.0ÆÇºÎÅÍ À¯´ÏÄÚµå/ISO 10646¿¡ ´ëÇÑ ±¤¹üÀ§ÇÑ Áö¿øÀ» ÇÕ´Ï´Ù. À¯´ÏÄÚµå Áö¿øÀÇ ÀÏÈ¯À¸·Î ÇÑÁßÀÏÀ» ºñ·ÔÇÑ ¼¼°è °¢±¹¿¡¼ À¯´ÏÄÚµå ÀÌÀü¿¡ ¾²°í ÀÖ¾ú°í Áö±Ýµµ ³Î¸® ¾²ÀÌ°í ÀÖ´Â ¼ö¸¹Àº ÀÎÄÚµùÀ» Áö¿øÇÕ´Ï´Ù. À¯´ÏÄÚµå´Â Àü ¼¼°è¿¡¼ ¾²ÀÌ´Â ¸ðµç ¾ð¾î¸¦ À§ÇÑ Ç¥±â Ã¼°è - À¯·´ÀÇ ¶óÆ¾ ¾ËÆÄºª, Å°¸± ¾ËÆÄºª, ±×¸®½º ¾ËÆÄºª, ÀÎµµ¿Í µ¿³² ¾Æ½Ã¾ÆÀÇ ºê¶ó¹Ì °è¿ ½ºÅ©¸³Æ®, ¾Æ¶ø ¹®ÀÚ, È÷ºê¸® ¹®ÀÚ, ÇÑÁßÀÏÀÇ ÇÑÀÚ, ÇÑ±¹¾îÀÇ ÇÑ±Û, ÀÏº»¾îÀÇ °¡³ª, ºÏ¹Ì ÀÎµð¾ÈÀÇ Ç¥±â Ã¼°è µî-¸¦ ¼ö¿ëÇÏ´Â °ÍÀ» ¸ñÇ¥·Î ÇÏ°í ÀÖ±â ¶§¹®¿¡ ±âÁ¸¿¡ ¾²ÀÌ´ø °¢ ¾ð¾î ¹× ±¹°¡ ±×¸®°í ¿î¿µ Ã¼°è¿¡ °íÀ¯ÇÑ ¹®ÀÚ ÁýÇÕ°ú ÀÎÄÚµù¿¡ ¾µ ¼ö ÀÖ´Â ¸ðµç ±ÛÀÚ´Â ¹°·ÐÀÌ°í ±âÁ¸ ¹®ÀÚ ÁýÇÕ¿¡¼ Áö¿øÇÏ°í ÀÖÁö ¾Ê´ø ¾ÆÁÖ ¸¹Àº ±ÛÀÚ¸¦ Æ÷ÇÔÇÏ°í ÀÖ½À´Ï´Ù.

PerlÀº ³»ºÎÀûÀ¸·Î À¯´ÏÄÚµå¸¦ ¹®ÀÚ Ç¥ÇöÀ» À§ÇØ »ç¿ëÇÕ´Ï´Ù. º¸´Ù ±¸Ã¼ÀûÀ¸·Î ¸»ÇÏ¸é Perl ½ºÅ©¸³Æ® ¾È¿¡¼ UTF-8 ¹®ÀÚ¿À» ¾µ ¼ö ÀÖ°í, °¢Á¾ ÇÔ¼ö¿Í ¿¬»êÀÚ(¿¹¸¦ µé¾î, Á¤±Ô½Ä, index, substr)°¡ ¹ÙÀÌÆ® ´ÜÀ§ ´ë½Å À¯´ÏÄÚµå ±ÛÀÚ ´ÜÀ§·Î µ¿ÀÛÇÕ´Ï´Ù. (´õ ÀÚ¼¼ÇÑ °ÍÀº perlunicode ¸Å´º¾óÀ» Âü°íÇÏ½Ê½Ã¿À.) À¯´ÏÄÚµå°¡ ³Î¸® º¸±ÞµÇ±â Àü¿¡ ³Î¸® ¾²ÀÌ°í ÀÖ¾ú°í, ¿©ÀüÈ÷ ³Î¸® ¾²ÀÌ°í ÀÖ´Â °¢±¹/°¢ ¾ð¾îº° ÀÎÄÚµùÀ¸·Î ÀÔÃâ·ÂÀ» ÇÏ°í ÀÌµé ÀÎÄÚµùÀ¸·Î µÈ µ¥ÀÌÅÍ¿Í ¹®¼¸¦ ´Ù·ç´Â °ÍÀ» µ½±â À§ÇØ 'Encode'°¡ ¾²¿´½À´Ï´Ù. ¹«¾ùº¸´Ù 'Encode'¸¦ ½á¼ ¼ö¸¹Àº ÀÎÄÚµù »çÀÌÀÇ º¯È¯À» ½±°Ô ÇÒ ¼ö ÀÖ½À´Ï´Ù.

'Encode'´Â ´ÙÀ½°ú °°Àº ÇÑ±¹¾î ÀÎÄÚµùÀ» Áö¿øÇÕ´Ï´Ù.

euc-kr
  US-ASCII¿Í KS X 1001À» °°ÀÌ ¾²´Â ¸ÖÆ¼¹ÙÀÌÆ® ÀÎÄÚµù (ÈçÈ÷ ¿Ï¼ºÇüÀÌ¶ó°í
  ºÒ¸².) KS X 2901°ú RFC 1557 Âü°í.
cp949
        MS-Windows 9x/ME¿¡¼ ¾²ÀÌ´Â È®Àå ¿Ï¼ºÇü.  euc-kr¿¡ 8,822ÀÚÀÇ
        ÇÑ±Û À½ÀýÀ» ´õÇÑ °ÍÀÓ.  alias´Â uhc, windows-949, x-windows-949,
        ks_c_5601-1987. ¸Ç ¸¶Áö¸· ÀÌ¸§Àº ÀûÀýÇÏÁö ¾ÊÀº ÀÌ¸§ÀÌÁö¸¸, Microsoft
        Á¦Ç°¿¡¼ CP949ÀÇ ÀÇ¹Ì·Î ¾²ÀÌ°í ÀÖÀ½.
johab
        KS X 1001:1998 ºÎ·Ï 3¿¡¼ ±ÔÁ¤ÇÑ Á¶ÇÕÇü.  ¹®ÀÚ ·¹ÆÛÅä¸®´Â cp949¿Í
        ¸¶Âù°¡Áö·Î US-ASCII¿Í  KS X 1001¿¡ 8,822ÀÚÀÇ ÇÑ±Û À½ÀýÀ» ´õÇÑ °ÍÀÓ.
        ÀÎÄÚµù ¹æ½ÄÀº ÀüÇô ´Ù¸§.
iso-2022-kr
        RFC 1557¿¡¼ ±ÔÁ¤ÇÑ ÇÑ±¹¾î ÀÎÅÍ³Ý ¸ÞÀÏ ±³È¯¿ë ÀÎÄÚµùÀ¸·Î US-ASCII¿Í
        KS X 1001À» ·¹ÆÛÅä¸®·Î ÇÏ´Â Á¡¿¡¼ euc-kr°ú °°Áö¸¸ ÀÎÄÚµù ¹æ½ÄÀÌ ´Ù¸§.
        1997-8³â °æ±îÁö ¾²¿´À¸³ª ´õ ÀÌ»ó ¸ÞÀÏ ±³È¯¿¡ ¾²ÀÌÁö ¾ÊÀ½.
ksc5601-raw
        KS X 1001(KS C 5601)À» GL(Áï, MSB¸¦ 0À¸·Î ÇÑ °æ¿ì) ¿¡ ³õ¾ÒÀ» ¶§ÀÇ
        ÀÎÄÚµù. US-ASCII¿Í °áÇÕÇÏÁö ¾Ê°í ´Üµ¶À¸·Î ¾²ÀÌ´Â ÀÏÀº X11 µî¿¡¼ ±Û²Ã
        ÀÎÄÚµù (ksc5601.1987-0. '0'Àº GLÀ» ÀÇ¹ÌÇÔ.)À¸·Î ¾²ÀÌ´Â °ÍÀ» Á¦¿ÜÇÏ°í´Â
        °ÅÀÇ ¾øÀ½. KS C 5601Àº 1997³â KS X 1001·Î ÀÌ¸§À» ¹Ù²Ù¾úÀ½.  1998³â¿¡´Â  µÎ
        ±ÛÀÚ (À¯·ÎÈ ºÎÈ£¿Í µî·Ï »óÇ¥ ºÎÈ£)°¡ ´õÇØÁ³À½.
 ¸î °¡Áö »ç¿ë ¿¹Á¦¸¦ ¾Æ·¡¿¡ º¸ÀÔ´Ï´Ù.

¿¹¸¦ µé¾î, euc-kr ÀÎÄÚµùÀ¸·Î µÈ ÆÄÀÏÀ» UTF-8·Î º¯È¯ÇÏ·Á¸é ´ÙÀ½°ú °°ÀÌ ÇÏ¸é µË´Ï´Ù.

    perl -Mencoding=euc-kr,STDOUT,utf8 -pe1  < file.euckr > file.utf8

¿ªº¯È¯Àº ´ÙÀ½°ú °°ÀÌ ÇÒ ¼ö ÀÖ½À´Ï´Ù.

    perl -Mencoding=utf8,STDOUT,euc-kr -pe1  < file.utf8  > file.euckr
  ÀÌ·± º¯È¯À» Á»´õ Æí¸®ÇÏ°Ô ÇÒ ¼ö ÀÖµµ·Ï Encode ¸ðµâÀ» ½á¼
¼ø¼öÇÏ°Ô Perl·Î¸¸ ¾²ÀÎ piconv°¡ Perl¿¡ µé¾î ÀÖ½À´Ï´Ù.
±× ÀÌ¸§¿¡¼ ¾Ë ¼ö ÀÖµíÀÌ piconv´Â Unix¿¡ ÀÖ´Â iconv¸¦
¸ðµ¨·Î ÇÑ °ÍÀÔ´Ï´Ù. ±× »ç¿ë¹ýÀº ¾Æ·¡¿Í °°½À´Ï´Ù.
   piconv -f euc-kr -t utf8 < file.euckr > file.utf8
   piconv -f utf8 -t euc-kr < file.utf8 > file.euckr
  ¶Ç, 'PerlIO::encoding' ¸ðµâÀ» ½á¼ ÇÑ±¹¾î ÀÎÄÚµùÀ» ¾²¸é¼ ±ÛÀÚ ´ÜÀ§
(¹ÙÀÌÆ® ´ÜÀ§°¡ ¾Æ´Ï¶ó) Ã³¸®¸¦ ½±°Ô ÇÒ ¼ö ÀÖ½À´Ï´Ù.
  #!/path/to/perl

  use encoding 'euc-kr', STDIN => 'euc-kr',
                         STDOUT-> 'euc-kr', STDERR=>'euc-kr';
  print length("°¡³ª");        # 2  (Å« µû¿ÈÇ¥´Â ±ÛÀÚ ´ÜÀ§ Ã³¸®¸¦ Áö½Ã)
  print length('°¡³ª');        # 4  (ÀÛÀº µû¿ÈÇ¥´Â ¹ÙÀÌÆ® ´ÜÀ§ Ã³¸®¸¦ Áö½Ã)
  print index("ÇÑ°, ´ëµ¿°", "¿°");   # -1 ('¿°'ÀÌ ¾øÀ½)
  print index('ÇÑ°, ´ëµ¿°', '¿°');   # 7 (8¹øÂ°¿Í 9¹øÂ° ¹ÙÀÌÆ®°¡ '¿°'ÀÇ
                                            ÄÚµå°ª°ú ÀÏÄ¡ÇÔ.)

´õ ÀÚ¼¼È÷ ¾Ë°í ½ÍÀ¸¸é...

  PerlÀ» ¼³Ä¡ÇÏ¸é  ´ë´ÜÈ÷ ÀÚ¼¼ÇÑ ¹®¼°¡ °°ÀÌ µû¶ó ¿À¸ç, ÀÌ ¹®¼¸¦ ÅëÇØ
Perl Àü¹Ý »Ó ¾Æ´Ï¶ó À¯´ÏÄÚµå Áö¿ø, EncodeÀÇ »ç¿ë¹ý µî¿¡ ¸¹Àº °ÍÀ»
¹è¿ï ¼ö ÀÖ½À´Ï´Ù.  ¾ÆÁ÷ ÀÌ ¹®¼´Â ÇöÀç ¸ðµÎ ¿µ¾î·Î ¾²¿© ÀÖ½À´Ï´Ù.

Perl °ü·Ã ÀÚ·á

À§¿¡¼ ¾ð±ÞÇÑ ¹®¼ ¿Ü¿¡µµ ´ÙÀ½°ú °°Àº ÀÚ·á°¡ ÀÖ½À´Ï´Ù. ÀÌ ¸ñ·ÏÀº °áÄÚ ¿ÏÀüÇÑ °ÍÀÌ ¾Æ´Ï°í ÀÏºÎ ´ëÇ¥ÀûÀÎ °Í¸¸ ¸ðÀº °ÍÀÔ´Ï´Ù.

http://www.perl.com/
   O'ReillyÀÇ Perl À¥ ÆäÀÌÁö
http://www.cpan.org/
        Comprehensive Perl Archive Network
http://lists.perl.org/
  Perl ¸ÞÀÏ¸µ ¸®½ºÆ®. ¸¹Àº ¸®½ºÆ® °¡¿îµ¥
  perl-unicode¿¡¼ 'Encode'¿¡ ´ëÇØ ³íÀÇÇÔ.

PerlÀ» ´õ ±í°Ô °øºÎÇÏ´Âµ¥ µµ¿òÀ» ÁÙ ¼ö ÀÖ´Â ÇÑ±¹¾î °ü·Ã »çÀÌÆ®

http://www.perl.or.kr/
  Perl ÇÑ±¹ »ç¿ëÀÚ ¸ðÀÓ
news:han.comp.lang.perl/
  ÇÑ±¹¾î Perl ´º½º ±×·ì
http://seoul.pm.org/
  Perl ¸Á°Å½º (¼¿ï)
http://www.perlmania.or.kr/
  Home for Korean Perlmanias
http://www.oreilly.co.kr/perl/
  O'Reilly¿¡¼ ³ª¿Â ÇÑ±¹¾î Perl ¼Àû ¸ñ·Ï
http://www.perlschool.net/
  Perl ±âÃÊ °ÁÂ ¹× ¼Ò½º, ÃÖ±Ù µ¿Çâ, °ü·Ã ÇØ¿Ü »çÀÌÆ® ¸µÅ©
http://www.perl.co.kr
  Perl¿¡ °ü·ÃµÈ CGI, DB, ¿¬µ¿ µî¿¡ ´ëÇÑ  Á¤º¸ ¹× ´º½º Á¦°ø

À¯´ÏÄÚµå ¹× ÇÑ±¹¾î ÀÎÄÚµù °ü·Ã ÀÚ·á

http://www.unicode.org/
  À¯´ÏÄÚµå ÄÁ¼Ò½Ã¾ö.
http://std.dkuug.dk/JTC1/SC2/WG2

±âº»ÀûÀ¸·Î Unicode¿Í °°Àº ISO Ç¥ÁØÀÎ ISO/IEC 10646 UCS(Universal Character Set)À» ¸¸µå´Â ISO/IEC JTC1/SC2/WG2ÀÇ À¥ ÆäÀÌÁö.

http://jshin.net/faq/qa8.html
  ÇÑ±¹¾î ¹®ÀÚ ÁýÇÕ ¹× ÀÎÄÚµù¿¡ ´ëÇÑ ¾È³».
http://www.cl.cam.ac.uk/~mgk25/unicode.html
  À¯´Ð½º/¸®´ª½º¿¡¼ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ)
http://kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html
  À¯´Ð½º/¸®´ª½º¿¡¼ À¯´ÏÄÚµå¿Í UTF-8 »ç¿ë¿¡ ´ëÇÑ ¹®´äÁý(FAQ)ÀÇ  ÇÑ±¹¾î ¹ø¿ª

SEE ALSO

the Encode manpage, the Encode::KR manpage, the encoding manpage, the perluniintro manpage, the perlunicode manpage

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi> ½ÅÁ¤½Ä <jshin@mailaps.org>


perltoc - perl documentation table of contents

  • BASIC DOCUMENTATION
    • perl - Practical Extraction and Report Language
    • perlintro - a brief introduction and overview of Perl
    • perlreftut - Mark's very short tutorial about references
    • perldsc - Perl Data Structures Cookbook
    • perllol - Manipulating Arrays of Arrays in Perl
    • perlrequick - Perl regular expressions quick start
    • perlretut - Perl regular expressions tutorial
    • perlboot - Beginner's Object-Oriented Tutorial
    • perltoot - Tom's object-oriented tutorial for perl
    • perltooc - Tom's OO Tutorial for Class Data in Perl
    • perlbot - Bag'o Object Tricks (the BOT)
    • perlstyle - Perl style guide
    • perlcheat - Perl 5 Cheat Sheet
    • perltrap - Perl traps for the unwary
    • perldebtut - Perl debugging tutorial
    • perlfaq - frequently asked questions about Perl ($Date: 2005/12/30
    • perlfaq1 - General Questions About Perl ($Revision: 1.19 $, $Date:
    • perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.38 $,
    • perlfaq3 - Programming Tools ($Revision: 1.56 $, $Date: 2005/12/31
    • perlfaq4 - Data Manipulation ($Revision: 1.73 $, $Date: 2005/12/31
    • perlfaq5 - Files and Formats ($Revision: 1.42 $, $Date: 2005/12/31
    • perlfaq6 - Regular Expressions ($Revision: 1.38 $, $Date: 2005/12/31
    • perlfaq7 - General Perl Language Issues ($Revision: 1.28 $, $Date:
    • perlfaq8 - System Interaction ($Revision: 1.27 $, $Date: 2005/12/31
    • perlfaq9 - Networking ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37
    • perlsyn - Perl syntax
    • perldata - Perl data types
    • perlop - Perl operators and precedence
    • perlsub - Perl subroutines
    • perlfunc - Perl builtin functions
    • perlopentut - tutorial on opening things in Perl
    • perlpacktut - tutorial on pack and unpack
    • perlpod - the Plain Old Documentation format
    • perlpodspec - Plain Old Documentation: format specification and
    • perlrun - how to execute the Perl interpreter
    • perldiag - various Perl diagnostics
    • perllexwarn - Perl Lexical Warnings
    • perldebug - Perl debugging
    • perlvar - Perl predefined variables
    • perlre - Perl regular expressions
    • perlreref - Perl Regular Expressions Reference
    • perlref - Perl references and nested data structures
    • perlform - Perl formats
    • perlobj - Perl objects
    • perltie - how to hide an object class in a simple variable
    • perldbmfilter - Perl DBM Filters
    • perlipc - Perl interprocess communication (signals, fifos, pipes,
    • perlfork - Perl's fork() emulation
    • perlnumber - semantics of numbers and numeric operations in Perl
    • perlthrtut - tutorial on threads in Perl
    • perlothrtut - old tutorial on threads in Perl
    • perlport - Writing portable Perl
    • perllocale - Perl locale handling (internationalization and
    • perluniintro - Perl Unicode introduction
    • perlunicode - Unicode support in Perl
    • perlebcdic - Considerations for running Perl on EBCDIC platforms
    • perlsec - Perl security
    • perlmod - Perl modules (packages and symbol tables)
    • perlmodlib - constructing new Perl modules and finding existing ones
    • perlmodstyle - Perl module style guide
    • perlmodinstall - Installing CPAN Modules
    • perlnewmod - preparing a new module for distribution
    • perlutil - utilities packaged with the Perl distribution
    • perlcompile - Introduction to the Perl Compiler-Translator
    • perlfilter - Source Filters
    • perlglossary - Perl Glossary
    • perlembed - how to embed perl in your C program
    • perldebguts - Guts of Perl debugging
    • perlxstut, perlXStut - Tutorial for writing XSUBs
    • perlxs - XS language reference manual
    • perlclib - Internal replacements for standard C library functions
    • perlguts - Introduction to the Perl API
    • perlcall - Perl calling conventions from C
    • perlapi - autogenerated documentation for the perl public API
    • perlintern - autogenerated documentation of purely internal
    • perliol - C API for Perl's implementation of IO in Layers.
    • perlapio - perl's IO abstraction interface.
    • perlhack - How to hack at the Perl internals
    • perlbook - Perl book information
    • perltodo - Perl TO-DO List
    • perldoc - Look up Perl documentation in Pod format.
    • perlhist - the Perl history records
    • perldelta - what is new for perl v5.8.8
    • perl588delta, perldelta - what is new for perl v5.8.8
    • perl587delta, perldelta - what is new for perl v5.8.7
    • perl586delta - what is new for perl v5.8.6
    • perl585delta - what is new for perl v5.8.5
    • perl584delta - what is new for perl v5.8.4
    • perl583delta - what is new for perl v5.8.3
    • perl582delta - what is new for perl v5.8.2
    • perl581delta - what is new for perl v5.8.1
    • perl58delta - what is new for perl v5.8.0
    • perl573delta - what's new for perl v5.7.3
    • perl572delta - what's new for perl v5.7.2
    • perl571delta - what's new for perl v5.7.1
    • perl570delta - what's new for perl v5.7.0
    • perl561delta - what's new for perl v5.6.x
    • perl56delta - what's new for perl v5.6.0
    • perl5005delta - what's new for perl5.005
    • perl5004delta - what's new for perl5.004
    • perlartistic - the Perl Artistic License
    • perlgpl - the GNU General Public License, version 2
    • perlaix, README.aix - Perl version 5 on IBM Unix (AIX) systems
    • perlamiga - Perl under Amiga OS
    • perlapollo, README.apollo - Perl version 5 on Apollo DomainOS
    • perlbeos, README.beos - Perl version 5.8+ on BeOS
    • perlbs2000, README.BS2000 - building and installing Perl for BS2000.
    • perlce - Perl for WinCE
    • perlcygwin, README.cygwin - Perl for Cygwin
    • perldgux - Perl under DG/UX.
    • perldos - Perl under DOS, W31, W95.
    • perlepoc, README.epoc - Perl for EPOC
    • perlfreebsd, README.freebsd - Perl version 5 on FreeBSD systems
    • perlhpux, README.hpux - Perl version 5 on Hewlett-Packard Unix
    • perlhurd, README.hurd - Perl version 5 on Hurd
    • perlirix, README.irix - Perl version 5 on Irix systems
    • perllinux, README.linux - Perl version 5 on Linux systems
    • perlmachten, README.machten - Perl version 5 on Power MachTen
    • perlmacos, README.macos - Perl under Mac OS (Classic)
    • perlmacosx, README.macosx - Perl under Mac OS X
    • perlmint, README.mint - Perl version 5 on Atari MiNT
    • perlmpeix, README.mpeix - Perl/iX for HP e3000 MPE
    • perlnetware - Perl for NetWare
    • perlopenbsd, README.openbsd - Perl version 5 on OpenBSD systems
    • perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
    • perlos390, README.os390 - building and installing Perl for OS/390
    • perlos400, README.os400 - Perl version 5 on OS/400
    • perlplan9 - Plan 9-specific documentation for Perl
    • perlqnx, README.qnx - Perl version 5 on QNX
    • perlsolaris, README.solaris - Perl version 5 on Solaris systems
    • perltru64, README.tru64 - Perl version 5 on Tru64 (formerly known as
    • perluts - Perl under UTS
    • perlvmesa, README.vmesa - building and installing Perl for VM/ESA.
    • perlvms - VMS-specific documentation for Perl
    • perlvos, README.vos - Perl for Stratus VOS
    • perlwin32 - Perl under Windows
  • PRAGMA DOCUMENTATION
    • attrs - set/get attributes of a subroutine (deprecated)
    • re - Perl pragma to alter regular expression behaviour
    • threadshared::shared, threads::shared - Perl extension for sharing
    • threads - Perl extension allowing use of interpreter based threads
    • attributes - get/set subroutine or variable attributes
    • autouse - postpone load of modules until a function is used
    • base - Establish IS-A relationship with base classes at compile time
    • bigint - Transparent BigInteger support for Perl
    • bignum - Transparent BigNumber support for Perl
    • bigrat - Transparent BigNumber/BigRational support for Perl
    • blib - Use MakeMaker's uninstalled version of a package
    • bytes - Perl pragma to force byte semantics rather than character
    • charnames - define character names for \N{named} string literal
    • constant - Perl pragma to declare constants
    • diagnostics, splain - produce verbose warning diagnostics
    • encoding - allows you to write your script in non-ascii or non-utf8
    • fields - compile-time class fields
    • filetest - Perl pragma to control the filetest permission operators
    • if - use a Perl module if a condition holds
    • integer - Perl pragma to use integer arithmetic instead of floating
    • less - perl pragma to request less of something from the compiler
    • lib - manipulate @INC at compile time
    • locale - Perl pragma to use and avoid POSIX locales for built-in
    • open - perl pragma to set default PerlIO layers for input and output
    • ops - Perl pragma to restrict unsafe operations when compiling
    • overload - Package for overloading Perl operations
    • sigtrap - Perl pragma to enable simple signal handling
    • sort - perl pragma to control sort() behaviour
    • strict - Perl pragma to restrict unsafe constructs
    • subs - Perl pragma to predeclare sub names
    • threadshared, threads::shared - Perl extension for sharing data
    • utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source
    • vars - Perl pragma to predeclare global variable names (obsolete)
    • vmsish - Perl pragma to control VMS-specific language features
    • warnings - Perl pragma to control optional warnings
    • warnings::register - warnings import function
  • MODULE DOCUMENTATION
    • AnyDBM_File - provide framework for multiple DBMs
    • Attribute::Handlers - Simpler definition of attribute handlers
    • AutoLoader - load subroutines only on demand
    • AutoSplit - split a package for autoloading
    • B - The Perl Compiler
    • B::Asmdata - Autogenerated data about Perl ops, used to generate
    • B::Assembler - Assemble Perl bytecode
    • B::Bblock - Walk basic blocks
    • B::Bytecode - Perl compiler's bytecode backend
    • B::C - Perl compiler's C backend
    • B::CC - Perl compiler's optimized C translation backend
    • B::Concise - Walk Perl syntax tree, printing concise info about ops
    • B::Debug - Walk Perl syntax tree, printing debug info about ops
    • B::Deparse - Perl compiler backend to produce perl code
    • B::Disassembler - Disassemble Perl bytecode
    • B::Lint - Perl lint
    • B::O, O - Generic interface to Perl Compiler backends
    • B::Showlex - Show lexical variables used in functions or files
    • B::Stackobj - Helper module for CC backend
    • B::Stash - show what stashes are loaded
    • B::Terse - Walk Perl syntax tree, printing terse info about ops
    • B::Xref - Generates cross reference reports for Perl programs
    • Bblock, B::Bblock - Walk basic blocks
    • Benchmark - benchmark running times of Perl code
    • ByteLoader - load byte compiled perl code
    • Bytecode, B::Bytecode - Perl compiler's bytecode backend
    • CGI - Simple Common Gateway Interface Class
    • CGI::Apache - Backward compatibility module for CGI.pm
    • CGI::Carp, CGI::Carp - CGI routines for writing to the HTTPD (or
    • CGI::Cookie - Interface to Netscape Cookies
    • CGI::Fast - CGI Interface for Fast CGI
    • CGI::Pretty - module to produce nicely formatted HTML code
    • CGI::Push - Simple Interface to Server Push
    • CGI::Switch - Backward compatibility module for defunct CGI::Switch
    • CGI::Util - Internal utilities used by CGI module
    • CPAN - query, download and build perl modules from CPAN sites
    • CPAN::FirstTime - Utility for CPAN::Config file Initialization
    • CPAN::Version - utility functions to compare CPAN versions
    • CPANox, CPAN::Nox - Wrapper around CPAN.pm without using any XS
    • Carp, carp - warn of errors (from perspective of caller)
    • Carp::Heavy - heavy machinery, no user serviceable parts inside
    • Class::ISA - report the search path for a class's ISA tree
    • Class::Struct - declare struct-like datatypes as Perl classes
    • Config - access Perl configuration information
    • Cwd - get pathname of current working directory
    • DB - programmatic interface to the Perl debugging API (draft,
    • DBM_Filter - Filter DBM keys/values
    • DB_File - Perl5 access to Berkeley DB version 1.x
    • Data::Dumper - stringified perl data structures, suitable for both
    • Devel::DProf - a Perl code profiler
    • Devel::PPPort - Perl/Pollution/Portability
    • Devel::Peek - A data debugging tool for the XS programmer
    • Devel::SelfStubber - generate stubs for a SelfLoading module
    • Devel::Size - Perl extension for finding the memory usage of Perl
    • Digest - Modules that calculate message digests
    • Digest::MD5 - Perl interface to the MD5 Algorithm
    • Digest::base - Digest base class
    • Digest::file - Calculate digests of files
    • DirHandle - supply object methods for directory handles
    • Dumpvalue - provides screen dump of Perl data.
    • DynaLoader - Dynamically load C libraries into Perl code
    • DynaLoader::XSLoader, XSLoader - Dynamically load C libraries into
    • Encode - character encodings
    • Encode::Alias - alias definitions to encodings
    • Encode::Byte - Single Byte Encodings
    • Encode::CJKConstants - Internally used by Encode::??::ISO_2022_*
    • Encode::CN - China-based Chinese Encodings
    • Encode::CN::HZ - internally used by Encode::CN
    • Encode::Config - internally used by Encode
    • Encode::EBCDIC - EBCDIC Encodings
    • Encode::Encoding - Encode Implementation Base Class
    • Encode::Guess - Guesses encoding from data
    • Encode::JP - Japanese Encodings
    • Encode::JP::H2Z - internally used by Encode::JP::2022_JP*
    • Encode::JP::JIS7 - internally used by Encode::JP
    • Encode::KR - Korean Encodings
    • Encode::KR::2022_KR - internally used by Encode::KR
    • Encode::MIME::Header - MIME 'B' and 'Q' header encoding
    • Encode::PerlIO - a detailed document on Encode and PerlIO
    • Encode::Supported - Encodings supported by Encode
    • Encode::Symbol - Symbol Encodings
    • Encode::TW - Taiwan-based Chinese Encodings
    • Encode::Unicode - Various Unicode Transformation Formats
    • Encode::Unicode::UTF7 - UTF-7 encoding
    • Encode::lib::Encode::Alias, Encode::Alias - alias definitions to
    • Encode::lib::Encode::CJKConstants, Encode::CJKConstants.pm -
    • Encode::lib::Encode::CN::HZ, Encode::CN::HZ - internally used by
    • Encode::lib::Encode::Config, Encode::Config - internally used by
    • Encode::lib::Encode::Encoding, Encode::Encoding - Encode
    • Encode::lib::Encode::Guess, Encode::Guess - Guesses encoding from
    • Encode::lib::Encode::JP::H2Z, Encode::JP::H2Z - internally used by
    • Encode::lib::Encode::JP::JIS7, Encode::JP::JIS7 - internally used
    • Encode::lib::Encode::KR::2022_KR, Encode::KR::2022_KR - internally
    • Encode::lib::Encode::MIME::Header, Encode::MIME::Header - MIME 'B'
    • Encode::lib::Encode::PerlIO, Encode::PerlIO - a detailed document
    • Encode::lib::Encode::Supported, Encode::Supported - Encodings
    • Encode::lib::Encode::Unicode::UTF7, Encode::Unicode::UTF7 - UTF-7
    • Encode::lib::Encoder, Encode::Encoder - Object Oriented Encoder
    • Encodencoding, encoding - allows you to write your script in
    • Encoder, Encode::Encoder - Object Oriented Encoder
    • English - use nice English (or awk) names for ugly punctuation
    • Env - perl module that imports environment variables as scalars or
    • Errno - System errno constants
    • Exporter - Implements default import method for modules
    • Exporter::Heavy - Exporter guts
    • ExtUtils::Command - utilities to replace common UNIX commands in
    • ExtUtils::Command::MM - Commands for the MM's to use in Makefiles
    • ExtUtils::Constant - generate XS code to import C header constants
    • ExtUtils::Constant::Base - base class for ExtUtils::Constant objects
    • ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant
    • ExtUtils::Constant::XS, ExtUtils::Constant::Base - base class for
    • ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
    • ExtUtils::Install - install files from here to there
    • ExtUtils::Installed - Inventory management of installed modules
    • ExtUtils::Liblist - determine libraries to use and how to use them
    • ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass
    • ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix
    • ExtUtils::MM_Any - Platform-agnostic MM methods
    • ExtUtils::MM_BeOS - methods to override UN*X behaviour in
    • ExtUtils::MM_Cygwin - methods to override UN*X behaviour in
    • ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix
    • ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic
    • ExtUtils::MM_NW5 - methods to override UN*X behaviour in
    • ExtUtils::MM_OS2 - methods to override UN*X behaviour in
    • ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix
    • ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix
    • ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker
    • ExtUtils::MM_VMS - methods to override UN*X behaviour in
    • ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix
    • ExtUtils::MM_Win32 - methods to override UN*X behaviour in
    • ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X
    • ExtUtils::MY - ExtUtils::MakeMaker subclass for customization
    • ExtUtils::MakeMaker - Create a module Makefile
    • ExtUtils::MakeMaker::Config - Wrapper around Config.pm
    • ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About
    • ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
    • ExtUtils::MakeMaker::bytes - Version-agnostic bytes.pm
    • ExtUtils::MakeMaker::vmsish - Platform-agnostic vmsish.pm
    • ExtUtils::Manifest - utilities to write and check a MANIFEST file
    • ExtUtils::Miniperl, writemain - write the C code for perlmain.c
    • ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader
    • ExtUtils::Mksymlists - write linker options files for dynamic
    • ExtUtils::Packlist - manage .packlist files
    • ExtUtils::testlib - add blib/* directories to @INC
    • Fatal - replace functions with equivalents which succeed or die
    • Fcntl - load the C Fcntl.h defines
    • File::Basename - Parse file paths into directory, filename and
    • File::CheckTree, validate - run many filetest checks on a tree
    • File::Compare - Compare files or filehandles
    • File::Copy - Copy files or filehandles
    • File::DosGlob - DOS like globbing and then some
    • File::Find - Traverse a directory tree.
    • File::Glob - Perl extension for BSD glob routine
    • File::Path - create or remove directory trees
    • File::Spec - portably perform operations on file names
    • File::Spec::Cygwin - methods for Cygwin file specs
    • File::Spec::Epoc - methods for Epoc file specs
    • File::Spec::Functions - portably perform operations on file names
    • File::Spec::Mac - File::Spec for Mac OS (Classic)
    • File::Spec::OS2 - methods for OS/2 file specs
    • File::Spec::Unix - File::Spec for Unix, base for other File::Spec
    • File::Spec::VMS - methods for VMS file specs
    • File::Spec::Win32 - methods for Win32 file specs
    • File::Temp - return name and handle of a temporary file safely
    • File::stat - by-name interface to Perl's built-in stat() functions
    • FileCache - keep more files open than the system permits
    • FileHandle - supply object methods for filehandles
    • Filter::Simple - Simplified source filtering
    • Filter::Util::Call - Perl Source Filter Utility Module
    • FindBin - Locate directory of original perl script
    • GDBM_File - Perl5 access to the gdbm library.
    • Getopt::Long - Extended processing of command line options
    • Getopt::Std, getopt, getopts - Process single-character switches
    • Hash::Util - A selection of general-utility hash subroutines
    • I18N::Collate - compare 8-bit scalar data according to the current
    • I18N::LangTags - functions for dealing with RFC3066-style language
    • I18N::LangTags::Detect - detect the user's language preferences
    • I18N::LangTags::List - tags and names for human languages
    • I18N::Langinfo - query locale information
    • IO - load various IO modules
    • IO::Dir - supply object methods for directory handles
    • IO::File - supply object methods for filehandles
    • IO::Handle - supply object methods for I/O handles
    • IO::Pipe - supply object methods for pipes
    • IO::Poll - Object interface to system poll call
    • IO::Seekable - supply seek based methods for I/O objects
    • IO::Select - OO interface to the select system call
    • IO::Socket - Object interface to socket communications
    • IO::Socket::INET - Object interface for AF_INET domain sockets
    • IO::Socket::UNIX - Object interface for AF_UNIX domain sockets
    • IO::lib::IO::Dir, IO::Dir - supply object methods for directory
    • IO::lib::IO::File, IO::File - supply object methods for filehandles
    • IO::lib::IO::Handle, IO::Handle - supply object methods for I/O
    • IO::lib::IO::Pipe, IO::Pipe - supply object methods for pipes
    • IO::lib::IO::Poll, IO::Poll - Object interface to system poll call
    • IO::lib::IO::Seekable, IO::Seekable - supply seek based methods for
    • IO::lib::IO::Select, IO::Select - OO interface to the select system
    • IO::lib::IO::Socket, IO::Socket - Object interface to socket
    • IO::lib::IO::Socket::INET, IO::Socket::INET - Object interface for
    • IO::lib::IO::Socket::UNIX, IO::Socket::UNIX - Object interface for
    • IPC::Msg - SysV Msg IPC object class
    • IPC::Open2, open2 - open a process for both reading and writing
    • IPC::Open3, open3 - open a process for reading, writing, and error
    • IPC::Semaphore - SysV Semaphore IPC object class
    • IPC::SysV - SysV IPC constants
    • IPC::SysV::Msg, IPC::Msg - SysV Msg IPC object class
    • IPC::SysV::Semaphore, IPC::Semaphore - SysV Semaphore IPC object
    • List::Util - A selection of general-utility list subroutines
    • List::Utilib::List::Util, List::Util - A selection of
    • List::Utilib::Scalar::Util, Scalar::Util - A selection of
    • Locale::Constants - constants for Locale codes
    • Locale::Country - ISO codes for country identification (ISO 3166)
    • Locale::Currency - ISO three letter codes for currency
    • Locale::Language - ISO two letter codes for language identification
    • Locale::Maketext - framework for localization
    • Locale::Maketext::TPJ13 - article about software localization
    • Locale::Script - ISO codes for script identification (ISO 15924)
    • MIME::Base64 - Encoding and decoding of base64 strings
    • MIME::Base64::QuotedPrint, MIME::QuotedPrint - Encoding and decoding
    • MIME::QuotedPrint - Encoding and decoding of quoted-printable
    • Math::BigFloat - Arbitrary size floating point math package
    • Math::BigInt - Arbitrary size integer/float math package
    • Math::BigInt::Calc - Pure Perl module to support Math::BigInt
    • Math::BigInt::CalcEmu - Emulate low-level math with BigInt code
    • Math::BigRat - Arbitrary big rational numbers
    • Math::Complex - complex numbers and associated mathematical
    • Math::Trig - trigonometric functions
    • Memoize - Make functions faster by trading space for time
    • Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for
    • Memoize::Expire - Plug-in module for automatic expiration of
    • Memoize::ExpireFile - test for Memoize expiration semantics
    • Memoize::ExpireTest - test for Memoize expiration semantics
    • Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for
    • Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for
    • Memoize::Storable - store Memoized data in Storable database
    • NDBM_File - Tied access to ndbm files
    • NEXT - Provide a pseudo-class NEXT (et al) that allows method
    • Net::Cmd - Network Command class (as used by FTP, SMTP etc)
    • Net::Config - Local configuration data for libnet
    • Net::Domain - Attempt to evaluate the current host's internet name
    • Net::FTP - FTP Client class
    • Net::NNTP - NNTP Client class
    • Net::POP3 - Post Office Protocol 3 Client class (RFC1939)
    • Net::Ping - check a remote host for reachability
    • Net::SMTP - Simple Mail Transfer Protocol Client
    • Net::Time - time and daytime network client interface
    • Net::hostent - by-name interface to Perl's built-in gethost*()
    • Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions
    • Net::netent - by-name interface to Perl's built-in getnet*()
    • Net::protoent - by-name interface to Perl's built-in getproto*()
    • Net::servent - by-name interface to Perl's built-in getserv*()
    • Netrc, Net::Netrc - OO interface to users netrc file
    • O - Generic interface to Perl Compiler backends
    • ODBM_File - Tied access to odbm files
    • Opcode - Disable named opcodes when compiling perl code
    • Opcode::Safe, Safe - Compile and execute code in restricted
    • Opcode::ops, ops - Perl pragma to restrict unsafe operations when
    • POSIX - Perl interface to IEEE Std 1003.1
    • PerlIO - On demand loader for PerlIO layers and root of PerlIO::*
    • PerlIO::encoding - encoding layer
    • PerlIO::scalar - in-memory IO, scalar IO
    • PerlIO::via - Helper class for PerlIO layers implemented in perl
    • PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings
    • Pod::Checker, podchecker() - check pod documents for syntax errors
    • Pod::Find - find POD documents in directory trees
    • Pod::Html - module to convert pod files to HTML
    • Pod::InputObjects - objects representing POD input paragraphs,
    • Pod::LaTeX - Convert Pod data to formatted Latex
    • Pod::Man - Convert POD data to formatted *roff input
    • Pod::ParseLink - Parse an L<> formatting code in POD text
    • Pod::ParseUtils - helpers for POD parsing and conversion
    • Pod::Parser - base class for creating POD filters and translators
    • Pod::Perldoc::ToChecker - let Perldoc check Pod for errors
    • Pod::Perldoc::ToMan - let Perldoc render Pod as man pages
    • Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff
    • Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!
    • Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF
    • Pod::Perldoc::ToText - let Perldoc render Pod as plaintext
    • Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod
    • Pod::Perldoc::ToXml - let Perldoc render Pod as XML
    • Pod::PlainText - Convert POD data to formatted ASCII text
    • Pod::Plainer - Perl extension for converting Pod to old style Pod.
    • Pod::Select, podselect() - extract selected sections of POD from
    • Pod::Text - Convert POD data to formatted ASCII text
    • Pod::Text::Color - Convert POD data to formatted color ASCII text
    • Pod::Text::Overstrike - Convert POD data to formatted overstrike
    • Pod::Text::Termcap - Convert POD data to ASCII text with format
    • Pod::Usage, pod2usage() - print a usage message from embedded pod
    • SDBM_File - Tied access to sdbm files
    • Safe - Compile and execute code in restricted compartments
    • Scalar::Util - A selection of general-utility scalar subroutines
    • Search::Dict, look - search for key in dictionary file
    • SelectSaver - save and restore selected file handle
    • SelfLoader - load functions only on demand
    • Shell - run shell commands transparently within perl
    • Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C
    • Storable - persistence for Perl data structures
    • Switch - A switch statement for Perl
    • Symbol - manipulate Perl symbols and their names
    • Sys::Hostname - Try every conceivable way to get hostname
    • Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3) calls
    • Syslog::Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3)
    • Term::ANSIColor - Color screen output using ANSI escape sequences
    • Term::Cap - Perl termcap interface
    • Term::Complete - Perl word completion module
    • Term::ReadLine - Perl interface to various readline packages.
    • Test - provides a simple framework for writing test scripts
    • Test::Builder - Backend for building test libraries
    • Test::Builder::Module - Base class for test modules
    • Test::Builder::Tester - test testsuites that have been built with
    • Test::Builder::Tester::Color - turn on colour in
    • Test::Harness - Run Perl standard test scripts with statistics
    • Test::Harness::Assert - simple assert
    • Test::Harness::Iterator - Internal Test::Harness Iterator
    • Test::Harness::Point - object for tracking a single test point
    • Test::Harness::Straps - detailed analysis of test results
    • Test::Harness::TAP - Documentation for the TAP format
    • Test::More - yet another framework for writing test scripts
    • Test::Simple - Basic utilities for writing tests.
    • Test::Tutorial - A tutorial about writing really basic tests
    • Text::Abbrev, abbrev - create an abbreviation table from a list
    • Text::Balanced - Extract delimited text sequences from strings.
    • Text::ParseWords - parse text into an array of tokens or array of
    • Text::Soundex - Implementation of the Soundex Algorithm as Described
    • Text::Tabs - expand and unexpand tabs per the unix expand(1) and
    • Text::Wrap - line wrapping to form simple paragraphs
    • Thread - manipulate threads in Perl (for old code only)
    • Thread::Queue - thread-safe queues
    • Thread::Semaphore - thread-safe semaphores
    • Thread::Signal - Start a thread which runs signal handlers reliably
    • Thread::Specific - thread-specific keys
    • Tie::Array - base class for tied arrays
    • Tie::File - Access the lines of a disk file via a Perl array
    • Tie::Handle, Tie::StdHandle - base class definitions for tied
    • Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for
    • Tie::Memoize - add data to hash when needed
    • Tie::RefHash - use references as hash keys
    • Tie::Scalar, Tie::StdScalar - base class definitions for tied
    • Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing
    • Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
    • Time::Local - efficiently compute time from local and GMT time
    • Time::gmtime - by-name interface to Perl's built-in gmtime()
    • Time::localtime - by-name interface to Perl's built-in localtime()
    • Time::tm - internal object used by Time::gmtime and Time::localtime
    • UNIVERSAL - base class for ALL classes (blessed references)
    • Unicode::Collate - Unicode Collation Algorithm
    • Unicode::Normalize - Unicode Normalization Forms
    • Unicode::UCD - Unicode character database
    • User::grent - by-name interface to Perl's built-in getgr*()
    • User::pwent - by-name interface to Perl's built-in getpw*()
    • XSLoader - Dynamically load C libraries into Perl code
  • AUXILIARY DOCUMENTATION
  • AUTHOR

NAME

perltoc - perl documentation table of contents

DESCRIPTION

This page provides a brief table of contents for the rest of the Perl documentation set. It is meant to be scanned quickly or grepped through to locate the proper section you're looking for.

BASIC DOCUMENTATION

perl - Practical Extraction and Report Language

SYNOPSIS
Overview
Tutorials
Reference Manual
Internals and C Language Interface
Miscellaneous
Language-Specific
Platform-Specific
DESCRIPTION
AVAILABILITY
ENVIRONMENT
AUTHOR
FILES
SEE ALSO
DIAGNOSTICS
BUGS
NOTES

perlintro -- a brief introduction and overview of Perl

DESCRIPTION
What is Perl?
Running Perl programs
Basic syntax overview
Perl variable types

Scalars, Arrays, Hashes

Variable scoping
Conditional and looping constructs

if, while, for, foreach

Builtin operators and functions

Arithmetic, Numeric comparison, String comparison, Boolean logic, Miscellaneous

Files and I/O
Regular expressions

Simple matching, Simple substitution, More complex regular expressions, Parentheses for capturing, Other regexp features

Writing subroutines
OO Perl
Using Perl modules
AUTHOR

perlreftut - Mark's very short tutorial about references

DESCRIPTION
Who Needs Complicated Data Structures?
The Solution
Syntax
Making References
Using References
An Example
Arrow Rule
Solution
The Rest
Summary
Credits
Distribution Conditions

perldsc - Perl Data Structures Cookbook

DESCRIPTION

arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes, more elaborate constructs

REFERENCES
COMMON MISTAKES
CAVEAT ON PRECEDENCE
WHY YOU SHOULD ALWAYS use strict
DEBUGGING
CODE EXAMPLES
ARRAYS OF ARRAYS
Declaration of an ARRAY OF ARRAYS
Generation of an ARRAY OF ARRAYS
Access and Printing of an ARRAY OF ARRAYS
HASHES OF ARRAYS
Declaration of a HASH OF ARRAYS
Generation of a HASH OF ARRAYS
Access and Printing of a HASH OF ARRAYS
ARRAYS OF HASHES
Declaration of an ARRAY OF HASHES
Generation of an ARRAY OF HASHES
Access and Printing of an ARRAY OF HASHES
HASHES OF HASHES
Declaration of a HASH OF HASHES
Generation of a HASH OF HASHES
Access and Printing of a HASH OF HASHES
MORE ELABORATE RECORDS
Declaration of MORE ELABORATE RECORDS
Declaration of a HASH OF COMPLEX RECORDS
Generation of a HASH OF COMPLEX RECORDS
Database Ties
SEE ALSO
AUTHOR

perllol - Manipulating Arrays of Arrays in Perl

DESCRIPTION
Declaration and Access of Arrays of Arrays
Growing Your Own
Access and Printing
Slices
SEE ALSO
AUTHOR

perlrequick - Perl regular expressions quick start

DESCRIPTION
The Guide
Simple word matching
Using character classes
Matching this or that
Grouping things and hierarchical matching
Extracting matches
Matching repetitions
More matching
Search and replace
The split operator
BUGS
SEE ALSO
AUTHOR AND COPYRIGHT
Acknowledgments

perlretut - Perl regular expressions tutorial

DESCRIPTION
Part 1: The basics
Simple word matching
Using character classes
Matching this or that
Grouping things and hierarchical matching
Extracting matches
Matching repetitions
Building a regexp
Using regular expressions in Perl
Part 2: Power tools
More on characters, strings, and character classes
Compiling and saving regular expressions
Embedding comments and modifiers in a regular expression
Non-capturing groupings
Looking ahead and looking behind
Using independent subexpressions to prevent backtracking
Conditional expressions
A bit of magic: executing Perl code in a regular expression
Pragmas and debugging
BUGS
SEE ALSO
AUTHOR AND COPYRIGHT
Acknowledgments

perlboot - Beginner's Object-Oriented Tutorial

DESCRIPTION
If we could talk to the animals...
Introducing the method invocation arrow
Invoking a barnyard
The extra parameter of method invocation
Calling a second method to simplify things
Inheriting the windpipes
A few notes about @ISA
Overriding the methods
Starting the search from a different place
The SUPER way of doing things
Where we're at so far...
A horse is a horse, of course of course -- or is it?
Invoking an instance method
Accessing the instance data
How to build a horse
Inheriting the constructor
Making a method work with either classes or instances
Adding parameters to a method
More interesting instances
A horse of a different color
Summary
SEE ALSO
COPYRIGHT

perltoot - Tom's object-oriented tutorial for perl

DESCRIPTION
Creating a Class
Object Representation
Class Interface
Constructors and Instance Methods
Planning for the Future: Better Constructors
Destructors
Other Object Methods
Class Data
Accessing Class Data
Debugging Methods
Class Destructors
Documenting the Interface
Aggregation
Inheritance
Overridden Methods
Multiple Inheritance
UNIVERSAL: The Root of All Objects
Alternate Object Representations
Arrays as Objects
Closures as Objects
AUTOLOAD: Proxy Methods
Autoloaded Data Methods
Inherited Autoloaded Data Methods
Metaclassical Tools
Class::Struct
Data Members as Variables
NOTES
Object Terminology
SEE ALSO
AUTHOR AND COPYRIGHT
COPYRIGHT
Acknowledgments

perltooc - Tom's OO Tutorial for Class Data in Perl

DESCRIPTION
Class Data in a Can
Class Data as Package Variables
Putting All Your Eggs in One Basket
Inheritance Concerns
The Eponymous Meta-Object
Indirect References to Class Data
Monadic Classes
Translucent Attributes
Class Data as Lexical Variables
Privacy and Responsibility
File-Scoped Lexicals
More Inheritance Concerns
Locking the Door and Throwing Away the Key
Translucency Revisited
NOTES
SEE ALSO
AUTHOR AND COPYRIGHT
ACKNOWLEDGEMENTS
HISTORY

perlbot - Bag'o Object Tricks (the BOT)

DESCRIPTION
OO SCALING TIPS
INSTANCE VARIABLES
SCALAR INSTANCE VARIABLES
INSTANCE VARIABLE INHERITANCE
OBJECT RELATIONSHIPS
OVERRIDING SUPERCLASS METHODS
USING RELATIONSHIP WITH SDBM
THINKING OF CODE REUSE
CLASS CONTEXT AND THE OBJECT
INHERITING A CONSTRUCTOR
DELEGATION
SEE ALSO

perlstyle - Perl style guide

DESCRIPTION

perlcheat - Perl 5 Cheat Sheet

DESCRIPTION
The sheet
ACKNOWLEDGEMENTS
AUTHOR
SEE ALSO

perltrap - Perl traps for the unwary

DESCRIPTION
Awk Traps
C/C++ Traps
Sed Traps
Shell Traps
Perl Traps
Perl4 to Perl5 Traps

Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical Traps, General data type traps, Context Traps - scalar, list contexts, Precedence Traps, General Regular Expression Traps using s///, etc, Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps

Discontinuance, Deprecation, and BugFix traps

Symbols starting with "_" no longer forced into main, Double-colon valid package separator in variable name, 2nd and 3rd args to splice() are now in scalar context, Can't do goto into a block that is optimized away, Can't use whitespace as variable name or quote delimiter, while/if BLOCK BLOCK gone, ** binds tighter than unary minus, foreach changed when iterating over a list, split with no args behavior changed, -e behavior fixed, push returns number of elements in resulting list, Some error messages differ, split() honors subroutine args, Bugs removed

Parsing Traps

Space between . and = triggers syntax error, Better parsing in perl 5, Function parsing, String interpolation of $#array differs, Perl guesses on map, grep followed by { if it starts BLOCK or hash ref

Numerical Traps

Formatted output and significant digits, Auto-increment operator over signed int limit deleted, Assignment of return values from numeric equality tests doesn't work, Bitwise string ops

General data type traps

Negative array subscripts now count from the end of array, Setting $#array lower now discards array elements, Hashes get defined before use, Glob assignment from localized variable to variable, Assigning undef to glob, Changes in unary negation (of strings), Modifying of constants prohibited, defined $var behavior changed, Variable Suicide

Context Traps - scalar, list contexts

Elements of argument lists for formats evaluated in list context, caller() returns false value in scalar context if no caller present, Comma operator in scalar context gives scalar context to args, sprintf() prototyped as ($;@)

Precedence Traps

LHS vs. RHS of any assignment operator, Semantic errors introduced due to precedence, Precedence of assignment operators same as the precedence of assignment, open requires parentheses around filehandle, $: precedence over $:: gone, Precedence of file test operators documented, keys, each, values are regular named unary operators

General Regular Expression Traps using s///, etc.

s'$lhs'$rhs' interpolates on either side, m//g attaches its state to the searched string, m//o used within an anonymous sub, $+ isn't set to whole match, Substitution now returns null string if it fails, s`lhs`rhs` is now a normal substitution, Stricter parsing of variables in regular expressions, m?x? matches only once, Failed matches don't reset the match variables

Subroutine, Signal, Sorting Traps

Barewords that used to look like strings look like subroutine calls, Reverse is no longer allowed as the name of a sort subroutine, warn() won't let you specify a filehandle

OS Traps

SysV resets signal handler correctly, SysV seek() appends correctly

Interpolation Traps

@ always interpolates an array in double-quotish strings, Double-quoted strings may no longer end with an unescaped $, Arbitrary expressions are evaluated inside braces within double quotes, $$x now tries to dereference $x, Creation of hashes on the fly with eval "EXPR" requires protection, Bugs in earlier perl versions, Array and hash brackets during interpolation, Interpolation of \$$foo{bar}, qq() string passed to eval will not find string terminator

DBM Traps

Perl5 must have been linked with same dbm/ndbm as the default for dbmopen(), DBM exceeding limit on the key/value size will cause perl5 to exit immediately

Unclassified Traps

require/do trap using returned value, split on empty string with LIMIT specified

perldebtut - Perl debugging tutorial

DESCRIPTION
use strict
Looking at data and -w and v
help
Stepping through code
Placeholder for a, w, t, T
REGULAR EXPRESSIONS
OUTPUT TIPS
CGI
GUIs
SUMMARY
SEE ALSO
AUTHOR
CONTRIBUTORS

perlfaq - frequently asked questions about Perl ($Date: 2005/12/30 15:04:07 $)

DESCRIPTION
Where to get the perlfaq
How to contribute to the perlfaq
What will happen if you mail your Perl programming problems to the authors
Credits
Author and Copyright Information
Bundled Distributions
Disclaimer
Table of Contents

perlfaq - this document, perlfaq1 - General Questions About Perl, perlfaq2 - Obtaining and Learning about Perl, perlfaq3 - Programming Tools, perlfaq4 - Data Manipulation, perlfaq5 - Files and Formats, perlfaq6 - Regular Expressions, perlfaq7 - General Perl Language Issues, perlfaq8 - System Interaction, perlfaq9 - Networking

The Questions
the perlfaq1 manpage: General Questions About Perl
the perlfaq2 manpage: Obtaining and Learning about Perl
the perlfaq3 manpage: Programming Tools
the perlfaq4 manpage: Data Manipulation
the perlfaq5 manpage: Files and Formats
the perlfaq6 manpage: Regular Expressions
the perlfaq7 manpage: General Perl Language Issues
the perlfaq8 manpage: System Interaction
the perlfaq9 manpage: Networking

perlfaq1 - General Questions About Perl ($Revision: 1.19 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
What is Perl?
Who supports Perl? Who develops it? Why is it free?
Which version of Perl should I use?
What are perl4, perl5, or perl6?
What is Ponie?
What is perl6?
How stable is Perl?
Is Perl difficult to learn?
How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
Can I do [task] in Perl?
When shouldn't I program in Perl?
What's the difference between "perl" and "Perl"?
Is it a Perl program or a Perl script?
What is a JAPH?
Where can I get a list of Larry Wall witticisms?
How can I convince my sysadmin/supervisor/employees to use version 5/5.6.1/Perl instead of some other language?
AUTHOR AND COPYRIGHT

perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
What machines support perl? Where do I get it?
How can I get a binary version of perl?
I don't have a C compiler. How can I build my own Perl interpreter?
I copied the perl binary from one machine to another, but scripts don't work.
I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work?
What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean?
Is there an ISO or ANSI certified version of Perl?
Where can I get information on Perl?
What are the Perl newsgroups on Usenet? Where do I post questions?
Where should I post source code?
Perl Books

References, Tutorials, Task-Oriented, Special Topics

Perl in Magazines
Perl on the Net: FTP and WWW Access
What mailing lists are there for Perl?
Archives of comp.lang.perl.misc
Where can I buy a commercial version of perl?
Where do I send bug reports?
What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
AUTHOR AND COPYRIGHT

perlfaq3 - Programming Tools ($Revision: 1.56 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
How do I do (anything)?
How can I use Perl interactively?
Is there a Perl shell?
How do I find which modules are installed on my system?
How do I debug my Perl programs?
How do I profile my Perl programs?
How do I cross-reference my Perl programs?
Is there a pretty-printer (formatter) for Perl?
Is there a ctags for Perl?
Is there an IDE or Windows Perl Editor?

Eclipse, Enginsite, Komodo, Open Perl IDE, OptiPerl, PerlBuilder, visiPerl+, Visual Perl, Zeus, GNU Emacs, MicroEMACS, XEmacs, Jed, Elvis, Vile, Vim, Codewright, MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, Affrus, Alpha, BBEdit and BBEdit Lite

Where can I get Perl macros for vi?
Where can I get perl-mode for emacs?
How can I use curses with Perl?
How can I use X or Tk with Perl?
How can I make my Perl program run faster?
How can I make my Perl program take less memory?

Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and stringification, Pass by reference, Tie large variables to disk

Is it safe to return a reference to local or lexical data?
How can I free an array or hash so my program shrinks?
How can I make my CGI script more efficient?
How can I hide the source for my Perl program?
How can I compile my Perl program into byte code or C?
How can I compile Perl into Java?
How can I get #!perl to work on [MS-DOS,NT,...]?
Can I write useful Perl programs on the command line?
Why don't Perl one-liners work on my DOS/Mac/VMS system?
Where can I learn about CGI or Web programming in Perl?
Where can I learn about object-oriented Perl programming?
Where can I learn about linking C with Perl?
I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
When I tried to run my script, I got this message. What does it mean?
What's MakeMaker?
AUTHOR AND COPYRIGHT

perlfaq4 - Data Manipulation ($Revision: 1.73 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
Data: Numbers
Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?
Why is int() broken?
Why isn't my octal data interpreted correctly?
Does Perl have a round() function? What about ceil() and floor()? Trig functions?
How do I convert between numeric representations/bases/radixes?

How do I convert hexadecimal into decimal, How do I convert from decimal to hexadecimal, How do I convert from octal to decimal, How do I convert from decimal to octal, How do I convert from binary to decimal, How do I convert from decimal to binary

Why doesn't & work the way I want it to?
How do I multiply matrices?
How do I perform an operation on a series of integers?
How can I output Roman numerals?
Why aren't my random numbers random?
How do I get a random number between X and Y?
Data: Dates
How do I find the day or week of the year?
How do I find the current century or millennium?
How can I compare two dates and find the difference?
How can I take a string and turn it into epoch seconds?
How can I find the Julian Day?
How do I find yesterday's date?
Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
Data: Strings
How do I validate input?
How do I unescape a string?
How do I remove consecutive pairs of characters?
How do I expand function calls in a string?
How do I find matching/nesting anything?
How do I reverse a string?
How do I expand tabs in a string?
How do I reformat a paragraph?
How can I access or change N characters of a string?
How do I change the Nth occurrence of something?
How can I count the number of occurrences of a substring within a string?
How do I capitalize all the words on one line?
How can I split a [character] delimited string except when inside [character]?
How do I strip blank space from the beginning/end of a string?
How do I pad a string with blanks or pad a number with zeroes?
How do I extract selected columns from a string?
How do I find the soundex value of a string?
How can I expand variables in text strings?
What's wrong with always quoting "$vars"?
Why don't my <<HERE documents work?

There must be no space after the << part, There (probably) should be a semicolon at the end, You can't (easily) have any space in front of the tag

Data: Arrays
What is the difference between a list and an array?
What is the difference between $array[1] and @array[1]?
How can I remove duplicate elements from a list or array?
How can I tell whether a certain element is contained in a list or array?
How do I compute the difference of two arrays? How do I compute the intersection of two arrays?
How do I test whether two arrays or hashes are equal?
How do I find the first array element for which a condition is true?
How do I handle linked lists?
How do I handle circular lists?
How do I shuffle an array randomly?
How do I process/modify each element of an array?
How do I select a random element from an array?
How do I permute N elements of a list?
How do I sort an array by (anything)?
How do I manipulate arrays of bits?
Why does defined() return true on empty arrays and hashes?
Data: Hashes (Associative Arrays)
How do I process an entire hash?
What happens if I add or remove keys from a hash while iterating over it?
How do I look up a hash element by value?
How can I know how many entries are in a hash?
How do I sort a hash (optionally by value instead of key)?
How can I always keep my hash sorted?
What's the difference between "delete" and "undef" with hashes?
Why don't my tied hashes make the defined/exists distinction?
How do I reset an each() operation part-way through?
How can I get the unique keys from two hashes?
How can I store a multidimensional array in a DBM file?
How can I make my hash remember the order I put elements into it?
Why does passing a subroutine an undefined element in a hash create it?
How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays?
How can I use a reference as a hash key?
Data: Misc
How do I handle binary data correctly?
How do I determine whether a scalar is a number/whole/integer/float?
How do I keep persistent data across program calls?
How do I print out or copy a recursive data structure?
How do I define methods for every class/object?
How do I verify a credit card checksum?
How do I pack arrays of doubles or floats for XS code?
AUTHOR AND COPYRIGHT

perlfaq5 - Files and Formats ($Revision: 1.42 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
How do I flush/unbuffer an output filehandle? Why must I do this?
How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
How do I count the number of lines in a file?
How can I use Perl's -i option from within a program?
How can I copy a file?
How do I make a temporary file name?
How can I manipulate fixed-record-length files?
How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles?
How can I use a filehandle indirectly?
How can I set up a footer format to be used with write()?
How can I write() into a string?
How can I output my numbers with commas added?
How can I translate tildes (~) in a filename?
How come when I open a file read-write it wipes it out?
Why do I sometimes get an "Argument list too long" when I use <*>?
Is there a leak/bug in glob()?
How can I open a file with a leading ">" or trailing blanks?
How can I reliably rename a file?
How can I lock a file?
Why can't I just open(FH, ">file.lock")?
I still don't get locking. I just want to increment the number in the file. How can I do this?
All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
How do I randomly update a binary file?
How do I get a file's timestamp in perl?
How do I set a file's timestamp in perl?
How do I print to more than one file at once?
How can I read in an entire file all at once?
How can I read in a file by paragraphs?
How can I read a single character from a file? From the keyboard?
How can I tell whether there's a character waiting on a filehandle?
How do I do a tail -f in perl?
How do I dup() a filehandle in Perl?
How do I close a file descriptor by number?
Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
Why doesn't glob("*.*") get all the files?
Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?
How do I select a random line from a file?
Why do I get weird spaces when I print an array of lines?
AUTHOR AND COPYRIGHT

perlfaq6 - Regular Expressions ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
How can I hope to use regular expressions without creating illegible and unmaintainable code?

Comments Outside the Regex, Comments Inside the Regex, Different Delimiters

I'm having trouble matching over more than one line. What's wrong?
How can I pull out lines between two patterns that are themselves on different lines?
I put a regular expression into $/ but it didn't work. What's wrong?
How do I substitute case insensitively on the LHS while preserving case on the RHS?
How can I make \w match national character sets?
How can I match a locale-smart version of /[a-zA-Z]/?
How can I quote a variable to use in a regex?
What is /o really for?
How do I use a regular expression to strip C style comments from a file?
Can I use Perl regular expressions to match balanced text?
What does it mean that regexes are greedy? How can I get around it?
How do I process each word on each line?
How can I print out a word-frequency or line-frequency summary?
How can I do approximate matching?
How do I efficiently match many regular expressions at once?
Why don't word-boundary searches with \b work for me?
Why does using $&, $`, or $' slow my program down?
What good is \G in a regular expression?
Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
What's wrong with using grep in a void context?
How can I match strings with multibyte characters?
How do I match a pattern that is supplied by the user?
AUTHOR AND COPYRIGHT

perlfaq7 - General Perl Language Issues ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
Can I get a BNF/yacc/RE for the Perl language?
What are all these $@%&* punctuation signs, and how do I know when to use them?
Do I always/never have to quote my strings or use semicolons and commas?
How do I skip some return values?
How do I temporarily block warnings?
What's an extension?
Why do Perl operators have different precedence than C operators?
How do I declare/create a structure?
How do I create a module?
How do I create a class?
How can I tell if a variable is tainted?
What's a closure?
What is variable suicide and how can I prevent it?
How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}?

Passing Variables and Functions, Passing Filehandles, Passing Regexes, Passing Methods

How do I create a static variable?
What's the difference between dynamic and lexical (static) scoping? Between local() and my()?
How can I access a dynamic variable while a similarly named lexical is in scope?
What's the difference between deep and shallow binding?
Why doesn't "my($foo) = <FILE>;" work right?
How do I redefine a builtin function, operator, or method?
What's the difference between calling a function as &foo and foo()?
How do I create a switch or case statement?
How can I catch accesses to undefined variables, functions, or methods?
Why can't a method included in this same file be found?
How can I find out my current package?
How can I comment out a large block of perl code?
How do I clear a package?
How can I use a variable as a variable name?
What does "bad interpreter" mean?
AUTHOR AND COPYRIGHT

perlfaq8 - System Interaction ($Revision: 1.27 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
How do I find out which operating system I'm running under?
How come exec() doesn't return?
How do I do fancy stuff with the keyboard/screen/mouse?

Keyboard, Screen, Mouse

How do I print something out in color?
How do I read just one key without waiting for a return key?
How do I check whether input is ready on the keyboard?
How do I clear the screen?
How do I get the screen size?
How do I ask the user for a password?
How do I read and write the serial port?

lockfiles, open mode, end of line, flushing output, non-blocking input

How do I decode encrypted password files?
How do I start a process in the background?

STDIN, STDOUT, and STDERR are shared, Signals, Zombies

How do I trap control characters/signals?
How do I modify the shadow password file on a Unix system?
How do I set the time and date?
How can I sleep() or alarm() for under a second?
How can I measure time under a second?
How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean?
How can I call my system's unique C functions from Perl?
Where do I get the include files to do ioctl() or syscall()?
Why do setuid perl scripts complain about kernel problems?
How can I open a pipe both to and from a command?
Why can't I get the output of a command with system()?
How can I capture STDERR from an external command?
Why doesn't open() return an error when a pipe open fails?
What's wrong with using backticks in a void context?
How can I call backticks without shell processing?
Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?
How can I convert my shell script to perl?
Can I use perl to run a telnet or ftp session?
How can I write expect in Perl?
Is there a way to hide perl's command line from programs such as "ps"?
I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible?

Unix

How do I close a process's filehandle without waiting for it to complete?
How do I fork a daemon process?
How do I find out if I'm running interactively or not?
How do I timeout a slow event?
How do I set CPU limits?
How do I avoid zombies on a Unix system?
How do I use an SQL database?
How do I make a system() exit on control-C?
How do I open a file without blocking?
How do I tell the difference between errors from the shell and perl?
How do I install a module from CPAN?
What's the difference between require and use?
How do I keep my own module/library directory?
How do I add the directory my program lives in to the module/library search path?
How do I add a directory to my include path (@INC) at runtime?
What is socket.ph and where do I get it?
AUTHOR AND COPYRIGHT

perlfaq9 - Networking ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)

DESCRIPTION
What is the correct form of response from a CGI script?
My CGI script runs from the command line but not the browser. (500 Server Error)
How can I get better error messages from a CGI program?
How do I remove HTML from a string?
How do I extract URLs?
How do I download a file from the user's machine? How do I open a file on another machine?
How do I make a pop-up menu in HTML?
How do I fetch an HTML file?
How do I automate an HTML form submission?
How do I decode or create those %-encodings on the web?
How do I redirect to another page?
How do I put a password on my web pages?
How do I edit my .htpasswd and .htgroup files with Perl?
How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
How do I parse a mail header?
How do I decode a CGI form?
How do I check a valid mail address?
How do I decode a MIME/BASE64 string?
How do I return the user's mail address?
How do I send mail?
How do I use MIME to make an attachment to a mail message?
How do I read mail?
How do I find out my hostname, domainname, or IP address?
How do I fetch a news article or the active newsgroups?
How do I fetch/put an FTP file?
How can I do RPC in Perl?
AUTHOR AND COPYRIGHT

perlsyn - Perl syntax

DESCRIPTION
Declarations
Comments
Simple Statements
Truth and Falsehood
Statement Modifiers
Compound Statements
Loop Control
For Loops
Foreach Loops
Basic BLOCKs and Switch Statements
Goto
PODs: Embedded Documentation
Plain Old Comments (Not!)

perldata - Perl data types

DESCRIPTION
Variable names
Context
Scalar values
Scalar value constructors
List value constructors
Subscripts
Slices
Typeglobs and Filehandles
SEE ALSO

perlop - Perl operators and precedence

DESCRIPTION
Operator Precedence and Associativity
Terms and List Operators (Leftward)
The Arrow Operator >>
Auto-increment and Auto-decrement
Exponentiation
Symbolic Unary Operators
Binding Operators
Multiplicative Operators
Additive Operators
Shift Operators >> > >>>
Named Unary Operators
Relational Operators
Equality Operators
Bitwise And
Bitwise Or and Exclusive Or
C-style Logical And
C-style Logical Or
Range Operators
Conditional Operator
Assignment Operators >> >= >>>
Comma Operator
List Operators (Rightward)
Logical Not
Logical And
Logical or and Exclusive Or
C Operators Missing From Perl

unary &, unary *, (TYPE)

Quote and Quote-like Operators >>
Regexp Quote-Like Operators

?PATTERN? , m/PATTERN/cgimosx , /PATTERN/cgimosx, q/STRING/ , 'STRING', qq/STRING/ , "STRING", qr/STRING/imosx , qx/STRING/ , `STRING`, qw/STRING/ , s/PATTERN/REPLACEMENT/egimosx , tr/SEARCHLIST/REPLACEMENTLIST/cds , y/SEARCHLIST/REPLACEMENTLIST/cds, <<EOF >>

Gory details of parsing quoted constructs

Finding the end, Removal of backslashes before delimiters, Interpolation , <<'EOF', m'', s''', tr///, y///, '', q//, "", ``, qq//, qx//, <file*glob>, ?RE?, /RE/, m/RE/, s/RE/foo/,, Interpolation of regular expressions , Optimization of regular expressions

I/O Operators >>
Constant Folding
No-ops
Bitwise String Operators
Integer Arithmetic
Floating-point Arithmetic
Bigger Numbers

perlsub - Perl subroutines

SYNOPSIS
DESCRIPTION
Private Variables via my()
Persistent Private Variables
Temporary Values via local()
Lvalue subroutines

Lvalue subroutines are EXPERIMENTAL

Passing Symbol Table Entries (typeglobs)
When to Still Use local()
Pass by Reference
Prototypes
Constant Functions
Overriding Built-in Functions
Autoloading
Subroutine Attributes
SEE ALSO

perlfunc - Perl builtin functions

DESCRIPTION
Perl Functions by Category

Functions for SCALARs or strings , Regular expressions and pattern matching , Numeric functions , Functions for real @ARRAYs , Functions for list data , Functions for real %HASHes , Input and output functions , Functions for fixed length data or records, Functions for filehandles, files, or directories , Keywords related to the control flow of your Perl program , Keywords related to scoping, Miscellaneous functions, Functions for processes and process groups , Keywords related to perl modules , Keywords related to classes and object-orientedness , Low-level socket functions , System V interprocess communication functions , Fetching user and group info , Fetching network info , Time-related functions , Functions new in perl5 , Functions obsoleted in perl5

Portability
Alphabetical Listing of Perl Functions

-X FILEHANDLE , -X EXPR, -X, abs VALUE , abs, accept NEWSOCKET,GENERICSOCKET , alarm SECONDS , alarm, atan2 Y,X , bind SOCKET,NAME , binmode FILEHANDLE, LAYER , binmode FILEHANDLE, bless REF,CLASSNAME , bless REF, caller EXPR , caller, chdir EXPR , chdir FILEHANDLE, chdir DIRHANDLE, chdir, chmod LIST , chomp VARIABLE , chomp( LIST ), chomp, chop VARIABLE , chop( LIST ), chop, chown LIST , chr NUMBER , chr, chroot FILENAME , chroot, close FILEHANDLE , close, closedir DIRHANDLE , connect SOCKET,NAME , continue BLOCK , cos EXPR , cos, crypt PLAINTEXT,SALT , dbmclose HASH , dbmopen HASH,DBNAME,MASK , defined EXPR , defined, delete EXPR , die LIST , do BLOCK , do SUBROUTINE(LIST) , do EXPR , dump LABEL , dump, each HASH , eof FILEHANDLE , eof (), eof, eval EXPR , eval BLOCK, eval, exec LIST , exec PROGRAM LIST, exists EXPR , exit EXPR , exit, exp EXPR , exp, fcntl FILEHANDLE,FUNCTION,SCALAR , fileno FILEHANDLE , flock FILEHANDLE,OPERATION , fork , format , formline PICTURE,LIST , getc FILEHANDLE , getc, getlogin , getpeername SOCKET , getpgrp PID , getppid , getpriority WHICH,WHO , getpwnam NAME , getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname NAME, getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent, getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent, endprotoent, endservent, getsockname SOCKET , getsockopt SOCKET,LEVEL,OPTNAME , glob EXPR , glob, gmtime EXPR , gmtime, goto LABEL , goto EXPR, goto &NAME, grep BLOCK LIST , grep EXPR,LIST, hex EXPR , hex, import LIST , index STR,SUBSTR,POSITION , index STR,SUBSTR, int EXPR , int, ioctl FILEHANDLE,FUNCTION,SCALAR , join EXPR,LIST , keys HASH , kill SIGNAL, LIST , last LABEL , last, lc EXPR , lc, lcfirst EXPR , lcfirst, length EXPR , length, link OLDFILE,NEWFILE , listen SOCKET,QUEUESIZE , local EXPR , localtime EXPR , localtime, lock THING , log EXPR , log, lstat EXPR , lstat, m//, map BLOCK LIST , map EXPR,LIST, mkdir FILENAME,MASK , mkdir FILENAME, msgctl ID,CMD,ARG , msgget KEY,FLAGS , msgrcv ID,VAR,SIZE,TYPE,FLAGS , msgsnd ID,MSG,FLAGS , my EXPR , my TYPE EXPR, my EXPR : ATTRS, my TYPE EXPR : ATTRS, next LABEL , next, no Module VERSION LIST , no Module VERSION, no Module LIST, no Module, oct EXPR , oct, open FILEHANDLE,EXPR , open FILEHANDLE,MODE,EXPR, open FILEHANDLE,MODE,EXPR,LIST, open FILEHANDLE,MODE,REFERENCE, open FILEHANDLE, opendir DIRHANDLE,EXPR , ord EXPR , ord, our EXPR , our EXPR TYPE, our EXPR : ATTRS, our TYPE EXPR : ATTRS, pack TEMPLATE,LIST , package NAMESPACE , package, pipe READHANDLE,WRITEHANDLE , pop ARRAY , pop, pos SCALAR , pos, print FILEHANDLE LIST , print LIST, print, printf FILEHANDLE FORMAT, LIST , printf FORMAT, LIST, prototype FUNCTION , push ARRAY,LIST , , q/STRING/, qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR , quotemeta, rand EXPR , rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET , read FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE , readline EXPR , readlink EXPR , readlink, readpipe EXPR , recv SOCKET,SCALAR,LENGTH,FLAGS , redo LABEL , redo, ref EXPR , ref, rename OLDNAME,NEWNAME , require VERSION , require EXPR, require, reset EXPR , reset, return EXPR , return, reverse LIST , rewinddir DIRHANDLE , rindex STR,SUBSTR,POSITION , rindex STR,SUBSTR, rmdir FILENAME , rmdir, s///, scalar EXPR , seek FILEHANDLE,POSITION,WHENCE , seekdir DIRHANDLE,POS , select FILEHANDLE , select, select RBITS,WBITS,EBITS,TIMEOUT , semctl ID,SEMNUM,CMD,ARG , semget KEY,NSEMS,FLAGS , semop KEY,OPSTRING , send SOCKET,MSG,FLAGS,TO , send SOCKET,MSG,FLAGS, setpgrp PID,PGRP , setpriority WHICH,WHO,PRIORITY , setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL , shift ARRAY , shift, shmctl ID,CMD,ARG , shmget KEY,SIZE,FLAGS , shmread ID,VAR,POS,SIZE , shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW , sin EXPR , sin, sleep EXPR , sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL , socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL , sort SUBNAME LIST , sort BLOCK LIST, sort LIST, splice ARRAY,OFFSET,LENGTH,LIST , splice ARRAY,OFFSET,LENGTH, splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT , split /PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST , format parameter index, flags, vector flag, (minimum) width, precision, or maximum width , size, order of arguments, sqrt EXPR , sqrt, srand EXPR , srand, stat FILEHANDLE , stat EXPR, stat, study SCALAR , study, sub NAME BLOCK , sub NAME (PROTO) BLOCK, sub NAME : ATTRS BLOCK, sub NAME (PROTO) : ATTRS BLOCK, substr EXPR,OFFSET,LENGTH,REPLACEMENT , substr EXPR,OFFSET,LENGTH, substr EXPR,OFFSET, symlink OLDFILE,NEWFILE , syscall NUMBER, LIST , sysopen FILEHANDLE,FILENAME,MODE , sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET , sysread FILEHANDLE,SCALAR,LENGTH, sysseek FILEHANDLE,POSITION,WHENCE , system LIST , system PROGRAM LIST, syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET , syswrite FILEHANDLE,SCALAR,LENGTH, syswrite FILEHANDLE,SCALAR, tell FILEHANDLE , tell, telldir DIRHANDLE , tie VARIABLE,CLASSNAME,LIST , tied VARIABLE , time , times , tr///, truncate FILEHANDLE,LENGTH , truncate EXPR,LENGTH, uc EXPR , uc, ucfirst EXPR , ucfirst, umask EXPR , umask, undef EXPR , undef, unlink LIST , unlink, unpack TEMPLATE,EXPR , untie VARIABLE , unshift ARRAY,LIST , use Module VERSION LIST , use Module VERSION, use Module LIST, use Module, use VERSION, utime LIST , values HASH , vec EXPR,OFFSET,BITS , wait , waitpid PID,FLAGS , wantarray , warn LIST , write FILEHANDLE , write EXPR, write, y///

perlopentut - tutorial on opening things in Perl

DESCRIPTION
Open à la shell
Simple Opens
Indirect Filehandles
Pipe Opens
The Minus File
Mixing Reads and Writes
Filters
Open à la C
Permissions à la mode
Obscure Open Tricks
Re-Opening Files (dups)
Dispelling the Dweomer
Paths as Opens
Single Argument Open
Playing with STDIN and STDOUT
Other I/O Issues
Opening Non-File Files
Opening Named Pipes
Opening Sockets
Binary Files
File Locking
IO Layers
SEE ALSO
AUTHOR and COPYRIGHT
HISTORY

perlpacktut - tutorial on pack and unpack

DESCRIPTION
The Basic Principle
Packing Text
Packing Numbers
Integers
Unpacking a Stack Frame
How to Eat an Egg on a Net
Floating point Numbers
Exotic Templates
Bit Strings
Uuencoding
Doing Sums
Unicode
Another Portable Binary Encoding
Template Grouping
Lengths and Widths
String Lengths
Dynamic Templates
Counting Repetitions
Packing and Unpacking C Structures
The Alignment Pit
Alignment, Take 2
Alignment, Take 3
Pointers for How to Use Them
Pack Recipes
Funnies Section
Authors

perlpod - the Plain Old Documentation format

DESCRIPTION
Ordinary Paragraph
Verbatim Paragraph
Command Paragraph

=head1 Heading Text , =head2 Heading Text, =head3 Heading Text>, =head4 Heading Text, =over indentlevel , =item stuff..., =back, =cut , =pod , =begin formatname , =end formatname, =for formatname text..., =encoding encodingname

Formatting Codes

I<text> -- italic text <> >> , B<text> -- bold text <> >> , C<code> -- code text <> >> , L<name> -- a hyperlink <> >> , E<escape> -- a character escape <> >> , F<filename> -- used for filenames <> >> , S<text> -- text contains non-breaking spaces <> >> , X<topic name> -- an index entry <> >> , Z<> -- a null (zero-effect) formatting code <> >>

The Intent
Embedding Pods in Perl Modules
Hints for Writing Pod

SEE ALSO
AUTHOR

perlpodspec - Plain Old Documentation: format specification and notes

DESCRIPTION
Pod Definitions
Pod Commands

"=head1", "=head2", "=head3", "=head4", "=pod", "=cut", "=over", "=item", "=back", "=begin formatname", "=end formatname", "=for formatname text...", "=encoding encodingname"

Pod Formatting Codes

I<text> -- italic text, B<text> -- bold text, C<code> -- code text, F<filename> -- style for filenames, X<topic name> -- an index entry, Z<> -- a null (zero-effect) formatting code, L<name> -- a hyperlink, E<escape> -- a character escape, S<text> -- text contains non-breaking spaces

Notes on Implementing Pod Processors
About L<...> Codes

First:, Second:, Third:, Fourth:, Fifth:, Sixth:

About =over...=back Regions
About Data Paragraphs and "=begin/=end" Regions
SEE ALSO
AUTHOR

perlrun - how to execute the Perl interpreter

SYNOPSIS
DESCRIPTION
#! and quoting on non-Unix systems

OS/2, MS-DOS, Win95/NT, Macintosh, VMS

Location of Perl
Command Switches

-0[octal/hexadecimal] , -a , -C [number/list] , -c , -d , -dt, -d:foo[=bar,baz] , -dt:foo[=bar,baz], -D letters , -D number, -e commandline , -f , -F pattern , -h , -i[extension] , -I directory , -l[octnum] , -m[-]module , -M[-]module, -M[-]'module ...', -[mM][-]module=arg[,arg]..., -n , -p , -P , -s , -S , -t , -T , -u , -U , -v , -V , -V:configvar, -w , -W , -X , -x , -x directory

ENVIRONMENT

HOME , LOGDIR , PATH , PERL5LIB , PERL5OPT , PERLIO , :bytes , :crlf , :mmap , :perlio , :pop , :raw , :stdio , :unix , :utf8 , :win32 , PERLIO_DEBUG , PERLLIB , PERL5DB , PERL5DB_THREADED , PERL5SHELL (specific to the Win32 port) , PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) , PERL_DEBUG_MSTATS , PERL_DESTRUCT_LEVEL , PERL_DL_NONLAZY , PERL_ENCODING , PERL_HASH_SEED , PERL_HASH_SEED_DEBUG , PERL_ROOT (specific to the VMS port) , PERL_SIGNALS , PERL_UNICODE , SYS$LOGIN (specific to the VMS port)

perldiag - various Perl diagnostics

DESCRIPTION

perllexwarn - Perl Lexical Warnings

DESCRIPTION
Default Warnings and Optional Warnings
What's wrong with -w and $^W
Controlling Warnings from the Command Line

-w , -W , -X

Backward Compatibility
Category Hierarchy
Fatal Warnings
Reporting Warnings from a Module
TODO
SEE ALSO
AUTHOR

perldebug - Perl debugging

DESCRIPTION
The Perl Debugger
Debugger Commands

h , h [command], h h, p expr , x [maxdepth] expr , V [pkg [vars]] , X [vars] , y [level [vars]] , T , s [expr] , n [expr] , r , <CR>, c [line|sub] , l , l min+incr, l min-max, l line, l subname, - , v [line] , . , f filename , /pattern/, ?pattern?, L [abw] , S [[!]regex] , t , t expr , b , b [line] [condition] , b subname [condition] , b postpone subname [condition] , b load filename , b compile subname , B line , B * , a [line] command , A line , A * , w expr , W expr , W * , o , o booloption ... , o anyoption? ... , o option=value ... , < ? >, < [ command ] >, < * >, << command >, > ? >>, > command >>, > * >>, >> command > >>>, { ? , { [ command ], { * , {{ command , ! number , ! -number , ! pattern , !! cmd , source file , H -number , q or ^D , R , |dbcmd , ||dbcmd , command, m expr , M , man [manpage]

Configurable Options

recallCommand, ShellBang , pager , tkRunning , signalLevel, warnLevel, dieLevel , AutoTrace , LineInfo , inhibit_exit , PrintRet , ornaments , frame , maxTraceLen , windowSize , arrayDepth, hashDepth , dumpDepth , compactDump, veryCompact , globPrint , DumpDBFiles , DumpPackages , DumpReused , quote, HighBit, undefPrint , UsageOnly , TTY , noTTY , ReadLine , NonStop

Debugger input/output

Prompt, Multiline commands, Stack backtrace , Line Listing Format, Frame listing

Debugging compile-time statements
Debugger Customization
Readline Support
Editor Support for Debugging
The Perl Profiler
Debugging regular expressions
Debugging memory usage
SEE ALSO
BUGS

perlvar - Perl predefined variables

DESCRIPTION
Predefined Names

$ARG, $_, $a, $b, $<digits>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $', $LAST_PAREN_MATCH, $+, $^N, @LAST_MATCH_END, @+, $*, HANDLE->input_line_number(EXPR), $INPUT_LINE_NUMBER, $NR, $, IO::Handle->input_record_separator(EXPR), $INPUT_RECORD_SEPARATOR, $RS, $/, HANDLE->autoflush(EXPR), $OUTPUT_AUTOFLUSH, $|, IO::Handle->output_field_separator EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $,, IO::Handle->output_record_separator EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $", $SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $#, HANDLE->format_page_number(EXPR), $FORMAT_PAGE_NUMBER, $%, HANDLE->format_lines_per_page(EXPR), $FORMAT_LINES_PER_PAGE, $=, HANDLE->format_lines_left(EXPR), $FORMAT_LINES_LEFT, $-, @LAST_MATCH_START, @-, $` is the same as substr($var, 0, $-[0]), $& is the same as substr($var, $-[0], $+[0] - $-[0]), $' is the same as substr($var, $+[0]), $1 is the same as substr($var, $-[1], $+[1] - $-[1]), $2 is the same as substr($var, $-[2], $+[2] - $-[2]), $3 is the same as substr($var, $-[3], $+[3] - $-[3]), HANDLE->format_name(EXPR), $FORMAT_NAME, $~, HANDLE->format_top_name(EXPR), $FORMAT_TOP_NAME, $^, IO::Handle->format_line_break_characters EXPR, $FORMAT_LINE_BREAK_CHARACTERS, $:, IO::Handle->format_formfeed EXPR, $FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A, $CHILD_ERROR, $?, ${^ENCODING}, $OS_ERROR, $ERRNO, $!, %!, $EXTENDED_OS_ERROR, $^E, $EVAL_ERROR, $@, $PROCESS_ID, $PID, $$, $REAL_USER_ID, $UID, $<, $EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(, $EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $], $COMPILING, $^C, $DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H, $INPLACE_EDIT, $^I, $^M, $OSNAME, $^O, ${^OPEN}, $PERLDB, $^P, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, 0x400, $LAST_REGEXP_CODE_RESULT, $^R, $EXCEPTIONS_BEING_CAUGHT, $^S, $BASETIME, $^T, ${^TAINT}, ${^UNICODE}, ${^UTF8LOCALE}, $PERL_VERSION, $^V, $WARNING, $^W, ${^WARNING_BITS}, $EXECUTABLE_NAME, $^X, ARGV, $ARGV, @ARGV, ARGVOUT, @F, @INC, @_, %INC, %ENV, $ENV{expr}, %SIG, $SIG{expr}

Error Indicators
Technical Note on the Syntax of Variable Names
BUGS

perlre - Perl regular expressions

DESCRIPTION

i , m , s , x

Regular Expressions

[1], [2], [3], cntrl , graph , print , punct , xdigit

Extended Patterns

(?#text) , (?imsx-imsx) , (?:pattern) , (?imsx-imsx:pattern), (?=pattern) , (?!pattern) , (?<=pattern) , (?<!pattern) , (?{ code }) , (??{ code }) , (?>pattern) , (?(condition)yes-pattern|no-pattern) , (?(condition)yes-pattern)

Backtracking
Version 8 Regular Expressions
Warning on \1 vs $1
Repeated patterns matching zero-length substring
Combining pieces together

ST, S|T, S{REPEAT_COUNT}, S{min,max}, S{min,max}?, S?, S*, S+, S??, S*?, S+?, (?>S), (?=S), (?<=S), (?!S), (?<!S), (??{ EXPR }), (?(condition)yes-pattern|no-pattern)

Creating custom RE engines
BUGS
SEE ALSO

perlreref - Perl Regular Expressions Reference

DESCRIPTION
OPERATORS
SYNTAX
ESCAPE SEQUENCES
CHARACTER CLASSES
ANCHORS
QUANTIFIERS
EXTENDED CONSTRUCTS
VARIABLES
FUNCTIONS
TERMINOLOGY
AUTHOR
SEE ALSO
THANKS

perlref - Perl references and nested data structures

NOTE
DESCRIPTION
Making References

1. , 2. , 3. , 4. , 5. , 6. , 7.

Using References

2. , 3. >> , 4.

Symbolic references
Not-so-symbolic references
Pseudo-hashes: Using an array as a hash
Function Templates
WARNING
SEE ALSO

perlform - Perl formats

DESCRIPTION
Text Fields
Numeric Fields
The Field @* for Variable Width Multi-Line Text
The Field ^* for Variable Width One-line-at-a-time Text
Specifying Values
Using Fill Mode
Suppressing Lines Where All Fields Are Void
Repeating Format Lines
Top of Form Processing
Format Variables
NOTES
Footers
Accessing Formatting Internals
WARNINGS

perlobj - Perl objects

DESCRIPTION
An Object is Simply a Reference
A Class is Simply a Package
A Method is Simply a Subroutine
Method Invocation >>
Indirect Object Syntax
Default UNIVERSAL methods

isa(CLASS) , can(METHOD) , VERSION( [NEED] )

Destructors
Summary
Two-Phased Garbage Collection
SEE ALSO

perltie - how to hide an object class in a simple variable

SYNOPSIS
DESCRIPTION
Tying Scalars

TIESCALAR classname, LIST , FETCH this , STORE this, value , UNTIE this , DESTROY this

Tying Arrays

TIEARRAY classname, LIST , FETCH this, index , STORE this, index, value , FETCHSIZE this , STORESIZE this, count , EXTEND this, count , EXISTS this, key , DELETE this, key , CLEAR this , PUSH this, LIST , POP this , SHIFT this , UNSHIFT this, LIST , SPLICE this, offset, length, LIST , UNTIE this , DESTROY this

Tying Hashes

USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST , FETCH this, key , STORE this, key, value , DELETE this, key , CLEAR this , EXISTS this, key , FIRSTKEY this , NEXTKEY this, lastkey , SCALAR this , UNTIE this , DESTROY this

Tying FileHandles

TIEHANDLE classname, LIST , WRITE this, LIST , PRINT this, LIST , PRINTF this, LIST , READ this, LIST , READLINE this , GETC this , CLOSE this , UNTIE this , DESTROY this

UNTIE this
The untie Gotcha
SEE ALSO
BUGS
AUTHOR

perldbmfilter - Perl DBM Filters

SYNOPSIS
DESCRIPTION

filter_store_key, filter_store_value, filter_fetch_key, filter_fetch_value

The Filter
An Example -- the NULL termination problem.
Another Example -- Key is a C int.
SEE ALSO
AUTHOR

perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)

DESCRIPTION
Signals
Handling the SIGHUP Signal in Daemons
Named Pipes
Deferred Signals (Safe Signals)

Long running opcodes, Interrupting IO, Restartable system calls, Signals as "faults", Signals triggered by operating system state

Using open() for IPC
Filehandles
Background Processes
Complete Dissociation of Child from Parent
Safe Pipe Opens
Bidirectional Communication with Another Process
Bidirectional Communication with Yourself
Sockets: Client/Server Communication
Internet Line Terminators
Internet TCP Clients and Servers
Unix-Domain TCP Clients and Servers
TCP Clients with IO::Socket
A Simple Client

Proto, PeerAddr, PeerPort

A Webget Client
Interactive Client with IO::Socket
TCP Servers with IO::Socket

Proto, LocalPort, Listen, Reuse

UDP: Message Passing
SysV IPC
NOTES
BUGS
AUTHOR
SEE ALSO

perlfork - Perl's fork() emulation

SYNOPSIS
DESCRIPTION
Behavior of other Perl features in forked pseudo-processes

$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to files, directories and network sockets

Resource limits
Killing the parent process
Lifetime of the parent process and pseudo-processes
CAVEATS AND LIMITATIONS

BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented, Global state maintained by XSUBs, Interpreter embedded in larger application, Thread-safety of extensions

BUGS
AUTHOR
SEE ALSO

perlnumber - semantics of numbers and numeric operations in Perl

SYNOPSIS
DESCRIPTION
Storing numbers
Numeric operators and numeric conversions
Flavors of Perl numeric operations

Arithmetic operators, ++, Arithmetic operators during use integer, Other mathematical operators, Bitwise operators, Bitwise operators during use integer, Operators which expect an integer, Operators which expect a string

AUTHOR
SEE ALSO

perlthrtut - tutorial on threads in Perl

DESCRIPTION
Status
What Is A Thread Anyway?
Threaded Program Models
Boss/Worker
Work Crew
Pipeline
What kind of threads are Perl threads?
Thread-Safe Modules
Thread Basics
Basic Thread Support
A Note about the Examples
Creating Threads
Waiting For A Thread To Exit
Ignoring A Thread
Threads And Data
Shared And Unshared Data
Thread Pitfalls: Races
Synchronization and control
Controlling access: lock()
A Thread Pitfall: Deadlocks
Queues: Passing Data Around
Semaphores: Synchronizing Data Access
Basic semaphores
Advanced Semaphores
cond_wait() and cond_signal()
Giving up control
General Thread Utility Routines
What Thread Am I In?
Thread IDs
Are These Threads The Same?
What Threads Are Running?
A Complete Example
Different implementations of threads
Performance considerations
Process-scope Changes
Thread-Safety of System Libraries
Conclusion
Bibliography
Introductory Texts
OS-Related References
Other References
Acknowledgements
AUTHOR
Copyrights

perlothrtut - old tutorial on threads in Perl

DESCRIPTION
What Is A Thread Anyway?
Threaded Program Models
Boss/Worker
Work Crew
Pipeline
Native threads
What kind of threads are perl threads?
Threadsafe Modules
Thread Basics
Basic Thread Support
Creating Threads
Giving up control
Waiting For A Thread To Exit
Errors In Threads
Ignoring A Thread
Threads And Data
Shared And Unshared Data
Thread Pitfall: Races
Controlling access: lock()
Thread Pitfall: Deadlocks
Queues: Passing Data Around
Threads And Code
Semaphores: Synchronizing Data Access

Basic semaphores, Advanced Semaphores

Attributes: Restricting Access To Subroutines
Subroutine Locks
Methods
Locking A Subroutine
General Thread Utility Routines
What Thread Am I In?
Thread IDs
Are These Threads The Same?
What Threads Are Running?
A Complete Example
Conclusion
Bibliography
Introductory Texts
OS-Related References
Other References
Acknowledgements
AUTHOR
Copyrights

perlport - Writing portable Perl

DESCRIPTION

Not all Perl programs have to be portable, Nearly all of Perl already is portable

ISSUES
Newlines
Numbers endianness and Width
Files and Filesystems
System Interaction
Command names versus file pathnames
Networking
Interprocess Communication (IPC)
External Subroutines (XS)
Standard Modules
Time and Date
Character sets and character encoding
Internationalisation
System Resources
Security
Style
CPAN Testers
PLATFORMS
Unix
DOS and Derivatives
Mac OS
VMS
VOS
EBCDIC Platforms
Acorn RISC OS
Other perls
FUNCTION IMPLEMENTATIONS
Alphabetical Listing of Perl Functions

-X, atan2 Y,X, atan2, binmode, chmod, chown, chroot, crypt, dbmclose, dbmopen, dump, exec, exit, fcntl, flock, fork, getlogin, getpgrp, getppid, getpriority, getpwnam, getgrnam, getnetbyname, getpwuid, getgrgid, getnetbyaddr, getprotobynumber, getservbyport, getpwent, getgrent, gethostbyname, gethostent, getnetent, getprotoent, getservent, sethostent, setnetent, setprotoent, setservent, endpwent, endgrent, endhostent, endnetent, endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob, gmtime, ioctl FILEHANDLE,FUNCTION,SCALAR, kill, link, localtime, lstat, msgctl, msgget, msgsnd, msgrcv, open, pipe, readlink, rename, select, semctl, semget, semop, setgrent, setpgrp, setpriority, setpwent, setsockopt, shmctl, shmget, shmread, shmwrite, sockatmark, socketpair, stat, symlink, syscall, sysopen, system, times, truncate, umask, utime, wait, waitpid

Supported Platforms
SEE ALSO
AUTHORS / CONTRIBUTORS

perllocale - Perl locale handling (internationalization and localization)

DESCRIPTION
PREPARING TO USE LOCALES
USING LOCALES
The use locale pragma
The setlocale function
Finding locales
LOCALE PROBLEMS
Temporarily fixing locale problems
Permanently fixing locale problems
Permanently fixing your system's locale configuration
Fixing system locale configuration
The localeconv function
I18N::Langinfo
LOCALE CATEGORIES
Category LC_COLLATE: Collation
Category LC_CTYPE: Character Types
Category LC_NUMERIC: Numeric Formatting
Category LC_MONETARY: Formatting of monetary amounts
LC_TIME
Other categories
SECURITY
ENVIRONMENT

PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY, LC_NUMERIC, LC_TIME, LANG

NOTES
Backward compatibility
I18N:Collate obsolete
Sort speed and memory use impacts
write() and LC_NUMERIC
Freely available locale definitions
I18n and l10n
An imperfect standard
Unicode and UTF-8
BUGS
Broken systems
SEE ALSO
HISTORY

perluniintro - Perl Unicode introduction

DESCRIPTION
Unicode
Perl's Unicode Support
Perl's Unicode Model
Unicode and EBCDIC
Creating Unicode
Handling Unicode
Legacy Encodings
Unicode I/O
Displaying Unicode As Text
Special Cases
Advanced Topics
Miscellaneous
Questions With Answers
Hexadecimal Notation
Further Resources
UNICODE IN OLDER PERLS
SEE ALSO
ACKNOWLEDGMENTS
AUTHOR, COPYRIGHT, AND LICENSE

perlunicode - Unicode support in Perl

DESCRIPTION
Important Caveats

Input and Output Layers, Regular Expressions, use utf8 still needed to enable UTF-8/UTF-EBCDIC in scripts, BOM-marked scripts and UTF-16 scripts autodetected, use encoding needed to upgrade non-Latin-1 byte strings

Byte and Character Semantics
Effects of Character Semantics
Scripts
Blocks
User-Defined Character Properties
Character Encodings for Input and Output
Unicode Regular Expression Support Level
Unicode Encodings
Security Implications of Unicode
Unicode in Perl on EBCDIC
Locales
When Unicode Does Not Happen
Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
Using Unicode in XS
BUGS
Interaction with Locales
Interaction with Extensions
Speed
Porting code from perl-5.6.X
SEE ALSO

perlebcdic - Considerations for running Perl on EBCDIC platforms

DESCRIPTION
COMMON CHARACTER CODE SETS
ASCII
ISO 8859
Latin 1 (ISO 8859-1)
EBCDIC
  • variant characters
  • POSIX-BC
    Unicode code points versus EBCDIC code points
    Remaining Perl Unicode problems in EBCDIC
    Unicode and UTF
    Using Encode
    • SINGLE OCTET TABLES

    recipe 0, recipe 1, recipe 2, recipe 3, recipe 4, recipe 5, recipe 6

    IDENTIFYING CHARACTER CODE SETS
    CONVERSIONS
    tr///
    iconv
    C RTL
    OPERATOR DIFFERENCES
    FUNCTION DIFFERENCES

    chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack()

    REGULAR EXPRESSION DIFFERENCES
    SOCKETS
    SORTING
    Ignore ASCII vs. EBCDIC sort differences.
    MONO CASE then sort data.
    Convert, sort data, then re convert.
    Perform sorting on one type of machine only.
    TRANSFORMATION FORMATS
    URL decoding and encoding
    uu encoding and decoding
    Quoted-Printable encoding and decoding
    Caesarian ciphers
    Hashing order and checksums
    I18N AND L10N
    MULTI OCTET CHARACTER SETS
    OS ISSUES
    OS/400

    PASE, IFS access

    OS/390, z/OS

    chcp, dataset access, OS/390, z/OS iconv, locales

    VM/ESA?
    POSIX-BC?
    BUGS
    SEE ALSO
    REFERENCES
    HISTORY
    AUTHOR

    perlsec - Perl security

    DESCRIPTION
    Laundering and Detecting Tainted Data
    Switches On the "#!" Line
    Taint mode and @INC
    Cleaning Up Your Path
    Security Bugs
    Protecting Your Programs
    Unicode
    Algorithmic Complexity Attacks
    SEE ALSO

    perlmod - Perl modules (packages and symbol tables)

    DESCRIPTION
    Packages
    Symbol Tables
    BEGIN, CHECK, INIT and END
    Perl Classes
    Perl Modules
    Making your module threadsafe
    SEE ALSO

    perlmodlib - constructing new Perl modules and finding existing ones

    THE PERL MODULE LIBRARY
    Pragmatic Modules

    assertions::compat, attributes, attrs, autouse, base, bigint, bignum, bigrat, blib, bytes, charnames, constant, diagnostics, encoding, fields, filetest, if, integer, less, lib, locale, open, ops, overload, re, sigtrap, sort, strict, subs, threads, threads::shared, utf8, vars, vmsish, warnings, warnings::register

    Standard Modules

    AnyDBM_File, Archive::Tar, Archive::Tar::File, Attribute::Handlers,
AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock, B::Bytecode,
B::C, B::CC, B::Concise, B::Debug, B::Deparse, B::Disassembler, B::Lint,
B::Showlex, B::Stackobj, B::Stash, B::Terse, B::Xref, Benchmark,
ByteLoader, CGI, CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast,
CGI::Pretty, CGI::Push, CGI::Switch, CGI::Util, CPAN, CPAN::FirstTime,
CPAN::Nox, Carp, Carp::Heavy, Class::ISA, Class::Struct, Compress::Zlib,
Config, Cwd, DB, DB_File, Data::Dumper, Devel::DProf, Devel::PPPort,
Devel::Peek, Devel::SelfStubber, Digest, Digest::MD5, Digest::base,
DirHandle, Dumpvalue, DynaLoader, Encode, Encode::Alias, Encode::Byte,
Encode::CJKConstants, Encode::CN, Encode::CN::HZ, Encode::Config,
Encode::EBCDIC, Encode::Encoder, Encode::Encoding, Encode::Guess,
Encode::JP, Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR,
Encode::KR::2022_KR, Encode::MIME::Header, Encode::PerlIO,
Encode::Supported, Encode::Symbol, Encode::TW, Encode::Unicode,
Encode::Unicode::UTF7, English, Env, Errno, Exporter, Exporter::Heavy,
ExtUtils::CBuilder, ExtUtils::CBuilder::Platform::Windows,
ExtUtils::Command, ExtUtils::Command::MM, ExtUtils::Constant,
ExtUtils::Embed, ExtUtils::Install, ExtUtils::Installed, ExtUtils::Liblist,
ExtUtils::MM, ExtUtils::MM_AIX, ExtUtils::MM_Any, ExtUtils::MM_BeOS,
ExtUtils::MM_Cygwin, ExtUtils::MM_DOS, ExtUtils::MM_MacOS,
ExtUtils::MM_NW5, ExtUtils::MM_OS2, ExtUtils::MM_QNX, ExtUtils::MM_UWIN,
ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_VOS, ExtUtils::MM_Win32,
ExtUtils::MM_Win95, ExtUtils::MY, ExtUtils::MakeMaker,
ExtUtils::MakeMaker::Config, ExtUtils::MakeMaker::FAQ,
ExtUtils::MakeMaker::Tutorial, ExtUtils::MakeMaker::bytes,
ExtUtils::MakeMaker::vmsish, ExtUtils::Manifest, ExtUtils::Mkbootstrap,
ExtUtils::Mksymlists, ExtUtils::Packlist, ExtUtils::ParseXS,
ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree,
File::Compare, File::Copy, File::DosGlob, File::Find, File::Glob,
File::Path, File::Spec, File::Spec::Cygwin, File::Spec::Epoc,
File::Spec::Functions, File::Spec::Mac, File::Spec::OS2, File::Spec::Unix,
File::Spec::VMS, File::Spec::Win32, File::Temp, File::stat, FileCache,
FileHandle, Filter::Simple, Filter::Util::Call, FindBin, GDBM_File,
Getopt::Long, Getopt::Std, Hash::Util, I18N::Collate, I18N::LangTags,
I18N::LangTags::List, I18N::Langinfo, IO, IO::Dir, IO::File, IO::Handle,
IO::Pipe, IO::Poll, IO::Seekable, IO::Select, IO::Socket, IO::Socket::INET,
IO::Socket::UNIX, IO::Zlib, IPC::Open2, IPC::Open3, IPC::SysV,
IPC::SysV::Msg, IPC::SysV::Semaphore, List::Util, Locale::Constants,
Locale::Country, Locale::Currency, Locale::Language, Locale::Maketext,
Locale::Maketext::TPJ13, Locale::Script, MIME::Base64,
MIME::Base64::QuotedPrint, Math::BigFloat, Math::BigInt,
Math::BigInt::Calc, Math::BigInt::FastCalc, Math::BigRat, Math::Complex,
Math::Trig, Memoize, Memoize::AnyDBM_File, Memoize::Expire,
Memoize::ExpireFile, Memoize::ExpireTest, Memoize::NDBM_File,
Memoize::SDBM_File, Memoize::Storable, NDBM_File, NEXT, Net::Cmd,
Net::Config, Net::Domain, Net::FTP, Net::NNTP, Net::Netrc, Net::POP3,
Net::Ping, Net::SMTP, Net::Time, Net::hostent, Net::libnetFAQ, Net::netent,
Net::protoent, Net::servent, O, ODBM_File, Opcode, POSIX, PerlIO,
PerlIO::encoding, PerlIO::scalar, PerlIO::via, PerlIO::via::QuotedPrint,
Pod::Checker, Pod::Find, Pod::Functions, Pod::Html, Pod::InputObjects,
Pod::LaTeX, Pod::Man, Pod::ParseLink, Pod::ParseUtils, Pod::Parser,
Pod::Perldoc::ToChecker, Pod::Perldoc::ToMan, Pod::Perldoc::ToNroff,
Pod::Perldoc::ToPod, Pod::Perldoc::ToRtf, Pod::Perldoc::ToText,
Pod::Perldoc::ToTk, Pod::Perldoc::ToXml, Pod::PlainText, Pod::Plainer,
Pod::Select, Pod::Text, Pod::Text::Color, Pod::Text::Overstrike,
Pod::Text::Termcap, Pod::Usage, SDBM_File, Safe, Scalar::Util,
Search::Dict, SelectSaver, SelfLoader, Shell, Socket, Storable, Switch,
Symbol, Sys::Hostname, Sys::Syslog, Term::ANSIColor, Term::Cap,
Term::Complete, Term::ReadLine, Test, Test::Builder, Test::Harness,
Test::Harness::Assert, Test::Harness::Iterator, Test::Harness::Point,
Test::Harness::Straps, Test::More, Test::Simple, Test::Tutorial,
Text::Abbrev, Text::Balanced, Text::ParseWords, Text::Soundex, Text::Tabs,
Text::Wrap, Thread, Thread::Queue, Thread::Semaphore, Thread::Signal,
Thread::Specific, Tie::Array, Tie::File, Tie::Handle, Tie::Hash,
Tie::Memoize, Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::HiRes,
Time::Local, Time::gmtime, Time::localtime, Time::tm, UNIVERSAL,
Unicode::Collate, Unicode::Normalize, Unicode::UCD, User::grent,
User::pwent, Win32, XS::APItest, XS::Typemap, XSLoader

    Extension Modules
    CPAN
    Africa

    South Africa

    Asia

    China, Indonesia, Israel, Japan, Malaysia, Russian Federation, Saudi Arabia, Singapore, South Korea, Taiwan, Thailand

    Central America

    Costa Rica

    Europe

    Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Croatia, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Lithuania, Netherlands, Norway, Poland, Portugal, Romania, Russia, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, Ukraine, United Kingdom

    North America

    Canada, Alberta, Manitoba, Nova Scotia, Ontario, Mexico, United States, Alabama, California, Colorado, Delaware, District of Columbia, Florida, Indiana, Kentucky, Massachusetts, Michigan, Nevada, New Jersey, New York, North Carolina, Oklahoma, Oregon, Pennsylvania, Tennessee, Texas, Utah, Virginia, Washington, Wisconsin

    Oceania

    Australia, New Zealand, United States

    South America

    Argentina, Brazil, Chile

    RSYNC Mirrors
    Modules: Creation, Use, and Abuse
    Guidelines for Module Creation
    Guidelines for Converting Perl 4 Library Scripts into Modules
    Guidelines for Reusing Application Code
    NOTE

    perlmodstyle - Perl module style guide

    INTRODUCTION
    QUICK CHECKLIST
    Before you start
    The API
    Stability
    Documentation
    Release considerations
    BEFORE YOU START WRITING A MODULE
    Has it been done before?
    Do one thing and do it well
    What's in a name?
    DESIGNING AND WRITING YOUR MODULE
    To OO or not to OO?
    Designing your API

    Write simple routines to do simple things, Separate functionality from output, Provide sensible shortcuts and defaults, Naming conventions, Parameter passing

    Strictness and warnings
    Backwards compatibility
    Error handling and messages
    DOCUMENTING YOUR MODULE
    POD
    README, INSTALL, release notes, changelogs

    perl Makefile.PL, make, make test, make install, perl Build.PL, perl Build, perl Build test, perl Build install

    RELEASE CONSIDERATIONS
    Version numbering
    Pre-requisites
    Testing
    Packaging
    Licensing
    COMMON PITFALLS
    Reinventing the wheel
    Trying to do too much
    Inappropriate documentation
    SEE ALSO

    the perlstyle manpage, the perlnewmod manpage, the perlpod manpage, podchecker, Packaging Tools, Testing tools, http://pause.perl.org/, Any good book on software engineering

    AUTHOR

    perlmodinstall - Installing CPAN Modules

    DESCRIPTION
    PREAMBLE

    DECOMPRESS the file, UNPACK the file into a directory, BUILD the module (sometimes unnecessary), INSTALL the module

    PORTABILITY
    HEY
    AUTHOR
    COPYRIGHT

    perlnewmod - preparing a new module for distribution

    DESCRIPTION
    Warning
    What should I make into a module?
    Step-by-step: Preparing the ground

    Look around, Check it's new, Discuss the need, Choose a name, Check again

    Step-by-step: Making the module

    Start with module-starter or h2xs, Use strict and warnings, Use Carp, Use Exporter - wisely!, Use plain old documentation, Write tests, Write the README

    Step-by-step: Distributing your module

    Get a CPAN user ID, perl Makefile.PL; make test; make dist, Upload the tarball, Announce to the modules list, Announce to clpa, Fix bugs!

    AUTHOR
    SEE ALSO

    perlutil - utilities packaged with the Perl distribution

    DESCRIPTION
    DOCUMENTATION

    perldoc, pod2man and pod2text, pod2html and pod2latex, pod2usage, podselect, podchecker, splain, roffitall

    CONVERTORS

    a2p, s2p, find2perl

    Administration

    libnetcfg

    Development

    perlbug, h2ph, c2ph and pstruct, h2xs, dprofpp, perlcc

    SEE ALSO

    perlcompile - Introduction to the Perl Compiler-Translator

    DESCRIPTION
    Layout

    B::Bytecode, B::C, B::CC, B::Lint, B::Deparse, B::Xref

    Using The Back Ends
    The Cross Referencing Back End

    i, &, s, r

    The Decompiling Back End
    The Lint Back End
    The Simple C Back End
    The Bytecode Back End
    The Optimized C Back End
    Module List for the Compiler Suite

    B, O, B::Asmdata, B::Assembler, B::Bblock, B::Bytecode, B::C, B::CC, B::Concise, B::Debug, B::Deparse, B::Disassembler, B::Lint, B::Showlex, B::Stackobj, B::Stash, B::Terse, B::Xref

    KNOWN PROBLEMS
    AUTHOR

    perlfilter - Source Filters

    DESCRIPTION
    CONCEPTS
    USING FILTERS
    WRITING A SOURCE FILTER
    WRITING A SOURCE FILTER IN C

    Decryption Filters

    CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
    WRITING A SOURCE FILTER IN PERL
    USING CONTEXT: THE DEBUG FILTER
    CONCLUSION
    THINGS TO LOOK OUT FOR

    Some Filters Clobber the DATA Handle

    REQUIREMENTS
    AUTHOR
    Copyrights

    perlglossary - Perl Glossary

    DESCRIPTION
    A

    accessor methods, actual arguments, address operator, algorithm, alias, alternatives, anonymous, architecture, argument, ARGV, arithmetical operator, array, array context, ASCII, assertion, assignment, assignment operator, associative array, associativity, asynchronous, atom, atomic operation, attribute, autogeneration, autoincrement, autoload, autosplit, autovivification, AV, awk

    B

    backreference, backtracking, backward compatibility, bareword, base class, big-endian, binary, binary operator, bind, bit, bit shift, bit string, bless, block, BLOCK, block buffering, Boolean, Boolean context, breakpoint, broadcast, BSD, bucket, buffer, built-in, bundle, byte, bytecode

    C

    C, C preprocessor, call by reference, call by value, callback, canonical, capturing, character, character class, character property, circumfix operator, class, class method, client, cloister, closure, cluster, CODE, code generator, code subpattern, collating sequence, command, command buffering, command name, command-line arguments, comment, compilation unit, compile phase, compile time, compiler, composer, concatenation, conditional, connection, construct, constructor, context, continuation, core dump, CPAN, cracker, current package, current working directory, currently selected output channel, CV

    D

    dangling statement, data structure, data type, datagram, DBM, declaration, decrement, default, defined, delimiter, dereference, derived class, descriptor, destroy, destructor, device, directive, directory, directory handle, dispatch, distribution, dweomer, dwimmer, dynamic scoping

    E

    eclectic, element, embedding, empty subclass test, en passant, encapsulation, endian, environment, environment variable, EOF, errno, error, escape sequence, exception, exception handling, exec, executable file, execute, execute bit, exit status, export, expression, extension

    F

    false, FAQ, fatal error, field, FIFO, file, file descriptor, file test operator, fileglob, filehandle, filename, filesystem, filter, flag, floating point, flush, FMTEYEWTK, fork, formal arguments, format, freely available, freely redistributable, freeware, function, funny character, garbage collection

    G

    GID, glob, global, global destruction, glue language, granularity, greedy, grep, group, GV

    H

    hacker, handler, hard reference, hash, hash table, header file, here document, hexadecimal, home directory, host, hubris, HV

    I

    identifier, impatience, implementation, import, increment, indexing, indirect filehandle, indirect object, indirect object slot, indirection, infix, inheritance, instance, instance variable, integer, interface, interpolation, interpreter, invocant, invocation, I/O, IO, IP, IPC, is-a, iteration, iterator, IV

    J

    JAPH

    K

    key, keyword

    L

    label, laziness, left shift, leftmost longest, lexeme, lexer, lexical analysis, lexical scoping, lexical variable, library, LIFO, line, line buffering, line number, link, LIST, list, list context, list operator, list value, literal, little-endian, local, logical operator, lookahead, lookbehind, loop, loop control statement, loop label, lvaluable, lvalue, lvalue modifier

    M

    magic, magical increment, magical variables, Makefile, man, manpage, matching, member data, memory, metacharacter, metasymbol, method, minimalism, mode, modifier, module, modulus, monger, mortal, multidimensional array, multiple inheritance

    N

    named pipe, namespace, network address, newline, NFS, null character, null list, null string, numeric context, NV, nybble

    O

    object, octal, offset, one-liner, open source software, operand, operating system, operator, operator overloading, options, overloading, overriding, owner

    P

    package, pad, parameter, parent class, parse tree, parsing, patch, PATH, pathname, pattern, pattern matching, permission bits, Pern, pipe, pipeline, platform, pod, pointer, polymorphism, port, portable, porter, POSIX, postfix, pp, pragma, precedence, prefix, preprocessing, procedure, process, program generator, progressive matching, property, protocol, prototype, pseudofunction, pseudohash, pseudoliteral, public domain, pumpkin, pumpking, PV

    Q

    qualified, quantifier

    R

    readable, reaping, record, recursion, reference, referent, regex, regular expression, regular expression modifier, regular file, relational operator, reserved words, return value, RFC, right shift, root, RTFM, run phase, run time, run-time pattern, RV, rvalue

    S

    scalar, scalar context, scalar literal, scalar value, scalar variable, scope, scratchpad, script, script kiddie, sed, semaphore, separator, serialization, server, service, setgid, setuid, shared memory, shebang, shell, side effects, signal, signal handler, single inheritance, slice, slurp, socket, soft reference, source filter, stack, standard, standard error, standard I/O, standard input, standard output, stat structure, statement, statement modifier, static, static method, static scoping, static variable, status, STDERR, STDIN, STDIO, STDOUT, stream, string, string context, stringification, struct, structure, subclass, subpattern, subroutine, subscript, substitution, substring, superclass, superuser, SV, switch, switch cluster, switch statement, symbol, symbol table, symbolic debugger, symbolic link, symbolic reference, synchronous, syntactic sugar, syntax, syntax tree, syscall

    T

    tainted, TCP, term, terminator, ternary, text, thread, tie, TMTOWTDI, token, tokener, tokenizing, toolbox approach, transliterate, trigger, trinary, troff, true, truncating, type, type casting, typed lexical, typedef, typeglob, typemap

    U

    UDP, UID, umask, unary operator, Unicode, Unix

    V

    value, variable, variable interpolation, variadic, vector, virtual, void context, v-string

    W

    warning, watch expression, whitespace, word, working directory, wrapper, WYSIWYG

    X

    XS, XSUB

    Y

    yacc

    Z

    zero width, zombie

    AUTHOR AND COPYRIGHT

    perlembed - how to embed perl in your C program

    DESCRIPTION
    PREAMBLE

    Use C from Perl?, Use a Unix program from Perl?, Use Perl from Perl?, Use C from C?, Use Perl from C?

    ROADMAP
    Compiling your C program
    Adding a Perl interpreter to your C program
    Calling a Perl subroutine from your C program
    Evaluating a Perl statement from your C program
    Performing Perl pattern matches and substitutions from your C program
    Fiddling with the Perl stack from your C program
    Maintaining a persistent interpreter
    Execution of END blocks
    Maintaining multiple interpreter instances
    Using Perl modules, which themselves use C libraries, from your C program
    Embedding Perl under Win32
    Hiding Perl_
    MORAL
    AUTHOR
    COPYRIGHT

    perldebguts - Guts of Perl debugging

    DESCRIPTION
    Debugger Internals
    Writing Your Own Debugger
    Frame Listing Output Examples
    Debugging regular expressions
    Compile-time output

    anchored STRING at POS, floating STRING at POS1..POS2, matching floating/anchored, minlen, stclass TYPE, noscan, isall, GPOS, plus, implicit, with eval, anchored(TYPE)

    Types of nodes
    Run-time output
    Debugging Perl memory usage
    Using $ENV{PERL_DEBUG_MSTATS}

    buckets SMALLEST(APPROX)..GREATEST(APPROX), Free/Used, Total sbrk(): SBRKed/SBRKs:CONTINUOUS, pad: 0, heads: 2192, chain: 0, tail: 6144

    SEE ALSO

    perlxstut, perlXStut - Tutorial for writing XSUBs

    DESCRIPTION
    SPECIAL NOTES
    make
    Version caveat
    Dynamic Loading versus Static Loading
    TUTORIAL
    EXAMPLE 1
    EXAMPLE 2
    What has gone on?
    Writing good test scripts
    EXAMPLE 3
    What's new here?
    Input and Output Parameters
    The XSUBPP Program
    The TYPEMAP file
    Warning about Output Arguments
    EXAMPLE 4
    What has happened here?
    Anatomy of .xs file
    Getting the fat out of XSUBs
    More about XSUB arguments
    The Argument Stack
    Extending your Extension
    Documenting your Extension
    Installing your Extension
    EXAMPLE 5
    New Things in this Example
    EXAMPLE 6
    New Things in this Example
    EXAMPLE 7 (Coming Soon)
    EXAMPLE 8 (Coming Soon)
    EXAMPLE 9 Passing open files to XSes
    Troubleshooting these Examples
    See also
    Author
    Last Changed

    perlxs - XS language reference manual

    DESCRIPTION
    Introduction
    On The Road
    The Anatomy of an XSUB
    The Argument Stack
    The RETVAL Variable
    Returning SVs, AVs and HVs through RETVAL
    The MODULE Keyword
    The PACKAGE Keyword
    The PREFIX Keyword
    The OUTPUT: Keyword
    The NO_OUTPUT Keyword
    The CODE: Keyword
    The INIT: Keyword
    The NO_INIT Keyword
    Initializing Function Parameters
    Default Parameter Values
    The PREINIT: Keyword
    The SCOPE: Keyword
    The INPUT: Keyword
    The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
    The length(NAME) Keyword
    Variable-length Parameter Lists
    The C_ARGS: Keyword
    The PPCODE: Keyword
    Returning Undef And Empty Lists
    The REQUIRE: Keyword
    The CLEANUP: Keyword
    The POSTCALL: Keyword
    The BOOT: Keyword
    The VERSIONCHECK: Keyword
    The PROTOTYPES: Keyword
    The PROTOTYPE: Keyword
    The ALIAS: Keyword
    The OVERLOAD: Keyword
    The FALLBACK: Keyword
    The INTERFACE: Keyword
    The INTERFACE_MACRO: Keyword
    The INCLUDE: Keyword
    The CASE: Keyword
    The & Unary Operator
    Inserting POD, Comments and C Preprocessor Directives
    Using XS With C++
    Interface Strategy
    Perl Objects And C Structures
    The Typemap
    Safely Storing Static Data in XS

    MY_CXT_KEY, typedef my_cxt_t, START_MY_CXT, MY_CXT_INIT, dMY_CXT, MY_CXT

    EXAMPLES
    XS VERSION
    AUTHOR

    perlclib - Internal replacements for standard C library functions

    DESCRIPTION
    Conventions

    t, p, n, s

    File Operations
    File Input and Output
    File Positioning
    Memory Management and String Handling
    Character Class Tests
    stdlib.h functions
    Miscellaneous functions
    SEE ALSO

    perlguts - Introduction to the Perl API

    DESCRIPTION
    Variables
    Datatypes
    What is an "IV"?
    Working with SVs
    Offsets
    What's Really Stored in an SV?
    Working with AVs
    Working with HVs
    Hash API Extensions
    AVs, HVs and undefined values
    References
    Blessed References and Class Objects
    Creating New Variables

    GV_ADDMULTI, GV_ADDWARN

    Reference Counts and Mortality
    Stashes and Globs
    Double-Typed SVs
    Magic Variables
    Assigning Magic
    Magic Virtual Tables
    Finding Magic
    Understanding the Magic of Tied Hashes and Arrays
    Localizing changes

    SAVEINT(int i), SAVEIV(IV i), SAVEI32(I32 i), SAVELONG(long i), SAVESPTR(s), SAVEPPTR(p), SAVEFREESV(SV *sv), SAVEMORTALIZESV(SV *sv), SAVEFREEOP(OP *op), SAVEFREEPV(p), SAVECLEARSV(SV *sv), SAVEDELETE(HV *hv, char *key, I32 length), SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p), SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p), SAVESTACK_POS(), SV* save_scalar(GV *gv), AV* save_ary(GV *gv), HV* save_hash(GV *gv), void save_item(SV *item), void save_list(SV **sarg, I32 maxsarg), SV* save_svref(SV **sptr), void save_aptr(AV **aptr), void save_hptr(HV **hptr)

    Subroutines
    XSUBs and the Argument Stack
    Calling Perl Routines from within C Programs
    Memory Allocation
    PerlIO
    Putting a C value on Perl stack
    Scratchpads
    Scratchpads and recursion
    Compiled code
    Code tree
    Examining the tree
    Compile pass 1: check routines
    Compile pass 1a: constant folding
    Compile pass 2: context propagation
    Compile pass 3: peephole optimization
    Pluggable runops
    Examining internal data structures with the dump functions
    How multiple interpreters and concurrency are supported
    Background and PERL_IMPLICIT_CONTEXT
    So what happened to dTHR?
    How do I use all this in extensions?
    Should I do anything special if I call perl from multiple threads?
    Future Plans and PERL_IMPLICIT_SYS
    Internal Functions

    A, p, d, s, n, r, f, M, o, x, m, X, E, b

    Formatted Printing of IVs, UVs, and NVs
    Pointer-To-Integer and Integer-To-Pointer
    Source Documentation
    Backwards compatibility
    Unicode Support
    What is Unicode, anyway?
    How can I recognise a UTF-8 string?
    How does UTF-8 represent Unicode characters?
    How does Perl store UTF-8 strings?
    How do I convert a string to UTF-8?
    Is there anything else I need to know?
    Custom Operators
    AUTHORS
    SEE ALSO

    perlcall - Perl calling conventions from C

    DESCRIPTION

    An Error Handler, An Event Driven Program

    THE CALL_ FUNCTIONS

    call_sv, call_pv, call_method, call_argv

    FLAG VALUES
    G_VOID
    G_SCALAR
    G_ARRAY
    G_DISCARD
    G_NOARGS
    G_EVAL
    G_KEEPERR
    Determining the Context
    EXAMPLES
    No Parameters, Nothing returned
    Passing Parameters
    Returning a Scalar
    Returning a list of values
    Returning a list in a scalar context
    Returning Data from Perl via the parameter list
    Using G_EVAL
    Using G_KEEPERR
    Using call_sv
    Using call_argv
    Using call_method
    Using GIMME_V
    Using Perl to dispose of temporaries
    Strategies for storing Callback Context Information

    1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of callbacks - hard wired limit, 3. Use a parameter to map to the Perl callback

    Alternate Stack Manipulation
    Creating and calling an anonymous subroutine in C
    SEE ALSO
    AUTHOR
    DATE

    perlapi - autogenerated documentation for the perl public API

    DESCRIPTION
    "Gimme" Values

    GIMME , GIMME_V , G_ARRAY , G_DISCARD , G_EVAL , G_NOARGS , G_SCALAR , G_VOID

    Array Manipulation Functions

    AvFILL , av_clear , av_delete , av_exists , av_extend , av_fetch , av_fill , av_len , av_make , av_pop , av_push , av_shift , av_store , av_undef , av_unshift , get_av , newAV , sortsv

    Callback Functions

    call_argv , call_method , call_pv , call_sv , ENTER , eval_pv , eval_sv , FREETMPS , LEAVE , SAVETMPS

    Character classes

    isALNUM , isALPHA , isDIGIT , isLOWER , isSPACE , isUPPER , toLOWER , toUPPER

    Cloning an interpreter

    perl_clone

    CV Manipulation Functions

    CvSTASH , get_cv

    Embedding Functions

    cv_undef , load_module , nothreadhook , perl_alloc , perl_construct , perl_destruct , perl_free , perl_parse , perl_run , require_pv

    Functions in file pp_pack.c

    packlist , pack_cat , unpackstring , unpack_str

    Global Variables

    PL_modglobal , PL_na , PL_sv_no , PL_sv_undef , PL_sv_yes

    GV Functions

    GvSV , gv_fetchmeth , gv_fetchmethod , gv_fetchmethod_autoload , gv_fetchmeth_autoload , gv_stashpv , gv_stashpvn , gv_stashsv

    Handy Values

    Nullav , Nullch , Nullcv , Nullhv , Nullsv

    Hash Manipulation Functions

    get_hv , HEf_SVKEY , HeHASH , HeKEY , HeKLEN , HePV , HeSVKEY , HeSVKEY_force , HeSVKEY_set , HeVAL , HvNAME , hv_clear , hv_clear_placeholders , hv_delete , hv_delete_ent , hv_exists , hv_exists_ent , hv_fetch , hv_fetch_ent , hv_iterinit , hv_iterkey , hv_iterkeysv , hv_iternext , hv_iternextsv , hv_iternext_flags , hv_iterval , hv_magic , hv_scalar , hv_store , hv_store_ent , hv_undef , newHV

    Magical Functions

    mg_clear , mg_copy , mg_find , mg_free , mg_get , mg_length , mg_magical , mg_set , SvGETMAGIC , SvLOCK , SvSETMAGIC , SvSetMagicSV , SvSetMagicSV_nosteal , SvSetSV , SvSetSV_nosteal , SvSHARE , SvUNLOCK

    Memory Management

    Copy , CopyD , Move , MoveD , Newx , Newxc , Newxz , Poison , Renew , Renewc , Safefree , savepv , savepvn , savesharedpv , savesvpv , StructCopy , Zero , ZeroD

    Miscellaneous Functions

    fbm_compile , fbm_instr , form , getcwd_sv , strEQ , strGE , strGT , strLE , strLT , strNE , strnEQ , strnNE , sv_nolocking , sv_nosharing , sv_nounlocking

    Numeric functions

    grok_bin , grok_hex , grok_number , grok_numeric_radix , grok_oct , scan_bin , scan_hex , scan_oct

    Optree Manipulation Functions

    cv_const_sv , newCONSTSUB , newXS

    Pad Data Structures

    pad_sv

    Stack Manipulation Macros

    dMARK , dORIGMARK , dSP , EXTEND , MARK , mPUSHi , mPUSHn , mPUSHp , mPUSHu , mXPUSHi , mXPUSHn , mXPUSHp , mXPUSHu , ORIGMARK , POPi , POPl , POPn , POPp , POPpbytex , POPpx , POPs , PUSHi , PUSHMARK , PUSHmortal , PUSHn , PUSHp , PUSHs , PUSHu , PUTBACK , SP , SPAGAIN , XPUSHi , XPUSHmortal , XPUSHn , XPUSHp , XPUSHs , XPUSHu , XSRETURN , XSRETURN_EMPTY , XSRETURN_IV , XSRETURN_NO , XSRETURN_NV , XSRETURN_PV , XSRETURN_UNDEF , XSRETURN_UV , XSRETURN_YES , XST_mIV , XST_mNO , XST_mNV , XST_mPV , XST_mUNDEF , XST_mYES

    SV Flags

    svtype , SVt_IV , SVt_NV , SVt_PV , SVt_PVAV , SVt_PVCV , SVt_PVHV , SVt_PVMG

    SV Manipulation Functions

    get_sv , looks_like_number , newRV_inc , newRV_noinc , NEWSV , newSV , newSVhek , newSViv , newSVnv , newSVpv , newSVpvf , newSVpvn , newSVpvn_share , newSVrv , newSVsv , newSVuv , SvCUR , SvCUR_set , SvEND , SvGROW , SvIOK , SvIOKp , SvIOK_notUV , SvIOK_off , SvIOK_on , SvIOK_only , SvIOK_only_UV , SvIOK_UV , SvIsCOW , SvIsCOW_shared_hash , SvIV , SvIVX , SvIVx , SvIV_set , SvLEN , SvLEN_set , SvMAGIC_set , SvNIOK , SvNIOKp , SvNIOK_off , SvNOK , SvNOKp , SvNOK_off , SvNOK_on , SvNOK_only , SvNV , SvNVX , SvNVx , SvNV_set , SvOK , SvOOK , SvPOK , SvPOKp , SvPOK_off , SvPOK_on , SvPOK_only , SvPOK_only_UTF8 , SvPV , SvPVbyte , SvPVbytex , SvPVbytex_force , SvPVbyte_force , SvPVbyte_nolen , SvPVutf8 , SvPVutf8x , SvPVutf8x_force , SvPVutf8_force , SvPVutf8_nolen , SvPVX , SvPVx , SvPV_force , SvPV_force_nomg , SvPV_nolen , SvPV_set , SvREFCNT , SvREFCNT_dec , SvREFCNT_inc , SvROK , SvROK_off , SvROK_on , SvRV , SvRV_set , SvSTASH , SvSTASH_set , SvTAINT , SvTAINTED , SvTAINTED_off , SvTAINTED_on , SvTRUE , SvTYPE , SvUOK , SvUPGRADE , SvUTF8 , SvUTF8_off , SvUTF8_on , SvUV , SvUVX , SvUVx , SvUV_set , sv_2bool , sv_2cv , sv_2io , sv_2iv , sv_2mortal , sv_2nv , sv_2pvbyte , sv_2pvbyte_nolen , sv_2pvutf8 , sv_2pvutf8_nolen , sv_2pv_flags , sv_2pv_nolen , sv_2uv , sv_backoff , sv_bless , sv_catpv , sv_catpvf , sv_catpvf_mg , sv_catpvn , sv_catpvn_flags , sv_catpvn_mg , sv_catpvn_nomg , sv_catpv_mg , sv_catsv , sv_catsv_flags , sv_catsv_mg , sv_catsv_nomg , sv_chop , sv_clear , sv_cmp , sv_cmp_locale , sv_collxfrm , sv_copypv , sv_dec , sv_derived_from , sv_eq , sv_force_normal , sv_force_normal_flags , sv_free , sv_gets , sv_grow , sv_inc , sv_insert , sv_isa , sv_isobject , sv_iv , sv_len , sv_len_utf8 , sv_magic , sv_magicext , sv_mortalcopy , sv_newmortal , sv_newref , sv_nv , sv_pos_b2u , sv_pos_u2b , sv_pv , sv_pvbyte , sv_pvbyten , sv_pvbyten_force , sv_pvn , sv_pvn_force , sv_pvn_force_flags , sv_pvutf8 , sv_pvutf8n , sv_pvutf8n_force , sv_reftype , sv_replace , sv_report_used , sv_reset , sv_rvweaken , sv_setiv , sv_setiv_mg , sv_setnv , sv_setnv_mg , sv_setpv , sv_setpvf , sv_setpvf_mg , sv_setpviv , sv_setpviv_mg , sv_setpvn , sv_setpvn_mg , sv_setpv_mg , sv_setref_iv , sv_setref_nv , sv_setref_pv , sv_setref_pvn , sv_setref_uv , sv_setsv , sv_setsv_flags , sv_setsv_mg , sv_setsv_nomg , sv_setuv , sv_setuv_mg , sv_taint , sv_tainted , sv_true , sv_unmagic , sv_unref , sv_unref_flags , sv_untaint , sv_upgrade , sv_usepvn , sv_usepvn_mg , sv_utf8_decode , sv_utf8_downgrade , sv_utf8_encode , sv_utf8_upgrade , sv_utf8_upgrade_flags , sv_uv , sv_vcatpvf , sv_vcatpvfn , sv_vcatpvf_mg , sv_vsetpvf , sv_vsetpvfn , sv_vsetpvf_mg

    Unicode Support

    bytes_from_utf8 , bytes_to_utf8 , ibcmp_utf8 , is_utf8_char , is_utf8_string , is_utf8_string_loc , is_utf8_string_loclen , pv_uni_display , sv_cat_decode , sv_recode_to_utf8 , sv_uni_display , to_utf8_case , to_utf8_fold , to_utf8_lower , to_utf8_title , to_utf8_upper , utf8n_to_uvchr , utf8n_to_uvuni , utf8_distance , utf8_hop , utf8_length , utf8_to_bytes , utf8_to_uvchr , utf8_to_uvuni , uvchr_to_utf8 , uvuni_to_utf8_flags

    Variables created by xsubpp and xsubpp internal functions

    ax , CLASS , dAX , dAXMARK , dITEMS , dXSARGS , dXSI32 , items , ix , newXSproto , RETVAL , ST , THIS , XS , XS_VERSION , XS_VERSION_BOOTCHECK

    Warning and Dieing

    croak , warn

    AUTHORS
    SEE ALSO

    perlintern - autogenerated documentation of purely internal Perl functions

    DESCRIPTION
    CV reference counts and CvOUTSIDE

    CvWEAKOUTSIDE

    Functions in file pad.h

    CX_CURPAD_SAVE , CX_CURPAD_SV , PAD_BASE_SV , PAD_CLONE_VARS , PAD_COMPNAME_FLAGS , PAD_COMPNAME_GEN , PAD_COMPNAME_GEN_set , PAD_COMPNAME_OURSTASH , PAD_COMPNAME_PV , PAD_COMPNAME_TYPE , PAD_DUP , PAD_RESTORE_LOCAL , PAD_SAVE_LOCAL , PAD_SAVE_SETNULLPAD , PAD_SETSV , PAD_SET_CUR , PAD_SET_CUR_NOSAVE , PAD_SV , PAD_SVl , SAVECLEARSV , SAVECOMPPAD , SAVEPADSV

    Functions in file pp_ctl.c

    find_runcv

    Global Variables

    PL_DBsingle , PL_DBsub , PL_DBtrace , PL_dowarn , PL_last_in_gv , PL_ofs_sv , PL_rs

    GV Functions

    is_gv_magical

    IO Functions

    start_glob

    Pad Data Structures

    CvPADLIST , cv_clone , cv_dump , do_dump_pad , intro_my , pad_add_anon , pad_add_name , pad_alloc , pad_block_start , pad_check_dup , pad_findlex , pad_findmy , pad_fixup_inner_anons , pad_free , pad_leavemy , pad_new , pad_push , pad_reset , pad_setsv , pad_swipe , pad_tidy , pad_undef

    Stack Manipulation Macros

    djSP , LVRET

    SV Manipulation Functions

    report_uninit , sv_add_arena , sv_clean_all , sv_clean_objs , sv_free_arenas

    AUTHORS
    SEE ALSO

    perliol - C API for Perl's implementation of IO in Layers.

    SYNOPSIS
    DESCRIPTION
    History and Background
    Basic Structure
    Layers vs Disciplines
    Data Structures
    Functions and Attributes
    Per-instance Data
    Layers in action.
    Per-instance flag bits

    PERLIO_F_EOF, PERLIO_F_CANWRITE, PERLIO_F_CANREAD, PERLIO_F_ERROR, PERLIO_F_TRUNCATE, PERLIO_F_APPEND, PERLIO_F_CRLF, PERLIO_F_UTF8, PERLIO_F_UNBUF, PERLIO_F_WRBUF, PERLIO_F_RDBUF, PERLIO_F_LINEBUF, PERLIO_F_TEMP, PERLIO_F_OPEN, PERLIO_F_FASTGETS

    Methods in Detail

    fsize, name, size, kind, PERLIO_K_BUFFERED, PERLIO_K_RAW, PERLIO_K_CANCRLF, PERLIO_K_FASTGETS, PERLIO_K_MULTIARG, Pushed, Popped, Open, Binmode, Getarg, Fileno, Dup, Read, Write, Seek, Tell, Close, Flush, Fill, Eof, Error, Clearerr, Setlinebuf, Get_base, Get_bufsiz, Get_ptr, Get_cnt, Set_ptrcnt

    Utilities
    Implementing PerlIO Layers

    C implementations, Perl implementations

    Core Layers

    "unix", "perlio", "stdio", "crlf", "mmap", "pending", "raw", "utf8"

    Extension Layers

    ":encoding", ":scalar", ":via"

    TODO

    perlapio - perl's IO abstraction interface.

    SYNOPSIS
    DESCRIPTION

    1. USE_STDIO, 2. USE_SFIO, 3. USE_PERLIO, PerlIO_stdin(),
PerlIO_stdout(), PerlIO_stderr(), PerlIO_open(path, mode),
PerlIO_fdopen(fd,mode), PerlIO_reopen(path,mode,f),
PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a),
PerlIO_stdoutf(fmt,...), PerlIO_read(f,buf,count),
PerlIO_write(f,buf,count), PerlIO_close(f), PerlIO_puts(f,s),
PerlIO_putc(f,c), PerlIO_ungetc(f,c), PerlIO_getc(f),
PerlIO_eof(f), PerlIO_error(f), PerlIO_fileno(f),
PerlIO_clearerr(f), PerlIO_flush(f), PerlIO_seek(f,offset,whence),
PerlIO_tell(f), PerlIO_getpos(f,p), PerlIO_setpos(f,p),
PerlIO_rewind(f), PerlIO_tmpfile(), PerlIO_setlinebuf(f)

    Co-existence with stdio

    PerlIO_importFILE(f,mode), PerlIO_exportFILE(f,mode), PerlIO_releaseFILE(p,f), PerlIO_findFILE(f)

    "Fast gets" Functions

    PerlIO_fast_gets(f), PerlIO_has_cntptr(f), PerlIO_get_cnt(f),
PerlIO_get_ptr(f), PerlIO_set_ptrcnt(f,p,c), PerlIO_canset_cnt(f),
PerlIO_set_cnt(f,c), PerlIO_has_base(f), PerlIO_get_base(f),
PerlIO_get_bufsiz(f)

    Other Functions

    PerlIO_apply_layers(f,mode,layers), PerlIO_binmode(f,ptype,imode,layers), '<' read, '>' write, '+' read/write, PerlIO_debug(fmt,...)

    perlhack - How to hack at the Perl internals

    DESCRIPTION

    Does concept match the general goals of Perl?, Where is the implementation?, Backwards compatibility, Could it be a module instead?, Is the feature generic enough?, Does it potentially introduce new bugs?, Does it preclude other desirable features?, Is the implementation robust?, Is the implementation generic enough to be portable?, Is the implementation tested?, Is there enough documentation?, Is there another way to do it?, Does it create too much work?, Patches speak louder than words

    Keeping in sync

    rsync'ing the source tree, Using rsync over the LAN, Using pushing over the NFS, rsync'ing the patches

    Why rsync the source tree

    It's easier to rsync the source tree, It's more reliable

    Why rsync the patches

    It's easier to rsync the patches, It's a good reference, Finding a start point, Finding how to fix a bug, Finding the source of misbehaviour

    Working with the source
    Perlbug administration
    Submitting patches

    the perlguts manpage, the perlxstut manpage and the perlxs manpage, the perlapi manpage, Porting/pumpkin.pod, The perl5-porters FAQ

    Finding Your Way Around

    Core modules, Tests, Documentation, Configure, Interpreter

    Elements of the interpreter

    Startup, Parsing, Optimization, Running, Exception handing

    Internal Variable Types
    Op Trees
    Stacks

    Argument stack, Mark stack, Save stack

    Millions of Macros
    The .i Targets
    Poking at Perl
    Using a source-level debugger

    run [args], break function_name, break source.c:xxx, step, next, continue, finish, 'enter', print

    gdb macro support
    Dumping Perl Data Structures
    Patching
    Patching a core module
    Adding a new function to the core
    Writing a test

    t/base/, t/cmd/, t/comp/, t/io/, t/lib/, t/op/, t/pod/, t/run/, t/uni/, t/win32/, t/x2p, t/base t/comp, t/cmd t/run t/io t/op, t/lib ext lib

    Special Make Test Targets

    coretest, test.deparse, test.taintwarn, minitest, test.valgrind check.valgrind utest.valgrind ucheck.valgrind, test.third check.third utest.third ucheck.third, test.torture torturetest, utest ucheck test.utf8 check.utf8, minitest.utf16 test.utf16, test_harness, test-notty test_notty

    Running tests by hand

    -v, -torture, -re=PATTERN, -re LIST OF PATTERNS, PERL_CORE=1, PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST

    EXTERNAL TOOLS FOR DEBUGGING PERL
    Rational Software's Purify
    Purify on Unix

    -Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity

    Purify on NT

    DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug

    valgrind
    Compaq's/Digital's/HP's Third Degree
    PERL_DESTRUCT_LEVEL
    Profiling
    Gprof Profiling

    -a, -b, -e routine, -f routine, -s, -z

    GCC gcov Profiling
    Pixie Profiling

    -h, -l, -p[rocedures], -h[eavy], -i[nvocations], -l[ines], -testcoverage, -z[ero]

    Miscellaneous tricks
    CONCLUSION

    The Road goes ever on and on, down from the door where it began.

    AUTHOR

    perlbook - Perl book information

    DESCRIPTION

    perltodo - Perl TO-DO List

    DESCRIPTION
    The roadmap to 5.10
    Needed for a 5.9.4 release
    Needed for a 5.9.5 release

    Implement _ prototype character, Implement state variables

    Needed for a 5.9.6 release
    Tasks that only need Perl knowledge
    common test code for timed bail out
    POD -> HTML conversion in the core still sucks
    Parallel testing
    Make Schwern poorer
    Improve the coverage of the core tests
    test B
    A decent benchmark
    fix tainting bugs
    Dual life everything
    Improving threads::shared
    POSIX memory footprint
    Tasks that need a little sysadmin-type knowledge
    Relocatable perl
    make HTML install work
    compressed man pages
    Add a code coverage target to the Makefile
    Make Config.pm cope with differences between build and installed perl
    make parallel builds work
    linker specification files
    Tasks that need a little C knowledge
    Make it clear from -v if this is the exact official release
    Tidy up global variables
    Ordering of "global" variables.
    bincompat functions
    am I hot or not?
    emulate the per-thread memory pool on Unix
    reduce duplication in sv_setsv_flags
    Tasks that need a knowledge of XS
    IPv6
    shrink GVs, CVs
    merge Perl_sv_2[inpu]v
    UTF8 caching code
    Implicit Latin 1 => Unicode translation
    autovivification
    Unicode in Filenames
    Unicode in %ENV
    use less 'memory'
    Re-implement :unique in a way that is actually thread-safe
    Make tainting consistent
    readpipe(LIST)
    Tasks that need a knowledge of the interpreter
    lexical pragmas
    Attach/detach debugger from running program
    Constant folding
    LVALUE functions for lists
    LVALUE functions in the debugger
    _ prototype character
    state variables
    @INC source filter to Filter::Simple
    regexp optimiser optional
    UNITCHECK
    optional optimizer
    You WANT *how* many
    lexical aliases
    entersub XS vs Perl
    Self ties
    Optimize away @_
    What hooks would assertions need?
    Big projects
    make ithreads more robust
    iCOW
    (?{...}) closures in regexps
    A re-entrant regexp engine

    perldoc - Look up Perl documentation in Pod format.

    SYNOPSIS
    DESCRIPTION
    OPTIONS

    -h, -v, -t, -u, -m module, -l, -F, -f perlfunc, -q perlfaq-search-regexp, -T, -d destination-filename, -o output-formatname, -M module-name, -w option:value or -w option, -X, PageName|ModuleName|ProgramName, -n some-formatter, -r, -i, -V

    SECURITY
    ENVIRONMENT
    AUTHOR

    perlhist - the Perl history records

    DESCRIPTION
    INTRODUCTION
    THE KEEPERS OF THE PUMPKIN
    PUMPKIN?
    THE RECORDS
    SELECTED RELEASE SIZES
    SELECTED PATCH SIZES
    THE KEEPERS OF THE RECORDS

    perldelta - what is new for perl v5.8.8

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata
    Utility Changes
    New Documentation
    Performance Enhancements
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    New Tests
    Known Problems
    Platform Specific Problems
    Reporting Bugs
    SEE ALSO

    perl588delta, perldelta - what is new for perl v5.8.8

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata
    Utility Changes
    New Documentation
    Performance Enhancements
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    New Tests
    Known Problems
    Platform Specific Problems
    Reporting Bugs
    SEE ALSO

    perl587delta, perldelta - what is new for perl v5.8.7

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Unicode Character Database 4.1.0
    suidperl less insecure
    Optional site customization script
    Config.pm is now much smaller.
    Modules and Pragmata
    Utility Changes
    find2perl enhancements
    Performance Enhancements
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    Known Problems
    Platform Specific Problems
    Reporting Bugs
    SEE ALSO

    perl586delta - what is new for perl v5.8.6

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata
    Utility Changes
    Performance Enhancements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    New Tests
    Reporting Bugs
    SEE ALSO

    perl585delta - what is new for perl v5.8.5

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata
    Utility Changes
    Perl's debugger
    h2ph
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    Known Problems
    Platform Specific Problems
    Reporting Bugs
    SEE ALSO

    perl584delta - what is new for perl v5.8.4

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Malloc wrapping
    Unicode Character Database 4.0.1
    suidperl less insecure
    format
    Modules and Pragmata
    Updated modules

    Attribute::Handlers, B, Benchmark, CGI, Carp, Cwd, Exporter, File::Find, IO, IPC::Open3, Local::Maketext, Math::BigFloat, Math::BigInt, Math::BigRat, MIME::Base64, ODBM_File, POSIX, Shell, Socket, Storable, Switch, Sys::Syslog, Term::ANSIColor, Time::HiRes, Unicode::UCD, Win32, base, open, threads, utf8

    Performance Enhancements
    Utility Changes
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    Future Directions
    Platform Specific Problems
    Reporting Bugs
    SEE ALSO

    perl583delta - what is new for perl v5.8.3

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata

    CGI, Cwd, Digest, Digest::MD5, Encode, File::Spec, FindBin, List::Util, Math::BigInt, PodParser, Pod::Perldoc, POSIX, Unicode::Collate, Unicode::Normalize, Test::Harness, threads::shared

    Utility Changes
    New Documentation
    Installation and Configuration Improvements
    Selected Bug Fixes
    New or Changed Diagnostics
    Changed Internals
    Configuration and Building
    Platform Specific Problems
    Known Problems
    Future Directions
    Obituary
    Reporting Bugs
    SEE ALSO

    perl582delta - what is new for perl v5.8.2

    DESCRIPTION
    Incompatible Changes
    Core Enhancements
    Hash Randomisation
    Threading
    Modules and Pragmata
    Updated Modules And Pragmata

    Devel::PPPort, Digest::MD5, I18N::LangTags, libnet, MIME::Base64,
Pod::Perldoc, strict, Tie::Hash, Time::HiRes, Unicode::Collate,
Unicode::Normalize, UNIVERSAL

    Selected Bug Fixes
    Changed Internals
    Platform Specific Problems
    Future Directions
    Reporting Bugs
    SEE ALSO

    perl581delta - what is new for perl v5.8.1

    DESCRIPTION
    Incompatible Changes
    Hash Randomisation
    UTF-8 On Filehandles No Longer Activated By Locale
    Single-number v-strings are no longer v-strings before "=>"
    (Win32) The -C Switch Has Been Repurposed
    (Win32) The /d Switch Of cmd.exe
    Core Enhancements
    UTF-8 no longer default under UTF-8 locales
    Unsafe signals again available
    Tied Arrays with Negative Array Indices
    local ${$x}
    Unicode Character Database 4.0.0
    Deprecation Warnings
    Miscellaneous Enhancements
    Modules and Pragmata
    Updated Modules And Pragmata

    base, B::Bytecode, B::Concise, B::Deparse, Benchmark, ByteLoader, bytes,
CGI, charnames, CPAN, Data::Dumper, DB_File, Devel::PPPort, Digest::MD5,
Encode, fields, libnet, Math::BigInt, MIME::Base64, NEXT, Net::Ping,
PerlIO::scalar, podlators, Pod::LaTeX, PodParsers, Pod::Perldoc,
Scalar::Util, Storable, strict, Term::ANSIcolor, Test::Harness, Test::More,
Test::Simple, Text::Balanced, Time::HiRes, threads, threads::shared,
Unicode::Collate, Unicode::Normalize, Win32::GetFolderPath,
Win32::GetOSVersion

    Utility Changes
    New Documentation
    Installation and Configuration Improvements
    Platform-specific enhancements
    Selected Bug Fixes
    Closures, eval and lexicals
    Generic fixes
    Platform-specific fixes
    New or Changed Diagnostics
    Changed "A thread exited while %d threads were running"
    Removed "Attempt to clear a restricted hash"
    New "Illegal declaration of anonymous subroutine"
    Changed "Invalid range "%s" in transliteration operator"
    New "Missing control char name in \c"
    New "Newline in left-justified string for %s"
    New "Possible precedence problem on bitwise %c operator"
    New "Pseudo-hashes are deprecated"
    New "read() on %s filehandle %s"
    New "5.005 threads are deprecated"
    New "Tied variable freed while still in use"
    New "To%s: illegal mapping '%s'"
    New "Use of freed value in iteration"
    Changed Internals
    New Tests
    Known Problems
    Tied hashes in scalar context
    Net::Ping 450_service and 510_ping_udp failures
    B::C
    Platform Specific Problems
    EBCDIC Platforms
    Cygwin 1.5 problems
    HP-UX: HP cc warnings about sendfile and sendpath
    IRIX: t/uni/tr_7jis.t falsely failing
    Mac OS X: no usemymalloc
    Tru64: No threaded builds with GNU cc (gcc)
    Win32: sysopen, sysread, syswrite
    Future Directions
    Reporting Bugs
    SEE ALSO

    perl58delta - what is new for perl v5.8.0

    DESCRIPTION
    Highlights In 5.8.0
    Incompatible Changes
    Binary Incompatibility
  • -bit platforms and malloc
    AIX Dynaloading
    Attributes for my variables now handled at run-time
    Socket Extension Dynamic in VMS
    IEEE-format Floating Point Default on OpenVMS Alpha
    New Unicode Semantics (no more use utf8, almost)
    New Unicode Properties
    REF(...) Instead Of SCALAR(...)
    pack/unpack D/F recycled
    glob() now returns filenames in alphabetical order
    Deprecations
    • Core Enhancements
    Unicode Overhaul
    PerlIO is Now The Default
    ithreads
    Restricted Hashes
    Safe Signals
    Understanding of Numbers
    Arrays now always interpolate into double-quoted strings [561]
    Miscellaneous Changes
    Modules and Pragmata
    New Modules and Pragmata
    Updated And Improved Modules and Pragmata
    Utility Changes
    New Documentation
    Performance Enhancements
    Installation and Configuration Improvements
    Generic Improvements
    New Or Improved Platforms
    Selected Bug Fixes
    Platform Specific Changes and Fixes
    New or Changed Diagnostics
    Changed Internals
    Security Vulnerability Closed [561]
    New Tests
    Known Problems
    The Compiler Suite Is Still Very Experimental
    Localising Tied Arrays and Hashes Is Broken
    Building Extensions Can Fail Because Of Largefiles
    Modifying $_ Inside for(..)
    mod_perl 1.26 Doesn't Build With Threaded Perl
    lib/ftmp-security tests warn 'system possibly insecure'
    libwww-perl (LWP) fails base/date #51
    PDL failing some tests
    Perl_get_sv
    Self-tying Problems
    ext/threads/t/libc
    Failure of Thread (5.005-style) tests
    Timing problems
    Tied/Magical Array/Hash Elements Do Not Autovivify
    Unicode in package/class and subroutine names does not work
    Platform Specific Problems
    AIX
    Alpha systems with old gccs fail several tests
    AmigaOS
    BeOS
    Cygwin "unable to remap"
    Cygwin ndbm tests fail on FAT
    DJGPP Failures
    FreeBSD built with ithreads coredumps reading large directories
    FreeBSD Failing locale Test 117 For ISO 8859-15 Locales
    IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5
    HP-UX lib/posix Subtest 9 Fails When LP64-Configured
    Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint
    Linux With Sfio Fails op/misc Test 48
    Mac OS X
    Mac OS X dyld undefined symbols
    OS/2 Test Failures
    op/sprintf tests 91, 129, and 130
    SCO
    Solaris 2.5
    Solaris x86 Fails Tests With -Duse64bitint
    SUPER-UX (NEC SX)
    Term::ReadKey not working on Win32
    UNICOS/mk
    UTS
    VOS (Stratus)
    VMS
    Win32
    XML::Parser not working
    z/OS (OS/390)
    Unicode Support on EBCDIC Still Spotty
    Seen In Perl 5.7 But Gone Now
    Reporting Bugs
    SEE ALSO
    HISTORY

    perl573delta - what's new for perl v5.7.3

    DESCRIPTION
    Changes
    Reporting Bugs
    SEE ALSO
    HISTORY

    perl572delta - what's new for perl v5.7.2

    DESCRIPTION
    Security Vulnerability Closed
    Incompatible Changes
    1. -bit platforms and malloc
      AIX Dynaloading
      Socket Extension Dynamic in VMS
      Different Definition of the Unicode Character Classes \p{In...}
      Deprecations
    Core Enhancements
    Modules and Pragmata
    New Modules and Distributions
    Updated And Improved Modules and Pragmata
    Utility Changes
    New Documentation
    Installation and Configuration Improvements
    New Or Improved Platforms
    Generic Improvements
    Selected Bug Fixes
    Platform Specific Changes and Fixes
    New or Changed Diagnostics
    Source Code Enhancements
    MAGIC constants
    Better commented code
    Regex pre-/post-compilation items matched up
    gcc -Wall
    New Tests
    Known Problems
    AIX
    Amiga Perl Invoking Mystery
    lib/ftmp-security tests warn 'system possibly insecure'
    Cygwin intermittent failures of lib/Memoize/t/expire_file 11 and 12
    HP-UX lib/io_multihomed Fails When LP64-Configured
    HP-UX lib/posix Subtest 9 Fails When LP64-Configured
    Linux With Sfio Fails op/misc Test 48
    OS/390
    op/sprintf tests 129 and 130
    Failure of Thread tests
    UNICOS
    UTS
    VMS
    Win32
    Localising a Tied Variable Leaks Memory
    Self-tying of Arrays and Hashes Is Forbidden
    Variable Attributes are not Currently Usable for Tieing
    Building Extensions Can Fail Because Of Largefiles
    The Compiler Suite Is Still Experimental
    The Long Double Support is Still Experimental
    Reporting Bugs
    SEE ALSO
    HISTORY

    perl571delta - what's new for perl v5.7.1

    DESCRIPTION
    Security Vulnerability Closed
    Incompatible Changes
    Core Enhancements
    AUTOLOAD Is Now Lvaluable
    PerlIO is Now The Default
    Signals Are Now Safe
    Modules and Pragmata
    New Modules
    Updated And Improved Modules and Pragmata
    Performance Enhancements
    Utility Changes
    New Documentation
    perlclib
    perliol
    README.aix
    README.bs2000
    README.macos
    README.mpeix
    README.solaris
    README.vos
    Porting/repository.pod
    Installation and Configuration Improvements
    New Or Improved Platforms
    Generic Improvements

    d_cmsghdr, d_fcntl_can_lock, d_fsync, d_getitimer, d_getpagsz, d_msghdr_s, need_va_copy, d_readv, d_recvmsg, d_sendmsg, sig_size, d_sockatmark, d_strtoq, d_u32align, d_ualarm, d_usleep

    Selected Bug Fixes
    Platform Specific Changes and Fixes
    New or Changed Diagnostics
    Changed Internals
    New Tests
    Known Problems
    AIX vac 5.0.0.0 May Produce Buggy Code For Perl
    lib/ftmp-security tests warn 'system possibly insecure'
    lib/io_multihomed Fails In LP64-Configured HP-UX
    Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
    lib/b test 19
    Linux With Sfio Fails op/misc Test 48
    sigaction test 13 in VMS
    sprintf tests 129 and 130
    Failure of Thread tests
    Localising a Tied Variable Leaks Memory
    Self-tying of Arrays and Hashes Is Forbidden
    Building Extensions Can Fail Because Of Largefiles
    The Compiler Suite Is Still Experimental
    Reporting Bugs
    SEE ALSO
    HISTORY

    perl570delta - what's new for perl v5.7.0

    DESCRIPTION
    Security Vulnerability Closed
    Incompatible Changes
    Core Enhancements
    Modules and Pragmata
    New Modules
    Updated And Improved Modules and Pragmata
    Utility Changes
    New Documentation
    Performance Enhancements
    Installation and Configuration Improvements
    Generic Improvements
    Selected Bug Fixes
    Platform Specific Changes and Fixes
    New or Changed Diagnostics
    Changed Internals
    Known Problems
    Unicode Support Still Far From Perfect
    EBCDIC Still A Lost Platform
    Building Extensions Can Fail Because Of Largefiles
    ftmp-security tests warn 'system possibly insecure'
    Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
    Long Doubles Still Don't Work In Solaris
    Linux With Sfio Fails op/misc Test 48
    Storable tests fail in some platforms
    Threads Are Still Experimental
    The Compiler Suite Is Still Experimental
    Reporting Bugs
    SEE ALSO
    HISTORY

    perl561delta - what's new for perl v5.6.x

    DESCRIPTION
    Summary of changes between 5.6.0 and 5.6.1
    Security Issues
    Core bug fixes

    UNIVERSAL::isa(), Memory leaks, Numeric conversions, qw(a\\b), caller(), Bugs in regular expressions, "slurp" mode, Autovivification of symbolic references to special variables, Lexical warnings, Spurious warnings and errors, glob(), Tainting, sort(), #line directives, Subroutine prototypes, map(), Debugger, PERL5OPT, chop(), Unicode support, 64-bit support, Compiler, Lvalue subroutines, IO::Socket, File::Find, xsubpp, no Module;, Tests

    Core features
    Configuration issues
    Documentation
    Bundled modules

    B::Concise, File::Temp, Pod::LaTeX, Pod::Text::Overstrike, CGI, CPAN,
Class::Struct, DB_File, Devel::Peek, File::Find, Getopt::Long, IO::Poll,
IPC::Open3, Math::BigFloat, Math::Complex, Net::Ping, Opcode, Pod::Parser,
Pod::Text, SDBM_File, Sys::Syslog, Tie::RefHash, Tie::SubstrHash

    Platform-specific improvements

    NCR MP-RAS, NonStop-UX

    Core Enhancements
    Interpreter cloning, threads, and concurrency
    Lexically scoped warning categories
    Unicode and UTF-8 support
    Support for interpolating named characters
    "our" declarations
    Support for strings represented as a vector of ordinals
    Improved Perl version numbering system
    New syntax for declaring subroutine attributes
    File and directory handles can be autovivified
    open() with more than two arguments
  • -bit support
    Large file support
    Long doubles
    "more bits"
    Enhanced support for sort() subroutines
    sort $coderef @foo allowed
    File globbing implemented internally
    Support for CHECK blocks
    POSIX character class syntax [: :] supported
    Better pseudo-random number generator
    Improved qw// operator
    Better worst-case behavior of hashes
    pack() format 'Z' supported
    pack() format modifier '!' supported
    pack() and unpack() support counted strings
    Comments in pack() templates
    Weak references
    Binary numbers supported
    Lvalue subroutines
    Some arrows may be omitted in calls through references
    Boolean assignment operators are legal lvalues
    exists() is supported on subroutine names
    exists() and delete() are supported on array elements
    Pseudo-hashes work better
    Automatic flushing of output buffers
    Better diagnostics on meaningless filehandle operations
    Where possible, buffered data discarded from duped input filehandle
    eof() has the same old magic as <>
    binmode() can be used to set :crlf and :raw modes
    -T filetest recognizes UTF-8 encoded files as "text"
    system(), backticks and pipe open now reflect exec() failure
    Improved diagnostics
    Diagnostics follow STDERR
    More consistent close-on-exec behavior
    syswrite() ease-of-use
    Better syntax checks on parenthesized unary operators
    Bit operators support full native integer width
    Improved security features
    More functional bareword prototype (*)
    require and do may be overridden
    $^X variables may now have names longer than one character
    New variable $^C reflects -c switch
    New variable $^V contains Perl version as a string
    Optional Y2K warnings
    Arrays now always interpolate into double-quoted strings
    @- and @+ provide starting/ending offsets of regex submatches
    • Modules and Pragmata
    Modules

    attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters

    Pragmata
    Utility Changes
    dprofpp
    find2perl
    h2xs
    perlcc
    perldoc
    The Perl Debugger
    Improved Documentation

    perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod, perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod, perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod, perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod

    Performance enhancements
    Simple sort() using { $a <=> $b } and the like are optimized
    Optimized assignments to lexical variables
    Faster subroutine calls
    delete(), each(), values() and hash iteration are faster
    Installation and Configuration Improvements
    -Dusethreads means something different
    New Configure flags
    Threadedness and 64-bitness now more daring
    Long Doubles
    -Dusemorebits
    -Duselargefiles
    installusrbinperl
    SOCKS support
    -A flag
    Enhanced Installation Directories
    gcc automatically tried if 'cc' does not seem to be working
    Platform specific changes
    Supported platforms
    DOS
    OS390 (OpenEdition MVS)
    VMS
    Win32
    Significant bug fixes
    <HANDLE> on empty files
    eval '...' improvements
    All compilation errors are true errors
    Implicitly closed filehandles are safer
    Behavior of list slices is more consistent
    (\$) prototype and $foo{a}
    goto &sub and AUTOLOAD
    -bareword allowed under use integer
    Failures in DESTROY()
    Locale bugs fixed
    Memory leaks
    Spurious subroutine stubs after failed subroutine calls
    Taint failures under -U
    END blocks and the -c switch
    Potential to leak DATA filehandles
    New or Changed Diagnostics

    "%s" variable %s masks earlier declaration in same %s, "my sub" not yet implemented, "our" variable %s redeclared, '!' allowed only after types %s, / cannot take a count, / must be followed by a, A or Z, / must be followed by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape \\%c passed through, /%s/: Unrecognized escape \\%c in character class passed through, /%s/ should probably be written as "%s", %s() called too early to check prototype, %s argument is not a HASH or ARRAY element, %s argument is not a HASH or ARRAY element or slice, %s argument is not a subroutine name, %s package attribute may clash with future reserved word: %s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled substitution pattern, Bad realloc() ignored, Bareword found in conditional, Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check filesystem of script "%s", Can't declare class for non-scalar %s in "%s", Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default, Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't weaken a nonreference, Character class [:%s:] unknown, Character class syntax [%s] belongs inside character classes, Constant is not %s reference, constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated, defined(%hash) is deprecated, Did not produce a valid header, (Did you mean "local" instead of "our"?), Document contains no data, entering effective %s failed, false [] range "%s" in regexp, Filehandle %s opened only for output, flock() on closed filehandle %s, Global symbol "%s" requires explicit package name, Hexadecimal number > 0xffffffff non-portable, Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter: |%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal number of bits in vec, Integer overflow in %s number, Invalid %s attribute: %s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid separator character %s in attribute list, Invalid separator character %s in subroutine attribute list, leaving effective %s failed, Lvalue subs returning %s not implemented yet, Method %s not permitted, Missing %sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub", No %s specified for -%c, No package name allowed for variable %s in "our", No space allowed after -%c, no UTC offset information; assuming local time is UTC, Octal number > 037777777777 non-portable, panic: del_backref, panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing around "%s" list, Possible unintended interpolation of %s in string, Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead, Premature end of script headers, Repeat count in pack overflows, Repeat count in unpack overflows, realloc() of freed memory ignored, Reference is already weak, setpgrp can't take arguments, Strange *+?{} on zero-length expression, switching effective %s is not implemented, This Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL environ elements (%s=%s), Too late to run %s block, Unknown open() mode '%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized escape \\%c passed through, Unterminated attribute parameter in attribute list, Unterminated attribute list, Unterminated attribute parameter in subroutine attribute list, Unterminated subroutine attribute list, Value of CLI symbol "%s" too long, Version number must be a constant number

    New tests
    Incompatible Changes
    Perl Source Incompatibilities

    CHECK is a new keyword, Treatment of list slices of undef has changed, Format of $English::PERL_VERSION is different, Literals of the form 1.2.3 parse differently, Possibly changed pseudo-random number generator, Hashing function for hash keys has changed, undef fails on read only values, Close-on-exec bit may be set on pipe and socket handles, Writing "$$1" to mean "${$}1" is unsupported, delete(), each(), values() and \(%h), vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic output has changed, %@ has been removed, Parenthesized not() behaves like a list operator, Semantics of bareword prototype (*) have changed, Semantics of bit operators may have changed on 64-bit platforms, More builtins taint their results

    C Source Incompatibilities

    PERL_POLLUTE, PERL_IMPLICIT_CONTEXT, PERL_POLLUTE_MALLOC

    Compatible C Source API Changes

    PATCHLEVEL is now PERL_VERSION

    Binary Incompatibilities
    Known Problems
    Localizing a tied hash element may leak memory
    Known test failures
    EBCDIC platforms not fully supported
    UNICOS/mk CC failures during Configure run
    Arrow operator and arrays
    Experimental features

    Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The pseudo-hash data type, The Compiler suite, Internal implementation of file globbing, The DB module, The regular expression code constructs:

    Obsolete Diagnostics

    Character class syntax [: :] is reserved for future extensions, Ill-formed logical name |%s| in prime_env_iter, In string, @%s now must be written as \@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated

    Reporting Bugs
    SEE ALSO
    HISTORY

    perl56delta - what's new for perl v5.6.0

    DESCRIPTION
    Core Enhancements
    Interpreter cloning, threads, and concurrency
    Lexically scoped warning categories
    Unicode and UTF-8 support
    Support for interpolating named characters
    "our" declarations
    Support for strings represented as a vector of ordinals
    Improved Perl version numbering system
    New syntax for declaring subroutine attributes
    File and directory handles can be autovivified
    open() with more than two arguments
  • -bit support
    Large file support
    Long doubles
    "more bits"
    Enhanced support for sort() subroutines
    sort $coderef @foo allowed
    File globbing implemented internally
    Support for CHECK blocks
    POSIX character class syntax [: :] supported
    Better pseudo-random number generator
    Improved qw// operator
    Better worst-case behavior of hashes
    pack() format 'Z' supported
    pack() format modifier '!' supported
    pack() and unpack() support counted strings
    Comments in pack() templates
    Weak references
    Binary numbers supported
    Lvalue subroutines
    Some arrows may be omitted in calls through references
    Boolean assignment operators are legal lvalues
    exists() is supported on subroutine names
    exists() and delete() are supported on array elements
    Pseudo-hashes work better
    Automatic flushing of output buffers
    Better diagnostics on meaningless filehandle operations
    Where possible, buffered data discarded from duped input filehandle
    eof() has the same old magic as <>
    binmode() can be used to set :crlf and :raw modes
    -T filetest recognizes UTF-8 encoded files as "text"
    system(), backticks and pipe open now reflect exec() failure
    Improved diagnostics
    Diagnostics follow STDERR
    More consistent close-on-exec behavior
    syswrite() ease-of-use
    Better syntax checks on parenthesized unary operators
    Bit operators support full native integer width
    Improved security features
    More functional bareword prototype (*)
    require and do may be overridden
    $^X variables may now have names longer than one character
    New variable $^C reflects -c switch
    New variable $^V contains Perl version as a string
    Optional Y2K warnings
    Arrays now always interpolate into double-quoted strings
    @- and @+ provide starting/ending offsets of regex matches
    • Modules and Pragmata
    Modules

    attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters

    Pragmata
    Utility Changes
    dprofpp
    find2perl
    h2xs
    perlcc
    perldoc
    The Perl Debugger
    Improved Documentation

    perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod, perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod, perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod, perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod

    Performance enhancements
    Simple sort() using { $a <=> $b } and the like are optimized
    Optimized assignments to lexical variables
    Faster subroutine calls
    delete(), each(), values() and hash iteration are faster
    Installation and Configuration Improvements
    -Dusethreads means something different
    New Configure flags
    Threadedness and 64-bitness now more daring
    Long Doubles
    -Dusemorebits
    -Duselargefiles
    installusrbinperl
    SOCKS support
    -A flag
    Enhanced Installation Directories
    Platform specific changes
    Supported platforms
    DOS
    OS390 (OpenEdition MVS)
    VMS
    Win32
    Significant bug fixes
    <HANDLE> on empty files
    eval '...' improvements
    All compilation errors are true errors
    Implicitly closed filehandles are safer
    Behavior of list slices is more consistent
    (\$) prototype and $foo{a}
    goto &sub and AUTOLOAD
    -bareword allowed under use integer
    Failures in DESTROY()
    Locale bugs fixed
    Memory leaks
    Spurious subroutine stubs after failed subroutine calls
    Taint failures under -U
    END blocks and the -c switch
    Potential to leak DATA filehandles
    New or Changed Diagnostics

    "%s" variable %s masks earlier declaration in same %s, "my sub" not yet implemented, "our" variable %s redeclared, '!' allowed only after types %s, / cannot take a count, / must be followed by a, A or Z, / must be followed by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape \\%c passed through, /%s/: Unrecognized escape \\%c in character class passed through, /%s/ should probably be written as "%s", %s() called too early to check prototype, %s argument is not a HASH or ARRAY element, %s argument is not a HASH or ARRAY element or slice, %s argument is not a subroutine name, %s package attribute may clash with future reserved word: %s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled substitution pattern, Bad realloc() ignored, Bareword found in conditional, Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check filesystem of script "%s", Can't declare class for non-scalar %s in "%s", Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default, Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't weaken a nonreference, Character class [:%s:] unknown, Character class syntax [%s] belongs inside character classes, Constant is not %s reference, constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated, defined(%hash) is deprecated, Did not produce a valid header, (Did you mean "local" instead of "our"?), Document contains no data, entering effective %s failed, false [] range "%s" in regexp, Filehandle %s opened only for output, flock() on closed filehandle %s, Global symbol "%s" requires explicit package name, Hexadecimal number > 0xffffffff non-portable, Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter: |%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal number of bits in vec, Integer overflow in %s number, Invalid %s attribute: %s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid separator character %s in attribute list, Invalid separator character %s in subroutine attribute list, leaving effective %s failed, Lvalue subs returning %s not implemented yet, Method %s not permitted, Missing %sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub", No %s specified for -%c, No package name allowed for variable %s in "our", No space allowed after -%c, no UTC offset information; assuming local time is UTC, Octal number > 037777777777 non-portable, panic: del_backref, panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing around "%s" list, Possible unintended interpolation of %s in string, Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead, Premature end of script headers, Repeat count in pack overflows, Repeat count in unpack overflows, realloc() of freed memory ignored, Reference is already weak, setpgrp can't take arguments, Strange *+?{} on zero-length expression, switching effective %s is not implemented, This Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL environ elements (%s=%s), Too late to run %s block, Unknown open() mode '%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized escape \\%c passed through, Unterminated attribute parameter in attribute list, Unterminated attribute list, Unterminated attribute parameter in subroutine attribute list, Unterminated subroutine attribute list, Value of CLI symbol "%s" too long, Version number must be a constant number

    New tests
    Incompatible Changes
    Perl Source Incompatibilities

    CHECK is a new keyword, Treatment of list slices of undef has changed, Format of $English::PERL_VERSION is different, Literals of the form 1.2.3 parse differently, Possibly changed pseudo-random number generator, Hashing function for hash keys has changed, undef fails on read only values, Close-on-exec bit may be set on pipe and socket handles, Writing "$$1" to mean "${$}1" is unsupported, delete(), each(), values() and \(%h), vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic output has changed, %@ has been removed, Parenthesized not() behaves like a list operator, Semantics of bareword prototype (*) have changed, Semantics of bit operators may have changed on 64-bit platforms, More builtins taint their results

    C Source Incompatibilities

    PERL_POLLUTE, PERL_IMPLICIT_CONTEXT, PERL_POLLUTE_MALLOC

    Compatible C Source API Changes

    PATCHLEVEL is now PERL_VERSION

    Binary Incompatibilities
    Known Problems
    Thread test failures
    EBCDIC platforms not supported
    In 64-bit HP-UX the lib/io_multihomed test may hang
    NEXTSTEP 3.3 POSIX test failure
    Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc
    UNICOS/mk CC failures during Configure run
    Arrow operator and arrays
    Experimental features

    Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The pseudo-hash data type, The Compiler suite, Internal implementation of file globbing, The DB module, The regular expression code constructs:

    Obsolete Diagnostics

    Character class syntax [: :] is reserved for future extensions, Ill-formed logical name |%s| in prime_env_iter, In string, @%s now must be written as \@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated

    Reporting Bugs
    SEE ALSO
    HISTORY

    perl5005delta - what's new for perl5.005

    DESCRIPTION
    About the new versioning system
    Incompatible Changes
    WARNING: This version is not binary compatible with Perl 5.004.
    Default installation structure has changed
    Perl Source Compatibility
    C Source Compatibility
    Binary Compatibility
    Security fixes may affect compatibility
    Relaxed new mandatory warnings introduced in 5.004
    Licensing
    Core Changes
    Threads
    Compiler
    Regular Expressions

    Many new and improved optimizations, Many bug fixes, New regular expression constructs, New operator for precompiled regular expressions, Other improvements, Incompatible changes

    Improved malloc()
    Quicksort is internally implemented
    Reliable signals
    Reliable stack pointers
    More generous treatment of carriage returns
    Memory leaks
    Better support for multiple interpreters
    Behavior of local() on array and hash elements is now well-defined
    %! is transparently tied to the the Errno manpage module
    Pseudo-hashes are supported
    EXPR foreach EXPR is supported
    Keywords can be globally overridden
    $^E is meaningful on Win32
    foreach (1..1000000) optimized
    Foo:: can be used as implicitly quoted package name
    exists $Foo::{Bar::} tests existence of a package
    Better locale support
    Experimental support for 64-bit platforms
    prototype() returns useful results on builtins
    Extended support for exception handling
    Re-blessing in DESTROY() supported for chaining DESTROY() methods
    All printf format conversions are handled internally
    New INIT keyword
    New lock keyword
    New qr// operator
    our is now a reserved word
    Tied arrays are now fully supported
    Tied handles support is better
  • th argument to substr
    Negative LENGTH argument to splice
    Magic lvalues are now more magical
    <> now reads in records
    • Supported Platforms
    New Platforms
    Changes in existing support
    Modules and Pragmata
    New Modules

    B, Data::Dumper, Dumpvalue, Errno, File::Spec, ExtUtils::Installed, ExtUtils::Packlist, Fatal, IPC::SysV, Test, Tie::Array, Tie::Handle, Thread, attrs, fields, re

    Changes in existing modules

    Benchmark, Carp, CGI, Fcntl, Math::Complex, Math::Trig, POSIX, DB_File, MakeMaker, CPAN, Cwd

    Utility Changes
    Documentation Changes
    New Diagnostics

    Ambiguous call resolved as CORE::%s(), qualify as such or use &, Bad index while coercing array into hash, Bareword "%s" refers to nonexistent package, Can't call method "%s" on an undefined value, Can't check filesystem of script "%s" for nosuid, Can't coerce array into hash, Can't goto subroutine from an eval-string, Can't localize pseudo-hash element, Can't use %%! because Errno.pm is not available, Cannot find an opnumber for "%s", Character class syntax [. .] is reserved for future extensions, Character class syntax [: :] is reserved for future extensions, Character class syntax [= =] is reserved for future extensions, %s: Eval-group in insecure regular expression, %s: Eval-group not allowed, use re 'eval', %s: Eval-group not allowed at run time, Explicit blessing to '' (assuming package main), Illegal hex digit ignored, No such array field, No such field "%s" in variable %s of type %s, Out of memory during ridiculously large request, Range iterator outside integer range, Recursive inheritance detected while looking for method '%s' %s, Reference found where even-sized list expected, Undefined value assigned to typeglob, Use of reserved word "%s" is deprecated, perl: warning: Setting locale failed

    Obsolete Diagnostics

    Can't mktemp(), Can't write to temp file for -e: %s, Cannot open temporary file, regexp too big

    Configuration Changes
    BUGS
    SEE ALSO
    HISTORY

    perl5004delta - what's new for perl5.004

    DESCRIPTION
    Supported Environments
    Core Changes
    List assignment to %ENV works
    Change to "Can't locate Foo.pm in @INC" error
    Compilation option: Binary compatibility with 5.003
    $PERL5OPT environment variable
    Limitations on -M, -m, and -T options
    More precise warnings
    Deprecated: Inherited AUTOLOAD for non-methods
    Previously deprecated %OVERLOAD is no longer usable
    Subroutine arguments created only when they're modified
    Group vector changeable with $)
    Fixed parsing of $$<digit>, &$<digit>, etc.
    Fixed localization of $<digit>, $&, etc.
    No resetting of $. on implicit close
    wantarray may return undef
    eval EXPR determines value of EXPR in scalar context
    Changes to tainting checks

    No glob() or <*>, No spawning if tainted $CDPATH, $ENV, $BASH_ENV, No spawning if tainted $TERM doesn't look like a terminal name

    New Opcode module and revised Safe module
    Embedding improvements
    Internal change: FileHandle class based on IO::* classes
    Internal change: PerlIO abstraction interface
    New and changed syntax

    $coderef->(PARAMS)

    New and changed builtin constants

    __PACKAGE__

    New and changed builtin variables

    $^E, $^H, $^M

    New and changed builtin functions

    delete on slices, flock, printf and sprintf, keys as an lvalue, my() in Control Structures, pack() and unpack(), sysseek(), use VERSION, use Module VERSION LIST, prototype(FUNCTION), srand, $_ as Default, m//gc does not reset search position on failure, m//x ignores whitespace before ?*+{}, nested sub{} closures work now, formats work right on changing lexicals

    New builtin methods

    isa(CLASS), can(METHOD), VERSION( [NEED] )

    TIEHANDLE now supported

    TIEHANDLE classname, LIST, PRINT this, LIST, PRINTF this, LIST, READ this LIST, READLINE this, GETC this, DESTROY this

    Malloc enhancements

    -DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE

    Miscellaneous efficiency enhancements
    Support for More Operating Systems
    Win32
    Plan 9
    QNX
    AmigaOS
    Pragmata

    use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use constant NAME => VALUE, use locale, use ops, use vmsish

    Modules
    Required Updates
    Installation directories
    Module information summary
    Fcntl
    IO
    Math::Complex
    Math::Trig
    DB_File
    Net::Ping
    Object-oriented overrides for builtin operators
    Utility Changes
    pod2html

    Sends converted HTML to standard output

    xsubpp

    void XSUBs now default to returning nothing

    C Language API Changes

    gv_fetchmethod and perl_call_sv, perl_eval_pv, Extended API for manipulating hashes

    Documentation Changes

    the perldelta manpage, the perlfaq manpage, the perllocale manpage, the perltoot manpage, the perlapio manpage, the perlmodlib manpage, the perldebug manpage, the perlsec manpage

    New Diagnostics

    "my" variable %s masks earlier declaration in same scope, %s argument is not a HASH element or slice, Allocation too large: %lx, Allocation too large, Applying %s to %s will act on scalar(%s), Attempt to free nonexistent shared string, Attempt to use reference as lvalue in substr, Bareword "%s" refers to nonexistent package, Can't redefine active sort subroutine %s, Can't use bareword ("%s") as %s ref while "strict refs" in use, Cannot resolve method `%s' overloading `%s' in package `%s', Constant subroutine %s redefined, Constant subroutine %s undefined, Copy method did not return a reference, Died, Exiting pseudo-block via %s, Identifier too long, Illegal character %s (carriage return), Illegal switch in PERL5OPT: %s, Integer overflow in hex number, Integer overflow in octal number, internal error: glob failed, Invalid conversion in %s: "%s", Invalid type in pack: '%s', Invalid type in unpack: '%s', Name "%s::%s" used only once: possible typo, Null picture in formline, Offset outside string, Out of memory!, Out of memory during request for %s, panic: frexp, Possible attempt to put comments in qw() list, Possible attempt to separate words with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found while resolving method `%s' overloading `%s' in %s, Too late for "-T" option, untie attempted while %d inner references still exist, Unrecognized character %s, Unsupported function fork, Use of "$$<digit>" to mean "${$}<digit>" is deprecated, Value of %s can be "0"; test with defined(), Variable "%s" may be unavailable, Variable "%s" will not stay shared, Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter, Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too long, Process terminated by SIG%s

    BUGS
    SEE ALSO
    HISTORY

    perlartistic - the Perl Artistic License

    SYNOPSIS
    DESCRIPTION
    The "Artistic License"
    Preamble
    Definitions

    "Package", "Standard Version", "Copyright Holder", "You", "Reasonable copying fee", "Freely Available"

    Conditions

    a), b), c), d), a), b), c), d)

    perlgpl - the GNU General Public License, version 2

    SYNOPSIS
    DESCRIPTION
    GNU GENERAL PUBLIC LICENSE

    perlaix, README.aix - Perl version 5 on IBM Unix (AIX) systems

    DESCRIPTION
    Compiling Perl 5 on AIX
    OS level
    Building Dynamic Extensions on AIX
    The IBM ANSI C Compiler
    The usenm option
    Using GNU's gcc for building perl
    Using Large Files with Perl
    Threaded Perl
  • -bit Perl
    AIX 4.2 and extensions using C++ with statics
    • AUTHOR
    DATE

    perlamiga - Perl under Amiga OS

    NOTE
    SYNOPSIS
    DESCRIPTION
    Prerequisites for Compiling Perl on AmigaOS

    Unix emulation for AmigaOS: ixemul.library, Version of Amiga OS

    Starting Perl programs under AmigaOS
    Shortcomings of Perl under AmigaOS
    INSTALLATION
    Accessing documentation
    Manpages for Perl on AmigaOS
    Perl HTML Documentation on AmigaOS
    Perl GNU Info Files on AmigaOS
    Perl LaTeX Documentation on AmigaOS
    BUILDING PERL ON AMIGAOS
    Build Prerequisites for Perl on AmigaOS
    Getting the Perl Source for AmigaOS
    Making Perl on AmigaOS
    Testing Perl on AmigaOS
    Installing the built Perl on AmigaOS
    PERL 5.8.0 BROKEN IN AMIGAOS
    AUTHORS
    SEE ALSO

    perlapollo, README.apollo - Perl version 5 on Apollo DomainOS

    DESCRIPTION
    AUTHOR

    perlbeos, README.beos - Perl version 5.8+ on BeOS

    DESCRIPTION
    BUILD AND INSTALL
    Requirements
    Configure
    Build
    Install
    KNOWN PROBLEMS
    CONTACT

    perlbs2000, README.BS2000 - building and installing Perl for BS2000.

    SYNOPSIS
    DESCRIPTION
    gzip on BS2000
    bison on BS2000
    Unpacking Perl Distribution on BS2000
    Compiling Perl on BS2000
    Testing Perl on BS2000
    Installing Perl on BS2000
    Using Perl in the Posix-Shell of BS2000
    Using Perl in "native" BS2000
    Floating point anomalies on BS2000
    Using PerlIO and different encodings on ASCII and EBCDIC partitions
    AUTHORS
    SEE ALSO
    Mailing list
    HISTORY

    perlce - Perl for WinCE

    DESCRIPTION
    BUILD
    Tools & SDK

    Microsoft Embedded Visual Tools, Microsoft Visual C++, Rainer Keuchel's celib-sources, Rainer Keuchel's console-sources

    Make

    go to ./wince subdirectory, edit file compile.bat, run compile.bat, run
    compile.bat dist

    ACKNOWLEDGEMENTS
    AUTHORS

    perlcygwin, README.cygwin - Perl for Cygwin

    SYNOPSIS
    PREREQUISITES FOR COMPILING PERL ON CYGWIN
    Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
    Cygwin Configuration

    PATH, nroff, Permissions

    CONFIGURE PERL ON CYGWIN
    Stripping Perl Binaries on Cygwin
    Optional Libraries for Perl on Cygwin

    -lcrypt, -lgdbm (use GDBM_File), -ldb (use DB_File), -lcygipc (use IPC::SysV), -lutil

    Configure-time Options for Perl on Cygwin

    -Uusedl, -Uusemymalloc, -Uuseperlio, -Dusemultiplicity, -Duse64bitint, -Duselongdouble, -Dusethreads, -Duselargefiles, -Dmksymlinks

    Suspicious Warnings on Cygwin

    dlsym(), Win9x and d_eofnblk, Compiler/Preprocessor defines

    MAKE ON CYGWIN
    Errors on Cygwin
    ld2 on Cygwin
    TEST ON CYGWIN
    File Permissions on Cygwin
    NDBM_File and ODBM_File do not work on FAT filesystems
    fork() failures in io_* tests
    Specific features of the Cygwin port
    Script Portability on Cygwin

    Pathnames, Text/Binary, PerlIO, .exe, cygwin vs. windows process ids, chown(), Miscellaneous

    Prebuilt methods:

    Cwd::cwd, Cygwin::pid_to_winpid, Cygwin::winpid_to_pid

    INSTALL PERL ON CYGWIN
    MANIFEST ON CYGWIN

    Documentation, Build, Configure, Make, Install, Tests, Compiled Perl Source, Compiled Module Source, Perl Modules/Scripts

    BUGS ON CYGWIN
    AUTHORS
    HISTORY

    perldgux - Perl under DG/UX.

    SYNOPSIS
    DESCRIPTION
    BUILDING PERL ON DG/UX
    Non-threaded Perl on DG/UX
    Threaded Perl on DG/UX
    Testing Perl on DG/UX
    Installing the built perl on DG/UX
    AUTHOR
    SEE ALSO

    perldos - Perl under DOS, W31, W95.

    SYNOPSIS
    DESCRIPTION
    Prerequisites for Compiling Perl on DOS

    DJGPP, Pthreads

    Shortcomings of Perl under DOS
    Building Perl on DOS
    Testing Perl on DOS
    Installation of Perl on DOS
    BUILDING AND INSTALLING MODULES ON DOS
    Building Prerequisites for Perl on DOS
    Unpacking CPAN Modules on DOS
    Building Non-XS Modules on DOS
    Building XS Modules on DOS
    AUTHOR
    SEE ALSO

    perlepoc, README.epoc - Perl for EPOC

    SYNOPSIS
    INTRODUCTION
    INSTALLING PERL ON EPOC
    STARTING PERL ON EPOC
    Editors on Epoc
    Features of Perl on Epoc
    Restrictions of Perl on Epoc
    Compiling Perl 5 on the EPOC cross compiling environment
    SUPPORT STATUS OF PERL ON EPOC
    AUTHOR
    LAST UPDATE

    perlfreebsd, README.freebsd - Perl version 5 on FreeBSD systems

    DESCRIPTION
    FreeBSD core dumps from readdir_r with ithreads
    $^X doesn't always contain a full path in FreeBSD
    Perl will no longer be part of "base FreeBSD"
    AUTHOR

    perlhpux, README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems

    DESCRIPTION
    Using perl as shipped with HP-UX
    Using perl from HP's porting centre
    Compiling Perl 5 on HP-UX
    PA-RISC
    Portability Between PA-RISC Versions
    PA-RISC 1.0
    PA-RISC 1.1
    PA-RISC 2.0
    Itanium Processor Family and HP-UX
    Itanium & Itanium 2
    Building Dynamic Extensions on HP-UX
    The HP ANSI C Compiler
    The GNU C Compiler
    Using Large Files with Perl on HP-UX
    Threaded Perl on HP-UX
  • -bit Perl on HP-UX
    Oracle on HP-UX
    GDBM and Threads on HP-UX
    NFS filesystems and utime(2) on HP-UX
    perl -P and // and HP-UX
    HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
    • nss_delete core dump from op/pwent or op/grent
    AUTHOR
    DATE

    perlhurd, README.hurd - Perl version 5 on Hurd

    DESCRIPTION
    Known Problems with Perl on Hurd
    AUTHOR

    perlirix, README.irix - Perl version 5 on Irix systems

    DESCRIPTION
    Building 32-bit Perl in Irix
    Building 64-bit Perl in Irix
    About Compiler Versions of Irix
    Linker Problems in Irix
    Malloc in Irix
    Building with threads in Irix
    Irix 5.3
    AUTHOR

    perllinux, README.linux - Perl version 5 on Linux systems

    DESCRIPTION
    Experimental Support for Sun Studio Compilers for Linux OS
    AUTHOR

    perlmachten, README.machten - Perl version 5 on Power MachTen systems

    DESCRIPTION
    Perl version 5.8.x and greater not supported
    Compiling Perl 5.6.x on MachTen
    Failures during make test on MachTen

    op/lexassign.t, pragma/warnings.t

    Building external modules on MachTen
    AUTHOR
    DATE

    perlmacos, README.macos - Perl under Mac OS (Classic)

    SYNOPSIS
    DESCRIPTION
    AUTHOR
    DATE

    perlmacosx, README.macosx - Perl under Mac OS X

    SYNOPSIS
    DESCRIPTION
    Installation Prefix
    libperl and Prebinding
    Updating Apple-supplied Perl
  • -bit Perl
    Intel processor support
    Universal binaries
    Known problems
    MacPerl
    Carbon
    Cocoa
    • Starting From Scratch
    AUTHOR
    DATE

    perlmint, README.mint - Perl version 5 on Atari MiNT

    DESCRIPTION
    Known problems with Perl on MiNT
    AUTHOR

    perlmpeix, README.mpeix - Perl/iX for HP e3000 MPE

    SYNOPSIS
    NOTE
    Binary distribution from HP
    What's New in Perl for MPE/iX
    Welcome to Perl/iX
    System Requirements for Perl/iX
    How to Obtain Perl/iX
    Perl/iX Distribution Contents Highlights

    README, INSTALL, LIBSHP3K, PERL, .cpan/, lib/, man/, public_html/feedback.cgi, src/perl-5.6.0-mpe

    How to Compile Perl/iX
     4,  6
    Getting Started with Perl/iX
    MPE/iX Implementation Considerations
    Known Perl/iX Bugs Under Investigation
    Perl/iX To-Do List
    Perl/iX Change History
    AUTHOR

    perlnetware - Perl for NetWare

    DESCRIPTION
    BUILD
    Tools & SDK
    Setup

    SetNWBld.bat, Buildtype.bat

    Make
    Interpreter
    Extensions
    INSTALL
    BUILD NEW EXTENSIONS
    ACKNOWLEDGEMENTS
    AUTHORS
    DATE

    perlopenbsd, README.openbsd - Perl version 5 on OpenBSD systems

    DESCRIPTION
    OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads
    AUTHOR

    perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.

    SYNOPSIS
    DESCRIPTION
    Target
    Other OSes
    Prerequisites

    EMX, RSX, HPFS, pdksh

    Starting Perl programs under OS/2 (and DOS and...)
    Starting OS/2 (and DOS) programs under Perl
    Frequently asked questions
    "It does not work"
    I cannot run external programs
    I cannot embed perl into my program, or use perl.dll from my program.

    Is your program EMX-compiled with -Zmt -Zcrtdll?, Did you use the ExtUtils::Embed manpage?

    `` and pipe-open do not work under DOS.
    Cannot start find.exe "pattern" file
    INSTALLATION
    Automatic binary installation

    PERL_BADLANG, PERL_BADFREE, Config.pm

    Manual binary installation

    Perl VIO and PM executables (dynamically linked), Perl_ VIO executable (statically linked), Executables for Perl utilities, Main Perl library, Additional Perl modules, Tools to compile Perl modules, Manpages for Perl and utilities, Manpages for Perl modules, Source for Perl documentation, Perl manual in .INF format, Pdksh

    Warning
    Accessing documentation
    OS/2 .INF file
    Plain text
    Manpages
    HTML
    GNU info files
    PDF files
    LaTeX docs
    BUILD
    The short story
    Prerequisites
    Getting perl source
    Application of the patches
    Hand-editing
    Making
    Testing

    A lot of bad free, Process terminated by SIGTERM/SIGINT, op/fs.t, op/stat.t

    Installing the built perl
    a.out-style build
    Building a binary distribution
    Building custom .EXE files
    Making executables with a custom collection of statically loaded extensions
    Making executables with a custom search-paths
    Build FAQ
    Some / became \ in pdksh.
    'errno' - unresolved external
    Problems with tr or sed
    Some problem (forget which ;-)
    Library ... not found
    Segfault in make
    op/sprintf test failure
    Specific (mis)features of OS/2 port
    setpriority, getpriority
    system()
    extproc on the first line
    Additional modules:
    Prebuilt methods:

    File::Copy::syscopy, DynaLoader::mod2fname,  Cwd::current_drive(),
 Cwd::sys_chdir(name),  Cwd::change_drive(name),
Cwd::sys_is_absolute(name),	Cwd::sys_is_rooted(name),
Cwd::sys_is_relative(name),	Cwd::sys_cwd(name),
Cwd::sys_abspath(name, dir),  Cwd::extLibpath([type]),
Cwd::extLibpath_set( path [, type ] ),
OS2::Error(do_harderror,do_exception), OS2::Errors2Drive(drive),
OS2::SysInfo(), OS2::BootDrive(), OS2::MorphPM(serve),
OS2::UnMorphPM(serve), OS2::Serve_Messages(force),
OS2::Process_Messages(force [, cnt]), OS2::_control87(new,mask),
OS2::get_control87(), OS2::set_control87_em(new=MCW_EM,mask=MCW_EM),
OS2::DLLname([how [, \&xsub]])

    Prebuilt variables:

    $OS2::emx_rev, $OS2::emx_env, $OS2::os_ver, $OS2::is_aout, $OS2::can_fork, $OS2::nsyserror

    Misfeatures
    Modifications

    popen, tmpnam, tmpfile, ctermid, stat, mkdir, rmdir, flock

    Identifying DLLs
    Centralized management of resources

    HAB, HMQ, Treating errors reported by OS/2 API, CheckOSError(expr), CheckWinError(expr), SaveWinError(expr), SaveCroakWinError(expr,die,name1,name2), WinError_2_Perl_rc, FillWinError, FillOSError(rc), Loading DLLs and ordinals in DLLs

    Perl flavors
    perl.exe
    perl_.exe
    perl__.exe
    perl___.exe
    Why strange names?
    Why dynamic linking?
    Why chimera build?
    ENVIRONMENT
    PERLLIB_PREFIX
    PERL_BADLANG
    PERL_BADFREE
    PERL_SH_DIR
    USE_PERL_FLOCK
    TMP or TEMP
    Evolution
    Text-mode filehandles
    Priorities
    DLL name mangling: pre 5.6.2
    DLL name mangling: 5.6.2 and beyond

    Global DLLs, specific DLLs, BEGINLIBPATH and ENDLIBPATH, . from LIBPATH

    DLL forwarder generation
    Threading
    Calls to external programs
    Memory allocation
    Threads

    COND_WAIT, os2.c

    BUGS
    AUTHOR
    SEE ALSO

    perlos390, README.os390 - building and installing Perl for OS/390 and z/OS

    SYNOPSIS
    DESCRIPTION
    Tools
    Unpacking Perl distribution on OS/390
    Setup and utilities for Perl on OS/390
    Configure Perl on OS/390
    Build, Test, Install Perl on OS/390
    Build Anomalies with Perl on OS/390
    Testing Anomalies with Perl on OS/390
    Installation Anomalies with Perl on OS/390
    Usage Hints for Perl on OS/390
    Floating Point Anomalies with Perl on OS/390
    Modules and Extensions for Perl on OS/390
    AUTHORS
    SEE ALSO
    Mailing list for Perl on OS/390
    HISTORY

    perlos400, README.os400 - Perl version 5 on OS/400

    DESCRIPTION
    Compiling Perl for OS/400 PASE
    Installing Perl in OS/400 PASE
    Using Perl in OS/400 PASE
    Known Problems
    Perl on ILE
    AUTHORS

    perlplan9 - Plan 9-specific documentation for Perl

    DESCRIPTION
    Invoking Perl
    What's in Plan 9 Perl
    What's not in Plan 9 Perl
    Perl5 Functions not currently supported in Plan 9 Perl
    Signals in Plan 9 Perl
    COMPILING AND INSTALLING PERL ON PLAN 9
    Installing Perl Documentation on Plan 9
    BUGS
    Revision date
    AUTHOR

    perlqnx, README.qnx - Perl version 5 on QNX

    DESCRIPTION
    Required Software for Compiling Perl on QNX4

    /bin/sh, ar, nm, cpp, make

    Outstanding Issues with Perl on QNX4
    QNX auxiliary files

    qnx/ar, qnx/cpp

    Outstanding issues with perl under QNX6
    AUTHOR

    perlsolaris, README.solaris - Perl version 5 on Solaris systems

    DESCRIPTION
    Solaris Version Numbers.
    RESOURCES

    Solaris FAQ, Precompiled Binaries, Solaris Documentation

    SETTING UP
    File Extraction Problems on Solaris.
    Compiler and Related Tools on Solaris.
    Environment for Compiling perl on Solaris
    RUN CONFIGURE.
    1. -bit perl on Solaris.
      Threads in perl on Solaris.
      Malloc Issues with perl on Solaris.
    MAKE PROBLEMS.

    Dynamic Loading Problems With GNU as and GNU ld, ld.so.1: ./perl: fatal: relocation error:, dlopen: stub interception failed, #error "No DATAMODEL_NATIVE specified", sh: ar: not found, warning: dead part of constant expression is nonconstant

    MAKE TEST
    op/stat.t test 4 in Solaris
    nss_delete core dump from op/pwent or op/grent
    PREBUILT BINARIES OF PERL FOR SOLARIS.
    RUNTIME ISSUES FOR PERL ON SOLARIS.
    Limits on Numbers of Open Files on Solaris.
    SOLARIS-SPECIFIC MODULES.
    SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
    Proc::ProcessTable on Solaris
    BSD::Resource on Solaris
    Net::SSLeay on Solaris
    SunOS 4.x
    AUTHOR

    perltru64, README.tru64 - Perl version 5 on Tru64 (formerly known as Digital UNIX formerly known as DEC OSF/1) systems

    DESCRIPTION
    Compiling Perl 5 on Tru64
    Using Large Files with Perl on Tru64
    Threaded Perl on Tru64
    Long Doubles on Tru64
    DB_File tests failing on Tru64
  • -bit Perl on Tru64
    Warnings about floating-point overflow when compiling Perl on Tru64
    • Testing Perl on Tru64
    ext/ODBM_File/odbm Test Failing With Static Builds
    Perl Fails Because Of Unresolved Symbol sockatmark
    AUTHOR

    perluts - Perl under UTS

    SYNOPSIS
    DESCRIPTION
    BUILDING PERL ON UTS
    Installing the built perl on UTS
    AUTHOR

    perlvmesa, README.vmesa - building and installing Perl for VM/ESA.

    SYNOPSIS
    DESCRIPTION
    Unpacking Perl Distribution on VM/ESA
    Setup Perl and utilities on VM/ESA
    Configure Perl on VM/ESA
    Testing Anomalies of Perl on VM/ESA
    Usage Hints for Perl on VM/ESA
    AUTHORS
    SEE ALSO
    Mailing list for Perl on VM/ESA

    perlvms - VMS-specific documentation for Perl

    DESCRIPTION
    Installation
    Organization of Perl Images
    Core Images
    Perl Extensions
    Installing static extensions
    Installing dynamic extensions
    File specifications
    Syntax
    Wildcard expansion
    Pipes
    PERL5LIB and PERLLIB
    Command line
    I/O redirection and backgrounding
    Command line switches

    -i, -S, -u

    Perl functions

    File tests, backticks, binmode FILEHANDLE, crypt PLAINTEXT, USER, dump, exec LIST, fork, getpwent, getpwnam, getpwuid, gmtime, kill, qx//, select (system call), stat EXPR, system LIST, time, times, unlink LIST, utime LIST, waitpid PID,FLAGS

    Perl variables

    %ENV, CRTL_ENV, CLISYM_[LOCAL], Any other string, $!, $^E, $?, $|

    Standard modules with VMS-specific differences
    SDBM_File
    Revision date
    AUTHOR

    perlvos, README.vos - Perl for Stratus VOS

    SYNOPSIS
    Multiple methods to build perl for VOS
    Stratus POSIX Support
    INSTALLING PERL IN VOS
    Compiling Perl 5 on VOS
    Installing Perl 5 on VOS
    USING PERL IN VOS
    Unimplemented Features of Perl on VOS
    Restrictions of Perl on VOS
    Handling of underflow and overflow
    TEST STATUS
    SUPPORT STATUS
    AUTHOR
    LAST UPDATE

    perlwin32 - Perl under Windows

    SYNOPSIS
    DESCRIPTION
    Setting Up Perl on Win32

    Make, Command Shell, Borland C++, Microsoft Visual C++, Microsoft Visual C++ Toolkit 2003, Microsoft Platform SDK 64-bit Compiler, MinGW release 3 with gcc, MinGW release 1 with gcc

    Building
    Testing Perl on Win32
    Installation of Perl on Win32
    Usage Hints for Perl on Win32

    Environment Variables, File Globbing, Using perl from the command line, Building Extensions, Command-line Wildcard Expansion, Win32 Specific Extensions, Notes on 64-bit Windows

    Running Perl Scripts
    Miscellaneous Things
    BUGS AND CAVEATS
    ACKNOWLEDGEMENTS
    AUTHORS

    Gary Ng <71564.1743@CompuServe.COM>, Gurusamy Sarathy <gsar@activestate.com>, Nick Ing-Simmons <nick@ing-simmons.net>, Jan Dubois <jand@activestate.com>, Steve Hay <steve.hay@uk.radan.com>

    SEE ALSO
    HISTORY

    PRAGMA DOCUMENTATION

    attrs - set/get attributes of a subroutine (deprecated)

    SYNOPSIS
    DESCRIPTION

    method, locked

    re - Perl pragma to alter regular expression behaviour

    SYNOPSIS
    DESCRIPTION

    threadshared::shared, threads::shared - Perl extension for sharing data structures between threads

    SYNOPSIS
    DESCRIPTION
    EXPORT
    FUNCTIONS

    share VARIABLE, lock VARIABLE, cond_wait VARIABLE, cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE, ABS_TIMEOUT, cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal VARIABLE, cond_broadcast VARIABLE

    NOTES
    BUGS
    AUTHOR
    SEE ALSO

    threads - Perl extension allowing use of interpreter based threads from perl

    SYNOPSIS
    DESCRIPTION

    $thread = threads->create(function, LIST), $thread->join, $thread->detach,
threads->self, $thread->tid, threads->object( tid ), threads->yield();,
threads->list();, async BLOCK;

    WARNINGS

    A thread exited while %d other threads were still running

    TODO
    BUGS

    Parent-Child threads, tid is I32, Returning objects, Creating threads inside BEGIN blocks, PERL_OLD_SIGNALS are not threadsafe, will not be

    AUTHOR and COPYRIGHT
    SEE ALSO

    attributes - get/set subroutine or variable attributes

    SYNOPSIS
    DESCRIPTION
    Built-in Attributes

    locked, method, lvalue

    Available Subroutines

    get, reftype

    Package-specific Attribute Handling

    FETCH_type_ATTRIBUTES, MODIFY_type_ATTRIBUTES

    Syntax of Attribute Lists
    EXPORTS
    Default exports
    Available exports
    Export tags defined
    EXAMPLES
    SEE ALSO

    autouse - postpone load of modules until a function is used

    SYNOPSIS
    DESCRIPTION
    WARNING
    AUTHOR
    SEE ALSO

    base - Establish IS-A relationship with base classes at compile time

    SYNOPSIS
    DESCRIPTION
    DIAGNOSTICS

    Base class package "%s" is empty

    HISTORY
    CAVEATS
    SEE ALSO

    bigint - Transparent BigInteger support for Perl

    SYNOPSIS
    DESCRIPTION
    Options

    a or accuracy, p or precision, t or trace, l or lib, v or version

    Math Library
    Internal Format
    Sign
    Methods
    Caveat
    MODULES USED
    EXAMPLES
    LICENSE
    SEE ALSO
    AUTHORS

    bignum - Transparent BigNumber support for Perl

    SYNOPSIS
    DESCRIPTION
    Options

    a or accuracy, p or precision, t or trace, l or lib, v or version

    Methods
    Caveat

    inf(), NaN(), upgrade()

    MATH LIBRARY
    INTERNAL FORMAT
    SIGN
    MODULES USED
    EXAMPLES
    LICENSE
    SEE ALSO
    AUTHORS

    bigrat - Transparent BigNumber/BigRational support for Perl

    SYNOPSIS
    DESCRIPTION
    Modules Used
    Math Library
    Sign
    Methods
    Cavaet
    Options

    a or accuracy, p or precision, t or trace, l or lib, v or version

    EXAMPLES
            perl -Mbigrat -le 'print sqrt(33)'
        perl -Mbigrat -le 'print 2*255'
        perl -Mbigrat -le 'print 4.5+2*255'
        perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
        perl -Mbigrat -le 'print 12->is_odd()';
    LICENSE
    SEE ALSO
    AUTHORS

    blib - Use MakeMaker's uninstalled version of a package

    SYNOPSIS
    DESCRIPTION
    BUGS
    AUTHOR

    bytes - Perl pragma to force byte semantics rather than character semantics

    SYNOPSIS
    DESCRIPTION
    LIMITATIONS
    SEE ALSO

    charnames - define character names for \N{named} string literal escapes

    SYNOPSIS
    DESCRIPTION
    CUSTOM TRANSLATORS
    CUSTOM ALIASES
    Anonymous hashes
    Alias file
    Alias shortcut
    charnames::viacode(code)
    charnames::vianame(name)
    ALIASES
    ILLEGAL CHARACTERS
    BUGS

    constant - Perl pragma to declare constants

    SYNOPSIS
    DESCRIPTION
    NOTES
    List constants
    Defining multiple constants at once
    Magic constants
    TECHNICAL NOTES
    BUGS
    AUTHOR
    COPYRIGHT

    diagnostics, splain - produce verbose warning diagnostics

    SYNOPSIS
    DESCRIPTION
    The diagnostics Pragma
    The splain Program
    EXAMPLES
    INTERNALS
    BUGS
    AUTHOR

    encoding - allows you to write your script in non-ascii or non-utf8

    SYNOPSIS
    ABSTRACT
    Literal Conversions
    PerlIO layers for STD(IN|OUT)
    Implicit upgrading for byte strings
    FEATURES THAT REQUIRE 5.8.1

    "NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle

    USAGE

    use encoding [ENCNAME] ;, use encoding ENCNAME [ STDIN => ENCNAME_IN ...] ;, use encoding ENCNAME Filter=>1;, no encoding;

    The Filter Option
    Filter-related changes at Encode version 1.87
    CAVEATS
    NOT SCOPED
    DO NOT MIX MULTIPLE ENCODINGS
    tr/// with ranges

    Legend of characters above

    EXAMPLE - Greekperl
    KNOWN PROBLEMS

    literals in regex that are longer than 127 bytes, EBCDIC, format

    The Logic of :locale
    HISTORY
    SEE ALSO

    fields - compile-time class fields

    SYNOPSIS
    DESCRIPTION

    new, phash

    SEE ALSO

    filetest - Perl pragma to control the filetest permission operators

    SYNOPSIS
    DESCRIPTION
    subpragma access

    if - use a Perl module if a condition holds

    SYNOPSIS
    DESCRIPTION
    BUGS
    AUTHOR

    integer - Perl pragma to use integer arithmetic instead of floating point

    SYNOPSIS
    DESCRIPTION

    less - perl pragma to request less of something from the compiler

    SYNOPSIS
    DESCRIPTION

    lib - manipulate @INC at compile time

    SYNOPSIS
    DESCRIPTION
    Adding directories to @INC
    Deleting directories from @INC
    Restoring original @INC
    CAVEATS
    NOTES
    SEE ALSO
    AUTHOR

    locale - Perl pragma to use and avoid POSIX locales for built-in operations

    SYNOPSIS
    DESCRIPTION

    open - perl pragma to set default PerlIO layers for input and output

    SYNOPSIS
    DESCRIPTION
    NONPERLIO FUNCTIONALITY
    IMPLEMENTATION DETAILS
    SEE ALSO

    ops - Perl pragma to restrict unsafe operations when compiling

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    overload - Package for overloading Perl operations

    SYNOPSIS
    DESCRIPTION
    Declaration of overloaded functions
    Calling Conventions for Binary Operations

    FALSE, TRUE, undef

    Calling Conventions for Unary Operations
    Calling Conventions for Mutators

    ++ and --, x= and other assignment versions

    Overloadable Operations

    Arithmetic operations, Comparison operations, Bit operations, Increment and decrement, Transcendental functions, Boolean, string and numeric conversion, Iteration, Dereferencing, Special

    Inheritance and overloading

    Strings as values of use overload directive, Overloading of an operation is inherited by derived classes

    SPECIAL SYMBOLS FOR use overload
    Last Resort
    Fallback

    undef, TRUE, defined, but FALSE

    Copy Constructor

    Example

    MAGIC AUTOGENERATION

    Assignment forms of arithmetic operations, Conversion operations, Increment and decrement, abs($a), Unary minus, Negation, Concatenation, Comparison operations, Iterator, Dereferencing, Copy operator

    Losing overloading
    Run-time Overloading
    Public functions

    overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op)

    Overloading constants

    integer, float, binary, q, qr

    IMPLEMENTATION
    Metaphor clash
    Cookbook
    Two-face scalars
    Two-face references
    Symbolic calculator
    Really symbolic calculator
    AUTHOR
    DIAGNOSTICS

    Odd number of arguments for overload::constant, `%s' is not an overloadable type, `%s' is not a code reference

    BUGS

    sigtrap - Perl pragma to enable simple signal handling

    SYNOPSIS
    DESCRIPTION
    OPTIONS
    SIGNAL HANDLERS

    stack-trace, die, handler your-handler

    SIGNAL LISTS

    normal-signals, error-signals, old-interface-signals

    OTHER

    untrapped, any, signal, number

    EXAMPLES

    sort - perl pragma to control sort() behaviour

    SYNOPSIS
    DESCRIPTION
    CAVEATS

    strict - Perl pragma to restrict unsafe constructs

    SYNOPSIS
    DESCRIPTION

    strict refs, strict vars, strict subs

    HISTORY

    subs - Perl pragma to predeclare sub names

    SYNOPSIS
    DESCRIPTION

    threadshared, threads::shared - Perl extension for sharing data structures between threads

    SYNOPSIS
    DESCRIPTION
    EXPORT
    FUNCTIONS

    share VARIABLE, lock VARIABLE, cond_wait VARIABLE, cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE, ABS_TIMEOUT, cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal VARIABLE, cond_broadcast VARIABLE

    NOTES
    BUGS
    AUTHOR
    SEE ALSO

    utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code

    SYNOPSIS
    DESCRIPTION
    Utility functions

    $num_octets = utf8::upgrade($string), $success = utf8::downgrade($string[,
FAIL_OK]), utf8::encode($string), utf8::decode($string), $flag =
utf8::is_utf8(STRING), $flag = utf8::valid(STRING)

    BUGS
    SEE ALSO

    vars - Perl pragma to predeclare global variable names (obsolete)

    SYNOPSIS
    DESCRIPTION

    vmsish - Perl pragma to control VMS-specific language features

    SYNOPSIS
    DESCRIPTION

    vmsish status, vmsish exit, vmsish time, vmsish hushed

    warnings - Perl pragma to control optional warnings

    SYNOPSIS
    DESCRIPTION

    use warnings::register, warnings::enabled(), warnings::enabled($category),
warnings::enabled($object), warnings::warn($message),
warnings::warn($category, $message), warnings::warn($object, $message),
warnings::warnif($message), warnings::warnif($category, $message),
warnings::warnif($object, $message)

    warnings::register - warnings import function

    SYNOPSIS
    DESCRIPTION

    MODULE DOCUMENTATION

    AnyDBM_File - provide framework for multiple DBMs

    SYNOPSIS
    DESCRIPTION
    DBM Comparisons

    [0], [1], [2], [3]

    SEE ALSO

    Attribute::Handlers - Simpler definition of attribute handlers

    VERSION
    SYNOPSIS
    DESCRIPTION

    [0], [1], [2], [3], [4], [5]

    Typed lexicals
    Type-specific attribute handlers
    Non-interpretive attribute handlers
    Phase-specific attribute handlers
    Attributes as tie interfaces
    EXAMPLES
    DIAGNOSTICS

    Bad attribute type: ATTR(%s), Attribute handler %s doesn't handle %s attributes, Declaration of %s attribute in package %s may clash with future reserved word, Can't have two ATTR specifiers on one subroutine, Can't autotie a %s, Internal error: %s symbol went missing, Won't be able to apply END handler

    AUTHOR
    BUGS
    COPYRIGHT

    AutoLoader - load subroutines only on demand

    SYNOPSIS
    DESCRIPTION
    Subroutine Stubs
    Using AutoLoader's AUTOLOAD Subroutine
    Overriding AutoLoader's AUTOLOAD Subroutine
    Package Lexicals
    Not Using AutoLoader
    AutoLoader vs. SelfLoader
    CAVEATS
    SEE ALSO

    AutoSplit - split a package for autoloading

    SYNOPSIS
    DESCRIPTION

    $keep, $check, $modtime

    Multiple packages
    DIAGNOSTICS

    B - The Perl Compiler

    SYNOPSIS
    DESCRIPTION
    OVERVIEW
    Utility Functions
    Functions Returning B::SV, B::AV, B::HV, and B::CV objects

    sv_undef, sv_yes, sv_no, svref_2object(SVREF), amagic_generation, init_av, check_av, begin_av, end_av, comppadlist, regex_padav, main_cv

    Functions for Examining the Symbol Table

    walksymtable(SYMREF, METHOD, RECURSE, PREFIX)

    Functions Returning B::OP objects or for walking op trees

    main_root, main_start, walkoptree(OP, METHOD), walkoptree_debug(DEBUG)

    Miscellaneous Utility Functions

    ppname(OPNUM), hash(STR), cast_I32(I), minus_c, cstring(STR), perlstring(STR), class(OBJ), threadsv_names

    OVERVIEW OF CLASSES
    SV-RELATED CLASSES
    B::SV Methods

    REFCNT, FLAGS, object_2svref

    B::IV Methods

    IV, IVX, UVX, int_value, needs64bits, packiv

    B::NV Methods

    NV, NVX

    B::RV Methods

    RV

    B::PV Methods

    PV, RV, PVX

    B::PVMG Methods

    MAGIC, SvSTASH

    B::MAGIC Methods

    MOREMAGIC, precomp, PRIVATE, TYPE, FLAGS, OBJ, PTR, REGEX

    B::PVLV Methods

    TARGOFF, TARGLEN, TYPE, TARG

    B::BM Methods

    USEFUL, PREVIOUS, RARE, TABLE

    B::GV Methods

    is_empty, NAME, SAFENAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN, LINE, FILE, FILEGV, GvREFCNT, FLAGS

    B::IO Methods

    LINES, PAGE, PAGE_LEN, LINES_LEFT, TOP_NAME, TOP_GV, FMT_NAME, FMT_GV, BOTTOM_NAME, BOTTOM_GV, SUBPROCESS, IoTYPE, IoFLAGS, IsSTD

    B::AV Methods

    FILL, MAX, OFF, ARRAY, ARRAYelt, AvFLAGS

    B::CV Methods

    STASH, START, ROOT, GV, FILE, DEPTH, PADLIST, OUTSIDE, OUTSIDE_SEQ, XSUB, XSUBANY, CvFLAGS, const_sv

    B::HV Methods

    FILL, MAX, KEYS, RITER, NAME, PMROOT, ARRAY

    OP-RELATED CLASSES
    B::OP Methods

    next, sibling, name, ppaddr, desc, targ, type, opt, static, flags, private, spare

    B::UNOP METHOD

    first

    B::BINOP METHOD

    last

    B::LOGOP METHOD

    other

    B::LISTOP METHOD

    children

    B::PMOP Methods

    pmreplroot, pmreplstart, pmnext, pmregexp, pmflags, pmdynflags, pmpermflags, precomp, pmoffset

    B::SVOP METHOD

    sv, gv

    B::PADOP METHOD

    padix

    B::PVOP METHOD

    pv

    B::LOOP Methods

    redoop, nextop, lastop

    B::COP Methods

    label, stash, stashpv, file, cop_seq, arybase, line, warnings, io

    AUTHOR

    B::Asmdata - Autogenerated data about Perl ops, used to generate bytecode

    SYNOPSIS
    DESCRIPTION

    %insn_data, @insn_name, @optype, @specialsv_name

    AUTHOR

    B::Assembler - Assemble Perl bytecode

    SYNOPSIS
    DESCRIPTION
    AUTHORS

    B::Bblock - Walk basic blocks

    SYNOPSIS
    DESCRIPTION
    Functions

    find_leaders

    AUTHOR

    B::Bytecode - Perl compiler's bytecode backend

    SYNOPSIS
    DESCRIPTION
    EXAMPLE
    OPTIONS

    -b, -H, -k, -o outfile, -s

    KNOWN BUGS
    NOTICE
    AUTHORS

    B::C - Perl compiler's C backend

    SYNOPSIS
    DESCRIPTION
    OPTIONS

    -ofilename, -v, --, -uPackname, -D, -Do, -Dc, -DA, -DC, -DM, -f, -fcog, -fsave-data, -fppaddr, -fwarn-sv, -fuse-script-name, -fsave-sig-hash, -On, -O0, -O1, -O2, -llimit

    EXAMPLES
    BUGS
    AUTHOR

    B::CC - Perl compiler's optimized C translation backend

    SYNOPSIS
    DESCRIPTION
    OPTIONS

    -ofilename, -v, --, -uPackname, -mModulename, -D, -Dr, -DO, -Ds, -Dp, -Dq, -Dl, -Dt, -f, -ffreetmps-each-bblock, -ffreetmps-each-loop, -fomit-taint, -On

    EXAMPLES
    BUGS
    DIFFERENCES
    Loops
    Context of ".."
    Arithmetic
    Deprecated features
    AUTHOR

    B::Concise - Walk Perl syntax tree, printing concise info about ops

    SYNOPSIS
    DESCRIPTION
    EXAMPLE
    OPTIONS
    Options for Opcode Ordering

    -basic, -exec, -tree

    Options for Line-Style

    -concise, -terse, -linenoise, -debug, -env

    Options for tree-specific formatting

    -compact, -loose, -vt, -ascii

    Options controlling sequence numbering

    -base n, -bigendian, -littleendian

    Other options

    -main, -nomain, -nobanner, -banner, -banneris => subref

    Option Stickiness
    ABBREVIATIONS
    OP class abbreviations
    OP flags abbreviations
    FORMATTING SPECIFICATIONS
    Special Patterns

    (x(exec_text;basic_text)x), (*(text)*), (*(text1;text2)*), (?(text1#varText2)?), ~

    # Variables

    #var, #varN, #Var, #addr, #arg, #class, #classsym, #coplabel, #exname, #extarg, #firstaddr, #flags, #flagval, #hyphseq, #label, #lastaddr, #name, #NAME, #next, #nextaddr, #noise, #private, #privval, #seq, #seqnum, #opt, #static, #sibaddr, #svaddr, #svclass, #svval, #targ, #targarg, #targarglife, #typenum

    Using B::Concise outside of the O framework
    Example: Altering Concise Renderings
    set_style()
    set_style_standard($name)
    add_style()
    add_callback()
    Running B::Concise::compile()
    B::Concise::reset_sequence()
    Errors
    AUTHOR

    B::Debug - Walk Perl syntax tree, printing debug info about ops

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    B::Deparse - Perl compiler backend to produce perl code

    SYNOPSIS
    DESCRIPTION
    OPTIONS

    -d, -f FILE, -l, -p, -P, -q, -s LETTERS, C, i NUMBER, T, v STRING., -x LEVEL

    USING B::Deparse AS A MODULE
    Synopsis
    Description
    new
    ambient_pragmas

    strict, $[, bytes, utf8, integer, re, warnings, hint_bits, warning_bits

    coderef2text
    BUGS
    AUTHOR

    B::Disassembler - Disassemble Perl bytecode

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    B::Lint - Perl lint

    SYNOPSIS
    DESCRIPTION
    OPTIONS AND LINT CHECKS

    context, implicit-read and implicit-write, bare-subs, dollar-underscore, private-names, undefined-subs, regexp-variables, all, none

    NON LINT-CHECK OPTIONS

    -u Package

    BUGS
    AUTHOR

    B::O, O - Generic interface to Perl Compiler backends

    SYNOPSIS
    DESCRIPTION
    CONVENTIONS
    IMPLEMENTATION
    BUGS
    AUTHOR

    B::Showlex - Show lexical variables used in functions or files

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    OPTIONS
    SEE ALSO
    TODO
    AUTHOR

    B::Stackobj - Helper module for CC backend

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    B::Stash - show what stashes are loaded

    B::Terse - Walk Perl syntax tree, printing terse info about ops

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    B::Xref - Generates cross reference reports for Perl programs

    SYNOPSIS
    DESCRIPTION
    OPTIONS

    -oFILENAME, -r, -d, -D[tO]

    BUGS
    AUTHOR

    Bblock, B::Bblock - Walk basic blocks

    SYNOPSIS
    DESCRIPTION
    Functions

    find_leaders

    AUTHOR

    Benchmark - benchmark running times of Perl code

    SYNOPSIS
    DESCRIPTION
    Methods

    new, debug, iters

    Standard Exports

    timeit(COUNT, CODE), timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] ), timethese ( COUNT, CODEHASHREF, [ STYLE ] ), timediff ( T1, T2 ), timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )

    Optional Exports

    clearcache ( COUNT ), clearallcache ( ), cmpthese ( COUNT, CODEHASHREF, [ STYLE ] ), cmpthese ( RESULTSHASHREF, [ STYLE ] ), countit(TIME, CODE), disablecache ( ), enablecache ( ), timesum ( T1, T2 )

    :hireswallclock
    NOTES
    EXAMPLES
    INHERITANCE
    CAVEATS
    SEE ALSO
    AUTHORS
    MODIFICATION HISTORY

    ByteLoader - load byte compiled perl code

    SYNOPSIS
    DESCRIPTION
    AUTHOR
    SEE ALSO

    Bytecode, B::Bytecode - Perl compiler's bytecode backend

    SYNOPSIS
    DESCRIPTION
    EXAMPLE
    OPTIONS

    -b, -H, -k, -o outfile, -s

    KNOWN BUGS
    NOTICE
    AUTHORS

    CGI - Simple Common Gateway Interface Class

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    PROGRAMMING STYLE
    CALLING CGI.PM ROUTINES
    CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):
    CREATING A NEW QUERY OBJECT FROM AN INPUT FILE
    FETCHING A LIST OF KEYWORDS FROM THE QUERY:
    FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:
    FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:
    SETTING THE VALUE(S) OF A NAMED PARAMETER:
    APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:
    IMPORTING ALL PARAMETERS INTO A NAMESPACE:
    DELETING A PARAMETER COMPLETELY:
    DELETING ALL PARAMETERS:
    HANDLING NON-URLENCODED ARGUMENTS
    DIRECT ACCESS TO THE PARAMETER LIST:
    FETCHING THE PARAMETER LIST AS A HASH:
    SAVING THE STATE OF THE SCRIPT TO A FILE:
    RETRIEVING CGI ERRORS
    USING THE FUNCTION-ORIENTED INTERFACE

    :cgi, :form, :html2, :html3, :html4, :netscape, :html, :standard, :all

    PRAGMAS

    -any, -compile, -nosticky, -tabindex, -no_undef_params, -no_xhtml, -nph, -newstyle_urls, -oldstyle_urls, -autoload, -no_debug, -debug, -private_tempfiles

    SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS

    1. start_table() (generates a <table> tag), 2. end_table() (generates a </table> tag), 3. start_ul() (generates a <ul> tag), 4. end_ul() (generates a </ul> tag)

    GENERATING DYNAMIC DOCUMENTS
    CREATING A STANDARD HTTP HEADER:
    GENERATING A REDIRECTION HEADER
    CREATING THE HTML DOCUMENT HEADER

    Parameters:, 4, 5, 6..

    ENDING THE HTML DOCUMENT:
    CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
    OBTAINING THE SCRIPT'S URL

    -absolute, -relative, -full, -path (-path_info), -query (-query_string), -base, -rewrite

    MIXING POST AND URL PARAMETERS
    CREATING STANDARD HTML ELEMENTS:
    PROVIDING ARGUMENTS TO HTML SHORTCUTS
    THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS
    HTML SHORTCUTS AND LIST INTERPOLATION
    NON-STANDARD HTML SHORTCUTS
    AUTOESCAPING HTML

    $escaped_string = escapeHTML("unescaped string");, $charset = charset([$charset]);, $flag = autoEscape([$flag]);

    PRETTY-PRINTING HTML
    CREATING FILL-OUT FORMS:
    CREATING AN ISINDEX TAG
    STARTING AND ENDING A FORM

    application/x-www-form-urlencoded, multipart/form-data

    FORM ELEMENTS

    -name, -value, -values, -tabindex, -id, -override, -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect

    CREATING A TEXT FIELD

    Parameters

    CREATING A BIG TEXT FIELD
    CREATING A PASSWORD FIELD
    CREATING A FILE UPLOAD FIELD

    Parameters

    CREATING A POPUP MENU
    CREATING AN OPTION GROUP
    CREATING A SCROLLING LIST

    Parameters:

    CREATING A GROUP OF RELATED CHECKBOXES

    Parameters:

    CREATING A STANDALONE CHECKBOX

    Parameters:

    CREATING A RADIO BUTTON GROUP

    Parameters:

    CREATING A SUBMIT BUTTON

    Parameters:

    CREATING A RESET BUTTON
    CREATING A DEFAULT BUTTON
    CREATING A HIDDEN FIELD

    Parameters:

    CREATING A CLICKABLE IMAGE BUTTON

    Parameters:, 3. The third option (-align, optional) is an alignment type, and may be TOP, BOTTOM or MIDDLE

    CREATING A JAVASCRIPT ACTION BUTTON
    HTTP COOKIES

    1. an expiration time, 2. a domain, 3. a path, 4. a "secure" flag, -name, -value, -path, -domain, -expires, -secure

    WORKING WITH FRAMES

    1. Create a <Frameset> document, 2. Specify the destination for the document in the HTTP header, 3. Specify the destination for the document in the <form> tag

    SUPPORT FOR JAVASCRIPT

    onLoad, onUnload, onSubmit, onClick, onChange, onFocus, onBlur, onSelect, onMouseOver, onMouseOut

    LIMITED SUPPORT FOR CASCADING STYLE SHEETS
    DEBUGGING
    DUMPING OUT ALL THE NAME/VALUE PAIRS
    FETCHING ENVIRONMENT VARIABLES

    Accept(), raw_cookie(), user_agent(), path_info(), path_translated(), remote_host(), script_name() Return the script name as a partial URL, for self-refering scripts, referer(), auth_type (), server_name (), virtual_host (), server_port (), virtual_port (), server_software (), remote_user (), user_name (), request_method(), content_type(), http(), https()

    USING NPH SCRIPTS

    In the use statement, By calling the nph() method:, By using -nph parameters

    Server Push

    multipart_init(), multipart_start(), multipart_end(), multipart_final()

    Avoiding Denial of Service Attacks

    $CGI::POST_MAX, $CGI::DISABLE_UPLOADS, 1. On a script-by-script basis, 2. Globally for all scripts

    COMPATIBILITY WITH CGI-LIB.PL
    AUTHOR INFORMATION
    CREDITS

    Matt Heffron (heffron@falstaff.css.beckman.com), James Taylor (james.taylor@srs.gov), Scott Anguish <sanguish@digifix.com>, Mike Jewell (mlj3u@virginia.edu), Timothy Shimmin (tes@kbs.citri.edu.au), Joergen Haegg (jh@axis.se), Laurent Delfosse (delfosse@delfosse.com), Richard Resnick (applepi1@aol.com), Craig Bishop (csb@barwonwater.vic.gov.au), Tony Curtis (tc@vcpc.univie.ac.at), Tim Bunce (Tim.Bunce@ig.co.uk), Tom Christiansen (tchrist@convex.com), Andreas Koenig (k@franz.ww.TU-Berlin.DE), Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au), Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu), Stephen Dahmen (joyfire@inxpress.net), Ed Jordan (ed@fidalgo.net), David Alan Pisoni (david@cnation.com), Doug MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org), ...and many many more..

    A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
    BUGS
    SEE ALSO

    CGI::Apache - Backward compatibility module for CGI.pm

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    AUTHOR INFORMATION
    BUGS
    SEE ALSO

    CGI::Carp, CGI::Carp - CGI routines for writing to the HTTPD (or other) error log

    SYNOPSIS
    DESCRIPTION
    REDIRECTING ERROR MESSAGES
    MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW
    Changing the default message
    MAKING WARNINGS APPEAR AS HTML COMMENTS
    OVERRIDING THE NAME OF THE PROGRAM
    AUTHORS
    SEE ALSO

    CGI::Cookie - Interface to Netscape Cookies

    SYNOPSIS
    DESCRIPTION
    USING CGI::Cookie

    1. expiration date, 2. domain, 3. path, 4. secure flag

    Creating New Cookies
    Sending the Cookie to the Browser
    Recovering Previous Cookies
    Manipulating Cookies

    name(), value(), domain(), path(), expires()

    AUTHOR INFORMATION
    BUGS
    SEE ALSO

    CGI::Fast - CGI Interface for Fast CGI

    SYNOPSIS
    DESCRIPTION
    OTHER PIECES OF THE PUZZLE
    WRITING FASTCGI PERL SCRIPTS
    INSTALLING FASTCGI SCRIPTS
    USING FASTCGI SCRIPTS AS CGI SCRIPTS
    EXTERNAL FASTCGI SERVER INVOCATION

    FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE

    CAVEATS
    AUTHOR INFORMATION
    BUGS
    SEE ALSO

    CGI::Pretty - module to produce nicely formatted HTML code

    SYNOPSIS
    DESCRIPTION
    Tags that won't be formatted
    Customizing the Indenting
    BUGS
    AUTHOR
    SEE ALSO

    CGI::Push - Simple Interface to Server Push

    SYNOPSIS
    DESCRIPTION
    USING CGI::Push

    -next_page, -last_page, -type, -delay, -cookie, -target, -expires, -nph

    Heterogeneous Pages
    Changing the Page Delay on the Fly
    INSTALLING CGI::Push SCRIPTS
    AUTHOR INFORMATION
    BUGS
    SEE ALSO

    CGI::Switch - Backward compatibility module for defunct CGI::Switch

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    AUTHOR INFORMATION
    BUGS
    SEE ALSO

    CGI::Util - Internal utilities used by CGI module

    SYNOPSIS
    DESCRIPTION
    AUTHOR INFORMATION
    SEE ALSO

    CPAN - query, download and build perl modules from CPAN sites

    SYNOPSIS
    STATUS
    DESCRIPTION
    Interactive Mode

    Searching for authors, bundles, distribution files and modules, make, test, install, clean modules or distributions, get, readme, perldoc, look module or distribution, ls author, ls globbing_expresion, Signals

    CPAN::Shell
    autobundle
    recompile
    The four CPAN::* Classes: Author, Bundle, Module, Distribution
    Programmer's interface

    expand($type,@things), expandany(@things), Programming Examples

    Methods in the other Classes

    CPAN::Author::as_glimpse(), CPAN::Author::as_string(),
CPAN::Author::email(), CPAN::Author::fullname(), CPAN::Author::name(),
CPAN::Bundle::as_glimpse(), CPAN::Bundle::as_string(),
CPAN::Bundle::clean(), CPAN::Bundle::contains(),
CPAN::Bundle::force($method,@args), CPAN::Bundle::get(),
CPAN::Bundle::inst_file(), CPAN::Bundle::inst_version(),
CPAN::Bundle::uptodate(), CPAN::Bundle::install(), CPAN::Bundle::make(),
CPAN::Bundle::readme(), CPAN::Bundle::test(),
CPAN::Distribution::as_glimpse(), CPAN::Distribution::as_string(),
CPAN::Distribution::clean(), CPAN::Distribution::containsmods(),
CPAN::Distribution::cvs_import(), CPAN::Distribution::dir(),
CPAN::Distribution::force($method,@args), CPAN::Distribution::get(),
CPAN::Distribution::install(), CPAN::Distribution::isa_perl(),
CPAN::Distribution::look(), CPAN::Distribution::make(),
CPAN::Distribution::prereq_pm(), CPAN::Distribution::readme(),
CPAN::Distribution::perldoc(), CPAN::Distribution::test(),
CPAN::Distribution::uptodate(), CPAN::Index::force_reload(),
CPAN::Index::reload(), CPAN::InfoObj::dump(), CPAN::Module::as_glimpse(),
CPAN::Module::as_string(), CPAN::Module::clean(),
CPAN::Module::cpan_file(), CPAN::Module::cpan_version(),
CPAN::Module::cvs_import(), CPAN::Module::description(),
CPAN::Module::force($method,@args), CPAN::Module::get(),
CPAN::Module::inst_file(), CPAN::Module::inst_version(),
CPAN::Module::install(), CPAN::Module::look(), CPAN::Module::make(),
CPAN::Module::manpage_headline(), CPAN::Module::readme(),
CPAN::Module::perldoc(), CPAN::Module::test(), CPAN::Module::uptodate(),
CPAN::Module::userid()

    Cache Manager
    Bundles
    Prerequisites
    Finding packages and VERSION
    Debugging
    Floppy, Zip, Offline Mode
    CONFIGURATION

    o conf <scalar option>, o conf <scalar option> E<lt>valueE<gt>, o conf <list option>, o conf <list optionE<gt> [shift|pop], o conf <list option> [unshift|push|splice] E<lt>listE<gt>

    Note on urllist parameter's format
    urllist parameter has CD-ROM support
    SECURITY
    Cryptographically signed modules
    EXPORT
    POPULATE AN INSTALLATION WITH LOTS OF MODULES
    WORKING WITH CPAN.pm BEHIND FIREWALLS
    Three basic types of firewalls

    http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade

    Configuring lynx or ncftp for going through a firewall
    FAQ

    1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11)

    BUGS
    AUTHOR
    TRANSLATIONS
    SEE ALSO

    CPAN::FirstTime - Utility for CPAN::Config file Initialization

    SYNOPSIS
    DESCRIPTION

    CPAN::Version - utility functions to compare CPAN versions

    SYNOPSIS
    DESCRIPTION

    CPANox, CPAN::Nox - Wrapper around CPAN.pm without using any XS module

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    Carp, carp - warn of errors (from perspective of caller)

    SYNOPSIS
    DESCRIPTION
    Forcing a Stack Trace
    GLOBAL VARIABLES
    $Carp::CarpLevel
    $Carp::MaxEvalLen
    $Carp::MaxArgLen
    $Carp::MaxArgNums
    $Carp::Verbose
    BUGS

    Carp::Heavy - heavy machinery, no user serviceable parts inside

    Class::ISA -- report the search path for a class's ISA tree

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS

    the function Class::ISA::super_path($CLASS), the function
Class::ISA::self_and_super_path($CLASS), the function
Class::ISA::self_and_super_versions($CLASS)

    CAUTIONARY NOTES
    COPYRIGHT
    AUTHOR

    Class::Struct - declare struct-like datatypes as Perl classes

    SYNOPSIS
    DESCRIPTION
    The struct() function
    Class Creation at Compile Time
    Element Types and Accessor Methods

    Scalar ('$' or '*$'), Array ('@' or '*@'), Hash ('%' or '*%'), Class ('Class_Name' or '*Class_Name')

    Initializing with new
    EXAMPLES

    Example 1, Example 2, Example 3

    Author and Modification History

    Config - access Perl configuration information

    SYNOPSIS
    DESCRIPTION

    myconfig(), config_sh(), config_re($regex), config_vars(@names)

    EXAMPLE
    WARNING
    GLOSSARY
    _

    _a, _exe, _o

    a

    afs, afsroot, alignbytes, ansi2knr, aphostname, api_revision, api_subversion, api_version, api_versionstring, ar, archlib, archlibexp, archname64, archname, archobjs, asctime_r_proto, awk

    b

    baserev, bash, bin, binexp, bison, byacc, byteorder

    c

    c, castflags, cat, cc, cccdlflags, ccdlflags, ccflags, ccflags_uselargefiles, ccname, ccsymbols, ccversion, cf_by, cf_email, cf_time, charsize, chgrp, chmod, chown, clocktype, comm, compress, contains, cp, cpio, cpp, cpp_stuff, cppccsymbols, cppflags, cpplast, cppminus, cpprun, cppstdin, cppsymbols, crypt_r_proto, cryptlib, csh, ctermid_r_proto, ctime_r_proto

    d

    d__fwalk, d_access, d_accessx, d_aintl, d_alarm, d_archlib, d_asctime_r, d_atolf, d_atoll, d_attribute_format, d_attribute_malloc, d_attribute_nonnull, d_attribute_noreturn, d_attribute_pure, d_attribute_unused, d_attribute_warn_unused_result, d_bcmp, d_bcopy, d_bsd, d_bsdgetpgrp, d_bsdsetpgrp, d_bzero, d_casti32, d_castneg, d_charvspr, d_chown, d_chroot, d_chsize, d_class, d_clearenv, d_closedir, d_cmsghdr_s, d_const, d_copysignl, d_crypt, d_crypt_r, d_csh, d_ctermid_r, d_ctime_r, d_cuserid, d_dbl_dig, d_dbminitproto, d_difftime, d_dirfd, d_dirnamlen, d_dlerror, d_dlopen, d_dlsymun, d_dosuid, d_drand48_r, d_drand48proto, d_dup2, d_eaccess, d_endgrent, d_endgrent_r, d_endhent, d_endhostent_r, d_endnent, d_endnetent_r, d_endpent, d_endprotoent_r, d_endpwent, d_endpwent_r, d_endsent, d_endservent_r, d_eofnblk, d_eunice, d_faststdio, d_fchdir, d_fchmod, d_fchown, d_fcntl, d_fcntl_can_lock, d_fd_macros, d_fd_set, d_fds_bits, d_fgetpos, d_finite, d_finitel, d_flexfnam, d_flock, d_flockproto, d_fork, d_fp_class, d_fpathconf, d_fpclass, d_fpclassify, d_fpclassl, d_fpos64_t, d_frexpl, d_fs_data_s, d_fseeko, d_fsetpos, d_fstatfs, d_fstatvfs, d_fsync, d_ftello, d_ftime, d_futimes, d_Gconvert, d_getcwd, d_getespwnam, d_getfsstat, d_getgrent, d_getgrent_r, d_getgrgid_r, d_getgrnam_r, d_getgrps, d_gethbyaddr, d_gethbyname, d_gethent, d_gethname, d_gethostbyaddr_r, d_gethostbyname_r, d_gethostent_r, d_gethostprotos, d_getitimer, d_getlogin, d_getlogin_r, d_getmnt, d_getmntent, d_getnbyaddr, d_getnbyname, d_getnent, d_getnetbyaddr_r, d_getnetbyname_r, d_getnetent_r, d_getnetprotos, d_getpagsz, d_getpbyname, d_getpbynumber, d_getpent, d_getpgid, d_getpgrp2, d_getpgrp, d_getppid, d_getprior, d_getprotobyname_r, d_getprotobynumber_r, d_getprotoent_r, d_getprotoprotos, d_getprpwnam, d_getpwent, d_getpwent_r, d_getpwnam_r, d_getpwuid_r, d_getsbyname, d_getsbyport, d_getsent, d_getservbyname_r, d_getservbyport_r, d_getservent_r, d_getservprotos, d_getspnam, d_getspnam_r, d_gettimeod, d_gmtime_r, d_gnulibc, d_grpasswd, d_hasmntopt, d_htonl, d_ilogbl, d_index, d_inetaton, d_int64_t, d_isascii, d_isfinite, d_isinf, d_isnan, d_isnanl, d_killpg, d_lchown, d_ldbl_dig, d_link, d_localtime_r, d_locconv, d_lockf, d_longdbl, d_longlong, d_lseekproto, d_lstat, d_madvise, d_malloc_size, d_malloc_good_size, d_mblen, d_mbstowcs, d_mbtowc, d_memchr, d_memcmp, d_memcpy, d_memmove, d_memset, d_mkdir, d_mkdtemp, d_mkfifo, d_mkstemp, d_mkstemps, d_mktime, d_mmap, d_modfl, d_modfl_pow32_bug, d_modflproto, d_mprotect, d_msg, d_msg_ctrunc, d_msg_dontroute, d_msg_oob, d_msg_peek, d_msg_proxy, d_msgctl, d_msgget, d_msghdr_s, d_msgrcv, d_msgsnd, d_msync, d_munmap, d_mymalloc, d_nanosleep, d_nice, d_nl_langinfo, d_nv_preserves_uv, d_nv_zero_is_allbits_zero, d_off64_t, d_old_pthread_create_joinable, d_oldpthreads, d_oldsock, d_open3, d_pathconf, d_pause, d_perl_otherlibdirs, d_phostname, d_pipe, d_poll, d_portable, d_PRId64, d_PRIeldbl, d_PRIEUldbl, d_PRIfldbl, d_PRIFUldbl, d_PRIgldbl, d_PRIGUldbl, d_PRIi64, d_PRIo64, d_PRIu64, d_PRIx64, d_PRIXU64, d_procselfexe, d_pthread_atfork, d_pthread_attr_setscope, d_pthread_yield, d_pwage, d_pwchange, d_pwclass, d_pwcomment, d_pwexpire, d_pwgecos, d_pwpasswd, d_pwquota, d_qgcvt, d_quad, d_random_r, d_readdir64_r, d_readdir, d_readdir_r, d_readlink, d_readv, d_recvmsg, d_rename, d_rewinddir, d_rmdir, d_safebcpy, d_safemcpy, d_sanemcmp, d_sbrkproto, d_scalbnl, d_sched_yield, d_scm_rights, d_SCNfldbl, d_seekdir, d_select, d_sem, d_semctl, d_semctl_semid_ds, d_semctl_semun, d_semget, d_semop, d_sendmsg, d_setegid, d_seteuid, d_setgrent, d_setgrent_r, d_setgrps, d_sethent, d_sethostent_r, d_setitimer, d_setlinebuf, d_setlocale, d_setlocale_r, d_setnent, d_setnetent_r, d_setpent, d_setpgid, d_setpgrp2, d_setpgrp, d_setprior, d_setproctitle, d_setprotoent_r, d_setpwent, d_setpwent_r, d_setregid, d_setresgid, d_setresuid, d_setreuid, d_setrgid, d_setruid, d_setsent, d_setservent_r, d_setsid, d_setvbuf, d_sfio, d_shm, d_shmat, d_shmatprototype, d_shmctl, d_shmdt, d_shmget, d_sigaction, d_sigprocmask, d_sigsetjmp, d_sockatmark, d_sockatmarkproto, d_socket, d_socklen_t, d_sockpair, d_socks5_init, d_sprintf_returns_strlen, d_sqrtl, d_srand48_r, d_srandom_r, d_sresgproto, d_sresuproto, d_statblks, d_statfs_f_flags, d_statfs_s, d_statvfs, d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdio_ptr_lval_nochange_cnt, d_stdio_ptr_lval_sets_cnt, d_stdio_stream_array, d_stdiobase, d_stdstdio, d_strchr, d_strcoll, d_strctcpy, d_strerrm, d_strerror, d_strerror_r, d_strftime, d_strlcat, d_strlcpy, d_strtod, d_strtol, d_strtold, d_strtoll, d_strtoq, d_strtoul, d_strtoull, d_strtouq, d_strxfrm, d_suidsafe, d_symlink, d_syscall, d_syscallproto, d_sysconf, d_sysernlst, d_syserrlst, d_system, d_tcgetpgrp, d_tcsetpgrp, d_telldir, d_telldirproto, d_time, d_times, d_tm_tm_gmtoff, d_tm_tm_zone, d_tmpnam_r, d_truncate, d_ttyname_r, d_tzname, d_u32align, d_ualarm, d_umask, d_uname, d_union_semun, d_unordered, d_unsetenv, d_usleep, d_usleepproto, d_ustat, d_vendorarch, d_vendorbin, d_vendorlib, d_vendorscript, d_vfork, d_void_closedir, d_voidsig, d_voidtty, d_volatile, d_vprintf, d_wait4, d_waitpid, d_wcstombs, d_wctomb, d_writev, d_xenix, date, db_hashtype, db_prefixtype, db_version_major, db_version_minor, db_version_patch, defvoidused, direntrytype, dlext, dlsrc, doublesize, drand01, drand48_r_proto, dynamic_ext

    e

    eagain, ebcdic, echo, egrep, emacs, endgrent_r_proto, endhostent_r_proto, endnetent_r_proto, endprotoent_r_proto, endpwent_r_proto, endservent_r_proto, eunicefix, exe_ext, expr, extensions, extras

    f

    fflushall, fflushNULL, find, firstmakefile, flex, fpossize, fpostype, freetype, from, full_ar, full_csh, full_sed

    g

    gccansipedantic, gccosandvers, gccversion, getgrent_r_proto, getgrgid_r_proto, getgrnam_r_proto, gethostbyaddr_r_proto, gethostbyname_r_proto, gethostent_r_proto, getlogin_r_proto, getnetbyaddr_r_proto, getnetbyname_r_proto, getnetent_r_proto, getprotobyname_r_proto, getprotobynumber_r_proto, getprotoent_r_proto, getpwent_r_proto, getpwnam_r_proto, getpwuid_r_proto, getservbyname_r_proto, getservbyport_r_proto, getservent_r_proto, getspnam_r_proto, gidformat, gidsign, gidsize, gidtype, glibpth, gmake, gmtime_r_proto, gnulibc_version, grep, groupcat, groupstype, gzip

    h

    h_fcntl, h_sysfile, hint, hostcat, html1dir, html1direxp, html3dir, html3direxp

    i

    i16size, i16type, i32size, i32type, i64size, i64type, i8size, i8type, i_arpainet, i_bsdioctl, i_crypt, i_db, i_dbm, i_dirent, i_dld, i_dlfcn, i_fcntl, i_float, i_fp, i_fp_class, i_gdbm, i_grp, i_ieeefp, i_inttypes, i_langinfo, i_libutil, i_limits, i_locale, i_machcthr, i_malloc, i_math, i_memory, i_mntent, i_ndbm, i_netdb, i_neterrno, i_netinettcp, i_niin, i_poll, i_prot, i_pthread, i_pwd, i_rpcsvcdbm, i_sfio, i_sgtty, i_shadow, i_socks, i_stdarg, i_stddef, i_stdlib, i_string, i_sunmath, i_sysaccess, i_sysdir, i_sysfile, i_sysfilio, i_sysin, i_sysioctl, i_syslog, i_sysmman, i_sysmode, i_sysmount, i_sysndir, i_sysparam, i_sysresrc, i_syssecrt, i_sysselct, i_syssockio, i_sysstat, i_sysstatfs, i_sysstatvfs, i_systime, i_systimek, i_systimes, i_systypes, i_sysuio, i_sysun, i_sysutsname, i_sysvfs, i_syswait, i_termio, i_termios, i_time, i_unistd, i_ustat, i_utime, i_values, i_varargs, i_varhdr, i_vfork, ignore_versioned_solibs, inc_version_list, inc_version_list_init, incpath, inews, installarchlib, installbin, installhtml1dir, installhtml3dir, installman1dir, installman3dir, installprefix, installprefixexp, installprivlib, installscript, installsitearch, installsitebin, installsitehtml1dir, installsitehtml3dir, installsitelib, installsiteman1dir, installsiteman3dir, installsitescript, installstyle, installusrbinperl, installvendorarch, installvendorbin, installvendorhtml1dir, installvendorhtml3dir, installvendorlib, installvendorman1dir, installvendorman3dir, installvendorscript, intsize, issymlink, ivdformat, ivsize, ivtype

    k

    known_extensions, ksh

    l

    ld, lddlflags, ldflags, ldflags_uselargefiles, ldlibpthname, less, lib_ext, libc, libperl, libpth, libs, libsdirs, libsfiles, libsfound, libspath, libswanted, libswanted_uselargefiles, line, lint, lkflags, ln, lns, localtime_r_proto, locincpth, loclibpth, longdblsize, longlongsize, longsize, lp, lpr, ls, lseeksize, lseektype

    m

    mail, mailx, make, make_set_make, mallocobj, mallocsrc, malloctype, man1dir, man1direxp, man1ext, man3dir, man3direxp, man3ext

    M

    Mcc, mips_type, mistrustnm, mkdir, mmaptype, modetype, more, multiarch, mv, myarchname, mydomain, myhostname, myuname

    n

    n, need_va_copy, netdb_hlen_type, netdb_host_type, netdb_name_type, netdb_net_type, nm, nm_opt, nm_so_opt, nonxs_ext, nroff, nv_preserves_uv_bits, nveformat, nvEUformat, nvfformat, nvFUformat, nvgformat, nvGUformat, nvsize, nvtype

    o

    o_nonblock, obj_ext, old_pthread_create_joinable, optimize, orderlib, osname, osvers, otherlibdirs

    p

    package, pager, passcat, patchlevel, path_sep, perl5, perl, perl_patchlevel

    P

    PERL_REVISION, PERL_SUBVERSION, PERL_VERSION, perladmin, perllibs, perlpath, pg, phostname, pidtype, plibpth, pmake, pr, prefix, prefixexp, privlib, privlibexp, procselfexe, prototype, ptrsize

    q

    quadkind, quadtype

    r

    randbits, randfunc, random_r_proto, randseedtype, ranlib, rd_nodata, readdir64_r_proto, readdir_r_proto, revision, rm, rmail, run, runnm

    s

    sched_yield, scriptdir, scriptdirexp, sed, seedfunc, selectminbits, selecttype, sendmail, setgrent_r_proto, sethostent_r_proto, setlocale_r_proto, setnetent_r_proto, setprotoent_r_proto, setpwent_r_proto, setservent_r_proto, sh, shar, sharpbang, shmattype, shortsize, shrpenv, shsharp, sig_count, sig_name, sig_name_init, sig_num, sig_num_init, sig_size, signal_t, sitearch, sitearchexp, sitebin, sitebinexp, sitehtml1dir, sitehtml1direxp, sitehtml3dir, sitehtml3direxp, sitelib, sitelib_stem, sitelibexp, siteman1dir, siteman1direxp, siteman3dir, siteman3direxp, siteprefix, siteprefixexp, sitescript, sitescriptexp, sizesize, sizetype, sleep, smail, so, sockethdr, socketlib, socksizetype, sort, spackage, spitshell, sPRId64, sPRIeldbl, sPRIEUldbl, sPRIfldbl, sPRIFUldbl, sPRIgldbl, sPRIGUldbl, sPRIi64, sPRIo64, sPRIu64, sPRIx64, sPRIXU64, srand48_r_proto, srandom_r_proto, src, sSCNfldbl, ssizetype, startperl, startsh, static_ext, stdchar, stdio_base, stdio_bufsiz, stdio_cnt, stdio_filbuf, stdio_ptr, stdio_stream_array, strerror_r_proto, strings, submit, subversion, sysman

    t

    tail, tar, targetarch, tbl, tee, test, timeincl, timetype, tmpnam_r_proto, to, touch, tr, trnl, troff, ttyname_r_proto

    u

    u16size, u16type, u32size, u32type, u64size, u64type, u8size, u8type, uidformat, uidsign, uidsize, uidtype, uname, uniq, uquadtype, use5005threads, use64bitall, use64bitint, usecrosscompile, usedl, usefaststdio, useithreads, uselargefiles, uselongdouble, usemallocwrap, usemorebits, usemultiplicity, usemymalloc, usenm, useopcode, useperlio, useposix, usereentrant, usesfio, useshrplib, usesocks, usethreads, usevendorprefix, usevfork, usrinc, uuname, uvoformat, uvsize, uvtype, uvuformat, uvxformat, uvXUformat

    v

    vendorarch, vendorarchexp, vendorbin, vendorbinexp, vendorhtml1dir, vendorhtml1direxp, vendorhtml3dir, vendorhtml3direxp, vendorlib, vendorlib_stem, vendorlibexp, vendorman1dir, vendorman1direxp, vendorman3dir, vendorman3direxp, vendorprefix, vendorprefixexp, vendorscript, vendorscriptexp, version, version_patchlevel_string, versiononly, vi, voidflags

    x

    xlibpth

    y

    yacc, yaccflags

    z

    zcat, zip

    NOTE

    Cwd - get pathname of current working directory

    SYNOPSIS
    DESCRIPTION
    getcwd and friends

    getcwd, cwd, fastcwd, fastgetcwd, getdcwd

    abs_path and friends

    abs_path, realpath, fast_abs_path

    $ENV{PWD}
    NOTES
    AUTHOR
    COPYRIGHT
    SEE ALSO

    DB - programmatic interface to the Perl debugging API (draft, subject to change)

    SYNOPSIS
    DESCRIPTION
    Global Variables
     $DB::sub,  %DB::sub,  $DB::single,  $DB::signal,  $DB::trace,  @DB::args,
@DB::dbline,  %DB::dbline,  $DB::package,  $DB::filename,  $DB::subname,
$DB::lineno
    API Methods

    CLIENT->register(), CLIENT->evalcode(STRING), CLIENT->skippkg('D::hide'), CLIENT->run(), CLIENT->step(), CLIENT->next(), CLIENT->done()

    Client Callback Methods

    CLIENT->init(), CLIENT->prestop([STRING]), CLIENT->stop(), CLIENT->idle(),
CLIENT->poststop([STRING]), CLIENT->evalcode(STRING), CLIENT->cleanup(),
CLIENT->output(LIST)

    BUGS
    AUTHOR

    DBM_Filter -- Filter DBM keys/values

    SYNOPSIS
    DESCRIPTION
    What is a DBM Filter?
    So what's new?
    METHODS
    $db->Filter_Push()
    $db->Filter_Key_Push()
    $db->Filter_Value_Push()

    Filter_Push, Filter_Key_Push, Filter_Value_Push

    $db->Filter_Pop()
    $db->Filtered()
    Writing a Filter
    Immediate Filters
    Canned Filters

    "name", params

    Filters Included

    utf8, encode, compress, int32, null

    NOTES
    Maintain Round Trip Integrity
    Don't mix filtered & non-filtered data in the same database file.
    EXAMPLE
    SEE ALSO
    AUTHOR

    DB_File - Perl5 access to Berkeley DB version 1.x

    SYNOPSIS
    DESCRIPTION

    DB_HASH, DB_BTREE, DB_RECNO

    Using DB_File with Berkeley DB version 2 or greater
    Interface to Berkeley DB
    Opening a Berkeley DB Database File
    Default Parameters
    In Memory Databases
    DB_HASH
    A Simple Example
    DB_BTREE
    Changing the BTREE sort order
    Handling Duplicate Keys
    The get_dup() Method
    The find_dup() Method
    The del_dup() Method
    Matching Partial Keys
    DB_RECNO
    The 'bval' Option
    A Simple Example
    Extra RECNO Methods

    $X->push(list) ;, $value = $X->pop ;, $X->shift,
$X->unshift(list) ;, $X->length, $X->splice(offset,
length, elements);

    Another Example
    THE API INTERFACE

    $status = $X->get($key, $value [, $flags]) ;, $status =
$X->put($key, $value [, $flags]) ;, $status = $X->del($key [,
$flags]) ;, $status = $X->fd ;, $status = $X->seq($key,
$value, $flags) ;, $status = $X->sync([$flags]) ;

    DBM FILTERS

    filter_store_key, filter_store_value, filter_fetch_key, filter_fetch_value

    The Filter
    An Example -- the NULL termination problem.
    Another Example -- Key is a C int.
    HINTS AND TIPS
    Locking: The Trouble with fd
    Safe ways to lock a database

    Tie::DB_Lock, Tie::DB_LockFile, DB_File::Lock

    Sharing Databases With C Applications
    The untie() Gotcha
    COMMON QUESTIONS
    Why is there Perl source in my database?
    How do I store complex data structures with DB_File?
    What does "Invalid Argument" mean?
    What does "Bareword 'DB_File' not allowed" mean?
    REFERENCES
    HISTORY
    BUGS
    AVAILABILITY
    COPYRIGHT
    SEE ALSO
    AUTHOR

    Data::Dumper - stringified perl data structures, suitable for both printing and eval

    SYNOPSIS
    DESCRIPTION
    Methods

    PACKAGE->new(ARRAYREF [, ARRAYREF]), $OBJ->Dump  or
PACKAGE->Dump(ARRAYREF [, ARRAYREF]), $OBJ->Seen([HASHREF]),
$OBJ->Values([ARRAYREF]), $OBJ->Names([ARRAYREF]),
$OBJ->Reset

    Functions

    Dumper(LIST)

    Configuration Variables or Methods
    Exports

    Dumper

    EXAMPLES
    BUGS
    NOTE
    AUTHOR
    VERSION
    SEE ALSO

    Devel::DProf - a Perl code profiler

    SYNOPSIS
    DESCRIPTION
    PROFILE FORMAT
    AUTOLOAD
    ENVIRONMENT
    BUGS
    SEE ALSO

    Devel::PPPort - Perl/Pollution/Portability

    SYNOPSIS
    DESCRIPTION
    Why use ppport.h?

    You should use ppport.h in modern code so that your code will work with the widest range of Perl interpreters possible, without significant additional work.

    How to use ppport.h
    Running ppport.h
    FUNCTIONS
    WriteFile
    COMPATIBILITY
    Provided Perl compatibility API
    Perl API not supported by ppport.h

    perl 5.9.2, perl 5.9.1, perl 5.9.0, perl 5.8.3, perl 5.8.1, perl 5.8.0, perl 5.7.3, perl 5.7.2, perl 5.7.1, perl 5.6.1, perl 5.6.0, perl 5.005_03, perl 5.005, perl 5.004_05, perl 5.004_04, perl 5.004

    BUGS
    AUTHORS
    COPYRIGHT
    SEE ALSO

    Devel::Peek - A data debugging tool for the XS programmer

    SYNOPSIS
    DESCRIPTION
    Runtime debugging
    Memory footprint debugging
    EXAMPLES
    A simple scalar string
    A simple scalar number
    A simple scalar with an extra reference
    A reference to a simple scalar
    A reference to an array
    A reference to a hash
    Dumping a large array or hash
    A reference to an SV which holds a C pointer
    A reference to a subroutine
    EXPORTS
    BUGS
    AUTHOR
    SEE ALSO

    Devel::SelfStubber - generate stubs for a SelfLoading module

    SYNOPSIS
    DESCRIPTION

    Devel::Size - Perl extension for finding the memory usage of Perl variables

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS
    size($ref)
    total_size($ref)
    EXPORT
    UNDERSTANDING MEMORY ALLOCATION
    The C library
    Perl
    DANGERS
    Messages: texts originating from this module.
    Errors
    warnings
    BUGS
    AUTHOR
    COPYRIGHT
    SEE ALSO

    Digest - Modules that calculate message digests

    SYNOPSIS
    DESCRIPTION

    binary, hex, base64

    OO INTERFACE

    $ctx = Digest->XXX($arg,...), $ctx = Digest->new(XXX => $arg,...), $ctx = Digest::XXX->new($arg,...), $other_ctx = $ctx->clone, $ctx->reset, $ctx->add( $data, ... ), $ctx->addfile( $io_handle ), $ctx->add_bits( $data, $nbits ), $ctx->add_bits( $bitstring ), $ctx->digest, $ctx->hexdigest, $ctx->b64digest

    Digest speed
    SEE ALSO
    AUTHOR

    Digest::MD5 - Perl interface to the MD5 Algorithm

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS

    md5($data,...), md5_hex($data,...), md5_base64($data,...)

    METHODS

    $md5 = Digest::MD5->new, $md5->reset, $md5->clone, $md5->add($data,...),
$md5->addfile($io_handle), $md5->add_bits($data, $nbits),
$md5->add_bits($bitstring), $md5->digest, $md5->hexdigest, $md5->b64digest

    EXAMPLES
    SEE ALSO
    COPYRIGHT
    AUTHORS

    Digest::base - Digest base class

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    Digest::file - Calculate digests of files

    SYNOPSIS
    DESCRIPTION

    digest_file( $file, $algorithm, [$arg,...] ), digest_file_hex( $file, $algorithm, [$arg,...] ), digest_file_base64( $file, $algorithm, [$arg,...] )

    SEE ALSO

    DirHandle - supply object methods for directory handles

    SYNOPSIS
    DESCRIPTION
    NOTES

    Dumpvalue - provides screen dump of Perl data.

    SYNOPSIS
    DESCRIPTION
    Creation

    arrayDepth, hashDepth, compactDump, veryCompact, globPrint, dumpDBFiles, dumpPackages, dumpReused, tick, quoteHighBit, printUndef, usageOnly, unctrl, subdump, bareStringify, quoteHighBit, stopDbSignal

    Methods

    dumpValue, dumpValues, stringify, dumpvars, set_quote, set_unctrl, compactDump, veryCompact, set, get

    DynaLoader - Dynamically load C libraries into Perl code

    SYNOPSIS
    DESCRIPTION

    @dl_library_path, @dl_resolve_using, @dl_require_symbols, @dl_librefs,
@dl_modules, @dl_shared_objects, dl_error(), $dl_debug, dl_findfile(),
dl_expandspec(), dl_load_file(), dl_unload_file(), dl_load_flags(),
dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(),
dl_install_xsub(), bootstrap()

    AUTHOR

    DynaLoader::XSLoader, XSLoader - Dynamically load C libraries into Perl code

    VERSION
    SYNOPSIS
    DESCRIPTION
    Migration from DynaLoader
    Backward compatible boilerplate
    Order of initialization: early load()
    The most hairy case
    DIAGNOSTICS

    Can't find '%s' symbol in %s, Can't load '%s' for module %s: %s, Undefined symbols present after loading %s: %s, XSLoader::load('Your::Module', $Your::Module::VERSION)

    LIMITATIONS
    BUGS
    SEE ALSO
    AUTHORS
    COPYRIGHT

    Encode - character encodings

    SYNOPSIS
    Table of Contents
    DESCRIPTION
    TERMINOLOGY
    PERL ENCODING API

    $octets = encode(ENCODING, $string [, CHECK]), $string = decode(ENCODING, $octets [, CHECK]), [$length =] from_to($octets, FROM_ENC, TO_ENC [, CHECK]), $octets = encode_utf8($string);, $string = decode_utf8($octets [, CHECK]);

    Listing available encodings
    Defining Aliases
    Encoding via PerlIO
    Handling Malformed Data

    NOTE: Not all encoding support this feature, CHECK =
Encode::FB_DEFAULT ( == 0), CHECK = Encode::FB_CROAK ( == 1), CHECK =
Encode::FB_QUIET, CHECK = Encode::FB_WARN, perlqq mode (CHECK =
Encode::FB_PERLQQ), HTML charref mode (CHECK = Encode::FB_HTMLCREF), XML
charref mode (CHECK = Encode::FB_XMLCREF), The bitmask

    coderef for CHECK
    Defining Encodings
    The UTF-8 flag

    Goal #1:, Goal #2:, Goal #3:, Goal #4:

    Messing with Perl's Internals

    is_utf8(STRING [, CHECK]), _utf8_on(STRING), _utf8_off(STRING)

    UTF-8 vs. utf8
    SEE ALSO
    MAINTAINER

    Encode::Alias - alias definitions to encodings

    SYNOPSIS
    DESCRIPTION

    As a simple string, As a qr// compiled regular expression, e.g.:, As a code reference, e.g.:

    Alias overloading
    SEE ALSO

    Encode::Byte - Single Byte Encodings

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    SEE ALSO

    Encode::CJKConstants -- Internally used by Encode::??::ISO_2022_*

    Encode::CN - China-based Chinese Encodings

    SYNOPSIS
    DESCRIPTION
    NOTES
    BUGS
    SEE ALSO

    Encode::CN::HZ -- internally used by Encode::CN

    Encode::Config -- internally used by Encode

    Encode::EBCDIC - EBCDIC Encodings

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    SEE ALSO

    Encode::Encoding - Encode Implementation Base Class

    SYNOPSIS
    DESCRIPTION
    Methods you should implement

    ->encode($string [,$check]), ->decode($octets [,$check]), ->cat_decode($destination, $octets, $offset, $terminator [,$check])

    Other methods defined in Encode::Encodings

    ->name, ->renew, ->renewed, ->perlio_ok(), ->needs_lines()

    Example: Encode::ROT13
    Why the heck Encode API is different?
    Compiled Encodings
    SEE ALSO

    Scheme 1, Scheme 2, Other Schemes

    Encode::Guess -- Guesses encoding from data

    SYNOPSIS
    ABSTRACT
    DESCRIPTION

    Encode::Guess->set_suspects, Encode::Guess->add_suspects,
Encode::decode("Guess" ...), Encode::Guess->guess($data),
guess_encoding($data, [, list of suspects])

    CAVEATS
    TO DO
    SEE ALSO

    Encode::JP - Japanese Encodings

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    Note on ISO-2022-JP(-1)?
    BUGS
    SEE ALSO

    Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*

    Encode::JP::JIS7 -- internally used by Encode::JP

    Encode::KR - Korean Encodings

    SYNOPSIS
    DESCRIPTION
    BUGS
    SEE ALSO

    Encode::KR::2022_KR -- internally used by Encode::KR

    Encode::MIME::Header -- MIME 'B' and 'Q' header encoding

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    BUGS
    SEE ALSO

    Encode::PerlIO -- a detailed document on Encode and PerlIO

    Overview
    How does it work?
    Line Buffering
    How can I tell whether my encoding fully supports PerlIO ?
    SEE ALSO

    Encode::Supported -- Encodings supported by Encode

    DESCRIPTION
    Encoding Names
    Supported Encodings
    Built-in Encodings
    Encode::Unicode -- other Unicode encodings
    Encode::Byte -- Extended ASCII

    ISO-8859 and corresponding vendor mappings, KOI8 - De Facto Standard for the Cyrillic world, gsm0338 - Hentai Latin 1

    CJK: Chinese, Japanese, Korean (Multibyte)

    Encode::CN -- Continental China, Encode::JP -- Japan, Encode::KR -- Korea, Encode::TW -- Taiwan, Encode::HanExtra -- More Chinese via CPAN, Encode::JIS2K -- JIS X 0213 encodings via CPAN

    Miscellaneous encodings

    Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess

    Unsupported encodings
      ISO-2022-JP-2 [RFC1554], ISO-2022-CN [RFC1922], Various HP-UX encodings,
Cyrillic encoding ISO-IR-111, ISO-8859-8-1 [Hebrew], ISIRI 3342, Iran
System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
Various Mac encodings, (Mac) Indic encodings
    Encoding vs. Charset -- terminology
    Encoding Classification (by Anton Tagunov and Dan Kogai)
    Microsoft-related naming mess

    KS_C_5601-1987, GB2312, Big5, Shift_JIS

    Glossary

    character repertoire, coded character set (CCS), character encoding scheme (CES), charset (in MIME context), EUC, ISO-2022, UCS, UCS-2, Unicode, UTF, UTF-16

    See Also
    References

    ECMA, ECMA-035 (eq ISO-2022), IANA, Assigned Charset Names by IANA, ISO, RFC, UC, Unicode Glossary

    Other Notable Sites

    czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org: "Introduction to i18n"

    Offline sources

    CJKV Information Processing by Ken Lunde

    Encode::Symbol - Symbol Encodings

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    SEE ALSO

    Encode::TW - Taiwan-based Chinese Encodings

    SYNOPSIS
    DESCRIPTION
    NOTES
    BUGS
    SEE ALSO

    Encode::Unicode -- Various Unicode Transformation Formats

    SYNOPSIS
    ABSTRACT

    http://www.unicode.org/glossary/ says:, Quick Reference

    Size, Endianness, and BOM
    by size
    by endianness

    BOM as integer when fetched in network byte order

    Surrogate Pairs
    Error Checking
    SEE ALSO

    Encode::Unicode::UTF7 -- UTF-7 encoding

    SYNOPSIS
    ABSTRACT
    In Practice
    SEE ALSO

    Encode::lib::Encode::Alias, Encode::Alias - alias definitions to encodings

    SYNOPSIS
    DESCRIPTION

    As a simple string, As a qr// compiled regular expression, e.g.:, As a code reference, e.g.:

    Alias overloading
    SEE ALSO

    Encode::lib::Encode::CJKConstants, Encode::CJKConstants.pm -- Internally used by Encode::??::ISO_2022_*

    Encode::lib::Encode::CN::HZ, Encode::CN::HZ -- internally used by Encode::CN

    Encode::lib::Encode::Config, Encode::Config -- internally used by Encode

    Encode::lib::Encode::Encoding, Encode::Encoding - Encode Implementation Base Class

    SYNOPSIS
    DESCRIPTION
    Methods you should implement

    ->encode($string [,$check]), ->decode($octets [,$check]), ->cat_decode($destination, $octets, $offset, $terminator [,$check])

    Other methods defined in Encode::Encodings

    ->name, ->renew, ->renewed, ->perlio_ok(), ->needs_lines()

    Example: Encode::ROT13
    Why the heck Encode API is different?
    Compiled Encodings
    SEE ALSO

    Scheme 1, Scheme 2, Other Schemes

    Encode::lib::Encode::Guess, Encode::Guess -- Guesses encoding from data

    SYNOPSIS
    ABSTRACT
    DESCRIPTION

    Encode::Guess->set_suspects, Encode::Guess->add_suspects,
Encode::decode("Guess" ...), Encode::Guess->guess($data),
guess_encoding($data, [, list of suspects])

    CAVEATS
    TO DO
    SEE ALSO

    Encode::lib::Encode::JP::H2Z, Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*

    Encode::lib::Encode::JP::JIS7, Encode::JP::JIS7 -- internally used by Encode::JP

    Encode::lib::Encode::KR::2022_KR, Encode::KR::2022_KR -- internally used by Encode::KR

    Encode::lib::Encode::MIME::Header, Encode::MIME::Header -- MIME 'B' and 'Q' header encoding

    SYNOPSIS
    ABSTRACT
    DESCRIPTION
    BUGS
    SEE ALSO

    Encode::lib::Encode::PerlIO, Encode::PerlIO -- a detailed document on Encode and PerlIO

    Overview
    How does it work?
    Line Buffering
    How can I tell whether my encoding fully supports PerlIO ?
    SEE ALSO

    Encode::lib::Encode::Supported, Encode::Supported -- Encodings supported by Encode

    DESCRIPTION
    Encoding Names
    Supported Encodings
    Built-in Encodings
    Encode::Unicode -- other Unicode encodings
    Encode::Byte -- Extended ASCII

    ISO-8859 and corresponding vendor mappings, KOI8 - De Facto Standard for the Cyrillic world, gsm0338 - Hentai Latin 1

    CJK: Chinese, Japanese, Korean (Multibyte)

    Encode::CN -- Continental China, Encode::JP -- Japan, Encode::KR -- Korea, Encode::TW -- Taiwan, Encode::HanExtra -- More Chinese via CPAN, Encode::JIS2K -- JIS X 0213 encodings via CPAN

    Miscellaneous encodings

    Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess

    Unsupported encodings
      ISO-2022-JP-2 [RFC1554], ISO-2022-CN [RFC1922], Various HP-UX encodings,
Cyrillic encoding ISO-IR-111, ISO-8859-8-1 [Hebrew], ISIRI 3342, Iran
System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
Various Mac encodings, (Mac) Indic encodings
    Encoding vs. Charset -- terminology
    Encoding Classification (by Anton Tagunov and Dan Kogai)
    Microsoft-related naming mess

    KS_C_5601-1987, GB2312, Big5, Shift_JIS

    Glossary

    character repertoire, coded character set (CCS), character encoding scheme (CES), charset (in MIME context), EUC, ISO-2022, UCS, UCS-2, Unicode, UTF, UTF-16

    See Also
    References

    ECMA, ECMA-035 (eq ISO-2022), IANA, Assigned Charset Names by IANA, ISO, RFC, UC, Unicode Glossary

    Other Notable Sites

    czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org: "Introduction to i18n"

    Offline sources

    CJKV Information Processing by Ken Lunde

    Encode::lib::Encode::Unicode::UTF7, Encode::Unicode::UTF7 -- UTF-7 encoding

    SYNOPSIS
    ABSTRACT
    In Practice
    SEE ALSO

    Encode::lib::Encoder, Encode::Encoder -- Object Oriented Encoder

    SYNOPSIS
    ABSTRACT
    Description
    Predefined Methods

    $e = Encode::Encoder->new([$data, $encoding]);, encoder(),
$e->data([$data]), $e->encoding([$encoding]),
$e->bytes([$encoding])

    Example: base64 transcoder
    Operator Overloading
    SEE ALSO

    Encodencoding, encoding - allows you to write your script in non-ascii or non-utf8

    SYNOPSIS
    ABSTRACT
    Literal Conversions
    PerlIO layers for STD(IN|OUT)
    Implicit upgrading for byte strings
    FEATURES THAT REQUIRE 5.8.1

    "NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle

    USAGE

    use encoding [ENCNAME] ;, use encoding ENCNAME [ STDIN => ENCNAME_IN ...] ;, use encoding ENCNAME Filter=>1;, no encoding;

    The Filter Option
    Filter-related changes at Encode version 1.87
    CAVEATS
    NOT SCOPED
    DO NOT MIX MULTIPLE ENCODINGS
    tr/// with ranges

    Legend of characters above

    EXAMPLE - Greekperl
    KNOWN PROBLEMS

    literals in regex that are longer than 127 bytes, EBCDIC, format

    The Logic of :locale
    HISTORY
    SEE ALSO

    Encoder, Encode::Encoder -- Object Oriented Encoder

    SYNOPSIS
    ABSTRACT
    Description
    Predefined Methods

    $e = Encode::Encoder->new([$data, $encoding]);, encoder(),
$e->data([$data]), $e->encoding([$encoding]),
$e->bytes([$encoding])

    Example: base64 transcoder
    Operator Overloading
    SEE ALSO

    English - use nice English (or awk) names for ugly punctuation variables

    SYNOPSIS
    DESCRIPTION
    PERFORMANCE

    Env - perl module that imports environment variables as scalars or arrays

    SYNOPSIS
    DESCRIPTION
    LIMITATIONS
    AUTHOR

    Errno - System errno constants

    SYNOPSIS
    DESCRIPTION
    CAVEATS
    AUTHOR
    COPYRIGHT

    Exporter - Implements default import method for modules

    SYNOPSIS
    DESCRIPTION
    How to Export
    Selecting What To Export
    How to Import

    use ModuleName;, use ModuleName ();, use ModuleName qw(...);

    Advanced features
    Specialised Import Lists
    Exporting without using Exporter's import method
    Exporting without inheriting from Exporter
    Module Version Checking
    Managing Unknown Symbols
    Tag Handling Utility Functions
    Generating combined tags
    AUTOLOADed Constants

    Exporter::Heavy - Exporter guts

    SYNOPSIS
    DESCRIPTION

    ExtUtils::Command - utilities to replace common UNIX commands in Makefiles etc.

    SYNOPSIS
    DESCRIPTION

    cat

    eqtime

    rm_rf

    rm_f

    touch

    mv

    cp

    chmod

    mkpath

    test_f

    dos2unix

    SEE ALSO
    AUTHOR

    ExtUtils::Command::MM - Commands for the MM's to use in Makefiles

    SYNOPSIS
    DESCRIPTION

    test_harness

    pod2man

    warn_if_old_packlist

    perllocal_install

    uninstall

    ExtUtils::Constant - generate XS code to import C header constants

    SYNOPSIS
    DESCRIPTION
    USAGE

    IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF

    FUNCTIONS

    constant_types

    XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME

    autoload PACKAGE, VERSION, AUTOLOADER

    WriteMakefileSnippet

    WriteConstants ATTRIBUTE => VALUE [, ...], NAME, DEFAULT_TYPE, BREAKOUT_AT, NAMES, C_FILE, XS_FILE, SUBNAME, C_SUBNAME

    AUTHOR

    ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

    SYNOPSIS
    DESCRIPTION
    USAGE

    header

    memEQ_clause args_hashref

    dump_names arg_hashref, ITEM..

    assign arg_hashref, VALUE..

    return_clause arg_hashref, ITEM

    switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..

    params WHAT

    dogfood arg_hashref, ITEM..

    C_constant arg_hashref, ITEM.., name, type, value, macro, default, pre, post, def_pre, def_post, utf8, weight

    BUGS
    AUTHOR

    ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant

    SYNOPSIS
    DESCRIPTION
    USAGE

    C_stringify NAME

    perl_stringify NAME

    AUTHOR

    ExtUtils::Constant::XS, ExtUtils::Constant::Base - base class for ExtUtils::Constant objects

    SYNOPSIS
    DESCRIPTION
    BUGS
    AUTHOR

    ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications

    SYNOPSIS
    DESCRIPTION
    @EXPORT
    FUNCTIONS

    xsinit(), Examples, ldopts(), Examples, perl_inc(), ccflags(), ccdlflags(), ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules)

    EXAMPLES
    SEE ALSO
    AUTHOR

    ExtUtils::Install - install files from here to there

    SYNOPSIS
    DESCRIPTION
    Functions

    install

    install_default DISCOURAGED

    uninstall

    pm_to_blib

    _autosplit

    ENVIRONMENT

    PERL_INSTALL_ROOT

    AUTHOR
    LICENSE

    ExtUtils::Installed - Inventory management of installed modules

    SYNOPSIS
    DESCRIPTION
    USAGE
    FUNCTIONS

    new(), modules(), files(), directories(), directory_tree(), validate(), packlist(), version()

    EXAMPLE
    AUTHOR

    ExtUtils::Liblist - determine libraries to use and how to use them

    SYNOPSIS
    DESCRIPTION

    For static extensions, For dynamic extensions at build/link time, For dynamic extensions at load time

    EXTRALIBS
    LDLOADLIBS and LD_RUN_PATH
    BSLOADLIBS
    PORTABILITY
    VMS implementation
    Win32 implementation
    SEE ALSO

    ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass

    SYNOPSIS
    DESCRIPTION

    ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix

    SYNOPSIS
    DESCRIPTION
    Overridden methods
    AUTHOR
    SEE ALSO

    ExtUtils::MM_Any - Platform-agnostic MM methods

    SYNOPSIS
    DESCRIPTION
    METHODS
    Cross-platform helper methods
    Targets
    Init methods
    Tools
    File::Spec wrappers
    Misc
    AUTHOR

    ExtUtils::MM_BeOS - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION

    os_flavor

    init_linker

    ExtUtils::MM_Cygwin - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION

    os_flavor

    cflags

    replace_manpage_separator

    init_linker

    ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix

    SYNOPSIS
    DESCRIPTION
    Overridden methods

    os_flavor

    replace_manpage_separator

    AUTHOR
    SEE ALSO

    ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic

    SYNOPSIS
    DESCRIPTION

    ExtUtils::MM_NW5 - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION

    os_flavor

    init_platform, platform_constants

    const_cccmd

    static_lib

    dynamic_lib

    ExtUtils::MM_OS2 - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION
    METHODS

    init_dist

    init_linker

    os_flavor

    ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix

    SYNOPSIS
    DESCRIPTION
    Overridden methods
    AUTHOR
    SEE ALSO

    ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix

    SYNOPSIS
    DESCRIPTION
    Overridden methods

    os_flavor

    replace_manpage_separator

    AUTHOR
    SEE ALSO

    ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION
    METHODS
    Methods

    os_flavor

    c_o (o)

    cflags (o)

    const_cccmd (o)

    const_config (o)

    const_loadlibs (o)

    constants (o)

    depend (o)

    init_DEST

    init_dist

    dist (o)

    dist_basics (o)

    dist_ci (o)

    dist_core (o)

    dist_target

    tardist_target

    zipdist_target

    tarfile_target

    zipfile_target

    uutardist_target

    shdist_target

    dlsyms (o)

    dynamic_bs (o)

    dynamic_lib (o)

    exescan

    extliblist

    find_perl

    fixin

    force (o)

    guess_name

    has_link_code

    init_dirscan

    init_DIRFILESEP

    init_main

    init_others

    init_linker

    init_lib2arch

    init_PERL

    init_platform, platform_constants

    init_PERM

    init_xs

    install (o)

    installbin (o)

    linkext (o)

    lsdir

    macro (o)

    makeaperl (o)

    makefile (o)

    maybe_command

    needs_linking (o)

    nicetext

    parse_abstract

    parse_version

    pasthru (o)

    perl_script

    perldepend (o)

    perm_rw (o)

    perm_rwx (o)

    pm_to_blib

    post_constants (o)

    post_initialize (o)

    postamble (o)

    ppd

    prefixify

    processPL (o)

    quote_paren

    replace_manpage_separator

    cd

    oneliner

    quote_literal

    escape_newlines

    max_exec_len

    static (o)

    static_lib (o)

    staticmake (o)

    subdir_x (o)

    subdirs (o)

    test (o)

    test_via_harness (override)

    test_via_script (override)

    tools_other (o)

    tool_xsubpp (o)

    all_target

    top_targets (o)

    writedoc

    xs_c (o)

    xs_cpp (o)

    xs_o (o)

    SEE ALSO

    ExtUtils::MM_VMS - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION
    Methods always loaded

    wraplist

    Methods

    guess_name (override)

    find_perl (override)

    maybe_command (override)

    pasthru (override)

    pm_to_blib (override)

    perl_script (override)

    replace_manpage_separator

    init_DEST

    init_DIRFILESEP

    init_main (override)

    init_others (override)

    init_platform (override)

    platform_constants

    init_VERSION (override)

    constants (override)

    special_targets

    cflags (override)

    const_cccmd (override)

    tools_other (override)

    init_dist (override)

    c_o (override)

    xs_c (override)

    xs_o (override)

    dlsyms (override)

    dynamic_lib (override)

    static_lib (override)

    extra_clean_files

    zipfile_target, tarfile_target, shdist_target

    install (override)

    perldepend (override)

    makeaperl (override)

    nicetext (override)

    prefixify (override)

    cd

    oneliner

    echo

    quote_literal

    escape_newlines

    max_exec_len

    init_linker

    eliminate_macros

    fixpath

    os_flavor

    AUTHOR

    ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix

    SYNOPSIS
    DESCRIPTION
    Overridden methods
    AUTHOR
    SEE ALSO

    ExtUtils::MM_Win32 - methods to override UN*X behaviour in ExtUtils::MakeMaker

    SYNOPSIS
    DESCRIPTION
    Overridden methods

    dlsyms

    replace_manpage_separator

    maybe_command

    init_DIRFILESEP

    init_others

    init_platform, platform_constants

    special_targets

    static_lib

    dynamic_lib

    extra_clean_files

    init_linker

    perl_script

    xs_o

    pasthru

    oneliner

    cd

    max_exec_len

    os_flavor

    ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X

    SYNOPSIS
    DESCRIPTION
    Overriden methods

    xs_c

    xs_cpp

    xs_o

    max_exec_len

    os_flavor

    AUTHOR

    ExtUtils::MY - ExtUtils::MakeMaker subclass for customization

    SYNOPSIS
    DESCRIPTION

    ExtUtils::MakeMaker - Create a module Makefile

    SYNOPSIS
    DESCRIPTION
    How To Write A Makefile.PL
    Default Makefile Behaviour
    make test
    make testdb
    make install
    PREFIX and LIB attribute
    AFS users
    Static Linking of a new Perl Binary
    Determination of Perl Library and Installation Locations
    Which architecture dependent directory?
    Using Attributes and Parameters

    ABSTRACT, ABSTRACT_FROM, AUTHOR, BINARY_LOCATION, C, CCFLAGS, CONFIG, CONFIGURE, DEFINE, DESTDIR, DIR, DISTNAME, DISTVNAME, DL_FUNCS, DL_VARS, EXCLUDE_EXT, EXE_FILES, FIRST_MAKEFILE, FULLPERL, FULLPERLRUN, FULLPERLRUNINST, FUNCLIST, H, IMPORTS, INC, INCLUDE_EXT, INSTALLARCHLIB, INSTALLBIN, INSTALLDIRS, INSTALLMAN1DIR, INSTALLMAN3DIR, INSTALLPRIVLIB, INSTALLSCRIPT, INSTALLSITEARCH, INSTALLSITEBIN, INSTALLSITELIB, INSTALLSITEMAN1DIR, INSTALLSITEMAN3DIR, INSTALLVENDORARCH, INSTALLVENDORBIN, INSTALLVENDORLIB, INSTALLVENDORMAN1DIR, INSTALLVENDORMAN3DIR, INST_ARCHLIB, INST_BIN, INST_LIB, INST_MAN1DIR, INST_MAN3DIR, INST_SCRIPT, LD, LDDLFLAGS, LDFROM, LIB, LIBPERL_A, LIBS, LINKTYPE, MAKEAPERL, MAKEFILE_OLD, MAN1PODS, MAN3PODS, MAP_TARGET, MYEXTLIB, NAME, NEEDS_LINKING, NOECHO, NORECURS, NO_META, NO_VC, OBJECT, OPTIMIZE, PERL, PERL_CORE, PERLMAINCC, PERL_ARCHLIB, PERL_LIB, PERL_MALLOC_OK, PERLPREFIX, PERLRUN, PERLRUNINST, PERL_SRC, PERM_RW, PERM_RWX, PL_FILES, PM, PMLIBDIRS, PM_FILTER, POLLUTE, PPM_INSTALL_EXEC, PPM_INSTALL_SCRIPT, PREFIX, PREREQ_FATAL, PREREQ_PM, PREREQ_PRINT, PRINT_PREREQ, SITEPREFIX, SIGN, SKIP, TYPEMAPS, VENDORPREFIX, VERBINST, VERSION, VERSION_FROM, VERSION_SYM, XS, XSOPT, XSPROTOARG, XS_VERSION

    Additional lowercase attributes

    clean, depend, dist, dynamic_lib, linkext, macro, postamble, realclean, test, tool_autosplit

    Overriding MakeMaker Methods
    The End Of Cargo Cult Programming

    MAN3PODS => ' '

    Hintsfile support
    Distribution Support
       make distcheck,    make skipcheck,    make distclean,    make manifest,
  make distdir,   make disttest,    make tardist,    make dist,    make
uutardist,    make shdist,    make zipdist,    make ci
    Module Meta-Data
    Disabling an extension
    Other Handy Functions

    prompt

    ENVIRONMENT

    PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE

    SEE ALSO
    AUTHORS
    LICENSE

    ExtUtils::MakeMaker::Config - Wrapper around Config.pm

    SYNOPSIS
    DESCRIPTION

    ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker

    DESCRIPTION
    Module Installation

    How do I keep from installing man pages?, How do I use a module without installing it?

    Philosophy and History

    Why not just use <insert other build config tool here>?, What is Module::Build and how does it relate to MakeMaker?, pure perl. no make, no shell commands, easier to customize, cleaner internals, less cruft

    Module Writing

    How do I keep my $VERSION up to date without resetting it manually?, What's this META.yml thing and how did it get in my MANIFEST?!

    XS

    How to I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors?, How do I make two or more XS files coexist in the same directory?

    PATCHING
    AUTHOR
    SEE ALSO

    ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker

    SYNOPSIS
    DESCRIPTION
    The Mantra
    The Layout

    Makefile.PL, MANIFEST, lib/, t/, Changes, README, INSTALL, MANIFEST.SKIP, bin/

    SEE ALSO

    ExtUtils::MakeMaker::bytes - Version-agnostic bytes.pm

    SYNOPSIS
    DESCRIPTION

    ExtUtils::MakeMaker::vmsish - Platform-agnostic vmsish.pm

    SYNOPSIS
    DESCRIPTION

    ExtUtils::Manifest - utilities to write and check a MANIFEST file

    SYNOPSIS
    DESCRIPTION
    Functions

    mkmanifest

    manifind

    manicheck

    filecheck

    fullcheck

    skipcheck

    maniread

    manicopy

    maniadd

    MANIFEST
    MANIFEST.SKIP
    EXPORT_OK
    GLOBAL VARIABLES
    DIAGNOSTICS

    Not in MANIFEST: file, Skipping file, No such file: file, MANIFEST: $!, Added to MANIFEST: file

    ENVIRONMENT

    PERL_MM_MANIFEST_DEBUG

    SEE ALSO
    AUTHOR

    ExtUtils::Miniperl, writemain - write the C code for perlmain.c

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader

    SYNOPSIS
    DESCRIPTION

    ExtUtils::Mksymlists - write linker options files for dynamic extension

    SYNOPSIS
    DESCRIPTION

    DLBASE, DL_FUNCS, DL_VARS, FILE, FUNCLIST, IMPORTS, NAME

    AUTHOR
    REVISION

    ExtUtils::Packlist - manage .packlist files

    SYNOPSIS
    DESCRIPTION
    USAGE
    FUNCTIONS

    new(), read(), write(), validate(), packlist_file()

    EXAMPLE
    AUTHOR

    ExtUtils::testlib - add blib/* directories to @INC

    SYNOPSIS
    DESCRIPTION

    Fatal - replace functions with equivalents which succeed or die

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    Fcntl - load the C Fcntl.h defines

    SYNOPSIS
    DESCRIPTION
    NOTE
    EXPORTED SYMBOLS

    File::Basename - Parse file paths into directory, filename and suffix.

    SYNOPSIS
    DESCRIPTION

    fileparse

    basename

    dirname

    fileparse_set_fstype

    SEE ALSO

    File::CheckTree, validate - run many filetest checks on a tree

    SYNOPSIS
    DESCRIPTION
    AUTHOR
    HISTORY

    File::Compare - Compare files or filehandles

    SYNOPSIS
    DESCRIPTION
    RETURN
    AUTHOR

    File::Copy - Copy files or filehandles

    SYNOPSIS
    DESCRIPTION
    Special behaviour if syscopy is defined (OS/2, VMS and Win32)

    rmscopy($from,$to[,$date_flag])

    RETURN
    NOTES
    AUTHOR

    File::DosGlob - DOS like globbing and then some

    SYNOPSIS
    DESCRIPTION
    NOTES
    EXPORTS (by request only)
    BUGS
    AUTHOR
    HISTORY
    SEE ALSO

    File::Find - Traverse a directory tree.

    SYNOPSIS
    DESCRIPTION

    find, finddepth

    %options

    wanted, bydepth, preprocess, postprocess, follow, follow_fast, follow_skip, dangling_symlinks, no_chdir, untaint, untaint_pattern, untaint_skip

    The wanted function

    $File::Find::dir is the current directory name,, $_ is the current filename within that directory, $File::Find::name is the complete pathname to the file

    WARNINGS
    CAVEAT

    $dont_use_nlink, symlinks

    NOTES
    BUGS AND CAVEATS
    HISTORY

    File::Glob - Perl extension for BSD glob routine

    SYNOPSIS
    DESCRIPTION
    META CHARACTERS
    POSIX FLAGS

    GLOB_ERR, GLOB_LIMIT, GLOB_MARK, GLOB_NOCASE, GLOB_NOCHECK, GLOB_NOSORT, GLOB_BRACE, GLOB_NOMAGIC, GLOB_QUOTE, GLOB_TILDE, GLOB_CSH, GLOB_ALPHASORT

    DIAGNOSTICS

    GLOB_NOSPACE, GLOB_ABEND

    NOTES
    SEE ALSO
    AUTHOR

    File::Path - create or remove directory trees

    SYNOPSIS
    DESCRIPTION
    DIAGNOSTICS
    AUTHORS

    File::Spec - portably perform operations on file names

    SYNOPSIS
    DESCRIPTION
    METHODS

    canonpath, catdir, catfile, curdir, devnull, rootdir, tmpdir, updir, no_upwards, case_tolerant, file_name_is_absolute, path, join, splitpath, splitdir, catpath(), abs2rel, rel2abs()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    File::Spec::Cygwin - methods for Cygwin file specs

    SYNOPSIS
    DESCRIPTION

    canonpath

    file_name_is_absolute

    tmpdir (override)

    COPYRIGHT

    File::Spec::Epoc - methods for Epoc file specs

    SYNOPSIS
    DESCRIPTION

    canonpath()

    AUTHOR
    COPYRIGHT
    SEE ALSO

    File::Spec::Functions - portably perform operations on file names

    SYNOPSIS
    DESCRIPTION
    Exports
    COPYRIGHT
    SEE ALSO

    File::Spec::Mac - File::Spec for Mac OS (Classic)

    SYNOPSIS
    DESCRIPTION
    METHODS

    canonpath

    catdir()

    catfile

    curdir

    devnull

    rootdir

    tmpdir

    updir

    file_name_is_absolute

    path

    splitpath

    splitdir

    catpath

    abs2rel

    rel2abs

    AUTHORS
    COPYRIGHT
    SEE ALSO

    File::Spec::OS2 - methods for OS/2 file specs

    SYNOPSIS
    DESCRIPTION

    tmpdir, splitpath

    COPYRIGHT

    File::Spec::Unix - File::Spec for Unix, base for other File::Spec modules

    SYNOPSIS
    DESCRIPTION
    METHODS

    canonpath()

    catdir()

    catfile

    curdir

    devnull

    rootdir

    tmpdir

    updir

    no_upwards

    case_tolerant

    file_name_is_absolute

    path

    join

    splitpath

    splitdir

    catpath()

    abs2rel

    rel2abs()

    COPYRIGHT
    SEE ALSO

    File::Spec::VMS - methods for VMS file specs

    SYNOPSIS
    DESCRIPTION

    canonpath (override)

    catdir (override)

    catfile (override)

    curdir (override)

    devnull (override)

    rootdir (override)

    tmpdir (override)

    updir (override)

    case_tolerant (override)

    path (override)

    file_name_is_absolute (override)

    splitpath (override)

    splitdir (override)

    catpath (override)

    abs2rel (override)

    rel2abs (override)

    COPYRIGHT
    SEE ALSO

    File::Spec::Win32 - methods for Win32 file specs

    SYNOPSIS
    DESCRIPTION

    devnull

    tmpdir

    catfile

    canonpath

    splitpath

    splitdir

    catpath

    Note For File::Spec::Win32 Maintainers
    COPYRIGHT
    SEE ALSO

    File::Temp - return name and handle of a temporary file safely

    PORTABILITY
    SYNOPSIS
    DESCRIPTION
    OBJECT-ORIENTED INTERFACE

    new

    filename

    unlink_on_destroy

    DESTROY

    FUNCTIONS

    tempfile

    tempdir

    MKTEMP FUNCTIONS

    mkstemp

    mkstemps

    mkdtemp

    mktemp

    POSIX FUNCTIONS

    tmpnam

    tmpfile

    ADDITIONAL FUNCTIONS

    tempnam

    UTILITY FUNCTIONS

    unlink0

    cmpstat

    unlink1

    cleanup

    PACKAGE VARIABLES

    safe_level, STANDARD, MEDIUM, HIGH

    TopSystemUID

    $KEEP_ALL, $DEBUG

    WARNING
    Temporary files and NFS
    Forking
    BINMODE
    HISTORY
    SEE ALSO
    AUTHOR

    File::stat - by-name interface to Perl's built-in stat() functions

    SYNOPSIS
    DESCRIPTION
    BUGS
    NOTE
    AUTHOR

    FileCache - keep more files open than the system permits

    SYNOPSIS
    DESCRIPTION

    cacheout EXPR, cacheout MODE, EXPR

    CAVEATS
    BUGS

    FileHandle - supply object methods for filehandles

    SYNOPSIS
    DESCRIPTION

    $fh->print, $fh->printf, $fh->getline, $fh->getlines

    SEE ALSO

    Filter::Simple - Simplified source filtering

    SYNOPSIS
    DESCRIPTION
    The Problem
    A Solution
    Disabling or changing <no> behaviour
    All-in-one interface
    Filtering only specific components of source code

    "code", "code_no_comments", "executable", "executable_no_comments", "quotelike", "string", "regex", "all"

    Filtering only the code parts of source code

    Most source code ceases to be grammatically correct when it is broken up into the pieces between string literals and regexes. So the 'code' and 'code_no_comments' component filter behave slightly differently from the other partial filters described in the previous section.

    Using Filter::Simple with an explicit import subroutine
    Using Filter::Simple and Exporter together
    How it works
    AUTHOR
    COPYRIGHT

    Filter::Util::Call - Perl Source Filter Utility Module

    SYNOPSIS
    DESCRIPTION
    use Filter::Util::Call
    import()
    filter() and anonymous sub

    $_, $status, filter_read and filter_read_exact, filter_del

    EXAMPLES
    Example 1: A simple filter.
    Example 2: Using the context
    Example 3: Using the context within the filter
    Example 4: Using filter_del
    Filter::Simple
    AUTHOR
    DATE

    FindBin - Locate directory of original perl script

    SYNOPSIS
    DESCRIPTION
    EXPORTABLE VARIABLES
    KNOWN ISSUES
    KNOWN BUGS
    AUTHORS
    COPYRIGHT

    GDBM_File - Perl5 access to the gdbm library.

    SYNOPSIS
    DESCRIPTION
    AVAILABILITY
    BUGS
    SEE ALSO

    Getopt::Long - Extended processing of command line options

    SYNOPSIS
    DESCRIPTION
    Command Line Options, an Introduction
    Getting Started with Getopt::Long
    Simple options
    A little bit less simple options
    Mixing command line option with other arguments
    Options with values
    Options with multiple values
    Options with hash values
    User-defined subroutines to handle options
    Options with multiple names
    Case and abbreviations
    Summary of Option Specifications

    !, +, s, i, o, f, : type [ desttype ], : number [ desttype ], : + [ desttype ]

    Advanced Possibilities
    Object oriented interface
    Thread Safety
    Documentation and help texts
    Storing option values in a hash
    Bundling
    The lonesome dash
    Argument callback
    Configuring Getopt::Long

    default, posix_default, auto_abbrev, getopt_compat, gnu_compat, gnu_getopt, require_order, permute, bundling (default: disabled), bundling_override (default: disabled), ignore_case (default: enabled), ignore_case_always (default: disabled), auto_version (default:disabled), auto_help (default:disabled), pass_through (default: disabled), prefix, prefix_pattern, long_prefix_pattern, debug (default: disabled)

    Exportable Methods

    VersionMessage, -message, -msg, -exitval, -output, HelpMessage

    Return values and Errors
    Legacy
    Default destinations
    Alternative option starters
    Configuration variables
    Trouble Shooting
    GetOptions does not return a false result when an option is not supplied
    GetOptions does not split the command line correctly
    Undefined subroutine &main::GetOptions called
    How do I put a "-?" option into a Getopt::Long?
    AUTHOR
    COPYRIGHT AND DISCLAIMER

    Getopt::Std, getopt, getopts - Process single-character switches with switch clustering

    SYNOPSIS
    DESCRIPTION
    --help and --version

    Hash::Util - A selection of general-utility hash subroutines

    SYNOPSIS
    DESCRIPTION
    Restricted hashes

    lock_keys, unlock_keys

    lock_value, unlock_value

    lock_hash, unlock_hash

    hash_seed

    CAVEATS
    AUTHOR
    SEE ALSO

    I18N::Collate - compare 8-bit scalar data according to the current locale

    SYNOPSIS
    DESCRIPTION

    I18N::LangTags - functions for dealing with RFC3066-style language tags

    SYNOPSIS
    DESCRIPTION

    the function is_language_tag($lang1)

    the function extract_language_tags($whatever)

    the function same_language_tag($lang1, $lang2)

    the function similarity_language_tag($lang1, $lang2)

    the function is_dialect_of($lang1, $lang2)

    the function super_languages($lang1)

    the function locale2language_tag($locale_identifier)

    the function encode_language_tag($lang1)

    the function alternate_language_tags($lang1)

    the function @langs = panic_languages(@accept_languages)

    the function implicate_supers( ...languages... ), the function implicate_supers_strictly( ...languages... )

    ABOUT LOWERCASING
    ABOUT UNICODE PLAINTEXT LANGUAGE TAGS
    SEE ALSO
    COPYRIGHT
    AUTHOR

    I18N::LangTags::Detect - detect the user's language preferences

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS
    ENVIRONMENT
    SEE ALSO
    COPYRIGHT
    AUTHOR

    I18N::LangTags::List -- tags and names for human languages

    SYNOPSIS
    DESCRIPTION
    ABOUT LANGUAGE TAGS
    LIST OF LANGUAGES

    {ab} : Abkhazian, {ace} : Achinese, {ach} : Acoli, {ada} : Adangme, {ady} : Adyghe, {aa} : Afar, {afh} : Afrihili, {af} : Afrikaans, [{afa} : Afro-Asiatic (Other)], {ak} : Akan, {akk} : Akkadian, {sq} : Albanian, {ale} : Aleut, [{alg} : Algonquian languages], [{tut} : Altaic (Other)], {am} : Amharic, {i-ami} : Ami, [{apa} : Apache languages], {ar} : Arabic, {arc} : Aramaic, {arp} : Arapaho, {arn} : Araucanian, {arw} : Arawak, {hy} : Armenian, {an} : Aragonese, [{art} : Artificial (Other)], {ast} : Asturian, {as} : Assamese, [{ath} : Athapascan languages], [{aus} : Australian languages], [{map} : Austronesian (Other)], {av} : Avaric, {ae} : Avestan, {awa} : Awadhi, {ay} : Aymara, {az} : Azerbaijani, {ban} : Balinese, [{bat} : Baltic (Other)], {bal} : Baluchi, {bm} : Bambara, [{bai} : Bamileke languages], {bad} : Banda, [{bnt} : Bantu (Other)], {bas} : Basa, {ba} : Bashkir, {eu} : Basque, {btk} : Batak (Indonesia), {bej} : Beja, {be} : Belarusian, {bem} : Bemba, {bn} : Bengali, [{ber} : Berber (Other)], {bho} : Bhojpuri, {bh} : Bihari, {bik} : Bikol, {bin} : Bini, {bi} : Bislama, {bs} : Bosnian, {bra} : Braj, {br} : Breton, {bug} : Buginese, {bg} : Bulgarian, {i-bnn} : Bunun, {bua} : Buriat, {my} : Burmese, {cad} : Caddo, {car} : Carib, {ca} : Catalan, [{cau} : Caucasian (Other)], {ceb} : Cebuano, [{cel} : Celtic (Other)], [{cai} : Central American Indian (Other)], {chg} : Chagatai, [{cmc} : Chamic languages], {ch} : Chamorro, {ce} : Chechen, {chr} : Cherokee, {chy} : Cheyenne, {chb} : Chibcha, {ny} : Chichewa, {zh} : Chinese, {chn} : Chinook Jargon, {chp} : Chipewyan, {cho} : Choctaw, {cu} : Church Slavic, {chk} : Chuukese, {cv} : Chuvash, {cop} : Coptic, {kw} : Cornish, {co} : Corsican, {cr} : Cree, {mus} : Creek, [{cpe} : English-based Creoles and pidgins (Other)], [{cpf} : French-based Creoles and pidgins (Other)], [{cpp} : Portuguese-based Creoles and pidgins (Other)], [{crp} : Creoles and pidgins (Other)], {hr} : Croatian, [{cus} : Cushitic (Other)], {cs} : Czech, {dak} : Dakota, {da} : Danish, {dar} : Dargwa, {day} : Dayak, {i-default} : Default (Fallthru) Language, {del} : Delaware, {din} : Dinka, {dv} : Divehi, {doi} : Dogri, {dgr} : Dogrib, [{dra} : Dravidian (Other)], {dua} : Duala, {nl} : Dutch, {dum} : Middle Dutch (ca.1050-1350), {dyu} : Dyula, {dz} : Dzongkha, {efi} : Efik, {egy} : Ancient Egyptian, {eka} : Ekajuk, {elx} : Elamite, {en} : English, {enm} : Old English (1100-1500), {ang} : Old English (ca.450-1100), {i-enochian} : Enochian (Artificial), {myv} : Erzya, {eo} : Esperanto, {et} : Estonian, {ee} : Ewe, {ewo} : Ewondo, {fan} : Fang, {fat} : Fanti, {fo} : Faroese, {fj} : Fijian, {fi} : Finnish, [{fiu} : Finno-Ugrian (Other)], {fon} : Fon, {fr} : French, {frm} : Middle French (ca.1400-1600), {fro} : Old French (842-ca.1400), {fy} : Frisian, {fur} : Friulian, {ff} : Fulah, {gaa} : Ga, {gd} : Scots Gaelic, {gl} : Gallegan, {lg} : Ganda, {gay} : Gayo, {gba} : Gbaya, {gez} : Geez, {ka} : Georgian, {de} : German, {gmh} : Middle High German (ca.1050-1500), {goh} : Old High German (ca.750-1050), [{gem} : Germanic (Other)], {gil} : Gilbertese, {gon} : Gondi, {gor} : Gorontalo, {got} : Gothic, {grb} : Grebo, {grc} : Ancient Greek, {el} : Modern Greek, {gn} : Guarani, {gu} : Gujarati, {gwi} : Gwich'in, {hai} : Haida, {ht} : Haitian, {ha} : Hausa, {haw} : Hawaiian, {he} : Hebrew, {hz} : Herero, {hil} : Hiligaynon, {him} : Himachali, {hi} : Hindi, {ho} : Hiri Motu, {hit} : Hittite, {hmn} : Hmong, {hu} : Hungarian, {hup} : Hupa, {iba} : Iban, {is} : Icelandic, {io} : Ido, {ig} : Igbo, {ijo} : Ijo, {ilo} : Iloko, [{inc} : Indic (Other)], [{ine} : Indo-European (Other)], {id} : Indonesian, {inh} : Ingush, {ia} : Interlingua (International Auxiliary Language Association), {ie} : Interlingue, {iu} : Inuktitut, {ik} : Inupiaq, [{ira} : Iranian (Other)], {ga} : Irish, {mga} : Middle Irish (900-1200), {sga} : Old Irish (to 900), [{iro} : Iroquoian languages], {it} : Italian, {ja} : Japanese, {jv} : Javanese, {jrb} : Judeo-Arabic, {jpr} : Judeo-Persian, {kbd} : Kabardian, {kab} : Kabyle, {kac} : Kachin, {kl} : Kalaallisut, {xal} : Kalmyk, {kam} : Kamba, {kn} : Kannada, {kr} : Kanuri, {krc} : Karachay-Balkar, {kaa} : Kara-Kalpak, {kar} : Karen, {ks} : Kashmiri, {csb} : Kashubian, {kaw} : Kawi, {kk} : Kazakh, {kha} : Khasi, {km} : Khmer, [{khi} : Khoisan (Other)], {kho} : Khotanese, {ki} : Kikuyu, {kmb} : Kimbundu, {rw} : Kinyarwanda, {ky} : Kirghiz, {i-klingon} : Klingon, {kv} : Komi, {kg} : Kongo, {kok} : Konkani, {ko} : Korean, {kos} : Kosraean, {kpe} : Kpelle, {kro} : Kru, {kj} : Kuanyama, {kum} : Kumyk, {ku} : Kurdish, {kru} : Kurukh, {kut} : Kutenai, {lad} : Ladino, {lah} : Lahnda, {lam} : Lamba, {lo} : Lao, {la} : Latin, {lv} : Latvian, {lb} : Letzeburgesch, {lez} : Lezghian, {li} : Limburgish, {ln} : Lingala, {lt} : Lithuanian, {nds} : Low German, {art-lojban} : Lojban (Artificial), {loz} : Lozi, {lu} : Luba-Katanga, {lua} : Luba-Lulua, {lui} : Luiseno, {lun} : Lunda, {luo} : Luo (Kenya and Tanzania), {lus} : Lushai, {mk} : Macedonian, {mad} : Madurese, {mag} : Magahi, {mai} : Maithili, {mak} : Makasar, {mg} : Malagasy, {ms} : Malay, {ml} : Malayalam, {mt} : Maltese, {mnc} : Manchu, {mdr} : Mandar, {man} : Mandingo, {mni} : Manipuri, [{mno} : Manobo languages], {gv} : Manx, {mi} : Maori, {mr} : Marathi, {chm} : Mari, {mh} : Marshall, {mwr} : Marwari, {mas} : Masai, [{myn} : Mayan languages], {men} : Mende, {mic} : Micmac, {min} : Minangkabau, {i-mingo} : Mingo, [{mis} : Miscellaneous languages], {moh} : Mohawk, {mdf} : Moksha, {mo} : Moldavian, [{mkh} : Mon-Khmer (Other)], {lol} : Mongo, {mn} : Mongolian, {mos} : Mossi, [{mul} : Multiple languages], [{mun} : Munda languages], {nah} : Nahuatl, {nap} : Neapolitan, {na} : Nauru, {nv} : Navajo, {nd} : North Ndebele, {nr} : South Ndebele, {ng} : Ndonga, {ne} : Nepali, {new} : Newari, {nia} : Nias, [{nic} : Niger-Kordofanian (Other)], [{ssa} : Nilo-Saharan (Other)], {niu} : Niuean, {nog} : Nogai, {non} : Old Norse, [{nai} : North American Indian], {no} : Norwegian, {nb} : Norwegian Bokmal, {nn} : Norwegian Nynorsk, [{nub} : Nubian languages], {nym} : Nyamwezi, {nyn} : Nyankole, {nyo} : Nyoro, {nzi} : Nzima, {oc} : Occitan (post 1500), {oj} : Ojibwa, {or} : Oriya, {om} : Oromo, {osa} : Osage, {os} : Ossetian; Ossetic, [{oto} : Otomian languages], {pal} : Pahlavi, {i-pwn} : Paiwan, {pau} : Palauan, {pi} : Pali, {pam} : Pampanga, {pag} : Pangasinan, {pa} : Panjabi, {pap} : Papiamento, [{paa} : Papuan (Other)], {fa} : Persian, {peo} : Old Persian (ca.600-400 B.C.), [{phi} : Philippine (Other)], {phn} : Phoenician, {pon} : Pohnpeian, {pl} : Polish, {pt} : Portuguese, [{pra} : Prakrit languages], {pro} : Old Provencal (to 1500), {ps} : Pushto, {qu} : Quechua, {rm} : Raeto-Romance, {raj} : Rajasthani, {rap} : Rapanui, {rar} : Rarotongan, [{qaa - qtz} : Reserved for local use.], [{roa} : Romance (Other)], {ro} : Romanian, {rom} : Romany, {rn} : Rundi, {ru} : Russian, [{sal} : Salishan languages], {sam} : Samaritan Aramaic, {se} : Northern Sami, {sma} : Southern Sami, {smn} : Inari Sami, {smj} : Lule Sami, {sms} : Skolt Sami, [{smi} : Sami languages (Other)], {sm} : Samoan, {sad} : Sandawe, {sg} : Sango, {sa} : Sanskrit, {sat} : Santali, {sc} : Sardinian, {sas} : Sasak, {sco} : Scots, {sel} : Selkup, [{sem} : Semitic (Other)], {sr} : Serbian, {srr} : Serer, {shn} : Shan, {sn} : Shona, {sid} : Sidamo, {sgn-...} : Sign Languages, {bla} : Siksika, {sd} : Sindhi, {si} : Sinhalese, [{sit} : Sino-Tibetan (Other)], [{sio} : Siouan languages], {den} : Slave (Athapascan), [{sla} : Slavic (Other)], {sk} : Slovak, {sl} : Slovenian, {sog} : Sogdian, {so} : Somali, {son} : Songhai, {snk} : Soninke, {wen} : Sorbian languages, {nso} : Northern Sotho, {st} : Southern Sotho, [{sai} : South American Indian (Other)], {es} : Spanish, {suk} : Sukuma, {sux} : Sumerian, {su} : Sundanese, {sus} : Susu, {sw} : Swahili, {ss} : Swati, {sv} : Swedish, {syr} : Syriac, {tl} : Tagalog, {ty} : Tahitian, [{tai} : Tai (Other)], {tg} : Tajik, {tmh} : Tamashek, {ta} : Tamil, {i-tao} : Tao, {tt} : Tatar, {i-tay} : Tayal, {te} : Telugu, {ter} : Tereno, {tet} : Tetum, {th} : Thai, {bo} : Tibetan, {tig} : Tigre, {ti} : Tigrinya, {tem} : Timne, {tiv} : Tiv, {tli} : Tlingit, {tpi} : Tok Pisin, {tkl} : Tokelau, {tog} : Tonga (Nyasa), {to} : Tonga (Tonga Islands), {tsi} : Tsimshian, {ts} : Tsonga, {i-tsu} : Tsou, {tn} : Tswana, {tum} : Tumbuka, [{tup} : Tupi languages], {tr} : Turkish, {ota} : Ottoman Turkish (1500-1928), {crh} : Crimean Turkish, {tk} : Turkmen, {tvl} : Tuvalu, {tyv} : Tuvinian, {tw} : Twi, {udm} : Udmurt, {uga} : Ugaritic, {ug} : Uighur, {uk} : Ukrainian, {umb} : Umbundu, {und} : Undetermined, {ur} : Urdu, {uz} : Uzbek, {vai} : Vai, {ve} : Venda, {vi} : Vietnamese, {vo} : Volapuk, {vot} : Votic, [{wak} : Wakashan languages], {wa} : Walloon, {wal} : Walamo, {war} : Waray, {was} : Washo, {cy} : Welsh, {wo} : Wolof, {x-...} : Unregistered (Semi-Private Use), {xh} : Xhosa, {sah} : Yakut, {yao} : Yao, {yap} : Yapese, {ii} : Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd} : Zande, [{zap} : Zapotec], {zen} : Zenaga, {za} : Zhuang, {zu} : Zulu, {zun} : Zuni

    SEE ALSO
    COPYRIGHT AND DISCLAIMER
    AUTHOR

    I18N::Langinfo - query locale information

    SYNOPSIS
    DESCRIPTION
    EXPORT
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    IO - load various IO modules

    SYNOPSIS
    DESCRIPTION
    DEPRECATED

    IO::Dir - supply object methods for directory handles

    SYNOPSIS
    DESCRIPTION

    new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (), rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::File - supply object methods for filehandles

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile

    METHODS

    open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode( [LAYER] )

    NOTE
    SEE ALSO
    HISTORY

    IO::Handle - supply object methods for I/O handles

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new (), new_from_fd ( FD, MODE )

    METHODS

    $io->fdopen ( FD, MODE ), $io->opened, $io->getline, $io->getlines, $io->ungetc ( ORD ), $io->write ( BUF, LEN [, OFFSET ] ), $io->error, $io->clearerr, $io->sync, $io->flush, $io->printflush ( ARGS ), $io->blocking ( [ BOOL ] ), $io->untaint

    NOTE
    SEE ALSO
    BUGS
    HISTORY

    IO::Pipe - supply object methods for pipes

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [READER, WRITER] )

    METHODS

    reader ([ARGS]), writer ([ARGS]), handles ()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::Poll - Object interface to system poll call

    SYNOPSIS
    DESCRIPTION
    METHODS

    mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove ( IO ), handles( [ EVENT_MASK ] )

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::Seekable - supply seek based methods for I/O objects

    SYNOPSIS
    DESCRIPTION

    $io->getpos, $io->setpos, $io->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), $io->sysseek( POS, WHENCE ),
$io->tell

    SEE ALSO
    HISTORY

    IO::Select - OO interface to the select system call

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ HANDLES ] )

    METHODS

    add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read ( [ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ), count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )

    EXAMPLE
    AUTHOR
    COPYRIGHT

    IO::Socket - Object interface to socket communications

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    accept([PKG]), socketpair(DOMAIN, TYPE, PROTOCOL), atmark, connected, protocol, sockdomain, sockopt(OPT [, VAL]), socktype, timeout([VAL])

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::Socket::INET - Object interface for AF_INET domain sockets

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost ()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::Socket::UNIX - Object interface for AF_UNIX domain sockets

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    hostpath(), peerpath()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Dir, IO::Dir - supply object methods for directory handles

    SYNOPSIS
    DESCRIPTION

    new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (), rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::File, IO::File - supply object methods for filehandles

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile

    METHODS

    open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode( [LAYER] )

    NOTE
    SEE ALSO
    HISTORY

    IO::lib::IO::Handle, IO::Handle - supply object methods for I/O handles

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new (), new_from_fd ( FD, MODE )

    METHODS

    $io->fdopen ( FD, MODE ), $io->opened, $io->getline, $io->getlines, $io->ungetc ( ORD ), $io->write ( BUF, LEN [, OFFSET ] ), $io->error, $io->clearerr, $io->sync, $io->flush, $io->printflush ( ARGS ), $io->blocking ( [ BOOL ] ), $io->untaint

    NOTE
    SEE ALSO
    BUGS
    HISTORY

    IO::lib::IO::Pipe, IO::Pipe - supply object methods for pipes

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [READER, WRITER] )

    METHODS

    reader ([ARGS]), writer ([ARGS]), handles ()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Poll, IO::Poll - Object interface to system poll call

    SYNOPSIS
    DESCRIPTION
    METHODS

    mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove ( IO ), handles( [ EVENT_MASK ] )

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Seekable, IO::Seekable - supply seek based methods for I/O objects

    SYNOPSIS
    DESCRIPTION

    $io->getpos, $io->setpos, $io->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), $io->sysseek( POS, WHENCE ),
$io->tell

    SEE ALSO
    HISTORY

    IO::lib::IO::Select, IO::Select - OO interface to the select system call

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ HANDLES ] )

    METHODS

    add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read ( [ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ), count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )

    EXAMPLE
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Socket, IO::Socket - Object interface to socket communications

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    accept([PKG]), socketpair(DOMAIN, TYPE, PROTOCOL), atmark, connected, protocol, sockdomain, sockopt(OPT [, VAL]), socktype, timeout([VAL])

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Socket::INET, IO::Socket::INET - Object interface for AF_INET domain sockets

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost ()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IO::lib::IO::Socket::UNIX, IO::Socket::UNIX - Object interface for AF_UNIX domain sockets

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ARGS] )

    METHODS

    hostpath(), peerpath()

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IPC::Msg - SysV Msg IPC object class

    SYNOPSIS
    DESCRIPTION
    METHODS

    new ( KEY , FLAGS ), id, rcv ( BUF, LEN [, TYPE [, FLAGS ]] ), remove, set ( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), snd ( TYPE, MSG [, FLAGS ] ), stat

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IPC::Open2, open2 - open a process for both reading and writing

    SYNOPSIS
    DESCRIPTION
    WARNING
    SEE ALSO

    IPC::Open3, open3 - open a process for reading, writing, and error handling

    SYNOPSIS
    DESCRIPTION
    WARNING

    IPC::Semaphore - SysV Semaphore IPC object class

    SYNOPSIS
    DESCRIPTION
    METHODS

    new ( KEY , NSEMS , FLAGS ), getall, getncnt ( SEM ), getpid ( SEM ), getval ( SEM ), getzcnt ( SEM ), id, op ( OPLIST ), remove, set ( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N , VALUE ), stat

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IPC::SysV - SysV IPC constants

    SYNOPSIS
    DESCRIPTION

    ftok( PATH, ID )

    SEE ALSO
    AUTHORS
    COPYRIGHT

    IPC::SysV::Msg, IPC::Msg - SysV Msg IPC object class

    SYNOPSIS
    DESCRIPTION
    METHODS

    new ( KEY , FLAGS ), id, rcv ( BUF, LEN [, TYPE [, FLAGS ]] ), remove, set ( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), snd ( TYPE, MSG [, FLAGS ] ), stat

    SEE ALSO
    AUTHOR
    COPYRIGHT

    IPC::SysV::Semaphore, IPC::Semaphore - SysV Semaphore IPC object class

    SYNOPSIS
    DESCRIPTION
    METHODS

    new ( KEY , NSEMS , FLAGS ), getall, getncnt ( SEM ), getpid ( SEM ), getval ( SEM ), getzcnt ( SEM ), id, op ( OPLIST ), remove, set ( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N , VALUE ), stat

    SEE ALSO
    AUTHOR
    COPYRIGHT

    List::Util - A selection of general-utility list subroutines

    SYNOPSIS
    DESCRIPTION

    first BLOCK LIST, max LIST, maxstr LIST, min LIST, minstr LIST, reduce BLOCK LIST, shuffle LIST, sum LIST

    KNOWN BUGS
    SUGGESTED ADDITIONS
    COPYRIGHT

    List::Utilib::List::Util, List::Util - A selection of general-utility list subroutines

    SYNOPSIS
    DESCRIPTION

    first BLOCK LIST, max LIST, maxstr LIST, min LIST, minstr LIST, reduce BLOCK LIST, shuffle LIST, sum LIST

    KNOWN BUGS
    SUGGESTED ADDITIONS
    COPYRIGHT

    List::Utilib::Scalar::Util, Scalar::Util - A selection of general-utility scalar subroutines

    SYNOPSIS
    DESCRIPTION

    blessed EXPR, dualvar NUM, STRING, isvstring EXPR, isweak EXPR, looks_like_number EXPR, openhandle FH, refaddr EXPR, reftype EXPR, set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF

    KNOWN BUGS
    COPYRIGHT
    BLATANT PLUG

    Locale::Constants - constants for Locale codes

    SYNOPSIS
    DESCRIPTION
    KNOWN BUGS AND LIMITATIONS
    SEE ALSO

    Locale::Language, Locale::Country, Locale::Script, Locale::Currency

    AUTHOR
    COPYRIGHT

    Locale::Country - ISO codes for country identification (ISO 3166)

    SYNOPSIS
    DESCRIPTION

    alpha-2, alpha-3, numeric

    CONVERSION ROUTINES

    code2country( CODE, [ CODESET ] ), country2code( STRING, [ CODESET ] ), country_code2code( CODE, CODESET, CODESET )

    QUERY ROUTINES

    all_country_codes( [ CODESET ] ), all_country_names( [ CODESET ] )

    SEMI-PRIVATE ROUTINES
    alias_code
    rename_country
    EXAMPLES
    DOMAIN NAMES
    KNOWN BUGS AND LIMITATIONS
    SEE ALSO

    Locale::Language, Locale::Script, Locale::Currency, Locale::SubCountry, ISO 3166-1, http://www.iso.org/iso/en/prods-services/iso3166ma/index.html, http://www.egt.ie/standards/iso3166/iso3166-1-en.html, http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html

    AUTHOR
    COPYRIGHT

    Locale::Currency - ISO three letter codes for currency identification (ISO 4217)

    SYNOPSIS
    DESCRIPTION

    XTS, XXX

    CONVERSION ROUTINES

    code2currency(), currency2code()

    QUERY ROUTINES

    all_currency_codes(), all_currency_names()

    EXAMPLES
    KNOWN BUGS AND LIMITATIONS
    SEE ALSO

    Locale::Country, Locale::Script, ISO 4217:1995, http://www.bsi-global.com/iso4217currency

    AUTHOR
    COPYRIGHT

    Locale::Language - ISO two letter codes for language identification (ISO 639)

    SYNOPSIS
    DESCRIPTION
    CONVERSION ROUTINES

    code2language(), language2code()

    QUERY ROUTINES

    all_language_codes(), all_language_names()

    EXAMPLES
    KNOWN BUGS AND LIMITATIONS
    SEE ALSO

    Locale::Country, Locale::Script, Locale::Currency, ISO 639:1988 (E/F), http://lcweb.loc.gov/standards/iso639-2/langhome.html

    AUTHOR
    COPYRIGHT

    Locale::Maketext - framework for localization

    SYNOPSIS
    DESCRIPTION
    QUICK OVERVIEW
    METHODS
    Construction Methods
    The "maketext" Method

    $lh->fail_with or $lh->fail_with(PARAM), $lh->failure_handler_auto

    Utility Methods

    $language->quant($number, $singular), $language->quant($number, $singular,
$plural), $language->quant($number, $singular, $plural, $negative),
$language->numf($number), $language->sprintf($format, @items),
$language->language_tag(), $language->encoding()

    Language Handle Attributes and Internals
    LANGUAGE CLASS HIERARCHIES
    ENTRIES IN EACH LEXICON
    BRACKET NOTATION
    AUTO LEXICONS
    CONTROLLING LOOKUP FAILURE
    HOW TO USE MAKETEXT
    SEE ALSO
    COPYRIGHT AND DISCLAIMER
    AUTHOR

    Locale::Maketext::TPJ13 -- article about software localization

    SYNOPSIS
    DESCRIPTION
    Localization and Perl: gettext breaks, Maketext fixes
    A Localization Horror Story: It Could Happen To You
    The Linguistic View
    Breaking gettext
    Replacing gettext
    Buzzwords: Abstraction and Encapsulation
    Buzzword: Isomorphism
    Buzzword: Inheritance
    Buzzword: Concision
    The Devil in the Details
    The Proof in the Pudding: Localizing Web Sites
    References

    Locale::Script - ISO codes for script identification (ISO 15924)

    SYNOPSIS
    DESCRIPTION

    alpha-2, alpha-3, numeric

    SPECIAL CODES
    CONVERSION ROUTINES

    code2script( CODE, [ CODESET ] ), script2code( STRING, [ CODESET ] ), script_code2code( CODE, CODESET, CODESET )

    QUERY ROUTINES

    all_script_codes ( [ CODESET ] ), all_script_names ( [ CODESET ] )

    EXAMPLES
    KNOWN BUGS AND LIMITATIONS
    SEE ALSO

    Locale::Language, Locale::Currency, Locale::Country, ISO 15924, http://www.evertype.com/standards/iso15924/

    AUTHOR
    COPYRIGHT

    MIME::Base64 - Encoding and decoding of base64 strings

    SYNOPSIS
    DESCRIPTION

    encode_base64($str), encode_base64($str, $eol);, decode_base64($str)

    DIAGNOSTICS

    Premature end of base64 data, Premature padding of base64 data, Wide character in subroutine entry

    EXAMPLES
    COPYRIGHT
    SEE ALSO

    MIME::Base64::QuotedPrint, MIME::QuotedPrint - Encoding and decoding of quoted-printable strings

    SYNOPSIS
    DESCRIPTION

    encode_qp($str), encode_qp($str, $eol), encode_qp($str, $eol, $binmode), decode_qp($str);

    COPYRIGHT
    SEE ALSO

    MIME::QuotedPrint - Encoding and decoding of quoted-printable strings

    SYNOPSIS
    DESCRIPTION

    encode_qp($str), encode_qp($str, $eol), encode_qp($str, $eol, $binmode), decode_qp($str);

    COPYRIGHT
    SEE ALSO

    Math::BigFloat - Arbitrary size floating point math package

    SYNOPSIS
    DESCRIPTION
    Canonical notation
    Output
    mantissa(), exponent() and parts()
    Accuracy vs. Precision
    Rounding

    ffround ( +$scale ), ffround ( -$scale ), ffround ( 0 ), fround ( +$scale ), fround ( -$scale ) and fround ( 0 )

    METHODS
    accuracy
    precision()
    Autocreating constants
    Math library
    Using Math::BigInt::Lite
    BUGS
    CAVEATS

    stringify, bstr(), bdiv, Modifying and =, bpow, precision() vs. accuracy()

    SEE ALSO
    LICENSE
    AUTHORS

    Math::BigInt - Arbitrary size integer/float math package

    SYNOPSIS
    DESCRIPTION

    Input, Output

    METHODS
    config
    accuracy
    precision
    brsft
    new
    bnan
    bzero
    binf
    bone
    is_one()/is_zero()/is_nan()/is_inf()
    is_pos()/is_neg()
            $x->is_pos();                   # true if > 0
        $x->is_neg();                   # true if < 0
    is_odd()/is_even()/is_int()
    bcmp
    bacmp
    sign
    digit
    bneg
    babs
    bnorm
    bnot
    binc
    bdec
    badd
    bsub
    bmul
    bdiv
    bmod
    bmodinv
    bmodpow
    bpow
    blsft
    brsft
    band
    bior
    bxor
    bnot
    bsqrt
    bfac
    round
    bround
    bfround
    bfloor
    bceil
    bgcd
    blcm
    exponent
    mantissa
    parts
    copy
    as_int
    bsstr
    as_hex
    as_bin
    ACCURACY and PRECISION
    Precision P
    Accuracy A
    Fallback F
    Rounding mode R

    'trunc', 'even', 'odd', '+inf', '-inf', 'zero', Precision, Accuracy (significant digits), Setting/Accessing, Creating numbers, Usage, Precedence, Overriding globals, Local settings, Rounding, Default values, Remarks

    Infinity and Not a Number

    oct()/hex(), log(-inf), exp(), cos(), sin(), atan2()

    INTERNALS
    MATH LIBRARY
    SIGN
    mantissa(), exponent() and parts()
    EXAMPLES
      use Math::BigInt;
    Autocreating constants
    PERFORMANCE
    Alternative math libraries
    SUBCLASSING
    Subclassing Math::BigInt
    UPGRADING
    Auto-upgrade

    bsqrt(), div(), blog()

    BUGS

    broot() does not work, Out of Memory!, Fails to load Calc on Perl prior 5.6.0

    CAVEATS

    bstr(), bsstr() and 'cmp', int(), length, bdiv, infinity handling, Modifying and =, bpow, Overloading -$x, Mixing different object types, bsqrt(), brsft()

    LICENSE
    SEE ALSO
    AUTHORS

    Math::BigInt::Calc - Pure Perl module to support Math::BigInt

    SYNOPSIS
    DESCRIPTION
    STORAGE
    METHODS
    WRAP YOUR OWN
    LICENSE

    This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

    AUTHORS
    SEE ALSO

    Math::BigInt::CalcEmu - Emulate low-level math with BigInt code

    SYNOPSIS
    DESCRIPTION
    METHODS
    __emu_bxor
    __emu_band
    __emu_bior
    LICENSE

    This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

    AUTHORS
    SEE ALSO

    Math::BigRat - Arbitrary big rational numbers

    SYNOPSIS
    DESCRIPTION
    MATH LIBRARY
    METHODS
    new()
    numerator()
    denominator()
            $d = $x->denominator();
    parts()
    as_int()
    as_hex()
    as_bin()
    bfac()
    blog()
    bround()/round()/bfround()
    bmod()
    is_one()
    is_zero()
    is_pos()
    is_neg()
    is_int()
    is_odd()
    is_even()
    bceil()
    bfloor()
            $x->bfloor();
    bsqrt()
            $x->bsqrt();
    config
    BUGS

    inf handling (partial), NaN handling (partial), rounding (not implemented except for bceil/bfloor), $x ** $y where $y is not an integer, bmod(), blog(), bmodinv() and bmodpow() (partial)

    LICENSE
    SEE ALSO
    AUTHORS

    Math::Complex - complex numbers and associated mathematical functions

    SYNOPSIS
    DESCRIPTION
    OPERATIONS
    CREATION
    DISPLAYING
    CHANGED IN PERL 5.6
    USAGE
    ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO
    ERRORS DUE TO INDIGESTIBLE ARGUMENTS
    BUGS
    AUTHORS

    Math::Trig - trigonometric functions

    SYNOPSIS
    DESCRIPTION
    TRIGONOMETRIC FUNCTIONS

    tan

    ERRORS DUE TO DIVISION BY ZERO
    SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
    PLANE ANGLE CONVERSIONS
    RADIAL COORDINATE CONVERSIONS
    COORDINATE SYSTEMS
  • -D ANGLE CONVERSIONS

    cartesian_to_cylindrical, cartesian_to_spherical, cylindrical_to_cartesian, cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical

    • GREAT CIRCLE DISTANCES AND DIRECTIONS
    EXAMPLES
    CAVEAT FOR GREAT CIRCLE FORMULAS
    BUGS
    AUTHORS

    Memoize - Make functions faster by trading space for time

    SYNOPSIS
    DESCRIPTION
    DETAILS
    OPTIONS
    INSTALL
    NORMALIZER
    SCALAR_CACHE, LIST_CACHE

    MEMORY, HASH, TIE, FAULT, MERGE

    OTHER FACILITIES
    unmemoize
    flush_cache
    CAVEATS
    PERSISTENT CACHE SUPPORT
    EXPIRATION SUPPORT
    BUGS
    MAILING LIST
    AUTHOR
    COPYRIGHT AND LICENSE
    THANK YOU

    Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for Storable use

    DESCRIPTION

    Memoize::Expire - Plug-in module for automatic expiration of memoized values

    SYNOPSIS
    DESCRIPTION
    INTERFACE
     TIEHASH,  EXISTS,  STORE
    ALTERNATIVES
    CAVEATS
    AUTHOR
    SEE ALSO

    Memoize::ExpireFile - test for Memoize expiration semantics

    DESCRIPTION

    Memoize::ExpireTest - test for Memoize expiration semantics

    DESCRIPTION

    Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for Storable use

    DESCRIPTION

    Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for Storable use

    DESCRIPTION

    Memoize::Storable - store Memoized data in Storable database

    DESCRIPTION

    NDBM_File - Tied access to ndbm files

    SYNOPSIS
    DESCRIPTION

    O_RDONLY, O_WRONLY, O_RDWR

    DIAGNOSTICS
    ndbm store returned -1, errno 22, key "..." at ...
    BUGS AND WARNINGS

    NEXT - Provide a pseudo-class NEXT (et al) that allows method redispatch

    SYNOPSIS
    DESCRIPTION
    Enforcing redispatch
    Avoiding repetitions
    Invoking all versions of a method with a single call
    Using EVERY methods
    AUTHOR
    BUGS AND IRRITATIONS
    COPYRIGHT

    Net::Cmd - Network Command class (as used by FTP, SMTP etc)

    SYNOPSIS
    DESCRIPTION
    USER METHODS

    debug ( VALUE ), message (), code (), ok (), status (), datasend ( DATA ), dataend ()

    CLASS METHODS

    debug_print ( DIR, TEXT ), debug_text ( TEXT ), command ( CMD [, ARGS, ... ]), unsupported (), response (), parse_response ( TEXT ), getline (), ungetline ( TEXT ), rawdatasend ( DATA ), read_until_dot (), tied_fh ()

    EXPORTS
    AUTHOR
    COPYRIGHT

    Net::Config - Local configuration data for libnet

    SYNOPSYS
    DESCRIPTION
    METHODS

    requires_firewall HOST

    NetConfig VALUES

    nntp_hosts, snpp_hosts, pop3_hosts, smtp_hosts, ph_hosts, daytime_hosts, time_hosts, inet_domain, ftp_firewall, ftp_firewall_type, ftp_ext_passive, ftp_int_pasive, local_netmask, test_hosts, test_exists

    Net::Domain - Attempt to evaluate the current host's internet name and domain

    SYNOPSIS
    DESCRIPTION

    hostfqdn (), hostname (), hostdomain ()

    AUTHOR
    COPYRIGHT

    Net::FTP - FTP Client class

    SYNOPSIS
    DESCRIPTION
    OVERVIEW
    CONSTRUCTOR

    new ([ HOST ] [, OPTIONS ])

    METHODS

    login ([LOGIN [,PASSWORD [, ACCOUNT] ] ]), authorize ( [AUTH [, RESP]]), site (ARGS), ascii, binary, rename ( OLDNAME, NEWNAME ), delete ( FILENAME ), cwd ( [ DIR ] ), cdup (), pwd (), restart ( WHERE ), rmdir ( DIR [, RECURSE ]), mkdir ( DIR [, RECURSE ]), alloc ( SIZE [, RECORD_SIZE] ), ls ( [ DIR ] ), dir ( [ DIR ] ), get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] ), put ( LOCAL_FILE [, REMOTE_FILE ] ), put_unique ( LOCAL_FILE [, REMOTE_FILE ] ), append ( LOCAL_FILE [, REMOTE_FILE ] ), unique_name (), mdtm ( FILE ), size ( FILE ), supported ( CMD ), hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] ), nlst ( [ DIR ] ), list ( [ DIR ] ), retr ( FILE ), stor ( FILE ), stou ( FILE ), appe ( FILE ), port ( [ PORT ] ), pasv (), pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ), pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ), pasv_wait ( NON_PASV_SERVER ), abort (), quit ()

    Methods for the adventurous

    quot (CMD [,ARGS])

    THE dataconn CLASS

    read ( BUFFER, SIZE [, TIMEOUT ] ), write ( BUFFER, SIZE [, TIMEOUT ] ), bytes_read (), abort (), close ()

    UNIMPLEMENTED

    SMNT, HELP, MODE, SYST, STAT, STRU, REIN

    REPORTING BUGS
    AUTHOR
    SEE ALSO
    USE EXAMPLES

    http://www.csh.rit.edu/~adam/Progs/

    CREDITS
    COPYRIGHT

    Net::NNTP - NNTP Client class

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ HOST ] [, OPTIONS ])

    METHODS

    article ( [ MSGID|MSGNUM ], [FH] ), body ( [ MSGID|MSGNUM ], [FH] ), head ( [ MSGID|MSGNUM ], [FH] ), articlefh ( [ MSGID|MSGNUM ] ), bodyfh ( [ MSGID|MSGNUM ] ), headfh ( [ MSGID|MSGNUM ] ), nntpstat ( [ MSGID|MSGNUM ] ), group ( [ GROUP ] ), ihave ( MSGID [, MESSAGE ]), last (), date (), postok (), authinfo ( USER, PASS ), list (), newgroups ( SINCE [, DISTRIBUTIONS ]), newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]]), next (), post ( [ MESSAGE ] ), postfh (), slave (), quit ()

    Extension methods

    newsgroups ( [ PATTERN ] ), distributions (), subscriptions (), overview_fmt (), active_times (), active ( [ PATTERN ] ), xgtitle ( PATTERN ), xhdr ( HEADER, MESSAGE-SPEC ), xover ( MESSAGE-SPEC ), xpath ( MESSAGE-ID ), xpat ( HEADER, PATTERN, MESSAGE-SPEC), xrover, listgroup ( [ GROUP ] ), reader

    UNSUPPORTED
    DEFINITIONS

    MESSAGE-SPEC, PATTERN, Examples, [^]-], *bdc, [0-9a-zA-Z], a??d

    SEE ALSO
    AUTHOR
    COPYRIGHT

    Net::POP3 - Post Office Protocol 3 Client class (RFC1939)

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTOR

    new ( [ HOST ] [, OPTIONS ] 0

    METHODS

    auth ( USERNAME, PASSWORD ), user ( USER ), pass ( PASS ), login ( [ USER [, PASS ]] ), apop ( [ USER [, PASS ]] ), banner (), capa (), capabilities (), top ( MSGNUM [, NUMLINES ] ), list ( [ MSGNUM ] ), get ( MSGNUM [, FH ] ), getfh ( MSGNUM ), last (), popstat (), ping ( USER ), uidl ( [ MSGNUM ] ), delete ( MSGNUM ), reset (), quit ()

    NOTES
    SEE ALSO
    AUTHOR
    COPYRIGHT

    Net::Ping - check a remote host for reachability

    SYNOPSIS
    DESCRIPTION
    Functions

    Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device [, $tos ]]]]]);, $p->ping($host [, $timeout]);, $p->source_verify( { 0 | 1 } );, $p->service_check( { 0 | 1 } );, $p->tcp_service_check( { 0 | 1 } );, $p->hires( { 0 | 1 } );, $p->bind($local_addr);, $p->open($host);, $p->ack( [ $host ] );, $p->nack( $failed_ack_host );, $p->close();, pingecho($host [, $timeout]);

    NOTES
    INSTALL
    BUGS
    AUTHORS
    COPYRIGHT

    Net::SMTP - Simple Mail Transfer Protocol Client

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    CONSTRUCTOR

    new ( [ HOST ] [, OPTIONS ] )

    METHODS

    banner (), domain (), hello ( DOMAIN ), host (), etrn ( DOMAIN ), auth ( USERNAME, PASSWORD ), mail ( ADDRESS [, OPTIONS] ), send ( ADDRESS ), send_or_mail ( ADDRESS ), send_and_mail ( ADDRESS ), reset (), recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] ), to ( ADDRESS [, ADDRESS [...]] ), cc ( ADDRESS [, ADDRESS [...]] ), bcc ( ADDRESS [, ADDRESS [...]] ), data ( [ DATA ] ), expand ( ADDRESS ), verify ( ADDRESS ), help ( [ $subject ] ), quit ()

    ADDRESSES
    SEE ALSO
    AUTHOR
    COPYRIGHT

    Net::Time - time and daytime network client interface

    SYNOPSIS
    DESCRIPTION

    inet_time ( [HOST [, PROTOCOL [, TIMEOUT]]]), inet_daytime ( [HOST [, PROTOCOL [, TIMEOUT]]])

    AUTHOR
    COPYRIGHT

    Net::hostent - by-name interface to Perl's built-in gethost*() functions

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    NOTE
    AUTHOR

    Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions

    DESCRIPTION
    Where to get this document
    How to contribute to this document
    Author and Copyright Information
    Disclaimer
    Obtaining and installing libnet
    What is libnet ?
    Which version of perl do I need ?
    What other modules do I need ?
    What machines support libnet ?
    Where can I get the latest libnet release
    Using Net::FTP
    How do I download files from an FTP server ?
    How do I transfer files in binary mode ?
    How can I get the size of a file on a remote FTP server ?
    How can I get the modification time of a file on a remote FTP server ?
    How can I change the permissions of a file on a remote server ?
    Can I do a reget operation like the ftp command ?
    How do I get a directory listing from an FTP server ?
    Changing directory to "" does not fail ?
    I am behind a SOCKS firewall, but the Firewall option does not work ?
    I am behind an FTP proxy firewall, but cannot access machines outside ?
    My ftp proxy firewall does not listen on port 21
    Is it possible to change the file permissions of a file on an FTP server ?
    I have seen scripts call a method message, but cannot find it documented ?
    Why does Net::FTP not implement mput and mget methods
    Using Net::SMTP
    Why can't the part of an Email address after the @ be used as the hostname ?
    Why does Net::SMTP not do DNS MX lookups ?
    The verify method always returns true ?
    Debugging scripts
    How can I debug my scripts that use Net::* modules ?
    AUTHOR AND COPYRIGHT

    Net::netent - by-name interface to Perl's built-in getnet*() functions

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    NOTE
    AUTHOR

    Net::protoent - by-name interface to Perl's built-in getproto*() functions

    SYNOPSIS
    DESCRIPTION
    NOTE
    AUTHOR

    Net::servent - by-name interface to Perl's built-in getserv*() functions

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    NOTE
    AUTHOR

    Netrc, Net::Netrc - OO interface to users netrc file

    SYNOPSIS
    DESCRIPTION
    THE .netrc FILE

    machine name, default, login name, password string, account string, macdef name

    CONSTRUCTOR

    lookup ( MACHINE [, LOGIN ])

    METHODS

    login (), password (), account (), lpa ()

    AUTHOR
    SEE ALSO
    COPYRIGHT

    O - Generic interface to Perl Compiler backends

    SYNOPSIS
    DESCRIPTION
    CONVENTIONS
    IMPLEMENTATION
    BUGS
    AUTHOR

    ODBM_File - Tied access to odbm files

    SYNOPSIS
    DESCRIPTION

    O_RDONLY, O_WRONLY, O_RDWR

    DIAGNOSTICS
    odbm store returned -1, errno 22, key "..." at ...
    BUGS AND WARNINGS

    Opcode - Disable named opcodes when compiling perl code

    SYNOPSIS
    DESCRIPTION
    NOTE
    WARNING
    Operator Names and Operator Lists

    an operator name (opname), an operator tag name (optag), a negated opname or optag, an operator set (opset)

    Opcode Functions

    opcodes, opset (OP, ...), opset_to_ops (OPSET), opset_to_hex (OPSET), full_opset, empty_opset, invert_opset (OPSET), verify_opset (OPSET, ...), define_optag (OPTAG, OPSET), opmask_add (OPSET), opmask, opdesc (OP, ...), opdump (PAT)

    Manipulating Opsets
    TO DO (maybe)
    Predefined Opcode Tags

    :base_core, :base_mem, :base_loop, :base_io, :base_orig, :base_math, :base_thread, :default, :filesys_read, :sys_db, :browse, :filesys_open, :filesys_write, :subprocess, :ownprocess, :others, :still_to_be_decided, :dangerous

    SEE ALSO
    AUTHORS

    Opcode::Safe, Safe - Compile and execute code in restricted compartments

    SYNOPSIS
    DESCRIPTION

    a new namespace, an operator mask

    WARNING
    RECENT CHANGES
    Methods in class Safe

    permit (OP, ...), permit_only (OP, ...), deny (OP, ...), deny_only (OP, ...), trap (OP, ...), untrap (OP, ...), share (NAME, ...), share_from (PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING), rdo (FILENAME), root (NAMESPACE), mask (MASK)

    Some Safety Issues

    Memory, CPU, Snooping, Signals, State Changes

    AUTHOR

    Opcode::ops, ops - Perl pragma to restrict unsafe operations when compiling

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    POSIX - Perl interface to IEEE Std 1003.1

    SYNOPSIS
    DESCRIPTION
    NOTE
    CAVEATS
    FUNCTIONS

    _exit, abort, abs, access, acos, alarm, asctime, asin, assert, atan, atan2, atexit, atof, atoi, atol, bsearch, calloc, ceil, chdir, chmod, chown, clearerr, clock, close, closedir, cos, cosh, creat, ctermid, ctime, cuserid, difftime, div, dup, dup2, errno, execl, execle, execlp, execv, execve, execvp, exit, exp, fabs, fclose, fcntl, fdopen, feof, ferror, fflush, fgetc, fgetpos, fgets, fileno, floor, fmod, fopen, fork, fpathconf, fprintf, fputc, fputs, fread, free, freopen, frexp, fscanf, fseek, fsetpos, fstat, fsync, ftell, fwrite, getc, getchar, getcwd, getegid, getenv, geteuid, getgid, getgrgid, getgrnam, getgroups, getlogin, getpgrp, getpid, getppid, getpwnam, getpwuid, gets, getuid, gmtime, isalnum, isalpha, isatty, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, kill, labs, ldexp, ldiv, link, localeconv, localtime, log, log10, longjmp, lseek, malloc, mblen, mbstowcs, mbtowc, memchr, memcmp, memcpy, memmove, memset, mkdir, mkfifo, mktime, modf, nice, offsetof, open, opendir, pathconf, pause, perror, pipe, pow, printf, putc, putchar, puts, qsort, raise, rand, read, readdir, realloc, remove, rename, rewind, rewinddir, rmdir, scanf, setgid, setjmp, setlocale, setpgid, setsid, setuid, sigaction, siglongjmp, sigpending, sigprocmask, sigsetjmp, sigsuspend, sin, sinh, sleep, sprintf, sqrt, srand, sscanf, stat, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strerror, strftime, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtod, strtok, strtol, strtoul, strxfrm, sysconf, system, tan, tanh, tcdrain, tcflow, tcflush, tcgetpgrp, tcsendbreak, tcsetpgrp, time, times, tmpfile, tmpnam, tolower, toupper, ttyname, tzname, tzset, umask, uname, ungetc, unlink, utime, vfprintf, vprintf, vsprintf, wait, waitpid, wcstombs, wctomb, write

    CLASSES
    POSIX::SigAction

    new, handler, mask, flags, safe

    POSIX::SigSet

    new, addset, delset, emptyset, fillset, ismember

    POSIX::Termios

    new, getattr, getcc, getcflag, getiflag, getispeed, getlflag, getoflag, getospeed, setattr, setcc, setcflag, setiflag, setispeed, setlflag, setoflag, setospeed, Baud rate values, Terminal interface values, c_cc field values, c_cflag field values, c_iflag field values, c_lflag field values, c_oflag field values

    PATHNAME CONSTANTS

    Constants

    POSIX CONSTANTS

    Constants

    SYSTEM CONFIGURATION

    Constants

    ERRNO

    Constants

    FCNTL

    Constants

    FLOAT

    Constants

    LIMITS

    Constants

    LOCALE

    Constants

    MATH

    Constants

    SIGNAL

    Constants

    STAT

    Constants, Macros

    STDLIB

    Constants

    STDIO

    Constants

    TIME

    Constants

    UNISTD

    Constants

    WAIT

    Constants, WNOHANG, WUNTRACED, Macros, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG

    PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space

    SYNOPSIS
    DESCRIPTION

    :unix, :stdio, :perlio, :crlf, :mmap, :utf8, :bytes, :raw, :pop, :win32

    Custom Layers

    :encoding, :via

    Alternatives to raw
    Defaults and how to override them
    Querying the layers of filehandles
    AUTHOR
    SEE ALSO

    PerlIO::encoding - encoding layer

    SYNOPSIS
    DESCRIPTION
    SEE ALSO

    PerlIO::scalar - in-memory IO, scalar IO

    SYNOPSIS
    DESCRIPTION
    IMPLEMENTATION NOTE

    PerlIO::via - Helper class for PerlIO layers implemented in perl

    SYNOPSIS
    DESCRIPTION
    EXPECTED METHODS

    $class->PUSHED([$mode[,$fh]]), $obj->POPPED([$fh]),
$obj->UTF8($bellowFlag,[$fh]), $obj->OPEN($path,$mode[,$fh]),
$obj->BINMODE([,$fh]), $obj->FDOPEN($fd[,$fh]),
$obj->SYSOPEN($path,$imode,$perm,[,$fh]), $obj->FILENO($fh),
$obj->READ($buffer,$len,$fh), $obj->WRITE($buffer,$fh), $obj->FILL($fh),
$obj->CLOSE($fh), $obj->SEEK($posn,$whence,$fh), $obj->TELL($fh),
$obj->UNREAD($buffer,$fh), $obj->FLUSH($fh), $obj->SETLINEBUF($fh),
$obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh)

    EXAMPLES
    Example - a Hexadecimal Handle

    PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings

    SYNOPSIS
    DESCRIPTION
    REQUIRED MODULES
    SEE ALSO
    ACKNOWLEDGEMENTS
    COPYRIGHT

    Pod::Checker, podchecker() - check pod documents for syntax errors

    SYNOPSIS
    OPTIONS/ARGUMENTS
    podchecker()

    -warnings => val

    DESCRIPTION
    DIAGNOSTICS
    Errors

    empty =headn, =over on line N without closing =back, =item without previous =over, =back without previous =over, No argument for =begin, =end without =begin, Nested =begin's, =for without formatter specification, unresolved internal link NAME, Unknown command "CMD", Unknown interior-sequence "SEQ", nested commands CMD<...CMD<...>...>, garbled entity STRING, Entity number out of range, malformed link L<>, nonempty Z<>, empty X<>, Spurious text after =pod / =cut, Spurious character(s) after =back

    Warnings

    multiple occurrence of link target name, line containing nothing but whitespace in paragraph, file does not start with =head, previous =item has no contents, preceding non-item paragraph(s), =item type mismatch (one vs. two), N unescaped <> in paragraph, Unknown entity, No items in =over, No argument for =item, empty section in previous paragraph, Verbatim paragraph in NAME section, =headn without preceding higher level

    Hyperlinks

    ignoring leading/trailing whitespace in link, (section) in '$page' deprecated, alternative text/node '%s' contains non-escaped | or /

    RETURN VALUE
    EXAMPLES
    INTERFACE

    Pod::Checker->new( %options )

    $checker->poderror( @args ), $checker->poderror( {%opts}, @args )

    $checker->num_errors()

    $checker->num_warnings()

    $checker->name()

    $checker->node()

    $checker->idx()

    $checker->hyperlink()

    AUTHOR

    Pod::Find - find POD documents in directory trees

    SYNOPSIS
    DESCRIPTION
    pod_find( { %opts } , @directories )

    -verbose => 1, -perl => 1, -script => 1, -inc => 1

    simplify_name( $str )
    pod_where( { %opts }, $pod )

    -inc => 1, -dirs => [ $dir1, $dir2, ... ], -verbose => 1

    contains_pod( $file , $verbose )
    AUTHOR
    SEE ALSO

    Pod::Html - module to convert pod files to HTML

    SYNOPSIS
    DESCRIPTION
    ARGUMENTS

    backlink, cachedir, css, flush, header, help, hiddendirs, htmldir, htmlroot, index, infile, libpods, netscape, outfile, podpath, podroot, quiet, recurse, title, verbose

    EXAMPLE
    ENVIRONMENT
    AUTHOR
    SEE ALSO
    COPYRIGHT

    Pod::InputObjects - objects representing POD input paragraphs, commands, etc.

    SYNOPSIS
    REQUIRES
    EXPORTS
    DESCRIPTION

    package Pod::InputSource, package Pod::Paragraph, package Pod::InteriorSequence, package Pod::ParseTree

    Pod::InputSource
    new()
    name()
    handle()
    was_cutting()
    Pod::Paragraph
    Pod::Paragraph->new()
    $pod_para->cmd_name()
    $pod_para->text()
    $pod_para->raw_text()
    $pod_para->cmd_prefix()
    $pod_para->cmd_separator()
    $pod_para->parse_tree()
    $pod_para->file_line()
    Pod::InteriorSequence
    Pod::InteriorSequence->new()
    $pod_seq->cmd_name()
    $pod_seq->prepend()
    $pod_seq->append()
    $pod_seq->nested()
    $pod_seq->raw_text()
    $pod_seq->left_delimiter()
    $pod_seq->right_delimiter()
    $pod_seq->parse_tree()
    $pod_seq->file_line()
    Pod::InteriorSequence::DESTROY()
    Pod::ParseTree
    Pod::ParseTree->new()
    $ptree->top()
    $ptree->children()
    $ptree->prepend()
    $ptree->append()
    $ptree->raw_text()
    Pod::ParseTree::DESTROY()
    SEE ALSO
    AUTHOR

    Pod::LaTeX - Convert Pod data to formatted Latex

    SYNOPSIS
    DESCRIPTION
    OBJECT METHODS

    initialize

    Data Accessors

    AddPreamble

    AddPostamble

    Head1Level

    Label

    LevelNoNum

    MakeIndex

    ReplaceNAMEwithSection

    StartWithNewPage

    TableOfContents

    UniqueLabels

    UserPreamble

    UserPostamble

    Lists

    Subclassed methods

    begin_pod

    end_pod

    command

    verbatim

    textblock

    interior_sequence

    List Methods

    begin_list

    end_list

    add_item

    Methods for headings

    head

    Internal methods

    _output

    _replace_special_chars

    _replace_special_chars_late

    _create_label

    _create_index

    _clean_latex_commands

    _split_delimited

    NOTES
    SEE ALSO
    AUTHORS
    COPYRIGHT
    REVISION

    Pod::Man - Convert POD data to formatted *roff input

    SYNOPSIS
    DESCRIPTION

    center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, name, quotes, release, section

    DIAGNOSTICS

    roff font should be 1 or 2 chars, not "%s", Invalid link %s, Invalid quote specification "%s", %s:%d: Unknown command paragraph "%s", %s:%d: Unknown escape E<%s>, %s:%d: Unknown formatting code %s, %s:%d: Unmatched =back

    BUGS
    CAVEATS
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::ParseLink - Parse an L<> formatting code in POD text

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::ParseUtils - helpers for POD parsing and conversion

    SYNOPSIS
    DESCRIPTION
    Pod::List

    Pod::List->new()

    $list->file()

    $list->start()

    $list->indent()

    $list->type()

    $list->rx()

    $list->item()

    $list->parent()

    $list->tag()

    Pod::Hyperlink

    Pod::Hyperlink->new()

    $link->parse($string)

    $link->markup($string)

    $link->text()

    $link->warning()

    $link->file(), $link->line()

    $link->page()

    $link->node()

    $link->alttext()

    $link->type()

    $link->link()

    Pod::Cache

    Pod::Cache->new()

    $cache->item()

    $cache->find_page($name)

    Pod::Cache::Item

    Pod::Cache::Item->new()

    $cacheitem->page()

    $cacheitem->description()

    $cacheitem->path()

    $cacheitem->file()

    $cacheitem->nodes()

    $cacheitem->find_node($name)

    $cacheitem->idx()

    AUTHOR
    SEE ALSO

    Pod::Parser - base class for creating POD filters and translators

    SYNOPSIS
    REQUIRES
    EXPORTS
    DESCRIPTION
    QUICK OVERVIEW
    PARSING OPTIONS

    -want_nonPODs (default: unset), -process_cut_cmd (default: unset), -warnings (default: unset)

    RECOMMENDED SUBROUTINE/METHOD OVERRIDES
    command()

    $cmd, $text, $line_num, $pod_para

    verbatim()

    $text, $line_num, $pod_para

    textblock()

    $text, $line_num, $pod_para

    interior_sequence()
    OPTIONAL SUBROUTINE/METHOD OVERRIDES
    new()
    initialize()
    begin_pod()
    begin_input()
    end_input()
    end_pod()
    preprocess_line()
    preprocess_paragraph()
    METHODS FOR PARSING AND PROCESSING
    parse_text()

    -expand_seq => code-ref|method-name, -expand_text => code-ref|method-name, -expand_ptree => code-ref|method-name

    interpolate()
    parse_paragraph()
    parse_from_filehandle()
    parse_from_file()
    ACCESSOR METHODS
    errorsub()
    cutting()
    parseopts()
    output_file()
    output_handle()
    input_file()
    input_handle()
    input_streams()
    top_stream()
    PRIVATE METHODS AND DATA
    _push_input_stream()
    _pop_input_stream()
    TREE-BASED PARSING
    SEE ALSO
    AUTHOR

    Pod::Perldoc::ToChecker - let Perldoc check Pod for errors

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToMan - let Perldoc render Pod as man pages

    SYNOPSIS
    DESCRIPTION
    CAVEAT
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff

    SYNOPSIS
    DESCRIPTION
    CAVEAT
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToText - let Perldoc render Pod as plaintext

    SYNOPSIS
    DESCRIPTION
    CAVEAT
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    AUTHOR

    Pod::Perldoc::ToXml - let Perldoc render Pod as XML

    SYNOPSIS
    DESCRIPTION
    SEE ALSO
    COPYRIGHT AND DISCLAIMERS
    AUTHOR

    Pod::PlainText - Convert POD data to formatted ASCII text

    SYNOPSIS
    DESCRIPTION

    alt, indent, loose, sentence, width

    DIAGNOSTICS

    Bizarre space in item, Can't open %s for reading: %s, Unknown escape: %s, Unknown sequence: %s, Unmatched =back

    RESTRICTIONS
    NOTES
    SEE ALSO
    AUTHOR

    Pod::Plainer - Perl extension for converting Pod to old style Pod.

    SYNOPSIS
    DESCRIPTION
    EXPORT
    AUTHOR
    SEE ALSO

    Pod::Select, podselect() - extract selected sections of POD from input

    SYNOPSIS
    REQUIRES
    EXPORTS
    DESCRIPTION
    SECTION SPECIFICATIONS
    RANGE SPECIFICATIONS
    OBJECT METHODS
    curr_headings()
    select()
    add_selection()
    clear_selections()
    match_section()
    is_selected()
    EXPORTED FUNCTIONS
    podselect()

    -output, -sections, -ranges

    PRIVATE METHODS AND DATA
    _compile_section_spec()
    $self->{_SECTION_HEADINGS}
    $self->{_SELECTED_SECTIONS}
    SEE ALSO
    AUTHOR

    Pod::Text - Convert POD data to formatted ASCII text

    SYNOPSIS
    DESCRIPTION

    alt, code, indent, loose, margin, quotes, sentence, width

    DIAGNOSTICS

    Bizarre space in item, Item called without tag, Can't open %s for reading: %s, Invalid quote specification "%s", %s:%d: Unknown command paragraph: %s, %s:%d: Unknown escape: %s, %s:%d: Unknown formatting code: %s, %s:%d: Unmatched =back

    RESTRICTIONS
    NOTES
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::Text::Color - Convert POD data to formatted color ASCII text

    SYNOPSIS
    DESCRIPTION
    BUGS
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::Text::Overstrike - Convert POD data to formatted overstrike text

    SYNOPSIS
    DESCRIPTION
    BUGS
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::Text::Termcap - Convert POD data to ASCII text with format escapes

    SYNOPSIS
    DESCRIPTION
    NOTES
    SEE ALSO
    AUTHOR
    COPYRIGHT AND LICENSE

    Pod::Usage, pod2usage() - print a usage message from embedded pod documentation

    SYNOPSIS
    ARGUMENTS

    -message, -msg, -exitval, -verbose, -section, -output, -input, -pathlist, -noperldoc

    DESCRIPTION
    EXAMPLES
    Recommended Use
    CAVEATS
    AUTHOR
    ACKNOWLEDGEMENTS

    SDBM_File - Tied access to sdbm files

    SYNOPSIS
    DESCRIPTION

    O_RDONLY, O_WRONLY, O_RDWR

    DIAGNOSTICS
    sdbm store returned -1, errno 22, key "..." at ...
    BUGS AND WARNINGS

    Safe - Compile and execute code in restricted compartments

    SYNOPSIS
    DESCRIPTION

    a new namespace, an operator mask

    WARNING
    RECENT CHANGES
    Methods in class Safe

    permit (OP, ...), permit_only (OP, ...), deny (OP, ...), deny_only (OP, ...), trap (OP, ...), untrap (OP, ...), share (NAME, ...), share_from (PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING), rdo (FILENAME), root (NAMESPACE), mask (MASK)

    Some Safety Issues

    Memory, CPU, Snooping, Signals, State Changes

    AUTHOR

    Scalar::Util - A selection of general-utility scalar subroutines

    SYNOPSIS
    DESCRIPTION

    blessed EXPR, dualvar NUM, STRING, isvstring EXPR, isweak EXPR, looks_like_number EXPR, openhandle FH, refaddr EXPR, reftype EXPR, set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF

    KNOWN BUGS
    COPYRIGHT
    BLATANT PLUG

    Search::Dict, look - search for key in dictionary file

    SYNOPSIS
    DESCRIPTION

    SelectSaver - save and restore selected file handle

    SYNOPSIS
    DESCRIPTION

    SelfLoader - load functions only on demand

    SYNOPSIS
    DESCRIPTION
    The __DATA__ token
    SelfLoader autoloading
    Autoloading and package lexicals
    SelfLoader and AutoLoader
    __DATA__, __END__, and the FOOBAR::DATA filehandle.
    Classes and inherited methods.
    Multiple packages and fully qualified subroutine names

    Shell - run shell commands transparently within perl

    SYNOPSIS
    DESCRIPTION
    Caveats
    Escaping Magic Characters
    Configuration
    BUGS
    AUTHOR

    Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators

    SYNOPSIS
    DESCRIPTION

    inet_aton HOSTNAME, inet_ntoa IP_ADDRESS, INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE, sockaddr_family SOCKADDR, sockaddr_in PORT, ADDRESS, sockaddr_in SOCKADDR_IN, pack_sockaddr_in PORT, IP_ADDRESS, unpack_sockaddr_in SOCKADDR_IN, sockaddr_un PATHNAME, sockaddr_un SOCKADDR_UN, pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN

    Storable - persistence for Perl data structures

    SYNOPSIS
    DESCRIPTION
    MEMORY STORE
    ADVISORY LOCKING
    SPEED
    CANONICAL REPRESENTATION
    CODE REFERENCES
    FORWARD COMPATIBILITY

    utf8 data, restricted hashes, files from future versions of Storable

    ERROR REPORTING
    WIZARDS ONLY
    Hooks

    STORABLE_freeze obj, cloning, STORABLE_thaw obj, cloning, serialized, .., STORABLE_attach class, cloning, serialized

    Predicates

    Storable::last_op_in_netorder, Storable::is_storing, Storable::is_retrieving

    Recursion
    Deep Cloning
    Storable magic
    EXAMPLES
    WARNING
    BUGS
    1. bit data in perl 5.6.0 and 5.6.1
    CREDITS
    AUTHOR
    SEE ALSO

    Switch - A switch statement for Perl

    VERSION
    SYNOPSIS
    BACKGROUND
    DESCRIPTION
    Allowing fall-through
    Automating fall-through
    Alternative syntax
    Higher-order Operations
    DEPENDENCIES
    AUTHOR
    BUGS
    LIMITATIONS
    COPYRIGHT

    Symbol - manipulate Perl symbols and their names

    SYNOPSIS
    DESCRIPTION
    BUGS

    Sys::Hostname - Try every conceivable way to get hostname

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3) calls

    VERSION
    SYNOPSIS
    DESCRIPTION
    EXPORTS
    FUNCTIONS

    openlog($ident, $logopt, $facility), syslog($priority, $message), syslog($priority, $format, @args), Note, setlogmask($mask_priority), setlogsock($sock_type), setlogsock($sock_type, $stream_location) (added in 5.004_02), closelog()

    EXAMPLES
    CONSTANTS
    Facilities
    Levels
    DIAGNOSTICS

    Invalid argument passed to setlogsock, no connection to syslog available, stream passed to setlogsock, but %s is not writable, stream passed to setlogsock, but could not find any device, tcp passed to setlogsock, but tcp service unavailable, syslog: expecting argument %s, syslog: invalid level/facility: %s, syslog: too many levels given: %s, syslog: too many facilities given: %s, syslog: level must be given, udp passed to setlogsock, but udp service unavailable, unix passed to setlogsock, but path not available

    SEE ALSO
    AUTHOR
    BUGS
    SUPPORT

    AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request tracker, Search CPAN

    LICENSE

    Syslog::Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3) calls

    VERSION
    SYNOPSIS
    DESCRIPTION
    EXPORTS
    FUNCTIONS

    openlog($ident, $logopt, $facility), syslog($priority, $message), syslog($priority, $format, @args), Note, setlogmask($mask_priority), setlogsock($sock_type), setlogsock($sock_type, $stream_location) (added in 5.004_02), closelog()

    EXAMPLES
    CONSTANTS
    Facilities
    Levels
    DIAGNOSTICS

    Invalid argument passed to setlogsock, no connection to syslog available, stream passed to setlogsock, but %s is not writable, stream passed to setlogsock, but could not find any device, tcp passed to setlogsock, but tcp service unavailable, syslog: expecting argument %s, syslog: invalid level/facility: %s, syslog: too many levels given: %s, syslog: too many facilities given: %s, syslog: level must be given, udp passed to setlogsock, but udp service unavailable, unix passed to setlogsock, but path not available

    SEE ALSO
    AUTHOR
    BUGS
    SUPPORT

    AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request tracker, Search CPAN

    LICENSE

    Term::ANSIColor - Color screen output using ANSI escape sequences

    SYNOPSIS
    DESCRIPTION
    DIAGNOSTICS

    Bad escape sequence %s, Bareword "%s" not allowed while "strict subs" in use, Invalid attribute name %s, Name "%s" used only once: possible typo, No comma allowed after filehandle, No name for escape sequence %s

    ENVIRONMENT

    ANSI_COLORS_DISABLED

    RESTRICTIONS
    NOTES
    SEE ALSO
    AUTHORS
    COPYRIGHT AND LICENSE

    Term::Cap - Perl termcap interface

    SYNOPSIS
    DESCRIPTION
    METHODS

    Tgetent, OSPEED, TERM

    Tpad, $string, $cnt, $FH

    Tputs, $cap, $cnt, $FH

    Tgoto, $cap, $col, $row, $FH

    Trequire

    EXAMPLES
    COPYRIGHT AND LICENSE
    AUTHOR
    SEE ALSO

    Term::Complete - Perl word completion module

    SYNOPSIS
    DESCRIPTION

    <tab>, ^D, ^U, <del>, <bs>

    DIAGNOSTICS
    BUGS
    AUTHOR

    Term::ReadLine - Perl interface to various readline packages. If no real package is found, substitutes stubs instead of basic functions.

    SYNOPSIS
    DESCRIPTION
    Minimal set of supported functions

    ReadLine, new, readline, addhistory, IN, OUT, MinLine, findConsole, Attribs, Features

    Additional supported functions

    tkRunning, ornaments, newTTY

    EXPORTS
    ENVIRONMENT
    CAVEATS

    Test - provides a simple framework for writing test scripts

    SYNOPSIS
    DESCRIPTION
    QUICK START GUIDE
    Functions

    plan(...), tests => number, todo => [1,5,14], onfail => sub { ... }, onfail => \&some_sub

    _to_value

    ok(...)

    skip(skip_if_true, args...)

    TEST TYPES

    NORMAL TESTS, SKIPPED TESTS, TODO TESTS

    ONFAIL
    BUGS and CAVEATS
    ENVIRONMENT
    NOTE
    SEE ALSO
    AUTHOR

    Test::Builder - Backend for building test libraries

    SYNOPSIS
    DESCRIPTION
    Construction

    new

    create

    reset

    Setting up tests

    exported_to

    plan

    expected_tests

    no_plan

    has_plan

    skip_all

    Running tests

    ok

    is_eq, is_num

    isnt_eq, isnt_num

    like, unlike

    maybe_regex

    cmp_ok

    BAIL_OUT

    skip

    todo_skip

    skip_rest

    Test style

    level

    use_numbers

    no_diag, no_ending, no_header

    Output

    diag

    _print

    _print_diag

    output, failure_output, todo_output

    Test Status and Info

    current_test

    summary

    details

    todo

    caller

    _sanity_check

    _whoa

    _my_exit

    EXIT CODES
    THREADS
    EXAMPLES
    SEE ALSO
    AUTHORS
    COPYRIGHT

    Test::Builder::Module - Base class for test modules

    SYNOPSIS
    DESCRIPTION
    Importing
    Builder

    Test::Builder::Tester - test testsuites that have been built with Test::Builder

    SYNOPSIS
    DESCRIPTION
    Methods

    test_out, test_err

    test_fail

    test_diag

    test_test, title (synonym 'name', 'label'), skip_out, skip_err

    line_num

    color

    BUGS
    AUTHOR
    NOTES
    SEE ALSO

    Test::Builder::Tester::Color - turn on colour in Test::Builder::Tester

    SYNOPSIS
    DESCRIPTION
    AUTHOR
    BUGS
    SEE ALSO

    Test::Harness - Run Perl standard test scripts with statistics

    VERSION
    SYNOPSIS
    DESCRIPTION
    Taint mode
    Configuration variables.

    $Test::Harness::Verbose, $Test::Harness::switches, $Test::Harness::Timer

    Failure

    Failed Test, Stat, Wstat, Total, Fail, Failed, List of Failed

    Functions

    runtests

    _all_ok

    _globdir

    _run_all_tests

    _mk_leader

    _leader_width

    EXPORT
    DIAGNOSTICS

    All tests successful.\nFiles=%d, Tests=%d, %s, FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay., Test returned status %d (wstat %d), Failed 1 test, %.2f%% okay. %s, Failed %d/%d tests, %.2f%% okay. %s, FAILED--Further testing stopped: %s

    ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS

    HARNESS_ACTIVE, HARNESS_VERSION

    ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS

    HARNESS_COLUMNS, HARNESS_COMPILE_TEST, HARNESS_DEBUG, HARNESS_FILELEAK_IN_DIR, HARNESS_IGNORE_EXITCODE, HARNESS_NOTTY, HARNESS_PERL, HARNESS_PERL_SWITCHES, HARNESS_VERBOSE

    EXAMPLE
    SEE ALSO
    TODO
    BUGS
    AUTHORS
    COPYRIGHT

    Test::Harness::Assert - simple assert

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS
    assert()
    AUTHOR
    SEE ALSO

    Test::Harness::Iterator - Internal Test::Harness Iterator

    SYNOPSIS
    DESCRIPTION
    new()
    next()

    Test::Harness::Point - object for tracking a single test point

    SYNOPSIS
    CONSTRUCTION
    new()
    from_test_line( $line )
    ACCESSORS

    ok, number

    Test::Harness::Straps - detailed analysis of test results

    SYNOPSIS
    DESCRIPTION
    CONSTRUCTION
    new()
    $strap->_init
    ANALYSIS
    $strap->analyze( $name, \@output_lines )
    $strap->analyze_fh( $name, $test_filehandle )
    $strap->analyze_file( $test_file )
    $strap->_command_line( $file )
    $strap->_command()
    $strap->_switches( $file )
    $strap->_cleaned_switches( @switches_from_user )
    $strap->_INC2PERL5LIB
    $strap->_filtered_INC()
    $strap->_restore_PERL5LIB()
    Parsing
    _is_diagnostic
    _is_header
    _is_bail_out
    _reset_file_state
    Results
    EXAMPLES
    AUTHOR
    SEE ALSO

    Test::Harness::TAP - Documentation for the TAP format

    SYNOPSIS
    TODO
    THE TAP FORMAT
    HARNESS BEHAVIOR
    TESTS LINES AND THE PLAN
    The plan
    The test line

    ok or not ok, Test number, Description, Directive, ok/not ok (required), Test number (recommended), Description (recommended), Directive (only when necessary)

    DIRECTIVES
    TODO tests
    Skipping tests
    OTHER LINES
    Bail out!
    Diagnostics
    Anything else
    EXAMPLES
    Common with explanation
    Unknown amount and failures
    Giving up
    Skipping a few
    Skipping everything
    Got spare tuits?
    Creative liberties
    AUTHORS
    ACKNOWLEDGEMENTS
    COPYRIGHT

    Test::More - yet another framework for writing test scripts

    SYNOPSIS
    DESCRIPTION
    I love it when a plan comes together
    Test names
    I'm ok, you're not ok.

    ok

    is, isnt

    like

    unlike

    cmp_ok

    can_ok

    isa_ok

    pass, fail

    Module tests

    use_ok

    require_ok

    Complex data structures

    is_deeply

    Diagnostics

    diag

    Conditional tests

    SKIP: BLOCK

    TODO: BLOCK, todo_skip

    When do I use SKIP vs. TODO?

    Test control

    BAIL_OUT

    Discouraged comparison functions

    eq_array

    eq_hash

    eq_set

    Extending and Embedding Test::More

    builder

    EXIT CODES
    CAVEATS and NOTES

    Backwards compatibility, Overloaded objects, Threads, Test::Harness upgrade

    HISTORY
    SEE ALSO
    AUTHORS
    BUGS
    COPYRIGHT

    Test::Simple - Basic utilities for writing tests.

    SYNOPSIS
    DESCRIPTION

    ok

    EXAMPLE
    CAVEATS
    NOTES
    HISTORY
    SEE ALSO

    the Test::More manpage, the Test manpage, the Test::Unit manpage, the Test::Inline manpage, SelfTest, the Test::Harness manpage

    AUTHORS
    COPYRIGHT

    Test::Tutorial - A tutorial about writing really basic tests

    DESCRIPTION
    Nuts and bolts of testing.
    Where to start?
    Names
    Test the manual
    Sometimes the tests are wrong
    Testing lots of values
    Informative names
    Skipping tests
    Todo tests
    Testing with taint mode.
    FOOTNOTES
    AUTHORS
    COPYRIGHT

    Text::Abbrev, abbrev - create an abbreviation table from a list

    SYNOPSIS
    DESCRIPTION
    EXAMPLE

    Text::Balanced - Extract delimited text sequences from strings.

    SYNOPSIS
    DESCRIPTION
    General behaviour in list contexts

    [0], [1], [2]

    General behaviour in scalar and void contexts
    A note about prefixes
    extract_delimited
    extract_bracketed
    extract_variable

    [0], [1], [2]

    extract_tagged

    reject => $listref, ignore => $listref, fail => $str, [0], [1], [2], [3], [4], [5]

    gen_extract_tagged
    extract_quotelike

    [0], [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

    extract_quotelike and "here documents"

    [0], [1], [2], [3], [4], [5], [6], [7..10]

    extract_codeblock
    extract_multiple
    gen_delimited_pat
    DIAGNOSTICS
     C<Did not find a suitable bracket: "%s">,  C<Did not find prefix: /%s/>,
C<Did not find opening bracket after prefix: "%s">,  C<No quotelike
operator found after prefix: "%s">,  C<Unmatched closing bracket: "%c">,
C<Unmatched opening bracket(s): "%s">, C<Unmatched embedded quote (%s)>,
C<Did not find closing delimiter to match '%s'>,  C<Mismatched closing
bracket: expected "%c" but found "%s">,  C<No block delimiter found after
quotelike "%s">, C<Did not find leading dereferencer>, C<Bad identifier
after dereferencer>, C<Did not find expected opening bracket at %s>,
C<Improperly nested codeblock at %s>,  C<Missing second block for quotelike
"%s">, C<No match found for opening bracket>, C<Did not find opening tag:
/%s/>, C<Unable to construct closing tag to match: /%s/>, C<Found invalid
nested tag: %s>, C<Found unbalanced nested tag: %s>, C<Did not find closing
tag>
    AUTHOR
    BUGS AND IRRITATIONS
    COPYRIGHT

    Text::ParseWords - parse text into an array of tokens or array of arrays

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    AUTHORS

    Text::Soundex - Implementation of the Soundex Algorithm as Described by Knuth

    SYNOPSIS
    DESCRIPTION
    EXAMPLES
    LIMITATIONS
    AUTHOR

    Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)

    SYNOPSIS
    DESCRIPTION
    BUGS
    LICENSE

    Text::Wrap - line wrapping to form simple paragraphs

    SYNOPSIS
    DESCRIPTION
    OVERRIDES
    EXAMPLE
    LICENSE

    Thread - manipulate threads in Perl (for old code only)

    CAVEAT
    SYNOPSIS
    DESCRIPTION
    FUNCTIONS

    $thread = Thread->new(\&start_sub), $thread = Thread->new(\&start_sub, LIST), lock VARIABLE, async BLOCK;, Thread->self, cond_wait VARIABLE, cond_signal VARIABLE, cond_broadcast VARIABLE, yield

    METHODS

    join, eval, detach, equal, tid, flags, done

    LIMITATIONS
    SEE ALSO

    Thread::Queue - thread-safe queues

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS AND METHODS

    new, enqueue LIST, dequeue, dequeue_nb, pending

    SEE ALSO

    Thread::Semaphore - thread-safe semaphores

    SYNOPSIS
    DESCRIPTION
    FUNCTIONS AND METHODS

    new, new NUMBER, down, down NUMBER, up, up NUMBER

    Thread::Signal - Start a thread which runs signal handlers reliably (for old code)

    CAVEAT
    SYNOPSIS
    DESCRIPTION
    BUGS

    Thread::Specific - thread-specific keys

    SYNOPSIS
    DESCRIPTION

    Tie::Array - base class for tied arrays

    SYNOPSIS
    DESCRIPTION

    TIEARRAY classname, LIST, STORE this, index, value, FETCH this, index, FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this, key, DELETE this, key, CLEAR this, DESTROY this, PUSH this, LIST, POP this, SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST

    CAVEATS
    AUTHOR

    Tie::File - Access the lines of a disk file via a Perl array

    SYNOPSIS
    DESCRIPTION
    recsep
    autochomp
    mode
    memory
    dw_size
    Option Format
    Public Methods
    flock
    autochomp
    defer, flush, discard, and autodefer
    offset
    Tying to an already-opened filehandle
    Deferred Writing
    Autodeferring
    CONCURRENT ACCESS TO FILES
    CAVEATS
    SUBCLASSING
    WHAT ABOUT DB_File?
    AUTHOR
    LICENSE
    WARRANTY
    THANKS
    TODO

    Tie::Handle, Tie::StdHandle - base class definitions for tied handles

    SYNOPSIS
    DESCRIPTION

    TIEHANDLE classname, LIST, WRITE this, scalar, length, offset, PRINT this, LIST, PRINTF this, format, LIST, READ this, scalar, length, offset, READLINE this, GETC this, CLOSE this, OPEN this, filename, BINMODE this, EOF this, TELL this, SEEK this, offset, whence, DESTROY this

    MORE INFORMATION
    COMPATIBILITY

    Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for tied hashes

    SYNOPSIS
    DESCRIPTION

    TIEHASH classname, LIST, STORE this, key, value, FETCH this, key, FIRSTKEY this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR this, SCALAR this

    Inheriting from Tie::StdHash
    Inheriting from Tie::ExtraHash
    SCALAR, UNTIE and DESTROY
    MORE INFORMATION

    Tie::Memoize - add data to hash when needed

    SYNOPSIS
    DESCRIPTION
    Inheriting from Tie::Memoize
    EXAMPLE
    BUGS
    AUTHOR

    Tie::RefHash - use references as hash keys

    SYNOPSIS
    DESCRIPTION
    EXAMPLE
    AUTHOR
    VERSION
    SEE ALSO

    Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars

    SYNOPSIS
    DESCRIPTION

    TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this

    MORE INFORMATION

    Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing

    SYNOPSIS
    DESCRIPTION
    CAVEATS

    Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers

    SYNOPSIS
    DESCRIPTION

    gettimeofday (), usleep ( $useconds ), nanosleep ( $nanoseconds ), ualarm ( $useconds [, $interval_useconds ] ), tv_interval, time (), sleep ( $floating_seconds ), alarm ( $floating_seconds [, $interval_floating_seconds ] ), setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] ), getitimer ( $which ), clock_gettime ( $which ), clock_getres ( $which ), clock_nanosleep ( $which, $seconds, $flags = 0), clock()

    EXAMPLES
    C API
    DIAGNOSTICS
    negative time not invented yet
    internal error: useconds < 0 (unsigned ... signed ...)
    CAVEATS
    SEE ALSO
    AUTHORS
    COPYRIGHT AND LICENSE

    Time::Local - efficiently compute time from local and GMT time

    SYNOPSIS
    DESCRIPTION
    Ambiguous Local Times (DST)
    Non-Existent Local Times (DST)
    Negative Epoch Values
    IMPLEMENTATION
    BUGS
    SUPPORT
    AUTHOR

    Time::gmtime - by-name interface to Perl's built-in gmtime() function

    SYNOPSIS
    DESCRIPTION
    NOTE
    AUTHOR

    Time::localtime - by-name interface to Perl's built-in localtime() function

    SYNOPSIS
    DESCRIPTION
    NOTE
    AUTHOR

    Time::tm - internal object used by Time::gmtime and Time::localtime

    SYNOPSIS
    DESCRIPTION
    AUTHOR

    UNIVERSAL - base class for ALL classes (blessed references)

    SYNOPSIS
    DESCRIPTION

    $obj->isa( TYPE ), CLASS->isa( TYPE ), isa( VAL, TYPE ), TYPE, $obj, CLASS, VAL, $obj->can( METHOD ), < CLASS-can( METHOD ) >>, can( VAL, METHOD ), VERSION ( [ REQUIRE ] )

    EXPORTS

    Unicode::Collate - Unicode Collation Algorithm

    SYNOPSIS
    DESCRIPTION
    Constructor and Tailoring

    UCA_Version, alternate, backwards, entry, hangul_terminator, ignoreChar, ignoreName, katakana_before_hiragana, level, normalization, overrideCJK, overrideHangul, preprocess, rearrange, table, undefChar, undefName, upper_before_lower, variable

    Methods for Collation

    @sorted = $Collator->sort(@not_sorted), $result =
$Collator-E<gt>cmp($a, $b), $result = $Collator->eq($a, $b),
$result = $Collator->ne($a, $b), $result = $Collator->lt($a,
$b), $result = $Collator->le($a, $b), $result =
$Collator-E<gt>gt($a, $b), $result = $Collator->ge($a, $b),
$sortKey = $Collator->getSortKey($string), $sortKeyForm =
$Collator-E<gt>viewSortKey($string)

    Methods for Searching

    $position = $Collator->index($string, $substring[, $position]),
($position, $length) = $Collator->index($string, $substring[,
$position]), $match_ref = $Collator->match($string, $substring),
($match)   = $Collator->match($string, $substring), @match =
$Collator-E<gt>gmatch($string, $substring), $count =
$Collator-E<gt>subst($string, $substring, $replacement), $count =
$Collator-E<gt>gsubst($string, $substring, $replacement)

    Other Methods

    %old_tailoring = $Collator->change(%new_tailoring), $version = $Collator-E<gt>version(), UCA_Version(), Base_Unicode_Version()

    EXPORT
    INSTALL
    CAVEATS

    Normalization, Conformance Test

    AUTHOR, COPYRIGHT AND LICENSE
    SEE ALSO

    Unicode Collation Algorithm - UTS #10, The Default Unicode Collation Element Table (DUCET), The conformance test for the UCA, Hangul Syllable Type, Unicode Normalization Forms - UAX #15

    Unicode::Normalize - Unicode Normalization Forms

    SYNOPSIS
    DESCRIPTION
    Normalization Forms

    $NFD_string = NFD($string), $NFC_string = NFC($string),
$NFKD_string = NFKD($string), $NFKC_string = NFKC($string),
$FCD_string = FCD($string), $FCC_string = FCC($string),
$normalized_string = normalize($form_name, $string)

    Decomposition and Composition

    $decomposed_string = decompose($string), $decomposed_string =
decompose($string, $useCompatMapping), $reordered_string  =
reorder($string), $composed_string	= compose($string)

    Quick Check

    $result = checkNFD($string), $result = checkNFC($string), $result =
checkNFKD($string), $result = checkNFKC($string), $result =
checkFCD($string), $result = checkFCC($string), $result =
check($form_name, $string)

    Character Data

    $canonical_decomposed = getCanon($codepoint),
$compatibility_decomposed = getCompat($codepoint),
$codepoint_composite = getComposite($codepoint_here, $codepoint_next),
$combining_class = getCombinClass($codepoint), $is_exclusion =
isExclusion($codepoint), $is_singleton = isSingleton($codepoint),
$is_non_starter_decomposition = isNonStDecomp($codepoint),
$may_be_composed_with_prev_char = isComp2nd($codepoint)

    EXPORT
    CAVEATS

    Perl's version vs. Unicode version, Correction of decomposition mapping, Revised definition of canonical composition

    AUTHOR
    SEE ALSO

    http://www.unicode.org/reports/tr15/, http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt, http://www.unicode.org/Public/UNIDATA/NormalizationCorrections.txt, http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/

    Unicode::UCD - Unicode character database

    SYNOPSIS
    DESCRIPTION
    charinfo
    charblock
    charscript
    charblocks
    charscripts
    Blocks versus Scripts
    Matching Scripts and Blocks
    Code Point Arguments
    charinrange
    compexcl
    casefold
    casespec
    namedseq()
    Unicode::UCD::UnicodeVersion
    Implementation Note
    BUGS
    AUTHOR

    User::grent - by-name interface to Perl's built-in getgr*() functions

    SYNOPSIS
    DESCRIPTION
    NOTE
    AUTHOR

    User::pwent - by-name interface to Perl's built-in getpw*() functions

    SYNOPSIS
    DESCRIPTION
    System Specifics
    NOTE
    AUTHOR
    HISTORY

    March 18th, 2000

    XSLoader - Dynamically load C libraries into Perl code

    VERSION
    SYNOPSIS
    DESCRIPTION
    Migration from DynaLoader
    Backward compatible boilerplate
    Order of initialization: early load()
    The most hairy case
    DIAGNOSTICS

    Can't find '%s' symbol in %s, Can't load '%s' for module %s: %s, Undefined symbols present after loading %s: %s, XSLoader::load('Your::Module', $Your::Module::VERSION)

    LIMITATIONS
    BUGS
    SEE ALSO
    AUTHORS
    COPYRIGHT

    AUXILIARY DOCUMENTATION

    Here should be listed all the extra programs' documentation, but they don't all have manual pages yet:

    a2p
    c2ph
    dprofpp
    h2ph
    h2xs
    perlbug
    perldoc
    pl2pm
    pod2html
    pod2man
    s2p
    splain
    xsubpp

    AUTHOR

    Larry Wall <larry@wall.org>, with the help of oodles of other folks.


perltw - ¥¿Åé¤¤¤å Perl «ü«n

    • ÃB¥~ªº¤¤¤å½s½X
    • ¶i¤@¨Bªº¸ê°T
    • ´£¨Ñ Perl ¸ê·½ªººô§}
    • ¾Ç²ß Perl ªººô§}
    • Perl ¨Ï¥ÎªÌ¶°·|
    • Unicode ¬ÛÃöºô§}
    • ¤¤¤å¤Æ¸ê°T
  • SEE ALSO
  • AUTHORS

NAME

perltw - ¥¿Åé¤¤¤å Perl «ü«n

DESCRIPTION

Åwªï¨Ó¨ì Perl ªº¤Ñ¦a!

±q 5.8.0 ª©¶}©l, Perl ¨ã³Æ¤F§¹µ½ªº Unicode (¸U°ê½X) ¤ä´©, ¤]³s±a¤ä´©¤F³\¦h©Ô¤B»y¨t¥H¥~ªº½s½X¤è¦¡; CJK (¤¤¤éÁú) «K¬O¨ä¤¤ªº¤@³¡¥÷. Unicode ¬O°ê»Ú©Êªº¼Ð·Ç, ¸Õ¹Ï²[»\¥@¬É¤W©Ò¦³ªº¦r²Å: ¦è¤è¥@¬É, ªF¤è¥@¬É, ¥H¤Î¨âªÌ¶¡ªº¤@¤Á (§ÆÃ¾¤å, ±Ô§Q¨È¤å, ªü©Ô§B¤å, §Æ§B¨Ó¤å, ¦L«×¤å, ¦L¦a¦w¤å, µ¥µ¥). ¥¦¤]®e¯Ç¤F¦hºØ§@·~¨t²Î»P¥»O (¦p PC ¤Î³Áª÷¶ð).

Perl ¥»¨¥H Unicode ¶i¦æ¾Þ§@. ³oªí¥Ü Perl ¤º³¡ªº¦r¦ê¸ê®Æ¥i¥Î Unicode ªí¥Ü; Perl ªº¨ç¦¡»Pºâ²Å (¨Ò¦p¥¿³Wªí¥Ü¦¡¤ñ¹ï) ¤]¯à¹ï Unicode ¶i¦æ¾Þ§@. ¦b¿é¤J¤Î¿é¥X®É, ¬°¤F³B²z¥H Unicode ¤§«eªº½s½X¤è¦¡Àx¦sªº¸ê®Æ, Perl ´£¨Ñ¤F Encode ³oÓ¼Ò²Õ, ¥i¥HÅý§A»´©ö¦aÅª¨ú¤Î¼g¤JÂÂ¦³ªº½s½X¸ê®Æ.

Encode ©µ¦ù¼Ò²Õ¤ä´©¤U¦C¥¿Åé¤¤¤åªº½s½X¤è¦¡ ('big5' ªí¥Ü 'big5-eten'):

    big5-eten   Big5 ½s½X (§tÊ¤Ñ©µ¦ù¦r§Î)
    big5-hkscs  Big5 + »´ä¥~¦r¶°, 2001 ¦~ª©
    cp950       ¦r½X¶ 950 (Big5 + ·L³n²K¥[ªº¦r²Å)

Á|¨Ò¨Ó»¡, ±N Big5 ½s½XªºÀÉ®×Âà¦¨ Unicode, ¯»ÝÁä¤J¤U¦C«ü¥O:

    perl -Mencoding=big5,STDOUT,utf8 -pe1 < file.big5 > file.utf8

Perl ¤]¤ºªþ¤F "piconv", ¤@¤ä§¹¥þ¥H Perl ¼g¦¨ªº¦r²ÅÂà´«¤u¨ãµ{¦¡, ¥Îªk¦p¤U:

    piconv -f big5 -t utf8 < file.big5 > file.utf8
    piconv -f utf8 -t big5 < file.utf8 > file.big5

¥t¥~, §Q¥Î encoding ¼Ò²Õ, §A¥i¥H»´©ö¼g¥X¥H¦r²Å¬°³æ¦ìªºµ{¦¡½X, ¦p¤U©Ò¥Ü:

    #!/usr/bin/env perl
    # ±Ò°Ê big5 ¦r¦ê¸ÑªR; ¼Ð·Ç¿é¥X¤J¤Î¼Ð·Ç¿ù»~³£³]¬° big5 ½s½X
    use encoding 'big5', STDIN => 'big5', STDOUT => 'big5';
    print length("Àd¾m");            #  2 (Âù¤Þ¸¹ªí¥Ü¦r²Å)
    print length('Àd¾m');            #  4 (³æ¤Þ¸¹ªí¥Ü¦ì¤¸²Õ)
    print index("½Î½Î±Ð»£", "Î½Î±"); # -1 (¤£¥]§t¦¹¤l¦r¦ê)
    print index('½Î½Î±Ð»£', 'Î½Î±'); #  1 (±q²Ä¤GÓ¦ì¤¸²Õ¶}©l)

¦b³Ì«á¤@¦C¨Ò¤l¸Ì, "½Î" ªº²Ä¤GÓ¦ì¤¸²Õ»P "½Î" ªº²Ä¤@Ó¦ì¤¸²Õµ²¦X¦¨ Big5 ½Xªº "Î½"; "½Î" ªº²Ä¤GÓ¦ì¤¸²Õ«h»P "±Ð" ªº²Ä¤@Ó¦ì¤¸²Õµ²¦X¦¨ "Î±". ³o¸Ñ¨M¤F¥H«e Big5 ½X¤ñ¹ï³B²z¤W±`¨£ªº°ÝÃD.

ÃB¥~ªº¤¤¤å½s½X

¦pªG»Ýn§ó¦hªº¤¤¤å½s½X, ¥i¥H±q CPAN (http://www.cpan.org/) ¤U¸ü Encode::HanExtra ¼Ò²Õ. ¥¦¥Ø«e´£¨Ñ¤U¦C½s½X¤è¦¡:

    cccii       1980 ¦~¤å«Ø·|ªº¤¤¤å¸ê°T¥æ´«½X
    euc-tw      Unix ©µ¦ù¦r²Å¶°, ¥]§t CNS11643 ¥± 1-7
    big5plus    ¤¤¤å¼Æ¦ì¤Æ§Þ³N±À¼s°òª÷·|ªº Big5+
    big5ext     ¤¤¤å¼Æ¦ì¤Æ§Þ³N±À¼s°òª÷·|ªº Big5e

¥t¥~, Encode::HanConvert ¼Ò²Õ«h´£¨Ñ¤FÂ²ÁcÂà´«¥Îªº¨âºØ½s½X:

    big5-simp   Big5 ¥¿Åé¤¤¤å»P Unicode Â²Åé¤¤¤å¤¬Âà
    gbk-trad    GBK Â²Åé¤¤¤å»P Unicode ¥¿Åé¤¤¤å¤¬Âà

Y·Q¦b GBK »P Big5 ¤§¶¡¤¬Âà, ½Ð°Ñ¦Ò¸Ó¼Ò²Õ¤ºªþªº b2g.pl »P g2b.pl ¨â¤äµ{¦¡, ©Î¦bµ{¦¡¤º¨Ï¥Î¤U¦C¼gªk:

    use Encode::HanConvert;
    $euc_cn = big5_to_gb($big5); # ±q Big5 Âà¬° GBK
    $big5 = gb_to_big5($euc_cn); # ±q GBK Âà¬° Big5

¶i¤@¨Bªº¸ê°T

½Ð°Ñ¦Ò Perl ¤ºªþªº¤j¶q»¡©ú¤å¥ó (¤£©¯¥þ¬O¥Î^¤å¼gªº), ¨Ó¾Ç²ß§ó¦hÃö©ó Perl ªºª¾ÃÑ, ¥H¤Î Unicode ªº¨Ï¥Î¤è¦¡. ¤£¹L, ¥~³¡ªº¸ê·½¬Û·íÂ×´I:

´£¨Ñ Perl ¸ê·½ªººô§}

http://www.perl.com/

Perl ªºº¶ (¥Ñ¼ÚµÜÂ§¤½¥qºûÅ@)

http://www.cpan.org/

Perl ºî¦X¨åÂÃºô (Comprehensive Perl Archive Network)

http://lists.perl.org/

Perl ¶l»¼½×¾Â¤@Äý

¾Ç²ß Perl ªººô§}

http://www.oreilly.com.tw/chinese/perl/index.html

¥¿Åé¤¤¤åª©ªº¼ÚµÜÂ§ Perl ®ÑÂÇ

http://groups.google.com/groups

»OÆW Perl ³s½u°Q½×°Ï (¤]´N¬O¦U¤j BBS ªº Perl ³s½uª©)

Perl ¨Ï¥ÎªÌ¶°·|

http://www.pm.org/groups/asia.shtml#Taiwan

»OÆW Perl ±À¼s²Õ¤@Äý

http://irc.elixus.org/

ÃÀ¥ß¨ó½u¤W²á¤Ñ«Ç

Unicode ¬ÛÃöºô§}

http://www.unicode.org/

Unicode ¾Ç³N¾Ç·| (Unicode ¼Ð·Çªº¨î©wªÌ)

http://www.cl.cam.ac.uk/%7Emgk25/unicode.html

Unix/Linux ¤Wªº UTF-8 ¤Î Unicode µª«È°Ý

¤¤¤å¤Æ¸ê°T

¬°¤°»ò¥s "¥¿Åé¤¤¤å" ¤£¥s "ÁcÅé¤¤¤å"?

http://www.csie.ntu.edu.tw/~b7506051/mozilla/faq.html#faqglossary

¤¤¤å¤Æ³nÅéÁp·ù

http://www.cpatch.org/

Linux ³nÅé¤¤¤å¤Æp¹º

http://www.linux.org.tw/CLDP/

SEE ALSO

the Encode manpage, the Encode::TW manpage, the encoding manpage, the perluniintro manpage, the perlunicode manpage

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi>

Autrijus Tang (ð©vº~) <autrijus@autrijus.org>


Internet Explorer could not load the PerlScript engine. This is most likely due to the value of the "Initialize and script ActiveX controls not marked as safe" security setting of the "Local intranet" zone. PerlScript inside IE will only run on Windows XP SP2 and later if this setting is set to Enable. Setting it to Prompt doesn't seem to work.


ActivePerl Components

PerlEx::DBI - Initiate a Persistent Database Connection

  • NAME
  • SYNOPSIS
  • DESCRIPTION
  • CONFIGURATION
  • PREREQUISITES
  • SEE ALSO
  • AUTHORS
  • COPYRIGHT

NAME

PerlEx::DBI - Initiate a persistent database connection

SYNOPSIS

    # add this switch to CommandLineOptions setting in Interpreter Class
    -mPerlEx::DBI
    # or add next line to StartupCode setting in the Interpreter Class
    use PerlEx::DBI ();  # this comes before all other modules using DBI

Note to Apache users: PerlEx::DBI is based on Apache::DBI. Except for the configuration noted above, PerlEx::DBI is functionally identical to Apache::DBI.

You do NOT need to change anything in your scripts. The usage of this module is absolutely transparent!

DESCRIPTION

This module transparently initiates persistent database connections.

The database access must be via the DBI module. For supported DBI drivers see:

    http://www.symbolstone.org/technology/perl/DBI/

When the DBI module is loaded by your script (do not confuse this with the loading of the PerlEx::DBI module itself) DBI looks at the environment variable GATEWAY_INTERFACE and checks to see if it starts with 'CGI-Perl', and whether an Apache::DBI compatible module (in this case PerlEx::DBI) has been loaded. If that is the case, every connect request will be forwarded to the Apache::DBI compatible module.

PerlEx::DBI then looks at whether a database handle from a previous connect request is already cached and whether the cached handle is still valid, using the ping method. If these two conditions are fulfilled it just returns the cached database handle. The parameters defining the connection have to be exactly the same for a cached handle to be selected, including the connect attributes. If there is no appropriate database handle or if the ping method fails, a new connection is established and the handle is cached for later re-use. There is no need to remove any disconnect() calls from your code. They won't do anything because the PerlEx::DBI module overloads the disconnect method.

The PerlEx::DBI module still has a potential limitation: it keeps database connections persistent on a per-interpreter basis. This means that if a user accesses a database several times, the http requests may end up being handled by different PerlEx interpreters, even though PerlEx tries to use as few interpreters as possible. In this case, every interpreter needs to do its own connect. It would be nice if all interpreters could share the database handles, but currently this is not possible because of strict isolation of the data space of interpreters, for scalability and security reasons. Also, it is currently not possible to create a database handle upon PerlEx startup and later inheriting this handle in every subsequent interpreter.

With these limitations in mind, there may be some scenarios where the usage of PerlEx::DBI may not be worthwhile. Consider a heavily loaded web site where every user connects to the database with a unique userid. This could cause many database handles to be initialized and kept persistent, hogging database resources.

If you find that PerlEx::DBI results in consumption of excess database resources, you should investigate enabling the native connection pooling features of your database instead of enabling PerlEx::DBI for your scripts.

Another potential problem are timeouts: some databases disconnect the client after a certain period of inactivity. PerlEx::DBI normally tries to validate the database handle using the ping-method of the DBI-module. This method returns true as default. If the database handle is not valid and the driver has no implementation for the ping method, you will get an error when accessing the database. To work around this, you can try to replace the ping method by any database command, which is cheap and safe, or you may deactivate the usage of the ping method (see CONFIGURATION below).

Here is a generalized ping method, which can be added to the driver module:

{ package DBD::xxx::db; # ====== DATABASE ====== use strict;

    sub ping {
        my($dbh) = @_;
        my $ret = 0;
        eval {
            local $SIG{__DIE__}  = sub { return (0); };
            local $SIG{__WARN__} = sub { return (0); };
            # adapt the select statement to your database:
            $ret = $dbh->do('select 1');
        };
        return ($@) ? 0 : $ret;
    }
}

Transactions: a standard DBI script will automatically perform a rollback whenever the script exits. In the case of persistent database connections, the database handle will not be destroyed and hence no automatic rollback occurs. While at first glance it might seem practical to handle a transaction over multiple requests, this will not really work because different requests may be handled by different interpreters. One interpreter will not know the state of a specific transaction which has been started by another interpreter.

In general it is good practice to perform an explicit commit or rollback at the end of every script. In order to avoid inconsistencies in the database in case AutoCommit is off and the script finishes without an explicit rollback, the PerlEx::DBI module uses a cleanup handler to issue a rollback at the end of every request. Note that this cleanup handler will only be used if the initial data_source sets AutoCommit = 0. It will not be used if AutoCommit is turned off after the connect has been done.

CONFIGURATION

PerlEx::DBI should be loaded upon startup of a PerlEx Interpreter Class. This can be done either by adding the following switch to the CommandLineOptions registry setting:

    -mPerlEx::DBI

or by adding the following line to the StartupCode setting such that it executes before anything else that loads the DBI module:

    use PerlEx::DBI ();

Either of the above can be set within an Interpreter Class to restrict the setting to a single script or a set of scripts under a given location. See the PerlEx documentation for more information on these registry settings.

Note that it is important to load PerlEx::DBI before any other modules using DBI!

There is one configuration which is server-specific and which can be done within the script after $data_source has been initialized:

    PerlEx::DBI->setPingTimeOut($data_source, $timeout);

This configures the usage of the ping method, to validate a connection. Setting the timeout to 0 will always validate the database connection using the ping method (default). Setting the timeout < 0 will de-activate the validation of the database handle. This can be used for drivers which do not implement the ping-method. Setting the timeout > 0 will ping the database only if the last access was more than timeout seconds before.

To enable logging, set the Trace value for your Interpreter Class to 1 or higher. Setting the variable to 1 simply reports every new connect. Setting Trace to 2 enables full debug output.

PREREQUISITES

Note that this module needs PerlEx 2.2 or higher and DBI 1.14 or higher.

SEE ALSO

DBI

AUTHORS

  • PerlEx::DBI is a modified version of Apache::DBI. PerlEx::DBI by Shane Caraveo <ShaneC@ActiveState.com>

  • Apache::DBI by Edmund Mergl <E.Mergl@bawue.de>

  • DBI by Tim Bunce <dbi-users@isc.org>

COPYRIGHT

The PerlEx::DBI module is based on Apache::DBI and is free software; you can redistribute it and/or modify it under the same terms as Perl itself.